Copyright: Windows NT 4.0


accept

The Windows Sockets accept function accepts a connection on a socket.

SOCKET accept (

SOCKET s,
struct sockaddr FAR* addr,
int FAR* addrlen
);
Parameters

s

[in] A descriptor identifying a socket which is listening for connections after a listen.

addr

[out] An optional pointer to a buffer which receives the address of the connecting entity, as known to the communications layer. The exact format of the addr argument is determined by the address family established when the socket was created.

addrlen

[out] An optional pointer to an integer which contains the length of the address addr.

Remarks

This routine extracts the first connection on the queue of pending connections on s, creates a new socket and returns a handle to the new socket. The newly created socket has the same properties as s including asynchronous events registered with WSAAsyncSelect or with WSAEventSelect, but not including the listening socket’s group ID, if any. If no pending connections are present on the queue, and the socket is not marked as nonblocking, accept blocks the caller until a connection is present. If the socket is marked nonblocking and no pending connections are present on the queue, accept returns an error as described below. The accepted socket cannot be used to accept more connections. The original socket remains open.

The argument addr is a result parameter that is filled in with the address of the connecting entity, as known to the communications layer. The exact format of the addr parameter is determined by the address family in which the communication is occurring. The addrlen is a value-result parameter; it should initially contain the amount of space pointed to by addr; on return it will contain the actual length (in bytes) of the address returned. This call is used with connection-oriented socket types such as SOCK_STREAM. If addr and/or addrlen are equal to NULL, then no information about the remote address of the accepted socket is returned.

Return Values

If no error occurs, accept returns a value of type SOCKET which is a descriptor for the accepted socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code can be retrieved by calling WSAGetLastError.

The integer referred to by addrlen initially contains the amount of space pointed to by addr. On return it will contain the actual length in bytes of the address returned.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this FUNCTION.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	The addrlen argument is too small or addr is not a valid part of the user address space.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINVAL	listen was not invoked prior to accept.
WSAEMFILE	The queue is nonempty upon entry to accept and there are no descriptors available.
WSAENOBUFS	No buffer space is available.
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	The referenced socket is not a type that supports connection-oriented service.
WSAEWOULDBLOCK	The socket is marked as nonblocking and no connections are present to be accepted.
See Also

bind, connect, listen, select, socket, WSAAsyncSelect, WSAAccept


AcceptEx

Notice  This function is a Microsoft-specific extension to the Windows Sockets specification. For more information, see Microsoft Extensions and Windows Sockets 2.

The Windows Sockets AcceptEx function accepts a new connection, returns the local and remote address, and receives the first block of data sent by the client application.

BOOL AcceptEx (

SOCKET sListenSocket,
SOCKET sAcceptSocket,
PVOID lpOutputBuffer,
DWORD dwReceiveDataLength,
DWORD dwLocalAddressLength,
DWORD dwRemoteAddressLength,
LPDWORD lpdwBytesReceived,
LPOVERLAPPED lpOverlapped
);
Parameters

sListenSocket

[in] A descriptor identifying a socket that has already been called with the listen function. A server application waits for attempts to connect on this socket.

sAcceptSocket

[in] A descriptor identifying a socket on which to accept an incoming connection. This socket must not be bound or connected.

lpOutputBuffer

[in] A pointer to a buffer that receives the first block of data sent on a new connection, the local address of the server, and the remote address of the client. The receive data is written to the first part of the buffer starting at offset zero, while the addresses are written to the latter part of the buffer. This parameter must be specified.

dwReceiveDataLength

[in] The number of bytes in the buffer that will be used for receiving data. If this parameter is specified as zero, then no receive operation is performed in conjunction with accepting the connection. Instead, the AcceptEx function completes as soon as a connection arrives without waiting for any data.

dwLocalAddressLength

[in] The number of bytes reserved for the local address information. This must be at least 16 bytes more than the maximum address length for the transport protocol in use.

dwRemoteAddressLength

[in] The number of bytes reserved for the remote address information. This must be at least 16 bytes more than the maximum address length for the transport protocol in use.

lpdwBytesReceived

[out] A pointer to a DWORD that receives the count of bytes received. This is set only if the operation completes synchronously. If it returns ERROR_IO_PENDING and is completed later, then this DWORD is never set and you must obtain the number of bytes read from the completion notification mechanism.

lpOverlapped

[in] An OVERLAPPED structure that is used to process the request. This parameter must be specified; it cannot be NULL.

Return Values

If no error occurs, the AcceptEx function was successfully completed and a value of TRUE is returned. If the function was unsuccesful, the AcceptEx function returns FALSE. The GetLastError function can then be called to return extended error information. If GetLastError returns ERROR_IO_PENDING, then the operation was successfully initiated and is still in progress.

Remarks

The AcceptEx function combines several socket functions into a single API/kernel transition. The AcceptEx function, when successful, performs three tasks: a new connection is accepted, both the local and remote addresses for the connection are returned, and the first block of data sent by the remote is received. A program will make a connection to a socket more quickly using the AcceptEx function instead of the Accept function.

A single output buffer receives the data, the local socket address (the server), and the remote socket address (the client). Using a single buffer improves performance, but the GetAcceptExSockaddrs function must be called to parse the buffer into its three distinct parts.

Because the addresses are written in an internal format, the buffer size for the local and remote address must be 16 bytes more than the size of the SOCKADDR structure for the transport protocol in use. For example, the size of a SOCKADDR_IN — the address structure for TCP/IP — is 16 bytes, so specify a buffer size of at least 32 bytes for the local and remote addresses.

The AcceptEx function uses overlapped I/O, unlike the Windows Sockets 1.1 accept function. If your application uses the AcceptEx function, it can service a large number of clients with a relatively small number of threads.

As with all overlapped Win32 functions, either Win32 events or completion ports can be used as a completion notification mechanism.

Another key difference between the AcceptEx function and the Windows Sockets 1.1 accept function is that the AcceptEx function requires the caller to already have two sockets: one that specifies the socket on which to listen and one that specifies the socket on which to accept the connection. The sAcceptSocket parameter must be an open socket that is neither bound nor connected.

The lpNumberOfBytesTransferred parameter of the GetQueuedCompletionStatus function or the GetOverlappedResult function indicates the number of bytes received in the request.

When this operation is successfully completed, sAcceptHandle can be passed only to the following functions:

ReadFile

WriteFile

send

recv

TransmitFile

closesocket

Note  If you have called the TransmitFile function with both the TF_DISCONNECT and TF_REUSE_SOCKET flags, the specified socket has been returned to a state in which it is neither bound nor connected. You can then pass the handle of the socket to the AcceptEx function in the sAcceptSocket parameter.

In order to use sAcceptHandle with other Window Sockets 1.1 functions, call the setsockopt function with the SO_UPDATE_ACCEPT_CONTEXT option. This option initializes the socket so that other Windows Sockets routines to access the socket correctly.

When the AcceptEx function returns, sAcceptSocket is in the default state for a connected socket. The socket associated with the sAcceptSocket parameter does not inherit the properties of the socket associated with sListenSocket parameter until SO_UPDATE_ACCEPT_CONTEXT is set on the socket. Use the setsockopt function to set the SO_UPDATE_ACCEPT_CONTEXT option, specifying sAcceptSocket as the socket handle and sListenSocket as the option value.

For example:

err = setsockopt( sAcceptSocket,

    SOL_SOCKET,

    SO_UPDATE_ACCEPT_CONTEXT,

    (char *)&sListenSocket,

    sizeof(sListenSocket) );

You can use the getsockopt function with the SO_CONNECT_TIME option to check whether a connection has been accepted. If it has been accepted, you can determine how long the connection has been established. The return value is the number of seconds that the socket has been connected. If the socket is not connected, the getsockopt returns 0xFFFFFFFF. Checking a connection like this is necessary in order to check for connections that have been established for awhile, but no data has been received. You can then kill those connections.

For example:

INT seconds;

INT bytes = sizeof(seconds);

err = getsockopt( sAcceptSocket, SOL_SOCKET, SO_CONNECT_TIME,

                      (char *)&seconds, (PINT)&bytes );

if ( err != NO_ERROR ) {

    printf( "getsockopt(SO_CONNECT_TIME) failed: %ld\n", WSAGetLastError( ) );

    exit(1);

}


bind

The Windows Sockets bind function associates a local address with a socket.

int bind (

SOCKET s,
const struct sockaddr FAR*  name,
int namelen
);
Parameters

s

[in] A descriptor identifying an unbound socket.

name

[in] The address to assign to the socket. The sockaddr structure is defined as follows:

struct sockaddr {

u_short    sa_family;

char       sa_data[14];

};

Except for the sa_family field, sockaddr contents are expressed in network byte order.

namelen

[in] The length of the name.

Remarks

This routine is used on an unconnected connectionless or connection-oriented socket, before subsequent connects or listens. When a socket is created with socket, it exists in a name space (address family), but it has no name assigned. bind establishes the local association of the socket by assigning a local name to an unnamed socket.

As an example, in the Internet address family, a name consists of three parts: the address family, a host address, and a port number which identifies the application. In Windows Sockets 2, the name parameter is not strictly interpreted as a pointer to a "sockaddr" structure. It is cast this way for Windows Sockets compatibility. Service Providers are free to regard it as a pointer to a block of memory of size namelen. The first two bytes in this block (corresponding to "sa_family" in the "sockaddr" declaration) must contain the address family that was used to create the socket. Otherwise, an error WSAEFAULT will occur.

If an application does not care what local address is assigned to it, it can specify the manifest constant value ADDR_ANY for the sa_data field of the name parameter. This allows the underlying service provider to use any appropriate network address, potentially simplifying application programming in the presence of multihomed hosts (that is, hosts that have more than one network interface and address). For TCP/IP, if the port is specified as zero, the service provider will assign a unique port to the application with a value between 1024 and 5000. The application can use getsockname after bind to learn the address and the port that has been assigned to it, but note that if the Internet address is equal to INADDR_ANY, getsockname will not necessarily be able to supply the address until the socket is connected, since several addresses can be valid if the host is multihomed.

Return Values

If no error occurs, bind returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEADDRINUSE	The specified address is already in use. (See the SO_REUSEADDR socket option under setsockopt.)
WSAEFAULT	The name or the namelen argument is not a valid part of the user address space, the namelen argument is too small, the name argument contains incorrect address format for the associated address family, or the first two bytes of the memory block specified by name does not match the address family associated with the socket descriptor s.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINVAL	The socket is already bound to an address.
WSAENOBUFS	Not enough buffers available, too many connections.
WSAENOTSOCK	The descriptor is not a socket.
See Also

connect, getsockname, listen, setsockopt, socket, WSACancelBlockingCall


closesocket

The Windows Sockets closesocket function closes a socket.

int closesocket (

SOCKET s
);
Parameters

s

[in] A descriptor identifying a socket.

Remarks

This function closes a socket. More precisely, it releases the socket descriptor s, so that further references to s will fail with the error WSAENOTSOCK. If this is the last reference to an underlying socket, the associated naming information and queued data are discarded. Any pending blocking, asynchronous calls issued by any thread in this process are canceled without posting any notification messages, or signaling any event objects. Any pending overlapped send and receive operations (WSASend/WSASendTo/WSARecv/WSARecvFrom with an overlapped socket) issued by any thread in this process are also canceled without setting the event object or invoking the completion routine, if specified. In this case, the pending overlapped operations fail with the error status WSA_OPERATION_ABORTED. An application should always have a matching call to closesocket for each successful call to socket to return socket resources to the system.

The semantics of closesocket are affected by the socket options SO_LINGER and SO_DONTLINGER as follows (Note: by default SO_DONTLINGER is enabled. That is, SO_LINGER is disabled):

Option	Interval	Type of close	Wait for close?
SO_DONTLINGER	Don't care	Graceful	No
SO_LINGER	Zero	Hard	No
SO_LINGER	Nonzero	Graceful	Yes
If SO_LINGER is set (that is, the l_onoff field of the linger structure is nonzero; see Multipoint and Multicast Semantics) with a zero time-out interval (l_linger is zero), closesocket is not blocked even if queued data has not yet been sent or acknowledged. This is called a "hard" or "abortive" close, because the socket's virtual circuit is reset immediately, and any unsent data is lost. Any recv call on the remote side of the circuit will fail with WSAECONNRESET.

If SO_LINGER is set with a nonzero time-out interval on a blocking socket, the closesocket call blocks on a blocking socket until the remaining data has been sent or until the time-out expires. This is called a graceful disconnect. If the time-out expires before all data has been sent, the Windows Sockets implementation terminates the connection before closesocket returns.

Enabling SO_LINGER with a nonzero time-out interval on a nonblocking socket is not recommended. In this case, the call to closesocket will fail with an error of WSAEWOULDBLOCK if the close operation cannot be completed immediately. If closesocket fails with WSAEWOULDBLOCK the socket handle is still valid, and a disconnect is not initiated. The application must call closesocket again to close the socket, although closesocket can continue to fail unless the application disables SO_DONTLINGER, enables SO_LINGER with a zero time-out, or calls shutdown to initiate closure.

If SO_DONTLINGER is set on a stream socket (that is, the l_onoff field of the linger structure is zero; see Multipoint and Multicast Semantics) the closesocket call will return immediately. However, any data queued for transmission will be sent if possible before the underlying socket is closed. This is also called a graceful disconnect. Note that in this case, the Windows Sockets provider cannot release the socket and other resources for an arbitrary period, which can affect applications which expect to use all available sockets. This is the default behavior.

Note  To assure that all data is sent and received on a connection, an application should call shutdown before calling closesocket (see Graceful shutdown, linger options and socket closure for more information). Also note, FD_CLOSE will not be posted after closesocket is called.

Here is a summary of closesocket behavior:

•	if SO_DONTLINGER enabled (the default setting) it always returns immediately − connection is gracefully closed "in the background"

•	if SO_LINGER enabled with a zero time-out: it always returns immediately - connection is reset/terminated

•	if SO_LINGER enabled with nonzero time-out:

− with blocking socket it blocks until all data sent or time-out expires

− with nonblocking socket it returns immediately indicating failure

For additional information please see Graceful shutdown, linger options and socket closure for more information.

Return Values

If no error occurs, closesocket returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAENOTSOCK	The descriptor is not a socket.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEWOULDBLOCK	The socket is marked as nonblocking and SO_LINGER is set to a nonzero time-out value.
See Also

accept, ioctlsocket, setsockopt, socket, WSAAsyncSelect, WSADuplicateSocket


connect

The Windows Sockets connect function establishes a connection to a peer.

int connect (

SOCKET s,
const struct sockaddr FAR*  name,
int namelen
);
Parameters

s

[in] A descriptor identifying an unconnected socket.

name

[in] The name of the peer to which the socket is to be connected.

namelen

[in] The length of the name.

Remarks

This function is used to create a connection to the specified destination. If the socket, s, is unbound, unique values are assigned to the local association by the system, and the socket is marked as bound.

For connection-oriented sockets (for example, type SOCK_STREAM), an active connection is initiated to the foreign host using name (an address in the name space of the socket; for a detailed description, please see bind). When the socket call completes successfully, the socket is ready to send/receive data. If the address field of the name structure is all zeroes, connect will return the error WSAEADDRNOTAVAIL. Any attempt to re-connect an active connection will fail with the error code WSAEISCONN.

For a connectionless socket (for example, type SOCK_DGRAM), the operation performed by connect is merely to establish a default destination address which will be used on subsequent send/WSASend and recv/WSARecv calls. Any datagrams received from an address other than the destination address specified will be discarded. If the address field of the name structure is all zeroes, the socket will be "dis-connected.” Then, the default remote address will be indeterminate, so send/WSASend and recv/WSARecv calls will return the error code WSAENOTCONN. However, sendto/WSASendTo and recvfrom/WSARecvFrom can still be used. The default destination can be changed by simply calling connect again, even if the socket is already "connected". Any datagrams queued for receipt are discarded if name is different from the previous connect.

For connectionless sockets, name can indicate any valid address, including a broadcast address. However, to connect to a broadcast address, a socket must have setsockopt SO_BROADCAST enabled. Otherwise, connect will fail with the error code WSAEACCES.

Comments

When connected sockets break (that is, become closed for whatever reason), they should be discarded and recreated. It is safest to assume that when things go awry for any reason on a connected socket, the application must discard and recreate the needed sockets in order to return to a stable point.

Return Values

If no error occurs, connect returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

On a blocking socket, the return value indicates success or failure of the connection attempt.

With a nonblocking socket, the connection attempt cannot be completed immediately. In this case, connect will return SOCKET_ERROR, and WSAGetLastError will return WSAEWOULDBLOCK. In this case, the application can:

1.	Use select to determine the completion of the connection request by checking if the socket is writeable, or

2.	If your application is using WSAAsyncSelect to indicate interest in connection events, then your application will receive an FD_CONNECT notification when the connect operation is complete, or

3.	If your application is using WSAEventSelect to indicate interest in connection events, then the associated event object will be signaled when the connect operation is complete.

For a nonblocking socket, until the connection attempt completes all subsequent calls to connect on the same socket will fail with the error code WSAEALREADY.

If the return error code indicates the connection attempt failed (that is, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) the application can call connect again for the same socket.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEADDRINUSE	The specified address is already in use.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEALREADY	A nonblocking connect call is in progress on the specified socket. Note  In order to preserve backward compatibility, this error is reported as WSAEINVAL to Windows Sockets 1.1 applications that link to either WINSOCK.DLL or WSOCK32.DLL.
WSAEADDRNOTAVAIL	The specified address is not available from the local machine.
WSAEAFNOSUPPORT	Addresses in the specified family cannot be used with this socket.
WSAECONNREFUSED	The attempt to connect was forcefully rejected.
WSAEFAULT	The name or the namelen argument is not a valid part of the user address space, the namelen argument is too small, or the name argument contains incorrect address format for the associated address family.
WSAEINVAL	The parameter s is a listening socket, or the destination address specified is not consistent with that of the constrained group the socket belongs to.
WSAEISCONN	The socket is already connected (connection-oriented sockets only).
WSAENETUNREACH	The network cannot be reached from this host at this time.
WSAENOBUFS	No buffer space is available. The socket cannot be connected.
WSAENOTSOCK	The descriptor is not a socket.
WSAETIMEDOUT	Attempt to connect timed out without establishing a connection.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the connection cannot be completed immediately. It is possible to select the socket while it is connecting by selecting it for writing.
WSAEACCES	Attempt to connect datagram socket to broadcast address failed because setsockopt SO_BROADCAST is not enabled.
See Also

accept, bind, getsockname, select, socket, WSAAsyncSelect, WSAConnect


EnumProtocols

Important  The EnumProtocols function is a Microsoft-specific extension to the Windows Sockets 1.1 specification. This function is obsolete. For the convenience of Windows Sockets 1.1 developers, the reference material is below.

In Windows Sockets 2, this functionality is realized with the function WSAEnumProtocols.

The EnumProtocols function obtains information about a specified set of

network protocols that are active on a local host.

INT EnumProtocols(

LPINT lpiProtocols,	// pointer to array of protocol identifiers
LPVOID lpProtocolBuffer,	// pointer to buffer to receive protocol information
LPDWORD lpdwBufferLength	// pointer to variable that specifies the size of the receiving buffer
);
Parameters

lpiProtocols

Pointer to a null-terminated array of protocol identifiers. The EnumProtocols function obtains information about the protocols specified by this array.

If lpiProtocols is NULL, the function obtains information about all available protocols.

The following protocol identifier values are defined:

Value	Protocol
IPPROTO_TCP	TCP/IP, a connection/stream-oriented protocol
IPPROTO_UDP	User Datagram Protocol (UDP/IP), a connectionless datagram protocol
ISOPROTO_TP4	ISO connection-oriented transport protocol
NSPROTO_IPX	IPX
NSPROTO_SPX	SPX
NSPROTO_SPXII	SPX II
lpProtocolBuffer

Pointer to a buffer that the function fills with an array of PROTOCOL_INFO data structures.

lpdwBufferLength

Pointer to a variable that, on input, specifies the size, in bytes, of the buffer pointed to by lpProtocolBuffer.

On output, the function sets this variable to the minimum buffer size needed to retrieve all of the requested information. For the function to succeed, the buffer must be at least this size.

Return Values

If the function succeeds, the return value is the number of PROTOCOL_INFO data structures written to the buffer pointed to by lpProtocolBuffer.

If the function fails, the return value is SOCKET_ERROR ( − 1). To get extended error information, call GetLastError. GetLastError may return the following extended error code:

Value	Meaning
ERROR_INSUFFICIENT_BUFFER	The buffer pointed to by lpProtocolBuffer was too small to receive all of the relevant PROTOCOL_INFO structures. Call the function with a buffer at least as large as the value returned in *lpdwBufferLength.
Remarks

In the following sample code, the EnumProtocols function obtains information about all protocols that are available on a system. The code then examines each of the protocols in greater detail.

SOCKET

OpenConnection (

    PTSTR ServiceName,

    PGUID ServiceType,

    BOOL Reliable,

    BOOL MessageOriented,

    BOOL StreamOriented,

    BOOL Connectionless,

    PINT ProtocolUsed

    )

{

    // local variables

    INT protocols[MAX_PROTOCOLS+1];

    BYTE buffer[2048];

    DWORD bytesRequired;

    INT err;

    PPROTOCOL_INFO protocolInfo;

    PCSADDR_INFO csaddrInfo;

    INT protocolCount;

    INT addressCount;

    INT i;

    DWORD protocolIndex;

    SOCKET s;

    // First look up the protocols installed on this machine.

    //

    bytesRequired = sizeof(buffer);

    err = EnumProtocols( NULL, buffer, &bytesRequired );

    if ( err <= 0 )

        return INVALID_SOCKET;

    // Walk through the available protocols and pick out the ones which

    // support the desired characteristics.

    //

    protocolCount = err;

    protocolInfo = (PPROTOCOL_INFO)buffer;

    for ( i = 0, protocolIndex = 0;

        i < protocolCount && protocolIndex < MAX_PROTOCOLS;

        i++, protocolInfo++ ) {

        // If connection-oriented support is requested, then check if

        // supported by this protocol.  We assume here that connection-

        // oriented support implies fully reliable service.

        //

        if ( Reliable ) {

            // Check to see if the protocol is reliable.  It must

            // guarantee both delivery of all data and the order in

            // which the data arrives.

            //

            if ( (protocolInfo->dwServiceFlags &

                    XP_GUARANTEED_DELIVERY) == 0

                ||

                    (protocolInfo->dwServiceFlags &

                    XP_GUARANTEED_ORDER) == 0 ) {

                continue;

                }

            // Check to see that the protocol matches the stream/message

            // characteristics requested.

            //

            if ( StreamOriented &&

                (protocolInfo->dwServiceFlags & XP_MESSAGE_ORIENTED)

                    != 0 &&

                (protocolInfo->dwServiceFlags & XP_PSEUDO_STREAM)

                     == 0 ) {

                continue;

                }

            if ( MessageOriented &&

                    (protocolInfo->dwServiceFlags & XP_MESSAGE_ORIENTED)

                              == 0 ) {

                continue;

                }

            }

        else if ( Connectionless ) {

            // Make sure that this is a connectionless protocol.

            //

            if ( (protocolInfo->dwServiceFlags & XP_CONNECTIONLESS)

                     != 0 )

                continue;

            }

        // This protocol fits all the criteria.  Add it to the list of

        // protocols in which we're interested.

        //

        protocols[protocolIndex++] = protocolInfo->iProtocol;

        }

See Also

GetAddressByName, PROTOCOL_INFO


GetAcceptExSockaddrs

Notice  This function is a Microsoft-specific extension to the Windows Sockets specification. For more information, see Microsoft Extensions and Windows Sockets 2.

The Windows Sockets GetAcceptExSockaddrs function parses the data obtained from a call to the AcceptEx function and passes the local and remote addresses to a SOCKADDR structure.

VOID GetAcceptExSockaddrs (

PVOID lpOutputBuffer,
DWORD dwReceiveDataLength,
DWORD dwLocalAddressLength,
DWORD dwRemoteAddressLength,
LPSOCKADDR *LocalSockaddr,
LPINT LocalSockaddrLength,
LPSOCKADDR *RemoteSockaddr,
LPINT RemoteSockaddrLength
);
Parameters

lpOutputBuffer

[in] A pointer to a buffer that receives the first block of data sent on a connection resulting from an AcceptEx call. It must be the same lpOutputBuffer parameter that was passed to the AcceptEx function.

dwReceiveDataLength

[in] The number of bytes in the buffer that will be used for receiving the first data. This must be equal to the dwReceiveDataLength parameter that was passed to the AcceptEx function.

dwLocalAddressLength

[in] The number of bytes reserved for the local address information. This must be equal to the dwLocalAddressLength parameter that was passed to the AcceptEx function.

dwRemoteAddressLength

[in] The number of bytes reserved for the remote address information. This must be equal to the dwRemoteAddressLength parameter that was passed to the AcceptEx function.

LocalSockaddr

[out] A pointer to the SOCKADDR structure that receives the local address of the connection (the same information that would be returned by the Windows Sockets getsockname function). This parameter must be specified.

LocalSockaddrLength

[out] The size of the local address. This parameter must be specified.

RemoteSockaddr

[out] A pointer to the SOCKADDR structure that receives the remote address of the connection (the same information that would be returned by the Windows Sockets getpeername function). This parameter must be specified.

RemoteSockaddrLength

[out] The size of the local address. This parameter must be specified.

Return Values

This function does not return a value.

Remarks

The GetAcceptExSockaddrs function is used exclusively with the AcceptEx function to parse the first data that the socket receives into local and remote addresses. You are required to use this function because the AcceptEx function writes address information in an internal (TDI) format. The GetAcceptExSockaddrs routine is required to locate the SOCKADDR structures in the buffer.


GetAddressByName

Important  The GetAddressByName function is a Microsoft-specific extension to the Windows Sockets 1.1 specification. This function is obsolete. For the convenience of Windows Sockets 1.1 developers, the reference material is below.

In Windows Sockets 2, this functionality is realized with the functions detailed in Protocol-Independent Name Resolution.

The GetAddressByName function queries a name space, or a set of default name spaces, in order to obtain network address information for a specified network service. This process is known as service name resolution. A network service can also use the function to obtain local address information that it can use with the bind function.

INT GetAddressByName(

DWORD dwNameSpace,	// name space to query for service address information
LPGUID lpServiceType,	// the type of the service
LPTSTR lpServiceName,	// the name of the service
LPINT lpiProtocols,	// points to array of protocol identifiers
DWORD dwResolution,	// set of bit flags that specify aspects of name resolution
LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,	// reserved for future use, must be NULL
LPVOID lpCsaddrBuffer,	// points to buffer to receive address information
LPDWORD lpdwBufferLength,	// points to variable with address buffer size information
LPTSTR lpAliasBuffer,	// points to buffer to receive alias information
LPDWORD lpdwAliasBufferLength	// points to variable with alias buffer size information
);
Parameters

dwNameSpace

Specifies the name space, or a set of default name spaces, that the operating system will query for network address information.

Use one of the following constants to specify a name space:

Value	Name Space
NS_DEFAULT	A set of default name spaces. The function queries each name space within this set. The set of default name spaces typically includes all the name spaces installed on the system. System administrators, however, can exclude particular name spaces from the set. This is the value that most applications should use for dwNameSpace.
NS_DNS	The Domain Name System used in the Internet for host name resolution.
NS_NETBT	The NetBIOS over TCP/IP layer. All Windows NT systems register their computer names with NetBIOS. This name space is used to convert a computer name to an IP address that uses this registration. Note that NS_NETBT may access a WINS server to perform the resolution.
NS_SAP	The Netware Service Advertising Protocol. This may access the Netware bindery if appropriate. NS_SAP is a dynamic name space that allows registration of services.
NS_TCPIP_HOSTS	Lookup value in the <systemroot>\system32\drivers\etc\hosts file.
NS_TCPIP_LOCAL	Local TCP/IP name resolution mechanisms, including comparisons against the local host name and looks up host names and IP addresses in cache of host to IP address mappings.
Most calls to GetAddressByName should use the special value NS_DEFAULT. This lets a client get by with no knowledge of which name spaces are available on an internetwork. The system administrator determines name space access. Name spaces can come and go without the client having to be aware of the changes.

lpServiceType

Points to a globally unique identifier (GUID) that specifies the type of the network service. The header file SVCGUID.H includes definitions of several GUID service types, and macros for working with them.

lpServiceName

Points to a zero-terminated string that uniquely represents the service name. For example, “MY SNA SERVER”.

Setting lpServiceName to NULL is the equivalent of setting dwResolution to RES_SERVICE. The function operates in its second mode, obtaining the local address to which a service of the specified type should bind. The function stores the local address within the LocalAddr member of the CSADDR_INFO structures stored into *lpCsaddrBuffer.

If dwResolution is set to RES_SERVICE, the function ignores the lpServiceName parameter.

If dwNameSpace is set to NS_DNS, *lpServiceName is the name of the host.

lpiProtocols

Points to a zero-terminated array of protocol identifiers. The function restricts a name resolution attempt to name space providers that offer these protocols. This lets the caller limit the scope of the search.

If lpiProtocols is NULL, the function obtains information on all available protocols.

dwResolution

A set of bit flags that specify aspects of the service name resolution process. The following bit flags are defined:

Value	Meaning
RES_SERVICE	If this flag is set, the function obtains the address to which a service of the specified type should bind. This is the equivalent of setting lpServiceName to NULL. If this flag is clear, normal name resolution occurs.
RES_FIND_MULTIPLE	If this flag is set, the operating system performs an extensive search of all name spaces for the service. It will ask every appropriate name space to resolve the service name. If this flag is clear, the operating system stops looking for service addresses as soon as one is found.
RES_SOFT_SEARCH	This flag is valid if the name space supports multiple levels of searching. If this flag is valid and set, the operating system performs a simple and quick search of the name space. This is useful if an application only needs to obtain easy-to-find addresses for the service. If this flag is valid and clear, the operating system performs a more extensive search of the name space.
lplpServiceAsyncInfo

Reserved for future use; must be set to NULL.

lpCsaddrBuffer

Points to a buffer to receive one or more CSADDR_INFO data structures. The number of structures written to the buffer depends on the amount of information found in the resolution attempt. You should assume that multiple structures will be written, although in many cases there will only be one.

lpdwBufferLength

Points to a variable that, upon input, specifies the size, in bytes, of the buffer pointed to by lpCsaddrBuffer.

Upon output, this variable contains the total number of bytes required to store the array of CSADDR_INFO structures. If this value is less than or equal to the input value of *lpdwBufferLength, and the function is successful, this is the number of bytes actually stored in the buffer. If this value is greater than the input value of *lpdwBufferLength, the buffer was too small, and the output value of *lpdwBufferLength is the minimal required buffer size.

lpAliasBuffer

Points to a buffer to receive alias information for the network service.

If a name space supports aliases, the function stores an array of zero-terminated name strings into the buffer pointed to by lpAliasBuffer. There is a double zero-terminator at the end of the list. The first name in the array is the service’s primary name. Names that follow are aliases. An example of a name space that supports aliases is DNS.

If a name space does not support aliases, it stores a double zero-terminator into the buffer.

This parameter is optional, and can be set to NULL.

lpdwAliasBufferLength

Points to a variable that, upon input, specifies the size, in bytes, of the buffer pointed to by lpAliasBuffer.

Upon output, this variable contains the total number of bytes required to store the array of name strings. If this value is less than or equal to the input value of *lpdwAliasBufferLength, and the function is successful, this is the number of bytes actually stored in the buffer. If this value is greater than the input value of *lpdwAliasBufferLength, the buffer was too small, and the output value of *lpdwAliasBufferLength is the minimal required buffer size.

If lpAliasBuffer is NULL, lpdwAliasBufferLength is meaningless and can also be NULL.

Return Values

If the function succeeds, the return value is the number of CSADDR_INFO data structures written to the buffer pointed to by lpCsaddrBuffer.

If the function fails, the return value is SOCKET_ERROR( − 1). To get extended error information, call GetLastError. GetLastError may return the following extended error value:

Value	Meaning
ERROR_INSUFFICIENT_BUFFER	The buffer pointed to by lpCsaddrBuffer was too small to receive all of the relevant CSADDR_INFO structures. Call the function with a buffer at least as large as the value returned in *lpdwBufferLength.
Remarks

This function is a more powerful version of the Windows Sockets function gethostbyname The GetAddressByName function works with multiple name services.

The GetAddressByName function lets a client obtain a Windows Sockets address for a network service. The client specifies the service of interest by its service type and service name.

Many name services support a default prefix or suffix that the name service provider considers when resolving service names. For example, in the DNS name space, if a domain is named “nt.microsoft.com”, and “ftp millikan” is provided as input, the DNS software fails to resolve “millikan”, but successfully resolves “millikan.nt.microsoft.com”.

Note that the GetAddressByName function can search for a service address in two ways: within a particular name space, or within a set of default name spaces. Using a default name space, an administrator can specify that certain name spaces will be searched for service addresses only if specified by name. An administrator or name space setup program can also control the ordering of name space searches.

See Also

gethostbyname, CSADDR_INFO


gethostbyaddr

The Windows Sockets gethostbyaddr function gets host information corresponding to an address.

struct hostent FAR * gethostbyaddr (

const char FAR * addr,
int len,
int type
);
Parameters

addr

[in] A pointer to an address in network byte order.

len

[in] The length of the address.

type

[in] The type of the address.

Remarks

gethostbyaddr returns a pointer to the following hostent structure which contains the name(s) and address which correspond to the given address. All strings are null terminated.

Return Values

If no error occurs, gethostbyaddr returns a pointer to the hostent structure described above. Otherwise, it returns a NULL pointer and a specific error number can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
WSATRY_AGAIN	Non-Authoritative Host not found, or server failed.
WSANO_RECOVERY	Nonrecoverable error occurred.
WSANO_DATA	Valid name, no data record of requested type.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEAFNOSUPPORT	The type specified is not supported by the Windows Sockets implementation.
WSAEFAULT	The addr argument is not a valid part of the user address space, or the len argument is too small.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
See Also

gethostbyname, hostent, WSAAsyncGetHostByAddr


gethostbyname

The Windows Sockets gethostbyname function gets host information corresponding to a hostname.

struct hostent FAR * gethostbyname (

const char FAR * name
);
Parameters

name

[out] A pointer to the null terminated name of the host.

Remarks

gethostbyname returns a pointer to a hostent structure. The contents of this structure correspond to the hostname name.

The pointer which is returned points to a structure which is allocated by Windows Sockets. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets function calls.

gethostbyname does not resolve IP address strings passed to it. Such a request is treated exactly as if an unknown host name were passed. An application with an IP address string to resolve should use inet_addr to convert the string to an IP address, then gethostbyaddr to obtain the hostent structure.

gethostbyname will resolve the string returned by a successful call to gethostname.

Return Values

If no error occurs, gethostbyname returns a pointer to the hostent structure described above. Otherwise, it returns a NULL pointer and a specific error number can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
WSATRY_AGAIN	Non-Authoritative Host not found, or server failure.
WSANO_RECOVERY	Nonrecoverable error occurred.
WSANO_DATA	Valid name, no data record of requested type.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEFAULT	The name argument is not a valid part of the user address space.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
See Also

gethostbyaddr, WSAAsyncGetHostByName


gethostname

The Windows Sockets gethostname function returns the standard host name for the local machine.

int gethostname (

char FAR * name,
int namelen
);
Parameters

name

[out] A pointer to a buffer that will receive the host name.

namelen

[in] The length of the buffer.

Remarks

This routine returns the name of the local host into the buffer specified by the name parameter. The host name is returned as a null-terminated string. The form of the host name is dependent on the Windows Sockets provider — it can be a simple host name, or it can be a fully qualified domain name. However, it is guaranteed that the name returned will be successfully parsed by gethostbyname and WSAAsyncGetHostByName.

Note  If no local host name has been configured gethostname must succeed and return a token host name that gethostbyname or WSAAsyncGetHostByName can resolve.

Return Values

If no error occurs, gethostname returns zero. Otherwise, it returns SOCKET_ERROR and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSAEFAULT	The name argument is not a valid part of the user address space, or the buffer size specified by namelen argument is too small to hold the complete host name.
WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
See Also

gethostbyname, WSAAsyncGetHostByName


GetNameByType

Important  The GetNameByType function is a Microsoft-specific extension to the Windows Sockets 1.1 specification. This function is obsolete. For the convenience of Windows Sockets 1.1 developers, the reference material is below.

In Windows Sockets 2, this functionality is realized with the functions detailed in Protocol-Independent Name Resolution.

The GetNameByType function obtains the name of a network service. The network service is specified by its service type.

INT GetNameByType(

LPGUID lpServiceType,	// points to network service type GUID
LPTSTR lpServiceName,	// points to buffer to receive name of network service
DWORD dwNameLength	// points to variable that specifies buffer size
);
Parameters

lpServiceType

Points to a globally unique identifier (GUID) that specifies the type of the network service. The header file SVCGUID.H includes definitions of several GUID service types, and macros for working with them.

lpServiceName

Points to a buffer to receive a zero-terminated string that uniquely represents the name of the network service.

dwNameLength

Points to a variable that, on input, specifies the size of the buffer pointed to by lpServiceName. On output, the variable contains the actual size of the service name string.

Return Values

If the function succeeds, the return value is not SOCKET_ERROR ( −1).

If the function fails, the return value is SOCKET_ERROR ( −1). To get extended error information, call GetLastError.

See Also

GetTypeByName


getpeername

The Windows Sockets getpeername function gets the address of the peer to which a socket is connected.

int getpeername (

SOCKET s,
struct sockaddr FAR*  name,
int FAR*  namelen
);
Parameters

s

[in] A descriptor identifying a connected socket.

name

[out] The structure which is to receive the name of the peer.

namelen

[out] A pointer to the size of the name structure.

Remarks

getpeername retrieves the name of the peer connected to the socket s and stores it in the struct sockaddr identified by name. It can be used only on a connected socket. For datagram sockets, only the name of a peer specified in a previous connect call will be returnedany name specified by a previous sendto call will not be returned by getpeername.

On return, the namelen argument contains the actual size of the name returned in bytes.

Return Values

If no error occurs, getpeername returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	The name or the namelen argument is not a valid part of the user address space, or the namelen argument is too small.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAENOTCONN	The socket is not connected.
WSAENOTSOCK	The descriptor is not a socket.
See Also

bind, getsockname, socket


getprotobyname

The Windows Sockets getprotobyname function gets protocol information corresponding to a protocol name.

struct protoent FAR * getprotobyname (

const char FAR * name
);
Parameters

name

[in] A pointer to a null terminated protocol name.

Remarks

getprotobyname returns a pointer to the following structure which contains the name(s) and protocol number which correspond to the given protocol name. All strings are null terminated.

struct protoent {

    char FAR *        p_name;

    char FAR * FAR *  p_aliases;

    short             p_proto;

};

The members of this structure are:

Element	Usage
p_name	Official name of the protocol.
p_aliases	A NULL-terminated array of alternate names.
p_proto	The protocol number, in host byte order.
The pointer which is returned points to a structure which is allocated by the Windows Sockets library. The application must never attempt to modify this structure or to free any of its components. Furthermore only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets function calls.

Return Values

If no error occurs, getprotobyname returns a pointer to the protoent structure described above. Otherwise, it returns a NULL pointer and a specific error number can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAHOST_NOT_FOUND	Authoritative Answer Protocol not found.
WSATRY_AGAIN	Non-Authoritative Protocol not found, or server failure.
WSANO_RECOVERY	Nonrecoverable errors, the protocols database is not accessible.
WSANO_DATA	Valid name, no data record of requested type.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEFAULT	The name argument is not a valid part of the user address space.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
See Also

getprotobynumber, WSAAsyncGetProtoByName


getprotobynumber

The Windows Sockets getprotobynumber function gets protocol information corresponding to a protocol number.

struct protoent FAR * getprotobynumber (

int number
);
Parameters

number

[in] A protocol number, in host byte order.

Remarks

This function returns a pointer to a protoent structure as described above in getprotobyname. The contents of the structure correspond to the given protocol number.

The pointer which is returned points to a structure which is allocated by Windows Sockets. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets function calls.

Return Values

If no error occurs, getprotobynumber returns a pointer to the protoent structure described above. Otherwise, it returns a NULL pointer and a specific error number can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAHOST_NOT_FOUND	Authoritative Answer Protocol not found.
WSATRY_AGAIN	Non-Authoritative Protocol not found, or server failure.
WSANO_RECOVERY	Nonrecoverable errors, the protocols database is not accessible.
WSANO_DATA	Valid name, no data record of requested type.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
See Also

getprotobyname, WSAAsyncGetProtoByNumber


getservbyname

The Windows Sockets getsservbyname function gets service information corresponding to a service name and protocol.

struct servent FAR * getservbyname (

const char FAR * name,
const char FAR * proto
);
Parameters

name

[in] A pointer to a null terminated service name.

proto

[in] An optional pointer to a null terminated protocol name. If this pointer is NULL, getservbyname returns the first service entry for which the name matches the s_name or one of the s_aliases. Otherwise, getservbyname matches both the name and the proto.

Remarks

getservbyname returns a pointer to the following structure which contains the name(s) and service number which correspond to the given service name. All strings are null terminated.

struct servent {

    char FAR *        s_name;

    char FAR * FAR *  s_aliases;

    short             s_port;

    char FAR *        s_proto;

};

The members of this structure are:

Element	Usage
s_name	Official name of the service.
s_aliases	A NULL-terminated array of alternate names.
s_port	The port number at which the service can be contacted. Port numbers are returned in network byte order.
s_proto	The name of the protocol to use when contacting the service.
The pointer which is returned points to a structure which is allocated by the Windows Sockets library. The application must never attempt to modify this structure or to free any of its components. Furthermore only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets function calls.

Return Values

If no error occurs, getservbyname returns a pointer to the servent structure described above. Otherwise, it returns a NULL pointer and a specific error number can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAHOST_NOT_FOUND	Authoritative Answer Service not found.
WSATRY_AGAIN	Non-Authoritative Service not found, or server failure.
WSANO_RECOVERY	Nonrecoverable errors, the services database is not accessible.
WSANO_DATA	Valid name, no data record of requested type.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
See Also

getservbyport, WSAAsyncGetServByName


getservbyport

The Windows Sockets getservbyport function gets service information corresponding to a port and protocol.

struct servent FAR * getservbyport (

int port,
const char FAR* proto
);
Parameters

port

[in] The port for a service, in network byte order.

proto

[in] An optional pointer to a protocol name. If this is NULL, getservbyport returns the first service entry for which the port matches the s_port. Otherwise, getservbyport matches both the port and the proto.

Remarks

getservbyport returns a pointer to a servent structure as described above for getservbyname.

The pointer which is returned points to a structure which is allocated by Windows Sockets. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets function calls.

Return Values

If no error occurs, getservbyport returns a pointer to the servent structure described above. Otherwise, it returns a NULL pointer and a specific error number can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAHOST_NOT_FOUND	Authoritative Answer Service not found.
WSATRY_AGAIN	Non-Authoritative Service not found, or server failure.
WSANO_RECOVERY	Nonrecoverable errors, the services database is not accessible.
WSANO_DATA	Valid name, no data record of requested type.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEFAULT	The proto argument is not a valid part of the user address space.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
See Also

getservbyname, WSAAsyncGetServByPort


GetService

Important  The GetService function is a Microsoft-specific extension to the Windows Sockets 1.1 specification. This function is obsolete. For the convenience of Windows Sockets 1.1 developers, the reference material is below..

In Windows Sockets 2, this functionality is realized with the functions detailed in Protocol-Independent Name Resolution.

The GetService function obtains information about a network service in the context of a set of default name spaces or a specified name space. The network service is specified by its type and name. The information about the service is obtained as a set of NS_SERVICE_INFO data structures.

INT GetService(

DWORD dwNameSpace,	// specifies name space or spaces to search
PGUID lpGuid,	// points to a GUID service type
LPTSTR lpServiceName,	// points to a service name
DWORD dwProperties,	// specifies service information to be obtained
LPVOID lpBuffer,	// points to buffer to receive service information
LPDWORD lpdwBufferSize,	// points to size of buffer, size of service information
LPSERVICE_ASYNC_INFO lpServiceAsyncInfo	// reserved for future use, must be NULL
);
Parameters

dwNameSpace

Specifies the name space, or a set of default name spaces, that the operating system will query for information about the specified network service.

Use one of the following constants to specify a name space:

Value	Name Space
NS_DEFAULT	A set of default name spaces. The operating system will query each name space within this set. The set of default name spaces typically includes all the name spaces installed on the system. System administrators, however, can exclude particular name spaces from the set. NS_DEFAULT is the value that most applications should use for dwNameSpace.
NS_DNS	The Domain Name System used in the Internet for host name resolution.
NS_NETBT	The NetBIOS over TCP/IP layer. All Windows NT systems register their computer names with NetBIOS. This name space is used to resolve a computer name into an IP address using this registration. Note that NS_NETBT may access a WINS server to perform the resolution.
NS_SAP	The Netware Service Advertising Protocol. This may access the Netware bindery if appropriate. NS_SAP is a dynamic name space that allows registration of services.
NS_TCPIP_HOSTS	Looks up host names and IP addresses in the <systemroot>\system32\drivers\etc\hosts file.
NS_TCPIP_LOCAL	Local TCP/IP name resolution mechanisms, including comparisons against the local host name and looks up host names and IP addresses in cache of host to IP address mappings.
Most calls to GetService should use the special value NS_DEFAULT. This lets a client get by with no knowledge of which name spaces are available on an internetwork. The system administrator determines name space access. Name spaces can come and go without the client having to be aware of the changes.

lpGuid

Points to a globally unique identifier (GUID) that specifies the type of the network service. The header file SVCGUID.H includes GUID service types from many well-known services within the DNS and SAP name spaces.

lpServiceName

Points to a zero-terminated string that uniquely represents the service name. For example, “MY SNA SERVER”.

dwProperties

A set of bit flags that specify the service information that the function obtains. Each of these bit flag constants, other than PROP_ALL, corresponds to a particular member of the SERVICE_INFO data structure. If the flag is set, the function puts information into the corresponding member of the data structures stored in *lpBuffer. The following bit flags are defined:

Value	Name Space
PROP_COMMENT	If this flag is set, the function stores data in the lpComment member of the data structures stored in *lpBuffer.
PROP_LOCALE	If this flag is set, the function stores data in the lpLocale member of the data structures stored in *lpBuffer.
PROP_DISPLAY_HINT	If this flag is set, the function stores data in the dwDisplayHint member of the data structures stored in *lpBuffer.
PROP_VERSION	If this flag is set, the function stores data in the dwVersion member of the data structures stored in *lpBuffer.
PROP_START_TIME	If this flag is set, the function stores data in the dwTime member of the data structures stored in *lpBuffer.
PROP_MACHINE	If this flag is set, the function stores data in the lpMachineName member of the data structures stored in *lpBuffer.
PROP_ADDRESSES	If this flag is set, the function stores data in the lpServiceAddress member of the data structures stored in *lpBuffer.
PROP_SD	If this flag is set, the function stores data in the ServiceSpecificInfo member of the data structures stored in *lpBuffer.
PROP_ALL	If this flag is set, the function stores data in all of the members of the data structures stored in *lpBuffer.
lpBuffer

Points to a buffer to receive an array of NS_SERVICE_INFO structures and associated service information. Each NS_SERVICE_INFO structure contains service information in the context of a particular name space. Note that if dwNameSpace is NS_DEFAULT, the function stores more than one structure into the buffer; otherwise, just one structure is stored.

Each NS_SERVICE_INFO structure contains a SERVICE_INFO structure. The members of these SERVICE_INFO structures will contain valid data based on the bit flags that are set in the dwProperties parameter. If a member’s corresponding bit flag is not set in dwProperties, the member’s value is undefined.

The function stores the NS_SERVICE_INFO structures in a consecutive array, starting at the beginning of the buffer. The pointers in the contained SERVICE_INFO structures point to information that is stored in the buffer between the end of the NS_SERVICE_INFO structures and the end of the buffer.

lpdwBufferSize

Points to a variable that, on input, contains the size, in bytes, of the buffer pointed to by lpBuffer. On output, this variable contains the number of bytes required to store the requested information. If this output value is greater than the input value, the function has failed due to insufficient buffer size.

lpServiceAsyncInfo

This parameter is reserved for future use. It must be set to NULL.

Return Values

If the function succeeds, the return value is the number of NS_SERVICE_INFO structures stored in *lpBuffer. Zero indicates that no structures were stored.

If the function fails, the return value is SOCKET_ERROR ( − 1). To get extended error information, call GetLastError. GetLastError may return one of the following extended error values:

Value	Meaning
ERROR_INSUFFICIENT_BUFFER	The buffer pointed to by lpBuffer is too small to receive all of the requested information. Call the function with a buffer at least as large as the value returned in *lpdwBufferSize.
ERROR_SERVICE_NOT_FOUND	The specified service was not found, or the specified name space is not in use. The function return value is zero in this case.
See Also

SetService, NS_SERVICE_INFO, SERVICE_INFO


getsockname

The Windows Sockets getsockname function gets the local name for a socket.

int getsockname (

SOCKET s,
struct sockaddr FAR*  name,
int FAR*  namelen
);
Parameters

s

[in] A descriptor identifying a bound socket.

name

[out] Receives the address (name) of the socket.

namelen

[out] The size of the name buffer.

Remarks

getsockname retrieves the current name for the specified socket descriptor in name. It is used on a bound and/or connected socket specified by the s parameter. The local association is returned. This call is especially useful when a connect call has been made without doing a bind first; this call provides the only means by which you can determine the local association which has been set by the system.

On return, the namelen argument contains the actual size of the name returned in bytes.

If a socket was bound to an unspecified address (for example, ADDR_ANY), indicating that any of the host's addresses within the specified address family should be used for the socket, getsockname will not necessarily return information about the host address, unless the socket has been connected with connect or accept. A Windows Sockets application must not assume that the address will be specified unless the socket is connected. This is because for a multihomed host the address that will be used for the socket is unknown unless the socket is connected.

Return Values

If no error occurs, getsockname returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	The name or the namelen argument is not a valid part of the user address space, or the namelen argument is too small.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAENOTSOCK	The descriptor is not a socket.
WSAEINVAL	The socket has not been bound to an address with bind, or ADDR_ANY is specified in bind but connection has not yet occurs.
See Also

bind, getpeername, socket


getsockopt

The Windows Sockets getsockopt function retrieves a socket option.

int getsockopt (

SOCKET s,
int level,
int optname,
char FAR* optval,
int FAR*  optlen
);
Parameters

s

[in] A descriptor identifying a socket.

level

[in] The level at which the option is defined; the supported levels include SOL_SOCKET and IPPROTO_TCP. (See annex for more protocol-specific levels.)

optname

[in] The socket option for which the value is to be retrieved.

optval

[out] A pointer to the buffer in which the value for the requested option is to be returned.

optlen

[in/out] A pointer to the size of the optval buffer.

Remarks

getsockopt retrieves the current value for a socket option associated with a socket of any type, in any state, and stores the result in optval. Options can exist at multiple protocol levels, but they are always present at the uppermost "socket'' level. Options affect socket operations, such as the packet routing and out-of-band data transfer.

The value associated with the selected option is returned in the buffer optval. The integer pointed to by optlen should originally contain the size of this buffer; on return, it will be set to the size of the value returned. For SO_LINGER, this will be the size of a struct linger; for most other options it will be the size of an integer.

The application is responsible for allocating any memory space pointed to directly or indirectly by any of the parameters it specified.

If the option was never set with setsockopt, then getsockopt returns the default value for the option.

The following options are supported for getsockopt. The Type identifies the type of data addressed by optval.

level = SOL_SOCKET

Value	Type	Meaning
SO_ACCEPTCONN	BOOL	Socket is listening.
SO_BROADCAST	BOOL	Socket is configured for the transmission of broadcast messages.
SO_DEBUG	BOOL	Debugging is enabled.
SO_DONTLINGER	BOOL	If true, the SO_LINGER option is disabled.
SO_DONTROUTE	BOOL	Routing is disabled.
SO_ERROR	int	Retrieve error status and clear.
SO_GROUP_ID	GROUP	The identifier of the group to which this socket belongs.
SO_GROUP_PRIORITY	int	The relative priority for sockets that are part of a socket group.
SO_KEEPALIVE	BOOL	Keepalives are being sent.
SO_LINGER	struct linger	Returns the current linger options.
SO_MAX_MSG_SIZE	unsigned int	Maximum size of a message for message-oriented socket types (for example, SOCK_DGRAM). Has no meaning for stream-oriented sockets.
SO_OOBINLINE	BOOL	Out-of-band data is being received in the normal data stream. (See section Windows Sockets 1.1 Blocking Routines & EINPROGRESS for a discussion of this topic.)
SO_PROTOCOL_INFO	WSAPROTOCOL_INFO	Description of protocol info for protocol that is bound to this socket.
SO_RCVBUF	int	Buffer size for receives
SO_REUSEADDR	BOOL	The socket may be bound to an address which is already in use.
SO_SNDBUF	int	Buffer size for sends
SO_TYPE	int	The type of the socket (for example, SOCK_STREAM).
PVD_CONFIG	Service Provider Dependent	An "opaque" data structure object from the service provider associated with socket s. This object stores the current configuration information of the service provider. The exact format of this data structure is service provider specific.
level = IPPROTO_TCP

TCP_NODELAY	BOOL	Disables the Nagle algorithm for send coalescing.
BSD options not supported for getsockopt are:

Value	Type	Meaning
SO_RCVLOWAT	int	Receive low water mark
SO_RCVTIMEO	int	Receive time-out
SO_SNDLOWAT	int	Send low water mark
SO_SNDTIMEO	int	Send time-out
TCP_MAXSEG	int	Get TCP maximum segment size
Calling getsockopt with an unsupported option will result in an error code of WSAENOPROTOOPT being returned from WSAGetLastError.

SO_DEBUG

Windows Sockets service providers are encouraged (but not required) to supply output debug information if the SO_DEBUG option is set by an application. The mechanism for generating the debug information and the form it takes are beyond the scope of this specification.

SO_ERROR

The SO_ERROR option returns and resets the per-socket based error code, which is different from the per-thread based error code that is handled using the WSAGetLastError and WSASetLastError function calls. A successful call using the socket does not reset the socket based error code returned by the SO_ERROR option.

SO_GROUP_ID

This is a get-only socket option which indicates the identifier of the group this socket belongs to. Note that socket group IDs are unique across all processes for a give service provider. If this socket is not a group socket, the value is NULL.

SO_GROUP_PRIORITY

Group priority indicates the priority of the specified socket relative to other sockets within the socket group. Values are non-negative integers, with zero corresponding to the highest priority. Priority values represent a hint to the underlying service provider about how potentially scarce resources should be allocated. For example, whenever two or more sockets are both ready to transmit data, the highest priority socket (lowest value for SO_GROUP_PRIORITY) should be serviced first, with the remainder serviced in turn according to their relative priorities.

The WSAENOPROTOOPT error code is indicated for non group sockets or for service providers which do not support group sockets.

SO_KEEPALIVE

An application can request that a TCP/IP service provider enable the use of "keep-alive" packets on TCP connections by turning on the SO_KEEPALIVE socket option. A Windows Sockets provider need not support the use of keep-alive: if it does, the precise semantics are implementation-specific but should conform to section 4.2.3.6 of RFC 1122: Requirements for Internet Hosts  Communication Layers. If a connection is dropped as the result of "keep-alives" the error code WSAENETRESET is returned to any calls in progress on the socket, and any subsequent calls will fail with WSAENOTCONN.

SO_LINGER

SO_LINGER controls the action taken when unsent data is queued on a socket and a closesocket is performed. See closesocket for a description of the way in which the SO_LINGER settings affect the semantics of closesocket. The application gets the current behavior by retrieving a struct linger (pointed to by the optval argument) with the following elements:

struct linger {

    u_short    l_onoff;

    u_short    l_linger;

}

SO_MAX_MSG_SIZE

This is a get-only socket option which indicates the maximum size of a message for message-oriented socket types (for example, SOCK_DGRAM) as implemented by a particular service provider. It has no meaning for byte stream oriented sockets

SO_PROTOCOL_INFO

This is a get-only option which supplies the WSAPROTOCOL_INFO structure associated with this socket. See WSAEnumProtocols for more information about this structure.

SO_RCVBUF

SO_SNDBUF

When a Windows Sockets implementation supports the SO_RCVBUF and SO_SNDBUF options, an application can request different buffer sizes (larger or smaller). The call to setsockopt can succeed, although the implementation did not provide the whole amount requested. An application must call this function with the same option to check the buffer size actually provided.

SO_REUSEADDR

By default, a socket cannot be bound (see bind) to a local address which is already in use. On occasion, however, it may be necessary to "re-use" an address in this way. Since every connection is uniquely identified by the combination of local and remote addresses, there is no problem with having two sockets bound to the same local address as long as the remote addresses are different. To inform the Windows Sockets provider that a bind on a socket should not be disallowed because the desired address is already in use by another socket, the application should set the SO_REUSEADDR socket option for the socket before issuing the bind. Note that the option is interpreted only at the time of the bind: it is therefore unnecessary (but harmless) to set the option on a socket which is not to be bound to an existing address, and setting or resetting the option after the bind has no effect on this or any other socket.

PVD_CONFIG

This option retrieves an "opaque" data structure object from the service provider associated with socket s. This object stores the current configuration information of the service provider. The exact format of this data structure is service provider specific.

TCP_NODELAY

The Nagle algorithm is disabled if the TCP_NODELAY option is enabled (and vice versa). The Nagle algorithm (described in RFC 896) is very effective in reducing the number of small packets sent by a host by essentially buffering send data if there is unacknowledged data already "in flight" or until a full-size packet can be sent. It is highly recommended that Windows Sockets implementations enable the Nagle Algorithm by default, and for the vast majority of application protocols the Nagle Algorithm can deliver significant performance enhancements. However, for some applications this algorithm can impede performance, and setsockopt with the same option can be used to turn it off. These are applications where many small messages are sent, which need to be received by the peer with the time delays between the messages maintained.

Return Values

If no error occurs, getsockopt returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	One of the optval or the optlen arguments is not a valid part of the user address space, or the optlen argument is too small.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINVAL	level is unknown or invalid
WSAENOPROTOOPT	The option is unknown or unsupported by the indicated protocol family.
WSAENOTSOCK	The descriptor is not a socket.
See Also

setsockopt, socket, WSAAsyncSelect, WSAConnect, WSAGetLastError, WSASetLastError


GetTypeByName

Important  The GetTypeByName function is a Microsoft-specific extension to the Windows Sockets 1.1 specification. This function is obsolete. For the convenience of Windows Sockets 1.1 developers, the reference material is below.

In Windows Sockets 2, this functionality is realized with the functions detailed in Protocol-Independent Name Resolution.

The GetTypeByName function obtains a service type GUID for a network service specified by name.

INT GetTypeByName(

LPTSTR lpServiceName,	// points to the name of the network service
PGUID lpServiceType	// points to a variable to receive network service type
);
Parameters

lpServiceName

Points to a zero-terminated string that uniquely represents the name of the service. For example, “MY SNA SERVER”.

lpServiceType

Points to a variable to receive a globally unique identifier (GUID) that specifies the type of the network service. The header file SVCGUID.H includes definitions of several GUID service types and macros for working with them.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is SOCKET_ERROR( − 1). To get extended error information, call GetLastError. GetLastError may return the following extended error value:

Value	Meaning
ERROR_SERVICE_DOES_NOT_EXIST	The specified service type is unknown.
See Also

GetNameByType


htonl

The Windows Sockets htonl function converts a u_long from host to TCP/IP network byte order.

u_long htonl (

u_long hostlong
);
Parameters

hostlong

[in] A 32-bit number in host byte order.

Remarks

This routine takes a 32-bit number in host byte order and returns a 32-bit number in the network byte order used in TCP/IP networks.

Return Values

htonl returns the value in TCP/IP’s network byte order.

See Also

htons, ntohl, ntohs, WSAHtonl, WSAHtons, WSANtohl, WSANtohs


htons

The Windows Sockets htons function converts a u_short from host to TCP/IP network byte order.

u_short htons (

u_short hostshort
);
Parameters

hostshort

[in] A 16-bit number in host byte order.

Remarks

This routine takes a 16-bit number in host byte order and returns a 16-bit number in network byte order used in TCP/IP networks.

Return Values

htons returns the value in TCP/IP network byte order.

See Also

htonl, ntohl, ntohs, WSAHtonl, WSAHtons, WSANtohl, WSANtohs


inet_addr

The Windows Sockets inet_addr function converts a string containing an Internet Protocol dotted address into an in_addr.

unsigned long inet_addr (

const char FAR * cp
);
Parameters

cp

[in] A null-terminated character string representing a number expressed in the Internet standard ".'' notation.

Remarks

This function interprets the character string specified by the cp parameter. This string represents a numeric Internet address expressed in the Internet standard ".'' notation. The value returned is a number suitable for use as an Internet address. All Internet addresses are returned in IP’s network order (bytes ordered from left to right).

Internet Addresses

Values specified using the ".'' notation take one of the following forms:

a.b.c.d    a.b.c    a.b    a

When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. Note that when an Internet address is viewed as a 32-bit integer quantity on the Intel architecture, the bytes referred to above appear as "d.c.b.a''. That is, the bytes on an Intel processor are ordered from right to left.

Note  The following notations are only used by Berkeley, and nowhere else on the Internet. In the interests of compatibility with their software, they are supported as specified.

When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right most two bytes of the network address. This makes the three part address format convenient for specifying Class B network addresses as "128.net.host''.

When a two part address is specified, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as "net.host''.

When only one part is given, the value is stored directly in the network address without any byte rearrangement.

Return Values

If no error occurs, inet_addr returns an unsigned long containing a suitable binary representation of the Internet address given. If the passed-in string does not contain a legitimate Internet address, for example if a portion of an "a.b.c.d" address exceeds 255, inet_addr returns the value INADDR_NONE.

See Also

inet_ntoa


inet_ntoa

The Windows Sockets inet_ntoa function converts a network address into a string in dotted format.

char FAR * inet_ntoa (

struct in_addr in
);
Parameters

in

[in] A structure which represents an Internet host address.

Remarks

This function takes an Internet address structure specified by the in parameter. It returns an ASCII string representing the address in ".'' notation as "a.b.c.d''. Note that the string returned by inet_ntoa resides in memory which is allocated by Windows Sockets. The application should not make any assumptions about the way in which the memory is allocated. The data is guaranteed to be valid until the next Windows Sockets function call within the same thread, but no longer.

Return Values

If no error occurs, inet_ntoa returns a char pointer to a static buffer containing the text address in standard ".'' notation. Otherwise, it returns NULL. The data should be copied before another Windows Sockets call is made.

See Also

inet_addr


ioctlsocket

The Windows Sockets ioctlsocket function controls the mode of a socket.

int ioctlsocket (

SOCKET s,
long cmd,
u_long FAR* argp
);
Parameters

s

[in] A descriptor identifying a socket.

cmd

[in] The command to perform on the socket s.

argp

[in/out] A pointer to a parameter for cmd.

Remarks

This routine can be used on any socket in any state. It is used to get or retrieve operating parameters associated with the socket, independent of the protocol and communications subsystem. Here are the supported commands and their semantics:

FIONBIO

Enable or disable nonblocking mode on socket s. argp points at an unsigned long, which is nonzero if nonblocking mode is to be enabled and zero if it is to be disabled. When a socket is created, it operates in blocking mode (that is, nonblocking mode is disabled). This is consistent with BSD sockets.

The WSAAsyncSelect or WSAEventSelect routine automatically sets a socket to nonblocking mode. If WSAAsyncSelect or WSAEventSelect has been issued on a socket, then any attempt to use ioctlsocket to set the socket back to blocking mode will fail with WSAEINVAL. To set the socket back to blocking mode, an application must first disable WSAAsyncSelect by calling WSAAsyncSelect with the lEvent parameter equal to zero, or disable WSAEventSelect by calling WSAEventSelect with the lNetworkEvents parameter equal to zero.

FIONREAD

Determine the amount of data which can be read atomically from socket s. argp points to an unsigned long in which ioctlsocket stores the result. If s is stream oriented (for example, type SOCK_STREAM), FIONREAD returns an amount of data which can be read in a single recv; this may or may not be the same as the total amount of data queued on the socket. If s is message oriented (for example, type SOCK_DGRAM), FIONREAD returns the size of the first datagram (message) queued on the socket.

SIOCATMARK

Determine whether or not all out-of-band data has been read. (See section Windows Sockets 1.1 Blocking Routines & EINPROGRESS for a discussion of this topic.) This applies only to a socket of stream style (for example, type SOCK_STREAM) which has been configured for in-line reception of any out-of-band data (SO_OOBINLINE). If no out-of-band data is waiting to be read, the operation returns TRUE. Otherwise, it returns FALSE, and the next recv or recvfrom performed on the socket will retrieve some or all of the data preceding the "mark"; the application should use the SIOCATMARK operation to determine whether any remains. If there is any normal data preceding the "urgent" (out of band) data, it will be received in order. (Note that a recv or recvfrom will never mix out-of-band and normal data in the same call.) argp points to an unsigned long in which ioctlsocket stores the boolean result.

Compatibility

This function is a subset of ioctl as used in Berkeley sockets. In particular, there is no command which is equivalent to FIOASYNC, while SIOCATMARK is the only socket-level command which is supported.

Return Values

Upon successful completion, the ioctlsocket returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAENOTSOCK	The descriptor s is not a socket.
WSAEFAULT	The argp argument is not a valid part of the user address space.
See Also

getsockopt, setsockopt, socket, WSAAsyncSelect, WSAEventSelect, WSAIoctl


listen

The Windows Sockets listen function establishes a socket to listen for an incoming connection.

int listen (

SOCKET s,
int backlog
);
Parameters

s

[in] A descriptor identifying a bound, unconnected socket.

backlog

[in] The maximum length to which the queue of pending connections can GROW. If this value is SOMAXCONN, then the underlying service provider responsible for socket s will set the backlog to a maximum “reasonable” value.

Remarks

To accept connections, a socket is first created with socket, a backlog for incoming connections is specified with listen, and then the connections are accepted with accept. listen applies only to sockets that are connection oriented, for example, those of type SOCK_STREAM. The socket s is put into "passive'' mode where incoming connection requests are acknowledged and queued pending acceptance by the process.

This function is typically used by servers that could have more than one connection request at a time: if a connection request arrives with the queue full, the client will receive an error with an indication of WSAECONNREFUSED.

listen attempts to continue to function rationally when there are no available descriptors. It will accept connections until the queue is emptied. If descriptors become available, a later call to listen or accept will refill the queue to the current or most recent "backlog'', if possible, and resume listening for incoming connections.

An application can call listen more than once on the same socket. This has the effect of updating the current backlog for the listening socket. Should there be more pending connections than the new backlog value, the excess pending connections will be reset and dropped.

Compatibility

The backlog parameter is limited (silently) to a reasonable value as determined by the underlying service provider. Illegal values are replaced by the nearest legal value.

Return Values

If no error occurs, listen returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEADDRINUSE	An attempt has been made to listen on an address in use.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINVAL	The socket has not been bound with bind.
WSAEISCONN	The socket is already connected.
WSAEMFILE	No more socket descriptors are available.
WSAENOBUFS	No buffer space is available.
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	The referenced socket is not of a type that supports the listen operation.
See Also

accept, connect, socket


ntohl

The Windows Sockets ntohl function converts a u_long from TCP/IP network order to host byte order.

u_long ntohl (

u_long netlong
);
Parameters

netlong

[in] A 32-bit number in TCP/IP network byte order.

Remarks

This routine takes a 32-bit number in TCP/IP network byte order and returns a 32-bit number in host byte order.

Return Values

ntohl returns the value in host byte order.

See Also

htonl, htons, ntohs, WSAHtonl, WSAHtons, WSANtohl, WSANtohs


ntohs

The Windows Sockets ntohs function converts a u_short from TCP/IP network byte order to host byte order.

u_short ntohs (

u_short netshort
);
Parameters

netshort

[in] A 16-bit number in TCP/IP network byte order.

Remarks

This routine takes a 16-bit number in TCP/IP network byte order and returns a 16-bit number in host byte order.

Return Values

ntohs returns the value in host byte order.

See Also

htonl, htons, ntohl, WSAHtonl, WSAHtons, WSANtohl, WSANtohs


recv

The Windows Sockets recv function receives data from a socket.

int recv (

SOCKET s,
char FAR* buf,
int len,
int flags
);
Parameters

s

[in] A descriptor identifying a connected socket.

buf

[out] A buffer for the incoming data.

len

[in] The length of buf.

flags

[in] Specifies the way in which the call is made.

Remarks

This function is used on connected sockets or bound connectionless sockets specified by the s parameter and is used to read incoming data.

For byte stream style socket (for example, type SOCK_STREAM), as much information as is currently available up to the size of the buffer supplied is returned. If the socket has been configured for in-line reception of out-of-band data (socket option SO_OOBINLINE) and out-of-band data is unread, only out-of-band data will be returned. The application can use the ioctlsocket SIOCATMARK to determine whether any more out-of-band data remains to be read.

For message-oriented sockets (for example, type SOCK_DGRAM), data is extracted from the first enqueued datagram (message) from the destination address specified in the connect call. If unconnected, the socket must be bound, and there are no source address restrictions on datagrams received. If the datagram or message is larger than the buffer supplied, the buffer is filled with the first part of the datagram, and recv generates the error WSAEMSGSIZE. For unreliable protocols (for example, UDP) the excess data is lost, for reliable protocols the data is retained by the service provider until it is successfully read by calling recv with a large enough buffer.

If no incoming data is available at the socket, the recv call waits for data to arrive unless the socket is nonblocking. In this case, a value of SOCKET_ERROR is returned with the error code set to WSAEWOULDBLOCK. The select, WSAAsyncSelect, or WSAEventSelect calls can be used to determine when more data arrives.

If the socket is connection oriented and the remote side has shut down the connection gracefully, a recv will complete immediately with zero bytes received. If the connection has been reset, a recv will fail with the error WSAECONNRESET.

The flags parameter can be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by or’ing any of the following values:

Value	Meaning
MSG_PEEK	Peek at the incoming data. The data is copied into the buffer but is not removed from the input queue.
MSG_OOB	Process out-of-band data. (See section Out-Of-Band data for a discussion of this topic.)
Return Values

If no error occurs, recv returns the number of bytes received. If the connection has been gracefully closed, the return value is zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	The buf argument is not totally contained in a valid part of the user address space.
WSAENOTCONN	The socket is not connected.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAENETRESET	The connection has been broken due to the remote host resetting.
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	MSG_OOB was specified, but the socket is not stream style such as type SOCK_STREAM, out-of-band data is not supported in the communication domain associated with this socket, or the socket is unidirectional and supports only send operations.
WSAESHUTDOWN	The socket has been shut down; it is not possible to recv on a socket after shutdown has been invoked with how set to SD_RECEIVE or SD_BOTH.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the receive operation would block.
WSAEMSGSIZE	The message was too large to fit into the specified buffer and was truncated.
WSAEINVAL	The socket has not been bound with bind, or an unknown flag was specified, or MSG_OOB was specified for a socket with SO_OOBINLINE enabled or (for byte stream sockets only) len was zero or negative.
WSAECONNABORTED	The virtual circuit was terminated due to a time-out or other failure. The application should close the socket as it is no longer usable.
WSAETIMEDOUT	The connection has been dropped because of a network failure or because the peer system failed to respond.
WSAECONNRESET	The virtual circuit was reset by the remote side executing a “hard” or “abortive” close. The application should close the socket as it is no longer usable. On a UDP datagram socket this error would indicate that a previous send operation resulted in an ICMP "Port Unreachable" message.
See Also

recvfrom, select, send, socket, WSAAsyncSelect


recvfrom

The Windows Sockets recvfrom function receives a datagram and stores the source address.

int recvfrom (

SOCKET s,
char FAR* buf,
int len,
int flags,
struct sockaddr FAR* from,
int FAR* fromlen
);
Parameters

s

[in] A descriptor identifying a bound socket.

buf

[out] A buffer for the incoming data.

len

[in] The length of buf.

flags

[in] Specifies the way in which the call is made.

from

[out] An optional pointer to a buffer which will hold the source address upon return.

fromlen

[in/out] An optional pointer to the size of the from buffer.

Remarks

This function is used to read incoming data on a (possibly connected) socket and capture the address from which the data was sent.

For stream-oriented sockets such as those of type SOCK_STREAM, as much information as is currently available up to the size of the buffer supplied is returned. If the socket has been configured for in-line reception of out-of-band data (socket option SO_OOBINLINE) and out-of-band data is unread, only out-of-band data will be returned. The application can use the ioctlsocket SIOCATMARK to determine whether any more out-of-band data remains to be read. The from and fromlen parameters are ignored for connection-oriented sockets.

For message-oriented sockets, data is extracted from the first enqueued message, up to the size of the buffer supplied. If the datagram or message is larger than the buffer supplied, the buffer is filled with the first part of the datagram, and recvfrom generates the error WSAEMSGSIZE. For unreliable protocols (for example, UDP) the excess data is lost.

If from is nonzero, and the socket is not connection oriented (for example, type SOCK_DGRAM), the network address of the peer which sent the data is copied to the corresponding struct sockaddr. The value pointed to by fromlen is initialized to the size of this structure, and is modified on return to indicate the actual size of the address stored there.

If no incoming data is available at the socket, the recvfrom call waits for data to arrive unless the socket is nonblocking. In this case, a value of SOCKET_ERROR is returned with the error code set to WSAEWOULDBLOCK. The select, WSAAsyncSelect, or WSAEventSelect can be used to determine when more data arrives.

If the socket is connection oriented and the remote side has shut down the connection gracefully, a recvfrom will complete immediately with zero bytes received. If the connection has been reset recvfrom will fail with the error WSAECONNRESET.

Flags can be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by or-ing any of the following values:

Value	Meaning
MSG_PEEK	Peek at the incoming data. The data is copied into the buffer but is not removed from the input queue.
MSG_OOB	Process out-of-band data. (See section Out-Of-Band data for a discussion of this topic.)
Return Values

If no error occurs, recvfrom returns the number of bytes received. If the connection has been gracefully closed, the return value is zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	The buf or from parameters are not part of the user address space, or the fromlen argument is too small to accommodate the peer address.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINVAL	The socket has not been bound with bind, or an unknown flag was specified, or MSG_OOB was specified for a socket with SO_OOBINLINE enabled, or (for byte stream style sockets only) len was zero or negative.
WSAENETRESET	The connection has been broken due to the remote host resetting.
WSAENOTCONN	The socket is not connected (connection-oriented sockets only).
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	MSG_OOB was specified, but the socket is not stream style such as type SOCK_STREAM, out-of-band data is not supported in the communication domain associated with this socket, or the socket is unidirectional and supports only send operations.
WSAESHUTDOWN	The socket has been shut down; it is not possible to recvfrom on a socket after shutdown has been invoked with how set to SD_RECEIVE or SD_BOTH.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the recvfrom operation would block.
WSAEMSGSIZE	The message was too large to fit into the specified buffer and was truncated.
WSAECONNABORTED	The virtual circuit was terminated due to a time-out or other failure. The application should close the socket as it is no longer usable.
WSAETIMEDOUT	The connection has been dropped, because of a network failure or because the system on the other end went down without notice.
WSAECONNRESET	The virtual circuit was reset by the remote side executing a “hard” or “abortive” close. The application should close the socket as it is no longer usable. On a UDP datagram socket this error would indicate that a previous send operation resulted in an ICMP "Port Unreachable" message.
See Also

recv, send, socket, WSAAsyncSelect, WSAEventSelect


select

The Windows Sockets select function determines the status of one or more sockets, waiting if necessary.

int select (

int nfds,
fd_set FAR * readfds,
fd_set FAR * writefds,
fd_set FAR * exceptfds,
const struct timeval FAR * timeout
);
Parameters

nfds

[in] This argument is ignored and included only for the sake of compatibility.

readfds

[in/out] An optional pointer to a set of sockets to be checked for readability.

writefds

[in/out] An optional pointer to a set of sockets to be checked for writability

exceptfds

[in/out] An optional pointer to a set of sockets to be checked for errors.

timeout

[in] The maximum time for select to wait, or NULL for blocking operation.

Remarks

This function is used to determine the status of one or more sockets. For each socket, the caller can request information on read, write or error status. The set of sockets for which a given status is requested is indicated by an fd_set structure. The sockets contained within the fd_set structures must be associated with a single service provider. Upon return, the structures are updated to reflect the subset of these sockets which meet the specified condition, and select returns the number of sockets meeting the conditions. A set of macros is provided for manipulating an fd_set. These macros are compatible with those used in the Berkeley software, but the underlying representation is completely different.

The parameter readfds identifies those sockets which are to be checked for readability. If the socket is currently listening, it will be marked as readable if an incoming connection request has been received, so that an accept is guaranteed to complete without blocking. For other sockets, readability means that queued data is available for reading so that a recv or recvfrom is guaranteed not to block.

For connection-oriented sockets, readability can also indicate that a close request has been received from the peer. If the virtual circuit was closed gracefully, then a recv will return immediately with zero bytes read. If the virtual circuit was reset, then a recv will complete immediately with an error code, such as WSAECONNRESET. The presence of out-of-band data will be checked if the socket option SO_OOBINLINE has been enabled (see setsockopt).

The parameter writefds identifies those sockets which are to be checked for writability. If a socket is connecting (nonblocking), writability means that the connection establishment successfully completed. If the socket is not in the process of connecting, writability means that a send or sendto are guaranteed to succeed. However, they can block on a blocking socket if the len exceeds the amount of outgoing system buffer space available. [It is not specified how long these guarantees can be assumed to be valid, particularly in a multithreaded environment.]

The parameter exceptfds identifies those sockets which are to be checked for the presence of out-of-band data (see section Out-Of-Band data for a discussion of this topic) or any exceptional error conditions. Note that out-of-band data will only be reported in this way if the option SO_OOBINLINE is FALSE. If a socket is connecting (nonblocking), failure of the connect attempt is indicated in exceptfds. This specification does not define which other errors will be included.

Any two of readfds, writefds, or exceptfds can be given as NULL if no descriptors are to be checked for the condition of interest. At least one must be non-NULL, and any non-NULL descriptor set must contain at least one socket descriptor.

Summary: A socket will be identified in a particular set when select returns if:

readfds:

•	If listening, a connection is pending, accept will succeed

•	Data is available for reading (includes OOB data if SO_OOBINLINE is enabled)

•	Connection has been closed/reset/terminated

writefds:

•	If connecting (nonblocking), connection has succeeded

•	Data can be sent

exceptfds:

•	If connecting (nonblocking), connection attempt failed

•	OOB data is available for reading (only if SO_OOBINLINE is disabled)

Four macros are defined in the header file WINSOCK2.H for manipulating and checking the descriptor sets. The variable FD_SETSIZE determines the maximum number of descriptors in a set. (The default value of FD_SETSIZE is 64, which can be modified by #defining FD_SETSIZE to another value before #including WINSOCK2.H.) Internally, socket handles in a fd_set are not represented as bit flags as in Berkeley Unix. Their data representation is opaque. Use of these macros will maintain software portability between different socket environments. The macros to manipulate and check fd_set contents are:

FD_CLR(s, *set)

Removes the descriptor s from set.

FD_ISSET(s, *set)

Nonzero if s is a member of the set. Otherwise, zero.

FD_SET(s, *set)

Adds descriptor s to set.

FD_ZERO(*set)

Initializes the set to the NULL set.

The parameter timeout controls how long the select can take to complete. If timeout is a null pointer, select will block indefinitely until at least one descriptor meets the specified criteria. Otherwise, timeout points to a struct timeval which specifies the maximum time that select should wait before returning. When select returns, the contents of the struct timeval are not altered. If the timeval is initialized to {0, 0}, select will return immediately; this is used to "poll" the state of the selected sockets. If this is the case, then the select call is considered nonblocking and the standard assumptions for nonblocking calls apply. For example, the blocking hook will not be called, and Windows Sockets will not yield.

Return Values

select returns the total number of descriptors which are ready and contained in the fd_set structures, zero if the time limit expired, or SOCKET_ERROR if an error occurred. If the return value is SOCKET_ERROR, WSAGetLastError can be used to retrieve a specific error code.

Comments

select has no effect on the persistence of socket events registered with WSAAsyncSelect or WSAEventSelect.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAEFAULT	The Windows Sockets implementation was unable to allocated needed resources for its internal operations, or the readfds, writefds, exceptfds, or timeval parameters are not part of the user address space.
WSAENETDOWN	The network subsystem has failed.
WSAEINVAL	The timeout value is not valid, or all three descriptor parameters were NULL.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAENOTSOCK	One of the descriptor sets contains an entry which is not a socket.
See Also

accept, connect, recv, recvfrom, send, WSAAsyncSelect, WSAEventSelect


send

The Windows Sockets send function sends data on a connected socket.

int send (

SOCKET s,
const char FAR * buf,
int len,
int flags
);
Parameters

s

[in] A descriptor identifying a connected socket.

buf

[in] A buffer containing the data to be transmitted.

len

[in] The length of the data in buf.

flags

[in] Specifies the way in which the call is made.

Remarks

send is used to write outgoing data on a connected socket. For message-oriented sockets, care must be taken not to exceed the maximum packet size of the underlying provider, which can be obtained by getting the value of socket option SO_MAX_MSG_SIZE. If the data is too long to pass atomically through the underlying protocol the error WSAEMSGSIZE is returned, and no data is transmitted.

Note that the successful completion of a send does not indicate that the data was successfully delivered.

If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in a nonblocking I/O mode. On nonblocking stream-oriented sockets, the number of bytes written can be between 1 and the requested length, depending on buffer availability on both the local and foreign hosts. The select, WSAAsyncSelect or WSAEventSelect call can be used to determine when it is possible to send more data.

Calling send with a len of zero is to be treated by implementations as successful. In this case, send can return zero as a valid return value. For message-oriented sockets, a zero-length transport datagram is sent.

Flags can be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by or-ing any of the following values:

Value	Meaning
MSG_DONTROUTE	Specifies that the data should not be subject to routing. A Windows Sockets service provider can choose to ignore this flag.
MSG_OOB	Send out-of-band data (stream-style socket such as SOCK_STREAM only. Also see Out-Of-Band data for a discussion of this topic).
Return Values

If no error occurs, send returns the total number of bytes sent. (Note that this can be less than the number indicated by len.) Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEACCES	The requested address is a broadcast address, but the appropriate flag was not set.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEFAULT	The buf argument is not totally contained in a valid part of the user address space.
WSAENETRESET	The connection has been broken due to the remote host resetting.
WSAENOBUFS	No buffer space is available.
WSAENOTCONN	The socket is not connected.
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	MSG_OOB was specified, but the socket is not stream style such as type SOCK_STREAM, out-of-band data is not supported in the communication domain associated with this socket, or the socket is unidirectional and supports only receive operations.
WSAESHUTDOWN	The socket has been shut down; it is not possible to send on a socket after shutdown has been invoked with how set to SD_SEND or SD_BOTH.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the requested operation would block.
WSAEMSGSIZE	The socket is message oriented, and the message is larger than the maximum supported by the underlying transport.
WSAEHOSTUNREACH	The remote host cannot be reached from this host at this time.
WSAEINVAL	The socket has not been bound with bind, or an unknown flag was specified, or MSG_OOB was specified for a socket with SO_OOBINLINE enabled.
WSAECONNABORTED	The virtual circuit was terminated due to a time-out or other failure. The application should close the socket as it is no longer usable.
WSAECONNRESET	The virtual circuit was reset by the remote side executing a “hard” or “abortive” close. For UPD sockets, the remote host was unable to deliver a previously sent UDP datagram and responded with a "Port Unreachable" ICMP packet. The application should close the socket as it is no longer usable.
WSAETIMEDOUT	The connection has been dropped, because of a network failure or because the system on the other end went down without notice.
See Also

recv, recvfrom, select, sendto, socket, WSAAsyncSelect, WSAEventSelect


sendto

The Windows Sockets sendto function sends data to a specific destination.

int sendto (

SOCKET s,
const char FAR * buf,
int len,
int flags,
const struct sockaddr FAR * to,
int tolen
);
Parameters

s

[in] A descriptor identifying a socket.

buf

[in] A buffer containing the data to be transmitted.

len

[in] The length of the data in buf.

flags

[in] Specifies the way in which the call is made.

to

[in] An optional pointer to the address of the target socket.

tolen

[in] The size of the address in to.

Remarks

sendto is used to write outgoing data on a socket. For message-oriented sockets, care must be taken not to exceed the maximum packet size of the underlying subnets, which can be obtained by getting the value of socket option SO_MAX_MSG_SIZE. If the data is too long to pass atomically through the underlying protocol the error WSAEMSGSIZE is returned, and no data is transmitted.

The to parameter can be any valid address in the socket's address family, including a broadcast or any multicast address. To send to a broadcast address, an application must have setsockopt SO_BROADCAST enabled. Otherwise, sendto will fail with the error code WSAEACCES. For TCP/IP, an application can send to any multicast address (without becoming a group member).

If the socket is unbound, unique values are assigned to the local association by the system, and the socket is marked as bound. An application can use getsockname to determine the local socket name in this case.

Note that the successful completion of a sendto does not indicate that the data was successfully delivered.

sendto is normally used on a connectionless socket to send a datagram to a specific peer socket identified by the to parameter. Even if the connectionless socket has been previously connected to a specific address, to overrides the destination address for that particular datagram only. On a connection-oriented socket, the to and tolen parameters are ignored; in this case, the sendto is equivalent to send.

For sockets using IP:

To send a broadcast (on a SOCK_DGRAM only), the address in the to parameter should be constructed using the special IP address INADDR_BROADCAST (defined in WINSOCK2.H) together with the intended port number. It is generally inadvisable for a broadcast datagram to exceed the size at which fragmentation can occur, which implies that the data portion of the datagram (excluding headers) should not exceed 512 bytes.

If no buffer space is available within the transport system to hold the data to be transmitted, sendto will block unless the socket has been placed in a nonblocking I/O mode. On nonblocking stream-oriented sockets, the number of bytes written can be between 1 and the requested length, depending on buffer availability on both the local and foreign hosts. The select, WSAAsyncSelect or WSAEventSelect call can be used to determine when it is possible to send more data.

Calling sendto with a len of zero is legal and, in this case, sendto will return zero as a valid return value. For message-oriented sockets, a zero-length transport datagram is sent.

Flags can be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by or-ing any of the following values:

Value	Meaning
MSG_DONTROUTE	Specifies that the data should not be subject to routing. A Windows Sockets service provider can choose to ignore this flag.
MSG_OOB	Send out-of-band data (stream-style socket such as SOCK_STREAM only. Also see Out-Of-Band data for a discussion of this topic.)
Return Values

If no error occurs, sendto returns the total number of bytes sent. (Note that this can be less than the number indicated by len.) Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEACCES	The requested address is a broadcast address, but the appropriate flag was not set.
WSAEINVAL	An unknown flag was specified, or MSG_OOB was specified for a socket with SO_OOBINLINE enabled.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEFAULT	The buf or to parameters are not part of the user address space, or the tolen argument is too small.
WSAENETRESET	The connection has been broken due to the remote host resetting.
WSAENOBUFS	No buffer space is available.
WSAENOTCONN	The socket is not connected (connection-oriented sockets only)
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	MSG_OOB was specified, but the socket is not stream style such as type SOCK_STREAM, out-of-band data is not supported in the communication domain associated with this socket, or the socket is unidirectional and supports only receive operations.
WSAESHUTDOWN	The socket has been shut down; it is not possible to sendto on a socket after shutdown has been invoked with how set to SD_SEND or SD_BOTH.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the requested operation would block.
WSAEMSGSIZE	The socket is message oriented, and the message is larger than the maximum supported by the underlying transport.
WSAEHOSTUNREACH	The remote host cannot be reached from this host at this time.
WSAECONNABORTED	The virtual circuit was terminated due to a time-out or other failure. The application should close the socket as it is no longer usable.
WSAECONNRESET	The virtual circuit was reset by the remote side executing a “hard” or “abortive” close. For UPD sockets, the remote host was unable to deliver a previously sent UDP datagram and responded with a "Port Unreachable" ICMP packet. The application should close the socket as it is no longer usable.
WSAEADDRNOTAVAIL	The specified address is not available from the local machine.
WSAEAFNOSUPPORT	Addresses in the specified family cannot be used with this socket.
WSAEDESTADDRREQ	A destination address is required.
WSAENETUNREACH	The network cannot be reached from this host at this time.
WSAETIMEDOUT	The connection has been dropped, because of a network failure or because the system on the other end went down without notice.
See Also

recv, recvfrom, select, send, socket, WSAAsyncSelect, WSAEventSelect


SetService

Important  The SetService function is obsolete. For the convenience of Windows Sockets 1.1 developers, the reference material is below.

In Windows Sockets 2, this functionality is realized with the functions detailed in Protocol-Independent Name Resolution.

The SetService function registers or deregisters a network service within

one or more name spaces. The function can also add or remove a network service type within one or more name spaces.

INT SetService(

DWORD dwNameSpace,	// specifies name space(s) to operate within
DWORD dwOperation,	// specifies operation to perform
DWORD dwFlags,	// set of bit flags that modify function operation
LPSERVICE_INFO lpServiceInfo,	// points to structure containing service information
LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,	// reserved for future use, must be NULL
LPDWORD lpdwStatusFlags	// points to set of status bit flags
);
Parameters

dwNameSpace

Specifies the name space, or a set of default name spaces, within which the function will operate.

Use one of the following constants to specify a name space:

Value	Name Space
NS_DEFAULT	A set of default name spaces. The function queries each name space within this set. The set of default name spaces typically includes all the name spaces installed on the system. System administrators, however, can exclude particular name spaces from the set. NS_DEFAULT is the value that most applications should use for dwNameSpace.
NS_DNS	The Domain Name System used in the Internet to resolve the name of the host.
NS_NDS	The NetWare 4 provider.
NS_NETBT	The NetBIOS over TCP/IP layer. All Windows NT and Windows 95 systems register their computer names with NetBIOS. This name space is used to convert a computer name to an IP address that uses this registration.
NS_SAP	The NetWare Service Advertising Protocol. This can access the Netware bindery, if appropriate. NS_SAP is a dynamic name space that enables the registration of services.
NS_TCPIP_HOSTS	Lookup value in the <systemroot>\system32\drivers\etc\posts file.
NS_TCPIP_LOCAL	Local TCP/IP name resolution mechanisms, including comparisons against the local host name and lookup value in the cache of host to IP address mappings.
dwOperation

Specifies the operation that the function will perform. Use one of the following values to specify an operation:

Value	Meaning
SERVICE_REGISTER	Register the network service with the name space. This operation may be used with the SERVICE_FLAG_DEFER and SERVICE_FLAG_HARD bit flags.
SERVICE_DEREGISTER	Deregister the network service from the name space. This operation can be used with the SERVICE_FLAG_DEFER and SERVICE_FLAG_HARD bit flags.
SERVICE_FLUSH	Perform any operation that was called with the SERVICE_FLAG_DEFER bit flag set to one.
SERVICE_ADD_TYPE	Add a service type to the name space.  For this operation, use the ServiceSpecificInfo member of the SERVICE_INFO structure pointed to by lpServiceInfo to pass a SERVICE_TYPE_INFO_ABS structure. You must also set the ServiceType member of the SERVICE_INFO structure. Other SERVICE_INFO members are ignored.
SERVICE_DELETE_TYPE	Remove a service type, added by a previous call specifying the SERVICE_ADD_TYPE operation, from the name space.
dwFlags

A set of bit flags that modify the function’s operation. You can set one or more of the following bit flags:

Value	Name Space
SERVICE_FLAG_DEFER	This bit flag is valid only if the operation is SERVICE_REGISTER or SERVICE_DEREGISTER. If this bit flag is one, and it is valid, the name-space provider should defer the registration or deregistration operation until a SERVICE_FLUSH operation is requested.
SERVICE_FLAG_HARD	This bit flag is valid only if the operation is SERVICE_REGISTER or SERVICE_DEREGISTER. If this bit flag is one, and it is valid, the name-space provider updates any relevant persistent store information when the operation is performed.  For example: If the operation involves deregistration in a name space that uses a persistent store, the name-space provider would remove the relevant persistent store information.
lpService_Info

Points to a SERVICE_INFO structure that contains information about the network service or service type.

lpServiceAsyncInfo

This parameter is reserved for future use. It must be set to NULL.

lpdwStatusFlags

A set of bit flags that receive function status information. The following bit flag is defined:

Value	Meaning
SET_SERVICE_PARTIAL_SUCCESS	One or more name-space providers were unable to successfully perform the requested operation.
Return Values

If the function succeeds, the return value is not SOCKET_ERROR.

If the function fails, the return value is SOCKET_ERROR. To get extended error information, call GetLastError. GetLastError may return the following extended error value:

Value	Meaning
ERROR_ALREADY_REGISTERED	The function tried to register a service that was already registered.
See Also

GetService, SERVICE_INFO, SERVICE_TYPE_INFO_ABS


setsockopt

The Windows Sockets setsockopt function sets a socket option.

int setsockopt (

SOCKET s,
int level,
int optname,
const char FAR * optval,
int optlen
);
Parameters

s

[in] A descriptor identifying a socket.

level

[in] The level at which the option is defined; the supported levels include SOL_SOCKET and IPPROTO_TCP. (See annex for more protocol-specific levels.)

optname

[in] The socket option for which the value is to be set.

optval

[in] A pointer to the buffer in which the value for the requested option is supplied.

optlen

[in] The size of the optval buffer.

Remarks

setsockopt sets the current value for a socket option associated with a socket of any type, in any state. Although options can exist at multiple protocol levels, they are always present at the uppermost "socket'' level. Options affect socket operations, such as whether expedited data is received in the normal data stream, whether broadcast messages can be sent on the socket.

There are two types of socket options: Boolean options that enable or disable a feature or behavior, and options which require an integer value or structure. To enable a Boolean option, optval points to a nonzero integer. To disable the option optval points to an integer equal to zero. optlen should be equal to sizeof(int) for Boolean options. For other options, optval points to the an integer or structure that contains the desired value for the option, and optlen is the length of the integer or structure.

The following options are supported for setsockopt. The Type identifies the type of data addressed by optval.

level = SOL_SOCKET

Value	Type	Meaning
SO_BROADCAST	BOOL	Allow transmission of broadcast messages on the socket.
SO_DEBUG	BOOL	Record debugging information.
SO_DONTLINGER	BOOL	Do not block close waiting for unsent data to be sent. Setting this option is equivalent to setting SO_LINGER with l_onoff set to zero.
SO_DONTROUTE	BOOL	Do not route: send directly to interface.
SO_GROUP_PRIORITY	int	Specify the relative priority to be established for sockets that are part of a socket group.
SO_KEEPALIVE	BOOL	Send keepalives
SO_LINGER	struct linger	Linger on close if unsent data is present
SO_OOBINLINE	BOOL	Receive out-of-band data in the normal data stream. (See section Out-Of-Band data for a discussion of this topic.)
SO_RCVBUF	int	Specify buffer size for receives
SO_REUSEADDR	BOOL	Allow the socket to be bound to an address which is already in use. (See bind.)
SO_SNDBUF	int	Specify buffer size for sends.
PVD_CONFIG	Service Provider Dependent	This object stores the configuration information for the service provider associated with socket s. The exact format of this data structure is service provider specific.
level = IPPROTO_TCP1

TCP_NODELAY	BOOL	Disables the Nagle algorithm for send coalescing.
1 included for backward compatibility with Windows Sockets 1.1
BSD options not supported for setsockopt are:

Value	Type	Meaning
SO_ACCEPTCONN	BOOL	Socket is listening
SO_RCVLOWAT	int	Receive low water mark
SO_RCVTIMEO	int	Receive time-out
SO_SNDLOWAT	int	Send low water mark
SO_SNDTIMEO	int	Send time-out
SO_TYPE	int	Type of the socket
SO_DEBUG

Windows Sockets service providers are encouraged (but not required) to supply output debug information if the SO_DEBUG option is set by an application. The mechanism for generating the debug information and the form it takes are beyond the scope of this specification.

SO_GROUP_PRIORITY

Group priority indicates the relative priority of the specified socket relative to other sockets within the socket group. Values are non-negative integers, with zero corresponding to the highest priority. Priority values represent a hint to the underlying service provider about how potentially scarce resources should be allocated. For example, whenever two or more sockets are both ready to transmit data, the highest priority socket (lowest value for SO_GROUP_PRIORITY) should be serviced first, with the remainder serviced in turn according to their relative priorities.

The WSAENOPROTOOPT error is indicated for nongroup sockets or for service providers which do not support group sockets.

SO_KEEPALIVE

An application can request that a TCP/IP provider enable the use of "keep-alive" packets on TCP connections by turning on the SO_KEEPALIVE socket option. A Windows Sockets provider need not support the use of keep-alives: if it does, the precise semantics are implementation-specific but should conform to section 4.2.3.6 of RFC 1122: Requirements for Internet Hosts  Communication Layers. If a connection is dropped as the result of "keep-alives" the error code WSAENETRESET is returned to any calls in progress on the socket, and any subsequent calls will fail with WSAENOTCONN.

SO_LINGER

SO_LINGER controls the action taken when unsent data is queued on a socket and a closesocket is performed. See closesocket for a description of the way in which the SO_LINGER settings affect the semantics of closesocket. The application sets the desired behavior by creating a struct linger (pointed to by the optval argument) with the following elements:

struct linger {

    u_short    l_onoff;

    u_short    l_linger;

}

To enable SO_LINGER, the application should set l_onoff to a nonzero value, set l_linger to zero or the desired time-out (in seconds), and call setsockopt. To enable SO_DONTLINGER (that is, disable SO_LINGER) l_onoff should be set to zero and setsockopt should be called. Note that enabling SO_LINGER with a nonzero time-out on a nonblocking socket is not recommended.

Enabling SO_LINGER also disables SO_DONTLINGER, and vice versa. Note that if SO_DONTLINGER is DISABLED (that is, SO_LINGER is ENABLED) then no time-out value is specified. In this case, the time-out used is implementation dependent. If a previous time-out has been established for a socket (by enabling SO_LINGER), then this time-out value should be reinstated by the service provider.

SO_REUSEADDR

By default, a socket cannot be bound (see bind) to a local address which is already in use. On occasion, however, it may be necessary to "re-use" an address in this way. Since every connection is uniquely identified by the combination of local and remote addresses, there is no problem with having two sockets bound to the same local address as long as the remote addresses are different. To inform the Windows Sockets provider that a bind on a socket should not be disallowed because the desired address is already in use by another socket, the application should set the SO_REUSEADDR socket option for the socket before issuing the bind. Note that the option is interpreted only at the time of the bind: it is therefore unnecessary (but harmless) to set the option on a socket which is not to be bound to an existing address, and setting or resetting the option after the bind has no effect on this or any other socket.

SO_RCVBUF

SO_SNDBUF

When a Windows Sockets implementation supports the SO_RCVBUF and SO_SNDBUF options, an application can request different buffer sizes (larger or smaller). The call to setsockopt can succeed, although the implementation did not provide the whole amount requested. An application must call getsockopt with the same option to check the buffer size actually provided.

PVD_CONFIG

This object stores the configuration information for the service provider associated with socket s. The exact format of this data structure is service provider specific.

TCP_NODELAY

The TCP_NODELAY option is specific to TCP/IP service providers. Enabling the TCP_NODELAY option disables the TCP Nagle Algorithm (and vice versa). The Nagle algorithm (described in RFC 896) is very effective in reducing the number of small packets sent by a host by essentially buffering send data if there is unacknowledged data already “in flight” or until a full-size packet can be sent. It is highly recommended that TCP/IP service providers enable the Nagle Algorithm by default, and for the vast majority of application protocols the Nagle Algorithm can deliver significant performance enhancements. However, for some applications this algorithm can impede performance, and TCP_NODELAY can be used to turn it off. These are applications where many small messages are sent, which need to be received by the peer with the time delays between the messages maintained. Application writers should not set TCP_NODELAY unless the impact of doing so is well-understood and desired, since setting TCP_NODELAY can have a significant negative impact of network and application performance.

Return Values

If no error occurs, setsockopt returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	optval is not in a valid part of the process address space or optlen argument is too small.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINVAL	level is not valid, or the information in optval is not valid.
WSAENETRESET	Connection has timed out when SO_KEEPALIVE is set.
WSAENOPROTOOPT	The option is unknown or unsupported for the specified provider.
WSAENOTCONN	Connection has been reset when SO_KEEPALIVE is set.
WSAENOTSOCK	The descriptor is not a socket.
See Also

bind, getsockopt, ioctlsocket, socket, WSAAsyncSelect, WSAEventSelect


shutdown

The Windows Sockets shutdown function disables sends and/or receives on a socket.

int shutdown (

SOCKET s,
int how
);
Parameters

s

[in] A descriptor identifying a socket.

how

[in] A flag that describes what types of operation will no longer be allowed.

Remarks

shutdown is used on all types of sockets to disable reception, transmission, or both.

If how is SD_RECEIVE, subsequent receives on the socket will be disallowed. This has no effect on the lower protocol layers. For TCP sockets, if there is still data queued on the socket waiting to be received, or data arrives subsequently, the connection is reset, since the data cannot be delivered to the user. For UDP sockets, incoming datagrams are accepted and queued. In no case will an ICMP error packet be generated.

If how is SD_SEND, subsequent sends are disallowed. For TCP sockets, a FIN will be sent.

Setting how to SD_BOTH disables both sends and receives as described above.

Note that shutdown does not close the socket, and resources attached to the socket will not be freed until closesocket is invoked.

To assure that all data is sent and received on a connected socket before it is closed, an application should use shutdown to close connection before calling closesocket. For example, to initiate a graceful disconnect, an application could:

1.	call WSAAsyncSelect to register for FD_CLOSE notification,

2.	call shutdown with how=SD_SEND,

3.	when FD_CLOSE received, call recv until zero returned, or SOCKET_ERROR, and

4.	call closesocket,

Comments

shutdown does not block regardless of the SO_LINGER setting on the socket.

An application should not rely on being able to re-use a socket after it has been shut down. In particular, a Windows Sockets provider is not required to support the use of connect on such a socket.

Return Values

If no error occurs, shutdown returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINVAL	how is not valid, or is not consistent with the socket type, for example, SD_SEND is used with a UNI_RECV socket type.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAENOTCONN	The socket is not connected (connection-oriented sockets only).
WSAENOTSOCK	The descriptor is not a socket.
See Also

connect, socket


socket

The Windows Sockets socket function creates a socket which is bound to a specific service provider.

SOCKET socket (

int af,
int type,
int protocol
);
Parameters

af

[in] An address family specification.

type

[in] A type specification for the new socket.

protocol

[in] A particular protocol to be used with the socket which is specific to the indicated address family.

Remarks

The socket function causes a socket descriptor and any related resources to be allocated and bound to a specific transport service provider. Windows Sockets will utilize the first available service provider that supports the requested combination of address family, socket type and protocol parameters. Note that the socket created will have the overlapped attribute. Sockets without the overlapped attribute can only be created by using WSASocket.

Note  The manifest constant AF_UNSPEC continues to be defined in the header file but its use is strongly discouraged, as this can cause ambiguity in interpreting the value of the protocol parameter.

The following are the only two type specifications supported for Windows Sockets 1.1:

Type	Explanation
SOCK_STREAM	Provides sequenced, reliable, two-way, connection-based byte streams with an out-of-band data transmission mechanism. Uses TCP for the Internet address family.
SOCK_DGRAM	Supports datagrams, which are connectionless, unreliable buffers of a fixed (typically small) maximum length. Uses UDP for the Internet address family.
In Windows Sockets 2, many new socket types will be introduced. However, since an application can dynamically discover the attributes of each available transport protocol through the WSAEnumProtocols function, the various socket types need not be called out in the API specification. Socket type definitions will appear in WINSOCK2.H which will be periodically updated as new socket types, address families and protocols are defined.

Connection-oriented sockets such as SOCK_STREAM provide full-duplex connections, and must be in a connected state before any data can be sent or received on it. A connection to another socket is created with a connect call. Once connected, data can be transferred using send and recv calls. When a session has been completed, a closesocket must be performed.

The communications protocols used to implement a reliable, connection-oriented socket ensure that data is not lost or duplicated. If data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, the connection is considered broken and subsequent calls will fail with the error code set to WSAETIMEDOUT.

Connectionless, message-oriented sockets allow sending and receiving of datagrams to and from arbitrary peers using sendto and recvfrom. If such a socket is connected to a specific peer, datagrams can be sent to that peer using send and can be received only from this peer using recv.

Support for sockets with type RAW is not required, but service providers are encourage to support raw sockets whenever it makes sense to do so.

Return Values

If no error occurs, socket returns a descriptor referencing the new socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem or the associated service provider has failed.
WSAEAFNOSUPPORT	The specified address family is not supported.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEMFILE	No more socket descriptors are available.
WSAENOBUFS	No buffer space is available. The socket cannot be created.
WSAEPROTONOSUPPORT	The specified protocol is not supported.
WSAEPROTOTYPE	The specified protocol is the wrong type for this socket.
WSAESOCKTNOSUPPORT	The specified socket type is not supported in this address family.
See Also

accept, bind, connect, getsockname, getsockopt, ioctlsocket, listen, recv, recvfrom, select, send, sendto, setsockopt, shutdown, WSASocket


TransmitFile

Notice  This function is a Microsoft-specific extension to the Windows Sockets specification. For more information, see Microsoft Extensions and Windows Sockets 2.

The Windows Sockets TransmitFile function transmits file data over a connected socket handle. This function uses the operating system’s cache manager to retrieve the file data, and provides high-performance file data transfer over sockets.

BOOL TransmitFile(

SOCKET hSocket,
HANDLE hFile,
DWORD nNumberOfBytesToWrite,
DWORD nNumberOfBytesPerSend,
LPOVERLAPPED lpOverlapped,
LPTRANSMIT_FILE_BUFFERS lpTransmitBuffers,
DWORD dwFlags
);
Parameters

hSocket

A handle to a connected socket. The function will transmit the file data over this socket.

The socket specified by hSocket must be a connection-oriented socket.

Sockets of type SOCK_STREAM, SOCK_SEQPACKET, or SOCK_RDM are connection-oriented sockets. The TransmitFile function does not support datagram sockets.

hFile

A handle to an open file. The function transmits this file’s data. The operating system reads the file data sequentially. You can improve caching performance by opening the handle with the FILE_FLAG_SEQUENTIAL_SCAN.

nNumberOfBytesToWrite

The number of bytes to transmit. The function completes when it has sent this many bytes, or if an error occurs.

Set this parameter to zero to transmit the entire file.

nNumberOfBytesPerSend

The size of each block of data sent per send operation. This specification is for use by the sockets layer of the operating system.

Set this parameter to zero to have the sockets layer select a default send size.

This parameter is useful for message protocols that have limitations on the size of individual send requests.

lpOverlapped

Pointer to an OVERLAPPED structure. If the socket handle has been opened as overlapped, specify this parameter in order to achieve an overlapped (aysnchronous) I/O operation. By default, socket handles are opened as overlapped.

You can use lpOverlapped to specify an offset within the file at which to start the file data transfer by setting the Offset and OffsetHigh member of the OVERLAPPED structure. If lpOverlapped is NULL, the transmission of data always starts at the current byte offset in the file.

When lpOverlapped is not NULL, the overlapped I/O might not finish before TransmitFile returns. In that case, the TransmitFile function returns FALSE, and GetLastError returns ERROR_IO_PENDING. This lets the caller continue processing while the file transmission operation completes. The operating system will set the event specified by the hEvent member of the OVERLAPPED structure, or the socket specified by hSocket, to the signaled state upon completion of the data transmission request.

lpTransmitBuffers

Pointer to a TRANSMIT_FILE_BUFFERS data structure that contains pointers to data to send before and after the file data is sent. Set this parameter to NULL if you only want to transmit the file data.

dwFlags

An attribute that has three settings:

TF_DISCONNECT

Start a transport-level disconnect after all the file data has been queued for transmission.

TF_REUSE_SOCKET

Prepare the socket handle to be reused. When the TransmitFile request completes, the socket handle can be passed to the AcceptEx function. It is only valid if TF_DISCONNECT is also specified.

TF_WRITE_BEHIND

Complete the TransmitFile request immediately, without pending. If this flag is specified and TransmitFile succeeds, then the data has been accepted by the system but not necessarily acknowledged by the remote end. If TransmitFile returns TRUE, there will be no completion port indication for the I/O. Do not use this setting with the other two settings.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. The function returns FALSE if an overlapped I/O operation is not complete before TransmitFile returns. In that case, GetLastError returns ERROR_IO_PENDING.

Remarks

The Windows NT Server optimizes the TransmitFile function for high performance. The Windows NT Workstation optimizes the function for minimum memory and resource utilization. Expect better performance results when using TransmitFile on Windows NT Server.


WSAAccept

The Windows Sockets WSAAccept function conditionally accepts a connection based on the return value of a condition function, and optionally creates and/or joins a socket group.

SOCKET WSAAccept (

SOCKET s,
struct sockaddr FAR * addr,
LPINT addrlen,
LPCONDITIONPROC lpfnCondition,
DWORD dwCallbackData
);
Parameters

s

[in] A descriptor identifying a socket which is listening for connections after a listen.

addr

[out] An optional pointer to a buffer which receives the address of the connecting entity, as known to the communications layer. The exact format of the addr argument is determined by the address family established when the socket was created.

addrlen

[in/out] An optional pointer to an integer which contains the length of the address addr.

lpfnCondition

[in] The procedure instance address of the optional, application-supplied condition function which will make an accept/reject decision based on the caller information passed in as parameters, and optionally create and/or join a socket group by assigning an appropriate value to the result parameter g of this function.

dwCallbackData

[in] The callback data passed back to the application as a condition function parameter. This parameter is not interpreted by Windows Sockets.

Remarks

This routine extracts the first connection on the queue of pending connections on s, and checks it against the condition function, provided the condition function is specified (that is, not NULL). If the condition function returns CF_ACCEPT, this routine creates a new socket and performs any socket grouping as indicated by the result parameter g in the condition function. The newly created socket has the same properties as s including asynchronous events registered with WSAAsyncSelect or with WSAEventSelect, but not including the listening socket’s group ID, if any. If the condition function returns CF_REJECT, this routine rejects the connection request. The condition function runs in the same thread as this routine does, and should return as soon as possible. If the decision cannot be made immediately, the condition function should return CF_DEFER to indicate that no decision has been made, and no action about this connection request should be taken by the service provider. When the application is ready to take action on the connection request, it will invoke WSAAccept again and return either CF_ACCEPT or CF_REJECT as a return value from the condition function.

For sockets which remain in the (default) blocking mode, if no pending connections are present on the queue, WSAAccept blocks the caller until a connection is present. For sockets in a nonblocking mode, if this function is called when no pending connections are present on the queue, WSAAccept returns an error as described below. The accepted socket cannot be used to accept more connections. The original socket remains open.

The argument addr is a result parameter that is filled in with the address of the connecting entity, as known to the communications layer. The exact format of the addr parameter is determined by the address family in which the communication is occurring. The addrlen is a value-result parameter; it should initially contain the amount of space pointed to by addr. On return, it will contain the actual length (in bytes) of the address returned. This call is used with connection-oriented socket types such as SOCK_STREAM. If addr and/or addrlen are equal to NULL, then no information about the remote address of the accepted socket is returned. Otherwise, these two parameters will be filled in regardless of whether the condition function is specified or what it returns.

The prototype of the condition function is as follows:

int CALLBACK ConditionFunc(
 IN LPWSABUF lpCallerId,
 IN LPWSABUF lpCallerData,
 IN OUT LPQOS lpSQOS,
 IN OUT LPQOS lpGQOS,
 IN LPWSABUF lpCalleeId,
 OUT LPWSABUF lpCalleeData,
 OUT GROUP FAR * g,
 IN DWORD dwCallbackData
);

ConditionFunc is a placeholder for the application-supplied function name. In 16-bit Windows environments, it is invoked in the same thread as WSAAccept, thus no other Windows Sockets functions can be called except WSAIsBlocking and WSACancelBlockingCall. The actual condition function must reside in a DLL or application module and be exported in the module definition file. You must use MakeProcInstance to get a procedure-instance address for the callback function.

The lpCallerId and lpCallerData are value parameters which contain the address of the connecting entity and any user data that was sent along with the connection request, respectively. If no caller ID or caller data is available, the corresponding parameters will be NULL.

lpSQOS references the flow specifications for socket s specified by the caller, one for each direction, followed by any additional provider-specific parameters. The sending or receiving flow specification values will be ignored as appropriate for any unidirectional sockets. A NULL value for lpSQOS indicates no caller supplied QOS. QOS information can be returned if a QOS negotiation is to occur.

lpGQOS references the flow specifications for the socket group the caller is to create, one for each direction, followed by any additional provider-specific parameters. A NULL value for lpGQOS indicates no caller-supplied group QOS. QOS information can be returned if a QOS negotiation is to occur.

The lpCalleeId is a value parameter which contains the local address of the connected entity. The lpCalleeData is a result parameter used by the condition function to supply user data back to the connecting entity. lpCalleeData->len initially contains the length of the buffer allocated by the service provider and pointed to by lpCalleeData->buf. A value of zero means passing user data back to the caller is not supported. The condition function should copy up to lpCalleeData->len bytes of data into lpCalleeData->buf, and then update lpCalleeData->len to indicate the actual number of bytes transferred. If no user data is to be passed back to the caller, the condition function should set lpCalleeData->len to zero. The format of all address and user data is specific to the address family to which the socket belongs.

The result parameter g is assigned within the condition function to indicate the following actions:

1.	if &g is an existing socket group ID, add s to this group, provided all the requirements set by this group are met; or

2.	if &g = SG_UNCONSTRAINED_GROUP, create an unconstrained socket group and have s as the first member; or

3.	if &g = SG_CONSTRAINED_GROUP, create a constrained socket group and have s as the first member; or

4.	if &g = zero, no group operation is performed.

For unconstrained groups, any set of sockets can be grouped together as long as they are supported by a single service provider. A constrained socket group can consist only of connection-oriented sockets, and requires that connections on all grouped sockets be to the same address on the same host. For newly created socket groups, the new group ID can be retrieved by using getsockopt with option SO_GROUP_ID, if this operation completes successfully. A socket group and its associated ID remain valid until the last socket belonging to this socket group is closed. Socket group IDs are unique across all processes for a given service provider.

Return Values

If no error occurs, WSAAccept returns a value of type SOCKET which is a descriptor for the accepted socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code can be retrieved by calling WSAGetLastError.

The integer referred to by addrlen initially contains the amount of space pointed to by addr. On return it will contain the actual length in bytes of the address returned.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAECONNREFUSED	The connection request was forcefully rejected as indicated in the return value of the condition function (CF_REJECT).
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	The addrlen argument is too small or the lpfnCondition is not part of the user address space.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress.
WSAEINVAL	listen was not invoked prior to WSAAccept, parameter g specified in the condition function is not a valid value, the source address of the incoming connection request is not consistent with that of the constrained group the parameter g is referring to, the return value of the condition function is not a valid one, or any case where the specified socket is in an invalid state.
WSAEMFILE	The queue is nonempty upon entry to WSAAccept and there are no socket descriptors available.
WSAENOBUFS	No buffer space is available.
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	The referenced socket is not a type that supports connection-oriented service.
WSATRY_AGAIN	The acceptance of the connection request was deferred as indicated in the return value of the condition function (CF_DEFER).
WSAEWOULDBLOCK	The socket is marked as nonblocking and no connections are present to be accepted.
WSAEACCES	The connection request that was offered has timed out or been withdrawn.
See Also

accept, bind, connect, getsockopt, listen, select, socket, WSAAsyncSelect, WSAConnect


WSAAddressToString

The Windows Sockets WSAAddressToString function converts all components of a SOCKADDR structure into a human-readable string representation of the address.

This is intended to be used mainly for display purposes. If the caller wants the translation to be done by a particular provider, it should supply the corresponding WSAPROTOCOL_INFO structure in the lpProtocolInfo parameter.

INT WSAAddressToString(

LPSOCKADDR lpsaAddress,
DWORD dwAddressLength,
LPWSAPROTOCOL_INFO lpProtocolInfo,
OUT LPTSTR lpszAddressString,
OUT LPDWORD lpdwAddressStringLength
);
Parameters

lpsaAddress

[in] Points to a SOCKADDR structure to translate into a string.

dwAddressLength

[in] The length of the Address SOCKADDR.

lpProtocolInfo

[in] (Optional) The WSAPROTOCOL_INFO structure for a particular provider.

lpszAddressString

[in] A buffer which receives the human-readable address string.

lpdwAddressStringLength

[in] On input, the length of the AddressString buffer. On output, returns the length ofthe string actually copied into the buffer.

Return Values

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number can be retrieved by calling WSAGetLastError.

Error Codes

WSAEFAULT	The specified AddressString buffer is too small. Pass in a larger buffer
WSAEINVAL	The specified address is not a valid socket address.


WSAAsyncGetHostByAddr

The Windows Sockets WSAAsyncGetHostByAddr function gets host information corresponding to an addressasynchronous version.

HANDLE WSAAsyncGetHostByAddr (

HWND hWnd,
unsigned int wMsg,
const char FAR * addr,
int len,
int type,
char FAR * buf,
int buflen
);
Parameters

hWnd

[in] The handle of the window which should receive a message when the asynchronous request completes.

wMsg

[in] The message to be received when the asynchronous request completes.

addr

[in] A pointer to the network address for the host. Host addresses are stored in network byte order.

len

[in] The length of the address.

type

[in] The type of the address.

buf

[out] A pointer to the data area to receive the hostent data. Note that this must be larger than the size of a hostent structure. This is because the data area supplied is used by Windows Sockets to contain not only a hostent structure but any and all of the data which is referenced by members of the hostent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.

buflen

[in] The size of data area buf above.

Remarks

This function is an asynchronous version of gethostbyaddr, and is used to retrieve host name and address information corresponding to a network address. Windows Sockets initiates the operation and returns to the caller immediately, passing back an opaque "asynchronous task handle" which the application can use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code can be any error as defined in WINSOCK2.H. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a hostent structure. To access the elements of this structure, the original buffer address should be cast to a hostent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it can reissue the WSAAsyncGetHostByAddr function call with a buffer large enough to receive all the desired information (that is, no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in WINSOCK2.H as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

Return Values

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.

If the operation was successfully initiated, WSAAsyncGetHostByAddr returns a nonzero value of type HANDLE which is the asynchronous task handle (not to be confused with a Windows HTASK) for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest. It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.

If the asynchronous operation could not be initiated, WSAAsyncGetHostByAddr returns a zero value, and a specific error number can be retrieved by calling WSAGetLastError.

Comments

The buffer supplied to this function is used by Windows Sockets to construct a structure together with the contents of data areas referenced by members of the same hostent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in WINSOCK2.H).

Error Codes

The following error codes can be set when an application window receives a message. As described above, they can be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

WSAENETDOWN	The network subsystem has failed.
WSAENOBUFS	Insufficient buffer space is available.
WSAEFAULT	addr or buf is not in a valid part of the process address space.
WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
WSATRY_AGAIN	Non-Authoritative Host not found, or SERVERFAIL.
WSANO_RECOVERY	Nonrecoverable errors, FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Valid name, no data record of requested type.
The following errors can occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
See Also

gethostbyaddr, hostent, WSACancelAsyncRequest


WSAAsyncGetHostByName

The Windows Sockets WSAAsyncGetHostByName function gets host information corresponding to a hostnameasynchronous version.

HANDLE WSAAsyncGetHostByName (

HWND hWnd,
unsigned int wMsg,
const char FAR * name,
char FAR * buf,
int buflen
);
Parameters

hWnd

[in] The handle of the window which should receive a message when the asynchronous request completes.

wMsg

[in] The message to be received when the asynchronous request completes.

name

[in] A pointer to the null terminated name of the host.

buf

[out] A pointer to the data area to receive the hostent data. Note that this must be larger than the size of a hostent structure. This is because the data area supplied is used by Windows Sockets to contain not only a hostent structure but any and all of the data which is referenced by members of the hostent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.

buflen

[in] The size of data area buf above.

Remarks

This function is an asynchronous version of gethostbyname, and is used to retrieve host name and address information corresponding to a hostname. Windows Sockets initiates the operation and returns to the caller immediately, passing back an opaque "asynchronous task handle" which the application can use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code can be any error as defined in WINSOCK2.H. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a hostent structure. To access the elements of this structure, the original buffer address should be cast to a hostent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it can reissue the WSAAsyncGetHostByName function call with a buffer large enough to receive all the desired information (that is, no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in WINSOCK2.H as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

WSAAsyncGetHostByName is guaranteed to resolve the string returned by a successful call to gethostname.

Return Values

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.

If the operation was successfully initiated, WSAAsyncGetHostByName returns a nonzero value of type HANDLE which is the asynchronous task handle (not to be confused with a Windows HTASK) for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest. It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.

If the asynchronous operation could not be initiated, WSAAsyncGetHostByName returns a zero value, and a specific error number can be retrieved by calling WSAGetLastError.

Comments

The buffer supplied to this function is used by Windows Sockets to construct a hostent structure together with the contents of data areas referenced by members of the same hostent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in WINSOCK2.H).

Error Codes

The following error codes can be set when an application window receives a message. As described above, they can be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

WSAENETDOWN	The network subsystem has failed.
WSAENOBUFS	Insufficient buffer space is available.
WSAEFAULT	name or buf is not in a valid part of the process address space.
WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
WSATRY_AGAIN	Non-Authoritative Host not found, or SERVERFAIL.
WSANO_RECOVERY	Nonrecoverable errors, FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Valid name, no data record of requested type.
The following errors can occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
See Also

gethostbyname, hostent, WSACancelAsyncRequest


WSAAsyncGetProtoByName

The Windows Sockets WSAAsyncGetProtoByName function gets protocol information corresponding to a protocol nameasynchronous version.

HANDLE WSAAsyncGetProtoByName (

HWND hWnd,
unsigned int wMsg,
const char FAR * name,
char FAR * buf,
int buflen
);
Parameters

hWnd

[in] The handle of the window which should receive a message when the asynchronous request completes.

wMsg

[in] The message to be received when the asynchronous request completes.

name

[in] A pointer to the null terminated protocol name to be resolved.

buf

[out] A pointer to the data area to receive the protoent data. Note that this must be larger than the size of a protoent structure. This is because the data area supplied is used by Windows Sockets to contain not only a protoent structure but any and all of the data which is referenced by members of the protoent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.

buflen

[out] The size of data area buf above.

Remarks

This function is an asynchronous version of getprotobyname, and is used to retrieve the protocol name and number corresponding to a protocol name. Windows Sockets initiates the operation and returns to the caller immediately, passing back an opaque "asynchronous task handle" which the application can use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code can be any error as defined in WINSOCK2.H. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a protoent structure. To access the elements of this structure, the original buffer address should be cast to a protoent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it can reissue the WSAAsyncGetProtoByName function call with a buffer large enough to receive all the desired information (that is, no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in WINSOCK2.H as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

Return Values

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.

If the operation was successfully initiated, WSAAsyncGetProtoByName returns a nonzero value of type HANDLE which is the asynchronous task handle for the request (not to be confused with a Windows HTASK). This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest. It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.

If the asynchronous operation could not be initiated, WSAAsyncGetProtoByName returns a zero value, and a specific error number can be retrieved by calling WSAGetLastError.

Comments

The buffer supplied to this function is used by Windows Sockets to construct a protoent structure together with the contents of data areas referenced by members of the same protoent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in WINSOCK2.H).

Error Codes

The following error codes can be set when an application window receives a message. As described above, they can be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

WSAENETDOWN	The network subsystem has failed.
WSAENOBUFS	Insufficient buffer space is available.
WSAEFAULT	name or buf is not in a valid part of the process address space.
WSAHOST_NOT_FOUND	Authoritative Answer Protocol not found.
WSATRY_AGAIN	Non-Authoritative Protocol not found, or server failure.
WSANO_RECOVERY	Nonrecoverable errors, the protocols database is not accessible.
WSANO_DATA	Valid name, no data record of requested type.
The following errors can occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
See Also

getprotobyname, WSACancelAsyncRequest


WSAAsyncGetProtoByNumber

The Windows Sockets WSAAsyncGetProtoByNumber function gets protocol information corresponding to a protocol numberasynchronous version.

HANDLE WSAAsyncGetProtoByNumber (

HWND hWnd,
unsigned int wMsg,
int number,
char FAR * buf,
int buflen
);
Parameters

hWnd

[in] The handle of the window which should receive a message when the asynchronous request completes.

wMsg

[in] The message to be received when the asynchronous request completes.

number

[in] The protocol number to be resolved, in host byte order.

buf

[out] A pointer to the data area to receive the protoent data. Note that this must be larger than the size of a protoent structure. This is because the data area supplied is used by Windows Sockets to contain not only a protoent structure but any and all of the data which is referenced by members of the protoent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.

buflen

[in] The size of data area buf above.

Remarks

This function is an asynchronous version of getprotobynumber, and is used to retrieve the protocol name and number corresponding to a protocol number. Windows Sockets initiates the operation and returns to the caller immediately, passing back an opaque "asynchronous task handle" which the application can use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code can be any error as defined in WINSOCK2.H. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a protoent structure. To access the elements of this structure, the original buffer address should be cast to a protoent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it can reissue the WSAAsyncGetProtoByNumber function call with a buffer large enough to receive all the desired information (that is, no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in WINSOCK2.H as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

Return Values

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.

If the operation was successfully initiated, WSAAsyncGetProtoByNumber returns a nonzero value of type HANDLE which is the asynchronous task handle for the request (not to be confused with a Windows HTASK). This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest. It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.

If the asynchronous operation could not be initiated, WSAAsyncGetProtoByNumber returns a zero value, and a specific error number can be retrieved by calling WSAGetLastError.

Comments

The buffer supplied to this function is used by Windows Sockets to construct a protoent structure together with the contents of data areas referenced by members of the same protoent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in WINSOCK2.H).

Error Codes

The following error codes can be set when an application window receives a message. As described above, they can be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

WSAENETDOWN	The network subsystem has failed.
WSAENOBUFS	Insufficient buffer space is available.
WSAEFAULT	buf is not in a valid part of the process address space.
WSAHOST_NOT_FOUND	Authoritative Answer Protocol not found.
WSATRY_AGAIN	Non-Authoritative Protocol not found, or server failure.
WSANO_RECOVERY	Nonrecoverable errors, the protocols database is not accessible.
WSANO_DATA	Valid name, no data record of requested type.
The following errors can occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
See Also

getprotobynumber, WSACancelAsyncRequest


WSAAsyncGetServByName

The Windows Sockets WSAAsyncGetServByName function gets service information corresponding to a service name and portasynchronous version.

HANDLE WSAAsyncGetServByName (

HWND hWnd,
unsigned int wMsg,
const char FAR * name,
const char FAR * proto,
char FAR * buf,
int buflen
);
Parameters

hWnd

[in] The handle of the window which should receive a message when the asynchronous request completes.

wMsg

[in] The message to be received when the asynchronous request completes.

name

[in] A pointer to a null terminated service name.

proto

[in] A pointer to a protocol name. This can be NULL, in which case WSAAsyncGetServByName will search for the first service entry for which s_name or one of the s_aliases matches the given name. Otherwise, WSAAsyncGetServByName matches both name and proto.

buf

[out] A pointer to the data area to receive the servent data. Note that this must be larger than the size of a servent structure. This is because the data area supplied is used by Windows Sockets to contain not only a servent structure but any and all of the data which is referenced by members of the servent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.

buflen

[in] The size of data area buf above.

Remarks

This function is an asynchronous version of getservbyname, and is used to retrieve service information corresponding to a service name. Windows Sockets initiates the operation and returns to the caller immediately, passing back an opaque "asynchronous task handle" which the application can use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code can be any error as defined in WINSOCK2.H. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a servent structure. To access the elements of this structure, the original buffer address should be cast to a servent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it can reissue the WSAAsyncGetServByName function call with a buffer large enough to receive all the desired information (that is, no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in WINSOCK2.H as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

Return Values

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.

If the operation was successfully initiated, WSAAsyncGetServByName returns a nonzero value of type HANDLE which is the asynchronous task handle for the request (not to be confused with a Windows HTASK). This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest. It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.

If the asynchronous operation could not be initiated, WSAAsyncServByName returns a zero value, and a specific error number can be retrieved by calling WSAGetLastError.

Comments

The buffer supplied to this function is used by Windows Sockets to construct a servent structure together with the contents of data areas referenced by members of the same servent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in WINSOCK2.H).

Error Codes

The following error codes can be set when an application window receives a message. As described above, they can be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

WSAENETDOWN	The network subsystem has failed.
WSAENOBUFS	Insufficient buffer space is available.
WSAEFAULT	buf is not in a valid part of the process address space.
WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
WSATRY_AGAIN	Non-Authoritative Service not found, or server failure.
WSANO_RECOVERY	Nonrecoverable errors, the services database is not accessible.
WSANO_DATA	Valid name, no data record of requested type.
The following errors can occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
See Also

getservbyname, WSACancelAsyncRequest


WSAAsyncGetServByPort

The Windows Sockets WSAAsyncGetServByPort function gets service information corresponding to a port and protocolasynchronous version.

HANDLE WSAAsyncGetServByPort (

HWND hWnd,
unsigned int wMsg,
int port,
const char FAR * proto,
char FAR * buf,
int buflen
);
Parameters

hWnd

[in] The handle of the window which should receive a message when the asynchronous request completes.

wMsg

[in] The message to be received when the asynchronous request completes.

port

[in] The port for the service, in network byte order.

proto

[in] A pointer to a protocol name. This can be NULL, in which case WSAAsyncGetServByPort will search for the first service entry for which s_port match the given port. Otherwise, WSAAsyncGetServByPort matches both port and proto.

buf

[out] A pointer to the data area to receive the servent data. Note that this must be larger than the size of a servent structure. This is because the data area supplied is used by Windows Sockets to contain not only a servent structure but any and all of the data which is referenced by members of the servent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.

buflen

[in] The size of data area buf above.

Remarks

This function is an asynchronous version of getservbyport, and is used to retrieve service information corresponding to a port number. Windows Sockets initiates the operation and returns to the caller immediately, passing back an opaque "asynchronous task handle" which the application can use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code can be any error as defined in WINSOCK2.H. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a servent structure. To access the elements of this structure, the original buffer address should be cast to a servent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it can reissue the WSAAsyncGetServByPort function call with a buffer large enough to receive all the desired information (that is, no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in WINSOCK2.H as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

Return Values

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.

If the operation was successfully initiated, WSAAsyncGetServByPort returns a nonzero value of type HANDLE which is the asynchronous task handle for the request (not to be confused with a Windows HTASK). This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest. It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.

If the asynchronous operation could not be initiated, WSAAsyncGetServByPort returns a zero value, and a specific error number can be retrieved by calling WSAGetLastError.

Comments

The buffer supplied to this function is used by Windows Sockets to construct a servent structure together with the contents of data areas referenced by members of the same servent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in WINSOCK2.H).

Error Codes

The following error codes can be set when an application window receives a message. As described above, they can be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

WSAENETDOWN	The network subsystem has failed.
WSAENOBUFS	Insufficient buffer space is available.
WSAEFAULT	proto or buf is not in a valid part of the process address space.
WSAHOST_NOT_FOUND	Authoritative Answer Port not found.
WSATRY_AGAIN	Non-Authoritative Port not found, or server failure.
WSANO_RECOVERY	Nonrecoverable errors, the services database is not accessible.
WSANO_DATA	Valid name, no data record of requested type.
The following errors can occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
See Also

getservbyport, WSACancelAsyncRequest


WSAAsyncSelect

The Windows Sockets WSAAsyncSelect function requests Windows message-based notification of network events for a socket.

int WSAAsyncSelect (

SOCKET s,
HWND hWnd,
unsigned int wMsg,
long lEvent
);
Parameters

s

[in] A descriptor identifying the socket for which event notification is required.

hWnd

[in] A handle identifying the window which should receive a message when a network event occurs.

wMsg

[in] The message to be received when a network event occurs.

lEvent

[in] A bitmask which specifies a combination of network events in which the application is interested.

Remarks

This function is used to request that the Windows Sockets DLL should send a message to the window hWnd whenever it detects any of the network events specified by the lEvent parameter. The message which should be sent is specified by the wMsg parameter. The socket for which notification is required is identified by s.

This function automatically sets socket s to nonblocking mode, regardless of the value of lEvent. See ioctlsocket about how to set the nonoverlapped socket back to blocking mode.

The lEvent parameter is constructed by or'ing any of the values specified in the following list.

Value	Meaning
FD_READ	Want to receive notification of readiness for reading
FD_WRITE	Want to receive notification of readiness for writing
FD_OOB	Want to receive notification of the arrival of out-of-band data
FD_ACCEPT	Want to receive notification of incoming connections
FD_CONNECT	Want to receive notification of completed connection
FD_CLOSE	Want to receive notification of socket closure
FD_QOS	Want to receive notification of socket Quality of Service (QOS) changes
FD_GROUP_QOS	Want to receive notification of socket group Quality of Service (QOS) changes
Issuing a WSAAsyncSelect for a socket cancels any previous WSAAsyncSelect or WSAEventSelect for the same socket. For example, to receive notification for both reading and writing, the application must call WSAAsyncSelect with both FD_READ and FD_WRITE, as follows:

rc = WSAAsyncSelect(s, hWnd, wMsg, FD_READ|FD_WRITE);

It is not possible to specify different messages for different events. The following code will not work; the second call will cancel the effects of the first, and only FD_WRITE events will be reported with message wMsg2:

rc = WSAAsyncSelect(s, hWnd, wMsg1, FD_READ);

rc = WSAAsyncSelect(s, hWnd, wMsg2, FD_WRITE);

To cancel all notification (that is, to indicate that Windows Sockets should send no further messages related to network events on the socket) lEvent should be set to zero.

rc = WSAAsyncSelect(s, hWnd, 0, 0);

Although in this instance WSAAsyncSelect immediately disables event message posting for the socket, it is possible that messages can be waiting in the application's message queue. The application must therefore be prepared to receive network event messages even after cancellation. Closing a socket with closesocket also cancels WSAAsyncSelect message sending, but the same caveat about messages in the queue prior to the closesocket still applies.

Since an accept'ed socket has the same properties as the listening socket used to accept it, any WSAAsyncSelect events set for the listening socket apply to the accepted socket. For example, if a listening socket has WSAAsyncSelect events FD_ACCEPT, FD_READ, and FD_WRITE, then any socket accepted on that listening socket will also have FD_ACCEPT, FD_READ, and FD_WRITE events with the same wMsg value used for messages. If a different wMsg or events are desired, the application should call WSAAsyncSelect, passing the accepted socket and the desired new information.

When one of the nominated network events occurs on the specified socket s, the application's window hWnd receives message wMsg. The wParam argument identifies the socket on which a network event has occurred. The low word of lParam specifies the network event that has occurred. The high word of lParam contains any error code. The error code be any error as defined in WINSOCK2.H.

Note  Upon receipt of an event notification message the WSAGetLastError function cannot be used to check the error value, because the error value returned can differ from the value in the high word of lParam.

The error and event codes can be extracted from the lParam using the macros WSAGETSELECTERROR and WSAGETSELECTEVENT, defined in WINSOCK2.H as:

#define WSAGETSELECTERROR(lParam)       HIWORD(lParam)

#define WSAGETSELECTEVENT(lParam)       LOWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

The possible network event codes which can be returned are as follows:

Value	Meaning
FD_READ	Socket s ready for reading
FD_WRITE	Socket s ready for writing
FD_OOB	Out-of-band data ready for reading on socket s
FD_ACCEPT	Socket s ready for accepting a new incoming connection
FD_CONNECT	Connection initiated on socket s completed
FD_CLOSE	Connection identified by socket s has been closed
FD_QOS	Quality of Service associated with socket s has changed
FD_GROUP_QOS	Quality of Service associated with the socket group to which s belongs has changed
Return Values

The return value is zero if the application's declaration of interest in the network event set was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number can be retrieved by calling WSAGetLastError.

Comments

Although WSAAsyncSelect can be called with interest in multiple events, the application window will receive a single message for each network event.

As in the case of the select function, WSAAsyncSelect will frequently be used to determine when a data transfer operation (send or recv) can be issued with the expectation of immediate success. Nevertheless, a robust application must be prepared for the possibility that it can receive a message and issue a Windows Sockets 2 call which returns WSAEWOULDBLOCK immediately. For example, the following sequence of events is possible:

1.	data arrives on socket s; Windows Sockets 2 posts WSAAsyncSelect message

2.	application processes some other message

3.	while processing, application issues an ioctlsocket(s, FIONREAD...) and notices that there is data ready to be read

4.	application issues a recv(s,...) to read the data

5.	application loops to process next message, eventually reaching the WSAAsyncSelect message indicating that data is ready to read

6.	application issues recv(s,...), which fails with the error WSAEWOULDBLOCK.

Other sequences are possible.

The Windows Sockets DLL will not continually flood an application with messages for a particular network event. Having successfully posted notification of a particular event to an application window, no further message(s) for that network event will be posted to the application window until the application makes the function call which implicitly re-enables notification of that network event.

Event	Re-enabling function
FD_READ	recv, recvfrom, WSARecv, or WSARecvFrom
FD_WRITE	send, sendto, WSASend, or WSASendTo
FD_OOB	recv, recvfrom, WSARecv, or WSARecvFrom
FD_ACCEPT	accept or WSAAccept unless the error code is WSATRY_AGAIN indicating that the condition function returned CF_DEFER
FD_CONNECT	NONE
FD_CLOSE	NONE
FD_QOS	WSAIoctl with command SIO_GET_QOS
FD_GROUP_QOS	WSAIoctl with command SIO_GET_GROUP_QOS
Any call to the re-enabling routine, even one which fails, results in re-enabling of message posting for the relevant event.

For FD_READ, FD_OOB, and FD_ACCEPT events, message posting is "level-triggered." This means that if the re-enabling routine is called and the relevant condition is still met after the call, a WSAAsyncSelect message is posted to the application. This allows an application to be event-driven and not be concerned with the amount of data that arrives at any one time. Consider the following sequence:

1.	Network transport stack receives 100 bytes of data on socket s and causes Windows Sockets 2 to post an FD_READ message.

2.	The application issues recv( s, buffptr, 50, 0) to read 50 bytes.

3.	Another FD_READ message is posted since there is still data to be read.

With these semantics, an application need not read all available data in response to an FD_READ messagea single recv in response to each FD_READ message is appropriate. If an application issues multiple recv calls in response to a single FD_READ, it can receive multiple FD_READ messages. Such an application may need to disable FD_READ messages before starting the recv calls by calling WSAAsyncSelect with the FD_READ event not set.

The FD_QOS and FD_GROUP_QOS events are considered edge triggered. A message will be posted exactly once when a QOS change occurs. Further messages will not be forthcoming until either the provider detects a further change in QOS or the application renegotiates the QOS for the socket.

If any event has already happened when the application calls WSAAsyncSelect or when the re-enabling function is called, then a message is posted as appropriate. For example, consider the following sequence:

1.	an application calls listen,

2.	a connect request is received but not yet accepted,

3.	the application calls WSAAsyncSelect specifying that it wants to receive FD_ACCEPT messages for the socket. Due to the persistence of events, Windows Sockets 2 posts an FD_ACCEPT message immediately.

The FD_WRITE event is handled slightly differently. An FD_WRITE message is posted when a socket is first connected with connect/WSAConnect (after FD_CONNECT, if also registered) or accepted with accept/WSAAccept, and then after a send operation fails with WSAEWOULDBLOCK and buffer space becomes available. Therefore, an application can assume that sends are possible starting from the first FD_WRITE message and lasting until a send returns WSAEWOULDBLOCK. After such a failure the application will be notified that sends are again possible with an FD_WRITE message.

The FD_OOB event is used only when a socket is configured to receive out-of-band data separately. (See section Out-Of-Band data for a discussion of this topic.) If the socket is configured to receive out-of-band data in-line, the out-of-band (expedited) data is treated as normal data and the application should register an interest in, and will receive, FD_READ events, not FD_OOB events. An application may set or inspect the way in which out-of-band data is to be handled by using setsockopt or getsockopt for the SO_OOBINLINE option.

The error code in an FD_CLOSE message indicates whether the socket close was graceful or abortive. If the error code is zero, then the close was graceful; if the error code is WSAECONNRESET, then the socket's virtual circuit was reset. This only applies to connection-oriented sockets such as SOCK_STREAM.

The FD_CLOSE message is posted when a close indication is received for the virtual circuit corresponding to the socket. In TCP terms, this means that the FD_CLOSE is posted when the connection goes into the TIME WAIT or CLOSE WAIT states. This results from the remote end performing a shutdown on the send side or a closesocket. FD_CLOSE should only be posted after all data is read from a socket, but an application should check for remaining data upon receipt of FD_CLOSE to avoid any possibility of losing data.

Please note your application will receive ONLY an FD_CLOSE message to indicate closure of a virtual circuit, and only when all the received data has been read if this is a graceful close. It will not receive an FD_READ message to indicate this condition.

The FD_QOS or FD_GROUP_QOS message is posted when any field in the flow specification associated with socket s or the socket group that s belongs to has changed, respectively. Applications should use WSAIoctl with command SIO_GET_QOS or SIO_GET_GROUP_QOS to get the current QOS for socket s or for the socket group s belongs to, respectively.

Here is a summary of events and conditions for each asynchronous notification message:

•	FD_READ:

1.	when WSAAsyncSelect called, if there is data currently available to receive,

2.	when data arrives, if FD_READ not already posted,

3.	after recv or recvfrom called (with or without MSG_PEEK), if data is still available to receive.

Note  when setsockopt SO_OOBINLINE is enabled "data" includes both normal data and out-of-band (OOB) data in the instances noted above.

•	FD_WRITE:

1.	when WSAAsyncSelect called, if a send or sendto is possible

2.	after connect or accept called, when connection established

3.	after send or sendto fail with WSAEWOULDBLOCK, when send or sendto are likely to succeed,

4.	after bind on a datagram socket.

•	FD_OOB: Only valid when setsockopt SO_OOBINLINE is disabled (default).

1.	when WSAAsyncSelect called, if there is OOB data currently available to receive with the MSG_OOB flag,

2.	when OOB data arrives, if FD_OOB not already posted,

3.	after recv or recvfrom called with or without MSG_OOB flag, if OOB data is still available to receive.

•	FD_ACCEPT:

1.	when WSAAsyncSelect called, if there is currently a connection request available to accept,

2.	when a connection request arrives, if FD_ACCEPT not already posted,

3.	after accept called, if there is another connection request available to accept.

•	FD_CONNECT:

1.	when WSAAsyncSelect called, if there is currently a connection established,

2.	after connect called, when connection is established (even when connect succeeds immediately, as is typical with a datagram socket)

•	FD_CLOSE: Only valid on connection-oriented sockets (for example, SOCK_STREAM)

1.	when WSAAsyncSelect called, if socket connection has been closed,

2.	after remote system initiated graceful close, when no data currently available to receive (note: if data has been received and is waiting to be read when the remote system initiates a graceful close, the FD_CLOSE is not delivered until all pending data has been read),

3.	after local system initiates graceful close with shutdown and remote system has responded with "End of Data" notification (for example, TCP FIN), when no data currently available to receive,

4.	when remote system terminates connection (for example, sent TCP RST), and lParam will contain WSAECONNRESET error value.

Note  FD_CLOSE is not posted after closesocket is called.

•	FD_QOS:

1.	when WSAAsyncSelect called, if the QOS associated with the socket has been changed,

2.	after WSAIoctl with SIO_GET_QOS called, when the QOS is changed.

•	FD_GROUP_QOS:

1.	when WSAAsyncSelect called, if the group QOS associated with the socket has been changed,

2.	after WSAIoctl with SIO_GET_GROUP_QOS called, when the group QOS is changed.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINVAL	Indicates that one of the specified parameters was invalid such as the window handle not referring to an existing window, or the specified socket is in an invalid state.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAENOTSOCK	The descriptor is not a socket.
Additional error codes may be set when an application window receives a message. This error code is extracted from the lParam in the reply message using the WSAGETSELECTERROR macro. Possible error codes for each network event are:

Event: FD_CONNECT

Error Code	Meaning
WSAEADDRINUSE	The specified address is already in use.
WSAEADDRNOTAVAIL	The specified address is not available from the local machine.
WSAEAFNOSUPPORT	Addresses in the specified family cannot be used with this socket.
WSAECONNREFUSED	The attempt to connect was forcefully rejected.
WSAENETUNREACH	The network cannot be reached from this host at this time.
WSAEFAULT	The namelen argument is incorrect.
WSAEINVAL	The socket is already bound to an address.
WSAEISCONN	The socket is already connected.
WSAEMFILE	No more file descriptors are available.
WSAENOBUFS	No buffer space is available. The socket cannot be connected.
WSAENOTCONN	The socket is not connected.
WSAETIMEDOUT	Attempt to connect timed out without establishing a connection.
Event: FD_CLOSE

Error Code	Meaning
WSAENETDOWN	The network subsystem has failed.
WSAECONNRESET	The connection was reset by the remote side.
WSAECONNABORTED	The connection was terminated due to a time-out or other failure.
Event: FD_READ

Event: FD_WRITE

Event: FD_OOB

Event: FD_ACCEPT

Event: FD_QOS

Event: FD_GROUP_QOS

Error Code	Meaning
WSAENETDOWN	The network subsystem has failed.
See Also

select, WSAEventSelect


WSACancelAsyncRequest

The Windows Sockets WSACancelAsyncRequest function cancels an incomplete asynchronous operation.

int WSACancelAsyncRequest (

HANDLE hAsyncTaskHandle
);
Parameters

hAsyncTaskHandle

[in] Specifies the asynchronous operation to be canceled.

Remarks

The WSACancelAsyncRequest function is used to cancel an asynchronous operation which was initiated by one of the WSAAsyncGetXByY functions such as WSAAsyncGetHostByName. The operation to be canceled is identified by the hAsyncTaskHandle parameter, which should be set to the asynchronous task handle as returned by the initiating WSAAsyncGetXByY function.

Return Values

The value returned by WSACancelAsyncRequest is zero if the operation was successfully canceled. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Comments

An attempt to cancel an existing asynchronous WSAAsyncGetXByY operation can fail with an error code of WSAEALREADY for two reasons. First, the original operation has already completed and the application has dealt with the resultant message. Second, the original operation has already completed but the resultant message is still waiting in the application window queue.

Note  It is unclear whether the application can usefully distinguish between WSAEINVAL and WSAEALREADY, since in both cases the error indicates that there is no asynchronous operation in progress with the indicated handle. [Trivial exception: zero is always an invalid asynchronous task handle.] The Windows Sockets specification does not prescribe how a conformant Windows Sockets provider should distinguish between the two cases. For maximum portability, a Windows Sockets application should treat the two errors as equivalent.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINVAL	Indicates that the specified asynchronous task handle was invalid
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEALREADY	The asynchronous routine being canceled has already completed.
See Also

WSAAsyncGetHostByAddr, WSAAsyncGetHostByName, WSAAsyncGetProtoByName, WSAAsyncGetProtoByNumber, WSAAsyncGetServByName, WSAAsyncGetServByPort


WSACancelBlockingCall

This function has been removed in compliance with the Windows Sockets 2 specification, revision 2.2.0.

The function is not exported directly by the WS2_32.DLL, and Windows Sockets 2 applications should not use this function. Windows Sockets 1.1 applications that call this function are still supported through the WINSOCK.DLL and WSOCK32.DLL.

Blocking hooks are generally used to keep a single-threaded GUI application responsive during calls to blocking functions. Instead of using blocking hooks, an applications should use a separate thread (separate from the main GUI thread) for network activity.


WSACleanup

The Windows Sockets WSACleanup function terminates use of the Windows Sockets DLL.

int  WSACleanup (void);

Remarks

An application or DLL is required to perform a successful WSAStartup call before it can use Windows Sockets services. When it has completed the use of Windows Sockets, the application or DLL must call WSACleanup to deregister itself from a Windows Sockets implementation and allow the implementation to free any resources allocated on behalf of the application or DLL. Any pending blocking or asynchronous calls issued by any thread in this process are canceled without posting any notification messages, or signaling any event objects. Any pending overlapped send and receive operations (WSASend/WSASendTo/WSARecv/WSARecvFrom with an overlapped socket) issued by any thread in this process are also canceled without setting the event object or invoking the completion routine, if specified. In this case, the pending overlapped operations fail with the error status WSA_OPERATION_ABORTED. Any sockets open when WSACleanup is called are reset and automatically deallocated as if closesocket was called; sockets which have been closed with closesocket but which still have pending data to be sent may be affectedthe pending data may be lost if the Windows Sockets DLL is unloaded from memory as the application exits. To insure that all pending data is sent an application should use shutdown to close the connection, then wait until the close completes before calling closesocket and WSACleanup. All resources and internal state, such as queued un-posted messages, must be deallocated so as to be available to the next user.

There must be a call to WSACleanup for every successful call to WSAStartup made by a task. Only the final WSACleanup for that task does the actual cleanup; the preceding calls simply decrement an internal reference count in the Windows Sockets DLL.

Return Values

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Comments

Attempting to call WSACleanup from within a blocking hook and then failing to check the return code is a common Windows Sockets programming error. If an application needs to quit while a blocking call is outstanding, the application must first cancel the blocking call with WSACancelBlockingCall then issue the WSACleanup call once control has been returned to the application.

In a multithreaded environment, WSACleanup terminates Windows Sockets operations for all threads.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
See Also

closesocket, shutdown, WSAStartup


WSACloseEvent

The Windows Sockets WSACloseEvent function closes an open event object handle.

BOOL WSACloseEvent(

WSAEVENT hEvent
);
Parameters

hEvent

[in] Identifies an open event object handle.

Remarks

The handle to the event object is closed so that further references to this handle will fail with the error WSA_INVALID_HANDLE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSA_INVALID_HANDLE	hEvent is not a valid event object handle.
See Also

WSACreateEvent, WSAEnumNetworkEvents, WSAEventSelect, WSAGetOverlappedResult, WSARecv, WSARecvFrom, WSAResetEvent, WSASend, WSASendTo, WSASetEvent, WSAWaitForMultipleEvents


WSAConnect

The Windows Sockets WSAConnect function establishes a connection to a peer, exchanges connect data, and specifies needed quality of service based on the supplied flow specification.

int  WSAConnect (

SOCKET s,
const struct sockaddr FAR * name,
int namelen,
LPWSABUF lpCallerData,
LPWSABUF lpCalleeData,
LPQOS lpSQOS,
LPQOS lpGQOS
);
Parameters

s

[in] A descriptor identifying an unconnected socket.

name

[in] The name of the peer to which the socket is to be connected.

namelen

[in] The length of the name.

lpCallerData

[in] A pointer to the user data that is to be transferred to the peer during connection establishment.

lpCalleeData

[out] A pointer to the user data that is to be transferred back from the peer during connection establishment.

lpSQOS

[in] A pointer to the flow specifications for socket s, one for each direction.

lpGQOS

[in] A pointer to the flow specifications for the socket group (if applicable).

Remarks

This function is used to create a connection to the specified destination, and to perform a number of other ancillary operations that occur at connect time as well. If the socket, s, is unbound, unique values are assigned to the local association by the system, and the socket is marked as bound.

For connection-oriented sockets (for example, type SOCK_STREAM), an active connection is initiated to the foreign host using name (an address in the name space of the socket; for a detailed description, please see bind). When this call completes successfully, the socket is ready to send/receive data. If the address field of the name structure is all zeroes, WSAConnect will return the error WSAEADDRNOTAVAIL. Any attempt to reconnect an active connection will fail with the error code WSAEISCONN.

For a connectionless socket (for example, type SOCK_DGRAM), the operation erformed by WSAConnect is merely to establish a default destination address so that the socket may be used on subsequent connection-oriented send and receive operations (send, WSASend, recv, WSARecv). Any datagrams received from an address other than the destination address specified will be discarded. If the address field of the name structure is all zeroes, the socket will be "dis-connected." Then, the default remote address will be indeterminate, so send/WSASend and recv/WSARecv calls will return the error code WSAENOTCONN. However, sendto/WSASendTo and recvfrom/WSARecvFrom can still be used. The default destination may be changed by simply calling WSAConnect again, even if the socket is already "connected". Any datagrams queued for receipt are discarded if name is different from the previous WSAConnect.

For connectionless sockets, name may indicate any valid address, including a broadcast address. However, to connect to a broadcast address, a socket must have setsockopt SO_BROADCAST enabled. Otherwise, WSAConnect will fail with the error code WSAEACCES.

On connectionless sockets, exchange of user to user data is not possible and the corresponding parameters will be silently ignored.

The application is responsible for allocating any memory space pointed to directly or indirectly by any of the parameters it specifies.

The lpCallerData is a value parameter which contains any user data that is to be sent along with the connection request. If lpCallerData is NULL, no user data will be passed to the peer. The lpCalleeData is a result parameter which will contain any user data passed back from the peer as part of the connection establishment. lpCalleeData->len initially contains the length of the buffer allocated by the application and pointed to by lpCalleeData->buf. lpCalleeData->len will be set to zero if no user data has been passed back. The lpCalleeData information will be valid when the connection operation is complete. For blocking sockets, this will be when the WSAConnect function returns. For nonblocking sockets, this will be after the FD_CONNECT notification has occurred. If lpCalleeData is NULL, no user data will be passed back. The exact format of the user data is specific to the address family to which the socket belongs.

At connect time, an application may use the lpSQOS and/or lpGQOS parameters to override any previous QOS specification made for the socket through WSAIoctl with either the SIO_SET_QOS or SIO_SET_GROUP_QOS opcodes.

lpSQOS specifies the flow specifications for socket s, one for each direction, followed by any additional provider-specific parameters. If either the associated transport provider in general or the specific type of socket in particular cannot honor the QOS request, an error will be returned as indicated below. The sending or receiving flow specification values will be ignored, respectively, for any unidirectional sockets. If no provider-specific parameters are supplied, the buf and len fields of lpSQOS->ProviderSpecific should be set to NULL and zero, respectively. A NULL value for lpSQOS indicates no application supplied QOS.

lpGQOS specifies the flow specifications for the socket group (if applicable), one for each direction, followed by any additional provider-specific parameters. If no provider-specific parameters are supplied, the buf and len fields of lpSQOS->ProviderSpecific should be set to NULL and zero, respectively. A NULL value for lpGQOS indicates no application-supplied group QOS. This parameter will be ignored if s is not the creator of the socket group.

Comments

When connected sockets break (that is, become closed for whatever reason), they should be discarded and recreated. It is safest to assume that when things go awry for any reason on a connected socket, the application must discard and recreate the needed sockets in order to return to a stable point.

Return Values

If no error occurs, WSAConnect returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code may be retrieved by calling WSAGetLastError. On a blocking socket, the return value indicates success or failure of the connection attempt.

With a nonblocking socket, the connection attempt may not be completed immediately. In this case, WSAConnect will return SOCKET_ERROR, and WSAGetLastError will return WSAEWOULDBLOCK. In this case, the application may:

1.	Use select to determine the completion of the connection request by checking if the socket is writeable, or

2.	If your application is using WSAAsyncSelect to indicate interest in connection events, then your application will receive an FD_CONNECT notification when the connect operation is complete, or

3.	If your application is using WSAEventSelect to indicate interest in connection events, then the associated event object will be signaled when the connect operation is complete.

For a nonblocking socket, until the connection attempt completes all subsequent calls to WSAConnect on the same socket will fail with the error code WSAEALREADY.

If the return error code indicates the connection attempt failed (that is, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) the application may call WSAConnect again for the same socket.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEADDRINUSE	The specified address is already in use.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEALREADY	A nonblocking connect/WSAConnect call is in progress on the specified socket.
WSAEADDRNOTAVAIL	The specified address is not available from the local machine.
WSAEAFNOSUPPORT	Addresses in the specified family cannot be used with this socket.
WSAECONNREFUSED	The attempt to connect was rejected.
WSAEFAULT	The name or the namelen argument is not a valid part of the user address space, the namelen argument is too small, the buffer length for lpCalleeData, lpSQOS, and lpGQOS are too small, or the buffer length for lpCallerData is too large.
WSAEINVAL	The parameter s is a listening socket, or the destination address specified is not consistent with that of the constrained group the socket belongs to.
WSAEISCONN	The socket is already connected (connection-oriented sockets only).
WSAENETUNREACH	The network cannot be reached from this host at this time.
WSAENOBUFS	No buffer space is available. The socket cannot be connected.
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	The flow specifications specified in lpSQOS and lpGQOS cannot be satisfied.
WSAEPROTONOSUPPORT	The lpCallerData augment is not supported by the service provider.
WSAETIMEDOUT	Attempt to connect timed out without establishing a connection.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the connection cannot be completed immediately. It is possible to select the socket while it is connecting by selecting it for writing.
WSAEACCES	Attempt to connect datagram socket to broadcast address failed because setsockopt SO_BROADCAST is not enabled.
See Also

accept, bind, connect, getsockname, getsockopt, select, socket, WSAAsyncSelect, WSAEventSelect


WSACreateEvent

The Windows Sockets connect function creates a new event object.

WSAEVENT  WSACreateEvent(void);

Remarks

The event object created by this function is manual reset, with an initial state of nonsignaled. Windows Sockets 2 event objects are system objects in Win32 environments. Therefore, if a Win32 application desires auto reset events, it may call the native CreateEvent Win32 function directly. The scope of an event object is limited to the process in which it is created.

Return Values

If the function succeeds, the return value is the handle of the event object.

If the function fails, the return value is WSA_INVALID_EVENT. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSA_NOT_ENOUGH_MEMORY	Not enough free memory available to create the event object.
See Also

WSACloseEvent, WSAEnumNetworkEvents, WSAEventSelect, WSAGetOverlappedResult, WSARecv, WSARecvFrom, WSAResetEvent, WSASend, WSASendTo, WSASetEvent, WSAWaitForMultipleEvents


WSADuplicateSocket

The Windows Sockets WSADuplicateSocket function returns a WSAPROTOCOL_INFO structure that can be used to create a new socket descriptor for a shared socket.

int WSADuplicateSocket (

SOCKET s,
DWORD dwProcessId,
LPWSAPROTOCOL_INFO lpProtocolInfo
);
Parameters

s

[in] Specifies the local socket descriptor.

dwProcessId

[in] Specifies the ID of the target process for which the shared socket will be used.

lpProtocolInfo

[out] A pointer to a buffer allocated by the client that is large enough to contain a WSAPROTOCOL_INFO structure. The service provider copies the protocol info structure contents to this buffer.

Remarks

This function is used to enable socket sharing between processes. A source process calls WSADuplicateSocket to obtain a special WSAPROTOCOL_INFO structure. It uses some interprocess communications (IPC) mechanism to pass the contents of this structure to a target process, which in turn uses it in a call to WSASocket to obtain a descriptor for the duplicated socket. Note that the special WSAPROTOCOL_INFO structure may only be used once by the target process.

Sockets can be shared among threads in a given process without using the WSADuplicateSocket function, since a socket descriptor is valid in all of a process's threads.

One possible scenario for establishing and using a shared socket in a handoff mode is illustrated below:

Source Process	IPC	Destination Process
1) WSASocket, WSAConnect
2) Request target process ID	⇒
		3) Receive process ID request and respond
4) Receive process ID	⇐
5) Call WSADuplicateSocket to get a special WSAPROTOCOL_INFO structure
6) Send WSAPROTOCOL_INFO structure to target
	⇒	7) Receive WSAPROTOCOL_INFO structure
		8) Call WSASocket to create shared socket descriptor.
10) closesocket		9)Use shared socket for data exchange
Return Values

If no error occurs, WSADuplicateSocket returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError.

Comments

The descriptors that reference a shared socket may be used independently as far as I/O is concerned. However, the Windows Sockets interface does not implement any type of access control, so it is up to the processes involved to coordinate their operations on a shared socket. A typical use for shared sockets is to have one process that is responsible for creating sockets and establishing connections, hand off sockets to other processes which are responsible for information exchange.

Since what is duplicated are the socket descriptors and not the underlying socket, all of the state associated with a socket is held in common across all the descriptors. For example a setsockopt operation performed using one descriptor is subsequently visible using a getsockopt from any or all descriptors. A process may call closesocket on a duplicated socket and the descriptor will become deallocated. The underlying socket, however, will remain open until closesocket is called by the last remaining descriptor.

Notification on shared sockets is subject to the usual constraints of WSAAsyncSelect and WSAEventSelect. Issuing either of these calls using any of the shared descriptors cancels any previous event registration for the socket, regardless of which descriptor was used to make that registration. Thus, for example, a shared socket cannot deliver FD_READ events to process A and FD_WRITE events to process B. For situations when such tight coordination is required, it is suggested that developers use threads instead of separate processes.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINVAL	Indicates that one of the specified parameters was invalid.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEMFILE	No more socket descriptors are available.
WSAENOBUFS	No buffer space is available. The socket cannot be created.
WSAENOTSOCK	The descriptor is not a socket.
See Also

WSASocket


WSAEnumNameSpaceProviders

The Windows Sockets WSAEnumNameSpaceProviders function retrieves information about available name spaces.

INT WSAAPI WSAEnumNameSpaceProviders (

LPDWORD lpdwBufferLength,
LPWSANAMESPACE_INFO lpnspBuffer
);
Parameters

lpdwBufferLength

[in/out] On input, the number of bytes contained in the buffer pointed to by lpnspBuffer. On output (if the function fails, and the error is WSAEFAULT), the minimum number of bytes to pass for the lpnspBuffer to retrieve all the requested information. The passed-in buffer must be sufficient to hold all of the name space information.

lpnspBuffer

[out] A buffer which is filled with WSANAMESPACE_INFO structuresdescribed below. The returned structures are located consecutively at the head of the buffer. Variable sized information referenced by pointers in the structures point to locations within the buffer located between the end of the fixed sized structures and the end of the buffer. The number of structures filled in is the return value of WSAEnumNameSpaceProviders.

Return Values

WSAEnumNameSpaceProviders returns the number of WSANAMESPACE_INFO structures copied into lpnspBuffer. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSAEFAULT	the buffer length was too small to receive all the relevant WSANAMESPACE_INFO structures and associated information. Pass in a buffer at least as large as the value returned in lpdwBufferLength.
WSANOTINITIALIZED	The Windows Sockets 2 DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.


WSAEnumNetworkEvents

The Windows Sockets WSAEnumNetworkEvents function discovers occurrences of network events for the indicated socket.

int WSAEnumNetworkEvents (

SOCKET s,
WSAEVENT hEventObject,
LPWSANETWORKEVENTS lpNetworkEvents
);
Parameters

s

[in] A descriptor identifying the socket.

hEventObject

[in] An optional handle identifying an associated event object to be reset.

lpNetworkEvents

[out] A pointer to a WSANETWORKEVENTS structure which is filled with a record of occurred network events and any associated error codes.

Remarks

This function is used to discover which network events have occurred for the indicated socket since the last invocation of this function. It is intended for use in conjunction with WSAEventSelect, which associates an event object with one or more network events. Recording of network events commences when WSAEventSelect is called with a nonzero lNetworkEvents parameter and remains in effect until another call is made to WSAEventSelect with the lNetworkEvents parameter set to zero, or until a call is made to WSAAsyncSelect.

The socket’s internal record of network events is copied to the structure referenced by lpNetworkEvents, whereafter the internal network events record is cleared. If hEventObject is non-null, the indicated event object is also reset. The Windows Sockets provider guarantees that the operations of copying the network event record, clearing it and resetting any associated event object are atomic, such that the next occurrence of a nominated network event will cause the event object to become set. In the case of this function returning SOCKET_ERROR, the associated event object is not reset and the record of network events is not cleared.

The WSANETWORKEVENTS structure is defined as follows:

typedef struct _WSANETWORKEVENTS {

       long lNetworkEvents;

       int iErrorCodes[FD_MAX_EVENTS];

} WSANETWORKEVENTS, FAR * LPWSANETWORKEVENTS;

The lNetworkEvents field of the structure indicates which of the FD_XXX network events have occurred. The iErrorCodes array is used to contain any associated error codes, with array index corresponding to the position of event bits in lNetworkEvents. The identifiers such as FD_READ_BIT and FD_WRITE_BIT can be used to index the iErrorCodes array.

The following error codes may be returned along with the respective network event:

Event: FD_CONNECT

Error Code	Meaning
WSAEADDRINUSE	The specified address is already in use.
WSAEADDRNOTAVAIL	The specified address is not available from the local machine.
WSAEAFNOSUPPORT	Addresses in the specified family cannot be used with this socket.
WSAECONNREFUSED	The attempt to connect was forcefully rejected.
WSAENETUNREACH	The network cannot be reached from this host at this time.
WSAENOBUFS	No buffer space is available. The socket cannot be connected.
WSAETIMEDOUT	Attempt to connect timed out without establishing a connection
Event: FD_CLOSE

Error Code	Meaning
WSAENETDOWN	The network subsystem has failed.
WSAECONNRESET	The connection was reset by the remote side.
WSAECONNABORTED	The connection was terminated due to a time-out or other failure.
Event: FD_READ

Event: FD_WRITE

Event: FD_OOB

Event: FD_ACCEPT

Event: FD_QOS

Event: FD_GROUP_QOS

Error Code	Meaning
WSAENETDOWN	The network subsystem has failed.
Return Values

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINVAL	Indicates that one of the specified parameters was invalid.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAENOTSOCK	The descriptor is not a socket.
See Also

WSAEventSelect


WSAEnumProtocols

The Windows Sockets WSAEnumProtocols function retrieves information about available transport protocols.

int WSAEnumProtocols (

LPINT lpiProtocols,
LPWSAPROTOCOL_INFO lpProtocolBuffer,
ILPDWORD lpdwBufferLength
);
Parameters

lpiProtocols

[in] A NULL-terminated array of iProtocol values. This parameter is optional; if lpiProtocols is NULL, information on all available protocols is returned. Otherwise, information is retrieved only for those protocols listed in the array.

lpProtocolBuffer

[out] A buffer which is filled with WSAPROTOCOL_INFO structures. See below for a detailed description of the contents of the WSAPROTOCOL_INFO structure.

lpdwBufferLength

[in/out] On input, the count of bytes in the lpProtocolBuffer buffer passed to WSAEnumProtocols. On output, the minimum buffer size that can be passed to WSAEnumProtocols to retrieve all the requested information. This routine has no ability to enumerate over multiple calls; the passed-in buffer must be large enough to hold all entries in order for the routine to succeed. This reduces the complexity of the API and should not pose a problem because the number of protocols loaded on a machine is typically small.

Remarks

This function is used to discover information about the collection of transport protocols and protocol chains installed on the local machine. Since layered protocols are only usable by applications when installed in protocol chains, information on layered protocols is not included in lpProtocolBuffer. The lpiProtocols parameter can be used as a filter to constrain the amount of information provided. Normally it will be supplied as a NULL pointer which will cause the routine to return information on all available transport protocols and protocol chains.

A WSAPROTOCOL_INFO structure is provided in the buffer pointed to by lpProtocolBuffer for each requested protocol. If the supplied buffer is not large enough (as indicated by the input value of lpdwBufferLength ), the value pointed to by lpdwBufferLength will be updated to indicate the required buffer size. The application should then obtain a large enough buffer and call this function again.

The order in which the WSAPROTOCOL_INFO structures appear in the buffer coincides with the order in which the protocol entries were registered by the service provider with the Windows Sockets DLL, or with any subsequent re-ordering that may have occurred through the Windows Sockets applet supplied for establishing default TCP/IP providers.

Return Values

If no error occurs, WSAEnumProtocols returns the number of protocols to be reported on. Otherwise, a value of SOCKET_ERROR is returned and a specific error code may be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress.
WSAEINVAL	Indicates that one of the specified parameters was invalid.
WSAENOBUFS	The buffer length was too small to receive all the relevant WSAPROTOCOL_INFO structures and associated information. Pass in a buffer at least as large as the value returned in lpdwBufferLength.


WSAEventSelect

The Windows Sockets WSAEventSelect function specifies an event object to be associated with the supplied set of FD_XXX network events.

int WSAEventSelect (

SOCKET s,
WSAEVENT hEventObject,
long lNetworkEvents
);
Parameters

s

[in] A descriptor identifying the socket.

hEventObject

[in] A handle identifying the event object to be associated with the supplied set of FD_XXX network events.

lNetworkEvents

[in] A bitmask which specifies the combination of FD_XXX network events in which the application has interest.

Remarks

This function is used to specify an event object, hEventObject, to be associated with the selected FD_XXX network events, lNetworkEvents. The socket for which an event object is specified is identified by s. The event object is set when any of the nominated network events occur.

WSAEventSelect operates very similarly to WSAAsyncSelect, the difference being in the actions taken when a nominated network event occurs. Whereas WSAAsyncSelect causes an application-specified Windows message to be posted, WSAEventSelect sets the associated event object and records the occurrence of this event in an internal network event record. An application can use WSAWaitForMultipleEvents to wait or poll on the event object, and use WSAEnumNetworkEvents to retrieve the contents of the internal network event record and thus determine which of the nominated network events have occurred.

This function automatically sets socket s to nonblocking mode, regardless of the value of lNetworkEvents. See ioctlsocket/WSAIoctl about how to set the socket back to blocking mode.

The lNetworkEvents parameter is constructed by or'ing any of the values specified in the following list.

Value	Meaning
FD_READ	Want to receive notification of readiness for reading
FD_WRITE	Want to receive notification of readiness for writing
FD_OOB	Want to receive notification of the arrival of out-of-band data
FD_ACCEPT	Want to receive notification of incoming connections
FD_CONNECT	Want to receive notification of completed connection
FD_CLOSE	Want to receive notification of socket closure
FD_QOS	Want to receive notification of socket Quality of Service (QOS) changes
FD_GROUP_QOS	Want to receive notification of socket group Quality of Service (QOS) changes
Issuing a WSAEventSelect for a socket cancels any previous WSAAsyncSelect or WSAEventSelect for the same socket and clears the internal network event record. For example, to associate an event object with both reading and writing network events, the application must call WSAEventSelect with both FD_READ and FD_WRITE, as follows:

rc = WSAEventSelect(s, hEventObject, FD_READ|FD_WRITE);

It is not possible to specify different event objects for different network events. The following code will not work; the second call will cancel the effects of the first, and only FD_WRITE network event will be associated with hEventObject2:

rc = WSAEventSelect(s, hEventObject1, FD_READ);

rc = WSAEventSelect(s, hEventObject2, FD_WRITE); //bad

To cancel the association and selection of network events on a socket, lNetworkEvents should be set to zero, in which case the hEventObject parameter will be ignored.

rc = WSAEventSelect(s, hEventObject, 0);

Closing a socket with closesocket also cancels the association and selection of network events specified in WSAEventSelect for the socket. The application, however, still must call WSACloseEvent to explicitly close the event object and free any resources.

Since an accept'ed socket has the same properties as the listening socket used to accept it, any WSAEventSelect association and network events selection set for the listening socket apply to the accepted socket. For example, if a listening socket has WSAEventSelect association of hEventOject with FD_ACCEPT, FD_READ, and FD_WRITE, then any socket accepted on that listening socket will also have FD_ACCEPT, FD_READ, and FD_WRITE network events associated with the same hEventObject. If a different hEventObject or network events are desired, the application should call WSAEventSelect, passing the accepted socket and the desired new information.

Return Values

The return value is zero if the application's specification of the network events and the associated event object was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

As in the case of the select and WSAAsyncSelect functions, WSAEventSelect will frequently be used to determine when a data transfer operation (send or recv) can be issued with the expectation of immediate success. Nevertheless, a robust application must be prepared for the possibility that the event object is set and it issues a Windows Sockets call which returns WSAEWOULDBLOCK immediately. For example, the following sequence of operations is possible:

1.	data arrives on socket s; Windows Sockets sets the WSAEventSelect event object

2.	application does some other processing

3.	while processing, application issues an ioctlsocket(s, FIONREAD...) and notices that there is data ready to be read

4.	application issues a recv(s,...) to read the data

5.	application eventually waits on event object specified in WSAEventSelect, which returns immediately indicating that data is ready to read

6.	application issues recv(s,...), which fails with the error WSAEWOULDBLOCK.

Other sequences are possible.

Having successfully recorded the occurrence of the network event (by setting the corresponding bit in the internal network event record) and signaled the associated event object, no further actions are taken for that network event until the application makes the function call which implicitly re-enables the setting of that network event and signaling of the associated event object.

Network Event	Re-enabling function
FD_READ	recv, recvfrom, WSARecv, or WSARecvFrom
FD_WRITE	send, sendto, WSASend, or WSASendTo
FD_OOB	recv, recvfrom, WSARecv, or WSARecvFrom
FD_ACCEPT	accept or WSAAccept unless the error code returned is WSATRY_AGAIN indicating that the condition function returned CF_DEFER
FD_CONNECT	NONE
FD_CLOSE	NONE
FD_QOS	WSAIoctl with command SIO_GET_QOS
FD_GROUP_QOS	WSAIoctl with command SIO_GET_GROUP_QOS
Any call to the re-enabling routine, even one which fails, results in re-enabling of recording and signaling for the relevant network event and event object, respectively.

For FD_READ, FD_OOB, and FD_ACCEPT network events, network event recording and event object signaling are "level-triggered." This means that if the re-enabling routine is called and the relevant network condition is still valid after the call, the network event is recorded and the associated event object is set. This allows an application to be event-driven and not be concerned with the amount of data that arrives at any one time. Consider the following sequence:

1.	Transport provider receives 100 bytes of data on socket s and causes Windows Sockets DLL to record the FD_READ network event and set the associated event object.

2.	The application issues recv( s, buffptr, 50, 0) to read 50 bytes.

3.	The transport provider causes Windows Sockets DLL to record the FD_READ network event and sets the associated event object again since there is still data to be read.

With these semantics, an application need not read all available data in response to an FD_READ network eventa single recv in response to each FD_READ network event is appropriate.

The FD_QOS and FD_GROUP_QOS events are considered edge triggered. A message will be posted exactly once when a QOS change occurs. Further messages will not be forthcoming until either the provider detects a further change in QOS or the application renegotiates the QOS for the socket.

If a network event has already happened when the application calls WSAEventSelect or when the re-enabling function is called, then a network event is recorded and the associated event object is set as appropriate. For example, consider the following sequence:

1.	an application calls listen,

2.	a connect request is received but not yet accepted,

3.	the application calls WSAEventSelect specifying that it is interested in the FD_ACCEPT network event for the socket. Due to the persistence of network events, Windows Sockets records the FD_ACCEPT network event and sets the associated event object immediately.

The FD_WRITE network event is handled slightly differently. An FD_WRITE network event is recorded when a socket is first connected with connect/WSAConnect or accepted with accept/WSAAccept, and then after a send fails with WSAEWOULDBLOCK and buffer space becomes available. Therefore, an application can assume that sends are possible starting from the first FD_WRITE network event setting and lasting until a send returns WSAEWOULDBLOCK. After such a failure the application will find out that sends are again possible when an FD_WRITE network event is recorded and the associated event object is set.

The FD_OOB network event is used only when a socket is configured to receive out-of-band data separately. If the socket is configured to receive out-of-band data in-line, the out-of-band (expedited) data is treated as normal data and the application should register an interest in, and will get, FD_READ network event, not FD_OOB network event. An application may set or inspect the way in which out-of-band data is to be handled by using setsockopt or getsockopt for the SO_OOBINLINE option.

The error code in an FD_CLOSE network event indicates whether the socket close was graceful or abortive. If the error code is zero, then the close was graceful; if the error code is WSAECONNRESET, then the socket's virtual circuit was reset. This only applies to connection-oriented sockets such as SOCK_STREAM.

The FD_CLOSE network event is recorded when a close indication is received for the virtual circuit corresponding to the socket. In TCP terms, this means that the FD_CLOSE is recorded when the connection goes into the FIN WAIT or CLOSE WAIT states. This results from the remote end performing a shutdown on the send side or a closesocket.

Please note Windows Sockets will record ONLY an FD_CLOSE network event to indicate closure of a virtual circuit. It will not record an FD_READ network event to indicate this condition.

The FD_QOS or FD_GROUP_QOS network event is recorded when any field in the flow specification associated with socket s or the socket group that s belongs to has changed, respectively. Applications should use WSAIoctl with command SIO_GET_QOS or SIO_GET_GROUP_QOS to get the current QOS for socket s or for the socket group s belongs to, respectively.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINVAL	Indicates that one of the specified parameters was invalid, or the specified socket is in an invalid state.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAENOTSOCK	The descriptor is not a socket.
See Also

WSACloseEvent, WSACreateEvent, WSAEnumNetworkEvents, WSAWaitForMultipleEvents


WSAGetLastError

The Windows Sockets WSAGetLastError function gets the error status for the last operation which failed.

int  WSAGetLastError (void);

Remarks

This function returns the last network error that occurred. When a particular Windows Sockets function indicates that an error has occurred, this function should be called to retrieve the appropriate error code. This error code may be different from the error code obtained from getsockopt SO_ERROR.

A successful function call, or a call to WSAGetLastError, does not reset the error code. To reset the error code, use the WSASetLastError function call with iError set to zero.

This function should not be used to check for an error value on receipt of an asynchronous message. In this case, the error value is passed in the lParam field of the message, and this may differ from the value returned by WSAGetLastError.

Return Values

The return value indicates the error code for this thread’s last Windows Sockets operation that failed.

See Also

getsockopt, WSASetLastError


WSAGetOverlappedResult

The Windows Sockets WSAGetOverlappedResult function returns the results of an overlapped operation on the specified socket.

BOOL WSAGetOverlappedResult (

SOCKET s,
LPWSAOVERLAPPED lpOverlapped,
LPDWORD lpcbTransfer,
BOOL fWait,
LPDWORD lpdwFlags
);
Parameters

s

[in] Identifies the socket. This is the same socket that was specified when the overlapped operation was started by a call to WSARecv, WSARecvFrom, WSASend, WSASendTo, or WSAIoctl.

lpOverlapped

[in] Points to a WSAOVERLAPPED structure that was specified when the overlapped operation was started.

pcbTransfer

[out] Points to a 32-bit variable that receives the number of bytes that were actually transferred by a send or receive operation, or by WSAIoctl.

fWait

[in] Specifies whether the function should wait for the pending overlapped operation to complete. If TRUE, the function does not return until the operation has been completed. If FALSE and the operation is still pending, the function returns FALSE and the WSAGetLastError function returns WSA_IO_INCOMPLETE.

lpdwFlags

[out] Points to a 32-bit variable that will receive one or more flags that supplement the completion status. If the overlapped operation was initiated through WSARecv or WSARecvFrom, this parameter will contain the results value for lpFlags parameter.

Remarks

The results reported by the WSAGetOverlappedResult function are those of the specified socket's last overlapped operation to which the specified WSAOVERLAPPED structure was provided, and for which the operation's results were pending. A pending operation is indicated when the function that started the operation returns FALSE, and the WSAGetLastError function returns WSA_IO_PENDING. When an I/O operation is pending, the function that started the operation resets the hEvent member of the WSAOVERLAPPED structure to the nonsignaled state. Then when the pending operation has been completed, the system sets the event object to the signaled state.

If the fWait parameter is TRUE, WSAGetOverlappedResult determines whether the pending operation has been completed by waiting for the event object to be in the signaled state.

Return Values

If WSAGetOverlappedResult succeeds, the return value is TRUE. This means that the overlapped operation has completed successfully and that the value pointed to by lpcbTransfer has been updated. If WSAGetOverlappedResult returns FALSE, this means that either the overlapped operation has not completed or the overlapped operation completed but with errors, or that completion status could not be determined due to errors in one or more parameters to WSAGetOverlappedResult. On failure, the value pointed to by lpcbTransfer will not be updated. Use WSAGetLastError to determine the cause of the failure (either of WSAGetOverlappedResult or of the associated overlapped operation).

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAENOTSOCK	The descriptor is not a socket.
WSA_INVALID_HANDLE	The hEvent field of the WSAOVERLAPPED structure does not contain a valid event object handle.
WSA_INVALID_PARAMETER	One of the parameters is unacceptable.
WSA_IO_INCOMPLETE	fWait is FALSE and the I/O operation has not yet completed.
See Also

WSAAccept, WSAConnect, WSACreateEvent, WSAIoctl, WSARecv, WSARecvFrom, WSASend, WSASendTo, WSAWaitForMultipleEvents


WSAGetQOSByName

The Windows Sockets WSAGetQOSByName function initializes a QOS structure based on a named template.

BOOL WSAGetQOSByName(

SOCKET s,
LPWSABUF lpQOSName,
LPQOS lpQOS
);
Parameters

s

[in] A descriptor identifying a socket.

lpQOSName

[in] Specifies the QOS template name.

lpQOS

[out] A pointer to the QOS structure to be filled.

Remarks

Applications may use this function to initalize a QOS structure to a set of known values appropriate for a particular service class or media type. These values are stored in a template which is referenced by a well-known name.

Return Values

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAENOTSOCK	The descriptor is not a socket.
WSAEFAULT	The lpQOS argument is not a valid part of the user address space, or the buffer length for lpQOS is too small.
WSA_INVAL	The specified QOS template name is invalid.
See Also

getsockopt, WSAAccept, WSAConnect


WSAGetServiceClassInfo

The Windows Sockets WSAGetServiceClassInfo function retrieves all of the class information (schema) pertaining to a specified service class from a specified name space provider.

INT WSAGetServiceClassInfo(

LPGUID lpProviderId,
LPGUID lpServiceClassId,
LPDWORD lpdwBufSize,
LPWSASERVICECLASSINFO lpServiceClassInfo
);
Parameters

lpProviderId

[in] Pointer to a GUID which identifies a specific name space provider

lpServiceClassId

[in] Pointer to a GUID identifying the service class in question

lpdwBufferLength

[in/out] On input, the number of bytes contained in the buffer pointed to by lpServiceClassInfos. On output, if the function fails and the error is WSAEFAULT, then it contains the minimum number of bytes to pass for the lpServiceClassInfo to retrieve the record.

lpServiceClasslnfo

[out] Returns service class information from the indicated name space provider for the specified service class.

Remarks

The service class information retrieved from a particular name space provider may not necessarily be the complete set of class information that was supplied when the service class was installed. Individual name space providers are only required to retain service class information that is applicable to the name spaces that they support. See section Service Class Data Structures for more information.

Return Values

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSAEFAULT	The buffer referenced by lpServiceClassInfo is too small. Pass in a larger buffer.
WSA_INVALID_PARAMETER	the specified service class ID or name space provider ID is invalid.
WSANOTINITIALIZED	The Windows Sockets 2 DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.


WSAGetServiceClassNameByServiceClassId

The Windows Sockets WSAGetServiceClassNameByServiceClassId function returns the name of the service associated with the given type. This name is the generic service name, like FTP or SNA, and not the name of a specific instance of that service.

INT WSAGetServiceClassNameByServiceClassId(

LPGUID lpServiceClassId,
LPTSTR lpszServiceClassName,
LPDWORD lpdwBufferLength
);
Parameters

lpServiceClassId

[in] Pointer to the GUID for the service class.

lpszServiceClassName

[out] Sevice name.

lpdwBufferLength

[in/out] On input length of buffer returned by lpszServiceClassName. On output, the length of the service name copied into lpszServiceClassName.

Return Values

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSAEFAULT	The specified ServiceClassName buffer is too small. Pass in a larger buffer
WSA_INVALID_PARAMETER	the specified ServiceClassId is invalid.
WSANOTINITIALIZED	The Windows Sockets 2 DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.


WSAHtonl

The Windows Sockets WSAHtonl function converts a u_long from host byte order to network byte order.

int WSAHtonl (

SOCKET s,
u_long hostlong,
u_long FAR * lpnetlong
);
Parameters

s

[in] A descriptor identifying a socket.

hostlong

[in] A 32-bit number in host byte order.

lpnetlong

[out] A pointer to a 32-bit number in network byte order.

Remarks

This routine takes a 32-bit number in host byte order and returns a 32-bit number pointed to by the lpnetlong parameter in the network byte order associated with socket s.

Return Values

If no error occurs, WSAHtonl returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAENOTSOCK	The descriptor is not a socket.
WSAEFAULT	The lpnetlong argument is not totally contained in a valid part of the user address space.
See Also

htonl, htons, ntohl, ntohs, WSANtohl, WSAHtons, WSANtohs


WSAHtons

The Windows Sockets WSAHtons function converts a u_short from host byte order to network byte order.

int WSAHtons (

SOCKET s,
u_short hostshort,
u_short FAR * lpnetshort
);
Parameters

s

[in] A descriptor identifying a socket.

hostshort

[in] A 16-bit number in host byte order.

lpnetshort

[out] A pointer to a 16-bit number in network byte order.

Remarks

This routine takes a 16-bit number in host byte order and returns a 16-bit number pointed to by the lpnetshort parameter in the network byte order associated with socket s.

Return Values

If no error occurs, WSAHtons returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAENOTSOCK	The descriptor is not a socket.
WSAEFAULT	The lpnetshort argument is not totally contained in a valid part of the user address space.
See Also

htonl, htons, ntohl, ntohs, WSAHtonl, WSANtohl, WSANtohs


WSAInstallServiceClass

The Windows Sockets WSAInstallServiceClass function registers a service class schema within a name space. This schema includes the class name, class id, and any name space specific information that is common to all instances of the service, such as the SAP ID or object ID.

INT WSAInstallServiceClass(

LPWSASERVICECLASSINFO lpServiceClassInfo
);
Parameters

lpServiceClasslnfo

[in] Service class to name space specific type mapping information. Multiple mappings can be handled at one time.

See section Service Class Data Structures for a description of pertinent data structures.

Return Values

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSAEACCESS	The calling routine does not have sufficient privileges to install the Service.
WSAEALREADY	Service class information has already been registered for this service class ID. To modify service class info, first use WSARemoveServiceClass, and then re-install with updated class info data.
WSANOTINITIALIZED	The Windows Sockets 2 DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.


WSAIoctl

The Windows Sockets WSAIoctl function controls the mode of a socket.

int WSAIoctl (

SOCKET s,
DWORD dwIoControlCode,
LPVOID lpvInBuffer,
DWORD cbInBuffer,
LPVOID lpvOUTBuffer,
DWORD cbOUTBuffer,
LPDWORD lpcbBytesReturned,
LPWSAOVERLAPPED lpOverlapped,
LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionROUTINE
);
Parameters

s

[in] Handle to a socket

dwIoControlCode

[in] Control code of operation to perform

lpvInBuffer

[in] Address of input buffer

cbInBuffer

[in] Size of input buffer

lpvOutBuffer

[out] Address of output buffer

cbOutBuffer

[in] Size of output buffer

lpcbBytesReturned

[out] Address of actual bytes of output

lpOverlapped

[in] Address of WSAOVERLAPPED structure

lpCompletionRoutine

[in] A pointer to the completion routine called when the operation has been completed.

Remarks

This routine is used to set or retrieve operating parameters associated with the socket, the transport protocol, or the communications subsystem. For nonoverlapped socket, lpOverlapped and lpCompletionRoutine parameters are ignored, and this function behaves like the standard ioctlsocket function except that it may block if socket s is in the blocking mode. Note that if socket s is in the nonblocking mode, this function may return WSAEWOULDBLOCK if the specified operation cannot be finished immediately. In this case, the application should change the socket to the blocking mode and reissue the request. For overlapped sockets, operations that cannot be completed immediately will be initiated, and completion will be indicated at a later time. The final completion status is retrieved through WSAGetOverlappedResult. The lpcbBytesReturned parameter is ignored.

In as much as the dwIoControlCode parameter is now a 32-bit entity, it is possible to adopt an encoding scheme that preserves the currently defined ioctlsocket opcodes while providing a convenient way to partition the opcode identifier space. The dwIoControlCode parameter is architected to allow for protocol and vendor independence when adding new control codes, while retaining backward compatibility with the Windows Sockets 1.1 and Unix control codes. The dwIoControlCode parameter has the following form:

3	3	2	2 2	2 2 2 2 2 2 2 1 1 1 1	1 1 1 1 1 1
1	0	9	8 7	6 5 4 3 2 1 0 9 8 7 6	5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
I	O	V	T	Vendor/Address Family	Code
I is set if the input buffer is valid for the code, as with IOC_IN.

O is set if the output buffer is valid for the code, as with IOC_OUT. Note that for codes with both input and output parameters, both I and O will be set.

V is set if there are no parameters for the code, as with IOC_VOID.

T is a two-bit quantity which defines the type of ioctl. The following values are defined:

0 − The ioctl is a standard Unix ioctl code, as with FIONREAD and FIONBIO.

1 − The ioctl is a generic Windows Sockets 2 ioctl code. New ioctl codes defined for Windows Sockets 2 will have T == 1.

2 − The ioctl applies only to a specific address family.

3 − The ioctl applies only to a specific vendor's provider. This type allows companies to be assigned a vendor number which appears in the

Vendor/Address family field, and then the vendor can define new ioctls specific to that vendor without having to register the ioctl with a clearinghouse, thereby providing vendor flexibility and privacy.

Vendor/Address family − An 11-bit quantity which defines the vendor who owns the code (if T == 3) or which contains the address family to which the code applies (if T == 2). If this is a Unix ioctl code (T == 0) then this field has the same value as the code on Unix. If this is a generic Windows Sockets 2 ioctl (T == 1) then this field can be used as an extension of the "code" field to provide additional code values.

Code − The specific ioctl code for the operation.

The following Unix commands are supported:

Parameters

FIONBIO

Enable or disable nonblocking mode on socket s. lpvInBuffer points at an unsigned long, which is nonzero if nonblocking mode is to be enabled and zero if it is to be disabled. When a socket is created, it operates in blocking mode (that is, nonblocking mode is disabled). This is consistent with BSD sockets.

The WSAAsyncSelect or WSAEventSelect routine automatically sets a socket to nonblocking mode. If WSAAsyncSelect or WSAEventSelect has been issued on a socket, then any attempt to use WSAIoctl to set the socket back to blocking mode will fail with WSAEINVAL. To set the socket back to blocking mode, an application must first disable WSAAsyncSelect by calling WSAAsyncSelect with the lEvent parameter equal to zero, or disable WSAEventSelect by calling WSAEventSelect with the lNetworkEvents parameter equal to zero.

FIONREAD

Determine the amount of data which can be read atomically from socket s. lpvOutBuffer points at an unsigned long in which WSAIoctl stores the result. If s is stream oriented (for example, type SOCK_STREAM), FIONREAD returns the total amount of data which may be read in a single receive operation; this is normally the same as the total amount of data queued on the socket. If s is message oriented (for example, type SOCK_DGRAM), FIONREAD returns the size of the first datagram (message) queued on the socket.

SIOCATMARK

Determine whether or not all out-of-band data has been read. This applies only to a socket of stream style (for example, type SOCK_STREAM) which has been configured for in-line reception of any out-of-band data (SO_OOBINLINE). If no out-of-band data is waiting to be read, the operation returns TRUE. Otherwise, it returns FALSE, and the next receive operation performed on the socket will retrieve some or all of the data preceding the "mark"; the application should use the SIOCATMARK operation to determine whether any remains. If there is any normal data preceding the "urgent" (out of band) data, it will be received in order. (Note that receive operations will never mix out-of-band and normal data in the same call.) lpvOutBuffer points at a BOOL in which WSAIoctl stores the result.

The following Windows Sockets 2 commands are supported:

Parameters

SIO_ASSOCIATE_HANDLE (opcode setting: I, T==1)

Associate this socket with the specified handle of a companion interface. The input buffer contains the integer value corresponding to the manifest constant for the companion interface (for example, TH_NETDEV and TH_TAPI.), followed by a value which is a handle of the specified companion interface, along with any other required information. Refer to the appropriate section in the Windows Sockets 2 Protocol-Specific Annex for details specific to a particular companion interface. The total size is reflected in the input buffer length. No output buffer is required. The WSAENOPROTOOPT error code is indicated for service providers which do not support this ioctl.

SIO_ENABLE_CIRCULAR_QUEUEING (opcode setting: V, T==1)

Indicates to the underlying message-oriented service provider that a newly arrived message should never be dropped because of a buffer queue overflow. Instead, the oldest message in the queue should be eliminated in order to accommodate the newly arrived message. No input and output buffers are required. Note that this ioctl is only valid for sockets associated with unreliable, message-oriented protocols. The WSAENOPROTOOPT error code is indicated for service providers which do not support this ioctl.

SIO_FIND_ROUTE (opcode setting: O, T==1)

When issued, this ioctl requests that the route to the remote address specified as a sockaddr in the input buffer be discovered. If the address already exists in the local cache, its entry is invalidated. In the case of Novell’s IPX, this call initiates an IPX GetLocalTarget (GLT), which queries the network for the given remote address.

SIO_FLUSH (opcode setting: V, T==1)

Discards current contents of the sending queue associated with this socket. No input and output buffers are required. The WSAENOPROTOOPT error code is indicated for service providers which do not support this ioctl.

SIO_GET_BROADCAST_ADDRESS (opcode setting: O, T==1)

This ioctl fills the output buffer with a sockaddr structure containing a suitable broadcast address for use with sendto/WSASendTo.

SIO_GET_EXTENSION_FUNCTION_POINTER (opcode setting: O, I, T==1)

Retrieve a pointer to the specified extension function supported by the associated service provider. The input buffer contains a globally unique identifier (GUID) whose value identifies the extension function in question. The pointer to the desired function is returned in the output buffer. Extension function identifiers are established by service provider vendors and should be included in vendor documentation that describes extension function capabilities and semantics.

SIO_GET_QOS (opcode setting: O, T==1)

Retrieve the QOS structure associated with the socket. The input buffer is optional. Some protocols (for example, RSVP) allow the input buffer to be used to qualify a QOS request. The QOS structure will be copied into the output buffer. The output buffer must be sized large enough to be able to contain the full QOS structure. The WSAENOPROTOOPT error code is indicated for service providers which do not support QOS.

SIO_GET_GROUP_QOS (opcode setting: O, I, T==1)

Retrieve the QOS structure associated with the socket group to which this socket belongs. The input buffer is optional. Some protocols (for example, RSVP) allow the input buffer to be used to qualify a QOS request. The QOS structure will be copied into the output buffer. If this socket does not belong to an appropriate socket group, the SendingFlowspec and ReceivingFlowspec fields of the returned QOS structure are set to NULL. The WSAENOPROTOOPT error code is indicated for service providers which do not support QOS.

SIO_MULTIPOINT_LOOPBACK (opcode setting: I, T==1)

Controls whether data sent in a multipoint session will also be received by the same socket on the local host. A value of TRUE causes loopback reception to occur while a value of FALSE prohibits this.

SIO_MULTICAST_SCOPE (opcode setting: I, T==1)

Specifies the scope over which multicast transmissions will occur. Scope is defined as the number of routed network segments to be covered. A scope of zero would indicate that the multicast transmission would not be placed “on the wire” but could be disseminated across sockets within the local host. A scope value of one (the default) indicates that the transmission will be placed on the wire, but will not cross any routers. Higher scope values determine the number of routers that may be crossed. Note that this corresponds to the time-to-live (TTL) parameter in IP multicasting.

SIO_SET_QOS (opcode setting: I, T==1)

Associate the supplied QOS structure with the socket. No output buffer is required, the QOS structure will be obtained from the input buffer. The WSAENOPROTOOPT error code is indicated for service providers which do not support QOS.

SIO_SET_GROUP_QOS	(opcode setting: I, T==1)

Establish the supplied QOS structure with the socket group to which this socket belongs. No output buffer is required, the QOS structure will be obtained from the input buffer. The WSAENOPROTOOPT error code is indicated for service providers which do not support QOS, or if the socket descriptor specified is not the creator of the associated socket group.

SIO_TRANSLATE_HANDLE (opcode setting: I, O, T==1)

To obtain a corresponding handle for socket s that is valid in the context of a companion interface (for example, TH_NETDEV and TH_TAPI). A manifest constant identifying the companion interface along with any other needed parameters are specified in the input buffer. The corresponding handle will be available in the output buffer upon completion of this function. Refer to the appropriate section in the Windows Sockets 2 Protocol-Specific Annex for details specific to a particular companion interface. The WSAENOPROTOOPT error code is indicated for service providers which do not support this ioctl for the specified companion interface.

If an overlapped operation completes immediately, this function returns a value of zero and the lpcbBytesReturned parameter is updated with the number of bytes in the output buffer. If the overlapped operation is successfully initiated and will complete later, this function returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, lpcbBytesReturned is not updated. When the overlapped operation completes the amount of data in the output buffer is indicated either through the cbTransferred parameter in the completion routine (if specified), or through the lpcbTransfer parameter in WSAGetOverlappedResult.

When called with an overlapped socket, the lpOverlapped parameter must be valid for the duration of the overlapped operation. The WSAOVERLAPPED structure has the following form:

typedef struct _WSAOVERLAPPED {

    DWORD        Internal;        // reserved

    DWORD        InternalHigh;    // reserved

    DWORD        Offset;          // reserved

    DWORD        OffsetHigh;      // reserved

    WSAEVENT     hEvent;

} WSAOVERLAPPED, FAR * LPWSAOVERLAPPED;

If the lpCompletionRoutine parameter is NULL, the hEvent field of lpOverlapped is signaled when the overlapped operation completes if it contains a valid event object handle. An application can use WSAWaitForMultipleEvents or WSAGetOverlappedResult to wait or poll on the event object.

If lpCompletionRoutine is not NULL, the hEvent field is ignored and can be used by the application to pass context information to the completion routine.

The prototype of the completion routine is as follows:

void CALLBACK CompletionRoutine(
 IN	DWORD dwError,
 IN	DWORD cbTransferred,
 IN	LPWSAOVERLAPPED lpOverlapped,
 IN	DWORD dwFlags
);

CompletionRoutine is a placeholder for an application-defined or library-defined function. dwError specifies the completion status for the overlapped operation as indicated by lpOverlapped. cbTransferred specifies the number of bytes returned. Currently there are no flag values defined and dwFlags will be zero. This function does not return a value.

Returning from this function allows invocation of another pending completion routine for this socket. The completion routines may be called in any order, not necessarily in the same order the overlapped operations are completed.

Compatibility

The ioctl codes with T == 0 are a subset of the ioctl codes used in Berkeley sockets. In particular, there is no command which is equivalent to FIOASYNC.

Return Values

Upon successful completion, the WSAIoctl returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError.

Error Codes

WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	The lpvInBuffer, lpvOutBuffer or lpcbBytesReturned argument is not totally contained in a valid part of the user address space, or the cbInBuffer or cbOutBuffer argument is too small.
WSAEINVAL	dwIoControlCode is not a valid command, or a supplied input parameter is not acceptable, or the command is not applicable to the type of socket supplied.
WSAEINPROGRESS	The function is invoked when a callback is in progress.
WSAENOTSOCK	The descriptor s is not a socket.
WSAEOPNOTSUPP	The specified ioctl command cannot be realized. (For examle, the flow specifications specified in SIO_SET_QOS or SIO_SET_GROUP_QOS cannot be satisfied.)
WSA_IO_PENDING	An overlapped operation was successfully initiated and completion will be indicated at a later time.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the requested operation would block.
See Also

getsockopt, ioctlsocket, setsockopt, socket, WSASocket


WSAIsBlocking

This function has been removed in compliance with the Windows Sockets 2 specification, revision 2.2.0.

The function is not exported directly by the WS2_32.DLL, and Windows Sockets 2 applications should not use this function. Windows Sockets 1.1 applications that call this function are still supported through the WINSOCK.DLL and WSOCK32.DLL.

Blocking hooks are generally used to keep a single-threaded GUI application responsive during calls to blocking functions. Instead of using blocking hooks, an applications should use a separate thread (separate from the main GUI thread) for network activity.


WSAJoinLeaf

The Windows Sockets connect function joins a leaf node into a multipoint session, exchanges connect data, and specifies needed quality of service based on the supplied flow specifications.

SOCKET WSAJoinLeaf (

SOCKET s,
const struct sockaddr FAR * name,
int namelen,
LPWSABUF lpCallerData,
LPWSABUF lpCalleeData,
LPQOS lpSQOS,
LPQOS lpGQOS,
DWORD dwFlags
);
Parameters

s

[in] A descriptor identifying a multipoint socket.

name

[in] The name of the peer to which the socket is to be joined.

namelen

[in] The length of the name.

lpCallerData

[in] A pointer to the user data that is to be transferred to the peer during multipoint session establishment.

lpCalleeData

[out] A pointer to the user data that is to be transferred back from the peer during multipoint session establishment.

lpSQOS

[in] A pointer to the flow specifications for socket s, one for each direction.

lpGQOS

[in] A pointer to the flow specifications for the socket group (if applicable).

dwFlags

[in] Flags to indicate that the socket is acting as a sender, receiver, or both.

Remarks

This function is used to join a leaf node to a multipoint session, and to perform a number of other ancillary operations that occur at session join time as well. If the socket, s, is unbound, unique values are assigned to the local association by the system, and the socket is marked as bound.

WSAJoinLeaf has the same parameters and semantics as WSAConnect except that it returns a socket descriptor (as in WSAAccept), and it has an additional dwFlags parameter. Only multipoint sockets created using WSASocket with appropriate multipoint flags set may be used for input parameter s in this function. If the socket is in the nonblocking mode, the returned socket descriptor will not be usable until after a corresponding FD_CONNECT indication has been received. A root application in a multipoint session may call WSAJoinLeaf one or more times in order to add a number of leaf nodes, however at most one multipoint connection request may be outstanding at a time. Refer to Multipoint and Multicast Semantics for additional information.

The socket descriptor returned by WSAJoinLeaf is different depending on whether the input socket descriptor, s, is a c_root or a c_leaf. When used with a c_root socket, the name parameter designates a particular leaf node to be added and the returned socket descriptor is a c_leaf socket corresponding to the newly added leaf node. The newly created socket has the same properties as s including asynchronous events registered with WSAAsyncSelect or with WSAEventSelect, but not including the c_root socket’s group ID, if any. It is not intended to be used for exchange of multipoint data, but rather is used to receive network event indications (for example, FD_CLOSE) for the connection that exists to the particular c_leaf. Some multipoint implementations may also allow this socket to be used for “side chats” between the root and an individual leaf node. An FD_CLOSE indication will be received for this socket if the corresponding leaf node calls closesocket to drop out of the multipoint session. Symmetrically, invoking closesocket on the c_leaf socket returned from WSAJoinLeaf will cause the socket in the corresponding leaf node to get FD_CLOSE notification.

When WSAJoinLeaf is invoked with a c_leaf socket, the name parameter contains the address of the root application (for a rooted control scheme) or an existing multipoint session (nonrooted control scheme), and the returned socket descriptor is the same as the input socket descriptor. In other words, a new socket descriptor is not allocated. In a rooted control scheme, the root application would put its c_root socket in the listening mode by calling listen. The standard FD_ACCEPT notification will be delivered when the leaf node requests to join itself to the multipoint session. The root application uses the usual accept/WSAAccept functions to admit the new leaf node. The value returned from either accept or WSAAccept is also a c_leaf socket descriptor just like those returned from WSAJoinLeaf. To accommodate multipoint schemes that allow both root-initiated and leaf-initiated joins, it is acceptable for a c_root socket that is already in listening mode to be used as an input to WSAJoinLeaf.

The application is responsible for allocating any memory space pointed to directly or indirectly by any of the parameters it specifies.

The lpCallerData is a value parameter which contains any user data that is to be sent along with the multipoint session join request. If lpCallerData is NULL, no user data will be passed to the peer. The lpCalleeData is a result parameter which will contain any user data passed back from the peer as part of the multipoint session establishment. lpCalleeData->len initially contains the length of the buffer allocated by the application and pointed to by lpCalleeData->buf. lpCalleeData->len will be set to zero if no user data has been passed back. The lpCalleeData information will be valid when the multipoint join operation is complete. For blocking sockets, this will be when the WSAConnect function returns. For nonblocking sockets, this will be after the FD_CONNECT notification has occurred. If lpCalleeData is NULL, no user data will be passed back. The exact format of the user data is specific to the address family to which the socket belongs.

At multipoint session establishment time, an application may use the lpSQOS and/or lpGQOS parameters to override any previous QOS specification made for the socket through WSAIoctl with either the SIO_SET_QOS or SIO_SET_GROUP_QOS opcodes.

lpSQOS specifies the flow specifications for socket s, one for each direction, followed by any additional provider-specific parameters. If either the associated transport provider in general or the specific type of socket in particular cannot honor the QOS request, an error will be returned as indicated below. The sending or receiving flow specification values will be ignored, respectively, for any unidirectional sockets. If no provider-specific parameters are supplied, the buf and len fields of lpSQOS->ProviderSpecific should be set to NULL and zero, respectively. A NULL value for lpSQOS indicates no application supplied QOS.

lpGQOS specifies the flow specifications for the socket group (if applicable), one for each direction, followed by any additional provider-specific parameters. If no provider-specific parameters are supplied, the buf and len fields of lpSQOS->ProviderSpecific should be set to NULL and zero, respectively. A NULL value for lpGQOS indicates no application-supplied group QOS. This parameter will be ignored if s is not the creator of the socket group.

The dwFlags parameter is used to indicate whether the socket will be acting only as a sender (JL_SENDER_ONLY), only as a receiver (JL_RECEIVER_ONLY), or both (JL_BOTH).

Comments

When connected sockets break (that is, become closed for whatever reason), they should be discarded and recreated. It is safest to assume that when things go awry for any reason on a connected socket, the application must discard and recreate the needed sockets in order to return to a stable point.

Return Values

If no error occurs, WSAJoinLeaf returns a value of type SOCKET which is a descriptor for the newly created multipoint socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code may be retrieved by calling WSAGetLastError.

On a blocking socket, the return value indicates success or failure of the join operation.

With a nonblocking socket, successful initiation of a join operation is indicated by a return of a valid socket descriptor. Subsequently, an FD_CONNECT indication will be given when the join operation completes, either successfully or otherwise. The application must use either WSAAsyncSelect or WSAEventSelect with interest registered for the FD_CONNECT event in order to determine when the join operation has completed. Note that the select function cannot be used to determine when the join operation completes.

Also, until the multipoint session join attempt completes all subsequent calls to WSAJoinLeaf on the same socket will fail with the error code WSAEALREADY.

If the return error code indicates the multipoint session join attempt failed (that is, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) the application may call WSAJoinLeaf again for the same socket.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEADDRINUSE	The specified address is already in use.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEALREADY	A nonblocking WSAJoinLeaf call is in progress on the specified socket.
WSAEADDRNOTAVAIL	The specified address is not available from the local machine.
WSAEAFNOSUPPORT	Addresses in the specified family cannot be used with this socket.
WSAECONNREFUSED	The attempt to join was forcefully rejected.
WSAEFAULT	The name or the namelen argument is not a valid part of the user address space, the namelen argument is too small, the buffer length for lpCalleeData, lpSQOS, and lpGQOS are too small, or the buffer length for lpCallerData is too large.
WSAEISCONN	The socket is already member of the multipoint session.
WSAENETUNREACH	The network cannot be reached from this host at this time.
WSAENOBUFS	No buffer space is available. The socket cannot be joined.
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	The flow specifications specified in lpSQOS and lpGQOS cannot be satisfied.
WSAEPROTONOSUPPORT	The lpCallerData augment is not supported by the service provider.
WSAETIMEDOUT	Attempt to join timed out without establishing a multipoint session.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the multipoint session join operation cannot be completed immediately. It is possible to select the socket while it is connecting by selecting it for writing.
See Also

accept, bind, select, WSAAccept, WSAAsyncSelect, WSAEventSelect, WSASocket


WSALookupServiceBegin

The Windows Sockets WSALookupServiceBegin function initiates a client query that is constrained by the information contained within a WSAQUERYSET structure. WSALookupServiceBegin only returns a handle, which should be used by subsequent calls to WSALookupServiceNext to get the actual results.

INT WSALookupServiceBegin (

LPWSAQUERYSET lpqsRestrictions,
DWORD dwControlFlags,
LPHANDLE lphLookup
);
Parameters

lpqsRestrictions

[in] Contains the search criteria. See below for details.

dwControlFlags

[in] Controls the depth of the search.

LUP_DEEP	Query deep as opposed to just the first level.
LUP_CONTAINERS	Return containers only
LUP_NOCONTAINERS	Do not return any containers
LUP_FLUSHCACHE	If the provider has been caching information, ignore the cache and go query the name space itself.
LUP_NEAREST	If possible, return results in the order of distance. The measure of distance is provider specific.
LUP_RES_SERVICE	This indicates whether prime response is in the remote or local part of CSADDR_INFO structure. The other part needs to be "usable" in either case.
LUP_RETURN_ALIAS	Any available alias information is to be returned in successive calls to WSALookupServiceNext, and each alias returned will have the RESULT_IS_ALIAS flag set.
LUP_RETURN_NAME	Retrieve the name
LUP_RETURN_TYPE	Retrieve the type
LUP_RETURN_VERSION	Retrieve the version
LUP_RETURN_COMMENT	Retrieve the comment
LUP_RETURN_ADDR	Retrieve the addresses
LUP_RETURN_BLOB	Retrieve the private data
LUP_RETURN_ALL	Retrieve all of the information
lphLookup

[out] Handle to be used when calling WSALookupServiceNext in order to start retrieving the results set.

Remarks

If LUP_CONTAINERS is specified in a call, all other restriction values should be avoided. If any are supplied, it is up to the name service provider to decide if it can support this restriction over the containers. If it cannot, it should return an error.

Some name service providers may have other means of finding containers. For example, containers might all be of some well-known type, or of a set of well-known types, and therefore a query restriction may be created for finding them. No matter what other means the name service provider has for locating containers, LUP_CONTAINERS and LUP_NOCONTAINERS take precedence. Hence, if a query restriction is given that includes containers, specifying LUP_NOCONTAINERS will prevent the container items from being returned. Similarly, no matter the query restriction, if LUP_CONTAINERS is given, only containers should be returned. If a name space does not support containers, and LUP_CONTAINERS is specified, it should simply return WSANO_DATA.

The preferred method of obtaining the containers within another container, is the call:

dwStatus = WSALookupServiceBegin(

      lpqsRestrictions,

      LUP_CONTAINERS,

      lphLookup);

followed by the requisite number of WSALookupServiceNext calls. This will return all containers contained immediately within the starting context; that is, it is not a deep query. With this, one can map the address space structure by walking the hierarchy, perhaps enumerating the content of selected containers. Subsequent uses of WSALookupServiceBegin use the containers returned from a previous call.

Forming Queries

As mentioned above, a WSAQUERYSET structure is used as an input parameter to WSALookupBegin in order to qualify the query. The following table indicates how the WSAQUERYSET is used to construct a query. When a field is marked as (Optional) a NULL pointer may be supplied, indicating that the field will not be used as a search criteria. See section Query-Related Data Structures for additional information.

WSAQUERYSET Field Name	Query Interpretation
dwSize	Must be set to sizeof(WSAQUERYSET). This is a versioning mechanism.
dwOutputflags	Ignored for queries.
lpszServiceInstanceName	(Optional) Referenced string contains service name. The semantics for wildcarding within the string are not defined, but may be supported by certain name space providers.
lpServiceClassId	(Required) The GUID corresponding to the service class.
lpVersion	(Optional) References desired version number and provides version comparison semantics (that is, version must match exactly, or version must be not less than the value supplied).
lpszComment	Ignored for queries.
dwNameSpace1	Identifier of a single name space in which to constrain the search, or NS_ALL to include all name spaces.
lpNSProviderId	(Optional) References the GUID of a specific name space provider, and limits the query to this provider only.
lpszContext	(Optional) Specifies the starting point of the query in a hierarchical name space.
dwNumberOfProtocols	Size of the protocol constraint array, may be zero.
lpafpProtocols	(Optional) References an array of AFPROTOCOLS structure. Only services that utilize these protocols will be returned.
lpszQueryString	(Optional) Some namespaces (such as whois++) support enriched SQL like queries which are contained in a simple text string. This parameter is used to specify that string.
dwNumberOfCsAddrs	Ignored for queries.
lpcsaBuffer	Ignored for queries.
lpBlob	(Optional) This is a pointer to a provider-specific entity.
1 See the Important note below
Important  In most instances, applications interested in only a particular transport protocol should constrain their query by address family and protocol rather than by name space. This would allow an application that needs to locate a TCP/IP service, for example, to have its query processed by all available name spaces such as the local hosts file, DNS, and NIS.

Return Values

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSANO_DATA	The name was found in the database but no data matching the given restrictions was located.
WSANOTINITIALIZED	The Windows Sockets 2 DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
WSASERVICE_NOT_FOUND	No such service is known. The service cannot be found in the specified name space.
See Also

WSALookupServiceEnd and WSALookupServiceNext


WSALookupServiceEnd

The Windows Sockets WSALookupServiceEnd function is called to free the handle after previous calls to WSALookupServiceBegin and WSALookupServiceNext.

Note that if you call WSALookupServiceEnd from another thread while an existing WSALookupServiceNext is blocked, the end call will have the same effect as a cancel and will cause the WSALookupServiceNext call to return immediately.

INT WSALookupServiceEnd (

HANDLE hLookup
);
Parameters

hLookup

[in] Handle previously obtained by calling WSALookupServiceBegin.

Return Values

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSA_INVALID_HANDLE	The Handle is not valid
WSANOTINITIALIZED	The Windows Sockets 2 DLL has not been initialized. The application must first call WSAStartup before calling any Windows Socketsfunctions.
See Also

WSALookupServiceBegin and WSALookupServiceNext


WSALookupServiceNext

The Windows Sockets WSALookupServiceNext function is called after obtaining a handle from a previous call to WSALookupServiceBegin in order to retrieve the requested service information.

The provider will pass back a WSAQUERYSET structure in the lpqsResults buffer. The client should continue to call this function until it returns WSA_E_NOMORE, indicating that all of WSAQUERYSET has been returned.

INT WSALookupServiceNext (

HANDLE hLookup,
DWORD dwControlFlags,
LPDWORD lpdwBufferLength,
LPWSAQUERYSET lpqsResults
);
Parameters

hLookup

[in] Handle returned from the previous call to WSALookupServiceBegin.

dwControlFlags

[in] Flags to control the next operation. This is currently used to indicate to the provider what to do if the result set is too big for the buffer. If on the previous call to WSALookupServiceNext the result set was too large for the buffer, the application can choose to do one of two things on this call. First, it can choose to pass a bigger buffer and try again. Second, if it cannot or is unwilling to allocate a larger buffer, it can pass LUP_FLUSHPREVIOUS to tell the provider to throw away the last result set, which was too large, and move on to the next set for this call.

lpdwBufferLength

[in/out] On input, the number of bytes contained in the buffer pointed to by lpresResults. On output, if the function fails and the error is WSAEFAULT, then it contains the minimum number of bytes to pass for the lpqsResults to retrieve the record.

lpqsResults

[out] A pointer to a block of memory, which will contain one result set in a WSAQUERYSET structure on return.

Query Results

The following table describes how the query results are represented in the WSAQUERYSET structure.

WSAQUERYSET Field Name	Result Interpretation
dwSize	Will be set to sizeof(WSAQUERYSET). This is used as a versioning mechanism.
dwOuputFlags	RESULT_IS_ALIAS flag indicates this is an alias result.
lpszServiceInstanceName	Referenced string contains service name.
lpServiceClassId	The GUID corresponding to the service class.
lpVersion	References version number of the particular service instance.
lpszComment	Optional comment string supplied by service instance.
dwNameSpace	Name space in which the service instance was found.
lpNSProviderId	Identifies the specific name space provider that supplied this query result.
lpszContext	Specifies the context point in a hierarchical name space at which the service is located.
dwNumberOfProtocols	Undefined for results.
lpafpProtocols	Undefined for results, all needed protocol information is in the CSADDR_INFO structures.
lpszQueryString	Undefined for results.
dwNumberOfCsAddrs	Indicates the number of elements in the array of CSADDR_INFO structures.
lpcsaBuffer	A pointer to an array of CSADDR_INFO structures, with one complete transport address contained within each element.
lpBlob	(Optional) This is a pointer to a provider-specific entity.
Return Values

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSA_E_NO_MORE	There is no more data available.
WSA_E_CANCELLED	A call to WSALookupServiceEnd was made while this call was still processing. The call has been canceled. The data in the lpqsResults buffer is undefined.
WSAEFAULT	The lpqsResults buffer was too small to contain a WSAQUERYSET set.
WSA_INVALID_HANDLE	The specified Lookup handle is invalid.
WSANOTINITIALIZED	The Windows Sockets 2 DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
WSANO_DATA	The name was ound in the database, but no data matching the given restrictions was located.
WSASERVICE_NOT_FOUND	No such service is known. The service cannot be found in the specified name space.
See Also

WSALookupServiceBegin and WSALookupServiceEnd


WSANtohl

The Windows Sockets WSANtohl function converts a u_long from network byte order to host byte order.

int WSANtohl (

SOCKET s,
u_long netlong,
u_long FAR * lphostlong
);
Parameters

s

[in] A descriptor identifying a socket.

netlong

[in] A 32-bit number in network byte order.

lphostlong

[out] A pointer to a 32-bit number in host byte order.

Remarks

This routine takes a 32-bit number in the network byte order associated with socket s and returns a 32-bit number pointed to by the lphostlong parameter in host byte order.

Return Values

If no error occurs, WSANtohl returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAENOTSOCK	The descriptor is not a socket.
WSAEFAULT	The lphostlong argument is not totally contained in a valid part of the user address space.
See Also

htonl, htons, ntohl, ntohs, WSAHtonl, WSAHtons, WSANtohs


WSANtohs

The Windows Sockets WSANtohs function converts a u_short from network byte order to host byte order.

int WSANtohs (

SOCKET s,
u_short netshort,
u_short FAR * lphostshort
);
Parameters

s

[in] A descriptor identifying a socket.

netshort

[in] A 16-bit number in network byte order.

lphostshort

[out] A pointer to a 16-bit number in host byte order.

Remarks

This routine takes a 16-bit number in the network byte order associated with socket s and returns a 16-bit number pointed to by the lphostshort parameter in host byte order.

Return Values

If no error occurs, WSANtohs returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAENOTSOCK	The descriptor is not a socket.
WSAEFAULT	The lphostshort argument is not totally contained in a valid part of the user address space.
See Also

htonl, htons, ntohl, ntohs, WSAHtonl, WSANtohl, WSAHtons


WSARecv

The Windows Sockets WSARecv function receives data from a socket.

int WSARecv (

SOCKET s,
LPWSABUF lpBuffers,
DWORD dwBufferCount,
LPDWORD lpNumberOfBytesRecvd,
LPDWORD lpFlags,
LPWSAOVERLAPPED lpOverlapped,
LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionROUTINE
);
Parameters

s

[in] A descriptor identifying a connected socket.

lpBuffers

[in/out] A pointer to an array of WSABUF structures. Each WSABUF structure contains a pointer to a buffer and the length of the buffer.

dwBufferCount

[in] The number of WSABUF structures in the lpBuffers array.

lpNumberOfBytesRecvd

[out] A pointer to the number of bytes received by this call if the receive operation completes immediately.

lpFlags

[in/out] A pointer to flags.

lpOverlapped

[in] A pointer to a WSAOVERLAPPED structure (ignored for nonoverlapped sockets).

lpCompletionRoutine

[in] A pointer to the completion routine called when the receive operation has been completed (ignored for nonoverlapped sockets).

Remarks

This function provides functionality over and above the standard recv function in three important areas:

1.	It can be used in conjunction with overlapped sockets to perform overlapped receive operations.

2.	It allows multiple receive buffers to be specified making it applicable to the scatter/gather type of I/O.

3.	The lpFlags parameter is both an INPUT and an OUTPUT parameter, allowing applications to sense the output state of the MSG_PARTIAL flag bit. Note however, that the MSG_PARTIAL flag bit is not supported by all protocols.

WSARecv is used on connected sockets or bound connectionless sockets specified by the s parameter and is used to read incoming data.

For overlapped sockets WSARecv is used to post one or more buffers into which incoming data will be placed as it becomes available, after which the application-specified completion indication (invocation of the completion routine or setting of an event object) occurs. If the operation does not complete immediately, the final completion status is retrieved through the completion routine or WSAGetOverlappedResult.

If both lpOverlapped and lpCompletionRoutine are NULL, the socket in this function will be treated as a nonoverlapped socket.

For nonoverlapped sockets, the blocking semantics are identical to that of the standard recv function and the lpOverlapped and lpCompletionRoutine parameters are ignored. Any data which has already been received and buffered by the transport will be copied into the supplied user buffers. For the case of a blocking socket with no data currently having been received and buffered by the transport, the call will block until data is received.

The supplied buffers are filled in the order in which they appear in the array pointed to by lpBuffers, and the buffers are packed so that no holes are created.

The array of WSABUF structures pointed to by the lpBuffers parameter is transient. If this operation completes in an overlapped manner, it is the service provider’s responsibility to capture these WSABUF structures before returning from this call. This enables applications to build stack-based WSABUF arrays.

For byte stream style sockets (for example, type SOCK_STREAM), incoming data is placed into the buffers until the buffers are filled, the connection is closed, or internally buffered data is exhausted. Regardless of whether or not the incoming data fills all the buffers, the completion indication occurs for overlapped sockets. For message-oriented sockets (for example, type SOCK_DGRAM), an incoming message is placed into the supplied buffers, up to the total size of the buffers supplied, and the completion indication occurs for overlapped sockets. If the message is larger than the buffers supplied, the buffers are filled with the first part of the message. If the MSG_PARTIAL feature is supported by the underlying service provider, the MSG_PARTIAL flag is set in lpFlags and subsequent receive operations will retrieve the rest of the message. If MSG_PARTIAL is not supported but the protocol is reliable, WSARecv generates the error WSAEMSGSIZE and a subsequent receive operation with a larger buffer can be used to retrieve the entire message. Otherwise, (that is, the protocol is unreliable and does not support MSG_PARTIAL), the excess data is lost, and WSARecv generates the error WSAEMSGSIZE.

For connection-oriented sockets, WSARecv can indicate the graceful termination of the virtual circuit in one of two ways, depending on whether the socket is a byte stream or message oriented. For byte streams, zero bytes having been read indicates graceful closure and that no more bytes will ever be read. For message-oriented sockets, where a zero byte message is often allowable, a return error code of WSAEDISCON is used to indicate graceful closure. In any case a return error code of WSAECONNRESET indicates an abortive close has occurred.

lpFlags may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the lpFlags parameter. The latter is constructed by or-ing any of the following values:

Value	Meaning
MSG_PEEK	Peek at the incoming data. The data is copied into the buffer but is not removed from the input queue. This flag is valid only for nonoverlapped sockets.
MSG_OOB	Process out-of-band data. (See section Out-Of-Band data for a discussion of this topic.)
MSG_PARTIAL	This flag is for message-oriented sockets only. On output, indicates that the data supplied is a portion of the message transmitted by the sender. Remaining portions of the message will be supplied in subsequent receive operations. A subsequent receive operation with MSG_PARTIAL flag cleared indicates end of sender’s message. As an input parameter, this flag indicates that the receive operation should complete even if only part of a message has been received by the service provider.
For message-oriented sockets, the MSG_PARTIAL bit is set in the lpFlags parameter if a partial message is received. If a complete message is received, MSG_PARTIAL is cleared in lpFlags. In the case of delayed completion, the value pointed to by lpFlags is not updated. When completion has been indicated the application should call WSAGetOverlappedResult and examine the flags pointed to by the lpdwFlags parameter.

Overlapped socket I/O:

If an overlapped operation completes immediately, WSARecv returns a value of zero and the lpNumberOfBytesRecvd parameter is updated with the number of bytes received and the flag bits pointed by the lpFlags parameter are also updated. If the overlapped operation is successfully initiated and will complete later, WSARecv returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, lpNumberOfBytesRecvd and lpFlags are not updated. When the overlapped operation completes the amount of data transferred is indicated either through the cbTransferred parameter in the completion routine (if specified), or through the lpcbTransfer parameter in WSAGetOverlappedResult. Flag values are obtained by examining the lpdwFlags parameter of WSAGetOverlappedResult.

This function may be called from within the completion routine of a previous WSARecv, WSARecvFrom, WSASend or WSASendTo function. For a given socket, I/O completion routines will not be nested. This permits time-sensitive data transmissions to occur entirely within a preemptive context.

The lpOverlapped parameter must be valid for the duration of the overlapped operation. If multiple I/O operations are simultaneously outstanding, each must reference a separate overlapped structure. The WSAOVERLAPPED structure has the following form:

typedef struct _WSAOVERLAPPED {

    DWORD        Internal;        // reserved

    DWORD        InternalHigh;    // reserved

    DWORD        Offset;          // reserved

    DWORD        OffsetHigh;      // reserved

    WSAEVENT     hEvent;

} WSAOVERLAPPED, FAR * LPWSAOVERLAPPED;

If the lpCompletionRoutine parameter is NULL, the hEvent field of lpOverlapped is signaled when the overlapped operation completes if it contains a valid event object handle. An application can use WSAWaitForMultipleEvents or WSAGetOverlappedResult to wait or poll on the event object.

If lpCompletionRoutine is not NULL, the hEvent field is ignored and can be used by the application to pass context information to the completion routine.

The completion routine follows the same rules as stipulated for Win32 file I/O completion routines. The completion routine will not be invoked until the thread is in an alertable wait state such as can occur when the function WSAWaitForMultipleEvents with the fAlertable parameter set to TRUE is invoked.

The transport providers allow an application to invoke send and receive operations from within the context of the socket I/O completion routine, and guarantee that, for a given socket, I/O completion routines will not be nested. This permits time-sensitive data transmissions to occur entirely within a preemptive context.

The prototype of the completion routine is as follows:

void CALLBACK CompletionROUTINE(
 IN DWORD dwError,
 IN DWORD cbTransferred,
 IN LPWSAOVERLAPPEDlpOverlapped,
 IN DWORD dwFlags
);

CompletionRoutine is a placeholder for an application-defined or library-defined function name. dwError specifies the completion status for the overlapped operation as indicated by lpOverlapped. cbTransferred specifies the number of bytes received. dwFlags contains information that would have appeared in lpFlags if the receive operation had completed immediately. This function does not return a value.

Returning from this function allows invocation of another pending completion routine for this socket. When using WSAWaitForMultipleEvents, all waiting completion routines are called before the alertable thread’s wait is satisfied with a return code of WSA_IO_COMPLETION. The completion routines may be called in any order, not necessarily in the same order the overlapped operations are completed. However, the posted buffers are guaranteed to be filled in the same order they are supplied.

Return Values

If no error occurs and the receive operation has completed immediately, WSARecv returns zero. Note that in this case, the completion routine will have already been scheduled, and to be called once the calling thread is in the alertable state. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError. The error code WSA_IO_PENDING indicates that the overlapped operation has been successfully initiated and that completion will be indicated at a later time. Any other error code indicates that the overlapped operation was not successfully initiated and no completion indication will occur.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAENOTCONN	The socket is not connected.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAENETRESET	The connection has been broken due to the remote host resetting.
WSAENOTSOCK	The descriptor is not a socket.
WSAEFAULT	The lpBuffers argument is not totally contained in a valid part of the user address space.
WSAEOPNOTSUPP	MSG_OOB was specified, but the socket is not stream style such as type SOCK_STREAM, out-of-band data is not supported in the communication domain associated with this socket, or the socket is unidirectional and supports only send operations.
WSAESHUTDOWN	The socket has been shut down; it is not possible to WSARecv on a socket after shutdown has been invoked with how set to SD_RECEIVE or SD_BOTH.
WSAEWOULDBLOCK	Overlapped sockets: There are too many outstanding overlapped I/O requests. Nonoverlapped sockets: The socket is marked as nonblocking and the receive operation cannot be completed immediately.
WSAEMSGSIZE	The message was too large to fit into the specified buffer and (for unreliable protocols only) any trailing portion of the message that did not fit into the buffer has been discarded.
WSAEINVAL	The socket has not been bound with bind, or the socket is not created with the overlapped flag.
WSAECONNABORTED	The virtual circuit was terminated due to a time-out or other failure.
WSAECONNRESET	The virtual circuit was reset by the remote side.
WSAEDISCON	Socket s is message oriented and the virtual circuit was gracefully closed by the remote side.
WSA_IO_PENDING	An overlapped operation was successfully initiated and completion will be indicated at a later time.
WSA_OPERATION_ABORTED	The overlapped operation has been canceled due to the closure of the socket.
See Also

WSACloseEvent, WSACreateEvent, WSAGetOverlappedResult, WSASocket, WSAWaitForMultipleEvents


WSARecvDisconnect

The Windows Sockets WSARecvDisconnect function terminates reception on a socket, and retrieves the disconnect data if the socket is connection oriented.

int WSARecvDisconnect (

SOCKET s,
LPWSABUF lpInboundDisconnectData
);
Parameters

s

[in] A descriptor identifying a socket.

lpInboundDisconnectData

[out] A pointer to the incoming disconnect data.

Remarks

WSARecvDisconnect is used on connection-oriented sockets to disable reception, and retrieve any incoming disconnect data from the remote party.

After this function has been successfully issued, subsequent receives on the socket will be disallowed. This has no effect on the lower protocol layers. For TCP, the TCP window is not changed and incoming data will be accepted (but not acknowledged) until the window is exhausted. For UDP, incoming datagrams are accepted and queued. In no case will an ICMP error packet be generated.

To successfully receive incoming disconnect data, an application must use other mechanisms to determine that the circuit has been closed. For example, an application needs to receive an FD_CLOSE notification, or get a zero return value, or a WSAEDISCON or WSAECONNRESET error code from recv/WSARecv.

Note that WSARecvDisconnect does not close the socket, and resources attached to the socket will not be freed until closesocket is invoked.

Comments

WSARecvDisconnect does not block regardless of the SO_LINGER setting on the socket.

An application should not rely on being able to re-use a socket after it has been WSARecvDisconnected. In particular, a Windows Sockets provider is not required to support the use of connect/WSAConnect on such a socket.

Return Values

If no error occurs, WSARecvDisconnect returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	The buffer referenced by the parameter lpInboundDisconnectData is too small.
WSAENOPROTOOPT	The disconnect data is not supported by the indicated protocol family.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAENOTCONN	The socket is not connected (connection-oriented sockets only).
WSAENOTSOCK	The descriptor is not a socket.
See Also

connect, socket


WSARecvEx

Notice  This function is a Microsoft-specific extension to the Windows Sockets specification. For more information, see Microsoft Extensions and Windows Sockets 2.

The Windows Sockets WSARecvEx function is identical to the recv function, except the flags parameter is an in-out parameter. When a partial message is received while using datagram protocol, the MSG_PARTIAL bit is set in the flags parameter on return from the function.

int PASCAL FAR WSARecvEx (

SOCKET s,
char FAR * buf,
int len,
int *flags
);
Parameters

s

[in] A descriptor identifying a connected socket.

buf

[out] A buffer for the incoming data.

len

[in] The length of buf.

flags

[in/out] Specifies whether the message is fully or partiall received for datagram sockets.

Remarks

By default, for message-oriented transport protocols the Windows Sockets recv function receives a single message in each call to the function. This works fine for most cases, but there are two situations in which this is insufficient: when the application’s data buffer is smaller than the message, and when the message is large and arrives in several pieces.

When the buffer is smaller than the data, as much of the message as will fit is copied into the user’s buffer and recv returns with the error code WSAEMSGSIZE. A subsequent call to recv will get the next part of the message. Applications written for message-oriented transport protocols should be coded for this possibility if message sizing is not guaranteed by the application’s data transfer protocol. If an application gets this error code, then the entire data buffer is filled with data.

It is more complicated when a very large message arrives a little at a time. For example, if an application sends a 1-megabyte message, the transport protocol must break up the message in order to send it over the physical network. It is theoretically possible for the transport protocol on the receiving side to buffer all the data in the message, but this would be quite expensive in terms of resources.

It would be better to allow a recv call to complete with only a partial message and some indication to the application that the data is only a partial message. However, the Windows Sockets recv function has only one output parameter: a pointer to the buffer for the incoming data. Therefore, Windows NT supplies the WSARecvEx function, which is identical to the recv function except that the flags parameter is an in-out parameter:

Return Values

On return from WSARecvEx, if a partial message was received, the MSG_PARTIAL bit is set in the flags parameter. If a complete message was received, MSG_PARTIAL is not set in flags. For a stream-oriented transport protocol, MSG_PARTIAL is never set on return from WSARecvEx; for stream transport protocols, this function behaves identically to the Windows Sockets recv function.


WSARecvFrom

The Windows Sockets WSARecvFrom function receives a datagram and stores the source address.

int WSARecvFrom (

SOCKET s,
LPWSABUF lpBuffers,
DWORD dwBufferCount,
LPDWORD lpNumberOfBytesRecvd,
LPDWORD lpFlags,
struct sockaddr FAR * lpFrom,
LPINT lpFromlen,
LPWSAOVERLAPPED lpOverlapped,
LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionROUTINE
);
Parameters

s

[in] A descriptor identifying a socket

lpBuffers

[in/out] A pointer to an array of WSABUF structures. Each WSABUF structure contains a pointer to a buffer and the length of the buffer.

dwBufferCount

[in] The number of WSABUF structures in the lpBuffers array.

lpNumberOfBytesRecvd

[out] A pointer to the number of bytes received by this call if the receive operation completes immediately.

lpFlags

[in/out] A pointer to flags.

lpFrom

[out] An optional pointer to a buffer which will hold the source address upon the completion of the overlapped operation.

lpFromlen

[in/out] A pointer to the size of the from buffer, required only if lpFrom is specified.

lpOverlapped

[in] A pointer to a WSAOVERLAPPED structure (ignored for nonoverlapped sockets).

lpCompletionRoutine

[in] A pointer to the completion routine called when the receive operation has been completed (ignored for nonoverlapped sockets).

Remarks

This function provides functionality over and above the standard recvfrom function in three important areas:

1.	It can be used in conjunction with overlapped sockets to perform overlapped receive operations.

2.	It allows multiple receive buffers to be specified making it applicable to the scatter/gather type of I/O.

3.	The lpFlags parameter is both an INPUT and an OUTPUT parameter, allowing applications to sense the output state of the MSG_PARTIAL flag bit. Note however, that the MSG_PARTIAL flag bit is not supported by all protocols.

WSARecvFrom is used primarily on a connectionless socket specified by s.

For overlapped sockets, this function is used to post one or more buffers into which incoming data will be placed as it becomes available on a (possibly connected) socket, after which the application-specified completion indication (invocation of the completion routine or setting of an event object) occurs. If the operation does not complete immediately, the final completion status is retrieved through the completion routine or WSAGetOverlappedResult. Also note that the values pointed to by lpFrom and lpFromlen are not updated until completion is indicated. Applications must not use or disturb these values until they have been updated, therefore the application must not use automatic (that is, stack-based) variables for these parameters.

If both lpOverlapped and lpCompletionRoutine are NULL, the socket in this function will be treated as a nonoverlapped socket.

For nonoverlapped sockets, the blocking semantics are identical to that of the standard recvfrom function and the lpOverlapped and lpCompletionRoutine parameters are ignored. Any data which has already been received and buffered by the transport will be copied into the supplied user buffers. For the case of a blocking socket with no data currently having been received and buffered by the transport, the call will block until data is received.

The supplied buffers are filled in the order in which they appear in the array pointed to by lpBuffers, and the buffers are packed so that no holes are created.

The array of WSABUF structures pointed to by the lpBuffers parameter is transient. If this operation completes in an overlapped manner, it is the service provider’s responsibility to capture these WSABUF structures before returning from this call. This enables applications to build stack-based WSABUF arrays.

For connectionless socket types, the address from which the data originated is copied to the buffer pointed by lpFrom. The value pointed to by lpFromlen is initialized to the size of this buffer, and is modified on completion to indicate the actual size of the address stored there. As noted previously for overlapped sockets, the lpFrom and lpFromlen parameters are not updated until after the overlapped I/O has completed. The memory pointed to by these parameters must, therefore, remain available to the service provider and cannot be allocated on the application’s stack frame. The lpFrom and lpFromlen parameters are ignored for connection-oriented sockets.

For byte stream style sockets (for example, type SOCK_STREAM), incoming data is placed into the buffers until the buffers are filled, the connection is closed, or internally buffered data is exhausted. Regardless of whether or not the incoming data fills all the buffers, the completion indication occurs for overlapped sockets. For message-oriented sockets, an incoming message is placed into the supplied buffers, up to the total size of the buffers supplied, and the completion indication occurs for overlapped sockets. If the message is larger than the buffers supplied, the buffers are filled with the first part of the message. If the MSG_PARTIAL feature is supported by the underlying service provider, the MSG_PARTIAL flag is set in lpFlags and subsequent receive operation(s) will retrieve the rest of the message. If MSG_PARTIAL is not supported but the protocol is reliable, WSARecvFrom generates the error WSAEMSGSIZE and a subsequent receive operation with a larger buffer can be used to retrieve the entire message. Otherwise, (that is, the protocol is unreliable and does not support MSG_PARTIAL), the excess data is lost, and WSARecvFrom generates the error WSAEMSGSIZE.

For connection-oriented sockets, WSARecvFrom can indicate the graceful termination of the virtual circuit in one of two ways, depending on whether the socket is a byte stream or message oriented. For byte streams, zero bytes read indicates graceful closure and that no more bytes will ever be read. For message-oriented sockets, where a zero byte message is often allowable, a return error code of WSAEDISCONN is used to indicate graceful closure. In any case, a return error code of WSAECONNRESET indicates an abortive close has occurred.

lpFlags may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the lpFlags parameter. The latter is constructed by or-ing any of the following values:

Value	Meaning
MSG_PEEK	Peek at the incoming data. The data is copied into the buffer but is not removed from the input queue. This flag is valid only for nonoverlapped sockets.
MSG_OOB	Process out-of-band data. (See section Out-Of-Band data for a discussion of this topic.)
MSG_PARTIAL	This flag is for message-oriented sockets only. On output, indicates that the data supplied is a portion of the message transmitted by the sender. Remaining portions of the message will be supplied in subsequent receive operations. A subsequent receive operation with MSG_PARTIAL flag cleared indicates end of sender’s message. As an input parameter indicates that the receive operation should complete even if only part of a message has been received by the service provider.
For message-oriented sockets, the MSG_PARTIAL bit is set in the lpFlags parameter if a partial message is received. If a complete message is received, MSG_PARTIAL is cleared in lpFlags. In the case of delayed completion, the value pointed to by lpFlags is not updated. When completion has been indicated the application should call WSAGetOverlappedResult and examine the flags pointed to by the lpdwFlags parameter.

Overlapped socket I/O:

If an overlapped operation completes immediately, WSARecv returns a value of zero and the lpNumberOfBytesRecvd parameter is updated with the number of bytes received and the flag bits pointed by the lpFlags parameter are also updated. If the overlapped operation is successfully initiated and will complete later, WSARecv returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, lpNumberOfBytesRecvd and lpFlags is not updated. When the overlapped operation completes the amount of data transferred is indicated either through the cbTransferred parameter in the completion routine (if specified), or through the lpcbTransfer parameter in WSAGetOverlappedResult. Flag values are obtained either through the dwFlags parameter of the completion routine, or by examining the lpdwFlags parameter of WSAGetOverlappedResult.

This function may be called from within the completion routine of a previous WSARecv, WSARecvFrom, WSASend or WSASendTo function. For a given socket, I/O completion routines will not be nested. This permits time-sensitive data transmissions to occur entirely within a preemptive context.

The lpOverlapped parameter must be valid for the duration of the overlapped operation. If multiple I/O operations are simultaneously outstanding, each must reference a separate overlapped structure. The WSAOVERLAPPED structure has the following form:

typedef struct _WSAOVERLAPPED {

    DWORD        Internal;        // reserved

    DWORD        InternalHigh;    // reserved

    DWORD        Offset;          // reserved

    DWORD        OffsetHigh;      // reserved

    WSAEVENT     hEvent;

} WSAOVERLAPPED, FAR * LPWSAOVERLAPPED;

If the lpCompletionRoutine parameter is NULL, the hEvent field of lpOverlapped is signaled when the overlapped operation completes if it contains a valid event object handle. An application can use WSAWaitForMultipleEvents or WSAGetOverlappedResult to wait or poll on the event object.

If lpCompletionRoutine is not NULL, the hEvent field is ignored and can be used by the application to pass context information to the completion routine.

The completion routine follows the same rules as stipulated for Win32 file I/O completion routines. The completion routine will not be invoked until the thread is in an alertable wait state such as can occur when the function WSAWaitForMultipleEvents with the fAlertable parameter set to TRUE is invoked.

The transport providers allow an application to invoke send and receive operations from within the context of the socket I/O completion routine, and guarantee that, for a given socket, I/O completion routines will not be nested. This permits time-sensitive data transmissions to occur entirely within a preemptive context.

The prototype of the completion routine is as follows:

void CALLBACK CompletionROUTINE(
 IN DWORD dwError,
 IN DWORD cbTransferred,
 IN LPWSAOVERLAPPED lpOverlapped,
 IN DWORD dwFlags
);

CompletionRoutine is a placeholder for an application-defined or library-defined function name. dwError specifies the completion status for the overlapped operation as indicated by lpOverlapped. cbTransferred specifies the number of bytes received. dwFlags contains information that would have appeared in lpFlags if the receive operation had completed immediately. This function does not return a value.

Returning from this function allows invocation of another pending completion routine for this socket. When using WSAWaitForMultipleEvents, all waiting completion routines are called before the alertable thread’s wait is satisfied with a return code of WSA_IO_COMPLETION. The completion routines may be called in any order, not necessarily in the same order the overlapped operations are completed. However, the posted buffers are guaranteed to be filled in the same order they are supplied.

Return Values

If no error occurs and the receive operation has completed immediately, WSARecvFrom returns zero. Note that in this case, the completion routine will have already been scheduled, and to be called once the calling thread is in the alertable state. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError. The error code WSA_IO_PENDING indicates that the overlapped operation has been successfully initiated and that completion will be indicated at a later time. Any other error code indicates that the overlapped operation was not successfully initiated and no completion indication will occur.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	The lpFromlen argument was invalid: the lpFrom buffer was too small to accommodate the peer address, or the lpBuffers argument is not totally contained in a valid part of the user address space.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINVAL	The socket has not been bound with bind, or the socket is not created with the overlapped flag.
WSAENETRESET	The connection has been broken due to the remote host resetting..
WSAENOTCONN	The socket is not connected (connection-oriented sockets only).
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	MSG_OOB was specified, but the socket is not stream style such as type SOCK_STREAM, out-of-band data is not supported in the communication domain associated with this socket, or the socket is unidirectional and supports only send operations.
WSAESHUTDOWN	The socket has been shut down; it is not possible to WSARecvFrom on a socket after shutdown has been invoked with how set to SD_RECEIVE or SD_BOTH.
WSAEWOULDBLOCK	Overlapped sockets: There are too many outstanding overlapped I/O requests. Nonoverlapped sockets: The socket is marked as nonblocking and the receive operation cannot be completed immediately.
WSAEMSGSIZE	The message was too large to fit into the specified buffer and (for unreliable protocols only) any trailing portion of the message that did not fit into the buffer has been discarded.
WSAECONNABORTED	The virtual circuit was terminated due to a time-out or other failure.
WSAECONNRESET	The virtual circuit was reset by the remote side.
WSAEDISCON	Socket s is message oriented and the virtual circuit was gracefully closed by the remote side.
WSA_IO_PENDING	An overlapped operation was successfully initiated and completion will be indicated at a later time.
WSA_OPERATION_ABORTED	The overlapped operation has been canceled due to the closure of the socket.
See Also

WSACloseEvent, WSACreateEvent, WSAGetOverlappedResult, WSASocket, WSAWaitForMultipleEvents


WSARemoveServiceClass

The Windows Sockets WSARemoveServiceClass function permanently unregisters service class schema.

INT WSARemoveServiceClass(

LPGUID lpServiceClassId
);
Parameters

lpServiceClassId

[in] Pointer to the GUID for the service class you want to remove.

Return Values

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSAETYPE_NOT_FOUND	The specified class was not found.
WSAEACCESS	The calling routine does not have sufficient privileges to remove the Service.
WSANOTINITIALIZED	The Windows Sockets 2 DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
WSAEINVAL	The specified GUID was not valid.


WSAResetEvent

The Windows Sockets WSAResetEvent function resets the state of the specified event object to nonsignaled.

BOOL WSAResetEvent(

WSAEVENT hEvent
);
Parameters

hEvent

[in] Identifies an open event object handle.

Remarks

The state of the event object is set to be nonsignaled.

Return Values

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSA_INVALID_HANDLE	hEvent is not a valid event object handle.
See Also

WSACloseEvent, WSACreateEvent, WSASetEvent


WSASend

The Windows Sockets WSASend function sends data on a connected socket.

int WSASend (

SOCKET s,
LPWSABUF lpBuffers,
DWORD dwBufferCount,
LPDWORD lpNumberOfBytesSent,
DWORD dwFlags,
LPWSAOVERLAPPED lpOverlapped,
LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionROUTINE
);
Parameters

s

[in] A descriptor identifying a connected socket.

lpBuffers

[in] A pointer to an array of WSABUF structures. Each WSABUF structure contains a pointer to a buffer and the length of the buffer. This array must remain valid for the duration of the send operation.

dwBufferCount

[in] The number of WSABUF structures in the lpBuffers array.

lpNumberOfBytesSent

[out] A pointer to the number of bytes sent by this call if the I/O operation completes immediately.

dwFlags

[in] Specifies the way in which the call is made.

lpOverlapped

[in] A pointer to a WSAOVERLAPPED structure (ignored for nonoverlapped sockets).

lpCompletionRoutine

[in] A pointer to the completion routine called when the send operation has been completed (ignored for nonoverlapped sockets).

Remarks

This function provides functionality over and above the standard send function in two important areas:

1.	It can be used in conjunction with overlapped sockets to perform overlapped send operations.

2.	It allows multiple send buffers to be specified making it applicable to the scatter/gather type of I/O.

WSASend is used to write outgoing data from one or more buffers on a connection-oriented socket specified by s. It may also be used, however, on connectionless sockets which have a stipulated default peer address established through the connect or WSAConnect function.

For overlapped sockets (created using WSASocket with flag WSA_FLAG_OVERLAPPED) this will occur using overlapped I/O, unless both lpOverlapped and lpCompletionRoutine are NULL in which case the socket is treated as a nonoverlapped socket. A completion indication will occur (invocation of the completion routine or setting of an event object) when the supplied buffer(s) have been consumed by the transport. If the operation does not complete immediately, the final completion status is retrieved through the completion routine or WSAGetOverlappedResult.

For nonoverlapped sockets, the last two parameters (lpOverlapped, lpCompletionRoutine) are ignored and WSASend adopts the same blocking semantics as send. Data is copied from the supplied buffer(s) into the transport’s buffer. If the socket is nonblocking and stream oriented, and there is not sufficient space in the transport’s buffer, WSASend will return with only part of the application’s buffers having been consumed. Given the same buffer situation and a blocking socket, WSASend will block until all of the application’s buffer contents have been consumed.

The array of WSABUF structures pointed to by the lpBuffers parameter is transient. If this operation is completed in an overlapped manner, it is the service provider’s responsibility to capture these WSABUF structures before returning from this call. This enables applications to build stack-based WSABUF arrays.

For message-oriented sockets, care must be taken not to exceed the maximum message size of the underlying provider, which can be obtained by getting the value of socket option SO_MAX_MSG_SIZE. If the data is too long to pass atomically through the underlying protocol the error WSAEMSGSIZE is returned, and no data is transmitted.

Note that the successful completion of a WSASend does not indicate that the data was successfully delivered.

dwFlags may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the dwFlags parameter. The latter is constructed by or-ing any of the following values:

Value	Meaning
MSG_DONTROUTE	Specifies that the data should not be subject to routing. A Windows Sockets service provider can choose to ignore this flag.
MSG_OOB	Send out-of-band data on a stream-style socket such as SOCK_STREAM only. (See section Out-Of-Band data for a discussion of this topic.)
MSG_PARTIAL	Specifies that lpBuffers only contains a partial message. Note that the error code WSAEOPNOTSUPP will be returned by transports which do not support partial message transmissions.
Overlapped socket I/O:

If an overlapped operation completes immediately, WSASend returns a value of zero and the lpNumberOfBytesSent parameter is updated with the number of bytes sent. If the overlapped operation is successfully initiated and will complete later, WSASend returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, lpNumberOfBytesSent is not updated. When the overlapped operation completes the amount of data transferred is indicated either through the cbTransferred parameter in the completion routine (if specified), or through the lpcbTransfer parameter in WSAGetOverlappedResult.

This function may be called from within the completion routine of a previous WSARecv, WSARecvFrom, WSASend or WSASendTo function. This permits time-sensitive data transmissions to occur entirely within a preemptive context.

The lpOverlapped parameter must be valid for the duration of the overlapped operation. If multiple I/O operations are simultaneously outstanding, each must reference a separate overlapped structure. The WSAOVERLAPPED structure has the following form:

typedef struct _WSAOVERLAPPED {

    DWORD        Internal;        // reserved

    DWORD        InternalHigh;    // reserved

    DWORD        Offset;          // reserved

    DWORD        OffsetHigh;      // reserved

    WSAEVENT     hEvent;

} WSAOVERLAPPED, FAR * LPWSAOVERLAPPED;

If the lpCompletionRoutine parameter is NULL, the hEvent field of lpOverlapped is signaled when the overlapped operation completes if it contains a valid event object handle. An application can use WSAWaitForMultipleEvents or WSAGetOverlappedResult to wait or poll on the event object.

If lpCompletionRoutine is not NULL, the hEvent field is ignored and can be used by the application to pass context information to the completion routine.

The completion routine follows the same rules as stipulated for Win32 file I/O completion routines. The completion routine will not be invoked until the thread is in an alertable wait state such as can occur when the function WSAWaitForMultipleEvents with the fAlertable parameter set to TRUE is invoked.

The transport providers allow an application to invoke send and receive operations from within the context of the socket I/O completion routine, and guarantee that, for a given socket, I/O completion routines will not be nested. This permits time-sensitive data transmissions to occur entirely within a preemptive context.

The prototype of the completion routine is as follows:

void CALLBACK CompletionROUTINE(
 IN DWORD dwError,
 IN DWORD cbTransferred,
 IN LPWSAOVERLAPPED lpOverlapped,
 IN DWORD dwFlags
);

CompletionRoutine is a placeholder for an application-defined or library-defined function name. dwError specifies the completion status for the overlapped operation as indicated by lpOverlapped. cbTransferred specifies the number of bytes sent. Currently there are no flag values defined and dwFlags will be zero. This function does not return a value.

Returning from this function allows invocation of another pending completion routine for this socket. All waiting completion routines are called before the alertable thread’s wait is satisfied with a return code of WSA_IO_COMPLETION. The completion routines may be called in any order, not necessarily in the same order the overlapped operations are completed. However, the posted buffers are guaranteed to be sent in the same order they are supplied.

Return Values

If no error occurs and the send operation has completed immediately, WSASend returns zero. Note that in this case, the completion routine will have already been scheduled, and to be called once the calling thread is in the alertable state. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError. The error code WSA_IO_PENDING indicates that the overlapped operation has been successfully initiated and that completion will be indicated at a later time. Any other error code indicates that the overlapped operation was not successfully initiated and no completion indication will occur.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEACCES	The requested address is a broadcast address, but the appropriate flag was not set.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEFAULT	The lpBuffers argument is not totally contained in a valid part of the user address space.
WSAENETRESET	The connection has been broken due to the remote host resetting.
WSAENOBUFS	The Windows Sockets provider reports a buffer deadlock.
WSAENOTCONN	The socket is not connected.
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	MSG_OOB was specified, but the socket is not stream style such as type SOCK_STREAM, out-of-band data is not supported in the communication domain associated with this socket, MSG_PARTIAL is not supported, or the socket is unidirectional and supports only receive operations.
WSAESHUTDOWN	The socket has been shut down; it is not possible to WSASend on a socket after shutdown has been invoked with how set to SD_SEND or SD_BOTH.
WSAEWOULDBLOCK	Overlapped sockets: There are too many outstanding overlapped I/O requests. Nonoverlapped sockets: The socket is marked as nonblocking and the send operation cannot be completed immediately.
WSAEMSGSIZE	The socket is message oriented, and the message is larger than the maximum supported by the underlying transport.
WSAEINVAL	The socket has not been bound with bind, or the socket is not created with the overlapped flag.
WSAECONNABORTED	The virtual circuit was terminated due to a time-out or other failure.
WSAECONNRESET	The virtual circuit was reset by the remote side.
WSA_IO_PENDING	An overlapped operation was successfully initiated and completion will be indicated at a later time.
WSA_OPERATION_ABORTED	The overlapped operation has been canceled due to the closure of the socket, or the execution of the SIO_FLUSH command in WSAIoctl.
See Also

WSACloseEvent, WSACreateEvent, WSAGetOverlappedResult, WSASocket, WSAWaitForMultipleEvents


WSASendDisconnect

The Windows Sockets WSASendDisconnect function initiates termination of the connection for the socket and sends disconnect data.

int WSASendDisconnect (

SOCKET s,
LPWSABUF lpOUT boundDisconnectData
);
Parameters

s

[in] A descriptor identifying a socket.

lpOutboundDisconnectData

[in] A pointer to the outgoing disconnect data.

Remarks

WSASendDisconnect is used on connection-oriented sockets to disable transmission, and to initiate termination of the connection along with the transmission of disconnect data, if any.

After this function has been successfully issued, subsequent sends are disallowed.

lpOutboundDisconnectData, if not NULL, points to a buffer containing the outgoing disconnect data to be sent to the remote party for retrieval by using WSARecvDisconnect.

Note that WSASendDisconnect does not close the socket, and resources attached to the socket will not be freed until closesocket is invoked.

Comments

WSASendDisconnect does not block regardless of the SO_LINGER setting on the socket.

An application should not rely on being able to re-use a socket after it has been WSASendDisconnected. In particular, a Windows Sockets provider is not required to support the use of connect/WSAConnect on such a socket.

Return Values

If no error occurs, WSASendDisconnect returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAENOPROTOOPT	The parameter lpOutboundDisconnectData is not NULL, and the disconnect data is not supported by the service provider.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAENOTCONN	The socket is not connected (connection-oriented sockets only).
WSAENOTSOCK	The descriptor is not a socket.
WSAEFAULT	The lpOutboundDisconnectData argument is not totally contained in a valid part of the user address space.
See Also

connect, socket


WSASendTo

The Windows Sockets WSASendTo function sends data to a specific destination, using overlapped I/O where applicable.

int WSASendTo (

SOCKET s,
LPWSABUF lpBuffers,
DWORD dwBufferCount,
LPDWORD lpNumberOfBytesSent,
DWORD dwFlags,
const struct sockaddr FAR * lpTo,
int iToLen,
LPWSAOVERLAPPED lpOverlapped,
LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionROUTINE
);
Parameters

s

[in] A descriptor identifying a connected socket which was created using WSASocket with flag WSA_FLAG_OVERLAPPED.

lpBuffers

[in] A pointer to an array of WSABUF structures. Each WSABUF structure contains a pointer to a buffer and the length of the buffer. This array must remain valid for the duration of the send operation.

dwBufferCount

[in] The number of WSABUF structures in the lpBuffers array.

lpNumberOfBytesSent

[out] A pointer to the number of bytes sent by this call if the I/O operation completes immediately.

dwFlags

[in] Specifies the way in which the call is made.

lpTo

[in] An optional pointer to the address of the target socket.

iToLen

[in] The size of the address in lpTo.

lpOverlapped

[in] A pointer to a WSAOVERLAPPED structure (ignored for nonoverlapped sockets).

lpCompletionRoutine

[in] A pointer to the completion routine called when the send operation has been completed (ignored for nonoverlapped sockets).

Remarks

This function provides functionality over and above the standard sendto function in two important areas:

1.	It can be used in conjunction with overlapped sockets to perform overlapped send operations.

2.	It allows multiple send buffers to be specified making it applicable to the scatter/gather type of I/O.

WSASendTo is normally used on a connectionless socket specified by s to send a datagram contained in one or more buffers to a specific peer socket identified by the lpTo parameter. On a connection-oriented socket, the lpTo and iToLen parameters are ignored; in this case, the WSASendTo is equivalent to WSASend.

For overlapped sockets (created using WSASocket with flag WSA_FLAG_OVERLAPPED) this will occur using overlapped I/O, unless both lpOverlapped and lpCompletionRoutine are NULL in which case the socket is treated as a nonoverlapped socket. A completion indication will occur (invocation of the completion routine or setting of an event object) when the supplied buffer(s) have been consumed by the transport. If the operation does not complete immediately, the final completion status is retrieved through the completion routine or WSAGetOverlappedResult.

For nonoverlapped sockets, the last two parameters (lpOverlapped, lpCompletionRoutine) are ignored and WSASendTo adopts the same blocking semantics as send. Data is copied from the supplied buffer(s) into the transport’s buffer. If the socket is nonblocking and stream oriented, and there is not sufficient space in the transport’s buffer, WSASendTo will return with only part of the application’s buffers having been consumed. Given the same buffer situation and a blocking socket, WSASendTo will block until all of the application’s buffer contents have been consumed.

The array of WSABUF structures pointed to by the lpBuffers parameter is transient. If this operation is completed in an overlapped manner, it is the sercvice provider’s responsibility to capture these WSABUF structures before returning from this call. This enables applications to build stack-based WSABUF arrays.

For message-oriented sockets, care must be taken not to exceed the maximum message size of the underlying transport, which can be obtained by getting the value of socket option SO_MAX_MSG_SIZE. If the data is too long to pass atomically through the underlying protocol the error WSAEMSGSIZE is returned, and no data is transmitted.

Note that the successful completion of a WSASendTo does not indicate that the data was successfully delivered.

dwFlags may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the dwFlags parameter. The latter is constructed by or-ing any of the following values:

Value	Meaning
MSG_DONTROUTE	Specifies that the data should not be subject to routing. A Windows Sockets service provider can choose to ignore this flag.
MSG_OOB	Send out-of-band data (stream-style socket such as SOCK_STREAM only).
MSG_PARTIAL	Specifies that lpBuffers only contains a partial message. Note that the error code WSAEOPNOTSUPP will be returned by transports which do not support partial message transmissions.
Overlapped socket I/O:

If an overlapped operation completes immediately, WSASendTo returns a value of zero and the lpNumberOfBytesSent parameter is updated with the number of bytes sent. If the overlapped operation is successfully initiated and will complete later, WSASendTo returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, lpNumberOfBytesSent is not updated. When the overlapped operation completes the amount of data transferred is indicated either through the cbTransferred parameter in the completion routine (if specified), or through the lpcbTransfer parameter in WSAGetOverlappedResult.

This function may be called from within the completion routine of a previous WSARecv, WSARecvFrom, WSASend or WSASendTo function. This permits time-sensitive data transmissions to occur entirely within a preemptive context.

The lpOverlapped parameter must be valid for the duration of the overlapped operation. If multiple I/O operations are simultaneously outstanding, each must reference a separate overlapped structure. The WSAOVERLAPPED structure has the following form:

typedef struct _WSAOVERLAPPED {

    DWORD        Internal;        // reserved

    DWORD        InternalHigh;    // reserved

    DWORD        Offset;          // reserved

    DWORD        OffsetHigh;      // reserved

    WSAEVENT     hEvent;

} WSAOVERLAPPED, FAR * LPWSAOVERLAPPED;

If the lpCompletionRoutine parameter is NULL, the hEvent field of lpOverlapped is signaled when the overlapped operation completes if it contains a valid event object handle. An application can use WSAWaitForMultipleEvents or WSAGetOverlappedResult to wait or poll on the event object.

If lpCompletionRoutine is not NULL, the hEvent field is ignored and can be used by the application to pass context information to the completion routine.

The completion routine follows the same rules as stipulated for Win32 file I/O completion routines. The completion routine will not be invoked until the thread is in an alertable wait state such as can occur when the function WSAWaitForMultipleEvents with the fAlertable parameter set to TRUE is invoked.

Transport providers allow an application to invoke send and receive operations from within the context of the socket I/O completion routine, and guarantee that, for a given socket, I/O completion routines will not be nested. This permits time-sensitive data transmissions to occur entirely within a preemptive context.

The prototype of the completion routine is as follows:

void CALLBACK CompletionROUTINE(
 IN DWORD dwError,
 IN DWORD cbTransferred,
 IN LPWSAOVERLAPPED lpOverlapped,
 IN DWORD dwFlags
);

CompletionRoutine is a placeholder for an application-defined or library-defined function name. dwError specifies the completion status for the overlapped operation as indicated by lpOverlapped. cbTransferred specifies the number of bytes sent. Currently there are no flag values defined and dwFlags will be zero. This function does not return a value.

Returning from this function allows invocation of another pending completion routine for this socket. All waiting completion routines are called before the alertable thread’s wait is satisfied with a return code of WSA_IO_COMPLETION. The completion routines may be called in any order, not necessarily in the same order the overlapped operations are completed. However, the posted buffers are guaranteed to be sent in the same order they are supplied.

Return Values

If no error occurs and the send operation has completed immediately, WSASendTo returns zero. Note that in this case, the completion routine will have already been scheduled, and to be called once the calling thread is in the alertable state. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError. The error code WSA_IO_PENDING indicates that the overlapped operation has been successfully initiated and that completion will be indicated at a later time. Any other error code indicates that the overlapped operation was not successfully initiated and no completion indication will occur.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEACCES	The requested address is a broadcast address, but the appropriate flag was not set.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEFAULT	The lpBuffers or lpTo parameters are not part of the user address space, or the lpTo argument is too small.
WSAENETRESET	The connection has been broken due to the remote host resetting.
WSAENOBUFS	The Windows Sockets provider reports a buffer deadlock.
WSAENOTCONN	The socket is not connected (connection-oriented sockets only)
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	MSG_OOB was specified, but the socket is not stream style such as type SOCK_STREAM, out-of-band data is not supported in the communication domain associated with this socket, MSG_PARTIAL is not supported, or the socket is unidirectional and supports only receive operations.
WSAESHUTDOWN	The socket has been shut down; it is not possible to WSASendTo on a socket after shutdown has been invoked with how set to SD_SEND or SD_BOTH.
WSAEWOULDBLOCK	Overlapped sockets: There are too many outstanding overlapped I/O requests. Nonoverlapped sockets: The socket is marked as nonblocking and the send operation cannot be completed immediately.
WSAEMSGSIZE	The socket is message oriented, and the message is larger than the maximum supported by the underlying transport.
WSAEINVAL	The socket has not been bound with bind, or the socket is not created with the overlapped flag.
WSAECONNABORTED	The virtual circuit was terminated due to a time-out or other failure.
WSAECONNRESET	The virtual circuit was reset by the remote side.
WSAEADDRNOTAVAIL	The specified address is not available from the local machine.
WSAEAFNOSUPPORT	Addresses in the specified family cannot be used with this socket.
WSAEDESTADDRREQ	A destination address is required.
WSAENETUNREACH	The network cannot be reached from this host at this time.
WSA_IO_PENDING	An overlapped operation was successfully initiated and completion will be indicated at a later time.
WSA_OPERATION_ABORTED	The overlapped operation has been canceled due to the closure of the socket, or the execution of the SIO_FLUSH command in WSAIoctl.
See Also

WSACloseEvent, WSACreateEvent, WSAGetOverlappedResult, WSASocket, WSAWaitForMultipleEvents


WSASetBlockingHook

This function has been removed in compliance with the Windows Sockets 2 specification, revision 2.2.0.

The function is not exported directly by the WS2_32.DLL, and Windows Sockets 2 applications should not use this function. Windows Sockets 1.1 applications that call this function are still supported through the WINSOCK.DLL and WSOCK32.DLL.

Blocking hooks are generally used to keep a single-threaded GUI application responsive during calls to blocking functions. Instead of using blocking hooks, an applications should use a separate thread (separate from the main GUI thread) for network activity.


WSASetEvent

The Windows Sockets WSASetEvent function sets the state of the specified event object to signaled.

BOOL WSASetEvent(

WSAEVENT hEvent
);
Paramters

hEvent

[in] Identifies an open event object handle.

Remarks

The state of the event object is set to be signaled.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSA_INVALID_HANDLE	hEvent is not a valid event object handle.
See Also

WSACloseEvent, WSACreateEvent, WSAResetEvent


WSASetLastError

The Windows Sockets WSASetLastError function sets the error code which can be retrieved through the WSAGetLastError function.

void WSASetLastError (

int iError
);
Parameters

iError

[in] Specifies the error code to be returned by a subsequent WSAGetLastError call.

Remarks

This function allows an application to set the error code to be returned by a subsequent WSAGetLastError call for the current thread. Note that any subsequent Windows Sockets routine called by the application will override the error code as set by this routine.

The error code set by WSASetLastError is different from the error code reset by getsockopt SO_ERROR.

Return Values

None.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
See Also

getsockopt, WSAGetLastError


WSASetService

The Windows Sockets WSASetService function registers or deregisters a service instance within one or more name spaces. This function can be used to affect a specific name space provider, all providers associated with a specific name space, or all providers across all name spaces.

INT WSASetService(

LPWSAQUERYSET lpqsRegInfo,
EWSASETSERVICEOP essOperation,
DWORD dwControlFlags
);
Parameters

lpqsRegInfo

[in] Specifies service information for registration, identifies service for deregistration.

essOperation

[in] An enumeration whose values include:

RNRSERVICE_REGISTER

Register the service. For SAP, this means sending out a periodic broadcast. This is a NOP for the DNS name space. For persistent data stores this means updating the address information.

RNRSERVICE_DEREGISTER

Deregister the service. For SAP, this means stop sending out the periodic broadcast. This is a NOP for the DNS name space. For persistent data stores this means deleting address information.

RNRSERVICE_DELETE

Delete the service from dynamic name and persistent spaces. For services represented by multiple CSADDR_INFO structures (using the SERVICE_MULTIPLE flag), only the supplied address will be deleted, and this much match exactly the corresponding CSADD_INFO structure that was supplied when the service was registered.

dwControlFlags

[in] The meaning of dwControlFlags is dependent on the value of essOperation as follows:

essOperation	dwControlFlags	Meaning
REGISTER	SERVICE_MULTIPLE	The service being registered may be represented by multiple CSADDR_INFO structures
Service Properties

The following table describes how service property data is represented in a WSAQUERYSET structure. Fields labeled as (Optional) may be supplied with a NULL pointer.

WSAQUERYSET Field Name	Service Property Description
Field Name	Service Property Description
dwSize	Must be set to sizeof(WSAQUERYSET). This is a versioning mechanism.
dwOutputFlags	Not applicable and ignored.
lpszServiceInstanceName	Referenced string contains the service instance name.
lpServiceClassId	The GUID corresponding to this service class.
lpVersion	(Optional) Supplies service instance version number.
lpszComment	(Optional) An optional comment string.
dwNameSpace	See table below.
lpNSProviderId	See table below.
lpszContext	(Optional) Specifies the starting point of the query in a hierarchical name space.
dwNumberOfProtocols	Ignored.
lpafpProtocols	Ignored.
lpszQueryString	Ignored.
dwNumberOfCsAddrs	The number of elements in the array of CSADDRO_INFO structures referenced by lpcsaBuffer.
lpcsaBuffer	A pointer to an array of CSADDRO_INFO structures which contain the address9(es) that the service is listening on.
lpBlob	(Optional) This is a pointer to a provider-specific entity.
As illustrated below, the combination of the dwNameSpace and lpNSProviderId parameters determine which name space providers are affected by this function.

dwNameSpace	lpNSProviderId	Scope of Impact
Ignored	Non-NULL	The specified name space provider
a valid name space ID	NULL	All name space providers that support the indicated name space
NS_ALL	NULL	All name space providers
Return Values

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSAEACCESS	The calling routine does not have sufficient privileges to install the Service.
WSANOTINITIALIZED	The Windows Sockets 2 DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.


WSASocket

The Windows Sockets WSASocket function creates a socket which is bound to a specific transport service provider, and optionally creates and/or joins a socket group.

SOCKET WSASocket (

int af,
int type,
int protocol,
LPWSAPROTOCOL_INFO lpProtocolInfo,
GROUP g,
DWORD dwFlags
);
Parameters

af

[in] An address family specification.

type

[in] A type specification for the new socket.

protocol

[in] A particular protocol to be used with the socket which is specific to the indicated address family.

lpProtocolInfo

[in] A pointer to a WSAPROTOCOL_INFO structure that defines the characteristics of the socket to be created.

g

[in] The identifier of the socket group.

dwFlags

[in] The socket attribute specification.

Remarks

This function causes a socket descriptor and any related resources to be allocated and associated with a transport service provider. By default, the socket will not have an overlapped attribute. If lpProtocolInfo is NULL, the Windows Sockets 2 DLL uses the first three parameters (af, type, protocol) to determine which service provider is used by selecting the first transport provider able to support the stipulated address family, socket type and protocol values. If the lpProtocolInfo is not NULL, the socket will be bound to the provider associated with the indicated WSAPROTOCOL_INFO structure. In this instance, the application may supply the manifest constant FROM_PROTOCOL_INFO as the value for any of af, type or protocol. This indicates that the corresponding values from the indicated WSAPROTOCOL_INFO structure (iAddressFamily, iSocketType, iProtocol) are to be assumed. In any case, the values supplied for af, type and protocol are supplied unmodified to the transport service provider through the corresponding parameters to the WSPSocket function in the SPI.

Note  The manifest constant AF_UNSPEC continues to be defined in the header file but its use is strongly discouraged, as this may cause ambiguity in interpreting the value of the protocol parameter.

Parameter g is used to indicate the appropriate actions on socket groups:

1.	if g is an existing socket group ID, join the new socket to this group, provided all the requirements set by this group are met; or

2.	if g = SG_UNCONSTRAINED_GROUP, create an unconstrained socket group and have the new socket be the first member; or

3.	if g = SG_CONSTRAINED_GROUP, create a constrained socket group and have the new socket be the first member; or

4.	if g = zero, no group operation is performed

For unconstrained groups, any set of sockets may be grouped together as long as they are supported by a single service provider. A constrained socket group may consist only of connection-oriented sockets, and requires that connections on all grouped sockets be to the same address on the same host. For newly created socket groups, the new group ID can be retrieved by using getsockopt with option SO_GROUP_ID, if this operation completes successfully. A socket group and its associated ID remain valid until the last socket belonging to this socket group is closed. Socket group IDs are unique across all processes for a given service provider.

The dwFlags parameter may be used to specify the attributes of the socket by or-ing any of the following Flags:

Flag	Meaning
WSA_FLAG_OVERLAPPED	This flag causes an overlapped socket to be created. Overlapped sockets may utilize WSASend, WSASendTo, WSARecv, WSARecvFrom and WSAIoctl for overlapped I/O operations, which allows multiple these operations to be initiated and in progress simultaneously.
WSA_FLAG_MULTIPOINT_C_ROOT	Indicates that the socket created will be a c_root in a multipoint session. Only allowed if a rooted control plane is indicated in the protocol’s WSAPROTOCOL_INFO structure. Refer to Multipoint and Multicast Semantics for additional information.
WSA_FLAG_MULTIPOINT_C_LEAF	Indicates that the socket created will be a c_leaf in a multicast session. Only allowed if XP1_SUPPORT_MULTIPOINT is indicated in the protocol’s WSAPROTOCOL_INFO structure. Refer to Multipoint and Multicast Semantics for additional information.
WSA_FLAG_MULTIPOINT_D_ROOT	Indicates that the socket created will be a d_root in a multipoint session. Only allowed if a rooted data plane is indicated in the protocol’s WSAPROTOCOL_INFO structure. Refer to Multipoint and Multicast Semantics for additional information.
WSA_FLAG_MULTIPOINT_D_LEAF	Indicates that the socket created will be a d_leaf in a multipoint session. Only allowed if XP1_SUPPORT_MULTIPOINT is indicated in the protocol’s WSAPROTOCOL_INFO structure. Refer to Multipoint and Multicast Semantics for additional information.
Important  For multipoint sockets, exactly one of WSA_FLAG_MULTIPOINT_C_ROOT or WSA_FLAG_MULTIPOINT_C_LEAF must be specified, and exactly one of WSA_FLAG_MULTIPOINT_D_ROOT or WSA_FLAG_MULTIPOINT_D_LEAF must be specified. Refer to Multipoint and Multicast Semantics for additional information.

Connection-oriented sockets such as SOCK_STREAM provide full-duplex connections, and must be in a connected state before any data may be sent or received on them. A connection to another socket is created with a connect/WSAConnect call. Once connected, data may be transferred using send/WSASend and recv/WSARecv calls. When a session has been completed, a closesocket must be performed.

The communications protocols used to implement a reliable, connection-oriented socket ensure that data is not lost or duplicated. If data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, the connection is considered broken and subsequent calls will fail with the error code set to WSAETIMEDOUT.

Connectionless, message-oriented sockets allow sending and receiving of datagrams to and from arbitrary peers using sendto/WSASendTo and recvfrom/WSARecvFrom. If such a socket is connected to a specific peer, datagrams may be sent to that peer using send/WSASend and may be received from (only) this peer using recv/WSARecv.

Support for sockets with type RAW is not required, but service providers are encourages to support raw sockets whenever it makes sense to do so.

Shared Sockets

When a special WSAPROTOCOL_INFO structure (obtained through the WSADuplicateSocket function and used to create additional descriptors for a shared socket) is passed as an input parameter to WSASocket, the g and dwFlags parameters are ignored.

Return Values

If no error occurs, WSASocket returns a descriptor referencing the new socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code may be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEAFNOSUPPORT	The specified address family is not supported.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEMFILE	No more socket descriptors are available.
WSAENOBUFS	No buffer space is available. The socket cannot be created.
WSAEPROTONOSUPPORT	The specified protocol is not supported.
WSAEPROTOTYPE	The specified protocol is the wrong type for this socket.
WSAESOCKTNOSUPPORT	The specified socket type is not supported in this address family.
WSAEINVAL	The parameter g specified is not valid.
See Also

accept, bind, connect, getsockname, getsockopt, ioctlsocket, listen, recv, recvfrom, select, send, sendto, setsockopt, shutdown


WSAStartup

The Windows Sockets WSAStartup function initiates use of the Windows Sockets DLL by a process.

int WSAStartup (

WORD wVersionRequested,
LPWSADATA lpWSAData
);
Parameters

wVersionRequested

[in] The highest version of Windows Sockets support that the caller can use. The high order byte specifies the minor version (revision) number; the low-order byte specifies the major version number.

lpWSAData

[out] A pointer to the WSADATA data structure that is to receive details of the Windows Sockets implementation.

Remarks

This function must be the first Windows Sockets function called by an application or DLL. It allows an application or DLL to specify the version of Windows Sockets required and to retrieve details of the specific Windows Sockets implementation. The application or DLL may only issue further Windows Sockets functions after a successful WSAStartup invocation.

In order to support future Windows Sockets implementations and applications which may have functionality differences from current version of Windows Sockets, a negotiation takes place in WSAStartup. The caller of WSAStartup and the Windows Sockets DLL indicate to each other the highest version that they can support, and each confirms that the other's highest version is acceptable. Upon entry to WSAStartup, the Windows Sockets DLL examines the version requested by the application. If this version is equal to or higher than the lowest version supported by the DLL, the call succeeds and the DLL returns in wHighVersion the highest version it supports and in wVersion the minimum of its high version and wVersionRequested. The Windows Sockets DLL then assumes that the application will use wVersion. If the wVersion field of the WSADATA structure is unacceptable to the caller, it should call WSACleanup and either search for another Windows Sockets DLL or fail to initialize.

This negotiation allows both a Windows Sockets DLL and a Windows Sockets application to support a range of Windows Sockets versions. An application can successfully utilize a Windows Sockets DLL if there is any overlap in the version ranges. The following chart gives examples of how WSAStartup works in conjunction with different application and Windows Sockets DLL versions:

App versions	DLL Versions	wVersion Requested	wVersion	wHigh Version	End Result
1.1	1.1	1.1	1.1	1.1	use 1.1
1.0 1.1	1.0	1.1	1.0	1.0	use 1.0
1.0	1.0 1.1	1.0	1.0	1.1	use 1.0
1.1	1.0 1.1	1.1	1.1	1.1	use 1.1
1.1	1.0	1.1	1.0	1.0	Application fails
1.0	1.1	1.0	---	---	WSAVERNOT SUPPORTED
1.0 1.1	1.0 1.1	1.1	1.1	1.1	use 1.1
1.1 2.0	1.1	2.0	1.1	1.1	use 1.1
2.0	2.0	2.0	2.0	2.0	use 2.0
The following code fragment demonstrates how an application which supports only version 2 of Windows Sockets makes a WSAStartup call:

WORD wVersionRequested;

WSADATA wsaData;

int err;

wVersionRequested = MAKEWORD( 2, 0 );

err = WSAStartup( wVersionRequested, &wsaData );

if ( err != 0 ) {

    /* Tell the user that we couldn't find a usable */

    /* WinSock DLL.                                  */

    return;

}

/* Confirm that the WinSock DLL supports 2.0.*/

/* Note that if the DLL supports versions greater    */

/* than 2.0 in addition to 2.0, it will still return */

/* 2.0 in wVersion since that is the version we      */

/* requested.                                        */

if ( LOBYTE( wsaData.wVersion ) != 2 ||

        HIBYTE( wsaData.wVersion ) != 0 ) {

    /* Tell the user that we couldn't find a usable */

    /* WinSock DLL.                                  */

    WSACleanup( );

    return;

}

/* The WinSock DLL is acceptable. Proceed. */

Once an application or DLL has made a successful WSAStartup call, it may proceed to make other Windows Sockets calls as needed. When it has finished using the services of the Windows Sockets DLL, the application or DLL must call WSACleanup in order to allow the Windows Sockets DLL to free any resources for the application.

Details of the actual Windows Sockets implementation are described in the WSAData structure defined as follows:

struct WSAData {

    WORD            wVersion;

    WORD            wHighVersion;

    char

szDescription[WSADESCRIPTION_LEN+1];

    char              szSystemStatus[WSASYSSTATUS_LEN+1];

    unsigned short    iMaxSockets;

    unsigned short    iMaxUdpDg;

    char FAR *        lpVendorInfo;

};

The members of this structure are:

Parameters

wVersion

The version of the Windows Sockets specification that the Windows Sockets DLL expects the caller to use.

wHighVersion

The highest version of the Windows Sockets specification that this DLL can support (also encoded as above). Normally this will be the same as wVersion.

sz

A null-terminated ASCII string into which the Windows Sockets DLL copies a description of the Windows Sockets implementation. The text (up to 256 characters in length) may contain any characters except control and formatting characters: the most likely use that an application will put this to is to display it (possibly truncated) in a status message.

szSystemStatus

A null-terminated ASCII string into which the Windows Sockets DLL copies relevant status or configuration information. The Windows Sockets DLL should use this field only if the information might be useful to the user or support staff: it should not be considered as an extension of the szDescription field.

iMaxSockets

This field is retained for backward compatibility, but should be ignored for version 2 and later as no single value can be appropriate for all underlying service providers.

iMaxUdpDg

This value should be ignored for version 2 and onward. It is retained for compatibility with Windows Sockets specification 1.1, but should not be used when developing new applications. For the actual maximum message size specific to a particular Windows Sockets service provider and socket type, applications should use getsockopt to retrieve the value of option SO_MAX_MSG_SIZE after a socket has been created.

lpVendorInfo

This value should be ignored for version 2 and onward. It is retained for compatibility with Windows Sockets specification 1.1. Applications needing to access vendor-specific configuration information should use getsockopt to retrieve the value of option PVD_CONFIG. The definition of this value (if utilized) is beyond the scope of this specification.

Note that an application should ignore the iMaxsockets, iMaxUdpDg, and lpVendorInfo fields in WSAData if the value in wVersion after a successful call to WSAStartup is at least 2. This is because the architecture of Windows Sockets has been changed in version 2 to support multiple providers, and WSAData no longer applies to a single vendor’s stack. Two new socket options are introduced to supply provider-specific information: SO_MAX_MSG_SIZE (replaces the iMaxUdpDg element) and PVD_CONFIG (allows any other provider-specific configuration to occur).

An application or DLL may call WSAStartup more than once if it needs to obtain the WSAData structure information more than once. On each such call the application may specify any version number supported by the DLL.

There must be one WSACleanup call corresponding to every successful WSAStartup call to allow third-party DLLs to make use of a Windows Sockets DLL on behalf of an application. This means, for example, that if an application calls WSAStartup three times, it must call WSACleanup three times. The first two calls to WSACleanup do nothing except decrement an internal counter; the final WSACleanup call for the task does all necessary resource deallocation for the task.

Return Values

WSAStartup returns zero if successful. Otherwise, it returns one of the error codes listed below. Note that the normal mechanism whereby the application calls WSAGetLastError to determine the error code cannot be used, since the Windows Sockets DLL may not have established the client data area where the "last error" information is stored.

Error Codes

WSASYSNOTREADY	Indicates that the underlying network subsystem is not ready for network communication.
WSAVERNOTSUPPORTED	The version of Windows Sockets support requested is not provided by this particular Windows Sockets implementation.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 operation is in progress.
WSAEPROCLIM	Limit on the number of tasks supported by the Windows Sockets implementation has been reached.
WSAEFAULT	The lpWSAData is not a valid pointer.
See Also

send, sendto, WSACleanup


WSAStringToAddress

The Windows Sockets WSAStringToAddress function converts a human-readable string to a socket address structure (SOCKADDR) suitable to pass to Windows Sockets routines which take such a structure.

Any missing components of the address will be defaulted to a reasonable value, if possible. For example, a missing port number will default to zero. If the caller wants the translation to be done by a particular provider, it should supply the corresponding WSAPROTOCOL_INFO structure in the lpProtocolInfo parameter.

INT WSAStringToAddress(

LPTSTR AddressString,
INT AddressFamily,
LPWSAPROTOCOL_INFO lpProtocolInfo,
LPSOCKADDR lpAddress,
LPINT lpAddressLength
);
Parameters

AddressString

[in] Points to the zero-terminated human-readable string to convert.

AddressFamily

[in] The address family to which the string belongs.

lpProtocolInfo

[in] (Optional) The WSAPROTOCOL_INFO structure for a particular provider.

Address

[in/out] A buffer which is filled with a single SOCKADDR structure.

lpAddressLength

[in/out] The length of the Address buffer. Returns the size of the resultant SOCKADDR structure.

Return Values

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSAEFAULT	The specified Address buffer is too small. Pass in a larger buffer.
WSAEINVAL	Unable to translate the string into a SOCKADDR.


WSAUnhookBlockingHook

This function has been removed in compliance with the Windows Sockets 2 specification, revision 2.2.0.

The function is not exported directly by the WS2_32.DLL, and Windows Sockets 2 applications should not use this function. Windows Sockets 1.1 applications that call this function are still supported through the WINSOCK.DLL and WSOCK32.DLL.

Blocking hooks are generally used to keep a single-threaded GUI application responsive during calls to blocking functions. Instead of using blocking hooks, an applications should use a separate thread (separate from the main GUI thread) for network activity.


WSAWaitForMultipleEvents

The Windows Sockets WSAWaitForMultipleEvents function returns either when one or all of the specified event objects are in the signaled state, or when the time-out interval expires.

DWORD WSAWaitForMultipleEvents(

DWORD cEvents,
const WSAEVENT FAR *lphEvents,
BOOL fWaitAll,
DWORD dwTimeOUT,
BOOL fAlertable
);
Parameters

cEvents

[in] Specifies the number of event object handles in the array pointed to by lphEvents. The maximum number of event object handles is WSA_MAXIMUM_WAIT_EVENTS. One or more events must be specified.

lphEvents

[in] Points to an array of event object handles.

fWaitAll

[in] Specifies the wait type. If TRUE, the function returns when all event objects in the lphEvents array are signaled at the same time. If FALSE, the function returns when any one of the event objects is signaled. In the latter case, the return value indicates the event object whose state caused the function to return.

dwTimeout

[in] Specifies the time-out interval, in milliseconds. The function returns if the interval expires, even if conditions specified by the fWaitAll parameter are not satisfied. If dwTimeout is zero, the function tests the state of the specified event objects and returns immediately. If dwTimeout is WSA_INFINITE, the function's time-out interval never expires.

fAlertable

[in] Specifies whether the function returns when the system queues an I/O completion routine for execution by the calling thread. If TRUE, the completion routine is executed and the function returns. If FALSE, the completion routine is not executed when the function returns.

Remarks

The WSAWaitForMultipleEvents function returns either when any one or when all of the specified objects are in the signaled state, or when the time-out interval elapses. This function is also used to perform an alertable wait by setting the parameter fAltertable to be TRUE. This enables the function to return when the system queues an I/O completion routine to be executed by the calling thread.

When fWaitAll is TRUE, the function’s wait condition is satisfied only when the state of all objects is signaled at the same time. The function does not modify the state of the specified objects until all objects are simultaneously signaled.

Applications that simply need to enter an alertable wait state without waiting for any event objects to be signalled should use the Win32 sleepEx function.

Return Values

If the function succeeds, the return value indicates the event object that caused the function to return.

If the function fails, the return value is WSA_WAIT_FAILED. To get extended error information, call WSAGetLastError.

The return value upon success is one of the following values:

Value	Meaning
WSA_WAIT_EVENT_0 to (WSA_WAIT_EVENT_0 + cEvents - 1)	If fWaitAll is TRUE, the return value indicates that the state of all specified event objects is signaled. If fWaitAll is FALSE, the return value minus WSA_WAIT_EVENT_0 indicates the lphEvents array index of the object that satisfied the wait.
WAIT_IO_COMPLETION	One or more I/O completion routines are queued for execution.
WSA_WAIT_TIMEOUT	The time-out interval elapsed and the conditions specified by the fWaitAll parameter are not satisfied.
Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSA_NOT_ENOUGH_MEMORY	Not enough free memory available to complete the operation.
WSA_INVALID_HANDLE	One or more of the values in the lphEvents array is not a valid event object handle.
WSA_INVALID_PARAMETER	The cEvents parameter does not contain a valid handle count.
See Also

WSACloseEvent, WSACreateEvent


Error Codes

The following is a list of possible error codes returned by the WSAGetLastError call, along with their extended explanations. Errors are listed in alphabetical order by error macro. Some error codes defined in WINSOCK2.H are not returned from any function - these have not been listed here.

WSAEACCES

(10013)

Permission denied.

An attempt was made to access a socket in a way forbidden by its access permissions. An example is using a broadcast address for sendto without broadcast permission being set using setsockopt(SO_BROADCAST).

WSAEADDRINUSE

(10048)

Address already in use.

Only one usage of each socket address (protocol/IP address/port) is normally permitted. This error occurs if an application attempts to bind a socket to an IP address/port that has already been used for an existing socket, or a socket that wasn't closed properly, or one that is still in the process of closing. For server applications that need to bind multiple sockets to the same port number, consider using setsockopt(SO_REUSEADDR). Client applications usually need not call bind at all - connect will choose an unused port automatically.

WSAEADDRNOTAVAIL

(10049)

Cannot assign requested address.

The requested address is not valid in its context. Normally results from an attempt to bind to an address that is not valid for the local machine, or connect/sendto an address or port that is not valid for a remote machine (e.g. port 0).

WSAEAFNOSUPPORT

(10047)

Address family not supported by protocol family.

An address incompatible with the requested protocol was used. All sockets are created with an associated "address family" (i.e. AF_INET for Internet Protocols) and a generic protocol type (i.e. SOCK_STREAM). This error will be returned if an incorrect protocol is explicitly requested in the socket call, or if an address of the wrong family is used for a socket, e.g. in sendto.

WSAEALREADY

(10037)

Operation already in progress.

An operation was attempted on a non-blocking socket that already had an operation in progress - i.e. calling connect a second time on a non-blocking socket that is already connecting, or canceling an asynchronous request (WSAAsyncGetXbyY) that has already been canceled or completed.

WSAECONNABORTED

(10053)

Software caused connection abort.

An established connection was aborted by the software in your host machine, possibly due to a data transmission timeout or protocol error.

WSAECONNREFUSED

(10061)

Connection refused.

No connection could be made because the target machine actively refused it. This usually results from trying to connect to a service that is inactive on the foreign host - i.e. one with no server application running.

WSAECONNRESET

(10054)

Connection reset by peer.

A existing connection was forcibly closed by the remote host. This normally results if the peer application on the remote host is suddenly stopped, the host is rebooted, or the remote host used a "hard close" (see setsockopt for more information on the SO_LINGER option on the remote socket.)

WSAEDESTADDRREQ

(10039)

Destination address required.

A required address was omitted from an operation on a socket. For example, this error will be returned if sendto is called with the remote address of ADDR_ANY.

WSAEFAULT

(10014)

Bad address.

The system detected an invalid pointer address in attempting to use a pointer argument of a call. This error occurs if an application passes an invalid pointer value, or if the length of the buffer is too small. For instance, if the length of an argument which is a struct sockaddr is smaller than sizeof(struct sockaddr).

WSAEHOSTDOWN

(10064)

Host is down.

A socket operation failed because the destination host was down. A socket operation encountered a dead host. Networking activity on the local host has not been initiated. These conditions are more likely to be indicated by the error WSAETIMEDOUT.

WSAEHOSTUNREACH

(10065)

No route to host.

A socket operation was attempted to an unreachable host. See WSAENETUNREACH

WSAEINPROGRESS

(10036)

Operation now in progress.

A blocking operation is currently executing. Windows Sockets only allows a single blocking operation to be outstanding per task (or thread), and if any other function call is made (whether or not it references that or any other socket) the function fails with the WSAEINPROGRESS error.

WSAEINTR

(10004)

Interrupted function call.

A blocking operation was interrupted by a call to WSACancelBlockingCall.

WSAEINVAL

(10022)

Invalid argument.

Some invalid argument was supplied (for example, specifying an invalid level to the setsockopt function). In some instances, it also refers to the current state of the socket - for instance, calling accept on a socket that is not listening.

WSAEISCONN

(10056)

Socket is already connected.

A connect request was made on an already connected socket. Some implementations also return this error if sendto is called on a connected SOCK_DGRAM socket (For SOCK_STREAM sockets, the to parameter in sendto is ignored), although other implementations treat this as a legal occurrence.

WSAEMFILE

(10024)

Too many open files.

Too many open sockets. Each implementation may have a maximum number of socket handles available, either globally, per process or per thread.

WSAEMSGSIZE

(10040)

Message too long.

A message sent on a datagram socket was larger than the internal message buffer or some other network limit, or the buffer used to receive a datagram into was smaller than the datagram itself.

WSAENETDOWN

(10050)

Network is down.

A socket operation encountered a dead network. This could indicate a serious failure of the network system (i.e. the protocol stack that the WinSock DLL runs over), the network interface, or the local network itself.

WSAENETRESET

(10052)

Network dropped connection on reset.

The host you were connected to crashed and rebooted. May also be returned by setsockopt if an attempt is made to set SO_KEEPALIVE on a connection that has already failed.

WSAENETUNREACH

(10051)

Network is unreachable.

A socket operation was attempted to an unreachable network. This usually means the local software knows no route to reach the remote host.

WSAENOBUFS

(10055)

No buffer space available.

An operation on a socket could not be performed because the system lacked sufficient buffer space or because a queue was full.

WSAENOPROTOOPT

(10042)

Bad protocol option.

An unknown, invalid or unsupported option or level was specified in a getsockopt or setsockopt call.

WSAENOTCONN

(10057)

Socket is not connected.

A request to send or receive data was disallowed because the socket is not connected and (when sending on a datagram socket using sendto) no address was supplied. Any other type of operation might also return this error - for example, setsockopt setting SO_KEEPALIVE if the connection has been reset.

WSAENOTSOCK

(10038)

Socket operation on non-socket.

An operation was attempted on something that is not a socket. Either the socket handle parameter did not reference a valid socket, or for select, a member of an fd_set was not valid.

WSAEOPNOTSUPP

(10045)

Operation not supported.

The attempted operation is not supported for the type of object referenced. Usually this occurs when a socket descriptor to a socket that cannot support this operation, for example, trying to accept a connection on a datagram socket.

WSAEPFNOSUPPORT

(10046)

Protocol family not supported.

The protocol family has not been configured into the system or no implementation for it exists. Has a slightly different meaning to WSAEAFNOSUPPORT, but is interchangeable in most cases, and all Windows Sockets functions that return one of these specify WSAEAFNOSUPPORT.

WSAEPROCLIM

(10067)

Too many processes.

A Windows Sockets implementation may have a limit on the number of applications that may use it simultaneously. WSAStartup may fail with this error if the limit has been reached.

WSAEPROTONOSUPPORT

(10043)

Protocol not supported.

The requested protocol has not been configured into the system, or no implementation for it exists. For example, a socket call requests a SOCK_DGRAM socket, but specifies a stream protocol.

WSAEPROTOTYPE

(10041)

Protocol wrong type for socket.

A protocol was specified in the socket function call that does not support the semantics of the socket type requested. For example, the ARPA Internet UDP protocol cannot be specified with a socket type of SOCK_STREAM.

WSAESHUTDOWN

(10058)

Cannot send after socket shutdown.

A request to send or receive data was disallowed because the socket had already been shut down in that direction with a previous shutdown call. By calling shutdown a partial close of a socket is requested, which is a signal that sending or receiving or both has been discontinued.

WSAESOCKTNOSUPPORT

(10044)

Socket type not supported.

The support for the specified socket type does not exist in this address family. For example, the optional type SOCK_RAW might be selected in a socket call, and the implementation does not support SOCK_RAW sockets at all.

WSAETIMEDOUT

(10060)

Connection timed out.

A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond.

WSAEWOULDBLOCK

(10035)

Resource temporarily unavailable.

This error is returned from operations on non-blocking sockets that cannot be completed immediately, for example recv when no data is queued to be read from the socket. It is a non-fatal error, and the operation should be retried later. It is normal for WSAEWOULDBLOCK to be reported as the result from calling connect on a non-blocking SOCK_STREAM socket, since some time must elapse for the connection to be established.

WSAHOST_NOT_FOUND

(11001)

Host not found.

No such host is known. The name is not an official hostname or alias, or it cannot be found in the database(s) being queried. This error may also be returned for protocol and service queries, and means the specified name could not be found in the relevant database.

WSA_INVALID_HANDLE

(OS dependent)

Specified event object handle is invalid.

An application attempts to use an event object, but the specified handle is not valid.

WSA_INVALID_PARAMETER

(OS dependent)

One or more parameters are invalid.

An application used a Windows Sockets function which directly maps to a Win32 function. The Win32 function is indicating a problem with one or more parameters.

WSAINVALIDPROCTABLE

(OS dependent)

Invalid procedure table from service provider.

A service provider returned a bogus proc table to WS2_32.DLL. (Usually caused by one or more of the function pointers being NULL.)

WSAINVALIDPROVIDER

(OS dependent)

Invalid service provider version number.

A service provider returned a version number other than 2.0.

WSA_IO_PENDING

(OS dependent)

Overlapped operations will complete later.

The application has initiated an overlapped operation which cannot be completed immediately. A completion indication will be given at a later time when the operation has been completed.

WSA_IO_INCOMPLETE

(OS dependent)

Overlapped I/O event object not in signaled state.

The application has tried to determine the status of an overlapped operation which is not yet completed. Applications that use WSAWaitForMultipleEvents in a polling mode to determine when an overlapped operation has completed will get this error code until the operation is complete.

WSA_NOT_ENOUGH_MEMORY

(OS dependent)

Insufficient memory available.

An application used a Windows Sockets function which directly maps to a Win32 function. The Win32 function is indicating a lack of required memory resources.

WSANOTINITIALISED

(10093)

Successful WSAStartup not yet performed.

Either the application hasn’t called WSAStartup or WSAStartup failed. The application may be accessing a socket which the current active task does not own (i.e. trying to share a socket between tasks), or WSACleanup has been called too many times.

WSANO_DATA

(11004)

Valid name, no data record of requested type.

The requested name is valid and was found in the database, but it does not have the correct associated data being resolved for. The usual example for this is a hostname -> address translation attempt (using gethostbyname or WSAAsyncGetHostByName) which uses the DNS (Domain Name Server), and an MX record is returned but no A record - indicating the host itself exists, but is not directly reachable.

WSANO_RECOVERY

(11003)

This is a non-recoverable error.

This indicates some sort of non-recoverable error occurred during a database lookup. This may be because the database files (e.g. BSD-compatible HOSTS, SERVICES or PROTOCOLS files) could not be found, or a DNS request was returned by the server with a severe error.

WSAPROVIDERFAILEDINIT

(OS dependent)

Unable to initialize a service provider.

Either a service provider's DLL could not be loaded (LoadLibrary failed) or the provider's WSPStartup/NSPStartup function failed.

WSASYSCALLFAILURE

(OS dependent)

System call failure.

Returned when a system call that should never fail does. For example, if a call to WaitForMultipleObjects fails or one of the registry functions fails trying to manipulate theprotocol/namespace catalogs.

WSASYSNOTREADY

(10091)

Network subsystem is unavailable.

This error is returned by WSAStartup if the Windows Sockets implementation cannot function at this time because the underlying system it uses to provide network services is currently unavailable. Users should check:

•	that the appropriate Windows Sockets DLL file is in the current path,

•	that they are not trying to use more than one Windows Sockets implementation simultaneously. If there is more than one WINSOCK DLL on your system, be sure the first one in the path is appropriate for the network subsystem currently loaded.

•	the Windows Sockets implementation documentation to be sure all necessary components are currently installed and configured correctly.

WSATRY_AGAIN

(11002)

Non-authoritative host not found.

This is usually a temporary error during hostname resolution and means that the local server did not receive a response from an authoritative server. A retry at some time later may be successful.

WSAVERNOTSUPPORTED

(10092)

WINSOCK.DLL version out of range.

The current Windows Sockets implementation does not support the Windows Sockets specification version requested by the application. Check that no old Windows Sockets DLL files are being accessed.

WSAEDISCON

(10094)

Graceful shutdown in progress.

Returned by recv, WSARecv to indicate the remote party has initiated a graceful shutdown sequence.

WSA_OPERATION_ABORTED

(OS dependent)

Overlapped operation aborted.

An overlapped operation was canceled due to the closure of the socket, or the execution of the SIO_FLUSH command in WSAIoctl.


AFPROTOCOLS

typedef struct _AFPROTOCOLS {

    INT iAddressFamily;

    INT iProtocol;

} AFPROTOCOLS, *PAFPROTOCOLS, *LPAFPROTOCOLS;


CSADDR_INFO

typedef struct _CSADDR_INFO {

    SOCKET_ADDRESS LocalAddr ;

    SOCKET_ADDRESS RemoteAddr ;

    INT iSocketType ;

    INT iProtocol ;

} CSADDR_INFO, *PCSADDR_INFO, FAR * LPCSADDR_INFO ;


flowspec

typedef struct _flowspec

{

    int32        TokenRate;            /* In Bytes/sec    */

    int32        TokenBucketSize;      /* In Bytes        */

    int32        PeakBandwidth;        /* In Bytes/sec    */

    int32        Latency;              /* In microseconds */

    int32        DelayVariation;       /* In microseconds */

    GUARANTEE    LevelOfGuarantee;     /* Guaranteed, Predictive, */

                                       /* Best Effort, etc.  */

    int32        CostOfCall;           /* Reserved for future use, */

                                       /* must be set to 0 now     */

    int32        NetworkAvailability;  /* read-only:         */

                                       /*   1 if accessible, */

                                       /*   0 if not         */

} FLOWSPEC, FAR * LPFLOWSPEC;

Members

TokenRate

A token bucket model is used to specify the rate at which permission to send traffic (or credits) accrues. In the model, the token bucket has a maximum volume, TokenBucketSize, and continuously fills at a certain rate TokenRate. If the bucket contains sufficient credit, the application can send data and reduce the available credit by that amount. If sufficient credits are not available, the application must wait or discard the extra traffic.

A value of -1 in the members TokenRate and TokenBucketSize indicates that no rate-limiting is in force. The TokenRate is expressed in bytes per second.

If an application has been sending at a low rate for a period of time, it can send a large burst of data all at once until it runs out of credit. Having done so, it must limit itself to sending at TokenRate until its data burst is exhausted.

In video applications, the TokenRate is typically the average bit rate peak to peak. In constant rate applications, the TokenRate is equal to the PeakBandwidth.

TokenBucketSize

The TokenBucketSize is expressed in bytes.

The TokenBucketSize is the largest typical frame size in video applications. In constant rate applications, the TokenBucketSize is chosen to accommodate small variations.

PeakBandwidth

This member, expressed in bytes/second, limits how fast packets may be sent back to back from the application. Some intermediate systems can take advantage of this information resulting in a more efficient resource allocation.

Latency

Latency is the maximum acceptable delay between transmission of a bit by the sender and its receipt by the intended receiver(s), expressed in microseconds. The precise interpretation of this number depends on the level of guarantee specified in the QOS request.

DelayVariation

This the difference, in microseconds, between the maximum and minimum possible delay that a packet will experience. This value is used by applications to determine the amount of buffer space needed at the receiving side in order to restore the original data transmission pattern.

LevelOfGuarantee

This is the level of service being negotiated for. The GUARANTEE type is enumerated below. Four levels of service are defined: Guaranteed, Guaranteed Delay, Predictive, Controlled Load and Best Effort.

The reason for defining both predictive and guaranteed service is that predictive services may achieve substantially better performance given the same level of network resource usage, while guaranteed service provides the mathematical level of certainty needed by selected applications. Specific providers may implement none, one, or both of these services.

Best effort service is just a hint to the service provider and should be always supported.

CostOfCall

This is just a place holder for now and should always be set to 0 until we can come up with a meaningful cost metric.

NetworkAvailability

Network Availability - This is a read-only field for the transport provider to use in indicating to the application whether or not the underlying media is currently accessible or temporarily unavailable. The typical example for a temporarily inaccessible network would be a wireless interface that has lost contact with the base station (due, for example to terrain interference). Any change in this value should result in an FD_QOS indication to applications that have registered interest in same.


FD_SET

typedef struct fd_set {

    u_int fd_count;                 /* how many are SET? */

    SOCKET fd_array[FD_SETSIZE];   /* an array of SOCKETs */

} fd_set;

typedef struct fd_set FD_SET;

Element	Usage
fd_count	The number of sockets that are set.
fd_array	An array of the sockets in the set.


GUARANTEE

typedef enum

{

    BestEffortService,

    ControlledLoadService,

    PredictiveService,

    GuaranteedService

} GUARANTEE;

Types

GuaranteedService

A service provider supporting guaranteed service implements a queuing algorithm which isolates the flow from the effects of other flows as much as possible, and guarantees the flow the ability to propagate data at the TokenRate for the duration of the connection. If the sender sends faster than that rate, the network may delay or discard the excess traffic. If the sender does not exceed TokenRate over time, then latency is also guaranteed. This service is designed for applications which require a precisely known quality of service but would not benefit from better service, such as real-time control systems.

PredictiveService

A service provider supporting predictive service guarantees the flow the ability to propagate data at the TokenRate for the duration of the connection. If the sender sends faster than that rate, the network may delay or discard the excess traffic. The delay limit is not guaranteed (occasional packets may take longer than specified), but is generally highly reliable. This service is designed for applications that can accommodate or adapt to some variation in service quality, such as video service.

ControlledLoadService

With this service, end-to-end behavior provided to an application by a series of network elements tightly approximates the behavior visible to applications receiving best-effort service "under unloaded conditions" from the same series of network elements. Thus, applications using this service can assume that:

1.	A very high percentage of transmitted packets will be successfully delivered by the network to the receiving end-nodes. (Packet loss rate will closely approximate the basic packet error rate of the transmission medium).

2.	Transit delay experienced by a very high percentage of the delivered packets will not greatly exceed the minimum transit delay experienced by any successfully delivered packet at the speed of light.

Note  This definition comes from the Internet Engineering Task Force (IETF).

BestEffortService

A service provider supporting best effort service, at minimum, takes the flow spec as a guideline and makes reasonable efforts to maintain the level of service requested, however without making any guarantees whatsoever.


hostent

This structure is allocated by Windows Sockets. An application should never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information that it needs before issuing any other Windows Sockets API calls.

struct hostent {

    char FAR *       h_name;

    char FAR * FAR * h_aliases;

    short            h_addrtype;

    short            h_length;

    char FAR * FAR * h_addr_list;

};

Members

h_name

Official name of the host (PC).If using the DNS or similar resolution system, it is the Fully Qualified Domain Name (FQDN) that caused the server to return a reply. If using a local "hosts" file, it is the first entry after the IP address.

h_aliases

A NULL-terminated array of alternate names.

h_addrtype

The type of address being returned.

h_length

The length, in bytes, of each address.

h_addr_list

A NULL-terminated list of addresses for the host. Addresses are returned in network byte order.The macro h_addr is defined to be h_addr_list[0] for compatibility with older software.


QualityOfService

The Windows Sockets 2 QOS structure is defined in WINSOCK2.H and is reproduced here.

typedef struct _QualityOfService

{

    FLOWSPEC    SendingFlowspec;       /* The flowspec for data */

                                       /*   sending              */

    FLOWSPEC    ReceivingFlowspec;     /* The flowspec for data */

                                       /*   receiving            */

    WSABUF      ProviderSpecific;      /* Additional provider-   */

                                       /*   specific parameters  */

} QOS, FAR * LPQOS;


sockaddr

The sockaddr structure varies depending on the the protocol selected. The structure below is used with TCP/IP. Other protocols use similar structures.

struct sockaddr_in {

        short   sin_family;

        u_short sin_port;

        struct  in_addr sin_addr;

        char    sin_zero[8];

};


SOCKET_ADDRESS

typedef struct _SOCKET_ADDRESS {

    LPSOCKADDR lpSockaddr ;

    INT iSockaddrLength ;

} SOCKET_ADDRESS, *PSOCKET_ADDRESS, FAR * LPSOCKET_ADDRESS ;


WSABUF

typedef struct _WSABUF {

    u_long      len;

    char FAR *  buf;

} WSABUF, FAR * LPWSABUF;

Members

len

The length of the buffer.

buf

A pointer to the buffer.


WSAEcomparator

typedef enum _WSAEcomparator

{

    COMP_EQUAL = 0,

    COMP_NOTLESS

} WSAECOMPARATOR, *PWSAECOMPARATOR, *LPWSAECOMPARATOR;


WSAData

typedef struct WSAData {

        WORD                    wVersion;

        WORD                    wHighVersion;

        char                    szDescription[WSADESCRIPTION_LEN+1];

        char                    szSystemStatus[WSASYS_STATUS_LEN+1];

        unsigned short          iMaxSockets;

        unsigned short          iMaxUdpDg;

        char FAR *              lpVendorInfo;

} WSADATA, FAR * LPWSADATA;


WSANAMESPACE_INFO

The WSANAMESPACE_INFO structure contains all of the registration information for a name space provider.

typedef struct _WSANAMESPACE_INFOW {

    GUID                NSProviderId;

    DWORD               dwNameSpace;

    BOOL                fActive;

    DWORD               dwVersion;

    LPWSTR              lpszIdentifier;

} WSANAMESPACE_INFOW, *PWSANAMESPACE_INFOW, *LPWSANAMESPACE_INFOW;

Members

NSProviderId

The unique identifier for this name space provider.

dwNameSpace

Specifies the name space supported by this implementation of the provider.

fActive

If TRUE, indicates that this provider is active. If FALSE, the provider is inactive and is not accessible for queries, even if the query specifically references this provider.

dwVersion

Name Space version identifier.

lpszIdentifier

Display string for the provider.


WSAOVERLAPPED

The WSAOVERLAPPED structure provides a communication medium between the initiation of an overlapped I/O operation and its subsequent completion. The WSAOVERLAPPED structure is designed to be compatible with the Win32 OVERLAPPED structure:

typedef struct _WSAOVERLAPPED {

    DWORD        Internal;

    DWORD        InternalHigh;

    DWORD        Offset;

    DWORD        OffsetHigh;

    WSAEVENT     hEvent;

} WSAOVERLAPPED, LPWSAOVERLAPPED;

Members

Internal

This reserved field is used internally by the entity that implements overlapped I/O. For service providers that create sockets as installable file system (IFS) handles, this field is used by the underlying operating system. Other service providers (non-IFS providers) are free to use this field as necessary.

InternalHigh

Reserved field is used internally by the entity that implements overlapped I/O. For service providers that create sockets as IFS handles, this field is used by the underlying operating system. Non-IFS providers are free to use this field as necessary.

OffsetT

This field is reserved for service providers to use.

OffsetHigh

This field is reserved for service providers to use.

Event

If an overlapped I/O operation is issued without an I/O completion routine (lpCompletionRoutine is NULL), then this field should either contain a valid handle to a WSAEVENT object or be NULL. If lpCompletionRoutine is non-NULL then applications are free to use this field as necessary.


WSAQuerySet

typedef struct _WSAQuerySetW

{

    DWORD           dwSize;

    LPWSTR          lpszServiceInstanceName;

    LPGUID          lpServiceClassId;

    LPWSAVERSION    lpVersion;

    LPWSTR          lpszComment;

    DWORD           dwNameSpace;

    LPGUID          lpNSProviderId;

    LPWSTR          lpszContext;

    DWORD           dwNumberOfProtocols;

    LPAFPROTOCOLS   lpafpProtocols;

    LPWSTR          lpszQueryString;

    DWORD           dwNumberOfCsAddrs;

    LPCSADDR_INFO   lpcsaBuffer;

    DWORD           dwOutputFlags;

    LPBLOB          lpBlob;

} WSAQUERYSETW, *PWSAQUERYSETW, *LPWSAQUERYSETW;


WSAPROTOCOL_INFO

typedef struct _WSAPROTOCOL_INFOW {

    DWORD dwServiceFlags1;

    DWORD dwServiceFlags2;

    DWORD dwServiceFlags3;

    DWORD dwServiceFlags4;

    DWORD dwProviderFlags;

    GUID ProviderId;

    DWORD dwCatalogEntryId;

    WSAPROTOCOLCHAIN ProtocolChain;

    int iVersion;

    int iAddressFamily;

    int iMaxSockAddr;

    int iMinSockAddr;

    int iSocketType;

    int iProtocol;

    int iProtocolMaxOffset;

    int iNetworkByteOrder;

    int iSecurityScheme;

    DWORD dwMessageSize;

    DWORD dwProviderReserved;

    WCHAR  szProtocol[WSAPROTOCOL_LEN+1];

} WSAPROTOCOL_INFOW, FAR * LPWSAPROTOCOL_INFOW;

Members

dwServiceFlags1

A bitmask describing the services provided by the protocol. The following values are possible:

XP1_CONNECTIONLESS

The protocol provides connectionless (datagram) service. If not set, the protocol supports connection-oriented data transfer.

XP1_GUARANTEED_DELIVERY

The protocol guarantees that all data sent will reach the intended destination.

XP1_GUARANTEED_ORDER

The protocol guarantees that data will only arrive in the order in which it was sent and that it will not be duplicated. This characteristic does not necessarily mean that the data will always be delivered, but that any data that is delivered is delivered in the order in which it was sent.

XP1_MESSAGE_ORIENTED

The protocol honors message boundaries, as opposed to a stream-oriented protocol where there is no concept of message boundaries.

XP1_PSEUDO_STREAM

This is a message oriented protocol, but message boundaries will be ignored for all receives. This is convenient when an application does not desire message framing to be done by the protocol.

XP1_GRACEFUL_CLOSE

The protocol supports two-phase (graceful) close. If not set, only abortive closes are performed.

XP1_EXPEDITED_DATA

The protocol supports expedited (urgent) data.

XP1_CONNECT_DATA

The protocol supports connect data.

XP1_DISCONNECT_DATA

The protocol supports disconnect data.

XP1_SUPPORT_BROADCAST

The protocol supports a broadcast mechanism.

XP1_SUPPORT_MULTIPOINT

The protocol supports a multipoint or multicast mechanism. Control and data plane attributes are indicated below. XP1_MULTIPOINT_CONTROL_PLANE

Indicates whether the control plane is rooted (value = 1) or non-rooted (value = 0).

XP1_MULTIPOINT_DATA_PLANE

Indicates whether the data plane is rooted (value = 1) or non-rooted (value = 0).

XP1_QOS_SUPPORTED

The protocol supports quality of service requests.

XP1_RESERVED

This bit is reserved.

XP1_UNI_SEND

The protocol is unidirectional in the send direction.

XP1_UNI_RECV

the protocol is unidirectional in the recv direction.

XP1_IFS_HANDLES

The socket descriptors returned by the provider are operating system Installable File System (IFS) handles.

XP1_PARTIAL_MESSAGE

The MSG_PARTIAL flag is supported in WSASend and WSASendTo.

Note that only one of XP1_UNI_SEND or XP1_UNI_RECV may be set. If a protocol can be unidirectional in either direction, two WSAPROTOCOL_INFO structs should be used. When neither bit is set, the protocol is considered to be bi-directional.

dwServiceFlags2

Reserved for additional protocol attribute definitions.

dwServiceFlags3

Reserved for additional protocol attribute definitions.

dwServiceFlags4

Reserved for additional protocol attribute definitions.

dwProviderFlags

Provide information about how this protocol is represented in the protocol catalog. The following flag values are possible:

PFL_MULTIPLE_PROTOCOL_ENTRIES

Indicates that this is one of two or more entries for a single protocol (from a given provider) which is capable of implementing multiple behaviors. An example of this is SPX which, on the receiving side, can behave either as a message oriented or a stream oriented protocol.

PFL_RECOMMENDED_PROTO_ENTRY

Indicates that this is the recommended or most frequently used entry for a protocol which is capable of implementing multiple behaviors.

PFL_HIDDEN

Set by a provider to indicate to the WS2_32.DLL that this protocol should not be returned in the result buffer generated by WSAEnumProtocols. Obviously, a Windows Sockets 2 application should never see an entry with this bit set.

PFL_MATCHES_PROTOCOL_ZERO

Indicates that a value of zero in the protocol parameter of socket or WSASocket matches this protocol entry.

ProviderId

A globally unique identifier assigned to the provider by the service provider vendor. This value is useful for instances where more than one service provider is able to implement a particular protocol. An application may use the dwProviderId value to distinguish between providers that might otherwise be indistinguishable.

dwCatalogEntryId

A unique identifier assigned by the WS2_32.DLL for each WSAPROTOCOL_INFO structure.

WSAPROTOCOLCHAIN ProtocolChain;

If the length of the chain is 0, this WSAPROTOCOL_INFO entry represents a layered protocol which has Windows Sockets 2 SPI as both its top and bottom edges. If the length of the chain equals 1, this entry represents a base protocol whose Catalog Entry ID is in the dwCatalogEntryId field of the WSAPROTOCOL_INFO structure. If the length of the chain is larger than 1, this entry represents a protocol chain which consists of one or more layered protocols on top of a base protocol. The corresponding Catalog Entry IDs are in the ProtocolChain.ChainEntries array starting with the layered protocol at the top (the zero element in the ProtocolChain.ChainEntries array) and ending with the base protocol. Refer to the Windows Sockets 2 Service Provider Interface specification for more information on protocol chains.

iVersion

Protocol version identifier.

iAddressFamily

The value to pass as the address family parameter to the socket/WSASocket function in order to open a socket for this protocol. This value also uniquely defines the structure of protocol addresses (SOCKADDRs) used by the protocol.

iMaxSockAddr

The maximum address length.

iMinSockAddr

The minimum address length.

iSocketType

The value to pass as the socket type parameter to the socket function in order to open a socket for this protocol.

iProtocol

The value to pass as the protocol parameter to the socket function in order to open a socket for this protocol.

iProtocolMaxOffset

The maximum value that may be added to iProtocol when supplying a value for the protocol parameter to socket and WSASocket. Not all protocols allow a range of values. When this is the case iProtocolMaxOffset will be zero.

iNetworkByteOrder

Currently these values are manifest constants (BIGENDIAN and LITTLEENDIAN) that indicate either “big-endian” or “little-endian” with the values 0 and 1 respectively.

iSecurityScheme

Indicates the type of security scheme employed (if any). A value of SECURITY_PROTOCOL_NONE is used for protocols that do not incorporate security provisions.

dwMessageSize

The maximum message size supported by the protocol. This is the maximum size that can be sent from any of the host’s local interfaces. For protocols which do not support message framing, the actual maximum that can be sent to a given address may be less. The following special values are defined:

0

The protocol is stream-oriented and hence the concept of message size is not relevant.

0x1

The maximum message size is dependent on the underlying network MTU (maximum sized transmission unit) and hence cannot be known until after a socket is bound. Applications should use getsockopt to retrieve the value of SO_MAX_MSG_SIZE after the socket has been bound to a local address.

0xFFFFFFFF

The protocol is message-oriented, but there is no maximum limit to the size of messages that may be transmitted.

dwProviderReserved

Reserved for use by service providers.

szProtocol

An array of characters that contains a human-readable name identifying the protocol, for example "SPX2". The maximum number of characters allowed is WSAPROTOCOL_LEN, which is defined to be 255.


WSAPROTOCOLCHAIN

A structure containing a counted list of Catalog Entry IDs which comprise a protocol chain. This structure is defined as follows:

typedef struct _WSAPROTOCOLCHAIN {

    int ChainLen;           /* the length of the chain,  */

                            /* length = 0 means layered protocol, */

                            /* length = 1 means base protocol,

                            /* length > 1 means protocol chain */

    DWORD ChainEntries[MAX_PROTOCOL_CHAIN];

                            /* a list of dwCatalogEntryIds */

} WSAPROTOCOLCHAIN, FAR * LPWSAPROTOCOLCHAIN;


WSAServiceClassInfo

typedef struct _WSAServiceClassInfoW

{

    LPGUID              lpServiceClassId;

    LPWSTR              lpszServiceClassName;

    DWORD               dwCount;

    LPWSANSCLASSINFOW   lpClassInfos;

}WSASERVICECLASSINFOW, *PWSASERVICECLASSINFOW, *LPWSASERVICECLASSINFOW;


Filters

The following filters are used by the Internet Server.

GetFilterVersion

HttpFilterProc


GetFilterVersion

The GetFilterVersion function is the first entry point called by the Internet Server.

BOOL WINAPI GetFilterVersion(

PHTTP_FILTER_VERSION pVer
);
Parameters

pVer

The HTTP_FILTER_VERSION structure pointed to by this parameter contains both the version information for the server and the fields for the client to indicate version number, notifications, and priority desired. There is also a space for the filter application to register a description of itself.

Return Values

The return code indicates whether the filter was properly loaded. If the filter returns FALSE, the filter application will be unloaded and will not receive any notifications.

Remarks

The GetFilterVersion function, implemented in the ISAPI filter application, is the first entry point called by the Internet Server. It is important to specify only the necessary notifications in the pVer->dwFlags member. Some notifications can have a strong impact on performance and scalability.

In addition to the notification flags described under the HttpFilterProc function, there are also priority flags to specify the order in which to call the filter:

Value	Meaning
SF_NOTIFY_ORDER_DEFAULT	Load the filter at the default priority (recommended).
SF_NOTIFY_ORDER_LOW	Load the filter at a low priority.
SF_NOTIFY_ORDER_MEDIUM	Load the filter at a medium priority.
SF_NOTIFY_ORDER_HIGH	Load the filter at a high priority.
Note  Every filter is contained in a separate DLL with two common entry points: GetFilterVersion and HttpFilterProc. When the DLL is loaded, GetFilterVersion is called. This lets the filter know the server version and also lets the filter tell the server the filter version and the events that the filter is interested in.

After this, the server calls the filter's HttpFilterProc entry point with appropriate notifications. Note that filters should only register for notifications the filter needs to see — some filter notifications are very expensive in terms of CPU resources and I/O throughput, and can have a significant effect on the speed and scalability of the Microsoft Internet Server.

BOOL WINAPI GetFilterVersion(
    HTTP_FILTER_VERSION *pVer
   );

DWORD WINAPI HttpFilterProc(
    HTTP_FILTER_CONTEXT *pfc,
    DWORD notificationType,
    VOID *pvNotification
   );

See Also

HttpFilterProc, HTTP_FILTER_VERSION


HttpFilterProc

The HttpFilterProc records notification of events from the server.

DWORD WINAPI HttpFilterProc(

PHTTP_FILTER_CONTEXT pfc,
DWORD notificationType,
LPVOID pvNotification
);
Parameters

pfc

The HTTP_FILTER_CONTEXT structure pointed to by this parameter contains context information. The pFilterContext member can be used by the filter to associate any context information with the HTTP request. The SF_NOTIFY_END_OF_NET_SESSION notification can be used to release any such context information.

notificationType

This indicates the type of event being processed. Valid types are:

SF_NOTIFY_SECURE_PORT

Notify application only for sessions over a secure port.

SF_NOTIFY_NONSECURE_PORT

Notify application only for sessions over a nonsecure port.

SF_NOTIFY_READ_RAW_DATA

Allow the application to see the raw data. The data returned will contain both headers and data.

SF_NOTIFY_PREPROC_HEADERS

The server has preprocessed the headers.

SF_NOTIFY_AUTHENTICATION

The server is authenticating the client.

SF_NOTIFY_URL_MAP

The server is mapping a logical URL to a physical path.

SF_NOTIFY_SEND_RAW_DATA

The server is sending raw data back to the client.

SF_NOTIFY_LOG

The server is writing information to the server log.

SF_NOTIFY_END_OF_NET_SESSION

The session with the client is ending.

SF_NOTIFY_ACCESS_DENIED

Allows an ISAPI Filter to be notified any time the server is about to return a "401 Access Denied".  This lets the Filter analyze the failure and return a custom message.

pvNotification

The notification-specific structure.

Notification Type	pvNotification points to
SF_NOTIFY_READ_RAW_DATA	HTTP_FILTER_RAW_DATA
SF_NOTIFY_SEND_RAW_DATA	HTTP_FILTER_RAW_DATA
SF_NOTIFY_PREPROC_HEADERS	HTTP_FILTER_PREPROC_HEADERS
SF_NOTIFY_AUTHENTICATION	HTTP_FILTER_AUTHENT
SF_NOTIFY_URL_MAP	HTTP_FILTER_URL_MAP
SF_NOTIFY_LOG	HTTP_FILTER_LOG
SF_NOTIFY_ACCESS_DENIED	HTTP_FILTER_ACCESS_DENIED
Return Values

The return codes indicate how the application handled the event. Possible return codes are:

SF_STATUS_REQ_FINISHED

The filter has handled the HTTP request. The server should disconnect the session.

SF_STATUS_REQ_FINISHED_KEEP_CONN

This is the same as SF_STATUS_REQ_FINISHED, except that the server should keep the TCP session open if the option was negotiated.

SF_STATUS_REQ_NEXT_NOTIFICATION

The next filter in the notification chain should be called.

SF_STATUS_REQ_HANDLED_NOTIFICATION

This filter handled the notification. No other handlers should be called for this particular notification type.

SF_STATUS_REQ_ERROR

An error occurred. The server should call GetLastError and indicate the error to the client.

SF_STATUS_REQ_READ_NEXT

The filter is an opaque stream filter and the session parameters are being negotiated. This is valid only for raw-read notification.

Remarks

This is where the core work of the ISAPI filter applications is done. The various structures pointed to by pvNotification contain data and function pointers specific to these operations. See the structure details for more information.

Note  Every filter is contained in a separate DLL with two common entry points: GetFilterVersion and HttpFilterProc. When the DLL is loaded, GetFilterVersion is called. This lets the filter know the server version and also lets the filter tell the server the filter version and the events that the filter is interested in.

After this, the server calls the filter's HttpFilterProc entry point with appropriate notifications. Note that filters should only register for notifications the filter needs to see — some filter notifications are very expensive in terms of CPU resources and I/O throughput, and can have a significant effect on the speed and scalability of the Microsoft Internet Server.

BOOL WINAPI GetFilterVersion(
    HTTP_FILTER_VERSION *pVer
   );

DWORD WINAPI HttpFilterProc(
    HTTP_FILTER_CONTEXT *pfc,
    DWORD notificationType,
    VOID *pvNotification
   );

See Also

HTTP_FILTER_CONTEXT, HTTP_FILTER_RAW_DATA, HTTP_FILTER_PREPROC_HEADERS, HTTP_FILTER_AUTHENT, HTTP_FILTER_URL_MAP, HTTP_FILTER_LOG


Functions

The following functions are used by the Internet Server.

GetServerVariable

ReadClient

ServerSupportFunction

WriteClient


GetServerVariable

The GetServerVariable function retrieves information about a connection or about the server itself.

BOOL WINAPI GetServerVariable(

HCONN hConn,
LPSTR lpszVariableName,
LPVOID lpvBuffer,
LPDWORD lpdwSizeofBuffer
);
Parameters

hConn

[in] The connection handle.

lpszVariableName

[in] A null-terminated string indicating which variable is being requested.

lpvBuffer

[out] A pointer to the buffer to receive the requested information.

lpdwSizeofBuffer

[in/out] A pointer to DWORD indicating the size of the buffer pointed to by lpvBuffer. On successful completion, the DWORD contains the size  of bytes transferred into the buffer, including the null-terminating byte.

Return Values

If the function is successful, a return value of TRUE is returned. If the function fails, a return value of FALSE is returned. The Win32 GetLastError function can be used to determine why the call failed.

Possible error values include:

Value	Meaning
ERROR_INVALID_PARAMETER	Bad connection handle.
ERROR_INVALID_INDEX	Bad or unsupported variable identifier.
ERROR_INSUFFICIENT_BUFFER	Buffer too small. The required buffer size is lpdwSize.
ERROR_MORE_DATA	Buffer too small. Only part of the data is returned. The total size of the data is not known.
ERROR_NO_DATA	The data requested is not available.
Remarks

The GetServerVariable function copies information into a buffer supplied by the caller. The information can include CGI variables and information relating to an HTTP connection or to the server itself.

Possible lpszVariableNames include:

AUTH_TYPE	This contains the type of authentication used. For example, the string will be “basic” if basic authentication is used, and it will be “NTLM” for Challenge-response. Other authentication schemes will have other strings. Since new authentication types can be added to the Internet Server, it is not possible to list all the string possibilities. If the string is empty, then no authentication is used.
CONTENT_LENGTH	The number of bytes which the script can expect to receive from the client.
CONTENT_TYPE	The content type of the information supplied in the body of a POST request.
PATH_INFO	Additional path information, as given by the client. This consists of the trailing part of the URL after the script name, but before the query string, if any.
PATH_TRANSLATED	This is the value of PATH_INFO, but with any virtual path name expanded into a directory specification.
QUERY_STRING	The information which follows the “?” in the URL that referenced this script.
REMOTE_ADDR	The IP address of the client or agent of the client (for example, gateway or firewall) that sent the request.
REMOTE_HOST	The host name of the client or agent of the client (for example, gateway or firewall) that sent the request.
REMOTE_USER	This contains the user name supplied by the client and authenticated by the server. This comes back as an empty string when the user is anonymous (but authenticated).
UNMAPPED_REMOTE_USER	This is the user name before any ISAPI ApplicationsPI Filter mapped the user making the request to an NT user account (which appears as REMOTE_USER).
REQUEST_METHOD	The HTTP request method.
SCRIPT_NAME	The name of the script program being executed.
SERVER_NAME	The server's host name, or IP address, as it should appear in self-referencing URLs.
SERVER_PORT	The TCP/IP port on which the request was received.
SERVER_PORT_SECURE	A string of either zero or 1.  If the request is being handled on the secure port, then this will be 1. Otherwise, it will be zero.
SERVER_PROTOCOL	The name and version of the information retrieval protocol relating to this request. This is usually HTTP/1.0.
SERVER_SOFTWARE	The name and version of the Web server under which the ISAPI ApplicationsPI DLL program is running.
ALL_HTTP	All HTTP headers that were not already parsed into one of the previous variables. These variables are of the form HTTP_<header field name>. The headers consist of a null-terminated string with the individual headers separated by line feeds.
HTTP_ACCEPT	Special-case HTTP header. Values of the Accept: fields are concatenated, and separated by a comma (“,”). For example, if the following lines are part of the HTTP header:    accept: */*; q=0.1    accept: text/html    accept: image/jpeg the HTTP_ACCEPT variable will have a value of:    */*; q=0.1, text/html, image/jpeg
URL (new for version 2.0)	Gives the base portion of the URL.
Note  In respect to Auth_Type, if the string is not empty it does not mean the user was authenticated, (if the authentication scheme is not "basic" or "NTLM").  The server allows authentication schemes it does not natively understand since an ISAPI ApplicationsPI Filter may be able to handle that particular scheme.


ReadClient

The ReadClient function reads data from the body of the client's HTTP request.

BOOL ReadClient(

HCONN hConn,
LPVOID lpvBuffer,
LPDWORD lpdwSize
);
Parameters

hConn

[in] A connection handle.

lpvBuffer

[out] A pointer to the buffer area to receive the requested information.

lpdwSize

[in/out] A pointer to DWORD indicating the number of bytes available in the buffer. On return, lpdwSize will contain the number of bytes actually transferred into the buffer.

Return Values

If the function is successful, a value of TRUE is returned. If an error occurs, a value of FALSE is returned. The GetLastError function can be called to determine the cause of the error.

Remarks

The ReadClient function reads information from the body of the Web client's HTTP request into the buffer supplied by the caller. Thus, the call can be used to read data from an HTML form that uses the POST method. If more than lpdwSize bytes are immediately available to be read, ReadClient will return after transferring that amount of data into the buffer. Otherwise, it will block and wait for data to become available. If the socket on which the server is listening to the client is closed, it will return TRUE, but with zero bytes read.


ServerSupportFunction

The ServerSupportFunction function is a callback function supplied in the EXTENSION_CONTROL_BLOCK (ECB). It supports several auxiliary functions not covered by other callback functions in the ECB.

BOOL ServerSupportFunction(

HCONN ConnID,
DWORD dwHSERequest,
LPVOID lpvBuffer,
LPDWORD lpdwSize,
LPDWORD lpdwDataType
);
Parameters

ConnID

A logical connection identifier for identifying the client to whom the response data should be sent.

dwHSERequest

A DWORD containing the HTTP Server Extension Request type, which indicates the requested functions by the ISAPI application. The various values are:

HSE_REQ_SEND_URL_REDIRECT_RESP

This sends a 302 (URL Redirect) message to the client. No further processing is needed after the call. This operation is similar to specifying "URI: <URL>" in a CGI script header. The lpvBuffer variable should point to a null-terminated string of URL. The variable lpdwSize should have the size of lpvBuffer. The variable lpdwDataType is ignored.

HSE_REQ_SEND_URL

This sends the data specified by the URL to the client as if the client had requested that URL. The null-terminated URL pointed to by lpvBuffer must be on the server and must not specify protocol information (that is, it must begin with a “/”). No further processing is required after this call. The parameter lpdwSize points to a DWORD holding the size of lpvBuffer. The parameter lpdwDataType is ignored.

HSE_REQ_SEND_RESPONSE_HEADER

This sends a complete HTTP server response header including the status, server version, message time, and MIME version. The ISAPI application should append other HTTP headers such as the content type and content length, followed by an extra “\r\n”. This function only takes textual data, up to the first '\0' terminator

HSE_REQ_MAP_URL_TO_PATH

The lpvBuffer parameter is a pointer to the buffer that contains the logical path on entry and the physical path on exit. The lpdwSize parameter is a pointer to the DWORD containing the size of the buffer passed in lpvBuffer on entry, and the number of bytes placed in the buffer on exit. The lpdwDataType parameter is ignored.

HSE_REQ_DONE_WITH_SESSION

If the server extension wants to hold on to the session because of extended processing requirements, it needs to tell the server when the session is finished so the server can close it and free the related structures. The parameters lpvBuffer, lpdwSize, and lpdwDataType are all ignored.

lpvBuffer

A pointer to the buffer that contains the primary argument required for the support function requested.

lpdwSize

A pointer to a DWORD that contains the size of data that is passed in the buffer pointed to by lpvBuffer. This parameter may be unused for several of the support function options.

lpdwDataType

A pointer to a DWORD containing a pointer, flags, or secondary arguments required for the specified support function.

Return Values

If the function is successful, a value of TRUE is returned. If an error occurs, a value of FALSE is returned. The GetLastError function can be called to determine the cause of the error.

Remarks

The ServerSupportFunction function provides several support functions that are not covered directly by ECB or the standard callback function. The following list describes the various requests that can be made using the ServerSupportFunction function:

1.	dwHSERRequest: HSE_REQ_IO_COMPLETION

lpvBuffer

A pointer to callback function PFN_HSE_IO_COMPLETION.

lpdwSize

This is ignored.

LpdwDataType

A pointer of type (PVOID) which is used as the context.

This option lets the ISAPI application set a callback function and context to use for handling asynchronous I/O operations. The callback function is used only if the function pointer passed is non-NULL. Any context value is allowed. If multiple calls are made for this option, the values used in the most recent call to ServerSupportFunction will be used (all old values will be lost). The callback function is defined as:

typedef VOID  (WINAPI * PFN_HSE_IO_COMPLETION)(

    IN EXTENSION_CONTROL_BLOCK * pECB,

    IN PVOID    pContext,

    IN DWORD    cbIO,

    IN DWORD    dwError );

In case of errors during asynchronous I/O processing, the server makes a single call to the callback function. It is the responsibility of the ISAPI application to do the cleanup during the call.

2.	 dwHSERRequest: HSE_REQ_TRANSMIT_FILE

lpvBuffer

A pointer to the HSE_TF_INFO object.

LpdwSize

This is ignored.

LpdwDataType

This is ignored.

This option lets the ISAPI application use TransmitFile to send a file (faster) to the client. The server performs this operation asynchronously. The application should either submit a callback function (and context) by setting the values in the HSE_TF_INFO object passed in or should call the ServerSupportFucntion function with HSE_REQ_IO_COMPLETION.

If none of the above is done, this call will fail and the server will return an error (ERROR_INVALID_PARAMETER). Also, the application should specify the file handle in the structure that is passed in.

If all parameters are present, the server submits this operation to its internal asynchronous I/O queue and returns to the caller. At this point, the ISAPI application can return HSE_STATUS_PENDING (if returning from HttpExtenionProc) and later use HSE_DONE_WITH_SESSION when the callback occurs indicating that the I/O was completed.

typedef struct _HSE_TF_INFO  {

    //

    // callback and context information

    // the callback function will be called when IO is completed.

    // the context specified will be used during such callback.

    //

    // These values (if non-NULL) will override the one set by calling

    //  ServerSupportFunction() with HSE_REQ_IO_COMPLETION

    //

    PFN_HSE_IO_COMPLETION   pfnHseIO;

    PVOID  pContext;

    // file should have been opened with FILE_FLAG_SEQUENTIAL_SCAN

    HANDLE hFile;

    //

    // HTTP header and status code

    // These fields are used only if HSE_IO_SEND_HEADERS

    //  is present in dwFlags

    //

    LPCSTR pszStatusCode; // HTTP Status Code  eg: "200 OK"

    DWORD  BytesToWrite; // value of "0" means send entire file

    DWORD  Offset; 	    // offset value within file to start from

    PVOID  pHead;        // pointer to Headers to be sent before file

    DWORD  HeadLength;   // header length

    PVOID  pTail;        // pointer to Tail to be sent after file data

    DWORD  TailLength;   // tail length

    DWORD  dwFlags;      // includes HSE_IO_DISCONNET_AFTER_SEND, ...

} HSE_TF_INFO, * LPHSE_TF_INFO;

A special flag, HSE_IO_DISCONNECT_AFTER_SEND, can be used if the application is mainly concerned with transmitting the file and closing the connection. This flag enables the server to optimally reuse its internal buffers and sockets for future connections. Thus, it improves the perceived latency by optimally using system features. However, the application will not be able to do any further data transmission if this flag is indicated, because the session to the client will be torn down.

Another special flag, HSE_IO_SEND_HEADER, can be used for transmitting custom header information to the client. The ISAPI application can store the status code (for example, “200 OK”) in the pszStatusCode member of the HSE_TF_INFO structure. When the header flag is turned on, the Internet server will automatically construct the appropriate HTTP header and send it to the client along with the file contents.

If this flag is used for header transmission, then the ISAPI application should not send its own header using the ServerSupportFunction(HSE_REQ_SEND_RESPONSE_HEADERS) function. In addition to the status code, the application can also include a special head buffer for each data chunk that it transmits from a file.

The file handle specified, hFile, should be opened using the Win32 CreateFile function with the FILE_FLAG_SEQUENTIAL_SCAN and FILE_FLAG_OVERLAPPED turned on. The head and tail buffers specified by pHead and pTail are optional.

Asynchronous I/O Support

Previous versions of this documentation have supported synchronous I/O operations using the callback functions, ReadClient and WriteClient. However, the ability to support asynchronous operations is important because it frees up a server pool thread from being blocked in completing the I/O operation. In addition, the Internet server engine already has built-in support to manage asynchronous I/O operations using the completion ports and server thread pool.

Support for asynchronous I/O operations were initially planned for a later version of this documentation. However, because of the need to support asynchronous I/O operations, a Microsoft-specific extension has been provided in this documentation. Thus, asynchronous write operations are supported in this documentation using the existing callback function WriteClient, with a special flag indicating that the operation has to be performed asynchronously. In addition, this documentation also provides a mechanism for requesting that the server transmit a file using the TransmitFile function. This function is a Win32 function that supports fast transmission of a file-from-file system over any stream sockets. It is supported in the Microsoft Windows Sockets implementation in Windows NT 3.51 and later.


WriteClient

The WriteClient function is a callback function supplied in the EXTENSION_CONTROL_BLOCK (ECB) for a request sent to the ISAPI application. This function sends data present in the given buffer to the client that made the request.

BOOL WriteClient(

HCONN ConnID,
LPVOID Buffer,
LPDWORD lpdwBytesr,
DWORD dwReserved
);
Parameters

ConnID

[in] A logical connection identifier for identifying the client to whom the response data should be sent.

Buffer

[in] A pointer to the buffer containing the data to be sent.

lpdwBytes

[in/out] A pointer to a DWORD that contains the number of bytes in the buffer that need to be sent out when the call is made, and contains the number of bytes of data successfully sent out for synchronous write operations. For asynchronous write operations, the returned value has no meaning.

dwReserved

A DWORD containing flags indicating how the I/O operation should be handled. The following flags are supported:

Value	Meaning
HSE_IO_SYNC	This indicates that the I/O operation should be done synchronously.
HSE_IO_ASYNC	This indicates that the I/O operation should be done asynchronously. The ISAPI application should have made a call to the ServerSupportFunction(HSE_REQ_IO_COMPLETION) function and submitted a callback function and context value for handling completion of asynchronous operations.
Return Values

If the function is successful, a value of TRUE is returned. If an error occurs, a value of FALSE is returned. The GetLastError function can be called to determine the cause of the error.

Remarks

The WriteClient function attempts to write the data in the supplied buffer to the socket in which the client request came. For synchronous writes, it attempts to the write in the called thread and the I/O may block trying to send the data to the client. On completion, the WriteClient function returns the number of bytes sent in lpdwBytes.

For asynchronous writes, the WriteClient function submits the write operation to the asynchronous thread queue and returns from the call immediately. At this point, the ISAPI application can choose to do more background processing or return from the HttpExtensionProc function with a HSE_STATUS_PENDING. When the I/O operation is completed, the server calls the callback function submitted by the ISAPI application with the ECB, context value, number of bytes sent, and error codes (if there are any errors).

It is the responsibility of the ISAPI application to do further processing and to use the ServerSupportFunction(HSE_DONE_WITH_SESSION) function to notify the server when it is done processing the request.

Only one outstanding asynchronous I/O operation is permitted per request. This includes asynchronous WriteClient, asychronous TransmitFile, or a ServerSupportFunction call with HSE_REQ_SEND_URL.

Asynchronous I/O Support

Previous versions of this documentation have supported synchronous I/O operations using the callback functions, ReadClient and WriteClient. However, the ability to support asynchronous operations is important because it frees up a server pool thread from being blocked in completing the I/O operation. In addition, the Internet server engine already has built-in support to manage asynchronous I/O operations using the completion ports and server thread pool.

Support for asynchronous I/O operations were initially planned for a later version of this documentation. However, because of the need to support asynchronous I/O operations, a Microsoft-specific extension has been provided in this documentation. Thus, asynchronous write operations are supported in this documentation using the existing callback function WriteClient, with a special flag indicating that the operation has to be performed asynchronously. In addition, this documentation also provides a mechanism for requesting that the server transmit a file using the TransmitFile function. This function is a Win32 function that supports fast transmission of a file-from-file system over any stream sockets. It is supported in the Microsoft Windows Sockets implementation in Windows NT 3.51 and later.


Modules

 The following module is used by the Internet Server.

Http Server Extension Interface


HTTP Server Extension Interface

Module Name: HttpExt.h

The following section contains structure definitions and prototypes for version 1.0 of the HTTP Server Extension interface. See specifically Converting Existing CGI Scripts to ISAPI Application DLLs and Important Notes.


Structures

The following structures are used by the Internet Server.

HTTP_FILTER_ACCESS_DENIED

HTTP_FILTER_AUTHENT

HTTP_FILTER_CONTEXT

HTTP_FILTER_LOG

HTTP_FILTER_PREPROC_HEADERS

HTTP_FILTER_RAW_DATA

HTTP_FILTER_VERSION

HTTP_FILTER_URL_MAP


HTTP_FILTER_ACCESS_DENIED

Bitfield indicating the requested resource has been denied by the server due to a logon failure, an ACL on a resource, an ISAPI Filter, or an ISAPI application/CGI application.

SF_DENIED_BY_CONFIG can appear with SF_DENIED_LOGON if the server configuration did not allow the user to log on.

#define SF_DENIED_LOGON             0x00000001

#define SF_DENIED_RESOURCE          0x00000002

#define SF_DENIED_FILTER            0x00000004

#define SF_DENIED_APPLICATION       0x00000008

#define SF_DENIED_BY_CONFIG         0x00010000

typedef struct _HTTP_FILTER_ACCESS_DENIED (added in Version 2.0)

{

const CHAR * pszURL;           Requesting URL

const CHAR * pszPhysicalPath;  Physical path of resource

DWORD        dwReason;         Bitfield of SF_DENIED flags

}

HTTP_FILTER_ACCESS_DENIED, *PHTTP_FILTER_ACCESS_DENIED

The server will automatically include the supported authentication schemes when an ISAPI application, Filter or CGI Script returns a "401 Access Denied".


HTTP_FILTER_AUTHENT

typedef struct _HTTP_FILTER_AUTHENT

{

    CHAR *    pszUser;

    DWORD     cbUserBuff;

    CHAR *    pszPassword;

    DWORD     cbPasswordBuff;

} HTTP_FILTER_AUTHENT, *PHTTP_FILTER_AUTHENT;

Members

pszUser

[in/out] A pointer to a string containing the user name for this request. An empty string indicates an anonymous user.

cbUserBuff

[in] The size of the buffer pointed to by pszUser. This is guaranteed to be at least SF_MAX_USERNAME.

pszPassword

[in/out] A pointer to a string containing the password for this request.

cbPasswordBuff

[in] The size of the buffer pointed to by pszPassword. This is guaranteed to be at least SF_MAX_PASSWORD.

Remarks

When the server is about to authenticate the client, this structure is pointed to by the pvNotification in the HttpFilterProc when notificationType is SF_NOTIFY_AUTHENTICATION. This can be used to implement a different authentication scheme.

See Also

HttpFilterProc


HTTP_FILTER_CONTEXT

typedef struct _HTTP_FILTER_CONTEXT

{

    DWORD    cbSize;

    DWORD    Revision;

    PVOID    ServerContext;

    DWORD    ulReserved;

    BOOL     fIsSecurePort;

    PVOID    pFilterContext;

    BOOL    (WINAPI * GetServerVariable) (

    struct _HTTP_FILTER_CONTEXT *    pfc,

    LPSTR      lpszVariableName,

    LPVOID     lpvBuffer,

    LPDWORD    lpdwSize

    );

BOOL    (WINAPI * AddResponseHeaders) (

    struct _HTTP_FILTER_CONTEXT *    pfc,

    LPSTR    lpszHeaders,

    DWORD    dwReserved

    );

BOOL    (WINAPI * WriteClient)  (

    struct _HTTP_FILTER_CONTEXT *    pfc,

    LPVOID     Buffer,

    LPDWORD    lpdwBytes,

    DWORD      dwReserved

    );

VOID *     (WINAPI * AllocMem) (

    struct _HTTP_FILTER_CONTEXT *    pfc,

    DWORD      cbSize,

    DWORD      dwReserved

    );

BOOL    (WINAPI * ServerSupportFunction) (

    struct _HTTP_FILTER_CONTEXT *    pfc,

    enum SF_REQ_TYPE    sfReq,

    PVOID       pData,

    DWORD       ul1,

    DWORD       ul2

    );

} HTTP_FILTER_CONTEXT, *PHTTP_FILTER_CONTEXT;

Members

cbSize

[in] The size of this structure, in bytes.

Revision

[in] The revision level of this structure. This is less than or equal to the version of the document, HTTP_FILTER_REVISION.

ServerContext

[in] Reserved for server use.

ulReserved

[in] Reserved for server use.

fIsSecurePort

[in] A value of TRUE indicates that this event is over a secure port.

pFilterContext

[in/out] A pointer to be used by the filter for any context information that the filter wants to associate with this request. Any memory associated with this request can be safely freed during the SF_NOTIFY_END_OF_NET_SESSION notification.

BOOL    (WINAPI * GetServerVariable) (
    struct _HTTP_FILTER_CONTEXT *pfc,
    LPSTR lpszVariableName,
    LPVOID lpvBuffer,
    LPDWORD lpdwSize
   );

A pointer to a function to retrieve information about the server and this connection. See GetServerVariable for more information.

Parameters

pfc

The pfc passed to HttpFilterProc.

lpszVariableName

The server variable to retrieve.

lpvBuffer

The buffer in which to store the value of the variable.

lpdwSize

The size of the buffer pointed to by lpvBuffer.

BOOL    (WINAPI * AddResponseHeaders) (
    struct _HTTP_FILTER_CONTEXT *pfc,
    LPSTR lpszHeaders,
    DWORD dwReserved
   );

A pointer to a function that adds a header to the HTTP response. See ServerSupportFunction, HSE_SEND_RESPONSE_HEADER, for more information.

Parameters

pfc

The pfc passed to HttpFilterProc.

lpszHeaders

A pointer string containing the headers to add.

dwReserved

Reserved for future use. This must be zero.

BOOL    (WINAPI * )  (
    struct _HTTP_FILTER_CONTEXT *pfc,
.   LPVOID buffer,
    LPDWORD lpdwBytes,
    DWORD dwReserved
   );

A pointer to a function that sends raw data back to the client. See WriteClient for more information.

Parameters

pfc

The pfc passed to HttpFilterProc.

buffer

A buffer containing data to send to the client.

lpdwBytes

The size of the buffer pointed to by buffer.

dwReserved

Reserved for future use.

VOID *     (WINAPI * AllocMem) (
struct _HTTP_FILTER_CONTEXT *pfc,
    DWORD cbSize,
    DWORD dwReserved
   );

A pointer to a function used to allocate memory. Any memory allocated with this function will automatically be freed when the request is completed.

Parameters

pfc

The pfc passed to HttpFilterProc.

cbSize

The size of the buffer to allocate.

dwReserved

Reserved for future use.

BOOL    (WINAPI * ServerSupportFunction) (
struct _HTTP_FILTER_CONTEXT *pfc,
    enum SF_REQ_TYPE sfReq,
    PVOID pData,
    DWORD ul1,
    DWORD ul2
    );

A pointer to a function used to extend the ISAPI filter functions. Parameters are specific to the extensions. Possible values for sfReq are SF_REQ_SEND_RESPONSE_HEADER, SF_REQ_ADD_HEADERS_ON_DENIAL, and SF_REQ_SET_NEXT_READ_SIZE.

SF_REQ_SEND_RESPONSE_HEADER

This sends a complete HTTP server response header including the status, server version, message time, and MIME version. Server extensions should append other information, such as content type and content length, followed by an extra “\r\n”.

Parameters

pData

A zero-terminated string pointing to optional status string (for example, "401 Access Denied") or NULL for the default response of "200 OK".

ul1

A zero-terminated string pointing to optional data to be appended and sent with the header. If NULL, the header will be terminated with an empty line.

SF_REQ_ADD_HEADERS_ON_DENIAL

If the server denies the HTTP request, add the specified headers to the server error response. This allows an authentication filter to advertise its services without filtering every request. Generally, the headers will be WWW-Authenticate headers with custom authentication schemes. However, no restriction is placed on which headers can be specified.

Parameters

pData

A zero-terminated string pointing to one or more header lines with terminating “\r\n.”

SF_REQ_SET_NEXT_READ_SIZE

This is used only by raw data filters that return SF_STATUS_READ_NEXT.

Parameters

ul1

The size in bytes for the next read.


HTTP_FILTER_LOG

typedef struct _HTTP_FILTER_LOG

{

    const CHAR *    pszClientHostName;

    const CHAR *    pszClientUserName;

    const CHAR *    pszServerName;

    const CHAR *    pszOperation;

    const CHAR *    pszTarget;

    const CHAR *    pszParameters;

    DWORD        dwHttpStatus;

    DWORD        dwWin32Status;

} HTTP_FILTER_LOG, *PHTTP_FILTER_LOG;

Members

pszClientHostName

[in/out] The client’s host name.

pszClientUserName

[in/out] The client’s user name.

pszServerName

[in/out] The name of the server the client is connected to.

pszOperation

[in/out] The HTTP command.

pszTarget

[in/out] The target of the HTTP command.

pszParameters

[in/out] The parameters passed to the HTTP command.

dwHttpStatus

[in/out] The HTTP return status.

dwWin32Status

[in/out] The Win32 error code.

Remarks

When the server is about to log information to the server log file, this structure is pointed to by the pvNotification in the HttpFilterProc when notificationType is SF_NOTIFY_LOG. The strings cannot be changed, but pointers can be replaced. If string pointers are changed, the memory they point to must have been allocated by the AllocMem callback function in the HTTP_FILTER_CONTEXT structure.


HTTP_FILTER_PREPROC_HEADERS

typedef struct _HTTP_FILTER_PREPROC_HEADERS

{

BOOL    (WINAPI * GetHeader) (

    struct _HTTP_FILTER_CONTEXT *    pfc,

    LPSTR    lpszName,

    LPVOID   lpvBuffer,

    LPDWORD  lpdwSize

    );

BOOL    (WINAPI * SetHeader) (

    struct _HTTP_FILTER_CONTEXT *    pfc,

    LPSTR    lpszName,

    LPSTR    lpszValue

    );

BOOL    (WINAPI * AddHeader) (

    struct _HTTP_FILTER_CONTEXT *    pfc,

    LPSTR    lpszName,

    LPSTR    lpszValue

    );

DWORD    dwReserved;

} HTTP_FILTER_PREPROC_HEADERS, *PHTTP_FILTER_PREPROC_HEADERS;

Members

BOOL (WINAPI * GetHeader) (
    struct _HTTP_FILTER_CONTEXT * pfc,
    LPSTR lpszName,
    LPVOID lpvBuffer,
    LPDWORD lpdwSizeofBuffer
   );

A pointer to a function that retrieves the specified header value. Header names should include the trailing colon (“:”). The special values “method”, “url”, and “version” can be used to retrieve the individual portions of the request line.

Parameters

pfc

The filter context for this request from the pfc passed to the HttpFilterProc.

lpszName

The name of the header to retrieve.

lpvBuffer

A pointer to a buffer of size lpdwSizeofBuffer where the value of the header will be stored.

lpdwSizeofBuffer

This should be set to the size of the buffer lpvBuffer, for example, sizeof(lpvBuffer). After the call, it contains the number of bytes retrieved including the null terminator. Therefore, for retrieved strings it is equal to strlen(lpvBuffer)+1.

BOOL (WINAPI * SetHeader) (
    struct _HTTP_FILTER_CONTEXT *pfc,
    LPSTR lpszName,
    LPSTR lpszValue
   );

A pointer to a function used to change or delete the value of a header.

Parameters

pfc

The filter context for this request from the pfc passed to the HttpFilterProc.

lpszName

A pointer to the name of the header to change or delete.

lpszValue

A pointer to the string to change the header to, or a pointer to “\0” to delete the header.

BOOL (WINAPI * AddHeader) (
    struct _HTTP_FILTER_CONTEXT *pfc,
    LPSTR lpszName,
   LPSTR lpszValue
   );

A pointer to a function to add a header.

Parameters

pfc

The filter context for this request from the pfc passed to the HttpFilterProc.

lpszName

A pointer to the name of the header to change or delete.

lpszValue

A pointer to the string to change the header to, or a pointer to “\0” to delete the header.

Remarks

When the server is about to process the client headers, this structure is pointed to by the pvNotification in the HttpFilterProc when notificationType is SF_NOTIFY_PREPROC_HEADERS.

See Also

HttpFilterProc


HTTP_FILTER_RAW_DATA

typedef struct _HTTP_FILTER_RAW_DATA

{

    PVOID pvInData;

    DWORD cbInData;

    DWORD cbInBuffer;

    DWORD dwReserved;

} HTTP_FILTER_RAW_DATA, *PHTTP_FILTER_RAW_DATA;

Members

pvInData

[in] A pointer to the data buffer (input or output).

cbInData

[in] The amount of data in the buffer pointed to by pvInData.

cbInBuffer

[in] The size of the buffer pointed to by pvInData.

dwReserved

[in] Reserved for future use.

Remarks

This structure is passed to the SF_NOTIFY_READ_RAW_DATA and SF_NOTIFY_SEND_RAW_DATA notification routines.

See Also

HttpFilterProc


HTTP_FILTER_URL_MAP

typedef struct _HTTP_FILTER_URL_MAP

{

    const CHAR *    pszURL;

    CHAR *          pszPhysicalPath;

    DWORD           cbPathBuff;

} HTTP_FILTER_URL_MAP, *PHTTP_FILTER_URL_MAP;

Members

pszURL

[in] A pointer to the URL that is being mapped to a physical path.

pszPhysicalPath

[in/out] A pointer to the buffer where the physical path is stored.

cbPathBuff

[in] The size of the buffer pointed to by pszPhysicalPath.

Remarks

When the server is about to map the specified URL to a physical path, this structure is pointed to by the pvNotification in the HttpFilterProc when notificationType is SF_NOTIFY_URL_MAP. Filters can modify the physical path in place.

See Also

HttpFilterProc


HTTP_FILTER_VERSION

typedef struct _HTTP_FILTER_VERSION

{

    DWORD     dwServerFilterVersion;

    DWORD     dwFilterVersion;

    CHAR      lpszFilterDesc[SF_MAX_FILTER_DESC_LEN+1];

    DWORD     dwFlags;

} HTTP_FILTER_VERSION, *PHTTP_FILTER_VERSION;

Members

dwServerFilterVersion

[in] The version of the document used by the server. The version of the current header file is HTTP_FILTER_REVISION.

dwFilterVersion

[out] The version of the document used by the server. The version of the current header file is HTTP_FILTER_REVISION.

lpszFilterDesc

[out] The location in which to store a short string description of the ISAPI filter application.

dwFlags

[out] The combination of SF_NOTIFY_* flags to specify which events this application is interested in. See HttpFilterProc for a list of valid flags.

Remarks

This structure is passed to the application's HttpFilterProc entry point by the server.

See Also

HttpFilterProc


Internet Service Manager

The following section describes the design of the Internet Service Manager (ISM) application and the Internet Service Manager API set (ISMAPI), which the ISM uses to communicate with the ISM Configuration DLLs.

The Internet Service Manager is designed to be a dynamic, extendable remote and local administration tool, which performs no configuration itself, but instead manages a set of configuration DLLs (also referred to as extension DLLs) to perform configuration tasks. A service is deemed to be “configurable” by the ISM if a configuration DLL has been loaded by it.


Program Structure

The Internet Service Manager package is divided into two parts—the main application and a set of DLLsone for each service. The main window of the ISM application is used to control the administration environment. The DLLs are set up for each service to perform configuration, discovery, and service status functions. In the first release of the application, we will provide three different DLLs to administer the Microsoft Internet Server services, namely FTP, WWW, and Gopher.


Internet Service Manager (ISM)

The main application is used to control the loading of each configuration DLL. When the application first starts, the ISM performs the following tasks:

1.	Reads the registry to load preference settings and discover which extension DLLs it needs to load.

2.	Loads and initializes each configuration DLL. The configuration DLL is queried on what type of service it is and what actions it supports.

3.	Discovers what configurable services are installed on the local machine and adds them to the default view.

4.	Awaits the user’s action. Optionally, the ISM may discover available configurable services on the network.


Configuration DLLs

Configuration DLLs (also referred to as extension DLLs) are the bridge between the ISM application and configurable services. A configuration DLL must be able to perform the following tasks for the ISM application:

1.	Return Service Information: Each successfully loaded service DLL tells the manager the name of the service it supports and the actions it supports. It also provides a bitmap to be shown in the toolbar and in the configuration views.

2.	Configuration: When the user double clicks the server item(s) or selects the Configure menu item in the main window, the main window issues a call to the related service DLL with the selected computer names. At this point, the configuration DLL takes over and presents the configuration dialogs and returns when configuration is completed. This is done modally.

3.	Start/Stop/Pause service: When the user selects the Start/Stop/Pause action in the menu bar, the main window calls the configuration DLL to issue a command to perform the proper action to the selected servers.

4.	Discovery: There are two types of available discovery supported by the ISM application. The first is INETSLOC discovery, which is supported by all the Internet Servers. If a configuration DLL manages a type of service that is discoverable in this way, it need not provide a discovery API, but only a INETSLOC mask. The ISM application then uses this for discovery. Those services not discoverable in this fashion must provide their own discovery API.


Internet Service Manager Application

The ISM application stores information about the discovered computer and the configurable services that are available on them. This information can be presented in several different ways, as shown in the Report View, the Servers View, and the Services View for the Internet Service Manager. In each of these views, specific services can be included or excluded in the view by selecting the service types buttons in the toolbar, or selecting them in the View menu. Only selected services will be shown in the view.


Report View

The Report view presents an alphabetically sorted list of computers and the services running on them. The list can be sorted by computer name, service name, state, or comment.


Servers View

The Servers view is a pivot of the services view. It is a tree view which has the computer names as top-level items, with the configurable services found on that server as child items.


Services View

The Services view presents the configurable services as the top-level item in a tree view, with each known server that runs the service enumerated underneath the service.


Service Features

These are the specific features that are available:

Connecting to a single server

When connecting to a single server, each service on the connected machine that can be administered is enumerated and added to the list.

Discovery

Discovery can be used to find all configurable services on the network.

Service Administration

When a configurable service (or services) is selected, the Configure menu item and toolbar button are enabled. Selecting Configure calls the configure API in the service DLL and passes control to it.

Changing Service State (Start/Stop/Pause)

When a controllable service (or services) is selected, the start, stop, and pause menu items and toolbar buttons are enabled in a manner consistent with the current state of the selected service. Selecting any of these menu commands calls upon the appropriate configuration DLL to start, stop, pause, or continue the appropriate service.


Extension DLLs

The Internet Service Manager is designed to support future extension. When a new Internet Server Service is created, the server service may be added to the administration tool using the following steps:

1.	The extension service should add itself to the registry key, \\LocalMachine\Software\InetMgr\AddOnServices, as described under Registry Layout.

2.	The extension service must provide a configuration DLL that contains the five DLL entry points. Optionally, a help file may be supplied, which should differ in name from the extension DLL only in that it should have the file extension .hlp.

Once the registry value entry has been added, the Internet Service Manager will automatically load and initialize the extension DLL when it starts up. It will then be able to administer the new extension service.


Internet Service Manager API (ISMAPI) Interface

The following sections contain the Definitions, Structures, and Functions for the ISMAPI interface.

Definitions

Functions

Structures


Definitions

enum

{

    //

    // the service has invoked de-registration or

    // the service has never called registration.

    //

    INetServiceStopped,

    //

    // the service is running.

    //

    INetServiceRunning,

    //

    //  the service is paused.

    //

    INetServicePaused,

};

#define INetServiceUnknown      INetServicePaused + 1

//

// Maximum length of some members in characters

//

#define MAX_SERVERNAME_LEN      256                // We allow hostnames

#define MAX_COMMENT_LEN         MAXCOMMENTSZ

//

// Dimensions of the toolbar bitmaps

//

#define TOOLBAR_BMP_CX          17

#define TOOLBAR_BMP_CY          17

The INetService* definitions are taken straight from INETSLOC, and are provided here only for services that do not support INETSLOC discovery.  TOOLBAR_BMP_CX and TOOLBAR_BMP_CY specify the ideal dimensions of the toolbar bitmap the configuration DLL provides.

//

// Service information flags

//

#define ISMI_INETSLOCDISCOVER   0x00000001  // Use INETSLOC for discovery

#define ISMI_CANCONTROLSERVICE  0x00000002  // Service state can be changed

#define ISMI_CANPAUSESERVICE    0x00000004  // Service is pausable.

#define ISMI_NORMALTBMAPPING    0x00000100  // Use normal toolbar color mapping

#define ISMI_VIRTUALHOSTS       0x00000200  // Service supports virtual hosts

#define ISMI_VIRTUALROOTS       0x00000400  // Service supports virtual roots

#define MAX_SNLEN               20          // Maximum short name length

#define MAX_LNLEN               48          // Maximum long name length

The service information bits are used in the ISMSERVICEINFO structure to specify supported features.


Functions

The following section contains the functions for the ISMAPI interface.

ISMChangeServiceState

ISMConfigureServers

ISMDiscoverServers

ISMQueryServerInfo

ISMQueryServiceInfo


ISMChangeServiceState

DWORD ISMChangeServiceState(
int nNewState,
int * pnCurrentState,
DWORD dwReserved,
LPCTSTR lpstrServers
);

Parameters:

nNewState

The requested state.

pnCurrentState

A pointer to the new state after the function call.

dwReserved

Reserved. Must be zero.

lpstrServers

A double null-terminated list of servers.

Return Values

The return value is a WIN32 error code. Additionally, the pnCurrentState value returns the current state of the service.

Remarks

This function is called to change the service state (running, stopped, paused) of the selected servers, provided service control is available. The nNewState parameter can be INetServiceStarted, INetServiceStopped, or INetServicePaused. The pnCurrentState parameter returns the current state of the service after the function returns, which may or may not be the same as the state requested. The dwReserved parameter is reserved for future use and must be zero. The lpstrServers parameter is a double null-terminated list of servers that the new state is to be applied to.


ISMConfigureServers

DWORD ISMConfigureServers(
HWND hWnd,
DWORD dwReserved,
LPCTSTR lpstrServers
);

Parameters

hWnd

Handle to main window.

dwReserved

Reserved. Must be zero.

lpstrServers

A double null-terminated list of servers.

Return Values

The return value is a WIN32 error code.

Remarks

The ISMConfigureServers function is called with a double null-terminated list of servers that are to be administered. It is the responsibility of the configuration DLL to provide the dialogs that the user uses to interact with the service, and it is also the responsibility of the configuration DLL to present multiple-server configuration to the user. The hWnd parameter is a window handle to the owning application (typically, the main frame window of the ISM application). The dwReserved parameter is reserved for future expansion and should be zero. The lpstrServers parameter is a double null-terminated list of server names.


ISMDiscoverServers

DWORD ISMDiscoverServers(
ISMSERVERINFO *psi,
DWORD *pdwBufferSize,
int *cServers
);

Parameters

psi

A pointer to a buffer of ISMSERVERINFO structures.

pdwBufferSize

A pointer to the size of the buffer.

cServers

A pointer to the number of the discovered server.

Return Values

The return value is a WIN32 error code.

Remarks

This function is used only for those configuration DLLs which are not configurable with INETSLOC. The calling program (for example, ISM) calls this function first with a buffer size of zero. It should then return the actual size required for the ISMSERVERINFO structures (for example, one structure per discovered service). The calling program then allocates sufficient storage for this and calls the function again with a pointer to this buffer. The function fills in this buffer with ISMSERVERINFO structures, one per discovered service, and returns the number of discovered servers in cServers.


ISMQueryServerInfo

DWORD ISMQueryServerInfo(
LPCTSTR lpstrServerName,
ISMSERVERINFO *psi
);

Parameters

lpstrServerName

A double null-terminated list of servers.

ps

A pointer to a ISMSERVERINFO structure.

Return Values

The return value is a WIN32 error code.

Remarks

This function is called to provide information about the service in respect to a specific server, which may or may not be running the service. The calling program calls this function to determine if the specified host is running the service and, if so, the function then fills in the ISMSERVERINFO structure with the computer name, the comment, and the current state of the service. If the service is not running on the specified computer, this is reflected in the error return code. As with all ISM API calls, it is the responsibility of the calling program to fill in the dwSize member of the ISMSERVERINFO structure prior to calling the function, and it is the responsibility of the configuration DLL to provide version control based on this size element.


ISMQueryServiceInfo

DWORD ISMQueryServiceInfo(
ISMSERVICEINFO * psi
);

Parameters

psi

A pointer to the SERVICEINFO structure.

Return Values

The return value is a WIN32 error code.

Remarks

This function fills in a ISMSERVICEINFO structure with information about the service and is called immediately after the configuration DLL has been successfully loaded. The calling program (ISM presumably) fills in the dwSize element of the ISMSERVICEINFO structure with the size of the structure. It is the responsibility of the configuration DLL to use this size for version control.


Structures

Important: Many of the following structures have a dwSize member. Functions that fill in these structures require that this member be filled in before the function is called.

ISMSERVERINFO

ISMSERVICEINFO


ISMSERVERINFO

//

// Standard Server information structure.

//

typedef struct tagISMSERVERINFO

{

    DWORD dwSize;                                  // Structure size

    TCHAR atchServerName[ MAX_SERVERNAME_LEN + 1]; // Server name

    TCHAR atchComment[ MAX_COMMENT_LEN + 1 ];      // Server Comment

    int   nState;                                  // Service State

} ISMSERVERINFO, *PISMSERVERINFO;

The ISMSERVERINFO structure returns information about a specific computer. The nState member can specify INetServiceStarted, INetServiceStopped, INetServicePaused, or INetServiceUnknown. This last value should be used by all services that do not support controllable services.


ISMSERVICEINFO

//

// Standard service configuration information structure

//

typedef struct tagISMSERVICEINFO

{

    DWORD dwSize;                     // Structure size

    DWORD dwVersion;                  // Version information

    DWORD flServiceInfoFlags;         // ISMI_ flags

    ULONGLONG ullDiscoveryMask;       // InetSloc mask (if necessary)

    COLORREF rgbButtonBkMask;         // Toolbar button bitmap background mask

    UINT nButtonBitmapID;             // Toolbar button bitmap resource ID

    COLORREF rgbServiceBkMask;        // Service bitmap background mask

    UINT nServiceBitmapID;            // Service bitmap resource ID

    TCHAR atchShortName[MAX_SNLEN+1]; // The name as it appears in the menu

    TCHAR atchLongName[MAX_LNLEN+1];  // The name as it appears in tool tips

} ISMSERVICEINFO, *PISMSERVICEINFO;

The ISMSERVICEINFO structure specifies information about the service, including its name and a description text, and bitmap identifiers and background masks for the toolbar button and service view bitmaps. These two bitmaps can be the same bitmap resource. The background masks refer to the color in the bitmap that is designated as the transparent color. The flServiceInfoFlags is made up of bits which specify the supported features. (See the ISMI_ flag definitions above). The ullDiscoveryMask is the mask used for INETSLOC discovery, if supported, and should be zero, if INETSLOC discovery is not supported.


Help Files

Each Internet Service Manager Extension DLL is expected to have its own help file. The name of the help file is generated by the Internet Service Manager at run time and is expected to have the same base name as the configuration DLL, with the file name extension .hlp. When the configuration function is called, this help file is set as the default help file by the ISM application. When the configuration function returns, the old help file name is restored.


Registry Layout

This section describes the registry layout that is used by the Internet Service Manager.

Local_Machine\Software\Microsoft\InetMgr\Parameters\

Various preference settings, such as the size of the ISM window and the current view, are stored here.

Local_Machine\Software\Microsoft\InetMgr\Parameters\AddOnServices

This entry consists of a series of REG_SZ entries, the name which specifies the name of the service, and value which specifies the configuration DLL name. For example, FTP has the following registry entry:

FTP: REG_SZ: fscfg.dll

Local_Machine\Software\Microsoft\InetMgr\Parameters\AddOnTools

This section specifies the add-on tools supported by the ISM application. An add-on tool is a free-standing application, which provides some additional functionality. Add-on tools are run synchronously and can be configured to receive information about the currently selected servers and their services through command line parameters.

A toolbar button is added for each add-on tool consisting of the small icon of the executable, and a menu item is added underneath the Tools menu as well. This registry entry consists of a series of REG_SZ entries, the name which specifies the menu item associated with it underneath the Tools menu (an accelerator may be used), and the value which has the following format:

application; tooltips text; selected parameters; nonselected parameters application:

Executable or batch file associated with the menu item/toolbar button. If this is an executable, its icon will be added to the toolbar.

tooltips text:

The text as it will appear in the tooltips, when the cursor is over the toolbar button.

selected parameters:

The command line parameters passed when an item is selected in the current view. There are three escape sequences that can be used here:

$C    Will be replaced with the selected computer name

$S    Will be replaced with the selected service name

$$    Will be replaced by a single $

nonselected parameters:

The command line parameters when no item is currently selected.

Any of these items, with the exception of application, are optional and can be omitted. For example: &Sample: REG_SZ: c:\sample.exe;Sample Application;/c $c /s $s;

Local_Machine\Software\Microsoft\InetMgr\Parameters\AddOnHelp

Similar to add-on tools, additional help topics can be added to the Help menu. This is a series of registry entries, the name which specifies the Help menu item (as with add-on tools, an accelerator can be used), and the value which specifies an executable or document name to be associated with the menu item.


Address Types

E-mail addresses in MAPI are defined by two properties. The address type, PR_ADDRTYPE, is a string property that names the messaging system the address is destined for. It is used by MAPI to assign responsibility for an e-mail address to the right transport provider. The e-mail address itself, PR_EMAIL_ADDRESS, is another string whose format varies depending upon PR_ADDRTYPE. It is not interpreted by MAPI, but by the transport provider and by the messaging system itself.

This appendix lists address types known to MAPI at this time and the corresponding e-mail address formats. Several of these address types, including SMTP, X400, and FAX are used by a large number of messaging systems. It is important that all MAPI components agree on the type name and address format for such common types, so they can interoperate smoothly. MAPI address book providers, MAPI transport providers, and gateways to messaging systems with MAPI-based clients should all take note of this specification.

To define a new address type, to make comments or suggestions about the information in this appendix, or to request more information, send e-mail to mapi@microsoft.com. The following table, and many of the address type specifications that follow, are work in progress.

Messaging system	Address type (PR_ADDRTYPE)	Owner or reference document
3Com® 3+Mail®	3COM	3Com (3+Open®)
AT&T Easylink Services	ATT	AT&T
cc:Mail™ (proposed)	CCMAIL	IBM
CompuServe (proposed)	COMPUSERVE	Compuserve
Microsoft Exchange Server	EX	Microsoft
Facsimile	FAX MSFAX
MCI MAIL	MCI	MCI Communications Corp.
Novell® Message Handling System	MHS	Novell
Microsoft Mail Server for PC Networks	MS	Microsoft
Microsoft Mail Server for Appletalk Networks	MSA	Starnine Technologies®
The Microsoft Network	MSN	Microsoft
Professional Office System	PROFS
Internet	SMTP	Internet Request for Comments (RFC) 822
SNA Distribution System	SNADS
Telex (proposed)	TELEX
X.400 Message Handling System	X400	CCITT X.400 series specifications
X.500 Directory Services	X500	CCITT X.500 series specifications


3+Mail (3COM)

This information is based on the Microsoft Mail Server for PC Networks gateway to 3+Mail. The custom recipient address is in the following format:

[3COM:UserName:Domain:Organization]

 − Or −

[3COM:UserName]

 − Or −

[3COM:UserAlias:Domain:Organization]


AT&T EasyLink (ATT)

This information is based on the Microsoft Mail for PC Networks gateway to AT&T Easylink. The custom recipient addresses are in the following formats:

AT&T Mail Address

[ATT:attmail!UserName]

attmail

The "gate name" for the AT&T Mail Network.

!

A delimiter.

UserName

A unique identifier for an individual user.

AT&T MailFAX

[ATT:fax!+FaxTelephoneNumber (/RecipientName) Option]

fax!

Indicates to the AT&T Mail Network that this message is being delivered to a fax machine.

+

Must be specified for AT&T Mail Network to insert the correct country access code.

FaxTelephoneNumber

The local fax telephone number, country code, area code and local exchange.

RecipientName

The recipient of the fax.

Options

Any AT&T Mail options.

An example of this address is:

[ATT:fax!+19085551234(/John Doe) delivery].

AT&T Telex

[ATT:telex!TelexNumber (/Attention)]

telex!

Indicates to the AT&T Mail Network that this is a message for a telex machine.

TelexNumber

The number of the telex machine to which the message is being delivered.

Attention

The name of the recipient of the message.

An example of this address is:

[ATT:telex!900123(Jones MFG CO/John Doe)].

AT&T MailPRINT

[ATT:printer!PrinterTelephoneNumber (/RecipientName) Options]

printer!

Indicates to the AT&T Mail Network that this message is being delivered to a printer.

PrinterTelephoneNumber

The local printer telephone number, country code, area code, and local exchange.

RecipientName

The recipient of the message.

Options

Any AT&T Mail option.

An example of this address type is:

[ATT:printer!19085551234 (/John Doe)].

AT&T Paper

[ATT:Address]

Address

The postal address is entered on one line with semicolons (;) used to separate the address parts. If the address contains a semicolon, surround it with quotation marks (";").

An example of this address type is:

[ATT:John Doe;123 Main Street; N.Y. 01234].


Facsimile (FAX, MSFAX)

Support is required for custom recipient addresses in the following format:

[FAX:Dialable | Name @ Canonical | SpecialDialing]

Dialable

A dialable fax phone number that consists of any of the following characters: 0-9, ( ), -, space. Examples are 64545 and 9, 1-206-8828080.

Name

Optional field used for inbound routing by Microsoft At Work Fax. MAPI providers that do not support Microsoft At Work Fax should simply ignore this field. The name field is interpreted by the receiving machine and can contain any information which helps route the fax to its intended recipient. For example, this field might be a recipient’s e-mail name. This field can include the at sign character (@).

Canonical

Must be a canonical fax phone number. If a canonical fax phone number is included in the address, and the provider can process canonical numbers, the provider should always use the canonical number instead of the dialable phone number.

|

Separator character, ASCII Hex 0x7C. The separator between the subscriber number and special dialing instructions (such as a postfix or TIA/EIA/IS-141 subaddress) is optional. If the phone number is in canonical form and a separator is not present, then the special dialing instructions are assumed to begin with the first character in the local number which is not one of the following: the numerals 0-9, hyphen (-), space.

SpecialDialing

Must be a postfix, TIA/EIA/IS-141 subaddress or ISDN subaddress. MAPI 1.0 providers can optionally support these special dialing extensions.

Examples of this address type are:

[FAX:936-7329]

[FAX:1-206-9367329]

[FAX:936-7329 | +1 (206) 936-7329]

[FAX:936-7329 | tedst@ +1 (206) 936-7329]

[FAX:936-7329 | tedst@+1 (206) 936-7329]

[FAX:936-7329 | +1 (206) 9367329|#546]

[FAX:936-7329 | +1 (206) 9364344|,,,,,567]

Note  Some service providers create ‘MSFAX’ formatted addresses but with the ‘FAX’ address type. Providers can either handle these addresses, or not accept responsibility for them as they see fit; either method is acceptable.

Support is optional (but recommended) for custom recipient addresses in the following format:

[MSFAX:Name@ PhoneNumber | SpecialDialing]

Name

Optional field used for inbound routing by Microsoft At Work Fax. MAPI providers that do not support Microsoft At Work Fax should simply ignore this field. The name field is interpreted by the receiving machine and can contain any information which helps route the fax to its intended recipient. For example, this field might be a recipient’s e-mail name. This field can include the at sign character (@).

PhoneNumber

Must be a canonical phone number or dialable phone number.

|

Separator character, ASCII Hex 7c. This is the separator between the subscriber number and special dialing instructions (such as a postfix or TIA/EIA/IS-141 subaddress). This separator is optional. If the phone number is in canonical form and a separator is not present, then the special dialing instructions are assumed to begin with the first character in the local number which is not one of the following: the numerals 0-9, hyphen (-), period (.), and space.

DialablePhoneNumber

A dialable address is a phone number that consists of any of the following characters: the numerals 0-9, letters A-D, asterisk (*), pound (#), comma (,), exclamation mark (!), uppercase and lowercase w (W, w), uppercase and lowercase p (P, p), uppercase and lowercase t (T, t), at sign (@), dollar sign ($), question mark (?), hyphen (-), period (.), and space. For example 64545. Dialable addresses are intended to be used to represent internal phone extensions.

SpecialDialing

Must be a postfix, TIA/EIA/IS-141 subaddress or ISDN subaddress. MAPI 1.0 providers can optionally support these special dialing extensions.

Examples of this address type are:

[MSFAX: 936-7329]

[MSFAX: +1 (206) 936-7329]

[MSFAX: tedst@+1 (206) 936-7329]

[MSFAX: +1 (206) 9367329|#546]

[MSFAX: +1 (206) 9364344|,,,,,567]

The following table includes descriptions of the components of this address:

Component	Description
canonical phone number	A phone number in the form: +CountryCode space (AreaCode) space LocalNumber. Examples are +1 (206) 936-4479 and +43 443444. CountryCode and AreaCode can only contain the numerals 0 through 9. If the area code is present it must be preceded by exactly one ASCII left parenthesis character (0x28), and be followed by exactly one ASCII right parenthesis character (0x29) and one ASCII space character (0x20). The local number must contain one or more of the numerals 0 through 9 but must not include any of the following characters: AaBbCcDdPpTtWw*#!,@$?;()|^ CRLF
special dialing	Must be a postfix, TIA/EIA/IS-141 subaddress or ISDN subaddress. MAPI 1.0 providers can optionally support these special dialing extensions.
postfix	A string of dialing control characters and digits used to complete calls which require DTMF routing, manual dialing, or pauses in the dialing sequence. The string must begin with one of the following characters: $ , ? W w @ and can contain any of the following characters: 0-9 A-D * # , ! W w P p T t @ $ ?. An example is +1 (206) 9367329|,,,,,567. This waits for several seconds after the main number is dialed before entering the DTMF tones 567.
TIA/EIA/IS-141 subaddress	Used for inbound routing according to the U.S. standard TIA/EIA/IS-141. MAPI 1.0 providers that cannot transmit this subaddress information should remove this field before dialing. This field must begin with the number sign (#). In typical use, this value uniquely identifies a recipient. An example is +1 (206) 9367329|#543. This example enables inbound routing to employee 543
ISDN Subaddress	For faxing over ISDN. MAPI 1.0 providers that cannot transmit ISDN subaddresses should remove this field before dialing. An ISDN subaddress can begin with any character except the following: # $ , ? W w @
$	Wait for “billing signal”, such as a credit card prompt tone.
,	Indicates that dialing is to be paused. The duration of a pause is device specific.
?	Indicates that the user is to be prompted before continuing with dialing.
W w	Dialing should proceed only after a dialing tone has been detected.
@	Indicates that dialing is to “wait for quiet answer” before dialing the remainder of the number. This means to wait for at least one ringback tone followed by several seconds of silence.
P p	Indicates that pulse dialing is to be used for the digits following it.
T t	Indicates that tone (DTMF) dialing is to be used for the digits following it.
Note  Microsoft supports two FAX address formats. FAX is intended to be used for compatibility with downlevel systems — including the Microsoft Mail for PC Networks FAX gateway. Although it is optional, all transport writers are encouraged to support and use the MSFAX standard. The ‘FAX’ standard will likely be eliminated in favor of the ‘MSFAX’ standard in a future release.

For more information on dialable and canonical addresses, see the Win32 Telephony (TAPI) documentation.


MCI MAIL (MCI)

This information is based on the Microsoft Mail for PC Networks gateway to MCI MAIL. It may be incomplete or out of date in certain respects. The custom recipient address is in the following format:

[MCI:UserName\r EMS:EMSName\r MBX:MCIMailbox]

MCI

MCI MAIL address indicator.

UserName

Name of mail recipient. Not used for mail delivery.

EMS

Indicates the name or number in the next field is the recipient's REMS (remote e-mail system) account.

EMSName

The actual EMS name or number. This can also be an MCI service provided by MCI; consult MCI Help for more information.

MBX

Indicates this is additional information required by the remote system.

MCIMailbox

Actual MBX (address) for the recipient on the remote system. If the remote system is Microsoft Mail, MCIMailbox is the full Microsoft Mail address. You can only have one complete MBX address.

There is always a space in front of the EMS: token and another space in front of each MBX: token. These spaces are required. The carriage-return symbol at the end of the line is in addition to whatever code your text editor inserts.

The actual message text requires a header separator after the TEXT: token. That is, the first line after TEXT: should be a line of 78 dash (-) characters to separate the header from the message text. Include these 78 characters in the TEXT count.

An example of this address type is:

[MCI:John Doe\r EMS:MCI Mail\r MBX:123-4567\r]

The following are other MCI addresses:

MCI MAIL

Example:

[MCI:John Doe at MCI\r EMS:MCI Mail\r MBX:123-4567]

MCI Paper

Example:

[MCI:John Doe\r EMS:MCI Mail\r MBX:Company:ABC, Inc.\r
MBX:Country:Canada\r MBX:Line1:100 - 123 Main Street\r
MBX:Line2:\r MBX:City:Vancouver\r MBX:State:B.C.\r
MBX:Code:V6B 1A1]

EMS

This address type is for Microsoft Mail recipients.

Example:

[MCI:John Doe\r EMS:ems_name\r
MBX:network/postoffice/JohnDoe\r
MBX:\r MBX:\r MBX:\r MBX:\r MBX:]

REMS

This address type is for non-Microsoft Mail recipients.

Example:

[MCI:John Doe\r EMS:Internet\r MBX:JohnDoe@aaa.bbb.bc.ca\r
MBX:\r MBX:\r MBX:\r MBX:\r MBX:]

TELEX

Example:

[MCI:John Doe\r EMS:MCI Mail\r MBX:Country:-\r
MBX:Telex:6501234567\r MBX:Answerback:6507654321]

Fax

Example:

[MCI:John Doe\r EMS:MCI Mail\r MBX:FAXNo:604-123-4567\r
MBX:Retry:4.0\r MBX:Company:ABC Company Inc.\r
MBX:SFax:604-111-1111\r MBX:SPhone:604-222-2222]


Novell Message Handling System (MHS)

This information is based on the Microsoft Mail for PC Networks gateway to MHS and the SMF 71 specification. It may be incomplete or out of date in certain respects. The custom recipient address is in the following format:

[MHS:User@Host] for a MHS user on MHS host.

Host

The name of the MHS host.

 − Or −

[MHS:Mailbox@Gateway] for a MSMail user on a MHS gateway

Mailbox

8 ASCII characters

Gateway

The name of the MHS gateway, not MHS host.

 − Or −

[MHS:User@Gateway {Network/Postoffice/Mailbox}] for a MSMail user on MHS gateway/downstream postoffice.

User

A place holder.

Network/Postoffice/Mailbox

MSMail for PC Networks address.

 − Or −

[MHS:User@Gateway LocalAddress] for non-MSMail user on MHS gateway (general case).

LocalAddress

The user's native address. For example, MSMail, X.400.


Microsoft Mail for PC Networks (MS)

The custom recipient address is in the following format:

[MS:Network/PostOffice/UserID]

Network

A 10 char (max) name of a MICROSOFT Mail Network.

PostOffice

A 10 character (max) Postoffice name.

UserID

A 10 chararacter (max) name of a PC Mail user.

/

A delimiter.

This address type is also used at times by Microsoft Exchange Server.


Microsoft Mail for Appletalk Networks (MSA)

The custom recipient address is in the following format:

[MSA:UserID@MS Mail Server]

UserID

Name of Microsoft Mail for AppleTalk user.

MS Mail Server

Name of Microsoft Mail for AppleTalk server.


The Microsoft Network (MSN)

The custom recipient address is in the following format:

[MSN:UserID]

UserID

The name of the MSN member. For example, [MSN:patsmith].

MSN allows the sender to change the recipient’s display name by using the following addressing style: Pat Smith[MSN:PatSm]. This will resolve on the client to a friendly name of 'Pat Smith' and an address alias of PatSm. The recipient will see the friendly name when they read the message.


Professional Office System (PROFS)

This information is based on the Microsoft Mail for PC Networks gateway to PROFS. The GATEWAY field is part of the gateway architecture, not the PROFS address. The custom recipient address is in the following format:

[PROFS:Gateway/Node/UserID]

Gateway

The gateway name. Limited to 10 characters.

Node

VM node name. Limited to 8 characters.

UserID

VM user ID. Limited to 8 characters.


Internet (SMTP)

The format of Internet e-mail addresses is defined in RFC 822. MAPI components should handle any address that complies with that standard. However, there is a particular form of RFC 822 address that best encodes MAPI addresses:

display name <e-mail address>

The angle brackets are included as literals. Blanks are common in display names; they need not be quoted. A typical address might look like this one, which belongs to one of the coauthors of RFC 1521:

Nathaniel Borenstein <nsb@bellcore.com>

If the display name contains characters that have special meaning in SMTP addresses, such as < or @, the entire display name should be quoted using double quotes. On outbound mail, if the total length of the e-mail address plus display name exceeds 255 characters, the display name should be dropped.


SNA Distribution System (SNADS)

This information is based on the Microsoft Mail for PC Networks gateway to SNADS. The GATEWAY field is part of the gateway architecture, not the SNADS address. The custom recipient address is in the following format:

[SNADS:Gateway/DistributionGroupName/DistributionElementName]

Gateway

Gateway name. Limited to 10 characters.

DistributionGroupName

Distribution Group Name. Limited to 8 characters.

DistributionElementName

Distribution Element Name. Limited to 8 characters.


Telex (TELEX) - Proposed

This address type definition is only a proposal. Comments and suggestions are welcome. The custom recipient address is in the following format:

[TELEX:Recipient@TelexNumber]

At least a telex number is required. For example [TELEX:foobar @ 1-2066354657].


X.400 Message Handling System (X400)

This information is based on the Microsoft Mail for PC Networks gateway to X.400 mail systems. Certain fields, particularly “DDA,” and the length limitations may not apply in all X.400-based messaging systems. The custom recipient address is in the following format:

[X400:g=GivenName;s=Surname;o=Organization;ou=OrganizationalUnit; p=PRMD;a=ADMD;c=Country;]

Label	Description	Maximum Length
G=	Given name	16
I=	Initials	5
S=	Surname (required if G, I or Q are used)	40
Q=	Generation Qualifier	3
CN=	Common name	64
X.121=	X.121 address	15
N-ID=	User agent numeric identifier	32
T-TY=	Terminal type	3
T-ID=	Terminal identifier	24
O=	Organization	64
OU1=	Organizational unit #1	32
OU2=	Organizational unit #2	32
OU3=	Organizational unit #3	32
OU4=	Organizational unit #4	32
P=	Private Management Domain (PRMD)	16
A=	Administrative Management Domain (ADMD - required)	16
C=	Country (required)	2 or 3
DDA=	Domain Defined Attribute (format => dda:<type>=<value>;)	8, 128


X.500 Directory Service (X500)

This address type is based on CCITT Recommendations X.500 and the associated APIA - X/OPEN API specifications and the proposed annex to F.401, Annex F. The custom recipient address is in the following format:

[X500:/C=CountryCode/O=Organization/OU=OrganizationUnit/CN=CommonName]

The following field length limits apply:

Field	Length limit
CountryCode	2 characters
Organization	Up to 64 characters
OrganizationUnit	Up to 32 characters
CommonName
The following guidelines apply:

•	Labels can be uppercase or lowercase.

•	Delimiters are slash marks (/) and must be specified before the first value as well as between values.

•	Delimiters can be followed by a space.

An example of this address is:

[X500:/ c=US/ o=Microsoft/ ou=WGA/ cn=TedSt]


MAPI Versions of 32-Bit Windows Functions

This appendix documents functions from the Win32 application programming interface (API) useful in the 16-bit environment used by MAPI client and server developers. Most of the functions documented in this appendix have counterparts published in the Win32 SDK, and some have limitations relative to their Win32 SDK counterparts. Such limitations are noted for each function. Where possible, if the calling implementation requests unsupported functionality, the function returns a value that indicates failure.

Some of the 32-bit Windows functions documented here have been implemented specifically for MAPI. The MAPIWIN.H header file includes definitions to aid in developing single-source service providers that run on both Win32 and Win16 API platforms.

MAPI works only with filenames, and other strings passed to it, in the ANSI character set. Applications that use filenames in the OEM character set must convert them to ANSI before calling MAPI.


Accessing Win32 Information in the MAPIWIN.H Header File

MAPIWIN.H has three sections. The first section defines how to call an available function by different methods in Win16. Functions included in the first section manage per-instance global variables for dynamic-link libraries (DLLs). They work on the assumption that all of a DLL’s per-instance global variables exist in a single block of memory.

The second section specifically defines for the Win16 environment functionality that is generally available in the Win32 environment. This section consists largely of Win32 file input-output functions that are not supported under Win16 but are implemented in MAPI.DLL using MS-DOS calls. Some functions of this type have limitations relative to their Win32 counterparts; the limitations are spelled out in this Appendix. The third section defines conventions that simplify certain common operations.

The following functions have no meaning on Win16, but Microsoft’s MAPI implementation defines macros to make it easier to write common code:

CloseMutexHandle

CreateMutex

DeleteCriticalSection

EnterCriticalSection

InitializeCriticalSection

LeaveCriticalSection

ReleaseMutex

WaitforSingleObject


Syntax and Limitations for Win32 Functions Useful in MAPI Development

The remainder of this appendix lists Win32 functions useful to MAPI developers that have limits, adaptations, or differences when used in the MAPI development environment. Where applicable, these limitations are described. Where there are no limitations specifically defined, only the syntax of a function is included. For detailed descriptions of the Win32 functions, see the Win32 Programmer’s Reference.

Three limitations apply to most of the Win32 functions that MAPI implements. Error codes returned from these functions or from GetLastError come from MS-DOS and may not always match the Win32 counterpart. Second, MAPI works only with filenames, and other strings passed to it, in the ANSI character set. Applications that use filenames in the OEM character set must convert them to ANSI before calling MAPI. And third, security attributes are ignored.


CloseHandle

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL CloseHandle(

HANDLE hObject
)
Limitations

This function will close only file handles.


CompareFileTime

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

LONG CompareFileTime(

CONST FILETIME * lpft1,
CONST FILETIME * lpft2
)


CompareStringA

int CompareStringA(

LCID Locale,
DWORD dwCmpFlags,
LPCSTR lpString1,
int cchCount1,
LPCSTR lpString2,
int cchCount2
)


CompareStringW

int CompareStringW(

LCID lcid,
DWORD fdwStyle,
LPCWSTR lpString1,
int cch1,
LPCWSTR lpString2,
int cch2
)
Limitations

Only accurate for character values less than 128. Characters whose values are greater may not be compared accurately because the 16-bit implementation does not have the necessary Unicode mapping tables.


CopyFile

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL CopyFile(

LPCTSTR lpszExistingFile,
LPCTSTR lpszNewFile,
BOOL fFailIfExists
)


CopyMemory

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

VOID CopyMemory (

PVOID Destination,
CONST VOID * Source,
DWORD Length
)


CreateDirectory

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL CreateDirectory(

LPCTSTR lpszPath,
LPSECURITY_ATTRIBUTES lpsa
)
Limitations:

LPSECURITY_ATTRIBUTES is not supported; fails if non-null.


CreateFile

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

HANDLE CreateFile(

LPCTSTR lpszName,
DWORD fdwAccess,
DWORD fdwShareMode,
LPSECURITY_ATTRIBUTES lpsa,
DWORD fdwCreate,
DWORD fdwAttrsAndFlags,
HANDLE hTemplateFile
)
Limitations

Several differences from ordinary Win32 usage occur when using the MAPI version of the CreateFile function:

•	dwFlagsAndAttributes and dwDesiredAccess are ignored.

•	lpSecurityAttributes is not supported and the function fails if it is not NULL.

•	hTemplateFile is not supported and the function fails if it is nonzero.


DeleteFile

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL DeleteFile(

LPCTSTR lpszFileName
)


DosDateTimeToFileTime

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL DosDateTimeToFileTime(

WORD wDOSDate,
WORD wDOSTime,
LPFILETIME lpft
)


FBadReadPtr

BOOL FBadReadPtr(

CONST VOID * lpvPtr,
UINT cbBytes
)
Limitations

The FBadReadPtr function behaves as does the IsBadReadPtr function but returns FALSE if the cbBytes parameter is zero regardless of the value of the lpvPtr parameter. This matches the behavior of Win32 IsBadReadPtr, rather than Win16 IsBadReadPtr.


FileTimeToLocalFileTime

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL FileTimeToLocalFileTime(

CONST FILETIME * lpft,
LPFILETIME lpftLocal
)
Limitations

Depends on time zone information in WIN.INI. The UI is included in the mail and fax control panel applet, and is set by the SetTimeZoneInformation call listed in this Appendix.


FileTimeToDosDateTime

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL FileTimeToDosDateTime(

CONST FILETIME * lpft,
LPWORD lpwDOSDate,
LPWORD lpwDOSTime
)


FileTimeToSystemTime

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL FileTimeToSystemTime(

CONST FILETIME * lpft,
LPSYSTEMTIME lpst
)


FillMemory

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

VOID FillMemory (

PVOID Destination,
DWORD Length,
BYTE Fill
)


FindClose

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL FindClose(

HANDLE hFindFile
)


FindFirstFile

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

HANDLE FindFirstFile(

LPCTSTR lpFileName,
LPWIN32_FIND_DATA lpFindFileData
)
Limitations

The dwReserved0, dwReserved1 and cAlternateFileName members are not supported in the WIN32_FIND_DATA structure.


FindNextFile

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL FindNextFile(

HANDLE hFindFile,
LPWIN32_FIND_DATA lpFindFileData
)
Limitations

The dwReserved0, dwReserved1 and cAlternateFileName members are not supported in the WIN32_FIND_DATA structure.


GetACP

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

UINT GetACP(VOID)


GetCurrentProcessID

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

DWORD GetCurrentProcessId(VOID)

Limitations

Returns HTASK. Value is subject to reuse by the operating system.


GetFileAttributes

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

DWORD GetFileAttributes(

LPCTSTR lpFileName
)
Limitations

This function won’t work on Novell NetWare without FILESCAN rights.


GetFileSize

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

DWORD GetFileSize(

HANDLE hFile,
LPDWORD lpdwFileSizeHigh
)


GetFileTime

BOOL GetFileTime(

HANDLE hFile,
LPFILETIME lpftCreation,
LPFILETIME lpftLastAccess,
LPFILETIME lpftLastWrite
)
Limitations

The time that the file in question was last modified is supported, but not the file creation or access time. The function fails if either of the latter is requested.


GetFullPathName

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

DWORD GetFullPathName(

LPCTSTR lpszFile,
DWORD cchPath,
LPTSTR lpszPath,
LPTSTR * lpszFilePart
)
Limitations

This function does not handle “..” path components in lpFileName.


GetLastError

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

DWORD GetLastError(VOID)

Limitations

This function won’t be as reliable as it is on Windows NT. If a function in this module fails because an unsupported feature was requested, no error is returned.


GetLocalTime

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

VOID GetLocalTime(

LPSYSTEMTIME lpst
)
Limitations

This function returns the current time as local time.


GetSystemTime

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

VOID GetSystemTime(

LPSYSTEMTIME lpst
)
Limitations

This function depends on the time zone and returns the current time as Greenwich mean time (GMT). Requires that an earlier call to SetTimeZoneInformation has been made to get the local time zone.


GetTempFileName

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

UINT GetTempFileName(

LPCTSTR lpszPath,
LPCTSTR lpszPrefix,
UINT uUnique,
LPTSTR lpszTempFile
)


GetTempFileName32

UINT WINAPI GetTempFileName32 (

LPCSTR lpPathName,
LPCSTR lpPrefixString,
UINT uUnique,
LPSTR lpTempFileName
)


GetTempPath

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

DWORD GetTempPath(

DWORD cchBuffer,
LPTSTR lpszTempPath
)


GetTimeZoneInformation

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

DWORD GetTimeZoneInformation(

LPTIME_ZONE_INFORMATION lptzi
)


GetUserDefaultLCID

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

LCID GetUserDefaultLCID(VOID)


InterlockedDecrement

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

LONG InterlockedDecrement(

LPLONG lplVal
)
Limitations

This function relies on cooperative multitasking.


InterlockedIncrement

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

LONG InterlockedIncrement(

LPLONG lplVal
)
Limitations

This function relies on cooperative multitasking.


IsBadBoundedStringPtr

BOOL WINAPI IsBadBoundedStringPtr(

const void FAR* lpsz,
UINT cchMax
)


IsBadReadPtr

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL IsBadReadPtr(

CONST VOID * lpvPtr,
UINT cbBytes
)
Limitations

This function has been redefined to work as on the Win32 version of FBadReadPtr.


IsBadStringPtrW

BOOL IsBadStringPtrW(

LPCWSTR lpszStr,
UINT cchMax
)


LocalFileTimeToFileTime

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL LocalFileTimeToFileTime(

CONST FILETIME * lpftLocal,
LPFILETIME lpft
)
Limitations

Requires that an earlier call to SetTimeZoneInformation has been made to get the local time zone.


lstrlenW

int lstrlenW(

LPCWSTR lpszString
)


lstrcmpW

int lstrcmpW(

LPCWSTR lpszString1,
LPCWSTR lpszString2
)


lstrcpyW

LPWSTR lstrcpyW(

LPWSTR lpszString1,
LPCWSTR lpszString2
)


MoveFile

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL MoveFile(

LPCTSTR lpszExisting,
LPCTSTR lpszNew
)
Limitations

The MAPI version of the MoveFile function won’t move a directory. This function always works across drives, and it always performs a copy operation then deletes the original file, as opposed to truly performing a move operation.


MoveMemory

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

VOID MoveMemory (

PVOID Destination,
CONST VOID * Source,
DWORD Length
)


MulDiv32

int MulDiv(

int nMultiplicand,
int nMultiplier,
int nDivisor
)
Limitations

The MulDiv32 function supports the MULDIV macro contained in the MAPIWIN.H header file. It takes 32-bit arguments, unlike the native Win16 MulDiv. The MAPI MulDiv32 does not check for overflow on the nMultiplier parameter.


MultiByteToWideChar

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

int MultiByteToWideChar(

UINT CodePage,
DWORD dwFlags,
LPCSTR lpMultiByteStr,
int cchMultiByte,
LPWSTR lpWideCharStr,
int cchWideChar
)
Limitations

This function is only accurate for character values less than 128. Characters whose values are greater may not be compared accurately because the 16-bit implementation does not have the necessary Unicode mapping tables; it does not support Unicode single-byte conversion; works reliably only for ASCII characters.


ReadFile

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL ReadFile(

HANDLE hFile,
LPVOID lpBuffer,
DWORD NumberOfBytesToRead,
LPDWORD lpNumberOfBytesRead,
LPOVERLAPPED lpOverlapped
)
Limitations

The count is limited to 64K. The lpOverlapped parameter is not supported and the function fails if lpOverlapped is not NULL.


RemoveDirectory

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL RemoveDirectory(

LPCTSTR lpszDir
)


SetEndOfFile

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL SetEndOfFile(

HANDLE hFile
)


SetFilePointer

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

DWORD SetFilePointer(

HANDLE hFile,
LONG lDistanceToMove,
PLONG lpDistanceToMoveHigh,
DWORD dwMoveMethod
)
Limitations

Distance is limited to 2 gigabytes (signed 32-bits). The SetFilePointer function fails if the lpDistanceToMoveHigh parameter is present and nonzero, unless the value it holds is the sign extension of a negative distance.


SetTimeZoneInformation

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL SetTimeZoneInformation(

CONST TIME_ZONE_INFORMATION * lptzi
)
Limitations

Depends on time zone information in WIN.INI. The UI is included in the mail and fax control panel applet.


Sleep

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

VOID Sleep(

DWORD cMilliseconds
)
Limitations

This function does not handle the ALT+TAB and ALT+ESC key combinations for task switching.


SystemTimeToFileTime

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL SystemTimeToFileTime(

CONST SYSTEMTIME * lpst,
LPFILETIME lpft
)


WideCharToMultiByte

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

int WideCharToMultiByte(

UINT CodePage,
DWORD dwFlags,
LPCWSTR lpWideCharStr,
int cchWideChar,
LPSTR lpMultiByteStr,
int cchMultiByte,
LPCSTR lpDefaultChar,
LPBOOL lpUsedDefaultChar
)
Limitations

This function is only accurate for character values less than 128. Characters whose values are greater may not be compared accurately because the 16-bit implementation does not have the necessary Unicode mapping tables; it does not support Unicode single-byte conversion; works reliably only for ASCII characters.


WriteFile

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

BOOL WriteFile(

HANDLE hFile,
PCVOID lpBuffer,
DWORD nNumberOfBytesToWrite,
PDWORD lpNumberOfBytesWritten,
POVERLAPPED lpOverlapped
)
Limitations

The lpOverlapped parameter is not supported, and the function fails if it is not NULL.


ZeroMemory

This function entry is part of a MAPI-specific list of Win32 functions. For a complete description, see Win32 Functions.

VOID ZeroMemory (

PVOID Destination,
DWORD Length
)


Property Identifiers and Types

All MAPI properties are represented by property tags. A property tag is a 32-bit unsigned integer value that contains the property’s identifier in the high order 16 bits and the property’s type in the low order 16 bits. Property tags for all of the properties defined by MAPI are included in the MAPITAGS.H header file.

Property identifiers are used to indicate what a property is used for and who is responsible for it. Property identifiers are divided by MAPI into ranges; where an identifier falls in the range indicates its use and ownership.

Property types are used to indicate the format of the property’s data. MAPI defines all of the valid types. Clients and service providers creating new properties must use one of these types. All of the property types are included in the MAPIDEFS.H header file.


List of Property Identifier Ranges

The following table summarizes the different ranges for property identifiers, describing the owner for the properties in each range.

Identifier range	Description
0000	Reserved by MAPI for the special value PR_NULL.
0001 - 0BFF	Message envelope properties defined by MAPI.
0C00 - 0DFF	Recipient properties defined by MAPI.
0E00 - 0FFF	Non-transmittable message properties defined by MAPI.
1000 - 2FFF	Message content properties defined by MAPI.
3000 - 3FFF	Properties for objects other than messages and recipients defined by MAPI.
4000 - 57FF	Message envelope properties defined by transport providers.
5800 - 5FFF	Recipient properties defined by transport and address book providers.
6000 - 65FF	Non-transmittable message properties defined by clients.
6600 - 67FF	Non-transmittable properties defined by a service provider. These properties can be visible or invisible to users.
6800 - 7BFF	Message content properties for custom message classes defined by creators of those classes.
7C00 - 7FFF	Non-transmittable properties for custom message classes defined by creators of those classes.
8000 - FFFE	Properties defined by clients and occasionally service providers that are identified by name through the IMAPIProp::GetNamesFromIDs and IMAPIProp::GetIDsFromNames methods.
FFFF	Reserved by MAPI for the special error value PROP_ID_INVALID.
The range between 3000 and 3FFF is reserved for properties that are not related to either messages or recipients. MAPI divides this range into sub-ranges by types of object; the following table shows this further breakdown.

Identifier range	Type of property
3000 - 33FF	Common properties that appear on multiple objects, such as PR_DISPLAY_NAME and PR_ENTRYID.
3400 - 35FF	Message store properties
3600 - 36FF	Folder and address book container properties
3700 - 38FF	Attachment properties
3900 - 39FF	Address book properties
3A00 - 3BFF	Messaging user properties
3C00 - 3CFF	Distribution list properties
3D00 - 3DFF	Profile properties
3E00 - 3FFF	Status object properties


List of Property Types

MAPI supports both single-valued and multivalued properties. With a single-valued property, there is one value of the base type for the property. With a multivalued property, there are multiple values of the base type.

The single-valued and multivalued property types that are supported by MAPI are described as follows. For each single-valued type that has a corresponding multivalued type, the multivalued type appears in parentheses after the single-valued type.

PT_APPTIME	 (PT_MV_APPTIME)

Double value that is interpreted as date and time. This property type is the same as the OLE type VT_DATE and is compatible with the Visual Basic time representation.

PT_BINARY (PT_MV_BINARY)

SBinary structure value, a counted byte array.

PT_BOOLEAN (PT_MV_12)

16-bit Boolean value where zero equals FALSE and non-zero equals TRUE. This property type is the same as the OLE type VT_BOOL.

PT_CLSID (PT_MV_CLSID)

CLSID structure value. This property type is the same as the OLE type VT_CLSID.

PT_CURRENCY (PT_MV_CURRENCY )

64-bit integer intepreted as decimal. This property type is compatible with the Visual Basic CURRENCY type and is the same as the OLE type VT_CY.

PT_DOUBLE (PT_MV_DOUBLE)

Double value; 64-bit floating point value. This property type is the same as PT_R8 and the OLE type VT_R8.

PT_ERROR

SCODE value; 32-bit unsigned integer. This property type is the same as the OLE type VT_ERROR.

PT_FLOAT (PT_MV_FLOAT)

32-bit floating point value. This property type is the same as PT_R4 and the OLE type VT_R4.

PT_I2 (PT_MV_I2)

Signed 16-bit integer. This property type is the same as PT_SHORT and the OLE type VT_I2.

PT_I4 (PT_MV_I4)

Signed or unsigned 32-bit integer. This property type is the same as PT_LONG and the OLE type VT_I4.

PT_I8 (PT_MV_I8)

Signed or unsigned 64-bit integer that uses the LARGE_INTEGER structure. This property type is the same as the OLE type VT_I8.

PT_LONG (PT_MV_LONG)

Signed or unsigned 32-bit integer. This property type is the same as PT_I4 and the OLE type VT_I4.

PT_LONGLONG (PT_MV_LONGLONG)

Signed or unsigned 64-bit integer. This property type is the same as PT_I8 and the OLE type VT_I8.

PT_NULL

Indicates no property value. This property type is reserved for use with interface methods and is the same as the OLE type VT_NULL.

PT_OBJECT

Pointer to an object that implements the IUnknown interface. This property type is similar to several OLE types such as VT_UNKNOWN.

PT_R4 (PT_MV_R4)

4-byte floating point value. This property type is the same as the OLE type VT_R4.

PT_R8 (PT_MV_R8)

8-byte floating point value. This property type is the same as the OLE type VT_DOUBLE.

PT_SHORT (PT_MV_SHORT)

Signed 16-bit integer. This property type is the same as PT_SHORT and the OLE type VT_I2.

PT_STRING8 (PT_MV_STRING8)

Null-terminated 8-bit character string. This property type is the same as the OLE type VT_LPSTR.

PT_SYSTIME (PT_MV_SYSTIME)

64-bit integer data and time value in the form of a FILETIME structure. This property type is the same as the OLE type VT_FILETIME.

PT_TSTRING (PT_MV_TSTRING)

Properties with this type have the property type reset to PT_UNICODE when compiling with the UNICODE symbol and to PT_STRING8 when not compiling with the UNICODE symbol. This property type is the same as the OLE type VT_LPSTR for resulting PT_STRING8 properties and VT_LPWSTR for PT_UNICODE properties

PT_UNSPECIFIED

Indicates that the property type is unknown. This property type is reserved for use with interface methods.


Regular Expressions

MAPI supports a limited form of regular expression notation. Regular expression notation is a compact way of specifying a group of strings that all match some criteria. A target string is said to match the regular expression if it is a member of this group of strings. Regular expressions are character strings in which plain text indicates that that text must exist in the target string, and special characters are used to indicate what variability is allowed in the target strings. MAPI uses the rules for regular expression matching only when the relational operator being used to compare strings is RELOP_RE.

Regular expressions are constructed of one or more single character regular expressions. A single character regular expression tests one character from the target string against one or more characters specified by the single character regular expression.


Single Character Regular Expressions

Single character regular expressions match at most one character from the target string. There are several types of single character regular expressions:

•	Ordinary characters. Any character that is not used in other sorts of regular expression syntax is an ordinary character. To match the regular expression, the target string must have that same character in the same position as it occurs in the regular expression. For example, the single character regular expression “g” indicates that the target string must have a “g” in the appropriate position.

•	Escaped special characters. The characters left bracket ([), right bracket (]), backslash (\), asterisk (*), period (.), dollar sign ($), and caret (^) are special in that they are used to form other types of regular expression syntax. To construct a single character regular expression that matches any one of those characters literally, preceed the character with a backslash (\). For example, the single character regular expression “\*” matches a single asterisk in the appropriate position. Recall that these rules only apply when the comparison operator is RELOP_RE, so these characters should not be escaped in all strings.

•	A period. A period (.) forms a special single character regular expression that matches any single character except NEWLINE. This indicates that the target string can have any character except NEWLINE in the position specified by the period.  For example, the strings “a”, “W”, and “7” all match the single character regular expression “.”.

•	Sets of allowed characters. Brackets ([ and ]) enclosing a set of characters indicates that any of the enclosed characters may occur in the appropriate position in the target string. The special characters period (.), asterisk (*), left-bracket ([), and backslash (\) are treated as normal characters when enclosed in brackets. Additionally, the right-bracket (]) is treated as a normal character if it is the first character in the set. For example, the single character regular expression “[]abc]” indicates that the target string can have either a right-bracket, an “a”, a “b”, or a “c” in the appropriate position.

A dash (-) between two other characters indicates a range of characters in ASCII sequence from the first character to the second. For example, the single character regular expression “[0-9]” indicates that the target string must have a digit in the appropriate position. The dash loses this meaning if it occurs as the first character in the set.

A caret (^) immediately following the left-bracket ([) is used to exclude the remaining characters within brackets from matching the target string. It indicates that the target string may have any character in the appropriate position except those following the caret, and NEWLINE. For example, the single character regular expression “[^0-9]” indicates that the target string cannot have a digit in the appropriate position. The caret loses this special meaning if it is not the first character within the square brackets. In addition, the left-bracket ([) and dash (-) may be excluded from matching if they immediately follow the caret, rather than immediately following the initial left-bracket ([) as previously described. For example, the regular expression “[^[]” matches any single character except for a left bracket.


Multiple Character Regular Expressions

Single character regular expressions can be combined into more complex regular expressions that match more than one character at a time. You can also apply modifiers to single character regular expressions to make them match more than one instance of the character or characters specified by the single character regular expression.

Use the following rules to construct regular expressions from single character regular expressions:

•	A single character regular expression followed by an asterisk (*) is a regular expression that matches zero or more consecutive occurrences of the single character regular expression; always as many as possible. For example, “f*” matches zero or more consecutive “f” characters.

•	A single character regular expression followed by \{m\}, \{m,\}, or \{m,n\} is a regular expression that matches a specified number of occurrences of the single character regular expression. The values of m and n must be nonnegative integers less than 255; \{m\} matches exactly m occurrences of the single character regular expression; \{m,\} matches at least m occurrences; \{m,n\} matches any number of occurrences between m and n, inclusive. Whenever a choice exists, the regular expression matches as many occurrences as possible. For example, the regular expression “[0-9]\{1,4\}” matches any sequence of 1 to 4 digits.

•	A concatenation of regular expressions is a regular expression that matches the concatenation of the strings matched by each component of the regular expression. For example, the regular expression “[0-9][a-z]” matches any string of two characters that starts with a digit and ends with a lowercase letter.

•	A regular expression enclosed between the character sequences \( and \) is a sub-expression that matches whatever the original regular expression matches. The sub-expression is placed in a internal, numbered register for use later. The registers are numbered according to the pairs of \( and \) within the whole regular expression. The first pair corresponds to register 1. For example, if a string matches the regular expression “\([0-9]*\)\([a-z]*\)”, register 1 will contain whatever sequence of characters matched the regular expression “[0-9]*”, and register 2 will contain whatever sequence of characters matched the regular expression “[a-z]*”. There may be up to 9 sub-expressions in a regular expression.

•	The expression \n, where n is a digit from 1 through 9, matches the same string of characters stored in the internal register number n; that is, the same string of characters that the sub-expression corresponding to n originally matched. Regular expressions of the form \n are meaningless unless there is a sub-expression corresponding to n. For example, the regular expression “\([0-9]\)\1\1” matches any string which consists of the same digit three times, such as “777”.

•	A regular expression preceeded by a caret (^) must match at the beginning of the target string. A regular expression followed by a dollar sign ($) must match at the end of the target string. Both may be used in the same regular expression. For example, the regular expression “^[0-9]*$” only matches strings that consist entirely of digits.


Mapping of Internet Mail Attributes to MAPI Properties

This appendix describes how a MAPI transport provider or MAPI-aware gateway which connects to the Internet should translate between MAPI message properties and Simple Mail Transport Protocol (SMTP) message attributes. SMTP is the messaging protocol used on much of the Internet. SMTP defines a set of message headers — the message envelope — and a message content format. SMTP is fully documented in a set of two docments, RFC 821 and RFC 822, which can be found at a number of FTP and WWW sites on the Internet.

For information on the SMTP protocol used to communicate with SMTP-based mail agents, see RFC 821.

For addressing and standard message headers, see RFC 822.

For MIME, see RFC 1521.

The goal of mapping SMTP message attributes to MAPI properties (and vice versa) is to ensure that the full content of MAPI messages, over and above that which can be encoded using native SMTP message attributes, can be reliably exchanged among different MAPI components that must communicate over the Internet. This document is based on work already done on such components at Microsoft. How to translate between MAPI message properties and X.400 message attributes is described in the appendix, Mapping of X.400 P2 Attributes to MAPI Properties.

This document assumes familiarity with MAPI transports, TNEF, and SMTP mail. It strives to be concise rather than abundantly clear.

As a convention, “outbound” refers to mail traveling from a MAPI-compliant UA or MTA to the Internet, and “inbound” refers to mail traveling from the Internet to a MAPI component.


Addressing

The format of SMTP e-mail addresses is defined in RFC 822. MAPI components should handle any address that complies with that standard. However, there is a particular form of RFC 822 address that best encodes MAPI addresses:

          display-name <email-address>

The angle brackets are included as literals. Blanks are common in display names; they need not be quoted. A typical address might look like this one, which belongs to one of the coauthors of RFC 1521:

          Nathaniel Borenstein <nsb@bellcore.com>

If the display name contains characters that have special meaning in SMTP addresses, such as < or @, the entire display name should be quoted using double quotes. On outbound mail, if the total length of the e-mail address plus display name exceeds 255 characters, the display name should be dropped.

The parts of an SMTP address map into MAPI properties as follows:

SMTP address component	MAPI property
display-name for all recipients	PR_DISPLAY_NAME
display-name for From field	PR_SENDER_NAME
display-name for Sender field	PR_SENT_REPRESENTING_NAME
email-address	PR_EMAIL_ADDRESS
implicit, always “SMTP”	PR_ADDRTYPE
If there is no display name for an address on inbound mail, the entire e-mail address should be used instead. The address type is always SMTP.

Recipient properties are taken from the MAPI message’s recipient table; sender properties are taken from the message itself.


Message Envelope

RFC 822 headers are mapped to MAPI properties as follows. PR_SENDER_* is an abbreviation for the following 5 properties:

PR_SENDER_NAME

PR_SENDER_ADDRTYPE

PR_SENDER_EMAIL_ADDRESS

PR_SENDER_SEARCH_KEY

PR_SENDER_ENTRYID

Similar abbreviations are used for PR_SENT_REPRESENTING_* and other groups of message properties.

SMTP header	MAPI property
From:	Outbound: PR_SENDER_*; inbound: PR_SENDER_* and PR_SENT_REPRESENTING_*
Date:	Outbound: current time; inbound: PR_MESSAGE_DELIVERY_TIME
To:	PR_DISPLAY_NAME and PR_EMAIL_ADDRESS for recipients where PR_RECIPIENT_TYPE is MAPI_TO
Cc:	PR_DISPLAY_NAME and PR_EMAIL_ADDRESS for recipients where PR_RECIPIENT_TYPE is MAPI_CC
Bcc:	PR_DISPLAY_NAME and PR_EMAIL_ADDRESS for recipients where PR_RECIPIENT_TYPE is MAPI_BCC
Received:	No corresponding MAPI property; put local host name and your component name here
Return-receipt-to:	PR_REPORT_NAME and PR_REPORT_ENTRYID
Reply-to:	PR_REPLY_RECIPIENT_ENTRIES and PR_REPLY_RECIPIENT_NAMES
Subject:	PR_SUBJECT No particular length limitation.
MIME-version:	Always “1.0”
X-MS-Attachment:	For compatibility with MS Mail SMTP gateway. filename size mm-dd-yyy hh:mm Details below.
entire SMTP message envelope	PR_TRANSPORT_MESSAGE_HEADERS
header name TBD	PR_SEND_RICH_INFO for sender only. The TBD header should be used to determine whether the sender is capable of interpreting TNEF content in a reply.
MessageID:	PR_TNEF_CORRELATION_KEY
Content-type	Either text/plain or multipart/mixed. See “Message Content” section.
The X-MS-Attachment header is formatted as four tokens, separated by a space:

          name size date time

The first token is the filename, which may contain embedded spaces, so this header should be parsed from the right on inbound messages. The size is in bytes; the date is formatted as mm-dd-yyyy, and the time as hh:mm.

Note  MessageID is not mapped to PR_SEARCH_KEY because the SMTP domain has specific requirements on the format of the message identifier which make it impossible to encode an arbitrary MAPI message identifier. Instead, MessageID is mapped to PR_TNEF_CORRELATION_KEY. This property is a transport-defined property that is set by the transport sending an outbound message and used by a transport receiving an inbound message. For more information, see Developing a TNEF-Enabled Transport Provider.


Message Content

There are two possible encodings for the message content: one using MIME, the other using uuencode. MIME is the preferred encoding. In addition, MAPI defines a per-recipient property, PR_SEND_RICH_INFO, that governs whether or not TNEF information should be included in an outgoing message. So there are a total of four ways of encoding message content:

•	MIME with TNEF

•	MIME without TNEF

•	uuencode with TNEF

•	uuencode without TNEF

How to choose MIME or uuencode for outbound messages is not specified.

The following properties are excluded from TNEF: PR_SENDER_*, PR_ATTACH_DATA_*, PR_BODY. All other transmittable message properties are included in the TNEF stream.


Message Text

For outbound messages in MIME mode, the content-type depends on whether there are attachments and what the message text looks like. If there are attachments, the Content-type is multipart/mixed; the message text and each attachment become a separate part of the message content, each with its own content-type. If there are no attachments, the content-type of the message is text/plain and there is only one part.

The message text is not line-wrapped unless some line exceeds 140 characters in length. If one does, the entire text is wrapped to 76 columns and the quoted-printable encoding is used to preserve line breaks. The content-type depends on what characters are found in the message text, as follows:

•	If only 7-bit characters are found and no line exceeds 140 characters in length, the message is ASCII text.

Content-type: text/plain; charset=us-ascii
(Content-Transfer-Encoding=7bit is assumed.)

•	If long lines or 8-bit characters are found, the message is text and the character set is determined by the locale. It should be chosen from the character sets defined by ISO standard 8859.

Content-type: text/plain; charset=iso-8859-1 (or another valid charset)
Content-Transfer-Encoding: quoted-printable

For inbound MIME messages, if the first message content part has Content-type: text/* (that is, any text type) and its character set is recognized, it is mapped to PR_BODY. A first message content part not meeting this criterion becomes an attachment. Any subsequent parts also become attachments.

In uuencode mode, message text in outbound messages is line-wrapped to 78 columns, as for MS Mail 3.x. The content-type is “text/plain.” To preserve the original message’s paragraph breaks under these circumstances, observe the following conventions in the wrapped text. There are three possible reasons for ending a line of text, each with its own character sequence:

•	Line-break. The original text contained a newline entered by the user (paragraph mark). In the transport, this maps to a newline with no preceding blanks. If the user enters a newline preceded by blanks, the blanks should be stripped out.

•	Line-nobreak. The original text contained a word too long to fit on a single line of the message. In the transport, this maps to a newline preceded by two blanks.

•	Line-wrap. The original text contained no newline, the text is too long to fit on a single line of the message, but it can be broken between two words. In the transport, this maps to a newline preceded by a single blank.


Attached Files and Messages

MIME with TNEF. All attachment properties and content are in the TNEF stream. The TNEF itself is a single, binary attached file named WINMAIL.DAT, encoded as described for MIME without TNEF.

MIME without TNEF. Attached files are sent as MIME message content parts. The filename is placed in the name parameter to the Content-type header for the attachment. The character set for the attachment is placed in the charset parameter to the Content-type; it and the content-transfer-encoding are determined by scanning the entire attachment content. URL attachments are treated specially:

•	If the attachment is a URL (an attached file with extension .URL), and the access mode defined in it is anonymous FTP, it is encoded as an external message, and the content of the file (the URL) is copied into the header of the external message.

Content-type: message/external-body; access-type=anon-ftp
(Content-Transfer-Encoding: 7bit is assumed.)

•	If only 7-bit characters are found and no line exceeds 140 characters in length, the attachment is ASCII text.

Content-type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

•	If long lines or up to 25% 8-bit characters are found, the attachment content is text and the character set is determined by the locale. It should be chosen from the character sets defined by ISO standard 8859.

Content-type: text/plain; charset=ISO-8859-1 (or what have you)
Content-Transfer-Encoding: quoted-printable

•	If 25% or more of the characters have the high bit set, the attachment is binary. It is encoded using the Base64 algorithm.

Content-type: application/octet-stream (by default; based on file extension)
Content-Transfer-Encoding: base64

On outbound messages, the content-type should be derived from the filename’s three-letter extension. This mapping exists in the system registry; under there is a string value named “Content Type” that gives the MIME content type if one is defined. This example is for a TIFF image file:

HKEY_LOCAL_MACHINE\
   Software\
      Microsoft\
         Classes\
            .tif
               Content Type = “image/tiff”

If there is no mapping for the file extension, the default application/octet-stream should be used. Windows 95 now supports this system registry mapping. Windows NT will support it in a forthcoming release. Windows 3.x does not support a system registry; implementations are free to choose how they store this mapping.

On inbound messages, the content-type for an attachment should always be copied to the MAPI property PR_ATTACH_MIME_TAG. Even if a filename is defined for an attached file, the extension mapped by the content-type should be used in the PR_ATTACH_FILENAME and PR_ATTACH_EXTENSION properties.

The name parameter is officially “deprecated” by RFC 821. As standards evolve, Microsoft will consider specifying an alternate mapping for attached filenames.

Outbound attached messages are sent as
Content-type: message/rfc822
Messages within attached messages are encoded recursively, in their proper place. Inbound message content parts with Content-Type: multipart/digest are also mapped to embedded messages.

Uuencode with TNEF. All attachment properties and content are in the TNEF stream. The TNEF itself is a single, binary attached file named WINMAIL.DAT, encoded as described for Uuencode without TNEF.

Uuencode without TNEF. All attached files are treated as binary and uuencoded, following the message text. The file name is present in the uuencode header:
begin 0755 WINMAIL.DAT
... data ...
end

Attached messages are textized into the message text. The hierarchy of attached messages is always flattened; that is, messages within attached messages are pulled out to the top level.

Embedded OLE objects are discarded.

General. Attachment rendering positions are transmitted literally, using the property PR_ATTACH_RENDERING in the TNEF. If TNEF is not used, they are lost. Incoming attachments with no rendering position (including when there is no TNEF) have their rendering position set to 0xFFFFFFFF, i.e. no position within the message text.


Suggested Configuration Parameters

The following are suggestions only, not requirements. The intent is to provide a convenient list of parameters which the implementation can choose how to support.

Whether to encode using MIME or uuencode for outbound messages: boolean.

Character set to use for outbound messages: string (copied directly to charset parameter) or enumeration (translated internally to charset string).

(possibly, if not supplied by the OS) List of mappings between file extensions and content-types.


Transport-Neutral Encapsulation Format (TNEF)

TNEF is a format for converting a set of MAPI properties—a MAPI message—into a serial data stream. The TNEF functions are primarily used by transport providers that need to encode MAPI message properties for transmission through a messaging system that does not support those properties directly. For example, an SMTP-based transport uses TNEF to encode properties like PR_SENT_REPRESENTING, which do not have direct representations in the structure of an SMTP message.

The TNEF implementation defines several TNEF-specific attributes, each of which corresponds to a particular MAPI property. These attributes are used to encode their respective MAPI properties into the TNEF stream. In addition, a special attribute is defined that can be used to encapsulate any MAPI property that does not have a specific attribute corresponding to it. The reason these attributes are defined — instead of simply using a uniform encoding method for all MAPI properties — is to enable backward compatibility with non-MAPI-compliant software that is using TNEF such as Microsoft Mail 3.x and its transport providers.

The remainder of this appendix describes the structure and syntax of a TNEF stream, the mapping between MAPI properties and TNEF attributes, and important considerations for certain TNEF attributes.


TNEF Stream Structure

A TNEF stream begins with a 32-bit signature that identifies the stream as a TNEF stream. Following the signature is a 16-bit unsigned integer that is used as a key to cross-reference attachments to their location within the tagged message text. The remainder of the stream is a sequence of TNEF attributes. Message attributes appear first in the TNEF stream, and attachment attributes follow. Attributes belonging to a particular attachment are grouped together, beginning with the attAttachRenddata attribute.

Most of the constant values used in TNEF streams are defined in the TNEF.H header file. Notably, TNEF_SIGNATURE, LVL_MESSAGE, LVL_ATTACHMENT, and all the TNEF attribute identifiers are defined in this file. Other constants have the values indicated by their interpretation to a C language compiler. Typically, such constants are used to give the sizes of the following item. For example, sizeof(ULONG) in an item’s definition indicates that an integer representing the size of the following unsigned long integer should occur in that place in the TNEF stream.

All integers in a TNEF stream are stored in little-endian binary form, but are shown in hexadecimal throughout this appendix. Checksum values are simply 16-bit unsigned integers that are the sum, modulo 65536, of the bytes of data that the checksum applies to. All attribute lengths are unsigned long integers, including any terminating null characters.

The key is a nonzero, 16-bit unsigned integer that signifies the initial value of the attachment reference keys. The attachment reference keys are assigned to each attachment sequentially beginning with the initial value, that is passed to the OpenTnefStream function by the service provider that is using TNEF. The service provider should generate a random initial value for the key to minimize the chance that two messages use the same key.

The TNEF implementation uses attribute identifiers to map attributes to their corresponding MAPI properties. An attribute identifier is a 32-bit unsigned integer made up of two word values. The high-order word indicates the data type, such as string or binary, and the low-order word identifies the particular attribute. The data types in the high order word are:

Type	Value
atpTriples	0x0000
atpString	0x0001
atpText	0x0002
atpDate	0x0003
atpShort	0x0004
atpLong	0x0005
atpByte	0x0006
atpWord	0x0007
atpDword	0x0008
atpMax	0x0009
The low-order word values for each attribute are defined in the TNEF.H header file.


TNEF Stream Syntax

This topic presents a Bakus-Nauer like description of the TNEF stream syntax. In this description, nonterminal elements that have a further definition are in italics. Constants and literal items are in bold. Sequences of elements are listed in order on a single line. For example, the Stream item consists of the constant TNEF_SIGNATURE, followed by a Key, followed by an Object. When an item has more than one possible implementation, the alternatives are listed on consecutive lines. For example, an Object can consist of a Message_Seq, a Message_Seq followed by an Attach_Seq, or just an Attach_Seq.

TNEF_Stream:

TNEF_SIGNATURE Key Object

Key:

a nonzero 16-bit unsigned integer

TNEF enabled transports generate this value before using the TNEF implementation to generate a TNEF stream.

Object:

Message_Seq
Message_Seq Attach_Seq
Attach_Seq

Message_Seq:

attTnefVersion
attTnefVersion Msg_Attribute_Seq
attTnefVersion attMessageClass
attTnefVersion attMessageClass Msg_Attribute_Seq
attMessageClass
attMessageClass Msg_Attribute_Seq
Msg_Attribute_Seq

attTnefVersion:

LVL_MESSAGE attTnefVersion sizeof(ULONG) 0x00010000 checksum

attMessageClass:

LVL_MESSAGE attMessageClass msg_class_length msg_class checksum

Msg_Attribute_Seq:

Msg_Attribute
Msg_Attribute Msg_Attribute_Seq

Msg_Attribute:

LVL_MESSAGE attribute-ID attribute-length attribute-data checksum

Attribute-ID is one of the TNEF attribute identifiers, such as attSubject. Attribute-length is the length in bytes of the attribute data. Attribute-data is the data associated with the attribute.

Attach_Seq:

attRenddata
attRenddata Att_Attribute_Seq

attRenddata:

LVL_ATTACHMENT attRenddata sizeof(RENDDATA) renddata checksum

Renddata is the data associated with the RENDDATA structure containing the rendering information for the corresponding attachment. The RENDDATA structure is defined in the TNEF.H header file.

Att_Attribute_Seq:

Att_Attribute
Att_Attribute Att_Attribute_Seq

Att_Attribute:

LVL_ATTACHMENT attribute-ID attribute-length attribute-data checksum

Attribute-ID, attribute-length, and attribute-data have the same meanings as for the Msg_Attribute item.


Mapping of TNEF Attributes to MAPI Properties

The following table lists all the attributes defined in the TNEF implementation and their mappings to MAPI properties. In some cases, multiple MAPI properties are encoded as a single attribute. Some attributes have extended descriptions later in this appendix.

TNEF attribute	MAPI property or properties
attAidOwner	PR_OWNER_APPT_ID
attAttachCreateDate	PR_CREATION_TIME
attAttachData	PR_ATTACH_DATA_BIN or PR_ATTACH_DATA_OBJ
attAttachment	For information about this mapping, see Comments About the Attributes.
attAttachMetaFile	PR_ATTACH_RENDERING
attAttachModifyDate	PR_LAST_MODIFICATION_TIME
attAttachRenddata	PR_ATTACH_METHOD, PR_RENDERING_POSITION
attAttachTitle	PR_ATTACH_FILENAME
attAttachTransportFilename	PR_ATTACH_TRANSPORT_NAME
attBody	PR_BODY
attConversationID	PR_CONVERSATION_KEY See attConversationID and attParentID for details.
attDateEnd	PR_END_DATE See attDate Attributes for details.
attDateModified	PR_LAST_MODIFICATION_TIME See attDate Attributes for details.
attDateRecd	PR_MESSAGE_DELIVERY_TIME See attDate Attributes for details.
attDateSent	PR_CLIENT_SUBMIT_TIME See attDate Attributes for details.
attDateStart	PR_START_DATE See attDate Attributes for details.
attFrom	PR_SENDER_ENTRYID and PR_SENDER_NAME
attMAPIProps	For information about this attribute, see attMAPIProps.
attMessageClass	PR_MESSAGE_CLASS
attMessageID	PR_SEARCH_KEY See TNEF Correlation in X.400 Gateways and Transports.
attMessageStatus	PR_MESSAGE_FLAGS
attOriginalMessageClass	PR_ORIG_MESSAGE_CLASS
attOwner	See attOwner for details.
attParentID	PR_PARENT_KEY See attConversationID and attParentID for details.
attPriority	PR_PRIORITY
attRecipTable	PR_MESSAGE_RECIPIENTS
attRequestRes	PR_RESPONSE_REQUESTED
attSentFor	PR_SENT_REPRESENTING_ENTRYID
attSubject	PR_SUBJECT
attTnefVersion


Comments About the Attributes

This section provides additional information about certain TNEF attributes. For more information about the MAPI properties that the attributes are mapped to, see the reference entries for the individual properties.


attMAPIProps

The attMAPIProps attribute is special in that it can be used to encode any MAPI property that does not have a counterpart in the set of existing TNEF-defined attributes. The attribute data is a counted set of MAPI properties laid end-to-end. The format of this encoding, which allows for any set of MAPI properties, is as follows:

Property_Seq:

property-count Property_Value, ...

There must be as many Property_Value items as the property-count value indicates.

Property_Value:

property-tag Property
property-tag Proptag_Name Property

The property-tag is simply the value associated with the property identifier, such as 0x0037001F for PR_SUBJECT.

Property:

Value
value-count Value, ...

Value:

value-data
value-size value-data padding
value-size value-IID value-data padding

Proptag_Name:

name-guid name-kind name-id
name-guid name-kind name-string-length name-string padding

The encapsulation of each property varies based on the property identifier and the property type. Property tags, identifiers, and types are defined in the MAPITAGS.H and MAPIDEFS.H header files.

If the property is a named property, then the property tag is immediately followed by the MAPI property name, consisting of a globally unique identifier (GUID), a type, and either an identifier or a Unicode string.

Multivalued properties and properties with variable length values, such as the PT_BINARY, PT_STRING8, PT_UNICODE, or PT_OBJECT property types, are treated in the following way. First the number of values, encoded as a 32-bit unsigned long, is placed in the TNEF stream, followed by the individual values. Each property’s value-data is encoded as its size in bytes followed by the value-data itself. The value-data is padded out to a 4-byte boundary, although the amount of padding is not included in the value-size.

If the property is of type PT_OBJECT, the value-size is followed by the interface identifier of the object. The current implementation of TNEF only supports the IID_IMessage, IID_IStorage, and IID_Istream interface identifiers. The size of the interface identifier is included in the value-size.

If the object is an embedded message (that is, it has a property type of PT_OBJECT and an interface identifier of IID_Imessage), the value data is encoded as an embedded TNEF stream. The actual encoding of an embedded message in TNEF implementation is done by opening a second TNEF object for the original stream and processing the stream inline.


attDate Attributes

All MAPI properties relating to dates and times are mapped to TNEF attributes that have the attDate prefix. These are all encoded as DTR structures. The dates and times for attachment attributes are encoded as DTR structures as well.

A DTR structure is very similar to the SYSTEMTIME structure defined in the Win32 header files. The DTR structure is encoded in the TNEF stream as sizeof(DTR) bytes starting with the first member of the structure. The DTR structure is defined in the TNEF.H header file.


attOriginalMessageClass

A message class is stored as a string. The encoded string usually holds the MAPI-specified name of the message class. The exception is that to provide compatibility with Microsoft Mail for Windows for Workgroups 3.1, the following MAPI message classes are mapped to the following Microsoft Mail for Windows for Workgroups 3.1 message classes:

MAPI message class	Windows for Workgroups Mail 3.x
IPM	IPM.Microsoft Mail.Note
IPM.Note	IPM.Microsoft Mail.Note
IPM.Schedule.Meeting.Canceled	IPM.Microsoft Schedule.MtgCncl
IPM.Schedule.Meeting.Request	IPM.Microsoft Schedule.MtgReq
IPM.Schedule.Meeting.Resp.Neg	IPM.Microsoft Schedule.MtgRespN
IPM.Schedule.Meeting.Resp.Pos	IPM.Microsoft Schedule.MtgRespP
IPM.Schedule.Meeting.Resp.Tent	IPM.Microsoft Schedule.MtgRespA
Report.IPM.Note.NDR	IPM.Microsoft Mail.Non-Delivery
Report.IPM.Note.RN	IPM.Microsoft Mail.Read Receipt


attConversationID and attParentID

The Windows for Workgroups 3.1 Mail conversation key is a text string. The MAPI equivalent is a binary value. To provide backward compatability, the TNEF implementation converts the binary data to text and adds a terminating null character.


attFrom

The attFrom attribute is encoded as a TRP structure which encodes the display name and e-mail address of the sender, followed by the display name and address of the sender, followed by any necessary padding. The format for attFrom is as follows:

attFrom:

TRP-structure sender-display-name sender-address padding

The sender-display-name is a null-terminated string that is padded with an additional null character, if necessary, to reach a 2-byte boundary. The padding at the end of the attFrom encoding consists of as many null characters as needed to reach a sizeof(TRP) boundary.

TRP-structure:

trpidOneOff cbgrtrp cch cb

For the attFrom item, the TRP-structure is always a one-off encoding, so the trpid off the TRP-structure field is always trpidOneOff. The cbgrtrp, cch, and cb items correspond to the remaining fields of the TRP structure.

The cbgrtrp field is calculated as the sum of (sizeof(TRP) *2), the length of the null-terminated sender-display-name with its padding, and the length of the null-terminated sender-address.

The cch field is calculated as the length of the null-terminated display-name with its padding.

The cb field is calculated as the length of the null-terminated sender-address.

sender-address:

address-type : address ‘\0’

The sender-address is a string that is composed of four parts, the address-type, a literal colon (:), the address itself, and a terminating null character. For example, the string “fax:1-909-555-1234\0” would be a legal sender-address value.


attOwner

The attOwner attribute is encoded as counted strings laid end-to-end. The format for attOwner is as follows:

attOwner:

display-name-length display-name address-length email-address

email-address

type : address

Unlike other length values, the display-name-length and address-length are unsigned 16-bit values instead of unsigned long integers. They still include terminating null characters, however. The type and address strings in the email-address entry are separated by a literal colon (:) character, such as “smtp:joe@nowhere.com”. Only the combined type:address string is null-terminated.

The mapping of MAPI properties to the attOwner attribute is dependent on the message class of the message being encoded. If the message is either a Microsoft Schedule+ meeting request or cancellation, then attOwner encodes one of the PR_SENT_REPRESENTING properties. If the message is a Microsoft Schedule+ meeting response of any type, then attOwner encodes one of the PR_RCVD_REPRESENTING properties.


attSentFor

The attSentFor attribute is encoded as counted strings laid end-to-end. The format for attSentFor is as follows:

attSentFor:

display-name-length display-name address-length email-address

email-address

type : address

Unlike other length values, the display-name-length and address-length are unsigned 16-bit values instead of unsigned long integers. They still include terminating null characters, however. The type and address strings in the email-address entry are separated by a literal colon (:) character, such as “smtp:joe@nowhere.com”. Only the combined type:address string is null-terminated.


attRecipTable

When a recipient table is being encoded, each recipient is encoded as a row of MAPI properties. The format is as follows:

Row_Seq:

row-count Property_Sequence, ...

The format of Property_Seq is the same as in the attMAPIProps attribute.


attPriority

MAPI message priorities are also mapped to Microsoft Mail 3.1 priority values for backward compatability as follows:

Priority	MAPI value	TNEF value
normal	-1	3
high	0	2
low	1	1


attMessageStatus

MAPI message flags are mapped to Microsoft Mail 3.1 values to preserve backward compatability. All the flags are grouped together and encoded in a single byte. The mappings are as follows:

MAPI message flags	TNEF flags
MSGFLAG_READ	fmsRead
MSGFLAG_UNMODIFED	~fmsModified
MSGFLAG_SUBMIT	fmsSubmitted
MSGFLAG_HASATTACH	fmsHasAttach
MSGFLAG_UNSENT	fmsLocal
These flags are defined in the TNEF.H header file.


attAttachRenddata

The attAttachRenddata attribute is encoded as a RENDDATA structure that describes how and where the attachment is rendered in the message text. The RENDDATA structure is simply encoded in the TNEF stream as sizeof(RENDDATA) bytes beginning with the first member of the RENDDATA structure. If the value of the RENDDATA structure’s dwFlags member is set to MAC_BINARY, then the data for the following attachment is stored in MacBinary format; otherwise, the attachment data is encoded as usual.


OLE Attachments

Attachments that are OLE objects are encoded as OLE 1 stream objects for backward compatability with Microsoft Mail 3.x. If the original object is really an OLE 2 IStorage object, then the object must be converted to an OLE 1 stream. This conversion is performed using the OleConvertIStorageToOLESTREAM function, which is part of the Win32 OLE libraries; examples of this conversion can be found in the OLE Programmer’s Reference.


TNEF Correlation

Some messaging systems perform a correlation check on any TNEF stream attached to an inbound message to verify that the TNEF stream does in fact belong to that message. This involves matching the value of some field in the header of the inbound message with a copy of that value stored in some property in the TNEF stream. Values that are presumably unique for each message, such as message ID numbers, are typically used for this. The transport or gateway the created the TNEF stream is responsible for choosing an appropriate value from the message header and placing a copy into an appropriate property before encoding the outgoing message’s properties into the TNEF stream. Gateways or transports that receive the message can then extract that property from the TNEF stream and verify that its value matches the value of the corresponding header field on the inbound message.

If the values do not match, the gateway or transport should discard the TNEF stream and process only the native message envelope. Such checks are prudent because non-MAPI-based mail clients may attach a file containing a TNEF stream from an old message to a forwarding or even an unrelated message; if not checked, such an error may result in the loss of message text.

The header field value chosen must be unique to the message. There is no fixed header field for all messaging systems because different messaging systems use different header fields, but typically the messaging system assigns a unique identifier to the message which is suitable for this purpose. For example, SMTP systems typically use the MessageID header, while X.400 systems typically use the IM_THIS_IPM attribute.


TNEF Correlation in SMTP Gateways and Transports

Gateways and transports that connect to internet based systems, those that use SMTP, use the value of the MessageID SMTP header and the PR_TNEF_CORRELATION_KEY property to implement TNEF correlation.

The value of the MessageID header of the outbound message should be copied to the PR_TNEF_CORRELATION_KEY property and encoded in the attMAPIProps attribute of the TNEF stream. Note that PR_TNEF_CORRELATION_KEY is a binary property, while the MessageID is a string; the null terminator should be included in the copy and in the comparison.

This technique is used by all Microsoft software that connects MAPI-based messaging systems to the Internet, such as Microsoft Mail 3.x and Microsoft Exchange Server. This technique should be used by any SMTP gateways and transports that connect to systems that support MAPI clients in order to maximize interoperability.


TNEF Correlation in X.400 Gateways and Transports

Gateways and transports that connect to X.400-based systems, use the value of the IM_THIS_IPM X.400 attribute and the attMessageID TNEF attribute to implement TNEF correlation.

The value of the IM_THIS_IPM attribute of the outbound message is copied to attMessageID in the TNEF stream. The IM_THIS_IPM X.400 attribute is typically a string, while the attMessageID TNEF attribute is a string of hexadecimal digits representing a binary value. Therefore, each character in the IM_THIS_IPM X.400 attribute, including the terminating null character, must be converted to a 2-character hexadecimal string representing the ASCII value of that character. For instance, if the IM_THIS_IPM X.400 attribute is the following string:

    3030322D3030312D305337533A3A3936303631312D313533373030

then the value of attMessageID would be the following sequence of hexadecimal digits:

    33 30 33 30 33 32 32 44

    33 30 33 30 33 31 32 44

    33 30 35 33 33 37 35 33

    33 41 33 41 33 39 33 36

    33 30 33 36 33 31 33 31

    32 44 33 31 33 35 33 33

    33 37 33 30 33 30 00

This technique is used by the Microsoft Exchange Server X.400 Connector. This technique should be used by any X.400 gateways and transports that connect to Microsoft Exchange Server in order to maximize interoperability.

For greatest compatibility with future as well as present Microsoft software, the IM_THIS_IPM X.400 attribute should also be copied to the PR_TNEF_CORRELATION_KEY property. However, since PR_TNEF_CORRELATION_KEY is a binary property, no translation into a hexadecimal string is necessary.


Mapping of X.400 P2 Attributes to MAPI Properties

The X/Open CAE Specification API to Electronic Mail (X.400), published by the X/Open Company Limited and X.400 API Association (1991), describes a recommended implementation of the X.400 (1984) and X.400 (1988) Blue Book specifications.

This appendix describes mappings between the recommended implementation’s P2 attributes and MAPI properties.

 The reference information is presented in two different ways in this appendix:

•	X.400 attributes are organized by object.

•	All X.400 attributes are combined into one comprehensive list and presented in alphabetical order.


X.400 Attributes By Object

The following entries contain tables for each object listing the mappings from X.400 P2 attributes to their corresponding MAPI properties.


OMP_O_IM_C_BD_PRT

The class OMP_O_IM_C_BD_PRT does not have any attributes that are unique to the class.


OMP_O_IM_C_BILAT_DEF_BD_PRT

The attributes of the class OMP_O_IM_C_BILAT_DEF_BD_PRT map to MAPI properties as follows:

MH ID/Type	MAPI Property
IM_BILATERAL_DATA	PR_ATTACH_DATA_BIN


OMP_O_IM_C_EXTERN_DEF_BD_PRT

The attributes of the class OMP_O_IM_C_EXTERN_DEF_BD_PRT map to MAPI properties as follows:

MH ID/Type	MAPI Property
IM_EXTERNAL_DATA	PR_ATTACH_DATA_BIN, PR_ATTACH_FILENAME, PR_ATTACH_TAG
IM_ EXTERNAL_PARAMETERS	PR_ATTACHMENT_X400_PARAMETERS


OMP_O_IM_C_G3_FAX_BD_PRT

The attributes of the class OMP_O_IM_C_G3_FAX_BD_PRT are not mapped to MAPI properties.

MH ID/Type	MAPI Property
IM_G3_FAX_NBPS	Not mapped to a MAPI property.
IM_IMAGES	Not mapped to a MAPI property.


OMP_O_IM_C_G4_CLASS_1_BD_PRT

The attributes of the class OMP_O_IM_C_G4_CLASS_1_BD_PRT are not mapped to MAPI properties.

MH ID/Type	MAPI Property
IM_G4_CLASS_1_DOCUMENT	Not mapped to a MAPI property.


OMP_O_IM_C_GENERAL_TEXT_BD_PRT

The attributes of the class OMP_O_IM_C_GENERAL_TEXT_BD_PRT are not mapped to MAPI properties.

MH ID/Type	MAPI Property
IM_CHAR_SET_REG	Not mapped to a MAPI property.
IM_TEXT	Not mapped to a MAPI property.


OMP_O_IM_C_IA5_TEXT_BD_PRT

The attributes of the class OMP_O_IM_C_IA5_TEXT_BD_PRT are mapped to the following MAPI properties:

MH ID/Type	MAPI Property
IM_REPERTOIRE	Not mapped to a MAPI property.
IM_TEXT	PR_BODY


OMP_O_IM_C_INTERPERSONAL_MSG

The attributes of the class OMP_O_IM_C_INTERPERSONAL_MSG map to MAPI properties as follows:

MH ID/Type	MAPI Property
IM_AUTHORIZING_USERS	PR_AUTHORIZING_USERS
IM_AUTO_FORWARDED	PR_AUTO_FORWARDED
IM_BLIND_COPY_RECIPIENTS	PR_DISPLAY_BCC
IM_BODY	PR_BODY
IM_COPY_RECIPIENTS	PR_DISPLAY_CC
IM_EXPIRY_TIME	PR_EXPIRY_TIME
IM_IMPORTANCE	PR_IMPORTANCE
IM_INCOMPLETE_COPY	PR_INCOMPLETE_COPY
IM_LANGUAGES	PR_LANGUAGES
IM_OBSOLETED_IPMS	PR_OBSOLETED_IPMS
IM_ORIGINATOR	PR_CALLBACK_TELEPHONE_NUMBER, PR_SENDER_ADDRTYPE, PR_SENDER_EMAIL_ADDRESS, PR_SENDER_ENTRYID, PR_SENDER_NAME, PR_SENDER_SEARCH_KEY (and all PR_SENT_REPRESENTING_* properties)
IM_PRIMARY_RECIPIENTS	PR_DISPLAY_TO
IM_RELATED_IPMS	PR_RELATED_IPMS
IM_REPLIED_TO_IPM	PR_PARENT_KEY
IM_REPLY_RECIPIENTS	PR_REPLY_RECIPIENT_ENTRIES, PR_REPLY_RECIPIENT_NAMES
IM_REPLY_TIME	PR_REPLY_TIME
IM_SENSITIVITY	PR_SENSITIVITY
IM_SUBJECT	PR_NORMALIZED_SUBJECT, PR_SUBJECT, PR_SUBJECT_PREFIX
IM_THIS_IPM	PR_SEARCH_KEY
The following constant values are mapped from IM_IMPORTANCE to PR_IMPORTANCE:

Importance	MAPI value
IM_HIGH	2
IM_LOW	0
IM_ROUTINE	1
The following constant values are mapped from IM_SENSITIVITY to PR_SENSITIVITY:

IM_SENSITIVITY value	PR_SENSITIVITY value
IM_COMPANY_CONFIDENTIAL	SENSITIVITY_COMPANY_CONFIDENTIAL
IM_NOT_SENSITIVE	SENSITIVITY_NONE
IM_PERSONAL	SENSITIVITY_PERSONAL
IM_PRIVATE	SENSITIVITY_PRIVATE


OMP_O_IM_C_INTERPERSONAL_NOTIF

The attributes of the class OMP_O_IM_C_INTERPERSONAL_NOTIF map to MAPI properties as follows:

MH ID/Type	MAPI Property
IM_CONVERSION_EITS	PR_CONVERSION_EITS
IM_IPM_INTENDED_RECIPIENT	PR_ORIGINALLY_INTENDED_RECIPIENT_NAME
IM_IPN_ORIGINATOR	PR_CALLBACK_TELEPHONE_NUMBER, PR_SENDER_ADDRTYPE, PR_SENDER_EMAIL_ADDRESS, PR_SENDER_ENTRYID, PR_SENDER_NAME, PR_SENDER_SEARCH_KEY (and all PR_SENT_REPRESENTING_ * properties)
IM_SUBJECT_IPM	PR_ORIGINAL_SEARCH_KEY


OMP_O_IM_C_IPM_IDENTIFIER

The attributes of the class OMP_O_IM_C_IPM_IDENTIFIER map to MAPI properties as follows:

MH ID/Type	MAPI Property
IM_USER, IM_USER_RELATIVE_IDENTIFIER	Construct a GUID from IM_USER_RELATIVE_IDENTIFIER


OMP_O_IM_C_ISO_6937_TEXT_BD_PRT

The attributes of the class OMP_O_IM_C_ISO_6937_TEXT_BD_PRT are mapped to the following MAPI properties:

MH ID/Type	MAPI Property
IM_REPERTOIRE	Not mapped to a MAPI property.
IM_TEXT	PR_ATTACH_DATA_BIN


OMP_O_IM_C_MESSAGE_BD_PRT

The attributes of the class OMP_O_IM_C_MESSAGE_BD_PRT are mapped as follows:

MH ID/Type	MAPI Property
IM_ENVELOPE	Not mapped to a MAPI property.
IM_IPM	Mapped to an IMessage object embedded in the message.


OMP_O_IM_C_MIXED_MODE_BD_PRT

The attributes of the class OMP_O_IM_C_MIXED_MODE_BD_PRT are not mapped to any MAPI properties.

MH ID/Type	MAPI Property
IM_MIXED_MODE_DOCUMENT	Not mapped to a MAPI property.


OMP_O_IM_C_NATIONAL_DEF_BD_PRT

The attributes of the class OMP_O_IM_C_NATIONAL_DEF_BD_PRT are not mapped to MAPI properties.

MH ID/Type	MAPI Property
IM_NATIONAL_DATA	Not mapped to a MAPI property.


OMP_O_IM_C_NON_RECEIPT_NOTIF

The attributes of the class OMP_O_IM_C_NON_RECEIPT_NOTIF map to MAPI properties (when PR_NON_RECEIPT_NOTIFICATION_REQUESTED = 1 in Recipient table or when the message has PR_READ_RECEIPT_REQUESTED = 1), as follows:

MH ID/Type	MAPI Property
IM_AUTO_FORWARD_COMMENT	PR_AUTO_FORWARD_COMMENT
IM_DISCARD_REASON	PR_DISCARD_REASON
IM_NON_RECEIPT_REASON	PR_NON_RECEIPT_REASON
IM_RETURNED_IPM	(Object; no corresponding property)
The following constant values are mapped from IM_DISCARD_REASON to PR_DISCARD_REASON:

IM_DISCARD_REASON value	PR_DISCARD_REASON value
IM_NO_DISCARD	-1
IM_IPM_EXPIRED	0
IM_IPM_OBSOLETED	1
IM_USER_TERMINATED	2
The following constant values are mapped from IM_NON_RECEIPT_REASON to PR_NON_RECEIPT_REASON:

IM_NON_RECEIPT_REASON value	PR_NON_RECEIPT_REASON value
IM_IPM_AUTO_FORWARDED	1
IM_IPM_DISCARDED	0


OMP_O_IM_C_ODA_BD_PRT

The attributes of the class OMP_O_IM_C_ODA_BD_PRT are not mapped to MAPI properties.

MH ID/Type	MAPI Property
IM_APPLICATION_PROFILE	Not mapped to a MAPI property.
IM_ARCHITECTURE_CLASS	Not mapped to a MAPI property.
IM_ODA_DOCUMENT	Not mapped to a MAPI property.


OMP_O_IM_C_OR_DESCRIPTOR

The attributes of the class OMP_O_IM_C_OR_DESCRIPTOR map to MAPI properties as follows:

MH ID/Type	MAPI Property
IM_FORMAL_NAME	Extract name using PR_ENTRYID; for X.400 address types, build an OR Address from string address.
IM_FREE_FORM_NAME	PR_SENDER_NAME for originator, PR_DISPLAY_NAME for recipient, or extract the display name using PR_SENDER_ENTRYID
IM_TELEPHONE_NUMBER	PR_CALLBACK_TELEPHONE_NUMBER for originator, PR_PRIMARY_TELEPHONE_NUMBER for recipient


OMP_O_IM_C_RECEIPT_NOTIF

The attributes of the class OMP_O_IM_C_RECEIPT_NOTIF map to MAPI properties, as follows:

MH ID/Type	MAPI Property
IM_ACKNOWLEDGEMENT_MODE	PR_ACKNOWLEDGEMENT_MODE
IM_RECEIPT_TIME	PR_RECEIPT_TIME
IM_SUPPLEMENTARY_RECEIPT_INFO	PR_REPORT_TEXT
The following constant values are mapped from IM_ACKNOWLEDGEMENT_MODE to PR_ACKNOWLEDGEMENT_MODE:

IM_ACKNOWLEDGEMENT_ MODE value	PR_ACKNOWLEDGEMENT_ MODE value
IM_AUTOMATIC	1
IM_MANUAL	0


OMP_O_IM_C_RECIPIENT_SPECIFIER

The attributes of the class OMP_O_IM_C_OR_DESCRIPTOR map to MAPI properties as follows:

MH ID/Type	MAPI Property
IM_IPM_RETURN_REQUESTED	PR_IPM_RETURN_REQUESTED
IM_NOTIFICATION_REQUEST	PR_NON_RECEIPT_NOTIFICATION_ REQUESTED,  PR_READ_RECEIPT_REQUESTED
IM_RECIPIENT	PR_ADDRTYPE, PR_DISPLAY_NAME, PR_EMAIL_ADDRESS, PR_ENTRYID, PR_OFFICE_LOCATION, PR_PRIMARY_TELEPHONE_NUMBER, PR_SEARCH_KEY
IM_REPLY_REQUESTED	PR_REPLY_REQUESTED
The following constant values are mapped from IM_NOTIFICATION_REQUEST to the corresponding MAPI properties:

IM_NOTIFICATION_REQUEST Value	MAPI Values
IM_ALWAYS	PR_NON_RECEIPT_NOTIFICATION_ REQUESTED = TRUE, PR_READ_RECEIPT_REQUESTED  = TRUE
IM_NEVER	PR_NON_RECEIPT_NOTIFICATION_ REQUESTED = FALSE, PR_READ_RECEIPT_REQUESTED  = FALSE
IM_NON_RECEIPT	PR_NON_RECEIPT_NOTIFICATION_ REQUESTED = TRUE, PR_READ_RECEIPT_REQUESTED  = FALSE


OMP_O_IM_C_TELETEX_BD_PRT

The attributes of the class OMP_O_IM_C_TELETEX_BD_PRT are mapped to the following MAPI properties:

MH ID/Type	MAPI Property
IM_TELETEX_COMPATIBLE	Not mapped to a MAPI property.
IM_TELETEX_DOCUMENT	PR_BODY
IM_TELETEX_NBPS	Not mapped to a MAPI property.


OMP_O_IM_C_UNIDENTIFIED_BD_PRT

The attributes of the class OMP_O_IM_C_UNIDENTIFIED_BD_PRT are not mapped to MAPI properties.

MH ID/Type	MAPI Property
IM_UNIDENTIFIED_DATA	Not mapped to a MAPI property.
IM_UNIDENTIFIED_TAG	Not mapped to a MAPI property.


OMP_O_IM_C_USA_NAT_DEF_BD_PRT

The attributes of the class OMP_O_IM_C_USA_NAT_DEF_BD_PRT are mapped to the following MAPI properties:

MH ID/Type	MAPI Property
IM_BODY_PART_NUMBER	Not mapped to a MAPI property.
IM_USA_DATA	Not mapped to a MAPI property.


OMP_O_IM_C_VIDEOTEX_BD_PRT

The attributes of the class OMP_O_IM_C_VIDEOTEX_BD_PRT are not mapped to MAPI properties.

MH ID/Type	MAPI Property
IM_VIDEOTEX_DATA	Not mapped to a MAPI property.
IM_VIDEOTEX_SYNTAX	Not mapped to a MAPI property.


Comprehensive X.400 Attributes Reference

The following table contains mappings between X.400 P2 attributes and MAPI properties, listed in alphabetical order. The name of the object appears in parentheses.

MH ID/Type	MAPI Property
IM_ACKNOWLEDGEMENT_MODE  (OMP_O_IM_C_RECEIPT_NOTIF)	PR_ACKNOWLEDGEMENT_MODE
IM_APPLICATION_PROFILE  (OMP_O_IM_C_ODA_BD_PRT)	Not mapped to a MAPI property.
IM_ARCHITECTURE_CLASS  (OMP_O_IM_C_ODA_BD_PRT)	Not mapped to a MAPI property.
IM_AUTHORIZING_USERS  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_AUTHORIZING_USERS
IM_AUTO_FORWARD_COMMENT  (OMP_O_IM_C_NON_RECEIPT_NOTIF)	PR_AUTO_FORWARD_COMMENT
IM_AUTO_FORWARDED  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_AUTO_FORWARDED
IM_BILATERAL_DATA  (OMP_O_IM_C_BILAT_DEF_BD_PRT)	PR_ATTACH_DATA_BIN
IM_BLIND_COPY_RECIPIENTS  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_DISPLAY_BCC
IM_BODY   (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_BODY
IM_BODY_PART_NUMBER  (OMP_O_IM_C_USA_NAT_DEF_BD_PRT)	Not mapped to a MAPI property.
IM_CHAR_SET_REG  (OMP_O_IM_C_GENERAL_TEXT_BD_PRT)	Not mapped to a MAPI property.
IM_CONVERSION_EITS  (OMP_O_IM_C_INTERPERSONAL_NOTIF)	PR_CONVERSION_EITS
IM_COPY_RECIPIENTS  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_DISPLAY_CC
IM_DISCARD_REASON  (OMP_O_IM_C_NON_RECEIPT_NOTIF)	PR_DISCARD_REASON
IM_ENVELOPE  (OMP_O_IM_C_MESSAGE_BD_PRT)	Not mapped to a MAPI property.
IM_EXPIRY_TIME  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_EXPIRY_TIME
IM_EXTERNAL_DATA  (OMP_O_IM_C_EXTERN_DEF_BD_PRT)	PR_ATTACH_DATA_BIN, PR_ATTACH_FILENAME, PR_ATTACH_TAG
IM_EXTERNAL_PARAMETERS  (OMP_O_IM_C_EXTERN_DEF_BD_PRT)	PR_ATTACHMENT_X400_PARAMETERS
IM_FORMAL_NAME  (OMP_O_IM_C_OR_DESCRIPTOR)	Extract name using PR_ENTRYID; for X.400 address types, build an OR Address from string address.
IM_FREE_FORM_NAME  (OMP_O_IM_C_OR_DESCRIPTOR)	PR_SENDER_NAME for originator, PR_DISPLAY_NAME for recipient, or extract the display name using PR_SENDER_ENTRYID
IM_G3_FAX_NBPS  (OMP_O_IM_C_G3_FAX_BD_PRT)	Not mapped to a MAPI property.
IM_G4_CLASS_1_DOCUMENT  (OMP_O_IM_C_G4_CLASS_1_BD_PRT)	Not mapped to a MAPI property.
IM_IMAGES  (OMP_O_IM_C_G3_FAX_BD_PRT)	Not mapped to a MAPI property.
IM_IMPORTANCE  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_IMPORTANCE
IM_INCOMPLETE_COPY  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_INCOMPLETE_COPY
IM_IPM  (OMP_O_IM_C_MESSAGE_BD_PRT)	Mapped to an IMessageobject embedded in the message.
IM_IPM_INTENDED_RECIPIENT  (OMP_O_IM_C_INTERPERSONAL_NOTIF)	PR_ORIGINALLY_INTENDED_RECIPIENT_NAME
IM_IPM_RETURN_REQUESTED  (OMP_O_IM_C_OR_DESCRIPTOR)	PR_IPM_RETURN_REQUESTED
IM_IPN_ORIGINATOR  (OMP_O_IM_C_INTERPERSONAL_NOTIF)	PR_CALLBACK_TELEPHONE_NUMBER, PR_SENDER_ADDRTYPE, PR_SENDER_EMAIL_ADDRESS, PR_SENDER_ENTRYID, PR_SENDER_NAME, PR_SENDER_SEARCH_KEY (and all PR_SENT_REPRESENTING_ * properties)
IM_LANGUAGES  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_LANGUAGES
IM_MIXED_MODE_DOCUMENT  (OMP_O_IM_C_MIXED_MODE_BD_PRT)	Not mapped to a MAPI property.
IM_NATIONAL_DATA  (OMP_O_IM_C_NATIONAL_DEF_BD_PRT)	Not mapped to a MAPI property.
IM_NON_RECEIPT_REASON  (OMP_O_IM_C_NON_RECEIPT_NOTIF)	PR_NON_RECEIPT_REASON
IM_NOTIFICATION_REQUEST  (OMP_O_IM_C_OR_DESCRIPTOR)	PR_NON_RECEIPT_NOTIFICATION_REQUESTED,  PR_READ_RECEIPT_REQUESTED
IM_OBSOLETED_IPMS  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_OBSOLETED_IPMS
IM_ODA_DOCUMENT  (OMP_O_IM_C_ODA_BD_PRT)	Not mapped to a MAPI property.
IM_ORIGINATOR  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_CALLBACK_TELEPHONE_NUMBER, PR_SENDER_ADDRTYPE, PR_SENDER_EMAIL_ADDRESS, PR_SENDER_ENTRYID, PR_SENDER_NAME, PR_SENDER_SEARCH_KEY (and all PR_SENT_REPRESENTING_* properties)
IM_PRIMARY_RECIPIENTS  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_DISPLAY_TO
IM_RECEIPT_TIME  (OMP_O_IM_C_RECEIPT_NOTIF)	PR_RECEIPT_TIME
IM_RECIPIENT  (OMP_O_IM_C_OR_DESCRIPTOR)	PR_ADDRTYPE, PR_DISPLAY_NAME, PR_EMAIL_ADDRESS, PR_ENTRYID, PR_OFFICE_LOCATION, PR_PRIMARY_TELEPHONE_NUMBER, PR_SEARCH_KEY
IM_RELATED_IPMS  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_RELATED_IPMS
IM_REPERTOIRE  (OMP_O_IM_C_IA5_TEXT_BD_PRT)	Not mapped to a MAPI property.
IM_REPERTOIRE  (OMP_O_IM_C_ISO_6937_TEXT_BD_PRT)	Not mapped to a MAPI property.
IM_REPLIED_TO_IPM  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_PARENT_KEY
IM_REPLY_RECIPIENTS  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_REPLY_RECIPIENT_ENTRIES, PR_REPLY_RECIPIENT_NAMES
IM_REPLY_REQUESTED  (OMP_O_IM_C_OR_DESCRIPTOR)	PR_REPLY_REQUESTED
IM_REPLY_TIME  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_REPLY_TIME
IM_RETURNED_IPM  (OMP_O_IM_C_NON_RECEIPT_NOTIF)	(Object; no corresponding property)
IM_SENSITIVITY  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_SENSITIVITY
IM_SUBJECT  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_NORMALIZED_SUBJECT, PR_SUBJECT, PR_SUBJECT_PREFIX
IM_SUBJECT_IPM  (OMP_O_IM_C_INTERPERSONAL_NOTIF)	PR_ORIGINAL_SEARCH_KEY
IM_SUPPLEMENTARY_RECEIPT_INFO  (OMP_O_IM_C_RECEIPT_NOTIF)	PR_REPORT_TEXT
IM_TELEPHONE_NUMBER  (OMP_O_IM_C_OR_DESCRIPTOR)	PR_CALLBACK_TELEPHONE_NUMBER for Originator, PR_PRIMARY_TELEPHONE_NUMBER for Recipient
IM_TELETEX_COMPATIBLE  (OMP_O_IM_C_TELETEX_BD_PRT)	Not mapped to a MAPI property.
IM_TELETEX_DOCUMENT  (OMP_O_IM_C_TELETEX_BD_PRT)	PR_BODY
IM_TELETEX_NBPS  (OMP_O_IM_C_TELETEX_BD_PRT)	Not mapped to a MAPI property.
IM_TEXT  (OMP_O_IM_C_GENERAL_TEXT_BD_PRT)	Not mapped to a MAPI property.
IM_TEXT  (OMP_O_IM_C_IA5_TEXT_BD_PRT)	PR_BODY
IM_TEXT  (OMP_O_IM_C_ISO_6937_TEXT_BD_PRT)	PR_ATTACH_DATA_BIN
IM_THIS_IPM  (OMP_O_IM_C_INTERPERSONAL_MSG)	PR_SEARCH_KEY
IM_UNIDENTIFIED_DATA  (OMP_O_IM_C_UNIDENTIFIED_BD_PRT)	Not mapped to a MAPI property.
IM_UNIDENTIFIED_TAG  (OMP_O_IM_C_UNIDENTIFIED_BD_PRT)	Not mapped to a MAPI property.
IM_USA_DATA  (OMP_O_IM_C_USA_NAT_DEF_BD_PRT)	Not mapped to a MAPI property.
IM_USER, IM_USER_RELATIVE_IDENTIFIER  (OMP_O_IM_C_IPM_IDENTIFIER)	Construct a GUID from IM_USER_RELATIVE_IDENTIFIER
IM_VIDEOTEX_DATA  (OMP_O_IM_C_VIDEOTEX_BD_PRT)	Not mapped to a MAPI property.
IM_VIDEOTEX_SYNTAX  (OMP_O_IM_C_VIDEOTEX_BD_PRT)	Not mapped to a MAPI property.


A

address book

A MAPI object that manages a collection of one or more types of recipient available to a client application. A recipient can be a messaging user or a distribution list. The recipients are stored in address book containers that are organized hierarchically. At a given workstation an address book includes recipients from every address book container furnished by every address book provider in the current profile. Address books implement the IAddrBook : IMAPIProp interface.

address book container

A MAPI object that contains recipient information furnished by an address book provider. Address book containers implement the IABContainer : IMAPIContainer interface.

address book provider

A MAPI service provider object that manages zero or more address book containers, enabling users to address messages and create recipients. An address book provider can furnish containers or templates or both. A fax address book provider, for example, typically furnishes messaging user and distribution list templates but no containers. Address book providers implement the IABContainer : IMAPIContainer, IABLogon : IUnknown, IABProvider : IUnknown, IDistList : IMAPIContainer, and IMailUser : IMAPIProp interfaces. See also address book container, container, message, template. For more information, see Developing an Address Book Provider.

address properties

A fundamental set of five properties for every recipient that describes the recipient’s e-mail address and address type, display name, entry identifier, and search key. For more information, see Base Address Properties.

advise sink

A MAPI object that registers for and receives notifications of specific events in other objects. The notification of an event is asynchronous to the event itself, that is, it is communicated at an indeterminate time following the event, and the object generating the event does not wait for any response to the notification. An advise sink provides a callback function for events that occur in a message store, address book, or session. Advise sinks implement the IMAPIAdviseSink : IUnknown interface.

ambiguous name resolution

(ANR) See name resolution.

application form library

A form library that supplies forms to a particular workstation. Forms installed in an application form library are available to every MAPI client application on that workstation, regardless of what message store or profile is currently active. See also folder form library, personal form library.

ASN

(Abstract Syntax Notation) An ISO standard for encoding of human-readable symbols, such as header tags, into condensed binary form. ASN.1 corresponds to CCITT standards X.208 (for the notation) and X.209 (for the encoding rules). In turn it forms part of the specifications for the X.400 and X.500 series of standards, as well as for various other specifications.

associated contents table

A table of information associated with a folder and normally stored in the “hidden” or associated part of that folder. It typically contains forms that are installed into the folder and view descriptors that are associated with the folder. See also associated information, contents table, form, standard contents table, view descriptor.

associated information

Additional information kept in a folder with a specific purpose for a client application, such as a view or a form definition. Associated information is typically not visible to the user. See also associated contents table.

attachment

A MAPI object that contains additional data, such as a file or OLE object, associated with a message. Attachments implement the IAttach : IMAPIProp interface.

attachment table

A MAPI table object that provides access to information about a message’s attachments. Each row represents a message attachment.


B

bookmark

A marker that identifies a position within a table.


C

canonical form

A conventional and normalized form of any entity, such as an address, phone number, or identifier, that could exist or be presented in several different forms. An entity’s canonical form is regarded as the most straightforward of its possible forms and the one that best facilitates interactions with other entities of the same type, particularly comparisons. In MAPI, canonical form is most often applied to e-mail addresses.

CCITT

The International Telegraph and Telephone Consultative Committee, an international standards committee and division of the United Nations that defines standards, such as the Electronic Data Interchange (EDI) data standard. Now called the International Telecommunications Union (ITU). CCITT stands for Comite Consultatif International Telegraphique et Telephonique, the committee’s original French name. See also X.400, X.435, X.500.

client

See client application.

client application

A program that enables its user to interact with an underlying messaging system by calling functions or interface methods implemented by the MAPI subsystem or a service provider. These functions and methods are known collectively as the client interface. See also messaging application, service provider interface.

client extension

A program component that adds to the feature set of a client application, for example a handler for custom commands. Client extensions implement the IExchExt : IUnknown interface or one of its sibling interfaces. For more information, see Interfaces for Extending the Microsoft Exchange Client.

client interface

The set of interfaces and functions used by a client application. The client interface has four components: MAPI, Simple MAPI, Common Messaging Calls (CMC), and the OLE Messaging Library. The last three components are layers between the client application and the MAPI component, and they make calls to MAPI. The client interface can use one or more of these four components in any combination. For more information, see Selecting a Client Interface.

CMC

See Common Messaging Calls.

common dialog box

A Microsoft Windows dialog box that is provided with the MAPI SDK. A client application uses common dialog boxes to promote an appearance both consistent within the application and consistent with other Windows-based applications. See also dialog box.

common extension set

A predefined set of Common Messaging Calls data extensions. The common extension set includes the extensions most frequently used in messaging systems and in CMC implementations, but which are not in the CMC base specification itself.

Common Messaging Calls

(CMC) A set of functions that is based upon the standard developed by the X.400 Application Programming Interface Association (XAPIA) and that is a component of the MAPI client interface. CMC is a cross-platform function set that enables a client application to be independent of the actual messaging system, operating system, and hardware used. It provides a layer between the client application and the MAPI client interface component. See also Simple MAPI, OLE Messaging Library.

Common Messaging Calls data extension

A data structure that is used to add features to Common Messaging Calls (CMC) functions and structures. Data extensions can add members to existing data structures or parameters to existing CMC functions.

compound entry identifier

An entry identifier that is created by combining the entry identifier of a message store and the entry identifier of a message within the store. Compound entry identifiers are used by a client application to open messages from a nondefault message store provider. MAPI, Simple MAPI, and Common Messaging Calls applications can all use compound entry identifiers.

configuration file

A formatted file used to store a user’s choices of names, features, limits, and other information that can vary among installations. See also form configuration file, MAPI configuration file.

connection number

A number that uniquely identifies an individual registration for a notification. A client application uses this number to cancel its registration.

container

A MAPI object that holds one or more other MAPI objects. Examples of containers are address book containers, distribution lists, and folders. Containers implement the IMAPIContainer : IMAPIProp interface. See also address book container, distribution list, folder, form container.

contents table

A MAPI table object that provides access to a summary view of entries in a folder or in an address book container. Each row represents a folder, a message, or a recipient, depending on which provider is implementing the table. See also associated contents table, standard contents table.

control

A MAPI object acting as a user interface (UI) for a property. A control appears as an element in a dialog box, where its value can be inspected and possibly changed by the user. For more information, see Display Table Controls.

conversation thread

A series of messages that pertain to the same topic. The topic is held in the PR_CONVERSATION_TOPIC property of each message in the thread. This property and the PR_CONVERSATION_INDEX property facilitate sorting of messages by threads.

custom message

A message with a message class other than those defined by MAPI. A custom message is created and displayed with a special purpose form server rather than with the standard send note or read note form. For more information on message class values, see PR_MESSAGE_CLASS. For more information on custom messages and form servers, see Choosing a Message Class.

custom recipient

See one-off address.

custom recipient entry identifier

See one-off entry identifier.

custom recipient table

See one-off table.

custom recipient template entry identifier

See one-off template entry identifier.


D

data extension

See Common Messaging Calls data extension.

DBCS

(Double-Byte Character Set) A mapping of a collection of characters to a set of values each of which can be either one or two bytes. Commonly used for encoding languages requiring more than 256 characters, such as Japanese Kanji. See also Unicode.

default profile

Configuration information about a session’s set of message services, with which a client application logs on if no other such configuration information is specified. See also message service, profile, session.

delegate access

The ability of one messaging user to send or receive messages on behalf of another user and to access that other user’s message store. The messaging users in a delegation are commonly human users, but either the delegator or the delegate could be a software application.

Deleted Items folder

A folder within the interpersonal message (IPM) subtree that is designated to hold messages marked for deletion. Also referred to as the wastebasket. See also IPM subtree.

delivery report

(DR) A report message sent to a message sender that indicates the message has been delivered to a particular recipient. A delivery report can be generated by the MAPI spooler, a message transfer agent, or a transport provider. The recipient may or may not have read the message.

dialog box

A window displayed in the user interface (UI) to solicit input from the user. It contains one or more controls. A dialog box and its controls are governed by a display table.

disk instance

A temporary file that contains executable files for a form if those executable files are not yet resident on the user’s local disk. A disk instance is created any time a form is loaded from a form library.

display name

A character string that represents a MAPI object in the user interface (UI). Service providers assign display names to their objects by setting each object’s PR_DISPLAY_NAME property.

display table

A MAPI table object that describes the layout of a dialog box. Each row in the table represents a control in the dialog box. Each column in the table holds data about one property of the control, such as its location, size, or type. A display table is used to display details of a messaging user, a distribution list, or a container. It can also be used to display and edit configuration parameters for a service provider.

distribution list

A MAPI object that identifies a grouping of message recipients. A distribution list can contain individual messaging users and other distribution lists. Distribution lists implement the IDistList : IMAPIContainer interface. See also messaging user, recipient.

domain

See messaging domain.

dynamic table

A table that changes as the underlying data changes. Attachment tables and message store tables are examples of dynamic tables. See also static table.


E

Electronic Data Interchange

(EDI) A standard for integrating data with various native formats into a message, which has been defined by the International Telegraph and Telephone Consultative Committee (CCITT) standards body, now called the International Telecommunications Union (ITU), and is implemented in the X.435 message-handling standard.

entry identifier

A binary value that distinguishes a MAPI object from other objects of the same type and permits clients and providers to open and access the object. Part of the entry identifier represents the service provider that defines the object, and part represents the individual object. Entry identifiers allow the MAPI subsystem to determine which service provider should handle a particular object. An object’s entry identifier is stored in its PR_ENTRYID property. See also compound entry identifier, one-off entry identifier, one-off template entry identifier, long-term entry identifier, short-term entry identifier, record key, search key.

entry point function

A function in a message service dynamic-link library (DLL) called by MAPI at logon time for configuration purposes. For more information, see About Message Service Entry Point Functions.

event

A change in an object’s state that can generate a notification, such as a critical error occurring or the object being modified.

event mask

A bitmask that is used to indicate one or more types of event notifications. Advise sink objects register for specific notifications using the event mask. See also advise sink, notification.

extension

See client extension, Common Messaging Calls data extension.


F

folder

A message store container object that holds messages and other folders. MAPI folders implement the IMAPIFolder : IMAPIContainer interface. See also header folder, IPM subtree, receive folder, root folder, search-results folder.

folder form library

A form library that supplies forms to a particular folder. Forms installed in a folder form library are available to every user of that folder. See also application form library, personal form library.

foreign system

An X.400 messaging term indicating a messaging system outside the messaging domain of the local X.400 network.

form

A MAPI object that enables a user of a client application to interact with a message of a particular message class. User interaction is controlled by a form server application and is based on MAPI properties corresponding to controls on the form. Form objects implement the IMAPIForm : IUnknown and IMAPIFormInfo : IMAPIProp interfaces.

form activation

The process of starting a form server to enable a user to work with a particular form within a client application.

form configuration file

A configuration file that defines a form and provides information for installing it into a form library using the IMAPIFormContainer::InstallForm method. Form configuration files must have the .CFG filename extension. See also Form Configuration File Format.

form container

A MAPI object that stores form definitions. A form container can be used to locate a form definition and to activate the appropriate form server. Form containers implement the IMAPIFormContainer : IUnknown interface. See also form resolution.

form library

A form container as seen through the user interface (UI). MAPI distinguishes several types of form library, including the application form library, folder form library, and personal form library.

form library provider

A MAPI service provider object that manages one or more form libraries. Like most service providers it is a dynamic-link library (DLL). Form library providers implement the IMAPIFormContainer : IUnknown, IMAPIFormInfo : IMAPIProp, and IMAPIFormMgr : IUnknown interfaces. See also form.

form resolution

The process of mapping the message class of a particular message to the class identifier of the form server for that message, and of locating the form for that message in the appropriate form container. Form resolution determines which piece of code should be activated to manage interaction with a particular message.

form server

An application that manages a user’s interaction with a form, for example responding to menu commands. Form servers implement the IMAPIForm : IUnknown, IMAPIFormAdviseSink : IUnknown, IMAPIFormFactory : IUnknown, and IPersistMessage : IUnknown interfaces, and can optionally implement the IMAPIViewAdviseSink : IUnknown interface. See also form viewer. For more information, see Developing MAPI Form Servers.

form viewer

A client application that is capable of launching a form. Form viewers implement the IMAPIMessageSite : IUnknown, IMAPIViewAdviseSink : IUnknown, and IMAPIViewContext : IUnknown interfaces. See also form server.

fuzzy level

A value that describes the degree of exactness or looseness desired when searching through a container for a target string. Lower levels of fuzziness indicate more exact matching. Higher levels return matches for more varied forms of the target string and usually require more execution time.


G

GAL

See global address list.

gateway

Software that links two or more dissimilar messaging systems, that is, systems that use different transport protocols. A gateway provides address translation and protocol and storage conversion. See also messaging system, messaging domain.

global address list

(GAL) A MAPI address book container that holds recipient entries for an entire organization and is available to all e-mail users in that organization.


H

hands-off state

A condition in which a form’s storage object is unavailable for either read or write access. A form is placed in the hands-off state during a save operation to permanent storage. See also uninitialized state, normal state, no-scribble state. For more information, see Form States.

header folder

A special folder exposed by a remote transport provider. A client application can open the header folder to view only the message headers at the remote message store and decide for each message whether it is worth downloading for reading or can simply be deleted at the remote site.

hierarchy table

A MAPI table object that provides access to the tree organization of a MAPI container. Each row represents the hierarchical position of a container held within the parent container. For example, a hierarchy table is used by message store providers to display the folder hierarchy.

hook

See messaging hook provider.

hook provider

See messaging hook provider.


I

IID

See interface identifier.

Inbox

A folder within the interpersonal message (IPM) subtree that is designated as the default destination for incoming messages. See also IPM subtree, receive folder.

information service

See message service.

interface

A collection of related methods exposed by a given class of objects. There is normally a one-to-one correspondence between an object class and an interface, for example address book objects and the IAddrBook interface. All interfaces inherit either directly or indirectly from IUnknown. See also MAPI interface.

interface identifier

(IID) A constant that represents a particular interface and is used to request a pointer to the interface in order to call its methods. For example, the IID for the IAddrBook interface is IID_IAddrBook. Interface identifiers are defined using the IID structure, which is a specialized GUID structure.

International Telecommunications Union

(ITU) See CCITT.

interpersonal message

(IPM) A message that is sent or received by a human user rather than an application or process. Interpersonal messages have message class IPM.Note. See also IPC message, non-IPM message.

interprocess communication

(IPC) The exchange of data between two or more processes or applications. This exchange takes place solely through software, without any human intervention.

IPC message

A message that is sent and received by interprocess communication rather than by human users. See also interpersonal message, non-IPM message.

IPM

See interpersonal message.

IPM subtree

(interpersonal message subtree) An area of a folder hierarchy reserved by MAPI for interpersonal message (IPM) applications. Only information stored within the IPM subtree is visible to IPM users. Folders are commonly created to handle incoming, outgoing, sent, and deleted interpersonal messages. These, together with any other folders created for IPM usage, constitute a subtree of the message store which can be accessed through the message store’s PR_IPM_SUBTREE_ENTRYID property. The default names for the common folders are the Inbox, Outbox, Sent Items folder, and Deleted Items folder.


K

key

A binary value associated with a MAPI object that can be compared with another binary value for the purpose of determining the relationship between the objects. Commonly used keys include the record key and the search key.


L

local message store

A message store provider that keeps its data on the user’s local disk.

logon

The process by which a messaging user establishes a session with a messaging system through the MAPI subsystem. Logon typically involves the verification of the user’s name and password and the user’s selection of a valid profile. A user can log on to more than one messaging system at the same time.

logoff

The process by which a messaging user ends a session with the MAPI subsystem and the messaging system or systems it was logged on to.

long-term entry identifier

An entry identifier associated permanently with a MAPI object and unique in a global scope. It is stored with the object and in other appropriate places so that it can be used for multiple operations. See also short-term entry identifier.


M

mail user

See messaging user.

MAPI

(Messaging Application Programming Interface) A messaging architecture and a client interface component.

As a messaging architecture, MAPI enables multiple applications to interact with multiple messaging systems across a variety of hardware platforms. See also MAPI subsystem, messaging system.

As a client interface component, MAPI is the complete set of functions and object-oriented interfaces that forms the foundation for the MAPI subsystem’s client application and service provider interfaces. In comparison with Simple MAPI, Common Messaging Calls (CMC), and the OLE Messaging Library, MAPI provides the highest performance and greatest degree of control to messaging-based applications and service providers.

MAPI configuration file

A configuration file, MAPISVC.INF, that contains information about every message service and service provider installed on a workstation. For more information, see Message Services and Profiles.

MAPI interface

A set of related methods that describe the behavior of a MAPI object. All MAPI interfaces derive from the OLE base interface, IUnknown.

MAPI object

An object that supports the OLE Component Object Model (COM), implementing one or more interfaces derived from the IUnknown interface. It is implemented or used by a MAPI compliant service provider or client application, or by MAPI itself.

MAPI spooler

A MAPI process that handles the sending and receiving of messages between client applications and most messaging systems. A tightly coupled message store and transport provider does not use the spooler. See also client application, messaging system.

MAPI subsystem

The set of dynamic-link libraries (DLLs) provided by MAPI that enable interaction between client applications and service providers. The MAPI subsystem DLLs implement the MAPI spooler, the client interface, the service provider interface, and the support object.

message

A MAPI object containing information that can be sent to one or more recipients by means of a messaging system, or posted to a public folder. The principal parts of a message are the message content and the message envelope. Messages implement the IMessage : IMAPIProp interface. See also message text, post, recipient.

message body

See message text.

message class

A character string property that is assigned to every MAPI message, identifying the type of the message. The message class determines behavior such as selecting the appropriate receive folder and launching a form for the message. Message class strings are stored in the PR_MESSAGE_CLASS property.

message content

The portion of a message representing the information the sender wishes to communicate to each recipient. The message content includes the message text and any attachment objects. It excludes the message envelope. Messages of the same message class are expected to have similar content structure.

message envelope

The portion of a message used for routing and delivery to each recipient. The message envelope includes the address properties for each recipient, header information such as the sender and subject, and specifications for responding and exception handling. It excludes the message content. See also message text.

message identifier

An ASCII string used by Simple MAPI to access an incoming message. A message identifier is valid only during the session in which it is assigned a value by the MAPIFindNext function, and does not correspond to the message reference used by CMC. For more information, see Receiving a Message: Simple MAPI Sample.

message preprocessor

A dynamic-link library (DLL) that runs on a client workstation and operates on outbound messages before they are given to any transport provider. For example, a message preprocessor might make a local copy of every outgoing message. A message preprocessor can be called selectively based on each recipient’s address type or entry identifier. Also referred to as a preprocessor. See also messaging hook provider. For more information, see Developing a Hook Provider or Preprocessor.

message reference

A counted string structure used by CMC to access a message within a mailbox. A message reference is valid only during the session in which it is assigned a value by the cmc_list function, and does not correspond to the message identifier used by Simple MAPI.

message service

A group of one or more related service providers installed and configured by a single body of code. For example, CompuServe might furnish an address book provider, message store provider, and transport provider all designed to interface with the CompuServe message service. For more information, see Message Services and Profiles.

message service table

A MAPI table object that provides access to information about every message service in the current profile, such as the service’s name, service providers, and associated files.

message site

A MAPI object that handles the manipulation of form objects. Message site objects implement the IMAPIMessageSite : IUnknown interface.

message store

A MAPI object that contains messages and folders organized hierarchically and that implements the IMsgStore : IMAPIProp interface. See also folder, message.

message store provider

A MAPI service provider object that manages a message store, handling message distribution, organization, and storage. Message store providers implement the IAttach : IMAPIProp, IMAPIFolder : IMAPIContainer, IMessage : IMAPIProp, IMsgStore : IMAPIProp, IMSLogon : IUnknown, and IMSProvider : IUnknown interfaces. For more information, see Developing a Message Store Provider.

message store table

A MAPI table object that provides access to information about every message store in the current profile.

message text

The principal content of an interpersonal message, that is, a message of message class IPM.Note. Message text can optionally be used in other message classes. It is the main portion of the message content, typically displayed to each recipient as an immediate result of opening the message. It excludes any attachment objects. Also referred to as the message body.

message transfer agent

(MTA) The X.400 term for the part of a message transfer system (MTS) that interfaces with clients of that MTS. A MAPI transport provider commonly interfaces with a message transfer agent.

message transfer system

(MTS) The X.400 term for a messaging system.

messaging application

A program that uses the MAPI client interface to pass messaging requests, such as requests to send and receive messages, to and from a messaging system. A messaging application is a type of client application.

messaging domain

A collection of interconnected messaging users that share a common addressing scheme and transport protocol. Communication with a messaging user in the same messaging domain does not involve reformatting or address translation. Communication with a messaging user in another messaging domain typically requires the use of a gateway. Also referred to as a domain or a site.

messaging hook provider

A MAPI service provider object that runs on the same machine as the MAPI spooler and performs special processing on inbound and outbound messages. Messaging hook providers implement the ISpoolerHook : IUnknown interface. A messaging hook provider can be called for all inbound messages, all outbound messages, or both. Also referred to as a spooler hook or a hook provider. See also message preprocessor. For more information, see Developing a Hook Provider or Preprocessor.

messaging service

See message service.

messaging system

A product that enables electronic communication over a network, such as fax, CompuServe, or the Internet. Typical clients of a messaging system include an individual computer with a modem and a local area network with a gateway.

messaging transport provider

See transport provider.

messaging user

 A MAPI object that describes an individual recipient of a message. Messaging users implement the IMailUser : IMAPIProp interface. See also distribution list.

MIME

(Multipurpose Internet Mail Extensions) A set of enhancements to SMTP allowing an Internet message to include a mixture of audio, image, video, and text components, and to accommodate a variety of international character sets. MIME messages are identified by a MIME header in the top level of the SMTP header. The MIME mechanisms are specified in the RFC 1341 document.

MTA

See message transfer agent.

MTS

See message transfer system.

multivalued property

A property that can contain many values of the same type. Its property type has MV_FLAG set, and its property value contains multiple values of the specified property type. See also single-valued property. For more information, see About Property Types.


N

name resolution

The process of associating a string with a valid address for a particular messaging system. An unresolved name lacks an entry identifier. The names of all recipients for a message must be resolved before the message can be sent. See also recipient, resolved recipient, unresolved recipient.

name space

The set of all possible named property names within a property set. The GUID that is part of each property’s name is unique to each property set and guarantees that no property names from different name spaces can be the same.

named property

A user-defined property whose principal designation is by a unique name rather than by a property identifier. Because of name-identifier mapping, a named property is valid in any messaging domain and any session. Every named property belongs to a property set, each member of which uses the same GUID for the first part of its name. For more information, see Named Properties.

name-identifier mapping

A bidirectional, persistent one-to-one mapping between the name and the property identifier of a named property. Name-identifier mapping is provided by certain implementations of the IMAPIProp::GetIDsFromNames and IMAPIProp::GetNamesFromIDs methods. For more information, see Supporting Named Properties.

NDR

See nondelivery report.

no-scribble state

A condition in which a form’s storage object is available only for read access; write access is prohibited. A form is placed in the no-scribble state during a save operation to enable the operation to finish uninterrupted. See also uninitialized state, normal state, hands-off state. For more information, see Form States.

non-IPM message

(non-interpersonal message) A message that is meant to be sent or received by an application rather than by a human user, such as a notification from a workgroup scheduling application or an IPC message. See also interpersonal message.

nondelivery report

(NDR) A report message sent to a message sender that indicates the message could not be delivered to a particular recipient. A nondelivery report can be generated by the MAPI spooler, a message transfer agent, or a transport provider. Many situations can cause nondelivery reports to be generated, such as an inaccurate recipient address, unavailable transport providers, or an inoperative network.

nonread notification

(NRN) See nonread report.

nonread report

(NRN) A report message from a message store provider to a message sender that indicates the message was not read by a particular recipient, that is, the client application did not display the message contents to the recipient before the recipient deleted the message or before a specified expiration time.

nontransmittable property

A property that is not sent along with the message it is associated with. Nontransmittable properties are typically those that apply only in the sending environment, such as PR_DELETE_AFTER_SUBMIT, or only in the receiving environment, such as PR_HASATTACH. See also transmittable property.

normal state

A condition in which a form’s storage object is available for both read and write access. A form is typically in the normal state unless a save or close operation is in process. See also uninitialized state, no-scribble state, hands-off state. For more information, see Form States.

notification

A communication advising a MAPI object of the occurrence of an event in another MAPI object. The notification is asynchronous to the event, that is, it is communicated at an indeterminate time following the event, and the object generating the event does not wait for any response to the notification. The object receiving the notification is referred to as the advise sink. Advise sinks register for notification of specific events in an object, such as critical errors, by calling that object’s Advise method. See also registration.


O

OID

(object identifier) A value specifying the nature of an X.400 object. MAPI uses OIDs for various purposes, such as indicating the types of attached files. “Object” is a much more generalized concept in X.400 than in object-oriented programming. It can mean an algorithm, application, body part type, character set, external parameter, or message type, among other things. Also, it usually refers to a class of things, such as CRC-32, rather than one particular implementation of a 32-bit CRC (cyclic redundancy code).

OLE Messaging Library

An OLE Automation programming interface that is a component of the MAPI client interface and is used primarily by Visual Basic and Visual C and C++ client application developers. The OLE Messaging Library furnishes programmable objects, like Microsoft Excel objects and Microsoft Access objects, that make available properties and methods that can then be managed by Visual Basic (VB) and Visual Basic for Applications (VBA) programs. It provides a layer between the client application and the MAPI client interface component. See also Simple MAPI, Common Messaging Calls.

OLE Messaging collection

An object that contains zero or more OLE Messaging objects of the same type. The OLE Messaging Library supports two types of collections: large collections and small collections. With large collections, you can use the object’s methods to get the first, next, last, and previous items within the collection. With small collections, you can access all items in the collection using an implied index.

OLE Messaging object

An object contained in the OLE Messaging Library, such as a session object, folder object, or message object, that exposes properties and methods. See the OLE Messaging Library documentation in the MAPI SDK.

one-off

British jargon for something that is used only once and not retained permanently. Also referred to as one-shot.

one-off address

A messaging address that represents a recipient that is not in the current address book. A one-off address is created by a client application or a service provider, either by presenting a complete address string for name resolution or by using a template supplied by an address book provider. An address string without an explicit address type is assumed to be an Internet address. Also referred to as a custom recipient. See also one-off template entry identifier.

one-off entry identifier

An entry identifier created from a one-off address and a display name. Also referred to as a custom recipient entry identifier. For more information, see Address Book Identifiers.

one-off table

A MAPI table object that provides access to information about supported one-off templates. Also referred to as a custom recipient table.

one-off template

A template for creating a one-off address.

one-off template entry identifier

An entry identifier held in an address book provider’s one-off table and used to access a one-off template for creating a one-off address. Also referred to as a custom recipient template entry identifier. For more information, see Address Book Identifiers.

Outbox

A folder within the interpersonal message (IPM) subtree that is designated to hold outgoing messages until they are sent. See also IPM subtree.


P

PAB

See personal address book.

personal address book

(PAB) A modifiable MAPI address book container that holds recipient entries either created by the user or copied from other address book containers. Each session can optionally designate a container to act as the PAB. Personal address book objects are commonly contained in files with the .PAB filename extension.

personal folders

A personal message store as seen through the user interface (UI).

personal form library

A form library that supplies forms to a particular client application. Forms installed in a personal form library reside in a hidden folder of the default message store and are available only to the creating client application. See also application form library, folder form library.

personal message store

(PST) A MAPI message store object that is created by a user and is stored in a file with the .PST filename extension.

post

The action of storing a message in a publicly known location such as a public folder. A message is posted for the purpose of making a single copy widely available for reading by human users or processing by an application.

preprocessor

See message preprocessor.

primary identity

An object, commonly an address book entry, that represents the user of a MAPI session. The primary identity is supplied by a service provider and exposed in the properties PR_IDENTITY_ENTRYID, PR_IDENTITY_SEARCH_KEY, and PR_IDENTITY_DISPLAY.

probe

An X.400 messaging term indicating a message that has a specific message class identifier but no content. A probe is used by X.400 message senders to determine whether a message of a particular message class can be sent to a particular recipient, and if so, how.

profile

Configuration information about the set of message services for a session. Profiles are created from information stored in the MAPI configuration file, MAPISVC.INF. A profile can be modified by MAPI, a service provider, or a MAPI configuration interface. See also message service.

profile name

A text string that identifies a particular profile.

profile provider

A MAPI service provider object that manages one or more profile sections. Profile providers implement the IProfSect : IMAPIProp interface. See also profile.

profile section

A MAPI object providing access to the configuration information of a service provider or message service. A profile section can contain information provided or used by MAPI, a message service, a service provider, or a client application.

profile table

A MAPI table object that provides access to the name of every profile on a particular computer.

property

A data attribute of a MAPI object that implements the IMAPIProp : IUnknown interface. Such an object exposes its defined properties to other objects that call IMAPIProp. The same property can be defined on more than one type of MAPI object. The information that designates a MAPI property is contained in its property tag. The property’s actual data contents are held in its property value. See also named property. For more information, see Properties.

property identifier

A unique 16-bit integer value that identifies a particular property. The property identifier is contained in the high-order 16 bits of the property tag. See also named property. For more information, see About Property Identifiers.

property page

One section or page of a property sheet, accessed by selecting one of the property sheet tabs.

property set

A group of named properties specified by a GUID. Each named property in the set has the GUID as part of its name, so the GUID identifies a name space. A property set can be user-defined, in which case there is no restriction on the individual property names. In a MAPI-defined name space such as PS_PUBLIC_STRINGS, names must be selected that do not conflict with existing names. For more information, see Property Names and Property Sets.

property sheet

A common dialog box that is used to display configuration information to the user and to enable the user to modify that information. A property sheet contains a collection of one or more property pages.

property tag

A 32-bit unsigned integer value that contains the unique identifier and type of a property. The high-order 16 bits contain the property identifier, and the low-order 16 bits contain the property type. See also named property, property value. For more information, see About Property Tags.

property type

A 16-bit integer value that describes the data type for a property and whether it can contain a single value or multiple values. The property type is contained in the low-order 16 bits of the property tag. For more information, see About Property Types.

property value

The current data contents of a property. A property value can consist of a single item of data or multiple items of data. See also multivalued property, single-valued property, property tag. For more information, see SPropValue.

provider

See service provider.

provider table

A MAPI table object that provides access to information about every currently loaded service provider.

proxy address

A non-native e-mail address for a recipient, that is, an address meaningful outside of the recipient’s messaging domain, such as an Internet or fax address.

PST

See personal message store.

public folder

One of a set of folders made available by a message store and visible to every messaging user that logs on to that message store.


R

read flag

A flag setting, MSGFLAG_READ, that is used in the PR_MESSAGE_FLAGS property of a message to mark it as having been read. The read flag can be set in a variety of situations, including opening, printing, and copying of the message. The read flag being set does not necessarily indicate that the message has been physically read by a human user or acted upon by an application.

read notification

(RN) See read report.

read receipt

See read report.

read report

(RN) A report message from a message store provider to a message sender that indicates the read flag has been set for the message by a particular recipient. A read report can be sent in a variety of situations; its being sent does not guarantee the intended recipient has physically read the message.

receive folder

A MAPI folder object that is designated as the destination for any incoming message belonging to a particular message class. Typically, the receive folder is the Inbox in the interpersonal message (IPM) subtree. See also IPM subtree.

recipient

A user or group of users designated to receive a particular message. A recipient can be a messaging user, distribution list, or one-off address.

recipient list

A collection of recipients associated with a message. A recipient list can contain zero or more recipients of any type, in any combination, and in any order.

recipient table

A MAPI table object that provides access to information about the recipient list of a message. Each row in the table contains information about one recipient.

record key

A binary value that can be directly compared with other record keys to help find references to a MAPI object. An object’s record key is stored in its PR_RECORD_KEY property. See also search key, entry identifier.

registration

A request on the part of a client application or MAPI to receive notifications about a specific type of event. See also notification.

registry provider

See form library provider.

report

A message sent to a recipient providing the status of a message that recipient had originated and sent. A report can be generated by a service provider, a messaging system component, or the MAPI subsystem. See also delivery report, nondelivery report, read report, nonread report.

resolution

See form resolution, name resolution.

resolved recipient

A messaging user or distribution list that has been assigned an entry identifier and an address for a particular messaging system. See also name resolution, unresolved recipient.

restriction

A set of criteria imposed against a table to filter the rows of the table, limiting a user’s view of the table’s data to only those rows that meet the criteria.

root folder

The MAPI folder object that appears at the top of a message store’s folder hierarchy. Only one root folder can exist in a message store. Root folders are invisible to the user because of their inability to be moved, copied, renamed, or deleted. Like most folders, a root folder can contain messages and other folders. See also IPM subtree.

rule

A specification of an automated response to a particular event. Rules are commonly used to route incoming e-mail; such a rule could, for example, store an incoming message meeting certain conditions in a specified folder. A rule can be implemented by a notification callback function or a messaging hook provider. It can be applied to personal folders and to a public folder.


S

search key

A binary value that can be directly compared with other search keys to help find objects related to a MAPI object. An object’s search key is stored in its PR_SEARCH_KEY property. See also record key, entry identifier.

search-results folder

A MAPI folder object that contains links to messages that match specified search criteria. A search-results folder can be saved across sessions if desired. It cannot contain other folders or messages, nor can a folder or message be created in it or moved into it.

section

A part of either a session profile or a form configuration file containing interrelated items of information. See also profile section.

secure property

A property of a profile section with a property tag in the range 0x6600 through 0x67FF. A secure property is set by a service provider, and is encrypted and invisible to a client application. To view a secure property, it is necessary to ask specifically to view it. Secure properties are typically used for credentials such as passwords.

Sent Items folder

A folder within the interpersonal message (IPM) subtree that is designated to hold copies of messages after they are sent. These copies are saved only if the message store provider supports this functionality and the user of the client application requests it. See also IPM subtree.

service provider

A MAPI component that allows a client application to use the services of a messaging system. A service provider is typically part of a message service and offers address book, form management, message store, messaging hook, profile section, or transport services. See also address book provider, form library provider, message store provider, messaging hook provider, profile provider, transport provider. For more information, see Service Provider Basics.

service provider interface

(SPI) The set of interfaces and functions that are implemented or used by service providers. The MAPISPI.H header file contains definitions of all the interface methods and functions in the service provider interface.

session

An active connection between a client application and the MAPI subsystem. As part of the logon procedure, which initiates the session, the client application selects a profile, which identifies the available messaging operations and the service providers available to handle the operations. A session implements the IMAPISession : IUnknown interface.

session handle

A handle to a session initiated by a client application using Simple MAPI or Common Messaging Calls. Session handles are returned by the MAPILogon or MAPILogonEx function at logon time.

session pointer

A pointer to a MAPI session made available to the client application that logs on to the session. A session pointer is unique to the initiating client and is not valid in any other task.

shared session

A MAPI session that can be used by multiple client applications on a given computer.

short-term entry identifier

An entry identifier of limited duration and scope. It is typically used only for a single operation and is not stored for later use. It can, however, be converted into a long-term entry identifier.

Simple Mail Transfer Protocol

(SMTP) An Internet standard for electronic mail among clients having common access to a server for message storage. The SMTP standard is specified in the RFC 821 document, and the message format is included in the RFC 822 document. For more information, see Mapping of Internet Mail Attributes to MAPI Properties.

Simple MAPI

A set of functions that is a component of the MAPI client interface and that enables basic messaging features to be added to a client application. It provides a layer between the client application and the MAPI client interface component. See also Common Messaging Calls, OLE Messaging Library.

single-valued property

A property for which the data structure contains one property value of the specified property type. See also multivalued property. For more information, see About Property Types.

site

See messaging domain.

SMTP

See Simple Mail Transfer Protocol.

SPI

See service provider interface.

spooler

See MAPI spooler.

spooler hook

See messaging hook provider.

standard contents table

A table of the information in a folder that is normally visible to the user. It typically contains messages and subfolders that belong to the folder. See also associated contents table, contents table, form, message, view descriptor.

static table

A table that does not change as its underlying data changes. Provider and profile tables are examples of static tables. See also dynamic table.

status table

A MAPI table object that provides access to information about each service provider in the active profile, the MAPI spooler and MAPI subsystem, and the address book. The status table describes the state of a MAPI session.

store-and-forward messaging

A messaging model wherein messages are forwarded from a local message store to a component that saves and delivers them if possible. If delivery is not possible with the requested transport provider, this component either forwards messages to another transport provider or holds onto them until the requested transport provider is available. With MAPI, the MAPI spooler performs the store-and-forward function.

subscription

See registration.

support object

A MAPI object presented to a service provider at logon time that furnishes implementations of commonly used methods as well as certain contextual data such as the last error. For more information, see Using A Support Object.


T

table

A MAPI object that provides access to a summary view of object data in row and column format. Tables implement the IMAPITable : IUnknown interface. Each row represents an instance of an object; each column represents a property on that object. See also associated contents table, attachment table, contents table, display table, hierarchy table, message service table, message store table, one-off table, profile table, provider table, recipient table, standard contents table, status table.

Telephony Application Programming Interface

(TAPI) A set of functions that allows applications to use telephone lines for transporting data across a network without requiring information on details of how the transport process works.

template

A common dialog box that is used for creating new address book entries, such as a one-off address, of a particular type. A template can be viewed as an entire schema that specifies the properties for the dialog box and the code that relates them.

template identifier

An entry identifier for a recipient that enables its address book provider to control its behavior if it is copied into a different address book container. A template identifier can support a messaging user or a distribution list and allows the destination provider to access the original provider’s implementation. The template identifier is held in the recipient’s PR_TEMPLATEID property. For more information, see Address Book Identifiers.

tightly coupled

Describes a relationship between two or more providers that enables them to communicate directly with each other without using all of the interface provided by MAPI. A tightly coupled message store provider and transport provider can bypass the MAPI spooler. A tightly coupled address book provider and transport provider can pass a recipient between them using only an entry identifier and without opening a property interface.

TNEF

See Transport-Neutral Encapsulation Format.

transmittable property

A property that is sent along with the message it is associated with. Transmittable properties are those that apply in both the sending and receiving environments, such as PR_IMPORTANCE and PR_RTF_COMPRESSED. See also nontransmittable property.

Transport-Neutral Encapsulation Format

(TNEF) A MAPI-defined method of passing MAPI message properties that are not supported by a messaging system. The outbound transport provider invokes the method to bundle all the unsupported properties into a single binary stream. The transport provider may then have to encode the stream into a format its messaging system can handle. The stream accompanies the message through the transport process as an attachment, is decoded if necessary by the inbound transport provider, and is finally passed to TNEF to reconstitute the MAPI properties. See also property.

transport provider

A MAPI service provider object that is responsible for transferring messages between a message store and an underlying messaging system that delivers the messages. Transport providers implement the IXPLogon : IUnknown and IXPProvider : IUnknown interfaces. For more information, see Developing a Transport Provider.


U

UNC

(Universal Naming Convention) A network resource name for a share point on a server, consisting of the string

\\<server name>\<share point name>

As opposed to a resolved drive letter such as S:, a UNC name is usable without alteration from any task on any computer that has access to the share point.

Unicode

A mapping of most known language characters to a set of 16-bit values. Unicode is a worldwide encoding standard and is used exclusively by Windows NT at the system level. See also DBCS.

uninitialized state

A condition in which a form’s storage object is available only for write access; read access is prohibited. A form is placed in the uninitialized state from the time of its creation until it has been loaded with default or supplied data. See also normal state, no-scribble state, hands-off state. For more information, see Form States.

unresolved recipient

A messaging user or distribution list that has not been assigned an entry identifier and an address for a particular messaging system. See also name resolution, resolved recipient.


V

verb

A command appearing in the menu of a form. MAPI defines standard verbs like Compose, Send, and Close.

view

A list of parameters and operations applied to a MAPI table object, commonly the contents table of a folder. A view defines a particular way to display the data in the table, for example which columns, in which display order, and in which sort order. Some applications enable views to be saved.

view context

A MAPI object that supports commands for printing and saving a form and for navigating between forms. View contexts implement the IMAPIViewContext : IUnknown interface.

view descriptor

A message of a specific message class which appears in the associated contents table of a folder and specifies a view on that folder. A view descriptor encodes the information in the view for use by a client application.


W

wastebasket

See Deleted Items folder.

Windows Messaging System

(WMS) The MAPI subsystem that is implemented on any of the Microsoft Windows operating systems.


X

X.400

An international message-handling standard for connecting e-mail networks and for connecting users to e-mail networks. X.400 is published by the International Telegraph and Telephone Consultative Committee (CCITT) standards body, now called the International Telecommunications Union (ITU). The X.400 Application Programming Interface Association (XAPIA) defines programming interfaces to X.400. MAPI applications are fully interoperable with X.400 messaging applications.

X.435

An international message-handling standard that is published by the International Telegraph and Telephone Consultative Committee (CCITT) standards body, now called the International Telecommunications Union (ITU), and that implements the Electronic Data Interchange (EDI) standard for integrating data with various native formats into a message.

X.500

An international message-handling standard for directory services, published by the International Telegraph and Telephone Consultative Committee (CCITT) standards body, now called the Internal Telecommunications Union (ITU).

XAPIA

The X.400 Application Programming Interface Association, the standards-setting body for programming interfaces to X.400 components. XAPIA also defines the Common Messaging Calls inteface component.


Common Messaging Calls (CMC)

The Common Messaging Calls (CMC) applications programming interface (API) provides a simple and convenient set of functions for applications that need basic messaging functionality. CMC provides for all the major messaging functionality an application should need, such as accessing message stores for sending and receiving messages, and addressing and name resolution services. The functions in the CMC API are typically high level functions and can each be used in several different ways depending on the arguments to the functions. The CMC API makes it possible for the calling application to know nothing about the underlying messaging system or transport mechanism used to implement the CMC API itself.

Most CMC functions use both input and output parameters. Input parameters provide information the CMC implementation uses to perform the tasks needed by the calling application. The CMC implementation uses output parameters to pass information back to the calling application from a CMC function. Some functions have parameters used for both input and output.

Data structures and symbolic constants for CMC and its extensions are described in this reference. Their C language definitions can be found in the following header files:

Header file name	Header file contents
XCMC.H	CMC data structures and symbolic constants.
XCMCEXT.H	Common CMC extension data structures and symbolic constants.
XCMCMSXT.H	Microsoft CMC extension data structures and symbolic constants.


Functions

The following functions are implemented in compliance with the X.400 API Association’s Common Messaging Call API specification. These functions make heavy use of extensions, which are described in the Data Extensions section of the CMC reference. The functions are listed in alphabetical order.


cmc_act_on

The cmc_act_on function performs the specified operation on a message.

Quick Info

Header file:	XCMC.H
CMC_return_code cmc_act_on (

CMC_session_id session,
CMC_message_reference * message_reference,
CMC_enum operation,
CMC_flags act_on_flags,
CMC_ui_id ui_id,
CMC_extension FAR * act_on_extensions
)
Parameters

session

[in] Session handle that represents a MAPI session. The value in the session parameter must be a valid session handle, not zero.

message_ reference

[in] Pointer to a message reference that identifies the message to be acted upon. A null pointer or a pointer to a message reference of length zero is invalid for any operation requiring a message reference. If the message reference is invalid, the cmc_act_on function returns CMC_E_INVALID_MESSAGE_REFERENCE.

operation

[in] An enumeration variable that identifies the operation to perform on the message. Possible values for this variable are:

CMC_ACT_ON_DELETE

Marks the specified message for deletion from the mailbox. This operation requires a valid message_reference parameter.

CMC_ACT_ON_EXTENDED

The operation to be performed is specified in the act_on_extensions parameter.

act_on_flags

[in] Bitmask of option flags. The following flag can be set:

CMC_ERROR_UI_ALLOWED

Displays a dialog box on encountering recoverable errors. If this flag is not set, cmc_act_on does not display a dialog box and returns an error value instead.

ui_id

[in] A handle that cmc_act_on uses to present a dialog box for resolving processing questions.

act_on_extensions

[in, out] Pointer to an array of CMC_extension structures containing function extensions. On input, this array contains MAPI extensions to the standard cmc_act_on function. A value of NULL for the act_on_extensions parameter indicates the caller has no extensions for cmc_act_on and is expecting no extensions. You can use the CMC_X_COM_SAVE_MESSAGE extension to save a message to the receive folder.

On output, cmc_act_on writes to the array new information about its processing. It writes NULL if it generates no output extensions.

Return Values

CMC_E_FAILURE

There was a general failure that does not fit the description of any other return value.

CMC_E_INSUFFICIENT_MEMORY

Insufficient memory was available to complete the requested operation.

CMC_E_INVALID_ENUM

A CMC_enum value was invalid.

CMC_E_INVALID_FLAG

A flag set using a flags parameter was invalid.

CMC_E_INVALID_MESSAGE_REFERENCE

The specified message reference is invalid or no longer valid (for example, it has been deleted).

CMC_E_INVALID_PARAMETER

A function parameter was invalid.

CMC_E_INVALID_SESSION_ID

The specified session handle is invalid or no longer valid (for example, after logging off).

CMC_E_INVALID_UI_ID

The specified user-interface identifier is invalid or no longer valid.

CMC_E_MESSAGE_IN_USE

The requested action could not be completed because the message was in use.

CMC_E_UNSUPPORTED_ACTION

The requested action is not supported by the current implementation.

CMC_E_UNSUPPORTED_FLAG

The flag requested is not supported.

CMC_E_UNSUPPORTED_FUNCTION_EXT

The function extension requested is not supported.

See Also

CMC_extension, CMC_X_COM_SAVE_MESSAGE


cmc_free

The cmc_free function frees memory allocated by the message service through another CMC function.

Quick Info

Header file:	XCMC.H
CMC_return_code cmc_free (

CMC_buffer memory
)
Parameters

memory

[in] Pointer to memory previously allocated by CMC. The cmc_free function ignores a parameter value of NULL. After this function completes, the pointer to memory is invalid, and the application cannot reference it again.

Return Values

CMC_E_FAILURE

There was a general failure that does not fit the description of any other return value.

CMC_E_INVALID_MEMORY

A memory pointer passed is invalid.

Remarks

Results of the cmc_free function are unpredictable if the client application calls it with a base pointer to a memory block not allocated by the message service, a base pointer to a memory block already freed, or a nonbase pointer to a complex structure written by another CMC function.

The CMC functions cmc_list, cmc_look_up, cmc_query_configuration, and cmc_read can provide the client application with a base pointer to a complex structure containing several levels of pointers. The client application should free the entire structure or structure array by calling cmc_free with the base pointer.

See Also

cmc_list, cmc_look_up, cmc_query_configuration, cmc_read


cmc_list

The cmc_list function lists summary information for messages that meet client application-specified criteria.

Quick Info

Header file:	XCMC.H
CMC_return_code cmc_list (

CMC_session_id session,
CMC_string message_type,
CMC_flags list_flags,
CMC_message_reference * seed,
CMC_uint32 FAR * count,
CMC_ui_id ui_id,
CMC_message_summary FAR * FAR * result,
CMC_extension FAR * list_extensions
)
Parameters

session

[in] Opaque session handle that represents a MAPI session object indicating a session with a message service. If the session handle is invalid, this function returns CMC_E_INVALID_SESSION_ID.

message_type

[in] Pointer to the ASCII name of the type of message for which this function lists information. If the cmc_list function does not recognize the specified message type, it returns CMC_E_UNRECOGNIZED_MESSAGE_TYPE. If the function receives a value of NULL for the message type, it lists information for all available message types.

list_flags

[in] Bitmask of flags. The following flags can be set:

CMC_ERROR_UI_ALLOWED

Displays a dialog box on encountering recoverable errors. If this flag is not set, cmc_list does not display a dialog box and returns an error value instead.

CMC_LIST_COUNT_ONLY

Lists only a count of messages meeting the specified criteria, not any actual summary information. If this flag is not set, the function lists summary information in the array.

CMC_LIST_MSG_REFS_ONLY

Writes only message reference information to the array pointed to by the result parameter. If this flag is not set, cmc_list writes information to all members of the structures in the array.

CMC_LIST_UNREAD_ONLY

Lists unread messages only. If this flag is not set, cmc_list can list both read and unread messages.

seed

[in] Pointer to a message reference that identifies the message after which cmc_list should begin to search. A value of NULL for this parameter indicates that the function should start the search with the first message in the mailbox. A pointer to a message reference of length zero is invalid and causes cmc_list to return CMC_E_INVALID_MESSAGE_REFERENCE. If the seed parameter is part of a structure that is returned by an earlier CMC call, the structure that was allocated by CMC should be freed before the current session exits.

count

[in, out] A message count. On input, this parameter specifies a pointer to the maximum number of messages for which cmc_list should provide summary information. A value of zero indicates no maximum.

On output, the count parameter specifies the location to which cmc_list writes the number of messages for which it provides summary information. If no messages match the search criteria, or if the mailbox is empty, cmc_list writes zero.

ui_id

[in] Handle of a dialog box for cmc_list to present to help resolve processing questions.

result

[out] Pointer to the location to which cmc_list writes the address of the array of CMC_message_summary structures that it has written.

list_extensions

[in, out] Pointer to an array of CMC_extension structures specifying function extensions. On input, this array contains MAPI extensions to the standard cmc_list function. A value of NULL for the list_extensions parameter indicates that the client application has no extensions for cmc_list and is expecting no extensions.

On output, cmc_list writes to the array new information about its processing of the message summaries. It writes NULL if it generates no output extensions.

Return Values

CMC_E_FAILURE

There was a general failure that does not fit the description of any other return value.

CMC_E_INSUFFICIENT_MEMORY

Insufficient memory was available to complete the requested operation.

CMC_E_INVALID_FLAG

A flag set using a flags parameter was invalid.

CMC_E_INVALID_MESSAGE_REFERENCE

The specified message reference is invalid or no longer valid (for example, it has been deleted).

CMC_E_INVALID_PARAMETER

A function parameter was invalid.

CMC_E_INVALID_SESSION_ID

The specified session handle is invalid or no longer valid (for example, after logging off).

CMC_E_INVALID_UI_ID

The specified user-interface identifier is invalid or no longer valid.

CMC_E_UNRECOGNIZED_MESSAGE_TYPE

The specified message type is not supported by the current implementation.

CMC_E_UNSUPPORTED_FLAG

The flag requested is not supported.

CMC_E_UNSUPPORTED_FUNCTION_EXT

The function extension requested is not supported.

Remarks

The client application can specify a cmc_list search to start with a certain message or to start at the first message in the mailbox. It can also specify the maximum number of messages to list. The cmc_list function writes the summary information for the specified messages in an array of CMC_message_summary structures. Using the message references in these structures, the application can then make calls to the cmc_read and cmc_act_on functions for additional processing.

Before cmc_list writes message summary information, it must allocate memory for the structure array to contain the information. When this memory is no longer needed, the client application should free the entire array with a call to the cmc_free function.

See Also

cmc_act_on, CMC_extension, cmc_free, CMC_message_summary, cmc_read


cmc_logoff

The cmc_logoff function logs a client application off a message service.

Quick Info

Header file:	XCMC.H
CMC_return_code cmc_logoff (

CMC_session_id session,
CMC_ui_id ui_id,
CMC_flags logoff_flags,
CMC_extension FAR * logoff_extensions
)
Parameters

session

[in] Opaque session handle that represents a MAPI session object indicating a session with a message service. If the session handle is invalid, the cmc_logoff function returns CMC_E_INVALID_SESSION_ID. After cmc_logoff returns, the session handle is invalid.

ui_id

[in] Handle of a dialog box for cmc_logoff to present to help resolve processing questions.

logoff_flags

[in] Bitmask of flags. The following flags can be set:

CMC_ERROR_UI_ALLOWED

Displays a dialog box on encountering recoverable errors. If this flag is not set, cmc_logoff does not display a dialog box and returns an error value instead.

CMC_LOGOFF_UI_ALLOWED

Indicates cmc_logoff can display a dialog box for other purposes than displaying error messages while logging the user off from the session.

logoff_extensions

[in, out] Pointer to an array of CMC_extension structures containing function extensions. On input, this array contains MAPI extensions to the standard cmc_logoff function. A value of NULL for the logoff_extensions parameter indicates that the client application has no extensions for cmc_logoff and is expecting no extensions.

On output, cmc_logoff writes to the array new information about the logoff operation. It writes NULL if it generates no output extensions.

Return Values

CMC_E_FAILURE

There was a general failure that does not fit the description of any other return value.

CMC_E_INSUFFICIENT_MEMORY

Insufficient memory was available to complete the requested operation.

CMC_E_INVALID_FLAG

A flag set using a flags parameter was invalid.

CMC_E_INVALID_PARAMETER

A function parameter was invalid.

CMC_E_INVALID_SESSION_ID

The specified session handle is invalid or no longer valid (for example, after logging off).

CMC_E_INVALID_UI_ID

The specified user-interface identifier is invalid or no longer valid.

CMC_E_UNSUPPORTED_FLAG

The flag requested is not supported.

CMC_E_UNSUPPORTED_FUNCTION_EXT

The function extension requested is not supported.

CMC_E_USER_NOT_LOGGED_ON

The user was not logged on and the CMC_LOGON_UI_ALLOWED flag was not set.

See Also

CMC_extension


cmc_logon

The cmc_logon function logs a client application onto a service provider.

Quick Info

Header file:	XCMC.H
CMC_return_code cmc_logon (

CMC_string service,
CMC_string user,
CMC_string password,
CMC_object_identifier character_set,
CMC_ui_id ui_id,
CMC_uint16 caller_CMC_version,
CMC_flags logon_flags,
CMC_session_id FAR * session,
CMC_extension FAR * logon_extensions
)
Parameters

service

[in] Pointer to the location of the service provider for the CMC implementation. Passing NULL for the service parameter indicates either that the client application is requesting logon to a service provider that does not require a service name, or that the client is requesting the CMC implementation’s logon dialog box.

user

[in] Pointer to a MAPI profile name identifying the client application. Passing NULL for the user parameter indicates either that the client is requesting logon to a service provider that does not require a user name, or that the client is requesting the CMC implementation’s dialog box to prompt for a name.

password

[in] Pointer to a MAPI profile password required for access to the CMC implementation. Passing NULL for the service parameter indicates either that the client is requesting logon to a service provider that does not require a password, or that the client is requesting the CMC implementation’s dialog box to prompt for a password.

character_set

[in] Pointer to an object identifier for the character set used by the client application. The client application can call the cmc_query_configuration function to retrieve the available values. The CMC implementation requires a non-null value for the character_set parameter.

ui_id

[in] Handle of a dialog box for the cmc_logon function to present to help resolve processing questions or prompt for logon.

caller_CMC_ version

[in] The client application’s CMC version number, multiplied by 100. For example, version 1 is specified as the integer 100.

logon_flags

[in] Bitmask of flags. The following flags can be set:

CMC_COUNTED_STRING_TYPE

The string type the calling application or provider uses for CMC interactions is a CMC_counted_string. If this flag is not set, the function treats all strings as null-terminated strings.

CMC_ERROR_UI_ALLOWED

Displays a dialog box on encountering recoverable errors. If this flag is not set, cmc_logon does not display a dialog box and returns an error value instead.

CMC_LOGON_UI_ALLOWED

Displays a dialog box to prompt for logon if required. If this flag is not set, cmc_logon does not display a dialog box and returns an error value if the user does not supply enough information.

session

[out] Pointer to the location to which cmc_logon writes an opaque session handle. This identifier represents a MAPI session object indicating a session with a message service.

logon_extensions

[in, out] Pointer to an array of CMC_extension structures specifying function extensions. On input, this array contains MAPI extensions to the standard cmc_logon function. A value of NULL for the logon_extensions parameter indicates that the client application has no extensions for cmc_logon and is expecting no extensions.

On output, cmc_logon writes to the array new information about the logon operation. It writes NULL if it generates no output extensions.

Return Values

CMC_E_COUNTED_STRING_UNSUPPORTED

This implementation does not support the counted-string type.

CMC_E_FAILURE

There was a general failure that does not fit the description of any other return value.

CMC_E_INSUFFICIENT_MEMORY

Insufficient memory was available to complete the requested operation.

CMC_E_INVALID_FLAG

A flag set using a flags parameter was invalid.

CMC_E_INVALID_PARAMETER

A function parameter was invalid.

CMC_E_INVALID_UI_ID

The specified user-interface identifier is invalid or no longer valid.

CMC_E_LOGON_FAILURE

The service, user name, or password specified was invalid, so logon cannot be completed.

CMC_E_PASSWORD_REQUIRED

A password is required on this message service.

CMC_E_SERVICE_UNAVAILABLE

The service requested was unavailable.

CMC_E_UNSUPPORTED_CHARACTER_SET

The current implementation does not support the character set requested.

CMC_E_UNSUPPORTED_FLAG

The current implementation does not support the flag requested.

CMC_E_UNSUPPORTED_FUNCTION_EXT

The current implementation does not support the function extension requested.

CMC_E_UNSUPPORTED_VERSION

The current implementation cannot support the version specified in the call.

Remarks

The cmc_logon function can, at the client application’s option, either prompt the user for information through a dialog box or proceed without any user interaction. It writes a session handle that the client application can use in subsequent calls to the CMC implementation.

See Also

CMC_extension, cmc_query_configuration


cmc_look_up

The cmc_look_up function looks up addressing information in a directory provided by a specified service provider.

Quick Info

Header file:	XCMC.H
CMC_return_code cmc_look_up (

CMC_session_id session,
CMC_recipient FAR * recipient_in,
CMC_flags look_up_flags,
CMC_ui_id ui_id,
CMC_uint32 FAR * count,
CMC_recipient FAR * FAR * recipient_out,
CMC_extension FAR * look_up_extensions
)
Parameters

session

[in] Opaque session handle that represents a MAPI session object that represents a session with a message service. If the session handle is invalid, the cmc_look_up function returns the CMC_E_INVALID_SESSION_ID error value.

recipient_in

[in] Pointer to an array of CMC_recipient structures containing recipient data. The cmc_look_up function interprets the array depending on the flags that the client application has set using the look_up_flags parameter. Possible interpretations are as following:

•	If the client application has set one of the flags for name resolution, cmc_look_up obtains the name to resolve from the name member of the first structure in the array. The function checks the corresponding name-type member to discover what resolution should be performed. The cmc_look_up function ignores all recipient structures except the first in the array.

•	If the client application has set the CMC_LOOKUP_DETAILS_UI flag, the information in the array must resolve to only one recipient. If it does not, cmc_look_up returns CMC_E_AMBIGUOUS_RECIPIENT. The cmc_look_up function ignores all recipient structures except the first in the array.

•	If the client application has set the CMC_LOOKUP_ADDRESSING_UI flag, cmc_look_up displays the recipients specified in the recipient array in the address-list dialog box.

look_up_flags

[in] Bitmask of flags. The following flags can be set:

CMC_COUNTED_STRING_TYPE

The string type the calling application or provider uses for CMC interactions is a CMC_counted_string. If this flag is not set, the function treats all strings as null-terminated strings.

CMC_ERROR_UI_ALLOWED

Displays a dialog box on encountering recoverable errors. If this flag is not set, cmc_look_up does not display a dialog box and returns an error value instead.

CMC_LOGON_UI_ALLOWED

Displays a dialog box to prompt for logon if required. If this flag is not set, cmc_look_up does not display a dialog box and returns an error value if the user does not supply enough information.

CMC_LOOKUP_ADDRESSING_UI

Displays a dialog box to allow creation of a recipient list for addressing a message and general directory browsing. The recipient list passed to the function is the original recipient list for the dialog box. The function returns the list of recipients created by the user. This flag is optional for implementations to support.

CMC_LOOKUP_DETAILS_UI

Displays a details dialog box for the recipient pointed to in the recipient_in parameter. This dialog box only acts on the first recipient in the list. If the recipient name indicated resolves to more than one address, cmc_look_up does not display the details dialog box and returns CMC_E_AMBIGUOUS_RECIPIENT.

CMC_LOOKUP_RESOLVE_IDENTITY

Returns a recipient record for the identity of the current user of the message service. If no unique identity can be determined, the implementation carries out ambiguous name resolution to determine the address of the current user.

CMC_LOOKUP_RESOLVE_PREFIX_SEARCH

The search method should be by prefix. In a prefix search, all names matching the prefix string, beginning at the first character of the name, are considered matches. If this flag is not set, the search method should be exact-match. CMC implementations must support simple prefix searching. The availability of wildcard or substring searches is optional.

CMC_LOOKUP_RESOLVE_UI

Attempts to resolve ambiguous names by presenting a name-resolution dialog box to the user. If this flag is not set, resolutions that do not result in a single name return the error value CMC_E_AMBIGUOUS_RECIPIENT for message services that require names to resolve to a single address. Message services that can return multiple addresses can return a list of addresses if the count parameter is non-null. The name_type field in the recipient_out parameter can also be set on input as a hint to aid in resolution of the name. Some CMC implementations might not support this flag. The CMC_LOOKUP_RESOLVE_UI flag is set only when the CMC_LOOKUP_RESOLVE_PREFIX_SEARCH flag is also set.

ui_id

[in] Handle of a dialog box for cmc_look_up to present to help resolve processing questions.

count

[in or out] Contains a maximum name count. On input, this parameter specifies a pointer to the maximum number of names for which cmc_look_up can find addressing information. A value of zero indicates no maximum.

On output, the count parameter specifies the location to which cmc_look_up writes the number of names that it actually writes to the location indicated by the recipient_out parameter. If no names are written, cmc_look_up writes zero to the count parameter.

recipient_out

[out] Pointer to the location to which cmc_look_up writes an array of one or more CMC_recipient structures containing addressing details for the recipients in the array passed in the recipient_in parameter.

look_up_extensions

[in, out] Pointer to an array of CMC_extension structures specifying function extensions. On input, this array contains MAPI extensions to the standard cmc_look_up function. A value of NULL for the look_up_extensions parameter indicates that the client application has no extensions for cmc_look_up and is expecting no extensions.

On output, cmc_look_up writes to the array new information about the lookup operation. It writes NULL if it generates no output extensions.

Return Values

CMC_E_AMBIGUOUS_RECIPIENT

The recipient name was ambiguous. Multiple matches were found.

CMC_E_FAILURE

There was a general failure that does not fit the description of any other return value.

CMC_E_INSUFFICIENT_MEMORY

Insufficient memory was available to complete the requested operation.

CMC_E_INVALID_FLAG

A flag set using a flags parameter was invalid.

CMC_E_INVALID_PARAMETER

A function parameter was invalid.

CMC_E_INVALID_SESSION_ID

The specified session handle is invalid or no longer valid (for example, after logging off).

CMC_E_INVALID_UI_ID

The specified user-interface identifier is invalid or no longer valid.

CMC_E_LOGON_FAILURE

The service, user name, or password specified was invalid, so logon cannot be completed.

CMC_E_NOT_SUPPORTED

The current implementation does not support the operation requested.

CMC_E_RECIPIENT_NOT_FOUND

One or more of the specified recipients were not found.

CMC_E_UNSUPPORTED_DATA_EXT

The current implementation does not support the data extension requested.

CMC_E_UNSUPPORTED_FLAG

The current implementation does not support the flag requested.

CMC_E_UNSUPPORTED_FUNCTION_EXT

The current implementation does not support the function extension requested.

CMC_E_USER_CANCEL

The operation was canceled by the user.

CMC_E_USER_NOT_LOGGED_ON

The user was not logged on and the CMC_LOGON_UI_ALLOWED flag was not set.

Remarks

A client application calls the cmc_look_up function to resolve a display name to a messaging address or to prompt the user to choose among multiple resolved names. A client can also use this function to display a dialog box for creation of recipient lists or to display recipient details.

The cmc_look_up function can write multiple addresses. Before it writes addressing information, it must allocate memory for the structure array to contain the information. When this memory is no longer needed, the client application should free the entire array with a call to cmc_free.

See Also

CMC_extension, cmc_free, CMC_recipient


cmc_query_configuration

The cmc_query_configuration function determines configuration information for the installed CMC implementation.

Quick Info

Header file:	XCMC.H
CMC_return_code cmc_query_configuration (

CMC_session_id session,
CMC_enum item,
CMC_buffer reference,
CMC_extension FAR * config_extensions
)
Parameters

session

[in] Opaque session handle that represents a MAPI session object indicating a session with a message service. If this parameter is set to zero, there is no session and the cmc_query_configuration function returns the default logon information to the buffer indicated by the reference parameter. If the session parameter is set to a nonzero value, cmc_query_configuration returns configuration information as determined by the session. If the value provided for the session parameter is invalid, cmc_query_configuration returns CMC_E_INVALID_SESSION_ID.

item

[in] Enumerated variable that identifies the configuration information required by the client application. The cmc_query_configuration function will write different values to the buffer or pointer that the reference parameter points to depending on the value of the item parameter. The caller must allocate this buffer or pointer before calling cmc_query_configuration. Possible item values are:

CMC_CONFIG_CHARACTER_SET

The reference parameter should be a pointer to a CMC_object_identifier structure array. The cmc_query_configuration function writes a pointer to the array of CMC_object_identifier structures that indicate the character sets supported by the current CMC implementation to the location pointed at by the reference parameter. The cmc_query_configuration function ends the array with a null CMC_object_identifier structure.

The first object identifier in the array is the default character set used if the calling client application or service provider does not specify one explicitly. The calling client or provider uses one of these object identifiers at logon to specify that the implementation use a different character set than the default. This array should be freed with cmc_free.

CMC_CONFIG_DEFAULT_SERVICE

The reference parameter should be a pointer to a CMC_string data type. The cmc_query_configuration function writes a pointer to the default message service name, if available, to the location indicated by the reference parameter. The cmc_query_configuration function writes NULL to this location if no default service name is available.

The calling client or provider can use this string, along with the one returned by CMC_CONFIG_DEFAULT_USER, as defaults when prompting the user for the service name, user name, and password. The string is returned in the CMC implementation’s default character set.

CMC_CONFIG_DEFAULT_USER

The reference parameter should be a pointer to a CMC_string data type. The cmc_query_configuration function writes a pointer to the default user name, if available, to the location indicated by the reference parameter. The cmc_query_configuration function writes NULL to this location if no default user name is available.

The calling client or provider can use this string, along with the one returned by CMC_CONFIG_DEFAULT_SERVICE, as defaults when prompting the user for the provider name, user name, and password. The string is returned in the CMC implementation’s default character set.

CMC_CONFIG_LINE_TERM

The reference parameter should be a pointer to a CMC_enum variable, which is set to CMC_LINE_TERM_CRLF if the line delimiter is a carriage return followed by a line feed, CMC_LINE_TERM_LF if the line delimiter is a line feed, or CMC_LINE_TERM_CR if the line delimiter is a carriage return.

CMC_CONFIG_REQ_PASSWORD

The reference parameter should be a pointer to a CMC_enum variable, which is set to CMC_REQUIRED_NO if the password is not required to log on, CMC_REQUIRED_OPT if the password is optional to log on, or CMC_REQUIRED_YES if the password is required to log on.

CMC_CONFIG_REQ_SERVICE

The reference parameter should be a pointer to a CMC_enum variable, which is set to CMC_REQUIRED_NO if the service name is not required to log on, CMC_REQUIRED_OPT if the service name is optional to log on, or CMC_REQUIRED_YES if the service name is required to log on.

CMC_CONFIG_REQ_USER

The reference parameter should be a pointer to a CMC_enum variable, which is set to CMC_REQUIRED_NO if the user name is not required to log on, CMC_REQUIRED_OPT if the user name is optional to log on, or CMC_REQUIRED_YES if the user name is required to log on.

CMC_CONFIG_SUP_COUNTED_STR

The reference parameter should be a pointer to a CMC_boolean variable, which is set to TRUE if the CMC_COUNTED_STRING_TYPE flag is supported during logon.

CMC_CONFIG_SUP_NOMKMSGREAD

The reference parameter should be a pointer to a CMC_boolean variable, which will be set to TRUE if the cmc_read function supports the CMC_DO_NOT_MARK_AS_READ flag.

CMC_CONFIG_UI_AVAIL

The reference parameter should be a pointer to a CMC_boolean variable, which will be set to TRUE if there is a dialog box provided by the CMC implementation.

CMC_CONFIG_VER_IMPLEM

The reference parameter should be a pointer to a CMC_uint16 variable, which is set to the version number for the implementation, multiplied by 100. For example, version 1.01 returns 101.

CMC_CONFIG_VER_SPEC

The reference parameter should be a pointer to a CMC_uint16 variable, which is set to the CMC specification version number for the implementation, multiplied by 100. For example, version 1.00 returns 100.

reference

[out] Pointer to a buffer or pointer to which cmc_query_configuration writes configuration information. The value of reference depends on the value of item, as previously described.

config_extensions

[in, out] Pointer to an array of CMC_extension structures specifying function extensions. On input, this array contains MAPI extensions to the standard cmc_query_configuration function. A value of NULL for the config_extensions parameter indicates that the client application has no extensions for cmc_query_configuration and is expecting no extensions.

On output, cmc_query_configuration writes to the array new information about the query configuration operation. It writes NULL if it generates no output extensions.

Return Values

CMC_E_FAILURE

There was a general failure that does not fit the description of any other return value.

CMC_E_INSUFFICIENT_MEMORY

Insufficient memory was available to complete the requested operation.

CMC_E_INVALID_ENUM

A CMC_enum value was invalid.

CMC_E_INVALID_PARAMETER

A function parameter was invalid. Either the reference parameter did not point to a writeable location, or the config_extensions parameter was badly formed.

CMC_E_NOT_SUPPORTED

The current implementation does not support the operation requested.

CMC_E_UNSUPPORTED_FUNCTION_EXT

The current implementation does not support the function extension requested.

Remarks

The client application must cast the reference parameter to the CMC_buffer type before calling cmc_query_configuration. The client application must allocate sufficient memory to contain the information passed in the item parameter. When this memory is no longer needed, the client should free this memory with whatever memory management routines it is using, or with a call to the cmc_free function if required by the previous explanation.

See Also

CMC_extension, cmc_free, cmc_read


cmc_read

The cmc_read function reads a specified message.

Quick Info

Header file:	XCMC.H
CMC_return_code cmc_read (

CMC_session_id session,
CMC_message_reference * message_reference,
CMC_flags read_flags,
CMC_message FAR * FAR * message,
CMC_ui_id ui_id,
CMC_extension FAR * read_extensions
)
Parameters

session

[in] Opaque session handle that represents a MAPI session object indicating a session with a message service. If the value provided for the session parameter is invalid, the cmc_read function returns CMC_E_INVALID_SESSION_ID.

message_reference

[in] Pointer to a CMC_message_reference structure containing the message reference of the message to be retrieved. A NULL value for this parameter indicates that cmc_read should retrieve the first message in the mailbox. If the message reference is invalid, cmc_read returns CMC_E_INVALID_MESSAGE_REFERENCE.

read_flags

[in] Bitmask of flags. The following flags can be set:

CMC_DO_NOT_MARK_AS_READ

Does not mark messages as read when they are returned. This flag also suppresses sending of receipt reports. The calling client application or service provider can query the implementation to see if it supports this flag by calling the cmc_query_configuration function.

CMC_ERROR_UI_ALLOWED

Displays a dialog box on encountering recoverable errors. If this flag is not set, cmc_read does not display a dialog box and returns an error value instead.

CMC_MSG_AND_ATT_HDRS_ONLY

The attach_filename fields in the CMC_message structure returned in the message parameter will be undefined when cmc_read returns and should be ignored. This flag can be used to reduce the amount of data transferred, because the filenames will not be included in the transfer. If this flag is not set, the attach_filename fields are returned as usual.

Note that if the CMC_MSG_TEXT_NOTE_AS_FILE value is set in the flags of the returned message, the first attachment contains the message text. In this case, cmc_read returns the attach_filename field for that attachment regardless of the setting of the CMC_MSG_AND_ATT_HDRS_ONLY flag.

CMC_READ_FIRST_UNREAD_MESSAGE

Returns the first message that is not marked as read. If this flag is not set, cmc_read should return the first message in the mailbox, whether it is marked as read or not. This flag can only be set when passing a null message reference to receive the first message in the mailbox.

message

[out] Pointer to the location to which cmc_read writes the CMC_message structure containing the message it has read. The function writes attachment data in files, and the CMC_message structure indicates the names of those files in its attachments member. If the client application has set the CMC_MSG_AND_ATT_HDRS_ONLY flag, the function does not indicate any attachment files.

ui_id

[in] Handle of a dialog box for cmc_read to present to help resolve processing questions.

read_extensions

[in, out] Pointer to an array of CMC_extension structures specifying function extensions. On input, this array contains MAPI extensions to the standard cmc_read function. A value of NULL for the read_extensions parameter indicates that the client application has no extensions for cmc_read and is expecting no extensions.

On output, cmc_read writes to the array new information about the read operation. It writes NULL if it generates no output extensions.

Return Values

CMC_E_ATTACHMENT_OPEN_FAILURE

The specified attachment was found but could not be opened, or the attachment file could not be created.

CMC_E_ATTACHMENT_READ_FAILURE

The specified attachment was found and opened, but there was an error reading it.

CMC_E_ATTACHMENT_WRITE_FAILURE

The attachment file was created successfully, but there was an error writing it.

CMC_E_DISK_FULL

Insufficient disk space was available to complete the requested operation (this can refer to local or shared disk space).

CMC_E_FAILURE

There was a general failure that does not fit the description of any other return value.

CMC_E_INSUFFICIENT_MEMORY

Insufficient memory was available to complete the requested operation.

CMC_E_INVALID_FLAG

A flag set using a flags parameter was invalid.

CMC_E_INVALID_MESSAGE_REFERENCE

The specified message reference is invalid or no longer valid (for example, it has been deleted).

CMC_E_INVALID_PARAMETER

A function parameter was invalid.

CMC_E_INVALID_SESSION_ID

The specified session handle is invalid or no longer valid (for example, after logging off).

CMC_E_INVALID_UI_ID

The specified user-interface identifier is invalid or no longer valid.

CMC_E_TOO_MANY_FILES

The current implementation cannot support the number of files specified.

CMC_E_UNABLE_TO_NOT_MARK_READ

The current implementation cannot support the CMC_DO_NOT_MARK_AS_READ flag.

CMC_E_UNSUPPORTED_FLAG

The current implementation does not support the flag requested.

CMC_E_UNSUPPORTED_FUNCTION_EXT

The current implementation does not support the function extension requested.

Remarks

The cmc_read function only reads the first message in the mailbox if the client application passes a null message-reference value.

After processing, cmc_read writes the data from the message into the CMC_message structure. Unless the client application has set the flag CMC_DO_NOT_MARK_AS_READ on input, the message will be marked as read when cmc_read returns. If the client application has set the input flag CMC_MSG_AND_ATT_HDRS_ONLY, cmc_read writes only message and attachment headers on output.

The cmc_read function can write multiple addresses. Before it writes message information, it must allocate memory for the structure to contain that information. When this memory is no longer needed, the client application should free all structures in the array with a call to the cmc_free function.

See Also

CMC_extension, cmc_free, cmc_list, CMC_message, CMC_message_reference, cmc_query_configuration


cmc_send

The cmc_send function sends a message.

Quick Info

Header file:	XCMC.H
CMC_return_code cmc_send (

CMC_session_id session,
CMC_message FAR * message,
CMC_flags send_flags,
CMC_ui_id ui_id,
CMC_extension FAR s* send_extensions
)
Parameters

session

[in] Opaque session handle that represents a MAPI session object indicating a session with a message service. If the value provided for the session parameter is invalid, the cmc_send function returns CMC_E_INVALID_SESSION_ID.

message

[in] Pointer to a CMC_message structure identifying the message to be sent. If the client application has not set the flag CMC_SEND_UI_REQUESTED in the send_flags parameter, the message structure must specify at least one primary (TO), carbon-copy (CC), or blind carbon-copy (BCC) recipient. All other structure members are optional. The cmc_send function ignores the time_sent and message_reference members.

send_flags

[in] Bitmask of flags. The following flags can be set:

CMC_COUNTED_STRING_TYPE

The string type the calling application or provider uses for CMC interactions is CMC_counted_string. If this flag is not set, the function treats all strings as null-terminated strings.

CMC_ERROR_UI_ALLOWED

Displays a dialog box on encountering recoverable errors. If this flag is not set, cmc_send does not display a dialog box and returns an error value instead.

CMC_LOGON_UI_ALLOWED

Displays a dialog box to prompt for logon if required. If this flag is not set, cmc_send does not display a dialog box and returns an error value if the caller does not supply enough information.

CMC_SEND_UI_REQUESTED

Displays a dialog box to prompt for recipients, message field information, and other sending options. If this flag is not set, cmc_send does not display a dialog box and the caller must specify at least one recipient.

ui_id

[in] Handle of a dialog box for cmc_send to present when resolving processing questions, prompting the user for additional information, or verifying provided information.

send_extensions

[in, out] Pointer to an array of CMC_extension structures specifying function extensions. On input, this array contains MAPI extensions to the standard cmc_send function. A value of NULL for the send_extensions parameter indicates that the client application has no extensions for cmc_send and is expecting no extensions.

On output, cmc_send returns to the array new information about the send operation. It returns NULL if it generates no output extensions.

Return Values

CMC_E_AMBIGUOUS_RECIPIENT

The recipient name was ambiguous. Multiple matches were found.

CMC_E_ATTACHMENT_NOT_FOUND

The specified attachment was not found as specified.

CMC_E_ATTACHMENT_OPEN_FAILURE

The specified attachment was found but could not be opened, or the attachment file could not be created.

CMC_E_ATTACHMENT_READ_FAILURE

The specified attachment was found and opened, but there was an error reading it.

CMC_E_ATTACHMENT_WRITE_FAILURE

The attachment file was created successfully, but there was an error writing it.

CMC_E_COUNTED_STRING_UNSUPPORTED

The current implementation does not support the counted-string type.

CMC_E_FAILURE

There was a general failure that does not fit the description of any other return value.

CMC_E_INSUFFICIENT_MEMORY

Insufficient memory was available to complete the requested operation.

CMC_E_INVALID_FLAG

A flag set using a flags parameter was invalid.

CMC_E_INVALID_MESSAGE_PARAMETER

One of the parameters in the message was invalid.

CMC_E_INVALID_PARAMETER

A function parameter was invalid.

CMC_E_INVALID_SESSION_ID

The specified session handle is invalid or no longer valid (for example, after logging off).

CMC_E_INVALID_UI_ID

The specified user-interface identifier is invalid or no longer valid.

CMC_E_LOGON_FAILURE

The service, user name, or password specified were invalid, so logon cannot be completed.

CMC_E_RECIPIENT_NOT_FOUND

One or more of the specified recipients were not found.

CMC_E_TEXT_TOO_LARGE

The size of the text string passed to the current implementation is too large.

CMC_E_TOO_MANY_FILES

The current implementation cannot support the number of files specified.

CMC_E_TOO_MANY_RECIPIENTS

The current implementation cannot support the number of recipients specified.

CMC_E_UNSUPPORTED_DATA_EXT

The current implementation does not support the data extension requested.

CMC_E_UNSUPPORTED_FLAG

The current implementation does not support the flag requested.

CMC_E_UNSUPPORTED_FUNCTION_EXT

The current implementation does not support the function extension requested.

CMC_E_USER_CANCEL

The operation was canceled by the user.

CMC_E_USER_NOT_LOGGED_ON

The user was not logged on and the CMC_LOGON_UI_ALLOWED flag was not set.

Remarks

The cmc_send function can, at the client application’s option, either use an interface, like a dialog box, to prompt the user for message creation or proceed without any user interaction. A successful return from this function does not necessarily imply recipient validation.

The client application can optionally provide recipient list, subject text, attachments, and note text for the message. If the client application does not provide the required message elements, the cmc_send function can prompt the user for them if a dialog box is available. If the client provides one or more recipients, the function can send the message without prompting the user. If the client provides optional parameters and requests a dialog box, the parameters provide the initial values for the dialog box.

The following conditions apply to the CMC_message structure members:

message_type

To specify an interpersonal message, use a pointer to the string “CMC:IPM”. If the client application provides a pointer value of NULL or a pointer to an empty string, cmc_send uses the default string CMC:IPM.

subject

A pointer value of NULL indicates no subject text.

text_note

A pointer value of NULL indicates no message text. If the client application does pass a non-null value to indicate the message text that exceeds the limits of the service provider, the provider can demote the text to an attachment. Alternatively, it can cause cmc_send to return CMC_E_TEXT_TOO_LARGE.

recipients

A pointer value of NULL indicates no recipients. If the client application passes a non-null value to indicate recipients in excess of the number of recipients that the service provider allows per message, cmc_send returns CMC_E_TOO_MANY_RECIPIENTS.

Note that the CMC_recipient structure pointed to by recipients can include either the recipient’s name, an address, or a name and address pair. If the client application specifies only a name, cmc_send resolves the name to an address using name resolution rules defined by the CMC implementation. If the client specifies only an address, cmc_send uses this address for delivery and for the recipient display name. Finally, if the client specifies a name and address pair, cmc_send does not resolve the name.

The cmc_send function does not require a recipient of type originator to send a message.

attachments

A pointer value of NULL indicates no attachments. If the client application passes a non-null value to indicate attachments in excess of the number of attachments that the service provider allows per message, cmc_send returns CMC_E_TOO_MANY_FILES.

The cmc_send function reads the attachment files before it returns. Thus the caller or user can freely change or delete attachment files after cmc_send returns without affecting the message.

message_flags

Bitmask of message flags. The following flag can be set:

CMC_MSG_TEXT_NOTE_AS_FILE

The text_note member of the message parameter is ignored and the message text is contained in the file referred to by the first attachment. If this flag is set to zero, the message text is contained in the text_note member.

See Also

CMC_extension, CMC_message, CMC_recipient


cmc_send_documents

The cmc_send_documents function sends a document.

Quick Info

Header file:	XCMC.H
CMC_return_code cmc_send_documents (

CMC_string recipient_addresses,
CMC_string subject,
CMC_string text_note,
CMC_flags send_doc_flags,
CMC_string file_paths,
CMC_string file_names,
CMC_string delimiter,
CMC_ui_id ui_id
)
Parameters

recipient_addresses

[in] Pointer to the address of the document recipient. When the client application specifies multiple recipients, it should separate the strings using the character specified by the delimiter parameter. The cmc_send_documents function assumes a recipient to be a primary recipient unless the address is prefixed by CC: (carbon copy) or BCC: (blind carbon copy). The TO: prefix can optionally be used with the primary recipient for consistency with the other recipient types. Passing NULL in the recipient_addresses parameter indicates that cmc_send_documents should present a dialog box to prompt for recipients.

subject

[in] Pointer to the subject of the document. Passing NULL in the subject parameter indicates no subject text.

text_note

[in] Pointer to the text note carried with the document. Passing NULL in the text_note parameter indicates no text note.

send_doc_flags

[in] Bitmask of flags used to control how documents are sent. The following flags can be set:

CMC_COUNTED_STRING_TYPE

The string type the calling application or provider uses for CMC interactions is CMC_counted_string. If this flag is not set, the function treats all strings as null-terminated strings.

CMC_ERROR_UI_ALLOWED

Displays a dialog box on encountering recoverable errors. If this flag is not set, cmc_send_documents does not display a dialog box and returns an error value instead.

CMC_FIRST_ATTACH_AS_TEXT_NOTE

Sends the first attachment as the message text. If this flag is not set, the text_note field contains the text note.

CMC_LOGON_UI_ALLOWED

Displays a dialog box to prompt for logon if required. If this flag is not set, cmc_send_documents does not display a dialog box and returns an error if the user does not supply enough information.

CMC_SEND_UI_REQUESTED

Displays a dialog box to prompt for recipients, message field information, and other sending options. If this flag is not set, cmc_send_documents does not display a dialog box but must specify at least one recipient.

file_paths

[in] Pointer to the actual path for the attachment file. When the client application specifies multiple paths, it should separate the names using the character indicated by the delimiter parameter.

attach_titles

[in] Pointer to the title of the attachment displayed for the recipient. When the client application specifies multiple titles, it should separate the titles using the character indicated by the delimiter parameter.

delimiter

[in] Pointer to a character used to delimit the names in the file_paths, attach_titles, and recipient_addresses strings. The client application should choose a character that is not used in operating system filenames or recipient names. This parameter cannot be NULL.

ui_id

[in] Handle of a dialog box for cmc_send_documents to present to help resolve processing questions or prompt the user for additional information as required.

Return Values

CMC_E_ATTACHMENT_NOT_FOUND

The specified attachment was not found as specified.

CMC_E_ATTACHMENT_OPEN_FAILURE

The specified attachment was found but could not be opened, or the attachment file could not be created.

CMC_E_ATTACHMENT_READ_FAILURE

The specified attachment was found and opened, but there was an error reading it.

CMC_E_ATTACHMENT_WRITE_FAILURE

The attachment file was created successfully, but there was an error writing it.

CMC_E_COUNTED_STRING_NOT_SUPPORTED

The current implementation does not support counted strings.

CMC_E_FAILURE

There was a general failure that does not fit the description of any other return value.

CMC_E_INSUFFICIENT_MEMORY

Insufficient memory was available to complete the requested operation.

CMC_E_INVALID_FLAG

A flag set using a flags parameter was invalid.

CMC_E_INVALID_PARAMETER

A function parameter was invalid.

CMC_E_INVALID_UI_ID

The specified user-interface identifier is invalid or no longer valid.

CMC_E_LOGON_FAILURE

The service, user name, or password specified was invalid, so logon cannot be completed.

CMC_E_RECIPIENT_NOT_FOUND

One or more of the specified recipients were not found.

CMC_E_TEXT_TOO_LARGE

The size of the text string passed to the current implementation is too large.

CMC_E_TOO_MANY_FILES

The current implementation cannot support the number of files specified.

CMC_E_TOO_MANY_RECIPIENTS

The current implementation cannot support the number of recipients specified.

CMC_E_UNSUPPORTED_FLAG

The current implementation does not support the flag requested.

CMC_E_USER_CANCEL

The operation was canceled by the user.

CMC_E_USER_NOT_LOGGED_ON

The user was not logged on and the CMC_LOGON_UI_ALLOWED flag was not set.

Remarks

The cmc_send_documents function is primarily useful for calls from a scripting language application, such as a spreadsheet application using macros, that cannot handle data structures. The cmc_send_documents function tries to establish a session without a logon dialog box. If this is not possible, it prompts the user for logon information to establish a session. Before the function returns, it closes the session.


Structures and Data Types

The following data structures and simple data types are used by the CMC implementation to pass information in to and out of CMC functions. Wherever possible, you should use these types to maintain compatibility with different CMC implementations.The structures and data types are listed in alphabetical order.


BYTE

BYTE is an unsigned character data type that is binary data.

Quick Info

Header file:	WINDEF.H
typedef unsigned char     BYTE;


CMC_attachment

A CMC_attachment structure contains a CMC message attachment.

Quick Info

Header file:	XCMC.H
typedef struct

{

     CMC_string     attach_title;

     CMC_object_identifier attach_type;

     CMC_string     attach_filename;

     CMC_flags attach_flags;

     CMC_extension FAR     *attach_extensions;

} CMC_attachment;

Members

attach_title

The optional title for the attachment, for example the original filename of the attachment.

attach_type

Object identifier that specifies the attachment type. Two attachment types have been defined for use by client applications:

CMC_ATT_OID_BINARY

Data in a file is treated as binary data. This attachment type is the default.

CMC_ATT_OID_TEXT

Data in a file is treated as a text string. This attachment type assumes that data exists in the character set for the session on input and maps to the character set for the session on output, if possible.

A NULL value for attach_type indicates an attachment of an undefined type.

attach_filename

Name of the file in which attachment content is located. The location of the file depends on the CMC implementation, which ensures access by the client application.

attach_flags

Bitmask of flags used to describe attachment options. The following flags can be set:

CMC_ATT_APP_OWNS_FILE

On output, the client application owns the attachment and is responsible for deleting it. This flag is ignored on input. If the flag is not set, it indicates on output that the CMC implementation owns the file and the client application can only read it.

CMC_ATT_LAST_ELEMENT

The last structure in an array of CMC_attachment structures. The structure with this flag set must be at the end of the array. If this flag is set to zero for any structure, that structure is not the last array element.

attach_extensions

Pointer to the first element in an array of CMC_extension structures, each of which is specific to an attachment. Attachment extensions exist to support graphic representation of the attachments in a message when it is displayed. The extensions contain the character positions for the graphic representations. A pointer value of NULL indicates that no extensions are present.

Remarks

A CMC_message structure, which contains information about a CMC message, contains a pointer to an array of one or more CMC_attachment structures defining attachments for the message, or is NULL if there are no attachments. The array elements should have the same order as the attachments in the message, and the last element in the array should have the CMC_ATT_LAST_ELEMENT flag set in its attach_flags member.

See Also

CMC_extension, CMC_message


CMC_boolean

CMC_boolean is a CMC unsigned integer data type that is a Boolean value.

Quick Info

Header file:	XCMC.H
typedef      CMC_uint16      CMC_boolean;

Remarks

The CMC_boolean data type can contain the symbolic constants CMC_TRUE and CMC_FALSE. The C interface denotes FALSE by using 0 and TRUE by using any other integer. CMC denotes CMC_FALSE by using 0, in line with C interface usage. However, CMC_TRUE is denoted specifically bythe integer 1.


CMC_buffer

CMC_buffer is a CMC data type that points to a memory storage location of an undefined type and size.

Quick Info

Header file:	XCMC.H
typedef      void *CMC_buffer;


CMC_counted_string

A CMC_counted_string structure is an optional structure supporting character sets that allow embedded null characters. The structure contains a counted string and explicitly defines the length of the string.

Quick Info

Header file:	XCMC.H
typedef struct {

     CMC_uint32     length;

     char      string[1];

} CMC_counted_string;

Members

length

The length, in bytes, of the string specified by the string member.

string

An array of characters that make up the string. CMC does not require the string to be null-terminated.

Remarks

If a client application uses counted strings instead of null-terminated strings, it must set the CMC_COUNTED_STRING_TYPE flag in the cmc_logon function’s logon_flags parameter when logging on to a MAPI session through cmc_logon. The data pointed to by a string of type CMC_string is then assumed to be defined as a CMC_counted_string structure.

To determine the character set of a string, the CMC implementation looks at the information for a session identified by a CMC_session_id data type. CMC implementations always attempt to map all strings passed to the client application to the character set for the session. If no session has been created by a call to cmc_logon, CMC interprets the string by using the implementation’s default character set.

See Also

CMC_string


CMC_enum

CMC_enum is a CMC data type that is an enumerated data value.

Quick Info

Header file:	XCMC.H
typedef      CMC_sint32          CMC_enum;

Remarks

A variable of this type contains a value selected from an enumeration.


CMC_extension

A CMC_extension structure contains a CMC data extension for use by the CMC API functions and data structures. A CMC data extension adds parameters to functions or members to data structures.

Quick Info

Header file:	XCMC.H
typedef struct {

     CMC_uint32 item_code;

     CMC_uint32 item_data;

     CMC_buffer item_reference;

     CMC_flags extension_flags;

} CMC_extension;

Members

item_code

Code that uniquely identifies an extension to a function or data structure. The item_code member is the mechanism for specifying the extension to be invoked. The client application puts the extension code in this member before calling CMC functions that use extensions. The possible extensions are:

CMC_X_COM_ATTACH_CHARPOS	CMC_X_COM_CAN_SEND_RECIP
CMC_X_COM_CONFIG_DATA	CMC_X_COM_PRIORITY
CMC_X_COM_RECIP_ID	CMC_X_COM_SAVE_MESSAGE
CMC_X_COM_SENT_MESSAGE	CMC_X_COM_SUPPORT_EXT
CMC_X_COM_TIME_RECEIVED	CMC_X_MS_ADDRESS_UI
CMC_X_MS_ATTACH_DATA	CMC_X_MS_FUNCTION_FLAGS
CMC_X_MS_MESSAGE_DATA	CMC_X_MS_SESSION_FLAGS
These extensions are identified by the extension identifiers CMC_XS_COM and CMC_XS_MS. For definitions of these extensions, see Data Extensions.

item_data

Item data for the extension. Depending on the value of item_code, the item_data member might contain the length of the item value, the item value itself, or other information about the item. The specification of the extension describes the interpretation of this member.

item_reference

The item reference for the extension. This value is a pointer to the storage location of the item value. It is NULL if there is no related item storage. The specification of the extension describes the interpretation of this member.

extension_flags

Bitmask of extension flags. The following flags can be set:

CMC_EXT_LAST_ELEMENT

The last structure in an array of CMC_extension structures. The structure with this flag set must be at the end of the array. If this flag is set to zero for any structure, that structure is not the last array element.

CMC_EXT_OUTPUT

For an output extension, the extension structure contains a pointer to implementation-allocated memory that the client application must release with the cmc_free function. If this flag is set to zero, the implementation has not allocated memory for the extension that the application needs to free. This flag is always set to zero for structure extensions.

CMC_EXT_REQUIRED

An error value is returned if this extension cannot be supported. If this flag is set to zero, it enables the CMC implementation to provide any level of support, including no support, for the extension.

Remarks

Extensions are used to add functionality to the CMC API. For example, a client application can implement the cmc_act_on function to allow saving a partially completed message in the receive folder (the Inbox) for later updating and sending. To pass the structure defining this partially completed message to CMC and receive back the resulting message reference, the client application can use the CMC_X_COM_SAVE_MESSAGE extension.

An extension can be either an input extension or an output extension; that is, it can be passed either as input from a client application to CMC or as output from CMC to a client application. Whether the information contained in an extension is input or output is implied by the semantics of the particular extension in question and by the presence or absence of CMC_EXT_OUTPUT in the extension’s extension_flags member after a call to a CMC function. For input extensions, the client application in question allocates memory for the extension structure and any other structures associated with the extension. For output extensions, storage for the extension result, if necessary, is allocated by a CMC function.

For output extensions, a client application must free storage allocated by CMC with calls to the cmc_free function. For each CMC_extension structure in the array, the caller must call cmc_free for the pointer in the item_reference member of the structure.

CMC does not require explicit release of a data extension structure, because CMC releases such structures along with the structures that contain them. For example, CMC implicitly releases the message extension array created by the cmc_read function when calling cmc_free for the enclosing CMC_message structure.

See Also

cmc_act_on, cmc_free, CMC_message, cmc_read


CMC_flags

CMC_flags is a CMC data type that is a bitmask of flags.

Quick Info

Header file:	XCMC.H
typedef          CMC_uint32     CMC_flags;

Remarks

A bitmask of this type contains 32 flag bits. The CMC implementation reserves the upper 16 bits for definition by the CMC specification. Any unused bits among the upper 16 must be clear. The implementation reserves the lower 16 flag bits for definition by a CMC data extension.

The meanings of these CMC flags depend on the context in which the client application uses them. CMC reserves all undocumented flags. Unspecified flags should always be set to zero.


CMC_message

A CMC_message structure contains information about a CMC message.

Quick Info

Header file:	XCMC.H
typedef struct {

     CMC_message_reference     *message_reference;

     CMC_string     message_type;

     CMC_string subject;

     CMC_time      time_sent;

     CMC_string text_note;

     CMC_recipient *recipients;

     CMC_attachment     *attachments;

     CMC_flags message_flags;

     CMC_extension *message_extensions;

} CMC_message;

Members

message_reference

Pointer to the message reference, which is a counted string (that is, a CMC_counted_string structure). The message reference is a unique identifier for a message within a mailbox.

message_type

Pointer to a string that identifies the type of the message. Three different string identifiers are available:

•	Object identifiers, which are used for message types identified by object identifiers as defined in CCITT Recommendation X.208.

•	CMC registered values, which are used for message types defined in the CMC specification.

•	Bilaterally defined values, which are used for message types that are unregistered. CMC does not ensure that bilaterally defined values are unique.

For the complete specification of CMC message types, see “Remarks.”

subject

Pointer to a string describing the subject of the message.

time_sent

The CMC_time structure containing the date and time when the client application submits the message to the CMC implementation.

text_note

Pointer to the string containing the message text. If the value of this member is NULL, there is no message text. If the CMC_MSG_TEXT_NOTE_AS_FILE flag is set for the message_flags member, the message text is in the first attachment to the message. For information on message text format, see “Remarks.”

recipients

Pointer to the first element in an array of CMC_recipient structures defining the message recipients.

attachments

Pointer to the first element in an array of CMC_attachment structures defining the attachments to the message.

message_flags

Bitmask of message flags. The following flags can be set:

CMC_MSG_LAST_ELEMENT

The last element in an array of CMC_message structures. The structure with this flag set must be at the end of the array. If this flag is set to zero for any structure, that structure is not the last array element.

CMC_MSG_READ

The message has been read. If this flag is set to zero, the message has not been read.

CMC_MSG_TEXT_NOTE_AS_FILE

The text_note member is ignored and the message text is contained in the file referred to by the first attachment. If this flag is set to zero, the message text is contained in the text_note member.

CMC_MSG_UNSENT

The client application has not sent the message, for example when the message is a draft. The sender can create such a message with the CMC_X_COM_SAVE_MESSAGE data extension. If this flag is set to zero, the client application has sent the message.

message_extensions

Pointer to the first structure in an array of CMC_extension structures representing the message extensions.

Remarks

Message types are used to distinguish between various sorts of messages that might require different processing. For example, the message type might be used by the client application to determine how to display the message or by CMC to determine how to send the message.

CMC message types possible in the message_type member of a CMC_message structure can have the following formats and are case-insensitive.

"OID: " + object_identifier

"CMC: " + cmc_registered_value

"BLT: " + string

An object_identifier is a string containing a series of whitespace separated integers. See CMC_object_identifier for details.

The following is a list of message types

IPM

Interpersonal message. An interpersonal message is a memo-like message containing a recipient list, an optional subject, an optional text note, and zero or more attachments. The CMC_message structure is optimized to accommodate a message with the registered value IPM.

IP RN

Read notification for an interpersonal message. A read notification indicates the recipient has opened a message.

IP NRN

Nonread notification for an interpersonal message. A nonread notification indicates a message has been removed from the recipient’s mailbox without being opened. For instance, the service or user has discarded the message or it has been automatically forwarded to another recipient.

DR

Delivery report. A delivery report indicates the service was able to deliver a message to its recipient.

NDR

Nondelivery report. A nondelivery report indicates the message service was not able to deliver a message to its recipient.

Bilaterally defined values are arbitrary strings and are used to identify custom message types used by the client application.

As the syntax preceding indicates, the OID: type identifier indicates a type identified by an object identifier, the CMC: type identifier indicates a type identified by a CMC registered value, and the BLT: type identifier indicates a type identified by a bilaterally defined value. Following are examples of valid type identifiers:

OID: 1 2 840 113556 3 2 850

CMC: IPM

BLT: my special message type

You can format type identifiers as you choose; the CMC implementation also defines a canonical type identifier format that allows a client application to easily compare type identifier strings. The CMC implementation always returns type identifiers in this format, which guarantees the following:

•	All tokens are separated with a single space.

•	The type identifiers OID:, CMC:, and BLT: are returned in uppercase.

The CMC specification does not define what it will do with type identifier strings that are not in this format.

The formats of messages with the preceding registered values within a CMC_message structure depend on the messaging protocols employed by the underlying messaging system. Often, non-IPM messages take the form of a program-generated message, which follows a memo-like format similar to an IPM format but serves instead to convey information about a previously sent message.

Note  The cmc_registered_value types correspond to X.400 message types; however, non-X.400 messaging systems can also use them. Thus, these message types are meant to apply generically and not specifically to X.400 services.

Some implementations only support the interpersonal message type (CMC: IPM). Some implementations might treat messages of types other than IPM as IPM messages or might generate an error for such messages.

For the text_note member, the format of the message text is a sequence of paragraphs, whether it is passed in memory or in a file. Each paragraph is terminated with the appropriate line terminator for the platform: CR (carriage return) for Macintosh, LF (linefeed) for UNIX, and CR/LF for MS-DOS and Windows. The CMC implementation can word-wrap long lines (paragraphs). There is no guarantee that paragraph formatting will remain constant when a message is saved and read back. For example, the cmc_read function can return a long paragraph as a series of shorter paragraphs.

See Also

CMC_attachment, CMC_extension, CMC_recipient, cmc_send, CMC_time


CMC_message_reference

A CMC_message_reference structure is a CMC_counted_string structure containing a message reference, which is the identifier for a message within a message store.

Quick Info

Header file:	XCMC.H
typedef          CMC_counted_string     CMC_message_reference;

Remarks

The CMC implementation only guarantees the message reference to be valid for the life of the session. The message reference is specific to the message store; CMC does not guarantee that the reference has any correspondence to a message identifier used by the underlying messaging system. Only during the current session can the client application expect the message reference to refer to the same message.


CMC_message_summary

A CMC_message_summary structure contains a summary of a message. A message summary includes the type of the message, a reference to it for later retrieval, the size of the message, and other information. Message summaries are useful for previewing messages on low-bandwidth networks without actually retrieving the entire message.

Quick Info

Header file:	XCMC.H
typedef struct {

     CMC_message_reference     *message_reference;

     CMC_string     message_type;

     CMC_string     subject;

     CMC_time      time_sent;

     CMC_uint32     byte_length;

     CMC_recipient     *originator;

     CMC_flags     summary_flags;

     CMC_extension     *message_summary_extensions;

} CMC_message_summary;

Members

message_reference

Pointer to the message reference, a CMC_counted_string structure containing the mailbox identifier for a message. The message reference is unique within a mailbox.

message_type

Pointer to a string that identifies the type of the message. See CMC_message for details.

subject

Pointer to a string containing the subject of the message.

time_sent

A CMC_time structure containing the date and time when the client application submits the message to the CMC implementation.

byte_length

The message size, in bytes. The value should include the size of all the associated features of the message such as attachments and envelope and heading fields. A client application can supply an approximate message size, or if the message size is unknown or unavailable, the value CMC_LENGTH_UNKNOWN.

originator

Pointer to a CMC_recipient structure indicating the message sender.

summary_flags

Bitmask of message summary flags. The following flags can be set:

CMC_SUM_LAST_ELEMENT

The last structure in an array of CMC_message_summary structures. The structure with this flag set must be at the end of the array. If this flag is set to zero for any structure, that structure is not the last array element.

CMC_SUM_READ

The message has been read. If this flag is set to zero, the message has not been read.

CMC_SUM_UNSENT

The client application has not sent the message, for example when the message is a draft. If this flag is set to zero, the client application has sent the message.

message_summary_extensions

Pointer to the first structure in an array of CMC_extension structures representing the message-summary data extensions, if any.

See Also

CMC_extension


CMC_object_identifier

CMC_object_identifier is a data type that is a CMC object identifier string.

Quick Info

Header file:	XCMC.H
typedef          CMC_string     CMC_object_identifier;

Remarks

An identifier of this type is globally unique. Its syntax must match the format defined in CCITT Recommendation X.208. This syntax is:

object_identifier          ::= object_id_component*

object_id_component          ::= integer

Namely, the object identifier is a sequence of whitespace separated integers.

The following is an example of an object identifier:

1 2 840 113556 3 2 850

Note  The format of the object identifier string is the same as that used in the OID message type. For more information on message types, see CMC_message.

See Also

CMC_message


CMC_recipient

A CMC_recipient structure contains information about a messaging user, either a message recipient or the message sender.

Quick Info

Header file:	XCMC.H
typedef struct {

     CMC_string     name;

     CMC_enum      name_type;

     CMC_string     address;

     CMC_enum role;

     CMC_flags recip_flags;

     CMC_extension *recip_extensions;

} CMC_recipient;

Members

name

Pointer to a string that identifies the recipient or sender display name. When the CMC implementation resolves the name to an address, it determines whether it should interpret the name as the name of an individual first and then as the name of a group if the individual name is not found, or vice versa, according to the value of the name_type member.

name_type

Enumeration that indicates whether the structure contains information for a message recipient or a message sender. Possible values are:

CMC_TYPE_GROUP

The recipient or sender name belongs to a distribution list.

CMC_TYPE_INDIVIDUAL

The recipient or sender name belongs to an individual messaging user.

CMC_TYPE_UNKNOWN

An unknown recipient or originator name.

The name_type member is meaningful only if the name member is present. The CMC implementation sets name_type on output. On input, the name_type information can be used by the addressing mechanism in the message service to optimize resolution of the name.

address

Pointer to a recipient or sender address string in a format recognized by the underlying messaging system. CMC does not define the format of the string. This member therefore accommodates any string notations supported by the CMC implementation, as configured at installation.

role

Enumeration that indicates the role of the message recipient or sender. Possible values are:

CMC_ROLE_AUTHORIZING_USER

The user authorizing the message, in cases of messages sent by proxy or in the name of another user.

CMC_ROLE_BCC

A blind carbon copy (BCC) recipient.

CMC_ROLE_CC

A carbon copy (CC) recipient.

CMC_ROLE_ORIGINATOR

The sender of the message.

CMC_ROLE_TO

A primary recipient.

recip_flags

Bitmask of recipient flags. The following flags can be set:

CMC_RECIP_IGNORE

CMC should ignore the specified recipient. This flag is useful for reusing an incoming message’s recipient list for a reply. If this flag is set to zero, it indicates that the recipient should not be ignored.

CMC_RECIP_LAST_ELEMENT

The last structure in an array of CMC_recipient structures. The structure with this flag set must be at the end of the array. If this flag is set to zero for any structure, that structure is not the last array element.

CMC_RECIP_LIST_TRUNCATED

CMC has not written all recipient or originator structures requested. The client application uses this flag only for the cmc_look_up function when the complete list of recipients matching the search name cannot be written. The function only sets this flag in the last structure in the array of CMC_recipient structures. If the flag is set to zero, cmc_look_up has written a complete recipient array.

recip_extensions

Pointer to the first structure in an array of CMC_extension structures that contain the recipient or sender data extensions, if any.

Remarks

If the underlying messaging system does not support carbon copy recipients, CMC can convert such a recipient to a primary recipient. Services that cannot support blind carbon-copy recipients should reject messages containing them. If a user designates the same recipient in more than one role, the client application should place multiple recipient entries in the recipient list, each differing from the others in role.

On output, the CMC implementation writes an array of CMC_recipient structures in a specific order. The message sender’s structure should be the first element in the array, followed by the primary, carbon copy, and blind carbon-copy recipient structures grouped together in that order. If there is an authorizing user structure, it should be the final element in the array. The CMC implementation does not require ordering of the CMC_recipient structures on input.

See Also

CMC_extension, cmc_look_up


CMC_return_code

CMC_return_code is a data type that is a 32-bit value returned by a CMC function.

Quick Info

Header file:	XCMC.H
typedef      CMC_uint32          CMC_return_code;

Remarks

A nonzero return value for a CMC function indicates an error and is associated with one of the defined CMC return values. A return value of zero for a function indicates success. The CMC implementation reserves values in the low-order 16 bits of the return value for standard CMC-defined error values. The high-order 16 bits of the return value are reserved for error values that are defined specifically for the implementation.

CMC client applications can resolve errors within the scope of the CMC implementation. For example, a client application can resolve errors by prompting the user with a dialog box defined through the CMC user interface. If the error remains unresolved after the dialog box has closed, CMC sets the CMC_ERROR_UI_DISPLAYED flag in the return value to indicate that a dialog box regarding the error has already been displayed.


CMC_session_id

CMC_session_id is a data type that is a 32-bit CMC session handle.

Quick Info

Header file:	XCMC.H
typedef      uint32          CMC_session_id;

Remarks

The context identified by the session handle contains information about the current session, such as the character set in use and handles for any open sessions with underlying message services. The cmc_logon function creates the CMC session handle, and the cmc_logoff function invalidates it.

See Also

cmc_logoff, cmc_logon


CMC_string

CMC_string is a CMC data type that is a pointer to a character string.

Quick Info

Header file:	XCMC.H
typedef      char      *CMC_string;

Remarks

By default, the CMC implementation interprets the string that this data type points to as a null-terminated array of characters. The chosen character set determines the width of a character and the corresponding null-terminating character.

If a client application uses counted strings instead of null-terminated strings, it must set the CMC_COUNTED_STRING_TYPE flag in the logon_flags parameter when logging onto a MAPI session through cmc_logon. The data pointed to by a string of type CMC_string is then defined as a CMC_counted_string structure.

To determine the character set of characters in the string, the CMC implementation looks at the character set in the session attributes, which are chosen by the client application when the call to cmc_logon is made. CMC always attempts to map all strings passed to the client application to the character set for the session. If the client application has not called cmc_logon and is using an implicit session, the CMC implementation interprets input strings by using its default character set.

See Also

CMC_counted_string, cmc_logon


CMC_time

A CMC_time structure contains a time value in CMC-compatible form for use in a message.

Quick Info

Header file:	XCMC.H
typedef struct{

     CMC_sint8     second;

     CMC_sint8     minute;

     CMC_sint8     hour;

     CMC_sint8     day;

     CMC_sint8     month;

     CMC_sint8     year;

     CMC_sint8     isdst;

     CMC_sint8      unused1;

     CMC_sint16     tmzone;

     CMC_sint16     unused2;

} CMC_time;

Members

second

Seconds; possible values range from 0 through 59.

minute

Minutes; possible values range from 0 through 59.

hour

Hours since midnight; possible values range from 0 through 23.

day

Day of the month; possible values range from 1 through 31.

month

Months since January; possible values range from 0 through 11.

year

Years since 1900.

isdst

Value for daylight saving time. A nonzero value means daylight saving time is in force.

unused1

Reserved. Do not use.

tmzone

Time zone, measured in minutes relative to Greenwich mean time. The value CMC_NO_TIMEZONE indicates that time zone information is not available.

unused2

Reserved. Do not use.

Remarks

The CMC time implementation is based on the assumption that all time values reflect the appropriate local time. For example, the time_sent members in the CMC_message and CMC_message_summary structures reflect the local time of the sender’s location.

See Also

CMC_message, CMC_message_summary


CMC_ui_id

CMC_ui_id is a data type that is a CMC user interface handle.

Quick Info

Header file:	XCMC.H
typedef CMC_uint32          CMC_ui_id;

Remarks

The CMC implementation uses a data value of this type for passing user interface information to CMC functions. For example, in a Windows-based operating environment, the parent window handle for the client application is a data value of this type.

A value of NULL for CMC_ui_id is always valid. The CMC implementation defines a default behavior. For example, some implementations might treat NULL as a request to use a user interface defined within the implementation, while other implementations might not have any internally defined interface at all.


CMC_X_COM_configuration

A CMC_X_COM_configuration structure contains configuration data written by the cmc_query_configuration function for the CMC_X_COM_CONFIG_DATA data extension.

Quick Info

Header file:	XCMCEXT.H
typedef struct {

     CMC_uint16          ver_spec;

     CMC_uint16          ver_implem;

     CMC_object_identifier     *character_set;

     CMC_enum               line_term;

     CMC_string          default_service;

     CMC_string          default_user;

     CMC_enum               req_password;

     CMC_enum               req_service;

     CMC_enum               req_user;

     CMC_boolean          ui_avail;

     CMC_boolean          sup_nomkmsgread;

     CMC_boolean          sup_counted_str;

} CMC_X_COM_configuration;

Members

ver_spec

A CMC specification version number.

ver_implem

A CMC version number multiplied by 100. For example, version 1.00 is represented as 100.

character_set

Pointer to a CMC_object_identifier structure.

line_term

Enumeration that indicates the type of line delimiter for the message text in a CMC_message. Possible values are:

CMC_LINE_TERM_CRLF

The line delimiter is a carriage return followed by a line feed.

CMC_LINE_TERM_LF

The line delimiter is a line feed.

CMC_LINE_TERM_CR

The line delimiter is a carriage return.

default_service

Pointer to a string identifying the default message service.

default_user

Pointer to a string identifying the default user name of the user accessing the CMC implementation. This default can be used when prompting the user for a user name.

req_password

Enumeration that indicates if a password is required to access the service. Possible values are:

CMC_REQUIRED_NO

No password is required.

CMC_REQUIRED_YES

A password is required.

CMC_REQUIRED_OPT

A password is optional.

req_service

Enumeration that indicates if the message service name is required for logon. Possible values are:

CMC_REQUIRED_NO

No service name is required.

CMC_REQUIRED_YES

A service name is required.

CMC_REQUIRED_OPT

A service name is optional.

req_user

Enumeration that indicates if the messaging user name is required for logon. Possible values are:

CMC_REQUIRED_NO

No user name is required.

CMC_REQUIRED_YES

A user name is required.

CMC_REQUIRED_OPT

A user name is optional.

ui_avail

Boolean value that is TRUE if the CMC implementation in use provides a user interface and FALSE otherwise.

sup_nomkmsgread

Boolean value that indicates whether the cmc_read function supports not marking messages as read. The value is TRUE if the cmc_read function supports the CMC_DO_NOT_MARK_AS_READ flag and FALSE otherwise.

sup_counted_str

Boolean value that indicates whether the cmc_logon function supports the use of the CMC_counted_string type. The value is TRUE if the cmc_logon function supports the CMC_COUNTED_STRING_TYPE flag and FALSE otherwise.

Remarks

The cmc_query_configuration function writes a value into the buffer pointed to by its reference parameter. That value is a copy of a particular member of the CMC implementation’s CMC_X_COM_configuration structure, depending on the value the client application passes for the item parameter. For example, to see whether the CMC implementation defines its own user interface for logon and error resolution, the client application should use CMC_CONFIG_UI_AVAIL as the value of item. When cmc_query_configuration returns, the CMC_buffer pointed to by reference will contain TRUE or FALSE to indicate whether an interface is available. The client application must ensure that the reference parameter points to a buffer of sufficient size to hold the type of data that the item parameter specifies.

See Also

cmc_free, cmc_logon, CMC_object_identifier, cmc_query_configuration, cmc_read, CMC_X_COM_CONFIG_DATA


CMC_X_COM_support

A CMC_X_COM_support structure contains information about MAPI support for a particular CMC data extension or extension set, and is used in an array pointed to by the item_reference member of a CMC_extension structure.

Quick Info

Header file:	XCMCEXT.H
typedef struct {

     CMC_uint32 item_code;

     CMC_flags flags;

} CMC_X_COM_support;

Members

item_code

Code for the CMC data extension whose support the client application is querying about. The client application sets this member during calls to the cmc_logon and cmc_query_configuration functions. The possible extensions are:

CMC_XS_COM	CMC_X_COM_ATTACH_CHARPOS
CMC_X_COM_CAN_SEND_RECIP	CMC_X_COM_CONFIG_DATA
CMC_X_COM_PRIORITY	CMC_X_COM_RECIP_ID
CMC_X_COM_SAVE_MESSAGE	CMC_X_COM_SENT_MESSAGE
CMC_X_COM_SUPPORT_EXT	CMC_X_COM_TIME_RECEIVED
CMC_XS_MS	CMC_X_MS_ADDRESS_UI
CMC_X_MS_ATTACH_DATA	CMC_X_MS_FUNCTION_FLAGS
CMC_X_MS_MESSAGE_DATA	CMC_X_MS_SESSION_FLAGS
flags

Bitmask of extension code flags. The following flags can be set:

CMC_X_COM_SUP_EXCLUDE

On input this flag removes the item represented by the value of the item_code member from consideration when deciding whether the implementation supports an extension set. If this flag is set on input for the cmc_logon function, the implementation will not attach the item to extension structures for this session even if other entries request it. If this flag is set on input, then none of the remaining flags in this list will be set on output.

CMC_X_COM_SUPPORTED

The CMC implementation supports the item represented by the item_code member. For whole extension sets (for example, CMC_XS_COM), this flag indicates the CMC implementation supports all the function and structure extensions in the set.

CMC_X_COM_NOT_SUPPORTED

The CMC implementation does not support the item represented by the item_code member. If this flag applies to a whole extension set containing both function and structure extensions, it indicates the CMC implementation does not support some or all function and structure extensions in the set. If this flag applies to a structure extension or an extension set containing structure extensions, it indicates the CMC implementation will not attach the structure extensions to structures for this session.

CMC_X_COM_DATA_EXT_SUPPORTED

The CMC implementation supports all requested structure extensions for an extension set. The client application must request function extensions separately. When the cmc_logon function returns this flag, the implementation will attach structure extensions to structures for this session.

CMC_X_COM_FUNC_EXT_SUPPORTED

The CMC implementation supports all requested function extensions for an extension set. The client application must request structure extensions separately. Unlike the CMC_X_COM_SUPPORTED flag, if the cmc_logon function returns this flag, structure extensions will not be attached to structures for this session and must be requested separately.

See Also

CMC_extension,cmc_logon, CMC_X_COM_SUPPORT_EXT


CMC_X_MS_ATTACH

CMC_X_MS_ATTACH data structures are used by the CMC_X_MS_ATTACH_DATA and CMC_X_MS_ATTACH_MESSAGE extensions to support message attachments.

Quick Info

Header file:	XCMCMSX2.H
typedef struct {

     CMC_message_reference FAR * message;

     CMC_uint32 id;

     CMC_buffer object;

} CMC_X_MS_ATTACH;


Data Extensions

The functionality of the CMC data structures and functions can be augmented through the use of CMC data extensions. Data extensions are used to add additional fields to data structures and additional parameters to a function.

A standard generic data structure, CMC_extension, specifies the item code, item data, item reference, and a bitmask of flags. The item code is the name of the extension and is used to identify it. The item data, depending on the item code, contains either the length of the item value, the item value itself, or other information about the item. The item reference points to where the extension value is stored or is NULL if there is no related item storage. The flags are set to zero or to values that describe options for the extension. To use an extension in a CMC function, a client application sets the item code member of a CMC_extension structure to a valid name and passes the structure as part of the parameter list.

Extensions that are additional parameters to a function can be either input or output parameters. If the extension is passed as an input parameter, the calling client application or service provider allocates memory for the CMC_extension structure and any other structures that are associated with the extension. If the extension is passed as an output parameter, CMC allocates the storage for the extension result and the caller frees it by calling the cmc_free function.

The following extensions make up the CMC common extension set, the extensions that are common to most CMC implementations but are not in the CMC base specification. The extensions are listed in alphabetical order. Each reference entry describes the purpose of the extension.


CMC_XS_COM

CMC_XS_COM is a CMC extension identifier used for all extensions in the common extension set, that is the extensions that are common to most CMC implementations but are not in the CMC base specification. For a complete list of common extensions, see CMC_X_COM_support.

Quick Info

Header file:	XCMCEXT.H
See Also

cmc_logon, cmc_query_configuration, CMC_X_COM_SUPPORT_EXT


CMC_X_COM_ATTACH_CHARPOS

CMC_X_COM_ATTACH_CHARPOS is a CMC extension that supports display of a graphical representation (usually an icon) of an attachment in the message text. The extension holds the character position for the representation.

Quick Info

Header file:	XCMCEXT.H
Input Usage

item_data

Zero-based character offset of the attachment within the message text. Note that this offset is a character offset, not a byte offset (an important distinction when multibyte character sets are in use).

item_reference

NULL.

extension_flags

All flags used with the CMC_extension structure are valid. No further flags are defined.

Output Usage

item_data

Zero-based character offset of the attachment.

item_reference

Unchanged.

extension_flags

Unchanged.

Adds to

The CMC_attachment structure.

Remarks

At logon, CMC passes the CMC_X_COM_ATTACH_CHARPOS item_data member and any flags in a CMC_X_COM_support structure. Doing so indicates that CMC supports the CMC_X_COM_ATTACH_CHARPOS extension and that the client application can attach a CMC_extension containing an item code and a graphic representation to the CMC_attachment structure during the session.

See Also

CMC_attachment, CMC_extension, CMC_X_COM_support


CMC_X_COM_CAN_SEND_RECIP

CMC_X_COM_CAN_SEND_RECIP is a CMC extension that checks whether the message service is ready to send to the specified recipient.

Quick Info

Header file:	XCMCEXT.H
Input Usage

item_data

Zero.

item_reference

NULL. On input to the cmc_look_up function, the recipient_in parameter contains the recipient about which the message service is being queried. If there is more than one recipient passed in recipient_in, cmc_look_up only looks at the first recipient.

extension_flags

All flags used with the CMC_extension structure are valid. No further flags are defined.

Output Usage

item_data

Bitmask of extension flags. The following flags can be set:

CMC_X_COM_DEFER

The service provider will accept the message but defer it until a transport provider is ready.

CMC_X_COM_NOT_READY

No transport provider is available for the specified recipient type.

CMC_X_COM_READY

The message can be sent immediately.

item_reference

Unchanged.

extension_flags

Unchanged.

Adds to

The cmc_look_up function.

See Also

CMC_extension, cmc_look_up


CMC_X_COM_CONFIG_DATA

CMC_X_COM_CONFIG_DATA is a CMC extension that obtains all available configuration information.

Quick Info

Header file:	XCMCEXT.H
Input Usage

item_data

Zero.

item_reference

NULL.

extension_flags

All flags used with the CMC_extension structure are valid. No further flags are defined.

Output Usage

item_data

Unchanged.

item_reference

Pointer to a CMC_X_COM_configuration structure containing all the information available from the cmc_query_configuration function.

extension_flags

Bitmask of extension flags. If the call successfully returns a structure, the function sets the CMC_EXT_OUTPUT flag.

Adds to

The cmc_query_configuration function.

Remarks

The buffer pointed to by the item_reference member should be freed with one call to cmc_free.

See Also

CMC_extension, cmc_query_configuration, CMC_X_COM_configuration


CMC_X_COM_PRIORITY

CMC_X_COM_PRIORITY is a CMC extension indicating message priority.

Quick Info

Header file:	XCMCEXT.H
Input Usage

item_data

Bitmask of extension flags. The following flags can be set:

CMC_X_COM_LOW

Indicates a low priority for the message.

CMC_X_COM_NORMAL

Indicates a normal priority for the message.

CMC_X_COM_URGENT

Indicates a high priority for the message.

item_reference

NULL.

extension_flags

All flags used with the CMC_extension structure are valid. No further flags are defined.

Output Usage

item_data

Bitmask of extension flags that describe the urgency of the message. The following flags can be set:

CMC_X_COM_LOW

A low priority for the message.

CMC_X_COM_NORMAL

A normal priority for the message.

CMC_X_COM_URGENT

A high priority for the message.

item_reference

Unchanged.

extension_flags

Unchanged.

Adds to

The CMC_message and CMC_message_summary structures.

Remarks

At logon, the caller passes CMC_X_COM_PRIORITY in the CMC_X_COM_SUPPORT_EXT extension to indicate that this extension should be attached to the CMC_message and CMC_message_summary structures during the session.

See Also

CMC_extension, CMC_message, CMC_message_summary, CMC_X_COM_SUPPORT_EXT.


CMC_X_COM_RECIP_ID

CMC_X_COM_RECIP_ID is a CMC extension that adds a unique recipient identifier to a CMC_recipient structure. A recipient identifier is an opaque object that the underlying messaging system uses to uniquely represent a recipient, and can be thought of as the result of resolving an address.

Quick Info

Header file:	XCMCEXT.H
Input Usage

item_data

The length in bytes of the recipient identifier.

item_reference

Pointer to the recipient identifier.

extension_flags

All flags used with the CMC_extension structure are valid. No further flags are defined.

Output Usage

item_data

The length in bytes of the recipient identifier.

item_reference

Pointer to the recipient identifier.

extension_flags

Unchanged.

Adds to

The CMC_recipient structure.

Remarks

The CMC implementation handles the CMC_X_COM_RECIP_ID extension during recipient name resolution. The client application can use this to avoid further name resolution during sending. Some message services allow the client application to reuse the recipient identifier returned by a previous call to cmc_look_up. The client application can attach it to a recipient structure that the service provider would otherwise try to resolve.

At logon, the client application passes the item_code member of CMC_X_COM_RECIP_ID in the CMC_X_COM_SUPPORT_EXT array to request that the CMC implementation should attach recipent identifiers to CMC_recipient structures during the session.

See Also

CMC_extension, CMC_recipient, CMC_X_COM_support


CMC_X_COM_SAVE_MESSAGE

CMC_X_COM_SAVE_MESSAGE is a CMC extension that saves a message (that is, a CMC_message structure) to the receive folder (the Inbox).

Quick Info

Header file:	XCMCEXT.H
Input Usage

item_data

Zero.

item_reference

Pointer to the CMC_message structure to save to the receive folder. To indicate that an unsent message has not been sent, the CMC implementation sets the CMC_MSG_UNSENT flag in the message_flags member of the CMC_message structure. To indicate that the operation to be performed (save to receive folder) is contained in a CMC_X_COM_SAVE_MESSAGE extension, the cmc_act_on function’s operation parameter must be set to the CMC_ACT_ON_EXTENDED flag.

extension_flags

All flags used with the CMC_extension structure are valid. No further flags are defined. To indicate that the CMC implementation should carry out a save action rather than a deletion, the flag CMC_EXT_REQUIRED must be set in the extension_flags member.

Output Usage

item_data

Unchanged.

item_reference

Pointer to the message reference of the message that was saved to the receive folder (the Inbox). The client application must free the message reference using the cmc_free function.

extension_flags

If cmc_act_on has successfully saved the message and returned the message reference, the CMC_EXT_OUTPUT flag is set.

Adds to

The cmc_act_on function.

See Also

cmc_act_on, CMC_extension, CMC_message, CMC_message_reference


CMC_X_COM_SENT_MESSAGE

CMC_X_COM_SENT_MESSAGE is a CMC extension that creates a CMC_message structure containing information for the message just sent.

Quick Info

Header file:	XCMCEXT.H
Input Usage

item_data

Zero.

item_reference

NULL.

extension_flags

All flags used with the CMC_extension structure are valid. No further flags are defined.

Output Usage

item_data

Unchanged.

item_reference

Pointer to a CMC_message structure containing information for the message just sent. The client application must free this pointer by calling the cmc_free function.

extension_flags

The cmc_send function has successfully put a pointer to a CMC_message structure in the item_reference parameter if the CMC_EXT_OUTPUT flag is set.

Adds to

The cmc_send function.

Remarks

CMC_X_COM_SAVE_MESSAGE is used to obtain information about a message that has just been sent when some or all of the members of the CMC_message structure are set by the user interface defined by the CMC implementation rather than by the client application before the cmc_send call.

See Also

CMC_extension, cmc_free, CMC_message, cmc_send


CMC_X_COM_SUPPORT_EXT

CMC_X_COM_SUPPORT_EXT is a CMC extension that client applications use to query the CMC implementation about the extensions it supports. If the implementation supports any extensions, it must support CMC_X_COM_SUPPORT_EXT.

Quick Info

Header file:	XCMCEXT.H
Input Usage

item_data

The number of items in an array pointed to by the item_reference member.

item_reference

Pointer to the first element in an array of CMC_X_COM_support structures listing extensions the client application requests the CMC implementation to support. See CMC_X_COM_support for details.

extension_flags

All flags used with CMC are valid. No further flags are defined.

Output Usage

item_data

Unchanged.

item_reference

Pointer to an array of CMC_X_COM_support structures where the CMC implementation sets the flags in the flags member to indicate support for the requested extensions. The implementation does not set these flags if CMC_X_COM_SUP_EXCLUDE was set on input. See CMC_X_COM_support for details.

extension_flags

Unchanged.

Adds to

The cmc_query_configuration and cmc_logon functions.

Remarks

Client applications can use this extension before establishing a session to get preliminary information about support before logging on. When a client application uses the extension with cmc_logon, it indicates which data extensions the client wants added to the data structures for the session.

Note  The CMC implementation supports different extensions, based on the service with which the client application creates a session. Thus client applications should use CMC_X_COM_SUPPORT_EXT at logon to verify extension support.

See Also

CMC_extension, cmc_logon, cmc_query_configuration, CMC_X_COM_support


CMC_X_COM_TIME_RECEIVED

CMC_X_COM_TIME_RECEIVED is a CMC extension that provides a CMC_time structure containing the delivery time of a message.

Quick Info

Header file:	XCMCEXT.H
Input Usage

CMC ignores this extension on input.

Output Usage

item_data

Zero.

item_reference

Points to the CMC_time structure containing the time the message was received.

extension_flags

NULL.

Adds to

The CMC_message and CMC_message_summary structures.

Remarks

At logon, the client application passes the CMC_X_COM_TIME_RECEIVED extension in the CMC_X_COM_SUPPORT_EXT array to indicate that the CMC implementation should attach this extension to CMC_message and CMC_message_summary structures during the session.

See Also

CMC_extension, CMC_message, CMC_message_summary, CMC_time, CMC_X_COM_support


CMC_XS_MS

CMC_XS_MS is a CMC extension identifier used for all extensions in the Microsoft extension set. For a full list of Microsoft extensions, see CMC_X_COM_support.

Quick Info

Header file:	XCMCMSXT.H
See Also

cmc_logon, cmc_query_configuration, CMC_X_COM_SUPPORT_EXT


CMC_X_MS_ADDRESS_UI

CMC_X_MS_ADDRESS_UI is a CMC extension that adds options to the address-book dialog box.

Quick Info

Header file:	XCMCMSXT.H
Input Usage

item_data

The number of edit boxes in the dialog box.

item_reference

Pointer to an array of two CMC_string data types. The first string is the caption for the address-book dialog box. To not provide a label, the client application sets the label string to NULL. The second string is a label for the recipient well if there is only one recipient well. If there are multiple recipient wells (for example, TO: and CC:) this string is ignored.

extension_flags

All flags used with the CMC_extension structure are valid. No further flags are defined.

Output Usage

item_data

Unchanged.

item_reference

Unchanged.

extension_flags

Unchanged.

Adds to

The cmc_look_up function.

See Also

CMC_extension, cmc_look_up


CMC_X_MS_ATTACH_DATA

CMC_X_MS_ATTACH_DATA is a CMC extension that contains bitmasks of flags used to provide data on message attachments.

Quick Info

Header file:	XCMCMSXT.H
Input Usage

item_data

Bitmask of attachment flags. The following flags can be set:

CMC_X_MS_ATTACH_OLE

The CMC implementation supports OLE attachments.

CMC_X_MS_ATTACH_OLE_STATIC

The CMC implementation supports static OLE attachments.

CMC_X_MS_ATTACH_MESSAGE

The CMC implementation supports attached messages.

item_reference

Object identifier for the attachment encoding. This member can point to a CMC_X_MS_ATTACH structure, to allow a message reference to be added as an embedded message in the current message.

extension_flags

All flags used with the CMC_extension structure are valid. No further flags are defined.

Output Usage

item_data

Bitmask of attachment flags. CMC can set the following flags:

CMC_X_MS_ATTACH_OLE

The CMC implementation supports OLE attachments.

CMC_X_MS_ATTACH_OLE_STATIC

The CMC implementation supports static OLE attachments.

CMC_X_MS_ATTACH_MESSAGE

The CMC implementation supports attached messages.

item_reference

Object identifier for the attachment encoding.

extension_flags

Unchanged.

Adds to

The CMC_attachment structure.

See Also

CMC_attachment, CMC_extension


CMC_X_MS_FUNCTION_FLAGS

CMC_X_MS_FUNCTION_FLAGS is a CMC extension that contains a bitmask of flags used for CMC functions that serve purposes other than session handling.

Quick Info

Header file:	XCMCMSXT.H
Input Usage

item_data

Bitmask of extension flags. The following flags can be set:

CMC_X_MS_AB_NO_MODIFY

Disallows changes to the address book through the address-book details dialog box if a user interface is being used with the cmc_look_up function.

CMC_X_MS_LIST_GUARANTEE_FIFO

Causes the CMC implementation to return messages in date order when the cmc_list function is called.

CMC_X_MS_READ_BODY_AS_FILE

Causes the CMC implementation to put an attachment containing the message text in the message body rather than putting the message text in the message body directly when returning a message with the cmc_read function.

CMC_X_MS_READ_ENV_ONLY

Causes the CMC implementation to return only the message header information when returning a message with the cmc_read function.

item_reference

NULL.

extension_flags

All flags used with the CMC_extension structure are valid. No further flags are defined.

Output Usage

extension_flags

Unchanged.

item_data

Unchanged.

item_reference

Unchanged.

Adds to

The cmc_read, cmc_look_up, and cmc_list functions.

See Also

CMC_extension, cmc_list, cmc_look_up, cmc_read


CMC_X_MS_MESSAGE_DATA

CMC_X_MS_MESSAGE_DATA is a CMC extension that contains a bitmask of flags used to provide extra data about messages.

Quick Info

Header file:	XCMCMSXT.H
Input Usage

item_data

Bitmask of extension flags. The following flag can be set:

CMC_X_MS_MSG_RECEIPT_REQ

The message sender requests notification of message receipt.

item_reference

Pointer to a string containing the conversation thread.

extension_flags

All flags used with the CMC_extension structure are valid. No further flags are defined.

Output Usage

item_data

Bitmask of extension flags. The following flag can be set:

CMC_X_MS_MSG_RECEIPT_REQ

The message sender requests notification of message receipt.

item_reference

Unchanged.

extension_flags

Unchanged.

Adds to

The CMC_message structure.

See Also

CMC_extension, CMC_message


CMC_X_MS_SESSION_FLAGS

CMC_X_MS_SESSION_FLAGS is a CMC extension that contains a bitmask of flags used to provide information when logging on and off a session.

Quick Info

Header file:	XCMCMSXT.H
Input Usage

item_data

Bitmask of logon and logoff flags. The following flags can be set for use with the cmc_logon function:

CMC_X_MS_NEW_SESSION

The message sender requests a new session instead of requesting use of a shared session.

CMC_X_MS_FORCE_DOWNLOAD

The CMC implementation should attempt to download all new messages before the cmc_logon function returns. If this flag is not set, downloading might take place in the background after cmc_logon returns.

The following flags can be used with the cmc_logoff function:

CMC_X_LOGOFF_SHARED

The CMC implementation should close all shared sessions.

item_reference

NULL.

extension_flags

All flags used with the CMC_extension structure are valid. No further flags are defined.

Output Usage

item_data

Unchanged.

item_reference

Unchanged.

extension_flags

Unchanged.

Adds to

The cmc_logon, cmc_look_up, and cmc_send functions.

See Also

CMC_extension, cmc_list, cmc_logon, cmc_look_up, cmc_send


MAPI Functions and Related Macros

The following alphabetic entries contain documentation for the MAPI Functions. For more information on using functions that may not be supported in future versions of MAPI, see Using Functions.


ACCELERATEABSDI

The ACCELERATEABSDI function prototype defines a callback function that accelerates the addition of names to an address book.

Quick Info

Header file:	MAPIDEFS.H
Defined function implemented by:	MAPI
Defined function called by:	Client applications
BOOL (STDMETHODCALLTYPE ACCELERATEABSDI)(

ULONG ulUIParam,
LPVOID lpvmsg
);
Parameters

ulUIParam

[in] An implementation-specific 32-bit value used for passing user interface information to a function. In Microsoft Windows applications, ulUIParam is the parent window handle for a dialog box and is of type HWND, cast to a ULONG. A value of zero indicates there is no parent window.

lpvmsg

[in] Pointer to a Windows message.

Return Values

A function with the ACCELERATEABSDI prototype returns TRUE if it handles the message.

Remarks

An ACCELERATEABSDI prototype-based function is used only if the client has set the DIALOG_SDI flag in the ulFlags member of the ADRPARM structure.

A client application calls a function based on this prototype in its Windows message loop during execution of a modeless address book dialog box for the IAddrBook::Address method. This calling is terminated when MAPI calls a function based on the DISMISSMODELESS function prototype.


ABProviderInit

The ABProviderInit function initializes an address book provider for operation.

Quick Info

Header file:	MAPISPI.H
Implemented by:	Address book providers
Called by:	MAPI
HRESULT ABProviderInit(

HINSTANCE hInstance,
LPMALLOC lpMalloc,
LPALLOCATEBUFFER lpAllocateBuffer,
LPALLOCATEMORE lpAllocateMore,
LPFREEBUFFER lpFreeBuffer,
ULONG ulFlags,
ULONG ulMAPIVer,
ULONG FAR * lpulProviderVer,
LPABPROVIDER FAR * lppABProvider
);
Parameters

hInstance

[in] The instance of the address book provider’s dynamic-link library (DLL) that MAPI used when it linked.

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. The address book provider may need to use this allocation method when working with certain interfaces such as IStream.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used where required by MAPI to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used where required by MAPI to allocate additional memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used where required by MAPI to free memory.

ulFlags

[in] Bitmask of flags. The following flag can be set:

MAPI_NT_SERVICE

The provider is being loaded in the context of a Windows NT service, a special type of process without access to any user interface.

ulMAPIVer

[in] Version number of the service provider interface (SPI) that MAPI.DLL uses. For the current version number, see the MAPISPI.H header file.

lpulProviderVer

[out] Pointer to the version number of the SPI that this address book provider uses.

lppABProvider

[out] Pointer to a pointer to the initialized address book provider object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_VERSION

The SPI version being used by MAPI is not compatible with the SPI being used by this provider.

Remarks

MAPI calls the entry point function ABProviderInit to initialize an address book provider following a client logon.

Notes to Implementers

An address book provider must implement ABProviderInit as an entry point function in the provider’s DLL. The implementation must be based on the ABPROVIDERINIT function prototype, also specified in MAPISPI.H. MAPI defines ABPROVIDERINIT to use the standard MAPI initialization call type, STDMAPIINITCALLTYPE, which causes ABProviderInit to follow the CDECL calling convention. The advantage of CDECL is that calls can be attempted even if the number of calling parameters does not match the number of defined parameters.

A provider can be initialized multiple times, as a result of appearing in several profiles in simultaneous use or of appearing more than once in the same profile. ABProviderInit must return a different provider object in lppABProvider for each initialization.

The address book provider should use the functions pointed to by lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer for most memory allocation and deallocation. In particular, the provider must use these functions to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetProps and IMAPITable::QueryRows. If the provider also expects to use the OLE memory allocator, it should call the IUnknown::AddRef method of the allocator object pointed to by the lpMalloc parameter.

For more information on writing ABProviderInit, see Implementing an Address Book Provider’s Entry Point Function. For more information on entry point functions, see About Provider Entry Point Functions.

See Also

HPProviderInit, IABProvider : IUnknown, MSProviderInit, XPProviderInit


BuildDisplayTable

The BuildDisplayTable function creates a display table from the property page data contained in one or more DTPAGE structures.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Service providers
STDAPI BuildDisplayTable(

LPALLOCATEBUFFER lpAllocateBuffer,
LPALLOCATEMORE lpAllocateMore,
LPFREEBUFFER lpFreeBuffer,
LPMALLOC lpMalloc,
HINSTANCE hInstance,
UINT cPages,
LPDTPAGE lpPage,
ULONG ulFlags,
LPMAPITABLE * lppTable,
LPTABLEDATA * lppTblData
);
Parameters

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used where required by MAPI to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used where required by MAPI to allocate additional memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used where required by MAPI to free memory.

lpMalloc

Unused; should be set to NULL.

hInstance

[in] An instance of a MAPI object from which BuildDisplayTable retrieves resources.

cPages

[in] Count of DTPAGE structures in the array pointed to by the lpPage parameter.

lpPage

[in] Pointer to an array of DTPAGE structures that contain information about the display table pages to be built.

ulFlags

[in] Bitmask of flags. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppTable

[out] Pointer to a pointer to the display table, which exposes the IMAPITable interface.

lppTblData

[in, out] Pointer to a pointer to a table data object exposing the ITableData interface on the table returned in the lppTable parameter. If no table data object is desired, lppTblData should be set to NULL instead of a pointer value.

Remarks

MAPI uses the functions pointed to by lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer for most memory allocation and deallocation, in particular to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetProps and IMAPITable::QueryRows.

Notes to Callers

Everything possible is read from the dialog resource, including:

•	The page title, that is, the ulbLpszLabel member of the DTBLPAGE structure, read from the dialog title in the resource.

•	All control titles, that is, the ulbLpszLabel members of other control structures, read from the control text in the resource.

BuildDisplayTable overwrites anything passed in the input control structures with information from the dialog resource, which means the caller of BuildDisplayTable cannot dynamically specify page or control titles. Callers who need to do that can choose to have BuildDisplayTable return to them the table data object in lppTableData and change rows in it; but they might find it simpler to build the display table by hand in a table data object instead.

If lppTableData is not set to NULL, the provider is responsible for freeing the table data object when it is finished with the display table.


CALLERRELEASE

The CALLERRELEASE function prototype defines a callback function that releases a table data object.

Quick Info

Header file:	MAPIUTIL.H
Defined function implemented by:	Client applications and service providers
Defined function called by:	MAPI
void CALLERRELEASE(

ULONG ulCallerData,
LPTABLEDATA lpTblData,
LPMAPITABLE lpVue
);
Parameters

ulCallerData

[in] 32-bit data about the table data object to release.

lpTblData

[in] Pointer to the ITableData : IUnknown interface for the table data object to release.

lpVue

[in] Pointer to the IMAPITable : IUnknown interface for the table whose data is released. This table interface is an interface for the table object passed in the lppMAPITable parameter of the ITableData::HrGetView method that created the object to release.

Return Values

None

Remarks

Client applications use the CALLERRELEASE function prototype to create a callback function to release a view on the underlying table data object without having to keep track of that object. After all views on a table data object are released, implementations of ITableData::HrGetView call the CALLERRELEASE function and then release the table data object underlying the views.


ChangeIdleRoutine

The ChangeIdleRoutine function changes some or all of the characteristics of an idle function based on the FNIDLE function prototype.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
VOID ChangeIdleRoutine(

FTG ftg,
PFNIDLE pfnIdle,
LPVOID pvIdleParam,
short priIdle,
ULONG csecIdle,
USHORT iroIdle,
USHORT ircIdle
);
Parameters

ftg

[in] Function tag that identifies the idle function.

pfnIdle

[in] Pointer to the idle function.

pvIdleParam

[in] Pointer to a new block of memory that the calling implementation allocates for the idle function.

priIdle

[in] Value representing a new priority for the idle function. Possible priorities for implementation-defined functions are greater than or less than zero, but not zero. A value of zero is reserved for a user event such as a mouse click.

Values greater than zero represent priorities for background tasks that have a higher priority than user events and are dispatched as part of the standard message pump loop. Values less than zero represent priorities for idle tasks that only run during message-pump idle time. Examples of priorities are: 1 for foreground submission, −1 for power-edit character insertion, and −3 for downloading new messages.

csecIdle

[in] A new time, in hundredths of a second, to apply to the idle function. The meaning of the initial time value varies, depending on what is passed in the iroIdle parameter. It can be:

•	The minimum period of user inaction that must elapse before the MAPI idle engine calls the idle function for the first time, if the FIROWAIT flag is set in iroIdle. After this time passes, the idle engine can call the idle function as often as necessary.

•	The minimum interval between calls to the idle function, if the FIROINTERVAL flag is set in iroIdle.

iroIdle

[in] Bitmask of flags indicating new options for the idle function. The following flags can be set:

FIRODISABLED

The idle function is initially disabled when registered. The default action is to enable the idle function when the FtgRegisterIdleRoutine function registers it.

FIROINTERVAL

The time specified by the csecIdle parameter is the minimum interval between successive calls to the idle function.

FIROWAIT

The time specified by the csecIdle parameter is the minimum period of user inaction that must elapse before the MAPI idle engine calls the idle function for the first time. After this time passes, the idle engine can call the idle function as often as necessary.

ircIdle

[in] Bitmask of flags used to indicate the changes to be made to the idle function. The following flags can be set:

FIRCCSEC

A change to the time associated with the idle function — that is, a change indicated by the value passed in the csecIdle parameter.

FIRCIRO

A change to the options for the idle function — that is, a change indicated by the value passed in the iroIdle parameter.

FIRCPFN

A change to the idle function pointer — that is, a change indicated by the value passed in the pfnIdle parameter.

FIRCPRI

A change to the priority of the idle function — that is, a change indicated by the value passed in the priIdle parameter.

FIRCPV

A change to the memory block of the idle function — that is, a change indicated by the value passed in the pvIdleParam parameter.


CheckParameters

The CheckParameters macro calls an internal function to check debugging parameters on service provider methods called by MAPI.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
HRESULT CheckParameters(

METHODS eMethod,
LPVOID First
);
Parameters

eMethod

[in] Specifies, by enumeration, the method to validate.

First

[in] Pointer to the first argument on the stack.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The CheckParameters macro has been superseded by the CheckParms macro. CheckParameters does not work correctly on RISC platforms and is now prevented from compiling on them. It still compiles and works correctly on Intel platforms, but CheckParms is recommended on all platforms.


CheckParms

The CheckParms macro calls an internal function to check debugging parameters on service provider methods called by MAPI.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
HRESULT CheckParms(

METHODS eMethod,
LPVOID First
);
Parameters

eMethod

[in] Specifies, by enumeration, the method to validate.

First

[in] Pointer to the first argument on the stack.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

In contrast to the ValidateParms and UlValidateParms  macros, the CheckParms macro does not perform a full parameter validation. Parameters passed between MAPI and service providers are assumed to be correct, so CheckParms performs a debug validation only.

For more information on parameter validation, see Validating Parameters to Interface Methods.


CloseIMsgSession

The CloseIMsgSession function closes a message session.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	IMESSAGE.H
Implemented by:	MAPI
Called by:	Client applications and service providers
VOID CloseIMsgSession(

LPMSGSESS lpMsgSess
);
Parameters

lpMsgSess

[in] Pointer to the message session object obtained using the OpenIMsgSession function at the start of the message session.

Remarks

A client application uses the CloseIMsgSession function along with the OpenIMsgSession function to wrap the creation of messages inside a message session. When a client application closes this session, it also closes all messages created within the session. Using sessions obtained with the IMessage interface is optional.

A message session keeps track of all messages opened during the session, in addition to all the tables and attachments within the messages. When a client calls CloseIMsgSession, it closes all these objects.


CreateIProp

The CreateIProp function creates a property data object, that is, an IPropData object.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE CreateIProp(

LPCIID lpInterface,
ALLOCATEBUFFER FAR * lpAllocateBuffer,
ALLOCATEMORE FAR * lpAllocateMore,
FREEBUFFER FAR * lpFreeBuffer,
LPVOID lpvReserved,
LPPROPDATA FAR * lppPropData
);
Parameters

lpInterface

[in] Pointer to an interface identifier (IID) for the property data object.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used to allocate additional memory where required.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

lpvReserved

Reserved; must be zero.

lppPropData

[out] Pointer to a pointer to the returned property data object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_INTERFACE_NOT_SUPPORTED

The requested interface is not supported for this object.

Remarks

The lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer input parameters point to the MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer functions, respectively. If a client application calls the CreateIProp function, it passes in these parameters pointers to the functions named as listed. If a service provider calls CreateIProp, it passes the pointers to these functions it received in its initialization call or retrieved with a call to the IMAPISupport::GetMemAllocRoutines method.


CreateTable

The CreateTable function creates structures and an object handle for an ITableData interface that can be used to create table views.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE CreateTable(

LPCIID lpInterface,
ALLOCATEBUFFER FAR * lpAllocateBuffer,
ALLOCATEMORE FAR * lpAllocateMore,
FREEBUFFER FAR * lpFreeBuffer,
LPVOID lpvReserved,
ULONG ulTableType,
ULONG ulPropTagIndexColumn,
LPSPropTagArray lpSPropTagArrayColumns,
LPTABLEDATA FAR * lppTableData
);
Parameters

lpInterface

[in] Pointer to an interface identifier (IID) for the table data object. Passing NULL in the lpInterface parameter indicates that the table data object returned in the lppTableData parameter is cast to the standard interface for a table data object; the valid interface identifier is IID_IMAPITableData.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used to allocate additional memory where required.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

lpvReserved

Reserved; must be zero.

ulTableType

[in] A table type that is available to a client application or service provider as part of the IMAPITable::GetStatus return data on its table views. Possible values are:

TBLTYPE_DYNAMIC

The table's contents are dynamic and can change as the underlying data changes.

TBLTYPE_KEYSET

The rows within the table are fixed, but the values within these rows are dynamic and can change as the underlying data changes.

TBLTYPE_SNAPSHOT

The table is static and the contents do not change when the underlying data changes.

ulPropTagIndexColumn

[in] Index number of the column for use when changing table data.

lpSPropTagArrayColumns

[in] Pointer to an SPropTagArray structure containing an array of property tags indicating the properties required in the table for which the object holds data.

lppTableData

[out] Pointer to a pointer to the returned table data object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer input parameters point to the MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer functions, respectively. If a client application calls the CreateTable function, it passes in these parameters pointers to the functions named as listed. If a service provider calls CreateTable, it passes the pointers to these functions that it received in its initialization call or retrieved with a call to the IMAPISupport::GetMemAllocRoutines method.

See Also

IMAPITable : IUnknown


DeinitMapiUtil

The DeinitMapiUtil function releases utility functions called explicitly by the ScInitMapiUtil function or implicitly by the MAPIInitialize function.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications
DeinitMapiUtil(VOID);

Parameters

None

Remarks

The ScInitMapiUtil and DeinitMapiUtil functions cooperate to call and release select utility functions, as opposed to the MAPIInitialize function, which calls core as well as utility functions. When ScInitMapiUtil calls utility functions, it also initializes the necessary memory.

When use of the functions called by ScInitMapiUtil is complete, DeinitMapiUtil must be explicitly called to release them. In contrast, MAPIInitialize implicitly calls DeinitMapiUtil.

See Also

MAPIUninitialize


DeregisterIdleRoutine

The DeregisterIdleRoutine function removes a client application or service provider function based on the FNIDLE function prototype from the idle table.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
VOID DeregisterIdleRoutine(

FTG ftg
);
Parameters

ftg

[in] Function tag that identifies the idle function to be removed.

Remarks

A client application or service provider can only remove an idle function — that is, a function based on the FNIDLE function prototype — from the idle table if the function is not active. MAPI does not verify that the idle function is in a state from which it can be exited.

A client or provider can use the idle function itself to make the call to the DeregisterIdleRoutine function. The idle function is deregistered when the function returns.

After the idle function is deregistered, the idle engine does not call it again. Any implementation that calls DeregisterIdleRoutine must deallocate any memory blocks to which it passed pointers for the idle engine to use in its original call to the FtgRegisterIdleRoutine function.


DISMISSMODELESS

The DISMISSMODELESS function prototype defines a callback function that MAPI calls when it has dismissed a modeless address book dialog box. This call is necessary so that the client application will stop calling the accelerator function based on the ACCELERATEABSDI function prototype when the modeless dialog box is not active.

Quick Info

Header file:	MAPIDEFS.H
Defined function implemented by:	Client applications
Defined function called by:	MAPI
void (STDMETHODCALLTYPE DISMISSMODELESS)(

ULONG ulUIParam,
LPVOID lpvContext
);
Parameters

ulUIParam

[in] An implementation-specific 32-bit value typically used for passing user interface information to a function. For example, in Microsoft Windows this parameter is the parent window handle for the dialog box and is of type HWND (cast to a ULONG). A value of zero is always valid.

lpvContext

[in] Pointer to an arbitrary value passed to the callback function when MAPI calls it. This value can represent an address of significance to the client application. Typically, for C++ code, lpvContext is a pointer to the address of a C++ object.

See Also

ADRPARM


EnableIdleRoutine

The EnableIdleRoutine function enables or disables an idle function based on the FNIDLE function prototype.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
VOID EnableIdleRoutine(

FTG ftg,
BOOL fEnable
);
Parameters

ftg

[in] Function tag that identifies the idle function to be enabled or disabled.

fEnable

[in] Contains TRUE if the idle engine should enable the idle function, or FALSE if the idle engine should disable it.

See Also

FtgRegisterIdleRoutine


FBadColumnSet

The FBadColumnSet function tests the validity of one or more table column sets for use by a service provider in a subsequent call to the IMAPITable::SetColumns method.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
ULONG FBadColumnSet(

LPSPropTagArray lpptaCols
);
Parameters

lpptaCols

[in] Pointer to an SPropTagArray structure containing an array of property tags defining the table column sets to validate.

Return Values

TRUE

The specified column sets are invalid.

FALSE

The specified column sets are valid.

Remarks

A service provider calls the FBadColumnSet function. This function treats columns of type PT_ERROR as invalid and columns of type PT_NULL as valid.


FBadEntryList

The FBadEntryList function validates a list of MAPI entry identifiers.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
BOOL FBadEntryList(

LPENTRYLIST lpEntryList
);
Parameters

lpEntryList

[in] Pointer to an ENTRYLIST structure defining the list of entry identifiers to be validated.

Return Values

TRUE

One or more of the listed entry identifiers are invalid.

FALSE

All of the listed entry identifiers are valid.

Remarks

The FBadEntryList function determines if the entry identifier list has been correctly generated. An example of an invalid entry identifier is an identifier for which memory has been incorrectly allocated or an identifier of an incorrect size.


FBadProp

The FBadProp function validates a specified property.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
ULONG FBadProp(

LPSPropValue lpprop
);
Parameters

lpprop

[in] An SPropValue structure defining the property to be validated.

Return Values

TRUE

The specified property is invalid.

FALSE

The specified property is valid.

Remarks

A service provider can call the FBadProp function for several reasons, for example to prepare for a call to the IMAPIProp::SetProps method setting a property. FBadProp validates the specified property depending on the property type. For example, if the property is Boolean, FBadProp ensures that its value is either TRUE or FALSE. If the property is binary, FBadProp checks its pointer and size and makes sure that it is allocated correctly.

See Also

FBadPropTag


FBadPropTag

The FBadPropTag function validates a specified property tag.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
ULONG FBadPropTag(

ULONG ulPropTag
);
Parameters

ulPropTag

[in] The property tag to be validated.

Return Values

TRUE

The specified property tag is not a valid MAPI property tag.

FALSE

The specified property tag is a valid MAPI property tag.

Remarks

A service provider calls the FBadPropTag function.

See Also

FBadProp


FBadRestriction

The FBadRestriction function validates a restriction used to limit a table.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
ULONG FBadRestriction(

LPSRestriction lpres
);
Parameters

lpres

[in] An SRestriction structure defining the restriction to be validated.

Return Values

TRUE

The specified restriction or any of its subrestrictions is invalid.

FALSE

The specified restriction and its subrestrictions are valid.

Remarks

A service provider calls the FBadRestriction function. Once validated, a restriction can be passed in calls to the IMAPITable::Restrict method to restrict a table to certain rows, to the IMAPITable::FindRow method to locate a table row, and to methods of the IMAPIContainer interface to perform a restriction on a container object.


FBadRglpNameID

The FBadRglpNameID function validates an array of pointers that specify name identifier structures and verifies their allocation.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
BOOL FBadRglpNameID(

LPMAPINAMEID FAR * lppNameId,
ULONG cNames
);
Parameters

lppNameId

[in] Pointer to an array of MAPINAMEID structures defining the name identifiers.

cNames

[in] Count of name identifiers in the array pointed to by the lppNameId parameter.

Return Values

TRUE

One or more of the specified name identifiers is invalid.

FALSE

The specified name identifiers are valid.

See Also

IMAPIProp::GetIDsFromNames, IMAPIProp::GetNamesFromIDs


FBadRglpszW

The FBadRglpszW function validates all strings in an array of Unicode strings.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
BOOL FBadRglpszW(

LPWSTR FAR * lppszW,
ULONG cStrings
);
Parameters

lppszW

[in] Pointer to an array of null-terminated Unicode strings.

cStrings

[in] Count of strings in the array pointed to by the lppszW parameter.

Return Values

TRUE

One or more of the strings in the specified array are invalid.

FALSE

The strings in the specified array are valid.


FBadRow

The FBadRow function validates a row in a table.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
ULONG FBadRow(

LPSRow lprow
);
Parameter

lprow

[in] Pointer to an SRow structure identifying the row to be validated.

Return Values

TRUE

The specified row is invalid.

FALSE

The specified row is valid.

See Also

FBadRowSet


FBadRowSet

The FBadRowSet function validates all table rows included in a set of table rows.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
BOOL FBadRowSet(

LPSRowSet lpRowSet
);
Parameter

lpRowSet

[in] Pointer to an SRowSet structure identifying the row set to be validated. If the pointer is NULL, the structure is invalid.

Return Values

TRUE

A row of the specified row set is invalid or the row set itself is invalid.

FALSE

The rows of the specified row set and the row itself are valid.

See Also

FBadRow


FBadSortOrderSet

The FBadSortOrderSet function validates a sort order set by verifying its memory allocation.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
ULONG FBadSortOrderSet(

LPSSortOrderSet lpsos
);
Parameter

lpsos

[in] Pointer to an SSortOrderSet structure identifying the sort order set to be validated.

Return Values

TRUE

The specified sort order set is invalid.

FALSE

The specified sort order set is valid.

Remarks

The FBadSortOrderSet function can be used to prepare for a call to a sort method such as the IMAPITable::SortTable method.


FBinFromHex

The FBinFromHex function converts a string representation of a hexadecimal number to binary data.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
BOOL FBinFromHex(

LPTSTR sz,
LPBYTE pb
);
Parameters

sz

[in] Pointer to the null-terminated string to be converted. Valid characters include the hexadecimal characters zero through nine and both uppercase and lowercase characters A through F.

pb

[out] Pointer to the returned binary number.

Return Values

TRUE

The string was successfully converted into a binary number.

FALSE

The input string contains invalid ASCII hexadecimal characters.

See Also

ScBinFromHexBounded


FEqualNames

The FEqualNames function determines whether two MAPI name identifiers are equal.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
BOOL FEqualNames(

LPMAPINAMEID lpName1,
LPMAPINAMEID lpName2
);
Parameters

lpName1

[in] Pointer to a MAPINAMEID structure defining the first name to be tested.

lpName2

[in] Pointer to a MAPINAMEID structure defining the second name to be tested.

Return Values

TRUE

The two name identifiers are equal.

FALSE

The two name identifiers are not equal.

Remarks

The FEqualNames function is useful because name identifiers are represented as structures, which cannot be compared by simple binary methods. The testing process is case-sensitive for strings.


FNIDLE

The FNIDLE function prototype defines an idle function that the MAPI idle engine calls periodically according to priority. The specific functionality of the idle function is defined by the client or provider.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Defined function implemented by:	Client applications and service providers
Defined function called by:	MAPI
BOOL (STDAPICALLTYPE FNIDLE)(

LPVOID lpvContext
);
Parameters

lpvContext

[in] Specifies a pointer to a block of memory. The idle function can use this value as a pointer to a state buffer for length operations.

Return Values

FALSE

An idle function with the FNIDLE prototype should always return FALSE.

Remarks

A client application or service provider must call the idle engine function Idle_InitDLL before it can register its own idle function with a call to the FtgRegisterIdleRoutine function. Then the client application or provider can use these other idle engine functions as needed during idle operations:

•	EnableIdleRoutine

•	ChangeIdleRoutine

•	DeregisterIdleRoutine

•	Idle_DeInitDLL

•	FIsIdleExit

•	FDoNextIdleTask


FPropCompareProp

The FPropCompareProp function compares two properties using a binary relational operator.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
BOOL FPropCompareProp(

LPSPropValue lpSPropValue1,
ULONG ulRelOp,
LPSPropValue lpSPropValue2
);
Parameters

lpSPropValue1

[in] Pointer to an SPropValue structure defining the first property for comparison.

ulRelOp

[in] The relational operator to use in the comparison.

lpSPropValue2

[in] Pointer to an SPropValue structure defining the second property for comparison.

Return Values

TRUE

The function has succeeded in comparing the input properties.

FALSE

The function has not succeeded in comparing the input properties.

Remarks

The order of comparison is lpSPropValue1, ulRelOp, lpSPropValue2. If the property types of the properties compared do not match, the FPropCompareProp function determines that they are not equal but that they are otherwise incomparable.

The comparison method depends on the property types included with the SPropValue property definitions and a fuzzy level heuristic also provided by the calling implementation. The FPropContainsProp function can be used to prepare restrictions for generating a table.


FPropContainsProp

The FPropContainsProp function compares two property values, generally strings or binary arrays, to see if one value contains the other.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
BOOL FPropContainsProp(

LPSPropValue lpSPropValueDst,
LPSPropValue lpSPropValueSrc,
ULONG ulFuzzyLevel
);
Parameters

lpSPropValueDst

[in] Pointer to an SPropValue structure defining the property value that might contain the property value pointed to by the lpSPropValueSrc parameter.

lpSPropValueSrc

[in] Pointer to an SPropValue structure defining the property value that FPropContainsProp is seeking within the property value pointed to by the lpSPropValueDst parameter.

ulFuzzyLevel

[in] The fuzzy level to use in the comparison. Possible fuzzy level values are:

FL_FULLSTRING

Works identically to TNEF_PROP_CONTAINED_TNEF; requires an exact match.

FL_IGNORECASE

The comparison deals only with properties of type PT_STRING8. When this value is set, FPropContainsProp makes the comparison in case-insensitive fashion.

FL_IGNORENONSPACE

The comparison deals only with properties of type PT_STRING8. When this value is set, FPropContainsProp makes the comparison so as to ignore Unicode-defined nonspacing characters, for example diacritical marks.

FL_LOOSE

The comparison deals only with properties of type PT_STRING8. When this value is set, a service provider performs as many fuzzy level heuristics of types FL_IGNORECASE and FL_IGNORESPACE as it has been designed to handle.

FL_PREFIX

The comparison deals with properties of types T_STRING8 and PT_BINARY. When this value is set, FPropContainsProp compares the values of the two properties only through the length of the property indicated by the lpSPropValueSrc parameter.

FL_SUBSTRING

The comparison deals with properties of types PT_STRING8 and PT_BINARY. When this value is set, FPropContainsProp checks to see if the property value indicated by the lpSPropValueSrc parameter is contained as a substring in the other property.

Return Values

TRUE

In the following cases:

•	FL_FULLSTRING is set for the fuzzy level and the values of the source and destination properties are equivalent.

•	FL_SUBSTRING is set for the fuzzy level and the property indicated by the lpSPropValueSrc parameter is contained as a substring in the property indicated by the lpSPropValueDst parameter.

•	For PT_BINARY properties not falling into one of the categories listed for the ulFuzzyLevel parameter, the property indicated by lpSPropValueSrc is contained as a byte sequence in the property indicated by lpSPropValueDst.

FL_FULLSTRING, FL_SUBSTRING and FL_PREFIX are mutually exclusive. Only one of them can be set where anywhere from zero to all three of the other possible values can be set: FL_IGNORECASE, FL_IGNORENONSPACE, and FL_LOOSE.

FALSE

The properties being compared are not both of the same type, one or both of the properties is not of either the PT_STRING8 or PT_BINARY type, or the input fuzzy level is not one of those listed for ulFuzzyLevel.

Remarks

For comparisons of properties of type PT_STRING8 not covered by one of the values for ulFuzzyLevel, the FPropContainsProp function compares the input property values as fuzzy level one.

The comparison method FPropContainsProp uses depends on the property types included with the SPropValue property definitions and a fuzzy level heuristic also provided by the calling implementation. FPropContainsProp can be used to prepare restrictions for generating a table.

See Also

FPropCompareProp


FPropExists

The FPropExists function searches for a given property tag in an IMAPIProp interface or an interface derived from IMAPIProp, such as IMessage or IMAPIFolder.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
BOOL FPropExists(

LPMAPIPROP pobj,
ULONG ulPropTag
);
Parameters

pobj

[in] Pointer to the IMAPIProp interface or interface derived from IMAPIProp within which to search for the property tag.

ulPropTag

[in] Property tag for which to search.

Return Values

TRUE

The function found a match for the given property tag.

FALSE

The function did not find a match for the given property tag.

Remarks

If the given property tag has type PT_UNSPECIFIED, the FPropExists function finds a match only for the property identifier. Otherwise, the match is for the entire property tag, including the type.


FreePadrlist

The FreePadrlist function destroys an ADRLIST structure and frees associated memory, including memory allocated for all member structures.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
void FreePadrlist(

LPADRLIST padrlist
);
Parameter

padrlist

[in] Pointer to the ADRLIST structure to be destroyed.

Remarks

MAPI calls the MAPIFreeBuffer function to free every entry in the ADRLIST structure before freeing the complete structure. Therefore all such entries must have been allocated using the MAPIAllocateBuffer and MAPIAllocateMore functions.


FreeProws

The FreeProws function destroys an SRowSet structure and frees associated memory, including memory allocated for all structure members.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
void FreeProws(

LPSRowSet prows
);
Parameter

prows

[in] Pointer to the SRowSet structure to be destroyed.

Remarks

MAPI normally uses the MAPIFreeBuffer function to free memory, but it can use any other comparable function if necessary.


FtAddFt

The FtAddFt function adds one unsigned 64-bit integer to another.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
FILETIME FtAddFt(

FILETIME Addend1,
FILETIME Addend2
);
Parameters

Addend1

[in] A FILETIME structure defining the first unsigned 64-bit integer to be added.

Addend2

[in] A FILETIME structure defining an unsigned 64-bit integer to be added to the value indicated by the Addend1 parameter.

Remarks

The FtAddFt function returns a FILETIME structure containing the sum of the two integers.


FtgRegisterIdleRoutine

The FtgRegisterIdleRoutine function adds a function based on the FNIDLE function prototype to the idle table.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
FtgRegisterIdleRoutine(

PFNIDLE pfnIdle,
LPVOID pvIdleParam,
short priIdle,
ULONG csecIdle,
USHORT iroIdle
);
Parameters

pfnIdle

[in] Pointer to the idle function.

pvIdleParam

[in] Pointer to a block of memory that the idle engine should use when it calls the idle function.

priIdle

[in] Initial priority that the calling implementation requests for the idle function. Possible priorities for implementation-defined functions are greater than or less than zero, but not zero. The zero priority is reserved for a user event (for example, a mouse click or a WM_PAINT message).

Priorities greater than zero represent background tasks that have a higher priority than user events and are dispatched as part of the standard message pump loop. Priorities less than zero represent idle tasks that only run during message-pump idle time. Examples of priorities are: 1 for foreground submission, −1 for power-edit character insertion, and −3 for downloading new messages.

csecIdle

[in] Initial time value, in hundredths of a second, that the calling implementation requests to be used in specifying idle function parameters. The meaning of the initial time value varies, depending on what is passed in the iroIdle parameter. It can be:

•	The minimum period of user inaction that must elapse before the MAPI idle engine calls the idle function for the first time, if the FIROWAIT flag is set in iroIdle. After this time passes, the idle engine can call the idle function as often as necessary.

•	The minimum interval between calls to the idle function, if the FIROINTERVAL flag is set in iroIdle.

iroIdle

[in] Bitmask of flags used to set initial options for the idle function. The following flags can be set:

FIRODISABLED

The idle function is initially disabled when registered. The default action is to enable the idle function when FtgRegisterIdleRoutine registers it.

FIROINTERVAL

The time specified by the csecIdle parameter is the minimum interval between successive calls to the idle function.

FIROWAIT

The time specified by the csecIdle parameter is the minimum period of user inaction that must elapse before the MAPI idle engine calls the idle function for the first time. After this time passes, the idle engine can call the idle function as often as necessary.

Remarks

To later make changes to a registered idle function, a client application or service provider can call the ChangeIdleRoutine function. To remove an idle function from the idle table, a client application or provider calls the DeregisterIdleRoutine function.

When all foreground tasks for the platform become idle, the idle engine calls the highest-priority idle function in the idle table that is ready to execute.

The FtgRegisterIdleRoutine function returns a function tag identifying the idle function that FtgRegisterIdleRoutine has added to the idle table. If FtgRegisterIdleRoutine cannot register the idle function for the client or service provider, for example because of memory problems, it returns NULL.


FtMulDw

The FtMulDw function multiplies an unsigned 64-bit integer indicating a time value by an unsigned 32-bit integer in doubleword format.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
FILETIME FtMulDw(

DWORD Multiplier,
FILETIME Multiplicand
);
Parameters

Multiplier

[in] An unsigned 32-bit integer in doubleword format.

Multiplicand

[in] A FILETIME structure defining a 64-bit integer time value to be multiplied by the value in the Multiplier parameter.

Remarks

The FtMulDw function returns a FILETIME structure containing the product of the input values.


FtMulDwDw

The FtMulDwDw function multiplies one unsigned 32-bit integer in doubleword format by another.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
FILETIME FtMulDwDw(

DWORD Multiplicand,
DWORD Multiplier
);
Parameters

Multiplicand

[in] An unsigned 32-bit integer in doubleword format to be multiplied by the value in the Multiplier parameter.

Multiplier

[in] An unsigned 32-bit integer in doubleword format.

Remarks

The FtMulDwDw function returns a FILETIME structure containing the product of the input values.


FtNegFt

The FtNegFt function computes the two’s complement of an unsigned 64-bit integer indicating a time value.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
FILETIME FtNegFt(

FILETIME ft
);
Parameters

ft

[in] A FILETIME structure containing the unsigned 64-bit integer indicating a time value for which to compute the two’s complement.

Remarks

The FtNegFt function returns a FILETIME structure containing the two’s complement of the input value.


FtSubFt

The FtSubFt function subtracts one unsigned 64-bit integer indicating a time value from another.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
FILETIME FtSubFt(

FILETIME Minuend,
FILETIME Subtrahend
);
Parameters

Minuend

[in] A FILETIME structure defining the unsigned 64-bit integer from which the value in the Subtrahend parameter is subtracted.

Subtrahend

[in] A FILETIME structure defining an unsigned 64-bit integer that this function subtracts from the value indicated by the Minuend parameter.

Remarks

The FtSubFt function returns a FILETIME structure containing the results of the subtraction.


GetAttribIMsgOnIStg

The GetAttribIMsgOnIStg function retrieves the attributes of the properties of a particular object.

Quick Info

Header file:	IMESSAGE.H
Implemented by:	MAPI
Called by:	Client applications and message store providers
HRESULT GetAttribIMsgOnIStg(

LPVOID lpObject,
LPSPropTagArray lpPropTagArray,
LPSPropAttrArray FAR * lppPropAttrArray
);
Parameters

lpObject

[in] Obtained from the OpenIMsgOnIStg function, pointing to the object for which property attributes are being retrieved.

lpPropTagArray

[in] Pointer to an SPropTagArray structure containing an array of property tags indicating the properties for which attributes are being retrieved.

lppPropAttrArray

[out] Pointer to a variable where the returned SPropAttrArray structure is stored. This SPropAttrArray structure contains the retrieved property attributes.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_W_ERRORS_RETURNED

The call succeeded overall, but one or more properties could not be accessed and were returned with a property type of PT_ERROR.

Remarks

The GetAttribIMsgOnIStg function is used to make message properties read-only when required by the IMessage schema. The sample message store provider uses it for this purpose. For more information, see Messages.

In the lppPropAttrArray parameter the number and position of the attributes correspond to the number and position of the property tags in the lpPropTagArray parameter.

See Also

IMAPIProp : IUnknown, SetAttribIMsgOnIStg


GetInstance

The GetInstance function copies one value within a multivalued property to a single-valued property of the same type.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
VOID GetInstance(

LPSPropValue pvalMv,
LPSPropValue pvalSv,
ULONG uliInst
);
Parameters

pvalMv

[in] Pointer to an SPropValue structure defining a multivalued property.

pvalSv

[in] Pointer to a single-valued property to receive data.

uliInst

[in] The instance number — that is, the array element — of the value being copied from the structure indicated by the pvalMv parameter.

Remarks

If the value copied is too large for the allocated memory, the GetInstance function only copies pointers rather than allocating new memory.


HexFromBin

The HexFromBin function converts a binary number into a string representation of a hexadecimal number.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
void HexFromBin(

LPBYTE pb,
int cb,
LPTSTR sz
);
Parameters

pb

[in] Pointer to the binary data to be converted.

cb

[in] Size, in bytes, of the pb parameter.

sz

[out] Pointer to the returned null-terminated string representing the binary data.

Remarks

The HexFromBin function takes a pointer to a unit of binary data whose size is indicated by the cb parameter. It returns back in the sz string, within (2*cb)+1 bytes of memory, a representation of this binary information in hexadecimal numbers. If the byte value is 10, for example, the hexadecimal string will be 0A, so one byte becomes two bytes long in the string.


HPProviderInit

The HPProviderInit function initializes a messaging hook provider for operation.

Quick Info

Header file:	MAPIHOOK.H
Implemented by:	Messaging hook providers
Called by:	MAPI
HRESULT HPProviderInit(

LPMAPISESSION lpSession,
HINSTANCE hInstance,
LPALLOCATEBUFFER lpAllocateBuffer,
LPALLOCATEMORE lpAllocateMore,
LPFREEBUFFER lpFreeBuffer,
LPMAPIUID lpSectionUID,
ULONG ulFlags,
LPSPOOLERHOOK FAR * lppSpoolerHook
);
Parameters

lpSession

[in] Pointer to a copy of the object representing the MAPI spooler session. Because the session object is a copy, any component installed as part of the messaging hook provider must be considered “trusted code.” The messaging hook provider should call the IUnknown::AddRef method for the session object.

hInstance

[in] The instance of the messaging hook provider’s dynamic-link library (DLL) that MAPI used when it linked.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used where required by MAPI to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used where required by MAPI to allocate additional memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used where required by MAPI to free memory.

lpSectionUID

[in] Pointer to the MAPIUID of the messaging hook provider’s profile section. HPProviderInit can open this identifier using a session-level call to the IMAPISupport::OpenProfileSection method. However, because MAPI and the MAPI spooler control some properties in the session, the provider should use the range of provider-specific property identifiers for storage and retrieval of profile section properties.

ulFlags

[in] Bitmask of flags used to control whether the messaging hook provider is called for incoming or outgoing messages. The following flags can be set:

HOOK_INBOUND

The messaging hook provider processes messages inbound to the MAPI spooler.

HOOK_OUTBOUND

The messaging hook provider processes messages outbound from the MAPI spooler.

MAPI_NT_SERVICE

The provider is being loaded in the context of a Windows NT service, a special type of process without access to any user interface.

lppSpoolerHook

[out] Pointer to a pointer to the initialized messaging hook provider object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

MAPI calls the entry point function HPProviderInit to initialize a messaging hook provider following a client logon.

Notes to Implementers

A messaging hook provider must implement HPProviderInit as an entry point function in the provider’s DLL. The implementation must be based on the HPPROVIDERINIT function prototype, also specified in MAPIHOOK.H. MAPI defines HPPROVIDERINIT to use the standard MAPI initialization call type, STDMAPIINITCALLTYPE, which causes HPProviderInit to follow the CDECL calling convention. The advantage of CDECL is that calls can be attempted even if the number of calling parameters does not match the number of defined parameters.

A provider can be initialized multiple times, as a result of appearing in several profiles in simultaneous use or of appearing more than once in the same profile. HPProviderInit must return a different provider object in lppSpoolerHook for each initialization.

The messaging hook provider should use the functions pointed to by lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer for most memory allocation and deallocation. In particular, the provider must use these functions to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetProps and IMAPITable::QueryRows. If the provider also expects to use the OLE memory allocator, it should call the IUnknown::AddRef method of the allocator object pointed to by the lpMalloc parameter.

If the provider needs to use mutex objects or critical sections, it should set them up during initialization using HPProviderInit. A mutex object should be owned by the message-hook provider object created by this function.

For more information on using the OLE method IUnknown::AddRef, see Implementing the IUnknown Interface.

For more information on writing HPProviderInit, see Implementing HPProviderInit for Hook Providers. For more information on entry point functions, see About Provider Entry Point Functions.

See Also

ABProviderInit, IMAPISession : IUnknown, MSProviderInit, XPProviderInit


HrAddColumnsEx

The HrAddColumnsEx function adds or moves columns to the beginning of an existing table.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
HRESULT HrAddColumnsEx(

LPMAPITABLE lptbl,
LPSPropTagArray lpproptagColumnsNew,
LPALLOCATEBUFFER lpAllocateBuffer,
LPFREEBUFFER lpFreeBuffer,
void (FAR * lpfnFilterColumns) (LPSPropTagArray ptaga)
);
Parameters

lptbl

[in] Pointer to the MAPI table affected.

lpproptagColumnsNew

[in] Pointer to an SPropTagArray structure containing the array of property tags for the properties to be added or moved to the beginning of the table.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

lpfnFilterColumns

[in] Pointer to a callback function furnished by the caller. If the lpfnFilterColumns parameter is set to NULL, no callback is made.

ptaga

(Input parameter to the callback function pointed to by lpfnFilterColumns) Pointer to an SPropTagArray structure containing the array of new property tags for the columns moved within or added to the table.

Return Values

S_OK

The call succeeded and the specified columns were moved or added.

Remarks

The HrAddColumnsEx function allows the caller to furnish a callback function to filter the original property tags. For example, the caller might want to convert strings from property type PT_UNICODE to PT_STRING8. HrAddColumnsEx first adds or moves the specified columns, then calls the callback function if one is furnished, and finally calls IMAPITable::SetColumns. The callback function can change data within the property tag array but cannot add new tags.

The properties passed to HrAddColumnsEx using the lpproptagColumnsNew parameter become the first properties listed on subsequent calls to the IMAPITable::QueryRows method. If any table properties are undefined when QueryRows is called, they are returned with property type PT_NULL and property identifier zero.

The lpAllocateBuffer and lpFreeBuffer input parameters point to the MAPIAllocateBuffer and MAPIFreeBuffer functions, respectively. If a client calls HrAddColumnsEx, it passes in these parameters pointers to the functions named as listed. If a service provider calls HrAddColumnsEx, it passes the pointers to these functions it received in its initialization call or retrieved by calling the IMAPISupport::GetMemAllocRoutines method.

See Also

IMAPITable::QueryColumns


HrAllocAdviseSink

The HrAllocAdviseSink function creates an advise sink object, given a context specified by the calling implementation and a callback function to be triggered by an event notification.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
STDAPI HrAllocAdviseSink(

LPNOTIFCALLBACK lpfnCallback,
LPVOID lpvContext,
LPMAPIADVISESINK FAR * lppAdviseSink
);
Parameters

lpfnCallback

[in] Pointer to the callback function defined by a client application or service provider that MAPI is to call when a notification event occurs for the newly created advise sink.

lpvContext

[in] Pointer to an arbitrary value passed to the callback function when MAPI calls it. This value can represent an address of significance to the client or provider. Typically, for C++ code, the lpvContext parameter represents a pointer to the address of an object.

lppAdviseSink

[out] Pointer to a pointer to an advise sink object.

Remarks

To use the HrAllocAdviseSink function, a client application or provider creates an object to receive notifications, creates a notification callback function based on the NOTIFCALLBACK function prototype that goes with that object, and passes a pointer to the object in the HrAllocAdviseSink function as the lpvContext value. Doing so performs a notification; and as part of the notification process, MAPI calls the callback function with the object pointer as the context.

MAPI implements its notification engine asynchronously. In C++, the notification callback can be an object method. If the object generating the notification is not present, the client or provider requesting notification must keep a separate reference count for that object for the object’s advise sink.

HrAllocAdviseSink should be used sparingly; it is safer for clients to create their own advise sinks.


HrComposeEID

The HrComposeEID function creates a compound entry identifier for an object, usually a message in a message store.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications
HrComposeEID(

LPMAPISESSION psession,
ULONG cbStoreRecordKey,
LPBYTE pStoreRecordKey,
ULONG cbMsgEID,
LPENTRYID pMsgEID,
ULONG FAR * pcbEID,
LPENTRYID FAR * ppEID
);
Parameters

psession

[in] Pointer to the session in use by the client application.

cbStoreRecordKey

[in] Size, in bytes, of the record key of the message store holding the message or other object. If zero is passed in the cbStoreRecordKey parameter, the ppEID parameter points to a copy of the object’s entry identifier.

pStoreRecordKey

[in] Pointer to the record key of the message store containing the message or other object.

cbMsgEID

[in] Size, in bytes, of the entry identifier of the message or other object.

pMsgEID

[in] Pointer to the entry identifier of the object.

pcbEID

[out] Pointer to the size, in bytes, of the returned identifier.

ppEID

[out] Pointer to the returned data. If the value of the cbStoreRecordKey parameter is greater than zero, the ppEID parameter points to a pointer to the compound entry identifier that is created. If cbStoreRecordKey is zero, ppEID points to a pointer to a copy of the object’s entry identifier.

Remarks

If the message or other object for which the compound entry identifier is being created resides in a message store, the identifier is created from the object’s entry identifier and the store’s record key. If the object is not in a store (that is, if the byte count for the store record key passed in cbStoreRecordKey is zero), the object’s entry identifier is simply copied.

The HrComposeEID function, primarily for use with CMC, enables CMC-based applications to work with objects in multiple stores through the use of compound entry identifiers.

See Also

HrComposeMsgID, HrDecomposeEID, HrDecomposeMsgID


HrComposeMsgID

The HrComposeMsgID function creates an ASCII entry identifier string for an object, usually a message in a message store.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications
HrComposeMsgID(

LPMAPISESSION psession,
ULONG cbStoreRecordKey,
LPBYTE pStoreRecordKey,
ULONG cbMsgEID,
LPENTRYID pMsgEID,
LPTSTR FAR * pszMsgID
);
Parameters

psession

[in] Pointer to the session in use by the client application.

cbStoreRecordKey

[in] Size, in bytes, of the record key of the message store containing the message or other object. If zero is passed in the cbStoreRecordKey parameter, the pszMsgID parameter points to a copy of the entry identifier converted to text.

pStoreRecordKey

[in] Pointer to the record key of the message store containing the message or other object.

cbMsgEID

[in] Size, in bytes, of the entry identifier of the message or other object.

pMsgEID

[in] Pointer to the entry identifier of the object.

pszMsgID

[out] Pointer to the returned data. If the cbStoreRecordKey parameter is greater than zero, the pszMsgID parameter points to a compound entry identifier converted to text. If cbStoreRecordKey is zero, it points to a noncompound entry identifier converted to text.

Remarks

If the message or other object for which the compound entry identifier is being created resides in a message store, the identifier string is created from the object’s entry identifier and the store’s record key. If the object is not in a store (that is, if the byte count for the store record key passed in the cbStoreRecordKey parameter is zero), the object’s entry identifier is simply copied and converted into a string.

The HrComposeMsgID function enables client applications based on Simple MAPI and OLE to work with objects in multiple stores through the use of compound entry identifiers.

Calling HrComposeMsgID is essentially equivalent to calling the HrComposeEID function and then the HrSzFromEntryID function.

See Also

HrDecomposeEID, HrDecomposeMsgID


HrDecomposeEID

The HrDecomposeEID function takes apart the compound entry identifier of an object, usually a message in a message store, into the entry identifier of that object within the store and that store’s entry identifier.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications
HrDecomposeEID(

LPMAPISESSION psession,
ULONG cbEID,
LPENTRYID pEID,
ULONG FAR * pcbStoreEID,
LPENTRYID FAR * ppStoreEID ,
ULONG FAR * pcbMsgEID,
LPENTRYID FAR * ppMsgEID
);
Parameters

psession

[in] Pointer to the session in use by the client application.

cbEID

[in] Size, in bytes, of the compound entry identifier to be taken apart.

pEID

[in] Pointer to the compound entry identifier to be taken apart.

pcbStoreEID

[out] Pointer to the returned size, in bytes, of the entry identifier of the message store containing the object. If the pEID parameter points to a noncompound entry identifier, then the pcbStoreEID parameter points to zero.

ppStoreEID

[out] Pointer to the returned entry identifier of the message store containing the object. If the pEID parameter points to a noncompound entry identifier, NULL is returned in the ppStoreEID parameter.

pcbMsgEID

[out] Pointer to the returned size, in bytes, of the entry identifier of the object. If the pEID parameter points to a noncompound entry identifier, then the pcbMsgEID parameter is equal to the value of the cbEID parameter.

ppMsgEID

[out] Pointer to the returned entry identifier of the object. If pEID points to a noncompound entry identifier, memory is copied so that the pointer in pEID is equal to the pointer to the pointer in the ppMsgEID parameter.

Remarks

If the identifier specified by the pEID parameter is compound, it is split into the entry identifier of the object within its message store and that store’s entry identifier. Noncompound entry identifier strings are simply copied. The compound identifier taken apart is usually one created by the HrComposeEID function.

The memory that holds the pEID parameter is released upon successful completion of this function. The calling implementation is responsible for freeing memory for the output parameters.

See Also

HrDecomposeMsgID


HrDecomposeMsgID

The HrDecomposeMsgID function takes apart the compound entry-identifier string of an object, usually a message in a message store, into the entry identifier of that object within the store and that store’s entry identifier.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications
HrDecomposeMsgID(

LPMAPISESSION psession,
LPTSTR szMsgID,
ULONG FAR * pcbStoreEID,
LPENTRYID FAR * ppStoreEID ,
ULONG FAR * pcbMsgEID,
LPENTRYID FAR * ppMsgEID
);
Parameters

psession

[in] Pointer to the session in use by the client application.

szMsgID

[in] The entry identifier string of the object.

pcbStoreEID

[out] Pointer to the returned size, in bytes, of the entry identifier string of the message store containing the object. If the szMsgID parameter points to a noncompound entry-identifier string, then the pcbStoreEID parameter points to zero.

ppStoreEID

[out] Pointer to the returned entry identifier of the message store containing the object. If the szMsgID parameter points to a noncompound entry identifier, NULL is returned in the ppStoreEID parameter.

pcbMsgEID

[out] Pointer to the returned size, in bytes, of the entry identifier string of the object (within its store). If the szMsgID parameter contains a noncompound entry-identifier string, then the pcbMsgEID parameter is equal to the value of the cbEID parameter.

ppMsgEID

[out] Pointer to the returned entry identifier string of the object (within its store).

Remarks

Noncompound entry-identifier strings are accepted. The compound identifier string taken apart is usually one created by the HrComposeMsgID function.

See Also

HrDecomposeEID


HrDispatchNotifications

The HrDispatchNotifications function forces dispatching of all queued notifications.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
HRESULT HrDispatchNotifications(

ULONG ulFlags
);
Parameters

ulFlags

Reserved; must be zero. .

Remarks

The HrDispatchNotifications function causes MAPI to dispatch all notifications that are currently queued in the MAPI notification engine without waiting for a message dispatch. This can have a beneficial effect on memory utilization. For more information, see Forcing a Notification.


HrEntryIDFromSz

The HrEntryIDFromSz function creates an entry identifier from an ASCII-encoded string, and allocates memory for the entry identifier.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications
HrEntryIDFromSz(

LPTSTR sz,
ULONG FAR * pcb,
LPENTRYID FAR * ppentry
);
Parameters

sz

[in] Pointer to the ASCII-encoded string from which to create an entry identifier.

pcb

[out] Pointer to the size, in bytes, of the entry identifier pointed to by the ppentry parameter.

ppentry

[out] Pointer to a pointer to the returned ENTRYID structure containing the new entry identifier.

See Also

HrSzFromEntryID


HrGetOneProp

The HrGetOneProp function retrieves the value of a single property from an IMAPIProp interface or an interface derived from IMAPIProp.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
HrGetOneProp(

LPMAPIPROP pmp,
ULONG ulPropTag,
LPSPropValue FAR * ppprop
);
Parameters

pmp

[in] Pointer to the interface from which the property value is to be retrieved.

ulPropTag

[in] Property tag of the property to be retrieved.

ppprop

[out] Pointer to a pointer to the returned SPropValue structure defining the retrieved property value.

Return Values

MAPI_E_NOT_FOUND

The requested object does not exist.

Remarks

Unlike the IMAPIProp::GetProps method, the HrGetOneProp function does not return any warning. Because it retrieves only one property, it simply either succeeds or fails. To retrieve multiple properties, a client application or service provider should call GetProps.

See Also

HrSetOneProp


HrIStorageFromStream

The HrIStorageFromStream function layers an IStorage interface onto an IStream object.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
HRESULT HrIStorageFromStream(

LPUNKNOWN lpUnkIn,
PIID lpInterface,
ULONG ulFlags,
LPSTORAGE FAR * lppStorageOut
);
Parameters

lpUnkIn

[in] Pointer to the IUnknown object that implements the stream object.

lpInterface

[in] Pointer to the interface identifier (IID) for the object that implements the stream object. Any of the following values can be passed in the lpInterface parameter: NULL, IID_IStream, or IID_ILockBytes. Passing NULL in lpInterface is the same as passing IID_IStream.

ulFlags

[in] Bitmask of flags that controls how the storage is to be created relative to the stream. The default setting is that the storage has read-only access and occurs within the stream starting at position zero. The following flags can be set:

STGSTRM_CREATE

Creates a new storage object for the stream object.

STGSTRM_CURRENT

Starts storage at the current position of the stream.

STGSTRM_MODIFY

Allows the calling service provider to write to the returned storage.

STGSTRM_RESET

Starts storage at position zero.

lppStorageOut

[out] Pointer to a pointer to the returned IStorage object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Store providers support the HrIStorageFromStream function using the IStorage interface for attachments. Store providers must implement the IStream interface. HrIStorageFromStream provides the IStorage interface for the IStream object. It is possible to pass either an ILockBytes or an IStream interface in lpUnkIn.


HrQueryAllRows

The HrQueryAllRows function retrieves all rows of a table.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
HRESULT HrQueryAllRows(

LPMAPITABLE ptable,
LPSPropTagArray ptaga,
LPSRestriction pres,
LPSSortOrderSet psos,
LONG crowsMax,
LPSRowSet FAR * pprows
);
Parameters

ptable

[in] Pointer to the MAPI table from which rows are retrieved.

ptaga

[in] Pointer to an SPropTagArray structure containing an array of property tags indicating the properties that identify each column in the table. These tags are used to select the table columns to be retrieved. If the ptaga parameter is NULL, HrQueryAllRows retrieves the column set of the current table view passed in the ptable parameter.

pres

[in] Pointer to an SRestriction structure containing retrieval restrictions. If the pres parameter is NULL, the calling implementation makes no restrictions.

psos

[in] Pointer to an SSortOrderSet structure identifying the sort order of the columns to be retrieved. If the psos parameter is NULL, the default sort order for the table is used.

crowsMax

[in] Maximum number of rows to be retrieved. If the value of the crowsMax parameter is zero, no limit on the number of rows retrieved is set.

pprows

[out] Pointer to the returned SRowSet structure containing the retrieved table rows.

Return Values

S_OK

The call retrieved the expected rows of a table.

MAPI_E_TABLE_TOO_BIG

The number of rows in the table is larger than the number passed for the crowsMax parameter.

Remarks

When querying all rows of a table, a client application or service provider should call HrQueryAllRows instead of the IMAPITable::QueryRows method.

See Also

IMAPITable : IUnknown


HrSetOneProp

The HrSetOneProp function changes one property of an object.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
HrSetOneProp(

LPMAPIPROP pmp,
LPSPropValue pprop
);
Parameters

pmp

[in] Pointer to an IMAPIProp interface or an interface derived from IMAPIProp.

pprop

[in] Pointer to the SPropValue structure defining the property to be changed.

Remarks

Unlike the IMAPIProp::SetProps method, the HrSetOneProp function does not return any warning. Because it sets only one property, it simply either succeeds or fails. To change multiple properties, use the faster SetProps.

See Also

HrGetOneProp


HrSzFromEntryID

The HrSzFromEntryID function encodes an entry identifier into an ASCII string, and allocates memory for the string.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications
HrSzFromEntryID(

ULONG cb,
LPENTRYID pentry,
LPTSTR FAR * psz
);
Parameters

cb

[in] Size, in bytes, of the entry identifier pointed to by the pentry parameter.

pentry

[in] Pointer to an ENTRYID structure defining the entry identifier to be encoded.

psz

[out] Pointer to the returned ASCII-encoded string.

Remarks

To use Simple MAPI to look at messages in a folder other than the Inbox folder, which is the only folder recognized by Simple MAPI, a client application or service provider must use MAPI methods. A client or provider calls these methods to enumerate the messages in the folder by looking through the contents table for the folder, which stores message entry identifiers. When a client or provider finds the entry identifier for a particular required message, it can call the HrSzFromEntryID function to convert the identifier to a string that is a Simple MAPI message identifier so the message can be manipulated in Simple MAPI. Then the client or provider can call the Simple MAPI MAPIReadMail function to retrieve the required information about the message.

See Also

HrComposeEID, HrEntryIDFromSz


HrThisThreadAdviseSink

The HrThisThreadAdviseSink function creates an advise sink that wraps an existing advise sink for thread safety.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications
HrThisThreadAdviseSink(

LPMAPIADVISESINK lpAdviseSink,
LPMAPIADVISESINK FAR * lppAdviseSink
);
Parameters

lpAdviseSink

[in] Pointer to the advise sink to be wrapped.

lppAdviseSink

[out] Pointer to a pointer to a new advise sink that wraps the advise sink pointed to by the lpAdviseSink parameter.

Remarks

The purpose of the wrapper is to ensure that notification is called on the same thread that called the HrThisThreadAdviseSink function. This function is used to protect notification callbacks that must run on a particular thread.

Client applications should use HrThisThreadAdviseSink to restrict when notifications are generated. This happens when calls are made to the IMAPIAdviseSink::OnNotify method of the advise sink object passed by the client in a previous Advise call. If notifications can be generated arbitrarily, a notification implementation might make a client multithreaded when multithreading is inappropriate. For example, this result is troublesome when an implementation has been created using a library, such as one of the Microsoft Foundation Class Libraries, that does not support multithreaded calls. In this situation, a client is difficult to test and is prone to error.

HrThisThreadAdviseSink ensures that the OnNotify methods calls occur at these appropriate times:

•	During the processing of any call to any MAPI method.

•	When window messages are being processed.

When HrThisThreadAdviseSink is implemented, any calls to the new advise sink’s OnNotify method on any thread cause the original notification method to be executed on the thread in which HrThisThreadAdviseSink was called.

For more information on notification and advise sinks, see Event Notification in MAPI and Implementing an Advise Sink Object.


HrValidateIPMSubtree

The HrValidateIPMSubtree function adds one or more standard interpersonal message (IPM) folders to a message store.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications
HrValidateIPMSubtree(

LPMDB lpMDB,
ULONG ulFlags,
ULONG FAR * lpcValues,
LPSPropValue FAR * lppProps,
LPMAPIERROR FAR * lppMapiError
);
Parameters

lpMDB

[in] Pointer to the message store object to which to add the folder or folders.

ulFlags

[in] Bitmask of flags used to control how the folders are created. The following flags can be set:

MAPI_FORCE_CREATE

The folder or folders created be verified before creation, even if message store properties indicate that they are valid. A client application or service provider typically sets this flag when an error indicates that the structure of the created folder has been damaged.

MAPI_FULL_IPM_TREE

The following folders should be created in addition to the two folders that are always created: a folder titled Folder and a folder titled Common Views, and under the IPM-subtree root folder the Inbox, Outbox and Sent Items folders. The MAPI_FULL_IPM_TREE flag is typically set when the message store in which the folders are created is the default store.

lpcValues

[out] Pointer to the number of values in the SPropValue array in the lppProps parameter is stored. The value of the lpcValues parameter can be zero if lppProps is NULL.

lppProps

[out] Pointer to a pointer to an array of SPropValue structures indicating values for PR_VALID_FOLDER_MASK and related properties is stored. The IPM Inbox’s entry identifier is included as part of this SPropValue array; this entry identifier has a special property tag coded as PROP_TAG(PT_BINARY, PROP_ID_NULL). The lppProps parameter can be NULL, indicating that the calling implementation does not require that a SPropValue array be returned.

lppMapiError

[out] Pointer to the pointer to the returned MAPIERROR structure containing version, component, and context information for an error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

Remarks

MAPI uses the HrValidateIPMSubtree function internally to construct the standard IPM folder tree in a message store when the store is first opened, or when a store is made the default store. This function can also be used by client applications to validate or repair standard message folders.

HrValidateIPMSubtree always creates a root folder in the IPM subtree, the Deleted Items folder in the root directory of the IPM subtree, and a finder folder in the message store root directory.

HrValidateIPMSubtree sets the PR_VALID_FOLDER_MASK property to indicate whether each IPM folder it creates has a valid entry identifier. The following entry identifier properties of the message store are set to the entry identifiers of the corresponding folders and returned in the lppProps parameter along with PR_VALID_FOLDER_MASK:

PR_COMMON_VIEWS_ENTRYID
PR_FINDER_ENTRYID
PR_IPM_OUTBOX_ENTRYID
PR_IPM_SENTMAIL_ENTRYID
PR_IPM_SUBTREE_ENTRYID
PR_IPM_WASTEBASKET_ENTRYID
PR_VIEWS_ENTRYID
PROP_TAG macro (PT_BINARY, PROP_ID_NULL, a placeholder tag for the IPM Inbox).

See Also

IMAPISession::OpenMsgStore


LAUNCHWIZARDENTRY

The LAUNCHWIZARDENTRY function prototype defines a function that starts the Profile Wizard application for the purpose of adding one or more message services to a profile.

Quick Info

Header file:	MAPIWZ.H
Defined function implemented by:	MAPI
Defined function called by:	Client applications
HRESULT LAUNCHWIZARDENTRY(

HWND hParentWnd,
ULONG ulFlags,
LPCTSTR FAR * lppszServiceNameToAdd,
ULONG cbBufferMax,
LPTSTR lpszNewProfileName
);
Parameters

hParentWnd

[in] A handle to the caller’s parent window. If the caller does not have a parent window, the hParentWnd parameter should be NULL.

ulFlags

[in] Bitmask of flags indicating options for the Profile Wizard. The following flags can be set:

MAPI_PW_ADD_SERVICE_ONLY

The Profile Wizard is to add only the message services listed through the lppszServiceNameToAdd parameter, and not display its page for selecting message services.

MAPI_PW_FIRST_PROFILE

The profile to be created is the first one for this workstation.

MAPI_PW_HIDE_SERVICES_LIST

The Profile Wizard’s page for selecting message services should not be displayed.

MAPI_PW_LAUNCHED_BY_CONFIG

The Profile Wizard was launched by the Control Panel configuration application.

MAPI_PW_PROVIDER_UI_ONLY

Only the service providers’s configuration dialog boxes should be displayed and the Profile Wizard’s pages should not appear. This flag can only be set if the MAPI_PW_ADD_SERVICE_ONLY flag is set.

lppszServiceNameToAdd

[in] Pointer to an array of strings containing the names of the message services to be added to the profile. The array must terminate with a NULL value.

cbBufferMax

[in] Size of the buffer pointed to by the lpszNewProfileName parameter.

lpszNewProfileName

[out] Pointer to a string buffer where the function based on LAUNCHWIZARDENTRY returns the name of the created profile.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_CALL_FAILED

An error of unexpected or unknown origin prevented the operation from completing. Possibilities include failure to initialize the MAPI subsystem for the Profile Wizard, inability to access the default profile, and an error return from the dialog box.

Remarks

The MAPI implementation of the LAUNCHWIZARDENTRY function prototype is the entry point into the MAPI Profile Wizard application. MAPI names this entry point LaunchWizard.

When the MAPI_PW_ADD_SERVICE_ONLY flag is set in the ulFlags parameter, the following rules apply:

•	The MAPI_PW_LAUNCHED_BY_CONFIG flag inhibits the welcome page from being displayed.

•	The MAPI_PW_HIDE_SERVICES_LIST and MAPI_PW_PROVIDER_UI_ONLY flags are useful only when there is no default profile. In this case these flags determine which Profile Wizard page is to be displayed.

•	If a default profile exists, none of the Profile Wizard pages are to be displayed.

•	If a default profile exists, only one message service is listed through the lppszServiceNameToAdd parameter, and that message service is already in the default profile, the Profile Wizard returns S_OK without adding anything to the profile.

For every message service to be added to the profile, the Profile Wizard calls the service’s entry point function based on the MSGSERVICEENTRY prototype. For each service provider selected from a message service to be added to the profile, the Profile Wizard calls the provider’s entry point function based on the WIZARDENTRY prototype. During interactive configuration, every user event in the property pages causes the Profile Wizard to call the provider’s callback function based on the SERVICEWIZARDDLGPROC prototype.

If a service provider being added to the profile supports the Profile Wizard pages, it must allow programmatic configuration of the profile. For more information on creating profiles, see Creating and Configuring a Profile.


LPFNBUTTON

The LPFNBUTTON function prototype defines a callback function that MAPI calls to activate an optional button control in an address book dialog box. This button is typically a Details button.

Quick Info

Header file:	MAPIDEFS.H
Defined function implemented by:	Service providers
Defined function called by:	MAPI
SCODE (STDMETHODCALLTYPE FAR * LPFNBUTTON) (

ULONG ulUIParam,
LPVOID lpvContext,
ULONG cbEntryID,
LPENTRYID lpSelection,
ULONG ulFlags
);
Parameters

ulUIParam

[in] Handle of the parent windows for any dialog boxes or windows this function displays.

lpvContext

[in] Pointer to an arbitrary value passed to the callback function when MAPI calls it. This value can represent an address of significance to the client application. Typically, for C++ code, lpvContext represents a pointer to the address of a C++ object.

cbEntryID

[in] Size, in bytes, of the entry identifier pointed to by the lpSelection parameter.

lpSelection

[in] Pointer to the entry identifier defining the selection within the dialog box.

ulFlags

Reserved; must be zero.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Client applications call a callback function based on the LPFNBUTTON prototype to define a button in a details dialog box. The client passes a pointer to the callback function in calls to the IAddrBook::Details method.

Service providers call a hook function based on the LPFNBUTTON prototype to define a button in a details dialog box. The provider passes a pointer to this hook function in calls to the IMAPISupport::Details method.

In both cases, when the dialog box is displayed and the user chooses the defined button, MAPI calls LPFNBUTTON.

See Also

BuildDisplayTable


LPropCompareProp

The LPropCompareProp function compares two property values to determine if they are equal.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
LONG LPropCompareProp(

LPSPropValue lpSPropValueA,
LPSPropValue lpSPropValueB
);
Parameters

lpSPropValueA

[in] Pointer to an SPropValue structure defining the first property value to be compared.

lpSPropValueB

[in] Pointer to an SPropValue structure defining the second property value to be compared.

Remarks

Use the LPropCompareProp function only if the types of the two properties to be compared are the same.

Before calling LPropCompareProp, a client application or service provider must first retrieve the properties for comparison with a call to the IMAPIProp::GetProps method. When a client or provider calls LPropCompareProp, the function first examines the property tags to ensure that the comparison of property values is valid. The function then compares the property values, returning an appropriate value.

If the property values are unequal, LPropCompareProp determines which one is the greater. The properties that LPropCompareProp compares do not have to belong to the same object.

LPropCompareProp returns one of the following values for most property types:

•	Less than zero if the value indicated by the lpSPropValueA parameter is less than that indicated by the lpSPropValueB parameter.

•	Greater than zero if the value indicated by lpSPropValueA is greater than that indicated by lpSPropValueB.

•	Zero if the value indicated by lpSPropValueA equals the value indicated by lpSPropValueB.

For property types that have no intrinsic ordering, such as Boolean or error types, the LPropCompareProp function returns an undefined value if the two property values are not equal. This undefined value is nonzero and consistent across calls.


MAPIAdminProfiles

The MAPIAdminProfiles function creates a profile administration object.

Quick Info

Header file:	MAPIX.H
Implemented by:	MAPI
Called by:	Client applications
HRESULT MAPIAdminProfiles(

ULONG ulFlags,
LPPROFADMIN FAR * lppProfAdmin
);
Parameters

ulFlags

[in] Bitmask of flags indicating options for the service entry function. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppProfAdmin

[out] Pointer to a pointer to the new profile administration object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

See Also

IProfAdmin::CreateProfile


MAPIAllocateBuffer

The MAPIAllocateBuffer function allocates a memory buffer.

Quick Info

Header file:	MAPIX.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE MAPIAllocateBuffer(

ULONG cbSize,
LPVOID FAR * lppBuffer
);
Parameters

cbSize

[in] Size, in bytes, of the buffer to be allocated.

lppBuffer

[out] Pointer to the returned allocated buffer.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

During MAPIAllocateBuffer call processing, the calling implementation acquires a block of memory from the operating system. The memory buffer is allocated on an even-numbered byte address. On platforms where long integer access is more efficient, the operating system allocates the buffer on an address whose size in bytes is a multiple of four.

Calling the MAPIFreeBuffer function releases the memory buffer allocated by MAPIAllocateBuffer, by calling the MAPIAllocateMore function and any buffers linked to it, when the memory is no longer needed.


MAPIAllocateMore

The MAPIAllocateMore function allocates a memory buffer that is linked to another buffer previously allocated with the MAPIAllocateBuffer function.

Quick Info

Header file:	MAPIX.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE MAPIAllocateMore(

ULONG cbSize,
LPVOID lpObject,
LPVOID FAR * lppBuffer
);
Parameters

cbSize

[in] Size, in bytes, of the new buffer to be allocated.

lpObject

[in] Pointer to an existing MAPI buffer allocated using MAPIAllocateBuffer.

lppBuffer

[out] Pointer to the returned, newly allocated buffer.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

During MAPIAllocateMore call processing, the calling implementation acquires a block of memory from the operating system. The memory buffer is allocated on an even-numbered byte address. On platforms where long integer access is more efficient, the operating system allocates the buffer on an address whose size in bytes is a multiple of four.

The only way to release a buffer allocated with MAPIAllocateMore is to pass the buffer pointer specified in the lpObject parameter to the MAPIFreeBuffer function. The link between the memory buffers allocated with MAPIAllocateBuffer and MAPIAllocateMore enables MAPIFreeBuffer to release both buffers with a single call.


MAPIDeInitIdle

The MAPIDeInitIdle function shuts down the DLL for the idle engine.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
VOID MAPIDeInitIdle(void)

Parameters

None.

Remarks

A client application or service provider should call this function when it no longer needs the idle engine, for example, when it is about to stop processing.

See Also

MAPIInitIdle, FNIDLE


MAPIFreeBuffer

The MAPIFreeBuffer function frees a memory buffer allocated with a call to the MAPIAllocateBuffer function or the MAPIAllocateMore function.

Quick Info

Header file:	MAPIX.H
Implemented by:	MAPI
Called by:	Client applications and service providers
ULONG MAPIFreeBuffer(

LPVOID lpBuffer
);
Parameters

lpBuffer

[in] Pointer to a previously allocated memory buffer. If NULL is passed in the lpBuffer parameter, MAPIFreeBuffer does nothing.

Return Values

S_OK

The call succeeded and freed the memory requested. MAPIFreeBuffer can also return S_OK on already freed locations or if memory block is not allocated with MAPIAllocateBuffer and MAPIAllocateMore.

Remarks

Usually, when a client application or service provider calls MAPIAllocateBuffer or MAPIAllocateMore, the operating system constructs in one contiguous memory buffer one or more complex structures with multiple levels of pointers. When a MAPI function or method creates a buffer with such contents, a client can later free all the structures contained in the buffer by passing to MAPIFreeBuffer the pointer to the buffer returned by the MAPI function that created the buffer. For a service provider to free a memory buffer using MAPIFreeBuffer, it must pass the pointer to that buffer returned with the provider’s support object.

The call to MAPIFreeBuffer to free a particular buffer must be made as soon as a client or provider is finished using this buffer. Simply calling the MAPILogoff function at the end of a MAPI session does not automatically release memory buffers.

A client or service provider should operate on the assumption that the pointer passed in lpBuffer is invalid after a successful return from MAPIFreeBuffer. If the pointer indicates either a memory block not allocated by the messaging system through MAPIAllocateBuffer or MAPIAllocateMore or a free memory block, the behavior of MAPIFreeBuffer is undefined.

Note  Passing a null pointer to MAPIFreeBuffer makes application cleanup code simpler and smaller because MAPIFreeBuffer can initialize pointers to NULL and then free them in the cleanup code without having to test them first.

MAPIFreeBuffer is exported, with a slightly different syntax, by both Simple MAPI and MAPI. For Simple MAPI, it is an entry point function.

See Also

IMAPISupport::GetMemAllocRoutines


MAPIGetDefaultMalloc

The MAPIGetDefaultMalloc function retrieves the address of the default MAPI memory allocation function.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
LPMALLOC MAPIGetDefaultMalloc()

Parameters

None.

Remarks

The MAPIGetDefaultMalloc function returns a pointer to the default MAPI memory allocation function.


MAPIInitialize

The MAPIInitialize function increments the MAPI subsystem reference count and initializes global data for the MAPI DLL.

Quick Info

Header file:	MAPIX.H
Implemented by:	MAPI
Called by:	Client applications
HRESULT MAPIInitialize(

LPVOID lpMapiInit
);
Parameters

lpMapiInit

[in] Pointer to a MAPIINIT_0 structure. The lpMapiInit parameter can be set to NULL.

Return Values

S_OK

The MAPI subsystem was initialized successfully.

Remarks

The MAPIInitialize function increments the MAPI reference count for the MAPI subsystem, and the MAPIUninitialize function decrements the internal reference count. Thus, the number of calls to one function must equal the number of calls to the other. MAPIInitialize returns S_OK if MAPI has not been previously initialized.

A client or service provider must call MAPIInitialize before making any other MAPI call. Failure to do so causes client or service provider calls to return the MAPI_E_NOT_INITIALIZED value.

When calling MAPIInitialize from a multithreaded application, set the lpMapiInit parameter to a MAPIINIT_0 structure that is declared as follows:

MAPIINIT_0 MAPIINIT= { 0, MAPI_MULTITHREAD_NOTIFICATIONS}

and call:

MAPIInitialize (&MAPIINIT);

When this structure is declared, MAPI creates a separate thread to handle the notification window, which continues until the initialize reference count falls to zero. A Windows NT service must set the ulflags member of the MAPIINIT_0 structure pointed to by lpMapiInit to MAPI_NT_SERVICE.

MAPIInitialize does not return any extended error information. Unlike most other MAPI calls, the meanings of its return values are strictly defined to correspond to the particular step of the initialization that failed:

Step 1 Checks parameters and flags

MAPI_E_INVALID_PARAMETER or MAPI_E_UNKNOWN_FLAGS. Caller passed invalid parameter or flag.

Step 2  Initializes registry keys required by MAPI and confirms the type of operating system. This step only happens if the client process is runnning as a service under Windows NT and sets the MAPI_NT SERVICE flag in the MAPIINIT_0.

MAPI_E_TOO_COMPLEX. (Windows NT only) The calling process is an NT service and registry keys required by MAPI could not be initalized.

Additional information may be available in the application event log.

Step 3a  Checks for compatibility between the current versions of OLE and MAPI.

MAPI_E_VERSION. The version of OLE installed on the workstation is not compatible with this version of MAPI.

Step 3b Initializes OLE.

During this step only, this function can return an error code not listed here. Any error not listed here should be assumed to come from the OLE function CoInitialize.

Step 4  Initializes per-process global variables.

MAPI_E_SESSION_LIMIT  MAPI sets up context specific to the current process. Failures may occur on Win16 if the number of processes exceeds a certain number, or on any system if available memory is exhausted.

Step 5  Initializes shared global variables of all processes.

MAPI_E_NOT_ENOUGH_RESOURCES. Not enough system resources were available to complete the operation

Step 6  Initializes the notification engine, creates its window and its thread if requested by the MAPI_MULTITHREAD_NOTIFICATIONS flag.

MAPI_E_INVALID_OBJECT  May fail if system resources are exhausted.

Step 7  Loads and initializes the profile provider. Verifies that MAPIInitialize can access the registry key where profile data are stored.

MAPI_E_NOT_INITIALIZED  The profile provider has encountered an error. In a service running under Windows NT version 3.51, the profile provider must first initialize the registry subtree called HKEY_CURRENT_USER, this occurs in Step 2. This process is subject to additional failures, including lack of access rights to the registry.


MAPIInitIdle

The MAPIInitIdle function initializes the DLL for the idle engine. A client application or service provider must call MAPIInitIdle before calling any other idle engine function.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
LONG MAPIInitIdle(

LPVOID lpvReserved
);
Parameter

lpvReserved

Reserved; must be zero.

Remarks

The MAPIInitIdle function returns zero if initialization is successful, and −1 otherwise. When MAPIInitIdle is called multiple times, only the first call succeeds.

See Also

MAPIDeinitIdle, FNIDLE


MAPILogonEx

The MAPILogonEx function logs a client application on to a session with the messaging system.

Quick Info

Header file:	MAPIX.H
Implemented by:	MAPI
Called by:	Client applications
HRESULT MAPILogonEx(

ULONG ulUIParam,
LPTSTR lpszProfileName,
LPTSTR lpszPassword,
FLAGS flFlags,
LPMAPISESSION FAR * lppSession
);
Parameters

ulUIParam

[in] Handle to the window to which the logon dialog box is modal. If no dialog box is displayed during the call, the ulUIParam parameter is ignored. This parameter can be zero.

lpszProfileName

[in] Pointer to a string containing the name of the profile to use when logging on. This string is limited to 64 characters.

lpszPassword

[in] Pointer to a string containing the password of the profile. The lpszPassword parameter can be NULL whether or not the lpszProfileName parameter is NULL. This string is limited to 64 characters.

flFlags

[in] Bitmask of flags used to control how logon is performed. The following flags can be set:

MAPI_ALLOW_OTHERS

The shared session should be returned, allowing subsequent clients to acquire the session without providing any user credentials.

MAPI_FORCE_DOWNLOAD

An attempt should be made to download all of the user’s messages before returning. If the MAPI_FORCE_DOWNLOAD flag is not set, messages can be downloaded in the background after the call to MAPILogonEx returns.

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user for logon information if required. When the MAPI_LOGON_UI flag is not set, the calling client does not display a logon dialog box and returns an error value if the user is not logged on. MAPI_LOGON_UI and MAPI_PASSWORD_UI are mutually exclusive.

MAPI_NEW_SESSION

An attempt should be made to create a new MAPI session rather than acquire the shared session. If the MAPI_NEW_SESSION flag is not set, MAPILogonEx uses an existing shared session even if the lpszprofileName parameter is not NULL.

MAPI_NO_MAIL

MAPI should not inform the MAPI spooler of the session’s existence. The result is that no messages can be sent or received within the session except through a tightly-coupled store and transport pair. A calling client sets this flag when either configuration work must be done or the client is browsing the available message stores.

MAPI_NT_SERVICE

The caller is running as a Windows NT service. Callers that are not running as a Windows NT service should not set this flag; callers that are running as a service must set this flag.

MAPI_PASSWORD_UI

A dialog box should be displayed to prompt the user for the profile password. MAPI_PASSWORD_UI cannot be set if MAPI_LOGON_UI is set because the calling client can only present one of the two dialog boxes. This dialog box does not allow the profile name to be changed; the lpszProfileName parameter must be non-NULL

MAPI_SERVICE_UI_ALWAYS

MAPILogonEx should display a configuration dialog box for each message service in the profile. The dialog boxes are displayed after the profile has been chosen but before any message service is logged on. The MAPI common dialog box for logon also contains a check box that requests the same operation.

MAPI_TIMEOUT_SHORT

The logon should fail if blocked for more than a few seconds.

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

MAPI_USE_DEFAULT

The messaging subsystem should substitute the profile name of the default profile for the lpszProfileName parameter. The MAPI_EXPLICIT_PROFILE flag is ignored unless lpszProfileName is NULL or empty.

lppSession

[out] Pointer to a pointer to the MAPI session interface.

Return Values

S_OK

The logon succeeded.

MAPI_E_LOGON_FAILED

The logon did not succeed, either because one or more of the parameters to MAPILogonEx were invalid or because there were too many sessions open already.

MAPI_E_TIMEOUT

MAPI serializes all logons through a mutex. This is returned if the MAPI_TIMEOUT_SHORT flag was set and another thread held the mutex.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

MAPI client applications call the MAPILogonEx function to log on to a session with the messaging system. All strings passed in and returned to and from MAPI calls are null terminated and must be specified in the current character set or code page of the calling client or provider’s operating system.

The lpszProfileName parameter is ignored if there is an existing previous session that called MapiLogonEx with the MAPI_ALLOW_OTHERS flag set and if the flag MAPI_NEW_SESSION is not set. If the lpszProfileName parameter is NULL or points to an empty string, and the flFlags parameter includes the MAPI_LOGON_UI flag, the MAPILogonEx function generates a logon dialog box with an empty field for the profile name.

When logging on to a specific profile, a client should pass the MAPI_NEW_SESSION flag into MAPILogonEx in addition to the profile name. Otherwise, if another client has established a shared session by logging on with MAPI_ALLOW_OTHERS, the client will be logged on to the shared session instead of to the profile requested.

The MAPI_EXPLICIT_PROFILE flag will not cause the default profile name to be used when lpszProfileName is NULL or empty unless the MAPI_USE_DEFAULT flag is also present.

The MAPI_NO_MAIL flag has several effects that result in the following when not using the MAPI spooler:

•	No messages can be sent or delivered by the MAPI spooler during this session.

•	Server based stores might still send or deliver messages.

•	Messages sent or delivered by server based stores will not be processed by any hook providers.

•	Per-message and per-recipient options for transports will not be available.

•	The status table will not contain entries for transport providers, and any transport functionality dependent on status objects (such as configuration) will not be available.

•	The message spooler row in the status table will contain the STATUS_FAILURE value.

•	Piggybacked logons will be allowed, but those logons will not cause the previous logon to receive status object updates.

See Also

IMAPISession::GetMsgStoresTable, IMAPISession::OpenMsgStore


MAPIOpenFormMgr

The MAPIOpenFormMgr function opens an IMAPIFormMgr interface on a form library provider object in the context of an existing session.

Quick Info

Header file:	MAPIFORM.H
Implemented by:	MAPI
Called by:	Client applications
MAPIOpenFormMgr(

LPMAPISESSION pSession,
LPMAPIFORMMGR FAR * ppmgr
);
Parameters

pSession

[in] Pointer to the session in use by the client application.

ppmgr

[out] Pointer to the returned IMAPIFormMgr interface.

Remarks

After a client application makes a call to the MAPIOpenFormMgr function, most subsequent forms-related interactions take place through the form library provider or an interface returned by the form library provider. Among other things, the IMAPIFormMgr interface allows the client to work with message handlers and perform resolutions between message classes and form libraries.


MAPIOpenLocalFormContainer

The MAPIOpenLocalFormContainer function returns an interface pointer to the local form library.

Quick Info

Header file:	MAPIFORM.H
Implemented by:	MAPI
Called by:	Client applications
MAPIOpenLocalFormContainer(

LPMAPIFORMCONTAINER FAR * ppfcnt
);
Parameters

ppfcnt

[out] Pointer to a pointer to the local form library interface.

Remarks

The interface to which a pointer is returned can be used by third-party installation programs to install application-specific forms into the library without the program first having to log onto MAPI.


MAPIUninitialize

The MAPIUninitialize function decrements the reference count, cleans up, and deletes per-instance global data for the MAPI DLL.

Quick Info

Header file:	MAPIX.H
Implemented by:	MAPI
Called by:	Client applications
void MAPIUninitialize()

Parameters

None.

Remarks

A client application calls the MAPIUninitialize function to end its interaction with MAPI, begun with a call to the MAPIInitialize function. After MAPIUninitialize is called, no other MAPI calls can be made by the client.

MAPIUninitialize decrements the reference count, and the corresponding MAPIInitialize function increments the reference count. Thus, the number of calls to one function must equal the number of calls to the other.


MapStorageSCode

The MapStorageSCode function maps an HRESULT return value from an OLE storage object to a MAPI return value of the SCODE type.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	IMESSAGE.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE MapStorageSCode(

SCODE StgSCode
);
Parameters

StgSCode

[in] HRESULT return value from an OLE storage object to be mapped to a MAPI SCODE value.

Return Values

S_OK

The call succeeded and returned the expected value.

MAPI_E_CALL_FAILED

The function cannot find a matching value.

Remarks

MAPI provides the MapStorageSCode function for the internal use of MAPI components that base their message implementations on the message DLL. Because these components open OLE storage themselves, they must be able to map error values returned for problems with OLE storage to MAPI SCODE values.

For more information, see Structured Storage.


MSGCALLRELEASE

The MSGCALLRELEASE function prototype defines a callback function that frees the IStorage interface after the final release of a top-level message that was opened with the OpenIMsgOnIStg function.

Quick Info

Header file:	IMESSAGE.H
Defined function implemented by:	Client applications and service providers
Defined function called by:	MAPI
void(

ULONG ulCallerData,
LPMESSAGE lpMessage
);
Parameters

ulCallerData

[in] Contains calling application information about the IMessage interface.

lpMessage

[in] Pointer to the top-level message and attachments that have been released.

Return Values

S_OK

The call succeeded and has returned the expected value or values.


MSGSERVICEENTRY

The MSGSERVICEENTRY function prototype defines a message service entry point function to support message service configuration.

Quick Info

Header file:	MAPISPI.H
Defined function implemented by:	Message services
Defined function called by:	MAPI
HRESULT MSGSERVICEENTRY(

HINSTANCE hInstance,
LPMALLOC lpMalloc,
LPMAPISUP lpMAPISup,
ULONG ulUIParam,
ULONG ulFlags,
ULONG ulContext,
ULONG cValues,
LPSPropValue lpProps,
LPPROVIDERADMIN lpProviderAdmin,
LPMAPIERROR FAR * lppMapiError
);
Parameters

hInstance

[in] Handle of the instance of the service provider DLL. The handle is typically used to retrieve resources.

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. The message service may need to use this allocation method when working with certain interfaces such as IStream.

lpMAPISup

[in] Pointer to an IMAPISupport:IUnknown interface implementation.

ulUIParam

[in] An implementation-specific 32-bit value used for passing user interface information to a function or zero. In Microsoft Windows applications, the ulUIParam parameter is the parent window handle for the configuration dialog box and is of type HWND (cast to a ULONG). A value of zero indicates that there is no parent window.

ulFlags

[in] Bitmask of flags indicating options for the service entry function. The following flags can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

MSG_SERVICE_UI_READ_ONLY

The service’s configuration user interface should display the current configuration but not allow the user to change it.

SERVICE_UI_ALLOWED

Permits a configuration dialog box to be displayed if necessary. When the SERVICE_UI_ALLOWED flag is set, the dialog box should be displayed only if the lpProps property value array is empty or does not contain a valid configuration. If SERVICE_UI_ALLOWED is not set, a dialog box might still be displayed if the UI_SERVICE_ALWAYS flag is set.

UI_CURRENT_PROVIDER_FIRST

Requests that the configuration dialog box for the active provider be displayed on top of other dialog boxes.

UI_SERVICE_ALWAYS

Requires the message service to display a configuration dialog box. If the UI_SERVICE_ALWAYS flag is not set, a configuration dialog box might still be displayed if the SERVICE_UI_ALLOWED flag is set and valid configuration information is not available from the lpProps property value array. Either SERVICE_UI_ALLOWED or UI_SERVICE_ALWAYS must be set to allow a user interface to be displayed.

ulContext

[in] The configuration operation that MAPI is currently performing. The ulContext parameter will contain one of the following values:

MSG_SERVICE_CONFIGURE

Changes to the service’s configuration should be made in the profile. If the UI_SERVICE_ALWAYS flag is set, the service should display its configuration dialog box. The dialog box should also be displayed if the SERVICE_UI_ALLOWED flag is set and the lpProps parameter is empty or does not contain valid configuration data. If lpProps contains valid data, no dialog box should be displayed and the service should use this data for making the configuration change.

MSG_SERVICE_CREATE

The service is being added to a profile. If either the UI_SERVICE_ALWAYS or SERVICE_UI_ALLOWED flag is set, the service should display its configuration dialog box. If neither flag is set, the service should fail.

MSG_SERVICE_DELETE

The service is being removed from a profile. After receiving this event, the service should return S_OK.

MSG_SERVICE_INSTALL

The service has been installed to the user’s workstation from a network, floppy disk, or other external medium. After receiving this event, the service usually returns S_OK.

MSG_SERVICE_PROVIDER_CREATE

Requests that the service create an additional instance of a provider. If the service supports this operation, it should call IProviderAdmin::CreateProvider. If the service does not support this operation, it can return MAPI_E_NO_SUPPORT.

MSG_SERVICE_PROVIDER_DELETE

Requests that the service delete a provider instance. If the service supports this operation, it should call IProviderAdmin::DeleteProvider. If the service does not support this operation, it can return MAPI_E_NO_SUPPORT.

MSG_SERVICE_UNINSTALL

The service is being removed. After receiving this event, the service can perform any clean up tasks that should be done before the service ends and then return with a success value. If the user cancels the removal, the service should return MAPI_E_USER_CANCEL.

cValues

[in] Count of property values in the array pointed to by the lpProps parameter. The value of the cValues parameter is zero if MAPI is passing no property values.

lpProps

[in] Pointer to an optional array of SPropValue structures indicating values for provider-supported properties that the function will use in configuring the message service. The function only uses this parameter if the ulContext parameter is set to MSG_SERVICE_CONFIGURE. This parameter is commonly used to pass the path to a file for a file-based service, such as a personal address book service. If the MSG_SERVICE_CONFIGURE flag is not passed in the ulFlags parameter, the lpProps parameter must be zero.

lpProviderAdmin

[in] Pointer to an IProviderAdmin:IUnknown interface that the function can use to locate profile sections for a specific provider in the current message service.

lppMapiError

[out] Pointer to a MAPIERROR structure. The structure is allocated with the MAPIAllocateBuffer function. All members are optional, although most structures will contain a valid error message string in the lpszError member. If the lpszComponent or lpszError members of the structure are present, their memory must eventually be freed by a single call to MAPIFreeBuffer  on the base structure.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_UNCONFIGURED

The service provider has not been configured.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

MAPI_E_NO_SUPPORT

The provider either does not support changes to its objects or does not support notification of changes.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

Remarks

A function defined using the MSGSERVICEENTRY function prototype enables message services to configure themselves or to perform other service-specific actions. The function primarily furnishes a dialog box in which the user can change settings specific to the message service. It can also support programmatic configuration by using the property value array passed in the lpProps parameter. Programmatic configuration is optional unless the service supports the Profile Wizard, for which it is required.

MAPI calls this entry point from the Control Panel application or in response to a client application calling IMsgServiceAdmin::CreateMsgService or IMsgServiceAdmin::ConfigureMsgService.

MAPI places no restriction on the function name that a message service uses for the MSGSERVICEENTRY prototype but prefers the name ServiceEntry. There is no restriction on the ordinal for the function, and a single provider DLL can contain more than one function. However, only one of the functions can be named ServiceEntry.

MAPI enables a message service to use Windows 95-style property sheets for its configuration dialog boxes. The message service can use the BuildDisplayTable function and the IMAPISupport::DoConfigPropsheet method to simplify configuration dialog box implementation.

It is possible for a user to cancel a MSG_SERVICE_UNINSTALL operation. In this case, the ServiceEntry function should check with the user to verify that the service should not be removed and return MAPI_E_USER_CANCEL if the service remains installed.

A function based on the MSGSERVICEENTRY prototype returns one of the HRESULT values listed. MAPI forwards this value when responding to a client’s call to IMsgServiceAdmin::ConfigureMsgService.

Message services that export a service entry function must include the PR_SERVICE_DLL_NAME and PR_SERVICE_ENTRY_NAME properties in the message service section of MAPISVC.INF.


MSProviderInit

The MSProviderInit function initializes a message store provider for operation.

Quick Info

Header file:	MAPISPI.H
Implemented by:	Message store providers
Called by:	MAPI
HRESULT MSProviderInit(

HINSTANCE hInstance,
LPMALLOC lpMalloc,
LPALLOCATEBUFFER lpAllocateBuffer,
LPALLOCATEMORE lpAllocateMore,
LPFREEBUFFER lpFreeBuffer,
ULONG ulFlags,
ULONG ulMAPIVer,
ULONG FAR * lpulProviderVer,
LPMSPROVIDER FAR * lppMSProvider
);
Parameters

hInstance

[in] The instance of the message store provider’s dynamic-link library (DLL) that MAPI used when it linked.

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. The message store provider may need to use this allocation method when working with certain interfaces such as IStream.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used where required by MAPI to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used where required by MAPI to allocate additional memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used where required by MAPI to free memory.

ulFlags

[in] Bitmask of flags. The following flag can be set:

MAPI_NT_SERVICE

The provider is being loaded in the context of a Windows NT service, a special type of process without access to any user interface.

ulMAPIVer

[in] Version number of the service provider interface (SPI) that MAPI.DLL uses. For the current version number, see the MAPISPI.H header file.

lpulProviderVer

[out] Pointer to the version number of the SPI that this message store provider uses.

lppMSProvider

[out] Pointer to a pointer to the initialized message store provider object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_VERSION

The SPI version being used by MAPI is not compatible with the SPI being used by this provider.

Remarks

MAPI calls the entry point function MSProviderInit to initialize a message store provider following a client logon.

Notes to Implementers

A message store provider must implement MSProviderInit as an entry point function in the provider’s DLL. The implementation must be based on the MSPROVIDERINIT function prototype, also specified in MAPISPI.H. MAPI defines MSPROVIDERINIT to use the standard MAPI initialization call type, STDMAPIINITCALLTYPE, which causes MSProviderInit to follow the CDECL calling convention. The advantage of CDECL is that calls can be attempted even if the number of calling parameters does not match the number of defined parameters.

A provider can be initialized multiple times, as a result of appearing in several profiles in simultaneous use or of appearing more than once in the same profile. MSProviderInit must return a different provider object in lppMSProvider for each initialization.

The provider DLL should not be linked with MAPIX.DLL. Instead, it should use these pointers for memory allocation or deallocation.

The message store provider should use the functions pointed to by lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer for most memory allocation and deallocation. In particular, the provider must use these functions to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetProps and IMAPITable::QueryRows. If the provider also expects to use the OLE memory allocator, it should call the IUnknown::AddRef method of the allocator object pointed to by the lpMalloc parameter.

For more information on writing MSProviderInit, see Loading Message Store Providers. For more information on entry point functions, see About Provider Entry Point Functions.

See Also

ABProviderInit, HPProviderInit, IMSProvider : IUnknown, XPProviderInit


NOTIFCALLBACK

The NOTIFCALLBACK function prototype defines a callback function that MAPI calls to send an event notification. This callback function can only be used when wrapped in an advise sink object created by calling the HrAllocAdviseSink function.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIDEFS.H
Defined function implemented by:	Client applications and service providers
Defined function called by:	MAPI
ULONG (STDAPICALLTYPE NOTIFCALLBACK) (

LPVOID lpvContext,
ULONG cNotification,
LPNOTIFICATION lpNotifications
);
Parameters

lpvContext

[in] Pointer to an arbitrary value passed to the callback function when MAPI calls it. This value can represent an address of significance to the client application or service provider. Typically, for C++ code, the lpvContext parameter represents a pointer to the address of a C++ object.

cNotification

[in] Count of event notifications in the array indicated by the lpNotifications parameter.

lpNotifications

[out] Pointer to the location where this function writes an array of NOTIFICATION structures containing the event notifications.

Remarks

The set of valid return values for the NOTIFCALLBACK function prototype depends on whether the function is implemented by a client application or a service provider. Clients should always return S_OK. Providers can return either S_OK or CALLBACK_DISCONTINUE. CALLBACK_DISCONTINUE is a valid return value for synchronous callback functions only; it requests that MAPI immediately stop processing the callbacks for this notification. When CALLBACK_DISCONTINUE is returned, MAPI sets the lpUlFlags parameter to NOTIFY_CANCELED when it returns from IMAPISupport::Notify.

There are limitations on what a synchronous callback function can do:

•	It cannot cause another synchronous notification to be generated.

•	It cannot display a user interface.

See Also

IMAPIAdviseSink::OnNotify


OpenIMsgOnIStg

The OpenIMsgOnIStg function creates internal memory structures and an object handle for creation of a new message object.

Quick Info

Header file:	IMESSAGE.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE OpenIMsgOnIStg(

LPMSGSESS lpMsgSess,
LPALLOCATEBUFFER lpAllocateBuffer,
LPALLOCATEMORE lpAllocateMore,
LPFREEBUFFER lpFreeBuffer,
LPMALLOC lpmalloc,
LPVOID lpMapiSup,
LPSTORAGE lpStg,
MSGCALLRELEASE FAR * lpfMsgCallRelease,
ULONG ulCallerData,
ULONG ulFlags,
LPMESSAGE FAR * lppMsg
);
Parameters

lpMsgSess

[in] Pointer to a message session object.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used by the service provider to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used by the service provider to allocate additional memory where required.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used by the service provider to free memory.

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. The message object may need to use this allocation method when working with certain interfaces such as IStream.

lpMapiSup

[in] Pointer to an optional MAPI support object used when a service provider calls OpenIMsgOnIStg.

lpStg

[in, out] Pointer to an IStorage object that is open and has read/write access. Because messages do not support write-only access, OpenIMsgOnIStg does not accept a storage object opened with write-only access.

lpfMsgCallRelease

[in] Pointer to a message-release callback function in the service provider DLL.

ulCallerData

[in] Caller data to be written by the callback function indicated by the lpfMsgCallRelease parameter.

ulFlags

[in] Bitmask of flags used to control whether the OLE IStorage::Commit method is called when the client application calls the IMessage::SaveChanges method. The following flag can be set:

IMSG_NO_ISTG_COMMIT

Controls whether the OLE method IStorage::Commit is called when the client calls SaveChanges.

lppMsg

[out] Pointer to a pointer to the opened message object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Warning  The correct process for defining a message attachment is to call the IMAPIProp::OpenProperty method with a source interface of IMessage : IMAPIProp. IMAPIProp::OpenProperty is also supported for message attachments when the source interface is the OLE interface IStorage. IStorage is supported to allow an easy way to put a Microsoft Word for Windows document into an attachment without converting the attachment to or from the OLE IStream interface. However, use of IStorage presents a danger to the predictability of IMessage when the client application or service provider passes a new attachment data pointer to OpenIMsgOnIStg and then releases objects in the wrong order.

Including the lpMsgSess parameter ensures that the new message is created within a session so that it can be closed when the session is closed. If lpMsgSess is NULL, a message is created independently of any session. If the client or service provider that created the message does not release the message or does not release open tables within the message, memory is leaked until the external application terminates.

The lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer input parameters point to the MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer functions, respectively, for use by the service provider DLL. The provider DLL should not be linked with MAPIX.DLL. Instead, it should use these pointers for memory allocation or deallocation. In particular, the provider must use these pointers when allocating memory for use by clients in calling object interfaces. For example, two provider interface methods that typically allocate memory are IMAPIProp::GetProps and IMAPITable::QueryRows. The lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer pointers are optional when the OpenIMsgOnIStg function is called with a valid lpMapiSup parameter.

If a value is supplied for lpMapiSup, IMessage supports the MAPI_DIALOG and ATTACH_DIALOG flags by calling the IMAPISupport::DoProgressDialog method to supply a progress user interface for the IMAPIProp::CopyTo and IMessage::DeleteAttach methods. The IMessage::ModifyRecipients method attempts to convert short-term entry identifiers to long-term entry identifiers by calling the support method IMAPISession::OpenAddressBook and making calls on the resulting address book object. If zero is passed for lpMapiSup, IMessage ignores MAPI_DIALOG and ATTACH_DIALOG and stores short-term entry identifiers without conversion.

MAPI does not define the behavior of multiple open operations performed on a message subobject, such as an attachment, a stream, a message store, or another message. MAPI currently allows a subobject that is already open to be opened once more, but MAPI performs the open operation by incrementing the reference count for the existing open object and returning it to the client or provider that called the IMessage::OpenAttach method or IMAPIProp::OpenProperty method. Thus, the access requested for the first open operation on a subobject is the access provided for all subsequent open operations, regardless of the access requested by the operations.

Some clients of IMessage might call the OLE method IStorage::Commit after writing data beyond what IMessage itself writes to the storage object. To aid in this, the IMessage implementation guarantees to name all substorages. Therefore, if the client keeps its names out of that namespace, there will be no accidental collisions.

The callback function mentioned with the lpfMsgCallRelease parameter is optional; if provided, it should be based on the MSGCALLRELEASE function prototype. If lpfMsgCallRelease is supplied, the IMessage interface calls the callback function when the top-level message receives its last release call. IMSG.DLL will not use the IStorage object pointed to by the lpStg parameter after making this call.

See Also

OpenIMsgSession


OpenIMsgSession

The OpenIMsgSession function groups the creation of messages within a session, so that closing the session also closes all messages created within that session.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	IMESSAGE.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE OpenIMsgSession(

LPMALLOC lpMalloc,
ULONG ulFlags,
LPMSGSESS FAR * lppMsgSess
);
Parameters

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. The client application may need to use this allocation method when working with certain interfaces such as IStream.

ulFlags

Reserved; must be zero.

lppMsgSess

[out] Pointer to the returned message-session object.

Remarks

To establish a message session, a client application should call the OpenIMsgSession function to obtain a message session pointer before calling the OpenIMsgOnIStg function for the first time to create a new message object. When finished with a message session, the client should call the CloseIMsgSession function to end it.

OpenIMsgSession is used by clients that require the ability to handle several related messages as storage objects. If only a single message is to be open at a time, a client does not need to track multiple messages. In this case, it has little cause to create a message session and no reason to call OpenIMsgSession.

For more information on the use of OLE memory allocators, see Inside OLE, Second Edition, by Kraig Brockschmidt, and the OLE Programmer’s Reference.

See Also

IMAPISession : IUnknown


OpenStreamOnFile

The OpenStreamOnFile function allocates and initializes an OLE IStream object to access the contents of a file.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
HRESULT STDMETHODCALLTYPE OpenStreamOnFile(

LPALLOCATEBUFFER lpAllocateBuffer,
LPFREEBUFFER lpFreeBuffer,
ULONG ulFlags,
LPTSTR lpszFileName,
LPTSTR lpszPrefix,
LPSTREAM FAR * lppStream
);
Parameters

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used where required by MAPI to allocate memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used where required by MAPI to free memory.

ulFlags

[in] Bitmask of flags used to control the creation or opening of the file to be accessed through the OLE IStream object. The following flags can be set:

SOF_UNIQUEFILENAME

A temporary file is to be created for the IStream object. If this flag is set, the STGM_CREATE and STGM_READWRITE flags should also be set.

STGM_CREATE

The file is to be created even if one already exists. If the lpszFileName parameter is not set, both this flag and STGM_DELETEONRELEASE must be set. If STGM_CREATE is set, the STGM_READWRITE flag must also be set.

STGM_DELETEONRELEASE

The file is to be deleted when the IStream object is released. If the lpszFileName parameter is not set, both this flag and STGM_CREATE must be set.

STGM_READ

The file is to be created or opened with read-only access.

STGM_READWRITE

The file is to be created or opened with read/write access. If this flag is not set, the STGM_CREATE flag must not be set either.

lpszFileName

[in] The filename, including path and extension, of the file for which OpenStreamOnFile initializes the IStream object. If the SOF_UNIQUEFILENAME flag is set, lpszFileName contains the path to the directory in which to create a temporary file. If lpszFileName is NULL, OpenStreamOnFile obtains an appropriate path from the system, and both the STGM_CREATE and STGM_DELETEONRELEASE flags must be set.

lpszPrefix

[in] The prefix for the filename on which OpenStreamOnFile initializes the IStream object. If set, the prefix must contain not more than three characters. If lpszPrefix is NULL, a prefix of “SOF” is used.

lppStream

[out] Pointer to a pointer to an object exposing the IStream interface.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_ACCESS

The file could not be accessed due to insufficient user permissions or because read-only files cannot be modified.

MAPI_E_NOT_FOUND

The designated file does not exist.

Remarks

The OpenStreamOnFile function has two important uses, distinguished by the setting of the SOF_UNIQUEFILENAME flag. When this flag is not set, OpenStreamOnFile opens an IStream object on an existing file, for example to copy its contents to the PR_ATTACH_DATA_BIN property of an attachment using the IStream::CopyTo method. In this case the lpszFileName parameter specifies the path and filename of the file.

When SOF_UNIQUEFILENAME is set, OpenStreamOnFile creates a temporary file to hold data for an IStream object. For this usage, the lpszFileName parameter can optionally designate the path to the directory where the file is to be created, and the lpszPrefix parameter can optionally specify a prefix for the filename.

When the calling client application or service provider is finished with the IStream object, it should free it by calling the OLE IStream::Release method.

MAPI uses the functions pointed to by lpAllocateBuffer and lpFreeBuffer for most memory allocation and deallocation, in particular to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetProps and IMAPITable::QueryRows.

Notes to Callers

The SOF_UNIQUEFILENAME flag is used to create a temporary file with a name unique to the messaging system. If this flag is set, the lpszFileName parameter specifes the path for the temporary file, and the lpszPrefix parameter contains the prefix characters of the filename. The constructed filename is <prefix>HHHH.TMP, where HHHH is a hexadecimal number. If lpszFileName is NULL, the file will be created in the temporary file directory that is returned from the Windows function GetTempPath, or the current directory if no temporary file directory has been designated.

If the SOF_UNIQUEFILENAME flag is not set, lpszPrefix is ignored, and lpszFileName should contain the fully qualified path and filename of the file to be opened or created. The file will be opened or created based on the other flags that are set in ulFlags.


OpenTnefStream

The OpenTnefStream function is called by a transport provider to initiate a MAPI Transport Neutral Encapsulation Format (TNEF) session.

Quick Info

Header file:	TNEF.H
Implemented by:	MAPI
Called by:	Transport providers
HRESULT OpenTnefStream(

LPVOID lpvSupport,
LPSTREAM lpStream,
LPTSTR lpszStreamName,
ULONG ulFlags,
LPMESSAGE lpMessage,
WORD wKey,
LPITNEF FAR * lppTNEF
);
Parameters

lpvSupport

Passes a support object or passes in NULL. If NULL, the value of the lpadrbook parameter should be non-null.

lpStream

[in] Pointer to a storage stream object (OLE IStream interface) providing a source or destination for a TNEF stream message.

lpszStreamName

[in] Pointer to the name of the data stream that the TNEF object uses. If the caller has set the TNEF_ENCODE flag (ulFlags parameter) in its call to OpenTnefStream, the lpszName parameter must specify a non-null pointer to a non-null string consisting of any characters considered valid for naming a file. MAPI does not allow string names including the characters “[“, “]”, or “:”, even if the file system permits their use. The size of the string passed for lpszName must not exceed the value of MAX_PATH, the maximum length of a string containing a path name.

ulFlags

[in] Bitmask of flags used to indicate the mode of the function. The following flags can be set:

TNEF_BEST_DATA

All possible properties are mapped into their down-level attributes, but when there is a possible data loss due to the conversion to a down-level attribute, the property is also encoded in the encapsulations. NOTE: this will cause the duplication of information in the TNEF stream. TNEF_BEST_DATA is the default if no other modes are specified.

TNEF_COMPATIBILITY

Ensures backwards compatibility with the MAIL 3.0 client. TNEF streams encoded with this flag will map all possible properties into their corresponding down-level attribute. This mode also causes the defaulting of some properties that are required by down-level clients.

TNEF_DECODE

The TNEF object on the indicated stream is opened with read-only access. The transport provider must set this flag if it wants the function to initialize the object for subsequent decoding.

TNEF_ENCODE

The TNEF object on the indicated stream is opened for read/write access. The transport provider must set this flag if it wants the function to initialize the object for subsequent encoding.

TNEF_PURE

Encodes all properties into the MAPI encapsulation blocks. Therefore, a “pure” TNEF file will consist of, at most, attMAPIProps, attAttachment, attRenddata, and attRecipTable. This mode is ideal for use when no backwards compatibility is required.

lpMessage

[in] Pointer to a message object as a destination for a decoded message with attachments or a source for an encoded message with attachments. Any properties of a destination message might be overwritten by the properties of an encoded message.

wKey

[in] A search key that the TNEF object uses to match attachments to the text tags inserted in the message text. This value should be relatively unique across messages.

lppTNEF

[out] Pointer to the new TNEF object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

A TNEF object created by the OpenTnefStream function later calls the OLE method IUnknown::AddRef to add references for the support object, the stream object, and the message object. The transport provider can release the references for all three objects with a single call to the OLE method IUnknown::Release on the TNEF object.

OpenTnefStream allocates and initializes a TNEF object (ITnef interface) for the provider to use in encoding a MAPI message (IMessage interface) into a TNEF stream message. Alternatively, the function can set up the object for the provider to use in subsequent calls to ITnef::ExtractProps to decode a TNEF stream message into a MAPI message. To free the TNEF object and close the session, the transport provider must call the inherited IUnknown::Release method on the object.

A 32-bit Windows program should call OpenTnefStream strictly as defined in the syntax, using the name provided. However, a 16-bit Windows program can set its own name for this function using the OPENTNEFSTREAM function prototype. The prototype has exactly the same syntax as the formal function, except that it designates a return value of HRESULT instead of STDMETHODIMP.

This function is the original entry point for TNEF access and has been replaced by OpenTnefStreamEx but is still used for compatibility for those already using TNEF.

See Also

IMAPISupport : IUnknown, IXPProvider::TransportLogon


OpenTnefStreamEx

The OpenTnefStreamEx function creates a TNEF object that can be used to encode or decode a message object into a TNEF data stream for use by transports or gateways and message stores. This is the entry-point for TNEF access.

Quick Info

Header file:	TNEF.H
Implemented by:	MAPI
Called by:	Transport providers
HRESULT OpenTnefStreamEx(

LPVOID lpvSupport,
LPSTREAM lpStreamName,
LPTSTR lpszStreamName,
ULONG ulFlags,
LPMESSAGE lpMessage,
WORD wKeyVal,
LPADRBOOK lpAdressBook,
LPITNEF FAR * lppTNEF
);
Parameters

lpvSupport

Passes a support object or passes in NULL. If NULL, the lpadrbook parameter should be non-null.

lpStreamName

[in] Pointer to a storage stream object, such as an OLE IStream interface, providing a source or destination for a TNEF stream message.

lpszStreamName

[in] Pointer to the name of the data stream that the TNEF object uses. If the caller has set the TNEF_ENCODE flag (ulFlags parameter) in its call to OpenTnefStream, the lpszName parameter must specify a non-null pointer to a non-null string consisting of any characters considered valid for naming a file. MAPI does not allow string names including the characters “[“, “]”, or “:”, even if the file system permits their use. The size of the string passed for the lpszName parameter must not exceed the value of MAX_PATH, the maximum length of a string containing a path name.

ulFlags

[in] Bitmask of flags used to indicate the mode of the function. The following flags can be set:

TNEF_BEST_DATA

All possible properties are mapped into their down-level attributes, but when there is a possible data loss due to the conversion to a down-level attribute, the property is also encoded in the encapsulations. NOTE: this will cause the duplication of information in the TNEF stream. TNEF_BEST_DATA is the default if no other modes are specified.

TNEF_COMPATIBILITY

Ensures backwards compatibility with the MAIL 3.0 client. TNEF streams encoded with this flag will map all possible properties into their corresponding down-level attribute. This mode also causes the defaulting of some properties that are required by down-level clients.

TNEF_DECODE

The TNEF object on the indicated stream is opened with read-only access. The transport provider must set this flag if it wants the function to initialize the object for subsequent decoding.

TNEF_ENCODE

The TNEF object on the indicated stream is opened for read/write access. The transport provider must set this flag if it wants the function to initialize the object for subsequent encoding.

TNEF_PURE

Encodes all properties into the MAPI encapsulation blocks. Therefore, a "pure" TNEF file will consist of, at most, the attributes attMAPIProps, attAttachment, attRenddata, and attRecipTable. This mode is ideal for use when no backwards compatibility is required.

lpMessage

[in] Pointer to a message object as a destination for a decoded message with attachments or a source for an encoded message with attachments. Any properties of a destination message can be overwritten by the properties of an encoded message.

wKeyVal

[in] A search key that the TNEF object uses to match attachments to the text tags inserted in the message text. This value should be relatively unique across messages.

lpAdressBook

[in] Pointer to an address book object used to get addressing information for entry identifiers.

lppTNEF

[out] Pointer to the new TNEF object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The OpenTnefStreamEx function is the recommended replacement for OpenTnefStream, the original entry point for TNEF access.

A TNEF object created by the OpenTnefStreamEx function later calls the OLE method IUnknown::AddRef to add references for the support object, the stream object, and the message object. The transport provider can release the references for all three objects with a single call to the OLE method IUnknown::Release on the TNEF object.

OpenTnefStreamEx allocates and initializes a TNEF object for the provider to use in encoding a MAPI message into a TNEF stream message. Alternatively, this function can set up the object for the provider to use in subsequent calls to ITnef::ExtractProps to decode a TNEF stream message into a MAPI message. To free the TNEF object and close the session, the transport provider must call the inherited IUnknown::Release method on the object.

A 32-bit Windows program should call OpenTnefStreamEx strictly as defined in the syntax, using the name provided. However, a 16-bit Windows program can set its own name for this function using the OPENTNEFSTREAM function prototype. The prototype has exactly the same syntax as the formal function, except that it designates a return value of HRESULT instead of STDMETHODIMP.

The base value for the wKeyVal parameter must not be zero and should not be the same for every call to OpenTnefStreamEx. Instead, use random numbers based on the system time from the run-time library’s random number generator.

See Also

IMAPISupport : IUnknown, IXPProvider::TransportLogon


OPTIONCALLBACK

The OPTIONCALLBACK function prototype defines a callback function that MAPI calls to retrieve a wrapped IMAPIProp interface that manages a transport provider’s properties.

Quick Info

Header file:	MAPISPI.H
Defined function implemented by:	Transport providers
Defined function called by:	MAPI
SCODE OPTIONCALLBACK(

HINSTANCE hInst,
LPMALLOC lpMalloc,
ULONG ulFlags,
ULONG cbOptionData,
LPBYTE lpbOptionData,
LPMAPISUP lpMAPISup,
LPMAPIPROP lpDataSource,
LPMAPIPROP FAR * lppWrappedSource,
LPMAPIERROR FAR * lppMAPIError
);
Parameters

hInst

[in] The hinstance value for this transport provider’s dynamic link library (DLL) as returned from the LoadLibrary function call made by MAPI.

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. The transport provider may need to use this allocation method when working with certain interfaces such as IStream.

ulFlags

[in] Bitmask of flags that controls what options are processed. The following flags can be set:

OPTION_TYPE_MESSAGE

Message options.

OPTION_TYPE_RECIPIENT

Recipient options.

cbOptionData

[in] Size, in bytes, of the data pointed to by the lpbOptionData parameter.

lpbOptionData

[in] Pointer to an OPTIONDATA structure containing option data for the recipient or message. This OPTIONDATA structure was passed in the call to the IXPLogon::RegisterOptions method that registered the options.

lpMAPISup

[in] Pointer to a MAPI support object the provider can use to call the methods of the IMAPISupport : IUnknown interface.

lpDataSource

[in] Pointer to an IMAPIProp : IUnknown interface that MAPI wraps for the transport provider’s use.

lppWrappedSource

[out] Pointer to a pointer to the wrapped IMAPIProp interface returned by the transport provider.

lppMAPIError

[out] Pointer to a pointer to the returned MAPIERROR structure, if any, containing version, component, and context information for the error.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

MAPI calls the transport provider’s OPTIONCALLBACK function if a transport provider has previously registered message options with the IXPLogon::RegisterOptions method. Transport providers that do not define message or recipient options do not need to implement this callback function.

MAPI passes a wrapped IMAPIProp : IUnknown interface in the lpDataSource parameter. The transport provider should build a display table, set any properties, and then pass that display table back to MAPI in a wrapped IMAPIProp interface in the lppWrappedSource parameter. MAPI uses this IMAPIProp interface to display properties in the message or recipient options dialog box that is displayed to users. When users make selections in the dialog box resulting in a call to the IMAPIProp::OpenProperty method for the PR_DETAILS_TABLE property, the transport provider gets the call and should display the display table. The transport provider must call the IMAPIProp::SetProps method followed by the IMAPIProp::SaveChanges method on any changes the user made to the display table.

For more information on how to create display tables, see Display Tables.


PpropFindProp

The PpropFindProp function searches for a specified property in a property set.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
PpropFindProp(

LPSPropValue rgprop,
ULONG cprop,
ULONG ulPropTag
);
Parameters

rgprop

[in] Array of SPropValue structures that define the properties to be searched.

cprop

[in] Count of properties in the property set indicated by the rgprop parameter.

ulPropTag

[in] Property tag for the property to search for in the property set indicated by the rgprop parameter.

Remarks

If the given property tag indicates a property of type PT_UNSPECIFIED, the PpropFindProp function finds a match only for the property identifier within the tag. Otherwise, it finds a match for the entire property tag, including the property type, and returns the property so identified.

PpropFindProp returns an SPropValue structure defining the property that matches the input property tag, and NULL if there is no match.


PreprocessMessage

The PreprocessMessage function prototype defines a function that preprocesses message contents or the format of a message.

Quick Info

Header file:	MAPISPI.H
Defined function implemented by:	Transport providers
Defined function called by:	MAPI spooler
HRESULT PreprocessMessage(

LPVOID lpvSession,
LPMESSAGE lpMessage,
LPADRBOOK lpAdrBook,
LPMAPIFOLDER lpFolder,
LPALLOCATEBUFFER AllocateBuffer,
LPALLOCATEMORE AllocateMore,
LPFREEBUFFER FreeBuffer,
ULONG FAR * lpcOutbound,
LPMESSAGE FAR * FAR * lpppMessage,
LPADRLIST FAR * lppRecipList
);
Parameters

lpvSession

[in] Pointer to the session to be used.

lpMessage

[in] Pointer to the message to be preprocessed.

lpAdrBook

[in] Pointer to the address book from which the user should select recipients for the message.

lpFolder

[in, out] Pointer to a folder. On input, the lpFolder parameter points to the folder that contains messages to be preprocessed. On output, lpFolder points to the folder where preprocessed messages have been placed.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used to allocate additional memory where required.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

lpcOutbound

[out] Pointer to the number of messages in the array pointed to by the lpppMessage parameter.

lpppMessage

[out] Pointer to a pointer to an array of pointers to preprocessed or otherwise generated messages.

lppRecipList

[out] Pointer to an optional returned ADRLIST structure, listing preprocessor-detected recipients for which the message is undeliverable. For more information on the contents of this list, see the IMAPISupport::StatusRecips method.

Remarks

A transport-provider message preprocessor can present a progress indicator during message preprocessing. However, it should never present a dialog box requiring user interaction during message preprocessing.

When a preprocessor adds large amounts of data to an outbound message, certain procedures should be followed. This type of message can be stored in a server-based message store, causing the preprocessor to access a remote store, a time-consuming procedure. To avoid having to do so, the preprocessor should have an option that enables it to store data that takes a large amount of space in a local message store and to provide a reference to that local store in the message.

The preprocessor should not release any of the objects originally passed to the function based on PreprocessMessage.

Before the MAPI spooler can call a PreprocessMessage function, the transport provider must have registered the function in a call to the IMAPISupport::RegisterPreprocessor method. After calling a PreprocessMessage function, the spooler cannot continue submitting a message until the function returns.

The MAPI spooler owns the task of submitting messages. This means the original message is never placed in an array of message pointers and that a call to the SubmitMessage methods is never required.

See Also

IAddrBook : IMAPIProp, IMAPIFolder : IMAPIContainer, IMAPISupport : IUnknown


PropCopyMore

The PropCopyMore function copies a single property value from a source location to a destination location.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE PropCopyMore(

LPSPropValue lpSPropValueDest,
LPSPropValue lpSPropValueSrc,
ALLOCATEMORE * lpfAllocMore,
LPVOID lpvObject
);
Parameters

lpSPropValueDest

[out] Pointer to the location to which this function writes an SPropValue structure defining the copied property value.

lpSPropValueSrc

[in] Pointer to the SPropValue structure containing the property value to be copied.

lpfAllocMore

[in] Pointer to the MAPIAllocateMore function to be used to allocate additional memory if the destination location is not large enough to hold the property to be copied.

lpvObject

[in] Pointer to an object for which MAPIAllocateMore will allocate space if necessary.

Remarks

A client application or service provider can use the PropCopyMore function to copy a property out of a table that is about to be freed in order to use it elsewhere.

PropCopyMore does not need to allocate memory unless the property value copied is of a type, such as PT_STRING8, that does not fit in an SPropValue structure. For these large properties, the function allocates memory using the MAPIAllocateMore function to which a pointer is passed in the lpfAllocMore parameter.

Injudicious use of PropCopyMore fragments memory; consider using the ScCopyProps function instead.


RemovePreprocessInfo

The RemovePreprocessInfo function prototype defines a function that removes from a message preprocessed information written by a function based on the PreprocessMessage function prototype.

Quick Info

Header file:	MAPISPI.H
Defined function implemented by:	Transport providers
Defined function called by:	MAPI spooler
HRESULT RemovePreprocessInfo(

LPMESSAGE lpMessage
);
Parameters

lpMessage

[in] Pointer to the preprocessed message from which information is to be removed.

Remarks

The MAPI spooler calls a RemovePreprocessInfo function. A transport provider registers the function based on RemovePreprocessInfo at the same time it registers the parallel function based on PreprocessMessage in a call to the IMAPISupport::RegisterPreprocessor method.

An image rendering suitable for fax transmission is an example of preprocessed information written by a function defined by the PreprocessMessage function prototype. The MAPI spooler usually calls a RemovePreprocessInfo function after sending a message containing preprocessed information.


RTFSync

The RTFSync function ensures that the Rich Text Format (RTF) message text matches the plain text version. It is necessary to call this function before reading the RTF version and after modifying the RTF version.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	RTF-aware client applications and message store providers
HRESULT RTFSync(

LPMESSAGE lpMessage,
ULONG ulFlags,
BOOL FAR * lpfMessageUpdated
);
Parameters

lpMessage

[in] Pointer to the message to be updated.

ulFlags

[in] Bitmask of flags used to indicate the RTF or plain text version of the message has changed. The following flags can be set:

RTF_SYNC_BODY_CHANGED

The plain text version of the message has changed.

RTF_SYNC_RTF_CHANGED

The RTF version has changed.

All other bits in the ulFlags parameter are reserved for future use.

lpfMessageUpdated

[out] Pointer to a variable indicating whether there is an updated message. TRUE if there is an updated message, FALSE otherwise.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

If the PR_RTF_IN_SYNC property is missing or is FALSE, before reading the PR_RTF_COMPRESSED property the RTFSync function should be called with the RTF_SYNC_BODY_CHANGED flag set.

If the STORE_RTF_OK flag is not set in the PR_STORE_SUPPORT_MASK property, this function should be called with the RTF_SYNC_RTF_CHANGED flag set after modifying PR_RTF_COMPRESSED.

If both PR_BODY and PR_RTF_COMPRESSED have been changed, the RTFSync function should be called with both flags set.

If the value of the lpfMessageUpdated parameter is set to TRUE, then the IMAPIProp::SaveChanges method should be called for the message. If SaveChanges is not called, the modifications will not be saved in the message.

Message store providers can use RTFSync to keep the PR_BODY and PR_RTF_COMPRESSED properties in sync.

For more information, see Supporting RTF Text for Message Store Providers.

See Also

WrapCompressedRTFStream


ScBinFromHexBounded

The ScBinFromHexBounded function converts the specified portion of a string representation of a hexadecimal number into a binary number.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE ScBinFromHexBounded(

LPTSTR sz,
LPBYTE pb,
ULONG cb
);
Parameters

sz

[in] Pointer to the null-terminated string to be converted. Valid characters include the hexadecimal characters 0 through 9 and both uppercase and lowercase characters a through f.

pb

[out] Pointer to the returned binary number.

cb

[in] Size, in bytes, of the pb parameter.

See Also

FBinFromHex


ScCopyNotifications

The ScCopyNotifications function copies a group of event notifications to a single block of memory.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE ScCopyNotifications(

int cntf,
LPNOTIFICATION rgntf,
LPVOID pvDst,
ULONG FAR * pcb
);
Parameters

cntf

[in] Count of NOTIFICATION structures in the array indicated by the rgntf parameter.

rgntf

[in] Pointer to an array of NOTIFICATION structures defining the event notifications to be copied.

pvDst

[out] Pointer to the returned notifications.

pcb

[out] Optional pointer to a variable where the size, in bytes, of the array pointed to by the rgntf parameter is stored. If not NULL, the pcb parameter is set to the number of bytes stored in the pvDst parameter.

Remarks

If NULL is passed in the pcb parameter, no copying is performed; if a non-null value is passed in pcb, the ScCopyNotifications function copies the size of the array and the array itself to a single block of memory. If pcb is not NULL, it is set to the number of bytes stored in the pvDst parameter. The pvDst parameter must be large enough to contain the entire array.


ScCopyProps

The ScCopyProps function copies the properties defined by an array of SPropValue structures to a new destination.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE ScCopyProps(

int cprop,
LPSPropValue rgprop,
LPVOID pvDst,
ULONG FAR * pcb
);
Parameters

cprop

[in] Count of properties to be copied.

rgprop

[in] Pointer to an array of SPropValue structures that define the properties to be copied. The rgprop parameter need not point to the beginning of the array, but it must point to the beginning of one of the SPropValue structures in the array.

pvDst

[in] Pointer to the initial position in memory to which this function copies the properties.

pcb

[out] Optional pointer to the size, in bytes, of the block of memory pointed to by the pvDst parameter.

Remarks

The new array and its data reside in a buffer created with a single allocation, and the ScRelocProps function can be used to adjust the pointers in the individual SPropValue structures. Prior to this adjustment, the pointers are valid.

ScCopyProps maintains the original property order for the copied property array.

The pcb parameter is optional; if it is not NULL, it is set to the number of bytes stored in the pvDst parameter.

See Also

ScDupPropset


ScCountNotifications

The ScCountNotifications function determines the size, in bytes, of an array of event notifications, and validates the memory associated with the array.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE ScCountNotifications(

int cntf,
LPNOTIFICATION rgntf,
ULONG FAR * pcb
);
Parameters

cntf

[in] Count of NOTIFICATION structures in the array indicated by the rgntf parameter.

rgntf

[in] Pointer to the array of NOTIFICATION structures whose size is to be determined.

pcb

[out] Optional pointer to the size, in bytes, of the array pointed to by the rgntf parameter. If NULL, ScCountNotifications validates the array of notifications.

Remarks

If NULL is passed in the pcb parameter, the ScCountNotifications function only validates the array of notifications but no counting is done; if a non-null value is passed in pcb, ScCountNotifications determines the size of the array and stores the result in pcb. The pcb parameter must be large enough to contain the entire array.


ScCountProps

The ScCountProps function determines the size, in bytes, of a property value array and validates the memory associated with the array.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE ScCountProps(

int cprop,
LPSPropValue rgprop,
ULONG FAR * pcb
);
Parameters

cprop

[in] Count of properties in the array indicated by the rgprop parameter.

rgprop

[in] Pointer to a range in an array of SPropValue structures that defines the properties whose size is to be determined. This range does not necessarily start at the beginning of the array.

pcb

[out] Optional pointer to the size, in bytes, of the property array.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_INVALID_PARAMETER

A property in the property value array has an identifier of PROP_ID_NULL or PROP_ID_INVALID or the property array contains a multivalued property with no property values.

Remarks

If NULL is passed in the pcb parameter, the ScCountProps function validates the array of notifications but no counting is done. If a non-null value is passed in pcb, the ScCountNotifications function determines the size of the array and stores the result in pcb. The pcb parameter must be large enough to contain the entire array.

As it is counting, ScCountProps validates the memory associated with the array. ScCountProps only works with properties about which MAPI has information.

See Also

PropCopyMore


ScCreateConversationIndex

The ScCreateConversationIndex function indicates where in a message thread a message belongs.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE ScCreateConversationIndex(

ULONG cbParent,
LPBYTE lpbParent,
ULONG FAR* lpcbIndex,
LPBYTE FAR * lppbIndex
);
Parameters

cbParent

Count of bytes in the parent conversation index.

lpbParent

Pointer to bytes in the parent conversation index. This may be NULL if cbParent is zero.

lpcbIndex

Pointer to the count of bytes in the new conversation index returned by the call.

lppbIndex

Pointer to a pointer to the new conversation index returned by the call.

Return Values

S_OK

The call succeeded and has returned the expected value or values.


ScDupPropset

The ScDupPropset function duplicates a property value array in a single block of MAPI memory combining the operations of the ScCopyProps and ScCountProps functions.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE ScDupPropset(

int cprop,
LPSPropValue rgprop,
LPALLOCATEBUFFER lpAllocateBuffer,
LPSPropValue FAR * prgprop
);
Parameters

cprop

[in] Count of property values in the array indicated by the rgprop parameter.

rgprop

[in] Pointer to an array of SPropValue structures defining the property values to be duplicated.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory for the duplicated array.

prgprop

[out] Pointer to the initial position in memory where the returned duplicated array of SPropValue structures is stored.

Return Values

S_OK

The call succeeded and has returned the expected value or values.


ScInitMapiUtil

The ScInitMapiUtil function replaces MAPIInitialize when only select utility functions are being used.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications
SCODE ScInitMapiUtil(

ULONG ulFlags
);
Parameters

ulFlags

Reserved; must be zero.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The ScInitMapiUtil and DeinitMapiUtil functions cooperate to call and release select utility functions, as opposed to MAPIInitialize, which calls core as well as utility functions. When ScInitMapiUtil calls utility functions, it also initializes the necessary memory.

When use of the functions that ScInitMapiUtil has called is complete, DeinitMapiUtil must be explicitly called to release them. In contrast, MAPIInitialize implicitly calls DeinitMapiUtil.

See Also

MapiUninitialize


ScLocalPathFromUNC

The ScLocalPathFromUNC function locates a local path counterpart to the given UNC path.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE ScLocalPathFromUNC(

LPSTR szUNC,
LPSTR szLocal,
UINT cchLocal
);
Parameters

szUNC

[in] A path in the format \\[server]\[share]\[path] of a file or directory.

szLocal

[out] A path in the format [drive:]\[path] of the same file or directory as for the szUNC parameter.

cchLocal

[in] Size of the buffer for the output string.

See Also

ScUNCFromLocalPath


ScMAPIXFromCMC

The ScMAPIXFromCMC function enables a client application to pass in a CMC session handle and get back a pointer to a MAPI session object.

Quick Info

Header file:	MAPI.H
Implemented by:	MAPI
Called by:	Client applications
SCODE ScMAPIXFromCMC(

CMC_SESSION cmcsession,
ULONG ulFlags,
LPCIID lpInterface,
LPMAPISESSION FAR * lppMAPISession
);
Parameters

cmcsession

[in] Pointer to the CMC session in use.

ulFlags

Reserved; must be zero.

lpInterface

[in] The MAPI interface being returned.

lppMAPISession

[out] Pointer to the pointer to the MAPI session in use.

Return Values

S_OK

The call succeeded and converted the CMC session to a MAPI session.

Remarks

There are no inverse functions for either the ScMAPIXFromCMC or ScMAPIXFromSMAPI function, that is, a client cannot convert to a CMC session or Simple MAPI session from a MAPI session. Also, a client cannot convert from a CMC session to a Simple MAPI session.

For more information on this function, see Using Multiple Client Interfaces and Explicit Logon with Simple MAPI.


ScMAPIXFromSMAPI

The ScMAPIXFromSMAPI function enables a client application to pass in a Simple MAPI session handle and get back a pointer to a MAPI session object.

Quick Info

Header file:	MAPI.H
Implemented by:	MAPI
Called by:	Client applications
SCODE ScMAPIXFromSMAPI(

LHANDLE lhSimpleSession,
ULONG ulFlags,
LPCIID lpInterface,
LPMAPISESSION FAR * lppMAPISession
);
Parameters

lhSimpleSession

[in] Pointer to a Simple MAPI session.

ulFlags

Reserved; must be zero.

lpInterface

[in] The MAPI interface to be returned.

lppMAPISession

[out] Pointer to a variable where a pointer for a specific MAPI session is stored.

Return Values

S_OK

The call succeeded and has converted the SMAPI session to a MAPI session.

Remarks

There are no inverse functions for either the ScMAPIXFromCMC or ScMAPIXFromSMAPI function, that is, a client cannot convert to a CMC session or Simple MAPI session from a MAPI session. Also, a client cannot convert from a Simple MAPI session to a CMC session.

For more information on using this function, see Using Multiple Client Interfaces and Explicit Logon with Simple MAPI.


ScRelocNotifications

The ScRelocNotifications function adjusts a pointer within a specified event notification array.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE ScRelocNotifications(

int cntf,
LPNOTIFICATION rgntf,
LPVOID pvBaseOld,
LPVOID pvBaseNew,
ULONG FAR * pcb
);
Parameters

cntf

[in] Count of NOTIFICATION structures in the array indicated by the rgntf parameter.

rgntf

[in] Pointer to the array of NOTIFICATION structures defining event notifications within which a pointer is to be adjusted.

pvBaseOld

[in] Pointer to the original base address of the array indicated by the rgntf parameter.

pvBaseNew

[in] The location to which ScRelocNotifications writes the new base address of the array indicated by the rgntf parameter.

pcb

[out] Pointer to the size, in bytes, of the array indicated by the pvBaseNew parameter.

Remarks

The pcb parameter to the ScRelocNotifications function is optional.

See Also

ScRelocProps


ScRelocProps

The ScRelocProps function adjusts the pointers in a SPropValue array after the array and its data have been copied or moved to a new location.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE ScRelocProps(

int cprop,
LPSPropValue rgprop,
LPVOID pvBaseOld,
LPVOID pvBaseNew,
ULONG FAR * pcb
);
Parameters

cprop

[in] Count of properties in the array pointed to by the rgprop parameter.

rgprop

[in] Pointer to an array of SPropValue structures for which pointers are to be adjusted.

pvBaseOld

[in] Pointer to the original base address of the array pointed to by the rgprop parameter.

pvBaseNew

[in] Pointer to the new base address of the array pointed to by the rgprop parameter.

pcb

[out] Optional pointer to a the size, in bytes, of the array indicated by the pvBaseNew parameter. If not NULL, the pcb parameter is set to the number of bytes stored in the pvD parameter.

Remarks

The ScRelocProps function operates on the assumption that the property value array for which pointers are adjusted was originally allocated in a single call similar to a call to the ScCopyProps function. If a client application or service provider is working with a property value that is built from disjointed blocks of memory, it should use ScCopyProps to copy properties instead.

ScRelocProps is used to maintain the validity of pointers in an SPropValue array. To maintain pointers’ validity when writing such an array to and reading it from a disk, perform the following operations:

1.	Before writing the array and data to a disk, call ScRelocProps on the array with the pvBaseNew parameter pointing to some standard value (zero, for instance).

2.	After reading the array and data from a disk, call ScRelocProps on the array with the pvBaseOld parameter equal to the same standard value used in Step 1. The array and data must be read into a buffer created with a single allocation.

3.	The pcb parameter to ScRelocProps is optional.

See Also

MAPIAllocateBuffer, ScCountProps, ScDupPropset, SCRelocNotifications


ScUNCFromLocalPath

The ScUNCFromLocalPath function locates a UNC path counterpart to the given local path.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
SCODE ScUNCFromLocalPath(

LPSTR szLocal,
LPSTR szUNC,
UINT cchUNC
);
Parameters

szLocal

[in] A path in the format [drive:]\[path] of a file or directory.

szUNC

[out] A path in the format \\[server]\[share]\[path] of the same file or directory as for the szLocal parameter.

cchUNC

[in] Size of the buffer for the output string.

See Also

ScLocalPathFromUNC


SERVICEWIZARDDLGPROC

The SERVICEWIZARDDLGPROC function prototype defines a callback function invoked by the Profile Wizard to allow a provider to react to user events when the provider’s property sheets or pages are shown.

Quick Info

Header file:	MAPIWZ.H
Defined function implemented by:	Service providers
Defined function called by:	MAPI Profile Wizard
BOOL SERVICEWIZARDDLGPROC(

HWND hDlg,
UINT wMsgID,
WPARAM wParam,
LPARAM lParam
);
Parameters

hDlg

[in] Window handle to the Profile Wizard dialog box.

wMsgID

[in] The message to be processed. In addition to all the regular Windows messages expected by a modal dialog box, the following messages can be received:

WM_CLOSE

Called when the Profile Wizard has completed. The provider should do any cleanup such as deallocating any dynamically allocated memory.

WM_COMMAND

Called for all of the provider’s controls, and in addition, WM_COMMAND is called for the Next { ID_NEXT }, and Prev { ID_PREV } buttons. When called with ID_NEXT or ID_PREV, the provider is responsible for hiding the old page’s controls and showing the controls for the next or previous page.

WM_INITDIALOG

Called even after the dialog box exists to allow the provider to initialize the controls that the Profile Wizard has added to the dialog box.

WIZ_QUERYNUMPAGES

Called to ask for the number of pages that the provider needs to display. The provider should return the number of pages instead of TRUE or FALSE. For example, use the following return statement to indicate that three pages should to be displayed:

return (BOOL)3;

wParam

[in] Contents depend on the message specified in the wMsgID parameter.

lParam

[in] Contents depend on the message specified in the wMsgID parameter.

Remarks

When the user chooses the Next button, the SERVICEWIZARDDLGPROC function is called with the WM_COMMAND message and ID_NEXT in the wParam parameter. The following steps describe what occurs between the time the user chooses Next and the time the first provider’s configuration pages are rendered.

1.	The Profile Wizard hides any controls that are on the window.

2.	The Profile Wizard adds the provider’s controls (hidden) to the page.

3.	The Profile Wizard calls SERVICEWIZARDDLGPROC, sending the WM_INITDIALOG message, so that the provider can initialize the controls.

4.	The Profile Wizard calls SERVICEWIZARDDLGPROC, sending the WIZ_QUERYNUMPAGES message. The provider returns the number of pages that it will be showing.

5.	The Profile Wizard calls SERVICEWIZARDDLGPROC, sending the WM_COMMAND message with the wParam parameter set to either ID_NEXT or ID_PREV. At this point, the provider either returns FALSE {error} or reveals its controls and returns TRUE {success}. If the Profile Wizard passes in ID_NEXT, the provider’s first page is displayed. If ID_PREV is passed in, the last page is displayed.

6.	The Profile Wizard calls the provider’s SERVICEWIZARDDLGPROC function, sending the WM_COMMAND message with the wParam parameter set to either ID_NEXT or ID_PREV (depending on which button the user chose). The provider is responsible for showing or hiding its controls and writing its data to the IMAPIProp passed to the profile wizard to step through its sequence of pages. The provider should return TRUE if the next or previous page was successfully shown, and FALSE if neither the next nor previous page could be shown. The provider needs to be aware of when it is stepping outside of its sequence of pages, and respond appropriately by hiding its controls and writing its data to the profile.

7.	If the user steps outside the provider’s range of pages, the Profile Wizard deletes the provider’s hidden controls from the dialog box and calls the next provider (or displays its next page if that was the last provider).

The value returned by SERVICEWIZARDDLGPROC is dependent on the message type sent. The recommended practice is to return TRUE if the provider processes the message and FALSE if the provider does not process the message.


SetAttribIMsgOnIStg

The SetAttribIMsgOnIStg function sets property attributes for properties of a particular object.

Quick Info

Header file:	IMESSAGE.H
Implemented by:	MAPI
Called by:	Client applications and message store providers
HRESULT SetAttribIMsgOnIStg(

LPVOID lpObject,
LPSPropTagArray lpPropTags,
LPSPropAttrArray lpPropAttrs,
LPSPropProblemArray FAR * lppPropProblems
);
Parameters

lpObject

[in] Pointer to the object for which property attributes are being set.

lpPropTags

[in] Pointer to an SPropTagArray structure containing an array of property tags indicating the properties for which property attributes are being set.

lpPropAttrs

[in] Pointer to an SPropAttrArray structure listing the property attributes to set.

lppPropProblems

[out] Pointer to the returned SPropProblemArray structure containing a set of property problems. This structure identifies problems encountered if SetAttribIMsgOnIStg has been able to set some properties, but not all. If a pointer to NULL is passed in the lppPropProblems parameter, no property problem array is returned even if some properties were not set.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_W_ERRORS_RETURNED

The call succeeded overall, but one or more properties could not be accessed and were returned with a property type of PT_ERROR.

Remarks

A message store provider usually calls the SetAttribIMsgOnIStg function.

In the lpPropAttrs parameter, the number and position of the attributes must match the number and position of the property tags passed in the lpPropTags parameter.

The SetAttribIMsgOnIStg function is used to make message properties read-only when required by the IMessage schema. The sample message store provider uses it for this purpose. For more information, see Messages.

See Also

GetAttribIMsgOnIStg


SzFindCh

The SzFindCh function searches for the first occurrence of a character in a null-terminated string.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
LPTSTR SzFindCh(

LPCTSTR lpsz,
USHORT ch
);
Parameters

lpsz

[in] Pointer to the null-terminated string to be searched.

ch

[in] The character to be searched for.

Return Values

SzFindCh returns a pointer to the first occurrence of the character in the string. If the character does not occur anywhere in the string, or if the lpsz parameter is NULL, a value of NULL is returned.

Remarks

The SzFindCh function searches for an exact match only; it is sensitive to case and diacritical differences. Searches in the Unicode and DBCS formats are supported.


SzFindLastCh

The SzFindLastCh function searches for the last occurrence of a character in a null-terminated string.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
LPTSTR SzFindLastCh(

LPCTSTR lpsz,
USHORT ch
);
Parameters

lpsz

[in] Pointer to the null-terminated string to be searched.

ch

[in] The character to be searched for.

Return Values

SzFindLastCh returns a pointer to the last occurrence of the character in the string. If the character does not occur anywhere in the string, or if the lpsz parameter is NULL, a value of NULL is returned.

Remarks

The SzFindLastCh function searches for an exact match only; it is sensitive to case and diacritical differences. Searches in the Unicode and DBCS formats are supported.


SzFindSz

The SzFindSz function searches for the first occurrence of a null-terminated substring in a null-terminated string.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
LPTSTR SzFindCh(

LPCTSTR lpsz,
LPCTSTR lpszKey
);
Parameters

lpsz

[in] Pointer to the null-terminated string to be searched. lpsz must not exceed 65536 characters.

lpszKey

[in] Pointer to the null-terminated substring to be searched for. lpszKey must not exceed 65536 characters.

Return Values

SzFindSz returns a pointer to the first character of the first occurrence of the substring in the string. If the substring does not occur anywhere in the string, if lpszKey is larger than lpsz, or if either parameter is NULL, a value of NULL is returned.

Remarks

The SzFindSz function searches for an exact match only; it is sensitive to case and diacritical differences. Searches in the Unicode and DBCS formats are supported. The length limit on both parameters is in characters, not necessarily bytes.


UFromSz

The UFromSz function converts a null-terminated string of decimal digits into an unsigned integer.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
UINT UFromSz(

LPCTSTR lpsz
);
Parameters

lpsz

[in] Pointer to the null-terminated string to be converted. lpsz must not exceed 65536 characters.

Return Values

UFromSz returns an unsigned integer. If the string does not begin with at least one decimal digit, a binary zero is returned.

Remarks

The UFromSz function stops converting when it reaches the first character in the string that is not a decimal digit. For example, given the string “55”, UFromSz returns the integer value 55. Given the string “5a5b”, the function returns the integer value 5. Given the string “a5b5”, UFromSz returns zero.

UFromSz is sensitive to diacritical differences. Strings in the Unicode and DBCS formats are supported. The length limit on lpsz is in characters, not necessarily bytes.


UlFromSzHex

The UlFromSzHex function converts a null-terminated string of hexadecimal digits into an unsigned long integer.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
ULONG UlFromSzHex(

LPCTSTR lpsz
);
Parameters

lpsz

[in] Pointer to the null-terminated string to be converted. lpsz must not exceed 65536 characters.

Return Values

UlFromSzHex returns an unsigned long integer. If the string does not begin with at least one hexadecimal digit, a binary zero is returned.

Remarks

The UlFromSzHex function stops converting when it reaches the first character in the string that is not a hexadecimal digit. For example, given the string “5a”, UlFromSzHex returns the integer value 90. Given the string “5g5h”, the function returns the integer value 5. Given the string “g5h5”, UlFromSzHex returns zero.

UlFromSzHex is sensitive to diacritical differences but allows both ‘a’ through ‘f’ and ‘A’ through ‘F’ for hexadecimal digits. Strings in the Unicode and DBCS formats are supported. The length limit on lpsz is in characters, not necessarily bytes.


UlAddRef

The UlAddRef function provides an alternative way to invoke the OLE method IUnknown::AddRef.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
ULONG UlAddRef(

LPVOID punk
);
Parameters

punk

[in] Pointer to an interface derived from the IUnknown interface, in other words any MAPI interface.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_CALL_FAILED

An error of unexpected or unknown origin prevented the operation from completing.

Remarks

The UlAddRef function generates less code than the AddRef method and can be used in situations requiring a minimum of code.

UlAddRef returns the value returned by the IUnknown::AddRef method, which is the new value of the reference count for the interface. The value is nonzero.

For more information on IUnknown::AddRef, see Implementing the IUnknown Interface.


UlPropSize

The UlPropSize function obtains the size of a single property value.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
ULONG UlPropSize(

LPSPropValue lpSPropValue
);
Parameters

lpSPropValue

[in] Pointer to an SPropValue structure defining the property to be measured.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_CALL_FAILED

An error of unexpected or unknown origin prevented the operation from completing.

Remarks

The UlPropSize function returns the size, in bytes, of the property value for the specified property. It disregards the size of the remainder of the SPropValue structure.


UlRelease

The UlRelease function provides an alternative way to invoke the OLE method IUnknown::Release.

Note  This function may not be supported in future versions of MAPI.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
ULONG UlRelease(

LPVOID punk
);
Parameters

punk

[in] Pointer to an interface derived from the IUnknown interface, in other words any MAPI interface.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_CALL_FAILED

An error of unexpected or unknown origin prevented the operation from completing.

Remarks

The reference count is the number of existing pointers to the object to be released.

If the punk parameter is NULL, the function returns immediately without calling IUnknown::Release. This feature can save code if an application or provider declares an interface pointer and initializes it to NULL. Code is used in the method indication but saved in not testing for NULL.

UlRelease returns the value returned by the IUnknown::Release method, which can be equal to the reference count for the object to be released.

For more information on IUnknown::Release, see Implementing the IUnknown Interface.


UlValidateParameters

The UlValidateParameters macro calls an internal function to check the parameters client applications have passed to service providers and MAPI.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
HRESULT UlValidateParameters(

METHODS eMethod,
LPVOID First
);
Parameters

eMethod

[in] Specifies, by enumeration, the method to validate.

First

[in] Pointer to the first argument on the stack.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_CALL_FAILED

An error of unexpected or unknown origin prevented the operation from completing.

Remarks

The UlValidateParameters macro has been superseded by the UlValidateParms macro. UlValidateParameters does not work correctly on RISC platforms and is now prevented from compiling on them. It still compiles and works correctly on Intel platforms, but UlValidateParms is recommended on all platforms.


UlValidateParms

The UlValidateParms macro calls an internal function to check the parameters client applications have passed to service providers and MAPI.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
HRESULT UlValidateParms(

METHODS eMethod,
LPVOID First
);
Parameters

eMethod

[in] Specifies, by enumeration, the method to validate.

First

[in] Pointer to the first argument on the stack.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_CALL_FAILED

An error of unexpected or unknown origin prevented the operation from completing.

Remarks

Parameters passed between MAPI and service providers are assumed to be correct and undergo only debug validation with the CheckParms macro. Providers should check all parameters passed in by client applications, but clients should assume that MAPI and provider parameters are correct. Use the HR_FAILED macro to test return values.

The UlValidateParms macro is called differently depending on whether the calling code is C or C++. This macro is used to validate parameters for the few IUnknown and MAPI methods that return ULONG rather than HRESULT values; the ValidateParms macro works for all others.

For more information on parameter validation, see Validating Parameters to Interface Methods.


ValidateParameters

The ValidateParameters macro calls an internal function to check the parameters client applications have passed to service providers.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
HRESULT ValidateParameters(

METHODS eMethod,
LPVOID First
);
Parameters

eMethod

[in] Specifies, by enumeration, the method to validate.

First

[in] Pointer to the first argument on the stack.

Return Values

S_OK

All of the parameters are valid.

MAPI_E_CALL_FAILED

One or more of the parameters are not valid.

Remarks

The ValidateParameters macro has been superseded by the ValidateParms macro. ValidateParameters does not work correctly on RISC platforms and is now prevented from compiling on them. It still compiles and works correctly on Intel platforms, but ValidateParms is recommended on all platforms.


ValidateParms

The ValidateParms macro calls an internal function to check the parameters client applications have passed to service providers.

Quick Info

Header file:	MAPIVAL.H
Implemented by:	MAPI
Called by:	Service providers
HRESULT ValidateParms(

METHODS eMethod,
LPVOID First
);
Parameters

eMethod

[in] Specifies, by enumeration, the method to validate.

First

[in] Pointer to the first argument on the stack.

Return Values

S_OK

All of the parameters are valid.

MAPI_E_CALL_FAILED

One or more of the parameters are not valid.

Remarks

Parameters passed between MAPI and service providers are assumed to be correct and undergo only debug validation with the CheckParms macro. Providers should check all parameters passed in by client applications, but clients should assume that MAPI and provider parameters are correct. Use the HR_FAILED macro to test return values.

ValidateParms is called differently depending on whether the calling code is C or C++. C++ passes an implicit parameter known as this to each method call, which becomes explicit in C and is the address of the object. The first parameter, eMethod, is an enumerator made from the interface and method being validated and tells what parameters to expect to find on the stack. The second parameter is different for C and C++. In C++ it is called First, and it is the first parameter to the method being validated. The second parameter for the C language, ppThis, is the address of the first parameter to the method which is always an object pointer. In both cases, the second parameter gives the address of the beginning of the method’s parameter list, and based on eMethod, moves down the stack and validates the parameters.

Providers implementing common interfaces such as IMAPITable and IMAPIProp should always check parameters using the ValidateParms function in order to ensure consistency across all providers. Additional parameter validation functions have been defined for some complex parameter types to be used instead as appropriate. See the reference topics for the following functions:

FBadColumnSet

FBadEntryList

FBadProp

FBadPropTag

FBadRestriction

FBadRglpNameID

FBadRglpszW

FBadRow

FBadRowSet

FBadSortOrderSet

Inherited methods use the same parameter validation as the interface from which they inherit. For example, the parameter checking for IMessage and IMAPIProp should be the same.

For more information on parameter validation, see Validating Parameters to Interface Methods.

See Also

UlValidateParms


WIZARDENTRY

The WIZARDENTRY function prototype defines a service provider entry point function for the Profile Wizard. The Profile Wizard calls this entry point function to retrieve enough information to display the provider’s configuration property sheets.

Quick Info

Header file:	MAPIWZ.H
Defined function implemented by:	Service providers
Defined function called by:	MAPI Profile Wizard
ULONG WIZARDENTRY(

HINSTANCE hProviderDLLInstance,
LPTSTR FAR * lpcsResourceName,
DLGPROC FAR * lppDlgProc,
LPMAPIPROP lpMAPIProp,
LPVOID  lpMapiSupportObject    );
Parameters

hProviderDLLInstance

[in] Instance handle of the provider’s DLL.

lpcsResourceName

[out] Pointer to a string containing the full name of the dialog resource that should be displayed by the Profile Wizard during configuration. The maximum size of the string, including the NULL terminator, is 32 characters.

lppDlgProc

[out] Pointer to a standard Windows dialog box procedure that will be called by the Profile Wizard to notify the provider of various events.

lpMapiProp

[in] Pointer to a property interface implementation that provides access to the configuration properties. When the wizard is finished configuring all providers, it writes the properties to the profile by calling IMsgServiceAdmin::ConfigureMsgService.

lpMapiSupportObject

[in] Pointer to a MAPI support object.

Return Values

S_OK

The provider’s WIZARDENTRY function was called successfully.

MAPI_E_CALL_FAILED

An error of unexpected or unknown origin prevented the operation from completing.

Remarks

The Profile Wizard calls the WIZARDENTRY function when it is ready to display the provider’s configuration user interface. The pointer to the property interface implementation should be stored by the provider for future reference. This pointer allows the provider access to the profile. During configuration, providers should add their configuration properties to this object. After all providers have been configured, the Profile Wizard adds these properties to the profile.

The name of the WIZARDENTRY function must be placed in the WIZARD_ENTRY_NAME entry in MAPISVC.INF.

The resource name is the same as the dialog resource that will be rendered in the pane of the Profile Wizard. The resource that is passed back needs to contain all the pages — in a single dialog resource — that should be displayed by the Profile Wizard. When the Profile Wizard receives this resource, it ignores the dialog style — but not the control styles — and creates all the controls as children of the Profile Wizard page. All controls are initially hidden. Providers should ensure that the coordinates for their controls are zero or zero-based, and that they don’t exceed a maximum width of 200 dialog units and a maximum height of 150 dialog units. Control identifiers below 400 are reserved for the Profile Wizard. The Profile Wizard displays the provider’s title in bold text above the provider’s user interface.

For more information on using this function, see About Profile Wizard Entry Point Functions.


WrapCompressedRTFStream

The WrapCompressedRTFStream function creates a text stream in uncompressed Rich Text Format (RTF) from the compressed format used in the PR_RTF_COMPRESSED property.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications
HRESULT WrapCompressedRTFStream(

LPSTREAM lpCompressedRTFStream,
ULONG ulflags,
LPSTREAM FAR * lpUncompressedRTFStream
);
Parameters

lpCompressedRTFStream

[in] Pointer to a stream opened on the PR_RTF_COMPRESSED property of a message.

ulFlags

[in] Bitmask of option flags for the function. The following flag can be set:

MAPI_MODIFY

Whether the client intends to read or write the wrapped stream interface that is returned.

STORE_UNCOMPRESSED_RTF

Uncompressed RTF should be written to the stream pointed to by lpCompressedRTFStream

lpUncompressedRTFStream

[out] Pointer to the location where WrapCompressedRTFStream returns a stream for the uncompressed RTF.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

If the MAPI_MODIFY flag is passed in the ulFlags parameter, the lpCompressedRTFStream parameter must already be open for reading and writing. New, uncompressed RTF text should be written into the stream interface returned in lpUncompressedRTFStream. Because it is not possible to append the existing stream, the entire message text must be written.

If zero is passed in the ulFlags parameter, then lpCompressedRTFStream may be opened read-only. Only the entire message text can be read out of the stream interface returned in lpUncompressedRTFStream; it is not possible to search into the middle of the stream and begin reading.

The WrapCompressedRTFStream assumes that the compressed stream’s pointer is set to the beginning of the stream. Certain OLE IStream methods are not supported by the returned uncompressed stream. These include IStream::Clone, IStream::LockRegion, IStream::Revert, IStream::Seek, IStream::SetSize, IStream::Stat, and IStream::UnlockRegion. In order to copy to the entire stream, a read/write loop is needed.

Because the client writes new RTF in uncompressed format, it should use WrapCompressedRTFStream, rather than directly writing to the stream. RTF-aware clients should search for the STORE_UNCOMPRESSED_RTF flag in the PR_STORE_SUPPORT_MASK property and pass it to WrapCompressed RTFStream if it is set.

See Also

RTFSync


WrapStoreEntryID

The WrapStoreEntryID function converts a message store’s internal entry identifier to an entry identifier more usable by the messaging system.

Quick Info

Header file:	MAPIUTIL.H
Implemented by:	MAPI
Called by:	Client applications and service providers
WrapStoreEntryID(

ULONG ulFlags,
LPTSTR szDLLName,
ULONG cbOrigEntry,
LPENTRYID lpOrigEntry,
ULONG * lpcbWrappedEntry,
LPENTRYID * lppWrappedEntry
);
Parameters

ulFlags

[in] Bitmask of flags. The following flag can be set:

MAPI_UNICODE

The strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

szDLLName

[in] The name of the message store provider DLL.

cbOrigEntry

[in] Size, in bytes, of the original entry identifier for the message store.

lpOrigEntry

[in] Pointer to an ENTRYID structure containing the original entry identifier.

lpcbWrappedEntry

[out] Pointer to the size, in bytes, of the new entry identifier.

lppWrappedEntry

[out] Pointer to a pointer to an ENTRYID structure containing the new entry identifier.

Remarks

A message store object retains an internal entry identifier which is meaningful only to service providers coresident with that message store. For other messaging components, MAPI supplies a wrapped version of the internal entry identifier that makes it recognizable as belonging to the message store. Coresident service providers should always be given the original unwrapped message store entry identifier; client applications should always be given the wrapped version, which is then usable anywhere in the messaging domain and in other domains.

A service provider can wrap a message store entry identifier using either the WrapStoreEntryID function or the IMAPISupport::WrapStoreEntryID method, which calls the WrapStoreEntryID function. The provider must wrap the entry identifier when exposing the message store’s PR_ENTRYID property or writing it into a profile section, and when exposing the PR_STORE_ENTRYID property. MAPI wraps a message store entry identifier when responding to an IMAPISession::OpenMsgStore call.

When a client application passes a wrapped message store entry identifier to MAPI, for example in a IMAPISession::OpenEntry call, MAPI unwraps the entry identifier before using it to call a provider method such as IMSProvider::Logon or IMSProvider::CompareStoreIDs.


XPProviderInit

The XPProviderInit function initializes a transport provider for operation.

Quick Info

Header file:	MAPISPI.H
Implemented by:	Transport providers
Called by:	MAPI
HRESULT XPProviderInit(

HINSTANCE hInstance,
LPMALLOC lpMalloc,
LPALLOCATEBUFFER lpAllocateBuffer,
LPALLOCATEMORE lpAllocateMore,
LPFREEBUFFER lpFreeBuffer,
ULONG ulFlags,
ULONG ulMAPIVer,
ULONG FAR * lpulProviderVer,
LPXPPROVIDER FAR * lppXPProvider
);
Parameters

hInstance

[in] The instance of the transport provider’s dynamic-link library (DLL) that MAPI used when it linked.

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. The transport provider may need to use this allocation method when working with certain interfaces such as IStream.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used where required by MAPI to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used where required by MAPI to allocate additional memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used where required by MAPI to free memory.

ulFlags

[in] Bitmask of flags. The following flag can be set:

MAPI_NT_SERVICE

The provider is being loaded in the context of a Windows NT service, a special type of process without access to any user interface.

ulMAPIVer

[in] Version number of the service provider interface (SPI) that MAPI.DLL uses. For the current version number, see the MAPISPI.H header file.

lpulProviderVer

[out] Pointer to the version number of the SPI that this transport provider uses.

lppXPProvider

[out] Pointer to a pointer to the initialized transport provider object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_VERSION

The SPI version being used by MAPI is not compatible with the SPI being used by this provider.

Remarks

MAPI calls the entry point function XPProviderInit to initialize a transport provider following a client logon.

Notes to Implementers

A transport provider must implement XPProviderInit as an entry point function in the provider’s DLL. The implementation must be based on the XPPROVIDERINIT function prototype, also specified in MAPISPI.H. MAPI defines XPPROVIDERINIT to use the standard MAPI initialization call type, STDMAPIINITCALLTYPE, which causes XPProviderInit to follow the CDECL calling convention. The advantage of CDECL is that calls can be attempted even if the number of calling parameters does not match the number of defined parameters.

A provider can be initialized multiple times, as a result of appearing in several profiles in simultaneous use or of appearing more than once in the same profile. XPProviderInit must return a different provider object in lppXPProvider for each initialization.

The transport provider should use the functions pointed to by lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer for most memory allocation and deallocation. In particular, the provider must use these functions to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetProps and IMAPITable::QueryRows. If the provider also expects to use the OLE memory allocator, it should call the IUnknown::AddRef method of the allocator object pointed to by the lpMalloc parameter.

For more information on writing XPProviderInit, see Initializing the Transport Provider. For more information on entry point functions, see About Provider Entry Point Functions.

See Also

ABProviderInit, HPProviderInit, IXPProvider : IUnknown, MSProviderInit


MAPI Interfaces

The documentation for each interface consists of an introductory section that includes a brief description of the interface’s purpose followed by a “Quick Info” table, which contains the following information:

Header file:	The header file where the interface is defined and that must be included when you compile your source code.
Exposed by:	The object that exposes the interface.
Implemented by:	A list of the components that provide an implementation of the interface.
Called by:	A list of the components that typically call the methods of the interface.
Corresponding pointer type:	The pointer type for the object that exposes the interface.
Transaction model:	If non-transacted, changes take effect immediately; if transacted, changes do not take effect until SaveChanges is called.
Following the “Quick Info” table is another table that lists all the methods of this interface in vtable order. A vtable is an array of function pointers created by the compiler containing one function pointer for each method of a MAPI object. The methods are listed in the same order that they are declared. Methods inherited from other interfaces are not shown in the “Vtable Order” table but can be used in the same way as documented in the interface that defines them.

Following the “Vtable Order” table, the interface’s methods are then covered in alphabetical order. For each method, the documentation includes a brief purpose statement for the method and its syntax followed by this information:

Heading	Content
Parameters	A description of each parameter in the method.
Return Values	A description of the unique values that the method can return. These are the values that callers should check for in their code.
Remarks	A description of why and how the method is used.
See Also	Cross-references to other topics in the MAPI Programmer’s Reference.


IABContainer : IMAPIContainer

The IABContainer interface provides access to address book containers. MAPI and client applications call the methods of the IABContainer interface to perform name resolution and to create, copy, and delete recipients.

Quick Info

Header file:	MAPIDEFS.H
Exposed by:	Address book container objects
Implemented by:	Address book providers
Called by:	MAPI and client applications
Corresponding pointer type:	LPABCONT
Transaction model:	Non-transacted
Vtable Order

CreateEntry	Creates a new entry, which can be a messaging user, a distribution list, or another container.
CopyEntries	Copies one or more entries,  typically messaging users or distribution lists .
DeleteEntries	Removes one or more entries, typically messaging users, distribution lists, or other containers.
ResolveNames	Performs name resolution for one or more recipient entries.
Required properties	Access
PR_CONTAINER_FLAGS	Read/write
PR_DISPLAY_NAME	Read/write
PR_ENTRYID	Read-only
PR_OBJECT_TYPE	Read-only
PR_RECORD_KEY	Read-only
Optional properties	Access
PR_CONTAINER_CONTENTS	Read-only
PR_CONTAINER_HIERARCHY	Read-only
PR_DEF_CREATE_DL	Read-only
PR_DEF_CREATE_MAILUSER	Read-only
PR_DISPLAY_TYPE	Read-only
Remarks

IABContainer inherits indirectly from IUnknown through IMAPIContainer and IMAPIProp. Address book providers implement IABContainer.

Any number of messaging user objects, distribution lists, and other address book containers can exist within an address book container. As with any container, clients or service providers can use an address book container to open one of its entries or to retrieve a hierarchy table or contents table. Address book containers also provide name resolution and, depending on the provider, the ability to add, remove, or modify entries.

MAPI defines a special address book container, called the Personal Address Book (PAB), that is meant to hold entries copied from other containers. A PAB is always modifiable. Users typically populate their PAB with entries designating the recipients with which they most frequently communicate. A PAB can also hold one-off addresses, new recipients not yet a part of any address book container.


IABContainer::CopyEntries

The IABContainer::CopyEntries method copies one or more entries,  typically messaging users or distribution lists.

Quick Info

See IABContainer : IMAPIContainer

HRESULT CopyEntries(

LPENTRYLIST lpEntries,
ULONG ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
)
Parameters

lpEntries

[in] Pointer to an array of ENTRYLIST structures containing the entry identifiers of the entries to copy.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays. The ulUIParam parameter must be zero if the AB_NO_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] Pointer to a progress object for displaying a progress indicator or NULL. If lpProgress is NULL, a progress indicator should be displayed using the progress object supplied by MAPI through the IMAPISupport::DoProgressDialog method. The lpProgress parameter is ignored if AB_NO_DIALOG is set in ulFlags.

ulFlags

[in] Bitmask of flags that controls how the copy operation is performed. The following flags can be set:

AB_NO_DIALOG

Suppresses display of a progress indicator. If this flag is not set, a progress indicator is displayed.

CREATE_CHECK_DUP_LOOSE

Suggests that a loose level of duplicate entry checking should be performed. The implementation of loose duplicate entry checking is provider-specific. For example, a provider can define a loose match as any two entries having the same display name.

CREATE_CHECK_DUP_STRICT

Suggests that a strict level of duplicate entry checking should be performed. The implementation of strict duplicate entry checking is provider-specific. For example, a provider can define a strict match as any two entries having both the same display name and messaging address.

CREATE_REPLACE

A new entry should replace an existing one if it is determined that the two are duplicates.

Return Values

S_OK

The copy operation succeeded.

MAPI_W_PARTIAL_COMPLETION

The copy operation succeeded overall, but one or more of the recipients could not be copied. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IABContainer::CopyEntries method copies recipients from the same container or a different container. A call to CopyEntries is functionally equivalent to making the following three calls for each recipient to be copied:

1.	IABContainer::CreateEntry to create the new recipient.

2.	The new recipient’s IMAPIProp::SaveChanges method to perform a save.

3.	The new recipient’s IUnknown::Release method to release the container’s reference.

The Personal Address Book (PAB) supplied by MAPI does not support the CREATE_REPLACE flag. For duplicate entry checking, the PAB defines “loose” to mean that two entries are duplicates if their original display names are equal and “strict” to mean that two entries are duplicates if both their original display names and search keys are equal. In the PAB, the original display name is defined as the transmittable display name, if available. Otherwise, it is simply the display name. Combined with the PR_SEARCH_KEY property, these criteria usually eliminate duplicates in most applications whether automated or user driven.

Notes to Implementers

All containers that support IABContainer::CopyEntries must be modifiable. Set your container’s AB_MODIFIABLE flag in its PR_CONTAINER_FLAGS property to indicate that it is modifiable.

You must support all of the ulFlags flags; however, the interpretation and use of these flags is implementation-specific. That is, you can determine what the semantics of CREATE_CHECK_DUP_LOOSE and CREATE_CHECK_DUP_STRICT mean within the context of your implementation. If you cannot or do not determine whether an entry is a duplicate, always allow the entry to be copied.

If CREATE_REPLACE is set, always copy the entry regardless of whether CREATE_CHECK_DUP_LOOSE or CREATE_CHECK_DUP_STRICT is set and whether or not the entry is a duplicate.

If CREATE_REPLACE is not set and CREATE_CHECK_DUP_STRICT is set, check for duplicates. If any entries are determined to be duplicates, do not copy the entry.

You do not need to support the CREATE_REPLACE flag; not supporting CREATE_REPLACE means that you can ignore it and always perform a copy.

Return the warning MAPI_W_PARTIAL_COMPLETION only if a nonduplicate entry cannot be copied.

Notes to Callers

Use the CREATE_CHECK_DUP_LOOSE and CREATE_CHECK_DUP_STRICT flags to suggest to the provider how you would like the container to perform duplicate entry checking. If you need to have an entry added regardless of whether or not it is a duplicate, either do not set either of these flags or set the CREATE_REPLACE flag. CREATE_REPLACE indicates that you do not care if an entry is a duplication; you always want it to replace the original entry.

See Also

ENTRYLIST, IABContainer::CreateEntry, IMAPIProgress : IUnknown, IMAPIProp::SaveChanges


IABContainer::CreateEntry

The IABContainer::CreateEntry method creates a new entry, which can be a messaging user, a distribution list, or another container.

Quick Info

See IABContainer : IMAPIContainer

HRESULT CreateEntry(

ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulCreateFlags,
LPMAPIPROP FAR * lppMAPIPropEntry
)
Parameters

cbEntryID

[in] Count of the bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of a template for creating new entries of a particular type.

ulCreateFlags

[in] Bitmask of flags that controls how entry creation is performed. The following flags can be set:

CREATE_CHECK_DUP_LOOSE

Suggests that a loose level of duplicate entry checking should be performed. The implementation of loose duplicate entry checking is provider-specific. For example, a provider can define a loose match as any two entries having the same display name.

CREATE_CHECK_DUP_STRICT

Suggests that a strict level of duplicate entry checking should be performed. The implementation of strict duplicate entry checking is provider-specific. For example, a provider can define a strict match as any two entries having both the same display name and messaging address.

CREATE_REPLACE

A new entry should replace an existing one if it is determined that the two are duplicates.

lppMAPIPropEntry

[out] Pointer to a pointer to the newly created entry.

Return Values

S_OK

The new entry was successfully created.

Remarks

The IABContainer::CreateEntry method creates a new entry of a particular type in the container, returning a pointer to an interface implementation for further access to the entry. The new entry is created using a template that has been selected from the container’s list of available templates published in its one -off table. Callers access a container’s one-off table by calling its IMAPIProp::OpenProperty method and requesting the PR_CREATE_TEMPLATES property.

Notes to Implementers

All containers that support the IABContainer::CreateEntry must be modifiable. Set your container’s AB_MODIFIABLE flag in its PR_CONTAINER_FLAGS property to indicate that it is modifiable.

Although the MAPI Personal Address Book does not support the CREATE_REPLACE flag, MAPI recommends that you support all of the ulFlags flags. However, the interpretation and use of these flags is implementation-specific. That is, you can determine what the semantics of CREATE_CHECK_DUP_LOOSE and CREATE_CHECK_DUP_STRICT mean within the context of your implementation. If you cannot or do not determine whether an entry is a duplicate, always allow the entry to be created.

Some providers implement strict entry checking by matching the display name, messaging address, and search key in an entry; other providers limit the match to display name and address. Loose entry checking is often implemented by checking the display name only.

Notes to Host Provider Implementers

If your container can create entries from the templates of other providers, your implementation of CreateEntry should provide storage for some or all of the properties associated with the created entries. For example, if you provide storage for an entry’s PR_DETAILS_TABLE property, you will be able to generate its details dialog box without having to depend on the foreign provider.

If your container can create entries that support the PR_TEMPLATEID property, your implementation of CreateEntry must:

1.	Call IMAPISupport::OpenTemplateID. OpenTemplateID allows the foreign provider’s code for the entry to bind to the new entry being created. Foreign providers support this binding process to maintain control over entries created from their templates into the containers of host providers.

2.	Perform any necessary initialization and populate the new object with all of the properties from the entry in the foreign provider — the object returned in the lppMAPIPropNew parameter from OpenTemplateID.

If OpenTemplateID succeeds, copy the properties to the bound interface — the implementation pointed to by the lppMAPIPropNew parameter — rather than directly to the implementation pointed to by the lpMAPIPropData parameter. Initialize the new entry for offline use as you would any other entry from a foreign provider.

If OpenTemplateID returns an error, CreateEntry should fail. Do not allow the entry to be created. Because the foreign provider can make assumptions about the data in your provider, do not create an entry with a template identifier that has not been successfully bound to the foreign provider.

Notes to Callers

When CreateEntry returns, you may or may not be able to access the entry identifier for the new entry immediately. Some address book providers do not make it accessible until after you have called the new entry’s IMAPIProp::SaveChanges method.

Although duplicate checking flags are passed as parameters to CreateEntry, the duplicate checking operation does not occur until SaveChanges is called. Therefore, related errors such as MAPI_E_COLLISION, indicating that an attempt was made to create an already existing entry, are returned by SaveChanges rather than CreateEntry.

See Also

IABContainer::CopyEntries, IMAPIProp::OpenProperty, IMAPIProp::SaveChanges, PR_CREATE_TEMPLATES


IABContainer::DeleteEntries

The IABContainer::DeleteEntries method removes one or more entries, typically messaging users, distribution lists, or other containers.

Quick Info

See IABContainer : IMAPIContainer

HRESULT DeleteEntries(

LPENTRYLIST lpEntries,
ULONG ulFlags
)
Parameters

lpEntries

[in] Pointer to an array of ENTRYLIST structures containing entry identifiers representing the entries being deleted.

ulFlags

Reserved; must be zero.

Return Values

S_OK

The specified entries have been successfully deleted.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but one or more of the entries could not be deleted. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.


IABContainer::ResolveNames

The IABContainer::ResolveNames method performs name resolution for one or more recipient entries.

Quick Info

See IABContainer : IMAPIContainer

HRESULT ResolveNames(

LPSPropTagArray lpPropTagArray,
ULONG ulFlags,
LPADRLIST lpAdrList,
LPFlagList lpFlagList
)
Parameters

lpPropTagArray

[in] Pointer to an SPropTagArray structure containing an array of property tags describing the properties to be included in the ADRLIST structure returned by the provider. To request the provider’s default set of properties, pass NULL in the lpPropTagArray parameter.

ulFlags

[in] Bitmask of flags that controls the type of the text in returned strings. The following flag can be set:

MAPI_UNICODE

The returned string properties are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lpAdrList

[in, out] On input, pointer to an ADRLIST structure containing the list of recipients to be resolved. On output, pointer to an ADRLIST structure containing the resolved names.

lpFlagList

[in, out] Pointer to an array of flags; each flag corresponding to an ADRENTRY structure in the lpAdrList parameter, that provides the status of the name resolution operation for the recipient. The flags in the lpFlagList parameter are in the same order as the entries in lpAdrList. The following flags can be set:

MAPI_AMBIGUOUS

The corresponding recipient has been resolved, but not to a unique entry identifier. Other containers should not try to resolve this recipient.

MAPI_RESOLVED

The corresponding recipient has been resolved to a unique entry identifier. Other containers should not try to resolve this recipient.

MAPI_UNRESOLVED

The corresponding entry has not been resolved. Other containers should try to resolve this recipient.

Return Values

S_OK

The name resolution process was successful.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

MAPI_E_NO_SUPPORT

The address book provider does not support bulk name resolution using this method.

Remarks

The IABContainer::ResolveNames method attempts to match unresolved recipients from the array of entries in the lpAdrList parameter to recipients in this address book container. An unresolved recipient typically only has the PR_DISPLAY_NAME property and possibly a few other properties. An unresolved recipient does not have the PR_ENTRYID property and its corresponding flag in the lpFlagList parameter is set to MAPI_UNRESOLVED. Conversely, a resolved recipient always has at least the PR_ENTRYID property plus several other properties such as PR_EMAIL_ADDRESS, PR_DISPLAY_NAME, and PR_ADDRTYPE.

The name resolution typically beings when a client calls IAddrBook::ResolveName. MAPI responds by calling the IABContainer::ResolveNames method of each address book container that is included in the address book search path — the PR_AB_SEARCH_PATH property. The entries in the lpAdrList parameter include recipients already resolved by containers that have already been called because they appear earlier in the search path and unresolved recipients.

Each container attempts to resolve the unresolved entries by matching the display name of the recipient with the display name of one of its entries. When a unique match is found, ResolveNames adds the PR_ENTRYID property and other properties included in the lpPropTagArray parameter to the corresponding entry in the outgoing ADRLIST structure and sets the entry in the lpFlagList parameter to MAPI_RESOLVED. The entry identifier stored in the PR_ENTRYID property can be short-term or long-term.

After all of the containers in the search path have attempted the name resolution process, MAPI launches a dialog box, if possible, to prompt the user for help in setting any remaining conflicts.

Clients can also use the returned ADRLIST in calls to the IMessage::ModifyRecipients method.

Notes to Implementers

You are not required to support name resolution with the IABContainer::ResolveNames method. Instead, or in addition, you can support it with the PR_ANR property restriction. If you choose to rely on the PR_ANR restriction for name resolution, you can return MAPI_E_NO_SUPPORT from IABContainer::ResolveNames. For more information, see Implementing the PR_ANR Property Restriction.

Set a recipient’s flag entry in the lpFlagList parameter to MAPI_UNRESOLVED if the recipient does not match any of the container’s recipients.

When a recipient matches multiple recipients, set its flag to MAPI_AMBIGUOUS and do not alter its ADRENTRY structure.

MAPI requires certain properties on recipients that are included in a message’s recipient list. You can include them in the ADRENTRY structure as part of the name resolution process or wait for MAPI to request them during the processing of IAddrBook::PrepareRecips and IMAPISupport::ExpandRecips. Eliminate these extra calls and improve performance by including the following properties in the ADRENTRY structures of all resolved recipients:

PR_ADDRTYPE

PR_DISPLAY_NAME

PR_EMAIL_ADDRESS

PR_ENTRYID

PR_OBJECT_TYPE

PR_SEARCH_KEY

PR_TRANSMITTABLE_DISPLAY_NAME

If some of the properties in the lpPropTagArray parameter are unavailable — typically because the container entry does not support them and they are not included in the recipient’s ADRENTRY member in the ADRLIST structure — set the property type of each unavailable property to PT_ERROR.

Do not remove any properties from a resolved recipient’s ADRENTRY structure.

If you need to replace rather than modify an ADRENTRY structure, free the original ADRENTRY structure first by calling the MAPIFreeBuffer function and then allocate the replacement ADRENTRY structure with MAPIAllocateBuffer.

See Also

ADRENTRY, ADRLIST, IAddrBook::PrepareRecips, IAddrBook::ResolveName, IMAPISupport::ExpandRecips, IMessage::ModifyRecipients, PR_ANR, SPropertyRestriction


IABLogon : IUnknown

The IABLogon interface is used to access resources in an address book provider.

Quick Info

Header file:	MAPISPI.H
Exposed by:	Address book logon objects
Implemented by:	Address book providers
Called by:	MAPI
Corresponding pointer type:	LPABLOGON
Vtable Order

GetLastError	Returns a MAPIERROR structure containing information about the previous address book provider error.
Logoff	Initiates the logoff process.
OpenEntry	Opens a container, messaging user, or distribution list and returns a pointer to an interface implementation to provide further access.
CompareEntryIDs	Compares two entry identifiers to determine if they refer to the same object.
Advise	Registers to receive notification of specified events affecting a container, messaging user, or distribution list.
Unadvise	Cancels the sending of notifications previously set up with a call to the IABLogon::Advise method.
OpenStatusEntry	Opens the provider’s status object.
OpenTemplateID	Opens a recipient entry that has data residing in a host address book provider.
GetOneOffTable	Returns a table of one-off templates for creating recipients to be added to the recipient list of an outgoing message.
PrepareRecips	Prepares a recipient list for later use by the messaging system.
For general information about the methods of IABLogon, see About Service Provider Logon Objects.

For information about implementing the methods of IABLogon, see Implementing the IABLogon Interface.


IABLogon::Advise

The IABLogon::Advise method registers to receive notification of specified events affecting a container, messaging user, or distribution list.

Quick Info

See IABLogon : IUnknown.

HRESULT Advise(

ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the object about which notifications should be generated.

ulEventMask

[in] A mask of values indicating the types of notification events that the caller is interested in and should be included in the registration. There is a corresponding NOTIFICATION structure associated with each type of event that holds information about the event.

The following table lists the valid values for the ulEventMask parameter and the structures associated with each value.

Notification event type	Corresponding NOTIFICATION structure
fnevCriticalError	ERROR_NOTIFICATION
fnevObjectCreated	OBJECT_NOTIFICATION
fnevObjectDeleted	OBJECT_NOTIFICATION
fnevObjectModified	OBJECT_NOTIFICATION
fnevObjectCopied	OBJECT_NOTIFICATION
fnevObjectMoved	OBJECT_NOTIFICATION
lpAdviseSink

[in] Pointer to an advise sink object to receive the subsequent notifications.

lpulConnection

[out] Pointer to a nonzero value that represents the notification registration.

Return Values

S_OK

The notification registration was successful.

MAPI_E_INVALID_ENTRYID

The entry identifier passed in lpEntryID is not in the appropriate format.

MAPI_E_NO_SUPPORT

The address book provider does not support notification, possibly because it does not allow changes to be made to its objects.

MAPI_E_UNKNOWN_ENTRYID

The address book provider cannot handle the entry identifier passed in lpEntryID.

Remarks

Address book providers implement the IABLogon::Advise method to register the caller to be notified when a change occurs to an object in one of their containers. Callers can register for notifications on messaging users, distribution lists, or entire containers.

Clients typically call IAddrBook::Advise to register for address book notifications. MAPI then calls the IABLogon::Advise method of the address book provider that is responsible for the object represented by the entry identifier in lpEntryID.

When a change occurs to the indicated object of the type represented in ulEventMask, a call is made to the OnNotify method of the advise sink pointed to by lpAdviseSink. Data passed in the notification structure to the OnNotify routine describes the event.

Notes to Implementers

You can support notification with or without help from MAPI. MAPI has three support object methods for helping service providers implement notification: IMAPISupport::Subscribe, IMAPISupport::Unsubscribe, and IMAPISupport::Notify. If you elect to use the MAPI support methods, call Subscribe when your Advise method is called and release the lpAdviseSink pointer.

If you elect to support notification yourself, call the IUnknown::AddRef method of the advise sink represented by the lpAdviseSink parameter to keep a copy of this pointer. Maintain this copy until your IABLogon::Unadvise method is called to cancel the registration.

Regardless of how you support notification, assign a nonzero connection number to the notification registration and return it in the lpulConnection parameter. Do not release this connection number until Unadvise has been called.

Notes to Callers

The advise sink pointer that you pass in the lpAdviseSink parameter to Advise can point to an object that you have created or that MAPI has created through the HrThisThreadAdviseSink function. You might want to use HrThisThreadAdviseSink if you support multiple threads of execution and want to ensure that subsequent calls to your OnNotify method occur at an appropriate time on an appropriate thread.

Be prepared for your advise sink object to be released any time after your call to Advise and before your call to Unadvise. MAPI recommends that you release your advise sink object after Advise returns, unless you have a specific long-term use for it.

For more information on the notification process, see Event Notification in MAPI. For information about using the IMAPISupport methods to support notification, see Using A Support Object for Event Notification. For more information about multithreading and MAPI, see Threading in MAPI.

See Also

HrThisThreadAdviseSink, IABLogon::Unadvise, IMAPIAdviseSink::OnNotify, NOTIFICATION


IABLogon::CompareEntryIDs

The IABLogon::CompareEntryIDs method compares two entry identifiers to determine if they refer to the same object.

Quick Info

See IABLogon : IUnknown.

HRESULT CompareEntryIDs(

ULONG cbEntryID1,
LPENTRYID lpEntryID1,
ULONG cbEntryID2,
LPENTRYID lpEntryID2,
ULONG ulFlags,
ULONG FAR * lpulResult
)
Parameters

cbEntryID1

[in] Count of bytes in the entry identifier pointed to by the lpEntryID1 parameter.

lpEntryID1

[in] Pointer to the first entry identifier to be compared.

cbEntryID2

[in] Count of bytes in the entry identifier pointed to by the lpEntryID2 parameter.

lpEntryID2

[in] Pointer to the second entry identifier to be compared.

ulFlags

Reserved; must be zero.

lpulResult

[out] Pointer to the returned result of the comparison. The contents of lpulResult is TRUE if the two entry identifiers refer to the same object, and FALSE otherwise.

Return Values

S_OK

The entry identifiers were successfully compared.

MAPI_E_INVALID_ENTRYID

One or both of the entry identifiers do not belong to the address book provider.

Remarks

Address book providers implement the IABLogon::CompareEntryIDs method to compare two entry identifiers to determine whether they refer to the same object.

CompareEntryIDs is useful because an object can have more than one valid entry identifier; such a situation can occur, for example, when trying to compare a short-term entry identifier with a long-term entry identifier.

For more information about creating entry identifiers, see Entry Identifiers.


IABLogon::GetLastError

The IABLogon::GetLastError method returns a MAPIERROR structure containing information about the previous address book provider error.

Quick Info

See IABLogon : IUnknown.

HRESULT GetLastError(

HRESULT hResult,
ULONG ulFlags,
LPMAPIERROR FAR * lppMAPIError
)
Parameters

hResult

[in] HRESULT data type containing the error value generated in the previous method call.

ulFlags

[in] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] Pointer to a pointer to a MAPIERROR structure containing version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if the provider cannot supply a MAPIERROR structure with appropriate information.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the address book provider does not support Unicode, or MAPI_UNICODE was not set and the address book provider only supports Unicode.

Remarks

Address book providers implement the IABLogon::GetLastError method to supply information about a prior method call that failed. Callers can provide their users with detailed information about the error by including the data from the MAPIERROR structure in a dialog box.

Notes to Callers

You can make use of the MAPIERROR structure pointed to by the lppMAPIError parameter — if the address book provider supplies one — only if GetLastError returns S_OK. Sometimes the address book provider cannot determine what the last error was or has nothing more to report about the error. In this situation, the address book provider returns a pointer to NULL in lppMAPIError instead.

For more information about the GetLastError method, see Using Extended Errors.

See Also

MAPIERROR, MAPIFreeBuffer


IABLogon::GetOneOffTable

The IABLogon::GetOneOffTable method returns a table of one-off templates for creating recipients to be added to the recipient list of an outgoing message.

Quick Info

See IABLogon : IUnknown.

HRESULT GetOneOffTable(

ULONG ulFlags,
LPMAPITABLE FAR * lppTable
)
Parameters

ulFlags

[in] Bitmask of flags that controls the type of string columns included in the table. The following flag can be set:

MAPI_UNICODE

The string columns are in Unicode format. If the MAPI_UNICODE flag is not set, the string columns are in ANSI format.

lppTable

[out] Pointer to a pointer to the one-off table.

Return Values

S_OK

The one-off table was successfully retrieved.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the address book provider does not support Unicode, or MAPI_UNICODE was not set and the address book provider only supports Unicode.

MAPI_E_NO_SUPPORT

The address book provider does not supply any one-off templates.

Remarks

MAPI calls the IABLogon::GetOneOffTable method to make available one-off templates for creating recipients. The new recipients are added to the recipient list of an outgoing message. Address book providers should support notification on their one-off table to inform MAPI of template modifications. MAPI keeps the one-off table open to enable dynamic updating.

Address book providers can also support a one-off table for each of their containers. Callers retrieve this one-off table by calling the container’s IMAPIProp::OpenProperty method and requesting the PR_CREATE_TEMPLATES property. The templates available through this table are used to add recipients to the container. For a discussion of the differences between the two types of one-off tables, see Implementing One-Off Tables.

For a list of the required columns in an address book provider’s one-off table, see One-Off Tables.

See Also

IABContainer::CreateEntry, IAddrBook::NewEntry, IMAPISupport::GetOneOffTable


IABLogon::Logoff

The IABLogon::Logoff method initiates the logoff process.

Quick Info

See IABLogon : IUnknown.

HRESULT Logoff(

ULONG ulFlags
)
Parameters

ulFlags

Reserved; must be zero.

Return Value

S_OK

The logoff process was successfully initiated.

Remarks

The logoff process is typically started when a client calls IMAPISession::Logoff to end a session. MAPI then calls each address book provider’s IABLogon::Logoff method to start the logoff process.

IABLogon::Logoff:

•	Releases all open objects, such as any subobjects or the status object.

•	Releases the provider’s support object.

For more information about the logoff process of address book providers, see Shutting Down Service Providers.

See Also

IABProvider::Logon


IABLogon::OpenEntry

The IABLogon::OpenEntry method opens a container, messaging user, or distribution list and returns a pointer to an interface implementation to provide further access.

Quick Info

See IABLogon : IUnknown.

HRESULT OpenEntry(

ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
ULONG ulFlags,
ULONG FAR * lpulObjType,
LPUNKNOWN FAR * lppUnk
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the container, messaging user, or distribution list to open.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the open object. Passing NULL results in the identifier for the object’s standard interface being returned. For containers, the standard interface is IABContainer. The standard interfaces for address book objects are IDistList for a distribution list and IMailUser for a messaging user.

ulFlags

[in] Bitmask of flags that controls how the object is opened. The following flags can be set:

MAPI_BEST_ACCESS

Requests that the object be opened with the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write access, the object should be opened with read/write access; if the client has read-only access, the object should be opened with read-only access.

MAPI_DEFERRED_ERRORS

Allows OpenEntry to return successfully, possibly before the object is fully accessible to the calling client. If the object is not accessible, making a subsequent object call can result in an error.

MAPI_MODIFY

Requests read/write access. By default, objects are opened with read-only access, and clients should not work on the assumption that read/write access has been granted.

lpulObjType

[out] Pointer to the type of the opened object.

lppUnk

[out] Pointer to a pointer to the opened object.

Return Values

S_OK

The object was successfully opened.

MAPI_E_NO_ACCESS

Either the user has insufficient permissions to open the object or an attempt was made to open a read-only object with read/write access.

MAPI_E_NOT_FOUND

The entry identifier specified by lpEntryID does not represent an object.

MAPI_E_UNKNOWN_ENTRYID

The entry identifier in the lpEntryID parameter is not of a format recognized by the address book provider.

Remarks

MAPI calls the IABLogon::OpenEntry method to open a container, messaging user, or distribution list.

Notes to Implementers

Before MAPI calls your IABLogon::OpenEntry method, it determines that the entry identifier in the lpEntryID parameter belongs to you and not to another provider. MAPI does this by matching the MAPIUID structure in the entry identifier with the MAPIUID that you registered by calling IMAPISupport::SetProviderUID at start up.

Open the object as read-only, unless the MAPI_MODIFY or MAPI_BEST_ACCESS flag is set in the ulFlags parameter. If you do not allow modification for the object requested, do not open the object at all and return MAPI_E_NO_ACCESS.

If MAPI passes NULL for lpEntryID, open the root container in your container hierarchy.

The object that you are being asked to open might be an object copied from another provider. In this case, it will support the PR_TEMPLATEID property. If the object does support this property, call IMAPISupport::OpenTemplateID to bind to code for this entry in the foreign provider. Pass PR_TEMPLATEID in the lpTemplateID parameter and zero in the ulTemplateFlags parameter. IMAPISupport::OpenTemplateID passes this information to the foreign provider in a call to the foreign provider’s IABLogon::OpenTemplateID method. If IMAPISupport::OpenTemplateID returns an error, usually because the foreign provider is unavailable or not included in the profile, try to continue by treating the unbound entry as read-only. For more information about opening foreign address book entries, see Implementing a Host Address Book Provider.


IABLogon::OpenStatusEntry

The IABLogon::OpenStatusEntry method opens the provider’s status object.

Quick Info

See IABLogon : IUnknown.

HRESULT OpenStatusEntry(

LPCIID lpInterface,
ULONG ulFlags,
ULONG FAR * lpulObjType,
LPMAPISTATUS FAR * lppMAPIStatus
)
Parameters

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the status object. Passing NULL results in the object’s standard interface being returned, which is IMAPIStatus.

ulFlags

[in] Bitmask of flags that controls how the status object is opened. The following flag can be set:

MAPI_MODIFY

Requests read/write access. By default, objects are opened with read-only access, and callers should not work on the assumption that read/write access has been granted.

lpulObjType

[out] Pointer to the type of the opened object.

lppEntry

[out] Pointer to a pointer to the opened object.

Return Value

S_OK

The call succeeded and the status object has been opened.

Remarks

Address book providers implement the IABLogon::OpenStatusEntry method to grant access to their status object. All address book providers are required to implement a status object that supports at a minimum the IMAPIStatus::ValidateState method. For more information, see Implementing a Status Object.

See Also

IMAPIStatus : IMAPIProp, IMAPIStatus::SettingsDialog, IMAPIStatus::ValidateState


IABLogon::OpenTemplateID

The IABLogon::OpenTemplateID method opens a recipient entry that has data residing in a host address book provider.

Quick Info

See IABLogon : IUnknown.

HRESULT OpenTemplateID(

ULONG cbTemplateID,
LPENTRYID lpTemplateID,
ULONG ulTemplateFlags,
LPMAPIPROP lpMAPIPropData,
LPCIID lpInterface,
LPMAPIPROP FAR * lppMAPIPropNew,
LPMAPIPROP lpMAPIPropSibling
)
Parameters

cbTemplateID

[in] Count of bytes in the template identifier pointed to by the lpTemplateID parameter.

lpTemplateID

[in] Pointer to the template identifier, or PR_TEMPLATEID property, of the recipient entry to be opened.

ulTemplateFlags

[in] Bitmask of flags used to indicate how to open the entry represented by the template identifier. The following flag can be set:

FILL_ENTRY

The host provider is creating a new entry in its container based on the entry represented by the template identifier. OpenTemplateID should either perform specific initialization of the host provider’s entry, using the IMAPIProp implementation in the lpMAPIPropData parameter, or return a custom IMAPIProp implementation in the lppMAPIPropNew parameter.

lpMAPIPropData

[in] Pointer to the host provider’s property object— an implementation of an interface derived from IMAPIProp.

lpInterface

[in] Pointer to the interface identifier (IID) representing the type of interface pointer to be returned in the lppMAPIPropNew parameter. Passing NULL results in the return of the standard messaging user interface, IMailUser.

lppMAPIPropNew

[out] Pointer to the bound property object —an implementation of an interface derived from IMAPIProp.

lpMAPIPropSibling

Reserved; must be NULL.

Return Values

S_OK

The appropriate code was successfully bound to related data in the host provider.

MAPI_E_UNKNOWN_ENTRYID

The template identifier passed in the lpTemplateID parameter is not recognized by the address book provider.

Remarks

The IABLogon::OpenTemplateID method is implemented only by address book providers that need to maintain control over copies of its entries that exist in the containers of host providers. Providers that implement OpenTemplateID are known as foreign address book providers. Host providers call IMAPISupport::OpenTemplateID to create a copied entry or open the copied entry and MAPI passes on the call to IABLogon::OpenTemplateID. IABLogon::OpenTemplateID opens the entry and binds the code that controls it to data in the host provider.

Rather than use an entry identifier, OpenTemplateID uses another property, the entry’s template identifier — PR_TEMPLATEID. Template identifiers should be supported for entries whose code will need to be bound to data in a host provider.

Some examples of when an address book provider should implement IABLogon::OpenTemplateID are as follows:

•	To periodically update the data for a copied entry so that it stays synchronized with the original.

•	To implement functionality that the host provider cannot implement, such as dynamically populating a list box that appears in the entry’s details table from data on a server.

•	To control the interaction between properties in the host provider’s entry and the original entry, such as computing PR_EMAIL_ADDRESS from edit controls in the details display that hold various components of the address.

Notes to Implementers

When a host provider copies or creates an entry from your provider and you supply a property object implementation through IABLogon::OpenTemplateID, you handle most of the calls to maintain the entry. However, because it is up to the host provider to forward these calls to you, the host provider can intercept any call and perform custom processing before forwarding the call.

Following are some guidelines that you should adhere to in your property object implementations:

•	When IMAPIProp::GetProps is called, determine if the request is for a computed property and if it is, handle it. Transfer all requests for non-computed properties to the host provider.

•	When IMAPIProp::OpenProperty is called to open any table except the details display table, handle the request. Most tables cannot be copied accurately to the host provider. You must generate the IMAPITable implementation for these requested tables. The details table, or PR_DETAILS_TABLE property, must be copied to the host provider, thereby allowing this provider to generate the table locally. You might want to wrap the display table implementation to generate display table notifications.

•	When IMAPIProp::SetProps is called, the host provider can validate the data before allowing you to set the properties. You can verify that all of the necessary properties were set or computed. If an error is detected, return the appropriate error value and, if possible, a further explanation through IMAPIProp::GetLastError.

•	When IMAPIProp::SaveChanges is called, the host provider might want to perform processing before you save the entry. You should save any data that is affected by the changed properties, such as a new address, in the host provider’s entry.

In general, make your implementation of the entry that you pass back to the host provider intercept all of the methods to perform context-specific manipulation of the relevant properties. If the FILL_ENTRY flag is passed in the ulFlags parameter, set all properties for the entry.

If you return a new property object in the lppMAPIPropNew parameter, call the IUnknown::AddRef method of the host provider’s property object to maintain a reference. All calls through the bound object — the IMAPIProp implementation returned in lppMAPIPropNew — should be routed to their corresponding method in the host property object after they are dealt with by the bound object.

The property identifiers of any named properties that are passed through your bound property object are in your provider’s identifier name space. Your implementation of GetNamesFromIDs method should determine the names of the properties so that it can perform any template-specific tasks. Similarly, properties that your provider passes on to the host provider must also be in your name space. For example, if you set a named property in OpenTemplateID, you should use one of your identifiers for the name, creating it if necessary by calling GetIDsFromNames.

If you do not recognize the entry identifier passed in lpTemplateID, return MAPI_E_UNKNOWN_ENTRYID.

For more information on working with address book template identifiers, see Implementing a Foreign Address Book Provider.

See Also

IMAPISupport::OpenTemplateID, IPropData : IMAPIProp, PR_TEMPLATEID


IABLogon::PrepareRecips

The IABLogon::PrepareRecips method prepares a recipient list for later use by the messaging system.

Quick Info

See IABLogon : IUnknown.

HRESULT PrepareRecips(

ULONG ulFlags,
LPSPropTagArray lpPropTagArray,
LPADRLIST lpRecipList
)
Parameters

ulFlags

Reserved; must be zero.

lpPropTagArray

[in] Pointer to an SPropTagArray structure containing an array of property tags indicating the properties that require updating, if any. The lpPropTagArray parameter can be NULL.

lpRecipList

[in] Pointer to an ADRLIST structure holding the recipient list.

Return Values

S_OK

The recipient list was successfully prepared.

MAPI_E_NOT_FOUND

One or more of the recipients in the lpRecipList parameter does not exist.

Remarks

MAPI calls the IABLogon::PrepareRecips method to:

•	Ensure that each recipient in the address list pointed to by lpRecipList has a long-term entry identifier.

•	Ensure that all of the properties in the lpPropTagArray parameter exist in the property value array included in each recipient’s ADRENTRY structure in the ADRLIST.

The ADRLIST structure in the lpRecipList parameter contains one ADRENTRY structure for each recipient. Each ADRENTRY structure contains an array of SPropValue structures to describe the recipient’s properties. When PrepareRecips returns, the SPropValue structure array for each recipient includes the properties from the lpPropTagArray followed by the other properties for the recipient.

Notes to Implementers

Implementing PrepareRecips involves placing properties in a specific order, retrieving property values, and converting short-term entry identifiers to long-term entry identifiers. The properties that are included in the lpPropTagArray parameter should appear at the beginning of the property value array associated with each recipient’s ADRENTRY structure in the lpRecipList parameter. If values for these properties do not exist, open the associated messaging user or distribution list by using its entry identifier and retrieve the missing property values.

If you do not recognize one or more of the properties in the lpPropTagArray parameter, set the property type in the recipient’s ADRENTRY structure to PT_ERROR and the property value either to MAPI_E_NOT_FOUND or to another value giving a more specific reason for the unavailability. For information about PT_ERROR, see List of Property Types.

Allocate each SPropValue structure passed in lpPropTagArray separately so that the structures can be freed individually. If you must allocate additional space for any SPropValue structure — for example, to store the data for a string property — use MAPIAllocateBuffer to allocate additional space for the full property tag array. Use the MAPIFreeBuffer function to free the original property tag array and then use MAPIAllocateMore to allocate any additional memory required.

See Also

ADRLIST, IMAPIProp::GetProps, PR_ENTRYID, SPropValue


IABLogon::Unadvise

The IABLogon::Unadvise method cancels the sending of notifications previously set up with a call to the IABLogon::Advise method.

Quick Info

See IABLogon : IUnknown.

HRESULT Unadvise(

ULONG ulConnection
)
Parameters

ulConnection

[in] Connection number associated with an active notification registration. The value of ulConnection must have been returned by a previous call to IABLogon::Advise.

Return Value

S_OK

The notification registration was successfully canceled.

Remarks

MAPI calls the IABLogon::Unadvise method to cancel a notification registration for a container, messaging user, or distribution list object.

Notes to Implementers

Your implementation of Unadvise will depend on whether you support notification with MAPI’s help or manually. If MAPI provides your support, call IMAPISupport::Unsubscribe to cancel the registration. If you support notifications manually, call the IUnknown::Release method of the advise sink object passed in the lpAdviseSink parameter in Advise. Calling Release decrements the advise sink’s reference count, allowing it to be freed when the count reaches zero. The call to Release can occur during the Unadvise method or, if another thread is in the process of calling the advise sink’s IMAPIAdviseSink::OnNotify method, it can be delayed until OnNotify has returned.

For more information on the notification process, see Event Notification in MAPI. For information about using the IMAPISupport methods to support notification, see Using A Support Object for Event Notification.

See Also

IABLogon::Advise, IMAPIAdviseSink::OnNotify


IABProvider : IUnknown

The IABProvider interface provides a method to log on to an address book provider object and a method to invalidate an address book provider object.

Quick Info

Header file:	MAPISPI.H
Exposed by:	Address book provider objects
Implemented by:	Address book providers
Called by:	MAPI
Corresponding pointer type:	LPABPROVIDER
Vtable Order

Shutdown	Cancels a connection to an active session.
Logon	Establishes a connection to an active session.


IABProvider::Logon

The IABProvider::Logon method establishes a connection to an active session.

Quick Info

See IABProvider : IUnknown.

HRESULT Logon(

LPMAPISUP lpMAPISup,
ULONG ulUIParam,
LPTSTR lpszProfileName,
ULONG ulFlags,
ULONG FAR * lpulcbSecurity,
LPBYTE FAR * lppbSecurity,
LPMAPIERROR FAR * lppMAPIError,
LPABLOGON FAR * lppABLogon
)
Parameters

lpMAPISup

[in] Pointer to the address book provider’s support object.

ulUIParam

[in] Handle of the parent window for the logon dialog box that Logon displays if permitted. The ulUIParam parameter contains the value of the parameter of the same name passed to MAPI in the preceding call to the MAPILogonEx function.

lpszProfileName

[in] Pointer to the name of the session profile.

ulFlags

[in] Bitmask of flags that controls how the logon is performed. The following flags can be set:

AB_NO_DIALOG

The provider should not display a dialog box during logon. If this flag is not set, the provider can display a dialog box to prompt the user for missing configuration information.

MAPI_DEFERRED_ERRORS

Allows Logon to return successfully, possibly before the logon process is complete.

MAPI_UNICODE

All strings should be in Unicode format. If the MAPI_UNICODE flag is not set, the strings should be in ANSI format.

lpulcbSecurity

[in, out] Pointer to the size, in bytes, of the security credentials structure pointed to by the lppbSecurity parameter. On input, the value must be nonzero; on output, the value must be zero. In both cases the pointers must be valid.

lppbSecurity

[in, out] Pointer to a pointer to security credentials. On input, the value must be nonzero; on output, the value must be zero. In both cases the pointer must be valid.

lppMAPIError

[out] Pointer to a pointer to a MAPIERROR structure. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

lppABLogon

[out] Pointer to a pointer to the provider’s logon object.

Return Values

S_OK

A connection to an active session was successfully established.

MAPI_E_FAILONEPROVIDER

The provider cannot log on, but MAPI can continue to log on the other providers in the message service to which the provider belongs.

MAPI_E_UNCONFIGURED

The provider does not have enough information to complete the logon. MAPI calls the provider’s message service entry function.

MAPI_E_UNKNOWN_CPID

The server is not configured to support the client's code page.

MAPI_E_UNKNOWN_LCID

The server is not configured to support the client's locale information.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in the logon dialog box.

Remarks

Connections are established with each of the address book providers in the session profile when a client calls the IMAPISession::OpenAddressBook method. OpenAddressBook then calls each provider’s IABProvider::Logon method.

The profile name pointed to by the lpszProfileName parameter is displayed in the character set of the user’s client as indicated by the presence or absence of the MAPI_UNICODE flag in the ulFlags parameter.

Notes to Implementers

In your implementation of IABProvider::Logon, call IMAPISupport::SetProviderUID to register a unique identifier, or MAPIUID. Each of your objects will have entry identifier that includes this MAPIUID. MAPI uses the MAPIUID to match an object with its provider. For example, when a client calls IMAPISession::OpenEntry to open a messaging user, OpenEntry examines the MAPIUID portion of the entry identifier passed in and matches it with a MAPIUID registered by an address book provider.

If a client logs on to your provider more than once, you may choose to register a different MAPIUID for each logon. Registering unique MAPIUIDs enables MAPI to correctly route requests to the appropriate provider instance. However, you may choose to have every logon object share one MAPIUID. In this case, you must be able to handle the routing yourself rather than relying on MAPI. For more information on creating one or more MAPIUIDs, see Registering Service Provider Unique Identifiers.

The support object that MAPI passes to your IABProvider::Logon method in the lpMAPISup parameter provides access to many of the methods included in the IMAPISupport interface. MAPI creates a support object specially tailored to your type of provider. For example, if you need to log on to an underlying messaging system or directory service when you establish your connection, you can call IMAPISupport::OpenProfileSection to retrieve security credentials for this particular logon session.

If IABProvider::Logon is successful, be sure to call the support object’s IUnknown::AddRef method to increment its reference count. This allows your provider to hold onto the support object pointer for the remainder of the session. If you do not call this AddRef method, MAPI will unload your provider.

You can include the profile name passed in the lpszProfileName parameter in error dialog boxes, logon screens, or other user interfaces. To use the profile name, copy it to storage that you have allocated.

Create a logon object and return a pointer to it in the lppABLogon parameter. MAPI uses this logon object to make calls to the methods in your IABLogon implementation.

If you require a password during logon, display a logon dialog box only if the AB_NO_DIALOG flag is not set. If the user cancels the logon process, typically by clicking the Cancel button in the dialog box, return MAPI_E_USER_CANCEL from Logon.

Typically when an address book provider cannot log on, MAPI disables the message service to which the failing provider belongs. That is, MAPI will not try to establish connections for any of the other providers belonging to the service for the rest of the session’s lifetime. However, if your provider fails to establish a connection and you wish not to disable the entire service, return either MAPI_E_FAILONEPROVIDER or MAPI_E_UNCONFIGURED. MAPI will not disable the message service to which the provider belongs.

Return MAPI_E_FAILONEPROVIDER if an error occurs that is not serious enough to prevent the other providers in the message service from establishing connections. Return MAPI_E_UNCONFIGURED if necessary configuration information is missing from the profile and you cannot display a dialog box to prompt the user. MAPI will respond by calling your provider’s message service entry point function with MSG_SERVICE_CONFIGURE set as the ulContext parameter, to give the service a chance to configure itself, either programmatically or using a property sheet. When the message service entry point function has finished, MAPI retries the logon.

See Also

IABLogon::Logoff, IABLogon::OpenEntry, IMAPISupport::OpenProfileSection, IMAPISupport::SetProviderUID, MSGSERVICEENTRY


IABProvider::Shutdown

The IABProvider::Shutdown method cancels a connection to an active session.

Quick Info

See IABLogon : IUnknown.

HRESULT Shutdown (

ULONG FAR * lpulFlags
)
Parameters

lpulFlags

Reserved; must be a pointer to zero.

Return Value

S_OK

The connection was successfully canceled.

Notes to Implementers

In your implementation of IABLogon::Shutdown, perform whatever tasks you deem necessary. MAPI calls your IABLogon::Shutdown method only after you have released all of your logon objects.


IAddrBook : IMAPIProp

The IAddrBook interface supports access to the MAPI address book and includes operations such as displaying common dialog boxes, opening containers, messaging users, and distribution lists, and performing name resolution.

Quick Info

Header file:	MAPIX.H
Exposed by:	Address book objects
Implemented by:	MAPI
Called by:	Client applications, service providers
Corresponding pointer type:	LPADRBOOK
Vtable Order

Note  The implementation of IMAPIProp::GetLastError for IAddrBook supports Unicode on Windows NT platforms only. The implementations of GetLastError for Windows 95 platforms and 16-bit platforms do not support Unicode.

OpenEntry	Opens an address book entry and returns a pointer to an interface that can be used to to the entry.
CompareEntryIDs	Compares two entry identifiers belonging to a particular address book provider to determine if they refer to the same address book object.
Advise	Registers a client or service provider to receive notifications about changes to one or more entries in the address book.
Unadvise	Cancels a notification registration previously established for an address book entry.
CreateOneOff	Creates an entry identifier for a one-off address.
NewEntry	Adds a new recipient directly to an address book container or to the recipient list of an outgoing message.
ResolveName	Performs name resolution, assigning entry identifiers to recipients in a recipient list.
Address	Displays the common address dialog box.
Details	Displays a modal dialog box showing details about a particular address book entry.
RecipOptions	Displays a dialog box showing the recipient option properties.
QueryDefaultRecipOpt	Returns the recipient options that have been set for a particular address type by the transport provider.
GetPAB	Returns the entry identifier of the container designated as the Personal Address Book (PAB).
SetPAB	Designates a particular container to be the Personal Address Book (PAB).
GetDefaultDir	Returns the entry identifier for the address book container that is initially made available.
SetDefaultDir	Establishes a container as the default address book container — the container that is initially made available.
GetSearchPath	Returns an ordered list of entry identifiers of containers to be included in the name resolution process initiated by the IAddrBook::ResolveName method.
SetSearchPath	Sets a new search path in the profile that is used for the name resolution process.
PrepareRecips	Prepares a recipient list for later use by the messaging system.


IAddrBook::Address

The IAddrBook::Address method displays the common address dialog box.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT Address(

ULONG FAR * lpulUIParam,
LPADRPARM lpAdrParms,
LPADRLIST FAR * lppAdrList
)
Parameters

lpulUIParam

[in, out] Handle of the parent window of the dialog box. On input, a window handle must always be passed. On output, if the ulFlags member of the lpAdrParms parameter is set to DIALOG_SDI, then the window handle of the modeless dialog box is returned.

lpAdrParms

[in, out] Pointer to an ADRPARM structure that controls the presentation and behavior of the address dialog box.

lppAdrList

[in, out] Pointer to a pointer to an ADRLIST structure containing recipient information. On input, this parameter can be NULL or point to a valid pointer. On output, this parameter points to a pointer to valid recipient information.

Return Values

S_OK

The common address dialog box was successfully displayed.

Remarks

The ADRLIST structure passed back by MAPI to the caller via the lppAdrList parameter contains an array of ADRENTRY structures, one structure for each recipient. When passed to an outgoing message’s IMessage::ModifyRecipients method in the lpMods parameter, the ADRLIST structure can be used to update its recipient list.

Each ADRENTRY structure in the ADRLIST structure contains zero or more SPropValue structures, one structure for every property set for the recipient. There can be zero SPropValue structures when the dialog box presented by IAddrBook::Address is used to remove a recipient. When there are one or more SPropValue structures, the corresponding ADRENTRY structure is used to add or update a recipient. The recipient can either be resolved, indicating that one of the SPropValue structures describes the recipient’s PR_ENTRYID property, or unresolved, indicating that the PR_ENTRYID property is missing.

In addition to PR_ENTRYID, resolved recipients include the following properties:

PR_RECIPIENT_TYPE

PR_DISPLAY_NAME

PR_ADDRTYPE

PR_DISPLAY_TYPE

The ADRLIST structure that the caller passes in might be a different size from the structure that MAPI returns. If MAPI must return a larger ADRLIST structure, it frees the original structure and allocates a new one. When allocating memory for the ADRLIST structure, allocate the memory for each SPropValue structure separately. For more information about how to allocate and free ADRLIST structures, see Managing Memory for ADRLIST and SRowSet Structures

Address returns immediately if the DIALOG_SDI flag is set in the ulFlags member of the ADRPARM structure in the lpAdrParms parameter.

Address supports Unicode character strings in the ADRPARM and ADRLIST parameters for Windows NT platforms only. The Unicode strings are converted to the multi-byte character string (MBCS) format before they are displayed in the common dialog box.

See Also

ADRENTRY, ADRLIST, ADRPARM, FreePadrlist, FreeProws, IMAPITable::QueryRows, IMessage::ModifyRecipients, MAPIAllocateBuffer, MAPIAllocateMore, MAPIFreeBuffer, SPropValue, SRowSet


IAddrBook::Advise

The IAddrBook::Advise method registers a client or service provider to receive notifications about changes to one or more entries in the address book.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT Advise(

ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the address book container, messaging user, or distribution list that will generate a notification when a change occurs of the type or types described in the ulEventMask parameter.

ulEventMask

[in] One or more notification events that the caller is registering to receive. Each event is associated with a particular notification structure containing information about the change that occurred. The following table lists the valid values for ulEventMask and their corresponding structures.

Notification event	Corresponding structure
fnevCriticalError	ERROR_NOTIFICATION
fnevObjectCreated	OBJECT_NOTIFICATION
fnevObjectDeleted	OBJECT_NOTIFICATION
fnevObjectModified	OBJECT_NOTIFICATION
fnevObjectCopied	OBJECT_NOTIFICATION
fnevObjectMoved	OBJECT_NOTIFICATION
fnevTableModified	TABLE_NOTIFICATION
lpAdviseSink

[in] Pointer to the advise sink object to be called when the event for which notification has been requested occurs.

lpulConnection

[out] Pointer to a nonzero connection number that represents the notification registration.

Return Values

S_OK

The notification registration was successful.

MAPI_E_INVALID_ENTRYID

The address book provider responsible for the entry identifier passed in lpEntryID could not register a notification for the corresponding entry.

MAPI_E_NO_SUPPORT

Notification is not supported by the address book provider responsible for the object identified by the entry identifier passed in the lpEntryID parameter.

MAPI_E_UNKNOWN_ENTRYID

The entry identifier passed in lpEntryID cannot be handled by any of the address book providers in the profile.

Remarks

Clients and service providers call the IAddrBook::Advise method to register for a particular type or types of notification on an address book entry. The types of notification are indicated by the event mask passed in with the lpEventMask parameter.

MAPI forwards this Advise call to the address book provider responsible for the entry as indicated by the entry identifier in the lpEntryID parameter. The address book provider either handles the registration itself or calls the support method, IMAPISupport::Subscribe, to prompt MAPI to register the caller. A nonzero connection number is returned to represent the successful registration.

Whenever a change occurs to the entry of the type indicated by the notification registration, the address book provider calls the IMAPIAdviseSink::OnNotify method for the advise sink object specified in the lpAdviseSink parameter. The OnNotify method includes a NOTIFICATION structure as an input parameter that contains data to describe the event.

Depending on the address book provider, the call to OnNotify can occur immediately following the change to the registered object or at some later time. On systems that support multiple threads of execution, the call to OnNotify can occur on any thread. Clients can request that these notifications occur on a particular thread by calling the HrThisThreadAdviseSink function to create the advise sink object that is passed to Advise.

Because an address book provider can release the advise sink object passed in by clients at any time after the successful completion of the Advise call and before an Unadvise call to cancel the notification, clients should release their advise sink objects when Advise returns.

For more information on the notification process, see Event Notification in MAPI.

See Also

HrThisThreadAdviseSink, IAddrBook::Unadvise, IMAPIAdviseSink::OnNotify, NOTIFICATION


IAddrBook::CompareEntryIDs

The IAddrBook::CompareEntryIDs method compares two entry identifiers belonging to a particular address book provider to determine if they refer to the same address book object.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT CompareEntryIDs(

ULONG cbEntryID1,
LPENTRYID lpEntryID1,
ULONG cbEntryID2,
LPENTRYID lpEntryID2,
ULONG ulFlags,
ULONG FAR * lpulResult
)
Parameters

cbEntryID1

[in] Count of bytes in the entry identifier pointed to by the lpEntryID1 parameter.

lpEntryID1

[in] Pointer to the first entry identifier to be compared.

cbEntryID2

[in] Count of bytes in the entry identifier pointed to by the lpEntryID2 parameter.

lpEntryID2

[in] Pointer to the second entry identifier to be compared.

ulFlags

Reserved; must be zero.

lpulResult

[out] Pointer to the result of the comparison. The contents of lpulResult is set to TRUE if the two entry identifiers refer to the same object, and FALSE otherwise.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_UNKNOWN_ENTRYID

One or both of the entry identifiers passed in with the lpEntryID1 or lpEntryID2 parameters are not recognized by any address book provider.

Remarks

Client applications and service providers call the IAddrBook::CompareEntryIDs method to compare two entry identifiers belonging to a single address book provider to determine if they refer to the same object. CompareEntryIDs is useful because an object can have more than one valid entry identifier; such a situation can occur, for example, after a new version of an address book provider is installed.

MAPI passes this call on to the address book provider responsible for the entry identifiers, determining the appropriate provider by matching the MAPIUID structure in the entry identifiers with the MAPIUID structure registered by the provider.

If the two entry identifiers refer to the same object, then CompareEntryIDs sets the contents of the lpulResult parameter to TRUE; if they refer to different objects, CompareEntryIDs sets it to FALSE. In either case, CompareEntryIDs returns S_OK. If CompareEntryIDs returns an error, which can occur if no address book provider has registered a MAPIUID structure that matches the one in the entry identifiers, clients and providers should not take any action based on the result of the comparison. They should instead take the most conservative approach to the action being performed.


IAddrBook::CreateOneOff

The IAddrBook::CreateOneOff method creates an entry identifier for a one-off address.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT CreateOneOff(

LPTSTR lpszName,
LPTSTR lpszAdrType,
LPTSTR lpszAddress,
ULONG ulFlags,
ULONG FAR * lpcbEntryID,
LPENTRYID FAR * lppEntryID
)
Parameters

lpszName

[in] Pointer to the display name of the recipient, the PR_DISPLAY_NAME property. The lpszName parameter can be NULL.

lpszAdrType

[in] Pointer to the address type of the recipient, such as FAX or SMTP. The lpszAdrType parameter cannot be NULL.

lpszAddress

[in] Pointer to the address of the recipient. The lpszAddress parameter cannot be NULL.

ulFlags

[in] Bitmask of flags that that affects the one-off recipient. The following flags can be set:

MAPI_SEND_NO_RICH_INFO

Indicates that the recipient can not handle formatted message content. If MAPI_SEND_NO_RICH_INFO is set, MAPI sets the recipient’s PR_SEND_RICH_INFO property to FALSE. If If MAPI_SEND_NO_RICH_INFO is not set, MAPI sets this property to TRUE unless the recipient’s messaging address pointed to by lpszAddress is interpreted to be an Internet address. In this case, MAPI sets PR_SEND_RICH_INFO to FALSE.

MAPI_UNICODE

The display name, address type, and address are in the Unicode format. If the MAPI_UNICODE flag is not set, these strings are in the ANSI format.

lpcbEntryID

[out] Pointer to the count of bytes in the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[out] Pointer to a pointer to the entry identifier for the one-off recipient.

Return Values

S_OK

The one-off entry identifier was created successfully.

Remarks

Clients call the IAddrBook::CreateOneOff method to create an entry identifier for a one-off recipient, a recipient that does not belong to any of the containers from any of the currently loaded address book providers. One-off recipients can have any type of address that is supported by one of the active address book providers for the session.

One-off recipients are typically created with a template for their particular address type. The address book provider that supports the address type supplies the template. A user of a client application enters the relevant information into the template.

MAPI supports Unicode character strings for the display name, address type, and address parameters to CreateOneOff on Windows NT platforms only.

The MAPI_SEND_NO_RICH_INFO flag controls whether or not formatted text in Rich Text Format (RTF) is sent along with each message. The Transport Neutral Encapsulation Format (TNEF) — a format used for transmitting formatted text — is sent by most transport providers, regardless of how the recipient sets its PR_SEND_RICH_INFO property. This is not an issue for messaging clients that work with interpersonal messages, but because TNEF is typically used to send custom properties for custom message classes, not supporting it can be a problem for form-based clients or clients that require custom MAPI properties. For more information, see Sending Messages with TNEF.

See Also

IMAPISupport::CreateOneOff


IAddrBook::Details

The IAddrBook::Details method displays a modal dialog box showing details about a particular address book entry.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT Details(

ULONG FAR * lpulUIParam,
LPFNDISMISS lpfnDismiss,
LPVOID lpvDismissContext,
ULONG cbEntryID,
LPENTRYID lpEntryID,
LPFNBUTTON lpfButtonCallback,
LPVOID lpvButtonContext,
LPTSTR lpszButtonText,
ULONG ulFlags
)
Parameters

lpulUIParam

[out] Handle of the parent window for the dialog box.

lpfnDismiss

[in] Pointer to a function based on the DISMISSMODELESS function prototype. This function is called when the modeless variety of the details dialog box is dismissed. This parameter is ignored at present because MAPI does not support a modeless details dialog box.

lpvDismissContext

[in] Data that is passed to the function specified by the lpfnDismiss parameter. This parameter is currently ignored.

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier for the entry for which details are displayed.

lpfButtonCallback

[in] Pointer to a function based on the LPFNBUTTON function prototype. An LPFNBUTTON function adds a button to the details dialog box.

lpvButtonContext

[in] Pointer to data used as a parameter for the function specified by the lpfButtonCallback parameter.

lpszButtonText

[in] Pointer to a string containing text to be applied to the added button if that button is extensible. The lpszButtonText parameter should be NULL if an extensible button is not needed.

ulFlags

[in] Bitmask of flags that controls the type of the text for the lpszButtonText parameter. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

Return Values

S_OK

The details dialog box was successfully displayed for the address book entry.

Remarks

Client applications call the IAddrBook::Details method to display a modal dialog box giving details on a particular entry in the address book. The lpfButtonCallback, lpvButtonContext, and lpButtonText parameters can be used to add a button the client has defined to the dialog box. When the button is chosen, MAPI calls the callback function pointed to by lpfButtonCallback, passing both the entry identifier of the button and the data in lpvButtonContext. If an extensible button is not needed, lpszButtonText should be NULL.

Details supports Unicode character strings for Windows NT platforms only. The Unicode strings are converted to the multi-byte character string (MBCS) format before they are displayed in the details dialog box.

See Also

IAddrBook::Address, LPFNBUTTON


IAddrBook::GetDefaultDir

The IAddrBook::GetDefaultDir method returns the entry identifier for the address book container that is initially made available.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT GetDefaultDir(

ULONG FAR * lpcbEntryID,
LPENTRYID FAR * lppEntryID
)
Parameters

lpcbEntryID

[out] Pointer to the count of bytes in the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[out] Pointer to a pointer to the entry identifier of the default container.

Return Values

S_OK

The entry identifier of the default container was successfully returned.

Remarks

Client applications and service providers call the IAddrBook::GetDefaultDir method to retrieve the entry identifier of the default address book container. The default container is what the user sees displayed in the address book when the address book is first opened. If a default container has not been set by a call to the IAddrBook::SetDefaultDir method, MAPI assigns as the default container the first container with names that is not the Personal Address Book (PAB). If such a container cannot be found, the PAB becomes the default container.

To set the default directory, a client or provider calls the IAddrBook::SetDefaultDir method. Clients and providers need not call the IMAPIProp::SaveChanges method; because changes to the address book are not transacted, changes are immediately made permanent.

See Also

IAddrBook::SetDefaultDir, MAPIAllocateBuffer, MAPIFreeBuffer, PR_CONTAINER_FLAGS


IAddrBook::GetPAB

The IAddrBook::GetPAB method returns the entry identifier of the container designated as the Personal Address Book (PAB).

Quick Info

See IAddrBook : IMAPIProp.

HRESULT GetPAB(

ULONG FAR * lpcbEntryID,
LPENTRYID FAR * lppEntryID
)
Parameters

lpcbEntryID

[out] Pointer to the count of bytes in the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[out] Pointer to a pointer to the entry identifier of the Personal Address Book (PAB). The lppEntryID parameter contains zero if no container has been designated as the PAB.

Return Values

S_OK

The entry identifier of the PAB was successfully returned.

Remarks

Clients call the IAddrBook::GetPAB method to retrieve the entry identifier of the container designated as the Personal Address Book (PAB). If a PAB has not been established in the profile, MAPI selects as the PAB the first container in the address book hierarchy that allows modifications.

See Also

MAPIAllocateBuffer, MAPIFreeBuffer, PR_CONTAINER_FLAGS


IAddrBook::GetSearchPath

The IAddrBook::GetSearchPath method returns an ordered list of entry identifiers of containers to be included in the name resolution process initiated by the IAddrBook::ResolveName method.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT GetSearchPath(

ULONG ulFlags,
LPSRowSet FAR * lppSearchPath
)
Parameters

ulFlags

[in] Bitmask of flags that controls the type of the strings returned in the search path. The following flag can be set:

MAPI_UNICODE

The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppSearchPath

[out] Pointer to a pointer to an ordered list of container entry identifiers. GetSearchPath stores the ordered list in an SRowSet structure. If there are no containers in the address book hierarchy, zero is returned in the SRowSet.

Return Values

S_OK

The search path was successfully retrieved.

Remarks

Clients and service providers call the IAddrBook::GetSearchPath method to get the search path that is used to resolve names with IAddrBook::ResolveName. Typically, clients call the IAddrBook::SetSearchPath method to establish a container search path in the profile before they call GetSearchPath to retrieve it. However, calling SetSearchPath is optional.

If SetSearchPath has never been called, GetSearchPath builds a path by working through the address book’s hierarchy tables. The default search path established by GetSearchPath is made up of the following containers in the following order:

1.	The first container with read/write access, usually the PAB.

2.	Every container that has its PR_DISPLAY_TYPE property set to DT_GLOBAL. Such a setting indicates that the container holds recipients.

3.	The container designated as the default, if there are no containers that have the DT_GLOBAL flag set in their PR_DISPLAY_TYPE property and the default container is not the same as the first container with read/write access.

If SetSearchPath has been called, GetSearchPath builds a path using the address book containers that have been stored in the profile. GetSearchPath validates this path before returning it to the caller.

After the first call to SetSearchPath, subsequent calls to SetSearchPath must be used to modify the search path returned by GetSearchPath. In other words, the calling client or provider does not receive the default search path after the first call to SetSearchPath.

See Also

IAddrBook::SetSearchPath, SRowSet


IAddrBook::NewEntry

The IAddrBook::NewEntry method adds a new recipient directly to an address book container or to the recipient list of an outgoing message..

Quick Info

See IAddrBook : IMAPIProp.

HRESULT NewEntry(

ULONG ulUIParam,
ULONG ulFlags,
ULONG cbEIDContainer,
LPENTRYID lpEIDContainer,
ULONG cbEIDNewEntryTpl,
LPENTRYID lpEIDNewEntryTpl,
ULONG FAR * lpcbEIDNewEntry,
LPENTRYID FAR * lppEIDNewEntry
)
Parameters

ulUIParam

[in] Handle of the parent window for the dialog box.

ulFlags

Reserved; must be zero.

cbEIDContainer

[in] Count of bytes in the entry identifier pointed to by the lpEIDContainer parameter.

lpEIDContainer

[in] Pointer to the entry identifier of the container where the new recipient is to be added. If the cbEIDContainer parameter is zero, NewEntry returns a recipient entry identifier and a list of templates as if the IAddrBook::CreateOneOff method was called.

cbEIDNewEntryTpl

[in] Count of bytes in the entry identifier pointed to by the lpEIDNewEntryTpl parameter.

lpEIDNewEntryTpl

[in] Pointer to a one-off template to be used to create the new recipient. If cbEIDNewEntryTpl is zero and lpEIDNewEntryTpl is NULL, NewEntry displays a dialog box enabling the user to select from a list of templates for adding new entries.

lpcbEIDNewEntry

[out] Pointer to the count of bytes in the entry identifier pointed to by the lppEIDNewEntry parameter is returned.

lppEIDNewEntry

[out] Pointer to a pointer to the new recipient’s entry identifier.

Return Values

S_OK

The new address book entry was successfully created.

Remarks

The IAddrBook::NewEntry method creates a new address book entry, to be added directly into a container or to be used to address an outgoing message.

Notes to Callers

If you want the new entry to be added to a specific container, set lpEIDContainer to the container’s entry identifier and cbEIDContainer to the count of bytes in the entry identifier.

If you want the new entry to be added to the recipient list of an outgoing message, set lpEIDContainer to NULL and cbEIDContainer to zero.

If you want to allow the user of a client application to select the type of entry to be created, pass zero in cbEIDNewEntryTpl and NULL in lpEIDNewEntryTpl. NewEntry displays MAPI’s one-off table, a listing of templates supported by MAPI and by each of the address book providers in the session. Each template can create a recipient entry for one or more address types.

If you want to retain the entry identifier of the new entry, pass valid pointers in the lpcbEIDNewEntry and lppEIDNewEntry parameters. You are responsible for freeing this entry identifier when you have finished with it by calling the MAPIFreeBuffer function.

To use a particular template for adding a new entry to a modifiable container:

•	Call IMAPISession::OpenEntry to open the destination container, setting the lpEntryID parameter to the entry identifier of the container.

1.	Call the destination container’s IMAPIProp::OpenProperty method and set ulPropTag to PR_CREATE_TEMPLATES and lpiid to IID_IMAPITable. The container will return a one-off table listing all of the templates that it supports for creating new entries.

2.	Retrieve the row that represents the template for the particular type of entry you want to create. The PR_ADDRTYPE column indicates the address type that is supported by the template.

3.	Call IAddrBook::NewEntry and set lpEIDNewEntryTpl to the entry identifier of the selected template. This will be the PR_ENTRYID column from the template’s row in the one-off table. Pass zero in cbEIDContainer and NULL in lpEIDContainer. Pass a valid pointer in the lppEIDNewEntry parameter if you want to retain the new entry’s entry identifier.

See Also

IAddrBook::OpenEntry, IMAPIProp::OpenProperty, PR_CREATE_TEMPLATES


IAddrBook::OpenEntry

The IAddrBook::OpenEntry method opens an address book entry and returns a pointer to an interface that can be used to access the entry.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT OpenEntry(

ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
ULONG ulFlags,
ULONG FAR * lpulObjType,
LPUNKNOWN FAR * lppUnk
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier representing the address book entry to open.

lpInterface

[in] Pointer to the interface identifier (IID) of the interface to be used to access the open entry. Passing NULL results in the object’s standard interface being returned. For messaging users, the standard interface is IMailUser. For distribution lists, it is IDistList and for containers, it is IABContainer. Caller can set lpInterface to the appropriate standard interface or an interface in the inheritance hierarchy.

ulFlags

[in] Bitmask of flags that controls how the entry is opened. The following flags can be set:

MAPI_BEST_ACCESS

Requests that the entry be opened with the maximum allowable network and client permissions. For example, if the client has read/write access, the address book provider should attempt to open the entry with read/write access.

The client can retrieve the access level that was granted by calling the open entry’s IMAPIProp::GetProps method and retrieving the PR_ACCESS_LEVEL property.

MAPI_DEFERRED_ERRORS

Allows the call to succeed potentially before the entry is fully open and accessible, implying that subsequent calls to the entry might return an error.

MAPI_MODIFY

Requests that the entry be opened with read/write access. Because by default, entries are opened with read-only access, clients should not assume that read/write access has been granted regardless of whether MAPI_MODIFY is set.

lpulObjType

[out] Pointer to the type of the opened entry.

lppUnk

[out] Pointer to a pointer to the opened entry.

Return Values

S_OK

The entry was successfully opened.

MAPI_E_NO_ACCESS

An attempt was made to open an entry for which the user has insufficient permissions.

MAPI_E_NOT_FOUND

The entry represented by lpEntryID does not exist.

MAPI_E_UNKNOWN_ENTRYID

The entry identifier specified in lpEntryID is not recognized. This value is typically returned if the address book provider responsible for the corresponding entry is not open.

Remarks

Clients and service providers call the IAddrBook::OpenEntry method to open an address book entry. MAPI forwards the call to the appropriate address book provider, based on the MAPIUID structure included in the entry identifier passed in the lpEntryID parameter. The address book provider opens the entry as read-only unless the MAPI_MODIFY or MAPI_BEST_ACCESS flag in the ulFlags parameter is set. However, these flags are suggestions. If the address book provider does not allow modification for the entry requested, then it returns MAPI_E_NO_ACCESS.

The lpInterface parameter indicates which interface should be used to access the opened entry. Passing NULL in lpInterface indicates the standard MAPI interface for that type of entry should be used. Because the address book provider might return a different interface than the one suggested by the lpInterface parameter, the caller should check the value returned in the lpulObjType parameter to determine that the object type returned is what was expected. If the object type is not of the type expected, the caller can cast the lppUnk parameter to a type that is more appropriate.


IAddrBook::PrepareRecips

The IAddrBook::PrepareRecips method prepares a recipient list for later use by the messaging system.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT PrepareRecips(

ULONG ulFlags,
LPSPropTagArray lpSPropTagArray,
LPADRLIST lpRecipList
)
Parameters

ulFlags

Reserved; must be zero.

lpSPropTagArray

[in] Pointer to an SPropTagArray structure containing an array of property tags indicating properties that require updating, if any. The lpSPropTagArray parameter can be NULL.

lpRecipList

[in] Pointer to an ADRLIST structure holding the list of recipients.

Return Values

S_OK

The recipient list was successfully prepared.

Remarks

Clients and service providers call IAddrBook::PrepareRecips to:

•	Ensure that all recipients in the lpRecipList parameter have long-term entry identifiers.

•	Ensure that each recipient in the lpRecipList parameter has the properties listed in the lpSPropTagArray parameter and that these properties appear at the beginning of the recipient list.

MAPI converts each recipient’s short-term entry identifiers to long-term entry identifiers. If necessary, recipients’ long-term entry identifiers are retrieved from the appropriate address book provider along with any additional properties requested.

Within an individual recipient entry, the requested properties are ordered first, followed by any additional properties that were already present for the entry. If one or more of the requested properties, the properties included in the lpSPropTagArray, are not handled by the appropriate address book provider, their property types will be set to PT_ERROR and their property values either to MAPI_E_NOT_FOUND or to another value giving a more specific reason why the properties are not available. Each SPropValue structure included in the lpSPropTagArray parameter must be separately allocated using the MAPIAllocateBuffer and MAPIAllocateMore functions such that it can be freed individually.

For information on PT_ERROR, see List of Property Types.

See Also

ADRLIST, IMAPIProp::GetProps, IMessage::ModifyRecipients, PR_ENTRYID, SPropValue, SRowSet


IAddrBook::QueryDefaultRecipOpt

The IAddrBook::QueryDefaultRecipOpt method returns the recipient options that have been set for a particular address type by the transport provider.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT QueryDefaultRecipOpt(

LPTSTR lpszAdrType,
ULONG ulFlags,
ULONG FAR * lpcValues,
LPSPropValue FAR * lppOptions
)
Parameters

lpszAdrType

[in] Pointer to a valid address type. The lpszAdrType parameter must not be NULL.

ulFlags

[in] Bitmask of flags that controls the type of the string passed in with the lpszAdrType parameter. The following flag can be set:

MAPI_UNICODE

The address type string is in Unicode format. If the MAPI_UNICODE flag is not set, the address type is in ANSI format.

lpcValues

[out] Pointer to the number of property values in the lppOptions parameter.

lppOptions

[out] Pointer to an array of SPropValue structures describing the recipient option properties.

Return Values

S_OK

The recipient option properties were successfully returned.

Remarks

Recipient options are properties that are set by a transport provider when MAPI calls its IXPLogon::RegisterOptions method. Not all transport providers register recipient options. Recipient options are usually, but not always, specific to a particular address type.

Clients and service providers call the IAddrBook::QueryDefaultRecipOpt method to programmatically retrieve the recipient options for a particular address type. If a client must display a dialog box with these options, the client should call the IAddrBook::RecipOptions method.

Transport providers can also register message options that apply to all of recipients. For more information on registering options, see Implementing Message and Recipient Options with Transport Providers.

See Also

IAddrBook::RecipOptions, IMAPISession::MessageOptions, IMAPISession::QueryDefaultMessageOpt


IAddrBook::RecipOptions

The IAddrBook::RecipOptions method displays a dialog box showing the recipient option properties.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT RecipOptions(

ULONG ulUIParam,
ULONG ulFlags,
LPADRENTRY lpRecip
)
Parameters

ulUIParam

[in] Handle of the parent window for the dialog box.

ulFlags

Reserved; must be zero.

lpRecip

[in] Pointer to the ADRENTRY structure that describes the recipient whose options are to be displayed.

Return Values

S_OK

The options for the specified recipient were successfully displayed.

MAPI_W_ERRORS_RETURNED

There are no recipient options for this recipient. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information on using the HR_FAILED macro, see Using Macros for Error Handling.

Remarks

Clients and service providers call the IAddrBook::RecipOptions method to display a dialog box to allow a user to set properties that control the sending and receiving of messages for a particular recipient and address type.

To locate the appropriate properties to be displayed, MAPI first scans through the SPropValue structure array in the ADRENTRY structure to find the PR_ENTRYID and PR_ADDRTYPE properties. MAPI then determines the transport provider, if any, that has registered options for the particular address type. If there is an appropriate transport provider, MAPI calls the provider’s function that is based on the OPTIONCALLBACK prototype to retrieve the properties.

To retrieve the set of default recipient options without presenting a dialog box to the user, clients or service providers should call the IAddrBook::QueryDefaultRecipOpt method.

If any recipient options are changed on a RecipOptions call, MAPI frees the old SPropValue structures for those options within the recipient’s ADRENTRY structure and allocates new ones.

If there are no recipient options available for the address type indicated in the lpRecip parameter, the warning MAPI_W_ERRORS_RETURNED is returned, indicating there was an error returned for the RecipOptions call. Calling the IMAPIProp::GetLastError method returns a text string describing the warning.

Transport providers can also register message options that apply to all of recipients. For more information on registering options, see Implementing Message and Recipient Options with Transport Providers.

See Also

ADRENTRY, IAddrBook::QueryDefaultRecipOpt, IMAPISession::MessageOptions, IMAPISession::QueryDefaultMessageOpt, SPropValue


IAddrBook::ResolveName

The IAddrBook::ResolveName method performs name resolution, assigning entry identifiers to recipients in a recipient list.

Quick Info

See IAddrBook : IMAPIProp

HRESULT ResolveName(

ULONG ulUIParam,
ULONG ulFlags,
LPTSTR lpszNewEntryTitle,
LPADRLIST lpAdrList
)
Parameters

ulUIParam

[in] Handle of the parent window for a dialog box that is shown, if necessary, to prompt the user to resolve ambiguity.

ulFlags

[in] Bitmask of flags that controls whether a dialog box can be displayed. The following flag can be set:

MAPI_DIALOG

Allows the display of a dialog box to prompt the user for additional name resolution information. If this flag is not set, no dialog box is displayed.

lpszNewEntryTitle

[in] Pointer to text for the title of the control in the dialog box that prompts the user to enter a recipient. The title varies depending on the type of recipient. The lpszNewEntryTitle parameter can be NULL.

lpAdrList

[in-out] Pointer to an ADRLIST structure containing the list of recipient names to be resolved. This ADRLIST structure can be created by the IAddrBook::Address method.

Return Values

S_OK

The name resolution process succeeded.

MAPI_E_AMBIGUOUS_RECIP

At least one recipient in the lpAdrList parameter matched more than one entry in the address book. Usually, this value is returned when the MAPI_DIALOG flag is set, prohibiting the display of a dialog box.

MAPI_E_NOT_FOUND

At least one recipient in the lpAdrList parameter cannot be resolved. Usually, this value is returned when the MAPI_DIALOG flag is set, prohibiting the display of a dialog box.

Remarks

Clients and service providers call the IAddrBook::ResolveName method to initiate the name resolution process. An unresolved entry is an entry that does not yet have an entry identifier — or PR_ENTRYID property.

ResolveName goes through the following process for each unresolved entry in the address list passed in the lpAdrList parameter:

1.	If the address type of the recipient adheres to the format of an SMTP address (displayname@address.addresslist), IAddrBook::ResolveName assigns it a one-off entry identifier.

2.	For each container in the PR_AB_SEARCH_PATH property, IAddrBook::ResolveName calls the IABContainer::ResolveNames method. IABContainer::ResolveNames tries to match the display name of each unresolved recipient with a display name belonging to one of its entries.

3.	If a container does not support IABContainer::ResolveNames, IAddrBook::ResolveName restricts the container’s contents table using a PR_ANR property restriction. This restriction causes the container to perform a “best guess” type of search to locate a matching recipient. All containers must support the PR_ANR property restriction.

4.	When a container returns a recipient that matches multiple names, IAddrBook::ResolveName displays a dialog box — if the MAPI_DIALOG flag is set — allowing the user to select the correct name.

5.	If all of the containers in the PR_AB_SEARCH_PATH property have been called and no match has been found, the recipient remains unresolved.

If one or more recipients are unresolved, IAddrBook::ResolveName returns MAPI_E_NOT_FOUND. If one or more recipients had ambiguous resolution that could not be resolved with a dialog box because the MAPI_DIALOG flag was not set, IAddrBook::ResolveName returns MAPI_E_AMBIGUOUS_RECIP. When some of the recipients are ambiguous and some cannot be resolved, IAddrBook::ResolveName can return either error value.

If a name cannot be resolved, the client can create a one-off address with a specially formatted address and entry identifier. For more information about the format of one-off entry identifiers, see One-Off Entry Identifiers. For more information about the format of one-off addresses, see One-Off Addresses.

MAPI supports Unicode character strings for the ADRLIST and the new entry title parameters to ResolveName on Windows NT platforms only.

See Also

ADRLIST, IABContainer::ResolveNames, IAddrBook::Address


IAddrBook::SetDefaultDir

The IAddrBook::SetDefaultDir method establishes a container as the default address book container — the container that is initially made available.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT SetDefaultDir(

ULONG cbEntryID,
LPENTRYID lpEntryID
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the default address book container.

Return Values

S_OK

The default address book container was successfully set.

Remarks

Clients and service providers call the IAddrBook::SetDefaultDir method to establish a new default address book container. The default container is the container that the user sees displayed in the address book when the address book is first opened. SetDefaultDir saves the default container as an entry in the profile. The container remains as the default either until another call to SetDefaultDir is made — in the same session or in another session — or the container is removed.

See Also

IAddrBook::GetDefaultDir, IAddrBook::GetSearchPath, IMAPISession::Logoff, MAPILogonEx


IAddrBook::SetPAB

The IAddrBook::SetPAB method designates a particular container to be the Personal Address Book (PAB).

Quick Info

See IAddrBook : IMAPIProp.

HRESULT SetPAB(

ULONG cbEntryID,
LPENTRYID lpEntryID
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the container to be designated as the PAB. The lpEntryID parameter cannot be NULL.

Return Values

S_OK

The specified container has been established as the PAB.

Remarks

Clients and service providers call the IAddrBook::SetPAB method to designate a particular container to be the Personal Address Book (PAB). The PAB is a container that is made up of entries copied from other containers as well as new entries.

Because information about the PAB is written in the profile, a particular container can be the PAB for multiple sessions. A call to SetPAB establishes a container as the PAB until that container is made unavailable or a new container becomes the PAB through a subsequent call to SetPAB.

Clients and providers need not call the IMAPIProp::SaveChanges method to make the PAB change permanent.

See Also

IAddrBook::GetPAB, IAddrBook::GetSearchPath, PR_CONTAINER_FLAGS


IAddrBook::SetSearchPath

The IAddrBook::SetSearchPath method sets a new search path in the profile that is used for the name resolution process.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT SetSearchPath(

ULONG ulFlags,
LPSRowSet lpSearchPath
)
Parameters

ulFlags

Reserved; must be zero.

lpSearchPath

[in] Pointer to the SRowSet structure used to hold the search path. The first property for each aRow member in the SRowSet must be PR_ENTRYID.

Return Values

S_OK

The search path was successfully set.

MAPI_E_MISSING_REQUIRED_COLUMN

One of the containers described in the SRowSet structure did not include its PR_ENTRYID property.

Remarks

Clients and service providers call the IAddrBook::SetSearchPath method to save changes made to the container search order that is used to resolve names with IAddrBook::ResolveName. The search path is saved between instances of a session. This functionality means that, after a call to the IMAPISession::Logoff method, subsequent calls to the MAPILogonEx function during the same session return the same search path as previously set, as long as that search path still exists.

Clients and providers need not call the IMAPIProp::SaveChanges method to make the search path changes permanent.

See Also

IAddrBook::GetDefaultDir, IAddrBook::GetPAB, IAddrBook::GetSearchPath, PR_CONTAINER_FLAGS


IAddrBook::Unadvise

The IAddrBook::Unadvise method cancels a notification registration previously established for an address book entry.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT Unadvise(

ULONG ulConnection
)
Parameters

ulConnection

[in] Connection number that represents the registration to be canceled. The ulConnection parameter should contain a value returned by a prior call to IAddrBook::Advise.

Return Values

S_OK

The registration was successfully canceled.

Remarks

Clients call the IAddrBook::Unadvise method to stop receiving notifications about changes to a particular address book entry. When a notification registration is canceled, the address book provider releases its pointer to the caller’s advise sink. However, the release can occur during the Unadvise call or at some later point, if another thread is in the process of calling IMAPIAdviseSink::OnNotify. When a notification is in progress, the release is delayed until the OnNotify method returns.

See Also

IAddrBook::Advise, IMAPIAdviseSink::OnNotify


IAttach : IMAPIProp

The IAttach interface is used to maintain and provide access to the properties of attachments in messages. The IAttach interface has no unique methods of its own.

For more information about using attachments, see Attachments and Attachment Tables.

Quick Info

Header file:	MAPIDEFS.H
Exposed by:	Attachment objects
Implemented by:	Message store providers
Called by:	Client applications
Corresponding pointer type:	LPATTACH
Transaction model:	Transacted
Vtable Order

No unique methods

Required properties	Access
PR_OBJECT_TYPE	Read-only
PR_ATTACH_METHOD	Read/write
PR_RENDERING_POSITION	Read/write


IDistList : IMAPIContainer

The IDistList interface is used to provide access to distribution lists in modifiable address book containers. IDistList can create, copy, and delete distribution lists, in addition to performing name resolution.

Quick Info

Header file:	MAPIDEFS.H
Exposed by:	Distribution list objects
Implemented by:	Address book providers
Called by:	Client applications
Corresponding pointer type:	LPDISTLIST
Vtable Order

No unique methods

Required properties	Access
PR_ADDRTYPE	Read/write
PR_DISPLAY_NAME	Read/write
PR_ENTRYID	Read-only
PR_OBJECT_TYPE	Read-only
PR_RECORD_KEY	Read-only
Remarks

IDistList inherits from IMAPIContainer and includes the same methods as address book containers. Therefore, because the methods of the IDistList interface are identical to those of the IABContainer interface, they are not redocumented here.

A distribution list, or object that implements IDistList, is a collection of messaging user objects, or individual recipients. A distribution list can be made up of all messaging user objects, or some messaging user and some distribution lists.

There are typically two types of distribution lists:

•	Distribution lists that are expanded by the underlying messaging system. This type of list has an address, PR_EMAIL_ADDRESS, and is treated the same as if it were an individual recipient.

•	Distribution lists that exist in a local container and are expanded by the client application.

Optional distribution list properties include:

PR_LAST_MODIFICATION_TIME

PR_DISPLAY_TYPE

PR_DETAILS_TABLE

Notice that PR_ADDRTYPE is required, but PR_EMAIL_ADDRESS is not. That is because a distribution list without an e-mail address can still receive messages, but its member list must be expanded. If the PR_ADDRTYPE property is set to MAPIPDL, MAPI performs the expansion. If PR_ADDRTYPE is a value other than MAPIPDL, the transport provider performs the expansion.

For further information on using the IDistList methods, see the reference entries for the parallel methods of IABContainer.

For more information about creating a distribution list, see Implementing IABContainer::CreateEntry.


IMailUser : IMAPIProp

The IMailUser interface is implemented by messaging user objects. IMailUser inherits from the IMAPIProp interface and has no unique methods of its own. The IMailUser interface provides access to the many properties that are associated with messaging users.

Quick Info

Header file:	MAPIDEFS.H
Exposed by:	Messaging user objects
Implemented by:	Address book providers
Called by:	Client applications
Corresponding pointer type:	LPMAILUSER
Vtable Order

No unique methods

Required properties	Access
PR_ADDRTYPE	Read/write
PR_DISPLAY_NAME	Read/write
PR_DISPLAY_TYPE	Read-only
PR_EMAIL_ADDRESS	Read/write
PR_ENTRYID	Read-only
PR_OBJECT_TYPE	Read-only
PR_RECORD_KEY	Read-only
PR_SEARCH_KEY	Read-only
Five of these required properties are known as the base address properties for recipients: PR_ADDRTYPE, PR_DISPLAY_NAME, PR_EMAIL_ADDRESS, PR_ENTRYID, and PR_SEARCH_KEY. These properties are considered special because many other groups of similar properties are built upon this base group. The other groups are used to describe a recipient in various roles, such as a message’s original or delegate sender. For more information about these properties and how to use them, see Address Types.

Messaging users can display a collection of their properties by supporting the PR_DETAILS_TABLE property. PR_DETAILS_TABLE is a display table that describes the layout of a details dialog box — a tabbed property page dedicated to showing recipient property information. Details dialog boxes are created by MAPI when a client calls the IAddrBook::Details method.

Messaging user objects can have other optional properties associated with them. MAPI defines over forty properties that provide additional addressing information about a messaging user. All of these properties are character strings. The more commonly used properties are:

PR_ACCOUNT

PR_ASSISTANT

PR_BUSINESS_TELEPHONE_NUMBER

PR_GIVEN_NAME

PR_GOVERNMENT_ID_NUMBER

PR_LOCALITY

PR_POSTAL_ADDRESS

For a complete list of these properties, see User Personal Information Properties.


IMAPIAdviseSink : IUnknown

The IMAPIAdviseSink interface is used to implement an advise sink object for handling notification. A pointer to an advise sink object is passed in a call to a service provider’s Advise method, the mechanism used to register for notification.

Quick Info

Header file:	MAPIDEFS.H
Exposed by:	Advise sink objects
Implemented by:	Client applications and MAPI
Called by:	Service providers and MAPI
Corresponding pointer type:	LPMAPIADVISESINK
Vtable Order

OnNotify	Responds to a notification by performing one or more tasks. The tasks performed depends on the object generating the notification and type of event.


IMAPIAdviseSink::OnNotify

The IMAPIAdviseSink::OnNotify method responds to a notification by performing one or more tasks. The tasks performed depends on the object generating the notification and type of event.

Quick Info

See IMAPIAdviseSink : IUnknown

ULONG OnNotify(

ULONG cNotif,
LPNOTIFICATION lpNotifications
)
Parameters

cNotif

[in] Count of NOTIFICATION structures pointed to by the lpNotifications parameter.

lpNotifications

[in] Pointer to one or more NOTIFICATION structures that provide information about the events that have occurred.

Return Value

S_OK

The notification was processed successfully.

Remarks

The notification process begins when a client or MAPI makes a call to a service provider’s Advise method to register to receive a notification of a particular type for a particular object. One of the parameters to the Advise method is a pointer to an advise sink object — an object that implements IMAPIAdviseSink. When an event occurs to the target object that corresponds to the registered notification, the service provider, either directly or indirectly through MAPI, calls the advise sink’s OnNotify method.

The call to OnNotify can occur either during the MAPI call that is causing the event or at some later time. On systems that support multiple threads of execution, OnNotify can be called either on the same thread that was used for registration or on a different thread. Clients can insure that the OnNotify call is made on the same thread used to call Advise by creating the advise sink that they pass to Advise with the HrThisThreadAdviseSink function.

The lpNotifications parameter points to one or more NOTIFICATION structures — structures that describe what has changed during the event. There is a different type of NOTIFICATION structure for each type of event.

The following table lists the values that are used to represent the possible types of events and the structures associated with each value:

Notification event type	Corresponding structure
fnevCriticalError	ERROR_NOTIFICATION
fnevNewMail	NEWMAIL_NOTIFICATION
fnevObjectCreated	OBJECT_NOTIFICATION
fnevObjectDeleted	OBJECT_NOTIFICATION
fnevObjectModified	OBJECT_NOTIFICATION
fnevObjectCopied	OBJECT_NOTIFICATION
fnevSearchComplete	OBJECT_NOTIFICATION
fnevTableModified	TABLE_NOTIFICATION
fnevStatusObjectModified	STATUS_OBJECT_NOTIFICATION
fnevExtended	EXTENDED_NOTIFICATION
For more information about setting up and stopping notifications, see the reference entries for the Advise and Unadvise methods for any of the following interfaces: IABLogon, IAddrBook, IMAPIForm, IMAPISession, IMAPITable, IMsgStore, and IMSLogon.

For general information about the notification process, see Event Notification in MAPI.

Notes to Implementers

Your OnNotify implementation will typically consist of one or more blocks of code for each type of notification you expect to receive. Within these blocks of code, perform any tasks that you deem necessary as a response to the notification. For example, suppose you register to receive fnevObjectModified notifications on a folder that is included in a dialog box display. In the block of code that you include in your OnNotify method to handle fnevObjectModified notifications, you might send a Windows message to the dialog box to request an updated display.

Do not modify or free the NOTIFICATION structure passed to OnNotify. The data in the structure is valid only until OnNotify returns.

Notes to Callers

When changes occur to multiple objects, you can notify a registered advise sink in a single call to OnNotify or in multiple calls depending on memory constraints. This is true regardless of whether the changes are the result of one method call or several. For example, a call to IMAPIFolder::CopyMessages can affect multiple messages and folders. As a message store provider, you can make one call to OnNotify with an fnevObjectModified event type for the target folder or many calls, one for each of the affected messages. Similarly, if a client makes repeated calls to IMAPIFolder::CreateMessage, these calls can be combined into one fnevObjectModified event for the folder or separated into individual fnevObjectCreated events for each of the new messages.

For more information about how and when to generate notifications, see the topics:

Event Notification in MAPI

Using A Support Object for Event Notification

See Also

HrAllocAdviseSink, HrThisThreadAdviseSink, IMAPISupport::Notify, NOTIFICATION


IMAPIContainer : IMAPIProp

The IMAPIContainer interface manages high-level operations on container objects such as address books, distribution lists, and folders. The IMAPIFolder, IABContainer, and IDistList interfaces are derived from IMAPIContainer.

Quick Info

Header file:	MAPIDEFS.H
Exposed by:	Folder, address book container, and distribution list objects
Implemented by:	Message store, address book, and remote transport providers
Called by:	Client applications
Corresponding pointer type:	LPMAPICONTAINER
Transaction model:	Not specified, abstract class
Vtable Order

GetContentsTable	Returns a pointer to the container’s contents table.
GetHierarchyTable	Returns a pointer to the container’s hierarchy table.
OpenEntry	Opens an object within the container, returning an interface pointer for further access.
SetSearchCriteria	Establishes search criteria for the container.
GetSearchCriteria	Obtains the search criteria for the container.
Required properties	Access
PR_CONTAINER_HIERARCHY	Read-only
PR_CONTAINER_CONTENTS	Read-only
PR_CONTAINER_FLAGS	Read/write


IMAPIContainer::GetContentsTable

The IMAPIContainer::GetContentsTable method returns a pointer to the container’s contents table.

Quick Info

See IMAPIContainer : IMAPIProp.

HRESULT GetContentsTable(

ULONG ulFlags,
LPMAPITABLE FAR * lppTable
)
Parameters

ulFlags

[in] Bitmask of flags that controls how the contents table is returned. The following flags can be set:

MAPI_ASSOCIATED

The container’s associated contents table should be returned rather than the standard contents table. This flag is used only with folders. The messages that are included in the associated contents table were created with the MAPI_ASSOCIATED flag set in the call to IMAPIFolder::CreateMessage. Clients typically use the associated contents table to retrieve forms and views.

MAPI_DEFERRED_ERRORS

GetContentsTable can return successfully, possibly before the table is made accessible to the caller. If the table is not accessible, making a subsequent table call can result in an error.

MAPI_UNICODE

Requests that the columns containing string data be returned in the Unicode format. If the MAPI_UNICODE flag is not set, the strings should be returned in the ANSI format.

lppTable

[out] Pointer to a pointer to the contents table.

Return Values

S_OK

The contents table was successfully retrieved.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

MAPI_E_NO_SUPPORT

The container has no contents and cannot provide a contents table.

Remarks

The IMAPIContainer::GetContentsTable method returns a pointer to the contents table of a container. A contents table contains summary information about objects within the container.

Contents tables have lengthy column sets. For a complete list of the required and optional columns in contents tables, see Contents Tables.

It is possible for some containers to have no contents. These containers return MAPI_E_NO_SUPPORT from their implementations of GetContentsTable.

Notes to Implementers

If you support a contents table for your container, you must also:

•	Support calls to the container’s IMAPIProp::OpenProperty method to open the PR_CONTAINER_CONTENTS property.

•	Return PR_CONTAINER_CONTENTS in response to a call to the container’s IMAPIProp::GetProps and IMAPIProp::GetPropList methods.

Notes to Callers

String and binary contents table columns can be truncated. Typically, providers return 255 characters. Because you cannot know ahead of time whether or not a table includes truncated columns, assume that a column is truncated if the length of the column is either 255 or 510 bytes. You can always retrieve the full value of a truncated column if necessary from the object directly by using its entry identifier to open it and then calling the IMAPIProp::GetProps method.

Depending on the provider’s implementation, restrictions and sorting operations can apply to an entire string or to the truncated version of that string.

See Also

IMAPIProp::GetPropList, IMAPIProp::GetProps, IMAPIProp::OpenProperty, IMAPITable : IUnknown, PR_CONTAINER_CONTENTS


IMAPIContainer::GetHierarchyTable

The IMAPIContainer::GetHierarchyTable method returns a pointer to the container’s hierarchy table.

Quick Info

See IMAPIContainer : IMAPIProp.

HRESULT GetHierarchyTable(

ULONG ulFlags,
LPMAPITABLE FAR * lppTable
)
Parameters

ulFlags

[in] Bitmask of flags that controls how information is returned in the table. The following flags can be set:

CONVENIENT_DEPTH

Fills the hierarchy table with containers from multiple levels. If CONVENIENT_DEPTH is not set, the hierarchy table contains only the container’s immediate child containers.

MAPI_DEFERRED_ERRORS

GetHierarchyTable can return successfully, possibly before the table is made accessible to the caller. If the table is not accessible, making a subsequent table call can result in an error.

MAPI_UNICODE

Requests that the columns containing string data be returned in the Unicode format. If the MAPI_UNICODE flag is not set, the strings should be returned in the ANSI format.

lppTable

[out] Pointer to a pointer to the hierarchy table.

Return Values

S_OK

The hierarchy table was successfully retrieved.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

MAPI_E_NO_SUPPORT

The container has no child containers and cannot provide a hierarchy table.

Remarks

The IMAPIContainer::GetHierarchyTable method returns a pointer to the hierarchy table of a container. A hierarchy table holds summary information about the child containers within the container. Folder hierarchy tables hold information about child folders; address book hierarchy tables hold information about child address book containers and distribution lists.

It is possible for some containers to have no child containers. These containers return MAPI_E_NO_SUPPORT from their implementations of GetHierarchyTable.

When the CONVENIENT_DEPTH flag is set, each row in the hierarchy table also includes the PR_DEPTH property as a column. PR_DEPTH indicates the level of each container relative to the container implementing the table. The implementing container’s immediate child containers are at depth zero, child containers within the zero depth containers are at depth one, and so on. The values of PR_DEPTH increase sequentially as the hierarchy of levels deepens.

For a complete list of required and optional columns in hierarchy tables, see Hierarchy Tables.

Notes to Implementers

If you support a hierarchy table for your container, you must also:

•	Support a call to the container’s IMAPIProp::OpenProperty method to open the PR_CONTAINER_HIERARCHY property.

•	Return PR_CONTAINER_HIERARCHY from a call to the container’s IMAPIProp::GetProps or IMAPIProp::GetPropList method.

Notes to Callers

String and binary contents table columns can be truncated. Typically, providers return 255 characters. Because you cannot know ahead of time whether or not a table includes truncated columns, assume that a column is truncated if the length of the column is either 255 or 510 bytes. You can always retrieve the full value of a truncated column if necessary from the object directly by using its entry identifier to open it and then calling the IMAPIProp::GetProps method.

Depending on the provider’s implementation, restrictions and sorting operations can apply to an entire string or to the truncated version of that string.

See Also

IMAPIProp::GetPropList, IMAPIProp::GetProps, IMAPITable : IUnknown, PR_CONTAINER_HIERARCHY


IMAPIContainer::GetSearchCriteria

The IMAPIContainer::GetSearchCriteria method obtains the search criteria for the container.

Quick Info

See IMAPIContainer : IMAPIProp.

HRESULT GetSearchCriteria(

ULONG ulFlags,
LPSRestriction FAR * lppRestriction,
LPENTRYLIST FAR * lppContainerList,
ULONG FAR * lpulSearchState
)
Parameters

ulFlags

[in] Bitmask of flags that controls the type of the passed-in strings. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppRestriction

[out] Pointer to a pointer to an SRestriction structure defining the search criteria. If a client application passes NULL in the lppRestriction parameter, GetSearchCriteria does not return an SRestriction structure.

lppContainerList

[out] Pointer to a pointer to an array of entry identifiers representing containers to be included in the search. If a client passes NULL in the lppContainerList parameter, GetSearchCriteria does not return an array of entry identifiers.

lpulSearchState

[out] Pointer to a bitmask of flags used to indicate the current state of the search. If a client passes NULL in the lpulSearchState parameter, GetSearchCriteria does not return any flags. The following flags can be set for lpulSearchState:

SEARCH_FOREGROUND

The search is running at high priority relative to other searches. If this flag is not set, the search is running at normal priority relative to other searches.

SEARCH_REBUILD

The search is in the CPU-intensive mode of its operation, attempting to locate messages that match the criteria. If this flag is not set, the CPU-intensive part of the search’s operation is over. This flag only has meaning if the search is active — that is, if the SEARCH_RUNNING flag is set.

SEARCH_RECURSIVE

The search is looking in specified containers and all of their child containers for matching entries. If this flag is not set, only the containers explicitly included in the last call to the IMAPIContainer::SetSearchCriteria method are being searched.

SEARCH_RUNNING

The search is active and the container’s contents table is being updated to reflect changes in the message store or address book. If this flag is not set, the search is inactive and the contents table is static.

Return Values

S_OK

The search criteria was successfully obtained.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

MAPI_E_NOT_INITIALIZED

Search criteria were never established for the container.

Remarks

The IMAPIContainer::GetSearchCriteria method obtains the search criteria for a container that supports searches, typically a search-results folder. Search criteria are created by calling a container’s IMAPIContainer::SetSearchCriteria method.

Notes to Implementers

Address book containers only need to support GetSearchCriteria if they provide the advanced search capabilities associated with the PR_SEARCH property. For more information on implementing the advanced search feature for address book containers, see Implementing Advanced Searching.

Notes to Callers

When you are finished with the data structures pointed to by the lppRestriction and lppContainerList parameters, call MAPIFreeBuffer to release the structures — one call to release each structure.

See Also

IMAPIContainer::SetSearchCriteria, IMAPIFolder::CreateFolder, MAPIFreeBuffer, PR_SEARCH


IMAPIContainer::OpenEntry

The IMAPIContainer::OpenEntry method opens an object within the container, returning an interface pointer for further access.

Quick Info

See IMAPIContainer : IMAPIProp.

HRESULT OpenEntry(

ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
ULONG ulFlags,
ULONG FAR * lpulObjType,
LPUNKNOWN FAR * lppUnk
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the object to open. If lpEntryID is set to NULL, the the top-level container in the container’s hierarchy is opened.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the object. Passing NULL results in the identifier for the object’s standard interface being returned. For messages, the standard interface is IMessage; for folders, it is IMAPIFolder. The standard interfaces for address book objects are IDistList for a distribution list and IMailUser for a messaging user.

ulFlags

[in] Bitmask of flags that controls how the object is opened. The following flags can be used:

MAPI_BEST_ACCESS

Requests that the object be opened with the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write access, the object should be opened with read/write access; if the client has read-only access, the object should be opened with read-only access.

MAPI_DEFERRED_ERRORS

Allows OpenEntry to return successfully, possibly before the object is fully accessible to the calling client. If the object is not accessible, making a subsequent object call can result in an error.

MAPI_MODIFY

Requests read/write access. By default, objects are opened with read-only access, and clients should not work on the assumption that read/write access has been granted.

lpulObjType

[out] Pointer to the opened object’s type.

lppUnk

[out] Pointer to a pointer to the interface implemention to use to access the open object.

Return Values

S_OK

The object was successfully opened.

MAPI_E_NO_ACCESS

Either the user has insufficient permissions to open the object or an attempt was made to open a read-only object with read/write access.

MAPI_E_NOT_FOUND

The entry identifier specified by lpEntryID does not represent an object.

MAPI_E_UNKNOWN_ENTRYID

The entry identifier in the lpEntryID parameter is not of a format recognized by the container.

Remarks

The IMAPIContainer::OpenEntry method opens an object within a container and returns a pointer to an interface implementation to use for further access.

Notes to Callers

Because service providers are not required to return an interface implementation of the type specified by the interface identifier in lpInterface, check the value pointed to by the lpulObjType parameter. If necessary, cast the pointer returned in lppUnk to a pointer of the appropriate type.

Service providers by default open objects with read-only access unless you set either the MAPI_MODIFY or MAPI_BEST_ACCESS flag. When one of these flags is set, service providers attempt to return a modifiable object. Do not assume that because you set the MAPI_MODIFY flag, for example, that the opened object has read/write access. Either plan for the possibility of a subsequent modification to fail or retrieve the object’s PR_ACCESS_LEVEL property to determine the access level granted by OpenEntry.


IMAPIContainer::SetSearchCriteria

The IMAPIContainer::SetSearchCriteria method establishes search criteria for the container.

Quick Info

See IMAPIContainer : IMAPIProp.

HRESULT SetSearchCriteria(

LPSRestriction lpRestriction,
LPENTRYLIST lpContainerList,
ULONG ulSearchFlags
)
Parameters

lpRestriction

[in] Pointer to an SRestriction structure defining the search criteria. If NULL is passed in the lpRestriction parameter, then the search criteria used most recently for this container are used again. NULL should not be passed in lpRestriction for the container’s first search.

lpContainerList

[in] Pointer to an array of entry identifiers representing containers to be included in the search. If a client passes NULL in the lpContainerList parameter, then the entry identifiers used most recently to search this container are used for the new search. A client should not pass NULL in lpContainerList for the first search within a container.

ulSearchFlags

[in] Bitmask of flags that controls how the search is performed. The following flags can be set:

BACKGROUND_SEARCH

The search should run at normal priority relative to other searches. This flag cannot be set at the same time as the FOREGROUND_SEARCH flag.

FOREGROUND_SEARCH

The search should run at high priority relative to other searches. This flag cannot be set at the same time as the BACKGROUND_SEARCH flag.

RECURSIVE_SEARCH

The search should include the containers specified in the lpContainerList parameter and all of their child containers. This flag cannot be set at the same time as the SHALLOW_SEARCH flag.

RESTART_SEARCH

The search should be initiated, if this is the first call to SetSearchCriteria, or restarted, if the search is inactive. This flag cannot be set at the same time as the STOP_SEARCH flag.

SHALLOW_SEARCH

The search should only look in the containers specified in the lpContainerList parameter for matching entries. This flag cannot be set at the same time as the RECURSIVE_SEARCH flag.

STOP_SEARCH

The search should be aborted. This flag cannot be set at the same time as the RESTART_SEARCH flag.

Return Values

S_OK

The search criteria was successfully set.

MAPI_E_TOO_COMPLEX

The service provider does not support the search criteria specified.

Remarks

The IMAPIContainer::SetSearchCriteria method establishes search criteria for a container that supports searches, typically a search-results folder. A search-results folder contains links to the messages that meet the search criteria; the actual messages are still stored in their original locations. The only unique data contained in a search-results folder is its contents table. The contents table of a search-results folder has the merged contents of the message store after the search restriction has been applied.

A search operation only works on this merged contents table; it does not search through other search-results folders. The search results only return the messages that match the search criteria; the folder hierarchy is not returned.

Control is returned to the client when the search has finished.

Notes to Implementers

Address book containers establish search critieria by applying restrictions to their contents tables. For more information about search criteria and address book containers, see Implementing Advanced Searching.

You should support open, copy, move, and delete operations on the messages within search-results folders, not on the search-results folder itself. Do not allow messages to be created within or copied into a search-results folder.

Notes to Callers

To search for message recipients, set lpRestriction to point to a subobject restriction with the ulSubObject member in the SSubRestriction structure set to PR_MESSAGE_RECIPIENTS. To search for attachments, set the ulSubObject member to PR_MESSAGE_ATTACHMENTS. Set the lpRes member to point to a property restriction describing the search criteria for the recipients or attachments.

For example, to look for file attachments with the extension .MSS, set ulSubObject to PR_MESSAGE_ATTACHMENTS and lpRes to a property restriction that matches PR_ATTACH_EXTENSION with MSS.

Setting the FOREGROUND_SEARCH flag in the ulSearchFlags parameter might cause a performance degradation.

You can use SetSearchCriteria to change the search criteria of a search already in progress. You can specify new restrictions, new lists of folders to search, and a new search priority, such as upgrading a search to a higher priority. Changes in search priority do not cause an existing search to restart, but other changes to search criteria can.

When you are through using a search-results folder, you can either delete the folder or let it remain open for later use. If you do delete the search-results folder, only message links are deleted. The actual messages remain in their parent folders.

For more information on search-results folders, see Search-Results Folders.

See Also

IMAPIContainer::GetContentsTable, IMAPIContainer::OpenEntry, IMAPIFolder::CreateFolder, IMAPIFolder : IMAPIContainer, SPropertyRestriction, SRestriction, SSubRestriction


IMAPIControl : IUnknown

The IMAPIControl interface is used to enable and disable a button control and to perform tasks when a user of a client application clicks the enabled control. Service providers implement control objects to create custom buttons on dialog boxes, such as configuration property sheets, that are defined with display tables.

For more information on working with display tables and control objects, see Display Tables.

Quick Info

Header file:	MAPIDEFS.H
Exposed by:	Control objects
Implemented by:	Service providers
Called by:	MAPI
Corresponding pointer type:	LPMAPICONTROL
Vtable Order

GetLastError	Returns a MAPIERROR structure containing information about the previous button control error.
Activate	Performs a task — such as displaying a dialog box or starting a programmatic operation — when the button control is clicked by a user of a client application.
GetState	Retrieves a value that indicates whether the button control is enabled or disabled.


IMAPIControl::Activate

The IMAPIControl::Activate method performs a task — such as displaying a dialog box or starting a programmatic operation — when the button control is clicked by a user of a client application.

Quick Info

See IMAPIControl : IUnknown.

HRESULT Activate(

ULONG ulFlags,
ULONG ulUIParam
)
Parameters

ulFlags

Reserved; must be zero.

ulUIParam

[in] Handle of the parent window for the dialog box on which the button control appears.

Return Values

S_OK

The button control was successfully activated.

Remarks

The IMAPIControl::Activate method performs tasks following a user’s click of the button control. After the click occurs, as part of the processing of the display table, MAPI makes a call to Activate after first calling IMAPIControl::GetState to determine if the button is enabled.

For more information about implementing Activate and the other IMAPIControl methods, see Implementing Control Objects.

See Also

IMAPIControl::GetState


IMAPIControl::GetLastError

The IMAPIControl::GetLastError method returns a MAPIERROR structure containing information about the previous button control error.

Quick Info

See IMAPIControl : IUnknown.

HRESULT GetLastError(

HRESULT hResult,
ULONG ulFlags,
LPMAPIERROR FAR * lppMAPIError
)
Parameters

hResult

[in] HRESULT data type containing the error value generated in the previous method call.

ulFlags

[in] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] Pointer to a pointer to a MAPIERROR structure containing version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if the provider cannot supply a MAPIERROR structure with appropriate information.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

Remarks

Service providers implement the IMAPIControl::GetLastError method to supply information about a prior method call that failed. MAPI can provide users with detailed information about the error by displaying the data from the MAPIERROR structure in a message or dialog box.

Notes to Implementers

It is not required that you have information to place in the MAPIERROR structure for every error. It may not be possible to determine what the previous error was. If you have information, return S_OK and the appropriate data in the MAPIERROR structure. If no information is available, return S_OK and a pointer to NULL for the lppMAPIError parameter.

For more information about the GetLastError method, see Using Extended Errors.

See Also

MAPIERROR, MAPIFreeBuffer


IMAPIControl::GetState

The IMAPIControl::GetState method retrieves a value that indicates whether the button control is enabled or disabled.

Quick Info

See IMAPIControl : IUnknown.

HRESULT GetState(

ULONG ulFlags,
ULONG FAR * lpulState
)
Parameters

ulFlags

Reserved; must be zero.

lpulState

[out] Pointer to a value indicating the state of the button control. One of the following values can be set:

MAPI_DISABLED

The button control is disabled and cannot be clicked.

MAPI_ENABLED

The button control is enabled and can be clicked.

Return Values

S_OK

The state of the button control was successfully retrieved.

Remarks

Service providers implement the IMAPIControl::GetState method to provide MAPI with the state of a button control. If enabled, the button can respond to a mouse click or key press. If disabled, the button appears dimmed and is incapable of responding to a mouse click or key press.

For more information about implementing GetState and the other IMAPIControl methods, see Implementing Control Objects.

See Also

IMAPIControl::Activate


IMAPIFolder : IMAPIContainer

The IMAPIFolder interface is used to perform operations on the messages and subfolders in a folder.

Quick Info

Header file:	MAPIDEFS.H
Exposed by:	Folder objects
Implemented by:	Message store providers
Called by:	Client applications and MAPI
Corresponding pointer type:	LPMAPIFOLDER
Transaction model:	Non-transacted
Vtable Order

CreateMessage	Creates a new message.
CopyMessages	Copies or moves one or more messages.
DeleteMessages	Deletes one or more messages.
CreateFolder	Creates a new subfolder.
CopyFolder	Copies or moves a subfolder.
DeleteFolder	Deletes a subfolder.
SetReadFlags	Sets or clears the MSGFLAG_READ flag in the PR_MESSAGE_FLAGS property of one or more of the folder’s messages and manages the sending of read reports.
GetMessageStatus	Obtains a message’s status.
SetMessageStatus	Sets a message’s status.
SaveContentsSort	Sets the default sort order for the contents table.
EmptyFolder	Removes all of the subfolders and messages without deleting the folder itself.
Required properties	Access
PR_DISPLAY_NAME	Read/write
PR_ENTRYID	Read-only
PR_FOLDER_TYPE	Read/write
PR_OBJECT_TYPE	Read-only
PR_PARENT_ENTRYID	Read-only
PR_RECORD_KEY	Read-only
PR_STORE_ENTRYID	Read-only
PR_STORE_RECORD_KEY	Read-only


IMAPIFolder::CopyFolder

The IMAPIFolder::CopyFolder method copies or moves a subfolder.

Quick Info

See IMAPIFolder : IMAPIContainer.

HRESULT CopyFolder(

ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
LPVOID lpDestFolder,
LPTSTR lpszNewFolderName,
ULONG ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the subfolder to copy or move.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the folder pointed to by the lpDestFolder parameter. Passing NULL results in the service provider returning the standard folder interface, IMAPIFolder. Valid values for lpInterface include IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer, or IID_IMAPIFolder.

lpDestFolder

[in] Pointer to the open folder to receive the copied or moved subfolder.

lpszNewFolderName

[in] Pointer to the name of the copied or moved folder in its new destination. If lpszNewFolderName is set to NULL, the name of the source subfolder is used for the name of the destination folder.

ulUIParam

[in] Handle of the parent window for the progress indicator. The ulUIParam parameter is ignored unless the FOLDER_DIALOG flag in the ulFlags parameter is set.

lpProgress

[in] Pointer to a progress object for displaying a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator using the MAPI progress object implementation. The lpProgress parameter is ignored unless the FOLDER_DIALOG flag is set in ulFlags.

ulFlags

[in] Bitmask of flags that controls the copy or move operation. The following flags can be set:

COPY_SUBFOLDERS

All of the subfolders in the subfolder to be copied should also be copied. When COPY_SUBFOLDERS is not set for a copy operation, only the subfolder identified by lpEntryID is copied. With a move operation, the COPY_SUBFOLDERS behavior is the default regardless of whether the flag is set.

FOLDER_DIALOG

Requests the display of a progress indicator.

FOLDER_MOVE

The subfolder is to be moved rather than copied. If FOLDER_MOVE is not set, the subfolder is copied.

MAPI_DECLINE_OK

Informs the message store provider that if it implements CopyFolder by calling its support object’s IMAPISupport::DoCopyTo or IMAPISupport::DoCopyProps method, it should instead immediately return MAPI_E_DECLINE_COPY from CopyFolder.

MAPI_UNICODE

The name of the destination folder is in the Unicode format. If the MAPI_UNICODE flag is not set, the folder name is in the ANSI format.

Return Values

S_OK

The specified folder has been successfully copied or moved.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the message store provider does not support Unicode, or MAPI_UNICODE was not set and the message store provider only supports Unicode.

MAPI_E_COLLISION

The name of the folder being moved or copied is the same as that of a subfolder in the destination folder. The message store provider requires that folder names be unique.

MAPI_E_DECLINE_COPY

The provider implements this method by calling a support object method and the caller has passed the MAPI_DECLINE_OK flag.

MAPI_E_FOLDER_CYCLE

The source folder directly or indirectly contains the destination folder. Significant work might have been performed before this condition was discovered so the source and destination folder might be partially modified.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but not all entries were successfully copied. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPIFolder::CopyFolder method copies or moves a subfolder from one location to another. The subfolder being copied or moved is added to the destination folder as a subfolder.

Notes to Implementers

When the copy or move operation involves more than one folder, as indicated by the COPY_SUBFOLDERS flag being set, perform the operation as completely as possible for each folder. Sometimes one of the folders to be moved or copied does not exist or has already been moved or copied elsewhere. Do not stop the operation prematurely unless a failure occurs that is beyond your control, such as running out of memory, running out of disk space, or corruption in the message store.

Try to retain all message entry identifiers in the copied messages. Preserving entry identifiers is not required, but it is recommended.

Notes to Callers

Expect these return values under the following conditions:

Condition	Return value
CopyFolder has successfully copied or moved every message and subfolder.	S_OK
CopyFolder was unable to successfully copy or move every message and subfolder.	MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND
CopyFolder was unable to complete.	Any error value except MAPI_E_NOT_FOUND
When CopyFolder is unable to complete, do not assume that no work was done. CopyFolder might have been able to copy or move one or more of the messages and subfolders before encountering the error.

If an entry identifier for a folder that doesn’t exist is passed in lpEntryID, CopyFolder returns MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND, depending on the message store’s implementation.

Depending on the message store provider, the entry identifier of the original message may or may not be preserved in the copied message. MAPI recommends that entry identifiers be preserved whenever possible, but it is not a requirement. You can generally depend on the following to occur:

•	When moving a folder between two different types of message stores, the entry identifier is guaranteed to change.

•	When moving a folder between two message stores of the same type, the entry identifier almost always changes.

•	When moving a folder to another location within the same message store, the entry identifier might or might not change, depending on the message store provider.


IMAPIFolder::CopyMessages

The IMAPIFolder::CopyMessages method copies or moves one or more messages.

Quick Info

See IMAPIFolder : IMAPIContainer.

HRESULT CopyMessages(

LPENTRYLIST lpMsgList,
LPCIID lpInterface,
LPVOID lpDestFolder,
ULONG ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
)
Parameters

lpMsgList

[in] Pointer to an array of ENTRYLIST structures that identify the message or messages to copy or move.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the destination folder pointed to by the lpDestFolder parameter. Passing NULL results in the service provider returning the standard folder interface, IMAPIFolder. Clients must pass NULL. Other callers can set the lpInterface parameter to IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer, or IID_IMAPIFolder.

lpDestFolder

[in] Pointer to the open folder to receive the copied or moved messages.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays. The ulUIParam parameter is ignored unless the client sets the MESSAGE_DIALOG flag in the ulFlags parameter and passes NULL in the lpProgress parameter.

lpProgress

[in] Pointer to a progress object for displaying a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator using the MAPI progress object implementation. The lpProgress parameter is ignored unless the MESSAGE_DIALOG flag is set in ulFlags.

ulFlags

[in] Bitmask of flags that controls how the copy or move operation is accomplished. The following flags can be set:

MAPI_DECLINE_OK

Informs the message store provider to immediately return MAPI_E_DECLINE_COPY if it implements CopyMessage by calling the support object’s IMAPISupport::DoCopyTo or IMAPISupport::DoCopyProps method.

MESSAGE_DIALOG

Displays a progress indicator as the operation proceeds.

MESSAGE_MOVE

The message or messages are to be moved rather than copied. If MESSAGE_MOVE is not set, the messages are copied.

Return Values

S_OK

The message or messages have been successfully copied or moved.

MAPI_E_DECLINE_COPY

The provider implements this method by calling a support object method and the caller has passed the MAPI_DECLINE_OK flag.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but not all entries were successfully copied or moved. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPIFolder::CopyMessages method copies or moves messages to another folder.

Messages that are open with read/write access can be moved or copied.

Notes to Implementers

If you are copying messages to another message store without using the IMAPISupport::CopyMessages method, you must first call IMAPIFolder::SetReadFlags with the GENERATE_RECEIPT_ONLY flag set. The receiving message store is not responsible for generating read reports for the copied or moved messages. If you are calling IMAPISupport::CopyMessages to implement IMAPIFolder::CopyMessages, do not make the SetReadFlags call. MAPI will take care of it.

Move or copy the messages in any order and generate read status reports in any order. That is, you can finish copying messages before generating any of the read status reports or send the reports before beginning the copy. However, read reports should be sent for all messages to be copied, regardless of whether or not the copy is successful.

When the copy or move operation involves more than one message, perform the operation as completely as possible. Do not stop the operation prematurely unless a failure occurs that is beyond your control, such as running out of memory, running out of disk space, or corruption in the message store.

Try to maintain entry identifiers across move or copy operations.

Send notifications when moving or copying messages so that clients are forewarned that their calls to the messages’ IMAPIProp::SaveChanges methods may fail.

Do not include a message’s status in the copy or move operation. Moving or copying a message status greatly affects performance.

Notes to Callers

Use CopyMessages for populating search-results folders, where messages are often grouped by parent folder.

Expect these return values under the following conditions:

Condition	Return value
CopyMessages has successfully copied or moved every message.	S_OK
CopyMessages was unable to successfully copy or move every message.	MAPI_W_PARTIAL_COMPLETION
CopyMessages was unable to complete.	Any error value
When CopyMessages is unable to complete, do not assume that no work was done. CopyMessages might have been able to copy or move one or more messages before encountering the error.


IMAPIFolder::CreateFolder

The IMAPIFolder::CreateFolder method creates a new subfolder.

Quick Info

See IMAPIFolder : IMAPIContainer.

HRESULT CreateFolder(

ULONG ulFolderType,
LPTSTR lpszFolderName,
LPTSTR lpszFolderComment,
LPCIID lpInterface,
ULONG ulFlags,
LPMAPIFOLDER FAR * lppFolder
)
Parameters

ulFolderType

[in] The type of folder to create. One of the following values can be passed:

FOLDER_GENERIC

A generic folder should be created.

FOLDER_SEARCH

A search-results folder should be created.

lpszFolderName

[in] Pointer to a string containing the name for the new folder. This name is the basis for the new folder’s PR_DISPLAY_NAME property.

lpszFolderComment

[in] Pointer to a string containing a comment associated with the new folder. This string becomes the value of the new folder’s PR_COMMENT property. If NULL is passed, the folder has no initial comment.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the new folder. Passing NULL results in the message store provider returning the standard folder interface, IMAPIFolder. Clients must pass NULL. Other callers can set the lpInterface parameter to IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer, or IID_IMAPIFolder.

ulFlags

[in] Bitmask of flags that controls how the folder is created. The following flags can be set:

MAPI_DEFERRED_ERRORS

Allows CreateFolder to return successfully, possibly before the new folder is fully accessible to the calling client. If the new folder is not accessible, making a subsequent call to it can result in an error.

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

OPEN_IF_EXISTS

Allows the method to succeed — even if the folder named in the lpszFolderName parameter already exists — by opening the existing folder with that name. Note that message store providers that allow sibling folders to have the same name might fail to open an existing folder if more than one exists with the supplied name.

lppFolder

[out] Pointer to a pointer to the newly created folder.

Return Values

S_OK

The new folder has been successfully created or opened, if the OPEN_IF_EXISTS flag is set.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

MAPI_E_COLLISION

A folder with the name given in the lpszFolderName parameter already exists. Folder names must be unique.

Remarks

The IMAPIFolder::CreateFolder method creates a subfolder in the current folder and assigns an entry identifier to the new folder.

Notes to Callers

When CreateFolder returns, be aware that the entry identifier for the new folder might not be available. Some message store providers do not make entry identifiers available until after you have called the new folder’s IMAPIProp::SaveChanges method to permanently save it. This is especially true if you have set the MAPI_DEFERRED_ERRORS flag.

Be aware that some message store providers always point lppFolder to the folder’s standard interface, regardless of the value that you pass in for the lpInterface parameter. Because the interface pointer that is returned might not be of the type that you expect, call the new folder’s IMAPIProp::GetProps method to retrieve the PR_OBJECT_TYPE property. If necessary, cast the pointer to a more appropriate type before making other calls.

Most message store providers require the name of the new folder to be unique with respect to the names of its sibling folders. Be able to handle the MAPI_E_COLLISION error value, which is returned if this rule is not followed.

To determine the entry identifier of the newly created folder, call the new folder’s IMAPIProp::GetProps method to retrieve its PR_ENTRYID property.

See Also

IMAPIProp::GetProps


IMAPIFolder::CreateMessage

The IMAPIFolder::CreateMessage method creates a new message.

Quick Info

See IMAPIFolder : IMAPIContainer.

HRESULT CreateMessage(

LPCIID lpInterface,
ULONG ulFlags,
LPMESSAGE FAR * lppMessage
)
Parameters

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the new message. Valid interface identifiers include IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer, and IID_IMAPIFolder. Passing NULL results in the message store provider returning the standard message interface, IMessage.

ulFlags

[in] Bitmask of flags that controls how the message is created. The following flags can be set:

MAPI_ASSOCIATED

The message to be created should be included in the associated contents table rather than the standard contents table. Associated messages typically contain invisible data, such as view descriptors.

MAPI_DEFERRED_ERRORS

CreateMessage is allowed to succeed even if the create operation has not fully completed. This implies that the new message might not be immediately accessible to the caller.

lppMessage

[out] Pointer to a pointer to the newly created message.

Return Values

S_OK

The message was successfully created.

Remarks

The IMAPIFolder::CreateMessage method creates a new message with generic or associated content and assigns an entry identifier. The entry identifier is made up of a part that represents the message store provider and a part that represents the individual message.

Notes to Callers

Some message store providers allow the entry identifier of the new message to be available immediately after CreateMessage returns; others delay its availability until the message has been saved. Because not all message store providers generate an entry identifier for a new message until you have called the message’s IMAPIProp::SaveChanges method, you may not be able to access the entry identifier when CreateMessage returns. Also, the new message may not be included in the folder’s contents table until the save occurs.

Expect the entry identifier assigned to the new message to be unique not only within the current message store, but most likely across all of the message stores that are open concurrently. One exception to this general rule occurs when multiple entries for a message store appear in the profile, causing the message store to be opened multiple times and entry identifiers to be duplicated.

To create an outgoing message, call the Outbox folder’s IMAPIFolder::CreateMessage method.

If you delete a folder containing a new message before the message is saved, the results are undefined.

Notes to Implementers

You can choose whether to set all of the required message properties in CreateMessage or in the message’s IMAPIProp::SaveChanges method. You do not need to make these properties available until a successful save has occurred.

For more information on working with associated information, see Folder Associated Information Tables and Contents Tables.

See Also

IMAPIProp::SaveChanges


IMAPIFolder::DeleteFolder

The IMAPIFolder::DeleteFolder method removes a subfolder.

Quick Info

See IMAPIFolder : IMAPIContainer.

HRESULT DeleteFolder(

ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the subfolder to delete.

ulUIParam

[in] Handle of the parent window for the progress indicator. The ulUIParam parameter is ignored unless the FOLDER_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] Pointer to a progress object for displaying a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator using the MAPI progress object implementation. The lpProgress parameter is ignored unless the FOLDER_DIALOG flag is set in ulFlags.

ulFlags

[in] Bitmask of flags that controls the deletion of the subfolder. The following flags can be set:

DEL_FOLDERS

All subfolders of the subfolder pointed to by lpEntryID should be deleted.

DEL_MESSAGES

All messages in the subfolder pointed to by lpEntryID should be deleted.

FOLDER_DIALOG

A progress indicator should be displayed while the operation proceeds.

Return Values

S_OK

The specified folder has been successfully deleted.

MAPI_E_HAS_FOLDERS

The subfolder being deleted contains subfolders, and the DEL_FOLDERS flag was not set. The subfolder was not deleted.

MAPI_E_HAS_MESSAGES

The subfolder being deleted contains messages, and the DEL_MESSAGES flag was not set. The subfolder was not deleted.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but not all of the entries were successfully deleted. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPIFolder::DeleteFolder method deletes a subfolder. Folders to be deleted must be located in the folder designated as the special wastebasket folder, typically the Deleted Items folder in the IPM subtree. By default, DeleteFolder only operates on empty folders, but it can be used successfully on non-empty folders by setting two flags: DEL_FOLDERS and DEL_MESSAGES. Only empty folders or folders that set both the DEL_FOLDERS and DEL_MESSAGES flags on the DeleteFolder call can be deleted. DEL_FOLDERS enables all of the folder’s subfolders to be removed; DEL_MESSAGES enables all of the folder’s messages to be removed.

Notes to Implementers

When the delete operation involves more than one folder, perform the operation as completely as possible for each folder. Sometimes one of the folders to be deleted does not exist or has been moved or copied elsewhere. Do not stop the operation prematurely unless a failure occurs that is beyond your control, such as running out of memory, running out of disk space, or corruption in the message store.

During a DeleteFolder call, messages being processed by the MAPI spooler are not deleted; they are left in their parent folders. Do not call the IMsgStore::AbortSubmit method for these messages.

Notes to Callers

Expect these return values under the following conditions:

Condition	Return value
DeleteFolder has successfully deleted every message and subfolder.	S_OK
DeleteFolder was unable to successfully delete every message and subfolder.	MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND
DeleteFolder was unable to complete.	Any error value except MAPI_E_NOT_FOUND
When DeleteFolder is unable to complete, do not assume that no work was done. DeleteFolder might have been able to delete one or more of the messages and subfolders before encountering the error.

If one or more subfolders cannot be deleted, DeleteFolder returns MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND, depending on the message store provider’s implementation.


IMAPIFolder::DeleteMessages

The IMAPIFolder::DeleteMessages method deletes one or more messages.

Quick Info

See IMAPIFolder : IMAPIContainer.

HRESULT DeleteMessages(

LPENTRYLIST lpMsgList,
ULONG ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
)
Parameters

lpMsgList

[in] Pointer to an array of ENTRYLIST structures that identify the message or messages to delete.

ulUIParam

[in] Handle of the parent window for the progress indicator. The ulUIParam parameter is ignored unless the MESSAGE_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] Pointer to a progress object for displaying a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator using the MAPI progress object implementation. The lpProgress parameter is ignored unless the MESSAGE_DIALOG flag is set in ulFlags.

ulFlags

[in] Bitmask of flags that controls how the messages are deleted. The following flag can be set:

MESSAGE_DIALOG

Displays a progress indicator as the operation proceeds.

Return Values

S_OK

The specified message or messages were successfully deleted.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but not all of the messages were successfully deleted. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPIFolder::DeleteMessages method deletes messages from a folder. Messages that do not exist, that have been moved elsewhere, that are open with read/write access, or that are currently submitted cannot be deleted.

Notes to Implementers

When the delete operation involves more than one message, perform the operation as completely as possible for each folder, even if one or more of the messages cannot be deleted. Do not stop the operation prematurely unless a failure occurs that is beyond your control, such as running out of memory, running out of disk space, or corruption in the message store.

During a DeleteMessages call, messages being processed by the MAPI spooler are not deleted; they are left in their parent folders. Do not call the IMsgStore::AbortSubmit method for these messages.

Notes to Callers

Expect these return values under the following conditions:

Condition	Return value
DeleteMessages has successfully deleted every message.	S_OK
DeleteMessages was unable to successfully delete every message and subfolder.	MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND
DeleteMessages was unable to complete.	Any error value except MAPI_E_NOT_FOUND
When DeleteMessages is unable to complete, do not assume that no work was done. DeleteMessages might have been able to delete one or more of the messages before encountering the error.

DeleteMessages returns MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND, depending on the message store’s implementation.


IMAPIFolder::EmptyFolder

The IMAPIFolder::EmptyFolder method deletes all messages and subfolders from a folder without deleting the folder itself.

Quick Info

See IMAPIFolder : IMAPIContainer.

HRESULT EmptyFolder(

ULONG ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
)
Parameters

ulUIParam

[in] Handle of the parent window for the progress indicator. The ulUIParam parameter is ignored unless the FOLDER_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] Pointer to a progress object for displaying a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator using the MAPI progress object implementation. The lpProgress parameter is ignored unless the FOLDER_DIALOG flag is set in ulFlags.

ulFlags

[in] Bitmask of flags that controls how the folder is emptied. The following flags can be set:

DEL_ASSOCIATED

Deletes all subfolders, including subfolders containing messages with associated content. The DEL_ASSOCIATED flag only has meaning for the top-level folder the call acts on.

FOLDER_DIALOG

Displays a progress indicator while the operation proceeds.

Return Values

S_OK

The folder was successfully emptied.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but the folder was not completely emptied. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPIFolder::EmptyFolder method deletes all of a folder’s contents without deleting the folder itself.

During an EmptyFolder call, submitted messages are not deleted.

A folder’s associated information includes messages that are used to describe views and form definitions.

Notes to Implementers

Do not call IMsgStore::AbortSubmit for messages in the folder that have been submitted. Submitted messages are not deleted.

Notes to Callers

Expect these return values under the following conditions:

Condition	Return value
EmptyFolder has successfully emptied the folder.	S_OK
EmptyFolder was unable to completely empty the folder.	MAPI_W_PARTIAL_COMPLETION
EmptyFolder was unable to complete.	Any error value
When EmptyFolder is unable to complete, do not assume that no work was done. EmptyFolder might have been able to delete some of the folder’s contents before encountering the error.


IMAPIFolder::GetMessageStatus

The IMAPIFolder::GetMessageStatus method obtains the status associated with a message in a particular folder — for example, whether that message is marked for deletion.

Quick Info

See IMAPIFolder : IMAPIContainer.

HRESULT GetMessageStatus(

ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulFlags,
ULONG FAR * lpulMessageStatus
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier for the message whose status is obtained.

ulFlags

Reserved; must be zero.

lpulMessageStatus

[out] Pointer to a pointer to a bitmask of flags indicating the message’s status. Bits 5 through 15 are reserved and must be zero; bits 16 through 31 are available for implementation-specific use.

The following flags can be set:

MSGSTATUS_DELMARKED

The message has been marked for deletion.

MSGSTATUS_HIDDEN

The message is not to be displayed.

MSGSTATUS_HIGHLIGHTED

The message is to be displayed highlighted.

MSGSTATUS_REMOTE_DELETE

The message has been marked for deletion at the remote message store without downloading to the local client.

MSGSTATUS_REMOTE_DOWNLOAD

The message has been marked for downloading from the remote message store to the local client.

MSGSTATUS_TAGGED

The message has been tagged for a client-defined purpose.

Return Values

S_OK

The message status was successfully retrieved.

Remarks

The IMAPIFolder::GetMessageStatus method returns the status of a message. Message status is stored in the message’s PR_MSG_STATUS property.

Notes to Implementers

How the message status bits are set, cleared, and used depends entirely on your implementation, except that bits 5 through 15 are reserved and must be zero. If you store messages in the IPM subtree, MAPI reserves bits 16 through 31 for use by IPM clients. If you store messages in other subtrees, you can use bits 16 through 31 for your own purposes.

See Also

IMAPIFolder::SetMessageStatus


IMAPIFolder::SaveContentsSort

The IMAPIFolder::SaveContentsSort method sets the default sort order for a folder’s contents table.

Quick Info

See IMAPIFolder : IMAPIContainer.

HRESULT SaveContentsSort(

LPSSortOrderSet lpSortCriteria,
ULONG ulFlags
)
Parameters

lpSortCriteria

[in] Pointer to an SSortOrderSet structure containing the default sort order.

ulFlags

[in] Bitmask of flags that controls how the default sort order is set. The following flag can be set:

RECURSIVE_SORT

The default sort order set applies to the indicated folder and to all of its subfolders.

Return Values

S_OK

The sort order was successfully saved.

MAPI_E_NO_SUPPORT

The message store provider does not support saving a sort order for its folder contents tables.

Remarks

The IMAPIFolder::SaveContentsSort method establishes a default sort order for a folder’s contents table. That is, when a client calls the folder’s IMAPIContainer::GetContentsTable method after calling SaveContentsSort, the rows in the returned contents table will appear in the order established by SaveContentsSort.

Not all message store providers support SaveContentsSort; it is acceptable for message store providers to return MAPI_E_NO_SUPPORT from the SaveContentsSort method.

See Also

IMAPIContainer::GetContentsTable, SSortOrderSet


IMAPIFolder::SetMessageStatus

The IMAPIFolder::SetMessageStatus method sets the status associated with a message— for example, whether that message is marked for deletion.

Quick Info

See IMAPIFolder : IMAPIContainer.

HRESULT SetMessageStatus(

ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulNewStatus,
ULONG ulNewStatusMask,
ULONG FAR * lpulOldStatus
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier for the message whose status is set.

ulNewStatus

[in] New status to be assigned.

ulNewStatusMask

[in] Bitmask of flags that is applied to the new status indicating the flags to be set.

The following flags can be set:

MSGSTATUS_DELMARKED

The message has been marked for deletion.

MSGSTATUS_HIDDEN

The message is not to be displayed.

MSGSTATUS_HIGHLIGHTED

The message is to be displayed as highlighted.

MSGSTATUS_REMOTE_DELETE

The message has been marked for deletion at the remote message store without downloading to the local client.

MSGSTATUS_REMOTE_DOWNLOAD

The message has been marked for downloading from the remote message store to the local client.

MSGSTATUS_TAGGED

The message has been tagged for a client-defined purpose.

lpulOldStatus

[out] Pointer to the previous status of the message.

Return Values

S_OK

The message status was successfully set.

Remarks

The IMAPIFolder::SetMessageStatus method sets the status associated with a message — the value that is stored in its PR_MSG_STATUS property.

Notes to Implementers

How the message status bits are set, cleared, and used depends entirely on your implementation, except that bits 5 through 15 are reserved and must be zero.

Notes to Callers

You can use the PR_MSG_STATUS property of a message to negotiate a message lockout operation with other clients. Designate a bit as the lockout bit. To determine if the lockout bit was set, examine the previous value for message status in the lpulOldStatus parameter. Use the other bits in the ulNewStatus parameter to track message status without interfering with the lockout bit.

See Also

IMAPIFolder::GetMessageStatus


IMAPIFolder::SetReadFlags

The IMAPIFolder::SetReadFlags method sets or clears the MSGFLAG_READ flag in the PR_MESSAGE_FLAGS property of one or more of the folder’s messages and manages the sending of read reports.

Quick Info

See IMAPIFolder : IMAPIContainer.

HRESULT SetReadFlags(

LPENTRYLIST lpMsgList,
ULONG ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
)
Parameters

lpMsgList

[in] Pointer to an array of ENTRYLIST structures that identify the message or messages with read flags to set or clear. If lpMsgList is set to NULL, the read flags for all of the folder’s messages are set or cleared.

ulUIParam

[in] Handle of the parent window for the progress indicator. The ulUIParam parameter is ignored unless the MESSAGE_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] Pointer to a progress object for displaying a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator using MAPI’s implementation. The lpProgress parameter is ignored unless the MESSAGE_DIALOG flag is set in ulFlags.

ulFlags

[in] Bitmask of flags that controls the setting of a message’s read flag and the processing of read reports. The following flags can be set:

CLEAR_READ_FLAG

The MSGFLAG_READ flag should be cleared in PR_MESSAGE_FLAGS and that no read report should be sent.

CLEAR_NRN_PENDING

The MSGFLAG_NRN_PENDING flag should be cleared in PR_MESSAGE_FLAGS and a nonread report should not be sent.

CLEAR_RN_PENDING

The MSGFLAG_RN_PENDING flag should be cleared in PR_MESSAGE_FLAGS and no read report should be sent.

GENERATE_RECEIPT_ONLY

A read report should be sent if one is pending, but there should be no change in the state of the MSGFLAG_READ flag.

MAPI_DEFERRED_ERRORS

Allows SetReadFlags to return successfully, possibly before the operation has completed.

MESSAGE_DIALOG

Displays a progress indicator while the operation proceeds.

SUPPRESS_RECEIPT

A pending read report should be canceled if a read report had been requested and this call changes the state of the message from unread to read. If this call does not change the state of the message, the message store provider can ignore this flag.

Return Values

S_OK

The read flag for the specified message or messages was successfully set or cleared.

MAPI_E_NO_SUPPRESS

The message store provider does not support the suppression of read reports.

MAPI_E_INVALID_PARAMETER

One of the following combinations of flags is set in the ulFlags parameter:

•	SUPPRESS_RECEIPT | CLEAR_READ_FLAG

•	SUPPRESS_RECEIPT | CLEAR_READ_FLAG | GENERATE_RECEIPT_ONLY

•	CLEAR_READ_FLAG | GENERATE_RECEIPT_ONLY

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but not all of the messages were successfully processed. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPIFolder::SetReadFlags method sets or clears the MSGFLAG_READ flag in the PR_MESSAGE_FLAGS property of one or more of the folder’s messages. Setting the MSGFLAG_READ flag marks a message as having been read, which does not necessarily indicate that the intended recipient has actually read the message.

SetReadFlags also manages the sending of read reports.

The read flag cannot be altered for:

•	Messages that do not exist.

•	Messages that have been moved elsewhere.

•	Messages that are open with read/write access.

•	Messages that are currently submitted.

Notes to Implementers

You can choose not to support the sending of read reports and the request to suppress read reports. To avoid suppressing a read report, return MAPI_E_NO_SUPPRESS when SetReadFlags is called with SUPPRESS_RECEIPT set in ulFlags.

When lpMsgList points to more than one message, perform the operation as completely as possible for each message. Do not stop the operation prematurely unless a failure occurs that is beyond your control, such as running out of memory, running out of disk space, or corruption in the message store.

If none of the flags is set in the ulFlags parameter, the following rules apply:

•	If MSGFLAG_READ is already set, do nothing.

•	If MSGFLAG_READ is not set, set it immediately and send any pending read reports if the PR_READ_RECEIPT_REQUESTED property is set.

When the SUPPRESS_RECEIPT flag is set:

•	If MSGFLAG_READ is already set, do nothing.

•	If MSGFLAG_READ is not set, set it and cancel any pending read reports.

When the CLEAR_READ_FLAG flag is set, clear the MSGFLAG_READ flag in each message’s PR_MESSAGE_FLAGS property and do not send any read reports.

When the GENERATE_RECEIPT_ONLY flag is set, send any pending read reports. Do not set or clear MSGFLAG_READ.

When both the SUPPRESS_RECEIPT and GENERATE_RECEIPT_ONLY flags are set, set the PR_READ_RECEIPT_REQUESTED to FALSE if it is set and do not send a read report.

Notes to Callers

Expect these return values under the following conditions:

Condition	Return value
SetReadFlags has successfully processed every message.	S_OK
SetReadFlags was unable to successfully process every message.	MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND
SetReadFlags was unable to complete.	Any error value except MAPI_E_NOT_FOUND
When SetReadFlags is unable to complete, do not assume that no work was done. SetReadFlags might have been able to set or clear the MSGFLAG_READ flag for one or more of the messages before encountering the error.

See Also

IMessage::SetReadFlag, PR_MESSAGE_FLAGS


IMAPIForm : IUnknown

The IMAPIForm interface is implemented by form servers for the benefit of form viewers. Its methods are used to work with form view contexts and form notification, to perform form verbs, and to shut down forms.

Quick Info

Header file:	MAPIFORM.H
Exposed by:	Form objects
Implemented by:	Form servers
Called by:	Form viewers
Corresponding pointer type:	LPMAPIFORM
Vtable Order

SetViewContext	Sets a form view context as the current view context for a form.
GetViewContext	Returns the current view context for a form.
ShutdownForm	Closes a form.
DoVerb	Requests a form object perform one of its verbs.
Advise	Registers a form viewer for notifications about changes to a form.
Unadvise	Removes a form viewer’s registration for notification of form object changes previously established with a call to the IMAPIForm::Advise method.


IMAPIForm::Advise

The IMAPIForm::Advise method registers a form viewer for notifications about changes to a form.

Quick Info

See IMAPIForm : IUnknown.

HRESULT Advise(

LPMAPIVIEWADVISESINK pAdvise,
ULONG FAR * pulConnection
)
Parameters

pAdvise

[in] Pointer to the view advise sink object to be called when an event occurs for the form object about which notification has been requested.

pulConnection

[out] Pointer to a variable that upon a successful return holds the connection number for the notification registration. The connection number must be nonzero.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IMAPIForm::Advise method to register for notification callbacks when changes occur to a form. A form server’s implementation of Advise keeps a copy of the pointer to the view advise sink object passed in the pAdvise parameter and uses this pointer in its notification callbacks. The Advise implementation should call the IUnknown::AddRef method on the view advise sink object to retain this pointer to the advise sink until notification registration is canceled. The Advise implementation should also assign a nonzero connection number to the notification registration and call AddRef on this number before returning it in the pulConnection parameter.

To cancel a notification registration, a form viewer calls the IMAPIForm::Unadvise method. During the call to Unadvise, or shortly thereafter, the saved pointer to the view advise sink object is released.

For more information on the notification process, see Event Notification in MAPI.

See Also

IMAPIForm::Unadvise, IMAPIViewAdviseSink : IUnknown


IMAPIForm::DoVerb

The IMAPIForm::DoVerb method requests a form object perform one of its verbs.

Quick Info

See IMAPIForm : IUnknown.

HRESULT DoVerb(

LONG iVerb,
LPMAPIVIEWCONTEXT lpViewContext,
ULONG hwndParent,
LPCRECT lprcPosRect
)
Parameters

iVerb

[in] Number of the verb to be performed.

lpViewContext

[in] Pointer to a view context object. The lpViewContext parameter can be NULL.

hwndParent

[in] Handle of the parent window for any dialog boxes or windows this method displays. The hwndParent parameter should be NULL if the dialog box or window is not modal.

lprcPosRect

[in] Pointer to a Win32 RECT structure containing the current form’s window size and position.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

OLEOBJ_S_CANNOT_DOVERB_NOW

The verb is valid, but the object cannot perform the operation now.

Remarks

Form viewers call the IMAPIForm::DoVerb method to request an object to perform one of its verbs. Typical form server implementations of DoVerb contain a switch statement that tests the valid values for the iVerb parameter.

If a view context is passed in the lpViewContext parameter, the form must use this view context for the duration of the verb processing rather than the view context passed in an earlier call to the IMAPIForm::SetViewContext method. The view context should not be saved.

Some verbs, such as Print, should be modal with respect to the DoVerb call — that is, the indicated operation must be finished before the DoVerb call returns. Nonmodal verbs can be made to act as modal verbs by passing in a view context object in lpViewContext for which a call to the IMAPIViewContext::GetViewStatus method returns the VCSTATUS_MODAL flag.

The handle in hwndParent usually remains valid throughout the DoVerb call, but because it can be destroyed immediately upon the call’s return, forms should not save the handle.

To obtain the RECT structure used by a form’s window, call the Windows GetWindowRect function.

See Also

IMAPIForm::SetViewContext, IMAPIViewContext::GetViewStatus


IMAPIForm::GetViewContext

The IMAPIForm::GetViewContext method returns the current view context for a form.

Quick Info

See IMAPIForm : IUnknown.

HRESULT GetViewContext(

LPMAPIVIEWCONTEXT FAR * ppViewContext
)
Parameters

ppViewContext

[out] Pointer to a pointer to the view context object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

S_FALSE

The form object doesn’t have a view context.

Remarks

The view context object returned from the GetViewContext method is the one obtained by the form object from the preceeding call to IMAPIForm::SetViewContext. If no client application has previously called SetViewContext, this method should return NULL in ppViewContext.

See Also

IMAPIForm::SetViewContext, IMAPIViewContext : IUnknown


IMAPIForm::SetViewContext

The IMAPIForm::SetViewContext method sets a form view context as the current view context for a form.

Quick Info

See IMAPIForm : IUnknown.

HRESULT SetViewContext(

LPMAPIVIEWCONTEXT pViewContext
)
Parameters

pViewContext

[in] Pointer to the view context object to set as current.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IMAPIForm::SetViewContext method to set a particular form view context as current. A typical implementation of SetViewContext sets up a view advise sink object by calling the IMAPIViewContext::SetAdviseSink method, so that notifications can be received for the view context, and calls the IMAPIViewContext::GetViewStatus method for the view context to set as current to determine which status flags have been set.

A form can have only one view context at a time. If a previous view context exists, the implementation must call IMAPIViewContext::SetAdviseSink, passing in NULL in the pmnvs parameter, before returning from the SetViewContext call.

The SetViewContext implementation can also perform other actions based on the GetViewStatus flags returned. For example, if the VCSTATUS_NEXT and VCSTATUS_PREV flags are set, the implementation can enable Next and Previous buttons for the view context that it sets as current.

See Also

IMAPIViewContext::GetViewStatus, IMAPIViewContext::SetAdviseSink


IMAPIForm::ShutdownForm

The IMAPIForm::ShutdownForm method closes a form.

Quick Info

See IMAPIForm : IUnknown.

HRESULT Close(

ULONG ulSaveOptions
)
Parameters

ulSaveOptions

[in] Value that controls how or whether a form’s contents are saved when the form is closed. One of the following values can be set:

SAVEOPTS_NOSAVE

Form data should not be saved.

SAVEOPTS_PROMPTSAVE

Prompts the user to save data related to the form if the form has changed.

SAVEOPTS_SAVEIFDIRTY

Data related to the form should be saved if the form has changed. If no user interface is being displayed, the form can optionally switch to using the functionality for the SAVEOPTS_NOSAVE option.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IMAPIForm::ShutdownForm method to close a form object.

A typical form server’s implementation of ShutdownForm:

1.	Calls the IUnknown::AddRef method for the form’s IPersistMessage object so it isn’t released before processing is finished.

2.	Handles saving form data as indicated by the flag set in the ulSaveOptions parameter.

3.	Destroys the form’s window.

4.	Releases the form’s subobjects.

5.	Calls the IMAPIViewAdviseSink::OnShutdown method to update notifications.

6.	Calls the IMAPIViewContext::SetAdviseSink method, setting the advise sink pointer to NULL.

7.	Calls the MAPIFreeBuffer function to release the form’s properties.

8.	Releases the IPersistMessage object for which it added a reference in Step 1.

9.	Releases all IMAPIMessageSite interfaces and interfaces relating to the form viewer.

10.	Returns S_OK.

Form viewers can ignore errors returned by ShutdownForm and release the form interface after making the call.

See Also

IMAPIViewAdviseSink::OnShutdown


IMAPIForm::Unadvise

The IMAPIForm::Unadvise method removes a form viewer’s registration for notification of form object changes previously established with a call to the IMAPIForm::Advise method.

Quick Info

See IMAPIForm : IUnknown.

HRESULT Unadvise(

ULONG ulConnection
)
Parameters

ulConnection

[in] Number of the registration connection returned by a call to the IMAPIForm::Advise method.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IMAPIForm::Unadvise method to release the pointer to the view advise sink object passed in the pAdvise parameter in the previous call to IMAPIForm::Advise, thereby canceling a notification registration. As part of discarding the pointer to the view advise sink, the view advise sink’s IUnknown::Release method is called. Generally, Release is called during the Unadvise call, but if another thread is in the process of calling one of the IMAPIViewAdviseSink methods for the view advise sink object, the Release call is delayed until the method call returns.

See Also

IMAPIForm::Advise, IMAPIViewAdviseSink : IUnknown


IMAPIFormAdviseSink : IUnknown

The IMAPIFormAdviseSink interface is implemented by form servers to receive notifications from form viewers. Since it is implemented by form servers, IMAPIFormAdviseSink is not an interface for form objects. Thus, client applications should not attempt to use the QueryInterface method on a form object to obtain a pointer to this interface. Form servers call the IMAPIViewContext::SetAdviseSink method to provide an IMAPIFormAdviseSink interface to the application providing the view context.

Quick Info

Header file:	MAPIFORM.H
Exposed by:	Form advise sink objects
Implemented by:	Form servers
Called by:	Form viewers
Corresponding pointer type:	LPMAPIFORMADVISESINK
Vtable Order

OnChange	Notifies a form object about a change in a form viewer’s status.
OnActivateNext	Identifies whether the current form object can handle the message class of the next message to display.


IMAPIFormAdviseSink::OnActivateNext

The IMAPIFormAdviseSink::OnActivateNext method identifies whether the current form object can handle the message class of the next message to display.

Quick Info

See IMAPIFormAdviseSink : IUnknown.

HRESULT OnActivateNext(

LPCSTR lpszMessageClass,
ULONG ulMessageStatus,
ULONG ulMessageFlags,
LPPERSISTMESSAGE FAR * ppPersistMessage
)
Parameters

lpszMessageClass

[in] Pointer to a string naming the message class of the next message.

ulMessageStatus

[in] Bitmask of client-defined or provider-defined flags — copied from the PR_MSG_STATUS property of the next message to display — that provides information on the state of the message.

ulMessageFlags

[in] Pointer to a bitmask of flags — copied from the PR_MESSAGE_FLAGS property of the next message to display — that indicates the current state of the message.

ppPersistMessage

[out] Pointer to a pointer to the form object used for the new form, if a new form is required. A pointer to NULL can be returned if the current form object can be used to display the next message.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

S_FALSE

The form does not handle the message class.

Remarks

Form viewers call the IMAPIFormAdviseSink::OnActivateNext method to find out if the message class of a message can be handled by the current form object. The form object should return S_OK and NULL in the ppPersistMessage parameter if it can handle the message class. If it cannot, it should return S_FALSE.

If the form object can activate message classes other than the base class or the currently loaded class, it should return S_OK and a pointer to an implementation of the IPersistMessage interface the message class in the ppPersistMessage parameter. The message in question is then loaded by the form viewer using the IPersistMessage::Load method of that object.

See Also

IPersistMessage::Load


IMAPIFormAdviseSink::OnChange

The IMAPIFormAdviseSink::OnChange method notifies a form object about a change in a form viewer’s status.

Quick Info

See IMAPIFormAdviseSink : IUnknown.

HRESULT OnChange(

ULONG ulDir
)
Parameters

ulDir

[in] Bitmask of flags that controls handling changes to the form viewer’s status. The following flags can be set:

VCSTATUS_INTERACTIVE

The form should display a user interface. If this flag is not set, the form should suppress displaying a user interface even in response to a verb that usually causes a user interface to be displayed.

VCSTATUS_MODAL

The form is to be modal to the form viewer.

VCSTATUS_NEXT

There is a next message in the form viewer.

VCSTATUS_PREV

There is a previous message in the form viewer.

VCSTATUS_READONLY

Delete, submit, and move operations should be disabled.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IMAPIFormAdviseSink::OnChange method to notify the form object about a change in a viewer’s status. Usually, the only change is setting or clearing the VCSTATUS_NEXT or VCSTATUS_PREVIOUS flag based on the presence or absence of a next or previous message in the viewer. The form object then enables or disables any next or previous actions it supports accordingly.

The settings of VCSTATUS_MODAL and VCSTATUS_INTERACTIVE cannot change in a view context once it has been created.

See Also

IMAPIViewContext::ActivateNext


IMAPIFormContainer : IUnknown

The IMAPIFormContainer interface creates and manages form libraries within folders. This interface is used to create application-specific form libraries.

Quick Info

Header file:	MAPIFORM.H
Exposed by:	Form container objects
Implemented by:	Form library providers
Called by:	Client applications
Corresponding pointer type:	LPMAPIFORMCONTAINER
Vtable Order

InstallForm	Installs a form into a form container.
RemoveForm	Removes a particular form from a form container.
ResolveMessageClass	Resolves a message class to its form within a form container and returns a form information object for that form.
ResolveMultipleMessageClasses	Resolves a group of message classes to their forms within a form container and returns an array of form information objects for those forms.
CalcFormPropSet	Returns an array of the properties used by all forms installed within a form container.
GetDisplay	Returns the display name of a form container.


IMAPIFormContainer::CalcFormPropSet

The IMAPIFormContainer::CalcFormPropSet method returns an array of the properties used by all forms installed within a form container.

Quick Info

See IMAPIFormContainer : IUnknown.

HRESULT CalcFormPropSet(

ULONG ulFlags,
LPMAPIFORMPROPARRAY FAR * ppResults
)
Parameters

ulFlags

[in] Bitmask of flags that controls how the property array in the ppResults parameter is returned. The following flags can be set:

FORMPROPSET_INTERSECTION

The returned array contains the intersection of the forms’ properties.

FORMPROPSET_UNION

The returned array contains the union of the forms’ properties.

MAPI_UNICODE

The strings returned in the array are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

ppResults

[out] Pointer to a pointer to the returned SMAPIFormPropArray structure. This structure contains all properties used by the installed forms.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

Remarks

Client applications call the IMAPIFormContainer::CalcFormPropSet method to obtain an array of properties used by all forms installed within a form container. CalcFormPropSet works like the IMAPIFormMgr::CalcFormPropSet method, except that it operates on every form registered in a particular container.

Notes to Callers

CalcFormPropSet either takes an intersection or a union of these forms’ property sets, depending on the flag set in the ulFlags parameter, and it returns an SMAPIFormPropArray structure containing the resulting group of properties.

If a client passes the MAPI_UNICODE flag in ulFlags, all strings returned are Unicode.

Notes to Implementers

Form library providers that do not support Unicode strings should return MAPI_E_BAD_CHARWIDTH if MAPI_UNICODE is passed.

See Also

IMAPIFormMgr::CalcFormPropSet, SMAPIFormPropArray


IMAPIFormContainer::GetDisplay

The IMAPIFormContainer::GetDisplay method returns the display name of a form container.

Quick Info

See IMAPIFormContainer : IUnknown.

HRESULT GetDisplay(

ULONG ulFlags,
LPTSTR FAR * pszDisplayName
)
Parameters

ulFlags

[in] Bitmask of flags that controls the type of the returned string. The following flag can be set:

MAPI_UNICODE

The returned string is in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

pszDisplayName

[out] Pointer to a string containing the display name of the form container.

Return Values

S_OK

The call succeeded and has returned the expected value or values.


IMAPIFormContainer::InstallForm

The IMAPIFormContainer::InstallForm method installs a form into a form container.

Quick Info

See IMAPIFormContainer : IUnknown.

HRESULT InstallForm(

ULONG ulUIParam,
ULONG ulFlags,
LPCTSTR szCfgPathName
)
Parameters

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays. The ulUIParam parameter is ignored unless the client application sets the MAPI_DIALOG flag in the ulFlags parameter. The ulUIParam parameter can be NULL if MAPI_DIALOG is not also passed.

ulFlags

[in] Bitmask of flags that controls the installation of the form. The following flags can be set:

MAPI_DIALOG

Displays a dialog box to provide progress information or prompt the user for additional information. If this flag is not set, no dialog box is displayed.

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

MAPIFORM_INSTALL_OVERWRITEONCONFLICT

A previous definition of the form is to be replaced with the definition of the form being installed. This flag is ignored when MAPI_DIALOG is present.

szCfgPathName

[in] Path to the form configuration file that describes the form and its implementation.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_EXTENDED_ERROR

An implementation error occurred; to get the MAPIERROR structure associated with the error, call the IMAPIFormContainer::GetLastError method.

MAPI_E_USER_CANCEL

The user canceled the installation of the form, typically by clicking the Cancel button in a dialog box.

Notes to Callers

Client applications call the IMAPIFormContainer::InstallForm method to install a form into a specific form container. The szCfgPathName parameter must contain the path of a form configuration file — that is, a file with the .CFG extension — that describes the form and its implementation. The ulFlags parameter specifies:

•	That a user interface enabling the user installing the form to specify details of installation is displayed, if the MAPI_DIALOG flag is set.

•	That the previous form definition is overlaid with the form being installed, if the MAPIFORM_INSTALL_OVERWRITEONCONFLICT flag is set. Otherwise, the form installation is merged with the current form description, if one exists.

•	That MAPIFORM_INSTALL_OVERWRITEONCONFLICT is ignored when MAPI_DIALOG is present.

•	That the absence of MAPIFORM_INSTALL_OVERWRITEONCONFLICT in the flag set means that a merge will be done. Any new platforms in the .CFG file not currently present in the form description will be installed and no other changes will take place.

•	That the path to the form configuration file is a Unicode string, if the MAPI_UNICODE flag is set.

Clients should call IMAPIFormContainer::GetLastError if InstallForm returns MAPI_E_EXTENDED_ERROR and should check the returned MAPIERROR structure to determine the condition causing the error.

Notes to Implementers

Form library providers should fill in a MAPIERROR structure and return MAPI_E_EXTENDED_ERROR if any of the following conditions occur:

•	The configuration file is not found.

•	The configuration file is not readable.

•	The configuration file is invalid.


IMAPIFormContainer::RemoveForm

The IMAPIFormContainer::RemoveForm method removes a particular form from a form container.

Quick Info

See IMAPIFormContainer : IUnknown.

HRESULT RemoveForm(

LPCSTR szMessageClass
)
Parameters

szMessageClass

[in] String naming the message class of the form to be removed from the form container. Message class names are always ANSI strings, never Unicode.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NOT_FOUND

The message class passed in the szMessageClass parameter does not match the message class for any form in the form container.


IMAPIFormContainer::ResolveMessageClass

The IMAPIFormContainer::ResolveMessageClass method resolves a message class to its form within a form container and returns a form information object for that form.

Quick Info

See IMAPIFormContainer : IUnknown.

HRESULT ResolveMessageClass(

LPCSTR szMessageClass,
ULONG ulFlags,
LPMAPIFORMINFO FAR * ppforminfo
)
Parameters

szMessageClass

[in] String naming the message class being resolved. Message class names are always ANSI strings, never Unicode.

ulFlags

[in] Bitmask of flags that controls how the message class is resolved. The following flag can be set:

MAPIFORM_EXACTMATCH

Only message class strings that are an exact match should be resolved.

ppforminfo

[out] Pointer to a pointer to the returned form information object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NOT_FOUND

The message class passed in the szMessageClass parameter does not match the message class for any form in the form container.

Remarks

Client applications call the IMAPIFormContainer::ResolveMessageClass method to resolve a message class to a form within a form container. The form information object returned in the ppforminfo parameter provides further access to the properties of the form with the given message class.

Notes to Callers

To resolve a message class to a form, pass in the name of the message class to be resolved, for example IPM.HelpDesk.Software. To force the resolution to be exact — that is, to prevent resolution to a superclass of the message class — the MAPIFORM_EXACTMATCH flag can be passed in the ulFlags parameter.

The class identifier for the resolved message class is returned as part of the form information object. Do not assume that the class identifier exists in the OLE library until after calling either the IMAPIFormMgr::PrepareForm method or the IMAPIFormMgr::CreateForm method.

See Also

IMAPIFormInfo : IMAPIProp, IMAPIFormMgr::CreateForm, IMAPIFormMgr::PrepareForm


IMAPIFormContainer::ResolveMultipleMessageClasses

The IMAPIFormContainer::ResolveMultipleMessageClasses method resolves a group of message classes to their forms within a form container and returns an array of form information objects for those forms.

Quick Info

See IMAPIFormContainer : IUnknown.

HRESULT ResolveMultipleMessageClasses (

LPSMESSAGECLASSARRAY pMsgClassArray,
ULONG ulFlags,
LPSMAPIFORMINFOARRAY FAR * ppfrminfoarray
)
Parameters

pMsgClassArray

[in] Pointer to an array containing the names of the message classes to resolve. Message class names are always ANSI strings, never Unicode.

ulFlags

[in] Bitmask of flags that controls how the message classes are resolved. The following flag can be set:

MAPIFORM_EXACTMATCH

Only message class strings that are an exact match should be resolved.

ppfrminfoarray

[out] Pointer to a pointer to an array of form information objects. If a client application passes NULL in the pMsgClassArray parameter, the ppfrminfoarray parameter contains form information objects for all forms in the container.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Client applications call the IMAPIFormContainer::ResolveMultipleMessageClasses method to resolve a group of message classes to forms within a form container. The array of form information objects returned in the ppfrminfoarray parameter provides further access to each of the forms’ properties.

Notes to Callers

To resolve a group of message classes to forms, pass in an array of message class names to be resolved. To force the resolution to be exact — that is, to prevent resolution to a superclass of the message class — the MAPIFORM_EXACTMATCH flag can be passed in the ulFlags parameter.

If a message class cannot be resolved to a form, NULL is returned for that message class in the form information array. Therefore, even if the method returns S_OK, do not assume that all message classes have been successfully resolved. Instead, check the values in the returned array.

See Also

IMAPIFormContainer::ResolveMessageClass


IMAPIFormFactory : IUnknown

The IMAPIFormFactory interface supports the use of configurable run-time forms in distributed computing environments. This interface is based on the OLE IClassFactory interface, and objects implementing IMAPIFormFactory should also inherit from IClassFactory. For more information on IClassFactory, see the OLE Programmer’s Reference.

Quick Info

Header file:	MAPIFORM.H
Exposed by:	Form factory objects
Implemented by:	Form servers
Called by:	Form viewers
Corresponding pointer type:	LPMAPIFORMFACTORY
Vtable Order

CreateClassFactory	Returns a class factory object for a form.
LockServer	Keeps an open form server in memory.


IMAPIFormFactory::CreateClassFactory

The IMAPIFormFactory::CreateClassFactory method returns a class factory object for a form.

Quick Info

See IMAPIFormFactory : IUnknown.

HRESULT CreateClassFactory(

REFCLSID clsidForm,
ULONG ulFlags,
LPCLASSFACTORY FAR * lppClassFactory
)
Parameters

clsidForm

[in] Message class identifier of the form for which to create the class factory.

ulFlags

Reserved; must be zero.

lppClassFactory

[out] Pointer to the returned class factory object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IMAPIFormFactory::CreateClassFactory method to obtain a class factory for a specific form from a form run-time package. CreateClassFactory can return the same object for CreateClassFactory on multiple calls for the same message class identifier; creating a new instance is not required. The class factory returned is used to generate a new instance of the form.


IMAPIFormFactory::LockServer

The IMAPIFormFactory::LockServer method keeps an open form server in memory.

Quick Info

See IMAPIFormFactory : IUnknown.

HRESULT LockServer(

ULONG ulFlags,
ULONG fLockServer
)
Parameters

ulFlags

Reserved; must be zero.

fLockServer

[in] Variable set to TRUE if the lock count is to be incremented, and FALSE otherwise.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IMAPIFormFactory::LockServer method to keep an open form server application in memory. Keeping the form server in memory improves its performance when form objects are created and released frequently.


IMAPIFormInfo : IMAPIProp

The IMAPIFormInfo interface gives client applications access to useful properties particular to form definition. By keeping form information in a separate object, the form library provider can describe a form to a client without activating the form.

Unlike most interfaces defined in the MAPIFORM.H header file, IMAPIFormInfo inherits from the IMAPIProp interface, as it exports most form information through calls to the IMAPIProp::GetProps method.

Quick Info

Header file:	MAPIFORM.H
Exposed by:	Form information objects
Implemented by:	Form library providers
Called by:	Client applications
Corresponding pointer type:	LPMAPIFORMINFO
Transaction model:	Non-transacted
Vtable Order

CalcFormPropSet	Returns a pointer to the complete set of properties used by a form.
CalcVerbSet	Returns a pointer to the complete set of verbs used by a form.
MakeIconFromBinary	Builds an icon from an icon property of a form.
SaveForm	Saves a description of a particular form in a configuration file.
OpenFormContainer	Returns a pointer to the form container in which a particular form is installed.


IMAPIFormInfo::CalcFormPropSet

The IMAPIFormInfo::CalcFormPropSet method returns a pointer to the complete set of properties used by a form.

Quick Info

See IMAPIFormInfo : IMAPIProp.

HRESULT CalcFormPropSet (

ULONG ulFlags,
LPMAPIFORMPROPARRAY FAR * ppFormPropArray
)
Parameters

ulFlags

[in] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

ppFormPropArray

[out] Pointer to a pointer to the returned SMAPIFormPropArray structure.

Return Values

S_OK

The call succeeded and has returned the expected value or values.


IMAPIFormInfo::CalcVerbSet

The IMAPIFormInfo::CalcVerbSet method returns a pointer to the complete set of verbs used by a form.

Quick Info

See IMAPIFormInfo : IMAPIProp.

HRESULT CalcVerbSet(

ULONG ulFlags,
LPMAPIVERBARRAY FAR * ppMAPIVerbArray
)
Parameters

ulFlags

[in] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

ppMAPIVerbArray

[out] Pointer to a pointer to the returned SMAPIVerbArray structure containing the form’s verbs.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Client applications call the IMAPIFormInfo::CalcVerbSet method to obtain a pointer to the set of verbs used by a form. Within the SMAPIVerbArray structure returned in the ppMAPIVerbArray parameter, the verbs are returned in order of index number; each verb’s index is found in its lVerb member.

See Also

SMAPIVerbArray


IMAPIFormInfo::MakeIconFromBinary

The IMAPIFormInfo::MakeIconFromBinary method builds an icon from an icon property of a form.

Quick Info

See IMAPIFormInfo : IMAPIProp.

HRESULT MakeIconFromBinary(

ULONG nPropID,
HICON FAR * phicon
)
Parameters

nPropID

[in] Property identifier for an icon property.

phicon

[out] Pointer to the returned icon.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Client applications call the IMAPIFormInfo::MakeIconFromBinary method to build an icon from an icon property of a form. In the nPropID parameter, MakeIconFromBinary takes the property identifier of any of the icon properties of a form. Using this property identifier, it builds an icon that can be displayed in table views that include property columns for icons.


IMAPIFormInfo::OpenFormContainer

The IMAPIFormInfo::OpenFormContainer method returns a pointer to the form container in which a particular form is installed.

Quick Info

See IMAPIFormInfo : IMAPIProp.

HRESULT OpenFormContainer (

LPMAPIFORMCONTAINER FAR * ppformcontainer
)
Parameters

ppformcontainer

[out] Pointer to a pointer to the returned form container object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.


IMAPIFormInfo::SaveForm

The IMAPIFormInfo::SaveForm method saves a description of a particular form in a configuration file.

Quick Info

See IMAPIFormInfo : IMAPIProp.

HRESULT SaveForm(

LPCTSTR szFileName
)
Parameters

szFileName

[in] String naming the form descriptor message file where the form description is saved. This filename must have the .FDM extension.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_EXTENDED_ERROR

The configuration file could not be written. To get the MAPIERROR structure associated with the error, call the IMAPIProp::GetLastError method.

MAPI_E_NO_SUPPORT

SaveForm was probably called to save a form in the local form container. SaveForm is not supported on the local form container.

Remarks

Client applications call the IMAPIFormInfo::SaveForm method to save a description of the current form in the file with the given filename. SaveForm creates a configuration file.

Notes to Callers

Forms can be reinstalled by being selected from a list of form descriptor messages in a dialog box displayed by form library providers. The recommended extension for form descriptor messages is .FDM.

Call IMAPIProp::GetLastError if SaveForm returns MAPI_E_EXTENDED_ERROR and check the returned MAPIERROR structure to determine the condition causing the error.


IMAPIFormMgr : IUnknown

The IMAPIFormMgr interface is used by form viewers to get information about and activate form servers.

Quick Info

Header file:	MAPIFORM.H
Exposed by:	Form manager objects
Implemented by:	Form library providers
Called by:	Form viewers
Corresponding pointer type:	LPMAPIFORMMGR
Vtable Order

LoadForm	Launches a form to open an existing message.
ResolveMessageClass	Resolves a message class to its form within a form container and returns a form information object for that form.
ResolveMultipleMessageClasses	Resolves a group of message classes to their forms within a form container and returns an array of form information objects for those forms.
CalcFormPropSet	Returns an array of the properties used by a group of forms.
CreateForm	Launches a form to create a new message based on that form.
SelectForm	Presents a dialog box that enables the user to select a form and returns a form information object describing that form.
SelectMultipleForms	Presents a dialog box that enables the user to select multiple forms and returns an array of form information objects describing those forms.
SelectFormContainer	Presents a dialog box that enables the user to select a form container and returns an interface for the container object the user selected.
OpenFormContainer	Opens an IMAPIFormContainer interface for a specific form container.
PrepareForm	Downloads a form for launching.
IsInConflict	Determines whether a form can handle its own message conflicts.


IMAPIFormMgr::CalcFormPropSet

The IMAPIFormMgr::CalcFormPropSet method returns an array of the properties used by a group of forms.

Quick Info

See IMAPIFormMgr : IUnknown.

HRESULT CalcFormPropSet (

LPSMAPIFORMINFOARRAY pfrminfoarray,
ULONG ulFlags,
LPMAPIFORMPROPARRAY FAR * ppResults
)
Parameters

pfrminfoarray

[in] Pointer to an array of form information objects identifying the forms for which to return properties.

ulFlags

[in] Bitmask of flags that controls how the property array in the ppResults parameter is returned. The following flags can be set:

FORMPROPSET_INTERSECTION

The returned array contains the intersection of the form’s properties.

FORMPROPSET_UNION

The returned array contains the union of the form’s properties.

MAPI_UNICODE

The strings returned in the array are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

ppResults

[out] Pointer to a pointer to the returned SMAPIFormPropArray structure which contains the properties used by the forms.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

Remarks

Form viewers call the IMAPIFormContainer::CalcFormPropSet method to obtain an array of the properties used by a group of forms. CalcFormPropSet either takes an intersection or a union of these forms’ property sets, depending on the flag set in the ulFlags parameter, and it returns an SMAPIFormPropArray structure containing the resulting group of properties.

Notes to Implementers

If a form viewer passes the MAPI_UNICODE flag in the ulFlags parameter, all strings should be returned as Unicode strings. Form library providers that do not support Unicode strings should return MAPI_E_BAD_CHARWIDTH if MAPI_UNICODE is passed.

See Also

SMAPIFormPropArray


IMAPIFormMgr::CreateForm

The IMAPIFormMgr::CreateForm method launches a form to create a new message based on that form.

Quick Info

See IMAPIFormMgr : IUnknown.

HRESULT CreateForm(

ULONG ulUIParam,
ULONG ulFlags,
IMAPIFormInfo pfrminfoToActivate,
REFIID refiidToAsk,
LPVOID FAR * ppvObj
)
Parameters

ulUIParam

[in] Handle to the parent window for the progress indicator displayed while the form is launched. The ulUIParam parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

ulFlags

[in] Bitmask of flags that controls how the form is launched. The following flag can be set:

MAPI_DIALOG

Displays a user interface to provide status or prompt the user for additional information. If this flag is not set, no user interface is displayed.

pfrminfoToActivate

[in] Pointer to the form information object used to launch the form.

refiidToAsk

[in] Pointer to the interface identifier (IID) for the interface to be returned for the form object created. The refiidToAsk parameter must not be NULL.

ppvObj

[out] Pointer to a pointer to the returned interface.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_INTERFACE

The requested interface is not supported by the form object.

Remarks

Form viewers call the IMAPIFormMgr::CreateForm method to launch a form to create a new message based on the form. CreateForm launches the form by creating an instance of the form server for that form as described in the given form information object. If required, CreateForm calls IMAPIFormMgr::PrepareForm to download the form server code to the user’s disk.

The pfrminfoToActivate parameter must point to a form information object that has been correctly resolved.

After the form has been launched, the calling form viewer must set up a message using the IPersistMessage interface and can optionally set up a view context for the form. For more information, see Launching a Form Server.

See Also

IMAPIViewContext : IUnknown, IPersistMessage : IUnknown


IMAPIFormMgr::IsInConflict

The IMAPIFormMgr::IsInConflict method determines whether a form can handle its own message conflicts.

Quick Info

See IMAPIFormMgr : IUnknown.

HRESULT IsInConflict(

ULONG ulMessageFlags,
ULONG ulMessageStatus,
LPCSTR szMessageClass
LPMAPIFOLDER pFolderFocus
)
Parameters

ulMessageFlags

[in] Pointer to a bitmask of flags — copied from the PR_MESSAGE_FLAGS property of a message — that indicates the current state of the message.

ulMessageStatus

[in] Bitmask of client- or provider-defined flags — copied from the PR_MSG_STATUS property of a message — that provides further information on the state of the message.

szMessageClass

[in] String naming the message’s message class.

pFolderFocus

[in] Pointer to the folder that contains the message. The pFolderFocus parameter can be NULL if such a folder doesn’t exist — for example, in a case where the message is embedded in another message.

Return Values

S_OK

The form does not handle its own message conflicts.

S_FALSE

The form handles its own message conflicts, or the message for which information was passed is not in conflict.

Remarks

Form viewers call the IMAPIFormMgr::IsInConflict method to discover if a particular form does not handle its own message conflicts. IsInConflict checks the bitmasks in the ulMessageFlags and ulMessageStatus parameters for the presence of a conflict flag. If a conflict flag is set, IsInConflict resolves the message class passed in the szMessageClass parameter and returns S_OK if the form does not handle its own conflicts. IsInConflict returns S_FALSE if the form handles its own conflicts.

A form that does not handle its own conflicts must be launched using the IMAPIFormMgr::LoadForm method and cannot reuse an existing form object.

See Also

IMAPIFormAdviseSink::OnActivateNext, PR_MESSAGE_FLAGS, PR_MSG_STATUS


IMAPIFormMgr::LoadForm

The IMAPIFormMgr::LoadForm method launches a form to open an existing message.

Quick Info

See IMAPIFormMgr : IUnknown.

HRESULT LoadForm(

ULONG ulUIParam,
ULONG ulFlags,
LPCSTR lpszMessageClass,
ULONG ulMessageStatus,
ULONG ulMessageFlags,
LPMAPIFOLDER pFolderFocus,
LPMAPIMESSAGESITE pMessageSite,
LPMESSAGE pmsg,
LPMAPIVIEWCONTEXT pViewContext,
REFIID riid,
LPVOID FAR * ppvObj
)
Parameters

ulUIParam

[in] Handle of the parent window for the progress indicator displayed while the form is launched. The ulUIParam parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

ulFlags

[in] Bitmask of flags that controls how the form is launched. The following flags can be set:

MAPI_DIALOG

Displays a user interface to provide status or prompt the user for additional information. If this flag is not set, no user interface is displayed.

MAPIFORM_EXACTMATCH

Only message class strings that are an exact match should be resolved.

lpszMessageClass

[in] Pointer to a string naming the message class of the message to be loaded. If NULL is passed in the lpszMessageClass parameter, the message class is determined from the message pointed to by the pmsg parameter.

ulMessageStatus

[in] Bitmask of client- or provider-defined flags — copied from the PR_MSG_STATUS property of the message — that provides information on the state of the message. The ulMessageStatus parameter must be set if lpszMessageClass is non-null; otherwise ulMessageStatus is ignored.

ulMessageFlags

[in] Pointer to a bitmask of flags — copied from the PR_MESSAGE_FLAGS property of the message — that indicates the current state of the message. The ulMessageFlags parameter must be set if lpszMessageClass is non-null; otherwise ulMessageFlags is ignored.

pFolderFocus

[in] Pointer to the folder that directly contains the message. The pFolderFocus parameter can be NULL if such a folder doesn’t exist — for example, if the message is embedded in another message.

pMessageSite

[in] Pointer to the message site of the message.

pmsg

[in] Pointer to the message.

pViewContext

[in] Pointer to the view context for the message. The pViewContext parameter can be NULL.

riid

[in] Interface identifier (IID) of the interface to be used for the returned form object. The refiidToAsk parameter must not be NULL.

ppvObj

[out] Pointer to a pointer to the returned interface.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_INTERFACE

The form does not support the requested interface.

MAPI_E_NOT_FOUND

The message class passed in lpszMessageClass does not match the message class for any form in the form library.

Remarks

Form viewers call the IMAPIFormMgr::LoadForm method to launch a form for an existing message. LoadForm launches the form object, loads the message into the form object, sets up the appropriate view context if necessary, and returns the requested interface for the form object.

The pFolderFocus parameter points to the folder containing the message. If the message is embedded within another message, pFolderFocus should be NULL.

Notes to Implementers

If NULL is passed in lpszMessageClass, then the implementation obtains the message’s message class and its PR_MSG_STATUS and PR_MESSAGE_FLAGS properties. If a message class string is provided in lpszMessageClass, then the implementation must use the values in ulMessageStatus and ulMessageFlags.

See Also

PR_MESSAGE_FLAGS, PR_MSG_STATUS


IMAPIFormMgr::OpenFormContainer

The IMAPIFormMgr::OpenFormContainer method opens an IMAPIFormContainer interface for a specific form container.

Quick Info

See IMAPIFormMgr : IUnknown.

HRESULT OpenFormContainer(

HFRMREG hfrmreg,
LPUNKNOWN lpunk,
LPMAPIFORMCONTAINER FAR * lppfcnt
)
Parameters

hfrmreg

[in] HFRMREG enumeration indicating the form library to open — that is, the form container to open. An HFRMREG enumeration is an enumeration specific to a form library provider. Possible HFRMREG values include:

HFRMREG_DEFAULT

Convenient form container.

HFRMREG_FOLDER

Folder container.

HFRMREG_PERSONAL

Container for the default message store.

HFRMREG_LOCAL

Local form container.

lpunk

[in] Pointer to the object for which the interface is opened. The lpunk parameter must be NULL unless the value for the hfrmreg parameter requires an object pointer.

lppfcnt

[out] Pointer to a pointer to the returned form container object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_INTERFACE

The object pointed to by lpUnk does not support the required interface.

Remarks

Form viewers call the IMAPIFormMgr::OpenFormContainer method to open an IMAPIFormContainer interface for a specific form container. This interface can then be used for installing forms into and removing forms from a form container.

Notes to Callers

If the value in hfrmreg is HFRMREG_FOLDER, which indicates a folder container, the interface identifier used in lpunk must be non-null and must allow QueryInterface calls to an IMAPIFolder interface.

To open the local form container, a call to OpenFormContainer or the MAPIOpenLocalFormContainer function must be used; the IMAPIFormMgr::SelectFormContainer method cannot be used to enable the user to select the local form container.

See Also

IMAPIFormContainer::InstallForm, IMAPIFormMgr::SelectFormContainer, MAPIOpenLocalFormContainer


IMAPIFormMgr::PrepareForm

The IMAPIFormMgr::PrepareForm method downloads a form for launching.

Quick Info

See IMAPIFormMgr : IUnknown.

HRESULT PrepareForm(

ULONG ulUIParam,
ULONG ulFlags,
LPMAPIFORMINFO pfrmiInfo
)
Parameters

ulUIParam

[in] Handle of the parent window for the progress indicator displayed while the form is downloaded. The ulUIParam parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

ulFlags

[in] Bitmask of flags that controls how the form is downloaded. The following flag can be set:

MAPI_DIALOG

Displays a user interface to provide status or prompt the user for additional information. If this flag is not set, no user interface is displayed.

pfrmiInfo

[in] Pointer to a form information object for the form to be downloaded.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IMAPIFormMgr::PrepareForm method to download a form from a form container for launching. Most form viewers do not need to call PrepareForm because both the IMAPIFormMgr::CreateForm and IMAPIFormMgr::LoadForm methods call PrepareForm if necessary.

PrepareForm can be used to obtain the dynamic-link libraries (DLLs) and other files associated with a form to modify them. If the modified form is loaded back into its form container, it must be reinstalled.

See Also

IMAPIFormMgr::CreateForm, IMAPIFormMgr::LoadForm


IMAPIFormMgr::ResolveMessageClass

The IMAPIFormMgr::ResolveMessageClass method resolves a message class to its form within a form container and returns a form information object for that form.

Quick Info

See IMAPIFormMgr : IUnknown.

HRESULT ResolveMessageClass(

LPCSTR szMsgClass,
ULONG ulFlags,
LPMAPIFOLDER pFolderFocus,
LPMAPIFORMINFO FAR * ppResult
)
Parameters

szMsgClass

[in] String naming the message class being resolved.

ulFlags

[in] Bitmask of flags that controls how the message class is resolved. The following flag can be set:

MAPIFORM_EXACTMATCH

Only message class strings that are an exact match should be resolved.

pFolderFocus

[in] Pointer to the folder containing the message being resolved. The pFolderFocus parameter can be NULL.

ppResult

[out] Pointer to a pointer to a returned form information object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NOT_FOUND

The message class passed in the szMsgClass parameter does not match the message class for any form in the form library.

Remarks

Form viewers call the IMAPIFormMgr::ResolveMessageClass method to resolve a message class to its form within a form container. The form information object returned in the ppResult parameter provides further access to the properties of the form with the given message class.

Notes to Callers

To resolve a message class to a form, a form viewer passes in the name of the message class to be resolved, such as “IPM.HelpDesk.Software”.To force the resolution to be exact — that is, to prevent resolution to a superclass of the message class when an exactly matching form server is not available — the MAPIFORM_EXACTMATCH flag can be passed in the ulFlags parameter. If the pFolderFocus parameter is NULL, the message-class resolution process does not search a folder container.

The order of the containers searched depends on the implementation of the form library provider. The default form library provider searches first the local container, then the folder container for the passed-in folder, the personal form container, and finally the organization container.

Message class names are always ANSI strings, never Unicode.

The class identifier for the resolved message class is returned as part of the form information object. A form viewer should not work on the assumption that the class identifier exists in the OLE library until after the form viewer has called either the IMAPIFormMgr::PrepareForm method or the IMAPIFormMgr::CreateForm method.

See Also

IMAPIFormInfo : IMAPIProp, IMAPIFormMgr::CreateForm, IMAPIFormMgr::PrepareForm


IMAPIFormMgr::ResolveMultipleMessageClasses

The IMAPIFormMgr::ResolveMultipleMessageClasses method resolves a group of message classes to their forms within a form container and returns an array of form information objects for those forms.

Quick Info

See IMAPIFormMgr : IUnknown.

HRESULT ResolveMultipleMessageClasses(

LPSMESSAGECLASSARRAY pMsgClasses,
ULONG ulFlags,
LPMAPIFOLDER pFolderFocus,
LPSMAPIFORMINFOARRAY FAR * ppfrminfoarray
)
Parameters

pMsgClasses

[in] Pointer to an array containing the names of the message classes to resolve.

ulFlags

[in] Bitmask of flags that controls how the message classes are resolved. The following flag can be set:

MAPIFORM_EXACTMATCH

Only message class strings that are an exact match should be resolved.

pFolderFocus

[in] Pointer to the folder containing the form whose message class is being resolved. The pFolderFocus parameter can be NULL.

ppfrminfoarray

[out] Pointer to a pointer to an array of form information objects. If a form viewer passes NULL in the pMsgClasses parameter, the ppfrminfoarray parameter contains form information objects for all forms in the container.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IMAPIFormMgr::ResolveMultipleMessageClasses method to resolve a group of message classes to forms within a form container. The array of form information objects returned in ppfrminfoarray provides further access to each of the forms’ properties.

Notes to Callers

To resolve a group of message classes to forms, a form viewer passes in an array of message class names to be resolved. To force the resolution to be exact — that is, to prevent resolution to a superclass of the message class when an exactly matching form server is not available — the MAPIFORM_EXACTMATCH flag can be passed in the ulFlags parameter.

Message class names are always ANSI strings, never Unicode.

If a message class cannot be resolved to a form, NULL is returned for that message class in the form information array. Therefore, even if the method returns S_OK, form viewers should not work on the assumption that all message classes have been successfully resolved. Instead, form viewers should check the values in the returned array.

See Also

IMAPIFormMgr::ResolveMessageClass


IMAPIFormMgr::SelectForm

The IMAPIFormMgr::SelectForm method presents a dialog box that enables the user to select a form and returns a form information object describing that form.

Quick Info

See IMAPIFormMgr : IUnknown.

HRESULT SelectForm(

ULONG ulUIParam,
ULONG ulFlags,
LPCTSTR pszTitle,
LPMAPIFOLDER pfld,
LPMAPIFORMINFO FAR * ppfrminfoReturned
)
Parameters

ulUIParam

[in] Handle of the parent window for the dialog box displayed.

ulFlags

[in] Bitmask of flags that controls the type of the passed-in strings. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

pszTitle

[in] Pointer to a string containing the caption of the dialog box. If the pszTitle parameter is NULL, the form library provider supplies a default caption.

pfld

[in] Pointer to the folder from which to select the form. If the pfld parameter is NULL, the form can be selected from the local, personal, or organization form container.

ppfrminfoReturned

[out] Pointer to a pointer to the returned form information object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in the dialog box.

Remarks

Form viewers call the IMAPIFormMgr::SelectForm method to first present a dialog box that enables the user to select a form and then to retrieve a form information object describing the selected form. The dialog box constrains the user to select a single form.

Notes to Callers

The SelectForm dialog box only displays forms that are not hidden — that is, that have their hidden properties clear. If a form viewer passes the MAPI_UNICODE flag in the ulFlags parameter, all strings are Unicode. Form library providers that do not support Unicode strings should return MAPI_E_BAD_CHARWIDTH if MAPI_UNICODE is passed.


IMAPIFormMgr::SelectMultipleForms

The IMAPIFormMgr::SelectMultipleForms method presents a dialog box that enables the user to select multiple forms and returns an array of form information objects describing those forms.

Quick Info

See IMAPIFormMgr : IUnknown.

HRESULT SelectMultipleForms(

ULONG ulUIParam,
ULONG ulFlags,
LPCTSTR pszTitle,
LPMAPIFOLDER pfld,
LPMAPIFORMINFOARRAY pfrminfoarray,
LPMAPIFORMINFOARRAY FAR * ppfrminfoarray
)
Parameters

ulUIParam

[in] Handle of the parent window for the dialog box displayed.

ulFlags

[in] Bitmask of flags that controls the type of the passed-in strings. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

pszTitle

[in] Pointer to a string containing the caption of the dialog box. If the pszTitle parameter is NULL, the form library provider that provides the forms supplies a default caption.

pfld

[in] Pointer to the folder from which to select the forms. If the pfld parameter is NULL, the forms are selected from the local, personal, or organization form container.

pfrminfoarray

[in] Pointer to an array of form information objects that are preselected for the user.

ppfrminfoarray

[out] Pointer to a pointer to the returned array of form information objects.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in the dialog box.

Remarks

Form viewers call the IMAPIFormMgr::SelectMultipleForms method to first present a dialog box that enables the user to select multiple forms and then to retrieve an array of form information objects describing the selected forms. The SelectMultipleForms dialog box displays all forms, whether or not they are hidden — that is, whether or not their hidden properties are clear.

Notes to Implementers

If a form viewer passes the MAPI_UNICODE flag in the ulFlags parameter, all strings are Unicode. Form library providers that do not support Unicode strings should return MAPI_E_BAD_CHARWIDTH if MAPI_UNICODE is passed.


IMAPIFormMgr::SelectFormContainer

The IMAPIFormMgr::SelectFormContainer method presents a dialog box that enables the user to select a form container and returns an interface for the container object the user selected.

Quick Info

See IMAPIFormMgr : IUnknown.

HRESULT SelectFormContainer(

ULONG ulUIParam,
ULONG ulFlags,
LPMAPIFORMCONTAINER FAR * lppfcnt
)
Parameters

ulUIParam

[in] Handle of the parent window for the dialog box displayed.

ulFlags

[in] Bitmask of flags that controls how the form library is selected — that is, how the form container is selected. The following flags can be set:

MAPIFORM_SELECT_ALL_REGISTRIES

Selection can be made from all containers. This type of selection is the default.

MAPIFORM_SELECT_FOLDER_REGISTRY_ONLY

Selection can be made only from folder containers.

MAPIFORM_SELECT_NON_FOLDER_REGISTRY_ONLY

Selection can be made only from containers not associated with folders.

lppfcnt

[out] Pointer to a pointer to the returned interface. This interface is for the container object selected by the user.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers commonly call the IMAPIFormMgr::SelectFormContainer method to select a form container into which a form is installed. SelectFormContainer cannot be used to select the local form container, which has the value HFRMREG_LOCAL.


IMAPIMessageSite : IUnknown

The IMAPIMessageSite interface manipulates messages and is implemented by the form viewer code that responds to such manipulation.

Quick Info

Header file:	MAPIFORM.H
Exposed by:	Message site objects
Implemented by:	Form viewers
Called by:	Form objects
Corresponding pointer type:	LPMAPIMESSAGESITE
Vtable Order

GetSession	Returns the MAPI session in which the current message was created or opened.
GetStore	Returns the message store containing the current message, if such a store exists.
GetFolder	Returns the folder in which the current message was created or opened, if such a folder exists.
GetMessage	Returns the current message.
GetFormManager	Returns a form manager interface, which a form server can use to launch another form server.
NewMessage	Creates a new message.
CopyMessage	Copies the current message to a folder.
MoveMessage	Moves the current message to a folder.
DeleteMessage	Deletes the current message.
SaveMessage	Requests that the current message be saved.
SubmitMessage	Requests that the current message be submitted to the MAPI spooler.
GetSiteStatus	Returns information from a message site object about the message site’s capabilities for the current message.


IMAPIMessageSite::CopyMessage

The IMAPIMessageSite::CopyMessage method copies the current message to a folder.

Quick Info

See IMAPIMessageSite : IUnknown.

HRESULT CopyMessage(

LPMAPIFOLDER pFolderDestination
)
Parameters

pFolderDestination

[in] Pointer to the folder where the message is copied.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_SUPPORT

The operation is not supported by this message site.

Remarks

Form objects call the IMAPIMessageSite::CopyMessage method to copy the current message to a new folder. CopyMessage does not change the message currently being displayed to the user, and no interface for the newly created message is returned to the form.

Notes to Implementers

A typical implementation of CopyMessage:

1.	Creates the new message the current message is copied to.

2.	Calls the IPersistMessage::Save method with a pointer to the new message in the pMessage parameter and FALSE in the fSameAsLoad parameter.

3.	Calls the IPersistMessage::SaveCompleted method passing NULL for its pMessage parameter.

1. 	Calls the IMAPIProp::SaveChanges method on the new message.

For more information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.

See Also

IMAPIProp::SaveChanges, IPersistMessage::Save, IPersistMessage::SaveCompleted


IMAPIMessageSite::DeleteMessage

The IMAPIMessageSite::DeleteMessage method deletes the current message.

Quick Info

See IMAPIMessageSite : IUnknown.

HRESULT DeleteMessage(

LPMAPIVIEWCONTEXT pViewContext,
LPCRECT prcPosRect
)
Parameters

pViewContext

[in] Pointer to a view context object.

prcPosRect

[in] Pointer to a RECT structure containing the current form’s window size and position. The next form displayed also uses this window rectangle.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_SUPPORT

The operation is not supported by this message site.

Remarks

A form object calls the IMAPIMessageSite::DeleteMessage method to delete the message the form is currently attached to.

Notes to Callers

Following the return of DeleteMessage, form objects must check for a new message and then dismiss themselves if none exists. To determine whether a message DeleteMessage acted on is deleted or moved to a Deleted Items folder, a form object can call the IMAPIMessageSite::GetSiteStatus method and check if the DELETE_IS_MOVE flag was returned.

Notes to Implementers

If a form viewer’s implementation of DeleteMessage moves to the next message after deleting a message, it should call the IMAPIViewContext::ActivateNext method passing the VCDIR_DELETE flag prior to performing the actual deletion. If a form viewer’s implementation of DeleteMessage moves the deleted message, for example to a Deleted Items folder, it must save changes to the message if the message has been modified.

A typical implementation of DeleteMessage:

1.	If moving the message, calls the IPersistMessage::Save method passing NULL for its pMessage parameter and TRUE for its fSameAsLoad parameter.

2.	Calls the IMAPIViewContext::ActivateNext method passing the VCDIR_DELETE flag in its ulDir parameter.

3.	If the ActivateNext call failed, it returns. If ActivateNext returned S_FALSE, it calls the IPersistMessage::HandsOffMessage method.

4.	Deletes or moves the message.

To obtain the RECT structure used by a form’s window, call the Windows GetWindowRect function.

For more information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.

See Also

IMAPIMessageSite::GetSiteStatus, IMAPIViewContext::ActivateNext, IPersistMessage::HandsOffMessage, IPersistMessage::Save


IMAPIMessageSite::GetFolder

The IMAPIMessageSite::GetFolder method returns the folder in which the current message was created or opened, if such a folder exists.

Quick Info

See IMAPIMessageSite : IUnknown.

HRESULT GetFolder(

LPMAPIFOLDER FAR * ppFolder
)
Parameters

ppFolder

[out] Pointer to a pointer to the returned folder.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

S_FALSE

No folder exists for the message.

Remarks

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.


IMAPIMessageSite::GetFormManager

The IMAPIMessageSite::GetFormManager method returns a form manager interface, which a form server can use to launch another form server.

Quick Info

See IMAPIMessageSite : IUnknown.

HRESULT GetFormManager(

LPMAPIFORMMGR FAR * ppFormMgr
)
Parameters

ppFormMgr

[out] Pointer to a pointer to the returned form manager interface.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.


IMAPIMessageSite::GetMessage

The IMAPIMessageSite::GetMessage method returns the current message.

Quick Info

See IMAPIMessageSite : IUnknown.

HRESULT GetMessage(

LPMESSAGE FAR * ppmsg
)
Parameters

ppmsg

[out] Pointer to a pointer to the returned interface for the message.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

S_FALSE

No message currently exists for the calling form.

Remarks

Forms call the IMAPIMessageSite::GetMessage method to obtain a message interface for the current message. The current message is the same message as was previously passed in the IPersistMessage::InitNew, IPersistMessage::Load, or IPersistMessage::SaveCompleted method.

GetMessage returns S_FALSE if no message currently exists. This state can occur after calls to the IPersistMessage::HandsOffMessage method or before the next call to IPersistMessage::Load or IPersistMessage::SaveCompleted is made.

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.

See Also

IPersistMessage : IUnknown


IMAPIMessageSite::GetSession

The IMAPIMessageSite::GetSession method returns the MAPI session in which the current message was created or opened.

Quick Info

See IMAPIMessageSite : IUnknown.

HRESULT GetSession(

LPMAPISESSION FAR * ppSession
)
Parameters

ppSession

[out] Pointer to a pointer to the returned session object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

S_FALSE

No session exists for the current message.

Remarks

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.


IMAPIMessageSite::GetSiteStatus

The IMAPIMessageSite::GetSiteStatus method returns information from a message site object about the message site’s capabilities for the current message.

Quick Info

See IMAPIMessageSite : IUnknown.

HRESULT GetSiteStatus(

ULONG FAR * lpulStatus
)
Parameters

lpulStatus

[out] Pointer to a bitmask of flags giving information on message status. The following flags can be set:

VCSTATUS_COPY

The message can be copied.

VCSTATUS_DELETE

The message can be deleted.

VCSTATUS_DELETE_IS_MOVE

The message is actually moved to a Deleted Items folder when deleted, rather than being immediately removed from its message store.

VCSTATUS_MOVE

The message can be moved.

VCSTATUS_NEW_MESSAGE

A new message can be created.

VCSTATUS_SAVE

The message can be saved.

VCSTATUS_SUBMIT

The message can be submitted.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form objects call the IMAPIMessageSite::GetSiteStatus method to obtain the message site object’s capabilities for the current message. The flags returned in the lpulStatus parameter provide information on the message site; typically, a form enables or disables menu commands based on information the flags provide on the capabilities of the message site implementation. If a new message is loaded into a form by the IPersistMessage::SaveCompleted method or the IPersistMessage::Load method, the status flags must be checked. Some message site objects, particularly read-only ones, do not permit messages to be saved or deleted.

Notes to Implementers

IMAPIMessageSite::GetSiteStatus may require your client application to do some calculation to determine what operations can and can’t be performed on the current message. Typically, that involves looking at the status row for the current message’s message store provider, or querying the store provider directly to determine which actions the client application can perform using the message store. For example, determining whether to return the MAPI_DELETE_IS_MOVE flag could be done by checking the message store object’s PR_IPM_WASTEBASKET_ENTRYID property to see whether there is a Deleted Items folder in the message store.

For more information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.

See Also

IPersistMessage::Load, IPersistMessage::SaveCompleted


IMAPIMessageSite::GetStore

The IMAPIMessageSite::GetStore method returns the message store containing the current message, if such a store exists.

Quick Info

See IMAPIMessageSite : IUnknown.

HRESULT GetStore(

LPMDB FAR * ppStore
)
Parameters

ppStore

[out] Pointer to a pointer to the message store.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

S_FALSE

There is no store containing the message.

Remarks

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.


IMAPIMessageSite::MoveMessage

The IMAPIMessageSite::MoveMessage method moves the current message to a folder.

Quick Info

See IMAPIMessageSite : IUnknown.

HRESULT MoveMessage(

LPFOLDER pFolderDestination,
LPMAPIVIEWCONTEXT pViewContext,
LPCRECT prcPosRect
)
Parameters

pFolderDestination

[in] Pointer to the folder where the message is moved.

pViewContext

[in] Pointer to a view context object.

prcPosRect

[in] Pointer to a RECT structure containing the current form’s window size and position. The next form displayed also uses this window rectangle.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_SUPPORT

The operation is not supported by this message site.

Remarks

Form objects call the IMAPIMessageSite::MoveMessage method to move the current message to a new folder.

Notes to Implementers

A form viewer’s implementation of MoveMessage must call the IMAPIViewContext::ActivateNext method, passing the VCDIR_MOVE flag, prior to actually moving the message to a new folder. To obtain the RECT structure used by a form’s window, call the Windows GetWindowRect function.

For more information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.

Notes to Callers

Following the return of MoveMessage, forms must check for a current message and then dismiss themselves if none exists.

See Also

IMAPIViewContext::ActivateNext


IMAPIMessageSite::NewMessage

The IMAPIMessageSite::NewMessage method creates a new message.

Quick Info

See IMAPIMessageSite : IUnknown.

HRESULT NewMessage(

ULONG fComposeInFolder,
LPMAPIFOLDER pFolderFocus,
LPPERSISTMESSAGE pPersistMessage,
LPMESSAGE FAR * ppMessage,
LPMAPIMESSAGESITE FAR * ppMessageSite,
LPMAPIVIEWCONTEXT FAR * ppViewContext
)
Parameters

fComposeInFolder

[in] Variable indicating in which folder the message should be composed. If the variable is FALSE, the pFolderFocus parameter is ignored and the form viewer can compose the message in any folder. If the variable is TRUE and NULL is passed in pFolderFocus, the message is composed in the current folder. If the variable is TRUE and a non-null value is passed in pFolderFocus, the message is composed in the folder pointed to by pFolderFocus.

pFolderFocus

[in] Pointer to the folder where the new message is created.

pPersistMessage

[in] Pointer to the form object for the new form.

ppMessage

[out] Pointer to a pointer to the new message.

ppMessageSite

[out] Pointer to a pointer to a message site object for the new message.

ppViewContext

[out] Pointer to a pointer to a view context appropriate for passing to a new form with the new message. If the form implements its own view context, NULL can be passed in the ppViewContext parameter.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form objects call the IMAPIMessageSite::NewMessage method to create a new message. The form uses NewMessage to get a new message and the associated message site from its view. It can then modify the new message and either aggregate the message site or use its message site directly.

An associated view context can also be obtained by passing in a non-null value in the ppViewContext parameter. This view context can be used directly, or it can be aggregated and passed to the new message. If a complete implementation is required, NULL should be passed in ppViewContext.

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.

See Also

IMAPIViewContext : IUnknown


IMAPIMessageSite::SaveMessage

The IMAPIMessageSite::SaveMessage method requests that the current message be saved.

Quick Info

See IMAPIMessageSite : IUnknown.

HRESULT SaveMessage()

Parameters

None.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Forms call the IMAPIMessageSite::SaveMessage method to request that a message be saved. After being saved, the message generates the usual form object behavior.

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.


IMAPIMessageSite::SubmitMessage

The IMAPIMessageSite::SubmitMessage method requests that the current message be submitted to the MAPI spooler.

Quick Info

See IMAPIMessageSite : IUnknown.

HRESULT SubmitMessage(

ULONG ulFlags
)
Parameters

ulFlags

[in] Bitmask of flags that controls how a message is submitted. The following flag can be set:

FORCE_SUBMIT

MAPI should submit the message even if it might not be sent right away.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form objects call the IMAPIMessageSite::SubmitMessage method to request that a message be submitted to the MAPI spooler. The message site should call the IPersistMessage::HandsOffMessage method prior to submitting the message. The message need not have previously been saved, as SubmitMessage should cause the message to be saved if it has been modified. Following the return of SubmitMessage, the form must check for a current message and then dismiss itself if none exists.

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.

See Also

IPersistMessage::HandsOffMessage


IMAPIProgress : IUnknown

The IMAPIProgress interface is used to implement a progress object, an object for providing client applications with a progress indicator. A progress indicator is a user interface display that shows the percentage of completion of an operation, such as copying folders between message stores. MAPI and client applications implement progress objects and service providers use them.

Quick Info

Header file:	MAPIDEFS.H
Exposed by:	Progress objects
Implemented by:	MAPI and client applications
Called by:	Service providers
Corresponding pointer type:	LPMAPIPROGRESS
Vtable Order

Progress	Updates the progress indicator with status on the progress made toward completion of the operation in question.
GetFlags	Returns flag settings from the progress object for the level of operation on which progress information is calculated.
GetMax	Returns the maximum number of items in the operation for which progress information is displayed.
GetMin	Returns the minimum number of items in the operation for which progress information is displayed.
SetLimits	Sets the minimum number of items operated on, the maximum number of items operated on, and the flags that control how progress information is calculated for the operation in question.
Remarks

MAPI includes an lpProgress parameter in many of the methods that perform potentially lengthy operations. The lpProgress parameter points to a client implementation of a progress object. Clients that implement IMAPIProgress set this parameter to point to their implementation; clients that do not implement IMAPIProgress set it to NULL. To display a progress indicator during processing of the operation, service providers use the progress object supplied by the client if possible or a MAPI implementation if lpProgress is set to NULL.


IMAPIProgress::GetFlags

The IMAPIProgress::GetFlags method returns flag settings from the progress object for the level of operation on which progress information is calculated.

Quick Info

See IMAPIProgress : IUnknown.

HRESULT GetFlags(

ULONG FAR * lpulFlags
)
Parameters

lpulFlags

[out] Bitmask of flags that controls the level of operation on which progress information is calculated. The following flag can be returned:

MAPI_TOP_LEVEL

Progress is being calculated for the top-level object, the object that is called by the client to begin the operation. For example, the top-level object in a folder copy operation is the folder being copied.

When MAPI_TOP_LEVEL is not set, progress is being calculated for a lower level object, or subobject. In the folder copy operation, a lower level object would be one of the subfolders in the folder being copied.

Return Values

S_OK

The flags value was returned successfully.

Remarks

MAPI allows service providers to differentiate between top-level objects and subobjects with the MAPI_TOP_LEVEL flag so that all objects involved in an operation can use the same IMAPIProgress implementation to show progress, thereby causing the indicator display to proceed smoothly in a single positive direction. Whether or not the MAPI_TOP_LEVEL flag is set determines how service providers set the other parameters in subsequent calls to the progress object.

The value returned by GetFlags is set initially by the implementer and subsequently by the service provider through a call to IMAPIProgress:SetLimits.

Notes to Implementers

Always initialize the flag to MAPI_TOP_LEVEL and then rely on service providers to clear it when appropriate. Service providers can clear and reset the flag by calling IMAPIProgress::SetLimits. For more information about implementing GetFlags and the other IMAPIProgress methods, see Implementing a Progress Indicator.

Notes to Callers

When displaying a progress indicator, make your first call a call to IMAPIProgress::GetFlags. The value returned should be MAPI_TOP_LEVEL because all implementations initialize the contents of lpulFlags to this value. For more information about the sequence of calls to a progress object, see Displaying Progress Step by Step.

See Also

IMAPIProgress::SetLimits


IMAPIProgress::GetMax

The IMAPIProgress::GetMax method returns the maximum number of items in the operation for which progress information is displayed.

Quick Info

See IMAPIProgress : IUnknown.

HRESULT GetMax(

ULONG FAR * lpulMax
)
Parameters

lpulMax

[out] Pointer to the maximum number of items in the operation.

Return Values

S_OK

The maximum number of items in the operation has been retrieved.

Remarks

The maximum value represents the end of the operation in numeric form. The value can be a global maximum value, used to represent the scope of the entire progress display, or a local value, used to represent only a part of the display.

The value of the flags setting affects whether the progress object understands the maximum value to be local or global. When the MAPI_TOP_LEVEL flag is set, the maximum value is considered to be global and is used to calculate progress for the entire operation. When MAPI_TOP_LEVEL is not set, the maximum value is considered local and is used internally by providers to display progress for lower level subobjects. Progress objects save the local maximum value only to return it to a provider through a GetMax call.

For more information about how and when to make calls to a progress object, see Displaying Progress Step by Step.

Notes to Implementers

Initialize the maximum value to 1000. Service providers can reset this value by calling IMAPIProgress::SetLimits. For more information about implementing GetMax and the other IMAPIProgress methods, see Implementing a Progress Indicator.

See Also

IMAPIProgress::GetMin, IMAPIProgress::Progress, IMAPIProgress::SetLimits


IMAPIProgress::GetMin

The IMAPIProgress::GetMin method returns the minimum value in IMAPIProgress::SetLimits for which progress information is displayed.

Quick Info

See IMAPIProgress : IUnknown.

HRESULT GetMin(

ULONG FAR * lpulMin
)
Parameters

lpulMin

[out] Pointer to the minimum number of items in the operation.

Return Values

S_OK

The minimum number of items in the operation has been retrieved.

Remarks

The minimum value represents the beginning of the operation in numeric form. The value can be a global maximum value, used to represent the scope of the entire progress display, or a local value, used to represent only a part of the display.

The value of the flags setting affects whether the progress object understands the minimum value to be local or global. When the MAPI_TOP_LEVEL flag is set, the minimum value is considered to be global and is used to calculate progress for the entire operation. When MAPI_TOP_LEVEL is not set, the minimum value is considered local and is used internally by providers to display progress for lower level subobjects. Progress objects save the local minimum value only to return it to a provider through a GetMin call.

Notes to Implementers

Initialize the minimum value to 1. Service providers can reset this value by calling IMAPIProgress::SetLimits. For more information about implementing GetMin and the other IMAPIProgress methods, see Implementing a Progress Indicator.

For more information about how and when to make calls to a progress object, see Displaying Progress Step by Step.

See Also

IMAPIProgress::GetMax, IMAPIProgress::Progress, IMAPIProgress::SetLimits


IMAPIProgress::Progress

The IMAPIProgress::Progress method updates the progress indicator with a display of the progress as it is made toward completion of the operation.

Quick Info

See IMAPIProgress : IUnknown.

HRESULT Progress(

ULONG ulValue,
ULONG ulCount,
ULONG ulTotal
)
Parameters

ulValue

[in] Number indicating the current level of progress, calculated from the ulCount and ulTotal parameters or from the lpulMin and lpulMax parameters of the IMAPIProgress::SetLimits method between the global lower limit and the global upper limit.

ulCount

[in] Number indicating the currently processed item relative to the total.

ulTotal

[in] Total number of items to be processed during the operation.

Return Values

S_OK

The progress indicator was successfully updated.

Notes to Implementers

The ulValue parameter will be equal to the global minimum value only at the beginning of the operation and to the global maximum value only at the completion of the operation.

Use the second and third parameters, ulCount and ulTotal, if available, to display an optional message such as “5 items completed out of 10.” If the second and third parameters are set to zero, choose whether or not to visually change the progress indicator. Some service providers set these parameters to zeroes to indicate that they are processing a subobject whose progress is monitored relative to a parent object. In this situation, it makes sense to change the display only when the parent object reports progress. Some service providers pass zeroes for these parameters every time.

For more information about implementing Progress and the other IMAPIProgress methods, see Implementing a Progress Indicator.

Notes to Callers

Not all three of the parameters to IMAPIProgress::Progress are required. The only parameter that is required is the first value, a number that indicates percentage of progress. If the MAPI_TOP_LEVEL flag is set, you can also pass an object count and an object total. Some implementations use these values to display a phrase such as “5 items completed out of 10” with the progress indicator.

If you are copying all messages within a single folder, set ulTotal to the total number of messages being copied. If you are copying a folder, set ulTotal to the number of subfolders within the folder. If the folder to be copied contains no subfolders and only messages, set ulTotal to 1.

For more information about how and when to make calls to a progress object, see Displaying Progress Step by Step.

See Also

IMAPIProgress::SetLimits


IMAPIProgress::SetLimits

The IMAPIProgress::SetLimits method sets the lower limit for the number of items operated on, the maximum number of items operated on, and the flags that control how progress information is calculated for the operation in question.

Quick Info

See IMAPIProgress : IUnknown.

HRESULT SetLimits(

LPULONG lpulMin,
LPULONG lpulMax,
LPULONG lpulFlags
)
Parameters

lpulMin

[in] Pointer to a variable containing the lower limit of items in the operation.

lpulMax

[in] Pointer to a variable containing the upper limit of items in the operation.

lpulFlags

[in] Bitmask of flags that controls the level of operation on which progress information is calculated. The following flag can be set:

MAPI_TOP_LEVEL

Uses the values in the IMAPIProgress::Progress method’s ulCount and ulTotal parameters, which indicate the item being operated on and the total items, respectively, to increment progress on the operation. When this flag is set, the values of the global lower and upper limits have to be set.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Service providers call IMAPIProgress::SetLimits to set or clear the MAPI_TOP_LEVEL flag and to set local and global minimum and maximum values. The value of the flags setting affects whether the progress object understands the minimum and maximum values to be local or global. When the MAPI_TOP_LEVEL flag is set, these values are considered global and are used to calculate progress for the entire operation. Progress objects initialize the global minimum value to 1 and the global maximum value to 1000.

When MAPI_TOP_LEVEL is not set, the minimum and maximum values are considered local and are used internally by providers to display progress for lower level subobjects. Progress objects save the local minimum and maximum values only so that they can be returned to providers when GetMin and GetMax are called.

For more information about implementing SetLimits and the other IMAPIProgress methods, see Implementing a Progress Indicator.

For more information about how and when to make calls to a progress object, see Displaying Progress Step by Step.

See Also

IMAPIProgress::Progress


IMAPIProp : IUnknown

The IMAPIProp interface is implemented by all objects that support properties. It is used by clients, service providers, and MAPI to work with properties.

Quick Info

Header file:	MAPIDEFS.H
Exposed by:	No object exposes this interface directly.
Implemented by:	Service providers and MAPI
Called by:	Client applications, service providers, and MAPI
Corresponding pointer type:	LPMAPIPROP
Vtable Order

GetLastError	Returns a MAPIERROR structure containing information about the previous error.
SaveChanges	Makes permanent any changes made to an object since the last save operation.
GetProps	Retrieves one or more properties.
GetPropList	Returns property tags for all properties.
OpenProperty	Returns a pointer to an interface to be used to access a property.
SetProps	Updates one or more properties.
DeleteProps	Deletes one or more properties.
CopyTo	Copies or moves all properties, except for specifically excluded properties.
CopyProps	Copies or moves selected properties.
GetNamesFromIDs	Provides the property names that correspond to one or more property identifiers.
GetIDsFromNames	Provides the property identifiers that correspond to one or more property names.
Remarks

IMAPIProp is the base interface for the following interfaces:

IAttach

IMailUser

IMAPIContainer

IMAPIFormInfo

IMAPIStatus

IMessage

IMsgStore

IProfSect

IPropData


IMAPIProp::CopyProps

The IMAPIProp::CopyProps method copies or moves selected properties.

Quick Info

See IMAPIProp : IUnknown.

HRESULT CopyProps(

LPSPropTagArray lpIncludeProps,
ULONG ulUIParam,
LPMAPIPROGRESS lpProgress,
LPCIID lpInterface,
LPVOID lpDestObj,
ULONG ulFlags,
LPSPropProblemArray FAR * lppProblems
)
Parameters

lpIncludeProps

[in] Pointer to a property tag array specifying the properties to copy or move. PR_NULL cannot be included in the array. The lpIncludeProps parameter cannot be NULL.

ulUIParam

[in] Handle of the parent window for the progress indicator.

lpProgress

[in] Pointer to an implementation of a progress indicator. If NULL is passed in the lpProgress parameter, the progress indicator is displayed using MAPI’s implementation. The lpProgress parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the object pointed to by lpDestObj. The lpInterface parameter must not be NULL.

lpDestObj

[in] Pointer to the object to receive the copied or moved properties.

ulFlags

[in] Bitmask of flags that controls the copy or move operation. The following flags can be set:

MAPI_DECLINE_OK

If the CopyProps calls IMAPISupport::DoCopyProps to handle the copy or move operation, it should instead return immediately with the error value MAPI_E_DECLINE_COPY. The MAPI_DECLINE_OK flag is set by MAPI to limit recursion. Clients do not set this flag.

MAPI_DIALOG

Allows the display of a progress indicator.

MAPI_MOVE

CopyProps should perform a move operation rather than a copy operation. When this flag is not set, CopyProps performs a copy operation.

MAPI_NOREPLACE

Existing properties in the destination object should not be overwritten. When this flag is not set, CopyProps overwrites existing properties.

lppProblems

[in, out] On input, can be NULL, indicating no need for error information, or a pointer to a pointer to an SPropProblemArray structure. If lppProblems is a valid pointer on input, CopyProps returns detailed information about errors in copying one or more properties.

Return Values

S_OK

Properties have been successfully copied or moved.

MAPI_E_COLLISION

A subobject cannot be copied because there is already an subobject existing in the destination object with the same display name (PR_DISPLAY_NAME property) as the subobject to be copied.

MAPI_E_DECLINE_COPY

The service provider does not implement the copy operation.

MAPI_E_FOLDER_CYCLE

The source object performing the copy or move operation directly or indirectly contains the destination object. Significant work might have been performed before this condition was discovered, so the source and destination objects might be partially modified.

MAPI_E_INTERFACE_NOT_SUPPORTED

The interface identified by the lpInterface parameter is not supported by the destination object.

MAPI_E_NO_ACCESS

An attempt was made to access an object for which the caller has insufficient permissions. This error is returned if the destination object is the same as the source object.

The following values can be returned in the SPropProblemArray structure, but not as return values for CopyProps. These errors apply to a single property:

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and CopyProps does not support Unicode, or MAPI_UNICODE was not set and CopyProps only supports Unicode.

MAPI_E_COMPUTED

The property cannot be modified by the caller because it is a read-only property, computed by the owner of the destination object. This error is not severe; the caller should allow the copy operation to continue.

MAPI_E_INVALID_TYPE

The property type is invalid.

MAPI_E_UNEXPECTED_TYPE

The property type is not the type expected by the caller.

Remarks

The IMAPIProp::CopyProps method copies or moves selected properties from the current object to a destination object. CopyProps is used mainly for replying to and forwarding messages, where only some of the properties from the original message travel with the reply or forwarded copy.

Any subobjects in the source object are automatically included in the operation and copied or moved in their entirety, regardless of the use of properties indicated by the SPropTagArray structure. By default, CopyProps overwrites any properties in the destination object that match properties from the source object. If any of the copied or moved properties already exist in the destination object, the existing properties are overwritten by the new, unless the MAPI_NOREPLACE flag is set in the ulFlags parameter. Existing information in the destination object that is not overwritten is left untouched.

Notes to Implementers

You can provide a full implementation of CopyProps or rely on the implementation that MAPI provides in its support object. If you want to use the MAPI implementation, call IMAPISupport::DoCopyProps. However, If you do delegate processing to DoCopyProps and you are passed the MAPI_DECLINE_OK flag, avoid the support call and return MAPI_E_DECLINE_COPY instead. You will be called with this flag by MAPI to avoid the possible recursion that can happen when copying folders.

Because the copy operation can be lengthy, you are encouraged to display a progress indicator. Use the IMAPIProgress implementation passed in the lpProgress parameter, if there is one. If lpProgress is NULL, call IMAPISupport::DoProgressDialog to use the MAPI implementation.

Notes to Callers

Do not set the MAPI_DECLINE_OK flag; it is used by MAPI in its calls to message store provider CopyProps implementations.

Because copy and move operations can take time, it is wise to request the display of a progress indicator by setting the MAPI_DIALOG flag. You can set the lpProgress parameter to your implementation of IMAPIProgress, if you have one, or to NULL. If lpProgress is NULL, CopyProps will use the default progress indicator provided by MAPI.

You can suppress the display of a progress indicator by not setting the MAPI_DIALOG flag. CopyProps will ignore the ulUIParam and lpProgress parameters and avoid displaying the indicator.

CopyProps can report global and individual errors, or errors that occur with one or more of the properties. These individual errors are placed in an SPropProblemArray structure. You can suppress error reporting at the property level by passing NULL for the property problem array structure parameter rather than a valid pointer.

If you want to receive information about errors, pass a valid SPropProblemArray structure pointer in the lppProblems parameter. When CopyProps returns S_OK, check for possible errors with individual properties in the structure. When CopyProps returns an error, no information is returned in the SPropProblemArray structure. Instead, call IMAPIProp::GetLastError to retrieve detailed error information.

If CopyProps returns S_OK, free the returned SPropProblemArray structure by calling the MAPIFreeBuffer function.

If you are copying properties that are unique to the source object type, you must be sure that the destination object is of the same type. CopyProps does not prevent you from associating properties that typically belong to one type of object with another type of object. It is up to you to copy properties that make sense for the destination object. For example, you should not copy message properties to an address book container.

To ensure that you are copying between objects of the same type, check that the source and destination object are the same type, either by comparing object pointers or calling IUnknown::QueryInterface. Set the interface identifier pointed to by lpInterface to the standard interface for the source object. Also, make sure that the object type — or PR_OBJECT_TYPE property — is the same for the two objects. For example, if you are copying from a message, set lpInterface to IID_IMessage and the PR_OBJECT_TYPE for both objects to MAPI_MESSAGE.

If an invalid pointer is passed in the lpDestObj parameter, the results are unpredictable.

To copy a message’s recipient list, call the message’s IMAPIProp::CopyProps method and include the PR_MESSAGE_RECIPIENTS property in the property tag array. To copy the message’s attachments, include the PR_MESSAGE_ATTACHMENTS property.

To copy a folder or address book container’s hierarchy or contents table, include PR_CONTAINER_HIERARCHY or PR_CONTAINER_CONTENTS in the property tag array. To include a folder’s associated contents table, include the PR_FOLDER_ASSOCIATED_CONTENTS property in the array.

See Also

IMAPIFolder::CopyMessages, IMAPIProp::CopyTo, IMAPIProp::GetLastError, SPropProblemArray, SPropTagArray


IMAPIProp::CopyTo

The IMAPIProp::CopyTo method copies or moves all properties, except for specifically excluded properties.

Quick Info

See IMAPIProp : IUnknown.

HRESULT CopyTo(

ULONG ciidExclude,
LPCIID rgiidExclude,
LPSPropTagArray lpExcludeProps,
ULONG ulUIParam,
LPMAPIPROGRESS lpProgress,
LPCIID lpInterface,
LPVOID lpDestObj,
ULONG ulFlags,
LPSPropProblemArray FAR * lppProblems
)
Parameters

ciidExclude

[in] Count of interfaces to exclude when copying or moving properties.

rgiidExclude

[in] Array of interface identifiers (IIDs) indicating interfaces that should not be used when copying or moving supplemental information to the destination object.

lpExcludeProps

[in] Pointer to a property tag array identifying the property tags that should be excluded from the copy or move operation. Passing NULL in the lpExcludeProps parameter indicates that all of the object’s properties should be copied or moved. CopyTo returns MAPI_E_INVALID_PARAMETER when the cValues member of the SPropTagArray structure pointed to by lpExcludeProps is set to zero.

ulUIParam

[in] Handle of the parent window for the progress indicator.

lpProgress

[in] Pointer to a progress indicator implementation. If NULL is passed in the lpProgress parameter, MAPI provides the progress implementation. The lpProgress parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the object pointed to by lpDestObj. The lpInterface parameter must not be NULL.

lpDestObj

[in] Pointer to the object to receive the copied or moved properties.

ulFlags

[in] Bitmask of flags that controls the copy or move operation. The following flags can be set:

MAPI_DECLINE_OK

If the CopyTo calls IMAPISupport::DoCopyTo to handle the copy or move operation, it should instead return immediately with the error value MAPI_E_DECLINE_COPY. The MAPI_DECLINE_OK flag is set by MAPI to limit recursion. Clients do not set this flag.

MAPI_DIALOG

Allows the display of a progress indicator.

MAPI_MOVE

CopyTo should perform a move operation rather than a copy operation. When this flag is not set, CopyTo performs a copy operation.

MAPI_NOREPLACE

Existing properties in the destination object should not be overwritten. When this flag is not set, CopyTo overwrites existing properties.

lppProblems

[in, out] On input, can be NULL, indicating no need for error information, or a pointer to a pointer to an SPropProblemArray structure. If lppProblems is a valid pointer on input, CopyTo returns detailed information about errors in copying one or more properties.

Return Values

S_OK

The properties have been successfully copied or moved.

MAPI_E_COLLISION

A subobject cannot be copied because there is already an subobject existing in the destination object with the same display name (PR_DISPLAY_NAME property) as the subobject to be copied.

MAPI_E_DECLINE_COPY

The service provider does not implement the copy operation.

MAPI_E_FOLDER_CYCLE

The source object performing the copy or move operation directly or indirectly contains the destination object. Significant work might have been performed before this condition was discovered, so the source and destination objects might be partially modified.

MAPI_E_INTERFACE_NOT_SUPPORTED

The interface identified by the lpInterface parameter is not supported by the destination object.

MAPI_E_NO_ACCESS

An attempt was made to access an object for which the caller has insufficient permissions. This error is returned if the destination object is the same as the source object.

The following values can be returned in the SPropProblemArray structure, but not as return values for CopyTo. These errors apply to a single property:

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and CopyTo does not support Unicode, or MAPI_UNICODE was not set and CopyTo only supports Unicode.

MAPI_E_COMPUTED

The property cannot be modified by the caller because it is a read-only property, computed by the owner of the destination object. This error is not severe; the caller should allow the copy operation to continue.

MAPI_E_INVALID_TYPE

The property type is invalid.

MAPI_E_UNEXPECTED_TYPE

The property type is not the type expected by the caller.

Remarks

The IMAPIProp::CopyTo method by default copies or moves all of the current object’s properties to a destination object. CopyTo is used when an object should be copied or moved exactly, with all or most of its properties intact.

Any subobjects in the source object are automatically included in the operation and copied or moved in their entirety. CopyTo by default overwrites any properties in the destination object that match properties from the source object. If any of the copied or moved properties already exist in the destination object, the existing properties are overwritten by the new, unless the MAPI_NOREPLACE flag is set in the ulFlags parameter. Existing information in the destination object that is not overwritten is left untouched.

Notes to Implementers

You can provide a full implementation of CopyTo or rely on the implementation that MAPI provides in its support object. If you want to use the MAPI implementation, call IMAPISupport::DoCopyTo. However, If you do delegate processing to DoCopyTo and you are passed the MAPI_DECLINE_OK flag, avoid the support call and return MAPI_E_DECLINE_COPY instead. You will be called with this flag by MAPI to avoid the possible recursion that can happen when copying folders.

Because the copy operation can be lengthy, you are encouraged to display a progress indicator. Use the IMAPIProgress implementation passed in the lpProgress parameter, if there is one. If lpProgress is NULL, call IMAPISupport::DoProgressDialog to use the MAPI implementation.

Do not attempt to set any known read-only properties in the destination object; return MAPI_E_NO_ACCESS instead.

The source and destination objects should use the same interfaces. Return MAPI_E_INVALID_PARAMETER if lpInterface is not set.

Return MAPI_E_INTERFACE_NOT_SUPPORTED if all known interfaces are excluded.

Notes to Callers

Do not set the MAPI_DECLINE_OK flag; it is used by MAPI in its calls to message store provider CopyTo implementations.

Because copy and move operations can take time, it is wise to request the display of a progress indicator by setting the MAPI_DIALOG flag. You can set the lpProgress parameter to your implementation of IMAPIProgress, if you have one, or to NULL. If lpProgress is NULL, CopyTo will use the default progress indicator provided by MAPI.

You can suppress the display of a progress indicator by not setting the MAPI_DIALOG flag. CopyTo will ignore the ulUIParam and lpProgress parameters and avoid displaying the indicator.

CopyTo can report global and individual errors, or errors that occur with one or more properties. These individual errors are placed in an SPropProblemArray structure. You can suppress error reporting at the property level by passing NULL for the property problem array structure parameter rather than a valid pointer.

If you want to receive information about errors, pass a valid SPropProblemArray structure pointer in the lppProblems parameter. When CopyTo returns S_OK, check for possible errors with individual properties in the structure. When CopyTo returns an error, no information is returned in the SPropProblemArray structure. Instead, call IMAPIProp::GetLastError to retrieve detailed error information.

If CopyTo returns S_OK, free the returned SPropProblemArray structure by calling the MAPIFreeBuffer function.

If you are copying properties that are unique to the source object type, you must be sure that the destination object is of the same type. CopyTo does not prevent you from associating properties that typically belong to one type of object with another type of object. It is up to you to copy properties that make sense for the destination object. For example, you should not copy message properties to an address book container.

To ensure that you are copying between objects of the same type, check that the source and destination object are the same type, either by comparing object pointers or calling IUnknown::QueryInterface. Set the interface identifier pointed to by lpInterface to the standard interface for the source object. Also, make sure that the object type — or PR_OBJECT_TYPE property — is the same for the two objects. For example, if you are copying from a message, set lpInterface to IID_IMessage and the PR_OBJECT_TYPE for both objects to MAPI_MESSAGE.

If an invalid pointer is passed in the lpDestObj parameter, the results are unpredictable.

Excluding properties on a CopyTo call can be useful. For example, some objects have properties that are specific to a single instance of the object, such as the date and time of message delivery. To avoid copying a message’s delivery time when copying the message to a different folder, specify PR_MESSAGE_DELIVERY_TIME in the property tag exclude array. To exclude a message’s recipient list, add the PR_MESSAGE_RECIPIENTS property to the exclude array. To exclude a message’s attachments, add the PR_MESSAGE_ATTACHMENTS property to the array.

Similarly, prevent the copying or moving of a folder or address book container’s hierarchy or contents table by including PR_CONTAINER_HIERARCHY or PR_CONTAINER_CONTENTS in the property tag exclude array.

To exclude properties from the copy or move operation, include their property tags in the lpExcludeProps parameter. If you pass the results of using the PROP_TAG macro to build a property tag from a specific identifier in the property tag array, all properties with that identifier will be excluded. For example, the following entry in the property tag array causes all properties with an identifier of 0x8002 to be excluded, regardless of type:

PROP_TAG(PT_LONG, 0x8002)

The PR_NULL property tag cannot be included in the lpExcludeProps array.

The usefulness of the CopyTo feature for excluding interfaces is perhaps not as obvious as the usefulness of excluding properties. You can exclude an interface when copying to an object that has no knowledge of a group of properties. For example, if you are copying properties from a folder to an attachment, the only properties that the attachment will be able to work with are the generic properties accessible with any IMAPIProp implementation. By excluding IMAPIFolder from the copy operation, the attachment will not receive any of the more specific folder properties.

When you use the rgiidExclude parameter to exclude an interface, it also excludes all interfaces derived from that interface. For example, excluding IMAPIContainer causes folders or address book containers to be excluded, depending on the type of provider. Do not exclude IMAPIProp or IUnknown because so many interfaces derive from them.

Ignore MAPI_E_COMPUTED errors returned in the SPropProblemArray structure in the lppProblems parameter.

See Also

IMAPIFolder::CopyMessages, IMAPIProp::GetLastError, SPropProblemArray, SPropTagArray


IMAPIProp::DeleteProps

The IMAPIProp::DeleteProps method deletes one or more properties.

Quick Info

See IMAPIProp : IUnknown.

HRESULT DeleteProps(

LPSPropTagArray lpPropTagArray,
LPSPropProblemArray FAR * lppProblems
)
Parameters

lpPropTagArray

[in] Pointer to an array of property tags indicating the properties to delete. The cValues member of the SPropTagArray structure pointed to by lpPropTagArray must not be zero and the lpPropTagArray parameter itself must not be NULL.

lppProblems

[in, out] On input, can be NULL, indicating no need for error information, or a pointer to a pointer to an SPropProblemArray structure. If lppProblems is a valid pointer on input, DeleteProps returns detailed information about errors in deleting one or more properties.

Return Values

S_OK

Properties were successfully deleted.

MAPI_E_NO_ACCESS

The caller has insufficient permissions to delete properties.

Remarks

The IMAPIProps::DeleteProps method removes one or more properties from the current object.

Notes to Implementers

You do not have to allow properties to be deleted from all objects. If the object is not modifiable, return MAPI_E_NO_ACCESS from DeleteProps.

Notes to Callers

You do not need to set the property type for each property tag in the property tag array pointed to by lpPropTagArray. Property types are ignored; only the property identifiers are used.

Be aware that some objects do not allow modification and that these objects return MAPI_E_NO_ACCESS from DeleteProps. Other objects allow some properties to be deleted, but not others. When there is a problem deleting only some of the properties, DeleteProps returns S_OK. If you have passed a valid pointer in the lppProblems parameter, DeleteProps will set it to an SPropProblemArray structure containing detailed information about the problems with each of the properties. For example, if you are deleting all of the properties of a message and there is a problem with one or more of its attachments, the SPropProblemArray structure will contain an entry for PR_MESSAGE_ATTACHMENTS.

The structure pointed to by lppProblems is only valid if DeleteProps returns S_OK. If DeleteProps returns an error, do not attempt to use the SPropProblemArray structure. Instead, call the object’s IMAPIProp::GetLastError method to get more information about the error.

Free the returned SPropProblemArray structure by calling the MAPIFreeBuffer function.

See Also

IMAPIProp::GetProps, IMAPIProp::SaveChanges, MAPIFreeBuffer, SPropTagArray


IMAPIProp::GetIDsFromNames

The IMAPIProp::GetIDsFromNames method provides the property identifiers that correspond to one or more property names.

Quick Info

See IMAPIProp : IUnknown.

HRESULT GetIDsFromNames(

ULONG cPropNames,
LPMAPINAMEID FAR * lppPropNames,
ULONG ulFlags,
LPSPropTagArray FAR * lppPropTags
)
Parameters

cPropNames

[in] Count of property names pointed to by the lppPropNames parameter. If lppPropNames is NULL, the cPropNames parameter must be zero.

lppPropNames

[in] Pointer to an array of property names or NULL. Passing NULL requests property identifiers for all property names in all property sets about which the object has information. The lppPropNames parameter must not be NULL if the MAPI_CREATE flag is set in the ulFlags parameter.

ulFlags

[in] Bitmask of flags that indicates how the property identifiers should be returned. The following flag can be set:

MAPI_CREATE

Assigns a property identifier to one or more of the names included in the property name array pointed to by lppPropNames if one has not yet been assigned. Internally registers the identifier in the name-to-identifier mapping table.

lppPropTags

[out] Pointer to a pointer to an array of property tags containing existing or newly assigned property identifiers. The property types for the property tags in this array are set to PT_UNSPECIFIED.

Return Values

S_OK

The identifiers for the specified property names were successfully returned.

MAPI_E_NO_SUPPORT

The object does not support named properties.

MAPI_E_NOT_ENOUGH_MEMORY

Insufficient memory was available to retrieve the identifiers.

MAPI_E_TOO_BIG

The operation cannot be performed because it requires too many property tags be returned.

MAPI_W_ERRORS_RETURNED

The call succeeded overall, but one or more property identifiers could not be returned. The corresponding property type for each inaccessible property is set to PT_ERROR and its identifier to zero. When this warning is returned, handle the call as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPIProp::GetIDsFromNames method retrieves an array of property tags that hold the property identifiers for one or more named properties. IMAPIProp::GetIDsFromNames can be called to:

•	Create identifiers for new names.

•	Retrieve identifiers for specific names.

•	Retrieve identifiers for all named properties that are included in the object’s mapping.

Named properties are commonly used by message store providers for folders and messages. Other objects, such as messaging users and profile sections, might not support the association of names to property identifiers and return MAPI_E_NO_SUPPORT from GetIDsFromNames.

If there is an error returning an identifier for a particular name, GetIDsFromNames returns MAPI_W_ERRORS_RETURNED and sets the property type in the property tag array entry that corresponds to the name to PT_ERROR and the identifier to zero.

Name-to-identifier mapping is represented by an object’s PR_MAPPING_SIGNATURE property. PR_MAPPING_SIGNATURE contains a MAPIUID structure that indicates the service provider responsible for the object. If the PR_MAPPING_SIGNATURE property is the same for two objects, assume that these objects use the same name-to-identifier mapping.

Notes to Implementers

The identifiers that you pass back in the property tag array pointed to by lppPropNames must be in the 0x8000 to 0xFFFE range. The entries in this array must be in the same order as the names passed in the property name array pointed to by lppPropNames.

If you support named properties on a container, use the same name-to-identifier mapping for all objects in your container. That is, do not use a different mapping for each folder in your message store or each message in your folder.

Notes to Callers

Because the property types for the returned identifiers in the property tag array pointed to by lppPropTags are set to PT_UNSPECIFIED, you will need to call IMAPIProp::SetProps to retrieve the accurate types.

If you move or copy objects with named properties, and the source and destination objects have different mapping signatures as indicated by the values of their PR_MAPPING_SIGNATURE properties, you must preserve the names during these operations. To preserve property names, adjust the corresponding property identifiers to match the name-to-identifier mapping of the destination object.

Some objects have a limit as to the name of property identifiers they can name. If a call to GetIDsFromNames causes this limit to be exceeded, the method returns MAPI_E_TOO_BIG. In this case, query by identifier.

For more information, see Named Properties.

See Also

IMAPIProp::GetNamesFromIDs, MAPINAMEID, MAPIUID


IMAPIProp::GetLastError

The IMAPIProp::GetLastError method returns a MAPIERROR structure containing information about the previous error.

Quick Info

See IMAPIProp : IUnknown.

HRESULT GetLastError(

HRESULT hResult,
ULONG ulFlags,
LPMAPIERROR FAR * lppMAPIError
)
Parameters

hResult

[in] HRESULT data type containing the error code generated in the previous method call.

ulFlags

[in] Bitmask of flags that indicates the format for the text returned in the MAPIERROR structure pointed to by lppMAPIError. The following flag can be set:

MAPI_UNICODE

The strings should be in the Unicode format. If the MAPI_UNICODE flag is not set, the strings should be in the ANSI format.

lppMAPIError

[out] Pointer to a pointer to the MAPIERROR structure containing version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if there is no error information to return.

Return Values

S_OK

The error information was returned.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

Remarks

The IMAPIProp::GetLastError method supplies information about a prior method call that failed. Clients can provide their users with detailed information about the error by including the data from the MAPIERROR structure in a dialog box.

All of the implementations of GetLastError provided by MAPI are ANSI implementations except for the IAddrBook implementation. The GetLastError method included with IAddrBook supports Unicode on Windows NT platforms only.

Notes to Callers

You can make use of the MAPIERROR structure pointed to by the lppMAPIError parameter, if GetLastError supplies one, only if the return value is S_OK. Sometimes GetLastError cannot determine what the last error was or has nothing more to report about the error. In this situation, a pointer to NULL is returned in lppMAPIError instead.

To release the memory for the MAPIERROR structure, call MAPIFreeBuffer.

For more information about the GetLastError method, see Using Extended Errors.

See Also

MAPIERROR, MAPIFreeBuffer


IMAPIProp::GetNamesFromIDs

The IMAPIProp::GetNamesFromIDs method provides the property names that correspond to one or more property identifiers.

Quick Info

See IMAPIProp : IUnknown.

HRESULT GetNamesFromIDs(

LPSPropTagArray FAR * lppPropTags,
LPGUID lpPropSetGuid,
ULONG ulFlags,
ULONG FAR * lpcPropNames,
LPMAPINAMEID FAR * FAR * lpppPropNames
)
Parameters

lppPropTags

[in, out] On input, can be NULL, indicating that all names should be returned, or a pointer to a pointer to an array of property tags. The cValues member for the property tag array cannot be zero. If lppPropTags is a valid pointer on input, GetNamesFromIDs returns names for each of the property identifiers included in the array.

lpPropSetGuid

[in] Pointer to a globally unique identifier, or GUID structure, identifying a property set. The lpPropSetGuid parameter can point to a valid property set or contain NULL.

ulFlags

[in] Bitmask of flags that indicates the type of names to be returned. The following flags can be used:

MAPI_NO_IDS

Requests that only names stored as Unicode strings be returned.

MAPI_NO_STRINGS

Requests that only names stored as numeric identifiers be returned.

If both flags are set, no names will be returned.

lpcPropNames

[out] Pointer to a count of the property names pointed to by lpppPropNames.

lpppPropNames

[out] Pointer to a pointer to an array of property names.

Return Values

S_OK

The property names were successfully returned.

MAPI_E_NO_SUPPORT

The object does not support named properties.

MAPI_W_ERRORS_RETURNED

The call succeeded overall, but names for one or more properties could not be returned. The property tags for the failing properties have a property type of PT_ERROR. When this warning is returned, the call should be handled as successful. To test for the warning, use the HR_FAILED macro. See Using Macros for Error Handling.

MAPI_E_INVALID_PARAMETER

The cValues member of one or more of the entries in the property tag array pointed to by lppPropTags is set to zero.

Remarks

While access to most properties is by property identifier, some properties can be accessed by name. The IMAPIProp::GetNamesFromIDs method can be called to:

•	Retrieve names for specific property identifiers in a specific property set.

•	Retrieve names for specific property identifiers in any property set.

•	Retrieve names for all named properties that are included in the object’s mapping.

If lppPropTags points to a valid property tag array with one or more property identifiers and lpPropSetGuid points to a valid property set, GetNamesFromIDs ignores the property set and the property types and returns all of the names that map to the specified identifiers.

If lppPropTags points to a valid property tag array with one or more property identifiers and lpPropSetGuid is NULL, GetNamesFromIDs returns all of the names that map to the specified identifiers.

If a specified identifier does not have a name, GetNamesFromIDs returns NULL in that identifier’s place in the structure returned in lpppPropNames and also returns MAPI_W_ERRORS_RETURNED.

If both lpPropSetGuid and lppPropTags are NULL, GetNamesFromIDs allocates a new property tag array and returns all of the names for all of the named properties for the object.

When there are no names to be returned, perhaps because there are no properties in the requested property set or all of the properties are of a type excluded by the flags, GetNamesFromIDs:

•	Returns S_OK.

•	Allocates a new SPropTagArray structure, setting the cValues member to 0.

•	Sets the contents of lpcPropNames to zero.

•	Sets the contents of lpppPropNames to NULL.

Notes to Implementers

If lpPropSetGuid points to a valid property set and lppPropsTags is NULL, the result is undefined. You can implement one of the following strategies:

•	Ignore the property set and return the names for the identifiers in the property tag array.

•	Return the names for only the identifiers in the property tag array that belong to the specified property set.

•	Fail the call, returning MAPI_E_INVALID_PARAMETER.

Notes to Callers

To retrieve all of the named properties for an object, you must first call the object’s IMAPIProp::GetPropList method and then pass the returned identifiers that are above the 0x8000 range to GetNamesFromIDs.

If you pass a valid property set without a valid property tag array, be prepared for unpredictable results. Some implementations of GetNamesFromIDs ignore the property set and return the names for the identifiers in the property tag array. Some implementations return MAPI_E_INVALID_PARAMETER.

Still other implementations only return names for identifiers of properties belonging to the specified property set. When the property set is PS_PUBLIC_STRINGS, GetNamesFromIDs can return all names that were ever created. Whether or not the object or any other object supported by the service provider stores a property under the identifiers associated with the public strings is immaterial.

Check the contents of the lpcPropNames parameter to determine if any names were returned and call MAPIFreeBuffer to free the memory pointed to by lppPropTags and lpppPropnames when success is returned.

For more information about named properties, see Named Properties.

See Also

IMAPIProp::GetIDsFromNames, MAPIFreeBuffer, MAPINAMEID, SPropTagArray


IMAPIProp::GetPropList

The IMAPIProp::GetPropList method returns property tags for all properties.

Quick Info

See IMAPIProp : IUnknown.

HRESULT GetPropList(

ULONG ulFlags,
LPSPropTagArray FAR * lppPropTagArray
)
Parameters

ulFlags

[in] Bitmask of flags that controls the format for the strings in the returned property tags. The following flag can be set:

MAPI_UNICODE

The returned strings are in the Unicode format. If the MAPI_UNICODE flag is not set, the strings are in the ANSI format.

lppPropTagArray

[out] Pointer to a pointer to the property tag array containing tags for all of the object’s properties.

Return Values

S_OK

All of the property tags were returned successfully.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

Remarks

The IMAPIProp::GetPropList method retrieves the property tag for each property currently supported by an object. If the object does not currently support any properties, GetPropList returns a property tag array with the cValues member set to zero.

The scope of properties returned by GetPropList varies from provider to provider. Some service providers exclude those properties for which the caller does not have access. All providers return properties of type PT_OBJECT.

If the object does not support Unicode, GetPropList returns MAPI_E_BAD_CHARWIDTH, even if there are no string properties defined for the object.

Notes to Callers

Call the MAPIFreeBuffer function to free the property tag array pointed to by lppPropTagArray.

See Also

MAPIFreeBuffer


IMAPIProp::GetProps

The IMAPIProp::GetProps method retrieves the property value of one or more properties of an object.

Quick Info

See IMAPIProp : IUnknown.

HRESULT GetProps(

LPSPropTagArray lpPropTagArray,
ULONG ulFlags,
ULONG FAR * lpcValues,
LPSPropValue FAR * lppPropArray
)
Parameters

lpPropTagArray

[in] Pointer to an array of property tags identifying the properties whose values are to be retrieved. The lpPropTagArray parameter must either be NULL, indicating that values for all properties of the object should be returned, or point to an SPropTagArray structure containing one or more property tags.

ulFlags

[in] Bitmask of flags that indicates the format for properties that have the type PT_UNSPECIFIED. The following flag can be set:

MAPI_UNICODE

The string values for these properties should be returned in the Unicode format. If the MAPI_UNICODE flag is not set, the string values should be returned in the ANSI format.

lpcValues

[out] Pointer to a count of property values pointed to by the lppPropArray parameter. If lppPropArray is NULL, the contents of the lpcValues parameter is zero.

lppPropArray

[out] Pointer to a pointer to the retrieved property values.

Return Values

S_OK

The property values were successfully retrieved.

MAPI_W_ERRORS_RETURNED

The call succeeded overall, but one or more properties could not be accessed. The ulPropTag member of the property value for each unaccessible property has a property type of PT_ERROR and an identifier of zero. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

MAPI_E_INVALID_PARAMETER

Zero was passed in the cValues member of the SPropTagArray structure pointed to by lpPropTagArray.

Remarks

The IMAPIProp::GetProps method gets the property values of one or more properties of an object.

The property values are returned in the same order as they were requested. That is, the order of properties in the property tag array pointed to by lpPropTagArray matches the order in the array of property value structures pointed to by lppPropArray.

The property types specified in the aulPropTag members of the property tag array indicate the type of value that should be returned in the Value member of each property value structure. However, if the caller does not know the type of a property, the type in the aulPropTag member can be set instead to PT_UNSPECIFIED. In retrieving the value, GetProps sets the correct type in the ulPropTag member of the property value structure for the property.

If property types are specified in the SPropTagArray in lpPropTagArray, then the property values in the SPropValue returned in lppPropArray have types that exactly match the requested types, unless an error value is returned instead.

String properties can have one of two property types: PT_UNICODE to represent the Unicode format and PT_STRING8 to represent the ANSI format. If the MAPI_UNICODE flag is set in the ulFlags parameter, whenever GetProps cannot determine the appropriate format for a string property, it returns its value in the Unicode format. GetProps cannot determine an exact string property type:

•	If the lpPropTagArray parameter is set to NULL to request all properties.

•	When the aulPropTag member includes the value PT_UNSPECIFIED as its property type in the property tag array.

If the lpPropTagArray parameter is set to NULL to retrieve all of the properties of the object and no properties exist, GetProps:

•	Returns S_OK.

•	Sets the count value in the cValues member of the property value structure to zero.

•	Sets the contents of lpcValues to zero.

•	Sets lppPropArray to NULL.

•	Must not return multivalued properties with cValues set to zero.

Notes to Implementers

Call the MAPIAllocateBuffer function to allocate memory initially for the SPropValue structure pointed to by lpPropTagArray; call MAPIAllocateMore to allocate any additional memory needed for the structure’s members.

Return MAPI_W_ERRORS_RETURNED if you cannot retrieve the value for one or more of the requested properties. In the property value structure, set the type in the ulPropTag member to PT_ERROR and the Value member to a status code describing the error. For example, if you need to convert a string to Unicode and do not support Unicode, set the Value member to MAPI_E_BAD_CHARWIDTH. If the property is too large, set it to MAPI_E_NOT_ENOUGH_MEMORY. If the object does not support the property, set it to MAPI_E_NOT_FOUND.

Notes to Callers

For properties of type PT_OBJECT, call the IMAPIProp::OpenProperty method instead of GetProps.

For secure properties, do not expect to retrieve them by calling GetProps with the lppPropTagArray parameter set to NULL. You must explicitly set a secure property’s identifier in the aulPropTag member of its property tag array when calling GetProps. When and how a secure property is available is up to the service provider.

Free the returned SPropValue structure by calling the MAPIFreeBuffer function only if GetProps returns S_OK or MAPI_W_ERRORS_RETURNED.

If GetProps returns MAPI_W_ERRORS_RETURNED because it could not access one or more properties, check the property tags of the returned properties. The failed properties will have the following values set in their property value structure:

•	Property type in the ulPropTag member set to PT_ERROR.

•	Property value in the Value member set to a status code for the error, such as MAPI_E_NOT_FOUND.

Properties that fail because they are too large to conveniently be returned in the property value structure have their Value member set to MAPI_E_NOT_ENOUGH_MEMORY. Typically this occurs with string or binary properties of type PT_STRING8, PT_UNICODE, or PT_BINARY when the value of the property is 4K or larger. Call IMAPIProp::OpenProperty to retrieve large properties.

Not all implementations of GetProps support both the Unicode and ANSI formats for character strings. When a particular property requires string format conversion and GetProps cannot support it, the Value member for the property is set to MAPI_E_BAD_CHARWIDTH.

For more information about using GetProps to access properties, see Retrieving Properties.

See Also

IMAPIProp::OpenProperty, MAPIAllocateBuffer, MAPIAllocateMore, MAPIFreeBuffer, SPropTagArray, SPropValue


IMAPIProp::OpenProperty

The IMAPIProp::OpenProperty method returns a pointer to an interface to be used to access a property.

Quick Info

See IMAPIProp : IUnknown.

HRESULT OpenProperty(

ULONG ulPropTag,
LPCIID lpiid,
ULONG ulInterfaceOptions,
ULONG ulFlags,
LPUNKNOWN FAR * lppUnk
)
Parameters

ulPropTag

[in] Property tag for the property to be accessed. Both the identifier and the type must be included in the property tag.

lpiid

[in] Pointer to the identifier for the interface to be used to access the property. The lpiid parameter must not be NULL.

ulInterfaceOptions

[in] Data that relates to the interface identified by the lpiid parameter.

ulFlags

[in] Bitmask of flags that controls access to the property. The following flags can be set:

MAPI_CREATE

If the property does not exist, it should be created. If the property does exist, the current value of the property should be discarded. When a caller sets the MAPI_CREATE flag, it should also set the MAPI_MODIFY flag.

MAPI_DEFERRED_ERRORS

Allows OpenProperty to return successfully, possibly before the object is fully accessible to the caller. If the object is not accessible, making a subsequent object call can result in an error.

MAPI_MODIFY

Requests read/write access to the property. The default access is read-only. MAPI_MODIFY must be set when MAPI_CREATE is set.

lppUnk

[out] Pointer to the requested interface to be used for property access.

Return Values

S_OK

The requested interface pointer was successfully returned.

MAPI_E_INTERFACE_NOT_SUPPORTED

The requested interface is not supported for this property.

MAPI_E_NO_ACCESS

The caller has insufficient permissions to access the property.

MAPI_E_NO_SUPPORT

The object cannot provide access to this property through the requested interface..

MAPI_E_NOT_FOUND

The requested property does not exist and MAPI_CREATE was not set in the ulFlags parameter.

MAPI_E_INVALID_PARAMETER

The property type in the tag is set to PT_UNSPECIFIED.

Remarks

The IMAPIProp::OpenProperty method provides access to a property through a particular interface. OpenProperty is an alternate to GetProps and SetProps. When either GetProps or SetProps fail because the property is too large or too complex, call OpenProperty. OpenProperty is commonly used to access properties of type PT_OBJECT.

Notes to Callers

To access message attachments, open the PR_ATTACH_DATA_OBJ property with a different interface identifier, depending on the type of attachment. The following table describes how to call OpenProperty for the different types of attachments:

Type of attachment	Interface identifier to use
Binary	IID_IStream
String	IID_IStream
Message	IID_IMessage
OLE 2	IID_IStreamDocfile
IStreamDocfile is a derivative of IStream that is based on an OLE2 compound file. IStreamDocfile is the best choice for accessing OLE 2 attachments because it involves the least amount of overhead. IID_IStreamDocFile can be used for those properties that contain data stored in structured storage accessible through the IStorage interface.

For more information about using OpenProperty with attachments, see PR_ATTACH_DATA_OBJ and Opening an Attachment.

Do not use the IStream pointer that you receive to call either its Seek or SetSize method unless you use a zero position or size variable. Also, do not rely on the value of the plibNewPosition output parameter returned from the Seek call.

If you call OpenProperty to access a property with the IStream interface, use only that interface to make changes to it. Do not attempt to update the property with any of the other IMAPIProp methods such as SetProps or DeleteProps.

Do not try to open a property with OpenProperty more than once. The results are undefined because they can vary from provider to provider.

If you need to modify the property to be opened, set the MAPI_MODIFY flag. If you are not sure if the object supports the property but think it should, set the MAPI_CREATE and MAPI_MODIFY flags. Whenever MAPI_CREATE is set, MAPI_MODIFY must also be set.

You are responsible for recasting the interface pointer returned in the lppUnk parameter to one appropriate for the interface specified in the lpiid parameter. You must also use the returned pointer to call its IUnknown::Release method when you have finished with it.

Sometimes setting the flags in the ulFlags parameter is not enough to indicate the type of access to the property that is required. You can place additional data such as flags in the ulInterfaceOptions parameter. This data is interface-dependent. Some interfaces, such as IStream, use it and others do not. For example, when opening a property to be modified with IStream, set the STGM_WRITE flag in the ulInterfaceOptions parameter in addition to MAPI_MODIFY. When opening a table using IMAPITable, you can set ulInterfaceOptions to MAPI_UNICODE to indicate whether or not the columns in the table that hold string properties should be in the Unicode format.

See Also

HrIStorageFromStream, IMAPIProp::DeleteProps, IMAPIProp::GetProps, IMAPIProp::SetProps, IMAPISupport::IStorageFromStream


IMAPIProp::SaveChanges

The IMAPIProp::SaveChanges method makes permanent any changes made to an object since the last save operation.

Quick Info

See IMAPIProp : IUnknown.

HRESULT SaveChanges(

ULONG ulFlags
)
Parameters

ulFlags

[in] Bitmask of flags that controls what happens to the object when the IMAPIProp::SaveChanges method is called.

The following flags can be set:

FORCE_SAVE

Changes should be written to be object, overriding any previous changes made to the object, and the object closed. Read/write access must have been set for the operation to succeed. The FORCE_SAVE flag is used after a previous call to SaveChanges returned MAPI_E_OBJECT_CHANGED.

KEEP_OPEN_READONLY

Changes should be committed and the object should be kept open for reading. No further changes will be made.

KEEP_OPEN_READWRITE

Changes should be committed and the object should be kept open for read/write access. This flag is usually set when the object was initially opened for read/write access. Subsequent changes to the object are allowed.

MAPI_DEFERRED_ERRORS

Allows SaveChanges to return successfully, possibly before the changes have been fully committed.

Return Values

S_OK

The commitment of changes has been successful.

MAPI_E_NO_ACCESS

SaveChanges cannot keep the object open for read-only access, if KEEP_OPEN_READONLY is set, or read/write access, if KEEP_OPEN_READWRITE is set. No changes are committed.

MAPI_E_OBJECT_CHANGED

The object has changed since it was opened.

MAPI_E_OBJECT_DELETED

The object has been deleted since it was opened.

Remarks

The IMAPIProp::SaveChanges method makes property changes permanent for an object that supports the transaction model of processing, such as messages, attachments, address book containers, and messaging user objects. Objects that do not support transactions, such as folders, message stores, and profile sections, make changes permanent immediately. No call to SaveChanges is required.

Because service providers are not required to generate an entry identifier for their objects until all properties have been saved, an object’s PR_ENTRYID property might not be available until after its SaveChanges method has been called. Some providers wait until the KEEP_OPEN_READONLY flag is set on the SaveChanges call. KEEP_OPEN_READONLY indicates that the changes to be saved in the current call will be the last changes that will be made on the object.

Some message store implementations do not show newly created messages in a folder until a client saves the message changes using SaveChanges and releases the message objects using the IUnknown::Release method. In addition, some object implementations cannot generate a PR_ENTRYID property for a newly created object until after SaveChanges has been called, and some can only do so after SaveChanges has been called with KEEP_OPEN_READONLY set in ulFlags.

Notes to Implementers

If you receive the KEEP_OPEN_READONLY flag, you have the option of leaving the object’s access as read/write.

However, in no case can a provider leave an object in a read-only state when the KEEP_OPEN_READWRITE flag is passed.

When a client is saving multiple attachments to multiple messages, it will be calling the SaveChanges method for every attachment and every message. Often clients will set the MAPI_DEFERRED_ERRORS for each of these calls except for the last one. You can return errors either with the last call or earlier. You can even ignore the flag.

If either KEEP_OPEN_READWRITE or KEEP_OPEN_READONLY is set along with MAPI_DEFERRED_ERRORS, you can ignore the error deferment request. If MAPI_DEFERRED_ERRORS is not set in ulFlags, one of the previously deferred errors can be returned for the SaveChanges call.

Notes to Callers

If a client passes KEEP_OPEN_READONLY, then calls the IMAPIProp::SetProps method and then SaveChanges again, the same implementation might stop.

After receiving MAPI_E_NO_ACCESS from a call where you set KEEP_OPEN_READWRITE, you will continue to have read/write access to the object. You can call SaveChanges again, passing either the KEEP_OPEN_READONLY flag or no flags with the KEEP_OPEN_suffix.

Whether a provider supports the KEEP_OPEN_READWRITE flag depends on the provider’s implementation.

To indicate that the only call to be made on the object after SaveChanges will be IUnknown::Release, set no flags for the ulFlags parameter. An error from SaveChanges indicates that it could not make the pending changes permanent. Different providers handle the absence of flags on the SaveChanges call differently. Some treat this state as the same as KEEP_OPEN_READONLY; others interpret it as the same as KEEP_OPEN_READWRITE. Still other providers shut down the object when they receive no flags on the SaveChanges call.

Some properties, typically computed properties, cannot be processed until you call SaveChanges and, in particular cases, Release.

When making bulk changes, such as saving attachments to multiple messages, defer error processing by setting the MAPI_DEFERRED_ERRORS flag in ulFlags. If you are saving multiple attachments to multiple messages, make one SaveChanges call to each attachment and one SaveChanges call to each message. Set the MAPI_DEFERRED_ERRORS flag for each attachment call and for all messages except for the last one.

If SaveChanges returns MAPI_E_OBJECT_CHANGED, check if the original object has been modified. If so, warn the user, who can either request that the changes overwrite the previous changes or save the object somewhere else. If the original object has been deleted, warn the user so that the user can be given the opportunity to save the object in an alternate location.

You cannot call SaveChanges with the FORCE_SAVE flag on an open object that has been deleted.

If SaveChanges returns an error, then the object whose changes were to be saved remains open, regardless of the flags set in the ulFlags parameter.

For more information, see Saving Properties.


IMAPIProp::SetProps

The IMAPIProp::SetProps method updates one or more properties.

Quick Info

See IMAPIProp : IUnknown.

HRESULT SetProps(

ULONG cValues,
LPSPropValue lpPropArray,
LPSPropProblemArray FAR * lppProblems
)
Parameters

cValues

[in] Count of property values pointed to by the lpPropArray parameter. The cValues parameter must not be zero.

lpPropArray

[in] Pointer to an array of SPropValue structures holding property values to be updated.

lppProblems

[in, out] On input, can be NULL, indicating no need for error information, or a pointer to a pointer to an SPropProblemArray structure. If lppProblems is a valid pointer on input, SetProps returns detailed information about errors in updating one or more properties.

Return Values

S_OK

The properties were successfully updated.

The following values can be returned in the SPropProblemArray structure, but not as return values for SetProps:

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

MAPI_E_COMPUTED

The property cannot be updated because it is read-only, computed by the service provider responsible for the object.

MAPI_E_INVALID_TYPE

The property type is invalid.

MAPI_E_NO_ACCESS

An attempt was made to modify a read-only object or to access an object for which the user has insufficient permissions.

MAPI_E_NOT_ENOUGH_MEMORY

The property cannot be updated because it is larger than the RPC buffer size.

MAPI_E_UNEXPECTED_TYPE

The property type is not the type expected by the calling implementation.

Remarks

The IMAPIProp::SetProps method updates one or more properties.

Notes to Implementers

Ignore the PR_NULL property tag and all properties with a type of PT_ERROR; make no changes and report no problems in the SPropProblemArray structure.

Return MAPI_E_INVALID_PARAMETER if a property of type PT_OBJECT is included in the property value array. Also return this error if a multivalued property is included in the array and its cValues member is set to zero.

If the call succeeds overall but there are problems with setting some of the properties, return S_OK and place information about the problems in the appropriate entry of the SPropProblemArray structure pointed to by the lppProblems parameter.

Notes to Callers

Depending on the service provider, you might also be able to change the property type by passing a property tag containing a different type than was previously used with a given property identifier.

If you include a property tag for a property that is unsupported by the object and the implementation of SetProps allows the creation of new properties, the property is added to the object. Any previous value stored with the property identifier used for the new property is discarded.

Note that the S_OK return value does not guarantee that all of the properties were successfully updated. Some providers cache SetProps calls until they receive a call that requires provider intervention, such as IMAPIProp::SaveChanges or IMAPIProp::GetProps. Therefore, it is possible to receive error values relating to the SetProps call with the later calls.

If SetProps returns S_OK, check the SPropProblemArray structure pointed to by lppProblems for problems updating individual properties. If SetProps returns an error, do not check the property problem array. Instead, call the object’s IMAPIProp::GetLastError method.

When updating large properties, SetProps can fail and return MAPI_E_NOT_ENOUGH_MEMORY. There is no maximum size for properties, and different objects can have different limits. If you deal with potentially large properties be prepared to call IMAPIProp::OpenProperty with IID_IStream as the interface identifier if SetProps returns this error value.

Call the MAPIFreeBuffer function to free the SPropProblemArray structure.

See Also

IMAPIProp::GetProps, IMAPIProp::SaveChanges, MAPIFreeBuffer, SPropProblemArray, SPropValue


IMAPISession : IUnknown

The IMAPISession interface is used to manage objects associated with a MAPI logon session.

Quick Info

Header file:	MAPIX.H
Exposed by:	Session objects
Implemented by:	MAPI
Called by:	Client applications and MAPI
Corresponding pointer type:	LPMAPISESSION
Vtable Order

GetLastError	Returns a MAPIERROR structure containing information about the previous session error.
GetMsgStoresTable	Provides access to the message store table, a table with information about all of the message stores in the session profile.
OpenMsgStore	Opens a message store and returns an IMsgStore pointer for further access.
OpenAddressBook	Opens MAPI’s integrated address book and returns an IAddrBook pointer for further access.
OpenProfileSection	Opens a section of the current profile and returns an IProfSect pointer for further access.
GetStatusTable	Provides access to the status table, a table with information about all of the MAPI resources in the session.
OpenEntry	Opens an object and returns an interface pointer for further access.
CompareEntryIDs	Compares two entry identifiers to determine if they refer to the same object.
Advise	Registers to receive notification of specified events affecting the session.
Unadvise	Cancels the sending of notifications previously set up with a call to the IMAPISession::Advise method.
MessageOptions	Displays a dialog box showing option properties for a particular address type and message.
QueryDefaultMessageOpt	Retrieves the message option properties for a particular address type.
EnumAdrTypes	Returns the address types that can be handled by all of the transport providers in the session.
QueryIdentity	Returns the entry identifier of the object that provides the primary identity for the session.
Logoff	Ends a MAPI session.
SetDefaultStore	Establishes a message store as the default message store for the session.
AdminServices	Returns an IMsgServiceAdmin pointer for making changes to message services.
ShowForm	Displays a form.
PrepareForm	Creates a numeric token to be used by the IMAPISession::ShowForm method to access a message.


IMAPISession::AdminServices

The IMAPISession::AdminServices method returns an IMsgServiceAdmin pointer for making changes to message services.

Quick Info

See IMAPISession : IUnknown.

HRESULT AdminServices(

ULONG ulFlags,
LPSERVICEADMIN FAR * lppServiceAdmin
)
Parameters

ulFlags

Reserved; must be zero.

lppServiceAdmin

[out] Pointer to a pointer to a message service administration object.

Return Values

S_OK

A pointer to a message service administration object was successfully returned.

Notes to Callers

The IMAPISession::AdminServices method creates a message service administration object — an object that supports the IMsgServiceAdmin interface — and returns a pointer. With this pointer, you can call IMsgServiceAdmin methods to make changes to any of the message services in the session profile. Be aware that these changes do not take affect until the next session; the current session is unaffected.

See Also

IMsgServiceAdmin : IUnknown, IProfAdmin::AdminServices


IMAPISession::Advise

The IMAPISession::Advise method registers to receive notification of specified events affecting the session.

Quick Info

See IMAPISession : IUnknown.

HRESULT Advise(

ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the address book or message store object about which notifications should be generated or NULL, indicating that the client is registering to receive notifications about events that affect only the session.

ulEventMask

[in] A mask of values indicating the types of notification events that the client is interested in and should be included in the registration. If lpEntryID is NULL, MAPI automatically registers the client for critical error events for the session — the only type of event supported by the session.

When lpEntryID points to an entry identifier, the following values are valid for the ulEventMask parameter:

fnevCriticalError

Registers for notifications about severe errors, such as insufficient memory.

fnevExtended

Registers for notifications about events specific to the particular address book or message store provider.

fnevNewMail

Registers for notifications about the arrival of new messages.

fnevObjectCreated

Registers for notifications about the creation of a new object.

fnevObjectCopied

Registers for notifications about an object being copied.

fnevObjectDeleted

Registers for notifications about an object being deleted.

fnevObjectModified

Registers for notifications about an object being modified.

fnevObjectMoved

Registers for notifications about an object being moved.

fnevSearchComplete

Registers for notifications about the completion of a search operation.

lpAdviseSink

[in] Pointer to an advise sink object to receive the subsequent notifications. This advise sink object must have already been allocated.

lpulConnection

[out] Pointer to a nonzero number that represents the connection between the caller’s advise sink object and the session.

Return Values

S_OK

The registration was successful.

MAPI_E_INVALID_ENTRYID

The entry identifier pointed to by lpEntryID does not represent a valid entry identifier.

MAPI_E_NO_SUPPORT

The service provider responsible for the entry identifier pointed to by lpEntryID either does not support the type of events specified in the ulEventMask parameter or does not support notification.

MAPI_E_UNKNOWN_ENTRYID

The entry identifier pointed to by lpEntryID cannot be handled by any of the service providers in the profile.

Remarks

The IMAPISession::Advise method establishes a connection between the caller’s advise sink object, the session, and, as an option, a service provider. This connection is used to send notifications to the advise sink when one or more events as specified in the ulEventMask parameter occur to the object pointed to by lpEntryID. When lpEntryID is NULL, the target object is the session and notifications are sent for critical error events only.

When lpEntryID points to a valid entry identifier, MAPI calls the Advise method of the logon object belonging to the responsible service provider. For example, if lpEntryID points to the entry identifier of a distribution list, MAPI calls the appropriate address book provider’s IABLogon::Advise method.

To send a notification, either the service provider or MAPI calls the registered advise sink’s IMAPIAdviseSink::OnNotify method. One of the parameters to OnNotify, a notification structure, contains information that describes the specific event.

Notes to Callers

On systems that support multiple threads of execution, the call to OnNotify can also occur on any thread at any time. If you must be assured that notifications only occur at a particular time on a particular thread, call HrThisThreadAdviseSink to generate the advise sink object that you pass to Advise.

After a call to Advise has succeeded and before Unadvise has been called to cancel the registration, be prepared for the advise sink object to be released. You should release your advise sink object after Advise returns unless you have a specific long-term use for it.

For an overview of the notification process, see Event Notification in MAPI.

For more information on handling notifications, see Handling Notifications.

See Also

NOTIFICATION, HrThisThreadAdviseSink, IMAPIAdviseSink::OnNotify, IMAPISession::Unadvise


IMAPISession::CompareEntryIDs

The IMAPISession::CompareEntryIDs method compares two entry identifiers to determine if they refer to the same object.

Quick Info

See IMAPISession : IUnknown.

HRESULT CompareEntryIDs(

ULONG cbEntryID1,
LPENTRYID lpEntryID1,
ULONG cbEntryID2,
LPENTRYID lpEntryID2,
ULONG ulFlags,
ULONG FAR * lpulResult
)
Parameters

cbEntryID1

[in] Count of bytes in the entry identifier pointed to by the lpEntryID1 parameter.

lpEntryID1

[in] Pointer to the first entry identifier to be compared.

cbEntryID2

[in] Count of bytes in the entry identifier pointed to by the lpEntryID2 parameter.

lpEntryID2

[in] Pointer to the second entry identifier to be compared.

ulFlags

Reserved; must be zero.

lpulResult

[out] Pointer to the result of the comparison, set toTRUE if the two entry identifiers refer to the same object and FALSE otherwise.

Return Values

S_OK

The comparison was successful.

MAPI_E_UNKNOWN_ENTRYID

One or both of the entry identifiers specified as parameters do not refer to objects, possibly because these objects are unopened and inaccessible at present.

Remarks

The IMAPISession::CompareEntryIDs method compares two entry identifiers belonging to a single service provider to determine whether they refer to the same object. MAPI extracts the MAPIUID portion from the entry identifiers to determine the service provider responsible for the objects and calls its logon object’s CompareEntryIDs method to perform the comparison.

Notes to Callers

CompareEntryIDs is useful because an object can have more than one valid entry identifier; such a situation can occur, for example, after a new version of a service provider is installed.

If CompareEntryIDs returns an error, do not take any action based on the result of the comparison. Instead, take the most conservative approach possible. CompareEntryIDs might fail if, for example, one or both of the entry identifiers contains an invalid MAPIUID.


IMAPISession::EnumAdrTypes

The IMAPISession::EnumAdrTypes method returns the address types that can be handled by all of the transport providers in the session.

Quick Info

See IMAPISession : IUnknown.

HRESULT EnumAdrTypes(

ULONG ulFlags,
ULONG FAR * lpcAdrTypes,
LPTSTR FAR * FAR * lpppszAdrTypes
)
Parameters

ulFlags

[in] Bitmask of flags that indicates the format for the returned address types. The following flag can be set:

MAPI_UNICODE

The address types are in the Unicode format. If the MAPI_UNICODE flag is not set, the address types are in the ANSI format.

lpcAdrTypes

[out] Pointer to a count of address types pointed to by the lpppszAdrTypes parameter.

lpppszAdrTypes

[out] Pointer to an array of pointers to address types.

Return Values

S_OK

The address types were successfully retrieved.

Remarks

The IMAPISession::EnumAdrTypes method returns a list of the address types that can be handled by all of the active transport providers in the session. The address types for transport providers that are not currently loaded are not included in the list. Transport providers register to handle one or more address types when MAPI calls their IXPLogon::AddressTypes method.

Notes to Callers

Call MAPIFreeBuffer to release the string array pointed to by the lpppszAdrTypes parameter .

See Also

MAPIFreeBuffer


IMAPISession::GetLastError

The IMAPISession::GetLastError method returns a MAPIERROR structure containing information about the previous session error.

Quick Info

See IMAPISession : IUnknown.

HRESULT GetLastError(

HRESULT hResult,
ULONG ulFlags,
LPMAPIERROR FAR * lppMAPIError
)
Parameters

hResult

[in] HRESULT data type containing the error value generated in the previous method call.

ulFlags

[in] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] Pointer to a pointer to a MAPIERROR structure containing version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if MAPI cannot supply a MAPIERROR structure with appropriate information.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

The MAPI_UNICODE flag was set and the session does not support Unicode.

Remarks

The IMAPISession::GetLastError method retrieves information about the last error that was returned by an IMAPISession method call. Clients can provide their users with detailed information about the error by including this information in a dialog box.

Notes to Callers

You can make use of the MAPIERROR structure pointed to by the lppMAPIError parameter, if MAPI supplies one, only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was or has nothing more to report about the error. In this situation, GetLastError returns a pointer to NULL in lppMAPIError instead.

For more information about the GetLastError method, see Using Extended Errors.

See Also

MAPIERROR, MAPIFreeBuffer


IMAPISession::GetMsgStoresTable

The IMAPISession::GetMsgStoresTable method provides access to the message store table, a table with information about all of the message stores in the session profile.

Quick Info

See IMAPISession : IUnknown.

HRESULT GetMsgStoresTable(

ULONG ulFlags,
LPMAPITABLE FAR * lppTable
)
Parameters

ulFlags

[in] Bitmask of flags that determine the format for columns that are character strings. The following flag can be set:

MAPI_UNICODE

The string columns are in Unicode format. If the MAPI_UNICODE flag is not set, the string columns are in ANSI format.

lppTable

[out] Pointer to a pointer to the message store table.

Return Values

S_OK

The table was successfully returned.

MAPI_E_BAD_CHARWIDTH

The MAPI_UNICODE flag was set and MAPI does not support Unicode at present.

Remarks

The IMAPISession::GetMsgStoresTable method retrieves a pointer to the message store table,  a table maintained by MAPI that contains information about each open message store in the profile.

For a complete list of required and optional columns in the message store table, see Message Store Table.

Notes to Callers

Because MAPI updates the message store table during the session whenever changes occur, call the Advise method of the message store table to register to be notified of these changes. Possible changes include the addition of new message stores, removal of existing stores, and changes to the default store.

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the format of the columns returned from the following IMAPITable methods:

•	IMAPITable::QueryColumns

•	IMAPITable::QueryRows

This flag also controls the property types in the sort order returned by the IMAPITable::QuerySortOrder method.

See Also

IMAPISession::OpenMsgStore, IMAPITable::QueryColumns, IMAPITable::QueryRows, IMAPITable::QuerySortOrder, IMAPITable::SetColumns, IMAPITable::SortTable


IMAPISession::GetStatusTable

The IMAPISession::GetStatusTable method provides access to the status table, a table with information about all of the MAPI resources in the session.

Quick Info

See IMAPISession : IUnknown.

HRESULT GetStatusTable(

ULONG ulFlags,
LPMAPITABLE FAR * lppTable
)
Parameters

ulFlags

[in] Bitmask of flags that determine the format for columns that are character strings. The following flag can be set:

MAPI_UNICODE

The string columns are in the Unicode format. If the MAPI_UNICODE flag is not set, the string columns are in the ANSI format.

lppTable

[out] Pointer to a pointer to the status table.

Return Values

S_OK

The table was successfully returned.

Remarks

The IMAPISession::GetStatusTable method provides access to the status table — a table with information about all of the MAPI resources in the session. There is one row in the table with information about the MAPI subsystem, one row for the MAPI spooler, one row for the integrated address book, and one row for each of the service providers in the profile.

For a complete list of required and optional columns in the status table, see Status Table.

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the format of the columns returned from the following IMAPITable methods:

•	IMAPITable::QueryColumns

•	IMAPITable::QueryRows

This flag also controls the property types in the sort order returned by the IMAPITable::QuerySortOrder method.

See Also

IMAPITable::QueryColumns, IMAPITable::QueryRows, IMAPITable::QuerySortOrder, IMAPITable::SetColumns, IMAPITable::SortTable


IMAPISession::Logoff

The IMAPISession::Logoff method ends a MAPI session.

Quick Info

See IMAPISession : IUnknown.

HRESULT Logoff(

ULONG ulUIParam,
ULONG ulFlags,
ULONG ulReserved
)
Parameters

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows to be displayed if possible. This parameter is ignored if the MAPI_LOGOFF_UI flag is not set.

ulFlags

[in] Bitmask of flags that control the logoff operation. The following flags can be set:

MAPI_LOGOFF_SHARED

If this session is shared, all clients logged on using the shared session should be notified of the logoff in progress. The clients should log off. Any client using the shared session can set this flag. MAPI_LOGOFF_SHARED is ignored if the current session is not shared.

MAPI_LOGOFF_UI

Logoff can display a dialog box during the operation, possibly prompting the user for confirmation.

ulReserved

Reserved; must be zero.

Return Values

S_OK

The logoff operation was successful.

Remarks

The IMAPISession::Logoff method ends a MAPI session. When Logoff returns, none of the methods except for Release can be called. IMAPISession::Logoff is similar in functionality to the Simple MAPI function MAPILogoff.

Notes to Callers

When Logoff returns, release the session object by calling its IUnknown::Release method.

For more information about ending a session, see Ending a MAPI Session.

See Also

MAPILogoff


IMAPISession::MessageOptions

The IMAPISession::MessageOptions method displays a dialog box showing option properties for a particular address type and message.

Quick Info

See IMAPISession : IUnknown.

HRESULT MessageOptions(

ULONG ulUIParam,
ULONG ulFlags,
LPTSTR lpszAdrType,
LPMESSAGE lpMessage
)
Parameters

ulUIParam

[in] Handle of the parent window for the dialog box.

ulFlags

[in] Bitmask of flags that controls the format of the message option properties. The following flag can be set:

MAPI_UNICODE

The message option properties are in the Unicode format. If the MAPI_UNICODE flag is not set, the message option properties are in the ANSI format.

lpszAdrType

[in] Pointer to the address type for which option properties should be displayed or NULL, indicating that all message option properties for all transport providers should be displayed.

lpMessage

[in] Pointer to the message for which option properties should be displayed.

Return Values

S_OK

The dialog box was successfully displayed.

MAPI_E_NOT_FOUND

No options were registered for the message and address type.

Remarks

The IMAPISession::MessageOptions method presents a dialog box displaying properties that relate to a particular message and addess type. These properties are under the control of the transport provider handling the address type. Users can make changes to the properties, but these changes do not take affect until the client calls the message’s IMAPIProp::SaveChanges method.

Users can make changes to option properties that apply to:

•	A particular message and address type.

•	All messages for a particular address type.

Changes made to the option properties for a particular message and address type do not affect the option properties that apply to all messages.

For more information about working with message option properties, see Message and Recipient Options.


IMAPISession::OpenAddressBook

The IMAPISession::OpenAddressBook method opens MAPI’s integrated address book, returning an IAddrBook pointer for further access.

Quick Info

See IMAPISession : IUnknown.

HRESULT OpenAddressBook(

ULONG ulUIParam,
LPCIID lpInterface,
ULONG ulFlags,
LPADRBOOK FAR * lppAdrBook
)
Parameters

ulUIParam

[in] Handle of the parent window for the common address dialog box and other related displays.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the address book. Passing NULL results in a pointer to the address book’s standard interface, or IAddrBook, being returned.

ulFlags

[in] Bitmask of flags that the opening of the address book. The following flag can be set:

AB_NO_DIALOG

Suppresses the display of dialog boxes. If the AB_NO_DIALOG flag is not set, the address book providers contributing to the integrated address book can prompt the user for any necessary information.

lppAdrBook

[out] Pointer to a pointer to the address book.

Return Values

S_OK

The address book was successfully opened.

MAPI_E_UNKNOWN_CPID

The server is not configured to support the client's code page.

MAPI_E_UNKNOWN_LCID

The server is not configured to support the client's locale information.

MAPI_W_ERRORS_RETURNED

The call succeeded, but the containers of one or more address book providers could not opened. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPISession::OpenAddressBook method opens the MAPI integrated address book — a collection of the top-level containers of all of the address book providers in the profile. The pointer that is returned in the lppAdrBook parameter provides further access to the contents of the address book, allowing the caller to perform tasks such as opening individual containers, finding messaging users, and displaying common address dialog boxes.

Notes to Callers

OpenAddressBook returns MAPI_W_ERRORS_RETURNED if it cannot load one or more of the address book providers in the profile. This value is a warning, not an error value; handle it as you would S_OK. OpenAddressBook always returns a valid pointer in the lppAdrBook parameter, regardless of how many of the address book providers failed to load. Therefore, you must always call the address book’s IUnknown::Release method at some point before logging off.

When OpenAddressBook returns MAPI_W_ERRORS_RETURNED, call IMAPISession::GetLastError to obtain a MAPIERROR structure containing information about the failing providers. A single MAPIERROR structure is returned that contains information supplied by all of the providers.

See Also

IMAPISession::GetLastError, MAPIERROR


IMAPISession::OpenEntry

The IMAPISession::OpenEntry method opens an object and returns an interface pointer for further access.

Quick Info

See IMAPISession : IUnknown.

HRESULT OpenEntry(

ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
ULONG ulFlags,
ULONG FAR * lpulObjType,
LPUNKNOWN FAR * lppUnk
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the object to open.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the opened object. Passing NULL results in the object’s standard interface being returned. For example, if the object to be opened is a message, the standard interface is IMessage; for folders, it is IMAPIFolder. The standard interfaces for address book objects are IDistList for a distribution list and IMailUser for a messaging user.

ulFlags

[in] Bitmask of flags that controls how the object is opened. The following flags can be used:

MAPI_BEST_ACCESS

Requests that the object be opened with the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write access, the object should be opened with read/write access; if the client has read-only access, the object should be opened with read-only access.

MAPI_DEFERRED_ERRORS

Allows OpenEntry to return successfully, possibly before the object is fully accessible to the calling client. If the object is not accessible, making a subsequent object call can result in an error.

MAPI_MODIFY

Requests read/write access. By default, objects are opened with read-only access, and clients should not work on the assumption that read/write access has been granted.

lpulObjType

[out] Pointer to the type of the opened object.

lppUnk

[out] Pointer to a pointer to the opened object.

Return Values

S_OK

The object was opened successfully.

MAPI_E_NO_ACCESS

An attempt was made to modify a read-only object or an attempt was made to access an object for which the user has insufficient permissions.

MAPI_E_NOT_FOUND

There is not an object associated with the entry identifier passed in lpEntryID.

MAPI_E_UNKNOWN_ENTRYID

The entry identifier passed in the lpEntryID parameter is in an unrecognizable format. This value is typically returned if the service provider that contains the object is not open.

Remarks

The IMAPISession::OpenEntry method opens a message store or address book object, returning a pointer to an interface that can be used to access the object.

Notes to Callers

Call IMAPISession::OpenEntry only when you do not know what kind of object you are opening. If you know you are opening a folder or a message, call IMsgStore::OpenEntry. If you know you are opening an address book container, a messaging user, or a distribution list, call IAddrBook::OpenEntry. These more specific methods are faster than IMAPISession::OpenEntry.

MAPI opens all objects with read-only access, unless you set the MAPI_MODIFY or MAPI_BEST_ACCESS flag in the ulFlags parameter. Setting one of these flags does not guarantee a particular type of access; the permissions that you are granted depends on the service provider, your access level, and the object. To determine the access level of the opened object, retrieve its PR_ACCESS_LEVEL property.

Calling OpenEntry and setting lpEntryID to point to the entry identifier of a message store is equivalent to calling the IMAPISession::OpenMsgStore method with the MDB_NO_DIALOG flag set. The flag settings are also equivalent, with the exception that to request read/write access with OpenMsgStore, you must set the MDB_WRITE flag rather than MAPI_MODIFY.

Check the value returned in the lpulObjType parameter to determine that the object type returned is what you expected. If the object type is not the type you expected, cast the pointer from the lppUnk parameter to a pointer of the appropriate type. For example, if you are opening a folder, cast lppUnk to a pointer of type LPMAPIFOLDER.

See Also

IAddrBook::OpenEntry, IMAPISession::OpenMsgStore, IMsgStore::OpenEntry


IMAPISession::OpenMsgStore

The IMAPISession::OpenMsgStore method opens a message store and returns an IMsgStore pointer for further access.

Quick Info

See IMAPISession : IUnknown.

HRESULT OpenMsgStore(

ULONG ulUIParam,
ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
ULONG ulFlags,
LPMDB FAR * lppMDB
)
Parameters

ulUIParam

[in] Handle of the parent window for the common address dialog box and other related displays.

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the message store to be opened. The lpEntryID parameter must not be NULL.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the message store. Passing NULL results in a pointer to its standard interface being returned in the lppMDB parameter. The standard interface for a message store is IMsgStore.

ulFlags

[in] Bitmask of flags that the open operation. The following flags can be used:

MAPI_BEST_ACCESS

Requests that the message store be opened with the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write access, the message store should be opened with read/write access; if the client has read-only access, the message store should be opened with read-only access.

MAPI_DEFERRED_ERRORS

Allows OpenMsgStore to return successfully, possibly before the message store is fully accessible to the calling client. If the message store is not accessible, making a subsequent object call can result in an error.

MDB_NO_DIALOG

Prevents the display of logon dialog boxes. If this flag is set, and OpenMsgStore does not have enough configuration information to open the message store without the user’s help, it returns MAPI_E_LOGON_FAILED. If this flag is not set, the message store provider can prompt the user to correct a name or password, to insert a disk, or to perform other actions necessary to establish connection to the message store.

MDB_NO_MAIL

The message store should not be used for sending or receiving mail. When this flag is set, MAPI does not notify the MAPI spooler that this message store is being opened.

MDB_TEMPORARY

Instructs MAPI that the message store is not permanent and should not be added to the message store table. This flag is used to log on the message store so that information can be retrieved programmatically from the profile section.

MDB_WRITE

Requests read/write access to the message store.

lppMDB

[out] Pointer to a pointer to the message store.

Return Values

S_OK

The message store was successfully opened.

MAPI_E_NO_ACCESS

An attempt was made to access a message store for which the user has insufficient permissions.

MAPI_E_NOT_FOUND

The message store indicated by lpEntryID does not exist.

MAPI_E_UNKNOWN_CPID

The server is not configured to support the client's code page.

MAPI_E_UNKNOWN_LCID

The server is not configured to support the client's locale information.

MAPI_W_ERRORS_RETURNED

The call succeeded, but the message store provider has error information available. When this warning is returned, the call should be handled as successful. To get the error information from the provider, call the IMAPISession::GetLastError method. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPISession::OpenMsgStore method opens a particular message store.

Notes to Callers

The default access level for message stores is read-only. If you set the MDB_WRITE flag, you may or may not be granted read/write access. The final level of access that MAPI assigns to the message store depends on your level of access, the message store itself, and the message store provider.

If you call OpenMsgStore to open a message store with read-only access:

•	The store’s PR_STORE_SUPPORT_MASK property will not have its STORE_MODIFY_OK and STORE_CREATE_OK bits set.

•	Calls to open one of the message store’s messages or folders using IMAPISession::OpenEntry with the MAPI_MODIFY flag set will fail.

•	Calls to open one of the properties of the message store’s messages or folders using IMAPIProp::OpenProperty and the MAPI_MODIFY will fail.

•	Calls to any of the following methods will fail:

IMAPIFolder::CreateMessage

IMAPIFolder::DeleteMessages

IMAPIFolder::CreateFolder

IMAPIFolder::DeleteFolder

IMAPIFolder::SetMessageStatus

IMAPIProp::SetProps

IMAPIProp::DeleteProps

•	Calls to the following methods fail if the destination for the copied message is read-only, whether it be the same as the source message store or another read-only store:

IMAPIFolder::CopyMessages

IMAPIFolder::CopyFolder

IMAPIProp::CopyTo


IMAPISession::OpenProfileSection

The IMAPISession::OpenProfileSection method opens a section of the current profile and returns an IProfSect pointer for further access.

Quick Info

See IMAPISession : IUnknown.

HRESULT OpenProfileSection(

LPMAPIUID lpUID,
LPCIID lpInterface,
ULONG ulFlags,
LPPROFSECT FAR * lppProfSect
)
Parameters

lpUID

[in] Pointer to the MAPIUID structure identifying the profile section.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the profile section. Passing NULL results in a pointer to its standard interface being returned in the lppProfSect parameter. The standard interface for a profile section is IProfSect.

ulFlags

[in] Bitmask of flags that controls access to the profile section. The following flags can be set:

MAPI_DEFERRED_ERRORS

Allows OpenProfileSection to return successfully, possibly before the profile section is fully accessible to the calling client. If the profile section is not accessible, making a subsequent call to it can result in an error.

MAPI_MODIFY

Requests read/write access. By default, profile sections are opened with read-only access, and clients should not work on the assumption that read/write access has been granted.

lppProfSect

[out] Pointer to a pointer to the profile section.

Return Values

S_OK

The profile section was successfully opened.

MAPI_E_NO_ACCESS

An attempt was made to access a profile section for which the caller has insufficient permissions.

MAPI_E_NOT_FOUND

The requested profile section does not exist.

Remarks

The IMAPISession::OpenProfileSection method opens a profile section — or object that supports the IProfSect interface. Profile sections are used for reading information from and writing information to the session profile.

OpenProfileSection cannot be used to open profile sections owned by individual service providers.

Notes to Callers

Multiple clients can open a profile section with read-only access, but only one client can open a profile section with read/write access. If another client has a profile section open that you attempt to open by calling OpenProfileSection with the MAPI_MODIFY flag set, the call will fail, returning MAPI_E_NO_ACCESS.

A read-only open operation fails if the section is open for writing.

You can create a profile section by calling OpenProfileSection with the MAPI_MODIFY flag and a non-existent MAPIUID structure in the lpUID parameter. Make sure you specify MAPI_MODIFY. If you set lpUID to point to a nonexistent MAPIUID and OpenProfileSection is set to use the default access mode of read-only, the call fails with MAPI_E_NOT_FOUND.

See Also

IMAPIProp : IUnknown, IProfSect : IMAPIProp, MAPIUID


IMAPISession::PrepareForm

The IMAPISession::PrepareForm method creates a numeric token to be used by the IMAPISession::ShowForm method to access a message.

Quick Info

See IMAPISession : IUnknown.

HRESULT PrepareForm(

LPCIID lpInterface,
LPMESSAGE lpMessage,
ULONG FAR * lpulMessageToken
)
Parameters

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the message. Passing NULL results in the standard interface, or IMessage, being used. The lpInterface parameter must be NULL or IID_IMessage.

lpMessage

[in] Pointer to the message to be displayed in the form.

lpulMessageToken

[out] Pointer to a message token, which is used by the IMAPISession::ShowForm method to access the message pointed to by lpMessage.

Return Values

S_OK

The form preparation was successful.

Remarks

The IMAPISession::PrepareForm method creates a message token for the message pointed to by the lpMessage parameter and calls the message’s IUnknown::AddRef method. This token is passed in the ulMessageToken parameter to IMAPISession::ShowForm.

Notes to Callers

If the call to PrepareForm succeeds, release the message pointed to by lpMessage by calling its IUnknown::Release method before calling ShowForm. Failure to release the message before calling ShowForm can cause memory leaks.

See Also

IMAPISession::ShowForm


IMAPISession::QueryDefaultMessageOpt

The IMAPISession::QueryDefaultMessageOpt method retrieves the message option properties for a particular address type.

Quick Info

See IMAPISession : IUnknown.

HRESULT QueryDefaultMessageOpt(

LPTSTR lpszAdrType,
ULONG ulFlags,
ULONG FAR * lpcValues,
LPSPropValue FAR * lppOptions
)
Parameters

lpszAdrType

[in] Pointer to an address type.

ulFlags

[in] Bitmask of flags that controls the format of the string property values pointed to by lppOptions. The following flag can be set:

MAPI_UNICODE

The property values should be in the Unicode format. If the MAPI_UNICODE flag is not set, the property values should be in the ANSI format.

lpcValues

[out] Pointer to a count of property values pointed to by the lppOptions parameter.

lppOptions

[out] Pointer to a pointer to an array of SPropValue structures describing message option properties.

Return Values

S_OK

The message option properties were successfully returned.

Remarks

The IMAPISession::QueryDefaultMessageOpt method retrieves the one or more message option properties that a transport provider supports for the address type pointed to by the lpszAdrType parameter. Message option properties control a message’s behavior after it is submitted to the transport provider; they are part of the message envelope, not its content.

The property value array pointed to by lppOptions includes the property tags and values for each of the message option properties.


IMAPISession::QueryIdentity

The IMAPISession::QueryIdentity method returns the entry identifier of the object that provides the primary identity for the session.

Quick Info

See IMAPISession : IUnknown.

HRESULT QueryIdentity(

ULONG FAR * lpcbEntryID,
LPENTRYID FAR * lppEntryID
)
Parameters

lpcbEntryID

[out] Pointer to the count of bytes in the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[out] Pointer to a pointer to the entry identifier of the object providing the primary identity.

Return Values

S_OK

The primary identity was successfully returned.

MAPI_W_NO_SERVICE

The call succeeded, but there is no primary identity for the session. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPSession::QueryIdentity method retrieves the primary identity for the current session. The primary identity is an object, typically a messaging user, that represents the user of a session. Although many service providers in multiple message services can provide the primary identity for a session, MAPI designates a single service provider. The service provider supplying the primary identity sets the following:

•	STATUS_PRIMARY_IDENTITY flag in the PR_RESOURCE_FLAGS property

•	PR_IDENTITY_DISPLAY

•	PR_IDENTITY_ENTRYID

•	PR_IDENTITY_SEARCH_KEY

If the service provider supplying the primary identity belongs to a message service, the other service providers in the message service also set the PR_IDENTITY properties. These properties are published in the session’s status table.

If possible, QueryIdentity returns the value for the PR_IDENTITY_ENTRYID property from the status row tagged with STATUS_PRIMARY_IDENTITY. If the PR_IDENTITY_ENTRYID property is missing from the primary identity row, QueryIdentity returns a one-off entry identifier built with other information from that row.

If the STATUS_PRIMARY_IDENTITY flag is missing from all of the PR_RESOURCE_FLAG columns in the status table, QueryIdentity returns the first entry identifier that it finds. When there is no appropriate entry identifier to return, QueryIdentity succeeds with the warning MAPI_W_NO_SERVICE and points lppEntryID to a hard-coded entry identifier.

Notes to Callers

You can call the IMsgServiceAdmin::SetPrimaryIdentity method to assign a message service the task of supplying the session’s primary identity.

Another way to retrieve the primary identity is by searching the status table for the row with the PR_RESOURCE_FLAGS columns set to STATUS_PRIMARY_IDENTITY. For more information on this alternate way of retrieving identity information, see Using the Status Table and Status Objects.

When you have finished using the entry identifier for the primary identity returned by QueryIdentity, free its memory by calling the MAPIFreeBuffer function.

For more information about identity in general, see Primary Identity.

For more information about retrieving MAPI session identity, see Retrieving Primary and Provider Identity.

See Also

IMAPISession::OpenEntry, IMsgServiceAdmin::SetPrimaryIdentity, MAPIFreeBuffer


IMAPISession::SetDefaultStore

The IMAPISession::SetDefaultStore method establishes a message store as the default message store for the session.

Quick Info

See IMAPISession : IUnknown.

HRESULT SetDefaultStore(

ULONG ulFlags,
ULONG cbEntryID,
LPENTRYID lpEntryID
)
Parameters

ulFlags

[in] Bitmask of flags that controls the setting of the default message store. These flags are mutually exclusive; only one of the following flags can be set:

MAPI_DEFAULT_STORE

Establishes the message store as the session default. Updates the message store’s status table row by setting the STATUS_DEFAULT_STORE flag in the PR_RESOURCE_FLAGS column.

MAPI_PRIMARY_STORE

Establishes the message store as the store to be used at logon. If the message store is not the default store, clients should make it the default. Updates the message store’s status table row by setting the STATUS_PRIMARY_STORE flag in the PR_RESOURCE_FLAGS column.

MAPI_SECONDARY_STORE

Establishes the message store as the store to be used at logon if the primary message store is not available. If a client cannot open the primary store, it should open the secondary store and set it as the default. Updates the message store’s status table row by setting the STATUS_SECONDARY_STORE flag in the PR_RESOURCE_FLAGS column.

MAPI_SIMPLE_STORE_PERMANENT

Establishes the message store as the session default for Simple MAPI and CMC clients and sets the STATUS_SIMPLE_STORE flag in the message store’s PR_RESOURCE_FLAGS property in its status table row, message store table row, and in the session profile.

MAPI_SIMPLE_STORE_TEMPORARY

Establishes the message store as the session default for Simple MAPI and CMC clients and sets the STATUS_SIMPLE_STORE flag in the message store’s PR_RESOURCE_FLAGS property in its status table row and message store table row. The profile is not modified.

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the message store intended as the default. If a client passes NULL in lpEntryID, no message store is selected as the default.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The IMAPISession::SetDefaultStore method establishes a message store as one of the following:

•	Default message store for the session

•	Primary message store for the session

•	Secondary message store for the session

•	Temporary or permanent message store that can be used with Simple MAPI

To establish a message store as the default, the message store must have the following flags set in its PR_STORE_SUPPORT_MASK property:

STORE_SUBMIT_OK

STORE_CREATE_OK

STORE_MODIFY_OK

Notes to Callers

You can determine the default message store for the session by retrieving the status table and searching for the setting of the STATUS_DEFAULT_STORE flag in the PR_RESOURCE_FLAGS column. The row with this setting represents the message store designated as the session default.

When either the MAPI_DEFAULT_STORE or the MAPI_SIMPLE_STORE_PERMANENT flag is set, MAPI updates the profile, message store table, and status table.

Whenever a change is made to the message store default setting, the following notifications are generated:

•	An fnevTableModified event notification is issued for each of the affected rows in both the message store and status table.

•	An internal notification is issued to the MAPI spooler. Operations already in progress are completed without change; new operations involving the default message store, such as message downloading, are processed for the new default store.

See Also

PR_RESOURCE_FLAGS, PR_STORE_SUPPORT_MASK, TABLE_NOTIFICATION


IMAPISession::ShowForm

The IMAPISession::ShowForm method displays a form.

Quick Info

See IMAPISession : IUnknown.

HRESULT ShowForm(

ULONG ulUIParam,
LPMDB lpMsgStore,
LPMAPIFOLDER lpParentFolder,
LPCIID lpInterface,
ULONG ulMessageToken,
LPMESSAGE lpMessageSent,
ULONG ulFlags,
ULONG ulMessageStatus,
ULONG ulMessageFlags,
ULONG ulAccess,
LPSTR lpszMessageClass
)
Parameters

ulUIParam

[in] Handle of the parent window for the form. The ulUIParam parameter must not be NULL if the form has been created using the Electronic Forms Designer (EFD). The ulUIParam parameter can be NULL if the form has been created using C or C++.

lpMsgStore

[in] Pointer to the message store containing the folder pointed to by the lpParentFolder parameter.

lpParentFolder

[in] Pointer to the folder in which the message associated with the ulMessageToken parameter was created.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the message being displayed in the form. The lpInterface parameter must be NULL or IID_IMessage. Passing NULL results in the standard interface, or IMessage, being used.

ulMessageToken

[in] Token associated with the message to be displayed in the form. The ulMessageToken parameter must be set to the contents of the lpulMessageToken parameter from the preceding call to IMAPISession::PrepareForm.

lpMessageSent

Reserved; must be NULL.

ulFlags

[in] Bitmask of flags that controls how and whether the message is saved. The following flags can be set:

MAPI_NEW_MESSAGE

The message has never been saved — that is, its IMAPIProp::SaveChanges method has never been called.

MAPI_POST_MESSAGE

The message should be saved to its parent folder. The message is not processed for sending but posted to the folder instead. If this flag is not set, the message is copied to the Outbox and processed for sending.

ulMessageStatus

[in] Bitmask of flags copied from the PR_MSG_STATUS property of the message associated with the token in the ulMessageToken parameter. The flags provide information on the state of the message.

ulMessageFlags

[in] Bitmask of flags copied from the PR_MESSAGE_FLAGS property of the message associated with the token in the ulMessageToken parameter. These flags provide further information on the state of the message.

ulAccess

[in] Flag indicating the access level for the message being displayed in the form. This information is copied from the PR_ACCESS property of the message associated with the token in the ulMessageToken parameter.

lpszMessageClass

[in] Pointer to the message class of the message being displayed in the form, copied from the PR_MESSAGE_CLASS property of the message associated with the token in the ulMessageToken parameter.

Return Values

S_OK

The form was successfully displayed.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The IMAPISession::ShowForm method displays a message form that has been prepared by the IMAPISession::PrepareForm method.

Notes to Callers

You should only have a single reference to the message passed in the PrepareForm method’s lpMessage parameter.

Be aware that form implementations can return error values other than the ones documented by MAPI. If you are able to use these error values to make a more accurate determination of the error condition, do so. Otherwise, handle these errors in the same manner as you would handle MAPI_E_CALL_FAILED.


IMAPISession::Unadvise

The IMAPISession::Unadvise method cancels the sending of notifications previously set up with a call to the IMAPISession::Advise method.

Quick Info

See IMAPISession : IUnknown.

HRESULT Unadvise(

ULONG ulConnection
)
Parameters

ulConnection

[in] Connection number associated with an active notification registration. The value of ulConnection must have been returned by a previous call to IMAPISession::Advise.

Return Values

S_OK

The registration was successfully canceled.

Remarks

The IMAPISession::Unadvise method cancels a registration for notification. Unadvise releases its pointer to the caller’s advise sink, which it received in the Advise call used for registration.

Generally, Unadvise calls the advise sink’s IUnknown::Release method during the Unadvise call, but if another thread is in the process of calling the advise sink’s IMAPIAdviseSink::OnNotify method, the Release call is delayed until the OnNotify method returns.

See Also

IMAPIAdviseSink::OnNotify, IMAPISession::Advise


IMAPIStatus : IMAPIProp

MAPI implements the IMAPIStatus interface to provide status information about the MAPI subsystem, the integrated address book and the MAPI spooler. A service provider implements IMAPIStatus to supply information about its own status.

Quick Info

Header file:	MAPIDEFS.H
Exposed by:	Status objects
Implemented by:	Service providers and MAPI
Called by:	Client applications
Corresponding pointer type:	LPMAPISTATUS
Transaction model:	Non-transacted
Vtable Order

ValidateState	Confirms the external status information available for the MAPI resource or the service provider. This method is supported in all status objects.
SettingsDialog	Displays a property sheet enabling the user to change a service provider’s configuration. This method is not supported in status objects implemented by MAPI.
ChangePassword	Modifies a service provider’s password without displaying a user interface. This method is optionally supported in status objects implemented by service providers.
FlushQueues	Forces all messages waiting to be sent or received to be immediately uploaded or downloaded. This method is supported by the MAPI spooler status object and status objects implemented by transport providers.
Required properties	Access
PR_DISPLAY_NAME	Read/write
PR_PROVIDER_DISPLAY	Read/write
PR_PROVIDER_DLL_NAME	Read-only
PR_RESOURCE_FLAGS	Read-only
PR_RESOURCE_METHODS	Read-only
PR_RESOURCE_TYPE	Read-only
PR_STATUS_CODE	Read-only
Remarks

The status objects implemented by MAPI support the following methods:

Status object	Supported methods
MAPI subsystem	ValidateState only
MAPI address book	ValidateState only
MAPI spooler	ValidateState and FlushQueues
The status objects implemented by MAPI are required to have a read-only version of the methods of the IMAPIProp interface and support the IMAPIStatus::ValidateState method. Transport providers are strongly recommended to also support FlushQueues. All providers are encouraged to support SettingsDialog and support for ChangePassword is optional.

Clients use status objects to perform configuration and to learn about the state of the session. They access a status object by calling the OpenStatusEntry method of a service provider logon object or IMAPISession::GetStatusTable to retrieve the status object.


IMAPIStatus::ChangePassword

The IMAPIStatus::ChangePassword method modifies a service provider’s password without displaying a user interface.

Quick Info

See IMAPIStatus : IMAPIProp.

HRESULT ChangePassword(

LPTSTR lpOldPass,
LPTSTR lpNewPass,
ULONG ulFlags
)
Parameters

lpOldPass

[in] Pointer to the old password.

lpNewPass

[in] Pointer to the new password.

ulFlags

[in] Bitmask of flags that controls the format of the passwords. The following flag can be set:

MAPI_UNICODE

The passwords are in Unicode format. If the MAPI_UNICODE flag is not set, the passwords are in ANSI format.

Return Values

S_OK

The password modification was successful.

MAPI_E_NO_ACCESS

The old password pointed to by lpOldPass is invalid.

MAPI_E_NO_SUPPORT

The status object does not support this operation, as indicated by the absence of the STATUS_CHANGE_PASSWORD flag in the status object’s PR_RESOURCE_METHODS property.

Remarks

Not all status objects support the IMAPIStatus::ChangePassword method. It is supported only by service providers that require clients to enter a password. None of the status objects implemented by MAPI support the password change operation.

ChangePassword modifies a password programmatically, without user interaction.

See Also

PR_RESOURCE_METHODS


IMAPIStatus::FlushQueues

The IMAPIStatus::FlushQueues method forces all messages waiting to be sent or received to be immediately uploaded or downloaded.

Quick Info

See IMAPIStatus : IMAPIProp.

HRESULT FlushQueues(

ULONG ulUIParam,
ULONG cbTargetTransport,
LPENTRYID lpTargetTransport,
ULONG ulFlags
)
Parameters

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays.

cbTargetTransport

[in] Count of bytes in the entry identifier pointed to by the lpTargetTransport parameter. The cbTargetTransport parameter is set only on calls to the MAPI spooler’s status object. For calls to a transport provider, the cbTargetTransport parameter is set to zero.

lpTargetTransport

[in] Pointer to the entry identifier of the transport provider that is to flush its message queues. The lpTargetTransport parameter is set only on calls to the MAPI spooler’s status object. For calls to a transport provider, the lpTargetTransport parameter is set to NULL.

ulFlags

[in] Bitmask of flags that controls the flush operation. The following flags can be set:

FLUSH_ASYNC_OK

The flush operation can occur asynchronously. This flag only applies to the MAPI spooler’s status object.

FLUSH_DOWNLOAD

The inbound message queues should be flushed.

FLUSH_FORCE

The flush operation should occur regardless, in spite of the possibility of performance degradation. This flag must be set when targeting an asynchronous transport provider.

FLUSH_NO_UI

The status object should not display a progress indicator. This flag is used only by the MAPI spooler; providers ignore this flag.

FLUSH_UPLOAD

The outbound message queues should be flushed.

Return Values

S_OK

The flush operation was successful.

MAPI_E_BUSY

Another operation is in progress; it should be allowed to complete, or it should be stopped, before this operation can be initiated.

MAPI_E_NO_SUPPORT

The status object does not support this operation, as indicated by the absence of the STATUS_FLUSH_QUEUES flag in the status object’s PR_RESOURCE_METHODS property.

Remarks

The IMAPIStatus::FlushQueues method requests that the MAPI spooler or a transport provider immediately send all messages in the outbound queue or receive all messages from the inbound queue. FlushQueues is only implemented by the MAPI spooler status object and by status objects supplied by transport providers.

The processing involved with FlushQueues can take a long time. By default, the MAPI spooler’s implementation displays a progress indicator to keep the user informed. If the FLUSH_NO_UI flag is set in the ulFlags parameter, no progress indicator is displayed. Transport providers never display a progress indicator as part of their flush operation; they always ignore the FLUSH_NO_UI flag.

MAPI_E_BUSY should be returned for asynchronous requests so that clients can continue work.

By default, FlushQueues is a synchronous operation; control does not return to the caller until the flush has completed. Only the flush operation performed by the MAPI spooler can be asynchronous; clients request this behavior by setting the FLUSH_ASYNC_OK flag.

Notes to Callers

When calling the MAPI spooler status object, this is a directive to transfer all messages either to or from the appropriate transport provider. When calling an individual transport provider’s status object, only the messages for that provider are affected.

See Also

PR_RESOURCE_METHODS


IMAPIStatus::SettingsDialog

The IMAPIStatus::SettingsDialog method displays a property sheet enabling the user to change a service provider’s configuration.

Quick Info

See IMAPIStatus : IMAPIProp.

HRESULT SettingsDialog(

ULONG ulUIParam,
ULONG ulFlags
)
Parameters

ulUIParam

[in] Handle of the parent window for the configuration property sheet.

ulFlags

[in] Bitmask of flags that controls the display of the property sheet. The following flag can be set:

UI_READONLY

Suggests that the provider not enable users to change configuration properties. This flag is only a suggestion; it can be ignored.

Return Values

S_OK

The configuration property sheet was displayed successfully.

MAPI_E_NO_SUPPORT

The status object does not support this method as indicated by the absence of the STATUS_SETTINGS_DIALOG flag in the PR_RESOURCE_METHODS property.

Remarks

The IMAPIStatus::SettingsDialog method displays a configuration property sheet. MAPI recommends that all service providers support the SettingsDialog method, but it is not required. Service providers can implement their own property sheets or use the implementation supplied in the support object’s IMAPISupport::DoConfigPropsheet method. DoConfigPropsheet builds a read/write property sheet.

Notes to Callers

You can use the property sheet displayed through SettingsDialog to perform a variety of tasks, such as:

•	Specify a default message store.

•	Specify a transport order.

•	Specify a default address book container for browsing.

•	Specify a search order for resolving ambiguous names.

•	Specify a default personal address book.

Service providers can implement property sheets that are read/write, read-only, or a mixture of access modes, depending on the property. Service providers can implement different access on individual properties by setting property restrictions. The default mode for property sheets is read/write. You can request read-only displays by setting the UI_READONLY flag in your calls to SettingsDialog. Service providers that are able to honor the request can do so. However, because some service providers cannot override the default mode, you must be prepared to handle property sheets of either type.

Because a user interface is always involved in this operation, only interactive clients should call SettingsDialog.


IMAPIStatus::ValidateState

The IMAPIStatus::ValidateState method confirms the external status information available for the MAPI resource or the service provider.

Quick Info

See IMAPIStatus : IMAPIProp.

HRESULT ValidateState(

ULONG ulUIParam,
ULONG ulFlags
)
Parameters

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays.

ulFlags

[in] Bitmask of flags that controls the validation. The following flags can be set:

ABORT_XP_HEADER_OPERATION

The user has canceled the operation, typically by clicking the Cancel button in the corresponding dialog box. The status object has two options:

•	Continue working on the operation

•	Abort the operation and return MAPI_E_USER_CANCELED

CONFIG_CHANGED

One or more of the status object’s configuration properties has changed. Clients can set this flag to allow the MAPI spooler to dynamically correct critical transport provider failures.

FORCE_XP_CONNECT

The status object should perform a connection. When this flag is used with the REFRESH_XP_HEADER_CACHE or PROCESS_XP_HEADER_CACHE flag, the connection occurs without caching.

FORCE_XP_DISCONNECT

The status object should perform a disconnect operation. When this flag is used with the REFRESH_XP_HEADER_CACHE or PROCESS_XP_HEADER_CACHE flag, the disconnection occurs without caching.

PROCESS_XP_HEADER_CACHE

Entries in the header cache table should be processed, all messages marked with the MSGSTATUS_REMOTE_DOWNLOAD flag should be downloaded, and all messages marked with the MSGSTATUS_REMOTE_DELETE flag should be deleted. Messages that have both MSGSTATUS_REMOTE_DOWNLOAD and MSGSTATUS_REMOTE_DELETE set should be moved.

REFRESH_XP_HEADER_CACHE

For a remote transport provider, a new list of message headers should be downloaded and all flags marking message status should be cleared.

SUPPRESS_UI

Prevents the status object from displaying a user interface as part of the operation.

Return Values

S_OK

The validation was successful.

MAPI_E_BUSY

Another operation is in progress; it should be allowed to complete, or it should be stopped, before this operation should be initiated.

MAPI_E_NO_SUPPORT

The status object does not support the validation method, as indicated by the absence of the STATUS_VALIDATE_STATE flag in the PR_RESOURCE_METHODS property.

MAPI_E_USER_CANCEL

The user canceled the validation operation, typically by clicking the Cancel button in a dialog box. This value is only returned by remote transport providers.

Remarks

The IMAPIStatus::ValidateState method checks the state of a resource associated with a status object. ValidateState is the only method in the IMAPIStatus interface that is required for all status objects.

The exact behavior of this method depends on the implementation. The following table describes the implementation of each of the different types of status objects:

Status object	ValidateState implementation
MAPI subsystem	Validates the state of all of the resources owned by the currently active service providers and the subsystem itself.
MAPI spooler	Performs a logon of all of the transport providers, regardless of whether they are already logged on.
MAPI address book	Checks the entries in its profile section.
Service provider	Depends on the type of provider and the flags set in the ulFlags parameter.
Notes to Callers

Because this method can result in other calls being made that take some time, ValidateState can return MAPI_E_BUSY to inform you that this method is dependent upon another operation’s completion and that operation is still in progress. You should wait until the pending operation has completed before attempting another task.

You have the most control over your calls to transport provider status objects. You can pass one or more flags to ValidateState that affect the transport provider’s operations. For example, if you set the flag ABORT_XP_HEADER_OPERATION, this indicates that the user has canceled the validation. Transport providers can choose to abort — returning MAPI_E_USER_CANCELED — or continue.

The CONFIG_CHANGED flag can be set on a call to either the status object of a service provider or the MAPI spooler to indicate that a configuration option has been altered. You can use CONFIG_CHANGED to dynamically reconfigure a transport provider. When called on a service provider’s status object, the provider responds with a call to IMAPISupport::SpoolerNotify to alert the MAPI spooler of the change. When called on the MAPI spooler’s status object, the spooler calls IXPLogon::AddressTypes for each of the active transport providers and IMAPISession::MessageOptions. AddressTypes informs the MAPI spooler of a transport’s supported address types; MessageOptions invokes the display of a property sheet showing a transport’s message option properties. Some service providers also display a progress indicator if the validation is expected to take a long time. Displaying a progress indicator is helpful, but not required.

When the SUPPRESS_UI flag is set, none of the configuration property sheets can be displayed nor can any progress dialog boxes.


IMAPISupport : IUnknown

The IMAPISupport interface provides implementations for tasks that are commonly performed by service providers and message service entry point functions. Service providers receive a pointer to their support object when MAPI calls their provider object’s logon method; message services receive their support object pointer in the call to their entry point function.

Quick Info

Header file:	MAPISPI.H
Exposed by:	Support objects
Implemented by:	MAPI
Called by:	Service providers
Corresponding pointer type:	LPMAPISUP
Vtable Order

GetLastError	Returns a MAPIERROR structure containing information about the previous support object error.
GetMemAllocRoutines	Retrieves the addresses of the MAPI memory allocation and deallocation functions: MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer.
Subscribe	Registers an advise sink to receive notifications through MAPI.
Unsubscribe	Cancels the responsibility for sending notifications that was previously established with a call to the IMAPISupport::Subscribe method.
Notify	Sends a notification of a specified event to an advise source that originally registered for the notification through IMAPISupport::Subscribe.
ModifyStatusRow	Modifies the status table by adding a new row or modifying an existing row.
OpenProfileSection	Opens a section of the current profile and returns an IProfSect pointer for further access
RegisterPreprocessor	Registers a transport provider’s preprocessor function, a function that conforms to the PreprocessMessage prototype.
NewUID	Creates a new MAPIUID structure to be used as a unique identifier.
MakeInvalid	Marks an object as unusable.
SpoolerYield	Gives control of the CPU to the the MAPI spooler so that it can perform any tasks it deems necessary.
SpoolerNotify	Notifies the MAPI spooler of a change in status or a request for service.
CreateOneOff	Creates an entry identifier for a one-off address.
SetProviderUID	Registers a MAPIUID structure that uniquely represents the service provider.
CompareEntryIDs	Compares two entry identifiers to determine if they refer to the same object.
OpenTemplateID	Opens a recipient entry in a foreign address book provider.
OpenEntry	Opens an object and returns an interface pointer for further access.
GetOneOffTable	Returns a pointer to MAPI’s one-off table, a list of templates supported by all address book providers for creating new recipients.
Address	Displays the common address dialog box.
Details	Displays a modal dialog box showing details about a particular address book entry.
NewEntry	Adds a new recipient directly to an address book container or to the recipient list of an outgoing message.
DoConfigPropsheet	Displays a configuration property sheet.
CopyMessages	Copies or moves messages from one folder to another folder.
CopyFolder	Copies or moves a folder from its current parent folder to another parent folder.
DoCopyTo	Copies or moves all properties of one object, except for specifically excluded properties, to another object.
DoCopyProps	Copies or moves one or more properties of an object to another object.
DoProgressDialog	Retrieves a progress object for displaying a progress indicator.
ReadReceipt	Generates a read or nonread report for a message.
PrepareSubmit	Prepares a message for submission to the MAPI spooler.
ExpandRecips	Completes a message’s recipient list, expanding particular distribution lists.
DoSentMail	Performs processing on a sent message.
OpenAddressBook	Provides access to the address book.
CompleteMsg	Performs postprocessing on a message.
StoreLogoffTransports	Requests the orderly release of a message store.
StatusRecips	Generates delivery and nondelivery reports.
WrapStoreEntryID	Converts a message store’s internal entry identifier to an entry identifier in MAPI’s standard format.
ModifyProfile	Makes the profile section for a message store provider permanent.
IStorageFromStream	Implements a storage object to access a stream.
GetSvcConfigSupportObj	Creates a message service support object.
Remarks

There are four different support objects, one for address book, message store, and transport providers and and one for message services. Service providers and message services call the methods in their support objects as part of their implementations of other interface methods. Each different support object has complete implementations of the methods that are applicable to its caller; the methods that are not applicable return MAPI_E_NO_SUPPORT.

Address book provider support objects have implementations for the following methods:

Address	CompareEntryIDs	CreateOneOff
Details	DoConfigPropsheet	DoProgressDialog
GetLastError	GetMemAllocRoutines	GetOneOffTable
IStorageFromStream	GetSvcConfigSupportObj	MakeInvalid
ModifyStatusRow	NewEntry	NewUID
Notify	OpenAddressBook	OpenEntry
OpenProfileSection	OpenTemplateID	SetProviderUID
Subscribe	Unsubscribe	WrapStoreEntryID
Message store provider support objects have implementations for the following methods:

CompareEntryIDs	CompleteMsg	CopyFolder
CopyMessages	CreateOneOff	DoCopyProps
DoCopyTo	DoConfigPropsheet	DoProgressDialog
DoSentMail	ExpandRecips	GetLastError
GetMemAllocRoutines	GetSvcConfigSupportObj	MakeInvalid
IStorageFromStream	ModifyProfile	ModifyStatusRow
NewUID	Notify	OpenAddressBook
OpenEntry	OpenProfileSection	PrepareSubmit
ReadReceipt	SetProviderUID	SpoolerNotify
StoreLogoffTransports	Subscribe	Unsubscribe
WrapStoreEntryID
Transport provider support objects have implementations for the following methods:

DoConfigPropsheet	CompareEntryIDs	CreateOneOff
GetMemAllocRoutines	GetSvcConfigSupportObj	GetLastError
IStorageFromStream	MakeInvalid	ModifyStatusRow
OpenAddressBook	RegisterPreprocessor	NewUID
Notify	OpenProfileSection	OpenEntry
StatusRecips	SpoolerNotify	SpoolerYield
WrapStoreEntryID	Subscribe	Unsubscribe
Message service support objects have implementations for the following methods:

DoConfigPropsheet	GetLastError
GetMemAllocRoutines	GetSvcConfigSupportObj
MakeInvalid	NewUID
OpenProfileSection


IMAPISupport::Address

The IMAPISupport::Address method displays the common address dialog box.

Quick Info

See IMAPISupport : IUnknown.

HRESULT Address(

ULONG FAR * lpulUIParam,
LPADRPARM lpAdrParms,
LPADRLIST FAR * lppAdrList
)
Parameters

lpulUIParam

[in, out] Handle of the parent window of the dialog box. On input, a window handle must always be passed. On output, if the DIALOG_SDI flag is set in the ADRPARM structure pointed to by the lpAdrParms parameter, then the window handle of the modeless dialog box is returned.

lpAdrParms

[in, out] Pointer to an ADRPARM structure that controls the presentation and behavior of the address dialog box.

lppAdrList

[in, out] Pointer to a pointer to an address list. On input, this list is either the current list of recipients in a message or NULL, if no such list exists. On output, lppAdrList points to an updated list of message recipients.

Return Values

S_OK

The address dialog box was successfully displayed.

Remarks

The IMAPISupport::Address method is implemented for address book provider support objects. Address book providers call Address to create or update a list of message recipients.

Each recipient is described in an ADRENTRY structure that is included in the ADRLIST structure pointed to by lppAdrList. The ADRENTRY structure contains an array of recipient property values, one of which is the recipient’s type, or PR_RECIPIENT_TYPE property. This ADRLIST structure can be passed to a client to use as the lpMods parameter in a call to IMessage::ModifyRecipients.

Each recipient in the ADRLIST structure can either be resolved, indicating that one of its property values is its PR_ENTRYID property, or unresolved, indicating that the PR_ENTRYID property is missing.

In addition to PR_ENTRYID, resolved recipients include the following properties:

PR_RECIPIENT_TYPE

PR_DISPLAY_NAME

PR_ADDRTYPE

PR_DISPLAY_TYPE

Unresolved recipients typically include only PR_DISPLAY_NAME and PR_RECIPIENT_TYPE.

Notes to Callers

The ADRLIST structure that the caller passes in might be a different size from the structure that MAPI returns. When allocating memory for the ADRLIST structure, allocate the memory for each SPropValue structure separately.

Use the pointers to the MAPI memory allocation functions passed in to your ABProviderInit function to allocate memory. Allocate memory for the ADRLIST structure and each property value structure within the ADRENTRY structures in the ADRLIST structure with the MAPIAllocateBuffer function.

If Address must return a larger ADRLIST structure, or if you have passed NULL for lppAdrList, it frees the original structure and allocates a new one. Address also allocates additional property value structures in the ADRLIST structure and frees old ones as appropriate. For more information about how memory is managed for ADRLIST structures, see Managing Memory for ADRLIST and SRowSet Structures.

Address returns immediately if the DIALOG_SDI flag was set in the ADRPARM structure in the lpAdrParms parameter.

See Also

ADRENTRY, ADRLIST, ADRPARM, FreePadrlist, FreeProws, IMAPISupport::GetMemAllocRoutines, IMAPITable::QueryRows, IMessage::ModifyRecipients, MAPIAllocateBuffer, MAPIAllocateMore, MAPIFreeBuffer, SPropValue, SRowSet


IMAPISupport::CompareEntryIDs

The IMAPISupport::CompareEntryIDs method compares two entry identifiers to determine if they refer to the same object.

Quick Info

See IMAPISupport : IUnknown.

HRESULT CompareEntryIDs(

ULONG cbEntryID1,
LPENTRYID lpEntryID1,
ULONG cbEntryID2,
LPENTRYID lpEntryID2,
ULONG ulFlags,
ULONG FAR * lpulResult
)
Parameters

cbEntryID1

[in] Count of bytes in the entry identifier pointed to by the lpEntryID1 parameter.

lpEntryID1

[in] Pointer to the first entry identifier to be compared.

cbEntryID2

[in] Count of bytes in the entry identifier pointed to by the lpEntryID2 parameter.

lpEntryID2

[in] Pointer to the second entry identifier to be compared.

ulFlags

Reserved; must be zero.

lpulResult

[out] Pointer to the result of the comparison, set toTRUE if the two entry identifiers refer to the same object and FALSE otherwise.

Return Values

S_OK

The comparison was successful.

MAPI_E_UNKNOWN_ENTRYID

One or both of the entry identifiers specified as parameters do not refer to valid objects, possibly because they are unopened and inaccessible at present.

Remarks

The IMAPISupport::CompareEntryIDs method is implemented for address book and message store provider support objects. CompareEntryIDs compares two entry identifiers belonging to a single service provider to determine whether they refer to the same object. MAPI extracts the MAPIUID portion from the entry identifiers to determine the service provider responsible for the objects and calls its logon object’s CompareEntryIDs method to perform the comparison.

Notes to Callers

CompareEntryIDs is useful because an object can have more than one valid entry identifier; such a situation can occur, for example, after a new version of a service provider is installed.

If CompareEntryIDs returns an error, do not take any action based on the result of the comparison. Instead, take the most conservative approach possible. CompareEntryIDs might fail if, for example, one or both of the entry identifiers contains an invalid MAPIUID.


IMAPISupport::CompleteMsg

The IMAPISupport::CompleteMsg method performs postprocessing on a message.

Quick Info

See IMAPISupport : IUnknown.

HRESULT CompleteMsg(

ULONG ulFlags,
ULONG cbEntryID,
LPENTRYID lpEntryID
)
Parameters

ulFlags

Reserved; must be zero.

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the message to process.

Return Values

S_OK

The postprocessing was successful.

Remarks

The IMAPISupport::CompleteMsg method is implemented for message store provider support objects and is called only by message store providers that are tightly coupled with transport providers. Tightly-coupled store providers call IMAPISupport::CompleteMsg to instruct the MAPI spooler to postprocess a message.

Notes to Callers

Call CompleteMsg only when you are tightly-coupled with a transport provider, you can handle all of the message’s recipients, and one of the following conditions exists:

•	The message in question was preprocessed.

•	The message in question requires postprocessing by the MAPI spooler, possibly causing messaging hook providers to be invoked.


IMAPISupport::CopyFolder

The IMAPISupport::CopyFolder method copies or moves a folder from its current parent folder to another parent folder.

Quick Info

See IMAPISupport : IUnknown.

HRESULT CopyFolder(

LPCIID lpSrcInterface,
LPVOID lpSrcFolder,
ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
LPVOID lpDestFolder,
LPSTR lpszNewFolderName,
ULONG ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
)
Parameters

lpSrcInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the parent folder of the folder to be copied or moved.

lpSrcFolder

[in] Pointer to the parent folder of the folder to be copied or moved.

cbEntryID

[in] Count of bytes in the entry identifier pointed to by lpEntryID.

lpEntryID

[in] Pointer to the entry identifier of the folder to be copied or moved.

lpInterface

Reserved; must be NULL.

lpDestFolder

[in] Pointer to the folder that is to receive the folder to be copied or moved.

lpszNewFolderName

[in] Pointer to the name of the copied or moved folder or NULL, indicating that the copied or moved folder should have the same name as the source folder, the folder pointed to by lpEntryID.

ulUIParam

[in] Handle of the window for the progress indicator dialog box and related windows. The ulUIParam parameter is ignored unless the the FOLDER_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] Pointer to a progress object for displaying a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator using MAPI’s progress object implementation. The lpProgress parameter is ignored unless the FOLDER_DIALOG flag is set in ulFlags.

ulFlags

[in] Bitmask of flags that controls how the copy or move operation is accomplished. The following flags can be set:

COPY_SUBFOLDERS

All of the folder’s subfolders should be copied or moved. When COPY_SUBFOLDERS is not set for a copy operation, only the folder identified by lpEntryID is copied. With a move operation, the COPY_SUBFOLDERS behavior is the default regardless of whether the flag is set.

FOLDER_DIALOG

Requests the display of a progress indicator.

FOLDER_MOVE

The folder should be moved rather than copied. If FOLDER_MOVE is not set, the folder is copied.

MAPI_UNICODE

The name of the folder is in Unicode format. If the MAPI_UNICODE flag is not set, the name of the folder is in ANSI format.

Return Values

S_OK

The folder has been successfully copied or moved.

MAPI_E_COLLISION

The name of the folder being moved or copied is the same as that of a subfolder in the destination folder. The message store provider requires that folder names be unique. The operation stops without completing.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but not all entries were successfully copied. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPISupport::CopyFolder method is implemented for message store provider support objects. Message store providers can call CopyFolder in their implementation of IMAPIFolder::CopyFolder to copy or move a single folder from one parent folder to another.

CopyFolder adds the copied or moved folder as a subfolder of the destination folder.

Notes to Callers

CopyFolder allows simultaneous renaming and moving of folders and the copying or moving of subfolders of the affected folder. To copy or move all subfolders nested within the copied or moved folder, pass the COPY_SUBFOLDERS flag in ulFlags.

Expect these return values under the following conditions:

Condition	Return value
CopyFolder has successfully copied or moved the folder and all of its subfolders, if applicable.	S_OK
CopyFolder was unable to successfully copy or move all of the folders.	MAPI_W_PARTIAL_COMPLETION
CopyFolder was unable to complete.	Any error value
If CopyFolder returns an error value, do not proceed on the assumption that no work was done. One or more folders could have been copied or moved before CopyFolder experienced the failure.


IMAPISupport::CopyMessages

The IMAPISupport::CopyMessages method copies or moves messages from one folder to another folder.

Quick Info

See IMAPISupport : IUnknown.

HRESULT CopyMessages(

LPCIID lpSrcInterface,
LPVOID lpSrcFolder,
LPENTRYLIST lpMsgList,
LPCIID lpDestInterface,
LPVOID lpDestFolder,
ULONG ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
)
Parameters

lpSrcInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the folder containing the messages to be copied or moved.

lpSrcFolder

[in] Pointer to the folder containing the messages to be copied or moved.

lpMsgList

[in] Pointer to an array of entry identifiers identifying the messages to be copied or moved.

lpDestInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the destination folder for the copied or moved messages.

lpDestFolder

[in] Pointer to the destination folder for the copied or moved messages. This folder must be open.

ulUIParam

[in] Pointer to a progress object for displaying a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator using MAPI’s progress object implementation. The lpProgress parameter is ignored unless the MESSAGE_DIALOG flag is set in ulFlags.

lpProgress

[in] Pointer to a progress object for displaying a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator using MAPI’s progress object implementation. The lpProgress parameter is ignored unless the MESSAGE_DIALOG flag is set in ulFlags.

ulFlags

[in] Bitmask of flags that controls how the copy or move operation is accomplished. The following flags can be set:

MESSAGE_DIALOG

Requests the display of a progress indicator.

MESSAGE_MOVE

The messages should be moved, rather than copied. If MESSAGE_MOVE is not set, the messages are copied.

Return Values

S_OK

The copy or move operation was successful.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The IMAPISupport::CopyMessages method is implemented for message store provider support objects. Message store providers can call CopyMessages in their implementation of IMAPIFolder::CopyMessages to copy or move one or more messages from one folder to another. As part of the CopyMessages call, the message store provider can specify that MAPI display a user interface showing progress information.


IMAPISupport::CreateOneOff

The IMAPISupport::CreateOneOff method creates an entry identifier for a one-off address.

Quick Info

See IMAPISupport : IUnknown.

HRESULT CreateOneOff(

LPTSTR lpszName,
LPTSTR lpszAdrType,
LPTSTR lpszAddress,
ULONG ulFlags,
ULONG FAR * lpcbEntryID,
LPENTRYID FAR * lppEntryID
)
Parameters

lpszName

[in] Pointer to the display name of the recipient, the PR_DISPLAY_NAME property. The lpszName parameter can be NULL.

lpszAdrType

[in] Pointer to the address type of the recipient, such as FAX, SMTP, or X500. The lpszAdrType parameter cannot be NULL.

lpszAddress

[in] Pointer to the messaging address of the recipient. The lpszAddress parameter cannot be NULL.

ulFlags

[in] Bitmask of flags that affects the one-off recipient. The following flags can be set:

MAPI_SEND_NO_RICH_INFO

The recipient cannot handle formatted message content. If MAPI_SEND_NO_RICH_INFO is set, MAPI sets the recipient’s PR_SEND_RICH_INFO property to FALSE. If MAPI_SEND_NO_RICH_INFO is not set, MAPI sets this property to TRUE unless the recipient’s messaging address pointed to by lpszAddress is interpreted to be an Internet address. In this case, MAPI sets PR_SEND_RICH_INFO to FALSE.

MAPI_UNICODE

The display name, address type, and address are in Unicode format. If the MAPI_UNICODE flag is not set, these strings are in ANSI format.

lpcbEntryID

[out] Pointer to the count of bytes in the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[out] Pointer to a pointer to the entry identifier for the one-off recipient.

Return Values

S_OK

The one-off entry identifier was successfully created.

Remarks

The IMAPISupport::CreateOneOff method is implemented for all service provider support objects. Service providers call the IMAPISupport::CreateOneOff method to create an entry identifier for a one-off recipient, a recipient that does not belong to any of the containers from any of the currently loaded address book providers.

Notes to Callers

When finished using the entry identifier returned by CreateOneOff, free the memory allocated for the entry identifier by using the MAPIFreeBuffer function.

Notes to Transport Providers

Support the Transport Neutral Encapsulation Format, or TNEF, and use the value of the PR_SEND_RICH_INFO property to determine whether or not to use TNEF when transporting a message. Not supporting TNEF or not sending a message in this format when requested can be a problem for form-based clients or clients that require custom MAPI properties. This is because TNEF is typically used to send custom properties for custom message classes.

See Also

MAPIFreeBuffer


IMAPISupport::Details

The IMAPISupport::Details method displays a modal dialog box showing details about a particular address book entry.

Quick Info

See IMAPISupport : IUnknown.

HRESULT Details(

ULONG FAR * lpulUIParam,
LPFNDISMISS lpfnDismiss,
LPVOID lpvDismissContext,
ULONG cbEntryID,
LPENTRYID lpEntryID,
LPFNBUTTON lpfButtonCallback,
LPVOID lpvButtonContext,
LPTSTR lpszButtonText,
ULONG ulFlags
)
Parameters

lpulUIParam

[out] Handle of the parent window for the returned dialog box.

lpfnDismiss

[in] Pointer to a function based on the DISMISSMODELESS function prototype. This function is called when the modeless variety of the details dialog box is dismissed. This parameter is ignored at present because MAPI does not support a modeless details dialog box.

lpvDismissContext

[in] Data that is passed to the function specified by the lpfnDismiss parameter. This parameter is currently ignored.

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier for which details are displayed.

lpfButtonCallback

[in] Pointer to a function based on the LPFNBUTTON function prototype. An LPFNBUTTON function adds a button to the details dialog box.

lpvButtonContext

[in] Pointer to data used as a parameter for the function specified by the lpfButtonCallback parameter.

lpszButtonText

[in] Pointer to a string containing text to be applied to the added button if that button is extensible. The lpszButtonText parameter should be NULL if an extensible button is not needed.

ulFlags

[in] Bitmask of flags that controls the type of the text for the lpszButtonText parameter. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

Return Values

S_OK

The details dialog box was successfully displayed for the address book entry.

Remarks

The IMAPISupport::Details method is implemented for address book provider support objects. Address book providers call the IMAPISupport::Details method to display a modal dialog box giving details on a particular entry in the address book. The lpfButtonCallback, lpvButtonContext, and lpButtonText parameters can be used to add a button the client has defined to the dialog box. When the button is chosen, MAPI calls the callback function pointed to by lpfButtonCallback, passing both the entry identifier of the button and the data in lpvButtonContext. If an extensible button is not needed, lpszButtonText should be NULL.

See Also

IMAPISupport::Address, LPFNBUTTON


IMAPISupport::DoConfigPropsheet

The IMAPISupport::DoConfigPropsheet method displays a configuration property sheet.

Quick Info

See IMAPISupport : IUnknown.

HRESULT DoConfigPropsheet(

ULONG ulUIParam,
ULONG ulFlags,
LPTSTR lpszTitle,
LPMAPITABLE lpDisplayTable,
LPMAPIPROP lpConfigData,
ULONG ulTopPage
)
Parameters

ulUIParam

[in] Handle of the parent window for the property sheet.

ulFlags

Reserved; must be zero.

lpszTitle

[in] Pointer to the title of the property sheet.

lpDisplayTable

[in] Pointer to the display table that describes the controls to appear on the property sheet.

lpConfigData

[in] Pointer to the IMAPIProp implementation to be used for accessing the configuration properties to be displayed on the property sheet.

ulTopPage

[in] A zero-based index to the default top page of the property sheet.

Return Values

S_OK

The configuration property sheet was displayed.

Remarks

The IMAPISupport::DoConfigPropSheet method is implemented for all support objects. DoConfigPropSheet provides a standard user interface for displaying the properties of service providers and message services. Microsoft strongly recommends that this standard dialog box be used for all configuration property displays so that users benefit from a consistent Windows interface.

Service providers call DoConfigPropSheet as part of their implementation of the IMAPIStatus::SettingsDialog method or from a button used to display details on properties. Message services call DoConfigPropSheet from their message service entry point function.

Notes to Callers

You can create the display table pointed to by the lpDisplayTable parameter by calling the BuildDisplayTable function or with custom code.

See Also

BuildDisplayTable, CreateIProp, IABProvider::Logon, IMAPIProp : IUnknown, IMAPIStatus::SettingsDialog, IMsgServiceAdmin : IUnknown, IMSProvider::Logon, IXPProvider::TransportLogon


IMAPISupport::DoCopyProps

The IMAPISupport::DoCopyProps method copies or moves one or more properties of an object to another object.

Quick Info

See IMAPISupport : IUnknown.

HRESULT DoCopyProps(

LPCIID lpSrcInterface,
LPVOID lpSrcObj,
LPSPropTagArray lpIncludeProps,
ULONG ulUIParam,
LPMAPIPROGRESS lpProgress,
LPCIID lpDestInterface,
LPVOID lpDestObj,
ULONG ulFlags,
LPSPropProblemArray FAR * lppProblems
)
Parameters

lpSrcInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the object with the properties to be copied or moved.

lpSrcObj

[in] Pointer to the object with the properties to be copied or moved.

lpIncludeProps

[in] Pointer to an SPropTagArray structure holding a counted array of property tags indicating the properties to copy or move. The lpIncludeProps parameter cannot be NULL.

ulUIParam

[in] Handle of the parent window for the progress indicator.

lpProgress

[in] Pointer to an implementation of a progress indicator. If NULL is passed in the lpProgress parameter, the progress indicator is displayed using MAPI’s implementation. The lpProgress parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

lpDestInterface

[in] Pointer to the interface identifier representing the interface to be used to access the object to receive the properties that are copied or moved.

lpDestObj

[in] Pointer to the object to receive the copied or moved properties.

ulFlags

[in] Bitmask of flags that controls how the copy or move operation is performed. The following flags can be set:

MAPI_DIALOG

Allows the display of a progress indicator.

MAPI_MOVE

DoCopyProps should perform a move operation rather than a copy operation. When this flag is not set, DoCopyProps performs a copy operation.

MAPI_NOREPLACE

Existing properties in the destination object should not be overwritten. When this flag is not set, DoCopyProps overwrites existing properties.

lppProblems

[in, out] On input, can be NULL, indicating no need for error information, or a pointer to a pointer to an SPropProblemArray structure. If lppProblems is a valid pointer on input, DoCopyProps returns detailed information about errors in copying one or more properties.

Return Values

S_OK

Properties have been successfully copied or moved.

MAPI_E_COLLISION

A property to be copied or moved already exists in the destination object and the MAPI_NOREPLACE flag is set.

MAPI_E_FOLDER_CYCLE

The source object directly or indirectly contains the destination object. Significant work might have been performed before this condition was discovered, so the source and destination objects might be partially modified.

MAPI_E_INTERFACE_NOT_SUPPORTED

The interface identified by the lpSrcInterface parameter is not supported by the source object or the interface identified by the lpDestInterface parameter is not supported by the destination object.

MAPI_E_NO_ACCESS

An attempt was made to access an object for which the caller has insufficient permissions. This error is returned if the destination object is the same as the source object.

The following values can be returned in the SPropProblemArray structure, but not as return values for DoCopyProps. These errors apply to a single property:

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and DoCopyProps does not support Unicode, or MAPI_UNICODE was not set and DoCopyProps only supports Unicode.

MAPI_E_COMPUTED

The property cannot be modified by the caller because it is a read-only property, computed by the owner of the destination object. This error is not severe; the caller should allow the copy operation to continue.

MAPI_E_INVALID_TYPE

The property type is invalid.

MAPI_E_UNEXPECTED_TYPE

The property type is not the type expected by the caller.

Remarks

The IMAPISupport::DoCopyProps method is implemented for message store provider support objects. Message store providers can call IMAPISupport::DoCopyProps to implement IMAPIProp::CopyProps for their folders and messages. IMAPISupport::DoCopyProps copies or moves the properties identified in the property tag array pointed to by lpIncludeProps that are present in the object pointed to by lpSrcObj.

Notes to Callers

When copying properties between like objects, such as between two messages, the lpSrcInterface and lpDestInterface parameters must contain the same interface identifier and lpSrcObj and lpDestObj parameters must point to objects of the same type. If lpDestInterface is set to NULL, then DoCopyProps returns MAPI_E_INVALID_PARAMETER. If you set lpDestInterface to an acceptable interface identifier, but set lpDestObj to an invalid pointer, the results are unpredictable. Most likely your provider will fail.

Set the MAPI_NOREPLACE flag if you do not want any of the properties in the destination object to be overwritten. Properties in the destination object that exist in the source object and are not overwritten are not deleted or modified.

To copy a message’s recipient list, include the PR_MESSAGE_RECIPIENTS property in the property tag array pointed to by lpIncludeProps. To copy the message’s attachments, include the PR_MESSAGE_ATTACHMENTS property.

To copy a folder or address book container’s hierarchy or contents table, include PR_CONTAINER_HIERARCHY or PR_CONTAINER_CONTENTS in the property tag array. To include a folder’s associated contents table, include the PR_FOLDER_ASSOCIATED_CONTENTS property in the array.

If subfolders are copied or moved, their contents are copied or moved in their entirety, regardless of the use of properties indicated by the SPropTagArray structure.

DoCopyProps reports global errors — or errors that occur with the operation as a whole — and individual errors, or errors that occur with one or more of the properties. These individual errors are placed in an SPropProblemArray structure. You can suppress error reporting at the property level by passing NULL for the property problem array structure parameter rather than a valid pointer.

If you want to receive information about errors, pass a valid SPropProblemArray structure pointer in the lppProblems parameter. When DoCopyProps returns S_OK, check for possible errors with individual properties in the structure. When DoCopyProps returns an error, no information is returned in the SPropProblemArray structure. Instead, call IMAPISupport::GetLastError to retrieve detailed error information.

If DoCopyProps returns S_OK, free the returned SPropProblemArray structure by calling the MAPIFreeBuffer function.

For more information about calling IMAPISupport::DoCopyProps, see Using a Support Object for Copying.

See Also

IMAPISupport::CopyMessages, IMAPISupport::DoCopyTo, SPropProblemArray, SPropTagArray


IMAPISupport::DoCopyTo

The IMAPISupport::DoCopyTo method copies or moves all properties of one object, except for specifically excluded properties, to another object.

Quick Info

See IMAPISupport : IUnknown.

HRESULT DoCopyTo(

LPCIID lpSrcInterface,
LPVOID lpSrcObj,
ULONG ciidExclude,
LPCIID rgiidExclude,
LPSPropTagArray lpExcludeProps,
ULONG ulUIParam,
LPMAPIPROGRESS lpProgress,
LPCIID lpDestInterface,
LPVOID lpDestObj,
ULONG ulFlags,
LPSPropProblemArray FAR * lppProblems
)
Parameters

lpSrcInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the object with the properties to be copied or moved.

lpSrcObj

[in] Pointer to the object with the properties to be copied or moved.

ciidExclude

[in] Count of interfaces to exclude when copying or moving properties.

rgiidExclude

[in] Array of interface identifiers indicating interfaces that should not be used when copying or moving supplemental information to the destination object.

lpExcludeProps

[in] Pointer to a property tag array identifying the property tags that should be excluded from the copy or move operation. Passing NULL in the lpExcludeProps parameter indicates that all of the object’s properties should be copied or moved. DoCopyTo returns MAPI_E_INVALID_PARAMETER when the cValues member of the SPropTagArray structure pointed to by lpExcludeProps is set to zero.

ulUIParam

[in] Handle of the parent window for the progress indicator.

lpProgress

[in] Pointer to a progress indicator implementation. If NULL is passed in the lpProgress parameter, MAPI provides the progress implementation. The lpProgress parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

lpDestInterface

[in] Pointer to the interface identifier representing the interface to be used to access the object to receive the copied or moved properties.

lpDestObj

[in] Pointer to the object to receive the copied or moved properties.

ulFlags

[in] Bitmask of flags that controls the copy or move operation. The following flags can be set:

MAPI_DIALOG

Allows the display of a progress indicator.

MAPI_MOVE

DoCopyTo should perform a move operation rather than a copy operation. When this flag is not set, DoCopyTo performs a copy operation.

MAPI_NOREPLACE

Existing properties in the destination object should not be overwritten. When this flag is not set, DoCopyTo overwrites existing properties.

lppProblems

[out] On input, can be NULL, indicating no need for error information, or a pointer to a pointer to an SPropProblemArray structure. If lppProblems is a valid pointer on input, DoCopyTo returns detailed information about errors in copying one or more properties.

Return Values

S_OK

The properties have been successfully copied or moved.

MAPI_E_COLLISION

A property to be copied or moved already exists in the destination object and the MAPI_NOREPLACE flag is set.

MAPI_E_FOLDER_CYCLE

The source object directly or indirectly contains the destination object. Significant work might have been performed before this condition was discovered, so the source and destination objects might be partially modified.

MAPI_E_INTERFACE_NOT_SUPPORTED

The interface identified by the lpSrcInterface parameter is not supported by the object pointed to by lpSrcObj or the interface identified by the lpDestInterface parameter is not supported by the object pointed to by lpDestObj.

MAPI_E_NO_ACCESS

An attempt was made to access an object for which the caller has insufficient permissions. This error is returned if the destination object is the same as the source object.

MAPI_E_INVALID_PARAMETER

The lpSrcInterface parameter is NULL.

The following values can be returned in the SPropProblemArray structure, but not as return values for DoCopyTo. These errors apply to a single property:

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and DoCopyTo does not support Unicode, or MAPI_UNICODE was not set and DoCopyTo only supports Unicode.

MAPI_E_COMPUTED

The property cannot be modified by the caller because it is a read-only property, computed by the owner of the destination object. This error is not severe; the caller should allow the copy operation to continue.

MAPI_E_INVALID_TYPE

The property type is invalid.

MAPI_E_UNEXPECTED_TYPE

The property type is not the type expected by the caller.

Remarks

The IMAPISupport::DoCopyTo method is implemented for message store provider support objects. Message store providers can call IMAPISupport::DoCopyTo to implement IMAPIProp::CopyTo for their folders and messages.

DoCopyTo by default copies or moves all of the properties of one object to another object. Any subobjects in the source object are automatically included in the operation and copied or moved in their entirety.

If any of the copied or moved properties already exist in the destination object, the existing properties are overwritten by the new, unless the MAPI_NOREPLACE flag is set in the ulFlags parameter. Existing information in the destination object that is not overwritten is left untouched.

Notes to Callers

To exclude properties from the copy or move operation, include their property tags in the lpExcludeProps parameter. If you pass the results of using the PROP_TAG macro to build a property tag from a specific identifier in the property tag array, all properties with that identifier will be excluded. For example, the following entry in the property tag array causes all properties with an identifier of 0x8002 to be excluded, regardless of type:

PROP_TAG(PT_LONG, 0x8002)

To avoid copying a message’s delivery time when copying the message to a different folder, specify PR_MESSAGE_DELIVERY_TIME in the property tag exclude array. To exclude a message’s recipient list, add the PR_MESSAGE_RECIPIENTS property to the exclude array. To exclude a message’s attachments, add the PR_MESSAGE_ATTACHMENTS property to the array.

Similarly, prevent the copying or moving of a folder or address book container’s hierarchy or contents table by including PR_CONTAINER_HIERARCHY or PR_CONTAINER_CONTENTS in the property tag exclude array.

Ignore MAPI_E_COMPUTED errors returned in the SPropProblemArray structure in the lppProblems parameter.

The interface identifier pointed to by lpSrcInterface is usually the same as the interface identifier pointed to by lpDestInterface.

If you pass an acceptable interface identifier in lpDestInterface but an invalid pointer in lpDestObj, the results are unpredictable. Most likely this will cause your provider to fail.

Conversely, if you are aware of supplemental information that should not be copied or moved, include the interface identifiers for the interfaces to be excluded in the array passed in the rgiidExclude parameter. For example, if you are copying messages, but not any of their message attachments, pass IID_IMessage in the rgiidExclude array. DoCopyTo ignores any interfaces listed in rgiidExclude it doesn’t recognize.

When you use the rgiidExclude parameter to exclude an interface, it also excludes all interfaces derived from that interface. For example, excluding  IMAPIContainer causes folders or address book containers to be excluded, depending on the type of provider. Do not exclude IMAPIProp or IUnknown because so many interfaces derive from them.

DoCopyTo reports global errors — errors that apply to the operation as a whole — and individual errors — errors that apply to individual properties. These individual errors are placed in an SPropProblemArray structure. You can suppress error reporting at the property level by passing NULL for the property problem array structure parameter rather than a valid pointer.

If you want to receive information about errors, pass a valid SPropProblemArray structure pointer in the lppProblems parameter. When DoCopyTo returns S_OK, check for possible errors with individual properties in the structure. When DoCopyTo returns an error, no information is returned in the SPropProblemArray structure. Instead, call IMAPISupport::GetLastError to retrieve detailed error information.

If CopyTo returns S_OK, free the returned SPropProblemArray structure by calling the MAPIFreeBuffer function.

If a global error occurs on the DoCopyTo call, do not use or free the SPropProblemArray structure. Providers should ignore the ulIndex member in SPropProblemArray structures returned by DoCopyTo.

For more information about calling IMAPISupport::DoCopyTo, see Using a Support Object for Copying.

See Also

IMAPISupport::CopyFolder, IMAPISupport::CopyMessages, SPropProblemArray, SPropTagArray


IMAPISupport::DoProgressDialog

The IMAPISupport::DoProgressDialog method retrieves a progress object for displaying a progress indicator.

Quick Info

See IMAPISupport : IUnknown.

HRESULT DoProgressDialog(

ULONG ulUIParam,
ULONG ulFlags,
LPMAPIPROGRESS FAR * lppProgress
)
Parameters

ulUIParam

[in] Handle of the parent window for the progress indicator.

ulFlags

[in] Bitmask of flags that controls how the progress object should calculate progress. The following flag can be set:

MAPI_TOP_LEVEL

Progress is being calculated for a top level item, such as a parent folder. The progress object should use the values in the IMAPIProgress::Progress method’s ulCount and ulTotal parameters — which indicate the item being operated on and the total items to operate on respectively — to increment progress made on the operation.

lppProgress

[out] Pointer to a pointer to the progress object.

Return Values

S_OK

The progress object was successfully retrieved.

Remarks

The IMAPISupport::DoProgressDialog method is implemented for address book and message store provider support objects. These providers call DoProgressDialog to access MAPI’s implementation of the IMAPIProgress interface which calculates the progress information and displays the result in a standard dialog box.

For information about how to use a progress object and the IMAPIProgress interface, see Displaying Progress Step by Step.

See Also

IMAPIProgress : IUnknown


IMAPISupport::DoSentMail

The IMAPISupport::DoSentMail method performs processing on a sent message.

Quick Info

See IMAPISupport : IUnknown.

HRESULT DoSentMail(

ULONG ulFlags,
LPMESSAGE lpMessage
)
Parameters

ulFlags

Reserved; must be zero.

lpMessage

[in] Pointer to the open message for which a message should be generated in the folder designated to hold sent items.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The IMAPISupport::DoSentMail method is implemented for message store provider support objects. Message store providers call DoSentMail from within their implementation of IMsgStore::FinishedMsg method, called by the MAPI spooler when it has finished processing a message. FinishedMsg unlocks the message, ensures that the message’s reference count is one, and calls IMAPISupport::DoSentMail.

DoSentMail performs the following tasks:

•	Determines whether the message should be deleted after sending by checking the message for the PR_DELETE_AFTER_SUBMIT property.

•	Determines the location of the Sent Items folder.

•	Initiates message hook processing for any hooks set on the Sent Items folder.

•	Moves the message to the Sent Items folder, Deleted Items folder, or to another folder as specified by any messaging hook providers.

•	Releases the message.

See Also

IMsgStore::FinishedMsg


IMAPISupport::ExpandRecips

The IMAPISupport::ExpandRecips method completes a message’s recipient list, expanding particular distribution lists.

Quick Info

See IMAPISupport : IUnknown.

HRESULT ExpandRecips(

LPMESSAGE lpMessage,
ULONG FAR * lpulFlags
)
Parameters

lpMessage

[in] Pointer to the message with the recipient list to be processed.

lpulFlags

[out] Pointer to a bitmask of flags that controls the type of processing that occurs. The following flags can be set:

NEEDS_PREPROCESSING

The message needs to be preprocessed before it is sent.

NEEDS_SPOOLER

The MAPI spooler must send the message rather than the transport provider to which the caller is tightly coupled.

Return Values

S_OK

The message’s recipient list was successfully processed.

Remarks

The IMAPISupport::ExpandRecips method is implemented for message store provider support objects. Message store providers call ExpandRecips to prompt MAPI to perform the following tasks:

•	Expand certain personal distribution lists to their component recipients.

•	Replace all display names that have been altered with the original names.

•	Mark any duplicate entries.

•	Resolve all one-off addresses.

•	Check if the message needs preprocessing and, if it does, set the flag pointed to by lpulFlags to NEEDS_PREPROCESSING.

ExpandRecips expands any distribution lists that have the messaging address type of MAPIPDL.

Notes to Callers

Always call ExpandRecips as part of your message processing. Make a call to ExpandRecips one of the first calls in your IMessage::SubmitMessage implementation.

See Also

IMessage::SubmitMessage


IMAPISupport::GetLastError

The IMAPISupport::GetLastError method returns a MAPIERROR structure containing information about the previous support object error.

Quick Info

See IMAPISupport : IUnknown.

HRESULT GetLastError(

HRESULT hResult,
ULONG ulFlags,
LPMAPIERROR FAR * lppMAPIError
)
Parameters

hResult

[in] HRESULT data type containing the error value generated in the previous method call for the support object.

ulFlags

[in] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] Pointer to a pointer to the MAPIERROR structure containing version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if a MAPIERROR structure with appropriate error information cannot be provided.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and MAPI does not support Unicode, or MAPI_UNICODE was not set and MAPI only supports Unicode.

Remarks

The IMAPISupport::GetLastError method is implemented for all support objects. Callers can provide their users with detailed information about the error by including the data from the MAPIERROR structure in a dialog box.

Notes to Callers

You can make use of the MAPIERROR structure pointed to by the lppMAPIError parameter, if MAPI supplies one, only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was or has nothing more to report about the error. In this situation, a pointer to NULL is returned in lppMAPIError instead.

For more information about the GetLastError method, see Using Extended Errors.

To release all the memory allocated by MAPI, call the MAPIFreeBuffer function for the returned MAPIERROR structure.

See Also

MAPIERROR, MAPIFreeBuffer


IMAPISupport::GetMemAllocRoutines

The IMAPISupport::GetMemAllocRoutines method retrieves the addresses of the MAPI memory allocation and deallocation functions: MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer.

Quick Info

See IMAPISupport : IUnknown.

HRESULT GetMemAllocRoutines(

LPALLOCATEBUFFER FAR * lppAllocateBuffer,
LPALLOCATEMORE FAR * lppAllocateMore,
LPFREEBUFFER FAR * lppFreeBuffer
)
Parameters

lppAllocateBuffer

[out] Pointer to a pointer to the MAPIAllocateBuffer function. The MAPIAllocateBuffer function allocates memory.

lppAllocateMore

[out] Pointer to a pointer to the MAPIAllocateMore function. The MAPIAllocateMore function allocates additional memory for memory originally allocated with MAPIAllocateBuffer.

lppFreeBuffer

[out] Pointer to a pointer to the MAPIFreeBuffer function. The MAPIFreeBuffer function frees memory.

Return Values

S_OK

The function addresses were successfully returned.

Remarks

The IMAPISupport::GetMemAllocRoutines method is implemented for all support objects. Service providers call IMAPISupport::GetMemAllocRoutines to get the addresses of the three memory allocation functions passed to their initialization function: ABProviderInit, MSProviderInit, or XPProviderInit.

See Also

MAPIAllocateBuffer, MAPIAllocateMore, MAPIFreeBuffer


IMAPISupport::GetOneOffTable

The IMAPISupport::GetOneOffTable method returns a pointer to MAPI’s one-off table, a list of templates supported by all address book providers for creating new recipients.

Quick Info

See IMAPISupport : IUnknown.

HRESULT GetOneOffTable(

ULONG ulFlags,
LPMAPITABLE FAR * lppTable
)
Parameters

ulFlags

[in] Bitmask of flags that controls the type of the string columns. The following flag can be set:

MAPI_UNICODE

The string columns are in the Unicode format. If the MAPI_UNICODE flag is not set, the string columns are in the ANSI format.

lppTable

[out] Pointer to a pointer to the one-off table.

Return Values

S_OK

The one-off table was successfully retrieved.

Remarks

The IMAPISupport::GetOneOffTable method is implemented for address book provider support objects. Address book providers call IMAPISupport::GetOneOffTable to retrieve the complete list of templates for creating new recipients. Included in this table are templates supported by all of the address book providers active in the session as well as templates supported by MAPI.

The newly created recipients can be used to address a message or added to an address book container

For a list of the properties that make up the required column set in one-off tables, see One-Off Tables.

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the format of the columns returned from the following IMAPITable methods:

•	IMAPITable::QueryColumns

•	IMAPITable::QueryRows

This flag also controls the property types in the sort order returned by the IMAPITable::QuerySortOrder method.

Notes to Callers

If registered for notification of changes to this one-off table, you will also receive notifications of changes made to other providers’ one-off tables. Based on these notifications, you can support new address types that are added during the current session.

See Also

IABContainer::CreateEntry, IMAPISupport::NewEntry, PR_CREATE_TEMPLATES


IMAPISupport::GetSvcConfigSupportObj

The IMAPISupport::GetSvcConfigSupportObj method creates a message service support object.

Quick Info

See IMAPISupport : IUnknown.

HRESULT GetSvcConfigSupportObj(

ULONG ulFlags,
LPMAPISUP FAR * lppSvcSupport
)
Parameters

ulFlags

Reserved; must be zero.

lppSvcSupport

[out] Pointer to a pointer to the new message service support object.

Return Values

S_OK

The configuration support object was successfully created.

Remarks

The IMAPISupport::GetSvcConfigSupportObj method is implemented for all support objects. Service providers call IMAPISupport::GetSvcConfigSupportObj to create a configuration support object to pass to a message service entry point function.

A message service entry point function is based on the MSGSERVICEENTRY prototype and is called by methods of the IMsgServiceAdmin interface. A message service entry point function allows message services to configure themselves or perform other actions when the profile is changed. Message service entry point functions can support configuration changes by displaying a property sheet or through a property value array passed to the IMsgServiceAdmin::ConfigureMsgService method.

See Also

IMsgServiceAdmin::CreateMsgService, IProfAdmin : IUnknown, MSGSERVICEENTRY


IMAPISupport::IStorageFromStream

The IMAPISupport::IStorageFromStream method implements a storage object to access a stream.

Quick Info

See IMAPISupport : IUnknown.

HRESULT IStorageFromStream(

LPUNKNOWN lpUnkIn,
LPCIID lpInterface,
ULONG ulFlags,
LPSTORAGE FAR * lppStorageOut
)
Parameters

lpUnkIn

[in] Pointer to a stream object.

lpInterface

[in] Pointer to the interface identifier (IID) that represents the interface to be used to access the stream pointed to by lpUnkIn. Any of the following values are valid: NULL, indicating that IStream should be used to access the stream, IID_IStream, or IID_ILockBytes.

ulFlags

[in] Bitmask of flags that controls how the storage object is to be created relative to the stream object. By default, the storage is created with read-only access and the stream starts at position zero within the storage. The following flags can be set:

STGSTRM_CREATE

A new storage object should be created for the stream object.

STGSTRM_CURRENT

The storage object should start at the current position of the stream.

STGSTRM_MODIFY

The caller should have read/write access to the returned storage object.

STGSTRM_RESET

The storage object should start at position zero.

lppStorageOut

[out] Pointer to a pointer to the storage object.

Return Values

S_OK

The storage object was successfully created.

Remarks

The IMAPISupport::IStorageFromStream method is implemented for all service provider support objects. Service providers call IStorageFromStream to create a storage object to use for opening particular properties. Service providers that have their own implementation of IStorage do not need to call IStorageFromStream.

The storage object created by IStorageFromStream calls the stream’s IUnknown::AddRef method to increment its reference count and then decrements the count when the storage is released.

Notes to Callers

When the IMAPIProp::OpenProperty method of one of your objects is called to open a property with the IStorage interface, perform the following tasks:

1.	Open a stream object with read/write access for the property.

2.	Internally mark the property stream as a storage object.

3.	Call IStorageFromStream to generate a storage object.

1. 	Return a pointer to this storage object.

If you implement additional interfaces that use the storage object, create an object that wraps the storage object and implement a higher level IUnknown::QueryInterface method.

Do not allow a property to be opened with the IStream interface if it was created with IStorage. Conversely, do not allow a property to be opened with the IStorage interface if it was created with IStream.

With one exception, it is acceptable to use the IStreamDocfile interface to stream a storage object from one container to another, but the IID_IStreamDocfile interface identifier must be passed in the OpenProperty method’s lpInterface parameter.

See Also

IMAPIProp::OpenProperty


IMAPISupport::MakeInvalid

The IMAPISupport::MakeInvalid method marks an object as unusable.

Quick Info

See IMAPISupport : IUnknown.

HRESULT MakeInvalid(

ULONG ulFlags,
LPVOID lpObject,
ULONG ulRefCount,
ULONG cMethods
)
Parameters

ulFlags

Reserved; must be zero.

lpObject

[in] Pointer to the object to be invalidated. The object’s interface must be derived from IUnknown.

ulRefCount

[in] The object’s present reference count.

cMethods

[in] Count of methods in the object’s vtable.

Return Values

S_OK

The object was successfully marked as unusable.

Remarks

The IMAPISupport::MakeInvalid method is implemented for all support objects. The object to be invalidated must be derived from the IUnknown interface or from an interface derived from IUnknown.

MakeInvalid marks an object as unusable by replacing the object’s vtable with a stub vtable of similar size in which the IUnknown::AddRef and IUnknown::Release methods perform as expected but any other methods fail, returning the value MAPI_E_INVALID_OBJECT.

Notes to Callers

Service providers and message services typically call IMAPISupport::MakeInvalid at shut down time. However, MakeInvalid can be called at any time. For example, if a client releases an object without releasing some of its subobjects, you can call MakeInvalid immediately to release those subobjects.

You must own the object that you attempt to invalidate. It must be at least 16 bytes long and have at least three methods in its vtable.

You can call MakeInvalid and then perform any shutdown work, such as discarding associated data structures, that is usually done during the release of an object. Code to support the object need not be kept in memory because MAPI frees the memory by calling MAPIFreeBuffer and then releases the object. You can release resources, call MakeInvalid, and then ignore the invalidated object.

See Also

MAPIAllocateBuffer


IMAPISupport::ModifyProfile

The IMAPISupport::ModifyProfile method makes changes to a message store profile section permanent.

Quick Info

See IMAPISupport : IUnknown.

HRESULT ModifyProfile(

ULONG ulFlags
)
Parameters

ulFlags

[in] Bitmask of flags that indicates the type of message store. The following flag can be set:

MDB_TEMPORARY

The message store is temporary and should not be added to the message store table. When MDB_TEMPORARY is set, ModifyProfile returns S_OK immediately.

Return Values

S_OK

The changes to the profile section were successful.

Remarks

The IMAPISupport::ModifyProfile method is implemented for message store provider support objects. Message store providers call IMAPISupport::ModifyProfile to prompt MAPI to modify their profile information.

ModifyProfile adds the profile section associated with the calling provider to the list of installed message store provider resources. This causes the message store to be listed in the message store table, available to clients through the IMAPISession::GetMsgStoresTable method, and to be opened without the display of a dialog box.

If the MDB_TEMPORARY flag is set, MAPI does nothing and the method returns immediately with S_OK.

See Also

IMAPISession::GetMsgStoresTable


IMAPISupport::ModifyStatusRow

The IMAPISupport::ModifyStatusRow method modifies the status table by adding a new row or modifying an existing row.

Quick Info

See IMAPISupport : IUnknown.

HRESULT ModifyStatusRow(

ULONG cValues,
LPSPropValue lpColumnVals,
ULONG ulFlags
)
Parameters

cValues

[in] Count of properties to be included in the new or modified status table row.

lpColumnVals

[in] Pointer to an array of property values describing the properties to be included as columns in the new or modified status table row.

ulFlags

[in] Bitmask of flags that controls how information defining the status table row is processed. The following flag can be set:

STATUSROW_UPDATE

Directs MAPI to merge the properties included in the array pointed to by lpColumnVals with an existing status table row rather than add them in a new row.

Return Values

S_OK

The status table was successfully updated.

Remarks

The IMAPISupport::ModifyStatusRow method is implemented for all service provider support objects. Service providers call IMAPISupport::ModifyStatusRow at logon time to add a row to the status table and at other times during the session to update the row. ModifyStatusRow provides MAPI with the information necessary to build the status table.

Notes to Callers

Set the STATUSROW_UPDATE flag when you call ModifyStatusRow to make changes to the properties in your existing status table row. Doing so informs MAPI that only the columns being changed are passed in the lpColumnVals parameter.

Clients can use the information in the status table to access your status object.

For a complete list of columns that you should include in your status table row, see Status Table.


IMAPISupport::NewEntry

The IMAPISupport::NewEntry adds a new recipient directly to an address book container or to the recipient list of an outgoing message.

Quick Info

See IMAPISupport : IUnknown.

HRESULT NewEntry(

ULONG ulUIParam,
ULONG ulFlags,
ULONG cbEIDContainer,
LPENTRYID lpEIDContainer,
ULONG cbEIDNewEntryTpl,
LPENTRYID lpEIDNewEntryTpl,
ULONG FAR * lpcbEIDNewEntry,
LPENTRYID FAR * lppEIDNewEntry
)
Parameters

ulUIParam

[in] Handle of the parent window for the dialog box.

ulFlags

Reserved; must be zero.

cbEIDContainer

[in] Count of bytes in the entry identifier pointed to by the lpEIDContainer parameter.

lpEIDContainer

[in] Pointer to the entry identifier of the container to receive the new entry. If cbEIDContainer is zero and lpEIDContainer is NULL, NewEntry creates a one-off entry identifier that is the same type as is generated by a call to IMAPISupport::CreateOneOff.

cbEIDNewEntryTpl

[in] Count of bytes in the entry identifier pointed to by the lpEIDNewEntryTpl parameter.

lpEIDNewEntryTpl

[in] Pointer to the entry identifier of the template to be used to create the new entry. If cbEIDNewEntryTpl is zero and lpEIDNewEntryTpl is NULL, NewEntry displays a dialog box enabling the user to select from a list of templates for adding new entries.

lpcbEIDNewEntry

[out] Pointer to the count of bytes in the entry identifier pointed to by the lppEIDNewEntry parameter.

lppEIDNewEntry

[out] Pointer to a pointer to the entry identifier of the newly created entry.

Return Values

S_OK

The new entry was successfully created.

Remarks

The IMAPISupport::NewEntry method is implemented for address book provider support objects. Address book providers call IMAPISupport::NewEntry to create a new address book entry to be added directly into a container or to be used to address an outgoing message.

Notes to Callers

If you want the new entry to be added to a specific container, set lpEIDContainer to the container’s entry identifier and cbEIDContainer to the count of bytes in the entry identifier.

If you want the new entry to be added to the recipient list of an outgoing message, set lpEIDContainer to NULL and cbEIDContainer to zero.

If you want to allow the user of a client application to select the type of entry to be created, pass zero in cbEIDNewEntryTpl and NULL in lpEIDNewEntryTpl. NewEntry displays MAPI’s one-off table — a listing of templates supported by MAPI and by each of the address book providers in the session. Each template can create a recipient entry for one or more address types.

If you want to retain the entry identifier of the new entry, pass valid pointers in the lpcbEIDNewEntry and lppEIDNewEntry parameters. You are responsible for freeing this entry identifier when you have finished with it by calling the MAPIFreeBuffer function.

To use a particular template for adding a new entry to a modifiable container

1.	Call IMAPISupport::OpenEntry to open the destination container, setting the lpEntryID parameter to the entry identifier of the container.

2.	Call the destination container’s IMAPIProp::OpenProperty method and set ulPropTag to PR_CREATE_TEMPLATES and lpiid to IID_IMAPITable. The container will return a one-off table listing all of the templates that it supports for creating new entries.

3.	Retrieve the row that represents the template for the particular type of entry you want to create. The PR_ADDRTYPE column indicates the address type that is supported by the template.

4.	Call IMAPISupport::NewEntry and set lpEIDNewEntryTpl to the entry identifier of the selected template. This will be the PR_ENTRYID column from the template’s row in the one-off table. Pass zero in cbEIDContainer and NULL in lpEIDContainer. Pass a valid pointer in the lppEIDNewEntry parameter if you want to retain the new entry’s entry identifier.

See Also

IMAPIProp::OpenProperty, IMAPISupport::OpenEntry, PR_CREATE_TEMPLATES


IMAPISupport::NewUID

The IMAPISupport::NewUID method creates a new MAPIUID structure to be used as a unique identifier.

Quick Info

See IMAPISupport : IUnknown.

HRESULT NewUID(

LPMAPIUID lpMuid
)
Parameters

lpMuid

Pointer to the new MAPIUID structure.

Return Values

S_OK

The new MAPIUID structure was created.

Remarks

The IMAPISupport::NewUID method is implemented for all support objects. Service providers and message services call IMAPISupport::NewUID whenever they need to generate a long-term unique identifier. A message store provider, for instance, might call NewUID to obtain a MAPIUID to place in the PR_SEARCH_KEY property of a newly created message.

Notes to Callers

Do not confuse the MAPIUID structure that you register at logon time with the MAPIUID structures that are created by NewUID. The MAPIUID structure that you register when you call IMAPISupport::SetProviderUID represents your address book or message store provider to MAPI and is used to distinguish entry identifiers created by different providers. This MAPIUID structure should be hard-coded, using the output of the utility UUIDGEN.EXE, and not obtained through a call to NewUID.

See Also

MAPIUID


IMAPISupport::Notify

The IMAPISupport::Notify method sends a notification of a specified event to an advise source that originally registered for the notification through IMAPISupport::Subscribe.

Quick Info

See IMAPISupport : IUnknown.

HRESULT Notify(

LPNOTIFKEY lpKey,
ULONG cNotification,
LPNOTIFICATION lpNotifications,
ULONG FAR * lpulFlags
)
Parameters

lpKey

[in] Pointer to the notification key for the advise source object. The lpKey parameter cannot be NULL.

cNotification

[in] Count of notification structures pointed to by the lpNotifications parameter.

lpNotifications

[in] Pointer to an array of NOTIFICATION structures describing pending notifications.

lpulFlags

[in, out] Bitmask of flags that controls the notification process. On input, the following flag can be set:

MAPI_UNICODE

The strings in the notification structures pointed to by lpNotifications are in the Unicode format. If the MAPI_UNICODE flag is not set, the strings are in the ANSI format.

On output, the following flag can be set by MAPI:

NOTIFY_CANCELED

A callback function canceled a synchronous notification.

Return Values

S_OK

The notifications were successfully generated.

Remarks

The IMAPISupport::Notify method is implemented for all service provider support objects. Service providers call IMAPISupport::Notify to request that MAPI generate a notification for an advise sink that has previously registered for the notification through IMAPISupport::Subscribe.

Notify copies the structures pointed to by the lpNotifications parameter into memory and calls the appropriate advise sink’s IMAPIAdviseSink::OnNotify method. When finished with the notification, it releases the memory involved. The caller does not need to allocate memory; MAPI performs all necessary memory allocation.

Notes to Callers

The notification key passed in the lpKey parameter should be identical to the key passed in lpKey to the IMAPISupport::Subscribe method. Many providers use the entry identifier of the advise source as the key, but other data, such as a file path, can be used. MAPI uses this key to find all the registrations for notifications on the identified advise source.

Make sure that you set the lpEntryID member of the notification structure to a long-term entry identifier.

If you set the NOTIFY_SYNC flag on the Subscribe call for any of the pending notifications, Notify calls the IMAPIAdviseSink::OnNotify method callback functions before returning. An advise sink can be created manually or by calling HrAllocAdviseSink. The HrAllocAdviseSink function allows its caller to specify a callback function that Notify calls as part of the notification. The callback function conforms to the NOTIFCALLBACK prototype. Callback functions implemented by clients always return S_OK; callback functions implemented by service providers can return CALLBACK_DISCONTINUE.

If a callback function returns CALLBACK_DISCONTINUE, MAPI stops sending notifications and returns NOTIFY_CANCELED in the Notify method’s lpulFlags parameter. You can assume that the process is inactive and stop generating notifications for that process. If Notify returns zero in lpulFlags, the process is still active and you should continue to send notifications as appropriate.

When using synchronous notifications, be careful to avoid deadlock situations.

For more information on the notification process, see Event Notification in MAPI.

See Also

IMAPISupport::Subscribe, IMAPISupport::Unsubscribe, NOTIFCALLBACK NOTIFICATION, NOTIFKEY, PR_RECORD_KEY


IMAPISupport::OpenAddressBook

The IMAPISupport::OpenAddressBook method provides access to the address book.

Quick Info

See IMAPISupport : IUnknown.

HRESULT OpenAddressBook(

LPCIID lpInterface,
ULONG ulFlags,
LPADRBOOK FAR * lppAdrBook
)
Parameters

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the address book. Valid values are NULL, indicating the standard address book interface — IAddrBook — and IID_IAddrBook.

ulFlags

Reserved; must be zero.

lppAdrBook

[out] Pointer to a pointer to the address book.

Return Values

S_OK

Access to the address book was provided.

MAPI_W_ERRORS_RETURNED

The call succeeded, but one or more address book providers could not be loaded. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPISupport::OpenAddressBook method is implemented for all service provider support objects. Service providers, typically tightly coupled message store and transport providers, call the IMAPISupport::OpenAddressBook method to get access to the address book. The returned IAddrBook pointer can be used for a variety of address book tasks, including opening address book containers, finding messaging users, and displaying address dialog boxes.

Notes to Callers

OpenAddressBook can return MAPI_W_ERRORS_RETURNED if it cannot load one or more of the address book providers in the current profile. This value is a warning and you should treat the call as successful. Even if all of the address book providers failed to load, OpenAddressBook still succeeds, returning MAPI_W_ERRORS_RETURNED and an IAddrBook pointer in the lppAdrBook parameter. Because OpenAddressBook always returns a valid IAddrBook pointer, you must release it when you are finished using it.

If one or more address book providers failed to load, call IMAPISupport::GetLastError to obtain a MAPIERROR structure containing information about the providers that did not load.

See Also

IAddrBook : IMAPIProp, IMAPISession::OpenAddressBook


IMAPISupport::OpenEntry

The IMAPISupport::OpenEntry method opens an object and returns an interface pointer for further access.

Quick Info

See IMAPISupport : IUnknown.

HRESULT OpenEntry(

ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
ULONG ulOpenFlags,
ULONG FAR * lpulObjType,
LPUNKNOWN FAR * lppUnk
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the object to open.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the object. Passing NULL results in the object’s standard interface being returned. For example, if the object to be opened is a message, the standard interface is IMessage; for folders, it is IMAPIFolder. The standard interfaces for address book objects are IDistList for a distribution list and IMailUser for a messaging user.

ulOpenFlags

[in] Bitmask of flags that controls how the object is opened. The following flags can be set:

MAPI_BEST_ACCESS

Requests that the object be opened with the maximum network permissions allowed for the caller. For example, if the caller has read/write access, the object should be opened with read/write access; if the caller has read-only access, the object should be opened with read-only access.

MAPI_DEFERRED_ERRORS

Allows OpenEntry to return successfully, possibly before the object is fully accessible to the caller. If the object is not accessible, making a subsequent object call can result in an error.

MAPI_MODIFY

Requests read/write access. By default, objects are opened with read-only access, and callers should not work on the assumption that read/write access has been granted.

lpulObjType

[out] Pointer to the type of the opened object.

lppUnk

[out] Pointer to a pointer to the opened object.

Return Values

S_OK

The object was successfully opened.

MAPI_E_NO_ACCESS

An attempt was made to modify a read-only object or an attempt was made to access an object for which the user has insufficient permissions.

MAPI_E_NOT_FOUND

There is not an object associated with the entry identifier passed in lpEntryID.

MAPI_E_UNKNOWN_ENTRYID

The entry identifier passed in the lpEntryID parameter is in an unrecognizable format. This value is typically returned if the address book provider that contains the object is not open.

Remarks

The IMAPISupport::OpenEntry method is implemented for all service provider support objects. Service providers call IMAPISupport::OpenEntry to retrieve a pointer to an interface that can be used to access a particular object.

Notes to Callers

Call IMAPISupport::OpenEntry only when you do not know what kind of object you are opening. If you know you are opening a folder or a message, call IMsgStore::OpenEntry instead. If you know you are opening an address book container, a messaging user, or a distribution list, call IAddrBook::OpenEntry. These more specific methods are faster than IMAPISupport::OpenEntry.

OpenEntry opens all objects with read-only access, unless you set the MAPI_MODIFY or MAPI_BEST_ACCESS flag in the ulFlags parameter and your access is sufficient. Setting one of these flags does not guarantee a particular type of access; the permissions that you are granted depends on the service provider that owns the object, your access level, and the object. To determine the access level of the opened object, retrieve its PR_ACCESS_LEVEL property.

Check the value returned in the lpulObjType parameter to determine that the object type returned is what you expected. If the object type is as expected, cast the pointer from the lppUnk parameter to a pointer of the appropriate type. For example, if you are opening a folder, cast lppUnk to a pointer of type LPMAPIFOLDER.


IMAPISupport::OpenProfileSection

The IMAPISupport::OpenProfileSection method opens a section of the current profile and returns an IProfSect pointer for further access.

Quick Info

See IMAPISupport : IUnknown.

HRESULT OpenProfileSection(

LPMAPIUID lpUid,
ULONG ulFlags,
LPPROFSECT FAR * lppProfileObj
)
Parameters

lpUid

[in] Pointer to the MAPIUID structure that identifies the profile section to be opened. Passing NULL for the lpUid parameter opens the caller’s profile section.

ulFlags

[in] Bitmask of flags that controls how the profile section is opened. The following flags can be set:

MAPI_DEFERRED_ERRORS

Allows OpenProfileSection to return successfully, possibly before the profile section is fully accessible to the caller. If the profile section is not accessible, making a subsequent object call can result in an error.

MAPI_MODIFY

Requests read/write access. By default, objects are opened with read-only access, and callers should not work on the assumption that read/write access has been granted.

lppProfileObj

[out] Pointer to a pointer to the opened profile section.

Return Values

S_OK

The profile section was successfully opened.

MAPI_E_NO_ACCESS

An attempt was made to modify a read-only profile section or to access an object for which the caller has insufficient permissions.

MAPI_E_NOT_FOUND

There is not a profile section associated with the entry identifier passed in lpEntryID.

MAPI_E_UNKNOWN_FLAGS

Reserved or unsupported flags were used, and therefore the operation did not complete.

Remarks

The IMAPISupport::OpenProfileSection method is implemented for all support objects. Service providers and message services call IMAPISupport::OpenProfileSection to open a profile section and retrieve a pointer to its IProfSect interface implementation.

Notes to Callers

OpenProfileSection opens profile sections with read-only access, unless you set the MAPI_MODIFY flag in the ulFlags parameter and your access is sufficient. Setting this flag does not guarantee read/write access; the permissions that you are granted depends on your access level and the object.

If OpenProfileSection attempts to open a nonexistent profile section with read-only access, it returns MAPI_E_NOT_FOUND. If OpenProfileSection attempts to open a nonexistent profile section with read/write access, it creates the profile section and returns the IProfSect pointer.

See Also

IMAPIProp : IUnknown, IProfSect : IMAPIProp, MAPIUID


IMAPISupport::OpenTemplateID

The IMAPISupport::OpenTemplateID method opens a recipient entry in a foreign address book provider.

Quick Info

See IMAPISupport : IUnknown.

HRESULT OpenTemplateID(

ULONG cbTemplateID,
LPENTRYID lpTemplateID,
ULONG ulTemplateFlags,
LPMAPIPROP lpMAPIPropData,
LPCIID lpInterface,
LPMAPIPROP FAR * lppMAPIPropNew,
LPMAPIPROP lpMAPIPropSibling
)
Parameters

cbTemplateID

[in] Count of bytes in the template identifier pointed to by lpTemplateID.

lpTemplateID

[in] Pointer to the template identifier — PR_TEMPLATEID property — of the recipient entry to be opened.

ulTemplateFlags

[in] Bitmask of flags used to describe how to open the entry. The following flag can be set:

FILL_ENTRY

A new entry is being created. When the foreign provider receives the subsequent IABLogon::OpenTemplateID call from MAPI, it can control how the entry is created by modifying properties pointed to by the lpMAPIPropData parameter or by returning a specific interface implementation in lppMAPIPropNew to control how properties for the new entry are set.

lpMAPIPropData

[in] Pointer to the interface implementation that the caller uses to access the entry. This is the implementation that the foreign provider can wrap with its own implementation and return in the lppMAPIPropNew parameter. The lpMAPIPropData parameter must point to a read/write interface implementation that derives from IMAPIProp and supports the interface being requested in the lpInterface parameter.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the entry. The lppMAPIPropNew parameter points to an interface of the type specified by lpInterface. Passing NULL results in the return of the standard interface for a messaging user, IID_IMailUser.

lppMAPIPropNew

[out] Pointer to the interface implementation supplied by the foreign provider for accessing the entry.

lpMAPIPropSibling

Reserved; must be NULL.

Return Values

S_OK

The binding process was successful.

MAPI_E_UNKNOWN_ENTRYID

The foreign address book provider doesn’t exist.

Remarks

The IMAPISupport::OpenTemplateID method is implemented only for address book provider support objects. OpenTemplateID is called only by address book providers that can act as hosts for entries belonging to other address book providers, also known as foreign providers. Host providers call OpenTemplateID to open a foreign entry, which occurs when data in the host provider is bound to code in the foreign provider.

Notes to Callers

Call OpenTemplateID only if you support the storage of entries with template identifiers from foreign address book providers. Such support places additional requirements on your IABContainer::CreateEntry and IABLogon::OpenEntry implementations. See the descriptions of these methods and Implementing a Host Address Book Provider for more information.

If the OpenTemplateID call returns as the bound interface the same property object implementation as you passed in, you can release your reference to your property object. This is because the foreign provider has called the object’s AddRef method to keep its own reference. If the foreign provider does not need to keep a reference to the property object, then OpenTemplateID will return the unbound property object.

If OpenTemplateID fails with MAPI_E_UNKNOWN_ENTRYID, try to continue by treating the entry as read-only.

See Also

IABLogon::OpenTemplateID, IPropData : IMAPIProp, PR_TEMPLATEID


IMAPISupport::PrepareSubmit

The IMAPISupport::PrepareSubmit method prepares a message for submission to the MAPI spooler.

Quick Info

See IMAPISupport : IUnknown.

HRESULT PrepareSubmit(

LPMESSAGE lpMessage,
ULONG FAR * lpulFlags
)
Parameters

lpMessage

[in] Pointer to the message to prepare.

lpulFlags

[in, out] On input, the lpulFlags parameter is reserved and must be zero. On output, lpulFlags must be NULL.

Return Values

S_OK

The message was successfully prepared.

Remarks

The IMAPISupport::PrepareSubmit method is implemented for message store provider support objects. Message store providers call PrepareSubmit in their implementation of IMessage::SubmitMessage to prepare a message for submission to the MAPI spooler.

PrepareSubmit is used to handle messages that have the MSGFLAG_RESEND flag set in their PR_MESSAGE_FLAGS property. MSGFLAG_RESEND is set for messages that include a request to be resent when an initial transmission fails. PrepareSubmit determines which of the recipients in the recipient list successfully received the message and which did not.

To access the recipient list, PrepareSubmit calls the message’s IMessage::GetRecipientTable method. To retrieve the recipient data, PrepareSubmit calls the recipient table’s IMAPITable::QueryRows. For each row in the table, PrepareSubmit checks PR_RECIPIENT_TYPE, and:

•	If the MAPI_SUBMITTED flag is set, PrepareSubmit clears the flag and sets the PR_RESPONSIBILITY property to FALSE.

•	If the MAPI_SUBMITTED flag is not set, PrepareSubmit changes the PR_RECIPIENT_TYPE to MAPI_P1 and sets the PR_RESPONSIBILITY property to TRUE.

Notes to Callers

Before you call PrepareSubmit, make sure you have called IMAPISupport::SpoolerNotify and set the NOTIFY_READYTOSEND flag in the ulFlags parameter. The SpoolerNotify call must be made once per session before the call to PrepareSubmit. IMAPISupport::SpoolerNotify synchronizes the MAPI spooler and ensures that all needed transport providers are logged on and their address types registered.

See Also

IMAPIFolder::GetMessageStatus, IMessage::SubmitMessage


IMAPISupport::ReadReceipt

The IMAPISupport::ReadReceipt method generates a read or nonread report for a message.

Quick Info

See IMAPISupport : IUnknown.

HRESULT ReadReceipt(

ULONG ulFlags,
LPMESSAGE lpReadMessage,
LPMESSAGE FAR * lppEmptyMessage
)
Parameters

ulFlags

[in] Bitmask of flags that controls how the read or nonread report is generated. The following flag can be set:

MAPI_NON_READ

A nonread report is generated. If MAPI_NON_READ is not set, a read report is generated.

lpReadMessage

[in] Pointer to the message about which the report should be generated.

lppEmptyMessage

[in, out] On input, lppEmptyMessage points to a pointer to an empty message. On output, lppEmptyMessage points to a pointer to the report message.

Return Values

S_OK

The report was successfully generated.

Remarks

The IMAPISupport::ReadReceipt method is implemented for message store provider support objects only. Message store providers call IMAPISupport::ReadReceipt to instruct MAPI to generate a read or nonread report for the message pointed to by the lpReadMessage parameter.

Notes to Callers

Call ReadReceipt when the PR_READ_RECEIPT_REQUESTED property is set and one of the following conditions is true:

•	The message has been read.

•	The message has been moved.

•	The message has been copied.

•	The message’s IMessage::SetReadFlag method has been called.

Do not call ReadReceipt when a message is deleted.

A read or nonread report should only be sent once for a message. Keep track of a message’s read status and do not send multiple reports for a single message.

If lppEmptyMessage points to a valid report message when MAPI returns from ReadReceipt, call its IMessage::SubmitMessage method to send it and then release it by calling its IUnknown::Release method.

If ReadReceipt fails, the message should be released without being submitted. If you store the message’s read status, you can attempt to generate the read or nonread report at a later time.

You can either hide or display read and nonread reports generated by stores in your folders. Storing read and nonread reports in hidden folders allows you to implement tighter security.

See Also

IMAPIFolder::DeleteMessages, IMessage::SubmitMessage, PR_READ_RECEIPT_REQUESTED


IMAPISupport::RegisterPreprocessor

The IMAPISupport::RegisterPreprocessor method registers a transport provider’s preprocessor function, a function that conforms to the PreprocessMessage prototype.

Quick Info

See IMAPISupport : IUnknown.

HRESULT RegisterPreprocessor(

LPMAPIUID lpMuid,
LPTSTR lpszAdrType,
LPTSTR lpszDLLName,
LPSTR lpszPreprocess,
LPSTR lpszRemovePreprocessInfo,
ULONG ulFlags
)
Parameters

lpMuid

[in] Pointer to the MAPIUID structure containing the identifier that the preprocessor function handles. The lpMuid parameter can be NULL.

lpszAdrType

[in] Pointer to the address type for the messages the function operates on, such as FAX, SMTP, or X500. The lpszAdrType parameter can be NULL.

lpszDLLName

[in] Pointer to the name of the dynamic-link library (DLL) containing the entry point for the preprocessor function.

lpszPreprocess

[in] Pointer to the name of the preprocessor function. The lpszPreprocess parameter can be NULL.

lpszRemovePreprocessInfo

[in] Pointer to the name of the function that removes preprocessor information, a function that conforms to the RemovePreprocessInfo prototype. The lpszRemovePreprocessInfo parameter can be NULL.

ulFlags

Reserved; must be zero.

Return Values

S_OK

The preprocessor function was successfully registered.

Remarks

The IMAPISupport::RegisterPreprocessor method is implemented for transport provider support objects only. Transport providers call the IMAPISupport::RegisterPreprocessor method to register a preprocessor function — a function that conforms to the PreprocessMessage prototype. A preprocessor function must be registered before it can be called by the MAPI spooler.

The lpszPreprocess, lpszRemovePreprocessInfo and lpszDLLName parameters should all point to strings that can be used in conjunction with calls to the Win32 GetProcAddress function, allowing the preprocessor’s DLL entry point to be called correctly.

Notes to Callers

Calls to preprocessors are specific to transport provider order. This means that if another transport provider ahead of your provider is able to handle a message, your preprocessor function will not get called for that message. Your preprocessor function will only be called for messages that you will handle.

Preprocessor functions can be written to handle either a specific identifier stored in a MAPIUID structure or a type of address. If you specify both a MAPIUID structure in the lpMuid parameter and an address type in lpszAdrType, your function will be called for message recipients that match either the MAPIUID or the address type. If lpMuid is NULL and lpszAdrType is non-null, your function will be called only for recipients with an address that matches the type pointed to by lpszAdrType. If lpMuid is non-null and lpszAdrType is NULL, your function will be called for recipients that match MAPIUID, regardless of their address type. If both are NULL, your function is called for all recipients of the message.

See Also

MAPIUID, PreprocessMessage, RemovePreprocessInfo


IMAPISupport::SetProviderUID

The IMAPISupport::SetProviderUID method registers a MAPIUID structure that uniquely represents the service provider.

Quick Info

See IMAPISupport : IUnknown.

HRESULT SetProviderUID(

LPMAPIUID lpProviderID,
ULONG ulFlags
)
Parameters

lpProviderID

[in] Pointer to the MAPIUID structure identifying the address book or message store provider.

ulFlags

Reserved; must be zero.

Return Values

S_OK

The MAPIUID structure was successfully registered.

Remarks

The IMAPISupport::SetProviderUID method is implemented for address book and message store provider support objects. These providers call IMAPISupport::SetProviderUID to register a unique identifier described in the MAPIUID structure pointed to by lpProviderID. Providers include this identifier in all of the entry identifiers that they create.

MAPI uses the MAPIUID when sending outbound messages to the MAPI spooler and to determine the appropriate provider for handling client requests. For example, when a client calls IMAPISession::OpenEntry, MAPI examines the MAPIUID portion of the entry identifier, maps it to the provider that passed it to SetProviderUID, and calls that provider’s OpenEntry.

Notes to Callers

Call SetProviderUID at logon time to register your MAPIUID structure. MAPI allows address book and message store providers to register multiple identifiers. When you make multiple calls to SetProviderUID, it always adds the MAPIUID structure to the provider’s set of MAPIUIDs, even if the MAPIUID is a duplicate. SetProviderUID cannot remove a MAPIUID.

See Also

MAPIUID


IMAPISupport::SpoolerNotify

The IMAPISupport::SpoolerNotify method notifies the MAPI spooler of a change in status or a request for service.

Quick Info

See IMAPISupport : IUnknown.

HRESULT SpoolerNotify(

ULONG ulFlags,
LPVOID lpvData
)
Parameters

ulFlags

[in] Bitmask of flags that indicates the type of notification. All of the flags except for NOTIFY_NEWMAIL_RECEIVED can be set by transport providers; only NOTIFY_NEWMAIL_RECEIVED and NOTIFY_READTOSEND are valid for message store providers.

The following flags are valid for the ulFlags parameter::

NOTIFY_CONFIG_CHANGE

Registers a request to change the transport provider’s configuration.

NOTIFY_CRITICAL_ERROR

An unrecoverable error has occurred to the transport provider. Because both NOTIFY_SENTDEFERRED and NOTIFY_CRITICAL_ERROR use the lpvData parameter for transport provider calls, these flags are mutually exclusive.

NOTIFY_CRITSEC

Requests a critical section for the transport provider. The lpvData parameter is undefined and should be NULL.

NOTIFY_NEWMAIL

The MAPI spooler should download any newly received messages at the next available time. The lpvData parameter is undefined and should be set to NULL.

NOTIFY_NEWMAIL_RECEIVED

A new message has been received in the message store. The lpvData parameter points to a NEWMAIL_NOTIFICATION structure describing the message. This flag is used for message store providers that are tightly coupled with transport providers and is ignored if the store provider logged on with the MAPI_NO_MAIL flag set.

NOTIFY_NONCRIT

Releases a critical section that was obtained with a previous call to SpoolerNotify with ulFlags set to NOTIFY_CRITSEC. The lpvData parameter is undefined and should be set to NULL.

NOTIFY_READYTOSEND

The transport or message store provider is ready to send messages. The lpvData parameter is undefined and should be set to NULL.

NOTIFY_SENTDEFERRED

A previously deferred message should now be sent and that the transport provider should be notified when it is ready to be delivered with a call to IXPLogon::SubmitMessage. The entry identifier of the deferred message is contained in an SBinary structure pointed to by lpvData. Because both NOTIFY_SENTDEFERRED and NOTIFY_CRITICAL_ERROR use the lpvData parameter, these flags are mutually exclusive.

lpvData

[in] Pointer to associated data applicable to a notification. The lpvData parameter points to valid data only when the following flags are set; lpvData is NULL when ulFlags is set to the other notification types:

Setting for ulFlags	Value for lpvData
NOTIFY_CRITICAL_ERROR	Information about the error.
NOTIFY_NEWMAIL_RECEIVED	A NEWMAIL_NOTIFICATION structure with information about the newly delivered message.
NOTIFY_SENTDEFERRED	SBinary structure with entry identifier of deferred message.
Return Values

S_OK

The notification was successful.

Remarks

The IMAPISupport::SpoolerNotify method is implemented for message store and transport provider support objects. These providers call the IMAPISupport::SpoolerNotify method to notify the MAPI spooler of a change in status or a request for service. SpoolerNotify is called primarily by transport providers and may be called at any time during the session.

Notes to Transport Providers

If you have changed your configuration, call SpoolerNotify and set ulFlags to NOTIFY_CONFIG_CHANGED. SpoolerNotify responds by calling your IXPLogon::AddressTypes method to query for a change in supported address types and the IMAPISession::MessageOptions method to ask MAPI to display your configuration properties to the user.

If you need a critical section to ensure uninterrupted processing, call SpoolerNotify with ulFlags set to NOTIFY_CRITSEC. Setting this flag informs the MAPI spooler that it should not call your IXPLogon::Idle and IXPLogon::Poll methods. While you have a critical section open, return MAPI_E_BUSY whenever your IMAPIStatus::ValidateState method is called. When you have finished with the critical section, make another call to SpoolerNotify with ulFlags set to NOTIFY_NONCRIT.

For example, if you are a remote transport provider in the process of uploading messages, you might need to allow a user to enter a telephone number for establishing the remote connection. Before looping through your dialog box procedure, declare a critical section. When the user closes the dialog box, terminating the dialog box procedure, release the critical section.

When you set ulFlags to NOTIFY_CRITICAL_ERROR, the MAPI spooler makes no further calls to your provider except to release it. If you call SpoolerNotify with this flag set from IXPLogon::StartMessage or IXPLogon::SubmitMessage, return with an appropriate error value from the StartMessage or SubmitMessage call immediately after the SpoolerNotify call.

If you have recovered from a condition that previously caused you to fail, call SpoolerNotify with ulFlags is set to NOTIFY_READYTOSEND. This flag indicates that you are again ready to handle messages.

Notes to Message Store Providers

Call SpoolerNotify, passing the NOTIFY_READYTOSEND flag in ulFlags, before you make your first call to IMAPISupport::PrepareSubmit in IMessage::SubmitMessage. This call to SpoolerNotify only needs to be made once per session.

If you are tightly coupled with a transport provider and you call SpoolerNotify with ulFlags set to NOTIFY_NEWMAIL_RECEIVED, the MAPI spooler opens the new message and begins processing the new message hook function. When processing is complete, the MAPI spooler calls your IMsgStore::NotifyNewMail method to inform you of your own new message.

For more information about calling SpoolerNotify, see any of the following topics:

Implementing the FlushQueues Method

Interacting with the MAPI Spooler

Message Reception Model

See Also

IMsgStore::NotifyNewMail, IXPLogon::StartMessage, IXPLogon::SubmitMessage


IMAPISupport::SpoolerYield

The IMAPISupport::SpoolerYield method gives control of the CPU to the the MAPI spooler so that it can perform any tasks it deems necessary.

Quick Info

See IMAPISupport : IUnknown.

HRESULT SpoolerYield(

ULONG ulFlags
)
Parameters

ulFlags

Reserved; must be zero.

Return Values

S_OK

The transport provider successfully released the CPU.

MAPI_W_CANCEL_MESSAGE

Instructs the transport provider to stop the delivery of the message to any recipients that have not yet received it.

Remarks

The IMAPISupport::SpoolerYield method is implemented for transport provider support objects. Transport providers call IMAPISupport::SpoolerYield to allow the MAPI spooler to accomplish any necessary processing.

Notes to Callers

Call SpoolerYield when you are performing lengthy operations that can be paused. This allows foreground applications to run during a long operation, such as delivery to a large recipient list across a busy network.

If SpoolerYield returns with MAPI_W_CANCEL_MESSAGE, the MAPI spooler has determined that the message should no longer be sent. Return MAPI_E_USER_CANCEL to your calling process and exit if possible.

For more information about yielding to the MAPI spooler, see Interacting with the MAPI Spooler.


IMAPISupport::StatusRecips

The IMAPISupport::StatusRecips method generates delivery and nondelivery reports.

Quick Info

See IMAPISupport : IUnknown.

HRESULT StatusRecips(

LPMESSAGE lpMessage,
LPADRLIST lpRecipList
)
Parameters

lpMessage

[in] Pointer to the message for which the report should be generated.

lpRecipList

[in] Pointer to an ADRLIST structure describing the recipients of the message pointed to by lpMessage.

Return Values

S_OK

The report was successfully generated.

MAPI_W_ERRORS_RETURNED

The call succeeded overall, but there are no recipient options for this type of recipient. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPISupport::StatusRecips method is implemented for transport provider support objects. Transport providers call StatusRecips to request that MAPI send a delivery or nondelivery report to a set of one or more of the recipients of a message.

Notes to Callers

You can call StatusRecips multiple times during the processing of a message. However, if you call StatusRecips for an open message, do your best to collect all delivery and nondelivery information for the message recipients and call StatusRecips for that recipient list. A single point of collection is important because multiple StatusRecips calls for one recipient can result in multiple identical reports being sent.

Store properties relating to message delivery or nondelivery in the ADRLIST structure indicated by the lpRecipList parameter. For a complete list of required and optional properties for delivery reports and nondelivery reports, see Required Report Message Properties and Optional Report Message Properties.

Allocate memory for the ADRLIST structure in lpRecipList using the MAPIAllocateBuffer and MAPIAllocateMore functions. MAPI releases the memory by calling the MAPIFreeBuffer function only if IMAPISupport::StatusRecips succeeds.

For an overview of delivery and nondelivery reports, see Report Messages.

See Also

ADRLIST, IMAPISupport::Address, IMAPISupport::SpoolerNotify, IXPLogon::EndMessage, MAPIAllocateBuffer, MAPIAllocateMore, MAPIFreeBuffer


IMAPISupport::StoreLogoffTransports

The IMAPISupport::StoreLogoffTransports method requests the orderly release of a message store.

Quick Info

See IMAPISupport : IUnknown.

HRESULT StoreLogoffTransports(

ULONG FAR * lpulFlags
)
Parameters

lpulFlags

[in, out] Bitmask of flags that controls how message store logoff occurs. On input, all flags for this parameter are mutually exclusive; only one flag can be set per call and the following flags can are valid:

LOGOFF_ABORT

Any transport provider activity for this store should be stopped before logoff. Control is returned to the client after the activity is stopped and the MAPI spooler has logged off the store. If any transport activity is taking place, the logoff does not occur and no change in MAPI spooler or transport provider behavior occurs. If there is currently no activity, the MAPI spooler releases the store.

LOGOFF_NO_WAIT

The MAPI spooler should release the store and return control to the client immediately after all outbound mail that is ready to be sent is sent. If the message store has the default Inbox, any in-process message is received and then further reception is disabled.

LOGOFF_ORDERLY

The MAPI spooler should release the store and return control to the client immediately after any pending messages have finished processing. No new messages should be processed.

LOGOFF_PURGE

Works the same as the LOGOFF_NO_WAIT flag. The LOGOFF_PURGE flag returns control to the caller after completion.

LOGOFF_QUIET

The logoff should not occur if any transport provider activity is taking place. The type of activity taking place is returned as a flag on output.

On output, the MAPI spooler can return more than one flag and the following flags can be set:

LOGOFF_COMPLETE

The logoff can complete. All resources associated with the store have been released, and the object has been invalidated. The MAPI spooler has performed or will perform all requests. Only the message store’s IUnknown::Release method should be called at this point.

LOGOFF_INBOUND

A message is currently coming into the store from one or more transport providers.

LOGOFF_OUTBOUND

A message is currently being sent from the store by one or more transport providers.

LOGOFF_OUTBOUND_QUEUE

There are currently messages in the outbound queue for the store.

Return Values

S_OK

The logoff procedure was successful.

Remarks

The IMAPISupport::StoreLogoffTransports method is implemented for message store provider support objects. Message store providers call StoreLogoffTransports to give client applications some control over how MAPI handles transport provider activity as a message store is closing.

If another process has the store to be logged off open for the same profile, MAPI ignores a call to StoreLogoffTransports and returns the flag LOGOFF_COMPLETE in lpulFlags.

The behavior of the store provider following the return from StoreLogoffTransports should be based on the value of lpulFlags, which indicates system status and conveys client instructions on logoff behavior.

Notes to Callers

StoreLogoffTransports is typically called from a store provider’s IMsgStore::StoreLogoff method. However, it can also be called from the IUnknown::Release method of the message store. Implement the Release method of your message store so that you can check whether or not a call to StoreLogoffTransports has occurred. If not, call it with the LOGOFF_ABORT flag set.

The lpulFlags parameter is set to a flag that indicates how the client requires the message store to be shut down. Determine the appropriate setting for ulFlags based on the setting of the corresponding parameter in the call to IMsgStore::StoreLogoff method. That is, if a client called your StoreLogoff method with ulFlags set to LOGOFF_ORDERLY, you should call StoreLogoffTransports with ulFlags set to LOGOFF_ORDERLY.

For more information about the message store logoff process, see Shutting Down a Message Store Provider.

See Also

IMsgStore::StoreLogoff, IXPLogon::FlushQueues


IMAPISupport::Subscribe

The IMAPISupport::Subscribe method registers an advise sink to receive notifications through MAPI.

Quick Info

See IMAPISupport : IUnknown.

HRESULT Subscribe(

LPNOTIFKEY lpKey,
ULONG ulEventMask,
ULONG ulFlags,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
)
Parameters

lpKey

[in] Pointer to a notification key that represents the advise source object. The lpKey parameter cannot be NULL.

ulEventMask

[in] A mask of values indicating the types of notification events that the caller is interested in and should be included in the registration. The following values are valid:

fnevCriticalError

Registers for notifications about severe errors, such as insufficient memory.

fnevExtended

Registers for notifications about events specific to the particular address book or message store provider.

fnevNewMail

Registers for notifications about the arrival of new messages.

fnevObjectCreated

Registers for notifications about the creation of a new object.

fnevObjectCopied

Registers for notifications about an object being copied.

fnevObjectDeleted

Registers for notifications about an object being deleted.

fnevObjectModified

Registers for notifications about an object being modified.

fnevObjectMoved

Registers for notifications about an object being moved.

fnevSearchComplete

Registers for notifications about the completion of a search operation.

ulFlags

[in] Bitmask of flags that controls how notification occurs. The following flag can be set:

NOTIFY_SYNC

When the caller calls IMAPISupport::Notify to generate notifications for this advise sink, Notify should make all necessary calls to advise sinks before returning. If this flag is not set, notification is asynchronous and callbacks are queued to the processes that have subscribed and started when those processes gain control of the CPU.

lpAdviseSink

[in] Pointer to an advise sink object.

lpulConnection

[out] Pointer to a non-zero connection number representing the registration.

Return Values

S_OK

The notification registration was successful.

Remarks

The IMAPISupport::Subscribe method is implemented for all service provider support objects. Service providers call Subscribe from one of their Advise methods to allow MAPI to manage the notifications.

Notes to Callers

To use the MAPI support methods for notification, create a key for the advise source — the object about which notifications should be generated. The value of the key must be unique and should be easily regenerated each time the object changes.

MAPI uses the notification key to search for any callback functions registered through the HrAllocAdviseSink function for the corresponding advise source. Pass this key to IMAPISupport::Notify whenever you need to generate a notification for the corresponding advise source.

The NOTIFY_SYNC flag affects the operation of subsequent calls to Notify. When you set NOTIFY_SYNC, Notify does not return until it has finished sending all of the necessary notifications. When you do not set NOTIFY_SYNC, Notify operates asynchronously, possibly returning before all of the notifications have been sent.

See Also

HrAllocAdviseSink, IMAPIAdviseSink::OnNotify, IMAPISupport::Notify, NOTIFICATION, NOTIFKEY


IMAPISupport::Unsubscribe

The IMAPISupport::Unsubscribe method cancels the responsibility for sending notifications that was previously established with a call to the IMAPISupport::Subscribe method.

Quick Info

See IMAPISupport : IUnknown.

HRESULT Unsubscribe(

ULONG ulConnection
)
Parameters

ulConnection

[in] The non-zero connection number representing the notification registration previously established through IMAPISupport::Subscribe.

Return Values

S_OK

The notification registration was canceled.

MAPI_E_NOT_FOUND

The connection number passed in the ulConnection parameter does not exist.

Remarks

The IMAPISupport::Unsubscribe method is implemented for all service provider support objects. Service providers call Unsubscribe to cancel a notification registration previously set up by Subscribe. Unsubscribe cancels the registration by releasing the advise sink pointer passed in the Subscribe call.

Generally, the advise sink’s IUnknown::Release method is called during the Unsubscribe call, but if another thread is in the process of calling the IMAPIAdviseSink::OnNotify method for the advise sink object, the Release call is delayed until the OnNotify method returns.

See Also

IMAPIAdviseSink::OnNotify, IMAPISupport::Subscribe


IMAPISupport::WrapStoreEntryID

The IMAPISupport::WrapStoreEntryID method converts a message store’s internal entry identifier to an entry identifier in MAPI’s standard format.

Quick Info

See IMAPISupport : IUnknown.

HRESULT WrapStoreEntryID(

ULONG cbOrigEntry,
LPENTRYID lpOrigEntry,
ULONG FAR * lpcbWrappedEntry,
LPENTRYID FAR * lppWrappedEntry
)
Parameters

cbOrigEntry

[in] Count of bytes in the entry identifier pointed to by the lpOrigEntry parameter.

lpOrigEntry

[in] Pointer to the private entry identifier for the message store.

lpcbWrappedEntry

[out] Pointer to the count of bytes in the entry identifier pointed to by the lppWrappedEntry parameter.

lppWrappedEntry

[out] Pointer to a pointer to the wrapped entry identifier.

Return Values

S_OK

The entry identifier was successfully wrapped.

Remarks

The IMAPISupport::WrapStoreEntryID method is implemented for all service provider support objects. Service providers use WrapStoreEntryID to have MAPI generate an entry identifier for a message store that wraps the store’s internal entry identifier.

Notes to Callers

When a client calls your message store’s IMAPIProp::GetProps method to retrieve its PR_STORE_ENTRYID property and your message store uses an entry identifier in a private format, call WrapStoreEntryID and return the entry identifier pointed to by lppWrappedEntry.

Calls to the IMSProvider::Logon and IMSLogon::CompareEntryIDs methods always obtain the store’s private entry identifier; the wrapped version is used only between client applications and MAPI.

Free the memory for the entry identifier pointed to by the lppWrappedEntry parameter using the MAPIFreeBuffer function when you have finished using it.

See Also

IMAPIProp::GetProps, IMAPISupport::CompareEntryIDs, IMSLogon::CompareEntryIDs, IMSProvider::Logon, MAPIFreeBuffer


IMAPITable : IUnknown

The IMAPITable interface is used to provide a read-only view of a table. IMAPITable is used by clients and service providers to manipulate the way a table appears.

Quick Info

Header file:	MAPIDEFS.H
Exposed by:	Table objects
Implemented by:	Service providers and MAPI
Called by:	Client applications, service providers
Corresponding pointer type:	LPMAPITABLE
Vtable Order

GetLastError	Returns a MAPIERROR structure containing information about the previous error on the table.
Advise	Registers to receive notification of specified events affecting the table.
Unadvise	Cancels the sending of notifications previously set up with a call to the IMAPITable::Advise method.
GetStatus	Returns the table’s status and type.
SetColumns	Defines the particular properties and order of properties to appear as columns in the table.
QueryColumns	Returns a list of columns for the table.
GetRowCount	Returns the total number of rows in the table.
SeekRow	Moves the cursor to a specific position in the table.
SeekRowApprox	Moves the cursor to an approximate fractional position in the table.
QueryPosition	Retrieves the current table row position of the cursor, based on a fractional value.
FindRow	Finds the next row in a table that matches specific search criteria.
Restrict	Applies a filter to a table, reducing the row set to only those rows matching the specified criteria.
CreateBookmark	Marks the table’s current position.
FreeBookmark	Releases the memory associated with a bookmark.
SortTable	Orders the rows of the table based on sort criteria.
QuerySortOrder	Retrieves the current sort order for a table.
QueryRows	Returns one or more rows from a table, beginning at the current cursor position.
Abort	Stops any asynchronous operations currently in progress for the table.
ExpandRow	Expands a collapsed table category, adding the leaf rows belonging to the category to the table view.
CollapseRow	Collapses an expanded table category, removing the leaf rows belonging to the category from the table view.
WaitForCompletion	Suspends processing until one or more asynchronous operations in progress on the table have completed.
GetCollapseState	Returns the data necessary to rebuild the current collapsed or expanded state of a categorized table.
SetCollapseState	Rebuilds the current expanded or collapsed state of a categorized table using data that was saved by a prior call to the IMAPITable::GetCollapseState method.


IMAPITable::Abort

The IMAPITable::Abort method stops any asynchronous operations currently in progress for the table.

Quick Info

See IMAPITable : IUnknown.

HRESULT Abort()

Parameters

None

Return Values

S_OK

One or more asynchronous operations have been stopped.

MAPI_E_UNABLE_TO_ABORT

An asynchronous operation is in progress and cannot be stopped or it has already completed.

Remarks

The IMAPITable::Abort method stops any asynchronous operation that is currently in progress.

Notes to Callers

To find out if an asynchronous operation is in progress, call the IMAPITable::GetStatus method.

If Abort halts the processing of a call to the IMAPITable::Restrict method, the state of the table will be as it was at the time the Abort call is processed.

If Abort halts the processing of a call to the IMAPITable::SortTable method, the table’s sort order is unaffected and remains as it was before the SortTable call.

See Also

IMAPITable::GetStatus, IMAPITable::Restrict, IMAPITable::SortTable


IMAPITable::Advise

The IMAPITable::Advise method registers to receive notification of specified events affecting the table.

Quick Info

See IMAPITable : IUnknown.

HRESULT Advise(

ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
)
Parameters

ulEventMask

[in] Value indicating the type of event that will generate the notification. Only the following value is valid:

fnevTableModified

lpAdviseSink

[in] Pointer to an advise sink object to receive the subsequent notifications. This advise sink object must have been already allocated.

lpulConnection

[out] Pointer to a nonzero value that represents the successful notification registration.

Return Values

S_OK

The notification registration successfully completed.

MAPI_E_NO_SUPPORT

The table implementation either does not support changes to its rows and columns or does not support notification.

Remarks

Use the IMAPITable::Advise method to register a table object implemented in the provider for notification callbacks. Whenever a change occurs to the table object, the provider checks to see what event mask bit was set in the ulEventMask parameter and thus what type of change occurred. If a bit is set, then the provider calls the IMAPIAdviseSink::OnNotify method for the advise sink object indicated by the lpAdviseSink parameter to report the event. Data passed in the notification structure to the OnNotify routine describes the event.

The call to OnNotify can occur during the call that changes the object, or at any following time. On systems that support multiple threads of execution, the call to OnNotify can occur on any thread. For a way to turn a call to OnNotify that might happen at an inopportune time into one that is safer to handle, a provider should use the HrThisThreadAdviseSink function.

To provide notifications, the provider implementing Advise needs to keep a copy of the pointer to the lpAdviseSink advise sink object; to do so, it calls the IUnknown::AddRef method for the advise sink to maintain its object pointer until notification registration is canceled with a call to the IMAPITable::Unadvise method. The Advise implementation should assign a connection number to the notification registration and call AddRef on this connection number before returning it in the lpulConnection parameter. Service providers can release the advise sink object before the registration is canceled, but they must not release the connection number until Unadvise has been called.

After a call to Advise has succeeded and before Unadvise has been called, clients must be prepared for the advise sink object to be released. A client should therefore release its advise sink object after Advise returns unless it has a specific long-term use for it.

Because of the asynchronous behavior of notification, implementations that change table column settings can receive notifications with information organized in a previous column order. For instance, a table row might be returned for a message that has just been deleted from the container. Such a notification is sent when the column setting change has been made and information about it sent but the notification table view has not been updated with that information yet.

For more information on the notification process, see Event Notification in MAPI. For specific information about table notification, see About Table Notifications. For information about using the IMAPISupport methods to support notification, see Using A Support Object for Event Notification.

See Also

HrThisThreadAdviseSink, IMAPIAdviseSink::OnNotify, IMAPITable::Unadvise, TABLE_NOTIFICATION


IMAPITable::CollapseRow

The IMAPITable::CollapseRow method collapses an expanded table category, removing the leaf rows belonging to the category from the table view.

Quick Info

See IMAPITable : IUnknown.

HRESULT CollapseRow(

ULONG cbInstanceKey,
LPBYTE pbInstanceKey,
ULONG ulFlags,
ULONG FAR * lpulRowCount
)
Parameters

cbInstanceKey

[in] Count of bytes in the PR_INSTANCE_KEY property pointed to by the pbInstanceKey parameter.

pbInstanceKey

[in] Pointer to the PR_INSTANCE_KEY property that identifies the heading row for the category.

ulFlags

Reserved; must be zero.

lpulRowCount

[out] Pointer to the total number of rows that are being removed from the table view.

Return Values

S_OK

The collapse operation has succeeded.

MAPI_E_NOT_FOUND

The row identified by the pbInstanceKey parameter does not exist.

MAPI_E_INVALID_ENTRYID

The row identified by the pbInstanceKey parameter does not exist. This error is an alternative to MAPI_E_NOT_FOUND; service providers can return either one.

Remarks

The IMAPITable::CollapseRow method collapses a table category and removes it from the table view. The rows are collapsed starting at the row identified by the PR_INSTANCE_KEY property pointed to by the pbInstanceKey parameter. The number of rows that are removed from the view is returned in the contents of the lpulRowCount parameter.

Notifications are never generated for table rows that are removed from a view as the result of a collapse operation.

When a row that is defined by a bookmark is collapsed out of view, the bookmark is moved to point to the next visible row.

For more information about categorized tables, see Sorting and Categorization.

See Also

IMAPITable::ExpandRow, IMAPITable::GetCollapseState, IMAPITable::QuerySortOrder, IMAPITable::SetCollapseState, IMAPITable::SortTable, SSortOrderSet


IMAPITable::CreateBookmark

The IMAPITable::CreateBookmark method marks the table’s current position.

Quick Info

See IMAPITable : IUnknown.

HRESULT CreateBookmark(

BOOKMARK FAR * lpbkPosition
)
Parameters

lpbkPosition

[out] Pointer to the returned 32-bit bookmark value. This bookmark can later be passed in a call to the IMAPITable::SeekRow method.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_UNABLE_TO_COMPLETE

The requested operation could not be completed.

Remarks

The IMAPITable::CreateBookmark method marks a table position by creating a value called a bookmark. A bookmark can be used to return to the position identified by the bookmark. The bookmarked position is associated with the object at that row in the table.

Bookmarks are not supported on attachment tables, and attachment table implementations of CreateBookmark return MAPI_E_NO_SUPPORT.

Notes to Implementers

Because of the memory expense of maintaining cursor positions with bookmarks, limit the number of bookmarks that you can create. When you reach that number, return MAPI_E_UNABLE_TO_COMPLETE from all subsequent calls to CreateBookmark.

Sometimes a bookmark points to a row that is no longer in the table view. If a caller uses such a bookmark, move the cursor to the next visible row and stop there.

When the caller attempts to use a bookmark that is pointing to a nonvisible row because it has been collapsed, return MAPI_W_POSITION_CHANGED after moving the bookmark. You can reposition the bookmark to the next visible row either at this time or when the collapsing occurs in the SetCollapseState method. If you move the bookmark at the time the row is collapsed, you must retain a bit in the bookmark that indicates exactly when the bookmark was moved: since its last use or — if it has never been used — since its creation.

Notes to Callers

CreateBookmark allocates memory for the bookmark it creates. Release the resources for the bookmark by calling the IMAPITable::FreeBookmark method.

See Also

IMAPITable::FreeBookmark, IMAPITable::SeekRow


IMAPITable::ExpandRow

The IMAPITable::ExpandRow method expands a collapsed table category, adding the leaf rows belonging to the category to the table view.

Quick Info

See IMAPITable : IUnknown.

HRESULT ExpandRow(

ULONG cbInstanceKey,
LPBYTE pbInstanceKey,
ULONG ulRowCount,
ULONG ulFlags,
LPSRowSet FAR * lppRows,
ULONG FAR * lpulMoreRows
)
Parameters

cbInstanceKey

[in] Count of bytes in the PR_INSTANCE_KEY property pointed to by the pbInstanceKey parameter.

pbInstanceKey

[in] Pointer to the PR_INSTANCE_KEY property that identifies the heading row for the category.

ulRowCount

[in] Maximum number of leaf rows to add to the table view.

ulFlags

Reserved; must be zero.

lppRows

[out] Pointer to an SRowSet structure holding the leaf rows that have been inserted into the table view as a result of the expansion. These rows are inserted after the heading row identified by the pbInstanceKey parameter. The lppRows parameter can be NULL if the ulRowCount parameter is zero.

lpulMoreRows

[out] Pointer to the total number of rows that were added to the table view.

Return Values

S_OK

The category was expanded successfully.

MAPI_E_NOT_FOUND

The row identified by the pbInstanceKey parameter does not exist.

Remarks

The IMAPITable::ExpandRow method expands a collapsed table category, adding the leaf rows that belong to the category to the table view. A limit to the number of rows to be included in the expanded category can be specified in the ulRowCount parameter. When ulRowCount is set to a value greater than zero and one or more rows are returned in the row set pointed to by lppRows, the position of the bookmark BOOKMARK_CURRENT is moved to the row immediately following the last row in the row set.

When ulRowCount is set to zero, requesting that zero leaf rows be added to the category, or zero rows are returned because there are no leaf rows in the category, the position of BOOKMARK_CURRENT is set to the row following the row identified by pbInstanceKey.

Notes to Implementers

Do not generate notifications on rows that are added to a table view due to category expansion.

Notes to Callers

The number of rows in the row set pointed to by the lppRows parameter might not equal the number of rows that were actually added to the table, the entire set of leaf rows for the category. Errors can occur, such as insufficient memory, or the number of rows in the category exceeding the number specified in ulRowCount parameter. In either case, BOOKMARK_CURRENT will be positioned to the last row returned. To immediately retrieve the rest of the rows in the category, call IMAPITable::QueryRows.

Do not expect to receive a table notification when a category changes its state. You can maintain a local cache of rows that can be updated with every ExpandRow or CollapseRow call.

For more information about categorized tables, see Sorting and Categorization.

See Also

IMAPITable::CollapseRow


IMAPITable::FindRow

The IMAPITable::FindRow method finds the next row in a table that matches specific search criteria.

Quick Info

See IMAPITable : IUnknown.

HRESULT FindRow(

LPSRestriction lpRestriction,
BOOKMARK BkOrigin,
ULONG ulFlags
)
Parameters

lpRestriction

[in] Pointer to an SRestriction structure that describes the search criteria.

BkOrigin

[in] Bookmark identifying the row where FindRow should begin its search. A bookmark can be created using the IMAPITable::CreateBookmark method, or one of the following predefined values can be passed:

BOOKMARK_BEGINNING

Searches from the beginning of the table.

BOOKMARK_CURRENT

Searches from the row in the table where the cursor is located.

BOOKMARK_END

Searches from the end of the table.

ulFlags

[in] Bitmask of flags that controls the direction of the search. The following flag can be set:

DIR_BACKWARD

Searches backward from the row identified by the bookmark.

Return Values

S_OK

The find operation was successful.

MAPI_E_INVALID_BOOKMARK

The bookmark in the BkOrigin parameter is invalid because it has been removed or because it is beyond the last row requested.

MAPI_E_NOT_FOUND

No rows were found that matched the restriction.

MAPI_W_POSITION_CHANGED

The call succeeded, but the bookmark used in the operation is no longer set at the same row as when it was last used; if the bookmark has not been used, it is no longer in the same position as when it was created. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPITable::FindRow method locates the first row in the table to match a set of search criteria described in the SRestriction structure pointed to by the lpRestriction parameter.

Usually, FindRow searches forward from the specified bookmark. The caller can set the search to move backward from the bookmark by setting the DIR_BACKWARD flag in the ulFlags parameter. Searching forward starts from the current bookmark; searching backward starts from the row prior to the bookmark. The end position of the search is just before the first row found that satisfied the restriction. FindRow returns the data of the found row.

If the row pointed to by the bookmark in the BkOrigin parameter no longer exists in the table and the table cannot establish a new position for the bookmark, FindRow returns MAPI_E_INVALID_BOOKMARK. If the row pointed to by BkOrigin no longer exists and the table is able to establish a new position for the bookmark, FindRow returns MAPI_W_POSITION_CHANGED.

If the bookmark passed in BkOrigin is either BOOKMARK_BEGINNING or BOOKMARK_END, FindRow returns MAPI_E_NOT_FOUND if no matching row is found. If the bookmark used in BkOrigin is BOOKMARK_CURRENT, FindRow can return MAPI_W_POSITION_CHANGED but not MAPI_E_INVALID_BOOKMARK, because there is always a current cursor position.

The PR_INSTANCE_KEY property column is required for all tables, and all implementations of FindRow are required to support calls seeking a row based on PR_INSTANCE_KEY.

Notes to Implementers

The type of prefix searching performed by FindRow is only useful when the search follows the same direction as the table organization. In order to achieve the required behavior, the comparison function implied by the RELOP_GE passed in the property restriction structure should be the same comparison function on which the table sort order is based.

Notes to Callers

You can use FindRow to support scrolling based on strings typed in by the user, especially in list boxes within address dialog boxes. In this type of scrolling, users enter progressively longer prefixes of a desired string value, and you can periodically issue a FindRow call to jump to the first row that matches the prefix. Which direction the cursor jumps depends on which direction the search is set to run.

To use FindRow, a bookmark must be set. The string search can originate from any bookmark, including from the preset bookmarks indicating the current position and the beginning and end of the table. If there is a large number of rows in the table, the search operation can be slow.

Use a restriction to find a string prefix for scrolling as follows. For forward searching on a column sorted in ascending order and for backward searching on a column sorted in descending order, pass a property restriction structure in the lpRestriction parameter with the relation RELOP_GE and the appropriate property tag and prefix, using the format tag GE prefix.

For more information about using restriction structures to specify a filter, see About Restrictions. For information about using regular expressions in restrictions, see Regular Expressions.

See Also

IMAPITable::CreateBookmark, SPropertyRestriction, SRestriction


IMAPITable::FreeBookmark

The IMAPITable::FreeBookmark method releases the memory associated with a bookmark.

Quick Info

See IMAPITable : IUnknown.

HRESULT FreeBookmark(

BOOKMARK bkPosition
)
Parameters

bkPosition

[in] The bookmark to be freed, created by calling the IMAPITable::CreateBookmark method.

Return Values

S_OK

The bookmark was successfully freed.

MAPI_E_INVALID_BOOKMARK

The specified bookmark does not exist.

Remarks

The IMAPITable::FreeBookmark releases a bookmark that is no longer needed. The bookmark is no longer valid after this call. Whenever a table is released from memory, all of its associated bookmarks are also released.

Notes to Implementers

If the caller passes one of the three predefined bookmarks in the bkPosition parameter, ignore the request and return S_OK.

See Also

IMAPITable::CreateBookmark


IMAPITable::GetCollapseState

The IMAPITable::GetCollapseState method returns the data necessary to rebuild the current collapsed or expanded state of a categorized table.

Quick Info

See IMAPITable : IUnknown.

HRESULT GetCollapseState(

ULONG ulFlags,
ULONG cbInstanceKey,
LPBYTE lpbInstanceKey,
ULONG FAR * lpcbCollapseState,
LPBYTE FAR * lppbCollapseState
)
Parameters

ulFlags

Reserved; must be zero.

cbInstanceKey

[in] Count of bytes in the instance key pointed to by the lpbInstanceKey parameter.

lpbInstanceKey

[in] Pointer to the PR_INSTANCE_KEY property of the row at which the current collapsed or expanded state should be rebuilt. The lpbInstanceKey parameter cannot be NULL.

lpcbCollapseState

[out] Pointer to the count of structures pointed to by the lppbCollapseState parameter.

lppbCollapseState

[out] Pointer to a pointer to structures containing data describing the current table view.

Return Values

S_OK

The state for the categorized table was successfully saved.

MAPI_E_BUSY

Another operation is in progress that prevents the operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

MAPI_E_NO_SUPPORT

The table does not support categorization and expanded and collapsed views.

Remarks

The IMAPITable::GetCollapseState method works with the IMAPITable::SetCollapseState method to change the user’s view of a categorized table. GetCollapseState saves the data necessary for SetCollapseState to use to rebuild the appropriate views of the categories of a categorized table. Service providers determine the data to be saved. However, most service providers implementing GetCollapseState save:

•	The sort keys (standard columns and category columns).

•	Information about the row that the instance key represents.

•	Information to restore the collapsed and expanded categories of the table.

For more information about categorized tables, see Sorting and Categorization.

Notes to Implementers

Store the entire current state of all nodes of a table in the lppbCollapseState parameter.

Notes to Callers

Always call GetCollapseState before calling SetCollapseState.

See Also

IMAPITable::SetCollapseState


IMAPITable::GetLastError

The IMAPITable::GetLastError method returns a MAPIERROR structure containing information about the previous error on the table.

Quick Info

See IMAPITable : IUnknown.

HRESULT GetLastError(

HRESULT hResult,
ULONG ulFlags,
LPMAPIERROR FAR * lppMAPIError
)
Parameters

hResult

[in] HRESULT data type containing the error value generated in the previous method call.

ulFlags

[in] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] Pointer to a pointer to the returned MAPIERROR structure containing version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if a MAPIERROR structure with appropriate information cannot be provided.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

Remarks

The IMAPITable::GetLastError method returns detailed information, if available, about a prior method call that failed. This information can be displayed in a message or a dialog box.

Notes to Callers

Call GetLastError whenever you need to display information about an error to the user.

You can make use of the MAPIERROR structure pointed to by the lppMAPIError parameter — if the table object supplies one — only if GetLastError returns S_OK. Sometimes the table implementation cannot determine what the last error was or has nothing more to report about the error. In this situation, you’ll find a pointer to NULL in lppMAPIError instead.

To release all the memory allocated for the MAPIERROR structure, call the MAPIFreeBuffer function.

For more information about the GetLastError method, see Using Extended Errors.

See Also

MAPIERROR, MAPIFreeBuffer


IMAPITable::GetRowCount

The IMAPITable::GetRowCount method returns the total number of rows in the table.

Quick Info

See IMAPITable : IUnknown.

HRESULT GetRowCount(

ULONG ulFlags,
ULONG FAR * lpulCount
)
Parameters

ulFlags

Reserved; must be zero.

lpulCount

[out] Pointer to the number of rows in the table.

Return Values

S_OK

The row count was successfully returned.

MAPI_E_BUSY

Another operation is in progress that prevents the row count retrieval operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

MAPI_E_NO_SUPPORT

The table cannot calculate the number of rows.

MAPI_W_APPROX_COUNT

The call succeeded, but an approximate row count was returned because the exact row count could not be determined possibly due to memory constraints. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPITable::GetRowCount method retrieves the total number of rows in a table.

Notes to Implementers

If you cannot determine the table’s exact row count, return MAPI_W_APPROX_COUNT and an approximate row count in the contents of the lpulCount parameter.

Notes to Callers

Use GetRowCount to find out how many rows a table holds before making a call to the IMAPITable::QueryRows method to retrieve the data. If there are less than twenty rows in the table, it is safe to call QueryRows to retrieve the whole table. If there are more than twenty rows in the table, consider making multiple calls to QueryRows and limit the number of rows retrieved in each call.

Some tables do not support GetRowCount and return MAPI_E_NO_SUPPORT. If GetRowCount is not supported, an alternative might be to call IMAPITable::QueryPosition. With the results from QueryPosition, you can determine the relationship between the current row and last row.

When GetRowCount returns MAPI_E_BUSY because it is temporarily unable to retrieve a row count, call the IMAPITable::WaitForCompletion method. When WaitForCompletion returns, retry the call to GetRowCount. Another way to detect whether an asynchronous operation is in progress is to call the IMAPITable::GetStatus method and check the contents of the lpulTableState parameter.

See Also

IMAPITable::GetStatus, IMAPITable::QueryPosition, IMAPITable::QueryRows, IMAPITable::WaitForCompletion


IMAPITable::GetStatus

The IMAPITable::GetStatus method returns the table’s status and type.

Quick Info

See IMAPITable : IUnknown.

HRESULT GetStatus(

ULONG FAR * lpulTableStatus,
ULONG FAR * lpulTableType
)
Parameters

lpulTableStatus

[out] Pointer to a value indicating the status of the table. One of the following values can be returned:

TBLSTAT_COMPLETE

No operations are in progress.

TBLSTAT_QCHANGED

The contents of the table has expectantly changed. This status value is not returned for changes that result from sort or restriction operations.

TBLSTAT_RESTRICT_ERROR

An error occurred during an IMAPITable::Restrict operation.

TBLSTAT_RESTRICTING

An IMAPITable::Restrict operation is in progress.

TBLSTAT_SETCOL_ERROR

An error occurred during an IMAPITable::SetColumns operation.

TBLSTAT_SETTING_COLS

An IMAPITable::SetColumns operation is in progress.

TBLSTAT_SORT_ERROR

An error occurred during an IMAPITable::SortTable operation.

TBLSTAT_SORTING

An IMAPITable::SortTable operation is in progress.

lpulTableType

[out] Pointer to a value that indicates the table’s type. One of the following three table types can be returned:

TBLTYPE_DYNAMIC

The table’s contents are dynamic; the rows and column values can change as the underlying data changes.

TBLTYPE_KEYSET

The rows within the table are fixed, but the values of the columns within these rows are dynamic and can change as the underlying data changes.

TBLTYPE_SNAPSHOT

The table is static, and its contents do not change when the underlying data changes.

Return Values

S_OK

The table’s status was successfully returned.

Remarks

The IMAPTable::GetStatus method retrieves information about a table’s type and current status.

Notes to Callers

You can use GetStatus in conjunction with three other IMAPITable methods to monitor the status of those operations and determine the affect on the table. Call GetStatus after making one of the following IMAPITable calls:

•	IMAPITable::Restrict to enforce a restriction.

•	IMAPITable::SortTable to establish a sort order.

•	IMAPITable::SetColumns to define a column set.

See Also

IMAPITable::Restrict, IMAPITable::SetColumns, IMAPITable::SortTable


IMAPITable::QueryColumns

The IMAPITable::QueryColumns method returns a list of columns for the table.

Quick Info

See IMAPITable : IUnknown.

HRESULT QueryColumns(

ULONG ulFlags,
LPSPropTagArray FAR * lpPropTagArray
)
Parameters

ulFlags

[in] Bitmask of flags that indicates which column set should be returned. The following flag can be set:

TBL_ALL_COLUMNS

The table should return all available columns.

lpPropTagArray

[out] Pointer to an SPropTagArray structure containing the property tags for the column set.

Return Values

S_OK

The column set was successfully returned.

MAPI_E_BUSY

Another operation is in progress that prevents the column set retrieval operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

Remarks

The IMAPITable::QueryColumns method can be called to retrieve:

•	The default column set for a table.

•	The current column set for a table, as established by a call to the IMAPITable::SetColumns method.

•	The complete column set for a table, the columns that are available, but not necessarily part of the current set.

Notes to Callers

If you do not set the TBL_ALL_COLUMNS flag, IMAPITable::QueryColumns returns either a table’s default or current column set, depending on whether the table has been affected by a call to IMAPITable::SetColumns. SetColumns changes the order and selection of columns in a table’s column set.

If you set the TBL_ALL_COLUMNS flag, IMAPITable::QueryColumns returns all of the columns that are capable of being in the table’s column set.

Free the memory for the property tag array pointed to by the lpPropTagArray parameter by calling the MAPIFreeBuffer function.

See Also

IMAPITable::SetColumns, MAPIFreeBuffer, SPropTagArray


IMAPITable::QueryPosition

The IMAPITable::QueryPosition method retrieves the current table row position of the cursor, based on a fractional value.

Quick Info

See IMAPITable : IUnknown.

HRESULT QueryPosition(

ULONG FAR * lpulRow,
ULONG FAR * lpulNumerator,
ULONG FAR * lpulDenominator
)
Parameters

lpulRow

[out] Pointer to the number of the current row. The row number is zero-based; the first row in the table is zero.

lpulNumerator

[out] Pointer to the numerator for the fraction identifying the table position.

lpulDenominator

[out] Pointer to the denominator for the fraction identifying the table position. The lpulDenominator parameter cannot be zero.

Return Values

S_OK

The method returned valid values in lpulRow, lpulNumerator, and lpulDenominator.

Remarks

The IMAPITable::QueryPosition method determines the current row position and returns both the number of the current row and a fractional value indicating its relative position to the end of the table. MAPI defines the current row as the next row to be read.

Notes to Implementers

You do not need to return the exact number of rows in the table for the lpulDenominator parameter; it can be an approximation.

If you cannot determine the current row, return a value of 0xFFFFFFFF in lpulRow.

Notes to Callers

You can use QueryPosition to position a scroll box in a scroll bar. For example, in a table containing 100 rows, if QueryPosition returns a value of 75 in the lpulNumerator parameter, 100 in the lpulDenominator parameter, and 75 in the lpulRow parameter, you can position the scroll box 3/4 of the way across the scroll bar.

Do not rely on the value in lpulDenominator being the number of rows in the table. QueryPosition cannot always identify the exact row that the cursor is positioned on.

A call to QueryPosition might involve large amounts of memory, particularly for large categorized tables. If the lpulRow parameter is set to 0xFFFFFFFF, too much memory was required for QueryPosition to determine the current row. Call the IMAPITable::SeekRowApprox method to position the table to the row identified by the lpulNumerator and lpulDenominator parameters. However, do not always expect SeekRowApprox to establish as the current position the same row QueryPosition would have if memory had not been a factor.

See Also

IMAPITable::SeekRowApprox


IMAPITable::QueryRows

The IMAPITable::QueryRows method returns one or more rows from a table, beginning at the current cursor position.

Quick Info

See IMAPITable : IUnknown.

HRESULT QueryRows(

LONG lRowCount,
ULONG ulFlags,
LPSRowSet FAR * lppRows
)
Parameters

lRowCount

[in] Maximum number of rows to be returned.

ulFlags

[in] Bitmask of flags that controls how rows are returned. The following flag can be set:

TBL_NOADVANCE

Prevents the cursor from advancing as a result of the row retrieval. If the TBL_NOADVANCE flag is set, the cursor points to the first row returned. If the TBL_NOADVANCE flag is not set, the cursor points to the row following the last row returned.

lppRows

[out] Pointer to a pointer to an SRowSet structure holding the table rows.

Return Values

S_OK

The rows were successfully returned.

MAPI_E_BUSY

Another operation is in progress that prevents the row retrieval operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

MAPI_E_INVALID_PARAMETER

The lRowCount parameter is set to zero.

Remarks

The IMAPITable::QueryRows method gets one or more rows of data from a table. The value of the lRowCount parameter affects the starting point for the retrieval. If lRowCount is positive, rows are read in a forward direction, starting at the current position. If lRowCount is negative, QueryRows resets the starting point by moving backward the indicated number of rows. After the cursor is reset, rows are read in forward order.

The cRows member in the SRowSet structure pointed to by the lppRows parameter indicates the number of rows returned. If zero rows are returned:

•	The cursor was already positioned at the beginning of the table and the value of IRowCount is negative.

-Or-

•	The cursor was already positioned at the end of the table and the value of IRowCount is positive.

The number of columns and their ordering is the same for each row. If a property does not exist for a row or there is an error reading a property, the SPropValue structure for the property in the row contains the following values:

•	PT_ERROR for the property type in the ulPropTag member

•	MAPI_E_NOT_FOUND for the Value member

Memory used for the SPropValue structures in the row set pointed to by the lppRows parameter must be separately allocated and freed for each row. Use MAPIFreeBuffer to free the property value structures and to free the row set. When a call to QueryRows returns zero, however, indicating the beginning or end of the table, only the SRowSet structure itself needs to be freed. For more information about how to allocate and free memory in an SRowSet structure, see Managing Memory for ADRLIST and SRowSet Structures.

The rows that are returned and the order in which they are returned depend on whether or not successful calls have been made to IMAPITable::Restrict and IMAPITable::SortTable. Restrict filters rows from the view, causing QueryRows to return only the rows that match the criteria specified in the restriction. SortTable establishes a standard or categorized sort order, affecting the sequence of rows returned by QueryRows. The returned rows are in the order specified in the SSortOrderSet structure passed to SortTable.

The columns returned for each row and the order in which they are returned depend on whether or not a successful call has been made to IMAPITable::SetColumns. SetColumns establishes a column set, specifying the properties to be included in columns in the table and the order in which they should be included. If a SetColumns call has been made, the particular columns in each row and the order of those columns match the column set specified in the call. If no SetColumns call has been made, the table returns its default column set.

If none of these calls has been made, QueryRows returns all of the rows in the table. Each row contains the default column set in default order.

When the column set established in a call to IMAPITable::SetColumns includes columns set to PR_NULL, the SPropValue array within the row set returned in lppRows will contain empty slots.

Notes to Implementers

You can allow a caller to request an unsupported column to be included in the column set. When this occurs, place PT_ERROR in the property type portion of the property tag and MAPI_E_NOT_FOUND in the property value for the unsupported column.

Treat the row count as a request rather than a requirement. You can return anywhere from zero rows, if there are no rows in the direction of the query, to the number requested.

Return only the rows that the user will see when rows are requested from a categorized table view, allowing the caller to make valid assumptions about the scope of the data and avoid extra work.

Notes to Callers

Usually you will end up with as many rows as you have specified in the lRowCount parameter. However, when memory or implementation limits are an issue or when the operation reaches the beginning or end of the table prematurely, QueryRows will return less rows than requested.

If QueryRows returns MAPI_E_BUSY, call the IMAPITable::WaitForCompletion method and retry the call to QueryRows when the asynchronous operation is complete.

When calling QueryRows, be aware that the timing of asynchronous notifications can potentially cause the row set that you get back from QueryRows to not accurately represent the underlying data. For example, a call to QueryRows to a folder’s contents table following the deletion of a message but prior to the receipt of the corresponding notification will cause the deleted row to be returned in the row set. Always wait for a notification to arrive before updating the user’s view of the data.

For more information about retrieving rows from tables, see Retrieving Data from Table Rows.

See Also

ADRENTRY, FreeProws, HrQueryAllRows, IMAPIProp::GetProps, IMAPITable::SetColumns, IMAPITable::WaitForCompletion, MAPIFreeBuffer, SRow, SRowSet


IMAPITable::QuerySortOrder

The IMAPITable::QuerySortOrder method retrieves the current sort order for a table.

Quick Info

See IMAPITable : IUnknown.

HRESULT QuerySortOrder(

LPSSortOrderSet FAR * lppSortCriteria
)
Parameters

lppSortCriteria

[out] Pointer to a pointer to the SSortOrderSet structure holding the current sort order.

Return Values

S_OK

The current sort order was successfully returned.

MAPI_E_BUSY

Another operation is in progress that prevents the sort order retrieval operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

Remarks

The IMAPITable::QuerySortOrder method retrieves the current sort order for a table. Sort orders are described with an SSortOrderSet structure.

The cSorts member of the SSortOrderSet structure can be set to zero if:

•	The table is unsorted.

•	There is no information about how the table is sorted.

•	The SSortOrderSet structure is not appropriate for describing the sort order.

Notes to Implementers

If a call is made to your IMAPITable::SortTable method with an SSortOrderSet structure containing zero columns in the sort key, remove the current sort order and apply the default order, if there is one. In subsequent calls to QuerySortOrder, you can choose whether to return zero or more columns for the sort key. You can return more columns than are in the present view.

For more information about sorting, see Sorting and Categorization.

See Also

IMAPITable::SortTable, MAPIFreeBuffer, SSortOrderSet


IMAPITable::Restrict

The IMAPITable::Restrict method applies a filter to a table, reducing the row set to only those rows matching the specified criteria.

Quick Info

See IMAPITable : IUnknown.

HRESULT Restrict(

LPSRestriction lpRestriction,
ULONG ulFlags
)
Parameters

lpRestriction

[in] Pointer to an SRestriction structure defining the conditions of the filter. Passing NULL in the lpRestriction parameter removes the current filter.

ulFlags

[in] Bitmask of flags that controls the timing of the restriction operation. The following flags can be set:

TBL_ASYNC

Starts the operation asynchronously and returns before the operation completes.

TBL_BATCH

Defers evaluation of the filter until the data in the table is required.

Return Values

S_OK

The filter was successfully applied.

MAPI_E_BUSY

Another operation is in progress that prevents the restriction operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

MAPI_E_TOO_COMPLEX

The table cannot perform the operation because the particular filter pointed to by the lpRestriction parameter is too complicated.

Remarks

The IMAPITable::Restrict method establishes a restriction, or filter, on a table. If there is a previous restriction, it is discarded and the new one applied. Applying a restriction has no affect on the underlying data of a table; it simply alters the view by limiting the rows that can be retrieved to rows containing data that satisfy the restriction.

There are several different types of restrictions, each described with a different structure. The SRestriction structure contains two members: a value that indicates the type of restriction and the specific structure applicable for that type.

Notifications for table rows that are hidden from view by calls to Restrict are never generated.

A property restriction on a multivalued property works like a restriction on a single-valued property. A multivalued property to be used in a property restriction must have the MVI_FLAG flag set. If it doesn’t have this flag set, it is treated as a totally ordered tuple. A comparison of two multivalued columns compares the column elements in order, reporting the relation of the columns at the first inequality. Equality is returned only if the columns compared contain the same values in the same order. If one column has fewer values than the other, the reported relation is that of a null value to the other value.

For more information about restrictions, see About Restrictions.

Notes to Callers

To discard the current restriction without creating a new one, pass NULL in lpRestriction.

If another asynchronous table call is in progress, causing Restrict to return MAPI_E_BUSY, you can call IMAPITable::Abort to stop the call.

Restrict operates synchronously unless you set one of the flags. If you set the TBL_BATCH flag, Restrict postpones the evaluation of the restriction unless you request the data. If the TBL_ASYNC flag is set, Restrict operates asynchronously, potentially returning before the completion of the operation.

All bookmarks for a table are discarded when a call to Restrict is made, and BOOKMARK_CURRENT, the current cursor position, is set to the beginning of the table.

If you attempt to impose a property restriction on a property that is not in the table’s column set, the results are undefined. Whenever you are unsure as to whether a property is supported in a table, combine the property restriction with an exists restriction. The exists restriction checks for the existence of the property before attempting to impose the property restriction.

Do not expect to receive a table notification on a row that has been filtered from a table due to a restriction.

See Also

IMAPITable::Abort, IMAPITable::FindRow, IMAPITable::GetRowCount, IMAPITable::QueryRows, SPropertyRestriction


IMAPITable::SeekRow

The IMAPITable::SeekRow method moves the cursor to a specific position in the table.

Quick Info

See IMAPITable : IUnknown.

HRESULT SeekRow(

BOOKMARK bkOrigin,
LONG lRowCount,
LONG FAR * lplRowsSought
)
Parameters

bkOrigin

[in] Bookmark identifying the starting position for the seek operation. A bookmark can be created using the IMAPITable::CreateBookmark method, or one of the following predefined values can be passed:

BOOKMARK_BEGINNING

Starts the seek operation from the beginning of the table.

BOOKMARK_CURRENT

Starts the seek operation from the row in the table where the cursor is located.

BOOKMARK_END

Starts the seek operation from the end of the table.

lRowCount

[in] Signed count of the number of rows to move, starting from the bookmark identified by the bkOrigin parameter.

lplRowsSought

[in-out] If lplRowsSought is a valid pointer on input, on output it points to the number of rows that were processed in the seek operation. If lplRowsSought is NULL on input — indicating that the caller is not interested in the number of rows processed — nothing is returned on output.

Return Values

S_OK

The seek operation was successful.

MAPI_E_BUSY

Another operation is in progress that prevents the row seeking operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

MAPI_E_INVALID_BOOKMARK

The bookmark specified in the bkOrigin parameter is invalid because it has been removed or because it is beyond the last row requested.

MAPI_W_POSITION_CHANGED

The call succeeded, but the bookmark specified in the bkOrigin parameter is no longer set at the same row as when it was last used. If the bookmark has not been used, it is no longer in the same position as when it was created. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPITable::SeekRow method establishes a new BOOKMARK_CURRENT position for the cursor. The lRowCount parameter indicates the number of rows that the cursor moves and the direction of movement.

If the resulting position is beyond the last row of the table, the cursor is positioned after the last row. If the resulting position is before the first row of the table, the cursor is placed at the beginning of the first row.

Notes to Implementers

If the row pointed to by bkOrigin no longer exists in the table and you cannot establish a new position for the bookmark, return MAPI_E_INVALID_BOOKMARK. If the row pointed to by bkOrigin no longer exists and you can establish a new position for the bookmark, return MAPI_W_POSITION_CHANGED.

A bookmark pointing to a row that is collapsed out of the table view can still be used. If the caller attempts to move the cursor to such a bookmark, move the cursor to the next visible row and return MAPI_W_POSITION_CHANGED.

You can move bookmarks for positions collapsed out of view either at the time of use or at the time the row is collapsed. If a bookmark is moved at the time the row is collapsed, keep a bit in the bookmark that indicates whether the bookmark has moved since its last use or, if it has never been used, since its creation.

Notes to Callers

To indicate a backward move for SeekRow, pass a negative value in lRowCount. To search to the beginning of the table, pass zero in lRowCount and the value BOOKMARK_BEGINNING in bkOrigin.

If there are large numbers of rows in the table, the SeekRow operation can be slow. Performance can also be impacted if you require a row count to be returned in the contents of the lplRowsSought parameter.

SeekRow returns the number of rows actually searched through, positive or negative, in the variable pointed to by lplRowsSought. In normal operation, it should return the same value for lplRowsSought as passed in for lRowCount, unless the search reached the beginning or end of the table.

Do not set lRowCount to a number greater than 50. To seek through a larger number of rows, use the IMAPITable::SeekRowApprox method.

See Also

IMAPITable::CreateBookmark, IMAPITable::FindRow, IMAPITable::QueryRows, IMAPITable::SeekRowApprox


IMAPITable::SeekRowApprox

The IMAPITable::SeekRowApprox method moves the cursor to an approximate fractional position in the table.

Quick Info

See IMAPITable : IUnknown.

HRESULT SeekRowApprox(

ULONG ulNumerator,
ULONG ulDenominator
)
Parameters

ulNumerator

[in] Pointer to the the numerator of the fraction representing the table position. If the ulNumerator parameter is zero, the cursor is positioned at the beginning of the table regardless of the denominator value. If ulNumerator is equal to the ulDenominator parameter, the cursor is positioned after the last table row.

ulDenominator

[in] Pointer to the denominator of the fraction representing the table position. The ulDenominator parameter cannot be zero.

Return Values

S_OK

The seek operation was successful.

MAPI_E_BUSY

Another operation is in progress that prevents the row seeking operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

Remarks

The cursor position in a table after a call to the IMAPITable::SeekRowApprox method is heuristically the fraction and might not be exact. For example, certain providers might implement a table on top of a binary tree, treating the table’s halfway point as the top of the tree for performance reasons. If the tree is not balanced, then the halfway point used might not be exactly halfway through the table.

Notes to Callers

Call SeekRowApprox to provide the data for a scroll bar implementation. For example, if the user positions the scroll box 2/3 down the scroll bar, you can model that action by calling SeekRowApprox and passing in an equivalent fractional value using ulNumerator and ulDenominator. The SeekRowApprox search is always absolute from the beginning of the table. To move to the end of the table, the values in ulNumerator and ulDenominator must be the same.

Use whatever number scheme is appropriate. That is, to seek to a position halfway through the table, you can specify 1/2, 10/20, or 50/100.


IMAPITable::SetCollapseState

The IMAPITable::SetCollapseState method rebuilds the current expanded or collapsed state of a categorized table using data that was saved by a prior call to the IMAPITable::GetCollapseState method.

Quick Info

See IMAPITable : IUnknown.

HRESULT SetCollapseState(

ULONG ulFlags,
ULONG cbCollapseState,
LPBYTE pbCollapseState,
BOOKMARK FAR * lpbkLocation
)
Parameters

ulFlags

Reserved; must be zero.

cbCollapseState

[in] Count of bytes in the structure pointed to by the pbCollapseState parameter.

pbCollapseState

[in] Pointer to the structures containing the data needed to rebuild the table view.

lpbkLocation

[out] Pointer to a bookmark identifying the row in the table at which the collapsed or expanded state should be rebuilt. This bookmark and the instance key passed in the lpbInstanceKey parameter in the call to IMAPITable::GetCollapseState identify the same row.

Return Values

S_OK

The state of the categorized table was successfully rebuilt.

MAPI_E_BUSY

Another operation is in progress that prevents the operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

MAPI_E_UNABLE_TO_COMPLETE

The table could not finish rebuilding the collapsed or expanded view.

Remarks

The IMAPITable::SetCollapseState method reestablishes the expanded or collapsed state of the table view. SetCollapseState and GetCollapseState work together as follows:

1.	When the state of a categorized table is about to change, IMAPITable::GetCollapseState is called to save all of the data pertaining to the state prior to the change.

2.	To restore the view of the table to its saved state, SetCollapseState is called. The data saved by GetCollapseState is passed to SetCollapseState. SetCollapseState is able to use that data to restore the state.

3.	SetCollapseState returns as an output parameter a bookmark that identifies the same row as the instance key passed as input to GetCollapseState.

For more information about categorized tables, see Sorting and Categorization.

Notes to Implementers

You are responsible for verifying that the sort order and restrictions are exactly the same as they were at the time of the GetCollapseState call. If a change has been made, ideally SetCollapseState should not be called because the results can be unpredictable. This can happen if, for example, a client calls GetCollapseState and then SortTable to change the sort key before calling SetCollapseState. To be safe, check that the saved data is still valid before proceeding with the restoration.

Notes to Callers

To call SetCollapseState, you must have previously called GetCollapseState. The sort order establishing the categories should be the same for both methods. If the sort orders differ, the results of the SetCollapseState operation are unpredictable.

See Also

IMAPITable::CreateBookmark, IMAPITable::FreeBookmark, IMAPITable::GetCollapseState


IMAPITable::SetColumns

The IMAPITable::SetColumns method defines the particular properties and order of properties to appear as columns in the table.

Quick Info

See IMAPITable : IUnknown.

HRESULT SetColumns(

LPSPropTagArray lpPropTagArray,
ULONG ulFlags
)
Parameters

lpPropTagArray

[in] Pointer to an array of property tags identifying properties to be included as columns in the table. The property type portion of each tag can be set to a valid type or to PR_NULL to reserve space for subsequent additions. The lpPropTagArray parameter cannot be set to NULL; every table must have at least one column.

ulFlags

[in] Bitmask of flags that controls the return of an asynchronous call to SetColumns, for example when SetColumns is used in notification. The following flags can be set:

TBL_ASYNC

Requests that the column setting operation be performed asynchronously; causing SetColumns to potentially return before the operation has fully completed.

TBL_BATCH

Permits the table to postpone the column setting operation until the data is actually required.

Return Values

S_OK

The column setting operation was successful.

MAPI_E_BUSY

Another operation is in progress that prevents the column setting operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

Remarks

The column set of a table is the group of properties that make up the columns for the rows in the table. There is a default column set for each type of table. The default column set is made up of the properties that the table implementer automatically includes. Table users can alter this default set by calling the IMAPITable::SetColumns method. They can request that other columns be added to the default set, if the table implementer supports them, that columns be removed, or that the order of columns be changed. SetColumns specifies the columns that are returned with each row and the order of these columns within the row.

The success of the SetColumns operation is apparent only after a subsequent call has been made to retrieve the data of the table. It is then that any errors are reported.

Notes to Implementers

Some providers allow a SetColumns call to order only table columns that are part of the available columns for a table view. Other providers allow a SetColumns call to order all table columns, including those containing properties not in the original column set.

When TBL_BATCH is set for asynchronous operations, providers should return a property type of PT_ERROR and a property value of NULL for columns that are not supported.

You do not need to respond to the TBL_ASYNC flag requesting that the operation be asynchronous. If you do not support asynchronous column set definition, perform the operation synchronously. If you can support the TBL_ASYNC flag and another asynchronous operation is still in progress, return MAPI_E_BUSY. Otherwise, return S_OK regardless of whether or not you support all of the properties included in the property tag array. Errors resulting from unsupported properties should be returned from IMAPITable methods that retrieve data, such as QueryRows.

Do not generate notifications for table rows that are hidden from view by calls to Restrict.

When sending table notifications, the order of the properties in the row member of the TABLE_NOTIFICATION structure and the order specified by the most recent SetColumns call must be the same as of the time that the notification request was sent.

Another flag, TBL_BATCH, allows callers to specify that the table implementer can defer evaluating the results of the operation until a later time. Whenever possible, callers should set this flag because batched operation improves performance.

It is often convenient for callers to reserve some columns in the retrieved row set for values to be added later. Callers do this by placing PR_NULL at the desired positions in the property tag array passed to SetColumns; the table will then pass back PR_NULL at those positions in all rows retrieved with QueryRows.

Notes to Callers

When building the property tag array for the lpPropTagArray parameter, order the tags in the order that you want the columns to appear in the table view.

You can specify multivalued properties to be included in the column set by applying the multivalued instance flag, or MVI_FLAG constant, to the property tag. Set this flag by passing the property tag for the single-valued version of the property as a parameter to the MVI_PROP macro as follows:

MVI_PROP(ulPropTag)

The MVI_PROP macro will set MVI_FLAG for the property, turning the tag into a multivalued tag. If you erroneously try to call MVI_PROP on a single-valued property, MAPI will ignore the call and leave the property tag unchanged.

You can include property tags set to PR_NULL in the property tag array to reserve space in the column set. Reserving space allows you to add to a column set without having to allocate a new property tag array.

When your call to SetColumns causes a change to the order of a table’s columns and one or more of these columns represent a multivalued property, it is possible for the number of rows in the table to increase. If this occurs, all of the bookmarks for the table are discarded. For more information about how multivalued columns affect tables, see Working with Multivalued Columns.

Setting columns is by default a synchronous operation. However, you can allow the table to postpone the operation until such time as the data is needed by setting the TBL_BATCH flag. Setting this flag can improve performance. Another flag, TBL_ASYNC, makes the operation asynchronous, allowing SetColumns to return before the operation is complete. To determine when completion occurs, call IMAPITable::GetStatus.

If a call to SetColumns returns MAPI_E_BUSY, indicating that another operation is preventing your operation from starting, you can call IMAPITable::Abort to stop the operation in progress.

You can also call HrAddColumnsEx to change a column set. The difference between HrAddColumnsEx and IMAPITable::SetColumns is that HrAddColumnsEx is less flexible; it can only add columns. The additional columns are placed at the beginning of the column set; all existing columns appear following these columns.

See Also

HrQueryAllRows, IMAPITable::Abort, IMAPITable::GetRowCount, IMAPITable::QueryColumns, IMAPITable::QueryRows, IMAPITable::Restrict, IMAPITable::SortTable, SPropTagArray, SPropValue, SRowSet, TABLE_NOTIFICATION


IMAPITable::SortTable

The IMAPITable::SortTable method orders the rows of the table based on sort criteria.

Quick Info

See IMAPITable : IUnknown.

HRESULT SortTable(

LPSSortOrderSet lpSortCriteria,
ULONG ulFlags
)
Parameters

lpSortCriteria

[in] Pointer to an SSortOrderSet structure containing the sort criteria to apply. Passing an SSortOrderSet structure containing zero columns indicates that the table does not need to be sorted in any particular order.

ulFlags

[in] Bitmask of flags that controls the timing of the IMAPITable::SortTable operation. The following flags can be set:

TBL_ASYNC

Starts the operation asynchronously and returns before the operation completes.

TBL_BATCH

Defers the completion of the sort until the data in the table is required.

Return Values

S_OK

The sort operation was successful.

MAPI_E_BUSY

Another operation is in progress that prevents the sort operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

MAPI_E_NO_SUPPORT

The table does not support the type of sorting requested.

MAPI_E_TOO_COMPLEX

The table cannot perform the operation because the particular sort criteria pointed to by the lpSortCriteria parameter is too complicated. SortTable can return MAPI_E_TOO_COMPLEX when:

•	A sort operation is requested for a property column that the implementation cannot sort.

•	The implementation does not support the sort order requested in the ulOrder member of the SSortOrderSet structure.

•	The number of columns to be sorted, as specified in the cSorts member in SSortOrderSet, is larger than the implementation can handle.

•	A sort operation is requested, as indicated by a property tag in SSortOrderSet, based on a property that is not in the available or active set and the implementation does not support sorting on properties not in the available set.

•	One property is specified multiple times in a sort order set, as indicated by multiple instances of the same property tag, and the implementation cannot perform such a sort operation.

•	A sort operation based on multivalued property columns is requested using MVI_FLAG and the implementation does not support sorting on multivalued properties.

•	A property tag for a property in SSortOrderSet specifies a property or type that the implementation does not support.

•	A sort operation other than one that proceeds through the table from the PR_RENDERING_POSITION property forward is specified only for an attachment table that supports this type of sorting.

Remarks

The IMAPITable::SortTable method orders the rows in a table view. Whereas some tables support both standard and categorized sorting on a variety of sort key columns, other tables are more limited in their support. Address book providers commonly do not support table sorting. Message store providers commonly support sorting to the extent that they retain the sort order of folders that results when a full table — that is, a table with no restrictions — is sorted.

Some tables allow sorting to be done on any table column. Other tables do not; columns not included in the table view are unaffected by a SortOrder call. Some tables require that sort keys be built only with columns in the table’s current column set.

A table will return either MAPI_E_NO_SUPPORT or MAPI_E_TOO_COMPLEX from SortTable when it cannot complete a sort operation for whatever reason.

When there are zero columns in the SSortOrderSet structure pointed to by the lpSortCriteria parameter, the table returns the current column set. The current sort order can be retrieved by calling the table’s IMAPITable::QuerySortOrder method.

All bookmarks for a table are invalidated and should be deleted when a call to SortTable is made, and the BOOKMARK_CURRENT bookmark, indicating the current cursor position, should be set to the beginning of the table.

If sorting on a column containing a multivalued property without the MVI_FLAG flag set, the column’s values are treated as a totally ordered tuple. A comparison of two multivalued columns compares the column elements in order, reporting the relation of the columns at the first inequality, and returns equality only if the columns compared contain the same values in the same order. If one column has fewer values than the other, the reported relation is that of a null value to the other value.

Notes to Callers

SortTable operates synchronously unless you set one of the flags. If you set the TBL_BATCH flag, SortTable postpones the sort operation unless you request the data. If the TBL_ASYNC flag is set, SortTable operates asynchronously, potentially returning before the completion of the operation.

Call the IMAPITable::Abort method to stop an asynchronous operation in progress if your sort must be done immediately. If SortTable cannot proceed because one or more asynchronous operations on the table are in progress, it returns MAPI_E_BUSY.

For best performance, call SetColumns to customize the table’s column set and Restrict to limit the number of rows in the table before calling SortTable to perform the sort.

Whenever SortTable fails, the sort order that was in effect before the failure is still in effect.

See Also

IMAPITable::Abort, IMAPITable::GetRowCount, IMAPITable::QueryColumns, IMAPITable::QuerySortOrder, IMAPITable::SetColumns, SSortOrderSet


IMAPITable::Unadvise

The IMAPITable::Unadvise method cancels the sending of notifications previously set up with a call to the IMAPITable::Advise method.

Quick Info

See IMAPITable : IUnknown.

HRESULT Unadvise(

ULONG ulConnection
)
Parameters

ulConnection

[in] Number of the registration connection returned by a call to IMAPITable::Advise.

Return Value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Use the IMAPITable::Unadvise method to release the pointer to the advise sink object passed in the lpAdviseSink parameter in the previous call to IMAPITable::Advise, thereby canceling a notification registration. As part of discarding the pointer to the advise sink object, the object’s IUnknown::Release method is called. Generally, Release is called during the Unadvise call, but if another thread is in the process of calling the IMAPIAdviseSink::OnNotify method for the advise sink, the Release call is delayed until the OnNotify method returns.

For more information on the notification process, see Event Notification in MAPI. For specific information about table notification, see About Table Notifications. For information about using the IMAPISupport methods to support notification, see Using A Support Object for Event Notification.

See Also

IMAPIAdviseSink::OnNotify, IMAPITable::Advise


IMAPITable::WaitForCompletion

The IMAPITable::WaitForCompletion method suspends processing until one or more asynchronous operations in progress on the table have completed.

Quick Info

See IMAPITable : IUnknown.

HRESULT WaitForCompletion(

ULONG ulFlags,
ULONG ulTimeout,
ULONG FAR * lpulTableStatus
)
Parameters

ulFlags

Reserved; must be zero.

ulTimeout

[in] Maximum number of milliseconds to wait for the asynchronous operation or operations to complete. To wait indefinitely until completion occurs, set ulTimeout to 0xFFFFFFFF.

lpulTableStatus

[in-out] On input, either a valid pointer or NULL. On output, if lpulTableStatus is a valid pointer, it points to the most recent status of the table. If lpulTableStatus is NULL, no status information is returned. If WaitForCompletion returns a nonzero HRESULT value, the contents of lpulTableStatus are undefined.

Return Values

S_OK

The wait operation was successful.

MAPI_E_NO_SUPPORT

The table does not support waiting for the completion of asynchronous operations.

MAPI_E_TIMEOUT

The asynchronous operation or operations did not complete in the specified time.

Remarks

The IMAPITable::WaitForCompletion method suspends processing until any asynchronous operations currently under way for the table have completed. WaitForCompletion can allow the asynchronous operations either to fully complete or to run for a certain number of milliseconds, as indicated by ulTimeout, before being interrupted. To detect asynchronous operations in progress, call the IMAPITable::GetStatus method.

See Also

IMAPITable::GetRowCount, IMAPITable::GetStatus, IMAPITable::Restrict, IMAPITable::SetColumns, IMAPITable::SortTable


IMAPIViewAdviseSink : IUnknown

The IMAPIViewAdviseSink interface is implemented by form viewers. Its methods are called by a form object to notify a viewer that some event has occurred in the form.

Quick Info

Header file:	MAPIFORM.H
Exposed by:	View advise sink objects
Implemented by:	Form viewers
Called by:	Form objects
Corresponding pointer type:	LPMAPIVIEWADVISESINK
Vtable Order

OnShutdown	Notifies a form viewer that a form is being closed.
OnNewMessage	Notifies a form viewer that either a new or an existing message has been loaded in a form.
OnPrint	Notifies a form viewer of the printing status of a form.
OnSubmitted	Notifies a form viewer that the current message has been submitted to the MAPI spooler.
OnSaved	Notifies a form viewer that the current message in a form has been saved.


IMAPIViewAdviseSink::OnShutdown

The IMAPIViewAdviseSink::OnShutdown method notifies a form viewer that a form is being closed.

Quick Info

See IMAPIViewAdviseSink : IUnknown.

HRESULT OnShutdown()

Parameters

None

Return Values

S_OK

The call succeeded.

Remarks

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.


IMAPIViewAdviseSink::OnNewMessage

The IMAPIViewAdviseSink::OnNewMessage method notifies a form viewer that either a new or an existing message has been loaded in a form.

Quick Info

See IMAPIViewAdviseSink : IUnknown.

HRESULT OnNewMessage()

Parameters

None

Return Values

S_OK

The call succeeded.

Remarks

Form objects call the IMAPIViewAdviseSink::OnNewMessage method whenever a message is loaded in a form using either the IPersistMessage::InitNew or IPersistMessage::Load method. A viewer often releases any IMAPIForm interfaces it has open at this point because the existing form object no longer points to the message the viewer was formerly viewing.

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.

See Also

IMAPIForm : IUnknown, IPersistMessage::InitNew, IPersistMessage::Load


IMAPIViewAdviseSink::OnPrint

The IMAPIViewAdviseSink::OnPrint method notifies a form viewer of the printing status of a form.

Quick Info

See IMAPIViewAdviseSink : IUnknown.

HRESULT OnPrint(

ULONG dwPageNumber,
HRESULT hrStatus
)
Parameters

dwPageNumber

[in] Number of the last page printed.

hrStatus

[in] An HRESULT data type whose value shows the status of the print job. The following values can be used to indicate status:

S_FALSE

The printing job has finished successfully.

S_OK

The printing job is in progress.

FAILED

The printing job was terminated due to a failure.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

Form objects call the IMAPIViewAdviseSink::OnPrint method while printing to inform the current view of printing progress. If the printing job involves multiple pages, OnPrint can be called after each page is printed with the page number for the last page printed in the dwPageNumber parameter and S_OK in the hrStatus parameter to indicate that the printing job is proceeding. When the printing job is complete, OnPrint should be called with the page number of the last page printed in dwPageNumber and S_FALSE in hrStatus.

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.


IMAPIViewAdviseSink::OnSaved

The IMAPIViewAdviseSink::OnSaved method notifies a form viewer that the current message in a form has been saved.

Quick Info

See IMAPIViewAdviseSink : IUnknown.

HRESULT OnSaved()

Parameters

None

Return Value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form objects call the IMAPIViewAdviseSink::OnSaved method after the current message in a form has been successfully saved. Doing so permits viewers to update their windows to reflect changes to the message.

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.


IMAPIViewAdviseSink::OnSubmitted

The IMAPIViewAdviseSink::OnSubmitted method notifies a form viewer that the current message has been submitted to the MAPI spooler.

Quick Info

See IMAPIViewAdviseSink : IUnknown.

HRESULT OnSubmitted()

Parameters

None

Return Value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form objects call the IMAPIViewAdviseSink::OnSubmitted method after a call to the IMAPIMessageSite::SubmitMessage method has returned successfully. After OnSubmitted is called, form viewers can continue on the assumption the message has been updated and can update their windows.

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.

See Also

IMAPIMessageSite::SubmitMessage


IMAPIViewContext : IUnknown

The IMAPIViewContext interface is implemented by form viewers to support form commands that activate the next or previous message, or that print or save the current message.

Quick Info

Header file:	MAPIFORM.H
Exposed by:	View context objects
Implemented by:	Form viewers
Called by:	Form objects
Corresponding pointer type:	LPMAPIVIEWCONTEXT
Vtable Order

SetAdviseSink	Registers a form for notifications about changes to a view’s status.
ActivateNext	Activates the next or previous message in a view.
GetPrintSetup	Retrieves the current print setup so as to print a message.
GetSaveStream	Retrieves a stream in which a version of the current message converted to text format will be placed.
GetViewStatus	Retrieves the current viewer status.


IMAPIViewContext::ActivateNext

The IMAPIViewContext::ActivateNext method activates the next or previous message in a view.

Quick Info

See IMAPIViewContext : IUnknown.

HRESULT ActivateNext(

ULONG ulDir,
LPCRECT prcPosRect
)
Parameters

ulDir

[in] Status value indicating which message to activate. The value can be one of the following flags:

VCDIR_DELETE

Activates the next message because the current message has been deleted.

VCDIR_MOVE

Activates the next message because the current message has been moved.

VCDIR_NEXT

Activates the next message in the view order.

VCDIR_PREV

Activates the previous message in the view order.

prcPosRect

[in] Pointer to a RECT structure containing the size and position of the window used to display the message to activate.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

S_FALSE

The call succeeded but a different type of form was opened; call the IMAPIForm::ShutdownForm method for your form object.

Remarks

Form objects call the IMAPIViewContext::ActivateNext method to change what message is displayed to the user. The value passed in the ulDir parameter informs the form viewer why and how the current message status has been changed. The VCDIR_NEXT and VCDIR_PREVIOUS flags correspond to users choosing the Next and Previous command in a view, respectively. These operations usually correspond to moving up or down one message in the form viewer’s list of messages.

The VCDIR_DELETE and VCDIR_MOVE flags are set by the IMAPIMessageSite::DeleteMessage and IMAPIMessageSite::MoveMessage methods, respectively. Implementations of these methods call ActivateNext with the appropriate direction and then perform the requested operation on the message, if the ActivateNext call did not fail. Form viewers typically enable users to specify the direction to move in the message list.

Upon return from ActivateNext, form objects must check for a current message and go through normal shutdown if a message is not present. If a next or previous message is displayed, the form uses the window rectangle passed in the prcPosRect parameter to display it.

Notes to Implementers

The client application’s implementation of IMAPIViewContext::ActivateNext just needs to make the next or previous message (depending on the ulDir parameter) in the folder the current one. After ActivateNext returns, the form object will call IMAPIMessageSite::GetMessage to get a pointer to the newly activated message.

For more information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.

See Also

IMAPIViewContext::GetViewStatus


IMAPIViewContext::GetPrintSetup

The IMAPIViewContext::GetPrintSetup method retrieves the current print setup so as to print a message.

Quick Info

See IMAPIViewContext : IUnknown.

HRESULT GetPrintSetup(

ULONG ulFlags,
LPFORMPRINTSETUP FAR * lppFormPrintSetup
)
Parameters

ulFlags

[in] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppFormPrintSetup

[out] Pointer to the pointer to the returned FORMPRINTSETUP structure. The FORMPRINTSETUP structure holds information on the print setup.

Return Value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form objects call the IMAPIViewContext::GetPrintSetup method to retrieve the current print setup to print the current message. A form should pass the MAPI_UNICODE flag in the ulFlags parameter if Unicode strings are required for the hDevMode and hDevName members of the FORMPRINTSETUP structure returned in the lppFormPrintSetup parameter. Otherwise, GetPrintSetup returns the contents of these members as ANSI strings.

The returned FORMPRINTSETUP structure must be freed by the calling form using the MAPIFreeBuffer function. The hDevMode and hDevNames members must be allocated using the Win32 function GlobalAlloc and must be freed using the Win32 function GlobalFree.

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.

See Also

FORMPRINTSETUP


IMAPIViewContext::GetSaveStream

The IMAPIViewContext::GetSaveStream method retrieves a stream in which a version of the current message converted to text format will be placed.

Quick Info

See IMAPIViewContext : IUnknown.

HRESULT GetSaveStream(

ULONG FAR * pulFlags,
ULONG FAR * pulFormat,
LPSTREAM FAR * ppstm
)
Parameters

pulFlags

[out] Pointer to a bitmask of flags that controls the type of the saved text. The following flag can be set:

MAPI_UNICODE

The returned text is in Unicode format. If the MAPI_UNICODE flag is not set, the text is in ANSI format.

pulFormat

[out] Pointer to a bitmask of flags that controls additional formatting characteristics. The following flags can be set:

SAVE_FORMAT_RICHTEXT

The message is converted to Rich Text Format.

SAVE_FORMAT_TEXT

The message is converted to plain text format.

ppstm

[out] Pointer to a pointer where the converted version of the message is written.

Return Value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form objects call the IMAPIViewContext::GetSaveStream method to support the Save As verb set for form viewers. A stream interface is returned to the form. Forms are not permitted to write any data before the seek pointer on entry, and they must leave the seek pointer at the end of the converted message when done. The message should be fully converted to text and placed into the stream before returning from the IMAPIForm::DoVerb call.

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.


IMAPIViewContext::GetViewStatus

The IMAPIViewContext::GetViewStatus method retrieves the current viewer status.

Quick Info

See IMAPIViewContext : IUnknown.

HRESULT GetViewStatus(

ULONG FAR * lpulStatus
)
Parameter

lpulStatus

[out] Pointer to a returned bitmask of flags giving information on view status is stored. The following flags can be set:

VCSTATUS_READONLY

The form is to be opened in read-only mode.

VCSTATUS_INTERACTIVE

The form should suppress displaying user interface even in response to a verb that usually causes user interface to be displayed.

VCSTATUS_MODAL

The form is modal to the viewer.

VCSTATUS_NEXT

There is a next form.

VCSTATUS_PREV

There is a previous form.

Return Value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form objects call the IMAPIViewContext::GetViewStatus method to determine whether there are more messages to be activated in a form view in either or both directions — that is, in the direction in which a Next command activates messages, in the direction in which a Previous command activates messages, or in both directions. The value in the lpulStatus parameter is used to determine whether the VCSTATUS_NEXT and VCSTATUS_PREVIOUS flags are valid for IMAPIViewContext::ActivateNext. If the VCSTATUS_DELETE flag is set, but not the VCSTATUS_READONLY flag, then the message can be deleted using the IMAPIMessageSite::DeleteMessage method.

Typically, forms disable menu commands and buttons if not valid for the context. The lpulStatus values are dynamic and can be changed if the view context calls the IMAPIFormAdviseSink::OnChange method.

The VCSTATUS_MODAL flag is set if the form must be modal to the window whose handle is passed in the earlier IMAPIForm::DoVerb call. If VCSTATUS_MODAL is set, the form can use the thread on which the DoVerb call was made until the form closes. If VCSTATUS_MODAL is not set, the form should not be modal to this window and must not use the thread.

For information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.

See Also

IMAPIForm::DoVerb, IMAPIFormAdviseSink::OnChange, IMAPIMessageSite::DeleteMessage, IMAPIMessageSite::GetSiteStatus, IMAPIViewContext::ActivateNext


IMAPIViewContext::SetAdviseSink

The IMAPIViewContext::SetAdviseSink method registers a form for notifications about changes to a view’s status.

Quick Info

See IMAPIViewContext : IUnknown.

HRESULT SetAdviseSink(

LPMAPIFORMADVISESINK pmvns
)
Parameters

pmvns

[in] Pointer to a form advise sink object.

Return Value

S_OK

The call succeeded.

Remarks

Form objects call the IMAPIViewContext::SetNotifySink method to register for notification about changes to which message is next or previous within a particular view context. When called with NULL in the pmvns parameter, SetNotifySink cancels a previous registration for notification.

Notes to Implementers

The client application’s implementation of IMAPIViewContext::SetAdviseSink needs to add the form object’s advise sink to the client application’s advising mechanism. Typically this just means remembering the LPMAPIFORMADVISESINK pointer so that the client application can call the form object’s IMAPIFormAdviseSink:IUnknown methods as appropriate.

For more information about implementing the interfaces related to form servers, see MAPI Form Interfaces Used by Client Applications.


IMessage : IMAPIProp

The IMessage interface is used for managing messages, attachments, and recipients.

Quick Info

Header file:	MAPIDEFS.H
Exposed by:	Message object
Implemented by:	Message store providers
Called by:	Client applications
Corresponding pointer type:	LPMESSAGE
Transaction model:	Transacted
Vtable Order

GetAttachmentTable	Returns the message’s attachment table.
OpenAttach	Opens an attachment.
CreateAttach	Creates a new attachment.
DeleteAttach	Deletes an attachment.
GetRecipientTable	Returns the message’s recipient table.
ModifyRecipients	Adds, deletes, or modifies message recipients.
SubmitMessage	Saves all changes to the message and marks it as ready for sending.
SetReadFlag	Sets or clears the MSGFLAG_READ flag in the PR_MESSAGE_FLAGS property of the message and manages the sending of read reports.
The following properties are required on messages at some point during their lifecycle. Most of the read-only properties are set by the message store provider when a client calls a message’s IMAPIProp::SaveChanges method. Other read-only properties are set by the transport provider.

Required properties for messages of all classes	Access
PR_CREATION_TIME	Read-only
PR_DISPLAY_BCC	Read-only
PR_DISPLAY_CC	Read-only
PR_DISPLAY_TO	Read-only
PR_ENTRYID	Read-only
PR_LAST_MODIFICATION_TIME	Read-only
PR_MESSAGE_ATTACHMENTS	Read-only
PR_MESSAGE_CLASS	Read/write
PR_MESSAGE_FLAGS	Read/write
PR_MESSAGE_RECIPIENTS	Read-only
PR_MESSAGE_SIZE	Read-only
PR_MESSAGE_CC_ME	Read-only
PR_MESSAGE_RECIP_ME	Read-only
PR_MESSAGE_TO_ME	Read-only
PR_NORMALIZED_SUBJECT	Read-only
PR_ORIGINATOR properties	Read-only
PR_PARENT_DISPLAY	Read-only
PR_PARENT_ENTRYID	Read-only
PR_RECEIVED_BY properties	Read-only
PR_RECIPIENT_TYPE	Read-only
PR_RECORD_KEY	Read-only
PR_SEARCH_KEY	Read-only
PR_SENDER properties	Read-only
PR_STORE_ENTRYID	Read-only
PR_STORE_RECORD_KEY	Read-only
The following properties are all read-only to clients, with the exception of PR_BODY. Clients construct this property when they process a report.

Properties for report messages

PR_BODY

PR_CONVERSATION_INDEX

PR_CONVERSATION_TOPIC

PR_MESSAGE_CLASS

PR_MESSAGE_DELIVERY_TIME

PR_ORIGINAL_DELIVERY_TIME

PR_ORIGINAL_DISPLAY_BCC

PR_ORIGINAL_DISPLAY_CC

PR_ORIGINAL_DISPLAY_TO

PR_ORIGINAL_SUBJECT

PR_ORIGINAL_SUBMIT_TIME

PR_REPORT_TAG

PR_REPORT_TEXT

PR_REPORT_TIME

PR_SEARCH_KEY

PR_SENDER properties

PR_SUBJECT

Properties for message recipients	Access	Required or optional
PR_ADDRTYPE	Read-only	Required
PR_DISPLAY_NAME	Read/write	Required
PR_DISPLAY_TYPE	Read/write	Required
PR_EMAIL_ADDRESS	Read-only	Optional
PR_ENTRYID	Read-only	Required
PR_OBJECT_TYPE	Read-only	Required
PR_SEARCH_KEY	Read-only	Optional


IMessage::CreateAttach

The IMessage::CreateAttach method creates a new attachment.

Quick Info

See IMessage : IMAPIProp.

HRESULT CreateAttach(

LPCIID lpInterface,
ULONG ulFlags,
ULONG FAR * lpulAttachmentNum,
LPATTACH FAR * lppAttach
)
Parameters

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the message. Passing NULL results in the message’s standard interface, or IMessage, being returned.

ulFlags

[in] Bitmask of flags that controls how the attachment is created. The following flag can be set:

MAPI_DEFERRED_ERRORS

Allows CreateAttach to return successfully, possibly before the attachment is fully accessible to the calling client. If the attachment is not accessible, making a subsequent call to it can result in an error.

lpulAttachmentNum

[out] Pointer to an index number identifying the newly created attachment. This number is valid only when the message is open and is the basis for the attachment’s PR_ATTACH_NUM property.

lppAttach

[out] Pointer to a pointer to the open attachment object.

Return Value

S_OK

The attachment was successfully created.

Remarks

The IMessage::CreateAttach method creates a new attachment within a message. The new attachment and any properties that are set for it are not available until a client has called the attachment’s IMAPIProp::SaveChanges method and the message’s IMAPIProp::SaveChanges method. Both the attachment and its message have to be saved before the attachment is included in the message’s attachment table.

The attachment number pointed to by lpulAttachmentNum is unique and valid only within the context of the message. That is, two attachments in two different messages can have the same number while two attachments in the same message cannot.


IMessage::DeleteAttach

The IMessage::DeleteAttach method deletes an attachment.

Quick Info

See IMessage : IMAPIProp.

HRESULT DeleteAttach(

ULONG ulAttachmentNum,
ULONG ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
)
Parameters

ulAttachmentNum

[in] Index number of the attachment to delete. This is the value for the attachment’s PR_ATTACH_NUM property.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays. The ulUIParam parameter is ignored unless the ATTACH_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] Pointer to a progress object for displaying a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator using the MAPI progress object implementation. The lpProgress parameter is ignored unless the ATTACH_DIALOG flag is set in ulFlags.

ulFlags

[in] Bitmask of flags that controls the display of a user interface. The following flag can be set:

ATTACH_DIALOG

Requests the display of a progress indicator as the operation proceeds.

Return Value

S_OK

The attachment was successfully deleted.

Remarks

The IMessage::DeleteAttach method deletes an attachment from within a message.

A deleted attachment is not permanently deleted until the message’s IMAPIProp::SaveChanges method has been called.

Notes to Callers

Before calling DeleteAttach, call the IUnknown::Release method for the attachment and each of its streams.

Because deleting an attachment can be a lengthy process, DeleteAttach provides the mechanism for displaying a progress indicator. You can request the display of a progress indicator by passing a pointer to your IMAPIProgress : IUnknown implementation or to take charge of the progress display or NULL if you do not have an implementation. You must also specify a window handle in the ulUIParam parameter and the ATTACH_DIALOG flag in the ulFlags parameter.

See Also

IMAPIProp::SaveChanges


IMessage::GetAttachmentTable

The IMessage::GetAttachmentTable method returns the message’s attachment table.

Quick Info

See IMessage : IMAPIProp.

HRESULT GetAttachmentTable(

ULONG ulFlags,
LPMAPITABLE FAR * lppTable
)
Parameters

ulFlags

[in] Bitmask of flags that relate to the creation of the table. The following flag can be set:

MAPI_UNICODE

The string columns are in Unicode format. If the MAPI_UNICODE flag is not set, the string columns are in ANSI format.

MAPI_DEFERRED_ERRORS

Allows GetAttachmentTable to return successfully, possibly before the table is fully accessible to the calling client. If the table is not accessible, making a subsequent call to it can result in an error.

lppTable

[out] Pointer to a pointer to the attachment table.

Return Values

S_OK

The attachment table was successfully retrieved.

Remarks

The IMessage::GetAttachmentTable method returns a pointer to the message’s attachment table, which includes information about all of the attachments in the message. Clients can get access to an attachment only through the attachment table. By retrieving an attachment’s number — its PR_ATTACH_NUM property — a client can use several of the IMessage methods to work with the attachment.

There is one row for each attachment. For a complete list of the columns in an attachment table, see Attachment Tables.

An attachment usually does not appear in the attachment table until both the attachment and the message have been saved with a call to IMAPIProp::SaveChanges. Attachment tables are dynamic. If a client creates a new attachment, deletes an existing attachment, or changes one or more properties once the SaveChanges calls have been made on the attachment on the message, the attachment table will be updated to reflect the new information.

Some attachment tables support a wide variety of restrictions; others do not. Support for restrictions depends on the message store provider’s implementation.

When initially opened, attachment tables are not necessarily sorted in any particular order.

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the following calls to the attachment table:

•	IMAPITable::QueryColumns to retrieve the column set.

•	IMAPITable::QueryRows to retrieve rows.

•	IMAPITable::QuerySortOrder to retrieve the sort order.

Setting the Unicode flag requests that the information for any string columns returned from these calls be in Unicode format. However, because not all message store providers support Unicode, setting this flag is only a request.

See Also

IMessage::CreateAttach, IMessage::DeleteAttach, IMessage::OpenAttach


IMessage::GetRecipientTable

The IMessage::GetRecipientTable method returns the message’s recipient table.

Quick Info

See IMessage : IMAPIProp.

HRESULT GetRecipientTable(

ULONG ulFlags,
LPMAPITABLE FAR * lppTable
)
Parameters

ulFlags

[in] Bitmask of flags that controls the return of the table. The following flags can be set:

MAPI_DEFERRED_ERRORS

Allows GetRecipientTable to return successfully, possibly before the table is fully accessible to the calling client. If the table is not accessible, making a subsequent call to it can result in an error.

MAPI_UNICODE

The string columns should be in Unicode format. If the MAPI_UNICODE flag is not set, the string columns should be in ANSI format.

lppTable

[out] Pointer to a pointer to the recipient table.

Return Value

S_OK

The recipient table was returned successfully.

Remarks

The IMessage::GetAttachmentTable method returns a pointer to the message’s recipient table, which includes information about all of the recipients for the message. There is one for every recipient.

Recipient tables have a different column set depending on whether the message has been submitted. For a complete list of the columns in a recipient table, see Recipient Tables.

Some recipient tables support a wide variety of restrictions; others do not. Support for restrictions depends on the message store provider’s implementation.

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the following calls to the recipient table:

•	IMAPITable::QueryColumns to retrieve the column set.

•	IMAPITable::QueryRows to retrieve rows.

•	IMAPITable::QuerySortOrder to retrieve the sort order.

Setting the Unicode flag requests that the information for any string columns returned from these calls be in Unicode format. However, because not all message store providers support Unicode, setting this flag is only a request.

Notes to Callers

You can change a recipient table while it is open by calling the IMessage::ModifyRecipients method. ModifyRecipients adds recipients, deletes recipients, or modifies recipient properties.

See Also

IMAPIProp::SaveChanges, IMAPITable::QueryRows, IMessage::ModifyRecipients


IMessage::ModifyRecipients

The IMessage::ModifyRecipients method adds, deletes, or modifies message recipients.

Quick Info

See IMessage : IMAPIProp.

HRESULT ModifyRecipients(

ULONG ulFlags,
LPADRLIST lpMods
)
Parameters

ulFlags

[in] Bitmask of flags that controls the recipient changes. If zero is passed for the ulFlags parameter, ModifyRecipients replaces all existing recipients with the recipient list pointed to by the lpMods parameter. The following flags can be set for ulFlags:

MODRECIP_ADD

The recipients pointed to by the lpMods parameter should be added to the recipient list.

MODRECIP_MODIFY

The recipients pointed to by the lpMods parameter should replace existing recipients. All of the existing properties are replaced by those in the corresponding ADRENTRY structure.

MODRECIP_REMOVE

Existing recipients should be removed from the recipient list using as an index the PR_ROWID property included in the property value array of each recipient entry in the lpMods parameter.

lpMods

[in] Pointer to an ADRLIST structure containing a list of recipients to be added, deleted, or modified in the message.

Return Value

S_OK

The recipient list was successfully modified.

Remarks

The IMessage::ModifyRecipients method changes the message’s recipient list. It is from this list, held in an ADRLIST structure, that the recipient table is built.

The ADRLIST structure contains one ADRENTRY structure for each recipient and each ADRENTRY structure contains an array of property values describing the recipient properties.

Recipients in the ADRLIST structure can be resolved or unresolved. The difference is in the number and type of properties that are included. An unresolved recipient contains only the PR_DISPLAY_NAME and PR_RECIPIENT_TYPE properties while a resolved recipient contains those two properties plus PR_ADDRTYPE and PR_ENTRYID. If PR_EMAIL_ADDRESS is available, it can be included also.

By the time a message is submitted, it must include only resolved recipients in its recipient list. Unresolved recipients cause nondelivery reports to be created and sent to the original sender of the message. For more information about the name resolution process from the client perspective, see Resolving a Name. For more information from the perspective of the address book provider, see Implementing Name Resolution.

In addition to resolved and unresolved recipients, a recipient can be NULL. That is, the cValues member of the ADRENTRY structure for the recipient is set to zero and the rgPropVals member is set to NULL.

Notes to Callers

You can create a recipient list by calling IAddrBook::Address to display the common dialog box and prompt the user to select entries. The address list pointed to by the lppAdrList parameter to Address can be passed to ModifyRecipients as the lpMods parameter.

When you specify properties for a recipient in the ADRLIST structure, include all of the recipient’s properties, not only the new or changed ones. When a recipient is modified, any properties not included in the ADRLIST structure are deleted. To retrieve the current set of properties for all of a message’s recipients, call GetRecipientTable and retrieve all of the rows. Because an SRowSet is identical in structure to an ADRLIST, you can use them interchangeably.

ModifyRecipients replaces all of the entries in the current recipient list with the information pointed to by lpMods when none of the flags are set in the ulFlags parameter.

Notes to Callers

When you set the MODRECIP_MODIFY flag, ModifyRecipients replaces each entire recipient row with the associated row in the ADRLIST structure passed in lpMods. Be careful to specify all of the properties that a recipient should have regardless of whether they have changed to prevent them from being unintentionally deleted.

Following are some rules for setting the properties of the recipients in the ADRLIST structure:

•	Do not use PT_NULL as a property type. ModifyRecipients returns an error when encountering this value.

•	Do not use PT_ERROR as a property type. ModifyRecipients ignores this value.

•	Include the PR_ROWID property for all recipients when you set either the MODRECIP_REMOVE or MODRECIP_MODIFY flag in ulFlags.

•	Do not include the PR_ROWID property for any of the recipients when you set the MODRECIP_ADD flag in ulFlags or when you pass zero in ulFlags.

If you include either the PR_ADDRTYPE property or PR_EMAIL_ADDRESS property for a recipient and one or both of these properties are inconsistent with the address type and address of the recipient as identified by PR_ENTRYID, the results are undefined. That is, there are three possibilities, depending on the service provider:

•	The message will be delivered to the address described by the PR_ADDRTYPE and PR_EMAIL_ADDRESS properties.

•	The message will be delivered to the recipient identified by PR_ENTRYID.

•	The message will be declared undeliverable due to the ambiguity of the address information.

Use the allocation rules outlined in Managing Memory for ADRLIST and SRowSet Structures to allocate memory for the recipient list. ModifyRecipients does not free the ADRLIST structure nor any of its substructures. The ADRLIST structure and each SPropValue structure must be separately allocated by using the MAPIAllocateBuffer function such that each can be freed individually. If the method requires additional space for any SPropValue structure, it can replace the SPropValue structure with a new one that can later be freed using MAPIFreeBuffer. The original SPropValue structure should also be freed using MAPIFreeBuffer.

See Also

ADRENTRY, ADRLIST, IAddrBook::Address, IMAPISupport::Address, MAPIAllocateBuffer, MAPIFreeBuffer, SPropValue


IMessage::OpenAttach

The IMessage::OpenAttach method opens an attachment.

Quick Info

See IMessage : IMAPIProp.

HRESULT OpenAttach(

ULONG ulAttachmentNum,
LPCIID lpInterface,
ULONG ulFlags,
LPATTACH FAR * lppAttach
)
Parameters

ulAttachmentNum

[in] Index number of the attachment to open, as stored in the attachment’s PR_ATTACH_NUM property. This index number uniquely identifies the attachment in the message and is valid only in the context of the message.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the attachment. Passing NULL results in the attachment’s standard interface, or IAttach, being returned.

ulFlags

[in] Bitmask of flags that controls how the attachment is opened. The following flags can be set:

MAPI_BEST_ACCESS

Requests that the attachment be opened with the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write access, the attachment should be opened with read/write access; if the client has read-only access, the attachment should be opened with read-only access.

MAPI_DEFERRED_ERRORS

Allows OpenAttach to return successfully, possibly before the attachment is fully accessible to the calling client. If the attachment is not accessible, making a subsequent call to it can result in an error.

MAPI_MODIFY

Requests read/write access. By default, attachments are opened with read-only access, and clients should not work on the assumption that read/write access has been granted.

lppAttach

[out] Pointer to a pointer to the open attachment.

Return Value

S_OK

The attachment was successfully opened.

Remarks

The IMessage::OpenAttach method opens a message’s attachment.

Notes to Callers

To open an attachment, you must have access to its attachment number — or PR_ATTACH_NUM property. Call IMessage::GetAttachmentTable to retrieve the message’s attachment table and locate the row that represents the attachment to be opened. See Opening an Attachment for more information.

Do not try to open one attachment multiple times; the results are undefined and dependent on the message store provider.

You can request that the attachment be opened in read/write mode, rather than the default read-only mode. However, whether or not the attachment will actually be opened in read/write mode is up to the message store provider. You can either attempt to modify the attachment, preparing to handle possible failure, or check the level of access that was granted by retrieving the attachment’s PR_ACCESS_LEVEL property, if it is available.


IMessage::SetReadFlag

The IMessage::SetReadFlag method sets or clears the MSGFLAG_READ flag in the PR_MESSAGE_FLAGS property of the message and manages the sending of read reports.

Quick Info

See IMessage : IMAPIProp.

HRESULT SetReadFlag(

ULONG ulFlags
)
Parameters

ulFlags

[in] Bitmask of flags that controls the setting of a message’s read flag — that is, the message’s MSGFLAG_READ flag in its PR_MESSAGE_FLAGS property — and the processing of read reports. The following flags can be set:

CLEAR_READ_FLAG

The MSGFLAG_READ flag should be cleared in PR_MESSAGE_FLAGS and no read report should be sent.

CLEAR_NRN_PENDING

The MSGFLAG_NRN_PENDING flag should be cleared in PR_MESSAGE_FLAGS and a nonread report should not be sent.

CLEAR_RN_PENDING

The MSGFLAG_RN_PENDING flag should be cleared in PR_MESSAGE_FLAGS and no read report should be sent.

GENERATE_RECEIPT_ONLY

A read report should be sent if one is pending, but there should be no change in the state of the MSGFLAG_READ flag.

MAPI_DEFERRED_ERRORS

Allows SetReadFlag to return successfully, possibly before the operation has completed.

SUPPRESS_RECEIPT

A pending read report should be canceled if a read report had been requested and this call changes the state of the message from unread to read. If this call does not change the state of the message, the message store provider can ignore this flag.

Return Values

S_OK

The message’s read flag has been successfully set or cleared.

MAPI_E_NO_SUPPRESS

The message store provider does not support the suppression of read reports.

MAPI_E_INVALID_PARAMETER

One of the following combinations of flags is set in the ulFlags parameter:

•	SUPPRESS_RECEIPT | CLEAR_READ_FLAG

•	SUPPRESS_RECEIPT | CLEAR_READ_FLAG | GENERATE_RECEIPT_ONLY

•	CLEAR_READ_FLAG | GENERATE_RECEIPT_ONLY

Remarks

The IMessage::SetReadFlag method sets or clears the message’s MSGFLAG_READ flag in the PR_MESSAGE_FLAGS property and calls IMAPIProp::SaveChanges to save the message. Setting the MSGFLAG_READ flag marks a message as having been read, which does not necessarily indicate that the intended recipient has actually read the message.

SetReadFlags also manages the sending of read reports. A read report is sent only if the sender has requested one.

The read flag cannot be altered for:

•	Messages that do not exist.

•	Messages that have been moved elsewhere.

•	Messages that are open with read/write access.

•	Messages that are currently submitted.

Notes to Implementers

If none of the flags are set in the ulFlags parameter, the following rules apply:

•	If MSGFLAG_READ is already set, do nothing.

•	If MSGFLAG_READ is not set, set it immediately and send any pending read reports if the PR_READ_RECEIPT_REQUESTED property is set.

If both the SUPPRESS_RECEIPT and GENERATE_RECEIPT_ONLY flags are set, the PR_READ_RECEIPT_REQUESTED bit, if set, should be cleared and a read report should not be sent.

When the SUPPRESS_RECEIPT flag is set:

•	If MSGFLAG_READ is already set, do nothing.

•	If MSGFLAG_READ is not set, set it and cancel any pending read reports.

When the CLEAR_READ_FLAG flag is set, clear the MSGFLAG_READ flag in each message’s PR_MESSAGE_FLAGS property and do not send any read reports.

When the GENERATE_RECEIPT_ONLY flag is set, send any pending read reports. Do not set or clear MSGFLAG_READ.

When both the SUPPRESS_RECEIPT and GENERATE_RECEIPT_ONLY flags are set, set the PR_READ_RECEIPT_REQUESTED property to FALSE if it is set and do not send a read report.

You can optimize report behavior by suppressing the generation of read reports under certain conditions. However, if you do not support the suppression of reports and a client calls SetReadFlag with the SUPPRESS_RECEIPT flag set, return MAPI_E_NO_SUPPRESS.

See Also

IMAPIContainer::OpenEntry, IMAPIFolder::SetReadFlags, IMAPIProp::GetProps, IMAPIProp::SaveChanges, PR_MESSAGE_FLAGS


IMessage::SubmitMessage

The IMessage::SubmitMessage method saves all of the message’s properties and marks the message as ready to be sent.

Quick Info

See IMessage : IMAPIProp.

HRESULT SubmitMessage(

ULONG ulFlags
)
Parameters

ulFlags

[in] Bitmask of flags used to control how a message is submitted. The following flag can be set:

FORCE_SUBMIT

MAPI should submit the message immediately. This flag is not currently in use.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_RECIPIENTS

The message’s recipient table is empty.

Remarks

The IMessage::SubmitMessage method marks a message as ready to be transmitted. MAPI passes messages to the underlying messaging system in the order in which they are marked for sending. Because of this functionality, a message might stay in a message store for some time before the underlying messaging system can take responsibility for it. The order of receipt at the destination is in the underlying messaging system’s control and does not necessarily match the order in which messages were sent.

Notes to Implementers

Call the message’s IMAPIProp::SaveChanges method to save it and then check the message’s PR_MESSAGE_FLAGS property. If the MSGFLAG_RESEND flag is set, call IMAPISupport::PrepareSubmit. PrepareSubmit updates the recipient type and PR_RESPONSIBILITY property for all of the recipients in the resend message.

Notes to Callers

When SubmitMessage returns, all pointers to the message and its associated subobjects — messages, folders, attachments, streams, tables, and so on — are no longer valid. MAPI does not permit any further operations on these pointers, except for calling their IUnknown::Release methods. MAPI is designed such that after SubmitMessage is called, you should release the message and all associated subobjects. However, if SubmitMessage returns an error value indicating missing or invalid information, the message remains open and the pointers remain valid.

To cancel a send operation, get and store a pointer to the message’s PR_ENTRYID property before the message is submitted. Because a message’s entry identifier is invalidated after the message has been submitted, it is necessary to save it before calling SubmitMessage. To cancel the send, point the lpEntryId parameter to this entry identifier and call IMsgStore::AbortSubmit.

See Also

IMsgStore::AbortSubmit


IMsgServiceAdmin : IUnknown

The IMsgServiceAdmin interface is used to make changes to a message service within a profile.

Quick Info

Header file:	MAPIX.H
Exposed by:	Message service administration objects
Implemented by:	MAPI
Called by:	Client applications
Corresponding pointer type:	LPSERVICEADMIN
Vtable Order

GetLastError	Returns a MAPIERROR structure containing information about the last error that occurred for a message service administration object.
GetMsgServiceTable	Provides access to the message service’s provider table, a listing of the message services in the profile.
CreateMsgService	Adds a message service to the current profile.
DeleteMsgService	Deletes a message service from a profile.
CopyMsgService	Copies a message service into a profile.
RenameMsgService	Assigns a new name to a message service.
ConfigureMsgService	Enables a user to reconfigure a message service using the service’s configuration property sheet.
OpenProfileSection	Opens a section of the current profile and returns an IProfSect pointer for further access
MsgServiceTransportOrder	Sets the order in which transport providers are called to deliver a message.
AdminProviders	Returns a pointer providing access to a provider administration object.
SetPrimaryIdentity	Designates a message service to be the supplier of the primary identifier for the profile.
GetProviderTable	Provides access to the provider table, a listing of the service providers in the profile.
Remarks

An implementation can get a pointer to an IMsgServiceAdmin interface in two ways: by calling the IMAPISession::AdminServices method or by calling the IProfAdmin::AdminServices method. For clients primarily concerned with profile configuration — for example, control panels — IProfAdmin::AdminServices is the preferred way to get the IMsgServiceAdmin interface because it does not log providers on to the MAPI session. If a client requires the ability to make changes to the active profile, then IMAPISession::AdminServices should be called to get the IMsgServiceAdmin pointer. Clients that are modifying the profile that is active for the session should be designed with the awareness that although MAPI does not allow a profile that is in use to be deleted, there are no safeguards to prevent a client from removing all the message services within the profile.


IMsgServiceAdmin::AdminProviders

The IMsgServiceAdmin::AdminProviders method returns a pointer providing access to a provider administration object.

Quick Info

See IMsgServiceAdmin : IUnknown.

HRESULT AdminProviders(

LPMAPIUID lpUID,
ULONG ulFlags,
LPPROVIDERADMIN FAR * lppProviderAdmin
)
Parameters

lpUID

[in] Pointer to the MAPIUID structure holding the unique identifier for the message service to be administered.

ulFlags

[in] Bitmask of flags that controls the type of the passed-in string. The following flag can be set:

MAPI_UNICODE

The passed-in string is in Unicode format. If the MAPI_UNICODE flag is not set, the string is in ANSI format.

lppProviderAdmin

[out] Pointer to a pointer to a provider administration object.

Return Values

S_OK

The provider administration object was successfully returned.

MAPI_E_NOT_FOUND

The MAPIUID pointed to by lpUID does not exist.

Remarks

The IMsgServiceAdmin::AdminProviders method provides access to a provider administration object. A provider administration object — an object that supports the IProviderAdmin interface — allows clients to add service providers to a message service, delete service providers from a message service, open profile sections, and access the message service provider table.

The types of changes that can actually be made to a message service while the profile is in use depend on the message service. However, most message services do not support changes such as adding and deleting providers while the profile is in use.

Notes to Callers

To retrieve the MAPIUID for the message service to administer, retrieve the PR_SERVICE_UID column from the message service’s row in the message service table. See the procedure outlined in IMsgServiceAdmin::CreateMsgService for more information.

See Also

IProviderAdmin : IUnknown, MAPIUID


IMsgServiceAdmin::ConfigureMsgService

The IMsgServiceAdmin::ConfigureMsgService method reconfigures a message service.

Quick Info

See IMsgServiceAdmin : IUnknown.

HRESULT ConfigureMsgService(

LPMAPIUID lpUID,
ULONG ulUIParam,
ULONG ulFlags,
ULONG cValues,
LPSPropValue lpProps
)
Parameters

lpUID

[in] Pointer to the MAPIUID structure holding the unique identifier for the message service to configure.

ulUIParam

[in] Handle of the parent window for the configuration property sheet.

ulFlags

[in] Bitmask of flags that controls the display of the property sheet. The following flags can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

MSG_SERVICE_UI_READ_ONLY

The message service should display its configuration property sheet but not enable the user to change it. Most message services ignore this flag.

SERVICE_UI_ALLOWED

The message service should display its configuration property sheet only if the service is not completely configured.

SERVICE_UI_ALWAYS

The message service must always display its configuration property sheet. If SERVICE_UI_ALWAYS is not set, a configuration property sheet can still be displayed if SERVICE_UI_ALLOWED is set and valid configuration information is not available from the property value array in the lpProps parameter. Either SERVICE_UI_ALLOWED or SERVICE_UI_ALWAYS must be set for a property sheet to be displayed.

cValues

[in] Count of property values in the SPropValue structure pointed to by lpProps.

lpProps

[in] Pointer to an array of property values describing the properties to display in the property sheet. The lpProps parameter should be NULL if the message service is being configured without displaying a property sheet.

Return Values

S_OK

The message service was successfully configured.

MAPI_E_EXTENDED_ERROR

An error specific to a message service. To get the MAPIERROR structure describing the error, the client application should call the IMsgServiceAdmin::GetLastError method.

MAPI_E_NOT_FOUND

The MAPIUID pointed to by lpUID does not match that of an existing message service.

MAPI_E_NOT_INITIALIZED

The message service does not have an entry point function.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in the property sheet.

Remarks

The IMsgServiceAdmin::ConfigureMsgService method allows a message service to be configured, with or without a configuration property sheet.

To allow configuration without a property sheet display, message services typically prepare a header file that includes constants for all the required and optional properties and their values.

Notes to Callers

To retrieve the MAPIUID for the message service to configure, retrieve the PR_SERVICE_UID column from the message service’s row in the message service table. See the procedure outlined in IMsgServiceAdmin::CreateMsgService for more information.

You can configure a message service without displaying a property sheet to a user only if you have advance information about the property values to be set. If you are configuring a message service without displaying a property sheet, do not set the MSG_SERVICE_UI_READ_ONLY, SERVICE_UI_ALLOWED, or SERVICE_UI_ALWAYS flags.

If you receive all or some of the configuration information from the user via a property sheet, set SERVICE_UI_ALLOWED in ulFlags. If you use existing property information only to establish default settings and the user is able to change the settings, set SERVICE_UI_ALWAYS in ulFlags.

See Also

MAPIUID, SPropValue


IMsgServiceAdmin::CopyMsgService

The IMsgServiceAdmin::CopyMsgService method copies a message service into a profile.

Quick Info

See IMsgServiceAdmin : IUnknown.

HRESULT CopyMsgService(

LPMAPIUID lpUID,
LPTSTR lpszDisplayName,
LPCIID lpInterfaceToCopy,
LPCIID lpInterfaceDst,
LPVOID lpObjectDst,
ULONG ulUIParam,
ULONG ulFlags
)
Parameters

lpUID

[in] Pointer to the MAPIUID structure holding the unique identifier of the message service to copy.

lpszDisplayName

[in] Pointer to the display name of the message service to copy.

lpInterfaceToCopy

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the profile section of the message service to copy. Passing NULL results in the standard profile section interface, IProfSect, being used.

lpInterfaceDst

[in] Pointer to the IID representing the interface to be used to access the object pointed to by the lpObjectDst parameter. Passing NULL results in  the session interface, IMAPISession, being used. The lpInterfaceDst parameter can also be set to IID_IMsgServiceAdmin.

lpObjectDst

[in] Pointer to a pointer to a session or message service administration object. The type of object should correspond to the interface identifier passed in lpInterfaceDst. Valid object pointers are LPMAPISESSION and LPSERVICEADMIN.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays.

ulFlags

[in] Bitmask of flags that controls how the message service is copied. The following flags can be set:

MAPI_UNICODE

The display name of the message service is in the Unicode format. If the MAPI_UNICODE flag is not set, the display name is in the ANSI format.

SERVICE_UI_ALWAYS

Requests that that message service always display a configuration property sheet.

Return Values

S_OK

The message service was successfully copied.

MAPI_E_NO_ACCESS

The message service is already in the profile and does not allow multiple instances of itself.

MAPI_E_NOT_FOUND

The MAPIUID pointed to by lpUID does not refer to an existing message service.

Remarks

The IMsgServiceAdmin::CopyMsgService method copies a message service into a profile, either the active profile or another profile. The profile containing the message service to be copied and the destination do not have to be the same profile, but they can be.

The message service’s entry point function is not called for a copy operation. The copied message service has the same configuration settings as its original. To change these settings, a client should call the IMsgServiceAdmin::ConfigureMsgService method.

See Also

IMsgServiceAdmin::ConfigureMsgService, MAPIUID


IMsgServiceAdmin::CreateMsgService

The IMsgServiceAdmin::CreateMsgService method adds a message service to the current profile.

Quick Info

See IMsgServiceAdmin : IUnknown.

HRESULT CreateMsgService(

LPTSTR lpszService,
LPTSTR lpszDisplayName,
ULONG ulUIParam,
ULONG ulFlags
)
Parameters

lpszService

[in] Pointer to the name of the message service to add. This message service name must appear in the [Services] section of MAPISVC.INF.

lpszDisplayName

[in] Pointer to the display name of the message service to add. The lpszDisplayName parameter is ignored if the message service has set PR_DISPLAY_NAME  in the MAPISVC.INF file.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays.

ulFlags

[in] Bitmask of flags that controls how the message service is installed. The following flags can be set:

MAPI_UNICODE

The names are in Unicode format. If the MAPI_UNICODE flag is not set, the names are in ANSI format.

SERVICE_UI_ALLOWED

Allows the display of the message service’s configuration property sheet only if the service is not completely configured.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NOT_FOUND

The message service name is not in the [Services] section of MAPISVC.INF.

Remarks

The IMsgServiceAdmin::CreateMsgService method adds a message service to the current profile. CreateMsgService calls the message service’s entry point function to perform any service-specific configuration tasks. If the SERVICE_UI_ALLOWED flag is set in the ulFlags parameter, the message service being installed can display a property sheet to enable the user to configure its settings.

The list of providers that make up a message service and the properties for each are contained within the MAPISVC.INF file. CreateMsgService first creates a new profile section for the message service and then copies all of the information for that service from the MAPISVC.INF file into the profile, creating new sections for each provider.

After all the information has been copied from MAPISVC.INF, the message service’s entry point function is called with the MSG_SERVICE_CREATE value set in the ulContext parameter. If the SERVICE_UI_ALLOWED flag is set in the CreateMsgService method’s ulFlags parameter, then the values in the CreateMsgService ulUIParam and ulFlags parameters are also passed when the message service’s entry point function is called. Service providers should display their configuration property sheets so users can configure the message service.

Notes to Callers

CreateMsgService does not return the MAPIUID for the message service added to the profile.

To retrieve the MAPIUID for the created message service

1.	Call IMsgServiceAdmin::GetMsgServiceTable to get the message service administration table.

2.	Locate the row that represents the message service by placing a restriction on the table that matches the PR_SERVICE_NAME property with the name of the message service.

3.	Retrieve the service’s PR_SERVICE_UID property.

4.	Pass the value of the PR_SERVICE_UID property in the lpUid parameter to IMsgServiceAdmin::ConfigureMsgService method to configure the service.


IMsgServiceAdmin::DeleteMsgService

The IMsgServiceAdmin::DeleteMsgService method deletes a message service from a profile.

Quick Info

See IMsgServiceAdmin : IUnknown.

HRESULT DeleteMsgService(

LPMAPIUID lpuid
)
Parameters

lpuid

[in] Pointer to the MAPIUID structure holding the unique identifier for the message service to delete.

Return Values

S_OK

The message service was deleted.

MAPI_E_NOT_FOUND

The MAPIUID pointed to by lpuid does not match an existing message service.

Remarks

The IMsgServiceAdmin::DeleteMsgService method deletes a message service from a profile. DeleteMsgService removes all profile sections related to the message service.

DeleteMsgService performs the following steps to delete the message service:

1.	Calls the message service’s entry point function with the ulContext parameter set to MSG_SERVICE_DELETE before the profile sections are removed. This allows the service to perform any service-specific tasks.

2.	Deletes the message service.

3.	Deletes the message service’s profile section.

The message service’s entry point function is not called again after the service has been deleted.

Notes to Callers

To retrieve the MAPIUID for the message service to delete, retrieve the PR_SERVICE_UID column from the message service’s row in the message service table. See the procedure outlined in IMsgServiceAdmin::CreateMsgService for more information.

See Also

MAPIUID


IMsgServiceAdmin::GetLastError

The IMsgServiceAdmin::GetLastError method returns a MAPIERROR structure containing information about the last error that occurred for a message service administration object.

Quick Info

See IMsgServiceAdmin : IUnknown.

HRESULT GetLastError(

HRESULT hResult,
ULONG ulFlags,
LPMAPIERROR FAR * lppMAPIError
)
Parameters

hResult

[in] HRESULT data type containing the error value generated by the previous method call.

ulFlags

[in] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] Pointer to a pointer to the returned MAPIERROR structure containing version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

The MAPI_UNICODE flag was set and the message service administration object does not support Unicode.

Remarks

The IMsgServiceAdmin::GetLastError method retrieves information about the last error that was returned by an IMsgServiceAdmin method call. Clients can provide their users with detailed information about the error by including this information in a dialog box.

Notes to Callers

You can make use of the MAPIERROR structure pointed to by the lppMAPIError parameter, if MAPI supplies one, only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was or has nothing more to report about the error. In this situation, GetLastError returns a pointer to NULL in lppMAPIError instead.

For more information about the GetLastError method, see Using Extended Errors.

See Also

MAPIERROR, MAPIFreeBuffer


IMsgServiceAdmin::GetMsgServiceTable

The IMsgServiceAdmin::GetMsgServiceTable method provides access to the message service table, a listing of the message services in the profile.

Quick Info

See IMsgServiceAdmin : IUnknown.

HRESULT GetMsgServiceTable(

ULONG ulFlags,
LPMAPITABLE FAR * lppTable
)
Parameters

ulFlags

[in] Bitmask of flags that controls the type of the string columns in the table. The following flag can be set:

MAPI_UNICODE

The string columns are in Unicode format. If the MAPI_UNICODE flag is not set, the string columns are in ANSI format.

lppTable

[out] Pointer to a pointer to the message service table.

Return Value

S_OK

The message service table was successfully returned.

Remarks

The IMsgServiceAdmin::GetMsgServiceTable method provides access to the message service table, a table maintained by MAPI that lists the message services currently installed in the session profile.

For a complete list of columns in the message service table, see Message Service Table.

The message service table is static. After a client has been given access to it, subsequent message service additions or deletions will not affect it.

If there are no message services in the current profile, GetMsgServiceTable returns a table with zero rows.

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the format of the columns returned from the following IMAPITable methods:

•	IMAPITable::QueryColumns

•	IMAPITable::QueryRows

This flag also controls the property types in the sort order returned by the IMAPITable::QuerySortOrder method.

See Also

IMsgServiceAdmin::ConfigureMsgService, IMsgServiceAdmin::DeleteMsgService


IMsgServiceAdmin::GetProviderTable

The IMsgServiceAdmin::GetProviderTable method provides access to the provider table, a listing of the service providers in the profile.

Quick Info

See IMsgServiceAdmin : IUnknown.

HRESULT GetProviderTable(

ULONG ulFlags,
LPMAPITABLE FAR * lppTable
)
Parameters

ulFlags

[in] Bitmask of flags that controls the type of the string columns returned in the table. The following flag can be set:

MAPI_UNICODE

The string columns are in Unicode format. If the MAPI_UNICODE flag is not set, the string columns are in ANSI format.

lppTable

[out] Pointer to a pointer to the provider table.

Return Value

S_OK

The provider table was successfully returned.

Remarks

The IMsgServiceAdmin::GetProviderTable method provides access to MAPI’s provider table, a table that lists all of the address book, message store, transport, and message hook providers currently installed in the profile.

Unlike the provider table returned through IProviderAdmin::GetProviderTable, the provider table returned through IMsgServiceAdmin::GetProviderTable cannot include additional rows that represent information associated with one or more service providers in the profile.

Providers that have been deleted, or are in use but have been marked for deletion, are not included in the provider table. Provider tables are static, meaning that subsequent additions to or deletions from the profile are not reflected in the table.

If the profile has no providers, GetProviderTable returns a table with zero rows and the S_OK return value.

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the format of the columns returned from the following IMAPITable methods:

•	IMAPITable::QueryColumns

•	IMAPITable::QueryRows

This flag also controls the property types in the sort order returned by the IMAPITable::QuerySortOrder method.

For a complete list of the columns in the provider table, see Provider Table.

Notes to Callers

To retrieve the rows of a provider table in transport order

1.	Call IMAPITable::Restrict to impose a property restriction that matches the PR_RESOURCE_TYPE property with MAPI_TRANSPORT_PROVIDER.

2.	Call IMAPITable::SortTable to sort the table by the PR_PROVIDER_ORDINAL column.

3.	Call IMAPITable::QueryRows to get the rows of the table.

An alternative to these calls is to make a single call to the HrQueryAllRows function with all of the appropriate data structures passed in.

If you retrieve the PR_SERVICE_UID columns in each of the rows, you can use this array of MAPIUID structures to set the transport order in a call to IMsgServiceAdmin::MsgServiceTransportOrder.

Setting the MAPI_UNICODE flag in the ulFlags parameter does the following:

•	Sets the string type to Unicode for data returned for the initial active columns of the provider table by the IMAPITable::QueryColumns method. The initial active columns for a provider table are those columns the QueryColumns method returns before the provider that contains the table calls the IMAPITable::SetColumns method.

•	Sets the string type to Unicode for data returned for the initial active rows of the provider table by QueryRows. The initial active rows for a provider table are those rows QueryRows returns before the provider that contains the table calls SetColumns.

•	Controls the property types of the sort order returned by the IMAPITable::QuerySortOrder method before the client that contains the provider table calls the IMAPITable::SortTable method.

See Also

IMsgServiceAdmin::GetMsgServiceTable, IMsgServiceAdmin::MsgServiceTransportOrder, IProviderAdmin::GetProviderTable


IMsgServiceAdmin::MsgServiceTransportOrder

The IMsgServiceAdmin::MsgServiceTransportOrder method sets the order in which transport providers are called to deliver a message.

Quick Info

See IMsgServiceAdmin : IUnknown.

HRESULT MsgServiceTransportOrder(

ULONG cUID,
LPMAPIUID lpUIDList,
ULONG ulFlags
)
Parameters

cUID

[in] Count of unique identifiers in the lpUIDList parameter.

lpUIDList

[in] Pointer to an array of unique identifiers representing transport providers. The array contains one identifier for each transport provider configured in the current profile.

ulFlags

Reserved; must be zero.

Return Values

S_OK

The transport order was set successfully.

MAPI_E_BUSY

The value in the cUID parameter differs from the number of transport providers actually in the profile.

MAPI_E_NOT_FOUND

One or more of the MAPIUIDs passed in the lpUIDList parameter does not refer to a transport provider currently in the profile.

Remarks

The IMsgServiceAdmin::MsgServiceTransportOrder method sets the delivery order of transport providers within a profile. The lpUIDList parameter must contain a sorted list of transport-provider entry identifiers obtained from the PR_PROVIDER_UID property of the table returned from the IMsgServiceAdmin::GetProviderTable method. A client application must pass the complete list in lpUIDList.

SetTransportOrder overrides transport provider preferences such as the STATUS_XP_PREFER_LAST flag set in the PR_RESOURCE_FLAGS property.

See Also

MAPIUID


IMsgServiceAdmin::OpenProfileSection

The IMsgServiceAdmin::OpenProfileSection method opens a section of the current profile and returns an IProfSect pointer for further access.

Quick Info

See IMsgServiceAdmin : IUnknown.

HRESULT OpenProfileSection(

LPMAPIUID lpUID,
LPCIID lpInterface,
ULONG ulFlags,
LPPROFSECT FAR * lppProfSect
)
Parameters

ulFlags

[in] Bitmask of flags that controls access to the profile section. The following flags can be set:

lpUID

Pointer to the MAPIUID structure identifying the profile section.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the profile section. Passing NULL results in a pointer to its standard interface being returned in the lppProfSect parameter. The standard interface for a profile section is IProfSect.

ulFlags

[in] Bitmask of flags that controls access to the profile section. The following flags can be set:

MAPI_DEFERRED_ERRORS

Allows OpenProfileSection to return successfully, possibly before the profile section is fully accessible to the calling client. If the profile section is not accessible, making a subsequent call to it can result in an error.

MAPI_MODIFY

Requests read/write access. By default, profile sections are opened with read-only access, and clients should not work on the assumption that read/write access has been granted.

lppProfSect

[out] Pointer to a pointer to the profile section.

Return Values

S_OK

The profile section was successfully opened.

MAPI_E_NO_ACCESS

An attempt was made to access a profile section for which the caller has insufficient permissions.

MAPI_E_NOT_FOUND

The requested profile section does not exist.

Remarks

The IMsgServiceAdmin::OpenProfileSection method opens a profile section — an object that supports the IProfSect interface. Profile sections are used for reading information from and writing information to the session profile.

OpenProfileSection cannot be used to open profile sections owned by individual service providers.

Notes to Callers

Multiple clients can open a profile section with read-only access, but only one client can open a profile section with read/write access. If another client has a profile section open that you attempt to open by calling OpenProfileSection with the MAPI_MODIFY flag set, the call will fail, returning MAPI_E_NO_ACCESS.

A read-only open operation fails if the section is open for writing.

You can create a profile section by calling OpenProfileSection with the MAPI_MODIFY flag and a non-existent MAPIUID structure in the lpUID parameter. Make sure you specify MAPI_MODIFY. If you set lpUID to point to a nonexistent MAPIUID and OpenProfileSection is set to use the default access mode of read-only, the call fails with MAPI_E_NOT_FOUND.

See Also

IMAPIProp : IUnknown, IMAPISession::OpenProfileSection, IProfSect : IMAPIProp, MAPIUID


IMsgServiceAdmin::RenameMsgService

The IMsgServiceAdmin::RenameMsgService method assigns a new name to a message service. This method is not currently supported.

Quick Info

See IMsgServiceAdmin : IUnknown.

HRESULT RenameMsgService(

LPMAPIUID lpUID,
ULONG ulFlags,
LPTSTR lpszDisplayName
)
Parameters

lpUID

[in] Pointer to the MAPIUID structure holding the unique identifier for the message service to rename.

ulFlags

Reserved; must be zero.

lpszDisplayName

[in] Pointer to the new name for the message service.

Return Values

MAPI_E_NO_SUPPORT

MAPI does not support renaming this message service. RenameMsgService always returns this value.

Remarks

Clients wanting to assign a new name to a message service should assign a new name to its PR_SERVICE_NAME property. The names of service providers in a message service are stored in their PR_DISPLAY_NAME properties.

See Also

MAPIUID


IMsgServiceAdmin::SetPrimaryIdentity

The IMsgServiceAdmin::SetPrimaryIdentity method designates a message service to be the supplier of the primary identifier for the profile.

Quick Info

See IMsgServiceAdmin : IUnknown.

HRESULT SetPrimaryIdentity(

LPMAPIUID lpUID,
ULONG ulFlags
)
Parameters

lpUID

[in] Pointer to the MAPIUID structure holding the unique identifier for the message service to supply the primary identity, or NULL, indicating that the SetPrimaryIdentity should clear the current identity.

ulFlags

Reserved; must be zero.

Return Values

S_OK

The message service was successfully assigned the supplier of the primary identity.

MAPI_E_NO_ACCESS

SetPrimaryIdentity attempted to designate a message service that has the SERVICE_NO_PRIMARY_IDENTITY flag set in its PR_RESOURCE_FLAGS property.

Remarks

The IMsgServiceAdmin::SetPrimaryIdentity method establishes a message service as the supplier of the primary identity for the profile. The primary identity is the typically the user logged on to the message service. It is represented by three properties:

PR_IDENTITY_DISPLAY

PR_IDENTITY_ENTRYID

PR_IDENTITY_SEARCH_KEY

Every service provider in the designated message service sets these three properties to the display name, entry identifier, and search key of the messaging user that is supplying the primary identity. Clients can retrieve the primary identity’s entry identifier by calling IMAPISession::QueryIdentity.

Another property, PR_RESOURCE_FLAGS, is set to STATUS_PRIMARY_IDENTITY for every provider that is a member of the message service supplying the primary identity and to SERVICE_PRIMARY_IDENTITY for the message service. When a service provider cannot supply the primary identity for its message service, it sets PR_RESOURCE_FLAGS to STATUS_NO_PRIMARY_IDENTITY. SetPrimaryIdentity sets the PR_RESOURCE_FLAGS property of each message service that is not supplying the primary identity to SERVICE_NO_PRIMARY_IDENTITY.

Each message service provider that MAPI has information about can establish an identity for each of its users when a client logs on to the service. However, because MAPI supports connections to multiple service providers for each MAPI session, there is no firm definition of a particular user’s identity for the MAPI session as a whole; a user’s identity depends on which service is involved. Clients can call SetPrimaryIdentity to designate one of the many identities established for a user by message services as the primary identity for that user.

See Also

IMAPISession::QueryIdentity, MAPIUID


IMsgStore : IMAPIProp

The IMsgStore interface provides access to message store information and to messages and folders.

Quick Info

Header file:	MAPIDEFS.H
Exposed by:	Message store object
Implemented by:	Message store providers
Called by:	Client applications, the MAPI spooler, MAPI
Corresponding pointer type:	LPMDB
Transaction model:	Non-transacted
Vtable Order

Advise	Registers to receive notification of specified events affecting the message store.
Unadvise	Cancels the sending of notifications previously set up with a call to the IMsgStore::Advise method.
CompareEntryIDs	Compares two folder or message entry identifiers to determine if they refer to the same object.
OpenEntry	Opens a folder or message and returns an interface pointer for further access.
SetReceiveFolder	Establishes a folder as the destination for incoming messages of a particular message class.
GetReceiveFolder	Obtains the folder that was established as the destination for incoming messages of a specified message class or the default receive folder for the message store.
GetReceiveFolderTable	Provides access to the receive folder table, a table with information about all of the receive folders for the message store.
StoreLogoff	Enables the orderly logoff of the message store.
AbortSubmit	Attempts to remove a message from the outgoing queue.
GetOutgoingQueue	Provides access to the outgoing queue table, a table with information about all of the messages in the message store’s outgoing queue. This method is called only by the MAPI spooler.
SetLockState	Locks or unlocks a message. This method is called only by the MAPI spooler.
FinishedMsg	Enables the message store provider to perform processing on a sent message. This method is called only by the MAPI spooler.
NotifyNewMail	Informs the message store that a new message has arrived. This method is called only by the MAPI spooler.
Required properties	Access level
PR_DISPLAY_NAME	Read/write
PR_ENTRYID	Read-only
PR_OBJECT_TYPE	Read-only
PR_RECORD_KEY	Read-only
PR_STORE_ENTRYID	Read-only
PR_STORE_RECORD_KEY	Read-only
PR_MDB_PROVIDER	Read-only
PR_STORE_SUPPORT_MASK	Read-only
Properties for IPM message stores
PR_IPM_OUTBOX_ENTRYID	PR_IPM_OUTBOX_SEARCH_KEY
PR_IPM_SENTMAIL_ENTRYID	PR_IPM_SENTMAIL_SEARCH_KEY
PR_IPM_SUBTREE_ENTRYID	PR_IPM_SUBTREE_SEARCH_KEY
PR_IPM_WASTEBASKET_ENTRYID	PR_IPM_WASTEBASKET_SEARCH_KEY
PR_MDB_PROVIDER	PR_STORE_SUPPORT_MASK


IMsgStore::AbortSubmit

The IMsgStore::AbortSubmit method attempts to remove a message from the outgoing queue.

Quick Info

See IMsgStore : IMAPIProp.

AbortSubmit(

ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulFlags
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the message to remove from the outgoing queue.

ulFlags

Reserved; must be zero.

Return Values

S_OK

The message was successfully removed from the outgoing queue.

MAPI_E_NOT_IN_QUEUE

The message identified by lpEntryID is no longer in the message store’s outgoing queue, typically because it has already been sent.

MAPI_E_UNABLE_TO_ABORT

The message identified by lpEntryID is locked by the MAPI spooler, and the operation cannot be aborted.

Remarks

The IMsgStore::AbortSubmit method attempts to remove a submitted message from the message store’s outgoing queue.

Notes to Callers

After a message is submitted, aborting the submission by calling AbortSubmit is the only action that can be performed on the message. Do not expect AbortSubmit always to succeed. Depending on how the underlying messaging system is implemented, it might not be possible to cancel the sending of the message.

See Also

IMessage::SubmitMessage


IMsgStore::Advise

The IMsgStore::Advise method registers to receive notification of specified events affecting the message store.

Quick Info

See IMsgStore : IMAPIProp.

HRESULT Advise(

ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the folder or message about which notifications should be generated or NULL.. If lpEntryID is set to NULL, Advise registers for notifications on the entire message store.

ulEventMask

[in] A mask of values indicating the types of notification events that the caller is interested in and should be included in the registration. There is a corresponding NOTIFICATION structure associated with each type of event that holds information about the event.

The following table lists the valid values for the ulEventMask parameter:

fnevCriticalError

Registers for notifications about severe errors, such as insufficient memory.

fnevExtended

Registers for notifications about events specific to the particular message store provider.

fnevNewMail

Registers for notifications about the arrival of new messages.

fnevObjectCreated

Registers for notifications about the creation of a new folder or message.

fnevObjectCopied

Registers for notifications about a folder or message being copied.

fnevObjectDeleted

Registers for notifications about a folder or message being deleted.

fnevObjectModified

Registers for notifications about a folder or message being modified.

fnevObjectMoved

Registers for notifications about a folder or message being moved.

fnevSearchComplete

Registers for notifications about the completion of a search operation.

lpAdviseSink

[in] Pointer to an advise sink object to receive the subsequent notifications. This advise sink object must have already been allocated.

lpulConnection

[out] Pointer to a nonzero number that represents the connection between the caller’s advise sink object and the session.

lpAdviseSink

[in] Pointer to an advise sink object to receive the subsequent notifications. This advise sink object must have already been allocated.

lpulConnection

[out] Pointer to a nonzero connection number representing the connection between the caller’s advise sink object and the message store.

Return Value

S_OK

The registration was successful.

MAPI_E_NO_SUPPORT

The message store provider does not support registration for notification through the message store. This error value is returned if the caller is not the MAPI spooler.

Remarks

The IMsgStore::Advise method establishes a connection between the caller’s advise sink object and either the message store or an object in the message store. This connection is used to send notifications to the advise sink when one or events as specified in the ulEventMask parameter occurs to the advise source object. When lpEntryID points to a valid entry identifier, the advise source is the object identified by this entry identifier. When lpEntryID is NULL, the advise source is the message store.

To send a notification, either the message store provider or MAPI calls the registered advise sink’s IMAPIAdviseSink::OnNotify method. One of the parameters to OnNotify, a notification structure, contains information that describes the specific event.

Notes to Implementers

You can support notification with or without help from MAPI. MAPI has three support object methods for helping service providers implement notification: IMAPISupport::Subscribe, IMAPISupport::Unsubscribe, and IMAPISupport::Notify. If you elect to use the MAPI support methods, call Subscribe when your Advise method is called and release the lpAdviseSink pointer.

If you elect to support notification yourself, call the IUnknown::AddRef method of the advise sink represented by the lpAdviseSink parameter to keep a copy of this pointer. Maintain this copy until your IMsgStore::Unadvise method is called to cancel the registration.

Regardless of how you support notification, assign a nonzero connection number to the notification registration and return it in the lpulConnection parameter. Do not release this connection number until Unadvise has been called and has completed.

Notes to Callers

On systems that support multiple threads of execution, the call to OnNotify can also occur on any thread at any time. If you must be assured that notifications only occur at a particular time on a particular thread, call HrThisThreadAdviseSink to generate the advise sink object that you pass to Advise.

After a call to Advise has succeeded and before Unadvise has been called to cancel the registration, be prepared for the advise sink object to be released. It is wise to release your advise sink object after Advise returns unless you have a specific long-term use for it.

For an overview of the notification process, see Event Notification in MAPI.

For more information on handling notifications, see Handling Notifications.

See Also

HrThisThreadAdviseSink, IMAPIAdviseSink::OnNotify, IMsgStore::Unadvise, NOTIFICATION


IMsgStore::CompareEntryIDs

The IMsgStore::CompareEntryIDs method compares two entry identifiers to determine if they refer to the same entry within a message store. MAPI only passes this call to a service provider if the unique identifiers (UIDs) in both entry identifiers to be compared are handled by that provider.

Quick Info

See IMsgStore : IMAPIProp.

HRESULT CompareEntryIDs(

ULONG cbEntryID1,
LPENTRYID lpEntryID1,
ULONG cbEntryID2,
LPENTRYID lpEntryID2,
ULONG ulFlags,
ULONG FAR * lpulResult
)
Parameters

cbEntryID1

[in] Count of bytes in the entry identifier pointed to by the lpEntryID1 parameter.

lpEntryID1

[in] Pointer to the first entry identifier to be compared.

cbEntryID2

[in] Count of bytes in the entry identifier pointed to by the lpEntryID2 parameter.

lpEntryID2

[in] Pointer to the second entry identifier to be compared.

ulFlags

Reserved; must be zero.

lpulResult

[out] Pointer to the result of the comparison, set toTRUE if the two entry identifiers refer to the same object and FALSE otherwise.

Return Values

S_OK

The comparison was successful.

MAPI_E_UNKNOWN_ENTRYID

One or both of the entry identifiers specified as parameters do not refer to objects, possible because the corresponding objects are unopened and inaccessible at present.

Remarks

The IMsgStore::CompareEntryIDs method compares two entry identifiers belonging to the message store to determine whether they refer to the same object.

Notes to Callers

CompareEntryIDs is useful because an object can have more than one valid entry identifier; such a situation can occur, for example, after a new version of a message store provider is installed.

If CompareEntryIDs returns an error, do not take any action based on the result of the comparison. Instead, take the most conservative approach possible. CompareEntryIDs might fail if, for example, one or both of the entry identifiers contains an invalid MAPIUID.

See Also

MAPIUID


IMsgStore::FinishedMsg

The IMsgStore::FinishedMsg method enables the message store provider to perform processing on a sent message. This method is called only by the MAPI spooler.

Quick Info

See IMsgStore : IMAPIProp.

HRESULT FinishedMsg(

ULONG ulFlags,
ULONG cbEntryID,
LPENTRYID lpEntryID
)
Parameters

ulFlags

Reserved; must be zero.

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the message to be processed.

Return Values

S_OK

Processing on the sent message was successful.

MAPI_E_NO_SUPPORT

The message store provider does not support sent message processing. This error value is returned if the caller is not the MAPI spooler.

Remarks

The IMsgStore::FinishedMsg method performs processing on a sent message. This processing can involve deleting the message, moving it to a different folder, or both actions. The type of processing depends on whether or not the PR_DELETE_AFTER_SUBMIT and PR_SENTMAIL_ENTRYID properties are set.

Notes to Implementers

In your implementation of FinishedMsg, unlock the message identified by lpEntryID and perform the appropriate processing. The target message will always be locked; the MAPI spooler never passes the entry identifier for an unlocked message to FinishedMsg.

It is possible that neither of these properties are set, both are set, or one or the other is set. The following table describes the action you should take based on the settings:

If neither property is set	Leave the message in the folder from which it was sent (typically the Outbox).
If both properties are set	Move the message to the indicated folder, if desired, and then delete it.
If PR_SENTMAIL_ENTRYID is set	Move the message to the indicated folder.
If PR_DELETE_AFTER_SUBMIT is set	Delete the message.
After you have taken whatever action is appropriate, call IMAPISupport::DoSentMail.

See Also

IMAPISupport::DoSentMail


IMsgStore::GetOutgoingQueue

The IMsgStore::GetOutgoingQueue method provides access to the outgoing queue table, a table with information about all of the messages in the message store’s outgoing queue. This method is called only by the MAPI spooler.

Quick Info

See IMsgStore : IMAPIProp.

HRESULT GetOutgoingQueue(

ULONG ulFlags,
LPMAPITABLE FAR * lppTable
)
Parameters

ulFlags

Reserved; must be zero.

lppTable

[out] Pointer to a pointer to the outgoing queue table.

Return Value

S_OK

The outgoing queue table was successfully returned.

Remarks

The IMsgStore::GetOutgoingQueue method provides the MAPI spooler with access to the table showing the message store’s queue of outgoing messages. Typically, messages are placed in the outgoing queue table after their IMessage::SubmitMessage method is called. However, because the order of submission affects the order of preprocessing and submission to the transport provider, some messages that have been marked for sending might not appear in the outgoing queue table immediately.

Notes to Implementers

For a list of the properties that must be included as columns in your outgoing queue table, see Outgoing Queue Tables.

Because the MAPI spooler is designed to accept messages from a message store in ascending order of submission time, either allow the MAPI spooler to sort the outgoing queue table to match this order or establish it as the default sort order.

You must support notifications for the outgoing message queue table, ensuring that the MAPI spooler is notified when the contents of the queue change.

See Also

IMessage::SubmitMessage


IMsgStore::GetReceiveFolder

The IMsgStore::GetReceiveFolder method obtains the folder that was established as the destination for incoming messages of a specified message class or the default receive folder for the message store.

Quick Info

See IMsgStore : IMAPIProp.

HRESULT GetReceiveFolder(

LPTSTR lpszMessageClass,
ULONG ulFlags,
ULONG FAR * lpcbEntryID,
LPENTRYID FAR * lppEntryID,
LPTSTR FAR * lppszExplicitClass
)
Parameters

lpszMessageClass

[in] Pointer to a message class that is associated with a receive folder. If the lpszMessageClass parameter is set to NULL or an empty string, GetReceiveFolder returns the default receive folder for the message store.

ulFlags

[in] Bitmask of flags that controls the type of the passed-in and returned strings. The following flag can be set:

MAPI_UNICODE

The message class string is in Unicode format. If the MAPI_UNICODE flag is not set, the message class string is in ANSI format.

lpcbEntryID

[out] Pointer to the count of bytes in the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[out] Pointer to a pointer to the entry identifier for the requested receive folder.

lppszExplicitClass

[out] Pointer to a pointer to the message class that explicitly sets as its receive folder the folder pointed to by lppEntryID. This message class should either be the same as the class in the lpszMessageClass parameter or of a superclass of that class. Passing NULL indicates that the folder pointed to by lppEntryID is the default receive folder for the message store.

Return Value

S_OK

The receive folder was successfully returned.

Remarks

The IMsgStore::GetReceiveFolder method obtains the entry identifier of a receive folder, a folder designated to receive incoming messages of a particular message class. Callers can specify a message class or NULL in the lpszMessageClass parameter. If lpszMessageClass is NULL, GetReceiveFolder returns:

•	In lppszExplicitClass, the name of the first superclass of the message class pointed to by lpszMessageClass that does explicitly set a receive folder.

•	In lppEntryID, the entry identifier of the receive folder for the superclass pointed to by the lppszExplicitClass parameter.

For example, suppose the receive folder of the message class IPM.Note has been set to the entry identifier of the Inbox and GetReceiveFolder is called with the contents of lpszMessageClass set to IPM.Note.Phone. If IPM.Note.Phone does not have an explicit receive folder set, GetReceiveFolder returns the entry identifier of the Inbox in lppEntryID and IPM.Note in lppszExplicitClass.

If the client calls GetReceiveFolder for a message class and has not set a receive folder for that message class, lppszExplicitClass is either a zero-length string, a string in Unicode format, or a string in ANSI format depending on whether the client set the MAPI_UNICODE flag in the ulFlags parameter.

A default receive folder, obtained by passing NULL in the lpszMessageClass parameter, always exists for every message store.

A client should call the MAPIFreeBuffer function when it is done with the entry identifier returned in lppEntryID to free the memory that holds that entry identifier. It should also call MAPIFreeBuffer when it is done with the message class string returned in lppszExplicitClass to free the memory that holds that string.

See Also

MAPIFreeBuffer


IMsgStore::GetReceiveFolderTable

The IMsgStore::GetReceiveFolderTable method provides access to the receive folder table, a table that includes information about all of the receive folders for the message store.

Quick Info

See IMsgStore : IMAPIProp.

HRESULT GetReceiveFolderTable(

ULONG ulFlags,
LPMAPITABLE FAR * lppTable
)
Parameters

ulFlags

[in] Bitmask of flags that controls table access. The following flags can be set:

MAPI_DEFERRED_ERRORS

Allows GetReceiveFolderTable to return successfully, possibly before the table is fully accessible to the caller. If the table is not fully accessible, making a subsequent table call can result in an error.

MAPI_UNICODE

The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppTable

[out] Pointer to a pointer to the receive folder table.

Return Value

S_OK

The receive folder table was successfully returned.

Remarks

The IMsgStore::GetReceiveFolderTable method provides access to a table showing the property settings for all of the message store’s receive folders.

Notes to Implementers

For a list of required columns in a receive folder table, see Receive Folder Tables.

Implement your receive folder tables to support setting property restrictions on the PR_RECORD_KEY property, allowing easy access to particular receive folders.

Notes to Callers

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the format of the columns returned from the following IMAPITable methods:

IMAPITable::QueryColumns

IMAPITable::QueryRows

This flag also controls the property types in the sort order returned by the IMAPITable::QuerySortOrder method.

See Also

IMAPITable::QueryColumns, IMAPITable::QueryRows, IMAPITable::QuerySortOrder, IMAPITable::SetColumns


IMsgStore::NotifyNewMail

The IMsgStore::NotifyNewMail method informs the message store that a new message has arrived. This method is called only by the MAPI spooler.

Quick Info

See IMsgStore : IMAPIProp.

HRESULT NotifyNewMail(

LPNOTIFICATION lpNotification
)
Parameters

lpNotification

[in] Pointer to a NOTIFICATION structure describing the new-message notification.

Return Value

S_OK

The message store was successfully notified.

Remarks

The IMsgStore::NotifyNewMail method is called by the MAPI spooler to inform the message store that a message is ready for delivery.

Notes to Implementers

When NotifyNewMail is called, send a new mail notification to all registered clients. This can be done by calling IMAPISupport::Notify if you elect to use the support object methods or with your own implementation. A registered client is one that has called IMsgStore::Advise and set the lpEntryID parameter to NULL and the ulEventMask parameter to fnevNewMail.

Do not modify or free the memory for the NOTIFICATION structure that describes the new mail notification. Copy the NOTIFICATION structure by calling the utility function ScCopyNotifications to make use of the information in its members.

See Also

IMAPISupport::Subscribe, IMAPISupport::Unsubscribe, NOTIFICATION, ScCopyNotifications


IMsgStore::OpenEntry

The IMsgStore::OpenEntry method opens a folder or message and returns an interface pointer for further access.

Quick Info

See IMsgStore : IMAPIProp.

HRESULT OpenEntry(

ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
ULONG ulFlags,
ULONG FAR * lpulObjType,
LPUNKNOWN FAR * lppUnk
)
Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the object to open or NULL. If lpEntryID is set to NULL, OpenEntry opens the root folder for the message store.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the opened object. Passing NULL results in the object’s standard interface being returned which is IMAPIFolder for folders and IMessage for messages.

ulFlags

[in] Bitmask of flags that controls how the object is opened. The following flags can be used:

MAPI_BEST_ACCESS

Requests that the object be opened with the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write access, the object should be opened with read/write access; if the client has read-only access, the object should be opened with read-only access.

MAPI_DEFERRED_ERRORS

Allows OpenEntry to return successfully, possibly before the object is fully accessible to the calling client. If the object is not accessible, making a subsequent object call can result in an error.

MAPI_MODIFY

Requests read/write access. By default, objects are opened with read-only access, and clients should not work on the assumption that read/write access has been granted.

lpulObjType

[out] Pointer to the type of the opened object.

lppUnk

[out] Pointer to a pointer to the opened object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_ACCESS

An attempt was made to modify a read-only object or to access an object for which the user has insufficient permissions.

Remarks

The IMsgStore::OpenEntry method opens a folder or message and returns a pointer to an interface that can be used for further access.

Notes to Callers

Folders and messages are automatically opened with read-only access, unless you set the MAPI_MODIFY or MAPI_BEST_ACCESS flag in the ulFlags parameter. Setting one of these flags does not guarantee a particular type of access; the permissions that you are granted depends on the message store provider, your access level, and the object. To determine the access level of the opened object, retrieve its PR_ACCESS_LEVEL property.

Although IMsgStore::OpenEntry can be used to open any folder or message, it is usually faster to use IMAPIContainer::OpenEntry if you have access to the folder containing the folder or message to be opened.

Check the value returned in the lpulObjType parameter to determine that the object type returned is what you expected. If the object type is not the expected type, cast the pointer from the lppUnk parameter to a pointer of the appropriate type. For example, if you are opening a folder, cast lppUnk to a pointer of type LPMAPIFOLDER.

See Also

IMAPIContainer::OpenEntry


IMsgStore::SetLockState

The IMsgStore::SetLockState method locks or unlocks a message. This method is called only by the MAPI spooler.

Quick Info

See IMsgStore : IMAPIProp.

HRESULT SetLockState(

LPMESSAGE lpMessage,
ULONG ulLockState
)
Parameters

lpMessage

[in] Pointer to the message to lock or unlock.

ulLockState

[in] Value indicating whether the message should be locked or unlocked. One of the following values are valid:

MSG_LOCKED

The message should be locked.

MSG_UNLOCKED

The message should be unlocked.

Return Value

S_OK

The lock state of the message was successfully set.

Remarks

The IMsgStore::SetLockState method locks or unlocks a message. SetLockState can only be called by the MAPI spooler while it is sending the message.

Usually, when the MAPI spooler calls SetLockState to lock a message, it only locks the oldest message — that is, the next message queued for the MAPI spooler to send. If the oldest message in the queue is waiting for a temporarily unavailable transport provider, and the next message in the queue uses a different transport provider, the MAPI spooler can begin processing the later message. It begins processing by locking that message using SetLockState.

Notes to Implementers

After the MAPI spooler has called SetLockState with the ulLockState parameter set to MSG_LOCKED, calls to IMsgStore::AbortSubmit to cancel the message’s transmission must fail.

Call the message’s IMAPIProp::SaveChanges method in your SetLockState implementation so that any changes made to the message before the SetLockState call was received are saved.

See Also

IMsgStore::AbortSubmit, IMsgStore::FinishedMsg


IMsgStore::SetReceiveFolder

The IMsgStore::SetReceiveFolder method establishes a folder as the destination for incoming messages of a particular message class.

Quick Info

See IMsgStore : IMAPIProp.

HRESULT SetReceiveFolder(

LPTSTR lpszMessageClass,
ULONG ulFlags,
ULONG cbEntryID,
LPENTRYID lpEntryID
)
Parameters

lpszMessageClass

[in] Pointer to the message class that is to be associated with the new receive folder. If the lpszMessageClass parameter is set to NULL or an empty string, SetReceiveFolder sets the default receive folder for the message store.

ulFlags

[in] Bitmask of flags that controls the type of the text in the passed-in strings. The following flag can be set:

MAPI_UNICODE

The message class string is in Unicode format. If the MAPI_UNICODE flag is not set, the message class string is in ANSI format.

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the folder to establish as the receive folder. If the lpEntryID parameter is set to NULL, SetReceiveFolder replaces the current receive folder with the message store’s default.

Return Value

S_OK

A receive folder was successfully established.

Remarks

The IMsgStore::SetReceiveFolder method sets or changes the receive folder for a particular message class. With SetReceiveFolder, a client can, by using successive calls, specify a different receive folder for each message class defined or specify that incoming messages for multiple message classes all go to the same folder. A client can, for example, have its own class of messages arrive in its own folder. For instance, a fax application can designate a folder where the store provider places incoming faxes and one where the provider places outgoing faxes.

If an error occurs while calling SetReceiveFolder, the receive folder setting remains unchanged.

If SetReceiveFolder changes the receive folder setting with lpEntryID set to NULL, indicating the default receive folder should be set, SetReceiveFolder returns S_OK even if there was no existing setting for the indicated message class.


IMsgStore::StoreLogoff

The IMsgStore::StoreLogoff method enables the orderly logoff of the message store.

Quick Info

See IMsgStore : IMAPIProp.

HRESULT StoreLogoff(

ULONG FAR * lpulFlags
)
Parameters

lpulFlags

[in, out] Bitmask of flags that controls logoff from the message store. On input, all flags set for this parameter are mutually exclusive; a caller must specify only one flag per call. The following flags are valid on input:

LOGOFF_ABORT

Any transport provider activity for this message store should be stopped before logoff. Control is returned to the caller after activity is stopped. If any transport provider activity is taking place, the logoff does not occur and no change in the behavior of the MAPI spooler or transport providers occurs. If transport provider activity is quiet, the MAPI spooler releases the store.

LOGOFF_NO_WAIT

The message store should not wait for messages from transport providers before closing. Outbound messages that are ready to be sent are sent. If this store contains the default Inbox, any in-process messages are received, and then further reception is disabled. When all activity is completed, the MAPI spooler releases the store, and control is returned to the caller immediately.

LOGOFF_ORDERLY

The message store should not wait for information from transport providers before closing. Messages currently being processed are completed, but no new messages are processed. When all activity is completed, the MAPI spooler releases the store, and control is returned to the store provider immediately.

LOGOFF_PURGE

The logoff should work the same as if the LOGOFF_NO_WAIT flag is set, but that either IXPLogon::FlushQueues or IMAPIStatus::FlushQueues for the appropriate transport providers should be called. The LOGOFF_PURGE flag returns control to the caller after completion.

LOGOFF_QUIET

If any transport provider activity is taking place, the logoff should not occur.

The following flags are valid on output:

LOGOFF_INBOUND

Inbound messages are currently arriving.

LOGOFF_OUTBOUND

Outbound messages are in the process of being sent.

LOGOFF_OUTBOUND_QUEUE

Outbound messages are pending, that is, they are in the Outbox.

Return Value

S_OK

The logoff completed successfully.

Remarks

The IMsgStore::StoreLogoff method exerts control over the interaction of the message store and transport providers during the logoff process. Calling StoreLogoff is valid only for message stores that are being used by only the caller. When two clients, for example, are using the same message store and one of them calls StoreLogoff, the message store is immediately released and control is returned to the calling client.

Notes to Implementers

Save the flags that are passed to StoreLogoff and pass them when you call IMAPISupport::StoreLogoffTransports. Do not call StoreLogoffTransports until the message store’s reference count drops to zero. Multiple calls to StoreLogoffTransports simply overwrite the saved flags.

If no call has been made to StoreLogoff before the message store’s reference count reaches zero, set the LOGOFF_ABORT flag in the ulFlags parameter that you pass to StoreLogoffTransports.

See Also

IMAPIStatus::FlushQueues, IMAPISupport::StoreLogoffTransports, IXPLogon::FlushQueues


IMsgStore::Unadvise

The IMsgStore::Unadvise method cancels the sending of notifications previously set up with a call to the IMsgStore::Advise method.

Quick Info

See IMsgStore : IMAPIProp.

HRESULT Unadvise(

ULONG ulConnection
)
Parameters

ulConnection

[in] Connection number associated with an active notification registration. The value of ulConnection must have been returned by a previous call to IMsgStore::Advise.

Return Value

S_OK

The registration was successfully canceled.

Remarks

The IMsgStore::Unadvise method cancels a registration for notification. Unadvise releases its pointer to the caller’s advise sink, which it received in the Advise call used for registration.

Generally, Unadvise calls the advise sink’s IUnknown::Release method during the Unadvise call, but if another thread is in the process of calling the advise sink’s IMAPIAdviseSink::OnNotify method, the Release call is delayed until the OnNotify method returns.

See Also

IMAPIAdviseSink::OnNotify, IMsgStore::Advise


IMSLogon : IUnknown

The IMSLogon interface is used to access resources in a message store logon object. The message store logon object is the part of an open message store provider that is called directly by MAPI. There is a one-to-one correspondence between the message store logon object called by MAPI and the message store object called by client applications; you can think of the logon and store objects as one object exposing two interfaces. The two objects are created together and freed together.

Quick Info

Header file:	MAPISPI.H
Exposed by:	Message store logon objects
Implemented by:	Message store providers
Called by:	MAPI
Corresponding pointer type:	LPMSLOGON
Vtable Order

GetLastError	Returns a MAPIERROR structure containing information about the last error that occurred for the message store object.
Logoff	Logs off a message store provider.
OpenEntry	Opens a folder or message object and returns a pointer to the object to provide further access.
CompareEntryIDs	Compares two entry identifiers to determine if they refer to the same object.
Advise	Registers a message store provider for notifications about changes within the message store.
Unadvise	Removes an object’s registration for notification of message store changes previously established with a call to the IMSLogon::Advise method.
OpenStatusEntry	Opens a status object.


IMSLogon::Advise

The IMSLogon::Advise method registers a message store provider for notifications about changes within the message store.

Quick Info

See IMSLogon : IUnknown.

HRESULT Advise(

ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
)
Parameters

cbEntryID

[in] Size, in bytes, of the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the object about which notifications should be generated. This object can be a folder, a message, or any other object in the message store. Alternatively, if MAPI sets the cbEntryID parameter to zero and passes NULL for lpEntryID, the advise sink provides notifications about changes to the entire message store.

ulEventMask

[in] Event mask of the types of notification events occurring for the object about which MAPI will generate notifications. The mask filters specific cases. Each event type has a structure associated with it that holds additional information about the event. The following table lists the possible event types along with their corresponding structures.

Notification event type	Corresponding structure
fnevCriticalError	ERROR_NOTIFICATION
fnevNewMail	NEWMAIL_NOTIFICATION
fnevObjectCreated	OBJECT_NOTIFICATION
fnevObjectDeleted	OBJECT_NOTIFICATION
fnevObjectModified	OBJECT_NOTIFICATION
fnevObjectCopied	OBJECT_NOTIFICATION
fnevObjectMoved	OBJECT_NOTIFICATION
fnevSearchComplete	OBJECT_NOTIFICATION
fnevStatusObjectModified	STATUS_OBJECT_NOTIFICATION
lpAdviseSink

[in] Pointer to an advise sink object to be called when an event occurs for the session object about which notification has been requested. This advise sink object must have already been allocated.

lpulConnection

[out] Pointer to a variable that upon a successful return holds the connection number for the notification registration. The connection number must be nonzero.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_SUPPORT

The operation is not supported by MAPI or by one or more service providers.

Remarks

Message store providers implement the IMSLogon::Advise method to register an object for notification callbacks. Whenever a change occurs to the indicated object, the provider checks to see what event mask bit was set in the ulEventMask parameter and thus what type of change occurred. If a bit is set, then the provider calls the IMAPIAdviseSink::OnNotify method for the advise sink object indicated by the lpAdviseSink parameter to report the event. Data passed in the notification structure to the OnNotify routine describes the event.

The call to OnNotify can occur during the call that changes the object, or at any following time. On systems that support multiple threads of execution, the call to OnNotify can occur on any thread. For a way to turn a call to OnNotify that might happen at an inopportune time into one that is safer to handle, a client application should use the HrThisThreadAdviseSink function.

To provide notifications, the message store provider implementing Advise needs to keep a copy of the pointer to the lpAdviseSink advise sink object; to do so, it calls the IUnknown::AddRef method for the advise sink to maintain its object pointer until notification registration is canceled with a call to the IMSLogon::Unadvise method. The Advise implementation should assign a connection number to the notification registration and call AddRef on this connection number before returning it in the lpulConnection parameter. Service providers can release the advise sink object before the registration is canceled, but they must not release the connection number until Unadvise has been called.

After a call to Advise has succeeded and before Unadvise has been called, providers must be prepared for the advise sink object to be released. A provider should therefore release its advise sink object after Advise returns unless it has a specific long-term use for it.

For more information about the notification process, see Event Notification in MAPI.

See Also

HrThisThreadAdviseSink, IMAPIAdviseSink::OnNotify, IMSLogon::Unadvise, NOTIFICATION


IMSLogon::CompareEntryIDs

The IMSLogon::CompareEntryIDs method compares two entry identifiers to determine if they refer to the same object. MAPI only passes this call to a service provider if the unique identifiers (UIDs) in both entry identifiers to be compared are handled by that provider.

Quick Info

See IMSLogon : IUnknown.

HRESULT CompareEntryIDs(

ULONG cbEntryID1,
LPENTRYID lpEntryID1,
ULONG cbEntryID2,
LPENTRYID lpEntryID2,
ULONG ulFlags,
ULONG FAR * lpulResult
)
Parameters

cbEntryID1

[in] Size, in bytes, of the entry identifier pointed to by the lpEntryID1 parameter.

lpEntryID1

[in] Pointer to the first entry identifier to be compared.

cbEntryID2

[in] Size, in bytes, of the entry identifier pointed to by the lpEntryID2 parameter.

lpEntryID2

[in] Pointer to the second entry identifier to be compared.

ulFlags

Reserved; must be zero.

lpulResult

[out] Pointer to the returned result of the comparison; this variable is TRUE if the two entry identifiers refer to the same object, and FALSE otherwise.

Return Value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Message store providers implement the IMSLogon::CompareEntryIDs method to compare two entry identifiers for a given entry within a message store to determine whether they refer to the same object. If the two entry identifiers refer to the same object, then CompareEntryIDs sets the lpulResult parameter to TRUE; if they refer to different objects, CompareEntryIDs sets lpulResult to FALSE.

CompareEntryIDs is useful because an object can have more than one valid entry identifier; such a situation can occur, for example, after a new version of a message store provider is installed.


IMSLogon::GetLastError

The IMSLogon::GetLastError method returns a MAPIERROR structure containing information about the last error that occurred for the message store object.

Quick Info

See IMSLogon : IUnknown.

HRESULT GetLastError(

HRESULT hResult,
ULONG ulFlags,
LPMAPIERROR FAR * lppMAPIError
)
Parameters

hResult

[in] HRESULT data type containing the error value generated in the previous method call for the message store object.

ulFlags

[in] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] Pointer to a pointer to the returned MAPIERROR structure containing version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

Remarks

Use the IMSLogon::GetLastError method to retrieve information to display in a message to the user regarding the last error returned from a method call for the message store object.

To release all the memory allocated by MAPI for the returned MAPIERROR structure, client applications need only call the MAPIFreeBuffer function.

The return value from GetLastError must be S_OK for an application to make use of the MAPIERROR structure. Even if the return value is S_OK, a MAPIERROR structure might not be returned. If the implementation cannot determine what the last error was, or if a MAPIERROR structure is not available for that error, GetLastError returns a pointer to NULL in lppMAPIError instead.

See Also

MAPIERROR, MAPIFreeBuffer


IMSLogon::Logoff

The IMSLogon::Logoff method logs off a message store provider.

Quick Info

See IMSLogon : IUnknown.

HRESULT Logoff(

ULONG FAR * lpulFlags
)
Parameters

lpulFlags

Reserved; must be a pointer to zero.

Return Value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Message store providers implement the IMSLogon::Logoff method to forcibly shut down a message store provider. IMSLogon::Logoff is called:

•	While MAPI is logging off a client after a call to the IMAPISession::Logoff method.

•	While MAPI is logging off a message store provider. In this case, IMSLogon::Logoff is called as part of MAPI’s processing the IUnknown::Release method of the support object that the message store provider creates while it is processing an IMsgStore::StoreLogoff or IUnknown::Release method call on a message store object.

See Also

IMAPISession::Logoff, IMAPISupport : IUnknown, IMsgStore::StoreLogoff, IMSProvider::Logon, MAPIFreeBuffer


IMSLogon::OpenEntry

The IMSLogon::OpenEntry method opens a folder or message object and returns a pointer to the object to provide further access.

Quick Info

See IMSLogon : IUnknown.

HRESULT OpenEntry(

ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
ULONG ulOpenFlags,
ULONG FAR * lpulObjType,
LPUNKNOWN FAR * lppUnk
)
Parameters

cbEntryID

[in] Size, in bytes, of the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the address of the entry identifier of the folder or message object to open.

lpInterface

[in] Pointer to the interface identifier (IID) for the object. Passing NULL indicates the object is cast to the standard interface for such an object. The lpInterface parameter can also be set to an identifier for an appropriate interface for the object.

ulOpenFlags

[in] Bitmask of flags that controls how the object is opened. The following flags can be set:

MAPI_BEST_ACCESS

The object should be opened with the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write access, the object is opened with read/write access; if the client has read-only access, the object is opened with read-only access. The client can retrieve the access level by getting the PR_ACCESS_LEVEL property.

MAPI_DEFERRED_ERRORS

The call is allowed to succeed even if the underlying object is not accessible to the calling application. If the object is not accessible, some subsequent call to the object might return an error.

MAPI_MODIFY

Requests read/write access. By default, objects are created with read-only access, and clients should not work on the assumption that read/write access has been granted.

lpulObjType

[out] Pointer to the type of the opened object.

lppUnk

[out] Pointer to the pointer to the opened object.

Return Value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

MAPI calls the IMSLogon::OpenEntry method to open a folder or a message in a message store. MAPI passes in the entry identifier of the object to open; the message store provider should return a pointer providing further access to the object in the lppUnk parameter.

Before MAPI calls IMSLogon::OpenEntry, it first determines that the given message or folder entry identifier matches one registered by this message store provider. For more information on how store providers register entry identifiers, see IMAPISupport::SetProviderUID.

IMSLogon::OpenEntry is identical to the IMsgStore::OpenEntry method of the message store object but is called by MAPI when processing an IMAPISession::OpenEntry method call instead of being called by a client. Objects opened using IMSLogon::OpenEntry should be treated exactly the same as objects opened with the message store object; in particular, objects opened using this call should be invalidated when the message store object is released.

See Also

IMAPISupport::SetProviderUID, IMsgStore::OpenEntry


IMSLogon::OpenStatusEntry

The IMSLogon::OpenStatusEntry method opens a status object.

Quick Info

See IMSLogon : IUnknown.

HRESULT OpenStatusEntry(

LPCIID lpInterface,
ULONG ulFlags,
ULONG FAR * lpulObjType,
LPVOID FAR * lppEntry
)
Parameters

lpInterface

[in] Pointer to the interface identifier (IID) for the status object to open. Passing NULL indicates the standard interface for the object is returned, in this case the IMAPIStatus interface. The lpInterface parameter can also be set to an identifier for an appropriate interface for the object.

ulFlags

[in] Bitmask of flags that controls how the status object is opened. The following flag can be set:

MAPI_MODIFY

Requests read/write access. By default, objects are created with read-only access, and client applications should not work on the assumption that read/write access has been granted.

lpulObjType

[out] Pointer to the type of the opened object.

lppEntry

[out] Pointer to the pointer to the opened object.

Return Value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Message store providers implement the IMSLogon::OpenStatusEntry method to open a status object. This status object is then used to enable clients to call IMAPIStatus methods; for example, clients can use the IMAPIStatus::SettingsDialog method to reconfigure the message store logon session or the IMAPIStatus::ValidateState method to validate the state of the message store logon session.

See Also

IMAPIStatus : IMAPIProp, IMAPIStatus::SettingsDialog, IMAPIStatus::ValidateState


IMSLogon::Unadvise

The IMSLogon::Unadvise method removes an object’s registration for notification of message store changes previously established with a call to the IMSLogon::Advise method.

Quick Info

See IMSLogon : IUnknown.

HRESULT Unadvise(

ULONG ulConnection
)
Parameters

ulConnection

[in] Number of the registration connection returned by a call to IMSLogon::Advise.

Return Value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Message store providers implement the IMSLogon::Unadvise method to release the pointer to the advise sink object passed in the lpAdviseSink parameter in the previous call to IMSLogon::Advise, thereby canceling a notification registration. As part of discarding the pointer to the advise sink object, the object’s IUnknown::Release method is called. Generally, Release is called during the Unadvise call, but if another thread is in the process of calling the IMAPIAdviseSink::OnNotify method for the advise sink object, the Release call is delayed until the OnNotify method returns.

See Also

IMAPIAdviseSink::OnNotify, IMSLogon::Advise


IMSProvider : IUnknown

The IMSProvider interface provides access to a message store provider through a message store provider object. This message store provider object is returned at provider logon by the message store provider’s MSProviderInit entry point function. The message store provider object is primarily used by client applications and the MAPI spooler to open message stores.

Quick Info

Header file:	MAPISPI.H
Exposed by:	Message store provider objects
Implemented by:	Message store providers
Called by:	MAPI and the MAPI spooler
Corresponding pointer type:	LPMSPROVIDER
Vtable Order

Shutdown	Closes down a message store provider in an orderly fashion.
Logon	Logs MAPI on to one instance of a message store provider.
SpoolerLogon	Logs the MAPI spooler on to a message store.
CompareStoreIDs	Compares two message store entry identifiers to determine if they refer to the same store object.
Remarks

MAPI uses one message store provider object for all the message stores opened by the store provider implementing the object for the current MAPI session. If a second MAPI session logs onto any open stores, MAPI calls MSProviderInit a second time to create a new message store provider object for that session to use.

A message store provider object must contain the following to operate correctly:

•	An lpMalloc memory-allocation pointer for use by all stores opened using this provider object.

•	The lpfAllocateBuffer, lpfAllocateMore, and lpfFreeBuffer routine pointers to the MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer memory allocation functions.

•	A linked list of all the stores opened using this provider object and not yet closed.


IMSProvider::CompareStoreIDs

The IMSProvider::CompareStoreIDs method compares two message store entry identifiers to determine if they refer to the same store object.

Quick Info

See IMSProvider : IUnknown.

HRESULT CompareStoreIDs(

ULONG cbEntryID1,
LPENTRYID lpEntryID1,
ULONG cbEntryID2,
LPENTRYID lpEntryID2,
ULONG ulFlags,
ULONG FAR * lpulResult
)
Parameters

cbEntryID1

[in] Size, in bytes, of the entry identifier pointed to by the lpEntryID1 parameter.

lpEntryID1

[in] Pointer to the first entry identifier to be compared.

cbEntryID2

[in] Size, in bytes, of the entry identifier pointed to by the lpEntryID2 parameter.

lpEntryID2

[in] Pointer to the second entry identifier to be compared.

ulFlags

Reserved; must be zero.

lpulResult

[out] Pointer to the returned result of the comparison; this variable is TRUE if the two entry identifiers refer to the same object, and FALSE otherwise.

Return Value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

MAPI calls the IMSProvider::CompareStoreIDs method while processing a call to the IMAPISession::OpenMsgStore method. CompareStoreIDs is called at this point to determine which profile section, if any, is associated with the message store being opened. A CompareStoreIDs call can be made when no message stores are open for a particular store provider. In addition, MAPI also calls CompareStoreIDs while processing a store provider call to the IMAPISupport::OpenProfileSection method.

The entry identifiers compared by CompareStoreIDs are both for the current store provider’s dynamic-link library (DLL) and are both unwrapped store entry identifiers. For more information on wrapping store entry identifiers, see IMAPISupport::WrapStoreEntryID.

Comparing entry identifiers is useful because an object can have more than one valid entry identifier; such a situation can occur, for example, after a new version of a message store provider is installed.

See Also

IMAPISession::OpenMsgStore, IMAPISupport::OpenProfileSection, IMAPISupport::WrapStoreEntryID


IMSProvider::Logon

The IMSProvider::Logon method logs MAPI on to one instance of a message store provider.

Quick Info

See IMSProvider : IUnknown.

HRESULT Logon(

LPMAPISUP lpMAPISup,
ULONG ulUIParam,
LPTSTR lpszProfileName,
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulFlags,
LPCIID lpInterface,
ULONG FAR * lpcbSpoolSecurity,
LPBYTE FAR * lppbSpoolSecurity,
LPMAPIERROR FAR * lppMAPIError,
LPMSLOGON FAR * lppMSLogon,
LPMDB FAR * lppMDB
)
Parameters

lpMAPISup

[in] Pointer to the current MAPI support object for the message store.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays.

lpszProfileName

[in] Pointer to a string containing the name of the profile being used for store provider logon. This string can be displayed in dialog boxes, written out to a log file, or simply ignored. It must be in Unicode format if the MAPI_UNICODE flag is set in the ulFlags parameter.

cbEntryID

[in] Size, in bytes, of the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier for the message store. Passing NULL in lpEntryID indicates that a message store has not yet been selected and that dialog boxes enabling the user to select a message store can be presented.

ulFlags

[in] Bitmask of flags that controls how the logon is performed. The following flags can be set:

MAPI_DEFERRED_ERRORS

The call is allowed to succeed even if the underlying object is not accessible to the calling implementation. If the object is not accessible, some subsequent call to the object might return an error.

MAPI_UNICODE

The passed-in strings are in Unicode format. If MAPI_UNICODE is not set, the strings are in ANSI format.

MDB_NO_DIALOG

Prevents display of logon dialog boxes. If this flag is set, the error value MAPI_E_LOGON_FAILED is returned if logon is unsuccessful. If this flag is not set, the message store provider can prompt the user to correct a name or password, to insert a disk, or to perform other actions necessary to establish connection to the store.

MDB_NO_MAIL

The message store should not be used for sending or receiving mail. The flag signals MAPI not to notify the MAPI spooler that this message store is being opened. If this flag is set, and the message store is tightly coupled with a transport provider, then the provider does not need to call the IMAPISupport::SpoolerNotify method.

MDB_TEMPORARY

Logs on the store so that information can be retrieved programmatically from the profile section, without use of dialog boxes. This flag instructs MAPI that the store is not to be added to the message store table and that the store cannot be made permanent. If this flag is set, message store providers do not need to call the IMAPISupport::ModifyProfile method.

MDB_WRITE

Requests read/write access.

lpInterface

[in] Pointer to the interface identifier (IID) for the message store to log on to. Passing NULL indicates the MAPI interface for the message store is returned — that is, the IMsgStore interface. The lpInterface parameter can also be set to an identifier for an appropriate interface for the message store, for example IID_IUnknown or IID_IMAPIProp.

lpcbSpoolSecurity

[out] Pointer to the variable where the store provider returns the size, in bytes, of the validation data in the lppbSpoolSecurity parameter.

lppbSpoolSecurity

[out] Pointer to the pointer to the returned validation data. This validation data is provided so the IMSProvider::SpoolerLogon method can log the MAPI spooler on to the same store as the message store provider.

lppMAPIError

[out] Pointer to a pointer to the returned MAPIERROR structure, if any, containing version, component, and context information for an error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

lppMSLogon

[out] Pointer to the pointer to the message store logon object for MAPI to log on to.

lppMDB

[out] Pointer to the pointer to the message store object for the MAPI spooler and client applications to log on to.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_FAILONEPROVIDER

This provider cannot log on, but this error should not disable the service.

MAPI_E_LOGON_FAILED

A logon session could not be established.

MAPI_E_UNCONFIGURED

The profile does not contain enough information for the logon to complete. When this value is returned, MAPI calls the message store provider’s message-service entry point function.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

MAPI_E_UNKNOWN_CPID

The server is not configured to support the client's code page.

MAPI_E_UNKNOWN_LCID

The server is not configured to support the client's locale information.

MAPI_W_ERRORS_RETURNED

The call succeeded, but the message store provider has error information available. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.To get the error information from the provider, call the IMAPISession::GetLastError method.

Remarks

MAPI calls the IMSProvider::Logon method to do the majority of processing necessary to obtain access to a message store. Message store providers validate any user credentials necessary to access a particular store and return a message store object in the lppMDB parameter that the MAPI spooler and client applications can log onto.

In addition to the message store object returned for client and MAPI spooler use, the provider also returns a message store logon object for MAPI’s use in controlling the opened store. The message store logon object and the message store object should be tightly linked inside the message store provider so each can affect the other. Usage of the store object and the logon object should be identical; there should be a one-to-one correspondence between the logon object and the store object such that the objects act as if they are one object exposing two interfaces. The two objects should also be created together and freed together.

The MAPI support object, created by MAPI and passed to the provider in the lpMAPISup parameter, provides access to functions in MAPI required by the provider. These include functions that save and retrieve profile information, access address books, and so on. The lpMAPISup pointer can be different for each store that is opened. While processing calls for a message store after logon, the store provider should use the lpMAPISup variable specific to that store. For any Logon call that opens a message store and succeeds in creating a message store logon object, the provider must save a pointer to the MAPI support object in the store logon object and must call the IUnknown::AddRef method to add a reference for the support object.

The ulUIParam parameter should be used if the provider presents dialog boxes during the Logon call. However, dialog boxes should not be presented if ulFlags contains the MDB_NO_DIALOG flag. If a user interface is called but ulFlags does not allow it, or if for some other reason a user interface cannot be displayed, the provider should return MAPI_E_LOGON_FAILED. If Logon displays a dialog box and the user cancels logon, typically by clicking the dialog box’s Cancel button, the provider should return MAPI_E_USER_CANCEL.

The lpEntryID parameter can either be NULL or point to an unwrapped store entry identifier previously created by this message store. If lpEntryID points to an unwrapped entry identifier, that entry identifier can come from one of several places:

•	It can be an entry identifier that the store provider previously wrapped and wrote to the profile section as a PR_ENTRYID property.

•	It can be an entry identifier that the provider previously wrapped and returned to a calling client as a PR_STORE_ENTRYID property.

•	It can be an entry identifier that the provider previously wrapped and returned to a calling client as the PR_ENTRYID property of a message store object.

In any of these cases, it is possible that the entry identifier was created on a different computer than the one currently being used.

When lpEntryID is not NULL, it should contain all of the information needed to identify and locate the message store. This information can include network volume names, phone numbers, user account names, and so on. If the connection to the store cannot be made using the data in the entry identifier, then the store provider should display a dialog box that enables the user to select the store to be opened. A dialog box might be required, for example, if a server has been renamed, an account name has changed, or portions of the network are not running.

When lpEntryID is NULL, the message store to use has not yet been selected. The provider can still access a store without displaying a dialog box if it supports further methods to specify the store. For example, the provider can check its initialization file, or it can look for additional properties that were placed in its or its message service’s profile section at configuration.

If a provider finds that all the required information is not in the profile, it should return MAPI_E_UNCONFIGURED so that MAPI calls the provider’s message service entry point function to enable the user to select a store, or even to create one, and to enter an account name and password as needed. MAPI automatically creates a new profile section for a new store; this new profile section can be temporary or permanent, depending on how it has been added. If the store provider calls the IMAPISupport::ModifyProfile method, the new profile section becomes permanent and the store is added to the list of message stores returned by the IMAPISession::GetMsgStoresTable method.

The lpInterface parameter specifies the IID of the interface required for the newly opened store object. Passing NULL in lpInterface specifies that the MAPI message store interface, IMsgStore, is required. Passing the message store object, IID_IMsgStore, also specifies that IMsgStore is required. If IID_IUnknown is passed in lpInterface, the provider should open the store using whatever interface derived from IUnknown that is best for the provider; again, this is typically IMsgStore. When IID_IUnknown is passed, after the store open operation succeeds the calling implementation uses the IUnknown::QueryInterface method to select an interface.

The IMSProvider::Logon call should return sufficient information, such as a path to the store and credentials for accessing the store, to allow the MAPI spooler to log onto the same store the store provider does without presenting a dialog box. The parameters lpcbSpoolSecurity and lppbSpoolSecurity are used to return this information. The provider allocates the memory for this data by passing a pointer to a buffer in the MSProviderInit function’s lpfAllocateBuffer parameter; the provider places the size of this buffer in lpcbSpoolSecurity.

MAPI frees this buffer when appropriate. If the MAPI spooler’s logon to the store can be accomplished from the information in the profile section alone, the provider can return NULL in lppbSpoolSecurity and zero for the information’s size in lpcbSpoolSecurity. The MAPI spooler logon occurs as part of a different process than the store logon; because the buffer holding the passed information gets copied between processes, it might not be in memory at the same location for the MAPI spooler process as for the store provider process. Therefore, a provider shouldn’t put addresses into this buffer. For more information on MAPI spooler logon, see IMSProvider::SpoolerLogon.

Most store providers use the IMAPISession::OpenProfileSection method of the support object passed in the lpMAPISup parameter for saving and retrieving user credentials and options. OpenProfileSection enables a store provider to save additional arbitrary information in a profile section and associate it with logon for a particular resource. For example, a store provider can save the user account name and password associated with a resource and any paths or other necessary information needed to access that resource for its logon.

Properties with property identifiers 0x6600 through 0x67FF are secure properties available to the provider for its own use to store private data in profile sections. For more information on the uses of properties in profile section objects, see IProfSect : IMAPIProp.

In addition to any private data in properties with identifiers 0x6600 through 0x67FF, the store provider should provide information for the PR_DISPLAY_NAME property in its profile section. It should place in PR_DISPLAY_NAME the display name of the provider itself — an identifying string displayed to users so they can distinguish this message store from others they might have access to — for example, Microsoft Personal Information Store. PR_DISPLAY_NAME commonly contains a server name, user account name, or path.

Some profile section properties are visible in the message store table; others are visible during setup, installation, and configuration of the MAPI subsystem. The provider typically provides information for these visible properties both for a new profile section, which does not yet include saved credentials or private information, and when it finds that property information has changed. For more information on profile sections, see IMAPISupport::OpenProfileSection.

After successfully logging on a user, and before returning to MAPI, the store provider should create the array of properties for the status row for the resource and call IMAPISupport::ModifyStatusRow.

Logon calls that open message stores already open for the current MAPI session skip much of the processing described previously. These calls do not create status rows, do not return message store logon objects, do not call AddRef for the MAPI support object, and do not return data for MAPI spooler logon. These calls do return S_OK and do return a message store object with the interface requested.

To detect such calls, the provider should maintain a list in the message store provider object of stores already open for this provider object. When processing a Logon call, the provider should scan this list of open stores and determine if the store to be logged onto is already open. If it is, user credentials do not need to be checked and dialog box display should be avoided if possible. If dialog boxes must be displayed, the provider should check information returned to see whether a store has been opened a second time. In addition, the provider should check for duplicate openings using lpEntryID at the beginning of Logon call processing.

Standard processing for a Logon call that accesses an open store is as follows:

1.	The store provider calls AddRef for the existing store object if the new interface being requested is the same as the interface for the existing store. Otherwise, it calls QueryInterface to get the new interface. If the new interface isn’t one the store supports, the provider should return the error value MAPI_E_INTERFACE_NOT_SUPPORTED.

2.	The provider returns a pointer to the required interface of the existing store object in lppMDB.

3.	The provider returns NULL in lppMSLogon.

4.	The provider should not open the profile for the support object passed in the call. Neither should it register a provider unique identifier, register a status row, nor return MAPI spooler logon data.

5.	The provider should not call AddRef for the support object, because it does not require a pointer to the object.

Whenever possible, providers should return appropriate error and warning strings for Logon calls because doing so greatly eases the burden of users in figuring out why something did not work. To do so, a provider sets the members in the MAPIERROR structure. MAPI looks for, uses, and releases the MAPIERROR structure if it is returned by a provider.

Memory for this MAPIERROR should be allocated using the buffer passed in lpfAllocateBuffer on the MSProviderInit call. Any error strings contained in the returned structure should be in Unicode format if MAPI_UNICODE is set in the Logon ulFlags; otherwise, they should be in the ANSI character set.

For most error values returned from Logon, MAPI disables the message services to which the failing provider belongs. MAPI will not call any providers belonging to those services for the rest of the life of the MAPI session. In contrast, when Logon returns the MAPI_E_FAILONEPROVIDER error value from its logon, MAPI does not disable the message service to which the provider belongs. Logon should return MAPI_E_FAILONEPROVIDER if it encounters an error that does not warrant disabling the entire service for the life of the session. For example, a provider might return this error when it does not allow the display of a user interface and a required password is unavailable.

If a provider returns MAPI_E_UNCONFIGURED from its logon, MAPI will call the provider’s message service entry function and then retry the logon. MAPI passes MSG_SERVICE_CONFIGURE as the context, to give the service a chance to configure itself. If the client has chosen to allow a user interface on the logon, the service can present its configuration property sheet so the user can enter configuration information.

See Also

IMAPISession::GetMsgStoresTable, IMAPISession::OpenMsgStore, IMAPISession::OpenProfileSection, IMAPISupport::ModifyProfile, IMAPISupport::ModifyStatusRow, IMsgStore : IMAPIProp, IMSProvider::SpoolerLogon, IProfSect : IMAPIProp, MAPIERROR, MSProviderInit


IMSProvider::Shutdown

The IMSProvider::Shutdown method closes down a message store provider in an orderly fashion.

Quick Info

See IMSProvider : IUnknown.

HRESULT Shutdown(

ULONG FAR * lpulFlags
)
Parameters

lpulFlags

Reserved; must be a pointer to zero.

Return Value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

MAPI calls the IMSProvider::Shutdown method just before releasing the message store provider object. MAPI releases all logon objects for a provider before calling Shutdown for that provider.


IMSProvider::SpoolerLogon

The IMSProvider::SpoolerLogon method logs the MAPI spooler onto a message store.

Quick Info

See IMSProvider : IUnknown.

HRESULT SpoolerLogon(

LPMAPISUP lpMAPISup,
ULONG ulUIParam,
LPTSTR lpszProfileName,
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulFlags,
LPCIID lpInterface,
ULONG cbSpoolSecurity,
LPBYTE lpbSpoolSecurity,
LPMAPIERROR FAR * lppMAPIError,
LPMSLOGON FAR * lppMSLogon,
LPMDB FAR * lppMDB
)
Parameters

lpMAPISup

[in] Pointer to the MAPI support object for the message store.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays.

lpszProfileName

[in] Pointer to a string containing the name of the profile being used for the MAPI spooler logon. This string can be displayed in dialog boxes, written out to a log file, or simply ignored. It must be in Unicode format if the MAPI_UNICODE flag is set in the ulFlags parameter.

cbEntryID

[in] Size, in bytes, of the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier for the message store. Passing NULL in the lpEntryID parameter indicates that a message store has not yet been selected and that dialog boxes enabling the user to select a message store can be presented.

ulFlags

[in] Bitmask of flags that controls how the logon is performed. The following flags can be set:

MAPI_DEFERRED_ERRORS

The call is allowed to succeed even if the underlying object is not accessible to the calling implementation. If the object is not accessible, some subsequent call to the object might return an error.

MAPI_UNICODE

The passed-in strings are in Unicode format. If MAPI_UNICODE is not set, the strings are in ANSI format.

MDB_NO_DIALOG

Prevents display of logon dialog boxes. If this flag is set, the error value MAPI_E_LOGON_FAILED is returned if logon is unsuccessful. If this flag is not set, the message store provider can prompt the user to correct a name or password, to insert a disk, or to perform other actions necessary to establish connection to the store.

MDB_WRITE

Requests read/write access.

lpInterface

[in] Pointer to the interface identifier (IID) for the message store to log on to. Passing NULL indicates the MAPI interface for the message store is returned — that is, the IMsgStore interface. The lpInterface parameter can also be set to an identifier for an appropriate interface for the message store, for example IID_IUnknown or IID_IMAPIProp.

cbSpoolSecurity

[in] Pointer to the size, in bytes, of validation data in the lppbSpoolSecurity parameter.

lpbSpoolSecurity

[in] Pointer to a pointer to validation data. The SpoolerLogon method uses this data to log the MAPI spooler on to the same store as the message store provider previously logged on to using the IMSProvider::Logon method.

lppMAPIError

[out] Pointer to a pointer to the returned MAPIERROR structure, if any, containing version, component, and context information for an error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

lppMSLogon

[out] Pointer to the pointer to the message store logon object for MAPI to log on to.

lppMDB

[out] Pointer to the pointer to the message store object for the MAPI spooler and client applications to log on to.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_UNCONFIGURED

The profile does not contain enough information for the logon to complete. When this value is returned, MAPI calls the message store provider’s message service entry point function.

MAPI_W_ERRORS_RETURNED

The call succeeded, but the message store provider has error information available. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling. To get the error information from the provider, call the IMAPISession::GetLastError method.

Remarks

The MAPI spooler calls the IMSProvider::SpoolerLogon method to log on to a message store. The MAPI spooler should use the message store object returned by the message store provider in the lppMDB parameter during and after logon.

For consistency with the IMSProvider::Logon method, the provider also returns a message store logon object in the lppMSLogon parameter. Usage of the store object and the logon object are identical for usual store logon, because there is a one-to-one correspondence between the logon object and the store object; you can think of the logon and store objects as one object exposing two interfaces. The two objects are created together and freed together.

The store provider should internally mark the returned message store object to indicate that the store is being used by the MAPI spooler. Some of the methods for this store object behave differently than for the message store object provided to client applications. Keeping this internal mark is the most common way of triggering the behavior specific to the MAPI spooler.

See Also

IMSProvider::Logon, MAPIERROR


IPersistMessage : IUnknown

The IPersistMessage interface is implemented by form objects to save, initialize, and load messages to and from forms. IPersistMessage works similarly to the OLE IPersistStorage interface; for more information on the IPersistStorage methods, and on working with storage objects in general, see the OLE Programmer’s Reference.

Quick Info

Header file:	MAPIFORM.H
Exposed by:	Persist message objects
Implemented by:	Form objects
Called by:	Form viewers
Corresponding pointer type:	LPPERSISTMESSAGE
Vtable Order

GetLastError	Returns a MAPIERROR structure containing information about the last error that occurred in a form’s message object.
GetClassID	Returns a form’s message class identifier.
IsDirty	Checks a form for changes made since the form was last saved.
InitNew	Provides a form with a base message on which to build a new message.
Load	Loads a form from a specified message.
Save	Saves a revised form back to the message from which it was loaded or created.
SaveCompleted	Returns a message to a form after a save, submission, or other operation.
HandsOffMessage	Causes a form to release its message object.


IPersistMessage::GetClassID

The IPersistMessage::GetClassID method returns a form’s message class identifier.

Quick Info

See IPersistMessage : IUnknown.

HRESULT GetClassID(

LPCLSID lpClassID
)
Parameters

lpClassID

[in] Pointer to the returned class identifier.

Return Value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

For more information on working with class identifiers of storage objects, see the documentation for the IPersistStorage methods in the OLE Programmer’s Reference.


IPersistMessage::GetLastError

The IPersistMessage::GetLastError method returns a MAPIERROR structure containing information about the last error that occurred in a form's message object.

Quick Info

See IPersistMessage : IUnknown.

HRESULT GetLastError(

HRESULT hResult,
ULONG ulFlags,
LPMAPIERROR FAR * lppMAPIError
)
Parameters

hResult

[in] HRESULT data type containing the error value generated in the previous method call for the message object.

ulFlags

[in] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] Pointer to a pointer to the returned MAPIERROR structure containing version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

Remarks

Use the IMAPITable::GetLastError method to retrieve information to display in a message to the user regarding the last error returned from a method call for a form's message object.

To release all the memory allocated by MAPI for the MAPIERROR structure, implementations need only call the MAPIFreeBuffer function.

The return value from GetLastError must be S_OK for an implementation to make use of the MAPIERROR structure. Even if the return value is S_OK, a MAPIERROR structure might not be returned. If the implementation cannot determine what the last error was, or if a MAPIERROR structure is not available for that error, GetLastError returns a pointer to NULL in lppMAPIError instead.

See Also

MAPIERROR, MAPIFreeBuffer


IPersistMessage::HandsOffMessage

The IPersistMessage::HandsOffMessage method causes a form to release its message object.

Quick Info

See IPersistMessage : IUnknown.

HRESULT HandsOffMessage()

Parameters

None

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

For more information on working with the hands-off state of storage objects, see the OLE Programmer’s Reference.


IPersistMessage::InitNew

The IPersistMessage::InitNew method provides a form with a base message on which to build a new message.

Quick Info

See IPersistMessage : IUnknown.

HRESULT InitNew(

LPMAPIMESSAGESITE pMessageSite,
LPMESSAGE pMessage
)
Parameters

pMessageSite

[in] Pointer to the message site the form uses to compose a new message.

pMessage

[in] Pointer to the message the form uses to compose a new message.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IPersistMessage::InitNew method to set up a form with a message site and a message so as to compose a new message within the form. When a message is loaded into a form with InitNew, you can assume that the following required properties, and no others, have been set by form server implementations:

PR_DELETE_AFTER_SUBMIT

PR_IMPORTANCE

PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED

PR_PRIORITY

PR_READ_RECEIPT_REQUESTED

PR_SENSITIVITY

PR_SENTMAIL_ENTRYID

For more information on initializing new storage objects, see the OLE Programmer’s Reference.


IPersistMessage::IsDirty

The IPersistMessage::IsDirty method checks a form for changes made since the form was last saved.

Quick Info

See IPersistMessage : IUnknown.

HRESULT IsDirty()

Parameters

None

Return Values

S_OK

The form has had changes made since it was last saved.

S_FALSE

The form has not had changes made since it was last saved.

Remarks

For more information, see the documentation for the IPersistStorage methods in the OLE Programmer’s Reference.


IPersistMessage::Load

The IPersistMessage::Load method loads a form from a specified message.

Quick Info

See IPersistMessage : IUnknown.

HRESULT Load(

LPMESSAGESITE pMessageSite,
LPMESSAGE pMessage,
ULONG ulMessageStatus,
ULONG ulMessageFlags
)
Parameters

pMessageSite

[in] Pointer to the specified message to be loaded.

pMessage

[in] Pointer to the message from which the message is loaded.

ulMessageStatus

[in] Bitmask of client-defined or provider-defined flags — copied from the message’s PR_MSG_STATUS property — that provides information on the state of the message.

ulMessageFlags

[in] Bitmask of flags — copied from the message’s PR_MESSAGE_FLAGS property — that provide further information on the state of the message.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IPersistMessage::Load method to load a form from a specified message. Load is used to read an existing message. Flags and status bits set in the existing message’s PR_MESSAGE_FLAGS and PR_MSG_STATUS properties are preserved in the new message.

For more information on loading storage objects, see the OLE Programmer’s Reference.

See Also

PR_MESSAGE_FLAGS, PR_MSG_STATUS


IPersistMessage::Save

The IPersistMessage::Save method saves a revised form back to the message from which it was loaded or created.

Quick Info

See IPersistMessage : IUnknown.

HRESULT Save(

LPMESSAGE pMessage,
ULONG fSameAsLoad
)
Parameters

pMessage

[in] Pointer to a message.

fSameAsLoad

[in] Variable that is TRUE if the message the pMessage parameter points to is the message from which the form was loaded or created, and FALSE otherwise.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IPersistMessage::Save method to save a revised form back to the message from which it was loaded or created. The form must not commit changes to this message; changes are committed by the form server implementation that calls Save.

For more information on saving storage objects, see the documentation on the IPersistStorage methods in the OLE Programmer’s Reference.


IPersistMessage::SaveCompleted

The IPersistMessage::SaveCompleted method returns a message to a form after a save, submission, or other operation.

Quick Info

See IPersistMessage : IUnknown.

HRESULT SaveCompleted(

LPMESSAGE pMessage
)
Parameters

pMessage

[in] Pointer to the message that was acted upon.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IPersistMessage::SaveCompleted method at the end of a save request or after the failure of a dismissive operation such as a save operation or deletion. SaveCompleted returns the saved message to the form in which it was composed. Note that there is no reason to suppose the IPersistMessage interface used is the same interface as held for the message at the beginning of the save or other operation. However, the interface is for the same message object.

For more information on saving storage objects, see the documentation on the IPersistStorage methods in the OLE Programmer’s Reference.


IProfAdmin : IUnknown

The IProfAdmin interface supports the administration of profiles.

Quick Info

Header file:	MAPIX.H
Exposed by:	Profile administration object
Implemented by:	MAPI
Called by:	Client applications
Corresponding pointer type:	LPPROFADMIN
Vtable Order

GetLastError	Returns a MAPIERROR structure containing information about the previous error occurring to a profile administration object.
GetProfileTable	Provides access to the profile table, a table with information about all of the available profiles.
CreateProfile	Creates a new profile.
DeleteProfile	Deletes a profile.
ChangeProfilePassword	Changes the password for a profile.
CopyProfile	Copies a profile.
RenameProfile	Assigns a new name to a profile.
SetDefaultProfile	Sets or clears a client’s default profile.
AdminServices	Provides access to a message service administration object for making changes to the message services in a profile.


IProfAdmin::AdminServices

The IProfAdmin::AdminServices method provides access to a message service administration object for making changes to the message services in a profile.

Quick Info

See IProfAdmin : IUnknown.

HRESULT AdminServices(

LPTSTR lpszProfileName,
LPTSTR lpszPassword,
ULONG ulUIParam,
ULONG ulFlags,
LPSERVICEADMIN FAR * lppServiceAdmin
)
Parameters

lpszProfileName

[in] Pointer to the name of the profile to be modified. The lpszProfileName parameter must not be NULL.

lpszPassword

[in] Pointer to the profile’s password or NULL, if the profile does not require a password. If lpszPassword is NULL, the profile requires a password, and the MAPI_DIALOG flag is set in the ulFlags parameter, a dialog box is displayed to prompt the user for the password.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays.

ulFlags

[in] Bitmask of flags that controls the retrieval of the message service administration object. The following flags can be set:

MAPI_DIALOG

Allows the display of a user interface.

MAPI_UNICODE

The profile name and password are in the Unicode format. If the MAPI_UNICODE flag is not set, they are in the ANSI format.

lppServiceAdmin

[out] Pointer to a pointer to a message service administration object.

Return Values

S_OK

The message service administration object was successfully returned.

MAPI_E_LOGON_FAILED

The specified profile doesn’t exist, or the password was wrong and a dialog box could not be displayed to the user requesting the correct password because MAPI_DIALOG was not set in ulFlags.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The IProfAdmin::AdminServices method provides access to a message service administration object for making configuration changes to the message services within a profile.

Profile passwords are not supported on all operating system platforms. On platforms that do not support profile passwords, lpszPassword can be NULL or a pointer to a zero-length string. Currently, Microsoft Windows NT and Microsoft Windows 95 do not support passwords; Microsoft Windows version 3.1 does.

Notes to Callers

Although you retrieve an IMsgServiceAdmin pointer by calling either this method or IMAPISession::AdminServices to retrieve an IMsgServiceAdmin pointer, call this method if you are a strictly a configuration client and offer no messaging features. The IProfAdmin method does not create a session object and does not load any service providers, enhancing performance.

IProfAdmin::AdminServices cannot be used to create a profile. Therefore, you must specify an existing valid profile in lpszProfileName. If the specified profile does not exist, AdminServices returns MAPI_E_LOGON_FAILED.

The name of the profile and its password can be up to 64 characters in length and can include the following characters:

•	All alphanumeric characters, including accent characters and the underscore character.

•	Embedded spaces, but not leading or trailing spaces.

See Also

IMAPISession::AdminServices


IProfAdmin::ChangeProfilePassword

The IProfAdmin::ChangeProfilePassword method changes the password for a profile.

Quick Info

See IProfAdmin : IUnknown.

HRESULT ChangeProfilePassword(

LPTSTR lpszProfileName,
LPTSTR lpszOldPassword,
LPTSTR lpszNewPassword,
ULONG ulFlags
)
Parameters

lpszProfileName

[in] Pointer to the name of the profile associated with the password to be changed.

lpszOldPassword

[in] Pointer to the current password.

lpszNewPassword

[in] Pointer to the new password.

ulFlags

[in] Bitmask of flags that controls the type of the passed-in strings. The following flag can be set:

MAPI_UNICODE

The profile name and passwords are in the Unicode format. If the MAPI_UNICODE flag is not set, these strings are in the ANSI format.

Return Values

S_OK

The profile’s password was successfully changed.

MAPI_E_LOGON_FAILED

The password pointed to by lpszOldPassword is incorrect.

MAPI_E_NO_SUPPORT

The operating system does not support passwords.

Remarks

The IProfAdmin::ChangeProfilePassword method replace one profile password with another. ChangeProfilePassword does not display a user interface.

Not all operating systems support passwords for their profiles. ChangeProfilePassword returns MAPI_E_NO_SUPPORT if the operating system does not support passwords. Currently, Windows NT Server and Windows 95 do not support passwords; Windows version 3.1 does.


IProfAdmin::CopyProfile

The IProfAdmin::CopyProfile method copies a profile.

Quick Info

See IProfAdmin : IUnknown.

HRESULT CopyProfile(

LPTSTR lpszOldProfileName,
LPTSTR lpszOldPassword,
LPTSTR lpszNewProfileName,
ULONG ulUIParam,
ULONG ulFlags
)
Parameters

lpszOldProfileName

[in] Pointer to the name of the profile to copy.

lpszOldPassword

[in] Pointer to the password of the profile to copy.

lpszNewProfileName

[in] Pointer to the name of the profile copy.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays.

ulFlags

[in] Bitmask of flags that controls how the profile is copied. The following flags can be set:

MAPI_DIALOG

Allows the display of a dialog box prompting the user for the correct password of the profile to copy. If this flag is not set, no dialog box is displayed.

MAPI_UNICODE

The profile names and password are in the Unicode format. If the MAPI_UNICODE flag is not set, these strings are in the ANSI format.

Return Values

S_OK

The profile was successfully copied.

MAPI_E_ACCESS_DENIED

The new profile name is the same as that of an existing profile.

MAPI_E_LOGON_FAILED

The password for the profile to copy is incorrect, and a dialog box could not be displayed to the user requesting the correct password because MAPI_DIALOG was not set in the ulFlags parameter.

MAPI_E_NOT_FOUND

The specified profile does not exist.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The IProfAdmin::CopyProfile method makes a copy of the profile pointed to by lpszOldProfileName, giving it the name pointed to by lpszNewProfileName. Copying a profile leaves the copy with the same password as the original.

The name of the original profile, its password, and the copy can be up to 64 characters in length and can include the following characters:

•	All alphanumeric characters, including accent characters and the underscore character.

•	Embedded spaces, but not leading or trailing spaces.

Profile passwords are not supported on all operating system platforms; on platforms that do not support profile passwords, lpszOldPassword can be NULL or a pointer to a zero-length string. Currently, Windows NT Server and Windows 95 do not support passwords; Windows version 3.1 does.

If lpszOldPassword is set to NULL, the profile to be copied requires a password, and the MAPI_DIALOG flag is set, a dialog box prompting the user to provide the password is displayed. If a password is required, but lpszOldPassword is set to NULL and the MAPI_DIALOG flag is not set, CopyProfile returns MAPI_E_LOGON_FAILED.


IProfAdmin::CreateProfile

The IProfAdmin::CreateProfile method creates a new profile.

Quick Info

See IProfAdmin : IUnknown.

HRESULT CreateProfile(

LPTSTR lpszProfileName,
LPTSTR lpszPassword,
ULONG ulUIParam,
ULONG ulFlags
)
Parameters

lpszProfileName

[in] Pointer to the name of the new profile.

lpszPassword

[in] Pointer to the password of the new profile.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays.

ulFlags

[in] Bitmask of flags that controls how the profile is created. The following flags can be set:

MAPI_DEFAULT_SERVICES

Indicates that MAPI should populate the new profile with the message services that are included in the [Default Services] section of the MAPISVC.INF file.

MAPI_DIALOG

Indicates that the configuration property sheets of each of the providers in the message services to be added can be displayed.

MAPI_UNICODE

The profile name and password are in the Unicode format. If the MAPI_UNICODE flag is not set, these strings are in the ANSI format.

Return Values

S_OK

The new profile was created.

MAPI_E_NO_ACCESS

The specified new profile already exists.

Remarks

The IProfAdmin::CreateProfile method creates a new profile.

Notes to Callers

You can call CreateProfile at application installation time or at any time during a session. When called at installation time, many of the configuration settings come from the MAPISVC.INF configuration file. When called during an active session, the settings come from the user who is prompted through a series of property sheets.

If the MAPI_DEFAULT_SERVICES flag is set in the ulFlags parameter, CreateProfile calls the message service entry point function for each message service in the [Default Services] section in the MAPISVC.INF file. Each message service entry point function is called with the ulContext parameter set to MSG_SERVICE_CREATE.

If both the MAPI_DIALOG and MAPI_DEFAULT_SERVICES flags are set, then the values in the ulUIParam and ulFlags parameters are also passed to the message service entry point function. The message service entry point functions are only called after all available information from the MAPISVC.INF file has been added to the profile.

The name of the new profile and its password can be up to 64 characters in length and can include the following characters:

•	All alphanumeric characters, including accent characters and the underscore character.

•	Embedded spaces, but not leading or trailing spaces.

Profile passwords are not supported on all operating system platforms; on platforms that do not support profile passwords, lpszPassword can be NULL or a pointer to a zero-length string. Currently, Windows NT Server and Windows 95 do not support passwords; Windows version 3.1 does.

See Also

IMsgServiceAdmin::ConfigureMsgService, IMsgServiceAdmin::CreateMsgService, MSGSERVICEENTRY


IProfAdmin::DeleteProfile

The IProfAdmin::DeleteProfile method deletes a profile.

Quick Info

See IProfAdmin : IUnknown.

HRESULT DeleteProfile(

LPTSTR lpszProfileName,
ULONG ulFlags
)
Parameters

lpszProfileName

[in] Pointer to the name of the profile to be deleted.

ulFlags

[in] Bitmask of flags that controls the type of the profile name. The following flag can be set:

MAPI_UNICODE

The profile name is in the Unicode format. If the MAPI_UNICODE flag is not set, the profile name is in the ANSI format.

Return Values

S_OK

The profile was successfully deleted.

MAPI_E_NOT_FOUND

The specified profile does not exist.

Remarks

The IProfAdmin::DeleteProfile method deletes a profile. If the profile to delete is in use when DeleteProfile is called, DeleteProfile returns S_OK but does not delete the profile immediately. Instead, DeleteProfile marks the profile for deletion and deletes it after it is no longer being used, when all of its active sessions have ended.

The entry point function for each message service in the profile is called with the MSG_SERVICE_DELETE value set in the ulContext parameter. First the function deletes the service, and then it deletes the service’s profile section. The message service entry point function is not called again after the service has been deleted.

No password is required to delete a profile.

See Also

IMsgServiceAdmin::DeleteMsgService, MSGSERVICEENTRY


IProfAdmin::GetLastError

The IProfAdmin::GetLastError method returns a MAPIERROR structure containing information about the previous error occurring to a profile administration object.

Quick Info

See IProfAdmin : IUnknown.

HRESULT GetLastError(

HRESULT hResult,
ULONG ulFlags,
LPMAPIERROR FAR * lppMAPIError
)
Parameters

hResult

[in] HRESULT data type containing the containing the error code generated in the previous method call.

ulFlags

[in] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] Pointer to a pointer to the MAPIERROR structure containing version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

Remarks

The IProfAdmin::GetLastError method retrieves information about the last error returned from a method call for the profile administration object.

Notes to Callers

You can make use of the MAPIERROR structure pointed to by the lppMAPIError parameter, if MAPI supplies one, only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was or has nothing more to report about the error. In this situation, the a pointer to NULL is returned in lppMAPIError.

To release all the memory allocated by MAPI for the MAPIERROR structure, call the MAPIFreeBuffer function.

For more information about the GetLastError method, see Using Extended Errors.

See Also

MAPIERROR, MAPIFreeBuffer


IProfAdmin::GetProfileTable

The IProfAdmin::GetProfileTable method provides access to the profile table, a table with information about all of the available profiles.

Quick Info

See IProfAdmin : IUnknown.

HRESULT GetProfileTable(

ULONG ulFlags,
LPMAPITABLE FAR * lppTable
)
Parameters

ulFlags

[in] Bitmask of flags that controls the type of the strings returned in the table’s columns. The following flag can be set:

MAPI_UNICODE

The string columns are in Unicode format. If the MAPI_UNICODE flag is not set, the columns are in ANSI format.

lppTable

[out] Pointer to the pointer to the profile table.

Return Values

S_OK

The profile table was successfully retrieved.

Remarks

The IProfAdmin::GetProfileTable method provides access to the profile table, a table with one row for every available profile. There are only two columns in each row: the profile’s display name and a flag that indicates whether or not the profile is the default.

Profiles that have been deleted, or that are in use but have been marked for deletion, are not included in the profile table. The profile table is static; subsequent additions and deletions of profiles are not reflected in the table.

If no profiles exist, GetProfileTable returns a table with zero rows.

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the format of the columns returned from the following IMAPITable methods:

•	IMAPITable::QueryColumns

•	IMAPITable::QueryRows

This flag also controls the property types in the sort order returned by the IMAPITable::QuerySortOrder method.

For more information about the profile table, see Profile Table.

See Also

IMAPITable : IUnknown, MAPILogonEx


IProfAdmin::RenameProfile

The IProfAdmin::RenameProfile method assigns a new name to a profile.

Quick Info

See IProfAdmin : IUnknown.

HRESULT RenameProfile(

LPTSTR lpszOldProfileName,
LPTSTR lpszOldPassword,
LPTSTR lpszNewProfileName,
ULONG ulUIParam,
ULONG ulFlags
)
Parameters

lpszOldProfileName

[in] Pointer to the current name of the profile to rename.

lpszOldPassword

[in] Pointer to the password of the profile to rename or NULL, indicating that the profile does not require a password. However, if lpszOldPassword is set to NULL and the profile does require a password, RenameProfile displays a dialog box if possible to prompt the user.

lpszNewProfileName

[in] Pointer to the new name of the profile to rename.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays.

ulFlags

[in] Bitmask of flags that controls how the renaming operation is performed. The following flags can be set:

MAPI_DIALOG

Allows the display of a dialog box prompting the user for the profile’s password. If this flag is not set, no dialog box is displayed.

MAPI_UNICODE

The profile names and password are in the Unicode format. If the MAPI_UNICODE flag is not set, these strings are in the ANSI format.

Return Values

S_OK

The profile was successfully renamed.

MAPI_E_LOGON_FAILED

The profile password is incorrect.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The IProfAdmin::RenameProfile method assigns a new name to a profile without changing its password, if it has one. If the profile to rename is in use by a client when RenameProfile is called, RenameProfile marks the profile and returns S_OK rather than attempting the rename operation while the profile is in use. When the profile is no longer being used, RenameProfile assigns it the new name.

The old and new names of the profile and the password can be up to 64 characters in length and can include the following characters:

•	All alphanumeric characters, including accent characters and the underscore character.

•	Embedded spaces, but not leading or trailing spaces.

Profile passwords are not supported on all operating system platforms; on platforms that do not support profile passwords, lpszPassword can be NULL or a pointer to a zero-length string. Currently, Windows NT Server and Windows 95 do not support passwords; Windows version 3.1 does.

The MAPI_DIALOG flag must be set in order for RenameProfile to display a user interface. If a client passes NULL in lpszOldPassword and the target profile requires a password, a dialog box must be displayed to allow the user to supply the missing password. If MAPI_DIALOG is not set in this situation, RenameProfile returns MAPI_E_LOGON_FAILED.


IProfAdmin::SetDefaultProfile

The IProfAdmin::SetDefaultProfile method sets or clears a client’s default profile.

Quick Info

See IProfAdmin : IUnknown.

HRESULT SetDefaultProfile(

LPTSTR lpszProfileName,
ULONG ulFlags
)
Parameters

lpszProfileName

[in] Pointer to the name of the profile to become the default or NUL. Setting lpszProfileName to NULL indicates that SetDefaultProfile should remove the existing default profile, leaving the client without a default.

ulFlags

[in] Bitmask of flags that controls the type of the string pointed to by lpszProfileName. The following flag can be set:

MAPI_UNICODE

The profile name is in the Unicode format. If the MAPI_UNICODE flag is not set, the profile name is in the ANSI format.

Return Values

S_OK

A default profile was successfully established or removed.

MAPI_E_NOT_FOUND

The specified profile does not exist.

Remarks

The IProfAdmin::SetDefaultProfile method either establishes a particular profile as the client’s default profile or clears the current default profile. The default profile is the profile that is automatically used whenever the client begins a MAPI session. SetDefaultProfile also sets the new default profile’s PR_DEFAULT_PROFILE property to TRUE.

Notes to Callers

To start a session with the default profile, pass the MAPI_USE_DEFAULT flag to the MAPILogonEx function.

See Also

IProfAdmin::GetProfileTable, MAPILogonEx, PR_DEFAULT_PROFILE


IProfSect : IMAPIProp

The IProfSect interface is used to work with the properties of profile section objects.

Quick Info

Header file:	MAPIX.H
Exposed by:	Profile section objects
Implemented by:	MAPI
Called by:	Client applications and service providers
Corresponding pointer type:	LPPROFSECT
Transaction model:	Non-transacted
Vtable Order

No unique methods

Required properties	Access
PR_OBJECT_TYPE	Read-only
PR_PROFILE_NAME	Read-only
Notes to Callers

IProfSect does not have any unique methods of its own, but you can call the profile section’s IMAPIProp methods. There are some differences between the IProfSect implementation and other implementations of IMAPIProp:

•	IProfSect does not support a transaction model.

•	IProfSect does not support named properties.

•	IProfSect reserves the identifier range 0X67F0 to 0X67FF for secure properties.

Not supporting a transaction model means that all changes made to a profile section following calls to the IMAPIProp::CopyProps and IMAPIProp::CopyTo methods occur immediately. Calls to the IMAPIProp::SaveChanges method succeed, but don’t actually save any changes.

To protect from having changes occur prematurely, service providers need to make copies of their profile sections that are displayed to users through property sheets. The property sheets should work with the copy, rather than the real profile section. When the user has verified that the changes are accurate by choosing the OK button, the changes can be saved to the real profile section.

To implement a property sheet with a copied profile section

1.	Open the profile section by calling IMAPISupport::OpenProfileSection or IProviderAdmin::OpenProfileSection.

2.	Call CreateIProp to retrieve a property data object, an object that supports the IPropData interface.

3.	Call the profile section’s IMAPIProp::CopyTo method to copy the properties to appear on the property sheet from the profile section to the property data object.

4.	Call IMAPISupport::DoConfigPropSheet to request that the service provider display a property sheet and pass a pointer to the property data object in the lpConfigData parameter.

5.	When the user saves changes to configuration properties in the property sheet, call the IMAPIProp::CopyTo method to copy the properties from the property data object back to the profile section.

Profile sections, unlike other objects, do not support named properties. IMAPIProp::GetIDsFromNames and IMAPIProp::GetNamesFromIDs return MAPI_E_NO_SUPPORT if called on a profile section object. Attempts to set properties with identifiers in the range above 0x8000 with IMAPIProp::SetProps return PT_ERROR as the property type.

Profile sections reserve the identifier range 0X67F0 to 0X67FF for secure properties. Service providers can use this range to store passwords and other provider-specific credentials. Properties in this range are not returned in the complete list of properties when NULL is passed in the lpPropTag parameter of the IMAPIProp::GetProps method, nor are they returned in the lppPropTagArray parameter of the IMAPIProp::GetPropList method. Secure properties must be requested specifically by their identifiers.

MAPI furnishes a profile section with the hard-coded constant MUID_PROFILE_INSTANCE as its identifier and PR_SEARCH_KEY as its single property. The PR_SEARCH_KEY property is guaranteed by MAPI to be unique among all profiles created. Use this property rather than PR_PROFILE_NAME when uniqueness is important, because it is possible for a deleted profile to be succeeded by another profile with the same name.

For more information on using profile sections, see Profile Administration.


IPropData : IMAPIProp

The IPropData interface provides the ability to retrieve and change the access for an object’s properties. It is implemented by MAPI and used primarily by service providers that access this implementation by calling the API function, CreateIProp.

For more information about access levels on objects and properties, see Permissions for Objects and Properties.

Quick Info

Header file:	MAPIUTIL.H
Exposed by:	Property data object
Implemented by:	MAPI
Called by:	Service providers and client applications
Corresponding pointer type:	LPPROPDATA
Transaction model:	Non-transacted
Vtable Order

HrSetObjAccess	Sets the access level for the object.
HrSetPropAccess	Sets the access level and status for one or more of the object’s properties.
HrGetPropAccess	Retrieves the access level and status for one or more of the object’s properties.
HrAddObjProps	Adds one or more properties that are of type PT_OBJECT to the object.


IPropData::HrAddObjProps

The IPropData::HrAddObjProps method adds one or more properties that are of type PT_OBJECT to the object.

Quick Info

See IPropData : IMAPIProp.

HRESULT HrAddObjProps(

LPSPropTagArray lpPropTagArray,
LPSPropProblemArray FAR * lppProblems
)
Parameters

lpPropTagArray

[in] Pointer to an array of property tags indicating the properties to add.

lppProblems

[in, out] On input, a valid pointer to an SPropProblemArray structure or NULL. On output, a pointer to a pointer to a structure that holds information about properties that could not be added, or NULL. A pointer to a property problem array structure is returned only if a valid pointer is passed in.

Return Values

S_OK

The properties were successfully added.

MAPI_E_INVALID_TYPE

A property type other than PT_OBJECT was passed in the array pointed to by the lpPropTagArray parameter.

MAPI_E_NO_ACCESS

The object has been set not to allow read/write access.

MAPI_W_PARTIAL_COMPLETION

Some, but not all, of the properties were added.

Remarks

The IPropData::HrAddObjProps method adds one or more properties that are type PT_OBJECT to the object. HrAddObjProps provides an alternative to IMAPIProp::SetProps for object properties, since object properties can not be created by calling SetProps. Adding an object property results in the property tag being included in the list of property tags retrieved through IMAPIProp::GetPropList.

Notes to Callers

If HrAddObjProps returns MAPI_W_PARTIAL_COMPLETION and you have set lppProblems to a valid pointer, check the returned SPropProblemArray structure to find out which properties were not added. Typically, the only problem that occurs is lack of memory. Free the SPropProblemArray structure by calling the MAPIFreeBuffer function when you are finished with it.

To add a property, the target object must have read/write access. If HrAddObjProps returns MAPI_E_NO_ACCESS, this indicates that you cannot add properties to the object because it does not permit modification. To obtain read/write access to an object prior to calling HrAddObjProps, call IPropData::SetObjAccess and set the ulAccess parameter to IPROP_READWRITE.

See Also

MAPIFreeBuffer, SPropProblemArray, SPropTagArray


IPropData::HrGetPropAccess

The IPropData::HrGetPropAccess method retrieves the access level and status for one or more of the object’s properties.

Quick Info

See IPropData : IMAPIProp.

HRESULT HrGetPropAccess(

LPSPropTagArray FAR * lppPropTagArray,
ULONG FAR * FAR * lprgulAccess
)
Parameters

lppPropTagArray

[in, out] On input, contains either an array of property tags indicating the properties for which to retrieve access levels and status or a pointer to NULL, indicating that HrGetPropAccess should retrieve access levels and status for all properties.

On output, contains an array of property tags for which access and status flags were retrieved. The flags are stored in the array pointed to by lprgulAccess.

lprgulAccess

[out] Pointer to an array of bitmasks of flags. Each bitmask indicates the access levels and/or status for each of the properties identified in the array pointed to by lppPropTagArray. The two arrays are positional in that the first bitmask pointed to by lprgulAccess describes the first property pointed to by lppPropTagArray and so on.

For each property tag, the following flags can be set:

Access level flag	Status flag
IPROP_READONLY, indicating that the property can not be modified	IPROP_CLEAN, indicating that the property has not been modified.
IPROP_READWRITE, indicating that the property can be modified.	IPROP_DIRTY, indicating that the property has been modified.
Return Values

S_OK

The access level and status flags for the properties were successfully returned.

Remarks

The IPropData::HrGetPropAccess method retrieves a set of flags indicating the access level and status for one or more properties.

Notes to Callers:

HrGetPropAccess can be used:

•	To determine if a client has changed or deleted a writable property.

•	To prevent a client from changing or deleting a property using the IMAPIProp methods.

If one of the properties in the property tag array pointed to by lppPropTagArray has been deleted, HrGetPropAccess sets the array entry to zero on output. If you set lppPropTagArray to NULL and one of the object’s properties has been deleted, the deleted property is returned in the array.

If a property has been modified, its IPROP_DIRTY flag is set in the corresponding entry in the array pointed to by lprgulAccess. Neither IPROP_READONLY or IPROP_READWRITE will be set.

If a property has not been modified or deleted, only an access level flag will be set: IPROP_READONLY or IPROP_READWRITE.

See Also

SPropTagArray


IPropData::HrSetObjAccess

The IPropData::HrSetObjAccess method sets the access level for the object.

Quick Info

See IPropData : IMAPIProp.

HRESULT HrSetObjAccess(

ULONG ulAccess
)
Parameters

ulAccess

[in] Bitmask of flags that specifies the object’s access level. One of the following flags can be set:

IPROP_READONLY

Sets the object’s access level to read-only.

IPROP_READWRITE

Sets the object’s access level to read/write.

Return Values

S_OK

The object’s access level was successfully set.

Remarks

The IPropData::HrSetObjAccess method sets the access level for an entire object, rather than for individual properties. HrSetObjAccess can be used to change the access level established when the object was created.

Notes to Callers

To set an access level on a property, first call HrSetObjAccess with the IPROP_READWRITE flag set in the ulAccess parameter to make the object modifiable. Then call IPropData::HrSetPropAccess, specifying the target property in the array pointed to by lpPropTagArray.

To create an object with properties that will be read-only to clients, create a read/write object, add the necessary properties, and then call HrSetObjAccess to change the object’s access to read-only.

HrSetObjAccess can also be used to prevent clients from creating new properties.

See Also

IPropData::HrGetPropAccess, IPropData::HrSetPropAccess


IPropData::HrSetPropAccess

The IPropData::HrSetPropAccess method sets the access level or status for one or more of the object’s properties.

Quick Info

See IPropData : IMAPIProp.

HRESULT HrSetPropAccess(

LPSPropTagArray lpPropTagArray,
ULONG FAR * rgulAccess
)
Parameters

lpPropTagArray

[in] Pointer to an array of property tags indicating the properties to be modified.

rgulAccess

[in] Array of bitmasks of flags. Each bitmask indicates the access levels and/or status for each of the properties identified in the array pointed to by lpPropTagArray. The two arrays are positional in that the first bitmask in rgulAccess describes the first property pointed to by lpPropTagArray and so on.

For each property tag, one access level flag and one status flag can be set. The choices are as follows:

Access level flag	Status flag
IPROP_READONLY, indicating that the property can not be modified	IPROP_CLEAN, indicating that the property has not been modified.
IPROP_READWRITE, indicating that the property can be modified.	IPROP_DIRTY, indicating that the property has been modified.
Return Values

S_OK

The access level and status flags have been successfully set.

MAPI_E_NO_ACCESS

An attempt was made to set a property on a read-only object or an object for which the caller has insufficient permissions.

MAPI_E_INVALID_PARAMETER

The rgulAccess parameter contains an invalid combination of flags, such as IPROP_READONLY and IPROP_READWRITE.

Remarks

The IPropData::HrSetPropAccess method changes the access level and status for the properties that are identified by the property tags in the SPropTagArray structure pointed to by lpPropTagArray. For each property, there is a corresponding entry in the rgulAccess array. The entry can be set to one flag that indicates the property’s access level and another flag that indicates its status.

Notes to Callers

Use HrSetPropAccess for determining when a particular property value changes and to change the access level for one or more of an object’s properties.

See Also

SPropTagArray


IProviderAdmin : IUnknown

The IProviderAdmin interface is used to work with service providers within a message service. Clients can get a pointer to an IProviderAdmin interface by calling IMsgServiceAdmin::AdminProviders; service providers are passed an IProviderAdmin pointer when their message service’s entry point function is called.

Quick Info

Header file:	MAPIDEFS.H
Exposed by:	Provider administration objects
Implemented by:	MAPI
Called by:	Client applications and service providers
Corresponding pointer type:	LPPROVIDERADMIN
Vtable Order

GetLastError	Returns a MAPIERROR structure containing information about the previous error occurring to the provider administration object.
GetProviderTable	Provides access to the message service’s provider table, a listing of the service providers in the message service.
CreateProvider	Adds a service provider to the message service.
DeleteProvider	Deletes a service provider from the message service.
OpenProfileSection	Opens a profile section from the current profile and returns an IProfSect pointer for further access.


IProviderAdmin::CreateProvider

The IProviderAdmin::CreateProvider method adds a service provider to the message service.

Quick Info

See IProviderAdmin : IUnknown.

HRESULT CreateProvider(

LPTSTR lpszProvider,
ULONG cValues,
LPSPropValue lpProps,
ULONG ulUIParam,
ULONG ulFlags,
MAPIUID FAR * lpUID
)
Parameters

lpszProvider

[in] Pointer to the name of the provider to add.

cValues

[in] Count of property values pointed to by the lpProps parameter.

lpProps

[in] Pointer to an property value array describing the properties of the provider to add.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays. The ulUIParam parameter is used if the MAPI_DIALOG flag is set in the ulFlags parameter.

ulFlags

[in] Bitmask of flags that controls the provider addition. The following flags can be set:

MAPI_DIALOG

Allows the display of a dialog box to prompt for configuration information.

MAPI_UNICODE

The provider name and string properties are in the Unicode format. If the MAPI_UNICODE flag is not set, these strings are in the ANSI format.

lpUID

[out] Pointer to the MAPIUID structure holding the unique identifier representing the provider to add.

Return Values

S_OK

The provider was successfully added to the message service.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The IProviderAdmin::CreateProvider method adds a service provider to the message service. The lpszProvider parameter must point to the name of a provider that belongs to the message service. CreateProvider does not verify that the name matches the name of a provider in the service; if the passed name doesn’t match a service name, the call succeeds, but the results are unpredictable. Most message services do not allow providers to be added or deleted while the profile is in use.

After all of the available information about the service provider has been added to the profile from the MAPISVC.INF file, CreateProvider calls the message service’s entry point function with the ulContext parameter set to MSG_SERVICE_PROVIDER_CREATE. If MAPI_DIALOG is set in the CreateProvider method’s ulFlags parameter, then the values in the ulUIParam and ulFlags parameters are also passed to the entry point function. These additional parameters allow the service provider to display its property sheet so that the user can enter configuration settings.

See Also

MAPIUID, MSGSERVICEENTRY, SPropValue


IProviderAdmin::DeleteProvider

The IProviderAdmin::DeleteProvider method deletes a service provider from the message service.

Quick Info

See IProviderAdmin : IUnknown.

HRESULT DeleteProvider(

LPMAPIUID lpUID
)
Parameters

lpUID

[in] [out] Pointer to the MAPIUID structure holding the unique identifier representing the provider to delete.

Return Values

S_OK

The provider was successfully deleted from the message service.

MAPI_E_NOT_FOUND

The MAPIUID pointed to by the lpUID parameter was not recognized.

Remarks

The IProviderAdmin::DeleteProvider method deletes a service provider from the message service. DeleteProvider determines the service provider to delete by matching the MAPIUID structure pointed to by lpUID with the set of identifiers registered by the active service providers.

Most message services do not allow providers to be deleted while the profile is in use. If the provider to delete is in use, DeleteProvider marks it for deletion instead of removing it immediately and returns S_OK. When the provider is no longer being used, it is deleted.

DeleteProvider calls the message service’s entry point function before the provider is removed from the service. The ulContext parameter is set to MSG_SERVICE_PROVIDER_DELETE. The message service entry point function performs the following tasks:

•	Deletes the service provider.

•	Deletes the service provider’s profile section.

The message service entry point function is not called again after the provider has been deleted.

See Also

MAPIUID, MSGSERVICEENTRY


IProviderAdmin::GetLastError

The IProviderAdmin::GetLastError method returns a MAPIERROR structure containing information about the previous error occurring to the provider administration object.

Quick Info

See IProviderAdmin : IUnknown.

HRESULT GetLastError(

HRESULT hResult,
ULONG ulFlags,
LPMAPIERROR FAR * lppMAPIError
)
Parameters

hResult

[in] HRESULT data type containing the error code generated in the previous method call.

ulFlags

[in] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] Pointer to a pointer to the returned MAPIERROR structure containing version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and GetLastError does not support Unicode, or MAPI_UNICODE was not set and GetLastError only supports Unicode.

Remarks

The IProviderAdmin::GetLastError method supplies information about a prior method call that failed. Callers can provide their users with detailed information about the error by including the data from the MAPIERROR structure in a dialog box.

Notes to Callers

You can make use of the MAPIERROR structure pointed to by the lppMAPIError parameter — if MAPI supplies one — only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was or has nothing more to report about the error. In this situation, a pointer to NULL is returned in lppMAPIError instead.

For more information about the GetLastError method, see Using Extended Errors.

See Also

MAPIERROR, MAPIFreeBuffer


IProviderAdmin::GetProviderTable

The IProviderAdmin::GetProviderTable method provides access to the message service’s provider table, a listing of the service providers in the message service.

Quick Info

See IProviderAdmin : IUnknown.

HRESULT GetProviderTable(

ULONG ulFlags,
LPMAPITABLE FAR * lppTable
)
Parameters

ulFlags

[in] Bitmask of flags that controls the type of the strings returned in the provider table’s columns. The following flag can be set:

MAPI_UNICODE

The string columns are in the Unicode format. If the MAPI_UNICODE flag is not set, the columns are in the ANSI format.

lppTable

[out] Pointer to a pointer to the provider table.

Return Values

S_OK

The provider table was successfully returned.

Remarks

The IProviderAdmin::GetProviderTable method retrieves a pointer to the message service’s provider table — a table maintained by MAPI that contains information about each service provider in the message service.

Unlike the provider table returned through IMsgServiceAdmin::GetProviderTable, the provider table returned through IProviderAdmin::GetProviderTable may include additional rows that represent information associated with one or more of the service providers in the message service. This extra information is added to the profile with the "Sections" keyword of MAPISVC.INF. When a provider has extra profile sections, it stores the MAPIUIDs for these sections in the PR_SERVICE_EXTRA_UIDS property. PR_SERVICE_EXTRA_UIDS is saved in the message service profile section.

Providers that have been deleted, or are in use but have been marked for deletion, are not included in the provider table. Provider tables are static, meaning that subsequent additions to or deletions from the message service are not reflected in the table.

If the message service has no providers, GetProviderTable returns a table with zero rows and the S_OK return value.

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the format of the columns returned from the following IMAPITable methods:

•	IMAPITable::QueryColumns

•	IMAPITable::QueryRows

This flag also controls the property types in the sort order returned by the IMAPITable::QuerySortOrder method.

For a complete list of the columns in the provider table, see Provider Table.

Notes to Callers

To retrieve the rows of a provider table in transport order, sort the table by the PR_PROVIDER_ORDINAL column.

To retrieve only those rows that represent service providers without including any extra rows, limit your retrieval to the rows that do have a value of PT_ERROR in their PR_RESOURCE_TYPE column.

See Also

IMAPITable::QueryColumns, IMAPITable::QueryRows, IMAPITable::QuerySortOrder, IMAPITable::SetColumns, IMsgServiceAdmin::GetProviderTable


IProviderAdmin::OpenProfileSection

The IProviderAdmin::OpenProfileSection method opens a profile section from the current profile and returns an IProfSect pointer for further access.

Quick Info

See IProviderAdmin : IUnknown.

HRESULT OpenProfileSection(

LPMAPIUID lpUID,
LPCIID lpInterface,
ULONG ulFlags,
LPPROFSECT FAR * lppProfSect
)
Parameters

lpUID

[in] Pointer to the MAPIUID structure holding the unique identifier for the profile section to be opened. Clients must not pass NULL for the lpUID parameter. Service providers can pass NULL to  retrieve the MAPIUID when calling from their message service entry point functions.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the profile section. Passing NULL results in the profile section’s standard interface, or IProfSect, being returned.

ulFlags

[in] Bitmask of flags that controls how the profile section is opened. The following flags can be set:

MAPI_DEFERRED_ERRORS

Allows OpenProfileSection to return successfully, possibly before the profile section is fully accessible to the caller. If the profile section is not accessible, making a subsequent call to it can result in an error.

MAPI_MODIFY

Requests read/write access. By default, objects are opened with read-only access, and callers should not work on the assumption that read/write access has been granted. Clients are not allowed read/write access to provider sections of the profile.

lppProfSect

[out] Pointer to a pointer to the profile section.

Return Values

S_OK

The profile section was successfully opened.

MAPI_E_NO_ACCESS

An attempt was made to modify a read-only profile section or to access an object for which the user has insufficient permissions.

MAPI_E_NOT_FOUND

The requested profile section does not exist.

Remarks

The IProviderAdmin::OpenProfileSection method opens a profile section, allowing the caller to read information from and possibly write information to the active profile.

Clients cannot open profile sections belonging to providers using the IProviderAdmin::OpenProfileSection method.

Multiple clients or service providers can simultaneously open a profile section with read-only access. However, when a profile section is open with read/write access, no other calls can be made to open the section, regardless of the type of access. If a profile section is open with read-only access, a subsequent call to request read/write access will fail with MAPI_E_NO_ACCESS. Likewise, if a section is open with read/write access, a subsequent call to request read-only access will also fail.

Notes to Callers

If you request that OpenProfileSection open a nonexistent profile section by passing MAPI_MODIFY in ulFlags and an unknown MAPIUID in lpUID, the profile section will be created.

If you request that OpenProfileSection open a nonexistent section with read-only access, it returns MAPI_E_NOT_FOUND.

See Also

IMAPIProp : IUnknown, IProfSect : IMAPIProp, MAPIUID


ISpoolerHook : IUnknown

The ISpoolerHook interface enables a messaging hook provider to reroute messages before they go to their destination.

Quick Info

Header file:	MAPIHOOK.H
Exposed by:	Messaging hook provider objects
Implemented by:	Messaging hook providers
Called by:	The MAPI spooler
Corresponding pointer type:	LPSPOOLERHOOK
Vtable Order

InboundMsgHook	Informs the MAPI spooler it should allow the messaging hook provider to reroute a message from the Inbox to another folder.
OutboundMsgHook	Informs the MAPI spooler it should allow the messaging hook provider to reroute a message from the Sent Items folder to another folder.


ISpoolerHook::InboundMsgHook

The ISpoolerHook::InboundMsgHook method informs the MAPI spooler it should allow the messaging hook provider to reroute a message from the Inbox to another folder.

Quick Info

See ISpoolerHook : IUnknown.

HRESULT InboundMsgHook(

LPMESSAGE lpMessage,
LPMAPIFOLDER lpFolder,
LPMDB lpMDB,
ULONG FAR * lpulFlags,
ULONG FAR * lpcbEntryID,
LPBYTE FAR * lppEntryID
)
Parameters

lpMessage

[in] Pointer to the message to reroute.

lpFolder

[in] Pointer to the parent folder of the message in its message store.

lpMDB

[in] Pointer to the message store containing the folder and message.

lpulFlags

[out] Bitmask of flags that controls how the MAPI spooler responds to the hook for the message indicated in the lpMessage parameter. The following flags can be set:

HOOK_CANCEL

Any subsequent hook functions should not be called for this message. If a hook closes, moves, or deletes the message, the messaging hook provider should set this flag.

HOOK_DELETE

The message should be deleted without being moved.

lpcbEntryID

[in, out] Pointer to the size, in bytes, of the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[in, out] Pointer to the pointer to the entry identifier of the folder where the message will be moved.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Messaging hook providers implement the ISpoolerHook::InboundMsgHook method to reroute a message from the default Inbox to another folder. Before moving a message to another folder or message store, a messaging hook provider should call the IUnknown::QueryInterface method for the message object to make sure the provider can get an interface for the message that is compatible with the provider’s implementation.

Before rerouting a message, a messaging hook provider must replace the passed-in entry identifier in lppEntryID with the entry identifier of the new target folder. The MAPI spooler moves the message to the indicated folder for the provider, unless another hook function replaces the folder entry identifier. If a hook requires that its operation be the final action on the message, it can set the HOOK_CANCEL flag in the lpulFlags parameter before returning.

If a provider replaces the lppEntryID entry identifier, it must call the MAPIFreeBuffer function to free the previous one. The copy of the entry identifier the provider stores in lppEntryID should be allocated using the MAPIAllocateBuffer function.

If a messaging hook provider’s implementation must move a message to another folder itself, it should close the message, place zero in the lpcbEntryID parameter, and free the lppEntryID entry identifier, if lppEntryID is not already NULL. The hook then sets lppEntryID to NULL and places a pointer to the message’s new parent folder in lpFolder. Messaging hook providers that move the message must set HOOK_CANCEL in lpulFlags.

If a hook deletes a message, it should close the message, place zero in lpcbEntryID, and place NULL in lppEntryID after freeing the existing entry identifier if need be. It then deletes the message and returns HOOK_CANCEL in lpulFlags. Alternatively, it can combine the HOOK_CANCEL and HOOK_DELETE flags in lpulFlags using the logical OR operator.

The MAPI spooler calls hook providers in the order in which they are specified in the provider section of the profile, as it does transport providers. The MAPI spooler releases the messaging hook provider object at session shutdown. If a provider called the IUnknown::AddRef method for a session at initialization, it should call the IUnknown::Release method to release the session and any objects, such as message stores, it opened and maintained during the session.


ISpoolerHook::OutboundMsgHook

The ISpoolerHook::OutboundMsgHook method informs the MAPI spooler it should allow the messaging hook provider to reroute a message from the Sent Items folder to another folder.

Quick Info

See ISpoolerHook : IUnknown.

HRESULT OutboundMsgHook(

LPMESSAGE lpMessage,
LPMAPIFOLDER lpFolder,
LPMDB lpMDB,
ULONG FAR * lpulFlags,
ULONG FAR * lpcbEntryID,
LPBYTE FAR * lppEntryID
)
Parameters

lpMessage

[in] Pointer to the message to reroute.

lpFolder

[in] Pointer to the parent folder of the message in its message store.

lpMDB

[in] Pointer to the message store containing the folder and message.

lpulFlags

[out] Bitmask of flags that controls how the MAPI spooler responds to the hook for the message indicated in the lpMessage parameter. The following flags can be set:

HOOK_CANCEL

Any subsequent hook functions should not be called for this message. If a hook closes, moves, or deletes the message, the messaging hook provider should set this flag.

HOOK_DELETE

The message should be deleted without being moved.

lpcbEntryID

[in, out] Pointer to the size, in bytes, of the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[in, out] Pointer to the pointer to the entry identifier of the folder where the message will be moved.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Messaging hook providers implement the ISpoolerHook::OutboundMsgHook method to reroute a message from the default Sent Items folder to another folder. Before moving a message to another folder or message store, a messaging hook provider should call the IUnknown::QueryInterface method for the message object to make sure the provider can get an interface for the message that is compatible with the provider’s implementation.

Before rerouting a message, a messaging hook provider must replace the passed-in entry identifier in lppEntryID with the entry identifier of the new target folder. The MAPI spooler moves the message to the indicated folder for the provider, unless another hook function replaces the folder entry identifier. If a hook requires that its operation be the final action on the message, it can set the HOOK_CANCEL flag in the lpulFlags parameter before returning.

If a provider replaces the lppEntryID entry identifier, it must call the MAPIFreeBuffer function to free the previous one. The copy of the entry identifier the provider stores in lppEntryID should be allocated using the MAPIAllocateBuffer function.

If a messaging hook provider’s implementation must move a message to another folder itself, it should close the message, place zero in the lpcbEntryID parameter, and free the lppEntryID entry identifier, if lppEntryID is not already NULL. The hook then sets lppEntryID to NULL and places a pointer to the message’s new parent folder in lpFolder. Messaging hook providers that move the message must set HOOK_CANCEL in lpulFlags.

If a hook deletes a message, it should close the message, place zero in lpcbEntryID, and place NULL in lppEntryID after freeing the existing entry identifier if need be. It then deletes the message and returns HOOK_CANCEL in lpulFlags. Alternatively, it can combine the HOOK_CANCEL and HOOK_DELETE flags in lpulFlags using the logical OR operator.

The MAPI spooler calls hook providers in the order in which they are specified in the provider section of the profile, as it does transport providers. The MAPI spooler releases the messaging hook provider object at session shutdown. If a provider called the IUnknown::AddRef method for a session at initialization, it should call the IUnknown::Release method to release the session and any objects, such as message stores, it opened and maintained during the session.


ITableData : IUnknown

The ITableData interface provides utility methods for working with tables. Table data objects, or objects that implement ITableData, are provided by MAPI to help service providers perform table maintenance. To obtain a table data object, service providers call the CreateTable function.

Quick Info

Header file:	MAPIUTIL.H
Exposed by:	Table data objects
Implemented by:	MAPI
Called by:	Service providers
Corresponding pointer type:	LPTABLEDATA
Vtable Order

HrGetView	Creates a table view, returning a pointer to an IMAPITable implementation.
HrModifyRow	Inserts a new table row, possibly replacing an existing row.
HrDeleteRow	Deletes a table row.
HrQueryRow	Retrieves a table row.
HrEnumRow	Retrieves a row based on its position in the table.
HrNotify	Sends a notification for a table row.
HrInsertRow	Inserts a table row.
HrModifyRows	Inserts multiple table rows, possibly replacing existing rows.
HrDeleteRows	Deletes multiple table rows.
Remarks

The MAPI implementation of ITableData works with tables by holding all of the data and any associated restrictions in memory, making it unsuitable for use with very large tables. Large restrictions and complex operations such as categorization are unsupported.

Table data objects identify rows using an index column — a property that is guaranteed to have a unique value for each row. Most service providers use the PR_INSTANCE_KEY property as the index column. Multivalued properties cannot be used as an index column.

Table data objects generate a single notification regardless of the number of rows affected by a change or deletion. If a target row in an operation does not exist, a row is added.


ITableData::HrDeleteRow

The ITableData::HrDeleteRow method deletes a table row.

Quick Info

See ITableData : IUnknown.

HRESULT HrDeleteRow(

LPSPropValue lpSPropValue
)
Parameters

lpSPropValue

[in] Pointer to a property value structure describing the index column for the row to be deleted. The ulPropTag member of the property value structure should contain the same property tag as the  ulPropTagIndexColumn parameter from the call to CreateTable.

Return Values

S_OK

The row was successfully deleted.

MAPI_E_NOT_FOUND

The property pointed to by the lpSPropValue parameter does not identify a row in the table.

Remarks

The ITableData::HrDeleteRow method removes the table row containing the column that matches the property pointed to by the lpSPropValue parameter. The data for the row is deleted and the row is removed from all open views.

After the row is deleted, notifications are sent to all clients or service providers with a view of the table that have called the table’s IMAPITable::Advise method to register for notifications.

Deleting a row does not reduce the column set available to existing views or subsequently opened views, even if the deleted row was the last row with a value for a specific column.

See Also

CreateTable, ITableData::HrDeleteRows, ITableData::HrModifyRow, SPropValue, TABLE_NOTIFICATION


ITableData::HrDeleteRows

The ITableData::HrDeleteRows method deletes multiple table rows.

Quick Info

See ITableData : IUnknown.

HRESULT HrDeleteRows(

ULONG ulFlags,
LPSRowSet lprowsetToDelete,
ULONG FAR * cRowsDeleted
)
Parameters

ulFlags

[in] Bitmask of flags that controls the deletion. The following flag can be set:

TAD_ALL_ROWS

Deletes all rows from the table and all corresponding views, sending a single TABLE_RELOAD notification.

lprowsetToDelete

[in] Pointer to a row set describing the rows to be deleted. The lprowsetToDelete parameter can be NULL if the TAD_ALL_ROWS flag is set in the ulFlags parameter.

cRowsDeleted

[out] Count of the deleted rows.

Return Values

S_OK

The table rows were successfully deleted.

Remarks

The ITableData::HrDeleteRows method locates and removes the table rows containing the columns that match the property pointed to by the lpProps member of each aRow entry in the row set. An index column is used to identity each row; this column must have the same property tag as the property tag passed in the ulPropTagIndexColumn parameter in the call to CreateTable.

The number of rows that were actually deleted is returned in cRowsDeleted. No error is returned if one or more rows could not be found.

After the rows are deleted, notifications are sent to all clients or service providers with a view of the table that have called the table’s IMAPITable::Advise to register for notifications.

Deleting rows does not reduce the columns available to existing table views or subsequently opened table views, even if the rows deleted were the last with values for a specific column.

See Also

CreateTable, ITableData::HrDeleteRow, ITableData::HrModifyRows, SRowSet, TABLE_NOTIFICATION


ITableData::HrEnumRow

The ITableData::HrEnumRow method retrieves a row based on its position in the table.

Quick Info

See ITableData : IUnknown.

HRESULT HrEnumRow(

ULONG ulRowNumber,
LPSRow FAR * lppSRow
)
Parameters

ulRowNumber

[in] Number of the row for which to return properties. The value in the ulRowNumber parameter can be any value from 0, indicating the first row in the table, through n − 1, indicating the last row in the table.

lppSRow

[out] Pointer to a pointer to an SRow structure describing the target row.

Return Values

S_OK

The row was retrieved successfully or a row for the row number specified by the ulRowNumber parameter does not exist.

Remarks

The ITableData::HrEnumRow method retrieves a row based on a sequential number. This number represents the order of insertion, with 0 being the first row and the number of rows minus 1 being the last row. MAPI maintains this chronological order of row insertion for the lifetime of the table data object.

If the number specified in ulRowNumber does not correspond to a row in the table, HrEnumRow returns S_OK and sets the lppSRow parameter to NULL

MAPI allocates memory for the returned SRow structure using the MAPIAllocateBuffer function when the table data object is created. The caller must release this memory by calling the MAPIFreeBuffer function.

To retrieve rows from a table in the order that they were inserted, table data object users call the HrEnumRow method.

See Also

MAPIAllocateBuffer, MAPIFreeBuffer, SRow


ITableData::HrGetView

The ITableData::HrGetView method creates a table view, returning a pointer to an IMAPITable implementation.

Quick Info

See ITableData : IUnknown.

HRESULT HrGetView(

LPSSortOrderSet lpSSortOrderSet,
CALLERRELEASE FAR * lpfCallerRelease,
ULONG ulCallerData,
LPMAPITABLE FAR * lppMAPITable
)
Parameters

lpSSortOrderSet

[in] Pointer to a sort order structure describing the sort order for the table view. If NULL is passed in the lpSSortOrderSet parameter, the view is not sorted.

lpfCallerRelease

[in] Pointer to a callback function based on the CALLERRELEASE prototype that MAPI calls when it releases the view. If NULL is passed in the lpfCallerRelease parameter, no function is called upon release of the view.

ulCallerData

[in] Data that must be saved with the new view and passed to the callback function pointed to by lpfCallerRelease.

lppMAPITable

[out] Pointer to a pointer to the newly created view.

Return Values

S_OK

The view was successfully created.

Remarks

The ITableData::HrGetView method creates a read-only view of the data in the table sorted in the order pointed to by lpSSortOrderSet. The cursor is placed at the beginning of the first row in the view. An IMAPITable interface implementation for accessing the view is returned.

Service providers call HrGetView when they need to give a client access to a table. HrGetView creates the view and returns the IMAPITable pointer. Service providers in turn pass the pointer on to the client. When the client is finished using the table and calls its IUnknown::Release method, HrGetView calls the callback function pointed to by the lpfCallerRelease parameter.

If a service provider needs to return to a client a view that has a customized column set or a restriction in place, the provider can call the view’s IMAPITable::SetColumns and Restrict methods before allowing the client access.

See Also

CALLERRELEASE, IMAPITable : IUnknown, SSortOrderSet


ITableData::HrInsertRow

The ITableData::HrInsertRow method inserts a table row.

Quick Info

See ITableData : IUnknown.

HRESULT HrInsertRow(

ULONG uliRow,
LPSRow lpSRow
)
Parameters

uliRow

[in] A sequential row number representing the row after which the new row should be inserted. The uliRow parameter can hold row numbers from 0 through n, where n is the total number of rows in the table; passing n in uliRow results in the row being appended to the table’s end.

lpSRow

[in] Pointer to an SRow structure describing the row to be inserted.

Return Values

S_OK

The row was successfully inserted.

MAPI_E_INVALID_PARAMETER

A row already exists in the table with the same value for its index column as the row to be inserted.

Remarks

The ITableData::HrInsertRow method inserts a row into a table at a particular position. The new row is inserted after the row that is in the position specified by the uliRow parameter.

If uliRow is set to the number of rows in the table, the new row is appended to the table’s end.

The property that acts as the index column for the table must be included in the lpProps member of the SRow structure pointed to by the lpSRow parameter. This index property, typically PR_INSTANCE_KEY, is used to uniquely identify the row for future maintenance tasks.

The property columns in the SRow structure do not have to be in the same order as the property columns in the table.

After the row is inserted, notifications are sent to all clients or service with a view of the table and have called the table’s IMAPITable::Advise method to register for notifications.

After the row is inserted, notifications are sent to all clients or service providers with a view of the table that have called the table’s IMAPITable::Advise method to register for notifications. No notification is sent if the inserted row is not included in the view due to a restriction in place.

See Also

SRow, TABLE_NOTIFICATION


ITableData::HrModifyRow

The ITableData::HrModifyRow method inserts a new table row, possibly replacing an existing row.

Quick Info

See ITableData : IUnknown.

HRESULT HrModifyRow(

LPSRow lpSRow
)
Parameters

lpSRow

[in] Pointer to an SRow structure describing the row to be added or to replace an existing row. One of the property value structures pointed to by the lpProps member of the SRow structure should contain the index column, the same property that was specified in the ulPropTagIndexColumn parameter in the call to CreateTable.

Return Values

S_OK

The row was successfully inserted or modified.

MAPI_E_INVALID_PARAMETER

The passed-in row does not have an index column.

Remarks

The ITableData::HrModifyRow method inserts the row described by the SRow structure pointed to by the lpSRow parameter. If a row already exists in the table that has the same value for its index column as the row that is pointed to by lpSRow, the existing row is replaced. If no row exists that matches the one included in the SRow structure, HrModifyRow adds the row to the end of the table.

All views of the table are modified to include the row pointed to by lpSRow. However, if a view has a restriction in place that excludes the row, it may not be visible to the user.

The columns in the row pointed to by lpSRow do not have to be in the same order as the columns in the table. The caller can also include as columns properties that are not currently in the table. For existing views, HrModifyRow makes these new columns available but does not include them in the current column set. For future views, HrModifyRow includes the new columns in the column set.

After HrModifyRow has added the row, notifications are sent to all clients or service providers with a view of the table and that have called the table’s IMAPITable::Advise method to register for notifications.

See Also

SRow, TABLE_NOTIFICATION


ITableData::HrModifyRows

The ITableData::HrModifyRows method inserts multiple table rows, possibly replacing existing rows.

Quick Info

See ITableData : IUnknown.

HRESULT HrModifyRows(

ULONG ulFlags,
LPSRowSet lpSRowSet
)
Parameters

ulFlags

Reserved; must be zero.

lpSRowSet

[in] Pointer to an SRowSet structure containing the set of rows to be added, replacing existing rows if necessary. One of the property value structures pointed to by the lpProps member of each SRow structure in the row set should contain the index column — the same property that was specified in the ulPropTagIndexColumn parameter in the call to CreateTable.

Return Values

S_OK

The rows were successfully inserted or modified.

MAPI_E_INVALID_PARAMETER

One or more of the passed-in rows does not have an index column. If this error is returned, no rows are changed.

Remarks

The ITableData::HrModifyRows method inserts the rows described by the SRowSet structure pointed to by the lpSRowSet parameter. For each row in the row set, if its index column value matches the value for an existing row in the table, the existing row is replaced. If no row exists that matches the one included in the SRowSet structure, HrModifyRows adds the row to the end of the table.

All views of the table are modified to include the rows pointed to by lpSRowSet. However, if a view has a restriction in place that excludes a row, it may not be visible to the user.

The columns in the rows pointed to by lpSRowSet do not have to be in the same order as the columns in the table. The caller can also include as columns properties that are not currently in the table. For existing views, HrModifyRows makes these new columns available but does not include them in the current column set. For future views, HrModifyRows includes the new columns in the column set.

After HrModifyRows has added the rows, notifications are sent to all clients or service providers with a view of the table and that have called the table’s IMAPITable::Advise method to register for notifications. MAPI sends TABLE_ROW_ADDED or TABLE_ROW_MODIFIED notifications for each row for up to eight rows. If more than eight rows are affected by the HrModifyRows call, MAPI sends a single TABLE_CHANGED notification instead.

See Also

SRowSet


ITableData::HrNotify

The ITableData::HrNotify method sends a notification for a table row.

Quick Info

See ITableData : IUnknown.

HRESULT HrNotify(

ULONG ulFlags,
ULONG cValues,
LPSPropValue lpSPropValue
)
Parameters

ulFlags

Reserved; must be zero.

cValues

[in] Count of property values in the SPropValue structure pointed to by the lpSPropValue parameter.

lpSPropValue

[in] Pointer to an SPropValue structure describing the values of the columns in the target row.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The ITableData::HrNotify method sends a TABLE_ROW_MODIFIED notification for the row that matches the row described by the properties pointed to by the lpSPropValue parameter. HrNotify sends the notification regardless of whether changes have occurred to the row. All clients and service providers that hold views of the table and have called IMAPITable::Advise to register for notifications on their views receive this notification.

See Also

SPropValue, TABLE_NOTIFICATION


ITableData::HrQueryRow

The ITableData::HrQueryRow method retrieves a table row.

Quick Info

See ITableData : IUnknown.

HRESULT HrQueryRow(

LPSPropValue lpSPropValue,
LPSRow FAR * lppSRow,
ULONG FAR * lpuliRow
)
Parameters

lpSPropValue

[in] Pointer to a property value structure describing the index column for the row to be retrieved. The ulPropTag member of the property value structure should contain the same property tag as the ulPropTagIndexColumn parameter from the call to CreateTable — the function used to access the ITableData implementation.

lppSRow

[out] Pointer to a pointer to the retrieved row.

lpuliRow

[in, out] On input, either a valid pointer or NULL, indicating no information need be returned. On output, a valid pointer points to the row’s row number, a sequential number that identifies the row’s position in the table.

Return Values

S_OK

The row was successfully retrieved.

MAPI_E_INVALID_PARAMETER

The SPropValue structure pointed to by lpSPropValue does not contain the index column property.

Remarks

The ITableData::HrQueryRow method retrieves all of the properties for the row that has an index column that matches the value of the index column included in the property structure pointed to by lpSPropValue. HrQueryRow also returns, if desired by the caller, the row number identifying the row’s position within the table.

Because HrQueryRow does not modify the SPropValue structure pointed to by lpSPropValue, callers must free it when HrQueryRow returns. Callers must also free the SRow structure containing the retrieved row.

See Also

MAPIAllocateBuffer, MAPIFreeBuffer, SPropValue, SRow


ITnef : IUnknown

The ITnef interface provides methods for encapsulating those MAPI properties not supported by a messaging system into binary streams that can accompany messages through transport provider handling and through gateways. The format used for this encapsulation is Transport-Neutral Encapsulation Format (TNEF). The target transport provider can then, on receiving a message including TNEF-encapsulated properties, decode the encapsulation to retrieve all the properties of the original message.

Quick Info

Header file:	TNEF.H
Exposed by:	TNEF objects
Implemented by:	MAPI
Called by:	Transport providers, message store providers, gateways
Corresponding pointer type:	LPTNEF
Vtable Order

AddProps	Allows the calling service provider or gateway to add properties to include in the encapsulation of a message or an attachment.
ExtractProps	Extracts the properties from a TNEF encapsulation.
Finish	Finishes processing for all TNEF operations that are queued and waiting.
OpenTaggedBody	Opens a stream interface on the text of an encapsulated message.
SetProps	Sets the value of one or more properties for an encapsulated message or attachment without modifying the original message or attachment.
EncodeRecips	Encodes a view for a message’s recipient table in the TNEF data stream for the message.
FinishComponent	Processes individual components from a message one at a time into a TNEF stream.


ITnef::AddProps

The ITnef::AddProps method allows the calling service provider or gateway to add properties to include in the encapsulation of a message or an attachment.

Quick Info

See ITnef : IUnknown.

HRESULT AddProps(

ULONG ulFlags,
ULONG ulElemID,
LPVOID lpvData,
LPSPropTagArray lpPropList
)
Parameters

ulFlags

[in] Bitmask of flags that controls how properties are included in or excluded from encapsulation. The following flags can be set:

TNEF_PROP_ATTACHMENTS_ONLY

Encodes only the properties in the lpPropList parameter that are part of attachments within the message.

TNEF_PROP_CONTAINED

Encodes only properties from the attachment specified by the ulElemID parameter. If the lpvData parameter is non-null, then the data pointed to is written into the attachment’s encapsulation in the transport file indicated in the PR_ATTACH_TRANSPORT_NAME property.

TNEF_PROP_CONTAINED_TNEF

Encodes only properties from the message or attachment specified by ulElemID. If this flag is set, the value in lpvData must be an ISTREAMTNEF pointer.

TNEF_PROP_EXCLUDE

Encodes all properties not specified in lpPropList.

TNEF_PROP_INCLUDE

Encodes all properties specified in lpPropList.

TNEF_PROP_MESSAGE_ONLY

Encodes only those properties specified in lpPropList that are part of the message itself.

ulElemID

[in] An attachment’s PR_ATTACH_NUM property, which holds a number that uniquely identifies the attachment within its parent message. The ulElemID parameter is used when special handling is requested for an attachment. The ulElemID parameter should be zero unless the TNEF_PROP_CONTAINED or TNEF_PROP_CONTAINED_TNEF flag is set in the ulFlags parameter.

lpvData

[in] Pointer to attachment data used to replace the data of the attachment specified in ulElemID. The lpvData parameter should be NULL unless TNEF_PROP_CONTAINED or TNEF_PROP_CONTAINED_TNEF is set in ulFlags.

lpPropList

[in] Pointer to the list of properties to include in or exclude from encapsulation.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Transport providers, message store providers, and gateways call the ITnef::AddProps method to list properties to be included in or excluded from the TNEF encapsulation of a message or an attachment. Using successive calls, the provider or gateway can specify a list of properties to add and encode or to exclude from being encoded. Providers and gateways can also use AddProps to provide information on any special handling attachments should be given.

AddProps is only supported for TNEF objects opened with the TNEF_ENCODE flag for the OpenTnefStream or OpenTnefStreamEx function.

Note that no actual TNEF encoding happens for AddProps until the ITnef::Finish method is called. This functionality means that pointers passed into AddProps must remain valid until after the call to Finish is made. At that point, all objects and data passed in with AddProps calls can be released or freed.

See Also

ITnef::Finish, OpenTnefStream, OpenTnefStreamEx, PR_ATTACH_TRANSPORT_NAME


ITnef::EncodeRecips

The ITnef::EncodeRecips method encodes a view for a message’s recipient table in the TNEF data stream for the message.

Quick Info

See ITnef : IUnknown.

HRESULT EncodeRecips(

ULONG ulFlags,
LPMAPITABLE lpRecipientTable
)
Parameters

ulFlags

Reserved; must be zero.

lpRecipientTable

[in] Pointer to the recipient table for which the view is encoded. The lpRecipientTable parameter can be NULL.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Transport providers, message store providers, and gateways call the ITnef::EncodeRecips method to perform TNEF encoding for a particular recipient table view. Such encoding is useful, for instance, if a provider or gateway requires a particular column set, sort order, or restriction for the recipient table.

A provider or gateway passes the table view to be encoded in lpRecipientTable. The TNEF implementation encodes the recipient table with the given view, using the given column set, sort order, restriction, and position. If a provider or gateway passes NULL in lpRecipientTable, TNEF gets the recipient table from the message being encoded, using the IMessage::GetRecipientTable method, and processes every row of the table into the TNEF stream using the table’s current settings.

Calling EncodeRecips with NULL in lpRecipientTable thus encodes all message recipients and is equivalent to calling the ITnef::AddProps method with the TNEF_PROP_INCLUDE flag in its ulFlags parameter and the PR_MESSAGE_RECIPIENTS property in its lpPropList parameter.

See Also

IMessage::GetRecipientTable, ITnef::AddProps, PR_MESSAGE_RECIPIENTS


ITnef::ExtractProps

The ITnef::ExtractProps method extracts the properties from a TNEF encapsulation.

Quick Info

See ITnef : IUnknown.

HRESULT ExtractProps(

ULONG ulFlags,
LPSPropTagArray lpPropList,
LPSTnefProblemArray FAR * lpProblems
)
Parameters

ulFlags

[in] Bitmask of flags that controls how properties are decoded. The following flags can be set:

TNEF_PROP_EXCLUDE

Decodes all properties not specified in the lpPropList parameter.

TNEF_PROP_INCLUDE

Decodes all properties specified in lpPropList.

lpPropList

[in] Pointer to the list of properties to include in or exclude from the decoding operation.

lpProblems

[out] Pointer to a pointer to a returned STnefProblemArray structure. The STnefProblemArray structure indicates which properties were not encoded properly, if any. If NULL is passed in the lpProblems parameter, no property problem array is returned.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_CORRUPT_DATA

Data being decoded into a stream is corrupted.

Remarks

Transport providers, message store providers, and gateways call the ITnef::ExtractProps method to extract — that is, decode — properties from the encapsulation of a message or an attachment that was passed to the OpenTnefStream function. The calling provider or gateway can specify a list of properties to decode. Providers and gateways can also use ExtractProps to provide information on any special handling attachments should be given.

Once decoding is done, the original message passed into OpenTnefStream is repopulated with the decoded properties. Subsequent ExtractProps calls go back to the message and extract the new list of properties.

Unlike the ITnef::AddProps method, which queues requested actions until the ITnef::Finish method is called, properties are decoded when the ExtractProps call is made. For that reason, the target message for encapsulation decoding should be relatively empty. Existing properties in the target message are overwritten by encapsulated properties.

ExtractProps is only supported for objects opened with the TNEF_DECODE flag for the OpenTnefStream or OpenTnefStreamEx function.

The TNEF implementation reports TNEF stream encoding problems without halting the ExtractProps process. The STnefProblemArray structure returned in lpProblems indicates which TNEF attributes or MAPI properties, if any, could not be processed. The value returned in the scode member of the STnefProblemArray indicates the specific problem. The provider or gateway can work on the assumption that all properties or attributes for which ExtractProps does not return a problem report were processed successfully.

One exception is that if, during the decoding of a TNEF stream, a property in the MAPI encapsulation block cannot be processed and leaves the stream unreliable; then decoding of the encapsulation block is halted and a problem is reported. The problem array for this type of problem contains 0L for the ulPropTag member, attMAPIProps or attAttachment for the ulAttribute member, and MAPI_E_UNABLE_TO_COMPLETE for the scode member. Note that the decoding of the stream is not halted, just the decoding of the MAPI encapsulation block. The stream decoding continues with the next attribute block.

If a provider or gateway does not work with problem arrays, it can pass NULL in lpProblems; in this case, no problem array is returned.

The value returned in lpProblems is only valid if the call returns S_OK. When S_OK is returned, the provider or gateway should check the values returned in the STnefProblemArray structure. If an error occurs on the call, then the STnefProblemArray structure is not filled in and the calling provider or gateway should not use or free the structure. If no error occurs on the call, the calling provider or gateway must release the memory for the STnefProblemArray structure by calling the MAPIFreeBuffer function.

See Also

ITnef::AddProps, ITnef::Finish, ITnef::SetProps, MAPIFreeBuffer, OpenTnefStream, OpenTnefStreamEx, STnefProblemArray


ITnef::Finish

The ITnef::Finish method finishes processing for all TNEF operations that are queued and waiting.

Quick Info

See ITnef : IUnknown.

HRESULT Finish(

ULONG ulFlags,
WORD FAR * lpKey,
LPSTnefProblemArray FAR * lpProblem
)
Parameters

ulFlags

Reserved; must be zero.

lpKey

[out] Pointer to the PR_ATTACH_NUM key property of an attachment. The TNEF encapsulation object uses this key to match an attachment to its attachment placement tag within a message. This key should be unique across messages.

lpProblem

[out] Pointer to a pointer to a returned STnefProblemArray structure. The STnefProblemArray structure indicates which properties were not encoded properly, if any. If NULL is passed in the lpProblem parameter, no property problem array is returned.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Transport providers, message store providers, and gateways call the ITnef::Finish method to perform the encoding of all properties for which encoding was requested in calls to the ITnef::AddProps and ITnef::SetProps methods. If the TNEF object to receive encoding was opened with the TNEF_ENCODE flag for the OpenTnefStream or OpenTnefStreamEx function, all properties processed in the Finish call are encoded into the encapsulation stream passed to that object.

After the Finish call, the pointer to the encapsulation stream is set to the end of the TNEF data. If the provider or gateway is to use the TNEF stream data, it must reset the stream pointer to the beginning of the TNEF stream data.

Finish is only supported on objects opened with TNEF_ENCODE set for OpenTnefStream or OpenTnefStreamEx.

The TNEF implementation reports TNEF stream encoding problems without halting the Finish process. The STnefProblemArray structure returned in lpProblem indicates which TNEF attributes or MAPI properties, if any, could not be processed. The value returned in the scode member of the STnefProblemArray indicates the specific problem. The provider or gateway can work on the assumption that all properties or attributes for which Finish does not return a problem report were processed successfully.

If a provider or gateway does not work with problem arrays, it can pass NULL in lpProblem; in this case, no problem array is returned.

The value returned in lpProblem is only valid if the call returns S_OK. When S_OK is returned, the provider or gateway should check the values returned in the STnefProblemArray structure. If an error occurs on the call, then the STnefProblemArray structure is not filled in and the calling provider or gateway should not use or free the structure. If no error occurs on the call, the calling provider or gateway must release the memory for the STnefProblemArray by calling the MAPIFreeBuffer function.

See Also

ITnef::AddProps, MAPIFreeBuffer, OpenTnefStream, OpenTnefStreamEx, PR_ATTACH_NUM, STnefProblemArray


ITnef::FinishComponent

The ITnef::FinishComponent method processes individual components from a message one at a time into a TNEF stream.

Quick Info

See ITnef : IUnknown.

HRESULT FinishComponent(

ULONG ulFlags,
ULONG ulComponentID,
LPSPropTagArray lpCustomPropList,
LPSPropValue lpCustomProps,
LPSPropTagArray lpPropList,
LPSTnefProblemArray FAR * lppProblems
)
Parameters

ulFlags

[in] Bitmask of flags that controls which component has processing finished. One or the other of the following flags must be set:

TNEF_COMPONENT_ATTACHMENT

An attachment object is encoded; the ulComponentID parameter contains the PR_ATTACH_NUM property of the attachment processed.

TNEF_COMPONENT_MESSAGE

A message object is encoded.

ulComponentID

[in] Zero to indicate processing for a message or the PR_ATTACH_NUM property of the attachment to be processed. If the TNEF_COMPONENT_MESSAGE flag is set in the ulFlags parameter, ulComponentID must be zero.

lpCustomPropList

[in] Pointer to an SPropTagArray structure that holds property tags identifying the properties passed in the lpCustomProps parameter. There must be a one-to-one correspondence between each property value in lpCustomProps and a property tag in the lpCustomPropList parameter.

lpCustomProps

[in] Pointer to an SPropValue structure containing property values for the properties to encode.

lpPropList

[in] Pointer to an SPropTagArray structure containing property tags for the properties to encode.

lppProblems

[out] Pointer to a pointer to a returned STnefProblemArray structure. The STnefProblemArray structure indicates which properties were not encoded properly, if any. If NULL is passed in the lppProblems parameter, no property problem array is returned.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Transport providers, message store providers, and gateways call the ITnef::FinishComponent method to perform TNEF processing for one component, either a message or an attachment, as indicated by the flag set in the ulFlags parameter.

For component processing to be enabled, the calling provider or gateway must have passed the TNEF_COMPONENT_ENCODING flag in ulFlags for the OpenTnefStream function or OpenTnefStreamEx function that opened the object to receive encoding.

Passing values in lpCustomPropList and lpCustomProps performs component encoding equivalent to that done by the ITnef::SetProps method. Passing a value in the lpPropList parameter performs component encoding equivalent to that done by the ITnef::AddProps method with the TNEF_PROP_INCLUDE flag set in ulFlags. Passing such values enables you to perform encodings with a single call rather than multiple calls.

The TNEF implementation reports TNEF stream encoding problems without halting the FinishComponent process. The STnefProblemArray structure returned in lppProblems indicates which TNEF attributes or MAPI properties, if any, could not be processed. The value returned in the scode member of the STnefProblemArray indicates the specific problem. The provider or gateway can work on the assumption that all properties or attributes for which FinishComponent does not return a problem report were processed successfully.

If a provider or gateway does not work with problem arrays, it can pass NULL in lppProblems; in this case, no problem array is returned.

The value returned in lppProblems is only valid if the call returns S_OK. When S_OK is returned, the provider or gateway should check the values returned in the STnefProblemArray structure. If an error occurs on the call, then the STnefProblemArray structure is not filled in and the calling provider or gateway should not use or free the structure. If no error occurs on the call, the calling provider or gateway must release the memory for the STnefProblemArray by calling the MAPIFreeBuffer function.

See Also

ITnef::AddProps, ITnef::SetProps, MAPIFreeBuffer, OpenTnefStream, OpenTnefStreamEx, SPropTagArray, STnefProblemArray


ITnef::OpenTaggedBody

The ITnef::OpenTaggedBody method opens a stream interface on the text of an encapsulated message.

Quick Info

See ITnef : IUnknown.

HRESULT OpenTaggedBody(

LPMESSAGE lpMessage,
ULONG ulFlags,
LPSTREAM FAR * lppStream
)
Parameters

lpMessage

[in] Pointer to the message the stream is associated with. This message is not required to be the same message passed in the call to the OpenTnefStream or OpenTnefStreamEx function beginning TNEF encoding.

ulFlags

[in] Bitmask of flags that controls how stream interface is opened. The following flags can be set:

MAPI_CREATE

The property does not exist; it should be created. If the property does exist, the current data in the property should be discarded. When an implementation sets the MAPI_CREATE flag, it should also set the MAPI_MODIFY flag.

MAPI_MODIFY

Requests read/write access. The default interface is read-only. MAPI_MODIFY must be set whenever MAPI_CREATE is set.

lppStream

[out] Pointer to the pointer to a stream object that contains the text from the PR_BODY property of the passed-in encapsulated message and that supports the IStream interface.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Transport providers, message store providers, and gateways call the ITnef::OpenTaggedBody method to open a stream interface on the text of an encapsulated message — that is, on a TNEF object.

As part of its processing, ITnef::OpenTaggedBody either inserts or parses attachment tags that indicate the position of any attachments or OLE objects within the message text. The attachment tags are in the following format:

[[ attachment name : n in attachment container name ]]

where attachment name describes the attachment object; n is a number identifying the attachment that is part of a sequence, incrementing from the value passed in the lpKey parameter of the OpenTnefStream or OpenTnefStreamEx function; and attachment container name describes the physical component where the attachment object resides.

OpenTaggedBody reads out message text and inserts an attachment tag wherever an attachment object originally appeared in the text. The original message text is not changed.

When a message that has tags is passed to a stream, the tags are stripped out and the attachment objects are relocated in the position of the tags in the stream.

See Also

OpenTnefStream, OpenTnefStreamEx, PR_BODY


ITnef::SetProps

The ITnef::SetProps method sets the value of one or more properties for an encapsulated message or attachment without modifying the original message or attachment.

Quick Info

See ITnef : IUnknown.

HRESULT SetProps(

ULONG ulFlags,
ULONG ulElemID,
ULONG cValues,
LPSPropValue lpProps
)
Parameters

ulFlags

[in] Bitmask of flags that controls how properties’ values are set. The following flag can be set:

TNEF_PROP_CONTAINED

Encodes only properties from the message or attachment specified by the ulElemID parameter.

ulElemID

[in] An attachment’s PR_ATTACH_NUM property, which holds a number that uniquely identifies the attachment within its parent message.

cValues

[in] Number of property values in the SPropValue structure pointed to by the lpProps parameter.

lpProps

[in] Pointer to an SPropValue structure containing the property values of the properties to set.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Transport providers, message store providers, and gateways call the ITnef::SetProps method to set properties to include in the encapsulation of a message or an attachment without modifying the original message or attachment. Any properties set with this call override existing properties in the encapsulated message.

SetProps is only supported for encapsulated messages — that is, TNEF objects — opened with the TNEF_ENCODE flag for the OpenTnefStream or OpenTnefStreamEx function. Any number of properties can be set with this call.

Note that no actual TNEF encoding for SetProps happens until after the ITnef::Finish method is called. This functionality means that pointers passed into SetProps must remain valid until after the call to Finish is made. At that point, all objects and data passed into SetProps calls can be released or freed.

See Also

ITnef::Finish, OpenTnefStream, OpenTnefStreamEx, PR_ATTACH_NUM, SPropValue


IXPLogon : IUnknown

The IXPLogon interface is used to provide the MAPI spooler access within a transport provider.

Quick Info

Header file:	MAPISPI.H
Exposed by:	Transport logon objects
Implemented by:	Transport providers
Called by:	The MAPI spooler
Corresponding pointer type:	LXPLOGON
Vtable Order

AddressTypes	Indicates to the MAPI spooler what types of recipients a transport provider can handle.
RegisterOptions	Informs the messaging system about the options provided by a transport provider for a messaging address type.
TransportNotify	Signals in a transport provider session the occurrence of an event for the MAPI spooler about which the provider requested notification.
Idle	Calls a transport provider at a point when the system is idle to perform low-priority operations.
TransportLogoff	Terminates a transport provider session with the MAPI spooler.
SubmitMessage	Indicates to a transport provider the MAPI spooler has a message for the provider to deliver.
EndMessage	Informs a transport provider the MAPI spooler has completed its sending pass for the provider.
Poll	Checks whether a transport provider has one or more incoming messages available.
StartMessage	Initiates the transfer of an incoming message from the transport provider to the MAPI spooler.
OpenStatusEntry	Opens a status object.
ValidateState	Has a transport provider check its external status.
FlushQueues	Requests that transport operations occur quickly.


IXPLogon::AddressTypes

The IXPLogon::AddressTypes method indicates to the MAPI spooler what types of recipients a transport provider can handle.

Quick Info

See IXPLogon : IUnknown.

HRESULT AddressTypes(

ULONG FAR * lpulFlags,
ULONG FAR * lpcAdrType,
LPTSTR FAR * FAR * lpppszAdrTypeArray,
ULONG FAR * lpcMAPIUID,
LPUID FAR * FAR * lpppUIDArray
)
Parameters

lpulFlags

[out] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lpcAdrType

[out] Pointer to the number of entries in the array pointed to by the lpppAdrTypeArray parameter.

lpppszAdrTypeArray

[out] Pointer to a variable where the transport provider places an array of pointers to strings that identify recipient types.

lpcMAPIUID

[out] Pointer to the number of entries in the array pointed to by the lpppUIDArray parameter.

lpppUIDArray

[out] Pointer to a variable where the transport provider places an array of pointers to MAPIUID structures that identify recipient types.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The MAPI spooler calls the IXPLogon::AddressTypes method immediately after a transport provider returns from a call to the IXPProvider::TransportLogon method so the transport provider can indicate what types of recipients it can handle. To indicate this, the transport provider should pass in the lpppszAdrTypeArray parameter a pointer to an array of pointers to strings, or pass in the lpppUIDArray parameter a pointer to an array of pointers to MAPIUID structures, or pass values in both parameters.

These two arrays are used for different identification processes. MAPI and the MAPI spooler use the MAPIUID structures in the lpppUIDArray array to identify those recipient entry identifiers that are directly handled by the transport provider or by the messaging system to which the transport provider connects. Neither MAPI nor the MAPI spooler performs expansion of addresses with entry identifiers containing any of these MAPIUID structures; these structures are only used for recipient type identification.

The MAPI spooler uses each of the strings in the lpppszAdrTypeArray parameter for a comparison test when deciding which transport provider should handle which recipients for an outbound message. If a message recipient’s PR_ADDRTYPE property exactly matches a string identifying one of the messaging address types supplied by the transport provider, the provider can handle that recipient.

In the event multiple transport providers can handle the same type of recipient, MAPI selects a transport provider based on the transport priority order indicated in the client application’s profile. To determine which transport provider to use, the MAPI spooler scans all provider-specified MAPIUID structures in priority order, then all provider-specified address type values in priority order. The first transport provider to match a particular recipient in this scan gets the first opportunity to handle this recipient. If that provider does not handle the recipient, the MAPI spooler continues the scan so as to find a transport provider for any recipient not yet handled. The scan continues until no further matches are found, at which point a nondelivery report is generated for any recipient that was not handled.

If the provider always supports a particular set of recipient types, the address type and MAPIUID arrays passed by the transport provider can be static. If the transport provider dynamically constructs these arrays, it can use the support object that was passed in the call to TransportLogon directly previous to allocate memory, although this is not strictly necessary.

The memory used for the address type and MAPIUID arrays should remain allocated until the final call to the IXPLogon::TransportLogoff method is performed, at which time the transport provider can free the memory if necessary. The contents of these arrays should not be altered by the transport provider after returning from the TransportLogoff call.

A transport provider that can handle any type of recipient can return NULL in lpppszAdrTypeArray. LAN-based messaging systems that support a variety of gateways commonly do this. Such a transport provider should be installed last in the MAPI and MAPI spooler priority order of transport providers within the profile.

A transport provider that does not support outbound messages dispatched to it based on address type should return a single zero-length string in lpppAdrTypeArray. If a transport provider supports no recipient types, it should pass NULL for the MAPIUID structure and an empty string for the address type.

For more information on working with address types, see Displaying and Editing Addresses with Simple MAPI.

See Also

IXPLogon::TransportLogoff, IXPProvider::TransportLogon, MAPIUID


IXPLogon::EndMessage

The IXPLogon::EndMessage method informs a transport provider the MAPI spooler has completed its sending pass for the provider.

Quick Info

See IXPLogon : IUnknown.

HRESULT EndMessage(

ULONG ulMsgRef,
ULONG FAR * lpulFlags
)
Parameters

ulMsgRef

[in] A 32-bit reference value, specific to a message, obtained in an earlier call to the IXPLogon::SubmitMessage method.

lpulFlags

[out] Bitmask of flags that indicates to the MAPI spooler what it should do with the message. If no flags are set, the message has been sent. The following flags can be set:

END_DONT_RESEND

The transport provider has all the information it needs about this message for now. When the transport provider requires more information or when it has completed sending the message, it notifies the MAPI spooler by calling the IMAPISupport::SpoolerNotify method with the NOTIFY_SENTDEFERRED flag and by passing the message’s entry identifier.

END_RESEND_LATER

The transport provider isn’t sending the message now for reasons that are not error conditions and should be called again later to send the message.

END_RESEND_NOW

The transport provider needs to restart the message passed to it in an IMessage::SubmitMessage method call.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The MAPI spooler calls the IXPLogon::EndMessage method after completing the processing involved in providing extended delivery or nondelivery information.

Once this call returns, the value in the ulMsgRef parameter is no longer valid for this message. The transport provider can reuse the same value on a future message.

All objects opened by the transport provider during the transfer of a message should be released before returning from the EndMessage call, with the exception of the message object the MAPI spooler passes to the transport provider. The message object passed by the MAPI spooler is invalid after the EndMessage call.

See Also

IMAPISupport::SpoolerNotify, IMessage::SubmitMessage, IXPLogon::SubmitMessage


IXPLogon::FlushQueues

The IXPLogon::FlushQueues method requests that transport operations occur quickly.

Quick Info

See IXPLogon : IUnknown.

HRESULT FlushQueues(

ULONG ulUIParam,
ULONG cbTargetTransport,
LPENTRYID lpTargetTransport,
ULONG ulFlags
)
Parameters

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays.

cbTargetTransport

Reserved; must be zero.

lpTargetTransport

Reserved; must be NULL.

ulFlags

[in] Bitmask of flags that controls how message queue flushing is done. The following flags can be set:

FLUSH_DOWNLOAD

The inbound message queue or queues should be flushed.

FLUSH_FORCE

The transport provider should process this request if possible, even if doing so is time-consuming.

FLUSH_NO_UI

The transport provider should not display a user interface.

FLUSH_UPLOAD

The outbound message queue or queues should be flushed.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The MAPI spooler calls the IXPLogon::FlushQueues method to advise the transport provider that the MAPI spooler is about to begin processing messages. The transport provider should call the IMAPISupport::ModifyStatusRow method to set an appropriate bit for its state in the PR_STATUS_CODE property of its status row. After updating its status row, the transport provider should return S_OK for the FlushQueues call. The MAPI spooler then starts sending messages, with the operation being synchronous to the MAPI spooler.

To support its implementation of the IMAPIStatus::FlushQueues method, the MAPI spooler calls IXPLogon::FlushQueues for all logon objects for active transport providers running in a profile session. When a transport provider’s FlushQueues method is called as a result of a client application calling IMAPIStatus::FlushQueues, the message processing occurs asynchronously to the client.

See Also

IMAPIStatus::FlushQueues


IXPLogon::Idle

The IXPLogon::Idle method calls a transport provider at a point when the system is idle to perform low-priority operations.

Quick Info

See IXPLogon : IUnknown.

HRESULT Idle(

ULONG ulFlags
)
Parameters

ulFlags

Reserved; must be zero.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The MAPI spooler periodically calls the IXPLogon::Idle method during times when the system is idle, if requested by passing the XP_LOGON_SP flag in the call to the IXPProvider::TransportLogon method that opened the current session. At times when the system is idle, the transport provider can perform background operations that are not appropriate during other calls, or that need to occur on a regular basis.

See Also

IXPProvider::TransportLogon


IXPLogon::OpenStatusEntry

The IXPLogon::OpenStatusEntry method opens a status object.

Quick Info

See IXPLogon : IUnknown.

HRESULT OpenStatusEntry(

LPCIID lpInterface,
ULONG ulFlags,
ULONG FAR * lpulObjType,
LPMAPISTATUS FAR * lppEntry
)
Parameters

lpInterface

[in] Pointer to an interface identifier (IID) for the transport logon object. Passing NULL indicates the IMAPIStatus interface is returned. The lpInterface parameter can also be set to an identifier for an interface for the object.

ulFlags

[in] Bitmask of flags that controls how the status object is opened. The following flag can be set:

MAPI_MODIFY

Requests read/write access. The default interface is read-only.

lpulObjType

[out] Pointer to the type of the opened object.

lppEntry

[out] Pointer to the pointer to the opened status object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The MAPI spooler calls the IXPLogon::OpenStatusEntry method when a client application calls an OpenEntry method for the entry identifier in the transport provider’s subsystem status table row. OpenStatusEntry opens an object with the IMAPIStatus interface associated with this particular transport provider logon. This object is then used to enable client applications to call IMAPIStatus methods, for example to reconfigure the logon session — using the IMAPIStatus::SettingsDialog method — or to validate the state of the logon session — using the IMAPIStatus::ValidateState method.

See Also

IMAPIStatus : IMAPIProp


IXPLogon::Poll

The IXPLogon::Poll method checks whether a transport provider has one or more incoming messages available.

Quick Info

See IXPLogon : IUnknown.

HRESULT Poll(

ULONG FAR * lpulIncoming
)
Parameters

lpulIncoming

[out] Value indicating the existence of incoming messages. A nonzero value indicates that there are incoming messages.

Returned Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The MAPI spooler periodically calls the IXPLogon::Poll method if the transport provider indicates it must be polled for new messages; it does so by passing the LOGON_SP_POLL flag to the call to the IXPProvider::TransportLogon method at the beginning of a session. If the transport provider indicates in response to the Poll call that there are one or more inbound messages available for it to process, the MAPI spooler calls the IXPLogon::StartMessage method to allow the provider to process the first incoming message. The transport provider indicates incoming messages by setting the value in the Poll lpulIncoming parameter to nonzero.

See Also

IXPLogon::StartMessage, IXPProvider::TransportLogon


IXPLogon::RegisterOptions

The IXPLogon::RegisterOptions method informs the messaging system about the options provided by a transport provider for a messaging address type.

Quick Info

See IXPLogon : IUnknown.

HRESULT RegisterOptions(

ULONG FAR * lpulFlags,
ULONG FAR * lpcOptions,
LPOPTIONDATA FAR * lppOptions
)
Parameters

lpulFlags

[out] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lpcOptions

[out] Pointer to the number of options contained in the structure returned in the lppOptions parameter.

lppOptions

[out] Pointer to a pointer to the returned OPTIONDATA structure. The OPTIONDATA structure contains information for a particular messaging address type.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

If anything other than S_OK is returned, the provider is logged off.

Remarks

The MAPI spooler calls the IXPLogon::RegisterOptions method to get the options for messages and recipients supported by a transport provider for a particular messaging address type. These options are then registered with MAPI so they can be displayed in options dialog boxes.

RegisterOptions returns in the lppOptions parameter pointers to one or two OPTIONDATA structures for each supported messaging address type, depending on whether the provider is registered for both recipient and message options, recipient options only, or message options only. If a provider is registered for both option types, RegisterOptions writes one structure containing option information for recipients and one containing option information for messages. For each structure, the ulFlags member indicates whether the options apply to a recipient or a message.

For an example of the use of OPTIONDATA, consider a transport provider that handles recipients for both Microsoft Mail Server and Microsoft Mail Server for the Macintosh. If the provider is registered for both recipient and message options, it provides two pairs of OPTIONDATA structures, one pair for each platform. The MAPI spooler can use these structures to determine what options are valid for each platform. Once it has this option information, the MAPI spooler prompts the user with a dialog box to retrieve the setting the user wants for each option.

MAPI also uses the options registered on the RegisterOptions call to resolve message and recipient options. MAPI does so by using a callback function that the transport provider supplies; this callback function, declared with the OPTIONCALLBACK function prototype defined in MAPIDEFS.H, receives a wrapped IMAPIProp interface that manages the provider’s message and recipient properties.

The provider is responsible for memory management. If memory is allocated for one or more OPTIONDATA structures during this call, the provider should free the memory upon logoff.

See Also

IXPLogon::RegisterOptions, OPTIONCALLBACK, OPTIONDATA


IXPLogon::StartMessage

The IXPLogon::StartMessage method initiates the transfer of an incoming message from the transport provider to the MAPI spooler.

Quick Info

See IXPLogon : IUnknown.

HRESULT StartMessage(

ULONG ulFlags,
LPMESSAGE lpMessage,
ULONG FAR * lpulMsgRef
)
Parameters

ulFlags

Reserved; must be zero.

lpMessage

[in] Pointer to a message object with read/write access, representing the incoming message, which is used by the transport provider to access and manipulate that message. This object remains valid until after the transport provider returns from the call to the IXPLogon::StartMessage method.

lpulMsgRef

[out] Pointer to a variable in which the transport provider returns the 32-bit reference value it assigned to this message. This value is initialized to 1 by the MAPI spooler before returning it to the transport provider.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The MAPI spooler calls the IXPLogon::StartMessage method to initiate the transfer of an incoming message from the transport provider to the MAPI spooler. Before the transport provider starts to use the message object, it should store a message reference in the lpulMsgRef parameter for potential use by a call to the IXPLogon::TransportNotify method.

During a StartMessage call, the MAPI spooler processes methods for objects opened during the transfer of the message and also processes any attachments. This processing can take a long time. Transport providers on 16-bit Windows platforms should call the IMAPISupport::SpoolerYield callback function for the MAPI spooler frequently during this processing to release CPU time for other system tasks.

All recipients in the recipient table created by the transport provider for the message must contain all required addressing properties. If necessary, the provider can construct a custom recipient to represent a particular recipient. However, if the provider can produce a recipient entry that includes more information, it should do so. For example, in the case where a transport provider has enough information about an address book provider’s recipient format that it can build a valid entry identifier for a recipient for that format, it should build the entry identifier.

If any nontransmittable properties are received, the transport provider should not store them in the new message. However, the provider should store in the message all transmittable properties required for the message.

If the incoming message is to be a delivery report or a nondelivery report and the transport provider is unable to use the IMAPISupport::StatusRecips method to generate the report from the original message, the provider should itself populate the passed message with the appropriate properties.

To save the incoming message in the appropriate MAPI message store after processing, the transport provider calls the IMAPIProp::SaveChanges method. If the transport provider doesn’t have any messages to pass to the MAPI spooler, it can stop the incoming message by returning from the StartMessage call without calling SaveChanges.

All objects opened by the transport provider during a StartMessage call should be released before returning. However, the provider should not release the message object originally passed by the MAPI spooler in the lpMessage parameter.

If an error is returned from StartMessage, the message in process is released without having changes saved and is lost. The transport provider in such a case should pass the flag NOTIFY_CRITICAL_ERROR with a call to the IMAPISupport::SpoolerNotify method and call the IXPLogon::Poll method to notify the MAPI spooler that it is in a severe error condition.

For more information, see Interacting with the MAPI Spooler.

See Also

IMAPIProp::SaveChanges, IMAPISupport::SpoolerNotify, IMAPISupport::SpoolerYield, IMAPISupport::StatusRecips, IMessage::GetRecipientTable, IXPLogon::Poll, IXPLogon::TransportNotify


IXPLogon::SubmitMessage

The IXPLogon::SubmitMessage method indicates to a transport provider the MAPI spooler has a message for the provider to deliver.

Quick Info

See IXPLogon : IUnknown.

HRESULT SubmitMessage(

ULONG ulFlags,
LPMESSAGE lpMessage,
ULONG FAR * lpulMsgRef,
ULONG FAR * lpulReturnParm
)
Parameters

ulFlags

[in] Bitmask of flags that controls how the message is submitted. The following flag can be set:

BEGIN_DEFERRED

The MAPI spooler is calling a transport provider with a message whose entry identifier was passed from the transport provider using the IMAPISupport::SpoolerNotify method’s NOTIFY_SENTDEFERRED flag.

lpMessage

[in] Pointer to a message object with read/write access, representing the message to deliver, which is used by the transport provider to access and manipulate that message. This object remains valid until after the transport provider returns from a subsequent call to the IXPLogon::EndMessage method.

lpulMsgRef

[out] Pointer to a variable in which the transport provider returns the 32-bit reference value it assigned to this message. The MAPI spooler passes this reference value in subsequent calls for this message. The value is initialized to zero by the MAPI spooler before returning it to the transport provider.

lpulReturnParm

[out] Pointer to a variable that corresponds to the MAPI_E_WAIT or MAPI_E_NETWORK_ERROR error value returned by the IXPLogon::SubmitMessage method.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BUSY

The transport provider can’t handle the message because it is performing another operation. A provider should use this return value to indicate that no processing occurred and that the MAPI spooler should not call EndMessage. The MAPI spooler tries the SubmitMessage call again later.

MAPI_E_CANCEL

Although on a previous SpoolerNotify call the transport provider requested the MAPI spooler resubmit the message, conditions have since changed and the message should not be resent. The MAPI spooler goes on to handle something else.

MAPI_E_NETWORK_ERROR

A network error prevented successful completion of the operation. The lpulReturnParm parameter should be set to the number of seconds before the MAPI spooler resubmits the message.

MAPI_E_NOT_ME

The transport provider cannot handle this message. The MAPI spooler should try to find another transport provider for it. A provider should use this return value to indicate that no processing occurred and that the MAPI spooler should not call EndMessage.

MAPI_E_WAIT

A temporary problem prevents the transport provider from handling the message. The lpulReturnParm parameter should be set to the number of seconds before the MAPI spooler resubmits the message.

Remarks

The MAPI spooler calls the IXPLogon::SubmitMessage method when it has a message for the transport provider to carry. The message is passed to the transport provider using the lpMessage parameter.

If the provider is ready to accept the message, it should return a reference value by using the lpulMsgRef parameter, process the passed object, and return the appropriate value, usually S_OK. If the provider is not prepared to handle the transfer, it should return an error value and, optionally, another MAPI return value in lpulReturnParm to indicate how long the MAPI spooler should wait before resubmitting the message.

A transport provider’s implementation of this method can:

•	Put the message into an internal queue to wait for transmission, possibly copying it to local storage, and return.

•	Attempt to perform the actual transmission and return when the transmission has completed, either successfully or unsuccessfully.

•	Determine whether or not to send the message after checking the resource involved. In this case, if the resource is free, the provider can lock the resource, prepare the message, and submit it. If the resource is busy, the provider can prepare the message and defer sending to a later time.

The preferred technique depends on the transport provider and the expected number of processes competing for system resources.

During a SubmitMessage call, the transport provider controls the transfer of message data from the message object. However, the transport provider should assign a 32-bit reference value to the message, to which it returns a pointer in lpulMsgRef, before transferring data. It does so because at any point during the process the MAPI spooler can call the IXPLogon::TransportNotify method with the NOTIFY_CANCEL_MESSAGE flag set to signal the provider it should release any open objects and stop message transfer.

The transport provider should not send any nontransmittable properties of the message. When it finds such a property, it should go on to process the next one. The provider should make every effort not to display MAPI_P1 recipient information as part of the transmitted message content, using such recipient information only for addressing purposes. MAPI_P1 recipients are internally-generated recipients for use in resends, they should not be transmitted. Instead, use the other recipients for transmitting recipient information. The purpose of this arrangement is to permit resend recipients to see the exact same recipient table as the original recipients.

During a SubmitMessage call, the MAPI spooler processes methods for objects opened during the transfer of the message and also processes any attachments. This processing can take a long time. Transport providers running on 16-bit Windows platforms should call the IMAPISupport::SpoolerYield callback function for the MAPI spooler frequently during this processing to release CPU time for other system tasks.

All message recipients are visible in the recipient table of the message originally passed by the MAPI spooler. The transport provider should process only those recipients that it can handle based on entry identifier, address type, or both, and that do not already have their PR_RESPONSIBILITY property set to TRUE. If PR_RESPONSIBILITY is already set to TRUE, another transport provider handles that recipient. When the provider has completed sufficient processing of a recipient to determine whether it can handle messages for that recipient, it should set that recipient’s PR_RESPONSIBILITY property to TRUE in the passed message. Usually, the provider makes this determination after message delivery is complete.

Typically, the transport provider does not return from a SubmitMessage call until it has completed the transfer of message data. If no error is returned, the next call from the MAPI spooler to the provider is a call to the IXPLogon::EndMessage method.

If an error is returned from SubmitMessage, the MAPI spooler releases the message in process without saving changes. If the transport provider requires message changes be saved, it must call the IMAPIProp::SaveChanges method on the message before returning.

In case of errors occurring because of transport problems, the MAPI spooler retains the message but delays resubmitting it to the transport provider based on the value returned in lpulRetunParm. The transport provider must fill in that value if its return from SubmitMessage is MAPI_E_WAIT or MAPI_E_NETWORK_ERROR. If a severe error condition is occurring, the transport provider must call the IMAPISupport::SpoolerNotify method with the NOTIFY_CRITICAL_ERROR flag.

See Also

IMAPIProp::SaveChanges, IMAPISupport::SpoolerNotify, IMAPISupport::SpoolerYield, IXPLogon::EndMessage, IXPLogon::TransportNotify


IXPLogon::TransportLogoff

The IXPLogon::TransportLogoff method terminates a transport provider session with the MAPI spooler.

Quick Info

See IXPLogon : IUnknown.

HRESULT TransportLogoff(

ULONG ulFlags
)
Parameters

ulFlags

Reserved; must be zero.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Whether or not the transport provider returns a value other than S_OK, the provider’s logged off.

Remarks

The MAPI spooler calls the IXPLogon::TransportLogoff method to terminate a transport provider session for a particular user. Before calling TransportLogoff, the MAPI spooler discards any data about supported messaging address types for this session passed in the IXPLogon::AddressTypes method.

The transport provider should be prepared to accept a call to TransportLogoff at any time. If a message is in process, the provider should stop the sending process.

The transport provider should release all resources allocated for its current session. If it has allocated any memory for this session with the MAPIAllocateBuffer function, it should free the memory by using the MAPIFreeBuffer function. Any memory allocated by the transport provider to satisfy calls to the IXPLogon::AddressTypes, IXPLogon::RegisterOptions, and IMAPISession::MessageOptions methods can be safely released at this time.

Usually, a provider should, on completing a TransportLogoff call, first invalidate its logon object by calling the IMAPISupport::MakeInvalid method and then release its support object. The provider’s implementation of TransportLogoff should release the support object last, because when the support object is released, the MAPI spooler can also release the provider object itself.

See Also

IMAPISession::MessageOptions, IMAPISupport::MakeInvalid, IMAPISupport::SpoolerYield, IXPLogon::AddressTypes, IXPLogon::RegisterOptions, MAPIAllocateBuffer, MAPIFreeBuffer


IXPLogon::TransportNotify

The IXPLogon::TransportNotify method signals in a transport provider session the occurrence of an event for the MAPI spooler about which the provider requested notification.

Quick Info

See IXPLogon : IUnknown.

HRESULT TransportNotify(

ULONG FAR * lpulFlags,
LPVOID FAR * lppvData
)
Parameters

lpulFlags

[in, out] Bitmask of flags that signals notification events. The following flags can be set by the MAPI spooler on input and must be returned unchanged on output:

NOTIFY_ABORT_DEFERRED

Notifies the transport provider that a message for which it accepted responsibility is being canceled. Only transport providers that support deferral must support this flag. The lppvData parameter points to the entry identifier of the canceled message. Messages that have not been processed by the MAPI spooler can still be canceled by calling the IMsgStore::AbortSubmit method.

NOTIFY_BEGIN_INBOUND

Inbound messages can now be accepted for this transport provider session. The MAPI spooler regularly calls the IXPLogon::Poll method if the transport provider set the flag LOGON_SP_POLL with the IXPProvider::TransportLogon call at logon. Once the NOTIFY_BEGIN_INBOUND flag is set, the MAPI spooler honors the NOTIFY_NEWMAIL flag passed in the call to the IMAPISupport::SpoolerNotify method. The status table row for the transport provider session should be updated before returning by calling the IMAPISupport::ModifyStatusRow method. NOTIFY_BEGIN_INBOUND is mutually exclusive with the NOTIFY_END_INBOUND flag.

NOTIFY_BEGIN_INBOUND_FLUSH

Signals the transport provider to cycle through inbound messages as quickly as possible. To comply with this notification, the transport provider should set the flag STATUS_INBOUND_FLUSH in the PR_STATUS_CODE property of its status table row as soon as it can, using ModifyStatusRow. Until the end of this inbound messaging cycle, which is when the provider determines it has downloaded all it can or when it has received an IXPLogon::TransportNotify method call with the flag NOTIFY_END_INBOUND_FLUSH set, the provider should not call the IMAPISupport::SpoolerYield method or otherwise give up cycles to the operating system that can be used to speed delivery of incoming messages. At the end of the inbound flush operation, the provider should use SpoolerNotify to clear the STATUS_INBOUND_FLUSH flag in the PR_STATUS_CODE property of its status row.

NOTIFY_BEGIN_OUTBOUND

Outbound operations can now occur for this transport provider session. If there are any messages to be sent for this provider, a call to the IXPLogon::SubmitMessage method follows. The status table row for this session should be updated before returning. The NOTIFY_BEGIN_OUTBOUND flag is mutually exclusive with the NOTIFY_END_OUTBOUND flag.

NOTIFY_BEGIN_OUTBOUND_FLUSH

Works similarly to the NOTIFY_BEGIN_INBOUND_FLUSH flag but refers to outbound messages, and the appropriate status flag is STATUS_OUTBOUND_FLUSH.

NOTIFY_CANCEL_MESSAGE

The MAPI spooler must cancel transfer of the message for which the lppvData parameter points to the 32-bit value obtained with the IXPLogon::SubmitMessage method call. The NOTIFY_CANCEL_MESSAGE flag can be set without the transport provider having returned from the SubmitMessage, IXPLogon::StartMessage, or IXPLogon::EndMessage method call associated with the message. The transport provider must return from the entry point that is handling the canceled message as soon as possible.

For an in-process incoming message, the transport provider should retain the incoming message wherever it is presently stored and pass it at the next convenient time. The message object data already stored for the incoming message is discarded.

If the transport provider did not update this 32-bit value at StartMessage or SubmitMessage time, it is 0 for outbound messages and 1 for inbound messages.

NOTIFY_END_INBOUND

Inbound operations must cease for this transport provider session. The MAPI spooler ceases to use Poll and ignores NOTIFY_NEWMAIL for this session. In-process messages should not be aborted. The status table row for the transport session should be updated by calling ModifyStatusRow before returning. NOTIFY_END_INBOUND is mutually exclusive with NOTIFY_BEGIN_INBOUND.

NOTIFY_END_INBOUND_FLUSH

Notifies the transport provider to come out of flush mode. The transport provider should not stop downloading, but downloading should be done in the background. The status table row for the transport session should be updated by calling ModifyStatusRow when the transport provider can comply with this notification.

NOTIFY_END_OUTBOUND

Outbound operations must cease for this transport provider session. The MAPI spooler ceases to call SubmitMessage and ignores the SpoolerNotify flag NOTIFY_READYTOSEND. If there is an in-process message, it should not be stopped; to stop a message, use the NOTIFY_CANCEL_MESSAGE flag. The status table row for this session should be updated by calling ModifyStatusRow before returning. NOTIFY_END_INBOUND is mutually exclusive with NOTIFY_BEGIN_OUTBOUND.

NOTIFY_END_OUTBOUND_FLUSH

Works similarly to NOTIFY_END_INBOUND_FLUSH but refers to outbound messages, and the appropriate status flag is STATUS_OUTBOUND_FLUSH.

lppvData

[out] Pointer to a pointer to event-specific data. For more information on what lppvData holds, see the description for the lpulFlags parameter.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The MAPI spooler calls the IXPLogon::TransportNotify method to signal to the transport provider the occurrence of events about which notification has been requested. These events include the MAPI spooler’s requiring the cancellation of transfer for a message, the beginning or ending of inbound or outbound transport operations, and the beginning or ending of an operation to clear an incoming or outgoing message queue.

When the user tries to cancel a message that the transport provider has previously deferred, the MAPI spooler calls TransportNotify passing in both the NOTIFY_ABORT_DEFERRED and NOTIFY_CANCEL_MESSAGE flags in ulFlags. If the MAPI spooler is logging off and still has messages in the queue, it passes only NOTIFY_ABORT_DEFERRED in ulFlags when it calls TransportNotify.

The provider must synchronize access to its data on this call, because the MAPI spooler can invoke this method from another thread of execution or from a procedure for a different window.

See Also

IMAPISupport::SpoolerNotify, IMAPISupport::SpoolerYield, IMsgStore::AbortSubmit, IXPLogon::EndMessage, IXPLogon::Poll, IXPLogon::StartMessage, IXPLogon::SubmitMessage, IXPLogon::TransportNotify, IXPProvider::TransportLogon


IXPLogon::ValidateState

The IXPLogon::ValidateState method has a transport provider check its external status.

Quick Info

See IXPLogon : IUnknown.

HRESULT ValidateState(

ULONG ulUIParam,
ULONG ulFlags
)
Parameters

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays.

ulFlags

[in] Bitmask of flags that controls how the status check is done and its results. The following flags can be set:

ABORT_XP_HEADER_OPERATION

The user canceled the operation, typically by clicking the Cancel button in a dialog box. The transport provider has the option to continue working on the operation, or it can abort the operation and return MAPI_E_USER_CANCELED.

CONFIG_CHANGED

Validates the state of currently loaded transport providers by causing the MAPI spooler to call their IXPLogon::AddressTypes and IMAPISession::MessageOptions methods. This flag also provides the MAPI spooler an opportunity to correct critical transport-provider failures without forcing client applications to log off and then log on again.

FORCE_XP_CONNECT

The user selected a connect operation. When this flag is used with the REFRESH_XP_HEADER_CACHE or PROCESS_XP_HEADER_CACHE flag, the connect action occurs without caching.

FORCE_XP_DISCONNECT

The user selected a disconnect operation. When this flag is used with REFRESH_XP_HEADER_CACHE or PROCESS_XP_HEADER_CACHE, the disconnect action occurs without caching.

PROCESS_XP_HEADER_CACHE

Entries in the header cache table should be processed, that all messages marked with the MSGSTATUS_REMOTE_DOWNLOAD flag should be downloaded, and that all messages marked with the MSGSTATUS_REMOTE_DELETE flag should be deleted. Messages that have both MSGSTATUS_REMOTE_DOWNLOAD and MSGSTATUS_REMOTE_DELETE set should be moved.

REFRESH_XP_HEADER_CACHE

A new list of message headers should be downloaded, and that all message status marking flags should be cleared.

SUPPRESS_UI

Prevents the transport provider from displaying a user interface.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BUSY

Another operation is in progress; it should be allowed to complete, or it should be stopped, before this operation is attempted.

MAPI_E_NO_SUPPORT

The remote transport provider involved does not support a user interface, and the client application should display the dialog box itself.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The MAPI spooler calls the IXPLogon::ValidateState method to support calls to the IMAPIStatus::ValidateState method for the status object. The transport provider should respond to the IXPLogon::ValidateState call exactly as if the MAPI spooler had opened a status object for the current logon session and then called ValidateState on that object.

To support its implementation of IMAPIStatus::ValidateState, the MAPI spooler calls IXPLogon::ValidateState on all logon objects for all active transport providers running in a profile session.

See Also

IMAPISession::MessageOptions, IMAPIStatus::ValidateState, IXPLogon::AddressTypes


IXPProvider : IUnknown

The IXPProvider interface is used to initialize a transport provider object and to shut down the object when it is no longer needed.

Quick Info

Header file:	MAPISPI.H
Exposed by:	Transport provider objects
Implemented by:	Transport providers
Called by:	The MAPI spooler
Corresponding pointer type:	LPXPROVIDER
Vtable Order

Shutdown	Closes down a transport provider in an orderly fashion.
TransportLogon	Establishes a session in which a user logs on to a transport provider.


IXPProvider::Shutdown

The IXPProvider::Shutdown method closes down a transport provider in an orderly fashion.

Quick Info

See IXPProvider : IUnknown.

HRESULT Shutdown (

ULONG FAR * lpulFlags
)
Parameters

lpulFlags

Reserved; must be zero.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The MAPI spooler calls the IXPProvider::Shutdown method just prior to releasing a transport provider object. Before calling Shutdown, MAPI releases all logon objects for a provider.

See Also

XPProviderInit


IXPProvider::TransportLogon

The IXPProvider::TransportLogon method establishes a session in which a user logs on to a transport provider.

Quick Info

See IXPProvider : IUnknown.

HRESULT TransportLogon(

LPMAPISUP lpMAPISup,
ULONG ulUIParam,
LPTSTR lpszProfileName,
ULONG FAR * lpulFlags,
LPMAPIERROR FAR * lppMAPIError,
LPXPLOGON FAR * lppXPLogon
)
Parameters

lpMAPISup

[in] Pointer to the transport provider’s support object for callback functions within MAPI for this session. This object remains valid until the transport provider releases it.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays. The ulUIParam parameter can be non-null, for example when the LOGON_SETUP flag is set in the lpulFlags parameter.

lpszProfileName

[in] Pointer to the profile name of the user. The lpszProfileName parameter is used primarily when a dialog box must be presented.

lpulFlags

[in, out] Bitmask of flags that controls how the logon session is established. The following flags can be set on input by the MAPI spooler:

LOGON_NO_CONNECT

The user account is logging on to this transport provider for purposes other than transmission and reception of messages. The transport provider should not attempt to make any connections.

LOGON_NO_DIALOG

No dialog box should be displayed even if the currently saved user credentials are invalid or insufficient for logon.

LOGON_NO_INBOUND

The transport provider does not need to initialize for reception of messages and should not accept incoming messages. The MAPI spooler can use the IXPLogon::TransportNotify method to signal the transport provider to enable inbound message processing.

LOGON_NO_OUTBOUND

The transport provider does not need to initialize for sending messages, as the MAPI spooler does not provide any. If a client application requires a connection to a remote provider during the composition of a message so that it can make IXPLogon::AddressTypes or IXPLogon::RegisterOptions method calls, the transport provider should make the connection. The MAPI spooler can use TransportNotify to signal the transport provider when outbound operations can begin.

MAPI_UNICODE

The passed-in string for the profile name is in Unicode format. If the MAPI_UNICODE flag is not set, the string is in ANSI format.

The following flags can be set on output by the transport provider:

LOGON_SP_IDLE

Requests that the MAPI spooler frequently call the transport provider’s IXPLogon::Idle method for idle-time processing.

LOGON_SP_POLL

Requests that the MAPI spooler frequently call the IXPLogon::Poll method on the returned logon object to check for new messages. If this flag is not set, the MAPI spooler only checks for new messages when the transport provider calls the IMAPISupport::SpoolerNotify method. A transport provider effectively becomes send-only by not setting this flag and by not notifying the MAPI spooler of message receipt.

LOGON_SP_RESOLVE

Requests that the MAPI spooler resolve to full addresses all message addresses for recipients not supported by this transport provider, so that the transport provider can construct a reply path for all recipients.

MAPI_UNICODE

The returned strings in the MAPIERROR structure, if any, are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] Pointer to a pointer to the returned MAPIERROR structure, if any, containing version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

lppXPLogon

[out] Pointer to the pointer to the returned transport provider logon object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_FAILONEPROVIDER

This provider cannot log on, but this error should not disable the service.

MAPI_E_UNCONFIGURED

The profile does not contain enough information for the logon to complete. MAPI calls the provider’s message service entry point function.

MAPI_E_UNKNOWN_CPID

The server is not configured to support the client's code page.

MAPI_E_UNKNOWN_LCID

The server is not configured to support the client's locale information.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The MAPI spooler calls the IXPProvider::TransportLogon method to establish a logon session for a user.

Most transport providers use the IMAPISupport::OpenProfileSection method provided with the support object pointed to by the lpMAPISup parameter for saving and retrieving user identity information, server addresses, and credentials. Using OpenProfileSection enables a transport provider to save arbitrary information and associate it with a logon to a particular resource. For example, a provider can use OpenProfileSection to save the account name and password associated with a particular session and any server names or other necessary information needed to access resources for that session. MAPI hides information associated with a resource from outside access. The profile section made available through lpMAPISup is segregated by the MAPI spooler so data related to this user context is separated from data for other contexts.

The transport provider must call the IUnknown::AddRef method for the support object and keep a copy of the pointer to this object as part of the provider logon object.

The profile display name in lpszProfileName is provided so the transport provider can use it in error messages or logon dialog boxes. If the provider retains this name, it must be copied to storage allocated by the provider.

Transport providers that are tightly coupled with other service providers might need to do additional work at logon to establish the proper credentials required for operations between companion providers.

Usually, transport providers are opened when the user first logs on to a profile. Because the first logon to a profile thus generally precedes logon to any message store, the MAPI spooler usually calls TransportLogon with both the LOGON_NO_INBOUND and LOGON_NO_OUTBOUND flags set in lpulFlags. Later, when the appropriate message stores are available in the profile session, the MAPI spooler calls TransportNotify to initiate inbound and outbound operations for the transport provider.

Passing the LOGON_NO_CONNECT flag in lpulFlags signals offline operation of the transport provider. This flag indicates no external connection is to be made; if the transport provider cannot establish a session without an external connection, it should return an error value for the logon.

A transport provider should set the LOGON_SP_IDLE flag in lpulFlags at initialization time to support any scheduled connections and to handle automatic operations, such as automatic message downloading, timed message downloading, or timed message submission. If this flag is set, the MAPI spooler calls Idle when system idle time occurs to initiate such operations. The MAPI spooler does not call Idle at regular intervals; rather, it is called only during true idle time, so providers should not work on any assumption about how frequently their Idle methods will be called. Providers that support idle-time operations should supply the correct configuration user interface in their provider property sheet.

If the transport provider logon succeeds, the provider should return in the lppXPLogon parameter a pointer to a logon object for the MAPI spooler to use for further provider access. If TransportLogon displays a logon dialog box and the user cancels logon, typically by clicking the Cancel button in the dialog box, the provider should return MAPI_E_USER_CANCEL.

For most error values returned from TransportLogon, MAPI disables the message services to which the failing provider belongs. MAPI will not call any providers belonging to that service for the rest of the life of the MAPI session. In contrast, when TransportLogon returns the MAPI_E_FAILONEPROVIDER error value from its logon, MAPI does not disable the message service to which the provider belongs. TransportLogon should return MAPI_E_FAILONEPROVIDER if it encounters an error that does not warrant disabling the entire service for the life of the session.

If a provider returns MAPI_E_UNCONFIGURED from its logon, MAPI will call the provider’s message service entry function and then retry the logon. MAPI passes MSG_SERVICE_CONFIGURE as the context, to give the service a chance to configure itself. If the client has chosen to allow a user interface on the logon, the service can present its configuration property sheet so the user can enter configuration information.

If the provider finds that all the required information is not in the profile, it should return MAPI_E_UNCONFIGURED so that MAPI calls the provider’s message-service entry point function.

See Also

IMAPISupport::OpenProfileSection, IMAPISupport::SpoolerNotify, IXPLogon::AddressTypes, IXPLogon::Idle, IXPLogon::Poll, IXPLogon::RegisterOptions, IXPLogon::TransportNotify, MAPIERROR


MAPI Properties

For a general explanation of how MAPI works with properties and a list of the properties available on each object, see Properties. For information on the property-related macros, see the SPropValue structure. For a comprehensive list of MAPI properties and their mappings to X.400 attributes, see Mapping of X.400 P2 Attributes to MAPI Properties.

Unlike members of OLE variant arrays, every member in a MAPI multivalued property array is of the same type.


PR_7BIT_DISPLAY_NAME

The PR_7BIT_DISPLAY_NAME property contains a 7-bit ASCII version of a messaging user’s name.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x39FF
Property type:	PT_STRING8
Property tag:	0x39FF001E
Remarks

The PR_7BIT_DISPLAY_NAME property can be considered a mapping of the PR_DISPLAY_NAME property into a 7-bit character set. Some messaging systems, such as Internet and certain X.400 links, are limited to the 128-character 7-bit ASCII code set. Gateways to such messaging systems can improve their performance by calling the IAddrBook::PrepareRecips method directly to retrieve the PR_7BIT_DISPLAY_NAME property to avoid extra processing for code conversion.


PR_AB_DEFAULT_DIR

The PR_AB_DEFAULT_DIR property contains the entry identifier of the address book container that is to be shown to the user first.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3D06
Property type:	PT_BINARY
Property tag:	0x3D060102
Remarks

Do not use this property. It is reserved for use by MAPI.


PR_AB_DEFAULT_PAB

The PR_AB_DEFAULT_PAB property contains the entry identifier of the address book container that is to be used as the personal address book.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3D07
Property type:	PT_BINARY
Property tag:	0x3D070102
Remarks

Do not use this property. It is reserved for use by MAPI.


PR_AB_PROVIDER_ID

The PR_AB_PROVIDER_ID property contains an address book provider’s MAPIUID structure.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Address book container objects
Must be a column in:	Hierarchy tables
Identifier:	0x3615
Property type:	PT_BINARY
Property tag:	0x36150102
Remarks

The MAPIUID structure identifies which address book provider supplies this particular container in the container hierarchy. The value is unique to each provider.

An address book provider can provide more than one identifier. For example, a provider that supplies two different containers can publish in PR_AB_PROVIDER_ID unique identifiers for each container.

PR_AB_PROVIDER_ID is analogous to the PR_MDB_PROVIDER property for message stores. Client applications can use PR_AB_PROVIDER_ID to find related rows in an address book hierarchy table.


PR_AB_PROVIDERS

The PR_AB_PROVIDERS property contains a list of identifiers for address book providers in the current profile.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3D01
Property type:	PT_BINARY
Property tag:	0x3D010102
Remarks

Do not use this property. It is reserved for use by MAPI.


PR_AB_SEARCH_PATH

The PR_AB_SEARCH_PATH property contains a list of entry identifiers for address book containers that are to be searched to resolve names.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3D05
Property type:	PT_MV_BINARY
Property tag:	0x3D051102
Remarks

Do not use this property. It is reserved for use by MAPI.


PR_AB_SEARCH_PATH_UPDATE

The PR_AB_SEARCH_PATH_UPDATE property contains a list of entry identifiers for address book containers explicitly configured by the user.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3D11
Property type:	PT_BINARY
Property tag:	0x3D110102
Remarks

Do not use this property. It is reserved for use by MAPI.


PR_ACCESS

The PR_ACCESS property contains a bitmask of flags indicating the operations a client application can perform on the open object.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Folder and message objects
Identifier:	0x0FF4
Property type:	PT_LONG
Property tag:	0x0FF40003
Remarks

Zero or more of the following flags can be set for the PR_ACCESS property:

MAPI_ACCESS_CREATE_ASSOCIATED

The client can create an associated contents table.

MAPI_ACCESS_CREATE_CONTENTS

The client can create a contents table.

MAPI_ACCESS_CREATE_HIERARCHY

The client can create a hierarchy table.

MAPI_ACCESS_DELETE

The client can delete the object.

MAPI_ACCESS_MODIFY

The client can write to the object.

MAPI_ACCESS_READ

The client can read the object.

The MAPI_ACCESS_DELETE, MAPI_ACCESS_MODIFY, and MAPI_ACCESS_READ flags are found on folder and message objects and in the PR_ACCESS column in contents tables and associated contents tables. The MAPI_ACCESS_CREATE_ASSOCIATED, MAPI_ACCESS_CREATE_CONTENTS, and MAPI_ACCESS_CREATE_HIERARCHY flags are found on folder objects only.

See Also

PR_ACCESS_LEVEL


PR_ACCESS_LEVEL

The PR_ACCESS_LEVEL property contains a bitmask of flags indicating the level at which a client application can access the open object.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Address book container, distribution list, folder, messaging user, message, and message store objects
Identifier:	0x0FF7
Property type:	PT_LONG
Property tag:	0x0FF70003
Remarks

The PR_ACCESS_LEVEL property is used to determine whether or not read/write access was granted. Calls to the IMsgStore::OpenEntry method can request read/write access. By default, access is read-only, although the access granted is defined by the service provider. A provider can grant read/write access when the client requested read-only access.

The following flag can be set:

MAPI_MODIFY

Read/write access was granted.

See Also

PR_ACCESS


PR_ACCOUNT

The PR_ACCOUNT property contains the recipient’s account name.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A00
Property type:	PT_TSTRING
Property tag:	0x3A00001E (0x3A00001F for Unicode)
Remarks

The PR_ACCOUNT property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information about this group of properties, see IMailUser::IMAPIProp.

PR_ACCOUNT commonly contains the recipient’s e-mail name, that is, the final component of the e-mail address, which uniquely identifies the recipient within the local organization. The e-mail name corresponds to the X.400 distinguished name, which is meant to be a short name guaranteed to be unique within a certain messaging domain.


PR_ACKNOWLEDGEMENT_MODE

The PR_ACKNOWLEDGEMENT_MODE property contains the identifier of the mode for message acknowledgment.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0001
Property type:	PT_LONG
Property tag:	0x00010003
Corresponding X.400 attribute:	IM_ACKNOWLEDGEMENT_MODE
Remarks

The PR_ACKNOWLEDGEMENT_MODE property can have exactly one of the following values:

0

Manual acknowledgment.

1

Automatic acknowledgment.

See Also

PR_MESSAGE_CLASS


PR_ADDRTYPE

The PR_ADDRTYPE property contains the messaging user’s e-mail address type, such as SMTP.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Distribution list and messaging user objects
Identifier:	0x3002
Property type:	PT_TSTRING
Property tag:	0x3002001E (0x3002001F for Unicode)
Remarks

The PR_ADDRTYPE property is one of the base address properties common to all messaging users. It specifies which messaging system MAPI uses to handle a given message.

PR_ADDRTYPE also determines the format of the address string in the PR_EMAIL_ADDRESS property. The string provided by PR_ADDRTYPE can contain only the uppercase alphabetic characters from A through Z and the numbers from 0 through 9.

Valid PR_ADDRTYPE examples include:

FAX

MHS

PROFS

SMTP

X400

For more information on the base address properties, see Base Address Properties. For more information on address types, see Address Types.


PR_ALTERNATE_RECIPIENT

The PR_ALTERNATE_RECIPIENT property contains a list of entry identifiers for alternate recipients designated by the originally intended recipient.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects.
Identifier:	0x3A01
Property type:	PT_BINARY
Property tag:	0x3A010102
Corresponding X.400 attribute:	MH_T_ALTERNATE_RECIPIENT_NAME
Remarks

The PR_ALTERNATE_RECIPIENT property is used in autoforwarded messages. It contains a FLATENTRYLIST structure of alternate recipients. If autoforwarding is not permitted or if no alternate recipient has been designated, a nondelivery report should be generated.


PR_ALTERNATE_RECIPIENT_ALLOWED

The PR_ALTERNATE_RECIPIENT_ALLOWED property contains TRUE if the sender permits autoforwarding of this message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0002
Property type:	PT_BOOLEAN
Property tag:	0x0002000B
Corresponding X.400 attribute:	MH_T_ALTERNATE_RECIPIENT_ALLOWED
Remarks

If autoforwarding is not permitted or if no alternate recipient has been designated, a nondelivery report should be generated.


PR_ANR

The PR_ANR property contains a string value for use in a property restriction on an address book container contents table.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x360C
Property type:	PT_TSTRING
Property tag:	0x360C001E (0x360C001F for Unicode)
Remarks

The PR_ANR property does not belong to any object; it is furnished by address book providers in SPropertyRestriction structures. This property contains an ambiguous name resolution (ANR) string that can be tested against an address book container’s contents table to find corresponding message recipients.

Address book providers match the value of PR_ANR against every entry in the contents table, using a provider-defined matching algorithm. The column or columns used in this match are chosen by the provider as part of the algorithm. The PR_DISPLAY_NAME column is the most commonly used; the PR_ACCOUNT column is also useful when it contains the user’s e-mail name.

For more information on ambiguous name resolution, see Address Book Restrictions.

See Also

IAddrBook::ResolveName, IABContainer::ResolveNames


PR_ASSISTANT

The PR_ASSISTANT property contains the name of the recipient’s administrative assistant.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A30
Property type:	PT_TSTRING
Property tag:	0x3A30001E (0x3A30001F for Unicode)
Remarks

The PR_ASSISTANT property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.

See Also

PR_ASSISTANT_TELEPHONE_NUMBER


PR_ASSISTANT_TELEPHONE_NUMBER

The PR_ASSISTANT_TELEPHONE_NUMBER property contains the telephone number of the recipient’s administrative assistant.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A2E
Property type:	PT_TSTRING
Property tag:	0x3A2E001E (0x3A2E001F for Unicode)
Remarks

The PR_ASSISTANT_TELEPHONE_NUMBER property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.

The telephone number is for the assistant specified in the PR_ASSISTANT property.


PR_ASSOC_CONTENT_COUNT

The PR_ASSOC_CONTENT_COUNT property contains the count of items in the associated contents table of the folder.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Folder objects
Identifier:	0x3617
Property type:	PT_LONG
Property tag:	0x36170003
Remarks

The PR_FOLDER_ASSOCIATED_CONTENTS property contains the associated contents table of the folder.

See Also

PR_ACCESS


PR_ATTACH_ADDITIONAL_INFO

The PR_ATTACH_ADDITIONAL_INFO property provides file type information for a non-Windows attachment.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Attachment subobjects
Identifier:	0x370F
Property type:	PT_BINARY
Property tag:	0x370F0102
Remarks

The PR_ATTACH_ADDITIONAL_INFO property is used to provide metadata about a particular attachment based on the attachment's encoding. For example, when the PR_ATTACH_ENCODING property contains MacBinary, PR_ATTACH_ADDITIONAL_INFO contains a string which represents the Macintosh file creator and file type, formatted as ":CREA:TYPE" for the encoded Macintosh file.


PR_ATTACH_DATA_BIN

The PR_ATTACH_DATA_BIN property contains binary attachment data typically accessed through the OLE IStream interface.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Attachment subobjects
Identifier:	0x3701
Property type:	PT_BINARY
Property tag:	0x37010102
Corresponding X.400 attribute:	IM_EXTERNAL_DATA or IM_BILATERAL_DATA
Remarks

The PR_ATTACH_DATA_BIN property holds the attachment when the value of the PR_ATTACH_METHOD property is ATTACH_BY_VALUE, which is the usual attachment method and the only one required to be supported. PR_ATTACH_DATA_BIN also holds an OLE 1.0 OLESTREAM attachment when the value of PR_ATTACH_METHOD is ATTACH_OLE.

OLESTREAM attachments can be copied into a file by calling the OLE IStream::CopyTo method. The OLE encoding type can be determined from the PR_ATTACH_TAG property.

For an OLE document file attachment, the message store provider must respond to an IMAPIProp::OpenProperty call on PR_ATTACH_DATA_OBJ and may optionally respond to a call on PR_ATTACH_DATA_BIN. Note that PR_ATTACH_DATA_BIN and PR_ATTACH_DATA_OBJ share the same property identifier and thus are two renditions of the same property.

For a storage object, such as a compound file in OLE 2.0 docfile format, some service providers allow it to be opened with the MAPI IStreamDocfile interface for improved performance. A provider supporting IStreamDocfile must expose it on PR_ATTACH_DATA_OBJ and may optionally expose it on PR_ATTACH_DATA_BIN.

For more information on OLE interfaces and formats, see the OLE Programmer’s Reference.


PR_ATTACH_DATA_OBJ

The PR_ATTACH_DATA_OBJ property contains an attachment object typically accessed through the OLE IStorage interface.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Attachment subobjects
Identifier:	0x3701
Property type:	PT_OBJECT
Property tag:	0x3701000D
Corresponding X.400 attribute	IM_EXTERNAL_DATA
Remarks

The PR_ATTACH_DATA_OBJ property holds the attachment when the value of the PR_ATTACH_METHOD property is ATTACH_EMBEDDED_MSG or ATTACH_OLE. The OLE encoding type can be determined from PR_ATTACH_TAG.

For an attachment associated with the ATTACH_EMBEDDED_MSG value, the IMessage:IMAPIProp inferface can be used for faster access.

For an embedded dynamic OLE object, the PR_ATTACH_DATA_OBJ property contains its own rendering information, and the PR_ATTACH_RENDERING property should be either nonexistent or empty.

For an OLE document file attachment, the message store provider must respond to an IMAPIProp::OpenProperty call on PR_ATTACH_DATA_OBJ and may optionally respond to a call on PR_ATTACH_DATA_BIN. The PR_ATTACH_DATA_BIN and PR_ATTACH_DATA_OBJ properties share the same property identifier and thus are two renditions of the same property.

For a storage object, such as a compound file in OLE 2.0 docfile format, some service providers allow it to be opened with the MAPI IStreamDocfile interface, a subclass of IStream with no additional members, designed to optimize performance. The potential saving is enough to justify attempting to open PR_ATTACH_DATA_OBJ through IStreamDocfile. If MAPI_E_INTERFACE_NOT_SUPPORTED is returned, the client can then open PR_ATTACH_DATA_BIN with IStream.

If the client application or service provider cannot open an attachment subobject using PR_ATTACH_DATA_OBJ with the help of PR_ATTACH_METHOD, it should use PR_ATTACH_DATA_BIN.

For more information on OLE interfaces and formats, see the OLE Programmer’s Reference.


PR_ATTACH_ENCODING

The PR_ATTACH_ENCODING property contains an ASN.1 object identifier specifying the encoding for an attachment.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Attachment subobjects
Identifier:	0x3702
Property type:	PT_BINARY
Property tag:	0x37020102
Remarks

The PR_ATTACH_ENCODING property identifies the algorithm used to transform the data in an attachment.

Note  The PR_ATTACH_ENCODING and PR_ATTACH_TAG properties should not be confused. They are not paired or related. PR_ATTACH_TAG identifies the application that originally generated the attachment. “Object” has a much more general meaning in the term object identifier, and in X.400, than in object-oriented programming.

The object identifier syntax and sample object identifiers are defined in the MAPIOID.H header file. Values for PR_ATTACH_ENCODING are not limited to those defined in MAPIOID.H. For example, attached Macintosh files can use an identifier such as MacBinary.

For complete information on these object identifiers, see the documentation on ASN.1, X.208, and X.209. The object identifier is found in the application-reference element of the FTBP (File Transfer Body Part) environment.


PR_ATTACH_EXTENSION

The PR_ATTACH_EXTENSION property contains a filename extension that indicates the document type of an attachment.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Attachment subobjects
Identifier:	0x3703
Property type:	PT_TSTRING
Property tag:	0x3703001E (0x3703001F for Unicode)
Remarks

The PR_ATTACH_EXTENSION property is set by the client application at submission time.

The messaging system uses PR_ATTACH_EXTENSION when converting message attachments (in-route conversion) or launching applications based on attachments in received messages. If the sending client does not provide a value for this property, the message store handling the attachment is not obligated to generate it. The receiving client should first check for PR_ATTACH_EXTENSION, and if it is not provided, should parse the filename extension from the attachment’s PR_ATTACH_FILENAME or PR_ATTACH_LONG_FILENAME property.


PR_ATTACH_FILENAME

The PR_ATTACH_FILENAME property contains an attachment’s base filename and extension, excluding path.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Attachment subobjects
Identifier:	0x3704
Property type:	PT_TSTRING
Property tag:	0x3704001E (0x3704001F for Unicode)
Corresponding X.400 attribute:	IM_EXTERNAL_PARAMETERS
Remarks

It is recommended that messaging user objects expose the PR_ATTACH_FILENAME property. PR_ATTACH_FILENAME pertains to the ATTACH_BY_VALUE, ATTACH_BY_REFERENCE, ATTACH_BY_REF_RESOLVE, and ATTACH_BY_REF_ONLY values of the PR_ATTACH_METHOD property. PR_ATTACH_FILENAME is required when any of these values is used.

PR_ATTACH_FILENAME can be used as a suggested filename for saving the attachment and to supply the filename extension if the PR_ATTACH_EXTENSION property is not provided.

The filename is restricted to eight characters plus a three-character extension. For a platform that supports long filenames, set both this property and the PR_ATTACH_LONG_FILENAME property.

MAPI works only with filenames, and other strings passed to it, in the ANSI character set. Client applications that use filenames in an OEM character set must convert them to ANSI before calling MAPI.


PR_ATTACH_LONG_FILENAME

The PR_ATTACH_LONG_FILENAME property contains an attachment’s long filename and extension, excluding path.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Attachment subobjects.
Identifier:	0x3707
Property type:	PT_TSTRING
Property tag:	0x3707001E (0x3707001F for Unicode)
Remarks

The PR_ATTACH_LONG_FILENAME property pertains to the ATTACH_BY_VALUE, ATTACH_BY_REFERENCE, ATTACH_BY_REF_RESOLVE, and ATTACH_BY_REF_ONLY values of the PR_ATTACH_METHOD property. Platforms that support long filenames should set both the PR_ATTACH_LONG_FILENAME and PR_ATTACH_FILENAME properties when sending, and should check PR_ATTACH_LONG_FILENAME first when receiving.

The client application should set this property to a suggested long filename to be used if the host computer receiving a message supports long filenames. PR_ATTACH_LONG_FILENAME can be used as a filename for saving the attachment, and to supply the filename extension if the PR_ATTACH_EXTENSION property is not provided.

Unlike the filename provided by PR_ATTACH_FILENAME, this name is not restricted to an eight-character filename plus a three-character extension. Instead, it can be up to 256 characters long, including the filename, extension, and separator period.

MAPI works only with filenames, and other strings passed to it, in the ANSI character set. Client applications that use filenames in an OEM character set must convert them to ANSI before calling MAPI.


PR_ATTACH_LONG_PATHNAME

The PR_ATTACH_LONG_PATHNAME property contains an attachment’s fully qualified long path and filename.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Attachment subobjects
Identifier:	0x370D
Property type:	PT_TSTRING
Property tag:	0x370D001E (0x370D001F for Unicode)
Remarks

The PR_ATTACH_LONG_PATHNAME property is applicable when you use any of the PR_ATTACH_METHOD property’s values that indicate attachment by reference: ATTACH_BY_REFERENCE, ATTACH_BY_REF_RESOLVE, or ATTACH_BY_REF_ONLY. Platforms that support long filenames should set both the PR_ATTACH_LONG_PATHNAME and PR_ATTACH_PATHNAME properties when sending, and should check PR_ATTACH_LONG_PATHNAME first when receiving.

The client application should set this property to a suggested long path and filename to be used if the host machine receiving a message supports long filenames. Setting PR_ATTACH_LONG_PATHNAME indicates that the attachment data is not included with the message but is available on a common file server.

Unlike the directories and filenames provided by PR_ATTACH_PATHNAME, these directories and filenames are not restricted to an eight-character directory or filename plus three-character extension. Instead, each directory or filename can be up to 256 characters long, including the name, extension, and separator period. However, the overall path is limited to 256 characters.

Clients should use a Universal Naming Convention (UNC) in most cases when the file is shared, and should use an absolute path when the file is local and in some shared cases, such as with NetWare®.

MAPI works only with paths, filenames, and other strings passed to it in the ANSI character set. Client applications that use paths and filenames in an OEM character set must convert them to ANSI before calling MAPI.


PR_ATTACH_METHOD

The PR_ATTACH_METHOD property contains a MAPI-defined constant representing the way the contents of an attachment can be accessed.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Attachment subobjects
Identifier:	0x3705
Property type:	PT_LONG
Property tag:	0x37050003
Remarks

The PR_ATTACH_METHOD property can have exactly one of the following values:

NO_ATTACHMENT

The attachment has just been created.

ATTACH_BY_VALUE

The PR_ATTACH_DATA_BIN property contains the attachment data.

ATTACH_BY_REFERENCE

The PR_ATTACH_PATHNAME or PR_ATTACH_LONG_PATHNAME property contains a fully qualified path identifying the attachment to recipients with access to a common file server.

ATTACH_BY_REF_RESOLVE

The PR_ATTACH_PATHNAME or PR_ATTACH_LONG_PATHNAME property contains a fully qualified path identifying the attachment.

ATTACH_BY_REF_ONLY

The PR_ATTACH_PATHNAME or PR_ATTACH_LONG_PATHNAME property contains a fully qualified path identifying the attachment.

ATTACH_EMBEDDED_MSG

The PR_ATTACH_DATA_OBJ property contains an embedded object that supports the IMessage interface.

ATTACH_OLE

The attachment is an embedded OLE object.

When created, all attachment objects have an initial PR_ATTACH_METHOD value of NO_ATTACHMENT.

Client applications and service providers are only required to support the attachment method represented by the ATTACH_BY_VALUE value. The other attachment methods are optional. The message store does not enforce any consistency between the value of PR_ATTACH_METHOD and the values of the other attachment properties.

Universal Naming Convention (UNC) names are recommended for fully qualified paths, which should be used with ATTACH_BY_REFERENCE and ATTACH_BY_REF_ONLY. With ATTACH_BY_REF_RESOLVE, an absolute path is faster, because the MAPI spooler converts the attachment to ATTACH_BY_VALUE.

If ATTACH_BY_REFERENCE is set, PR_ATTACH_DATA_BIN must be empty. An outbound gateway can turn an ATTACH_BY_REFERENCE attachment into an ATTACH_BY_VALUE attachment by copying the attachment data into the PR_ATTACH_DATA_BIN property.

If ATTACH_BY_REF_RESOLVE is set, PR_ATTACH_DATA_BIN must be empty. When the message that contains the ATTACH_BY_REF_RESOLVE attachment is sent, the MAPI spooler copies the attachment data into an ATTACH_BY_VALUE attachment. This resolution process places the attachment data in PR_ATTACH_DATA_BIN.

If ATTACH_BY_REF_ONLY is set, PR_ATTACH_DATA_BIN must be empty, and the messaging system never resolves the attachment reference. Use this value when you want to send the link but not the data.

When the OLE object is in OLE 2.0 IStorage format, the data are accessible through PR_ATTACH_DATA_OBJ. When the OLE object is in OLE 1.0 OLESTREAM format, the data are accessible through PR_ATTACH_DATA_BIN as an IStream. The type of the OLE encoding can be determined by the PR_ATTACH_TAG value.

For more information on OLE interfaces and formats, see the OLE Programmer’s Reference.

See Also

PR_STORE_SUPPORT_MASK


PR_ATTACH_MIME_TAG

The PR_ATTACH_MIME_TAG property contains formatting information about a Multipurpose Internet Mail Extensions (MIME) attachment.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Attachment subobjects
Identifier:	0x370E
Property type:	PT_TSTRING
Property tag:	0x370E001E (0x370E001F for Unicode)
Remarks

If the PR_ATTACH_TAG property contains the value OID_MIMETAG, the transport provider should look at the PR_ATTACH_MIME_TAG property to determine how the attachment is formatted.

PR_ATTACH_MIME_TAG is copied from the Content-type parameter of the inbound MIME header. The composition of the string is defined in the RFC 1521 document. The format is type/subtype, such as application/binary or text/plain.


PR_ATTACH_NUM

The PR_ATTACH_NUM property contains a number that uniquely identifies the attachment within its parent message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Attachment subobjects
Identifier:	0x3706
Property type:	PT_LONG
Property tag:	0x37060003
Remarks

Message stores generate and maintain the PR_ATTACH_NUM property. The attachment number is the secondary sort key, after the rendering position, in the attachment table.

PR_ATTACH_NUM is used to open the attachment with the IMessage::OpenAttach method. Within a client application’s session, the PR_ATTACH_NUM property of a message attachment remains constant as long as the attachment table is open.

The message store propagates changes to the table using the IMessage::CreateAttach and IMessage::DeleteAttach methods. At its option the message store can generate table notifications on open attachment tables so that clients can resynchronize to those changes.


PR_ATTACH_PATHNAME

The PR_ATTACH_PATHNAME property contains an attachment’s fully qualified path and filename.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Attachment subobjects
Identifier:	0x3708
Property type:	PT_TSTRING
Property tag:	0x3708001E (0x3708001F for Unicode)
Remarks

It is recommended that attachment subobjects expose the PR_ATTACH_PATHNAME property. Setting PR_ATTACH_PATHNAME indicates that the attachment data is not included with the message but is available on a common file server. PR_ATTACH_PATHNAME is required in conjunction with any of the PR_ATTACH_METHOD flags that indicate attachment by reference: ATTACH_BY_REFERENCE, ATTACH_BY_REF_RESOLVE, or ATTACH_BY_REF_ONLY.

Each directory or filename is restricted to an eight-character name plus a three-character extension. The overall path is restricted to 256 characters. For a platform that supports long filenames, set both the PR_ATTACH_PATHNAME and PR_ATTACH_LONG_PATHNAME properties.

Client applications should use a Universal Naming Convention (UNC) in most cases when the file is shared, and should use an absolute path when the file is local and in some shared cases, such as with NetWare.

MAPI works only with paths, filenames, and other strings passed to it in the ANSI character set. Clients that use paths and filenames in an OEM character set must convert them to ANSI before calling MAPI.

See Also

ScLocalPathFromUNC, ScUNCFromLocalPath


PR_ATTACH_RENDERING

The PR_ATTACH_RENDERING property contains a Microsoft Windows metafile with rendering information for an attachment.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Attachment subobjects
Identifier:	0x3709
Property type:	PT_BINARY
Property tag:	0x37090102
Remarks

The purpose of the PR_ATTACH_RENDERING property is to provide an icon or other pictorial representation that can be displayed within the parent message at the point of attachment. Such representation typically includes the name of the attachment, if any, and the nature of the attachment, such as a Microsoft Word document. A client application can use this representation in the display of the message.

For an attached file, PR_ATTACH_RENDERING usually portrays an icon for the file.

For an attached message, PR_ATTACH_RENDERING is typically not set. A client application needing to render an attached message should obtain its PR_MESSAGE_CLASS property, call IMAPIFormMgr::ResolveMessageClass for a pointer to the corresponding form information object, open the IMAPIFormInfo interface on that object, and use GetProps to retrieve the PR_ICON or PR_MINI_ICON property.

For an embedded static OLE object, PR_ATTACH_RENDERING contains a Microsoft Windows metafile that can be used to draw the attachment representation in a window.

For an embedded dynamic OLE object, the client should use the OLE data to generate the rendering information.

In all cases, the client application should be aware that PR_ATTACH_RENDERING is usually several hundred bytes in size and is subject to truncation in the attachment table. If a client wishes to render the attachment from PR_ATTACH_RENDERING without opening the attachment itself, it must work within the table truncation rule. For more information, see Working with Large Columns.


PR_ATTACH_SIZE

The PR_ATTACH_SIZE property contains the sum, in bytes, of the sizes of all properties on an attachment.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Attacment subobjects
Identifier:	0x0E20
Property type:	PT_LONG
Property tag:	0x0E200003
Remarks

It is recommended that attachment subobjects expose the PR_ATTACH_SIZE property. The sum contained in PR_ATTACH_SIZE includes the size of the PR_ATTACH_DATA_BIN or PR_ATTACH_DATA_OBJ property. Accordingly, PR_ATTACH_SIZE is usually larger than the contents of the attachment alone.

This property can be used to check the approximate size of the attachment before performing a remote transfer by modem and to display progress indicators when saving the attachment to disk. It is particularly useful with attached OLE objects.

See Also

PR_MESSAGE_SIZE


PR_ATTACH_TAG

The PR_ATTACH_TAG property contains an ASN.1 object identifier specifying the application that supplied an attachment.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Attachment subobjects
Identifier:	0x370A
Property type:	PT_BINARY
Property tag:	0x370A0102
Corresponding X.400 attribute:	IM_EXTERNAL_PARAMETERS
Remarks

The PR_ATTACH_TAG property identifies the application that originally generated the attachment.

Note  The PR_ATTACH_ENCODING and PR_ATTACH_TAG properties should not be confused. They are not paired or related. PR_ATTACH_ENCODING identifies the algorithm used to transform the data in an attachment. “Object” has a much more general meaning in the term object identifier, and in X.400 usage, than in object-oriented programming.

The object identifier syntax and sample object identifiers are defined in the MAPIOID.H header file. Values for PR_ATTACH_TAG are not limited to those defined in MAPIOID.H.

For complete information on these object identifiers, see the documentation on ASN.1, X.208, and X.209. The object identifier is found in the application-reference element of the File Transfer Body Part (FTBP) environment.

See Also

PR_ATTACH_MIME_TAG


PR_ATTACH_TRANSPORT_NAME

The PR_ATTACH_TRANSPORT_NAME property contains the name of an attachment file modified so that it can be correlated with TNEF messages.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Attachment subobjects
Identifier:	0x370C
Property type:	PT_TSTRING
Property tag:	0x370C001E (0x370C001F for Unicode)
Remarks

TNEF and the transport provider use the PR_ATTACH_TRANSPORT_NAME property. It is usually not available to client applications.

This property is commonly used by TNEF when the underlying messaging system doesn’t support the supplied filenames. For example, PR_ATTACH_TRANSPORT_NAME is used when the user attaches multiple files with the same name, such as five files named CONFIG.SYS. The transport provider must modify the names to ensure uniqueness. Each modified name appears in its attachment’s PR_ATTACH_TRANSPORT_NAME property.

MAPI works only with filenames, and other strings passed to it, in the ANSI character set. Applications that use filenames in an OEM character set must convert them to ANSI before calling MAPI.


PR_ATTACHMENT_X400_PARAMETERS

The PR_ATTACHMENT_X400_PARAMETERS property was originally meant to contain an ASN.1 object identifier specifying how the attachment should be handled during transmission.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3700
Property type:	PT_BINARY
Property tag:	0x37000102
Corresponding X.400 attribute:	IM_EXTERNAL_PARAMETERS
Remarks

Do not use this property. It is not supported in MAPI 1.0.


PR_AUTHORIZING_USERS

The PR_AUTHORIZING_USERS property contains a list of entry identifiers for users who have authorized the sending of a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0003
Property type:	PT_BINARY
Property tag:	0x00030102
Corresponding X.400 attribute:	IM_AUTHORIZING_USERS
Remarks

The message store does not maintain the PR_AUTHORIZING_USERS property.

See Also

PR_ENTRYID


PR_AUTO_FORWARD_COMMENT

The PR_AUTO_FORWARD_COMMENT property contains a comment added by the autoforwarding agent.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0004
Property type:	PT_TSTRING
Property tag:	0x0004001E (0x0004001F for Unicode)
Corresponding X.400 attribute:	IM_AUTO_FORWARD_COMMENT


PR_AUTO_FORWARDED

The PR_AUTO_FORWARDED property contains TRUE if an automatic agent has forwarded a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0005
Property type:	PT_BOOLEAN
Property tag:	0x0005000B
Corresponding X.400 attribute:	IM_AUTO_FORWARDED


PR_BODY

The PR_BODY property contains the message text.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x1000
Property type:	PT_TSTRING
Property tag:	0x1000001E (0x1000001F for Unicode)
Corresponding X.400 attribute:	IM_BODY and IM_TEXT
Remarks

The PR_BODY property is typically used only in an interpersonal message (IPM).

Message stores that support Rich Text Format (RTF) ignore any changes to white space in the message text. When PR_BODY is stored for the first time, the message store also generates and stores the PR_RTF_COMPRESSED property, the RTF version of the message text. If the IMAPIProp::SaveChanges method is subsequently called and PR_BODY has been modified, the message store calls the RTFSync function to ensure synchronization with the RTF version. If only white space has been changed, the properties are left unchanged. This preserves any nontrivial RTF formatting when the message travels through non-RTF-aware clients and messaging systems.

The value for PR_BODY must be expressed in the code page of the operating system that MAPI is running on.

See Also

PR_RTF_IN_SYNC


PR_BODY_CRC

The PR_BODY_CRC property contains a circular redundancy check (CRC) value on the message text.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0E1C
Property type:	PT_LONG
Property tag:	0x0E1C0003
Remarks

The message store can use any CRC algorithm that generates a PT_LONG value. It must compute PR_BODY_CRC as part of the IMAPIProp::SaveChanges method when the PR_BODY property has been set for the first time and whenever it has been subsequently modified.

A client application uses PR_BODY_CRC to aid in comparing message text strings contained in PR_BODY properties or their variants. Using this property, the client can quickly and easily detect when the message text has changed. It can realize significant performance gains by using PR_BODY_CRC instead of obtaining PR_BODY from the message store and comparing it with a local version.


PR_BUSINESS_FAX_NUMBER

The PR_BUSINESS_FAX_NUMBER property contains the telephone number of the recipient’s business fax machine.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A24
Property type:	PT_TSTRING
Property tag:	0x3A24001E (0x3A24001F for Unicode)
Remarks

The PR_BUSINESS_FAX_NUMBER property is one of the properties that provide identification and access information about a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_BUSINESS_TELEPHONE_NUMBER

The PR_BUSINESS_TELEPHONE_NUMBER property contains the primary telephone number of the recipient’s place of business.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A08
Property type:	PT_TSTRING
Property tag:	0x3A08001E (0x3A08001F for Unicode)
Remarks

The PR_BUSINESS_TELEPHONE_NUMBER property is one of the properties that provide identification and access information about a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.

MAPI also supports the PR_OFFICE_TELEPHONE_NUMBER property, which is synonymous with PR_BUSINESS_TELEPHONE_NUMBER.


PR_BUSINESS2_TELEPHONE_NUMBER

The PR_BUSINESS2_TELEPHONE_NUMBER property contains a secondary telephone number at the recipient’s place of business.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A1B
Property type:	PT_TSTRING
Property tag:	3A1B001E (3A1B001F for Unicode)
Remarks

The PR_BUSINESS2_TELEPHONE_NUMBER property is one of the properties that provide identification and access information about a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.

MAPI also supports the PR_OFFICE2_TELEPHONE_NUMBER property, which is synonymous with PR_BUSINESS2_TELEPHONE_NUMBER.

See Also

PR_BUSINESS_TELEPHONE_NUMBER


PR_CALLBACK_TELEPHONE_NUMBER

The PR_CALLBACK_TELEPHONE_NUMBER property contains a telephone number that the message recipient can use to reach the sender.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A02
Property type:	PT_TSTRING
Property tag:	0x3A02001E (0x3A02001F for Unicode)
Remarks

The PR_CALLBACK_TELEPHONE_NUMBER property is one of the properties that provide identification and access information about a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_CAPABILITIES_TABLE

The PR_CAPABILITIES_TABLE property was originally meant to contain an embedded table object to provide a summary of the address book capabilities.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3903
Property type:	PT_OBJECT
Property tag:	0x3903000D
Remarks

Do not use this property. It is not supported in MAPI 1.0.


PR_CAR_TELEPHONE_NUMBER

The PR_CAR_TELEPHONE_NUMBER property contains the recipient’s car telephone number.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A1E
Property type:	PT_TSTRING
Property tag:	0x3A1E001E (0x3A1E001F for Unicode)
Remarks

The PR_CAR_TELEPHONE_NUMBER property is one of the properties that provide identification and access information about a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_CLIENT_SUBMIT_TIME

The PR_CLIENT_SUBMIT_TIME property contains the date and time the message sender submitted a message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0039
Property type:	PT_SYSTIME
Property tag:	0x00390040
Corresponding X.400 attribute:	MH_T_SUBMISSION_TIME
Remarks

The store provider sets PR_CLIENT_SUBMIT_TIME to the time the client application calls IMessage::SubmitMessage.


PR_COMMENT

The PR_COMMENT property contains a comment about the purpose or content of an object.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	All objects
Identifier:	0x3004
Property type:	PT_TSTRING
Property tag:	0x3004001E (0x3004001F for Unicode)
Remarks

The content of the string is defined by the messaging user.


PR_COMMON_VIEWS_ENTRYID

The PR_COMMON_VIEWS_ENTRYID property contains the entry identifier of the predefined common view folder.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message store objects
Identifier:	0x35E6
Property type:	PT_BINARY
Property tag:	0x35E60102
Remarks

The common view folder contains a predefined set of standard view specifiers, while the view folder contains specifiers defined by a messaging user. These folders, which are not visible in the interpersonal message (IPM) hierarchy, can hold many view specifiers, each one stored as a message. A client application can choose to merge the two sets of specifiers and make them both available.

For more information on views, see View Folders.

See Also

PR_DEFAULT_VIEW_ENTRYID, PR_VIEWS_ENTRYID


PR_COMPANY_NAME

The PR_COMPANY_NAME property contains the recipient’s company name.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A16
Property type:	PT_TSTRING
Property tag:	0x3A16001E (0x3A16001F for Unicode)
Remarks

The PR_COMPANY_NAME property is one of the properties that provide identification and access information about a recipient. These properties are defined by the recipient and the recipient’s organization.


PR_CONTAINER_CLASS

The PR_CONTAINER_CLASS property was originally meant to contain a text string describing the type of a folder.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3613
Property type:	PT_TSTRING
Property tag:	0x3613001E (0x3613001F for Unicode)
Remarks

Do not use this property. It is not supported in MAPI 1.0.


PR_CONTAINER_CONTENTS

The PR_CONTAINER_CONTENTS property contains an embedded contents table object that provides information about a container.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Address book container and folder objects
Identifier:	0x360F
Property type:	PT_OBJECT
Property tag:	0x360F000D
Remarks

The PR_CONTAINER_CONTENTS property can be excluded in IMAPIProp::CopyTo operations or included in IMAPIProp::CopyProps operations. As a property of type PT_OBJECT, it cannot be successfully retrieved by the IMAPIProp::GetProps method; its contents should be accessed by the IMAPIProp::OpenProperty method, requesting the IID_IMAPITable interface identifier. Service providers must report it to the IMAPIProp::GetPropList method if it is set, but can optionally report it or not if it is not set.

To retrieve table contents, a client application should call the IMAPIContainer::GetContentsTable method. For more information, see Contents Tables.

The PR_CONTAINER_CONTENTS, PR_CONTAINER_HIERARCHY, and PR_FOLDER_ASSOCIATED_CONTENTS properties are similar in usage. Several MAPI properties provide access to tables:

Property	Table
PR_CONTAINER_CONTENTS	Contents table
PR_CONTAINER_HIERARCHY	Hierarchy table
PR_FOLDER_ASSOCIATED_CONTENTS	Associated contents table
PR_MESSAGE_ATTACHMENTS	Attachment table
PR_MESSAGE_RECIPIENTS	Recipient table


PR_CONTAINER_FLAGS

The PR_CONTAINER_FLAGS property contains a bitmask of flags describing capabilities of an address book container.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Address book container objects
Identifier:	0x3600
Property type:	PT_LONG
Property tag:	0x36000003
Remarks

One or more of the following flags can be set for the PR_CONTAINER_FLAGS bitmask:

AB_FIND_ON_OPEN

Displays a dialog box to request a restriction before displaying any contents of the container.

AB_MODIFIABLE

Entries can be added to and removed from the container. This flag does not indicate whether any entries in the container can be modified.

AB_RECIPIENTS

The container can hold recipients. This flag does not indicate whether any recipients are actually present in the container, nor whether they can be added or removed.

AB_SUBCONTAINERS

The container can hold child containers. This flag does not indicate whether any subcontainers are actually present in the container, nor whether they can be added or removed. AB_SUBCONTAINERS must be set for the container to support IMAPIContainer::GetHierarchyTable.

AB_UNMODIFIABLE

Entries cannot be added to or removed from the container. This flag does not indicate whether any entries in the container can be modified.

The AB_FIND_ON_OPEN flag is highly recommended for containers used with online services or with slow connections to servers. When a container is opened that has AB_FIND_ON_OPEN set, a Find dialog box is presented to the user to restrict the displayed messaging users. Even a partial specification limiting the messaging users can dramatically speed up a display of the contents.

Either the AB_MODIFIABLE or AB_UNMODIFIABLE flag must be set. Both flags can be set to indicate that the container does not know whether it can be modified or not, for example if modification depends on the user’s access rights. In this case, a client application must attempt a call and examine the return code to determine the container’s capabilities. A client typically starts by examining AB_MODIFIABLE. If it is set, the client makes a call that attempts to modify the container and checks the return value.

The AB_MODIFIABLE flag does not indicate what types of entries can be added to the container. To determine this, the client should use the appropriate OpenProperty method to open the container’s PR_CREATE_TEMPLATES property. Opening PR_CREATE_TEMPLATES causes the container’s one-off table to be returned, listing the kinds of entries that can be created in the container.


PR_CONTAINER_HIERARCHY

The PR_CONTAINER_HIERARCHY property contains an embedded hierarchy table object that provides information about the child containers.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Address book container and folder objects
Identifier:	0x360E
Property type:	PT_OBJECT
Property tag:	0x360E000D
Remarks

The PR_CONTAINER_HIERARCHY property can be excluded in IMAPIProp::CopyTo operations or included in IMAPIProp::CopyProps operations. As a property of type PT_OBJECT, it cannot be successfully retrieved by the IMAPIProp::GetProps method; its contents should be accessed by the IMAPIProp::OpenProperty method, requesting the IID_IMAPITable interface identifier. Service providers must report it to the IMAPIProp::GetPropList method if it is set, but can optionally report it or not if it is not set.

To retrieve table contents, a client application should call the IMAPIContainer::GetHierarchyTable method. For more information, see Hierarchy Tables.

The PR_CONTAINER_CONTENTS, PR_CONTAINER_HIERARCHY, and PR_FOLDER_ASSOCIATED_CONTENTS properties are similar in usage. Several MAPI properties provide access to tables:

Property	Table
PR_CONTAINER_CONTENTS	Contents table
PR_CONTAINER_HIERARCHY	Hierarchy table
PR_FOLDER_ASSOCIATED_CONTENTS	Associated contents table
PR_MESSAGE_ATTACHMENTS	Attachment table
PR_MESSAGE_RECIPIENTS	Recipient table


PR_CONTAINER_MODIFY_VERSION

The PR_CONTAINER_MODIFY_VERSION property was originally meant to contain the current modification version for a folder.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3614
Property type:	PT_I8
Property tag:	0x36140014
Remarks

Do not use this property. It is not supported in MAPI 1.0.


PR_CONTENT_CONFIDENTIALITY_ALGORITHM_ID

The PR_CONTENT_CONFIDENTIALITY_ALGORITHM_ID property contains an identifier for the algorithm used to confirm message content confidentiality.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0006
Property type:	PT_BINARY
Property tag:	0x00060102
Corresponding X.400 attribute:	MH_T_ALGORITHM_ID or MH_T_CONFIDENTIALITY_ALGORITHM
See Also

PR_SECURITY


PR_CONTENT_CORRELATOR

The PR_CONTENT_CORRELATOR property contains a value the message sender can use to match a report with the original message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0007
Property type:	PT_BINARY
Property tag:	0x00070102
Corresponding X.400 attribute:	MH_T_CONTENT_CORRELATOR
Remarks

The contents of the binary string are defined by the message originator. If set on an outgoing message, the PR_CONTENT_CORRELATOR property should be copied onto any reports generated in response to the message.


PR_CONTENT_COUNT

The PR_CONTENT_COUNT property contains the number of messages in a folder, as computed by the message store.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Folder objects
May be a column in:	Folder contents tables
Must be a column in:	Folder hierarchy tables
Identifier:	0x3602
Property type:	PT_LONG
Property tag:	0x36020003
Remarks

The number contained in the PR_CONTENT_COUNT property does not include associated entries in the folder. PR_CONTENT_UNREAD contains the count of unread messages for the folder. A client application can read but not change PR_CONTENT_COUNT and PR_CONTENT_UNREAD.


PR_CONTENT_IDENTIFIER

The PR_CONTENT_IDENTIFIER property contains a key value that enables the message recipient to identify its content.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0008
Property type:	PT_TSTRING
Property tag:	0x0008001E (0x0008001F for Unicode)
Corresponding X.400 attribute:	MH_T_CONTENT_IDENTIFIER


PR_CONTENT_INTEGRITY_CHECK

The PR_CONTENT_INTEGRITY_CHECK property contains an ASN.1 content integrity check value that allows a message sender to protect message content from disclosure to unauthorized recipients.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0C00
Property type:	PT_BINARY
Property tag:	0x0C000102
Corresponding X.400 attribute:	MH_T_INTEGRITY_CHECK
Remarks

The PR_CONTENT_INTEGRITY_CHECK property provides for non-repudiation of message content. In conjunction with PR_MESSAGE_TOKEN it ensures that the content of a message arrives at its destination unchanged.

See Also

PR_MESSAGE_SECURITY_LABEL


PR_CONTENT_LENGTH

The PR_CONTENT_LENGTH property contains a message length, in bytes, passed to a client application or service provider to determine if a message of that length can be delivered.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0009
Property type:	PT_LONG
Property tag:	0x00090003
Corresponding X.400 attribute:	MH_T_CONTENT_LENGTH


PR_CONTENT_RETURN_REQUESTED

The PR_CONTENT_RETURN_REQUESTED property contains TRUE if a message should be returned with a nondelivery report.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x000A
Property type:	PT_BOOLEAN
Property tag:	0x000A000B
Corresponding X.400 attribute:	MH_T_CONTENT_RETURN_REQUESTED
Remarks

If the PR_CONTENT_RETURN_REQUESTED property is not set, MAPI treats it as having a TRUE value.


PR_CONTENT_UNREAD

The PR_CONTENT_UNREAD property contains the number of unread messages in a folder, as computed by the message store.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Folder objects
May be a column in:	Folder contents tables
Must be a column in:	Folder hierarchy tables
Identifier:	0x3603
Property type:	PT_LONG
Property tag:	0x36030003
Remarks

The PR_CONTENT_UNREAD property contains the number of messages in the folder contents table for which the MSGFLAG_READ flag is not set in the PR_MESSAGE_FLAGS property. The PR_CONTENT_COUNT property contains the total message count for the folder. PR_CONTENT_COUNT and PR_CONTENT_UNREAD are read-only to clients.

Some client applications display the heading row of a category differently depending on the value of PR_CONTENT_UNREAD. For example, a client can display a category that includes unread messages in bold. PR_CONTENT_UNREAD cannot be used as a category and an attempt to do so results in the MAPI_E_INVALID_PARAMETER value being returned from the IMAPITable::SortTable method.

See Also

PR_CONTENT_IDENTIFIER


PR_CONTENTS_SORT_ORDER

The PR_CONTENTS_SORT_ORDER property was originally meant to contain a value specifying the sort order for the columns of a container.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x360D
Property type:	PT_MV_LONG
Property tag:	0x360D1003
Remarks

Do not use this property. It is not supported in MAPI 1.0.

See Also

SSortOrder


PR_CONTROL_FLAGS

The PR_CONTROL_FLAGS property contains a bitmask of flags governing the behavior of a control used in a dialog box built from a display table.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Display tables
Identifier:	0x3F00
Property type:	PT_LONG
Property tag:	0x3F000003
Remarks

One or more of the following flags can be set for PR_CONTROL_FLAGS:

DT_ACCEPT_DBCS

The control can have Double-Byte Character Set (DBCS) characters in it. This flag is used with edit controls. It allows multiple-byte character sets.

DT_EDITABLE

The control can be edited; the value associated with the control can be changed. When this flag is not set, the control is read-only. This value is ignored on label, group box, standard push button, multivalued drop down list box and list box controls.

DT_MULTILINE

The edit control can contain multiple lines. This means a return character can be entered within the control. This flag is valid for edit controls only.

DT_PASSWORD_EDIT

Applies to edit controls. The edit control is treated like a password. The value is displayed using asterisks instead of echoing the actual characters entered.

DT_REQUIRED

If the control allows changes (DT_EDITABLE), it must have a value before IMAPIProp::SaveChanges is called.

DT_SET_IMMEDIATE

Enables immediate setting of a value; as soon as a value in the control changes, MAPI calls the SetProps method for the property associated with that control. When this flag is not set, the values are set when the dialog box is dismissed.

DT_SET_SELECTION

When a selection is made within the list box, the index column of that list box is set as a property. Always used with DT_SET_IMMEDIATE.

The PR_CONTROL_FLAGS property is stored in the ulCtlFlags member of a control’s DTCTL structure. Most of the control flags apply to all of the controls that allow user input; a few apply only to the edit control. Controls that do not allow user input, such as a button or a label, set 0 for their control flags.

Many of the flag values are self-explanatory. For example, when DT_REQUIRED is set for a control, it must contain a value before the dialog box is allowed to be dismissed. Either the service provider can supply a value through its IMAPIProp implementation or the user can enter one. DT_EDITABLE indicates that the value for the control can be modified. DT_MULTILINE allows the value for an edit control to span multiple lines.

Some control flags are not so obvious in their meaning. When a control sets the DT_SET_IMMEDIATE flag, any changes to its value take affect as soon as the user moves to a new control. MAPI makes a single call to the property interface’s IMAPIProp::SetProps method for the control’s property. This is different from the default behavior, which is to postpone having changes to control values take effect until after the user selects the OK button or dismisses the dialog box. The DT_SET_IMMEDIATE flag is often used in combination with display table notifications.

The following table lists the types of controls and all of the flag values that can be set for each type.

Control	Valid values for PR_CONTROL_FLAGS
Button	Must be zero
Check box	DT_EDITABLE, DT_SET_IMMEDIATE
Combo box	DT_EDITABLE, DT_REQUIRED,  DT_SET_IMMEDIATE
Drop-down list box	DT_EDITABLE, DT_SET_IMMEDIATE
Edit	DT_ACCEPT_DBCS, DT_MULTILINE, DT_EDITABLE, DT_PASSWORD_EDIT, DT_REQUIRED, DT_SET_IMMEDIATE
Group box	Must be zero
Label	Must be zero
List box	Must be zero
Multivalue drop-down list box	Must be zero
Multivalue list box	Must be zero
Tabbed page	Must be zero
Radio button	Must be zero
See Also

DTCTL


PR_CONTROL_ID

The PR_CONTROL_ID property contains a unique identifier for a control used in a dialog box.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Display tables
Identifier:	0x3F07
Property type:	PT_BINARY
Property tag:	0x3F070102
Remarks

The PR_CONTROL_ID property contains a unique identifier for the control. This identifier should contain a GUID structure and a binary value of type LONG. All controls in the dialog box should use the same GUID to identify the service provider, and each control should use a unique LONG value to ensure that the controls do not collide.

PR_CONTROL_ID is used in notifications. For example, notifications sent on the display table must have PR_CONTROL_ID to uniquely identify the control to update.

See Also

DTCTL


PR_CONTROL_STRUCTURE

The PR_CONTROL_STRUCTURE property contains a pointer to a structure for a control used in a dialog box.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Display tables
Identifier:	0x3F01
Property type:	PT_BINARY
Property tag:	0x3F010102
Remarks

The PR_CONTROL_STRUCTURE property represents a long pointer that is cast to one of the control structures. The control structures include:

DTBLBUTTON	DTBLCHECKBOX
DTBLCOMBOBOX	DTBLDDLBX
DTBLEDIT	DTBLGROUPBOX
DTBLLABEL	DTBLLBX
DTBLMVDDLBOX	DTBLMVLISTBOX
DTBLPAGE	DTBLRADIOBUTTON
See Also

DTCTL


PR_CONTROL_TYPE

The PR_CONTROL_TYPE property contains a value indicating a control type for a control used in a dialog box.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Display tables
Identifier:	0x3F02
Property type:	PT_LONG
Property tag:	0x3F020003
Remarks

The PR_CONTROL_TYPE property can have exactly one of the following values:

DTCT_BUTTON

A dialog button control.

DTCT_CHECKBOX

A dialog check box.

DTCT_COMBOBOX

A dialog combo box.

DTCT_DDLBX

A dialog drop-down list box.

DTCT_EDIT

A dialog edit text box.

DTCT_GROUPBOX

A dialog group box.

DTCT_LABEL

A dialog label.

DTCT_LBX

A dialog list box.

DTCT_LISTBOX

A dialog list box.

DTCT_MVDDLBX

A multivalued list box populated by a multivalued property of type string.

DTCT_PAGE

A dialog tabbed page.

DTCT_RADIOBUTTON

A dialog radio button.

See Also

DTCTL


PR_CONVERSATION_INDEX

The PR_CONVERSATION_INDEX property contains an index that indicates the relative position of this message within a conversation thread.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0071
Property type:	PT_BINARY
Property tag:	0x00710102
Remarks

The conversation index is usually implemented using concatenated time stamp values. A message that represents a reply to another message concatenates a time stamp to the PR_CONVERSATION_INDEX value of the original message. All messages that have the same value for PR_CONVERSATION_TOPIC, can be sorted by PR_CONVERSATION_INDEX to indicate the hierarchical relationship of the messages.


PR_CONVERSATION_KEY

The PR_CONVERSATION_KEY property is the obsolete precursor of the PR_CONVERSATION_INDEX and PR_CONVERSATION_TOPIC properties.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x000B
Property type:	PT_BINARY
Property tag:	0x000B0102
Remarks

Do not use this property. Use PR_CONVERSATION_INDEX and PR_CONVERSATION_TOPIC instead.


PR_CONVERSATION_TOPIC

The PR_CONVERSATION_TOPIC property represents the topic of the first message in a conversation thread.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0070
Property type:	PT_TSTRING
Property tag:	0x0070001E (0x0070001F for Unicode)
Remarks

A conversation thread represents a series of messages and replies. The PR_CONVERSATION_TOPIC property is set for the first message in a thread, usually to the same value as the message subject, with any RE: and FW: strings removed. Subsequent messages in the conversation thread use the same PR_CONVERSATION_TOPIC. The PR_CONVERSATION_INDEX property indicates the order relationship between subsequent messages and replies.


PR_CONVERSION_EITS

The PR_CONVERSION_EITS property contains the encoded information types (EITs) that are applied to a message in transit to describe conversions.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x000C
Property type:	PT_BINARY
Property tag:	0x000C0102
Corresponding X.400 attribute:	IM_CONVERSION_EITS
Remarks

X.400 environments use the PR_CONVERSION_EITS property for both nondelivery reports and delivery reports.


PR_CONVERSION_PROHIBITED

The PR_CONVERSION_PROHIBITED property contains TRUE if message conversions are prohibited by default for the associated messaging user.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x3A03
Property type:	PT_BOOLEAN
Property tag:	0x3A03000B
Corresponding X.400 attribute:	MH_T_CONVERSION_PROHIBITED


PR_CONVERSION_WITH_LOSS_PROHIBITED

The PR_CONVERSION_WITH_LOSS_PROHIBITED property contains TRUE if a message transfer agent (MTA) is prohibited from making message text conversions that lose information.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x000D
Property type:	PT_BOOLEAN
Property tag:	0x000D000B
Corresponding X.400 attribute:	MH_T_CONVERSION_LOSS_PROHIBITED
Remarks

An example of the type of conversion being prohibited is the “lossy” mapping from Unicode (two bytes per character) to a single-byte character set.


PR_CONVERTED_EITS

The PR_CONVERTED_EITS property contains an identifier for the types of text in a message after conversion.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x000E
Property type:	PT_BINARY
Property tag:	0x000E0102
Corresponding X.400 attribute:	MH_T_CONVERTED_EITS
Remarks

The PR_CONVERTED_EITS property indicates which encoded information types (EITs) were used to convert the text components of the message.


PR_CORRELATE

The PR_CORRELATE property contains TRUE if the sender of a message requests the correlation feature of the messaging system.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0E0C
Property type:	PT_BOOLEAN
Property tag:	0x0E0C000B
Remarks

The PR_CORRELATE property is used to request the correlation of incoming reports with the original sent message. When a transport provider encounters a submitted message with PR_CORRELATE set to TRUE, it sets the PR_CORRELATE_MTSID property to the message transfer system (MTS) identifier for that message.

PR_CORRELATE should be used with messaging systems that support correlation by MTS identifier, such as X.400.


PR_CORRELATE_MTSID

The PR_CORRELATE_MTSID property contains the message transfer system (MTS) identifier used in correlating reports with sent messages.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0E0D
Property type:	PT_BINARY
Property tag:	0x0E0D0102
Remarks

When a transport provider encounters a submitted message with the PR_CORRELATE property set to TRUE, it sets the PR_CORRELATE_MTSID property to the MTS identifier for that message. Following transmission, PR_CORRELATE_MTSID is stored with the message in the interpersonal message (IPM) Sent Items folder.

Messaging systems that support correlation by MTS identifier, such as X.400, retain the identifier as part of the transport envelope of the original message and also of any reports generated in response to it. When a report is delivered from such a messaging system, the transport provider sets PR_CORRELATE_MTSID to the original MTS identifier from the report’s transport envelope. PR_CORRELATE_MTSID will then be stored with the report.

A client application can maintain a search-results folder of all messages having a PR_CORRELATE_MTSID property. When a report comes in for such a message, the client can apply restrictions to the search-results folder, find the original version of the message, and correlate the original message information with the new information.


PR_COUNTRY

The PR_COUNTRY property contains the name of the recipient’s country.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A26
Property type:	PT_TSTRING
Property tag:	0x3A26001E (0x3A26001F for Unicode)
Remarks

The PR_COUNTRY property is one of the properties that provide identification and access information about a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_CREATE_TEMPLATES

The PR_CREATE_TEMPLATES property contains an embedded table object that contains dialog box template entry identifiers.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Address book container objects
Identifier:	0x3604
Property type:	PT_OBJECT
Property tag:	0x3604000D
Remarks

To learn what template objects can be created inside a container, call the IMAPIProp::OpenProperty method on the PR_CREATE_TEMPLATES property. The resulting object is the one-off table that gives the entry identifiers for all the templates you can create inside the container.

To subsequently create the template objects, call the container object’s CreateEntry method on the PR_ENTRYID column values from the one-off table.

See Also

IABContainer::CreateEntry, PR_DISPLAY_NAME, PR_DISPLAY_TYPE


PR_CREATION_TIME

The PR_CREATION_TIME property contains the creation date and time for a message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x3007
Property type:	PT_SYSTIME
Property tag:	0x30070040
Remarks

A message store sets the PR_CREATION_TIME property for each message that it creates.

See Also

PR_CREATION_VERSION


PR_CREATION_VERSION

The PR_CREATION_VERSION property was originally meant to contain the message store version current at the time a message was created.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x0E19
Property type:	PT_I8
Property tag:	0x0E190014
Remarks

Do not use this property. It is not supported in MAPI 1.0.

See Also

PR_CURRENT_VERSION, PR_MODIFY_VERSION


PR_CURRENT_VERSION

The PR_CURRENT_VERSION property was originally meant to contain the current version of a message store.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x0E00
Property type:	PT_I8
Property tag:	0x0E000014
Remarks

Do not use this property. It is not supported in MAPI 1.0.

See Also

PR_CREATION_VERSION, PR_MODIFY_VERSION


PR_DEF_CREATE_DL

The PR_DEF_CREATE_DL property contains the template entry identifier for a default distribution list object.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Address book container objects
Identifier:	0x3611
Property type:	PT_BINARY
Property tag:	0x36110102
Remarks

Client applications use the PR_DEF_CREATE_DL property to create a distribution list within a container. Support of entry creation is optional for address book containers; those that do not support it are not required to expose this property.

PR_DEF_CREATE_DL specifies an entry that can appear in the PR_CREATE_TEMPLATES property for distribution lists. After obtaining the identifier, the client uses it in a call to the IABContainer::CreateEntry method. The entry represents the template for the default distribution list.

See Also

IABLogon::CompareEntryIDs


PR_DEF_CREATE_MAILUSER

The PR_DEF_CREATE_MAILUSER property contains the template entry identifier for a default messaging user object.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Address book container objects
Identifier:	0x3612
Property type:	PT_BINARY
Property tag:	0x36120102
Remarks

Client applications use the PR_DEF_CREATE_MAILUSER property to create a messaging user object within a container. Support of entry creation is optional for address book containers; those that do not support it are not required to expose this property.

PR_DEF_CREATE_MAILUSER specifies an entry that can appear in the PR_CREATE_TEMPLATES property for messaging users. After obtaining the identifier, the client uses it in a call to the IABContainer::CreateEntry method. The entry represents the template for the default messaging user.

See Also

IABLogon::CompareEntryIDs


PR_DEFAULT_PROFILE

The PR_DEFAULT_PROFILE property contains TRUE if a messaging user profile is the MAPI default profile.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Profile section objects
Identifier:	0x3D04
Property type:	PT_BOOLEAN
Property tag:	0x3D04000B
Remarks

The PR_DEFAULT_PROFILE property does not appear as a property of any object but only as a column in a profile table. A client application can use the IProfAdmin::SetDefaultProfile method to designate the default profile.

See Also

PR_DEFAULT_STORE


PR_DEFAULT_STORE

The PR_DEFAULT_STORE property contains TRUE if a message store is the default message store in the message store table.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message store objects
Identifier:	0x3400
Property type:	PT_BOOLEAN
Property tag:	0x3400000B
Remarks

The PR_DEFAULT_STORE property appears as a column in the message store table. The value is based on PR_RESOURCE_FLAGS.

See Also

PR_RESOURCE_FLAGS


PR_DEFAULT_VIEW_ENTRYID

The PR_DEFAULT_VIEW_ENTRYID property contains the entry identifier of a folder’s default view.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Folder objects
Identifier:	0x3616
Property type:	PT_BINARY
Property tag:	0x36160102
Remarks

The PR_DEFAULT_VIEW_ENTRYID property is the entry identifier of the folder view that should be set as the initial view. The property need not be set if the “Normal” view is to be used as the initial view.

A client application can obtain PR_DEFAULT_VIEW_ENTRYID at the time it opens the folder and realize significant performance gains. PR_DEFAULT_VIEW_ENTRYID can be used as a shortcut to obtain the default view, instead of opening the associated contents table and submitting a restriction.

A service provider implementation of the IMAPIFolder::CopyFolder method can copy this property when it copies folders.

See Also

PR_COMMON_VIEWS_ENTRYID, PR_VIEWS_ENTRYID


PR_DEFERRED_DELIVERY_TIME

The PR_DEFERRED_DELIVERY_TIME property contains the date and time at which a message sender wants a message delivered.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x000F
Property type:	PT_SYSTIME
Property tag:	0x000F0040
Corresponding X.400 attribute:	MH_T_DEFERRED_DELIVERY_TIME
Remarks

MAPI does not perform the deferred delivery; it is an option of the underlying messaging system to handle deferred delivery.


PR_DELEGATION

The PR_DELEGATION property contains the converted value of the attDelegate workgroup property.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects used in scheduling
Identifier:	0x007E
Property type:	PT_BINARY
Property tag:	0x007E0102
Remarks

The PR_DELEGATION property is used for compatibility with earlier versions of Schedule+. TNEF computes it on messages for Schedule+ 7.0 and compatible versions. Client applications should not use PR_DELEGATION.

In inbound messages to Schedule+ 7.0, the workgroup property attDelegate is decoded into PR_DELEGATION. TNEF constructs PR_DELEGATION in current recipient table order. If a client calling TNEF has provided a recipient table for use in the ITnef::EncodeRecips method, that table is used to build the delegation properties.

PR_DELEGATION is not encoded into attDelegate in outbound messages. Instead, attDelegate is built from the PR_RCVD_REPRESENTING_EMAIL_ADDRESS property if the message is generated by Schedule+, and not built at all otherwise.


PR_DELETE_AFTER_SUBMIT

The PR_DELETE_AFTER_SUBMIT property contains TRUE if a client application wants MAPI to delete the associated message after submission.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0E01
Property type:	PT_BOOLEAN
Property tag:	0x0E01000B
Remarks

A client application uses the PR_DELETE_AFTER_SUBMIT property with the PR_SENTMAIL_ENTRYID property to control what happens to a message after it is submitted. Either one or the other should be set, but not both.


PR_DELIVER_TIME

The PR_DELIVER_TIME property contains the date and time at which the original message was delivered.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects used for delivery reports
Identifier:	0x0010
Property type:	PT_SYSTIME
Property tag:	0x00100040
Corresponding X.400 attribute:	MH_T_DELIVERY_TIME
Remarks

The PR_DELIVER_TIME property is a per-recipient property on a delivery report that indicates the time the original message was delivered to the messaging user for which the delivery report is being generated.

See Also

IMAPISupport::StatusRecips


PR_DELIVERY_POINT

The PR_DELIVERY_POINT property specifies the nature of the functional entity by means of which a message was or would have been delivered to the recipient.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects used on reports
Identifier:	0x0C07
Property type:	PT_LONG
Property tag:	0x0C070003
Corresponding X.400 attribute:	MH_T_DELIVERY_POINT
Remarks

The PR_DELIVERY_POINT property can have exactly one of the following values:

MAPI_MH_DP_ML

Delivered to a distribution list, a delivery point which in turn may distribute the message to many recipients.

MAPI_MH_DP_MS

Delivered to a message store instead of directly to a recipient.

MAPI_MH_DP_OTHER_AU

Delivered to an access unit (AU) other than a physical delivery access unit (PDAU), such as a FAX system.

MAPI_MH_DP_PDAU

Delivered to a physical delivery access unit, such as a human postal carrier.

MAPI_MH_DP_PDS_PATRON

Delivered to a physical delivery system patron, such as a conventional postal mailbox.

MAPI_MH_DP_PRIVATE_UA

Delivered to a private user agent (UA), such as a client in an in-house messaging system.

MAPI_MH_DP_PUBLIC_UA

Delivered to a public user agent, or public service provider.

The default value is MAPI_MH_DP_PRIVATE_UA, that is, a MAPI client.


PR_DELTAX

The PR_DELTAX property contains the width of a dialog box control in standard Windows dialog units.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Display tables
Identifier:	0x3F03
Property type:	PT_LONG
Property tag:	0x3F030003
Remarks

The PR_XPOS, PR_YPOS, PR_DELTAX, and PR_DELTAY properties position and size the dialog box control.


PR_DELTAY

The PR_DELTAY property contains the height of a dialog box control in standard Windows dialog units.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Display tables
Identifier:	0x3F04
Property type:	PT_LONG
Property tag:	0x3F040003
Remarks

The PR_XPOS, PR_YPOS, PR_DELTAX, and PR_DELTAY properties position and size the dialog box control.


PR_DEPARTMENT_NAME

The PR_DEPARTMENT_NAME property contains a name for the department in which the recipient works.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A18
Property type:	PT_TSTRING
Property tag:	0x3A18001E (0x3A18001F for Unicode)
Remarks

The PR_DEPARTMENT_NAME property is one of the properties that provide identification and access information about a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_DEPTH

The PR_DEPTH property represents the relative level of indentation, or depth, of an object in a hierarchy table.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Contents tables and hierarchy tables
Identifier:	0x3005
Property type:	PT_LONG
Property tag:	0x30050003
Remarks

The PR_DEPTH property can also specify the categorization level of a row in a contents table or the hierarchy depth in a hierarchy table. The depth is zero-based, where zero represents the leftmost category. In all cases, the property value represents a relative value rather than an absolute value. In the hierarchy table, for example, the depth value is relative to the container from which the hierarchy table was retrieved. The depth does not represent an absolute depth from the root container.

See Also

PR_OBJECT_TYPE, PR_SELECTABLE


PR_DETAILS_TABLE

The PR_DETAILS_TABLE property contains an embedded display table object.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Address book container, distribution list, and messaging user objects
Identifier:	0x3605
Property type:	PT_OBJECT
Property tag:	0x3605000D
Remarks

Passing the PR_DETAILS_TABLE property to the IMAPIProp::OpenProperty method for the object returns an IMAPITable interface that allows creation of the display table. MAPI uses this table to display property sheets for an address book object in response to an IAddrBook::Details call.

For more information, see Display Tables.

See Also

IAddrBook::RecipOptions, IMAPISession::MessageOptions, PR_CREATE_TEMPLATES, PR_SEARCH


PR_DISC_VAL

The PR_DISC_VAL property is the obsolete precursor of the PR_DISCRETE_VALUES property.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x004A
Property type:	PT_BOOLEAN
Property tag:	0x004A000B
Remarks

Do not use this property. Use PR_DISCRETE_VALUES.

See Also

PR_DISCRETE_VALUES


PR_DISCARD_REASON

The PR_DISCARD_REASON property contains a reason why a message transfer agent (MTA) has discarded a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0011
Property type:	PT_LONG
Property tag:	0x00110003
Corresponding X.400 attribute:	IM_DISCARD_REASON
Remarks

The reason contained in the PR_DISCARD_REASON property is used in a nondelivery report for the message.

See Also

PR_NDR_REASON_CODE


PR_DISCLOSURE_OF_RECIPIENTS

The PR_DISCLOSURE_OF_RECIPIENTS property contains TRUE if disclosure of recipients is allowed.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0012
Property type:	PT_BOOLEAN
Property tag:	0x0012000B
Corresponding X.400 attribute:	MH_T_DISCLOSURE_ALLOWED


PR_DISCRETE_VALUES

The PR_DISCRETE_VALUES property contains TRUE if a nondelivery report applies only to discrete members of a distribution list rather than the entire list.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message recipient subobjects used on nondelivery reports
Identifier:	0x0E0E
Property type:	PT_BOOLEAN
Property tag:	0x0E0E000B
Remarks

The PR_DISCRETE_VALUES property is used within a nondelivery report when the message could not be delivered to one or more members of a distribution list. Its purpose is to limit retransmission attempts to only those individual members and not the distribution list as a whole.

The recipient table of a nondelivery report contains entries for all recipients the message could not be delivered to, and also for the distribution lists, if any, to which they belong. The transport provider should set PR_DISCRETE_VALUES to TRUE for each distribution list entry, and it should copy PR_DISPLAY_NAME, PR_ENTRYID, and PR_SEARCH_KEY from the distribution list to PR_ORIGINAL_DISPLAY_NAME, PR_ORIGINAL_ENTRYID, and PR_ORIGINAL_SEARCH_KEY for each member of that distribution list.

PR_DISCRETE_VALUES should not be set at all for any nondelivery report recipient entry other than a distribution list.


PR_DISPLAY_BCC

The PR_DISPLAY_BCC property contains an ASCII list of the display names of any blind carbon copy (BCC) message recipients, separated by semicolons (;).

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0E02
Property type:	PT_TSTRING
Property tag:	0x0E02001E (0x0E02001F for Unicode)
Corresponding X.400 attribute:	IM_BLIND_COPY_RECIPIENTS
Remarks

The message store computes the PR_DISPLAY_BCC property on message objects using the IMessage::ModifyRecipients method. The message store also maintains the property so that it always reflects the last saved state of a message. The value is synchronized at the time of every call to the IMAPIProp::SaveChanges method.

If a message has no blind carbon copy recipients, the message store should respond to an IMAPIProp::GetProps call with a return value of S_OK and an empty string for PR_DISPLAY_BCC.

Because of the possible need for localization, MAPI provides some guidelines for blind carbon copy recipient names:

•	All names should be able to be localized.

•	The semicolon should be the character that is used to separate names in the PR_DISPLAY_BCC property.

•	Clients must translate the semicolon encountered in the PR_DISPLAY_BCC property to a localized separator character before making the property information visible in the user interface.

Note  Semicolons cannot be used within recipient names in MAPI messaging.


PR_DISPLAY_CC

The PR_DISPLAY_CC property contains an ASCII list of the display names of any carbon copy (CC) message recipients, separated by semicolons (;).

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0E03
Property type:	PT_TSTRING
Property tag:	0x0E03001E (0x0E03001F for Unicode)
Corresponding X.400 attribute:	IM_COPY_RECIPIENTS
Remarks

The message store computes the PR_DISPLAY_CC property on message objects using the IMessage::ModifyRecipients method. The message store also maintains the property so that it always reflects the last saved state of a message. The value is synchronized at the time of every call to IMAPIProp::SaveChanges.

If a message has no carbon copy recipients, the message store should respond to an IMAPIProp::GetProps call with a return value of S_OK and an empty string for PR_DISPLAY_CC.

Because of the possible need for localization, MAPI provides some guidelines for blind carbon copy recipient names:

•	All names should be able to be localized.

•	The semicolon should be the character that is used to separate names in the PR_DISPLAY_CC property.

•	Clients must translate the semicolon encountered in the PR_DISPLAY_CC property to a localized separator character before making the property information visible in the user interface.

•	When forwarding messages, clients do not need to translate the separator character on the carbon copy recipient line.

Note  Semicolons cannot be used within recipient names in MAPI messaging.


PR_DISPLAY_NAME

The PR_DISPLAY_NAME property contains the display name for a given MAPI object.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Folder, messaging user, provider, and status objects
Identifier:	0x3001
Property type:	PT_TSTRING
Property tag:	0x3001001E (0x3001001F for Unicode)
Corresponding X.400 attribute:	IM_FREE_FORM_NAME
Remarks

Folders require sibling subfolders to have unique display names. For example, if a folder contains two subfolders, the two subfolders cannot use the same value for their PR_DISPLAY_NAME properties. This restriction does not apply to other containers, such as address books and distribution lists.

PR_DISPLAY_NAME is one of the base address properties for all messaging users. For more information on the base address properties, see Base Address Properties.

Service providers should set the value of PR_DISPLAY_NAME so that it contains both the provider type and configuration information. The additional information helps to distinguish between instances of providers of the same type. Unconfigured providers should use a string that names the provider. Configured providers should use the same string followed by a distinguishing string in parentheses. For example, an unconfigured message store provider might set PR_DISPLAY_NAME to Personal Information Store, while the configured version could set PR_DISPLAY_NAME to Personal Information Store (July 31, 1996).

For status objects, this property contains the name of the component that can be displayed by the user interface.

Note  Semicolons cannot be used within recipient names in MAPI messaging.

See Also

PR_TRANSMITTABLE_DISPLAY_NAME


PR_DISPLAY_TO

The PR_DISPLAY_TO property contains an ASCII list of the display names of the primary (To) message recipients, separated by semicolons (;).

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0E04
Property type:	PT_TSTRING
Property tag:	0x0E04001E (0x0E04001F for Unicode)
Corresponding X.400 attribute:	IM_PRIMARY_RECIPIENTS
Remarks

The message store computes the PR_DISPLAY_TO property on message objects using the IMessage::ModifyRecipients method. The message store also maintains the property so that it always reflects the last saved state of a message. The value is synchronized at the time of every call to the IMAPIProp::SaveChanges method.

If a message has no primary recipients, the message store should respond to an IMAPIProp::GetProps call with a return value of S_OK and an empty string for PR_DISPLAY_TO.

Because of the possible need for localization, MAPI provides some guidelines for blind carbon copy recipient names:

•	All names should be able to be localized.

•	The semicolon should be the character that is used to separate names in the PR_DISPLAY_TO property.

•	Clients must translate the semicolon encountered in the PR_DISPLAY_TO property to a localized separator character before making the property information visible in the user interface.

•	When forwarding messages, clients do not need to translate the separator character on the primary recipient line.

Note  Semicolons cannot be used within recipient names in MAPI messaging.


PR_DISPLAY_TYPE

The PR_DISPLAY_TYPE property contains a value used to associate an icon with a particular row of a table.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Address book contents tables, address book hierarchy tables, folder hierarchy tables, and one-off tables
Identifier:	0x3900
Property type:	PT_LONG
Property tag:	0x39000003
Remarks

The PR_DISPLAY_TYPE property contains a long integer that facilitates special treatment of the table entry based on its type. This special treatment typically consists of displaying an icon, or other display element, associated with the display type.

PR_DISPLAY_TYPE is not used in folder contents tables. Client applications should use a message’s PR_MESSAGE_CLASS property and appropriate IMAPIFormInfo interface to get the PR_ICON and PR_MINI_ICON properties for that message.

PR_DISPLAY_TYPE can have exactly one of the following values:

DT_AGENT

An automated agent, such as Quote-Of-The-Day or a weather chart display.

DT_DISTLIST

A distribution list.

DT_FOLDER

Display default folder icon adjacent to folder.

DT_FOLDER_LINK

Display default folder link icon adjacent to folder rather than the default folder icon.

DT_FOLDER_SPECIAL

Display icon for a folder with an application-specific distinction, such as a special type of public folder.

DT_FORUM

A forum, such as a bulletin board service or a public or shared folder.

DT_GLOBAL

A global address book.

DT_LOCAL

A local address book that you share with a small workgroup.

DT_MAILUSER

A typical messaging user.

DT_MODIFIABLE

Modifiable; the container should be denoted as modifiable in the user interface.

DT_NOT_SPECIFIC

Does not match any of the other settings.

DT_ORGANIZATION

A special alias defined for a large group, such as helpdesk, accounting, or blood-drive coordinator.

DT_PRIVATE_DISTLIST

A private, personally administered distribution list.

DT_REMOTE_MAILUSER

A recipient known to be from a foreign or remote messaging system.

DT_WAN

A wide area network address book.

Address book contents tables use the DT_AGENT, DT_DISTLIST, DT_FORUM, DT_MAILUSER, DT_ORGANIZATION, DT_PRIVATE_DISTLIST, and DT_REMOTE_MAILUSER values. Address book hierarchy tables and one-off tables use the DT_GLOBAL, DT_LOCAL, DT_MODIFIABLE, DT_NOT_SPECIFIC, and DT_WAN values. Folder hierarchy tables use the DT_FOLDER, DT_FOLDER_LINK, and DT_FOLDER_SPECIAL values.

If PR_DISPLAY_TYPE is not set, the client should assume the default type appropriate for the table, typically DT_FOLDER, DT_LOCAL, or DT_MAILUSER.

Note  All values not documented are reserved for MAPI. Client applications must not define any new values and must be prepared to deal with an undocumented value.


PR_DL_EXPANSION_HISTORY

The PR_DL_EXPANSION_HISTORY property contains a history showing how a distribution list has been expanded during message transmission.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0013
Property type:	PT_BINARY
Property tag:	0x00130102
Corresponding X.400 attribute:	MH_T_EXPANSION_HISTORY
Remarks

The PR_DL_EXPANSION_HISTORY property is available to receiving client applications if the transport provider has set it. It is also available to the sending client if the message content is returned with a report.

See Also

PR_DL_EXPANSION_PROHIBITED


PR_DL_EXPANSION_PROHIBITED

The PR_DL_EXPANSION_PROHIBITED property contains TRUE if a message transfer agent (MTA) is prohibited from expanding distribution lists.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0014
Property type:	PT_BOOLEAN
Property tag:	0x0014000B
Corresponding X.400 attribute:	MH_T_EXPANSION_PROHIBITED
See Also

PR_DL_EXPANSION_HISTORY


PR_EMAIL_ADDRESS

The PR_EMAIL_ADDRESS property contains the messaging user’s e-mail address.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Distribution list and messaging user objects
Identifier:	0x3003
Property type:	PT_TSTRING
Property tag:	0x3003001E (0x3003001F for Unicode)
Remarks

The PR_EMAIL_ADDRESS property is one of the base address properties for all messaging users. It is a null-terminated string whose format has meaning only for the underlying messaging system.

PR_EMAIL_ADDRESS is used in conjunction with the PR_ADDRTYPE and PR_MESSAGE_CLASS properties in addressing messages. The string format is qualified by PR_ADDRTYPE.

Valid PR_EMAIL_ADDRESS examples include:

network/postoffice/user

Bruce@XYZZY.COM

/c=US/a=att/p=Microsoft/o=Finance/ou=Purchasing/s=Furthur/g=Joe

For more information on the base address properties, see Base Address Properties. For more information on address types, see Address Types.


PR_END_DATE

The PR_END_DATE property contains the ending date and time of an appointment as managed by a scheduling application.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects used in scheduling
Identifier:	0x0061
Property type:	PT_SYSTIME
Property tag:	0x00610040
Remarks

Scheduling applications should set both the PR_START_DATE and PR_END_DATE properties when sending meeting requests.


PR_ENTRYID

The PR_ENTRYID property contains a MAPI entry identifier used to open and edit properties of a particular MAPI object.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Address book container, distribution list, folder, messaging user, message, message store, and status objects
Identifier:	0x0FFF
Property type:	PT_BINARY
Property tag:	0x0FFF0102
Remarks

The PR_ENTRYID property identifies an object for OpenEntry to instantiate and provides access to all of its properties through the appropriate derived interface of IMAPIProp.

PR_ENTRYID is one of the base address properties for all messaging users. For more information on the base address properties, see Base Address Properties.

PR_ENTRYID can contain either a long-term or a short-term identifier. Short-term identifiers are easier and faster to construct, but are limited in their scope and duration, typically to the current session and workstation. They are commonly used for objects of a temporary nature, such as table rows or dialog box entries, and then abandoned. Long-term identifiers are used for objects of a more wide-ranging and long-lasting nature.

PR_ENTRYID is always available through the IMAPIProp::GetProps method following the first call to the IMAPIProp::SaveChanges method. Some service providers can make it available immediately after instantiation. The provider must always return a long-term entry identifier from GetProps. Therefore, to convert a short-term identifier to long-term, simply open the object and get its PR_ENTRYID through GetProps.

The following table summarizes important differences among PR_ENTRYID, PR_RECORD_KEY, and PR_SEARCH_KEY.

Characteristic	PR_ENTRYID	PR_RECORD_KEY	PR_SEARCH_KEY
Required on attachment objects	No	Yes	No
Required on folder objects	Yes	Yes	No
Required on message store objects	Yes	Yes	No
Required on status objects	Yes	No	No
Created by client	No	No	Yes
Available before call to SaveChanges	Maybe	Maybe	Messages — Yes Others — Maybe
Changed in a copy operation	Yes	Yes	No
Changeable by client after a copy	No	No	Yes
Unique within	Entire world	Provider instance	Entire world
Binary comparable (as with memcmp)	No — use IMAPISupport:: CompareEntryIDs	Yes	Yes
See Also

ENTRYID, NOTIFICATION, PR_STORE_ENTRYID


PR_EXPIRY_TIME

The PR_EXPIRY_TIME property contains the date and time at which the messaging system can invalidate the content of a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0015
Property type:	PT_SYSTIME
Property tag:	0x00150040
Corresponding X.400 attribute:	IM_EXPIRY_TIME
Remarks

The PR_EXPIRY_TIME property is used to direct the messaging system in handling delivered interpersonal messages.


PR_EXPLICIT_CONVERSION

The PR_EXPLICIT_CONVERSION property indicates that a message sender has requested a message content conversion for a particular recipient.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects
Identifier:	0x0C01
Property type:	PT_LONG
Property tag:	0x0C010003
Corresponding X.400 attribute:	MH_T_EXPLICIT_CONVERSION


PR_FILTERING_HOOKS

The PR_FILTERING_HOOKS property was originally meant to contain hook identifiers.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3D08
Property type:	PT_BINARY
Property tag:	0x3D080102
Remarks

Do not use this property. It is not supported in MAPI 1.0.


PR_FINDER_ENTRYID

The PR_FINDER_ENTRYID property contains the entry identifier for the folder in which search results are typically created.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message store objects
Identifier:	0x35E7
Property type:	PT_BINARY
Property tag:	0x35E70102
Remarks

The entry identifier contained in the PR_FINDER_ENTRYID property has the same format as the ENTRYID structure.

See Also

PR_ENTRYID


PR_FOLDER_ASSOCIATED_CONTENTS

The PR_FOLDER_ASSOCIATED_CONTENTS property contains an embedded contents table object that provides information about the associated contents table.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Folder objects
Identifier:	0x3610
Property type:	PT_OBJECT
Property tag:	0x3610000D
Remarks

The associated contents table represents a subfolder that does not appear in the standard contents table. It contains the folder’s associated, or hidden, messages.

The PR_FOLDER_ASSOCIATED_CONTENTS property can be excluded in IMAPIProp::CopyTo operations or included in IMAPIProp::CopyProps operations. As a property of type PT_OBJECT, it cannot be successfully retrieved by the IMAPIProp::GetProps method; its contents should be accessed by the IMAPIProp::OpenProperty method, requesting the IID_IMAPITable interface identifier. Service providers must report it to the IMAPIProp::GetPropList method if it is set, but may optionally report it or not if it is not set.

To retrieve table contents, client applications should call the IMAPIContainer::GetContentsTable method. For more information on folder contents tables, see Contents Tables and Displaying a Folder Contents Table.

The PR_CONTAINER_CONTENTS, PR_CONTAINER_HIERARCHY, and PR_FOLDER_ASSOCIATED_CONTENTS properties are similar in usage. Several MAPI properties provide access to tables:

Property	Table
PR_CONTAINER_CONTENTS	Contents table
PR_CONTAINER_HIERARCHY	Hierarchy table
PR_FOLDER_ASSOCIATED_CONTENTS	Associated contents table
PR_MESSAGE_ATTACHMENTS	Attachment table
PR_MESSAGE_RECIPIENTS	Recipient table
See Also

PR_ASSOC_CONTENT_COUNT


PR_FOLDER_TYPE

The PR_FOLDER_TYPE property contains a constant that indicates the folder type.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Folder objects
Identifier:	0x3601
Property type:	PT_LONG
Property tag:	0x36010003
Remarks

The PR_FOLDER_TYPE property can have exactly one of the following values:

FOLDER_GENERIC

A generic folder that contains messages and other folders.

FOLDER_ROOT

The root folder of the folder hierarchy table, that is, a folder that has no parent folder.

FOLDER_SEARCH

A folder containing the results of a search, in the form of links to messages that meet search criteria.

The root of a message store should not be confused with the root of the interpersonal message (IPM) subtree in that store. The store’s root folder, which has no parent, is obtained by calling the IMsgStore::OpenEntry method with a null entry identifier. The IPM subtree’s root folder, which does have a parent, is obtained by using the value of the PR_IPM_SUBTREE_ENTRYID property for the OpenEntry call.

MAPI allows only one root folder per message store. This folder contains messages and other folders. The root folder’s PR_PARENT_ENTRYID property contains the folder’s own entry identifier.

The information in a search-results folder is mainly stored in its contents table, which contains the same columns as a typical contents table, as well as two extra columns identifying the folder in which each message was found: PR_PARENT_DISPLAY (display name, required) and PR_PARENT_ENTRYID (entry identifier, optional).

For more information on folder types, see Folders.


PR_FORM_CATEGORY

The PR_FORM_CATEGORY property contains the category of a form.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Form objects
Identifier:	0x3309
Property type:	PT_TSTRING
Property tag:	0x3309001E (0x3309001F for Unicode)
Remarks

The category name is defined by a client application in a way that is appropriate to the application.


PR_FORM_CATEGORY_SUB

The PR_FORM_CATEGORY_SUB property contains the subcategory of a form, as defined by a client application.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Form objects
Identifier:	0x3310
Property type:	PT_TSTRING
Property tag:	0x3310001E (0x3310001F for Unicode)
Remarks

The PR_FORM_CATEGORY_SUB property is subordinate to the main form category provided in the PR_FORM_CATEGORY property.


PR_FORM_CLSID

The PR_FORM_CLSID property contains the 128-bit OLE globally unique identifier (GUID) of a form.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Form objects
Identifier:	0x3307
Property type:	PT_CLSID
Property tag:	0x33070048
Remarks

The MAPIUID structure contains the definition of the unique identifier.


PR_FORM_CONTACT_NAME

The PR_FORM_CONTACT_NAME property contains the name of a contact for information concerning a form.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Form objects
Identifier:	0x3308
Property type:	PT_TSTRING
Property tag:	0x3308001E (0x3308001F for Unicode)
Remarks

The contact typically contains the name of a person or an alias that is responsible for maintaining the form.


PR_FORM_DESIGNER_GUID

The PR_FORM_DESIGNER_GUID property contains the unique identifier for the object used to design a form.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Form objects
Identifier:	0x3314
Property type:	PT_CLSID
Property tag:	0x33140048
Remarks

The PR_FORM_DESIGNER_GUID property usually contains the globally unique identifier of the design program used to create the form. This property can be empty.

The MAPIUID structure contains the definition of the unique identifier.


PR_FORM_DESIGNER_NAME

The PR_FORM_DESIGNER_NAME property contains the display name for the object used to design the form.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Form objects
Identifier:	0x3313
Property type:	PT_TSTRING
Property tag:	0x3313001E (0x3313001F for Unicode)
Remarks

The PR_FORM_DESIGNER_GUID property contains the unique identifier for the form designer object.


PR_FORM_HIDDEN

The PR_FORM_HIDDEN property contains TRUE if a form is to be suppressed from display by compose menus and dialog boxes.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Form objects
Identifier:	0x3312
Property type:	PT_BOOLEAN
Property tag:	0x3312000B
Remarks

Form-related properties are read-only.


PR_FORM_HOST_MAP

The PR_FORM_HOST_MAP property contains a host map of available forms.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Address book container objects
Identifier:	0x3311
Property type:	PT_LONG
Property tag:	0x33110003
Remarks

A client application should update the PR_FORM_HOST_MAP property, along with the PR_DISPLAY_NAME property, when changing the underlying structure in the IMAPIFormProp interface.


PR_FORM_MESSAGE_BEHAVIOR

The PR_FORM_MESSAGE_BEHAVIOR property contains TRUE if a message should be composed in the current folder.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Form objects
Identifier:	0x3315
Property type:	PT_BOOLEAN
Property tag:	0x3315000B
Remarks

A value of FALSE indicates that the message should be composed as any other interpersonal message, that is, in the Outbox folder.


PR_FORM_VERSION

The PR_FORM_VERSION property contains the version of a form.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Form objects
Identifier:	0x3306
Property type:	PT_TSTRING
Property tag:	0x3306001E (0x3306001F for Unicode)
Remarks

The form version is a string indicating what design version is currently in effect for the form. The version is defined and maintained by the form’s designer and is not necessarily related to any MAPI component version.


PR_GENERATION

The PR_GENERATION property contains a generational abbreviation that follows the full name of the recipient.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A05
Property type:	PT_TSTRING
Property tag:	0x3A05001E (0x3A05001F for Unicode)
Corresponding X.400 attribute:	MH_T_GENERATION
Remarks

The PR_GENERATION property is one of the properties that provide identification and access information about a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.

Common PR_GENERATION values include Jr., Sr., and III.


PR_GIVEN_NAME

The PR_GIVEN_NAME property contains the first name of the recipient.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A06
Property type:	PT_TSTRING
Property tag:	0x3A06001E (0x3A06001F for Unicode)
Corresponding X.400 attribute:	MH_T_GIVEN_NAME
Remarks

The PR_GIVEN_NAME property is one of the properties that provide identification and access information about a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_GOVERNMENT_ID_NUMBER

The PR_GOVERNMENT_ID_NUMBER property contains a government identifier for the recipient.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A07
Property type:	PT_TSTRING
Property tag:	0x3A07001E (0x3A07001F for Unicode)
Remarks

The PR_GOVERNMENT_ID_NUMBER property is one of the properties that provide identification and access information about a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.

PR_GOVERNMENT_ID_NUMBER is commonly set to a passport number, citizen number, or taxpayer number such as a Social Security number.


PR_HASATTACH

The PR_HASATTACH property contains TRUE if a message contains at least one attachment.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0E1B
Property type:	PT_BOOLEAN
Property tag:	0x0E1B000B
Remarks

The message store copies the PR_HASATTACH property from the MSGFLAG_HASATTACH flag of the PR_MESSAGE_FLAGS property. A client application can then use PR_HASATTACH to sort on message attachments in a message viewer.

The value of PR_HASATTACH is updated with the IMAPIProp::SaveChanges method.


PR_HEADER_FOLDER_ENTRYID

The PR_HEADER_FOLDER_ENTRYID property was originally meant to contain the entry identifier that a remote transport provider furnishes for its header folder.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3E0A
Property type:	PT_BINARY
Property tag:	0x3E0A0102
Remarks

Do not use this property. It is not supported in MAPI 1.0.

For information on obtaining the header folder for the purpose of viewing remote message headers, see Implementing the IUnknown Interface for Folder Objects for Remote Transports.

See Also

PR_ENTRYID, PR_MSG_STATUS


PR_HOME_FAX_NUMBER

The PR_HOME_FAX_NUMBER property contains the telephone number of the recipient’s home fax machine.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A25
Property type:	PT_TSTRING
Property tag:	0x3A25001E (0x3A25001F for Unicode)
Remarks

The PR_HOME_FAX_NUMBER property is one of the properties that provide identification and access information about a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_HOME_TELEPHONE_NUMBER

The PR_HOME_TELEPHONE_NUMBER property contains the primary telephone number of the recipient’s home.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A09
Property type:	PT_TSTRING
Property tag:	0x3A09001E (0x3A09001F for Unicode)
Remarks

The PR_HOME_TELEPHONE_NUMBER property is one of the properties that provide identification and access for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.

See Also

PR_HOME2_TELEPHONE_NUMBER


PR_HOME2_TELEPHONE_NUMBER

The PR_HOME2_TELEPHONE_NUMBER property contains a secondary telephone number at the recipient’s home.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A2F
Property type:	PT_TSTRING
Property tag:	0x3A2F001E (0x3A2F001F for Unicode)
Remarks

The PR_HOME2_TELEPHONE_NUMBER property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.

See Also

PR_HOME_TELEPHONE_NUMBER


PR_ICON

The PR_ICON property contains a bitmap of a full size icon for a form.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Form objects
Identifier:	0x0FFD
Property type:	PT_BINARY
Property tag:	0x0FFD0102
Remarks

The PR_ICON property contains a 32 × 32 pixel image of an icon, the same as the contents of a .ICO file. This property is normally copied from the .ICO file specified in the LargeIcon line of the appropriate [Description] section of the form configuration file.

See Also

PR_MINI_ICON


PR_IDENTITY_DISPLAY

The PR_IDENTITY_DISPLAY property contains the display name for a service provider’s identity as defined within a messaging system.

Quick Info

Header file:	MAPITAGS.H
May be a column in:	Status tables
Identifier:	0x3E00
Property type:	PT_TSTRING
Property tag:	0x3E00001E (0x3E00001F for Unicode)
Remarks

The PR_IDENTITY_DISPLAY property does not appear as a property on any object but only as a column in a status table. It is part of the identity of the service provider exposing the status table row. The provider’s identity typically refers to its account on the server, but can refer to any representation the provider defines within the messaging system.

A service provider furnishing any of the identity properties should furnish all of them. Providers that belong to the same message service should expose the same values for the identity properties.

See Also

IMAPISession::QueryIdentity


PR_IDENTITY_ENTRYID

The PR_IDENTITY_ENTRYID property contains the entry identifier for a service provider’s identity as defined within a messaging system.

Quick Info

Header file:	MAPITAGS.H
May be a column in:	Status tables
Identifier:	0x3E01
Property type:	PT_BINARY
Property tag:	0x3E010102
Remarks

The PR_IDENTITY_ENTRYID property does not appear as a property on any object but only as a column in a status table. It is part of the identity of the service provider exposing the status table row. The provider’s identity typically refers to its account on the server, but can refer to any representation the provider defines within the messaging system.

PR_IDENTITY_ENTRYID is commonly set to the appropriate address book entry identifier.

A service provider furnishing any of the identity properties should furnish all of them. Providers that belong to the same message service should expose the same values for the identity properties.

See Also

IMAPISession::QueryIdentity


PR_IDENTITY_SEARCH_KEY

The PR_IDENTITY_SEARCH_KEY property contains the search key for a service provider’s identity as defined within a messaging system.

Quick Info

Header file:	MAPITAGS.H
May be a column in:	Status tables
Identifier:	0x3E05
Property type:	PT_BINARY
Property tag:	0x3E050102
Remarks

The PR_IDENTITY_SEARCH_KEY property does not appear as a property on any object but only as a column in a status table. It is part of the identity of the service provider exposing the status table row. The provider’s identity typically refers to its account on the server, but can refer to any representation the provider defines within the messaging system.

A service provider furnishing any of the identity properties should furnish all of them. Providers that belong to the same message service should expose the same values for the identity properties.

See Also

IMAPISession::QueryIdentity


PR_IMPLICIT_CONVERSION_PROHIBITED

The PR_IMPLICIT_CONVERSION_PROHIBITED property contains TRUE if a message transfer agent (MTA) is prohibited from making implicit message text conversions.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0016
Property type:	PT_BOOLEAN
Property tag:	0x0016000B
Remarks

If the PR_IMPLICIT_CONVERSION_PROHIBITED property is TRUE, the messaging system must not perform any content conversion on the message unless it is explicitly requested on a per-recipient basis with the PR_EXPLICIT_CONVERSION property.


PR_IMPORTANCE

The PR_IMPORTANCE property contains a value indicating the message sender’s opinion of the importance of a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0017
Property type:	PT_LONG
Property tag:	0x00170003
Corresponding X.400 attribute:	IM_IMPORTANCE
Remarks

The PR_IMPORTANCE and PR_PRIORITY properties should not be confused. Importance indicates a value to users, while priority indicates the order or speed at which the message should be sent by the messaging system software. Higher priority usually indicates a higher cost. Higher importance usually is associated with a different display by the user interface.

PR_IMPORTANCE can have exactly one of the following values:

IMPORTANCE_LOW

The message has low importance.

IMPORTANCE_HIGH

The message has high importance.

IMPORTANCE_NORMAL

The message has normal importance.


PR_INCOMPLETE_COPY

The PR_INCOMPLETE_COPY property contains TRUE if this message is an incomplete copy of another message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0035
Property type:	PT_BOOLEAN
Property tag:	0x0035000B
Corresponding X.400 attribute:	IM_INCOMPLETE_COPY


PR_INITIAL_DETAILS_PANE

The PR_INITIAL_DETAILS_PANE property contains the property page in a property sheet to be displayed first.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Display tables
Identifier:	0x3F08
Property type:	PT_LONG
Property tag:	0x3F080003
Remarks

The PR_INITIAL_DETAILS_PANE property contains the zero-based index of the initial foreground pane that appears when a client application displays a details table for an object that exposes property sheets. The value indicates which page should be displayed first. This property appears in an object from which a display table can be obtained.

See Also

IMAPISupport::DoConfigPropSheet


PR_INITIALS

The PR_INITIALS property contains the initials for parts of the full name of the recipient.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A0A
Property type:	PT_TSTRING
Property tag:	0x3A0A001E (0x3A0A001F for Unicode)
Corresponding X.400 attribute:	MH_T_INITIALS
Remarks

The PR_INITIALS property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.

Examples of PR_INITIALS values are AJT, GMcD, JL, RCKJr, and WMSIII.


PR_INSTANCE_KEY

The PR_INSTANCE_KEY property contains a value that uniquely identifies a row in a table.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	All tables
Identifier:	0x0FF6
Property type:	PT_BINARY
Property tag:	0x0FF60102
Remarks

The PR_INSTANCE_KEY property is a binary value that uniquely identifies a row in a table view. PR_INSTANCE_KEY is a required column in most tables. If a row is included in two views, there will be two different instance keys. The instance key of a row may differ each time the table is opened, but remains constant while the table is open. Rows added while a table is in use do not reuse an instance key that was previously used.

Use the PR_ENTRYID or PR_RECORD_KEY properties to correlate all the rows of an expansion. Use PR_INSTANCE_KEY to locate a particular instance within the expansion.

When a multivalued property is expanded in a table, a row is created for each instance of the expansion, that is, for each value of that property. Each row has a unique value for the PR_INSTANCE_KEY property, while all the other columns retain their original values throughout the expansion.

In a categorized sort of a table, rows not corresponding to actual data can be added to the result of the sort. Each such row, like all rows in all tables, has its own unique instance key.

PR_INSTANCE_KEY is also used in table event notifications. The propIndex and propPrior members of the TABLE_NOTIFICATION structure are SPropValue structures holding PR_INSTANCE_KEY values. The propIndex member indicates the row that was added or changed. The propPrior member indicates the row before the added or changed row (PR_NULL indicates a change to the first row).

This value is not copied as part of the display table.

PR_INSTANCE_KEY is a MAPIUID structure. All instance keys can be directly compared as binary values.


PR_IPM_ID

The PR_IPM_ID property was originally meant to contain an X.400 identifier of an interpersonal message.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x0018
Property type:	PT_BINARY
Property tag:	0x00180102
Remarks

Do not use this property. It is not supported in MAPI 1.0.


PR_IPM_OUTBOX_ENTRYID

The PR_IPM_OUTBOX_ENTRYID property contains the entry identifier of the standard interpersonal message (IPM) Outbox folder.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message store objects
Identifier:	0x35E2
Property type:	PT_BINARY
Property tag:	0x35E20102
Remarks

Outbound messages are usually created in the Outbox folder. Interpersonal messages should be placed in this folder for submission.

See Also

PR_ENTRYID


PR_IPM_OUTBOX_SEARCH_KEY

The PR_IPM_OUTBOX_SEARCH_KEY property was originally meant to contain the search key of the standard Outbox folder.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3411
Property type:	PT_BINARY
Property tag:	0x34110102
Remarks

Do not use this property. It is not supported in MAPI 1.0.


PR_IPM_RETURN_REQUESTED

The PR_IPM_RETURN_REQUESTED property contains TRUE if this message should be returned with a report.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0C02
Property type:	PT_BOOLEAN
Property tag:	0x0C02000B
Corresponding X.400 attribute:	IM_IPM_RETURN_REQUESTED


PR_IPM_SENTMAIL_ENTRYID

The PR_IPM_SENTMAIL_ENTRYID property contains the entry identifier of the standard interpersonal message (IPM) Sent Items folder.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message store objects
Identifier:	0x35E4
Property type:	PT_BINARY
Property tag:	0x35E40102
Remarks

After being sent, interpersonal messages are usually placed in the Sent Items folder. A client can use the PR_IPM_SENTMAIL_ENTRYID property to set the PR_SENTMAIL_ENTRYID property on a submitted message.

See Also

PR_ENTRYID


PR_IPM_SENTMAIL_SEARCH_KEY

The PR_IPM_SENTMAIL_SEARCH_KEY property was originally meant to contain the search key of the standard Sent Items folder.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3413
Property type:	PT_BINARY
Property tag:	0x34130102
Remarks

Do not use this property. It is not supported in MAPI 1.0.


PR_IPM_SUBTREE_ENTRYID

The PR_IPM_SUBTREE_ENTRYID property contains the entry identifier of the root of the interpersonal message (IPM) folder subtree in the message store’s folder tree.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message store objects
Identifier:	0x35E0
Property type:	PT_BINARY
Property tag:	0x35E00102
Remarks

The PR_IPM_SUBTREE_ENTRYID property represents the root of the IPM hierarchy. IPM clients should not display any folders that are not subfolders of the folder represented by PR_IPM_SUBTREE_ENTRYID.

See Also

PR_ENTRYID


PR_IPM_SUBTREE_SEARCH_KEY

The PR_IPM_SUBTREE_SEARCH_KEY property was originally meant to contain the search key of the interpersonal message (IPM) root folder.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3410
Property type:	PT_BINARY
Property tag:	0x34100102
Remarks

Do not use this property. It is not supported in MAPI 1.0.


PR_IPM_WASTEBASKET_ENTRYID

The PR_IPM_WASTEBASKET_ENTRYID property contains the entry identifier of the standard interpersonal message (IPM) Deleted Items folder.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message store objects
Identifier:	0x35E3
Property type:	PT_BINARY
Property tag:	0x35E30102
Remarks

A client application should move deleted interpersonal messages to the Deleted Items folder. If the message is already in this folder, or if the PR_IPM_WASTEBASKET_ENTRYID property is not supported, the client should delete the message.

See Also

PR_ENTRYID


PR_IPM_WASTEBASKET_SEARCH_KEY

The PR_IPM_WASTEBASKET_SEARCH_KEY property was originally meant to contain the search key of the standard Deleted Items folder.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3412
Property type:	PT_BINARY
Property tag:	0x34120102
Remarks

Do not use this property. It is not supported in MAPI 1.0.


PR_ISDN_NUMBER

The PR_ISDN_NUMBER property contains the recipient’s ISDN-capable telephone number.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A2D
Property type:	PT_STRING
Property tag:	0x3A2D001E
Remarks

The PR_ISDN_NUMBER property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_KEYWORD

The PR_KEYWORD property contains a keyword identifying the recipient to the recipient’s system administrator.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A0B
Property type:	PT_TSTRING
Property tag:	0x3A0B001E (0x3A0B001F for Unicode)
Remarks

The PR_KEYWORD property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.

The contents of the keyword string property are defined based on the needs of the recipient’s organization.


PR_LANGUAGE

The PR_LANGUAGE property contains a value indicating the language in which the messaging user is writing messages.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A0C
Property type:	PT_TSTRING
Property tag:	0x3A0C001E (0x3A0C001F for Unicode)
Remarks

The string contains a single two-character country code.

See Also

PR_LANGUAGES


PR_LANGUAGES

The PR_LANGUAGES property contains an ASCII list of the languages incorporated in a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x002F
Property type:	PT_TSTRING
Property tag:	0x002F001E (0x002F001F for Unicode)
Corresponding X.400 attribute:	IM_LANGUAGES
Remarks

The underlying string is a sequence of two-character country codes separated by commas.

See Also

PR_LANGUAGE


PR_LAST_MODIFICATION_TIME

The PR_LAST_MODIFICATION_TIME property contains the date and time the object or subobject was last modified.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	All objects including attachment subobjects
Identifier:	0x3008
Property type:	PT_SYSTIME
Property tag:	0x30080040
Remarks

The PR_LAST_MODIFICATION_TIME property is initially set to the same value as the PR_CREATION_TIME property. Attachment subobjects can update it as necessary by copying the last modification time maintained by the native file system. A client applicatin can set this property until the first call to the IMAPIProp::SaveChanges method. From then on the provider should update PR_LAST_MODIFICATION_TIME during every SaveChanges call.


PR_LATEST_DELIVERY_TIME

The PR_LATEST_DELIVERY_TIME property contains the latest date and time when a message transfer agent (MTA) should deliver a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0019
Property type:	PT_SYSTIME
Property tag:	0x00190040
Corresponding X.400 attribute:	MH_T_LATEST_DELIVERY_TIME
Remarks

If an MTA cannot deliver a message by the time the PR_LATEST_DELIVERY_TIME property specifies, it cancels the message without delivery.


PR_LOCALITY

The PR_LOCALITY property contains the name of the recipient’s locality, such as the town or city.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A27
Property type:	PT_TSTRING
Property tag:	0x3A27001E (0x3A27001F for Unicode)
Remarks

The PR_LOCALITY property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_LOCATION

The PR_LOCATION property contains the location of the recipient in a format that is useful to the recipient’s organization.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A0D
Property type:	PT_TSTRING
Property tag:	0x3A0D001E (0x3A0D001F for Unicode)
Remarks

The PR_LOCATION property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.

The contents of PR_LOCATION are defined by the needs of the recipient’s organization. For example, some organizations might identify messaging users by specifying the building number and office number.


PR_MAIL_PERMISSION

The PR_MAIL_PERMISSION property contains TRUE if the messaging user is allowed to send and receive messages.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A0E
Property type:	PT_BOOLEAN
Property tag:	0x3A0E000B
Remarks

If the PR_MAIL_PERMISSION property is not set, MAPI treats it as having a TRUE value.

An example of PR_MAIL_PERMISSION being set to FALSE is a corporate directory where some of the entries are not e-mail-enabled.


PR_MAPPING_SIGNATURE

The PR_MAPPING_SIGNATURE property contains the mapping signature for named properties of a particular MAPI object.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Objects having named properties
Identifier:	0x0FF8
Property type:	PT_BINARY
Property tag:	0x0FF80102
Remarks

It is recommended that objects having named properties expose the PR_MAPPING_SIGNATURE property. A client application should check the PR_MAPPING_SIGNATURE property of both objects when copying named properties from one object to another. Use of this property can minimize translating between copied properties’ names and identifiers.

If PR_MAPPING_SIGNATURE does not exist for a given MAPI object, then the object has its own unique mapping of names and identifiers. In this case the client must call the IMAPIProp::GetNamesFromIDs method on the source object and then the IMAPIProp::GetIDsFromNames method on the destination object.

When two objects have the same PR_MAPPING_SIGNATURE value, the client does not need to translate name to identifier and identifier to name. The client can simply call the IMAPIProp::GetProps method on the source and then the IMAPIProp::SetProps method on the destination. This is convenient for clients that perform custom copying of named properties, and for providers implementing the IMAPIProp::CopyTo and IMAPIProp::CopyProps methods.

For more information on named properties and mapping of names and identifiers, see Named Properties.

See Also

MAPINAMEID


PR_MDB_PROVIDER

The PR_MDB_PROVIDER property contains a provider-defined MAPIUID structure that indicates the type of the message store.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message store objects
Must be a column in:	Message store tables
Identifier:	0x3414
Property type:	PT_BINARY
Property tag:	0x34140102
Remarks

The MAPIUID structure identifies the type of message store. The value is computed by message store providers on message store objects and is unique to each provider. It is typically used for browsing through the message store table to find a store of the desired type, such as public folders.

PR_MDB_PROVIDER is analogous to the PR_AB_PROVIDER_ID for address books.


PR_MESSAGE_ATTACHMENTS

The PR_MESSAGE_ATTACHMENTS property contains a table of restrictions that can be applied to a contents table to find all messages that contain attachment subobjects meeting the restrictions.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0E13
Property type:	PT_OBJECT
Property tag:	0x0E13000D
Remarks

The PR_MESSAGE_ATTACHMENTS property can be excluded in IMAPIProp::CopyTo operations or included in IMAPIProp::CopyProps operations. As a property of type PT_OBJECT, it cannot be successfully retrieved by the IMAPIProp::GetProps method; its contents should be accessed by the IMAPIProp::OpenProperty method, requesting the IID_IMAPITable interface identifier. Service providers must report it to the IMAPIProp::GetPropList method if it is set, but may optionally report it or not if it is not set.

To retrieve table contents, a client application should call the IMessage::GetAttachmentTable method. For more information, see Attachment Tables.

PR_MESSAGE_ATTACHMENTS can be used for subobject restriction by specifying it in the SSubRestriction structure. This allows the client to limit the view of a container to messages with attachments meeting given criteria. A message qualifies for viewing if at least one row in its attachments table, that is, one attachment, satisfies the subobject restriction.

Note

Using subobject restriction results in the equivalent of an IMAPISession::OpenEntry call on every message in the table. Depending on the client application and the number of messages to be searched, it can affect performance.

The PR_MESSAGE_ATTACHMENTS and PR_MESSAGE_RECIPIENTS properties are similar in usage. Several MAPI properties provide access to tables:

Property	Table
PR_CONTAINER_CONTENTS	Contents table
PR_CONTAINER_HIERARCHY	Hierarchy table
PR_FOLDER_ASSOCIATED_CONTENTS	Associated contents table
PR_MESSAGE_ATTACHMENTS	Attachment table
PR_MESSAGE_RECIPIENTS	Recipient table


PR_MESSAGE_CC_ME

The PR_MESSAGE_CC_ME property contains TRUE if this messaging user is specifically named as a carbon copy (CC) recipient of this message and is not part of a group.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects
Identifier:	0x0058
Property type:	PT_BOOLEAN
Property tag:	0x0058000B
Remarks

The PR_MESSAGE_CC_ME property provides a convenient way to determine whether the user name explicitly appears in the recipient list, without examining all entries in the list.

This property also assists automated handling of received messages at the time of receipt. At the transport provider’s option, PR_MESSAGE_CC_ME either contains FALSE or is not included if the messaging user is not listed directly in the recipient table.

Message delivery resulting from distribution list expansion or a blind carbon copy designation for the message sender does not cause this property to be set. The user must be explicitly named.

Unsent messages generally do not include PR_MESSAGE_CC_ME. If it is present in messages the user can access in public message stores, in other users’ private stores, in files on disk, or embedded inside other received messages, it generally contains the value to which it was set the last time the transport provider delivered it.


PR_MESSAGE_CLASS

The PR_MESSAGE_CLASS property contains a text string that identifies the sender-defined message class, such as IPM.Note.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Must be a column in:	Folder contents tables
Identifier:	0x001A
Property type:	PT_TSTRING
Property tag:	0x001A001E (0x001A001F for Unicode)
Remarks

The message class specifies the type of the message. It determines the set of properties defined for the message, the kind of information the message conveys, and how to handle the message.

The PR_MESSAGE_CLASS property contains ASCII strings concatenated with periods. Each string represents a level of subclassing. For example, IPM.Note is a subclass of IPM and a superclass of IPM.Note.Private.

PR_MESSAGE_CLASS must consist of the ASCII characters 32 through 127 and must not end with a period (ASCII 46). Sort and compare operations must treat it as a case-insensitive string. The maximum possible length is 255 characters, but in order to allow MAPI room to append qualifiers it is recommended that the original length be kept under 128 characters. Note that these lengths are given in characters; on platforms such as Unicode and DBCS (Double-Byte Character Set) the actual byte count could be higher.

Every message is required to furnish the PR_MESSAGE_CLASS property. Normally the client application creating a new message sets PR_MESSAGE_CLASS as soon as IMAPIFolder::CreateMessage returns successfully. But if the property has not been set when the client calls IMAPIProp::SaveChanges, the message store should set it to IPM.

The PR_MESSAGE_CLASS values defined by MAPI are:

IPM.Note for a standard interpersonal message
REPORT.<subject message class>.DR for a delivery report
REPORT.<subject message class>.NDR for a nondelivery report
REPORT.<subject message class>.IPNRN for a read report
REPORT.<subject message class>.IPNNRN for a nonread report

IPM and IPC are intended to be superclasses only, and a message should have at least one subclass qualifier appended before being stored or submitted. For more information on message class usage, see Message Classes.

A custom message class can define properties in a reserved range for use with that message class only. For more information, see About Property Identifiers.

Message classes control which receive folder an incoming message is stored in. For more information, see the IMsgStore::GetReceiveFolderTable method.

For more information on using message classes with forms and form servers, see Choosing a Message Class.


PR_MESSAGE_DELIVERY_ID

The PR_MESSAGE_DELIVERY_ID property contains a message transfer system (MTS) identifier for a message delivered to a client application.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x001B
Property type:	PT_BINARY
Property tag:	0x001B0102
Corresponding X.400 attribute:	MH_T_MTS_IDENTIFIER
See Also

PR_MESSAGE_SUBMISSION_ID


PR_MESSAGE_DELIVERY_TIME

The PR_MESSAGE_DELIVERY_TIME property contains the date and time a message was delivered.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0E06
Property type:	PT_SYSTIME
Property tag:	0x0E060040
Corresponding X.400 attribute:	MH_T_DELIVERY_TIME
Remarks

The PR_MESSAGE_DELIVERY_TIME property describes the time the message was stored at the server, rather than the download time when the transport provider copied the message from the server to the local store.


PR_MESSAGE_DOWNLOAD_TIME

The PR_MESSAGE_DOWNLOAD_TIME property contains the estimated time to download a message from a remote server to a local message store.

Quick Info

Header file:	MAPITAGS.H
May be a column in:	Header folder contents tables
Identifier:	0x0E18
Property type:	PT_LONG
Property tag:	0x0E180003
Remarks

The PR_MESSAGE_DOWNLOAD_TIME property is expressed in seconds and represents the best estimate of the time it would take a remote transport provider to download a given message from its current location to a message store local to the client viewing the header folder. The remote transport provider typically calculates PR_MESSAGE_DOWNLOAD_TIME by dividing the value of the PR_MESSAGE_SIZE property by the speed of the communications link in bytes per second. If the provider cannot calculate the download time, for example if it does not know the link speed, it should furnish a PT_ERROR value such as MAPI_E_NO_SUPPORT for this column in the header folder contents table.


PR_MESSAGE_FLAGS

The PR_MESSAGE_FLAGS property contains a bitmask of flags indicating the current state of a message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0E07
Property type:	PT_LONG
Property tag:	0x0E070003
Remarks

The PR_MESSAGE_FLAGS property is a nontransmittable message property exposed at both the sending and receiving ends of a transmission, with different values depending upon the client application or store provider involved. This property is initialized by the client or message store provider when a message is created and saved for the first time and then updated periodically by the message store provider, a transport provider, and the MAPI spooler as the message is processed and its state changes.

PR_MESSAGE_FLAGS exists on a message both before and after submission, and on all copies of the received message. Although it is not a recipient property, it is exposed differently to each recipient according to whether it has been read or modified by that recipient.

One or more of the following flags can be set for PR_MESSAGE_FLAGS:

MSGFLAG_ASSOCIATED

The message is an associated message of a folder. The client or provider has read-only access to this flag.

MSGFLAG_FROMME

The messaging user sending was the messaging user receiving the message. The client or provider has read/write access to this flag until the first IMAPIProp::SaveChanges call and read-only thereafter. This flag is meant to be set by the transport provider.

MSGFLAG_HASATTACH

The message has at least one attachment. This flag corresponds to the message’s PR_HASATTACH property. The client has read-only access to this flag.

MSGFLAG_NRN_PENDING

A nonread report needs to be sent for the message. The client or provider has read-only access to this flag.

MSGFLAG_READ

The message is marked as having been read. This can occur as the result of a call at any time to IMessage::SetReadFlag or IMAPIFolder::SetReadFlags. Clients can also set this flag by calling a message’s IMAPIProp::SetProps method before the message has been saved for the first time.

MSGFLAG_RESEND

The message includes a request for a resend operation with a nondelivery report. The client or provider has read/write access to this flag until the first IMAPIProp::SaveChanges call and read-only thereafter.

MSGFLAG_RN_PENDING

A read report needs to be sent for the message. The client or provider has read-only access to this flag.

MSGFLAG_SUBMIT

The message is marked for sending as a result of a call to IMessage::SubmitMessage. Message store providers set this flag; the client has read-only access.

MSGFLAG_UNMODIFIED

The outgoing message has not been modified since the first time that it was saved; the incoming message has not been modified since it was delivered.

MSGFLAG_UNSENT

The message is still being composed. It is saved, but has not been sent. The client or provider has read/write access to this flag until the first IMAPIProp::SaveChanges call and read-only thereafter. If a client doesn’t set this flag by the time the message is sent, the message store provider sets it when IMessage::SubmitMessage is called. Typically, this flag is cleared after the message is sent.

A client or message store provider can check the current state of the message at any time by calling the IMAPIProp::GetProps method to read the flag values. The client or provider can also call the IMAPIProp::SetProps method to change any flags that currently have read/write access.

Several of the flags are always read-only. Some are read/write until the first call to the IMAPIProp::SaveChanges method and thereafter become read-only as far as IMAPIProp::SetProps is concerned. One of these, MSGFLAG_READ, can be changed later through IMessage::SetReadFlag or IMAPIFolder::SetReadFlags.

The initial values for PR_MESSAGE_FLAGS are typically MSGFLAG_UNSENT and MSGFLAG_UNMODIFIED to indicate a message that has not yet been sent or changed. When a message is saved for the second time, the message store provider clears the MSGFLAG_UNMODIFIED bit. Another value that a message store provider can set when a message is saved is the MSGFLAG_HASATTACH flag. MSGFLAG_HASATTACH indicates that the message has one or more attachments. The PR_HASATTACH property is computed from this setting.

When a client calls the IMessage::SubmitMessage method to send the message, the message store provider makes a copy of it for the MAPI spooler and updates PR_MESSAGE_FLAGS by setting the MSGFLAG_SUBMIT bit. The message store provider also sets MSGFLAG_UNSENT if it is not yet set. MSGFLAG_SUBMIT indicates that SubmitMessage has been called, beginning the send process, and that the message is now read-only to clients. MSGFLAG_UNSENT indicates that the MAPI spooler is handling the message. If the send process is canceled, the message store provider resets this value.

As a message is given to a transport provider for delivery, the transport provider sets the MSGFLAG_FROMME flag if the sender had the same account on the messaging server as the message was received on. Transport providers set MSGFLAG_FROMME for an incoming message that has been sent from the currently logged on user. A client can use this value to determine that it is more appropriate to show recipient names in the contents table of the Sent Items folder than sender names. Messages that have been saved during the composition process and not yet sent should also be displayed with recipient names rather than sender names.

For an incoming message, a message store provider clears the MSGFLAG_READ flag to reset its read status. A client can set or clear the MSGFLAG_READ flag when it is necessary to change the read status and control the sending of read and nonread reports by calling either the message’s IMessage::SetReadFlag method or its folder’s IMAPIFolder::SetReadFlags method. The main difference between these methods, other than the object implementing them, is that the folder method can affect one, several, or all of the messages in the folder. The message method affects a single message.

Message store providers also set the MSGFLAG_UNMODIFIED flag for incoming messages. MSGFLAG_UNMODIFIED indicates that a message has not changed since delivery. A client cannot clear this value after it has been set by a message store provider.

See Also

IMsgStore::AbortSubmit


PR_MESSAGE_RECIP_ME

The PR_MESSAGE_RECIP_ME property contains TRUE if this messaging user is specifically named as a primary (To), carbon copy (CC), or blind carbon copy (BCC) recipient of this message and is not part of a group.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects
Identifier:	0x0059
Property type:	PT_BOOLEAN
Property tag:	0x0059000B
Remarks

The PR_MESSAGE_RECIP_ME property provides a convenient way to determine whether the user name explicitly appears in the recipient list, without examining all entries in the list. The value represents the logical OR operation of the properties PR_MESSAGE_CC_ME and PR_MESSAGE_TO_ME, and the BCC information (which does not otherwise appear in a property).

PR_MESSAGE_RECIP_ME assists automated handling of received messages at the time of receipt. At the transport provider’s option, this property either contains FALSE or is not included if the messaging user is not listed directly in the recipient table.

Message delivery resulting from distribution list expansion or a blind carbon copy designation for the message sender does not cause this property to be set. The user must be explicitly named.

Unsent messages generally do not include PR_MESSAGE_RECIP_ME. If it is present in messages the user can access in public message stores, in other users’ private stores, in files on disk, or embedded inside other received messages, it generally contains the value to which it was set the last time the transport provider delivered it.


PR_MESSAGE_RECIPIENTS

The PR_MESSAGE_RECIPIENTS property contains a table of restrictions that can be applied to a contents table to find all messages that contain recipient subobjects meeting the restrictions.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0E12
Property type:	PT_OBJECT
Property tag:	0x0E12000D
Remarks

The PR_MESSAGE_RECIPIENTS property can be excluded in IMAPIProp::CopyTo operations or included in IMAPIProp::CopyProps operations. As a property of type PT_OBJECT, it cannot be successfully retrieved by the IMAPIProp::GetProps method; its contents should be accessed by the IMAPIProp::OpenProperty method, requesting the IID_IMAPITable interface identifier. Service providers must report it to the IMAPIProp::GetPropList method if it is set, but may optionally report it or not if it is not set.

To retrieve table contents, a client application should call the IMessage::GetRecipientTable method. For more information, see Recipient Tables.

PR_MESSAGE_RECIPIENTS can be used for subobject restriction by specifying it in the SSubRestriction structure. This enables a client to limit the view of a container to messages with recipients meeting given criteria. A message qualifies for viewing if at least one row in its recipient table, that is, one recipient satisfies the subobject restriction.

Note  Using subobject restriction results is the equivalent of an IMAPISession::OpenEntry call on every message in the table. Depending on the client application and the number of messages to be searched, it can affect performance.

The PR_MESSAGE_ATTACHMENTS and PR_MESSAGE_RECIPIENTS properties are similar in usage. Several MAPI properties provide access to tables:

Property	Table
PR_CONTAINER_CONTENTS	Contents table
PR_CONTAINER_HIERARCHY	Hierarchy table
PR_FOLDER_ASSOCIATED_CONTENTS	Associated contents table
PR_MESSAGE_ATTACHMENTS	Attachment table
PR_MESSAGE_RECIPIENTS	Recipient table


PR_MESSAGE_SECURITY_LABEL

The PR_MESSAGE_SECURITY_LABEL property contains a security label for a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x001E
Property type:	PT_BINARY
Property tag:	0x001E0102
Corresponding X.400 attribute:	MH_T_SECURITY_LABEL
Remarks

The PR_MESSAGE_SECURITY_LABEL property provides the basis on which the PR_MESSAGE_TOKEN property protects a message. Its association with the message content is guaranteed by the token.

See Also

PR_CONTENT_INTEGRITY_CHECK


PR_MESSAGE_SIZE

The PR_MESSAGE_SIZE property contains the sum, in bytes, of the sizes of all properties on a message object.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0E08
Property type:	PT_LONG
Property tag:	0x0E080003
Remarks

It is recommended that message objects expose the PR_MESSAGE_SIZE property. The message size indicates the approximate number of bytes transferred when the message is moved from one message store to another. Being the sum of the sizes of all properties on the message object, it is usually considerably greater than the message text alone.

Most message store providers compute the PR_MESSAGE_SIZE property for messages that they handle. However, some message store providers do not support this property.

See Also

PR_ATTACH_SIZE


PR_MESSAGE_SUBMISSION_ID

The PR_MESSAGE_SUBMISSION_ID property contains a message transfer system (MTS) identifier for the message transfer agent (MTA).

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0047
Property type:	PT_BINARY
Property tag:	0x00470102
Corresponding X.400 attribute:	MH_T_MTS_IDENTIFIER
Remarks

The PR_MESSAGE_SUBMISSION_ID property is returned by the MTA upon successful completion of message submission. Any future contact with the MTA regarding this message, such as requesting cancellation, uses the MTS identifier in the PR_MESSAGE_SUBMISSION_ID property.

See Also

PR_MESSAGE_DELIVERY_ID


PR_MESSAGE_TO_ME

The PR_MESSAGE_TO_ME property contains TRUE if this messaging user is specifically named as a primary (To) recipient of this message and is not part of a group.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects
Identifier:	0x0057
Property type:	PT_BOOLEAN
Property tag:	0x0057000B
Remarks

The PR_MESSAGE_TO_ME property provides a convenient way to determine whether the user name explicitly appears in the recipient list, without examining all entries in the list.

This property also assists automated handling of received messages at the time of receipt. At the transport provider’s option, PR_MESSAGE_TO_ME either contains FALSE or is not included if the messaging user is not listed directly in the recipient table.

Message delivery resulting from distribution list expansion or a blind carbon copy designation for the message sender does not cause this property to be set. The user must be explicitly named.

Unsent messages generally do not include PR_MESSAGE_TO_ME. If it is present in messages the user can access in public message stores, in other users’ private stores, in files on disk, or embedded inside other received messages, it generally contains the value to which it was set the last time the transport provider delivered it.


PR_MESSAGE_TOKEN

The PR_MESSAGE_TOKEN property contains an ASN.1 security token for a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0C03
Property type:	PT_BINARY
Property tag:	0x0C030102
Corresponding X.400 attribute:	MH_T_TOKEN
Remarks

The PR_MESSAGE_TOKEN property conveys protected security-related information from its originator to its recipient. In conjunction with PR_MESSAGE_SECURITY_LABEL it guarantees the label’s association with the message content. In conjunction with PR_CONTENT_INTEGRITY_CHECK it verifies that the message content is unchanged.


PR_MHS_COMMON_NAME

The PR_MHS_COMMON_NAME property contains the common name of a messaging user for use in a message header.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x3A0F
Property type:	PT_TSTRING
Property tag:	0x3A0F001E (0x3A0F001F for Unicode)
Corresponding X.400 attribute:	MH_T_COMMON_NAME
See Also

PR_DISPLAY_NAME


PR_MINI_ICON

The PR_MINI_ICON property contains a bitmap of a half-size icon for a form.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Form objects
Identifier:	0x0FFC
Property type:	PT_BINARY
Property tag:	0x0FFC0102
Remarks

The PR_MINI_ICON property contains a 32 × 32 pixel image of an icon, the same as the contents of a .ICO file, but only the upper left 16 × 16 pixels are considered significant. This property is normally copied from the .ICO file specified in the SmallIcon line of the appropriate [Description] section of the form configuration file.

Note  Some platforms do not support 16 × 16 pixel icons. The 32 × 32 format of PR_MINI_ICON is usable in such a case but client applications should be aware of display inconsistencies.

See Also

PR_ICON


PR_MOBILE_TELEPHONE_NUMBER

The PR_MOBILE_TELEPHONE_NUMBER property contains the recipient’s cellular telephone number.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A1C
Property type:	PT_TSTRING
Property tag:	0x3A1C001E (0x3A1C001F for Unicode)
Remarks

The PR_MOBILE_TELEPHONE_NUMBER property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.

MAPI also supports the PR_CELLULAR_TELEPHONE_NUMBER property that is synonymous with PR_MOBILE_TELEPHONE_NUMBER.


PR_MODIFY_VERSION

The PR_MODIFY_VERSION property was originally meant to contain the message store version current at the time the message was last modified.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x0E1A
Property type:	PT_I8
Property tag:	0x0E1A0014
Remarks

Do not use this property. It is not supported in MAPI 1.0.

See Also

PR_CREATION_VERSION, PR_CURRENT_VERSION


PR_MSG_STATUS

The PR_MSG_STATUS property contains a 32-bit bitmask of flags defining the status of a message in a contents table.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Message store contents tables
Identifier:	0x0E17
Property type:	PT_LONG
Property tag:	0x0E170003
Remarks

A message can exist in a contents table and in one or more search-results tables, and each instance of the message can have a different status. The PR_MSG_STATUS property should not be considered a property on a message but a column in a contents table.

A client application can set one or more of the following flags in PR_MSG_STATUS:

MSGSTATUS_DELMARKED

The message has been marked for subsequent deletion.

MSGSTATUS_HIDDEN

The message is to be suppressed from recipients’ folder displays.

MSGSTATUS_HIGHLIGHTED

The message is to be highlighted in recipients’ folder displays.

MSGSTATUS_REMOTE_DELETE

The message has been marked for deletion at the remote message store without downloading to the local client.

MSGSTATUS_REMOTE_DOWNLOAD

The message has been marked for downloading from the remote message store to the local client.

MSGSTATUS_TAGGED

The message has been tagged for a client-defined purpose.

The MSGSTATUS_DELMARKED, MSGSTATUS_HIDDEN, MSGSTATUS_HIGHLIGHTED, and MSGSTATUS_TAGGED flags are defined by the client. Transport and store providers pass these bits without any action.

Clients can interpret these values in any way that is appropriate for their applications. One way that many clients use the PR_MSG_STATUS property is to display messages marked for deletion with a representative icon.

A remote viewer client can set MSGSTATUS_REMOTE_DELETE or MSGSTATUS_REMOTE_DOWNLOAD on messages in the header folder presented to it by the remote transport provider. The client application can examine each message header in this folder to determine whether the message should be downloaded or deleted at the remote message store. It then uses the IMAPIFolder::SetMessageStatus method to set the appropriate flag. SetMessageStatus is the only way to set any of the PR_MSG_STATUS flags; the IMAPIProp::SetProps method cannot be used. To retrieve the PR_MSG_STATUS property, clients call IMAPIFolder::GetMessageStatus rather than IMAPIProp::GetProps. For more information on remote viewing and remote transport providers, see Remote Transport Architecture.

Bits 16 through 31 (0x10000 through 0x80000000) of PR_MSG_STATUS are available for use by the interpersonal message (IPM) client application. All other bits are reserved for use by MAPI; those not defined in the preceding table should be initially set to zero and not altered subsequently.

See Also

IMAPIFolder::GetMessageStatus, IMAPITable::QueryRows


PR_NDR_DIAG_CODE

The PR_NDR_DIAG_CODE property contains a diagnostic code that forms part of a nondelivery report.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Recipient subobjects within nondelivery report message objects
Identifier:	0x0C05
Property type:	PT_LONG
Property tag:	0x0C050003
Corresponding X.400 attribute:	MH_T_NON_DELIVERY_DIAGNOSTIC
Remarks

The PR_NDR_DIAG_CODE property can have exactly one of the following values:

MAPI_DIAG_ALPHABETIC_CHARACTER_LOST

MAPI_DIAG_CONTENT_SYNTAX_IN_ERROR

MAPI_DIAG_CONTENT_TOO_LONG

MAPI_DIAG_CONTENT_TYPE_UNSUPPORTED

MAPI_DIAG_CONVERSION_LOSS_PROHIB

MAPI_DIAG_CONVERSION_UNSUBSCRIBED

MAPI_DIAG_CRITICAL_FUNC_UNSUPPORTED

MAPI_DIAG_EITS_UNSUPPORTED

MAPI_DIAG_EXPANSION_FAILED

MAPI_DIAG_EXPANSION_PROHIBITED

MAPI_DIAG_IMPRACTICAL_TO_CONVERT

MAPI_DIAG_LENGTH_CONSTRAINT_VIOLATD

MAPI_DIAG_LINE_TOO_LONG

MAPI_DIAG_LOOP_DETECTED

MAPI_DIAG_MAIL_ADDRESS_INCOMPLETE

MAPI_DIAG_MAIL_ADDRESS_INCORRECT

MAPI_DIAG_MAIL_FORWARDING_PROHIB

MAPI_DIAG_MAIL_FORWARDING_UNWANTED

MAPI_DIAG_MAIL_NEW_ADDRESS_UNKNOWN

MAPI_DIAG_MAIL_OFFICE_INCOR_OR_INVD

MAPI_DIAG_MAIL_ORGANIZATION_EXPIRED

MAPI_DIAG_MAIL_RECIPIENT_DECEASED

MAPI_DIAG_MAIL_RECIPIENT_DEPARTED

MAPI_DIAG_MAIL_RECIPIENT_MOVED

MAPI_DIAG_MAIL_RECIPIENT_TRAVELLING

MAPI_DIAG_MAIL_RECIPIENT_UNKNOWN

MAPI_DIAG_MAIL_REFUSED

MAPI_DIAG_MAIL_UNCLAIMED

MAPI_DIAG_MAXIMUM_TIME_EXPIRED

MAPI_DIAG_MTS_CONGESTED

MAPI_DIAG_MULTIPLE_INFO_LOSSES

MAPI_DIAG_NO_BILATERAL_AGREEMENT

MAPI_DIAG_NO_DIAGNOSTIC

MAPI_DIAG_NUMBER_CONSTRAINT_VIOLATD

MAPI_DIAG_OR_NAME_AMBIGUOUS

MAPI_DIAG_OR_NAME_UNRECOGNIZED

MAPI_DIAG_PAGE_TOO_LONG

MAPI_DIAG_PARAMETERS_INVALID

MAPI_DIAG_PICTORIAL_SYMBOL_LOST

MAPI_DIAG_PROHIBITED_TO_CONVERT

MAPI_DIAG_PUNCTUATION_SYMBOL_LOST

MAPI_DIAG_REASSIGNMENT_PROHIBITED

MAPI_DIAG_RECIPIENT_UNAVAILABLE

MAPI_DIAG_REDIRECTION_LOOP_DETECTED

MAPI_DIAG_RENDITION_UNSUPPORTED

MAPI_DIAG_SECURE_MESSAGING_ERROR

MAPI_DIAG_SUBMISSION_PROHIBITED

MAPI_DIAG_TOO_MANY_RECIPIENTS

See Also

PR_NDR_REASON_CODE


PR_NDR_REASON_CODE

The PR_NDR_REASON_CODE property contains an encoded reason for nondelivery that forms part of a nondelivery report.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Recipient subobjects within nondelivery report message objects
Identifier:	0x0C04
Property type:	PT_LONG
Property tag:	0x0C040003
Corresponding X.400 attribute:	MH_T_NON_DELIVERY_REASON
See Also

PR_NDR_DIAG_CODE


PR_NON_RECEIPT_NOTIFICATION_REQUESTED

The PR_NON_RECEIPT_NOTIFICATION_REQUESTED property contains TRUE if a message sender wants notification of non-receipt for a specified recipient.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects, recipient subobjects
Identifier:	0x0C06
Property type:	PT_BOOLEAN
Property tag:	0x0C06000B
Corresponding X.400 attribute:	IM_NOTIFICATION_REQUEST
Remarks

If the PR_NON_RECEIPT_NOTIFICATION_REQUESTED property contains FALSE and the PR_READ_RECEIPT_REQUESTED property contains TRUE, the service provider can override PR_NON_RECEIPT_NOTIFICATION_REQUESTED and generate a nondelivery report.


PR_NON_RECEIPT_REASON

The PR_NON_RECEIPT_REASON property contains reasons why a message was not received that forms part of a nondelivery report.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Nondelivery report message objects
Identifier:	0x003E
Property type:	PT_LONG
Property tag:	0x003E0003
Corresponding X.400 attribute:	IM_NON_RECEIPT_REASON
Remarks

Reasons can include, for example, that the message was discarded.

See Also

PR_NDR_DIAG_CODE


PR_NORMALIZED_SUBJECT

The PR_NORMALIZED_SUBJECT property contains the message subject with any prefix removed.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0E1D
Property type:	PT_TSTRING
Property tag:	0x0E1D001E (0x0E1D001F for Unicode)
Corresponding X.400 attribute:	IM_SUBJECT
Remarks

The PR_NORMALIZED_SUBJECT property is computed by message store or transport providers from the PR_SUBJECT and PR_SUBJECT_PREFIX properties in the following manner.

•	If PR_SUBJECT_PREFIX is present and is an initial substring of PR_SUBJECT, PR_NORMALIZED_SUBJECT is set to the contents of PR_SUBJECT with the prefix removed.

•	If PR_SUBJECT_PREFIX is present, but it is not an initial substring of PR_SUBJECT, PR_SUBJECT_PREFIX is deleted and recalculated from PR_SUBJECT using the following rule:

If the string contained in PR_SUBJECT begins with one to three non-numeric characters followed by a colon and a space, then the string together with the colon and the blank becomes the prefix. Numbers, blanks, and punctuation characters are not valid prefix characters.

•	If PR_SUBJECT_PREFIX is not present, it is calculated from PR_SUBJECT using the rule outlined in the previous step. PR_NORMALIZED_SUBJECT then is set to the contents of PR_SUBJECT with the prefix removed.

Note  When PR_SUBJECT_PREFIX is an empty string, PR_SUBJECT and PR_NORMALIZED_SUBJECT are the same.

Ultimately, PR_NORMALIZED_SUBJECT should be the part of PR_SUBJECT following the prefix. If there is no prefix, PR_NORMALIZED_SUBJECT becomes the same as PR_SUBJECT.

PR_SUBJECT_PREFIX and PR_NORMALIZED_SUBJECT should be computed as part of the IMAPIProp::SaveChanges implementation. A client application should not prompt the IMAPIProp::GetProps method for their values until they have been committed by an IMAPIProp::SaveChanges call.

The subject properties are typically small strings of fewer than 256 characters, and a message store provider is not obligated to support the OLE IStream interface on them. The client should always attempt access through the IMAPIProp interface first, and resort to IStream only if MAPI_E_NOT_ENOUGH_MEMORY is returned.


PR_NULL

The PR_NULL property represents a null value or setting of a property or reserves array space.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x0000
Property type:	PT_NULL
Property tag:	0x00000001
Remarks

The PR_NULL property is used to reserve space in arrays of SPropValue structures. It is used in an array of SPropTag structures to tell the method to reserve space in the returned array of SPropValue structures. This allows for computed properties to be filled in an inexpensive way.

For more information, see About Property Types.


PR_OBJECT_TYPE

The PR_OBJECT_TYPE property contains the type of an object.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Address book container, distribution list, folder, messaging user, message, and message store objects
Identifier:	0x0FFE
Property type:	PT_LONG
Property tag:	0x0FFE0003
Remarks

The object type contained in the PR_OBJECT_TYPE property corresponds to the primary interface available for an object accessible through the OpenEntry interface. It is usually obtained by consulting the lpulObjType parameter returned by the appropriate OpenEntry method. When the interface is obtained in other ways, call IMAPIProp::GetProps to obtain the value for PR_OBJECT_TYPE.

PR_OBJECT_TYPE can have exactly one of the following values:

MAPI_ABCONT

Address book container object

MAPI_ADDRBOOK

Address book object

MAPI_ATTACH

Message attachment object

MAPI_DISTLIST

Distribution list object

MAPI_FOLDER

Folder object

MAPI_FORMINFO

Form object

MAPI_MAILUSER

Messaging user object

MAPI_MESSAGE

Message object

MAPI_PROFSECT

Profile section object

MAPI_STATUS

Status object

MAPI_STORE

Message store object

For more information on object types, see Objects and Interfaces.


PR_OBSOLETED_IPMS

The PR_OBSOLETED_IPMS property contains the identifiers of messages that this message supersedes.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x001F
Property type:	PT_BINARY
Property tag:	0x001F0102
Corresponding X.400 attribute:	IM_OBSOLETED_IPMS
Remarks

The identifiers contained in the PR_OBSOLETED_IPMS property are standard search keys using the format of the PR_SEARCH_KEY property.

See Also

PR_SEARCH_KEY


PR_OFFICE_LOCATION

The PR_OFFICE_LOCATION property contains the recipient’s office location.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A19
Property type:	PT_TSTRING
Property tag:	0x3A19001E (0x3A19001F for Unicode)
Remarks

The PR_OFFICE_LOCATION property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_ORGANIZATIONAL_ID_NUMBER

The PR_ORGANIZATIONAL_ID_NUMBER property contains an identifier for the recipient used within the recipient’s organization.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A10
Property type:	PT_TSTRING
Property tag:	0x3A10001E (0x3A10001F for Unicode)
Remarks

The PR_ORGANIZATIONAL_ID_NUMBER property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.

PR_ORGANIZATIONAL_ID_NUMBER is commonly set to an employee number.


PR_ORIG_MESSAGE_CLASS

The PR_ORIG_MESSAGE_CLASS property contains the class of the original message for use in a report.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x004B
Property type:	PT_TSTRING
Property tag:	0x004B001E (0x004B001F for Unicode)
Remarks

The PR_ORIG_MESSAGE_CLASS property contains a copy of the PR_MESSAGE_CLASS property of the message for which the report is being generated.


PR_ORIGIN_CHECK

The PR_ORIGIN_CHECK property contains a binary verification value enabling a delivery report recipient to verify the origin of the original message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0027
Property type:	PT_BINARY
Property tag:	0x00270102
Corresponding X.400 attribute:	MH_T_ORIGIN_CHECK
Remarks

The PR_ORIGIN_CHECK property provides a means for a third party, such as a message transfer agent (MTA) or a messaging user receiving a delivery report, to verify the submitted message’s origin. If present on a received message, this property should be copied onto any delivery report generated in response to the message.

PR_ORIGIN_CHECK replaces several obsolete properties supplied in pre-release versions of MAPI, including PR_MESSAGE_ORIGIN_AUTHENTICATION_CHECK, PR_PROBE_SUBMISSION_AUTHENTICATION_CHECK, and PR_REPORT_ORIGIN_AUTHENTICATION_CHECK.

See Also

PR_ORIGINATOR_CERTIFICATE


PR_ORIGINAL_AUTHOR_ADDRTYPE

The PR_ORIGINAL_AUTHOR_ADDRTYPE property contains the address type of the author of the first version of a message, that is, the message before being forwarded or replied to.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0079
Property type:	PT_TSTRING
Property tag:	0x0079001E (0x0079001F for Unicode)
Remarks

The PR_ORIGINAL_AUTHOR_ADDRTYPE property is one of the address properties for the author of a message. At first submission of the message, the client application should set this property to the value of the PR_SENDER_ADDRTYPE property. It is never changed when the message is forwarded or replied to.

The original author properties allow for preservation of information from outside the local messaging domain. When a message arrives from another messaging domain, such as from the Internet, these properties provide a way to ensure that original information is not lost.

For more information on the address properties, see Base Address Properties.

See Also

PR_ADDRTYPE


PR_ORIGINAL_AUTHOR_EMAIL_ADDRESS

The PR_ORIGINAL_AUTHOR_EMAIL_ADDRESS property contains the e-mail address of the author of the first version of a message, that is, the message before being forwarded or replied to.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x007A
Property type:	PT_TSTRING
Property tag:	0x007A001E (0x007A001F for Unicode)
Remarks

The PR_ORIGINAL_AUTHOR_EMAIL_ADDRESS property is one of the address properties for the author of a message. At first submission of the message, the client application should set this property to the value of PR_SENDER_EMAIL_ADDRESS. It is never changed when the message is forwarded or replied to.

The original author properties allow for preservation of information from outside the local messaging domain. When a message arrives from another messaging domain, such as from the Internet, these properties provide a way to ensure that original information is not lost.

For more information on the address properties, see Base Address Properties.

See Also

PR_EMAIL_ADDRESS


PR_ORIGINAL_AUTHOR_ENTRYID

The PR_ORIGINAL_AUTHOR_ENTRYID property contains the entry identifier of the author of the first version of a message, that is, the message before being forwarded or replied to.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x004C
Property type:	PT_BINARY
Property tag:	0x004C0102
Remarks

The PR_ORIGINAL_AUTHOR_ENTRYID property is one of the address properties for the author of a message. At first submission of the message, the client application should set this property to the value of PR_SENDER_ENTRYID. It is never changed when the message is forwarded or replied to.

The original author properties allow for preservation of information from outside the local messaging domain. When a message arrives from another messaging domain, such as from the Internet, these properties provide a way to ensure that original information is not lost.

For more information on the address properties, see Base Address Properties.

See Also

PR_ENTRYID


PR_ORIGINAL_AUTHOR_NAME

The PR_ORIGINAL_AUTHOR_NAME property contains the display name of the author of the first version of a message, that is, the message before being forwarded or replied to.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x004D
Property type:	PT_TSTRING
Property tag:	0x004D001E (0x004D001F for Unicode)
Corresponding X.400 attribute:	MH_T_ORIGINATOR_NAME
Remarks

The PR_ORIGINAL_AUTHOR_NAME property is one of the address properties for the author of a message. At first submission of the message, the client application should set this property to the value of PR_SENDER_NAME. It is never changed when the message is forwarded or replied to.

The original author properties allow for preservation of information from outside the local messaging domain. When a message arrives from another messaging domain, such as from the Internet, these properties provide a way to ensure that original information is not lost.

For more information on the address properties, see Base Address Properties.

See Also

PR_DISPLAY_NAME


PR_ORIGINAL_AUTHOR_SEARCH_KEY

The PR_ORIGINAL_AUTHOR_SEARCH_KEY property contains the search key of the author of the first version of a message, that is, the message before being forwarded or replied to.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0056
Property type:	PT_BINARY
Property tag:	0x00560102
Remarks

The PR_ORIGINAL_AUTHOR_SEARCH_KEY property is one of the address properties for the author of a message. At first submission of the message, the client application should set this property to the value of PR_SENDER_SEARCH_KEY. It is never changed when the message is forwarded or replied to.

The original author properties allow for preservation of information from outside the local messaging domain. When a message arrives from another messaging domain, such as from the Internet, these properties provide a way to ensure that original information is not lost.

For more information on the address properties, see Base Address Properties.

See Also

PR_SEARCH_KEY


PR_ORIGINAL_DELIVERY_TIME

The PR_ORIGINAL_DELIVERY_TIME property contains a copy of the original message’s delivery date and time in a thread.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Read and nonread report objects
Identifier:	0x0055
Property type:	PT_SYSTIME
Property tag:	0x00550040
Remarks

The PR_ORIGINAL_DELIVERY_TIME property is copied from the original PR_MESSAGE_DELIVERY_TIME property in subsequent reply or forward operations and used in read and nonread reports. Delivery reports use the PR_DELIVER_TIME property instead.


PR_ORIGINAL_DISPLAY_BCC

The PR_ORIGINAL_DISPLAY_BCC property contains the display names of any blind carbon copy (BCC) recipients of the original message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0072
Property type:	PT_TSTRING
Property tag:	0x0072001E (0x0072001F for Unicode)
Remarks

The PR_ORIGINAL_DISPLAY_BCC property contains an ASCII list separated by semicolons. It is furnished by MAPI and is copied directly from PR_DISPLAY_BCC when a delivery or nondelivery report or a read or nonread report is generated. PR_ORIGINAL_DISPLAY_BCC may be present on other messages as defined by their message classes.


PR_ORIGINAL_DISPLAY_CC

The PR_ORIGINAL_DISPLAY_CC property contains the display names of any carbon copy (CC) recipients of the original message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Report message objects
Identifier:	0x0073
Property type:	PT_TSTRING
Property tag:	0x0073001E (0x0073001F for Unicode)
Remarks

The PR_ORIGINAL_DISPLAY_CC property contains an ASCII list separated by semicolons. It is furnished by MAPI and is copied directly from PR_DISPLAY_CC when a delivery or nondelivery report or a read or nonread report is generated. PR_ORIGINAL_DISPLAY_CC may be present on other messages as defined by their message classes.


PR_ORIGINAL_DISPLAY_NAME

The PR_ORIGINAL_DISPLAY_NAME property contains the original display name for an entry copied from an address book to a personal address book or other writable address book.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A13
Property type:	PT_TSTRING
Property tag:	0x3A13001E (0x3A13001F for Unicode)
Remarks

The PR_ORIGINAL_DISPLAY_NAME property is one of the properties that contain information about the original source of a copied entry.

For a nonread report, PR_ORIGINAL_DISPLAY_NAME contains a copy of the display name of the original message recipient for which the report is generated. When the original recipient is part of a distribution list, the display name of the distribution list is preserved for the report.

A client application can use PR_ORIGINAL_DISPLAY_NAME to prevent alteration or “spoofing” of entries. An example of spoofing is displaying John Doe as John (What a Guy) Doe.

See Also

PR_TRANSMITTABLE_DISPLAY_NAME


PR_ORIGINAL_DISPLAY_TO

The PR_ORIGINAL_DISPLAY_TO property contains the display names of the primary (To) recipients of the original message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Report message objects
Identifier:	0x0074
Property type:	PT_TSTRING
Property tag:	0x0074001E (0x0074001F for Unicode)
Remarks

The PR_ORIGINAL_DISPLAY_TO property contains an ASCII list separated by semicolons. It is furnished by MAPI and is copied directly from PR_DISPLAY_TO when a delivery or nondelivery report or a read or nonread report is generated. PR_ORIGINAL_DISPLAY_TO may be present on other messages as defined by their message classes.


PR_ORIGINAL_EITS

The PR_ORIGINAL_EITS property contains a copy of the original encoded information types (EITs) for message text.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0021
Property type:	PT_BINARY
Property tag:	0x00210102
Corresponding X.400 attribute:	MH_T_ORIGINAL_EITS


PR_ORIGINAL_ENTRYID

The PR_ORIGINAL_ENTRYID property contains the original entry identifier for an entry copied from an address book to a personal address book or other writeable address book.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A12
Property type:	PT_BINARY
Property tag:	0x3A120102
Remarks

The PR_ORIGINAL_ENTRYID property is one of the properties that contain information about the original source of a copied entry.

For a nonread report, PR_ORIGINAL_ENTRYID contains a copy of the entry identifier of the original message recipient for which the report is generated. When the original recipient is part of a distribution list, the entry identifier of the distribution list is preserved for the report.


PR_ORIGINAL_SEARCH_KEY

The PR_ORIGINAL_SEARCH_KEY property contains the original search key for an entry copied from an address book to a personal address book or other writeable address book.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A14
Property type:	PT_BINARY
Property tag:	0x3A140102
Remarks

The PR_ORIGINAL_SEARCH_KEY property is one of the properties that contain information about the original source of a copied entry.

For a nonread report, PR_ORIGINAL_SEARCH_KEY contains a copy of the search key of the original message recipient for which the report is generated. When the original recipient is part of a distribution list, the search key of the distribution list is preserved for the report.


PR_ORIGINAL_SENDER_ADDRTYPE

The PR_ORIGINAL_SENDER_ADDRTYPE property contains the address type of the sender of the first version of a message, that is, the message before being forwarded or replied to.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0066
Property type:	PT_TSTRING
Property tag:	0x0066001E (0x0066001F for Unicode)
Remarks

The PR_ORIGINAL_SENDER_ADDRTYPE property is one of the address properties for the original sender of a message. At first submission of the message, the client application should set this property to the value of PR_SENDER_ADDRTYPE. It is never changed when the message is forwarded or replied to.

For more information on the address properties, see Base Address Properties.


PR_ORIGINAL_SENDER_EMAIL_ADDRESS

The PR_ORIGINAL_SENDER_EMAIL_ADDRESS property contains the e-mail address of the sender of the first version of a message, that is, the message before being forwarded or replied to.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0067
Property type:	PT_TSTRING
Property tag:	0x0067001E (0x0067001F for Unicode)
Remarks

The PR_ORIGINAL_SENDER_EMAIL_ADDRESS property is one of the address properties for the original sender of a message. At first submission of the message, the client application should set this property to the value of PR_SENDER_EMAIL_ADDRESS. It is never changed when the message is forwarded or replied to.

For more information on the address properties, see Base Address Properties.


PR_ORIGINAL_SENDER_ENTRYID

The PR_ORIGINAL_SENDER_ENTRYID property contains the entry identifier of the sender of the first version of a message, that is, the message before being forwarded or replied to.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x005B
Property type:	PT_BINARY
Property tag:	0x005B0102
Remarks

The PR_ORIGINAL_SENDER_ENTRYID property is one of the address properties for the original sender of a message. At first submission of the message, a client application should set this property to the value of the PR_SENDER_ENTRYID property. It is never changed when the message is forwarded or replied to.

For more information on the address properties, see Base Address Properties.


PR_ORIGINAL_SENDER_NAME

The PR_ORIGINAL_SENDER_NAME property contains the display name of the sender of the first version of a message, that is, the message before being forwarded or replied to.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x005A
Property type:	PT_TSTRING
Property tag:	0x005A001E (0x005A001F for Unicode)
Corresponding X.400 attribute:	MH_T_ORIGINATOR_NAME
Remarks

The PR_ORIGINAL_SENDER_NAME property is one of the address properties for the original sender of a message. At first submission of the message, a client application should set this property to the value of the PR_SENDER_NAME property. It is never changed when the message is forwarded or replied to.

For more information on the address properties, see Base Address Properties.


PR_ORIGINAL_SENDER_SEARCH_KEY

The PR_ORIGINAL_SENDER_SEARCH_KEY property contains the search key for the sender of the first version of a message, that is, the message before being forwarded or replied to.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x005C
Property type:	PT_BINARY
Property tag:	0x005C0102
Remarks

The PR_ORIGINAL_SENDER_SEARCH_KEY property is one of the address properties for the original sender of a message. At first submission of the message, the client application should set this property to the value of the PR_SENDER_SEARCH_KEY property. It is never changed when the message is forwarded or replied to.

For more information on the address properties, see Base Address Properties.


PR_ORIGINAL_SENSITIVITY

The PR_ORIGINAL_SENSITIVITY property contains the sensitivity value assigned by the sender of the first version of a message that is, the message before being forwarded or replied to.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x002E
Property type:	PT_LONG
Property tag:	0x002E0003
Remarks

A client application should set the PR_ORIGINAL_SENSITIVITY property to the same value as the PR_SENSITIVITY property when the message is first submitted. It should never be changed subsequently.

PR_ORIGINAL_SENSITIVITY is used by the transport provider to protect the sensitivity on copied entries. It enables it, for example, to block modification of the original message text in a forward of or reply to a message that was originally marked SENSITIVITY_PRIVATE.


PR_ORIGINAL_SENT_REPRESENTING_ADDRTYPE

The PR_ORIGINAL_SENT_REPRESENTING_ADDRTYPE property contains the address type of the messaging user on whose behalf the original message was sent.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0068
Property type:	PT_TSTRING
Property tag:	0x0068001E (0x0068001F for Unicode)
Remarks

The PR_ORIGINAL_SENT_REPRESENTING_ADDRTYPE property is one of the address properties for the original represented sender of a message. It is used in a conversation thread.

A client application sending a message on behalf of another client should set this property to the value of the PR_SENT_REPRESENTING_ADDRTYPE property at the first submission of the message. Once set, it should never be changed.

For more information on the address properties, see Base Address Properties.


PR_ORIGINAL_SENT_REPRESENTING_EMAIL_ADDRESS

The PR_ORIGINAL_SENT_REPRESENTING_EMAIL_ADDRESS property contains the e-mail address of the messaging user on whose behalf the original message was sent.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0069
Property type:	PT_TSTRING
Property tag:	0x0069001E (0x0069001F for Unicode)
Remarks

The PR_ORIGINAL_SENT_REPRESENTING_EMAIL_ADDRESS property is one of the address properties for the original represented sender of a message. It is used in a conversation thread.

A client application sending a message on behalf of another client should set this property to the value of the PR_SENT_REPRESENTING_EMAIL_ADDRESS property at the first submission of the message. Once set, it should never be changed.

For more information on the address properties, see Base Address Properties.


PR_ORIGINAL_SENT_REPRESENTING_ENTRYID

The PR_ORIGINAL_SENT_REPRESENTING_ENTRYID property contains the entry identifier of the messaging user on whose behalf the original message was sent.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x005E
Property type:	PT_BINARY
Property tag:	0x005E0102
Remarks

The PR_ORIGINAL_SENT_REPRESENTING_ENTRYID property is one of the address properties for the original represented sender of a message. It is used in a conversation thread.

A client application sending a message on behalf of another client should set this property to the value of the PR_SENT_REPRESENTING_ENTRYID property at the first submission of the message. Once set, it should never be changed.

For more information on the address properties, see Base Address Properties.


PR_ORIGINAL_SENT_REPRESENTING_NAME

The PR_ORIGINAL_SENT_REPRESENTING_NAME property contains the display name of the messaging user on whose behalf the original message was sent.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x005D
Property type:	PT_TSTRING
Property tag:	0x005D001E (0x005D001F for Unicode)
Remarks

The PR_ORIGINAL_SENT_REPRESENTING_NAME property is one of the address properties for the original represented sender of a message. It is used in a conversation thread.

A client application sending a message on behalf of another client should set this property to the value of the PR_SENT_REPRESENTING_NAME property at the first submission of the message. Once set, it should never be changed.

For more information on the address properties, see Base Address Properties.


PR_ORIGINAL_SENT_REPRESENTING_SEARCH_KEY

The PR_ORIGINAL_SENT_REPRESENTING_SEARCH_KEY property contains the search key of the messaging user on whose behalf the original message was sent.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x005F
Property type:	PT_BINARY
Property tag:	0x005F0102
Remarks

The PR_ORIGINAL_SENT_REPRESENTING_SEARCH_KEY property is one of the address properties for the original represented sender of a message. It is used in a conversation thread.

A client application sending a message on behalf of another client should set this property to the value of the PR_SENT_REPRESENTING_SEARCH_KEY property at the first submission of the message. Once set, it should never be changed.

For more information on the address properties, see Base Address Properties.


PR_ORIGINAL_SUBJECT

The PR_ORIGINAL_SUBJECT property contains the subject of an original message for use in a report about the message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0049
Property type:	PT_TSTRING
Property tag:	0x0049001E (0x0049001F for Unicode)
Corresponding X.400 attribute:	IM_SUBJECT
Remarks

The PR_ORIGINAL_SUBJECT property is originally set to the same value as the PR_SUBJECT property.

The subject properties are typically small strings of fewer than 256 characters, and a message store provider is not obligated to support the OLE IStream interface on them. The client should always attempt access through the IMAPIProp interface first, and resort to IStream only if MAPI_E_NOT_ENOUGH_MEMORY is returned.


PR_ORIGINAL_SUBMIT_TIME

The PR_ORIGINAL_SUBMIT_TIME property contains the original submission date and time of the message in the report.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Report message objects
Identifier:	0x004E
Property type:	PT_SYSTIME
Property tag:	0x004E0040
Remarks

At first submission of a message, a client application should set the PR_ORIGINAL_SUBMIT_TIME property to the value of the PR_CLIENT_SUBMIT_TIME property. It is not changed when the message is forwarded. This is used in reports only.


PR_ORIGINALLY_INTENDED_RECIP_ADDRTYPE

The PR_ORIGINALLY_INTENDED_RECIP_ADDRTYPE property contains the address type of the originally intended recipient of an autoforwarded message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x007B
Property type:	PT_TSTRING
Property tag:	0x007B001E (0x007B001F for Unicode)
Corresponding X.400 attribute:	IM_IPM_INTENDED_RECIPIENT
Remarks

The PR_ORIGINALLY_INTENDED_RECIP_ADDRTYPE property is one of the address properties for the originally intended message recipient. It must be set by the automatic agent that has forwarded the message.

For more information on the address properties, see Base Address Properties.

See Also

PR_ADDRTYPE


PR_ORIGINALLY_INTENDED_RECIP_EMAIL_ADDRESS

The PR_ORIGINALLY_INTENDED_RECIP_EMAIL_ADDRESS property contains the e-mail address of the originally intended recipient of an autoforwarded message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x007C
Property type:	PT_TSTRING
Property tag:	0x007C001E (0x007C001F for Unicode)
Remarks

The PR_ORIGINALLY_INTENDED_RECIP_EMAIL_ADDRESS property is one of the address properties for the originally intended message recipient. It must be set by the automatic agent that has forwarded the message.

For more information on the address properties, see Base Address Properties.

PR_ORIGINALLY_INTENDED_RECIP_EMAIL_ADDRESS corresponds to the X.400 report per-recipient attribute.

See Also

PR_EMAIL_ADDRESS


PR_ORIGINALLY_INTENDED_RECIP_ENTRYID

The PR_ORIGINALLY_INTENDED_RECIP_ENTRYID property contains the entry identifier of the originally intended recipient of an autoforwarded message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x1012
Property type:	PT_BINARY
Property tag:	0x10120102
Remarks

The PR_ORIGINALLY_INTENDED_RECIP_ENTRYID property is one of the address properties for the originally intended message recipient. It must be set by the automatic agent that has forwarded the message.

For more information on the address properties, see Base Address Properties.

PR_ORIGINALLY_INTENDED_RECIP_ENTRYID corresponds to the X.400 report per-recipient attribute.

See Also

PR_ENTRYID


PR_ORIGINALLY_INTENDED_RECIPIENT_NAME

The PR_ORIGINALLY_INTENDED_RECIPIENT_NAME property contains the encoded name of the originally intended recipient of an autoforwarded message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0020
Property type:	PT_BINARY
Property tag:	0x00200102
Corresponding X.400 attribute:	MH_T_ORIGINALLY_INTENDED_RECIP
Remarks

The PR_ORIGINALLY_INTENDED_RECIPIENT_NAME property must be set by the automatic agent that has forwarded the message.

This property is not one of the address properties.


PR_ORIGINATING_MTA_CERTIFICATE

The PR_ORIGINATING_MTA_CERTIFICATE property contains an identifier for the message transfer agent (MTA) that originated the message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0E25
Property type:	PT_BINARY
Property tag:	0x0E250102
Remarks

The PR_ORIGINATING_MTA_CERTIFICATE property, if set, is available on sent messages in the Sent Items folder.

PR_ORIGINATING_MTA_CERTIFICATE corresponds to the X.400 report per-message attribute.

See Also

PR_REPORTING_MTA_CERTIFICATE


PR_ORIGINATOR_AND_DL_EXPANSION_HISTORY

The PR_ORIGINATOR_AND_DL_EXPANSION_HISTORY property contains information about a message originator and a distribution list expansion history.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x1002
Property type:	PT_BINARY
Property tag:	0x10020102
Corresponding X.400 attribute:	MH_T_ORIG_AND_EXPANSION_HISTORY
Remarks

The PR_ORIGINATOR_AND_DL_EXPANSION_HISTORY property is used in report generation.


PR_ORIGINATOR_CERTIFICATE

The PR_ORIGINATOR_CERTIFICATE property contains an ASN.1 certificate for the message originator.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0022
Property type:	PT_BINARY
Property tag:	0x00220102
Corresponding X.400 attribute:	MH_T_ORIGINATOR_CERTIFICATE
Remarks

The PR_ORIGINATOR_CERTIFICATE property is a copy of the originator’s PR_USER_CERTIFICATE property.


PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED

The PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED property contains TRUE if a message sender requests a delivery report for a particular recipient from the messaging system before the message is placed in the message store.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects, message objects
Identifier:	0x0023
Property type:	PT_BOOLEAN
Property tag:	0x0023000B
Corresponding X.400 attribute:	MH_T_ORIGINATOR_REPORT_REQUEST
Remarks

The PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED property is used to direct the messaging system in handling delivered messages. In this case, the message must also furnish the PR_ORIGINATOR_NON_DELIVERY_REPORT_REQUESTED property set to FALSE.

Setting PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED on a message is a way to request delivery status reports for all recipients.


PR_ORIGINATOR_NON_DELIVERY_REPORT_REQUESTED

The PR_ORIGINATOR_NON_DELIVERY_REPORT_REQUESTED property contains TRUE if a message sender requests a nondelivery report for a particular recipient.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects
Identifier:	0x0C08
Property type:	PT_BOOLEAN
Property tag:	0x0C08000B
Corresponding X.400 attribute:	MH_T_ORIGINATOR_REPORT_REQUEST
Remarks

The PR_ORIGINATOR_NON_DELIVERY_REPORT_REQUESTED property is used to direct the messaging system in handling undelivered messages. In this case, the message must also furnish the PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED property set to FALSE.


PR_ORIGINATOR_REQUESTED_ALTERNATE_RECIPIENT

The PR_ORIGINATOR_REQUESTED_ALTERNATE_RECIPIENT property contains an entry identifier for an alternate recipient designated by the sender.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects
Identifier:	0x0C09
Property type:	PT_BINARY
Property tag:	0x0C090102
Remarks

The PR_ORIGINATOR_REQUESTED_ALTERNATE_RECIPIENT property is used in autoforwarded messages. If autoforwarding is not permitted or if no alternate recipient has been designated, a nondelivery report should be generated.


PR_ORIGINATOR_RETURN_ADDRESS

The PR_ORIGINATOR_RETURN_ADDRESS property contains the binary-encoded return address of the message originator.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0024
Property type:	PT_BINARY
Property tag:	0x00240102
Corresponding X.400 attribute:	MH_T_ORIGINATOR_RETURN_ADDRESS


PR_OTHER_TELEPHONE_NUMBER

The PR_OTHER_TELEPHONE_NUMBER property contains an alternate telephone number for the recipient.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A1F
Property type:	PT_TSTRING
Property tag:	0x3A1F001E (0x3A1F001F for Unicode)
Remarks

The PR_OTHER_TELEPHONE_NUMBER property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on these properties, see IMailUser::IMAPIProp.

PR_OTHER_TELEPHONE_NUMBER is used for a telephone number other than at the recipient’s place of business, home, or office.


PR_OWN_STORE_ENTRYID

The PR_OWN_STORE_ENTRYID property contains the entry identifier of a transport’s tightly coupled message store.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Status objects
May be a column in:	Status tables
Identifier:	0x3E06
Property type:	PT_BINARY
Property tag:	0x3E060102
Remarks

The PR_OWN_STORE_ENTRYID property specifies the entry identifier for the tightly coupled store, if one exists. For example, a transport provider can specify the private folder store entry identifier so that the MAPI spooler can connect the transport provider to the store.

See Also

PR_STORE_ENTRYID


PR_OWNER_APPT_ID

The PR_OWNER_APPT_ID property contains an identifier for an appointment in the owner’s schedule.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects used for scheduling
Identifier:	0x0062
Property type:	PT_LONG
Property tag:	0x00620003
Remarks

The PR_OWNER_APPT_ID property is used in meeting requests. It does not represent an entry identifier, but a long integer that uniquely identifies the appointment within the sender’s schedule.

See Also

PR_ORIGINAL_AUTHOR_SEARCH_KEY


PR_PAGER_TELEPHONE_NUMBER

The PR_PAGER_TELEPHONE_NUMBER property contains the recipient’s pager telephone number.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A21
Property type:	PT_TSTRING
Property tag:	0x3A21001E (0x3A21001F for Unicode)
Remarks

The PR_PAGER_TELEPHONE_NUMBER property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on these properties, see IMailUser::IMAPIProp.

MAPI also supports the PR_BEEPER_TELEPHONE_NUMBER property that is synonymous with PR_PAGER_TELEPHONE_NUMBER.


PR_PARENT_DISPLAY

The PR_PARENT_DISPLAY property contains the display name of the folder in which a message was found during a search.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Contents tables for search-results folders
Identifier:	0x0E05
Property type:	PT_TSTRING
Property tag:	0x0E05001E (0x0E05001F for Unicode)
Remarks

The PR_PARENT_DISPLAY property is not a property of any object. It can only appear in the contents table of a search-results folder.

The PR_PARENT_DISPLAY, PR_PARENT_ENTRYID, and PR_PARENT_KEY properties are not related to each other. They belong to entirely different contexts.


PR_PARENT_ENTRYID

The PR_PARENT_ENTRYID property contains the entry identifier of the folder containing a folder or message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Folder and message objects
May be a column in:	Folder contents tables
Identifier:	0x0E09
Property type:	PT_BINARY
Property tag:	0x0E090102
Remarks

The PR_PARENT_ENTRYID property is computed by message stores for all folders and messages.

For a message store root folder, PR_PARENT_ENTRYID contains the folder’s own entry identifier.

The PR_PARENT_DISPLAY, PR_PARENT_ENTRYID, and PR_PARENT_KEY properties are not related to each other. They belong to entirely different contexts.

See Also

PR_FOLDER_TYPE


PR_PARENT_KEY

The PR_PARENT_KEY property was originally meant to contain a value used in correlating conversation threads.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x0025
Property type:	PT_BINARY
Property tag:	0x00250102
Corresponding X.400 attribute:	IM_REPLIED_TO_IPM
Remarks

Do not use this property. It is not supported in MAPI 1.0.


PR_PHYSICAL_DELIVERY_BUREAU_FAX_DELIVERY

The PR_PHYSICAL_DELIVERY_BUREAU_FAX_DELIVERY property contains TRUE if the messaging system should use a fax bureau for physical delivery of this message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0C0A
Property type:	PT_BOOLEAN
Property tag:	0x0C0A000B
Corresponding X.400 attribute:	MH_T_BUREAU_FAX_DELIVERY


PR_PHYSICAL_DELIVERY_MODE

The PR_PHYSICAL_DELIVERY_MODE property contains a bitmask of flags defining the physical delivery mode (for example, special delivery) for a message designated for a specific recipient.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects
Identifier:	0x0C0B
Property type:	PT_LONG
Property tag:	0x0C0B0003
Corresponding X.400 attribute:	MH_T_POSTAL_MODE


PR_PHYSICAL_DELIVERY_REPORT_REQUEST

The PR_PHYSICAL_DELIVERY_REPORT_REQUEST property contains the mode of a report to be delivered to a particular message recipient upon completion of physical message delivery or delivery by the message handling system.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects
Identifier:	0x0C0C
Property type:	PT_LONG
Property tag:	0x0C0C0003
Corresponding X.400 attribute:	MH_T_POSTAL_REPORT


PR_PHYSICAL_FORWARDING_ADDRESS

The PR_PHYSICAL_FORWARDING_ADDRESS property contains the physical forwarding address of a message recipient and is used only with message reports.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects
Identifier:	0x0C0D
Property type:	PT_BINARY
Property tag:	0x0C0D0102
Corresponding X.400 attribute:	MH_T_FORWARDING_ADDRESS


PR_PHYSICAL_FORWARDING_ADDRESS_REQUESTED

The PR_PHYSICAL_FORWARDING_ADDRESS_REQUESTED property contains TRUE if a message sender requests the message transfer agent to attach a physical forwarding address for a message recipient.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects
Identifier:	0x0C0E
Property type:	PT_BOOLEAN
Property tag:	0x0C0E000B
Corresponding X.400 attribute:	MH_T_FORWARDING_ADR_REQUESTED


PR_PHYSICAL_FORWARDING_PROHIBITED

The PR_PHYSICAL_FORWARDING_PROHIBITED property contains TRUE if a message sender prohibits physical message forwarding for a specific recipient.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects
Identifier:	0x0C0F
Property type:	PT_BOOLEAN
Property tag:	0x0C0F000B
Corresponding X.400 attribute:	MH_T_FORWARDING_PROHIBITED


PR_PHYSICAL_RENDITION_ATTRIBUTES

The PR_PHYSICAL_RENDITION_ATTRIBUTES property contains an ASN.1 object identifier used for rendering message attachments.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Attachment subobjects
Identifier:	0x0C10
Property type:	PT_BINARY
Property tag:	0x0C100102
Corresponding X.400 attribute:	MH_T_RENDITION_ATTRIBUTES


PR_POST_OFFICE_BOX

The PR_POST_OFFICE_BOX property contains the number or identifier of the recipient’s post office box.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A2B
Property type:	PT_TSTRING
Property tag:	0x3A2B001E (0x3A2B001F for Unicode)
Remarks

The PR_POST_OFFICE_BOX property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_POSTAL_ADDRESS

The PR_POSTAL_ADDRESS property contains the recipient’s postal address.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A15
Property type:	PT_TSTRING
Property tag:	0x3A15001E (0x3A15001F for Unicode)
Remarks

The PR_POSTAL_ADDRESS property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_POSTAL_CODE

The PR_POSTAL_CODE property contains the postal code for the recipient’s postal address.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A2A
Property type:	PT_TSTRING
Property tag:	0x3A2A001E (0x3A2A001F for Unicode)
Remarks

The PR_POSTAL_CODE property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.

The postal code is specific to the recipient’s country. In the United States of America, this property contains the ZIP code.


PR_PREPROCESS

The PR_PREPROCESS property contains TRUE if the message requires preprocessing.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x0E22
Property type:	PT_BOOLEAN
Property tag:	0x0E22000B
Remarks

Do not use this property. It is reserved for use by MAPI.

See Also

PR_SUBMIT_FLAGS


PR_PRIMARY_CAPABILITY

Obsolete address book property.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3904
Property type:	PT_BINARY
Property tag:	0x39040102
Remarks

Do not use this property.


PR_PRIMARY_FAX_NUMBER

The PR_PRIMARY_FAX_NUMBER property contains the telephone number of the recipient’s primary fax machine.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A23
Property type:	PT_TSTRING
Property tag:	0x3A23001E (0x3A23001F for Unicode)
Remarks

The PR_PRIMARY_FAX_NUMBER property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_PRIMARY_TELEPHONE_NUMBER

The PR_PRIMARY_TELEPHONE_NUMBER property contains the recipient’s primary telephone number.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A1A
Property type:	PT_TSTRING
Property tag:	0x3A1A001E (0x3A1A001F for Unicode)
Corresponding X.400 attribute:	IM_TELEPHONE_NUMBER
Remarks

The PR_PRIMARY_TELEPHONE_NUMBER property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_PRIORITY

The PR_PRIORITY property contains the relative priority of a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0026
Property type:	PT_LONG
Property tag:	0x00260003
Corresponding X.400 attribute:	MH_T_PRIORITY
Remarks

The PR_PRIORITY and PR_IMPORTANCE properties should not be confused. Importance indicates a value to users, while priority indicates the order or speed at which the message should be sent by the messaging system software. Higher priority usually indicates a higher cost. Higher importance usually is associated with a different display by the user interface.

The priority of a report message should be the same as the priority of the original message being reported.

PR_PRIORITY can have exactly one of the following values:

PRIO_NONURGENT

The message is not urgent.

PRIO_NORMAL

The message has normal priority.

PRIO_URGENT

The message is urgent.


PR_PROFILE_NAME

The PR_PROFILE_NAME property contains the name of the profile.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Profile section objects
Identifier:	0x3D12
Property type:	PT_TSTRING
Property tag:	0x3D12001E (0x3D12001F for Unicode)
Remarks

The PR_PROFILE_NAME property is computed by service providers. A provider’s implementation of the ServiceEntry function can use the PR_PROFILE_NAME property to discover the profile name.

Client applications can use PR_PROFILE_NAME as a convenient alternative to obtaining the profile name by examining the PR_DISPLAY_NAME property in the MAPI subsystem’s status table row.

PR_PROFILE_NAME may not be unique across time, for example where a profile is deleted and later recreated with the same name. MAPI furnishes a totally unique PR_SEARCH_KEY property in a hard-coded profile section called MUID_PROFILE_INSTANCE.


PR_PROOF_OF_DELIVERY

The PR_PROOF_OF_DELIVERY property contains an ASN.1 proof of delivery value.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects
Identifier:	0x0C11
Property type:	PT_BINARY
Property tag:	0x0C110102
Corresponding X.400 attribute:	MH_T_PROOF_OF_DELIVERY


PR_PROOF_OF_DELIVERY_REQUESTED

The PR_PROOF_OF_DELIVERY_REQUESTED property contains TRUE if a message sender requests proof of delivery for a particular recipient.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects
Identifier:	0x0C12
Property type:	PT_BOOLEAN
Property tag:	0x0C12000B
Corresponding X.400 attribute:	MH_T_PROOF_OF_DELIV_REQUESTED


PR_PROOF_OF_SUBMISSION

The PR_PROOF_OF_SUBMISSION property contains an ASN.1 proof of submission value.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0E26
Property type:	PT_BINARY
Property tag:	0x0E260102
Remarks

The PR_PROOF_OF_SUBMISSION property corresponds to an X.400 submission envelope per-message attribute.


PR_PROOF_OF_SUBMISSION_REQUESTED

The PR_PROOF_OF_SUBMISSION_REQUESTED property contains TRUE if a message sender requests proof that the message transfer system has submitted a message for delivery to the originally intended recipient.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0028
Property type:	PT_BOOLEAN
Property tag:	0x0028000B
Corresponding X.400 attribute:	MH_T_PROOF_OF_SUBMSN_REQUESTED


PR_PROVIDER_DISPLAY

The PR_PROVIDER_DISPLAY property contains the vendor-defined display name for a service provider.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Profile section objects
Identifier:	0x3006
Property type:	PT_TSTRING
Property tag:	0x3006001E (0x3006001F for Unicode)
Remarks

The PR_PROVIDER_DISPLAY and PR_PROVIDER_DLL_NAME properties are defined only on profile sections belonging to service providers. They must be present in MAPISVC.INF.


PR_PROVIDER_DLL_NAME

The PR_PROVIDER_DLL_NAME property contains the base filename of the MAPI service provider DLL.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Profile section objects
Identifier:	0x300A
Property type:	PT_TSTRING
Property tag:	0x300A001E (0x300A001F for Unicode)
Remarks

MAPI uses a DLL file naming convention. The base filename contains up to six characters that uniquely identify the DLL. MAPI appends the string 32 to the base DLL name to identify the version that runs on 32-bit platforms. For example, when the name MAPI.DLL is specified, MAPI constructs the name MAPI32.DLL to represent the corresponding 32-bit version of the DLL.

The PR_PROVIDER_DLL_NAME property should specify the base name. MAPI appends the string 32 as appropriate. Including the string 32 as part of the PR_PROVIDER_DLL_NAME property results in an error.

See Also

PR_SERVICE_DLL_NAME


PR_PROVIDER_ORDINAL

The PR_PROVIDER_ORDINAL property contains the zero-based index of a service provider’s position in the provider table.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Provider table objects
Identifier:	0x300D
Property type:	PT_LONG
Property tag:	0x300D0003
Remarks

The PR_PROVIDER_ORDINAL property is computed by MAPI.

Obtain the provider table by calling the IMsgServiceAdmin::GetProviderTable method. Sort the provider table on the PR_PROVIDER_ORDINAL column to display the transport order.


PR_PROVIDER_SUBMIT_TIME

The PR_PROVIDER_SUBMIT_TIME property contains the date and time a transport provider passed a message to its underlying messaging system.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0048
Property type:	PT_SYSTIME
Property tag:	0x00480040
Remarks

The PR_PROVIDER_SUBMIT_TIME property is set by the outgoing transport provider at the time a message is sent.

PR_PROVIDER_SUBMIT_TIME corresponds to an X.400 submission envelope per-message attribute.


PR_PROVIDER_UID

The PR_PROVIDER_UID property contains a MAPIUID structure of the service provider that is handling a message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Provider table objects
Identifier:	0x300C
Property type:	PT_BINARY
Property tag:	0x300C0102
Remarks

The PR_PROVIDER_UID property is computed by all service providers. It contains a MAPIUID structure associated with, and usually hard-coded by, the provider. It is typically used by a client application that is interested in only the address book containers supplied by a particular provider.

PR_PROVIDER_UID appears only as a column entry in the provider table.


PR_RADIO_TELEPHONE_NUMBER

The PR_RADIO_TELEPHONE_NUMBER property contains the recipient’s radio telephone number.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A1D
Property type:	PT_TSTRING
Property tag:	0x3A1D001E (0x3A1D001F for Unicode)
Remarks

The PR_RADIO_TELEPHONE_NUMBER property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_RCVD_REPRESENTING_ADDRTYPE

The PR_RCVD_REPRESENTING_ADDRTYPE property contains the address type for the messaging user represented by the user actually receiving the message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0077
Property type:	PT_TSTRING
Property tag:	0x0077001E (0x0077001F for Unicode)
Remarks

The PR_RCVD_REPRESENTING_ADDRTYPE property is one of the address properties for the messaging user being represented by the receiving user. It must be set by the incoming transport provider, which is also responsible for authorization or verification of the delegate. If no messaging user is being represented, PR_RCVD_REPRESENTING_ADDRTYPE should be set to the address type contained in the PR_RECEIVED_BY_ADDRTYPE property.

A client application replying to a message received on behalf of another client should copy PR_RCVD_REPRESENTING_ADDRTYPE from the received message into the PR_SENT_REPRESENTING_ADDRTYPE property for the reply.

For more information on the address properties, see Base Address Properties.

See Also

PR_ADDRTYPE


PR_RCVD_REPRESENTING_EMAIL_ADDRESS

The PR_RCVD_REPRESENTING_EMAIL_ADDRESS property contains the e-mail address for the messaging user represented by the receiving user.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0078
Property type:	PT_TSTRING
Property tag:	0x0078001E (0x0078001F for Unicode)
Remarks

The PR_RCVD_REPRESENTING_EMAIL_ADDRESS property is one of the address properties for the messaging user being represented by the receiving user. It must be set by the incoming transport provider, which is also responsible for authorization or verification of the delegate. If no messaging user is being represented, PR_RCVD_REPRESENTING_EMAIL_ADDRESS should be set to the e-mail address contained in the PR_RECEIVED_BY_EMAIL_ADDRESS property.

A client application replying to a message received on behalf of another client should copy PR_RCVD_REPRESENTING_EMAIL_ADDRESS from the received message into the PR_SENT_REPRESENTING_EMAIL_ADDRESS property for the reply.

For more information on the address properties, see Base Address Properties.

See Also

PR_EMAIL_ADDRESS


PR_RCVD_REPRESENTING_ENTRYID

The PR_RCVD_REPRESENTING_ENTRYID property contains the entry identifier for the messaging user represented by the receiving user.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0043
Property type:	PT_BINARY
Property tag:	0x00430102
Remarks

The PR_RCVD_REPRESENTING_ENTRYID property is one of the address properties for the messaging user being represented by the receiving user. It must be set by the incoming transport provider, which is also responsible for authorization or verification of the delegate. If no messaging user is being represented, PR_RCVD_REPRESENTING_ENTRYID should be set to the entry identifier contained in the PR_RECEIVED_BY_ENTRYID property.

A client application replying to a message received on behalf of another client should copy PR_RCVD_REPRESENTING_ENTRYID from the received message into the PR_SENT_REPRESENTING_ENTRYID property for the reply.

For more information on the address properties, see Base Address Properties.

See Also

PR_ENTRYID


PR_RCVD_REPRESENTING_NAME

The PR_RCVD_REPRESENTING_NAME property contains the display name for the messaging user represented by the receiving user.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0044
Property type:	PT_TSTRING
Property tag:	0x0044001E (0x0044001F for Unicode)
Remarks

The PR_RCVD_REPRESENTING_NAME property is one of the address properties for the messaging user being represented by the receiving user. It must be set by the incoming transport provider, which is also responsible for authorization or verification of the delegate. If no messaging user is being represented, PR_RCVD_REPRESENTING_NAME should be set to the display name contained in the PR_RECEIVED_BY_NAME property.

A client application replying to a message received on behalf of another client should copy PR_RCVD_REPRESENTING_NAME from the received message into the PR_SENT_REPRESENTING_NAME property for the reply.

For more information on the address properties, see Base Address Properties.

See Also

PR_DISPLAY_NAME


PR_RCVD_REPRESENTING_SEARCH_KEY

The PR_RCVD_REPRESENTING_SEARCH_KEY property contains the search key for the messaging user represented by the receiving user.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0052
Property type:	PT_BINARY
Property tag:	0x00520102
Remarks

The PR_RCVD_REPRESENTING_SEARCH_KEY is one of the address properties for the messaging user being represented by the receiving user. It must be set by the incoming transport provider, which is also responsible for authorization or verification of the delegate. If no messaging user is being represented, PR_RCVD_REPRESENTING_SEARCH_KEY should be set to the search key contained in the PR_RECEIVED_BY_SEARCH_KEY property.

A client application replying to a message received on behalf of another client should copy PR_RCVD_REPRESENTING_SEARCH_KEY from the received message into the PR_SENT_REPRESENTING_SEARCH_KEY property for the reply.

For more information on the address properties, see Base Address Properties.

See Also

PR_SEARCH_KEY


PR_READ_RECEIPT_ENTRYID

The PR_READ_RECEIPT_ENTRYID property contains an entry identifier for the messaging user to which the messaging system should direct a read report for this message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0046
Property type:	PT_BINARY
Property tag:	0x00460102
Remarks

The PR_READ_RECEIPT_ENTRYID property is ignored unless the PR_READ_RECEIPT_REQUESTED property is set to TRUE.

If a client application wants to receive read reports itself, it can leave PR_READ_RECEIPT_ENTRYID unset or set it to the entry identifier contained in the PR_SENDER_ENTRYID property at message submission time.


PR_READ_RECEIPT_REQUESTED

The PR_READ_RECEIPT_REQUESTED property contains TRUE if a message sender wants the messaging system to generate a read report when the recipient has read a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects, message objects
Identifier:	0x0029
Property type:	PT_BOOLEAN
Property tag:	0x0029000B
Corresponding X.400 attribute:	IM_NOTIFICATION_REQUEST
Remarks

The PR_READ_RECEIPT_REQUESTED property must be set to TRUE to validate the values in the PR_READ_RECEIPT_ENTRYID and PR_READ_RECEIPT_SEARCH_KEY properties.

If a message with PR_READ_RECEIPT_REQUESTED set is deleted or expires before the messaging system can generate a read report, a nonread report is generated.


PR_READ_RECEIPT_SEARCH_KEY

The PR_READ_RECEIPT_SEARCH_KEY property contains a search key for the messaging user to which the messaging system should direct a read report for a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0053
Property type:	PT_BINARY
Property tag:	0x00530102
Remarks

The PR_READ_RECEIPT_SEARCH_KEY property is ignored unless the PR_READ_RECEIPT_REQUESTED property is set to TRUE.

If a client application wants to receive read reports itself, it can leave PR_READ_RECEIPT_SEARCH_KEY unset or set it to the search key contained in the PR_SENDER_SEARCH_KEY property at message submission time.


PR_RECEIPT_TIME

The PR_RECEIPT_TIME property contains the date and time a delivery report is generated.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Report message objects
Identifier:	0x002A
Property type:	PT_SYSTIME
Property tag:	0x002A0040
Corresponding X.400 attribute:	IM_RECEIPT_TIME
Remarks

The PR_RECEIPT_TIME property must be set by the message store provider receiving the original message and generating the report. The report is usually generated with the IMAPISupport::ReadReceipt method.

See Also

PR_REPORT_ENTRYID


PR_RECEIVE_FOLDER_SETTINGS

The PR_RECEIVE_FOLDER_SETTINGS property contains a table of a message store’s receive folder settings.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message store objects
Identifier:	0x3415
Property type:	PT_OBJECT
Property tag:	0x3415000D
Remarks

The PR_RECEIVE_FOLDER_SETTINGS property can be excluded in IMAPIProp::CopyTo operations or included in IMAPIProp::CopyProps operations. As a property of type PT_OBJECT, it cannot be successfully retrieved by the IMAPIProp::GetProps method; its contents should be accessed by the IMAPIProp::OpenProperty method, requesting the interface with identifier IID_IMAPITable. Service providers must report it to the IMAPIProp::GetPropList method if it is set, but can optionally report it or not if it is not set.

To retrieve table contents, a client application should call the IMsgStore::GetReceiveFolderTable method. For more information, see Receive Folder Tables.

PR_RECEIVE_FOLDER_SETTINGS contains a table of mappings of the receive folders for the message store. Calling OpenProperty on this property is equivalent to calling GetReceiveFolderTable on the message store.


PR_RECEIVED_BY_ADDRTYPE

The PR_RECEIVED_BY_ADDRTYPE property contains the e-mail address type, such as SMTP, for the messaging user that actually receives the message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0075
Property type:	PT_TSTRING
Property tag:	0x0075001E (0x0075001F for Unicode)
Remarks

The PR_RECEIVED_BY_ADDRTYPE property is one of the address properties for the messaging user that actually receives the message. It must be set by the incoming transport provider.

The address type string can contain only the uppercase alphabetic characters A through Z and the numbers 0 through 9. PR_RECEIVED_BY_ADDRTYPE qualifies the PR_RECEIVED_BY_EMAIL_ADDRESS property by specifying an address type, such as SMTP, thereby indicating how the address should be constructed.

For more information on the address properties, see Base Address Properties.

See Also

PR_ADDRTYPE


PR_RECEIVED_BY_EMAIL_ADDRESS

The PR_RECEIVED_BY_EMAIL_ADDRESS property contains the e-mail address for the messaging user that actually receives the message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0076
Property type:	PT_TSTRING
Property tag:	0x0076001E (0x0076001F for Unicode)
Remarks

The PR_RECEIVED_BY_EMAIL_ADDRESS property is one of the address properties for the messaging user that actually receives the message. It must be set by the incoming transport provider.

For more information on the address properties, see Base Address Properties.

See Also

PR_EMAIL_ADDRESS


PR_RECEIVED_BY_ENTRYID

The PR_RECEIVED_BY_ENTRYID property contains the entry identifier of the messaging user that actually receives the message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x003F
Property type:	PT_BINARY
Property tag:	0x003F0102
Remarks

The PR_RECEIVED_BY_ENTRYID property is one of the address properties for the messaging user that actually receives the message. It must be set by the incoming transport provider.

For more information on the address properties, see Base Address Properties.

PR_RECEIVED_BY_ENTRYID corresponds to an X.400 delivery envelope per-message MH_T_ attribute.

See Also

PR_ENTRYID


PR_RECEIVED_BY_NAME

The PR_RECEIVED_BY_NAME property contains the display name of the messaging user that actually receives the message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0040
Property type:	PT_TSTRING
Property tag:	0x0040001E (0x0040001F for Unicode)
Corresponding X.400 attribute:	MH_T_ACTUAL_RECIPIENT_NAME
Remarks

The PR_RECEIVED_BY_NAME property is one of the address properties for the messaging user that actually receives the message. It must be set by the incoming transport provider.

For more information on the address properties, see Base Address Properties.

See Also

PR_DISPLAY_NAME


PR_RECEIVED_BY_SEARCH_KEY

The PR_RECEIVED_BY_SEARCH_KEY property contains the search key of the messaging user that actually receives the message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0051
Property type:	PT_BINARY
Property tag:	0x00510102
Remarks

The PR_RECEIVED_BY_SEARCH_KEY property is one of the address properties for the messaging user that actually receives the message. It must be set by the incoming transport provider.

For more information on the address properties, see Base Address Properties.

See Also

PR_SEARCH_KEY


PR_RECIPIENT_CERTIFICATE

The PR_RECIPIENT_CERTIFICATE property contains a message recipient’s ASN.1 certificate for use in a report.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects
Identifier:	0x0C13
Property type:	PT_BINARY
Property tag:	0x0C130102
Corresponding X.400 attribute:	MH_T_RECEIPT_CERTIFICATE
Remarks

The PR_RECIPIENT_CERTIFICATE property is a copy of the recipient’s PR_USER_CERTIFICATE property for use in a report. It can be used to prove to the originator that the recipient actually received the message, which a delivery report does not necessarily indicate.

See Also

PR_RECIPIENT_NUMBER_FOR_ADVICE


PR_RECIPIENT_NUMBER_FOR_ADVICE

The PR_RECIPIENT_NUMBER_FOR_ADVICE property contains a message recipient’s voice telephone number to call to advise of the physical delivery of a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects
Identifier:	0x0C14
Property type:	PT_TSTRING
Property tag:	0x0C14001E (0x0C14001F for Unicode)
Corresponding X.400 attribute:	MH_T_RECIP_NUMBER_FOR_ADVICE
Remarks

The PR_RECIPIENT_NUMBER_FOR_ADVICE property is meant to be used in conjunction with delivery to a physical destination, rather than an electronic mailbox, when the human recipient is not expected to be present at delivery. An example is the telephone number usually included on a fax cover sheet.

See Also

PR_RECIPIENT_REASSIGNMENT_PROHIBITED


PR_RECIPIENT_REASSIGNMENT_PROHIBITED

The PR_RECIPIENT_REASSIGNMENT_PROHIBITED property contains TRUE if recipient reassignment is prohibited.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x002B
Property type:	PT_BOOLEAN
Property tag:	0x002B000B
Corresponding X.400 attribute:	MH_T_REASSIGNMENT_PROHIBITED


PR_RECIPIENT_STATUS

The PR_RECIPIENT_STATUS property contains a value used by the MAPI spooler in assigning delivery responsibility among transport providers.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x0E15
Property type:	PT_LONG
Property tag:	0x0E150003
Remarks

Do not use this property. It is reserved for use by MAPI.


PR_RECIPIENT_TYPE

The PR_RECIPIENT_TYPE property contains the recipient type for a message recipient.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Recipient subobjects
Identifier:	0x0C15
Property type:	PT_LONG
Property tag:	0x0C150003
Remarks

The recipient type contained in the PR_RECIPIENT_TYPE property consists of one required value and one optional flag.

PR_RECIPIENT_TYPE must contain exactly one of the following values:

MAPI_TO

The recipient is a primary (To) recipient. Clients are required to handle primary recipients; all other types are optional.

MAPI_CC

The recipient is a carbon copy (CC) recipient, a recipient that receives a message in addition to the primary recipients.

MAPI_BCC

The recipient is a blind carbon copy (BCC) recipient. Primary and carbon copy recipients are unaware of the existence of BCC recipients.

MAPI_P1

The recipient did not successfully receive the message on the previous attempt. This is a resend of an earlier transmission.

In addition, the following flag can be set:

MAPI_SUBMITTED

The recipient has already received the message and does not need to receive it again. This is a resend of an earlier transmission. This flag is set in conjunction with the MAPI_TO, MAPI_CC, and MAPI_BCC values.

The MAPI_P1 value and the MAPI_SUBMITTED flag are used when a message is being retransmitted due to nondelivery to one or more of the intended recipients. For this retransmission, the client sets MAPI_SUBMITTED on every recipient that does not need the message again but should be displayed in the recipient list. For every recipient that did not receive the message previously, the client retains the original recipient with its PR_RECIPIENT_TYPE value unchanged, but additionally submits a copy of the recipient with MAPI_P1 in place of the original value. This copy, which is discarded before actual delivery, forces the recipient into the P1 envelope and guarantees physical retransmission to that recipient. The PR_RESPONSIBILITY property is set to FALSE for MAPI_P1 recipients.

When a client displays a resend form, only the MAPI_P1 recipients are visible. Unless the user enters additional recipients, when the message is delivered, the recipient list appears exactly as it did when the message was sent for the first time.

The PR_DISPLAY_TO, PR_DISPLAY_CC, and PR_DISPLAY_BCC properties are related to recipient type. When a client calls a message’s IMAPIProp::SaveChanges and there is at least one recipient in the recipient list, the message store provider sets these properties as follows:

Property	Description
PR_DISPLAY_TO	Set to TRUE if one or more of the recipients are MAPI_TO recipients.
PR_DISPLAY_CC	Set to TRUE if one or more of the recipients are MAPI_CC recipients.
PR_DISPLAY_BCC	Set to TRUE if one or more of the recipients are MAPI_BCC recipients.
In X.400, the P1 or delivery envelope is the information needed to deliver a message, including the recipient’s address properties and any option flags controlling delivery and replies. The P2 or display envelope is the information usually displayed to each recipient other than the message text itself. It typically includes the subject, importance, priority, sensitivity, and submission time, as well as the primary and copied recipient names.

See Also

PR_RECIPIENT_STATUS, PR_DISPLAY_TO, PR_DISPLAY_BCC, PR_DISPLAY_CC


PR_RECORD_KEY

The PR_RECORD_KEY property contains a unique binary-comparable identifier for a specific object.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Address book container, attachment, distribution list, folder, messaging user, message, and message store objects
Identifier:	0x0FF9
Property type:	PT_BINARY
Property tag:	0x0FF90102
Remarks

The PR_RECORD_KEY property facilitates locating references to an object, such as finding its row in a contents table. PR_RECORD_KEY cannot be used to open an object; use the entry identifier for that purpose.

An attachment subobject should be uniquely identified within a message by PR_RECORD_KEY. This identifier is the only attachment characteristic guaranteed to stay the same after the message is closed and reopened. The store provider must preserve PR_RECORD_KEY across sessions to ensure this guarantee.

For folders, this property contains a key used in the folder hierarchy table. Typically this is the same value as that provided by the PR_ENTRYID property.

For message stores, this property is identical to the PR_STORE_RECORD_KEY property.

In a message store object, PR_RECORD_KEY should be unique across all store providers. One way to do this is to combine the value of the PR_MDB_PROVIDER property for the store (unique to that provider type) with a GUID structure  or other value unique to the specific message store.

PR_RECORD_KEY is always available through the IMAPIProp::GetProps method following the first call to the IMAPIProp::SaveChanges method. Some providers can make it available immediately after instantiation.

A client or service provider can compare PR_RECORD_KEY values using memcmp. This is not possible for entry identifier values. However, PR_RECORD_KEY is guaranteed to be unique only within the same message store or address book container; two objects from different containers can have the same PR_RECORD_KEY value.

One distinction between the record and search keys is that the record key is specific to the object, whereas the search key can be copied to other objects. For example, two copies of the object can have the same PR_SEARCH_KEY value but must have different PR_RECORD_KEY values.

The following table summarizes important differences among PR_ENTRYID, PR_RECORD_KEY, and PR_SEARCH_KEY.

Characteristic	PR_ENTRYID	PR_RECORD_KEY	PR_SEARCH_KEY
Required on  attachment objects	No	Yes	No
Required on  folder objects	Yes	Yes	No
Required on  message store objects	Yes	Yes	No
Required on  status objects	Yes	No	No
Creatable by client	No	No	Yes
Available before a call to  SaveChanges	Maybe	Maybe	Messages — Yes Others — Maybe
Changed in a  copy operation	Yes	Yes	No
Changeable by a client  after a copy	No	No	Yes
Unique within ...	Entire world	Provider instance	Entire world
Binary comparable  (as with memcmp)	No -- use  IMAPISupport:: CompareEntryIDs	Yes	Yes


PR_REDIRECTION_HISTORY

The PR_REDIRECTION_HISTORY property contains information about the route covered by a delivered message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x002C
Property type:	PT_BINARY
Property tag:	0x002C0102
Corresponding X.400 attribute:	MH_T_REDIRECTION_HISTORY
Remarks

The PR_REDIRECTION_HISTORY property is used when a message is autoforwarded by an automatic agent.


PR_REGISTERED_MAIL_TYPE

The PR_REGISTERED_MAIL_TYPE property contains the type of registration used for physical delivery of a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0C16
Property type:	PT_LONG
Property tag:	0x0C160003
Corresponding X.400 attribute:	MH_T_REGISTRATION
See Also

PR_X400_CONTENT_TYPE


PR_RELATED_IPMS

The PR_RELATED_IPMS property contains a list of identifiers for messages to which a message is related.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x002D
Property type:	PT_BINARY
Property tag:	0x002D0102
Corresponding X.400 attribute:	IM_RELATED_IPMS
Remarks

The identifiers use the same specific construction rules as are used for the PR_SEARCH_KEY property.


PR_REMOTE_PROGRESS

The PR_REMOTE_PROGRESS property contains a number indicating the status of a remote transfer.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x3E0B
Property type:	PT_LONG
Property tag:	0x3E0B0003
Remarks

If no transfer is in progress, the PR_REMOTE_PROGRESS property should be set to −1. If a transfer is in progress, it should be set to a value from 0 to 100 indicating the transfer’s percent of completion.

The text associated with the numeric status code appears in the PR_REMOTE_PROGRESS_TEXT property.

The following flags can be set for PR_REMOTE_PROGRESS:

MSGSTATUS_REMOTE_DELETE

The message transfer is deleted.

MSGSTATUS_REMOTE_DOWNLOAD

The message transfer is in progress.


PR_REMOTE_PROGRESS_TEXT

The PR_REMOTE_PROGRESS_TEXT property contains an ASCII string indicating the status of a remote transfer.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x3E0C
Property type:	PT_TSTRING
Property tag:	0x3E0C001E (0x3E0C001F for Unicode)
Remarks

A numeric code associated with this text is passed in the PR_REMOTE_PROGRESS property.


PR_REMOTE_VALIDATE_OK

The PR_REMOTE_VALIDATE_OK property contains TRUE if the remote viewer is allowed to call the IMAPIStatus::ValidateState method.

Quick Info

Header file:	MAPITAGS.H
May be a column in:	Status tables
Identifier:	0x3E0D
Property type:	PT_BOOLEAN
Property tag:	0x3E0D000B
Remarks

The PR_REMOTE_VALIDATE_OK property appears in the status table and offers some control over transport performance. It can be considered as another way of directing the remote viewer to idle. When it is set to TRUE, the remote viewer can call IMAPIStatus::ValidateState as often as desired. A value of FALSE indicates that the remote viewer cannot make any more calls.

The transport provider usually sets this property dynamically, setting the value to FALSE to disable additional calls when the transport provider has a sufficient amount of processing to perform. When the transport provider is done, it then sets the value to TRUE to allow the client application to make further IMAPIStatus::ValidateState calls.


PR_RENDERING_POSITION

The PR_RENDERING_POSITION property contains an offset, in characters, to use in rendering an attachment within the main message text.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Attachment subobjects
Identifier:	0x370B
Property type:	PT_LONG
Property tag:	0x370B0003
Remarks

When the supplied offset is −1 (0xFFFFFFFF), the attachment is not rendered using the PR_RENDERING_POSITION property. All values other than −1 indicate the position within PR_BODY at which the attachment is to be rendered.

Note  The character at PR_RENDERING_POSITION in PR_BODY is replaced by the attachment. Typically this character is a space, although a special placeholder character can also be used.

PR_RENDERING_POSITION is expressed in characters. In some character sets this is not equivalent to bytes. Unicode applications can compute the position based on two-byte characters. Double-Byte Character Set (DBCS) applications must scan the text up to the PR_RENDERING_POSITION value, because their character representation varies between one and two bytes per character.

This property should not be used with Rich Text Format (RTF) text. The rendering position is indicated in RTF by an escape sequence called the object attachment placeholder. This sequence consists of the string \objattph followed by a single character, normally a space, that will be replaced by the attachment rendering.


PR_REPLY_RECIPIENT_ENTRIES

The PR_REPLY_RECIPIENT_ENTRIES property contains a sized array of entry identifiers for recipients that are to get a reply.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x004F
Property type:	PT_BINARY
Property tag:	0x004F0102
Corresponding X.400 attribute:	IM_REPLY_RECIPIENTS
Remarks

The PR_REPLY_RECIPIENT_ENTRIES property contains a FLATENTRYLIST structure and is not a multivalued property.

When this property is not present, a reply is sent only to the user identified by PR_SENDER_ENTRYID. When PR_REPLY_RECIPIENT_ENTRIES and PR_REPLY_RECIPIENT_NAMES are defined, the reply is sent to all of the recipients identified by these two properties. A transport provider uses these properties to override the usual reply logic.

If either PR_REPLY_RECIPIENT_ENTRIES or PR_REPLY_RECIPIENT_NAMES is set, the other property must be set also. These properties must contain the same number of recipients, and they must contain them in the same order. Failure to observe these requirements can cause unpredictable results.


PR_REPLY_RECIPIENT_NAMES

The PR_REPLY_RECIPIENT_NAMES property contains a list of display names for recipients that are to get a reply.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0050
Property type:	PT_TSTRING
Property tag:	0x0050001E (0x0050001F for Unicode)
Remarks

The PR_REPLY_RECIPIENT_NAMES property contains one string, with the display names separated by semicolons.

When this property is not present, a reply is sent only to the user identified by PR_SENDER_NAME. When PR_REPLY_RECIPIENT_ENTRIES and PR_REPLY_RECIPIENT_NAMES are defined, the reply is sent to all of the recipients identified by these two properties. A transport provider uses these properties to override the usual reply logic.

If either PR_REPLY_RECIPIENT_ENTRIES or PR_REPLY_RECIPIENT_NAMES is set, the other property must be set also. These properties must contain the same number of recipients, and they must contain them in the same order. Failure to observe these requirements can cause unpredictable results.


PR_REPLY_REQUESTED

The PR_REPLY_REQUESTED property contains TRUE if a message sender requests a reply from a recipient.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0C17
Property type:	PT_BOOLEAN
Property tag:	0x0C17000B
Corresponding X.400 attribute:	IM_REPLY_REQUESTED
See Also

PR_REPLY_TIME


PR_REPLY_TIME

The PR_REPLY_TIME property contains the date and time by which a reply is expected for a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0030
Property type:	PT_SYSTIME
Property tag:	0x00300040
Corresponding X.400 attribute:	IM_REPLY_TIME
See Also

PR_REPLY_REQUESTED


PR_REPORT_ENTRYID

The PR_REPORT_ENTRYID property contains the entry identifier for the recipient that should get reports for this message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0045
Property type:	PT_BINARY
Property tag:	0x00450102
Remarks

The PR_REPORT_ENTRYID property is one of the address properties for the recipient that the sender has delegated to receive any reports generated for this message.

A client application that needs to route reports to another user should set this property at message submission time. If it is not set, the reports are sent to the message sender.

For more information on the address properties, see Base Address Properties.

See Also

PR_SENDER_ENTRYID


PR_REPORT_NAME

The PR_REPORT_NAME property contains the display name for the recipient that should get reports for this message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x003A
Property type:	PT_TSTRING
Property tag:	0x003A001E (0x003A001F for Unicode)
Remarks

The PR_REPORT_NAME property is one of the address properties for the recipient that the sender has delegated to receive any reports generated for this message.

A client application that needs to route reports to another user should set this property at message submission time. If it is not set, the reports are sent to the message sender.

For more information on the address properties, see Base Address Properties.

See Also

PR_SENDER_NAME


PR_REPORT_SEARCH_KEY

The PR_REPORT_SEARCH_KEY property contains the search key for the recipient that should get reports for this message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0054
Property type:	PT_BINARY
Property tag:	0x00540102
Remarks

The PR_REPORT_SEARCH_KEY property is one of the address properties for the recipient that the sender has delegated to receive any reports generated for this message.

A client application that needs to route reports to another user should set this property at message submission time. If it is not set, the reports are sent to the message sender.

For more information on the address properties, see Base Address Properties.

See Also

PR_SENDER_SEARCH_KEY


PR_REPORT_TAG

The PR_REPORT_TAG property contains a binary tag value that the messaging system should copy to any report generated for the message.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0031
Property type:	PT_BINARY
Property tag:	0x00310102
Remarks

The PR_REPORT_TAG property, like the PR_SUBJECT_IPM property property, is used to correlate a report with the original message.

See Also

PR_REPORT_NAME


PR_REPORT_TEXT

The PR_REPORT_TEXT property contains optional text for a report generated by the messaging system.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x1001
Property type:	PT_TSTRING
Property tag:	0x1001001E (0x1001001F for Unicode)
Remarks

Usually, the text contained in the PR_REPORT_TEXT property is generated in response to a delivery or nondelivery report or a read or nonread report received from the underlying messaging system, but is not itself text that was transferred through that system.


PR_REPORT_TIME

The PR_REPORT_TIME property contains the date and time when the messaging system generated a report.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Read and nonread report message objects and recipient subobjects within delivery and nondelivery report message objects
Identifier:	0x0032
Property type:	PT_SYSTIME
Property tag:	0x00320040
Remarks

The PR_REPORT_TIME property represents a per-recipient property on delivery and nondelivery reports and a per-message property on read and nonread reports.


PR_REPORTING_DL_NAME

The PR_REPORTING_DL_NAME property contains the display name of a distribution list for which the messaging system is delivering a report.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Report message objects
Identifier:	0x1003
Property type:	PT_BINARY
Property tag:	0x10030102
Corresponding X.400 attribute:	MH_T_REPORTING_DL_NAME


PR_REPORTING_MTA_CERTIFICATE

The PR_REPORTING_MTA_CERTIFICATE property contains an identifier for the message transfer agent that generated a report.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Report message objects
Identifier:	0x1004
Property type:	PT_BINARY
Property tag:	0x10040102
Corresponding X.400 attribute:
Remarks

The PR_REPORTING_MTA_CERTIFICATE property corresponds to an X.400 report per-message attribute.

See Also

PR_ORIGINATING_MTA_CERTIFICATE


PR_REQUESTED_DELIVERY_METHOD

The PR_REQUESTED_DELIVERY_METHOD property contains a binary array of delivery methods (service providers), in order of a message sender’s preference.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0C18
Property type:	PT_BINARY
Property tag:	0x0C180102
Corresponding X.400 attribute:	MH_T_PREFERRED_DELIVERY_MODE
Remarks

The array contained in the PR_REQUESTED_DELIVERY_METHOD property consists of 32-bit ASN.1 identifiers for each of the service providers. Typical identifier values are MH_DM_TELEX and MH_DM_G3FAX.

See Also

PR_PROOF_OF_DELIVERY_REQUESTED


PR_RESOURCE_FLAGS

The PR_RESOURCE_FLAGS property contains a bitmask of flags for message services and providers.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Status objects
Must be a column in:	Message service, message store, and status tables
Identifier:	0x3009
Property type:	PT_LONG
Property tag:	0x30090003
Remarks

PR_RESOURCE_FLAGS describes the characteristics of a message service, a service provider, or a status object. The flags that are set for PR_RESOURCE_FLAGS depend on its context. For example, some flags are valid only for status objects and other flags only for columns in the message service table.

The flags are of three classes: static, modifiable, and dynamic. Static flags are set by MAPI from data in MAPISVC.INF and never altered. Modifiable flags are set by MAPI from MAPISVC.INF but can be subsequently changed. Dynamic flags can be set and reset by MAPI methods.

For a message service, one or more of the following flags can be set in PR_RESOURCE_FLAGS:

SERVICE_CREATE_WITH_STORE

Reserved. Do not use.

SERVICE_DEFAULT_STORE

Dynamic. The message service contains the default store. A user interface should be displayed prompting the user for confirmation before deleting or moving this service out of the profile.

SERVICE_NO_PRIMARY_IDENTITY

Static. The service level flag that should be set to indicate that none of the providers in the message service can be used to supply an identity. Either this flag or SERVICE_PRIMARY_IDENTITY should be set, but not both.

SERVICE_PRIMARY_IDENTITY

Modifiable. The corresponding message service contains the provider used for the primary identity for this session. Use IMsgServiceAdmin::SetPrimaryIdentity to set this flag. Either this flag or SERVICE_NO_PRIMARY_IDENTITY should be set, but not both.

SERVICE_SINGLE_COPY

Static. Any attempt to create or copy this message service into a profile where the service already exists will fail. To create a single copy message service add the PR_RESOURCE_FLAGS property to the service’s section in MAPISVC.INF and set this flag.

For a service provider, one or more of the following flags can be set in PR_RESOURCE_FLAGS:

HOOK_INBOUND

Static. The spooler hook needs to process inbound messages.

HOOK_OUTBOUND

Static. The spooler hook needs to process outbound messages.

STATUS_DEFAULT_OUTBOUND

Modifiable. This identity should be applied to outbound messages if the profile contains multiple instances of this transport provider. This can happen if multiple instances of a single transport provider appear in the profile.

STATUS_DEFAULT_STORE

Modifiable. This message store is the default store for the profile.

STATUS_NEED_IPM_TREE

Dynamic. The standard folders in this message store, including the interpersonal message (IPM) root folder, have not yet been verified. MAPI sets and clears this flag.

STATUS_NO_DEFAULT_STORE

Static. This message store is incapable of becoming the default message store for the profile.

STATUS_NO_PRIMARY_IDENTITY

Static. This provider does not furnish an identity in its status row. Either this flag or STATUS_PRIMARY_IDENTITY must be set.

STATUS_OWN_STORE

Static. This transport provider is tightly coupled with a message store and furnishes the PR_OWN_STORE_ENTRYID property in its status row.

STATUS_PRIMARY_IDENTITY

Modifiable. This provider furnishes the primary identity for the session; the entry identifier for the object furnishing the identity is returned from IMAPISession::QueryIdentity. Either this flag or STATUS_NO_PRIMARY_IDENTITY must be set.

STATUS_PRIMARY_STORE

Modifiable. This message store is to be used when a client application logs on. Once opened, this store should be set as the default store for the profile.

STATUS_SECONDARY_STORE

Modifiable. This message store is to be used if the primary store is not available when a client application logs on. Once opened, this store should be set as the default store for the profile.

STATUS_SIMPLE_STORE

Dynamic. This message store will be used by Simple MAPI or CMC as its default message store.

STATUS_TEMP_SECTION

Dynamic. This message store should not be published in the message store table and will be deleted from the profile after logoff.

STATUS_XP_PREFER_LAST

Static. This transport expects to be the last transport selected to send a message when multiple transport providers are able to transmit the message.

See Also

IMsgServiceAdmin::MsgServiceTransportOrder, PR_IDENTITY_ENTRYID


PR_RESOURCE_METHODS

The PR_RESOURCE_METHODS property contains a bitmask of flags indicating the methods in the IMAPIStatus interface that are supported by the status object.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Status objects
Must be a column in:	Status tables
Identifier:	0x3E02
Property type:	PT_LONG
Property tag:	0x3E020003
Remarks

PR_RESOURCE_METHODS indicates which of the methods in a status object’s implementation of IMAPIStatus are supported. Status objects are allowed to return MAPI_E_NO_SUPPORT from unsupported methods.

Clients use a status object’s PR_RESOURCE_METHODS property to avoid making calls to unsupported methods. If the flag that corresponds to a particular method is set, the method exists and can be called. If that flag is clear, the method should not be called.

The status objects implemented by MAPI support the following methods:

Status object	Supported methods
MAPI subsystem	ValidateState only
MAPI address book	ValidateState only
MAPI spooler	ValidateState and FlushQueues
One or more of the following flags can be set in PR_RESOURCE_METHODS:

STATUS_CHANGE_PASSWORD

Indicates that the IMAPIStatus::ChangePassword method is supported.

STATUS_FLUSH_QUEUES

Indicates that the IMAPIStatus::FlushQueues method is supported.

STATUS_SETTINGS_DIALOG

Indicates that the IMAPIStatus::SettingsDialog method is supported.

STATUS_VALIDATE_STATE

Indicates that the IMAPIStatus::ValidateState method is supported.


PR_RESOURCE_PATH

The PR_RESOURCE_PATH property contains a path to the service provider’s server.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Status objects
May be a column in:	Status tables
Identifier:	0x3E07
Property type:	PT_TSTRING
Property tag:	0x3E07001E (0x3E07001F for Unicode)
Remarks

The path contained in the PR_RESOURCE_PATH property represents the suggested path where the user can find resources. The definition of the property is provider specific. For example, a scheduling application uses this property to specify the suggested location for its scheduling application files.

The messaging user profile furnishes PR_RESOURCE_PATH as a convenience so that a client application does not have to prompt the messaging user for a network path or network drive letter.

MAPI works only with filenames, and other strings passed to it, in the ANSI character set. Applications that use filenames in an OEM character set must convert them to ANSI before calling MAPI.


PR_RESOURCE_TYPE

The PR_RESOURCE_TYPE property contains a value indicating the service provider type.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Provider objects
Identifier:	0x3E03
Property type:	PT_LONG
Property tag:	0x3E030003
Remarks

The PR_RESOURCE_TYPE property can have exactly one of the following values:

MAPI_AB

Address book

MAPI_AB_PROVIDER

Address book provider

MAPI_HOOK_PROVIDER

Spooler hook provider

MAPI_PROFILE_PROVIDER

Profile provider

MAPI_SPOOLER

Message spooler

MAPI_STORE_PROVIDER

Message store provider

MAPI_SUBSYSTEM

Internal MAPI subsystem

MAPI_TRANSPORT_PROVIDER

Transport provider


PR_RESPONSE_REQUESTED

The PR_RESPONSE_REQUESTED property contains TRUE if the message sender wants a response to a meeting request.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects used for scheduling
Identifier:	0x0063
Property type:	PT_BOOLEAN
Property tag:	0x0063000B
Remarks

The PR_RESPONSE_REQUESTED property is used for meeting requests. The receiving client application should prompt the user to accept or decline the request and then send this response back to the sender.


PR_RESPONSIBILITY

The PR_RESPONSIBILITY property contains TRUE if some transport provider has already accepted responsibility for delivering the message to this recipient, and FALSE if the MAPI spooler considers that this transport provider should accept responsibility.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Recipient subobjects
Identifier:	0x0E0F
Property type:	PT_BOOLEAN
Property tag:	0x0E0F000B
Corresponding X.400 attribute:	MH_T_MTA_RESPONSIBILITY
Remarks

When the MAPI spooler presents an outbound message to a transport provider, through IXPLogon::SubmitMessage, it sets the PR_RESPONSIBILITY property to FALSE for all recipients for which the MAPI spooler considers that transport provider responsible, and TRUE for all other recipients. The transport provider should attempt to handle all recipients with PR_RESPONSIBILITY set to FALSE. After successfully sending, or conclusively failing to send, to a recipient, the transport provider should set PR_RESPONSIBILITY to TRUE in the source message to indicate that it has accepted responsibility for that recipient.

If, after examining a recipient, a transport provider decides that it cannot or should not handle it, the transport provider should leave PR_RESPONSIBILITY set to FALSE. The MAPI spooler will then look for another transport provider that can handle that recipient. The MAPI spooler ultimately creates a nondelivery report for any recipients for which no transport provider accepts responsibility.

If the transport provider attempts and fails to deliver the message, it should call the IMAPISupport::StatusRecips method to indicate to MAPI the reasons for the failure, so that MAPI can generate a nondelivery report.

See Also

PR_DELETE_AFTER_SUBMIT


PR_RETURNED_IPM

The PR_RETURNED_IPM property contains TRUE if the original message is being returned with a nonread report.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Report message objects
Identifier:	0x0033
Property type:	PT_BOOLEAN
Property tag:	0x0033000B
Remarks

An X.400 transport provider sets the PR_RETURNED_IPM property in the nonread report.


PR_ROW_TYPE

The PR_ROW_TYPE property contains a value that indicates the type of a row in a table.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Contents tables
Identifier:	0x0FF5
Property type:	PT_LONG
Property tag:	0x0FF50003
Remarks

The PR_ROW_TYPE property appears only on contents tables. A category only exists when it has items.

PR_ROW_TYPE can have exactly one of the following values:

TBL_LEAF_ROW

Represents actual data, rather than a category row.

TBL_EMPTY_CATEGORY

Not currently used.

TBL_EXPANDED_CATEGORY

The category is expanded; the user interface usually displays this with the minus sign ( − ) next to it.

TBL_COLLAPSED_CATEGORY

The category is collapsed; the user interface usually displays this with the plus sign (+) next to it.

See Also

PR_ROWID


PR_ROWID

The PR_ROWID property contains a unique identifier for a recipient in a recipient table or status table.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Recipient tables and status tables
Identifier:	0x3000
Property type:	PT_LONG
Property tag:	0x30000003
Remarks

The PR_ROWID property is a temporary value that is valid only for the life of the object that owns the table. It appears as a column of the table but is not stored.

See Also

IMessage::GetRecipientTable, IMessage::ModifyRecipients


PR_RTF_COMPRESSED

The PR_RTF_COMPRESSED property contains the Rich Text Format version of the message text, usually in compressed form.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x1009
Property type:	PT_BINARY
Property tag:	0x10090102
Remarks

The PR_RTF_COMPRESSED property contains the same message text as the PR_BODY property but in Rich Text Format (RTF).

Message text in RTF is normally stored in compressed form. However, some systems do not compress formatted text. To accommodate them, MAPI provides the dwMagicUncompressedRTF value for a stream header to identify uncompressed RTF, and the STORE_UNCOMPRESSED_RTF in PR_STORE_SUPPORT_MASK for the message store to indicate it can store uncompressed RTF.

To obtain the contents of PR_RTF_COMPRESSED, call OpenProperty, then call WrapCompressedRTFStream with the MAPI_READ flag. To write into PR_RTF_COMPRESSED, open it with the MAPI_MODIFY and MAPI_CREATE flags. This ensures that the new data completely replace any old data and that the writes are performed using the minimum number of store updates.

Message stores that support RTF ignore any changes to white space in the message text. When PR_BODY is stored for the first time, the message store also generates and stores PR_RTF_COMPRESSED. If the IMAPIProp::SaveChanges method is subsequently called and PR_BODY has been modified, the message store calls the RTFSync function to ensure synchronization with the RTF version. If only white space has been changed, the properties are left unchanged. This preserves any nontrivial RTF formatting when the message travels through non-RTF-aware clients and messaging systems.


PR_RTF_IN_SYNC

The PR_RTF_IN_SYNC property contains TRUE if PR_RTF_COMPRESSED has the same text content as PR_BODY for this message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0E1F
Property type:	PT_BOOLEAN
Property tag:	0x0E1F000B
Remarks

A value of TRUE means that the PR_BODY property, the plain text version of this message, and the PR_RTF_COMPRESSED property, the Rich Text Format version, are identical except for white space in PR_BODY and formatting in PR_RTF_COMPRESSED. The text in the two versions consists of the same characters in the same sequence.

A value of FALSE means that the two versions are not synchronized for text content but are capable of being synchronized by the RTFSync function. One version has been altered and the other version has not.

No value, PR_RTF_IN_SYNC is not set at all, means that the two versions, if both exist or ever existed, cannot be synchronized. One version has been deleted or altered so radically that synchronization is no longer possible.

A client application that has modified PR_RTF_COMPRESSED should set a value of FALSE in PR_RTF_IN_SYNC to force synchronization. RTF-aware message stores should perform the synchronization using RTFSync during an IMAPIProp::SaveChanges call. RTF-aware clients should check the setting of PR_RTF_IN_SYNC before reading PR_RTF_COMPRESSED, and call RTFSync first if necessary.

If PR_BODY has had modifications to anything other than its white space, the message store must delete PR_RTF_IN_SYNC to terminate synchronization.


PR_RTF_SYNC_BODY_COUNT

The PR_RTF_SYNC_BODY_COUNT property contains a count of the significant characters of the message text.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x1007
Property type:	PT_LONG
Property tag:	0x10070003
Remarks

The RTFSync function computes the count of characters in the text using only those that it considers to be significant to the message. For example, some white space and other ignorable characters are omitted from the count.

The PR_RTF_SYNC_BODY_COUNT property is an RTF auxiliary property. These properties are used by the RTFSync function and are not intended to be used directly by client applications.


PR_RTF_SYNC_BODY_CRC

The PR_RTF_SYNC_BODY_CRC property contains the cyclical redundancy check (CRC) computed for the message text.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x1006
Property type:	PT_LONG
Property tag:	0x10060003
Remarks

The RTFSync function computes the CRC using only the characters that it considers to be significant to the message. For example, some white space and other ignorable characters are omitted from the CRC.

The PR_RTF_SYNC_BODY_CRC property is a Rich Text Format auxiliary property. These properties are used by the RTFSync function and are not intended to be used directly by client applications.


PR_RTF_SYNC_BODY_TAG

The PR_RTF_SYNC_BODY_TAG property contains significant characters that appear at the beginning of the message text.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x1008
Property type:	PT_TSTRING
Property tag:	0x1008001E (0x1008001F for Unicode)
Remarks

The RTFSync function uses the text tag to indicate the beginning of the message text. When the text is modified, the tag is used to find the beginning of the previous text.

The PR_RTF_SYNC_BODY_TAG property is a Rich Text Format auxiliary property. These properties are used by the RTFSync function and are not intended to be used directly by client applications.


PR_RTF_SYNC_PREFIX_COUNT

The PR_RTF_SYNC_PREFIX_COUNT property contains a count of the ignorable characters that appear before the significant characters of the message.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x1010
Property type:	PT_LONG
Property tag:	0x10100003
Remarks

The count of prefix characters does not include white space.

The PR_RTF_SYNC_PREFIX_COUNT property is a Rich Text Format auxiliary property. These properties are used by the RTFSync function and are not intended to be used directly by client applications.


PR_RTF_SYNC_TRAILING_COUNT

The PR_RTF_SYNC_TRAILING_COUNT property contains a count of the ignorable characters that appear after the significant characters of the message.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x1011
Property type:	PT_LONG
Property tag:	0x10110003
Remarks

The PR_RTF_SYNC_TRAILING_COUNT property is a Rich Text Format auxiliary property. These properties are used by the RTFSync function and are not intended to be used directly by client applications.


PR_SEARCH

The PR_SEARCH property contains a container object that is used for advanced searches.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Address book container and message store objects
Identifier:	0x3607
Property type:	PT_OBJECT
Property tag:	0x3607000D
Remarks

A container that does not support advanced search capabilities, does not have to supply the PR_SEARCH property.

See Also

IMAPIContainer : IMAPIProp


PR_SEARCH_KEY

The PR_SEARCH_KEY property contains a binary-comparable key that identifies correlated objects for a search.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Address book container, distribution list, messaging user, and message objects
Identifier:	0x300B
Property type:	PT_BINARY
Property tag:	0x300B0102
Corresponding X.400 attribute:	IM_THIS_IPM
Remarks

The PR_SEARCH_KEY property provides a trace for related objects, such as message copies, and facilitates finding unwanted occurrences, such as duplicate recipients.

PR_SEARCH_KEY is one of the base address properties for all messaging users. For more information on the base address properties, see Base Address Properties.

MAPI uses specific rules for constructing search keys for message recipients. The search key is formed by concatenating the address type (in uppercase characters), the colon character ‘:’, the e-mail address in canonical form, and the terminating null character. Canonical form here means that case-sensitive addresses appear in the correct case, and addresses that are not case-sensitive are converted to uppercase. This is important in preserving correlations among messages.

For message objects, PR_SEARCH_KEY is available through the IMAPIProp::GetProps method immediately following message creation. For other objects, it is available following the first call to the IMAPIProp::SaveChanges method. Because PR_SEARCH_KEY is changeable, it is unreliable to obtain it through GetProps until a SaveChanges call has committed any values set or changed by the IMAPIProp::SetProps method.

For profiles, MAPI also furnishes a hard-coded profile section named MUID_PROFILE_INSTANCE, with PR_SEARCH_KEY as its single property. This key is guaranteed to be unique among all profiles ever created, and can be more reliable than the PR_PROFILE_NAME property, which can be, for example, deleted and recreated with the same name.

The following table summarizes important differences among the PR_ENTRYID, PR_RECORD_KEY, and PR_SEARCH_KEY properties.

Characteristic	PR_ENTRYID	PR_RECORD_KEY	PR_SEARCH_KEY
Required on  attachment objects	No	Yes	No
Required on  folder objects	Yes	Yes	No
Required on  message store objects	Yes	Yes	No
Required on  status objects	Yes	No	No
Creatable by client	No	No	Yes
Available before  SaveChanges	Maybe	Maybe	Messages — Yes Others — Maybe
Changed in a  copy operation	Yes	Yes	NO
Changeable by client  after a copy	No	No	Yes
Unique within ...	Entire world	Provider instance	Entire world
Binary comparable  (as with memcmp)	No -- use  IMAPISupport:: CompareEntryIDs	Yes	Yes
See Also

PR_RESPONSIBILITY, PR_STORE_RECORD_KEY


PR_SECURITY

The PR_SECURITY property contains a flag that indicates the security level of a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0034
Property type:	PT_LONG
Property tag:	0x00340003
Remarks

The underlying messaging system chooses whether to use the flag contained in the PR_SECURITY property. The PR_MESSAGE_CLASS property can determine whether the messaging system honors the security settings.

The following flags can be set:

SECURITY_SIGNED

The message has been digitally signed. The recipient can read the digital signature to see if it is expired or suspended, or if the contents have been altered since the digital signing.

SECURITY_ENCRYPTED

The message has been encrypted. The recipient must present a security password to read the message text.


PR_SELECTABLE

The PR_SELECTABLE property contains TRUE if the entry in the one-off table can be selected.

Quick Info

Header file:	MAPITAGS.H
May be a column in:	One-off tables
Identifier:	0x3609
Property type:	PT_BOOLEAN
Property tag:	0x3609000B
Remarks

The PR_SELECTABLE property is used primarily for visual formatting of a one-off table. X.400 or gateway templates can be grouped by creating an entry that indicates the heading for the group. Setting PR_SELECTABLE to FALSE for the heading ensures that the user can select only the actual templates in the group and not this heading entry.

This property applies only to a one-off table, not to an address book hierarchy table.

MAPI allows an address book provider to group items visually by two means. First, certain rows can function as headings by being unselectable. Second, the selectable items can be indented relative to their headings using the PR_DEPTH property. PR_SELECTABLE is used in such grouping to indicate whether or not this item can be selected from a list box to create a one-off address. For example, if a client has several templates for building FAX addresses, it can display them as follows:

FAX templates (depth 0, not selectable)
Local (depth 1, selectable)
Long-distance (depth 1, selectable)

See Also

IABLogon::GetOneOffTable, PR_FOLDER_TYPE


PR_SEND_RICH_INFO

The PR_SEND_RICH_INFO property contains TRUE if the recipient can receive all message content, including Rich Text Format and OLE objects.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Distribution list and messaging user objects
Identifier:	0x3A40
Property type:	PT_BOOLEAN
Property tag:	0x3A40000B
Remarks

It is recommended that distribution list and messaging user objects expose the PR_SEND_RICH_INFO property.

PR_SEND_RICH_INFO indicates whether the sender considers the recipient to be MAPI-enabled.

When this property is set to TRUE, the transport and gateway can transmit the full content of the message, including Rich Text Format and OLE objects. The transport provider and gateway should use TNEF to encapsulate any properties that are not native to all the messaging systems involved.

When this property is set to FALSE, the transport provider and gateway are free to discard message content that their native clients cannot use. For example, when the clients do not support Rich Text Format, the transport provider can send only plain text.

When PR_SEND_RICH_INFO is not set, default behavior is determined by the implementation of the transport provider, MTA, or gateway. Address book providers are not required to support this property. For example, a tightly coupled address book and transport provider can choose to send TNEF but never use Rich Text Format.

The client should not assume the transport provider and gateway will use TNEF on their own initiative. Some transport providers and gateways that support TNEF transmit it without regard to the value of PR_SEND_RICH_INFO, but others decline to construct or send TNEF if PR_SEND_RICH_INFO is not set to TRUE.

Note  The setting of this property, and the decisions based on its value, are on a per-recipient basis.

By default, MAPI sets the value of PR_SEND_RICH_INFO to TRUE. A client calling IAddrBook::CreateOneOff or a provider calling IMAPISupport::CreateOneOff can set the MAPI_SEND_NO_RICH_INFO bit in the ulFlags parameter, which causes MAPI to set PR_SEND_RICH_INFO to FALSE. One-offs created by the user interface use the value specified by the creating template.

On calls to the IAddrBook::ResolveName method when the name cannot be resolved but can be interpreted as an Internet address (SMTP), PR_SEND_RICH_INFO is set to FALSE. To be construed as an Internet address, the display name of the unresolved entry must be in the format X@Y.Z, such as “pete@pinecone.com”.

See Also

PR_ATTACH_DATA_OBJ


PR_SENDER_ADDRTYPE

The PR_SENDER_ADDRTYPE property contains the message sender’s e-mail address type.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0C1E
Property type:	PT_TSTRING
Property tag:	0x0C1E001E (0x0C1E001F for Unicode)
Remarks

The PR_SENDER_ADDRTYPE property is one of the address properties for the message sender. It must be set by the outgoing transport provider, which should never propagate any previously existing values.

If no transport provider has supplied any sender address properties, the MAPI spooler attempts to fill them in by calling the IMAPISession::QueryIdentity method for an entry identifier. If no entry identifiers have been provided, the MAPI spooler stores “Unknown” in all the sender address properties of type PT_TSTRING.

For more information on the address properties, see Base Address Properties.

See Also

PR_ADDRTYPE, PR_SENT_REPRESENTING_ADDRTYPE


PR_SENDER_EMAIL_ADDRESS

The PR_SENDER_EMAIL_ADDRESS property contains the message sender’s e-mail address.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0C1F
Property type:	PT_TSTRING
Property tag:	0x0C1F001E (0x0C1F001F for Unicode)
Remarks

The PR_SENDER_EMAIL_ADDRESS property is one of the address properties for the message sender. It must be set by the outgoing transport provider, which should never propagate any previously existing values.

If no transport provider has supplied any sender address properties, the MAPI spooler attempts to fill them in by calling the IMAPISession::QueryIdentity method for an entry identifier. If no entry identifiers have been provided, the MAPI spooler stores “Unknown” in all the sender address properties of type PT_TSTRING.

For more information on the address properties, see Base Address Properties.

See Also

PR_EMAIL_ADDRESS, PR_SENT_REPRESENTING_EMAIL_ADDRESS


PR_SENDER_ENTRYID

The PR_SENDER_ENTRYID property contains the message sender’s entry identifier.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0C19
Property type:	PT_BINARY
Property tag:	0x0C190102
Corresponding X.400 attribute:	IM_ORIGINATOR
Remarks

The PR_SENDER_ENTRYID property is one of the address properties for the message sender. It must be set by the outgoing transport provider, which should never propagate any previously existing values.

If no transport provider has supplied any sender address properties, the MAPI spooler attempts to fill them in by calling the IMAPISession::QueryIdentity method for an entry identifier. If no entry identifiers have been provided, the MAPI spooler stores in PR_SENDER_ENTRYID an identifier corresponding to the string “Unknown.”

For more information on the address properties, see Base Address Properties.

See Also

PR_ENTRYID, PR_SENT_REPRESENTING_ENTRYID


PR_SENDER_NAME

The PR_SENDER_NAME property contains the message sender’s display name.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0C1A
Property type:	PT_TSTRING
Property tag:	0x0C1A001E (0x0C1A001F for Unicode)
Corresponding X.400 attribute:	IM_FREE_FORM_NAME and MH_T_ORIGINATOR_NAME
Remarks

The PR_SENDER_NAME property is one of the address properties for the message sender. It must be set by the outgoing transport provider, which should never propagate any previously existing values.

If no transport provider has supplied any sender address properties, the MAPI spooler attempts to fill them in by calling the IMAPISession::QueryIdentity method for an entry identifier. If no entry identifiers have been provided, the MAPI spooler stores “Unknown” in all the sender address properties of type PT_TSTRING.

For more information on the address properties, see Base Address Properties.

See Also

PR_DISPLAY_NAME, PR_SENT_REPRESENTING_NAME


PR_SENDER_SEARCH_KEY

The PR_SENDER_SEARCH_KEY property contains the message sender’s search key.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0C1D
Property type:	PT_BINARY
Property tag:	0x0C1D0102
Remarks

The PR_SENDER_SEARCH_KEY property is one of the address properties for the message sender. It must be set by the outgoing transport provider, which should never propagate any previously existing values.

If no transport provider has supplied any sender address properties, the MAPI spooler attempts to fill them in by calling the IMAPISession::QueryIdentity method for an entry identifier. If no entry identifiers have been provided, the MAPI spooler stores in PR_SENDER_SEARCH_KEY a key corresponding to the string “Unknown.”

For more information on the address properties, see Base Address Properties.

See Also

PR_SEARCH_KEY, PR_SENT_REPRESENTING_SEARCH_KEY


PR_SENSITIVITY

The PR_SENSITIVITY property contains a value indicating the message sender’s opinion of the sensitivity of a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0036
Property type:	PT_LONG
Property tag:	0x00360003
Corresponding X.400 attribute:	IM_SENSITIVITY
Remarks

It is recommended that message objects expose the PR_SENSITIVITY property.

This property can have exactly one of the following values:

SENSITIVITY_NONE

The message has no special sensitivity.

SENSITIVITY_PERSONAL

The message is personal.

SENSITIVITY_PRIVATE

The message is private.

SENSITIVITY_COMPANY_CONFIDENTIAL

The message is designated Company Confidential.


PR_SENT_REPRESENTING_ADDRTYPE

The PR_SENT_REPRESENTING_ADDRTYPE property contains the address type for the messaging user represented by the sender.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0068
Property type:	PT_TSTRING
Property tag:	0x0068001E (0x0068001F for Unicode)
Remarks

The PR_SENT_REPRESENTING_ADDRTYPE property is one of the address properties for the messaging user being represented by the sender. When a client application sends a message on behalf of another client, it should set all the represented sender properties to the values for that client. A messaging user sending on its own behalf typically leaves the represented sender properties unset.

The outgoing transport provider must always leave PR_SENT_REPRESENTING_ADDRTYPE unchanged if it has been set by the sending client. If it is unset, the transport provider should set it to PR_SENDER_ADDRTYPE on the outbound copy of the message, and leave it unset on the local copy.

For more information on the address properties, see Base Address Properties.

See Also

PR_ADDRTYPE


PR_SENT_REPRESENTING_EMAIL_ADDRESS

The PR_SENT_REPRESENTING_EMAIL_ADDRESS property contains the e-mail address for the messaging user represented by the sender.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0069
Property type:	PT_TSTRING
Property tag:	0x0069001E (0x0069001F for Unicode)
Remarks

The PR_SENT_REPRESENTING_EMAIL_ADDRESS property is one of the address properties for the messaging user being represented by the sender. When a client application sends a message on behalf of another client, it should set all the represented sender properties to the values for that client. A messaging user sending on its own behalf typically leaves the represented sender properties unset.

The outgoing transport provider must always leave PR_SENT_REPRESENTING_EMAIL_ADDRESS unchanged if it has been set by the sending client. If it is unset, the transport provider should set it to PR_SENDER_EMAIL_ADDRESS on the outbound copy of the message, and leave it unset on the local copy.

For more information on the address properties, see Base Address Properties.

See Also

PR_EMAIL_ADDRESS


PR_SENT_REPRESENTING_ENTRYID

The PR_SENT_REPRESENTING_ENTRYID property contains the entry identifier for the messaging user represented by the sender.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0041
Property type:	PT_BINARY
Property tag:	0x00410102
Remarks

The PR_SENT_REPRESENTING_ENTRYID property is one of the address properties for the messaging user being represented by the sender. When a client application sends a message on behalf of another client, it should set all the represented sender properties to the values for that client. A messaging user sending on its own behalf typically leaves the represented sender properties unset.

The outgoing transport provider must always leave PR_SENT_REPRESENTING_ENTRYID unchanged if it has been set by the sending client. If it is unset, the transport provider should set it to PR_SENDER_ENTRYID on the outbound copy of the message, and leave it unset on the local copy.

For more information on the address properties, see Base Address Properties.

See Also

PR_ENTRYID


PR_SENT_REPRESENTING_NAME

The PR_SENT_REPRESENTING_NAME property contains the display name for the messaging user represented by the sender.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0042
Property type:	PT_TSTRING
Property tag:	0x0042001E (0x0042001F for Unicode)
Remarks

The PR_SENT_REPRESENTING_NAME property is one of the address properties for the messaging user being represented by the sender. When a client application sends a message on behalf of another client, it should set all the represented sender properties to the values for that client. A messaging user sending on its own behalf typically leaves the represented sender properties unset.

The outgoing transport provider must always leave PR_SENT_REPRESENTING_NAME unchanged if it has been set by the sending client. If it is unset, the transport provider should set it to PR_SENDER_NAME on the outbound copy of the message, and leave it unset on the local copy.

For more information on the address properties, see Base Address Properties.

See Also

PR_DISPLAY_NAME


PR_SENT_REPRESENTING_SEARCH_KEY

The PR_SENT_REPRESENTING_SEARCH_KEY property contains the search key for the messaging user represented by the sender.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x003B
Property type:	PT_BINARY
Property tag:	0x003B0102
Remarks

The PR_SENT_REPRESENTING_SEARCH_KEY property is one of the address properties for the messaging user being represented by the sender. When a client application sends a message on behalf of another client, it should set all the represented sender properties to the values for that client. A messaging user sending on its own behalf typically leaves the represented sender properties unset.

The outgoing transport provider must always leave PR_SENT_REPRESENTING_SEARCH_KEY unchanged if it has been set by the sending client. If it is unset, the transport provider should set it to PR_SENDER_SEARCH_KEY on the outbound copy of the message, and leave it unset on the local copy.

For more information on the address properties, see Base Address Properties.

See Also

PR_SEARCH_KEY


PR_SENTMAIL_ENTRYID

The PR_SENTMAIL_ENTRYID property contains the entry identifier of the folder where the message should be moved after submission.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0E0A
Property type:	PT_BINARY
Property tag:	0x0E0A0102
Remarks

The PR_SENTMAIL_ENTRYID property is often copied from the PR_IPM_SENTMAIL_ENTRYID property, the client application’s standard Sent Items folder.

The client application uses PR_SENTMAIL_ENTRYID with the PR_DELETE_AFTER_SUBMIT property to control what happens to a message after it is submitted. Either one or the other should be set, but not both.


PR_SERVICE_DELETE_FILES

The PR_SERVICE_DELETE_FILES property contains a list of filenames that are to be deleted when the message service is uninstalled.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Profile section objects
Identifier:	0x3D10
Property type:	PT_MV_TSTRING
Property tag:	0x3D10101E (0x3D10101F for Unicode)
Remarks

The filenames in the list contained in the PR_SERVICE_DELETE_FILES property are deleted from the computer when using the control panel to uninstall the message service. Do not include in the list any DLL that supports multiple message services, or additional message services could be inadvertently removed.

MAPI works only with filenames, and other strings passed to it, in the ANSI character set. Applications that use filenames in an OEM character set must convert them to ANSI before calling MAPI.


PR_SERVICE_DLL_NAME

The PR_SERVICE_DLL_NAME property contains the filename of the DLL containing the message service provider entry point function to call for configuration.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Profile section objects
Must be a column in:	Message service tables
Identifier:	0x3D0A
Property type:	PT_TSTRING
Property tag:	0x3D0A001E (0x3D0A001F for Unicode)
Remarks

When the entry point function name appears in the PR_SERVICE_ENTRY_NAME method, it indicates that the entry point exists.

MAPI uses a DLL file naming convention. The base filename contains up to six characters that uniquely identify the DLL. MAPI appends the string 32 to the base DLL name to identify the version that runs on 32-bit platforms. For example, when the name MAPI.DLL is specified, MAPI constructs the name MAPI32.DLL to represent the corresponding 32-bit version of the DLL.

The PR_SERVICE_DLL_NAME property should specify the base name. MAPI appends the string 32 as appropriate. Including the string 32 as part of the PR_SERVICE_DLL_NAME property results in an error.

See Also

PR_PROVIDER_DLL_NAME


PR_SERVICE_ENTRY_NAME

The PR_SERVICE_ENTRY_NAME property contains the name of the entry point function for configuration of a message service.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Profile section objects
Must be a column in:	Message service tables
Identifier:	0x3D0B
Property type:	PT_STRING8
Property tag:	0x3D0B001E
Remarks

It is recommended that message service implementers provide a message service entry point, but the entry point is not required. However, the entry point should be supplied only if the related configuration properties exist. If these properties do not exist, MAPI assumes that no entry point is provided.

The DLL in which the entry point function appears is named by the PR_SERVICE_DLL_NAME property.

For more information on message service entry points, see About Message Service Entry Point Functions.


PR_SERVICE_EXTRA_UIDS

The PR_SERVICE_EXTRA_UIDS property contains a list of MAPIUID structures that identify additional profile sections for the message service.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Profile section objects
Identifier:	0x3D0D
Property type:	PT_BINARY
Property tag:	0x3D0D0102
Remarks

New profile sections can be created for each message filter. When the information about the message service is to be copied to another profile, it is important to copy the additional profile sections for the filters as well. A service provider that uses additional profile sections can store the MAPIUID structures of those profile sections in PR_SERVICE_EXTRA_UIDS, allowing MAPI to copy the additional message service information.


PR_SERVICE_NAME

The PR_SERVICE_NAME property contains the name of a message service as set by the user in the MAPISVC.INF file.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Profile section objects
Must be a column in:	Message service tables
Identifier:	0x3D09
Property type:	PT_TSTRING
Property tag:	0x3D09001E (0x3D09001F for Unicode)
Remarks

The name contained in the PR_SERVICE_NAME property is specific to the message service. It comes from the [Services] section in MAPISVC.INF.

PR_SERVICE_NAME appears as a column in the message service table and can be used to filter services. Because it is used to identify and filter services, the value should not be localized.


PR_SERVICE_SUPPORT_FILES

The PR_SERVICE_SUPPORT_FILES property contains a list of the files that belong to the message service.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Profile section objects
Must be a column in:	Message service tables
Identifier:	0x3D0F
Property type:	PT_MV_TSTRING
Property tag:	0x3D0F101E (0x3D0F101F for Unicode)
Remarks

Using a dialog box in the control panel applet, a user can obtain the list of files that belong to the message service. For example, the user can obtain the names of all DLLs that belong to the service. The user can then seek additional details about the specified files, such as the names and version numbers of all the DLLs. MAPI uses the PR_SERVICE_SUPPORT_FILES property to create a support file list in a dialog box for messaging user selection.

MAPI works only with filenames, and other strings passed to it, in the ANSI character set. Client applications that use filenames in an OEM character set must convert them to ANSI before calling MAPI.


PR_SERVICE_UID

The PR_SERVICE_UID property contains the MAPIUID structure for a message service.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Profile section objects
Must be a column in:	Message service tables
Identifier:	0x3D0C
Property type:	PT_BINARY
Property tag:	0x3D0C0102
Remarks

The PR_SERVICE_UID property is computed by MAPI on profile section objects. MAPI uses this property to group all the providers that belong to the same message service. PR_SERVICE_UID is supplied as a parameter to most of the IMsgServiceAdmin methods. It must not appear in MAPISVC.INF.

See Also

IMsgServiceAdmin::IUnknown


PR_SERVICES

The PR_SERVICES property contains a list of identifiers of message services in the current profile.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3D0E
Property type:	PT_BINARY
Property tag:	0x3D0E0102
Remarks

Do not use this property. It is reserved for use by MAPI.

See Also

MAPIUID


PR_SPOOLER_STATUS

The PR_SPOOLER_STATUS property contains the status of the message based on information available to the MAPI spooler.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects
Identifier:	0x0E10
Property type:	PT_LONG
Property tag:	0x0E100003
Remarks

The PR_SPOOLER_STATUS property is computed by MAPI on message objects.

This property appears on inbound messages only and is reserved in all other cases. It indicates whether or not a message has been delivered to its final location or whether a messaging hook provider potentially deleted the message while rerouting it.

Client applications should never set this property. For an inbound message, a client or service provider can call the IMAPIProp::GetProps property on PR_SPOOLER_STATUS to determine the message status. The value S_OK indicates that the message was successfully delivered to the message store. The value MAPI_E_OBJECT_DELETED indicates that the message was deleted and was never committed to the store.

Message store providers should support PR_SPOOLER_STATUS on messages, recipient tables, and the outgoing queue table. Clients and providers should be able to set columns on the outgoing queue table and restrict based on this property.


PR_START_DATE

The PR_START_DATE property contains the starting date and time of an appointment as managed by a scheduling application.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message objects used for scheduling
Identifier:	0x0060
Property type:	PT_SYSTIME
Property tag:	0x00600040
Remarks

Scheduling applications should set both the PR_START_DATE and PR_END_DATE properties when sending meeting requests.


PR_STATE_OR_PROVINCE

The PR_STATE_OR_PROVINCE property contains the name of the recipient’s state or province.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A28
Property type:	PT_TSTRING
Property tag:	0x3A28001E (0x3A28001F for Unicode)
Remarks

The PR_STATE_OR_PROVINCE property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_STATUS

The PR_STATUS property contains a 32-bit bitmask of flags defining folder status.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Folder objects
Must be a column in:	Hierarchy tables
Identifier:	0x360B
Property type:	PT_LONG
Property tag:	0x360B0003
Remarks

The PR_STATUS property for folders is analogous to the PR_MSG_STATUS property for messages. Its flags are provided for the client application only and do not affect the message store. Clients can use or ignore these settings. The client can also define its own values for the client-definable bits of the PR_STATUS property.

One or more of the following flags can be set for the PR_STATUS bitmask:

FLDSTATUS_DELMARKED

The folder is marked for deletion. The client application sets this flag.

FLDSTATUS_HIDDEN

The folder is hidden.

FLDSTATUS_HIGHLIGHTED

The folder is highlighted, for example, shown in reverse video.

FLDSTATUS_TAGGED

The folder is tagged.

Message store providers set a folder’s PR_STATUS property to one or more of these values and clients interpret the status as appropriate for their applications. For example, a client can use the folder status to visually differentiate between folders in a hierarchy table, displaying folders with the same status in the same way. Highlighted folders can be shown in reverse videa, tagged folders and folders marked for deletion can be shown with a meaningful icon, and hidden folders can be concealed.

Bits 16 through 31 (0x10000 through 0x80000000) of PR_STATUS are available for use by the IPM client application. All other bits are reserved for use by MAPI; those not defined in the preceding list should be initially set to zero and not altered subsequently.


PR_STATUS_CODE

The PR_STATUS_CODE property contains a bitmask of flags indicating the current status of a session resource. All service providers set status codes as does MAPI to report on the status of the subsystem, the MAPI spooler, and the integrated address book.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Status objects
Must be a column in:	Status tables
Identifier:	0x3E04
Property type:	PT_LONG
Property tag:	0x3E040003
Remarks

The status code must appear in the MAPISVC.INF file for all providers.

Status objects are implemented by MAPI and by all service providers. There are two sets of valid values for status codes, one set for all status objects and another set for transport providers only. All status objects can set PR_STATUS_CODE to the following values:

STATUS_AVAILABLE

Indicates that the resource is operational.

STATUS_FAILURE

Indicates that the resource is experiencing a problem. For service providers, STATUS_FAILURE indicates that the provider might soon be shut down to end the current session.

STATUS_OFFLINE

Indicates that only local data or services are available.

Transport providers can also set their status objects’ PR_STATUS_CODE properties to the following values:

STATUS_INBOUND_ACTIVE

Indicates that the transport provider is receiving an inbound message.

STATUS_INBOUND_ENABLED

Indicates that the transport provider is able to receive inbound messages.

STATUS_INBOUND_FLUSH

Indicates that the transport provider is downloading messages from the inbound queue.

STATUS_OUTBOUND_ACTIVE

Indicates that the transport provider is receiving an outbound message.

STATUS_OUTBOUND_ENABLED

Indicates that the transport provider is able to handle outbound messages.

STATUS_OUTBOUND_FLUSH

Indicates that the transport provider is uploading messages from its outbound queue.

STATUS_REMOTE_ACCESS

Indicates that the transport provider supports remote access.

See Also

PR_STATUS_STRING


PR_STATUS_STRING

The PR_STATUS_STRING property contains an ASCII message indicating the current status of a session resource.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Status objects
Identifier:	0x3E08
Property type:	PT_TSTRING
Property tag:	0x3E08001E (0x3E08001F for Unicode)
Remarks

The PR_STATUS_STRING property gives service providers and MAPI the opportunity to supply specific information about the status of a session resource, such as the integrated address book or a particular service provider. The PR_STATUS_STRING property explains and provides additional information about a status code, or PR_STATUS_CODE property. Whereas PR_STATUS_CODE is required for all status objects, PR_STATUS_STRING is optional. When the transport provider does not supply a value, the MAPI spooler supplies a default value.

The string is generated on the same side of the remote procedure call as the MAPI spooler; it travels through shared memory rather than being marshaled across a process boundary.

See Also

PR_STATUS_CODE


PR_STORE_ENTRYID

The PR_STORE_ENTRYID property contains the unique entry identifier of the message store in which an object resides.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Folder, message, and message store objects
Identifier:	0x0FFB
Property type:	PT_BINARY
Property tag:	0x0FFB0102
Remarks

The PR_STORE_ENTRYID property is used to open a message store with the IMAPISession::OpenMsgStore method. It is also used to open any object owned by the message store.

For a message store, this property is identical to the store’s own PR_ENTRYID property. A client application can compare the two properties using the IMAPISession::CompareEntryIDs method.


PR_STORE_PROVIDERS

The PR_STORE_PROVIDERS property contains a list of identifiers of message store providers in the current profile.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3D00
Property type:	PT_BINARY
Property tag:	0x3D000102
Remarks

Do not use this property. It is reserved for use by MAPI.

See Also

MAPIUID


PR_STORE_RECORD_KEY

The PR_STORE_RECORD_KEY property contains the unique binary-comparable identifier (record key) of the message store in which an object resides.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Folder, message, and message store objects
Identifier:	0x0FFA
Property type:	PT_BINARY
Property tag:	0x0FFA0102
Remarks

For a message store, the PR_STORE_RECORD_KEY property is identical to the store’s own PR_RECORD_KEY property.

The relationship between PR_STORE_RECORD_KEY and PR_RECORD_KEY is the same as the relationship between PR_STORE_ENTRYID and PR_ENTRYID.


PR_STORE_STATE

The PR_STORE_STATE property contains a flag that describes the state of the message store.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message store objects
Identifier:	0x340E
Property type:	PT_LONG
Property tag:	0x340E0003
Remarks

The PR_STORE_STATE property is dynamic and can change based on user actions, unlike the PR_STORE_SUPPORT_MASK property.

The following value can be set:

STORE_HAS_SEARCHES

The user has created one or more active searches in the store.

See Also

PR_STORE_ENTRYID


PR_STORE_SUPPORT_MASK

The PR_STORE_SUPPORT_MASK property contains a bitmask of flags that client applications should query to determine the characteristics of a message store.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Folder, message, and message store objects
Identifier:	0x3A0D
Property type:	PT_LONG
Property tag:	0x3A0D0003
Remarks

The PR_STORE_SUPPORT_MASK property discloses the capabilities of a message store to client applications planning to send it a message. The flags can facilitate decisions by a client or another store, such as whether to send PR_BODY or only PR_RTF_COMPRESSED. A client should never set PR_STORE_SUPPORT_MASK; an attempt returns MAPI_E_COMPUTED.

One or more of the following flags can be set for the PR_STORE_SUPPORT_MASK bitmask:

STORE_ATTACH_OK

The message store supports attachments (OLE or non-OLE) to messages.

STORE_CATEGORIZE_OK

The message store supports categorized views of tables.

STORE_CREATE_OK

The message store supports creation of new messages.

STORE_ENTRYID_UNIQUE

Entry identifiers for the objects in the message store are unique, that is, never reused during the life of the store.

STORE_MODIFY_OK

The message store supports modification of its existing messages.

STORE_MV_PROPS_OK

The message store supports multivalued properties, guarantees the stability of value order in a multivalued property throughout a save operation, and supports instantiation of multivalued properties in tables.

STORE_NOTIFY_OK

The message store supports notifications.

STORE_OLE_OK

The message store supports OLE attachments. The OLE data is accessible through an IStorage interface, such as that available through the PR_ATTACH_DATA_OBJ property.

STORE_PUBLIC_FOLDERS

The folders in this store are public (multi-user), not private (possibly multi-instance but not multi-user).

STORE_READONLY

All interfaces for the message store have a read-only access level.

STORE_RESTRICTION_OK

The message store supports restrictions.

STORE_RTF_OK

The message store supports Rich Text Format (RTF) messages, usually stored compressed, and the store itself keeps PR_BODY and PR_RTF_COMPRESSED synchronized.

STORE_SEARCH_OK

The message store supports search-results folders.

STORE_SORT_OK

The message store supports sorting views of tables.

STORE_SUBMIT_OK

The message store supports marking a message for submission.

STORE_UNCOMPRESSED_RTF

The message store supports storage of Rich Text Format (RTF) messages in uncompressed form. An uncompressed RTF stream is identified by the value dwMagicUncompressedRTF in the stream header. The dwMagicUncompressedRTF value is defined in the RTFLIB.H file.

An RTF version of a message can always be stored, even if the message store is non-RTF-aware. If the STORE_RTF_OK bit is not set for a particular store, a client maintaining RTF versions must itself call the RTFSync function to keep the PR_BODY and PR_RTF_COMPRESSED versions synchronized for text content. RTF is always stored in PR_RTF_COMPRESSED, whether it is actually compressed or not.


PR_STREET_ADDRESS

The PR_STREET_ADDRESS property contains the recipient’s street address.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A29
Property type:	PT_TSTRING
Property tag:	0x3A29001E (0x3A29001F for Unicode)
Remarks

The PR_STREET_ADDRESS property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_SUBFOLDERS

The PR_SUBFOLDERS property contains TRUE if a folder contains subfolders.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	All folders
Identifier:	0x360A
Property type:	PT_BOOLEAN
Property tag:	0x360A000B
Remarks

Message stores must compute the PR_SUBFOLDERS property for all folders.

See Also

PR_FOLDER_TYPE


PR_SUBJECT

The PR_SUBJECT property contains the full subject of a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x0037
Property type:	PT_TSTRING
Property tag:	0x0037001E (0x0037001F for Unicode)
Corresponding X.400 attribute:	IM_SUBJECT
Remarks

The PR_SUBJECT property is recommended on all message objects.

This property is always the full subject text, that is, the concatenation of the prefix and the normalized subject. If there is no prefix, the normalized subject should be the same as the subject. A message store or transport provider uses both the PR_SUBJECT and PR_SUBJECT_PREFIX properties to compute the normalized subject using the rule described under PR_NORMALIZED_SUBJECT.

The subject properties are typically small strings of fewer than 256 characters, and a message store provider is not obligated to support the OLE IStream interface on them. The client should always attempt access through the IMAPIProp interface first, and resort to IStream only if MAPI_E_NOT_ENOUGH_MEMORY is returned.

For a report, PR_SUBJECT contains the original message’s subject preceded by a string indicating what has happened to the message.


PR_SUBJECT_IPM

The PR_SUBJECT_IPM property contains a binary value that is copied from the message for which a report is being generated.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Report message objects
Identifier:	0x0038
Property type:	PT_BINARY
Property tag:	0x00380102
Corresponding X.400 attribute:	IM_SUBJECT
Remarks

The PR_SUBJECT_IPM property, like the PR_REPORT_TAG property, can be used to correlate a report with the original message. The PR_PARENT_KEY property can also be used for correlation.


PR_SUBJECT_PREFIX

The PR_SUBJECT_PREFIX property contains a subject prefix that typically indicates some action on a message, such as “FW: “ for forwarding.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x003D
Property type:	PT_TSTRING
Property tag:	0x003D001E (0x003D001F for Unicode)
Remarks

The PR_SUBJECT_PREFIX property is recommended on all message objects.

The subject prefix consists of one or more alphanumeric characters, followed by a colon and a space (which are part of the prefix). It must not contain any nonalphanumeric characters before the colon. Absence of a prefix can be represented by an empty string or by PR_SUBJECT_PREFIX not being set.

If PR_SUBJECT_PREFIX is set explicitly, it can be of any length and use any alphanumeric characters, but it must match a substring at the beginning of the PR_SUBJECT property. If PR_SUBJECT_PREFIX is not set by the sender and must be computed, its contents are more restricted. The rule for computing the prefix is that PR_SUBJECT must begin with one, two, or three letters (alphabetic only) followed by a colon and a space. If such a substring is found at the beginning of PR_SUBJECT, it then becomes PR_SUBJECT_PREFIX (and also stays at the beginning of PR_SUBJECT). Otherwise PR_SUBJECT_PREFIX remains unset.

PR_SUBJECT_PREFIX and PR_NORMALIZED_SUBJECT should be computed as part of the IMAPIProp::SaveChanges implementation. A client should not prompt IMAPIProp::GetProps for their values until they have been committed by an IMAPIProp::SaveChanges call.

The subject properties are typically small strings of fewer than 256 characters, and a message store provider is not obligated to support the OLE IStream interface on them. A client should always attempt access through the IMAPIProp interface first, and resort to IStream only if MAPI_E_NOT_ENOUGH_MEMORY is returned.


PR_SUBMIT_FLAGS

The PR_SUBMIT_FLAGS property contains a bitmask of flags indicating details about a message submission.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Outgoing queue tables
Identifier:	0x0E14
Property type:	PT_LONG
Property tag:	0x0E140003
Remarks

One or more of the following flags can be set for the PR_SUBMIT_FLAGS bitmask:

SUBMITFLAG_LOCKED

The MAPI spooler currently has the message locked.

SUBMITFLAG_PREPROCESS

The message needs preprocessing. When the MAPI spooler is done preprocessing this message, it should call the IMessage::SubmitMessage method. The message store provider recognizes that the spooler, rather than the client application, has called SubmitMessage, clears the flag, and continues message submission.

See Also

IMsgStore::SetLockState


PR_SUPPLEMENTARY_INFO

The PR_SUPPLEMENTARY_INFO property contains additional information for use in a report.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects used for reports
Identifier:	0x0C1B
Property type:	PT_TSTRING
Property tag:	0x0C1B001E (0x0C1B001F for Unicode)
Corresponding X.400 attribute:	IM_SUPPLEMENTARY_INFO
Remarks

The PR_SUPPLEMENTARY_INFO property contains information generated by the message transfer agent or transport provider related to the report. It is typically used for delivery or nondelivery report text that originated with the underlying messaging system.


PR_SURNAME

The PR_SURNAME property contains the recipient’s family name.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A11
Property type:	PT_TSTRING
Property tag:	0x3A11001E (0x3A11001F for Unicode)
Remarks

The PR_SURNAME property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_TELEX_NUMBER

The PR_TELEX_NUMBER property contains the recipient’s telex number.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A2C
Property type:	PT_TSTRING
Property tag:	0x3A2C001E (0x3A2C001F for Unicode)
Remarks

The PR_TELEX_NUMBER property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.


PR_TEMPLATEID

The PR_TEMPLATEID property contains an entry identifier that can find the code associated with a service provider.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Address book provider objects
Identifier:	0x3902
Property type:	PT_BINARY
Property tag:	0x39020102
Remarks

The entry identifier can bind the code to the data.

See Also

IABLogon::OpenTemplateID, IMAPISupport::OpenTemplateID


PR_TITLE

The PR_TITLE property contains the recipient’s job title.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A17
Property type:	PT_TSTRING
Property tag:	0x3A17001E (0x3A17001F for Unicode)
Remarks

The PR_TITLE property is one of the properties that provide identification and access information for a recipient. These properties are defined by the recipient and the recipient’s organization. For more information on this group of properties, see IMailUser::IMAPIProp.

PR_TITLE is commonly used to indicate the recipient’s formal job title, such as Senior Programmer, rather than occupational class, such as programmer. It is not typically used for “suffix” titles such as Esq. or DDS.

Common PR_TITLE values include: Managing Director, Programmer II, Associate Professor, and Development Lead.


PR_TNEF_CORRELATION_KEY

The PR_TNEF_CORRELATION_KEY property contains a value used to correlate a TNEF attachment with a message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	TNEF attachment subobjects
Identifier:	0x007F
Property type:	PT_BINARY
Property tag:	0x007F0102
Remarks

It is recommended that TNEF attachment subobjects expose the PR_TNEF_CORRELATION_KEY property. This property determines whether or not an inbound TNEF file belongs to the message it is attached to. It is used primarily by transport providers and gateways.

On an outbound message, the transport provider should compute a binary value unique to that message, or use an existing value that satisfies the uniqueness requirement, such as a message identifier. The transport provider should store this value in PR_TNEF_CORRELATION_KEY and then call the ITnef::AddProps method to encapsulate it. The same value should also be stored in the transport envelope in a place defined by the provider, such as the message header.

On an inbound message, the transport provider should call the ITnef::ExtractProps method to decapsulate the TNEF attachment and then compare PR_TNEF_CORRELATION_KEY with the value stored in the transport envelope. If the values match, TNEF should be processed normally, that is, all the properties extracted from the TNEF attachment should be used. If the values do not match, all the properties from the TNEF attachment should be ignored. If PR_TNEF_CORRELATION_KEY is not set, the TNEF file should be considered to belong to this message, and the other properties extracted from it should be used.


PR_TRANSMITTABLE_DISPLAY_NAME

The PR_TRANSMITTABLE_DISPLAY_NAME property contains a recipient’s display name in a secure form that cannot be changed.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Messaging user objects
Identifier:	0x3a20
Property type:	PT_TSTRING
Property tag:	0x3A20001E (0x3A20001F for Unicode)
Remarks

The PR_TRANSMITTABLE_DISPLAY_NAME property should be furnished by all address book providers. It contains the version of the recipient’s display name that is transmitted with the message. For most address book providers this property has the same value as the PR_DISPLAY_NAME property. Providers that do not have a secure display name return PT_ERROR and MAPI changes the display name by adding quotation marks around the name.

A client application can use PR_TRANSMITTABLE_DISPLAY_NAME to prevent alteration or “spoofing” of entries. An example of spoofing is transmitting John Doe as John (What a Guy) Doe.

This property was formerly defined as PR_TRANSMITABLE_DISPLAY_NAME.


PR_TRANSPORT_KEY

The PR_TRANSPORT_KEY property contains a value used by the MAPI spooler to track the progress of an outbound message through the outgoing transport providers.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x0E16
Property type:	PT_LONG
Property tag:	0x0E160003
Remarks

Do not use this property. It is reserved for use by MAPI.

See Also

PR_TRANSPORT_PROVIDERS


PR_TRANSPORT_MESSAGE_HEADERS

The PR_TRANSPORT_MESSAGE_HEADERS property contains transport-specific message envelope information.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x007D
Property type:	PT_TSTRING
Property tag:	0x007D001E (0x007D001F for Unicode)
Remarks

The transport provider can generate the message header information for inbound messages.

The PR_TRANSPORT_MESSAGE_HEADERS property offers an alternative to either discarding the transport message header information or prepending it to the message text. The client can choose whether or not to display the information.

See Also

PR_BODY


PR_TRANSPORT_PROVIDERS

The PR_TRANSPORT_PROVIDERS property contains a list of identifiers of transport providers in the current profile.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3D02
Property type:	PT_BINARY
Property tag:	0x3D020102
Remarks

Do not use this property. It is reserved for use by MAPI.

See Also

MAPIUID


PR_TRANSPORT_STATUS

Obsolete MAPI spooler property.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x0E11
Property type:	PT_LONG
Property tag:	0x0E110003
Remarks

Do not use this property.


PR_TYPE_OF_MTS_USER

The PR_TYPE_OF_MTS_USER property contains the type of a message recipient, for use in a report.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Recipient subobjects within report message objects
Identifier:	0x0C1C
Property type:	PT_LONG
Property tag:	0x0C1C0003
Corresponding X.400 attribute:	MH_T_DELIVERY_POINT
See Also

PR_CORRELATE_MTSID


PR_USER_CERTIFICATE

The PR_USER_CERTIFICATE property contains an ASN.1 authentication certificate for a messaging user.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Messaging user objects
Identifier:	0x3A22
Property type:	PT_BINARY
Property tag:	0x3A220102
Remarks

An authentication certificate is similar to a digital signature. Several MAPI properties supply ASN.1 certificates.


PR_VALID_FOLDER_MASK

The PR_VALID_FOLDER_MASK property contains a bitmask of flags that indicate the validity of the entry identifiers of the folders in a message store.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message store objects
Identifier:	0x35DF
Property type:	PT_LONG
Property tag:	0x35DF0003
Remarks

A folder’s entry identifier can become invalid if a user deletes the folder or if the message store becomes corrupted.

One or more of the following flags can be set for the PR_VALID_FOLDER_MASK bitmask:

FOLDER_COMMON_VIEWS_VALID

The common views folder has a valid entry identifier. See PR_COMMON_VIEWS_ENTRYID.

FOLDER_FINDER_VALID

The finder folder has a valid entry identifier. See PR_FINDER_ENTRYID.

FOLDER_IPM_INBOX_VALID

The interpersonal message (IPM) receive folder has a valid entry identifier. See IMsgStore::GetReceiveFolder.

FOLDER_IPM_OUTBOX_VALID

The IPM Outbox folder has a valid entry identifier. See PR_IPM_OUTBOX_ENTRYID.

FOLDER_IPM_SENTMAIL_VALID

The IPM Sent Items folder has a valid entry identifier. See PR_IPM_SENTMAIL_ENTRYID.

FOLDER_IPM_SUBTREE_VALID

The IPM folder subtree has a valid entry identifier. See PR_IPM_SUBTREE_ENTRYID.

FOLDER_IPM_WASTEBASKET_VALID

The IPM Deleted Items folder has a valid entry identifier. See PR_IPM_WASTEBASKET_ENTRYID.

FOLDER_VIEWS_VALID

The views folder has a valid entry identifier. See PR_VIEWS_ENTRYID.

For more information on folder entry identifiers, see Opening a Folder.

See Also

PR_FOLDER_TYPE


PR_VIEWS_ENTRYID

The PR_VIEWS_ENTRYID property contains the entry identifier of the user-defined Views folder.

Quick Info

Header file:	MAPITAGS.H
Must be exposed by:	Message store objects
Identifier:	0x35E5
Property type:	PT_BINARY
Property tag:	0x35E50102
Remarks

The common view folder contains a predefined set of standard view specifiers, while the view folder contains specifiers defined by a messaging user. These folders, which are not visible in the interpersonal message (IPM) hierarchy, can hold many view specifiers, each one stored as a message. The client application can choose to merge the two sets of specifiers and make them both available.

For more information on views, see View Folders.

See Also

PR_COMMON_VIEWS_ENTRYID, PR_DEFAULT_VIEW_ENTRYID


PR_WIZARD_NO_PAB_PAGE

The PR_WIZARD_NO_PAB_PAGE property contains TRUE if the Profile Wizard is to suppress the PAB page.

Quick Info

Header file:	MAPIWZ.H
May be exposed by:	Provider objects
Identifier:	0x6701
Property type:	PT_BOOLEAN
Property tag:	0x6701000B
Remarks

Service providers can set this property when calling a function based on the LAUNCHWIZARDENTRY function prototype. PR_WIZARD_NO_PAB_PAGE tells the Profile Wizard that the provider does not want the personal address book (PAB) page to be displayed during the user dialog.


PR_WIZARD_NO_PST_PAGE

The PR_WIZARD_NO_PST_PAGE property contains TRUE if the Profile Wizard is to suppress the PST page.

Quick Info

Header file:	MAPIWZ.H
May be exposed by:	Provider objects
Identifier:	0x6700
Property type:	PT_BOOLEAN
Property tag:	0x6700000B
Remarks

Service providers can set this property when calling a function based on the LAUNCHWIZARDENTRY function prototype. PR_WIZARD_NO_PST_PAGE tells the Profile Wizard that the provider does not want the personal message store (PST) page to be displayed during the user dialog.


PR_X400_CONTENT_TYPE

The PR_X400_CONTENT_TYPE property contains the content type for a submitted message.

Quick Info

Header file:	MAPITAGS.H
May be exposed by:	Message objects
Identifier:	0x003C
Property type:	PT_BINARY
Property tag:	0x003C0102
Corresponding X.400 attribute:	MH_T_CONTENT_TYPE
See Also

PR_X400_DEFERRED_DELIVERY_CANCEL


PR_X400_DEFERRED_DELIVERY_CANCEL

The PR_X400_DEFERRED_DELIVERY_CANCEL property was originally meant to contain TRUE if the message transfer system (MTS) allows X.400 deferred delivery cancellation.

Quick Info

Header file:	MAPITAGS.H
Identifier:	0x3E09
Property type:	PT_BOOLEAN
Property tag:	0x3E09000B
Remarks

Do not use this property. It is not supported in MAPI 1.0.

See Also

PR_X400_CONTENT_TYPE


PR_XPOS

The PR_XPOS property contains the x coordinate of the starting position (the upper-left corner) of a dialog box control, in standard Windows dialog units.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Display tables
Identifier:	0x3F05
Property type:	PT_LONG
Property tag:	0x3F050003
Remarks

The PR_XPOS, PR_YPOS, PR_DELTAX, and PR_DELTAY properties position and size the dialog box control.


PR_YPOS

The PR_YPOS property contains the y coordinate of the starting position (the upper-left corner) of a dialog box control, in standard Windows dialog units.

Quick Info

Header file:	MAPITAGS.H
Must be a column in:	Display tables
Identifier:	0x3F06
Property type:	PT_LONG
Property tag:	0x3F060003
Remarks

The PR_XPOS, PR_YPOS, PR_DELTAX, and PR_DELTAY properties position and size the control.


Simple MAPI

Simple MAPI is a set of functions and related data structures you can use to add messaging functionality to C, C++, or Visual Basic Windows applications. The Simple MAPI functions are available in C and C++ and Visual Basic versions.

The following table provides an overview of the Simple MAPI functions.

Simple MAPI function	Description
MAPIAddress	Addresses a message.
MAPIDeleteMail	Deletes a message.
MAPIDetails	Displays a recipient-details dialog box.
MAPIFindNext	Returns the identifier of the first or next message of a specified type.
MAPIFreeBuffer	Frees memory allocated by the messaging system.
MAPILogoff	Ends a session with the messaging system.
MAPILogon	Establishes a messaging session.
MAPIReadMail	Reads a message.
MAPIResolveName	Displays a dialog box to resolve an ambiguous recipient name.
MAPISaveMail	Saves a message.
MAPISendDocuments	Sends a standard message using a dialog box.
MAPISendMail	Sends a message, allowing greater flexibility than MAPISendDocuments in message generation.
To use the Simple MAPI functions, compile your source code with MAPI.H. MAPI.H contains definitions for all of the functions, return value constants, and data types. To call a Simple MAPI function, load MAPI.DLL and use the Win32 GetProcAddress function to acquire an entry point. The function calling conventions should be FAR PASCAL.

All strings passed to all MAPI calls and returned by all MAPI calls are null-terminated and must be specified in the current character set or code page of the caller’s operating system process.


Functions for C and C++

The following alphabetical entries contain documentation for the Simple MAPI functions for C and C++.


MAPIAddress

The MAPIAddress function creates or modifies a set of address list entries.

Quick Info

Header file:	MAPI.H
ULONG FAR PASCAL MAPIAddress(

LHANDLE lhSession,
ULONG ulUIParam,
LPTSTR lpszCaption,
ULONG nEditFields,
LPTSTR lpszLabels,
ULONG nRecips,
lpMapiRecipDesc lpRecips,
FLAGS flFlags,
ULONG ulReserved,
LPULONG lpnNewRecips,
lpMapiRecipDesc FAR * lppNewRecips
)
Parameters

lhSession

[in] Session handle that represents a Simple MAPI session or zero. If the value of the lhSession parameter is zero, MAPI logs on the user and creates a session that exists only for the duration of the call. This temporary session can be an existing shared session or a new one. If necessary, a logon dialog box is displayed.

ulUIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG). If no dialog box is displayed during the call, ulUIParam is ignored.

lpszCaption

[in] Pointer to the caption for the address list dialog box, NULL, or an empty string. When the lpszCaption parameter is NULL or points to an empty string, MAPIAddress uses the default caption “Address Book.”

nEditFields

[in] The number of edit controls that should be present in the address list. The values 0 through 4 are valid. If the value of the nEditFields parameter is 4, each recipient class supported by the underlying messaging system has an edit control. If the value of nEditFields is zero, only address list browsing is possible. Values of 1, 2, or 3 control the number of edit controls present.

However, if the number of recipient classes in the array pointed to by the lpRecips parameter is greater than the value of nEditFields, the number of classes in lpRecips is used to indicate the number of edit controls instead of the value of nEditFields. If the value of nEditFields is 1 and more than one kind of entry exists in lpRecips, then the lpszLabels parameter is ignored.

Entries selected for the different controls are differentiated by the ulRecipClass member in the returned recipient structure.

lpszLabels

[in] Pointer to a string to be used as an edit control label in the address-list dialog box. When the nEditFields parameter is set to any value other than 1, the lpszLabels parameter is ignored and should be NULL or point to an empty string. Also, if the caller requires the default control label “To,” lpszLabels should be NULL or point to an empty string.

nRecips

[in] The number of entries in the array indicated by the lpRecips parameter. If the value of the nRecips parameter is zero, lpRecips is ignored.

lpRecips

[in] Pointer to an array of MapiRecipDesc structures defining the initial recipient entries to be used to populate the address-list dialog box. The entries do not need to be grouped by recipient class; they are differentiated by the values of the ulRecipClass members of the MapiRecipDesc structures in the array. If the number of different recipient classes is greater than the value indicated by the nEditFields parameter, the nEditFields and lpszLabels parameters are ignored.

flFlags

[in] Bitmask of option flags. The following flags can be set:

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user to log on if required. When the MAPI_LOGON_UI flag is not set, the client application does not display a logon dialog box and returns an error value if the user is not logged on.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment’s shared session. If the MAPI_NEW_SESSION flag is not set, MAPIAddress uses an existing shared session.

ulReserved

Reserved; must be zero.

lpnNewRecips

[out] Pointer to the number of entries in the lppNewRecips recipient output array. If the value of the lpnNewRecips parameter is zero, the lppNewRecips parameter is ignored.

lppNewRecips

[out] Pointer to an array of MapiRecipDesc structures containing the final list of recipients. This array is allocated by MAPIAddress, cannot be NULL, and must be freed using MAPIFreeBuffer, even if there are no new recipients. Recipients are grouped by recipient class in the following order: MAPI_TO, MAPI_CC, MAPI_BCC.

Return Values

MAPI_E_FAILURE

One or more unspecified errors occurred while addressing the message. No list of recipient entries was returned.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. No list of recipient entries was returned.

MAPI_E_INVALID_EDITFIELDS

The value of the nEditFields parameter was outside the range of 0 through 4. No list of recipient entries was returned.

MAPI_E_INVALID_RECIPS

One or more of the recipients in the address list was not valid. No list of recipient entries was returned.

MAPI_E_INVALID_SESSION

An invalid session handle was used for the lhSession parameter. No list of recipient entries was returned.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No list of recipient entries was returned.

MAPI_E_NOT_SUPPORTED

The operation was not supported by the underlying messaging system.

MAPI_E_USER_ABORT

The user canceled one of the dialog boxes. No list of recipient entries was returned.

SUCCESS_SUCCESS

The call succeeded and a list of recipient entries was returned.

Remarks

The MAPIAddress function displays a standard address-list dialog box to show an initial set of zero or more recipients. The user can choose new entries to add to the set or make changes to existing entries. This dialog box cannot be suppressed, but the caller can set dialog box characteristics. The changed set of recipients is returned to the caller.

Before MAPIAddress writes new or changed recipient information, it must allocate memory for the structure array that will contain the information. Memory is also allocated as part of preloading the address book, regardless of whether new or changed recipient data is written. Client applications must call the MAPIFreeBuffer function to free this memory after MAPIAddress returns. If any error occurs, no memory was allocated and clients do not need to call MAPIFreeBuffer.

See Also

MAPIFreeBuffer, MAPILogon, MapiRecipDesc


MAPIDeleteMail

The MAPIDeleteMail function deletes a message.

Quick Info

Header file:	MAPI.H
ULONG FAR PASCAL MAPIDeleteMail(

LHANDLE lhSession,
ULONG ulUIParam,
LPTSTR lpszMessageID,
FLAGS flFlags,
ULONG ulReserved
)
Parameters

lhSession

[in] Session handle that represents a valid Simple MAPI session. The value of the lhSession parameter must represent a valid session; it cannot be zero.

ulUIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG). If no dialog box is displayed during the call, ulUIParam is ignored.

lpszMessageID

[in] The identifier for the message to be deleted. This identifier is messaging system-specific and will be invalid when MAPIDeleteMail successfully returns.

flFlags

Reserved; must be zero.

ulReserved

Reserved; must be zero.

Return Values

MAPI_E_FAILURE

One or more unspecified errors occurred while deleting the message. No message was deleted.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. No message was deleted.

MAPI_E_INVALID_MESSAGE

An invalid message identifier was passed in the lpszMessageID parameter. No message was deleted.

MAPI_E_INVALID_SESSION

An invalid session handle was passed in the lhSession parameter. No message was deleted.

SUCCESS_SUCCESS

The call succeeded and the message was deleted.

Remarks

To find the message to be deleted, call the MAPIFindNext function before calling the MAPIDeleteMail function. Because message identifiers are opaque, messaging system-specific, and can be invalidated at any time, MAPIDeleteMail considers a message identifier to be valid only for the current session. MAPIDeleteMail handles invalid message identifiers by returning the MAPI_E_INVALID_MESSAGE value.

See Also

MAPIFindNext, MAPILogon, MAPISaveMail


MAPIDetails

The MAPIDetails function displays a dialog box containing the details of a selected address list entry.

Quick Info

Header file:	MAPI.H
ULONG FAR PASCAL MAPIDetails(

LHANDLE lhSession,
ULONG ulUIParam,
lpMapiRecipDesc lpRecip,
FLAGS flFlags,
ULONG ulReserved
)
Parameters

lhSession

[in] Session handle that represents a Simple MAPI session or zero. If the value of the lhSession parameter is zero, MAPI logs on the user and creates a session that exists only for the duration of the call. This temporary session can be an existing shared session or a new one. If additional information is required from the user to successfully complete the logon, a dialog box is displayed.

ulUIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG). If no dialog box is displayed during the call, ulUIParam is ignored.

lpRecip

[in] Pointer to the recipient for which details are to be displayed. MAPIDetails ignores all members of this MapiRecipDesc structure except the ulEIDSize and lpEntryID members. If the value of ulEIDSize is non-zero, MAPIDetails resolves the recipient entry. If the value of ulEIDSize is zero, MAPIDetails returns the MAPI_E_AMBIGUOUS_RECIP value.

flFlags

[in] Bitmask of option flags. The following flags can be set:

MAPI_AB_NOMODIFY

The caller is requesting that the dialog box be read-only, prohibiting changes. MAPIDetails might or might not honor the request.

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user to log on if required. When the MAPI_LOGON_UI flag is not set, the client application does not display a logon dialog box and returns an error value if the user is not logged on.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment’s shared session. If the MAPI_NEW_SESSION flag is not set, MAPIDetails uses an existing shared session.

ulReserved

Reserved; must be zero.

ReturnValues

MAPI_E_AMBIGUOUS_RECIPIENT

The dialog box could not be displayed because the ulEIDSize member of the structure pointed to by the lpRecips parameter was zero.

MAPI_E_FAILURE

One or more unspecified errors occurred. No dialog box was displayed.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. No dialog box was displayed.

MAPI_E_INVALID_RECIPS

The recipient specified in the lpRecip parameter was unknown or the recipient had an invalid ulEIDSize value. No dialog box was displayed.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No dialog box was displayed.

MAPI_E_NOT_SUPPORTED

The operation was not supported by the underlying messaging system.

MAPI_E_USER_ABORT

The user canceled either the logon dialog box or the details dialog box.

SUCCESS_SUCCESS

The call succeeded and the details dialog box was displayed.

Remarks

The MAPIDetails function presents a dialog box that shows the details of a particular address list entry. The display name and address are the minimum attributes that are displayed in the dialog box; more information can be shown, depending on the address book provider. The details dialog box cannot be suppressed, but the caller can request that it be read-only or modifiable.

Details can only be shown for resolved address list entries. An entry is resolved if the value of the ulEIDSize member of the MapiRecipDesc structure is nonzero. Entries are resolved when they are returned by the MAPIAddress or MAPIResolveName functions and as the result being recipients of read mail.

See Also

MAPIAddress, MAPILogon, MapiRecipDesc, MAPIResolveName


MAPIFindNext

The MAPIFindNext function retrieves the next (or first) message identifier of a specified type of incoming message.

Quick Info

Header file:	MAPI.H
ULONG FAR PASCAL MAPIFindNext(

LHANDLE lhSession,
ULONG ulUIParam,
LPTSTR lpszMessageType,
LPTSTR lpszSeedMessageID,
FLAGS flFlags,
ULONG ulReserved,
LPTSTR lpszMessageID
)
Parameters

lhSession

[in] Session handle that represents a Simple MAPI session. The value of the lhSession parameter must represent a valid session; it cannot be zero.

ulUIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG). If no dialog box is displayed during the call, ulUIParam is ignored.

lpszMessageType

[in] Pointer to a string identifying the message class to search. To find an interpersonal message (IPM), specify NULL in the lpszMessageType parameter or have it point to an empty string. Messaging systems whose only supported message class is IPM can ignore this parameter.

lpszSeedMessageID

[in] Pointer to a string containing the message identifier seed for the request. If the lpszSeedMessageID parameter is NULL or points to an empty string, MAPIFindNext retrieves the first message that matches the type specified in the lpszMessageType parameter.

flFlags

[in] Bitmask of option flags. The following flags can be set:

MAPI_GUARANTEE_FIFO

The message identifiers returned should be in the order of time received. MAPIFindNext calls can take longer if this flag is set. Some implementations cannot honor this request and return the MAPI_E_NO_SUPPORT value.

MAPI_LONG_MSGID

The returned message identifier can be as long as 512 characters. If this flag is set, the lpszMessageID parameter must be large enough to accomodate 512 characters.

Older versions of MAPI supported smaller message identifiers (64 bytes) and did not include this flag. MAPIFindNext will succeed without this flag set as long as lpszMessageID is large enough to hold the message identifier. If lpszMessageID cannot hold the message identifier, MAPIFindNext will fail.

MAPI_UNREAD_ONLY

Only unread messages of the specified type should be enumerated. If this flag is not set, MAPIFindNext can return any message of the specified type.

ulReserved

Reserved; must be zero.

lpszMessageID

[out] Pointer to the returned message identifier. The caller is responsible for allocating the memory. To ensure compatibility, allocate 512 characters and set MAPI_LONG_MSGID in the flFlags parameter. A smaller buffer is sufficient only if the returned message identifier is always 64 characters or less.

Return Values

MAPI_E_FAILURE

One or more unspecified errors occurred while matching the message type. The call failed before message type matching could take place.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. No message was found.

MAPI_E_INVALID_MESSAGE

An invalid message identifier was passed in the lpszSeedMessageID parameter. No message was found.

MAPI_E_INVALID_SESSION

An invalid session handle was passed in the lhSession parameter. No message was found.

MAPI_E_NO_MESSAGES

A matching message could not be found.

SUCCESS_SUCCESS

The call succeeded and the message identifier was returned.

Remarks

The MAPIFindNext function allows a client application to enumerate messages of a given type. This function can be called repeatedly to list all messages in the folder. Message identifiers returned from MAPIFindNext can be used in other Simple MAPI calls to retrieve message contents and delete messages. This function is for processing incoming messages, not for managing received messages.

MAPIFindNext looks for messages in the folder in which new messages of the specified type are delivered. MAPIFindNext calls can be made only in the context of a valid Simple MAPI session established with the MAPILogon function.

When the lpszSeedMessageID parameter is NULL or points to an empty string, MAPIFindNext returns the message identifier for the first message of the type specified by the lpszMessageType parameter. When lpszSeedMessageID contains a valid identifier, the function returns the next matching message of the type specified by lpszMessageType. Repeated calls to MAPIFindNext ultimately result in a return of the MAPI_E_NO_MESSAGES value, which means the enumeration is complete.

Message type matching is done against message class strings. All message types whose names match (up to the length specified in lpszMessageType) are returned.

Because message identifiers are messaging system-specific and can be invalidated at any time, message identifiers are valid only for the current session. If the message identifier passed in lpszSeedMessageID is invalid, MAPIFindNext returns the MAPI_E_INVALID_MESSAGE value.

See Also

MAPILogon


MAPIFreeBuffer (Simple MAPI)

The MAPIFreeBuffer function frees memory allocated by the messaging system.

Quick Info

Header file:	MAPI.H
ULONG FAR PASCAL MAPIFreeBuffer(

LPVOID pv
)
Parameters

pv

[in] Pointer to memory allocated by the messaging system. This pointer is returned by the MAPIReadMail, MAPIAddress, and MAPIResolveName functions.

Return Values

MAPI_E_FAILURE

One or more unspecified errors occurred. The memory could not be freed.

SUCCESS_SUCCESS

The call succeeded and the memory was freed.

See Also

MAPILogoff


MAPILogoff

The MAPILogoff function ends a session with the messaging system.

Quick Info

Header file:	MAPI.H
ULONG FAR PASCAL MAPILogoff (

LHANDLE lhSession,
ULONG ulUIParam,
FLAGS flFlags,
ULONG ulReserved
)
Parameters

lhSession

[in] Handle for the Simple MAPI session to be terminated. Session handles are returned by the MAPILogon function and invalidated by MAPILogoff. The value of the lhSession parameter must represent a valid session; it cannot be zero.

ulUIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG). If no dialog box is displayed during the call, ulUIParam  is ignored.

flFlags

Reserved; must be zero.

ulReserved

Reserved; must be zero.

Return Values

MAPI_E_FAILURE

The flFlags parameter is invalid or one or more unspecified errors occurred.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. The session was not terminated.

MAPI_E_INVALID_SESSION

An invalid session handle was used for the lhSession parameter. The session was not terminated.

SUCCESS_SUCCESS

The call succeeded and the session was terminated.

See Also

MAPILogon


MAPILogon

The MAPILogon function begins a Simple MAPI session, loading the default message store and address book providers.

Quick Info

Header file:	MAPI.H
ULONG FAR PASCAL MAPILogon(

ULONG ulUIParam,
LPTSTR lpszProfileName,
LPTSTR lpszPassword,
FLAGS flFlags,
ULONG ulReserved,
LPLHANDLE lplhSession
)
Parameters

ulUIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG). If no dialog box is displayed during the call, ulUIParam is ignored.

lpszProfileName

[in] Pointer to a null-terminated profile name string, limited to 256 characters or less. This is the profile to use when logging on. If the lpszProfileName parameter is NULL or points to an empty string, and the flFlags parameter is set to MAPI_LOGON_UI, MAPILogon displays a logon dialog box with an empty name field.

lpszPassword

[in] Pointer to a null-terminated credential string, limited to 256 characters or less. If the messaging system does not require password credentials, or if it requires that the user enter them, the lpszPassword parameter should be NULL or point to an empty string. When the user must enter credentials, the flFlags parameter must be set to MAPI_LOGON_UI to allow a logon dialog box to be displayed.

flFlags

[in] Bitmask of option flags. The following flags can be set:

MAPI_FORCE_DOWNLOAD

An attempt should be made to download all of the user’s messages before returning. If the MAPI_FORCE_DOWNLOAD flag is not set, messages can be downloaded in the background after the function call returns.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment’s shared session. If the MAPI_NEW_SESSION flag is not set, MAPILogon uses an existing shared session.

MAPI_LOGON_UI

A logon dialog box should be displayed to prompt the user for logon information. If the user needs to provide a password and profile name to enable a successful logon, MAPI_LOGON_UI must be set.

MAPI_PASSWORD_UI

MAPILogon should only prompt for a password and not allow the user to change the profile name. Either MAPI_PASSWORD_UI or MAPI_LOGON_UI should not be set, since the intent is to select between two different dialog boxes for logon.

ulReserved

Reserved; must be zero.

lplhSession

[out] Simple MAPI session handle.

Return Values

MAPI_E_FAILURE

One or more unspecified errors occurred during logon. No session handle was returned.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. No session handle was returned.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No session handle was returned.

MAPI_E_TOO_MANY_SESSIONS

The user had too many sessions open simultaneously. No session handle was returned.

MAPI_E_USER_ABORT

The user canceled the logon dialog box. No session handle was returned.

SUCCESS_SUCCESS

The call succeeded and a Simple MAPI session was established.

Remarks

The MAPILogon function begins a session with the messaging system, returning a handle that can be used in subsequent MAPI calls to explicitly provide user credentials to the messaging system. To request the display of a logon dialog box if the credentials presented fail to validate the session, set the flFlags parameter to MAPI_LOGON_UI.

The client application tests for an existing session by calling MAPILogon with a NULL value for the lpszProfileName parameter, a NULL value for the lpszPassword parameter and by not setting the MAPI_LOGON_UI flag in flFlags. If there is an existing session, the call succeeds and returns a valid LHANDLE for the session. Otherwise, the call fails.

See Also

MAPILogoff


MAPIReadMail

The MAPIReadMail function retrieves a message for reading.

Quick Info

Header file:	MAPI.H
ULONG FAR PASCAL MAPIReadMail(

LHANDLE lhSession,
ULONG ulUIParam,
LPTSTR lpszMessageID,
FLAGS flFlags,
ULONG ulReserved,
lpMapiMessage FAR * lppMessage
)
Parameters

lhSession

[in] Handle to a Simple MAPI session. The value of the lhSession parameter must represent a valid session; it cannot be zero.

ulUIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG). If no dialog box is displayed during the call, ulUIParam is ignored.

lpszMessageID

[in] Pointer to a message identifier string for the message to be read. The string is allocated by the caller.

flFlags

[in] Bitmask of option flags. The following flags can be set:

MAPI_BODY_AS_FILE

MAPIReadMail should write the message text to a temporary file and add it as the first attachment in the attachment list.

MAPI_ENVELOPE_ONLY

MAPIReadMail should read the message header only. File attachments are not copied to temporary files, and neither temporary file names nor message text is written. Setting this flag enhances performance.

MAPI_PEEK

MAPIReadMail does not mark the message as read. Marking a message as read affects its appearance in the user interface and generates a read receipt. If the messaging system does not support this flag, MAPIReadMail always marks the message as read. If MAPIReadMail encounters an error, it leaves the message unread.

MAPI_SUPPRESS_ATTACH

MAPIReadMail should not copy file attachments but should write message text into the MapiMessage structure. MAPIReadMail ignores this flag if the calling application has set the MAPI_ENVELOPE_ONLY flag. Setting the MAPI_SUPPRESS_ATTACH flag enhances performance.

ulReserved

Reserved; must be zero.

lppMessage

[out] Pointer to the location where the message is written. Messages are written to a MapiMessage structure which can be freed with a single call to the MAPIFreeBuffer function.

When MAPI_ENVELOPE_ONLY and MAPI_SUPPRESS_ATTACH are not set, attachments are written to temporary files pointed to by the lpFiles member of the MapiMessage structure. It is the caller’s responsibility to delete these files when they are no longer needed.

Return Values

MAPI_E_ATTACHMENT_WRITE_FAILURE

An attachment could not be written to a temporary file. Check directory permissions.

MAPI_E_DISK_FULL

An attachment could not be written to a temporary file because there was not enough space on the disk.

MAPI_E_FAILURE

One or more unspecified errors occurred while reading the message.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to read the message.

MAPI_E_INVALID_MESSAGE

An invalid message identifier was passed in the lpszMessageID parameter.

MAPI_E_INVALID_SESSION

An invalid session handle was passed in the lhSession parameter. No message was retrieved.

MAPI_E_TOO_MANY_FILES

There were too many file attachments in the message. The message could not be read.

MAPI_E_TOO_MANY_RECIPIENTS

There were too many recipients of the message. The message could not be read.

SUCCESS_SUCCESS

The call succeeded and the message was read.

Remarks

The MAPIReadMail function returns one message, breaking the message content into the same parameters and structures used in the MAPISendMail function. MAPIReadMail fills a block of memory with the MapiMessage structure containing message elements, such as the subject, message class, delivery time, and the sender. File attachments are saved to temporary files, and the names are returned to the caller in the message structure. Recipients, attachments, and contents are copied from the message before MAPIReadMail returns to the caller, so later changes to the files do not affect the contents of the message.

A flag is provided to specify that only envelope information is to be returned from the call. Another flag (in the MapiMessage structure) specifies whether the message is marked as sent or unsent.

The caller is responsible for freeing the MapiMessage structure by calling the MAPIFreeBuffer function and deleting any files associated with attachments included with the message.

Before calling MAPIReadMail, use the MAPIFindNext function to verify that the message to be read is the one you want to be read. Because message identifiers are system-specific and opaque and can be invalidated at any time, MAPIReadMail considers a message identifier to be valid only for the current Simple MAPI session.

See Also

MAPIFreeBuffer, MAPILogon, MapiMessage


MAPIResolveName

The MAPIResolveName function transforms a message recipient’s name as entered by a user to an unambiguous address list entry.

Quick Info

Header file:	MAPI.H
ULONG FAR PASCAL MAPIResolveName(

LHANDLE lhSession,
ULONG ulUIParam,
LPTSTR lpszName,
FLAGS flFlags,
ULONG ulReserved,
lpMapiRecipDesc FAR * lppRecip
)
Parameters

lhSession

[in] Handle that represents a Simple MAPI session or zero. If the value of the lhSession parameter is zero, MAPI logs on the user and creates a session that exists only for the duration of the call. This temporary session can be an existing shared session or a new one. If necessary, the logon dialog box is displayed.

ulUIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG). If no dialog box is displayed during the call, ulUIParam is ignored.

lpszName

[in] Pointer to the name to be resolved.

flFlags

[in] Bitmask of option flags. The following flags can be set:

MAPI_AB_NOMODIFY

The caller is requesting that the dialog box be read-only, prohibiting changes. MAPIResolveName ignores this flag if MAPI_DIALOG is not set.

MAPI_DIALOG

A dialog box should be displayed for name resolution. If this flag is not set and the name cannot be resolved, MAPIResolveName returns the MAPI_E_AMBIGUOUS_RECIPIENT value.

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user to log on if required. When the MAPI_LOGON_UI flag is not set, the client application does not display a logon dialog box and returns an error value if the user is not logged on.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment’s shared session. If the MAPI_NEW_SESSION flag is not set, MAPIResolveName uses an existing shared session.

ulReserved

Reserved; must be zero.

lppRecip

[out] Pointer to a recipient structure if the resolution results in a single match. The recipient structure contains the resolved name and related information. Memory for this structure must be freed using the MAPIFreeBuffer function.

Return Values

MAPI_E_AMBIGUOUS_RECIPIENT

The recipient requested has not been or could not be resolved to a unique address list entry.

MAPI_E_UNKNOWN_RECIPIENT

The recipient could not be resolved to any address. The recipient might not exist or might be unknown.

MAPI_E_FAILURE

One or more unspecified errors occurred. The name was not resolved.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. The name was not resolved.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. The name was not resolved.

MAPI_E_NOT_SUPPORTED

The operation was not supported by the underlying messaging system.

MAPI_E_USER_ABORT

The user canceled one of the dialog boxes. The name was not resolved.

SUCCESS_SUCCESS

The call succeeded and the name was resolved.

Remarks

The MAPIResolveName function resolves a message recipient’s name (as entered by a user) to an unambiguous address list entry, optionally prompting the user to choose between possible entries, if necessary. A recipient descriptor structure containing fully resolved information about the entry is allocated and returned. The caller should free this MAPIRecipDesc structure at some point by calling the MAPIFreeBuffer function. If MAPIResolveName returns an error value, it is not necessary to deallocate memory with MAPIFreeBuffer.

See Also

MAPIFreeBuffer, MAPILogon, MapiRecipDesc


MAPISaveMail

The MAPISaveMail function saves a message into the message store.

Quick Info

Header file:	MAPI.H
ULONG FAR PASCAL MAPISaveMail(

LHANDLE lhSession,
ULONG ulUIParam,
lpMapiMessage lpMessage,
FLAGS flFlags,
ULONG ulReserved,
LPTSTR lpszMessageID
)
Parameters

lhSession

[in] Handle for a Simple MAPI session or zero. The value of the lhSession parameter must not be zero if the lpszMessageID parameter contains a valid message identifier. However, if lpszMessageID does not contain a valid message identifier, and the value of lhSession is zero, MAPI logs on the user and creates a session that exists only for the duration of the call. This temporary session can be an existing shared session or a new one. If necessary, the logon dialog box is displayed.

ulUIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG). If no dialog box is displayed during the call, ulUIParam is ignored.

lpMessage

Input parameter pointing to a MapiMessage structure containing the contents of the message to be saved. The lpOriginator member is ignored. Applications can either ignore the flFlags member, or if the message has never been saved, can set the MAPI_SENT and MAPI_UNREAD flags.

flFlags

[in] Bitmask of option flags. The following flags can be set:

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user to logon if required. When the MAPI_LOGON_UI flag is not set, the client application does not display a logon dialog box and returns an error value if the user is not logged on. MAPISaveMail ignores this flag if the lpszMessageID parameter is empty.

MAPI_LONG_MSGID

The returned message identifier is expected to be 512 characters. If this flag is set, the lpszMessageID parameter must be large enough to accomodate 512 characters.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment’s shared session. If the MAPI_NEW_SESSION flag is not set, MAPISaveMail uses an existing shared session.

MAPI_LONG_MSGID

When the input message is NULL, this flag should be passed into MAPISaveMail, and the accompanying message identifier buffer should be 512 bytes long.

ulReserved

Reserved; must be zero.

lpszMessageID

[in, out] Pointer to either the message identifier to be replaced by the save operation or an empty string, indicating that a new message is to be created. The string must be allocated by the caller and must be able to hold at least 512 characters if the flFlags parameter is set to MAPI_LONG_MSGID. If the flFlags parameter is not set to MAPI_LONG_MSGID, the message identifier string can hold 64 characters.

Return Values

MAPI_E_ATTACHMENT_NOT_FOUND

An attachment could not be located at the specified path. Either the drive letter was invalid, the path was not found on that drive, or the file was not found in that path.

MAPI_E_BAD_RECIPTYPE

The recipient type in the lpMessage was invalid.

MAPI_E_FAILURE

One or more unspecified errors occurred while saving the message. No message was saved.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to save the message. No message was saved.

MAPI_E_INVALID_MESSAGE

An invalid message identifier was passed in the lpszMessageID parameter; no message was saved.

MAPI_E_INVALID_RECIPS

One or more recipients of the message were invalid or could not be identified.

MAPI_E_INVALID_SESSION

An invalid session handle was passed in the lhSession parameter. No message was saved.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No message was saved.

MAPI_E_NOT_SUPPORTED

The operation was not supported by the underlying messaging system.

MAPI_E_USER_ABORT

The user canceled one of the dialog boxes. No message was saved.

SUCCESS_SUCCESS

The call succeeded and the message was saved.

Remarks

The MAPISaveMail function saves a message, optionally replacing an existing message. Before calling MAPISaveMail, use the MAPIFindNext function to verify that the message to be saved is the one you want saved. The elements of the message identified by the lpszMessageID parameter are replaced by the elements in the lpMessage parameter. If lpszMessageID is empty, a new message is created. All replaced messages are saved in their appropriate folders. New messages are saved in the folder appropriate for incoming messages of that class.

Not all messaging systems support storing messages. If the underlying messaging system does not support message storage, MAPISaveMail returns the MAPI_E_NOT_SUPPORTED value.

Because message identifiers are system-specific and opaque and can be invalidated at any time, MAPISaveMail considers a message identifier to be valid only for the current Simple MAPI session. MAPISaveMail handles invalid message identifiers by returning the MAPI_E_INVALID_MESSAGE value.

See Also

MAPILogon, MapiMessage


MAPISendDocuments

The MAPISendDocuments function sends a standard message with one or more attached files and a cover note. The cover note is a dialog box that allows the user to enter a list of recipients and an optional message. MAPISendDocuments differs from the MAPISendMail function in that it allows less flexibility in message generation.

Quick Info

Header file:	MAPI.H
ULONG FAR PASCAL MAPISendDocuments(

ULONG ulUIParam,
LPTSTR lpszDelimChar,
LPTSTR lpszFullPaths,
LPTSTR lpszFileNames,
ULONG ulReserved
)
Parameters

ulUIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG). If no dialog box is displayed during the call, ulUIParam is ignored.

lpszDelimChar

[in] Pointer to a character that the caller uses to delimit the names pointed to by the lpszFullPaths and lpszFileNames parameters. The caller should select a character for the delimiter that is not used in operating system filenames.

lpszFullPaths

[in] Pointer to a string containing a list of full paths (including drive letters) to attachment files. This list is formed by concatenating correctly formed file paths separated by the character specified in the lpszDelimChar parameter and followed by a null terminator. An example of a valid list is:

C:\TMP\TEMP1.DOC;C:\TMP\TEMP2.DOC

The files specified in this parameter are added to the message as file attachments. If this parameter is NULL or contains an empty string, the Send Note dialog box is displayed with no attached files.

lpszFileNames

[in] Pointer to a null-terminated list of the original filenames as they should appear in the message. When multiple names are specified, the list is formed by concatenating the filenames separated by the character specified in the lpszDelimChar parameter and followed by a null terminator. An example is:

TEMP3.DOC;TEMP4.DOC

If there is no value for the lpszFileNames parameter or if it is empty, MAPISendDocuments sets the filenames set to the filename values indicated by the lpszFullPaths parameter.

ulReserved

Reserved; must be zero.

Return Values

MAPI_E_ATTACHMENT_OPEN_FAILURE

One or more files in the lpszFilePaths parameter could not be located. No message was sent.

MAPI_E_ATTACHMENT_WRITE_FAILURE

An attachment could not be written to a temporary file. Check directory permissions.

MAPI_E_FAILURE

One or more unspecified errors occurred while sending the message. It is not known if the message was sent.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No message was sent.

MAPI_E_USER_ABORT

The user canceled one of the dialog boxes. No message was sent.

SUCCESS_SUCCESS

The call succeeded and the message was sent.

Remarks

The MAPISendDocuments function sends a standard message, always displaying a cover note dialog box so the user can provide recipients and other sending options. This function tries to establish a session using the messaging system’s shared session. If no shared session exists, it prompts the user for logon information to establish a session. Before MAPISendDocuments returns, it ends the session.

Message attachments can include the active document or all the currently open documents in the client application that called MAPISendDocuments. This function is used primarily for calls from a macro or scripting language, often found in applications such as spreadsheet or word-processing programs.

MAPISendDocuments creates as many file attachments as there are paths specified by the lpszFullPaths parameter in spite of the fact that there can be different numbers of paths and filenames. The caller is responsible for deleting temporary files created when using MAPISendDocuments.

See Also

MAPISendMail


MAPISendMail

The MAPISendMail function sends a message. This function differs from the MAPISendDocuments function in that it allows greater flexibility in message generation.

Quick Info

Header file:	MAPI.H
ULONG FAR PASCAL MAPISendMail(

LHANDLE lhSession,
ULONG ulUIParam,
lpMapiMessage lpMessage,
FLAGS flFlags,
ULONG ulReserved
)
Parameters

lhSession

[in] Handle to a Simple MAPI session or zero. If the value of the lhSession parameter is zero, MAPI logs on the user and creates a session that exists only for the duration of the call. This temporary session can be an existing shared session or a new one. If necessary, the logon dialog box is displayed.

ulUIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG). If no dialog box is displayed during the call, ulUIParam is ignored.

lpMessage

[in] Pointer to a MapiMessage structure containing the message to be sent. If the MAPI_DIALOG flag is not set, the nRecipCount and lpRecips members must be valid for successful message delivery. Client applications can set the flFlags member to MAPI_RECEIPT_REQUESTED to request a read report. All other members are ignored and unused pointers should be NULL.

flFlags

[in] Bitmask of option flags. The following flags can be set:

MAPI_DIALOG

A dialog box should be displayed to prompt the user for recipients and other sending options. When MAPI_DIALOG is not set, at least one recipient must be specified.

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user to log on if required. When the MAPI_LOGON_UI flag is not set, the client application does not display a logon dialog box and returns an error value if the user is not logged on. MAPISendMail ignores this flag if the lpszMessageID parameter is empty.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment’s shared session. If the MAPI_NEW_SESSION flag is not set, MAPISendMail uses an existing shared session.

ulReserved

Reserved; must be zero.

Return Values

MAPI_E_AMBIGUOUS_RECIPIENT

A recipient matched more than one of the recipient descriptor structures and MAPI_DIALOG was not set. No message was sent.

MAPI_E_ATTACHMENT_NOT_FOUND

The specified attachment was not found. No message was sent.

MAPI_E_ATTACHMENT_OPEN_FAILURE

The specified attachment could not be opened. No message was sent.

MAPI_E_BAD_RECIPTYPE

The type of a recipient was not MAPI_TO, MAPI_CC, or MAPI_BCC. No message was sent.

MAPI_E_FAILURE

One or more unspecified errors occurred. No message was sent.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. No message was sent.

MAPI_E_INVALID_RECIPS

One or more recipients were invalid or did not resolve to any address.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No message was sent.

MAPI_E_TEXT_TOO_LARGE

The text in the message was too large. No message was sent.

MAPI_E_TOO_MANY_FILES

There were too many file attachments. No message was sent.

MAPI_E_TOO_MANY_RECIPIENTS

There were too many recipients. No message was sent.

MAPI_E_UNKNOWN_RECIPIENT

A recipient did not appear in the address list. No message was sent.

MAPI_E_USER_ABORT

The user canceled one of the dialog boxes. No message was sent.

SUCCESS_SUCCESS

The call succeeded and the message was sent.

Remarks

The MAPISendMail function sends a standard message, with or without any user interaction. The profile must be configured so that MAPISendMail can open the default service providers without requiring user interaction. However, if the flFlags parameter is set to MAPI_NEW_SESSION, disallowing the use of a shared session, and the profile requires a password, MAPI_LOGON_UI must be set or the function will fail. Client applications can avoid this situation by using an explicit profile without a password or by using the default profile without a password.

Client applications can provide a full or partial list of recipient names, subject text, file attachments, or message text. If any information is missing, MAPISendMail can prompt the user for it. If no information is missing, either the message can be sent as is or the user can be prompted to verify the information, changing values if necessary.

A successful return from MAPISendMail does not necessarily imply recipient validation. The message might not have been sent to all recipients. Depending on the transport provider, recipient validation can be a lengthy process.

A NULL value for the lpszSubject member of the MapiMessage structure pointed to by the lpMessage parameter indicates that there is no text for the subject of the message. A NULL value for the lpszNoteText member indicates that there is no message text. Some client applications can truncate subject lines that are too long or contain carriage returns, line feeds, or form feeds.

Each paragraph should be terminated with a CR (0x0d), an LF (0x0a), or a CRLF pair (0x0d0a). MAPISendMail wraps lines as appropriate. If the text exceeds system limits, the function returns the MAPI_E_TEXT_TOO_LARGE value.

The lpszMessageType member of the MapiMessage structure pointed to by lpMessage is used only by non-IPM applications. Applications that handle IPM messages can set it to NULL or have it point to an empty string.

The number of attachments per message can be limited in some messaging systems. If the limit is exceeded, the MAPI_E_TOO_MANY_FILES value is returned. If no files are specified, a pointer value of NULL should be assigned to the lpFiles member of the structure pointed to by lpMessage. File attachments are copied to the message before MAPISendMail returns; therefore, later changes to the files do not affect the contents of the message. The files must be closed when they are copied. Do not attempt to display attachments outside the range of the message text.

Some messaging systems can limit the number of recipients per message. A pointer value of NULL for the lpRecips member in the MapiMessage structure pointed to by lpMessage indicates no recipients. If the client application passes a non-NULL value indicating a number of recipients exceeding the system limit, MAPISendMail returns the MAPI_E_TOO_MANY_RECIPIENTS value. If the value of the nRecipCount member in the MapiMessage structure pointed to by lpMessage is 0, the MAPI_DIALOG flag must be present in the call to MAPISendMail.

Note that the lpRecips member in the MapiMessage structure can include either an entry identifier, the recipient’s name, an address, or a name and address pair. The following table shows how MAPISendMail handles the variety of information that can be specified:

Information	Action
entry identifier	No name resolution; the name and address are ignored.
name	Name resolved using the Simple MAPI resolution rules.
address	No name resolution; address is used for both message delivery and for displaying the recipient name.
name and address	No name resolution; name used only for displaying the recipient name.
Client applications that send messages to custom recipients can avoid name resolution. Such clients should set the lpszAddress member of the MapiRecipDesc structure pointed to by the lpRecips member of the MapiMessage structure pointed to by the lpMessage parameter to the custom address.

MAPISendMail does not require an originator-type recipient to send a message.

See Also

MAPILogon, MapiMessage, MapiRecipDesc


Structures for C and C++

The following alphabetized entries contain documentation for the Simple MAPI structures for C and C++.


MapiFileDesc (Simple MAPI)

A MapiFileDesc structure contains information about a file containing a message attachment stored as a temporary file. That file can contain a static OLE object, an embedded OLE object, an embedded message, and other types of files.

Quick Info

Header file:	MAPI.H
typedef struct {

     ULONG ulReserved;

     ULONG flFlags;

     ULONG nPosition;

     LPTSTR lpszPathName;

     LPTSTR lpszFileName;

     LPVOID lpFileType;

} MapiFileDesc, FAR *lpMapiFileDesc;

Members

ulReserved

Reserved; must be zero.

flFlags

Bitmask of attachment flags. The following flags can be set:

MAPI_OLE

The attachment is an OLE object. If MAPI_OLE_STATIC is also set, the attachment is a static OLE object. If MAPI_OLE_STATIC is not set, the attachment is an embedded OLE object.

MAPI_OLE_STATIC

The attachment is a static OLE object.

If neither flag is set, the attachment is treated as a data file.

nPosition

An integer used to indicate where in the message text to render the attachment. Attachments replace the character found at a certain position in the message text. That is, attachments replace the character in the MapiMessage structure field NoteText[nPosition]. A value of  − 1 (0xFFFFFFFF) means the attachment position is not indicated; the client application will have to provide a way for the user to access the attachment.

lpszPathName

Pointer to the fully qualified path of the attached file. This path should include the disk drive letter and directory name.

lpszFileName

Pointer to the attachment filename seen by the recipient, which may differ from the filename in the lpszPathName member if temporary files are being used. If the lpszFileName member is empty or NULL, the filename from lpszPathName is used.

lpFileType

Pointer to the attachment file type, which can be represented with a MapiFileTagExt structure. A value of NULL indicates an unknown file type or a file type determined by the operating system.

Remarks

Simple MAPI works with three kinds of embedded attachments:

•	Data file attachments

•	Editable OLE object file attachments

•	Static OLE object file attachments

Data file attachments are simply data files. OLE object file attachments are OLE objects that are displayed in the message text. If the OLE attachment is editable, the recipient can double-click it and its source application will be started to handle the edit session. If the OLE attachment is static, the object cannot be edited. The flag set in the flFlags member of the MapiFileDesc structure determines the kind of a particular attachment. Embedded messages can be identified by a .MSG extension in the lpszFileName member.

OLE object files are file representations of OLE object streams. The client application can recreate an OLE object from the file by calling the OLE function OleLoadFromStream with an OLESTREAM object that reads the file contents. If an OLE file attachment is included in an outbound message, the OLE object stream should be written directly to the file used as the attachment.

When using the MapiFileDesc member nPosition, the client application should not place two attachments in the same location. Client applications might not display file attachments at positions beyond the end of the message text.

See Also

MapiFileTagExt


MapiFileTagExt (Simple MAPI)

A MapiFileTagExt structure specifies a message attachment’s type at its creation and its current form of encoding so that it can be restored to its original type at its destination.

Quick Info

Header file:	MAPI.H
typedef struct {

     ULONG ulReserved;

     ULONG cbTag;

     LPBYTE lpTag;

     ULONG cbEncoding;

     LPBYTE lpEncoding

} MapiFileTagExt, FAR *lpMapiFileTagExt;

Members

ulReserved

Reserved; must be zero.

cbTag

The size, in bytes, of the value defined by the lpTag member.

lpTag

Pointer to an X.400 object identifier indicating the type of the attachment in its original form, for example “Microsoft Excel worksheet”.

cbEncoding

The size, in bytes, of the value defined by the lpEncoding member.

lpEncoding

Pointer to an X.400 object identifier indicating the form in which the attachment is currently encoded, for example MacBinary, UUENCODE, or binary.

Remarks

A MapiFileTagExt structure defines the type of an attached file for purposes such as encoding and decoding the file, choosing the correct application to launch when opening it, or any use that requires full information regarding the file type. Client applications can use information in the lpTag and lpEncoding members of this structure to determine what to do with an attachment.

See Also

PR_ATTACH_TAG, PR_ATTACH_ENCODING, MapiFileDesc


MapiMessage (Simple MAPI)

A MapiMessage structure contains information about a message.

Quick Info

Header file:	MAPI.H
typedef struct {

     ULONG ulReserved;

     LPTSTR lpszSubject;

     LPTSTR lpszNoteText;

     LPTSTR lpszMessageType;

     LPTSTR lpszDateReceived;

     LPTSTR lpszConversationID;

     FLAGS flFlags;

     lpMapiRecipDesc lpOriginator;

     ULONG nRecipCount;

     lpMapiRecipDesc lpRecips;

     ULONG nFileCount;

     lpMapiFileDesc lpFiles;

} MapiMessage, FAR *lpMapiMessage;

Members

ulReserved

Reserved; must be zero.

lpszSubject

Pointer to the text string describing the message subject, typically limited to 256 characters or less. If this member is empty or NULL, the user has not entered subject text.

lpszNoteText

Pointer to a string containing the message text. If this member is empty or NULL, there is no message text.

lpszMessageType

Pointer to a string indicating a non-IPM type of message. Client applications can select message types for their non-IPM messages. Clients that only support IPM messages can ignore the lpszMessageType member when reading messages and set it to empty or NULL when sending messages.

lpszDateReceived

Pointer to a string indicating the date when the message was received. The format is YYYY/MM/DD HH:MM, using a 24-hour clock.

lpszConversationID

Pointer to a string identifying the conversation thread to which the message belongs. Some messaging systems can ignore and not return this member.

flFlags

Bitmask of message status flags. The following flags can be set:

MAPI_RECEIPT_REQUESTED

A receipt notification is requested. Client applications set this flag when sending a message.

MAPI_SENT

The message has been sent.

MAPI_UNREAD

The message has not been read.

lpOriginator

Pointer to a MapiRecipDesc structure containing information about the sender of the message.

nRecipCount

The number of message recipient structures in the array pointed to by the lpRecips member. A value of zero indicates no recipients are included.

lpRecips

Pointer to an array of MapiRecipDesc structures, each containing information about a message recipient.

nFileCount

The number of structures describing file attachments in the array pointed to by the lpFiles member. A value of zero indicates no file attachments are included.

lpFiles

Pointer to an array of MapiFileDesc structures, each containing information about a file attachment.

See Also

MapiFileDesc, MapiRecipDesc


MapiRecipDesc (Simple MAPI)

A MapiRecipDesc structure contains information about a message sender or recipient.

Quick Info

Header file:	MAPI.H
typedef struct {

     ULONG ulReserved

     ULONG ulRecipClass;

     LPTSTR lpszName;

     LPTSTR lpszAddress;

     ULONG ulEIDSize;

     LPVOID lpEntryID;

} MapiRecipDesc, FAR *lpMapiRecipDesc;

Members

ulReserved

Reserved; must be zero.

ulRecipClass

Contains a numeric value that indicates the type of recipient. Possible values are:

Value	Constant	Meaning
0	MAPI_ORIG	Indicates the original sender of the message.
1	MAPI_TO	Indicates a primary message recipient.
2	MAPI_CC	Indicates a recipient of a message copy.
3	MAPI_BCC	Indicates a recipient of a blind copy.
lpszName

Pointer to the display name of the message recipient or sender.

lpszAddress

Optional pointer to the recipient or sender’s address; this address is provider-specific message delivery data. Generally, the messaging system provides such addresses for inbound messages. For outbound messages, the lpszAddress member can point to an address entered by the user for a recipient not in an address book (that is, a custom recipient).

The format of an address pointed to by the lpszAddress member is [address type][e-mail address]. Examples of valid addresses are FAX:206-555-1212 and SMTP:M@X.COM.

ulEIDSize

The size, in bytes, of the entry identifier pointed to by the lpEntryID member.

lpEntryID

Pointer to an opaque entry identifier used by a messaging system service provider to identify the message recipient. Entry identifiers have meaning only for the service provider; client applications will not be able to decipher them. The messaging system uses this member to return valid entry identifiers for all recipients or senders listed in the address book.


Functions for Visual Basic

Visual Basic uses a different set of calling and programming conventions than C and C++ use. Different structure and parameter definitions support the Visual Basic representation of strings and of structures, which in Visual Basic are called types. The following list describes how programming Simple MAPI Visual Basic applications differs from programming Simple MAPI C and C++ applications:

•	Because the concept of a pointer is foreign to Visual Basic, developers use extra function parameters instead of the complex pointer structures used in C and C++.

•	Because the Visual Basic MAPI functions are declared, it is not necessary to explicitly cast passed arguments using ByVal.

•	An empty string in a string variable is equivalent to a NULL value.

•	Arrays must be dynamically declared so that they are redimensioned when the Simple MAPI function is executed.

•	Visual Basic manages memory, eliminating the need for calling the MAPIFreeBuffer function.

•	All structures used in the Visual Basic version of Simple MAPI are Visual Basic types rather than C-language structures.

•	All strings used in the Visual Basic version of Simple MAPI are Visual Basic strings rather than C-language strings.

The Simple MAPI functions for Visual Basic work with Visual Basic 3, Visual Basic 4, and Visual Basic for Applications. Note that slight differences in the 16-bit and 32-bit Visual Basic runtime DLLs mean that some Simple MAPI functions have different declarations depending on which runtime is being used. The 32-bit declarations use explicit Visual Basic array notation. The alternate declarations are documented with the functions that have them.


MAPIAddress (VB)

The Visual Basic MAPIAddress function enables users to create or modify a set of recipients. MAPIAddress generates an address-book dialog box that shows the contents of the recipient set and allows the user to select new entries or change existing entries.

Quick Info

Header file:	MAPIVB32.BAS
MAPIAddress(

Session as Long,
UIParam as Long,
Caption as String,
EditFields as Long,
Label as String,
RecipCount as Long,
Recipients() as MapiRecip,
Flags as Long,
Reserved as Long) as Long

Parameters

Session

[in] Session handle that represents a Simple MAPI session or zero. If the value of the Session parameter is zero, MAPI logs on the user and creates a session that exists only for the duration of the call. This temporary session can be an existing shared session or a new one. If necessary, a logon dialog box is displayed.

UIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If no dialog box is displayed during the call, the UIParam parameter is ignored.

Caption

[in] Caption of the address-list dialog box. If this parameter is an empty string, the default value “Address Book” is used.

EditFields

[in] The number of edit controls that should be present in the address list. The values 0 through 4are valid. If the value of the nEditFields parameter is 4, each recipient class supported by the underlying messaging system has an edit control. If the value of EditFields is zero, only address list browsing is possible. Values of 1, 2, or 3 control the number of edit controls present.

However, if the number of recipient classes in the Recipients parameter is greater than the value of EditFields, the number of classes in Recipients is used to indicate the number of edit controls instead of the value of EditFields. If the value of EditFields is 1 and more than one kind of entry exists in Recipients, then the Labels parameter is ignored.

Entries selected for the different controls are differentiated by the ulRecipClass member in the returned recipient structure.

Label

[in] Edit control label in the address-list dialog box. The Label parameter is ignored and should be an empty string except when the value of the EditFields parameter is 1. If you want a default control label “To:”, Label should be an empty string.

RecipCount

[in] The number of entries in the Recipients parameter. If the value of the RecipCount parameter is zero, Recipients is ignored.

Recipients

[in] The initial array of recipient entries to be used to populate edit controls in the address-list dialog box. Recipient entries need not be grouped by recipient class. If the value of the greatest recipient class present is greater than the value of the EditFields parameter, the EditFields and Label parameters are ignored. This array is redimensioned as necessary to accommodate the entries made by the user in the address-list dialog box.

Flags

[in] Bitmask of flags. The following flags can be set:

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user to log on if required. When the MAPI_LOGON_UI flag is not set, the client application does not display a logon dialog box and returns an error value if the user is not logged on.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment’s shared session. If the MAPI_NEW_SESSION flag is not set, MAPIAddress uses an existing shared session.

Reserved

Reserved; must be zero.

Return Values

MAPI_E_FAILURE

One or more unspecified errors occurred while building recipient lists or browsing the address book. No list of recipients was returned.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. No list of recipients was returned.

MAPI_E_INVALID_EDITFIELDS

The value of the nEditFields parameter was outside the range of 0 through 4. No list of recipients was returned.

MAPI_E_INVALID_RECIPS

One or more of the recipients in the address list was not valid or the Recipients parameter was not a valid array. No list of recipients was returned.

MAPI_E_INVALID_SESSION

An invalid session handle was used for the lhSession parameter. No list of recipients was returned.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No list of recipients was returned.

MAPI_E_NOT_SUPPORTED

The operation was not supported by the underlying messaging system. A list of recipients might have been returned.

MAPI_E_USER_ABORT

The user canceled one of the dialog boxes. No list of recipients was returned.

SUCCESS_SUCCESS

The call succeeded and a list of address entries was returned.

Remarks

The MAPIAddress function makes it possible for users to create or modify a set of address-list entries using a standard address-list dialog box. The dialog box cannot be suppressed, but function parameters allow the caller to set characteristics of the dialog box.

The call is made with an initial, and possibly empty, set of recipients. The address-list dialog box shows the contents of the recipient set; users can choose new entries to add to the set. The final set of recipients is returned to the caller in the RecipCount and Recipients parameters, destroying their initial values.

The declaration of this function for the 32-bit Visual Basic runtime is:

MAPIAddress(

Session As Long,
UIParam As Long,
Caption As String,
nEditFields As Long,
Label As String,
nRecipients As Long,
Recips() As MapiRecip,
Flags As Long,
Reserved As Long) As Long


MAPIDeleteMail (VB)

The Visual Basic MAPIDeleteMail function deletes a message.

Quick Info

Header file:	MAPIVB32.BAS
MAPIDeleteMail(

Session as Long,
UIParam as Long,
MessageID as String,
Flags as Long,
Reserved as Long) as Long

Parameters

Session

[in] Session handle that represents a valid Simple MAPI session. The value of the Session parameter cannot be zero.

UIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If no dialog box is displayed during the call, the UIParam parameter is ignored.

MessageID

[in] Identifier for the message to be deleted. This string identifier is messaging system-specific and will be invalid when the MAPIDeleteMail function successfully returns. Both the MAPIFindNext and MAPISaveMail functions return message identifiers.

Flags

Reserved; must be zero.

Reserved

Reserved; must be zero.

Return Values

MAPI_E_FAILURE

One or more unspecified errors occurred while deleting the message. No message was deleted.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. No message was deleted.

MAPI_E_INVALID_MESSAGE

An invalid message identifier was passed in for the MessageID parameter. No message was deleted.

MAPI_E_INVALID_SESSION

An invalid session handle was passed in for the Session parameter. No message was deleted.

SUCCESS_SUCCESS

The call succeeded and the message was deleted.

Remarks

To find the message to be deleted, call the MAPIFindNext function before calling MAPIDeleteMail.

The declaration of this function for the 32-bit Visual Basic runtime is:

MAPIDeleteMail(

ByVal Session&,
ByVal UIParam&,
ByVal MsgID$,
ByVal Flags&,
ByVal Reserved&) As Long


MAPIDetails (VB)

The Visual Basic MAPIDetails function displays a dialog box containing the details of a selected address-list entry.

Quick Info

Header file:	MAPIVB32.BAS
MAPIDetails(

Session as Long,
UIParam as Long,
Recipient as MapiRecip,
Flags as Long,
Reserved as Long) as Long

Parameters

Session

[in] Session handle that represents a Simple MAPI session or zero. If the value of the Session parameter is zero, MAPI logs on the user and creates a session that exists only for the duration of the call. This temporary session can be an existing shared session or a new one. If necessary, a logon dialog box is displayed.

UIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If no dialog box is displayed during the call, the UIParam parameter is ignored.

Recipient

[in] Recipient descriptor containing the entry whose details are to be displayed. MAPIDetails ignores all members of the MapiRecip type except EIDSize and EntryID. If the value of the EIDSize member is non-zero, MAPIDetails resolves the recipient entry. If the value of EIDSize is zero, the MAPI_E_AMBIGUOUS_RECIPIENT value is returned.

Flags

[in] Bitmask of flags. The following flags can be set:

MAPI_AB_NOMODIFY

The caller is requesting that the dialog box be read-only, prohibiting changes. MAPIDetails might or might not honor the request.

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user to log on if required. When the MAPI_LOGON_UI flag is not set, the client application does not display a logon dialog box and returns an error value if the user is not logged on.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment’s shared session. If the MAPI_NEW_SESSION flag is not set, MAPIDetails uses an existing shared session.

Reserved

Reserved; must be zero.

Return Values

MAPI_E_AMBIGUOUS_RECIPIENT

The recipient requested has not been or could not be resolved to a unique address list entry.

MAPI_E_FAILURE

One or more unspecified errors occurred. No dialog box was displayed.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. No dialog box was displayed.

MAPI_E_INVALID_RECIPS

The recipient specified in the Recipient parameter was unknown. No dialog box was displayed.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No dialog box was displayed.

MAPI_E_NOT_SUPPORTED

The operation was not supported by the underlying messaging system.

MAPI_E_USER_ABORT

The user canceled either the logon dialog box or the details dialog box.

SUCCESS_SUCCESS

The call succeeded and the details dialog box was displayed.

Remarks

The MAPIDetails function presents a dialog box that shows the details of a particular address list entry. The display name and address are the minimum attributes that are displayed in the dialog box; more information can be shown depending on the directory to which the entry belongs. The details dialog box cannot be suppressed, but the caller can request that it be read-only or modifiable.

Details can only be shown for resolved address list entries. An entry is resolved if the EIDSize member of the MapiRecip type is nonzero. Entries are resolved when they are returned by the MAPIAddress or MAPIResolveName functions and as the result of being recipients of read mail.

The declaration of this function for the 32-bit Visual Basic runtime is:

MAPIDetails(

ByVal Session&,
ByVal UIParam&,
Recipient As MapiRecip,
ByVal Flags&,
ByVal Reserved&) As Long


MAPIFindNext (VB)

The Visual Basic MAPIFindNext function retrieves the next (or first) message identifier of a specified type of incoming message.

Quick Info

Header file:	MAPIVB32.BAS
MAPIFindNext(

Session as Long,
UIParam as Long,
MessageType as String,
SeedMessageID as String,
Flags as Long,
Reserved as Long,
MessageID as String) as Long

Parameters

Session

[in] Session handle that represents a Simple MAPI session. The value of the Session parameter must represent a valid session; it cannot be zero.

UIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If no dialog box is displayed during the call, the UIParam parameter is ignored.

MessageType

[in] The type of message to search. To find an interpersonal message (IPM), use an empty string, "".

SeedMessageID

[in] The message identifier seed for the request. If the SeedMessageID parameter is an empty string, MAPIFindNext retrieves the first message that matches the type specified in the MessageType parameter.

Flags

[in] Bitmask of option flags. The following flags can be set:

MAPI_GUARANTEE_FIFO

The message identifiers returned should be in the order of time received. MAPIFindNext calls can take longer if this flag is set. Some implementations cannot honor this request and return the MAPI_E_NO_SUPPORT value.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment’s shared session. If the MAPI_NEW_SESSION flag is not set, MAPIFindNext uses an existing shared session.

MAPI_UNREAD_ONLY

Only unread messages of the specified type should be enumerated. When this flag is not set, MAPIFindNext can return any message of the specified type.

Reserved

Reserved; must be zero.

MessageID

[out] The returned message identifier. The MessageID parameter is a variable-length string allocated by the caller. To ensure compatibility, allocate 512 characters. A smaller buffer is sufficient only if the returned message identifier is always 64 characters or less.

Return Values

MAPI_E_FAILURE

One or more unspecified errors occurred while matching the message type. The call failed before message type matching could take place.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. No message was found.

MAPI_E_INVALID_MESSAGE

An invalid message identifier was passed in the SeedMessageID parameter. No message was found.

MAPI_E_INVALID_SESSION

An invalid session handle was passed in the lhSession parameter. No message was found.

MAPI_E_NO_MESSAGES

A matching message could not be found.

SUCCESS_SUCCESS

The call succeeded and the message identifier was returned.

Remarks

The MAPIFindNext function allows a client application to enumerate messages of a given type. This function can be called repeatedly to list all messages in the folder. Message identifiers returned from MAPIFindNext can be used in other Simple MAPI calls to retrieve message contents and delete messages. This function is for processing incoming messages, not for managing received messages.

When the value of the SeedMessageID parameter is NULL or empty, MAPIFindNext returns the message identifier for the first message of the type specified by the MessageType parameter. When SeedMessageID contains a valid identifier, MAPIFindNext returns the next matching message of the type specified by MessageType. Repeated calls to MAPIFindNext ultimately result in a return of the MAPI_E_NO_MESSAGES value, which means the enumeration is complete.

Because message identifiers are messaging system-specific and can be invalidated at any time, message identifiers are valid only for the current session. If the message identifier passed in with SeedMessageID is invalid, MAPIFindNext returns the MAPI_E_INVALID_MESSAGE value.

Message type matching is done against message class strings. All message types whose names match, up to the length specified in MessageType, are returned.

The declaration of this function for the 32-bit Visual Basic runtime is:

MAPIFindNext(

ByVal Session&,
ByVal UIParam&,
MsgType$,
SeedMsgID$,
ByVal Flag&,
ByVal Reserved&,
MsgID$) As Long


MAPILogoff (VB)

The Visual Basic MAPILogoff function ends a session with the messaging system.

Quick Info

Header file:	MAPIVB32.BAS
MAPILogoff(

Session as Long,
UIParam as Long,
Flags as Long,
Reserved as Long) as Long

Parameters

Session

[in] Handle for a Simple MAPI session to be terminated. Session handles are returned by MAPILogon and invalidated by MAPILogoff. The value of the Session parameter must represent a valid session; it cannot be zero.

UIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If no dialog box is displayed during the call, the UIParam parameter is ignored.

Flags

Reserved; must be zero.

Reserved

Reserved; must be zero.

Return Values

MAPI_E_FAILURE

One or more unspecified errors occurred.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. The session was not terminated.

MAPI_E_INVALID_SESSION

An invalid session handle was used for the Session parameter. The session was not terminated.

SUCCESS_SUCCESS

The call succeeded and the session was terminated.

The declaration of this function for the 32-bit Visual Basic runtime is:

MAPILogoff(

ByVal Session&,
ByVal UIParam&,
ByVal Flags&,
ByVal Reserved&) As Long


MAPILogon (VB)

The Visual Basic MAPILogon function begins a Simple MAPI session, loading the default message store and address book providers.

Quick Info

Header file:	MAPIVB32.BAS
MAPILogon(

UIParam ByVal as Long,
User as String,
Password as String,
Flags as Long,
Reserved as Long,
Session as Long) as Long

Parameters

UIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If no dialog box is displayed during the call, the UIParam parameter is ignored.

User

[in] Client account-name string, limited to 256 characters or less. This is the name to use when logging on. If the User parameter is empty, and the Flags parameter is set to MAPI_LOGON_UI, MAPILogon displays a logon dialog box with an empty name field.

Password

[in] Credential string, limited to 256 characters or less. If the messaging system does not require password credentials, or if it requires that the user enter them, the Password parameter should be empty. When the user must enter credentials, the Flags parameter must be set to MAPI_LOGON_UI to allow a logon dialog box to be displayed.

Flags

[in] Bitmask of option flags. The following flags can be set:

MAPI_FORCE_DOWNLOAD

An attempt should be made to download all of the user’s messages before returning. If the MAPI_FORCE_DOWNLOAD flag is not set, messages can be downloaded in the background after the function call returns.

MAPI_LOGON_UI

A logon dialog box should be displayed to prompt the user for logon information. If the user needs to provide information to enable a successful logon, MAPI_LOGON_UI must be set.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment’s shared session. If the MAPI_NEW_SESSION flag is not set, MAPILogon uses an existing shared session.

Reserved

Reserved; must be zero.

Session

[out] Simple MAPI session handle.

Return Values

MAPI_E_FAILURE

One or more unspecified errors occurred during logon. No session handle was returned.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. No session handle was returned.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No session handle was returned.

MAPI_E_TOO_MANY_SESSIONS

The user had too many sessions open simultaneously. No session handle was returned.

MAPI_E_USER_ABORT

The user canceled the process. No session handle was returned.

SUCCESS_SUCCESS

The call succeeded and a session was established.

Remarks

The MAPILogon function begins a session with the messaging system, returning a handle that can be used in subsequent MAPI calls to explicitly provide user credentials to the messaging system. To request the display of a logon dialog box if the credentials presented fail to validate the session, set the Flags parameter to MAPI_LOGON_UI.

The declaration of this function for the 32-bit Visual Basic runtime is:

MAPILogon(

ByVal UIParam&,
ByVal User$,
ByVal Password$,
ByVal Flags&,
ByVal Reserved&,
Session&) As Long


MAPIReadMail (VB)

The Visual Basic MAPIReadMail function retrieves a message for reading.

Quick Info

Header file:	MAPIVB32.BAS
MAPIReadMail(

Session as Long,
UIParam as Long,
MessageID as String,
Flags as Long,
Reserved as Long,
Message as MapiMessage,
Originator as MapiRecip,
Recips() as MapiRecip,
Files() as MapiFile) as Long

Parameters

Session

[in] Handle to a Simple MAPI session. The value of the Session parameter must represent a valid session; it cannot be zero.

UIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If no dialog box is displayed during the call, the UIParam parameter is ignored.

MessageID

[in] The message identifier of the message to be read. The MessageID parameter is a variable-length string that is obtained from the MAPIFindNext and MAPISaveMail functions.

Flags

[in] Bitmask of flags. The following flags can be set:

MAPI_BODY_AS_FILE

MAPIReadMail should write the message text to a temporary file and add it as the first attachment in the attachment list.

MAPI_ENVELOPE_ONLY

MAPIReadMail should read the message header only. File attachments are not copied to temporary files, and neither temporary file names nor message text are written. Setting this flag makes MAPIReadMail processing faster.

MAPI_PEEK

MAPIReadMail does not mark the message as read. Marking a message as read affects its appearance in the user interface and generates a read receipt. If the messaging system does not support this flag, MAPIReadMail always marks the message as read. If MAPIReadMail encounters an error, it leaves the message unread.

MAPI_SUPPRESS_ATTACH

MAPIReadMail should not copy file attachments but should write message text into the MapiMessage type. MAPIReadMail ignores this flag if the calling application has set the MAPI_ENVELOPE_ONLY flag. Setting this flag makes MAPIReadMail processing faster.

Reserved

Reserved; must be zero.

Message

[out] A type set by MAPIReadMail to a message containing the message contents.

Originator

[out] The originator of the message.

Recips

[out] Array of recipients. This array is redimensioned as necessary to accommodate the number of recipients chosen by the user.

Files

[out] Array of attachment files written when the message is read. When MAPIReadMail is called, all message attachments are written to temporary files. It is the caller’s responsibility to delete these files when they are no longer needed. When MAPI_ENVELOPE_ONLY or MAPI_SUPPRESS_ATTACH is set, no temporary files are written and no temporary names are filled into the file attachment descriptors. This array is redimensioned as necessary to accommodate the number of files attached by the user.

Return Values

MAPI_E_ATTACHMENT_WRITE_FAILURE

An attachment could not be written to a temporary file. Check directory permissions.

MAPI_E_DISK_FULL

The disk was full.

MAPI_E_FAILURE

One or more unspecified errors occurred while reading the message.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to read the message.

MAPI_E_INVALID_MESSAGE

An invalid message identifier was passed in the MessageID parameter.

MAPI_E_INVALID_SESSION

An invalid session handle was passed in the Session parameter. No message was retrieved.

MAPI_E_TOO_MANY_FILES

There were too many file attachments in the message. The message could not be read.

MAPI_E_TOO_MANY_RECIPIENTS

There were too many recipients of the message. The message could not be read.

SUCCESS_SUCCESS

The call succeeded and the message was read.

Remarks

The MAPIReadMail function returns one message, breaking the message content into the same parameters and types used in the MAPISendMail function. MAPIReadMail fills a block of memory with the MapiMessage type containing message elements. File attachments are saved to temporary files, and the names are returned to the caller in the message type. Recipients, attachments, and contents are copied from the message before MAPIReadMail returns to the caller, so later changes to the files do not affect the contents of the message.

A flag is provided to specify that only envelope informationis to be returned from the call. Another flag in the MapiMessage type specifies whether the message is marked as sent or unsent.

All strings are null-terminated and must be specified in the current character set or code page of the client application’s operating system process. In Microsoft Windows, the character set is ANSI.

The sender, recipients, and file attachments are written into the appropriate parameters of the Visual Basic call. The Recips and Files parameters should be dynamically allocated arrays of their respective types.

The declaration of this function for the 32-bit Visual Basic runtime is:

MAPIReadMail(

Session As Long,
UIParam As Long,
MessageID As String,
Flags As Long,
Reserved As Long,
message As MAPIMessage,
Orig As MapiRecip,
RecipsOut() As MapiRecip,
FilesOut() As MapiFile) As Long


MAPIResolveName (VB)

The Visual Basic MAPIResolveName function transforms a message recipient’s name as entered by a user to an unambiguous address list entry.

Quick Info

Header file:	MAPIVB32.BAS
MAPIResolveName(

Session as Long,
UIParam as Long,
UserName as String,
Flags as Long,
Reserved as Long,
Recipient as MapiRecip) as Long

Parameters

Session

[in] Session handle that represents a Simple MAPI session or zero. If the value of the Session parameter is zero, MAPI logs on the user and creates a session that exists only for the duration of the call. This temporary session can be an existing shared session or a new one. If necessary, a logon dialog box is displayed.

UIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If no dialog box is displayed during the call, the UIParam parameter is ignored.

UserName

[in] The name to be resolved.

Flags

[in] Bitmask of option flags. The following flags can be set:

MAPI_AB_NOMODIFY

The caller is requesting that the dialog box be read-only, prohibiting changes. MAPIResolveName ignores this flag if MAPI_DIALOG is not set.

MAPI_DIALOG

A dialog box should be displayed for name resolution. If this flag is not set and the name cannot be resolved, MAPIResolveName returns the MAPI_E_AMBIGUOUS_RECIPIENT value.

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user to log on if required. When the MAPI_LOGON_UI flag is not set, the client application does not display a logon dialog box and returns an error value if the user is not logged on.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment’s shared session. If the MAPI_NEW_SESSION flag is not set, MAPIResolveName uses an existing shared session.

Reserved

Reserved; must be zero.

Recipient

[out] A recipient-type set returned by MAPIResolveName if the resolution results in a single match. The type contains the recipient information of the resolved name. The descriptor can then be used in calls to the MAPISendMail, MAPISaveMail, and MAPIAddress functions.

Return Values

MAPI_E_AMBIGUOUS_RECIPIENT

The recipient requested has not been or could not be resolved to a unique address list entry.

MAPI_E_FAILURE

One or more unspecified errors occurred. The name was not resolved.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. The name was not resolved.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. The name was not resolved.

MAPI_E_NOT_SUPPORTED

The operation was not supported by the underlying messaging system.

MAPI_E_USER_ABORT

The user canceled the resolution. The name was not resolved.

SUCCESS_SUCCESS

The call succeeded and the name was resolved.

Remarks

The MAPIResolveName function resolves a message recipient’s name (as entered by a user) to an unambiguous address list entry, optionally prompting the user to choose between possible entries, if necessary. A recipient descriptor containing fully resolved information about the entry is allocated and returned.

The declaration of this function for the 32-bit Visual Basic runtime is:

MAPIResolveName(

ByVal Session&,
ByVal UIParam&,
ByVal UserName$,
ByVal Flags&,
ByVal Reserved&,
Recipient As MapiRecip) As Long


MAPISaveMail (VB)

The Visual Basic MAPISaveMail function saves a message.

Quick Info

Header file:	MAPIVB32.BAS
MAPISaveMail(

Session as Long,
UIParam as Long,
Message as MapiMessage,
Recips as MapiRecip,
Files as MapiFile,
Flags as Long,
Reserved ByVal as Long,
MessageID as String) as Long

Parameters

Session

[in] Session handle that represents a Simple MAPI session or zero. If the value for the Session parameter is zero, MAPI logs on the user and creates a session that exists only for the duration of the call. This temporary session can be an existing shared session or a new one. If necessary, a logon dialog box is displayed.

UIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If no dialog box is displayed during the call, the UIParam parameter is ignored.

Message

[in] Contents of the message to be saved. Client applications can either ignore the Flags member of the MapiMessage type, or if the message has never been saved, can set the MAPI_SENT and MAPI_UNREAD flags.

Recips

[in] The first element in an array of recipients. When the value of the RecipCount member in the MapiMessage type is zero, this parameter is ignored. The recipient string can include either the recipient’s name or the recipient’s name-address pair. If only a name is specified, the name is resolved to an address using implementation-defined address-book search rules. If an address is also specified, a search for the name is not performed. The address is in an implementation-defined format and is assumed to have been obtained from the implementation some other way. When the address is specified, the name is used for display to the user and the address is used for delivery. When the EntryID member for a particular recipient is used, no search is performed and the display-name and address are ignored. (A name and address are associated with the EntryID within the messaging system.)

Files

[in] The first element in an array of attachment files written when the message is read. The number of attachments per message can be limited in some systems. If the limit is exceeded, the MAPI_E_TOO_MANY_FILES value is returned. When the value of the FileCount member in the MapiMessage type is zero, this parameter is ignored. Attachment files are read and attached to the message before the call returns. Do not attempt to display attachments outside the range of the message text.

Flags

[in] Bitmask of option flags. The following flags can be set:

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user to log on if required. When the MAPI_LOGON_UI flag is not set, the client application does not display a logon dialog box and returns an error value if the user is not logged on. MAPISaveMail ignores this flag if the MessageID parameter is empty.

MAPI_LONG_MSGID

The returned message identifier is expected to be 512 characters. If this flag is set, the MessageID parameter must be large enough to accomodate 512 characters.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment’s shared session. If the MAPI_NEW_SESSION flag is not set, MAPISaveMail uses an existing shared session.

Reserved

Reserved; must be zero.

MessageID

[in] A variable-length, caller-allocated string identifier for the message, returned either by the MAPIFindNext function or a previous call to MAPISaveMail, or a null string. If the MessageID parameter contains a valid message identifier, the message is overwritten. If MessageID contains a null string, a new message is created.

Return Values

MAPI_E_FAILURE

One or more unspecified errors occurred while saving the message. No message was saved.

MAPI_E_BAD_RECIPTYPE

The type of a recipient was not MAPI_TO, MAPI_CC, or MAPI_BCC. No message was sent.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to save the message. No message was saved.

MAPI_E_INVALID_MESSAGE

An invalid message identifier was passed in the MessageID parameter. No message was saved.

MAPI_E_INVALID_SESSION

An invalid session handle was passed in the Session parameter. No message was saved.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No message was saved.

MAPI_E_NOT_SUPPORTED

The operation was not supported by the underlying messaging system.

MAPI_E_USER_ABORT

The user canceled the process. No message was saved.

SUCCESS_SUCCESS

The call succeeded and the message was saved.

Remarks

To replace an existing message, the caller first calls the MAPIFindNext function to locate the message to be replaced and then calls the MAPISaveMail function with the MessageID parameter set with a valid message identifier. The elements of the message identified by MessageID are replaced by the elements in the MapiMessage type pointed to by the Message parameter.

To create a new message, the caller passes an empty string for MessageID. New messages are saved in the folder appropriate for incoming messages of that class. The new message identifier is returned in MessageID on completion.

The MessageID parameter must be a variable-length string. The elements of the message identified by MessageID are replaced by the elements in the Message parameter. If MessageID is empty, a new message is created.

MAPISaveMail takes the recipients and file attachments from the Recips and Files parameters, which should each be the first element of dynamically allocated arrays of their respective types. These arrays are not redimensioned.

The declaration of this function for the 32-bit Visual Basic runtime is:

MAPISaveMail(

ByVal Session&,
ByVal UIParam&,
message As MAPIMessage,
Recipient() As MapiRecip,
File() As MapiFile,
ByVal Flags&,
ByVal Reserved&,
MsgID$) As Long


MAPISendDocuments (VB)

The Visual Basic MAPISendDocuments function sends a standard message with one or more attached files and a cover note. The cover note is a dialog box that allows the user to enter a list of recipients and an optional message.

Quick Info

Header file:	MAPIVB32.BAS
MAPISendDocuments(

UIParam as Long,
DelimChar as String,
FullPaths as String,
FileNames as String,
Reserved as Long) as Long

Parameters

UIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If no dialog box is displayed during the call, the UIParam parameter is ignored.

DelimChar

[in] String containing the character used to delimit the names in the FullPaths and FileNames parameters. This character should not be used in filenames on your operating system.

FullPaths

[in] String containing the list of full paths, including drive letters, for the attached files. The list is formed by concatenating correctly formed file paths separated by the character specified in the DelimChar parameter. An example of a valid list is:

C:\TMP\TEMP1.DOC;C:\TMP\TEMP2.DOC

The files specified in FullPaths are added to the message as file attachments. If FullPaths contains an empty string, the Send Note dialog box is displayed with no attached files.

FileNames

[in] String containing the list of the original filenames as they should be displayed in the message. When multiple names are specified, the list is formed by concatenating the filenames separated by the character specified in the DelimChar parameter. An example is:

MEMO.DOC;EXPENSES.DOC

If there is no value for the FileNames parameter or if it is empty, MAPISendDocuments sets the filenames set to the filename values indicated by the FullPaths parameter.

Reserved

Reserved; must be zero.

Return Values

MAPI_E_ATTACHMENT_NOT_FOUND

An attachment could not be located in the specified path. Either the drive letter was invalid, the path was not found on that drive, or the file was not found in that path.

MAPI_E_ATTACHMENT_OPEN_FAILURE

One or more files in the FullPaths parameter could not be located. No message was sent.

MAPI_E_ATTACHMENT_WRITE_FAILURE

An attachment could not be written to a temporary file. Check directory permissions.

MAPI_E_FAILURE

One or more unspecified errors occurred while sending the message. It is not known if the message was sent.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No message was sent.

MAPI_E_USER_ABORT

The user canceled the process. No message was sent.

SUCCESS_SUCCESS

The call succeeded and the message was sent.

Remarks

Calling the MAPISendDocuments function displays a Send Note dialog box, which prompts the user to send a message with data file attachments. Attachments can include the active document or all the currently open documents in the Windows-based application that called MAPISendDocuments. This function is used primarily for calls from a macro or scripting language, often found in applications such as spreadsheet or word-processing programs.

There is no default identification when MAPISendDocuments is called; a standard logon dialog box appears. After the user provides a mailbox name and password, the Send Note dialog box appears.

The user’s default messaging options are used as the default dialog box values. The caller is responsible for deleting temporary files created when using MAPISendDocuments.

The declaration of this function for the 32-bit Visual Basic runtime is:

MAPISendDocuments(

ByVal UIParam&,
ByVal DelimStr$,
ByVal FilePaths$,
ByVal FileNames$,
ByVal Reserved&) As Long


MAPISendMail (VB)

The Visual Basic MAPISendMail function sends a standard message.

Quick Info

Header file:	MAPIVB32.BAS
MAPISendMail(

Session as Long,.
UIParam as Long,
Message as MapiMessage,
Recips as MapiRecip,
Files as MapiFile,
Flags as Long,
Reserved as Long) as Long

Parameters

Session

[in] Session handle that represents a Simple MAPI session or zero. If the value of the Session parameter is zero, MAPI logs on the user and creates a session that exists only for the duration of the call. This temporary session can be an existing shared session or a new one. If necessary, a logon dialog box is displayed.

UIParam

The parent window handle for the dialog box. A value of zero indicates that any dialog box displayed is application modal.

Message

[in] The message to be sent. An empty string indicates no text. Each paragraph should be terminated with either a carriage return (0x0d), a line feed (0x0a), or a carriage return−line feed pair (0x0d0a). The implementation wraps lines as appropriate. Implementations can place limits on the size of the text. The MAPI_E_TEXT_TOO_LARGE value is returned if this limit is exceeded. Client applications can set MAPI_RECEIPT_REQUESTED in the Flags member in the MapiMessage type pointed to by the Message parameter to prompt for a read report.

Recips

[in] The first element of an array of recipients. When the the value of the RecipCount member in the MapiRecip type pointed to by the Message parameter is zero, the Recips parameter is ignored. The Recips parameter can include either an entry identifier, the recipient’s name, an address, or a name and address pair. Depending on the type and amount of information passed, MAPISendMail will perform varied levels of name resolution. If an entry identifier in the EntryID member for a particular recipient is specified, MAPISendMail performs no lookup and ignores the name and address. If only a name is specified, MAPISendMail resolves the name to a valid address using name resolution rules defined by Simple MAPI. If only an address is specified, MAPISendMail uses this address for both message delivery and for displaying the recipient name; no name resolution occurs. If both a name and address are specified, again MAPISendMail does not resolve the name. The specified name is used as the display name and not for resolution.

Files

[in] The first element of an array of attachment files written when the message is read. The number of attachments per message might be limited in some systems. If the limit is exceeded, the MAPI_E_TOO_MANY_FILES value is returned. When the value of the FileCount member in the MapiMessage type pointed to by the Message parameter is zero, the Files parameter is ignored. Attachment files are read and attached to the message before the call returns. Do not attempt to display attachments outside the range of the message text.

Flags

[in] Bitmask of option flags. The following flags can be set:

MAPI_DIALOG

A dialog box should be displayed to prompt the user for recipients and other sending options. Set the MAPI_LOGON_UI flag if MAPISendMail should display a dialog box to prompt the user to log on. When this flag is not set, MAPISendMail does not display a dialog box and returns a message if the user is not logged on.

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user to log on if required. When the MAPI_LOGON_UI flag is not set, the client application does not display a logon dialog box and returns an error value if the user is not logged on. MAPISaveMail ignores this flag if the MessageID parameter is empty.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment’s shared session. If the MAPI_NEW_SESSION flag is not set, MAPISendMail uses an existing shared session.

Reserved

Reserved; must be zero.

Return Values

MAPI_E_AMBIGUOUS_RECIPIENT

A recipient matched more than one of the recipient descriptor structures and MAPI_DIALOG was not set. No message was sent.

MAPI_E_ATTACHMENT_NOT_FOUND

The specified attachment was not found. No message was sent.

MAPI_E_ATTACHMENT_OPEN_FAILURE

The specified attachment could not be opened. No message was sent.

MAPI_E_FAILURE

One or more unspecified errors occurred. No message was sent.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. No message was sent.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No message was sent.

MAPI_E_TEXT_TOO_LARGE

The text in the message was too large. No message was sent.

MAPI_E_TOO_MANY_FILES

There were too many file attachments. No message was sent.

MAPI_E_TOO_MANY_RECIPIENTS

There were too many recipients. No message was sent.

MAPI_E_UNKNOWN_RECIPIENT

A recipient did not appear in the address list. No message was sent.

MAPI_E_USER_ABORT

The user canceled the process. No message was sent.

SUCCESS_SUCCESS

The call succeeded and the message was sent.

Remarks

The MAPISendMail function sends a standard message, with or without any user interaction. If recipient names, file attachments, or message text is provided, MAPISendMail can send the files or note without prompting users. If the optional parameters are specified and a dialog box is requested by use of the MAPI_DIALOG flag, the parameters provide the initial values for the dialog box.

File attachments are copied to the message before MAPISendMail returns; therefore, later changes to the files do not affect the contents of the message. The files must be closed when they are copied.

MAPISendMail takes the recipients and file attachments from the Recips and Files parameters, which should each be the first element of dynamically allocated arrays of their respective types. These arrays are not redimensioned.

All strings must be specified in the current character set or code page of the client application’s operating system process.

The declaration of this function for the 32-bit Visual Basic runtime is:

MAPISendMail(

ByVal Session&,
ByVal UIParam&,
message As MAPIMessage,
Recipient() As MapiRecip,
File() As MapiFile,
ByVal Flags&,
ByVal Reserved&) As Long


Data Types for Visual Basic

Visual Basic uses a different set of calling and programming conventions than C and C++ use. Different structure and parameter definitions support the Visual Basic representation of strings and of structures, which in Visual Basic are called types. The following list describes how programming Simple MAPI Visual Basic applications differs from programming Simple MAPI C and C++ applications:

•	In C and C++, structures can contain pointers to other structures. Because the concept of a pointer is foreign to Visual Basic, extra function parameters are used instead of these complex structures.

•	Because the Visual Basic MAPI functions are declared, it is not necessary to explicitly cast passed arguments using ByVal.

•	An empty string in a string variable is equivalent to a NULL value.

•	Arrays must be dynamically declared so that they are redimensioned when the Simple MAPI function is executed.

•	Visual Basic manages memory, eliminating the need to call the MAPIFreeBuffer function.

•	All structures used in the Visual Basic version of Simple MAPI are Visual Basic types rather than C-language structures.

•	All strings used in the Visual Basic version of Simple MAPI are Visual Basic strings rather than C-language strings.

The following alphabetized entries contain documentation for the Visual Basic Data Types


MapiFile (VB)

The Visual Basic MapiFile type contains file attachment information.

Quick Info

Header file:	MAPIVB32.BAS
Type MapiFile
     Reserved as Long
     Flags as Long
     Position as Long
     PathName as String
     FileName as String
     FileType as String
End Type

Members

Reserved

Reserved; must be zero.

Flags

Bitmask of flags. The following flags can be set:

MAPI_OLE

The attachment is an OLE object file attachment. If MAPI_OLE_STATIC is also set, the object is static. If neither flag is set, the attachment is simply a data file.

MAPI_OLE_STATIC

The attachment is a static OLE object file attachment.

Position

An integer used to determine where the attachment should be placed in the message text. Attachments replace the character found at a certain position in the message text; in other words, attachments replace the MapiMessage member NoteText[Position]. Applications cannot place two attachments in the same location within a message, and attachments cannot be placed beyond the end of the message text. MAPIReadMail does not return an attachment with the value of Position equal to −1 unless the MAPI_BODY_AS_FILE flag is set.

PathName

The full path of the attached file. The file should be closed before this call is made.

FileName

The filename seen by the recipient. This name can differ from the filename in the PathName member if temporary files are being used. If the FileName member is empty, the filename from PathName is used. If the attachment is an OLE object, FileName contains the class name of the object, such as “Microsoft Excel Worksheet.”

FileType

A reserved descriptor that indicates to the recipient the type of the attached file. An empty string indicates an unknown or operating system−determined file type. With this release, you must use an empty string, "", for this parameter.

Remarks

Simple MAPI for Visual Basic supports the following kinds of attachments:

•	Data files

•	Embedded OLE objects

•	Static OLE objects

The Flags member determines the kind of attachment. OLE object files are file representations of OLE object streams. You can re-create an OLE object from the file by calling the OLE function OleLoadFromStream with an OLESTREAM object that reads the file contents. If an OLE file attachment is included in an outbound message, the OLE object stream should be written directly to the file used as the attachment.


MapiMessage (VB)

The Visual Basic MapiMessage type contains message information.

Quick Info

Header file:	MAPIVB32.BAS
Type MapiMessage
     Reserved as Long
     Subject as String
     NoteText as String
     MessageType as String
     DateReceived as String
     ConversiondID as String
     Flags as Long
     Originator as Long
     RecipCount as Long
     FileCount as Long
End Type

Members

Reserved

Reserved; must be zero.

Subject

The subject text, limited to 256 characters or less. Messages saved with the MAPISaveMail function are not limited to 256 characters. An empty string indicates no subject text.

NoteText

A string containing text in the message. An empty string indicates no text. For inbound messages, each paragraph is terminated with a carriage return−line feed pair (0x0d0a). For outbound messages, paragraphs can be delimited with a carriage return, a line feed, or a carriage return−line feed pair (0x0d, 0x0a, or 0x0d0a).

MessageType

A message type string used by applications other than interpersonal electronic mail. An empty string indicates an interpersonal message (IPM) type.

DateReceived

A string indicating the date a message is received. The format is YYYY/MM/DD HH:MM; hours are measured on a 24-hour clock.

ConversationID

A string indicating the conversation thread identifier to which this message belongs.

Flags

Bitmask of flags. The following flags can be set:

MAPI_RECEIPT_REQUESTED

A receipt notification is requested.

MAPI_SENT

The message has been sent.

MAPI_UNREAD

The message has not been read.

Originator

A MapiFile type describing the sender of the message.

RecipCount

A count of the recipient descriptor types. A value of 0 indicates that no recipients are included.

FileCount

A count of the file attachment descriptor types. A value of 0 indicates that no file attachments are included.


MapiRecip (VB)

The Visual Basic MAPIRecip type contains recipient information.

Quick Info

Header file:	MAPIVB32.BAS
Type MapiRecip
     Reserved as Long
     RecipClass as Long
     Name as String
     Address as String
     EIDSize as Long
     EntryID as String
End Type

Members

Reserved

Reserved; must be zero.

RecipClass

Classifies the recipient of the message. (Messages can be sorted by recipient class.) This member can also contain information about the originator of an inbound message.

Name

The name of the recipient that is displayed by the messaging system.

Address

Provider-specific message delivery data. This can be used by the messaging system to identify custom recipients who are not in an address list.

EIDSize

The size, in bytes, of the data in the EntryID member.

EntryID

A string used by the messaging system to uniquely identify the recipient. Unlike the contents of the Address member, this data is opaque and is not printable. The messaging system returns valid EntryID members for recipients or senders included in the address list.


MAPI Structures

The following alphabetized entries describe MAPI structures. For more detailed information, cross references to other publications or to other topics in this documentation are also included.


ADRENTRY

The ADRENTRY structure describes zero or more properties belonging to a recipient.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _ADRENTRY

{

     ULONG        ulReserved1;

     ULONG        cValues;

     LPSPropValue rgPropVals;

} ADRENTRY, FAR *LPADRENTRY;

Members

ulReserved1

Reserved; must be zero.

cValues

Count of properties in the property value array pointed to by the rgPropVals member. The cValues member can be zero.

rgPropVals

Pointer to a property value array describing the properties for the recipient. The rgPropVals member can be NULL.

Remarks

An ADRENTRY structure describes properties belonging to a single recipient. The properties that are typically used to describe a recipient include:

PR_DISPLAY_NAME

PR_ADDRTYPE

PR_EMAIL_ADDRESS

PR_ENTRYID

When an entry identifier — or PR_ENTRYID property — appears in the SPropValue array for a recipient, this indicates that the recipient has been resolved. Clients call the IAddrBook::ResolveName method to ensure that all recipients in the recipient list of an outgoing message have been resolved. Only resolved recipients can be sent with messages.

ADRENTRY structures are commonly combined to form an array for the aEntries member of an ADRLIST structure.

ADRENTRY structures and SRow structures are identical in that they both contain a reserved member, an array of property values, and a count of values in the array. Whereas ADRENTRY structures are combined to form the aEntries member of an ADRLIST structure, SRow structures are combined to form the aRow member of an SRowSet structure. Both types of structures follow the same allocation rules, implying that an SRowSet structure that is retrieved from the contents table of an address book container can be cast to an ADRLIST structure and used as is.

An ADRENTRY structure can be empty. An ADRENTRY structure contained in the ADRLIST structure pointed to by the lppAdrList parameter in a call to IAddrBook::Address can be empty when, for example, a recipient is being removed.

For more information on allocating memory for ADRENTRY structures, see Managing Memory for ADRLIST and SRowSet Structures.

See Also

IAddrBook::Address, IMessage::ModifyRecipients, MAPIAllocateBuffer, SRow


ADRLIST

The ADRLIST structure describes zero or more properties belonging to one or more recipients.

Quick Info

Header file:	MAPIDEFS.H
Related macros:	CbADRLIST CbNewADRLIST SizedADRLIST
typedef struct _ADRLIST

{

     ULONG      cEntries;

     ADRENTRY   aEntries[MAPI_DIM];

} ADRLIST, FAR *LPADRLIST;

Members

cEntries

Count of entries in the array specified by the aEntries member.

aEntries

Array of ADRENTRY structures, one structure for each recipient.

Remarks

An ADRLIST structure contains one or more ADRENTRY structures, each describing the properties of a recipient. A recipient can be unresolved, meaning that it is lacking an entry identifier in its array of property values, or resolved, meaning that the PR_ENTRYID property is included. Typically, resolved recipients also have an e-mail address — the PR_EMAIL_ADDRESS property. However, the e-mail address is not required. ADRLIST structures are used, for example, to describe the recipient list for an outgoing message and by MAPI to display the entries in the address book.

ADRLIST structures resemble SRowSet structures — the structures used for representing rows in tables. In fact, these two structures are designed so that they can be used interchangeably. Both contain an array of structures describing a group of properties and a count of the values in the array. Whereas in the ADRLIST structure, the array contains ADRENTRY structures, in the SRowSet structure the array contains SRow structures. ADRENTRY structures and SRow structures are identical in layout. Because ADRLIST and SRowSet structures follow the same allocation rules, an SRowSet structure that is retrieved from the contents table of an address book container can be cast to an ADRLIST structure and used as is.

The following diagram illustrates the layout of an ADRLIST structure.

The ADRENTRY and SPropValue portions in an ADRLIST structure can be allocated and freed independently of the other parts. That is, each SPropValue structure can be allocated individually after memory for the ADRENTRY structure has been allocated and freed before the ADRENTRY structure is freed. This independence in handling memory allows recipients and individual recipient properties to be freely added or deleted from the address list.

If a recipient list is too large to fit in memory, clients can call the IMessage::ModifyRecipients method to work with a subset of the list. Clients should not use the address book common dialog boxes in such a situation.

For more information on allocating memory for ADRENTRY structures, see Managing Memory for ADRLIST and SRowSet Structures.

See Also

ADRENTRY, CbNewADRLIST, IMessage::ModifyRecipients, SRowSet


ADRPARM

The ADRPARM structure describes the display and behavior of the common address dialog box.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _ADRPARM

{

     ULONG            cbABContEntryID;

     LPENTRYID        lpABContEntryID;

     ULONG            ulFlags;

     LPVOID           lpReserved;

     ULONG            ulHelpContext;

     LPTSTR           lpszHelpFileName;

     LPFNABSDI        lpfnABSDI;

     LPFNDISMISS      lpfnDismiss;

     LPVOID           lpvDismissContext;

     LPTSTR           lpszCaption;

     LPTSTR           lpszNewEntryTitle;

     LPTSTR           lpszDestWellsTitle;

     ULONG            cDestFields;

     ULONG            nDestFieldFocus;

     LPTSTR FAR      *lppszDestTitles;

     ULONG FAR       *lpulDestComps;

     LPSRestriction   lpContRestriction;

     LPSRestriction   lpHierRestriction;

} ADRPARM, FAR *LPADRPARM;

Members

cbABContEntryID

Count of bytes in the entry identifier pointed to by lpABContEntryID.

lpABContEntryID

Pointer to the entry identifier of the container that initially supplies the list of recipient addresses that are displayed in the address dialog box.

ulFlags

Bitmask of flags associated with various address dialog box options. The following flags can be set:

AB_RESOLVE

Causes all names to be resolved after the address dialog box is closed. If there are ambiguous entries resulting from the name resolution process, a dialog box is displayed to prompt the user for help in resolving them.

AB_SELECTONLY

Disables the creation of one-off addresses and direct type-in entries for a recipient list. This flag is used only if the dialog box is modal, as indicated by the DIALOG_MODAL flag being set.

ADDRESS_ONE

The user can select exactly one recipient instead of multiple recipients from a list. This flag is valid only when cDestFields is zero and the dialog box is modal, as indicated by the DIALOG_MODAL flag being set.

DIALOG_MODAL

Causes the modal version of the common address dialog box to be displayed. Either this flag or DIALOG_SDI should be set; they cannot both be set.

DIALOG_OPTIONS

Causes the Send Options button to be displayed on the dialog box. This flag is used only if the dialog box is modal, as indicated by the DIALOG_MODAL flag being set.

DIALOG_SDI

Causes the modeless version of the common address dialog box to be displayed. Either this flag or DIALOG_MODAL should be set; they cannot both be set.

lpReserved

Reserved, must be zero.

ulHelpContext

Specifies the context within Help that will first be shown when the user clicks the Help button in the address dialog box.

lpszHelpFileName

Pointer to the name of a Help file that will be associated with the address dialog box. The lpszHelpFileName member is used in conjunction with ulHelpContext to call the Windows WinHelp function.

lpfnABSDI

Pointer to a MAPI function based on the ACCELERATEABSDI prototype or NULL. This member applies to the modeless version of the dialog box only, as indicated by the DIALOG_SDI flag being set.

Clients building an ADRPARM structure to pass to IAddrBook::Address must always set the lpfnABSDI member to NULL. If the DIALOG_SDI flag is set, MAPI will then set it to a valid function before returning. Clients call this function from within their message loop to insure that accelerators in the address book dialog box work. When the dialog box is dismissed and MAPI calls the function pointed to by the lpfnDismiss member, clients should unhook the ACCELERATEABSDI function from their message loop.

lpfnDismiss

Pointer to a function based on the DISMISSMODELESS prototype or NULL. This member applies only to the modeless version of the dialog box only, as indicated by the DIALOG_SDI flag being set. MAPI calls the DISMISSMODELESS function when the user dismisses the modeless address dialog box, informing a client calling IAddrBook::Address that the dialog box is no longer active.

lpvDismissContext

Pointer to context information to be passed to the DISMISSMODELESS function pointed to by the lpfnDismiss member. This member applies only to the modeless version of the dialog box, as indicated by the DIALOG_SDI flag being set.

lpszCaption

Pointer to text to be used as the title for the common address dialog box.

lpszNewEntryTitle

Pointer to text to be used as the button label for the button that invokes either the New Entry dialog box or another dialog box.

lpszDestWellsTitle

Pointer to text to be used as a title for the recipient edit box controls that can appear in the modal version of the common address dialog box. This member is not used for modeless dialog boxes.

cDestFields

Count of recipient edit box controls in the modal version of the address dialog box, or zero if the dialog box is modeless. The address dialog box is open for browsing only when:

•	The cDestFields member is set to zero.

•	The DIALOG_BOX flag is set.

•	The ADDRESS_ONE flag is not set.

Setting cDestFields to 0XFFFFFFFF implies that MAPI should create the default number of recipient edit box controls. In this case, the lppszDestTitles and lpulDestComps members must be NULL.

nDestFieldFocus

Indicates the particular edit box control that should have the initial focus when the modal version of the dialog box appears. This value must be between 0 and the value of cDestFields minus 1.

lppszDestTitles

Pointer to an array of labels for buttons associated with each of the edit box controls that are displayed in the modal version of the address dialog box. The value of the cDestFields member indicates the number of labels included in the array. If the lppszDestTitles member is NULL, the Address method chooses default titles.

lpulDestComps

Pointer to an array of recipient type values, such as MAPI_TO, MAPI_CC, and MAPI_BCC, that is associated with each edit box control. The value of the CDestFields member indicates the number of recipient types included in the array. The values pointed to by lpulDestComps can be used to set the PR_RECIPIENT_TYPE property of each recipient. If the lpulDestComps member is NULL, the Address method chooses default recipient types.

lpContRestriction

Pointer to an SRestriction structure that limits the type of address entries that can be displayed in the dialog box.

lpHierRestriction

Pointer to an SRestriction structure that limits the address book containers that can supply address entries to be displayed in the dialog box.

Remarks

ADRPARM structures are used by clients and service providers to control the appearance and behavior of the MAPI common address dialog boxes. There are two varieties of the address dialog box: modeless and modal. Some of the members in the ADRPARM structure apply to both versions of the dialog box, but some only apply to one of the two versions. The following table relates the members of an ADRPARM structure to their use with the common address dialog boxes.

ADRPARM member	Type of dialog box
cbABContEntryID and lpABContEntryID	Modal and modeless
ulFlags	Modal and modeless
lpReserved	Modal and modeless
ulHelpContext and lpszHelpFileName	Modal and modeless
lpfnABSDI	Modeless
lpfnDismiss and lpvDismissContext	Modeless
lpszCaption	Modal and modeless
lpszNewEntryTitle	Modal
lpszDestWellsTitle, cDestFields, nDestFieldFocus, lppszDestTitles, and lpulDestComps	Modal
lpContRestriction	Modal and modeless
lpHierRestriction	Modal and modeless
The modeless dialog box is a read-only display of entries from one or more address book containers. The dialog box can display all entries from the selected containers or be limited to only those entries and containers that match criteria established by a restriction. The contents restriction pointed to by lpContRestriction can limit the types of entries displayed and the hierarchy restriction pointed to by lpHierRestriction can limit the containers providing the entries. To inform the caller when the dialog box has been dismissed, MAPI invokes a function provided by the caller that conforms to the DISMISSMODELESS prototype. Another function, one that conforms to the ACCELERATEABSDI prototype, is provided by MAPI and invoked by the caller in the Windows message loop to facilitate the working of accelerator keys. The modeless version of the MAPI address dialog box can be displayed when clients call IAddrBook::Address or when service providers call IMAPISupport::Address.

The following illustration shows the modeless address dialog box.

The modal dialog box is a read/write display of entries from one or more containers. Its contents can be affected in the same way as can the modeless version — by restrictions set in the lpContRestriction and lpHierRestriction members. In addition to the list box displaying container entries, the modal dialog box can contain between one and three edit box controls for holding entries selected by the user. Each edit control is associated with a particular recipient type — or PR_RECIPIENT_TYPE property — such as MAPI_TO. The modal address dialog box can be displayed by either of the Address methods or when clients call IAddrBook::Details and service providers call IMAPISupport::Details.

The following illustration shows the modal address dialog box.

This illustration includes two edit box controls because the cDestFields member of the ADRPARM structure controlling the display of this dialog box is set to 2. The first control has initial focus because the nDestFieldFocus member is set to 0.

The lpszNewEntryTitle member points to text for a button label that, when selected, causes an additional dialog box to be displayed. Typically, as is shown in the illustration of the modal dialog box, the button is labeled New and the dialog box that is displayed lists all of the types of addresses that can be created by any of the address book providers in the profile. Clients cause this New Entry dialog box to be displayed by calling  IAddrBook::NewEntry and passing zero for the cbEidNewEntryTpl parameter and NULL for the lpEidNewEntryTpl parameter when the user selects the button. The information included in this dialog box comes from the MAPI one-off table.

The following illustration shows the appearance of the New Entry dialog box.

Every entry in this dialog box is associated with a template for entering the data required to create an address of the particular type. Most address book providers supply one template for every type of address entry they can create. When a user makes a selection from this dialog box, MAPI displays the corresponding template.

The most significant four bits of the ADRPARM structure’s ulFlags member contain a version number identifying the version of the ADRPARM structure. The current version is 0 (zero) — or ADRPARM_HELP_CTX. The current implementation of MAPI will fail for any version of the structure other than zero.

Future versions of the structure may be completely different; they may or may not support the version-zero structure. The following macros are provided for extracting the version number from the ulFlags member and for combining it with the defined flags:

GET_ADRPARM_VERSION(ulFlags)

SET_ADRPARM_VERSION(ulFlags, ulVersion)

ADRPARM_HELP_CTX

See Also

ACCELERATEABSDI, DISMISSMODELESS, IAddrBook::Address, IMAPISupport::Address, SRestriction


CURRENCY

The CURRENCY structure contains a signed 64-bit integer representing a currency value.

Quick Info

Header file:	MAPIDEFS.H
typedef struct tagCY

{

     unsigned long Lo;

     long     Hi;

} CURRENCY;

Members

Lo

Low-order 32 bits of the currency value.

Hi

High-order 32 bits of the currency value.

Remarks

The CURRENCY value is construed as a signed decimal number with four digits to the right of the decimal point.

See Also

SPropValue


DTBLBUTTON

The DTBLBUTTON structure contains information about a button control for a dialog box built from a display table.

Quick Info

Header file:	MAPIDEFS.H
Related macro:	SizedDtblButton
typedef struct _DTBLBUTTON

{

     ULONG ulbLpszLabel;

     ULONG ulFlags;

     ULONG ulPRControl;

} DTBLBUTTON, FAR *LPDTBLBUTTON;

Members

ulbLpszLabel

Position in memory of the character string that is displayed on the button.

ulFlags

Bitmask of flags used to designate the format of the label pointed to by the ulbLpszLabel member. The following flag can be set:

MAPI_UNICODE

The label is in Unicode format. If the MAPI_UNICODE flag is not set, the label is in ANSI format.

ulPRControl

Property tag for a property of type PT_OBJECT that implements the IMAPIControl interface. When the button is clicked, MAPI calls the OpenProperty method for the display table’s IMAPIProp implementation to retrieve this property.

Remarks

A DTBLBUTTON structure describes a button — a control that, when clicked, allows a user to begin an operation. Typically, clicking a button causes a modal dialog box to be displayed or a programmatic task to be invoked. Service providers can implement anything through a button control. If the button is supposed to perform a task based on the values of other controls, those controls must have set the DT_SET_IMMEDIATE flag.

The ulbLpszLabel member is the position in memory of the character string that is displayed on the button. Service providers can add an ampersand character (&) to indicate a Windows accelerator in the button label. Typing an accelerator has the same effect as clicking the button.

The ulPRControl member describes an object property that, when opened with the IMAPIProp::OpenProperty method, returns a pointer to a control object. Implementing a control object — an object that supports the IMAPIControl interface — is a way to extend the MAPI feature set and define the operation or task that occurs when the button is clicked. IMAPIControl supplies two methods for manipulating buttons: GetState to disable or enable buttons and Activate to handle button clicks.

For an overview of display tables, see Display Tables. For information about implementing a display table, see Implementing a Display Table.

See Also

DTCTL, PR_CONTROL_TYPE


DTBLCHECKBOX

The DTBLCHECKBOX structure contains information about a check box to be used in a dialog box built from a display table.

Quick Info

Header file:	MAPIDEFS.H
Related macro:	SizedDtblCheckBox
typedef struct _DTBLCHECKBOX

{

     ULONG ulbLpszLabel;

     ULONG ulFlags;

     ULONG ulPRPropertyName;

} DTBLCHECKBOX, FAR *LPDTBLCHECKBOX;

Members

ulbLpszLabel

Position in memory of the character string that is displayed with the check box.

ulFlags

Bitmask of flags used to designate the format of the check box label. The following flag can be set:

MAPI_UNICODE

The label is in Unicode format. If the MAPI_UNICODE flag is not set, the label is in ANSI format.

ulPRPropertyName

Property tag for a property of type PT_BOOLEAN. The value of this property is affected by the state of the check box.

Remarks

A DTBLCHECKBOX structure describes a check box — a control that reflects one of two states: enabled (a checked box) or disabled (an empty box).

The ulPRPropertyName member describes a Boolean property whose value is manipulated by changing the state of the check box. When the check box is first displayed, MAPI calls the GetProps method of the IMAPIProp implementation that is associated with the display table to retrieve a set of default properties. If one of the properties maps to the property tag in the DTBLCHECKBOX structure, the value for that property is displayed as the check box’s initial value.

Check box controls can be modifiable, allowing a user to change their states. Modifiable check boxes set the DT_EDITABLE flag in the ulCtlFlags member of their DTCTL structure and in their PR_CONTROL_FLAGS property. When a check box changes its state, MAPI calls IMAPIProp::SetProps to set the property identified in the property tag member of the DTBLCHECKBOX structure to the new state.

For example, an address book provider might include a modifiable check box control in its configuration dialog box to manipulate the setting of a recipient’s PR_SEND_RICH_INFO property. When the user selects the check box, MAPI sets this property to TRUE. When the check box is unselected, the property is set to FALSE.

For an overview of display tables, see Display Tables. For information about implementing a display table, see Implementing a Display Table.

See Also

DTCTL, PR_CONTROL_TYPE


DTBLCOMBOBOX

The DTBLCOMBOBOX structure describes a combo box control to be used in a dialog box built from a display table.

Quick Info

Header file:	MAPIDEFS.H
Related macro:	SizedDtblComboBox
typedef struct _DTBLCOMBOBOX

{

     ULONG ulbLpszCharsAllowed;

     ULONG ulFlags;

     ULONG ulNumCharsAllowed;

     ULONG ulPRPropertyName;

     ULONG ulPRTableName;

} DTBLCOMBOBOX, FAR *LPDTBLCOMBOBOX;

Members

ulbLpszCharsAllowed

An offset from the beginning of the DTBLCOMBOBOX structure to a character string filter that describes restrictions, if any, to the characters that can be entered into the combo box’s edit control.

The filter is not interpreted as a regular expression and the same filter is applied to every character entered.The format of the filter is as follows:

*	 	Any character is allowed (for example, “*”).

[  ] 	Defines a set of characters (for example, “[0123456789]”).

-	 	Indicates a range of characters (for example, “[a-z]”).

~	 	Indicates that these characters are not allowed. (for example, “[~0-9]”).

\	 	Used to quote any of the above symbols (for example, “[\-\\\[\]]” means -, \, [, and ] characters are allowed).

ulFlags

Bitmask of flags used to designate the format of the character string filter. The following flag can be set:

MAPI_UNICODE

The filter is in Unicode format. If the MAPI_UNICODE flag is not set, the filter is in ANSI format.

ulNumCharsAllowed

Maximum number of characters that can be entered in the combo box’s edit box.

ulPRPropertyName

Property tag for a property of type PT_TSTRING.

ulPRTableName

Property tag for a property of type PT_OBJECT on which an IMAPITable interface can be opened using an OpenProperty call. The table must have one column with a property that is the same type as the property identified by the ulPRPropName member. The rows of the table are used to populate the list box.

Remarks

A DTBLCOMBOBOX structure describes a combo box — a control that consists of a list box and a selection field. The list box presents the information from which a user can select, and the selection field displays the current selection. The selection field is an edit control that can also be used to enter text not already in the list.

The following dialog box includes an example of a combo box.

The two property tag members work together to coordinate the list box display with the edit control. When MAPI first displays the combo box, it calls the OpenProperty method of the IMAPIProp implementation that is associated with the display table to retrieve the table represented by the ulPRTableName member. This table has one column — a column that contains values for the property represented by the ulPRPropertyName member. Therefore, this column must be of the same type as the ulPRPropertyName property and both columns must be character strings.

The values for the column are displayed in the list box portion of the combo box. Therefore, PR_NULL is not a valid property tag for ulPRPropertyName. When a user either selects one of the rows or enters new data into the edit box, the ulPRPropertyName property is set to the selected or entered value.

To display an initial value for the edit control, MAPI calls IMAPIProp::GetProps to retrieve the property values for the display table. If one of the retrieved properties matches the property represented by the ulPRPropertyName member, its value becomes the initial value.

For an overview of display tables, see Display Tables. For information about implementing a display table, see Implementing a Display Table.

See Also

DTCTL, PR_CONTROL_TYPE


DTBLDDLBX

The DTBLDDLBX structure describes a drop-down list box control to be used in a dialog box built from a display table.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _DTBLDDLBX

{

     ULONG ulFlags;

     ULONG ulPRDisplayProperty;

     ULONG ulPRSetProperty;

     ULONG ulPRTableName;

} DTBLDDLBX, FAR *LPDTBLDDLBX;

Members

ulFlags

Reserved, must be zero.

ulPRDisplayProperty

Property tag for a property of type PT_TSTRING. This property is one of the columns in the table identified by the ulPRTableTable member. The values for this property are displayed in the list box.

ulPRSetProperty

Property tag for a property of any type. This property is one of the columns in the table identified by the ulPRTableTable member. When the user of the list box selects a property value for the ulPRDisplayProperty member from the rows of the table identified by the ulPRTableName member, the corresponding ulPRSetProperty member is set.

ulPRTableName

Property tag for a table property of type PT_OBJECT that can be opened using an OpenProperty call. The table should have two columns: ulPRDisplayProperty and ulPrSetProperty. The rows of the table should correspond to items in the list box.

Remarks

A DTBLDDLBX structure describes a drop-down list box — a list box control that is displayed as a single item until the user elects to expand it. The following illustration provides an example of a drop-down list box.

The three properties identified by the property tags work together to display the information in the list box and set a related property. The ulPRTableName member is a table object that is accessed through a call to IMAPIProp::OpenProperty. The table has two columns: one column for the property identified by the ulPRDisplayProperty member and the other for the property identified by the ulPRSetProperty member.

The ulPRDisplayProperty property drives the list box display. When a user selects one of the values from the display, MAPI calls IMAPIProp::SetProps to set the corresponding property as identified by the ulPRSetProperty member, meaning the property in the same row as the selected display property. The ulPRSetProperty member cannot be set to PR_NULL.

An initial value is displayed in the list box if MAPI has retrieved the property represented by the ulPRSetProperty member through a call to IMAPIProp::GetProps and located a row in the table with the value for the ulPRSetProperty member. The initial displayed value is the contents of the ulPRDisplayProperty column from that row that matches the property in the ulPRDisplayProperty member of the structure. The value returned by GetProps for the property identified by the ulPRDisplayProperty member becomes the initial value that is shown when the list box is first displayed.

For an overview of display tables, see Display Tables. For information about implementing a display table, see Implementing a Display Table.

See Also

DTCTL


DTBLEDIT

The DTBLEDIT structure describes an edit control to be used in a dialog box built from a display table.

Quick Info

Header file:	MAPIDEFS.H
Related macro:	SizedDtblEdit
typedef struct _DTBLEDIT

{

     ULONG ulbLpszCharsAllowed;

     ULONG ulFlags;

     ULONG ulNumCharsAllowed;

     ULONG ulPropTag;

} DTBLEDIT, FAR *LPDTBLEDIT;

Members

ulbLpszCharsAllowed

An offset from the beginning of the DTBLEDIT structure to a character string filter that describes restrictions, if any, to the characters that can be entered into the edit control.

The filter is not interpreted as a regular expression and the same filter is applied to every character entered.The format of the filter is as follows:

*	 	Any character is allowed (for example, “*”).

[  ] 	Defines a set of characters (for example, “[0123456789]”).

-	 	Indicates a range of characters (for example, “[a-z]”).

~	 	Indicates that these characters are not allowed (for example, “[~0-9]”).

\	 	Used to quote any of the above symbols (for example, “[\-\\\[\]]” means -, \, [, and ] characters are allowed).

ulFlags

Bitmask of flags used to designate the format of the character filter. The following flag can be set:

MAPI_UNICODE

The filter is in Unicode format. If the MAPI_UNICODE flag is not set, the filter is in ANSI format.

ulNumCharsAllowed

Maximum number of characters that the user can type into the edit box.

ulPropTag

Property tag for a property of type PT_TSTRING. The ulPropTag member identifies the string property whose data is displayed and edited in the edit control.

Remarks

A DTBLEDIT structure describes an edit control — an area on a dialog box that contains alphanumeric information. Almost all dialog boxes have at least one edit control. Edit controls can be modifiable by a user or read-only.

Edit controls can also be single line or multiline. Multiline edit controls typically have a scroll bar associated with them as shown in the following illustration.

For an overview of display tables, see Display Tables. For information about implementing a display table, see Implementing a Display Table.

See Also

DTCTL, IMAPIProp::GetProps, PR_CONTROL_TYPE


DTBLGROUPBOX

The DTBLGROUPBOX structure describes a group box control to be used in a dialog box that is built from a display table.

Quick Info

Header file:	MAPIDEFS.H
Related macro:	SizedDtblGroupBox
typedef struct _DTBLGROUPBOX

{

     ULONG ulbLpszLabel;

     ULONG ulFlags;

} DTBLGROUPBOX, FAR *LPDTBLGROUPBOX;

Members

ulbLpszLabel

Position in memory of the character string that accompanies the group box. If displayed, the label appears on the top, left-hand side of the box.

ulFlags

Bitmask of flags used to designate the format of the label pointed to by the ulbLpszLabel member. The following flag can be set:

MAPI_UNICODE

The label is in Unicode format. If the MAPI_UNICODE flag is not set, the label is in ANSI format.

Remarks

A DTBLGROUPBOX structure describes a group box — a control that is used to visually associate other controls in the dialog box. The highlighting technique involves surrounding the other controls by a box, as illustrated in the following dialog box.

For an overview of display tables, see Display Tables. For information about implementing a display table, see Implementing a Display Table.

See Also

DTCTL


DTBLLABEL

The DTBLLABEL structure describes a label to be used in a dialog box that is built from a display table.

Quick Info

Header file:	MAPIDEFS.H
Related macro	SizedDtblLabel
typedef struct _DTBLLABEL

{

     ULONG ulbLpszLabelName;

     ULONG ulFlags;

} DTBLLABEL, FAR *LPDTBLLABEL;

Members

ulbLpszLabelName

Position in memory of the character string label.

ulFlags

Bitmask of flags used to designate the format of the label pointed to by the ulbLpszLabelName member. The following flag can be set:

MAPI_UNICODE

The label is in Unicode format. If the MAPI_UNICODE flag is not set, the label is in ANSI format.

Remarks

A DTBLLABEL structure describes a label control — text that is displayed with another type of control to add meaning to that control. For example, most edit controls are placed next to labels to inform the user of the type of information to be entered. Some controls, such as group boxes and radio buttons, hold their own labels.

The label can include a Windows accelerator, identified as the character following the ampersand (&). Typing the accelerator character puts the focus in the first non-label, non-button control following this label in the display table.

There is no support for multiline labels. Showing multiple lines requires multiple labels.

It is not possible to use a label as a read-only edit control. The distinction is that an edit control can be selected and copied while a label cannot.

For an overview of display tables, see Display Tables. For information about implementing a display table, see Implementing a Display Table.

See Also

DTCTL


DTBLLBX

The DTBLLBX structure describes a list box to be used in a dialog box that is built from a display table.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _DTBLLBX

{

     ULONG ulFlags;

     ULONG ulPRSetProperty;

     ULONG ulPRTableName;

} DTBLLBX, FAR *LPDTBLLBX

Members

ulFlags

Bitmask of flags used to eliminate a horizontal or vertical scroll bar from the list box. The following flags can be set:

MAPI_NO_HBAR

No horizontal scroll bar should be shown with the list box.

MAPI_NO_VBAR

No vertical scroll bar should be shown with the list box.

ulPRSetProperty

Property tag for a property of any type. This property is one of the columns in the table identified by the ulPRTableTable member.

ulPRTableName

Property tag for a table property of type PT_OBJECT that can be opened using an OpenProperty call. The number of columns that the table should have depends on whether or not the list box is a single or multiple selection list box. If the ulPRSetProperty member is set to PR_NULL, the list box allows multiple selection.

Remarks

A DTBLLBX structure describes a list box — a control that is used to show multiple items and allow a user to select one or more of the items.

The ulPRSetProperty member and ulPRTableName member work together; when one value is chosen from the table, it is written back to ulPRSetProperty when the dialog is dismissed.

The flags value indicates whether or not a horizontal or vertical scroll bar should be displayed with the list box. The default is to have types of scroll bars appear if necessary. Service providers can set MAPI_NO_HBAR to suppress a horizontal scroll bar and MAPI_NO_VBAR to suppress a vertical scroll bar.

The two property tag members work together to display values in the list box and set corresponding properties when an item in the list box is selected. When MAPI first displays the list box, it calls the IMAPIProp implementation’s OpenProperty method to retrieve the table identified in the ulPRTableName member. The number of columns in the table depends on the value of the ulPRSetProperty member. If ulPRSetProperty is set to PR_NULL, the list box is a multiple selection list box based on an object that contains recipients, such as an address book container, a recipient table for a message, or a distribution list contents table.

A table for a multiple selection list box must include the following columns:

PR_DISPLAY_NAME

PR_ENTRYID

PR_INSTANCE_KEY

PR_DISPLAY_TYPE and a maximum of five other multivalued string properties can also be displayed with the three required columns.

If the ulPRSetProperty member is not set to PR_NULL, the list box is a single selection list box. The initial value of ulPRSetProperty determines the initially selected row. When a user selects one of the rows, the ulPRSetProperty member is set to the selected value and this value is written back to the property interface implementation with a call to IMAPIProp::SetProps.

For an overview of display tables, see Display Tables. For information about implementing a display table, see Implementing a Display Table.

See Also

DTCTL


DTBLMVDDLBOX

The DTBLMVDDLBOX structure describes a drop-down list box to be used in a dialog box that is built from a display table.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _DTBLMVDDLBX

{

     ULONG ulFlags;

     ULONG ulMVPropTag;

} DTBLMVDDLBX, FAR * LPDTBLMVDDLBX;

Members

ulFlags

Reserved; must be zero.

ulMVPropTag

Property tag for a multivalued property of type PT_MV_TSTRING. The different values of this property are displayed as distinct entries in the drop-down list box.

Remarks

A DTBLMVDDLBOX structure describes a multivalued drop-down list box — a read-only list of items. With a multivalued drop-down list box, values are displayed when a user clicks on a scroll bar.

The data that is displayed comes from the property identified in the ulMVPropTag member. There is no need to read from the property interface that is associated with the display table. Also, because users are not allowed to make selections from these types of list boxes, data is not written to the property interface.

Only multivalued string properties are supported for the multivalued drop-down list box; other multivalued property types are not supported.

For an overview of display tables, see Display Tables. For information about implementing a display table, see Implementing a Display Table.

See Also

DTCTL


DTBLMVLISTBOX

The DTBLMVLISTBOX structure describes a multivalued list box to be displayed in a dialog box that is built from a display table.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _DTBLMVLISTBOX

{

     ULONG ulFlags;

     ULONG ulMVPropTag;

} DTBLMVLISTBOX, FAR * LPDTBLMVLISTBOX;

Members

ulFlags

Reserved; must be zero.

ulMVPropTag

Property tag for a multivalued property of type PT_MV_TSTRING.

Remarks

A DTBLMVLISTBOX structure describes a standard multivalued list box — a read-only list of items. With a standard multivalued list box, the values are displayed immediately.

The data that is displayed comes from the property identified in the ulMVPropTag member. There is no need to read from the property interface that is associated with the display table. Also, because users are not allowed to make selections from these types of list boxes, data is not written to the property interface.

Only multivalued string properties are supported for the multivalued list box; other multivalued property types are not supported.

For an overview of display tables, see Display Tables. For information about implementing a display table, see Implementing a Display Table.

See Also

DTCTL


DTBLPAGE

The DTBLPAGE structure describes a tabbed page to be used in a dialog box that is built from a display table.

Quick Info

Header file:	MAPIDEFS.H
Related macro:	SizedDtblPage
typedef struct _DTBLPAGE

{

     ULONG ulbLpszLabel;

     ULONG ulFlags;

     ULONG ulbLpszComponent;

     ULONG ulContext;

} DTBLPAGE, FAR *LPDTBLPAGE;

Members

ulbLpszLabel

Position in memory of the character string label for the page tab.

ulFlags

Bitmask of flags used to designate the format of the label pointed to by the ulbLpszLabelName member. The following flag can be set:

MAPI_UNICODE

The label is in Unicode format. If the MAPI_UNICODE flag is not set, the label is in ANSI format.

ulbLpszComponent

Position in memory of a character string identifying a Help file entry that appears in the MAPISVC.INF configuration file. If this string is not NULL, a user can access extended Help for the tabbed page by clicking the Help button on the dialog box.

ulContext

A unique identifier for the tabbed page within the string defined by the ulbLpszComponent member. The ulbLpszComponent member and the ulContext member must both be nonzero in order for the Help button to work. If this identifier is zero and the component string is NULL, there is no Help associated with the page.

Remarks

A DTBLPAGE structure describes a tabbed page — a control that is used to separate several related dialog boxes. Typically these dialog boxes are property sheets for showing configuration, message, or recipient options. By clicking the tab, the user can switch from one sheet to another.

The following dialog box includes four tabbed page controls: one control for each type of property relating to a particular address type.

The component string and context identifier provide information about whether or not extended help is available for the tabbed page and if it is available, how to access it. The component string maps to the Help file; the context identifier maps to the initial Help topic. If the context identifier is zero and the component string is NULL, extended Help is not available.

For an overview of display tables, see Display Tables. For information about implementing a display table, see Implementing a Display Table.

See Also

DTCTL


DTBLRADIOBUTTON

The DTBLRADIOBUTTON structure describes one radio button that will be part of a radio button group to be used in a dialog box that is built from a display table.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _DTBLRADIOBUTTON

{

     ULONG ulbLpszLabel;

     ULONG ulFlags;

     ULONG ulcButtons;

     ULONG ulPropTag;

     long lReturnValue;

} DTBLRADIOBUTTON, FAR *LPDTBLRADIOBUTTON;

Members

ulbLpszLabel

Position in memory of the character string label for the radio button.

ulFlags

Bitmask of flags used to designate the format of the label pointed to by the ulbLpszLabel member. The following flag can be set:

MAPI_UNICODE

The label is in Unicode format. If the MAPI_UNICODE flag is not set, the label is in ANSI format.

ulcButtons

Count of buttons in the radio button group. The DTBLRADIOBUTTON structures for the other buttons in the group must be contained in successive rows of the display table. Each of these rows should contain the same value for the ulcButtons member.

ulPropTag

Property tag for a property of type PT_LONG. The initial selection within the radio button group is based on the initial value of this property. Each button in the group must have ulPropTag set to the same property.

lReturnValue

Unique number that identifies the selected button.

Remarks

A DTBLRADIOBUTTON structure describes a radio button — a button control that is associated with a group of buttons. Only one button in the group can be checked; setting one button causes the other buttons in the group to be unset. The following dialog box includes an example of a group of three radio button controls.

The button count is the number of radio buttons in the group. The structures for the other radio buttons in the group must be in subsequent rows in the display table. Each of these structures should have the same value for its button count.

For an overview of display tables, see Display Tables. For information about implementing a display table, see Implementing a Display Table.

See Also

BuildDisplayTable, DTCTL, SizedDtblButton


DTCTL

The DTCTL structure describes a control to be used in a dialog box built from a display table.

Quick Info

Header file:	MAPIUTIL.H
typedef struct

{

     ULONG      ulCtlType;

     ULONG      ulCtlFlags;

     LPBYTE     lpbNotif;

     ULONG      cbNotif;

     LPTSTR     lpszFilter;

     ULONG      ulItemID;

     union

     {

          LPVOID               lpv;

          LPDTBLLABEL          lplabel;

          LPDTBLEDIT           lpedit;

          LPDTBLLBX            lplbx;

          LPDTBLCOMBOBOX       lpcombobox;

          LPDTBLDDLBX          lpddlbx;

          LPDTBLCHECKBOX       lpcheckbox;

          LPDTBLGROUPBOX       lpgroupbox;

          LPDTBLBUTTON         lpbutton;

          LPDTBLRADIOBUTTON    lpradiobutton;

          LPDTBLMVLISTBOX      lpmvlbx;

          LPDTBLMVDDLBX        lpmvddlbx;

          LPDTBLPAGE           lppage;

     } ctl;

} DTCTL, FAR *LPDTCTL;

Members

ulCtlType

Type of control that is included in the ctl member and corresponds to the control’s PR_CONTROL_TYPE property. Possible values are described in the following table.

Value of ulCtlType member	Description
DTCT_LABEL	Label control
DTCT_EDIT	Edit control
DTCT_LBX	List box control
DTCT_COMBOBOX	Combo box control
DTCT_DDLBX	Drop-down list box control
DTCT_CHECKBOX	Check box control
DTCT_GROUPBOX	Group box control
DTCT_BUTTON	Button control
DTCT_PAGE	Tabbed page control
DTCT_RADIOBUTTON	Radio button control
DTCT_MVLISTBOX	Multivalued list box control
DTCT_MVDDLBX	Multivalued drop-down list box control
ulCtlFlags

Bitmask of flags that describes the control’s features and corresponds to the control’s PR_CONTROL_FLAGS property. These flags can be set for check boxes, combo boxes, list boxes, and edit controls only. Possible values are:

DT_ACCEPT_DBCS

Either the ANSI or DBCS format is accepted. This flag is valid for edit controls only.

DT_EDITABLE

A user can edit the text in the control.

DT_MULTILINE

The control can contain multiple text lines. This flag is valid for edit controls only.

DT_PASSWORD_EDIT

The control contains a password; therefore, the contents of the control should not be displayed to the user. This flag is valid for edit controls only.

DT_REQUIRED

The dialog box control is required. This flag is valid only for edit and combo box controls.

DT_SET_IMMEDIATE

Enables immediate output of a value upon a change in the control, allowing a dependency relationship to be established between two controls.

lpbNotif

Pointer to a structure made up of a globally unique identifier, or GUID structure, to represent the service provider and an identifier for the control. The lpbNotif and cbNotif members correspond to the control’s PR_CONTROL_ID property and are used to notify the user interface when the control needs updating.

cbNotif

Count of bytes in the structure pointed to by the lpbNotif member.

lpszFilter

Pointer to a character string that describes which characters can be entered into an edit or combo box control. For other types of controls, the lpszFilter member can be NULL. For edit and combo box controls, it should be a regular expression that applies to a single character at a time. The same filter is applied to all characters in the control.

The format of the filter string is as follows:

*	 	Any character is allowed (for example, “*”).

[  ] 	Defines a set of characters (for example, “[0123456789]”).

-	 	Indicates a range of characters (for example, “[a-z]”).

~	 	Indicates that these characters are not allowed (for example, “[~0-9]”).

\	 	Used to quote any of the above symbols (for example, “[\-\\\[\]]” means -, \, [, and ] characters are allowed).

ulItemID

Value that identifies the control in the dialog box resource. For tabbed pages — controls of type DTCT_PAGE — the ulItemID member is optionally used to load the component name for the page from a string resource.

ctl

A structure that holds the data for the control and corresponds to the control’s PR_CONTROL_STRUCTURE property. Each type of control has a different structure.

Remarks

The DTCTL structure describes one control of any type. Most of its members are used to set properties on the control.

The ctl member is a union of structures that relate to a particular type of control. If the DTCTL structure is describing an edit control, for example, the ctl member will point to an DTBLEDIT structure. This structure corresponds to the control’s PR_CONTROL_STRUCTURE property. The union has as its first member a variable of type LPVOID to permit compile time initialization of the DTCTL structure.

Although the BuildDisplayTable function uses the DTCTL structure for building the display table from control resources, the DTCTL structure never appears in the display table itself. This structure simply supplies information to BuildDisplayTable.

In the ulCtlFlags member, four flags — DT_ACCEPT_DBCS, DT_EDITABLE, DT_MULTILINE_and DT_PASSWORD_EDIT — affect edit controls only. Two others — DT_REQUIRED and DT_SET_IMMEDIATE — affect any editable control.

The controls available for a dialog box are label, edit box, ink-aware edit box, list box, drop-down list box, combo box, check box, group box, button, radio button, and tabbed page.

For an overview of display tables, see Display Tables. For information about implementing a display table, see Implementing a Display Table.

See Also

BuildDisplayTable, DTBLBUTTON, DTBLCHECKBOX, DTBLCOMBOBOX, DTBLDDLBX, DTBLEDIT, DTBLGROUPBOX, DTBLLABEL, DTBLLBX, DTBLMVDDLBOX, DTBLMVLISTBOX, DTBLPAGE, DTBLRADIOBUTTON


DTPAGE

The DTPAGE structure describes the dialog box that is built from a display table by the BuildDisplayTable function.

Quick Info

Header file:	MAPIUTIL.H
typedef struct DTPAGE

{

     ULONG        cctl;

     LPTSTR       lpszResourceName;

     union

     {

          LPTSTR              lpszComponent;

          ULONG               ulItemID;

      }

     LPDTCTL      lpctl;

}    DTPAGE, FAR *LPDTPAGE;

Members

cctl

Count of controls pointed to by the lpctl member.

lpszResourceName

Pointer to the name or integer identifier for the dialog box resource. The MAKEINTRESOURCE macro should be used with an integer identifer to guarantee correctness.

lpszComponent

Pointer to a string that appears in a Help file mapping entry in MAPISVC.INF.

ulItemID

Resource identifier from which the Help file name can be read.

lpctl

Pointer to a array of DTCTL structures, one for each control on the page.

Remarks

To identify the Help file for the tabbed page, set either the lpszComponent member to a hard-coded string or the ulItemID member to an integer resource identifier. When an integer identifier is used, the BuildDisplayTable function obtains the name from the corresponding string resource.

Although BuildDisplayTable uses this structure to build the display table from control resources, the DTPAGE structure never appears in the display table itself.

Each help file mapping entry in MAPISVC.INF consists of a component string, no longer than 30 characters, on the left side and a Help file path on the right. Both ulItemID and lpszResourceName are found in the hInstance parameter of BuildDisplayTable.

For an overview of display tables, see Display Tables. For information about implementing a display table, see Implementing a Display Table.

See Also

BuildDisplayTable, DTBLPAGE, DTCTL


ENTRYID

The ENTRYID structure contains an entry identifier for a MAPI object.

Quick Info

Header file:	MAPIDEFS.H
Related macros:	CbNewENTRYID SizedENTRYID
typedef struct

{

     BYTE        abFlags[4];

     BYTE        ab[MAPI_DIM];

} ENTRYID, FAR *LPENTRYID;

Members

abFlags

Bitmask of flags that provide information describing the object. Only the first byte of the flags, abFlags[0], may be set by the provider; the other three are reserved. The client should never change anything in the structure.

The following flags can be set in abFlags[0]:

MAPI_NOTRECIP

The entry identifier cannot be used as a recipient on a message.

MAPI_NOTRESERVED

Other users cannot access the entry identifier.

MAPI_NOW

The entry identifier cannot be used at other times.

MAPI_SHORTTERM

The entry identifier is short-term. All other values in this byte must be set unless other uses of the entry identifier are allowed.

MAPI_THISSESSION

The entry identifier cannot be used on other sessions.

The flags must not be set for permanent entry identifiers and set for short-term entry identifiers.

ab

Array of binary data used by service providers. The client application cannot use this array.

Remarks

A message store or address book provider fills an entry identifier with information that makes sense for that provider. For a message store, entry identifiers identify folders or messages but not attachments. For an address book, entry identifiers identify address book containers, individual messaging users, and distribution lists. Entry identifiers also identify message store, status, profile, and session objects. An entry identifier is a unique number that distinguishes one object from all other objects of the same type. For example, a message entry identifier uniquely identifies a message in the message store.

Directly comparing the binary data in two entry identifiers does not provide much information to the application because MAPI can use different binary values in ENTRYID structures to refer to the same object. To determine if two entry identifiers refer to the same object, the client application can use the IMAPISession::CompareEntryIDs method for the appropriate object.

The following rules apply for using the abFlags[0] byte in entry identifiers.

•	Each object, if queried for its entry identifier through its IMAPIProp interface, generates and provides the most permanent form of its entry identifier. To indicate an entry identifier is the most permanent one available for a given object, clear all the bits in the abFlags array.

•	Entry identifiers found in most MAPI tables can be short-term instead of permanent. The use of short-term entry identifiers is usually restricted. In general, a client can use a short-term entry identifier to open an object only in the current MAPI session. Use the short-term entry identifier with the message store only for the current session and only while the address book remains open. To indicate a short-term entry identifier, set all the values in the abFlags array. The next rule slightly modifies these limitations.

•	In some cases, your short-term entry identifier might be just as good as a permanent entry identifier. In such cases, clear individual bits in the abFlags array as appropriate.

Although providers should handle arbitrarily aligned entry identifiers, clients cannot expect providers to handle arbitrarily aligned entry identifiers. Failure to pass in a suitable aligned entry identifier can result in an alignment fault on RISC CPUs. To allow for those providers that do not handle arbitrarily aligned identifiers, clients should always pass in naturally aligned entry identifiers. The natural alignment factor, typically 8 bytes, is the largest data type supported by the CPU, and usually the same alignment factor used by the system memory allocator. A naturally aligned memory address allows the CPU to access any data type it supports at that address without generating an alignment fault. For RISC CPUs, a data type of size N bytes must usually be aligned on an even multiple of N bytes, with the address being an even multiple of N.

See Also

IMAPISupport::CompareEntryIDs, PR_RECORD_KEY


ENTRYLIST

The ENTRYLIST structure is an array of entry identifiers representing MAPI objects.

Quick Info

Header file:	MAPIDEFS.H
typedef SBinaryArray ENTRYLIST, FAR *LPENTRYLIST;

See Also

ENTRYID, SBinaryArray


ERROR_NOTIFICATION

The ERROR_NOTIFICATION structure describes information relating to a critical error, causing an error notification to be generated.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _ERROR_NOTIFICATION

{

     ULONG         cbEntryID;

     LPENTRYID     lpEntryID;

     SCODE         scode;

     ULONG         ulFlags;

     LPMAPIERROR   lpMAPIError;

} ERROR_NOTIFICATION;

Members

cbEntryID

Count of bytes in the entry identifier pointed to by lpEntryID.

lpEntryID

Pointer to the entry identifier of the object causing the error.

scode

Error value for the critical error.

ulFlags

Bitmask of flags used to designate the format of the text pointed to by the lpszError member in the structure pointed to by lpMAPIError. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lpMAPIError

Pointer to a MAPIERROR structure describing the error.

Remarks

The ERROR_NOTIFICATION structure is one of the members of the union of structures included in the info member of the NOTIFICATION structure. When the info member of a NOTIFICATION structure contains an ERROR_NOTIFICATION structure, the ulEventType member of the NOTIFICATION structure is set to fnevCriticalError.

The value of the cbEntryID member and the lpEntryID member can be NULL.

For more information about notification, see the topics described in the following table.

Topic	Description
Event Notification in MAPI	General overview of notification and notification events.
Handling Notifications	Discussion of how clients should handle notifications.
Using a Support Object for Event Notification	Discussion of how service providers can use the IMAPISupport method to generate notifications.
See Also

NOTIFICATION


EXTENDED_NOTIFICATION

The EXTENDED_NOTIFICATION structure describes information relating to an event that is service provider-specific.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _EXTENDED_NOTIFICATION

{

     ULONG    ulEvent;

     ULONG    cb;

     LPBYTE   pbEventParameters;

} EXTENDED_NOTIFICATION;

Members

ulEvent

Extended event code that is defined by the provider.

cb

Count of bytes in the event-specific parameters pointed to by pbEventParameters.

pbEventParameters

Pointer to event-specific parameters. What type of parameters are used depends on the value of the ulEvent member; these parameters are documented by the provider that issued the event.

Remarks

The EXTENDED_NOTIFICATION structure is one of the members of the union of structures included in the info member of the NOTIFICATION structure. When the info member of a NOTIFICATION structure contains an EXTENDED_NOTIFICATION structure, the ulEventType member of the NOTIFICATION structure is set to fnevExtended.

The extended event is defined by a service provider to represent a type of change that cannot be covered by any of the other pre-defined events. Only clients that know before they register that a service provider supports an extended event can register for that event. It is not possible for clients to determine without advanced knowledge if a service provider supports an extended event and, if it does, how to handle such an event when it is received.

For more information about notification, see the topics described in the following table.

Topic	Description
Event Notification in MAPI	General overview of notification and notification events.
Handling Notifications	Discussion of how clients should handle notifications.
Using a Support Object for Event Notification	Discussion of how service providers can use the IMAPISupport method to generate notifications.
See Also

NOTIFICATION


FILETIME

The FILETIME structure holds a 64-bit time value for a file. This value represents the number of 100-nanosecond intervals since January 1, 1601.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _FILETIME

{

     DWORD dwLowDateTime;

     DWORD dwHighDateTime;

} FILETIME, FAR *LPFILETIME;

Members

dwLowDateTime

Low-order 32 bits of the file time value.

dwHighDateTime

High-order 32 bits of the file time value.

Remarks

Each MAPI property includes a FILETIME structure in its definition in an SPropValue structure. A property of type PT_SYSTIME has a FILETIME structure for its value.

The full definition of the FILETIME structure is in the Win32 Programmer’s Reference.

See Also

SPropValue


FLAGLIST

The FLAGLIST structure contains a list of flags used to indicate the status of address entries during the name resolution process.

Quick Info

Header file:	MAPIDEFS.H
typedef struct

{

     ULONG cFlags;

     ULONG ulFlags[MAPI_DIM];

} FlagList, FAR * LPFlagList;

Members

cFlags

Count of MAPI-defined flags in the list.

ulFlags

First flag in the list.

Remarks

See IABContainer::ResolveNames and IDistList::ResolveNames for descriptions of the flags that can be part of this list.

See Also

IABContainer::ResolveNames


FLATENTRY

The FLATENTRY structure is an ENTRYID structure plus a byte count that specifies the size of the ENTRYID structure.

Quick Info

Header file:	MAPIDEFS.H
Related macros:	cbFLATENTRY CbNewFLATENTRY
typedef struct

{

     ULONG  cb;

     BYTE   abEntry[MAPI_DIM];

} FLATENTRY, FAR *LPFLATENTRY;

Members

cb

Count of bytes in the abEntry member.

abEntry

The complete entry identifier, including the array of flags and binary data.

Remarks

There are two differences between a FLATENTRY structure and an ENTRYID structure:

•	FLATENTRY stores the size of the entry identifier; ENTRYID does not.

•	FLATENTRY stores the flag data together with the rest of the entry identifier; ENTRYID stores them separately.

A FLATENTRY structure is used to store an entry identifier in a file or pass it in a stream of bytes whereas an ENTRYID structure is used by the IMAPIProp methods and by the OpenEntry methods. When an entry identifier needs to be stored on disk, it must be stored in an ENTRYID structure. A FLATENTRY structure cannot be used because there are byte order problems with storing the size.

See Also

ENTRYID


FLATENTRYLIST

The FLATENTRYLIST structure contains an array of FLATENTRY structures.

Quick Info

Header file:	MAPIDEFS.H
Related macros:	CbFLATENTRYLIST CbNewFLATENTRYLIST
typedef struct

{

     ULONG     cEntries;

     ULONG     cbEntries;

     BYTE      abEntries[MAPI_DIM];

} FLATENTRYLIST, FAR *LPFLATENTRYLIST;

Members

cEntries

Count of FLATENTRY structures in the array described by the abEntries member.

cbEntries

Count of bytes occupied by the entire array described by abEntries.

abEntries

Byte array containing the number of FLATENTRY structures in the cEntries member, arranged end to end.

Remarks

In the abEntries array, each FLATENTRY structure is aligned on a naturally aligned boundary. Extra bytes are included as padding to ensure natural alignment between any two FLATENTRY structures. The first FLATENTRY structure in the array is always aligned correctly because the offset of the abEntries member is 8. To compute the offset of the next structure, use the size of the first entry rounded up to the next multiple of 4. Use the CbFLATENTRY macro to compute the size of a FLATENTRY structure.

For example, the second FLATENTRY structure starts at an offset made up of the offset of the first entry plus the length of the first entry rounded to the next four bytes. The length of the first entry is the length of its cb member plus the length of its abEntry member.

The following code sample indicates how to compute offsets in a FLATENTRYLIST structure. Assume that lpFlatEntry is a pointer to the first structure in the list.

(offsetof(lpFlatEntry->ab)	// for example, 4

+ lpFlatEntry->cb	// size of lpFlatEntry->ab

+ 4) & ~3	// round to next 4 byte boundary

See Also

FLATENTRY, PR_REPLY_RECIPIENT_ENTRIES


FLATMTSIDLIST

The FLATMTSIDLIST structure contains an array of MTSID structures, each of which contains an X.400 message transport system (MTS) entry identifier.

Quick Info

Header file:	MAPIDEFS.H
Related macros:	CbFLATMTSIDLIST CbNewFLATMTSIDLIST
typedef struct

{

     ULONG     cMTSIDs;

     ULONG     cbMTSIDs;

     BYTE      abMTSIDs[MAPI_DIM];

} FLATMTSIDLIST, FAR *LPFLATMTSIDLIST;

Members

cMTSIDs

Count of MTSID structures in the array described by the abMTSIDs member.

cbMTSIDs

Count of bytes in the array described by abMTSIDs.

abMTSIDs

Byte array of MTSID structures.

Remarks

The FLATMTSIDLIST structure’s use in X.400 messaging corresponds to the FLATENTRYLIST structure’s use in MAPI messaging. MAPI uses FLATMTSIDLIST structures to maintain X.400 properties during message handling. Service providers use FLATMTSIDLIST structures when handling inbound and outbound X.400 messages.

In the abMTSIDs array, each MTSID structure is aligned on a naturally aligned boundary. Extra bytes are included as padding to ensure natural alignment between any two MTSID structures.

See Also

CbNewFLATMTSIDLIST, FLATENTRYLIST, MTSID


FORMPRINTSETUP

The FORMPRINTSETUP structure describes the print setup information for the form object.

Quick Info

Header file:	MAPIFORM.H
typedef struct

{

    ULONG        ulFlags;

    HDEVMODE     hDevMode;

    HDEVNAMES    hDevNames;

    ULONG        ulFirstPageNumber;

    ULONG        ulFPrintAttachments;

} FORMPRINTSETUP, FAR * LPFORMPRINTSETUP;

Members

ulFlags

Bitmask of flags that controls the type of the strings. The following flag can be used:

MAPI_UNICODE

The strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

hDevmode

Handle to the mode of the printer.

hDevnames

Handle to the path of the printer.

ulFirstPageNumber

Page number of the first page to be printed.

ulFPrintAttachments

Flag that indicates whether there are attachments to be printed. If there are attachments to print, the ulFPrintAttachments member is set to 1. If there are no attachments to print, it is set to 0.

Remarks

The FORMPRINTSETUP structure is used to describe the print setup information for the form object. Implementations of IMAPIViewContext::GetPrintSetup fill in the FORMPRINTSETUP structure and return it in the lppformprintsetup output parameter of GetPrintSetup.

If the MAPI_UNICODE flag is passed in the ulflags parameter of GetPrintSetup, the strings in the hDevmode and hDevnames members should be in Unicode format. Otherwise, the strings should be ANSI format.

The hDevMode and hDevNames members must be allocated using the Windows function GlobalAlloc and must be freed using the Windows function GlobalFree. The FORMPRINTSETUP structure must be freed by the calling form object using the MAPIFreeBuffer function. The application must free the FORMPRINTSETUP structure using MAPIFreeBuffer and the other two items using GlobalFree.

See Also

IMAPIViewContext::GetPrintSetup, MAPIFreeBuffer


GUID

The GUID structure describes a globally unique identifier. GUID structures are used in the MAPIUID structures that uniquely identify service providers, for interface identifiers, and in the property set names of named properties.

Quick Info

Header file:	MAPIGUID.H
typedef struct _GUID

{

    unsigned long        Data1;

    unsigned short       Data2;

    unsigned short       Data3;

    unsigned char        Data4[8];

} GUID;

Members

Data1

An unsigned long integer data value.

Data2

An unsigned short integer data value.

Data3

An unsigned short integer data value.

Data4

An array of unsigned characters.

Remarks

Message store and address book providers call the Microsoft utility UUIDGEN.EXE to generate a GUID structure to use in their MAPIUID structure. By passing the resulting MAPIUID to IMAPISupport::SetProviderUID, these service providers inform MAPI of their unique identifier.

For more information about GUID structures, see the Remote Procedure Call (RPC) documentation, OLE Programmer’s Reference, and Inside OLE, Second Edition.

See Also

MAPIUID


IID

The IID structure is a GUID structure defined by MAPI that identifies a MAPI interface.

Remarks

Interface identifiers are used to specify the interface to use to access an object. For example, in a call to IMAPISession::OpenEntry to open a folder, a client would specify IID_IMAPIFolder in the lpInterface parameter.

All of the IID structures for the MAPI interfaces are defined in the MAPIGUID.H header file.


LARGE_INTEGER

The LARGE_INTEGER structure, implemented for all platforms, contains a 64-bit signed integer value.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _LARGE_INTEGER

{

     DWORD LowPart;

     DWORD HighPart;

} LARGE_INTEGER, FAR *LARGE_INTEGER;

Members

LowPart

Low-order 32 bits of the value.

HighPart

High-order 32 bits of the value.

Remarks

A LARGE_INTEGER structure is used, for example, to describe a PT_I8 type of property.

See Also

SPropValue


MAPIERROR

The MAPIERROR structure provides detailed information about an error, typically generated by the operating system, MAPI, or a service provider.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _MAPIERROR

{

     ULONG      ulVersion;

     LPTSTR     lpszError;

     LPTSTR     lpszComponent;

     ULONG      ulLowLevelError;

     ULONG      ulContext;

} MAPIERROR, FAR * LPMAPIERROR;

Members

ulVersion

Version number of the structure. The ulVersion member should be set to MAPI_ERROR_VERSION, which is currently defined as zero.

lpszError

Pointer to a string describing the error.

lpszComponent

Unallocated constant string that describes the component generating the error.

ulLowLevelError

Low-level error value used only when the error to be returned is low-level.

ulContext

Error location within the lpszComponent member. If there is a Help file for this component, ulContext is a Help file context identifier; otherwise, it specifies a unique numeric identifier.

Remarks

The MAPIERROR structure is used to describe error information. Clients and service providers pass a pointer to a MAPIERROR structure in the lppMAPIError parameter to the IMAPIProp::GetLastError method. GetLastError returns information about the previous error that has occurred to an object.

Callers of GetLastError free the memory for the MAPIERROR structure by calling MAPIFreeBuffer.

Service providers implementing GetLastError are not required to provide any detailed error information in the MAPIERROR structure. However, placing an error message string in the lpszError member is strongly recommended. The component name and context members are optional.

The ulContext member primarily identifies the point in the code where the error occurred. This assists support personnel and developers in tracking and isolating problems. It can also be used to refer to an online Help topic for common errors.

For more information about error handling in MAPI, see Error Handling.

See Also

IABLogon::GetLastError, IABProvider::Logon, IMAPIControl::GetLastError, IMAPIProp::GetLastError, IMAPISession::GetLastError, IMAPISupport::GetLastError, IMAPISupport::OpenAddressBook, IMAPISession::OpenAddressBook, IMAPITable::GetLastError, IMsgServiceAdmin::GetLastError, IMSLogon::GetLastError, IMSProvider::Logon, IProfAdmin::GetLastError, IProviderAdmin::GetLastError


MAPIINIT_0

The MAPIINIT_0 structure conveys options to the MAPIInitialize function.

Quick Info

Header file:	MAPIX.H
typedef struct

{

     ULONG ulVersion;

     ULONG ulFlags;

} MAPIINIT_0, FAR *LPMAPIINIT_0;

Members

ulVersion

The integer value representing the version of the MAPIINIT_0 structure. Currently, ulVersion must be set to MAPI_INIT_VERSION.

ulFlags

Bitmask of flags used to control the initialization of the MAPI session. The following flags can be set:

MAPI_MULTITHREAD_NOTIFICATIONS

MAPI should generate notifications using a thread dedicated to notification handling.

MAPI_NT_SERVICE

The caller is running as a Windows NT service. Callers that are not running as a Windows NT service should not set this flag; callers that are running as a service must set this flag.

Remarks

Multithreaded clients running under Windows NT or Windows 95 should set the MAPI_MULTITHREADED_NOTIFICATIONS flag. If the flag is not set, notifications are generated on the thread used to make the first call to MAPIInitialize. For more information about when to set this flag and how to implement thread safety in a client, see Threading in MAPI.

See Also

MapiInitialize


MAPINAMEID

The MAPINAMEID structure is used to describe a named property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _MAPINAMEID

{

     LPGUID lpguid;

     ULONG  ulKind;

     union

     {

          LONG    lID;

          LPWSTR  lpwstrName;

     } Kind;

} MAPINAMEID, FAR *LPMAPINAMEID;

Members

lpguid

Pointer to a GUID structure defining a particular property set; this member cannot be NULL. Valid values are PS_PUBLIC_STRINGS, PS_MAPI, or a client-defined value.

ulKind

Value describing the type of value in the Kind member. Valid values are:

MNID_ID

The Kind member contains an integer value representing the property name.

MNID_STRING

The Kind member contains a Unicode character string representing the property name.

Kind

Union describing the name of the named property. The name can either be an integer value, stored in lID, or a Unicode character string, stored in lpwstrName.

Remarks

The MAPINAMEID structure is used to describe the names of named properties — properties that have identifiers over 0x8000. A property set is an integral part of a named property's property name. For example PS_PUBLIC_STRINGS or PS_ROUTING_ADDRTYPE are property sets defined by MAPI.

Property names enable users to define custom properties in a larger name space than the MAPI property identifier. Property names cannot be used to obtain property values directly; they must first be mapped to property identifiers through the IMAPIProp::GetIDsFromNames method.

For more information about named properties, see Named Properties.

See Also

GUID, IMAPIProp::GetIDsFromNames


MAPIUID

The MAPIUID structure is used to uniquely identify a service provider.

Quick Info

Header file:	MAPIDEFS.H
Related macro:	IsEqualMAPIUID
typedef struct _MAPIUID

{

     BYTE ab[16];

} MAPIUID, FAR *LPMAPIUID;

Members

ab

An array containing a 16-byte identifier.

Remarks

A MAPI unique identifier, or MAPIUID, is a GUID structure put into Intel® processor byte order. That is, MAPIUID and GUID structures have the same byte order when used on an Intel-processor computer. However, on a computer that uses a different byte order — for example, a Motorola®-processor computer — the MAPIUID has the same byte order as on the Intel machine and the GUID uses the byte order specific to the computer.

MAPI creates MAPIUID structures in a way that makes it extremely rare for two different items to have the same identifier. MAPIUID structures can be stored as binary properties or as files, without regard to the byte ordering of the computer storing or accessing the information.

MAPIUID structures are used:

•	To identify a profile section.

•	In the entry identifiers of message store and address book objects to identify the responsible service provider.

•	In the PR_SEARCH_KEY property of messages.

To generate a MAPIUID identifier for a profile section or an entry identifier, service providers call the Microsoft utility UUIDGEN.EXE. To generate a MAPIUID identifier for a search key, service providers call IMAPISupport::NewUID.

When a client transmits a message across a network, it should use a protocol or transmission format that does not change the byte order of MAPIUID data.

See Also

GUID,  IMAPISession::OpenProfileSection, IMAPISupport::NewUID


MTSID

The MTSID structure contains the actual data of an X.400 message transport system (MTS) entry identifier. Its format contrasts with that of an ENTRYID structure, which contains only a pointer to entry identifier data.

Quick Info

Header file:	MAPIDEFS.H
Related macros:	CbMTSID CbNewMTSID
typedef struct

{

     ULONG         cb;

     BYTE          ab[MAPI_DIM];

} MTSID, FAR *LPMTSID;

Members

cb

Count of bytes in the data contained in abEntry.

abEntry

Byte array containing the MTS entry identifier data.

Remarks

The MTSID structure is used only for X.400 mappings of MAPI entry identifiers. It corresponds to the MAPI FLATENTRY structure.

An MTS identifier has the same format as a MAPI entry identifier or a binary property value. MTS identifiers can be particularly useful for canceling deferred messages.

See Also

FLATENTRY, FLATMTSIDLIST


NEWMAIL_NOTIFICATION

The NEWMAIL_NOTIFICATION structure describes information relating to the arrival of a new message.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _NEWMAIL_NOTIFICATION

{

     ULONG      cbEntryID;

     LPENTRYID  lpEntryID;

     ULONG      cbParentID;

     LPENTRYID  lpParentID;

     ULONG      ulFlags;

     LPTSTR     lpszMessageClass;

     ULONG      ulMessageFlags;

} NEWMAIL_NOTIFICATION;

Members

cbEntryID

Count of bytes in the entry identifier pointed to by the lpEntryID member.

lpEntryID

Pointer to the entry identifier of the newly arrived message.

cbParentID

Count of bytes in the entry identifier pointed to by the lpParentID member.

lpParentID

Pointer to the entry identifier of the receive folder for the newly arrived message.

ulFlags

Bitmask of flags used to describe the format of the string properties included with the message. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lpszMessageClass

Pointer to the message class of the newly arrived message.

ulMessageFlags

Bitmask of flags that describes the current state of the newly arrived message. The ulMessageFlags member is a copy of the message’s PR_MESSAGE_FLAGS property.

Remarks

The NEWMAIL_NOTIFICATION structure is one of the members of the union of structures included in the info member of the NOTIFICATION structure. When the info member of a NOTIFICATION structure contains a NEWMAIL_NOTIFICATION structure, the ulEventType member of the NOTIFICATION structure is set to fnevNewMail.

MAPI uses the NEWMAIL_NOTIFICATION structure only as a member of the NOTIFICATION structure, which holds information about a notification event for the advise sink.

For more information about notification, see the topics described in the following table.

Topic	Description
Event Notification in MAPI	General overview of notification and notification events.
Handling Notifications	Discussion of how clients should handle notifications.
Using a Support Object for Event Notification	Discussion of how service providers can use the IMAPISupport method to generate notifications.
See Also

NOTIFICATION, PR_MESSAGE_FLAGS


NOTIFICATION

The NOTIFICATION structure contains information about an event that has occurred and the data that has been affected by the event.

Quick Info

Header file:	MAPIDEFS.H
typedef struct

{

     ULONG     ulEventType;

     union

     {

          ERROR_NOTIFICATION         err;

          NEWMAIL_NOTIFICATION       newmail;

          OBJECT_NOTIFICATION        obj;

          TABLE_NOTIFICATION         tab;

          EXTENDED_NOTIFICATION      ext;

          STATUS_OBJECT_NOTIFICATION statobj;

     } info;

} NOTIFICATION, FAR *LPNOTIFICATION;

Members

ulEventType

Type of notification event that occurred. The value of the ulEventType member corresponds to the structure that is included in the info union.

The ulEventType member can be set to one of the following values:

fnevCriticalError

A global error has occurred, such as a session shut down in progress.

fnevExtended

An internal event defined by a particular service provider has occurred.

fnevNewMail

A message has been delivered to the appropriate receive folder for the message class and is waiting to be processed.

fnevObjectCopied

A MAPI object has been copied.

fnevObjectCreated

A MAPI object has been created.

fnevObjectDeleted

A MAPI object has been deleted.

fnevObjectModified

A MAPI object has changed.

fnevObjectMoved

A message store or address book object has been moved.

fnevSearchComplete

A search operation has finished and the results are available.

fnevTableModified

Information in a table has changed.

info

Union of notification structures describing the affected data for a particular type of event. The structure included in the info member depends on the value of the ulEventType member.

The following table relates event types with the corresponding type of notification structure.

Value for ulEventType member	Structure type in info member
fnevCriticalError	ERROR_NOTIFICATION
fnevExtended	EXTENDED_NOTIFICATION
fnevNewMail	NEWMAIL_NOTIFICATION
fnevObjectCreated	OBJECT_NOTIFICATION
fnevObjectDeleted	OBJECT_NOTIFICATION
fnevObjectModified	OBJECT_NOTIFICATION
fnevObjectCopied	OBJECT_NOTIFICATION
fnevObjectMoved	OBJECT_NOTIFICATION
fnevSearchComplete	OBJECT_NOTIFICATION
fnevTableModified	TABLE_NOTIFICATION
Remarks

One or more NOTIFICATION structures are passed as an input parameter with every call to a registered advise sink’s IMAPIAdviseSink::OnNotify method. The NOTIFICATION structures contain information about the particular events that have occurred and describe the affected objects.

Before clients or service providers receiving a notification can use the structure to process the event, they must check the event type as indicated in the ulEventType member. For example, the code sample below checks for the arrival of a new message and upon detecting an event of this type, prints out the message class of the message.

if (pNotif -> ulEventType == fnevNewMail)

{

     printf("%s\n", pNotif -> newmail.lpszMessageClass)

}

For more information about notification, see the topics described in the following table.

Topic	Description
Event Notification in MAPI	General overview of notification and notification events.
Handling Notifications	Discussion of how clients should handle notifications.
Using a Support Object for Event Notification	Discussion of how service providers can use the IMAPISupport method to generate notifications.
See Also

ERROR_NOTIFICATION, EXTENDED_NOTIFICATION, NEWMAIL_NOTIFICATION, OBJECT_NOTIFICATION, STATUS_OBJECT_NOTIFICATION, TABLE_NOTIFICATION


NOTIFKEY

The NOTIFKEY structure uniquely identifies a connection between an advise sink, an advise source, and MAPI. MAPI uses the NOTIFKEY structure for generating notifications to the appropriate advise sink about the appropriate advise source.

Quick Info

Header file:	MAPISPI.H
typedef struct

{

     ULONG     cb;

     BYTE      ab[MAPI_DIM];

} NOTIFKEY, FAR *LPNOTIFKEY;

Members

cb

Count of bytes in the ab member.

ab

Array of bytes describing the notification key.

Remarks

Service providers generate notification keys when their Advise method is called and they want to call IMAPISupport::Subscribe to handle the notification registration and the subsequent sending of notifications. A notification key can be the entry identifier of the advise source or it can be any other identifying item such as a constant. For example, a message store provider might use the path of a folder as its notification key.

The notification key should work across multiple processes.


OBJECT_NOTIFICATION

The OBJECT_NOTIFICATION structure contains information about an object that has undergone a change, such as being modified or copied .

Quick Info

Header file:	MAPIDEFS.H
typedef struct _OBJECT_NOTIFICATION

{

     ULONG             cbEntryID;

     LPENTRYID         lpEntryID;

     ULONG             ulObjType;

     ULONG             cbParentID;

     LPENTRYID         lpParentID;

     ULONG             cbOldID;

     LPENTRYID         lpOldID;

     ULONG             cbOldParentID;

     LPENTRYID         lpOldParentID;

     LPSPropTagArray   lpPropTagArray;

} OBJECT_NOTIFICATION;

Members

cbEntryID

Count of bytes in the entry identifier of the affected object.

lpEntryID

Pointer to the entry identifier of the affected object.

ulObjType

Type of object affected. Possible types are:

MAPI_STORE

Message store.

MAPI_ADDRBOOK

Address book.

MAPI_FOLDER

Folder.

MAPI_ABCONT

Address book container.

MAPI_MESSAGE

Message.

MAPI_MAILUSER

Messaging user.

MAPI_ATTACH

Attachment.

MAPI_DISTLIST

Distribution list.

MAPI_PROFSECT

Profile section.

MAPI_STATUS

Status.

MAPI_SESSION

Session.

cbParentID

Count of bytes in the entry identifier pointed to by the lpParentID member.

lpParentID

Pointer to the entry identifier of the parent of the affected object.

cbOldID

Count of bytes in the entry identifier pointed to by the lpOldID member.

lpOldID

Pointer to the entry identifier of the original object. This pointer can be NULL if an original object is not applicable to the event.

cbOldParentID

Count of bytes in the entry identifier pointed to by the lpOldParentID member.

lpOldParentID

Pointer to the entry identifier of the parent of the original object. This pointer can be NULL if an original object is not applicable to the event.

lpPropTagArray

Pointer to an SPropTagArray structure containing the property tags identifying properties affected by the event.

Remarks

The OBJECT_NOTIFICATION structure is one of the members of the union of structures included in the info member of the NOTIFICATION structure. When the info member of a NOTIFICATION structure contains an OBJECT_NOTIFICATION structure, the ulEventType member of the NOTIFICATION structure is set to one of the following events:

fnevObjectCreated

fnevObjectModified

fnevObjectDeleted

fnevObjectMoved

fnevObjectCopied

fnevSearchComplete

For more information about notification, see the topics described in the following table.

Topic	Description
Event Notification in MAPI	General overview of notification and notification events.
Handling Notifications	Discussion of how clients should handle notifications.
Using a Support Object for Event Notification	Discussion of how service providers can use the IMAPISupport method to generate notifications.
See Also

NOTIFICATION, SPropTagArray


OPTIONDATA

The OPTIONDATA structure describes option properties supported by a transport provider.

Quick Info

Header file:	MAPISPI.H
typedef struct _OPTIONDATA

{

     ULONG           ulFlags;

     LPGUID          lpRecipGUID;

     LPTSTR          lpszAdrType;

     LPTSTR          lpszDLLName;

     ULONG           ulOrdinal;

     ULONG           cbOptionsData;

     LPBYTE          lpbOptionsData;

     ULONG           cOptionsProps;

     LPSPropValue    lpOptionsProps;

} OPTIONDATA, FAR *LPOPTIONDATA;

Members

ulFlags

Bitmask of flags used to specify recipient or message options. The following flags can be set:

MAPI_MESSAGE

Message-specific options.

MAPI_RECIPIENT

Recipient-specific options.

lpRecipGUID

Pointer to a GUID structure identifying the message recipient, if applicable.

lpszAdrType

Pointer to the e-mail address type that must be NULL.

lpszDLLName

Pointer to the name of the DLL to be loaded.

ulOrdinal

Specifies which ordinal the transport provider DLL uses to find the client’s option callback function.

cbOptionsData

Size, in bytes, of the data pointed to by the lpbOptionsData member.

lpbOptionsData

Pointer to transport-provider option data that is specific to the recipient or message.

cOptionsProps

Count of properties in the array pointed to by the lpOptionsProps member.

lpOptionsProps

Pointer to an array of SPropValue structures, each containing information about a default option property.

Remarks

Option properties can apply to a recipient or to a message. They often relate to an address type or GUID supported by a transport provider. Transport providers register to support option properties when MAPI calls their IXPLogon::RegisterOptions method.

RegisterOptions writes one or two OPTIONDATA structures for each supported address type, depending on whether the provider registers for both recipient and message options, recipient options only, or message options only. If a provider is registered for both option types, RegisterOptions writes one structure containing message option properties and one structure containing recipient option properties.

Clients can retrieve the current settings for these options either interactively with a property sheet or programmatically with a property value array. To display option properties to the user, clients call IMAPISession::MessageOptions or IAddrBook::RecipOptions. To retrieve option properties without user intervention, clients call IMAPISession::QueryDefaultMessageOpt or IAddrBook::QueryDefaultRecipOpt.

When a client calls MessageOptions or RecipOptions, MAPI invokes a callback function created by the transport provider that conforms to the OPTIONCALLBACK prototype. This function typically resides in the same DLL as the transport provider and is called to retrieve an IMAPIProp implementation to use with a display table for showing the message and recipient options described in the OPTIONDATA structures.

The DLL name in the lpszDLLname parameter should not indicate the operating system platform when OPTIONDATA is passed in the lppOptions parameter of the IXPLogon::RegisterOptions method.

See Also

IXPLogon::AddressTypes, IXPLogon::RegisterOptions, SPropValue


PFNIDLE

PFNIDLE is a pointer type used to declare a MAPI idle function — a function with the prototype FNIDLE.

Quick Info

Header file:	MAPIUTIL.H
typedef FNIDLE     *PFNIDLE;

Remarks

Functions based on the FNIDLE prototype are functions that a service provider writes to perform processing during idle time in the CPU. Service providers register their FNIDLE functions by calling FtgRegisterIdleRoutine and cancel the registration by calling DeregisterIdleRoutine.

See Also

FNIDLE


SAndRestriction

The SAndRestriction structure describes an AND restriction, which is used to join a group of restrictions using a logical AND operation.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SAndRestriction

{

     ULONG          cRes;

     LPSRestriction lpRes;

} SAndRestriction;

Members

cRes

Count of search restrictions in the array pointed to by the lpRes member.

lpRes

Pointer to an array of SRestriction structures to be combined with a logical AND operation.

Remarks

The result of the SAndRestriction is TRUE if all of its child restrictions evaluate TRUE, and FALSE if any child restriction evaluates FALSE.

See Also

SRestriction


SAppTimeArray

The SAppTimeArray structure contains a pointer to an array of application time values for use in an SPropValue structure containing information about a property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SAppTimeArray

{

     ULONG      cValues;

     double     FAR *lpat;

} SAppTimeArray;

Members

cValues

Count of values in the array pointed to by the lpat member.

lpat

Pointer to an array of application time values.


SBinary

The SBinary structure contains a pointer to a property value of type PT_BINARY for use in an SPropValue structure containing information about a property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SBinary

{

     ULONG      cb;

     LPBYTE     lpb;

} SBinary, FAR *LPSBinary;

Members

cb

Size, in bytes, of the data pointed to by the lpb member.

lpb

Pointer to the PT_BINARY property value.

See Also

SPropValue


SBinaryArray

The SBinaryArray structure contains a property value of type PT_MV_BINARY for use in an SPropValue structure containing information about a multivalued property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SBinaryArray

{

     ULONG        cValues;

     SBinary      FAR *lpbin;

} SBinaryArray;

Members

cValues

Count of values in the array pointed to by the lpbin member.

lpbin

Pointer to an array of SBinary structures holding the multiple values for the property.

Remarks

For more information on PT_MV_BINARY, see List of Property Types.

See Also

SBinary, SPropValue


SBitMaskRestriction

The SBitMaskRestriction structure describes a bitmask restriction, which is used to apply a bitmask to a particular property value and test the result.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SBitMaskRestriction

{

     ULONG relBMR;

     PT_LONG ulPropTag;

     ULONG ulMask;

} SBitMaskRestriction;

Members

relBMR

Relational operator describing how the mask specified in the ulMask member should be applied to the property tag. Possible values are:

BMR_EQZ

The result of applying the bitmask to the property should be tested for being equal to zero.

BMR_NEZ

The result of applying the bitmask to the property should be tested for not being equal to zero.

ulPropTag

Indicates the property tag of the property to which the bitmask is applied.

ulMask

Indicates the bitmask to apply to the property identified by ulPropTag.

Remarks

This restriction performs a logical AND operation using the bitmask described in the ulMask member and the value of the property described by the ulPropTag member. If the result is zero, then BMR_EQZ is satisfied. If it’s nonzero — that is, if the property value has at least one of the same bits set as ulMask — then BMR_NEZ is satisfied.

See Also

SRestriction


SCommentRestriction

The SCommentRestriction structure describes a comment restriction, which is used to annotate a restriction.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SCommentRestriction

{

     ULONG          cValues;

     LPSRestriction lpRes;

     LPSPropValue   lpProp;

} SCommentRestriction;

Members

cValues

Count of property values in the array pointed to by the lpProp member.

lpRes

Pointer to an SRestriction structure.

lpProp

Pointer to an array of SPropValue structures, each containing information about a property.

Remarks

The SCommentRestriction structure can be used to keep application-specific information with a restriction. For example, a client saving the name of a named property used in a property restriction can do so in an SCommentRestriction structure. Saving the name is not possible in a property restriction; the SPropertyRestriction structure holds only the property tag.

Comment restrictions are ignored by the IMAPITable::Restrict method. There is no effect on the rows returned by the IMAPITable::QueryRows method after an IMAPITable::Restrict call has been made.

See Also

SPropValue, SRestriction


SComparePropsRestriction

The SComparePropsRestriction structure describes a compare property restriction, which tests two properties using a particular relational operator.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SComparePropsRestriction

{

     ULONG relop;

     ULONG ulPropTag1;

     ULONG ulPropTag2;

} SComparePropsRestriction;

Members

relop

Relational operator to use to compare the two properties. Possible values are:

RELOP_GE

The comparison is made based on a greater or equal first value.

RELOP_GT

The comparison is made based on a greater first value.

RELOP_LE

The comparison is made based on a lesser or equal first value.

RELOP_LT

The comparison is made based on a lesser first value.

RELOP_NE

The comparison is made based on unequal values.

RELOP_RE

The comparison is made based on LIKE (regular expression) values.

RELOP_EQ

The comparison is made based on equal values.

ulPropTag1

Property tag of the first property to be compared.

ulPropTag2

Property tag of the second property to be compared.

Remarks

The comparison order is (property tag 1) (relational operator) (property tag 2). The two properties compared should be of the same type. Attempting to compare properties of different types commonly returns the error value MAPI_E_TOO_COMPLEX.

The result of a property value restriction is undefined when the property does not exist. When a client requires well-defined behavior for such a restriction and is not sure whether the property exists — for example, it is not a required column of a table — it should create an AND restriction to join the compare property restriction with an exist restriction. Use an SExistRestriction structure to define the exist restriction and an SAndRestriction structure to define the AND restriction.

The properties can be multivalued if the service provider supports it.

See Also

SBitMaskRestriction, SRestriction


SContentRestriction

The SContentRestriction structure contains a search restriction to limit a view of the messages in a table based on checking for a search string.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SContentRestriction

{

     ULONG        ulFuzzyLevel;

     ULONG        ulPropTag;

     LPSPropValue lpProp;

} SContentRestriction;

Members

ulFuzzyLevel

Option settings defining the level of preciseness that the restriction should enforce. The lower 16 bits must be set to exactly one of the following values:

FL_FULLSTRING

The lpProp search string must be completely contained in the property identified by ulPropTag.

FL_PREFIX

The lpProp search string must appear at the beginning of the property identified by ulPropTag. The two strings should be compared only up to the length of the search string indicated by lpProp.

FL_SUBSTRING

The lpProp search string must be contained anywhere within the property identified by ulPropTag.

The upper 16 bits can be set to the following values in any combination:

FL_IGNORECASE

The comparison should be made without considering case sensitivity.

FL_IGNORENONSPACE

The comparison should ignore Unicode-defined “nonspacing characters,” for example, diacritical marks.

FL_LOOSE

The comparison should result in a match whenever possible, ignoring case sensitivity and nonspacing characters.

ulPropTag

Property tag identifying the string property to be checked for occurrence of the search string.

lpProp

Pointer to a property value structure containing the string value to use as the search string.

Remarks

There are two property tags in an SContentRestriction structure: one in the ulPropTag member and the other in the ulPropTag member of the SPropValue structure pointed to by lpProp. In both tags, MAPI requires only the property type field and ignores the property identifier field. However, the two property types must match, or else the error value MAPI_E_TOO_COMPLEX is returned when the restriction is used in a call to IMAPITable::Restrict or IMAPITable::FindRow.

The values FL_FULLSTRING, FL_PREFIX, and FL_SUBSTRING are mutually exclusive. Only one of them can be set, and one of them must be set. Their meanings are fixed, and the provider must implement them exactly as defined. The provider should return MAPI_E_TOO_COMPLEX if it is unable to implement a specified code.

The flags FL_IGNORECASE, FL_IGNORENONSPACE, and FL_LOOSE are independent. Anywhere from zero to all three of them can be set. Their definitions are provided as a guideline only, and the provider is free to implement its own specific meaning of each flag. The provider should not return any error indication if it has no implementation of a specified flag.

The result of a restriction imposed against a property is undefined when the property does not exist. When a client requires well-defined behavior for such a restriction and is not sure whether the property exists — for example, it is not a required column of a table — it should create an AND restriction to join the content restriction with an exist restriction. Use an SExistRestriction structure to define the exist restriction and an SAndRestriction structure to define the AND restriction.

See Also

SPropValue, SRestriction


SCurrencyArray

The SCurrencyArray structure contains a property value of type PT_MV_CURRENCY for use in an SPropValue structure containing information about a multivalued property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SCurrencyArray

{

     ULONG         cValues;

     CURRENCY FAR *lpcur;

} SCurrencyArray;

Members

cValues

Count of values in the array pointed to by the lpcur member.

lpcur

Pointer to an array of CURRENCY structures containing the multiple values for the property.

Remarks

For more information on PT_MV_CURRENCY, see List of Property Types.

See Also

PropValue


SDateTimeArray

The SDateTimeArray structure contains a property value of type PT_MV_SYSTIME for use in an SPropValue structure containing information about a multivalued property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SDateTimeArray

{

     ULONG         cValues;

     FILETIME FAR *lpft;

} SDateTimeArray;

Members

cValues

Count of values in the array pointed to by the lpft member.

lpft

Pointer to an array of FILETIME structures containing the multiple values for the property.

Remarks

For more information on PT_MV_SYSTIME, see List of Property Types.

See Also

FILETIME, SPropValue


SDoubleArray

The SDoubleArray structure contains a property value of type PT_MV_DOUBLE for use in an SPropValue structure containing information about a multivalued property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SDoubleArray

{

     ULONG           cValues;

     double     FAR *lpdbl;

} SDoubleArray;

Members

cValues

Count of values in the array pointed to by the lpdbl member.

lpdbl

Pointer to the array of double values making up the property.

Remarks

For more information on PT_MV_DOUBLE, see List of Property Types.

See Also

SPropValue


SExistRestriction

The SExistRestriction structure describes an exist restriction, which is used to test whether or not a particular property exists.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SExistRestriction

{

     ULONG ulReserved1;

     ULONG ulPropTag;

     ULONG ulReserved2;

} SExistRestriction;

Members

ulReserved1

Reserved; must be zero.

ulPropTag

Property tag identifying the property to be tested for existence.

ulReserved2

Reserved; must be zero.

Remarks

The exist restriction is used to guarantee meaningful results for other types of restrictions that involve properties, such as property and content restrictions. When a restriction that involves a property is passed to IMAPITable::Restrict or IMAPITable::FindRow and the property does not exist, the results of the restriction are undefined. By creating an AND restriction that joins the property restriction with an exist restriction, a caller can be guaranteed accurate results.

Exist restrictions cannot be used with subobject properties, or properties that have type PT_OBJECT.

See Also

SRestriction


SGuidArray

The SGuidArray structure contains a property value of type PT_MV_CLSID for use in an SPropValue structure containing information about a multivalued property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SGuidArray

{

     ULONG     cValues;

     GUID      FAR *lpguid;

} SGuidArray;

Members

cValues

Count of values in the array pointed to by the lpguid member.

lpguid

Pointer to an array of property values for use in the SPropValue structure.

Remarks

For more information on PT_MV_CLSID, see List of Property Types.

See Also

GUID, SPropValue


SLargeIntegerArray

The SLargeIntegerArray structure contains a property value of type PT_MV_I8 for use in an SPropValue structure containing information about a multivalued property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SLargeIntegerArray

{

     ULONG     cValues;

     LARGE_INTEGER      FAR *lpli;

} SLargeIntegerArray;

Members

cValues

Count of values in the array pointed to by the lpli member.

lpli

Pointer to an array of LARGE_INTEGER structures holding the multiple values for the property.

Remarks

For more information on PT_MV_18, see List of Property Types.

See Also

LARGE_INTEGER, SPropValue


SLongArray

The SLongArray structure contains a property value of type PT_MV_LONG for use in an SPropValue structure containing information about a multivalued property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SLongArray

{

     ULONG     cValues;

     LONG      FAR *lpl;

} SLongArray;

Members

cValues

Count of values in the array pointed to by the lpl member.

lpl

Pointer to the array of long values making up the property.

Remarks

For more information on PT_MV_LONG, see List of Property Types.

See Also

SPropValue


SLPSTRArray

The SLPSTRArray structure contains a property value of type PT_MV_STRING8 for use in an SPropValue structure containing information about a multivalued property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SLPSTRArray

{

     ULONG      cValues;

     LPSTR FAR *lppszA

} SLPSTRArray;

Members

cValues

Count of values in the array pointed to by the lppszA member.

lppszA

Pointer to the array of null-terminated 8-bit character strings making up the property.

Remarks

For more information on PT_MV_STRING8, see List of Property Types.

See Also

SPropValue


SMAPIFormInfoArray

The SMAPIFormInfoArray structure contains a list of pointers to IMAPIFormInfo interfaces.

Quick Info

Header file:	MAPIFORM.H
Related macro:	CbMAPIFormInfoArray
typedef struct

{

     ULONG          cForms;

     LPMAPIFORMINFO aFormInfo[MAPI_DIM];

} SMAPIFormInfoArray, FAR * LPSMAPIFORMINFOARRAY;

Members

cForms

Count of IMAPIFormInfo interface pointers in the array in the aFormInfo member.

aFormInfo

Array of pointers to IMAPIFormInfo interface implementations.

Remarks

The SMAPIFormInfoArray structure is passed as a parameter in the IMAPIFormMgr methods ResolveMultipleMessageClasses, CalcFormPropSet, SelectMultipleForms and the IMAPIFormContainer method ResolveMultipleMessageClasses.

See Also

IMAPIFormContainer::ResolveMultipleMessageClasses, IMAPIFormMgr::CalcFormPropSet, IMAPIFormMgr::ResolveMultipleMessageClasses, IMAPIFormMgr::SelectMultipleForms


SMAPIFormProp

The SMAPIFormProp structure contains a form property used with form interfaces.

Quick Info

Header file:	MAPIFORM.H
typedef struct _SMAPIFormProp

{

     ULONG                    ulFlags;

     ULONG                    nPropType;

     MAPINAMEID               nmid;

     LPTSTR                   pszDisplayName;

     FORMPROPSPECIALTYPE      nSpecialType;

     union

     {

          struct

          {

          MAPINAMEID                 nmidIdx;

          ULONG                      cfpevAvailable;

          LPMAPIFormPropEnumVal      pfpevAvailable;

          } s1;

     } u;

} SMAPIFormProp;

Members

ulFlags

Contains MAPI_UNICODE if the strings in the structure are Unicode; zero if they are not.

nPropType

Property type of the form property, with the most significant word equal to zero.

nmid

MAPINAMEID structure containing the property’s globally unique identifier (GUID) and a form kind, made up of an interface identifier and the form’s name.

pszDisplayName

Pointer to the display name of the property.

nSpecialType

Special type tag defined in the FORMPROPSPECIALTYPE enumeration. This tag applies to the u union.

nmidIdx

The MAPINAMEID structure containing the identifier for the interface implementing the property.

cfpevAvailable

Count of SMAPIFormPropEnumVal structures in the array pointed to by the pfpevAvailable member.

pfpevAvailable

Pointer to an array of SMAPIFormPropEnumVal structures, each of which holds a value for a form property.

Remarks

The SMAPIFormProp structure contains information about a form property used as part of the definitions of the IMAPIFormInfo interface; nSpecialType contains a tag that applies to the u union that is part of SMAPIFormProp.

The FORMPROPSPECIALTYPE enumeration lists possible special type tags for the nSpecialType member of the SMAPIFormProp structure. In the FORMPROPSPECIALTYPE enumeration, the FPST_VANILLA member indicates that no enumeration is used, and the FPST_ENUM_PROP member indicates the enumeration contains a MAPI property.

See Also

MAPINAMEID, SMAPIFormPropEnumVal


SMAPIFormPropArray

The SMAPIFormPropArray structure contains a list of form properties — SMAPIFormProp structures.

Quick Info

Header file:	MAPIFORM.H
Related macro:	CbMAPIFormPropArray
typedef struct

{

     ULONG         cProps;

     ULONG         ulPad;

     SMAPIFormProp aFormProp[MAPI_DIM];

} SMAPIFormPropArray, FAR * LPMAPIFORMPROPARRAY;

Members

cProps

Count of verbs in the list.

ulPad

An eight-byte pad used for alignment of the SMAPIFormPropArray.

aFormProp

Name of the first form property in the list.

Remarks

The SMAPIFormPropArray structure is passed as a parameter in the methods IMAPIFormInfo::CalcFormPropSet, IMAPIFormMgr::CalcFormPropSet, and IMAPIFormContainer::CalcFormPropSet.

See Also

CbMAPIFormPropArray, IMAPIFormContainer::CalcFormPropSet, IMAPIFormInfo::CalcFormPropSet, IMAPIFormMgr::CalcFormPropSet, SMAPIFormProp


SMAPIFormPropEnumVal

The SMAPIFormPropEnumVal structure contains a value of a form property that will be used as part of the SMAPIFormProp structure.

Quick Info

Header file:	MAPIFORM.H
typedef struct _SMAPIFormPropEnumVal

{

     SPropValue     val;

     ULONG          nVal;

} SMAPIFormPropEnumVal;

Members

val

An SPropValue structure containing information about the form property.

nVal

An enumeration value for the structure in the val member.

Remarks

The SMAPIFormProp structure contains form property information used in forms definitions.

See Also

SMAPIFormProp, SPropValue


SMAPIVerb

The SMAPIVerb structure contains arrays of MAPI verbs.

Quick Info

Header file:	MAPIFORM.H
typedef struct

{

     LONG    lVerb;

     LPTSTR  szVerbname;

     DWORD   fuFlags;

     DWORD   grfAttribs;

     ULONG   ulFlags;                 /* Either 0 or MAPI_UNICODE */

} SMAPIVerb, FAR * LPMAPIVERB;

Members

lVerb

Numeric value for the verb.

szVerbname

Character string containing the name of the verb.

fuFlags

Flags for the verb.

grfAttribs

Attributes of the verb.

ulFlags

Bitmask of flags. If the szVerbname member has Unicode format, the following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

Remarks

The SMAPIVerb structure is passed as a parameter in the IMAPIFormMgr and IMAPIFormContainer method ResolveMultipleMessageClasses.

See Also

CbMessageClassArray, IMAPIFormContainer::ResolveMultipleMessageClasses, IMAPIFormMgr::ResolveMultipleMessageClasses


SMAPIVerbArray

The SMAPIVerbArray structure contains a list of MAPI verbs — SMAPIVerb structures.

Quick Info

Header file:	MAPIFORM.H
Related macro:	CbMAPIVerbArray
typedef struct

{

     ULONG     cMAPIVerb;

     SMAPIVerb aMAPIVerb[MAPI_DIM];

} SMAPIVerbArray, FAR * LPMAPIVERBARRAY;

Members

cForms

Count of verbs in the list.

aFormInfo

Indicates the first verb in the list.

Remarks

The SMAPIVerbArray structure is passed as a parameter in the IMAPIFormInfo::CalcVerbSet method.

See Also

IMAPIFormInfo::CalcVerbSet, SMAPIVerb


SMessageClassArray

The SMessageClassArray structure contains a list of message class string pointers.

Quick Info

Header file:	MAPIDEFS.H
Related macro:	CbMessageClassArray
typedef struct

{

     ULONG   cValues;

     LPCSTR  aMessageClass[MAPI_DIM];

} SMessageClassArray, FAR * LPSMESSAGECLASSARRAY;

Members

cValues

Count of message class string pointers in this structure.

aMessageClass

Names the first pointer in the list of message class string pointers.

Remarks

The SMessageClassArray structure is passed as a parameter in the IMAPIFormMgr and IMAPIFormContainer method ResolveMultipleMessageClasses.

See Also

IMAPIFormContainer::ResolveMultipleMessageClasses, IMAPIFormMgr::ResolveMultipleMessageClasses


SNotRestriction

The SNotRestriction structure describes a NOT restriction, which is used to join a group of restrictions using a logical NOT operation.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SNotRestriction

{

     ULONG           ulReserved;

     LPSRestriction  lpRes;

} SNotRestriction;

Members

ulReserved

Reserved; must be zero.

lpRes

Pointer to the group of restrictions that are to be joined with the logical NOT operator.

See Also

SRestriction


SOrRestriction

The SOrRestriction structure describes an OR restriction, which is used to join a group of restrictions using a logical OR operation.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SOrRestriction

{

     ULONG           cRes;

     LPSRestriction  lpRes;

} SOrRestriction;

Members

cRes

Count of structures in the array pointed to by the lpRes member.

lpRes

Pointer to an array of SRestriction structures defining the restrictions to be combined using the logical OR operation.

See Also

SRestriction


SPropAttrArray

The SPropAttrArray structure contains a list of attributes for properties of an object. SPropAttrArray is used only by property data objects, objects that implement the IPropData interface, and by MAPI's implementation of IMessage that is based on structured storage.

Quick Info

Header file:	IMESSAGE.H
Related macros:	CbNewSPropAttrArray CbSPropAttrArray
typedef struct

{

     ULONG     cValues;

     ULONG     aPropAttr[MAPI_DIM];

} SPropAttrArray, FAR *LPSPropAttrArray;

Members

cValues

Count of property attributes in the array in the aPropAttr member.

aPropAttr

An array of property attributes. Attributes that can be placed in this list are:

PROPATTR_MANDATORY

PROPATTR_READABLE

PROPATTR_WRITEABLE

PROPATTR_NOT_PRESENT


SPropertyRestriction

The SPropertyRestriction structure describes a property restriction, which is used to match a constant with the value of a property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SPropertyRestriction

{

     ULONG        relop;

     ULONG        ulPropTag;

     LPSPropValue lpProp;

} SPropertyRestriction;

Members

relop

Relational operator to be used in the search. Possible values are:

RELOP_GE

The comparison is made based on a greater or equal first value.

RELOP_GT

The comparison is made based on a greater first value.

RELOP_LE

The comparison is made based on a lesser or equal first value.

RELOP_LT

The comparison is made based on a lesser first value.

RELOP_NE

The comparison is made based on unequal values.

RELOP_RE

The comparison is made based on LIKE (regular expression) values.

RELOP_EQ

The comparison is made based on equal values.

ulPropTag

Property tag identifying the property in each message to be compared to the constant.

lpProp

Pointer to an SPropValue structure containing the constant value to be compared against.

Remarks

There are two property tags in an SContentRestriction structure: one in the ulPropTag member and the other in the ulPropTag member of the SPropValue structure pointed to by lpProp. In both tags, MAPI requires only the property type field and ignores the property identifier field. However, the two property types must match, or else the error value MAPI_E_TOO_COMPLEX is returned when the restriction is used in a call to IMAPITable::Restrict or IMAPITable::FindRow.

The comparison order is (property value) (relational operator) (constant value).

When a property restriction is passed to IMAPITable::Restrict or IMAPITable::FindRow and the target property does not exist, the results of the restriction are undefined. By creating an AND restriction that joins the property restriction with an exist restriction, a caller can be guaranteed accurate results. Use an SExistRestriction structure to define the exist restriction and an SAndRestriction structure to define the AND restriction.

Multivalued properties can be used in property restrictions if the service provider implementing the table supports them. If supported, multivalued property tags can be used anywhere single valued property tags can be used. They can be used in IMAPIProp::SetProps, IMAPIProp::GetProps, IMAPITable::SetColumns, IMAPITable::SortTable, and IMAPITable::Restrict.

See Also

SPropValue, SRestriction


SPropProblem

The SPropProblem structure describes an error relating to a particular property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SPropProblem

{

     ULONG     ulIndex;

     ULONG     ulPropTag;

     SCODE     scode;

} SPropProblem, FAR *LPSPropProblem;

Members

ulIndex

An index in an array of property tags.

ulPropTag

Property tag for the property.

scode

Error value indicating the property problem encountered during the update. This value can be any SCODE value.

Remarks

An SPropProblem structure contains an SCODE error value that is a result of an operation attempting to modify or delete a MAPI property.

See Also

SCODE, SPropProblemArray


SPropProblemArray

The SPropProblemArray structure contains an array of one or more SPropProblem structures, each of which holds an SCODE error value that is a result of an operation attempting to modify, delete, copy, or move a MAPI property.

Quick Info

Header file:	MAPIDEFS.H
Related macros:	CbNewSPropProblemArray CbSPropProblemArray SizedSPropProblemArray
typedef struct _SPropProblemArray
{

     ULONG          cProblem;

     SPropProblem   aProblem[MAPI_DIM];

} SPropProblemArray, FAR *LPSPropProblemArray;

Members

cProblem

Count of SPropProblem structures in the array indicated by the aProblem member.

aProblem

Array of SPropProblem structures, each describing a property error.

See Also

SCODE, SPropProblem


SPropTagArray

The SPropTagArray structure contains an array of property tags.

Quick Info

Header file:	MAPIDEFS.H
Related macros:	CbNewSPropTagArray CbSPropTagArray SizedSPropTagArray
typedef struct _SPropTagArray

{

     ULONG      cValues;

     ULONG      aulPropTag[MAPI_DIM];

} SPropTagArray, FAR *LPSPropTagArray;

Members

cValues

Count of property tags in the array indicated by the aulPropTag member.

aulPropTag

Array of property tags. Property tags are 32-bit unsigned integers consisting of the property’s unique identifier in the high order 16 bits and the property’s type in the low order 16 bits.

Remarks

A property tag is made up of two parts: an identifier and a type. The identifier is a numeric value that is assigned to a particular range. MAPI defines ranges for identifiers to describe what the property is used for and who is responsible for maintaining it. The type is a value that indicates the format for the property’s value. MAPI defines constants for each of the property types that it supports in the MAPIDEFS.H header file and each of the property tags it supports in the MAPITAGS.H header file.

For more information about property tags and their components, see one of the following topics:

About Property Tags

About Property Identifiers

About Property Types

For a complete list of the single-valued and multivalued property types, see the appendix, Property Identifiers and Types.


SPropValue

The SPropValue structure describes a MAPI property.

Quick Info

Header file:	MAPIDEFS.H
Related macros:	CHANGE_PROP_TYPE MVI_PROP PROP_ID PROP_TAG PROP_TYPE
typedef struct _SPropValue

{

     ULONG     ulPropTag;

     ULONG     dwAlignPad;

     union _PV  Value;

} SPropValue, FAR *LPSPropValue;

Members

ulPropTag

Property tag for the property. Property tags are 32-bit unsigned integers consisting of the property’s unique identifier in the high order 16 bits and the property’s type in the low order 16 bits.

dwAlignPad

Reserved for MAPI; do not use.

Value

Union of data values, the specific value dictated by the type of property. Property types are stored in the ulPropTag member.

Remarks

The ulPropTag member is made up of two parts: an identifier and a type. The identifier is a numeric value that is assigned to a particular range. MAPI defines ranges for identifiers to describe the purpose of the property and who is responsible for maintaining it. The type is a value that indicates the format for the property’s value. MAPI defines constants for each of the property types that it supports in the MAPIDEFS.H header file and each of the property tags it supports in the MAPITAGS.H header file.

For a complete list of the valid property ranges for identifiers and property types, see the Property Identifiers and Types appendix.

The dwAlignPad member is designed for computers that require 8-byte alignment for 8-byte values. This member makes it possible for clients and service providers to allocate an array of property values on an 8-byte boundary and have the array aligned correctly. Developers who write code on such computers should use memory allocation routines that allocate the SPropValue arrays on 8-byte boundaries. The property type designates which member of the union should be used. The Value member contains one of the members of the _UPV union, defined as follows:

typedef union _PV

{

     short int             i;

     LONG                  l;

     ULONG                 ul;

     float                 flt;

     double                dbl;

     unsigned short int    b;

     CURRENCY              cur;

     double                at;

     FILETIME              ft;

     LPSTR                 lpszA;

     SBinary               bin;

     LPWSTR                lpszW;

     LPGUID                lpguid;

     LARGE_INTEGER         li;

     SShortArray           MVi;

     SLongArray            MVl;

     SRealArray            MVflt;

     SDoubleArray          MVdbl;

     SCurrencyArray        MVcur;

     SAppTimeArray         MVat;

     SDateTimeArray        MVft;

     SBinaryArray          MVbin;

     SLPSTRArray           MVszA;

     SWStringArray         MVszW;

     SGuidArray            MVguid;

     SLargeIntegerArray    MVli;

     SCODE                 err;

     LONG                  x;

} _UPV;

The members of the _UPV union contain the following values for single valued properties:

_UPV member	Type of single valued property
i	PT_I2
I	PT_LONG (signed)
ul	PT_LONG (unsigned)
flt	PT_R4
dbl	PT_DOUBLE
b	PT_BOOLEAN
cur	PT_CURRENCY
at	PT_APPTIME
ft	PT_SYSTIME
lpszA	PT_STRING8
bin	PT_BINARY
lpszW	PT_UNICODE
lpguid	PT_CLSID
li	PT_I8
The following table lists the members of the _UPV union that describe multivalued properties:

_UPV member	Type of multivalued property
MVi	PT_MV_I2
MVI	PT_MV_LONG
MVflt	PT_MV_R4
MVdbl	PT_MV_DOUBLE
MVcur	PT_MV_CURRENCY
MVat	PT_MV_APPTIME
MVft	PT_MV_SYSTEM
MVbin	PT_MV_BINARY
MVszA	PT_MV_STRING8
MVszW	PT_MV_UNICODE
MVguid	PT_MV_CLSID
MVli	PT_MV_I8
The final two members of the _UPV union, err and x, describe property values with special types. The err member describes a property of type PT_ERROR and the x member a property of type PT_NULL or PT_OBJECT.


SRealArray

The SRealArray structure contains a property value of type PT_FLOAT for use in an SPropValue structure containing information about a multivalued property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SRealArray

{

     ULONG     cValues;

     float     FAR *lpflt;

} SRealArray;

Members

cValues

Count of values in the array pointed to by the lpflt member.

lpflt

Pointer to an array of float values making up the property.

Remarks

For more information on PT_FLOAT, see List of Property Types.

See Also

SPropValue


SRestriction

The SRestriction structure describes a filter for limiting the view of a table to particular rows.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SRestriction

{

     ULONG     rt;

     union

     {

          SComparePropsRestriction    resCompareProps;

          SAndRestriction             resAnd;

          SOrRestriction              resOr;

          SNotRestriction             resNot;

          SContentRestriction         resContent;

          SPropertyRestriction        resProperty;

          SBitMaskRestriction         resBitMask;

          SSizeRestriction            resSize;

          SExistRestriction           resExist;

          SSubRestriction             resSub;

          SCommentRestriction         resComment;

     } res;

} SRestriction;

Members

rt

Indicates the restriction type. Possible values are:

Value of rt member	Description
RES_AND	Applies a logical AND operation to a group of restrictions.
RES_BITMASK	Applies a bitmask to a property.
RES_COMMENT	Associates a comment with a restriction.
RES_COMPAREPROPS	Compares two property values.
RES_CONTENT	Searches a property to determine if it contains a particular value.
RES_EXIST	Determines if a property exists.
RES_NOT	Applies a logical NOT operation to a group of restrictions.
RES_OR	Applies a logical OR operation to a group of restrictions.
RES_PROPERTY	Determines if the value of a property matches a particular value.
RES_SIZE	Determines if the value of a property is a particular size.
RES_SUBRESTRICTION	Applies a restriction to a message’s attachments or recipients.
res

Union of restriction structures describing the type of filters to be applied. The structure included in the res member depends on the value of the rt member. The following table relates restriction types with the corresponding type of restriction structure.

Value of rt member	Structure type of res member
RES_AND	SAndRestriction
RES_BITMASK	SBitMaskRestriction
RES_COMMENT	SCommentRestriction
RES_COMPAREPROPS	SComparePropsRestriction
RES_CONTENT	SContentRestriction
RES_EXIST	SExistRestriction
RES_NOT	SNotRestriction
RES_OR	SOrRestriction
RES_PROPERTY	SPropertyRestriction
RES_SIZE	SSizeRestriction
RES_SUBRESTRICTION	SSubRestriction
Remarks

A client application uses SRestriction structures in calls to the IMAPITable::Restrict and (for search-results folders) IMAPIContainer::SetSearchCriteria methods. A client can also use SRestriction with the IMAPITable::FindRow method to find table rows with certain attributes.

These three methods use SRestriction structures to filter out rows in the table.

See Also

SAndRestriction, SBitMaskRestriction, SCommentRestriction, SComparePropsRestriction, SContentRestriction, SExistRestriction, SNotRestriction, SOrRestriction, SPropertyRestriction, SSizeRestriction, SSubRestriction, IMAPIContainer::SetSearchCriteria, IMAPITable::FindRow, IMAPITable::Restrict


SRow

The SRow structure describes a row from a table containing selected properties for a specific object.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SRow

{

     ULONG         ulAdrEntryPad;

     ULONG         cValues;

     LPSPropValue  lpProps;

} SRow, FAR *LPSRow;

Members

ulAdrEntryPad

Padding bytes to properly align the property values pointed to by the lpProps member.

cValues

Count of property values pointed to by lpProps.

lpProps

Pointer to an array of SPropValue structures that describe the property values for the columns in the row.

Remarks

When a service provider makes a call to ITableData::HrQueryRow to retrieve a single row of data from a table or receives a table notification that includes a TABLE_NOTIFICATION structure with the OnNotify call, the data for the row is described with an SRow structure. An SRow structure contains a count of columns in the row and an array of property values, or SPropValue structures, that describe the column set.

When more than one row is returned, the data is described using an SRowSet structure. An SRowSet structure contains an array of SRow structures and a count of structures in the array.

The following illustration shows the relationship between an SRow and an SRowSet data structure.

For information about how the memory for SRow structures should be allocated, see Managing Memory for ADRLIST and SRowSet Structures.

See Also

ITableData::HrQueryRow, TABLE_NOTIFICATION,

SPropValue, SRowSet


SRowSet

The SRowSet structure describes multiple rows from a table. Each row contains selected properties for a specific object.

Quick Info

Header file:	MAPIDEFS.H
Related macros:	CbNewSRowSet CbSRowSet SizedSRowSet
typedef struct _SRowSet
{
     ULONG   cRows;
     SRow    aRow[MAPI_DIM];
} SRowSet, FAR *LPSRowSet;

Members

cRows

Count of SRow structures in the aRow member.

aRow

Array of SRow structures, one for each row in the table.

Remarks

An SRowSet structure is used to describe multiple rows of data from a table. Clients and service providers are given SRowSet structures when they call IMAPITable::QueryRows and HrQueryAllRows. An SRowSet structure contains multiple SRow structures and a count of the total number of rows.

Because the layout is the same for SRowSet and ADRLIST structures and for SRow and ADRENTRY structures, SRowSet structures can be cast into ADRLIST structures and passed to methods such as IMessage::ModifyRecipients and IAddrBook::Address.

The rules for memory allocation for SRowSet structures are the same as for ADRLIST structures. To summarize, each SPropValue structure in the array pointed to by the lpProps member of each row in the row set must be allocated separately using MAPIAllocateBuffer. Each property value structure also must be deallocated prior to the deallocation of its SRowSet so that pointers to the allocated SPropValue structures are not lost. A row’s allocated memory can then be preserved and reused outside of the context of the SRowSet. For more information about how the memory for SRowSet structures should be allocated, see Managing Memory for ADRLIST and SRowSet Structures.

See Also

IMAPITable::QueryRows, ADRLIST, SRow


SShortArray

The SShortArray structure contains a property value of type PT_MV_SHORT for use in an SPropValue structure containing information about a multivalued property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SShortArray

{

     ULONG              cValues;

     short int     FAR *lpi;

} SShortArray;

Members

cValues

Count of values in the array pointed to by the lpi member.

lpi

Pointer to an array of values making up the property.

Remarks

For more information on PT_MV_SHORT, see List of Property Types.

See Also

SPropValue


SSizeRestriction

The SSizeRestriction structure describes a size restriction, which is used to test the size of a property value.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SSizeRestriction

{

     ULONG relop;

     ULONG ulPropTag;

     ULONG cb;

} SSizeRestriction;

Members

relop

Relational operator used in the size comparison. Possible values are:

RELOP_GE

The comparison is made based on a greater or equal first value.

RELOP_GT

The comparison is made based on a greater first value.

RELOP_LE

The comparison is made based on a lesser or equal first value.

RELOP_LT

The comparison is made based on a lesser first value.

RELOP_NE

The comparison is made based on unequal values.

RELOP_RE

The comparison is made based on LIKE (regular expression) values.

RELOP_EQ

The comparison is made based on equal values.

ulPropTag

Property tag identifying the property to test.

cb

Count of bytes in the property value.

See Also

SRestriction


SSortOrder

The SSortOrder structure defines the sort order of data in a table.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SSortOrder

{

     ULONG ulPropTag;

     ULONG ulOrder;

} SSortOrder, FAR *LPSSortOrder;

Members

ulPropTag

Property tag identifying the sort key column.

ulOrder

The order in which the data is to be sorted. Possible values are:

TABLE_SORT_ASCEND

The table should be sorted in ascending order.

TABLE_SORT_COMBINE

This category, as identified by the ulPropTag member, should be combined with the ulPropTag member of the previous sort order to form a sort key. This flag is only valid with categorized tables that specify multiple sort orders in a SSortOrderSet structure.

TABLE_SORT_DESCEND

The table should be sorted in descending order.

Remarks

Client applications and service providers use an SSortOrder structure for specifying a sort key for a table.

The ulPropTag member can always be set to a property tag for a column in the current view. Support for sort keys defined with available columns that are not in the current view, although valuable, depends on the implementer of the table. Some tables support these extra sort key columns; others do not. An available column is a column that is returned from IMAPITable::QueryColumns when the TBL_ALL_COLUMNS flag is set.

The ulOrder member indicates both directional order and categorization information. Rows can be sorted in either an ascending or descending sequence with all NULL entries placed last. The ulOrder member can be set to TABLE_ASCEND, TABLE_DESCEND, or TABLE_SORT_COMBINE, for categorized tables.

The TABLE_SORT_COMBINE value indicates that the column specified in ulPropTag should be combined with the previous category column to form a composite category. That is, instead of categorizing on unique values of individual columns, TABLE_SORT_COMBINE allows categorization on unique values of a combination of columns. A single category could be defined, for example, to group messages received from a particular sender on a particular subject. Using TABLE_SORT_COMBINE reduces the number of category rows which are displayed.

Sorting on multivalued columns is not universally supported by all table implementations. If supported, apply the MV_FLAG using the MVI_PROP macro to the property tag in the ulPropTag member to identify the sort key as a multivalued column. Sorting on a multivalued column is based on using the individual values.

For more information about standard and categorized sorting, see Sorting and Categorization.

See Also

SSortOrderSet


SSortOrderSet

The SSortOrderSet structure defines a collection of sort keys for a table to be used for standard or categorized sorting.

Quick Info

Header file:	MAPIDEFS.H
Related macros:	CbNewSSortOrderSet CbSSortOrderSet SizedSSortOrderSet
typedef struct _SSortOrderSet

{

     ULONG      cSorts;

     ULONG      cCategories;

     ULONG      cExpanded;

     SSortOrder aSort[MAPI_DIM];

} SSortOrderSet, FAR *LPSSortOrderSet;

Members

cSorts

Count of sort orders that are defined in the aSort member.

cCategories

Count of columns that are designated as category columns. Possible values range from zero, which indicates a noncategorized sort, up to the number indicated by the cSorts member.

cExpanded

Count of categories that start in an expanded state.

aSort

Array of SSortOrder structures, each defining a sort order.

Remarks

Clients and service providers use an SSortOrderSet structure for defining multiple sort orders for standard and categorized sorting.

When there are more columns than there are categories, the first columns are used for the categorization. For example, consider the situation where cCategories is set to two and there are three columns defined as sort keys in the SSortOrderSet structure: sender name, subject, and date received. Sender name is the top level category grouping; subject is the secondary grouping. Every leaf row that has columns with values that match the two category columns is ordered by date received, so that the expanded display for such a grouping appears as shown in the following illustration.

The cExpanded member specifies the number of categories that are initially expanded. When there are multiple categories, the table implementation begins with the first column to be designated as a category and continues in sequential order with the subsequent category columns until the number of cCategories has been exceeded. If there are more category columns than there are expanded columns, the category columns are collapsed. If cExpanded is equal to zero, only the top level heading row is available to the table user for display. If cExpanded is equal to one less than the number of categories, then all of the heading rows but none of the leaf rows are available. If cExpanded is equal to the number of categories, then the table is fully expanded.

For more information about standard and categorized sorting, see Sorting and Categorization.

See Also

IMAPITable::ExpandRow, IMAPITable::CollapseRow


SSubRestriction

The SSubRestriction structure describes a subobject restriction, which is used to impose a restriction against a message’s attachments or recipients.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SSubRestriction

{

     ULONG          ulSubObject;

     LPSRestriction lpRes;

} SSubRestriction;

Members

ulSubObject

Subobject identified in the RES_SUBRESTRICTION restriction type supplied for the rt member of the SRestriction structure. Possible values are PR_MESSAGE_RECIPIENTS or PR_MESSAGE_ATTACHMENTS.

lpRes

Pointer to an SRestriction structure.

Remarks

The most common objects to support subrestrictions are folder contents tables and search-results folders. These objects may support restricting a search using PR_MESSAGE_ATTACHMENTS or PR_MESSAGE_RECIPIENTS as a restriction to find a message that has an attachment or a recipient that meets the other given restrictions. If an implementation does not support subrestrictions, it returns for a subrestricted search the error value MAPI_E_TOO_COMPLEX.

See Also

SRestriction


STATUS_OBJECT_NOTIFICATION

The STATUS_OBJECT_NOTIFICATION structure describes changes that were made to a status object.

Quick Info

Header file:	MAPIDEFS.H
typedef struct

{

     ULONG         cbEntryID;

     LPENTRYID     lpEntryID;

     ULONG         cValues;

     LPSPropValue  lpPropVals;

} STATUS_OBJECT_NOTIFICATION;

Members

cbEntryID

Count of bytes in the entry identifier pointed to by the lpEntryID member.

lpEntryID

Pointer to the entry identifier of the changed status object.

cValues

Count of SPropValue structures in the array pointed to by the lpPropVals member.

lpPropVals

Pointer to an array of SPropValue structures, one property value structure for each changed property of the status object.

Remarks

The STATUS_OBJECT_NOTIFICATION structure is one of the members of the union of structures included in the info member of the NOTIFICATION structure. When the info member of a NOTIFICATION structure contains a TABLE_NOTIFICATION structure, the ulEventType member of the NOTIFICATION structure is set to fnevStatusObjectModified. Status object notification is an internal MAPI notification; clients and service providers cannot register for it and service providers cannot generate it.

For more information about notification, see the topics described in the following table.

Topic	Description
Event Notification in MAPI	General overview of notification and notification events.
Handling Notifications	Discussion of how clients should handle notifications.
Using a Support Object for Event Notification	Discussion of how service providers can use the IMAPISupport method to generate notifications.
See Also

NOTIFICATION, SPropValue


STnefProblem

The STnefProblem structure contains information about a property or attribute processing problem that occurred during the encoding or decoding of a Transport-Neutral Encapsulation Format (TNEF) stream.

Quick Info

Header file:	TNEF.H
typedef struct _STnefProblem

{

     ULONG     ulComponent;

     ULONG     ulAttribute;

     ULONG     ulPropTag;

     SCODE     scode;

} STnefProblem;

Members

ulComponent

The type of processing during which the problem occurred. If the problem occurred during message processing, the ulComponent member is set to zero. If the problem occurred during attachment processing, ulComponent is set equal to the corresponding attachment’s PR_ATTACH_NUM value.

ulAttribute

The attribute corresponding to the ulPropTag member, except when the TNEF processing problem arises while decoding an encapsulation block. In this case, the ulAttribute member can have the following possible values:

attMAPIProps

Message level

attAttachment

Attachment level

ulPropTag

Property tag of the property that caused the TNEF processing problem, except when the problem arises while decoding an encapsulation block, in which case ulPropTag is set to zero.

scode

Error value indicating the problem encountered during processing.

Remarks

If an STnefProblem structure is not generated during the processing of an attribute or property, the application can continue under the assumption that the processing of that attribute or property succeeded. The only exception occurs when the problem arose during decoding of an encapsulation block. In this case, the decoding of the component corresponding to the block is halted and decoding is continued in another component.

See Also

STnefProblemArray


STnefProblemArray

The STnefProblemArray structure lists one or more property or attribute processing problems that occurred during the encoding or decoding of a Transport-Neutral Encapsulation Format (TNEF) stream.

Quick Info

Header file:	TNEF.H
typedef struct _STnefProblemArray

{

     ULONG           cProblem;

     STnefProblem    aProblem[MAPI_DIM];

}STnefProblemArray, FAR * LPSTnefProblemArray

Members

cProblem

Count of elements in the array in the aProblem member.

aProblem

Array of STnefProblem structures. Each structure contains information about a property or attribute processing problem.

Remarks

If a problem occurs during attribute or property processing, an output parameter in the ITnef::ExtractProps method and in the ITnef::Finish method each receive a pointer to an STnefProblemArray structure and ExtractProps and Finish each return the value MAPI_W_ERRORS_RETURNED. This error value indicates that a problem arose during processing and an STnefProblemArray structure was generated.

If an STnefProblem structure is not generated during the processing of an attribute or property, the client application can continue under the assumption that the processing of that attribute or property succeeded. The only exception occurs when the problem arose during decoding of an encapsulation block. If the error occurred during this decoding, MAPI_E_UNABLE_TO_COMPLETE can be returned as the SCODE in the structure. In this case, the decoding of the component corresponding to the block is halted and decoding is continued in another component.

See Also

ITnef::ExtractProps, ITnef::Finish, STnefProblem


SWStringArray

The SWStringArray structure contains a property value of type PT_MV_UNICODE for use in an SPropValue structure containing information about a multivalued property.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _SWStringArray

{

     ULONG           cValues;

     LPWSTR     FAR *lppszW;

} SWStringArray;

Members

cValues

Count of values in the array pointed to by the lppszW member.

lppszW

Pointer to the array of null-terminated Unicode string values making up the property.

Remarks

For more information on PT_MV_UNICODE, see List of Property Types.

See Also

SPropValue


TABLE_NOTIFICATION

The TABLE_NOTIFICATION structure describes a row in a table that has been affected by some type of event, such as a change or an error, causing a table notification to be generated.

Quick Info

Header file:	MAPIDEFS.H
typedef struct _TABLE_NOTIFICATION

{

     ULONG        ulTableEvent;

     HRESULT      hResult;

     SPropValue   propIndex;

     SPropValue   propPrior;

     SRow         row;

} TABLE_NOTIFICATION;

Members

ulTableEvent

Bitmask of flags used to represent the table event type. The following flags can be set:

TABLE_CHANGED

Indicates at a high level that something about the table has changed. The table’s state is as it was before the event, meaning that all PR_INSTANCE_KEY properties, bookmarks, current positioning, and user interface selections are still valid.

Handle this event by re-reading the entire table. Service providers that do not want to implement “rich” table notifications simply send TABLE_CHANGED events rather than more detailed events to indicate a particular type of change.

TABLE_ERROR

An error has occurred, usually during the processing of an asynchronous operation. Errors during the processing of the following methods can generate this event:

IMAPITable::SortTable

IMAPITable::SetColumns

IMAPITable::Restrict

The IMAPITable::GetLastError method cannot provide any further information about the error because it was generated at some previous point, not necessarily from the last method call.

TABLE_RELOAD

The data in the table should be reloaded. Service providers send TABLE_RELOAD when, for example, the underlying data is stored in a database and the database is replaced.

Handle this event by assuming that nothing about the table is still valid and by re-reading the entire table. All bookmarks, instance keys, status and positioning information are invalid.

TABLE_RESTRICT_DONE

A restriction operation initiated with an IMAPITable::Restrict method call has completed.

TABLE_ROW_ADDED

A new row has been added to the table and the corresponding object saved. TABLE_ROW_ADDED events are generated after a call to the object’s IMAPIProp::SaveChanges method.

TABLE_ROW_DELETED

A row has been removed from the table. The propPrior member is set to NULL.

TABLE_ROW_MODIFIED

A row has been changed. The row member contains the affected properties for the row. Multiple TABLE_ROW_MODIFIED events are sent in the order that they appear in the table view.

TABLE_ROW_MODIFIED events are sent after changes to the corresponding object have been committed with a call to the object’s IMAPIProp::SaveChanges method. If the modified row is now the first row in the table, the the value of the property tag in the propPrior member is PR_NULL.

TABLE_SETCOL_DONE

A column setting operation initiated with an IMAPITable::SetColumns method call has competed.

TABLE_SORT_DONE

A table sorting operation initiated with an IMAPITable::SortTable method call has competed.

hResult

HRESULT value for the error that has occurred, if the ulTableEvent member is set to TABLE_ERROR.

propIndex

SPropValue structure for the PR_INSTANCE_KEY property of the affected row.

propPrior

SPropValue structure for the PR_INSTANCE_KEY property of the row preceding the affected one. If the affected row is the first row in the table, propPrior must be set to PR_NULL and not zero. Zero is not a valid property tag.

row

SRow structure containing the data for the affected row. This structure is filled for all table notification events, even if an event of the current type doesn’t require it. For table notification events that do not pass row data, the cValues member of the SRow structure is set to zero and lpProps member is NULL. This SRow structure is read-only; to make modifications, a copy must be made.

Remarks

The TABLE_NOTIFICATION structure is one of the members of the union of structures included in the info member of the NOTIFICATION structure. When the info member of a NOTIFICATION structure contains a TABLE_NOTIFICATION structure, the ulEventType member of the NOTIFICATION structure is set to fnevTableModified.

When table notifications are generated, a NOTIFICATION structure that includes a TABLE_NOTIFICATION structure in its info member is constructed. The TABLE_NOTIFICATION describes the change that has occurred to the table.

The properties that are included in the row member are ordered using the column set that was established from the previous IMAPITable::SetColumns call, if one occurred. If a SetColumns call has been made after the notification was generated, the column set described in the row member will not match the current set of columns. If no SetColumns call was made prior to the notification being sent, the columns are ordered in a default order decided by the table implementer.

For more information about notification, see the topics described in the following table.

Topic	Description
Event Notification in MAPI	General overview of notification and notification events.
Handling Notifications	Discussion of how clients should handle notifications.
Using a Support Object for Event Notification	Discussion of how service providers can use the IMAPISupport method to generate notifications.
Because table notifications are asynchronous, clients and service providers might receive a notification of an added row after they have learned of the addition.

They might receive a TABLE_ERROR event when there is an error in an IMAPITable::Sort, IMAPITable::Restrict, or IMAPITable::SetColumns method or when an underlying process attempts to update a table with, for example, new or modified rows.

See Also

IMAPITable::Restrict, IMAPITable::SetColumns, NOTIFICATION, SPropValue, SRow


Macros Related to Structures

The following alphabetized entries describe the macros related to MAPI structures. For more detailed information, cross references to other publications or to other topics in this documentation are also included.


CbADRLIST

The CbADRLIST macro computes the number of bytes of memory occupied by an existing ADRLIST structure.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	ADRLIST
int CbADRLIST (LPADRLIST _lpadrlist)

Parameters

_lpadrlist

Pointer to an ADRLIST structure.

Remarks

TheCbADRLIST macro returns the number of bytes occupied by the ADRLIST structure pointed to by the _lpadrlist parameter.


CbFLATENTRY

The CbFLATENTRY macro determines the number of bytes of memory occupied by an existing FLATENTRY structure.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	FLATENTRY
int CbFLATENTRY (LPFLATENTRY _lpentry)

Parameters

_lpentry

Pointer to a FLATENTRY structure.

Remarks

The CbFLATENTRY macro returns the number of bytes occupied by the FLATENTRY structure pointed to by _lpentry.


CbFLATENTRYLIST

The CbFLATENTRYLIST macro determines the number of bytes of memory occupied by an existing FLATENTRYLIST structure.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	FLATENTRYLIST
int CbFLATENTRYLIST (LPFLATENTRYLIST _lplist)

Parameters

_lplist

Pointer to a FLATENTRYLIST structure.

Remarks

The CbFLATENTRYLIST macro returns the number of bytes occupied by the FLATENTRY structure pointed to by _lplist.


CbFLATMTSIDLIST

The CbFLATMTSIDLIST macro determines the number of bytes of memory occupied by a FLATMTSIDLIST structure.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	FLATMTSIDLIST
int CbFLATMTSIDLIST (LPFLATMTSIDLIST _lplist)

Parameters

_lplist

Pointer to a FLATMTSIDLIST structure.

Remarks

The CbFLATMTSIDLIST macro returns the number of bytes occupied by the FLATMTSIDLIST structure pointed to by _lpentry.


CbMAPIFormInfoArray

The CbMAPIFormInfoArray macro determines the minimum number of bytes required to hold an SMAPIFormInfoArray containing a specified number of IMAPIFormInfo interface pointers.

Quick Info

Header file:	MAPIFORM.H
Related structure:	SMAPIFormInfoArray
int CbMAPIFormInfoArray (int  _c)

Parameters

_c

Count of IMAPIFormInfo interface pointers.

Remarks

The CbMAPIFormInfoArray macro returns the number of bytes of memory needed to hold a SMAPIFormInfoArray containing the number of interface pointers specified by _c.


CbMAPIFormPropArray

The CbMAPIFormPropArray macro determines the memory allocation requirements for an SMAPIFormPropArray containing a specified number of form properties, that is a specified number of SMAPIFormProp structures.

Quick Info

Header file:	MAPIFORM.H
Related structure:	SMAPIFormPropArray
int CbMAPIFormPropArray (int  _c)

Parameters

_c

Count of form properties.

Remarks

The CbMAPIFormPropArray macro returns the number of bytes of memory needed to hold an SMAPIFormPropArray containing the number of form properties specified by _c.


CbMAPIVerbArray

The CbMAPIVerbArray macro determines the memory allocation requirements of an SMAPIVerbArray containing a specified number of verbs, that is a specified number of SMAPIVerb structures.

Quick Info

Header file:	MAPIFORM.H
Related structure:	SMAPIVerbArray
int CbMAPIVerbArray (int  _c)

Parameters

_c

Count of verbs.

Remarks

The CbMAPIVerbArray macro returns the number of bytes of memory needed to hold an SMAPIVerbArray containing the number of verbs specified by _c.


CbMessageClassArray

The CbMessageClassArray macro determines the minimum number of bytes required to hold an SMessageClassArray containing a specified number of message class string pointers.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SMessageClassArray
int CbMessageClassArray (int  _c)

Parameters

_c

Count of message class string pointers.

Remarks

The CbMessageClassArray macro returns the number of bytes of memory needed to hold a SMessageClassArray containing the number of pointers specified by _c.


CbMTSID

The CbMTSID macro determines the number of bytes of memory occupied by a MTSID structure.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	MTSID
int CbFLATENTRYLIST (LPMTSID _lpentry)

Parameters

_lpentry

Pointer to an MTSID structure.

Remarks

The CbMTSID macro returns the number of bytes occupied by the MTSID structure pointed to by _lpentry.


CbNewADRLIST

The CbNewADRLIST macro determines the memory allocation requirements of an ADRLIST structure containing a specified number of ADRENTRY structures (recipients).

Quick Info

Header file:	MAPIDEFS.H
Related structure:	ADRLIST
int CbNewADRLIST (int _centries)

Parameters

_centries

Count of recipients.

Remarks

The CbNewADRLIST macro returns the number of bytes of memory that an ADRLIST structure containing the number of recipients specified by the _centries parameter would occupy.


CbNewENTRYID

The CbNewENTRYID macro determines the memory allocation requirements of an ENTRYID structure with an entry identifier of a specified byte size.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	ENTRYID
int CbNewENTRYID (int _cb)

Parameters

_cb

Count of bytes used for the entry identifier.

Remarks

The CbNewENTRYID macro returns the size, in bytes, of an ENTRYID containing a _cb byte entry identifier.


CbNewFLATENTRY

The CbNewFLATENTRY macro determines the memory allocation requirements of a FLATENTRY structure containing an entry identifier of a specified byte size.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	FLATENTRY
int CbNewFLATENTRY (int _cb)

Parameters

_cb

The entry identifier byte size.

Remarks

The CbNewFLATENTRY macro returns the number of bytes of memory that a FLATENTRY with a _cb byte entry identifier would occupy.


CbNewFLATENTRYLIST

The CbNewFLATENTRYLIST macro determines the memory allocation requirements of a FLATENTRYLIST whose list of FLATENTRY structures is of a specified byte size.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	FLATENTRYLIST
int CbNewFLATENTRY (int _cb)

Parameters

_cb

Byte size of the list of FLATENTRY structures.

Remarks

The CbNewFLATENTRYLIST macro returns the number of bytes in memory that a FLATENTRYLIST with a _cb byte FLATENTRY list would occupy.


CbNewFLATMTSIDLIST

The CbNewFLATMTSIDLIST macro determines the memory allocation requirements of a FLATMTSIDLIST structure whose list of MTSID structures is of a specified byte size.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	FLATMTSIDLIST
int CbNewMTSID (int _cb)

Parameters

_cb

The byte size of the MTSID list.

Remarks

The CbNewFLATMTSIDLIST macro returns the number of bytes of memory occupied by a FLATMTSIDLIST with a _cb byte MTSID list.


CbNewMTSID

The CbNewMTSID macro determines the memory allocation requirements of an MTSID structure using a specified number of bytes for its message transfer agent identifier.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	MTSID
int CbNewMTSID (int _cb)

Parameters

_cb

Byte size of the identifier, a message transfer agent.

Remarks

The CbNewMTSID macro returns the number of bytes of memory occupied by an MTSID structure with a _cb byte message transfer agent identifier.


CbNewSPropAttrArray

The CbNewSPropAttrArray macro determines the memory allocation requirement of an SPropAttrArray structure containing a specified number of property attributes.

Quick Info

Header file:	IMESSAGE.H
Related structure:	SPropAttrArray
int CbNewSPropAttrArray (int  _c)

Parameters

_c

Count of property attributes.

Remarks

The CbNewSPropAttrArray macro returns the number of bytes of memory needed to hold an SPropAttrArray containing the number of property attributes specified by _c.


CbNewSPropProblemArray

The CbNewSPropProblemArray macro determines the memory allocation requirements of a SPropProblemArray structure containing a specified number of SPropProblem structures.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SPropProblemArray
int CbNewSPropProblemArray (int_cprob)

Parameters

_cprob

Count of SPropProblem structures.

Remarks

The CbNewSPropProblemArray macro returns the number of bytes of memory occupied by an SPropProblemArray structure that contains the number of SPropProblem structures specified by _cprob.


CbNewSPropTagArray

The CbNewSPropTagArray macro determines the memory allocation requirements of an SPropTagArray structure containing a specified number of property tags.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SPropTagArray
int CbNewSPropTagArray (int _ctag)

Parameters

_ctag

Count of property tags.

Remarks

The CbNewSPropTagArray macro returns the number of bytes of memory occupied by an SPropTagArray structure that contains the number of property tags specified by _ctag.


CbNewSRowSet

The cbNewSRowSet macro determines the memory allocation requirements of an SRowSet structure containing a specified number of rows.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SRowSet
int CbNewSRowSet (int _crow)

Parameters

_crow

Count of rows, that is the number of elements of type SRow in the aRow member.

Remarks

The CbNewSRowSet macro returns the number of bytes of memory that an SRowSet with the number of rows specified by _crow would occupy.


CbNewSSortOrderSet

The CbNewSSortOrderSet macro determines the memory allocation requirements of an SSortOrderSet structure containing a specified number of sort orders.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SSortOrderSet
CbNewSSortOrderSet (_csort)

Parameters

_csort

Count of sort orders, that is, the number of elements of type SSortOrder in the aSort member.

Remarks

The CbNewSSortOrderSet macro returns the number of bytes of memory that an SSortOrderSet with the number of sort orders specified by _csort would occupy.


CbSPropAttrArray

The CbSPropAttrArray macro determines the number of bytes occupied by an existing SPropAttrArray structure.

Quick Info

Header file:	IMESSAGE.H
Related structure:	SPropAttrArray
int CbSPropAttrArray (LPSPROPATTRARRAY _lparray)

Parameters

_lparray

Pointer to an SPropAttrArray structure.

Remarks

The CbSPropAttrArray macro returns the number of bytes of memory occupied by the SPropAttrArray structure.


CbSPropProblemArray

The CbSPropProblemArray macro determines the number of bytes in an existing SPropProblemArray.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SPropProblemArray
int CbSPropProblemArray (LPSPropProblemArray _lparray)

Parametersc

_lparray

Pointer to an SPropProblemArray structure.

Remarks

The CbSPropProblemArray macro returns the number of bytes of memory in the SPropProblemArray structure pointed to by  _lparray.


CbSPropTagArray

The CbSPropTagArray macro determines the number of bytes occupied by an existing SPropTagArray.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SPropTagArray
int CbSPropTagArray (LPSPropTagArray _lparray)

Parameters

_lparray

Pointer to an SPropTagArray structure.

Remarks

The CbSPropTagArray macro returns the number of bytes of memory occupied by the SPropTagArray structure pointed to by _lparray.


CbSRowSet

The CbSRowSet macro determines the number of bytes of memory occupied by an existing SRowSet structure.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SRowSet
int CbSRowSet (LPSRowSet _lpSRowSet)

Parameters

_lpSRowSet

Pointer to an SRowSet structure.

Remarks

The CbSRowSet macro returns the number of bytes occupied by the SRowSet structure pointed to by _lpSRowSet.


CbSSortOrderSet

The CbSSortOrderSet macro determines the number of bytes of memory occupied by an existing SSortOrderSet structure.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SSortOrderSet
CbSSortOrderSet (_lpSSortOrderSet)

Parameters

_lpSSortOrderSet

Pointer to an SSortOrderSet structure.

Remarks

The CbSSortOrderSet macro returns the number of bytes occupied by the SSortOrderSet structure pointed to by _lpSSortOrderSet.


CHANGE_PROP_TYPE

The CHANGE_PROP_TYPE macro sets the data type of the supplied MAPI property tag without changing the property identifier part of the tag.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SPropValue
ULONG CHANGE_PROP_TYPE (ULONG ulPropTag,ULONG ulPropType)

Parameters

ulPropTag

The property tag.

UlPropType

The value of the property type to set within ulPropTag.

Remarks

The CHANGE_PROP_TYPE macro returns a property tag with the property identifier set to ulPropTag and with the property type set to ulPropType.


IsEqualMAPIUID

The IsEqualMAPIUID macro is used by a client application or a service provider to compare two MAPI unique identifiers (UIDs). It evaluates to TRUE if the two UIDs are equal.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	MAPIUID
BOOL IsEqualMAPIUID(lpuid1, lpuid2)

Parameters

lpuid1

Pointer to a MAPIUID structure identifying the first unique identifier.

lpuid2

Pointer to a MAPIUID structure identifying the second unique identifier.

Remarks

If the client or provider uses the IsEqualMAPIUID macro, be sure to include MEMORY.H in code. This macro returns TRUE, if the unique identifiers are equal, and FALSE otherwise.


MVI_PROP

The MVI_PROP macro sets the MV_FLAG and MV_INSTANCE flags for the supplied property tag. The property identifier and property type are otherwise unchanged.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SPropValue
ULONG MVI_PROP (ULONG tag)

Parameters

tag

The property tag that will have its MVI_FLAG bits set; this macro returns the property tag with its MVI_FLAG bits set. The MVI_FLAG represents the MV_FLAG and the MV_INSTANCE flags.

The MV_FLAG indicates a multivalued property. The MV_INSTANCE flag is used in table operations to request that a multivalued property be presented as a single-valued property appearing in multiple rows.

For example, when the input property tag contains the type PT_FLOAT, the returned property tag specifies the type PT_MVI_FLOAT; that is, PT_MV_FLOAT with the MV_INSTANCE bit set. All single-valued types have corresponding multivalued types.


PROP_ID

The PROP_ID macro returns the property identifier value from the supplied property tag.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SPropValue
ULONG PROP_ID (ULONG ulPropTag)

Parameters

ulPropTag

Property tag for which you want to obtain the property identifier.

Remarks

The PROP_ID macro returns the property identifier in the low-order word (bits 0-15) and zeros in the high-order word (bits 16-31). Bits 0-15 of the return value are equal to bits 16-31 of the supplied ulPropTag.


PROP_TAG

The PROP_TAG macro returns a property tag constructed from the supplied property type and the supplied property identifier.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SPropValue
ULONG PROP_TAG (ulPropType, ulPropID)

Parameters

ulPropType

Property type to be used in the property tag.

ulPropID

Property identifier.

Remarks

The PROP_TAG macro returns a property tag with a data type of ulPropType and identifier ulPropID.

For example, the property tag PR_ENTRYID is formed by using the PROP_TAG macro as follows: PROP_TAG( PT_BINARY, 0x0FFF).

The low-order 16 bits of the returned property tag contain the property type, and the high-order 16 bits of the returned tag contain the property identifier.


PROP_TYPE

The PROP_TYPE macro returns the property type of the supplied property tag.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SPropValue
ULONG PROP_TYPE (ULONG ulPropTag)

Parameters

ulPropTag

Property tag.

Remarks

The PROP_TYPE macro returns the low-order 16 bits of the property tag, which contain the value that represents the property type. The high-order 16 bits in the return value are set to zero. For example, PROP_TYPE(PR_ENTRYID) returns the value PT_BINARY.

The MVI_FLAG property tags are never used in the SPropValue structure.


SizedADRLIST

The SizedADRLIST macro defines a structure with the specified name that contains the specified number of ADRENTRY structures.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	ADRLIST
SizedADRLIST (int _centries, _name)

Parameters

_centries

Count of ADRENTRY structures. The structure type is defined with the tag _ADRLIST_ _name and type name _name.

Remarks

The SizedADRLIST macro provides a way to define a recipient list with explicit bounds when array length requirements are known.

To use a sized recipient list pointer lpSizedADRList in any function call or structure that expects an LPADRLIST pointer, perform the following cast:

lpADRList = (LPADRLIST) & SizedADRList;


SizedDtblButton

The SizedDtblButton macro creates a structure similar to DTBLBUTTON but containing a label of specified character length.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	DTBLBUTTON
SizedDtblButton (int n, u)

Parameters

n

The character length of the button's label.

u

The structure type is defined with the tag _DTBLBUTTON_ u and type name u.


SizedDtblCheckBox

The SizedDtblCheckBox macro defines a structure similar to DTBLCHECKBOX but containing a label of specified character length.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	DTBLCHECKBOX
SizedDtblCheckBox (int n, u)

Parameters

n

The character length of the check box's label. The structure type is defined with the tag _DTBLCHECKBOX_ u and type name u.

Remarks

The SizedDtblCheckBox macro provides a way to define a check box when the number of label characters is known. A DTBLCHECKBOX structure does not explicitly give the length of the lpszLabel string, it only provides an offset to the first character in it.

To use a sized display table check box pointer lpSizedDtblCheckBox in any function call or structure that expects an LPDTBLCHECKBOX pointer, perform the following cast:

lpDtblCheckBox = (LPDTBLCHECKBOX) lpSizedDtblCheckBox


SizedDtblComboBox

The SizedDtblComboBox macro defines a structure similar to DTBLCOMBOBOX, but with the added explicit number of characters in the combo box’s text edit, or static text, control.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	DTBLCOMBOBOX
SizedDtblComboBox (int n, u)

Parameters

n

The length of the allowed character string. The structure type is defined with the tag _DTBLCOMBOBOX_u and type name u. See the ulbLpszCharsAllowed member of this structure for the formatting rules of this character string.

Remarks

The SizedDtblComboBox macro provides a way to define a combo box when the length of the allowed character string is known.

To use a sized display table combo box pointer lpSizedDtblComboBox in any function call or structure that expects a LPDTBLCOMBOBOX pointer, perform the following cast:

lpDtblComboBox = (LPDTBLCOMBOBOX) lpSizedDtblComboBox


SizedDtblEdit

The SizedDtblEdit macro defines a structure similar to DTBLEDIT but with the added explicit number of characters contained in the allowed characters member.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	DTBLEDIT
SizedDtblEdit (int n, u)

Parameters

n

The length of the allowed characters string. See ulbLpszCharsAllowed for the formatting rules of the allowed character string.

Remarks

The SizedDtblEdit macro provides a way to define a text edit box when the number of allowed characters is known. A DTBLEDIT structure does not explicitly give the length of the lpszCharsAllowed string, it only provides an offset to the first character in the string.

To use lpSizedDtblEdit, which is a sized, display table edit pointer, in any function call or structure that expects a LPDTBLEDIT pointer, perform the following cast:

lpDtblEdit = (LPDTBLEDIT) lpSizedDtblEdit


SizedDtblGroupBox

The SizedDtblGroupBox macro defines a structure similar to DTBLGROUPBOX but containing a label of specified character length.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	DTBLGROUPBOX
SizedDtblGroupBox (int n, u)

Parameters

n

The character length of the group box's label. The structure type is defined with the tag _DTBLGROUPBOX_ u and type name u.

Remarks

The SizedDtblGroupBox macro provides a way to define a group box when the number of label characters is known. A DTBLGROUPBOX structure does not explicitly give the length of the lpszLabel string, it only provides an offset to the first character in it.

To use a sized display table group box pointer lpSizedDtblGroupBox in any function call or structure that expects a LPDTBLGROUPBOX pointer, perform the following cast:

lpDtblGroupBox = (LPDTBLGROUPBOX) lpSizedDtblGroupBox


SizedDtblLabel

The SizedDtblLabel macro creates a structure definition similar to DTBLLABEL but containing a specified character length for the label.

Quick Info

Specified in header file:	MAPIDEFS.H
Related structure	DTBLLABEL
SizedDtblLabel (int n, u)

Parameters

n

The character length of the label, including the terminating NULL character. The structure type is defined with the tag _DTBLLABEL_ u and type name u.

Remarks

The SizedDtblLabel macro provides a way to define a display table label when the number of characters in the label is known. A DTBLLABEL structure does not explicitly give the length of the lpszLabelName string, it only provides an offset to the first character of the string.

To use a pointer to a sized label control such as lpSizedDtblLabel in any function call or structure that expects a LPDTBLLABEL pointer, perform the following cast:

lpDtblLabel = (LPDtblLabel) lpSizedDtblLabel


SizedDtblPage

The SizedDtblPage macro defines a structure similar to DTBLPAGE but whose page label and Help file component string are of specified character lengths.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	DTBLPAGE
SizedDtblPage (int n, int n1, u)

Parameters

n

The character length of the page's label.

n1

The character length of a Help file component string that appears in a MAPISVC.INF entry mapping Help files to user interface items. If this string is not NULL, a user can access extended Help for the tabbed page by clicking the Help button on the property sheet. The structure type is defined with the tag _DTBLPAGE_ u and type name u.

Remarks

The SizedDtblPage macro provides a means of defining a display table page when the number of label and component string characters is known. A DTBLPAGE structure does not explicitly give the length of these strings, only offsets to their locations in memory allocated for the structure.

To use lpSizedDtblPage, a sized display-table page pointer in any function call or structure that expects a LPDTBLPAGE pointer, perform the following cast:

lpDtblPage = (LPDTBLPAGE) lpSizedDtblPage


SizedENTRYID

The SizedENTRYID macro creates a structure type definition identical to that of ENTRYID but containing an ab member that is a sized array. Use this macro to create an entry identifier array with explicit bounds.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	ENTRYID
SizedENTRYID (int _cb, _name)

Parameters

_cb

Count of bytes used for the entry identifier.

_name

A suffix to be appended to the tag and name of the structure type.

Remarks

The structure type is defined with the tag _ENTRYID_ _name and type name _name.

The SizedENTRYID macro provides a way to define an entry identifier after array length requirements are known.

To use a sized recipient list pointer such as lpSizedENTRYID in any function call or structure that expects an LPENTRYID pointer, perform the following cast:

lpENTRYID = (LPENTRYID) lpSizedENTRYID


SizedSPropProblemArray

The SizedSPropProblemArray creates a structure definition identical to that of SPropProblemArray but with a specified number of SPropProblem structures. Use the SizedSPropProblemArray macro to create property problem arrays with explicit bounds.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SPropProblemArray
SizedSPropProblemArray  (int_cprob, _name)

Parameters

_cprob

Count of SPropProblem structures to be in the property problem array, aProblem.

_name

The structure type is defined with the _SPropProblemArray_ _name and type name _name.


SizedSPropTagArray

The SizedSPropTagArray macro creates a structure definition identical to that of SPropTagArray but with a specified number of property tags. Use the SizedSPropTagArray macro to create property tag arrays with explicit bounds.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SPropTagArray
SizedSPropTagArray (int _ctag, _name)

Parameters

_ctag

Count of property tags to be in the property tag array aulPropTag.

_name

The structure type is defined with the tag _SPropTagArray_ _name and type name _name.

Remarks

To use lpSizedSPropTagArray, a sized property tag pointer, with a sized property tag in any function call or structure that expects a LPSPropTagArray pointer, perform the following cast:

lpSPropTagArray = (LPSPropTagArray) lpSizedSPropTagArray


SizedSRowSet

The SizedSRowSet macro creates a structure definition identical to that of SRowSet but with a specified number of rows.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SRowSet
SizedSRowSet (int _crow, _name)

Parameters

_crow

Count of rows.

_name

The structure type is defined with the tag _SRowSet_ _name and type name _name.

Remarks

To use a sized property tag array pointer lpSizedSRowSet in any function call or structure that expects a LPSRowSet pointer, perform the following cast:

lpSRowSet = (LPSRowSet) lpSizedSRowSet


SizedSSortOrderSet

The SizedSSortOrderSet macro creates a structure definition identical to that of SSortOrderSet but specifies the columns to sort on. Use the SizedSSortOrderSet macro to create sort order sets with explicit bounds.

Quick Info

Header file:	MAPIDEFS.H
Related structure:	SSortOrderSet
SizedSSortOrderSet (_csort, _name)

Parameters

_csort

Count of sort orders.

_name

The structure type is defined with the tag _SSortOrderSet_ _name and type name _name.

Remarks

To use a sized, sort order set pointer lpSizedSSortOrderSet in any function call or structure that expects an LPSSortOrderSet pointer, perform the following cast:

lpSSortOrderSet = (LPSSortOrderSet) lpSizedSSortOrderSet


MAPI Data Types

The following alphabetized entries contain documentation for MAPI Data Types.


BOOKMARK

BOOKMARK is an unsigned long data type that retains in memory a position in a table. The data stored in a bookmark depends on the client application.

typedef ULONG BOOKMARK;

Remarks

MAPI defines the following bookmarks:

BOOKMARK_BEGINNING

Seeks to the beginning of the table.

BOOKMARK_CURRENT

Seeks to the row in the table where the cursor is located.

BOOKMARK_END

Seeks to the end of the table.

The client application can create additional bookmarks. Created bookmarks are only useful while a table is open. The client must free any created bookmarks when it closes a table.

The BOOKMARK unsigned long data type is defined in MAPIDEFS.H.

See Also

IMAPITable::CreateBookmark, IMAPITable::FindRow, IMAPITable::FreeBookmark, IMAPITable::SeekRow


BYTE

BYTE is an unsigned character data type that is binary data.

typedef unsigned char     BYTE;


HRESULT

HRESULT is a data type that is a 32-bit error or warning value.

typedef LONG          HRESULT;

Remarks

An HRESULT data type is made up of a 1-bit severity flag, an 11-bit handle, a 4-bit facility code indicating status code (SCODE) group, and a 16-bit SCODE information code. A value of zero for the severity flag indicates the success of the operation for which the HRESULT was returned.

An HRESULT type returned as an error value for a function can provide the application that called the function information on the error and how to recover from it. To obtain this information, the application uses the handle of the HRESULT. The HRESULT and SCODE types are not equivalent. OLE includes functions and macros to convert between error values of these two types. To create an HRESULT value from an SCODE value, use ResultFromScode(SCODE). To convert an HRESULT form to SCODE value, use GetScode(HRESULT). For details about ResultFromScode and GetScode and for faster ways of making the conversions just mentioned, see the OLE Programmer’s Reference. For a description of the OLE implementation of HRESULT, see Inside OLE, Second Edition, by Kraig Brockschmidt.

See Also

SCODE


LHANDLE

LHANDLE is a Simple MAPI data type that is a MAPI session handle.

typedef unsigned long LHANDLE, FAR *LPLHANDLE;


LONG

LONG is a data type that is a 32-bit signed integer.

typedef long          LONG;


SCODE

SCODE is a data type that is a 32-bit status value. MAPI functions and methods return values of the SCODE type.

typedef ULONG     SCODE;

Remarks

All MAPI functions and methods return SCODE values; some MAPI functions also return warnings, which are nonzero HRESULT values.

To obtain an SCODE value from an HRESULT value, the client application can use the OLE function GetScode as follows:

SCODE scode;

HRESULT hresult;

hresult = arbitrary function call;

if (hresult)

{

     scode = GetScode(hresult);

/* Display error based on scode */

}

When a MAPI function returns an HRESULT value as a warning, an SCODE return value can be identified as a type of success. For example:

hresult = SomeCall(..)

if (hresult !=0)

{

     SCODE scode = GetScode(hresult);

     if (FAILED(scode))

          goto error;

     /*Handle the warning here */

     if (scode == MAPI_W_warning)

     {

     }

}

See Also

HRESULT


TCHAR

TCHAR is a data type that is a character string on either a Unicode or an ANSI or DBCS platform. For Unicode platforms, this string is defined as having the WCHAR type. For ANSI and DBCS platforms, the string is defined as having the char type.

typedef char          TCHAR;

typedef WCHAR  TCHAR;

Remarks

The client application can use TCHAR to represent a string of either the WCHAR or char type. Be sure to define the symbolic constant UNICODE and limit the platform where necessary. MAPI will interpret the platform information and internally translate TCHAR to the appropriate string.


ULONG

ULONG is a data type that is a 32-bit unsigned integer.

typedef unsigned long     ULONG;


WCHAR

WCHAR is a data type that is a Unicode character string.

typedef WORD          WCHAR;


MIDL Command-Line Reference

This section contains reference information for each command-line switch and switch option recognized by the Microsoft® RPC MIDL compiler. Switch entries are arranged in alphabetical order. The topic General MIDL Command-line Syntax describes the general command-line syntax.


General MIDL Command-line Syntax‹
General MIDL Command-line Syntax

midl [switch [switch-options ]] filename

switch

Specifies MIDL compiler command-line switches. Switches can appear in any sequence.

switch-options

Specifies options associated with switch. Valid options are described in the reference entry for each MIDL compiler switch.

filename

Specifies the name of the IDL file. This file usually has the extension .IDL, but it can have any extension or no extension.

Remarks

The MIDL compiler processes an IDL file and an optional ACF to generate a set of output files. The attributes specified in the IDL file’s interface attribute list determine whether the compiler generates source files for an RPC interface or for a custom OLE interface. The following lists show the default names of the files generated for an IDL file named name.IDL. You can use command-line switches to override these default names. Note that the name of the IDL file can have no extension, or it can have an extension other than .IDL.

By default (that is, if the interface attribute list does not contain the object or local attribute), the compiler generates the following files for an RPC interface:

•	Client stub (name_C.C)

•	Server stub (name_S.C)

•	Header file (name.H)

When the object attribute appears in the interface attribute list, the compiler generates the following files for an OLE interface:

•	Interface proxy file (name_P.C)

•	Interface header file (name.H)

•	Interface UUID file (name_I.C)

When the local attribute appears in the interface attribute list, the compiler generates only the interface header file, name.H.

The MIDL compiler provided with Microsoft® RPC invokes the C preprocessor as needed to process the IDL file. It does not automatically invoke the C compiler to compile generated files.

Note  The MIDL compiler provided with Microsoft RPC uses a different command-line syntax than the DCE IDL compiler uses.

The MIDL compiler switches /env, /server, /sstub, and /out affect the server stub file.

The Header File

The header file contains definitions of all the data types and operations declared in the IDL file. The header file must be included by all application modules that call the defined operations, implement the defined operations, or manipulate the defined types.

The MIDL compiler switches /header and /out affect the header file.


@ Response File Command

midl @response_file

response_file

Specifies the name of a response file. The response filename must immediately follow the @ character. No white space is allowed between the @ character and the response filename.

Examples

midl @midl.rsp

midl /pack 4 @midl1.rsp /env win32 @midl2.rsp itf.idl

Remarks

As an alternative to placing all the options associated with a switch on the command line, the MIDL compiler accepts response files that contain switches and arguments.

A response file is a text file containing one or more MIDL compiler command-line options. Unlike a command line, a response file allows multiple lines of options and filenames. This is important on systems such as MS-DOS, which limit the number of characters in the command line.

Options in a response file are interpreted as if they are present at that place in the MIDL command line.

Each argument in a response file must begin and end on the same line. The backslash character (“\”) cannot be used to concatenate lines.

When it is part of a quoted string in the response file, the backslash character can only be used before another backslash (\or before a double quotation mark character ("). When it is not part of a quoted string, the backslash character can only be used before a double quotation mark character.

MIDL supports command-line arguments that include one or more response files combined with other command-line switches.

The MIDL compiler does not support nested response files.

See Also

General MIDL Command-line Syntax


/acf

midl /acf acf_filename

acf_filename

Specifies the name of the ACF. White space may or may not be present between the /acf switch and the filename.

Example

midl /acf bar.acf filename.idl

Remarks

The /acf switch allows the user to supply an explicit ACF filename. The switch also allows the use of different interface names in the IDL and ACF files.

By default, the MIDL compiler constructs the name of the ACF by replacing the IDL filename extension (usually .IDL) with .ACF. When the /acf switch is present, the ACF takes its name from the specified filename. The /acf switch applies only to the IDL file specified on the MIDL compiler command line. It does not apply to imported files.

When the /acf switch is used, the interface name in the ACF need not match the MIDL interface name. This feature allows interfaces to share an ACF specification.

When an absolute path to an ACF is not specified, the MIDL compiler searches in the current directory, directories supplied by the /I option, and directories in the INCLUDE path. If the ACF is not found, the MIDL compiler assumes there is no ACF for this interface. For more information about the sequence of directories, see  /no_def_idir switches. For more information relating to /acf, see IDL.

See Also

General MIDL Command-line Syntax


/align

midl /align:alignment

alignment

Specifies the alignment for types in the library. The alignment value can be 1, 2, 4, or 8. The value 1 indicates natural alignment; n indicates alignment on byte n. When you do not specify the /align switch, the default is 8.

Example

midl /align:4 filename.idl

Remarks

The /align switch is functionally the same as the MIDL /Zp option and is recognized by the MIDL compiler solely for backward compatibility with MKTYPLIB. If you are generating a new makefile, use the /Zp switch.

The alignment value corresponds to the /Zp option value used by the Microsoft C/C++ compiler.Be sure that you specify the same alignment when you invoke the C compiler as when you invoke the MIDL compiler. For more information, see your Microsoft C/C++ programming documentation.

For a discussion of the potential dangers in using nonstandard packing levels, see the /Zp help topic.

See Also

General MIDL Command-line Syntax, /Zp


/app_config

midl /app_config

Examples

midl /app_config filename.idl

Remarks

The /app_config switch selects application-configuration mode, which allows you to use some ACF keywords in the IDL file. With this MIDL compiler switch, you can omit the ACF and specify an interface in a single IDL file.

This release of Microsoft RPC supports the use of the following ACF attributes in the IDL file:

•	implicit_handle

•	auto_handle

•	explicit_handle

Future releases of Microsoft RPC may support the use of other ACF attributes in the IDL file.

For more information related to the /app_config switch, see ACF and IDL.

See Also

General MIDL Command-line Syntax


/c_ext

midl /c_ext

This switch is obsolete with the current version (3.0) of the MIDL compiler. However, using the switch will not generate a compiler error, so you do not have to remove references to /ms_ext or /c_ext from an existing makefile.

The following features are now available by default:

•	Many existing header files define types with qualifiers, such as far and stdcall, that are not part of the DCE IDL. DCE IDL compilers (and the MIDL compiler in DCE-compatibility mode) generate errors when they attempt to process these qualifiers. The MIDL compiler allows you to compile IDL files that contain these qualifiers. The type qualifiers do not affect the way the data is transmitted on the network.

•	You can omit directional attributes (in, out).

The following C-language extensions are supported in default mode:

•	Bit fields in structures and unions

•	Comments that start with two slash characters (“//”)

•	External declarations

•	Procedures with ellipses in the parameter list

•	On 32-bit platforms, int is a native 32-bit base type. On 16-bit platforms, int is recognized but is not a remotable type

•	Type void * that is not used in remote operations

•	Type qualifiers, including the form with the ANSI-conformant prefix, contain two underscore characters: _ _cdecl, cdecl, _ _const, const, _ _export, export, _ _far, far, _ _loadds, loadds, _ _near, near, _ _pascal, pascal, _ _stdcall, stdcall, _ _volatile, and volatile.

For more information about declaration qualifiers, see your Microsoft C/C++ documentation.

See Also

/app_config, /osf, General MIDL Command-line Syntax


/caux

This switch is obsolete and, if used, results in an error.


/char

midl /char { signed | unsigned | ascii7 }

signed

Specifies that the default C-compiler type for char is signed. All occurrences of char not accompanied by a sign specification are generated as unsigned char.

unsigned

Specifies that the default C-compiler type for char is unsigned. All uses of small not accompanied by a sign specification are generated as signed small.

ascii7

Specifies that all char values are to be passed into the generated files without a specific sign keyword. All uses of small not accompanied by a sign specification are generated as small.

Examples

midl /char signed filename.idl

midl /char unsigned filename.idl

midl /char ascii7 filename.idl

Remarks

The /char switch helps you ensure that the MIDL compiler and C compiler operate together correctly for all char and small types. By definition, MIDL char is unsigned. Small is defined in terms of char (#define small char), and MIDL small is signed.

The /char switch directs the MIDL compiler to specify explicit signed or unsigned declarations in the generated files when the C-compiler sign declaration conflicts with the MIDL default for that type.

The following table summarizes the generated types:

midl /char option	Generated char type	Generated small type
midl /char signed	unsigned char	small
midl /char unsigned	char	signed small
midl /char ascii7	char	small
The /char signed option indicates that the C-compiler char type is signed. To match the MIDL default for char, the MIDL compiler must convert all uses of char not accompanied by a sign specification to unsigned char. The small type is not modified because this C-compiler default matches the MIDL default for small.

The /char unsigned option indicates that the C-compiler char type is unsigned. The MIDL compiler converts all uses of small not accompanied by a sign specification to signed small.

The ascii7 option indicates that no explicit sign specification is added to char types. The type small is generated as small.

To avoid confusion, you should use explicit sign specifications for char and small types whenever possible in the IDL file. Note that the use of explicitly signed char types in your IDL file is not supported by DCE IDL. Therefore, this feature is not available when you compile with the MIDL /osf switch.

For more information related to /char, see small.

See Also

char, General MIDL Command-line Syntax, /osf, small


/client

midl /client { stub | none }

stub

Generates the client-side files.

none

Does not generate any client-side files.

Examples

midl /client none filename.idl

midl /client stub filename.idl

Remarks

The /client switch directs the MIDL compiler to generate client-side C source files for an RPC interface. When the /client switch is not specified, the MIDL compiler generates the client stub file. This switch does not affect OLE interfaces.

The /client switch takes precedence over the /cstub switch.

See Also

/cstub, /server, General MIDL Command-line Syntax


/confirm

midl /confirm

Examples

midl /confirm

midl /confirm @response.rsp filename.idl

Remarks

The /confirm switch instructs the compiler to display all MIDL compiler options without processing the input IDL (and optional ACF) files.

See Also

/help, General MIDL Command-line Syntax


/cpp_cmd

midl /cpp_cmd “C_preprocessor_command”

C_preprocessor_command

Specifies the command that invokes the C preprocessor. This command allows you to override the default C preprocessor. By default, MIDL invokes the Microsoft C compiler for the build environment you are using.

Examples

midl /cpp_cmd "cl386" /cpp_opt "/E" filename.idl

midl /cpp_cmd "mycpp" /DFLAG=TRUE /Ic:\tmp filename.idl

midl /cpp_opt "/E /DFLAG=TRUE" filename.idl

Remarks

The /cpp_cmd switch specifies the C-compiler preprocessor that the MIDL compiler uses to preprocess the IDL and ACF files. When this switch is present, the C_preprocessor_command option is required.

When the specified C preprocessor does not direct its output to stdout, you must specify the C compiler switch that redirects output to stdout as part of the MIDL compiler /cpp_opt switch.

The C preprocessor is invoked by a command string that is formed from the information provided to the MIDL compiler /cpp_cmd, /cpp_opt, /D, /I, and /U switches. The following table summarizes how the command string is constructed for each combination of /cpp_cmd and /cpp_opt switches:

/cpp_cmd present?	/cpp_opt present?	Description
Yes	Yes	Invokes specified C compiler with specified options. You must supply /E as part of /cpp_opt
Yes	No	Invokes specified C compiler with settings obtained from MIDL /I, /D, /U switches. Adds C compiler /E switch
No	Yes	Invokes Microsoft C compiler with specified options. Does not use MIDL /I, /D, /U options. You must supply /E as part of /cpp_opt
No	No	Invokes Microsoft C compiler with /E option only
When the /cpp_cmd switch is not specified, the MIDL compiler invokes the Microsoft C/C++ compiler for that environment.

When the /cpp_opt switch is not present, the MIDL compiler concatenates the string specified by the /cpp_cmd switch with the information specified by the MIDL /I, /D, and /U options. The string /E is also concatenated to the C-compiler invocation string to indicate that the C compiler should perform preprocessing only. The MIDL compiler uses the concatenated string to invoke the C preprocessor for each IDL and ACF source file.

When the /cpp_opt switch is present, the MIDL compiler concatenates the string specified by the /cpp_cmd switch with the string specified by the /cpp_opt switch. The MIDL compiler uses the concatenated string to invoke the C preprocessor for each IDL and ACF source file. When the /cpp_opt switch is present, neither the MIDL compiler options specified by the /I, /D, and /U switches nor the C compiler switch /E is concatenated with the string. You must supply the /E option as part of the string.

See Also

/cpp_opt, General MIDL Command-line Syntax, /no_cpp


/cpp_opt

midl /cpp_opt “C_preprocessor_option”

C_preprocessor_option

Specifies a command-line option associated with the C preprocessor. You must supply the C-compiler option /E as part of the C_preprocessor_option string.

Examples

midl /cpp_cmd "cl386" /cpp_opt "/E" filename.idl

midl /cpp_cmd "mycpp" /DFLAG=TRUE /Ic:\tmp filename.idl

midl /cpp_opt "/E /DFLAG=TRUE" filename.idl

Remarks

The /cpp_opt switch specifies options to pass to the C preprocessor. The /cpp_opt switch can be used with or without the /cpp_cmd switch. The following table summarizes how the C-preprocessor command string is constructed for each combination of /cpp_cmd and /cpp_opt switches:

/cpp_cmd present?	/cpp_opt present?	Description
Yes	Yes	Invokes specified C compiler with specified options. You must supply /E as part of /cpp_opt
Yes	No	Invokes specified C compiler with settings obtained from MIDL /I, /D, /U switches. Adds C-compiler /E switch
No	Yes	Invokes Microsoft C compiler with specified options. Does not use MIDL /I, /D, /U options. You must supply /E as part of /cpp_opt
No	No	Invokes Microsoft C compiler with /E option only
When the /cpp_cmd switch is present and the /cpp_opt switch is not, the MIDL compiler concatenates the string specified by the cpp_cmd switch with the /I, /D, and /U options and uses this concatenated string to invoke the C preprocessor for each IDL and ACF source file.

When the /cpp_cmd switch is not present, the preprocessor option is sent to the default C preprocessor. When the /cpp_cmd switch is present, the preprocessor option is sent to the specified C preprocessor.

See Also

/cpp_cmd, General MIDL Command-line Syntax, /no_cpp


/cstub

midl /cstub stub_file_name

stub_file_name

Specifies a filename that overrides the default client stub filename. Filenames can be explicitly quoted using double quotes (") to prevent the shell from interpreting the special characters.

Example

midl /cstub my_cstub.c filename.idl

Remarks

The /cstub switch specifies the name of the client stub file for an RPC interface. The specified filename replaces the default filename. By default, the filename is obtained by adding the extension _C.C to the name of the IDL file. This switch does not affect OLE interfaces.

When you are importing files, the specified filename applies to only one stub file — the stub file that corresponds to the IDL file specified on the command line.

If stub_file_name does not include an explicit path, the file is written to the current directory or the directory specified by the /out switch. An explicit path in stub_file_name overrides the /out switch specification.

The /client none switch takes precedence over the /cstub switch.

See Also

/header, General MIDL Command-line Syntax, /out, /sstub


/D

midl /D name=definition

name

Specifies a defined name that is passed to the C preprocessor when the /cpp_cmd switch is present and the /cpp_opt switch is not present.

definition

Specifies a value associated with the defined name.

Example

midl -DUNICODE filename.idl

Remarks

The /D switch defines a name and an optional value to be passed to the C preprocessor as if by a #define directive. Multiple /D directives can be used in a command line. White space between the /D switch and the defined name is optional.

When the /cpp_cmd switch is present and the /cpp_opt switch is not, the MIDL compiler concatenates the string specified by the /cpp_cmd switch with the /I, /D, and /U options and uses this concatenated string to invoke the C preprocessor for each IDL and ACF source file.

The MIDL compiler switch /D is ignored when the MIDL compiler switch /no_cpp or /cpp_opt is specified.

See Also

/cpp_cmd, /cpp_opt, /I, General MIDL Command-line Syntax, /no_cpp, /U


/dlldata

midl /dlldata

Example

midl /dlldata data.c

Remarks

The /dlldata switch is used to specify the filename for the generated dlldata file for a proxy DLL. The default filename “dlldata.c” is used if the /dlldata switch is not specified.

The dlldata file must be linked to the proxy DLL. The dlldata file contains entry points and data structures required by the class factory for the proxy DLL. These data structures specify the object interfaces contained in the proxy DLL. The dlldata file also specifies the class ID of the class factory for the proxy DLL. This is always the UUID (IID) of the first interface of the first proxy file (by alphabetical order).

The same dlldata file should be specified when invoking MIDL on all the IDL files that will go into a particular proxy DLL. The dlldata file is created or updated during each MIDL compilation, incrementally building a list of the interfaces that will go into the proxy DLL.

See Also

General MIDL Command-line Syntax


/env

midl /env { dos | win16 | mac  | win32 }

dos

Directs the MIDL compiler to generate stub files, or a type library file, for an MS-DOS environment.

win16

Directs the MIDL compiler to generate stub files, or a type library file, for the 16-bit Microsoft Windows environment such as Microsoft Windows 3.x or Microsoft Windows for Workgroups 3.11.

mac

Directs the MIDL compiler to generate stub files, or a type library file, for the Apple® Macintosh® (680x0) environment.

Note  The MIDL compiler does not generate a server-stub file when you use the /env switch with the dos, win16, or mac options.

win32

Directs the MIDL compiler to generate stub files, or a type library file, for a 32-bit Microsoft Windows environment—either Microsoft® Windows® 95 or Microsoft® Windows NT™.

Examples

midl /env dos filename.idl

midl /env win32 filename.idl

Remarks

The /env switch selects the environment in which the application runs. The /env switch primarily affects the packing level used for structures in that environment.

Be sure you specify the same packing-level setting for both the MIDL compiler and the C compiler.

The /env switch determines the packing level and other settings as follows:

•	When dos is specified, _ _far precedes pointer declarations in the generated header file, and the stub files use packing-level 2 for all types involved in remote operations.

•	When win16 is specified, _ _far precedes pointer declarations in the generated files, stub files use C-compiler packing-level 2 for all types involved in remote operations, and _ _export is applied to callback stubs on the client side. You must compile the stubs with the /GA option.

•	When win32 is specified, generated stubs use C-compiler packing-level 8 for all types involved in remote operations.

•	When mac  is specified, the stub files use packing level 2 for all types involved in remote operations. The mac environment does not support object interfaces.

The /align, /pack, and /Zp switches take precedence over the /env settings.

See Also

General MIDL Command-line Syntax, /pack, /Zp


/error

midl /error { allocation | stub_data | ref | bounds_check | none | all }

allocation

Checks whether midl_user_allocate returns a null value, indicating an out-of-memory error.

stub_data

Generates a stub that catches unmarshalling exceptions on the server side and propogates them back to the client.

ref

Generates code that checks at run time to ensure that no NULL [ref] pointers are being passed to the client stubs and raises an RPC_X_NULL_REF_POINTER exception if it finds any.

bounds_check

Checks size of conformant-varying and varying arrays against transmission length specification.

none

Performs no error checking.

all

Performs all error checking.

Examples

midl /error allocation filename.idl

midl /error none filename.idl

Remarks

The /error switch selects the amount of error checking to be performed by the generated stub files.

By default, the MIDL compiler generates code that checks for enum and certain memory-access errors. The enum errors that are checked are truncation errors caused by conversion between long enum types (32-bit integers) and short enum types (the network-data representation of enum) and the number of identifiers in an enumeration exceeding 32,767. The memory-access error checking is for pointers that exceed the end of the buffer in marshalling code and for conformant arrrays whose size is less than zero. Use the /error bounds_check flag to check for other invalid array bounds.

When you specify /error allocate, the stubs include code that raises an exception when midl_user_allocate returns 0.

The /error stub_data option prevents client data from crashing the server during unmarshalling; in effect providing a more robust method of handling the unmarshalling operation.

See Also

General MIDL Command-line Syntax


/h

midl /h filename

filename

Specifies a header filename that overrides the default header filename. Filenames can be explicitly quoted using double quotes (") to prevent the shell from interpreting special characters.

Examples

midl /h tlibhead.h filename.idl

midl /h "midl.h" filename.idl

Remarks

The /h option is functionally equivalent to the /header option. The /h switch specifies filename as the name for a header file that contains all the definitions contained in the IDL file, without the IDL syntax. This file can be used as a C or C++ header file.

See Also

General MIDL Command-line Syntax, /header


/header

midl /header filename

filename

Specifies a header filename that overrides the default header filename. Filenames can be explicitly quoted using double quotes (") to prevent the shell from interpreting special characters.

Example

midl /header "bar.h" filename.idl

Remarks

The /header switch specifies the name of the header file. The specified filename replaces the default filename. The default filename is obtained by replacing the IDL file extension (usually .IDL) with the extension .H. For OLE interfaces, the /header switch overrides the default name of the interface header file.

When you are importing files, the specified filename applies to only one header file — the header file that corresponds to the IDL file specified on the command line.

If filename does not include an explicit path, the file is written to the current directory or the directory specified by the /out switch. An explicit path in filename overrides the /out switch specification.

See Also

General MIDL Command-line Syntax, /h, /cstub, /out, /sstub, /proxy


/help
/help (/?)

midl /help
midl /?

Example

midl /help

Remarks

The /help (/?) switch instructs the compiler to display a usage message detailing all available MIDL command-line switches and options.

The /confirm switch displays the MIDL compiler switch settings selected by the user.

See Also

General MIDL Command-line Syntax, /confirm


/I

midl /I include_path

include_path

Specifies one or more directories that contain import, include, and ACF files. White space between the /I switch and include_path is optional. Separate multiple directories with a semicolon character (;).

Example

midl /I c:\include;c:\include\h /I\include2 filename.idl

Remarks

The /I switch specifies directories to be searched for imported IDL files, included header files, and ACF files. More than one directory can appear with each /I switch, and more than one /I switch can appear with each MIDL compiler invocation. Directories are searched in the order they are specified.

The /I switch setting is also passed by the MIDL compiler to the C compiler’s C preprocessor. When the /cpp_cmd switch is present and the /cpp_opt switch is not, the MIDL compiler concatenates the string specified by the /cpp_cmd switch with the /I, /D, and /U options and uses this concatenated string to invoke the C preprocessor for each IDL and ACF source file. The MIDL compiler switch /I is not passed to the preprocessor when the MIDL compiler switch /no_cpp or /cpp_opt is specified.

In Microsoft operating-system environments (32-bit Windows, 16-bit Windows, and MS-DOS), directories are searched in the following sequence:

1.	Current directory.

2.	Directories specified by the /I switch (in order as they appear following the switch).

3.	Directories specified by the INCLUDE environment variable.

When directories are specified with the /I switch, the /no_def_idir switch instructs the MIDL compiler to ignore the current directory, ignore the directories specified by the INCLUDE environment variable, and search only the specified directories.

When no directories are specified with the /I switch, the /no_def_idir switch instructs the MIDL compiler to search only the current directory.

See Also

General MIDL Command-line Syntax, /acf, /cpp_cmd, /cpp_opt, /no_def_idir


/iid

midl /iid filename

filename

Specifies an interface identifier filename that overrides the default interface identifier filename for an OLE interface. Filenames can be explicitly quoted using double quotes (") to prevent the shell from interpreting the special characters.

Example

midl /iid "foo_iid.c" filename.idl

Remarks

The /iid switch specifies the name of the interface identifier file for an OLE interface, overriding the default name obtained by adding _I.C to the IDL filename. The /iid switch does not affect RPC interfaces.

If filename does not include an explicit path, the file is written to the current directory or to the directory specified by the /out switch. An explicit path in filename overrides the /out switch specification.

See Also

General MIDL Command-line Syntax, /header, /out, /proxy


/import

This switch is obsolete and, if used, results in an error.


/mktyplib203

midl /mktyplib203

Examples

midl /mktyplib203 myoldodl.odl

midl /mktyplib203 oldhabit.idl

Remarks

The /mktyplib203 switch forces the MIDL compiler to parse the input file in much the same manner as MKTYPLIB.EXE, version 2.03, would handle the file. In order to use this switch, the input file must follow the ODL syntax exactly — you cannot place any statements outside of the library block. Specifically, using the /mktyplib203 switch resolves the following discrepancies between MKTYPLIB and MIDL:

•	MKTYPLIB typdef syntax is required for struct, union and enum data types.

•	GUIDs in the header files are defined with a macro that can be conditionally compiled to generate either a GUID predefinition or an instantiated GUID.

•	The base type BOOL is represented as a VARIANT_BOOL, which is defined as a short.

See Differences Between MIDL and MKTYPLIB for a more detailed description of these differences.

There is only one discrepancy betweey MKTYPLIB.EXE and MIDL 3.0 that using the /mktyplib203 switch will not resolve and that is the scope of symbols in an enum declaration. In MKTYPLIB, these symbols have local scope; in MIDL 3.0 they have global scope. For example, the following code will generate a duplicate name error in MIDL:

typedef struct {. . . } a;

enum { a=1, b=2, c=3};

See Also

General MIDL Command-line Syntax, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


/ms_ext

midl /ms_ext

Effective with MIDL version 3.0, the features enabled by this switch are now the default mode for the MIDL compiler. Using the switch will not generate a compiler error, so you do not have to remove references to /ms_ext or /c_ext from an existing makefile.

The following Microsoft extensions to OSF DCE are now available by default:

•	Interface definitions for OLE objects. For more information on the files generated for OLE interfaces, see Files Generated for an OLE Interface.

•	A callback attribute specifying a static callback function on the client.

•	cpp_quote(quoted_string) and #pragma midl_echo

•	wchar_t wide-character types, constants, and strings

•	enum initialization (sparse enumerators)

•	Expressions as size and discriminator specifiers.

•	Handle extensions.

•	Pointer-attribute type inheritance.

•	Multiple interfaces.

•	Definitions outside of the interface block.

•	You can omit directional attributes (in, out).

See Also

General MIDL Command-line Syntax, Pointer-Attribute Type Inheritance, /app_config, /osf


/ms_union

midl /ms_union

Example

midl /ms_union file.idl

Remarks

The /ms_union switch controls the NDR alignment of nonencapsulated unions.

The MIDL compiler mirrors the behavior of the OSF-DCE IDL compiler for nonencapsulated unions. However, because earlier versions of the MIDL compiler did not do so, the /ms_union switch provides compatibility with interfaces built on previous versions of the MIDL compiler.

The ms_union feature can be used as a command line switch (/ms_union), an IDL interface attribute, or as an IDL type attribute.

See Also

General MIDL Command-line Syntax, IDL, ms_union


/new

midl /new

Examples

midl /new filename.idl

midl filename.idl

Remarks

This is the default setting for choosing a type library format. Effective with Windows NT 4.0, there is a new version of OLEAUT32.DLL that supports a richer format for 32-bit type libraries. MIDL looks for this DLL on the build machine; if the new version is present, MIDL generates a new-format type library, otherwise it generates an old-format type library. Thus, if the new OLEAUT32.DLL is present, this switch does nothing. If the new OLEAUT32.DLL is not present, specifying this switch in the MIDL command line will generate an error.

See Also

General MIDL Command-line Syntax, /old


/no_cpp

midl /no_cpp

Example

midl /no_cpp filename.idl

Remarks

The /no_cpp switch specifies that the MIDL compiler does not call the C preprocessor to preprocess the IDL file.

The /no_cpp switch takes precedence over the /cpp_cmd and /cpp_opt switches.

See Also

General MIDL Command-line Syntax, /cpp_cmd, /cpp_opt, /D, /I, /U


/no_default_epv

midl /no_default_epv

Example

midl /no_default_epv filename.idl

Remarks

The /no_default_epv switch directs the MIDL compiler not to generate a default entry-point vector (epv). In this case, the application must register an epv with the RpcServerRegisterIf call. Compare this switch with the /use_epv switch described earlier in this chapter.

See Also

General MIDL Command-line Syntax, IDL, /use_epv, RpcServerRegisterIf


/no_def_idir

midl /no_def_idir

Examples

; search only the current directory

midl /no_def_idir filename.idl

; search only the specified directories

midl /no_def_idir /I c:\c700\include filename.idl

Remarks

When directories are specified with the /I switch, the /no_def_idir switch instructs the MIDL compiler to search only the directories specified with the /I switch, ignoring the current directory and ignoring the directories specified by the INCLUDE environment variable.

When no directories are specified with the /I switch, the /no_def_idir switch instructs the MIDL compiler to search only the current directory.

See Also

General MIDL Command-line Syntax, /acf, /I


/nologo

midl /nologo

Remarks

Disables the display of the copyright banner.

See Also

General MIDL Command-line Syntax


/no_warn

midl /no_warn

Examples

midl /no_warn filename.idl

midl /W0 filename.idl

Remarks

The /no_warn switch directs the MIDL compiler to suppress warning messages. The use of the /no_warn switch is equivalent to /W0.

See Also

General MIDL Command-line Syntax, /W, /WX


/o

midl /o outputfile

outputfile

Specifies a filename for the MIDL compiler to redirect output (error messages and warnings) to.

See Also

General MIDL Command-line Syntax


/Oi

midl /{Oi | Oic | Oif | Oicf}

/Oi

Specifies the fully-interpreted method for marshalling stub code passed between client and server.

/Oic

Specifies the codeless proxy method of marshaling that provides all the features of /Oi and also further reduces the size of the client stub code for object interfaces.

/Oif or /Oicf

Specifies the codeless proxy method of marshaling that includes all the features provided by /Oi and /Oic but uses a new interpreter (“fast format strings”) that provides better performance than /Oi or /Oic.

Please note the restrictions related to supporting platforms, below.

Examples

midl /Oi filename.idl

midl /Oic filename.idl

midl /Oif filename.idl

Remarks

The MIDL 3.0 compiler provides two methods for marshalling code: fully-interpreted (/Oi, /Oic and /Oif) and mixed-mode (/Os). Mixed-mode is the default. Some language features are not supported in some modes. In this case, the compiler automatically switches to the appropriate mode and issues a warning.

If performance is a concern, the mixed-mode (/Os) method can be the best approach. In this mode, the compiler chooses to marshall some parameters inline in the generated stubs. While this results in larger stub size, it offers increased performance.

The fully-interpreted method marshals data completely offline. This considerably reduces the size of the stub code, but results in decreased performance. Also, with the fully-interpreted method, there is a limit of 16 parameters for each procedure. Any procedure containing more than 16 parameters will automatically be processed in /Os mode. Among the interpreted modes, /Oif offers the best performance and /Oi offers the best backward compatibility.

If your application uses OLE object interfaces and if it will never run on a version of Microsoft Windows NT earlier than 3.51, you can reduce the size of your client stub code for object interfaces by using the /Oic option. With this option the MIDL compiler does not generate any client-side stub code. Since object interface calls are through vtable pointers, the compiler generates the proper vtable structures and the application calls the stubs through them.

If your application will be run only on Microsoft Windows NT 4.0 or later, you can use the faster /Oif option. Specifically, you may want to use the /Oif option if your application uses MIDL features that were introduced with MIDL 3.0, such as the wire_marshal and user_marshal attributes. If your application uses pipes you must use the /Oif option; if you specify another mode, the MIDL compiler will switch to /Oif.

To fine-tune the way your stub code is marshalled, Microsoft RPC provides an ACF optimize attribute. This attribute is used as an interface attribute or operation attribute to select the marshalling mode for individual interfaces or for individual operations.

Calling Conventions

Stubs generated by the MIDL compiler in the interpreted method using the /Oi, /Oic, or /Oif switches must be compiled as either a stdcall or a cdecl procedure during the C compilation. A PASCAL or Fastcall calling convention will not work. Additionally, the server stub must be compiled as stdcall.

Supporting Platforms

/Oi is supported on Windows NT 3.5 or later and Windows 95
/Oic is supported on Windows NT 3.51 or later and Windows 95
/Oif is supported on Windows NT 4.0.

See Also

General MIDL Command-line Syntax, /Os, optimize


/old

midl /old

Examples

midl /old filename.idl

midl /old myoldodl.odl

Remarks

The /old switch determines the format of MIDL-generated type libraries.

Effective with Windows NT 4.0, there is a new version of OLEAUT32.DLL that supports a richer format for 32-bit type libraries. MIDL looks for this DLL on the build machine; if the new version is present, MIDL generates a new-format type library. Otherwise, it generates an old-format type library. The /old switch overrides this default and directs the MIDL compiler to generate old-format type libraries even if the newer version of OLEAUT32.DLL is present.

See Also

General MIDL Command-line Syntax


/oldnames

midl /oldnames

Example

midl /oldnames filename.idl

Remarks

The /oldnames switch directs the MIDL compiler to generate interface names which do not include the version number.

The MIDL 2.0 compiler incorporates the version number of the interface into the interface name that is generated in the stub (for example, foo_v1_0_ServerIfHandle). This naming format is consistent with the format used by the OSF DCE IDL compiler. However, it differs from the naming format used by the MIDL 1.0 compiler. The MIDL 1.0 compiler did not include version numbers in interface names (for example, foo_ServerIfHandle). The /oldnames switch allows you to instruct the MIDL compiler to generate interface names which do not include the version number. In this way, the format is consistent with names generated by the MIDL 1.0 compiler.

If you have server application code that was written for use with a stub generated by the MIDL 1.0 compiler and it refers to the MIDL-generated interface name (for example, in a call to RpcServerRegisterIf), you must either change it to reference the MIDL 2.0 style of interface name or use the /oldnames switch when invoking the MIDL compiler.

See Also

General MIDL Command-line Syntax, IDL


/Os

midl /Os

Examples

midl /Os filename.idl

Remarks

The /Os switch specifies the mixed-mode method to marshal stub code passed between client and server.

There are important issues to consider before deciding on the method for marshalling code. These issues concern size and performance. The MIDL 2.0 compiler provides two methods for marshalling code: mixed-mode (/Os) and fully-interpreted (/Oi). The fully-interpreted method marshals data completely offline. This reduces the size of the stub code considerably, but it also results in decreased performance.

If performance is an important concern, the mixed-mode method (/Os) can be the best approach. In this mode, the compiler marshals some parameters inline in the generated stubs. While this results in larger stub size, it also offers increased performance. Because mixed-mode is the default, you do not need to explicitly select the /Os switch to accomplish mixed-mode marshalling.

To further define the level of gradiation in how data is marshalled, this version of RPC provides an optimize attribute. This attribute is used as an ACF interface attribute or operation attribute to select the marshalling mode.

See Also

General MIDL Command-line Syntax, /Oi, optimize


/osf

midl /osf

Examples

midl /osf filename.idl

midl /osf /app_config filename.idl

Remarks

The /osf switch forces strict compatibility with OSF DCE. Use this switch if your application requires strict compatibility with OSF DCE for portability reasons.

In /osf mode, the Rpcss package is automatically enabled when you use full pointers, the arguments require memory allocation, or when you use the enable_allocate attribute. This means that you do not have to supply the midl_user_allocate and midl_user_free functions in your client and server application.

The following Microsoft-extended features are not available when you compile with the /osf switch:

•	Abstract declarators (unnamed parameters) in the IDL file.

•	Interface definitions for OLE objects.

•	MIDL-only attributes, such as wire_marshal, user_marshal, and the typelib (ODL)extensions.

•	Using ACF keywords in an IDL file.

•	Static callback functions on the client.

•	cpp_quote(quoted_string) and #pragma midl_echo.

•	wchar_t wide-character types, constants, and strings.

•	enum initialization (sparse enumerators).

•	[out] -only size specification.

•	Mixed sized-pointers and sized arrays.

•	Expressions used for size and discriminator specifiers.

•	Explicit handle parameters in any position in the argument list. In /osf mode, the MIDL compiler looks for an explicit binding handle as the first parameter. When the first parameter is not a binding handle and one or more context handles are specified, the leftmost context handle is used as the binding handle. When the first parameter is not a handle and there are no context handles, the procedure uses implicit binding using the ACF attribute implicit_handle or auto_handle.

•	Pointer-attribute type inheritance. OSF DCE does not allow unattributed pointers. Therefore, in /osf mode each IDL file must define attributes for its pointers. If any pointer does not have an explicit attribute, the IDL file must have a pointer_default specification to set the pointer type.

•	Multiple interfaces in an IDL file.

•	Definitions outside of the interface block.

•	Type qualifiers such as far and stdcall.

•	Omitting directional attributes.

The following C/C++ language extensions are not available when you compile with the /osf switch:

•	Bit fields in structures and unions.

•	Single line comments delimited with two slash characters (//).

•	External declarations.

•	Procedures with ellipses in the parameter list.

•	Type int.

•	Type void * (except with the context_handle attribute).

•	Type qualifiers, including the form with the ANSI-conformant prefix, contain two underscore characters: _ _cdecl, cdecl, _ _const, const, _ _export, export, _ _far, far, _ _loadds, loadds, _ _near, near, _ _pascal, pascal, _ _stdcall, stdcall, _ _volatile, and volatile.

See Also

General MIDL Command-line Syntax, /app_config, /ms_ext, Rpcss Memory Management Model


/out

midl /out path-specification

path-specification

Specifies the path to the directory in which the stub, header, and switch files are generated. A drive specification, an absolute directory path, or both can be specified. Paths can be explicitly quoted using double quotes (") to prevent the shell from interpreting the special characters.

Examples

midl /out c:\mydir\mysubdir\subdir2 deeper filename.idl

midl /out c:  filename.idl

midl /out \mydir\mysubdir\another filename.idl

Remarks

The /out switch specifies the default directory where the MIDL compiler writes output files. The output directory can be specified with a drive letter, an absolute path name, or both. The /out option can be used with any of the switches that enable individual output file specification.

When the /out switch is not specified, files are written to the current directory.

The default directory specified by the /out switch can be overridden by an explicit path name specified as part of the /cstub, /header, /proxy, or /sstub switch.

See Also

General MIDL Command-line Syntax, /cstub, /header, /proxy, /sstub


/pack

midl /pack packing_level

packing_level

Specifies the packing level of structures in the target system. The packing-level value can be set to 1, 2, 4, or 8.

Examples

midl /pack 2 filename.idl

midl /pack 8 bar.idl

Remarks

The /pack switch is the same as the /Zp option. The /pack switch designates the packing level of structures in the target system. The packing-level value corresponds to the /Zp option value used by the Microsoft C/C++ version 7.0 compiler. For more information, see your Microsoft C/C++ programming documentation.

Specify the same packing level when you invoke the MIDL compiler and the C compiler. The default is 8.

For a discussion of the potential dangers in using nonstandard packing levels, see the /Zp help topic.

See Also

General MIDL Command-line Syntax, /env, /Zp


/prefix

midl /prefix { client | server | switch | all }

client

Affects only the client stub routine names.

server

Affects only the routine names called by the server stub routine.

switch

Affects an extra prototype added to the header file.

all

Affects both the client and server stub routine names.

Examples

midl /prefix client "c_" server "s_"

midl /prefix all "foo_"

midl /prefix client "bar_"

Remarks

The /prefix switch directs the MIDL compiler to add prefix strings to the client and/or server stub routine names. This can be used to allow a single program to be both a client and server of the same interface, without having the client- and server-side routine names conflict with each other. If the prefix for the client-side routines is different from the prefix for the server-side routines, the generated header file will have both client-side routine prototypes and server-side routine prototypes.

The /prefix switch is useful when a single header file will be used with stubs from multiple runs of the MIDL compiler. This forces additional routine prototypes in the header file.

In all cases, the client, server, and switch prefixes will override an all prefix.

See Also

General MIDL Command-line Syntax


/proxy

midl /proxy proxy_file_name

proxy_file_name

Specifies a filename that overrides the default interface proxy filename. Filenames can be explicitly quoted using double quotes (") to prevent the shell from interpreting the special characters.

Example

midl /proxy my_proxy.c filename.idl

Remarks

The /proxy switch specifies the name of the interface proxy file for an OLE interface. The specified filename replaces the default filename obtained by adding _P.C to the name of the IDL file. The /proxy switch does not affect RPC interfaces.

If proxy_file_name does not include an explicit path, the file is written to the current directory or to the directory specified by the /out switch. An explicit path in proxy_file_name overrides the /out switch specification.

For a more detailed description of the interface proxy file and other files generated by the MIDL compiler, see General MIDL Command-line Syntax.

See Also

General MIDL Command-line Syntax, /header, /iid, /out


/rpcss

midl /rpcss

Example

midl /rpcss filename.idl

Remarks

The /rpcss switch, when specified, acts as though the enable_allocate attribute was specified on all operations of the interface. In the default mode of operation, the rpcss package is enabled only if either the procedure or interface has the enable_allocate attribute or the /rpcss switch is specified on the command line. In /osf mode, the server side stub enables the rpcss allocation package.

See Also

General MIDL Command-line Syntax, IDL, enable_allocate, /osf


/saux

This switch is obsolete and, if used, results in an error.


/server

midl /server { stub | none }

stub

Generates the server-side files.

none

Does not generate server-side files.

Examples

midl /server none

midl /server stub

Remarks

When the /server switch is not specified, the MIDL compiler generates the server stub file. This switch does not affect OLE interfaces.

The none option causes no files to be generated.

The /server switch takes precedence over the /sstub switch.

See Also

General MIDL Command-line Syntax, /client, /sstub


/sstub

midl /sstub stub_file_name

stub_file_name

Specifies a filename that overrides the default server stub filename. Filenames can be explicitly quoted using double quotes (") to prevent the shell from interpreting the special characters.

Example

midl /sstub my_sstub.c filename.idl

Remarks

The /sstub switch specifies the name of the server stub file for an RPC interface. The specified filename replaces the default filename. By default, the filename is obtained by adding _S.C to the name of the IDL file. This switch does not affect OLE interfaces.

When you are importing files, the specified filename applies to only one stub file — the stub file that corresponds to the IDL file specified on the command line.

If stub_file_name does not include an explicit path, the file is written to the current directory or the directory specified by the /out switch. An explicit path in stub_file_name overrides the /out switch specification.

The /server none switch takes precedence over the /sstub switch.

See Also

General MIDL Command-line Syntax, /cstub, /header, /out


/syntax_check

midl /syntax_check
midl /Zs

Examples

midl /Zs filename.idl

midl /syntax_check filename.idl

Remarks

The /syntax_check switch indicates that the compiler checks only syntax and does not generate output files. This switch overrides all other switches that specify information about output files.

You can also specify syntax-checking mode with the MIDL compiler option /Zs.

See Also

General MIDL Command-line Syntax, /Zs


/<system>

midl /<system>       where <system> is one of: /win16 /win32 /mac /mips
                                                                          /alpha /ppc /ppc32

Example

midl /alpha filename.idl

Remarks

Directs the MIDL compiler to generate a type library for the specified system.The default is the current operating system. The /mac switch directs MIDL to generate a type library for a 680x0-based Apple Macintosh system.

The /<system> switch is functionally the same as the MIDL /env option and is recognized by the MIDL compiler solely for backward compatibility with MKTYPLIB. If you are generating a new makefile, use the /env switch.

See Also

General MIDL Command-line Syntax, /env


/tlb

midl /tlb filename

filename

Specifies filename as the name of the output type library (TLB) file. By default, if the /tlb switch is not used, the TLB file has the same name as the IDL file, with the extension .TLB.

Example

midl /tlb newname.tlb

See Also

General MIDL Command-line Syntax


/U

midl /Uname

name

Specifies a defined name to be passed to the C preprocessor as if by a #undefine directive. The name is predefined by the C preprocessor or previously defined by the user.

Example

midl /UUNICODE filename.idl

Remarks

The /U switch removes any previous definition of a name by passing the name to the C preprocessor as if by a #undefine directive. Multiple /U directives can be used in a command line. White space between the /U switch and the undefined name is optional.

When the /cpp_cmd switch is present and the /cpp_opt switch is not, the MIDL compiler concatenates the string specified by the /cpp_cmd switch with the /I, /D, and /U options and uses this concatenated string to invoke the C preprocessor for each IDL and ACF source file. The MIDL compiler switch /U is ignored when the MIDL compiler switch /no_cpp or /cpp_opt is specified.

See Also

General MIDL Command-line Syntax, /cpp_cmd, /cpp_opt, /D, /I, /no_cpp


/use_epv

midl /use_epv

Example

midl /use_epv filename.idl

Remarks

The /use_epv switch directs the MIDL compiler to generate server stub code that calls the server application routine through an entry-point vector (epv), rather than by a static call.

Typically, applications require static linkage to the server application routine. The MIDL compiler generates such a call by default. However, if an application requires the server stub to call the server application routine by using the epv, the /use_epv switch must be specified. When the /use_epv switch is specified, the MIDL compiler generates a default epv. This default epv is then used if the application does not register another epv through the RpcServerRegisterIf call.

See Also

General MIDL Command-line Syntax, IDL, /no_default_epv, RpcServerRegisterIf


/W

midl /Wlevel

level

Specifies the warning level, an integer in the range 0 through 4. There is no space between the /W switch and the digit indicating the warning-level value.

Examples

midl /W2 filename.idl

midl /W4 bar.idl

Remarks

The /W switch specifies the warning level of the MIDL compiler. The warning level indicates the severity of the warning. Warning levels range from 1 to 4, with a value of zero meaning to display no warning information. The highest-severity warning is level 1. The following table describes the warnings for each warning level:

Warning level	Description	Example
W0	No warnings.
W1	Severe warnings that can cause application errors.	No binding handle specified, unattributed pointers, conflicting switches.
W2	May cause problems in the user’s operating environment.	Identifier length exceeds 31 characters. No default union arm specified.
W3	Reserved.
W4	Lowest warning level.	Non-ANSI C constructs.
Warnings are different from errors. Errors cause the MIDL compiler to halt processing of the IDL file. Warnings cause the MIDL compiler to emit an informational message and continue processing the IDL file.

The warning level set by the /W switch can be used with the /WX switch to cause the MIDL compiler to halt processing of the IDL file.

The /W switch behaves the same as the /warn switch.

See Also

General MIDL Command-line Syntax, /warn


/warn

midl /warnlevel

level

Specifies the warning level, an integer in the range 0 through 4. There is no space between the /warn switch and the digit indicating the warning-level value.

Examples

midl /warn2 filename.idl

midl /warn4 bar.idl

Remarks

The /warn switch specifies the warning level of the MIDL compiler. The warning level indicates the severity of the warning. Warning levels range from 1 to 4, with a value of zero meaning to display no warning information. The highest severity warning is level 1. The following table describes the warnings for each warning level:

Warning level	Description	Example
0	No warnings.
1	Severe warnings that can cause application errors.	No binding handle specified, unattributed pointers, conflicting switches.
2	May cause problems in the user’s operating environment.	Identifier length exceeds 31 characters. No default union arm specified.
3	Reserved.
4	Lowest warning level.	Non-ANSI C constructs.
Warnings are different from errors. Errors cause the MIDL compiler to halt processing of the IDL file. Warnings cause the MIDL compiler to emit an informational message and continue processing the IDL file.

The warning level set by the /warn switch can be used with the WX switch to cause the MIDL compiler to halt processing of the IDL file.

The /warn switch behaves the same as the /W switch.

See Also

General MIDL Command-line Syntax


/WX

midl /WX

Examples

midl /WX filename.idl

midl /W3 /WX filename.idl

Remarks

The /WX switch instructs the MIDL compiler to handle all errors at the given warning level as errors. If the /WX switch is specified and the /Wn switch is not specified, all warnings at the default level, level 1, are treated as errors.

The /Wn switch directs the compiler to display all warnings at level n and /WX directs the compiler to handle all warnings as errors. The combination of these two switches directs the compiler to handle all warnings at level n as errors.

Errors are different from warnings. Errors cause the MIDL compiler to halt processing of the IDL file. Warnings cause the MIDL compiler to emit an informational message and continue processing the IDL file.

Warning-level zero (0) directs the MIDL compiler to suppress warning information. When the /W0 and /WX switches are combined, the MIDL compiler suppresses all warning information. In this case, the /WX switch has no effect.

See Also

General MIDL Command-line Syntax, /W


/Zp

midl /Zppacking_level

packing_level

Specifies the packing level of structures in the target system. The packing-level value can be set to 1, 2, 4, or 8.

Example

midl /Zp4 filename.idl

Remarks

The /Zp switch is the same as the /pack option.

The /Zp switch designates the packing level of structures in the target system. The packing-level value corresponds to the /Zp option value used by the Microsoft C/C++ compiler. For more information, see your Microsoft C/C++ programming documentation.

Specify the same packing level when you invoke the MIDL compiler and the C compiler.

The default packing level used when you do not specify the /Zp or /pack switch is 8.

Note  Do not use /Zp1 or /Zp2 on MIPS or Alpha platforms and do not use /Zp4 or /Zp8 on 16-bit platforms. Depending on the data type and memory location assigned by the C compiler at run time, this can result in a data misalignment exception on MIPS and Alpha platforms. On MS-DOS platforms, the C compiler will not ensure the alignment at 4 or 8, and so the application may terminate.

See Also

General MIDL Command-line Syntax, /pack


/Zs

midl /Zs
midl /syntax_check

Examples

midl /Zs filename.idl

midl /syntax_check filename.idl

Remarks

The /Zs switch indicates that the compiler only checks syntax and does not generate output files.

This switch overrides all other switches that specify information about output files.

You can also specify syntax-checking mode with the MIDL compiler switch /syntax_check.

See Also

General MIDL Command-line Syntax, /syntax_check


Using The MIDL Compiler

The MIDL compiler is automatically installed as part of the Win32 SDK or Win16 SDK setup. The following topics describe MIDL’s C compiler and preprocessor requirements, the link libraries that are part of the RPC product, and the files that MIDL generates for OLE interfaces, RPC interfaces, and type libraries. For more information about the files that make up the RPC product, see Installing the RPC Programming Environment.


Help

A complete listing of MIDL compiler switches and options is available when you use the MIDL compiler /help and /? switches. The switches are organized by categories.


Response Files

As an alternative to placing all the options on the command line, the MIDL compiler accepts response files that contain switches and arguments. A response file is a text file containing one or more MIDL compiler command-line options. Unlike a command line, a response file allows multiple lines of options and filenames. This is important on systems such as MS-DOS that have a hard-coded limit on the length of a command line. You can specify a MIDL response file as:

midl @filename

filename

Specifies the name of the response file. The response filename must immediately follow the @ character. No white space is allowed between the @ character and the response filename.

Options in a response file are interpreted as if they were present at that place in the MIDL command line.

Each argument in a response file must begin and end on the same line. You cannot use the backslash character (\) to concatenate lines.

MIDL supports command-line arguments that include one or more response files, combined with other command-line switches:

midl -pack 4 @midl1.rsp -env win32 @midl2.rsp itf.idl

The MIDL compiler does not support nested response files.


C-Compiler and C-Preprocessor Requirements

The MIDL compiler must interoperate with the C compiler and C preprocessor. The following topics describe the requirements for the C compiler and preprocessor.


C-Preprocessor Requirements for MIDL

The MIDL compiler uses the C preprocessor during initial processing of the IDL file. The operating system used when you compile the IDL files is associated with a default C preprocessor. If you want to use a different C-preprocessor name, the MIDL compiler switch /cpp_cmd allows you to override the default C-preprocessor name:

midl /cpp_cmd cl386 filename

filename

Specifies the name of the IDL file.

During initial processing, the C preprocessor removes all preprocessor directives in the IDL file. After preprocessing, the only directive that can appear in a file is the #line directive in one of the following forms:

#line digit-sequence "filename" new-line

# digit-sequence "filename" new-line

Other directives should not appear in either the IDL file or any header file included by the IDL file. These other directives are not supported by the MIDL compiler and can cause errors. For a complete description of the line directive and other preprocessor directives, see your C-compiler documentation.

The MIDL compiler requires the C preprocessor to observe the following conventions:

•	The input file must be the last argument on the command line.

•	The preprocessor must direct output to the standard output device, stdout.

Preprocessor directives present in the IDL file do not appear in the header file generated by the MIDL compiler. For example, any values defined in the IDL file with the C #define statement are removed by the C preprocessor. These #define statements will not appear in the header file generated by the MIDL compiler. If such values are defined only in the MIDL file and are required by C source files, the C compiler will report errors when it tries to compile these source files.

These are the four workarounds that are recommended:

•	Use cpp_quote to reproduce #define in the generated header file.

•	Use const declaration specification.

•	Use header files that are included in the IDL file and the C source code.

•	Use enumeration constants in the IDL file.

To get a declaration in the generated header file with cpp_quote, use the following statement:

cpp_quote ("#define ARRSIZE 10");

This statement results in the following line being generated in the header file:

#define ARRSIZE 10

You can reproduce manifest constants using the constant-declaration syntax:

const short ARRSIZE = 10

This syntax results in the following line being generated in the header file:

#define ARRSIZE 10

You can define separate header files that contain only preprocessor directives and include them in both the IDL file and the C source files. Although the directives will not be available in the header file generated by the MIDL compiler, the C source program can include the separate header file.

You can also use enumeration constants in the IDL file. Enumeration constants are not removed during the early phases of MIDL compilation by the C-compiler preprocessor, so these constants are available in the header file generated by the MIDL compiler. For example, the statement

typedef enum midlworkaround { MAXSTRINGCOUNT = 300 };

will not be removed during MIDL compilation by the C preprocessor. The constant MAXSTRINGCOUNT is available to C source programs that include the header file generated by the MIDL compiler.


Verifying Preprocessor Options

To verify the correct operation of /cpp_opt options, invoke the C preprocessor independently before including the command line as part of the MIDL compiler command line. When called independently, the C compiler correctly reports errors caused by invalid options.

Incorrect usage of the MIDL command-line /cpp_opt switch can produce error messages related to the IDL file. These errors are incorrectly reported by the MIDL compiler when operating with some C compilers.

For example, invalid command-line syntax to the Microsoft C compiler can be reported as a syntax error in the IDL file when that syntax is included as part of the MIDL compiler command line. The error is not in the IDL file, but in the MIDL compiler /cpp_opt input.

The following MIDL compiler command line contains the /cpp_opt switch and related options:

midl /cpp_cmd "cl" /cpp_opt /E foo.idl

The options in this command line can be verified by invoking the compiler only, as shown:

cl /E foo.idl


C-Compiler Requirements for MIDL

The MIDL compiler requires the C compiler to support a packing level of 1, 2, 4, or 8. The command-line option for Microsoft C compilers that controls packing is /Zplevel, where level is the packing level 1, 2, 4, or 8. The following rules govern the alignment of compound types:

•	Base-type fields of size < packing level start on a (0 modulo size) address.

•	Base-type fields of size >= packing level start on a (0 modulo packing level) address.

•	The compound type itself (and any field of compound type) is aligned according to the strictest alignment requirement on any of its fields.

•	Compound types are padded to the next (0 modulo level) address. This padding appears in the size returned by the C SIZEOF macro.

As an example, consider a compound type consisting of a 1-byte character, an integer 4 bytes long, and a 1-byte character:

struct mystructtype {

    char c1;  /* requires 1 byte  */

    long l2;  /* requires 4 bytes */

    char c3;  /* requires 1 byte  */

 } mystruct;

For packing level 4, the structure mystruct is aligned on a (0 mod 4) boundary and sizeof(struct mystructtype) = 12.

For packing level 2, the structure mystruct is aligned on a (0 mod 2) boundary and sizeof(struct mystructtype) = 8.


C-Compiler Requirements for Callbacks in Microsoft Windows 3.x

When you use Microsoft 16-bit Visual C/C++ to develop your RPC application for Microsoft Windows 3.x platforms, compile with the /GA switch. The /GA switch directs the compiler to generate code that loads the DS register from the SS register on entry to a far exported function in a protected-mode application based on Windows 3.x.

For protected-mode, 16-bit Windows applications, the /GA switch allows the C compiler to generate the code for performing the housekeeping chores required when switching between tasks. This code is needed when your RPC interface contains one or more callback functions. Without this code, these callback functions can fail at run time due to an incorrect DS value.

When you use compilers other than Microsoft 16-bit Visual C/C++, use the compiler switch that is equivalent to /GA.

Previous versions of the Microsoft C compiler and 16-bit Windows used calls to the Windows 3.x function MakeProcInstance, and the /Gw switch to generate this code. The /GA switch is a more efficient way to accomplish the same tasks.

When you do not compile using the /GA switch (for example, when you are using a compiler that does not support the /GA switch), your application must:

1.	Compile using the /Gw switch (or its equivalent).

2.	Add the client stub functions to the EXPORTS section of the application’s DEF file.

3.	Replace function pointers in the the client stub function dispatch table with function pointers returned by MakeProcInstance.

The function dispatch table is part of the RPC_CLIENT_INTERFACE structure defined in the RPC header file RPCDCEP.H. For example, step 3 can be implemented using the following C code:

#include "hello.h"   // generated stub file

RPC_DISPATCH_FUNCTION Old, New;

HINSTANCE hInst;

RPC_CLIENT_INTERFACE * If = Hello_ClientIfHandle;

...

    for (i = 0; i < If->DispatchTable->DispatchTableCount; i++)

    {

       Old = If->DispatchTable->DispatchTable[i];

       New = (RPC_DISPATCH_FUNCTION) MakeProcInstance(Old, hInst);

       If->DispatchTable->DispatchTable[i] = New; // overwrite

    }

...


Link Libraries for MS-DOS

These are the static libraries that are included in MS-DOS for the RPC client application:

Static library	Description
RPC.LIB	Base RPC functions and name-service functions.
RPCNDR.LIB	NDR and other stub-helper functions.
NDRLIB10.LIB	If you are using MIDL 1.0 on MS-DOS, you must connect to this library. All other users should disregard this library. Note that this library is meant to be a temporary solution and MIDL 1.0 users should migrate to MIDL 2.0 at the earliest occasion.
The following RPC transports are included for MS-DOS clients:

Pseudo-dynamic-link library	Description
RPC16C1.RPC	Client named-pipe transport
RPC16C3.RPC	Client TCP/IP transport
RPC16C5.RPC	NetBIOS transport
RPC16DG3.RPC	Datagram UPD transport
RPC16DG6.RPC	Datagram IPX transport
RPC16C6.RPC	Client SPX transport
RPCNS.RPC	Name-service functions
RPCNSLM.RPC	LAN Manager support functions
RPCNSMGM.RPC	Name-service management functions


Link Libraries for Microsoft Windows 3.x

The following RPC import libraries are included for Microsoft 16-bit Windows clients:

Import library	Description
RPCW.LIB	RPC API and name-service functions.
RPCNDRW.LIB	NDR and other stub-helper functions.
The following RPC dynamic-link libraries are included for Microsoft 16-bit Windows clients:

Dynamic-link library	Description
RPCNS1.DLL	Name service
RPCRT1.DLL	16-bit Windows run-time library
RPC16C1.DLL	Client named-pipe transport
RPC16C3.DLL	Client TCP/IP transport
RPC16C5.DLL	Client NetBIOS transport
RPC16C6.DLL	SPX transport
RPC16DG3.DLL	Datagram UDP transport
RPC16DG6.DLL	Datagram IPX transport


Link Libraries for Microsoft Windows NT and Windows 95

The following RPC import libraries are included for Microsoft 32-bit Windows clients and servers:

Import library	Description
RPCNDR.LIB	Helper functions
RPCNS4.LIB	Name-service functions
RPCRT4.LIB	32-bit Windows run-time functions
The following RPC libraries are included for Microsoft 32-bit Windows clients and servers:

Dynamic-link library	Description
RPCLTC1.DLL	Client named-pipe transport
RPCLTS1.DLL	Server named-pipe transport (NT only)
RPCLTC3.DLL	Client TCP/IP transport
RPCLTS3.DLL	Server TCP/IP transport
RPCLTC5.DLL	Client NetBIOS transport
RPCLTS5.DLL	Server NetBIOS transport
RPCLTC6.DLL	Client SPX transport
RPCLTS6.DLL	Server SPX transport
RPCDGC6.DLL	Client IPX transport (NT only)
RPCDGS6.DLL	Server IPX transport (NT only)
RPCDGC3.DLL	Client UDP transport (NT only)
RPCDGS3.DLL	Server UDP transport (NT only)
RPCNS4.DLL	Name service
RPCRT4.DLL	32-bit Windows run-time library


Using the __midl Predefined Constant

When the MIDL compiler processes the input IDL and ACF files, __midl is defined by default and is used for conditional compilation to attain consistency throughout the build. This phases out the use of defines in the header files, such as MIDL_PASS, and replaces them with a consistent flag.

If you choose, you can override this default by specifying the following on the command line:

-U__midl

See also

/U


MIDL Compiler Errors and Warnings

This section lists MIDL compiler error and warning messages.

An error or warning message sometimes specifies the name of one or more MIDL compiler mode switches. The MIDL compiler accepts an IDL file when you use some mode switches but generates errors for the same file when you do not use mode switches. For example, you can include ACF attributes in an IDL file when you use the /app_config switch, but that IDL file will generate an error if you compile without using the /app_config switch.

Command-line errors appear in the following format:

Command line error : MIDLnnnn : <error text>

[<additional error information>]

The additional-error information field provides context-specific information about the error. The information in this field depends on the error message. For example, when an unresolved type-declaration error occurs, the additional-information field displays the name of the type that could not be resolved.

Compile-time warnings appear in the following format:

<FileName>(line#) : warning MIDLnnnn :

<warning text>

[optional context information] :

Compile-time errors appear in the following format:

<FileName>(line#) : error MIDLnnnn :

<error text>

[optional context information] :

Optional context information refers to the context in which the error occurred. The MIDL compiler reports this information to help you quickly find the error in the IDL file. Context information is generated when the MIDL compiler discovers an error during semantic analysis of type and procedure signatures.

MIDL1000 : missing source file name

No input file has been specified in the MIDL compiler command line.

MIDL1001 : cannot open input file

The input file specified could not be opened.

MIDL1002 : error while reading input file

The system returned an error while reading the input file.

MIDL1003 : error returned by the C preprocessor

The preprocessor returned an error. The error message is directed to the output stream.

MIDL1004 : cannot execute C preprocessor

The operating system reported an error when it tried to spawn the preprocessor. With MS-DOS, this error can occur when the argument list exceeds 128 bytes. You can reduce the size of the argument list by using a response file.

MIDL1005 : cannot find C preprocessor

The MIDL compiler cannot locate the preprocessor in the specified path or in the path specified by the PATH environment variable.

MIDL1006 : invalid C preprocessor executable

The specified preprocessor is not executable or has an invalid executable-file format.

MIDL1007 : switch specified more than once on command line

A switch has been redefined. The redefined switch is displayed after the error message.

MIDL1008 : unknown switch

An unknown switch has been specified on the command line.

MIDL1009 : unknown argument ignored

The MIDL compiler does not recognize the command-line argument as either a switch, a switch argument, or a filename. The compiler discards the unknown argument and attempts to continue processing.

MIDL1010 : switch not implemented

The switch is defined as part of the IDL compiler but is not implemented in Microsoft RPC.

MIDL1011 : argument(s) missing for switch

The switch expected an argument and the argument is not present. Check the syntax documentation for the specified switch.

MIDL1012 : argument illegal for switch /

The argument supplied to the specified switch is illegal.

MIDL1013 : illegal syntax for switch

Several command-line switches require a space between the switch and the argument, while other switches require no space between the switch and the argument. The specified command line violates the defined syntax for that switch.

MIDL1014 : /no_cpp overrides /cpp_cmd and /cpp_opt

The cpp_opt command has been supplied along with the /no_cpp switch. The /no_cpp switch takes precedence over the other switches.

MIDL1015 : /no_warn overrides warning-level switch

The no_warn option has been specified along with the warning-level switch W1, W2, or W3. The /no_warn switch takes precedence over all other warning-level switches.

MIDL1016 : cannot create intermediate file

The system returned an error when the compiler tried to create an intermediate file.

MIDL1018 : out of system file handles

The MIDL compiler ran out of file handles while opening a file. This error can occur if too many import files are open and the compiler tries to open an IDL file or an intermediate file.

MIDL1020 : cannot open response file

The specified response file could not be opened. The file probably does not exist.

MIDL1021 : illegal character(s) found in response file

A non-printable character has been detected in the response file. The response file should contain valid MIDL command-line switches and arguments.

MIDL1023 : nested invocation of response files is illegal

A response file cannot contain the @ command that directs the MIDL compiler to process another response file. Although there is no limit on the number of response files, response files cannot be nested.

MIDL2000 : must specify /c_ext for abstract declarators

Abstract declarators represent a Microsoft extension to RPC and are not defined in DCE RPC. To compile a file that includes abstract declarators, you must use the /c_ext switch.

MIDL2001 : instantiation of data is illegal; you must use “extern” or “static”

Declaration and initialization in the IDL file are not compatible with DCE RPC. This feature is a Microsoft extension and is not available when you compile in DCE-compatibility (osf) mode.

MIDL2002 : compiler stack overflow

The compiler ran out of stack space while processing the IDL file. This problem can occur when the compiler is processing a complex declaration or expression. To solve the problem, simplify the complex declaration or expression.

MIDL2003 : redefinition

This error message can appear under the following circumstances: a type has been redefined; a procedure prototype has been redefined; a member of a structure or union of the same name already exists; a parameter of the same name already exists in the prototype.

MIDL2004 : [auto_handle] binding will be used for procedure

No handle type has been defined as the default handle type. The compiler assumes that an auto handle will be used as the binding handle for the specified procedure.

MIDL2005 : out of memory

The compiler ran out of memory during compilation. Reduce the size or complexity of the IDL file or allocate more memory to the process.

MIDL2006 : recursive definition

A structure or union has been recursively defined. This error can occur when a pointer specification in a nested structure definition is missed.

MIDL2007 : import ignored; file already imported

Importing an IDL file is an idempotent operation. All but the first import operation are ignored.

MIDL2008 : sparse enums require /c_ext or /ms_ext switch

Assigning to enumeration constants is not compatible with DCE RPC. To use the extensions to RPC that permit assigning values to enumeration constants, use the /c_ext or /ms_ext switch.

MIDL2009 : undefined symbol

An undefined symbol has been used in an expression. This error can occur when you use an enum label that is not defined.

MIDL2010 : type used in ACF file not defined in IDL file

An undefined type is being used.

MIDL2011 : unresolved type declaration

The type reported in the additional-information field has not been defined elsewhere in the IDL file.

MIDL2012 : use of wide-character constants requires /ms_ext or /c_ext

Wide-character constants are a Microsoft extension to DCE IDL. To enable the use of the data type wchar_t, use the MIDL compiler switch /ms_ext or /c_ext.

MIDL2013 : use of wide-character strings requires /ms_ext or /c_ext

Wide-character string constants are a Microsoft extension to DCE IDL. To enable the use of the data type wchar_t, use the MIDL compiler switch /ms_ext or /c_ext.

MIDL2014 : inconsistent redefinition of type wchar_t

The type wchar_t has been redefined as a type that is not equivalent to unsigned short.

MIDL2017 : syntax error

The compiler detected a syntax error at the specified line.

MIDL2018 : cannot recover from earlier syntax errors; aborting compilation

The MIDL compiler automatically tries to recover from syntax errors by adding or removing syntactic elements. This message indicates that despite these attempts to recover, the compiler detected too many errors. Correct the specified error(s) and recompile.

MIDL2019 : unknown pragma option

The specified C pragma is not supported in MIDL. Remove the pragma from the IDL file.

MIDL2020 : feature not implemented

The MIDL feature, although part of the language definition, is not implemented in Microsoft RPC and is not supported by the MIDL compiler. For example, the following language features are not implemented: bitset, pipe, and the international character type. The unimplemented language feature appears in the additional-information field of the error message.

MIDL2021 : type not implemented

The specified data type, although a legal MIDL keyword, is not implemented in Microsoft RPC.

MIDL2022 : non-pointer used in a dereference operation

A data type that is not a pointer has been associated with pointer operations. You cannot access the object through the specified non-pointer.

MIDL2023 : expression has a divide by zero

The constant expression contains a divide by zero.

MIDL2024 : expression uses incompatible types

The left and right sides of the operator in an expression are of incompatible types.

MIDL2025 : non-array expression uses index operator

The expression uses the array-indexing operation on a data item that is not of the array type.

MIDL2026 : left-hand side of expression does not evaluate to struct/union/enum

The direct or indirect reference operator “.” or “->“ has been applied to a data object that is not a structure, union, or enum. You cannot obtain a direct or indirect reference using the specified object.

MIDL2027 : constant expression expected

A constant expression was expected in the syntax. For example, array bounds require a constant expression. The compiler issues this error message when the array bound is defined with a variable or undefined symbol.

MIDL2028 : expression cannot be evaluated at compile time

The compiler cannot evaluate an expression at compile time.

MIDL2029 : expression not implemented

A feature that was supported in previous releases of the MIDL compiler is not supported in the version of the compiler supplied with Microsoft RPC. Remove the specified feature.

MIDL2030 : no [pointer_default] specified, assuming [unique] for all unattributed pointers

The MIDL compiler offers three different default cases for pointers that do not have pointer attributes. Function parameters that are top-level pointers default to ref pointers. Pointers embedded in structures and pointers to other pointers (not top-level pointers) default to the type specified by the pointer_default attribute. When no pointer_default attribute is supplied, these non-top-level pointers default to unique pointers. This error message indicates the last case: no pointer_default attribute is supplied and there is at least one non-top-level pointer that will be treated as a unique pointer.

MIDL2031 : [out] only parameter cannot be a pointer to an open structure

An out-only parameter has been used as a pointer to a structure, known as an open structure, whose transmitted range and size are determined at run time. The server stub does not know how much space to allocate for an open structure. Use a pointer to a pointer to the open structure and ensure that the server application allocates sufficient space for it.

MIDL2032 : [out] only parameter cannot be an unsized string

An array with the string attribute has been declared as an out-only parameter without any size specification. The server stub needs size information to allocate memory for the string. You can remove the string attribute and add the size_is attribute, or you can change the parameter to an in, out parameter.

MIDL2033 : [out] parameter is not a pointer

All out parameters must be pointers, in keeping with the call-by-value convention of the C programming language. The out directional parameter indicates that the server transmits a value to the client. With the call-by-value convention, the server can transmit data to the client only if the function argument is a pointer.

MIDL2034 : open structure cannot be a parameter

A structure or union is truncated when the last element of that structure or union is a conformant array.

MIDL2035 : [out] context handle/generic handle must be specified as a pointer to that handle type

A context-handle or user-defined handle parameter with the out directional attribute must be a pointer to a pointer.

MIDL2036 : [context_handle] must not derive from a type that has the [transmit_as] attribute

Context handles must be transmitted as context-handle types. They cannot be transmitted as other types.

MIDL2037 : cannot specify a variable number of arguments to a remote procedure

Remote procedure calls that specify the number of variable arguments at compile time are not compatible with the DCE RPC definition. You cannot use a variable number of arguments in Microsoft RPC.

MIDL2038 : named parameter cannot be “void”

A parameter with the base type void is specified with a name.

MIDL2040 : cannot use [comm_status] on both a parameter and a return type

Both the procedure and one of its parameters have the comm_status attribute. The comm_status attribute specifies that only one data object can be of type error_status_t at a time.

MIDL2041 : [local] attribute on a procedure requires /ms_ext

A procedure uses the local attribute as a function attribute, which is not compatible with DCE RPC. To enable the Microsoft RPC extensions, use the MIDL compiler switch /ms_ext.

MIDL2042 : field deriving from a conformant array must be the last member of the structure

The structure contains a conformant array that is not the last element in the structure. The conformant array must appear as the last structure element.

MIDL2043 : duplicate [case] label

A duplicate case label has been specified. The duplicate label is displayed.

MIDL2044 : no [default] case specified for discriminated union

A discriminated union has been specified without a default case.

MIDL2045 : attribute expression cannot be resolved

The expression associated with the attribute cannot be resolved. This error usually occurs when a variable that appears in the expression is not defined. For example, the error can occur when the variable s is not defined and is used by the attribute size_is(s).

MIDL2046 : attribute expression must be of integral type

The specified attribute variable or expression must be an integral type. This error occurs when the attribute-expression type does not resolve to an integer.

MIDL2047 : [byte_count] requires /ms_ext

The byte_count attribute represents an extension to DCE RPC. To enable the Microsoft RPC extensions, use the MIDL compiler switch /ms_ext.

MIDL2048 : [byte_count] can be applied only to out parameters of pointer type

The byte_count attribute can only be applied to out parameters, and all out parameters must be pointer types.

MIDL2049 : [byte_count] cannot be specified on a pointer to a conformant array or structure

The byte_count attribute cannot be applied to a conformant array or structure.

MIDL2050 : parameter specifying the byte count is not [in]

The value associated with the byte_count must be transmitted from the client to the server; it must be an in parameter. The byte_count parameter does not need to be an in, out parameter.

MIDL2051 : parameter specifying the byte count is not an integral type

The value associated with the byte count must be the integer type small, short, or long.

MIDL2052 : [byte_count] cannot be specified on a parameter with size attributes

The byte_count attribute cannot be used with other size attributes such as size_is or length_is.

MIDL2053 : [case] expression is not constant

The expression specified for the case label is not a constant.

MIDL2054 : [case] expression is not of integral type

The expression specified for the case label is not an integer type.

MIDL2055 : specifying [context handle] on a type other than void * requires /ms_ext

For DCE RPC compatibility, the context handle must be a pointer of type void *. To use the Microsoft RPC extensions that allow context handles to be associated with types other than void *, use the MIDL compiler switch /ms_ext.

MIDL2056 : cannot specify more than one parameter with each of comm_status/fault_status

The comm_status attribute may only appear once, and the fault_status attribute may only appear once per procedure.

MIDL2057 : error_status_t parameter must be an [out] only pointer parameter

The error-code type error_status_t is transmitted from server to client and therefore must be specified as an out parameter. Due to the constraints in the C programming language, all out parameters must be pointers.

MIDL2058 : endpoint syntax error

The endpoint syntax is incorrect.

MIDL2059 : inapplicable attribute

The specified attribute cannot be applied in this construct. For example, the string attribute applies to char arrays or char pointers and cannot be applied to a structure that consists of two short integers:

typedef [string] struct foo {

    short x;

    short y;

};

MIDL2060 : [allocate] requires /ms_ext

The allocate attribute represents a Microsoft extension that is not defined as part of DCE RPC. To enable the Microsoft extensions, use the /ms_ext switch.

MIDL2061 : invalid [allocate] mode

An invalid mode for the allocate attribute construct has been specified. The four valid modes are single_node, all_nodes, on_null, and always.

MIDL2062 : length attributes cannot be applied with string attribute

When the string attribute is used, the generated stub files call the strlen function to determine the string length. Don’t use the length attribute and the string attribute for the same variable.

MIDL2063 : [last_is] and [length_is] cannot be specified at the same time

Both last_is and length_is have been specified for the same array. These attributes are related as follows: length = last - first + 1. Because each value can be derived from the other, don’t specify both.

MIDL2064 : [max_is] and [size_is] cannot be specified at the same time

Both max_is and size_is have been specified for the same array. These attributes are related as follows: max = size + 1. Because each value can be derived from the other, don’t specify both.

MIDL2065 : no [switch_is] attribute specified at use of union

No discriminant has been specified for the union. The switch_is attribute indicates the discriminant used to select among the union fields.

MIDL2066 : no [uuid] specified for interface

No UUID has been specified for the interface.

MIDL2067 : cannot specify both [local] and [uuid] as interface attributes

The local and UUID keywords cannot be used at the same time, except on [object] interfaces.

MIDL2068 : type mismatch between length and size attribute expressions

The length and size attribute expressions must be of the same types. For example, this warning is issued when the attribute variable for the size_is expression is of type unsigned long and the attribute variable for the length_is expression is of type long.

MIDL2069 : [string] attribute must be specified “byte”, “char”, or “wchar_t” array or pointer

A string attribute cannot be applied to a pointer or array whose base type is not a byte, char, or struct in which the members are all of the byte or char type.

MIDL2070 : mismatch between the type of the [switch_is] expression and the switch type of the union

If the union switch_type is not specified, the switch type is the same type as the switch_is field.

MIDL2071 : [transmit_as] cannot be applied to a type that derives from a context handle

Context handles cannot be transmitted as other types.

MIDL2072 : [transmit_as] must specify a transmissible type

The specified transmit_as type derives from a type that cannot be transmitted by Microsoft RPC, such as void, void *, or int. Use a defined RPC base type; in the case of int, add size specifiers like small, short, or long to qualify the int.

MIDL2073 : transmitted type must not be a pointer or derive from a pointer

The transmitted type cannot be a pointer or derive from a pointer.

MIDL2074 : presented type must not derive from a conformant/varying array, its pointer equivalent, or a conformant/varying structure

The type to which transmit_as has been applied cannot derive from a conformant array or structure (an array or structure whose size is determined at run time).

MIDL2075 : [uuid] format is incorrect

The UUID format does not conform to specification. The UUID must be a string that consists of five sequences of hexadecimal digits of length 8, 4, 4, 4, and 12 digits. “12345678-1234-ABCD-EF01-28A49C28F17D” is a valid UUID. Use the function UuidCreate or a utility to generate a valid UUID.

MIDL2076 : uuid is not a hex number

The UUID specified for the interface contains characters that are invalid in a hexadecimal number representation. The characters 0 through 9 and A through F are valid in a hexadecimal representation.

MIDL2077 : interface name specified in the ACF file does not match that specified in the IDL file

In this compiler mode, the name that follows the interface keyword in the ACF must be the same as the name that follows the interface keyword in the IDL file. The interface names in the IDL and ACF files can be different when you compile with the MIDL compiler switch /acf.

MIDL2078 : conflicting attributes

Conflicting attributes have been specified. This error often occurs when two attributes are mutually exclusive. For example, the attributes code and nocode cannot be used at the same time.

MIDL2080 : [local] procedure cannot be specified in ACF file

A local procedure has been specified in the ACF. The local procedure can only be specified in the IDL file.

MIDL2081 : specified type is not defined as a handle

The type specified in the implicit_handle attribute is not defined as a handle type. Change the type definition or the type name specified by the attribute.

MIDL2082 : procedure undefined

An attribute has been applied to a procedure in the ACF and that procedure is not defined in the IDL file.

MIDL2083 : this parameter does not exist in the IDL file

A parameter specified in the ACF does not exist in the definition in the IDL file. All parameters, functions, and type definitions that appear in the ACF must correspond to parameters, functions, and types previously defined in the IDL file.

MIDL2084 : this array bounds construct is not supported

MIDL currently supports array-bounds constructs of the form Array[Lower .. Upper] only when the constant that specifies the lower bound of the array resolves to the value zero.

MIDL2085 : array bound specification is illegal

The user specification of array bounds for the fixed-size array is illegal. For example:

typedef short Array[-1]

MIDL2087 : pointee / array does not derive any size

A conformant array has been specified without any size specification. You can specify the size with the max_is or size_is attribute.

MIDL2088 : badly formed character constant

The end-of-line character is not allowed in character constants.

MIDL2089 : end of file found in comment

The end-of-file character has been encountered in a comment.

MIDL2090 : end of file found in string

The end-of-file character has been encountered in a string.

MIDL2091 : identifier length exceeds 31 characters

Identifiers are limited to 31 alphanumeric characters. Identifier names longer than 31 characters are truncated.

MIDL2092 : end of line found in string

The end-of-line character has been encountered in the string. Verify that you have included the double-quote character that terminates the string.

MIDL2093 : string constant exceeds limit of 255 characters

The string exceeded the maximum allowable length of 255 characters.

MIDL2094 : constant too big

The constant is too large to be represented internally.

MIDL2095 : error in opening file

The operating system reported an error while trying to open an output file. This error can be caused by a name that is too long for the file system or by a duplicate filename.

MIDL2096 : [out] only parameter must not derive from a top-level [unique] or [ptr] pointer/array

A unique pointer cannot be an out-only parameter. By definition, a unique pointer can change from null to non-null. No information about the out-only parameter is passed from client to server.

MIDL2097 : attribute is not applicable to this non-rpcable union

The switch_is and switch_type attributes apply to a union that is transmitted as part of a remote procedure call.

MIDL2098 : expression used for a size attribute must not derive from an [out] only parameter

The value of an out-only parameter is not transmitted to the server and cannot be used to determine the length or size of the in parameter.

MIDL2099 : expression used for a length attribute for an [in] parameter cannot derive from an [out] only parameter

The value of an out-only parameter is not transmitted to the server and cannot be used to determine the length or size of the in parameter.

MIDL2100 : use of “int” needs /c_ext

MIDL is a strongly typed language. All parameters transmitted over the network must be derived from one of the MIDL base types. The type int is not defined as part of MIDL. Transmitted data must include a size specifier: small, short, or long. Data that is not transmitted over the network can be included in an interface; use the /c_ext switch.

MIDL2101 : struct/union field must not be void

Fields in a structure or union must be declared to be of a specific base type supported by MIDL or a type that is derived from the base types. Void types are not allowed in remote operations.

MIDL2102 : array element must not be void

An array element cannot be void.

MIDL2103 : use of type qualifiers and/or modifiers needs /c_ext

Type modifiers such as _cdecl and _far can be compiled only if you specify the /c_ext switch.

MIDL2104 : struct/union field must not derive from a function

The fields of a structure or union must be MIDL base types or types that are derived from these base types. Functions are not legal in structure or union fields.

MIDL2105 : array element must not be a function

An array element cannot be a function.

MIDL2106 : parameter must not be a function

The parameter to a remote procedure must be a variable of a specified type. A function cannot be a parameter to the remote procedure.

MIDL2107 : struct/union with bit fields needs /c_ext

You must specify the MIDL compiler switch /c_ext to allow bit fields on data that is not transmitted in a remote procedure call.

MIDL2108 : bit field specification on a type other that “int” is a non ANSI-compatible extension

The ANSI C programming language specification does not allow bit fields to be applied to non-integer types.

MIDL2109 : bit field specification can be applied only to simple, integral types

The ANSI C programming language specification does not allow bit fields to be applied to non-integer types.

MIDL2110 : struct/union field must not derive from handle_t or a context_handle

Context handles cannot be transmitted as part of another structure. They must be transmitted as context handles.

MIDL2111 : array element must not derive from handle_t or a context handle

Context handles cannot be transmitted as part of an array.

MIDL2112 : this specification of union needs /c_ext

A union that appears in the interface definition must be associated with the discriminant or declared as local. Data that is not transmitted over the network can be implicitly declared as local when you use the /c_ext switch.

MIDL2113 : parameter deriving from an “int” must have size specifier “small”, “short”, or “long” with the “int”

The type int is not a valid MIDL type unless it is accompanied by a size specification. Use one of the size specifiers small, short, or long.

MIDL2114 : type of the parameter cannot derive from void or void*

MIDL is a strongly typed language. All parameters transmitted over the network must be derived from one of the MIDL base types. MIDL does not support void as a base type. You must change the declaration to a valid MIDL type.

MIDL2115 : parameter deriving from a struct/union containing bit fields is not supported

Bit fields are not defined as a valid data type by DCE RPC.

MIDL2116 : use of a parameter deriving from a type containing type-modifiers/type-qualifiers needs /c_ext

Such keywords as far, near, const, and volatile can appear in the IDL file only when you activate the /c_ext extension to the MIDL compiler.

MIDL2117 : parameter must not derive from a pointer to a function

The RPC run-time libraries transmit a pointer and its associated data between client and server. Pointers to functions cannot be transmitted as parameters because the function cannot be transmitted over the network.

MIDL2118 : parameter must not derive from a non-rpcable union

The union must be associated with a discriminant. Use the switch_is and switch_type attributes.

MIDL2119 : return type derives from an “int”. You must use size specifiers with the “int”

The type int is not a valid MIDL type unless it is accompanied by a size specification. Use one of the size specifiers small, short, or long.

MIDL2120 : return type must not derive from a void pointer

MIDL is a strongly typed language. All parameters transmitted over the network must be derived from one of the MIDL base types. Void types are not defined as part of MIDL. You must change the declaration to a valid MIDL type.

MIDL2121 : return type must not derive from a struct/union containing bit-fields

Bit fields are not defined as a valid data type by DCE RPC.

MIDL2122 : return type must not derive from a non-rpcable union

The union must be associated with a discriminant. Use the switch_is and switch_type attributes.

MIDL2123 : return type must not derive from a pointer to a function

The RPC run-time libraries transmit a pointer and its associated data between client and server. Pointers to functions cannot be transmitted as parameters because RPC does not define a method to transmit the associated function over the network.

MIDL2124 : compound initializers are not supported

DCE RPC supports simple initialization only. The structure or array cannot be initialized in the IDL file.

MIDL2125 : ACF attributes in the IDL file need the /app_config switch

A Microsoft extension allows you to specify ACF attributes in the IDL file. Use the /app_config switch to activate this extension.

MIDL2126 : single line comment needs /ms_ext or /c_ext

Single-line comments that use two slash characters (//) represent a Microsoft extension to DCE RPC. You must use one of the mode-extension switches for a single-line comment.

MIDL2127 : [version] format is incorrect

The interface version number in the interface header must be specified in the format major.minor, where each number can range from 0 to 65535.

MIDL2128 : “signed” needs /ms_ext or /c_ext

The use of the signed keyword is a Microsoft extension to DCE RPC. You must use one of the mode-extension switches to activate this extension.

MIDL2129 : mismatch in assignment type

The type of the variable does not match the type of the value that is assigned to the variable.

MIDL2130 : declaration must be of the form: const <type><declarator> = <initializing expression>

The declaration is not compatible with DCE RPC syntax. Use the /ms_ext or /c_ext MIDL compiler mode switch.

MIDL2131 : declaration must have “const”

Declarations in the IDL file must be constant expressions that use the keyword const. For example:

const short x = 2;

MIDL2132 : struct/union/enum must not be defined in a parameter type specification

The structure, union, or enumerated type must be explicitly specified outside of the function prototype.

MIDL2133 : [allocate] attribute must be applied only on non-void pointer types

The allocate attribute is designed for complex pointer-based data structures. When the allocate attribute is specified, the stub file traverses the data structure to compute the total size of all objects accessible from the pointer and all other pointers in the data structure. Change the type to a non-void pointer type or remove the allocate attribute and use another method to determine its allocation size, such as the sizeof operator.

MIDL2134 : array or equivalent pointer construct cannot derive from a non-encapsulated union

Each union must be associated with a discriminant. Arrays of unions are not permitted because they do not provide the associated discriminant. Arrays of structures are permitted because each structure consists of the union and its discriminant.

MIDL2135 : field must not derive from an error_status_t type

The error_status_t type can only be used as a parameter or a return type. It cannot be embedded in the field of a structure or union.

MIDL2136 : union has at least one arm without a case label

The union declaration does not match the required MIDL syntax for the union. Each union arm requires a case label or default label that selects that union arm.

MIDL2137 : a parameter or a return value must not derive from a type which has [ignore] applied to it

The ignore attribute is a field attribute that can only be applied to fields, such as fields of structures and arrays. The ignore attribute indicates that the stub should not dereference the pointer during transmission and is not allowed when it conflicts with other attributes that must be dereferenced, such as out parameters and function return values.

MIDL2138 : pointer already has a pointer-attribute applied to it

Only one of the pointer attributes, ref, unique, or ptr, can be applied to a pointer.

MIDL2139 : field/parameter must not derive from a structure that is recursive through a ref pointer

By definition, a reference pointer cannot be set to NULL. A recursive data structure defined with a reference pointer has no null elements and by convention is non-terminating. Use a unique pointer attribute to allow the data structure to specify a null element or redefine the data structure as a non-recursive data structure.

MIDL2140 : use of field deriving from a void pointer needs /c_ext

The type void * and other types and type qualifiers that are not supported by DCE IDL are only allowed in the IDL file when you use the MIDL compiler switch /c_ext. Redefine the pointer type or recompile using the /c_ext switch.

MIDL2141 : use of this attribute needs /ms_ext

This language feature is a Microsoft extension to DCE IDL. You must specify the MIDL compiler switch /ms_ext.

MIDL2142 : use of wchar_t needs /ms_ext or /c_ext

The wide-character type represents an extension to DCE IDL. The MIDL compiler accepts the wide-character type only when you specify the /ms_ext or /c_ext switch.

MIDL2143 : unnamed fields need /ms_ext or /c_ext

DCE IDL does not support the use of unnamed structures or unions embedded in other structures or unions. In DCE IDL, all such embedded fields must be named. To enable this Microsoft extension to IDL, supply the MIDL compiler switch /ms_ext or /c_ext.

MIDL2144 : unnamed fields can derive only from struct/union types

The Microsoft extension to the DCE IDL that supports unnamed fields applies only to structures and unions. You must assign a name to the field or redefine the field to comply with this restriction.

MIDL2145 : field of a union cannot derive from a varying/conformant array or its pointer equivalent

The conformant array cannot appear alone in the union but must be accompanied by the value that specifies the size of the array. Instead of using the array as the union arm, use a structure that consists of the conformant array and the identifier that specifies the size.

MIDL2146 : no [pointer_default] attribute specified, assuming [ptr] for all unattributed pointers in interface

The DCE IDL implementation specifies that all pointers in each IDL file must be associated with pointer attributes. When an explicit pointer attribute is not assigned to the parameter or pointer type and no pointer_default attribute is specified in the IDL file, the full pointer attribute ptr is associated with the pointer. You can change the pointer attributes by using explicit pointer attributes, by specifying a pointer_default attribute, or by specifying the /ms_ext switch to change the default for unattributed pointers to unique.

MIDL2147 : initializing expression must resolve to a constant expression

The use of initializing expressions is limited to constant expressions in all MIDL compiler modes. The expression must be resolvable at compile time. Specify a literal constant, or an expression that resolves to a constant, rather than a variable.

MIDL2148 : attribute expression must be of type integer, char, byte, boolean or enum

The specified type does not resolve to a valid switch type. Use an integer, character, byte, boolean, or enum type, or a type that is derived from one of these types.

MIDL2149 : illegal constant

The specified constant is out of the valid range for the specified type.

MIDL2150 : attribute not implemented; ignored

The attribute specified is not implemented in this release of Microsoft RPC. The MIDL compiler continues processing the IDL file as if the attribute were not present.

MIDL2151 : return value must not derive from a [ref] pointer

Function return values that are defined to be pointer types must be specified as unique or full pointers. Reference pointers cannot be used.

MIDL2152 : attribute expression must be a variable name or a pointer dereference expression in this mode. You must specify the /ms_ext switch

The DCE IDL compiler requires the size associated with the size_is attribute to be specified by a variable or pointer variable. To enable the Microsoft extension that allows the size_is attribute to be defined by a constant expression, use the /ms_ext switch.

MIDL2153 : parameter must not derive from a recursive non-encapsulated union

A union must include a discriminant, so a union cannot have another union as an element. A union can be embedded in another union only when it is part of a structure that includes the discriminant.

MIDL2154 : binding-handle parameter cannot be [out] only

The handle parameter identified by the MIDL compiler as the binding handle for this operation must be an in parameter. Out-only parameters are undefined on the client stub, and the binding handle must be defined on the client.

MIDL2155 : pointer to a handle cannot be [unique] or [ptr]

The unique and full pointer attributes allow the value NULL. The binding handle cannot be null. Use the ref attribute to derive the binding-handle parameter from reference pointers.

MIDL2156 : parameter that is not a binding handle must not derive from handle_t

The primitive handle type handle_t is not a valid data type that is transmitted over the network. Change the parameter type to a type other than handle_t or remove the parameter.

MIDL2157 : unexpected end of file found

The MIDL compiler found the end of the file before it was able to successfully resolve all syntactical elements of the file. Verify that the terminating right brace character (}) is present at the end of the file, or check the syntax.

MIDL2158 : type deriving from handle_t must not have [transmit_as] applied to it

The primitive handle type handle_t is not transmitted over the network.

MIDL2159 : [context_handle] must not be applied to a type that has [handle] applied to it

The context_handle and handle attributes cannot be applied to the same type.

MIDL2160 : [handle] must not be specified on a type deriving from void or void *

A type specified with the handle attribute can be transmitted over the network, but the type void * is not a transmissible type. The handle type must resolve to a type that derives from the valid base types.

MIDL2161 : parameter must have either [in], [out] or [in,out] in this mode. You must specify /ms_ext or /c_ext

The DCE IDL compiler requires all parameters to have explicit directional parameters. To use the Microsoft extensions to DCE IDL, where you can omit explicit directional attributes, use the MIDL compiler switch /ms_ext or /c_ext.

MIDL2162 : [transmit_as] must not be specified on void type

The transmit_as attribute applies only to pointer types. Use the type void * in place of void.

MIDL2163 : void must be specified on the first and only parameter specification

The keyword void incorrectly appears with other function parameters. To specify a function without parameters, the keyword void must be the only element of the parameter list, as in the following example:

void Foo(void)

MIDL2164 : [switch_is] must be specified only on a type deriving from a non-encapsulated union

The switch_is keyword is incorrectly applied. It can only be used with non-encapsulated union types. For more information, see the syntax section in the reference entry for non-encapsulated unions.

MIDL2165 : stringable structures are not implemented in this version

DCE IDL allows the attribute string to apply to a structure whose elements consist only of characters, bytes, or types that resolve to characters or bytes. This functionality is not supported in Microsoft RPC. The string attribute cannot be applied to the structure as a whole; it can be applied to each individual array.

MIDL2166 : switch type can only be integral, char, byte, boolean or enum

The specified type does not resolve to a valid switch type. Use an integer, character, byte, boolean, or enum type, or a type that is derived from one of these types.

MIDL2167 : [handle] must not be specified on a type deriving from handle_t

A handle type must be defined using one and only one of the handle types or attributes. Use the primitive type handle_t or the attribute handle, but not both. The user-defined handle type must be transmissible, but the handle_t type is not transmitted on the network.

MIDL2168 : parameter deriving from handle_t must not be an [out] parameter

A handle of the primitive type handle_t is meaningful only to the side of the application in which it is defined. The type handle_t is not transmitted on the network.

MIDL2169 : expression specifying size or length attributes derives from [unique] or [ptr] pointer dereference

Although the unique and full pointer attributes allow pointers to have null values, the expression that defines the size or length attribute must never have a null value. When pointers are used, MIDL constrains expressions to ref pointers.

MIDL2170 : “cpp_quote” requires /ms_ext

The cpp_quote attribute is a Microsoft extension to DCE IDL. Use the MIDL compiler switch /ms_ext.

MIDL2171 : quoted uuid requires /ms_ext

The ability to specify a UUID value within quotation marks is a Microsoft extension to DCE IDL. Use the MIDL compiler switch /ms_ext.

MIDL2172 : return type cannot derive from a non-encapsulated union

The non-encapsulated union cannot be used as a function return type. To return the union type, specify the union type as an out or in, out parameter.

MIDL2173 : return type cannot derive from a conformant structure

The size of the return type must be a constant. You cannot specify as a return type a structure that contains a conformant array even when the structure also includes its size specifier. To return the conformant structure, specify the structure as an out or in, out parameter.

MIDL2174 : [transmit_as] must not be applied to a type deriving from a generic handle

In this release, the handle and transmit_as attributes cannot be combined on the same type.

MIDL2175 : [handle] must not be applied to a type that has [transmit_as] applied to it

In this release, the handle and transmit_as attributes cannot be combined on the same type.

MIDL2176 : type specified for the const declaration is invalid

Const declarations are limited to integer, character, wide-character, string, and boolean types.

MIDL2177 : operand to the sizeof operator is not supported

The MIDL compiler supports the sizeof operation for simple types only.

MIDL2178 : this name already used as an const identifier name

The identifier has previously been used to identify a constant in a const declaration. Change the name of one of the identifiers so that the identifiers are unique.

MIDL2179 : inconsistent redefinition of type error_status_t

The type error_status_t must resolve to the type unsigned long. Other type definitions cannot be used.

MIDL2180 : [case] value out of range of switch type

The value associated with the switch statement case is out of range for the specified switch type. For example, this error occurs when a long integer value is used in the case statement for a short integer type.

MIDL2181 : parameter deriving from wchar_t needs /ms_ext

The wide-character type wchar_t is a Microsoft extension to DCE IDL. Use the MIDL compiler switch /ms_ext.

MIDL2182 : this interface has only callbacks

Callbacks are valid only in the context of a remote procedure call. The interface must include at least one function prototype for a remote procedure call that does not include the callback attribute.

MIDL2183 : redundantly specified attribute; ignored

The specified attribute has been applied more than once. Multiple instances of the same attribute are ignored.

MIDL2184 : context handle type used for an implicit handle

A type that was defined using the context_handle attribute has been specified as the handle type in an implicit_handle attribute. The attributes cannot be combined in this way.

MIDL2185 : conflicting options specified for [allocate]

The options specified for the ACF attribute allocate represent conflicting directives. For example, specify either the option all_nodes or the option single_node, but not both.

MIDL2186 : error while writing to file

An error occurred while writing to the file. This condition can be caused by errors relating to disk space, file handles, file-access restrictions, and hardware failures.

MIDL2187 : no switch type found at definition of union, using the [switch_is] type

The union definition does not include an explicit switch_type attribute. The type of the variable specified by the switch_is attribute is used as the switch type.

MIDL2188 : semantic check incomplete due to previous errors

The MIDL compiler makes two passes over the input file(s) to resolve any forward declarations. Due to errors encountered during the first pass, checking for the second pass has not been performed. Unreported errors relating to forward declarations may still be present in the file.

MIDL2189 : handle parameter or return type is not supported on a [callback] procedure

A callback procedure occurs in the context of a call from a client to the server and uses the same binding handle as the original call. Explicit binding-handle parameters or return types are not permitted in callback functions.

MIDL2192 : [context_handle] must not derive from handle_t

The three handle characteristics — the type handle_t, the attribute handle, and the attribute context_handle — are mutually exclusive. Only one can be applied to a type or parameter at a time.

MIDL2193 : array size exceeds 65536 bytes

On some Microsoft platforms, the maximum transmissible data size is 64K. Redesign your application so that all transmitted data fits within the maximum transmissible size.

MIDL2194 : field of a non-encapsulated union cannot be another non-encapsulated union

Unions that are transmitted as part of a remote procedure call require an associated data item, the discriminant, that selects the union arm. Unions nested in other unions do not offer a discriminant; as a result, they cannot be transmitted in this form. Create a structure that consists of the union and its discriminant.

MIDL2195 : pointer attribute(s) applied on an embedded array; ignored

A pointer attribute can be applied to an array only when the array is a top-level parameter. Other pointer attributes applied to arrays embedded in other data structures are ignored.

MIDL2196 : [allocate] is illegal on a type that has [transmit_as] applied to it

The transmit_as and allocate attributes cannot both be applied to the same type. The transmit_as attribute distinguishes between presented and transmitted types, while the allocate attribute assumes that the presented type is the same as the transmitted type.

MIDL2198 : [implicit_handle] type undefined; assuming primitive handle

The handle type specified in the ACF is not defined in the IDL file. The MIDL compiler assumes that the handle type resolves to the primitive handle type handle_t. Add the handle attribute to the type definition if you want the handle to behave like a user-defined, or generic, handle.

MIDL2199 : array element must not derive from error_status_t

In this release of Microsoft RPC, the type error_status_t can only appear as a parameter or a return type. It cannot appear in arrays.

MIDL2200 : [allocate] illegal on a type deriving from a primitive/generic/context handle

By design, the ACF attribute allocate cannot be applied to handle types.

MIDL2201 : transmitted or presented type must not derive from error_status_t

In this release of Microsoft RPC, the type error_status_t cannot be used with the transmit_as attribute.

MIDL2202 : discriminant of a union must not derive from a field with [ignore] applied to it

A union used in a remote procedure call must be associated with another data item, called the discriminant, that selects the union arm. The discriminant must be transmitted. The ignore attribute cannot be applied to the union discriminant.

MIDL2203 : [nocode] must be specified with “/server none” in this mode

Some DCE IDL compilers generate an error when the nocode attribute is applied to a procedure in an interface for which server stub files are being generated. Because the server must support all operations, nocode must not be applied to a procedure in this mode or you must use the MIDL compiler switch /server none to explicitly specify that no server routines are to be generated.

MIDL2204 : no remote procedures specified, no client/server stubs will be generated

The provided interface does not have any remote procedures, so only header files will be generated.

MIDL2205 : too many default cases specified for encapsulated union

An encapsulated union may only have one default: arm.

MIDL2206 : union specification with no fields is illegal

Unions must have at least one field.

MIDL2207 : value out of range

The provided case value is out of the range of the switch type.

MIDL2208 : [context_handle] must be applied on a pointer type

Context handles must always be pointer types. DCE specifies that all context handles must be typed as “void *”.

MIDL2209 : return type must not derive from handle_t

Handle_t may not be returned.

MIDL2210 : [handle] must not be applied to a type deriving from a context handle

A type may not be both a context handle and a generic handle.

MIDL2211 : field deriving from an \”int\” must have size specifier \”small\”, \”short\”, or \”long\” with the \”int\”

The use of “int” is not remotable, since the size of “int” may be different accross machines.

MIDL2212 : field must not derive from a void or void *

Void and void * are not remotable types.

MIDL2213 : field must not derive from a struct containing bit-fields

bit fields in structs are not remotable.

MIDL2214 : field must not derive from a non-rpcable union

A union must be specified as a non-encapsulated union or encapsulated union in order to be remoted. Ordinary C unions lack the discriminant needed to remote the union.

MIDL2215 : field must not derive from a pointer to a function

Pointers to functions may not be remoted.

MIDL2216 : cannot use [fault_status] on both a parameter and a return type

[fault_status] may only be used once per procedure, although [comm_status] may be used independently.

MIDL2217 : return type too complicated for /Oi, using /Os

Large by-value return types may only be handled by /Os optimization stubs. The stubs for this routine will be generated using /Os optimization.

MIDL2218 : generic handle type too large for /Oi, using /Os

Large by-value generic handle types may only be handled by /Os optimization stubs. The stubs for this routine will be generated using /Os optimization.

MIDL2219 : [allocate(all_nodes)] on an [in,out] parameter may orphan the original memory

Use of [allocate(all_nodes)] on an [in,out] parameter must re-allocate contiguous memory for the [out] direction, thus orphaning the [in] parameter. This usage is not recommended.

MIDL2220 : cannot have a [ref] pointer as a union arm

Ref pointers must always point to valid memory, but an [in,out] union with a ref pointer may return a ref pointer when the [in] direction used another type.

MIDL2222 : use of [comm_status] or [fault_status] not supported for /Oi, using /Os

[comm_status] and [fault_status] may only be handled by /Os optimization stubs. The stubs for this routine will be generated using /Os optimization.

MIDL2223 : use of an unknown type for [represent_as] not supported for /Oi, using /Os

Use of a represent_as with a local type that is not defined in the idl file or an imported idl file may only be handled by /Os optimization stubs. The stubs for this routine will be generated using /Os optimization.

MIDL2224 : array types with [transmit_as] or [represent_as] not supported on return type for /Oi, using /Os

Returning an array with [transmit_as] or [represent_as] applied may only be handled by /Os optimization stubs. The stubs for this routine will be generated using /Os optimization.

MIDL2226 : [callback] requires /ms_ext

[callback] is a Microsoft extension and requires use of the /ms_ext switch.

MIDL2227 : circular interface dependency

This interface uses itself (directly or indirectly) as a base interface.

MIDL2228 : only IUnknown may be used as the root interface

Currently, all interfaces must have IUnknown as the root interface.

MIDL2229 : [IID_IS] may only be applied to pointers to interfaces

[iid_is] can only be applied to interface pointers, although they may be specified as IUnknown *.

MIDL2230 : interfaces may only be used in pointer-to-interface constructs

Interface names may not be used except as base interfaces or interface pointers.

MIDL2231 : interface pointers must have a UUID/IID

The base type of the iid_is expression must be a UUID/GUID/IID type.

MIDL2232 : definitions and declarations outside of interface body requires /ms_ext

Putting declarations and definitions outside of any interface body is a Microsoft extension and requires the use of the /ms_ext switch.

MIDL2233 : multiple interfaces in one file requires /ms_ext

Using multiple interfaces in a single idl file is a Microsoft extension and requires the use of the /ms_ext switch.

MIDL2234 : only one of [implicit_handle], [auto_handle], or [explicit_handle] allowed

Each interface may only have one of the above.

MIDL2235 : [implicit_handle] references a type which is not a handle

Implicit handles must be of one of the handle types.

MIDL2236 : [object] procs may only be used with “/env win32”

[object] interfaces may not be used with 16-bit environments.

MIDL2237 : [callback] with -env dos/win16 not supported for /Oi, using /Os

Callbacks in 16-bit environments may only be handled by /Os optimization stubs. The stubs for this routine will be generated using /Os optimization.

MIDL2238 : float/double not supported as top-level parameter for /Oi, using /Os

Float and double as parameters may only be handled by /Os optimization stubs. The stubs for this routine will be generated using /Os optimization. Float and double within structs/arrays/etc. May still be handled with /Oi.

MIDL2239 : pointers to context handles may not be used as return values

Context handles must be used as direct return values, not indirect return values.

MIDL2240 : procedures in an object interface must return an HRESULT

All non-[local] procedures in an object interface must return an HRESULT/SCODE.

MIDL2241 : duplicate UUID

UUIDs must be unique.

MIDL2242 : [object] interfaces must derive from other [object] interfaces

Interface inheritance is only allowed using object interfaces.

MIDL2243 : [IID_IS] expression must be a pointer to IID structure

The base type of the iid_is expression must be a UUID/GUID/IID type.

MIDL2244 : [call_as] type must be a [local] procedure

Tthe target of a call_as, if defined, must have [local] applied.

MIDL2245 : undefined [call_as] must not be used in an object interface [call_as]: in_list

Another routine defined in the ACf is attempting to use the same call_as routine as the previous routine.

MIDL2246 : [auto_handle] may not be used with [encode] or [decode]

[encode] and [decode] may only be used with explicit handles or implicit handles.

MIDL2247 : normal procs are not allowed in an interface with [encode] or [decode]

Interfaces containing [encode] or [decode] procedures may not also have remoted procedures.

MIDL2248 : top-level conformance or variance not allowed with [encode] or [decode]

Types that have top-level conformance or variance may not use type serialization, since there is no way to provide sizing/lengthing. Structs containing them are, however, allowed.

MIDL2249 : [out] parameters may not have \”const\”

Since an [out] parameter is altered, it may not have const.

MIDL2250 : return values may not have \”const\”

Since a function value is set, it must not have const.

MIDL2251 : multiple calling conventions illegal

Only one calling convention may be applied to a single procedure.

MIDL2252 : attribute illegal on [object] procedure

The above attribute only applies to procedures in interfaces that do not have [object].

MIDL2253 : [out] interface pointers must use double indirection

Since the altered value is the pointer to the interface, there must be another level of indirection above it to allow it to be returned.

MIDL2254 : procedure used twice as the caller in [call_as]

A given [local] procedure may only be used once as the target of a [call_as], in order to avoid name clashes.

MIDL2255 : [call_as] target must have [local] in an object interface

The target of a call_as must be a defined, [local] procedure in the current interface.

MIDL2256 : [code] and [nocode] may not be used together

These two attributes are contradictory, and may not be used together.

MIDL2257 : [maybe] procedures may not have a return value or [out] params

Since [maybe] procedures may never return, there is no way to get returned values.

MIDL2258 : pointer to function must be used

Although function type definitions are allowed in /c_ext mode, they may only be used as pointers to functions (and may never be remoted).

MIDL2259 : functions may not be passed in an RPC operation

Functions and function pointers may not be remoted.

MIDL2260 : hyper/double not supported as return value for /Oi, using /Os

Hyper and double return values may only be handled by /Os optimization stubs. The stubs for this routine will be generated using /Os optimization.

MIDL2261 : #pragma pack( pop ) without matching #pragma pack( push )

#pragma pack(push) and #pragma pack(pop) must appear in matching pairs. At least one too many #pragma pack(push)'s were specified.

MIDL2262 : stringable structure fields must be byte/char/wchar_t

[string] may only be applied to a struct whose fields are all of type byte, or a type definition equivalent of byte.

MIDL2263 : [notify] not supported for /Oi, using /Os

The [notify] attribute may only be processed by /Os optimization stubs.

MIDL2264 : handle parameter or return type is not supported on a procedure in an [object] interface

Handles may not be used with [object] interfaces.

MIDL2265 : ANSI C only allows the leftmost array bound to be unspecified

In an conformant array, ANSI C only allows the leftmost ( most significant ) array bound to be unspecified. If multiple dimensions are conformant, MIDL will attempt to put a “1” in the other conformant dimensions. If the other dimensions are defined in a different typedef, this may not be possible. Try putting all the array dimensions on the use of the array to avoid this. In any case, beware of the array indexing calculations done by the compiler; you may need to do your own calculations using the actual sizes.


Files Generated for an RPC Interface

The MIDL compiler generates the C-language stub and header files necessary to create the interface between the client application and the server application. The following topics describe each of the files generated for an RPC interface. For more information on defining and implementing an RPC interface see The Microsoft RPC Programmer’s Guide and Reference.


The Client Stub

The client stub module provides surrogate entry points on the client for each of the operations defined in the input IDL file.

When the client application makes a call to the remote procedure, its call first goes to the surrogate routine in the client stub file. The client stub routine performs the following functions:

•	Marshals arguments. The client stub packages input arguments into a form that can be transmitted to the server.

•	Calls the client run-time library to transmit arguments to the remote address space and invoke the remote procedure in the server address space.

•	Unmarshals output arguments. The client stub unpackages output arguments and returns to the caller.

The MIDL compiler switches /client, /cstub, and /out affect the client stub file.


The Server Stub

The server stub provides surrogate entry points on the server for each of the operations defined in the input IDL file.

When a server stub routine is invoked by the RPC run-time library, it performs the following functions:

•	Unmarshals input arguments (unpacks the arguments from their transmitted formats).

•	Calls the actual implementation of the procedure on the server.

•	Marshals output arguments (packages the arguments into the transmitted forms).

The MIDL compiler switches /env, /server, /sstub, and /out affect the server stub file.


The Header File

The header file contains definitions of all the data types and operations declared in the IDL file. The header file must be included by all application modules that call the defined operations, implement the defined operations, or manipulate the defined types.

The MIDL compiler switches /header and /out affect the header file.


Targetting Stubs for Specific 32-Bit Platforms

Some of the features of Microsoft RPC and the MIDL 3.0 compiler are platform-specific and are intended for implementation in distributed applications that run only on Windows NT 4.0 or a later version. Some features are supported in Windows NT 3.51 and Windows 95, as well as in later versions, but are not supported on older 32-bit, or 16-bit platforms.

As a safeguard, the MIDL 3.0 compiler generates macros that facilitate compatibility checking during the C compilation phase. If the interface uses features supported only on Windows NT 4.0, MIDL generates a TARGET_IS_NT40_OR_LATER macro. If supported features require Windows NT 3.51 or Windows95, a TARGET_IS_NT351_OR_WIN95_OR_LATER macro is generated. These macros, defined in rpcndr.h, depend on the environment variables WINVER and _WIN32_WINNT and are evaluated by the C/C++ compiler.

If, at compile time, you get an error message indicating that you need a specific platform to run this stub, first check to make sure you have not used a feature not available on this platform. For example, the pipe type constructor, the /Oif compiler option, and the user_marshal and wire_marshal attributes are only available on Windows NT 4.0. Stubs using these features will not run on earlier systems. The /Oic compiler switch is available on NT. 3.51 and Windows 95, but is not available in earlier versions.

Also, the technology needed to use OLE and OLE Automation data types (for example, BSTR or STGMEDIUM) in remote operations is present only on NT 4.0. Therefore, you cannot develop a custom interface that uses these data types in a remote procedure call to run on earlier platforms.

If you know that your target platform is correct for the features you are using, you need to explicitly set the environment variables in your makefile.

To build for Windows NT 3.51 or Windows 95

Add this line to your makefile:

CFLAGS = $(CFLAGS) -DWINVER=0x400

To build for Windows NT 4.0

Add this line to your makefile:

CFLAGS = $(CFLAGS) -D_WIN32_WINNT=0x400

Note that this target control is not in effect when you are building for MS-DOS, 16-bit Windows, or Macintosh platforms.

See Also

/Oi, pipe, wire_marshal, user_marshal, Marshaling OLE Data Types


Files Generated for an OLE Interface

The following topics describe each of the files generated for a custom OLE interface, which you identify by including the object attribute in the interface attribute list of the IDL file. For OLE interfaces, the MIDL compiler combines all client and object server routines into a single interface proxy file. This file includes the surrogate entry points for both clients and servers. In addition, the MIDL compiler generates an interface header file, a private header file, and an interface UUID file. You will use all these files when creating a proxy DLL that contains the code to support the use of the interface by both client applications and object servers. You will also use the interface header file and the interface UUID file when creating the executable file for a client application that uses the interface.

See Also

ACF, /app_config, IDL, Building a Proxy/Stub DLL


The Interface Proxy File

The interface proxy file (name_P.C) is a C file that contains routines equivalent to those in the client stub, server stub, and client and server files of an RPC interface. This file contains implementations of CProxyInterface and CStubInterface classes that are derived from the CProxy and CStub classes of the base interface. For example, an interface named ISomeInterface derived from the IUnknown interface is implemented in the CProxyISomeInterface and CStubISomeInterface classes derived from the CProxyIUnknown and CStubIUnknown classes.

The interface proxy file includes the following sections:

•	The implementation of a CProxyInterface class.

The virtual member functions of this class provide a client application’s surrogate entry points for each of the interface functions. These member functions marshal the input arguments into a transmittable form, transmit the marshalled arguments along with information that identifies the interface and the operation, and then unmarshal the return value and any output arguments when the transmitted operation returns.

•	The implementation of a CStubInterface class.

The virtual member functions of this class provide an object server’s surrogate entry points for each of the interface functions. These member functions unmarshal the input arguments, invoke the server’s implementation of the interface function, and then marshal and transmit the return value and any output arguments. A CStubInterface class also includes a member function that is invoked by the RPC run-time library when a client application calls one of the interface functions. This routine calls the surrogate routine specified by the RPC message.

•	Marshalling and unmarshalling support routines for complex data types.

Use the /proxy MIDL compiler switch to override the default name of the interface proxy file. The /env and /out switches affect this file.


The Header Files

The interface header file (name.H) contains type definitions and function declarations based on the interface definition in the IDL file. Include this file in the source files for the proxy DLL and for client applications that use the interface.

The /header MIDL compiler switch overrides the default name of the interface header file.


The Interface UUID File

The interface UUID file defines the constant IID_Interface and initializes it to the interface’s UUID specified in the IDL file. Client applications and the proxy DLL use this constant to identify the interface.

The /iid MIDL compiler switch overrides the default name of the interface UUID file.


Marshaling OLE Data Types

To make it easier to use certain OLE Automation data types and OLE handles in remote operations, wire_marshal typedefs for these data types, and their related helper functions, are available by importing Win32 IDL files and linking to the OLE and OLE AUTOMATION DLL files. These files are automatically installed on your system during installation of Microsoft® Windows NT® or Windows® 95.

•	To use the BSTR data type in remote procedure calls, import the wtypes.idl file into your interface definition (IDL) file and link to oleaut32.lib when building your distributed application. This will let your stubs use the ready-made helper functions BSTR_UserSize, BSTR_UserMarshal, BSTR_UserUnmarshal, and BSTR_UserFree.

•	To use other OLE Automation data types, such as VARIANT and SAFEARRAY, or types that use those types (for example, DISPPARAM and EXCEPINFO), import the objidl.idl file into your IDL file and link to the oleaut32.lib at build time. This will allow you to use the appropriate helper routines.

•	To use OLE data types and handles (such as CLIPFORMAT, SNB, STGMEDIUM, ASYNC_STGMEDIUM, HMETAFILE_PICT, HENHMETAFILE, HMETAFILE, HBITMAP, HPALETTE, and HGLOBAL), import the objidl.idl file into your interface definition file and link to the ole32.lib at build time.

•	The following OLE handles are also defined with the wire_marshal attribute, but only as handles within a machine since they cannot be used in remote procedure calls to other machines at this time: HWND, HMENU, HACCEL, HDC, HFONT, HICON, HBRUSH. Import the objidl.idl file into your IDL file and link to ole32.lib at build time to use these handles in interprocess communication on a single machine. The helper routines for these data types may change to include support for remote marshaling in a future release.

Note  The technology needed to support the above-described data types in proxy/stub code is part of Windows NT 4.0 only; this support is not present in Windows NT 3.51, Windows 95, or earlier versions of Windows. Therefore any application you develop on Windows NT 4.0, that uses these data types in remote procedure calls, will not run on an earlier platform. (The upcoming DCOM release for Windows 95 will include this support.) If your application needs to run on older platforms, and it uses these data types in remote procedure calls, you will need to create your own marshaling routines, using the transmit_as or represent_as attributes and their related helper functions. This restriction does not apply to type libraries generated with MIDL 3.0 for Automation/dual interfaces.

See Also

The wire_marshal Attribute, The type_UserSize Function, The type_UserMarshal Function, The type_UserUnmarshal Function, The type_UserFree Function, The transmit_as Attribute, The represent_as Attribute, Targetting Stubs for Specific 32-Bit Platforms


Generating a Type Library With MIDL

Microsoft’s Interface Definition Language (IDL) now includes the complete Object Definition Language (ODL) syntax. This allows you to use the 32-bit MIDL compiler instead of MKTYPLIB.EXE to generate a type library and optional header files for an OLE application.

Note  When the documentation refers to an ODL file, this means a file that MKTYPLIB can parse. When it refers to an IDL file, this means a file that MIDL parses. This is strictly a naming convention. The MIDL compiler will parse an input file regardless of its filename extension.

The top-level element of the ODL syntax is the library statement (library block). Every other ODL statement, with the exception of the attributes that are applied to the library statement, must be defined within the library block.When the MIDL compiler sees a library block it generates a type library in much the same way as MKTYPLIB does. With a few exceptions, described in Differences Between MIDL and MKTYPLIB, the statements within the library block should follow the same syntax as in the ODL language and MKTYPLIB.

You can apply ODL attributes to elements that are defined either inside or outside the library block. These attributes have no effect outside the library block unless the element they are applied to is referenced from within the library block. Statements inside the library block can reference an outside element either by using it as a base type, inheriting from it, or by referencing it on a line as shown:

<some IDL definitions including definitions for interface IFoo and struct bar>

[<some attributes>]

library a

{

interface IFoo;

struct bar;

...

};

If an element defined outside the library block is referenced within the library block, then its definition will be put into the generated type library.

The MIDL compiler treats the statements outside of a library block as a typical IDL file and parses those statements as it has always done. Normally, this means generating C-language stubs for an RPC application.

For more information about the general syntax for an ODL file see ODL File Syntax.


Additional Files Required To Generate a Type Library

In order to compile an IDL file that contains a library statement, the OLE and OLE AUTOMATION DLL files must be on your system. These files are automatically installed during installation of Microsoft® Windows NT™ or Windows® 95.

Effective with Windows NT 4.0, there is a new version of OLEAUT32.DLL that supports a richer format for 32-bit type libraries. MIDL looks for this DLL on the build machine; if the new version is present, MIDL generates a new-format type library, otherwise it generates an old-format type library.

Note for 16-bit developers

If your application must interoperate with 16-bit applications, you must use the old-format type library for compatibility. The MIDL command-line option /old overrides this default and directs the MIDL compiler to generate old-format type libraries even if the newer version of OLEAUT32.DLL is present.

Some of the base types that MKTYPLIB supports are not directly supported in MIDL. MIDL obtains definitions for these base types by automatically importing oaidl.idl whenever it sees a library statement. You need to ensure that this file is somewhere in your include path. The oaidl.idl file, and the files that it imports (objidl.idl, unkwn.idl, and wtypes.idl) are automatically installed when you install the Win32 SDK.

See Also

Marshaling OLE Data Types, /old, /new


Differences Between MIDL and MKTYPLIB

There are a few key areas in which the MIDL compiler differs from MKTYPLIB. Most of these differences arise because MIDL is oriented more toward C-syntax than MKTYPLIB.

In general, you will want to use the MIDL syntax in your IDL files. However, if you need to compile an existing ODL file, or otherwise maintain compatibility with MKTYPLIB, use the /mktyplib203 MIDL compiler option to force MIDL to behave like MKTYPLIB.EXE, version 2.03. (This is the last release of the MKTYPLIB tool.) Specifically, the /mktyplib203 option resolves these differences:

•	typedef syntax for complex data types

In MKTYPLIB, both of the following definitions generate a TKIND_RECORD for “bar” in the type library. The tag “foo” is optional and, if used, will not show up in the type library.

typedef struct foo { ... } bar;

typedef struct { ... } bar;

If an optional tag is missing, MIDL will generate it, effectively adding a tag to the definition supplied by the user. Since the first definition has a tag, MIDL will generate a TKIND_RECORD for "foo" and a TKIND_ALIAS for “bar” (defining “bar” as an alias for “foo”). Because the tag is missing in the second definition, MIDL will generate a TKIND_RECORD for a mangled name, internal to MIDL, that is not meaningful to the user and a TKIND_ALIAS for “bar”. This has potential implications for type library browsers that simply show the name of a record in their user interface. If you expect a TKIND_RECORD to have a real name, unrecognizable names could appear in the user interface.This behavior also applies to union and enum definitions, with the MIDL compiler generating TKIND_UNIONs and TKIND_ENUMs, respectively.

MIDL also allows C-style struct, union and enum definitions. For example, the following definition is legal in MIDL:

struct foo { ... };

typedef struct foo bar;

•	boolean data types

In MKTYPLIB, the boolean base type and the MKTYPLIB data type BOOL equate to VT_BOOL, which maps to VARIANT_BOOL, and which is defined as a short. In MIDL, the boolean base type is equivalent to VT_UI1, which is defined as an unsigned char, and the BOOL data type is defined as a long. This leads to difficulties if you mix IDL syntax and ODL syntax in the same file while still trying to maintain compatibility with MKTYPLIB. Because the data types are different sizes, the marshaling code will not match what is described in the type information. If you want a VT_BOOL in your type library, you should use the VARIANT_BOOL data type.

•	GUID definitions in header files

In MKTYPLIB, GUIDs are defined in the header file with a macro that can be conditionally compiled to generate either a GUID predefinition or an instantiated GUID. MIDL normally puts GUID predefinitions in its generated header files and GUID instantiations only in the file generated by the /iid switch.

The following differences in behavior can not be resolved by using the /mktyplib203 switch:

•	Scope of symbols in an enum declaration

In MKTYPLIB the scope of symbols in an enum is local. In MIDL, the scope of symbols in an enum is global, as it is in C. For example, the following code will compile in MKTYPLIB, but will generate a duplicate name error in MIDL:

typedef struct { ... } a;

enum {a=1, b=2, c=3};

•	Scope of public attribute

If you apply the public attribute to an interface block, MKTYPLIB treats every typdef inside that interface block as public. MIDL requires that you explicitly apply the public attribute to those typedefs that you want public.

•	Importlib search order

If you import more than one type library, and if these libraries contain duplicate references, MKTYPLIB resolves this by using the first reference that it finds. MIDL will use the last reference that it finds. For example, given the following ODL syntax, library C will use the FOO typedef from library A if you compile with MKTYPLIB, and the FOO typedef from library B if you compile with MIDL:

[...]library A

{

    typedef struct tagFOO

    {...}FOO

}

[...]library B

{

    typedef struct tagFOO

    {...} FOO

}

[...]library C

{

    importlib (A.TLB)

    importlib (B.TLB)

    typedef struct tagBAR

    {FOO y;}BAR

}

The appropriate workaround for this is to qualify each such reference with the correct import library name, like this:

typedef struct tagBAR

    {A.FOO y;}BAR

•	VOID data type not recognized

MIDL recognizes the C-language void data type and does not recognize the OLE Automation VOID data type. If you have an ODL file that uses VOID, place this definition at the top of the file:

#define VOID void

•	Exponential notation

MIDL requires that values expressed in exponential notation be contained within quotation marks. For example, “-2.5E+3”.

•	LCID values and constants

Normally MIDL does not consider the LCID when parsing files. To force this behavior for a value, or if you need to use locale-specific notation when defining a constant, enclose the value or constant in quotation marks.

See Also

/mktyplib203, /iid, Marshaling OLE Data Types


ODL Language Features in MIDL

The following topics list the Object Description Language (ODL) attributes, keywords, statements, and directives that are now part of the Microsoft Interface Definition Language (MIDL).

ODL Attributes

appobject	bindable
control	default
defaultvalue	displaybind
dllname	dual
entry	helpcontext
helpstring	helpfile
hidden	id
immediatebind	in
lcid	licensed
nonextensible	odl
oleautomation	optional
out
propget	propput
propputref	public
readonly	requestedit
restricted	retval
source	uuid
vararg	version
ODL Keywords, Statements, and Directives

coclass

dispinterface

enum

importlib

interface

library

module

struct

typedef

union

For information on how to marshal OLE Automation types, such as BSTR, VARIANT, and SAFEARRAY, see Marshaling OLE Data Types.


Generating a Proxy DLL and a Type Library From a Single IDL File

You can use a single IDL file to generate both the proxy stubs and header files for marshaling code, and a type library. You do this by defining an interface outside the library block and then referencing that interface from inside the library block, as shown in this example:

//file: AllKnown.idl

[object, uuid(. . .), <other interface attributes>]

interface IKnown : IUnknown {

import “unknwn.idl”

<declarations, etc. for IKnown interface go here>

};

[<library attributes>]library KnownLibrary {

//reference interface IKnown:

interface IKnown;

//or create a new class:

  [<coclass attributes>] coclass KnowMore {

   interface IKnown;

  };

};

See Also

Marshaling OLE Data Types, Additional Files Required To Generate a Type Library


MIDL Language Reference

This section provides a reference entry for each keyword in the Microsoft® Interface Definition Language (MIDL). Reference entries are also included for important language productions and concepts.

The reference entries are arranged in alphabetical order and each entry includes syntax, examples, descriptions, and cross-references. To examine the top-level structure of these files, start with the topics ACF and IDL.


ACF

[ interface-attribute-list ] interface interface-name
{
[ include filename-list ; ... ]
[ typedef [type-attribute-list] typename; ... ]

[	[ [function-attribute-list] ] function-name(
[ [ [parameter-attribute-list] ] parameter-name ]
...
);
]
...
}

interface-attribute-list

Specifies a list of one or more attributes that apply to the interface as a whole. Valid attributes include auto_handle, implicit_handle, explicit_handle, and optimize, code, or nocode. When two or more interface attributes are present, they must be separated by commas.

interface-name

Specifies the name of the interface. In DCE-compatibility mode, the interface name must match the name of the interface specified in the IDL file. When you use the MIDL compiler switch /acf, the interface name in the ACF and the interface name in the IDL file can be different.

filename-list

Specifies a list of one or more C-language header filenames, separated by commas. The full filename, including the extension, must be supplied.

type-attribute-list

Specifies a list of one or more attributes, separated by commas, that apply to the specified type. Valid type attributes include allocate or represent_as.

typename

Specifies a type defined in the IDL file. Type attributes in the ACF can only be applied to types previously defined in the IDL file.

function-attribute-list

Specifies a list of one or more attributes, separated by commas, that apply to the function-return type. Valid function attributes include allocate, optimize, call_as, code or nocode.

function-name

Specifies the name of the function in the IDL file.

parameter-attribute-list

Specifies a list of zero or more attributes, separated by commas, that apply to the specified parameter. Valid parameter attributes include byte_count.

parameter-name

Specifies the name of the parameter in the IDL file. Only the name of the parameter must match the IDL file specification. The sequence of parameters is not significant.

Examples

/* example 1 */

[auto_handle] interface foo1 { }

/* example 2 */

[implicit_handle(handle_t h), code] interface foo2 {}

/* example 3 */

[code]

interface foo3;

{

    include "foo3a.h", "foo3b.h";

    typedef [allocate(all_nodes)] TREETYPE1;

    typedef [allocate(all_nodes, dont_free)] TREETYPE2;

    f1([byte_count(length)] pBuffer);

}

Remarks

The application configuration file, or ACF, is one of two files that define the interface for your distributed application. The second interface-defining file is the IDL file. The IDL file contains type definitions and function prototypes that describe how data is transmitted on the network. The ACF configures your application for a particular operating environment without affecting its network characteristics.

By using the IDL and ACF files, you separate the interface specification from environment-specific settings. The IDL file is meant to be portable to any other computer. When you move your distributed application to another computer, you should be able to reuse the IDL file. Environment-specific changes are made in the ACF.

Many distributed applications require no special configuration. For such applications, use the MIDL compiler switch /app_config to supply the ACF keywords auto_handle and implicit_handle in the IDL file and omit the ACF.

The ACF corresponds to the IDL file in the following ways:

•	The interface name in the ACF must be the same as the interface name in the IDL file, unless you compile with the MIDL compiler switch /acf.

•	All type names and function names in the ACF must refer to types and functions defined in the IDL file.

•	Function parameters do not need to appear in the same sequence in the ACF as in the IDL file, but parameter names in the ACF must match names in the IDL file.

As with the IDL file, the ACF consists of a header portion and a body portion and, except in /osf mode, can contain multiple interfaces.

See Also

/app_config, auto_handle, code, explicit_handle, IDL, implicit_handle, include, midl, nocode, optimize, represent_as, typedef


allocate

typedef [allocate (allocate-option-list) [, type-attribute-list] ] type-name;

allocate-option-list

Specifies one or more memory-allocation options. Select one of either single_node or all_nodes, or one of either free or dont_free, or one from each group. When you specify more than one option, separate the options with commas.

type-attribute-list

Specifies other optional ACF type attributes. When you specify more than one type attribute, separate the options with commas.

type-name

Specifies a type defined in the IDL file.

Examples

/* ACF file */

typedef [allocate(all_nodes, dont_free)] PTYPE1;

typedef [allocate(all_nodes)] PTYPE2;

typedef [allocate(dont_free)] PTYPE3;

Remarks

The ACF type attribute allocate lets you customize memory allocation and deallocation for a type defined in the IDL file. These are the valid options:

Option	Description
all_nodes	Makes one call to allocate and free memory for all nodes.
single_node	Makes many individual calls to allocate and free each node of memory.
free	Frees memory on return from the server stub.
dont_free	Does not free memory on return from the server stub.
By default, the stubs may allocate storage for data referenced by a unique or full pointer by calling midl_user_allocate and midl_user_free individually for each pointer.

You can optimize the speed of your application by specifying the option all_nodes. This option directs the stub to compute the size of all memory referenced through the pointer of the specified type and to make a single call to midl_user_allocate. The stub releases the memory by making one call to midl_user_free.

The dont_free option directs the MIDL compiler to generate a server stub that does not call midl_user_free for the specified type. The dont_free option allows the pointer structures to remain accessible to the server application after the remote procedure call has completed and returned to the client.

Note that when applied to types used for in, out parameters, any parameter that is a pointer to a type qualified with the all_nodes option will cause a reallocation when the data is unmarshalled. It is the responsibility of the application to free the previously allocated memory corresponding to this parameter. For example:

typedef struct foo

{

[string] char * PFOO;

} * PFOO

void proc1 ( [in,out] PFOO * ppfoo);

The data type PFOO will be reallocated in the out direction by the stub before “unmarshalling.” Therefore, the previously allocated area must be freed by the application or a memory leak will occur.

See Also

ACF, midl_user_allocate, midl_user_free, typedef


appobject

[uuid(. . .), appobject [, coclass-attribute-list]]
coclass classname { [coclass definition]}

coclass-attribute-list

Specifies zero or more attributes that apply to the coclass statement. Allowable coclass attributes are helpstring, helpcontext, licensed, version, control, and hidden.

classname

Specifies the name by which the component object is known in the type library.

Example

[uuid(. . .),helpstring("Hello Class"),appobject] coclass Hello

    {[default]    interface IHello : IUnknown;

                  interface IDispatch;

    }

Remarks

The appobject attribute identifies the coclass as an application object, which is associated with a full EXE application, and indicates that the functions and properties of the coclass are globally available in this type library.

Flags

TYPEFLAG_FAPPOBJECT

See Also

ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, coclass, TYPEFLAGS


arrays

typedef [ [type-attr-list] ] type-specifier [pointer-decl] array-declarator;

typedef [ [type-attr-list] ] struct [ tag ] {
[ [ field-attribute-list ] ] type-specifier [pointer-decl] array-declarator;
...
}
typedef [ [type-attr-list] ] union [ tag ] {
[ case (limited-expression [ , ... ] ) ]
[ [ field_attribute-list ] ] type-specifier [pointer-decl] array-declarator;
[ [ default ]
[ [ field_attribute-list ] ] type-specifier [pointer-decl] array-declarator;
]

[ [function-attribute-list] ] type-specifier [pointer-decl] function-name(
[ [param-attr-list] ] type-specifier [pointer-decl] array-declarator
, ...
);

type-attr-list

Specifies zero or more attributes that apply to the type. Valid type attributes include handle, switch_type, transmit_as; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle, string, and ignore. Separate multiple attributes with commas.

type-specifier

Specifies the type identifier, base type, struct, union, or enum type. The type specification can include an optional storage specification.

pointer-decl

Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C, constructed from the * designator, modifiers such as far, and the qualifier const.

array-declarator

Specifies the name of the array, followed by one of the following constructs for each dimension of the array: “[ ]”, “[*]”, “[const1]”, or “[lower...upper]” where lower and upper are constant values that represent the lower and upper bounds. The constant lower must evaluate to zero.

tag

Specifies an optional tag for the structure or union.

field-attribute-list

Specifies zero or more field attributes that apply to the structure, union member, or function parameter. Valid field attributes include first_is, last_is, length_is, max_is, size_is; the usage attributes string, and ignore; the pointer attributes ref, unique, and ptr; and the union attribute switch_type. Separate multiple field attributes with commas. Note that of the attributes listed above, first_is, last_is, and ignore are not valid for unions.

limited-expression

Specifies a C-language expression. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators.

function-attribute-list

Specifies zero or more attributes that apply to the function. Valid function attributes are callback, local; the pointer attribute ref, unique, or ptr; and the usage attributes string, and context_handle.

function-name

Specifies the name of the remote procedure.

param-attr-list

Specifies the directional attributes and one or more optional field attributes that apply to the array parameter. Valid field attributes include max_is, size_is, length_is, first_is, and last_is.

Examples

/* IDL file interface body */

#define MAX_INDEX 10

typedef char  ATYPE[MAX_INDEX];

typedef short BTYPE[];        // Equivalent to [*];

typedef long  CTYPE[*][10];   // [][10]

typedef float DTYPE[0..10];   // Equivalent to [11]

typedef float ETYPE[0..(MAX_INDEX)];

typedef struct {

    unsigned short size;

    unsigned short length;

    [size_is(size), length_is(length)] char string[*];

} counted_string;

void MyFunction(

     [in, out] short * pSize,

     [in, out, string, size_is(*pSize)] char a[0..*]

);

Remarks

Array declarators appear in the interface body of the IDL file as part of a general declaration, as a member of a structure or union declarator, or as a parameter to a remote procedure call.

The bounds of each dimension of the array are expressed inside a separate pair of square brackets. An expression that evaluates to n signifies a lower bound of zero and an upper bound of n − 1. If the square brackets are empty or contain a single asterisk (*), the lower bound is zero and the upper bound is determined at run time.

The array can also contain two values separated by an ellipsis that represent the lower and upper bounds of the array, as in [lower...upper]. Microsoft RPC requires a lower bound of zero. The MIDL compiler does not recognize constructs that specify nonzero lower bounds.

Arrays can be associated with the field attributes size_is, max_is, length_is, first_is, and last_is to specify the size of the array or the part of the array that contains valid data. These field attributes identify the parameter, structure field, or constant that specifies the array dimension or index.

The array must be associated with the identifier specified by the field attribute in this way: When the array is a parameter, the identifier must also be a parameter to the same function; when the array is a structure field, the identifier must be another structure field of that same structure.

An array is called “conformant” if the upper bound of any dimension is determined at run time, and only upper bounds can be determined at run time. To determine the upper bound, the array declaration must include a size_is or max_is attribute.

An array is called “varying” when its bounds are determined at compile time, but the range of transmitted elements is determined at run time. To determine the range of transmitted elements, the array declaration must include a length_is, first_is, or last_is attribute.

A conformant varying array (also called “open”) is an array whose upper bound and range of transmitted elements are determined at run time. At most, one conformant or conformant varying array can be nested in a C structure and must be the last element of the structure. Nonconformant varying arrays can occur anywhere in a structure.

Multidimensional Arrays

The user can declare types that are arrays and then declare arrays of objects of such types. The semantics of m-dimensional arrays of n-dimensional array types are the same as the semantics of m+n-dimensional arrays.

For example, the type RECT_TYPE can be defined as a two-dimensional array and the variable rect can be defined as an array of RECT_TYPE. This is equivalent to the three-dimensional array equivalent_rect:

typedef short int RECT_TYPE[10][20];

RECT_TYPE rect[15];

short int equivalent_rect[15][10][20];  // ~RECT_TYPE rect[15]

Microsoft RPC is C-oriented. Following C-language conventions, only the first dimension of a multidimensional array can be determined at run time. Interoperation with DCE IDL arrays that support other languages is limited to:

•	Multidimensional arrays with constant (compile-time-determined) bounds.

•	Multidimensional arrays with all constant bounds except the first dimension. The upper bound and range of transmitted elements of the first dimension are dependent on run time.

•	Any one-dimensional arrays with a lower bound of zero.

When the string attribute is used on multidimensional arrays, the attribute applies to the rightmost array.

Arrays of Pointers

Reference pointers must point to valid data. The client application must allocate all memory for an in or in, out array of reference pointers, especially when the array is associated with in, or in, out length_is, or last_is values. The client application must also initialize all array elements before the call. Before returning to the client, the server application must verify that all array elements in the transmitted range point to valid storage.

On the server side, the stub allocates storage for all array elements, regardless of the length_is or last_is value at the time of the call. This feature can affect the performance of your application.

No restrictions are placed on arrays of unique pointers. On both the client and the server, storage is allocated for null pointers. When pointers are non-null, data is placed in preallocated storage.

An optional pointer declarator can precede the array declarator.

When embedded reference pointers are out-only parameters, the server-manager code must assign valid values to the array of reference pointers. For example:

typedef [ref] short * ARefPointer;

typedef ARefPointer ArrayOfRef[10];

void proc1( [out] ArrayOfRef Parameter );

The generated stubs allocate the array and assign NULL values to all pointers embedded in the array.

See Also

first_is, IDL, last_is, length_is, max_is, ptr, ref, size_is, string, unique


auto_handle

[ auto_handle [, interface-attribute-list] ] interface interface-name

interface-attribute-list

Specifies zero or more attributes that apply to the interface as a whole, such as code or nocode. Separate interface attributes with commas.

interface-name

Specifies the name of the interface.

Examples

[auto_handle] interface MyInterface { }

[auto_handle, code] interface MyInterface { }

Remarks

The ACF attribute auto_handle directs the stub to automatically establish the binding for a function that does not have an explicit binding-handle parameter.

The auto_handle attribute appears in the interface header of the ACF. It also appears in the interface header of the IDL file when you specify the MIDL compiler switch /app_config.

When the client calls a function that uses automatic binding, and no binding to a server exists, the stub automatically establishes the binding. The binding is reused for subsequent calls to other functions in the interface that use automatic binding. The client application program does not have to declare or perform any processing relating to the binding handle.

When the ACF is not present or does not include the implicit_handle attribute, the MIDL compiler uses auto_handle and issues an informational message. The MIDL compiler also uses auto_handle, if needed, to establish the initial binding for a context_handle.

The auto_handle attribute can occur only if the implicit_handle or explicit_handle attribute does not occur. The auto_handle attribute can occur in the ACF or IDL interface header at most once.

Note  You cannot use automatic binding (either with the auto_handle attribute, or by default) if you are processing data through pipes.

See Also

ACF, /app_config, context_handle, IDL, implicit_handle


base_types

Remarks

All data transmitted on the network during a remote procedure call must resolve to a base type or predefined type.

MIDL supports the following base types: int, boolean, byte, char, double, float, handle_t, hyper, long, short, small, and void *. The keywords signed and unsigned can be used to qualify integer and character types. MIDL also provides the predefined types error_status_t and wchar_t.

Base types can appear as type specifiers in const declarations, typedef declarations, general declarations, and as parameter type specifiers in function declarators.

The base and predefined types have the following default signs and sizes:

Base type	Default sign	Description
boolean	unsigned	8-bit data item
byte	- (not applicable)	8-bit data item
char	unsigned	8-bit unsigned data item
double	-	64-bit floating-point number
float	-	32-bit floating-point number
handle_t	-	Primitive handle type
hyper	signed	64-bit signed integer
int	signed	32-bit signed integer
long	signed	32-bit signed integer
short	signed	16-bit signed integer
small	signed	8-bit signed integer
void *	-	32-bit context handle pointer type
wchar_t	unsigned	16-bit unsigned data item
Any other types in the interface must be derived from these base or predefined types. The following restrictions apply to data types in interfaces:

•	On 16-bit platforms, the type int cannot appear in remote functions without a size qualifier such as short, small, long or hyper.

•	The type void * cannot appear in remote functions except when it is used to define a context handle.

•	DCE IDL compilers do not recognize the keyword signed. Therefore, this feature is not available when you use the MIDL compiler /osf switch.

See Also

byte, char, handle_t, long, /osf, short, small, wchar_t


bindable

[interface-attribute-list] interface | dispinterface interface-name
{
[bindable[, attribute-list]] returntype function-name(params)
}

attribute-list

Specifies zero or more attributes that apply to the function prototype for a property or a method in an interface or dispinterface. The following attributes are accepted: helpstring, helpcontext, string, defaultbind, displaybind, immediatebind, propget, propput, propputref, and vararg. If vararg is specified, the last parameter must be a safe array of VARIANT type. Separate multiple attributes with commas.

Example

[uuid(. . .)]dispinterface MyObject

{

properties:

methods:

 [id(1), propget, bindable, defaultbind, displaybind]

        long x();

 [id(1), propput, bindable, defaultbind, displaybind]

        void x(long rhs);

}

Remarks

The bindable attribute indicates that the property supports data binding. This allows the client to be notified whenever a property has changed value. (If you want the client to be notified of impending changes to a property, use the requestedit attribute.)

Because the bindable attribute refers to the property as a whole, it must be specified wherever the property is defined. Therefore, you need to specify the attribute on both the property-accessing function and the property-setting function.

Flags

FUNCFLAG_FBINDABLE, VARFLAG_FBINDABLE

See Also

defaultbind, displaybind, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, TYPEFLAGS, dispinterface


boolean

Remarks

The keyword boolean indicates that the expression or constant expression associated with the identifier takes the value TRUE or FALSE.

The boolean type is one of the base types of the IDL language. The boolean type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function-return-type specifier and as a parameter-type specifier). For the context in which type specifiers appear, see IDL.

See Also

base_types, IDL


broadcast

[[ [ IDL-operation-attributes ] ]] operation-attribute , ...

IDL-operation-attributes

Specifies zero or more IDL operation attributes, such as broadcast and idempotent. Operation attributes are enclosed in square brackets.

Remarks

The keyword broadcast specifies that remote procedure calls be sent to all servers on a local network. Rather than being delivered to one particular server, the routine is always broadcasted to all the servers on the network. The client receives output from the first reply to return successfully, while subsequent replies are discarded.

The broadcast attribute specifies that the routine can be called multiple times and at the same time be sent to multiple servers as the result of one RPC. This is different from the idempotent attribute, which specifies that a call can be retried if it is not completed. However, an operation with the broadcast attribute is implicitly an idempotent operation. It ensures that the data for an RPC is received and processed zero or more times.

The broadcast attribute is supported only by connectionless protocols (datagrams). If a remote procedure broadcasts its call to all hosts on a local network, it must use the datagram protocol sequence ncadg_ip_udp. Note that the size of a broadcast packet is determined by the datagram service in use.

See Also

idempotent, IDL, maybe, non-idempotent


byte

Remarks

The byte keyword specifies an 8-bit data item.

A byte data item does not undergo any conversion for transmission on the network as a char type can.

The byte type is one of the base types of the interface definition language (IDL). The byte type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function-return-type specifier and as a parameter-type specifier). For the context in which type specifiers appear, see IDL.

See Also

base_types, char


byte_count

[ function-attribute-list ] function-name(
[byte_count(length-variable-name)] pointer-parameter-name);
...
);

function-attribute-list

Specifies zero or more ACF function attributes.

function-name

Specifies the name of the function defined in the IDL file. The function name is required.

length-variable-name

Specifies the name of the in-only parameter that specifies the size, in bytes, of the memory area referenced by pointer-parameter-name.

pointer-parameter-name

Specifies the name of the out-only pointer parameter defined in the IDL file.

Examples

/* IDL file */

void proc1([in] unsigned long length, [out] struct foo * pFoo);

/* ACF file */

proc1([byte_count(length)] pFoo);

Remarks

Note  The ACF attribute byte_count represents a Microsoft extension to DCE IDL. Therefore, this attribute is not available when you use the MIDL compiler switch /osf.

The byte_count attribute is a parameter attribute that associates a size, in bytes, with the memory area indicated by the pointer.

Memory referenced by the pointer parameter is contiguous and is not allocated or freed by the client stubs. This feature of the byte_count attribute lets you create a persistent buffer area in client memory that can be reused during more than one call to the remote procedure.

The ability to turn off the client stub memory allocation lets you tune the application for efficiency. For example, the byte_count attribute can be used by service-provider functions that use Microsoft RPC. When a user application calls the service-provider API and provides a pointer to a buffer, the service provider can pass the buffer pointer on to the remote function and reuse the buffer during multiple remote calls without forcing the user to reallocate the memory area.

The memory area can contain complex data structures that consist of multiple pointers. Because the memory area is contiguous, the application does not have to make many calls to individually free each pointer and structure. The memory area can be allocated or freed with one call to the memory allocation or free routine.

The buffer must be an out-only parameter, while the buffer length in bytes must be an in-only parameter.

Note  Specify a buffer that is large enough to contain all the out parameters. Pointers are unmarshalled on a 4-byte aligned boundary. Therefore, the alignment padding the stubs will perform must be accounted for in the space for the buffer. In addition, packing levels used during C-language compilation can vary. Use a byte count value that accounts for additional packing bytes added for the packing level used during C-language compilation.

See Also

ACF, in, length_is, out, size_is


call_as

[call_as (local-proc), [ , operation-attribute-list ] ] operation-name ;

local-proc

Specifies an operation-defined routine.

operation-attribute-list

Specifies one or more attributes that apply to the operation. Separate multiple attributes with commas.

operation-name

Specifies the named operation presented to the application.

Remarks

The call_as attribute enables a nonremotable function to be mapped to a remote function. This is particularly helpful in interfaces that have numerous nonremotable types as parameters. Rather than using many represent_as and transmit_as types, you can combine all the conversions using call_as routines. You supply the two call_as routines (client side and server side) to bind the routine between the application calls and the remote calls. The call_as attribute can be used for object interfaces, where the interface definition can be used for local calls as well as remote calls because it allows a nonremotable interface to be remoted transparently. The call_as attribute cannot be used with /osf mode.

For example, assume that the routine f1 in object interface IFace requires numerous conversions between the user calls and what is actually transmitted. The following examples describe the IDL and ACF files for interface IFace:

In the IDL file for interface IFace:

[local] HRESULT f1 ( <users parameter list> )

[call_as( f1 )] long Remf1 ( <remotable parameter list> );

In the ACF for interface IFace:

[call_as( f1 )] Remf1();

This would cause the generated header file to define the interface using the definition of f1, yet it would also provide stubs for Remf1:

Generated Vtable in the header file for interface IFace:

struct IFace_vtable

        {

        ..

        HRESULT ( * f1) ( <users parameter list>);

        ..

        };

The client-side proxy would then have a typical MIDL-generated proxy for Remf1, while the server side stub for Remf1 would be the same as the typical MIDL-generated stub:

void IFace_Remf1_Stub ( . . .)

    {

    ..

    invoke IFace_f1_Stub ( <remotable parameter list> )    /* instead

            of IFace_f1 */

    ..

    }

Then, the two call_as bond routines (client side and server side) must be manually coded:

HRESULT f1_Proxy ( <users parameter list> )

    {

    ..

    Remf1_Proxy ( <remotable parameter list> );

    ..

    }

long IFace_f1_Stub ( <remotable parameter list> )

    {

    ..

    IFace_f1 ( <users parameter list> );

    ..

    }

For object interfaces, these are the prototypes for the bond routines.

For client side:

<local_return_type>  <interface>_<local_routine>_proxy

( <local_parameter_list> );

For server side:

<remote_return_type>  <interface>_<local_routine>_stub

( <remote_parameter_list> );

For nonobject interfaces, these are the prototypes for the bond routines.

For client side:

<local_return_type>  <local_routine> ( <local_parameter_list> );

For server side:

<local_return_type>  <interface>_v<maj>_<min>_<local_routine>

( <remote_parameter_list> );

See Also

represent_as, transmit_as


callback

[callback [ , function-attr-list] ] type-specifier [ptr-declarator] function-name(
[ [parameter-attribute-list] ] type-specifier [declarator]
, ...
);

function-attr-list

Specifies zero or more attributes that apply to the function. Valid function attributes are local; the pointer attribute ref, unique, or ptr; and the usage attributes string, ignore, and context_handle. Separate multiple attributes with commas.

type-specifier

Specifies a base_type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.

ptr-declarator

Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.

function-name

Specifies the name of the remote procedure.

parameter-attribute-list

Specifies zero or more directional attributes, field attributes, usage attributes, and pointer attributes appropriate for the specified parameter type. Separate multiple attributes with commas.

declarator

Specifies a standard C declarator such as identifiers, pointer declarators, and array declarators. For more information, see pointers and arrays. The parameter-name identifier is optional.

Example

[callback] void DisplayString([in, string] char * p1);

Remarks

The callback attribute declares a static callback function that exists on the client side of the distributed application. Callback functions provide a way for the server to execute code on the client.

The callback function is useful when the server must obtain information from the client. If server applications were supported on Windows 3.x, the server could make a call to a remote procedure on the Windows 3.x server to obtain the needed information. The callback function accomplishes the same purpose and lets the server query the client for information in the context of the original call.

Callbacks are special cases of remote calls that execute as part of a single thread. A callback is issued in the context of a remote call. Any remote procedure defined as part of the same interface as the static callback function can call the callback function.

Only the connection-oriented and local protocol sequences support the callback attribute. If an RPC interface uses a connectionless (datagram) protocol sequence, calls to procedures with the callback attribute will fail.

Handles cannot be used as parameters in callback functions. Because callbacks always execute in the context of a call, the binding handle used by the client to make the call to the server is also used as the binding handle from the server to the client.

Callbacks can nest to any depth.

See Also

IDL, /osf


char

Remarks

The keyword char identifies a data item that has 8 bits. To the MIDL compiler, a char is unsigned by default and is synonymous with unsigned char.

In this version of Microsoft RPC, the character translation tables that convert between ASCII and EBCDIC are built into the run-time libraries and cannot be changed by the user.

The char type is one of the base types of the interface definition language (IDL). The char type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function-return-type specifier and a parameter-type specifier). For the context in which type specifiers appear, see IDL.

DCE IDL compilers do not accept the keyword signed applied to char types. Therefore, this feature is not available when you use the MIDL compiler /osf switch.

See Also

base_types, byte, /char, /osf, signed, string, wchar_t


coclass

[attribute-list]coclass classname {[attributes2] [interface | dispinterface] interfacename {. . . };

attribute-list

The uuid attribute is required on a coclass. This is the same uuid that is registered as a CLSID in the system registration database. The helpstring, helpcontext, licensed, version, control, hidden, and appobject attributes are accepted, but not required, before a coclass definition.

classname

Name by which the common object is known in the type library.

attributes2

Optional attributes for the interface or dispinterface. The source, default, and restricted attributes are accepted on an interface or dispinterface within a coclass.

interfacename

Either an interface declared with the interface keyword, or a dispinterface declared with the dispinterface keyword.

Examples

[uuid(. . .), version(1.0), helpstring("A class"), helpcontext(2481), appobject] coclass myapp

{

    [source] interface IMydocfuncs : IUnknown;

    dispinterface DMydocfuncs;

};

[uuid(. . .)]

coclass foo

{

    [restricted] interface bar;

    interface baz;

}

Remarks

The coclass statement provides a listing of the supported interfaces for a component object.

The Microsoft® Component Object Model defines a class as an implementation that allows QueryInterface between a set of interfaces.

See Also

ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, TYPEFLAGS


code

[ code [ , ACF-interface-attributes ] ] interface interface-name
{
[ include filename-list ; ] ...
[ typedef [type-attribute-list] typename; ] ...

[ [ code [ , ACF-function-attributes ] ] function-name (
[ ACF-parameter-attributes ] parameter-name ;
...
);
]
...
}

ACF-interface-attributes

Specifies a list of one or more attributes that apply to the interface as a whole. Valid attributes include either auto_handle or implicit_handle and either code, nocode, or optimize. When two or more interface attributes are present, they must be separated by commas.

interface-name

Specifies the name of the interface. In DCE-compatibility mode, the interface name must match the name of the interface specified in the IDL file. When you use the MIDL compiler switch /acf, the interface name in the ACF and the interface name in the IDL file can be different.

filename-list

Specifies a list of one or more C-header filenames, separated by commas. You must supply the full filename, including the extension.

type-attribute-list

Specifies a list of one or more attributes, separated by commas, that apply to the specified type. Valid type attributes include allocate and represent_as.

typename

Specifies a type defined in the IDL file. Type attributes in the ACF can only be applied to types previously defined in the IDL file.

ACF-function-attributes

Specifies zero or more attributes that apply to the function as a whole, such as comm_status. Function attributes are enclosed in square brackets. Separate multiple function attributes with commas.

function-name

Specifies the name of the function as defined in the IDL file.

ACF-parameter-attributes

Specifies ACF attributes that apply to a parameter. Note that zero, one, or more attributes can be applied to the parameter. Separate multiple parameter attributes with commas. ACF parameter attributes are enclosed in square brackets.

parameter-name

Specifies a parameter of the function as defined in the IDL file. Each parameter for the function must be specified in the same sequence and using the same name as defined in the IDL file.

Remarks

The code attribute can appear in the ACF header or be applied to an individual function.

When the code attribute appears in the ACF header, client stub code is generated for all remote functions that do not have the nocode function attribute. You can override the code attribute in the header for an individual function by specifying the nocode attribute as a function attribute.

When the code attribute appears in the remote function’s attribute list, client stub code is generated for the function. Client stub code is not generated when:

•	The ACF header includes the nocode attribute.

•	The nocode attribute is applied to the function.

•	The local attribute applies to the function in the interface file.

Either code or nocode can appear in the interface or function attribute list, but the one you choose can appear only once in the list.

See Also

ACF, nocode


comm_status

[comm_status [ , ACF-function-attributes ] ] function-name(
[ [ ACF-parameter-attributes ] ] parameter-name
, ...
);

[ [ ACF-function-attributes ] ] function-name(
[comm_status [ , ACF-parameter-attributes ] ] parameter-name
... );

ACF-function-attributes

Specifies zero or more ACF function attributes, such as comm_status and nocode. Function attributes are enclosed in square brackets. Note that zero, one, or more attributes can be applied to a function. Separate multiple function attributes with commas. Note that if comm_status appears as a function attribute, it cannot also appear as a parameter attribute.

function-name

Specifies the name of the function as defined in the IDL file.

ACF-parameter-attributes

Specifies attributes that apply to a parameter. Note that zero, one, or more attributes can be applied to the parameter. Separate multiple parameter attributes with commas. Parameter attributes are enclosed in square brackets. IDL parameter attributes, such as directional attributes, are not allowed in the ACF. Note that if comm_status appears as a parameter attribute, it cannot also appear as a function attribute.

parameter-name

Specifies the parameter for the function as defined in the IDL file. Each parameter for the function must be specified in the same sequence, using the same name as defined in the IDL file.

Remarks

The comm_status attribute can be used as either a function attribute or as a parameter attribute, but it can appear only once per function. It can be applied either to the function or to one parameter in each function.

The comm_status attribute can only be applied to functions that return the type error_status_t. When a communication error occurs during the execution of the function, an error code is returned.

When comm_status is used as a parameter attribute, the parameter must be defined in the IDL file and must be an out parameter of type error_status_t. When a communication error occurs during the execution of the function, the parameter is set to the error code. When the remote call is completed successfully, the procedure sets the value.

It is possible for both the comm_status and fault_status attributes to appear in a single function, either as function attributes or parameter attributes. If both attributes are function attributes or if they apply to the same parameter and no error occurs, the function or parameter has the value error_status_ok. Otherwise, it contains the appropriate comm_status or fault_status value. Because values returned for comm_status are different from the values returned for fault_status, the returned values are readily interpreted.

See Also

ACF, error_status_t, fault_status


const

const const-type identifier = const-expression ;

/* IDL file typedef syntax */
[ typedef [ , type-attribute-list ] ] const const-type declarator-list;
[ typedef [ , type-attribute-list ] ] pointer-type const declarator-list;

[ [ function-attr-list ] ] type-specifier [ ptr-decl ] function-name(
[ [ parameter-attribute-list ] ] const const-type [declarator],
[ [ parameter-attribute-list ] ] pointer-type const [declarator]
, ...
);

const-type

Specifies a valid MIDL integer, character, string, or boolean type. Valid MIDL types include small, short, long, char, char *, wchar_t, wchar_t *, byte, byte *, and void *. The integer and character types can be signed or unsigned.

identifier

Specifies a valid MIDL identifier. Valid MIDL identifiers consist of up to 31 alphanumeric and/or underscore characters and must start with an alphabetic or underscore character.

const-expression

Specifies an expression, identifier, or numeric or character constant appropriate for the specified type: constant integer literals or constant integer expressions for integer constants; boolean expressions that can be computed at compilation for boolean types; single-character constants for character types; and string constants for string types. The void * type can be initialized only to NULL.

type-attribute-list

Specifies one or more attributes that apply to the type.

pointer-type

Specifies a valid MIDL pointer type.

declarator and declarator-list

Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see pointers and arrays. The declarator-list consists of one or more declarators, separated by commas. The parameter-name identifier in the function declarator is optional.

function-attr-list

Specifies zero or more attributes that apply to the function. Valid function attributes are callback, local; the pointer attribute ref, unique, or ptr; and the usage attributes string, ignore, and context_handle.

type-specifier

Specifies a base_type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.

ptr-decl

Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C. It is constructed from the * designator, modifiers such as far, and the qualifier const.

function-name

Specifies the name of the remote procedure.

parameter-attribute-list

Specifies zero or more directional attributes, field attributes, usage attributes, and pointer attributes appropriate for the specified parameter type. Separate multiple attributes with commas.

Examples

const void *  p1        = NULL;

const char    my_char1  = 'a';

const char    my_char2  = my_char1;

const wchar_t my_wchar3 = L'a';

const wchar_t * pszNote = L"Note";

const unsigned short int x = 123;

typedef [string] const char *LPCSTR;

HRESULT GetName([out] wchar_t * const pszName );

Remarks

MIDL allows you to declare constant integer, character, string, and boolean types in the interface body of the IDL file. You can use the const keyword to modify the type of a type declaration or the type of a function parameter. Const type declarations are reproduced in the generated header file as #define directives.

DCE IDL compilers do not support constant expressions. Therefore this feature is not available when you use the MIDL compiler /osf switch.

A previously defined constant can be used as the assigned value of a subsequent constant. The value of a constant integral expression is automatically converted to the respective integer type in accordance with C conversion rules.

The value of a character constant must be a single-quoted ASCII character. When the character constant is the single-quote character itself ('), the backslash character (\) must precede the single-quote character, as in \'.

The value of a character-string constant (char *) must be a double-quoted string. Within a string, the backslash (\) character must precede a literal double-quote character ( “ ), as in \”. Within a string, the backslash character (\) represents an escape character. String constants can consist of up to 255 characters.

The value NULL is the only valid value for constants of type void *. Any attributes associated with the const declaration are ignored.

The MIDL compiler does not check for range errors in const initialization. For example, when you specify “const short x = 0xFFFFFFFF;” the MIDL compiler does not report an error and the initializer is reproduced in the generated header file.

See Also

base_types, IDL, /osf


context_handle

typedef [context_handle [ , type-attribute-list ] ] type-specifier declarator-list;

[context_handle [, function-attr-list ] ] type-specifier [ptr-decl] function-name(
[ [parameter-attribute-list] ] type-specifier [declarator]
, ...
);

[ [ function-attr-list ] ] type-specifier [ ptr-decl ] function-name(
[context_handle [ , parameter-attribute-list ] ] type-specifier [declarator]
, ...
);

[ void __RPC_USER context-handle-type_rundown (context-handle-type); ]

type-attribute-list

Specifies one or more attributes that apply to the type.

type-specifier

Specifies a pointer type or a type identifier. An optional storage specification can precede type-specifier.

declarator and declarator-list

Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. The declarator for a context handle must include at least one pointer declarator. For more information, see pointers and arrays. The declarator-list consists of one or more declarators, separated by commas. The parameter-name identifier in the function declarator is optional.

function-attr-list

Specifies zero or more attributes that apply to the function. Valid function attributes are callback, local; the pointer attribute ref, unique, or ptr; and the usage attributes string, ignore, and context_handle.

ptr-decl

Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.

function-name

Specifies the name of the remote procedure.

parameter-attribute-list

Specifies zero or more directional attributes, field attributes, usage attributes, and pointer attributes appropriate for the specified parameter type. Separate multiple attributes with commas.

context-handle-type

Specifies the identifier that specifies the context handle type as defined in a typedef declaration that takes the context_handle attribute. The rundown routine is optional.

Example

typedef [context_handle] void * PCONTEXT_HANDLE_TYPE;

short RemoteFunc1([out] PCONTEXT_HANDLE_TYPE * pCxHandle);

short RemoteFunc2([in, out] PCONTEXT_HANDLE_TYPE * pCxHandle);

void __RPC_USER PCONTEXT_HANDLE_TYPE_rundown (PCONTEXT_HANDLE_TYPE);

Remarks

The context_handle attribute identifies a binding handle that maintains context, or state information, on the server between remote procedure calls. The attribute can appear as an IDL typedef type attribute, as a function return type attribute, or as a parameter attribute.

When you use the MIDL 3.0 compiler in default mode, a context handle can be any pointer type selected by the user, as long as it complies with the requirements for context handles described following. The data associated with such a context handle type is not transmitted on the network and should only be manipulated by the server application. DCE IDL compilers restrict context handles to pointers of type void *. Therefore this feature is not available when you use the MIDL compiler /osf switch.

As with other handle types, the context handle is opaque to the client application and any data associated with it is not transmitted. On the server, the context handle serves as a handle on active context and all data associated with the context handle type is accessible.

To create a context handle, the client passes to the server an out, ref pointer to a context handle. (The context handle itself can have a null or non-null value, as long as its value is consistent with its pointer attributes. For example, when the context handle type has the ref attribute applied to it, it cannot have a null value.) Another binding handle must be supplied to accomplish the binding until the context handle is created. When no explicit handle is specified, implicit binding is used. When no implicit_handle attribute is present, an auto handle is used.

The remote procedure on the server creates an active context handle. The client must use that context handle as an in or in, out parameter in subsequent calls. An in-only context handle can be used as a binding handle, so it must have a non-null value. An in-only context handle does not reflect state changes on the server.

On the server, the called procedure can interpret the context handle as needed. For example, the called procedure can allocate heap storage and use the context handle as a pointer to this storage.

To close a context handle, the client passes the context handle as an in, out argument. The server must return a null context handle when it is no longer maintaining context on behalf of the caller. For example, if the context handle represents an open file and the call closes the file, the server must set the context handle to NULL and return it to the client. A null value is invalid as a binding handle on subsequent calls.

A context handle is only valid for one server. When a function has two handle parameters and the context handle is not null, the binding handles must refer to the same address space.

When a function has an in or an in, out context handle, its context handle can be used as the binding handle. In this case, implicit binding is not used and the implicit_handle or auto_handle attribute is ignored.

The following restrictions apply to context handles:

•	Context handles cannot be array elements, structure members, or union members. They can only be parameters.

•	Context handles cannot have the transmit_as or represent_as attribute.

•	Parameters that are pointers to out context handles must be ref pointers.

•	An in context handle can be used as the binding handle and cannot be null.

•	An in, out context handle can be null on input, but only if the procedure has another explicit handle parameter.

•	A context handle cannot be used with callbacks.

See Also

auto_handle, handle, handles, Context Handles, Server Context Rundown Routine, Client Context Reset


control

[uuid, control [, attribute-list]] library | coclass lib-or-coclassname
{ definitions }

attribute-list

Specifies zero or more attributes that apply to the library or coclass statement. Separate multiple attributes with commas.

Example

[uuid(. . .),helpstring("Hello 2.1 OLE Control Library"),

   control,version(2.1)]

library Hello

{ /* library definitions */}

Remarks

The control attribute identifies a coclass or library as an OLE control, from which a container site will derive additional type libraries or component object classes. This attribute allows you to mark type libraries that describe controls so they will not be displayed in type browsers intended for nonvisual objects.

Flags

TYPEFLAG_FCONTROL, LIBFLAG_FCONTROL

See Also

ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, TYPEFLAGS, coclass, library


cpp_quote

cpp_quote(“string”)

string

Specifies a quoted string that is emitted in the generated header file. The string must be quoted to prevent expansion by the C preprocessor.

Examples

cpp_quote("#include \"foo.h\" ")

cpp_quote("#define UNICODE")

Remarks

The cpp_quote keyword instructs MIDL to emit the specified string, without the quote characters, into the generated header file.

C-language preprocessing directives that appear in the IDL file are processed by the C compiler’s preprocessor. The #define directives in the IDL file are available during MIDL compilation but are not available to the C compiler.

For example, when the preprocessor encounters the directive “#define WINDOWS 4”, the preprocessor replaces all occurrences of “WINDOWS” in the IDL file with “4”. The symbol “WINDOWS” is not available during C-language compilation.

To allow the C-preprocessor macro definitions to pass through the MIDL compiler to the C compiler, use the #pragma midl_echo or cpp_quote directive. These directives instruct the MIDL compiler to generate a header file that contains the parameter string with the quotation marks removed. The #pragma midl_echo and cpp_quote directives are equivalent.

The MIDL compiler places the strings specified in the cpp_quote and pragma directives into the header file in the sequence in which they are specified in the IDL file, and relative to other interface components in the IDL file. The strings should usually appear in the IDL file interface body section after all import operations.

See Also

IDL, pragma


decode

[ decode [ , interface-attribute-list] ] interface interface-name
[ decode [ , op-attribute-list] ] proc-name
typedef [decode [ , type-attribute-list] ] type-name

interface-attribute-list

Specifies other attributes that apply to the interface as a whole.

interface-name

Specifies the name of the interface.

op-attribute-list

Specifies other operational attributes that apply to the procedure such as encode.

proc-name

Specifies the name of the procedure.

type-attribute-list

Specifies other attributes such as encode and allocate.

typename

Specifies a type defined in the IDL file.

Remarks

The decode attribute specifies that a procedure or a type needs de-serialization support. This attribute causes the MIDL compiler to generate code that an application can use to retrieve serialized data from a buffer. The encode attribute provides serialization support, generating the code to serialize data into a buffer.

Use the encode and decode attributes in an ACF to generate serialization code for procedures or types defined in the IDL file of an interface. When used as an interface attribute, decode applies to all types and procedures defined in the IDL file. When used as a type attribute, decode applies only to the specified type. When used as an operational attribute, decode applies only to that procedure.

For more information about using this serialization support, see Encoding Services and encode.

See Also

encode


default

[uuid, attribute-list] coclass coclass-name
{
[default [, optional-interface-attribute]] interface | dispinterface interface-name
}

attribute-list

Specifies additional coclass attributes. Separate multiple attributes with commas.

optional-interface-attribute

The source attribute, which specifies that an interface or dispinterface is outgoing, is the only other attribute that can be used here.

Example

 [ uuid(. . .), helpstring("Hello Class"),appobject]  coclass Hello

    {[default] interface IHello;

               interface IDispatch;

    };

Remarks

The default attribute Indicates that the interface or dispinterface, defined within a coclass, represents the default programmability interface. This attribute is intended for use by macro languages.

A coclass may have at most two default members. One represents the outgoing (source) interface or dispinterface, and the other represents the incoming (sink) interface or dispinterface. If the default attribute is not specified for any member of the coclass or cotype, the first outgoing and incoming members that do not have the restricted attribute are treated as the defaults.

Flags

IMPLTYPEFLAG_FDEFAULT

See Also

TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


defaultbind

[interface-attribute-list] interface | dispinterface interface-name
{
[bindable, defaultbind[, attribute-list]] returntype function-name(params)
}

Example

[uuid(. . .)] interface MyObject : IUnknown

{

    properties:

    methods:

        [id(1), propget, bindable, defaultbind, displaybind]

        long Size(void);

        [id(1), propput, bindable, defaultbind, displaybind]

        void Size([in]long lSize);

}

Remarks

The defaultbind attribute indicates the single, bindable property that best represents the object. Properties that have the defaultbind attribute must also have the bindable attribute. Only one property in an interface or dispinterface can have the defaultbind attribute.

This attribute is used by containers that have a user model involving binding to an object rather than binding to a property of an object. An object can support data binding but not have this attribute.

Flags

FUNCFLAG_FDEFAULTBIND, VARFLAG_FDEFAULTBIND

See Also

TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


defaultvalue

interface interface-name
{

    return-type func-name(mandatory-param-list,
[[attribute-list,] defaultvalue(value)] param-type param-name[, optional-param-list]);

    }

Examples

interface IFoo : IUnknown

{

    HRESULT Ex1([defaultvalue(44)] LONG       i);

    HRESULT Ex2([defaultvalue(44)] SHORT      i);

    HRESULT Ex3([defaultvalue("Hello")] BSTR  i);

...

}

interface QueryDef : IUnknown

{

    HRESULT    OpenRecordset(  [in, defaultvalue(DBOPENTABLE)]

    LONG Type,

    [out,retval] Recordset **pprst);

}

 //  Type is now known to be a LONG type (good for browser in VBA and

//  good for a C/C++ programmer) and has a default value of

//  DBOPENTABLE

Remarks

The defaultvalue attribute allows specification of a default value for a typed optional parameter. The value can be any constant, or an expression that resolves to a constant, that can be represented by a VARIANT. Specifically, you cannot apply the defaultvalue attribute to a parameter that is a structure, an array, or a SAFEARRAY.type.

The MIDL compiler accepts the following parameter ordering (from left-to-right):

1.	Required parameters (parameters that do not have the defaultvalue or optional attributes),

2.	optional parameters with or without the defaultvalue attribute,

3.	parameters with the optional attribute and without the defaultvalue attribute,

4.	lcid parameter, if any,

5.	retval parameter

See Also

interface, dispinterface, TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


dispinterface

[attributes]dispinterface intfname {    properties:proplist    methods:    methlist};

[attributes]dispinterface intfname {    interface interfacename};

attributes

Specifies attributes that apply to the entire dispinterface. The following attributes are accepted: helpstring, helpcontext, helpfile, hidden, nonextensible, oleautomation, restricted, uuid, version.

intfname

The name by which the dispinterface is known in the type library. This name must be unique within the type library.

interfacename

(Syntax 2) The name of the interface to declare as an IDispatch interface.

proplist

(Syntax 1) An optional list of properties supported by the object, declared in the form of variables. This is the short form for declaring the property functions in the methods list. See the comments section for details.

methlist

(Syntax 1) A list comprising a function prototype for each method and property in the dispinterface. Any number of function definitions can appear in methlist. A function in methlist has the following form:

[attributes] returntype methname(params);

The following attributes are accepted on a method in a dispinterface: helpstring, helpcontext, string, bindable, defaultbind, displaybind, propget, propput, propputref, and vararg. If vararg is specified, the last parameter must be a safe array of VARIANT type.

The parameter list is a comma-delimited list, each element of which has the following form:

[attributes] type paramname

The type can be any declared or built-in type, or a pointer to any type. Attributes on parameters are:

in, out, optional, string

The MIDL compiler accepts the following parameter ordering (from left-to-right):

1.	Required parameters (parameters that do not have the defaultvalue or optional attributes),

2.	optional parameters with or without the defaultvalue attribute,

3.	parameters with the optional attribute and without the defaultvalue attribute,

4.	lcid parameter, if any,

5.	retval parameter

Examples

[ uuid(. . .), version(1.0), helpstring("Useful help string."), helpcontext(2480)]

dispinterface MyDispatchObject {

    properties:

        [id(1)] int x;    //An integer property named x

        [id(2)] BSTR y;   //A string property named y

    methods:

        [id(3)] void show();    //No arguments, no result

        [id(11)] int computeit(int inarg, double *outarg);

};

[uuid(. . .)]

dispinterface MyObject

{

    properties:

    methods:

        [id(1), propget, bindable, defaultbind, displaybind]

        long x();

        [id(1), propput, bindable, defaultbind, displaybind]

        void x(long rhs);

}

Remarks

The dispinterface statement defines a set of properties and methods on which you can call IDispatch::Invoke. A dispinterface may be defined by explicitly listing the set of supported methods and properties (Syntax 1), or by listing a single interface (Syntax 2).

Method functions are specified exactly as described in the reference page for module except that the entry attribute is not allowed. Note that STDOLE32.TLB (STDOLE.TLB on 16-bit systems) must be imported, because a dispinterface inherits from IDispatch.

You can declare properties in either the properties or methods lists. Declaring properties in the properties list does not indicate the type of access the property supports (that is, get, put, or putref). Specify the readonly attribute for properties that don’t support put or putref. If you declare the property functions in the methods list, functions for one property all have the same ID.

Using the first syntax, the properties: and methods: tags are required. The id attribute is also required on each member. For example:

properties:

    [id(0)] int Value;    // Default property.

methods:

    [id(1)] void Show();

Unlike interface members, dispinterface members cannot use the retval attribute to return a value in addition to an HRESULT error code. The lcid attribute is likewise invalid for dispinterfaces, because IDispatch::Invoke passes an LCID. However, it is possible to redeclare an interface that uses these attributes.

Using the second syntax, interfaces that support IDispatch and are declared earlier in an ODL script can be redeclared as IDispatch interfaces as follows:

dispinterface helloPro {

    interface hello;

};

The preceding example declares all the members of hello and all the members that hello inherits as supporting IDispatch. In this case, if hello were declared earlier with lcid and retval members that returned HRESULTs, MkTypLib would remove each lcid parameter and HRESULT return type, and instead mark the return type as that of the retval parameter.

The properties and methods of a dispinterface are not part of the VTBL of the dispinterface. Consequently, CreateStdDispatch and DispInvoke cannot be used to implement IDispatch::Invoke. The dispinterface is used when an application needs to expose existing non-VTBL functions through OLE Automation. These applications can implement IDispatch::Invoke by examining the dispidMember parameter and directly calling the corresponding function.

See Also

interface, TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


displaybind

[interface-attribute-list] interface | dispinterface interface-name
{
[bindable, displaybind[, attribute-list]] returntype function-name(params)
}

Example

[uuid(. . .)] interface MyObject : IUnknown

{

    properties:

    methods:

        [id(1), propget, bindable, defaultbind, displaybind]

        long Size(void);

        [id(1), propput, bindable, defaultbind, displaybind]

        void Size([in]long lSize);

}

Remarks

The displaybind attribute indicates a property that should be displayed to the user as bindable. Properties that have the displaybind attribute must also have the bindable attribute. An object can support data binding but not have this attribute.

Flags

FUNCFLAG_FDISPLAYBIND, VARFLAG_FDISPLAYBIND

See Also

TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


dllname(str)

[uuid, dllname(“filename”)[, optional-attribute-list]]
module modulename {
elementlist
};

Example

[uuid(. . .),helpstring("A meaningful comment"),      dllname("HANDY.DLL")]

module HandyStuff{

    . . .

};

Remarks

The dllname attribute defines the name of the DLL that contains the entry points for a module. This attribute is required on a module.

See Also

module,entry, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


double

Remarks

The double keyword designates a 64-bit floating-point number.

The double type is one of the base types of the interface definition language (IDL). This type can appear as a type specifier in typedef declarations, general declarations, and function declarators (as a function-return-type specifier and a parameter-type specifier). For the context in which type specifiers appear, see IDL.

The double type cannot appear in const declarations.

See Also

base_types, float


dual

[uuid, oleautomation, dual [, optional-attribute-list]]
interface interfacename
{. . .};

Example

[uuid(. . .), oleautomation, dual]

    interface IHello : Idispatch

    {

     //diverse and sundry properties and methods defined here

    };

Remarks

The dual attribute identifies an interface that exposes properties and methods through IDispatch and directly through the VTBL. The interface must be compatible with OLE Automation and be derived from IDispatch. The attribute is not allowed on dispinterfaces.

The dual attribute creates an interface that is both a Dispatch interface and a Component Object Model (COM) interface. The first seven entries of the VTBL for a dual interface are the seven members of IDispatch, and the remaining entries are OLE COM entries for direct access to members of the dual interface. All the parameters and return types specified for members of a dual interface must be OLE Automation-compatible types.

All members of a dual interface must pass an HRESULT as the function return value. Members, such as property accessor functions, that need to return other values, such as  should specify the last parameter as [out, retval], indicating an output parameter that returns the value of the function. In addition, members that need to support multiple locales should pass an lcid parameter.

A dual interface provides for both the speed of direct VTBL binding and the flexibility of IDispatch binding. For this reason, dual interfaces are recommended whenever possible.

Note  If your application accesses object data by casting the this pointer within the interface call, you should check the VTBL pointers in the object against your own VTBL pointers to ensure that you are connected to the appropriate proxy.

Specifying dual on an interface implies that the interface is compatible with OLE Automation, and therefore causes both the TYPEFLAG_FDUAL and TYPEFLAG_FOLEAUTOMATION flags to be set.

Flags

TYPEFLAG_FDUAL, TYPEFLAG_FOLEAUTOMATION

See Also

interface, oleautomation, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


enable_allocate

Remarks

The keyword enable_allocate specifies that the server stub code should enable the stub memory management environment. In default mode, the server stub enables the memory environment only when the enable_allocate attribute is used. The memory management environment must be enabled before memory can be allocated using RpcSmAllocate. In osf mode (when you compile using the /osf switch), the stub enables this environment automatically when the remote operation includes full pointers or pointers that provide for the stub or the user to allocate memory, or on request when the enable_allocate attribute is used.

The client side stub may be sensitive to the Rpcss memory management environment. If a sensitive client stub is executed when the Rpcss package is disabled, the default user allocator/deallocators are called (for example, midl_user_allocate/midl_user_free). When enabled, the Rpcss package uses the allocator/deallocator pair from the package. In the default mode, the client is sensitive only when the enable_allocate attribute is used. Typically, the client side stub operates in the disabled environment. In osf mode (when you compile using the /osf switch), the client is always sensitive to the Rpcss memory management environment and, therefore, the enable_allocate attribute will not affect the client stubs.

See Also

ACF, RpcSmDisableAllocate, RpcSmEnableAllocate, RpcSmFree


encapsulated_union

typedef [ [type-attribute-list] ]
union [ struct-name ] switch (switch-type switch-name) [ union-name ] {
[ case (limited-expression-list ) ]
[ [ field-attribute-list ] ] type-specifier declarator-list ;
...
}

type-attribute-list

Specifies zero or more attributes that apply to the union type. Valid type attributes include handle, transmit_as; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle and ignore. Separate multiple attributes with commas.

struct-name

Specifies an optional tag that names the structure generated by the MIDL compiler.

switch-type

Specifies an int, char, enum type, or an identifier that resolves to one of these types.

switch-name

Specifies the name of the variable of type switch-type that acts as the union discriminant.

union-name

Specifies an optional identifier that names the union in the structure, generated by the MIDL compiler, that contains the union and the discriminant.

limited-expression-list

Specifies one or more C-language expressions. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators.

field-attribute-list

Specifies zero or more field attributes that apply to the union member. Valid field attributes include first_is, last_is, length_is, max_is, size_is; the usage attributes string, ignore, and context_handle; the pointer attribute unique or ptr; and, for members that are tnonencapsulated unions, the union attribute switch_type. Separate multiple field attributes with commas.

type-specifier

Specifies a base_type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.

declarator-list

One or more standard C declarators, such as identifiers, pointer declarators, and array declarators. (Function declarators and bit-field declarations are not allowed in unions that are transmitted in remote procedure calls. Except when you use the MIDL compiler switch /osf, these declarators are allowed in unions that are not transmitted.) Separate multiple declarators with commas.

Examples

typedef union _S1_TYPE switch (long l1) U1_TYPE {

    case 1024:

        float f1;

    case 2048:

        double d2;

} S1_TYPE;

/* in generated header file */

typedef struct _S1_TYPE {

    long l1;

    union {

        float f1;

        double d2;

    } U1_TYPE;

} S1_TYPE;

Remarks

The encapsulated union is indicated by the presence of the switch keyword. This type of union is so named because the MIDL compiler automatically encapsulates the union and its discriminant in a structure for transmission during a remote procedure call.

If the union tag is missing (U1_TYPE in the example above), the compiler will generate the structure with the union field named tagged_union.

The shape of unions must be the same across platforms to ensure interconnectivity.

See Also

IDL, ms_union, non-encapsulated_union, switch_is, switch_type, union


encode

[ encode [ , interface-attribute-list] ] interface interface-name
[ encode [ , op-attribute-list] ] proc-name
typedef [encode [ , type-attribute-list] ] type-name

interface-attribute-list

Specifies other attributes that apply to the interface as a whole.

interface-name

Specifies the name of the interface.

op-attribute-list

Specifies other operational attributes that apply to the procedure such as decode.

proc-name

Specifies the name of the procedure.

type-attribute-list

Specifies other attributes that apply to the type such as decode and allocate.

typename

Specifies a type defined in the IDL file.

Examples

/*

    ACF file example;

    Assumes MyType1, MyType2, MyType3, MyProc1, MyProc2, MyProc3 defined

    in IDL file

    MyType1, MyType2, MyProc1, MyProc2 have encode and decode

    serialization support

    MyType3 and MyProc3 have encode serialization support only

*/

[ encode, implicit_handle(handle_t bh) ]    interface regress

{

    typedef [ decode ] MyType1;

    typedef [ encode, decode ] MyType2;

    [ decode ] MyProcc1();

    [ encode ] MyProc2();

}

Remarks

The encode attribute specifies that a procedure or a data type needs serialization support. This attribute causes the MIDL compiler to generate code that an application can use to serialize data into a buffer. The decode attribute provides deserialization support, generating the code for retrieving data from a buffer.

Use the encode and decode attributes in an ACF to generate serialization code for procedures or types defined in the IDL file of an interface. When used as an interface attribute, encode applies to all the types and procedures defined in the IDL file. When used as an operational attribute, encode applies only to the specified procedure. When used as a type attribute, encode applies only to the specified type.

When the encode or decode attribute is applied to a procedure, the MIDL compiler generates a serialization stub in a similar fashion as remote stubs are generated for remote routines. A procedure can be either a remotable or a serializing procedure, but it cannot be both. The prototype of the generated routine is sent to the STUB.H file while the stub itself goes into the STUB_C.C file.

The MIDL compiler generates two functions for each type the encode attribute applies to, and one additional function for each type the decode attribute applies to. For example, for a user-defined type named MyType, the compiler generates code for the MyType_Encode, MyType_Decode, and MyType_AlignSize functions. For these functions, the compiler writes prototypes to STUB.H and source code to STUB_C.C.

For additional information about serialization handles and encoding or decoding data, see Using Encoding Services.

See Also

decode


endpoint

endpoint(“protocol-sequence:[endpoint-port]” [ , ...] )

protocol-sequence

Specifies a character string that represents a valid combination of an RPC protocol (such as “ncacn”), a transport protocol (such as “tcp”), and a network protocol (such as “ip”). Microsoft RPC supports the following protocol sequences:

Protocol sequence	Description	Supporting Platforms
ncacn_nb_tcp	Connection-oriented NetBIOS over TCP	Client and server: Windows NT Client only: MS-DOS, Windows 3.x™
ncacn_nb_ipx	Connection-oriented NetBIOS over IPX	Client and server: Windows NT Client : MS-DOS, Windows 3.x
ncacn_nb_nb	Connection-oriented NetBEUI	Client and server: Windows NT, Windows® 95 Client : MS-DOS, Windows 3.x
ncacn_ip_tcp	Connection-oriented TCP/IP	Client and server: Windows 95 and Windows NT Client: MS-DOS,Windows 3.x, and Apple® Macintosh®
ncacn_np	Connection-oriented named pipes	Client and server: Windows NT Client: MS-DOS, Windows 3.x, Windows 95
ncacn_spx	Connection-oriented SPX	Client and server: Windows NT, Windows 95 Client: MS-DOS, Windows 3.x
ncacn_dnet_nsp	Connection-oriented DECnet	Client only: MS-DOS, Windows 3.x
ncacn_at_dsp	Connection-oriented AppleTalk DSP	Server: Windows NT Client: Apple Macintosh
ncacn_vns_spp	Connection-oriented Vines SPP	Client and server: Windows NT Client: MS-DOS, Windows 3.x
ncadg_ip_udp	Datagram (connectionless) UDP/IP	Client and server: Windows NT Client: MS-DOS, Windows 3.x
ncadg_ipx	Datagram (connectionless) IPX	Client and server: Windows NT Client: MS-DOS, Windows 3.x
ncalrpc	Local procedure call	Client and server: Windows NT and Windows 95
endpoint-port

Specifies a string that represents the endpoint designation for the specified protocol family. The syntax of the port string is specific to each protocol sequence.

Examples

endpoint("ncacn_np:[\\pipe\\rainier]")

endpoint("ncacn_ip_tcp:[1044]", "ncacn_np:[\\pipe\\shasta]")

Remarks

The endpoint attribute specifies a well-known port or ports (communication endpoints) on which servers of the interface listen for calls.

The endpoint specifies a transport family such as the TCP/IP connection-oriented protocol, a NetBIOS connection-oriented protocol, or the named-pipe connection-oriented protocol.

The protocol-sequence value determines the valid values for the endpoint-port. The MIDL compiler checks only general syntax for the endpoint-port entry. Port specification errors are reported by the run-time libraries. For information about the allowed values for each protocol sequence, see the topic for that protocol sequence.

The following protocol sequences specified by DCE are not supported by the MIDL compiler provided with Microsoft RPC: ncacn_osi_dna and ncadg_dds.

Make sure that you correctly quote backslash characters in endpoints. This error commonly occurs when the endpoint is a named pipe. Endpoint information specified in the IDL file is used by the RPC run-time functions RpcServerUseProtseqIf and RpcServerUseAllProtseqsIf.

See Also

IDL


entry

 [uuid, entry(entry-id)[, optional-attribute-list]]
module modulename {
elementlist
};

Example

[dllname("MyAppsFirst.dll")] module MyModule

    {

    [entry(20), bindable, requestedit, propputref, defaultbind]

        void Func1([in]IUnknown * Param1, [out] MyType * Param2);

    [entry("TwentyOne"), hidden, vararg]

         SAFEARRAY (int) Func2 ([in, out] SAFEARRAY (variant) *varP) ;

    [entry(22)] Float Func3 ([in] lpstr pName, [in] double dLevel,
                           [out] short * sByte) ;

    } ;

Remarks

The entry attribute specifies an exported function or constant in a module by identifying the entry point in the DLL. If entryid is a string, this is a named entry point. If entryid is a number, the entry point is defined by an ordinal. This attribute provides a way to obtain the address of a function in a module.

See Also

dllname, module, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


enum

enum [tag ] { identifier [=integer-value ] [ , ... ] }

tag

Specifies an optional tag for the enumerated type.

identifier

Specifies the particular enumeration.

integer-value

Specifies a constant integer value.

Examples

typedef enum {Monday=2, Tuesday, Wednesday, Thursday, Friday} workdays;

typedef enum {Clemens=21, Palmer=22, Ryan=34} pitchers;

Remarks

The keyword enum is used to identify an enumerated type. Enum types can appear as type specifiers in typedef declarations, general declarations, and function declarators (either as the function-return-type or as a parameter-type specifier). For the context in which type specifiers appear, see IDL.

In the MIDL compiler’s default mode, you can assign integer values to enumerators. (This feature is not available when you compile with the /osf switch.) As with C-language enumerators, enumerator names must be unique, but the enumerator values need not be.

When assignment operators are not provided, identifiers are mapped to consecutive integers from left to right, starting with zero. When assignment operators are provided, assigned values start from the most recently assigned value.

The maximum number of identifiers is 65,535.

Objects of type enum are int types, and their size is system-dependent. By default, objects of enum types are treated as 16-bit objects of type unsigned short when transmitted over a network. Values outside the range 0 - 32,767 cause the run-time exception RPC_X_ENUM_VALUE_OUT_OF_RANGE. To transmit objects as 32-bit entities, apply the v1_enum attribute to the enum typedef.

See Also

IDL, typedef, v1_enum


error_status_t

Remarks

The error_status_t keyword designates a type for an object that contains communication-status or fault-status information.

The error_status_t type is used as a part of the exception handling architecture in IDL. This type maps to an unsigned long. Applications that catch error situations have an out parameter or a return type of a procedure specified as error_status_t, and qualify the error_status_t with the comm_status or fault_status attributes in the ACF. If the parameter or return type was not qualified with the comm_status or fault_status attributes, then the parameter operates as though it were an unsigned long.

The MIDL 2.0 compiler generates stubs that contain the proper error handling architecture. However, earlier versions of the MIDL compiler handled a parameter or return type of error_status_t as though the comm_status and fault_status attributes were applied, even if they were not. With the MIDL 2.0 compiler, you must explicitly apply the comm_status and fault_status attributes to the parameter or procedure in the ACF.

The error_status_t type is one of the predefined types of the interface definition language. Predefined types can appear as type specifiers in typedef declarations, in general declarations, and in function declarators (either as the function-return-type or as parameter-type specifiers).

See Also

comm_status, fault_status, IDL


explicit_handle

[explicit_handle] {...}

Example

/* ACF File */

[explicit_handle]

{

};

Remarks

The explicit_handle attribute specifies that each procedure has, as its first parameter, a primitive handle, such as a handle_t type. This is the case even if the IDL file does not contain the handle in its parameter list. The prototypes emitted to the header file and stub routines contain the additional parameter, and that parameter is used as the handle for directing the remote call.

The explicit_handle attribute affects both remote procedures and serialization procedures. For type serialization, the support routines are generated with the initial parameter as an explicit (serialization) handle. If the explicit_handle attribute is not used, the application can still specify that an operation have an explicit handle (binding or serialization) directing the call. To do this, a prototype with an argument containing a handle type is supplied to the IDL file. Note that in default mode, an argument that does not appear first can also be used as a handle directing the call. Therefore, while the explicit_handle attribute is a way of giving the IDL prototype a primitive explicit_handle attribute, it does not necessarily require a change to the IDL file. In /osf mode only the first argument can be used as an explicit handle type.

The explicit_handle attribute can be used as either an interface attribute or an operation attribute. As an interface attribute, it affects all the operations in the interface and all the types that require serialization support. If, however, it is used as an operation attribute, it affects only that particular operation.

See Also

ACF, auto_handle, implicit_handle


fault_status

[fault_status [ , ACF-function-attributes ] ] function-name(
[ [ ACF-parameter-attributes ] ] parameter-name
, ...
);

[ [ ACF-function-attributes ] ] function-name(
[fault_status [ , ACF-parameter-attributes ] ] parameter-name
... );

ACF-function-attributes

Specifies zero or more ACF function attributes such as fault_status and nocode. Function attributes are enclosed in square brackets. Note that zero or more attributes can be applied to a function. Separate multiple function attributes with commas. Also note that if fault_status appears as a function attribute, it cannot also appear as a parameter attribute.

function-name

Specifies the name of the function as defined in the IDL file.

ACF-parameter-attributes

Specifies attributes that apply to a parameter. Note that zero or more attributes can be applied to the parameter. Parameter attributes are enclosed in square brackets. Separate multiple parameter attributes with commas. IDL parameter attributes, such as directional attributes, are not allowed in the ACF. Note that if fault_status appears as a parameter attribute, it cannot also appear as a function attribute.

parameter-name

Specifies the parameter for the function as defined in the IDL file. Each parameter for the function must be specified in the same sequence, using the same name as defined in the IDL file.

Remarks

The fault_status attribute can be used as either a function attribute or as a parameter attribute, but it can appear only once per function. It can be applied either to the function or to one parameter in each function.

The fault_status attribute can be applied only to functions that return the type error_status_t. When the remote procedure fails in a way that causes a fault PDU to be returned, an error code is returned.

When fault_status is used as a parameter attribute, the parameter must be an out parameter of type error_status_t. If a server error occurs, the parameter is set to the error code. When the remote call is successfully completed, the procedure sets the value.

The parameter associated with the fault_status attribute does not have to be specified in the IDL file. When the parameter is not specified, a new out parameter of type error_status_t is generated following the last parameter defined in the DCE IDL file.

It is possible for both the fault_status and comm_status attributes to appear in a single function, either as function attributes or parameter attributes. If both attributes are function attributes, or if they apply to the same parameter and no error occurs, the function or parameter has the value error_status_ok. Otherwise, it contains the appropriate status code value. Because values returned for fault_status are different from the values returned for comm_status, the returned values are readily interpreted.

See Also

ACF, comm_status, error_status_t


field_attributes

[ [ field-attribute-list ] ] type-specifier declarator-list;

field-attribute-list

Specifies zero or more field attributes that apply to the structure or union member, array, or function parameter. Valid field attributes include first_is, last_is, length_is, max_is, size_is; the usage attributes string, ignore, and context_handle; the pointer attribute ref, unique, or ptr; and the union attribute switch_type. Separate multiple field attributes with commas.

type-specifier

Specifies a base_type, struct, union, or enum type or type identifier. An optional storage specification can precede type-specifier.

declarator-list

Specifies one or more standard C declarators, such as identifiers, pointer declarators, and array declarators. Separate multiple declarators with commas.

Remarks

Field attributes are used in structure, union, array, and function-parameter declarators to define transmission characteristics of the declarator during a remote procedure call.

Field-attribute keywords include size_is, max_is, length_is, first_is, and last_is; the usage attributes string, ignore, and context_handle; the union switch switch_is;and the pointer attributes ref, unique, and ptr.

The field attributes size_is, max_is, length_is, first_is, and last_is specify the size or range of valid data for the declarator. These field attributes associate another parameter, structure member, union member, or constant expression with the declarator.

Field attributes that are parameters must associate with declarators that are parameters, while field attributes that are members of structures or unions must associate with declarators that are members of the same structure or union.

For information about the context in which field attributes appear, see arrays, struct, and union.

See Also

arrays, first_is, IDL, last_is, length_is, max_is, size_is


first_is

first_is(limited-expression-list)

limited-expression-list

Specifies one or more C-language expressions. Each expression evaluates to an integer that represents the array index of the first array element to be transmitted. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators. Separate multiple expressions with commas.

Example

void Proc1(

    [in] short First,

    [first_is(First)] Arr[10]);

Remarks

The first_is attribute specifies the index of the first array element to be transmitted. If the first_is attribute is not present, or if the specified index is a negative number, array element zero is the first element transmitted.

The first_is attribute can also help determine the values of the array indexes corresponding to the last_is or length_is attribute when these attributes are not specified. The relationship between these array indexes is:

length = last - first + 1

The following relationship must also hold:

0 <= first_is <= max_is

The following relationship must hold when max_is <= 0:

first_is == 0

The first_is attribute cannot be used at the same time as the string attribute.

Using a constant expression with the first_is attribute is an inappropriate use of the attribute. It is legal, but inefficient, and will result in slower marshalling code.

See Also

field_attributes, IDL, last_is, length_is, max_is, min_is, size_is


float

Remarks

The float keyword designates a 32-bit floating-point number.

The float type is one of the base types of the interface definition language (IDL). The float type can appear as a type specifier in typedef declarations, general declarations, and function declarators (as a function-return-type specifier and a parameter-type specifier). For the context in which type specifiers appear, see IDL.

The float type cannot appear in const declarations.

See Also

base_types, double


handle

typedef [handle] typename;
handle_t __RPC_USER typename_bind (typename);
void __RPC_USER typename_unbind (typename, handle_t);

typename

Specifies the name of the user-defined binding-handle type.

Examples

typedef [handle] struct {

    char machine[8];

    char nmpipe[256];

 } h_service;

handle_t __RPC_USER h_service_bind(h_service);

void __RPC_USER h_service_unbind(h_service, handle_t);

Remarks

The handle attribute specifies a user-defined or “customized” handle type. User-defined handles permit developers to design handles that are meaningful to the application.

A user-defined handle can only be defined in a type declaration, not in a function declarator.

A parameter of a type defined by the handle attribute is used to determine the binding for the call and is transmitted to the called procedure.

The user must provide binding and unbinding routines to convert between primitive and user-defined handle types. Given a user-defined handle of type typename, the user must supply the routines typename_bind and typename_unbind. For example, if the user-defined handle type is named MYHANDLE, the routines are named MYHANDLE_bind and MYHANDLE_unbind.

If successful, the typename_bind routine should return a valid primitive binding handle. If unsuccessful, the routine should return a NULL. If the routine returns NULL, the typename_unbind routine will not be called. If the binding routine returns an invalid binding handle different from NULL, the stub behavior is undefined.

When the remote procedure has a user-defined handle as a parameter or as an implicit handle, the client stubs call the binding routine before calling the remote procedure. The client stubs call the unbinding routine after the remote call.

In DCE IDL, a parameter with the handle attribute must appear as the first parameter in the remote procedure argument list. Subsequent parameters, including other handle attributes, are treated as ordinary parameters. Microsoft supports an extension to DCE IDL that allows the user-defined handle parameter to appear in positions other than the first parameter.

See Also

handles, IDL, implicit_handle, typedef


handles

Remarks

Binding handles are data objects that represent the binding between the client and the server.

MIDL supports the base type handle_t. Handles of this type are known as “primitive handles.”

You can define your own handle types using the handle attribute. Handles defined in this way are known as “user-defined” or “customized” handles or “generic handles.”

You can also define a handle that maintains state information using the context_handle attribute. Handles defined in this way are known as “context handles.”

If no state information is needed and you do not choose to call the RPC run-time libraries to manage the handle, you can request that the run-time libraries provide automatic binding. This is done by using the ACF keyword auto_handle.

You can specify a global variable as the binding handle by using the ACF keyword implicit_handle. The explicit_handle keyword is used to state that each remote function has an explicitly specified handle.

See Also

auto_handle, base_types, context_handle, explicit_handle, handle, handle_t, implicit_handle


handle_t

Remarks

The handle_t keyword declares an object to be of the primitive handle type handle_t. A primitive binding handle is a data object that can be used by the application to represent the binding.

The handle_t type is one of the predefined types of the interface definition language (IDL). It can appear as a type specifier in typedef declarations, general declarations, and function declarators (as a function-return-type specifier and a parameter-type specifier). For the context in which type specifiers appear, see IDL.

In Microsoft RPC, parameters of type handle_t can occur only as in parameters. Primitive handles cannot have the unique or ptr attribute.

Parameters of type handle_t (primitive handle parameters) are not transmitted on the network.

See Also

base_types, handles


heap

The DCE ACF keyword heap is not implemented in Microsoft RPC.


helpcontext

[uuid, helpcontext(helpcontext-value)[,attribute-list]] statement | directive statement-name {definitions}

Example

[uuid(. . .),helpcontext(7035943), helpstring("Hello Class"),appobject] coclass Hello
    {[default, helpcontext(3914972)]    interface IHello : IUnknown;

                        interface IDispatch;

    }

Remarks

The helpcontext attribute specifies a context ID that lets the user view information about this element in the Help file. This attribute can be applied to the following elements: library, importlib, interface, dispinterface, module, typedef, method, property, coclass.

The helpcontext-value is a 32-bit context identifier within the Help file that can be retrieved with the GetDocumentation functions in the ITypeLib and ITypeInfo interfaces.

See Also

ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


helpfile

[uuid, helpfile(“filename”) [, optional-attribute-list]] library {library statements};

Example

[uuid(. . .),helpfile(“filename.hlp”),lcid(0x0409), version(2.0)]

library Hello

{ . . .};

Remarks

The helpfile attribute sets the name of the Help file for a type library. All types in a library share the same Help file.

Use  the GetDocumentation functions in the ITypeLib and ITypeInfo interfaces to retrieve the filename.

See Also

library, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


helpstring

[helpstring(“string”)[, optional-attribute-list]] odl-statement

Example

  [uuid(. . .),helpstring("Lines 1.0 Type Library"),version(1.0)]

library Lines

{

     [uuid(. . .), helpstring("Line object."),oleautomation,dual]

    interface ILine : IDispatch

    {

      [propget, helpstring("Returns and sets RGB color.")]

      HRESULT Color([out, retval] long* retval);

      [propput, helpstring("Returns and sets RGB color.")]

      HRESULT Color([in] long rgb);

     }

};

Remarks

The helpstring attribute specifies a character string that is used to describe the element to which it applies. You can apply the helpstring attribute to library, importlib, interface, dispinterface, module, or coclass statements, typedefs, properties, and methods.

Use the GetDocumentation functions in the ITypeLib and ITypeInfo interfaces to retrieve the help string.

See Also

library, importlib, interface, dispinterface, module, coclass, typedef, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


hidden

[other-attributes, hidden] statement-or-function-type statement-or-function-name

Examples

[hidden, vararg]

  SAFEARRAY (int) SecretFunc ([in, out] SAFEARRAY (variant) *varP) ;

[uuid(. . .), hidden, version (3.0)] library HiddenLib {. . .};

Remarks

The hidden attribute indicates that the item exists but should not be displayed in a user-oriented browser. This attribute allows you to remove members from your interface (by shielding them from further use) while maintaining compatibility with existing code. You can use the hidden attribute on properties, methods, and the coclass, dispinterface, interface, and library statements.

When specified for a library, the hidden attribute prevents the entire library from being displayed. This usage is intended for use with controls. Hosts need to create a new type library that wraps the control with extended properties.

Flags

VARFLAG_FHIDDEN, FUNCFLAG_FHIDDEN, TYPEFLAG_FHIDDEN

See Also

TYPEFLAGS, dispinterface, coclass, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


hyper

Remarks

The keyword hyper indicates a 64-bit integer that can be declared as either signed or unsigned.

The hyper type is one of the base types of the interface definition language (IDL). The hyper type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function-return-type specifier and as a parameter-type specifier). For the context in which type specifiers appear, see IDL.

Note  For 16-bit platforms, the MIDL compiler replaces unsigned hyper integers with MIDL_uhyper. This allows interfaces with unsigned hyper integers to be defined on platforms that do not directly support 64-bit integers. MIDL_uhyper is defined in the RPC header files.

See Also

base_types


id

[id(id-num) [,optional-attribute-list]] return-type function-name

Example

Interface IKnown : IUnknown

{

properties:

[id(90), propget, helpstring(“A meaningful comment.”]

        long Func1(void);

. . .

}

Remarks

The id attribute specifies a DISPID for a member function (either a property or a method, in an interface or dispinterface). You use the id attribute when you want to assign a standard DISPID (like DISPID_VALUE, DISPID_NEWENUM etc.) to a method or property, or when you implement your own IDispatch::Invoke instead of delegating to DispInvoke/ITypeInfo::Invoke.

If you do not use the id attribute, the MIDL compiler will assign a DISPID for you.

The id-num is a 32-bit integral value in the following format:

Bits	Value
0−15	Offset. Any value is permissible.
16−21	The nesting level of this typeinfo in the inheritance hierarchy. For example: interface mydisp : IDispatch   The nesting level of IUnknown is 0, IDispatch is 1, and mydisp is 2.
22−25	Reserved; must be zero
26−28	DISPID value.
29	True if this is the member ID for a FuncDesc; otherwise False.
30−31	Must be 01.
Negative IDs are reserved for use by OLE Automation.

See Also

interface, dispinterface, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


idempotent

[[ [ IDL-operation-attributes ] ]] operation-attribute , ...

IDL-operation-attributes

Specifies zero or more IDL operation attributes such as idempotent and broadcast. Operation attributes are enclosed in square brackets.

Remarks

An idempotent operation is one that does not modify state information and returns the same results each time it is performed. Performing the routine more than once has the same effect as performing it once.

RPC supports two types of remote call semantics: calls to idempotent operations and calls to non-idempotent operations. An idempotent operation can be carried out more than once with no ill effect. Conversely, a non-idempotent operation (at-most-once) cannot be executed more than once because it will either return different results each time or because it modifies some state.

To ensure that a procedure is automatically re-executed if the call does not complete, use the idempotent attribute. If the idempotent, broadcast, or maybe attributes are not present, the procedure will use non-idempotent semantics by default. In this case, the operation is executed only once.

See Also

broadcast, IDL, maybe, non-idempotent


IDL

[ interface-attribute-list ] interface interface-name
{
[ import import-file-list ; ... ]
[ cpp_quote(“string”) ... ]

[ const const-type identifier = const-expression ; ... ]

[ [ typedef ] [ [type-attribute-list] ] type-specifier declarator-list; ...]

[	[ [function-attr-list] ] type-specifier [pointer-declarator] function-name(
[ [parameter-attribute-list] ] type-specifier [declarator]
, ...
);
...
]
}

interface-attribute-list

Specifies either the attribute uuid or the attribute local and other optional attributes that apply to the interface as a whole. The attributes endpoint, version, and pointer_default are optional. When you compile with the /app_config switch, either implicit_handle or auto_handle can also be present. Separate multiple attributes with commas. The interface-attribute-list does not have to be present for imported IDL files, but must be present for the base IDL file.

interface-name

Specifies the name of the interface. The identifier must be unique or different from any type names. It also must be 17 characters or less because it is used to form the name of the interface handle. The same interface name must be supplied in the ACF, except when you compile with the /acf switch.

import-file-list

Specifies one or more IDL files to import. Separate filenames with commas.

string

Specifies a string that is emitted in the generated header file.

const-type

Specifies the name of an integer, character, boolean, void *, byte, or string (char *, byte *, wchar_t *) type. Only these types can be assigned const values in the IDL file.

identifier

Specifies a valid MIDL identifier. Valid MIDL identifiers consist of up to 31 alphanumeric and/or underscore characters and must start with an alphabetic or underscore character.

const-expression

Specifies a constant declaration. The const-expression must evaluate to the type specified by const-type. For more information, see const.

type-attribute-list

Specifies one or more attributes that apply to the type. Valid type attributes include handle, switch_type, transmit_as; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle, ignore, and string. Separate multiple attributes with commas.

type-specifier

Specifies a base_type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.

declarator and declarator-list

Specify standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see pointers and arrays. The declarator-list consists of one or more declarators separated by commas. The parameter declarator in the function declarator, such as the parameter name, is optional.

function-attr-list

Specifies zero or more attributes that apply to the function. Valid function attributes are callback, local; the pointer attribute ref, unique, or ptr; and the usage attributes string, ignore, and context_handle.

pointer-declarator

Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C and is is constructed from the * designator, modifiers such as far and the qualifier const.

function-name

Specifies the name of the remote procedure.

parameter-attribute-list

Specifies zero or more attributes appropriate for the specified parameter type. Parameter attributes can take the directional attributes in and out; the field attributes first_is, last_is, length_is, max_is, size_is, and switch_type; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle and string. The usage attribute ignore cannot be used as a parameter attribute. Separate multiple attributes with commas.

Examples

[ uuid(12345678-1234-1234-1234-123456789ABC),

  version(3.1),

  pointer_default(unique)

] interface IdlGrammarExample

{

import "windows.idl", "other.idl";

const wchar_t * NAME = L"Example Program";

typedef char * PCHAR;

void DictCheckSpelling(

     [in, string] PCHAR   word,     // word to look up

     [out]        short * isPresent // 0 if not present

);

}

Remarks

The IDL file contains the specification for the interface. The interface includes the set of data types and the set of functions to be executed from a remote location. Interfaces specify the function prototypes for remote functions and for many aspects of their behavior from the point of view of interface users.

Another file, the application configuration file (ACF), contains attributes that tailor the application for a specific operating environment. For more information, see ACF.

An interface specification consists of an interface header followed by an interface body. The interface header includes an attribute list describing characteristics that apply to the interface as a whole. The interface body contains the remote data types and function prototypes. The interface body also contains zero or more import lists, constant declarations, general declarations, and function declarators.

In Microsoft RPC, an IDL file can contain multiple interfaces and these interfaces can be forward declared (within the IDL file that defines them). For example:

interface ITwo; //forward declaration

interface IOne {

...uses ITwo...

}

interface ITwo {

...uses IOne...

}

Type definitions, construct declarations, and imports can occur outside of the interface body. All definitions from the main IDL file will appear in the generated header file, and all the procedures from all the interfaces in the main IDL file will generate stub routines. This enables applications that support multiple interfaces to merge IDL files into a single, combined IDL file.

As a result, it requires less time to compile the files and also allows MIDL to reduce redundancies in the generated stubs. This can significantly improve object interfaces through the ability to share common code for base interfaces and derived interfaces. For non-object interfaces, the procedure names must be unique across all the interfaces. For object interfaces, the procedure names only need to be unique within an interface. Note that multiple interfaces are not permitted when you use the /osf switch.

The syntax for declarative constructs in the IDL file is similar to that for C. MIDL supports all Microsoft C/C++ declarative constructs except:

•	Older style declarators that allow a declarator to be specified without a type specifier, such as:

x (y)

short x (y)

•	Declarations with initializers (MIDL only accepts declarations that conform to the MIDL const syntax).

The import keyword specifies the names of one or more IDL files to import. The import directive is similar to the C include directive, except that only data types are assimilated into the importing IDL file.

The constant declaration specifies boolean, integer, character, wide-character, string, and void * constants. For more information, see const.

A general declaration is similar to the C typedef statement with the addition of IDL type attributes. Except in /osf mode, the MIDL compiler also allows an implicit declaration in the form of a variable definition.

The function declarator is a special case of the general declaration. You can use IDL attributes to specify the behavior of the function return type and each of the parameters.

See Also

arrays, const, enum, import, in, interface, MIDL Language Reference, out, pointers, struct, union


ignore

[ignore] pointer-member-type pointer-name;

pointer-member-type

Specifies the type of the pointer member of the structure or union.

pointer-name

Specifies the name of the pointer member that is to be ignored during marshalling.

Example

typedef struct _DBL_LINK_NODE_TYPE {

    long value;

    struct _DBL_LINK_NODE_TYPE * next;

    [ignore] struct _DBL_LINK_NODE_TYPE * previous;

} DBL_LINK_NODE_TYPE;

Remarks

The ignore attribute designates that a pointer contained in a structure or union and the object indicated by the pointer is not transmitted. The ignore attribute is restricted to pointer members of structures or unions.

The value of a structure member with the ignore attribute is undefined at the destination. An in parameter is not defined at the remote computer. An out parameter is not defined at the local computer.

The ignore attribute allows you to prevent transmisison of data. This is useful in situations such as a double-linked list. The following example includes a double-linked list that introduces data aliasing:

/* IDL file */

typedef struct _DBL_LINK_NODE_TYPE {

    long value;

    struct _DBL_LINK_NODE_TYPE * next;

    struct _DBL_LINK_NODE_TYPE * previous;

} DBL_LINK_NODE_TYPE;

void remote_op([in] DBL_LINK_NODE_TYPE * list_head);

/* application */

DBL_LINK_NODE_TYPE * p, * q

p = (DBL_LINK_NODE_TYPE *)

    midl_user_allocate(sizeof(DBL_LINK_NODE_TYPE));

q = (DBL_LINK_NODE_TYPE *)

    midl_user_allocate(sizeof(DBL_LINK_NODE_TYPE));

p->next = q;

q->previous = p;

p->previous = q->next = NULL;

..

remote_op(p);

Aliasing occurs in the preceding example because the same memory area is available from two different pointers in the function p and p->next->previous.

Note that ignore cannot be used as a type attribute.

See Also

pointers, ptr, ref, unique


iid_is

[ iid_is(limited-expression) ]

limited-expression

Specifies a C-language expression. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators.

Example

HRESULT    CreateInstance(

    [in] REFIID riid,

    [out, iid_is(riid)] IUnknown ** ppvObject);

Remarks

The iid_is pointer attribute specifies the IID of the OLE interface pointed to by an interface pointer. You can use iid_is in attribute lists for function parameters and for structure or union members. The stubs use the IID to determine how to marshal the interface pointer. This is useful for an interface pointer that is typed as a base class parameter.

Files that use the iid_is attribute must be compiled with the MIDL compiler in default mode, that is not using the /osf switch.

See Also

object, uuid


immediatebind

[interface-attribute-list] interface | dispinterface interface-name
{
[bindable, immediatebind[, optional-attribute-list]] returntype function-name(params)
}

Example

[uuid(. . .)] interface MyObject : IUnknown

{

    properties:

    methods:

        [id(1), propget, bindable, immediatebind]

        long Size(void);

        [id(1), propput, bindable, immediatebind]

        void Size([in]long lSize);

}

Remarks

The immediatebind attribute indicates that the database will be notified immediately of all changes to a property of a data-bound object.

This attribute allows controls to differentiate between properties that need to notify the database of every change, and those that do not. For example, every change to a checkbox control should be sent to the underlying database immediately, even if the control has not lost the focus. However, for a listbox control, a change occurs whenever a different selection is highlighted. Notifying the database of a change before the control loses focus would be inefficient and unnecessary. The immediatebind attribute allows individual properties on a form to specify, by setting the ImmediateBind bit, that changes should be reported immediately.

Properties that have the immediatebind attribute must also have the bindable attribute.

Flags

FUNCFLAG_FIMMEDIATEBIND, VARFLAG_FIMMEDIATEBIND

See Also

bindable, TYPEFLAGS, interface, dispinterface, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


implicit_handle

implicit_handle(handle-type handle-name)

handle-type

Specifies the handle data type, such as the base type handle_t or a user-defined handle type.

handle-name

Specifies the name of the handle.

Example

/* ACF file */

[implicit_handle(handle_t hMyHandle)]

{

}

Remarks

The implicit_handle attribute specifies the handle used for functions that do not include an explicit handle as a procedure parameter. If the procedure is remote, the handle will be used as the binding handle for the remote call. The implicit handle may also be used to establish an initial binding for a function that uses a context handle. If the procedure is a serializing procedure, the handle is used as a serializing handle controlling the operation. In the case of type serialization, the handle is used as the serialization handle for all the serialized types.

The implicit_handle attribute specifies a global variable that contains a handle used by any function needing implicit handles.

The implicit binding handle type must be either handle_t (or a type based on handle_t) or a user-defined handle type specified with the handle attribute. The implicit serializing handle must be a type based on handle_t.

If the implicit handle type is not defined in the IDL file or in any files included and imported by the IDL file for the MIDL computer, you must supply the file containing the handle-type definition when you compile the stubs. Use the ACF include statement to include the file containing the handle-type definition.

The implicit_handle attribute can occur once, at most. The implicit_handle attribute can occur only if the auto_handle or explicit_handle attribute does not occur.

See Also

ACF, auto_handle, explicit_handle, include


import

import “filename” [ , ... ] ;

filename

Specifies the name of the header or IDL file to import.

Examples

import "recycled.idl";

import "system.h";

import “unknwn.idl”;

import "part1.idl", "part2.idl", "part3.idl";

Remarks

The import directive specifies another .IDL file containing definitions you wish to reference from the main .IDL file. The imported file is processed separately from the main IDL file and the CPP preprocessor is invoked independently on this file. All resultant type, constant, and interface definitions are available to the main .IDL file. This implies that CPP directives like #define do not carry over from an imported IDL file to the main IDL file, and vice versa

IDL statements, such as const declarations, typedefs, and interfaces become available to the importing file.

Similar to the C-language preprocessor macro #include, the import directive directs the compiler to include data types defined in the imported IDL files. Unlike the #include directive, the import directive ignores procedure prototypes, since no stubs are generated for anything in the imported file.

The import keyword is optional and can appear zero or more times in the IDL file. Each import keyword can be associated with more than one file name. Separate multiple filenames with commas. You must enclose the file name within quotation marks and end the import statement with a semicolon (;). Note that an interface without attributes can be imported into a base IDL file. However, the interface must contain only datatypes with no procedures. If even one procedure is contained in the interface, a local or UUID attribute must be specified.

The C-language header (.H) file generated for the interface does not directly contain the imported types but instead generates a #include directive for the header file corresponding to the imported interface. For example, when FOO.IDL imports BAR.IDL, the generated header file FOO.H includes BAR.H (FOO.H contains the directive #include BAR.H).

The import function is idempotent — that is, importing an interface more than once has no effect.

The behavior of the import directive is independent of the MIDL compiler mode switches /osf, and /app_config. However, pointer attribute decoration across imports may depend on the compiler mode (/osv vs. the default, /ms_ext). For details see Pointer-Attribute Type Inheritance.

See Also

IDL, Importing System Header Files, Importing Other IDL Files, /ms_ext, /osf


importlib

library (library-name){ importlib(file-to-import) }

file-to-import

The name and location of the imported file at MIDL compile-time.

Example

library BrowseHelper

{

    importlib("stdole.tlb");

    importlib("mydisp.tlb");

//remainder of library definition

};

Remarks

The importlib directive makes types that have already been compiled into another type library available to the library being created. All importlib directives must precede the other type descriptions in the library.

Note  Because the importlib directive makes any type defined in the imported library accessible from within the library being compiled, ambiguity is resolved as follows. If the imported libraries contain duplicate references, MIDL will use the last reference that it finds. This is in contrast to MKTYPLIB, which uses the first reference that it finds.

The imported type library should be distributed with the library being compiled.

See Also

library, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


in

[ [function-attribute-list] ] type-specifier [pointer-declarator] function-name(
[ in [ , parameter-attribute-list ] ] type-specifier [declarator]
, ...
);

function-attribute-list

Specifies zero or more attributes that apply to the function. Valid function attributes are callback, local, the pointer attribute ref, unique, or ptr, and the usage attributes string, ignore, and context_handle.

type-specifier

Specifies a base_type, struct, union, or enum type or type identifier. An optional storage specification can precede type-specifier.

pointer-declarator

Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.

function-name

Specifies the name of the remote procedure.

parameter-attribute-list

Specifies zero or more attributes appropriate for the specified parameter type. Parameter attributes with the in attribute can also take the directional attribute out; the field attributes first_is, last_is, length_is, max_is, size_is and switch_type; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle and string. The usage attribute ignore cannot be used as a parameter attribute. Separate multiple attributes with commas.

declarator

Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see pointers and arrays. The parameter declarator in the function declarator, such as the parameter name, is optional.

Example

void MyFunction([in] short count);

Remarks

The in attribute indicates that a parameter is to be passed from the calling procedure to the called procedure.

A related attribute, out, indicates that a parameter is to be returned from the called procedure to the calling procedure. The in and out attributes are known as directional parameter attributes because they specify the direction in which parameters are passed. A parameter can be defined as in, out, or in, out.

The in attribute identifies parameters that are marshalled by the client stub for transmission to the server.

The in attribute is applied to a parameter by default when no directional parameter attribute is specified.

See Also

IDL, midl_user_allocate, out


include

include filenames;

filenames

Specifies the name of one or more C-language header files. The .H extension must be supplied in the MS-DOS, 16-bit Windows, and 32-bit Windows environments. Separate multiple C-language header filenames with commas.

Remarks

The body of the ACF can contain include directives, ACF typedef attributes, and ACF function and parameter attributes.

The ACF include statement specifies one or more header files included in the generated stub code. The stub code contains a C-preprocessor #include statement, and the user supplies the C-language header file when compiling the stubs. Include statements rely on the C-compiler mechanism of searching the directory structure for included files.

Note  Use the import directive rather than the include directive for system files, such as WINDOWS.H, that contain data types you want to make available to the IDL file. The import directive ignores function prototypes and allows you to use MIDL compiler switches that optimize the generation of support routines.

See Also

ACF, import, typedef


in_line

The DCE IDL keyword in_line is not supported in Microsoft RPC.

See Also

IDL


int

[type-specifier] [ signed | unsigned ] integer-modifier [ int ] declarator-list;

type-specifier

Specifies a base_type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.

integer-modifier

Specifies the keyword small, short, long, or hyper, which selects the size of the integer data. On 16-bit platforms, the size qualifier must be present.

declarator-list

Specifies one or more standard C declarators, such as identifiers, pointer declarators, and array declarators. (Function declarators and bit-field declarations are not allowed in structures that are transmitted in remote procedure calls. These declarators are allowed in structures that are not transmitted.) Separate multiple declarators with commas.

Examples

signed short int i = 0;

int j = i;

typedef struct {

    small int         i1;

    short             i2;

    unsigned long int i3;

} INTSIZETYPE;

void MyFunc([in] long int lCount);

Remarks

On 32-bit platforms, the keyword int specifies a 32-bit signed integer. On 16-bit platforms, the keyword int is an optional keyword that can accompany the keywords small, short, and long.

Integer types are among the base types of the interface definition language (IDL). They can appear as type specifiers in typedef declarations, general declarations, and function declarators (as a function-return-type specifier and as a parameter-type specifier). For the context in which type specifiers appear, see IDL.

If no integer sign specification is provided, the integer type defaults to signed.

DCE IDL compilers do not allow the keyword signed to specify the sign of integer types. Therefore, this feature is not available when you use the MIDL compiler /osf switch.

See Also

base_types, long, /osf, short, small


__int64

The keyword __int64 specifies a valid integer supported by the MIDL compiler. For a discussion of how to use __int64, see hyper.

See Also

IDL, int


interface

[ interface-attribute-list ] interface interface-name [ : base-interface ]

/*IDL file typedef syntax */
typedef interface interface-name declarator-list

interface-attribute-list

Specifies attributes that apply to the interface as a whole. Valid interface attributes for an IDL file include endpoint, local, object, pointer_default, uuid, and version. Valid interface attributes for an ACF include encode, decode, either auto_handle or implicit_handle, and either code or nocode.

interface-name

Specifies the name of the interface. The identifier must start with an alphabetic or underscore character and can consist of up to 17 alphanumeric and underscore characters. The identifier must be 17 characters or less because it is used to form the name of the interface handle.

base-interface

Specifies the name of an interface from which this derived interface inherits member functions, status codes, and interface attributes. The derived interface does not inherit type definitions. To do this, use the import keyword to import the IDL file of the base interface.

declarator-list

Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see pointers and arrays. The declarator-list consists of one or more declarators, separated by commas.

Examples

/* use of interface keyword in IDL file for an RPC interface */

  [ uuid (00000000-0000-0000-0000-000000000000),

    version (1.0) ]

  interface remote_if_2

  {

  }

/* use of interface keyword in ACF for an RPC interface */

  [ implicit_handle( handle_t xa_bhandle ) ]

  interface remote_if_2

  {

  }

/* use of interface keyword in IDL file for an OLE interface */

  [ object, uuid (00000000-0000-0000-0000-000000000000) ]

  interface IDerivedInterface : IBaseInterface

  {

    import "base.idl"

    Save();

  }

/* use of interface keyword to define an interface pointer type */

  typedef interface IStorage *LPSTORAGE;

Remarks

The interface keyword specifies the name of the interface. The interface name must be provided in both the IDL file and the ACF.

The interface names in the IDL file and ACF must be the same, except when you use the MIDL compiler switch /acf. For more information, see /acf.

The interface name forms the first part of the name of interface-handle data structures that are parameters to the RPC run-time functions. For more information, see RPC_IF_HANDLE.

If the interface header includes the object attribute to indicate an OLE interface, it must also include the uuid attribute and must specify the base OLE interface from which it is derived. For more information about OLE interfaces, see object.

You can also use the interface keyword with the typedef keyword to define an interface data type.

See Also

ACF, endpoint, IDL, local, pointer_default, uuid, version


last_is

[last_is( limited-expression-list )]

limited-expression-list

Specifies one or more C-language expressions. Each expression evaluates to an integer that represents the array index of the last array element to be transmitted. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators. Separate multiple expressions with commas.

Example

proc1(

    [in] short Last,

    [in, last_is(Last)] short asNumbers[MAXSIZE]);

Remarks

The field attribute last_is specifies the index of the last array element to be transmitted. When the specified index is zero or negative, no array elements are transmitted.

The last_is attribute determines the value of the array index corresponding to the length_is attribute when length_is is not specified. The relationship between these array indexes is as follows:

length = last - first + 1

If the value of the array index specified by first_is is larger than the value specified by last_is, zero elements are transmitted.

The last_is attribute cannot be used as a field attribute at the same time as the length_is attribute or the string attribute.

Using a constant expression with the last_is attribute is an inappropriate use of the attribute. It is legal, but inefficient, and will result in slower marshalling code.

When the value specified by max_is is equal to or greater than zero, the following relationship must be true:

0 <= last_is <= max_is

See Also

field_attributes, first_is, IDL, length_is, max_is, size_is


lcid

[uuid, lcid(numid)[, optional-attribute-list]] library { }

Examples

[  uuid(. . .),lcid(0x09),version(1.0)]

library MyLibrary

{. . .};

interface IMyFace : IDispatch

{

[propget] HRESULT MyFunc([in, lcid] long LocaleID,
                         [out, retval] BSTR * retval);

. . .

}

Remarks

The lcid  attribute identifies the locale for a type library or for a function argument.

The numid is a 32-bit locale ID as used in Win32 National Language Support. The locale ID is typically entered in hexadecimal.

The MIDL compiler accepts the following parameter ordering (from left-to-right):

1.	Required parameters (parameters that do not have the defaultvalue or optional attributes),

2.	optional parameters with or without the defaultvalue attribute,

3.	parameters with the optional attribute and without the defaultvalue attribute,

4.	lcid parameter, if any,

5.	retval parameter

See Also

library, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


length_is

[length_is( limited-expression-list )]

limited-expression-list

Specifies one or more C-language expressions. Each expression evaluates to an integer that represents the number of array elements to be transmitted. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators. Separate multiple expressions with commas.

Examples

/* counted string holding at most "size" characters */

typedef struct {

     unsigned short size;

     unsigned short length;

     [size_is(size), length_is(length)] char string[*];

 } COUNTED_STRING_TYPE;

/* counted string holding at most 80 characters */

typedef struct {

     unsigned short length;

     [length_is(length)] char string[80];

 } STATIC_COUNTED_STRING_TYPE;

void Proc1(

    [in] short iLength;

    [in, length_is(iLength)] short asNumbers[10];

Remarks

The length_is attribute specifies the number of array elements to be transmitted. A non-negative value must be specified.

The length_is attribute determines the value of the array indexes corresponding to the last_is attribute when last_is is not specified. The relationship between these array indexes is as follows:

length = last - first + 1

The length_is attribute cannot be used at the same time as the last_is attribute or the string attribute.

To define a counted string with a length_is or last_is attribute, use a character array or pointer without the string attribute.

Using a constant expression with the length_is attribute is an inappropriate use of the attribute. It is legal, but inefficient, and will result in slower marshalling code.

See Also

field_attributes, first_is, IDL, last_is, max_is, min_is, size_is


library

[uuid [, optional-attribute-list]] library libname {definitions};

optional-attribute-list

Specifies additional attributes that apply to the entire library statement. Allowable attributes include control, helpcontext, helpfile, helpstring, hidden, lcid, restricted, and version.

libname

The name by which the type library is known.

definitions

Descriptions of any imported libraries, data types, modules, interfaces, dispinterfaces, and coclasses relevant to the object being exposed.

Example

[uuid(. . .), helpstring("Hello 2.0 Type Library"),

    lcid(0x0409), version(2.0)]

library Hello

{. . .};

Remarks

The library statement contains all the information that the MIDL compiler uses to generate a type library. In addition to elements defined inside of the library block, statements inside the library block can use elements that are declared outside of the library block by using those elements as base types, inheriting from those elements, or by simply referencing them on a line, as follows:

interface MyFace {. . .};

[library attributes] library

{

interface My Face;

};

The MIDL compiler will create a type library that includes definitions for every element inside the library block, plus definitions for any elements defined outside and referenced from within the library block.

For information on generating both a type library and proxy stubs and headers from a single IDL file see Generating a Proxy DLL and a Type Library From a Single IDL File.

See Also

Generating a Type Library With MIDL, Contents of a Type Library, ODL File Syntax


licensed

[attribute-list]coclass classname {coclass-definitions];

Example

[uuid(. . .), licensed, helpstring(“A meaningfulcomment”]   coclass MyClass

{. . .};

Remarks

The licensed attribute indicates that the coclass to which it applies is licensed, and must be instantiated using IClassFactory2.

Licensing is a feature of COM that provides control over object creation. Licensed objects can be created only by clients that are authorized to use them. Licensing is implemented in COM through the IClassFactory2 interface and by support for a license key that can be passed at run time.

Flags

TYPEFLAG_FLICENSED

See Also

coclass, Generating a Type Library With MIDL, Contents of a Type Library, ODL File Syntax, TYPEFLAGS


local

[ local [, interface-attribute-list] ] interface interface-name

[ object, uuid(string-uuid), local [, interface-attribute-list] ]
 interface interface-name

[ local [, function-attribute-list] ] function-declarator ;

interface-attribute-list

Specifies other attributes that apply to the interface as a whole. The attributes endpoint, version, and pointer_default are optional. When you compile with the /app_config switch, either implicit_handle or auto_handle can also be present. Separate multiple attributes with commas.

interface-name

Specifies the name of the interface.

string-uuid

Specifies a UUID string generated by the uuidgen utility. If you are not using the MIDL compiler switch /osf, you can enclose the UUID string in quotes.

function-attribute-list

Specifies zero or more attributes that apply to the function. Valid function attributes are callback; the pointer attribute ref, unique, or ptr; and the usage attributes string, ignore, and context_handle. Separate multiple attributes with commas.

function-declarator

Specifies the type specifier, function name, and parameter list for the function.

Examples

/* IDL file #1 */

[local] interface local_procs

{ void MyLocalProc(void);}

/* IDL file #2 */

[object,

 uuid(12345678-1234-1234-123456789ABC),

 local] interface local_object_procs

{ void MyLocalObjectProc(void);}

/* IDL file #3 */

[uuid(12345678-1234-1234-123456789ABC)]

interface mixed_procs

{

[local] void MyLocalProc(void);

void MyRemoteProc([in] short sParam);

}

Remarks

The local attribute can be applied to individual functions or to the interface as a whole.

When used in the interface header, the local attribute allows you to use the MIDL compiler as a header generator. The compiler does not generate stubs for any functions and does not ensure that the header can be transmitted.

For an RPC interface, the local attribute cannot be used at the same time as the uuid attribute. Either uuid or local must be present in the interface header, and the one you choose must occur exactly once.

For an OLE interface (identified by the object interface attribute), the interface attribute list can include the local attribute even though the uuid attribute is present.

When used in an individual function, the local attribute designates a local procedure for which no stubs are generated. Using local as a function attribute is a Microsoft extension to DCE IDL. Therefore this attribute is not available when you compile using the MIDL /osf switch.

Note that an interface without attributes can be imported into a base IDL file. However, the interface must contain only datatypes with no procedures. If even one procedure is contained in the interface, a local or UUID attribute must be specified.

See Also

IDL, /osf, object, uuid


long

The long keyword designates a 32-bit integer. It can be preceded by either the keyword signed or the keyword unsigned. The int keyword is optional and can be omitted. To the MIDL compiler, a long integer is signed by default and is synonymous with signed long int. On 32-bit platforms, long is synonymous with int.

The long integer type is one of the base types of the IDL language. The long integer type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function-return-type specifier and as a parameter-type specifier). For the context in which type specifiers appear, see IDL.

See Also

base_types, hyper, int, short, small


max_is

[max_is(limited-expression-list )]

limited-expression-list

Specifies one or more C-language expressions. Each expression evaluates to an integer that represents the highest valid array index. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators. Separate multiple expressions with commas.

Examples

/* if m = 10, there are 11 transmitted elements (a[0]...a[10])*/

void Proc1(

    [in] short m,

    [in, max_is(m)] short a[]);

/* if m = 10, the valid range for b is b[0...10][20] */

void Proc2(

    [in] short m,

    [in, max_is(m)] short b[][20];

Remarks

The max_is attribute designates the maximum value for a valid array index. For an array of size n in C, where the first array element is element number zero, the maximum value for a valid array index is n-1.

The max_is attribute cannot be used as a field attribute at the same time as the size_is attribute.

While it is legal to use the max_is attribute with a constant expression, doing so is inefficient and unnecessary. For example, use a fixed size array:

/* transmits values of a[0]... a[MAX_SIZE-1] */

void Proc3([in] short Arr[MAX_SIZE]);

instead of:

/* legal but marshalling code is much slower */

void Proc3([in max_is(MAX_SIZE-1)] short Arr[] );

See Also

field_attributes, IDL, min_is, size_is


maybe

[[ [ IDL-operation-attributes ] ]] operation-attribute , ...

IDL-operation-attributes

Specifies zero or more IDL operation attributes, such as maybe and idempotent. Operation attributes are enclosed in square brackets.

Remarks

The keyword maybe indicates that the remote procedure call does not need to execute every time it is called and the client does not expect a response. Note that the maybe protocol ensures neither delivery nor completion of the call.

A call with the maybe attribute cannot contain output parameters and is implicitly an idempotent call.

See Also

broadcast, idempotent, IDL, non-idempotent


midl_user_allocate

void __RPC_FAR * __RPC_API midl_user_allocate (size_t cBytes);

cBytes

Specifies the count of bytes to allocate.

Example

void __RPC_FAR * __RPC_API midl_user_allocate(size_t cBytes)

{

    return(malloc(cBytes));

}

Remarks

Both client applications and server applications must implement the midl_user_allocate function, unless you are compiling in OSF-compatibility (/osf) mode. Applications and generated stubs call midl_user_allocate when dealing with objects referenced by pointers:

•	The server application should call midl_user_allocate to allocate memory for the application — for example, when creating a new node.

•	The server stub calls midl_user_allocate when unmarshalling pointed-at data into the server address space.

•	The client stub calls midl_user_allocate when unmarshalling data from the server that is referenced by an out pointer. Note that for in, out, and unique pointers, the client stub calls midl_user_allocate only if the unique pointer value was NULL on input and changes to a non-null value during the call. If the unique pointer was non-null on input, the client stub writes the associated data into existing memory.

If midl_user_allocate fails to allocate memory, it must return a null pointer.

It is recommended that midl_user_allocate return a pointer that is 8 bytes aligned.

See Also

allocate, midl_user_free, pointers, ptr, ref, unique


midl_user_free

void __RPC_API midl_user_free(void __RPC_FAR * p);

Example

void __RPC_API midl_user_free(void __RPC_FAR * p)

{

    free(p);

}

Remarks

Both client application and server application must implement the midl_user_free function, unless you are compiling in OSF-compatibility (/osf) mode. The midl_user_free function must be able to free all storage allocated by midl_user_allocate.

Applications and stubs call midl_user_free when dealing with objects referenced by pointers:

•	The server application should call midl_user_free to free memory allocated by the application — for example, when deleting a specified node.

•	The server stub calls midl_user_free to release memory on the server after marshalling all out arguments, in, out arguments, and the return value.

See Also

midl_user_allocate, pointers, unique


min_is

The DCE IDL attribute min_is is not implemented in Microsoft RPC. The value of the minimum valid array index is zero.

See Also

arrays, IDL, max_is


module

[attributes] module modulename {elementlist};

attributes

The uuid, version, helpstring, helpcontext, hidden, and dllname attributes are accepted before a module statement. See “Attribute Descriptions,” in the Ole Automation book, for more information on the attributes accepted before a module definition. The dllname attribute is required. If the uuid attribute is omitted, the module is not uniquely specified in the system.

modulename

The name of the module.

elementlist

List of constant definitions and function prototypes for each function in the DLL. Any number of function definitions can appear in the function list. A function in the function list has the following form:

[attributes] returntype [calling convention] funcname(params);
[attributes] const constname = constval;

Only the helpstring and helpcontext attributes are accepted for a const.

The following attributes are accepted on a function in a module: helpstring, helpcontext, string, entry, propget, propput, propputref, vararg. If vararg is specified, the last parameter must be a safe array of VARIANT type.

The optional calling convention can be one of __pascal/_pascal/pascal, __cdecl/_cdecl/cdecl, or __stdcall/_stdcall/stdcall. The calling convention can include up to two leading underscores.

The parameter list is a comma-delimited list of:

[attributes] type paramname

The type can be any previously declared type or built-in type, a pointer to any type, or a pointer to a built-in type. Attributes on parameters are:

in, out, optional

If optional is used, the types of those parameters must be VARIANT or VARIANT *.

Example

[uuid(. . .),

    helpstring("This is not GDI.EXE"), helpcontext(190),

    dllname("MATH.DLL")]

module somemodule{

    [helpstring("Color for the frame")] unsigned long const COLOR_FRAME

        = 0xH80000006;

    [helpstring("Not a rectangle but a square"), entry(1)] pascal double square([in] double x);

};

Remarks

The module statement defines a group of functions, typically a set of DLL entry points. The header file (.H) output for modules is a series of function prototypes. The module keyword and surrounding brackets are stripped from the header (.H) file output, but a comment (// module modulename) is inserted before the prototypes. The keyword extern is inserted before the declarations.

See Also

Generating a Type Library With MIDL, Contents of a Type Library, ODL File Syntax, TYPEFLAGS


ms_union

[..., ms_union, ...] interface-name {...}

interface-name

Specifies the name of the interface.

Example

[ms_union] long procedure (...);

Remarks

The keyword ms_union is used to control the NDR alignment of nonencapsulated unions.

The MIDL compiler in this version of Microsoft RPC mirrors the behavior of the OSF DCE IDL compiler for nonencapsulated unions. However, because earlier versions of the MIDL compiler did not do so, the /ms_union switch provides compatibility with interfaces built on previous versions of the MIDL compiler.

The ms_union feature can be used as an IDL interface attribute, an IDL type attribute, or as a command-line switch (/ms_union).

See Also

IDL, /ms_union


ncacn_at_dsp

endpoint(“ncacn_at_dsp:[port-name]”)

port-name

Specifies a character string up to 22 bytes long.

Example

[   uuid(12345678-4000-2006-0000-20000000001a),

    version(1.1),

    endpoint("ncacn_at_dsp:[my_services_endpoint]")

]

Remarks

The ncacn_at_dsp keyword identifies Appletalk DSP as the protocol family for the endpoint.

The syntax of the Appletalk DSP port string, like all port strings, is defined by the transport implementation and is independent of the IDL specification. The MIDL compiler performs limited syntax checking but does not guarantee that the endpoint specification is correct. Some classes of errors may be reported at run time rather than compile time.

See Also

endpoint, IDL, string_binding


ncacn_dnet_nsp

endpoint(“ncacn_dnet_nsp:server-name[port-name]”)

server-name

Specifies the name or internet address for the server, or host, computer. The name is a character string.

port-name

Specifies a DECnet object name or object number. The object name can consist of up to 16 characters. Object numbers can be prefixed by the pound sign (#).

Examples

[   uuid(12345678-4000-2006-0000-20000000001a),

    version(1.1),

    endpoint("ncacn_dnet_nsp:node[RPC0034501]")

[   uuid(12345678-4000-2006-0000-20000000001a),

    version(1.1),

    endpoint("ncacn_dnet_nsp:node[#41]")

]

Remarks

The ncacn_dnet_nsp keyword identifies DECnet as the protocol family for the endpoint.

The syntax of the DECnet transport port string, like all port strings, is defined independently of the IDL specification. The compiler performs some syntax checking but does not guarantee that the endpoint specification is correct. Some errors may be reported at run time.

See Also

endpoint, string_binding


ncacn_ip_tcp

endpoint(“ncacn_ip_tcp:server-name[port-name]”)

server-name

Specifies the name or Internet address for the server, or host, computer. The name is a character string. The Internet address is a common Internet address notation.

port-name

Specifies an optional 16-bit number. Values of less than 1024 are usually reserved. If no value is specified, the endpoint-mapping service selects a valid port-name value.

Example

[   uuid(12345678-4000-2006-0000-20000000001a),

    version(1.1),

    endpoint("ncacn_ip_tcp:rainier[1404]")

] interface foo

endpoint("ncacn_ip_tcp:128.10.2.30[1404]")

Remarks

The ncacn_ip_tcp keyword identifies TCP/IP as the protocol family for the endpoint.

The syntax of the TCP/IP transport port string, like all port strings, is defined independently of the IDL specification. The compiler performs some syntax checking but does not guarantee that the endpoint specification is correct. Some errors may be reported at run time rather than during compilation.

See Also

endpoint, IDL, ncacn_nb_tcp, ncacn_np, ncacn_spx, ncalrpc, string_binding


ncacn_nb_ipx

endpoint(“ncacn_nb_ipx:[port-name]”)

port-name

Specifies an optional 8-bit value ranging from zero to 255. Values of less than 0x20 are reserved. If the port-name value is not specified, the endpoint-mapping service selects the port value.

Example

[   uuid(12345678-4000-2006-0000-20000000001a),

    version(1.1),

    endpoint("ncacn_nb_ipx:[100]")

]

Remarks

The ncacn_nb_ipx keyword identifies NetBIOS over IPX as the protocol family for the endpoint.

The syntax of the NetBIOS port string, like all port strings, is defined by the transport implementation and is independent of the IDL specification. The MIDL compiler performs limited syntax checking but does not guarantee that the endpoint specification is correct. Some classes of errors may be reported at run time rather than compile time.

See Also

endpoint, IDL, ncacn_ip_tcp, ncacn_nb_tcp, ncacn_nb_nb, ncacn_at_dsp, ncacn_spx, ncacn_np, ncalrpc, ncadg_ip_udp, ncadg_ipx, string_binding


ncacn_nb_nb

endpoint(“ncacn_nb_nb:[port-name]”)

port-name

Specifies an optional 8-bit value ranging from zero to 255. Values of less than 0x20 are reserved. If the port-name value is not specified, the endpoint-mapping service selects the port value.

Example

[   uuid(12345678-4000-2006-0000-20000000001a),

    version(1.1),

    endpoint("ncacn_nb_nb:[100]")

]

Remarks

The ncacn_nb_nb keyword identifies NetBEUI over NetBIOS as the protocol family for the endpoint.

The syntax of the NetBIOS port string, like all port strings, is defined by the transport implementation and is independent of the IDL specification. The MIDL compiler performs limited syntax checking but does not guarantee that the endpoint specification is correct. Some classes of errors may be reported at run time rather than during compilation.

See Also

endpoint, IDL, ncacn_ip_tcp, ncacn_nb_tcp, ncacn_np, ncacn_spx, ncalrpc, string_binding


ncacn_nb_tcp

endpoint(“ncacn_nb_tcp:[port-name]”)

port-name

Specifies an optional 8-bit value ranging from zero to 255. Values of less than 0x20 are reserved. If the port-name value is not specified, the endpoint-mapping service selects the port value.

Example

[   uuid(12345678-4000-2006-0000-20000000001a),

    version(1.1),

    endpoint("ncacn_nb_tcp:[100]")

]

Remarks

The ncacn_nb_tcp keyword is used to identify TCP over NetBIOS as the protocol family for the endpoint.

The syntax of the NetBIOS port string, like all port strings, is defined by the transport implementation and is independent of the IDL specification. The MIDL compiler performs limited syntax checking but does not guarantee that the endpoint specification is correct. Some classes of errors may be reported at run time rather than compile time.

See Also

endpoint, IDL, ncacn_ip_tcp, ncacn_nb_nb, ncacn_np, ncacn_spx, ncalrpc, string_binding


ncacn_np

endpoint(“ncacn_np:server-name[\\pipe\\pipe-name]”)

server-name

Optional. Specifies the name of the server. Backslash characters are optional.

pipe-name

Specifies a valid pipe name. A valid pipe name is a string containing identifiers separated by backslash characters. The first identifier must be pipe. Each identifier must be separated by two backslash characters.

Examples

[   uuid(12345678-4000-2006-0000-20000000001a),

    version(1.1),

    endpoint("ncacn_np:[\\pipe\\stove\\hat]")

]

[   uuid(12345678-4000-2006-0000-20000000001b),

    version(1.1),

    endpoint("ncacn_np:\\\\myotherserver[\\pipe\\corncob]")

]

Remarks

The ncacn_np keyword identifies named-pipes as the protocol family for the endpoint.

Note  For Windows 95 platforms, ncacn_np is supported only for client applications.

The syntax of the named-pipe port string, like all port strings, is defined by the transport implementation and is independent of the IDL specification. The MIDL compiler performs limited syntax checking but does not guarantee that the endpoint specification is correct. Some classes of errors may be reported at run time rather than during compilation.

See Also

endpoint, IDL, ncacn_at_dsp, ncacn_dnet_nsp, ncacn_ip_tcp, ncacn_nb_ipx, ncacn_spx, ncacn_nb_nb, ncacn_nb_tcp, ncacn_vns_spp ncalrpc, ncadg_ipx, ncadg_ip_udp, string_binding


ncacn_spx

endpoint(“ncacn_spx:link-address[port-name]”)

link-address

Specifies the host server. This may be either a character string (the server name), or a 20 digit hexadecimal number that consists of the host server’s network address (8 digits)concatenated with the node address (12 digits). See Remarks for instructions on how to obtain the network address and node address. A null string specifies the local computer.

port-name

Specifies an optional 16-bit number that represents the socket address. Values can range from 1 to 65,535. When no value is specified, the endpoint-mapping service selects a valid port-name value.

Example

[   uuid(12345678-4000-2006-0000-20000000001a),

    version(1.1),

    endpoint("ncacn_spx:[1000]")

] interface foo

Remarks

The ncacn_spx keyword identifies SPX as the protocol family for the endpoint.

The syntax of the SPX transport port string, like all port strings, is defined independently of the IDL specification. The compiler performs some syntax checking but does not guarantee that the endpoint specification is correct. Some errors may be reported at run time rather than during compilation.

When using the ncacn_spx transport, the server name is exactly the same as the 32-bit Windows NT name. However, since the names are distributed using Novell protocols, they must conform to the Novell naming conventions. If a server name is not a valid Novell name, servers will not be able to create endpoints with the ncacn_spx transport. The following is a partial list of characters prohibited in Novell server names:

“    *    +    .    /    :    ;    <    =    >    ?    [    ]    \    |

The ncacn_spx transport is not supported by the version of NWLink supplied with MS Client 3.0.

16-bit Windows client applications that use the ncacn_spx transport require that the file NWIPXSPX.DLL be installed in order to run under the Windows NT Windows on Windows (WOW) subsystem. Contact Novell to obtain this file.

Note  To obtain the network and node addresses, use Novell’s comcheck utility, or the Novell-defined API IPXGetInternetAddress. On Windows NT, you can also obtain these addresses with the ipxroute configTo obtain the network and node addresses, use Novell’s comcheck utility, or the Novell-defined API IPXGetInternetAddress. On Windows NT, you can also obtain these addresses with the ipxroute config command.

See Also

endpoint, IDL, ncacn_at_dsp, ncacn_dnet_nsp, ncacn_ip_tcp, ncacn_nb_ipx, ncacn_nb_nb, ncacn_nb_tcp, ncacn_np, ncacn_vns_spp, ncalrpc, ncadg_ipx, ncadg_ip_udp, string_binding


ncacn_vns_spp

endpoint(“ncacn_vns_spp:server-name[port-address]”)

server-name

Specifies the StreetTalk name of the server. The name is of the form item@group@organization. The item can be up to 31 characters long and the group and organization can be up to 15 characters.

port-name

Specifies a Banyan Vines SPP port. The valid range for static endpoints is 250 - 511.

Example

[   uuid( ... ),

    version(1.1),

    endpoint("ncacn_vns_spp:printer@sdkgrp@company[260]")

Remarks

The ncacn_vns_spp keyword identifies Banyan Vines SPP as the protocol family for the endpoint.

The syntax of the Banyan Vines SPP transport port string, like all port strings, is defined independently of the IDL specification. The compiler performs some syntax checking but does not guarantee that the endpoint specification is correct. Some errors may be reported at run time.

In order to use the ncacn_vns_spp transport protocol in distributed applications running on Windows NT, Banyan's Enterprise Client for Windows NT must be installed. After installation, open the Control Panel, choose Configuration and Add, then select “Service | Banyan | RPC services for Banyan”. Support for 16-bit clients (MS-DOS and Windows 3.x) requires appropriate Vines software.

For more information on Enterprise Client for Windows NT and 16-bit Vines software, contact http://WWW.BANYAN.COM or call:

In USA                      1-800-2-BANYAN

In Canada                (905)-855-2971

In Europe                  31-3465-75080

In Asia Pacific          (852) 2821-9700

See Also

endpoint, IDL, ncacn_at_dsp, ncacn_dnet_nsp, ncacn_ip_tcp, ncacn_nb_ipx, ncacn_spx, ncacn_nb_nb, ncacn_nb_tcp, ncacn_np, ncalrpc, ncadg_ipx, ncadg_ip_udp,string_binding


ncadg_ip_udp

endpoint(“ncadg_ip_udp:server-name[port-name]”)

server-name

Specifies the name or internet address for the server, or host, computer. The name is a character string and may be a fully-qualified domain name. The internet address is a common internet address notation.

port-name

Specifies an optional 16-bit number. Values of less than 1024 are usually reserved. If no value is specified, the endpoint-mapping service selects a valid port-name value.

Example

[   uuid(12345678-4000-2006-0000-20000000001a),

    version(1.1),

    endpoint("ncadg_ip_udp:rainier[1404]")

] interface foo

endpoint("ncadg_ip_udp:128.10.2.30[1404]")

Remarks

The ncadg_ip_udp keyword identifies the datagram version of TCP/IP as the protocol family for the endpoint.

The following restrictions apply to the datagram protocols, ncadg_ipx and ncadg_ip_udp:

•	They do not support callbacks. Any functions using the callback attribute will fail.

•	They do not support use of the pipe type constructor.

The syntax of the TCP/IP transport port string, like all port strings, is defined independently of the IDL specification. The compiler performs some syntax checking but does not guarantee that the endpoint specification is correct. Some errors may be reported at run time rather than during compilation.

See Also

endpoint, IDL, ncacn_at_dsp, ncacn_dnet_nsp, ncacn_ip_tcp, ncacn_nb_ipx, ncacn_spx, ncacn_nb_nb, ncacn_nb_tcp, ncacn_np, ncacn_vns_spp, ncalrpc, ncadg_ipx, string_binding


ncadg_ipx

endpoint(“ncadg_ipx:link-address[port-name]”)

link-address

Specifies the host server. This may be either a character string (the server name), or a 20 digit hexadecimal number that consists of the host server’s network address (8 digits)concatenated with the node address (12 digits). See Remarks for instructions on how to obtain the network address and node address. A null string specifies the local computer.

port-name

Specifies an optional 16-bit number that represents the socket address. Values can range from 1 to 65535. When no value is specified, the endpoint-mapping service selects a valid port-name value.

Example

[   uuid(12345678-4000-2006-0000-20000000001a),

    version(1.1),

    endpoint("ncadg_ipx:[1000]")

] interface foo

Remarks

The ncadg_ipx keyword identifies IPX as the protocol family for the endpoint.

The following restrictions apply to the datagram protocols, ncadg_ipx and ncadg_ip_udp:

•	They do not support callbacks. Any functions using the callback attribute will fail.

•	They do not support use of the pipe type constructor.

The syntax of the TCP/IP transport port string, like all port strings, is defined independently of the IDL specification. The compiler performs some syntax checking but does not guarantee that the endpoint specification is correct. Some errors may be reported at run time rather than during compilation.

When using the ncadg_ipx transport, the server name is exactly the same as the 32-bit Windows server name. However, since the names are distributed using Novell protocols, they must conform to the Novell naming conventions. If a server name is not a valid Novell name, servers will not be able to create endpoints with the ncadg_ipx transport. The following is a partial list of characters prohibited in Novell server names:

“    *    +    .    /    :    ;    <    =    >    ?    [    ]    \    |

The ncadg_ipx transport is supported by the version of NWLink supplied with MS Client 3.0.

16-bit Windows client applications that use the ncadg_ipx transport require that the file NWIPXSPX.DLL be installed in order to run under the Windows NT Windows on Windows (WOW) subsystem. Contact Novell to obtain this file.

To obtain the network and node addresses, use Novell’s comcheck utility, or the Novell-defined API IPXGetInternetAddress. On Windows NT, you can also obtain these addresses with the ipxroute config command.

See Also

endpoint, IDL, ncacn_at_dsp, ncacn_dnet_nsp, ncacn_ip_tcp, ncacn_nb_ipx, ncacn_spx, ncacn_nb_nb, ncacn_nb_tcp, ncacn_np, ncacn_vns_spp, ncalrpc, ncadg_ip_udp, string_binding


ncalrpc

endpoint(“ncalrpc:[port-name]”)

port-name

A character string that specifies the communication port (an application, a service, or an instance of a service) that a client uses to make interprocess calls to a server. The string can contain up to 250 characters and should not contain any backslash (\) characters. The computer name must not be used with the ncalrpc keyword.

Example

[   uuid(12345678-4000-2006-0000-20000000001a),

    version(1.1),

    endpoint("ncalrpc:[myapplicationname]")

]

Remarks

The ncalrpc keyword identifies local interprocess communication as the protocol family for the endpoint. This keyword is one of the valid protocol family names that must be used with the endpoint attribute.

The syntax of the local interprocess-communication port string, like all port strings, is defined by the transport implementation and is independent of the IDL specification. The MIDL compiler performs limited syntax checking but does not guarantee that the endpoint specification is correct. Some classes of errors may be reported at run time rather than during compilation.

See Also

endpoint, IDL, ncacn_at_dsp, ncacn_dnet_nsp, ncacn_ip_tcp, ncacn_nb_ipx, ncacn_spx, ncacn_nb_nb, ncacn_nb_tcp, ncacn_np, ncacn_vns_spp, ncadg_ip_udp, ncadg_ipx, string_binding


nocode

[ nocode [ , ACF-interface-attributes ] ] interface interface-name
{
[ include filename-list ; ] ...
[ typedef [type-attribute-list] typename; ] ...

[ [ nocode [ , ACF-function-attributes ] ] function-name (
[ ACF-parameter-attributes ] parameter-name ;
...
);
]
...
}

ACF-interface-attributes

Specifies a list of one or more attributes that apply to the interface as a whole. Valid attributes include either auto_handle or implicit_handle and either code or nocode. When two or more interface attributes are present, they must be separated by commas.

interface-name

Specifies the name of the interface. In DCE-compatibility mode, the interface name must match the name of the interface specified in the IDL file. When you use the MIDL compiler switch /acf, the interface name in the ACF and the interface name in the IDL file can be different.

filename-list

Specifies a list of one or more C-language header filenames, separated by commas. The full filename, including the extension, must be supplied.

type-attribute-list

Specifies a list of one or more attributes, separated by commas, that apply to the specified type. Valid type attributes include allocate.

typename

Specifies a type defined in the IDL file. Type attributes in the ACF can only be applied to types previously defined in the IDL file.

ACF-function-attributes

Specifies attributes that apply to the function as a whole, such as comm_status. Function attributes are enclosed in square brackets. Separate multiple function attributes with commas.

function-name

Specifies the name of the function as defined in the IDL file.

ACF-parameter-attributes

Specifies ACF attributes that apply to a parameter. Note that zero or more attributes can be applied to the parameter. Separate multiple parameter attributes with commas. ACF parameter attributes are enclosed in square brackets.

parameter-name

Specifies a parameter of the function as defined in the IDL file. Each parameter for the function must be specified in the same sequence and using the same name as defined in the IDL file.

Remarks

The nocode attribute can appear in the ACF header, or it can be applied to an individual function.

When the nocode attribute appears in the ACF header, client stub code is not generated for any remote function unless it has the code function attribute. You can override the nocode attribute in the header for an individual function by specifying the code attribute as a function attribute.

When the nocode attribute appears in the function’s attribute list, no client stub code is generated for the function.

Client stub code is not generated when:

•	The ACF header includes the nocode attribute.

•	The nocode attribute is applied to the function.

•	The local attribute applies to the function in the interface file.

Either code or nocode can appear in a function’s attribute list, and the one you choose can appear exactly once.

The nocode attribute is ignored when server stubs are generated. You cannot apply it when generating server stubs in DCE-compatibility mode.

See Also

ACF, code


non-encapsulated_union

typedef [switch_type(switch-type-specifier) [ , type-attr-list ] ] union [ tag ] {
[ case ( limited-expr-list) ]
[ [ field-attribute-list ] ] type-specifier declarator-list ;
[ [ default ]
[ [ field-attribute-list ] ] type-specifier declarator-list ;
]
}

switch-type-specifier

Specifies an integer, character, or enum type or an identifier of such a type.

type-attr-list

Specifies zero or more attributes that apply to the union type. Valid type attributes include handle, transmit_as; the pointer attribute unique, or ptr; and the usage attributes context_handle and ignore. Separate multiple attributes with commas.

tag

Specifies an optional tag.

limited-expr-list

Specifies one or more C-language expressions that are supported by MIDL. Almost all C expressions are supported. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow pre- and post-increment and -decrement operators.

field-attribute-list

Specifies zero or more field attributes that apply to the union member. Valid field attributes include first_is, last_is, length_is, max_is, size_is; the usage attributes string, ignore, and context_handle; the pointer attribute ref, unique, or ptr; and, for members that are themselves unions, the union attribute switch_type. Separate multiple field attributes with commas.

type-specifier

Specifies a base_type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.

declarator-list

Specifies one or more standard C declarators, such as identifiers, pointer declarators, and array declarators. (Function declarators and bit-field declarations are not allowed in unions that are transmitted in remote procedure calls. These declarators are allowed in unions that are not transmitted.) Separate multiple declarators with commas.

Remarks

The nonencapsulated union is indicated by the presence of the type attribute switch_type and the field attribute switch_is.

The shape of unions must be the same across platforms to ensure interconnectivity.

For more information, see switch_is and switch_type.

See Also

field_attributes, IDL, union


nonextensible

[uuid, nonextensible [, optional-attribute-list] interface | dispinterface interface-name {interface-definitions}

Example

library Hello

{

[uuid( . . .), helpstring("A helpful description."),

  oleautomation, dual, nonextensible] interface IHello : IDispatch

    {. . .};

Remarks

By default, OLE Automation assumes that interfaces may add members at run time; that is, it assumes they are extensible. The nonextensible attribute specifies that the IDispatch implementation includes only the properties and methods listed in the interface description and cannot be extended with additional members at run time.

You can apply the nonextensible attribute to either an interface or a dispinterface. However, an interface must also have the dual and oleautomation attributes.

Flags

TYPEFLAG_FNONEXTENSIBLE

See Also

TYPEFLAGS, interface, dispinterface, Generating a Type Library With MIDL, Contents of a Type Library, ODL File Syntax, TYPEFLAGS


non-idempotent

Non-idempotent (at most once) indicates that the remote procedure call cannot be executed more than once because it will return a different value or change a state. Non-idempotent is the default for remote procedure calls.

All non-idempotent calls are executed by the server “at most once”; that is, not at all or exactly once. The protocol used to enforce this is the callback function. Non-idempotent requests require the server to perform a callback when it receives a request from a client about which it has no information. The server makes the callback request by issuing a remote procedure call to the client. When it receives the callback, the server’s boot time and the client’s sequence number are used as the basis of comparison to validate the request. If a match is made, the server executes the original request. Otherwise, the request is ignored.

A non-idempotent call ensures that the data is received and processed at most one time.

See Also

broadcast, callback, idempotent, IDL, maybe


notify

[notify] ... ;

Example

[notify] ProcedureFoo;

Remarks

The notify attribute instructs the MIDL compiler to generate a server stub that contains a call to a specially-named procedure on the server side of the application. This procedure is called the notify procedure. It is called after all the output arguments have been marshalled and any memory associated with the parameters is freed.

The notify attribute is useful to develop applications acquiring resources in the server manager routine. These resources are then freed in the notify procedure after the output parameters are fully marshalled.

The notify procedure name is the name of the remote procedure suffixed by _notify. The notify procedure does not require any parameters and does not return a result. A prototype of this procedure is also generated in the header file. For example, if the IDL file contains the following:

ProcedureFoo [in] short S);

Specify the following in the ACF for MIDL to generate the notify call:

[notify] ProcedureFoo();

The generated code will contain the following call to the notify procedure:

ProcedureFoo_notify();

The header file will contain a prototype:

void ProcedureFoo_notif(void);

See Also

ACF


object

[ object, uuid(string-uuid)[ , interface-attribute-list] ]
 interface interface-name : base-interface

string-uuid

Specifies a UUID string generated by the uuidgen utility. You can enclose the UUID string in quotes, except when you use the MIDL compiler switch /osf.

interface-attribute-list

Specifies other attributes that apply to the interface as a whole.

interface-name

Specifies the name of the interface.

base-interface

Specifies the name of an OLE interface from which this derived interface inherits member functions, status codes, and interface attributes. All OLE interfaces are derived from the IUnknown interface or another OLE interface.

Remarks

The object interface attribute identifies a custom OLE interface. An interface attribute list that does not include the object attribute indicates a DCE RPC interface. An interface attribute list for an OLE interface must include the uuid attribute, but it cannot include the version attribute.

By default, compiling an OLE interface with the MIDL compiler generates the files needed to build a proxy DLL. This DLL contains the code to support the use of the custom OLE interface by both client applications and object servers. However, if the interface attribute list for an OLE interface specifies the local attribute, the MIDL compiler generates only the interface header file.

The MIDL compiler automatically generates an interface data type for an OLE interface. As an alternative, you can use typedef with the interface keyword to explicitly define an interface data type. The interface specification can then use the interface data type in function parameters and return values, struct and union members, and other type declarations. The following example illustrates the use of an automatically generated IStream data type:

[object, uuid (ABCDEFOO-1234-1234-5678-ABCDEF123456)]

    interface IStream : IUnknown{

        typedef IStream * LPSTREAM;

}

In an OLE interface, all the interface member functions are assumed to be virtual functions. A virtual function has an implicit this pointer as the first parameter. The virtual function table contains an entry for each interface member function.

Non-[local] object interface member functions must have a return value of HRESULT or SCODE. (Note that earlier versions of MIDL allowed member functions to return void. However, beginning with MIDL version 3.0, returning void generates a compiler error.) Having a return value of HRESULT or SCODE means that if an exception is generated during a remote call, the generated proxies catch the exception and return the exception code in the return value. If your application can afford to ignore errors that occur during a remote procedure call, you can specify HRESULT as the return type without checking the return value after the call.

If you are recompiling an old application, changing the return types can introduce backward compatibility problems when the server sends the newly introduced result to the client. As an alternative to changing the return type, you can label the function that returns void with the [call_as] attribute, thus making it a local function. Then define a related remote function with the same parameters but with the return type of HRESULT. The local function can raise an exception based on that HRESULT value, if necessary.

The object attribute is not available when you compile using the MIDL compiler /osf switch.

See Also

IDL, iid_is, local, /osf, uuid, version


odl

Remarks

MKTYPLIB required this attribute on ODL interfaces. The MIDL compiler does not require the odl attribute; it is recognized only for compatibility with older ODL files.


oleautomation

[ oleautomation, uuid(string-uuid)[ , interface-attribute-list] ]
 interface interface-name : base-interface

string-uuid

Specifies a UUID string generated by the uuidgen utility.

interface-attribute-list

Specifies other attributes that apply to the interface as a whole.

interface-name

Specifies the name of the interface.

base-interface

Specifies the name of an OLE Automation interface from which this derived interface inherits member functions, status codes, and interface attributes. All OLE Automation interfaces are derived from IUnknown or IDispatch.

Example

library Hello

{

 importlib("stdole32.tlb");

    [

      uuid( . . .),

      helpstring("Application object for the Hello application."),

      oleautomation,

      dual

    ]

    interface IHello : IDispatch

    {. . .}

Remarks

The oleautomation attribute indicates that an interface is compatible with OLE Automation. The parameters and return types specified for its members must be OLE Automation-compatible, as listed in the following table.

Type	Description
boolean	Data item that can have the value TRUE or FALSE. In MIDL, the size corresponds to unsigned char.
unsigned char	8-bit unsigned data item.
double	64-bit IEEE floating-point number.
float	32-bit IEEE floating-point number.
int	Integer whose size is system dependent. On 32-bit platforms, MIDL treats int  as a 32-bit signed integer.
long	32-bit signed integer.
short	16-bit signed integer.
BSTR	Length-prefixed string, as described in the OLE Automation topic BSTR.
CY	(Formerly CURRENCY) 8-byte fixed-point number.
DATE	64-bit floating-point fractional number of days since December 30, 1899.
SCODE	Built-in error type that corresponds to VT_ERROR.
enum	Signed integer, whose size is system-dependent. In remote operations, enum objects are treated as 16-bit unsigned entities. Applying the v1_enum attribute to an enum type definition allows enum objects to be transmitted as 32-bit entities.
IDispatch *	Pointer to IDispatch interface (VT_DISPATCH).
IUnknown *	Pointer to interface that is not derived from IDispatch (VT_UNKNOWN). (Any OLE interface can be represented by its IUnknown interface.)
A parameter is compatible with OLE Automation if its type is an OLE Automation-compatible type, a pointer to an OLE Automation-compatible type, or a SAFEARRAY of an OLE Automation-compatible type.

A return type is compatible with OLE Automation if its type is an HRESULT, SCODE or void. However, MIDL requires that interface methods return either HRESULT or SCODE. Returning void generates a compiler error.

A member is compatible with OLE Automation if its return type and all its parameters are OLE-Automation compatible.

An interface is compatible with OLE Automation if it is derived from IDispatch or IUnknown, it has the oleautomation attribute, and all of its VTBL entries are OLE-Automation compatible. For 32-bit platforms, the calling convention for all methods in the interface must be STDCALL. For 16-bit systems, all methods must have the CDECL calling convention.

Every dispinterface is implicitly OLE Automation-compatible. Therefore you should not use the oleautomation attribute on dispinterfaces.

The oleautomation attribute is not available when you compile using the MIDL compiler /osf switch.

Flags

TYPEFLAG_FOLEAUTOMATION

See Also

ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB, IDL, uuid


optimize

optimize (“optimization-options”)

optimization-options

Specifies the method of marshalling data. Use either “s” for mixed-mode marshalling or “i” for interpreted marshalling.

Examples

optimize ("s") void FasterProcedure(...);

optimize ("i") void SmallerProcedure(...);

{

};

Remarks

The keyword optimize is used to fine-tune the level of gradation for marshalling data.

This version of RPC provides two methods for marshalling data: mixed-mode (“s”) and interpreted (“i”). These methods correspond to the /Os and /Oi command-line switches. The interpreted method marshals data completely offline. While this can reduce the size of the stub considerably, performance can be affected.

If performance is a concern, the mixed-mode method can be the best approach. Mixed-mode allows the MIDL compiler to make the determination between which data will be marshalled inline and which will be marshalled by a call to an offline dynamic-link library. If many procedures use the same data types, a single procedure can be called repeatedly to marshal the data. In this way, data that is most suited to inline marshalling is processed inline while other data can be more efficiently marshalled offline.

Note that the optimize attribute can be used as an interface attribute or as an operation attribute. If it is used as an interface attribute, it sets the default for the entire interface, overriding command-line switches. If, however, it is used as an operation attribute, it affects only that operation, overriding command-line switches and the interface default.

See Also

ACF, /Oi, /Os


optional

return-type func-name([optional [, other-attributes]] param-type param-name)

Example

HRESULT MyFunc([in, optional] VARIANT Param1,

               [out, optional] VARIANT Param2)

Remarks

The optional attribute specifies an optional parameter for a member function. This attribute is valid only if the parameter is of type VARIANT or VARIANT*.

The MIDL compiler accepts the following parameter ordering (from left-to-right):

1.	Required parameters (parameters that do not have the defaultvalue or optional attributes),

2.	optional parameters with or without the defaultvalue attribute,

3.	parameters with the optional attribute and without the defaultvalue attribute,

4.	lcid parameter, if any,

5.	retval parameter

You cannot apply the optional attribute to a parameter that also has the lcid or retval attributes.

See Also

ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


out

[ [function-attribute-list] ] type-specifier [pointer-declarator] function-name(
[ out [ , parameter-attribute-list ] ] type-specifier [declarator]
, ...
);

function-attribute-list

Specifies zero or more attributes that apply to the function. Valid function attributes are callback, local; the pointer attribute ref, unique, or ptr; and the usage attributes string, ignore, and context_handle.

type-specifier

Specifies a base_type, struct, union, or enum type or type identifier. An optional storage specification can precede type-specifier.

pointer-declarator

Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.

function-name

Specifies the name of the remote procedure.

parameter-attribute-list

Specifies zero or more attributes appropriate for a specified parameter type. Parameter attributes with the out attribute can also take the directional attribute out; the field attributes first_is, last_is, length_is, max_is, size_is, and switch_type; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle and string. The usage attribute ignore cannot be used as a parameter attribute. Separate multiple attributes with commas.

declarator

Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see pointers and arrays. The parameter declarator in the function declarator, such as the parameter name, is optional.

Example

void MyFunction([out] short * pcount);

Remarks

The out attribute identifies pointer parameters that are returned from the called procedure to the calling procedure (from the server to the client).

The out attribute indicates that a parameter that acts as a pointer and its associated data in memory are to be passed back from the called procedure to the calling procedure.

The out attribute must be a pointer. DCE IDL compilers require the presence of an explicit * as a pointer declarator in the parameter declaration. Microsoft IDL offers an extension that drops this requirement and allows an array or a previously defined pointer type.

A related attribute, in, indicates that the parameter is passed from the calling procedure to the called procedure. The in and out attributes specify the direction in which the parameters are passed. A parameter can be defined as in-only, out-only, or in, out.

An out-only parameter is assumed to be undefined when the remote procedure is called and memory for the object is allocated by the server. Since top-level pointer/parameters must always point to valid storage, and therefore cannot be null, out cannot be applied to top-level unique or ptr pointers. Parameters that are ref pointers must be either in or in, out parameters.

See Also

in, ref


out_of_line

The DCE IDL keyword out_of_line is not supported in Microsoft RPC.

See Also

IDL


pipe

typedef pipe element-type pipe-declarator;

element-type

Defines the size of a single element in the transfer buffer. The element-type can be a base_type, predefined_type, struct, enum, or type identifier. Several restrictions apply to element-types, as described in Remarks, below.

pipe-declarator

Specifies one or more identifiers or pointers to identifiers. Separate multiple declarators with commas.

Examples

typedef pipe unsigned char UCHAR_PIPE1, UCHAR_PIPE2;

//SIMPLE_STRUCT defined elsewhere

typedef pipe SIMPLE_STRUCT SIMPLE_STRUCT_PIPE;

Remarks

The pipe type constructor makes it possible to transmit an open-ended stream of typed data across a remote procedure call. An in pipe parameter allows the server to pull the data stream from the client during a remote procedure call. An out pipe parameter allows the server to push the data stream back to the client. You supply the client-side routines to push and pull the data stream and to allocate a global buffer for the data. The client and server stub routines marshal and unmarshal data and pass a reference to the buffer back to the application.

The following restrictions apply to pipes:

•	A pipe element cannot be or contain a pointer, a conformant or varying array, a handle, or a context handle. In this (MIDL 3.0) implementation of pipes, a pipe element cannot be or contain a union.

•	You cannot apply the transmit_as, represent_as, wire_marshal, or user_marshal attributes to a pipe type or to the element-type.

•	A pipe type cannot be a member of a structure or union, the target of a pointer, or the base type of an array.

•	A data type declared to be a pipe type can only be used as a parameter of a remote call.

•	You can pass a pipe parameter in either direction by value or by reference (ref pointer). However you cannot apply the ptr attribute to a pipe that is passed by reference. You cannot specify a pipe parameter with a unique or a full pointer, regardless of direction.

•	You cannot use pipes in object interfaces.

•	You cannot apply the idempotent attribute to a routine that has a pipe parameter.

•	You cannot use the serialization attributes, encode and decode with pipes.

•	You cannot use automatic handles, either by default, or with the auto_handle attribute, with pipes.

Note  The MIDL 3.0 compiler supports pipes in /Oi2 mode only.

For more information on implementing routines with pipe parameters, see Pipes in the RPC Programmer’s Guide and Reference.


pointer_default

pointer_default ( ptr | ref | unique )

Example

[uuid(6B29FC40-CA47-1067-B31D-00DD010662DA),

version(3.3),

pointer_default(unique)]

interface dictionary

Remarks

The pointer_default attribute specifies the default pointer attribute for all pointers except top-level pointers that appear in parameter lists. This includes embedded pointers — pointers that appear in structures, unions, and arrays. The pointer_default attribute can also apply to pointers returned by functions.

MIDL generates an error during compilation when you do not supply a pointer attribute in an interface that includes embedded pointers.

The default does not apply to pointers that appear as top-level parameters, such as individual pointers used as function parameters. A pointer attribute must be supplied for these pointers. The default is always overridden when a pointer attribute is supplied. If all pointers are supplied with pointer attributes, the default attribute is ignored.

The pointer_default attribute is an optional attribute in the IDL file. The pointer_default attribute is required only in the interface header when:

•	A parameter with more than one asterisk (*) appears in a function.

•	A structure member or union arm with a pointer declarator does not have a pointer attribute.

•	A function returns a pointer type and does not have a pointer attribute as a function attribute.

If the pointer_default attribute appears in the interface header and is not required, it is ignored.

See Also

interface, pointers, ptr, ref, unique


pointers

MIDL supports three kinds of pointers: reference pointers, unique pointers, and full pointers. These pointers are specified by the pointer attributes ref, unique, and ptr.

A pointer attribute can be applied as a type attribute; as a field attribute that applies to a structure member, union member, or parameter; or as a function attribute that applies to the function return type. The pointer attribute can also appear with the pointer_default keyword.

To allow a pointer parameter to change in value during a remote function, you must provide another level of indirection by supplying multiple pointer declarators. The explicit pointer attribute applied to the parameter affects only the rightmost pointer declarator for the parameter. When there are multiple pointer declarators in a parameter declaration, the other declarators default to the pointer attribute specified by the pointer_default attribute. To apply different pointer attributes to multiple pointer declarators, you must define intermediate types that specify the explicit pointer attributes.

Default Pointer-Attribute Values

When no pointer attribute is associated with a pointer that is a parameter, the pointer is assumed to be a ref pointer.

When no pointer attribute is associated with a pointer that is a member of a structure or union, the MIDL compiler assigns pointer attributes using the following priority rules (1 is highest):

1.	Attributes explicitly applied to the pointer type

2.	Attributes explicitly applied to the pointer parameter or member

3.	Pointer_default attribute in the IDL file that defines the type

4.	Pointer_default attribute in the IDL file that imports the type

5.	Ptr (osf mode); unique (Microsoft RPC default mode)

When the IDL file is compiled in default mode, imported files can inherit pointer attributes from importing files. This feature is not available when you compile using the /osf switch. For more information, see import.

Function Return Types

A pointer returned by a function must be a unique pointer or a full pointer. The MIDL compiler reports an error if a function result is a reference pointer, either explicitly or by default. The returned pointer always indicates new storage.

Functions that return a pointer value can specify a pointer attribute as a function attribute. If a pointer attribute is not present, the function-result pointer uses the value provided as the pointer_default attribute.

Pointer Attributes in Type Definitions

When you specify a pointer attribute at the top level of a typedef statement, the specified attribute is applied to the pointer declarator, as expected. When no pointer attribute is specified, pointer declarators at the top level of a typedef statement inherits the pointer attribute type when used.

DCE IDL does not allow the same pointer attribute to be explicitly applied twice — for example, in both the typedef declaration and the parameter attribute list. When you use the default (Microsoft-extensions) mode of the MIDL compiler, this constraint is relaxed.

See Also

allocate, IDL, import, /osf, pointer_default, ptr, ref, unique


pragma

#pragma midl_echo(“string”)
#pragma token-sequence
#pragma pack (n)
#pragma pack ( [push] [, id] [, n} )
#pragma pack ( [pop] [, id] [, n} )

string

Specifies a string that is inserted into the generated header file. The quotation marks are removed during the insertion process.

token-sequence

Specifies a sequence of tokens that are inserted into the generated header file as part of a #pragma directive without processing by the MIDL compiler.

n

Specifies the current pack size. Valid values are 1, 2, 4, 8, and 16.

id

Specifies the user id.

Examples

/* IDL file */

#pragma midl_echo("#define UNICODE")

cpp_quote("#define __DELAYED_PREPROCESSING__ 1")

#pragma hdrstop

#pragma check_pointer(on)

/* generated header file */

#define UNICODE

#define __DELAYED_PREPROCESSING__ 1

#pragma hdrstop

#pragma check_pointer(on)

Remarks

The #pragma midl_echo directive instructs MIDL to emit the specified string, without the quote characters, into the generated header file.

C-language preprocessing directives that appear in the IDL file are processed by the C compiler’s preprocessor. The #define directives in the IDL file are available during MIDL compilation, although not to the C compiler.

For example, when the preprocessor encounters the directive “#define WINDOWS 4”, the preprocessor replaces all occurrences of “WINDOWS” in the IDL file with “4”. The symbol “WINDOWS” is not available at C-compile time.

To allow the C-preprocessor macro definitions to pass through the MIDL compiler to the C compiler, use the #pragma midl_echo or cpp_quote directive. These directives instruct the MIDL compiler to generate a header file that contains the parameter string with the quotation marks removed. The #pragma midl_echo and cpp_quote directives are equivalent.

The #pragma pack directive is used by the MIDL compiler to control the packing of structures. It overrides the /Zp command-line switch. The pack (n) option sets the current pack size to a specific value: 1, 2, 4, 8, or 16. The pack (push) and pack (pop) options have the following characteristics:

•	The compiler maintains a packing stack. The elements of the packing stack include a pack size and an optional id. The stack is limited only by available memory with the current pack size at the top of the stack.

•	Pack (push) results in the current pack size pushed onto the packing stack. The stack is limited by available memory.

•	Pack (push, n) is the same as pack (push) followed by pack (n).

•	Pack (push, id) also pushes id onto the packing stack along with the pack size.

•	Pack (push, id, n) is the same as pack (push, id) followed by pack (n).

•	Pack (pop) results in popping the packing stack. Unbalanced pops cause warnings and set the current pack size to the command-line value.

•	If pack (pop, id, n) is specified, then n is ignored.

The MIDL compiler places the strings specified in the cpp_quote and pragma directives in the header file in the sequence in which they are specified in the IDL file and relative to other interface components in the IDL file. The strings should usually appear in the interface-body section of the IDL file after all import operations.

The MIDL compiler does not attempt to process #pragma directives that do not start with the prefix “midl_.” Other #pragma directives in the IDL file are passed into the generated header file without changes.

See Also

cpp_quote, IDL, /Zp


propget

[propget [,optional-property-attributes]] return-type func-name( parameters);

Example

 interface InMyFace : IDispatch

    {

      [propget, helpstring("A meaningful comment.")]

      HRESULT Method1([out, retval] int* retval);

      [propput, helpstring("Another meaningful comment.")]

      HRESULT Method1([in] int Value);

     [propget, helpstring("A meaningful comment."), id(1)]

      HRESULT Method2([out, retval] InYourFace** retval);

      [propputref, helpstring("Another meaningful comment."), id(1)]

      HRESULT Method2([in] InYourFace* Point);

    }

Remarks

The propget attribute specifies a property accessor function. The property must have the same name as the function.

A function that has the propget attribute must also have, as its last parameter, a pointer type with the out and retval attributes.

At most, one of propget, propput, and propputref can be specified for a function.

Flags

INVOKE_PROPERTYGET

See Also

TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


propput

[propput [,optional-property-attributes]] return-type func-name( parameters);

Example

 interface InMyFace : IDispatch

    {

      [propget, helpstring("A meaningful comment.")]

      HRESULT Method1([out, retval] int* retval);

      [propput, helpstring("Another meaningful comment.")]

      HRESULT Method1([in] int Value);

    }

Remarks

The propput attribute specifies a property-setting function. The property must have the same name as the function.

A function that has the propput attribute must also have, as its last parameter, a parameter that has the in attribute.

At most, one of propget, propput and propputref can be specified for a function.

Flags

INVOKE_PROPERTYPUT

See Also

TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


propputref

[propputref [,optional-property-attributes]] return-type func-name( parameters);

Example

 interface InMyFace : IDispatch

    {

      [propget, helpstring("A meaningful comment."), id(1)]

      HRESULT Method2([out, retval] InYourFace** retval);

      [propputref, helpstring("Another meaningful comment."), id(1)]

      HRESULT Method2([in] InYourFace* Point);

Remarks

The propputref attribute specifies a property-setting function that uses a reference instead of a value.

A function that has the propputref attribute must also have, as its last parameter, a pointer that has the in attribute.

The property must have the same name as the function. At most, one of propget, propput and propputref attributes can be specified for a function.

Flags

INVOKE_PROPERTYPUTREF

See Also

TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


public

typedef [public] data-type identifier;

Example

typedef [public] long MEMBERID;

Remarks

The public attribute includes an alias declared with the typedef keyword in the type library.

By default, an alias that is declared with typedef and has no other attributes is treated as a #define and is not included in the type library. Using the public attribute ensures that the alias becomes part of the type library.

Note  The MIDL compiler requires that you explicitly apply the public attribute to each typedef that you want public. This is in contrast to MKTYPLIB, which treated as public, every typedef inside of a public interface block.

See Also

interface, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


ptr

pointer_default(ptr)

typedef [ ptr [ , type-attribute-list ] ] type-specifier declarator-list;

typedef struct-or-union-declarator {
[ ptr [ , field-attribute-list ] ] type-specifier declarator-list;
...}

[ ptr [ , function-attribute-list ] ] type-specifier ptr-decl function-name(
[ [ parameter-attribute-list ] ] type-specifier [declarator]
, ...
);
[ [ function-attribute-list ] ] type-specifier [ptr-decl] function-name(
[ ptr [ , parameter-attribute-list ] ] type-specifier [declarator]
, ...
);

type-attribute-list

Specifies one or more attributes that apply to the type. Valid type attributes include handle, switch_type, transmit_as; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle, string, and ignore. Separate multiple attributes with commas.

type-specifier

Specifies a base_type, struct, union, or enum type or type identifier. An optional storage specification can precede type-specifier.

declarator and declarator-list

Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see pointers and arrays. The declarator-list consists of one or more declarators separated by commas. The parameter-name identifier in the function declarator is optional.

struct-or-union-declarator

Specifies a MIDL struct or union declarator.

field-attribute-list

Specifies zero or more field attributes that apply to the structure or union member or function parameter. Valid field attributes include first_is, last_is, length_is, max_is, size_is; the usage attributes string, ignore, and context_handle; the pointer attribute ref, unique, or ptr; and the union attribute switch_type. Separate multiple field attributes with commas.

function-attribute-list

Specifies zero or more attributes that apply to the function. Valid function attributes are callback, local; the pointer attribute ref, unique, or ptr; and the usage attributes string, ignore, and context_handle.

ptr-decl

Specifies at least one pointer declarator to which the ptr attribute applies. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.

function-name

Specifies the name of the remote procedure.

parameter-attribute-list

Consists of zero or more attributes appropriate for the specified parameter type. Parameter attributes can take the directional attributes in and out; the field attributes first_is, last_is, length_is, max_is, size_is, and switch_type; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle and string. The usage attribute ignore cannot be used as a parameter attribute. Separate multiple attributes with commas.

Examples

pointer_default(ptr)

typedef [ptr, string] unsigned char * MY_STRING_TYPE;

[ptr] char * MyFunction([in, out, unique] long * plNumber);

Remarks

The ptr attribute designates a pointer as a full pointer. The full pointer approaches the full functionality of the C-language pointer. The full pointer can have the value NULL and can change during the call from null to non-null. Storage pointed to by full pointers can be reached by other names in the application supporting aliasing and cycles. This functionality requires more overhead during a remote procedure call to identify the data referred to by the pointer, determine whether the value is NULL, and to discover if two pointers point to the same data.

Use full pointers for:

•	Remote return values.

•	Double pointers, when the size of an output parameter is not known.

•	NULL pointers.

Full (and unique) pointers cannot be used to describe the size of an array or union because these pointers can have the value NULL. This restriction by MIDL prevents an error that can result when a NULL value is used as the size.

Reference and unique pointers are assumed to cause no aliasing of data. A directed graph obtained by starting from a unique or reference pointer and following only unique or reference pointers contains neither reconvergence nor cycles.

To avoid aliasing, all pointer values should be obtained from an input pointer of the same class of pointer. If more than one pointer points to the same memory location, all such pointers must be full pointers.

In some cases, full and unique pointers can be mixed. A full pointer can be assigned the value of a unique pointer, as long as the assignment does not violate the restrictions on changing the value of a unique pointer. However, when you assign a unique pointer the value of a full pointer, you may cause aliasing.

Mixing full and unique pointers can cause aliasing, as demonstrated in the following example:

typedef struct {

    [ptr] short * pdata;          // full pointer

} GRAPH_NODE_TYPE;

typedef struct {

    [unique] graph_node * left;   // unique pointer

    [unique] graph_node * right;  // unique pointer

} TREE_NODE_TYPE;

// application code:

short a = 5;

TREE_NODE_TYPE * t;

GRAPH_NODE_TYPE g, h;

g.pdata = h.pdata = &a;

t->left = &g;

t->right = &h;

// t->left->pdata == t->right->pdata == &a

Although “t->left” and “t->right” point to unique memory locations, “t->left->pdata” and “t->right->pdata” are aliased. For this reason, aliasing-support algorithms must follow all pointers (including unique and reference pointers) that may eventually reach a full pointer.

See Also

IDL, pointer_default, pointers, ref, unique


readonly

[readonly [, optional-attributes]] data-type identifier

Example

HRESULT Method3([in, readonly] int iMmutable);

Remarks

The readonly attribute prohibits assignment to a variable.

Flags

VARFLAG_FREADONLY

See Also

TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


ref

pointer_default(ref)

typedef [ ref [ , type-attribute-list ] ] type-specifier declarator-list;

typedef struct-or-union-declarator {
[ ref [ , field-attribute-list ] ] type-specifier declarator-list;
...}

[ [ function-attribute-list ] ] type-specifier [ptr-decl] function-name(
[ ref [ , parameter-attribute-list ] ] type-specifier [declarator]
, ...
);

type-attribute-list

Specifies one or more attributes that apply to the type. Valid type attributes include handle, switch_type, transmit_as; the pointer attributes ref, unique, or ptr; and the usage attributes context_handle, string, and ignore. Separate multiple attributes with commas.

type-specifier

Specifies a base_type, struct, union, or enum type or type identifier. An optional storage specification can precede type-specifier.

declarator and declarator-list

Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see pointers and arrays. The declarator-list consists of one or more declarators separated by commas. The parameter-name identifier in the function declarator is optional.

struct-or-union-declarator

Specifies a MIDL struct or union declarator.

field-attribute-list

Specifies zero or more field attributes that apply to the structure, union member, or function parameter. Valid field attributes include first_is, last_is, length_is, max_is, size_is; the usage attributes string, ignore, and context_handle; the pointer attribute ref, unique, or ptr; and the union attribute switch_type. Separate multiple field attributes with commas.

function-attribute-list

Specifies zero or more attributes that apply to the function. Valid function attributes are callback, local; the pointer attribute ref, unique, or ptr; and the usage attributes string, ignore, and context_handle.

ptr-decl

Specifies at least one pointer declarator to which the ref attribute applies. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.

function-name

Specifies the name of the remote procedure.

parameter-attribute-list

Consists of zero or more attributes appropriate for the specified parameter type. Parameter attributes can take the directional attributes in and out; the field attributes first_is, last_is, length_is, max_is, size_is, and switch_type; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle and string. The usage attribute ignore cannot be used as a parameter attribute. Separate multiple attributes with commas.

Example

[unique] char * GetFirstName(

    [in, ref] char * pszFullName

);

Remarks

The ref attribute identifies a reference pointer. It is used simply to represent a level of indirection.

A pointer attribute can be applied as a type attribute, as a field attribute that applies to a structure member, union member, or parameter; or as a function attribute that applies to the function return type. The pointer attribute can also appear with the pointer_default keyword.

A reference pointer has the following characteristics:

•	Always points to valid storage; never has the value NULL. A reference pointer can always be dereferenced.

•	Never changes during a call. A reference pointer always points to the same storage on the client before and after the call.

•	Does not allocate new memory on the client. Data returned from the server is written into existing storage specified by the value of the reference pointer before the call.

•	Does not cause aliasing. Storage pointed to by a reference pointer cannot be reached from any other name in the function.

A reference pointer cannot be used as the type of a pointer returned by a function.

If no attribute is specified for a top-level pointer parameter, it is treated as a reference pointer.

See Also

pointers, ptr, unique


represent_as

typedef [represent_as(repr-type) [ , type-attribute-list ] ]
named-type;

void __RPC_USER named-type_from_local (
repr-type __RPC_FAR * ,
named-type __RPC_FAR * __RPC_FAR * );

void __RPC_USER named-type_to_local (
named-type __RPC_FAR * ,
repr-type __RPC_FAR * );

void __RPC_USER named-type_free_inst (
named-type __RPC_FAR * );

void __RPC_USER named-type_free_local (
repr-type__RPC_FAR * );

named-type

Specifies the named transfer data type that is transferred between client and server.

type-attribute-list

Specifies one or more attributes that apply to the type. Separate multiple attributes with commas.

repr-type

Specifies the represented local type in the target language that is presented to the client and server applications.

Example

//these data types defined in .IDL or elsewhere

typedef struct  _lbox {

    long         data;

    struct _lbox *next;

} lbox;

typedef [ref] lbox *PBOX_LOC;

typedef long LONG4[4];

//in .ACF file :

interfaceFoo

{

typedef  [ represent_as(PBOX_LOC) ]  LONG4;

}

Remarks

The represent_as attribute associates a named local type in the target language repr-type with a transfer type named-type that is transferred between client and server. You must supply routines that convert between the local and the transfer types and that free memory used to hold the converted data. The represent_as attribute instructs the stubs to call the user-supplied conversion routines.

The transferred type named-type must resolve to a MIDL base type, predefined type, or to a type identifier. For more information, see base_types.

You must supply the following routines:

Routine name	Description
named_type_from_local	Allocates an instance of the network type and converts from the local type to the network type
named_type_to_local	Converts from the network type to the local type
named_type_free_local	Frees memory allocated by a call to the named_type_to_local routine, but not the type itself
named_type_free_inst	Frees storage for the network type (both sides)
The client stub calls named-type_from_local to allocate space for the transmitted type and to translate the data from the local type to the network type. The server stub allocates space for the original data type and calls named-type_to_local to translate the data from the network type to the local type.

Upon return from the application code, the client and server stubs call named-type_free_inst to deallocate the storage for network type. The client stub calls named-type_free_local to deallocate storage returned by the routine.

The following types cannot have a represent_as attribute:

•	Conformant, varying, or conformant varying arrays.

•	Structures in which the last member is a conformant array (a conformant structure).

•	Pointers or types that contain a pointer.

•	Predefined types handle_t, void.

•	A type cannot have both the represent_as attribute and the handle attribute.

See Also

ACF, arrays, base_types, typedef


requestedit

[requestedit [,optional-attributes]] return-type function-name(params)

Example

properties:

 [propget, helpstring("A useful comment"), bindable, defaultbind,

     displaybind, requestedit] long Func1(void);

Remarks

The requestedit attribute indicates that the property supports the OnRequestEdit notification. This means that, before a change is made, the object will send the client a request for permission to change a property. An object can support data binding but not have this attribute.

Flags

FUNCFLAG_FREQUESTEDIT, VARFLAG_FREQUESTEDIT

See Also

TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


restricted

[restricted[, other-attributes]]
statement-type statement-name {definitions};

Examples

[uuid(. . .), version (1.0), restricted] library UCantTouchThis

{. . .};

[propget, restricted] HRESULT DontTouch(void);

Remarks

The restricted attribute specifies that a library, or member of a module, interface, or dispinterface cannot be called arbitrarily. For example, this prevents a data item from being used by a macro programmer. You can apply this attribute to a member of a coclass, independent of whether the member is a dispinterface or interface, and independent of whether the member is a sink (incoming) or source (outgoing). A member of a coclass cannot have both the restricted and default attributes.

Flags

IMPLTYPEFLAG_FRESTRICTED, FUNCFLAG_FRESTRICTED

See Also

TYPEFLAGS, library, interface, dispinterface, module, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


retval

return-type function-name([out, retval
                                     [, optional-attributes]] data-type * retval)

Examples

HRESULT MyMethod([out, retval] InMyFace** retval);

HRESULT MyOtherMethod([out, retval] boolean* retval);

Remarks

The retval attribute designates the parameter that receives the return value of the member. You can use this atttribute on parameters of interface members that describe methods or get properties. (The attribute is required on the last parameter of a method that has the propget attribute.) Note that the parameter takes the name of the attribute. The parameter must have the out attribute and must be a pointer type.

You cannot apply the optional attribute to a retval parameter.

The MIDL compiler accepts the following parameter ordering (from left-to-right):

1.	Required parameters (parameters that do not have the defaultvalue or optional attributes),

2.	optional parameters with or without the defaultvalue attribute,

3.	parameters with the optional attribute and without the defaultvalue attribute,

4.	lcid parameter, if any,

5.	retval parameter

Parameters with the retval attribute are not displayed in user-oriented browsers.

Flags

IDLFLAG_FRETVAL

See Also

TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


shape

The DCE IDL keyword shape is not supported in Microsoft RPC.

See Also

IDL


short

The short keyword designates a 16-bit integer. The short keyword can be preceded by either the keyword signed or the keyword unsigned. The int keyword is optional and can be omitted. To the MIDL compiler, a short integer is signed by default and is synonymous with signed short int.

The short integer type is one of the base types of the IDL language. The short integer type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function-return-type specifier and a parameter-type specifier). For the context in which type specifiers appear, see IDL.

See Also

base_types, IDL, int, long, small


signed

The signed keyword indicates that the most significant bit of an integer variable represents a sign bit rather than a data bit. This keyword is optional and can be used with any of the character and integer types char, wchar_t, long, short, and small.

When you use the MIDL compiler switch char, character and integer types that appear in the IDL file without explicit sign keywords can appear with the signed or unsigned keywords in the generated header file.  To avoid confusion, explicitly specify the sign of the integer and character types.

See Also

base_types, IDL, int, long, short, small, unsigned


size_is

[ size_is(limited-expression-list) ]

limited-expression-list

Specifies one or more C-language expressions. Each expression evaluates to a non-negative integer that represents the amount of memory allocated to a sized pointer or an array. In the case of an array, specifies a single expression that represents the maximum allocation size, in elements, of the first dimension of that array. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators. Use commas as placeholders for implicit parameters, or to separate multiple expressions.

Examples

void Proc1(

    [in, short] m;

    [in, size_is(m)] short a[]);  // if m = 10, a[10]

void Proc2(

    [in, short] m;

    [in, size_is(m)] short b[][20]);  // if m = 10, b[10][20]

void Proc3(

    [in, short] m;

    [size_is(m)] short * pshort); //specifies a pointer

                      // to an m-sized block of shorts

void Proc4(

    [in, short] m;

    [size_is(,m)] short ** ppshort); /*specifies a pointer

                               to a pointer to an m-sized

                                       block of shorts */

void Proc5(

    [in, short] m;

    [size_is(m,)] short ** ppshort); /*specifies an

            m-sized block of pointers to shorts */

void Proc6(

    [in, short] m;

    [in, short] n;

    [size_is(m,n)] short ** ppshort); /* specifies a

            pointer to an m-sized block of pointers,

                 each of which points to an n-sized

                                  block of shorts.*/

Remarks

You can use the size_is attribute to specify the size of memory allocated for sized pointers, sized pointers to sized pointers, and single- or multi-dimensional arrays. However, if you are using array [ ] notation, only the first dimension of a multi-dimensional array can be determined at run time.

For more information on using the size_is attribute with multiple levels of pointers to enable a server to return a dynamically-sized array of data to a client, see Multiple Levels of Pointers.

You can use either size_is or max_is (but not both in the same attribute list) to specify the size of an array whose upper bounds are determined at run time. Note, however, that the size_is attribute cannot be used on array dimensions that are fixed. The max_is attribute specifies the maximum valid array index. As a result, specifying size_is(n) is equivalent to specifying max_is(n-1).

An in or in, out conformant-array parameter with the string attribute need not have the size_is or max_is attribute. In this case, the size of the allocation is determined from the null terminator of the input string. All other conformant arrays with the string attribute must have a size_is or max_is attribute.

While it is legal to use the size_is attribute with a constant, doing so is inefficient and unnecessary. For example, use a fixed size array:

void Proc3([in] short Arr[MAX_SIZE]);

instead of:

// legal but marshalling code is much slower

void Proc3([in size_is(MAX_SIZE)] short Arr[] );

See Also

arrays, field_attributes, first_is, IDL, last_is, length_is, max_is, min_is


small

The small keyword designates an 8-bit integer number. The small keyword can be preceded by either the keyword signed or the keyword unsigned. The int keyword is optional and can be omitted. To the MIDL compiler, a small integer is signed by default and is synonymous with signed small int.

The small integer type is one of the base types of the IDL language. The small integer type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function-return-type specifier and as a parameter-type specifier). For the context in which type specifiers appear, see IDL.

The sign of the small type can be modified by the MIDL compiler switch /char. To avoid confusion, specify the sign of the integer type with the keywords signed and unsigned.

See Also

/char, int, long, short


source

[source [, optional-attributes]] statement-type statement-name {definitions};

Example

[default, source] dispinterface DIMyFaceAdviseSink;

[source]interface IMyFaceAdviseSink;

Remarks

The source attribute indicates that a member of a coclass, property, or method is a source of events. For a member of a coclass, this attribute means that the member is called rather than implemented.

On a property or method, the source attribute indicates that the member returns an object or VARIANT that is a source of events. The object implements IConnectionPointContainer.

Flags

IMPLTYPEFLAG_FSOURCE, VARFLAG_SOURCE, FUNCFLAG_SOURCE

See Also

TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


string

typedef [ string [ , type-attribute-list ] ] type-specifier declarator-list;

typedef struct-or-union-declarator {
[ string [ , field-attribute-list ] ] type-specifier declarator-list;
...}

[ string [ , function-attribute-list ] ] type-specifier ptr-decl function-name(
[ [ parameter-attribute-list ] ] type-specifier [declarator]
, ...
);
[ [ function-attribute-list ] ] type-specifier [ptr-decl] function-name(
[ string [ , parameter-attribute-list ] ] type-specifier [declarator]
, ...
);

type-attribute-list

Specifies one or more attributes that apply to a type. Valid type attributes include handle, switch_type, transmit_as; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle, string, and ignore. Separate multiple attributes with commas.

type-specifier

Specifies a base_type, struct, union, or enum type or type identifier. An optional storage specification can precede type-specifier.

declarator and declarator-list

Specify standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see pointers and arrays. The declarator-list consists of one or more declarators separated by commas. The parameter-name identifier in the function declarator is optional.

struct-or-union-declarator

Specifies a MIDL struct or union declarator.

field-attribute-list

Specifies zero or more field attributes that apply to the structure, union member, or function parameter. Valid field attributes include first_is, last_is, length_is, max_is, size_is; the usage attributes string, ignore, and context_handle, the pointer attribute ref, unique, or ptr, and the union attribute switch_type. Separate multiple field attributes with commas.

function-attribute-list

Specifies zero or more attributes that apply to the function. Valid function attributes are callback, local; the pointer attribute ref, unique, or ptr; and the usage attributes string, ignore, and context_handle.

ptr-decl

Specifies an optional pointer declarator to which the string attribute applies. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.

function-name

Specifies the name of the remote procedure.

parameter-attribute-list

Consists of zero or more attributes appropriate for the specified parameter type. Parameter attributes can take the directional attributes in and out; the field attributes first_is, last_is, length_is, max_is, size_is, and switch_type; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle and string. The usage attribute ignore cannot be used as a parameter attribute. Separate multiple attributes with commas.

Example

/* a string type that can hold up to 80 characters */

typedef [string] char line[81];

void Proc1([in, string] char * pszName);

Remarks

The string attribute indicates that the one-dimensional char, wchar_t, byte (or equivalent) array or the pointer to such an array must be treated as a string.

The string can also be an array (or a pointer to an array) of constructs whose fields are all of the type “byte.”

If the string attribute is used with an array whose bounds are determined at run time, you must also specify a size_is or max_is attribute.

The string attribute cannot be used with attributes that specify the range of transmitted elements, such as first_is, last_is, and length_is.

When used on multidimensional arrays, the string attribute applies to the rightmost array.

To define a counted string, do not use the string attribute. Use a character array or character-based pointer such as the following:

typedef struct {

    unsigned short size;

    unsigned short length;

    [size_is(size), length_is(length)] char string[*];

} counted_string;

The string attribute specifies that the stub should use a language-supplied method to determine the length of strings.

When declaring strings in C, you must allocate space for an extra character that marks the end of the string.

See Also

arrays, char, wchar_t


struct

struct [ struct-tag ] {
[ [ field-attribute-list ] ] type-specifier declarator-list;
...
}

struct-tag

Specifies an optional tag for the structure.

field-attribute-list

Specifies zero or more field attributes that apply to the structure member. Valid field attributes include first_is, last_is, length_is, max_is, size_is; the usage attributes string, ignore, and context_handle; the pointer attribute ref, unique, or ptr; and the union attribute switch_type. Separate multiple field attributes with commas.

type-specifier

Specifies a base_type, struct, union, or enum type or type identifier. An optional storage specification can precede type-specifier.

declarator-list

Specifies one or more standard C declarators, such as identifiers, pointer declarators, and array declarators. (Function declarators and bit-field declarations are not allowed in structures that are transmitted in remote procedure calls. These declarators are allowed in structures that are not transmitted.) Separate multiple declarators with commas.

Example

typedef struct _PITCHER_RECORD_TYPE {

    short flag;

    [switch_is(flag)] union PITCHER_STATISTICS_TYPE p;

} PITCHER_RECORD_TYPE;

Remarks

The struct keyword is used in a structure type specifier. The IDL structure type specifier differs from the standard C type specifier in the following ways:

•	Each structure member can be associated with optional field attributes that describe characteristics of that structure member for the purposes of a remote procedure call.

•	Bit fields and function declarators are not allowed in structures that are used in remote procedure calls. These standard C declarator constructs can be used only if the structure is not transmitted on the network.

The shape of structures must be the same across platforms to ensure interconnectivity.

See Also

arrays, base_types, /c_ext, IDL, /osf, pointers


switch

switch (switch-type switch-name)

switch-type

Specifies an int, char, enum type, or an identifier that resolves to one of these types.

switch-name

Specifies the name of the variable of type switch-type that acts as the union discriminant.

Examples

typedef union _S1_TYPE switch (long l1) U1_TYPE {

    case 1024:

        float f1;

    case 2048:

        double d2;

} S1_TYPE;

/* in generated header file */

typedef struct _S1_TYPE {

    long l1;

    union {

        float f1;

        double d2;

    } U1_TYPE;

} S1_TYPE;

Remarks

The switch keyword selects the discriminant for an encapsulated_union.

See Also

IDL, non-encapsulated_union, switch_is, switch_type, union


switch_is

typedef struct [ struct-tag ] {
[ switch_is(limited-expr) [ , field-attr-list ] ] union-type-specifier declarator;
...
}

[ [function-attribute-list] ] type-specifier [pointer-declarator] function-name(
[ switch_is(limited-expr) [ , param-attr-list ] ] union-type [declarator]
, ...
);

struct-tag

Specifies an optional tag for a structure.

limited-expr

Specifies a C-language expression supported by MIDL. Almost all C-language expressions are supported. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow pre- and post-increment and -decrement operators.

field-attr-list

Specifies zero or more field attributes that apply to a union member. Valid field attributes include first_is, last_is, length_is, max_is, size_is; the usage attributes string, ignore, and context_handle; the pointer attribute ref, unique, or ptr; and for members that are themselves unions, the union attribute switch_type. Separate multiple field attributes with commas.

union-type-specifier

Specifies the union type identifier. An optional storage specification can precede type-specifier.

declarator and declarator-list

Specifies a standard C declarator, such as an identifier, pointer declarator, and array declarator. (Function declarators and bit-field declarations are not allowed in unions that are transmitted in remote procedure calls. These declarators are allowed in unions that are not transmitted.) Separate multiple declarators with commas.

function-attribute-list

Specifies zero or more attributes that apply to the function. Valid function attributes are callback, local; the pointer attribute ref, unique, or ptr; and the usage attributes string, ignore, and context_handle.

type-specifier

Specifies a base_type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.

pointer-declarator

Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.

function-name

Specifies the name of the remote procedure.

param-attr-list

Specifies zero or more attributes appropriate for the specified parameter type. Parameter attributes can take the directional attributes in and out, the field attributes first_is, last_is, length_is, max_is, size_is, and switch_type; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle and string. The usage attribute ignore cannot be used as a parameter attribute. Separate multiple attributes with commas.

union-type

Identifies the union type specifier.

Examples

typedef [switch_type(short)] union _WILLIE_UNION_TYPE {

    [case(24)]

        float fMays;

    [case(25)]

        double dMcCovey;

    [default]

        ;

} WILLIE_UNION_TYPE;

typedef struct _WINNER_TYPE {

    [switch_is(sUniformNumber)] union WILLIE_UNION_TYPE w;

    short sUniformNumber;

} WINNER_TYPE;

Remarks

The switch_is attribute specifies the expression or identifier acting as the union discriminant that selects the union member. The discriminant associated with the switch_is attribute must be defined at the same logical level as the union:

•	When the union is a parameter, the union discriminant must be another parameter.

•	When the union is a field of a structure, the discriminant must be another field of the same structure.

The sequence in a structure or a function parameter list is not significant. The union can either precede or follow the discriminant.

The switch_is attribute can appear as a field attribute or as a parameter attribute.

See Also

encapsulated_union, non-encapsulated_union, switch_type, union


switch_type

switch_type(switch-type-specifier)

switch-type-specifier

Specifies an integer, character, boolean, or enum type, or an identifier of such a type.

Examples

typedef [switch_type(short)] union _WILLIE_UNION_TYPE {

    [case(24)]

        float fMays;

    [case(25)]

        double dMcCovey;

    [default]

        ;

} WILLIE_UNION_TYPE;

typedef struct _WINNER_TYPE {

    [switch_is(sUniformNumber)] union WILLIE_UNION_TYPE w;

    short sUniformNumber;

} WINNER_TYPE;

Remarks

The switch_type attribute identifies the type of the variable used as the union discriminant. The switch type can be an integer, character, boolean, or enum type.

The switch_is attribute specifies the name of the parameter that is the union discriminant. The switch_is attribute applies to parameters or members of structures or unions.

The union and its discriminant must be specified at the same logical level. When the union is a parameter, the union discriminant must be another parameter. When the union is a field of a structure, the discriminant must be another field of the structure at the same level as the union field.

See Also

encapsulated_union, IDL, non-encapsulated_union, switch_is, union


transmit_as

typedef [transmit_as(xmit-type) [ , type-attribute-list ] ]
type-specifier declarator-list;

void __RPC_USER type-id_to_xmit (
type-id __RPC_FAR *,
xmit-type __RPC_FAR * __RPC_FAR *);

void __RPC_USER type-id_from_xmit (
xmit-type __RPC_FAR *,
type-id __RPC_FAR *);

void __RPC_USER type-id_free_inst (
type-id __RPC_FAR *);

void __RPC_USER type-id_free_xmit (
xmit-type__RPC_FAR *);

xmit-type

Specifies the data type that is transmitted between client and server.

type-attribute-list

Specifies one or more attributes that apply to the type. Valid type attributes include handle, switch_type; the pointer attribute ref, unique, or ptr; and the usage attributes string and ignore. Separate multiple attributes with commas.

type-specifier

Specifies a base_type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.

declarator-list

Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see pointers and arrays. The declarator-list consists of one or more declarators separated by commas. The parameter declarator in the function declarator, such as the parameter name, is optional.

type-id

Specifies the name of the data type that is presented to the client and server applications.

Examples

typedef struct _TREE_NODE_TYPE {

    unsigned short data;

    struct _TREE_NODE_TYPE * left;

    struct _TREE_NODE_TYPE * right;

} TREE_NODE_TYPE;

typedef [transmit_as(TREE_XMIT_TYPE)] TREE_NODE_TYPE * TREE_TYPE;

void __RPC_USER TREE_TYPE_to_xmit(

    TREE_TYPE __RPC_FAR * ,

    TREE_XMIT_TYPE __RPC_FAR * __RPC_FAR *);

void __RPC_USER TREE_TYPE_from_xmit (

    TREE_XMIT_TYPE __RPC_FAR *,

    TREE_TYPE __RPC_FAR *);

void __RPC_USER TREE_TYPE_free_inst(

    TREE_TYPE __RPC_FAR *);

void __RPC_USER TREE_TYPE_free_xmit(

    TREE_XMIT_TYPE __RPC_FAR *);

Remarks

The transmit_as attribute instructs the compiler to associate type-id, a presented type that client and server applications manipulate, with a transmitted type xmit-type. The user must supply routines that convert data between the presented and the transmitted types; these routines must also free memory used to hold the converted data. The transmit_as attribute instructs the stubs to call the user-supplied conversion routines.

The transmitted type xmit-type must resolve to a MIDL base type, predefined type, or a type identifier. For more information, see base_types.

The user must supply the following routines:

Routine name	Description
type-id_to_xmit	Converts data from the presented type to the transmitted type
type-id_from_xmit	Converts data from the transmitted type to the presented type
type-id_free_inst	Frees storage used by the callee for the presented type
type-id_free_xmit	Frees storage used by the caller for the transmitted type
The client stub calls type-id_to_xmit to allocate space for the transmitted type and to translate the data into objects of type xmit-type. The server stub allocates space for the original data type and calls type-id_from_xmit to translate the data from its transmitted type to the presented type.

Upon return from the application code, the server stub calls type-id_free_inst to deallocate the storage for type-id on the server side. The client stub calls type-id_free_xmit to deallocate the xmit-type storage on the client side.

The following types cannot have a transmit_as attribute:

•	Context handles (types with the context_handle type attribute and types that are used as parameters with the context_handle attribute)

•	Parameters that are conformant, varying, or open arrays

•	Structures that contain conformant arrays

•	The predefined type handle_t, void

When a pointer attribute appears as one of the type attributes with the transmit_as attribute, the pointer attribute is applied to the xmit_type parameter of the type-id-to_xmit and type-id-from_xmit routines.

See Also

arrays, base_types, context_handle, IDL, typedef


typedef

/* IDL file typedef syntax */
typedef [ [ idl-type-attribute-list ] ] type-specifier declarator-list;

/* ACF typedef syntax */
typedef [ acf-type-attribute-list ] typename;

idl-type-attribute-list

Specifies one or more attributes that apply to the type. Valid type attributes in an IDL file include handle, switch_type, transmit_as; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle, string, and ignore. Separate multiple attributes with commas.

type-specifier

Specifies a base_type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier. The const keyword can precede type-specifier.

declarator-list

Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see pointers and arrays. The declarator-list consists of one or more declarators, separated by commas.

acf-type-attribute-list

Specifies one or more attributes that apply to the type. Valid type attributes in an ACF include allocate, encode, and decode.

typename

Specifies a type defined in the IDL file.

Remarks

The IDL typedef keyword allows typedef declarations that are very similar to C-language typedef declarations. The IDL typedef declaration is augmented to allow you to associate type attributes with the defined types. Valid type attributes include handle, switch_type, transmit_as; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle, string, and ignore.

The typedef keyword in an ACF applies attributes to types that are defined in the corresponding IDL file. For example, the allocate type attribute allows you to customize memory allocation and deallocation by both the application and the stubs.

The ACF typedef statement appears as part of the ACF_body. Note that the ACF typedef syntax is different from the IDL typedef syntax and the C-language typedef syntax. No new types can be introduced in the ACF.

See Also

ACF, allocate, decode, encode, IDL


union

The union keyword appears in functions that relate to discriminated unions.

MIDL supports two types of discriminated unions: encapsulated unions and nonencapsulated unions. The encapsulated union is compatible with previous implementations of RPC (NCA version 1). The nonencapsulated union eliminates some of the restrictions of the encapsulated union and provides a more visible discriminant than the encapsulated union.

The encapsulated union is identified by the switch keyword and the absence of other union-related keywords.

The nonencapsulated union, also known as a union, is identified by the presence of the switch_is and switch_type keywords, which identify the discriminant and its type.

When you use in, out unions, be aware that changing the value of the union switch during the call can make the remote call behave differently from a local call. On return, the stubs copy the in, out parameter into memory that is already present on the client. When the remote procedure modifies the value of the union switch and consequently changes the data object’s size, the stubs can overwrite valid memory with the out value. When the union switch changes the data object from a base type to a pointer type, the stubs can overwrite valid memory when they copy the pointer referent into the memory location indicated by the in value of a base type.

The shape of unions must be identical across platforms to ensure interconnectivity.

See Also

encapsulated_union, IDL, non-encapsulated_union, switch_is, switch_type


unique

pointer_default(unique)

typedef [ unique [ , type-attribute-list ] ] type-specifier declarator-list;

typedef struct-or-union-declarator {
[ unique [ , field-attribute-list ] ] type-specifier declarator-list;
...}

[ unique [ , function-attribute-list ] ] type-specifier ptr-decl function-name(
[ [ parameter-attribute-list ] ] type-specifier [declarator]
, ...
);
[ [ function-attribute-list ] ] type-specifier [ptr-decl] function-name(
[ unique [ , parameter-attribute-list ] ] type-specifier [declarator]
, ...
);

type-attribute-list

Specifies one or more attributes that apply to the type. Valid type attributes include handle, switch_type, transmit_as; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle, string, and ignore. Separate multiple attributes with commas.

type-specifier

Specifies a base_type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.

declarator and declarator-list

Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see pointers and arrays. The declarator-list consists of one or more declarators separated by commas. The parameter-name identifier in the function declarator is optional.

struct-or-union-declarator

Specifies a MIDL struct or union declarator.

field-attribute-list

Specifies zero or more field attributes that apply to the structure member, union member, or function parameter. Valid field attributes include first_is, last_is, length_is, max_is, size_is; the usage attributes string, ignore, and context_handle; the pointer attribute ref, unique, or ptr; and the union attribute switch_type. Separate multiple field attributes with commas.

function-attribute-list

Specifies zero or more attributes that apply to the function. Valid function attributes are callback, local; the pointer attribute ref, unique, or ptr; and the usage attributes string, ignore, and context_handle.

ptr-decl

Specifies at least one pointer declarator to which the unique attribute applies. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.

function-name

Specifies the name of the remote procedure.

parameter-attribute-list

Consists of zero or more attributes appropriate for the specified parameter type. Parameter attributes can take the directional attributes in and out; the field attributes first_is, last_is, length_is, max_is, size_is, and switch_type; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle and string. The usage attribute ignore cannot be used as a parameter attribute. Separate multiple attributes with commas.

Example

pointer_default(unique)

typedef [unique, string] unsigned char * MY_STRING_TYPE;

[unique] char * MyFunction([in, out, unique] long * plNumber);

Remarks

The unique attribute specifies a unique pointer.

Pointer attributes can be applied as a type attribute; as a field attribute that applies to a structure member, union member, or parameter; or as a function attribute that applies to the function return type. The pointer attribute can also appear with the pointer_default keyword.

A unique pointer has the following characteristics:

•	Can have the value NULL.

•	Can change during a call from NULL to non-null, from non-null to NULL, or from one non-null value to another.

•	Can allocate new memory on the client. When the unique pointer changes from NULL to non-null, data returned from the server is written into new storage.

•	Can use existing memory on the client without allocating new memory. When a unique pointer changes during a call from one non-null value to another, the pointer is assumed to point to a data object of the same type. Data returned from the server is written into existing storage specified by the value of the unique pointer before the call.

•	Can orphan memory on the client. Memory referenced by a non-null unique pointer may never be freed if the unique pointer changes to NULL during a call and the client does not have another means of dereferencing the storage.

•	Does not cause aliasing. Like storage pointed to by a reference pointer, storage pointed to by a unique pointer cannot be reached from any other name in the function.

The stubs call the user-supplied memory-management functions midl_user_allocate and midl_user_free to allocate and deallocate memory required for unique pointers and their referents.

The following restrictions apply to unique pointers:

•	The unique attribute cannot be applied to binding-handle parameters (handle_t) and context-handle parameters.

•	The unique attribute cannot be applied to out-only top-level pointer parameters (parameters that have only the out directional attribute).

•	Unique pointers cannot be used to describe the size of an array or union arm because unique pointers can have the value NULL. This restriction prevents the error that results if a null value is used as the array size or the union-arm size.

See Also

pointer_default, pointers, ptr, ref


unsigned

The unsigned keyword indicates that the most significant bit of an integer variable represents a data bit rather than a signed bit. This keyword is optional and can be used with any of the character and integer types char, wchar_t, int, long, short, and small.

When you use the MIDL compiler switch /char, character and integer types that appear in the IDL file without explicit sign keywords can appear with the signed or unsigned keyword in the generated header file. To avoid confusion, explicitly specify the sign of the integer and character types.

See Also

base_types, /char, IDL, int, long, short, signed, small


user_marshal

typedef [user_marshal(userm_type)] wire-type;

unsigned long __RPC_USER  < userm_type >_UserSize(
unsigned long __RPC_FAR *pFlags,
unsigned long                      StartingSize,
< userm_type >  __RPC_FAR * pUser_typeObject );

unsigned char __RPC_FAR * __RPC_USER  < userm_type >_UserMarshal(
unsigned long __RPC_FAR *pFlags,
unsigned char __RPC_FAR * Buffer,
< userm_type >  __RPC_FAR * pUser_typeObject);

unsigned char __RPC_FAR * __RPC_USER  < userm_type >_UserUnmarshal(
unsigned long  __RPC_FAR *  pFlags,
unsigned char __RPC_FAR *  Buffer,
< userm_type >  __RPC_FAR * pUser_typeObject);

void __RPC_USER  < userm_type >_UserFree(
unsigned long  __RPC_FAR * pFlags,
< userm_type >  __RPC_FAR * pUser_typeObject);

userm-type

Specifies the id of the user data type to be marshaled. The userm-type need not be remotable and need not be a type known to the MIDL compiler.

wire-type

Specifies the named transfer data type that is actually transferred between client and server. the wire-type must be a MIDL base type, predefined type, or a type identifier of a remotable.

pFlags

Specifies a pointer to a flag field(unsigned long). The high-order word specifies NDR data representation flags as defined by DCE for floating point, big- or little-endian, and character representation. The low-order word specifies a marshaling context flag. The exact layout of the flags is described in The type_UserSize Function.

StartingSize

Specifies the current buffer size (offset) before sizing the object.

Buffer

Specifies the current buffer pointer.

pUser_typeObject

Specifies a pointer to an object of userm_type.

Example

// Marshal a long as a structure containing two shorts.

typedef unsigned long FOUR_BYTE_DATA;

typedef struct _TWO_X_TWO_BYTE_DATA {

    unsigned short low;

    unsigned short high;

} TWO_X_TWO_BYTE_DATA;

//in ACFL file:

typedef [user_marshal(FOUR_BYTE_DATA)] TWO_X_TWO_BYTE_DATA;

//Marshaling functions:

unsigned long __RPC_USER FOUR_BYTE_DATA_UserSize(

    ULONG __RPC_FAR * pulFlags,

    char __RPC_FAR * pBufferStart,

    FOUR_BYTE_DATA __RPC_FAR * pul

    );//calculate size that converted data will

      // require in the buffer

unsigned long __RPC_USER FOUR_BYTE_DATA_UserMarshal(

    ULONG __RPC_FAR *pulFlags,

    char __RPC_FAR * pBufferStart,

    FOUR_BYTE_DATA __RPC_FAR * pul

    );//copy FOUR_BYTE_DATA into buffer as

      //TWO_X_TWO_BYTE_DATA

unsigned long __RPC_USER FOUR_BYTE_DATA_UserUnmarshal(

    ULONG __RPC_FAR * pulFlags,

    char __RPC_FAR * pBufferStart,

    FOUR_BYTE_DATA __RPC_FAR * pul

    );//recreate FOUR_BYTE_DATA from TWO_X_TWO_BYTE_DATA

      //in buffer

void __RPC_USER FOUR_BYTE_DATA_UserFree(

    ULONG __RPC_FAR * pulFlags,

    FOUR_BYTE_DATA __RPC_FAR * pul

    );//nothing to do here as the engine frees the

      // top node and FOUR_BYTE_DATA is a flat data

      //type.

Remarks

The user_marshal attribute associates a named local type in the target language (userm-type) with a transfer type (wire-type) that is transferred between client and server. Each userm-type has a one-to-one correspondence with a wire-type that defines the wire representation of the type. You must supply routines to size the data for marshaling, to marshal and unmarshal the data, and to free memory. For more information on these routines, see The user_marshal Attribute. Note that if there are embedded types in your data that are also defined with user_marshal or wire_marshal, you need to manage the servicing of those embedded types also.

The wire-type cannot be an interface pointer or a full pointer. The wire-type must have a well-defined memory size. See Marshaling Rules for user_marshal and wire_marshal for details on how to marshal a given wire-type.

The userm-type should not be an interface pointer as these can be marshaled directly. If the user type is a full pointer, you must manage the aliasing yourself.

See Also

The user_marshal Attribute, wire_marshal, represent_as, base_types


usesgetlasterror

[module-attributes] module module-name
{[entry(entry-id), usesgetlasterror [, other-attributes]] return-typefunction-name(param-list);
};

Example

[dllname("MyOwn.dll")] module MyModule

    {

    [entry(“One”), usesgetlasterror, bindable, requestedit,

   propputref, defaultbind]

        void Func1 ([in]IUnknown * iParam1, [out] long * Param2) ;

    [entry("TwentyOne"), usesgetlasterror, hidden, vararg]

         SAFEARRAY (int) Func2 ([in, out] SAFEARRAY (variant) *varP) ;

. . .};

Remarks

The usesgetlasterror attribute can be set on a module entry point, if that entry point uses the Win32 function SetLastError to return error codes. The attribute tells the caller that, if there is an error when calling that function, the caller can then call GetLastError to retrieve the error code.

See Also

ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


uuid

uuid (string_uuid)
uuid (“string-uuid”)

string-uuid

Specifies a string consisting of eight hexadecimal digits followed by a hyphen, then three groups of four hexadecimal digits each followed by a hyphen, then twelve hexadecimal digits. You can enclose the UUID string in quotes, except when you use the MIDL compiler switch /osf.

Examples

uuid(6B29FC40-CA47-1067-B31D-00DD010662DA)

uuid("6B29FC40-CA47-1067-B31D-00DD010662DA")

Remarks

The uuid interface attribute designates a universally unique identifier (UUID) that is assigned to the interface and that distinguishes it from other interfaces. The run-time library uses the interface UUID to help establish communication between the client and server applications.The uuid attribute can appear in the interface attribute list for either an RPC interface or an OLE interface.

For an RPC interface, the interface attribute list must include either the uuid attribute or the local attribute, and the one you choose must occur exactly once. If the list includes the uuid attribute, it can also include the version attribute.

For an OLE interface (identified by the object interface attribute), the interface attribute list must include the uuid attribute, but it cannot include the version attribute. The list for an OLE interface can include the local attribute even though the uuid attribute is present.

Microsoft RPC supports an extension to DCE IDL that allows the UUID to be enclosed in double quotation marks. The quoted form is needed for C-compiler preprocessors that interpret UUID numbers as floating-point numbers.

All UUID values should be computer-generated to guarantee uniqueness. Use the uuidgen utility to generate unique UUID values.

The UUID and version numbers of the interface are used to determine whether the client can bind to the server. For the client to bind to the server, the UUID specified in the client and server interfaces must be the same.

Note that an interface without attributes can be imported into a base IDL file. However, the interface must contain only datatypes with no procedures. If even one procedure is contained in the interface, a local or UUID attribute must be specified.

See Also

IDL, interface, local, /osf, version


v1_enum

[v1_enum] enum {...}

Example

typedef [v1_enum] enum {label1, label2, ...};

Remarks

The v1_enum attribute directs that the specified enumerated type be transmitted as a 32-bit entity, rather than the 16-bit default. This increases the efficiency of marshalling and unmarshalling data when such an enumerator is embedded in structures or unions.

For improved performance, we recommend applying the v1_enum attribute to enumerators in 32-bit applications. Keep in mind, however, that on 16-bit platforms the C compiler treats an enumerated type as a 16-bit int. Therefore 16-bit client applications need to convert enum types to long for remote transmission in order to avoid overwriting data or sending incorrect values.

See Also

enum, IDL


vararg

[vararg [, optional-attributes]] return-type function-name([optional-param-attributes] param-list, SAFEARRAY(VARIANT) last-param-name)

optional-attributes

Specifies zero or more attributes to be applied to the function. Separate multiple attributes with commas.

optional-param-attributes

Specifies zero or more attributes to be applied to the function parameter immediately following the attribute listing.

param-list

Specifies all the parameters, save the final, varying, parameters.

Example

[vararg] boolean Button([in]SAFEARRAY(VARIANT) psa);

Remarks

The vararg attribute specifies that the function takes a variable number of arguments. To accomplish this, the last argument must be a safe array of VARIANT type that contains all the remaining arguments.

You cannot apply the optional or defaultvalue attributes to any parameters in a function that has the vararg attribute.

See Also

ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


version

version ( major-value[. minor-value] )

major-value

Specifies a short unsigned integer between zero and 65,535, inclusive, that represents the major version number.

minor-value

Specifies a short unsigned integer between zero and 65,535, inclusive, that represents the minor version number. The minor version value is optional. If present, the minor version value is separated from the major version number by a period character (.). If not specified, the minor version value is zero.

Remarks

The version interface attribute identifies a particular version among multiple versions of an RPC interface. With the version attribute, you ensure that only compatible versions of client and server software are allowed to bind.

The MIDL compiler does not support multiple versions of an OLE interface. As a result, an interface attribute list that includes the object attribute cannot include the version attribute. To create a new version of an existing OLE interface, use interface inheritance. A derived OLE interface has a different UUID but inherits the interface member functions, status codes, and interface attributes of the base interface.

In combination with the uuid value, the version value uniquely identifies the interface. The run-time library passes the version and uuid values to the server when the client calls a remote function. A client can bind to a server for a given interface if:

•	The uuid value is the same.

•	The major version number is the same.

•	The client’s minor version number is less than or equal to the server’s minor version number.

It is to your benefit and your users’ benefit to retain upward compatibility among versions — that is, to modify the interface so that only the minor version number changes. You can retain upward compatibility when you add new data types that are not used by existing functions and when you add new functions without changing the interface specification for existing functions.

Change the major version number if any one of the following conditions apply:

•	If you change a data type that is used by an existing function.

•	If you change the interface specification for an existing function (such as adding or removing a parameter).

•	If you add callbacks that are called by existing functions.

Change the minor version number if all of the following conditions apply:

•	If you add type definitions or constants that are not used by any existing functions or callbacks.

•	If you do not change any existing functions and you add new functions to the interface.

•	If you add callbacks that are not called by any existing functions and the new callbacks follow any existing functions.

If your modifications qualify as an upward-compatible change to the interface, use the following procedure to modify the interface (IDL) file:

1.	Add new constant and type definitions to the interface file.

2.	Add callback functions to the end of the interface file.

3.	Add new functions to the end of the interface file.

The version attribute can occur at most once in the interface header.

When the version attribute is not present, the interface has a default version of 0.0.

The period character between the major and minor numbers is a delimiter and does not represent a decimal point. The minor number is treated as an integer. Leading zeroes are not significant. Trailing zeroes are significant.

For example, the version setting 1.11 represents a major value of one and a minor value of eleven. Version 1.11 does not represent a value between 1.1 and 1.2.

See Also

IDL, interface, uuid


void

void function (parameter-list);
return-type function(void);
typedef [context_handle] void * context-handle-type;
return-type function (...[context_handle] void * * context-handle-type...);

function

Specifies the name of the remote procedure.

parameter-list

Specifies the list of parameters passed to the function along with the associated parameter types and parameter attributes.

return-type

Specifies the name of the type returned by the function.

context-handle-type

Specifies the name of the type that takes the context_handle attribute.

Examples

void VoidFunc1(void);

void VoidFunc2([in, out] short s1);

typedef [context_handle] void * MY_CX_HNDL_TYPE;

void InitHandle([out] MY_CX_HNDL_TYPE * ppCxHndl);

Remarks

The base type void indicates a procedure with no arguments or a procedure that does not return a result value.

The pointer type void *, which in C describes a generic pointer that can be cast to represent any pointer type, is limited in MIDL to its use with the context_handle keyword.

See Also

base_types, context_handle, IDL


wchar_t

The wchar_t keyword designates a wide-character type. The wchar_t type is defined by MIDL as an unsigned short (16-bit) data object.

The MIDL compiler allows redefinition of wchar_t, but only if it is consistent with the preceding definition.

The wide-character type is one of the predefined types of MIDL. The wide-character type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function-return-type specifier and as a parameter-type specifier). For the context in which type specifiers appear, see IDL.

The string attribute can be applied to a pointer or array of type wchar_t.

Use the L character before a character or a string constant to designate the wide-character-type constant.

See Also

base_types, char, IDL


wire_marshal

typedef [wire_marshal(wire_type)] type-specifier userm-type;

unsigned long __RPC_USER  < userm_type >_UserSize(
unsigned long __RPC_FAR *pFlags,
unsigned long                      StartingSize,
< userm_type >  __RPC_FAR * pUser_typeObject );

unsigned char __RPC_FAR * __RPC_USER  < userm_type >_UserMarshal(
unsigned long  __RPC_FAR * pFlags,
unsigned char __RPC_FAR * Buffer,
< userm_type >  __RPC_FAR * pUser_typeObject);

unsigned char __RPC_FAR * __RPC_USER  < userm_type >_UserUnmarshal(
unsigned long  __RPC_FAR *  pFlags,
unsigned char __RPC_FAR *  Buffer,
< userm_type >  __RPC_FAR * pUser_typeObject);

void __RPC_USER  < userm_type >_UserFree(
unsigned long  __RPC_FAR * pFlags,
< userm_type >  __RPC_FAR * pUser_typeObject);

userm-type

Specifies the id of the user data type to be marshaled. It can be any type, as given by the type-specifier,.as long as it has a well-defined size. The userm-type need not be remotable but must be a type known to the MIDL compiler.

wire-type

Specifies the named transfer data type that is actually transferred between client and server. The wire-type must be a MIDL base type, predefined type, or a type identifier of a remotable type.

pFlags

Specifies a pointer to a flag field (unsigned long). The high-order word specifies NDR data representation flags as defined by DCE for floating point, big- or little-endian, and character representation. The low-order word specifies a marshaling context flag. The exact layout of the flags is described in The type_UserSize Function.

StartingSize

Specifies the current buffer size (offset) before sizing the object.

Buffer

Specifies the current buffer pointer.

pUser_typeObject

Specifies a pointer to an object of userm_type.

Example

typedef unsigned long _FOUR_BYTE_DATA;

    typedef struct _TWO_X_TWO_BYTE_DATA {

        unsigned short low;

        unsigned short high;

        } TWO_X_TWO_BYTE_DATA;

    typedef [wire_marshal(TWO_X_TWO_BYTE_DATA)] _FOUR_BYTE_DATA FOUR_BYTE_DATA;

//Marshaling functions:

unsigned long __RPC_USER FOUR_BYTE_DATA_UserSize(

    ULONG __RPC_FAR * pulFlags,

    char __RPC_FAR * pBufferStart,

    FOUR_BYTE_DATA __RPC_FAR * pul

    );//calculate size that converted data will

      // require in the buffer

unsigned long __RPC_USER FOUR_BYTE_DATA_UserMarshal(

    ULONG __RPC_FAR *pulFlags,

    char __RPC_FAR * pBufferStart,

    FOUR_BYTE_DATA __RPC_FAR * pul

    );//copy FOUR_BYTE_DATA into buffer as

      //TWO_X_TWO_BYTE_DATA

unsigned long __RPC_USER FOUR_BYTE_DATA_UserUnmarshal(

    ULONG __RPC_FAR * pulFlags,

    char __RPC_FAR * pBufferStart,

    FOUR_BYTE_DATA __RPC_FAR * pul

    );//recreate FOUR_BYTE_DATA from TWO_X_TWO_BYTE_DATA

      //in buffer

void __RPC_USER FOUR_BYTE_DATA_UserFree(

    ULONG __RPC_FAR * pulFlags,

    FOUR_BYTE_DATA __RPC_FAR * pul

    );//nothing to do here as the engine frees the top

      //node and FOUR_BYTE_DATA is a flat data type.

Remarks

The wire_marshal attribute specifies a data type that will be used for transmission (the wire-type) instead of an application-specific data type (the userm-type). Each userm-type has a one-to-one correspondence with a wire-type that defines the wire representation of the type. You must supply routines to size the data for marshaling, to marshal and unmarshal the data, and to free memory. Note that if there are embedded types in your data that are also defined with wire_marshal or user_marshal, you need to manage the servicing of those embedded types also. For more information on these routines, see The wire_marshal Attribute.

The wire-type cannot be an interface pointer or a full pointer. The wire-type must have a well-defined memory size. See Marshaling Rules for user_marshal and wire_marshal for details on how to marshal a given wire-type.

The userm-type should not be an interface pointer because these can be marshaled directly. If the user type is a full pointer, you must manage the aliasing yourself.

You cannot use the wire_marshal attribute with the allocate attribute, either directly or indirectly, because the NDR engine does not control memory allocation for the transmitted type.

See Also

The wire_marshal Attribute, user_marshal, transmit_as, base_types


About OpenGL

OpenGL, originally developed by Silicon Graphics Incorporated (SGI) for their graphics workstations, lets applications create high-quality color images independent of windowing systems, operating systems, and hardware.

The OpenGL Architecture Review Board (ARB), an industry consortium, is currently responsible for defining OpenGL. Members of the ARB include Silicon Graphics Incorporated, Microsoft Corporation, Intel, IBM, and Digital Equipment Corporation.

The official reference document for OpenGL, version 1, is the OpenGL Reference Manual, by the OpenGL Architecture Review Board (ISBN 0-201-63276-4). The official guide to learning OpenGL, version 1, is the OpenGL Programming Guide, by Jackie Neider, Tom Davis, and Mason Woo (ISBN 0-201-63274-8). Both books are published by Addison-Wesley.


OpenGL on Windows NT and Windows 95

The Microsoft implementation of OpenGL in the Microsoft® Windows NT® and Windows® 95 operating systems is an implementation of the industry-standard OpenGL three-dimensional (3-D) graphics software interface with which programmers create high-quality still and animated 3-D color images. This overview describes the Windows NT and Windows 95 implementation of OpenGL.


Components

Microsoft’s implementation of OpenGL in Windows NT and Windows 95 includes the following components:

•	The full set of current OpenGL commands

OpenGL contains a library of core functions for 3-D graphics operations. These basic functions are used to manage object shape description, matrix transformation, lighting, coloring, texture, clipping, bitmaps, fog, and antialiasing. The names for these core functions have a “gl” prefix.

Many of the OpenGL commands have several variants, which differ in the number and type of their parameters. Counting all the variants, there are more than 300 OpenGL commands.

•	The OpenGL Utility (GLU) library

This library of auxiliary functions complements the core OpenGL functions. The commands manage texture support, coordinate transformation, polygon tessellation, rendering spheres, cylinders and disks, NURBS (Non-Uniform Rational B-Spline) curves and surfaces, and error handling.

•	The OpenGL Programming Guide Auxiliary library

This is a simple, platform-independent library of functions for managing windows, handling input events, drawing classic 3-D objects, managing a background process, and running a program. The window management and input routines provide a base level of functionality with which you can quickly get started programming in OpenGL.

Do not use them, however, in a production application. Here are some reasons for this warning:

•	The message loop is in the library code.

•	There is no way to add handlers for additional WM* messages.

•	There is very little support for logical palettes.

The library is described and used in the OpenGL Programming Guide.

•	The WGL functions

This set of functions connects OpenGL to the Windows NT and Windows 95 windowing system. The functions manage rendering contexts, display lists, extension functions, and font bitmaps. The WGL functions are analogous to the GLX extensions that connect OpenGL to the X Window System. The names for these functions have a “wgl” prefix.

•	New Win32 functions for pixel formats and double buffering

These functions support per-window pixel formats and double buffering (for smooth image changes) of windows. These new functions apply only to OpenGL graphics windows.


Generic Implementation and Hardware Implementations

This overview discusses the current generic implementation of OpenGL in Windows NT and Windows 95, which is the Microsoft Windows NT and Windows 95 software implementation of OpenGL. Hardware manufacturers may enhance parts of OpenGL in their drivers and may support some features not supported by the generic implementation.


Limitations

The generic implementation has the following limitations:

•	Printing.

You can print an OpenGL image directly to a printer using metafiles only. For more information, see Printing an OpenGL Image.

•	OpenGL and GDI graphics cannot be mixed in a double-buffered window.

An application can directly draw both OpenGL graphics and GDI graphics into a single-buffered window, but not into a double-buffered window.

•	There are no per-window hardware color palettes.

Windows NT and Windows 95 have a single system hardware color palette, which applies to the whole screen. An OpenGL window cannot have its own hardware palette, but can have its own logical palette. To do so, it must become a palette-aware application. For more information, see OpenGL Color Modes and Windows Palette Management.

•	There is no direct support for the Clipboard, dynamic data exchange (DDE), or OLE.

A window with OpenGL graphics does not directly support these Windows NT and Windows 95 capabilities. There are workarounds, however, for using the Clipboard. For more information, see Copying an OpenGL Image to the Clipboard.

•	The Inventor 2.0 C++ class library is not included.

The Inventor class library, built on top of OpenGL, provides higher-level constructs for programming 3-D graphics. It is not included in the current version of Microsoft’s implementation of OpenGL for Windows NT and Windows 95.

•	There is no support for the following pixel format features: stereoscopic images, alpha bitplanes, and auxiliary buffers.

There is, however, support for several ancillary buffers including: stencil buffer, accumulation buffer, back buffer (double buffering), overlay and underlay plane buffer, and depth (z-axis) buffer.


Guide to Documentation

The documentation set for OpenGL in Windows NT and Windows 95 includes five elements.

The first two elements are the official OpenGL books: the OpenGL Reference Manual and the OpenGL Programming Guide.

Note  The OpenGL Reference Manual and the OpenGL Programming Guide are not included with the Win32® application programming interface SDK.

The OpenGL Reference Manual includes an overview of how OpenGL works and a set of detailed reference pages. The reference pages cover all the 115 distinct OpenGL functions, as well as the 43 functions in the OpenGL Utility (GLU) library.

The OpenGL Programming Guide explains how to create graphics programs using OpenGL. It includes discussions of the following major topics:

•	Drawing geometric shapes

•	Pixels, bitmaps, fonts, and images

•	Viewing and matrix transformations

•	Texture mapping

•	Display lists

•	Advanced composite techniques

•	Color

•	Evaluators and NURBS

•	Lighting

•	Selection and feedback

•	Blending, antialiasing, and fog

•	Advanced techniques

In addition, the OpenGL Programming Guide contains appendixes that discuss the OpenGL Utility library and the OpenGL Programming Guide Auxiliary library.

The third documentation element is this overview. It describes the Windows NT and Windows 95 implementation of OpenGL and provides an overview of its components. It discusses the concepts of rendering contexts, pixel formats, and buffers; the WGL functions that connect OpenGL to the Windows NT and Windows 95 windowing systems; and the Win32 functions that support per-window pixel formats and double buffering of windows for OpenGL graphics windows. The WGL functions and the Win32 functions are specific to the Windows NT and Windows 95 implementation of OpenGL.

The fourth documentation element is the set of reference pages for the WGL functions, the Win32 functions just mentioned, and the PIXELFORMATDESCRIPTOR data structure.

The fifth documentation element is Porting to OpenGL. It discusses moving existing OpenGL code from other environments into Windows NT and Windows 95.


Rendering Contexts

An OpenGL rendering context is a port through which all OpenGL commands pass. Every thread that makes OpenGL calls must have a current rendering context. Rendering contexts link OpenGL to the Windows NT and Windows 95 windowing systems.

An application specifies a Windows NT or Windows 95 device context when it creates a rendering context. This rendering context is suitable for drawing on the device that the specified device context references. In particular, the rendering context has the same pixel format as the device context. For more information, see Rendering Context Functions.

Despite this relationship, a rendering context is not the same as a device context. A device context contains information pertinent to the graphics component (GDI) of Windows NT and Windows 95. A rendering context contains information pertinent to OpenGL. A device context must be explicitly specified in a GDI call. A rendering context is implicit in an OpenGL call. You should set a device context’s pixel format before creating a rendering context.

A thread that makes OpenGL calls must have a current rendering context. If an application makes OpenGL calls from a thread that lacks a current rendering context, nothing happens; the call has no effect. An application commonly creates a rendering context, sets it as a thread’s current rendering context, and then calls OpenGL functions. When it finishes calling OpenGL functions, the application uncouples the rendering context from the thread, and then deletes the rendering context. A window can have multiple rendering contexts drawing to it at one time, but a thread can have only one current, active rendering context.

A current rendering context has an associated device context. That device context need not be the same device context as that used when the rendering context was created, but it must reference the same device and have the same pixel format.

A thread can have only one current rendering context. A rendering context can be current to only one thread.


Rendering Context Functions

Five WGL functions manage rendering contexts, as described in the following table.

WGL Function	Description
wglCreateContext	Creates a new rendering context.
wglMakeCurrent	Sets a thread’s current rendering context.
wglGetCurrentContext	Obtains a handle to a thread’s current rendering context.
wglGetCurrentDC	Obtains a handle to the device context associated with a thread’s current rendering context.
wglDeleteContext	Deletes a rendering context.
The wglCreateContext function takes a device context handle as its parameter and returns a rendering context handle. The created rendering context is suitable for drawing on the device referenced by the device context handle. In particular, its pixel format is the same as the device context’s pixel format. After you create a rendering context, you can release or dispose of the device context. See Device Contexts for more details on creating, obtaining, releasing, and disposing of a device context.

Note  The device context sent to wglCreateContext must be a display device context, a memory device context, or a color printer device context that uses four or more bits per pixel. The device context cannot be a monochrome printer device context.

The wglMakeCurrent function takes a rendering context handle and a device context handle as parameters. All subsequent OpenGL calls made by the thread are made through that rendering context, and are drawn on the device referenced by that device context. The device context does not have to be the same one passed to wglCreateContext when the rendering context was created, but it must be on the same device and have the same pixel format. The call to wglMakeCurrent creates an association between the supplied rendering context and device context. You cannot release or dispose of the device context associated with a current rendering context until after you make the rendering context not current.

Once a thread has a current rendering context, it can make OpenGL graphics calls. All calls must pass through a rendering context. Nothing happens if you make OpenGL graphics calls from a thread that lacks a current rendering context.

The wglGetCurrentContext function takes no parameters, and returns a handle to the calling thread’s current rendering context. If the thread has no current rendering context, the return value is NULL.

When you obtain a handle to the device context associated with a thread’s current rendering context by calling wglGetCurrentDC, the association is created when a rendering context is made current.

You can break the association between a current rendering context and a thread by calling wglMakeCurrent with either of two handles:

•	A null rendering context handle

•	A handle other than the one originally called

After calling wglMakeCurrent with the rendering context handle parameter set to NULL, the calling thread has no current rendering context. The rendering context is released from its connection to the thread, and the rendering context’s association to a device context ends. OpenGL flushes all drawing commands, and may release some resources. No OpenGL drawing will be done until the next call to wglMakeCurrent, because the thread can make no OpenGL graphics calls until it regains a current rendering context.

The second way to break the association between a rendering context and a thread is to call wglMakeCurrent with a different rendering context. After such a call, the calling thread has a new current rendering context, the former current rendering context is released from its connection to the thread, and the former current rendering context’s association to a device context ends.

The wglDeleteContext function takes a single parameter, the handle to the rendering context to be deleted. Before calling wglDeleteContext, make the rendering context not current by calling wglMakeCurrent, and delete or release the associated device context by calling DeleteDC or ReleaseDC as appropriate.

It is an error for a thread to delete a rendering context that is another thread’s current rendering context. However, if a rendering context is the calling thread’s current rendering context, wglDeleteContext flushes all OpenGL drawing commands and makes the rendering context not current before deleting it. In this case, relying on wglDeleteContext to make a rendering context not current requires the programmer to delete or release the associated device context.


Pixel Formats

A pixel format specifies several properties of an OpenGL drawing surface. Some of the properties specified by a pixel format are:

•	Whether the pixel buffer is single- or double-buffered.

•	Whether the pixel data is in RGBA or color-index form.

•	The number of bits used to store color data.

•	The number of bits used for the depth (z-axis) buffer.

•	The number of bits used for the stencil buffer.

•	The number of overlay and underlay planes.

•	Various visibility masks.

Microsoft’s implementation of OpenGL for Windows NT and Windows 95 uses the PIXELFORMATDESCRIPTOR data structure to convey pixel format data. The structure’s members specify the preceding properties and several others.

A given device context can support several pixel formats. Windows NT and Windows 95 identify the pixel formats that a device context supports with consecutive one-based index values (1, 2, 3, 4, and so on). A device context can have just one current pixel format, chosen from the set of pixel formats it supports.

Each window has its own current pixel format in OpenGL in Windows NT and Windows 95. This means, for example, that an application can simultaneously display RGBA and color-index OpenGL windows, or single- and double-buffered OpenGL windows. This per-window pixel format capability is limited to OpenGL windows.

Typically, you obtain a device context, set the device context’s pixel format, and then create an OpenGL rendering context suitable for that device.

Note  You set the pixel format before creating a rendering context because the rendering context inherits the device context’s pixel format.


Pixel Format Functions

The following Win32 functions manage pixel formats.

Win32 Function	Description
ChoosePixelFormat	Obtains the device context’s pixel format that is the closest match to a specified pixel format.
SetPixelFormat	Sets a device context’s current pixel format to the pixel format specified by a pixel format index.
GetPixelFormat	Obtains the pixel format index of a device context’s current pixel format.
DescribePixelFormat	Given a device context and a pixel format index, fills in a PIXELFORMATDESCRIPTOR data structure with the pixel format’s properties.
GetEnhMetaFilePixelFormat	Retrieves pixel format information for an enhanced metafile.
The ChoosePixelFormat function returns a one-based pixel format index that identifies the best match from the device context’s supported pixel formats.

The SetPixelFormat function identifies the desired format using a one-based pixel format index. Typically, you call ChoosePixelFormat to find a best-match pixel format, and then call SetPixelFormat with the result of ChoosePixelFormat.

If you call SetPixelFormat for a device context that references a window, SetPixelFormat also changes the pixel format of the window. Setting the pixel format of a window more than once can lead to significant complications for the Window Manager and for multithread applications, so it is not allowed. You can set the pixel format of a window only one time; after that, the window’s pixel format cannot be changed.

The GetPixelFormat function returns a one-based pixel format index.

The DescribePixelFormat function takes the following as parameters:

•	A handle to a device context

•	A pixel format index

•	A pointer to a PIXELFORMATDESCRIPTOR data structure

The DescribePixelFormat function returns with the members of PIXELFORMATDESCRIPTOR appropriately set.

The GetEnhMetaFilePixelFormat function returns the size of a metafile’s pixel format and retrieves the pixel format information of the metafile.


Front, Back, and Other Buffers

OpenGL stores and manipulates pixel data in a frame buffer. The frame buffer consists of a set of logical buffers: color, depth, accumulation, and stencil buffers. The color buffer itself consists of a set of logical buffers; this set can include a front-left, a front-right, a back-left, a back-right, and some number of auxiliary buffers. A particular pixel format or OpenGL implementation may not supply all of these buffers. For example, the current version of Microsoft’s implementation of OpenGL in Windows NT and Windows 95 does not support stereoscopic images, so a pixel format cannot have left and right color buffers. In addition, the current version does not support auxiliary buffers. For more information on OpenGL buffers and the OpenGL functions that operate on them, see the OpenGL Reference Manual and the OpenGL Programming Guide.

Microsoft’s implementation of OpenGL in Windows NT and Windows 95 supports double buffering of images. This is a technique in which an application draws pixels to an off-screen buffer, and then, when that image is ready for display, copies the contents of the off-screen buffer to an on-screen buffer. Double buffering enables smooth image changes, which are especially important for animated images.

Two color buffers are available to applications that use double buffering: a front buffer and a back buffer. By default, drawing commands are directed to the back buffer (the off-screen buffer), while the front buffer is displayed on the screen. When the off-screen buffer is ready for display, you call SwapBuffers, and Windows NT or Windows 95 copies the contents of the off-screen buffer to the on-screen buffer.

The generic implementation uses a device-independent bitmap (DIB) as the back buffer and the screen display as the front buffer. Hardware devices and their drivers may use different approaches.

Double buffering is a pixel-format property. To request double buffering for a pixel format, set the PFD_DOUBLEBUFFER flag in the PIXELFORMATDESCRIPTOR data structure in a call to ChoosePixelFormat.

The OpenGL core function, glDrawBuffer, selects buffers for writing and clearing.


Buffer Functions

To copy the contents of an off-screen buffer to an on-screen buffer, call SwapBuffers. The SwapBuffers function takes a handle to a device context. The current pixel format for the specified device context must include a back buffer. By default, the back buffer is off-screen, and the front buffer is on-screen.

Note  The SwapBuffers function does not really swap the contents of the two buffers, but rather copies the contents of one buffer to another. The contents of the off-screen buffer are undefined after a call to SwapBuffers. Thus, the result of two consecutive calls to SwapBuffers is undefined.

The following illustration shows how the contents of the buffers are copied when calling SwapBuffers.

Several OpenGL core functions also manage buffers. The glDrawBuffer function is the one most relevant to double buffering; it specifies the frame buffer or buffers that OpenGL draws into.

The following functions also affect buffers:

glReadBuffer
glReadPixels
glCopyPixels
glAccum
glColorMask
glDepthMask
glIndexMask
glStencilMask
glClearAccum
glClearColor
glClearDepth
glClearIndex
glClearStencil


Fonts and Text

Microsoft’s implementation of OpenGL in Windows NT and Windows 95 supports GDI graphics in a single-buffered OpenGL window. It does not support GDI graphics in a double-buffered OpenGL window. Thus, you can call only the standard GDI font and text functions to draw text in a single-buffered OpenGL window; you cannot call those functions to draw text in a double-buffered OpenGL window.

There is a workaround for this restriction on text in double-buffered windows: build OpenGL display lists for bitmap images of characters, and then execute those display lists to draw characters. There are three main steps in this process:

1.	Select a font for a device context, setting the font’s properties as desired.

2.	Create a set of bitmap display lists based on the glyphs in the device context’s font, one display list for each glyph that the application will draw.

3.	Draw each glyph in a string, using those bitmap display lists.

To create the display lists, call the wglUseFontBitmaps and wglUseFontOutlines functions. To draw characters in a string using those display lists, call glCallLists.

To create applications that are easy to localize and that use resources sparingly, the creation and storage of these glyph image display lists must be managed carefully. Many languages, unlike English, have alphabets whose character codes range over a relatively large set of values.


Font and Text Functions

Two functions can be used to manage fonts and text.

Win32 Function	Description
wglUseFontBitmaps	Creates a set of character bitmap display lists. Characters come from a specified device context’s current font. Characters are specified as a consecutive run within the font’s glyph set.
wglUseFontOutlines	Creates a set of display lists, based on the glyphs of the currently selected outline font of a device context, for use with the current rendering context. The display lists are used to draw 3-D characters of TrueType fonts.
The wglUseFontBitmaps and wglUseFontOutlines functions take a handle to a device context, and use that device context’s current font as a source for the bitmaps. It is therefore necessary to set the device context’s font and the font’s properties before calling wglUseFontBitmaps or wglUseFontOutlines.

The wglUseFontBitmaps and wglUseFontOutlines functions also take a parameter that turns the first glyph in the font into a bitmap display list, and a parameter that specifies how many glyphs to turn into display lists. The function then creates display lists for the specified consecutive run of glyphs. For example:

•	To create a set of 224 bitmap display lists for all of the Windows NT and Windows 95 character set glyphs, set these two parameters to 32 and 224, respectively.

•	To create a set of 256 bitmap display lists for all of the OEM character set glyphs, set these two parameters to 0 and 256, respectively.

•	To create a single bitmap display list for any single character set glyph, set the second of these parameters to 1.

The wglUseFontBitmaps and wglUseFontOutlines functions represent a null glyph in a font with an empty display list.

The display lists created by a call to wglUseFontBitmaps or wglUseFontOutlines are automatically numbered consecutively.

After calling the wglUseFontBitmaps or wglUseFontOutlines function, call glCallLists to draw a string of characters. See Drawing Text in a Double-Buffered OpenGL Window for sample code. In this context, glCallLists uses each character in a string as an index into the array of consecutively numbered display lists created by wglUseFontBitmaps or wglUseFontOutlines.

When you finish drawing text, call the glDeleteLists function to release the contiguous set of display lists created by wglUseFontBitmaps and wglUseFontOutlines.


OpenGL Color Modes and Windows Palette Management

Microsoft’s implementation of OpenGL in Windows NT and Windows 95 supports two color pixel data modes: RGBA and color-index modes. Windows NT and Windows 95 provide two analogous ways of handling color: true color and palette management.

True-color devices, able to accept 16, 24, or more bits of color information per pixel, can display tens of thousands, tens of millions, or more colors simultaneously. Complexities arise, however, when an application has to manage RGBA or color-index mode on a palette-type device. Palette-type devices, such as a 256-color VGA display, are limited in the number of colors they can display simultaneously. Applications must handle a number of tricky details to successfully use palette-type devices. Because color-index mode programs don’t use a hardware palette, they are more difficult to use with true-color devices than programs using the RGBA mode.

If you are unfamiliar with true-color devices or the Palette Manager, refer to the articles “Palette Awareness,” “The Palette Manager: How and Why,” and “Using True-Color devices” on the Microsoft Developer Network Development Library compact discs for an introduction to the essentials of Windows NT and Windows 95 color management.


Palettes and the Palette Manager

The Windows NT and Windows 95 Palette Manager, which is part of the GDI, specifically targets 8-bit display adapters with a hardware palette of 256 color entries. Pixels on the screen are stored as an 8-bit index into the hardware palette. Each entry in the hardware palette usually defines a 24-bit color (8 each of red, green, and blue).

The Palette Manager maintains a system palette that is a copy of the hardware palette. The system palette is divided into two sections: 20 reserved colors and the remaining 236 colors, which you can set using the Palette Manager.

A default 20-color logical palette is selected and realized into a device context. You can create and use a new logical palette. To change the system palette, select and realize the logical palette you created.

You’ll probably create a logical palette to specify the colors you want displayed in your OpenGL application. Using certain GDI calls, you can temporarily replace most of the system palette with a logical palette. Using a logical palette, you can define pixel colors for the GDI using either the RGBA or the color-index mode. The maximum size of a logical palette is 256 colors for 8-bit devices and 4,096 colors on a true-color device (16, 24, and 32 bits).

For more information on the RGBA and color-index modes, see RGBA Mode and Windows Palette Management and OpenGL Color Modes and Windows Palette Management.


Palette Awareness

Your application must respond to the WM_PALETTECHANGED, WM_QUERYNEWPALETTE, and WM_ACTIVATE messages to be aware of and use palettes. Design your application to select and realize palettes in response to these messages.

For more information on palettes and palette awareness, see the articles “Palette Awareness,” and “The Palette Manager: How and Why” on the Microsoft Developer Network Development Library compact discs.


Reading Color Values from the Frame Buffer

When using functions that read back color values from the frame buffer, be aware of the differences between reading RGBA values and color-index values on true-color devices and on palette-based devices.

On a true-color device:

•	RGBA values are limited to the channel in the device.

•	Color-index values are stored as RGBA values in the frame buffer. When using these values, you must perform an inverse translation from RGBA to the logical palette index. If two logical indexes have the same RGBA values, the wrong index can be returned.

On a palette-based device:

•	RGBA values are read from an index in the system palette. The logical index is obtained from an inverse table, and the RGBA components are extracted.

•	Color-index values are read from an index into the system palette and an inverse table is used to get the logical palette index.


Choosing Between RGBA and Color-Index Mode

In general, use the RGBA mode for your OpenGL applications; it provides more flexibility than the color-index mode for effects such as shading, lighting, color mapping, fog, antialiasing, and blending.

Consider using the color-index mode in the following cases:

•	If you have a limited number of bitplanes available; the color-index mode can produce less-coarse shading than the RGBA mode.

•	If you are not concerned about using “real” colors; for example, using several colors in a topographic map to designate relative elevations.

•	When you’re porting an existing application that uses color-index mode extensively.

•	When you want to use color-map animation and effects in your application. (This is not possible on true-color devices.)


RGBA Mode and Windows Palette Management

While most GDI applications tend to use color-indexing with logical palettes, the RGBA mode is usually preferable for OpenGL applications. It works better than color mapping for several effects, such as shading, lighting, fog, and texture mapping.

The RGBA mode uses red, green, and blue (R, G, and B) color values that together specify the color of each pixel in the display. The R, G, and B values specify the intensity of each color (red, green, and blue); the values range from 0.0 (least intense) to 1.0 (most intense). The number of bits for each component varies depending on the hardware used (2, 3, 5, 6, and 8 bits are possible).The color displayed is a result of the sum of the three color values. If all three values are 0.0, the result is black. If the three values are all 1.0, the result is white. Other colors are a result of a combination of values of R, G, and B that fall between 0 and 1.0. The A (alpha) bit isn’t used to specify color.

The standard super-VGA display uses palettes with eight color-bits per pixel. The eight bits are read from the buffer and used as an index in the system palette to get the R, G, and B values. When an RGB palette is selected and realized in a device context, OpenGL can render using the RGBA mode.

Because there are eight color-bits per pixel, OpenGL emphasizes the use of a three-three-two RGBA palette. “Three-three-two” refers to how the color-bit data is handled by the hardware or physical palette. Red (R) and green (G) are each specified by three bits; blue (B) is specified by two bits. Red is the least-significant bit and blue is the most-significant bit.

You determine the colors of your application’s logical palette with PALETTEENTRY structures. Typically you create an array of PALETTEENTRY structures to specify the entire palette entry table of the logical palette.

RGBA Mode Palette Sample

The following code fragment shows how you can create a three-three-two RGBA palette.

/*

 * win8map.c - program to create an 8-bit RGB color map for

 * use with OpenGL

 *

 * For OpenGL RGB rendering you need to know red, green, & blue

 * component bit sizes and positions. On 8 bit palette devices you need

 * to create a logical palette that has the correct RGBA values for all

 * 256 possible entries. This program creates an 8 bit RGBA color cube

 * with a default gamma of 1.4

 *

 * Unfortunately, because the standard 20 colors in the system palette

 * cannot be changed,if you select this palette into an 8-bit display

 * DC, you will not realize all of the logical palette. The program

 * changes some of the entries in the logical palette to match enties in

 * the system palette using a least-squares calculation to find which

 * entries to replace

 *

 * Note: Three bits for red & green and two bits for blue; red is the

 * least-significant bit and blue is the most-significant bit

 */

#include <stdio.h>

#include <math.h>

#define DEFAULT_GAMMA 1.4F

#define MAX_PAL_ERROR (3*256*256L)

struct colorentry {

    unsigned char red;

    unsigned char green;

    unsigned char blue;

};

struct rampentry {

    struct colorentry color;

    long defaultindex;

    unsigned char flags;

};

struct defaultentry {

    struct colorentry color;

    long rampindex;

    unsigned char flags;

};

/* values for flags */

#define EXACTMATCH      0x01

#define CHANGED         0x02        /* one of the default entries is close */

/*

 * These arrays hold bit arrays with a gamma of 1.0

 * used to convert n bit values to 8-bit values

 */

unsigned char threeto8[8] = {

    0, 0111>>1, 0222>>1, 0333>>1, 0444>>1, 0555>>1, 0666>>1, 0377

};

unsigned char twoto8[4] = {

    0, 0x55, 0xaa, 0xff

};

unsigned char oneto8[2] = {

    0, 255

};

struct defaultentry defaultpal[20] = {

    { 0,   0,   0 },

    { 0x80,0,   0 },

    { 0,   0x80,0 },

    { 0x80,0x80,0 },

    { 0,   0,   0x80 },

    { 0x80,0,   0x80 },

    { 0,   0x80,0x80 },

    { 0xC0,0xC0,0xC0 },

    { 192, 220, 192 },

    { 166, 202, 240 },

    { 255, 251, 240 },

    { 160, 160, 164 },

    { 0x80,0x80,0x80 },

    { 0xFF,0,   0 },

    { 0,   0xFF,0 },

    { 0xFF,0xFF,0 },

    { 0,   0,   0xFF },

    { 0xFF,0,   0xFF },

    { 0,   0xFF,0xFF },

    { 0xFF,0xFF,0xFF }

};

struct rampentry rampmap[256];

void

gammacorrect(double gamma)

{

    int i;

    unsigned char v, nv;

    double dv;

    for (i=0; i<8; i++) {

        v = threeto8[i];

        dv = (255.0 * pow(v/255.0, 1.0/gamma)) + 0.5;

    nv = (unsigned char)dv;

    printf("Gamma correct %d to %d (gamma %.2f)\n", v, nv, gamma);

        threeto8[i] = nv;

    }

    for (i=0; i<4; i++) {

        v = twoto8[i];

        dv = (255.0 * pow(v/255.0, 1.0/gamma)) + 0.5;

    nv = (unsigned char)dv;

    printf("Gamma correct %d to %d (gamma %.2f)\n", v, nv, gamma);

        twoto8[i] = nv;

    }

    printf("\n");

}

main(int argc, char *argv[])

{

    long i, j, error, min_error;

    long error_index, delta;

    double gamma;

    struct colorentry *pc;

    if (argc == 2)

        gamma = atof(argv[1]);

    else

        gamma = DEFAULT_GAMMA;

    gammacorrect(gamma);

    /* First create a 256 entry RGB color cube */

    for (i = 0; i < 256; i++) {

        /* BGR: 2:3:3 */

        rampmap[i].color.red = threeto8[(i&7)];

        rampmap[i].color.green = threeto8[((i>>3)&7)];

        rampmap[i].color.blue = twoto8[(i>>6)&3];

    }

    /* Go through the default palette and find exact matches */

    for (i=0; i<20; i++) {

        for(j=0; j<256; j++) {

            if ( (defaultpal[i].color.red == rampmap[j].color.red) &&

                 (defaultpal[i].color.green == rampmap[j].color.green) &&

                 (defaultpal[i].color.blue == rampmap[j].color.blue)) {

                rampmap[j].flags = EXACTMATCH;

                rampmap[j].defaultindex = i;

                defaultpal[i].rampindex = j;

                defaultpal[i].flags = EXACTMATCH;

                break;

            }

        }

    }

    /* Now find close matches */

    for (i=0; i<20; i++) {

        if (defaultpal[i].flags == EXACTMATCH)

            continue;         /* skip entries w/ exact matches */

        min_error = MAX_PAL_ERROR;

        /* Loop through RGB ramp and calculate least square error */

        /* if an entry has already been used, skip it */

        for(j=0; j<256; j++) {

            if (rampmap[j].flags != 0)      /* Already used */

                continue;

            delta = defaultpal[i].color.red - rampmap[j].color.red;

            error = (delta * delta);

            delta = defaultpal[i].color.green - rampmap[j].color.green;

            error += (delta * delta);

            delta = defaultpal[i].color.blue - rampmap[j].color.blue;

            error += (delta * delta);

            if (error < min_error) {        /* New minimum? */

                error_index = j;

                min_error = error;

            }

        }

        defaultpal[i].rampindex = error_index;

        rampmap[error_index].flags = CHANGED;

        rampmap[error_index].defaultindex = i;

    }

    /* First print out the color cube */

    printf("Standard 8-bit RGB color cube with gamma %.2f:\n", gamma);

    for (i=0; i<256; i++) {

        pc = &rampmap[i].color;

        printf("%3ld: (%3-D, %3-D, %3-D)\n", i, pc->red,

                pc->green, pc->blue);

    }

    printf("\n");

    /* Now print out the default entries that have an exact match */

    for (i=0; i<20; i++) {

        if (defaultpal[i].flags == EXACTMATCH) {

            pc = &defaultpal[i].color;

            printf("Default entry %2ld exactly matched RGB ramp entry

                      %3ld", i, defaultpal[i].rampindex);

            printf(" (%3-D, %3-D, %3-D)\n", pc->red, pc->green, pc->blue);

        }

    }

    printf("\n");

    /* Now print out the closest entries for rest of

     * the default entries */

    for (i=0; i<20; i++) {

        if (defaultpal[i].flags != EXACTMATCH) {

            pc = &defaultpal[i].color;

            printf("Default entry %2ld (%3-D, %3-D, %3-D) is close to ",

                i, pc->red, pc->green, pc->blue);

            pc = &rampmap[defaultpal[i].rampindex].color;

            printf("RGB ramp entry %3ld (%3-D, %3-D, %3-D)\n",

                defaultpal[i].rampindex, pc->red, pc->green, pc->blue);

        }

    }

    printf("\n");

    /* Print out code to initialize a logical palette

     * that will not overflow */

    printf("Here is code you can use to create a logical palette\n");

    printf("static struct {\n");

    printf("    WORD        palVersion;\n");

    printf("    WORD        palNumEntries;\n");

    printf("    PALETTEENTRY palPalEntries[256];\n");

    printf("} rgb8palette = {\n");

    printf("    0x300,\n");

    printf("    256,\n");

    for (i=0; i<256; i++) {

        if (rampmap[i].flags == 0)

            pc = &rampmap[i].color;

        else

            pc = &defaultpal[rampmap[i].defaultindex].color;

        printf("    %3-D, %3-D, %3-D,   0,    /* %ld",

                pc->red, pc->green, pc->blue, i);

        if (rampmap[i].flags == EXACTMATCH)

            printf(" - Exact match with default %d",

                       rampmap[i].defaultindex);

        if (rampmap[i].flags == CHANGED)

            printf(" - Changed to match default %d",

                       rampmap[i].defaultindex);

        printf(" */\n");

    }

    printf("};\n");

    printf("\n    * * *\n\n");

    printf("    hpal = CreatePalette((LOGPALETTE *)&rgb8palette);\n");

    return 0;

}


Color-Index Mode and Windows Palette Management

The color-index mode specifies colors in a logical palette with an index to a specific logical-palette entry. Most GDI programs use color-index palettes, but the RGBA mode works better for OpenGL for several effects, such as shading, lighting, fog, and texture mapping. If having the truest color isn’t critical for your OpenGL application, you might choose to use the color-index mode (for example, for a topographic map that uses “false color” to emphasize the elevation gradient).

Color-Index Mode Palette Sample

The following code sets up a PIXELFORMATDESCRIPTOR structure that sets the flag of the iPixelType member to PFD_TYPE_COLORINDEX. This specifies that the application use a color-index palette.

BOOL bSetupPixelFormat(HDC hdc)

{

    PIXELFORMATDESCRIPTOR pfd, *ppfd;

    int pixelformat;

    ppfd = &pfd;

    ppfd->nSize = sizeof(PIXELFORMATDESCRIPTOR);

    ppfd->nVersion = 1;

    ppfd->dwFlags = PFD_DRAW_TO_WINDOW | PFD_SUPPORT_OPENGL |

                        PFD_DOUBLEBUFFER;

    ppfd->dwLayerMask = PFD_MAIN_PLANE;

    /* Set to color-index mode and use the default color palette. */

    ppfd->iPixelType = PFD_TYPE_COLORINDEX;

    ppfd->cColorBits = 8;

    ppfd->cDepthBits = 16;

    ppfd->cAccumBits = 0;

    ppfd->cStencilBits = 0;

    pixelformat = ChoosePixelFormat(hdc, ppfd);

    if ( (pixelformat = ChoosePixelFormat(hdc, ppfd)) == 0 )

    {

        MessageBox(NULL, "ChoosePixelFormat failed", "Error", MB_OK);

        return FALSE;

    }

    if (SetPixelFormat(hdc, pixelformat, ppfd) == FALSE)

    {

        MessageBox(NULL, "SetPixelFormat failed", "Error", MB_OK);

        return FALSE;

    }

    return TRUE;

}


Overlay, Underlay, and Main Planes

You can use hardware layer planes (overlay and underlay planes) in your applications. With Windows NT and Windows 95, pixel formats describe the pixel configurations of a graphics device. Each pixel format describes the depth and other characteristics of the main color buffers and describes additional buffers (such as depth, accumulation, stencil, and auxiliary) that the main plane uses. Pixel formats are now extended to include overlay and underlay buffers.

Layer planes always have a front-left color buffer and also can include front-right and back color buffers. Each layer plane has a specific rendering context to render into the layer buffers. You cannot use GDI drawing functions in layer planes.

A window manages the color buffers of layer planes similarly to the way it manages main-plane color buffers. You can display multiple windows with overlay and/or underlay planes at the same time. You cannot have free-floating overlay windows that can move over any window in the main drawing plane. In addition, because it would obscure underlying planes in a window at all times, you cannot use hardware pop-up planes that have no transparent color.

Each layer plane in a window has an associated palette. You can set the palette of a color-index layer plane, but the palette of an RGBA color plane is fixed. You must realize the appropriate palette when a window is in the foreground. Layer planes have a transparent pixel color or index that enables any underlying layer planes to show through.

You can copy the state of a rendering context to another rendering context in a separate layer plane. You can also share display lists among rendering contexts in different layer planes.

The following functions are used with layer planes:

wglCopyContext
wglCreateLayerContext
wglDescribeLayerPlane
wglGetLayerPaletteEntries
wglRealizeLayerPalette
wglSetLayerPaletteEntries
wglSwapLayerBuffers


Sharing Display Lists

When you create a rendering context, it has its own display-list space. The wglShareLists function enables a rendering context to share the display-list space of another rendering context. Any number of rendering contexts can share a single display-list space.


Extending OpenGL Functions

The OpenGL library supports multiple implementations of its functions. Extension functions supported in one rendering context aren’t necessarily supported in a different rendering context. For a given rendering context in an application using extension functions, use only the function addresses returned by the wglGetProcAddress function.


GLX and WGL/Win32

Some of the WGL functions, new Win32 functions, and existing Win32 functions are more or less analogous to GLX X Window functions. The following list shows GLX functions and their corresponding WGL/Win32 functions, if available.

GLX Functions	WGL/Win32 Functions
glXChooseVisual	ChoosePixelFormat
glXCopyContext	—
glXCreateContext	wglCreateContext
glXCreateGLXPixmap	CreateDIBitmap/ CreateDIBSection
glXDestroyContext	wglDeleteContext
glXDestroyGLXPixmap	DeleteObject
glXGetConfig	DescribePixelFormat
glXGetCurrentContext	wglGetCurrentContext
glXGetCurrentDrawable	wglGetCurrentDC
glXIsDirect	—
glXMakeCurrent	wglMakeCurrent
glXQueryExtension	GetVersion
glXQueryVersion	GetVersion
glXSwapBuffers	SwapBuffers
glXUseXFont	wglUseFontBitmaps/ wglUseFontOutlines
glXWaitGL	—
glXWaitX	—
XGetVisualInfo	GetPixelFormat
XCreateWindow	CreateWindow/CreateWindowEx and GetDC/BeginPaint
XSync	GdiFlush
—	SetPixelFormat
—	wglGetProcAddress
—	wglShareLists
For more information, refer to the Porting Guide.


Using OpenGL on Windows NT and Windows 95

The following topics explain how to use several features specific to Windows NT and Windows 95 of the Microsoft implementation of OpenGL.


Header Files

Applications that use:

•	The core OpenGL functions must include the header file <GL\GL.H>.

•	The OpenGL Utility library must include the header file <GL\GLU.H>.

•	The OpenGL Programming Guide auxiliary library must include the header file <GL\GLAUX.H>.

•	The WGL functions must include the header file WINDOWS.H.

•	The new Win32 functions that support Microsoft’s implementation of OpenGL in Windows NT and Windows 95 must include the header file WINDOWS.H.


Pixel Format Tasks

You set a device-context pixel format prior to creating an OpenGL rendering context.


Choosing and Setting a Best-Match Pixel Format

This topic explains the procedure for matching a device context to a pixel format.

To obtain a device context’s best match to a pixel format

1.	Specify the desired pixel format in a PIXELFORMATDESCRIPTOR structure.

2.	Call ChoosePixelFormat.

The ChoosePixelFormat function returns a pixel format index, which you can then pass to SetPixelFormat to set the best pixel format match as the device context’s current pixel format.

The following code sample shows how to carry out the above steps:

PIXELFORMATDESCRIPTOR pfd = {

    sizeof(PIXELFORMATDESCRIPTOR),    // size of this pfd

    1,                                // version number

    PFD_DRAW_TO_WINDOW |              // support window

    PFD_SUPPORT_OPENGL |              // support OpenGL

    PFD_DOUBLEBUFFER,                 // double buffered

    PFD_TYPE_RGBA,                    // RGBA type

    24,                               // 24-bit color depth

    0, 0, 0, 0, 0, 0,                 // color bits ignored

    0,                                // no alpha buffer

    0,                                // shift bit ignored

    0,                                // no accumulation buffer

    0, 0, 0, 0,                       // accum bits ignored

    32,                               // 32-bit z-buffer

    0,                                // no stencil buffer

    0,                                // no auxiliary buffer

    PFD_MAIN_PLANE,                   // main layer

    0,                                // reserved

    0, 0, 0                           // layer masks ignored

};

HDC  hdc;

int  iPixelFormat;

// get the device context's best, available pixel format match

iPixelFormat = ChoosePixelFormat(hdc, &pfd);

// make that match the device context's current pixel format

SetPixelFormat(hdc, iPixelFormat, &pfd);


Examining a Device Context's Current Pixel Format
Examining a Device Context’s Current Pixel Format

Use the GetPixelFormat and DescribePixelFormat functions to examine a device context’s current pixel format, as shown in the following code fragment:

PIXELFORMATDESCRIPTOR  pfd;

HDC    hdc;

int    iPixelFormat;

// if the device context has a current pixel format ...

if (iPixelFormat = GetPixelFormat(hdc)) {

    // obtain a detailed description of that pixel format

    DescribePixelFormat(hdc, iPixelFormat,

                             sizeof(PIXELFORMATDESCRIPTOR), &pfd);

    }


Examining a Device's Supported Pixel Formats
Examining a Device’s Supported Pixel Formats

The DescribePixelFormat function obtains pixel format data for a device context. It also returns an integer that is the maximum pixel format index for the device context. The following code sample shows how to use that result to step through and examine the pixel formats supported by a device:

// local variables

int                      iMax ;

PIXELFORMATDESCRIPTOR    pfd;

int                      iPixelFormat ;

// initialize a pixel format index variable

iPixelFormat = 1;

// keep obtaining and examining pixel format data...

do {

    // try to obtain some pixel format data

    iMax = DescribePixelFormat(hdc, iPixelFormat, sizeof(pfd), &pfd);

    // if there was some problem with that...

    if (iMax == 0)

        // return indicating failure

        return(FALSE);

    // we have successfully obtained pixel format data

    // let's examine the pixel format data...

    myPixelFormatExaminer (&pfd);

    }

// ...until we've looked at all the device context's pixel formats

while (++iPixelFormat <= iMax);


Rendering Context Tasks

All calls pass through a rendering context. After you set a device context’s pixel format, you can create a rendering context.


Creating a Rendering Context and Making It Current

The following code sample shows how to create an OpenGL rendering context in response to a WM_CREATE message. Notice that you set up the pixel format before creating the rendering context. Also notice that in this scenario the device context is not released locally; you release it when the window is closed, after making the rendering context not current. For more information, see Deleting a Rendering Context. Finally, notice that you can use local variables for the device context and rendering context handles, because with the wglGetCurrentContext and wglGetCurrentDC functions you can obtain handles to those contexts as needed.

// a window has been created, but is not yet visible

case WM_CREATE:

    {

    // local variables

    HDC      hdc ;

    HGLRC    hglrc ;

    // obtain a device context for the window

    hdc = GetDC(hWnd);

    // set an appropriate pixel format

    myPixelFormatSetupFunction(hdc);

    // if we can create a rendering context ...

    if (hglrc = wglCreateContext( hdc ) ) {

        // try to make it the thread's current rendering context

        bHaveCurrentRC = wglMakeCurrent(hdc, hglrc) ;

        }

    // perform miscellaneous other WM_CREATE chores ...

    }

    break ;


Making a Rendering Context Not Current

To detach a rendering context from a thread, make it not current. You can do this by calling the wglMakeCurrent function with the parameters set to NULL. The following is a sample of this simple task:

// detach the current rendering context from the thread

wglMakeCurrent(NULL, NULL);


Deleting a Rendering Context

The following code sample shows how to delete an OpenGL rendering context when an OpenGL window is closed. It is a continuation of the scenario used in Creating a Rendering Context and Making It Current.

// a window is about to be destroyed

case WM_DESTROY:

    {

    // local variables

    HGLRC    hglrc;

    HDC      hdc ;

    // if the thread has a current rendering context ...

    if(hglrc = wglGetCurrentContext()) {

        // obtain its associated device context

        hdc = wglGetCurrentDC() ;

        // make the rendering context not current

        wglMakeCurrent(NULL, NULL) ;

        // release the device context

        ReleaseDC (hwnd, hdc) ;

        // delete the rendering context

        wglDeleteContext(hglrc);

        }


Drawing with Double Buffers

Double buffers smooth the transition between one image and another on the screen. Swapping buffers typically comes at the end of a sequence of drawing commands. By default, the Microsoft implementation of OpenGL in Windows NT and Windows 95 draws to the off-screen buffer; when drawing is complete, you call the SwapBuffers function to copy the off-screen buffer to the on-screen buffer. The following code sample prepares to draw, calls a drawing function, and then copies the completed image on to the screen if double buffering is available.

void myRedraw(void)

{

    // set up for drawing commands

    glMatrixMode(GL_PROJECTION);

    glLoadIdentity();

    gluPerspective(45, 1.0, 0.1, 100.0);

    // draw our objects

    myDrawAllObjects(GL_FALSE);

    // if we're double-buffering ...

    if (bDoubleBuffering)

        // ...draw the copied image to the screen

        SwapBuffers(hdc);

}

The following code sample obtains a window device context, renders a scene, copies the image to the screen (to show the rendering), and then releases the device context.

hdc = GetDC(hwnd);

mySceneRenderingFunction();

SwapBuffers(hdc);

ReleaseDC(hWnd, hdc);


Drawing Text in a Double-Buffered OpenGL Window

You draw text in a double-buffered OpenGL window by creating display lists for selected characters in a font, and then executing the appropriate display list for each character you want to draw. The following code sample creates a rendering context, draws a red triangle, and then labels it with text. For this sample code, we assume that there is a device context, with a font and pixel format.

// create an OpenGL rendering context

hglrc = wglCreateContext(hdc);

// make it this thread's current rendering context

wglMakeCurrent(hdc, hglrc);

// make the color a deep blue hue

glClearColor(0.0F, 0.0F, 0.4F, 1.0F);

// make the shading smooth

glShadeModel(GL_SMOOTH);

// clear the color buffers

glClear(GL_COLOR_BUFFER_BIT);

// specify a red triangle

glBegin(GL_TRIANGLES);

    glColor3f(1.0F, 0.0F, 0.0F);

    glVertex2f(10.0F, 10.0F);

    glVertex2f(250.0F, 50.0F);

    glVertex2f(105.0F, 280.0F);

glEnd();

// create bitmaps for the device context font's first 256 glyphs

wglUseFontBitmaps(hdc, 0, 256, 1000);

// move bottom left, southwest of the red triangle

glRasterPos2f(30.0F, 300.0F);

// set up for a string-drawing display list call

glListBase(1000);

// draw a string using font display lists

glCallLists(12, GL_UNSIGNED_BYTE, "Red Triangle");

// get all those commands to execute

glFlush();

// delete our 256 glyph display lists

glDeleteLists(1000, 256) ;

// make the rendering context not current

wglMakeCurrent (NULL, NULL) ;

// release the device context

ReleaseDC(hdc) ;

// delete the rendering context

wglDeleteContext(hglrc);


Printing an OpenGL Image

You can print OpenGL images rendered in enhanced metafiles. When you render to a printer device (HDC) it must be backed by a metafile spooler. OpenGL uses memory for depth, color, and other buffers to store graphics output to a printer. Because typical printer resolution requires a significant amount of memory to store the graphics output, printing an OpenGL image might require more memory than is available in the system. To overcome this limitation, the current implementation of OpenGL prints OpenGL graphics in bands. However, this increases the time it takes to print OpenGL images.

Before you print an OpenGL image, you must call the StartDoc function to complete the initialization of a printer device context (DC). After calling StartDoc, you can create rendering contexts (HGLRC) to render to the printer device. If you create rendering contexts before calling StartDoc, there is no way to determine whether a metafile is spooled.

The following code sample shows how to print an OpenGL image:

HDC            hDC;

DOCINFO        di;

HGLRC          hglrc;

// Call StartDoc to start the document

StartDoc( hDC, &di );

// Prepare the printer driver to accept data

StartPage(hDC);

// Create a rendering context using the metafile DC

hglrc = wglCreateContext ( hDCmetafile );

// Do OpenGL rendering operations here

    . . .

wglMakeCurrent(NULL, NULL); // Get rid of rendering context

    . . .

EndPage(hDC); // Finish writing to the page

EndDoc(hDC); // End the print job

For more information on using metafiles, see Enhanced Metafile Operations.


Copying an OpenGL Image to the Clipboard

Although the current version of the Microsoft implementation of OpenGL in Windows NT and Windows 95 does not directly support the Clipboard, you can copy a Windows NT or Windows 95 OpenGL image to the Clipboard.

To copy an OpenGL image to the Clipboard

1.	Draw the image to a memory bitmap or an enhanced metafile.

2.	Copy that bitmap to the Clipboard.


Multithread OpenGL Drawing Strategies

The GDI does not support multiple threads. You must use a distinct device context and a distinct rendering context for each thread. This tends to limit the performance advantages of using multiple threads with single-processor systems running OpenGL applications. However, there are ways to use threads with a single processor system to greatly increase performance. For example, you can use a separate thread to pass OpenGL rendering calls to dedicated 3-D hardware.

Symmetric multiprocessing (SMP) systems can greatly benefit from using multiple threads. An obvious strategy is to use a separate thread for each processor to handle OpenGL rendering in separate windows. For example, in a flight-simulation application you could use separate processors and threads to render the front, back, and side views.

A thread can have only one current, active rendering context. When you use multiple threads and multiple rendering contexts, you must be careful to synchronize their use. For example, use one thread only to call SwapBuffers after all threads finish drawing.


Using the Auxiliary Library

Using OpenGL, Silicon Graphics (SGI) created the Auxiliary Library to write simple sample programs for the OpenGL Programming Guide. The source code for the Auxiliary Library is supplied with the Win32 SDK, along with the OpenGL samples. To understand how the Auxiliary Library was developed from OpenGL functions and routines, examine the source code. You can use Auxiliary Library functions in your own programs. For a description of the Auxiliary Library, see the OpenGL Programming Guide.


Reference for Win 32 Extensions to OpenGL

The following sections contain listings of the functions and structures associated with WGL and Win32.


WGL Functions

wglCopyContext

wglCreateContext

wglCreateLayerContext

wglDeleteContext

wglDescribeLayerPlane

wglGetCurrentContext

wglGetCurrentDC

wglGetLayerPaletteEntries

wglGetProcAddress

wglMakeCurrent

wglRealizeLayerPalette

wglSetLayerPaletteEntries

wglShareLists

wglSwapLayerBuffers

wglUseFontBitmaps

wglUseFontOutlines


Win32 Functions

ChoosePixelFormat

DescribePixelFormat

GetEnhMetaFilePixelFormat

GetPixelFormat

SetPixelFormat

SwapBuffers


Structures

GLYPHMETRICSFLOAT

LAYERPLANEDESCRIPTOR

PIXELFORMATDESCRIPTOR

POINTFLOAT


glAccum [New - Windows 95, OEM Service Release 2]
glAccum

[New - Windows 95, OEM Service Release 2]

The glAccum function operates on the accumulation buffer.

void glAccum(

GLenum op,
GLfloat value
);
Parameters

op

The accumulation buffer operation. The accepted symbolic constants are:

GL_ACCUM

Obtains R, G, B, and A values from the buffer currently selected for reading (see glReadBuffer). Each component value is divided by 2n − 1, where n is the number of bits allocated to each color component in the currently selected buffer. The result is a floating-point value in the range [0,1], which is multiplied by value and added to the corresponding pixel component in the accumulation buffer, thereby updating the accumulation buffer.

GL_LOAD

Similar to GL_ACCUM, except that the current value in the accumulation buffer is not used in the calculation of the new value. That is, the R, G, B, and A values from the currently selected buffer are divided by 2n − 1, multiplied by value, and then stored in the corresponding accumulation buffer cell, overwriting the current value.

GL_ADD

Adds value to each R, G, B, and A in the accumulation buffer.

GL_MULT

Multiplies each R, G, B, and A in the accumulation buffer by value and returns the scaled component to its corresponding accumulation buffer location.

GL_RETURN

Transfers accumulation buffer values to the color buffer or buffers currently selected for writing. Each R, G, B, and A component is multiplied by value, then multiplied by 2n − 1, clamped to the range [0, 2n − 1 ], and stored in the corresponding display buffer cell. The only fragment operations that are applied to this transfer are pixel ownership, scissor, dithering, and color writemasks.

value

A floating-point value used in the accumulation buffer operation. The op parameter determines how value is used.

Remarks

The accumulation buffer is an extended-range color buffer. Images are not rendered into it. Rather, images rendered into one of the color buffers are added to the contents of the accumulation buffer after rendering. You can create effects such as antialiasing (of points, lines, and polygons), motion blur, and depth of field by accumulating images generated with different transformation matrices.

Each pixel in the accumulation buffer consists of red, green, blue, and alpha values. The number of bits per component in the accumulation buffer depends on the implementation. You can examine this number by calling glGetIntegerv four times, with the arguments GL_ACCUM_RED_BITS, GL_ACCUM_GREEN_BITS, GL_ACCUM_BLUE_BITS, and GL_ACCUM_ALPHA_BITS, respectively. Regardless of the number of bits per component, however, the range of values stored by each component is [ − 1, 1]. The accumulation buffer pixels are mapped one-to-one with frame buffer pixels.

The glAccum function operates on the accumulation buffer. The first argument, op, is a symbolic constant that selects an accumulation buffer operation. The second argument, value, is a floating-point value to be used in that operation. Five operations are specified: GL_ACCUM, GL_LOAD, GL_ADD, GL_MULT, and GL_RETURN.

All accumulation buffer operations are limited to the area of the current scissor box and are applied identically to the red, green, blue, and alpha components of each pixel. The contents of an accumulation buffer pixel component are undefined if the glAccum operation results in a value outside the range [ − 1,1]. The operations are as follows:

To clear the accumulation buffer, use the glClearAccum function to specify R, G, B, and A values to set it to, and issue a glClear function with the accumulation buffer enabled.

Only those pixels within the current scissor box are updated by any glAccum operation.

The following functions retrieve information related to the glAccum function:

glGet with argument GL_ACCUM_RED_BITS

glGet with argument GL_ACCUM_GREEN_BITS

glGet with argument GL_ACCUM_BLUE_BITS

glGet with argument GL_ACCUM_ALPHA_BITS

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	op was not an accepted value.
GL_INVALID_OPERATION	There was no accumulation buffer.
GL_INVALID_OPERATION	glAccum was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glBlendFunc, glClear, glClearAccum, glCopyPixels, glEnd, glGet, glLogicOp, glPixelStore, glPixelTransfer, glReadBuffer, glReadPixels, glScissor, glStencilOp


glAddSwapHintRectWIN [New - Windows 95, OEM Service Release 2]
glAddSwapHintRectWIN

[New - Windows 95, OEM Service Release 2]

The glAddSwapHintRectWIN function specifies a set of rectangles that are to be copied by SwapBuffers.

void glAddSwapHintRectWIN(

GLint x,
GLint y,
GLsizei width,
GLsizei height
);
Parameters

x

The x-coordinate (in window coordinates) of the lower-left corner of the hint region rectangle.

y

The y-coordinate (in window coordinates) of the lower-left corner of the hint region rectangle.

width

The width of the hint region rectangle.

height

The height of the hint region rectangle.

Remarks

The glAddSwapHintRectWIN function speeds up animation by reducing the amount of repainting between frames. With glAddSwapHintRectWIN, you specify a set of rectangular areas that you want copied when you call SwapBuffers. When you do not specify any rectangles with glAddSwapHintRectWIN before calling SwapBuffers, the entire frame buffer is swapped. Using glAddSwapHintRectWIN to copy only parts of the buffer that changed can significantly increase the performance of SwapBuffers, especially when SwapBuffers is implemented in software.

The glAddSwapHintRectWIN function adds a rectangle to the hint region. When the PFD_SWAP_COPY flag of the PIXELFORMATDESCRIPTOR pixel format structure is set, SwapBuffers uses this region to clip the copying of the back buffer to the front buffer. You don’t specify PFD_SWAP_COPY; it is set by capable hardware. The hint region is cleared after each call to SwapBuffers. With some hardware configurations, SwapBuffers can ignore the hint region and exchange the entire buffer. SwapBuffers is implemented by the system, not by the application.

OpenGL maintains a separate hint region for each window. When you call glAddSwapHintRectWIN on any rendering contexts associated with a window, the hint rectangles are combined into a single region.

Call glAddSwapHintRectWIN with a bounding rectangle for each object drawn for a frame and for each rectangle cleared to erase previous frame objects.

Note  The glAddSwapHintRectWIN function is an extension function that is not part of the standard OpenGL library but is part of the GL_WIN_swap_hint extension. To check whether your implementation of OpenGL supports glAddSwapHintRectWIN, call glGetString(GL_EXTENSIONS). If it returns GL_WIN_swap_hint, glAddSwapHintRectWIN is supported. To obtain the address of an extension function, call wglGetProcAddress.

See Also

glGetString, PIXELFORMATDESCRIPTOR, SwapBuffers, wglGetProcAddress


glAlphaFunc [New - Windows 95, OEM Service Release 2]
glAlphaFunc

[New - Windows 95, OEM Service Release 2]

The glAlphaFunc function specifies the alpha test function.

void glAlphaFunc(

GLenum func,
GLclampf ref
);
Parameters

func

The alpha comparison function. The following are the accepted symbolic constants and their meanings.

Symbolic Constant	Meaning
GL_NEVER	Never passes.
GL_LESS	Passes if the incoming alpha value is less than the reference value.
GL_EQUAL	Passes if the incoming alpha value is equal to the reference value.
GL_LEQUAL	Passes if the incoming alpha value is less than or equal to the reference value.
GL_GREATER	Passes if the incoming alpha value is greater than the reference value.
GL_NOTEQUAL	Passes if the incoming alpha value is not equal to the reference value.
GL_GEQUAL	Passes if the incoming alpha value is greater than or equal to the reference value.
GL_ALWAYS	Always passes. This is the default.
ref

The reference value to which incoming alpha values are compared. This value is clamped to the range 0 through 1, where 0 represents the lowest possible alpha value and 1 the highest possible value. The default reference is 0.

Remarks

The alpha test discards fragments depending on the outcome of a comparison between the incoming fragments’ alpha values and a constant reference value. The glAlphaFunc function specifies the reference and comparison function. The comparison is performed only if alpha testing is enabled. (For more information on GL_ALPHA_TEST, see glEnable.)

The func and ref parameters specify the conditions under which the pixel is drawn. The incoming alpha value is compared to ref using the function specified by func. If the comparison passes, the incoming fragment is drawn, conditional on subsequent stencil and depth-buffer tests. If the comparison fails, no change is made to the frame buffer at that pixel location.

The glAlphaFunc function operates on all pixel writes, including those resulting from the scan conversion of points, lines, polygons, and bitmaps, and from pixel draw and copy operations. The glAlphaFunc function does not affect screen clear operations.

Alpha testing is done only in RGBA mode.

The following functions retrieve information related to the glAlphaFunc function:

glGet with argument GL_ALPHA_TEST_FUNC

glGet with argument GL_ALPHA_TEST_REF

glIsEnabled with argument GL_ALPHA_TEST

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	func was not an accepted value.
GL_INVALID_OPERATION	glAlphaFunc was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glBlendFunc, glClear, glDepthFunc, glEnable, glEnd, glGet, glIsEnabled, glStencilFunc


glAreTexturesResident [New - Windows 95, OEM Service Release 2]
glAreTexturesResident

[New - Windows 95, OEM Service Release 2]

The glAreTexturesResident function determines whether specified texture objects are resident.

GLboolean glAreTexturesResident(

GLsizei n,
GLuint * textures
GLboolean * residences
);
Parameters

n

The number of textures to be queried.

textures

The address of an array containing the names of the textures to be queried.

residences

The address of an array in which the texture residence status is returned. The residence status of a texture named by an element of textures is returned in the corresponding element of residences.

Remarks

On machines with a limited amount of texture memory, OpenGL establishes a ``working set'' of textures that are resident in texture memory. These textures can be bound to a texture target much more efficiently than textures that are not resident.

The glAreTexturesResident function queries the texture residence status of the n textures named by the elements of textures. If all the named textures are resident, glAreTexturesResident returns GL_TRUE, and the contents of residences are undisturbed. If any of the named textures are not resident, glAreTexturesResident returns GL_FALSE, and detailed status is returned in the n elements of residences.

If an element of residences is GL_TRUE, then the texture named by the corresponding element of textures is resident.

To query the residence status of a single bound texture, call glGetTexParameter with the target parameter set to the target texture to which the target is bound and set the pname parameter to GL_TEXTURE_RESIDENT. You must use this method to query the resident status of a default texture.

You cannot include glAreTexturesResident in display lists.

Note  The glAreTexturesResident function is only available in OpenGL version 1.1 or later.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	n was a negative value.
GL_INVALID_VALUE	An element in textures was zero or did not contain a texture name.
GL_INVALID_OPERATION	glAreTexturesResident was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glBindTexture, glEnd, glGetTexParameter, glPrioritizeTextures, glTexImage1D, glTexImage2D


glArrayElement [New - Windows 95, OEM Service Release 2]
glArrayElement

[New - Windows 95, OEM Service Release 2]

The glArrayElement function specifies the array elements used to render a vertex.

void glArrayElement(

GLint index
);
Parameters

index

An index in the enabled arrays.

Remarks

Use the glArrayElement function within glBegin and glEnd pairs to specify vertex and attribute data for point, line, and polygon primitives. The glArrayElement function specifies the data for a single vertex using vertex and attribute data located at the index of the enabled vertex arrays.

You can use glArrayElement to construct primitives by indexing vertex data, rather than by streaming through arrays of data in first-to-last order. Because glArrayElement specifies a single vertex only, you can explicitly specify attributes for individual primitives. For example, you can set a single normal for each individual triangle.

When you include calls to glArrayElement in display lists, the necessary array data, determined by the array pointers and enable values, is entered in the display list also. Array pointer and enable values are determined when display lists are created, not when display lists are executed.

You can read and cache static array data at any time with glArrayElement. When you modify the elements of a static array without specifying the array again, the results of any subsequent calls to glArrayElement are undefined.

When you call glArrayElement without first calling glEnableClientState(GL_VERTEX_ARRAY), no drawing occurs, but the attributes corresponding to enabled arrays are modified. Although no error is generated when you specify an array within glBegin and glEnd pairs, the results are undefined.

See Also

glBegin, glColorPointer, glDrawArrays, glEdgeFlagPointer, glEnableClientState, glEnd, glGetPointerv, glGetString, glIndexPointer, glNormalPointer, glTexCoordPointer, glVertexPointer


glBegin, glEnd [New - Windows 95, OEM Service Release 2]
glBegin, glEnd

[New - Windows 95, OEM Service Release 2]

The glBegin and glEnd functions delimit the vertices of a primitive or a group of like primitives.

void glBegin(

GLenum mode
);
void glEnd(

void
);
Parameters

mode

The primitive or primitives that will be created from vertices presented between glBegin and the subsequent glEnd. The following are accepted symbolic constants and their meanings:

GL_POINTS

Treats each vertex as a single point. Vertex n defines point n. N points are drawn.

GL_LINES

Treats each pair of vertices as an independent line segment. Vertices 2n − 1 and 2n define line n. N/2 lines are drawn.

GL_LINE_STRIP

Draws a connected group of line segments from the first vertex to the last. Vertices n and n+1 define line n. N − 1 lines are drawn.

GL_LINE_LOOP

Draws a connected group of line segments from the first vertex to the last, then back to the first. Vertices n and n+1 define line n. The last line, however, is defined by vertices N and 1. N lines are drawn.

GL_TRIANGLES

Treats each triplet of vertices as an independent triangle. Vertices 3n − 2, 3n −1, and 3n define triangle n. N/3 triangles are drawn.

GL_TRIANGLE_STRIP

Draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices. For odd n, vertices n, n + 1, and n + 2 define triangle n. For even n, vertices n + 1, n, and n + 2 define triangle n. N − 2 triangles are drawn.

GL_TRIANGLE_FAN

Draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices. Vertices 1, n + 1, and n + 2 define triangle n. N − 2 triangles are drawn.

GL_QUADS

Treats each group of four vertices as an independent quadrilateral. Vertices 4n − 3, 4n − 2, 4n − 1, and 4n define quadrilateral n. N/4 quadrilaterals are drawn.

GL_QUAD_STRIP

Draws a connected group of quadrilaterals. One quadrilateral is defined for each pair of vertices presented after the first pair. Vertices 2n − 1, 2n, 2n + 2, and 2n + 1 define quadrilateral n. N quadrilaterals are drawn. Note that the order in which vertices are used to construct a quadrilateral from strip data is different from that used with independent data.

GL_POLYGON

Draws a single, convex polygon. Vertices 1 through N define this polygon.

Remarks

The glBegin and glEnd functions delimit the vertices that define a primitive or a group of like primitives. The glBegin function accepts a single argument that specifies which of ten ways the vertices are interpreted. Taking n as an integer count starting at one, and N as the total number of vertices specified, the interpretations are as follows:

•	You can use only a subset of OpenGL functions between glBegin and glEnd. The functions you can use are:

glVertex
glColor
glIndex
glNormal
glTexCoord
glEvalCoord
glEvalPoint
glMaterial
glEdgeFlag

You can also use glCallList or glCallLists to execute display lists that include only the preceding functions. If any other OpenGL function is called between glBegin and glEnd, the error flag is set and the function is ignored.

•	Regardless of the value chosen for mode in glBegin, there is no limit to the number of vertices you can define between glBegin and glEnd. Lines, triangles, quadrilaterals, and polygons that are incompletely specified are not drawn. Incomplete specification results when either too few vertices are provided to specify even a single primitive or when an incorrect multiple of vertices is specified. The incomplete primitive is ignored; the complete primitives are drawn.

•	The minimum specification of vertices for each primitive is:

Minimum Number  of Vertices	Type of Primitive
1	point
2	line
3	triangle
4	quadrilateral
3	polygon
Modes that require a certain multiple of vertices are GL_LINES (2), GL_TRIANGLES (3), GL_QUADS (4), and GL_QUAD_STRIP (2).

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	mode was set to an unaccepted value.
GL_INVALID_OPERATION	A function other than glVertex, glColor, glIndex, glNormal, glTexCoord, glEvalCoord, glEvalPoint, glMaterial, glEdgeFlag, glCallList, or glCallLists was called between glBegin and the corresponding glEnd.
GL_INVALID_OPERATION	glEnd was called before the corresponding glBegin was called, or glBegin was called within a glBegin/glEnd sequence.
See Also

glCallList, glCallLists, glColor, glEdgeFlag, glEvalCoord, glEvalPoint, glIndex, glMaterial, glNormal, glTexCoord, glVertex


glBindTexture [New - Windows 95, OEM Service Release 2]
glBindTexture

[New - Windows 95, OEM Service Release 2]

The glBindTexture function enables the creation of a named texture that is bound to a texture target.

void glBindTexture(

GLenum target,
GLuint texture
);
Parameters

target

The target to which the texture is bound. Must have the value GL_TEXTURE_1D or GL_TEXTURE_2D.

texture

The name of a texture; the texture name cannot currently be in use.

Remarks

The glBindTexture function enables you to create a named texture. Calling glBindTexture with target set to GL_TEXTURE_1D or GL_TEXTURE_2D, and texture set to the name of the new texture you have created binds the texture name to the appropriate texture target. When a texture is bound to a target, the previous binding for that target is no longer in effect.

Texture names are unsigned integers with the value zero reserved to represent the default texture for each texture target. Texture names and the corresponding texture contents are local to the shared display-list space of the current OpenGL rendering context; two rendering contexts share texture names only if they also share display lists. You can generate a set of new texture names using glGenTextures.

When a texture is first bound, it assumes the dimensionality of its texture target; a texture bound to GL_TEXTURE_1D becomes one-dimensional and a texture bound to GL_TEXTURE_2D becomes two-dimensional. Operations you perform on a texture target also affect a texture bound to the target. When you query a texture target, the return value is the state of the texture bound to it. Texture targets become aliases for textures currently bound to them.

When you bind a texture with glBindTexture, the binding remains active until a different texture is bound to the same target or you delete the bound texture with the glDeleteTextures function. Once you create a named texture you can bind it to a texture target that has the same dimensionality as often as needed.

It is usually much faster to use glBindTexture to bind an existing named texture to one of the texture targets than it is to reload the texture image using glTexImage1D or glTexImage2D. For additional control of texturing performance, use glPrioritizeTextures.

You can include calls to glBindTexture in display lists.

Note  The glBindTexture function is only available in OpenGL version 1.1 or later.

The following functions retrieve information related to glBindTexture:

glGet with argument GL_TEXTURE_1D_BINDING

glGet with argument GL_TEXTURE_2D_BINDING

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target was not an accepted value.
GL_INVALID_OPERATION	texture did not have the same dimensionality as target.
GL_INVALID_OPERATION	glBindTexture was called between a call to glBegin and the corresponding call to glEnd.
See Also

glAreTexturesResident, glDeleteTextures, glGenTextures, glGet, glGetTexParameter, glIsTexture, glPrioritizeTextures, glTexImage1D, glTexImage2D, glTexParameter


glBitmap [New - Windows 95, OEM Service Release 2]
glBitmap

[New - Windows 95, OEM Service Release 2]

The glBitmap function draws a bitmap.

void glBitmap(

GLsizei width,
GLsizei height,
GLfloat xorig,
GLfloat yorig,
GLfloat xmove,
GLfloat ymove,
const GLubyte * bitmap
);
Parameters

width, height

The pixel width and height of the bitmap image.

xorig, yorig

The location of the origin in the bitmap image. The origin is measured from the lower-left corner of the bitmap, with right and up directions being the positive axes.

xmove, ymove

The x and y offsets to be added to the current raster position after the bitmap is drawn.

bitmap

The address of the bitmap image.

Remarks

A bitmap is a binary image. When drawn, the bitmap is positioned relative to the current raster position, and frame buffer pixels corresponding to 1s in the bitmap are written using the current raster color or index. Frame-buffer pixels corresponding to zeros in the bitmap are not modified.

The bitmap image is interpreted like image data for the glDrawPixels function, with width and height corresponding to the width and height arguments of that function, and with type set to GL_BITMAP and format set to GL_COLOR_INDEX. Modes you specify using glPixelStore affect the interpretation of bitmap image data; modes you specify using glPixelTransfer do not.

If the current raster position is invalid, glBitmap is ignored. Otherwise, the lower-left corner of the bitmap image is positioned at the following window coordinates:

x (w)  =  x (r)  − x (o)

y (w)  =  y (r)  − y (o)

In these coordinates, (xr, yr) is the raster position, and (xo, yo) is the bitmap origin. Fragments are then generated for each pixel corresponding to a 1 in the bitmap image. These fragments are generated using the current raster z-coordinate, color or color index, and current raster texture coordinates. They are then treated just as if they had been generated by a point, line, or polygon, including texture mapping, fogging, and all per-fragment operations such as alpha and depth testing.

After the bitmap has been drawn, the x and y coordinates of the current raster position are offset by xmove and ymove. No change is made to the z-coordinate of the current raster position, or to the current raster color, index, or texture coordinates.

The following functions retrieve information related to the glBitmap function:

glGet with argument GL_CURRENT_RASTER_POSITION
glGet with argument GL_CURRENT_RASTER_COLOR
glGet with argument GL_CURRENT_RASTER_INDEX
glGet with argument GL_CURRENT_RASTER_TEXTURE_COORDS
glGet with argument GL_CURRENT_RASTER_POSITION_VALID

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	width or height is negative.
GL_INVALID_OPERATION	glBitmap is called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glDrawPixels, glEnd, glPixelStore, glPixelTransfer, glRasterPos


glBlendFunc [New - Windows 95, OEM Service Release 2]
glBlendFunc

[New - Windows 95, OEM Service Release 2]

The glBlendFunc function specifies pixel arithmetic.

void glBlendFunc(

GLenum sfactor,
GLenum dfactor
);
Parameters

sfactor

Specifies how the red, green, blue, and alpha source-blending factors are computed. Nine symbolic constants are accepted: GL_ZERO, GL_ONE, GL_DST_COLOR, GL_ONE_MINUS_DST_COLOR, GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA, GL_DST_ALPHA, GL_ONE_MINUS_DST_ALPHA, and GL_SRC_ALPHA_SATURATE.

dfactor

Specifies how the red, green, blue, and alpha destination-blending factors are computed. Eight symbolic constants are accepted: GL_ZERO, GL_ONE, GL_SRC_COLOR, GL_ONE_MINUS_SRC_COLOR, GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA, GL_DST_ALPHA, and GL_ONE_MINUS_DST_ALPHA.

Remarks

In RGB mode, pixels can be drawn using a function that blends the incoming (source) RGBA values with the RGBA values that are already in the frame buffer (the destination values). By default, blending is disabled. Use glEnable and glDisable with the GL_BLEND argument to enable and disable blending.

When enabled, glBlendFunc defines the operation of blending. The sfactor parameter specifies which of nine methods is used to scale the source color components. The dfactor parameter specifies which of eight methods is used to scale the destination color components. The eleven possible methods are described in the following table. Each method defines four scale factors, one each for red, green, blue, and alpha.

In the table and in subsequent equations, source and destination color components are referred to as (R (s) ,G (s) ,B (s) ,A (s) ) and (R (d) ,G (d) ,B (d) ,A (d) ). They are understood to have integer values between zero and (k (R) ,k (G) ,k (B) ,k (A) ), where

k (c)  = 2^m (c)  − 1

and (m (R) ,m (G) ,m (B) ,m (A) ) is the number of red, green, blue, and alpha bitplanes.

Source and destination scale factors are referred to as (s (R) ,s (G) ,s (B) ,s (A) ) and (d (R) ,d (G) ,d (B) ,d (A) ). The scale factors described in the table, denoted (f (R) ,f (G) ,f (B) ,f (A) ), represent either source or destination factors. All scale factors have range [0,1].

Parameter	(f (R) ,f (G) ,f (B) ,f (A) )
GL_ZERO	(0,0,0,0)
GL_ONE	(1,1,1,1)
GL_SRC_COLOR	(R (s) /k (R) ,G (s) /k (G) ,B (s) /k (B) ,A (s) /k (A) )
GL_ONE_MINUS_SRC_COLOR	(1,1,1,1). (R (s) /k (R) ,G (s) /k (G) ,B (s) /k (B) ,A (s) /k (A) )
GL_DST_COLOR	(R (d) /k (R) ,G (d) /k (G) ,B (d) /k (B) ,A (d) /k (A) )
GL_ONE_MINUS_DST_COLOR	(1,1,1,1)
GL_SRC_ALPHA	(R (d) /k (R) ,G (d) /k (G) ,B (d) /k (B) ,A (d) /k (A) ) (A (s) /k (A) ,A (s) /k (A) ,A (s) /k (A) ,A (s) /k (A) )
GL_ONE_MINUS_SRC_ALPHA	(1,1,1,1) (A (s) /k (A) ,A (s) /k (A) ,A (s) /k (A) ,A (s) /k (A) )
GL_DST_ALPHA	(A (d) /k (A) ,A (d) /k (A) ,A (d) /k (A) ,A (d) /k (A) )
GL_ONE_MINUS_DST_ALPHA	(1,1,1,1) (A (d) /k (A) ,A (d) /k (A) ,A (d) /k (A) ,A (d) /k (A) )
GL_SRC_ALPHA_SATURATE	(i,i,i,1)
In the table,

i = min (A (s) ,k (A)  − A (d) ) / kA

To determine the blended RGBA values of a pixel when drawing in RGB mode, the system uses the following equations:

R (d)  = min(kR,RssR+RddR)

G (d)  = min(kG,GssG+GddG)

B (d)  = min(kB,BssB+BddB)

A (d)  = min(kA,AssA+AddA)

Despite the apparent precision of the above equations, blending arithmetic is not exactly specified, because blending operates with imprecise integer color values. However, a blend factor that should be equal to one is guaranteed not to modify its multiplicand, and a blend factor equal to zero reduces its multiplicand to zero. Thus, for example, when sfactor is GL_SRC_ALPHA, dfactor is GL_ONE_MINUS_SRC_ALPHA, and A (s)  is equal to k (A) , the equations reduce to simple replacement:

R (d) = R (s)

G (d) = G (s)

B (d) = B (s)

A (d) = A (s

)

Examples

Transparency is best implemented using glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA) with primitives sorted from farthest to nearest. Note that this transparency calculation does not require the presence of alpha bitplanes in the frame buffer.

You can also use glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA) for rendering antialiased points and lines in arbitrary order.

To optimize polygon antialiasing, use glBlendFunc(GL_SRC_ALPHA_SATURATE, GL_ONE) with polygons sorted from nearest to farthest. (See the GL_POLYGON_SMOOTH argument in glEnable for information on polygon antialiasing.) Destination alpha bitplanes, which must be present for this blend function to operate correctly, store the accumulated coverage.

Incoming (source) alpha is a material opacity, ranging from 1.0 (K (A) ), representing complete opacity, to 0.0 (0), representing complete transparency.

When you enable more than one color buffer for drawing, each enabled buffer is blended separately, and the contents of the buffer is used for destination color. (See glDrawBuffer.)

Blending affects only RGB rendering. It is ignored by color-index renderers.

The following functions retrieve information related to glBlendFunc:

glGet with argument GL_BLEND_SRC

glGet with argument GL_BLEND_DST

glIsEnabled with argument GL_BLEND

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	Either sfactor or dfactor was not an accepted value.
GL_INVALID_OPERATION	glBlendFunc was called between a call to glBegin and the corresponding call to glEnd.
See Also

glAlphaFunc, glBegin, glClear, glDisable, glDrawBuffer, glEnable, glGet, glIsEnabled, glLogicOp, glStencilFunc


glCallList [New - Windows 95, OEM Service Release 2]
glCallList

[New - Windows 95, OEM Service Release 2]

The glCallList function executes a display list.

void glCallList(

GLuint list
);
Parameters

list

The integer name of the display list to be executed.

Remarks

You start execution of the named display list with glCallList. The functions saved in the display list are executed in order, just as if you called them without using a display list. If list has not been defined as a display list, glCallList is ignored.

The glCallList function can appear inside a display list. To avoid the possibility of infinite recursion resulting from display lists calling one another, a limit is placed on the nesting level of display lists during display-list execution. This limit is at least 64, and it depends on the implementation.

The OpenGL state is not saved and restored across a call to glCallList. Thus, changes made to the OpenGL state during the execution of a display list remain after execution of the display list is completed. To preserve the OpenGL state across glCallList calls, use glPushAttrib, glPopAttrib, glPushMatrix, and glPopMatrix.

You can execute display lists between a call to glBegin and the corresponding call to glEnd, as long as the display list includes only functions that are allowed in this interval.

The following functions retrieve information related to glCallList:

glGet with argument GL_MAX_LIST_NESTING

glIsList

See Also

glBegin, glCallLists, glDeleteLists, glEnd, glGenLists, glGet, glIsList, glNewList, glPopAttrib, glPopMatrix, glPushAttrib, glPushMatrix


glCallLists [New - Windows 95, OEM Service Release 2]
glCallLists

[New - Windows 95, OEM Service Release 2]

The glCallLists function executes a list of display lists.

void glCallLists(

GLsizei n,
GLenum type,
const GLvoid * lists
);
Parameters

n

The number of display lists to be executed.

type

The type of values in lists. The following symbolic constants are accepted:

GL_BYTE

The lists parameter is treated as an array of signed bytes, each in the range − 128 through 127.

GL_UNSIGNED_BYTE

The lists parameter is treated as an array of unsigned bytes, each in the range 0 through 255.

GL_SHORT

The lists parameter is treated as an array of signed two-byte integers, each in the range  − 32768 through 32767.

GL_UNSIGNED_SHORT

The lists parameter is treated as an array of unsigned two-byte integers, each in the range 0 through 65535.

GL_INT

The lists parameter is treated as an array of signed four-byte integers.

GL_UNSIGNED_INT

The lists parameter is treated as an array of unsigned four-byte integers.

GL_FLOAT

The lists parameter is treated as an array of four-byte, floating-point values.

GL_2_BYTES

The lists parameter is treated as an array of unsigned bytes. Each pair of bytes specifies a single display-list name. The value of the pair is computed as 256 times the unsigned value of the first byte plus the unsigned value of the second byte.

GL_3_BYTES

The lists parameter is treated as an array of unsigned bytes. Each triplet of bytes specifies a single display list name. The value of the triplet is computed as 65536 times the unsigned value of the first byte, plus 256 times the unsigned value of the second byte, plus the unsigned value of the third byte.

GL_4_BYTES

The lists parameter is treated as an array of unsigned bytes. Each quadruplet of bytes specifies a single display list name. The value of the quadruplet is computed as 16777216 times the unsigned value of the first byte, plus 65536 times the unsigned value of the second byte, plus 256 times the unsigned value of the third byte, plus the unsigned value of the fourth byte.

lists

The address of an array of name offsets in the display list. The pointer type is void because the offsets can be bytes, shorts, ints, or floats, depending on the value of type.

Remarks

The glCallLists function causes each display list in the list of names passed as lists to be executed. As a result, the functions saved in each display list are executed in order, just as if they were called without using a display list. Names of display lists that have not been defined are ignored.

The glCallLists function provides an efficient means for executing display lists.The n parameter specifies the number of lists with various name formats (specified by the type parameter) glCallLists executes.

The list of display list names is not null-terminated. Rather, n specifies how many names are to be taken from lists.

The glListBase function makes an additional level of indirection available. The glListBase function specifies an unsigned offset that is added to each display list name specified in lists before that display list is executed.

The glCallLists function can appear inside a display list. To avoid the possibility of infinite recursion resulting from display lists calling one another, a limit is placed on the nesting level of display lists during display list execution. This limit must be at least 64, and it depends on the implementation.

The OpenGL state is not saved and restored across a call to glCallLists. Thus, changes made to the OpenGL state during the execution of the display lists remain after execution is completed. Use glPushAttrib, glPopAttrib, glPushMatrix, and glPopMatrix to preserve the OpenGL state across glCallLists calls.

You can execute display lists between a call to glBegin and the corresponding call to glEnd, as long as the display list includes only functions that are allowed in this interval.

The following functions retrieve information related to the glCallLists function:

glGet with argument GL_LIST_BASE

glGet with argument GL_MAX_LIST_NESTING

glIsList

See Also

glBegin, glCallList, glDeleteLists, glEnd, glGenLists, glGet, glIsList, glListBase, glNewList, glPopAttrib, glPopMatrix, glPushAttrib, glPushMatrix


glClear [New - Windows 95, OEM Service Release 2]
glClear

[New - Windows 95, OEM Service Release 2]

The glClear function clears buffers within the viewport.

void glClear(

GLbitfield mask
);
Parameters

mask

Bitwise OR of masks that indicate the buffers to be cleared. The four masks are as follows.

Mask	Buffer to be Cleared
GL_COLOR_BUFFER_BIT	The buffers currently enabled for color writing.
GL_DEPTH_BUFFER_BIT	The depth buffer.
GL_ACCUM_BUFFER_BIT	The accumulation buffer.
GL_STENCIL_BUFFER_BIT	The stencil buffer.
Remarks

The glClear function sets the bitplane area of the window to values previously selected by glClearColor, glClearIndex, glClearDepth, glClearStencil, and glClearAccum. You can clear multiple color buffers simultaneously by selecting more than one buffer at a time using glDrawBuffer.

The pixel-ownership test, the scissor test, dithering, and the buffer writemasks affect the operation of glClear. The scissor box bounds the cleared region. The alpha function, blend function, logical operation, stenciling, texture mapping, and z-buffering are ignored by glClear.

The glClear function takes a single argument (mask) that is the bitwise OR of several values indicating which buffer is to be cleared.

The value to which each buffer is cleared depends on the setting of the clear value for that buffer.

If a buffer is not present, a glClear call directed at that buffer has no effect.

The following functions retrieve information related to glClear:

glGet with argument GL_ACCUM_CLEAR_VALUE

glGet with argument GL_DEPTH_CLEAR_VALUE

glGet with argument GL_INDEX_CLEAR_VALUE

glGet with argument GL_COLOR_CLEAR_VALUE

glGet with argument GL_STENCIL_CLEAR_VALUE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	Any bit other than the four defined bits was set in mask.
GL_INVALID_OPERATION	glClear was called between a call to glBegin and the corresponding call to glEnd.
See Also

glClearAccum, glClearColor, glClearDepth, glClearIndex, glClearStencil, glDrawBuffer, glGet, glScissor


glClearAccum [New - Windows 95, OEM Service Release 2]
glClearAccum

[New - Windows 95, OEM Service Release 2]

The glClearAccum function clears values for the accumulation buffer.

void glClearAccum(

GLfloat red,
GLfloat green,
GLfloat blue,
GLfloat alpha
);
Parameters

red, green, blue, alpha

The red, green, blue, and alpha values used when the accumulation buffer is cleared. The default values are all zero.

Remarks

The glClearAccum function specifies the red, green, blue, and alpha values used by glClear to clear the accumulation buffer.

Values specified by glClearAccum are clamped to the range [ − 1,1].

The following function retrieves information related to glClearAccum:

glGet with argument GL_ACCUM_CLEAR_VALUE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glClearAccum was called between a call to glBegin and the corresponding call to glEnd
See Also

glBegin, glClear, glEnd, glGet


glClearColor [New - Windows 95, OEM Service Release 2]
glClearColor

[New - Windows 95, OEM Service Release 2]

The glClearColor function specifies clear values for the color buffers.

void glClearColor(

GLclampf red,
GLclampf green,
GLclampf blue,
GLclampf alpha
);
Parameters

red, green, blue, alpha

The red, green, blue, and alpha values used when the color buffers are cleared. The default values are all zero.

Remarks

The glClearColor function specifies the red, green, blue, and alpha values used by glClear to clear the color buffers. Values specified by glClearColor are clamped to the range [0,1].

The following functions retrieve information related to the glClearColor function:

glGet with argument GL_ACCUM_CLEAR_VALUE

glGet with argument GL_COLOR_CLEAR_VALUE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glClearColor was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glClear, glEnd, glGet


glClearDepth [New - Windows 95, OEM Service Release 2]
glClearDepth

[New - Windows 95, OEM Service Release 2]

The glClearDepth function specifies the clear value for the depth buffer.

void glClearDepth(

GLclampd depth
);
Parameters

depth

The depth value used when the depth buffer is cleared.

Remarks

The glClearDepth function specifies the depth value used by glClear to clear the depth buffer. Values specified by glClearDepth are clamped to the range [0,1].

The following function retrieves information related to the glClearDepth function:

glGet with argument GL_DEPTH_CLEAR_VALUE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glClearDepth was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glClear, glEnd, glGet


glClearIndex [New - Windows 95, OEM Service Release 2]
glClearIndex

[New - Windows 95, OEM Service Release 2]

The glClearIndex function specifies the clear value for the color-index buffers.

void glClearIndex(

GLfloat c
);
Parameters

c

The index used when the color-index buffers are cleared. The default value is zero.

Remarks

The glClearIndex function specifies the index used by glClear to clear the color-index buffers. The c parameter is not clamped. Rather, c is converted to a fixed-point value with unspecified precision to the right of the binary point. The integer part of this value is then masked with 2^m − 1, where m is the number of bits in a color index stored in the frame buffer.

The following functions retrieve information related to glClearIndex:

glGet with argument GL_INDEX_CLEAR_VALUE

glGet with argument GL_INDEX_BITS

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glClearIndex was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glClear, glEnd, glGet


glClearStencil [New - Windows 95, OEM Service Release 2]
glClearStencil

[New - Windows 95, OEM Service Release 2]

The glClearStencil function specifies the clear value for the stencil buffer.

void glClearStencil(

GLint s
);
Parameters

s

The index used when the stencil buffer is cleared. The default value is zero.

Remarks

The glClearStencil function specifies the index used by glClear to clear the stencil buffer. The s parameter is masked with 2^m − 1, where m is the number of bits in the stencil buffer.

The following functions retrieve information related to the glClearStencil function:

glGet with argument GL_STENCIL_CLEAR_VALUE

glGet with argument GL_STENCIL_BITS

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glClearStencil was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glClear, glEnd, glGet


glClipPlane [New - Windows 95, OEM Service Release 2]
glClipPlane

[New - Windows 95, OEM Service Release 2]

The glClipPlane function specifies a plane against which all geometry is clipped.

void glClipPlane(

GLenum plane,
const GLdouble * equation
);
Parameters

plane

The clipping plane that is being positioned. Symbolic names of the form GL_CLIP_PLANEi, where i is an integer between 0 and GL_MAX_CLIP_PLANES − 1, are accepted.

equation

The address of an array of four double-precision floating-point values. These values are interpreted as a plane equation.

Remarks

Geometry is always clipped against the boundaries of a six-plane frustum in x, y, and z. The glClipPlane function allows the specification of additional planes, not necessarily perpendicular to the x- , y- , or z-axis, against which all geometry is clipped. Up to GL_MAX_CLIP_PLANES planes can be specified, where GL_MAX_CLIP_PLANES is at least six in all implementations. Because the resulting clipping region is the intersection of the defined half-spaces, it is always convex.

The glClipPlane function specifies a half-space using a four-component plane equation. When you call glClipPlane, equation is transformed by the inverse of the modelview matrix and stored in the resulting eye coordinates. Subsequent changes to the modelview matrix have no effect on the stored plane-equation components. If the dot product of the eye coordinates of a vertex with the stored plane equation components is positive or zero, the vertex is in with respect to that clipping plane. Otherwise, it is out.

Use the glEnable and glDisable functions to enable and disable clipping planes. Call clipping planes with the argument GL_CLIP_PLANEi, where i is the plane number.

By default, all clipping planes are defined as (0,0,0,0) in eye coordinates and are disabled.

It is always the case that GL_CLIP_PLANEi = GL_CLIP_PLANE0 + i.

The following functions retrieve information related to glClipPlane:

glGetClipPlane

glIsEnabled with argument GL_CLIP_PLANEi

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	plane was not an accepted value.
GL_INVALID_OPERATION	glClipPlane was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glDisable, glEnable, glEnd, glGetClipPlane, glIsEnabled


glColor [New - Windows 95, OEM Service Release 2]
glColor

[New - Windows 95, OEM Service Release 2]

glColor3b, glColor3d, glColor3f, glColor3i, glColor3s, glColor3ub, glColor3ui, glColor3us, glColor4b, glColor4d, glColor4f, glColor4i, glColor4s, glColor4ub, glColor4ui, glColor4us, glColor3bv, glColor3dv, glColor3fv, glColor3iv, glColor3sv, glColor3ubv, glColor3uiv, glColor3usv, glColor4bv, glColor4dv, glColor4fv, glColor4iv, glColor4sv, glColor4ubv, glColor4uiv, glColor4usv

These functions set the current color.

void glColor3b(

GLbyte red,
GLbyte green,
GLbyte blue
);
void glColor3d(

GLdouble red,
GLdouble green,
GLdouble blue
);
void glColor3f(

GLfloat red,
GLfloat green,
GLfloat blue
);
void glColor3i(

GLint red,
GLint green,
GLint blue
);
void glColor3s(

GLshort red,
GLshort green,
GLshort blue
);
void glColor3ub(

GLubyte red,
GLubyte green,
GLubyte blue
);
void glColor3ui(

GLuint red,
GLuint green,
GLuint blue
);
void glColor3us(

GLushort red,
GLushort green,
GLushort blue
);
void glColor4b(

GLbyte red,
GLbyte green,
GLbyte blue,
GLbyte alpha
);
void glColor4d(

GLdouble red,
GLdouble green,
GLdouble blue,
GLdouble alpha
);
void glColor4f(

GLfloat red,
GLfloat green,
GLfloat blue,
GLfloat alpha
);
void glColor4i(

GLint red,
GLint green,
GLint blue,
GLint alpha
);
void glColor4s(

GLshort red,
GLshort green,
GLshort blue,
GLshort alpha
);
void glColor4ub(

GLubyte red,
GLubyte green,
GLubyte blue,
GLubyte alpha
);
void glColor4ui(

GLuint red,
GLuint green,
GLuint blue,
GLuint alpha
);
void glColor4us(

GLushort red,
GLushort green,
GLushort blue,
GLushort alpha
);
Parameters

red, green, blue

New red, green, and blue values for the current color.

alpha

A new alpha value for the current color. Included only in the four-argument glColor4 function.

void glColor3bv(

const GLbyte *v
);
void glColor3dv(

const GLdouble *v
);
void glColor3fv(

const GLfloat *v
);
void glColor3iv(

const GLint *v
);
void glColor3sv(

const GLshort *v
);
void glColor3ubv(

const GLubyte *v
);
void glColor3uiv(

const GLuint *v
);
void glColor3usv(

const GLushort *v
);
void glColor4bv(

const GLbyte *v
);
void glColor4dv(

const GLdouble *v
);
void glColor4fv(

const GLfloat *v
);
void glColor4iv(

const GLint *v
);
void glColor4sv(

const GLshort *v
);
void glColor4ubv(

const GLubyte *v
);
void glColor4uiv(

const GLuint *v
);
void glColor4usv(

const GLushort *v
);
Parameters

v

A pointer to an array that contains red, green, blue, and (sometimes) alpha values.

Remarks

OpenGL stores both a current single-valued color index and a current four-valued RGBA color. The glColor function sets a new four-valued RGBA color.

There are two major variants to glColor:

•	The glColor3 variants specify new red, green, and blue values explicitly, and set the current alpha value to 1.0 implicitly.

•	The glColor4 variants specify all four color components explicitly.

The glColor3b, glColor4b, glColor3s, glColor4s, glColor3i, and glColor4i functions take three or four signed byte, short, or long integers as arguments. When you append v to the name, the color functions can take a pointer to an array of such values.

Current color values are stored in floating-point format, with unspecified mantissa and exponent sizes. Unsigned integer color components, when specified, are linearly mapped to floating-point values such that the largest representable value maps to 1.0 (full intensity), and zero maps to 0.0 (zero intensity). Signed integer color components, when specified, are linearly mapped to floating-point values such that the most positive representable value maps to 1.0, and the most negative representable value maps to −1.0. Floating-point values are mapped directly.

Neither floating-point nor signed integer values are clamped to the range [0,1] before updating the current color. However, color components are clamped to this range before they are interpolated or written into a color buffer.

You can update the current color at any time. In particular, you can call glColor between a call to glBegin and the corresponding call to glEnd.

The following functions retrieve information related to the glColor functions:

glGet with argument GL_CURRENT_COLOR

glGet with argument GL_RGBA_MODE

See Also

glBegin, glEnd, glGet, glIndex


glColorMask [New - Windows 95, OEM Service Release 2]
glColorMask

[New - Windows 95, OEM Service Release 2]

The glColorMask function enables and disables writing of frame-buffer color components.

void glColorMask(

GLboolean red,
GLboolean green,
GLboolean blue,
GLboolean alpha
);
Parameters

red, green, blue, alpha

Specify whether red, green, blue, and alpha can or cannot be written into the frame buffer. The default values are all GL_TRUE, indicating that the color components can be written.

Remarks

The glColorMask function specifies whether the individual color components in the frame buffer can or cannot be written. If red is GL_FALSE, for example, no change is made to the red component of any pixel in any of the color buffers, regardless of the drawing operation attempted.

Changes to individual bits of components cannot be controlled. Rather, changes are either enabled or disabled for entire color components.

The following functions retrieve information related to glColorMask:

glGet with argument GL_COLOR_WRITEMASK

glGet with argument GL_RGBA_MODE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glColorMask was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glColor, glDepthMask, glEnd, glGet, glIndex, glIndexMask, glStencilMask


glColorMaterial [New - Windows 95, OEM Service Release 2]
glColorMaterial

[New - Windows 95, OEM Service Release 2]

The glColorMaterial function causes a material color to track the current color.

void glColorMaterial(

GLenum face,
GLenum mode
);
Parameters

face

Specifies whether front, back, or both front and back material parameters should track the current color. Accepted values are GL_FRONT, GL_BACK, and GL_FRONT_AND_BACK. The default value is GL_FRONT_AND_BACK.

mode

Specifies which of several material parameters track the current color. Accepted values are GL_EMISSION, GL_AMBIENT, GL_DIFFUSE, GL_SPECULAR, and GL_AMBIENT_AND_DIFFUSE. The default value is GL_AMBIENT_AND_DIFFUSE.

Remarks

The glColorMaterial function specifies which material parameters track the current color. When you enable GL_COLOR_MATERIAL, the material parameter or parameters specified by mode, of the material or materials specified by face, track the current color at all times. You enable and disable GL_COLOR_MATERIAL with the functions glEnable and glDisable, which you call with GL_COLOR_MATERIAL as their argument. By default, GL_COLOR_MATERIAL is disabled.

With glColorMaterial, you can change a subset of material parameters for each vertex using only the glColor function, without calling glMaterial. If you are going to specify only such a subset of parameters for each vertex, it is better to do so with glColorMaterial than with glMaterial.

The following functions retrieve information related to glColorMaterial:

glGet with argument GL_COLOR_MATERIAL_PARAMETER

glGet with argument GL_COLOR_MATERIAL_FACE

glIsEnabled with argument GL_COLOR_MATERIAL

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	face or mode was not an accepted value.
GL_INVALID_OPERATION	glColorMaterial was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glColor, glDisable, glEnable, glEnd, glGet, glIsEnabled, glLight, glLightModel, glMaterial


glColorPointer [New - Windows 95, OEM Service Release 2]
glColorPointer

[New - Windows 95, OEM Service Release 2]

The glColorPointer function defines an array of colors.

void glColorPointer(

GLint size,
GLenum type,
GLsizei stride,
GLsizei count,
const GLvoid * pointer
);
Parameters

size

The number of components per color. The value must be either 3 or 4.

type

The data type of each color component in a color array. Acceptable data types are specified with the following constants: GL_BYTE, GL_UNSIGNED_BYTE, GL_SHORT, GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT, GL_FLOAT, or GL_DOUBLE.

stride

The byte offset between consecutive colors. When stride is zero, the colors are tightly packed in the array.

count

The number of static colors, counting from the first color.

pointer

A pointer to the first component of the first color element in a color array.

Remarks

The glColorPointer function specifies the location and data format of an array of color components to use when rendering. The stride parameter determines the byte offset from one color to the next, enabling the packing of vertex attributes in a single array or storage in separate arrays. In some implementations, storing vertex attributes in a single array can be more efficient than the use of separate arrays. Starting from the first color array element, count indicates the total number of static elements. You can modify static elements, but once the elements are modified, you must explicitly specify the array again before using the array for any rendering. Nonstatic color array elements are not accessed until you call glDrawArrays or glArrayElement.

The color array is enabled when you specify the GL_COLOR_ARRAY constant with glEnableClientState. Calling glArrayElement, or glDrawArrays uses the color array that is thus enabled. By default, the color array is disabled. The glColorPointer calls are not entered in display lists.

When you specify a color array using glColorPointer, the values of all the function’s color array parameters are saved in a client-side state, and you can cache static array elements. Because the color array parameters are in a client-side state, glPushAttrib and glPopAttrib do not save or restore the parameters’ values.

Although specifying the color array within glBegin and glEnd pairs does not generate an error, the results are undefined.

The following functions retrieve information related to the glColorPointer function:

glIsEnabled with argument GL_COLOR_ARRAY

glGet with argument GL_COLOR_ARRAY_SIZE

glGet with argument GL_COLOR_ARRAY_TYPE

glGet with argument GL_COLOR_ARRAY_STRIDE

glGet with argument GL_COLOR_ARRAY_COUNT

glGetPointerv with argument GL_COLOR_ARRAY_POINTER

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	size was not 3 or 4.
GL_INVALID_ENUM	type was not an accepted value.
GL_INVALID_VALUE	stride or count was negative.
See Also

glArrayElement, glBegin, glDrawArrays, glEdgeFlagPointer, glEnableClientState, glEnd, glGet, glGetString, glGetPointerv, glIndexPointer, glIsEnabled, glNormalPointer, glPopAttrib, glPushAttrib, glTexCoordPointer, glVertexPointer


glColorTableEXT [New - Windows 95, OEM Service Release 2]
glColorTableEXT

[New - Windows 95, OEM Service Release 2]

The glColorTableEXT function specifies the format and size of a palette for targeted paletted textures.

void glColorTableEXT(

GLenum target,
GLenum internalFormat,
GLsizei width,
GLenum format,
GLenum type,
const GLvoid * data
);
Parameters

target

The target texture that is to have its palette changed. Must be TEXTURE_1D, TEXTURE_2D, PROXY_TEXTURE_1D, or PROXY_TEXTURE_2D.

internalFormat

The internal format and resolution of the palette. This parameter can assume one of the following symbolic values:

Constant	Base Format	R Bits	G Bits	B Bits	A Bits
GL_R3_G3_B2	GL_RGB	3	3	2	—
GL_RGB4	GL_RGB	4	4	4	—
GL_RGB5	GL_RGB	5	5	5	—
GL_RGB8	GL_RGB	8	8	8	—
GL_RGB10	GL_RGB	10	10	10	—
GL_RGB12	GL_RGB	12	12	12	—
GL_RGB16	GL_RGB	16	16	16	—
GL_RGBA2	GL_RGBA	2	2	2	2
GL_RGBA4	GL_RGBA	4	4	4	4
GL_RGB5_A1	GL_RGBA	5	5	5	1
GL_RGBA8	GL_RGBA	8	8	8	8
GL_RGB10_A2	GL_RGBA	10	10	10	2
GL_RGB12	GL_RGBA	12	12	12	12
GL_RGBA16	GL_RGBA	16	16	16	16
width

The size of the palette. Must be 2^n ≥ 1 for some integer n.

format

The format of the pixel data. The following symbolic constants are accepted:

GL_RGBA

Each pixel is a group of four components in this order: red, green, blue, alpha. The RGBA format is determined in this way:

1.	The glColorTableEXT function converts floating-point values directly to an internal format with unspecified precision. Signed integer values are mapped linearly to the internal format such that the most positive representable integer value maps to 1.0, and the most negative representable integer value maps to −1.0. Unsigned integer data is mapped similarly: the largest integer value maps to 1.0, and zero maps to 0.0.

2.	The glColorTableEXT function multiplies the resulting color values by GL_c_SCALE and adds them to GL_c_BIAS, where c is RED, GREEN, BLUE, and ALPHA for the respective color components. The results are clamped to the range [0,1].

3.	If GL_MAP_COLOR is TRUE, glColorTableEXT scales each color component by the size of lookup table GL_PIXEL_MAP_c_TO_c, then replaces the component by the value that it references in that table; c is R, G, B, or A, respectively.

4.	The glColorTableEXT function converts the resulting RGBA colors to fragments by attaching the current raster position z-coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that

x (n)  = x (r)  + n mod width

y (n)  = y (r)  +  n/width

where (x (r) , y (r) ) is the current raster position.

5.	These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. The glColorTableEXT function applies texture mapping, fog, and all the fragment operations before writing the fragments to the frame buffer.

GL_RED

Each pixel is a single red component.

The glColorTableEXT function converts this component to the internal format in the same way that the red component of an RGBA pixel is, then converts it to an RGBA pixel with green and blue set to 0.0, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_GREEN

Each pixel is a single green component.

The glColorTableEXT function converts this component to the internal format in the same way that the green component of an RGBA pixel is, and then converts it to an RGBA pixel with red and blue set to 0.0, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_BLUE

Each pixel is a single blue component.

The glColorTableEXT function converts this component to the internal format in the same way that the blue component of an RGBA pixel is, and then converts it to an RGBA pixel with red and green set to 0.0, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_ALPHA

Each pixel is a single alpha component.

The glColorTableEXT function converts this component to the internal format in the same way that the alpha component of an RGBA pixel is, and then converts it to an RGBA pixel with red, green, and blue set to 0.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_RGB

Each pixel is a group of three components in this order: red, green, blue.

The glColorTableEXT function converts each component to the internal format in the same way that the red, green, and blue components of an RGBA pixel are. The color triple is converted to an RGBA pixel with alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_BGR_EXT

Each pixel is a group of three components in this order: blue, green, red.

GL_BGR_EXT provides a format that matches the memory layout of Windows device-independent bitmaps (DIBs). Thus your applications can use the same data with Win32 function calls and OpenGL pixel function calls.

GL_BGRA_EXT

Each pixel is a group of four components in this order: blue, green, red, alpha.

GL_BGRA_EXT provides a format that matches the memory layout of Windows device-independent bitmaps (DIBs). Thus your applications can use the same data with Win32 function calls and OpenGL pixel function calls.

type

The data type for data. The following symbolic constants are accepted: GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, and GL_FLOAT.

The following table summarizes the meaning of the valid constants for the type parameter.

Constant	Meaning
GL_UNSIGNED_BYTE	Unsigned 8-bit integer
GL_BYTE	Signed 8-bit integer
GL_UNSIGNED_SHORT	Unsigned 16-bit integer
GL_SHORT	Signed 16-bit integer
GL_UNSIGNED_INT	Unsigned 32-bit integer
GL_INT	32-bit integer
GL_FLOAT	Single-precision floating-point value
data

A pointer to the paletted texture data. The data is treated as single pixels of a 1-D texture palette entry for a palette entry.

Remarks

Paletted textures are defined with a palette of colors and a set of image data that is composed of indexes to color entries of a palette (a color table).

The glColorTableEXT function specifies the texture palette of a targeted texture. It takes the data from memory and converts the data as if each palette entry is a single pixel of a 1-D texture. The glColorTableEXT function unpacks and converts the data and translates it into an internal format that matches the given format as closely as possible.

If a palette’s width is greater than the range of the color indexes in the texture data, some of the palette entries are unused. If a palette’s width is less than the range of the color indexes in the texture data, the most significant bits of the texture data are ignored and only the appropriate number of bits in the index are used when accessing the palette. When you specify a proxy target using PROXY_TEXTURE_1D or PROXY_TEXTURE_2D, the palette of the proxy texture is resized and its parameters are set but no data is transferred or accessed.

When the target parameter is GL_PROXY_TEXTURE_1D or GL_PROXY_TEXTURE_2D, and the implementation does not support the values specified for either format or width, glColorTableEXT can fail to create the requested color table. In this case, the color table is empty and all parameters retrieved will be zero. You can determine whether OpenGL supports a particular color table format and size by calling glColorTableEXT with a proxy target, and then calling glGetColorTableParameterivEXT or glGetColorTableParameterfvEXT to determine whether the width parameter matches that set by glColorTableEXT. If the retrieved width is zero, the color table request by glColorTable failed. If the retrieved width is not zero, you can call glColorTable with the real target with TEXTURE_1D or TEXTURE_2D to set the color table.

Note  The glColorTableEXT function is an extension function that is not part of the standard OpenGL library but is part of the GL_EXT_paletted_texture extension. To check whether your implementation of OpenGL supports glColorTableEXT, call glGetString(GL_EXTENSIONS). If it returns GL_EXT_paletted_texture, glColorTableEXT is supported. To obtain the function address of an extension function, call wglGetProcAddress.

To retrieve the actual color table data specified by the glColorTableEXT function, call glGetColorTableEXT. To retrieve the parameters, such as width and format, of the color table specified by the glColorTableEXT function, call the glGetColorTableParameterivEXT or glGetColorTableParameterfvEXT function.

Error Codes

The following are the errors generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	width was an invalid integer.
GL_INVALID_ENUM	target, internalFormat, format, or type was not an accepted value.
GL_INVALID_OPERATION	glColorTableEXT was called between glBegin and glEnd pairs.
See Also

glBegin, glColorSubTableEXT, glEnd, glGetColorTableEXT, glGetColorTableParameterfvEXT, glGetColorTableParameterivEXT, wglGetProcAddress


glColorSubTableEXT [New - Windows 95, OEM Service Release 2]
glColorSubTableEXT

[New - Windows 95, OEM Service Release 2]

The glColorSubTableEXT function specifies a portion of the targeted texture’s palette to be replaced.

void glColorSubTableEXT(

GLenum target,
GLsizei start,
GLsizei count,
GLenum format,
GLenum type,
const GLvoid * data
);
Parameters

target

The target paletted texture that is to have its palette changed. Must be TEXTURE_1D or TEXTURE_2D.

start

The starting palette index entry of the palette to be changed.

count

The number of palette index entries of the palette to be changed beginning at start. The count parameter determines the range of palette index entries that are changed.

format

The format of the pixel data. The following symbolic constants are accepted:

GL_RGBA

Each pixel is a group of four components in the following order: red, green, blue, alpha. The RGBA format is determined in this way:

1.	The glColorSubTableEXT function converts floating-point values directly to an internal format with unspecified precision. Signed integer values are mapped linearly to the internal format such that the most positive representable integer value maps to 1.0, and the most negative representable value maps to − 1.0. Unsigned integer data is mapped similarly: the largest integer value maps to 1.0, and zero maps to 0.0.

2.	The glColorSubTableEXT function multiplies the resulting color values by GL_c_SCALE and adds them to GL_c_BIAS, where c is RED, GREEN, BLUE, and ALPHA for the respective color components. The results are clamped to the range [0,1].

3.	If GL_MAP_COLOR is TRUE, glColorSubTableEXT scales each color component by the size of lookup table GL_PIXEL_MAP_c_TO_c, then replaces the component by the value that it references in that table; c is R, G, B, or A, respectively.

4.	The glColorSubTableEXT function converts the resulting RGBA colors to fragments by attaching the current raster position z-coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that

x (n)  = x (r)  + n mod width

y (n)  = y (r)  +  n/width

where (x (r) , y (r) ) is the current raster position.

5.	These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. The glColorSubTableEXT function applies texture mapping, fog, and all the fragment operations before writing the fragments to the frame buffer.

GL_RED

Each pixel is a single red component.

The glColorSubTableEXT function converts this component to the internal format in the same way that the red component of an RGBA pixel is, then converts it to an RGBA pixel with green and blue set to 0.0, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_GREEN

Each pixel is a single green component.

The glColorSubTableEXT function converts this component to the internal format in the same way that the green component of an RGBA pixel is, and then converts it to an RGBA pixel with red and blue set to 0.0, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_BLUE

Each pixel is a single blue component.

The glColorSubTableEXT function converts this component to the internal format in the same way that the blue component of an RGBA pixel is, and then converts it to an RGBA pixel with red and green set to 0.0, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_ALPHA

Each pixel is a single alpha component.

The glColorSubTableEXT function converts this component to the internal format in the same way that the alpha component of an RGBA pixel is, and then converts it to an RGBA pixel with red, green, and blue set to 0.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_RGB

Each pixel is a group of three components in this order: red, green, blue.

The glColorSubTableEXT function converts each component to the internal format in the same way that the red, green, and blue components of an RGBA pixel are. The color triple is converted to an RGBA pixel with alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_BGR_EXT

Each pixel is a group of three components in this order: blue, green, red.

GL_BGR_EXT provides a format that matches the memory layout of Windows device-independent bitmaps (DIBs). Thus your applications can use the same data with Win32 function calls and OpenGL pixel function calls.

GL_BGRA_EXT

Each pixel is a group of four components in this order: blue, green, red, alpha.

GL_BGRA_EXT provides a format that matches the memory layout of Windows device-independent bitmaps (DIBs). Thus your applications can use the same data with Win32 function calls and OpenGL pixel function calls.

type

The data type for data. The following symbolic constants are accepted: GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, and GL_FLOAT.

The following table summarizes the meaning of the valid constants for the type parameter.

Constant	Meaning
GL_UNSIGNED_BYTE	Unsigned 8-bit integer
GL_BYTE	Signed 8-bit integer
GL_UNSIGNED_SHORT	Unsigned 16-bit integer
GL_SHORT	Signed 16-bit integer
GL_UNSIGNED_INT	Unsigned 32-bit integer
GL_INT	32-bit integer
GL_FLOAT	Single-precision floating-point value
data

A pointer to the paletted texture data. The data is treated as single pixels of a 1-D texture palette entry for a palette entry.

Remarks

The glColorSubTableEXT function specifies portions of the current targeted texture’s palette to be replaced. Unlike glColorTableEXT, you cannot specify the target parameter to be a proxy texture palette.

Note  The glColorSubTableEXT function is an extension function that is not part of the standard OpenGL library but is part of the GL_EXT_paletted_texture extension. To check whether your implementation of OpenGL supports glColorSubTableEXT, call glGetString(GL_EXTENSIONS). If it returns GL_EXT_paletted_texture, glColorSubTableEXT is supported. To obtain the function address of an extension function, call wglGetProcAddress.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	start or count was an invalid integer.
GL_INVALID_ENUM	target, format, or type was not an accepted value.
GL_INVALID_OPERATION	glColorSubTableEXT was called between glBegin and glEnd pairs.
See Also

glBegin, glColorTableEXT, glEnd, glGetColorTableEXT, glGetColorTableParameterfvEXT, glGetColorTableParameterivEXT, glGetString, wglGetProcAddress


glCopyPixels [New - Windows 95, OEM Service Release 2]
glCopyPixels

[New - Windows 95, OEM Service Release 2]

The glCopyPixels function copies pixels in the frame buffer.

void glCopyPixels(

GLint x,
GLint y,
GLsizei width,
GLsizei height,
GLenum type
);
Parameters

x, y

The window coordinates of the lower-left corner of the rectangular region of pixels to be copied.

width, height

The dimensions of the rectangular region of pixels to be copied. Both must be nonnegative.

type

Specifies whether glCopyPixels is to copy color values, depth values, or stencil values. The acceptable symbolic constants are:

GL_COLOR

The glCopyPixels function reads indexes or RGBA colors from the buffer currently specified as the read source buffer (see glReadBuffer).

If OpenGL is in color-index mode:

1.	Each index that is read from this buffer is converted to a fixed-point format with an unspecified number of bits to the right of the binary point.

2.	Each index is shifted left by GL_INDEX_SHIFT bits, and added to GL_INDEX_OFFSET.

If GL_INDEX_SHIFT is negative, the shift is to the right. In either case, zero bits fill otherwise unspecified bit locations in the result.

3.	If GL_MAP_COLOR is true, the index is replaced with the value that it references in lookup table GL_PIXEL_MAP_I_TO_I.

4.	Whether the lookup replacement of the index is done or not, the integer part of the index is then ANDed with 2^b − 1, where b is the number of bits in a color-index buffer.

If OpenGL is in RGBA mode:

1.	The red, green, blue, and alpha components of each pixel that is read are converted to an internal floating-point format with unspecified precision.

2.	The conversion maps the largest representable component value to 1.0, and component value zero to 0.0.

3.	The resulting floating-point color values are then multiplied by GL_c_SCALE and added to GL_c_BIAS, where c is RED, GREEN, BLUE, and ALPHA for the respective color components.

4.	The results are clamped to the range [0,1].

5.	If GL_MAP_COLOR is true, each color component is scaled by the size of lookup table GL_PIXEL_MAP_c_TO_c, and then replaced by the value that it references in that table; c is R, G, B, or A, respectively.

The resulting indexes or RGBA colors are then converted to fragments by attaching the current raster position z-coordinate and texture coordinates to each pixel, and then assigning window coordinates (x (r)  + i, y (r)  + j), where (x (r)  y (r) ) is the current raster position, and the pixel was the pixel in the i position in the j row. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.

GL_DEPTH

Depth values are read from the depth buffer and converted directly to an internal floating-point format with unspecified precision. The resulting floating-point depth value is then multiplied by GL_DEPTH_SCALE and added to GL_DEPTH_BIAS. The result is clamped to the range [0,1].

The resulting depth components are then converted to fragments by attaching the current raster position color or color index and texture coordinates to each pixel, then assigning window coordinates (x (r)  + i, y (r)  + j), where (x (r) , y (r) ) is the current raster position, and the pixel was the pixel in the i position in the j row. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.

GL_STENCIL

Stencil indexes are read from the stencil buffer and converted to an internal fixed-point format with an unspecified number of bits to the right of the binary point. Each fixed-point index is then shifted left by GL_INDEX_SHIFT bits, and added to GL_INDEX_OFFSET. If GL_INDEX_SHIFT is negative, the shift is to the right. In either case, zero bits fill otherwise unspecified bit locations in the result. If GL_MAP_STENCIL is true, the index is replaced with the value that it references in lookup table GL_PIXEL_MAP_S_TO_S. Whether the lookup replacement of the index is done or not, the integer part of the index is then ANDed with 2^b − 1, where b is the number of bits in the stencil buffer. The resulting stencil indexes are then written to the stencil buffer such that the index read from the i location of the j row is written to location (x (r)  + i, y (r)  + j), where (x (r) , y (r) ) is the current raster position. Only the pixel-ownership test, the scissor test, and the stencil writemask affect these writes.

Remarks

The glCopyPixels function copies a screen-aligned rectangle of pixels from the specified frame buffer location to a region relative to the current raster position. Its operation is well defined only if the entire pixel source region is within the exposed portion of the window. Results of copies from outside the window, or from regions of the window that are not exposed, are hardware dependent and undefined.

The x and y parameters specify the window coordinates of the lower-left corner of the rectangular region to be copied. The width and height parameters specify the dimensions of the rectangular region to be copied. Both width and height must be nonnegative.

Several parameters control the processing of the pixel data while it is being copied. These parameters are set with three functions: glPixelTransfer, glPixelMap, and glPixelZoom. This topic describes the effects on glCopyPixels of most, but not all, of the parameters specified by these three functions.

The glCopyPixels function copies values from each pixel with the lower-left corner at (x + i, y + j) for 0≤i<width and 0≤j<height. This pixel is said to be the i pixel in the j row. Pixels are copied in row order from the lowest to the highest row, left to right in each row.

The type parameter specifies whether color, depth, or stencil data is to be copied.

The rasterization described thus far assumes pixel zoom factors of 1.0. If you use glPixelZoom to change the x and y pixel zoom factors, pixels are converted to fragments as follows. If (x (r) , y (r) ) is the current raster position, and a given pixel is in the i location in the j row of the source pixel rectangle, then fragments are generated for pixels whose centers are in the rectangle with corners at

(x (r)  + zoom (x)  i, y (r)  + zoom (y)  j)

and

(x (r)  + zoom (x)  (i + 1), y (r)  + zoom (y)  (j + 1 ))

where zoom (x)  is the value of GL_ZOOM_X and zoom (y)  is the value of GL_ZOOM_Y.

Modes specified by glPixelStore have no effect on the operation of glCopyPixels.

The following functions retrieve information related to glCopyPixels:

glGet with argument GL_CURRENT_RASTER_POSITION

glGet with argument GL_CURRENT_RASTER_POSITION_VALID

To copy the color pixel in the lower-left corner of the window to the current raster position, use

glCopyPixels(0, 0, 1, 1, GL_COLOR);

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	type was not an accepted value.
GL_INVALID_VALUE	Either width or height was negative.
GL_INVALID_OPERATION	type was GL_DEPTH and there was no depth buffer.
GL_INVALID_OPERATION	type was GL_STENCIL and there was no stencil buffer.
GL_INVALID_OPERATION	glCopyPixels was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glDepthFunc, glDrawBuffer, glDrawPixels, glEnd, glGet, glPixelMap, glPixelStore, glPixelTransfer, glPixelZoom, glRasterPos, glReadBuffer, glReadPixels, glStencilFunc


glCopyTexImage1D [New - Windows 95, OEM Service Release 2]
glCopyTexImage1D

[New - Windows 95, OEM Service Release 2]

The glCopyTexImage1D function copies pixels from the frame buffer into a one-dimensional texture image.

void glCopyTexImage1D(

GLenum target,
GLint level,
GLenum internalFormat,
GLint x,
GLint y,
GLsizei width,
GLint border
);
Parameters

target

The target for which the image data will be changed. Must have the value GL_TEXTURE_1D.

level

The level-of-detail number. Level 0 is the base image. Level n is the nth mipmap reduction image.

internalFormat

The internal format and resolution of the texture data. The values 1, 2, 3, and 4 are not accepted for internalFormat. This parameter can assume one of the following symbolic values:

Constant	Base Format	R Bits	G Bits	B Bits	A Bits	L Bits	I Bits
ALPHA	—	—	—	—	—	—	—
ALPHA4	ALPHA	—	—	—	4	—	—
ALPHA8	ALPHA	—	—	—	8	—	—
ALPHA12	ALPHA	—	—	—	12	—	—
ALPHA16	ALPHA	—	—	—	16	—	—
LUMINANCE	—	—	—	—	—	—	—
LUMINANCE4	LUMINANCE	—	—	—	—	4	—
LUMINANCE8	LUMINANCE	—	—	—	—	8	—
LUMINANCE12	LUMINANCE	—	—	—	—	12	—
LUMINANCE16	LUMINANCE	—	—	—	—	16	—
LUMINANCE_ALPHA	—	—	—	—	—	—	—
LUMINANCE4_ALPHA4	LUMINANCE_ALPHA	—	—	—	4	4	—
LUMINANCE6_ALPHA2	LUMINANCE_ALPHA	—	—	—	2	6	—
LUMINANCE8_ALPHA8	LUMINANCE_ALPHA	—	—	—	8	8	—
LUMINANCE12_ALPHA4	LUMINANCE_ALPHA	—	—	—	4	12	—
LUMINANCE12_ALPHA12	LUMINANCE_ALPHA	—	—	—	12	12	—
LUMINANCE16_ALPHA16	LUMINANCE_ALPHA	—	—	—	16	16	—
INTENSITY	—	—	—	—	—	—	—
INTENSITY4	INTENSITY	—	—	—	—	—	4
INTENSITY8	INTENSITY	—	—	—	—	—	8
INTENSITY12	INTENSITY	—	—	—	—	—	12
INTENSITY16	INTENSITY	—	—	—	—	—	16
GL_RGB	—	—	—	—	—	—	—
GL_R3_G3_B2	GL_RGB	3	3	2	—	—	—
GL_RGB4	GL_RGB	4	4	4	—	—	—
GL_RGB5	GL_RGB	5	5	5	—	—	—
GL_RGB8	GL_RGB	8	8	8	—	—	—
GL_RGB10	GL_RGB	10	10	10	—	—	—
GL_RGB12	GL_RGB	12	12	12	—	—	—
GL_RGB16	GL_RGB	16	16	16	—	—	—
GL_RGBA	—	—	—	—	—	—	—
GL_RGBA2	GL_RGBA	2	2	2	2	—	—
GL_RGBA4	GL_RGBA	4	4	4	4	—	—
GL_RGB5_A1	GL_RGBA	5	5	5	1	—	—
GL_RGBA8	GL_RGBA	8	8	8	8	—	—
GL_RGB10_A2	GL_RGBA	10	10	10	2	—	—
GL_RGBA12	GL_RGBA	12	12	12	12	—	—
GL_RGBA16	GL_RGBA	16	16	16	16	—	—
x, y

The window coordinates of the lower-left corner of the row of pixels to be copied.

width

The width of the texture image. Must be 2^n + 2 * border for some integer n. The height of the texture image is 1.

border

The width of the border. Must be either zero or 1.

Remarks

The glCopyTexImage1D function defines a one-dimensional texture image using pixels from the current frame buffer, rather than from main memory as is the case for glTexImage1D.

Using the mipmap level specified with level, texture arrays are defined as a pixel row aligned with the lower-left corner of the window at the coordinates specified by x and y, with a length equal to width + 2 * border. The internal format of the texture array is specified with the internalFormat parameter.

The glCopyTexImage1D function processes the pixels in a row in the same way as glCopyPixels, except that before the final conversion of the pixels, all pixel component values are clamped to the range [0, 1] and converted to the texture’s internal format for storage in the texture array. Pixel ordering is determined with lower x coordinates corresponding to lower texture coordinates. If any of the pixels within a specified row of the current frame buffer are outside the window associated with the current rendering context, then their values are undefined.

You cannot include calls to glCopyTexImage1D in display lists.

Note  The glCopyTexImage1D function is only available in OpenGL version 1.1 or later.

Texturing has no effect in color-index mode. The glPixelStore and glPixelTransfer functions affect texture images in exactly the way they affect glDrawPixels.

The following function retrieves information related to glCopyTexImage1D:

glIsEnabled with argument GL_TEXTURE_1D

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target was not an accepted value.
GL_INVALID_VALUE	level was less than zero or greater than log sub 2(max), where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE	border was not zero or 1.
GL_INVALID_VALUE	width was less than zero, greater than 2 + GL_MAX_TEXTURE_SIZE; or width cannot be represented as 2^n + 2 * border for some integer n.
GL_INVALID_OPERATION	glCopyTexImage1D was called between a call to glBegin and the corresponding call to glEnd.
See Also

glCopyPixels, glCopyTexImage2D, glDrawPixels, glFog, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexParameter


glCopyTexImage2D [New - Windows 95, OEM Service Release 2]
glCopyTexImage2D

[New - Windows 95, OEM Service Release 2]

The glCopyTexImage2D function copies pixels from the frame buffer into a two-dimensional texture image.

void glCopyTexImage2D(

GLenum target,
GLint level,
GLenum internalFormat,
GLint x,
GLint y,
GLsizei width,
GLsizei height,
GLint border
);
Parameters

target

The target to which the image data will be changed. Must have the value GL_TEXTURE_2D.

level

The level-of-detail number. Level 0 is the base image. Level n is the nth mipmap reduction image.

internalFormat

The internal format and resolution of the texture data. The values 1, 2, 3, and 4 are not accepted for internalFormat. The parameter can assume one of the following symbolic values:

Constant	Base Format	R Bits	G Bits	B Bits	A Bits	L Bits	I Bits
ALPHA	—	—	—	—	—	—	—
ALPHA4	ALPHA	—	—	—	4	—	—
ALPHA8	ALPHA	—	—	—	8	—	—
ALPHA12	ALPHA	—	—	—	12	—	—
ALPHA16	ALPHA	—	—	—	16	—	—
LUMINANCE	—	—	—	—	—	—	—
LUMINANCE4	LUMINANCE	—	—	—	—	4	—
LUMINANCE8	LUMINANCE	—	—	—	—	8	—
LUMINANCE12	LUMINANCE	—	—	—	—	12	—
LUMINANCE16	LUMINANCE	—	—	—	—	16	—
LUMINANCE_ALPHA	—	—	—	—	—	—	—
LUMINANCE4_ALPHA4	LUMINANCE_ALPHA	—	—	—	4	4	—
LUMINANCE6_ALPHA2	LUMINANCE_ALPHA	—	—	—	2	6	—
LUMINANCE8_ALPHA8	LUMINANCE_ALPHA	—	—	—	8	8	—
LUMINANCE12_ALPHA4	LUMINANCE_ALPHA	—	—	—	4	12	—
LUMINANCE12_ALPHA12	LUMINANCE_ALPHA	—	—	—	12	12	—
LUMINANCE16_ALPHA16	LUMINANCE_ALPHA	—	—	—	16	16	—
INTENSITY	—	—	—	—	—	—	—
INTENSITY4	INTENSITY	—	—	—	—	—	4
INTENSITY8	INTENSITY	—	—	—	—	—	8
INTENSITY12	INTENSITY	—	—	—	—	—	12
INTENSITY16	INTENSITY	—	—	—	—	—	16
GL_RGB	—	—	—	—	—	—	—
GL_R3_G3_B2	GL_RGB	3	3	2	—	—	—
GL_RGB4	GL_RGB	4	4	4	—	—	—
GL_RGB5	GL_RGB	5	5	5	—	—	—
GL_RGB8	GL_RGB	8	8	8	—	—	—
GL_RGB10	GL_RGB	10	10	10	—	—	—
GL_RGB12	GL_RGB	12	12	12	—	—	—
GL_RGB16	GL_RGB	16	16	16	—	—	—
GL_RGBA	—	—	—	—	—	—	—
GL_RGBA2	GL_RGBA	2	2	2	2	—	—
GL_RGBA4	GL_RGBA	4	4	4	4	—	—
GL_RGB5_A1	GL_RGBA	5	5	5	1	—	—
GL_RGBA8	GL_RGBA	8	8	8	8	—	—
GL_RGB10_A2	GL_RGBA	10	10	10	2	—	—
GL_RGBA12	GL_RGBA	12	12	12	12	—	—
GL_RGBA16	GL_RGBA	16	16	16	16	—	—
x, y

The window coordinates of the lower-left corner of the rectangular region of pixels to be copied.

width

The width of the texture image. Must be 2^n + 2 * border for some integer n.

height

The height of the texture image. Must be 2^n + 2 * border for some integer n.

border

The width of the border. Must be either zero or 1.

Remarks

The glCopyTexImage2D function defines a two-dimensional texture image using pixels from the current frame buffer, rather than from main memory as is the case for glTexImage2D.

Using the mipmap level specified with level, texture arrays are defined as a rectangle of pixels with the lower-left corner located at the coordinates x and y, width equal to width + (2 * border), and a height equal to height + (2 * border). The internal format of the texture array is specified with the internalFormat parameter.

The glCopyTexImage2D function processes the pixels in a row in the same way as glCopyPixels except that before the final conversion of the pixels, all pixel component values are clamped to the range [0, 1] and converted to the texture’s internal format for storage in the texture array. Pixel ordering is determined with lower x and y coordinates corresponding to lower s and t texture coordinates. If any of the pixels within a specified row of the current frame buffer are outside the window associated with the current rendering context, then their values are undefined.

You cannot include calls to glCopyTexImage2D in display lists.

Note  The glCopyTexImage2D function is only available in OpenGL version 1.1 or later.

Texturing has no effect in color-index mode. The glPixelStore and glPixelTransfer functions affect texture images in exactly the way they affect glDrawPixels.

The following function retrieves information related to glCopyTexImage2D:

glIsEnabled with argument GL_TEXTURE_2D

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target was not an accepted value.
GL_INVALID_VALUE	level was less than zero or greater than log sub 2(max), where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE	border was not zero or 1.
GL_INVALID_VALUE	width was less than zero, greater than 2 + GL_MAX_TEXTURE_SIZE; or width cannot be represented as 2^n + 2 * border for some integer n.
GL_INVALID_OPERATION	glCopyTexImage2D was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glCopyTexImage1D, glDrawPixels, glEnd, glFog, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexParameter


glCopyTexSubImage1D [New - Windows 95, OEM Service Release 2]
glCopyTexSubImage1D

[New - Windows 95, OEM Service Release 2]

The glCopyTexSubImage1D function copies a sub-image of a one-dimensional texture image from the frame buffer.

void glCopyTexSubImage1D(

GLenum target,
GLint level,
GLint xoffset,
GLint x,
GLint y,
GLsizei width
);
Parameters

target

The target to which the image data will be changed. Must have the value GL_TEXTURE_1D.

level

The level-of-detail number. Level 0 is the base image. Level n is the nth mipmap reduction image.

xoffset

The texel offset within the texture array.

x, y

The window coordinates of the lower-left corner of the row of pixels to be copied.

width

The width of the sub-image of the texture image. Specifying a texture sub-image with zero width has no effect.

Remarks

The glCopyTexSubImage1D function replaces a portion of a one-dimensional texture image using pixels from the current frame buffer, rather than from main memory as is the case for glTexSubImage1D.

A row of pixels beginning with the window coordinates specified by x and y and with the length width replaces the portion of the texture array with the indexes xoffset through xoffset + (width − 1). The destination in the texture array cannot include any texels outside the originally specified texture array.

The glCopyTexSubImage1D function processes the pixels in a row in the same way as glCopyPixels except that before the final conversion of the pixels, all pixel component values are clamped to the range [0, 1] and converted to the texture’s internal format for storage in the texture array. Pixel ordering is determined with lower x coordinates corresponding to lower texture coordinates. If any of the pixels within a specified row of the current frame buffer are outside the window associated with the current rendering context, then their values are undefined.

No change is made to the internalFormat, width, or border parameter of the specified texture array or to texel values outside the specified texture sub-image.

You cannot include calls to glCopyTexSubImage1D in display lists.

Note  The glCopyTexSubImage1D function is only available in OpenGL version 1.1 or later.

Texturing has no effect in color-index mode. The glPixelStore and glPixelTransfer functions affect texture images in exactly the way they affect the way pixels are drawn using glDrawPixels.

The following functions retrieve information related to glCopyTexSubImage1D:

glGetTexImage

glIsEnabled with argument GL_TEXTURE_1D

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target was not an accepted value.
GL_INVALID_VALUE	level was less than zero or greater than log sub 2(max), where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE	xoffset was less than border or (xoffset + width) was greater than (w + border), where w is GL_TEXTURE_WIDTH and border is GL_TEXTURE_BORDER. Note that w includes twice the border width.
GL_INVALID_VALUE	width was less than border or y was less than border, where border is the border width of the texture array.
GL_INVALID_OPERATION	The texture array was not defined by a previous glTexImage1D operation.
GL_INVALID_OPERATION	glCopyTexSubImage1D was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glCopyTexSubImage2D, glDrawPixels, glEnd, glFog, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexSubImage1D, glTexSubImage2D, glTexParameter


glCopyTexSubImage2D [New - Windows 95, OEM Service Release 2]
glCopyTexSubImage2D

[New - Windows 95, OEM Service Release 2]

The glCopyTexSubImage2D function copies a sub-image of a two-dimensional texture image from the frame buffer.

void glCopyTexSubImage2D(

GLenum target,
GLint level,
GLint xoffset,
GLint yoffset,
GLint x,
GLint y,
GLsizei width,
GLsizei height
);
Parameters

target

The target to which the image data will be changed and can only have the value GL_TEXTURE_2D.

level

The level-of-detail number. Level 0 is the base image. Level n is the nth mipmap reduction image.

xoffset

The texel offset in the x direction within the texture array.

yoffset

The texel offset in the y direction within the texture array.

x, y

The window coordinates of the lower-left corner of the row of pixels to be copied.

width

The width of the sub-image of the texture image. Specifying a texture sub-image with zero width has no effect.

height

The height of the sub-image of the texture image. Specifying a texture sub-image with zero width has no effect.

Remarks

The glCopyTexSubImage2D function replaces a rectangular portion of a two-dimensional texture image with pixels from the current frame buffer, rather than from main memory as is the case for glTexSubImage2D.

A rectangle of pixels beginning with the x and y window coordinates and with the dimensions width and height replaces the portion of the texture array with the indexes xoffset through xoffset + (width − 1), with the indexes yoffset through yoffset + (width − 1) at the mipmap level specified by level. The destination rectangle in the texture array cannot include any texels outside the originally specified texture array.

The glCopyTexSubImage2D function processes the pixels in a row in the same way as glCopyPixels except that before the final conversion of the pixels, all pixel component values are clamped to the range [0, 1] and converted to the texture’s internal format for storage in the texture array. Pixel ordering is determined with lower x coordinates corresponding to lower texture coordinates. If any of the pixels within a specified row of the current frame buffer are outside the window associated with the current rendering context, then their values are undefined.

If any of the pixels within the specified rectangle of the current frame buffer are outside the read window associated with the current rendering context, then the values obtained for those pixels are undefined. No change is made to the internalFormat, width, height, or border parameter of the specified texture array or to texel values outside the specified texture sub-image.

You cannot include calls to glCopyTexSubImage2D in display lists.

Note  The glCopyTexSubImage2D function is only available in OpenGL version 1.1 or later.

Texturing has no effect in color-index mode. The glPixelStore and glPixelTransfer functions affect texture images in exactly the way they affect the way pixels are drawn using glDrawPixels.

The following functions retrieve information related to glCopyTexSubImage2D:

glGetTexImage

glIsEnabled with argument GL_TEXTURE_2D.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target was not an accepted value.
GL_INVALID_VALUE	level was less than zero or greater than log sub 2(max), where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE	xoffset was less than border, (xoffset + width) was greater than (w + border), yoffset was less than border, or (yoffset + height) was greater than (h + border), where w is GL_TEXTURE_WIDTH, h is GL_TEXTURE_HEIGHT, and border is GL_TEXTURE_BORDER. Note that w includes twice the border width.
GL_INVALID_VALUE	width was less than border or y was less than border, where border is the border width of the texture array.
GL_INVALID_OPERATION	The texture array was not defined by a previous glTexImage2D operation.
GL_INVALID_OPERATION	glCopyTexSubImage2D was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glCopyPixels, glCopyTexSubImage1D, glDrawPixels, glEnd, glFog, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage2D, glTexSubImage2D, glTexParameter


glCullFace [New - Windows 95, OEM Service Release 2]
glCullFace

[New - Windows 95, OEM Service Release 2]

The glCullFace function specifies whether front- or back-facing facets can be culled.

void glCullFace(

GLenum mode
);
Parameters

mode

Specifies whether front- or back-facing facets are candidates for culling. Symbolic constants GL_FRONT and GL_BACK are accepted. The default value is GL_BACK.

Remarks

The glCullFace function specifies whether front- or back-facing facets are culled (as specified by mode) when facet culling is enabled. You enable and disable facet culling using glEnable and glDisable with the argument GL_CULL_FACE. Facets include triangles, quadrilaterals, polygons, and rectangles.

The glFrontFace function specifies which of the clockwise and counterclockwise facets are front-facing and back-facing.

The following functions retrieve information related to glCullFace:

glGet with argument GL_CULL_FACE_MODE

glIsEnabled with argument GL_CULL_FACE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	mode was not an accepted value.
GL_INVALID_OPERATION	glCullFace was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glDisable, glEnable, glEnd, glFrontFace, glGet, glIsEnabled


glDeleteLists [New - Windows 95, OEM Service Release 2]
glDeleteLists

[New - Windows 95, OEM Service Release 2]

The glDeleteLists function deletes a contiguous group of display lists.

void glDeleteLists(

GLuint list,
GLsizei range
);
Parameters

list

The integer name of the first display list to delete.

range

The number of display lists to delete.

Remarks

The glDeleteLists function causes a contiguous group of display lists to be deleted. The list parameter is the name of the first display list to be deleted, and range is the number of display lists to delete. All display lists d with list ≤ d ≤ list + range − 1 are deleted.

All storage locations allocated to the specified display lists are freed, and the names are available for reuse at a later time. Names within the range that do not have an associated display list are ignored. If range is zero, nothing happens.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	range was negative.
GL_INVALID_OPERATION	glDeleteLists was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glCallList, glCallLists, glEnd, glGenLists, glIsList, glNewList


glDeleteTextures [New - Windows 95, OEM Service Release 2]
glDeleteTextures

[New - Windows 95, OEM Service Release 2]

The glDeleteTextures function deletes named textures.

void glDeleteTextures(

GLsizei n,
const GLuint * textures
);
Parameters

n

The number of textures to be deleted.

textures

An array of textures to be deleted.

Remarks

The glDeleteTextures function deletes n textures named by the elements of the array textures. After a texture is deleted, it has no contents or dimensionality, and its name is free for reuse (for example, by glGenTextures). The glDeleteTextures function ignores zeros and names that do not correspond to existing textures.

If a texture that is currently bound is deleted, the binding reverts to zero (the default texture).

You cannot include calls to glDeleteTextures in display lists.

Note  The glDeleteTextures function is only available in OpenGL version 1.1 or later.

The following function retrieves information related to glDeleteTextures:

glIsTexture

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	n was a negative value.
GL_INVALID_OPERATION	glDeleteTextures was called between a call to glBegin and the corresponding call to glEnd.
See Also

glAreTexturesResident, glBegin, glBindTexture, glEnd, glGenTextures, glGet, glGetTexParameter, glIsTexture, glPrioritizeTextures, glTexGen, glTexImage1D, glTexImage2D, glTexParameter


glDepthFunc [New - Windows 95, OEM Service Release 2]
glDepthFunc

[New - Windows 95, OEM Service Release 2]

The glDepthFunc function specifies the value used for depth-buffer comparisons.

void glDepthFunc(

GLenum func
);
Parameters

func

The depth-comparison function. The following symbolic constants are accepted.

Symbolic Constant	Meaning
GL_NEVER	Never passes.
GL_LESS	Passes if the incoming z value is less than the stored z value. This is the default value.
GL_EQUAL	Passes if the incoming z value is equal to the stored z value.
GL_LEQUAL	Passes if the incoming z value is less than or equal to the stored z value.
GL_GREATER	Passes if the incoming z value is greater than the stored z value.
GL_NOTEQUAL	Passes if the incoming z value is not equal to the stored z value.
GL_GEQUAL	Passes if the incoming z value is greater than or equal to the stored z value.
GL_ALWAYS	Always passes.
Remarks

The glDepthFunc function specifies the function used to compare each incoming pixel z value with the z value present in the depth buffer. The comparison is performed only if depth testing is enabled. (See glEnable with the argument GL_DEPTH_TEST.)

Initially, depth testing is disabled.

The following functions retrieve information related to glDepthFunc:

glGet with argument GL_DEPTH_FUNC

glIsEnabled with argument GL_DEPTH_TEST

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	func was not an accepted value.
GL_INVALID_OPERATION	glDepthFunc was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glDepthRange, glEnable, glEnd, glGet, glIsEnabled


glDepthMask [New - Windows 95, OEM Service Release 2]
glDepthMask

[New - Windows 95, OEM Service Release 2]

The glDepthMask function enables or disables writing into the depth buffer.

void glDepthMask(

GLboolean flag
);
Parameters

flag

Specifies whether the depth buffer is enabled for writing. If flag is zero, depth-buffer writing is disabled. Otherwise, it is enabled. Initially, depth-buffer writing is enabled.

Remarks

The following function retrieves information related to glDepthMask:

glGet with argument GL_DEPTH_WRITEMASK

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glDepthMask was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glColorMask, glDepthFunc, glDepthRange, glEnd, glGet, glIndexMask, glStencilMask


glDepthRange [New - Windows 95, OEM Service Release 2]
glDepthRange

[New - Windows 95, OEM Service Release 2]

The glDepthRange function specifies the mapping of z values from normalized device coordinates to window coordinates.

void glDepthRange(

GLclampd znear,
GLclampd zfar
);
Parameters

znear

The mapping of the near clipping plane to window coordinates. The default value is 0.

zfar

The mapping of the far clipping plane to window coordinates. The default value is 1.

Remarks

After clipping and division by w, z-coordinates range from −1.0 to 1.0, corresponding to the near and far clipping planes. The glDepthRange function specifies a linear mapping of the normalized z-coordinates in this range to window z-coordinates. Regardless of the actual depth buffer implementation, window coordinate depth values are treated as though they range from 0.0 through 1.0 (like color components). Thus, the values accepted by glDepthRange are both clamped to this range before they are accepted.

The default mapping of 0,1 maps the near plane to 0 and the far plane to 1. With this mapping, the depth-buffer range is fully utilized.

It is not necessary that znear be less than zfar. Reverse mappings such as 1,0 are acceptable.

The following function retrieves information related to glDepthRange:

glGet with argument GL_DEPTH_RANGE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glDepthRange was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glDepthFunc, glEnd, glGet, glViewport


glDrawArrays [New - Windows 95, OEM Service Release 2]
glDrawArrays

[New - Windows 95, OEM Service Release 2]

The glDrawArrays function specifies multiple primitives to render.

void glDrawArrays(

GLenum mode,
GLint first,
GLsizei count
);
Parameters

mode

The kind of primitives to render. The following constants specify acceptable types of primitives: GL_POINTS, GL_LINE_STRIP, GL_LINE_LOOP, GL_LINES, GL_TRIANGLE_STRIP, GL_TRIANGLE_FAN, GL_TRIANGLES, GL_QUAD_STRIP, GL_QUADS, and GL_POLYGON.

first

The starting index in the enabled arrays.

count

The number of indexes to render.

Remarks

With glDrawArrays, you can specify multiple geometric primitives to render. Instead of calling separate OpenGL functions to pass each individual vertex, normal, or color, you can specify separate arrays of vertices, normals, and colors to define a sequence of primitives (all the same kind) with a single call to glDrawArrays.

When you call glDrawArrays, count sequential elements from each enabled array are used to construct a sequence of geometric primitives, beginning with the first element. The mode parameter specifies what kind of primitive to construct and how to use the array elements to construct the primitives.

After glDrawArrays returns, the values of vertex attributes that are modified by glDrawArrays are undefined. For example, if GL_COLOR_ARRAY is enabled, the value of the current color is undefined after glDrawArrays returns. Attributes not modified by glDrawArrays remain defined. When GL_VERTEX_ARRAY is not enabled, no geometric primitives are generated but the attributes corresponding to enabled arrays are modified.

You can include glDrawArrays in display lists. When you include glDrawArrays in a display list, the necessary array data, determined by the array pointers and the enables, are generated and entered in the display list. The values of array pointers and enables are determined during the creation of display lists.

You can read static array data at any time. If any static array elements are modified and the array is not specified again, the results of any subsequent calls to glDrawArrays are undefined.

Although no error is generated when you specify an array more than once within glBegin and glEnd pairs, the results are undefined.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	count was negative.
GL_INVALID_ENUM	mode was not an accepted value.
GL_INVALID_OPERATION	glDrawArrays was called between a call to glBegin and the corresponding call to glEnd.
See Also

glArrayElement, glBegin, glColorPointer, glEdgeFlagPointer, glEnd, glGetPointerv, glGetString, glIndexPointer, glNormalPointer, glTexCoordPointer, glVertexPointer


glDrawBuffer [New - Windows 95, OEM Service Release 2]
glDrawBuffer

[New - Windows 95, OEM Service Release 2]

The glDrawBuffer function specifies which color buffers are to be drawn into.

void glDrawBuffer(

GLenum mode
);
Parameters

mode

Specifies up to four color buffers to be drawn into with the following acceptable symbolic constants:

GL_NONE

No color buffers are written.

GL_FRONT_LEFT

Only the front-left color buffer is written.

GL_FRONT_RIGHT

Only the front-right color buffer is written.

GL_BACK_LEFT

Only the back-left color buffer is written.

GL_BACK_RIGHT

Only the back-right color buffer is written.

GL_FRONT

Only the front-left and front-right color buffers are written. If there is no front-right color buffer, only the front left-color buffer is written.

GL_BACK

Only the back-left and back-right color buffers are written. If there is no back-right color buffer, only the back-left color buffer is written.

GL_LEFT

Only the front-left and back-left color buffers are written. If there is no back-left color buffer, only the front-left color buffer is written.

GL_RIGHT

Only the front-right and back-right color buffers are written. If there is no back-right color buffer, only the front-right color buffer is written.

GL_FRONT_AND_BACK

All the front and back color buffers (front-left, front-right, back-left, back-right) are written. If there are no back color buffers, only the front-left and front-right color buffers are written. If there are no right color buffers, only the front-left and back-left color buffers are written. If there are no right or back color buffers, only the front-left color buffer is written.

GL_AUXi

Only the auxiliary color buffer i is written; i is between 0 and GL_AUX_BUFFERS −1. (GL_AUX_BUFFERS is not the upper limit; use glGet to query the number of available aux buffers.)

The default value is GL_FRONT for single-buffered contexts, and GL_BACK for double-buffered contexts.

Remarks

When colors are written to the frame buffer, they are written into the color buffers specified by glDrawBuffer.

If more than one color buffer is selected for drawing, then blending or logical operations are computed and applied independently for each color buffer and can produce different results in each buffer.

Monoscopic contexts include only left buffers, and stereoscopic contexts include both left and right buffers. Likewise, single-buffered contexts include only front buffers, and double-buffered contexts include both front and back buffers. The context is selected at OpenGL initialization.

It is always the case that GL_AUXi = GL_AUX0 + i.

The following functions retrieve information related to the glDrawBuffer function:

glGet with argument GL_DRAW_BUFFER

glGet with argument GL_AUX_BUFFERS

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	mode was not an accepted value.
GL_INVALID_OPERATION	None of the buffers indicated by mode existed.
GL_INVALID_OPERATION	glDrawBuffer was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glBlendFunc, glColorMask, glEnd, glGet, glIndexMask, glLogicOp, glReadBuffer


glDrawElements [New - Windows 95, OEM Service Release 2]
glDrawElements

[New - Windows 95, OEM Service Release 2]

The glDrawElements function renders primitives from array data.

void glDrawElements(

GLenum mode,
GLsizei count,
GLenum type,
const GLvoid *indices
);
Parameters

mode

The kind of primitives to render. It can assume one of the following symbolic values: GL_POINTS, GL_LINE_STRIP, GL_LINE_LOOP, GL_LINES, GL_TRIANGLE_STRIP, GL_TRIANGLE_FAN, GL_TRIANGLES, GL_QUAD_STRIP, GL_QUADS, and GL_POLYGON.

count

The number of elements to be rendered.

type

The type of the values in indices. Must be one of GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT, or GL_UNSIGNED_INT.

indices

A pointer to the location where the indices are stored.

Remarks

The glDrawElements function enables you to specify multiple geometric primitives with very few function calls. Instead of calling an OpenGL function to pass each individual vertex, normal, or color, you can specify separate arrays of vertexes, normals, and colors beforehand and use them to define a sequence of primitives (all of the same type) with a single call to glDrawElements.

When you call the glDrawElements function, it uses count sequential elements from indices to construct a sequence of geometric primitives. The mode parameter specifies what kind of primitives are constructed, and how the array elements are used to construct these primitives. If GL_VERTEX_ARRAY is not enabled, no geometric primitives are generated.

Vertex attributes that are modified by glDrawElements have an unspecified value after glDrawElements returns. For example, if GL_COLOR_ARRAY is enabled, the value of the current color is undefined after glDrawElements executes. Attributes that aren't modified remain unchanged.

You can include the glDrawElements function in display lists. When glDrawElements is included in a display list, the necessary array data (determined by the array pointers and enables) is also entered into the display list. Because the array pointers and enables are client-side state variables, their values affect display lists when the lists are created, not when the lists are executed.

Note  The glDrawElements function is only available in OpenGL version 1.1 or later.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	mode was not an accepted value.
GL_INVALID_VALUE	count was a negative value.
GL_INVALID_OPERATION	glDrawElements was called between a call to glBegin and the corresponding call to glEnd.
See Also

glArrayElement, glBegin, glColorPointer, glDrawArrays, glEdgeFlagPointer, glEnd, glGetPointerv, glIndexPointer, glNormalPointer, glTexCoordPointer, glVertexPointer


glDrawPixels [New - Windows 95, OEM Service Release 2]
glDrawPixels

[New - Windows 95, OEM Service Release 2]

The glDrawPixels function writes a block of pixels to the frame buffer.

void glDrawPixels(

GLsizei width,
GLsizei height,
GLenum format,
GLenum type,
const GLvoid *pixels
);
Parameters

width, height

The dimensions of the pixel rectangle that will be written into the frame buffer.

format

The format of the pixel data. Acceptable symbolic constants are:

GL_COLOR_INDEX

Each pixel is a single value, a color index.

1.	The glDrawPixels function converts each pixel to fixed-point format, with an unspecified number of bits to the right of the binary point, regardless of the memory data type. Floating-point values convert to true fixed-point values. The glDrawPixels function converts signed and unsigned integer data with all fraction bits set to zero. The function converts bitmap data to either 0.0 or 1.0.

2.	The glDrawPixels function shifts each fixed-point index left by GL_INDEX_SHIFT bits and adds it to GL_INDEX_OFFSET. If GL_INDEX_SHIFT is negative, the shift is to the right. In either case, zero bits fill otherwise unspecified bit locations in the result.

3.	When in RGBA mode, glDrawPixels converts the resulting index to an RGBA pixel using the GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, and GL_PIXEL_MAP_I_TO_A tables. When in the color-index mode and GL_MAP_COLOR is true, the index is replaced with the value that glDrawPixels references in lookup table GL_PIXEL_MAP_I_TO_I.

4.	Whether the lookup replacement of the index is done or not, the integer part of the index is ANDed with 2b − 1, where b is the number of bits in a color-index buffer.

5.	The resulting indexes or RGBA colors are then converted to fragments by attaching the current raster position z-coordinate and texture coordinates to each pixel, and then assigning x and y window coordinates to the nth fragment such that

x (n)  = x (r)  + n mod width

y (n)  = y (r)  +  n/width

where (x (r) , y (r) ) is the current raster position.

6.	The glDrawPixels function treats these pixel fragments just like the fragments generated by rasterizing points, lines, or polygons. It applies texture mapping, fog, and all the fragment operations before writing the fragments to the frame buffer.

GL_STENCIL_INDEX

Each pixel is a single value, a stencil index.

1.	The glDrawPixels function converts it to fixed-point format, with an unspecified number of bits to the right of the binary point, regardless of the memory data type. Floating-point values convert to true fixed-point values. The glDrawPixels function converts signed and unsigned integer data with all fraction bits set to zero. Bitmap data converts to either 0.0 or 1.0.

2.	The glDrawPixels function shifts each fixed-point index left by GL_INDEX_SHIFT bits, and adds it to GL_INDEX_OFFSET. If GL_INDEX_SHIFT is negative, the shift is to the right. In either case, zero bits fill otherwise unspecified bit locations in the result.

3.	If GL_MAP_STENCIL is true, the index is replaced with the value that glDrawPixels references in lookup table GL_PIXEL_MAP_S_TO_S.

4.	Whether the lookup replacement of the index is done or not, the integer part of the index is then ANDed with 2b − 1, where b is the number of bits in the stencil buffer. The resulting stencil indexes are then written to the stencil buffer such that the nth index is written to location

x (n)  = x (r)  + n mod width

y (n)  = y (r)  +  n /width

where (x (r) , y (r) ) is the current raster position. Only the pixel ownership test, the scissor test, and the stencil writemask affect these writes.

GL_DEPTH_COMPONENT

Each pixel is a single-depth component.

1.	The glDrawPixels function converts floating-point data directly to an internal floating-point format with unspecified precision. Signed integer data is mapped linearly to the internal floating-point format such that the most positive representable integer value maps to 1.0, and the most negative representable value maps to −1.0. Unsigned integer data is mapped similarly: the largest integer value maps to 1.0, and zero maps to 0.0.

2.	The glDrawPixels function multiplies the resulting floating-point depth value by GL_DEPTH_SCALE and adds it to GL_DEPTH_BIAS. The result is clamped to the range [0,1].

3.	The glDrawPixels function converts the resulting depth components to fragments by attaching the current raster position color or color index and texture coordinates to each pixel, and then assigning x and y window coordinates to the nth fragment such that

x (n)  = x (r)  + n mod width

y (n)  = y (r)  +  n /width

where (x (r) , y (r) ) is the current raster position.

4.	These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. The glDrawPixels function applies texture mapping, fog, and all the fragment operations before writing the fragments to the frame buffer.

GL_RGBA

Each pixel is a four-component group in this order: red, green, blue, alpha.

1.	The glDrawPixels function converts floating-point values directly to an internal floating-point format with unspecified precision. Signed integer values are mapped linearly to the internal floating-point format such that the most positive representable integer value maps to 1.0, and the most negative representable value maps to − 1.0. Unsigned integer data is mapped similarly: the largest integer value maps to 1.0, and zero maps to 0.0.

2.	The glDrawPixels function multiplies the resulting floating-point color values by GL_c_SCALE and adds them to GL_c_BIAS, where c is RED, GREEN, BLUE, and ALPHA for the respective color components. The results are clamped to the range [0,1].

3.	If GL_MAP_COLOR is true, glDrawPixels scales each color component by the size of lookup table GL_PIXEL_MAP_c_TO_c, and then replaces the component by the value that it references in that table; c is R, G, B, or A, respectively.

4.	The glDrawPixels function converts the resulting RGBA colors to fragments by attaching the current raster position z-coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that

x (n)  = x (r)  + n mod width

y (n)  = y (r)  +  n /width

where (x (r) , y (r) ) is the current raster position.

5.	These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. The glDrawPixels function applies texture mapping, fog, and all the fragment operations before writing the fragments to the frame buffer.

GL_RED

Each pixel is a single red component.

The glDrawPixels function converts this component to the internal floating-point format in the same way that the red component of an RGBA pixel is, and then converts it to an RGBA pixel with green and blue set to 0.0, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_GREEN

Each pixel is a single green component.

The glDrawPixels function converts this component to the internal floating-point format in the same way that the green component of an RGBA pixel is, and then converts it to an RGBA pixel with red and blue set to 0.0, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_BLUE

Each pixel is a single blue component.

The glDrawPixels function converts this component to the internal floating-point format in the same way that the blue component of an RGBA pixel is, and then converts it to an RGBA pixel with red and green set to 0.0, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_ALPHA

Each pixel is a single alpha component.

The glDrawPixels function converts this component to the internal floating-point format in the same way that the alpha component of an RGBA pixel is, and then converts it to an RGBA pixel with red, green, and blue set to 0.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_RGB

Each pixel is a group of three components in this order: red, green, blue.

The glDrawPixels function converts each component to the internal floating-point format in the same way that the red, green, and blue components of an RGBA pixel are. The color triple is converted to an RGBA pixel with alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_LUMINANCE

Each pixel is a single luminance component.

The glDrawPixels function converts this component to the internal floating-point format in the same way that the red component of an RGBA pixel is, and then converts it to an RGBA pixel with red, green, and blue set to the converted luminance value, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_LUMINANCE_ALPHA

Each pixel is a group of two components in this order: luminance, alpha.

The glDrawPixels function converts the two components to the internal floating-point format in the same way that the red component of an RGBA pixel is, and then converts them to an RGBA pixel with red, green, and blue set to the converted luminance value, and alpha set to the converted alpha value. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_BGR_EXT

Each pixel is a group of three components in this order: blue, green, red.

GL_BGR_EXT provides a format that matches the memory layout of Windows device-independent bitmaps (DIBs). Thus your applications can use the same data with Win32 function calls and OpenGL pixel function calls.

GL_BGRA_EXT

Each pixel is a group of four components in this order: blue, green, red, alpha.

GL_BGRA_EXT provides a format that matches the memory layout of Windows device-independent bitmaps (DIBs). Thus your applications can use the same data with Win32 function calls and OpenGL pixel function calls.

type

The data type for pixels. The following symbolic constants are accepted: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, and GL_FLOAT.

The following table summarizes the meaning of the valid constants for the type parameter.

Type	Meaning
GL_UNSIGNED_BYTE	Unsigned 8-bit integer
GL_BYTE	Signed 8-bit integer
GL_BITMAP	Single bits in unsigned 8-bit integers
GL_UNSIGNED_SHORT	Unsigned 16-bit integer
GL_SHORT	Signed 16-bit integer
GL_UNSIGNED_INT	Unsigned 32-bit integer
GL_INT	32-bit integer
GL_FLOAT	Single-precision floating-point
pixels

A pointer to the pixel data.

Remarks

The glDrawPixels function reads pixel data from memory and writes it into the frame buffer relative to the current raster position. Use glRasterPos to set the current raster position, and use glGet with argument GL_CURRENT_RASTER_POSITION to query the raster position.

Several parameters define the encoding of pixel data in memory and control the processing of the pixel data before it is placed in the frame buffer. These parameters are set with four functions: glPixelStore, glPixelTransfer, glPixelMap, and glPixelZoom. This topic describes the effects on glDrawPixels of many, but not all, of the parameters specified by these four functions.

Data is read from pixels as a sequence of signed or unsigned bytes, signed or unsigned shorts, signed or unsigned integers, or single-precision floating-point values, depending on type. Each of these bytes, shorts, integers, or floating-point values is interpreted as one color or depth component, or one index, depending on format. Indexes are always treated individually. Color components are treated as groups of one, two, three, or four values, again based on format. Both individual indexes and groups of components are referred to as pixels. If type is GL_BITMAP, the data must be unsigned bytes, and format must be either GL_COLOR_INDEX or GL_STENCIL_INDEX. Each unsigned byte is treated as eight 1-bit pixels, with bit ordering determined by GL_UNPACK_LSB_FIRST (see glPixelStore).

The width by height pixels are read from memory, starting at location pixels. By default, these pixels are taken from adjacent memory locations, except that after all width pixels are read, the read pointer is advanced to the next 4-byte boundary. The glPixelStore function specifies the 4-byte row alignment with argument GL_UNPACK_ALIGNMENT, and you can set it to 1, 2, 4, or 8 bytes. Other pixel store parameters specify different read pointer advancements, both before the first pixel is read, and after all width pixels are read.

The glPixelStore function operates on each of the width-by-height pixels that it reads from memory in the same way, based on the values of several parameters specified by glPixelTransfer and glPixelMap. The details of these operations, as well as the target buffer into which the pixels are drawn, are specific to the format of the pixels, as specified by format.

The rasterization described thus far assumes pixel zoom factors of 1.0. If you use glPixelZoom to change the x and y pixel zoom factors, pixels are converted to fragments as follows. If (x (r) , y (r) ) is the current raster position, and a given pixel is in the n column and m row of the pixel rectangle, then fragments are generated for pixels whose centers are in the rectangle with corners at

(x (r)  + zoom (x)  n, y (r)  + zoom (y)  m)

(x (r)  + zoom (x)  (n + 1), y (r)  + zoom (y)  (m + 1))

where zoom (x)  is the value of GL_ZOOM_X and zoom (y)  is the value of GL_ZOOM_Y.

The following functions retrieve information related to glDrawPixels:

glGet with argument GL_CURRENT_RASTER_POSITION

glGet with argument GL_CURRENT_RASTER_POSITION_VALID

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	Either width or height was negative.
GL_INVALID_ENUM	Either format or type was not an accepted value.
GL_INVALID_OPERATION	format was GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_BGR_EXT, GL_BGRA_EXT, GL_LUMINANCE, or GL_LUMINANCE_ALPHA, and OpenGL was in color-index mode.
GL_INVALID_ENUM	type was GL_BITMAP and format was not either GL_COLOR_INDEX or GL_STENCIL_INDEX.
GL_INVALID_OPERATION	format was GL_STENCIL_INDEX and there was no stencil buffer.
GL_INVALID_OPERATION	glDrawPixels was called between a call to glBegin and the corresponding call to glEnd.
See Also

glAlphaFunc, glBegin, glBlendFunc, glCopyPixels, glDepthFunc, glEnd, glGet, glLogicOp, glPixelMap, glPixelStore, glPixelTransfer, glPixelZoom, glRasterPos, glReadPixels, glScissor, glStencilFunc


glEdgeFlag [New - Windows 95, OEM Service Release 2]
glEdgeFlag, glEdgeFlagv

[New - Windows 95, OEM Service Release 2]

The glEdgeFlag and glEdgeFlagv functions flag edges as either boundary or nonboundary.

void glEdgeFlag(

GLboolean flag
);
Parameters

flag

In glEdgeFlag, specifies the current edge flag value, either TRUE or FALSE.

void glEdgeFlagv(

const GLboolean * flag
);
Parameters

flag

In glEdgeFlagv, specifies a pointer to an array that contains a single Boolean element, which replaces the current edge flag value.

Remarks

Each vertex of a polygon, separate triangle, or separate quadrilateral specified between a glBegin/glEnd pair is marked as the start of either a boundary or nonboundary edge. If the current edge flag is TRUE when the vertex is specified, the vertex is marked as the start of a boundary edge. If the current edge flag is FALSE, the vertex is marked as the start of a nonboundary edge. The glEdgeFlag function sets the edge flag to TRUE if flag is nonzero, FALSE otherwise.

The vertices of connected triangles and connected quadrilaterals are always marked as boundary, regardless of the value of the edge flag.

Boundary and nonboundary edge flags on vertices are significant only if GL_POLYGON_MODE is set to GL_POINT or GL_LINE. See glPolygonMode.

Initially, the edge flag bit is TRUE.

The current edge flag can be updated at any time. In particular, glEdgeFlag can be called between a call to glBegin and the corresponding call to glEnd.

The following function retrieves information related to the glEdgeFlag function:

glGet with argument GL_EDGE_FLAG

See Also

glBegin, glEnd, glGet, glPolygonMode


glEdgeFlagPointer [New - Windows 95, OEM Service Release 2]
glEdgeFlagPointer

[New - Windows 95, OEM Service Release 2]

The glEdgeFlagPointer function defines an array of edge flags.

void glEdgeFlagPointer(

GLsizei stride,
GLsizei count,
const GLboolean * pointer
);
Parameters

stride

The byte offset between consecutive edge flags. When stride is zero, the edge flags are tightly packed in the array.

count

The number of edge flags, counting from the first, that are static.

pointer

A pointer to the first edge flag in the array.

Remarks

The glEdgeFlagPointer function specifies the location and data of an array of Boolean edge flags to use when rendering. The stride parameter determines the byte offset from one edge flag to the next, which enables the packing of vertices and attributes in a single array or storage in separate arrays. In some implementations, storing the vertices and attributes in a single array can be more efficient than using separate arrays.

Starting from the first edge-flag array element, count indicates the total number of static elements. Your application can modify static elements, but once the elements are modified, the application must explicitly specify the array again before using it for any rendering. Nonstatic array elements are not accessed until you call glDrawArrays or glArrayElement.

Static array data can be read at any time. If any static array elements are modified and the array is not specified again, the results of any subsequent calls to glEdgeFlagPointer are undefined.

An edge-flag array is enabled when you specify the GL_EDGE_FLAG_ARRAY constant with glEnableClientState. When enabled, glDrawArrays or glArrayElement uses the edge-flag array. By default the edge-flag array is disabled.

You cannot include glEdgeFlagPointer in display lists.

When you specify an edge-flag array using glEdgeFlagPointer, the values of all the function’s edge-flag array parameters are saved in a client-side state and static array elements can be cached. Because the edge-flag array parameters are in a client-side state, glPushAttrib and glPopAttrib do not save or restore their values.

Although calling glEdgeFlagPointer within a glBegin/glEnd pair does not generate an error, the results are undefined.

The following functions retrieve information related to the glEdgeFlagPointer function:

glIsEnabled with argument GL_EDGE_FLAG_ARRAY

glGet with argument GL_EDGE_FLAG_ARRAY_STRIDE

glGet with argument GL_EDGE_FLAG_ARRAY_COUNT

glGetPointerv with argument GL_EDGE_FLAG_ARRAY_POINTER

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	stride or count was negative.
See Also

glArrayElement, glBegin, glColorPointer, glDrawArrays, glEnableClientState, glEnd, glGet, glGetPointerv, glGetString, glIndexPointer, glIsEnabled, glNormalPointer, glPopAttrib, glPushAttrib, glTexCoordPointer, glVertexPointer


glEnable, glDisable [New - Windows 95, OEM Service Release 2]
glEnable, glDisable

[New - Windows 95, OEM Service Release 2]

The glEnable and glDisable functions enable or disable OpenGL capabilities.

void glEnable(

GLenum cap
);
void glDisable(

GLenum cap
);
Parameters

cap

A symbolic constant indicating an OpenGL capability.

For discussion of the values cap can take, see the following Remarks section.

Remarks

The glEnable and glDisable functions enable and disable various capabilities. Use glIsEnabled or glGet to determine the current setting of any capability.

Both glEnable and glDisable take a single argument, cap, which can assume one of the following values:

GL_ALPHA_TEST

If enabled, do alpha testing. See glAlphaFunc.

GL_AUTO_NORMAL

If enabled, compute surface normal vectors analytically when either GL_MAP2_VERTEX_3 or GL_MAP2_VERTEX_4 has generated vertices. See glMap2.

GL_BLEND

If enabled, blend the incoming RGBA color values with the values in the color buffers. See glBlendFunc.

GL_CLIP_PLANEi

If enabled, clip geometry against user-defined clipping plane i. See glClipPlane.

GL_COLOR_MATERIAL

If enabled, have one or more material parameters track the current color. See glColorMaterial.

GL_CULL_FACE

If enabled, cull polygons based on their winding in window coordinates. See glCullFace.

GL_DEPTH_TEST

If enabled, do depth comparisons and update the depth buffer. See glDepthFunc and glDepthRange.

GL_DITHER

If enabled, dither color components or indexes before they are written to the color buffer.

GL_FOG

If enabled, blend a fog color into the post-texturing color. See glFog.

GL_LIGHTi

If enabled, include light i in the evaluation of the lighting equation. See glLightModel and glLight.

GL_LIGHTING

If enabled, use the current lighting parameters to compute the vertex color or index. If disabled, associate the current color or index with each vertex. See glMaterial, glLightModel, and glLight.

GL_LINE_SMOOTH

If enabled, draw lines with correct filtering. If disabled, draw aliased lines. See glLineWidth.

GL_LINE_STIPPLE

If enabled, use the current line stipple pattern when drawing lines. See glLineStipple.

GL_LOGIC_OP

If enabled, apply the currently selected logical operation to the incoming and color-buffer indexes. See glLogicOp.

GL_MAP1_COLOR_4

If enabled, calls to glEvalCoord1, glEvalMesh1, and glEvalPoint1 generate RGBA values. See also glMap1.

GL_MAP1_INDEX

If enabled, calls to glEvalCoord1, glEvalMesh1, and glEvalPoint1 generate color indexes. See also glMap1.

GL_MAP1_NORMAL

If enabled, calls to glEvalCoord1, glEvalMesh1, and glEvalPoint1 generate normals. See also glMap1.

GL_MAP1_TEXTURE_COORD_1

If enabled, calls to glEvalCoord1, glEvalMesh1, and glEvalPoint1 generate s texture coordinates. See also glMap1.

GL_MAP1_TEXTURE_COORD_2

If enabled, calls to glEvalCoord1, glEvalMesh1, and glEvalPoint1 generate s and t texture coordinates. See also glMap1.

GL_MAP1_TEXTURE_COORD_3

If enabled, calls to glEvalCoord1, glEvalMesh1, and glEvalPoint1 generate s, t, and r texture coordinates. See also glMap1.

GL_MAP1_TEXTURE_COORD_4

If enabled, calls to glEvalCoord1, glEvalMesh1, and glEvalPoint1 generate s, t, r, and q texture coordinates. See also glMap1.

GL_MAP1_VERTEX_3

If enabled, calls to glEvalCoord1, glEvalMesh1, and glEvalPoint1 generate x, y, and z vertex coordinates. See also glMap1.

GL_MAP1_VERTEX_4

If enabled, calls to glEvalCoord1, glEvalMesh1, and glEvalPoint1 generate homogeneous x, y, z, and w vertex coordinates. See also glMap1.

GL_MAP2_COLOR_4

If enabled, calls to glEvalCoord2, glEvalMesh2, and glEvalPoint2 generate RGBA values. See also glMap2.

GL_MAP2_INDEX

If enabled, calls to glEvalCoord2, glEvalMesh2, and glEvalPoint2 generate color indexes. See also glMap2.

GL_MAP2_NORMAL

If enabled, calls to glEvalCoord2, glEvalMesh2, and glEvalPoint2 generate normals. See also glMap2.

GL_MAP2_TEXTURE_COORD_1

If enabled, calls to glEvalCoord2, glEvalMesh2, and glEvalPoint2 generate s texture coordinates. See also glMap2.

GL_MAP2_TEXTURE_COORD_2

If enabled, calls to glEvalCoord2, glEvalMesh2, and glEvalPoint2 generate s and t texture coordinates. See also glMap2.

GL_MAP2_TEXTURE_COORD_3

If enabled, calls to glEvalCoord2, glEvalMesh2, and glEvalPoint2 generate s, t, and r texture coordinates. See also glMap2.

GL_MAP2_TEXTURE_COORD_4

If enabled, calls to glEvalCoord2, glEvalMesh2, and glEvalPoint2 generate s, t, r, and q texture coordinates. See also glMap2.

GL_MAP2_VERTEX_3

If enabled, calls to glEvalCoord2, glEvalMesh2, and glEvalPoint2 generate x, y, and z vertex coordinates. See also glMap2.

GL_MAP2_VERTEX_4

If enabled, calls to glEvalCoord2, glEvalMesh2, and glEvalPoint2 generate homogeneous x, y, z, and w vertex coordinates. See also glMap2.

GL_NORMALIZE

If enabled, normal vectors specified with glNormal are scaled to unit length after transformation. See glNormal.

GL_POINT_SMOOTH

If enabled, draw points with proper filtering. If disabled, draw aliased points. See glPointSize.

GL_POLYGON_SMOOTH

If enabled, draw polygons with proper filtering. If disabled, draw aliased polygons. See glPolygonMode.

GL_POLYGON_STIPPLE

If enabled, use the current polygon stipple pattern when rendering polygons. See glPolygonStipple.

GL_SCISSOR_TEST

If enabled, discard fragments that are outside the scissor rectangle. See glScissor.

GL_STENCIL_TEST

If enabled, do stencil testing and update the stencil buffer. See glStencilFunc and glStencilOp.

GL_TEXTURE_1D

If enabled, one-dimensional texturing is performed (unless two-dimensional texturing is also enabled). See glTexImage1D.

GL_TEXTURE_2D

If enabled, two-dimensional texturing is performed. See glTexImage2D.

GL_TEXTURE_GEN_Q

If enabled, the q texture coordinate is computed using the texture-generation function defined with glTexGen. Otherwise, the current q texture coordinate is used.

GL_TEXTURE_GEN_R

If enabled, the r texture coordinate is computed using the texture generation function defined with glTexGen. If disabled, the current r texture coordinate is used.

GL_TEXTURE_GEN_S

If enabled, the s texture coordinate is computed using the texture generation function defined with glTexGen. If disabled, the current s texture coordinate is used.

GL_TEXTURE_GEN_T

If enabled, the t texture coordinate is computed using the texture generation function defined with glTexGen. If disabled, the current t texture coordinate is used.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	cap was not one of the values listed in the preceding Remarks section.
GL_INVALID_OPERATION	glEnable was called between a call to glBegin and the corresponding call to glEnd.
See Also

glAlphaFunc, glArrayElement, glBegin, glBlendFunc, glClipPlane, glColorMaterial, glColorPointer, glCullFace, glDepthFunc, glDepthRange, glDrawArrays, glEdgeFlagPointer, glEnd, glEvalCoord1, glEvalMesh1, glEvalPoint1, glFog, glGet, glIndexPointer, glIsEnabled, glLight, glLightModel, glLineWidth, glLineStipple, glLogicOp, glMap1, glMap2, glMaterial, glNormal, glNormalPointer, glPointSize, glPolygonMode, glPolygonStipple, glScissor, glStencilFunc, glStencilOp, glTexCoordPointer, glTexGen, glTexImage1D, glTexImage2D


glEnableClientState, glDisableClientState [New - Windows 95, OEM Service Release 2]
glEnableClientState, glDisableClientState

[New - Windows 95, OEM Service Release 2]

The glEnableClientState and glDisableClientState functions enable and disable arrays respectively.

void glEnableClientState(

GLenum array
);
void glDisableClientState(

GLenum array
);
Parameters

array

A symbolic constant for the array you want to enable or disable. This parameter can assume one of the following values:

GL_COLOR_ARRAY

If enabled, use color arrays with calls to glArrayElement, glDrawElements, or glDrawArrays. See also glColorPointer.

GL_EDGE_FLAG_ARRAY

If enabled, use edge flag arrays with calls to glArrayElement, glDrawElements, or glDrawArrays. See also glEdgeFlagPointer.

GL_INDEX_ARRAY

If enabled, use index arrays with calls to glArrayElement, glDrawElements, or glDrawArrays. See also glIndexPointer.

GL_NORMAL_ARRAY

If enabled, use normal arrays with calls to glArrayElement, glDrawElements, or glDrawArrays. See also glNormalPointer.

GL_TEXTURE_COORD_ARRAY

If enabled, use texture coordinate arrays with calls to glArrayElement, glDrawElements, or glDrawArrays. See also glTexCoordPointer.

GL_VERTEX_ARRAY

If enabled, use vertex arrays with calls to glArrayElement, glDrawElements, or glDrawArrays. See also glVertexPointer.

Remarks

The glEnableClientState and glDisableClientState functions enable and disable various individual arrays. Use glIsEnabled or glGet to determine the current setting of any capability.

Calling glEnableClientState and glDisableClientState between calls to glBegin and the corresponding call to glEnd can cause an error. If no error is generated, the behavior is undefined.

Note  The glEnableClientState and glDisableClientState functions are only available in OpenGL version 1.1 or later.

Error Codes

The following is the error code generated and its condition.

Error Code	Condition
GL_INVALID_ENUM	array was not an accepted value.
See Also

glArrayElement, glBegin, glColorPointer, glDrawArrays, glDrawElements, glEdgeFlagPointer, glEnable, glEnd, glGetPointerv, glIndexPointer, glInterleavedArrays, glNormalPointer, glTexCoordPointer, glVertexPointer


glEvalCoord [New - Windows 95, OEM Service Release 2]
glEvalCoord

[New - Windows 95, OEM Service Release 2]

glEvalCoord1d, glEvalCoord1f, glEvalCoord2d, glEvalCoord2f, glEvalCoord1dv, glEvalCoord1fv, glEvalCoord2dv, glEvalCoord2fv

These functions evaluate enabled one- and two-dimensional maps.

void glEvalCoord1d(

GLdouble u
);
void glEvalCoord1f(

GLfloat u
);
void glEvalCoord2d(

GLdouble u,
GLdouble v
);
void glEvalCoord2f(

GLfloat u,
GLfloat v
);
Parameters

u

In glEvalCoord1d, glEvalCoord1f, glEvalCoord2d, and glEvalCoord2f, specifies a value that is the domain coordinate u to the basis function defined in a previous glMap1 or glMap2 function.

v

A value that is the domain coordinate v to the basis function defined in a previous glMap2 function. This argument is not present in a glEvalCoord1 function.

void glEvalCoord1dv(

const GLdouble * u
);
void glEvalCoord1fv(

const GLfloat * u
);
void glEvalCoord2dv(

const GLdouble * u
);
void glEvalCoord2fv(

const GLfloat * u
);
Parameters

u

In glEvalCoord1dv, glEvalCoord1fv, glEvalCoord2dv, and glEvalCoord2fv, specifies a pointer to an array containing either one or two domain coordinates. The first coordinate is u. The second coordinate is v, which is present only in glEvalCoord2 versions.

Remarks

The glEvalCoord1 function evaluates enabled one-dimensional maps at argument u. The glEvalCoord2 function does the same for two-dimensional maps using two domain values, u and v. Maps are defined with glMap1 and glMap2, and are enabled and disabled with glEnable and glDisable.

When one of the glEvalCoord functions is issued, all currently enabled maps of the indicated dimension are evaluated. Then, for each enabled map, it is as if the corresponding OpenGL function were issued with the computed value. That is, if GL_MAP1_INDEX or GL_MAP2_INDEX is enabled, a glIndex function is simulated. If GL_MAP1_COLOR_4 or GL_MAP2_COLOR_4 is enabled, a glColor function is simulated. If GL_MAP1_NORMAL or GL_MAP2_NORMAL is enabled, a normal vector is produced, and if any of GL_MAP1_TEXTURE_COORD_1, GL_MAP1_TEXTURE_COORD_2, GL_MAP1_TEXTURE_COORD_3, GL_MAP1_TEXTURE_COORD_4, GL_MAP2_TEXTURE_COORD_1, GL_MAP2_TEXTURE_COORD_2, GL_MAP2_TEXTURE_COORD_3, and GL_MAP2_TEXTURE_COORD_4 is enabled, then an appropriate glTexCoord function is simulated.

OpenGL uses evaluated values instead of current values for those evaluations that are enabled, and current values otherwise, for color, color index, normal, and texture coordinates. However, the evaluated values do not update the current values. Thus, if glVertex functions are interspersed with glEvalCoord functions, the color, normal, and texture coordinates associated with the glVertex functions are not affected by the values generated by the glEvalCoord functions, but only by the most recent glColor, glIndex, glNormal, and glTexCoord functions.

No functions are issued for maps that are not enabled. If more than one texture evaluation is enabled for a particular dimension (for example, GL_MAP2_TEXTURE_COORD_1 and GL_MAP2_TEXTURE_COORD_2), then only the evaluation of the map that produces the larger number of coordinates (in this case, GL_MAP2_TEXTURE_COORD_2) is carried out. GL_MAP1_VERTEX_4 overrides GL_MAP1_VERTEX_3, and GL_MAP2_VERTEX_4 overrides GL_MAP2_VERTEX_3, in the same manner. If neither a three- nor four-component vertex map is enabled for the specified dimension, glEvalCoord is ignored.

If automatic normal generation is enabled, glEvalCoord2 calls glEnable with argument GL_AUTO_NORMAL to generate surface normals analytically, regardless of the contents or enabling of the GL_MAP2_NORMAL map. Let

The generated normal n is

If automatic normal generation is disabled, the corresponding normal map GL_MAP2_NORMAL, if enabled, is used to produce a normal. If neither automatic normal generation nor a normal map is enabled, no normal is generated for glEvalCoord2 functions.

The following functions retrieve information related to the glEvalCoord functions:

glIsEnabled with argument GL_MAP1_VERTEX_3

glIsEnabled with argument GL_MAP1_VERTEX_4

glIsEnabled with argument GL_MAP1_INDEX

glIsEnabled with argument GL_MAP1_COLOR_4

glIsEnabled with argument GL_MAP1_NORMAL

glIsEnabled with argument GL_MAP1_TEXTURE_COORD_1

glIsEnabled with argument GL_MAP1_TEXTURE_COORD_2

glIsEnabled with argument GL_MAP1_TEXTURE_COORD_3

glIsEnabled with argument GL_MAP1_TEXTURE_COORD_4

glIsEnabled with argument GL_MAP2_VERTEX_3

glIsEnabled with argument GL_MAP2_VERTEX_4

glIsEnabled with argument GL_MAP2_INDEX

glIsEnabled with argument GL_MAP2_COLOR_4

glIsEnabled with argument GL_MAP2_NORMAL

glIsEnabled with argument GL_MAP2_TEXTURE_COORD_1

glIsEnabled with argument GL_MAP2_TEXTURE_COORD_2

glIsEnabled with argument GL_MAP2_TEXTURE_COORD_3

glIsEnabled with argument GL_MAP2_TEXTURE_COORD_4

glIsEnabled with argument GL_AUTO_NORMAL

glGetMap

See Also

glBegin, glColor, glDisable, glEnable, glEvalMesh, glEvalPoint, glGetMap, glIndex, glIsEnabled, glMap1, glMap2, glMapGrid, glNormal, glTexCoord, glVertex


glEvalMesh [New - Windows 95, OEM Service Release 2]
glEvalMesh1, glEvalMesh2

[New - Windows 95, OEM Service Release 2]

The glEvalMesh1 and glEvalMesh2 functions compute a one- or two-dimensional grid of points or lines.

void glEvalMesh1(

GLenum mode,
GLint i1,
GLint i2
);
Parameters

mode

In glEvalMesh1, specifies whether to compute a one-dimensional mesh of points or lines. The following symbolic constants are accepted: GL_POINT and GL_LINE.

i1, i2

The first and last integer values for grid domain variable i.

void glEvalMesh2(

GLenum mode,
GLint i1,
GLint i2,
GLint j1,
GLint j2
);
Parameters

mode

In glEvalMesh2, specifies whether to compute a two-dimensional mesh of points, lines, or polygons. The following symbolic constants are accepted: GL_POINT, GL_LINE, and GL_FILL.

i1, i2

The first and last integer values for grid domain variable i.

j1, j2

The first and last integer values for grid domain variable j.

Remarks

Use glMapGrid and glEvalMesh in tandem to efficiently generate and evaluate a series of evenly spaced map domain values. The glEvalMesh function steps through the integer domain of a one- or two-dimensional grid, whose range is the domain of the evaluation maps specified by glMap1 and glMap2. The mode parameter determines whether the resulting vertices are connected as points, lines, or filled polygons.

In the one-dimensional case, glEvalMesh1, the mesh is generated as if the following code fragment were executed:

glBegin(type) ;

for (i = i1; i <= i2; i += 1)

    glEvalCoord1(i·Δu + u (1) )

glEnd( );

where

Δu = (u (2)  − u (1) ) / n

and n, u (1) , and u (2)  are the arguments to the most recent glMapGrid1 function. The type parameter is GL_POINTS if mode is GL_POINT, or GL_LINES if mode is GL_LINE. The one absolute numeric requirement is that if i = n, then the value computed from i·Δ u + u (1)  is exactly u (2) .

In the two-dimensional case, glEvalMesh2, let

Δ u = (u (2)  − u (1) )/n

Δ v = (v (2)  − v (1) )/m,

where n, u (1) , u (2) , m, v (1) , and v (2)  are the arguments to the most recent glMapGrid2 function. Then, if mode is GL_FILL, glEvalMesh2 is equivalent to:

for (j = j1; j < j2; j += 1) {

    glBegin(GL_QUAD_STRIP);

    for (i = i1; i <= i2; i += 1) {

        glEvalCoord2(i·Δ u + u (1 ) , j ·Δ v + v (1) );

        glEvalCoord2(i·Δ u + u (1 ) , (j+1) ·Δ v + v (1) );

    }

    glEnd( );

}

If mode is GL_LINE, then a call to glEvalMesh2 is equivalent to:

for (j = j1; j <= j2; j += 1) {

    glBegin(GL_LINE_STRIP);

    for (i = i1; i <= i2; i += 1)

        glEvalCoord2(i·Δ u + u (1) , j·Δ v + v (1) );

    glEnd( );

}

    for (i = i1; i <= i2; i += 1) {

    glBegin(GL_LINE_STRIP);

    for (j = j1; j <= j1; j += 1)

        glEvalCoord2(i·Δ u + u (1) , j·Δ v + v (1) );

    glEnd( );

}

And finally, if mode is GL_POINT, then a call to glEvalMesh2 is equivalent to:

glBegin(GL_POINTS);

for (j = j1; j <= j2; j += 1) {

    for (i = i1; i <= i2; i += 1) {

        glEvalCoord2(i·Δ u + u (1) , j·Δ v + v (1) );

    }

}

glEnd( );

In all three cases, the only absolute numeric requirements are that if i = n, then the value computed from i·Δ u + u (1)  is exactly u (2) , and if j = m, then the value computed from j·Δ v + v (1)  is exactly v (2) .

The following functions retrieve information relating to glEvalMesh:

glGet with argument GL_MAP1_GRID_DOMAIN

glGet with argument GL_MAP2_GRID_DOMAIN

glGet with argument GL_MAP1_GRID_SEGMENTS

glGet with argument GL_MAP2_GRID_SEGMENTS

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	mode was not an accepted value.
GL_INVALID_OPERATION	glEvalMesh was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glEvalCoord, glEvalPoint, glMap1, glMap2, glMapGrid


glEvalPoint [New - Windows 95, OEM Service Release 2]
glEvalPoint1, glEvalPoint2

[New - Windows 95, OEM Service Release 2]

The glEvalPoint1 and glEvalPoint2 functions generate and evaluate a single point in a mesh.

void glEvalPoint1(

GLint i
);
void glEvalPoint2(

GLint i,
GLint j
);
Parameters

i

The integer value for grid domain variable i.

j

The integer value for grid domain variable j (glEvalPoint2 only).

Remarks

The glMapGrid and glEvalMesh functions are used in tandem to efficiently generate and evaluate a series of evenly spaced map domain values. You can use glEvalPoint to evaluate a single grid point in the same gridspace that is traversed by glEvalMesh. Calling glEvalPoint1 is equivalent to calling

glEvalCoord1(i·Δu + u (1) );

where

Δu = (u (2)  − u (1) ) / n

and n, u (1) , and u (2)  are the arguments to the most recent glMapGrid1 function. The one absolute numeric requirement is that if i = n, then the value computed from i·Δ u + u (1)  is exactly u (2) .

In the two-dimensional case, glEvalPoint2, let

Δu = (u (2)  − u (1) )/n

Δv = (v (2)  − v (1) )/m

where n, u (1) , u (2) , m, v (1) , and v (2)  are the arguments to the most recent glMapGrid2 function. Then the glEvalPoint2 function is equivalent to calling

glEvalCoord2(i·Δu + u (1) , j·Δv + v (1) );

The only absolute numeric requirements are that if i = n, then the value computed from i·Δu + u (1)  is exactly u (2) , and if j = m, then the value computed from j·Δv + v (1)  is exactly v (2) .

The following functions retrieve information relating to glEvalPoint1 and glEvalPoint2:

glGet with argument GL_MAP1_GRID_DOMAIN

glGet with argument GL_MAP2_GRID_DOMAIN

glGet with argument GL_MAP1_GRID_SEGMENTS

glGet with argument GL_MAP2_GRID_SEGMENTS

See Also

glEvalCoord, glEvalMesh, glGet, glMap1, glMap2, glMapGrid


glFeedbackBuffer [New - Windows 95, OEM Service Release 2]
glFeedbackBuffer

[New - Windows 95, OEM Service Release 2]

The glFeedbackBuffer function controls feedback mode.

void glFeedbackBuffer(

GLsizei size,
GLenum type,
GLfloat * buffer
);
Parameters

size

The maximum number of values that can be written into buffer.

type

A symbolic constant that describes the information that will be returned for each vertex. The following symbolic constants are accepted: GL_2D, GL_3D, GL_3D_COLOR, GL_3D_COLOR_TEXTURE, and GL_4D_COLOR_TEXTURE.

buffer

Returns the feedback data.

Remarks

The glFeedbackBuffer function controls feedback. Feedback, like selection, is an OpenGL mode. The mode is selected by calling glRenderMode with GL_FEEDBACK. When OpenGL is in feedback mode, no pixels are produced by rasterization. Instead, information about primitives that would have been rasterized is fed back to the application using OpenGL.

The glFeedbackBuffer function has three arguments:

•	buffer is a pointer to an array of floating-point values into which feedback information is placed.

•	size indicates the size of the array.

•	type is a symbolic constant describing the information that is fed back for each vertex.

You must issue glFeedbackBuffer before feedback mode is enabled (by calling glRenderMode with argument GL_FEEDBACK). Setting GL_FEEDBACK without establishing the feedback buffer, or calling glFeedbackBuffer while OpenGL is in feedback mode, is an error.

Take OpenGL out of feedback mode by calling glRenderMode with a parameter value other than GL_FEEDBACK. When you do this while OpenGL is in feedback mode, glRenderMode returns the number of entries placed in the feedback array. The returned value never exceeds size. If the feedback data required more room than was available in buffer, glRenderMode returns a negative value.

While in feedback mode, each primitive that would be rasterized generates a block of values that get copied into the feedback array. If doing so would cause the number of entries to exceed the maximum, the block is partially written so as to fill the array (if there is any room left at all), and an overflow flag is set. Each block begins with a code indicating the primitive type, followed by values that describe the primitive’s vertices and associated data. Entries are also written for bitmaps and pixel rectangles. Feedback occurs after polygon culling and glPolygonMode interpretation of polygons has taken place, so polygons that are culled are not returned in the feedback buffer. It can also occur after polygons with more than three edges are broken up into triangles, if the OpenGL implementation renders polygons by performing this decomposition.

You can insert a marker into the feedback buffer with glPassThrough.

The following is the grammar for the blocks of values written into the feedback buffer. Each primitive is indicated with a unique identifying value followed by some number of vertices. Polygon entries include an integer value indicating how many vertices follow. A vertex is fed back as some number of floating-point values, as determined by type. Colors are fed back as four values in RGBA mode and one value in color-index mode.

feedbackList ← feedbackItem feedbackList | feedbackItem

feedbackItem ← point | lineSegment | polygon | bitmap | pixelRectangle | passThru

point ← GL_POINT_TOKEN vertex

lineSegment ← GL_LINE_TOKEN vertex vertex | GL_LINE_RESET_TOKEN vertex vertex

polygon ← GL_POLYGON_TOKEN n polySpec

polySpec ← polySpec vertex | vertex vertex vertex

bitmap ← GL_BITMAP_TOKEN vertex

pixelRectangle ← GL_DRAW_PIXEL_TOKEN vertex | GL_COPY_PIXEL_TOKEN vertex

passThru ← GL_PASS_THROUGH_TOKEN value

vertex ← 2d | 3d | 3dColor | 3dColorTexture | 4dColorTexture

2d ← value value

3d ← value value value

3dColor ← value value value color

3dColorTexture ← value value value color tex

4dColorTexture ← value value value value color tex

color ← rgba | index

rgba ← value value value value

index ← value

tex ← value value value value

The value parameter is a floating-point number, and n is a floating-point integer giving the number of vertices in the polygon. The following are symbolic floating-point constants: GL_POINT_TOKEN, GL_LINE_TOKEN, GL_LINE_RESET_TOKEN, GL_POLYGON_TOKEN, GL_BITMAP_TOKEN, GL_DRAW_PIXEL_TOKEN, GL_COPY_PIXEL_TOKEN, and GL_PASS_THROUGH_TOKEN. GL_LINE_RESET_TOKEN is returned whenever the line stipple pattern is reset. The data returned as a vertex depends on the feedback type.

The following table gives the correspondence between type and the number of values per vertex; k is 1 in color-index mode and 4 in RGBA mode.

Type	Coordinates	Color	Texture	Total Number of Values
GL_2D	x, y			2
GL_3D	x, y, z			3
GL_3D_COLOR	x, y, z	k		3 + k
GL_3D_COLOR_TEXTURE	x, y, z,	k	4	7 + k
GL_4D_COLOR_TEXTURE	x, y, z, w	k	4	8 + k
Feedback vertex coordinates are in window coordinates, except w, which is in clip coordinates. Feedback colors are lighted, if lighting is enabled. Feedback texture coordinates are generated, if texture coordinate generation is enabled. They are always transformed by the texture matrix.

The glFeedbackBuffer function, when used in a display list, is not compiled into the display list but rather is executed immediately.

The following function retrieves information related to glFeedbackBuffer:

glGet with argument GL_RENDER_MODE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	type was not an accepted value.
GL_INVALID_VALUE	size was negative.
GL_INVALID_OPERATION	glFeedbackBuffer was called while the render mode was GL_FEEDBACK, or glRenderMode was called with argument GL_FEEDBACK before glFeedbackBuffer was called at least once.
GL_INVALID_OPERATION	glFeedbackBuffer was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glGet, glLineStipple, glPassThrough, glPolygonMode, glRenderMode, glSelectBuffer


glFinish [New - Windows 95, OEM Service Release 2]
glFinish

[New - Windows 95, OEM Service Release 2]

The glFinish function blocks until all OpenGL execution is complete.

void glFinish(

void
);
Remarks

The glFinish function does not return until the effects of all previously called OpenGL functions are complete. Such effects include all changes to the OpenGL state, all changes to the connection state, and all changes to the frame buffer contents.

The glFinish function requires a round trip to the server.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glFinish was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glFlush


glFlush [New - Windows 95, OEM Service Release 2]
glFlush

[New - Windows 95, OEM Service Release 2]

The glFlush function forces execution of OpenGL functions in finite time.

void glFlush(

void
);
Remarks

Different OpenGL implementations buffer commands in several different locations, including network buffers and the graphics accelerator itself. The glFlush function empties all these buffers, causing all issued commands to be executed as quickly as they are accepted by the actual rendering engine. Though this execution may not be completed in any particular time period, it does complete in finite time.

Because any OpenGL program might be executed over a network, or on an accelerator that buffers commands, be sure to call glFlush in all programs whenever they require that all of their previously issued commands have been completed. For example, call glFlush before waiting for user input that depends on the generated image.

The glFlush function can return at any time. It does not wait until the execution of all previously issued OpenGL functions is complete.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glFlush was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glFinish


glFog [New - Windows 95, OEM Service Release 2]
glFogf, glFogi, glFogfv, glFogiv

[New - Windows 95, OEM Service Release 2]

These functions specify fog parameters.

void glFogf(

GLenum pname,
GLfloat param
);
void glFogi(

GLenum pname,
GLint param
);
void glFogfv(

GLenum pname,
const GLfloat * params
);
void glFogiv(

GLenum pname,
const GLint * params
);
Parameters

pname

In glFogf and glFogi, specifies a single-valued fog parameter.

In glFogfv and glFogiv, specifies a fog parameter.

The glFogf, glFogi, glFogfv, and glFogiv functions accept the following values:

GL_FOG_MODE

The params parameter is a single integer or floating-point value that specifies the equation to be used to compute the fog blend factor, f. Three symbolic constants are accepted: GL_LINEAR, GL_EXP, and GL_EXP2. The equations corresponding to these symbolic constants are defined in the following Remarks section. The default fog mode is GL_EXP.

GL_FOG_DENSITY

The params parameter is a single integer or floating-point value that specifies density, the fog density used in both exponential fog equations. Only nonnegative densities are accepted. The default fog density is 1.0.

GL_FOG_START

The params parameter is a single integer or floating-point value that specifies start, the near distance used in the linear fog equation. The default near distance is 0.0.

GL_FOG_END

The params parameter is a single integer or floating-point value that specifies end, the far distance used in the linear fog equation. The default far distance is 1.0.

GL_FOG_INDEX

The params parameter is a single integer or floating-point value that specifies i (f) , the fog color index. The default fog index is 0.0.

The glFogfv and glFogiv functions also accept GL_FOG_COLOR:

GL_FOG_COLOR

The params parameter contains four integer or floating-point values that specify C (f) , the fog color. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to −1.0. Floating-point values are mapped directly. After conversion, all color components are clamped to the range [0,1]. The default fog color is (0,0,0,0).

param

In glFogf and glFogi, specifies the value that pname will be set to.

params

In glFogfv and glFogiv, specifies the value or values to be assigned to pname. GL_FOG_COLOR requires an array of four values. All other parameters accept an array containing only a single value.

Remarks

You enable and disable fog with glEnable and glDisable, using the argument GL_FOG. While enabled, fog affects rasterized geometry, bitmaps, and pixel blocks, but not buffer-clear operations.

The glFog function assigns the value or values in params to the fog parameter specified by pname.

Fog blends a fog color with each rasterized pixel fragment’s posttexturing color using a blending factor f. Factor f is computed in one of three ways, depending on the fog mode. Let z be the distance in eye coordinates from the origin to the fragment being fogged. The equation for GL_LINEAR fog is:

The equation for GL_EXP fog is:

The equation for GL_EXP2 fog is:

Regardless of the fog mode, f is clamped to the range [0,1] after it is computed. Then, if OpenGL is in RGBA color mode, the fragment’s color C (r)  is replaced by

In color-index mode, the fragment’s color index i (r)  is replaced by

The following functions retrieve information related to the glFog functions:

glGet with argument GL_FOG_COLOR

glGet with argument GL_FOG_INDEX

glGet with argument GL_FOG_DENSITY

glGet with argument GL_FOG_START

glGet with argument GL_FOG_END

glGet with argument GL_FOG_MODE

glIsEnabled with argument GL_FOG

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	pname was not an accepted value.
GL_INVALID_OPERATION	glFinish was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glDisable, glEnable, glEnd, glGet, glIsEnabled


glFrontFace [New - Windows 95, OEM Service Release 2]
glFrontFace

[New - Windows 95, OEM Service Release 2]

The glFrontFace function defines front- and back-facing polygons.

void glFrontFace(

GLenum mode
);
Parameters

mode

The orientation of front-facing polygons. GL_CW and GL_CCW are accepted. The default value is GL_CCW.

Remarks

In a scene composed entirely of opaque closed surfaces, back-facing polygons are never visible. Eliminating these invisible polygons has the obvious benefit of speeding up the rendering of the image. You enable and disable elimination of back-facing polygons with glEnable and glDisable using argument GL_CULL_FACE.

The projection of a polygon to window coordinates is said to have clockwise winding if an imaginary object following the path from its first vertex, its second vertex, and so on, to its last vertex, and finally back to its first vertex, moves in a clockwise direction about the interior of the polygon. The polygon’s winding is said to be counterclockwise if the imaginary object following the same path moves in a counterclockwise direction about the interior of the polygon. The glFrontFace function specifies whether polygons with clockwise winding in window coordinates, or counterclockwise winding in window coordinates, are taken to be front-facing. Passing GL_CCW to mode selects counterclockwise polygons as front-facing; GL_CW selects clockwise polygons as front-facing. By default, counterclockwise polygons are taken to be front-facing.

The following function retrieves information about glFrontface:

glGet with argument GL_FRONT_FACE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	mode was not an accepted value.
GL_INVALID_OPERATION	glFrontFace was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glCullFace, glDisable, glEnable, glEnd, glGet, glLightModel


glFrustum [New - Windows 95, OEM Service Release 2]
glFrustum

[New - Windows 95, OEM Service Release 2]

The glFrustum function multiplies the current matrix by a perspective matrix.

void glFrustum(

GLdouble left,
GLdouble right,
GLdouble bottom,
GLdouble top,
GLdouble znear,
GLdouble zfar
);
Parameters

left, right

The coordinates for the left and right vertical clipping planes.

bottom, top

The coordinates for the bottom and top horizontal clipping planes.

znear, zfar

The distances to the near and far depth clipping planes. Both distances must be positive.

Remarks

The glFrustum function describes a perspective matrix that produces a perspective projection. The (left, bottom, znear) and (right, top, znear) parameters specify the points on the near clipping plane that are mapped to the lower-left and upper-right corners of the window, respectively, assuming that the eye is located at (0, 0, 0). The zfar parameter specifies the location of the far clipping plane. Both znear and zfar must be positive. The corresponding matrix is:

The glFrustum function multiplies the current matrix by this matrix, with the result replacing the current matrix. That is, if M is the current matrix and F is the frustum perspective matrix, then glFrustum replaces M with M • F.

Use glPushMatrix and glPopMatrix to save and restore the current matrix stack.

Depth-buffer precision is affected by the values specified for znear and zfar. The greater the ratio of zfar to znear is, the less effective the depth buffer will be at distinguishing between surfaces that are near each other. If

roughly log (2)  r bits of depth buffer precision are lost. Because r approaches infinity as znear approaches zero, you should never set znear to zero.

The following functions retrieve information about glFrustum:

glGet with argument GL_MATRIX_MODE

glGet with argument GL_MODELVIEW_MATRIX

glGet with argument GL_PROJECTION_MATRIX

glGet with argument GL_TEXTURE_MATRIX

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	znear or zfar was not positive.
GL_INVALID_OPERATION	glFrustum was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glGet, glMatrixMode, glMultMatrix, glOrtho, glPopMatrix, glPushMatrix, glViewport


glGenLists [New - Windows 95, OEM Service Release 2]
glGenLists

[New - Windows 95, OEM Service Release 2]

The glGenLists function generates a contiguous set of empty display lists.

GLuint glGenLists(

GLsizei range
);
Parameters

range

The number of contiguous empty display lists to be generated.

Remarks

The glGenLists function has one argument, range. It returns an integer n such that range contiguous empty display lists, named n, n+1, . . ., n+range − 1, are created. If range is zero, if there is no group of range contiguous names available, or if any error is generated, then no display lists are generated and zero is returned.

The following function retrieves information related to glGenLists:

glIsList

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	range is negative.
GL_INVALID_OPERATION	glGenLists was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glCallList, glCallLists, glDeleteLists, glEnd, glIsList, glNewList


glGenTextures [New - Windows 95, OEM Service Release 2]
glGenTextures

[New - Windows 95, OEM Service Release 2]

The glGenTextures function generates texture names.

void glGenTextures(

GLsizei n,
GLuint * textures
);
Parameters

n

The number of texture names to be generated.

textures

A pointer to the first element of an array in which the generated texture names are stored.

Remarks

The glGenTextures function returns n texture names in the textures parameter. The texture names are not necessarily a contiguous set of integers, however, none of the returned names can have been in use immediately prior to calling the glGenTextures function. The generated textures assume the dimensionality of the texture target to which they are first bound with the glBindTexture function. Texture names returned by glGenTextures are not returned by subsequent calls to glGenTextures unless they are first deleted by calling glDeleteTextures.

You cannot include glGenTextures in display lists.

Note  The glGenTextures function is only available in OpenGL version 1.1 or later.

The following function retrieves information related to glGenTextures:

glIsTexture

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	n was a negative value.
GL_INVALID_OPERATION	glGenTextures was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glBindTexture, glDeleteTextures, glEnd, glGet, glGetTexParameter, glIsTexture, glTexImage1D, glTexImage2D, glTexParameter


glGetBooleanv, glGetDoublev, glGetFloatv, glGetIntegerv [New - Windows 95, OEM Service Release 2]
glGetBooleanv, glGetDoublev, glGetFloatv, glGetIntegerv

[New - Windows 95, OEM Service Release 2]

These functions return the value or values of a selected parameter.

void glGetBooleanv(

GLenum pname,
GLboolean * params
);
void glGetDoublev(

GLenum pname,
GLdouble * params
);
void glGetFloatv(

GLenum pname,
GLfloat * params
);
void glGetIntegerv(

GLenum pname,
GLint * params
);
Parameters

pname

The parameter value to be returned. The following symbolic constants are accepted:

GL_ACCUM_ALPHA_BITS

The params parameter returns one value: the number of alpha bitplanes in the accumulation buffer.

GL_ACCUM_BLUE_BITS

The params parameter returns one value: the number of blue bitplanes in the accumulation buffer.

GL_ACCUM_CLEAR_VALUE

The params parameter returns four values: the red, green, blue, and alpha values used to clear the accumulation buffer. Integer values, if requested, are linearly mapped from the internal floating-point representation such that 1.0 returns the most positive representable integer value, and −1.0 returns the most negative representable integer value. See glClearAccum.

GL_ACCUM_GREEN_BITS

The params parameter returns one value: the number of green bitplanes in the accumulation buffer.

GL_ACCUM_RED_BITS

The params parameter returns one value: the number of red bitplanes in the accumulation buffer.

GL_ALPHA_BIAS

The params parameter returns one value: the alpha bias factor used during pixel transfers. See glPixelTransfer.

GL_ALPHA_BITS

The params parameter returns one value: the number of alpha bitplanes in each color buffer.

GL_ALPHA_SCALE

The params parameter returns one value: the alpha scale factor used during pixel transfers. See glPixelTransfer.

GL_ALPHA_TEST

The params parameter returns a single Boolean value indicating whether alpha testing of fragments is enabled. See glAlphaFunc.

GL_ALPHA_TEST_FUNC

The params parameter returns one value: the symbolic name of the alpha test function. See glAlphaFunc.

GL_ALPHA_TEST_REF

The params parameter returns one value: the reference value for the alpha test. See glAlphaFunc. An integer value, if requested, is linearly mapped from the internal floating-point representation such that 1.0 returns the most positive representable integer value, and −1.0 returns the most negative representable integer value.

GL_ATTRIB_STACK_DEPTH

The params parameter returns one value: the depth of the attribute stack. If the stack is empty, zero is returned. See glPushAttrib.

GL_AUTO_NORMAL

The params parameter returns a single Boolean value indicating whether 2-D map evaluation automatically generates surface normals. See glMap2.

GL_AUX_BUFFERS

The params parameter returns one value: the number of auxiliary color buffers.

GL_BLEND

The params parameter returns a single Boolean value indicating whether blending is enabled. See glBlendFunc.

GL_BLEND_DST

The params parameter returns one value: the symbolic constant identifying the destination blend function. See glBlendFunc.

GL_BLEND_SRC

The params parameter returns one value: the symbolic constant identifying the source blend function. See glBlendFunc.

GL_BLUE_BIAS

The params parameter returns one value: the blue bias factor used during pixel transfers. See glPixelTransfer.

GL_BLUE_BITS

The params parameter returns one value: the number of blue bitplanes in each color buffer.

GL_BLUE_SCALE

The params parameter returns one value: the blue scale factor used during pixel transfers. See glPixelTransfer.

GL_CLIP_PLANEi

The params parameter returns a single Boolean value indicating whether the specified clipping plane is enabled. See glClipPlane.

GL_COLOR_CLEAR_VALUE

The params parameter returns four values: the red, green, blue, and alpha values used to clear the color buffers. Integer values, if requested, are linearly mapped from the internal floating-point representation such that 1.0 returns the most positive representable integer value, and −1.0 returns the most negative representable integer value. See glClearColor.

GL_COLOR_MATERIAL

The params parameter returns a single Boolean value indicating whether one or more material parameters are tracking the current color. See glColorMaterial.

GL_COLOR_MATERIAL_FACE

The params parameter returns one value: a symbolic constant indicating which materials have a parameter that is tracking the current color. See glColorMaterial.

GL_COLOR_MATERIAL_PARAMETER

The params parameter returns one value: a symbolic constant indicating which material parameters are tracking the current color. See glColorMaterial.

GL_COLOR_WRITEMASK

The params parameter returns four Boolean values: the red, green, blue, and alpha write enables for the color buffers. See glColorMask.

GL_CULL_FACE

The params parameter returns a single Boolean value indicating whether polygon culling is enabled. See glCullFace.

GL_CULL_FACE_MODE

The params parameter returns one value: a symbolic constant indicating which polygon faces are to be culled. See glCullFace.

GL_CURRENT_COLOR

The params parameter returns four values: the red, green, blue, and alpha values of the current color. Integer values, if requested, are linearly mapped from the internal floating-point representation such that 1.0 returns the most positive representable integer value, and −1.0 returns the most negative representable integer value. See glColor.

GL_CURRENT_INDEX

The params parameter returns one value: the current color index. See glIndex.

GL_CURRENT_NORMAL

The params parameter returns three values: the x, y, and z values of the current normal. Integer values, if requested, are linearly mapped from the internal floating-point representation such that 1.0 returns the most positive representable integer value, and −1.0 returns the most negative representable integer value. See glNormal.

GL_CURRENT_RASTER_COLOR

The params parameter returns four values: the red, green, blue, and alpha values of the current raster position. Integer values, if requested, are linearly mapped from the internal floating-point representation such that 1.0 returns the most positive representable integer value, and −1.0 returns the most negative representable integer value. See glRasterPos.

GL_CURRENT_RASTER_DISTANCE

The params parameter returns one value: the distance from the eye to the current raster position. See glRasterPos.

GL_CURRENT_RASTER_INDEX

The params parameter returns one value: the color index of the current raster position. See glRasterPos.

GL_CURRENT_RASTER_POSITION

The params parameter returns four values: the x, y, z, and w components of the current raster position. The x, y, and z components are in window coordinates, and w is in clip coordinates. See glRasterPos.

GL_CURRENT_RASTER_TEXTURE_COORDS

The params parameter returns four values: the s, t, r, and q current raster texture coordinates. See glRasterPos and glTexCoord.

GL_CURRENT_RASTER_POSITION_VALID

The params parameter returns a single Boolean value indicating whether the current raster position is valid. See glRasterPos.

GL_CURRENT_TEXTURE_COORDS

The params parameter returns four values: the s, t, r, and q current texture coordinates. See glTexCoord.

GL_DEPTH_BIAS

The params parameter returns one value: the depth bias factor used during pixel transfers. See glPixelTransfer.

GL_DEPTH_BITS

The params parameter returns one value: the number of bitplanes in the depth buffer.

GL_DEPTH_CLEAR_VALUE

The params parameter returns one value: the value that is used to clear the depth buffer. Integer values, if requested, are linearly mapped from the internal floating-point representation such that 1.0 returns the most positive representable integer value, and −1.0 returns the most negative representable integer value. See glClearDepth.

GL_DEPTH_FUNC

The params parameter returns one value: the symbolic constant that indicates the depth comparison function. See glDepthFunc.

GL_DEPTH_RANGE

The params parameter returns two values: the near and far mapping limits for the depth buffer. Integer values, if requested, are linearly mapped from the internal floating-point representation such that 1.0 returns the most positive representable integer value, and −1.0 returns the most negative representable integer value. See glDepthRange.

GL_DEPTH_SCALE

The params parameter returns one value: the depth scale factor used during pixel transfers. See glPixelTransfer.

GL_DEPTH_TEST

The params parameter returns a single Boolean value indicating whether depth testing of fragments is enabled. See glDepthFunc and glDepthRange.

GL_DEPTH_WRITEMASK

The params parameter returns a single Boolean value indicating if the depth buffer is enabled for writing. See glDepthMask.

GL_DITHER

The params parameter returns a single Boolean value indicating whether dithering of fragment colors and indexes is enabled.

GL_DOUBLEBUFFER

The params parameter returns a single Boolean value indicating whether double buffering is supported.

GL_DRAW_BUFFER

The params parameter returns one value: a symbolic constant indicating which buffers are being drawn to. See glDrawBuffer.

GL_EDGE_FLAG

The params parameter returns a single Boolean value indicating whether the current edge flag is true or false. See glEdgeFlag.

GL_FOG

The params parameter returns a single Boolean value indicating whether fogging is enabled. See glFog.

GL_FOG_COLOR

The params parameter returns four values: the red, green, blue, and alpha components of the fog color. Integer values, if requested, are linearly mapped from the internal floating-point representation such that 1.0 returns the most positive representable integer value, and −1.0 returns the most negative representable integer value. See glFog.

GL_FOG_DENSITY

The params parameter returns one value: the fog density parameter. See glFog.

GL_FOG_END

The params parameter returns one value: the end factor for the linear fog equation. See glFog.

GL_FOG_HINT

The params parameter returns one value: a symbolic constant indicating the mode of the fog hint. See glHint.

GL_FOG_INDEX

The params parameter returns one value: the fog color index. See glFog.

GL_FOG_MODE

The params parameter returns one value: a symbolic constant indicating which fog equation is selected. See glFog.

GL_FOG_START

The params parameter returns one value: the start factor for the linear fog equation. See glFog.

GL_FRONT_FACE

The params parameter returns one value: a symbolic constant indicating whether clockwise or counterclockwise polygon winding is treated as front-facing. See glFrontFace.

GL_GREEN_BIAS

The params parameter returns one value: the green bias factor used during pixel transfers.

GL_GREEN_BITS

The params parameter returns one value: the number of green bitplanes in each color buffer.

GL_GREEN_SCALE

The params parameter returns one value: the green scale factor used during pixel transfers. See glPixelTransfer.

GL_INDEX_BITS

The params parameter returns one value: the number of bitplanes in each color-index buffer.

GL_INDEX_CLEAR_VALUE

The params parameter returns one value: the color index used to clear the color-index buffers. See glClearIndex.

GL_INDEX_MODE

The params parameter returns a single Boolean value indicating whether OpenGL is in color-index mode (TRUE) or RGBA mode (FALSE).

GL_INDEX_OFFSET

The params parameter returns one value: the offset added to color and stencil indexes during pixel transfers. See glPixelTransfer.

GL_INDEX_SHIFT

The params parameter returns one value: the amount that color and stencil indexes are shifted during pixel transfers. See glPixelTransfer.

GL_INDEX_WRITEMASK

The params parameter returns one value: a mask indicating which bitplanes of each color-index buffer can be written. See glIndexMask.

GL_LIGHTi

The params parameter returns a single Boolean value indicating whether the specified light is enabled. See glLight and glLightModel.

GL_LIGHTING

The params parameter returns a single Boolean value indicating whether lighting is enabled. See glLightModel.

GL_LIGHT_MODEL_AMBIENT

The params parameter returns four values: the red, green, blue, and alpha components of the ambient intensity of the entire scene. Integer values, if requested, are linearly mapped from the internal floating-point representation such that 1.0 returns the most positive representable integer value, and −1.0 returns the most negative representable integer value. See glLightModel.

GL_LIGHT_MODEL_LOCAL_VIEWER

The params parameter returns a single Boolean value indicating whether specular reflection calculations treat the viewer as being local to the scene. See glLightModel.

GL_LIGHT_MODEL_TWO_SIDE

The params parameter returns a single Boolean value indicating whether separate materials are used to compute lighting for front- and back-facing polygons. See glLightModel.

GL_LINE_SMOOTH

The params parameter returns a single Boolean value indicating whether antialiasing of lines is enabled. See glLineWidth.

GL_LINE_SMOOTH_HINT

The params parameter returns one value: a symbolic constant indicating the mode of the line antialiasing hint. See glHint.

GL_LINE_STIPPLE

The params parameter returns a single Boolean value indicating whether stippling of lines is enabled. See glLineStipple.

GL_LINE_STIPPLE_PATTERN

The params parameter returns one value: the 16-bit line stipple pattern. See glLineStipple.

GL_LINE_STIPPLE_REPEAT

The params parameter returns one value: the line stipple repeat factor. See glLineStipple.

GL_LINE_WIDTH

The params parameter returns one value: the line width as specified with glLineWidth.

GL_LINE_WIDTH_GRANULARITY

The params parameter returns one value: the width difference between adjacent supported widths for antialiased lines. See glLineWidth.

GL_LINE_WIDTH_RANGE

The params parameter returns two values: the smallest and largest supported widths for antialiased lines. See glLineWidth.

GL_LIST_BASE

The params parameter returns one value: the base offset added to all names in arrays presented to glCallLists. See glListBase.

GL_LIST_INDEX

The params parameter returns one value: the name of the display list currently under construction. Zero is returned if no display list is currently under construction. See glNewList.

GL_LIST_MODE

The params parameter returns one value: a symbolic constant indicating the construction mode of the display list currently being constructed. See glNewList.

GL_LOGIC_OP

The params parameter returns a single Boolean value indicating whether fragment indexes are merged into the frame buffer using a logical operation. See glLogicOp.

GL_LOGIC_OP_MODE

The params parameter returns one value: a symbolic constant indicating the selected logic operational mode. See glLogicOp.

GL_MAP1_COLOR_4

The params parameter returns a single Boolean value indicating whether 1-D evaluation generates colors. See glMap1.

GL_MAP1_GRID_DOMAIN

The params parameter returns two values: the endpoints of the 1-D maps grid domain. See glMapGrid.

GL_MAP1_GRID_SEGMENTS

The params parameter returns one value: the number of partitions in the 1-D maps grid domain. See glMapGrid.

GL_MAP1_INDEX

The params parameter returns a single Boolean value indicating whether 1-D evaluation generates color indexes. See glMap1.

GL_MAP1_NORMAL

The params parameter returns a single Boolean value indicating whether 1-D evaluation generates normals. See glMap1.

GL_MAP1_TEXTURE_COORD_1

The params parameter returns a single Boolean value indicating whether 1-D evaluation generates 1-D texture coordinates. See glMap1.

GL_MAP1_TEXTURE_COORD_2

The params parameter returns a single Boolean value indicating whether 1-D evaluation generates 2-D texture coordinates. See glMap1.

GL_MAP1_TEXTURE_COORD_3

The params parameter returns a single Boolean value indicating whether 1-D evaluation generates 3-D texture coordinates. See glMap1.

GL_MAP1_TEXTURE_COORD_4

The params parameter returns a single Boolean value indicating whether 1-D evaluation generates 4-D texture coordinates. See glMap1.

GL_MAP1_VERTEX_3

The params parameter returns a single Boolean value indicating whether 1-D evaluation generates 3-D vertex coordinates. See glMap1.

GL_MAP1_VERTEX_4

The params parameter returns a single Boolean value indicating whether 1-D evaluation generates 4-D vertex coordinates. See glMap1.

GL_MAP2_COLOR_4

The params parameter returns a single Boolean value indicating whether 2-D evaluation generates colors. See glMap2.

GL_MAP2_GRID_DOMAIN

The params parameter returns four values: the endpoints of the 2-D maps i and j grid domains. See glMapGrid.

GL_MAP2_GRID_SEGMENTS

The params parameter returns two values: the number of partitions in the 2-D maps i and j grid domains. See glMapGrid.

GL_MAP2_INDEX

The params parameter returns a single Boolean value indicating whether 2-D evaluation generates color indexes. See glMap2.

GL_MAP2_NORMAL

The params parameter returns a single Boolean value indicating whether 2-D evaluation generates normals. See glMap2.

GL_MAP2_TEXTURE_COORD_1

The params parameter returns a single Boolean value indicating whether 2-D evaluation generates 1-D texture coordinates. See glMap2.

GL_MAP2_TEXTURE_COORD_2

The params parameter returns a single Boolean value indicating whether 2-D evaluation generates 2-D texture coordinates. See glMap2.

GL_MAP2_TEXTURE_COORD_3

The params parameter returns a single Boolean value indicating whether 2-D evaluation generates 3-D texture coordinates. See glMap2.

GL_MAP2_TEXTURE_COORD_4

The params parameter returns a single Boolean value indicating whether 2-D evaluation generates 4-D texture coordinates. See glMap2.

GL_MAP2_VERTEX_3

The params parameter returns a single Boolean value indicating whether 2-D evaluation generates 3-D vertex coordinates. See glMap2.

GL_MAP2_VERTEX_4

The params parameter returns a single Boolean value indicating whether 2-D evaluation generates 4-D vertex coordinates. See glMap2.

GL_MAP_COLOR

The params parameter returns a single Boolean value indicating whether colors and color indexes are to be replaced by table lookup during pixel transfers. See glPixelTransfer.

GL_MAP_STENCIL

The params parameter returns a single Boolean value indicating whether stencil indexes are to be replaced by table lookup during pixel transfers. See glPixelTransfer.

GL_MATRIX_MODE

The params parameter returns one value: a symbolic constant indicating which matrix stack is currently the target of all matrix operations. See glMatrixMode.

GL_MAX_ATTRIB_STACK_DEPTH

The params parameter returns one value: the maximum supported depth of the attribute stack. See glPushAttrib.

GL_MAX_CLIP_PLANES

The params parameter returns one value: the maximum number of application-defined clipping planes. See glClipPlane.

GL_MAX_EVAL_ORDER

The params parameter returns one value: the maximum equation order supported by 1-D and 2-D evaluators. See glMap1 and glMap2.

GL_MAX_LIGHTS

The params parameter returns one value: the maximum number of lights. See glLight.

GL_MAX_LIST_NESTING

The params parameter returns one value: the maximum recursion depth allowed during display-list traversal. See glCallList.

GL_MAX_MODELVIEW_STACK_DEPTH

The params parameter returns one value: the maximum supported depth of the modelview matrix stack. See glPushMatrix.

GL_MAX_NAME_STACK_DEPTH

The params parameter returns one value: the maximum supported depth of the selection name stack. See glPushName.

GL_MAX_PIXEL_MAP_TABLE

The params parameter returns one value: the maximum supported size of a glPixelMap lookup table. See glPixelMap.

GL_MAX_PROJECTION_STACK_DEPTH

The params parameter returns one value: the maximum supported depth of the projection matrix stack. See glPushMatrix.

GL_MAX_TEXTURE_SIZE

The params parameter returns one value: the maximum width or height of any texture image (without borders). See glTexImage1D and glTexImage2D.

GL_MAX_TEXTURE_STACK_DEPTH

The params parameter returns one value: the maximum supported depth of the texture matrix stack. See glPushMatrix.

GL_MAX_VIEWPORT_DIMS

The params parameter returns two values: the maximum supported width and height of the viewport. See glViewport.

GL_MODELVIEW_MATRIX

The params parameter returns 16 values: the modelview matrix on the top of the modelview matrix stack. See glPushMatrix.

GL_MODELVIEW_STACK_DEPTH

The params parameter returns one value: the number of matrices on the modelview matrix stack. See glPushMatrix.

GL_NAME_STACK_DEPTH

The params parameter returns one value: the number of names on the selection name stack. See glPushMatrix.

GL_NORMALIZE

The params parameter returns a single Boolean value indicating whether normals are automatically scaled to unit length after they have been transformed to eye coordinates. See glNormal.

GL_PACK_ALIGNMENT

The params parameter returns one value: the byte alignment used for writing pixel data to memory. See glPixelStore.

GL_PACK_LSB_FIRST

The params parameter returns a single Boolean value indicating whether single-bit pixels being written to memory are written first to the least significant bit of each unsigned byte. See glPixelStore.

GL_PACK_ROW_LENGTH

The params parameter returns one value: the row length used for writing pixel data to memory. See glPixelStore.

GL_PACK_SKIP_PIXELS

The params parameter returns one value: the number of pixel locations skipped before the first pixel is written into memory. See glPixelStore.

GL_PACK_SKIP_ROWS

The params parameter returns one value: the number of rows of pixel locations skipped before the first pixel is written into memory. See glPixelStore.

GL_PACK_SWAP_BYTES

The params parameter returns a single Boolean value indicating whether the bytes of 2-byte and 4-byte pixel indexes and components are swapped before being written to memory. See glPixelStore.

GL_PERSPECTIVE_CORRECTION_HINT

The params parameter returns one value: a symbolic constant indicating the mode of the perspective correction hint. See glHint.

GL_PIXEL_MAP_A_TO_A_SIZE

The params parameter returns one value: the size of the alpha-to-alpha pixel-translation table. See glPixelMap.

GL_PIXEL_MAP_B_TO_B_SIZE

The params parameter returns one value: the size of the blue-to-blue pixel-translation table. See glPixelMap.

GL_PIXEL_MAP_G_TO_G_SIZE

The params parameter returns one value: the size of the green-to-green pixel-translation table. See glPixelMap.

GL_PIXEL_MAP_I_TO_A_SIZE

The params parameter returns one value: the size of the index-to-alpha pixel translation table. See glPixelMap.

GL_PIXEL_MAP_I_TO_B_SIZE

The params parameter returns one value: the size of the index-to-blue pixel translation table. See glPixelMap.

GL_PIXEL_MAP_I_TO_G_SIZE

The params parameter returns one value: the size of the index-to-green pixel-translation table. See glPixelMap.

GL_PIXEL_MAP_I_TO_I_SIZE

The params parameter returns one value: the size of the index-to-index pixel-translation table. See glPixelMap.

GL_PIXEL_MAP_I_TO_R_SIZE

The params parameter returns one value: the size of the index-to-red pixel-translation table. See glPixelMap.

GL_PIXEL_MAP_R_TO_R_SIZE

The params parameter returns one value: the size of the red-to-red pixel-translation table. See glPixelMap.

GL_PIXEL_MAP_S_TO_S_SIZE

The params parameter returns one value: the size of the stencil-to-stencil pixel translation table. See glPixelMap.

GL_POINT_SIZE

The params parameter returns one value: the point size as specified by glPointSize.

GL_POINT_SIZE_GRANULARITY

The params parameter returns one value: the size difference between adjacent supported sizes for antialiased points. See glPointSize.

GL_POINT_SIZE_RANGE

The params parameter returns two values: the smallest and largest supported sizes for antialiased points. See glPointSize.

GL_POINT_SMOOTH

The params parameter returns a single Boolean value indicating whether antialiasing of points is enabled. See glPointSize.

GL_POINT_SMOOTH_HINT

The params parameter returns one value: a symbolic constant indicating the mode of the point antialiasing hint. See glHint.

GL_POLYGON_MODE

The params parameter returns two values: symbolic constants indicating whether front-facing and back-facing polygons are rasterized as points, lines, or filled polygons. See glPolygonMode.

GL_POLYGON_SMOOTH

The params parameter returns a single Boolean value indicating whether antialiasing of polygons is enabled. See glPolygonMode.

GL_POLYGON_SMOOTH_HINT

The params parameter returns one value: a symbolic constant indicating the mode of the polygon antialiasing hint. See glHint.

GL_POLYGON_STIPPLE

The params parameter returns a single Boolean value indicating whether stippling of polygons is enabled. See glPolygonStipple.

GL_PROJECTION_MATRIX

The params parameter returns 16 values: the projection matrix on the top of the projection matrix stack. See glPushMatrix.

GL_PROJECTION_STACK_DEPTH

The params parameter returns one value: the number of matrices on the projection matrix stack. See glPushMatrix.

GL_READ_BUFFER

The params parameter returns one value: a symbolic constant indicating which color buffer is selected for reading. See glReadPixels and glAccum.

GL_RED_BIAS

The params parameter returns one value: the red bias factor used during pixel transfers. See glPixelTransfer.

GL_RED_BITS

The params parameter returns one value: the number of red bitplanes in each color buffer.

GL_RED_SCALE

The params parameter returns one value: the red scale factor used during pixel transfers. See glPixelTransfer.

GL_RENDER_MODE

The params parameter returns one value: a symbolic constant indicating whether OpenGL is in render, select, or feedback mode. See glRenderMode.

GL_RGBA_MODE

The params parameter returns a single Boolean value indicating whether OpenGL is in RGBA mode (TRUE) or color-index mode (FALSE). See glColor.

GL_SCISSOR_BOX

The params parameter returns four values: the x and y window coordinates of the scissor box, followed by its width and height. See glScissor.

GL_SCISSOR_TEST

The params parameter returns a single Boolean value indicating whether scissoring is enabled. See glScissor.

GL_SHADE_MODEL

The params parameter returns one value: a symbolic constant indicating whether the shading mode is flat or smooth. See glShadeModel.

GL_STENCIL_BITS

The params parameter returns one value: the number of bitplanes in the stencil buffer.

GL_STENCIL_CLEAR_VALUE

The params parameter returns one value: the index to which the stencil bitplanes are cleared. See glClearStencil.

GL_STENCIL_FAIL

The params parameter returns one value: a symbolic constant indicating what action is taken when the stencil test fails. See glStencilOp.

GL_STENCIL_FUNC

The params parameter returns one value: a symbolic constant indicating what function is used to compare the stencil reference value with the stencil buffer value. See glStencilFunc.

GL_STENCIL_PASS_DEPTH_FAIL

The params parameter returns one value: a symbolic constant indicating what action is taken when the stencil test passes, but the depth test fails. See glStencilOp.

GL_STENCIL_PASS_DEPTH_PASS

The params parameter returns one value: a symbolic constant indicating what action is taken when the stencil test passes and the depth test passes. See glStencilOp.

GL_STENCIL_REF

The params parameter returns one value: the reference value that is compared with the contents of the stencil buffer. See glStencilFunc.

GL_STENCIL_TEST

The params parameter returns a single Boolean value indicating whether stencil testing of fragments is enabled. See glStencilFunc and glStencilOp.

GL_STENCIL_VALUE_MASK

The params parameter returns one value: the mask that is used to mask both the stencil reference value and the stencil buffer value before they are compared. See glStencilFunc.

GL_STENCIL_WRITEMASK

The params parameter returns one value: the mask that controls writing of the stencil bitplanes. See glStencilMask.

GL_STEREO

The params parameter returns a single Boolean value indicating whether stereo buffers (left and right) are supported.

GL_SUBPIXEL_BITS

The params parameter returns one value: an estimate of the number of bits of subpixel resolution that are used to position rasterized geometry in window coordinates.

GL_TEXTURE_1D

The params parameter returns a single Boolean value indicating whether 1-D texture mapping is enabled. See glTexImage1D.

GL_TEXTURE_2D

The params parameter returns a single Boolean value indicating whether 2-D texture mapping is enabled. See glTexImage2D.

GL_TEXTURE_ENV_COLOR

The params parameter returns four values: the red, green, blue, and alpha values of the texture environment color. Integer values, if requested, are linearly mapped from the internal floating-point representation such that 1.0 returns the most positive representable integer value, and −1.0 returns the most negative representable integer value. See glTexEnv.

GL_TEXTURE_ENV_MODE

The params parameter returns one value: a symbolic constant indicating which texture environment function is currently selected. See glTexEnv.

GL_TEXTURE_GEN_S

The params parameter returns a single Boolean value indicating whether automatic generation of the S texture coordinate is enabled. See glTexGen.

GL_TEXTURE_GEN_T

The params parameter returns a single Boolean value indicating whether automatic generation of the T texture coordinate is enabled. See glTexGen.

GL_TEXTURE_GEN_R

The params parameter returns a single Boolean value indicating whether automatic generation of the R texture coordinate is enabled. See glTexGen.

GL_TEXTURE_GEN_Q

The params parameter returns a single Boolean value indicating whether automatic generation of the Q texture coordinate is enabled. See glTexGen.

GL_TEXTURE_MATRIX

The params parameter returns 16 values: the texture matrix on the top of the texture matrix stack. See glPushMatrix.

GL_TEXTURE_STACK_DEPTH

The params parameter returns one value: the number of matrices on the texture matrix stack. See glPushMatrix.

GL_UNPACK_ALIGNMENT

The params parameter returns one value: the byte alignment used for reading pixel data from memory. See glPixelStore.

GL_UNPACK_LSB_FIRST

The params parameter returns a single Boolean value indicating whether single-bit pixels being read from memory are read first from the least significant bit of each unsigned byte. See glPixelStore.

GL_UNPACK_ROW_LENGTH

The params parameter returns one value: the row length used for reading pixel data from memory. See glPixelStore.

GL_UNPACK_SKIP_PIXELS

The params parameter returns one value: the number of pixel locations skipped before the first pixel is read from memory. See glPixelStore.

GL_UNPACK_SKIP_ROWS

The params parameter returns one value: the number of rows of pixel locations skipped before the first pixel is read from memory. See glPixelStore.

GL_UNPACK_SWAP_BYTES

The params parameter returns a single Boolean value indicating whether the bytes of 2-byte and 4-byte pixel indexes and components are swapped after being read from memory. See glPixelStore.

GL_VIEWPORT

The params parameter returns four values: the x and y window coordinates of the viewport, followed by its width and height. See glViewport.

GL_ZOOM_X

The params parameter returns one value: the x pixel zoom factor. See glPixelZoom.

GL_ZOOM_Y

The params parameter returns one value: the y pixel zoom factor. See glPixelZoom.

params

Returns the value or values of the specified parameter.

Remarks

These four functions return values for simple state variables in OpenGL. The pname parameter is a symbolic constant indicating the state variable to be returned, and params is a pointer to an array of the indicated type in which to place the returned data.

Type conversion is performed if params has a different type from the state variable value being requested. If you call glGetBooleanv, a floating-point or integer value is converted to GL_FALSE if and only if it is zero. Otherwise, it is converted to GL_TRUE.

If you call glGetIntegerv, Boolean values are returned as GL_TRUE or GL_FALSE, and most floating-point values are rounded to the nearest integer value. Floating-point colors and normals, however, are returned with a linear mapping that maps 1.0 to the most positive representable integer value and −1.0 to the most negative representable integer value.

If you call glGetFloatv or glGetDoublev, Boolean values are returned as GL_TRUE or GL_FALSE, and integer values are converted to floating-point values.

You can query many of the Boolean parameters more easily with glIsEnabled.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	pname was not an accepted value.
GL_INVALID_OPERATION	glGet was called between a call to glBegin and the corresponding call to glEnd.
See Also

glAccum, glAlphaFunc, glBegin, glBlendFunc, glCallList, glClearAccum, glClearColor, glClearDepth, glClearIndex, glClearStencil, glClipPlane, glColor, glColorMask, glColorMaterial, glCullFace, glDepthFunc, glDepthMask, glDepthRange, glDrawBuffer, glEdgeFlag, glEnd, glFog, glFrontFace, glGetClipPlane, glGetError, glGetLight, glGetMap, glGetMaterial, glGetPixelMap, glGetPolygonStipple, glGetString, glGetTexEnv, glGetTexGen, glGetTexImage, glGetTexLevelParameter, glGetTexParameter, glHint, glIndex, glIndexMask, glIsEnabled, glLight, glLightModel, glLineStipple, glLineWidth, glListBase, glLogicOp, glMap1, glMap2, glMapGrid, glMatrixMode, glNewList, glNormal, glPixelMap, glPixelStore, glPixelTransfer, glPixelZoom, glPointSize, glPolygonMode, glPolygonStipple, glPushAttrib, glPushMatrix, glPushName, glRasterPos, glReadPixels, glScissor, glShadeModel, glStencilFunc, glStencilMask, glStencilOp, glTexCoord, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glViewport


glGetClipPlane [New - Windows 95, OEM Service Release 2]
glGetClipPlane

[New - Windows 95, OEM Service Release 2]

The glGetClipPlane function returns the coefficients of the specified clipping plane.

void glGetClipPlane(

GLenum plane,
GLdouble * equation
);
Parameters

plane

A clipping plane. The number of clipping planes depends on the implementation, but at least six clipping planes are supported. They are identified by symbolic names of the form GL_CLIP_PLANEi where 0 ≤ i < GL_MAX_CLIP_PLANES.

equation

Returns four double-precision values that are the coefficients of the plane equation of plane in eye coordinates.

Remarks

The glGetClipPlane function returns in equation the four coefficients of the plane equation for plane.

It is always the case that GL_CLIP_PLANEi = GL_CLIP_PLANE0 + i.

If an error is generated, no change is made to the contents of equation.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	plane was not an accepted value.
GL_INVALID_OPERATION	glGetClipPlane was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glClipPlane, glEnd


glGetColorTableEXT [New - Windows 95, OEM Service Release 2]
glGetColorTableEXT

[New - Windows 95, OEM Service Release 2]

The glGetColorTableEXT function gets the color table data of the current targeted texture palette.

void glGetColorTableEXT(

GLenum target,
GLenum format,
GLenum type,
const GLvoid * data
);
Parameters

target

The target texture that is to have its palette changed. Must be TEXTURE_1D or TEXTURE_2D.

format

The format of the pixel data. The following symbolic constants are accepted:

GL_RGBA

Each pixel is a group of four components in the following order: red, green, blue, alpha. The RGBA format is determined in this way:

1.	The glGetColorTableEXT function converts floating-point values directly to an internal format with unspecified precision. Signed integer values are mapped linearly to the internal format such that the most positive representable integer value maps to 1.0, and the most negative representable integer value maps to − 1.0. Unsigned integer data is mapped similarly: the largest integer value maps to 1.0, and zero maps to 0.0.

2.	The glGetColorTableEXT function multiplies the resulting color values by GL_c_SCALE and adds them to GL_c_BIAS, where c is RED, GREEN, BLUE, and ALPHA for the respective color components. The results are clamped to the range [0,1].

3.	If GL_MAP_COLOR is TRUE, glGetColorTableEXT scales each color component by the size of lookup table GL_PIXEL_MAP_c_TO_c, then replaces the component by the value that it references in that table; c is R, G, B, or A, respectively.

4.	The glGetColorTableEXT function converts the resulting RGBA colors to fragments by attaching the current raster position z-coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that

x (n)  = x (r)  + n mod width

y (n)  = y (r)  +  n/width

where (x (r) , y (r) ) is the current raster position.

5.	These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. The glGetColorTableEXT function applies texture mapping, fog, and all the fragment operations before writing the fragments to the frame buffer.

GL_RED

Each pixel is a single red component.

The glGetColorTableEXT function converts this component to the internal format in the same way that the red component of an RGBA pixel is, then converts it to an RGBA pixel with green and blue set to 0.0, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_GREEN

Each pixel is a single green component.

The glGetColorTableEXT function converts this component to the internal format in the same way that the green component of an RGBA pixel is, and then converts it to an RGBA pixel with red and blue set to 0.0, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_BLUE

Each pixel is a single blue component.

The glGetColorTableEXT function converts this component to the internal format in the same way that the blue component of an RGBA pixel is, and then converts it to an RGBA pixel with red and green set to 0.0, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_ALPHA

Each pixel is a single alpha component.

The glGetColorTableEXT function converts this component to the internal format in the same way that the alpha component of an RGBA pixel is, and then converts it to an RGBA pixel with red, green, and blue set to 0.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_RGB

Each pixel is a group of three components in this order: red, green, blue.

The glGetColorTableEXT function converts each component to the internal format in the same way that the red, green, and blue components of an RGBA pixel are. The color triple is converted to an RGBA pixel with alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

GL_BGR_EXT

Each pixel is a group of three components in this order: blue, green, red.

GL_BGR_EXT provides a format that matches the memory layout of Windows device-independent bitmaps (DIBs). Thus your applications can use the same data with Win32 function calls and OpenGL pixel function calls.

GL_BGRA_EXT

Each pixel is a group of four components in this order: blue, green, red, alpha.

GL_BGRA_EXT provides a format that matches the memory layout of Windows device-independent bitmaps (DIBs). Thus your applications can use the same data with Win32 function calls and OpenGL pixel function calls.

type

The data type for data. The following symbolic constants are accepted: GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, and GL_FLOAT.

The following table summarizes the meaning of the valid constants for the type parameter.

Constant	Meaning
GL_UNSIGNED_BYTE	Unsigned 8-bit integer
GL_BYTE	Signed 8-bit integer
GL_UNSIGNED_SHORT	Unsigned 16-bit integer
GL_SHORT	Signed 16-bit integer
GL_UNSIGNED_INT	Unsigned 32-bit integer
GL_INT	32-bit integer
GL_FLOAT	Single-precision floating-point value
data

Points to the location where returned color table information is to be stored. Each color table entry is stored as if it was a single pixel of a 1-D texture. Because all textures have a default palette, glGetColorTableEXT always returns palette information even if the texture data is not in a paletted format.

Remarks

The glGetColorTableEXT function gets the actual color table data specified by glColorTableEXT and glColorSubTableEXT.

Note  The glGetColorTableEXT function is an extension function that is not part of the standard OpenGL library but is part of the GL_EXT_paletted_texture extension. To check whether your implementation of OpenGL supports glGetColorTableEXT, call glGetString(GL_EXTENSIONS). If it returns GL_EXT_paletted_texture, glGetColorTableEXT is supported. To obtain the function address of an extension function, call wglGetProcAddress.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target, format, or type was not an accepted value.
GL_INVALID_OPERATION	glGetColorTableEXT was called between glBegin and glEnd pairs.
See Also

glColorSubTableEXT, glColorTableEXT, glGetColorTableParameterfvEXT, glGetColorTableParameterivEXT, wglGetProcAddress


glGetColorTableParameterfvEXT, glGetColorTableParameterivEXT [New - Windows 95, OEM Service Release 2]
glGetColorTableParameterfvEXT, glGetColorTableParameterivEXT

[New - Windows 95, OEM Service Release 2]

The glGetColorTableParameterfvEXT and glGetColorTableParameterivEXT functions get palette parameters from color tables.

void glGetColorTableParameterfvEXT(

GLenum target,
GLenum pname,
GLint * params
);
void glGetColorTableParameterivEXT(

GLenum target,
GLenum pname,
GLint * params
);
Parameters

target

The target texture of the palette for which you want parameter data. Must be TEXTURE_1D, TEXTURE_2D, PROXY_TEXTURE_1D, or PROXY_TEXTURE_2D.

pname

A symbolic constant for the type of palette parameter data pointed to by params.

The following table summarizes the meaning of the valid constants for the pname parameter.

Constant	Meaning
GL_COLOR_TABLE_FORMAT_EXT	Return the internal format specified by the most recent call to glColorTableEXT or the default value.
GL_COLOR_TABLE_WIDTH_EXT	Return the width of the current palette.
GL_COLOR_TABLE_RED_SIZE_EXT	Return the actual size used internally to store the red component of the palette data.
GL_COLOR_TABLE_GREEN_SIZE_EXT	Return the actual size used internally to store the green component of the palette data.
GL_COLOR_TABLE_BLUE_SIZE_EXT	Return the actual size used internally to store the blue component of the palette data.
GL_COLOR_TABLE_ALPHA_SIZE_EXT	Return the actual size used internally to store the alpha component of the palette data.
params

Points to the color table parameter data specified by the pname parameter.

Remarks

You use the glGetColorTableParameterivEXT and glGetColorTableParameterfvEXT functions to retrieve specific parameter data from color tables set with glColorTableEXT for targeted texture palettes. Also you can use these functions to determine the number of color table entries that glGetColorTableEXT returns.

When the target parameter is GL_PROXY_TEXTURE_1D or GL_PROXY_TEXTURE_2D, and the implementation does not support the values specified for either format or width, glColorTableEXT can fail to create the requested color table. In this case, the color table is empty and all parameters retrieved will be zero. You can determine whether OpenGL supports a particular color table format and size by calling glColorTableEXT with a proxy target, and then calling glGetColorTableParameterivEXT or glGetColorTableParameterfvEXT to determine whether the width parameter matches that set by glColorTableEXT. If the retrieved width is zero, the color table request by glColorTable failed. If the retrieved width is not zero, you can call glColorTable with the real target with TEXTURE_1D or TEXTURE_2D to set the color table.

Note  The glGetColorTableParameterivEXT and glGetColorTableParameterfvEXT functions are extension functions that are not part of the standard OpenGL library but are part of the GL_EXT_paletted_texture extension. To check whether your implementation of OpenGL supports glGetColorTableParameterivEXT and glGetColorTableParameterfvEXT, call glGetString(GL_EXTENSIONS). If it returns GL_EXT_paletted_texture, glGetColorTableParameterivEXT and glGetColorTableParameterfvEXT are supported. To obtain the function address of an extension function, call wglGetProcAddress.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target or pname was not an accepted value.
GL_INVALID_OPERATION	glGetColorTableParameterivEXT or glGetColorTableParameterfvEXT was called between glBegin and glEnd pairs.
See Also

glColorSubTableEXT, glColorTableEXT, glGetColorTableEXT, wglGetProcAddress


glGetError [New - Windows 95, OEM Service Release 2]
glGetError

[New - Windows 95, OEM Service Release 2]

The glGetError function returns error information.

GLenum glGetError(

void
);
Remarks

The glGetError function returns the value of the error flag. Each detectable error is assigned a numeric code and symbolic name. When an error occurs, the error flag is set to the appropriate error code value. No other errors are recorded until glGetError is called, the error code is returned, and the flag is reset to GL_NO_ERROR. If a call to glGetError returns GL_NO_ERROR, there has been no detectable error since the last call to glGetError, or since OpenGL was initialized.

To allow for distributed implementations, there may be several error flags. If any single error flag has recorded an error, the value of that flag is returned and that flag is reset to GL_NO_ERROR when glGetError is called. If more than one flag has recorded an error, glGetError returns and clears an arbitrary error flag value. If all error flags are to be reset, you should always call glGetError in a loop until it returns GL_NO_ERROR.

Initially, all error flags are set to GL_NO_ERROR.

The following are the currently defined errors:

GL_NO_ERROR

No error has been recorded. The value of this symbolic constant is guaranteed to be zero.

GL_INVALID_ENUM

An unacceptable value is specified for an enumerated argument. The offending function is ignored, having no side effect other than to set the error flag.

GL_INVALID_VALUE

A numeric argument is out of range. The offending function is ignored, having no side effect other than to set the error flag.

GL_INVALID_OPERATION

The specified operation is not allowed in the current state. The offending function is ignored, having no side effect other than to set the error flag.

GL_STACK_OVERFLOW

This function would cause a stack overflow. The offending function is ignored, having no side effect other than to set the error flag.

GL_STACK_UNDERFLOW

This function would cause a stack underflow. The offending function is ignored, having no side effect other than to set the error flag.

GL_OUT_OF_MEMORY

There is not enough memory left to execute the function. The state of OpenGL is undefined, except for the state of the error flags, after this error is recorded.

When an error flag is set, results of an OpenGL operation are undefined only if GL_OUT_OF_MEMORY has occurred. In all other cases, the function generating the error is ignored and has no effect on the OpenGL state or frame buffer contents.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glGetError was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd


glGetLight [New - Windows 95, OEM Service Release 2]
glGetLightfv, glGetLightiv

[New - Windows 95, OEM Service Release 2]

The glGetLightfv and glGetLightiv functions return light source parameter values.

void glGetLightfv(

GLenum light,
GLenum pname,
GLfloat * params
);
void glGetLightiv(

GLenum light,
GLenum pname,
GLint * params
);
Parameters

light

A light source. The number of possible lights depends on the implementation, but at least eight lights are supported. They are identified by symbolic names of the form GL_LIGHTi where 0 ≤ i < GL_MAX_LIGHTS.

pname

A light source parameter for light. The following symbolic names are accepted:

GL_AMBIENT

The params parameter returns four integer or floating-point values representing the ambient intensity of the light source. Integer values, when requested, are linearly mapped from the internal floating-point representation such that 1.0 maps to the most positive representable integer value, and −1.0 maps to the most negative representable integer value. If the internal value is outside the range [−1,1], the corresponding integer return value is undefined.

GL_DIFFUSE

The params parameter returns four integer or floating-point values representing the diffuse intensity of the light source. Integer values, when requested, are linearly mapped from the internal floating-point representation such that 1.0 maps to the most positive representable integer value, and −1.0 maps to the most negative representable integer value. If the internal value is outside the range [−1,1], the corresponding integer return value is undefined.

GL_SPECULAR

The params parameter returns four integer or floating-point values representing the specular intensity of the light source. Integer values, when requested, are linearly mapped from the internal floating-point representation such that 1.0 maps to the most positive representable integer value, and −1.0 maps to the most negative representable integer value. If the internal value is outside the range [−1,1], the corresponding integer return value is undefined.

GL_POSITION

The params parameter returns four integer or floating-point values representing the position of the light source. Integer values, when requested, are computed by rounding the internal floating-point values to the nearest integer value. The returned values are those maintained in eye coordinates. They will not be equal to the values specified using glLight, unless the modelview matrix was identified at the time glLight was called.

GL_SPOT_DIRECTION

The params parameter returns three integer or floating-point values representing the direction of the light source. Integer values, when requested, are computed by rounding the internal floating-point values to the nearest integer value. The returned values are those maintained in eye coordinates. They will not be equal to the values specified using glLight, unless the modelview matrix was identified at the time glLight was called. Although spot direction is normalized before being used in the lighting equation, the returned values are the transformed versions of the specified values prior to normalization.

GL_SPOT_EXPONENT

The params parameter returns a single integer or floating-point value representing the spot exponent of the light. An integer value, when requested, is computed by rounding the internal floating-point representation to the nearest integer.

GL_SPOT_CUTOFF

The params parameter returns a single integer or floating-point value representing the spot cutoff angle of the light. An integer value, when requested, is computed by rounding the internal floating-point representation to the nearest integer.

GL_CONSTANT_ATTENUATION

The params parameter returns a single integer or floating-point value representing the constant (not distance-related) attenuation of the light. An integer value, when requested, is computed by rounding the internal floating-point representation to the nearest integer.

GL_LINEAR_ATTENUATION

The params parameter returns a single integer or floating-point value representing the linear attenuation of the light. An integer value, when requested, is computed by rounding the internal floating-point representation to the nearest integer.

GL_QUADRATIC_ATTENUATION

The params parameter returns a single integer or floating-point value representing the quadratic attenuation of the light. An integer value, when requested, is computed by rounding the internal floating-point representation to the nearest integer.

params

Returns the requested data.

Remarks

The glGetLight function returns in params the value or values of a light source parameter. The light parameter names the light and is a symbolic name of the form GL_LIGHTi for 0 ≤ i < GL_MAX_LIGHTS, where GL_MAX_LIGHTS is an implementation-dependent constant that is greater than or equal to eight. The pname parameter specifies one of ten light source parameters, again by symbolic name.

It is always the case that GL_LIGHTi = GL_LIGHT0 + i.

If an error is generated, no change is made to the contents of params.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	light or pname was not an accepted value.
GL_INVALID_OPERATION	glGetLight was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glLight


glGetMap [New - Windows 95, OEM Service Release 2]
glGetMapdv, glGetMapfv, glGetMapiv

[New - Windows 95, OEM Service Release 2]

These functions return evaluator parameters.

void glGetMapdv(

GLenum target,
GLenum query,
GLdouble * v
);
void glGetMapfv(

GLenum target,
GLenum query,
GLfloat * v
);
void glGetMapiv(

GLenum target,
GLenum query,
GLint * v
);
Parameters

target

The symbolic name of a map. The following are accepted values: GL_MAP1_COLOR_4, GL_MAP1_INDEX, GL_MAP1_NORMAL, GL_MAP1_TEXTURE_COORD_1, GL_MAP1_TEXTURE_COORD_2, GL_MAP1_TEXTURE_COORD_3, GL_MAP1_TEXTURE_COORD_4, GL_MAP1_VERTEX_3, GL_MAP1_VERTEX_4, GL_MAP2_COLOR_4, GL_MAP2_INDEX, GL_MAP2_NORMAL, GL_MAP2_TEXTURE_COORD_1, GL_MAP2_TEXTURE_COORD_2, GL_MAP2_TEXTURE_COORD_3, GL_MAP2_TEXTURE_COORD_4, GL_MAP2_VERTEX_3, and GL_MAP2_VERTEX_4.

query

Specifies which parameter to return. The following symbolic names are accepted:

GL_COEFF

The v parameter returns the control points for the evaluator function. One-dimensional evaluators return order control points, and two-dimensional evaluators return uorderxvorder control points. Each control point consists of one, two, three, or four integer, single-precision floating-point, or double-precision floating-point values, depending on the type of the evaluator. Two-dimensional control points are returned in row-major order, incrementing the uorder index quickly, and the vorder index after each row. Integer values, when requested, are computed by rounding the internal floating-point values to the nearest integer values.

GL_ORDER

The v parameter returns the order of the evaluator function. One-dimensional evaluators return a single value, order. Two-dimensional evaluators return two values, uorder and vorder.

GL_DOMAIN

The v parameter returns the linear u and v mapping parameters. One-dimensional evaluators return two values, u1 and u2, as specified by glMap1. Two-dimensional evaluators return four values (u1, u2, v1, and v2) as specified by glMap2. Integer values, when requested, are computed by rounding the internal floating-point values to the nearest integer values.

v

Returns the requested data.

Remarks

The glGetMap function returns evaluator parameters. (The glMap1 and glMap2 functions define evaluators.) The target parameter specifies a map, query selects a specific parameter, and v points to storage where the values will be returned.

The acceptable values for the target parameter are described in glMap1 and glMap2

If an error is generated, no change is made to the contents of v.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target or query was not an accepted value.
GL_INVALID_OPERATION	glGetMap was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glEvalCoord, glMap1, glMap2


glGetMaterial [New - Windows 95, OEM Service Release 2]
glGetMaterialfv, glGetMaterialiv

[New - Windows 95, OEM Service Release 2]

The glGetMaterialfv and glGetMaterialiv functions return material parameters.

void glGetMaterialfv(

GLenum face,
GLenum pname,
GLfloat * params
);
void glGetMaterialiv(

GLenum face,
GLenum pname,
GLint * params
);
Parameters

face

Specifies which of the two materials is being queried. GL_FRONT or GL_BACK are accepted, representing the front and back materials, respectively.

pname

The material parameter to return. The following values are accepted:

GL_AMBIENT

The params parameter returns four integer or floating-point values representing the ambient reflectance of the material. Integer values, when requested, are linearly mapped from the internal floating-point representation such that 1.0 maps to the most positive representable integer value, and −1.0 maps to the most negative representable integer value. If the internal value is outside the range [−1,1], the corresponding integer return value is undefined.

GL_DIFFUSE

The params parameter returns four integer or floating-point values representing the diffuse reflectance of the material. Integer values, when requested, are linearly mapped from the internal floating-point representation such that 1.0 maps to the most positive representable integer value, and −1.0 maps to the most negative representable integer value. If the internal value is outside the range [−1,1], the corresponding integer return value is undefined.

GL_SPECULAR

The params parameter returns four integer or floating-point values representing the specular reflectance of the material. Integer values, when requested, are linearly mapped from the internal floating-point representation such that 1.0 maps to the most positive representable integer value, and −1.0 maps to the most negative representable integer value. If the internal value is outside the range [−1,1], the corresponding integer return value is undefined.

GL_EMISSION

The params parameter returns four integer or floating-point values representing the emitted light intensity of the material. Integer values, when requested, are linearly mapped from the internal floating-point representation such that 1.0 maps to the most positive representable integer value, and −1.0 maps to the most negative representable integer value. If the internal value is outside the range [−1,1], the corresponding integer return value is undefined.

GL_SHININESS

The params parameter returns one integer or floating-point value representing the specular exponent of the material. Integer values, when requested, are computed by rounding the internal floating-point value to the nearest integer value.

GL_COLOR_INDEXES

The params parameter returns three integer or floating-point values representing the ambient, diffuse, and specular indexes of the material. Use these indexes only for color-index lighting. (The other parameters are all used only for RGBA lighting.) Integer values, when requested, are computed by rounding the internal floating-point values to the nearest integer values.

params

Returns the requested data.

Remarks

The glGetMaterial function returns in params the value or values of parameter pname of material face.

If an error is generated, no change is made to the contents of params.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	face or pname was not an accepted value.
GL_INVALID_OPERATION	glGetMaterial was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glMaterial


glGetPixelMap [New - Windows 95, OEM Service Release 2]
glGetPixelMapfv, glGetPixelMapuiv, glGetPixelMapusv

[New - Windows 95, OEM Service Release 2]

These functions return the specified pixel map.

void glGetPixelMapfv(

GLenum map,
GLfloat * values
);
void glGetPixelMapuiv(

GLenum map,
GLuint * values
);
void glGetPixelMapusv(

GLenum map,
GLushort * values
);
Parameters

map

The name of the pixel map to return. Accepted values are GL_PIXEL_MAP_I_TO_I, GL_PIXEL_MAP_S_TO_S, GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, GL_PIXEL_MAP_I_TO_A, GL_PIXEL_MAP_R_TO_R, GL_PIXEL_MAP_G_TO_G, GL_PIXEL_MAP_B_TO_B, and GL_PIXEL_MAP_A_TO_A.

values

Returns the pixel map contents.

Remarks

See glPixelMap for a description of the acceptable values for the map parameter. The glGetPixelMap function returns in values the contents of the pixel map specified in map. Use pixel maps during the execution of glReadPixels, glDrawPixels, glCopyPixels, glTexImage1D, and glTexImage2D to map color indexes, stencil indexes, color components, and depth components to other values.

Unsigned integer values, if requested, are linearly mapped from the internal fixed or floating-point representation such that 1.0 maps to the largest representable integer value, and 0.0 maps to zero. Return unsigned integer values are undefined if the map value was not in the range [0,1].

To determine the required size of map, call glGet with the appropriate symbolic constant.

If an error is generated, no change is made to the contents of values.

The following functions retrieve information related to glGetPixelMap:

glGet with argument GL_PIXEL_MAP_I_TO_I_SIZE

glGet with argument GL_PIXEL_MAP_S_TO_S_SIZE

glGet with argument GL_PIXEL_MAP_I_TO_R_SIZE

glGet with argument GL_PIXEL_MAP_I_TO_G_SIZE

glGet with argument GL_PIXEL_MAP_I_TO_B_SIZE

glGet with argument GL_PIXEL_MAP_I_TO_A_SIZE

glGet with argument GL_PIXEL_MAP_R_TO_R_SIZE

glGet with argument GL_PIXEL_MAP_G_TO_G_SIZE

glGet with argument GL_PIXEL_MAP_B_TO_B_SIZE

glGet with argument GL_PIXEL_MAP_A_TO_A_SIZE

glGet with argument GL_MAX_PIXEL_MAP_TABLE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	map was not an accepted value.
GL_INVALID_OPERATION	glGetPixelMap was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glCopyPixels, glDrawPixels, glEnd, glGet, glPixelMap, glPixelTransfer, glReadPixels, glTexImage1D, glTexImage2D


glGetPointerv [New - Windows 95, OEM Service Release 2]
glGetPointerv

[New - Windows 95, OEM Service Release 2]

The glGetPointerv function returns the address of a vertex data array.

void glGetPointerv(

GLenum pname,
GLvoid * * params
);
Parameters

pname

The type of array pointer to return from the following symbolic constants: GL_VERTEX_ARRAY_POINTER, GL_NORMAL_ARRAY_POINTER, GL_COLOR_ARRAY_POINTER, GL_INDEX_ARRAY_POINTER, GL_TEXTURE_COORD_ARRAY_POINTER, and GL_EDGE_FLAG_ARRAY_POINTER.

params

Returns the value of the array pointer specified by pname.

Remarks

The glGetPointerv function returns array pointer information. The pname parameter is a symbolic constant specifying the kind of array pointer to return, and params is a pointer to a location to place the returned data.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	pname was not an accepted value.
See Also

glArrayElement, glColorPointer, glDrawArrays, glEdgeFlagPointer, glGetString, glIndexPointer, glNormalPointer, glTexCoordPointer, glVertexPointer


glGetPolygonStipple [New - Windows 95, OEM Service Release 2]
glGetPolygonStipple

[New - Windows 95, OEM Service Release 2]

The glGetPolygonStipple function returns the polygon stipple pattern.

void glGetPolygonStipple(

GLubyte * mask
);
Parameters

mask

Returns the stipple pattern.

Remarks

The glGetPolygonStipple function returns to mask a 32x32 polygon stipple pattern. The pattern is packed into memory as if glReadPixels with both height and width of 32, type of GL_BITMAP, and format of GL_COLOR_INDEX were called, and the stipple pattern were stored in an internal 32x32 color-index buffer. Unlike glReadPixels, however, pixel-transfer operations (shift, offset, and pixel map) are not applied to the returned stipple image.

If an error is generated, no change is made to the contents of mask.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glGetPolygonStipple was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glPixelStore, glPixelTransfer, glPolygonStipple, glReadPixels


glGetString [New - Windows 95, OEM Service Release 2]
glGetString

[New - Windows 95, OEM Service Release 2]

The glGetString function returns a string describing the current OpenGL connection.

const GLubyte * glGetString(

GLenum name
);
Parameters

name

One of the following symbolic constants:

GL_VENDOR

Returns the company responsible for this OpenGL implementation. This name does not change from release to release.

GL_RENDERER

Returns the name of the renderer. This name is typically specific to a particular configuration of a hardware platform. It does not change from release to release.

GL_VERSION

Returns a version or release number.

GL_EXTENSIONS

Returns a space-separated list of supported extensions to OpenGL.

Remarks

The glGetString function returns a pointer to a static string describing some aspect of the current OpenGL connection.

Because OpenGL does not include queries for the performance characteristics of an implementation, it is expected that some applications will be written to recognize known platforms and will modify their OpenGL usage based on known performance characteristics of these platforms. The strings GL_VENDOR and GL_RENDERER together uniquely specify a platform, and will not change from release to release. They should be used by such platform recognition algorithms.

The format and contents of the string that glGetString returns depend on the implementation, except that:

•	Extension names will not include space characters and will be separated by space characters in the GL_EXTENSIONS string.

•	All strings are null-terminated.

If an error is generated, glGetString returns zero.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	name was not an accepted value.
GL_INVALID_OPERATION	glGetString was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd


glGetTexEnv [New - Windows 95, OEM Service Release 2]
glGetTexEnvfv

[New - Windows 95, OEM Service Release 2]

The glGetTexEnvfv and glGetTexEnviv functions return texture environment parameters.

void glGetTexEnvfv(

GLenum target,
GLenum pname,
GLfloat * params
);
void glGetTexEnviv(

GLenum target,
GLenum pname,
GLint * params
);
Parameters

target

A texture environment. Must be GL_TEXTURE_ENV.

pname

The symbolic name of a texture environment parameter. The following values are accepted:

GL_TEXTURE_ENV_MODE

The params parameter returns the single-valued texture environment mode, a symbolic constant.

GL_TEXTURE_ENV_COLOR

The params parameter returns four integer or floating-point values that are the texture environment color. Integer values, when requested, are linearly mapped from the internal floating-point representation such that 1.0 maps to the most positive representable integer, and −1.0 maps to the most negative representable integer.

params

Returns the requested data.

Remarks

The glGetTexEnv function returns in params selected values of a texture environment that was specified with glTexEnv. The target parameter specifies a texture environment. Currently, only one texture environment is defined and supported: GL_TEXTURE_ENV.

The pname parameter names a specific texture environment parameter.

If an error is generated, no change is made to the contents of params.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target or pname was not an accepted value.
GL_INVALID_OPERATION	glGetTexEnv was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glTexEnv


glGetTexGen [New - Windows 95, OEM Service Release 2]
glGetTexGendv, glGetTexGenfv, glGetTexGeniv

[New - Windows 95, OEM Service Release 2]

These functions return texture coordinate generation parameters.

void glGetTexGendv(

GLenum coord,
GLenum pname,
GLdouble * params
);
void glGetTexGenfv(

GLenum coord,
GLenum pname,
GLfloat * params
);
void glGetTexGeniv(

GLenum coord,
GLenum pname,
GLint * params
);
Parameters

coord

A texture coordinate. Must be GL_S, GL_T, GL_R, or GL_Q.

pname

The symbolic name of the value(s) to be returned. Must be either GL_TEXTURE_GEN_MODE or the name of one of the texture generation plane equations: GL_OBJECT_PLANE or GL_EYE_PLANE. These values are as follows:

GL_TEXTURE_GEN_MODE

The params parameter returns the single-valued texture-generation function, a symbolic constant.

GL_OBJECT_PLANE

The params parameter returns the four plane equation coefficients that specify object linear-coordinate generation. Integer values, when requested, are mapped directly from the internal floating-point representation.

GL_EYE_PLANE

The params parameter returns the four plane equation coefficients that specify eye linear-coordinate generation. Integer values, when requested, are mapped directly from the internal floating-point representation. The returned values are those maintained in eye coordinates. They are not equal to the values specified using glTexGen, unless the modelview matrix was identified at the time glTexGen was called.

params

Returns the requested data.

Remarks

The glGetTexGen function returns in params selected parameters of a texture-coordinate generation function that you specified with glTexGen. The coord parameter names one of the (s,t,r,q) texture coordinates, using the symbolic constant GL_S, GL_T, GL_R, or GL_Q.

If an error is generated, no change is made to the contents of params.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	coord or pname was not an accepted value.
GL_INVALID_OPERATION	glGetTexGen was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glTexGen


glGetTexImage [New - Windows 95, OEM Service Release 2]
glGetTexImage

[New - Windows 95, OEM Service Release 2]

The glGetTexImage function returns a texture image.

void glGetTexImage(

GLenum target,
GLint level,
GLenum format,
GLenum type,
GLvoid * pixels
);
Parameters

target

Specifies which texture is to be obtained. GL_TEXTURE_1D and GL_TEXTURE_2D are accepted.

level

The level-of-detail number of the desired image. Level 0 is the base image level. Level n is the nth mipmap reduction image.

format

A pixel format for the returned data. The supported formats are GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, GL_BGR_EXT, GL_BGRA_EXT, and GL_LUMINANCE_ALPHA.

type

A pixel type for the returned data. The supported types are GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, and GL_FLOAT.

pixels

Returns the texture image. Should be a pointer to an array of the type specified by type.

Remarks

The glGetTexImage function returns a texture image into pixels. The target parameter specifies whether the desired texture image is one specified by glTexImage1D(GL_TEXTURE_1D) or by glTexImage2D(GL_TEXTURE_2D). The level parameter specifies the level-of-detail number of the desired image. The format and type parameters specify the format and type of the desired image array. For a description of the acceptable values for the format and type parameters, respectively, see glTexImage1D and glDrawPixels.

Operation of glGetTexImage is best understood by considering the selected internal four-component texture image to be an RGBA color buffer the size of the image. The semantics of glGetTexImage are then identical to those of glReadPixels called with the same format and type, with x and y set to zero, width set to the width of the texture image (including border if one was specified), and height set to one for 1-D images, or to the height of the texture image (including border, if one was specified) for 2-D images.

Because the internal texture image is an RGBA image, pixel formats GL_COLOR_INDEX, GL_STENCIL_INDEX, and GL_DEPTH_COMPONENT are not accepted, and pixel type GL_BITMAP is not accepted.

If the selected texture image does not contain four components, the following mappings are applied. Single-component textures are treated as RGBA buffers with red set to the single-component value, and green, blue, and alpha set to zero.

Two-component textures are treated as RGBA buffers, with red set to the value of component zero, alpha set to the value of component one, and green and blue set to zero. Finally, three-component textures are treated as RGBA buffers with red set to component zero, green set to component one, blue set to component two, and alpha set to zero.

To determine the required size of pixels, use glGetTexLevelParameter to ascertain the dimensions of the internal texture image, and then scale the required number of pixels by the storage required for each pixel, based on format and type. Be sure to take the pixel-storage parameters into account, especially GL_PACK_ALIGNMENT.

If an error is generated, no change is made to the contents of pixels.

The following functions retrieve information related to glGetTexImage:

glGetTexLevelParameter with argument GL_TEXTURE_WIDTH

glGetTexLevelParameter with argument GL_TEXTURE_HEIGHT

glGetTexLevelParameter with argument GL_TEXTURE_BORDER

glGetTexLevelParameter with argument GL_TEXTURE_COMPONENTS

glGet with argument GL_PACK_ALIGNMENT and others

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target, format, or type was not an accepted value.
GL_INVALID_VALUE	level is less than zero or greater than log (2)  max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_OPERATION	glGetTexImage was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glDrawPixels, glEnd, glGetTexLevelParameter, glReadPixels, glTexImage1D, glTexImage2D


glGetTexLevelParameter [New - Windows 95, OEM Service Release 2]
glGetTexLevelParameterfv, glGetTexLevelParameteriv

[New - Windows 95, OEM Service Release 2]

The glGetTexLevelParameterfv and glGetTexLevelParameteriv functions return texture parameter values for a specific level of detail.

void glGetTexLevelParameterfv(

GLenum target,
GLint level,
GLenum pname,
GLfloat * params
);
void glGetTexLevelParameteriv(

GLenum target,
GLint level,
GLenum pname,
GLint * params
);
Parameters

target

The symbolic name of the target texture: either GL_TEXTURE_1D or GL_TEXTURE_2D.

level

The level-of-detail number of the desired image. Level 0 is the base image level. Level n is the nth mipmap reduction image.

pname

The symbolic name of a texture parameter. The following parameter names are accepted:

GL_TEXTURE_WIDTH

The params parameter returns a single value: the width of the texture image. This value includes the border of the texture image.

GL_TEXTURE_HEIGHT

The params parameter returns a single value: the height of the texture image. This value includes the border of the texture image.

GL_TEXTURE_COMPONENTS

The params parameter returns a single value: the number of components in the texture image.

GL_TEXTURE_BORDER

The params parameter returns a single value: the width in pixels of the border of the texture image.

params

Returns the requested data.

Remarks

The glGetTexLevelParameter function returns in params texture parameter values for a specific level-of-detail value, specified as level. The target parameter defines the target texture—either GL_TEXTURE_1D or GL_TEXTURE_2D—to specify one- or two-dimensional texturing. The pname parameter specifies the texture parameter whose value or values will be returned.

If an error is generated, no change is made to the contents of params.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target or pname was not an accepted value.
GL_INVALID_VALUE	level is less than zero or greater than log (2)  max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_OPERATION	glGetTexLevelParameter was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glGetTexParameter, glTexImage1D, glTexImage2D, glTexParameter


glGetTexParameter [New - Windows 95, OEM Service Release 2]
glGetTexParameterfv, glGetTexParameteriv

[New - Windows 95, OEM Service Release 2]

The glGetTexParameterfv and glGetTexParameteriv functions return texture parameter values.

void glGetTexParameterfv(

GLenum target,
GLenum pname,
GLfloat * params
);
void glGetTexParameteriv(

GLenum target,
GLenum pname,
GLint * params
);
Parameters

target

The symbolic name of the target texture. GL_TEXTURE_1D and GL_TEXTURE_2D are accepted.

pname

The symbolic name of a texture parameter. The following values are accepted:

GL_TEXTURE_MAG_FILTER

Returns the single-valued texture magnification filter, a symbolic constant.

GL_TEXTURE_MIN_FILTER

Returns the single-valued texture minification filter, a symbolic constant.

GL_TEXTURE_WRAP_S

Returns the single-valued wrapping function for texture coordinate s, a symbolic constant.

GL_TEXTURE_WRAP_T

Returns the single-valued wrapping function for texture coordinate t, a symbolic constant.

GL_TEXTURE_BORDER_COLOR

Returns four integer or floating-point numbers that comprise the RGBA color of the texture border. Floating-point values are returned in the range [0,1]. Integer values are returned as a linear mapping of the internal floating-point representation such that 1.0 maps to the most positive representable integer and −1.0 maps to the most negative representable integer.

params

Returns the texture parameters.

Remarks

The glGetTexParameter function returns in params the value or values of the texture parameter specified as pname. The target parameter defines the target texture—either GL_TEXTURE_1D or GL_TEXTURE_2D—to specify one- or two-dimensional texturing. The pname parameter accepts the same symbols as glTexParameter, with the same interpretations.

If an error is generated, no change is made to the contents of params.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target or pname was not an accepted value.
GL_INVALID_OPERATION	glGetTexParameter was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glTexParameter


glHint [New - Windows 95, OEM Service Release 2]
glHint

[New - Windows 95, OEM Service Release 2]

The glHint function specifies implementation-specific hints.

void glHint(

GLenum target,
GLenum mode
);
Parameters

target

A symbolic constant indicating the behavior to be controlled. The following symbolic constants, along with suggested semantics, are accepted:

GL_FOG_HINT

Indicates the accuracy of fog calculation. If per-pixel fog calculation is not efficiently supported by the OpenGL implementation, hinting GL_DONT_CARE or GL_FASTEST can result in per-vertex calculation of fog effects.

GL_LINE_SMOOTH_HINT

Indicates the sampling quality of antialiased lines. Hinting GL_NICEST can result in more pixel fragments being generated during rasterization, if a larger filter function is applied.

GL_PERSPECTIVE_CORRECTION_HINT

Indicates the quality of color and texture coordinate interpolation. If perspective-corrected parameter interpolation is not efficiently supported by the OpenGL implementation, hinting GL_DONT_CARE or GL_FASTEST can result in simple linear interpolation of colors and/or texture coordinates.

GL_POINT_SMOOTH_HINT

Indicates the sampling quality of antialiased points. Hinting GL_NICEST can result in more pixel fragments being generated during rasterization, if a larger filter function is applied.

GL_POLYGON_SMOOTH_HINT

Indicates the sampling quality of antialiased polygons. Hinting GL_NICEST can result in more pixel fragments being generated during rasterization, if a larger filter function is applied.

mode

A symbolic constant indicating the desired behavior. The following symbolic constants are accepted:

GL_FASTEST

The most efficient option should be chosen.

GL_NICEST

The most correct, or highest quality, option should be chosen.

GL_DONT_CARE

The client doesn’t have a preference.

Remarks

When there is room for interpretation, you can control certain aspects of OpenGL behavior with hints. You specify a hint with two arguments. The target parameter is a symbolic constant indicating the behavior to be controlled, and mode is another symbolic constant indicating the desired behavior.

Though the implementation aspects that can be hinted are well defined, the interpretation of the hints depends on the implementation.

The glHint function can be ignored.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target or mode was not an accepted value.
GL_INVALID_OPERATION	glHint was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd


glIndex [New - Windows 95, OEM Service Release 2]
glIndex

[New - Windows 95, OEM Service Release 2]

glIndexd, glIndexf, glIndexi, glIndexs, glIndexdv, glIndexfv, glIndexiv, glIndexsv

These functions set the current color index.

void glIndexd(

GLdouble c
);
void glIndexf(

GLfloat c
);
void glIndexi(

GLint c
);
void glIndexs(

GLshort c
);
Parameters

c

The new value for the current color index.

void glIndexdv(

const GLdouble *c
);
void glIndexfv(

const GLfloat *c
);
void glIndexiv(

const GLint *c
);
void glIndexsv(

const GLshort *c
);
Parameters

c

A pointer to a one-element array that contains the new value for the current color index.

Remarks

The glIndex function updates the current (single-valued) color index. It takes one argument: the new value for the current color index.

The current index is stored as a floating-point value. Integer values are converted directly to floating-point values, with no special mapping.

Index values outside the representable range of the color-index buffer are not clamped. However, before an index is dithered (if enabled) and written to the frame buffer, it is converted to fixed-point format. Any bits in the integer portion of the resulting fixed-point value that do not correspond to bits in the frame buffer are masked out.

The current index can be updated at any time. In particular, glIndex can be called between a call to glBegin and the corresponding call to glEnd.

The following function retrieves information related to glIndex:

glGet with argument GL_CURRENT_INDEX

See Also

glBegin, glColor, glEnd, glGet


glIndexMask [New - Windows 95, OEM Service Release 2]
glIndexMask

[New - Windows 95, OEM Service Release 2]

The glIndexMask function controls the writing of individual bits in the color-index buffers.

void glIndexMask(

GLuint mask
);
Parameters

mask

A bit mask to enable and disable the writing of individual bits in the color-index buffers. Initially, the mask is all ones.

Remarks

The glIndexMask function controls the writing of individual bits in the color-index buffers. The least significant n bits of mask, where n is the number of bits in a color-index buffer, specify a mask. Wherever a one appears in the mask, the corresponding bit in the color-index buffer (or buffers) is made writable. Where a zero appears, the bit is write-protected.

This mask is used only in color-index mode, and it affects only the buffers currently selected for writing (see glDrawBuffer). Initially, all bits are enabled for writing.

The following function retrieves information related to glIndexMask:

glGet with argument GL_INDEX_WRITEMASK

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glIndexMask was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glDepthMask, glDrawBuffer, glEnd, glIndex, glStencilMask


glIndexPointer [New - Windows 95, OEM Service Release 2]
glIndexPointer

[New - Windows 95, OEM Service Release 2]

The glIndexPointer function defines an array of color indexes.

void glIndexPointer(

GLenum type,
GLsizei stride,
GLsizei count,
const GLvoid *pointer
);
Parameters

type

The data type of each color index in the array using the following symbolic constants: GL_SHORT, GL_INT, GL_FLOAT, GL_DOUBLE.

stride

The byte offset between consecutive color indexes. When stride is zero, the color indexes are tightly packed in the array.

count

The number of color indexes, counting from the first, that are static.

pointer

A pointer to the first color index in the array.

Remarks

The glIndexPointer function specifies the location and data of an array of color indexes to use when rendering. The type parameter specifies the data type of each color index and stride determines the byte offset from one color index to the next, enabling the packing of vertices and attributes in a single array or storage in separate arrays. In some implementations storing the vertices and attributes in a single array can be more efficient than using separate arrays. Starting from the first color-index element, count indicates the total number of static elements. Your application can modify static elements, but once the elements are modified, the application must explicitly specify the array again before using the array for any rendering. Non-static array elements are not accessed until you call glDrawArrays or glArrayElement.

A color-index array is enabled when you specify the GL_INDEX_ARRAY constant with glEnableClientState. When enabled, glDrawArrays and glArrayElement use the color-index array. By default the color-index array is disabled.

You cannot include glIndexPointer in display lists.

When you specify a color-index array using glIndexPointer, the values of all the function’s color-index array parameters are saved in a client-side state and static array elements can be cached. Because the color-index array parameters are client-side state, their values are not saved or restored by glPushAttrib and glPopAttrib.

Although no error is generated when you call glIndexPointer within glBegin and glEnd pairs, the results are undefined.

The following functions retrieve information related to glIndexPointer:

glIsEnabled with argument GL_INDEX_ARRAY

glGet with argument GL_INDEX_ARRAY_STRIDE

glGet with argument GL_INDEX_ARRAY_COUNT

glGet with argument GL_INDEX_ARRAY_TYPE

glGet with argument GL_INDEX_ARRAY_SIZE

glGetPointerv with argument GL_INDEX_ARRAY_POINTER

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	type was not an accepted value.
GL_INVALID_VALUE	stride or count was negative.
See Also

glArrayElement, glColorPointer, glDrawArrays, glEdgeFlagPointer, glGetPointerv, glGetString, glNormalPointer, glPushAttrib, glTexCoordPointer, glVertexPointer


glInitNames [New - Windows 95, OEM Service Release 2]
glInitNames

[New - Windows 95, OEM Service Release 2]

The glInitNames function initializes the name stack.

void glInitNames(

void
);
Remarks

The glInitNames function causes the name stack to be initialized to its default empty state. The name stack is used during selection mode to allow sets of rendering commands to be uniquely identified. It consists of an ordered set of unsigned integers.

The name stack is always empty while the render mode is not GL_SELECT. Calls to glInitNames while the render mode is not GL_SELECT are ignored.

The following functions retrieve information related to glInitNames:

glGet with argument GL_NAME_STACK_DEPTH

glGet with argument GL_MAX_NAME_STACK_DEPTH

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glInitNames was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glLoadName, glPushName, glRenderMode, glSelectBuffer


glInterleavedArrays [New - Windows 95, OEM Service Release 2]
glInterleavedArrays

[New - Windows 95, OEM Service Release 2]

The glInterleavedArrays function simultaneously specifies and enables several interleaved arrays in a larger aggregate array.

void glInterleavedArrays(

GLenum format,
GLsizei stride,
const GLvoid * pointer
);
Parameters

format

The type of array to enable. The parameter can assume one of the following symbolic values: GL_V2F, GL_V3F, GL_C4UB_V2F, GL_C4UB_V3F, GL_C3F_V3F, GL_N3F_V3F, GL_C4F_N3F_V3F, GL_T2F_V3F, GL_T4F_V4F, GL_T2F_C4UB_V3F, GL_T2F_C3F_V3F, GL_T2F_N3F_V3F, GL_T2F_C4F_N3F_V3F, or GL_T4F_C4F_N3F_V4F.

stride

The offset in bytes between each aggregate array element.

pointer

A pointer to the first element of an aggregate array.

Remarks

With the glInterleavedArrays function you can simultaneously specify and enable several interleaved color, normal, texture, and vertex arrays whose elements are part of a larger aggregate array element. For some memory architectures this is more efficient than specifying the arrays separately.

If the stride parameter is zero then the aggregate array elements are stored consecutively; otherwise stride bytes occur between aggregate array elements.

The format parameter serves as a “key” that describes how to extract individual arrays from the aggregate array:

•	If format contains a T, then texture coordinates are extracted from the interleaved array.

•	If C is present, color values are extracted.

•	If N is present, normal coordinates are extracted.

•	Vertex coordinates are always extracted.

•	The digits 2, 3, and 4 denote how many values are extracted.

•	F indicates that values are extracted as floating point values.

•	If 4UB follows the C, colors may also be extracted as 4 unsigned bytes. If a color is extracted as 4 unsigned bytes the vertex array element that follows is located at the first possible floating point aligned address.

If you call glInterleavedArrays while compiling a display list, it is not compiled into the list but is executed immediately.

You cannot include calls to glInterleavedArrays in glDisableClientState between calls to glBegin and the corresponding call to glEnd.

Note  The glInterleavedArrays function is only available in OpenGL version 1.1 or later.

The glInterleavedArrays function is implemented on the client side with no protocol. Because the vertex array parameters are client-side state, they are not saved or restored by glPushAttrib and glPopAttrib. Use glPushClientAttrib and glPopClientAttrib instead.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	format was not an accepted value.
GL_INVALID_VALUE	stride was a negative value.
GL_INVALID_OPERATION	glInterleavedArrays was called between a call to glBegin and the corresponding call to glEnd.
See Also

glArrayElement, glColorPointer, glDrawArrays, glDrawElements, glEdgeFlagPointer, glEnableClientState, glGetPointerv, glIndexPointer, glNormalPointer, glPushAttrib, glPushClientAttrib, glTexCoordPointer, glVertexPointer


glIsEnabled [New - Windows 95, OEM Service Release 2]
glIsEnabled

[New - Windows 95, OEM Service Release 2]

The gllsEnabled function tests whether a capability is enabled.

GLboolean glIsEnabled(

GLenum cap
);
Parameters

cap

A symbolic constant indicating an OpenGL capability. The following capabilities are accepted:

GL_ALPHA_TEST	See glAlphaFunc
GL_AUTO_NORMAL	See glEvalCoord
GL_BLEND	See glBlendFunc
GL_CLIP_PLANEi	See glClipPlane
GL_COLOR_MATERIAL	See glColorMaterial
GL_CULL_FACE	See glCullFace
GL_DEPTH_TEST	See glDepthFunc and glDepthRange
GL_DITHER	See glEnable
GL_FOG	See glFog
GL_LIGHTi	See glLightModel and glLight
GL_LIGHTING	See glMaterial, glLightModel, and glLight
GL_LINE_SMOOTH	See glLineWidth
GL_LINE_STIPPLE	See glLineStipple
GL_LOGIC_OP	See glLogicOp
GL_MAP1_COLOR_4	See glMap1
GL_MAP1_INDEX	See glMap1
GL_MAP1_NORMAL	See glMap1
GL_MAP1_TEXTURE_COORD_1	See glMap1
GL_MAP1_TEXTURE_COORD_2	See glMap1
GL_MAP1_TEXTURE_COORD_3	See glMap1
GL_MAP1_TEXTURE_COORD_4	See glMap1
GL_MAP1_VERTEX_3	See glMap1
GL_MAP1_VERTEX_4	See glMap1
GL_MAP2_COLOR_4	See glMap2
GL_MAP2_INDEX	See glMap2
GL_MAP2_NORMAL	See glMap2
GL_MAP2_TEXTURE_COORD_1	See glMap2
GL_MAP2_TEXTURE_COORD_2	See glMap2
GL_MAP2_TEXTURE_COORD_3	See glMap2
GL_MAP2_TEXTURE_COORD_4	See glMap2
GL_MAP2_VERTEX_3	See glMap2
GL_MAP2_VERTEX_4	See glMap2
GL_NORMALIZE	See glNormal
GL_POINT_SMOOTH	See glPointSize
GL_POLYGON_SMOOTH	See glPolygonMode
GL_POLYGON_STIPPLE	See glPolygonStipple
GL_SCISSOR_TEST	See glScissor
GL_STENCIL_TEST	See glStencilFunc and glStencilOp
GL_TEXTURE_1D	See glTexImage1D
GL_TEXTURE_2D	See glTexImage2D
GL_TEXTURE_GEN_Q	See glTexGen
GL_TEXTURE_GEN_R	See glTexGen
GL_TEXTURE_GEN_S	See glTexGen
GL_TEXTURE_GEN_T	See glTexGen
Remarks

The gllsEnabled function returns GL_TRUE if cap is an enabled capability and returns GL_FALSE otherwise.

Error Codes

If an error is generated, glIsEnabled returns zero.

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	cap was not an accepted value.
GL_INVALID_OPERATION	glIsEnabled was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnable, glEnd


glIsList [New - Windows 95, OEM Service Release 2]
glIsList

[New - Windows 95, OEM Service Release 2]

The gllsList function tests for display list existence.

GLboolean glIsList(

GLuint list
);
Parameters

list

A potential display list name.

Remarks

The gllsList function returns GL_TRUE if list is the name of a display list and returns GL_FALSE otherwise.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glIsList was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glCallList, glCallLists, glDeleteLists, glEnd, glGenLists, glNewList


glIsTexture [New - Windows 95, OEM Service Release 2]
glIsTexture

[New - Windows 95, OEM Service Release 2]

The glIsTexture function determines if a name corresponds to a texture.

GLboolean glIsTexture(

GLuint texture
);
Parameters

texture

A value that is the name of a texture.

Remarks

If the texture parameter is currently the name of a texture, the glIsTexture function returns GL_TRUE. If texture is zero, is a non-zero value that is not currently the name of a texture, or if an error occurs, glIsTexture returns GL_FALSE.

You cannot include calls to glIsTexture in display lists.

Note  The glIsTexture function is only available in OpenGL version 1.1 or later.

Error Codes

The following is the error code generated and its condition.

Error Code	Condition
GL_INVALID_OPERATION	glIsTexture was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glBindTexture, glEnd, glGenTextures, glGet, glGetTexParameter, glTexImage1D, glTexImage2D, glTexParameter


glLight [New - Windows 95, OEM Service Release 2]
glLightf, glLighti, glLightfv, glLightiv

[New - Windows 95, OEM Service Release 2]

These functions set light source parameters.

void glLightf(

GLenum light,
GLenum pname,
GLfloat param
);
void glLighti(

GLenum light,
GLenum pname,
GLint param
);
Parameters

light

A light. The number of lights depends on the implementation, but at least eight lights are supported. They are identified by symbolic names of the form GL_LIGHTi where 0 ≤ i < GL_MAX_LIGHTS.

pname

A single-valued light source parameter for light. The following values are accepted.

GL_SPOT_EXPONENT

The params parameter is a single integer or floating-point value that specifies the intensity distribution of the light. Integer and floating-point values are mapped directly. Only values in the range [0,128] are accepted.

Effective light intensity is attenuated by the cosine of the angle between the direction of the light and the direction from the light to the vertex being lighted, raised to the power of the spot exponent. Thus, higher spot exponents result in a more focused light source, regardless of the spot cutoff angle (see the following paragraph). The default spot exponent is 0, resulting in uniform light distribution.

GL_SPOT_CUTOFF

The params parameter is a single integer or floating-point value that specifies the maximum spread angle of a light source. Integer and floating-point values are mapped directly. Only values in the range [0,90], and the special value 180, are accepted. If the angle between the direction of the light and the direction from the light to the vertex being lighted is greater than the spot cutoff angle, then the light is completely masked. Otherwise, its intensity is controlled by the spot exponent and the attenuation factors. The default spot cutoff is 180, resulting in uniform light distribution.

GL_CONSTANT_ATTENUATION

GL_LINEAR_ATTENUATION

GL_QUADRATIC_ATTENUATION

The params parameter is a single integer or floating-point value that specifies one of the three light attenuation factors. Integer and floating-point values are mapped directly. Only nonnegative values are accepted. If the light is positional, rather than directional, its intensity is attenuated by the reciprocal of the sum of: the constant factor, the linear factor multiplied by the distance between the light and the vertex being lighted, and the quadratic factor multiplied by the square of the same distance. The default attenuation factors are (1,0,0), resulting in no attenuation.

param

The value to which parameter pname of light source light will be set.

void glLightfv(

GLenum light,
GLenum pname,
const GLfloat *params
);
void glLightiv(

GLenum light,
GLenum pname,
const GLint *params
);
Parameters

light

A light. The number of lights depends on the implementation, but at least eight lights are supported. They are identified by symbolic names of the form GL_LIGHTi where 0 ≤ i < GL_MAX_LIGHTS.

pname

A light source parameter for light. The following values are accepted:

GL_AMBIENT

The params parameter contains four integer or floating-point values that specify the ambient RGBA intensity of the light. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to −1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The default ambient light intensity is (0.0, 0.0, 0.0, 1.0).

GL_DIFFUSE

The params parameter contains four integer or floating-point values that specify the diffuse RGBA intensity of the light. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to −1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The default diffuse intensity is (0.0, 0.0, 0.0, 1.0) for all lights other than light zero. The default diffuse intensity of light zero is (1.0, 1.0, 1.0, 1.0).

GL_SPECULAR

The params parameter contains four integer or floating-point values that specify the specular RGBA intensity of the light. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to −1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The default specular intensity is (0.0, 0.0, 0.0, 1.0) for all lights other than light zero. The default specular intensity of light zero is (1.0, 1.0, 1.0, 1.0).

GL_POSITION

The params parameter contains four integer or floating-point values that specify the position of the light in homogeneous object coordinates. Both integer and floating-point values are mapped directly. Neither integer nor floating-point values are clamped.

The position is transformed by the modelview matrix when glLight is called (just as if it were a point), and it is stored in eye coordinates. If the w component of the position is 0.0, the light is treated as a directional source. Diffuse and specular lighting calculations take the lights direction, but not its actual position, into account, and attenuation is disabled. Otherwise, diffuse and specular lighting calculations are based on the actual location of the light in eye coordinates, and attenuation is enabled. The default position is (0,0,1,0); thus, the default light source is directional, parallel to, and in the direction of the −z axis.

GL_SPOT_DIRECTION

The params parameter contains three integer or floating-point values that specify the direction of the light in homogeneous object coordinates. Both integer and floating-point values are mapped directly. Neither integer nor floating-point values are clamped.

The spot direction is transformed by the inverse of the modelview matrix when glLight is called (just as if it were a normal), and it is stored in eye coordinates. It is significant only when GL_SPOT_CUTOFF is not 180, which it is by default. The default direction is (0,0,−1).

GL_SPOT_EXPONENT

The params parameter is a single integer or floating-point value that specifies the intensity distribution of the light. Integer and floating-point values are mapped directly. Only values in the range [0,128] are accepted.

Effective light intensity is attenuated by the cosine of the angle between the direction of the light and the direction from the light to the vertex being lighted, raised to the power of the spot exponent. Thus, higher spot exponents result in a more focused light source, regardless of the spot cutoff angle (see the following paragraph). The default spot exponent is 0, resulting in uniform light distribution.

GL_SPOT_CUTOFF

The params parameter is a single integer or floating-point value that specifies the maximum spread angle of a light source. Integer and floating-point values are mapped directly. Only values in the range [0,90], and the special value 180, are accepted. If the angle between the direction of the light and the direction from the light to the vertex being lighted is greater than the spot cutoff angle, then the light is completely masked. Otherwise, its intensity is controlled by the spot exponent and the attenuation factors. The default spot cutoff is 180, resulting in uniform light distribution.

GL_CONSTANT_ATTENUATION

GL_LINEAR_ATTENUATION

GL_QUADRATIC_ATTENUATION

The params parameter is a single integer or floating-point value that specifies one of the three light attenuation factors. Integer and floating-point values are mapped directly. Only nonnegative values are accepted. If the light is positional, rather than directional, its intensity is attenuated by the reciprocal of the sum of: the constant factor, the linear factor multiplied by the distance between the light and the vertex being lighted, and the quadratic factor multiplied by the square of the same distance. The default attenuation factors are (1,0,0), resulting in no attenuation.

params

A pointer to the value or values to which parameter pname of light source light will be set.

Remarks

The glLight function sets the values of individual light source parameters. The light parameter names the light and is a symbolic name of the form:

GL_LIGHTi, where 0 ≤ i < GL_MAX_LIGHTS

The pname parameter specifies one of ten light source parameters, again by symbolic name. The params parameter is either a single value or a pointer to an array that contains the new values.

Lighting calculation is enabled and disabled using glEnable and glDisable with argument GL_LIGHTING. When lighting is enabled, light sources that are enabled contribute to the lighting calculation. Light source i is enabled and disabled using glEnable and glDisable with argument GL_LIGHTi.

It is always the case that GL_LIGHTi = GL_LIGHT0 + i.

The following functions retrieve information related to the glLight function:

glGetLight

glIsEnabled with argument GL_LIGHTING

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	light or pname was not an accepted value.
GL_INVALID_VALUE	a spot exponent value was specified outside the range [0,128], or if spot cutoff was specified outside the range [0,90] (except for the special value 180), or if a negative attenuation factor was specified.
GL_INVALID_OPERATION	glLight was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glColorMaterial, glEnd, glLightModel, glMaterial


glLightModel [New - Windows 95, OEM Service Release 2]
glLightModelf, glLightModeli, glLightModelfv, glLightModeliv

[New - Windows 95, OEM Service Release 2]

These functions set the lighting model parameters.

void glLightModelf(

GLenum pname,
GLfloat param
);
void glLightModeli(

GLenum pname,
GLint param
);
Parameters

pname

A single-valued lighting model parameter. The following values are accepted:

GL_LIGHT_MODEL_LOCAL_VIEWER

The params parameter is a single integer or floating-point value that specifies how specular reflection angles are computed. If params is 0 (or 0.0), specular reflection angles take the view direction to be parallel to and in the direction of the −z axis, regardless of the location of the vertex in eye coordinates. Otherwise specular reflections are computed from the origin of the eye coordinate system. The default is 0.

GL_LIGHT_MODEL_TWO_SIDE

The params parameter is a single integer or floating-point value that specifies whether one- or two-sided lighting calculations are done for polygons. It has no effect on the lighting calculations for points, lines, or bitmaps. If params is 0 (or 0.0), one-sided lighting is specified, and only the front material parameters are used in the lighting equation. Otherwise, two-sided lighting is specified. In this case, vertices of back-facing polygons are lighted using the back material parameters, and have their normals reversed before the lighting equation is evaluated. Vertices of front-facing polygons are always lighted using the front material parameters, with no change to their normals. The default is 0.

param

The value to which param will be set.

void glLightModelfv(

GLenum pname,
const GLfloat *params
);
void glLightModeliv(

GLenum pname,
const GLint *params
);
Parameters

pname

A lighting model parameter. The following values are accepted:

GL_LIGHT_MODEL_AMBIENT

The params parameter contains four integer or floating-point values that specify the ambient RGBA intensity of the entire scene. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to −1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The default ambient scene intensity is (0.2, 0.2, 0.2, 1.0).

GL_LIGHT_MODEL_LOCAL_VIEWER

The params parameter is a single integer or floating-point value that specifies how specular reflection angles are computed. If params is 0 (or 0.0), specular reflection angles take the view direction to be parallel to and in the direction of the −z axis, regardless of the location of the vertex in eye coordinates. Otherwise specular reflections are computed from the origin of the eye coordinate system. The default is 0.

GL_LIGHT_MODEL_TWO_SIDE

The params parameter is a single integer or floating-point value that specifies whether one- or two-sided lighting calculations are done for polygons. It has no effect on the lighting calculations for points, lines, or bitmaps. If params is 0 (or 0.0), one-sided lighting is specified, and only the front material parameters are used in the lighting equation. Otherwise, two-sided lighting is specified. In this case, vertices of back-facing polygons are lighted using the back material parameters, and have their normals reversed before the lighting equation is evaluated. Vertices of front-facing polygons are always lighted using the front material parameters, with no change to their normals. The default is 0.

params

A pointer to the value or values to which params will be set.

Remarks

The glLightModel function sets the lighting model parameter. The pname parameter names a parameter and params gives the new value.

In RGBA mode, the lighted color of a vertex is the sum of the material emission intensity, the product of the material ambient reflectance and the lighting model full-scene ambient intensity, and the contribution of each enabled light source. Each light source contributes the sum of three terms: ambient, diffuse, and specular. The ambient light source contribution is the product of the material ambient reflectance and the light’s ambient intensity. The diffuse light source contribution is the product of the material diffuse reflectance, the light’s diffuse intensity, and the dot product of the vertex's normal with the normalized vector from the vertex to the light source. The specular light source contribution is the product of the material specular reflectance, the light’s specular intensity, and the dot product of the normalized vertex-to-eye and vertex-to-light vectors, raised to the power of the shininess of the material. All three light source contributions are attenuated equally based on the distance from the vertex to the light source and on light source direction, spread exponent, and spread cutoff angle. All dot products are replaced with zero if they evaluate to a negative value.

The alpha component of the resulting lighted color is set to the alpha value of the material diffuse reflectance.

In color-index mode, the value of the lighted index of a vertex ranges from the ambient to the specular values passed to glMaterial using GL_COLOR_INDEXES. Diffuse and specular coefficients, computed with a (.30, .59, .11) weighting of the light’s colors, the shininess of the material, and the same reflection and attenuation equations as in the RGBA case, determine how much above ambient the resulting index is.

The following functions retrieve information related to glLightModel:

glGet with argument GL_LIGHT_MODEL_AMBIENT

glGet with argument GL_LIGHT_MODEL_LOCAL_VIEWER

glGet with argument GL_LIGHT_MODEL_TWO_SIDE

glIsEnabled with argument GL_LIGHTING

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	pname was not an accepted value.
GL_INVALID_OPERATION	glLightModel was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glLight, glMaterial


glLineStipple [New - Windows 95, OEM Service Release 2]
glLineStipple

[New - Windows 95, OEM Service Release 2]

The glLineStipple function specifies the line stipple pattern.

void glLineStipple(

GLint factor,
GLushort pattern
);
Parameters

factor

A multiplier for each bit in the line stipple pattern. If factor is 3, for example, each bit in the pattern will be used three times before the next bit in the pattern is used. The factor parameter is clamped to the range [1, 256] and defaults to one.

pattern

A 16-bit integer whose bit pattern determines which fragments of a line will be drawn when the line is rasterized. Bit zero is used first, and the default pattern is all ones.

Remarks

The glLineStipple function specifies the line stipple pattern. Line stippling masks out certain fragments produced by rasterization; those fragments will not be drawn. The masking is achieved by using three parameters: the 16-bit line stipple pattern pattern, the repeat count factor, and an integer stipple counter s.

Counter s is reset to zero whenever glBegin is called, and before each line segment of a glBegin(GL_LINES)/glEnd sequence is generated. It is incremented after each fragment of a unit width aliased line segment is generated, or after each i fragments of an i width line segment are generated. The i fragments associated with count s are masked out if pattern bit (s factor) mod 16 is zero, otherwise these fragments are sent to the frame buffer. Bit zero of pattern is the least significant bit.

Antialiased lines are treated as a sequence of 1xwidth rectangles for purposes of stippling. Rectangle s is rasterized or not based on the fragment rule described for aliased lines; it counts rectangles rather than groups of fragments.

Line stippling is enabled or disabled using glEnable and glDisable with argument GL_LINE_STIPPLE. When enabled, the line stipple pattern is applied as described above. When disabled, it is as if the pattern were all ones. Initially, line stippling is disabled.

The following functions retrieve information related to glLineStipple:

glGet with argument GL_LINE_STIPPLE_PATTERN

glGet with argument GL_LINE_STIPPLE_REPEAT

glIsEnabled with argument GL_LINE_STIPPLE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glLineStipple was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glLineWidth, glPolygonStipple


glLineWidth [New - Windows 95, OEM Service Release 2]
glLineWidth

[New - Windows 95, OEM Service Release 2]

The glLineWidth function specifies the width of rasterized lines.

void glLineWidth(

GLfloat width
);
Parameters

width

The width of rasterized lines. The default is 1.0.

Remarks

The glLineWidth function specifies the rasterized width of both aliased and antialiased lines. Using a line width other than 1.0 has different effects, depending on whether line antialiasing is enabled. Line antialiasing is controlled by calling glEnable and glDisable with argument GL_LINE_SMOOTH.

If line antialiasing is disabled, the actual width is determined by rounding the supplied width to the nearest integer. (If the rounding results in the value 0, it is as if the line width were 1.) If | Δ x | ≥ | Δ y |, i pixels are filled in each column that is rasterized, where i is the rounded value of width. Otherwise, i pixels are filled in each row that is rasterized.

If antialiasing is enabled, line rasterization produces a fragment for each pixel square that intersects the region lying within the rectangle having width equal to the current line width, length equal to the actual length of the line, and centered on the mathematical line segment. The coverage value for each fragment is the window coordinate area of the intersection of the rectangular region with the corresponding pixel square. This value is saved and used in the final rasterization step.

Not all widths can be supported when line antialiasing is enabled. If an unsupported width is requested, the nearest supported width is used. Only width 1.0 is guaranteed to be supported; others depend on the implementation. The range of supported widths and the size difference between supported widths within the range can be queried by calling glGet with arguments GL_LINE_WIDTH_RANGE and GL_LINE_WIDTH_GRANULARITY.

The line width specified by glLineWidth is always returned when GL_LINE_WIDTH is queried. Clamping and rounding for aliased and antialiased lines have no effect on the specified value.

Non-antialiased line width may be clamped to an implementation-dependent maximum. Although this maximum cannot be queried, it must be no less than the maximum value for antialiased lines, rounded to the nearest integer value.

The following functions retrieve information related to glLineWidth:

glGet with argument GL_LINE_WIDTH

glGet with argument GL_LINE_WIDTH_RANGE

glGet with argument GL_LINE_WIDTH_GRANULARITY

glIsEnabled with argument GL_LINE_SMOOTH

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	width was less than or equal to zero.
GL_INVALID_OPERATION	glLineWidth was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnable, glEnd, glIsEnabled


glListBase [New - Windows 95, OEM Service Release 2]
glListBase

[New - Windows 95, OEM Service Release 2]

The glListBase function sets the display list base for glCallLists.

void glListBase(

GLuint base
);
Parameters

base

An integer offset that will be added to glCallLists offsets to generate display list names. Initial value is zero.

Remarks

The glListBase function specifies an array of offsets. Display list names are generated by adding base to each offset. Names that reference valid display lists are executed; others are ignored.

The following function retrieves information related to glListBase:

glGet with argument GL_LIST_BASE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glListBase was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glCallLists, glEnd


glLoadIdentity [New - Windows 95, OEM Service Release 2]
glLoadIdentity

[New - Windows 95, OEM Service Release 2]

The glLoadIdentity function replaces the current matrix with the identity matrix.

void glLoadIdentity(

void
);
Remarks

The glLoadIdentity function replaces the current matrix with the identity matrix. It is semantically equivalent to calling glLoadMatrix with the identity matrix

but in some cases it is more efficient.

The following functions retrieve information related to glLoadIdentity:

glGet with argument GL_MATRIX_MODE

glGet with argument GL_MODELVIEW_MATRIX

glGet with argument GL_PROJECTION_MATRIX

glGet with argument GL_TEXTURE_MATRIX

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glLoadIdentity was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glLoadMatrix, glMatrixMode, glMultMatrix, glPushMatrix


glLoadMatrix [New - Windows 95, OEM Service Release 2]
glLoadMatrixd, glLoadMatrixf

[New - Windows 95, OEM Service Release 2]

The glLoadMatrixd and glLoadMatrixf functions replace the current matrix with an arbitrary matrix.

void glLoadMatrixd(

const GLdouble *m
);
void glLoadMatrixf(

const GLfloat *m
);
Parameters

m

A pointer to a 4x4 matrix stored in column-major order as 16 consecutive values.

Remarks

The glLoadMatrix function replaces the current matrix with the one specified in m. The current matrix is the projection matrix, modelview matrix, or texture matrix, determined by the current matrix mode (see glMatrixMode).

The m parameter points to a 4x4 matrix of single- or double-precision floating-point values stored in column-major order. That is, the matrix is stored as follows:

The following functions retrieve information related to glLoadMatrix:

glGet with argument GL_MATRIX_MODE

glGet with argument GL_MODELVIEW_MATRIX

glGet with argument GL_PROJECTION_MATRIX

glGet with argument GL_TEXTURE_MATRIX

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glLoadMatrix was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glLoadIdentity, glMatrixMode, glMultMatrix, glPushMatrix


glLoadName [New - Windows 95, OEM Service Release 2]
glLoadName

[New - Windows 95, OEM Service Release 2]

The glLoadName function loads a name onto the name stack.

void glLoadName(

GLuint name
);
Parameters

name

A name that will replace the top value on the name stack.

Remarks

The glLoadName function causes name to replace the value on the top of the name stack, which is initially empty. The name stack is used during selection mode to allow sets of rendering commands to be uniquely identified. It consists of an ordered set of unsigned integers.

The name stack is always empty while the render mode is not GL_SELECT. Calls to glLoadName while the render mode is not GL_SELECT are ignored.

The following functions retrieve information related to glLoadName:

glGet with argument GL_NAME_STACK_DEPTH

glGet with argument GL_MAX_NAME_STACK_DEPTH

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glLoadName was called while the name stack was empty.
GL_INVALID_OPERATION	glLoadName was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glInitNames, glPushName, glRenderMode, glSelectBuffer


glLogicOp [New - Windows 95, OEM Service Release 2]
glLogicOp

[New - Windows 95, OEM Service Release 2]

The glLogicOp function specifies a logical pixel operation for color index rendering.

void glLogicOp(

GLenum opcode
);
Parameters

opcode

A symbolic constant that selects a logical operation. The following symbols are accepted:

Opcode	Resulting Value
GL_CLEAR	0
GL_SET	1
GL_COPY	s
GL_COPY_INVERTED	!s
GL_NOOP	d
GL_INVERT	!d
GL_AND	s & d
GL_NAND	!(s & d)
GL_OR	s | d
GL_NOR	!(s | d)
GL_XOR	s ^ d
GL_EQUIV	!(s ^ d)
GL_AND_REVERSE	s & !d
GL_AND_INVERTED	!s & d
GL_OR_REVERSE	s | !d
GL_OR_INVERTED	!s | d
Remarks

The glLogicOp function specifies a logical operation that, when enabled, is applied between the incoming color index and the color index at the corresponding location in the frame buffer. The logical operation is enabled or disabled with glEnable and glDisable using the symbolic constant GL_LOGIC_OP.

The opcode parameter is a symbolic constant chosen from the list below. In the explanation of the logical operations, s represents the incoming color index and d represents the index in the frame buffer. Standard C-language operators are used. As these bitwise operators suggest, the logical operation is applied independently to each bit pair of the source and destination indexes.

Logical pixel operations are not applied to RGBA color buffers.

When more than one color-index buffer is enabled for drawing, logical operations are done separately for each enabled buffer, using the contents of that buffer for the destination index (see glDrawBuffer).

The opcode parameter must be one of the 16 accepted values. Other values result in an error.

The following functions retrieve information related to glLogicOp:

glGet with argument GL_LOGIC_OP_MODE

glIsEnabled with argument GL_LOGIC_OP

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	opcode was not an accepted value.
GL_INVALID_OPERATION	glLogicOp was called between a call to glBegin and the corresponding call to glEnd.
See Also

glAlphaFunc, glBegin, glBlendFunc, glDrawBuffer, glEnable, glEnd, glIsEnabled, glStencilOp


glMap1 [New - Windows 95, OEM Service Release 2]
glMap1d, glMap1f

[New - Windows 95, OEM Service Release 2]

The glMap1d and glMap1f functions define a one-dimensional evaluator.

void glMap1d(

GLenum target,
GLdouble u1,
GLdouble u2,
GLint stride,
GLint order,
const GLdouble *points
);
void glMap1f(

GLenum target,
GLfloat u1,
GLfloat u2,
GLint stride,
GLint order,
const GLfloat *points
);
Parameters

target

The kind of values that are generated by the evaluator. Symbolic constants. The target parameter is a symbolic constant that indicates what kind of control points are provided in points, and what output is generated when the map is evaluated. It can assume one of nine predefined values:

GL_MAP1_VERTEX_3

Each control point is three floating-point values representing x, y, and z. Internal glVertex3 commands are generated when the map is evaluated.

GL_MAP1_VERTEX_4

Each control point is four floating-point values representing x, y, z, and w. Internal glVertex4 commands are generated when the map is evaluated.

GL_MAP1_INDEX

Each control point is a single floating-point value representing a color index. Internal glIndex commands are generated when the map is evaluated. However, the current index is not updated with the value of these glIndex commands.

GL_MAP1_COLOR_4

Each control point is four floating-point values representing red, green, blue, and alpha. Internal glColor4 commands are generated when the map is evaluated. However, the current color is not updated with the value of these glColor4 commands.

GL_MAP1_NORMAL

Each control point is three floating-point values representing the x, y, and z components of a normal vector. Internal glNormal commands are generated when the map is evaluated. However, the current normal is not updated with the value of these glNormal commands.

GL_MAP1_TEXTURE_COORD_1

Each control point is a single floating-point value representing the s texture coordinate. Internal glTexCoord1 commands are generated when the map is evaluated. However, the current texture coordinates are not updated with the value of these glTexCoord commands.

GL_MAP1_TEXTURE_COORD_2

Each control point is two floating-point values representing the s and t texture coordinates. Internal glTexCoord2 commands are generated when the map is evaluated. However, the current texture coordinates are not updated with the value of these glTexCoord commands.

GL_MAP1_TEXTURE_COORD_3

Each control point is three floating-point values representing the s, t, and r texture coordinates. Internal glTexCoord3 commands are generated when the map is evaluated. However, the current texture coordinates are not updated with the value of these glTexCoord commands.

GL_MAP1_TEXTURE_COORD_4

Each control point is four floating-point values representing the s, t, r, and q texture coordinates. Internal glTexCoord4 commands are generated when the map is evaluated. However, the current texture coordinates are not updated with the value of these glTexCoord commands.

u1, u2

A linear mapping of u, as presented to glEvalCoord1, to û, the variable that is evaluated by the equations specified by this command.

stride

The number of floats or doubles between the beginning of one control point and the beginning of the next one in the data structure referenced in points. This allows control points to be embedded in arbitrary data structures. The only constraint is that the values for a particular control point must occupy contiguous memory locations.

order

The number of control points. Must be positive.

points

A pointer to the array of control points.

Remarks

Evaluators provide a way to use polynomial or rational polynomial mapping to produce vertices, normals, texture coordinates, and colors. The values produced by an evaluator are sent to further stages of OpenGL processing just as if they had been presented using glVertex, glNormal, glTexCoord, and glColor commands, except that the generated values do not update the current normal, texture coordinates, or color.

All polynomial or rational polynomial splines of any degree (up to the maximum degree supported by the OpenGL implementation) can be described using evaluators. These include almost all splines used in computer graphics, including B-splines, Bezier curves, Hermite splines, and so on.

Evaluators define curves based on Bernstein polynomials. Define p(û) as

where R (i)  is a control point and [image] (û) is the ith Bernstein polynomial of degree n (order = n + 1):

Recall that

The glMap1 function is used to define the basis and to specify what kind of values are produced. Once defined, a map can be enabled and disabled by calling glEnable and glDisable with the map name, one of the nine predefined values for target described above. The glEvalCoord1 function evaluates the one-dimensional maps that are enabled. When glEvalCoord1 presents a value u, the Bernstein functions are evaluated using û, where

The stride, order, and points parameters define the array addressing for accessing the control points. The points parameter is the location of the first control point, which occupies one, two, three, or four contiguous memory locations, depending on which map is being defined. The order parameter is the number of control points in the array. The stride parameter tells how many float or double locations to advance the internal memory pointer to reach the next control point.

As is the case with all OpenGL commands that accept pointers to data, it is as if the contents of points were copied by glMap1 before it returned. Changes to the contents of points have no effect after glMap1 is called.

The following functions retrieve information related to glMap1:

glGet with argument GL_MAX_EVAL_ORDER

glGetMap

glIsEnabled with argument GL_MAP1_VERTEX_3

glIsEnabled with argument GL_MAP1_VERTEX_4

glIsEnabled with argument GL_MAP1_INDEX

glIsEnabled with argument GL_MAP1_COLOR_4

glIsEnabled with argument GL_MAP1_NORMAL

glIsEnabled with argument GL_MAP1_TEXTURE_COORD_1

glIsEnabled with argument GL_MAP1_TEXTURE_COORD_2

glIsEnabled with argument GL_MAP1_TEXTURE_COORD_3

glIsEnabled with argument GL_MAP1_TEXTURE_COORD_4

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target was not an accepted value.
GL_INVALID_VALUE	u1 was equal to u2.
GL_INVALID_VALUE	stride was less than the number of values in a control point.
GL_INVALID_VALUE	order was less than one or greater than GL_MAX_EVAL_ORDER.
GL_INVALID_OPERATION	glMap1 was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glColor, glEnable, glEnd, glEvalCoord, glEvalMesh, glEvalPoint, glMap2, glMapGrid, glNormal, glTexCoord, glVertex


glMap2 [New - Windows 95, OEM Service Release 2]
glMap2d, glMap2f

[New - Windows 95, OEM Service Release 2]

The glMap2d and glMap2f functions define a two-dimensional evaluator.

void glMap2d(

GLenum target,
GLdouble u1,
GLdouble u2,
GLint ustride,
GLint uorder,
GLdouble v1,
GLdouble v2,
GLint vstride,
GLint vorder,
const GLdouble *points
);
void glMap2f(

GLenum target,
GLfloat u1,
GLfloat u2,
GLint ustride,
GLint uorder,
GLfloat v1,
GLfloat v2,
GLint vstride,
GLint vorder,
const GLfloat *points
);
Parameters

target

The kind of values that are generated by the evaluator. The following symbolic constants are accepted:

GL_MAP2_VERTEX_3

Each control point is three floating-point values representing x, y, and z. Internal glVertex3 commands are generated when the map is evaluated.

GL_MAP2_VERTEX_4

Each control point is four floating-point values representing x, y, z, and w. Internal glVertex4 commands are generated when the map is evaluated.

GL_MAP2_INDEX

Each control point is a single floating-point value representing a color index. Internal glIndex commands are generated when the map is evaluated. The current index is not updated with the value of these glIndex commands, however.

GL_MAP2_COLOR_4

Each control point is four floating-point values representing red, green, blue, and alpha. Internal glColor4 commands are generated when the map is evaluated. The current color is not updated with the value of these glColor4 commands, however.

GL_MAP2_NORMAL

Each control point is three floating-point values representing the x, y, and z components of a normal vector. Internal glNormal commands are generated when the map is evaluated. The current normal is not updated with the value of these glNormal commands, however.

GL_MAP2_TEXTURE_COORD_1

Each control point is a single floating-point value representing the s texture coordinate. Internal glTexCoord1 commands are generated when the map is evaluated. The current texture coordinates are not updated with the value of these glTexCoord commands, however.

GL_MAP2_TEXTURE_COORD_2

Each control point is two floating-point values representing the s and t texture coordinates. Internal glTexCoord2 commands are generated when the map is evaluated. The current texture coordinates are not updated with the value of these glTexCoord commands, however.

GL_MAP2_TEXTURE_COORD_3

Each control point is three floating-point values representing the s, t, and r texture coordinates. Internal glTexCoord3 commands are generated when the map is evaluated. The current texture coordinates are not updated with the value of these glTexCoord commands, however.

GL_MAP2_TEXTURE_COORD_4

Each control point is four floating-point values representing the s, t, r, and q texture coordinates. Internal glTexCoord4 commands are generated when the map is evaluated. The current texture coordinates are not updated with the value of these glTexCoord commands, however.

u1, u2

A linear mapping of u, as presented to glEvalCoord2, to û, one of the two variables that is evaluated by the equations specified by this command.

ustride

The number of floats or doubles between the beginning of control point R (ij)  and the beginning of control point R ((i+1)j) , where i and j are the u and v control point indexes, respectively. This allows control points to be embedded in arbitrary data structures. The only constraint is that the values for a particular control point must occupy contiguous memory locations.

uorder

The dimension of the control point array in the u-axis. Must be positive.

v1, v2

A linear mapping of v, as presented to glEvalCoord2, to [image], one of the two variables that is evaluated by the equations specified by this command.

vstride

The number of floats or doubles between the beginning of control point R (ij)  and the beginning of control point R (i(j+1)) , where i and j are the u and v control point indexes, respectively. This allows control points to be embedded in arbitrary data structures. The only constraint is that the values for a particular control point must occupy contiguous memory locations.

vorder

The dimension of the control point array in the v-axis. Must be positive.

points

A pointer to the array of control points.

Remarks

Evaluators provide a way to use polynomial or rational polynomial mapping to produce vertices, normals, texture coordinates, and colors. The values produced by an evaluator are sent on to further stages of OpenGL processing just as if they had been presented using glVertex, glNormal, glTexCoord, and glColor commands, except that the generated values do not update the current normal, texture coordinates, or color.

All polynomial or rational polynomial splines of any degree (up to the maximum degree supported by the OpenGL implementation) can be described using evaluators. These include almost all surfaces used in computer graphics, including B-spline surfaces, NURBS surfaces, Bezier surfaces, and so on.

Evaluators define surfaces based on bivariate Bernstein polynomials. Define p(û, [image]) as

where R (ij)  is a control point, [image] (û) is the ith Bernstein polynomial of degree

n (uorder = n + 1)

and ( [image]) is the jth Bernstein polynomial of degree m (vorder = m + 1)

Recall that

The glMap2 function is used to define the basis and to specify what kind of values are produced. Once defined, a map can be enabled and disabled by calling glEnable and glDisable with the map name, one of the nine predefined values for target, described above. When glEvalCoord2 presents values u and v, the bivariate Bernstein polynomials are evaluated using û and [image], where

The target parameter is a symbolic constant that indicates what kind of control points are provided in points, and what output is generated when the map is evaluated.

The ustride, uorder, vstride, vorder, and points parameters define the array addressing for accessing the control points. The points parameter is the location of the first control point, which occupies one, two, three, or four contiguous memory locations, depending on which map is being defined. There are uorderxvorder control points in the array. The ustride parameter tells how many float or double locations are skipped to advance the internal memory pointer from control point R (ij)  to control point R ((i+1)j) . The vstride parameter tells how many float or double locations are skipped to advance the internal memory pointer from control point R (ij)  to control point R (i(j+1)) .

As is the case with all OpenGL commands that accept pointers to data, it is as if the contents of points were copied by glMap2 before it returned. Changes to the contents of points have no effect after glMap2 is called.

The following functions retrieve information related to glMap2:

glGet with argument GL_MAX_EVAL_ORDER

glGetMap

glIsEnabled with argument GL_MAP2_VERTEX_3

glIsEnabled with argument GL_MAP2_VERTEX_4

glIsEnabled with argument GL_MAP2_INDEX

glIsEnabled with argument GL_MAP2_COLOR_4

glIsEnabled with argument GL_MAP2_NORMAL

glIsEnabled with argument GL_MAP2_TEXTURE_COORD_1

glIsEnabled with argument GL_MAP2_TEXTURE_COORD_2

glIsEnabled with argument GL_MAP2_TEXTURE_COORD_3

glIsEnabled with argument GL_MAP2_TEXTURE_COORD_4

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target was not an accepted value.
GL_INVALID_VALUE	u1 was equal to u2, or if v1 was equal to v2.
GL_INVALID_VALUE	either ustride or vstride was less than the number of values in a control point.
GL_INVALID_VALUE	either uorder or vorder was less than one or greater than GL_MAX_EVAL_ORDER.
GL_INVALID_OPERATION	glMap2 was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glColor, glEnable, glEnd, glEvalCoord, glEvalMesh, glEvalPoint, glMap1, glMapGrid, glNormal, glTexCoord, glVertex


glMapGrid [New - Windows 95, OEM Service Release 2]
glMapGrid1d, glMapGrid1f, glMapGrid2d, glMapGrid2f

[New - Windows 95, OEM Service Release 2]

These functions define a one- or two-dimensional mesh.

void glMapGrid1d(

GLint un,
GLdouble u1,
GLdouble u2
);
void glMapGrid1f(

GLint un,
GLfloat u1,
GLfloat u2
);
void glMapGrid2d(

GLint un,
GLdouble u1,
GLdouble u2,
GLint vn,
GLdouble v1,
GLdouble v2
);
void glMapGrid2f(

GLint un,
GLfloat u1,
GLfloat u2,
GLint vn,
GLfloat v1,
GLfloat v2
);
Parameters

un

The number of partitions in the grid range interval [u1, u2]. Must be positive.

u1, u2

The mappings for integer grid domain values i = 0 and i = un.

vn

The number of partitions in the grid range interval [v1, v2] (glMapGrid2 only).

v1, v2

The mappings for integer grid domain values j = 0 and j = vn (glMapGrid2 only).

Remarks

The glMapGrid and glEvalMesh functions are used in tandem to efficiently generate and evaluate a series of evenly spaced map domain values. The glEvalMesh function steps through the integer domain of a one- or two-dimensional grid, whose range is the domain of the evaluation maps specified by glMap1 and glMap2.

The glMapGrid1 and glMapGrid2 functions specify the linear grid mappings between the i (or i and j) integer grid coordinates, to the u (or u and v) floating-point evaluation map coordinates. See glMap1 and glMap2 for details of how u and v coordinates are evaluated.

The glMapGrid1 function specifies a single linear mapping such that integer grid coordinate 0 maps exactly to u1, and integer grid coordinate un maps exactly to u2. All other integer grid coordinates i are mapped such that:

u = i(u2 − u1)/un + u1

The glMapGrid2 function specifies two such linear mappings. One maps integer grid coordinate i = 0 exactly to u1, and integer grid coordinate i = un exactly to u2. The other maps integer grid coordinate j = 0 exactly to v1, and integer grid coordinate j = vn exactly to v2. Other integer grid coordinates i and j are mapped such that

u = i(u2 − u1)/un + u1

v = j (v2 − v1)/vn + v1

The mappings specified by glMapGrid are used identically by glEvalMesh and glEvalPoint.

The following functions retrieve information related to glMapGrid:

glGet with argument GL_MAP1_GRID_DOMAIN

glGet with argument GL_MAP2_GRID_DOMAIN

glGet with argument GL_MAP1_GRID_SEGMENTS

glGet with argument GL_MAP2_GRID_SEGMENTS

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	Either un or vn was not positive.
GL_INVALID_OPERATION	glMapGrid was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glEvalCoord, glEvalMesh, glEvalPoint, glMap1, glMap2


glMaterial [New - Windows 95, OEM Service Release 2]
glMaterialf, glMateriali, glMaterialfv, glMaterialiv

[New - Windows 95, OEM Service Release 2]

These functions specify material parameters for the lighting model.

void glMaterialf(

GLenum face,
GLenum pname,
GLfloat param
);
void glMateriali(

GLenum face,
GLenum pname,
GLint param
);
Parameters

face

The face or faces that are being updated. Must be one of GL_FRONT, GL_BACK, or GL_FRONT_AND_BACK.

pname

The single-valued material parameter of the face or faces being updated. Must be GL_SHININESS.

param

The value that parameter GL_SHININESS will be set to.

void glMaterialfv(

GLenum face,
GLenum pname,
const GLfloat *params
);
void glMaterialiv(

GLenum face,
GLenum pname,
const GLint *params
);
Parameters

face

The face or faces that are being updated. Must be one of GL_FRONT, GL_BACK, or GL_FRONT_AND_BACK.

pname

The material parameter of the face or faces being updated. The parameters that can be specified using glMaterial, and their interpretations by the lighting equation, are as follows:

GL_AMBIENT

The params parameter contains four integer or floating-point values that specify the ambient RGBA reflectance of the material. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to −1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The default ambient reflectance for both front- and back-facing materials is (0.2, 0.2, 0.2, 1.0).

GL_DIFFUSE

The params parameter contains four integer or floating-point values that specify the diffuse RGBA reflectance of the material. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to −1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The default diffuse reflectance for both front- and back-facing materials is (0.8, 0.8, 0.8, 1.0).

GL_SPECULAR

The params parameter contains four integer or floating-point values that specify the specular RGBA reflectance of the material. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to −1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The default specular reflectance for both front- and back-facing materials is (0.0, 0.0, 0.0, 1.0).

GL_EMISSION

The params parameter contains four integer or floating-point values that specify the RGBA emitted light intensity of the material. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to −1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The default emission intensity for both front- and back-facing materials is (0.0, 0.0, 0.0, 1.0).

GL_SHININESS

The params parameter is a single integer or floating-point value that specifies the RGBA specular exponent of the material. Integer and floating-point values are mapped directly. Only values in the range [0,128] are accepted. The default specular exponent for both front- and back-facing materials is 0.

GL_AMBIENT_AND_DIFFUSE

Equivalent to calling glMaterial twice with the same parameter values, once with GL_AMBIENT and once with GL_DIFFUSE.

GL_COLOR_INDEXES

The params parameter contains three integer or floating-point values specifying the color indexes for ambient, diffuse, and specular lighting. These three values, and GL_SHININESS, are the only material values used by the color-index mode lighting equation. Refer to glLightModel for a discussion of color-index lighting.

params

A pointer to the value or values to which pname will be set.

Remarks

The glMaterial function assigns values to material parameters. There are two matched sets of material parameters. One, the front-facing set, is used to shade points, lines, bitmaps, and all polygons (when two-sided lighting is disabled), or just front-facing polygons (when two-sided lighting is enabled). The other set, back-facing, is used to shade back-facing polygons only when two-sided lighting is enabled. Refer to glLightModel for details concerning one- and two-sided lighting calculations.

The glMaterial function takes three arguments. The first, face, specifies whether the GL_FRONT materials, the GL_BACK materials, or both GL_FRONT_AND_BACK materials will be modified. The second, pname, specifies which of several parameters in one or both sets will be modified. The third, params, specifies what value or values will be assigned to the specified parameter.

Material parameters are used in the lighting equation that is optionally applied to each vertex. The equation is discussed in glLightModel.

The material parameters can be updated at any time. In particular, glMaterial can be called between a call to glBegin and the corresponding call to glEnd. If only a single material parameter is to be changed per vertex, however, glColorMaterial is preferred over glMaterial.

The following function retrieves information related to glMaterial:

glGetMaterial

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	Either face or pname was not an accepted value.
GL_INVALID_VALUE	A specular exponent outside the range [0,128] was specified.
See Also

glColorMaterial, glLight, glLightModel


glMatrixMode [New - Windows 95, OEM Service Release 2]
glMatrixMode

[New - Windows 95, OEM Service Release 2]

The glMatrixMode function specifies which matrix is the current matrix.

void glMatrixMode(

GLenum mode
);
Parameters

mode

The matrix stack that is the target for subsequent matrix operations. The mode parameter can assume one of three values:

GL_MODELVIEW

Applies subsequent matrix operations to the modelview matrix stack.

GL_PROJECTION

Applies subsequent matrix operations to the projection matrix stack.

GL_TEXTURE

Applies subsequent matrix operations to the texture matrix stack.

Remarks

The glMatrixMode function sets the current matrix mode.

The following function retrieves information related to glMatrixMode:

glGet with argument GL_MATRIX_MODE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	mode was not an accepted value.
GL_INVALID_OPERATION	glMatrixMode was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glLoadMatrix, glPushMatrix


glMultMatrix [New - Windows 95, OEM Service Release 2]
glMultMatrixd, glMultMatrixf

[New - Windows 95, OEM Service Release 2]

The glMultMatrixd and glMultMatrixf functions multiply the current matrix by an arbitrary matrix.

void glMultMatrixd(

const GLdouble *m
);
void glMultMatrixf(

const GLfloat *m
);
Parameters

m

A pointer to a 4x4 matrix stored in column-major order as 16 consecutive values.

Remarks

The glMultMatrix function multiplies the current matrix by the one specified in m. That is, if M is the current matrix and T is the matrix passed to glMultMatrix, then M is replaced with M • T.

The current matrix is the projection matrix, modelview matrix, or texture matrix, determined by the current matrix mode (see glMatrixMode).

The m parameter points to a 4x4 matrix of single- or double-precision floating-point values stored in column-major order. That is, the matrix is stored as:

The following functions retrieve information related to glMultMatrix:

glGet with argument GL_MATRIX_MODE

glGet with argument GL_MODELVIEW_MATRIX

glGet with argument GL_PROJECTION_MATRIX

glGet with argument GL_TEXTURE_MATRIX

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glMultMatrix was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glLoadIdentity, glLoadMatrix, glMatrixMode, glPushMatrix


glNewList, glEndList [New - Windows 95, OEM Service Release 2]
glNewList, glEndList

[New - Windows 95, OEM Service Release 2]

The glNewList and glEndList functions create or replace a display list.

void glNewList(

GLuint list,
GLenum mode
);
void glEndList(

void
);
Parameters

list

The display list name.

mode

The compilation mode. The following values are accepted:

GL_COMPILE

Commands are merely compiled.

GL_COMPILE_AND_EXECUTE

Commands are executed as they are compiled into the display list.

Remarks

Display lists are groups of OpenGL commands that have been stored for subsequent execution. The display lists are created with glNewList. All subsequent commands are placed in the display list, in the order issued, until glEndList is called.

The glNewList function has two parameters. The first parameter, list, is a positive integer that becomes the unique name for the display list. Names can be created and reserved with glGenLists and tested for uniqueness with glIsList. The second parameter, mode, is a symbolic constant that can assume one of the two preceding values.

Certain commands are not compiled into the display list, but are executed immediately, regardless of the display list mode. These commands are glIsList, glGenLists, glDeleteLists, glFeedbackBuffer, glSelectBuffer, glRenderMode, glReadPixels, glPixelStore, glFlush, glFinish, glIsEnabled, and all of the glGet routines.

When the glNewList function is encountered, the display list definition is completed by associating the list with the unique name list (specified in the glNewList command). If a display list with name list already exists, it is replaced only when glEndList is called.

The glCallList and glCallLists functions can be entered into display lists. The commands in the display list or lists executed by glCallList or glCallLists are not included in the display list being created, even if the list creation mode is GL_COMPILE_AND_EXECUTE.

The following function retrieves information related to glNewList:

glGet with argument GL_MATRIX_MODE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	list was zero.
GL_INVALID_ENUM	mode was not an accepted value.
GL_INVALID_OPERATION	glEndList was called without a preceding glNewList, or if glNewList was called while a display list was being defined.
GL_INVALID_OPERATION	glNewList was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glCallList, glCallLists, glDeleteLists, glEnd, glGenLists, glIsList


glNormal [New - Windows 95, OEM Service Release 2]
glNormal

[New - Windows 95, OEM Service Release 2]

glNormal3b, glNormal3d, glNormal3f, glNormal3i, glNormal3s, glNormal3bv, glNormal3dv, glNormal3fv, glNormal3iv, glNormal3sv

These functions set the current normal vector.

void glNormal3b(

GLbyte nx,
GLbyte ny,
GLbyte nz
);
void glNormal3d(

GLdouble nx,
GLdouble ny,
GLdouble nz
);
void glNormal3f(

GLfloat nx,
GLfloat ny,
GLfloat nz
);
void glNormal3i(

GLint nx,
GLint ny,
GLint nz
);
void glNormal3s(

GLshort nx,
GLshort ny,
GLshort nz
);
Parameters

nx, ny, nz

The x, y, and z coordinates of the new current normal. The initial value of the current normal is (0,0,1).

void glNormal3bv(

const GLbyte *v
);
void glNormal3dv(

const GLdouble *v
);
void glNormal3fv(

const GLfloat *v
);
void glNormal3iv(

const GLint *v
);
void glNormal3sv(

const GLshort *v
);
Parameters

v

A pointer to an array of three elements: the x, y, and z coordinates of the new current normal.

Remarks

The current normal is set to the given coordinates whenever glNormal is issued. Byte, short, or integer arguments are converted to floating-point format with a linear mapping that maps the most positive representable integer value to 1.0, and the most negative representable integer value to −1.0.

Normals specified with glNormal need not have unit length. If normalization is enabled, then normals specified with glNormal are normalized after transformation. Normalization is controlled using glEnable and glDisable with the argument GL_NORMALIZE. By default, normalization is disabled.

The current normal can be updated at any time. In particular, glNormal can be called between a call to glBegin and the corresponding call to glEnd.

The following functions retrieve information related to glNormal:

glGet with argument GL_CURRENT_NORMAL

glIsEnable with argument GL_NORMALIZE

See Also

glBegin, glColor, glEnd, glIndex, glTexCoord, glVertex


glNormalPointer [New - Windows 95, OEM Service Release 2]
glNormalPointer

[New - Windows 95, OEM Service Release 2]

The glNormalPointer function defines an array of normals.

void glNormalPointer(

GLenum type,
GLsizei stride,
GLsizei count,
const GLvoid *pointer
);
Parameters

type

The data type of each coordinate in the array using the following symbolic constants: GL_BYTE, GL_SHORT, GL_INT, GL_FLOAT, and GL_DOUBLE.

stride

The byte offset between consecutive normals. When stride is zero, the normals are tightly packed in the array.

count

The number of normals, counting from the first, that are static.

pointer

A pointer to the first normal in the array.

Remarks

The glNormalPointer function specifies the location and data of an array of normals to use when rendering. The type parameter specifies the data type of each normal coordinate. The stride parameter determines the byte offset from one normal to the next, enabling the packing of vertices and attributes in a single array or storage in separate arrays. In some implementations storing the vertices and attributes in a single array can be more efficient than using separate arrays. Starting from the first normal element, count indicates the total number of static elements. Your application can modify static elements, but once the elements are modified, the application must explicitly specify the array again before using the array for any rendering. Non-static array elements are not accessed until you call glDrawArrays or glArrayElement.

A normal array is enabled when you specify the GL_NORMAL_ARRAY constant with glEnableClientState. When enabled, glDrawArrays and glArrayElement use the normal array. By default the normal array is disabled.

You cannot include glNormalPointer in display lists.

When you specify a normal array using glNormalPointer, the values of all the function’s normal array parameters are saved in a client-side state and static array elements can be cached. Because the normal array parameters are saved in a client-side state, their values are not saved or restored by glPushAttrib and glPopAttrib.

Although no error is generated when you call glNormalPointer within glBegin and glEnd pairs, the results are undefined.

The following functions are associated with glNormalPointer:

glGet with argument GL_NORMAL_ARRAY_STRIDE

glGet with argument GL_NORMAL_ARRAY_COUNT

glGet with argument GL_NORMAL_ARRAY_TYPE

glGetPointerv with argument GL_NORMAL_ARRAY_POINTER

glIsEnabled with argument GL_NORMAL_ARRAY

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	type was not an accepted value.
GL_INVALID_VALUE	stride or count was negative.
See Also

glArrayElement, glColorPointer, glDrawArrays, glEdgeFlagPointer, glGetPointerv, glIndexPointer, glIsEnabled, glTexCoordPointer, glVertexPointer, glGetString


glOrtho [New - Windows 95, OEM Service Release 2]
glOrtho

[New - Windows 95, OEM Service Release 2]

The glOrtho function multiplies the current matrix by an orthographic matrix.

void glOrtho(

GLdouble left,
GLdouble right,
GLdouble bottom,
GLdouble top,
GLdouble near,
GLdouble far
);
Parameters

left, right

The coordinates for the left and right vertical clipping planes.

bottom, top

The coordinates for the bottom and top horizontal clipping planes.

near, far

The distances to the nearer and farther depth clipping planes. These distances are negative if the plane is to be behind the viewer.

Remarks

The glOrtho function describes a perspective matrix that produces a parallel projection. The (left, bottom, − near) and (right, top, − near) parameters specify the points on the near clipping plane that are mapped to the lower-left and upper-right corners of the window, respectively, assuming that the eye is located at (0, 0, 0). The −far parameter specifies the location of the far clipping plane. Both near and far can be either positive or negative. The corresponding matrix is

where

The current matrix is multiplied by this matrix with the result replacing the current matrix. That is, if M is the current matrix and O is the ortho matrix, then M is replaced with M • O.

Use glPushMatrix and glPopMatrix to save and restore the current matrix stack.

The following functions retrieve information related to glOrtho:

glGet with argument GL_MATRIX_MODE

glGet with argument GL_MODELVIEW_MATRIX

glGet with argument GL_PROJECTION_MATRIX

glGet with argument GL_TEXTURE_MATRIX

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glOrtho was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glFrustum, glMatrixMode, glMultMatrix, glPushMatrix, glViewport


glPassThrough [New - Windows 95, OEM Service Release 2]
glPassThrough

[New - Windows 95, OEM Service Release 2]

The glPassThrough function places a marker in the feedback buffer.

void glPassThrough(

GLfloat token
);
Parameters

token

A marker value to be placed in the feedback buffer. It is indicated with the following unique identifying value:

GL_PASS_THROUGH_TOKEN

The order of glPassThrough commands with respect to the specification of graphics primitives is maintained.

Remarks

Feedback is an OpenGL render mode. The mode is selected by calling glRenderMode with GL_FEEDBACK. When OpenGL is in feedback mode, no pixels are produced by rasterization. Instead, information about primitives that would have been rasterized is fed back to the application using OpenGL. See glFeedbackBuffer for a description of the feedback buffer and the values in it.

The glPassThrough function inserts a user-defined marker in the feedback buffer when it is executed in feedback mode. The token parameter is returned as if it were a primitive.

The glPassThrough function is ignored if OpenGL is not in feedback mode.

The following function retrieves information related to glPassThrough:

glGet with argument GL_RENDER_MODE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glPassThrough was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glFeedbackBuffer, glRenderMode


glPixelMap [New - Windows 95, OEM Service Release 2]
glPixelMapfv, glPixelMapuiv, glPixelMapusv

[New - Windows 95, OEM Service Release 2]

These functions set up pixel transfer maps.

void glPixelMapfv(

GLenum map,
GLint mapsize,
const GLfloat *values
);
void glPixelMapuiv(

GLenum map,
GLint mapsize,
const GLuint *values
);
void glPixelMapusv(

GLenum map,
GLint mapsize,
const GLushort *values
);
Parameters

map

A symbolic map name. The ten maps are as follows:

GL_PIXEL_MAP_I_TO_I

Maps color indexes to color indexes.

GL_PIXEL_MAP_S_TO_S

Maps stencil indexes to stencil indexes.

GL_PIXEL_MAP_I_TO_R

Maps color indexes to red components.

GL_PIXEL_MAP_I_TO_G

Maps color indexes to green components.

GL_PIXEL_MAP_I_TO_B

Maps color indexes to blue components.

GL_PIXEL_MAP_I_TO_A

Maps color indexes to alpha components.

GL_PIXEL_MAP_R_TO_R

Maps red components to red components.

GL_PIXEL_MAP_G_TO_G

Maps green components to green components.

GL_PIXEL_MAP_B_TO_B

Maps blue components to blue components.

GL_PIXEL_MAP_A_TO_A

Maps alpha components to alpha components.

mapsize

The size of the map being defined.

values

An array of mapsize values.

Remarks

The glPixelMap function sets up translation tables, or maps, used by glDrawPixels, glReadPixels, glCopyPixels, glTexImage1D, and glTexImage2D. Use of these maps is described completely in the glPixelTransfer topic, and partly in the topics for the pixel and texture image commands. Only the specification of the maps is described in this topic.

The map parameter is a symbolic map name, indicating one of ten maps to set. The mapsize parameter specifies the number of entries in the map, and values is a pointer to an array of mapsize map values.

The entries in a map can be specified as single-precision floating-point numbers, unsigned short integers, or unsigned long integers. Maps that store color component values (all but GL_PIXEL_MAP_I_TO_I and GL_PIXEL_MAP_S_TO_S) retain their values in floating-point format, with unspecified mantissa and exponent sizes. Floating-point values specified by glPixelMapfv are converted directly to the internal floating-point format of these maps, and then clamped to the range [0,1]. Unsigned integer values specified by glPixelMapusv and glPixelMapuiv are converted linearly such that the largest representable integer maps to 1.0, and zero maps to 0.0.

Maps that store indexes, GL_PIXEL_MAP_I_TO_I and GL_PIXEL_MAP_S_TO_S, retain their values in fixed-point format, with an unspecified number of bits to the right of the binary point. Floating-point values specified by glPixelMapfv are converted directly to the internal fixed-point format of these maps. Unsigned integer values specified by glPixelMapusv and glPixelMapuiv specify integer values, with all zeros to the right of the binary point.

The following table shows the initial sizes and values for each of the maps. Maps that are indexed by either color or stencil indexes must have mapsize = 2^n for some n or results are undefined. The maximum allowable size for each map depends on the implementation and can be determined by calling glGet with argument GL_MAX_PIXEL_MAP_TABLE. The single maximum applies to all maps, and it is at least 32.

GL_PIXEL_MAP_I_TO_I

Lookup Index:	color index
Lookup Value:	color index
Initial Size:	1
Initial Value:	0.0
GL_PIXEL_MAP_S_TO_S

Lookup Index:	stencil index
Lookup Value:	stencil index
Initial Size:	1
Initial Value:	0.0
GL_PIXEL_MAP_I_TO_R

Lookup Index:	color index
Lookup Value:	R
Initial Size:	1
Initial Value:	0.0
GL_PIXEL_MAP_I_TO_G

Lookup Index:	color index
Lookup Value:	G
Initial Size:	1
Initial Value:	0.0
GL_PIXEL_MAP_I_TO_B

Lookup Index:	color index
Lookup Value:	B
Initial Size:	1
Initial Value:	0.0
GL_PIXEL_MAP_I_TO_A

Lookup Index:	color index
Lookup Value:	A
Initial Size:	1
Initial Value:	0.0
GL_PIXEL_MAP_R_TO_R

Lookup Index:	R
Lookup Value:	R
Initial Size:	1
Initial Value:	0.0
GL_PIXEL_MAP_G_TO_G

Lookup Index:	G
Lookup Value:	G
Initial Size:	1
Initial Value:	0.0
GL_PIXEL_MAP_B_TO_B

Lookup Index:	B
Lookup Value:	B
Initial Size:	1
Initial Value:	0.0
GL_PIXEL_MAP_A_TO_A

Lookup Index:	A
Lookup Value:	A
Initial Size:	1
Initial Value:	0.0
The following functions retrieve information related to glPixelMap:

glGet with argument GL_PIXEL_MAP_I_TO_I_SIZE

glGet with argument GL_PIXEL_MAP_S_TO_S_SIZE

glGet with argument GL_PIXEL_MAP_I_TO_R_SIZE

glGet with argument GL_PIXEL_MAP_I_TO_G_SIZE

glGet with argument GL_PIXEL_MAP_I_TO_B_SIZE

glGet with argument GL_PIXEL_MAP_I_TO_A_SIZE

glGet with argument GL_PIXEL_MAP_R_TO_R_SIZE

glGet with argument GL_PIXEL_MAP_G_TO_G_SIZE

glGet with argument GL_PIXEL_MAP_B_TO_B_SIZE

glGet with argument GL_PIXEL_MAP_A_TO_A_SIZE

glGet with argument GL_MAX_PIXEL_MAP_TABLE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	map was not an accepted value.
GL_INVALID_VALUE	mapsize was negative or larger than GL_MAX_PIXEL_MAP_TABLE.
GL_INVALID_VALUE	map was GL_PIXEL_MAP_I_TO_I, GL_PIXEL_MAP_S_TO_S, GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, or GL_PIXEL_MAP_I_TO_A, and mapsize was not a power of two.
GL_INVALID_OPERATION	glPixelMap was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glCopyPixels, glDrawPixels, glEnd, glPixelStore, glPixelTransfer, glReadPixels, glTexImage1D, glTexImage2D


glPixelStore [New - Windows 95, OEM Service Release 2]
glPixelStoref, glPixelStorei

[New - Windows 95, OEM Service Release 2]

The glPixelStoref and glPixelStorei functions set pixel storage modes.

void glPixelStoref(

GLenum pname,
GLfloat param
);
void glPixelStorei(

GLenum pname,
GLint param
);
Parameters

pname

The symbolic name of the parameter to be set. Six of the twelve storage parameters affect how pixel data is returned to client memory, and are therefore significant only for glReadPixels commands. They are as follows:

GL_PACK_SWAP_BYTES

If true, byte ordering for multibyte color components, depth components, color indexes, or stencil indexes is reversed. That is, if a four-byte component is made up of bytes b (0) , b (1) , b (2) , b (3) , it is stored in memory as b (3) , b (2) , b (1) , b (0)  if GL_PACK_SWAP_BYTES is true. GL_PACK_SWAP_BYTES has no effect on the memory order of components within a pixel, only on the order of bytes within components or indexes. For example, the three components of a GL_RGB format pixel are always stored with red first, green second, and blue third, regardless of the value of GL_PACK_SWAP_BYTES.

GL_PACK_LSB_FIRST

If true, bits are ordered within a byte from least significant to most significant; otherwise, the first bit in each byte is the most significant one. This parameter is significant for bitmap data only.

GL_PACK_ROW_LENGTH

If greater than zero, GL_PACK_ROW_LENGTH defines the number of pixels in a row. If the first pixel of a row is placed at location p in memory, then the location of the first pixel of the next row is obtained by skipping

components or indexes, where n is the number of components or indexes in a pixel, l is the number of pixels in a row (GL_PACK_ROW_LENGTH if it is greater than zero, the width argument to the pixel routine otherwise), a is the value of GL_PACK_ALIGNMENT, and s is the size, in bytes, of a single component (if a < s, then it is as if a = s). In the case of 1-bit values, the location of the next row is obtained by skipping

components or indexes.

The word component in this description refers to the nonindex values red, green, blue, alpha, and depth. Storage format GL_RGB, for example, has three components per pixel: first red, then green, and finally blue.

GL_PACK_SKIP_PIXELS and GL_PACK_SKIP_ROWS

These values are provided as a convenience to the programmer; they provide no functionality that cannot be duplicated simply by incrementing the pointer passed to glReadPixels. Setting GL_PACK_SKIP_PIXELS to i is equivalent to incrementing the pointer by i n components or indexes, where n is the number of components or indexes in each pixel. Setting GL_PACK_SKIP_ROWS to j is equivalent to incrementing the pointer by j k components or indexes, where k is the number of components or indexes per row, as computed above in the GL_PACK_ROW_LENGTH section.

GL_PACK_ALIGNMENT

Specifies the alignment requirements for the start of each pixel row in memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to even-numbered bytes), 4 (word alignment), and 8 (rows start on double-word boundaries).

The other six of the twelve storage parameters affect how pixel data is read from client memory. These values are significant for glDrawPixels, glTexImage1D, glTexImage2D, glBitmap, and glPolygonStipple. They are as follows:

GL_UNPACK_SWAP_BYTES

If true, byte ordering for multibyte color components, depth components, color indexes, or stencil indexes is reversed. That is, if a four-byte component is made up of bytes b (0) , b (1) , b (2) , b (3) , it is taken from memory as b (3) , b (2) , b (1) , b (0)  if GL_UNPACK_SWAP_BYTES is true. GL_UNPACK_SWAP_BYTES has no effect on the memory order of components within a pixel, only on the order of bytes within components or indexes. For example, the three components of a GL_RGB format pixel are always stored with red first, green second, and blue third, regardless of the value of GL_UNPACK_SWAP_BYTES.

GL_UNPACK_LSB_FIRST

If true, bits are ordered within a byte from least significant to most significant; otherwise, the first bit in each byte is the most significant one. This is significant for bitmap data only.

GL_UNPACK_ROW_LENGTH

If greater than zero, GL_UNPACK_ROW_LENGTH defines the number of pixels in a row. If the first pixel of a row is placed at location p in memory, then the location of the first pixel of the next row is obtained by skipping

components or indexes, where n is the number of components or indexes in a pixel, l is the number of pixels in a row (GL_UNPACK_ROW_LENGTH if it is greater than zero, the width argument to the pixel routine otherwise), a is the value of GL_UNPACK_ALIGNMENT, and s is the size, in bytes, of a single component (if a < s, then it is as if a = s). In the case of 1-bit values, the location of the next row is obtained by skipping

components or indexes.

The word component in this description refers to the nonindex values red, green, blue, alpha, and depth. Storage format GL_RGB, for example, has three components per pixel: first red, then green, and finally blue.

GL_UNPACK_SKIP_PIXELS and GL_UNPACK_SKIP_ROWS

These values are provided as a convenience to the programmer; they provide no functionality that cannot be duplicated simply by incrementing the pointer passed to glDrawPixels, glTexImage1D, glTexImage2D, glBitmap, or glPolygonStipple. Setting GL_UNPACK_SKIP_PIXELS to i is equivalent to incrementing the pointer by i n components or indexes, where n is the number of components or indexes in each pixel. Setting GL_UNPACK_SKIP_ROWS to j is equivalent to incrementing the pointer by j k components or indexes, where k is the number of components or indexes per row, as computed above in the GL_UNPACK_ROW_LENGTH section.

GL_UNPACK_ALIGNMENT

Specifies the alignment requirements for the start of each pixel row in memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to even-numbered bytes), 4 (word alignment), and 8 (rows start on double-word boundaries).

param

The value that pname is set to.

Remarks

The glPixelStore function sets pixel storage modes that affect the operation of subsequent glDrawPixels and glReadPixels as well as the unpacking of polygon stipple patterns (see glPolygonStipple), bitmaps (see glBitmap), and texture patterns (see glTexImage1D and glTexImage2D).

The following table gives the type, initial value, and range of valid values for each of the storage parameters that can be set with glPixelStore.

Pname	Type	Initial Value	Valid Range
GL_PACK_SWAP_BYTES	Boolean	false	true or false
GL_PACK_SWAP_BYTES	Boolean	false	true or false
GL_PACK_ROW_LENGTH	integer	0	[0,)
GL_PACK_SKIP_ROWS	integer	0	[0,)
GL_PACK_SKIP_PIXELS	integer	0	[0,)
GL_PACK_ALIGNMENT	integer	4	1, 2, 4, or 8
GL_UNPACK_SWAP_BYTES	Boolean	false	true or false
GL_UNPACK_LSB_FIRST	Boolean	false	true or false
GL_UNPACK_ROW_LENGTH	integer	0	[0,)
GL_UNPACK_SKIP_ROWS	integer	0	[0,)
GL_UNPACK_SKIP_PIXELS	integer	0	[0,)
GL_UNPACK_ALIGNMENT	integer	4	1, 2, 4, or 8
The glPixelStoref function can be used to set any pixel store parameter. If the parameter type is Boolean, and if param is 0.0, then the parameter is false; otherwise it is set to true. If pname is an integer type parameter, then param is rounded to the nearest integer.

Likewise, the glPixelStorei function can also be used to set any of the pixel store parameters. Boolean parameters are set to false if param is 0 and true otherwise. The param parameter is converted to floating point before being assigned to real-valued parameters.

The pixel storage modes in effect when glDrawPixels, glReadPixels, glTexImage1D, glTexImage2D, glBitmap, or glPolygonStipple is placed in a display list control the interpretation of memory data. The pixel storage modes in effect when a display list is executed are not significant.

The following functions retrieve information related to glPixelStore:

glGet with argument GL_PACK_SWAP_BYTES

glGet with argument GL_PACK_LSB_FIRST

glGet with argument GL_PACK_ROW_LENGTH

glGet with argument GL_PACK_SKIP_ROWS

glGet with argument GL_PACK_SKIP_PIXELS

glGet with argument GL_PACK_ALIGNMENT

glGet with argument GL_UNPACK_SWAP_BYTES

glGet with argument GL_UNPACK_LSB_FIRST

glGet with argument GL_UNPACK_ROW_LENGTH

glGet with argument GL_UNPACK_SKIP_ROWS

glGet with argument GL_UNPACK_SKIP_PIXELS

glGet with argument GL_UNPACK_ALIGNMENT

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	pname was not an accepted value.
GL_INVALID_VALUE	A negative row length, pixel skip, or row skip value was specified, or if alignment was specified as other than 1, 2, 4, or 8.
GL_INVALID_OPERATION	glPixelStore was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glBitmap, glDrawPixels, glEnd, glPixelMap, glPixelTransfer, glPixelZoom, glPolygonStipple, glReadPixels, glTexImage1D, glTexImage2D


glPixelTransfer [New - Windows 95, OEM Service Release 2]
glPixelTransferf, glPixelTransferi

[New - Windows 95, OEM Service Release 2]

The glPixelTransferf and glPixelTransferi functions set pixel transfer modes.

void glPixelTransferf(

GLenum pname,
GLfloat param
);
void glPixelTransferi(

GLenum pname,
GLint param
);
Parameters

pname

The symbolic name of the pixel transfer parameter to be set. The following table gives the type, initial value, and range of valid values for each of the pixel transfer parameters that are set with glPixelTransfer.

Pname	Type	Initial Value	Valid Range
GL_MAP_COLOR	Boolean	false	true/false
GL_MAP_STENCIL	Boolean	false	true/false
GL_INDEX_SHIFT	integer	0	( − ,)
GL_INDEX_OFFSET	integer	0	( − ,)
GL_RED_SCALE	float	1.0	( − ,)
GL_GREEN_SCALE	float	1.0	( − ,)
GL_BLUE_SCALE	float	1.0	( − ,)
GL_ALPHA_SCALE	float	1.0	( − ,)
GL_DEPTH_SCALE	float	1.0	( − ,)
GL_RED_BIAS	float	0.0	( − ,)
GL_GREEN_BIAS	float	0.0	( − ,)
GL_BLUE_BIAS	float	0.0	( − ,)
GL_ALPHA_BIAS	float	0.0	( − ,)
GL_DEPTH_BIAS	float	0.0	( − ,)
param

The value that pname is set to.

Remarks

The glPixelTransfer function sets pixel transfer modes that affect the operation of subsequent glDrawPixels, glReadPixels, glCopyPixels, glTexImage1D, and glTexImage2D commands. The algorithms that are specified by pixel transfer modes operate on pixels after they are read from the frame buffer (glReadPixels and glCopyPixels) or unpacked from client memory (glDrawPixels, glTexImage1D, and glTexImage2D). Pixel transfer operations happen in the same order, and in the same manner, regardless of the command that resulted in the pixel operation. Pixel storage modes (glPixelStore) control the unpacking of pixels being read from client memory, and the packing of pixels being written back into client memory.

Pixel transfer operations handle four fundamental pixel types: color, color index, depth, and stencil. Color pixels are made up of four floating-point values with unspecified mantissa and exponent sizes, scaled such that 0.0 represents zero intensity and 1.0 represents full intensity. Color indexes comprise a single fixed-point value, with unspecified precision to the right of the binary point. Depth pixels comprise a single floating-point value, with unspecified mantissa and exponent sizes, scaled such that 0.0 represents the minimum depth buffer value, and 1.0 represents the maximum depth buffer value. Finally, stencil pixels comprise a single fixed-point value, with unspecified precision to the right of the binary point.

The pixel transfer operations performed on the four basic pixel types are as follows:

Color

Each of the four color components is multiplied by a scale factor, and then added to a bias factor. That is, the red component is multiplied by GL_RED_SCALE, and then added to GL_RED_BIAS; the green component is multiplied by GL_GREEN_SCALE, and then added to GL_GREEN_BIAS; the blue component is multiplied by GL_BLUE_SCALE, and then added to GL_BLUE_BIAS; and the alpha component is multiplied by GL_ALPHA_SCALE, and then added to GL_ALPHA_BIAS. After all four color components are scaled and biased, each is clamped to the range [0,1]. All color scale and bias values are specified with glPixelTransfer.

If GL_MAP_COLOR is true, each color component is scaled by the size of the corresponding color-to-color map, and then replaced by the contents of that map indexed by the scaled component. That is, the red component is scaled by GL_PIXEL_MAP_R_TO_R_SIZE, and then replaced by the contents of GL_PIXEL_MAP_R_TO_R indexed by itself. The green component is scaled by GL_PIXEL_MAP_G_TO_G_SIZE, and then replaced by the contents of GL_PIXEL_MAP_G_TO_G indexed by itself. The blue component is scaled by GL_PIXEL_MAP_B_TO_B_SIZE, and then replaced by the contents of GL_PIXEL_MAP_B_TO_B indexed by itself. The alpha component is scaled by GL_PIXEL_MAP_A_TO_A_SIZE, and then replaced by the contents of GL_PIXEL_MAP_A_TO_A indexed by itself. All components taken from the maps are then clamped to the range [0,1]. GL_MAP_COLOR is specified with glPixelTransfer. The contents of the various maps are specified with glPixelMap.

Color index

Each color index is shifted left by GL_INDEX_SHIFT bits, filling with zeros any bits beyond the number of fraction bits carried by the fixed-point index. If GL_INDEX_SHIFT is negative, the shift is to the right, again zero filled. GL_INDEX_OFFSET is then added to the index. GL_INDEX_SHIFT and GL_INDEX_OFFSET are specified with glPixelTransfer.

From this point, operation diverges depending on the required format of the resulting pixels. If the resulting pixels are to be written to a color-index buffer, or if they are being read back to client memory in GL_COLOR_INDEX format, the pixels continue to be treated as indexes. If GL_MAP_COLOR is true, then each index is masked by 2^n − 1, where n is GL_PIXEL_MAP_I_TO_I_SIZE, and then replaced by the contents of GL_PIXEL_MAP_I_TO_I indexed by the masked value. GL_MAP_COLOR is specified with glPixelTransfer. The contents of the index map are specified with glPixelMap.

If the resulting pixels are to be written to an RGBA color buffer, or if they are being read back to client memory in a format other than GL_COLOR_INDEX, the pixels are converted from indexes to colors by referencing the four maps GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, and GL_PIXEL_MAP_I_TO_A. Before being dereferenced, the index is masked by 2n − 1, where n is GL_PIXEL_MAP_I_TO_R_SIZE for the red map, GL_PIXEL_MAP_I_TO_G_SIZE for the green map, GL_PIXEL_MAP_I_TO_B_SIZE for the blue map, and GL_PIXEL_MAP_I_TO_A_SIZE for the alpha map. All components taken from the maps are then clamped to the range [0,1]. The contents of the four maps are specified with glPixelMap.

Depth

Each depth value is multiplied by GL_DEPTH_SCALE, added to GL_DEPTH_BIAS, and then clamped to the range [0,1].

Stencil

Each index is shifted GL_INDEX_SHIFT bits just as a color index is, and then added to GL_INDEX_OFFSET. If GL_MAP_STENCIL is true, each index is masked by 2^n − 1, where n is GL_PIXEL_MAP_S_TO_S_SIZE, then replaced by the contents of GL_PIXEL_MAP_S_TO_S indexed by the masked value.

The glPixelTransferf function can be used to set any pixel transfer parameter. If the parameter type is Boolean, 0.0 implies false and any other value implies true. If pname is an integer parameter, param is rounded to the nearest integer.

Likewise, glPixelTransferi can also be used to set any of the pixel transfer parameters. Boolean parameters are set to false if param is 0 and true otherwise. The param parameter is converted to floating point before being assigned to real-valued parameters.

If a glDrawPixels, glReadPixels, glCopyPixels, glTexImage1D, or glTexImage2D command is placed in a display list (see glNewList and glCallList), the pixel transfer mode settings in effect when the display list is executed are the ones that are used. They may be different from the settings when the command was compiled into the display list.

The following functions retrieve information related to glPixelTransfer:

glGet with argument GL_MAP_COLOR

glGet with argument GL_MAP_STENCIL

glGet with argument GL_INDEX_SHIFT

glGet with argument GL_INDEX_OFFSET

glGet with argument GL_RED_SCALE

glGet with argument GL_RED_BIAS

glGet with argument GL_GREEN_SCALE

glGet with argument GL_GREEN_BIAS

glGet with argument GL_BLUE_SCALE

glGet with argument GL_BLUE_BIAS

glGet with argument GL_ALPHA_SCALE

glGet with argument GL_ALPHA_BIAS

glGet with argument GL_DEPTH_SCALE

glGet with argument GL_DEPTH_BIAS

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	pname was not an accepted value.
GL_INVALID_OPERATION	glPixelTransfer was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glCallList, glCopyPixels, glDrawPixels, glEnd, glNewList, glPixelMap, glPixelStore, glPixelZoom, glReadPixels, glTexImage1D, glTexImage2D


glPixelZoom [New - Windows 95, OEM Service Release 2]
glPixelZoom

[New - Windows 95, OEM Service Release 2]

The glPixelZoom function specifies the pixel zoom factors.

void glPixelZoom(

GLfloat xfactor,
GLfloat yfactor
);
Parameters

xfactor, yfactor

The x and y zoom factors for pixel write operations.

Remarks

The glPixelZoom function specifies values for the x and y zoom factors. During the execution of glDrawPixels or glCopyPixels, if (x (r) , y (r) ) is the current raster position, and a given element is in the nth row and mth column of the pixel rectangle, then pixels whose centers are in the rectangle with corners at

are candidates for replacement. Any pixel whose center lies on the bottom or left edge of this rectangular region is also modified.

Pixel zoom factors are not limited to positive values. Negative zoom factors reflect the resulting image about the current raster position.

The following functions retrieve information related to glPixelZoom:

glGet with argument GL_ZOOM_X

glGet with argument GL_ZOOM_Y

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glPixelZoom was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glCopyPixels, glDrawPixels, glEnd


glPointSize [New - Windows 95, OEM Service Release 2]
glPointSize

[New - Windows 95, OEM Service Release 2]

The glPointSize function specifies the diameter of rasterized points.

void glPointSize(

GLfloat size
);
Parameters

size

The diameter of rasterized points. The default is 1.0.

Remarks

The glPointSize function specifies the rasterized diameter of both aliased and antialiased points. Using a point size other than 1.0 has different effects, depending on whether point antialiasing is enabled. Point antialiasing is controlled by calling glEnable and glDisable with argument GL_POINT_SMOOTH.

If point antialiasing is disabled, the actual size is determined by rounding the supplied size to the nearest integer. (If the rounding results in the value 0, it is as if the point size were 1.) If the rounded size is odd, then the center point (x, y) of the pixel fragment that represents the point is computed as

( x (w)  + .5, y (w)  + .5)

where w subscripts indicate window coordinates. All pixels that lie within the square grid of the rounded size centered at (x, y) make up the fragment. If the size is even, the center point is

( x (w)  + .5, y (w)  + .5 )

and the rasterized fragment’s centers are the half-integer window coordinates within the square of the rounded size centered at (x, y). All pixel fragments produced in rasterizing a nonantialiased point are assigned the same associated data; that of the vertex corresponding to the point.

If antialiasing is enabled, then point rasterization produces a fragment for each pixel square that intersects the region lying within the circle having diameter equal to the current point size and centered at the points (x (w) , y (w) ). The coverage value for each fragment is the window coordinate area of the intersection of the circular region with the corresponding pixel square. This value is saved and used in the final rasterization step. The data associated with each fragment is the data associated with the point being rasterized.

Not all sizes are supported when point antialiasing is enabled. If an unsupported size is requested, the nearest supported size is used. Only size 1.0 is guaranteed to be supported; others depend on the implementation. The range of supported sizes and the size difference between supported sizes within the range can be queried by calling glGet with arguments GL_POINT_SIZE_RANGE and GL_POINT_SIZE_GRANULARITY.

The point size specified by glPointSize is always returned when GL_POINT_SIZE is queried. Clamping and rounding for aliased and antialiased points have no effect on the specified value.

Non-antialiased point size may be clamped to an implementation-dependent maximum. Although this maximum cannot be queried, it must be no less than the maximum value for antialiased points, rounded to the nearest integer value.

The following functions retrieve information related to glPointSize:

glGet with argument GL_POINT_SIZE

glGet with argument GL_POINT_SIZE_RANGE

glGet with argument GL_POINT_SIZE_GRANULARITY

glIsEnabled with argument GL_POINT_SMOOTH

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	size was less than or equal to zero.
GL_INVALID_OPERATION	glPointSize was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnable, glEnd, glIsEnabled


glPolygonMode [New - Windows 95, OEM Service Release 2]
glPolygonMode

[New - Windows 95, OEM Service Release 2]

The glPolygonMode function selects a polygon rasterization mode.

void glPolygonMode(

GLenum face,
GLenum mode
);
Parameters

face

The polygons that mode applies to. Must be GL_FRONT for front-facing polygons, GL_BACK for back-facing polygons, or GL_FRONT_AND_BACK for front- and back-facing polygons.

mode

The way polygons will be rasterized. The following modes are defined and can be specified in mode. The default is GL_FILL for both front- and back-facing polygons.

GL_POINT

Polygon vertices that are marked as the start of a boundary edge are drawn as points. Point attributes such as GL_POINT_SIZE and GL_POINT_SMOOTH control the rasterization of the points. Polygon rasterization attributes other than GL_POLYGON_MODE have no effect.

GL_LINE

Boundary edges of the polygon are drawn as line segments. They are treated as connected line segments for line stippling; the line stipple counter and pattern are not reset between segments (see glLineStipple). Line attributes such as GL_LINE_WIDTH and GL_LINE_SMOOTH control the rasterization of the lines. Polygon rasterization attributes other than GL_POLYGON_MODE have no effect.

GL_FILL

The interior of the polygon is filled. Polygon attributes such as GL_POLYGON_STIPPLE and GL_POLYGON_SMOOTH control the rasterization of the polygon.

Remarks

The glPolygonMode function controls the interpretation of polygons for rasterization. The face parameter describes which polygons mode applies to: front-facing polygons (GL_FRONT), back-facing polygons (GL_BACK), or both (GL_FRONT_AND_BACK). The polygon mode affects only the final rasterization of polygons. In particular, a polygon’s vertices are lit and the polygon is clipped and possibly culled before these modes are applied.

To draw a surface with filled back-facing polygons and outlined front-facing polygons, call

glPolygonMode(GL_FRONT, GL_LINE);

Vertices are marked as boundary or nonboundary with an edge flag. Edge flags are generated internally by OpenGL when it decomposes polygons, and they can be set explicitly using glEdgeFlag.

The following function retrieves information related to glPolygonMode:

glGet with argument GL_POLYGON_MODE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	Either face or mode was not an accepted value.
GL_INVALID_OPERATION	glPolygonMode was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEdgeFlag, glEnd, glLineStipple, glLineWidth, glPointSize, glPolygonStipple


glPolygonStipple [New - Windows 95, OEM Service Release 2]
glPolygonStipple

[New - Windows 95, OEM Service Release 2]

The glPolygonStipple function sets the polygon stippling pattern.

void glPolygonStipple(

const GLubyte *mask
);
Parameters

mask

A pointer to a 32x32 stipple pattern that will be unpacked from memory in the same way that glDrawPixels unpacks pixels.

Remarks

The glPolygonStipple function sets the polygon stippling pattern. Polygon stippling, like line stippling (see glLineStipple), masks out certain fragments produced by rasterization, creating a pattern. Stippling is independent of polygon antialiasing.

The mask parameter is a pointer to a 32x32 stipple pattern that is stored in memory just like the pixel data supplied to glDrawPixels with height and width both equal to 32, a pixel format of GL_COLOR_INDEX, and data type of GL_BITMAP. That is, the stipple pattern is represented as a 32x32 array of 1-bit color indexes packed in unsigned bytes. The glPixelStore function parameters, such as GL_UNPACK_SWAP_BYTES and GL_UNPACK_LSB_FIRST, affect the assembling of the bits into a stipple pattern. Pixel transfer operations (shift, offset, and pixel map) are not applied to the stipple image, however.

Polygon stippling is enabled and disabled with glEnable and glDisable, using argument GL_POLYGON_STIPPLE. If enabled, a rasterized polygon fragment with window coordinates x (w)  and y (w)  is sent to the next stage of OpenGL if and only if the (x (w)  mod 32)th bit in the (y (w)  mod 32)th row of the stipple pattern is one. When polygon stippling is disabled, it is as if the stipple pattern were all ones.

The following functions retrieve information related to glPolygonStipple:

glGetPolygonStipple

glIsEnabled with argument GL_POLYGON_STIPPLE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glPolygonStipple was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glDrawPixels, glEnd, glLineStipple, glPixelStore, glPixelTransfer


glPrioritizeTextures [New - Windows 95, OEM Service Release 2]
glPrioritizeTextures

[New - Windows 95, OEM Service Release 2]

The glPrioritizeTextures function sets the residence priority of textures.

void glPrioritizeTextures(

GLsizei n,
GLuint * textures,
GLclampf * priorities
);
Parameters

n

The number of textures to be prioritized.

textures

A pointer to the first element of an array containing the names of the textures to be prioritized.

priorities

A pointer to the first element of an array containing the texture priorities. A priority given in an element of the priorities parameter applies to the texture named by the corresponding element of the textures parameter.

Remarks

The glPrioritizeTextures function assigns the n texture priorities specified in the priorities parameter to the n textures named in the textures parameter. On machines with a limited amount of texture memory, OpenGL establishes a ``working set'' of textures that are resident in texture memory. These textures can be bound to a texture target much more efficiently than textures that are not resident.

By specifying a priority for each texture, the glPrioritizeTextures function enables you to determine which textures should be resident.

The texture priorities elements in priorities are clamped to the range [0.0, 1.0] before being assigned. Zero indicates the lowest priority; thus textures with priority zero are least likely to be resident. The value 1.0 indicates the highest priority; thus textures with priority 1.0 are most likely to be resident. However, textures are not guaranteed to be resident until they are bound.

The glPrioritizeTextures function ignores attempts to prioritize textures with a priorities value of zero or any texture name that does not correspond to an existing texture. None of the functions named by the textures parameter need to be bound to a texture target.

If a texture is currently bound, you can also use the glTexParameter function to set its priority. This is the only way to set the priority of a default texture.

You can include glPrioritizeTextures in display lists.

Note  The glPrioritizeTextures function is only available in OpenGL version 1.1 or later.

The following function retrieves the priority of a currently-bound texture related to glPrioritizeTextures:

glGetTexParameter with parameter name GL_TEXTURE_PRIORITY.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	n was a negative value.
GL_INVALID_OPERATION	glPrioritizeTextures was called between a call to glBegin and the corresponding call to glEnd.
See Also

glAreTexturesResident, glBegin, glEnd, glGetTexParameter, glTexImage1D, glTexImage2D, glTexParameter


glPushAttrib, glPopAttrib [New - Windows 95, OEM Service Release 2]
glPushAttrib, glPopAttrib

[New - Windows 95, OEM Service Release 2]

The glPushAttrib and glPopAttrib functions push and pop the attribute stack.

void glPushAttrib(

GLbitfield mask
);
Parameter

mask

A mask that indicates which attributes to save. The symbolic mask constants and their associated OpenGL state are as follows (the indented paragraphs list which attributes are saved):

GL_ACCUM_BUFFER_BIT

Accumulation buffer clear value

GL_COLOR_BUFFER_BIT

GL_ALPHA_TEST enable bit

Alpha test function and reference value

GL_BLEND enable bit

Blending source and destination functions

GL_DITHER enable bit

GL_DRAW_BUFFER setting

GL_LOGIC_OP enable bit

Logic op function

Color-mode and index-mode clear values

Color-mode and index-mode writemasks

GL_CURRENT_BIT

Current RGBA color

Current color index

Current normal vector

Current texture coordinates

Current raster position

GL_CURRENT_RASTER_POSITION_VALID flag

RGBA color associated with current raster position

Color index associated with current raster position

Texture coordinates associated with current raster position

GL_EDGE_FLAG flag

GL_DEPTH_BUFFER_BIT

GL_DEPTH_TEST enable bit

Depth buffer test function

Depth buffer clear value

GL_DEPTH_WRITEMASK enable bit

GL_ENABLE_BIT

GL_ALPHA_TEST flag

GL_AUTO_NORMAL flag

GL_BLEND flag

Enable bits for the user-definable clipping planes

GL_COLOR_MATERIAL

GL_CULL_FACE flag

GL_DEPTH_TEST flag

GL_DITHER flag

GL_FOG flag

GL_LIGHTi where 0 <= i < GL_MAX_LIGHTS

GL_LIGHTING flag

GL_LINE_SMOOTH flag

GL_LINE_STIPPLE flag

GL_LOGIC_OP flag

GL_MAP1_x where x is a map type

GL_MAP2_x where x is a map type

GL_NORMALIZE flag

GL_POINT_SMOOTH flag

GL_POLYGON_SMOOTH flag

GL_POLYGON_STIPPLE flag

GL_SCISSOR_TEST flag

GL_STENCIL_TEST flag

GL_TEXTURE_1D flag

GL_TEXTURE_2D flag

Flags GL_TEXTURE_GEN_x where x is S, T, R, or Q

GL_EVAL_BIT

GL_MAP1_x enable bits, where x is a map type

GL_MAP2_x enable bits, where x is a map type

1-D grid endpoints and divisions

2-D grid endpoints and divisions

GL_AUTO_NORMAL enable bit

GL_FOG_BIT

GL_FOG enable flag

Fog color

Fog density

Linear fog start

Linear fog end

Fog index

GL_FOG_MODE value

GL_HINT_BIT

GL_PERSPECTIVE_CORRECTION_HINT setting

GL_POINT_SMOOTH_HINT setting

GL_LINE_SMOOTH_HINT setting

GL_POLYGON_SMOOTH_HINT setting

GL_FOG_HINT setting

GL_LIGHTING_BIT

GL_COLOR_MATERIAL enable bit

GL_COLOR_MATERIAL_FACE value

Color material parameters that are tracking the current color

Ambient scene color

GL_LIGHT_MODEL_LOCAL_VIEWER value

GL_LIGHT_MODEL_TWO_SIDE setting

GL_LIGHTING enable bit

Enable bit for each light

Ambient, diffuse, and specular intensity for each light

Direction, position, exponent, and cutoff angle for each light

Constant, linear, and quadratic attenuation factors for each light

Ambient, diffuse, specular, and emissive color for each material

Ambient, diffuse, and specular color indexes for each material

Specular exponent for each material

GL_SHADE_MODEL setting

GL_LINE_BIT

GL_LINE_SMOOTH flag

GL_LINE_STIPPLE enable bit

Line stipple pattern and repeat counter

Line width

GL_LIST_BIT

GL_LIST_BASE setting

GL_PIXEL_MODE_BIT

GL_RED_BIAS and GL_RED_SCALE settings

GL_GREEN_BIAS and GL_GREEN_SCALE values

GL_BLUE_BIAS and GL_BLUE_SCALE

GL_ALPHA_BIAS and GL_ALPHA_SCALE

GL_DEPTH_BIAS and GL_DEPTH_SCALE

GL_INDEX_OFFSET and GL_INDEX_SHIFT values

GL_MAP_COLOR and GL_MAP_STENCIL flags

GL_ZOOM_X and GL_ZOOM_Y factors

GL_READ_BUFFER setting

GL_POINT_BIT

GL_POINT_SMOOTH flag

Point size

GL_POLYGON_BIT

GL_CULL_FACE enable bit

GL_CULL_FACE_MODE value

GL_FRONT_FACE indicator

GL_POLYGON_MODE setting

GL_POLYGON_SMOOTH flag

GL_POLYGON_STIPPLE enable bit

GL_POLYGON_STIPPLE_BIT

Polygon stipple image

GL_SCISSOR_BIT

GL_SCISSOR_TEST flag

Scissor box

GL_STENCIL_BUFFER_BIT

GL_STENCIL_TEST enable bit

Stencil function and reference value

Stencil value mask

Stencil fail, pass, and depth buffer pass actions

Stencil buffer clear value

Stencil buffer writemask

GL_TEXTURE_BIT

Enable bits for the four texture coordinates

Border color for each texture image

Minification function for each texture image

Magnification function for each texture image

Texture coordinates and wrap mode for each texture image

Color and mode for each texture environment

Enable bits GL_TEXTURE_GEN_x; x is S, T, R, and Q

GL_TEXTURE_GEN_MODE setting for S, T, R, and Q

glTexGen plane equations for S, T, R, and Q

GL_TRANSFORM_BIT

Coefficients of the six clipping planes

Enable bits for the user-definable clipping planes

GL_MATRIX_MODE value

GL_NORMALIZE flag

GL_VIEWPORT_BIT

Depth range (near and far)

Viewport origin and extent

void glPopAttrib(

void
);
Remarks

The glPushAttrib function takes one argument, a mask that indicates which groups of state variables to save on the attribute stack. Symbolic constants are used to set bits in the mask. The mask parameter is typically constructed by ORing several of these constants together. The special mask GL_ALL_ATTRIB_BITS can be used to save all stackable states.

The glPopAttrib function restores the values of the state variables saved with the last glPushAttrib command. Those not saved are left unchanged.

It is an error to push attributes onto a full stack, or to pop attributes off an empty stack. In either case, the error flag is set and no other change is made to the OpenGL state.

Initially, the attribute stack is empty.

Not all values for the OpenGL state can be saved on the attribute stack. For example, pixel pack and unpack state, render mode state, and select and feedback state cannot be saved.

The depth of the attribute stack depends on the implementation, but it must be at least 16.

The following functions retrieve information related to glPushAttrib and glPopAttrib:

glGet with argument GL_ATTRIB_STACK_DEPTH

glGet with argument GL_MAX_ATTRIB_STACK_DEPTH

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_STACK_OVERFLOW	glPushAttrib was called while the attribute stack was full.
GL_STACK_UNDERFLOW	glPopAttrib was called while the attribute stack was empty.
GL_INVALID_OPERATION	glPushAttrib was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glGet, glGetClipPlane, glGetError, glGetLight, glGetMap, glGetMaterial, glGetPixelMap, glGetPolygonStipple, glGetString, glGetTexEnv, glGetTexGen, glGetTexImage, glGetTexLevelParameter, glGetTexParameter, glIsEnabled


glPushClientAttrib, glPopClientAttrib [New - Windows 95, OEM Service Release 2]
glPushClientAttrib, glPopClientAttrib

[New - Windows 95, OEM Service Release 2]

The glPushClientAttrib and glPopClientAttrib functions save and restore groups of client-state variables on the client-attribute stack.

void glPushClientAttrib(

GLbitfield mask
);
Parameters

mask

A mask that indicates which attributes to save. The following are the symbolic mask constants and their associated OpenGL client state:

GL_CLIENT_PIXEL_STORE_BIT

Pixel storage mode attributes.

GL_CLIENT_VERTEX_ARRAY_BIT

Vertex array attributes.

GL_CLIENT_ALL_ATTRIB_BITS

All stackable client-state attributes.

void glPopClientAttrib(

void void
);
Remarks

The glPushClientAttrib function uses its mask parameter to determine which groups of client-state variables are saved on the client-attribute stack. You can OR together accepted symbolic constants to set bits and construct a mask.

The glPopClientAttrib function restores the values of the client-state variables last saved with glPushClientAttrib. Client-state variables not previously saved are left unchanged. Pushing attributes onto a full client-attribute stack or popping attributes off an empty stack sets an error flag and no other change is made to the OpenGL state. By default the client attribute stack is empty.

Some OpenGL client-state values cannot be saved on the client-attribute stack. For example, you cannot save the select or feedback states on the client-attribute stack. The depth of the client-attribute stack is at least 16.

The glPushClientAttrib and glPopClientAttrib functions are not compiled into display lists, but are executed immediately.

The glPushClientAttrib and glPopClientAttrib functions can only push and pop pixel storage modes and vertex array client states. You must use glPushAttrib and glPopAttrib to push and pop states that are kept on the server.

Note  The glPushClientAttrib and glPopClientAttrib functions are only available in OpenGL version 1.1 or later.

The following functions retrieve information related to glPushClientAttrib and glPopClientAttrib:

glGet with argument GL_CLIENT_ATTRIB_STACK_DEPTH

glGet with argument GL_MAX_CLIENT_ATTRIB_STACK_DEPTH

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_STACK_OVERFLOW	glPushClientAttrib was called while the client-attribute stack was full.
GL_STACK_UNDERFLOW	glPopClientAttrib was called while the client-attribute stack was empty.
See Also

glColorPointer, glDisableClientState, glEdgeFlagPointer, glEnableClientState, glGet, glGetError, glIndexPointer, glNormalPointer, glNewList, glPixelStore, glPushAttrib, glTexCoordPointer, glVertexPointer


glPushMatrix, glPopMatrix [New - Windows 95, OEM Service Release 2]
glPushMatrix, glPopMatrix

[New - Windows 95, OEM Service Release 2]

The glPushMatrix and glPopMatrix functions push and pop the current matrix stack.

void glPushMatrix(

void
);
void glPopMatrix(

void
);
Remarks

There is a stack of matrices for each of the matrix modes. In GL_MODELVIEW mode, the stack depth is at least 32. In the other two modes, GL_PROJECTION and GL_TEXTURE, the depth is at least 2. The current matrix in any mode is the matrix on the top of the stack for that mode.

The glPushMatrix function pushes the current matrix stack down by one, duplicating the current matrix. That is, after a glPushMatrix call, the matrix on the top of the stack is identical to the one below it. The glPushMatrix function pops the current matrix stack, replacing the current matrix with the one below it on the stack. Initially, each of the stacks contains one matrix, an identity matrix.

The following functions retrieve information related to glPushMatrix and glPopMatrix:

glGet with argument GL_MATRIX_MODE

glGet with argument GL_MODELVIEW_MATRIX

glGet with argument GL_PROJECTION_MATRIX

glGet with argument GL_TEXTURE_MATRIX

glGet with argument GL_MODELVIEW_STACK_DEPTH

glGet with argument GL_PROJECTION_STACK_DEPTH

glGet with argument GL_TEXTURE_STACK_DEPTH

glGet with argument GL_MAX_MODELVIEW_STACK_DEPTH

glGet with argument GL_MAX_PROJECTION_STACK_DEPTH

glGet with argument GL_MAX_TEXTURE_STACK_DEPTH

Error Codes

It is an error to push a full matrix stack, or to pop a matrix stack that contains only a single matrix. In either case, the error flag is set and no other change is made to the OpenGL state.

The following are the error codes generated and their conditions.

Error Code	Condition
GL_STACK_OVERFLOW	glPushMatrix was called while the current matrix stack was full.
GL_STACK_UNDERFLOW	glPopMatrix was called while the current matrix stack contained only a single matrix.
GL_INVALID_OPERATION	glPushMatrix was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glFrustum, glLoadIdentity, glLoadMatrix, glMatrixMode, glMultMatrix, glOrtho, glRotate, glScale, glTranslate, glViewport


glPushName, glPopName [New - Windows 95, OEM Service Release 2]
glPushName, glPopName

[New - Windows 95, OEM Service Release 2]

The glPushName and glPopName functions push and pop the name stack.

void glPushName(

GLuint name
);
Parameters

name

A name that will be pushed onto the name stack.

void glPopName(

void
);
Remarks

The glPushName function causes name to be pushed onto the name stack, which is initially empty. The glPopName function pops one name off the top of the stack. The name stack is used during selection mode to allow sets of rendering commands to be uniquely identified. It consists of an ordered set of unsigned integers.

The name stack is always empty while the render mode is not GL_SELECT. Calls to glPushName or glPopName while the render mode is not GL_SELECT are ignored.

The following functions retrieve information related to glPushName and glPopName:

glGet with argument GL_NAME_STACK_DEPTH

glGet with argument GL_MAX_NAME_STACK_DEPTH

Error Codes

It is an error to push a name onto a full stack, or to pop a name off an empty stack. It is also an error to manipulate the name stack between a call to glBegin and the corresponding call to glEnd. In any of these cases, the error flag is set and no other change is made to the OpenGL state.

The following are the error codes generated and their conditions.

Error Code	Condition
GL_STACK_OVERFLOW	glPushName was called while the name stack was full.
GL_STACK_UNDERFLOW	glPopName was called while the name stack was empty.
GL_INVALID_OPERATION	glPushName or glPopName was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glInitNames, glLoadName, glRenderMode, glSelectBuffer


glRasterPos [New - Windows 95, OEM Service Release 2]
glRasterPos

[New - Windows 95, OEM Service Release 2]

glRasterPos2d, glRasterPos2f, glRasterPos2i, glRasterPos2s, glRasterPos3d, glRasterPos3f, glRasterPos3i, glRasterPos3s, glRasterPos4d, glRasterPos4f, glRasterPos4i, glRasterPos4s, glRasterPos2dv, glRasterPos2fv, glRasterPos2iv, glRasterPos2sv, glRastePos3dv, glRasterPos3fv, glRasterPos3iv, glRasterPos3sv, glRasterPos4dv, glRasterPos4fv, glRasterPos4iv, glRasterPos4sv

These functions specify the raster position for pixel operations.

void glRasterPos2d(

GLdouble x,
GLdouble y
);
void glRasterPos2f(

GLfloat x,
GLfloat y
);
void glRasterPos2i(

GLint x,
GLint y
);
void glRasterPos2s(

GLshort x,
GLshort y
);
void glRasterPos3d(

GLdouble x,
GLdouble y,
GLdouble z
);
void glRasterPos3f(

GLfloat x,
GLfloat y,
GLfloat z
);
void glRasterPos3i(

GLint x,
GLint y,
GLint z
);
void glRasterPos3s(

GLshort x,
GLshort y,
GLshort z
);
void glRasterPos4d(

GLdouble x,
GLdouble y,
GLdouble z,
GLdouble w
);
void glRasterPos4f(

GLfloat x,
GLfloat y,
GLfloat z,
GLfloat w
);
void glRasterPos4i(

GLint x,
GLint y,
GLint z,
GLint w
);
void glRasterPos4s(

GLshort x,
GLshort y,
GLshort z,
GLshort w
);
Parameters

x, y, z, w

The x, y, z, and w object coordinates (if present) for the raster position.

void glRasterPos2dv(

const GLdouble *v
);
void glRasterPos2fv(

const GLfloat *v
);
void glRasterPos2iv(

const GLint *v
);
void glRasterPos2sv(

const GLshort *v
);
void glRasterPos3dv(

const GLdouble *v
);
void glRasterPos3fv(

const GLfloat *v
);
void glRasterPos3iv(

const GLint *v
);
void glRasterPos3sv(

const GLshort *v
);
void glRasterPos4dv(

const GLdouble *v
);
void glRasterPos4fv(

const GLfloat *v
);
void glRasterPos4iv(

const GLint *v
);
void glRasterPos4sv(

const GLshort *v
);
Parameters

v

A pointer to an array of two, three, or four elements, specifying x, y, z, and w coordinates, respectively.

Remarks

OpenGL maintains a 3-D position in window coordinates. This position, called the raster position, is maintained with subpixel accuracy. It is used to position pixel and bitmap write operations. See glBitmap, glDrawPixels, and glCopyPixels.

The current raster position consists of three window coordinates (x, y, z), a clip coordinate w value, an eye coordinate distance, a valid bit, and associated color data and texture coordinates. The w coordinate is a clip coordinate, because w is not projected to window coordinates. The glRasterPos4 function specifies object coordinates x, y, z, and w explicitly. The glRasterPos3 function specifies object coordinates x, y, and z explicitly, while w is implicitly set to one. The glRasterPos2 function uses the argument values for x and y while implicitly setting z and w to zero and one.

The object coordinates presented by glRasterPos are treated just like those of a glVertex command. They are transformed by the current modelview and projection matrices and passed to the clipping stage. If the vertex is not culled, then it is projected and scaled to window coordinates, which become the new current raster position, and the GL_CURRENT_RASTER_POSITION_VALID flag is set. If the vertex is culled, then the valid bit is cleared and the current raster position and associated color and texture coordinates are undefined.

The current raster position also includes some associated color data and texture coordinates. If lighting is enabled, then GL_CURRENT_RASTER_COLOR, in RGBA mode, or the GL_CURRENT_RASTER_INDEX, in color-index mode, is set to the color produced by the lighting calculation (see glLight, glLightModel, and glShadeModel). If lighting is disabled, current color (in RGBA mode, state variable GL_CURRENT_COLOR) or color index (in color-index mode, state variable GL_CURRENT_INDEX) is used to update the current raster color.

Likewise, GL_CURRENT_RASTER_TEXTURE_COORDS is updated as a function of GL_CURRENT_TEXTURE_COORDS, based on the texture matrix and the texture generation functions (see glTexGen). Finally, the distance from the origin of the eye coordinate system to the vertex, as transformed by only the modelview matrix, replaces GL_CURRENT_RASTER_DISTANCE.

Initially, the current raster position is (0,0,0,1), the current raster distance is 0, the valid bit is set, the associated RGBA color is (1,1,1,1), the associated color index is 1, and the associated texture coordinates are (0, 0, 0, 1). In RGBA mode, GL_CURRENT_RASTER_INDEX is always 1; in color-index mode, the current raster RGBA color always maintains its initial value.

Note  The raster position is modified both by glRasterPos and by glBitmap.

When the raster position coordinates are invalid, drawing commands that are based on the raster position are ignored (that is, they do not result in changes to the OpenGL state).

The following functions retrieve information related to glRasterPos:

glGet with argument GL_CURRENT_RASTER_POSITION

glGet with argument GL_CURRENT_RASTER_POSITION_VALID

glGet with argument GL_CURRENT_RASTER_DISTANCE

glGet with argument GL_CURRENT_RASTER_COLOR

glGet with argument GL_CURRENT_RASTER_INDEX

glGet with argument GL_CURRENT_RASTER_TEXTURE_COORDS

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glRasterPos was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glBitmap, glCopyPixels, glDrawPixels, glEnd, glLight, glLightModel, glShadeModel, glTexCoord, glTexGen, glVertex


glReadBuffer [New - Windows 95, OEM Service Release 2]
glReadBuffer

[New - Windows 95, OEM Service Release 2]

The glReadBuffer function selects a color buffer source for pixels.

void glReadBuffer(

GLenum mode
);
Parameters

mode

A color buffer. Accepted values are GL_FRONT_LEFT, GL_FRONT_RIGHT, GL_BACK_LEFT, GL_BACK_RIGHT, GL_FRONT, GL_BACK, GL_LEFT, GL_RIGHT, and GL_AUXi, where i is between 0 and GL_AUX_BUFFERS −1.

Remarks

The glReadBuffer function specifies a color buffer as the source for subsequent glReadPixels and glCopyPixels commands. The mode parameter accepts one of twelve or more predefined values. (GL_AUX0 through GL_AUX3 are always defined.) In a fully configured system, GL_FRONT, GL_LEFT, and GL_FRONT_LEFT all name the front-left buffer, GL_FRONT_RIGHT and GL_RIGHT name the front-right buffer, and GL_BACK_LEFT and GL_BACK name the back-left buffer.

Nonstereo double-buffered configurations have only a front-left and a back-left buffer. Single-buffered configurations have a front-left and a front-right buffer if stereo, and only a front-left buffer if nonstereo. It is an error to specify a nonexistent buffer to glReadBuffer.

By default, mode is GL_FRONT in single-buffered configurations, and GL_BACK in double-buffered configurations.

The following function retrieves information related to glReadBuffer:

glGet with argument GL_READ_BUFFER

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	mode was not one of the twelve (or more) accepted values.
GL_INVALID_OPERATION	mode specified a buffer that does not exist.
GL_INVALID_OPERATION	glReadBuffer was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glCopyPixels, glDrawBuffer, glEnd, glReadPixels


glReadPixels [New - Windows 95, OEM Service Release 2]
glReadPixels

[New - Windows 95, OEM Service Release 2]

The glReadPixels function reads a block of pixels from the frame buffer.

void glReadPixels(

GLint x,
GLint y,
GLsizei width,
GLsizei height,
GLenum format,
GLenum type,
GLvoid *pixels
);
Parameters

x, y

The window coordinates of the first pixel that is read from the frame buffer. This location is the lower-left corner of a rectangular block of pixels.

width, height

The dimensions of the pixel rectangle. The width and height parameters of one correspond to a single pixel.

format

The format of the pixel data. The following symbolic values are accepted:

GL_COLOR_INDEX

Color indexes are read from the color buffer selected by glReadBuffer. Each index is converted to fixed point, shifted left or right depending on the value and sign of GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET. If GL_MAP_COLOR is GL_TRUE, indexes are replaced by their mappings in the table GL_PIXEL_MAP_I_TO_I.

GL_STENCIL_INDEX

Stencil values are read from the stencil buffer. Each index is converted to fixed point, shifted left or right depending on the value and sign of GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET. If GL_MAP_STENCIL is GL_TRUE, indexes are replaced by their mappings in the table GL_PIXEL_MAP_S_TO_S.

GL_DEPTH_COMPONENT

Depth values are read from the depth buffer. Each component is converted to floating point such that the minimum depth value maps to 0.0 and the maximum value maps to 1.0. Each component is then multiplied by GL_DEPTH_SCALE, added to GL_DEPTH_BIAS, and finally clamped to the range [0,1].

GL_RED

GL_GREEN

GL_BLUE

GL_ALPHA

GL_RGB

GL_RGBA
GL_BGR_EXT
GL_BGRA_EXT

GL_LUMINANCE

GL_LUMINANCE_ALPHA

Processing differs depending on whether color buffers store color indexes or RGBA color components. If color indexes are stored, they are read from the color buffer selected by glReadBuffer. Each index is converted to fixed point, shifted left or right depending on the value and sign of GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET. Indexes are then replaced by the red, green, blue, and alpha values obtained by indexing the GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, and GL_PIXEL_MAP_I_TO_A tables.

If RGBA color components are stored in the color buffers, they are read from the color buffer selected by glReadBuffer. Each color component is converted to floating point such that zero intensity maps to 0.0 and full intensity maps to 1.0. Each component is then multiplied by GL_c_SCALE and added to GL_c_BIAS, where c is GL_RED, GL_GREEN, GL_BLUE, and GL_ALPHA. Each component is clamped to the range [0,1]. Finally, if GL_MAP_COLOR is GL_TRUE, each color component c is replaced by its mapping in the table GL_PIXEL_MAP_c_TO_c, where c again is GL_RED, GL_GREEN, GL_BLUE, and GL_ALPHA. Each component is scaled to the size of its corresponding table before the lookup is performed.

Finally, unneeded data is discarded. For example, GL_RED discards the green, blue, and alpha components, while GL_RGB discards only the alpha component. GL_LUMINANCE computes a single component value as the sum of the red, green, and blue components, and GL_LUMINANCE_ALPHA does the same, while keeping alpha as a second value.

type

The data type of the pixel data. Must be one of the following values:

Type	Index Mask	Component Conversion
GL_UNSIGNED_BYTE	2^8−1	(2^8−1)c
GL_BYTE	2^7−1	[2^7−1]c-1]/2
GL_BITMAP	1	1
GL_UNSIGNED_SHORT	2^16−1	(2^16−1) c
GL_SHORT	2^15−1	[(2^15−1) c−1] / 2
GL_UNSIGNED_INT	2^32−1	(2^32−1) c
GL_INT	2^31−1	[(2^31−1) c−1] / 2
GL_FLOAT	none	c
pixels

Returns the pixel data.

Remarks

The glReadPixels function returns pixel data from the frame buffer, starting with the pixel whose lower-left corner is at location (x, y), into client memory starting at location pixels. Several parameters control the processing of the pixel data before it is placed into client memory. These parameters are set with three commands: glPixelStore, glPixelTransfer, and glPixelMap. This topic describes the effects on glReadPixels of most, but not all of the parameters specified by these three commands.

The glReadPixels function returns values from each pixel with lower-left corner at (x + i, y + j) for 0 ≤ i < width and 0 ≤ j < height. This pixel is said to be the ith pixel in the jth row. Pixels are returned in row order from the lowest to the highest row, left to right in each row.

The shift, scale, bias, and lookup factors described above are all specified by glPixelTransfer. The lookup table contents are specified by glPixelMap.

The final step involves converting the indexes or components to the proper format, as specified by type. If format is GL_COLOR_INDEX or GL_STENCIL_INDEX and type is not GL_FLOAT, each index is masked with the mask value given in the following table. If type is GL_FLOAT, then each integer index is converted to single-precision floating-point format.

If format is GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_BGR_EXT, GL_BGRA_EXT, GL_LUMINANCE, or GL_LUMINANCE_ALPHA and type is not GL_FLOAT, each component is multiplied by the multiplier shown in the preceding table. If type is GL_FLOAT, then each component is passed as is (or converted to the client’s single-precision floating-point format if it is different from the one used by OpenGL).

Return values are placed in memory as follows. If format is GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, or GL_LUMINANCE, a single value is returned and the data for the ith pixel in the jth row is placed in location (j) width + i. GL_RGB and GL_BGR_EXT return three values, GL_RGBA and GL_BGRA_EXT return four values, and GL_LUMINANCE_ALPHA returns two values for each pixel, with all values corresponding to a single pixel occupying contiguous space in pixels. Storage parameters set by glPixelStore, such as GL_PACK_SWAP_BYTES and GL_PACK_LSB_FIRST, affect the way that data is written into memory. See glPixelStore for a description.

Values for pixels that lie outside the window connected to the current OpenGL context are undefined.

If an error is generated, no change is made to the contents of pixels.

The following function retrieves information related to glReadPixels:

glGet with argument GL_INDEX_MODE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	format or type was not an accepted value.
GL_INVALID_VALUE	either width or height was negative.
GL_INVALID_OPERATION	format was GL_COLOR_INDEX and the color buffers stored RGBA or BGRA color components.
GL_INVALID_OPERATION	format was GL_STENCIL_INDEX and there was no stencil buffer.
GL_INVALID_OPERATION	format was GL_DEPTH_COMPONENT and there was no depth buffer.
GL_INVALID_OPERATION	glReadPixels was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glCopyPixels, glDrawPixels, glEnd, glPixelMap, glPixelStore, glPixelTransfer, glReadBuffer


glRect [New - Windows 95, OEM Service Release 2]
glRectd, glRectf, glRecti, glRects, glRectdv, glRectfv, glRectiv, glRectsv

[New - Windows 95, OEM Service Release 2]

These functions draw a rectangle.

void glRectd(

GLdouble x1,
GLdouble y1,
GLdouble x2,
GLdouble y2
);
void glRectf(

GLfloat x1,
GLfloat y1,
GLfloat x2,
GLfloat y2
);
void glRecti(

GLint x1,
GLint y1,
GLint x2,
GLint y2
);
void glRects(

GLshort x1,
GLshort y1,
GLshort x2,
GLshort y2
);
Parameters

x1, y1

One vertex of a rectangle.

x2, y2

The opposite vertex of the rectangle.

void glRectdv(

const GLdouble *v1,
const GLdouble *v2
);
void glRectfv(

const GLfloat *v1,
const GLfloat *v2
);
void glRectiv(

const GLint *v1,
const GLint *v2
);
void glRectsv(

const GLshort *v1,
const GLshort *v2
);
Parameters

v1

A pointer to one vertex of a rectangle.

v2

A pointer to the opposite vertex of the rectangle.

Remarks

The glRect function supports efficient specification of rectangles as two corner points. Each rectangle command takes four arguments, organized either as two consecutive pairs of (x, y) coordinates, or as two pointers to arrays, each containing an (x,y) pair. The resulting rectangle is defined in the z = 0 plane.

The glRect(x1, y1, x2, y2) function is exactly equivalent to the following sequence:

glBegin(GL_POLYGON);

glVertex2(x1, y1);

glVertex2(x2, y1);

glVertex2(x2, y2);

glVertex2(x1, y2);

glEnd( );

Notice that if the second vertex is above and to the right of the first vertex, the rectangle is constructed with a counterclockwise winding.

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glRect was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glVertex


glRenderMode [New - Windows 95, OEM Service Release 2]
glRenderMode

[New - Windows 95, OEM Service Release 2]

The glRenderMode function sets the rasterization mode.

GLint glRenderMode(

GLenum mode
);
Parameters

mode

The rasterization mode. The following three values are accepted. The default value is GL_RENDER.

GL_RENDER

Render mode. Primitives are rasterized, producing pixel fragments, which are written into the frame buffer. This is the normal mode and also the default mode.

GL_SELECT

Selection mode. No pixel fragments are produced, and no change to the frame buffer contents is made. Instead, a record of the names of primitives that would have been drawn if the render mode was GL_RENDER is returned in a select buffer, which must be created (see glSelectBuffer) before selection mode is entered.

GL_FEEDBACK

Feedback mode. No pixel fragments are produced, and no change to the frame buffer contents is made. Instead, the coordinates and attributes of vertices that would have been drawn had the render mode been GL_RENDER are returned in a feedback buffer, which must be created (see glFeedbackBuffer) before feedback mode is entered.

Remarks

The glRenderMode function takes one argument, mode, which can assume one of three predefined values above.

The return value of the glRenderMode function is determined by the render mode at the time glRenderMode is called, rather than by mode. The values returned for the three render modes are as follows:

GL_RENDER

Zero.

GL_SELECT

The number of hit records transferred to the select buffer.

GL_FEEDBACK

The number of values (not vertices) transferred to the feedback buffer.

Refer to glSelectBuffer and glFeedbackBuffer for more details concerning selection and feedback operation.

If an error is generated, glRenderMode returns zero regardless of the current render mode.

The following function retrieves information related to glRenderMode:

glGet with argument GL_RENDER_MODE

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	mode was not one of the three accepted values.
GL_INVALID_OPERATION	glSelectBuffer was called while the render mode was GL_SELECT, or if glRenderMode was called with argument GL_SELECT before glSelectBuffer was called at least once.
GL_INVALID_OPERATION	glFeedbackBuffer was called while the render mode was GL_FEEDBACK, or if glRenderMode was called with argument GL_FEEDBACK before glFeedbackBuffer was called at least once.
GL_INVALID_OPERATION	glRenderMode was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glFeedbackBuffer, glInitNames, glLoadName, glPassThrough, glPushName, glSelectBuffer


glRotate [New - Windows 95, OEM Service Release 2]
glRotated, glRotatef

[New - Windows 95, OEM Service Release 2]

The glRotated and glRotatef functions multiply the current matrix by a rotation matrix.

void glRotated(

GLdouble angle,
GLdouble x,
GLdouble y,
GLdouble z
);
void glRotatef(

GLfloat angle,
GLfloat x,
GLfloat y,
GLfloat z
);
Parameters

angle

The angle of rotation, in degrees.

x, y, z

The x, y, and z coordinates of a vector, respectively.

Remarks

The glRotate function computes a matrix that performs a counterclockwise rotation of angle degrees about the vector from the origin through the point (x, y, z).

The current matrix (see glMatrixMode) is multiplied by this rotation matrix, with the product replacing the current matrix. That is, if M is the current matrix and R is the translation matrix, then M is replaced with M•R.

If the matrix mode is either GL_MODELVIEW or GL_PROJECTION, all objects drawn after glRotate is called are rotated. Use glPushMatrix and glPopMatrix to save and restore the unrotated coordinate system.

The following functions retrieve information related to glRotate:

glGet with argument GL_RENDER_MODE

glGet with argument GL_MATRIX_MODE

glGet with argument GL_MODELVIEW_MATRIX

glGet with argument GL_PROJECTION_MATRIX

glGet with argument GL_TEXTURE_MATRIX

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glRotate was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glMatrixMode, glMultMatrix, glPushMatrix, glScale, glTranslate


glScale [New - Windows 95, OEM Service Release 2]
glScaled, glScalef

[New - Windows 95, OEM Service Release 2]

The glScaled and glScalef functions multiply the current matrix by a general scaling matrix.

void glScaled(

GLdouble x,
GLdouble y,
GLdouble z
);
void glScalef(

GLfloat x,
GLfloat y,
GLfloat z
);
Parameters

x, y, z

Scale factors along the x, y, and z axes, respectively.

Remarks

The glScale function produces a general scaling along the x, y, and z axes. The three arguments indicate the desired scale factors along each of the three axes. The resulting matrix is

The current matrix (see glMatrixMode) is multiplied by this scale matrix, with the product replacing the current matrix. That is, if M is the current matrix and S is the scale matrix, then M is replaced with M•S.

If the matrix mode is either GL_MODELVIEW or GL_PROJECTION, all objects drawn after glScale is called are scaled. Use glPushMatrix and glPopMatrix to save and restore the unscaled coordinate system.

If scale factors other than 1.0 are applied to the modelview matrix and lighting is enabled, automatic normalization of normals should probably also be enabled (glEnable and glDisable with argument GL_NORMALIZE).

The following functions retrieve information related to glScale:

glGet with argument GL_MATRIX_MODE

glGet with argument GL_MODELVIEW_MATRIX

glGet with argument GL_PROJECTION_MATRIX

glGet with argument GL_TEXTURE_MATRIX

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glScale was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glMatrixMode, glMultMatrix, glPushMatrix, glRotate, glTranslate


glScissor [New - Windows 95, OEM Service Release 2]
glScissor

[New - Windows 95, OEM Service Release 2]

The glScissor function defines the scissor box.

void glScissor(

GLint x,
GLint y,
GLsizei width,
GLsizei height
);
Parameters

x, y

The lower-left corner of the scissor box. Initially (0,0).

width, height

The width and height of the scissor box. When an OpenGL context is first attached to a window, width and height are set to the dimensions of that window.

Remarks

The glScissor function defines a rectangle, called the scissor box, in window coordinates. The first two parameters, x and y, specify the lower-left corner of the box. The width and height parameters specify the width and height of the box.

The scissor test is enabled and disabled using glEnable and glDisable with argument GL_SCISSOR_TEST. While the scissor test is enabled, only pixels that lie within the scissor box can be modified by drawing commands. Window coordinates have integer values at the shared corners of frame buffer pixels, so glScissor(0,0,1,1) allows only the lower-left pixel in the window to be modified, and glScissor(0,0,0,0) disallows modification to all pixels in the window.

When the scissor test is disabled, it is as though the scissor box includes the entire window.

The following functions retrieve information related to glScissor:

glGet with argument GL_SCISSOR_BOX

glIsEnabled with argument GL_SCISSOR_TEST

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	either width or height was negative.
GL_INVALID_OPERATION	glScissor was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnable, glEnd, glIsEnabled, glViewport


glSelectBuffer [New - Windows 95, OEM Service Release 2]
glSelectBuffer

[New - Windows 95, OEM Service Release 2]

The glSelectBuffer function establishes a buffer for selection mode values.

void glSelectBuffer(

GLsizei size,
GLuint *buffer
);
Parameters

size

The size of buffer.

buffer

Returns the selection data.

Remarks

The glSelectBuffer function has two parameters: buffer is a pointer to an array of unsigned integers, and size indicates the size of the array. The buffer parameter returns values from the name stack (see glInitNames, glLoadName, glPushName) when the rendering mode is GL_SELECT (see glRenderMode). The glSelectBuffer function must be issued before selection mode is enabled, and it must not be issued while the rendering mode is GL_SELECT.

Selection is used by a programmer to determine which primitives are drawn into some region of a window. The region is defined by the current modelview and perspective matrices.

In selection mode, no pixel fragments are produced from rasterization. Instead, if a primitive intersects the clip volume defined by the viewing frustum and the user-defined clipping planes, this primitive causes a selection hit. (With polygons, no hit occurs if the polygon is culled.) When a change is made to the name stack, or when glRenderMode is called, a hit record is copied to buffer if any hits have occurred since the last such event (either a name stack change or a glRenderMode call). The hit record consists of the number of names in the name stack at the time of the event; followed by the minimum and maximum depth values of all vertices that hit since the previous event; followed by the name stack contents, bottom name first.

Returned depth values are mapped such that the largest unsigned integer value corresponds to window coordinate depth 1.0, and zero corresponds to window coordinate depth 0.0.

An internal index into buffer is reset to zero whenever selection mode is entered. Each time a hit record is copied into buffer, the index is incremented to point to the cell just past the end of the block of names—that is, to the next available cell. If the hit record is larger than the number of remaining locations in buffer, as much data as can fit is copied, and the overflow flag is set. If the name stack is empty when a hit record is copied, that record consists of zero followed by the minimum and maximum depth values.

Selection mode is exited by calling glRenderMode with an argument other than GL_SELECT. Whenever glRenderMode is called while the render mode is GL_SELECT, it returns the number of hit records copied to buffer, resets the overflow flag and the selection buffer pointer, and initializes the name stack to be empty. If the overflow bit was set when glRenderMode was called, a negative hit record count is returned.

The contents of buffer are undefined until glRenderMode is called with an argument other than GL_SELECT.

The glBegin/glEnd primitives and calls to glRasterPos can result in hits.

The following function retrieves information related to glSelectBuffer:

glGet with argument GL_NAME_STACK_DEPTH

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	size was negative.
GL_INVALID_OPERATION	glSelectBuffer was called while the render mode was GL_SELECT, or if glRenderMode was called with argument GL_SELECT before glSelectBuffer was called at least once.
GL_INVALID_OPERATION	glSelectBuffer was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glFeedbackBuffer, glInitNames, glLoadName, glPushName, glRenderMode


glShadeModel [New - Windows 95, OEM Service Release 2]
glShadeModel

[New - Windows 95, OEM Service Release 2]

The glShadeModel function selects flat or smooth shading.

void glShadeModel(

GLenum mode
);
Parameters

mode

A symbolic value representing a shading technique. Accepted values are GL_FLAT and GL_SMOOTH. The default is GL_SMOOTH.

Remarks

OpenGL primitives can have either flat or smooth shading. Smooth shading, the default, causes the computed colors of vertices to be interpolated as the primitive is rasterized, typically assigning different colors to each resulting pixel fragment. Flat shading selects the computed color of just one vertex and assigns it to all the pixel fragments generated by rasterizing a single primitive. In either case, the computed color of a vertex is the result of lighting, if lighting is enabled, or it is the current color at the time the vertex was specified, if lighting is disabled.

Flat and smooth shading are indistinguishable for points. Counting vertices and primitives from one, starting when glBegin is issued, each flat-shaded line segment i is given the computed color of vertex i + 1, its second vertex. Counting similarly from one, each flat-shaded polygon is given the computed color of the vertex listed in the following table. This is the last vertex to specify the polygon in all cases except single polygons, where the first vertex specifies the flat-shaded color.

Primitive Type of Polygon i	Vertex
Single polygon (i≡1)	1
Triangle strip	i + 2
Triangle fan	i + 2
Independent triangle	3i
Quad strip	2i + 2
Independent quad	4i
Flat and smooth shading are specified by glShadeModel with mode set to GL_FLAT and GL_SMOOTH, respectively.

The following function retrieves information related to glShadeModel:

glGet with argument GL_SHADE_MODEL

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	mode was any value other than GL_FLAT or GL_SMOOTH.
GL_INVALID_OPERATION	glShadeModel was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glColor, glEnd, glLight, glLightModel


glStencilFunc [New - Windows 95, OEM Service Release 2]
glStencilFunc

[New - Windows 95, OEM Service Release 2]

The glStencilFunc function sets the function and reference value for stencil testing.

void glStencilFunc(

GLenum func,
GLint ref,
GLuint mask
);
Parameters

func

The test function. The following eight tokens are valid:

GL_NEVER

Always fails.

GL_LESS

Passes if ( ref & mask) < ( stencil & mask).

GL_LEQUAL

Passes if ( ref & mask) ≤ ( stencil & mask).

GL_GREATER

Passes if ( ref & mask) > ( stencil & mask).

GL_GEQUAL

Passes if ( ref & mask) ≥ ( stencil & mask).

GL_EQUAL

Passes if ( ref & mask) = ( stencil & mask).

GL_NOTEQUAL

Passes if ( ref & mask) ≠ ( stencil & mask).

GL_ALWAYS

Always passes.

ref

The reference value for the stencil test. The ref parameter is clamped to the range [0,2^n − 1], where n is the number of bitplanes in the stencil buffer.

mask

A mask that is ANDed with both the reference value and the stored stencil value when the test is done.

Remarks

Stenciling, like z-buffering, enables and disables drawing on a per-pixel basis. You draw into the stencil planes using OpenGL drawing primitives, then render geometry and images, using the stencil planes to mask out portions of the screen. Stenciling is typically used in multipass rendering algorithms to achieve special effects, such as decals, outlining, and constructive solid geometry rendering.

The stencil test conditionally eliminates a pixel based on the outcome of a comparison between the reference value and the value in the stencil buffer. The test is enabled by glEnable and glDisable with argument GL_STENCIL. Actions taken based on the outcome of the stencil test are specified with glStencilOp.

The func parameter is a symbolic constant that determines the stencil comparison function. It accepts one of the eight values shown above. The ref parameter is an integer reference value that is used in the stencil comparison. It is clamped to the range [0,2^n − 1], where n is the number of bitplanes in the stencil buffer. The mask parameter is bitwise ANDed with both the reference value and the stored stencil value, with the ANDed values participating in the comparison.

If stencil represents the value stored in the corresponding stencil buffer location, the preceding list shows the effect of each comparison function that can be specified by func. Only if the comparison succeeds is the pixel passed through to the next stage in the rasterization process (see glStencilOp). All tests treat stencil values as unsigned integers in the range [0,2^n − 1], where n is the number of bitplanes in the stencil buffer.

Initially, the stencil test is disabled. If there is no stencil buffer, no stencil modification can occur and it is as if the stencil test always passes.

The following functions retrieve information related to glStencilFunc:

glGet with argument GL_STENCIL_FUNC

glGet with argument GL_STENCIL_VALUE_MASK

glGet with argument GL_STENCIL_REF

glGet with argument GL_STENCIL_BITS

glIsEnabled with argument GL_STENCIL_TEST

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	func was not one of the eight accepted values.
GL_INVALID_OPERATION	glStencilFunc was called between a call to glBegin and the corresponding call to glEnd.
See Also

glAlphaFunc, glBegin, glBlendFunc, glDepthFunc, glEnable, glEnd, glIsEnabled, glLogicOp, glStencilOp


glStencilMask [New - Windows 95, OEM Service Release 2]
glStencilMask

[New - Windows 95, OEM Service Release 2]

The glStencilMask function controls the writing of individual bits in the stencil planes.

void glStencilMask(

GLuint mask
);
Parameters

mask

A bit mask to enable and disable writing of individual bits in the stencil planes. Initially, the mask is all ones.

Remarks

The glStencilMask function controls the writing of individual bits in the stencil planes. The least significant n bits of mask, where n is the number of bits in the stencil buffer, specify a mask. Wherever a one appears in the mask, the corresponding bit in the stencil buffer is made writable. Where a zero appears, the bit is write-protected. Initially, all bits are enabled for writing.

The following functions retrieve information related to glStencilMask:

glGet with argument GL_STENCIL_WRITEMASK

glGet with argument GL_STENCIL_BITS

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glStencilMask was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glColorMask, glDepthMask, glEnd, glIndexMask, glStencilFunc, glStencilOp


glStencilOp [New - Windows 95, OEM Service Release 2]
glStencilOp

[New - Windows 95, OEM Service Release 2]

The glStencilOp function sets the stencil test actions.

void glStencilOp(

GLenum fail,
GLenum zfail,
GLenum zpass
);
Parameters

fail

The action to take when the stencil test fails. The following six symbolic constants are accepted:

GL_KEEP

Keeps the current value.

GL_ZERO

Sets the stencil buffer value to zero.

GL_REPLACE

Sets the stencil buffer value to ref, as specified by glStencilFunc.

GL_INCR

Increments the current stencil buffer value. Clamps to the maximum representable unsigned value.

GL_DECR

Decrements the current stencil buffer value. Clamps to zero.

GL_INVERT

Bitwise inverts the current stencil buffer value.

zfail

Stencil action when the stencil test passes, but the depth test fails. Accepts the same symbolic constants as fail.

zpass

Stencil action when both the stencil test and the depth test pass, or when the stencil test passes and either there is no depth buffer or depth testing is not enabled. Accepts the same symbolic constants as fail.

Remarks

Stenciling, like z-buffering, enables and disables drawing on a per-pixel basis. You draw into the stencil planes using OpenGL drawing primitives, then render geometry and images, using the stencil planes to mask out portions of the screen. Stenciling is typically used in multipass rendering algorithms to achieve special effects, such as decals, outlining, and constructive solid geometry rendering.

The stencil test conditionally eliminates a pixel based on the outcome of a comparison between the value in the stencil buffer and a reference value. The test is enabled with glEnable and glDisable calls with argument GL_STENCIL, and controlled with glStencilFunc.

The glStencilOp function takes three arguments that indicate what happens to the stored stencil value while stenciling is enabled. If the stencil test fails, no change is made to the pixel’s color or depth buffers, and fail specifies what happens to the stencil buffer contents.

Stencil buffer values are treated as unsigned integers. When incremented and decremented, values are clamped to 0 and 2^n − 1, where n is the value returned by querying GL_STENCIL_BITS.

The other two arguments to glStencilOp specify stencil buffer actions should subsequent depth buffer tests succeed (zpass) or fail (zfail). (See glDepthFunc.) They are specified using the same six symbolic constants as fail. Note that zfail is ignored when there is no depth buffer, or when the depth buffer is not enabled. In these cases, fail and zpass specify stencil action when the stencil test fails and passes, respectively.

Initially the stencil test is disabled. If there is no stencil buffer, no stencil modification can occur and it is as if the stencil tests always pass, regardless of any call to glStencilOp.

The following functions retrieve information related to glStencilOp:

glGet with argument GL_STENCIL_FAIL

glGet with argument GL_STENCIL_PASS_DEPTH_PASS

glGet with argument GL_STENCIL_PASS_DEPTH_FAIL

glGet with argument GL_STENCIL_BITS

glIsEnabled with argument GL_STENCIL_TEST

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	fail, zfail, or zpass was any value other than the six defined constant values.
GL_INVALID_OPERATION	glStencilOp was called between a call to glBegin and the corresponding call to glEnd.
See Also

glAlphaFunc, glBegin, glBlendFunc, glDepthFunc, glEnable, glEnd, glIsEnabled, glLogicOp, glStencilFunc


glTexCoord [New - Windows 95, OEM Service Release 2]
glTexCoord

[New - Windows 95, OEM Service Release 2]

glTexCoord1d, glTexCoord1f, glTexCoord1i, glTexCoord1s, glTexCoord2d, glTexCoord2f, glTexCoord2i, glTexCoord2s, glTexCoord3d, glTexCoord3f, glTexCoord3i, glTexCoord3s, glTexCoord4d, glTexCoord4f, glTexCoord4i, glTexCoord4s, glTexCoord1dv, glTexCoord1fv, glTexCoord1iv, glTexCoord1sv, glTexCoord2dv, glTexCoord2fv, glTexCoord2iv, glTexCoord2sv, glTexCoord3dv, glTexCoord3fv, glTexCoord3iv, glTexCoord3sv, glTexCoord4dv, glTexCoord4fv, glTexCoord4iv, glTexCoord4sv

These functions set the current texture coordinates.

void glTexCoord1d(

GLdouble s
);
void glTexCoord1f(

GLfloat s
);
void glTexCoord1i(

GLint s
);
void glTexCoord1s(

GLshort s
);
void glTexCoord2d(

GLdouble s,
GLdouble t
);
void glTexCoord2f(

GLfloat s,
GLfloat t
);
void glTexCoord2i(

GLint s,
GLint t
);
void glTexCoord2s(

GLshort s,
GLshort t
);
void glTexCoord3d(

GLdouble s,
GLdouble t,
GLdouble r
);
void glTexCoord3f(

GLfloat s,
GLfloat t,
GLfloat r
);
void glTexCoord3i(

GLint s,
GLint t,
GLint r
);
void glTexCoord3s(

GLshort s,
GLshort t,
GLshort r
);
void glTexCoord4d(

GLdouble s,
GLdouble t,
GLdouble r,
GLdouble q
);
void glTexCoord4f(

GLfloat s,
GLfloat t,
GLfloat r,
GLfloat q
);
void glTexCoord4i(

GLint s,
GLint t,
GLint r,
GLint q
);
void glTexCoord4s(

GLshort s,
GLshort t,
GLshort r,
GLshort q
);
Parameters

s, t, r, q

The s, t, r, and q texture coordinates. Not all parameters are present in all forms of the command.

void glTexCoord1dv(

const GLdouble *v
);
void glTexCoord1fv(

const GLfloat *v
);
void glTexCoord1iv(

const GLint *v
);
void glTexCoord1sv(

const GLshort *v
);
void glTexCoord2dv(

const GLdouble *v
);
void glTexCoord2fv(

const GLfloat *v
);
void glTexCoord2iv(

const GLint *v
);
void glTexCoord2sv(

const GLshort *v
);
void glTexCoord3dv(

const GLdouble *v
);
void glTexCoord3fv(

const GLfloat *v
);
void glTexCoord3iv(

const GLint *v
);
void glTexCoord3sv(

const GLshort *v
);
void glTexCoord4dv(

const GLdouble *v
);
void glTexCoord4fv(

const GLfloat *v
);
void glTexCoord4iv(

const GLint *v
);
void glTexCoord4sv(

const GLshort *v
);
Parameters

v

A pointer to an array of one, two, three, or four elements, which in turn specify the s, t, r, and q texture coordinates.

Remarks

The glTexCoord function sets the current texture coordinates that are part of the data that is associated with polygon vertices.

The glTexCoord function specifies texture coordinates in one, two, three, or four dimensions. The glTexCoord1 function sets the current texture coordinates to (s, 0, 0, 1); a call to glTexCoord2 sets them to (s, t, 0, 1). Similarly, glTexCoord3 specifies the texture coordinates as (s, t, r, 1), and glTexCoord4 defines all four components explicitly as (s, t, r, q).

The current texture coordinates can be updated at any time. In particular, glTexCoord can be called between a call to glBegin and the corresponding call to glEnd.

The following function retrieves information related to glTexCoord:

glGet with argument GL_CURRENT_TEXTURE_COORDS

See Also

glVertex


glTexCoordPointer [New - Windows 95, OEM Service Release 2]
glTexCoordPointer

[New - Windows 95, OEM Service Release 2]

The glTexCoordPointer function defines an array of texture coordinates.

void glTexCoordPointer(

GLint size,
GLenum type,
GLsizei stride,
GLsizei count,
const GLvoid *pointer
);
Parameters

size

The number of coordinates per array element. The value of size must be 1, 2, 3, or 4.

type

The data type of each texture coordinate in the array using the following symbolic constants: GL_SHORT, GL_INT, GL_FLOAT, and GL_DOUBLE.

stride

The byte offset between consecutive array elements. When stride is zero, the array elements are tightly packed in the array.

count

The number of array elements, counting from the first, that are static.

pointer

A pointer to the first coordinate of the first element in the array.

Remarks

The glTexCoordPointer function specifies the location and data of an array of texture coordinates to use when rendering.The size parameter specifies the number of coordinates used for each element of the array.The type parameter specifies the data type of each texture coordinate. The stride parameter determines the byte offset from one array element to the next, enabling the packing of vertices and attributes in a single array or storage in separate arrays. In some implementations, storing the vertices and attributes in a single array can be more efficient than using separate arrays. Starting from the first array element, count indicates the total number of static elements. Your application can modify static elements, but once the elements are modified, the application must explicitly specify the array again before using the array for any rendering. Non-static array elements are not accessed until you call glDrawArrays or glArrayElement.

A texture coordinate array is enabled when you specify the GL_TEXTURE_COORD_ARRAY constant with glEnableClientState. When enabled, glDrawArrays and glArrayElement use the texture coordinate array. By default the texture coordinate array is disabled.

You cannot include glTexCoordPointer in display lists.

When you specify a texture coordinate array using glTexCoordPointer, the values of all the function’s texture coordinate array parameters are saved in a client-side state, and static array elements can be cached. Because the texture coordinate array parameters are client-side state, their values are not saved or restored by glPushAttrib and glPopAttrib.

Although no error is generated when you call glTexCoordPointer within glBegin and glEnd pairs, the results are undefined.

The following functions retrieve information related to glTexCoordPointer:

glIsEnabled with argument GL_TEXTURE_COORD_ARRAY

glGet with argument GL_TEXTURE_COORD_ARRAY_SIZE

glGet with argument GL_TEXTURE_COORD_ARRAY_STRIDE

glGet with argument GL_TEXTURE_COORD_ARRAY_COUNT

glGet with argument GL_TEXTURE_COORD_ARRAY_TYPE

glGetPointerv with argument GL_TEXTURE_COORD_ARRAY_POINTER

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	size was not 1, 2, 3, or 4.
GL_INVALID_ENUM	type was not an accepted value.
GL_INVALID_VALUE	stride or count was negative.
See Also

glArrayElement, glColorPointer, glDrawArrays, glEdgeFlagPointer, glGetPointerv, glGetString, glIndexPointer, glIsEnabled, glNormalPointer, glVertexPointer


glTexEnv [New - Windows 95, OEM Service Release 2]
glTexEnvf, glTexEnvi, glTexEnvfv, glTexEnviv

[New - Windows 95, OEM Service Release 2]

These functions set texture environment parameters.

void glTexEnvf(

GLenum target,
GLenum pname,
GLfloat param
);
void glTexEnvi(

GLenum target,
GLenum pname,
GLint param
);
Parameters

target

A texture environment. Must be GL_TEXTURE_ENV.

pname

The symbolic name of a single-valued texture environment parameter. Must be GL_TEXTURE_ENV_MODE.

param

A single symbolic constant, one of GL_MODULATE, GL_DECAL, or GL_BLEND.

void glTexEnvfv(

GLenum target,
GLenum pname,
const GLfloat *params
);
void glTexEnviv(

GLenum target,
GLenum pname,
const GLint *params
);
Parameters

target

A texture environment. Must be GL_TEXTURE_ENV.

pname

The symbolic name of a texture environment parameter. Accepted values are GL_TEXTURE_ENV_MODE and GL_TEXTURE_ENV_COLOR.

params

A pointer to an array of parameters: either a single symbolic constant or an RGBA color.

Remarks

A texture environment specifies how texture values are interpreted when a fragment is textured. The target parameter must be GL_TEXTURE_ENV. The pname parameter can be either GL_TEXTURE_ENV_MODE or GL_TEXTURE_ENV_COLOR.

If pname is GL_TEXTURE_ENV_MODE, then params is (or points to) the symbolic name of a texture function. Three texture functions are defined: GL_MODULATE, GL_DECAL, and GL_BLEND.

A texture function acts on the fragment to be textured using the texture image value that applies to the fragment (see glTexParameter) and produces an RGBA color for that fragment. The following table shows how the RGBA color is produced for each of the three texture functions that can be chosen. C is a triple of color values (RGB) and A is the associated alpha value. RGBA values extracted from a texture image are in the range [0,1]. The subscript f refers to the incoming fragment, the subscript t to the texture image, the subscript c to the texture environment color, and subscript v indicates a value produced by the texture function.

A texture image can have up to four components per texture element (see glTexImage1D and glTexImage2D). In a one-component image, L (t)  indicates that single component. A two-component image uses L (t)  and A (t) . A three-component image has only a color value, C (t) . A four-component image has both a color value C (t)  and an alpha value A (t) .

If pname is GL_TEXTURE_ENV_COLOR, params is a pointer to an array that holds an RGBA color consisting of four values. Integer color components are interpreted linearly such that the most positive integer maps to 1.0, and the most negative integer maps to −1.0. The values are clamped to the range [0,1] when they are specified. C (c)  takes these four values.

GL_TEXTURE_ENV_MODE defaults to GL_MODULATE and GL_TEXTURE_ENV_COLOR defaults to (0,0,0,0).

The following function retrieves information related to glTexEnv:

glGetTexEnv

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target or pname was not one of the accepted defined values, or when params should have had a defined constant value (based on the value of pname) and did not.
GL_INVALID_OPERATION	glTexEnv was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glTexImage1D, glTexImage2D, glTexParameter


glTexGen [New - Windows 95, OEM Service Release 2]
glTexGend, glTexGenf, glTexGeni, glTexGendv, glTexGenfv, glTexGeniv

[New - Windows 95, OEM Service Release 2]

These functions control the generation of texture coordinates.

void glTexGend(

GLenum coord,
GLenum pname,
GLdouble param
);
void glTexGenf(

GLenum coord,
GLenum pname,
GLfloat param
);
void glTexGeni(

GLenum coord,
GLenum pname,
GLint param
);
Parameters

coord

A texture coordinate. Must be one of the following: GL_S, GL_T, GL_R, or GL_Q.

pname

The symbolic name of the texture-coordinate generation function. Must be GL_TEXTURE_GEN_MODE.

param

A single-valued texture generation parameter, one of GL_OBJECT_LINEAR, GL_EYE_LINEAR, or GL_SPHERE_MAP.

void glTexGendv(

GLenum coord,
GLenum pname,
const GLdouble *params
);
void glTexGenfv(

GLenum coord,
GLenum pname,
const GLfloat *params
);
void glTexGeniv(

GLenum coord,
GLenum pname,
const GLint *params
);
Parameters

coord

A texture coordinate. Must be one of the following: GL_S, GL_T, GL_R, or GL_Q.

pname

The symbolic name of the texture-coordinate generation function or function parameters. Must be GL_TEXTURE_GEN_MODE, GL_OBJECT_PLANE, or GL_EYE_PLANE.

params

A pointer to an array of texture generation parameters. If pname is GL_TEXTURE_GEN_MODE, then the array must contain a single symbolic constant, one of GL_OBJECT_LINEAR, GL_EYE_LINEAR, or GL_SPHERE_MAP. Otherwise, params holds the coefficients for the texture-coordinate generation function specified by pname.

Remarks

The glTexGen function selects a texture-coordinate generation function or supplies coefficients for one of the functions. The coord parameter names one of the (s,t,r,q) texture coordinates, and it must be one of these symbols: GL_S, GL_T, GL_R, or GL_Q. The pname parameter must be one of three symbolic constants: GL_TEXTURE_GEN_MODE, GL_OBJECT_PLANE, or GL_EYE_PLANE. If pname is GL_TEXTURE_GEN_MODE, then params chooses a mode, one of GL_OBJECT_LINEAR, GL_EYE_LINEAR, or GL_SPHERE_MAP. If pname is either GL_OBJECT_PLANE or GL_EYE_PLANE, params contains coefficients for the corresponding texture generation function.

If the texture generation function is GL_OBJECT_LINEAR, the function

is used, where g is the value computed for the coordinate named in coord; p (1) , p (2) , p (3) , and p (4)  are the four values supplied in params; and x (o) , y (o) , z (o) , and w (o)  are the object coordinates of the vertex. This function can be used to texture-map terrain using sea level as a reference plane (defined by p (1) , p (2) , p (3) , and p (4) ). The altitude of a terrain vertex is computed by the GL_OBJECT_LINEAR coordinate generation function as its distance from sea level; that altitude is used to index the texture image to map white snow onto peaks and green grass onto foothills, for example.

If the texture generation function is GL_EYE_LINEAR, the function

is used, where

and x (e) , y (e) , z (e) , and w (e)  are the eye coordinates of the vertex, p (1) , p (2) , p (3) , and p (4)  are the values supplied in params, and M is the modelview matrix when glTexGen is invoked. If M is poorly conditioned or singular, texture coordinates generated by the resulting function may be inaccurate or undefined.

Note that the values in params define a reference plane in eye coordinates. The modelview matrix that is applied to them may not be the same one in effect when the polygon vertices are transformed. This function establishes a field of texture coordinates that can produce dynamic contour lines on moving objects.

If pname is GL_SPHERE_MAP and coord is either GL_S or GL_T, s and t texture coordinates are generated as follows. Let u be the unit vector pointing from the origin to the polygon vertex (in eye coordinates). Let n′ be the current normal, after transformation to eye coordinates. Let f = (f (x ) f (y ) f (z) )T be the reflection vector such that

Finally, let

Then the values assigned to the i and t texture coordinates are

A texture-coordinate generation function is enabled or disabled using glEnable or glDisable with one of the symbolic texture-coordinate names (GL_TEXTURE_GEN_S, GL_TEXTURE_GEN_T, GL_TEXTURE_GEN_R, or GL_TEXTURE_GEN_Q) as the argument. When enabled, the specified texture coordinate is computed according to the generating function associated with that coordinate. When disabled, subsequent vertices take the specified texture coordinate from the current set of texture coordinates. Initially, all texture generation functions are set to GL_EYE_LINEAR and are disabled. Both s plane equations are (1,0,0,0); both t plane equations are (0,1,0,0); and all r and q plane equations are (0,0,0,0).

The following functions retrieve information related to glTexGen:

glGetTexGen

glIsEnabled with argument GL_TEXTURE_GEN_S

glIsEnabled with argument GL_TEXTURE_GEN_T

glIsEnabled with argument GL_TEXTURE_GEN_R

glIsEnabled with argument GL_TEXTURE_GEN_Q

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	coord or pname was not an accepted defined value, or when pname was GL_TEXTURE_GEN_MODE and params was not an accepted defined value.
GL_INVALID_ENUM	pname was GL_TEXTURE_GEN_MODE, params was GL_SPHERE_MAP, and coord was either GL_R or GL_Q.
GL_INVALID_OPERATION	glTexGen was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glGetTexGen, glIsEnabled, glTexEnv, glTexImage1D, glTexImage2D, glTexParameter


glTexImage1D [New - Windows 95, OEM Service Release 2]
glTexImage1D

[New - Windows 95, OEM Service Release 2]

The glTexImage1D function specifies a one-dimensional texture image.

void glTexImage1D(

GLenum target,
GLint level,
GLint components,
GLsizei width,
GLint border,
GLenum format,
GLenum type,
const GLvoid *pixels
);
Parameters

target

The target texture. Must be GL_TEXTURE_1D.

level

The level-of-detail number. Level 0 is the base image level. Level n is the nth mipmap reduction image.

components

The number of color components in the texture. Must be 1, 2, 3, or 4.

width

The width of the texture image. Must be 2^n + 2(border) for some integer n. The height of the texture image is 1.

border

The width of the border. Must be either 0 or 1.

format

The format of the pixel data. It can assume one of nine symbolic values:

GL_COLOR_INDEX

Each element is a single value, a color index. It is converted to fixed point (with an unspecified number of 0 bits to the right of the binary point), shifted left or right depending on the value and sign of GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET (see glPixelTransfer). The resulting index is converted to a set of color components using the GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, and GL_PIXEL_MAP_I_TO_A tables, and clamped to the range [0,1].

GL_RED

Each element is a single red component. It is converted to floating point and assembled into an RGBA element by attaching 0.0 for green and blue, and 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_GREEN

Each element is a single green component. It is converted to floating point and assembled into an RGBA element by attaching 0.0 for red and blue, and 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_BLUE

Each element is a single blue component. It is converted to floating point and assembled into an RGBA element by attaching 0.0 for red and green, and 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_ALPHA

Each element is a single red component. It is converted to floating point and assembled into an RGBA element by attaching 0.0 for red, green, and blue. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_RGB

Each element is an RGB triple. It is converted to floating point and assembled into an RGBA element by attaching 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_RGBA

Each element is a complete RGBA element. It is converted to floating point. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_BGR_EXT

Each pixel is a group of three components in this order: blue, green, red.

GL_BGR_EXT provides a format that matches the memory layout of Windows device-independent bitmaps (DIBs). Thus your applications can use the same data with Win32 function calls and OpenGL pixel function calls.

GL_BGRA_EXT

Each pixel is a group of four components in this order: blue, green, red, alpha.

GL_BGRA_EXT provides a format that matches the memory layout of Windows device-independent bitmaps (DIBs). Thus your applications can use the same data with Win32 function calls and OpenGL pixel function calls.

GL_LUMINANCE

Each element is a single luminance value. It is converted to floating point, and then assembled into an RGBA element by replicating the luminance value three times for red, green, and blue, and attaching 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_LUMINANCE_ALPHA

Each element is a luminance/alpha pair. It is converted to floating point, and then assembled into an RGBA element by replicating the luminance value three times for red, green, and blue. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

type

The data type of the pixel data. The following symbolic values are accepted: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, and GL_FLOAT.

pixels

A pointer to the image data in memory.

Remarks

The glTexImage1D function specifies a one-dimensional texture image. Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. One-dimensional texturing is enabled and disabled using glEnable and glDisable with argument GL_TEXTURE_1D.

Texture images are defined with glTexImage1D. The arguments describe the parameters of the texture image, such as width, width of the border, level-of-detail number (see glTexParameter), and number of color components provided. The last three arguments describe the way the image is represented in memory. These arguments are identical to the pixel formats used for glDrawPixels.

Data is read from pixels as a sequence of signed or unsigned bytes, shorts or longs, or single-precision floating-point values, depending on type. These values are grouped into sets of one, two, three, or four values, depending on format, to form elements. If type is GL_BITMAP, the data is considered as a string of unsigned bytes (and format must be GL_COLOR_INDEX). Each data byte is treated as eight 1-bit elements, with bit ordering determined by GL_UNPACK_LSB_FIRST (see glPixelStore).

A texture image can have up to four components per texture element, depending on components. A one-component texture image uses only the red component of the RGBA color extracted from pixels. A two-component image uses the R and A values. A three-component image uses the R, G, and B values. A four-component image uses all of the RGBA components.

Texturing has no effect in color-index mode.

The texture image can be represented by the same data formats as the pixels in a glDrawPixels command, except that GL_STENCIL_INDEX and GL_DEPTH_COMPONENT cannot be used. The glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.

A texture image with zero width indicates the null texture. If the null texture is specified for level-of-detail 0, it is as if texturing were disabled.

The following functions retrieve information related to glTexImageID:

glGetTexImage

glIsEnabled with argument GL_TEXTURE_1D

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target was not GL_TEXTURE_1D.
GL_INVALID_ENUM	format was not an accepted format constant. Format constants other than GL_STENCIL_INDEX and GL_DEPTH_COMPONENT were accepted.
GL_INVALID_ENUM	type was not a type constant.
GL_INVALID_ENUM	type was GL_BITMAP and format was not GL_COLOR_INDEX.
GL_INVALID_VALUE	level was less than zero or greater than log (2) max, where max was the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE	components was not 1, 2, 3, or 4.
GL_INVALID_VALUE	width was less than zero or greater than 2 + GL_MAX_TEXTURE_SIZE, or if it could not be represented as 2^n + 2(border) for some integer value of n.
GL_INVALID_VALUE	border was not 0 or 1.
GL_INVALID_OPERATION	glTexImage1D was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glDrawPixels, glEnd, glFog, glGetTexImage, glIsEnabled, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage2D, glTexParameter


glTexImage2D [New - Windows 95, OEM Service Release 2]
glTexImage2D

[New - Windows 95, OEM Service Release 2]

The glTexImage2D function specifies a two-dimensional texture image.

void glTexImage2D(

GLenum target,
GLint level,
GLint components,
GLsizei width,
GLsizei height,
GLint border,
GLenum format,
GLenum type,
const GLvoid *pixels
);
Parameters

target

The target texture. Must be GL_TEXTURE_2D.

level

The level-of-detail number. Level 0 is the base image level. Level n is the nth mipmap reduction image.

components

The number of color components in the texture. Must be 1, 2, 3, or 4.

width

The width of the texture image. Must be 2^n + 2(border) for some integer n.

height

The height of the texture image. Must be 2^m + 2(border) for some integer m.

border

The width of the border. Must be either 0 or 1.

format

The format of the pixel data. It can assume one of nine symbolic values:

GL_COLOR_INDEX

Each element is a single value, a color index. It is converted to fixed point (with an unspecified number of 0 bits to the right of the binary point), shifted left or right depending on the value and sign of GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET (see glPixelTransfer). The resulting index is converted to a set of color components using the GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, and GL_PIXEL_MAP_I_TO_A tables, and clamped to the range [0,1].

GL_RED

Each element is a single red component. It is converted to floating point and assembled into an RGBA element by attaching 0.0 for green and blue, and 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_GREEN

Each element is a single green component. It is converted to floating point and assembled into an RGBA element by attaching 0.0 for red and blue, and 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_BLUE

Each element is a single blue component. It is converted to floating point and assembled into an RGBA element by attaching 0.0 for red and green, and 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_ALPHA

Each element is a single red component. It is converted to floating point and assembled into an RGBA element by attaching 0.0 for red, green, and blue. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_RGB

Each element is an RGB triple. It is converted to floating point and assembled into an RGBA element by attaching 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_RGBA

Each element is a complete RGBA element. It is converted to floating point. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_BGR_EXT

Each pixel is a group of three components in this order: blue, green, red.

GL_BGR_EXT provides a format that matches the memory layout of Windows device-independent bitmaps (DIBs). Thus your applications can use the same data with Win32 function calls and OpenGL pixel function calls.

GL_BGRA_EXT

Each pixel is a group of four components in this order: blue, green, red, alpha.

GL_BGRA_EXT provides a format that matches the memory layout of Windows device-independent bitmaps (DIBs). Thus your applications can use the same data with Win32 function calls and OpenGL pixel function calls.

GL_LUMINANCE

Each element is a single luminance value. It is converted to floating point, and then assembled into an RGBA element by replicating the luminance value three times for red, green, and blue, and attaching 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_LUMINANCE_ALPHA

Each element is a luminance/alpha pair. It is converted to floating point, and then assembled into an RGBA element by replicating the luminance value three times for red, green, and blue. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

type

The data type of the pixel data. The following symbolic values are accepted: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, and GL_FLOAT.

pixels

A pointer to the image data in memory.

Remarks

The glTexImage2D function specifies a two-dimensional texture image. Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. Two-dimensional texturing is enabled and disabled using glEnable and glDisable with argument GL_TEXTURE_2D.

Texture images are defined with glTexImage2D. The arguments describe the parameters of the texture image, such as height, width, width of the border, level-of-detail number (see glTexParameter), and number of color components provided. The last three arguments describe the way the image is represented in memory. These arguments are identical to the pixel formats used for glDrawPixels.

Data is read from pixels as a sequence of signed or unsigned bytes, shorts or longs, or single-precision floating-point values, depending on type. These values are grouped into sets of one, two, three, or four values, depending on format, to form elements. If type is GL_BITMAP, the data is considered as a string of unsigned bytes (and format must be GL_COLOR_INDEX). Each data byte is treated as eight 1-bit elements, with bit ordering determined by GL_UNPACK_LSB_FIRST (see glPixelStore). Please see glDrawPixels for a description of the acceptable values for the type parameter.

A texture image can have up to four components per texture element, depending on components. A one-component texture image uses only the red component of the RGBA color extracted from pixels. A two-component image uses the R and A values. A three-component image uses the R, G, and B values. A four-component image uses all of the RGBA components.

Texturing has no effect in color-index mode.

The texture image can be represented by the same data formats as the pixels in a glDrawPixels command, except that GL_STENCIL_INDEX and GL_DEPTH_COMPONENT cannot be used. The glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.

A texture image with zero height or width indicates the null texture. If the null texture is specified for level-of-detail 0, it is as if texturing were disabled.

The following functions retrieve information related to glTexImage2D:

glGetTexImage

glIsEnabled with argument GL_TEXTURE_2D

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target was not GL_TEXTURE_2D.
GL_INVALID_ENUM	format was not an accepted format constant. Format constants other than GL_STENCIL_INDEX and GL_DEPTH_COMPONENT were accepted.
GL_INVALID_ENUM	type was not a type constant.
GL_INVALID_ENUM	type was GL_BITMAP and format was not GL_COLOR_INDEX.
GL_INVALID_VALUE	level was less than zero or greater than log (2)  max, where max was the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE	components was not 1, 2, 3, or 4.
GL_INVALID_VALUE	width or height was less than zero or greater than 2 + GL_MAX_TEXTURE_SIZE, or if either could not be represented as 2^k + 2(border) for some integer value of k.
GL_INVALID_VALUE	border was not 0 or 1.
GL_INVALID_OPERATION	glTexImage2D was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glDrawPixels, glEnd, glFog, glIsEnabled, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage1D, glTexParameter


glTexParameter [New - Windows 95, OEM Service Release 2]
glTexParameterf, glTexParameteri, glTexParameterfv, glTexParameteriv

[New - Windows 95, OEM Service Release 2]

These functions set texture parameters.

void glTexParameterf(

GLenum target,
GLenum pname,
GLfloat param
);
void glTexParameteri(

GLenum target,
GLenum pname,
GLint param
);
Parameters

target

The target texture, which must be either GL_TEXTURE_1D or GL_TEXTURE_2D.

pname

The symbolic name of a single-valued texture parameter. The following symbols are accepted in pname:

GL_TEXTURE_MIN_FILTER

The texture minifying function is used whenever the pixel being textured maps to an area greater than one texture element. There are six defined minifying functions. Two of them use the nearest one or nearest four texture elements to compute the texture value. The other four use mipmaps.

A mipmap is an ordered set of arrays representing the same image at progressively lower resolutions. If the texture has dimensions 2^nx2^m there are max(n, m) + 1 mipmaps. The first mipmap is the original texture, with dimensions 2^nx2^m. Each subsequent mipmap has dimensions 2^k−1x2^l−1 where 2^kx2^l are the dimensions of the previous mipmap, until either k = 0 or l = 0. At that point, subsequent mipmaps have dimension 1x2^l−1 or 2^k−1x1 until the final mipmap, which has dimension 1x1. Mipmaps are defined using glTexImage1D or glTexImage2D with the level-of-detail argument indicating the order of the mipmaps. Level 0 is the original texture; level bold max(n, m) is the final 1x1 mipmap.

GL_TEXTURE_MAG_FILTER

The texture magnification function is used when the pixel being textured maps to an area less than or equal to one texture element. It sets the texture magnification function to either GL_NEAREST or GL_LINEAR.

GL_TEXTURE_WRAP_S

Sets the wrap parameter for texture coordinate s to either GL_CLAMP or GL_REPEAT. GL_CLAMP causes s coordinates to be clamped to the range [0,1] and is useful for preventing wrapping artifacts when mapping a single image onto an object. GL_REPEAT causes the integer part of the s coordinate to be ignored; OpenGL uses only the fractional part, thereby creating a repeating pattern. Border texture elements are accessed only if wrapping is set to GL_CLAMP. Initially, GL_TEXTURE_WRAP_S is set to GL_REPEAT.

GL_TEXTURE_WRAP_T

Sets the wrap parameter for texture coordinate t to either GL_CLAMP or GL_REPEAT. See the discussion under GL_TEXTURE_WRAP_S. Initially, GL_TEXTURE_WRAP_T is set to GL_REPEAT.

param

The value of pname.

void glTexParameterfv(

GLenum target,
GLenum pname,
const GLfloat *params
);
void glTexParameteriv(

GLenum target,
GLenum pname,
const GLint *params
);
Parameters

target

The target texture, which must be either GL_TEXTURE_1D or GL_TEXTURE_2D.

pname

The symbolic name of a texture parameter. The following symbols are accepted in pname:

GL_TEXTURE_MIN_FILTER

The texture minifying function is used whenever the pixel being textured maps to an area greater than one texture element. There are six defined minifying functions. Two of them use the nearest one or nearest four texture elements to compute the texture value. The other four use mipmaps.

A mipmap is an ordered set of arrays representing the same image at progressively lower resolutions. If the texture has dimensions 2^nx2^m there are max(n, m) + 1 mipmaps. The first mipmap is the original texture, with dimensions 2^nx2^m. Each subsequent mipmap has dimensions 2^k−1x2^l−1 where 2^kx2^l are the dimensions of the previous mipmap, until either k = 0 or l = 0. At that point, subsequent mipmaps have dimension 1x2^l−1 or 2^k−1x1 until the final mipmap, which has dimension 1x1. Mipmaps are defined using glTexImage1D or glTexImage2D with the level-of-detail argument indicating the order of the mipmaps. Level 0 is the original texture; level bold max(n, m) is the final 1x1 mipmap.

GL_TEXTURE_MAG_FILTER

The texture magnification function is used when the pixel being textured maps to an area less than or equal to one texture element. It sets the texture magnification function to either GL_NEAREST or GL_LINEAR.

GL_TEXTURE_WRAP_S

Sets the wrap parameter for texture coordinate s to either GL_CLAMP or GL_REPEAT. GL_CLAMP causes s coordinates to be clamped to the range [0,1] and is useful for preventing wrapping artifacts when mapping a single image onto an object. GL_REPEAT causes the integer part of the s coordinate to be ignored; OpenGL uses only the fractional part, thereby creating a repeating pattern. Border texture elements are accessed only if wrapping is set to GL_CLAMP. Initially, GL_TEXTURE_WRAP_S is set to GL_REPEAT.

GL_TEXTURE_WRAP_T

Sets the wrap parameter for texture coordinate t to either GL_CLAMP or GL_REPEAT. See the discussion under GL_TEXTURE_WRAP_S. Initially, GL_TEXTURE_WRAP_T is set to GL_REPEAT.

GL_TEXTURE_BORDER_COLOR

Sets a border color. The params parameter contains four values that comprise the RGBA color of the texture border. Integer color components are interpreted linearly such that the most positive integer maps to 1.0, and the most negative integer maps to −1.0. The values are clamped to the range [0,1] when they are specified. Initially, the border color is (0, 0, 0, 0).

params

A pointer to an array where the value or values of pname are stored. The params parameter supplies a function for minifying the texture as one of the following:

GL_NEAREST

Returns the value of the texture element that is nearest (in Manhattan distance) to the center of the pixel being textured.

GL_LINEAR

Returns the weighted average of the four texture elements that are closest to the center of the pixel being textured. These can include border texture elements, depending on the values of GL_TEXTURE_WRAP_S, GL_TEXTURE_WRAP_T, and on the exact mapping. GL_NEAREST is generally faster than GL_LINEAR, but it can produce textured images with sharper edges because the transition between texture elements is not as smooth. The default value of GL_TEXTURE_MAG_FILTER is GL_LINEAR.

GL_NEAREST_MIPMAP_NEAREST

Chooses the mipmap that most closely matches the size of the pixel being textured and uses the GL_NEAREST criterion (the texture element nearest to the center of the pixel) to produce a texture value.

GL_LINEAR_MIPMAP_NEAREST

Chooses the mipmap that most closely matches the size of the pixel being textured and uses the GL_LINEAR criterion (a weighted average of the four texture elements that are closest to the center of the pixel) to produce a texture value.

GL_NEAREST_MIPMAP_LINEAR

Chooses the two mipmaps that most closely match the size of the pixel being textured and uses the GL_NEAREST criterion (the texture element nearest to the center of the pixel) to produce a texture value from each mipmap. The final texture value is a weighted average of those two values.

GL_LINEAR_MIPMAP_LINEAR

Chooses the two mipmaps that most closely match the size of the pixel being textured and uses the GL_LINEAR criterion (a weighted average of the four texture elements that are closest to the center of the pixel) to produce a texture value from each mipmap. The final texture value is a weighted average of those two values.

Remarks

Texture mapping is a technique that applies an image onto an object’s surface as if the image were a decal or cellophane shrink-wrap. The image is created in texture space, with an (s, t) coordinate system. A texture is a one- or two-dimensional image and a set of parameters that determine how samples are derived from the image.

The glTexParameter function assigns the value or values in params to the texture parameter specified as pname. The target parameter defines the target texture, either GL_TEXTURE_1D or GL_TEXTURE_2D.

As more texture elements are sampled in the minification process, fewer aliasing artifacts will be apparent. While the GL_NEAREST and GL_LINEAR minification functions can be faster than the other four, they sample only one or four texture elements to determine the texture value of the pixel being rendered and can produce moire patterns or ragged transitions. The default value of GL_TEXTURE_MIN_FILTER is GL_NEAREST_MIPMAP_LINEAR.

Suppose texturing is enabled (by calling glEnable with argument GL_TEXTURE_1D or GL_TEXTURE_2D) and GL_TEXTURE_MIN_FILTER is set to one of the functions that requires a mipmap. If either the dimensions of the texture images currently defined (with previous calls to glTexImage1D or glTexImage2D) do not follow the proper sequence for mipmaps, or there are fewer texture images defined than are needed, or the set of texture images have differing numbers of texture components, then it is as if texture mapping were disabled.

Linear filtering accesses the four nearest texture elements only in 2-D textures. In 1-D textures, linear filtering accesses the two nearest texture elements.

The following function retrieves information related to glTexParameterf, glTexParameteri, glTexParameterfv, and glTexParameteriv:

glGetTexParameter

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target or pname was not one of the accepted defined values, or when params should have had a defined constant value (based on the value of pname) and did not.
GL_INVALID_OPERATION	glTexParameter was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glGetTexParameter, glTexEnv, glTexGen, glTexImage1D, glTexImage2D


glTexSubImage1D [New - Windows 95, OEM Service Release 2]
glTexSubImage1D

[New - Windows 95, OEM Service Release 2]

The glTexSubImage1D function specifies a portion of an existing one-dimensional texture image. You cannot define a new texture with glTexSubImage1D.

void glTexSubImage1D(

GLenum target,
GLint level,
GLint xoffset,
GLsizei width,
GLenum format,
GLenum type,
const GLvoid *pixels
);
Parameters

target

The target texture. Must be GL_TEXTURE_1D.

level

The level-of-detail number. Level 0 is the base image. Level n is the nth mipmap reduction image.

xoffset

A texel offset in the x direction within the texture array.

width

The width of the texture sub-image.

format

The format of the pixel data. This parameter can assume one of the following symbolic values:

GL_COLOR_INDEX

Each element is a single value, a color index. It is converted to fixed point format (with an unspecified number of 0 bits to the right of the binary point), shifted left or right depending on the value and sign of GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET (see glPixelTransfer). The resulting index is converted to a set of color components using the GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, and GL_PIXEL_MAP_I_TO_A tables, and clamped to the range [0,1].

GL_RED

Each element is a single red component. It is converted to floating point format and assembled into an RGBA element by attaching 0.0 for green and blue, and 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_GREEN

Each element is a single green component. It is converted to floating point format and assembled into an RGBA element by attaching 0.0 for red and blue, and 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_BLUE

Each element is a single blue component. It is converted to floating point format and assembled into an RGBA element by attaching 0.0 for red and green, and 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_ALPHA

Each element is a single alpha component. It is converted to floating point format and assembled into an RGBA element by attaching 0.0 for red, green, and blue. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_RGB

Each element is an RGB triple. It is converted to floating point and assembled into an RGBA element by attaching 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_RGBA

Each element is a complete RGBA element. It is converted to floating point format. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_LUMINANCE

Each element is a single luminance value. It is converted to floating point format, and then assembled into an RGBA element by replicating the luminance value three times for red, green, and blue, and attaching 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_LUMINANCE_ALPHA

Each element is a luminance/alpha pair. It is converted to floating point format, and then assembled into an RGBA element by replicating the luminance value three times for red, green, and blue. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

type

The data type of the pixel data. The following symbolic values are accepted: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, and GL_FLOAT.

pixels

A pointer to the image data in memory.

Remarks

One-dimensional texturing for a primitive is enabled using glEnable and glDisable with the argument GL_TEXTURE_1D. During texturing, part of a specified texture image is mapped onto each enabled primitive. You use the glTexSubImage1D function to specify a contiguous sub-image of an existing one-dimensional texture image for texturing.

The texels referenced by pixels replace a region of the existing texture array with x indexes of xoffset and xoffset + (width − 1) inclusive. This region cannot include any texels outside the range of the originally specified texture array.

Specifying a sub-image with a width of zero has no effect and does not generate an error.

Texturing has no effect in color-index mode.

In general, texture images can be represented by the same data formats as the pixels in a glDrawPixels command, except that GL_STENCIL_INDEX and GL_DEPTH_COMPONENT cannot be used. The glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.

The following functions retrieve information related to glTexSubImage1D:

glGetTexImage

glIsEnabled with argument GL_TEXTURE_1D

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target was not GL_TEXTURE_1D.
GL_INVALID_ENUM	format was not an accepted constant.
GL_INVALID_ENUM	type was not a constant.
GL_INVALID_ENUM	type was GL_BITMAP and format was not GL_COLOR_INDEX.
GL_INVALID_VALUE	level was less than zero or greater than log (2) max, where max was the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE	xoffset was less than −b, or xoffset + width was greater than w − b, where w is the GL_TEXTURE_WIDTH, and b is the width of the GL_TEXTURE_BORDER of the texture image being modified. Note that w includes twice the border width.
GL_INVALID_VALUE	width was less than −b, where b is the border width of the texture array.
GL_INVALID_VALUE	border was not zero or 1.
GL_INVALID_OPERATION	The texture array was not defined by a previous glTexImage1D operation.
GL_INVALID_OPERATION	glTexSubImage1D was called between a call to glBegin and the corresponding call to glEnd.
See Also

glDrawPixels, glEnable, glFog, glGetTexImage, glIsEnabled, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage1D, glTexParameter


glTexSubImage2D [New - Windows 95, OEM Service Release 2]
glTexSubImage2D

[New - Windows 95, OEM Service Release 2]

The glTexSubImage2D function specifies a portion of an existing one-dimensional texture image. You cannot define a new texture with glTexSubImage2D.

void glTexSubImage2D(

GLenum target,
GLint level,
GLint xoffset,
GLint yoffset,
GLsizei width,
GLsizei height,
GLenum format,
GLenum type,
const GLvoid *pixels
);
Parameters

target

The target texture. Must be GL_TEXTURE_2D.

level

The level-of-detail number. Level 0 is the base image. Level n is the nth mipmap reduction image.

xoffset

A texel offset in the x direction within the texture array.

yoffset

A texel offset in the y direction within the texture array.

width

The width of the texture sub-image.

height

The height of the texture sub-image.

format

The format of the pixel data. It can assume one of the following symbolic values:

GL_COLOR_INDEX

Each element is a single value, a color index. It is converted to fixed point format (with an unspecified number of 0 bits to the right of the binary point), shifted left or right depending on the value and sign of GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET (see glPixelTransfer). The resulting index is converted to a set of color components using the GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, and GL_PIXEL_MAP_I_TO_A tables, and clamped to the range [0,1].

GL_RED

Each element is a single red component. It is converted to floating point format and assembled into an RGBA element by attaching 0.0 for green and blue, and 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_GREEN

Each element is a single green component. It is converted to floating point format and assembled into an RGBA element by attaching 0.0 for red and blue, and 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_BLUE

Each element is a single blue component. It is converted to floating point format and assembled into an RGBA element by attaching 0.0 for red and green, and 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_ALPHA

Each element is a single alpha component. It is converted to floating point format and assembled into an RGBA element by attaching 0.0 for red, green, and blue. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_RGB

Each element is an RGB triple. It is converted to floating point format and assembled into an RGBA element by attaching 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_RGBA

Each element is a complete RGBA element. It is converted to floating point. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_LUMINANCE

Each element is a single luminance value. It is converted to floating point format, and then assembled into an RGBA element by replicating the luminance value three times for red, green, and blue, and attaching 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

GL_LUMINANCE_ALPHA

Each element is a luminance/alpha pair. It is converted to floating point format, and then assembled into an RGBA element by replicating the luminance value three times for red, green, and blue. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

type

The data type of the pixel data. The following symbolic values are accepted: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, and GL_FLOAT.

pixels

A pointer to the image data in memory.

Remarks

Two-dimensional texturing for a primitive is enabled using glEnable and glDisable with the argument GL_TEXTURE_2D. During texturing, part of a specified texture image is mapped onto each enabled primitive. You use the glTexSubImage2D function to specify a contiguous sub-image of an existing one-dimensional texture image for texturing.

The texels referenced by pixels replace a region of the existing texture array with x indexes of xoffset and xoffset + (width − 1) inclusive and y indexes of yoffset and Yoffset + (height − 1) inclusive. This region cannot include any texels outside the range of the originally specified texture array.

Specifying a sub-image with a width of zero has no effect and does not generate an error.

Texturing has no effect in color-index mode.

In general, texture images can be represented by the same data formats as the pixels in a glDrawPixels command, except that GL_STENCIL_INDEX and GL_DEPTH_COMPONENT cannot be used. The glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.

The following functions retrieve information related to glTexSubImage2D:

glGetTexImage

glIsEnabled with argument GL_TEXTURE_2D

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_ENUM	target was not GL_TEXTURE_2D.
GL_INVALID_ENUM	format was not an accepted constant.
GL_INVALID_ENUM	type was not an accepted constant.
GL_INVALID_ENUM	type was GL_BITMAP and format was not GL_COLOR_INDEX.
GL_INVALID_VALUE	level was less than zero or greater than log (2) max, where max was the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE	xoffset was less than -b; or xoffset + width was greater than w - b; or yoffset was less than -b; or yoffset + height was greater than h - b, where w is the GL_TEXTURE_WIDTH, h is the GL_TEXTURE_HEIGHT, and b is the width of the GL_TEXTURE_BORDER of the texture image being modified. Note that w and h include twice the border width.
GL_INVALID_VALUE	width was less than -b, where b is the border width of the texture array.
GL_INVALID_VALUE	border was not zero or 1.
GL_INVALID_OPERATION	The texture array was not defined by a previous glTexImage2D operation.
GL_INVALID_OPERATION	glTexSubImage2D was called between a call to glBegin and the corresponding call to glEnd.
See Also

glDrawPixels, glEnable, glFog, glGetTexImage, glIsEnabled, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage2D, glTexParameter


glTranslate [New - Windows 95, OEM Service Release 2]
glTranslated, glTranslatef

[New - Windows 95, OEM Service Release 2]

The glTranslated and glTranslatef functions multiply the current matrix by a translation matrix.

void glTranslated(

GLdouble x,
GLdouble y,
GLdouble z
);
void glTranslatef(

GLfloat x,
GLfloat y,
GLfloat z
);
Parameters

x, y, z

The x, y, and z coordinates of a translation vector.

Remarks

The glTranslate function moves the coordinate system origin to the point specified by (x, y, z). The translation vector is used to compute a 4x4 translation matrix:

The current matrix (see glMatrixMode) is multiplied by this translation matrix, with the product replacing the current matrix. That is, if M is the current matrix and T is the translation matrix, then M is replaced with M•T.

If the matrix mode is either GL_MODELVIEW or GL_PROJECTION, all objects drawn after glTranslate is called are translated. Use glPushMatrix and glPopMatrix to save and restore the untranslated coordinate system.

The following functions retrieve information related to glTranslated and glTranslatef:

glGet with argument GL_MATRIX_MODE

glGet with argument GL_MODELVIEW_MATRIX

glGet with argument GL_PROJECTION_MATRIX

glGet with argument GL_TEXTURE_MATRIX

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_OPERATION	glTranslate was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glEnd, glMatrixMode, glMultMatrix, glPushMatrix, glRotate, glScale


glVertex [New - Windows 95, OEM Service Release 2]
glVertex

[New - Windows 95, OEM Service Release 2]

glVertex2d, glVertex2f, glVertex2i, glVertex2s, glVertex3d, glVertex3f, glVertex3i, glVertex3s, glVertex4d, glVertex4f, glVertex4i, glVertex4s, glVertex2dv, glVertex2fv, glVertex2iv, glVertex2sv, glVertex3dv, glVertex3fv, glVertex3iv, glVertex3sv, glVertex4dv, glVertex4fv, glVertex4iv, glVertex4sv

These functions specify a vertex.

void glVertex2d(

GLdouble x,
GLdouble y
);
void glVertex2f(

GLfloat x,
GLfloat y
);
void glVertex2i(

GLint x,
GLint y
);
void glVertex2s(

GLshort x,
GLshort y
);
void glVertex3d(

GLdouble x,
GLdouble y,
GLdouble z
);
void glVertex3f(

GLfloat x,
GLfloat y,
GLfloat z
);
void glVertex3i(

GLint x,
GLint y,
GLint z
);
void glVertex3s(

GLshort x,
GLshort y,
GLshort z
);
void glVertex4d(

GLdouble x,
GLdouble y,
GLdouble z,
GLdouble w
);
void glVertex4f(

GLfloat x,
GLfloat y,
GLfloat z,
GLfloat w
);
void glVertex4i(

GLint x,
GLint y,
GLint z,
GLint w
);
void glVertex4s(

GLshort x,
GLshort y,
GLshort z,
GLshort w
);
Parameters

x, y, z, w

The x, y, z, and w coordinates of a vertex. Not all parameters are present in all forms of the command.

void glVertex2dv(

const GLdouble *v
);
void glVertex2fv(

const GLfloat *v
);
void glVertex2iv(

const GLint *v
);
void glVertex2sv(

const GLshort *v
);
void glVertex3dv(

const GLdouble *v
);
void glVertex3fv(

const GLfloat *v
);
void glVertex3iv(

const GLint *v
);
void glVertex3sv(

const GLshort *v
);
void glVertex4dv(

const GLdouble *v
);
void glVertex4fv(

const GLfloat *v
);
void glVertex4iv(

const GLint *v
);
void glVertex4sv(

const GLshort *v
);
Parameters

v

A pointer to an array of two, three, or four elements. The elements of a two-element array are x and y; of a three-element array, x, y, and z; and of a four-element array, x, y, z, and w.

Remarks

The glVertex function commands are used within glBegin/glEnd pairs to specify point, line, and polygon vertices. The current color, normal, and texture coordinates are associated with the vertex when glVertex is called.

When only x and y are specified, z defaults to 0.0 and w defaults to 1.0. When x, y, and z are specified, w defaults to 1.0.

Invoking glVertex outside of a glBegin/glEnd pair results in undefined behavior.

See Also

glBegin, glCallList, glColor, glEdgeFlag, glEnd, glEvalCoord, glIndex, glMaterial, glNormal, glRect, glTexCoord


glVertexPointer [New - Windows 95, OEM Service Release 2]
glVertexPointer

[New - Windows 95, OEM Service Release 2]

The glVertexPointer function defines an array of vertex data.

void glVertexPointer(

GLint size,
GLenum type,
GLsizei stride,
GLsizei count,
const GLvoid *pointer
);
Parameters

size

The number of coordinates per vertex. The value of size must be 2, 3, or 4.

type

The data type of each coordinate in the array using the following symbolic constants: GL_SHORT, GL_INT, GL_FLOAT, and GL_DOUBLE.

stride

The byte offset between consecutive vertices. When stride is zero, the vertices are tightly packed in the array.

count

The number of vertices, counting from the first, that are static.

pointer

A pointer to the first coordinate of the first vertex in the array.

Remarks

The glVertexPointer function specifies the location and data of an array of vertex coordinates to use when rendering. The size parameter specifies the number of coordinates per vertex. The type parameter specifies the data type of each vertex coordinate. The stride parameter determines the byte offset from one vertex to the next, enabling the packing of vertices and attributes in a single array or storage in separate arrays. In some implementations, storing the vertices and attributes in a single array can be more efficient than using separate arrays. Starting from the first vertex element, the count parameter indicates the total number of static elements. Your application can modify static elements, but once the elements are modified, the application must explicitly specify the array again before using the array for any rendering. Non-static array elements are not accessed until you call glDrawArrays or glArrayElement.

A vertex array is enabled when you specify the GL_VERTEX_ARRAY constant with glEnableClientState. When enabled, glDrawArrays and glArrayElement use the vertex array. By default, the vertex array is disabled.

You cannot include glVertexPointer in display lists.

When you specify a vertex array using glVertexPointer, the values of all the function’s vertex array parameters are saved in a client-side state and static array elements can be cached. Because the vertex array parameters are client-side state, their values are not saved or restored by glPushAttrib and glPopAttrib.

Although no error is generated if you call glVertexPointer within glBegin and glEnd pairs, the results are undefined.

The following functions retrieve information related to glVertexPointer:

glGet with argument GL_VERTEX_ARRAY_SIZE

glGet with argument GL_VERTEX_ARRAY_STRIDE

glGet with argument GL_VERTEX_ARRAY_COUNT

glGet with argument GL_VERTEX_ARRAY_TYPE

glGetPointerv with argument GL_VERTEX_ARRAY_POINTER

glIsEnabled with argument GL_VERTEX_ARRAY

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	size was not 2, 3, or 4.
GL_INVALID_ENUM	type was not an accepted value.
GL_INVALID_VALUE	stride or count was negative.
See Also

glArrayElement, glColorPointer, glDrawArrays, glEdgeFlagPointer, glEnableClientState, glGetPointerv, glGetString, glIndexPointer, glIsEnabled, glNormalPointer, glTexCoordPointer


glViewport [New - Windows 95, OEM Service Release 2]
glViewport

[New - Windows 95, OEM Service Release 2]

The glViewport function sets the viewport.

void glViewport(

GLint x,
GLint y,
GLsizei width,
GLsizei height
);
Parameters

x, y

The lower-left corner of the viewport rectangle, in pixels. The default is (0,0).

width, height

The width and height, respectively, of the viewport. When an OpenGL context is first attached to a window, width and height are set to the dimensions of that window.

Remarks

The glViewport function specifies the affine transformation of x and y from normalized device coordinates to window coordinates. Let (x (nd) , y (nd) ) be normalized device coordinates. The window coordinates (x (w) , y (w) ) are then computed as follows:

Viewport width and height are silently clamped to a range that depends on the implementation. This range is queried by calling glGet with argument GL_MAX_VIEWPORT_DIMS.

The following functions retrieve information related to glViewport:

glGet with argument GL_VIEWPORT

glGet with argument GL_MAX_VIEWPORT_DIMS

Error Codes

The following are the error codes generated and their conditions.

Error Code	Condition
GL_INVALID_VALUE	Either width or height was negative.
GL_INVALID_OPERATION	glViewport was called between a call to glBegin and the corresponding call to glEnd.
See Also

glBegin, glDepthRange


A

aliasing

A rendering technique that assigns to pixels the color of the primitive being rendered, regardless of whether that primitive covers all of the pixel’s area or only a portion of the pixel’s area. This results in jagged edges, or jaggies.

alpha

A fourth color component typically used to control color blending. The alpha component is never displayed directly. By convention, OpenGL alpha corresponds to opacity rather than transparency, meaning an alpha value of 1.0 implies complete opacity, and an alpha value of 0.0 implies complete transparency.

animation

The generation of repeated renderings of a scene quickly enough, with smoothly changing viewpoint or object positions, so that the illusion of motion is achieved. OpenGL animation almost always uses double-buffering.

antialiasing

A rendering technique that assigns colors to pixels based on the fraction of the pixel area that is covered by the primitive being rendered. Antialiased rendering reduces or eliminates the jaggies that result from aliased rendering. See also jaggies, rendering.

application-specific clipping

Clipping of primitives against planes in eye coordinates. The planes are specified by the application using glClipPlane. See also eye coordinates.


B

back face

See face.

bit

Binary digit. A state variable that has only two possible values: 0 or 1. Binary numbers are constructions of one or more bits.

bitmap

A rectangular array of bits. Also, the primitive rendered by the glBitmap command, which uses its bitmap parameter as a mask.

bitplane

A rectangular array of bits mapped one-to-one with pixels.

blending

Reducing two color components to one component, usually as a linear interpolation between the two components.

buffer

A group of bitplanes that store a single component (such as depth or green) or a single index (such as the color index or the stencil index). Sometimes the red, green, blue, and alpha buffers together are referred to as the color buffer, rather than the color buffers.


C

client

The computer from which OpenGL commands are issued. The computer that issues OpenGL commands can be connected through a network to a different computer that executes the commands, or commands can be issued and executed on the same computer. See also server.

client memory

The main memory (where program variables are stored) of the client computer.

clip coordinates

The coordinate system that follows transformation by the projection matrix and that precedes perspective division. View-volume clipping is done in clip coordinates, but application-specific clipping is not. See also application-specific clipping.

clipping

Eliminating the portion of a geometric primitive that is outside the half-space defined by a clipping plane. Points are simply rejected if outside. The portion of a line or of a polygon that is outside the half-space is eliminated, and additional vertices are generated as necessary to complete the primitive within the clipping half-space. Geometric primitives and the current raster position (when specified) are always clipped against the six half-spaces defined by the left, right, bottom, top, near, and far planes of the view volume. Applications can specify optional application-specific clipping planes to be applied in eye coordinates.

color index

A single value that represents a color by name, rather than by value. OpenGL color indexes are treated as continuous values (for example, floating-point numbers) while operations such as interpolation and dithering are performed on them. Color indexes stored in the frame buffer are always integer values, however. Floating-point indexes are converted to integers by rounding to the nearest integer value.

color-index mode

Mode of an OpenGL context in which its color buffers store color indexes, rather than red, green, blue, and alpha color components.

color map

A table of index-to-RGB mappings that is accessed by the display hardware. Each color index is read from the color buffer, converted to an RGB triple by lookup in the color map, and sent to the monitor.

component

A single, continuous (for example, floating-point) value that represents an intensity or quantity. Usually, a component value of zero represents the minimum value or intensity, and a component value of one represents the maximum value or intensity, though other normalizations are sometimes used. Because component values are interpreted in a normalized range, they are specified independently of actual resolution. For example, the RGB triple (1, 1, 1) is white, regardless of whether the color buffers store 4, 8, or 12 bits each.

Out-of-range components are typically clamped to the normalized range, not truncated or otherwise interpreted. For example, the RGB triple (1.4, 1.5, 0.9) is clamped to (1.0, 1.0, 0.9) before it’s used to update the color buffer. Red, green, blue, alpha, and depth are always treated as components, never as indexes.

context

A complete set of OpenGL state variables. Note that frame buffer contents are not part of the OpenGL state, but that the configuration of the frame buffer is.

convex

Condition of a polygon in which no straight line in the plane of the polygon intersects the polygon more than twice.

convex hull

The smallest convex region enclosing a specified group of points. In two dimensions, the convex hull is found conceptually by stretching a rubber band around the points so that all of the points lie within the band.

coordinate system

In n-dimensional space, a set of n linearly independent vectors anchored to a point (called the origin). A group of coordinates specifies a point in space (or a vector from the origin) by indicating how far to travel along each vector to reach the point (or tip of the vector).

culling

The process of eliminating a front face or back face of a polygon so that the face isn’t drawn.

current matrix

A matrix that transforms coordinates in one coordinate system to coordinates of another system. There are three current matrices in OpenGL: the modelview matrix, which transforms object coordinates (coordinates specified by the programmer) to eye coordinates; the perspective matrix, which transforms eye coordinates to clip coordinates; and the texture matrix, which transforms specified or generated texture coordinates as described by the matrix. Each current matrix is the top element on a stack of matrices. Each of the three stacks can be manipulated with OpenGL matrix-manipulation commands.

current raster position

A window coordinate position that specifies the placement of an image primitive when it’s rasterized. The current raster position, and other current raster parameters, are updated when glRasterpos is called.


D

depth

Generally refers to the z window coordinate.

depth-cueing

A rendering technique that assigns color based on distance from the viewpoint.

display list

A named list of OpenGL commands. Display lists are always stored on the server, so display lists can be used to reduce the network traffic in client/server environments. The contents of a display list may be preprocessed, and might therefore execute more efficiently than the same set of OpenGL commands executed in immediate mode. Such preprocessing is especially important for computing intensive commands such as glTexImage.

dithering

A technique for increasing the perceived range of colors in an image at the cost of spatial resolution. Adjacent pixels are assigned differing color values. When viewed from a distance, these colors seem to blend into a single intermediate color. The technique is similar to the half-toning used in black-and-white publications to achieve shades of gray.

double-buffering

Using OpenGL contexts in which both front and back color buffers are double-buffered. Smooth animation is accomplished by rendering into only the back buffer (which isn’t displayed), then causing the front and back buffers to be swapped.


E

element

A single component or index.

evaluation

The OpenGL process of generating object-coordinate vertices and parameters from previously specified Bézier equations.

execute

To call an OpenGL command in immediate mode or to call the display list that the command is a part of.

eye coordinates

The coordinate system that follows transformation by the modelview matrix and that precedes transformation by the projection matrix. Lighting and application-specific clipping are done in eye coordinates.


F

face

One side of a polygon. Each polygon has two faces: a front face and a back face. Only one face is ever visible in the window. Whether the back or front face is visible is effectively determined after the polygon is projected onto the window. After this projection, if the polygon’s edges are directed clockwise, one of the faces is visible; if directed counterclockwise, the other face is visible. Whether clockwise corresponds to front or back (and counterclockwise corresponds to back or front) is determined by the OpenGL programmer.

flat shading

Refers to coloring a primitive with a single, constant color across its extent, rather than smoothly interpolating colors across the primitive. See Gouraud shading.

fog

A rendering technique that can be used to simulate atmospheric effects such as haze, fog, and smog by fading object colors to a background color based on distance from the viewer. Fog also aids in the perception of distance from the viewer, giving a depth cue. See also depth-cueing.

font

A group of graphical character representations usually used to display strings of text. The characters may be roman letters, mathematical symbols, Asian ideograms, Egyptian hieroglyphs, and so on.

fragment

Graphic data generated by the rasterization of primitives. Each fragment corresponds to a single pixel and includes color, depth, and sometimes texture-coordinate values.

frame buffer

A stack of bitplanes. All the buffers of a given window or context. Sometimes includes all the pixel memory of the graphics hardware accelerator. See also bitplane.

front face

See face.

frustum

The view volume warped by perspective division.


G

gamma correction

A function applied to colors stored in the frame buffer to correct for the nonlinear response of the eye (and sometimes of the monitor) to linear changes in color-intensity values.

geometric model

The object-coordinate vertices and parameters that describe an object. Note that OpenGL doesn’t define a syntax for geometric models, but rather a syntax and semantics for the rendering of geometric models.

geometric object

A geometric model.

geometric primitive

A point, line, or polygon.

Gouraud shading

Smooth interpolation of colors across a polygon or line segment. Colors are assigned at vertices and linearly interpolated across the primitive to produce a relatively smooth variation in color. Also called smooth shading.

group

A group of one, two, three, or four elements that represents each pixel of an image in client memory. Thus, in the context of a client memory image, a group and a pixel are the same thing.


H

half-space

The result of a plane dividing space. A plane divides space into two half-spaces.

homogenous coordinates

A set of n+1 coordinates used to represent points in n-dimensional projective space. Points in projective space can be thought of as points in Euclidean space together with some points at infinity. The coordinates are homogenous because a scaling of each of the coordinates by the same non-zero constant doesn’t alter the point to which the coordinates refer. Homogeneous coordinates are useful in the calculations of projective geometry, and thus in computer graphics, where scenes must be projected onto a window.


I

image

A rectangular array of pixels, either in client memory or in the frame buffer.

image primitive

A bitmap or an image.

immediate mode

Mode in which an OpenGL command is called directly, rather than from a display list. No immediate-mode bit exists; the mode in immediate mode refers to usage of OpenGL, rather than to a specific bit of OpenGL state.

index

A single value that is interpreted as an absolute value, rather than as a normalized value in a specified range (as is a component). Color indexes are the names of colors, which are dereferenced by the display hardware using the color map. Indexes are typically masked, rather than clamped, when out of range. For example, the index 0xf7 is masked to 0x7 when written to a 4-bit buffer (color or stencil). Color indexes and stencil indexes are always treated as indexes, never as components.

IRIS GL

Silicon Graphics’ proprietary graphics library, developed from 1982 through 1992. OpenGL was designed with IRIS GL as a starting point.


JK

jaggies

Artifacts of aliased rendering. The edges of primitives that are rendered with aliasing are jagged rather than smooth. A near-horizontal aliased line, for example, is rendered as a set of horizontal lines on adjacent pixel rows, rather than as a smooth, continuous line.


L

lighting

The process of computing the color of a vertex based on current lights, material properties, and lighting-model modes.

line

A straight region of finite width between two vertices. (Unlike mathematical lines, OpenGL lines have finite width and length.) Each segment of a strip of lines is itself a line.

luminance

The perceived brightness of a surface. Often refers to a weighted average of red, green, and blue color values that gives the perceived brightness of the combination.


M

matrices

Plural of matrix. See matrix.

matrix

A two-dimensional array of values. OpenGL matrices are all 4x4, though when they are stored in client memory they’re treated as 1x16 single-dimension arrays.

modelview matrix

The 4x4 matrix that transforms points, lines, polygons, and raster positions from object coordinates to eye coordinates.

monitor

The device that displays the image in the frame buffer.

motion blurring

A technique that simulates what you get on a piece of film when you take a picture of a moving object, or when you move the camera when you take a picture of a stationary object. In animations without motion blur, object motion can appear jerky.


N

network

A connection between two or more computers that allows each to transfer data to and from the others.

nonconvex

A state of a polygon in which a line in the plane of the polygon intersects the polygon more than twice.

normal

A three-component plane equation that defines the angular orientation, but not position, of a plane or surface.

normalize

To divide each of the components of a normal by the square root of the sum of their squares. Then, if the normal is thought of as a vector from the origin to the point (nx′, ny′, nx′), this vector has unit length:

nx′ = nx/factor
ny′ = ny/factor
nz′ = nz/factor

normal vector

See normal.

NURBS

Non-Uniform Rational B-Spline. A common way to specify parametric curves and surfaces.


O

object

An object-coordinate model that is rendered as a collection of primitives.

object coordinates

Coordinate system prior to any OpenGL transformation.

orthographic

Nonperspective projection, as in some engineering drawings, with no foreshortening.


P

parameter

A value passed as an argument to an OpenGL command. Sometimes one of the values passed by reference to an OpenGL command.

perspective division

The division of x, y, and z by w, carried out in clip coordinates. See also clip coordinates.

pixel

Picture element. The bits at location (x, y) of all the bitplanes in the frame buffer constitute the single pixel (x, y). In an image in client memory, a pixel is one group of elements. In OpenGL window coordinates, each pixel corresponds to a 1.0x1.0 screen area. The coordinates of the lower left corner of the pixel names x, y are (x, y), and the upper right corner are (x+1, y+1).

point

An exact location in space, which is rendered as a finite-diameter dot.

polygon

A near-planar surface bounded by edges specified by vertices. Each triangle of a triangle mesh is a polygon, as is each quadrilateral of a quadrilateral mesh. The rectangle specified by glRect is also a polygon.

primitive

A shape (such as a point, line, polygon, bitmap or image) that can be drawn, stored, and manipulated as a discrete entity; elements from which large graphic designs are created.

projection matrix

The 4x4 matrix that transforms points, lines, polygons, and raster positions from eye coordinates to clip coordinates.


Q

quadrilateral

A polygon with four edges.


R

rasterize

To convert a projected point, line, or polygon, or the pixels of a bitmap or image, to fragments, each corresponding to a pixel in the frame buffer. Note that all primitives are rasterized, not just points, lines, and polygons.

rectangle

A quadrilateral whose alternate edges are parallel to each other in object coordinates. Polygons specified with glRect*( ) are always rectangles; other quadrilaterals might be rectangles.

rendering

Conversion of primitives specified in object coordinates to an image in the frame buffer. Rendering is the primary operation of OpenGL.

RGBA

The red, green, blue, and alpha color components of the RGBA mode.

RGBA mode

An OpenGL context in which its color buffers store red, green, blue, and alpha color components, rather than color indexes.


S

server

The computer on which OpenGL commands are executed. This might differ from the computer from which commands are issued. See also client.

shading

The process of interpolating color within the interior of a polygon, or between the vertices of a line, during rasterization.

single-buffering

An OpenGL context without a back color buffer.

stipple

A one- or two-dimensional binary pattern that defeats the generation of fragments where its value is zero. Line stipples are one-dimensional and are applied relative to the start of a line. Polygon stipples are two-dimensional and are applied with a fixed orientation to the window.


T

tessellation

Reduction of a portion of an analytic surface to a mesh of polygons, or of a portion of an analytic curve to a sequence of lines.

texel

A texture element. A texel is obtained from texture memory and represents the color of the texture to be applied to a corresponding fragment. See also fragment.

texture

A one- or two-dimensional image used to modify the color of fragments produced by rasterization. See also rasterize.

texture mapping

The process of applying an image (the texture) to a primitive. Texture mapping is often used to add realism to a scene. For example, you could apply a picture of a building facade to a polygon representing a wall. See also texture.

texture matrix

The 4x4 matrix that transforms texture coordinates from the coordinates that they’re specified in to the coordinates that are used for interpolation and texture lookup.

transformation

A warping of space. In OpenGL, transformations are limited to projective transformations that include anything that can be represented by a 4x4 matrix. Such transformations include rotations, translations, (nonuniform) scalings along the coordinate axes, perspective transformations, and combinations of these.

triangle

A polygon with three edges. Triangles are always convex.


U V

vertex

A point in three-dimensional space.

vertices

Preferred plural of vertex. See vertex.

viewpoint

The origin of either the eye- or the clip-coordinate system, depending on context. For example, when discussing lighting, the viewpoint is the origin of the eye-coordinate system. When discussing projection, the viewpoint is the origin of the clip-coordinate system. With a typical projection matrix, the eye-coordinate and clip-coordinate origins are at the same location.

view volume

The volume in clip coordinates whose coordinates satisfy the three conditions

 − w ≤ x ≤ w
 − w ≤ y ≤ w
 − w ≤ z ≤ w


W

window

A subregion of the frame buffer, usually rectangular, whose pixels all have the same buffer configuration. An OpenGL context renders to one window at a time.

window-aligned

When referring to line segments or polygon edges, implies that these are parallel to the window boundaries. (In OpenGL, the window is rectangular, with horizontal and vertical edges). When referring to a polygon pattern, implies that the pattern is fixed relative to the window origin.

window coordinates

The coordinate system of a window. It’s important to distinguish between the names of pixels, which are discrete, and the window-coordinate system, which is continuous. For example, the pixel at the lower-left corner of a window is pixel (0, 0); the window coordinates of the center of this pixel are (0.5, 0.5, z). Note that window coordinates include a depth, or z, component, and that this component is continuous as well.

wireframe

A representation of an object that contains line segments only. Typically, the line segments indicate polygon edges.


X Y Z

X Window System

A window system used by many of the machines on which OpenGL is implemented.


gluBeginCurve, gluEndCurve [New - Windows 95, OEM Service Release 2]
gluBeginCurve, gluEndCurve

[New - Windows 95, OEM Service Release 2]

The gluBeginCurve and gluEndCurve functions delimit a NURBS curve definition.

void gluBeginCurve(

GLUnurbsObj * nobj
);
void gluEndCurve(

GLUnurbsObj * nobj
);
Parameters

nobj

The NURBS object (created with gluNewNurbsRenderer).

Remarks

Use gluBeginCurve to mark the beginning of a NURBS curve definition. After calling gluBeginCurve, make one or more calls to gluNurbsCurve to define the attributes of the curve. Exactly one of the calls to gluNurbsCurve must have a curve type of GL_MAP1_VERTEX_3 or GL_MAP1_VERTEX_4. To mark the end of the NURBS curve definition, call gluEndCurve.

OpenGL evaluators are used to render the NURBS curve as a series of line segments. Evaluator state is preserved during rendering with glPushAttrib(GL_EVAL_BIT) and glPopAttrib. For information on exactly what state these calls preserve, see glPushAttrib.

Example

The following functions render a textured NURBS curve with normals; texture coordinates and normals are also specified as NURBS curves:

gluBeginCurve(nobj);

gluNurbsCurve(nobj, . . ., GL_MAP1_TEXTURE_COORD_2);

gluNurbsCurve(nobj, . . ., GL_MAP1_NORMAL);

gluNurbsCurve(nobj, . . ., GL_MAP1_VERTEX_4);

gluEndCurve(nobj);

See Also

glPopAttrib, glPushAttrib, gluBeginSurface, gluBeginTrim, gluNewNurbsRenderer, gluNurbsCurve


gluBeginPolygon, gluEndPolygon [New - Windows 95, OEM Service Release 2]
gluBeginPolygon, gluEndPolygon

[New - Windows 95, OEM Service Release 2]

The gluBeginPolygon and gluEndPolygon functions delimit a polygon description.

void gluBeginPolygon(

GLUtesselator * tess
);
void gluEndPolygon(

GLUtesselator * tess
);
Parameters

tess

The tessellation object (created with gluNewTess).

Remarks

Use gluBeginPolygon and gluEndPolygon to delimit the definition of a nonconvex polygon.

To define such a polygon

1.	Call gluBeginPolygon.

2.	Define the contours of the polygon by calling gluTessVertex for each vertex and gluNextContour to start each new contour.

3.	Call gluEndPolygon to signal the end of the definition.

Once gluEndPolygon is called, the polygon is tessellated, and the resulting triangles are described through callbacks. For descriptions of the callback functions, see gluTessCallback.

Note  The gluBeginPolygon and gluEndPolygon functions are obsolete and are provided for backward compatibility only. The gluBeginPolygon function is mapped to gluTessBeginPolygon followed by gluTessBeginContour; gluEndPolygon is mapped to gluTessEndPolygon followed by gluTessEndContour.

Example

The following example describes a quadrilateral with a triangular hole:

gluBeginPolygon(tess);

    gluTessVertex(tess, v1, v1);

    gluTessVertex(tess, v2, v2);

    gluTessVertex(tess, v3, v3);

    gluTessVertex(tess, v4, v4);

gluNextContour(tess, GLU_INTERIOR);

    gluTessVertex(tess, v5, v5);

    gluTessVertex(tess, v6, v6);

    gluTessVertex(tess, v7, v7);

gluEndPolygon(tess);

See Also

gluNewTess, gluNextContour, gluTessBeginContour, gluTessBeginPolygon, gluTessCallback, gluTessVertex


gluBeginSurface, gluEndSurface [New - Windows 95, OEM Service Release 2]
gluBeginSurface, gluEndSurface

[New - Windows 95, OEM Service Release 2]

The gluBeginSurface and gluEndSurface functions delimit a NURBS surface definition.

void gluBeginSurface(

GLUnurbsObj * nobj
);
void gluEndSurface(

GLUnurbsObj * nobj
);
Parameters

nobj

The NURBS object (created with gluNewNurbsRenderer).

Remarks

The gluBeginSurface and gluEndSurface functions mark the beginning and end of NURBS surface definitions, which are defined with calls to gluNurbsSurface.

To define a surface

1.	Call gluBeginSurface to mark the beginning of a NURBS surface definition.

2.	Make one or more calls to gluNurbsSurface to define the attributes of the surface.

Exactly one of these calls to gluNurbsSurface must have a surface type of GL_MAP2_VERTEX_3 or GL_MAP2_VERTEX_4.

3.	To mark the end of the NURBS surface definition, call gluEndSurface.

The gluBeginTrim, gluPwlCurve, gluNurbsCurve, and gluEndTrim functions support trimming of NURBS surfaces. For more information, see gluBeginTrim.

Use OpenGL evaluators to render the NURBS surface as a set of polygons. Preserve the evaluator state during rendering with glPushAttrib(GL_EVAL_BIT) and glPopAttrib. For information on exactly what states these calls preserve, see glPushAttrib.

Example

The following functions render a textured NURBS surface with normals; the texture coordinates and normals are also described as NURBS surfaces:

gluBeginSurface(nobj);

    gluNurbsSurface(nobj, . . ., GL_MAP2_TEXTURE_COORD_2);

    gluNurbsSurface(nobj, . . ., GL_MAP2_NORMAL);

    gluNurbsSurface(nobj, . . ., GL_MAP2_VERTEX_4);

gluEndSurface(nobj);

See Also

gluBeginCurve, gluBeginTrim, gluNewNurbsRenderer, gluNurbsCurve, gluNurbsSurface, gluPwlCurve


gluBeginTrim, gluEndTrim [New - Windows 95, OEM Service Release 2]
gluBeginTrim, gluEndTrim

[New - Windows 95, OEM Service Release 2]

The gluBeginTrim and gluEndTrim functions delimit a NURBS trimming loop definition.

void gluBeginTrim(

GLUnurbsObj * nobj
);
void gluEndTrim(

GLUnurbsObj * nobj
);
Parameters

nobj

The NURBS object (created with gluNewNurbsRenderer).

Remarks

Use gluBeginTrim to mark the beginning of a trimming loop, and gluEndTrim to mark the end of a trimming loop. A trimming loop is a set of oriented curve segments (forming a closed curve) that define boundaries of a NURBS surface. You include these trimming loops in the definition of a NURBS surface, between calls to gluBeginSurface and gluEndSurface.

The definition for a NURBS surface can contain many trimming loops. For example, if you write a definition for a NURBS surface that resembles a rectangle with a hole punched out, the definition would contain two trimming loops. One loop would define the outer edge of the rectangle; the other would define the punched-out hole. The definitions of each of these trimming loops would be bracketed by a gluBeginTrim/gluEndTrim pair.

The definition of a single closed trimming loop can consist of multiple curve segments, each described as a series of line segments that form a linear curve (see gluPwlCurve), as a single NURBS curve (see gluNurbsCurve), or as a combination of both in any order. The only library calls that can appear in a trimming-loop definition (between the calls to gluBeginTrim and gluEndTrim) are gluPwlCurve and gluNurbsCurve.

The displayed area of the NURBS surface is the region in the domain to the left of the trimming curve as the curve parameter increases. Thus, the retained region of the NURBS surface is inside a counterclockwise trimming loop and outside a clockwise trimming loop. For the rectangle mentioned earlier, the trimming loop for the outer edge of the rectangle runs counterclockwise, while the trimming loop for the punched-out hole runs clockwise.

If you use more than one curve to define a single trimming loop, the curve segments must form a closed loop (that is, the endpoint of each curve must be the starting point of the next curve, and the endpoint of the final curve must be the starting point of the first curve). If the endpoints of the curve are sufficiently close together but not exactly coincident, they will be forced to match. If the endpoints are not sufficiently close, an error results (see gluNurbsCallback).

If a trimming-loop definition contains multiple curves, the direction of the curves must be consistent (that is, the inside must be to the left of all of the curves). You can use nested trimming loops as long as the curve orientations alternate correctly. Trimming curves cannot be self-intersecting, nor can they intersect one another (or an error results).

If no trimming information is given for a NURBS surface, the entire surface is drawn.

Example

This code fragment defines a trimming loop that consists of one piecewise linear curve and two NURBS curves:

gluBeginTrim(nobj);

    gluPwlCurve(. . ., GLU_MAP1_TRIM_2);

    gluNurbsCurve(. . ., GLU_MAP1_TRIM_2);

    gluNurbsCurve(. . ., GLU_MAP1_TRIM_3);

gluEndTrim(nobj);

See Also

gluBeginSurface, gluEndSurface, gluNewNurbsRenderer, gluNurbsCallback, gluNurbsCurve, gluPwlCurve


gluBuild1DMipmaps [New - Windows 95, OEM Service Release 2]
gluBuild1DMipmaps

[New - Windows 95, OEM Service Release 2]

The gluBuild1DMipmaps function creates 1-D mipmaps.

int gluBuild1DMipmaps(

GLenum target,
GLint components,
GLint width,
GLenum format,
GLenum type,
const void * data
);
Parameters

target

The target texture. Must be GL_TEXTURE_1D.

components

The number of color components in the texture. Must be 1, 2, 3, or 4.

width

The width of the texture image.

format

The format of the pixel data. The following values are valid: GL_COLOR_INDEX, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_BGR_EXT, GL_BGRA_EXT, GL_LUMINANCE, or GL_LUMINANCE_ALPHA.

type

The data type for data. The following values are valid: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, or GL_FLOAT.

data

A pointer to the image data in memory.

Remarks

The gluBuild1DMipmaps function obtains the input image and generates all mipmap images (using gluScaleImage) so that the input image can be used as a mipmapped texture image. The glTexImage1D function is then called to load each of the images. If the width of the input image is not a power of two, then the image is scaled to the nearest power of two before the mipmaps are generated.

A return value of zero indicates success. Otherwise, a GLU error code is returned (see gluErrorString).

For a description of the acceptable values for the format parameter, see glTexImage1D. For a description of the acceptable values for the type parameter, see glDrawPixels.

See Also

glDrawPixels, glTexImage1D, gluBuild2DMipmaps, gluScaleImage


gluBuild2DMipmaps [New - Windows 95, OEM Service Release 2]
gluBuild2DMipmaps

[New - Windows 95, OEM Service Release 2]

The gluBuild2DMipmaps function creates 2-D mipmaps.

int gluBuild2DMipmaps(

GLenum target,
GLint components,
GLint width,
GLint height,
GLenum format,
GLenum type,
const void * data
);
Parameters

target

The target texture. Must be GL_TEXTURE_2D.

components

The number of color components in the texture. Must be 1, 2, 3, or 4.

width, height

The width and height, respectively, of the texture image.

format

The format of the pixel data. Must be one of the following: GL_COLOR_INDEX, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_BGR_EXT, GL_BGRA_EXT, GL_LUMINANCE, or GL_LUMINANCE_ALPHA.

type

The data type for data. Must be one of the following: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, or GL_FLOAT.

data

A pointer to the image data in memory.

Remarks

The gluBuild2DMipmaps function obtains the input image and generates all mipmap images (using gluScaleImage) so the input image can be used as a mipmapped texture image. To load each of the images, call glTexImage2D. If the dimensions of the input image are not powers of two, then the image is scaled so that both the width and height are powers of two before the mipmaps are generated.

A return value of zero indicates success. Otherwise, a GLU error code is returned (see gluErrorString).

For a description of the acceptable values for the format parameter, see glTexImage2D. For a description of the acceptable values for type, see glDrawPixels.

See Also

glDrawPixels, glTexImage2D, gluBuild1DMipmaps, gluScaleImage


gluCylinder [New - Windows 95, OEM Service Release 2]
gluCylinder

[New - Windows 95, OEM Service Release 2]

The gluCylinder function draws a cylinder.

void gluCylinder(

GLUquadricObj * qobj,
GLdouble baseRadius,
GLdouble topRadius,
GLdouble height,
GLint slices,
GLint stacks
);
Parameters

qobj

The quadric object (created with gluNewQuadric).

baseRadius

The radius of the cylinder at z = 0.

topRadius

The radius of the cylinder at z = height.

height

The height of the cylinder.

slices

The number of subdivisions around the z-axis.

stacks

The number of subdivisions along the z-axis.

Remarks

The gluCylinder function draws a cylinder oriented along the z-axis. The base of the cylinder is placed at z = 0, and the top at z = height. Like a sphere, a cylinder is subdivided around the z-axis into slices, and along the z-axis into stacks.

Notice that if topRadius is set to zero, then this routine will generate a cone.

If the orientation is set to GLU_OUTSIDE (with gluQuadricOrientation), then any generated normals point away from the z-axis. Otherwise, they point toward the z-axis.

If texturing is turned on (with gluQuadricTexture): texture coordinates are generated so that t ranges linearly from 0.0 at z = 0 to 1.0 at z = height; and s ranges from 0.0 at the positive y-axis, to 0.25 at the positive x-axis, to 0.5 at the negative y-axis, to 0.75 at the positive x-axis, and back to 1.0 at the positive y-axis.

See Also

gluDisk, gluNewQuadric, gluPartialDisk, gluQuadricOrientation, gluQuadricTexture, gluSphere


gluDeleteNurbsRenderer [New - Windows 95, OEM Service Release 2]
gluDeleteNurbsRenderer

[New - Windows 95, OEM Service Release 2]

The gluDeleteNurbsRenderer function destroys a NURBS object.

void gluDeleteNurbsRenderer(

GLUnurbsObj * nobj
);
Parameters

nobj

The NURBS object to be destroyed (created with gluNewNurbsRenderer).

Remarks

The gluDeleteNurbsRenderer function destroys the NURBS object and frees any memory that it used. After you have called gluDeleteNurbsRenderer, you cannot use nobj again.

See Also

gluNewNurbsRenderer


gluDeleteQuadric [New - Windows 95, OEM Service Release 2]
gluDeleteQuadric

[New - Windows 95, OEM Service Release 2]

The gluDeleteQuadric function destroys a quadric object.

void gluDeleteQuadric(

GLUquadricObj * state
);
Parameters

state

The quadric object to be destroyed (created with gluNewQuadric).

Remarks

The gluDeleteQuadric function destroys the quadric object and frees any memory that it used. After you have called gluDeleteQuadric, you cannot use state again.

See Also

gluNewQuadric


gluDeleteTess [New - Windows 95, OEM Service Release 2]
gluDeleteTess

[New - Windows 95, OEM Service Release 2]

The gluDeleteTess function destroys a tessellation object.

void gluDeleteTess(

GLUtesselator * tess
);
Parameters

tess

The tessellation object to destroy (created with gluNewTess).

Remarks

The gluDeleteTess function destroys the indicated tessellation object and frees any memory that it used.

See Also

gluNewTess, gluTessBeginPolygon, gluTessCallback


gluDisk [New - Windows 95, OEM Service Release 2]
gluDisk

[New - Windows 95, OEM Service Release 2]

The gluDisk function draws a disk.

void gluDisk(

GLUquadricObj * qobj,
GLdouble innerRadius,
GLdouble outerRadius,
GLint slices,
GLint loops
);
Parameters

qobj

The quadric object (created with gluNewQuadric).

innerRadius

The inner radius of the disk (may be zero).

outerRadius

The outer radius of the disk.

slices

The number of subdivisions around the z-axis.

loops

The number of concentric rings about the origin into which the disk is subdivided.

Remarks

The gluDisk function renders a disk on the z = 0 plane. The disk has a radius of outerRadius, and contains a concentric circular hole with a radius of innerRadius. If innerRadius is 0, then no hole is generated. The disk is subdivided around the z-axis into slices (like pizza slices) and also about the z-axis into rings (as specified by slices and loops, respectively).

With respect to orientation, the positive z-side of the disk is considered to be outside (see gluQuadricOrientation). This means that if the orientation is set to GLU_OUTSIDE, then any normals generated point along the positive z-axis.

If texturing is turned on (with gluQuadricTexture), texture coordinates are generated linearly such that where r = outerRadius, the value at (r, 0, 0) is (1, 0.5); at (0, r, 0) it is (0.5, 1); at (r, 0, 0) it is (0, 0.5); and at (0, r, 0) it is (0.5, 0).

See Also

gluCylinder, gluNewQuadric, gluPartialDisk, gluQuadricTexture, gluSphere


gluErrorString [New - Windows 95, OEM Service Release 2]
gluErrorString

[New - Windows 95, OEM Service Release 2]

The gluErrorString function produces an error string from an OpenGL or GLU error code. The error string is ANSI only.

const GLubyte* gluErrorString(

GLenum errCode
);
Parameters

errCode

An OpenGL or GLU error code.

Remarks

The gluErrorString function produces an error string from an OpenGL or GLU error code. The string is in an ISO Latin 1 format. For example, gluErrorString(GL_OUT_OF_MEMORY) returns the string out of memory.

The standard GLU error codes are GLU_INVALID_ENUM, GLU_INVALID_VALUE, and GLU_OUT_OF_MEMORY. Certain other GLU functions can return specialized error codes through callbacks. For the list of OpenGL error codes, see glGetError.

The gluErrorString function produces error strings in ANSI only. Whenever possible, use gluErrorStringWIN, which allows ANSI or Unicode error strings. This makes it easier to localize your program for use with another language.

See Also

glGetError, gluNurbsCallback, gluQuadricCallback, gluTessCallback


gluGetNurbsProperty [New - Windows 95, OEM Service Release 2]
gluGetNurbsProperty

[New - Windows 95, OEM Service Release 2]

The gluGetNurbsProperty function gets a NURBS property.

void gluGetNurbsProperty(

GLUnurbsObj * nobj,
GLenum property,
GLfloat * value
);
Parameters

nobj

The NURBS object (created with gluNewNurbsRenderer).

property

The property whose value is to be retrieved. The following values are valid: GLU_SAMPLING_TOLERANCE, GLU_DISPLAY_MODE, GLU_CULLING, GLU_AUTO_LOAD_MATRIX, GLU_PARAMETRIC_TOLERANCE, GLU_SAMPLING_METHOD, GLU_U_STEP, and GLU_V_STEP.

value

A pointer to the location into which the value of the named property is written.

Remarks

Use gluGetNurbsProperty to retrieve properties stored in a NURBS object. These properties affect the way NURBS curves and surfaces are rendered. For information about what the properties are and what they do, see gluNurbsProperty.

See Also

gluNewNurbsRenderer, gluNurbsProperty


gluGetString [New - Windows 95, OEM Service Release 2]
gluGetString

[New - Windows 95, OEM Service Release 2]

The gluGetString function gets a string that describes the GLU version number or supported GLU extension calls.

const GLubyte *gluGetString(

GLenum name
);
Parameters

name

Either the version number of GLU (GLU_VERSION) or available vendor-specific extension calls (GLU_EXTENSIONS).

Remarks

The gluGetString function returns a pointer to a static, null-terminated string. When name is GLU_VERSION, the returned string is a value that represents the version number of GLU. The format of the version number is as follows:

<version number><space><vendor-specific information>

(for example, “1.2.11 Microsoft Windows NT”)

The version number has the form “major_number.minor_number” or “major_number.minor_number.release_number”. The vendor-specific information is optional, and the format and contents depend on the implementation.

When name is GLU_EXTENSIONS, the returned string contains a list of names of supported GLU extensions that are separated by spaces. The format of the returned list of names is as follows:

<extension_name><space><extension_name><space> . . .

(for example, “GLU_NURBS GL_TESSELATION”)

The extension names cannot contain any spaces.

The gluGetString function is valid for GLU version 1.1 or later.


gluGetTessProperty [New - Windows 95, OEM Service Release 2]
gluGetTessProperty

[New - Windows 95, OEM Service Release 2]

The gluGetTessProperty function gets a tessellation object property.

void gluTessProperty(

GLUtesselator * tess,
GLenum which,
GLdouble * value
);
Parameters

tess

The tessellation object (created with gluNewTess).

which

The property whose value is to be retrieved. The following values are valid: GLU_TESS_WINDING_RULE, GLU_TESS_BOUNDARY_ONLY, and GLU_TESS_TOLERANCE.

value

A pointer to the location where the value of the named property is written.

Remarks

Use gluGetTessProperty to retrieve properties stored in a tessellation object. These properties affect the way tessellation objects are interpreted and rendered. For information about what the properties are and what they do, see gluTessProperty.

See Also

gluNewTess, gluTessProperty


gluLoadSamplingMatrices [New - Windows 95, OEM Service Release 2]
gluLoadSamplingMatrices

[New - Windows 95, OEM Service Release 2]

The gluLoadSamplingMatrices function loads NURBS sampling and culling matrices.

void gluLoadSamplingMatrices(

GLUnurbsObj *nobj,
const GLfloat modelMatrix[16],
const GLfloat projMatrix[16],
const GLint viewport[4]
);
Parameters

nobj

The NURBS object (created with gluNewNurbsRenderer).

modelMatrix

A modelview matrix (as from a glGetFloatv call).

projMatrix

A projection matrix (as from a glGetFloatv call).

viewport

A viewport (as from a glGetIntegerv call).

Remarks

The gluLoadSamplingMatrices function uses modelMatrix, projMatrix, and viewport to recompute the sampling and culling matrices stored in nobj. The sampling matrix determines how finely a NURBS curve or surface must be tessellated to satisfy the sampling tolerance (as determined by the GLU_SAMPLING_TOLERANCE property). The culling matrix is used in deciding if a NURBS curve or surface should be culled before rendering (when the GLU_CULLING property is turned on).

The gluLoadSamplingMatrices function is necessary only if the GLU_AUTO_LOAD_MATRIX property is turned off (see gluNurbsProperty). Although it can be convenient to leave the GLU_AUTO_LOAD_MATRIX property turned on, doing so necessitates a round trip to the OpenGL server to get the current values of the modelview matrix, projection matrix, and viewport.)

See Also

glGetFloatv, glGetIntegerv, gluGetNurbsProperty, gluNewNurbsRenderer


gluLookAt [New - Windows 95, OEM Service Release 2]
gluLookAt

[New - Windows 95, OEM Service Release 2]

The gluLookAt function defines a viewing transformation.

void gluLookAt(

GLdouble eyex,
GLdouble eyey,
GLdouble eyez,
GLdouble centerx,
GLdouble centery,
GLdouble centerz,
GLdouble upx,
GLdouble upy,
GLdouble upz
);
Parameters

eyex, eyey, eyez

The position of the eye point.

centerx, centery, centerz

The position of the reference point.

upx, upy, upz

The direction of the up vector.

Remarks

The gluLookAt function creates a viewing matrix derived from an eye point, a reference point indicating the center of the scene, and an up vector. The matrix maps the reference point to the negative z-axis and the eye point to the origin, so that when you use a typical projection matrix, the center of the scene maps to the center of the viewport. Similarly, the direction described by the up vector projected onto the viewing plane is mapped to the positive y-axis so that it points upward in the viewport. The up vector must not be parallel to the line of sight from the eye to the reference point.

The matrix generated by gluLookAt postmultiplies the current matrix.

See Also

glFrustum, gluPerspective


gluNewNurbsRenderer [New - Windows 95, OEM Service Release 2]
gluNewNurbsRenderer

[New - Windows 95, OEM Service Release 2]

The gluNewNurbsRenderer function creates a NURBS object.

GLUnurbsObj* gluNewNurbsRenderer(

void
);
Remarks

The gluNewNurbsRenderer function creates and returns a pointer to a new NURBS object. Refer to this object when calling NURBS rendering and control functions. A return value of zero means there is not enough memory to allocate to the object.

See Also

gluBeginCurve, gluBeginSurface, gluBeginTrim, gluDeleteNurbsRenderer, gluNurbsCallback, gluNurbsProperty


gluNewQuadric [New - Windows 95, OEM Service Release 2]
gluNewQuadric

[New - Windows 95, OEM Service Release 2]

The gluNewQuadric function creates a quadric object.

GLUquadricObj* gluNewQuadric(

void
);
Remarks

The gluNewQuadric function creates and returns a pointer to a new quadric object. Refer to this object when calling quadric rendering and control functions. A return value of zero means there is not enough memory to allocate to the object.

See Also

gluCylinder, gluDeleteQuadric, gluDisk, gluPartialDisk, gluQuadricCallback, gluQuadricDrawStyle, gluQuadricNormals, gluQuadricOrientation, gluQuadricTexture, gluSphere


gluNewTess [New - Windows 95, OEM Service Release 2]
gluNewTess

[New - Windows 95, OEM Service Release 2]

The gluNewTess function creates a tessellation object.

GLUtesselator* gluNewTess(

void
);
Remarks

The gluNewTess function creates and returns a pointer to a new tessellation object. Refer to this object when calling tessellation functions. A return value of zero means there is not enough memory to allocate to the object.

See Also

gluDeleteTess, gluTessBeginPolygon, gluTessCallback


gluNextContour [New - Windows 95, OEM Service Release 2]
gluNextContour

[New - Windows 95, OEM Service Release 2]

The gluNextContour function marks the beginning of another contour.

void gluNextContour(

GLUtesselator * tess,
GLenum type
);
Parameters

tess

The tessellation object (created with gluNewTess).

type

The type of the contour being defined. The following values are valid.

Value	Meaning
GLU_EXTERIOR	An exterior contour defines an exterior boundary of the polygon.
GLU_INTERIOR	An interior contour defines an interior boundary of the polygon (such as a hole).
GLU_UNKNOWN	An unknown contour is analyzed by the library to determine whether it is interior or exterior.
GLU_CCW, GLU_CW	The first GLU_CCW or GLU_CW contour defined is considered to be exterior. All other contours are considered to be exterior if they are oriented in the same direction (clockwise or counterclockwise) as the first contour, and interior if they are not.  If one contour is of type GLU_CCW or GLU_CW, then all contours must be of the same type (if they are not, then all GLU_CCW and GLU_CW contours will be changed to GLU_UNKNOWN). Note that there is no real difference between the GLU_CCW and GLU_CW contour types.
Remarks

Use the gluNextContour function to describe polygons with multiple contours. After you describe the first contour through a series of gluTessVertex calls, a gluNextContour call indicates that the previous contour is complete and that the next contour is about to begin. Perform another series of gluTessVertex calls to describe the new contour. Repeat this process until all contours have been described.

The type parameter defines what type of contour follows.

To define the type of the first contour, you can call gluNextContour before describing the first contour. If you do not call gluNextContour before the first contour, the first contour is marked GLU_EXTERIOR.

Note  The gluNextContour function is obsolete and is provided for backwards compatibility only. The gluNextContour function is mapped to gluTessEndContour followed by gluTessBeginContour.

Example

You can describe a quadrilateral with a triangular hole in it as follows:

gluBeginPolygon(tess);

    gluTessVertex(tess, v1, v1);

    gluTessVertex(tess, v2, v2);

    gluTessVertex(tess, v3, v3);

    gluTessVertex(tess, v4, v4);

gluNextContour(tess, GLU_INTERIOR);

    gluTessVertex(tess, v5, v5);

    gluTessVertex(tess, v6, v6);

    gluTessVertex(tess, v7, v7);

gluEndPolygon(tess);

See Also

gluNewTess, gluTessBeginContour, gluTessBeginPolygon, gluTessCallback, gluTessEndContour, gluTessVertex


gluNurbsCallback [New - Windows 95, OEM Service Release 2]
gluNurbsCallback

[New - Windows 95, OEM Service Release 2]

The gluNurbsCallback function defines a callback for a NURBS object.

void gluNurbsCallback(

GLUnurbsObj * nobj,
GLenum which,
void (* fn)( )
);
Parameters

nobj

The NURBS object (created with gluNewNurbsRenderer).

which

The callback being defined. The only valid value is GLU_ERROR. The meaning of GLU_ERROR means that the error function is called when an error is encountered. Its single argument is of type GLenum, and it indicates the specific error that occurred. There are 37 errors unique to NURBS, named GLU_NURBS_ERROR1 through GLU_NURBS_ERROR37. Character strings describing these errors can be retrieved with gluErrorString.

fn

The function that the callback calls.

Remarks

Use gluNurbsCallback to define a callback to be used by a NURBS object. If the specified callback is already defined, it is replaced. If fn is NULL, then any existing callback is erased.

See Also

gluErrorString, gluNewNurbsRenderer


gluNurbsCurve [New - Windows 95, OEM Service Release 2]
gluNurbsCurve

[New - Windows 95, OEM Service Release 2]

The gluNurbsCurve function defines the shape of a NURBS curve.

void gluNurbsCurve(

GLUnurbsObj * nobj,
GLint nknots,
GLfloat * knot,
GLint stride,
GLfloat * ctlarray,
GLint order,
GLenum type
);
Parameters

nobj

The NURBS object (created with gluNewNurbsRenderer).

nknots

The number of knots in knot. The nknots parameter equals the number of control points plus the order.

knot

An array of nknots nondecreasing knot values.

stride

The offset (as a number of single-precision floating-point values) between successive curve control points.

ctlarray

A pointer to an array of control points. The coordinates must agree with type.

order

The order of the NURBS curve. The order parameter equals degree + 1; hence a cubic curve has an order of 4.

type

The type of the curve. If this curve is defined within a gluBeginCurve/gluEndCurve pair, then the type can be any of the valid one-dimensional evaluator types (such as GL_MAP1_VERTEX_3 or GL_MAP1_COLOR_4). Between a gluBeginTrim/gluEndTrim pair, the only valid types are GLU_MAP1_TRIM_2 and GLU_MAP1_TRIM_3.

Remarks

When gluNurbsCurve appears between a gluBeginCurve/gluEndCurve pair, it describes a curve to be rendered. You associate positional, texture, and color coordinates by presenting each as a separate gluNurbsCurve between a gluBeginCurve/gluEndCurve pair. Do not make more than one call to gluNurbsCurve for color, position, and texture data within a single gluBeginCurve/gluEndCurve pair. Make exactly one call to describe the position of the curve (a type of GL_MAP1_VERTEX_3 or GL_MAP1_VERTEX_4).

When gluNurbsCurve appears between a gluBeginTrim/gluEndTrim pair, it describes a trimming curve on a NURBS surface. If type is GLU_MAP1_TRIM_2, it describes a curve in two-dimensional (u and v) parameter space. If it is GLU_MAP1_TRIM_3, it describes a curve in two-dimensional homogeneous (u, v, and w) parameter space. For more discussion about trimming curves, see gluBeginTrim.

Example

The following functions render a textured NURBS curve with normals:

gluBeginCurve(nobj);

    gluNurbsCurve(nobj, ..., GL_MAP1_TEXTURE_COORD_2);

    gluNurbsCurve(nobj, ..., GL_MAP1_NORMAL);

    gluNurbsCurve(nobj, ..., GL_MAP1_VERTEX_4);

gluEndCurve(nobj);

See Also

gluBeginCurve, gluBeginTrim, gluEndCurve, gluEndTrim, gluNewNurbsRenderer, gluPwlCurve


gluNurbsProperty [New - Windows 95, OEM Service Release 2]
gluNurbsProperty

[New - Windows 95, OEM Service Release 2]

The gluNurbsProperty function sets a NURBS property.

void gluNurbsProperty(

GLUnurbsObj * nobj,
GLenum property,
GLfloat value
);
Parameters

nobj

The NURBS object (created with gluNewNurbsRenderer).

property

The property to be set. The following values are valid: GLU_SAMPLING_TOLERANCE, GLU_DISPLAY_MODE, GLU_CULLING, GLU_AUTO_LOAD_MATRIX, GLU_PARAMETRIC_TOLERANCE, GLU_SAMPLING_METHOD, GLU_U_STEP, and GLU_V_STEP. For the meaning of these values, see the following Remarks section.

value

The value to which to set the indicated property. The value parameter can be a numeric value or one of the following three values: GLU_PATH_LENGTH, GLU_PARAMETRIC_ERROR, or GLU_DOMAIN_DISTANCE. For the meaning of these values, see the following Remarks section.

Remarks

Use gluNurbsProperty to control properties stored in a NURBS object. These properties affect the way a NURBS curve is rendered. The valid values for property are as follows:

GLU_SAMPLING_TOLERANCE

Specifies the maximum length, in pixels, to use when the sampling method is set to GLU_PATH_LENGTH. The default value is 50.0 pixels.

GLU_DISPLAY_MODE

The value parameter defines how a NURBS surface is to be rendered. You can set value to GLU_FILL, GLU_OUTLINE_POLYGON, or GLU_OUTLINE_PATCH. The following table describes the results of these constants.

Constant	Result
GLU_FILL	The surface is rendered as a set of polygons. This is the default value.
GLU_OUTLINE_POLYGON	The NURBS library draws only the outlines of the polygons created by tessellation.
GLU_OUTLINE_PATCH	Only the outlines of patches and trim curves defined by the user are drawn.
GLU_CULLING

The value parameter is a Boolean value. When value is set to GL_TRUE, NURBS curves whose control points lie outside the current viewport are discarded prior to tessellation. The default is GL_FALSE (because a NURBS curve cannot fall entirely within the convex hull of its control points).

GLU_PARAMETRIC_TOLERANCE

Specifies the maximum distance, in pixels, to use when the sampling method is set to GLU_PARAMETRIC_ERROR. The default value is 0.5.

GLU_SAMPLING_METHOD

Specifies how to tessallate a NURBS surface. GLU_SAMPLING_METHOD can have one of the following three values.

Value	Meaning
GLU_PATH_LENGTH	The default value. Specifies that surfaces rendered with the maximum length, in pixels, of the edges of the tessellation polygons are no greater than the value specified by GLU_SAMPLING_TOLERANCE.
GLU_PARAMETRIC_ERROR	Specifies that in rendering the surface, the value of GLU_PARAMETRIC_TOLERANCE specifies the maximum distance, in pixels, between the tessellation polygons and the surfaces they approximate.
GLU_DOMAIN_DISTANCE	Specifies, in parametric coordinates, how many sample points per unit length to take in the u and v dimensions.
GLU_U_STEP

Specifies the number of sample points per unit length taken along the u dimension in parametric coordinates. The value of GLU_U_STEP is used when GLU_SAMPLING_METHOD is set to GLU_DOMAIN_DISTANCE. The default value is 100.

GLU_V_STEP

Specifies the number of sample points per unit length taken along the v dimension in parametric coordinates. The value of GLU_V_STEP is used when GLU_SAMPLING_METHOD is set to GLU_DOMAIN_DISTANCE. The default value is 100.

GLU_AUTO_LOAD_MATRIX

The value parameter is a Boolean value. When set to GL_TRUE, the NURBS code downloads the projection matrix, modelview matrix, and viewport from the OpenGL server to compute sampling and culling matrices for each NURBS curve that is rendered. Sampling and culling matrices are required to determine the tessellation of a NURBS surface into line segments or polygons and to cull a NURBS surface if it lies outside of the viewport. If this mode is set to GL_FALSE, you must provide a projection matrix, modelview matrix, and viewport for the NURBS renderer to use to construct sampling and culling matrices. You can do this with the gluLoadSamplingMatrices function. The default for this mode is GL_TRUE. Changing this mode from GL_TRUE to GL_FALSE does not affect the sampling and culling matrices until you call gluLoadSamplingMatrices.

Note  The following property parameters are supported in GLU version 1.1 or later and are not valid for GLU version 1.0:

GLU_PARAMETRIC_TOLERANCE, GLU_SAMPLING_METHOD, GLU_U_STEP, and GLU_V_STEP.

The following value parameters are supported in GLU version 1.1 or later and are not valid for GLU version 1.0:

GLU_PATH_LENGTH, GLU_PARAMETRIC_ERROR, and GLU_DOMAIN_DISTANCE.

See Also

gluGetNurbsProperty, gluGetString, gluLoadSamplingMatrices, gluNewNurbsRenderer


gluNurbsSurface [New - Windows 95, OEM Service Release 2]
gluNurbsSurface

[New - Windows 95, OEM Service Release 2]

The gluNurbsSurface function defines the shape of a NURBS surface.

void gluNurbsSurface(

GLUnurbsObj * nobj,
GLint sknot_count,
GLfloat * sknot,
GLint tknot_count,
GLfloat * tknot,
GLint s_stride,
GLint t_stride,
GLfloat * ctlarray,
GLint sorder,
GLint torder,
GLenum type
);
Parameters

nobj

The NURBS object (created with gluNewNurbsRenderer).

sknot_count

The number of knots in the parametric u direction.

sknot

An array of sknot_count nondecreasing knot values in the parametric u direction.

tknot_count

The number of knots in the parametric v direction.

tknot

An array of tknot_count nondecreasing knot values in the parametric v direction.

s_stride

The offset (as a number of single-precision floating-point values) between successive control points in the parametric u direction in ctlarray.

t_stride

The offset (in single-precision floating-point values) between successive control points in the parametric v direction in ctlarray.

ctlarray

An array containing control points for the NURBS surface. The offsets between successive control points in the parametric u and v directions are given by s_stride and t_stride.

sorder

The order of the NURBS surface in the parametric u direction. The order is one more than the degree, hence a surface that is cubic in u has a u order of 4.

torder

The order of the NURBS surface in the parametric v direction. The order is one more than the degree, hence a surface that is cubic in v has a v order of 4.

type

The type of the surface. The type parameter can be any of the valid two-dimensional evaluator types (such as GL_MAP2_VERTEX_3 or GL_MAP2_COLOR_4).

Remarks

Use gluNurbsSurface within a NURBS (Non-Uniform Rational B-Spline) surface definition to describe the shape of a NURBS surface (before any trimming). To mark the beginning of a NURBS surface definition, use the gluBeginSurface function. To mark the end of a NURBS surface definition, use the gluEndSurface function. Call gluNurbsSurface within a NURBS surface definition only.

You associate positional, texture, and color coordinates with a surface by presenting each as a separate gluNurbsSurface between a gluBeginSurface/gluEndSurface pair. Within a single gluBeginSurface/gluEndSurface pair, you can make only one call to gluNurbsSurface for color, position, and texture data. Make exactly one call to describe the position of the surface (a type of GL_MAP2_VERTEX_3 or GL_MAP2_VERTEX_4).

You can trim a NURBS surface by using the gluNurbsCurve and gluPwlCurve functions between calls to gluBeginTrim and gluEndTrim.

Note  A gluNurbsSurface with sknot_count knots in the u direction and tknot_count knots in the v direction with orders sorder and torder must have (sknot_count - sorder) multipied by (tknot_count - torder) control points.

Example

The following functions render a textured NURBS surface with normals; the texture coordinates and normals are also NURBS surfaces:

gluBeginSurface(nobj);

    gluNurbsSurface(nobj, . . ., GL_MAP2_TEXTURE_COORD_2);

    gluNurbsSurface(nobj, . . ., GL_MAP2_NORMAL);

    gluNurbsSurface(nobj, . . ., GL_MAP2_VERTEX_4);

gluEndSurface(nobj);

See Also

gluBeginSurface, gluBeginTrim, gluEndSurface, gluEndTrim, gluNewNurbsRenderer, gluNurbsCurve, gluPwlCurve


gluOrtho2D [New - Windows 95, OEM Service Release 2]
gluOrtho2D

[New - Windows 95, OEM Service Release 2]

The gluOrtho2D function defines a 2-D orthographic projection matrix.

void gluOrtho2D(

GLdouble left,
GLdouble right,
GLdouble bottom,
GLdouble top
);
Parameters

left, right

The coordinates for the left and right vertical clipping planes.

bottom, top

The coordinates for the bottom and top horizontal clipping planes.

Remarks

The gluOrtho2D function sets up a two-dimensional orthographic viewing region. This is equivalent to calling glOrtho with near = −1 and far = 1.

See Also

glOrtho, gluPerspective


gluPartialDisk [New - Windows 95, OEM Service Release 2]
gluPartialDisk

[New - Windows 95, OEM Service Release 2]

The gluPartialDisk function draws an arc of a disk.

void gluPartialDisk(

GLUquadricObj * qobj,
GLdouble innerRadius,
GLdouble outerRadius,
GLint slices,
GLint loops,
GLdouble startAngle,
GLdouble sweepAngle
);
Parameters

qobj

A quadric object (created with gluNewQuadric).

innerRadius

The inner radius of the partial disk (can be zero).

outerRadius

The outer radius of the partial disk.

slices

The number of subdivisions around the z-axis.

loops

The number of concentric rings about the origin into which the partial disk is subdivided.

startAngle

The starting angle, in degrees, of the disk portion.

sweepAngle

The sweep angle, in degrees, of the disk portion.

Remarks

The gluPartialDisk function renders a partial disk on the z = 0 plane. A partial disk is similar to a full disk, except that only the subset of the disk from startAngle through startAngle + sweepAngle is included (where 0 degrees is along the positive y-axis, 90 degrees is along the positive x-axis, 180 degrees is along the negative y-axis, and 270 degrees is along the negative x-axis).

The partial disk has a radius of outerRadius and contains a concentric circular hole with a radius of innerRadius. If innerRadius is zero, then no hole is generated. The partial disk is subdivided around the z-axis into slices (like pizza slices), and also about the z-axis into rings (as specified by slices and loops, respectively).

With respect to orientation, the positive z-side of the partial disk is considered to be outside (see gluQuadricOrientation). This means that if the orientation is set to GLU_OUTSIDE, then any normals generated point along the positive z-axis.

If you have turned on texturing (with gluQuadricTexture), gluPartialDisk generates texture coordinates linearly such that where r = outerRadius, the value at (r, 0, 0) is (1, 0.5); at (0, r, 0) it is (0.5, 1); at (r, 0, 0) it is (0, 0.5); and at (0, r, 0) it is (0.5, 0).

See Also

gluCylinder, gluDisk, gluNewQuadric, gluQuadricOrientation, gluQuadricTexture, gluSphere


gluPerspective [New - Windows 95, OEM Service Release 2]
gluPerspective

[New - Windows 95, OEM Service Release 2]

The gluPerspective function sets up a perspective projection matrix.

void gluPerspective(

GLdouble fovy,
GLdouble aspect,
GLdouble zNear,
GLdouble zFar
);
Parameters

fovy

The field of view angle, in degrees, in the y-direction.

aspect

The aspect ratio that determines the field of view in the x-direction. The aspect ratio is the ratio of x (width) to y (height).

zNear

The distance from the viewer to the near clipping plane (always positive).

zFar

The distance from the viewer to the far clipping plane (always positive).

Remarks

The gluPerspective function specifies a viewing frustum into the world coordinate system. In general, the aspect ratio in gluPerspective should match the aspect ratio of the associated viewport. For example, aspect = 2.0 means the viewer’s angle of view is twice as wide in x as it is in y. If the viewport is twice as wide as it is tall, it displays the image without distortion.

The matrix generated by gluPerspective is multipled by the current matrix, just as if glMultMatrix were called with the generated matrix. To load the perspective matrix onto the current matrix stack instead, precede the call to gluPerspective with a call to glLoadIdentity.

See Also

glFrustum, glLoadIdentity, glMultMatrix, gluOrtho2D


gluPickMatrix [New - Windows 95, OEM Service Release 2]
gluPickMatrix

[New - Windows 95, OEM Service Release 2]

The gluPickMatrix function defines a picking region.

void gluPickMatrix(

GLdouble x,
GLdouble y,
GLdouble width,
GLdouble height,
GLint viewport[4]
);
Parameters

x, y

The center of a picking region in window coordinates.

width, height

The width and height, respectively, of the picking region in window coordinates.

viewport

The current viewport (as from a glGetIntegerv call).

Remarks

The gluPickMatrix function creates a projection matrix you can use to restrict drawing to a small region of the viewport.

To determine which objects are being drawn near the cursor

1.	Use gluPickMatrix to restrict drawing to a small region around the cursor.

2.	Enter selection mode (with glRenderMode), and then rerender the scene.

All primitives that would have been drawn near the cursor are identified and stored in the selection buffer.

The matrix created by gluPickMatrix is multiplied by the current matrix just as if glMultMatrix were called with the generated matrix.

To effectively use the generated pick matrix for picking

1.	Call glLoadIdentity to load an identity matrix onto the perspective matrix stack.

2.	Call gluPickMatrix.

3.	Call a function (such as gluPerspective) to multiply the perspective matrix by the pick matrix.

When using gluPickMatrix to pick NURBS, be careful to turn off the NURBS property GLU_AUTO_LOAD_MATRIX. If GLU_AUTO_LOAD_MATRIX is not turned off, any NURBS surface rendered is subdivided differently with the pick matrix from how it was subdivided without the pick matrix.

Example

When rendering a scene as follows:

glMatrixMode(GL_PROJECTION);

glLoadIdentity( );

gluPerspective(. . .);

glMatrixMode(GL_MODELVIEW);

/* Draw the scene */

the following code selects a portion of the viewport:

glMatrixMode(GL_PROJECTION);

glLoadIdentity( );

gluPickMatrix(x, y, width, height, viewport);

gluPerspective(. . .);

glMatrixMode(GL_MODELVIEW);

/* Draw the scene */

See Also

glGetIntegerv, glLoadIdentity, glMultMatrix, glRenderMode, gluPerspective


gluProject [New - Windows 95, OEM Service Release 2]
gluProject

[New - Windows 95, OEM Service Release 2]

The gluProject function maps object coordinates to window coordinates.

int gluProject(

GLdouble objx,
GLdouble objy,
GLdouble objz,
const GLdouble modelMatrix[16],
const GLdouble projMatrix[16],
const GLint viewport[4],
GLdouble * winx,
GLdouble * winy,
GLdouble * winz
);
Parameters

objx, objy, objz

The object coordinates.

modelMatrix

The current modelview matrix (as from a glGetDoublev call).

projMatrix

The current projection matrix (as from a glGetDoublev call).

viewport

The current viewport (as from a glGetIntegerv call).

winx, winy, winz

The computed window coordinates.

Remarks

The gluProject function transforms the specified object coordinates into window coordinates using modelMatrix, projMatrix, and viewport. The result is stored in winx, winy, and winz. A return value of GL_TRUE indicates success, and GL_FALSE indicates failure.

See Also

glGetDoublev, glGetIntegerv, gluUnProject


gluPwlCurve [New - Windows 95, OEM Service Release 2]
gluPwlCurve

[New - Windows 95, OEM Service Release 2]

The gluPwlCurve function describes a piecewise linear NURBS trimming curve.

void gluPwlCurve(

GLUnurbsObj * nobj,
GLint count,
GLfloat * array,
GLint stride,
GLenum type
);
Parameters

nobj

The NURBS object (created with gluNewNurbsRenderer).

count

The number of points on the curve.

array

An array containing the curve points.

stride

The offset (a number of single-precision floating-point values) between points on the curve.

type

The type of curve. Must be either GLU_MAP1_TRIM_2 or GLU_MAP1_TRIM_3.

Remarks

The gluPwlCurve function describes a piecewise linear trimming curve for a NURBS surface. A piecewise linear curve consists of a list of coordinates of points in the parameter space for the NURBS surface to be trimmed. These points are connected with line segments to form a curve. If the curve is an approximation to a real curve, the points should be close enough that the resulting path appears curved at the resolution used in the application.

If type is GLU_MAP1_TRIM_2, it describes a curve in two-dimensional (u and v) parameter space. If it is GLU_MAP1_TRIM_3, then it describes a curve in two-dimensional homogeneous (u, v, and w) parameter space. For more information about trimming curves, see gluBeginTrim.

See Also

gluBeginCurve, gluBeginTrim, gluNewNurbsRenderer, gluNurbsCurve


gluQuadricCallback [New - Windows 95, OEM Service Release 2]
gluQuadricCallback

[New - Windows 95, OEM Service Release 2]

The gluQuadricCallback function defines a callback for a quadric object.

void gluQuadricCallback(

GLUquadricObj * qobj,
GLenum which,
void (* fn)( )
);
Parameters

qobj

The quadric object (created with gluNewQuadric).

which

The callback being defined. The only valid value is GLU_ERROR.

Value	Meaning
GLU_ERROR	The gluQuadricCallback function is called when an error is encountered. Its single argument is of type GLenum, and it indicates the specific error that occurred. Character strings describing these errors can be retrieved with the gluErrorString call.
fn

The function to be called.

Remarks

Use gluQuadricCallback to define a new callback to be used by a quadric object. If the specified callback is already defined, it is replaced. If fn is NULL, any existing callback is erased.

See Also

gluErrorString, gluNewQuadric


gluQuadricDrawStyle [New - Windows 95, OEM Service Release 2]
gluQuadricDrawStyle

[New - Windows 95, OEM Service Release 2]

The gluQuadricDrawStyle function specifies the draw style desired for quadrics.

void gluQuadricDrawStyle(

GLUquadricObj * qobj,
GLenum drawStyle
);
Parameters

qobj

The quadric object (created with gluNewQuadric).

drawStyle

The desired draw style. The following values are valid.

Value	Meaning
GLU_FILL	Quadrics are rendered with polygon primitives. The polygons are drawn in a counterclockwise fashion with respect to their normals (as defined with gluQuadricOrientation).
GLU_LINE	Quadrics are rendered as a set of lines.
GLU_SILHOUETTE	Quadrics are rendered as a set of lines, except that edges separating coplanar faces will not be drawn.
GLU_POINT	Quadrics are rendered as a set of points.
Remarks

The gluQuadricDrawStyle function specifies the draw style for quadrics rendered with qobj.

See Also

gluNewQuadric, gluQuadricNormals, gluQuadricOrientation, gluQuadricTexture


gluQuadricNormals [New - Windows 95, OEM Service Release 2]
gluQuadricNormals

[New - Windows 95, OEM Service Release 2]

The gluQuadricNormals function specifies what kind of normals are to be used for quadrics.

void gluQuadricNormals(

GLUquadricObj *qobj,
GLenum normals
);
Parameters

qobj

The quadric object (created with gluNewQuadric).

normals

The desired type of normals. The following values are valid.

Value	Meaning
GLU_NONE	No normals are generated.
GLU_FLAT	One normal is generated for every facet of a quadric.
GLU_SMOOTH	One normal is generated for every vertex of a quadric. This is the default value.
Remarks

The gluQuadricNormals function specifies what kind of normals are to be used for quadrics rendered with qobj.

See Also

gluNewQuadric, gluQuadricDrawStyle, gluQuadricOrientation, gluQuadricTexture


gluQuadricOrientation [New - Windows 95, OEM Service Release 2]
gluQuadricOrientation

[New - Windows 95, OEM Service Release 2]

The gluQuadricOrientation function specifies inside or outside orientation for quadrics.

void gluQuadricOrientation(

GLUquadricObj * quadObject,
GLenum orientation
);
Parameters

quadObject

The quadric object (created with gluNewQuadric).

orientation

The desired orientation. The following values are valid.

Value	Meaning
GLU_OUTSIDE	Draw quadrics with normals pointing outward. This is the default value.
GLU_INSIDE	Draw quadrics with normals pointing inward.
Remarks

The gluQuadricOrientation function specifies what kind of orientation is desired for quadrics rendered with quadObject. The interpretation of outward and inward depends on the quadric being drawn.

See Also

gluNewQuadric, gluQuadricDrawStyle, gluQuadricNormals, gluQuadricTexture


gluQuadricTexture [New - Windows 95, OEM Service Release 2]
gluQuadricTexture

[New - Windows 95, OEM Service Release 2]

The gluQuadricTexture function specifies whether quadrics are to be textured.

void gluQuadricTexture(

GLUquadricObj * quadObject,
GLboolean textureCoords
);
Parameters

quadObject

The quadric object (created with gluNewQuadric).

textureCoords

A flag indicating whether texture coordinates are to be generated. The following values are valid.

Value	Meaning
GL_TRUE	Generate texture coordinates.
GL_FALSE	Do not generate texture coordinates. This is the default value.
Remarks

The gluQuadricTexture function specifies whether texture coordinates are to be generated for quadrics rendered with quadObject.

The manner in which texture coordinates are generated depends upon the specific quadric rendered.

See Also

gluNewQuadric, gluQuadricDrawStyle, gluQuadricNormals


gluScaleImage [New - Windows 95, OEM Service Release 2]
gluScaleImage

[New - Windows 95, OEM Service Release 2]

The gluScaleImage function scales an image to an arbitrary size.

int gluScaleImage(

GLenum format,
GLint widthin,
GLint heightin,
GLenum typein,
const void * datain,
GLint widthout,
GLint heightout,
GLenum typeout,
void * dataout
);
Parameters

format

The format of the pixel data. The following symbolic values are valid: GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_BGR_EXT, GL_BGRA_EXT, GL_LUMINANCE, and GL_LUMINANCE_ALPHA.

widthin, heightin

The width and height, respectively, of the source image that is scaled.

typein

The data type for datain. Must be one of the following: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, or GL_FLOAT.

datain

A pointer to the source image.

widthout, heightout

The width and height, respectively, of the destination image.

typeout

The data type for dataout. Must be one of the following: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, or GL_FLOAT.

dataout

A pointer to the destination image.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a GLU error code (see gluErrorString).

Remarks

The gluScaleImage function scales a pixel image using the appropriate pixel store modes to unpack data from the source image and pack data into the destination image.

When shrinking an image, gluScaleImage uses a box filter to sample the source image and create pixels for the destination image. When magnifying an image, the pixels from the source image are linearly interpolated to create the destination image.

For a description of the acceptable values for the format, typein, and typeout parameters, see glReadPixels.

See Also

glDrawPixels, glReadPixels, gluBuild1DMipmaps, gluBuild2DMipmaps, gluErrorString


gluSphere [New - Windows 95, OEM Service Release 2]
gluSphere

[New - Windows 95, OEM Service Release 2]

The gluSphere function draws a sphere.

void gluSphere(

GLUquadricObj * qobj,
GLdouble radius,
GLint slices,
GLint stacks
);
Parameters

qobj

The quadric object (created with gluNewQuadric).

radius

The radius of the sphere.

slices

The number of subdivisions around the z-axis (similar to lines of longitude).

stacks

The number of subdivisions along the z-axis (similar to lines of latitude).

Remarks

The gluSphere function draws a sphere of the given radius centered around the origin. The sphere is subdivided around the z-axis into slices and along the z-axis into stacks (similar to lines of longitude and latitude).

If the orientation is set to GLU_OUTSIDE (with gluQuadricOrientation), any normals generated point away from the center of the sphere. Otherwise, they point toward the center of the sphere.

If texturing is turned on (with gluQuadricTexture): texture coordinates are generated so that t ranges from 0.0 at z = −radius to 1.0 at z = radius (t increases linearly along longitudinal lines); and s ranges from 0.0 at the positive y-axis, to 0.25 at the positive x-axis, to 0.5 at the positive y-axis, to 0.75 at the positive x-axis, and back to 1.0 at the positive y-axis.

See Also

gluCylinder, gluDisk, gluNewQuadric, gluPartialDisk, gluQuadricOrientation, gluQuadricTexture


gluTessBeginContour, gluTessEndContour [New - Windows 95, OEM Service Release 2]
gluTessBeginContour, gluTessEndContour

[New - Windows 95, OEM Service Release 2]

The gluTessBeginContour and gluTessEndContour functions delimit a contour description.

void gluTessBeginContour(

GLUtesselator * tess
);
void gluTessEndContour(

GLUtesselator * tess
);
Parameters

tess

The tessellation object (created with gluNewTess).

Remarks

The gluTessBeginContour and gluTessEndContour functions delimit the definition of a polygon contour. Within each gluTessBeginContour/gluTessEndContour pair, there can be zero or more calls to gluTessVertex. The vertices specify a closed contour (the last vertex of each contour is automatically linked to the first). You can call gluTessBeginContour only between gluTessBeginPolygon and gluTessEndPolygon.

See Also

gluNewTess, gluTessBeginPolygon, gluTessCallback, gluTessEndPolygon, gluTessNormal, gluTessProperty, gluTessVertex


gluTessBeginPolygon, gluTessEndPolygon [New - Windows 95, OEM Service Release 2]
gluTessBeginPolygon, gluTessEndPolygon

[New - Windows 95, OEM Service Release 2]

The gluTessBeginPolygon and gluTessEndPolygon functions delimit a polygon description.

void gluTessBeginPolygon(

GLUtesselator * tess,
void * polygon_data
);
void gluTessEndPolygon(

GLUtesselator * tess
);
Parameters

tess

The tessellation object (created with gluNewTess).

polygon_data

A pointer to user-defined polygon data.

Remarks

The gluTessBeginPolygon and gluTessEndPolygon functions delimit the definition of a nonconvex polygon. Within each gluTessBeginPolygon/gluTessEndPolygon pair, include one or more calls to gluTessBeginContour/gluTessEndContour. Within each contour, there are zero or more calls to gluTessVertex. The vertices specify a closed contour (the last vertex of each contour is automatically linked to the first).

The polygon_data parameter is a pointer to a user-defined data structure. If the appropriate callbacks are specified (see gluTessCallback), this pointer is returned to the callback function or functions, making it a convenient way to store per-polygon information.

When you call gluTessEndPolygon, the polygon is tessellated, and the resulting triangles are described through callbacks. For descriptions of the callback functions, see gluTessCallback.

Example

The following describes a quadrilateral with a triangular hole:

gluTessBeginPolygon(tobj, NULL);

  gluTessBeginContour(tobj);

    gluTessVertex(tobj, v1, v1);

    gluTessVertex(tobj, v2, v2);

    gluTessVertex(tobj, v3, v3);

    gluTessVertex(tobj, v4, v4);

  gluTessEndContour(tobj);

  gluTessBeginContour(tobj);

    gluTessVertex(tobj, v5, v5);

    gluTessVertex(tobj, v6, v6);

    gluTessVertex(tobj, v7, v7);

  gluTessEndContour(tobj);

gluTessEndPolygon(tobj);

See Also

gluNewTess, gluTessBeginContour, gluTessCallback, gluTessEndContour, gluTessNormal, gluTessProperty, gluTessVertex


gluTessCallback [New - Windows 95, OEM Service Release 2]
gluTessCallback

[New - Windows 95, OEM Service Release 2]

The gluTessCallback function defines a callback for a tessellation object.

void gluTessCallback(

GLUtesselator * tess,
GLenum which,
void (* fn)( )
);
Parameters

tess

The tessellation object (created with gluNewTess).

which

The callback being defined. The following values are valid: GLU_TESS_BEGIN, GLU_TESS_BEGIN_DATA, GLU_TESS_EDGE_FLAG, GLU_TESS_EDGE_FLAG_DATA, GLU_TESS_VERTEX, GLU_TESS_VERTEX_DATA, GLU_TESS_END, GLU_TESS_END_DATA, GLU_TESS_COMBINE, GLU_TESS_COMBINE_DATA, GLU_TESS_ERROR, and GLU_TESS_ERROR_DATA.

For more information on these callbacks, see the following Remarks section.

fn

The function to be called.

Remarks

Use gluTessCallback to specify a callback to be used by a tessellation object. If the specified callback is already defined, then it is replaced. If fn is NULL, then the existing callback becomes undefined.

The tessellation object uses these callbacks to describe how a polygon that you specify is broken into triangles.

There are two versions of each callback, one with polygon data that you can define and one without. If both versions of a particular callback are specified, the callback with the polygon data you specify will be used. The polygon_data parameter of gluTessBeginPolygon is a copy of the pointer that was specified when gluTessBeginPolygon was called.

The following are valid callbacks:

GLU_TESS_BEGIN

The GLU_TESS_BEGIN callback is invoked like glBegin to indicate the start of a (triangle) primitive. The function takes a single argument of type GLenum. If you set the GLU_TESS_BOUNDARY_ONLY property to GL_FALSE, the argument is set to either GL_TRIANGLE_FAN, GL_TRIANGLE_STRIP, or GL_TRIANGLES. If you set the GLU_TESS_BOUNDARY_ONLY property to GL_TRUE, the argument is set to GL_LINE_LOOP. The function prototype for this callback is as follows:

void begin (GLenum type);

GLU_TESS_BEGIN_DATA

GLU_TESS_BEGIN_DATA is the same as the GLU_TESS_BEGIN callback except that it takes an additional pointer argument. This pointer is identical to the opaque pointer provided when you call gluTessBeginPolygon. The function prototype for this callback is:

void beginData (GLenum type, void * polygon_data);

GLU_TESS_EDGE_FLAG

The GLU_TESS_EDGE_FLAG callback is similar to glEdgeFlag. The function takes a single Boolean flag that indicates which edges lie on the polygon boundary. If the flag is GL_TRUE, then each vertex that follows begins an edge that lies on the polygon boundary; that is, an edge which separates an interior region from an exterior one. If the flag is GL_FALSE, then each vertex that follows begins an edge that lies in the polygon interior. The GLU_TESS_EDGE_FLAG callback (if defined) is invoked before the first vertex callback is made.

Because triangle fans and triangle strips do not support edge flags, the begin callback is not called with GL_TRIANGLE_FAN or GL_TRIANGLE_STRIP if an edge flag callback is provided. Instead, the fans and strips are converted to independent triangles. The function prototype for this callback is:

void edgeFlag (GLboolean flag);

GLU_TESS_EDGE_FLAG_DATA

The GLU_TESS_EDGE_FLAG_DATA callback is the same as the GLU_TESS_EDGE_FLAG callback except that it takes an additional pointer argument. This pointer is identical to the opaque pointer provided when you call gluTessBeginPolygon. The function prototype for this callback is:

void edgeFlagData (GLboolean flag, void * polygon_data);

GLU_TESS_VERTEX

The GLU_TESS_VERTEX callback is invoked between the begin and end callbacks. It is similar to glVertex, and it defines the vertices of the triangles created by the tessellation process. The function takes a pointer as its only argument. This pointer is identical to the opaque pointer that you provided when you defined the vertex (see gluTessVertex). The function prototype for this callback is:

void vertex (void * vertex_data);

GLU_TESS_VERTEX_DATA

The GLU_TESS_VERTEX_DATA is the same as the GLU_TESS_VERTEX callback except that it takes an additional pointer argument. This pointer is identical to the opaque pointer provided when you call gluTessBeginPolygon. The function prototype for this callback is:

void vertexData (void * vertex_data, void * polygon_data);

GLU_TESS_END

The GLU_TESS_END callback serves the same purpose as glEnd. It indicates the end of a primitive, and it takes no arguments. The function prototype for this callback is:

void end (void);

GLU_TESS_END_DATA

The GLU_TESS_END_DATA callback is the same as the GLU_TESS_END callback except that it takes an additional pointer argument. This pointer is identical to the opaque pointer provided when you call gluTessBeginPolygon. The function prototype for this callback is:

void endData (void * polygon_data);

GLU_TESS_COMBINE

Call the GLU_TESS_COMBINE callback to create a new vertex when the tessellation detects an intersection, or to merge features. The function takes four arguments:

•	An array of three elements, each of type Gldouble.

•	An array of four pointers.

•	An array of four elements, each of type GLfloat.

•	A pointer to a pointer.

The function prototype for this callback is:

void combine(GLdouble coords[3], void * vertex_data[4], GLfloat weight[4], void **outData);

The vertex is defined as a linear combination of up to four existing vertices, stored in vertex_data. The coefficients of the linear combination are given by weight; these weights always sum to 1.0. All vertex pointers are valid even when some of the weights are zero. The coords parameter gives the location of the new vertex.

Allocate another vertex, interpolate parameters using vertex_data and weight, and return the new vertex pointer in outData. This handle is supplied during rendering callbacks. Free the memory sometime after calling gluTessEndPolygon.

For example, if the polygon lies in an arbitrary plane in three-dimensional space, and you associate a color with each vertex, the GLU_TESS_COMBINE callback might look like the following:

void myCombine( GLdouble coords[3], VERTEX *d[4],

                         GLfloat w[4], VERTEX **dataOut )

{

    VERTEX *new = new_vertex();

    new->x = coords[0];

    new->y = coords[1];

    new->z = coords[2];

    new->r = w[0]*d[0]->r + w[1]*d[1]->r + w[2]*d[2]->r +

                w[3]*d[3]->r;

    new->g = w[0]*d[0]->g + w[1]*d[1]->g + w[2]*d[2]->g +

                w[3]*d[3]->g;

    new->b = w[0]*d[0]->b + w[1]*d[1]->b + w[2]*d[2]->b +

                w[3]*d[3]->b;

    new->a = w[0]*d[0]->a + w[1]*d[1]->a + w[2]*d[2]->a +

                w[3]*d[3]->a;

        *dataOut = new;

}

When the tessellation detects an intersection, the GLU_TESS_COMBINE or GLU_TESS_COMBINE_DATA callback (see below) must be defined, and must write a non-NULL pointer into dataOut. Otherwise the GLU_TESS_NEED_COMBINE_CALLBACK error occurs, and no output is generated. (This is the only error that can occur during tessellation and rendering.)

GLU_TESS_COMBINE_DATA

The GLU_TESS_COMBINE_DATA callback is the same as the GLU_TESS_COMBINE callback except that it takes an additional pointer argument. This pointer is identical to the opaque pointer provided when you call gluTessBeginPolygon. The function prototype for this callback is:

void combineData (GLdouble coords[3], void *vertex_data[4], GLfloat weight[4], void **outData, void * polygon_data);

GLU_TESS_ERROR

The GLU_TESS_ERROR callback is called when an error is encountered. The one argument is of type GLenum; it indicates the specific error that occurred and is set to one of the following: GLU_TESS_MISSING_BEGIN_POLYGON, GLU_TESS_MISSING_END_POLYGON, GLU_TESS_MISSING_BEGIN_CONTOUR, GLU_TESS_MISSING_END_CONTOUR, GLU_TESS_COORD_TOO_LARGE, or GLU_TESS_NEED_COMBINE_CALLBACK.

Call gluErrorString to retrieve character strings describing these errors. The function prototype for this callback is as follows:

void error (GLenum errno);

The GLU library recovers from the first four errors by inserting the missing call or calls. GLU_TESS_COORD_TOO_LARGE indicates that some vertex coordinate exceeded the predefined constant GLU_TESS_MAX_COORD in absolute value, and that the value has been clamped. (Coordinate values must be small enough that two can be multiplied together without overflow.) GLU_TESS_NEED_COMBINE_CALLBACK indicates that the tessellation detected an intersection between two edges in the input data, and the GLU_TESS_COMBINE or GLU_TESS_COMBINE_DATA callback was not provided. No output will be generated.

GLU_TESS_ERROR_DATA

The GLU_TESS_ERROR_DATA callback is the same as the GLU_TESS_ERROR callback, except that it takes an additional pointer argument. This pointer is identical to the opaque pointer provided when you call gluTessBeginPolygon. The function prototype for this callback is:

void errorData (GLenum errno, void * polygon_data);

Example

You can directly render tessallated polygons as follows:

gluTessCallback(tess, GLU_TESS_BEGIN, glBegin);

gluTessCallback(tess, GLU_TESS_VERTEX, glVertex3dv);

gluTessCallback(tess, GLU_TESS_END, glEnd);

gluTessBeginPolygon(tess, NULL);

    gluTessBeginContour(tess);

        gluTessVertex(tess, v, v);

        . .

    gluTessEndContour(tess);

gluTessEndPolygon(tess);

Store the tessellated polygon in a display list so that it does not need to be tessellated every time it is rendered.

See Also

glBegin, glEdgeFlag, glEnd, glVertex, gluDeleteTess, gluErrorString, gluNewTess, gluTessBeginPolygon, gluTessEndPolygon, gluTessVertex


gluTessNormal [New - Windows 95, OEM Service Release 2]
gluTessNormal

[New - Windows 95, OEM Service Release 2]

The gluTessNormal function specifies a normal for a polygon.

void gluTessNormal(

GLUtesselator * tess,
GLdouble x,
GLdouble y,
GLdouble z
);
Parameters

tess

The tessellation object (created with gluNewTess).

x

The x-coordinate component of a normal.

y

The y-coordinate component of a normal.

z

The z-coordinate component of a normal.

Remarks

The gluTessNormal function describes a normal for a polygon that you define. All input data is projected onto a plane perpendicular to one of the three coordinate axes before tessellation, and all output triangles are oriented counterclockwise with respect to the normal. (To obtain clockwise orientation, reverse the sign of the supplied normal). For example, if you know that all polygons lie in the x-y plane, call gluTessNormal(tess, 0.0, 0.0, 1.0) before rendering any polygons.

If the supplied normal is (0,0,0) (the default value), the normal is determined as follows:

1.	The direction of the normal, up to its sign, is found by fitting a plane to the vertices, without regard to how the vertices are connected. It is expected that the input data lies approximately in the plane; otherwise projection perpendicular to one of the three coordinate axes can change the geometry substantially.

2.	The sign of the normal is chosen so that the sum of the signed areas of all input contours is non-negative (where a counterclockwise contour has positive area).

The supplied normal persists until another call to gluTessNormal changes it.

See Also

gluNewTess, gluTessBeginPolygon, gluTessEndPolygon


gluTessProperty [New - Windows 95, OEM Service Release 2]
gluTessProperty

[New - Windows 95, OEM Service Release 2]

The gluTessProperty function sets the property of a tessellation object.

void gluTessProperty(

GLUtesselator * tess,
GLenum which,
GLdouble value
);
Parameters

tess

The tessellation object (created with gluNewTess).

which

The property value to set. The following values are valid: GLU_TESS_WINDING_RULE, GLU_TESS_BOUNDARY_ONLY, and GLU_TESS_TOLERANCE.

For more information about these values, see the following Remarks section.

value

The value of the indicated property.

Remarks

The gluTessProperty function controls properties stored in a tessellation object. These properties affect the way the polygons are interpreted and rendered. The following values are valid:

GLU_TESS_WINDING_RULE

Determines which parts of the polygon are on the interior. The value parameter may be set to one of the following: GLU_TESS_WINDING_ODD, GLU_TESS_WINDING_NONZERO, GLU_TESS_WINDING_POSITIVE, GLU_TESS_WINDING_NEGATIVE, or GLU_TESS_WINDING_ABS_GEQ_TWO.

To understand how the winding rule works, first consider that the input contours partition the plane into regions. The winding rule determines which of these regions are inside the polygon.

For a single-contour C, the winding number of a point x is simply the signed number of revolutions we make around x as we travel once around C (where counterclockwise is positive). When there are several contours, the individual winding numbers are summed. This procedure associates a signed integer value with each point x in the plane. Note that the winding number is the same for all points in a single region.

The winding rule classifies a region as “inside” if its winding number belongs to the chosen category (odd, nonzero, positive, negative, or absolute value of at least two). The previous GLU tessellator (prior to GLU 1.2) used the “odd” rule. The “nonzero” rule (GLU_TESS_WINDING_NONZERO) is another common way to define the interior. The other three rules (GLU_TESS_WINDING_POSITIVE, GLU_TESS_WINDING_NEGATIVE, GLU_TESS_WINDING_ABS_GEQ_TWO) are useful for polygon CSG operations.

GLU_TESS_BOUNDARY_ONLY

Specifies a Boolean value (set value to GL_TRUE or GL_FALSE). When you set value to GL_TRUE, a set of closed contours separating the polygon interior and exterior is returned instead of a tessellation. Exterior contours are oriented counterclockwise with respect to the normal; interior contours are oriented clockwise. The GLU_TESS_BEGIN and GLU_TESS_BEGIN_DATA callbacks use the type GL_LINE_LOOP for each contour.

GLU_TESS_TOLERANCE

Specifies a tolerance for merging features to reduce the size of the output. For example, two vertices that are very close to each other might be replaced by a single vertex. The tolerance is multiplied by the largest coordinate magnitude of any input vertex; this specifies the maximum distance that any feature can move as the result of a single merge operation. If a single feature takes part in several merge operations, the total distance moved can be larger.

Feature merging is completely optional; the tolerance is only a hint. The implementation is free to merge in some cases and not in others, or to never merge features at all. The default tolerance is zero.

The current implementation merges vertices only if they are exactly coincident, regardless of the current tolerance. A vertex is spliced into an edge only if the implementation is unable to distinguish which side of the edge the vertex lies on. Two edges are merged only when both endpoints are identical.

See Also

gluGetTessProperty, gluNewTess


gluTessVertex [New - Windows 95, OEM Service Release 2]
gluTessVertex

[New - Windows 95, OEM Service Release 2]

The gluTessVertex function specifies a vertex on a polygon.

void gluTessVertex(

GLUtesselator * tess,
GLdouble coords[3],
void * data
);
Parameters

tess

The tessellation object (created with gluNewTess).

coords

The location of the vertex.

data

An opaque pointer passed back to the user with the vertex callback (as specified by gluTessCallback).

Remarks

The gluTessVertex function describes a vertex on a polygon that the user is defining. Successive gluTessVertex calls describe a closed contour. For example, to describe a quadrilateral, call gluTessVertex four times. You can only call gluTessVertex between gluTessBeginContour and gluTessEndContour.

The data parameter normally points to a structure containing the vertex location, as well as other per-vertex attributes such as color and normal. This pointer is passed back to the user through the GLU_VERTEX callback after tessellation (see gluTessCallback).

Example

The following describes a quadrilateral with a triangular hole:

gluTessBeginPolygon(tess, NULL);

  gluTessBeginContour(tess);

    gluTessVertex(tess, v1, v1);

    gluTessVertex(tess, v2, v2);

    gluTessVertex(tess, v3, v3);

    gluTessVertex(tess, v4, v4);

  gluTessEndContour(tess);

gluNextContour(tess, GLU_INTERIOR);

  gluTessBeginContour(tess);

    gluTessVertex(tess, v5, v5);

    gluTessVertex(tess, v6, v6);

    gluTessVertex(tess, v7, v7);

  gluTessEndContour(tess);

gluTessEndPolygon(tess);

See Also

gluNewTess, gluTessBeginContour, gluTessBeginPolygon, gluTessCallback, gluTessEndContour, gluTessNormal, gluTessProperty


gluUnProject [New - Windows 95, OEM Service Release 2]
gluUnProject

[New - Windows 95, OEM Service Release 2]

The gluUnProject function maps window coordinates to object coordinates.

int gluUnProject(

GLdouble winx,
GLdouble winy,
GLdouble winz,
const GLdouble modelMatrix[16],
const GLdouble projMatrix[16],
const GLint viewport[4],
GLdouble * objx,
GLdouble * objy,
GLdouble * objz
);
Parameters

winx, winy, winz

The window coordinates to be mapped.

modelMatrix

The modelview matrix (as from a glGetDoublev call).

projMatrix

The projection matrix (as from a glGetDoublev call).

viewport

The viewport (as from a glGetIntegerv call).

objx, objy, objz

The computed object coordinates.

Return Values

If the function succeeds, the return value is GL_TRUE.

If the function fails, the return value is GL_FALSE.

Remarks

The gluUnProject function maps the specified window coordinates into object coordinates using modelMatrix, projMatrix, and viewport. The result is stored in objx, objy, and objz.

See Also

glGet, glGetDoublev, glGetIntegerv, gluProject


Attribute Groups

Mask Bit	Attribute Group
GL_ACCUM_BUFFER_BIT	accum-buffer
GL_ALL_ATTRIB_BITS	—
GL_COLOR_BUFFER_BIT	color-buffer
GL_CURRENT_BIT	current
GL_DEPTH_BUFFER_BIT	depth-buffer
GL_ENABLE_BIT	enable
GL_EVAL_BIT	eval
GL_FOG_BIT	fog
GL_HINT_BIT	hint
GL_LIGHTING_BIT	lighting
GL_LINE_BIT	line
GL_LIST_BIT	list
GL_PIXEL_MODE_BIT	pixel
GL_POINT_BIT	point
GL_POLYGON_BIT	polygon
GL_POLYGON_STIPPLE_BIT	polygon-stipple
GL_SCISSOR_BIT	scissor
GL_STENCIL_BUFFER_BIT	stencil-buffer
GL_TEXTURE_BIT	texture
GL_TRANSFORM_BIT	transform
GL_VIEWPORT_BIT	viewport
void glPopAttrib(void);

Restores the values of those state variables that were saved with the last glPushAttrib.


State Variables for Current Values and Associated Data

GL_CURRENT_COLOR

Description:	Current color
Attribute group:	current
Initial value:	1,1,1,1
Get command:	glGetIntegerv glGetFloatv
GL_CURRENT_INDEX

Description:	Current color index
Attribute group:	current
Initial value:	1
Get command:	glGetIntegerv glGetFloatv
GL_CURRENT_TEXTURE_COORDS

Description:	Current texture coordinates
Attribute group:	current
Initial value:	0,0,0,1
Get command:	glGetFloatv
GL_CURRENT_NORMAL

Description:	Current normal
Attribute group:	current
Initial value:	0,0,1
Get command:	glGetFloatv
GL_CURRENT_RASTER POSITION

Description:	Current raster position
Attribute group:	current
Initial value:	0,0,0,1
Get command:	glGetFloatv
GL_CURRENT_RASTER_DISTANCE

Description:	Current raster distance
Attribute group:	current
Initial value:	0
Get command:	glGetFloatv
GL_CURRENT_RASTER_COLOR

Description:	Color associated with raster position
Attribute group:	current
Initial value:	1,1,1,1
Get command:	glGetIntegerv glGetFloatv
GL_CURRENT_RASTER_INDEX

Description:	Color index associated with raster position
Attribute group:	current
Initial value:	1
Get command:	glGetIntegerv glGetFloatv
GL_CURRENT_RASTER_TEXTURE_COORDS

Description:	Texture coordinates associated with raster position
Attribute group:	current
Initial value:	0,0,0,1
Get command:	glGetFloatv
GL_CURRENT_RASTER_POSITION_VALID

Description:	Raster position valid bit
Attribute group:	current
Initial value:	GL_TRUE
Get command:	glGetBooleanv
GL_EDGE_FLAG

Description:	Edge flag
Attribute group:	current
Initial value:	GL_TRUE
Get command:	glGetBooleanv


Transformation State Variables

GL_MODELVIEW_MATRIX

Description:	Modelview matrix stack
Attribute group:	—
Initial value:	Identity
Get command:	glGetFloatv
GL_PROJECTION_MATRIX

Description:	Projection matrix stack
Attribute group:	—
Initial value:	Identity
Get command:	glGetFloatv
GL_TEXTURE_MATRIX

Description:	Texture matrix stack
Attribute group:	—
Initial value:	Identity
Get command:	glGetFloatv
GL_VIEWPORT

Description:	Viewport origin and extent
Attribute group:	viewport
Initial value:	—
Get command:	glGetIntegerv
GL_DEPTH_RANGE

Description:	Depth range near and far
Attribute group:	viewport
Initial value:	0,1
Get command:	glGetFloatv
GL_MODELVIEW_STACK_DEPTH

Description:	Modelview matrix stack pointer
Attribute group:	—
Initial value:	1
Get command:	glGetIntegerv
GL_PROJECTION_STACK_DEPTH

Description:	Projection matrix stack pointer
Attribute group:	—
Initial value:	1
Get command:	glGetIntegerv
GL_TEXTURE_STACK_DEPTH

Description:	Texture matrix stack pointer
Attribute group:	—
Initial value:	1
Get command:	glGetIntegerv
GL_MATRIX_MODE

Description:	Current matrix mode
Attribute group:	transform
Initial value:	GL_MODELVIEW
Get command:	glGetIntegerv
GL_NORMALIZE

Description:	Current normal normalization on/off
Attribute group:	transform/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_CLIP_PLANEi

Description:	User clipping plane coefficients
Attribute group:	transform
Initial value:	0,0,0,0
Get command:	glGetClipPlane
GL_CLIP_PLANEi

Description:	ith user clipping plane enabled
Attribute group:	transform/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled


Coloring State Variables

GL_FOG_COLOR

Description:	Fog color
Attribute group:	fog
Initial value:	0,0,0,0
Get command:	glGetFloatv
GL_FOG_INDEX

Description:	Fog index
Attribute group:	fog
Initial value:	0
Get command:	glGetFloatv
GL_FOG_DENSITY

Description:	Exponential fog density
Attribute group:	fog
Initial value:	1.0
Get command:	glGetFloatv
GL_FOG_START

Description:	Linear fog start
Attribute group:	fog
Initial value:	0.0
Get command:	glGetFloatv
GL_FOG_END

Description:	Linear fog end
Attribute group:	fog
Initial value:	1.0
Get command:	glGetFloatv
GL_FOG_MODE

Description:	Fog mode
Attribute group:	fog
Initial value:	GL_EXP
Get command:	glGetIntegerv
GL_FOG

Description:	True if fog enabled
Attribute group:	fog/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_SHADE_MODEL

Description:	glShadeModel setting
Attribute group:	lighting
Initial value:	GL_SMOOTH
Get command:	glGetIntegerv


Lighting State Variables

GL_LIGHTING

Description:	True if lighting is enabled
Attribute group:	lighting/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_COLOR_MATERIAL

Description:	True if color tracking is enabled
Attribute group:	lighting
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_COLOR_MATERIAL_PARAMETER

Description:	Material properties tracking current color
Attribute group:	lighting
Initial value:	GL_AMBIENT_AND_DIFFUSE
Get command:	glGetIntegerv
GL_COLOR_MATERIAL_FACE

Description:	Face(s) affected by color tracking
Attribute group:	lighting
Initial value:	GL_FRONT_AND_BACK
Get command:	glGetIntegerv
GL_AMBIENT

Description:	Ambient material color
Attribute group:	lighting
Initial value:	(0.2, 0.2, 0.2, 1.0)
Get command:	glGetMaterialfv
GL_DIFFUSE

Description:	Diffuse material color
Attribute group:	lighting
Initial value:	(0.8, 0.8, 0.8, 1.0)
Get command:	glGetMaterialfv
GL_SPECULAR

Description:	Specular material color
Attribute group:	lighting
Initial value:	(0.0, 0.0, 0.0, 1.0)
Get command:	glGetMaterialfv
GL_EMISSION

Description:	Emissive material color
Attribute group:	lighting
Initial value:	(0.0, 0.0, 0.0, 1.0)
Get command:	glGet
GL_SHININESS

Description:	Specular exponent of material
Attribute group:	lighting
Initial value:	0.0
Get command:	glGetMaterialfv
GL_LIGHT_MODEL_AMBIENT

Description:	Ambient scene color
Attribute group:	lighting
Initial value:	(0.2, 0.2, 0.2, 0.1)
Get command:	glGetFloatv
GL_LIGHT_MODEL_LOCAL_VIEWER

Description:	Viewer is local
Attribute group:	lighting
Initial value:	GL_FALSE
Get command:	glGetBooleanv
GL_LIGHT_MODEL_TWO_SIDE

Description:	Use two-sided lighting
Attribute group:	lighting
Initial value:	GL_FALSE
Get command:	glGetBooleanv
GL_AMBIENT

Description:	Ambient intensity of light i
Attribute group:	lighting
Initial value:	(0.0, 0.0, 0.0, 1.0)
Get command:	glGetLightfv
GL_DIFFUSE

Description:	Diffuse intensity of light i
Attribute group:	lighting
Initial value:	—
Get command:	glGetLightfv
GL_SPECULAR

Description:	Specular intensity of light i
Attribute group:	lighting
Initial value:	—
Get command:	glGetLightfv
GL_POSITION

Description:	Position of light i
Attribute group:	lighting
Initial value:	(0.0, 0.0, 1.0, 0.0)
Get command:	glGetLightfv
GL_CONSTANT_ATTENUATION

Description:	Constant attenuation factor
Attribute group:	lighting
Initial value:	1.0
Get command:	glGetLightfv
GL_LINEAR_ATTENUATION

Description:	Linear attenuation factor
Attribute group:	lighting
Initial value:	0.0
Get command:	glGetLightfv
GL_QUADRATIC_ATTENUATION

Description:	Quadratic attenuation factor
Attribute group:	lighting
Initial value:	0.0
Get command:	glGetLightfv
GL_SPOT_DIRECTION

Description:	Spotlight direction of light i
Attribute group:	lighting
Initial value:	(0.0, 0.0, −1.0)
Get command:	glGetLightfv
GL_SPOT_EXPONENT

Description:	Spotlight exponent of light i
Attribute group:	lighting
Initial value:	0.0
Get command:	glGetLightfv
GL_SPOT_CUTOFF

Description:	Spotlight angle of light i
Attribute group:	lighting
Initial value:	180.0
Get command:	glGetLightfv
GL_LIGHTi

Description:	True if light i enabled
Attribute group:	lighting/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_COLOR_INDEXES

Description:	C (a) , C (d) , and C (s)  for color-index lighting
Attribute group:	lighting/enable
Initial value:	0, 1, 1
Get command:	glGetFloatv


Rasterization State Variables

GL_POINT_SIZE

Description:	Point size
Attribute group:	point
Initial value:	1.0
Get command:	glGetFloatv
GL_POINT_SMOOTH

Description:	Point aliasing on
Attribute group:	point/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_LINE_WIDTH

Description:	Line width
Attribute group:	line
Initial value:	1.0
Get command:	glGetFloatv
GL_LINE_SMOOTH

Description:	Line antialiasing on
Attribute group:	line/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_LINE_STIPPLE_PATTERN

Description:	Line stipple
Attribute group:	line
Initial value:	1’s
Get command:	glGetIntegerv
GL_LINE_STIPPLE_REPEAT

Description:	Line stipple repeat
Attribute group:	line
Initial value:	1
Get command:	glGetIntegerv
GL_LINE_STIPPLE

Description:	Line stipple enable
Attribute group:	line/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_CULL_FACE

Description:	Polygon culling enabled
Attribute group:	polygon/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_CULL_FACE_MODE

Description:	Cull front-/back-facing polygons
Attribute group:	polygon
Initial value:	GL_BACK
Get command:	glGetIntegerv
GL_FRONT_FACE

Description:	Polygon front-face CW/CCW indicator
Attribute group:	polygon
Initial value:	GL_CCW
Get command:	glGetIntegerv
GL_POLYGON_SMOOTH

Description:	Polygon antialiasing on
Attribute group:	polygon/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_POLYGON_MODE

Description:	Polygon rasterization mode (front and back)
Attribute group:	polygon
Initial value:	GL_FILL
Get command:	glGetIntegerv
GL_POLYGON_STIPPLE

Description:	Polygon stipple enable
Attribute group:	polygon/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
—

Description:	Polygon stipple pattern
Attribute group:	polygon-stipple
Initial value:	1’s
Get command:	glGetPolygonStipple


Texturing State Variables

GL_TEXTURE_x

Description:	True if x-D texturing enabled (x is 1-D or 2-D)
Attribute group:	texture/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_TEXTURE

Description:	x-D texture image at level of detail i
Attribute group:	—
Initial value:	—
Get command:	glGetTexImage
GL_TEXTURE_WIDTH

Description:	x-D texture image i’s width
Attribute group:	—
Initial value:	0
Get command:	glGetTexLevelParameter
GL_TEXTURE_HEIGHT

Description:	x-D texture image i’s height
Attribute group:	—
Initial value:	0
Get command:	glGetTexLevelParameter
GL_TEXTURE_BORDER

Description:	x-D texture image i’s border
Attribute group:	—
Initial value:	0
Get command:	glGetTexLevelParameter
GL_TEXTURE_COMPONENTS

Description:	Texture image components
Attribute group:	—
Initial value:	1
Get command:	glGetTexLevelParameter
GL_TEXTURE_BORDER_COLOR

Description:	Texture border color
Attribute group:	texture
Initial value:	0,0,0,0
Get command:	glGetTexParameter
GL_TEXTURE_MIN_FILTER

Description:	Texture minification function
Attribute group:	texture
Initial value:	GL_NEAREST_MIPMAP_LINEAR
Get command:	glGetTexParameter
GL_TEXTURE_MAG_FILTER

Description:	Texture magnification function
Attribute group:	texture
Initial value:	GL_LINEAR
Get command:	glGetTexParameter
GL_TEXTURE_WRAP_x

Description:	Texture wrap mode (x is S or T)
Attribute group:	texture
Initial value:	GL_REPEAT
Get command:	glGetTexParameter
GL_TEXTURE_ENV_MODE

Description:	Texture application function
Attribute group:	texture
Initial value:	GL_MODULATE
Get command:	glGetTexEnviv
GL_TEXTURE_ENV_COLOR

Description:	Texture environment color
Attribute group:	texture
Initial value:	0,0,0,0
Get command:	glGetTexEnvfv
GL_TEXTURE_GEN_x

Description:	Texgen is enabled (x is S, T, R, or Q)
Attribute group:	texture/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_EYE_LINEAR

Description:	Texgen plane equation coefficients
Attribute group:	texture
Initial value:	—
Get command:	glGetTexGenfv
GL_OBJECT_LINEAR

Description:	Texgen object linear coefficients
Attribute group:	texture
Initial value:	—
Get command:	glGetTexGenfv
GL_TEXTURE_GEN_MODE

Description:	Function used for texgen
Attribute group:	texture
Initial value:	GL_EYTE_LINEAR
Get command:	glGetTexGeniv


Pixel Operations

GL_SCISSOR_TEST

Description:	Scissoring enabled
Attribute group:	scissor/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_SCISSOR_BOX

Description:	Scissor box
Attribute group:	scissor
Initial value:	—
Get command:	glGetIntegerv
GL_STENCIL_TEST

Description:	Stenciling enabled
Attribute group:	stencil-buffer/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_STENCIL_FUNC

Description:	Stencil function
Attribute group:	stencil-buffer
Initial value:	GL_ALWAYS
Get command:	glGetIntegerv
GL_STENCIL_VALUE_MASK

Description:	Stencil mask
Attribute group:	stencil-buffer
Initial value:	1’s
Get command:	glGetIntegerv
GL_STENCIL_REF

Description:	Stencil reference value
Attribute group:	stencil-buffer
Initial value:	0
Get command:	glGetIntegerv
GL_STENCIL_FAIL

Description:	Stencil fail action
Attribute group:	stencil-buffer
Initial value:	GL_KEEP
Get command:	glGetIntegerv
GL_STENCIL_PASS_DEPTH_FAIL

Description:	Stencil depth buffer fail action
Attribute group:	stencil-buffer
Initial value:	GL_KEEP
Get command:	glGetIntegerv
GL_STENCIL_PASS_DEPTH_PASS

Description:	Stencil depth buffer pass action
Attribute group:	stencil-buffer
Initial value:	GL_KEEP
Get command:	glGetIntegerv
GL_ALPHA_TEST

Description:	Alpha test enabled
Attribute group:	color-buffer/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_ALPHA_TEST_FUNC

Description:	Alpha test function
Attribute group:	color-buffer
Initial value:	GL_ALWAYS
Get command:	glGetIntegerv
GL_ALPHA_TEST_REF

Description:	Alpha test reference value
Attribute group:	color-buffer
Initial value:	0
Get command:	glGetIntegerv
GL_DEPTH_TEST

Description:	Depth buffer enabled
Attribute group:	depth-buffer/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_DEPTH_FUNC

Description:	Depth buffer test function
Attribute group:	depth-buffer
Initial value:	GL_LESS
Get command:	glGetIntegerv
GL_BLEND

Description:	Blending enabled
Attribute group:	color-buffer/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_BLENC_SRC

Description:	Blending source function
Attribute group:	color-buffer
Initial value:	GL_ONE
Get command:	glGetIntegerv
GL_BLEND_DST

Description:	Blending destination function
Attribute group:	color-buffer
Initial value:	GL_ZERO
Get command:	glGetIntegerv
GL_LOGIC_OP

Description:	Logical operation enabled
Attribute group:	color-buffer/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_LOGIC_OP_MODE

Description:	Logical operation function
Attribute group:	color-buffer
Initial value:	GL_COPY
Get command:	glGetIntegerv
GL_DITHER

Description:	Dithering enabled
Attribute group:	color-buffer/enable
Initial value:	GL_TRUE
Get command:	glIsEnabled


Framebuffer Control State Variables

GL_DRAW_BUFFER

Description:	Buffers selected for drawing
Attribute group:	color-buffer
Initial value:	—
Get command:	glGetIntegerv
GL_INDEX_WRITEMASK

Description:	Color-index writemask
Attribute group:	color-buffer
Initial value:	1’s
Get command:	glGetIntegerv
GL_COLOR_WRITEMASK

Description:	Color write enables; R, G, B, or A
Attribute group:	color-buffer
Initial value:	GL_TRUE
Get command:	glGetBooleanv
GL_DEPTH_WRITEMASK

Description:	Depth buffer enabled for writing
Attribute group:	depth-buffer
Initial value:	GL_TRUE
Get command:	glGetBooleanv
GL_STENCIL_WRITEMASK

Description:	Stencil-buffer writemask
Attribute group:	stencil-buffer
Initial value:	1’s
Get command:	glGetIntegerv
GL_COLOR_CLEAR_VALUE

Description:	Color-buffer clear value (RGBA mode)
Attribute group:	color-buffer
Initial value:	0, 0, 0, 0
Get command:	glGetFloatv
GL_INDEX_CLEAR_VALUE

Description:	Color-buffer clear value (color-index mode)
Attribute group:	color-buffer
Initial value:	0
Get command:	glGetFloatv
GL_DEPTH_CLEAR_VALUE

Description:	Depth-buffer clear value
Attribute group:	depth-buffer
Initial value:	1
Get command:	glGetIntegerv
GL_STENCIL_CLEAR_VALUE

Description:	Stencil-buffer clear value
Attribute group:	stencil-buffer
Initial value:	0
Get command:	glGetIntegerv
GL_ACCUM_CLEAR_VALUE

Description:	Accumulation-buffer clear value
Attribute group:	accum-buffer
Initial value:	0
Get command:	glGetFloatv


Pixel State Variables

GL_UNPACK_SWAP_BYTES

Description:	Value of GL_UNPACK_SWAP_BYTES
Attribute group:	—
Initial value:	GL_FALSE
Get command:	glGetBooleanv
GL_UNPACK_LSB_FIRST

Description:	Value of GL_UNPACK_LSB_FIRST
Attribute group:	—
Initial value:	GL_FALSE
Get command:	glGetBooleanv
GL_UNPACK_ROW_LENGTH

Description:	Value of GL_UNPACK_ROW_LENGTH
Attribute group:	—
Initial value:	0
Get command:	glGetIntegerv
GL_UNPACK_SKIP_ROWS

Description:	Value of GL_UNPACK_SKIP_ROWS
Attribute group:	—
Initial value:	0
Get command:	glGetIntegerv
GL_UNPACK_SKIP_PIXELS

Description:	Value of GL_UNPACK_SKIP_PIXELS
Attribute group:	—
Initial value:	0
Get command:	glGetIntegerv
GL_UNPACK_ALIGNMENT

Description:	Value of GL_UNPACK_ALIGNMENT
Attribute group:	—
Initial value:	4
Get command:	glGetIntegerv
GL_PACK_SWAP_BYTES

Description:	Value of GL_PACK_SWAP_BYTES
Attribute group:	—
Initial value:	GL_FALSE
Get command:	glGetBooleanv
GL_PACK_LSB_FIRST

Description:	Value of GL_PACK_LSB_FIRST
Attribute group:	—
Initial value:	GL_FALSE
Get command:	glGetBooleanv
GL_PACK_ROW_LENGTH

Description:	Value of GL_PACK_ROW_LENGTH
Attribute group:	—
Initial value:	0
Get command:	glGetIntegerv
GL_PACK_SKIP_ROWS

Description:	Value of GL_PACK_SKIP_ROWS
Attribute group:	—
Initial value:	0
Get command:	glGetIntegerv
GL_PACK_SKIP_PIXELS

Description:	Value of GL_PACK_SKIP_PIXELS
Attribute group:	—
Initial value:	0
Get command:	glGetIntegerv
GL_PACK_ALIGNMENT

Description:	Value of GL_PACK_ALIGNMENT
Attribute group:	—
Initial value:	4
Get command:	glGetIntegerv
GL_MAP_COLOR

Description:	True if colors are mapped
Attribute group:	pixel
Initial value:	GL_FALSE
Get command:	glGetBooleanv
GL_MAP_STENCIL

Description:	True if stencil values are mapped
Attribute group:	pixel
Initial value:	GL_FALSE
Get command:	glGetBooleanv
GL_INDEX_SHIFT

Description:	Value of GL_INDEX_SHIFT
Attribute group:	pixel
Initial value:	0
Get command:	glGetIntegerv
GL_INDEX_OFFSET

Description:	Value of GL_INDEX_OFFSET
Attribute group:	pixel
Initial value:	0
Get command:	glGetIntegerv
GL_x_SCALE

Description:	Value of GL_x_SCALE; x is GL_RED, GL_BLUE, GL_ALPHA, or GL_DEPTH
Attribute group:	pixel
Initial value:	1
Get command:	glGetFloatv
GL_x_BIAS

Description:	Value of GL_x_BIAS; x is GL_RED GL_BLUE, GL_ALPHA, or GL_DEPTH
Attribute group:	pixel
Initial value:	0
Get command:	glGetFloatv
GL_ZOOM_X

Description:	x zoom factor
Attribute group:	pixel
Initial value:	1.0
Get command:	glGetFloatv
GL_ZOOM_Y

Description:	y zoom factor
Attribute group:	pixel
Initial value:	1.0
Get command:	glGetFloatv
GL_x

Description:	glPixelMap translation tables
Attribute group:	pixel
Initial value:	0’s
Get command:	glGetPixelMap
GL_x_SIZE

Description:	Size of table x
Attribute group:	pixel
Initial value:	1
Get command:	glGetIntegerv
GL_READ_BUFFER

Description:	Read source buffer
Attribute group:	pixel
Initial value:	—
Get command:	glGetIntegerv


Evaluator State Variables

GL_ORDER

Description:	1-D map order
Attribute group:	—
Initial value:	1
Get command:	glGetMapiv
GL_ORDER

Description:	2-D map orders
Attribute group:	—
Initial value:	1, 1
Get command:	glGetMapiv
GL_COEFF

Description:	1-D control points
Attribute group:	—
Initial value:	—
Get command:	glGetMapfv
GL_COEFF

Description:	2-D control points
Attribute group:	—
Initial value:	—
Get command:	glGetMapfv
GL_DOMAIN

Description:	1-D domain endpoints
Attribute group:	—
Initial value:	—
Get command:	glGetMapfv
GL_DOMAIN

Description:	2-D domain endpoints
Attribute group:	—
Initial value:	—
Get command:	glGetMapfv
GL_MAP1_x

Description:	1-D map enables: x is map type
Attribute group:	eval/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_MAP2_x

Description:	2-D map enables: x is map type
Attribute group:	eval/enable
Initial value:	GL_FALSE
Get command:	glIsEnabled
GL_MAP1_GRID_DOMAIN

Description:	1-D grid endpoints
Attribute group:	eval
Initial value:	0, 1
Get command:	glGetFloatv
GL_MAP2_GRID_DOMAIN

Description:	2-D grid endpoints
Attribute group:	eval
Initial value:	0, 1; 0, 1
Get command:	glGetFloatv
GL_MAP1_GRID_SEGMENTS

Description:	1-D grid divisions
Attribute group:	eval
Initial value:	1
Get command:	glGetFloatv
GL_MAP1_GRID_SEGMENTS

Description:	2-D grid segments
Attribute group:	eval
Initial value:	1, 1
Get command:	glGetFloatv
GL_AUTO_NORMAL

Description:	True if automatic normal generation enabled
Attribute group:	eval
Initial value:	GL_FALSE
Get command:	glIsEnabled


Hint State Variables

GL_PERSPECTIVE_CORRECTION_HINT

Description:	Perspective correction hint
Attribute group:	hint
Initial value:	GL_DON’T CARE
Get command:	glGetIntegerv
GL_POINT_SMOOTH_HINT

Description:	Point smooth hint
Attribute group:	hint
Initial value:	GL_DON’T CARE
Get command:	glGetIntegerv
GL_LINE_SMOOTH_HINT

Description:	Line smooth hint
Attribute group:	hint
Initial value:	GL_DON’T CARE
Get command:	glGetIntegerv
GL_POLYGON_SMOOTH_HINT

Description:	Polygon smooth hint
Attribute group:	hint
Initial value:	GL_DON’T CARE
Get command:	glGetIntegerv
GL_FOG_HINT

Description:	Fog hint
Attribute group:	hint
Initial value:	GL_DON’T CARE
Get command:	glGetIntegerv


Implementation-Dependent State Variables

GL_MAX_LIGHTS

Description:	Maximum number of lights
Attribute group:	—
Initial value:	8
Get command:	glGetIntegerv
GL_MAX_CLIP_PLANES

Description:	Maximum number of user clipping planes
Attribute group:	—
Initial value:	6
Get command:	glGetIntegerv
GL_MAX_MODELVIEW_STACK_DEPTH

Description:	Maximum modelview-matrix stack depth
Attribute group:	—
Initial value:	32
Get command:	glGetIntegerv
GL_MAX_PROJECTION_STACK_DEPTH

Description:	Maximum projection-matrix stack depth
Attribute group:	—
Initial value:	2
Get command:	glGetIntegerv
GL_MAX_MAX_TEXTURE_STACK_DEPTH

Description:	Maximum depth of texture matrix stack
Attribute group:	—
Initial value:	2
Get command:	glGetIntegerv
GL_SUBPIXEL_BITS

Description:	Number of bits of subpixel precision in x and y
Attribute group:	—
Initial value:	4
Get command:	glGetIntegerv
GL_MAX_TEXTURE_SIZE

Description:	Maximum height or width of a texture image (without borders)
Attribute group:	—
Initial value:	64
Get command:	glGetIntegerv
GL_MAX_PIXEL_MAP_TABLE

Description:	Maximum size of a glPixelMap translation table
Attribute group:	—
Initial value:	32
Get command:	glGetIntegerv
GL_MAX_NAME_STACK_DEPTH

Description:	Maximum selection-name stack depth
Attribute group:	—
Initial value:	64
Get command:	glGetIntegerv
GL_MAX_LIST_NESTING

Description:	Maximum display-list call nesting
Attribute group:	—
Initial value:	64
Get command:	glGetIntegerv
GL_MAX_EVAL_ORDER

Description:	Maximum evaluator polynomial order
Attribute group:	—
Initial value:	8
Get command:	glGetIntegerv
GL_MAX_VIEWPORT_DIMS

Description:	Maximum viewport dimensions
Attribute group:	—
Initial value:	—
Get command:	glGetIntegerv
GL_MAX_ATTRIB_STACK_DEPTH

Description:	Maximum depth of the attribute stack
Attribute group:	—
Initial value:	16
Get command:	glGetIntegerv
GL_AUX_BUFFERS

Description:	Number of auxiliary buffers
Attribute group:	—
Initial value:	0
Get command:	glGetBooleanv
GL_RGBA_MODE

Description:	True if color buffers store RGBA
Attribute group:	—
Initial value:	—
Get command:	glGetBooleanv
GL_INDEX_MODE

Description:	True if color buffers store indexes
Attribute group:	—
Initial value:	—
Get command:	glGetBooleanv
GL_DOUBLEBUFFER

Description:	True if front and back buffers exist
Attribute group:	—
Initial value:	—
Get command:	glGetBooleanv
GL_STEREO

Description:	True if left and right buffers exist
Attribute group:	—
Initial value:	—
Get command:	glGetFloatv
GL_POINT_SIZE_RANGE

Description:	Range (low to high) of antialiased point sizes
Attribute group:	—
Initial value:	1, 1
Get command:	glGetFloatv
GL_POINT_SIZE_GRANULARITY

Description:	Antialiased point size granularity
Attribute group:	—
Initial value:	—
Get command:	glGetFloatv
GL_LINE_WIDTH_RANGE

Description:	Range (low to high) of antialiased line widths
Attribute group:	—
Initial value:	1, 1
Get command:	glGetFloatv
GL_LINE_WIDTH_GRANULARITY

Description:	Antialiased line-width granularity
Attribute group:	—
Initial value:	—
Get command:	glGetFloatv


Implementation-Dependent Pixel-Depth State Variables

GL_RED_BITS

Description:	Number of bits per red component in color buffers
Attribute group:	—
Initial value:	—
Get command:	glGetIntegerv
GL_GREEN_BITS

Description:	Number of bits per green component in color buffers
Attribute group:	—
Get command:	glGetIntegerv
Initial value:	—
GL_BLUE_BITS

Description:	Number of bits per blue component in color buffers
Attribute group:	—
Initial value:	—
Get command:	glGetIntegerv
GL_ALPHA_BITS

Description:	Number of bits per alpha component in color buffers
Attribute group:	—
Initial value:	—
Get command:	glGetIntegerv
GL_INDEX_BITS

Description:	Number of bits per index in color buffers
Attribute group:	—
Initial value:	—
Get command:	glGetIntegerv
GL_DEPTH_BITS

Description:	Number of depth-buffer bitplanes
Attribute group:	—
Initial value:	—
Get command:	glGetIntegerv
GL_STENCIL_BITS

Description:	Number of stencil bitplanes
Attribute group:	—
Initial value:	—
Get command:	glGetIntegerv
GL_ACCUM_RED_BITS

Description:	Number of bits per red component in the accumulation buffer
Attribute group:	—
Initial value:	—
Get command:	glGetIntegerv
GL_ACCUM_GREEN_BITS

Description:	Number of bits per green component in the accumulation buffer
Attribute group:	—
Initial value:	—
Get command:	glGetIntegerv
GL_ACCUM_BLUE_BITS

Description:	Number of bits per blue component in the accumulation buffer
Attribute group:	—
Initial value:	—
Get command:	glGetIntegerv
GL_ACCUM_ALPHA_BITS

Description:	Number of bits per alpha component in the accumulation buffer
Attribute group:	—
Initial value:	—
Get command:	glGetIntegerv


Miscellaneous State Variables

GL_LIST_BASE

Description:	Setting of glListBase
Attribute group:	list
Initial value:	0
Get command:	glGetIntegerv
GL_LIST_INDEX

Description:	Number of display lists under construction; 0 if none
Attribute group:	—
Initial value:	0
Get command:	glGetIntegerv
GL_LIST_MODE

Description:	Mode of display list under construction; undefined if none
Attribute group:	—
Initial value:	0
Get command:	glGetIntegerv
GL_ATTRIB_STACK_DEPTH

Description:	Attribute stack pointer
Attribute group:	—
Initial value:	0
Get command:	glGetIntegerv
GL_NAME_STACK_DEPTH

Description:	Name stack depth
Attribute group:	—
Initial value:	0
Get command:	glGetIntegerv
GL_RENDER_MODE

Description:	glRenderMode setting
Attribute group:	—
Initial value:	GL_RENDER
Get command:	glGetIntegerv
—

Description:	Current error code(s)
Attribute group:	—
Initial value:	0
Get command:	glGetError


ChoosePixelFormat [New - Windows 95, OEM Service Release 2]
ChoosePixelFormat

[New - Windows 95, OEM Service Release 2]

The ChoosePixelFormat function attempts to match an appropriate pixel format supported by a device context to a given pixel format specification.

int ChoosePixelFormat(

HDC  hdc,	// device context to search for a best pixel format match
CONST PIXELFORMATDESCRIPTOR *  ppfd	// pixel format for which a best match is sought
);
Parameters

hdc

Specifies the device context that the function examines to determine the best match for the pixel format descriptor pointed to by ppfd.

ppfd

Pointer to a PIXELFORMATDESCRIPTOR structure that specifies the requested pixel format. In this context, the members of the PIXELFORMATDESCRIPTOR structure that ppfd points to are used as follows:

nSize

Specifies the size of the PIXELFORMATDESCRIPTOR data structure. Set this member to sizeof(PIXELFORMATDESCRIPTOR).

nVersion

Specifies the version number of the PIXELFORMATDESCRIPTOR data structure. Set this member to 1.

dwFlags

A set of bit flags that specify properties of the pixel buffer. You can combine the following bit flag constants by using bitwise-OR.

If any of the following flags are set, the ChoosePixelFormat function attempts to match pixel formats that also have that flag or flags set. Otherwise, ChoosePixelFormat ignores that flag in the pixel formats:

PFD_DRAW_TO_WINDOW
PFD_DRAW_TO_BITMAP
PFD_SUPPORT_GDI
PFD_SUPPORT_OPENGL

If any of the following flags are set, ChoosePixelFormat attempts to match pixel formats that also have that flag or flags set. Otherwise, it attempts to match pixel formats without that flag set:

PFD_DOUBLEBUFFER
PFD_STEREO

If the following flag is set, the function ignores the PFD_DOUBLEBUFFER flag in the pixel formats:

PFD_DOUBLEBUFFER_DONTCARE

If the following flag is set, the function ignores the PFD_STEREO flag in the pixel formats:

PFD_STEREO_DONTCARE

iPixelType

Specifies the type of pixel format for the function to consider:

PFD_TYPE_RGBA
PFD_TYPE_COLORINDEX

cColorBits

Zero or greater.

cRedBits

Not used.

cRedShift

Not used.

cGreenBits

Not used.

cGreenShift

Not used.

cBlueBits

Not used.

cBlueShift

Not used.

cAlphaBits

Zero or greater.

cAlphaShift

Not used.

cAccumBits

Zero or greater.

cAccumRedBits

Not used.

cAccumGreenBits

Not used.

cAccumBlueBits

Not used.

cAccumAlphaBits

Not used.

cDepthBits

Zero or greater.

cStencilBits

Zero or greater.

cAuxBuffers

Zero or greater.

iLayerType

Specifies one of the following layer type values:

PFD_MAIN_PLANE
PFD_OVERLAY_PLANE
PFD_UNDERLAY_PLANE

bReserved

Not used.

dwLayerMask

Not used.

dwVisibleMask

Not used.

dwDamageMask

Not used.

Return Values

If the function succeeds, the return value is a pixel format index (one-based) that is the closest match to the given pixel format descriptor.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

You must ensure that the pixel format matched by the ChoosePixelFormat function satisfies your requirements. For example, if you request a pixel format with a 24-bit RGB color buffer but the device context offers only 8-bit RGB color buffers, the function returns a pixel format with an 8-bit RGB color buffer.

The following code sample shows how to use ChoosePixelFormat to match a specified pixel format:

PIXELFORMATDESCRIPTOR pfd = {

    sizeof(PIXELFORMATDESCRIPTOR),  //  size of this pfd

    1,                     // version number

    PFD_DRAW_TO_WINDOW |   // support window

    PFD_SUPPORT_OPENGL |   // support OpenGL

    PFD_DOUBLEBUFFER,      // double buffered

    PFD_TYPE_RGBA,         // RGBA type

    24,                    // 24-bit color depth

    0, 0, 0, 0, 0, 0,      // color bits ignored

    0,                     // no alpha buffer

    0,                     // shift bit ignored

    0,                     // no accumulation buffer

    0, 0, 0, 0,            // accum bits ignored

    32,                    // 32-bit z-buffer

    0,                     // no stencil buffer

    0,                     // no auxiliary buffer

    PFD_MAIN_PLANE,        // main layer

    0,                     // reserved

    0, 0, 0                // layer masks ignored

    };

    HDC  hdc;

    int  iPixelFormat;

iPixelFormat = ChoosePixelFormat(hdc, &pfd);

See Also

DescribePixelFormat, GetPixelFormat, SetPixelFormat


DescribePixelFormat [New - Windows 95, OEM Service Release 2]
DescribePixelFormat

[New - Windows 95, OEM Service Release 2]

The DescribePixelFormat function obtains information about the pixel format identified by iPixelFormat of the device associated with hdc. The function sets the members of the PIXELFORMATDESCRIPTOR structure pointed to by ppfd with that pixel format data.

int DescribePixelFormat(

HDC  hdc,	// device context of interest
int  iPixelFormat,	// pixel format selector
UINT  nBytes,	// size of buffer pointed to by ppfd
LPPIXELFORMATDESCRIPTOR  ppfd	// pointer to structure to receive pixel format data
);
Parameters

hdc

Specifies the device context.

iPixelFormat

Index that specifies the pixel format. The pixel formats that a device context supports are identified by positive one-based integer indexes.

nBytes

The size, in bytes, of the structure pointed to by ppfd. The DescribePixelFormat function stores no more than nBytes bytes of data to that structure. Set this value to sizeof(PIXELFORMATDESCRIPTOR).

ppfd

Pointer to a PIXELFORMATDESCRIPTOR structure whose members the function sets with pixel format data. The function stores the number of bytes copied to the structure in the structure’s nSize member. If, upon entry, ppfd is NULL, the function writes no data to the structure. This is useful when you only want to obtain the maximum pixel format index of a device context.

Return Values

If the function succeeds, the return value is the maximum pixel format index of the device context. In addition, the function sets the members of the PIXELFORMATDESCRIPTOR structure pointed to by ppfd according to the specified pixel format.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The following code sample shows DescribePixelFormat usage:

PIXELFORMATDESCRIPTOR  pfd;

HDC  hdc;

int  iPixelFormat;

iPixelFormat = 1;

// obtain detailed information about

// the device context's first pixel format

DescribePixelFormat(hdc, iPixelFormat,

        sizeof(PIXELFORMATDESCRIPTOR), &pfd);

See Also

ChoosePixelFormat, GetPixelFormat, SetPixelFormat


GetEnhMetaFilePixelFormat [New - Windows 95, OEM Service Release 2]
GetEnhMetaFilePixelFormat

[New - Windows 95, OEM Service Release 2]

The GetEnhMetaFilePixelFormat function retrieves pixel format information for an enhanced metafile.

UNIT GetEnhMetaFilePixelFormat(

HENHMETAFILE  hemf,	// handle to an enhanced metafile
DWORD cbBuffer,	// buffer size
CONST PIXELFORMATDESCRIPTOR *  ppfd	// pointer to logical pixel format specification
);
Parameters

hemf

Identifies the enhanced metafile.

cbBuffer

Specifies the size, in bytes, of the buffer into which the pixel format information is copied.

ppfd

Pointer to a PIXELFORMATDESCRIPTOR structure that contains the logical pixel format specification. The metafile uses this structure to record the logical pixel format specification.

Return Values

If the function succeeds and finds a pixel format, the return value is the size of the metafile’s pixel format.

If no pixel format is present, the return value is zero.

If an error occurs and the function fails, the return value is GDI_ERROR. To get extended error information, call GetLastError.

Remarks

When an enhanced metafile specifies a pixel format in its ENHMETAHEADER structure and the pixel format fits in the buffer, the pixel format information is copied into ppfd. When cbBuffer is too small to contain the pixel format of the metafile, the pixel format is not copied to the buffer. In either case, the function returns the size of the metafile’s pixel format.

For information on metafile recording and other operations, see Enhanced Metafile Operations.

See Also

ENHMETAHEADER, PIXELFORMATDESCRIPTOR


GetPixelFormat [New - Windows 95, OEM Service Release 2]
GetPixelFormat

[New - Windows 95, OEM Service Release 2]

The GetPixelFormat function obtains the index of the currently selected pixel format of the specified device context.

int GetPixelFormat(

HDC  hdc	// device context whose currently selected pixel format index is sought
);
Parameters

hdc

Specifies the device context of the currently selected pixel format index returned by the function.

Return Values

If the function succeeds, the return value is the currently selected pixel format index of the specified device context. This is a positive, one-based index value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The following code sample shows GetPixelFormat usage:

PIXELFORMATDESCRIPTOR  pfd;

HDC  hdc;

int  iPixelFormat;

// get the current pixel format index

iPixelFormat = GetPixelFormat(hdc);

// obtain a detailed description of that pixel format

DescribePixelFormat(hdc, iPixelFormat,

        sizeof(PIXELFORMATDESCRIPTOR), &pfd);

See Also

ChoosePixelFormat, DescribePixelFormat, SetPixelFormat


SetPixelFormat [New - Windows 95, OEM Service Release 2]
SetPixelFormat

[New - Windows 95, OEM Service Release 2]

The SetPixelFormat function sets the pixel format of the specified device context to the format specified by the iPixelFormat index.

BOOL SetPixelFormat(

HDC  hdc,	// device context whose pixel format the function attempts to set
int  iPixelFormat,	// pixel format index (one-based)
CONST PIXELFORMATDESCRIPTOR *  ppfd	// pointer to logical pixel format specification
);
Parameters

hdc

Specifies the device context whose pixel format the function attempts to set.

iPixelFormat

Index that identifies the pixel format to set. The various pixel formats supported by a device context are identified by one-based indexes.

ppfd

Pointer to a PIXELFORMATDESCRIPTOR structure that contains the logical pixel format specification. The system’s metafile component uses this structure to record the logical pixel format specification. The structure has no other effect upon the behavior of the SetPixelFormat function.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

If hdc references a window, calling the SetPixelFormat function also changes the pixel format of the window. Setting the pixel format of a window more than once can lead to significant complications for the Window Manager and for multithread applications, so it is not allowed. An application can only set the pixel format of a window one time. Once a window’s pixel format is set, it cannot be changed.

You should select a pixel format in the device context before calling the wglCreateContext function. The wglCreateContext function creates a rendering context for drawing on the device in the selected pixel format of the device context.

An OpenGL window has its own pixel format. Because of this, only device contexts retrieved for the client area of an OpenGL window are allowed to draw into the window. As a result, an OpenGL window should be created with the WS_CLIPCHILDREN and WS_CLIPSIBLINGS styles. Additionally, the window class attribute should not include the CS_PARENTDC style.

The following code example shows SetPixelFormat usage:

PIXELFORMATDESCRIPTOR pfd = {

    sizeof(PIXELFORMATDESCRIPTOR),   // size of this pfd

    1,                     // version number

    PFD_DRAW_TO_WINDOW |   // support window

    PFD_SUPPORT_OPENGL |   // support OpenGL

    PFD_DOUBLEBUFFER,      // double buffered

    PFD_TYPE_RGBA,         // RGBA type

    24,                    // 24-bit color depth

    0, 0, 0, 0, 0, 0,      // color bits ignored

    0,                     // no alpha buffer

    0,                     // shift bit ignored

    0,                     // no accumulation buffer

    0, 0, 0, 0,            // accum bits ignored

    32,                    // 32-bit z-buffer

    0,                     // no stencil buffer

    0,                     // no auxiliary buffer

    PFD_MAIN_PLANE,        // main layer

    0,                     // reserved

    0, 0, 0                // layer masks ignored

};

HDC  hdc;

int  iPixelFormat;

// get the best available match of pixel format for the device context

iPixelFormat = ChoosePixelFormat(hdc, &pfd);

// make that the pixel format of the device context

SetPixelFormat(hdc, iPixelFormat, &pfd);

See Also

ChoosePixelFormat, DescribePixelFormat, GetPixelFormat


SwapBuffers [New - Windows 95, OEM Service Release 2]
SwapBuffers

[New - Windows 95, OEM Service Release 2]

The SwapBuffers function exchanges the front and back buffers if the current pixel format for the window referenced by the specified device context includes a back buffer.

BOOL SwapBuffers(

HDC  hdc	// device context whose buffers get swapped
);
Parameters

hdc

Specifies a device context. If the current pixel format for the window referenced by this device context includes a back buffer, the function exchanges the front and back buffers.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

If the current pixel format for the window referenced by the device context does not include a back buffer, this call has no effect and the content of the back buffer is undefined when the function returns.

With multithread applications, flush the drawing commands in any other threads drawing to the same window before calling SwapBuffers.


wglCreateContext [New - Windows 95, OEM Service Release 2]
wglCreateContext

[New - Windows 95, OEM Service Release 2]

The wglCreateContext function creates a new OpenGL rendering context, which is suitable for drawing on the device referenced by hdc. The rendering context has the same pixel format as the device context.

HGLRC wglCreateContext(

HDC  hdc	// device context of device that the rendering context will be suitable for
);
Parameters

hdc

Handle to a device context for which the function creates a suitable OpenGL rendering context.

Return Values

If the function succeeds, the return value is a valid handle to an OpenGL rendering context.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

A rendering context is not the same as a device context. Set the pixel format of the device context before creating a rendering context. For more information on setting the device context’s pixel format, see the SetPixelFormat function.

To use OpenGL, you create a rendering context, select it as a thread’s current rendering context, and then call OpenGL functions. When you are finished with the rendering context, you dispose of it by calling the wglDeleteContext function.

The following code example shows wglCreateContext usage:

HDC    hdc;

HGLRC  hglrc;

// create a rendering context

hglrc = wglCreateContext (hdc);

// make it the calling thread's current rendering context

wglMakeCurrent (hdc, hglrc);

// call OpenGL APIs as desired ...

// when the rendering context is no longer needed ...

// make the rendering context not current

wglMakeCurrent (NULL, NULL) ;

// delete the rendering context

wglDeleteContext (hglrc);

See Also

SetPixelFormat, wglDeleteContext, wglGetCurrentContext, wglGetCurrentDC, wglMakeCurrent


wglCreateLayerContext [New - Windows 95, OEM Service Release 2]
wglCreateLayerContext

[New - Windows 95, OEM Service Release 2]

The wglCreateLayerContext function creates a new OpenGL rendering context for drawing to a specified layer plane on a device context.

HGLRC wglCreateLayerContext(

HDC  hdc,	// device context used for a rendering context
int  iLayerPlane	// specifies the layer plane that a rendering context is bound to
);
Parameters

hdc

Specifies the device context for a new rendering context.

iLayerPlane

Specifies the layer plane to which you want to bind a rendering context. The value 0 identifies the main plane. Positive values of iLayerPlane identify overlay planes, where 1 is the first overlay plane over the main plane, 2 is the second overlay plane over the first overlay plane, and so on. Negative values identify underlay planes, where −1 is the first underlay plane under the main plane, −2 is the second underlay plane under the first underlay plane, and so on. The number of overlay and underlay planes is given in the bReserved member of the PIXELFORMATDESCRIPTOR structure.

Return Values

If the function succeeds, the return value is a handle to an OpenGL rendering context.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

A rendering context is a port through which all OpenGL commands pass. Every thread that makes OpenGL calls must have one current, active rendering context. A rendering context is not the same as a device context; a rendering context contains information specific to OpenGL, while a device context contains information specific to GDI.

Before you create a rendering context, set the pixel format of the device context with the SetPixelFormat function. You can use a rendering context in a specified layer plane of a window with identical pixel formats only.

With OpenGL applications that use multiple threads, you create a rendering context, select it as the current rendering context of a thread, and make OpenGL calls for the specified thread. When you are finished with the rendering context of the thread, call the wglDeleteContext function. The following code example shows how to use wglCreateLayerContext.

// The following code fragment shows how to render to overlay 1

// This example assumes that the pixel format of hdc includes

// overlay plane 1

HDC hdc;

HGLRC;

// create a rendering context for overlay plane 1

hglrc = wglCreateLayerContext(hdc, 1);

// make it the calling thread's current rendering context

wglMakeCurrent(hdc, hglrc);

// call OpenGL functions here. . .

// when the rendering context is no longer needed. . .

// make the rendering context not current

wglMakeCurrent(NULL, NULL);

// delete the rendering context

wglDeleteContext(hglrc);

See Also

PIXELFORMATDESCRIPTOR, SetPixelFormat, wglCreateContext, wglDeleteContext, wglGetCurrentContext, wglGetCurrentDC, wglMakeCurrent


wglCopyContext [New - Windows 95, OEM Service Release 2]
wglCopyContext

[New - Windows 95, OEM Service Release 2]

The wglCopyContext function copies selected groups of rendering states from one OpenGL rendering context to another.

BOOL wglCopyContext(

HGLRC  hglrcSrc,	// specifies the source of a rendering context
HGLRC  hlglrcDst,	// specifies the destination of a rendering context
UINT  mask	// specifies what rendering state information is copied
);
Parameters

hglrcSrc

Specifies the source OpenGL rendering context whose state information is to be copied.

hglrcDst

Specifies the destination OpenGL rendering context to which state information is to be copied.

mask

Specifies which groups of the hglrcSrc rendering state are to be copied to hglrcDst. It contains the bitwise-OR of the same symbolic names that are passed to the glPushAttrib function. You can use GL_ALL_ATTRIB_BITS to copy all the rendering state information.

Return Values

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

Using the wglCopyContext function, you can synchronize the rendering state of two rendering contexts. You can only copy the rendering state between two rendering contexts within the same process. The rendering contexts must be from the same OpenGL implementation. For example, you can always copy a rendering state between two rendering contexts with identical pixel format in the same process.

You can copy the same state information available only with the glPushAttrib function. You cannot copy some state information, such as pixel pack/unpack state, render mode state, select state, and feedback state. When you call wglCopyContext, make sure that the destination rendering context, hglrcDst, is not current to any thread.

See Also

glPushAttrib, wglCreateLayerContext, wglCreateContext, wglShareLists


wglDeleteContext [New - Windows 95, OEM Service Release 2]
wglDeleteContext

[New - Windows 95, OEM Service Release 2]

The wglDeleteContext function deletes a specified OpenGL rendering context.

BOOL wglDeleteContext(

HGLRC  hglrc	// handle to the OpenGL rendering context to delete
);
Parameters

hglrc

Handle to an OpenGL rendering context that the function will delete.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

It is an error to delete an OpenGL rendering context that is the current context of another thread. However, if a rendering context is the calling thread’s current context, the wglDeleteContext function changes the rendering context to being not current before deleting it.

The wglDeleteContext function does not delete the device context associated with the OpenGL rendering context when you call the wglMakeCurrent function. After calling wglDeleteContext, you must call DeleteDC to delete the associated device context.

See Also

DeleteDC, wglCreateContext, wglGetCurrentContext, wglGetCurrentDC, wglMakeCurrent


wglDescribeLayerPlane [New - Windows 95, OEM Service Release 2]
wglDescribeLayerPlane

[New - Windows 95, OEM Service Release 2]

The wglDescribeLayerPlane function obtains information about the layer planes of a given pixel format.

BOOL wglDescribeLayerPlane(

HDC  hdc,	// device context whose layer planes are of interest
int  iPixelFormat,	// pixel format of the desired layer plane
int  iLayerPlane,	// specifies an overlay or underlay plane
UINT  nBytes,	// specifies the size, in bytes, of a LAYERPLANEDESCRIPTOR structure
LPLAYERPLANEDESCRIPTOR plpd	// points to a LAYERPLANEDESCRIPTOR structure
);
Parameters

hdc

Specifies the device context of a window whose layer planes are to be described.

iPixelFormat

Specifies which layer planes of a pixel format are being described.

iLayerPlane

Specifies the overlay or underlay plane. Positive values of iLayerPlane identify overlay planes, where 1 is the first overlay plane over the main plane, 2 is the second overlay plane over the first overlay plane, and so on. Negative values identify underlay planes, where −1 is the first underlay plane under the main plane, −2 is the second underlay plane under the first underlay plane, and so on. The number of overlay and underlay planes is given in the bReserved member of the PIXELFORMATDESCRIPTOR structure.

nBytes

Specifies the size, in bytes, of the structure pointed to by plpd. The wglDescribeLayerPlane function stores layer plane data in a LAYERPLANEDESCRIPTOR structure, and stores no more than nBytes of data. Set the value of nBytes to the size of LAYERPLANEDESCRIPTOR.

plpd

Points to a LAYERPLANEDESCRIPTOR structure. The wglDescribeLayerPlane function sets the value of the structure’s data members. The function stores the number of bytes of data copied to the structure in the nSize member.

Return Values

If the function succeeds, the return value is TRUE. In addition, the wglDescribeLayerPlane function sets the members of the LAYERPLANEDESCRIPTOR structure pointed to by plpd according to the specified layer plane (iLayerPlane) of the specified pixel format (iPixelFormat).

If the function fails, the return value is FALSE.

Remarks

The numbering of planes (iLayerPlane) determines their order. Higher-numbered planes overlay lower-numbered planes.

See Also

DescribePixelFormat, LAYERPLANEDESCRIPTOR, PIXELFORMATDESCRIPTOR, wglCreateLayerContext


wglGetCurrentContext [New - Windows 95, OEM Service Release 2]
wglGetCurrentContext

[New - Windows 95, OEM Service Release 2]

The wglGetCurrentContext function obtains a handle to the current OpenGL rendering context of the calling thread.

HGLRC wglGetCurrentContext(VOID);

Parameters

This function has no parameters.

Return Values

If the calling thread has a current OpenGL rendering context, wglGetCurrentContext returns a handle to that rendering context. Otherwise, the return value is NULL.

Remarks

The current OpenGL rendering context of a thread is associated with a device context by means of the wglMakeCurrent function. You can use the wglGetCurrentDC function to obtain a handle to the device context associated with the current OpenGL rendering context.

See Also

wglCreateContext, wglDeleteContext, wglGetCurrentDC, wglMakeCurrent


wglGetCurrentDC [New - Windows 95, OEM Service Release 2]
wglGetCurrentDC

[New - Windows 95, OEM Service Release 2]

The wglGetCurrentDC function obtains a handle to the device context that is associated with the current OpenGL rendering context of the calling thread.

HDC wglGetCurrentDC(VOID);

Parameters

This function has no parameters.

Return Values

If the calling thread has a current OpenGL rendering context, the function returns a handle to the device context associated with that rendering context by means of the wglMakeCurrent function. Otherwise, the return value is NULL.

Remarks

You associate a device context with an OpenGL rendering context when it calls the wglMakeCurrent function. You can use the wglGetCurrentContext function to obtain a handle to the calling thread’s current OpenGL rendering context.

See Also

wglCreateContext, wglDeleteContext, wglGetCurrentContext, wglMakeCurrent


wglGetLayerPaletteEntries [New - Windows 95, OEM Service Release 2]
wglGetLayerPaletteEntries

[New - Windows 95, OEM Service Release 2]

The wglGetLayerPaletteEntries function retrieves the palette entries from a given color-index layer plane for a specified device context.

int wglGetLayerPaletteEntries(

HDC  hdc,	// device context of a window whose layer planes are to be described
int  iLayerPlane,	// specifies an overlay or underlay plane
int  iStart,	// specifies the first palette entry to be set
int  cEntries,	// specifies the number of palette entries to be set
CONST COLORREF *pcr	// points to the first member of an array of COLORREF structures
);
Parameters

hdc

Specifies the device context of a window whose layer planes are to be described.

iLayerPlane

Specifies the overlay or underlay plane. Positive values of iLayerPlane identify overlay planes, where 1 is the first overlay plane over the main plane, 2 is the second overlay plane over the first overlay plane, and so on. Negative values identify underlay planes, where −1 is the first underlay plane under the main plane, −2 is the second underlay plane under the first underlay plane, and so on. The number of overlay and underlay planes is given in the bReserved member of the PIXELFORMATDESCRIPTOR structure.

iStart

Specifies the first palette entry to be retrieved.

cEntries

Specifies the number of palette entries to be retrieved.

pcr

Points to an array of COLORREF structures that contain palette RGB color values. The array must contain at least as many structures as specified by cEntries.

Return Values

If the function succeeds, the return value is the number of entries that were set in the palette in the specified layer plane of the window.

If the function fails or when no pixel format is selected, the return value is zero. To get extended error information, call GetLastError.

Remarks

Each color-index layer plane in a window has a palette with a size 2^n, where n is the number of bit planes in the layer plane. You cannot modify the transparent index of a palette.

Use the wglRealizeLayerPalette function to realize the layer palette. Initially the layer palette contains only entries for white.

The wglSetPaletteEntries function doesn’t set the palette entries of the main plane palette. To update the main plane palette, use GDI palette functions.

See Also

COLORREF, LAYERPLANEDESCRIPTOR, PIXELFORMATDESCRIPTOR, wglDescribeLayerPlane, wglRealizeLayerPalette, wglSetLayerPaletteEntries


wglGetProcAddress [New - Windows 95, OEM Service Release 2]
wglGetProcAddress

[New - Windows 95, OEM Service Release 2]

The wglGetProcAddress function returns the address of an OpenGL extension function for use with the current OpenGL rendering context.

PROC wglGetProcAddress(

LPCSTR  lpszProc	// name of the extension function
);
Parameters

lpszProc

Points to a null-terminated string that is the name of the extension function. The name of the extension function must be identical to a corresponding function implemented by OpenGL.

Return Values

When the function succeeds, the return value is the address of the extension function.

When no current rendering context exists or the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The OpenGL library supports multiple implementations of its functions. Extension functions supported in one rendering context are not necessarily available in a separate rendering context. Thus, for a given rendering context in an application, use the function addresses returned by the wglGetProcAddress function only.

The spelling and the case of the extension function pointed to by lpszProc must be identical to that of a function supported and implemented by OpenGL. Because extension functions are not exported by OpenGL, you must use wglGetProcAddress to get the addresses of vendor-specific extension functions.

The extension function addresses are unique for each pixel format. All rendering contexts of a given pixel format share the same extension function addresses.

See Also

glGetString, wglMakeCurrent


wglMakeCurrent [New - Windows 95, OEM Service Release 2]
wglMakeCurrent

[New - Windows 95, OEM Service Release 2]

The wglMakeCurrent function makes a specified OpenGL rendering context the calling thread’s current rendering context. All subsequent OpenGL calls made by the thread are drawn on the device identified by hdc. You can also use wglMakeCurrent to change the calling thread’s current rendering context so it’s no longer current.

BOOL wglMakeCurrent(

HDC  hdc,	// device context of device that OpenGL calls are to be drawn on
HGLRC  hglrc	// OpenGL rendering context to be made the calling thread’s current rendering context
);
Parameters

hdc

Handle to a device context. Subsequent OpenGL calls made by the calling thread are drawn on the device identified by hdc.

hglrc

Handle to an OpenGL rendering context that the function sets as the calling thread’s rendering context.

If hglrc is NULL, the function makes the calling thread’s current rendering context no longer current, and releases the device context that is used by the rendering context. In this case, hdc is ignored.

Return Values

When the wglMakeCurrent function succeeds, the return value is TRUE; otherwise the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The hdc parameter must refer to a drawing surface supported by OpenGL. It need not be the same hdc that was passed to wglCreateContext when hglrc was created, but it must be on the same device and have the same pixel format. GDI transformation and clipping in hdc are not supported by the rendering context. The current rendering context uses the hdc device context until the rendering context is no longer current.

Before switching to the new rendering context, OpenGL flushes any previous rendering context that was current to the calling thread.

A thread can have one current rendering context. A process can have multiple rendering contexts by means of multithreading. A thread must set a current rendering context before calling any OpenGL functions. Otherwise, all OpenGL calls are ignored.

A rendering context can be current to only one thread at a time. You cannot make a rendering context current to multiple threads.

An application can perform multithread drawing by making different rendering contexts current to different threads, supplying each thread with its own rendering context and device context.

If an error occurs, the wglMakeCurrent function makes the thread’s current rendering context not current before returning.

See Also

wglCreateContext, wglDeleteContext, wglGetCurrentContext, wglGetCurrentDC


wglRealizeLayerPalette [New - Windows 95, OEM Service Release 2]
wglRealizeLayerPalette

[New - Windows 95, OEM Service Release 2]

The wglRealizeLayerPalette function maps palette entries from a given color-index layer plane into the physical palette or initializes the palette of an RGBA layer plane.

BOOL wglRealizeLayerPalette(

HDC  hdc,	// device context whose layer plane palette is to be realized
int  iLayerPlane,	// specifies an overlay or underlay plane
BOOL bRealize	// indicates whether the palette is to be realized into the physical palette
);
Parameters

hdc

Specifies the device context of a window whose layer plane palette is to be realized into the physical palette.

iLayerPlane

Specifies the overlay or underlay plane. Positive values of iLayerPlane identify overlay planes, where 1 is the first overlay plane over the main plane, 2 is the second overlay plane over the first overlay plane, and so on. Negative values identify underlay planes, where −1 is the first underlay plane under the main plane, −2 is the second underlay plane under the first underlay plane, and so on. The number of overlay and underlay planes is given in the bReserved member of the PIXELFORMATDESCRIPTOR structure.

bRealize

Indicates whether the palette is to be realized into the physical palette. When bRealize is TRUE, the palette entries are mapped into the physical palette where available. When bRealize is FALSE, the palette entries for the layer plane of the window are no longer needed and might be released for use by another foreground window.

Return Values

If the function succeeds, the return value is TRUE, even if bRealize is TRUE and the physical palette is not available. If the function fails or when no pixel format is selected, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The physical palette for a layer plane is a shared resource among windows with layer planes. When more than one window attempts to realize a palette for a given physical layer plane, only one palette at a time is realized. When you call the wglRealizeLayerPalette function, the layer palette of a foreground window is always realized first.

When a window’s layer palette is realized, its palette entries are always mapped one-to-one into the physical palette. Unlike GDI logical palettes, with wglRealizeLayerPalette there is no mapping of other windows’ layer palettes to the current physical palette.

Whenever a window becomes the foreground window, call wglRealizeLayerPalette to realize its layer palettes again, even if the pixel type of the layer plane is RGBA.

Because wglRealizeLayerPalette doesn’t realize the palette of the main plane, use GDI palette functions to realize the main plane palette.

See Also

LAYERPLANEDESCRIPTOR, PIXELFORMATDESCRIPTOR, wglDescribeLayerPlane, wglGetLayerPaletteEntries, wglRealizeLayerPalette, wglSetLayerPaletteEntries


wglSetLayerPaletteEntries [New - Windows 95, OEM Service Release 2]
wglSetLayerPaletteEntries

[New - Windows 95, OEM Service Release 2]

The wglSetLayerPaletteEntries function sets the palette entries in a given color-index layer plane for a specified device context.

int wglSetLayerPaletteEntries(

HDC  hdc,	// device context whose layer palette is to be set
int  iLayerPlane,	// specifies an overlay or underlay plane
int  iStart,	// specifies the first palette entry to be set
int  cEntries,	// specifies the number of palette entries to be set
CONST COLORREF *pcr	// points to the first member of an array of COLORREF structures
);
Parameters

hdc

Specifies the device context of a window whose layer palette is to be set.

iLayerPlane

Specifies an overlay or underlay plane. Positive values of iLayerPlane identify overlay planes, where 1 is the first overlay plane over the main plane, 2 is the second overlay plane over the first overlay plane, and so on. Negative values identify underlay planes, where −1 is the first underlay plane under the main plane, −2 is the second underlay plane under the first underlay plane, and so on. The number of overlay and underlay planes is given in the bReserved member of the PIXELFORMATDESCRIPTOR structure.

iStart

Specifies the first palette entry to be set.

cEntries

Specifies the number of palette entries to be set.

pcr

Points to the first member of an array of cEntries COLORREF structures that contain RGB color information.

Return Values

If the function succeeds, the return value is the number of entries that were set in the palette in the specified layer plane of the window. If the function fails or no pixel format is selected, the return value is zero. To get extended error information, call GetLastError.

Remarks

Each color-index plane in a window has a palette with a size 2^n, where n is the number of bit planes in the layer plane. You cannot modify the transparent index of a palette.

Use the wglRealizeLayerPalette function to realize the layer palette. Initially the layer palette contains only entries for white.

The wglSetLayerPaletteEntries function doesn’t set the palette entries of the main plane palette. To update the main plane palette, use GDI palette functions.

See Also

LAYERPLANEDESCRIPTOR, PIXELFORMATDESCRIPTOR, wglDescribeLayerPlane, wglGetLayerPaletteEntries, wglRealizeLayerPalette


wglShareLists [New - Windows 95, OEM Service Release 2]
wglShareLists

[New - Windows 95, OEM Service Release 2]

The wglShareLists function enables multiple OpenGL rendering contexts to share a single display-list space.

BOOL wglShareLists(

HGLRC  hglrc1,	// OpenGL rendering context with which to share display lists
HGLRC  hglrc2	// OpenGL rendering context to share display lists
);
Parameters

hglrc1

Specifies the OpenGL rendering context with which to share display lists.

hglrc2

Specifies the OpenGL rendering context to share display lists with hglrc1. The hglrc2 parameter should not contain any existing display lists when wglShareLists is called.

Return Values

When the function succeeds, the return value is TRUE.

When the function fails, the return value is FALSE and the display lists are not shared. To get extended error information, call GetLastError.

Remarks

When you create an OpenGL rendering context, it has its own display-list space. The wglShareLists function enables a rendering context to share the display-list space of another rendering context; any number of rendering contexts can share a single display-list space. Once a rendering context shares a display-list space, the rendering context always uses the display-list space until the rendering context is deleted. When the last rendering context of a shared display-list space is deleted, the shared display-list space is deleted. All the indexes and definitions of display lists in a shared display-list space are shared.

You can only share display lists with rendering contexts within the same process. However, not all rendering contexts in a process can share display lists. Rendering contexts can share display lists only if they use the same implementation of OpenGL functions. All client rendering contexts of a given pixel format can always share display lists.

All rendering contexts of a shared display list must use an identical pixel format. Otherwise the results depend on the implementation of OpenGL used.

Note  The wglShareLists function is only available with OpenGL version 1.01 or later. To determine the version number of the implementation of OpenGL, call glGetString.

See Also

glGetString


wglSwapLayerBuffers [New - Windows 95, OEM Service Release 2]
wglSwapLayerBuffers

[New - Windows 95, OEM Service Release 2]

The wglSwapLayerBuffers function swaps the front and back buffers in the overlay, underlay, and main planes of the window referenced by a specified device context.

BOOL wglSwapLayerBuffers(

HDC  hdc,	// device context whose layer plane buffers are to be swapped
UINT  fuPlanes	// specifies the overlay, underlay and main planes to be swapped
);
Parameters

hdc

Specifies the device context of a window whose layer plane palette is to be realized into the physical palette.

fuPlanes

Specifies the overlay, underlay, and main planes whose front and back buffers are to be swapped. The bReserved member of the PIXELFORMATDESCRIPTOR structure specifies the number of overlay and underlay planes. The fuPlanes parameter is a bitwise combination of the following values.

Value	Meaning
WGL_SWAP_MAIN_PLANE	Swaps the front and back buffers of the main plane.
WGL_SWAP_OVERLAYi	Swaps the front and back buffers of the overlay plane i, where i is an integer between 1 and 15. WGL_SWAP_OVERLAY1 identifies the first overlay plane over the main plane, WGL_SWAP_OVERLAY2 identifies the second overlay plane over the first overlay plane, and so on.
WGL_SWAP_UNDERLAYi	Swaps the front and back buffers of the underlay plane i, where i is an integer between 1 and 15. WGL_SWAP_UNDERLAY1 identifies the first underlay plane under the main plane, WGL_SWAP_UNDERLAY2 identifies the second underlay plane under the first underlay plane, and so on.
Return Values

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

When a layer plane doesn’t include a back buffer, calling the wglSwapLayerBuffers function has no effect on that layer plane. After you call wglSwapLayerBuffers, the state of the back buffer content is given in the corresponding LAYERPLANEDESCRIPTOR structure of the layer plane or in the PIXELFORMATDESCRIPTOR structure of the main plane. The wglSwapLayerBuffers function swaps the front and back buffers in the specified layer planes simultaneously.

Some devices don’t support swapping layer planes individually; they swap all layer planes as a group. When the PFD_SWAP_LAYER_BUFFERS flag of the PIXELFORMATDESCRIPTOR structure is set, it indicates that a device can swap individual layer planes and that you can call wglSwapLayerBuffers.

With applications that use multiple threads, before calling wglSwapLayerBuffers, clear all drawing commands in all threads drawing to the same window.

See Also

LAYERPLANEDESCRIPTOR, PIXELFORMATDESCRIPTOR, SwapBuffers


wglUseFontBitmaps [New - Windows 95, OEM Service Release 2]
wglUseFontBitmaps

[New - Windows 95, OEM Service Release 2]

The wglUseFontBitmaps function creates a set of bitmap display lists for use in the current OpenGL rendering context. The set of bitmap display lists is based on the glyphs in the currently selected font in the device context. You can then use bitmaps to draw characters in an OpenGL image.

The wglUseFontBitmaps function creates count display lists, one for each of a run of count glyphs that begins with the first glyph in the hdc parameter’s selected fonts.

BOOL wglUseFontBitmaps(

HDC  hdc,	// device context whose font will be used
DWORD  first,	// glyph that is the first of a run of glyphs to be turned into bitmap display lists
DWORD  count,	// number of glyphs to turn into bitmap display lists
DWORD  listBase	// specifies starting display list
);
Parameters

hdc

Specifies the device context whose currently selected font will be used to form the glyph bitmap display lists in the current OpenGL rendering context.

first

Specifies the first glyph in the run of glyphs that will be used to form glyph bitmap display lists.

count

Specifies the number of glyphs in the run of glyphs that will be used to form glyph bitmap display lists. The function creates count display lists, one for each glyph in the run.

listBase

Specifies a starting display list.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The wglUseFontBitmaps function defines count display lists in the current OpenGL rendering context. Each display list has an identifying number, starting at listBase. Each display list consists of a single call to glBitmap. The definition of bitmap listBase+i is taken from the glyph first+i of the font currently selected in the device context specified by hdc. If a glyph is not defined, then the function defines an empty display list for it.

The wglUseFontBitmaps function creates bitmap text in the plane of the screen. It enables the labeling of objects in OpenGL.

In the current version of Microsoft’s implementation of OpenGL in Windows NT and Windows 95, you cannot make GDI calls to a device context that has a double-buffered pixel format. Therefore, you cannot use the GDI fonts and text functions with such device contexts. You can use the wglUseFontBitmaps function to circumvent this limitation and draw text in a double-buffered device context.

The function determines the parameters of each call to glBitmap as follows.

glBitmap Parameter	Meaning
width	The width of the glyph’s bitmap, as returned in the gmBlackBoxX member of the glyph’s GLYPHMETRICS structure.
height	The height of the glyph’s bitmap, as returned in the gmBlackBoxY member of the glyph’s GLYPHMETRICS structure.
xorig	The x offset of the glyph’s origin, as returned in the gmptGlyphOrigin.x member of the glyph’s GLYPHMETRICS structure.
yorig	The y offset of the glyph’s origin, as returned in the gmptGlyphOrigin.y member of the glyph’s GLYPHMETRICS structure.
xmove	The horizontal distance to the origin of the next character cell, as returned in the gmCellIncX member of the glyph’s GLYPHMETRICS structure.
ymove	The vertical distance to the origin of the next character cell as returned in the gmCellIncY member of the glyph’s GLYPHMETRICS structure.
bitmap	The bitmap for the glyph, as returned by GetGlyphOutline with uFormat equal to 1.
The following code example shows how to use wglUseFontBitmaps to draw some text:

HDC    hdc;

HGLRC  hglrc;

// create a rendering context

hglrc = wglCreateContext (hdc);

// make it the calling thread's current rendering context

wglMakeCurrent (hdc, hglrc);

// now we can call OpenGL API

// make the system font the device context's selected font

SelectObject (hdc, GetStockObject (SYSTEM_FONT));

// create the bitmap display lists

// we're making images of glyphs 0 thru 255

// the display list numbering starts at 1000, an arbitrary choice

wglUseFontBitmaps (hdc, 0, 255, 1000);

// display a string:

// indicate start of glyph display lists

glListBase (1000);

// now draw the characters in a string

glCallLists (24, GL_UNSIGNED_BYTE, "Hello Win32 OpenGL World");

See Also

GetGlyphOutline, glBitmap, glCallLists, glListBase, GLYPHMETRICS, wglUseFontOutlines


wglUseFontOutlines [New - Windows 95, OEM Service Release 2]
wglUseFontOutlines

[New - Windows 95, OEM Service Release 2]

The wglUseFontOutlines function creates a set of display lists, one for each glyph of the currently selected outline font of a device context, for use with the current rendering context. The display lists are used to draw 3-D characters of TrueType fonts. Each display list describes a glyph outline in floating-point coordinates.

The run of glyphs begins with the first glyph of the font of the specified device context. The em square size of the font, the notional grid size of the original font outline from which the font is fitted, is mapped to 1.0 in the x- and y-coordinates in the display lists. The extrusion parameter sets how much depth the font has in the z direction.

The lpgmf parameter returns a GLYPHMETRICSFLOAT structure that contains information about the placement and orientation of each glyph in a character cell.

BOOL wglUseFontOutlines(

HDC  hdc,	// device context of the outline font
DWORD  first,	// first glyph to be turned into a display list
DWORD  count,	// number of glyphs to be turned into display lists
DWORD  listBase,	// specifies the starting display list
FLOAT  deviation,	// specifies the maximum chordal deviation from the true outlines
FLOAT  extrusion,	// extrusion value in the negative z direction
int  format,	// specifies line segments or polygons in display lists
LPGLYPHMETRICSFLOAT  lpgmf	// address of buffer to receive glyph metric data
);
Parameters

hdc

Specifies the device context with the desired outline font. The outline font of hdc is used to create the display lists in the current rendering context.

first

Specifies the first of the set of glyphs that form the font outline display lists.

count

Specifies the number of glyphs in the set of glyphs used to form the font outline display lists. The wglUseFontOutlines function creates count display lists, one display list for each glyph in a set of glyphs.

listBase

Specifies a starting display list.

deviation

Specifies the maximum chordal deviation from the original outlines. When deviation is zero, the chordal deviation is equivalent to one design unit of the original font. The value of deviation must be equal to or greater than 0.

extrusion

Specifies how much a font is extruded in the negative z direction. The value must be equal to or greater than 0. When extrusion is 0, the display lists are not extruded.

format

Specifies the format, either WGL_FONT_LINES or WGL_FONT_POLYGONS, to use in the display lists. When format is WGL_FONT_LINES, the wglUseFontOutlines function creates fonts with line segments. When format is WGL_FONT_POLYGONS, wglUseFontOutlines creates fonts with polygons.

lpgmf

Points to an array of count GLYPHMETRICSFLOAT structures that is to receive the metrics of the glyphs. When lpgmf is NULL, no glyph metrics are returned.

Return Values

When the function succeeds, the return value is TRUE.

When the function fails, the return value is FALSE and no display lists are generated. To get extended error information, call GetLastError.

Remarks

The wglUseFontOutlines function defines the glyphs of an outline font with display lists in the current rendering context. The wglUseFontOutlines function works with TrueType fonts only; stroke and raster fonts are not supported.

Each display list consists of either line segments or polygons, and has a unique identifying number starting with the listBase number.

The wglUseFontOutlines function approximates glyph outlines by subdividing the quadratic B-spline curves of the outline into line segments, until the distance between the outline and the interpolated midpoint is within the value specified by deviation. This is the final format used when format is WGL_FONT_LINES. When you specify WGL_FONT_OUTLINES, the display lists created don’t contain any normals; thus lighting doesn’t work properly. To get the correct lighting of lines use WGL_FONT_POLYGONS and set glPolygonMode(GL_FRONT, GL_LINE). When you specify format as WGL_FONT_POLYGONS the outlines are further tessellated into separate triangles, triangle fans, triangle strips, or quadrilateral strips to create the surface of each glyph. With WGL_FONT_POLYGONS, the created display lists call glFrontFace(GL_CW) or glFrontFace(GL_CCW); thus the current front-face value might be altered. For the best appearance of text with WGL_FONT_POLYGONS, cull the back faces as follows:

glCullFace(GL_BACK);

glEnable(GL_CULL_FACE);

A GLYPHMETRICSFLOAT structure contains information about the placement and orientation of each glyph in a character cell. The lpgmf parameter is an array of GLYPHMETRICSFLOAT structures holding the entire set of glyphs for a font. Each display list ends with a translation specified with the gmfCellIncX and gmfCellIncY members of the corresponding GLYPHMETRICSFLOAT structure. The translation enables the drawing of successive characters in their natural direction with a single call to glCallLists.

Note  With the current release of OpenGL for Windows NT and Windows 95, you cannot make GDI calls to a device context when a pixel format is double-buffered. You can work around this limitation by using wglUseFontOutlines and wglUseFontBitmaps, when using double-buffered device contexts.

The following code example shows how to draw text using wglUseFontOutlines:

HDC    hdc;  // A TrueType font has already been selected

HGLRC  hglrc;

GLYPHMETRICSFLOAT agmf[256];

// Make hglrc the calling thread's current rendering context

wglMakeCurrent(hdc, hglrc);

// create display lists for glyphs 0 through 255 with 0.1 extrusion

// and default deviation. The display list numbering starts at 1000

// (it could be any number)

wglUseFontOutlines(hdc, 0, 255, 1000, 0.0f, 0.1f,

            WGL_FONT_POLYGONS, &agmf);

// Set up transformation to draw the string

glLoadIdentity();

glTranslate(0.0f, 0.0f, -5.0f)

glScalef(2.0f, 2.0f, 2.0f);

// Display a string

glListBase(1000); // Indicates the start of display lists for the glyphs

// Draw the characters in a string

glCallLists(24, GL_UNSIGNED_BYTE, "Hello Win32 OpenGL World.");

See Also

glCallLists, glListBase, glTexGen, GLYPHMETRICSFLOAT, wglUseFontBitmaps


GLYPHMETRICSFLOAT [New - Windows 95, OEM Service Release 2]
GLYPHMETRICSFLOAT

[New - Windows 95, OEM Service Release 2]

The GLYPHMETRICSFLOAT structure contains information about the placement and orientation of a glyph in a character cell.

typedef struct _GLYPHMETRICSFLOAT { // gmf

    FLOAT      gmfBlackBoxX;

    FLOAT      gmfBlackBoxY;

    POINTFLOAT gmfptGlyphOrigin;

    FLOAT      gmfCellIncX;

    FLOAT      gmfCellIncY;

} GLYPHMETRICSFLOAT;

Members

gmfBlackBoxX

Specifies the width of the smallest rectangle (the glyph’s black box) that completely encloses the glyph.

gmfBlackBoxY

Specifies the height of the smallest rectangle (the glyph’s black box) that completely encloses the glyph.

gmfptGlyphOrigin

Specifies the x and y coordinates of the upper-left corner of the smallest rectangle that completely encloses the glyph.

gmfCellIncX

Specifies the horizontal distance from the origin of the current character cell to the origin of the next character cell.

gmfCellIncY

Specifies the vertical distance from the origin of the current character cell to the origin of the next character cell.

Remarks

The values of GLYPHMETRICSFLOAT are specified as notional units.

See Also

POINTFLOAT, wglUseFontOutlines


LAYERPLANEDESCRIPTOR [New - Windows 95, OEM Service Release 2]
LAYERPLANEDESCRIPTOR

[New - Windows 95, OEM Service Release 2]

The LAYERPLANEDESCRIPTOR structure describes the pixel format of a drawing surface.

typedef struct tagLAYERPLANEDESCRIPTOR { // pfd

    WORD  nSize;

    WORD  nVersion;

    DWORD dwFlags;

    BYTE  iPixelType;

    BYTE  cColorBits;

    BYTE  cRedBits;

    BYTE  cRedShift;

    BYTE  cGreenBits;

    BYTE  cGreenShift;

    BYTE  cBlueBits;

    BYTE  cBlueShift;

    BYTE  cAlphaBits;

    BYTE  cAlphaShift;

    BYTE  cAccumBits;

    BYTE  cAccumRedBits;

    BYTE  cAccumGreenBits;

    BYTE  cAccumBlueBits;

    BYTE  cAccumAlphaBits;

    BYTE  cDepthBits;

    BYTE  cStencilBits;

    BYTE  cAuxBuffers;

    BYTE  iLayerPlane

    BYTE  bReserved;

    COLORREF crTransparent;

} LAYERPLANEDESCRIPTOR;

Members

nSize

Specifies the size of this data structure. Set this value to sizeof(LAYERPLANEDESCRIPTOR).

nVersion

Specifies the version of this data structure. Set this value to 1.

dwFlags

A set of bit flags that specify properties of the layer plane. The properties are generally not mutually exclusive; any combination of bit flags can be set, with the exceptions noted. The following bit flag constants are defined.

Value	Meaning
LPD_SUPPORT_OPENGL	The layer plane supports OpenGL drawing.
LPD_SUPPORT_GDI	The layer plane supports GDI drawing. The current implementation of OpenGL doesn’t support this flag.
LPD_DOUBLEBUFFER	The layer plane is double-buffered. A layer plane can be double-buffered even when the main plane is single-buffered and vice versa.
LPD_STEREO	The layer plane is stereoscopic. A layer plane can be stereoscopic even when the main plane is monoscopic and vice versa.
LPD_SWAP_EXCHANGE	In a double-buffered layer plane, swapping the color buffer exchanges the front buffer and back buffer contents. The back buffer then contains the contents of the front buffer before the swap. This flag is a hint only and might not be provided by a driver.
LPD_SWAP_COPY	In a double-buffered layer plane, swapping the color buffer copies the back buffer contents to the front buffer. The swap does not affect the back buffer contents. This flag is a hint only and might not be provided by a driver.
LPD_TRANSPARENT	The crTransparent member of this structure contains a transparent color or index value that enables underlying layers to show through this layer. All layer planes, except the lowest-numbered underlay layer, have a transparent color or index.
LPD_SHARE_DEPTH	The layer plane shares the depth buffer with the main plane.
LPD_SHARE_STENCIL	The layer plane shares the stencil buffer with the main plane.
LPD_SHARE_ACCUM	The layer plane shares the accumulation buffer with the main plane.
iPixelType

Specifies the type of pixel data. The following types are defined.

Value	Meaning
LPD_TYPE_RGBA	RGBA pixels. Each pixel has four components: red, green, blue, and alpha.
LPD_TYPE_COLORINDEX	Color-index pixels. Each pixel uses a color-index value.
cColorBits

Specifies the number of color bitplanes in each color buffer. For RGBA pixel types, it is the size of the color buffer, excluding the alpha bitplanes. For color-index pixels, it is the size of the color-index buffer.

cRedBits

Specifies the number of red bitplanes in each RGBA color buffer.

cRedShift

Specifies the shift count for red bitplanes in each RGBA color buffer.

cGreenBits

Specifies the number of green bitplanes in each RGBA color buffer.

cGreenShift

Specifies the shift count for green bitplanes in each RGBA color buffer.

cBlueBits

Specifies the number of blue bitplanes in each RGBA color buffer.

cBlueShift

Specifies the shift count for blue bitplanes in each RGBA color buffer.

cAlphaBits

Specifies the number of alpha bitplanes in each RGBA color buffer. Alpha bitplanes are not supported.

cAlphaShift

Specifies the shift count for alpha bitplanes in each RGBA color buffer. Alpha bitplanes are not supported.

cAccumBits

Specifies the total number of bitplanes in the accumulation buffer.

cAccumRedBits

Specifies the number of red bitplanes in the accumulation buffer.

cAccumGreenBits

Specifies the number of green bitplanes in the accumulation buffer.

cAccumBlueBits

Specifies the number of blue bitplanes in the accumulation buffer.

cAccumAlphaBits

Specifies the number of alpha bitplanes in the accumulation buffer.

cDepthBits

Specifies the depth of the depth (z-axis) buffer.

cStencilBits

Specifies the depth of the stencil buffer.

cAuxBuffers

Specifies the number of auxiliary buffers. Auxiliary buffers are not supported.

iLayerType

Specifies the layer plane number. Positive values of iLayerType identify overlay planes, where 1 is the first overlay plane over the main plane, 2 is the second overlay plane over the first overlay plane, and so on. Negative values identify underlay planes, where −1 is the first underlay plane under the main plane, −2 is the second underlay plane under the first underlay plane, and so on. The number of overlay and underlay planes is given in the bReserved member of the PIXELFORMATDESCRIPTOR structure.

bReserved

Not used. Must be zero.

crTransparent

When the LPD_TRANSPARENT flag is set, specifies the transparent color or index value. Typically the value is zero.

Remarks

Please notice, as documented above, that certain layer plane properties are not supported in the current implementation. The implementation is the Microsoft GDI software implementation of OpenGL. Hardware manufacturers that enhance parts of OpenGL may support some layer plane properties not supported by the generic implementation.

See Also

PIXELFORMATDESCRIPTOR, wglCreateLayerContext, wglDescribeLayerPlane, wglGetLayerPaletteEntries, wglRealizeLayerPalette, wglSetLayerPaletteEntries, wglSwapLayerBuffers


PIXELFORMATDESCRIPTOR [New - Windows 95, OEM Service Release 2]
PIXELFORMATDESCRIPTOR

[New - Windows 95, OEM Service Release 2]

The PIXELFORMATDESCRIPTOR structure describes the pixel format of a drawing surface.

typedef struct tagPIXELFORMATDESCRIPTOR { // pfd

    WORD  nSize;

    WORD  nVersion;

    DWORD dwFlags;

    BYTE  iPixelType;

    BYTE  cColorBits;

    BYTE  cRedBits;

    BYTE  cRedShift;

    BYTE  cGreenBits;

    BYTE  cGreenShift;

    BYTE  cBlueBits;

    BYTE  cBlueShift;

    BYTE  cAlphaBits;

    BYTE  cAlphaShift;

    BYTE  cAccumBits;

    BYTE  cAccumRedBits;

    BYTE  cAccumGreenBits;

    BYTE  cAccumBlueBits;

    BYTE  cAccumAlphaBits;

    BYTE  cDepthBits;

    BYTE  cStencilBits;

    BYTE  cAuxBuffers;

    BYTE  iLayerType;

    BYTE  bReserved;

    DWORD dwLayerMask;

    DWORD dwVisibleMask;

    DWORD dwDamageMask;

} PIXELFORMATDESCRIPTOR;

Members

nSize

Specifies the size of this data structure. This value should be set to sizeof(PIXELFORMATDESCRIPTOR).

nVersion

Specifies the version of this data structure. This value should be set to 1.

dwFlags

A set of bit flags that specify properties of the pixel buffer. The properties are generally not mutually exclusive; you can set any combination of bit flags, with the exceptions noted. The following bit flag constants are defined.

Value	Meaning
PFD_DRAW_TO_WINDOW	The buffer can draw to a window or device surface.
PFD_DRAW_TO_BITMAP	The buffer can draw to a memory bitmap.
PFD_SUPPORT_GDI	The buffer supports GDI drawing. This flag and PFD_DOUBLEBUFFER are mutually exclusive in the current generic implementation.
PFD_SUPPORT_OPENGL	The buffer supports OpenGL drawing.
PFD_GENERIC_ACCELERATED	The pixel format is supported by a device driver that accelerates the generic implementation. If this flag is clear and the PFD_GENERIC_FORMAT flag is set, the pixel format is supported by the generic implementation only.
PFD_GENERIC_FORMAT	The pixel format is supported by the GDI software implementation, which is also known as the generic implementation. If this bit is clear, the pixel format is supported by a device driver or hardware.
PFD_NEED_PALETTE	The buffer uses RGBA pixels on a palette-managed device. A logical palette is required to achieve the best results for this pixel type. Colors in the palette should be specified according to the values of the cRedBits, cRedShift, cGreenBits, cGreenShift, cBluebits, and cBlueShift members. The palette should be created and realized in the device context before calling wglMakeCurrent.
PFD_NEED_SYSTEM_PALETTE	Defined in the pixel format descriptors of hardware that supports one hardware palette in 256-color mode only. For such systems to use hardware acceleration, the hardware palette must be in a fixed order (for example, 3-3-2) when in RGBA mode or must match the logical palette when in color-index mode.  When this flag is set, you must call SetSystemPaletteUse in your program to force a one-to-one mapping of the logical palette and the system palette. If your OpenGL hardware supports multiple hardware palettes and the device driver can allocate spare hardware palettes for OpenGL, this flag is typically clear. This flag is not set in the generic pixel formats.
PFD_DOUBLEBUFFER	The buffer is double-buffered. This flag and PFD_SUPPORT_GDI are mutually exclusive in the current generic implementation.
PFD_STEREO	The buffer is stereoscopic. This flag is not supported in the current generic implementation.
PFD_SWAP_LAYER_BUFFERS	Indicates whether a device can swap individual layer planes with pixel formats that include double-buffered overlay or underlay planes. Otherwise all layer planes are swapped together as a group. When this flag is set, wglSwapLayerBuffers is supported.
You can specify the following bit flags when calling ChoosePixelFormat.

Value	Meaning
PFD_DEPTH_DONTCARE	The requested pixel format can either have or not have a depth buffer. To select a pixel format without a depth buffer, you must specify this flag. The requested pixel format can be with or without a depth buffer. Otherwise, only pixel formats with a depth buffer are considered.
PFD_DOUBLEBUFFER _DONTCARE	The requested pixel format can be either single- or double-buffered.
PFD_STEREO_DONTCARE	The requested pixel format can be either monoscopic or stereoscopic.
With the glAddSwapHintRectWIN extension function, two new flags are included for the PIXELFORMATDESCRIPTOR pixel format structure.

Value	Meaning
PFD_SWAP_COPY	Specifies the content of the back buffer in the double-buffered main color plane following a buffer swap. Swapping the color buffers causes the content of the back buffer to be copied to the front buffer. The content of the back buffer is not affected by the swap. PFD_SWAP_COPY is a hint only and might not be provided by a driver.
PFD_SWAP_EXCHANGE	Specifies the content of the back buffer in the double-buffered main color plane following a buffer swap. Swapping the color buffers causes the exchange of the back buffer’s content with the front buffer’s content. Following the swap, the back buffer’s content contains the front buffer’s content before the swap. PFD_SWAP_EXCHANGE is a hint only and might not be provided by a driver.
iPixelType

Specifies the type of pixel data. The following types are defined.

Value	Meaning
PFD_TYPE_RGBA	RGBA pixels. Each pixel has four components in this order: red, green, blue, and alpha.
PFD_TYPE_COLORINDEX	Color-index pixels. Each pixel uses a color-index value.
cColorBits

Specifies the number of color bitplanes in each color buffer. For RGBA pixel types, it is the size of the color buffer, excluding the alpha bitplanes. For color-index pixels, it is the size of the color-index buffer.

cRedBits

Specifies the number of red bitplanes in each RGBA color buffer.

cRedShift

Specifies the shift count for red bitplanes in each RGBA color buffer.

cGreenBits

Specifies the number of green bitplanes in each RGBA color buffer.

cGreenShift

Specifies the shift count for green bitplanes in each RGBA color buffer.

cBlueBits

Specifies the number of blue bitplanes in each RGBA color buffer.

cBlueShift

Specifies the shift count for blue bitplanes in each RGBA color buffer.

cAlphaBits

Specifies the number of alpha bitplanes in each RGBA color buffer. Alpha bitplanes are not supported.

cAlphaShift

Specifies the shift count for alpha bitplanes in each RGBA color buffer. Alpha bitplanes are not supported.

cAccumBits

Specifies the total number of bitplanes in the accumulation buffer.

cAccumRedBits

Specifies the number of red bitplanes in the accumulation buffer.

cAccumGreenBits

Specifies the number of green bitplanes in the accumulation buffer.

cAccumBlueBits

Specifies the number of blue bitplanes in the accumulation buffer.

cAccumAlphaBits

Specifies the number of alpha bitplanes in the accumulation buffer.

cDepthBits

Specifies the depth of the depth (z-axis) buffer.

cStencilBits

Specifies the depth of the stencil buffer.

cAuxBuffers

Specifies the number of auxiliary buffers. Auxiliary buffers are not supported.

iLayerType

Ignored. Earlier implementations of OpenGL used this member, but it is no longer used.

bReserved

Specifies the number of overlay and underlay planes. Bits 0 through 3 specify up to 15 overlay planes and bits 4 through 7 specify up to 15 underlay planes.

dwLayerMask

Ignored. Earlier implementations of OpenGL used this member, but it is no longer used.

dwVisibleMask

Specifies the transparent color or index of an underlay plane. When the pixel type is RGBA, dwVisibleMask is a transparent RGB color value. When the pixel type is color index, it is a transparent index value.

dwDamageMask

Ignored. Earlier implementations of OpenGL used this member, but it is no longer used.

Remarks

Please notice carefully, as documented above, that certain pixel format properties are not supported in the current generic implementation. The generic implementation is the Microsoft GDI software implementation of OpenGL. Hardware manufacturers may enhance parts of OpenGL, and may support some pixel format properties not supported by the generic implementation.

See Also

ChoosePixelFormat, DescribePixelFormat, GetPixelFormat, SetPixelFormat


POINTFLOAT [New - Windows 95, OEM Service Release 2]
POINTFLOAT

[New - Windows 95, OEM Service Release 2]

The POINTFLOAT structure contains the x and y coordinates of a point.

typedef struct _POINTFLOAT { // ptf

    FLOAT      x;

    FLOAT      y;

} POINTFLOAT;

Members

x

Specifies the horizontal (x) coordinate of a point.

y

Specifies the vertical (y) coordinate of a point.

See Also

GLYPHMETRICSFLOAT


C and C++ main:0000
C and C++ Design Considerations

Component objects contain data specific to the object and one or more interface implementations. The data is private and inaccessible from outside the object, while the interface implementations are public and you can access them through pointers.

Because interfaces are a binary standard, interface implementation is language independent. However, C++ is the preferred language because it supports many of the object-oriented concepts inherent in OLE. Using a procedural language such as C involves extra work, as summarized below:

•	You must explicitly initialize VTBLs either at compile-time or run-time and you should not change them later. Once initialized with function pointers, those pointers should remain unchanged until the application shuts down. VTBLs in C++ are declared as constants to prevent them from being modified inadvertently. However, in C there is no way to ensure that a VTBL will remain unchanged.

To overcome this difference, OLE provides a mechanism that lets C developers declare VTBLs as constants. To do so, place the following statement before the #include statement for the “ole2.h” header file:

#define CONST_VTABLE

•	Each method requires a pointer to the object that owns the method. In C++, all members are implicitly dereferenced off the this pointer. In C, there must be an additional first parameter passed to each method that is a pointer to the interface in which the method is declared.

•	Methods in C++ can have identical names because methods are actually known by a name that is the result of concatenating the method name to the class name. Methods in C must have a unique name to designate the object with which they are associated.

For example, the following C++ code sample defines an implementation of IUnknown::QueryInterface. The method name is QueryInterface and there are two parameters: a REFIID and a pointer to where to return the requested interface instance.

CUnknown::QueryInterface (REFIID riid, LPVOID * ppvObj);

A similar C implementation would require a more complex name and an additional first parameter to indicate the object owning the method:

IUnknown_Doc_QueryInterface (LPUNKNOWN pUnk, REFIID riid,

    LPVOID * ppvObj);

The following sections demonstrate how to declare a component object in a few typical ways: using C nested data structures, C++ nested classes, and C++ multiple inheritance. The demonstration object, called CObj, derives from IUnknown and supports two interfaces that also derive from IUnknown, InterfaceA and InterfaceB. CObj’s private data includes a pointer to another component object in the application (m_pCDoc), a count of all the external references to the object (m_ObjRefCount), and pointers to two interfaces implemented by other component objects and used by CObj (m_pOleObj and m_pStg). All object members use the m_ prefix to make it easy to distinguish between member variables and other variables.


Component Objects: C Nested Structures

C interface implementations comprise data structures nested within the object’s data structure. Each interface structure contains a VTBL pointer as its first member (pVtbl), a pointer to the object (pCObj), and a count of the external references to the interface (m_RefCount). The order of the members in the interface structures is identical, to facilitate code sharing.

typedef struct CObj {

  ULONG            m_ObjRefCount;

  LPSTORAGE        m_pStg;

  LPOLEOBJECT      m_pOleObj;

  struct CDOC    *  m_pCDoc;

  struct InterfaceA  {

    LPVTBL        pVtbl;

    struct CObj  *  pCObj;

    ULONG        m_RefCount;

  } m_InterfaceA;

  struct InterfaceB {

    LPVTBL       pVtbl;

    struct Obj  *    pCObj;

    ULONG        m_RefCount;

  } m_InterfaceB;

} COBJ;


Component Objects: C++ main:0000
Component Objects: C++ Nested Classes

The next example shows how the same object is declared and initialized using the C++ nested class approach. As in the C example, the nested class declaration includes one data structure for each interface and four private data members: an object-level reference count, two interface pointers, and a pointer to the enclosing object. The private implementations of the IUnknown methods are called by the implementations declared for the derived interfaces. For each interface implementation, there is a structure containing a public constructor and destructor, private declarations of the interface methods, a private pointer to CObj, and an interface-level reference counter for debugging purposes. To allow the nested interface classes to access the private members of the outer class, each interface class is made a friend of the outer class.

The benefits of implementing with C++ nested classes lie in the ability to include initialization code and method implementation inline. However, inline declaration is for the convenience of illustration and is not required.

class  CObj  {

private:

  ULONG          m_ObjRefCount;

  LPSTORAGE      m_pStg;

  LPOLEOBJECT    m_pOleObj;

  CDOC    *      m_pCDoc;

public:

  CObj();

  ~CObj();

  struct CUnknown : IUnknown

{

  private:

  ULONG          m_RefCount;

  CObj  *        m_pCObj;

  public:

  CUnknown(CObj (pCObj)

  { m_pCObj = pCObj; m_RefCount = 0; }

  HRESULT QueryInterface(REFIID riid, LPVOID  * ppvObj)

  ULONG AddRef(void) { return ++m_ObjRefCount; }

  ULONG Release(void);

}

friend CUnknown;

CUnknown m_Unknown;

struct InterfaceA : InterfaceA

{

  private:

  ULONG          m_RefCount;

  CObj  *        m_pCObj;

  public:

  CInterfaceA(CObj *pCObj)

  { m_pCObj = pCObj; m_RefCount = 0; }

  HRESULT QueryInterface(REFIID riid, LPVOID  * ppvObj)

  ULONG AddRef(void) { return ++m_ObjRefCount; }

  ULONG Release(void);

  HRESULT MethodA1(LPVOID  * ppvObj);

  HRESULT MethodA2(DWORD dwArg);

}

friend CInterfaceA;

CInterfaceA m_InterfaceA;

struct InterfaceB : InterfaceB

{

  private:

  ULONG          m_RefCount;

  CObj  *        m_pCObj;

  public:

  CInterfaceB(CObj *pCObj)

  { m_pCObj = pCObj; m_RefCount = 0; }

  HRESULT QueryInterface(REFIID riid, LPVOID  * ppvObj)

  ULONG AddRef(void) { return ++m_ObjRefCount; }

  ULONG Release(void);

  HRESULT MethodB1(void);

  HRESULT MethodB2(DWORD dwArg1, DWORD dwArg2);

}

friend CInterfaceB;

CInterfaceB m_InterfaceB;


Multiple Inheritance

The next example illustrates the use of C++ multiple inheritance. There are two disadvantages to using multiple inheritance with OLE. First, it is not possible to have an interface-level reference count. For more information about reference counting, see Chapter 2, “The Component Object Model.” Second, there is the potential for confusion over the interpretation of the class statement. A standard C++ multiple inheritance declaration implies the “is a” relationship where an object inherits implementations. In OLE, however, interfaces are attributes of the object and implementations are not inherited.

The main advantage to using multiple inheritance lies in its simplicity. Only the prototypes for each of the interface methods are listed; no interface data structures or class definitions are necessary.

Because both InterfaceA and InterfaceB inherit from IUnknown, it is not necessary to list IUnknown explicitly in the class statement. A single implementation of the IUnknown methods (QueryInterface, AddRef, and Release) is sufficient.

class  CObj : public InterfaceA, public InterfaceB

{

private:

  ULONG          m_ObjRefCount;

  LPSTORAGE      m_pStg;

  LPOLEOBJECT    m_pOleObj;

  CDOC  *        m_pCDoc;

public:

  CObj();

  ~CObj();

  HRESULT QueryInterface(REFIID riid, LPVOID  * ppvObj)

  ULONG AddRef(void) { return ++m_ObjRefCount; }

  ULONG Release(void);

  HRESULT MethodA1(LPVOID  * ppvObj);

  HRESULT MethodA2(DWORD dwArg);

  HRESULT MethodB1(void);

  HRESULT MethodB2(DWORD dwArg1, DWORD dwArg2);

};


APPENDIX A


Compatibility with OLE 1 and 16:32-Bit Interoperability

Note  In moving from OLE 1 to OLE 2, the following changes in terminology were made:

•	The OLE 1 term “server application” has been changed to “object application.”

•	The OLE 1 term “client application” has been changed to “container application.”

Compatibility implies that an OLE 1 client application can contain OLE 2 embedded and linked objects and that an OLE 1 server application can create objects to be embedded in and linked to by OLE 2 containers. OLE provides these capabilities by means of a built-in compatibility layer in the core code, which includes a set of functions for conversion.

Interoperability is not the same as OLE 1 to OLE 2 compatibility. Interoperability implies that a 16-bit OLE application can interact with a 32-bit application running on the same system. Interoperability between 16- and 32-bit implementations means that 16-bit and 32-bit implementations can call each other.


Compatibility with OLE 1

Compatibility between OLE 2 and OLE 1 applications is achieved through the implementation of two types of special remoting objects, called stubs and proxies. The stub is instantiated on the object, or server, application’s side of the process; the proxy is instantiated on the container, or client, application’s side. These special stubs and proxies use DDE to communicate rather than LRPC. When an OLE 2 object makes a call to a function in an OLE 1 client application, for example, the stub intercepts the call and responds appropriately. For the most part, this response simulates the response that an OLE 2 object or container would make. However, in a few cases the behavior is different or special HRESULT (SCODE) values are returned.

This chapter discusses the issues that affect applications that must be compatible with an earlier or more recent version of OLE and describes the functions that promote this compatibility.


Working with OLE 1 Clients

This section describes some of the idiosyncrasies of working with OLE 1 clients.

A successful call to the IOleClientSite::GetContainer method returns a pointer to the container’s IOleContainer interface. If the container does not support the IOleContainer interface, OLE_E_NOT_SUPPORTED is returned. All OLE 1 clients fall in this category, as do OLE 2 containers that do not support linking to their embedded objects.

The IOleClientSite::ShowObject method, a request to make the embedded or linked object visible, always returns OLE_E_NOT_SUPPORTED when called on an OLE 1 client. The purpose of this method is to help make the user model work smoothly; its failure does not effect OLE functionality.

When an OLE 1 client contains an OLE 2 object and the object is activated or the OleUpdate function is called, the aspect of the data returned will always be DVASPECT_CONTENT. This is because OLE 1 clients have no concept of a FORMATETC data structure. This situation may occur when an iconic OLE 2 object is pasted from an OLE 2 container into an OLE 1 container. When the object is first pasted, its presentation remains iconic. With the next update, however, the object’s content picture is returned.

OLE 1 clients can link to OLE 2 objects only if the link source:

•	is represented by a file moniker or a generic composite moniker consisting of a file moniker and one item moniker.

•	is not an embedded OLE 2 object.

An OLE 1 client can contain an incompatible link when a linked object is pasted from an OLE 2 container into the OLE 1 client or when an OLE 2 container saves the data to an OLE 1 file, to allow the OLE 1 version of the application access to its data. When the OLE 1 client loads the incompatible link, the link is converted to an embedded object and assigned the class name “Ole2Link.” The OLE 1 client cannot connect to the link source. However, if the newly embedded object is then pasted into an OLE 2 container using the Clipboard, or converted to an OLE 2 object using the OleConvertOLESTREAMToIStorage function, it will be converted back to its original state as an OLE 2 linked object.

When the link source for an OLE 1 linked object changes its name, the link can remain intact only if the file moniker for the link source has changed. That is, if the link source is a range of cells within an OLE 2 spreadsheet application and the name of the file that contains the cell range changes, OLE will track the link. However, if the name of the cell range changes, the link will break.

Pasting an OLE 2 linked object into an OLE 1 client document and then calling the OleCopyFromLink function to convert it to an embedded object will fail if the data transfer object provided by the link source does not support the IPersistStorage interface. Creating an embedded object always requires native data, and the IPersistStorage interface provides access to native data.


Working with OLE 1 Servers

This section describes some of the known idiosyncrasies of embedding or linking OLE 1 objects.

As with OLE 2 objects, either the IPersistStorage::InitNew method or the IPersistStorage::Load method must be called to properly initialize a newly instantiated OLE 1 object before any other OLE calls are made. The InitNew method should be called to initialize a newly created object; the Load method should be called for existing objects. If one of the OleCreate helper functions or the OleLoad function is being used, these functions make the IPersistStorage call, eliminating the need to make the call directly. When an OLE 2 container with an OLE 1 embedded or linked object calls the IDataObject::GetData method or the IDataObject::GetDataHere method, the container can anticipate support for a smaller set of formats and storage mediums than would be supported for an OLE 2 object. The following table lists the combinations that can be supported.

Tymed Formats	Data Formats
TYMED_MFPICT	CF_METAFILEPICT
TYMED_GDI	CF_BITMAP
TYMED_HGLOBAL	cfNative, CF_DIB, and other OLE 1 server formats
For the aspect value of DVASPECT_ICON, only TYMED_MFPICT with CF_METAFILEPICT is supported. The icon returned from the IDataObject::GetData or IDataObject::GetDataHere call will always be the first icon (index 0) in the executable object application.

Several methods typically called by containers have unique implementations for OLE 1. The IPersistStorage::IsDirty method is defined to return S_OK if the object has changed since its last save to persistent storage; S_FALSE if it has not changed. When an OLE 2 container with an OLE 1 embedded object calls the IPersistStorage::IsDirty method, the compatibility code always returns S_OK when the server is running, because there is no way to determine if the object has in fact changed until the File Close or File Update command is selected. S_FALSE is returned when the server is not running.

An OLE 2 implementation of IOleObject::IsUpToDate can return either S_OK if the object is up-to-date, S_FALSE if it is not up-to-date, or OLE_E_UNAVAILABLE if the object cannot determine whether it is up-to-date. The OLE 1 implementation always returns either E_NOT_RUNNING, if the object is in the loaded state, or S_FALSE, if the server is running.

The OLE 1 implementation of the IOleItemContainer::EnumObjects method always returns OLE_E_NOTSUPPORTED because it is not possible for an OLE 1 server to enumerate its objects.

The IOleObject::Close method takes a save option as a parameter that indicates whether the object should be saved before the close occurs. For OLE 2 objects, there are three possible save options: OLECLOSE_SAVEIFDIRTY, OLECLOSE_NOSAVE, and OLECLOSE_PROMPTSAVE. The OLE 1 implementation of the IOleObject::Close method treats OLECLOSE_PROMPTSAVE as equivalent to OLECLOSE_SAVEIFDIRTY, because it is not possible to require an OLE 1 server to prompt the user.

OLE 2 containers cannot expect an OLE 1 object to activate in-place; all OLE 1 objects support activation in a separate, open window.

OLE 1 servers do not support linking to their embedded objects. It is up to OLE 2 containers with OLE 1 embedded objects to prevent a possible link from occurring. Containers can call the CoIsOle1Class function to determine at Clipboard copy time if a data selection being copied is an OLE 1 object. If the CoIsOle1Class function returns TRUE, indicating that the selection is an OLE 1 object, the container should not offer the Link Source format. Link Source must be available for a linked object to be created.

OLE 2 containers can store multiple presentations for an OLE 1 object. However, only the first presentation format is sent to the container when the OLE 1 server closes. After that, the server is in the process of closing down and cannot honor requests for any more formats. Therefore, only the first presentation cache will be updated. The rest will be out of date (perhaps blank) if the object has changed since the last update.

Because OLE 1 servers do not update the cache for every change to an embedded object until the user selects the File Update command, an OLE 2 container may not be obtaining the latest data from the server. By calling the IOleObject::Update method, the container can obtain the latest object data.

An OLE 1 embedded (not linked) object does not notify its container that its data has changed until the user chooses File Update or File Close. Therefore, if an OLE 2 container registers for a data-change notification on an OLE 2 object in a particular format, it should be aware that it will not be notified immediately when the data changes.

When an OLE 1 object is inserted into a container document and then closed without an update being invoked, the container document is not saved. Neither are the correct streams for the object written into storage. Any subsequent loading of the object by the container will fail. To protect against this, containers can keep data available after the object closes without updating by implementing the following:

OleCreate();             \\ to insert the object

OleRun();                \\ if OLERENDER_NONE was specified

IOleObject::Update();    \\ to get snapshot of data

OleSave();

IOleObject::DoVerb();


OLE 1/Registry Compatibility Information

This section discusses the registry and how to handle compatibility issues between OLE 1 and  related to OLE 2.


OLE 1 Compatibility Subkeys

To handle two-way compatibility, the OLE 2 compatibility layer creates OLE 2-style entries for OLE 1 classes it discovers and places them under the CLSID key. When installing an OLE 2 object application on a system that contains an OLE 1 version of the same application, it might be necessary to add “AutoConvertTo” or “TreatAs” subkeys to the original OLE 1 application portion of the registry. For more information, see “When the OLE 1 Version is Overwritten,” later in this section.


Information for OLE 1 Applications Subkey Entries

To maintain compatibility with OLE 1, you must include specific OLE 1 information. The “server” key entry should contain a full path to the application. The entries for verbs must start with 0 as the primary verb and be consecutively numbered.

Hkey_Classes_Root\Ole2isvrotl\Protocol\Stdfileediting\Server =

    C:\Samp\Isvrotl.Exe

Hkey_Classes_Root\Ole2isvrotl\Protocol\Stdfileediting\Verb\0 = &Edit

Hkey_Classes_Root\Ole2isvrotl\Protocol\Stdfileediting\Verb\1 = &Open


OLE 1 Application Entries

When an OLE 1 class is inserted into an OLE 2 container for the first time, a new subkey, CLSID, is added to the original OLE 1 registration information by the OLE 2 compatibility layer. The value given to this key is a CLSID assigned by OLE 2 to this OLE 1 class as shown in the following portion of the registry.

<OLE1ClassName> = <OLE1UserTypeName>
    Protocol
        StdFileEditing
        Verb
    CLSID = <CLSID>


ProgID and OLE 1 Compatibility

Programmatic identifiers are not guaranteed to be unique so they can be used only where name collisions are manageable, such as in achieving compatibility with OLE 1. Also, the ProgID is the “class name” used for an OLE 2 class when it is placed in a server application (OLE 1 server).

Note  Because OLE 2 provides a built-in OLE 1/OLE 2 compatibility layer, rarely will an OLE 2 class that is insertable in an OLE 2 container not be insertable in an OLE 1 container.


Version-dependent Identifiers

The <VersionDependentProgID> is the string to use when OLE 1 needs to contact OLE 2 using DDE. Version-dependent ProgID-to-CLSID conversions must be specific, well-defined, and one-to-one.


Inserting an OLE 2 Object in an OLE 1 Application

If a particular class is insertable in an OLE 1 container, the “ProgID” root key will contain a Protocol\StdFileEditing subkey with appropriate subkeys Verb, Server, and so on, as in OLE 1. The Server that should be registered here is the full path to the executable file of the OLE 2 object application. An OLE 1 container uses the path and executable file names to launch the OLE 2 object application. The initialization of this application, in turn, loads the OLE 2 compatibility layer. This layer handles subsequent interactions with the OLE 1 container (client), turning them into OLE 2−like requests to the OLE 2 application. An OLE 2 object application doesn’t have to take any special action beyond setting up these registry entries to make objects insertable into an OLE 1 container.

The ProgID key and its subkeys appear in the registry as shown in the following example, where “<Progid>“ is the key, and “Insertable,” “Protocol,” “StdFileEditing,” “Verb,” and so on are subkeys.

<ProgId> = <MainUserTypeName>
Insertable    // class is insertable in OLE 2 containers
Protocol
    StdFileEditing    // OLE 1 compatibility info; present if, and only if,
                               // objects of this class are insertable in OLE 1 containers.
        Server = <full path to the OLE 2 object application>
        Verb
            0 = <verb 0>    // Verb entries for the OLE 2 application must start with zero as the
            1 = <verb 1>    // primary verb and run consecutively.
CLSID = <CLSID>    // The corresponding CLSID. Needed by GetClassFile.
Shell    // Windows 3.1 File Manager Info
    Print
    Open
    Command = <appname.exe> %1

To summarize, any root key that has either an Insertable or a Protocol\StdFileEditing subkey is the ProgID (or OLE 1 class name) of a class that should appear in the Insert Object dialog box. The value of that root key is the name displayed in the Insert Object dialog box.

The values of each key in the example below are used for registering the “Ole 2 In-Place Server Outline” sample application. Set these values as required and used by your application.


Specifying Unregistered Verbs

It is possible to register OLE 1 object applications (servers) with no specified verbs. In such cases, the application has a single implied verb that is understood to be “edit” by OLE 1 containers. When an OLE 2 application calls the IOleObject::EnumVerbs method (or the OleRegEnumVerbs function) on an object of this class, one verb is enumerated. By default, the name of the verb is “Edit.” To avoid having the string “Edit” as the enumerated verb, a key can be included in the registry. This key is

\Software\Microsoft\OLE1\UnregisteredVerb = <verbname>

(where verbname is the value that will be returned from the enumeration) and allows for localization of the default verb to a specified string to accommodate a specific language.

Note  Do not attempt to register a verb (under ProgID\Protocol\StdFileEditing) for an application that did not register the verb itself.


Accommodating OLE 1 Versions of the Object Application

When the OLE 1 version of an object application is superseded by an OLE 2 version and the OLE 2 version is to be installed in the user’s system, such as when upgrading, two situations can arise:

•	An OLE 1 version of the application is present on the user’s system and the installation process overwrites the OLE 1 executable with the OLE 2 version.

•	An OLE 1 version of the application is present on the user’s system and the user chooses not to overwrite it with the OLE 2 version.

Note  Even if the OLE 1 object application is not on the user’s system, the install/setup program for the OLE 2 object application should register the application as capable of servicing its OLE 1 objects. To do this, follow the guidelines presented under “When the OLE 1 Version is Overwritten,” and add the following entry to the CLSID root key:

<OLE 1 class name>/CLSID = <CLSID of OLE 1 application>


When the OLE 1 Version is Overwritten

When the OLE 1 object application is replaced by the OLE 2 version, do the following. (For the purpose of illustration, the OLE 1 object application is referred to as Ole 1 In-Place Server Outline while the OLE 2 version is Ole 2 In-Place Server Outline, as shown in the dialog box illustrations that follow).

1.	Register Ole 2 In-Place Server Outline.

2.	Modify (with your install/setup program) the original registry entries of Ole 1 In-Place Server Outline by changing the executable path to point to the Ole 2 In-Place Server Outline executable.

For example, the Server subkey for the OLE 1 executable, named svrapp.exe in this example, changes from

OLE1ISvrOtl\Protocol\StdFileEditing\Server = svrapp.exe

to

OLE1ISvrOtl\Protocol\StdFileEditing\Server = isvrotl.exe

where isvrotl.exe is the name of the OLE 2 object application.

Next, proceed to either step 3 or step 4, depending on whether or not you want OLE 1 objects converted automatically to the OLE 2 format.

3.	If Ole 1 In-Place Server Outline objects will be converted automatically to the Ole 2 In-Place Server Outline format when the application is saved, create or modify the following registration database entries:

a.	Modify the original registry entry of Ole 1 In-Place Server Outline by changing the “Value of the ProgID = Main User Type Name” key of the entry to Ole 2 In-Place Server Outline.

For example, where OLE1ISvrOtl is the ProgID of the OLE 1 application,

OLE1ISvrOtl = Ole 1 In-Place Server Outline

becomes

OLE1ISvrOtl = Ole 2 In-Place Server Outline

b.	Modify the original registry entry of Ole 1 In-Place Server Outline by adding a NotInsertable subkey under the ProgID key. For example:

HKEY_CLASSES_ROOT\OLE1SvrOtl\NotInsertable

Note  Since the original registry entries for the OLE 1 server application remain (but with a pointer to the OLE 2 object application as shown in the preceding step 3a), the OLE 1 ProgID will appear in the Insert Object dialog box of any OLE 2 container application installed on the system. The NotInsertable subkey mentioned in step 3b prevents the ProgID of the OLE 1 application from appearing in the Insert Object dialog box of OLE 2 containers. The NotInsertable subkey overrides any Insertable subkey entries for that ProgID key.

c.	Set the “AutoConvertTo = CLSID” subkey entry for Ole 1 In-Place Server Outline under the CLSID key to the CLSID of Ole 2 In-Place Server Outline. (See also “OLE 1 Compatibility Subkeys”).

CLSID\{CLSID of OLE 1 app.}\AutoConvertTo = {CLSID of OLE 2 app.}

Note  You can obtain the CLSID of the OLE 1 object application for inclusion in registration entry file by calling CLSIDFromProgID.

d.	Modify the original registry entry of Ole 1 In-Place Server Outline by setting the verbs to those of Ole 2 In-Place Server Outline.

For example, change

OLE1ISvrOtl\Protocol\StdFileEditing\Verb\0 = &Edit

to

OLE1ISvrOtl\Protocol\StdFileEditing\Verb\0 = &Edit

OLE1ISvrOtl\Protocol\StdFileEditing\Verb\1 = &Open

4.	If the user is allowed to open Acme Draw 1.0 objects and save them back to disk in the Acme Draw 1.0 format:

a.	Set the “TreatAs = CLSID” entry to the CLSID of Ole 2 In-Place Server Outline using the following form.

CLSID\{CLSID of OLE 1 app.}\TreatAs = {CLSID of OLE 2 app.}

b.	Set the Ole 1 In-Place Server Outline verbs to those of Ole 2 In-Place Server Outline as described in the preceding step 3.


When the OLE 1 Version is Not Overwritten

You can install your program so the OLE 1 object application (Ole 1 In-Place Server Outline) is not replaced by the OLE 2 version (Ole 2 In-Place Server Outline). Instead, the user is allowed to open Ole 1 In-Place Server Outline objects with the Ole 2 In-Place Server Outline and save them back to disk in the Ole 1 In-Place Server Outline format. To do this, set the “TreatAs = CLSID” entry (Ole 1 In-Place Server Outline’s portion of the registry) to the CLSID of Ole 2 In-Place Server Outline (as in step 4 above).

If the OLE 1 version of the application is not overwritten, or if the user does not want to set the “Treat As” option, register the OLE 2 version as a separate and new application.

Installing a new version of a server application.


Upgrading Applications

When an OLE 1 server is upgraded to an OLE 2 object application, several issues arise. A primary issue is whether the OLE 2 application will replace the OLE 1 application or both versions will coexist. If only the newer version will be available to the user, it is best to convert objects from the older version of the application automatically to the new version format. Objects can be converted on a global basis, where all objects of a specific class are converted, or on a more selective basis, where only some objects are converted. Conversion can be either automatic, under programmatic control, or under the control of a user.

The ability to detect whether an object is from an OLE 1 server is helpful for implementing conversion functionality. The OLE 2 implementation of the IPersistStorage::Load method can check for a stream named “\1Ole10Native.” The “\1Ole10Native” stream contains a DWORD header whose value is the length of the native data that follows. The existence of this stream indicates that the data is coming from an OLE 1 server. Applications can check whether a storage object contains an object in an OLE 1 format by calling the ReadFmtUserTypeStg method and examining the contents of pcfFormat. This is where the OLE 1 class name would appear.

In the IPersistStorage::Save method, objects that are being permanently converted should be written back to storage in the new format and the “\1Ole10Native” stream should be deleted. The conversion bit in the storage should also be cleared once the conversion to the new format is complete.

To allow manual conversion of an old OLE 1 object to the new OLE 2 version, the OLE 2 object application must put the OLE 1 server’s ProgID (OLE 1 server class name) into the registry under the CLSID\{...}\Conversion\Readable\Main entry. This entry indicates that the OLE 2 application can read its OLE 1 data format; the ‘Clipboard format’ of the OLE 1 data is the ProgID (that is, the class name) of the OLE 1 object.

To get a CLSID for an OLE 1 server, the CLSIDFromProgId function or the CLSIDFromString function must be called. That is, an OLE 1 application cannot be assigned a CLSID from an OLE 2 application with uuidgen.exe, CoCreateGuid, or by using a GUID from a range assigned by Microsoft. Because all OLE 1 CLSIDs are expected to fall in a specific range, OLE 1 CLSIDs are assigned with the CLSIDFromProgId function.

Refer to the appendix called “Registering Object Applications” for detailed information on the required registry entries for upgraded applications.


Functions to Support Compatibility

The following functions enable applications to determine whether an object class is from OLE 1, and to support conversion between OLE 1 and OLE 2 storage formats.

OLE 1 Compatibility Functions	Description
CoIsOle1Class	Determines if a given CLSID represents an OLE 1 object.
OleConvertIStorageToOLESTRAM	Converts the specified storage object from OLE 2 structured storage to the OLE 1 storage model.
OleConvertIStorageToOLESTREAMEx	Converts the specified storage object from OLE 2 structured storage to the OLE 1 storage model.
OleConvertOLESTREAMToIStorage	Converts the specified object from the OLE 1 storage model to an OLE 2 structured storage object.
OleConvertOLESTREAMToIStorageEx	Converts the specified object from the OLE 1 storage model to an OLE 2 structured storage object.


16:32 Bit Interoperability

The 32-bit implementation of OLE 2 is compatible with OLE 1 applications in the manner described above. Interoperability is achieved by converting calls made on objects in one model into calls suitable in another model. For example, if a call is made by a 16-bit application to an object that is a 32-bit implementation, the OLE 16:32 interoperability (thunk) layer takes care of marshalling and converting parameters between the two models.


Thunk Layer Operation

The thunk layer replaces the 16-bit implementations of OLE 2 with a new set of binaries that allow the 16-bit implementations to call the updated 32-bit implementation of OLE 2. These new binaries, collectively known as the thunk layer, forward all OLE 2 method and function calls to the 32-bit implementation of OLE. The OLE thunk layer inserts itself between implementations of different models. Whenever an interface is passed between implementation types, the system provides a thunk proxy and stub.

For example, a call to the CreateFileMoniker function returns a pointer to a moniker. When a 16-bit implementation calls the CreateFileMoniker function, the system thunks the call to the 32-bit OLE 2 implementation and creates a file moniker using a 32-bit implementation. When the call returns through the OLE thunk layer, the moniker pointer is translated into a 16/32 proxy.

A 16/32 proxy sets up an object in the 16-bit address space that, when called, converts each parameter for the specific method into the appropriate values for calling the 32-bit implementation. It then performs a model switch from 16-bit to 32-bit. The call is made on the 32-bit implementation, and then another model switch is made from the 32-bit to 16-bit implementation. In the process of switching back, any output parameters are converted into their 16-bit counterparts.

The system keeps track of the model of each pointer. For example, if a 16-bit application calls a 32-bit application, it passes a 16-bit pointer to an object. The thunk layer will create a 32/16 proxy to let the 32-bit application call the 16-bit application’s object. In response, the 32-bit application calls back to the 16-bit application, passing the pointer it received. In this direction, the pointer being held by the 32-bit application holds is to a 32/16 proxy. The thunk layer also detects that the 32-bit pointer being passed in is a proxy, and passes the original pointer it started with to the 16-bit application. Thus, the 16-bit application sees the same pointer it passed in. This works when passing from 16 to 32 to 16, or from 32 to16 to 32. For more information about thunking, see the Win32 SDK.


Interoperability Using Standard Interfaces (OLE 2 Defined)

In its 32-bit implementation, OLE 2 is provided by the operating system and can translate OLE-defined interfaces and methods. Existing OLE 2 applications will continue to work as before. The following combinations of interoperability using the standard interfaces defined by OLE 2 are supported:

•	16 to 16 (in-process server)

•	16 to 16 (local server)

•	16 to 32 (local server)

•	32 to 32 (in-process server)

•	32 to 32 (local server)

•	32 to 16 (local server)

32- to16-bit (in-process server) interoperability using the standard interfaces is not supported.


Interoperability Using Custom Interfaces (either MIDL or Manually Written Marshalling)

Due to major architectural changes in the OLE communication layer, 16-bit applications that require remoting of custom interfaces are not supported at this time. However, 16-bit applications that use custom interfaces to an inprocess server should still function correctly. The following combinations of interoperability using custom interfaces are supported:

•	16 to 16 (inprocess server)

•	32 to 32 (inprocess server)

•	32 to 32 (local server using MIDL-generated stubs)

The following combinations of interoperability using custom interfaces are not supported:

•	16 to 16 (local server)

•	16 to 32 (all combinations)

•	32 to 16 (all combinations)

Programmers who have written applications that provide custom interfaces must rewrite the custom interface marshalling code to conform to the RPC-based communication layer. However, information about writing a 16-bit custom-marshalling library is not available at this time. For more information about RPC, see the RPC Programmer’s Guide and Reference.


ActiveX Control and Control Container Guidelines

The purpose of this appendix is to provide guidelines for implementing ActiveX controls and containers that will interoperate well with other controls and containers. This appendix defines the minimum set of interfaces, methods, and features that are required of ActiveX Controls and Containers to accomplish seamless and useful interoperability.


Overview of Control and Control Container Guidelines

An ActiveX Control is essentially a simple OLE object that supports the IUnknown interface. It will usually support a lot more interfaces in order to offer functionality, but all additional interfaces may be viewed as optional and as such, a control container should not rely on any additional interfaces being supported. By not specifying additional interfaces that a control must support, a control may efficiently target a particular area of functionality without having to support particular interfaces to qualify as a control. As always with OLE, whether in a control or a control container, it should never be assumed that an interface is available and standard return-checking conventions should always be followed. It is important for a control or control container to degrade gracefully and offer alternative functionality if an interface required is not available.

An ActiveX control container must be able to host a minimal ActiveX Control as specified in this appendix, it will also support a number of additional interfaces as specified in the Containers section of this appendix. There are a number of interfaces and methods that a container may optionally support, which are grouped into functional areas known as Component Categories. A container may support any combination of component categories, for example, a component category exists for Databinding and a container may or may not support the databinding functionality, depending on the market needs of the container. If a control needs databinding support from a container to function, then it will enter this requirement in the registry. This allows a control container to only offer for insertion those controls that it knows it can successfully host. It is important to note that Component Categories are specified as part of OLE and are not specific to ActiveX Controls, the controls architecture uses Component Categories to identify areas of functionality that an OLE component may support. Component categories are not cumulative or exclusive, so a control container can support one category without necessarily supporting another.

It is important for controls that require optional features, or features specific to a certain container to be clearly packaged and marketed with those requirements. Similarly containers that offer certain features or component categories must be marketed and packaged as offering those levels of support when hosting ActiveX controls. It is recommended that controls target and test with as many containers as possible and degrade gracefully to offer less or alternative functionality if interfaces or methods are not available. In a situation where a control cannot perform its designated job function without the support of a component category, then that category should be entered as a requirement in the registry in order to prevent the control being inserted in an inappropriate container.

These guidelines define those interfaces and methods that a control may expect a control container to support, although as always a control should check the return values when using QueryInterface or other methods to obtain pointers to these interfaces. A container should not expect a control to support anything more than the IUnknown interface, and these guidelines identify what interfaces a control may support and what the presence of a particular interface means.


Why are the ActiveX Control and Control Container Guidelines Important?

ActiveX Controls have become the primary architecture for developing programmable software components for use in a variety of different containers ranging from software development tools to end-user productivity tools. In order for a control to operate well in a variety of containers, the control must be able to assume some minimum level of functionality that it can rely on in all containers.

By following these guidelines, control and container developers make their controls and containers more reliable and interoperable, and ultimately, better and more usable components for building component-based solutions.

This appendix provides guidelines towards good interoperability. It is expected that new interfaces and component categories will develop over time, future versions of this appendix reflecting these changes will be made readily available through Microsoft. It is important to note that this appendix does not cover detailed semantics of the OLE interfaces; this is covered by the Win32 SDK documentation.


What to do When an Interface You Need is Not Available

This section states some fundamental rules that apply to all OLE programming. OLE programs should use QueryInterface to acquire interface pointers, and must check the return value. OLE applications cannot safely assume that QueryInterface will succeed, this requirement applies to all OLE applications. If the requested interface is not available (i.e., QueryInterface returns E_NOINTERFACE), the control or container must degrade gracefully, even if that means that it cannot perform its designated job function.


What's New in the Control and Control Container Guidelines?
What’s New in the Control and Control Container Guidelines?

This release of the guidelines embraces the concept of Component Categories which are a part of the OLE specification. In previous versions of this document component categories were loosely referred to as function groups and were used to identify areas of functionality that a container may optionally support, for this version there has been a definition of how component categories work for ActiveX Controls and some fundamental categories are identified. The use of component categories allows the relaxing of some of the previous rules that identified interfaces as being mandatory, and allows greater flexibility for controls to efficiently target certain areas of functionality without having to provide superfluous additional support in order to qualify as a control. This edition of the guidelines also discusses what the presence or absence of an interface means and what to do in that situation.

The remainder of this appendix is divided into four sections. The first discusses guidelines for implementing controls, the second discusses guidelines for implementing control containers, the third discusses component categories, and the fourth discusses general guidelines, relevant to both control and control container developers.


Controls

An ActiveX control is really just another term for OLE object or more specifically, COM object. In other words, a control, at the very least, is some COM object that supports the IUnknown interface and is also self-registering. Through IUnknown::QueryInterface a container can manage the lifetime of the control as well as dynamically discover the full extent of a control’s functionality based on the available interfaces. This allows a control to implement as little functionality as it needs to, instead of supporting a large number of interfaces that actually don’t do anything. In short, this minimal requirement for nothing more than IUnknown allows any control to be as lightweight as it can.

In short, other than IUnknown and self-registration, there are no other requirements for a control. There are however conventions that should be followed about what the support of an interface means in terms of functionality provided to the container by the control. This section then describes what it means for a control to actually support an interface, as well as methods, properties, and events that a control should provide as a baseline if it has occasion to support methods, properties, and events.


Self Registration for Controls

ActiveX controls must support self-registration by implementing the DllRegisterServer and DllUnregisterServer functions. ActiveX controls must register all of the standard registry entries for embeddable objects and automation servers.

ActiveX Controls must use the component categories API to register themselves as a control and register the component categories that they require a host to support and any categories that the control implements, see the Component Categories section of this appendix. In addition an ActiveX Control may wish to register the control keyword in order to allow older control containers such as VB4 to host them.

ActiveX Controls should also register the ToolBoxBitmap32 registry key, although this is not mandatory.

The Insertable component category should only be registered if the control is suitable for use as a compound document object. It is important to note that a compound document object must support certain interfaces beyond the minimum IUnknown required for an ActiveX Control. Although an ActiveX Control may qualify as a compound document object, the control’s documentation should clearly state what behavior to expect under these circumstances.


What Support for an Interface Means

Besides the IUnknown interface, an ActiveX Control—or COM Object for that matter—expresses whatever optional functionality it supports through additional interfaces. This is to say that no other interfaces are required above IUnknown. To that end, the following table lists the interfaces that an ActiveX Control might support, and what it means to support that interface. Further details about the methods of these interfaces are given in a later section.

Interface	Comments/What it Means to Support the Interface
IOleObject	If the control requires communication with its client site for anything other than events (see IConnectionPointContainer), then IOleObject is a necessity. When implementing this interface, the control must also support the semantics of the following methods: SetHostNames, Close, EnumVerbs, Update, IsUpToDate, GetUserClassID, GetUserType, GetMiscStatus, and the Advise, Unadvise, and EnumAdvise methods that work in conjunction with a container’s IAdviseSink implementation. A control implementing IOleObject must be able to handle IAdviseSink if the container provides one; a container may not, in which case a control ensures, of course, that it does not attempt to call a non-existent sink.
IOleInPlaceObject	Expresses the control’s ability to be in-place activated and possibly UI activated. This interface means that the control has a user interface of some kind that can be activated, and IOleInPlaceActiveObject is supported as well. Required methods are GetWindow, InPlaceActivate, UIDeactivate, SetObjectRects, and ReactivateAndUndo. Support for this interface requires support for IOleObject.
IOleInPlaceActiveObject	An in-place capable object that supports IOleInPlaceObject must also provide this interface as well, though the control itself doesn’t necessarily implement the interface directly.
IOleControl	Expresses the control’s ability and desire to deal with (a) mnemonics (GetControlInfo, OnMnemonic methods), (b)  ambient properties (OnAmbientPropertyChange), and/or (c) events that the control requires the container to handle (FreezeEvents). Note that mnemonics are different than accelerators that are handled through IOleInPlaceActiveObject:  mnemonics have associated UI and are active even when the control is not UI active. A control’s support for mnemonics means that the control also knows how to use the container’s IOleControlSite::OnControlInfoChanged method. Because this requires the control to know the container’s site, support for mnemonics also means support for IOleObject. In addition, knowledge of mnemonics requires in-place support and thus IOleInPlaceObject. If a control uses any container-ambient properties, then it must also implement this interface to receive change notifications, as following the semantics of changes is required. Because ambient properties are only available through the container site’s IDispatch, ambient property support means that the control supports IOleObject (to get the site) as well as being able to generate IDispatch::Invoke calls. The FreezeEvents method is necessary for controls that must know when a container is not going to handle an event—this is the only way for control to know this condition. If FreezeEvents is only necessary in isolation, such that other IOleControl methods are not implemented, then IOleControl can stand alone without IOleObject or IOleInPlaceObject.
IDataObject	Indicates that the control can supply at least (a) graphical renderings of the control (CF_METAFILEPICT is the minimum if the control has any visuals at all) and/or (b) property sets, if the control has any properties to provide. The methods GetData, QueryGetData, EnumFormatEtc, DAdvise, DUnadvise, and EnumDAdvise are required. Support for graphical formats other than CF_METAFILEPICT is optional.
IViewObject2	Indicates that the control has some interesting visuals when it is not in-place active. If implemented, a control must support the methods Draw, GetAdvise, SetAdvise, and GetExtent.
IDispatch	Indicates that the control has either (a) custom methods, or (b) custom properties that are both available via late-binding through IDispatch::Invoke. This also requires that the control provides type information through other IDispatch methods. A control may support multiple IDispatch implementations where only one is associated with IID_IDispatch—the others must have their own unique dispinterface identifiers. A control is encouraged to supply dual interfaces for custom method and property access, but this is optional if methods and properties exist.
IConnectionPointContainer	Indicates that a control supports at least one outgoing interface, such as events or property change notifications. All methods of this interface must be implemented if this interface is available at all, including EnumConnectionPoints which requires a separate object with IEnumConnectionPoints. Support for IConnectionPointContainer means that the object also supports one or more related objects with IConnectionPoint that are available through IConnectionPointContainer methods. Each connection point object itself must implement the full IConnectionPoint interface, including EnumConnections, which requires another enumerator object with the IEnumConnections interface.
IProvideClassInfo[2]	Indicates that the object can provide its own coclass type information directly through IProvideClassInfo::GetClassInfo. If the control supports the later variation IProvideClassInfo2, then it also indicates its ability to provide its primary source IID through IProvideClassInfo2::GetGUID. All methods of this interface must be implemented.
ISpecifyPropertyPages	Indicates that the control has property pages that it can display such that a container can coordinate this control’s property pages with other control’s pages when property pages are to be shown for a multi-control selection. All methods of this interface must be implemented when support exists.
IPerPropertyBrowsing	Indicates the control’s ability to (a) provide a display string for a property, (b) provide pre-defined strings and values for its properties and/or (c) map a property dispID to a specific property page. Support for this interface means that support for properties through IDispatch as above is provided. If (c) is supported, then it also means that the object’s property pages mapped through IPerPropertyBrowsing::MapPropertyToPage themselves implement IPropertyPage2 as opposed to the basic IPropertyPage interface.
IPersistStream	See Persistence Interfaces section.
IPersistStreamInit	See Persistence Interfaces section.
IPersistMemory	See Persistence Interfaces section.
IPersistStorage	See Persistence Interfaces section.
IPersistMoniker	See Persistence Interfaces section.
IPersistPropertyBag	See Persistence Interfaces section.
IOleCache[2]	Indicates support for container caching of control visuals. A control generally obtains caching support itself through the OLE function CreateDataCache. Only controls with meaningful static content should choose to do this (although it is not required). If a control supports caching at all, it should simply aggregate the data cache and expose both IOleCache and IOleCache2 interfaces from the data cache. A control implementing IOleObject must be able to handle IAdviseSink if the container provides one; a container may not, in which case a control ensures, of course, that it does not attempt to call a non-existent sink.
IExternalConnection	Indicates that the control supports external links to itself; that is, the control is not marked with OLEMISC_CANTLINKINSIDE and supports IOleObject::SetMoniker and IOleObject::GetMoniker. A container will never query for this interface itself nor call it directly as calls are generated from inside OLE’s remoting layer.
IRunnableObject	Indicates that the control differentiates being loaded from being running, as some in-process objects do.


Persistence Interfaces

Objects that have a persistent state of any kind must implement at least one IPersist* interface, and preferably multiple interfaces, in order to provide the container with the most flexible choice of how it wishes to save a control’s state.

If a control has any persistent state whatsoever, it must, as a minimum, implement either IPersistStream or IPersistStreamInit (the two are mutually exclusive and shouldn’t be implemented together for the most part). The latter is used when a control wishes to know when it is created new as opposed to reloaded from an existing persistent state (IPersistStream does not have the created new capability). The existence of either interface indicates that the control can save and load its persistent state into a stream, that is, an instance of IStream.

Beyond these two stream-based interfaces, the IPersist* interfaces listed in the following table can be optionally provided in order to support persistence to locations other than an expandable IStream.

A set of component categories is identified to cover the support for persistency interfaces see the Component Categories section of this appendix.

Interface	Usage
IPersistMemory	The object can save and load its state into a fixed-length sequential byte array (in memory).
IPersistStorage	The object can save and load its state into an IStorage instance. Controls that wish to be marked Insertable as other compound document objects (for insertion into non-control aware containers) must support this interface.
IPersistPropertyBag	The object can save and load its state as individual properties written to IPropertyBag which the container implements. This is used for Save As Text functionality in some containers.
IPersistMoniker	The object can save and load its state to a location named by a moniker. The control calls IMoniker::BindToStorage to retrieve the storage interface it requires, such as IStorage, IStream, ILockBytes, IDataObject, etc.
While support for IPersistPropertyBag is optional, it is strongly recommended as an optimization for containers with Save As Text features, such as Visual Basic.

With the exception of IPersistStream[Init]::GetSizeMax and IPersistMemory::GetSizeMax, all methods of each interface must be fully implemented.


Optional Methods in Control Interfaces

Implementing an interface doesn’t necessarily mean implementing all methods of that interface to do anything more than return E_NOTIMPL or S_OK as appropriate. The following table identifies the methods of the interfaces listed in the What Support for an Interface Means section that a control may implement in this manner. Check with the SDK OLE Reference documentation for full syntax and valid return values from these methods. Any method not listed here must be fully implemented if the interface is supported.

Method	Comments
IOleControl
GetControlInfo, OnMnemonic	Mandatory for controls with mnemonics.
OnAmbientPropertyChange	Mandatory for controls that use ambient properties.
FreezeEvents	See Event Freezing in the General Guidelines section.
IOleObject
SetMoniker	Mandatory if the control is not marked with OLEMISC_CANTLINKINSIDE
GetMoniker	Mandatory if the control is not marked with OLEMISC_CANTLINKINSIDE
InitFromData	Optional
GetClipboardData	Optional
SetExtent	Mandatory only for DVASPECT_CONTENT
GetExtent	Mandatory only for DVASPECT_CONTENT
SetColorScheme	Optional
DoVerb	See Note 1.
IOleInPlaceObject
ContextSensitiveHelp	Optional
ReactivateAndUndo	Optional
IOleInPlaceActiveObject
ContextSensitiveHelp	Optional
IViewObject2
Freeze	Optional
Unfreeze	Optional
GetColorSet	Optional
IPersistStream[Init], IPersistMemory
GetSizeMax	See Note 2.

1.	A control with property pages must support IOleObject::DoVerbs for the OLEIVERB_PROPERTIES and OLEIVERB_PRIMARY verbs. A control that can be active must support IOleObject::DoVerbs for the OLEIVERB_INPLACEACTIVATE verb. A control  that can be UI active must also support IOleObject::DoVerbs for the OLEIVERB_UIACTIVATE verb.

2.	If a control supports IPersistStream[Init] and can return an accurate value, then it should do so.


Class Factory Options

An ActiveX Control, by virtue of being a COM object, must have associated server code that supports control creation through IClassFactory as a minimum.

It is optional, not required, that this class object also supports IClassFactory2 for licensing management. Only those vendors that are concerned about licensing need to support COM’s licensing mechanism. In other words, because IClassFactory2 is the only way to achieve COM-level licensing, this interface is required on the class object for those controls that wish to be licensed.


Properties

Although most controls do have properties, controls are not required to expose any properties and thus the control does not require IDispatch. If the control does have properties, there are no requirements for which properties a control must expose.


Methods (via IDispatch and Other dispinterfaces)

Although most controls do expose and support several methods, controls are not required to expose or support any methods and thus the control does not require IDispatch. If the control does have any methods, there are no requirements for which methods a control must expose.


Events in Controls

Although most controls do expose and fire several events, controls are not required to expose or fire any events and thus the control does not require IConnectionPointContainer. If the control does have any events, there are no requirements for which events a control must expose.


Property Pages

Support for property pages and per-property browsing is strongly recommended, but not required. If a control does implement property pages, then those pages should conform to one of the standard sizes: 250x62 or 250x110 dialog units (DLUs).


Ambient Properties for Controls

If a control supports any ambient properties at all, it must at least respect the values of the following ambient properties under the conditions stated in the following table using the standard dispids.

Ambient Property	Dispid	Comment/Conditions for Use
LocaleID	-705	If Locale is significant to the control, e.g. for text output
UserMode	-709	If the control behaves differently in user (design) mode and run mode
UIDead	-710	If the control reacts to UI events, then it should honor this ambient property
ShowGrabHandles	-711	If the control support in-place resizing of itself
ShowHatching	-712	If the control support in-place activation and UI activation
DisplayAsDefault	-713	Only if the control is marked OLEMISC_ACTSLIKEBUTTON (which means that support for keyboard mnemonics is provided, thus IOleControl::GetControlInfo and IOleControl::OnMnemonic must be implemented).
As described previously, use of ambients requires both IOleControl (for OnAmbientPropertyChange as a minimum) as well as IOleObject (for SetClientSite and GetClientSite).

The OLEMISC_SETCLIENTSITEFIRST bit may not necessarily be supported by a container. In these circumstances, a control must resort to default values for the ambient properties that it requires.


Using the Container's Functionality
Using the Container’s Functionality

The previous sections have described some of the necessary caller-side support that an ActiveX Control must have in order to access certain features of its container. The following table describes a control’s usage of container-side interfaces and when such usage would occur.

Interface	Container Object	Usage
IOleClientSite	Site	Controls that implement IOleObject call IOleClientSite methods as part of the standard OLE embedding protocol, specifically the methods SaveObject, ShowObject, OnShowWindow (only if a separate-window activation state is supported), RequestNewObjectLayout, and GetContainer (if communication with other controls is desired). The GetMoniker method is only used when the control can be linked to externally, that is, the control is not marked with OLEMISC_CANTLINKINSIDE.
IOleInPlaceSite	Site	Controls that have an in-place activate and possibly a UI active state will call IOleInPlaceSite methods (generally all of them with the exception of ContextSensitiveHelp) as part of the standard OLE in-place activation protocol.
IAdviseSink	Site	Control calls OnDataChange if the control supports IDataObject, OnViewChange if the control supports IViewObject2, and OnClose, OnSave, and OnRename if the control supports IOleObject.
IOleControlSite	Site	If supported, control calls OnControlInfoChanged when mnemonics change, LockInPlaceActive and TransformCoords if events are fired (the latter method is only used if coordinates are passed as event arguments), OnFocus and TranslateAccelerator if the control has a UI active state, and GetExtendedControl if the control wants to look at extended-control (container-owned) properties.
IDispatch (ambient properties)	Site	Used to access ambient properties.
IPropertyNotifySink	Varies	A control must generate OnChanged and OnRequestEdit for any control properties that are marked as [bindable] and [request], respectively.
Other event sink interfaces	Varies	A control that has outgoing interfaces other than IPropertyNotifySink will be handed other interface pointers of the correct IID to the control’s IConnectionPoint::Advise implementations (which are usually found in sub-objects of the control). A control always knows how to call its own event interfaces since the control defines those interfaces.
IOleInPlaceFrame	Frame	Used when a control has an in-place UI active state that requires frame-level tools or menu items.
IOleInPlaceUIWindow	Document	Used only when a control has an in-place UI active state that requires document-level or pane-level UI tools. This is rare.


Containers

An ActiveX Control container is an OLE container that supports the following additional features:

1.	Embedded objects from in-process servers

2.	In Place activation

3.	OLEMISC_ACTIVATEWHENVISIBLE

4.	Event Handling

ActiveX Control Containers must provide support for all of these features.

The following sections describe the specific interfaces, methods, and other features that are required of ActiveX Control Containers. Required Interfaces, Optional Methods, Misc. Status Bits Support, Keyboard Handling, Storage Interfaces, Ambient Properties, Extended Properties, Events, Methods, Message Reflection, and Automatic Clipping. The last section describes how to gracefully degrade when a particular control interface is not supported.


Required Interfaces

The table below lists the ActiveX Control Container interfaces, and denotes which interfaces are optional, and which are mandatory and must be implemented by control containers.

Interface	Required?	Comments
IOleClientSite	Yes
IAdviseSink	No	Only when the container desires (a) data change notifications (controls with IDataObject), (b) view change notification (controls that are not active and have IViewObject[2]), and (c) other notifications from controls acting as standard embedded objects.
IOleInPlaceSite	Yes
IOleControlSite	Yes
IOleInPlaceFrame	Yes
IOleContainer	Yes	See Note 1.
IDispatch for ambient properties	Yes	See Note 2 and Ambient Properties for Controls section
Control Event Sets	Yes	See Note 2.
ISimpleFrameSite	No	ISimpleFrameSite and support for nested simple frames is optional.
IPropertyNotifySink	No	Only needed for containers that (a) have their own property editing UI which would require updating whenever a control changed a property itself or (b) want to control [requestedit] property changes and other such data-binding features.
IErrorInfo	Yes	Mandatory if container supports dual interfaces. See Note 2.
IClassFactory2	No	Support is strongly recommended.

1.	IOleContainer is implemented on the document or form object (or appropriate analog) that holds the container sites. Controls use IOleContainer to navigate to other controls in the same document or form.

2.	Support for dual interfaces is not mandatory, but is strongly recommended. Writing ActiveX Control Containers to take advantage of dual interfaces will afford better performance with controls that offer dual interface support.

ActiveX Control containers must support OLE Automation exceptions. If a control container supports dual interfaces, then it must capture automation exceptions through IErrorInfo.


Optional Methods

An OLE component can implement an interface without implementing all the semantics of every method in the interface, instead returning E_NOTIMPL or S_OK as appropriate. The following table describes those methods that an ActiveX Control container is not required to implement (i.e. the control container can return E_NOTIMPL).

The table below describes optional methods; note that the method must still exist, but can simply return E_NOTIMPL instead of implementing real semantics. Note that any method from a mandatory interface that is not listed below must be considered mandatory and may not return E_NOTIMPL.

Method	Comments
IOleClientSite
SaveObject	Necessary for persistence to be successfully supported.
GetMoniker	Necessary only if the container supports linking to controls within its own form or document.
IOleInPlaceSite
ContextSensitiveHelp	Optional
Scroll	May return S_FALSE with no action.
DiscardUndoState	Can return S_OK with no action.
DeactivateAndUndo	Deactivation is mandatory; Undo is optional.
IOleControlSite
GetExtendedControl	Necessary for containers that support extended controls.
ShowPropertyFrame	Necessary for containers that wish to include their own property pages to handle extended control properties in addition to those provided by a control.
TranslateAccelerator	May return S_FALSE with no action.
LockInPlaceActive	Optional
IDispatch (Ambient properties)
GetTypeInfoCount	Necessary for containers that support non-standard ambient properties.
GetTypeInfo	Necessary for containers that support non-standard ambient properties.
GetIDsOfNames	Necessary for containers that support non-standard ambient properties.
IDispatch (Event sink)
GetTypeInfoCount	The control knows its own type information, so it has no need to call this.
GetTypeInfo	The control knows its own type information, so it has no need to call this.
GetIDsOfNames	The control knows its own type information, so it has no need to call this.
IOleInPlaceFrame
ContextSensitiveHelp
GetBorder	Necessary for containers with toolbar UI (which is optional)
RequestBorderSpace	Necessary for containers with toolbar UI (which is optional)
SetBorderSpace	Necessary for containers with toolbar UI (which is optional)
InsertMenus	Necessary for containers with menu UI (which is optional)
SetMenu	Necessary for containers with menu UI (which is optional)
RemoveMenus	Necessary for containers with menu UI (which is optional)
SetStatusText	Necessary only for containers that have a status line
EnableModeless	Optional
TranslateAccelerator	Optional
IOleContainer
ParseDisplayName	Only if linking to controls or other embeddings in the container is supported, as this is necessary for moniker binding.
LockContainer	As for ParseDisplayName
EnumObjects	Returns all ActiveX Controls through an enumerator with IEnumUnknown, but not necessarily all objects (since there’s no guarantee that all objects are ActiveX Controls; some may be regular Windows controls).


Miscellaneous Status Bits Support

ActiveX Control Containers must recognize and support the following OLEMISC_ status bits:

Status Bit	Required?	Comments
ACTIVATEWHENVISIBLE	Yes
IGNOREACTIVATEWHENVISIBLE	No	Needed for inactive and windowless control support. See Note 1.
INSIDEOUT	No	Not generally used with ActiveX Controls but rather with compound document embeddings. Note this is contrary to some SDK documentation that says this bit must be set for the ACTIVATEWHENVISIBLE bit to be set.
INVISIBLEATRUNTIME	Yes	Designates a control that should be visible at design time, but invisible at run time.
ALWAYSRUN	Yes
ACTSLIKEBUTTON	No	Support is normally mandatory although it is not necessary for document style containers.
ACTSLIKELABEL	No	Support is normally mandatory although it is not necessary for document style containers.
NOUIACTIVATE	Yes
ALIGNABLE	No
SIMPLEFRAME	No	See Simple Frame Site Containment section.
SETCLIENTSITEFIRST	No	Support for this bit is recommended but not mandatory.
IMEMODE	No

1.	The IGNOREACTIVATEWHENVISIBLE bit is for containers hosting inactive and windowless controls. The IGNOREACTIVATEWHENVISIBLE bit is introduced as part of the ActiveX Controls 96 specification, see this documentation for more details.


Keyboard Handling in Controls

Keyboard handling support for the following functionality is strongly recommended, although it is recognized that it is not applicable to all containers.

•	Support for OLEMISC_ACTSLIKELABEL and OLEMISC_ACTSLIKEBUTTON status bits.

•	Implementing the DisplayAsDefault ambient property (if it exists, it can return FALSE).

•	Implementing tab handling, including tab order.

Some containers will use ActiveX Controls in traditional compound document scenarios. For example, a spreadsheet may allow a user to embed an ActiveX Control into a worksheet. In such scenarios, the container would do keyboard handling differently, because the keyboard interface should remain consistent with the user’s expectations of a spreadsheet. Documentation for such products should inform users of differences in control handling in these different scenarios. Other containers should endeavor to honor the above functionality correctly, including Mnemonic handling.


Storage Interfaces

Control containers must be able to support controls that implement IPersistStorage, IPersistStream, or IPersistStreamInit. Optionally, a container can support any other persistence interfaces such as IPersistMemory, IPersistPropertyBag, and IPersistMoniker for those controls that provide support.

Once an ActiveX Control Container has chosen and initialized a storage interface to use (IPersistStorage, IPersistStream, IPersistStreamInit, etc), that storage interface will remain the primary storage interface for the lifetime of the control, i.e. the control will remain in possession of the storage. This does not preclude the container from saving to other storage interfaces.

ActiveX Control Containers do not need to support a save as text mechanism, thus using IPersistPropertyBag and the associated container-side interface IPropertyBag are optional.


Ambient Properties

At a minimum, ActiveX Control containers must support the following ambient properties using the standard dispids.

Ambient Property	Dispid	Comments/Conditions
LocaleID	-705
UserMode	-709	For containers that have different user and run environments.
DisplayAsDefault	-713	For those containers where a default button is relevant.


Extended Properties, Events and Methods

ActiveX Control Containers are not required to support extended controls. However, if the control container does support extended properties, then it must support the following minimal set:

Visible

Parent

Default

Cancel

Currently, extended properties, events, and methods do not have standard dispids.


Message Reflection

It is strongly recommended that an ActiveX Control container supports message reflection. This will result in more efficient operation for subclassed controls. If message reflection is supported, the MessageReflect ambient property must be supported and have a value of TRUE. If a container does not implement message reflection, then the OLE CDK creates two windows for every sub-classed control, to provide message reflection on behalf on the control container.


Automatic Clipping

It is strongly recommended that an ActiveX Control container supports automatic clipping of its controls. This will result in more efficient operation for most controls. If automatic clipping is supported, the AutoClip ambient property must be supported and have a value of TRUE.

Automatic clipping is the ability of a container to ensure that a control’s drawn output goes only to the container’s current clipping region. In a container that supports automatic clipping, a control can paint without regard to its clipping region, because the container will automatically clip any painting that occurs outside the control’s area. If a container does not support automatic clipping, then CDK-generated controls will create an extra parent window if a non-null clipping region is passed.


Degrading Gracefully in the Absence of an Interface

Because a control may not support any interface other than IUnknown, a container has to degrade gracefully when it encounters the absence of any particular interface.

One might question the usefulness of a control with nothing more than IUnknown. But consider the advantages that a control receives from a container’s visual programming environment (such as VB) when the container recognizes the object as a control:

1.	A button for the object appears in a toolbox.

2.	One can create an object by dragging it from the toolbox onto a form.

3.	One can give the object a name that is recognized in the visual programming environment.

4.	The same name in (3) above can be used immediately in writing any other code for controls on the same form (or even a different form).

5.	The container can automatically provide code entry points for any events available from that object.

6.	The container provides its own property browsing UI for any available properties.

When an object isn’t recognized as a control, then it potentially loses all of these very powerful and beneficial integration features. For example, in Visual Basic 4.0 it is very difficult to really integrate some random object that is not a control in the complete sense, but may still have properties and events. Because VB 4’s idea of a control is very restrictive the object does not gain any of the integration features above. But even a control with IUnknown, where the mere lifetime of the control determines the existence of some resource, should be able to gain the integration capabilities described above.

As current tools require a large set of control interfaces to gain any advantage, controls are generally led to over-implementation, such that they contain more code than they really need. Controls that could be 7K might end up being 25K, which is a big performance problem in areas such as the Internet. This has also led to the perception that one can only implement a control with one tool like the CDK because of the complexity of implementing all the interfaces—and this has implications when a large DLL like OC30.DLL is required for such a control, increasing the working set. If not all interfaces are required, then this opens up many developers to writing very small and light controls with straight OLE or with other tools as well, minimizing the overhead for each control.

This is why this appendix recognizes a control as any object with a CLSID and an IUnknown interface. Even with nothing more than IUnknown, a container with a programming environment should be able to provide at least features #3 and #4 from the list above. If the object provides a ToolBoxBitmap32 registry entry, it gains #1 and #2. If the object supplies IConnectionPointContainer (and IProvideClassInfo generally) for some event set, it gains #5, and if it supports IDispatch for properties and methods, it gains #6, as well as better code integration in the container.

In short, an object should be able to implement as little as IDispatch and one event set exposed through IConnectionPointContainer to gain all of those visual features above.

With this in mind, the following table describes what a container might do in the absence of any possible interface. Note that only those interfaces are listed that the container will directly obtain through QueryInterface. Other interfaces, like IOleInPlaceActiveObject, are obtained through other means.

Interface	Meaning of Interface Absence
IViewObject2	The control has no visuals that it will draw itself, so has no definite extents to provide. In run-time, the container simply doesn’t attempt to draw anything when this interface is absent. In design time, the container must at least draw some kind of default rectangle with a name in it for such a control, so a user in a visual programming environment can select the object and check out its properties, methods, and events that exist. Handling the absence of IViewObject2 is critical for good visual programming support.
IOleObject	The control doesn’t need the site whatsoever, nor does it take part in any embedded object layout negotiation. Any information (like control extents) that a container might expect from this interface should be filled in with container-provided defaults.
IOleInPlaceObject	The control doesn’t go in-place active (like a label) and thus never attempts to activate in this manner. Its only activation may be its property pages.
IOleControl	Control has no mnemonics and no use of ambient properties, and doesn’t care if the container ignores events. In the absence of this interface, the container just doesn’t call its methods.
IDataObject	The control provides no property sets nor any visual renderings that could be cached, so the container would choose to cache some default presentation in the absence of this interface (support for CF_METAFILEPICT, specifically) and disable any property-set related functionality.
IDispatch	The control has no custom properties or methods. The container does not need to try to show any control properties in this case, and should disallow any custom method calls that the container doesn’t recognize as belonging to its own extended controls (that may support methods and properties). As extended controls generally delegate certain IDispatch calls to the control, an extended control should not expect the control to have IDispatch at all.
IConnectionPointContainer	The control has no events, so the container doesn’t have to think about handling any.
IProvideClassInfo[2]	The control either doesn’t have type information or events, or the container needs to go into the control’s type information through the control’s registry entries. The existence of this interface is an optimization.
ISpecifyPropertyPages	The control has no property pages, so if the container has any UI that would invoke them, the container should disable that UI.
IPerPropertyBrowsing	The control has no display name itself, no predetermined strings and values, and no property to page mapping. This interface is nearly always used for generating container user interface, so such UI elements would be disabled in the absence of this interface.
IPersist*	The control has no persistent state to speak of, so the container doesn’t have to worry about saving any control-specific data. The container will, of course, save its own information about the control in its own form or document, but the control itself has nothing to contribute to that information.
IOleCache[2]	The object doesn’t support caching. A container can still support caching by just creating a data cache itself using CreateDataCache.


Component Categories

OLE’s component categories allow a software component’s abilities and requirements to be identified by entries in the registry. In a scenario where a container may not wish to or not be able to support an area of functionality, such as databinding for example, the container will not wish to host controls that require databinding in order to perform their job function. Component Categories allow areas of functionality such as databinding to be identified, so that the control container can avoid those controls that state it to be a requirement. Component Categories are specified separately as part of OLE and are not specific to the ActiveX Control architecture, the specification for component categories includes a set of APIs for manipulation of the component category registry keys.


What are Component Categories and how do they work?

Component Categories identify those areas of functionality that a software component supports and requires, a registry entry is used for each category or identified area of functionality. Each component category is identified by a globally unique identifier (GUID), when a control is installed it registers itself as a control in the system registry using the component category ID for control, see the Self Registration for Controls section. Within the control’s self registration it will also register those component categories that it implements and those component categories that it requires a container to support in order to successfully host the control.

When a control container is offering controls to the user to insert, it only allows the user to select and instantiate those controls that will be able to function adequately  in that environment. For example, if the control container does not support databinding, then the container will not allow the user to select and instantiate those controls that have an entry in the registry signifying that they require the databinding component category. A common dialog for control insertion and APIs to handle the registry entries are available.

Component categories are not cumulative or exclusive, a control can require any mix of component categories to function. A control that has no required entries for component categories may be expected to be capable of functioning in any control container and not require any specific functionality of a control container to function.

The following component categories are identified here, where necessary more detailed specifications of the categories may be available.

•	ISimpleFrameSite control containment.

•	Simple Databinding through the IPropertyNotifySink interface.

•	Advanced Databinding (as supported by the additional databinding interfaces of VB4.0).

•	Visual Basic private interfaces - IVBFormat, IVBGetControl

•	Internet aware controls.

•	Windowless controls.

This is not a definitive list of categories; further categories are likely to be defined in the future as new requirements are identified. An up-to-date list of component categories is available from Microsoft on their world wide web site, this list reflects those component categories that have been identified by Microsoft and any others that about which vendors have informed Microsoft.

It is important to remember that controls should attempt to work in as many environments as possible. If it is possible, the control should degrade its functionality when placed in a container that does not support certain interfaces. The purpose of component categories is to prevent a situation where the control is placed in an environment that is unsuitable and the control can not achieve its desired task. Generally, a control should degrade gracefully when interfaces are not present, a control may choose to advise the user with a message box that some functionality is not available or clearly document the functionality required of a control container for optimal performance.

Note older controls and containers do not make use of Component Categories and instead rely on the control keyword being present against the control in the registry. In order to be recognized by older containers controls may wish to register the control keyword in the registry, control developers should check that the control can successfully be hosted in such containers before doing this. Containers that use component categories may successfully use them to host older controls as the components category DLL handles the mapping, a separate category exists for older controls CATID_ControlV1 so that a container may optionally exclude them if necessary.

As Component Categories are identified by GUIDs it is possible for containers that offer particular specific functionality to have their own category IDs, generated using a GUID generation tool. However this can possibly undermine the advantage of interoperability of controls and containers so it is preferred that wherever possible existing component categories be used. Vendors are encouraged to consult together when defining new component categories to ensure that they meet the common requirements of the marketplace, and follow the spirit of interoperability of ActiveX Controls.


Simple Frame Site Containment

A container control is an ActiveX Control that is capable of containing other controls. A group box that contains a collection of radio buttons is an example of a container control. Container controls should set the OLEMISC_SIMPLEFRAME status bit, and should call its container’s ISimpleFrameSite implementation. An ActiveX Control container that supports Container Controls must implement ISimpleFrameSite.

CATID - {157083E0-2368-11cf-87B9-00AA006C8166} CATID_SimpleFrameControl


Simple Data Binding

The ActiveX Controls Architecture defines a data-binding mechanism, whereby an ActiveX Control can specify that one or more of its properties are bindable. In most cases, a data-bound control should not absolutely require data binding, so that it could be inserted into a container that does not support data binding. Obviously, in such a situation, the functionality of the control may be reduced.

CATID - {157083E1-2368-11cf-87B9-00AA006C8166} CATID_PropertyNotifyControl


Advanced Data Binding

There is a set of advanced data binding interfaces that allow a more complex databinding scenario to be supported. This component category covers that area of functionality.

CATID - {157083E2-2368-11cf-87B9-00AA006C8166} CATID_VBDataBound


Visual Basic private interfaces

Two interfaces that are implemented by Visual Basic are identified here for component categories. It is not expected that controls should require these categories as it is possible for controls to offer alternative functionality when these are not available.

The IVBFormat interface allows controls to better integrate into the Visual Basic environment when formatting data.

CATID - {02496840-3AC4-11cf-87B9-00AA006C8166} CATID_VBFormat

The IVBGetControl interface allows a control to enumerate other controls on the VB form.

CATID - {02496841-3AC4-11cf-87B9-00AA006C8166} CATID_VBGetControl


Internet-Aware Objects

There are certain categories identified to cover the persistency interfaces, these have been identified as a result of defining how controls function across the internet. A container that does not support the full range of persistency interfaces should ensure that it does not host a control that requires a combination of interfaces that it does not support. Details of the features required for internet aware controls are available in the ActiveX SDK.

The following tables describe the meaning for various categories as both implemented and required categories.

Required Categories	Description
CATID_PersistsToMoniker, CATID_PersistsToStreamInit, CATID_PersisitsToStream, CATID_PersistsToStorage, CATID_PersistsToMemory, CATID_PersistsToFile, CATID_PersistsToPropertyBag	Each of these categories are mutually exclusive and are only used when an object supports only one persistence mechanism at all (hence the mutual exclusion). Containers that do not support the persistence mechanism described by one of these categories should prevent themselves from creating any objects of classes so marked.
CATID_RequiresDataPathHost	The object requires the ability to save data to one or more paths and requires container involvement, therefore requiring container support for IBindHost.
Implemented Categories	Description
CATID_PersistsToMoniker, CATID_PersistsToStreamInit, CATID_PersistsToStream, CATID_PersistsToStorage, CATID_PersistsToMemory, CATID_PersistsToFile, CATID_PersistsToPropertyBag	Object supports the corresponding IPersist* mechanism for the category.
The following table provides the exact CATIDs assigned to each category:

Category	CATID
CATID_RequiresDataPathHost	0de86a50-2baa-11cf-a229-00aa003d7352
CATID_PersistsToMoniker	0de86a51-2baa-11cf-a229-00aa003d7352
CATID_PersistsToStorage	0de86a52-2baa-11cf-a229-00aa003d7352
CATID_PersistsToStreamInit	0de86a53-2baa-11cf-a229-00aa003d7352
CATID_PersistsToStream	0de86a54-2baa-11cf-a229-00aa003d7352
CATID_PersistsToMemory	0de86a55-2baa-11cf-a229-00aa003d7352
CATID_PersistsToFile	0de86a56-2baa-11cf-a229-00aa003d7352
CATID_PersistsToPropertyBag	0de86a57-2baa-11cf-a229-00aa003d7352


Windowless Controls

The ActiveX Controls 96 specification includes a definition for windowless controls. Such controls do not operate in their own window and require a container to offer a shared window into which the control may draw, see the ActiveX SDK. Windowless controls are designed to be compatible with older control containers by creating their own window in that situation, windowless control containers should host windowed controls in the traditional way with no problem. It may however be useful for a container to distinguish those controls that can operate in a windowless mode, so an appropriate component category is defined.

CATID - {1D06B600-3AE3-11cf-87B9-00AA006C8166} CATID_WindowlessObject


General Guidelines

This section describes various features, hints and tips for ActiveX Control and ActiveX Control container developers to help ensure good interoperability between controls and control containers.


Overloading IPropertyNotifySink

Many ActiveX Control Containers implement a modeless property browsing window. If a control’s properties are altered through the control’s property pages, then the control’s properties can get out of sync with the container’s view of those properties (the control is always right, of course). To ensure that it always has the current values for a control’s properties, an ActiveX Control Container can overload the IPropertyNotifySink interface (data binding) and also use it to be notified that a control property has changed. This technique is optional, and is not required of ActiveX Control Containers or ActiveX Controls.

Note that a control should use IPropertyNotifySink::OnRequestEdit only for data binding; it is free to use OnChanged for either or both purposes.


Container-Specific Private Interfaces

Some containers provide container-specific private interfaces for additional functionality or improved performance. Controls that rely on those container-specific interfaces should, if possible, work without those container-specific interfaces present so that the control functions in different containers. For example, Visual Basic® implements private interfaces that provide string formatting functionality to controls. If a control makes use of VB’s private formatting interfaces, it should be able to run with default formatting support if these interfaces are not available. If the control can function without the private interfaces, it should take appropriate action (such as warn the user of reduced functionality) but continue to work. If this is not an option, then a component category should be registered as required to ensure that only containers supporting this functionality can host these controls.


Multi-Threaded Issues

Starting with Microsoft® Windows® 95 and Microsoft Windows NT® 3.51, OLE provides support for multi-threaded applications, allowing applications to make OLE calls from multiple threads. This multi-threaded support is called the apartment model, it is important that all OLE components using multiple threads follow this model. The apartment model requires that interface pointers are marshaled (using CoMarshallInterface, and CoUnmarshalInterface) when passed between threads. For more information about apartment model threading, refer to the Win32 SDK documentation, and the OLEAPT sample (in Win32® SDK).


Event Freezing

A container can notify a control that it is not ready to respond to events by calling IOleControl::FreezeEvents(TRUE). It can un-freeze the events by calling IOleControl::FreezeEvents(FALSE). When a container freezes events, it is freezing event processing, not event receiving; that is, a container can still receive events while events are frozen. If a container receives an event notification while its events are frozen, the container should ignore the event. No other action is appropriate.

A control should take note of a container’s call to IOleControl::FreezeEvents(TRUE) if it is important to the control that an event is not missed. While a container’s event processing is frozen, a control should implement one of the following techniques:

1.	Fire the events in the full knowledge that the container will take no action.

2.	Discard all events that the control would have fired.

3.	Queue up all pending events and fire them after the container has called IOleControl::FreezeEvents(FALSE).

4.	Queue up only relevant or important events and fire them after the container has called IOleControl::FreezeEvents(FALSE).

Each technique is acceptable and appropriate in different circumstances. The control developer is responsible for determining and implementing the appropriate technique for the control’s functionality.


Container Controls

As described above, container controls are ActiveX Controls that visually contain other controls. The ActiveX Controls Architecture specifies the ISimpleFrameSite interface to enable container controls. Containers may also support container controls without supporting ISimpleFrameSite, although the behavior cannot be guaranteed. For this reason, a component category exists for SimpleFrameSite controls where the full functionality of this interface is required.

In order to support container controls without implementing ISimpleFrameSite, an ActiveX Control Container must:

•	Activate all controls at all times.

•	Reparent the contained controls to the hWnd of the containing control.

•	Remain the parent of the container control.


WS_GROUP and WS_TABSTOP Flags in Controls

A control should not use the WS_GROUP and WS_TABSTOP flags internally; some containers rely on these flags to manage keyboard handling.


Multiple Controls in One DLL

A single .OCX DLL can container any number of ActiveX Controls, thus simplifying the distribution and use of a set of related controls.

If you ship multiple controls in a single DLL, be sure to include the vendor name in each control name in the package. Including the vendors’ names in each control name will enable users to easily identify controls within a package. For example, if you ship a DLL that implements three controls, Con1, Con2 and Con3, then the control names should be:

<Your company name> Con1 Control

<Your company name> Con2 Control

<Your company name> Con3 Control


The IOleContainer::EnumObjects Method

This method is used to enumerate over all the OLE objects contained in a document or form, returning an interface pointer for each OLE object. The container must return pointers to each OLE object that shares the same container.  Nested forms or nested controls must also be enumerated.

Some containers implement extender controls, which wrap non-ActiveX Controls, and then return pointers to these extender controls as a form is enumerated. This behavior enables ActiveX Controls and ActiveX Control containers to integrate well with non-ActiveX Controls, and is thus recommended, but not required.


Enhanced Metafiles

Not surprisingly, enhanced metafiles provide more functionality than standard metafiles; using enhanced metafiles generally simplifies rendering code. An enhanced metafile DC is used in exactly the same way as a standard metafile DC. Enhanced metafiles are not available in 16-bit OLE. OLE supports enhanced metafiles, and includes backwards compatibility with standard metafiles and 16-bit applications.

32-bit ActiveX Control containers should use enhanced metafiles instead of standard metafiles.


Licensing

In order to embed licensed controls successfully, ActiveX Control containers must use IClassFactory2 instead of IClassFactory. Several OLE creation and loading helper functions (i.e., OleLoad and CoCreateInstance) explicitly call IClassFactory and not IClassFactory2, and therefore cannot be used to create or load licensed ActiveX Controls. ActiveX Control Containers should explicitly create and load ActiveX Controls using IClassFactory2. In the future, Microsoft will update these standard APIs to use both IClassFactory and IClassFactory2, as appropriate.


Dual Interfaces

OLE Automation enables an object to expose a set of methods in two ways: via the IDispatch interface, and through direct OLE VTable binding. IDispatch is used by most tools available today, and offers support for late binding to properties and methods. VTable binding offers much higher performance because this method is called directly instead of through IDispatch::Invoke. IDispatch offers late bound support, where direct VTable binding offers a significant performance gain; both techniques are valuable and important in different scenarios. By labeling an interface as dual in the type library, an OLE Automation interface can be used either via IDispatch, or it can be bound to directly. Containers can thus choose the most appropriate technique. Support for dual interfaces is strongly recommended for both controls and containers.


IPropertyBag and IPersistPropertyBag

IPropertyBag and IPersistPropertyBag optimize save as text mechanisms, and therefore are recommended for ActiveX Control containers that implement a save as text mechanism. IPropertyBag is implemented by a container, and is roughly analogous to IStream. IPersistPropertyBag is implemented by controls, and is roughly analogous to IPersistStream.


Event Coordinate Translation

The 96 specification for controls requires that coordinates passed for events fired by the control change from being HIMETRIC to being Points based. This change brings the event passing of coordinates in line with properties and methods and thus coordinate translation is no longer the responsibility of the container. This raises certain compatibility issues where a control fires events using a coordinate base that it is not expecting, this should only be an issue where a 96 control container is hosting an older pre-96 control as follows:

•	When an older pre-96 container hosts a 96 control the control will present the event coordinates as points, this should not cause the container any problems as the container should recognize the parameter type.

•	When a 96 container hosts a pre-96 control the control will present the container with coordinates and expect the container to any translation necessary. However the 96 container will be expecting a control to conform to the 96 controls specification and present its coordinates as points. The control uses the TranslateCoordinates method on the IOleControlSite interface provided by the container in the same way as it does for properties and methods to achieve this.

As a result the user of a 96 container hosting pre-96 controls will need to be aware that further translation of coordinates may be necessary when events are fired.


Standard DISPIDS

A number of standard dispids have been defined for the 96 controls specification.

DISPID_MOUSEPOINTER

#define DISPID_MOUSEPOINTER             -521

Property of type integer.

The Mousepointer property identifies standard mouse icons:

Value	Description
0	(Default) Shape determined by the object.
1	Arrow
2	Cross (cross-hair pointer)
3	I Beam
4	Icon (small square within a square)
5	Size (four-pointed arrow pointing north, south, east, and west)
6	Size NE SW (double arrow pointing northeast and southwest)
7	Size N S (double arrow pointing north and south)
8	Size NW, SE
9	Size E W (double arrow pointing east and west)
10	Up Arrow
11	Hourglass (wait)
12	No Drop
13	Arrow and hourglass
14	Arrow and question mark
15	Size all
99	Custom icon specified by the MouseIcon property
DISPID_MOUSEICON

#define DISPID_MOUSEICON                    -522

Property of type Picture.

DISPID_PICTURE

#define DISPID_PICTURE                           -523

Property of type picture.

DISPID_VALID

#define DISPID_VALID                               -524   // Is data in control valid?

Property of type BOOL.

Used to determine if the control has valid data or not.

DISPID_ AMBIENT_PALETTE

#define DISPID_AMBIENT_PALETTE      -726   // Container's HPAL

Used to allow the control to get the container’s HPAL. If the container supplies an ambient palette then that is the only palette that may be realized into the foreground. Controls that wish to realize their own palettes must do so in the background. If their is no ambient palette provided by the container then the active control may realize its palette in the foreground. Palette handling is further discussed in Palette Behaviour for OLE Controls which is in the ActiveX SDK.


Databinding

A new databinding attribute has been added to allow properties distinguish between communicating changes only when focus leaves the control or during all property change notifications.

The new attribute known as ImmediateBind is to allow controls to differentiate two different types of bindable properties. One type of bindable property needs to notify every change to the database, for example with a checkbox control where every change needs to be sent through to the underlying database even though the control has not lost the focus. However controls such as a listbox only wish to have the change of a property notified to the database when the control loses focus, as the user may have changed the highlighted selection with the arrow keys before finding the desired setting, to have the change notification sent to the database every time that the user hit the arrow key would be give unacceptable performance. The new immediate bind property allows individual bindable properties on a form to have this behavior specified, when this bit is set all changes will be notified.

The new ImmediateBind bit maps through to the new VARFLAG_FIMMEDIATEBIND (0x80) and the FUNCFLAG_FIMMEDIATEBIND (0x80) bits in the VARFLAGS and FUNCFLAGS enumerations for the ITypeInfo interface allowing for the properties attributes to be inspected.


Converting Mapping Modes

In Windows, mapping modes define how numbers relating to object sizes are to be passed and interpreted. The 32-bit version of OLE uses only one mapping mode, MM_HIMETRIC. The other Win32 mapping modes include MM_HIENGLISH, MM_LOENGLISH, MM_LOMETRIC, TWIPS, and PIXEL Modes (MM_ISOTROPIC and MM_ANISOTROPIC being PIXEL modes). When working with the visual presentation of OLE data, it is important to be aware of the mapping mode that OLE uses and how this mapping mode affects an application.

The mapping modes communicate physical sizes. For example, if an application using MM_HIMETRIC is to display a line ten centimeters long, the number of units would be 10,000. However, the line drawn on the screen would be ten centimeters long, regardless of the size of the video display area. The printed output would also be a line ten centimeters long.

Note  For those applications that use a mapping mode other than MM_HIMETRIC, the sample user interface library provides some functions that can be used to convert objects to and from MM_HIMETRIC units.

Because people read display screens from a greater distance than they do printed copy, most applications written for Windows display text in a larger size than they print it, using what is commonly referred to as logical resolution. For example, a ten-point font is easy enough to read on the printed page, but generally appears too small on a screen for comfortable reading. To afford more comfortable viewing, applications typically expand the size of the displayed text to some logical size. Using this approach, a column of text that is physically six inches wide might be eight inches wide on the screen, yet still print as a six-inch column.

While this display-enlargement scheme works well from the user’s point of view, a problem can occur when pasting objects into container documents. It is possible to lose the correct size ratio between the pasted object and the text owned and displayed by the container. The result is that the container’s text is scaled up for readability but the pasted object might not be. Consequently, applications must preserve the relative size and position of text and objects, meaning that if text uses logical resolution, it should scale objects accordingly.

In the examples shown in the figure below, a chart object has been pasted from a source application that uses physical size into documents of two different containers that use logical resolution for display of the text. The container displaying the object on the left has scaled up the chart object to the logical size of the adjacent text to maintain the object/text size ratio. That is, it has been enlarged from its physical size by an amount that maintains its proportion to the text of the container document. In the document on the right, the application displays the chart object at its physical size, with no scaling to logical resolution for display. Both documents print with the correct object-to-text-size ratio.

In OLE, the units for specifying the size of drawn objects is MM_HIMETRIC, which means object sizes are in physical units. However, containers need not use the MM_HIMETRIC mapping mode to draw pasted objects to the display. Rather, they should should map objects to the screen in the same manner as text. That is, if the container application displays text to the screen using a mapping mode that enlarges it, objects should be mapped to the display in the same manner. Using the same mapping mode for both the text and objects is required to establish the correct object-to-text ratio as shown in the document on the left side of the preceding figure. Because most Windows applications use logical resolution for this type of display mapping, we suggest that OLE containers also use logical resolution and set up their mapping modes and coordinate transforms accordingly. This allows objects to be moved from one application to another without changing their displayed size.


OLE Serialized Property Set Format

Persistent property sets provide a way to store information within file system entities. It is recommended that to create and manage them, you use the IPropertySetStorage and IPropertyStorage interfaces as described in the section of the Structured Storage chapter entitled Persistent Property Sets.

Property sets are made up of a tagged section of values, with the section uniquely identified by a Format Identifier (FMTID). Every property consists of a property identifier and a type indicator that represents a value. Each value stored in a property set has a unique property identifier that distinguishes the property. The type indicator describes the representation of the data in the value.

When you use the IPropertySetStorage and IPropertyStorage interfaces, you do not have to deal directly with the OLE serialized property set format structure. However, for those who are interested, this Appendix describes this format.

All data elements within a property set are stored in Intel representation (that is, in little-endian byte order).

OLE defines a standard, serialized data format for property sets. When you are dealing directly with the serialized format, and not with the interfaces, property sets have the following characteristics:

•	Property sets allow for different applications to create their own independent property sets to serve the application’s needs.

•	Property sets can be stored in a single IStream instance or in an IStorage instance containing multiple streams. Indeed, in the abstract, property sets are simply another data type that can be stored in many different forms of an in-memory or on-disk storage. For recommended conventions on creating the string name for the storage object, see the section “Naming Property Sets” later in this appendix.

•	Property sets allow for a dictionary of displayable names to be included to further describe the contents. A set of conventions for choosing property names is recommended. For more information on this optional dictionary, see “Property ID 0” later in this appendix.

The property set stream is divided into three major parts:

•	Header

•	FORMATID/offset pair

•	Section containing the actual property set values

The overall length of the property set stream must be less than or equal to 256K. The following sections of this chapter describe the individual components that make up the property set data format, as shown in the previous figure.

Note  Previous versions of this document described extensions to the property set stream with more than one section allowed, but that has been revised now to provide for one section in the property stream. The one exception is the DocumentSummaryInformation property set, described in the section The DocumentSummaryInformation Property Set.


Property Set Header

At the beginning of the property set stream is a header. It consists of a byte-order indicator, a format version, the originating operating system version, the CLSID, and a reserved field.

The following pseudo-structure illustrates the header:

typedef struct tagPROPERTYSETHEADER

{

    // Header

    WORD   wByteOrder ;  // Always 0xFFFE

    WORD   wFormat ;     // Always 0

    DWORD   dwOSVer ;     // System version

    CLSID  clsID ;       // Application CLSID

    DWORD  reserved ;    // Should be 1

} PROPERTYSETHEADER;


Byte-Order Indicator

The byte-order indicator is a WORD and should always hold the value 0xFFFE. This is the same as the Unicode byte-order indicator. This value is always written in Intel byte order and, thus, appears in the file or stream as 0xFE, 0xFF.


Format Version

The Format Version is a WORD used to indicate the format version of this stream. It should always be zero. The format-version indicator should be checked when reading the property set. If it is not zero, then the stream was written to a different specification and cannot be read by code developed according to the OLE 2 specification.


Originating OS Version

This DWORD should hold the kind of operating system in the high-order word and the version number of the operating system in the low-order word. Possible values for the operating system are:

Operating System	Value
32-Bit Windows (Win32)	0x0002
Macintosh	0x0001
16-Bit Windows (Win16)	0x0000
For Windows, the operating system version is the low-order word returned by the GetVersion function. On Windows, the following code would correctly set the version of the originating operating system:

#ifdef WIN32

dwOSVer = (DWORD)MAKELONG( LOWORD(GetVersion()), 2 ) ;

#else

dwOSVer = (DWORD)MAKELONG( LOWORD(GetVersion()), 0 ) ;

#endif


CLSID

The CLSID is that of a class that can display and/or provide programmatic access to the property values. If there is no such class, it is recommended that you set this value the same as the Format identifier (see below). Alternately, you can set this value to all zeroes; however, using the Format identifier allows more flexibility in the future.


Reserved

This DWORD is reserved for future use. Writers of property sets should set this value to 1; readers of property sets should ensure that this value is at least 1. An exception to this guideline is that, for the DocumentSummaryInformation property set, this value may be 2.


Format Identifier/Offset Pair

The second part of the property set stream contains one Format Identifier (FMTID)/Offset Pair. The FMTID is the name of the property set; it uniquely identifies how to interpret the contents of the following section. The Offset is the distance of bytes from the start of the whole stream to where the section begins.

The following structure is helpful in dealing with Format Identifier/Offset Pairs:

typedef struct tagFORMATIDOFFSET

{

    FMTID  fmtid ;     // Name of the section

    DWORD  dwOffset ;  // Offset for the section

} FORMATIDOFFSET;


Format Identifiers

Property set values are stored in a section that is tagged with a unique format identifier. For example, the FMTID for the OLE Summary Information property set is:

F29F85E0-4FF9-1068-AB91-08002B27B3D9

To define a FMTID for the Summary Information property set, you would use the DEFINE_GUID macro in an include file for the code that manipulates the property set:

DEFINE_GUID(FMTID_SummaryInformation, 0xF29F85E0, 0x4FF9, 0x1068,

0xAB, 0x91, 0x08, 0x00, 0x2B, 0x27, 0xB3, 0xD9);

Anywhere in your code you need to use the FMTID for the Summary Information property set, you can access it through the FMTID_SummaryInformation variable.

When storing property sets in IStorage instances, you need to convert the FMTID to a string name for the storage object.


Allocating Format Identifiers

FMTIDs are created and represented in the same way as OLE CLSIDs and interface identifiers. To create a unique FMTID, use the UUIDGEN.EXE program included in the Win32 SDK.


Section

This is the third part of the property set stream, as shown in Figure C.2. A section contains:

•	Byte count for the section (which is inclusive of the byte count itself)

•	Array of 32-bit Property ID/Offset pairs

•	Array of property Type Indicators/Value pairs

Offsets are the distance from the start of the section to the start of the property (type, value) pair. This allows a section to be copied as an array of bytes without any translation of internal structure.

The following pseudo-structures illustrate the format of a section:

typedef struct tagPROPERTYSECTIONHEADER

{

    DWORD  cbSection ;    // Size of Section

    DWORD  cProperties ;  // Count of Properties in section

} PROPERTYSECTIONHEADER;

typedef struct tagPROPERTYIDOFFSET

{

    DWORD  propid;    // Name of property

    DWORD  dwOffset;  // Offset from start of section to that property

} PROPERTYIDOFFSET;

typedef struct tag SERIALIZEDPROPERTYVALUE

{

    DWORD  dwType;   // Property Type

    BYTE   rgb[];    // Property Value

} SERIALIZEDPROPERTYVALUE ;


Size of Section

This DWORD indicates the size (in bytes) of the section. Because the section size is the first four bytes, you can copy sections as an array of bytes. The section size should always be a multiple of four.

For example, an empty section (one with zero properties in it) would have a byte count of eight (the DWORD byte count and the DWORD count of properties). The section itself would contain the eight bytes:

08 00 00 00 00 00 00 00


Count of Properties

This DWORD gives a count of the property values in the section. A property set may contain any number of property values. Readers must be able to handle the case where there are zero properties.


Property ID/Offset Pairs
Property Identifiers/Offset Pairs

Following the Count of Properties is an array of Property Identifiers/Offset Pairs. Property identifiers are 32-bit values that uniquely identify a property within a section. The Offsets indicate the distance from the start of the section to the start of the property Type/Value Pair. Since the offsets are relative to the section, sections can be copied as an array of bytes.

Property identifiers are not sorted in any particular order. Properties can be omitted from the stored property set; readers must not rely on a specific order or range of property identifiers.


Type Indicators

After the table of Property Identifiers/Offset Pairs comes the actual properties. Each property is stored as a DWORD type, followed by the data value.

Type indicators and their associated values are described in the PROPVARIANT structure reference page.

All Type/Value pairs must begin on a 32-bit boundary. Thus, values may be followed with null bytes to align the subsequent pair on a 32-bit boundary. Given a count of bytes, the following code will calculate how many bytes are needed to align on a 32-bit boundary:

cbAdd = (((cbCurrent + 3) >> 2) << 2) - cbCurrent ;

Within a vector of values, each repetition of a simple scalar value smaller than 32 bits must align with its natural alignment rather than with a 32-bit alignment. In practice, this is only significant for types VT_UI1, VTUI2, VT_I2, and VT_BOOL (which have one- or two-byte natural alignment). All other types have four-byte natural alignment. Some types (VT_R8, etc.) actually have 8-byte natural alignment, but are stored as if they have 4-byte alignment. Therefore, a property value with type indicator VT_I2 | VT_VECTOR would be:

•	A DWORD element count, followed by

•	A sequence of packed two-byte integers with no padding between them.

Note that any 32-bit counts or property types that are stored as a part of a vector property element must also be 32-bit aligned.

A property value of type identifier VT_LPSTR | VT_VECTOR would be:

•	A DWORD element count (DWORD cElems), followed by

•	A sequence of strings (char rgch[]), each of which is preceded by a length count DWORD and may be followed by null padding to round to a 32-bit boundary.


Reserved Property IDs
Reserved Property Identifiers

As a designer of property sets you can use any Property identifier for your properties except 0, 1, and all values greater than or equal to 0x80000000. These Property identifier values are reserved for use by applications as follows.


Property ID 0

To enable users of property sets to attach meaning to properties beyond those provided by the type indicator, property ID 0 is reserved for an optional dictionary of displayable names for the property set.

The dictionary contains a count of entries in the list, followed by a list of dictionary entries.

typedef struct tagDICTIONARY

{

    DWORD  cEntries ;               // Count of entries in the list

    ENTRY  rgEntry[ cEntries ] ;    // Property ID/String pair

} DICTIONARY ;

Each dictionary entry in the list is a Property Identifier/String pair. This can be illustrated using the following pseudo-structure definition for a dictionary entry (it’s a pseudo-structure because the sz[] member is variable in size):

typedef struct tagENTRY

{

    DWORD  propid ; // Property ID

    DWORD  cch ;       // Count of characters in the string

    char  sz[cch];     // Zero-terminated string

} ENTRY ;

Note the following about property set dictionaries:

•	Property ID 0 does not have a type indicator. The DWORD that indicates the count of entries sits in the type indicator position.

•	The count of characters in the string (cch) includes the zero character that terminates the string. When the codepage of the property set is not Unicode, this field is actually a byte count.  This count may not exceed 256.

•	The dictionary is entirely optional. Not all the names of properties in the set need appear in the dictionary. Conversely, not all names in the dictionary need to correspond to properties in the set. The dictionary should omit entries for properties assumed to be universally known by clients that manipulate the property set. Typically, names for the base property sets for widely accepted standards are omitted, but special purpose property sets may include dictionaries for use by browsers.

•	Property names in the dictionary are stored in the code page indicated by Property ID 1 (see below). For ANSI code pages, each dictionary entry is byte-aligned. Thus, there is no padding between property names with Property ID 0. This is the only case where DWORD values (the property ID and property name length DWORDs) are not required to be aligned on 32-bit boundaries. For Unicode pages, each dictionary entry is 32-bit aligned.

•	Property names that begin with the binary Unicode characters 0x0001 through 0x001F are reserved for future use.

•	The property name associated with property ID 0 represents the name of the entire property set.


Example Dictionary
Sample Dictionary

The stock market data transfer example (see “Transferring Data Contained in Property Sets,” in the Storage chapter of this Guide) might include a displayable name of “Stock Quote” for the entire set, and “Ticker Symbol” for PID_SYMBOL. If a property set contained just a symbol and the dictionary, the property set section would have a byte stream that looked like the following:

Offset     Bytes

; Start of section

0000    5C 01 00 00    ; DWORD size of section

0004    04 00 00 00    ; DWORD number of properties in section

; Start of PropID/Offset pairs

0008    01 00 00 00    ; DWORD Property ID (1 == code page)

000C    28 00 00 00    ; DWORD offset to property ID

0010    00 00 00 80    ; DWORD Property ID (0x80000000 == locale

          	                                        ID)

0014    30 00 00 00    ; DWORD offset to property ID

0018    00 00 00 00    ; DWORD Property ID (0 == dictionary)

001C    38 00 00 00    ; DWORD offset to property ID

0020    07 00 00 00    ; DWORD Property ID (3 == PID_SYMBOL)

0024    5C 01 00 00    ; DWORD offset to property ID

; Start of Property 1 (code page)

0028    01 00 00 00    ; DWORD type indicator (VT_12)

002C    B0 04          ; USHORT codepage (0x04b0 == 1200 ==

          	                                      unicode)

002E    00 00          ; Pad to 32-bit boundary

; Start of Property 0x80000000 (Local ID)

0030    13 00 00 00    ; DWORD type indicator (VT_U14)

0034    09 04 00 00    ; ULONG locale ID (0x0409 == American

          	                                     English)

; Start of Property 0 (the dictionary)

0038    08 00 00 00    ; DWORD number of entries in dictionary

          	                  (Note:  No type indicator)

003C    00 00 00 00    ; DWORD propid == 0 (the dictionary)

0040    0C 00 00 00    ; DWORD cch == wcslen(L”Stock Quote”) +

          	                    sizeof(L’\0’) == 12

0044    L”Stock Quote” ; wchar_t wsz(12)

005C    05 00 00 00    ; DWORD propid == 5 (PID_HIGH)

0060    0B 00 00 00    ; DWORD cch == wcslen(L”High Price”) +

          	                    sizeof(L’\0’) == 11

0064    L”High Price\0”; wchar_t wsz(11)

007A    00 00          ; padding for 32-bit alignment (necessary

          	                 because the codepage is unicode)

007C    07 00 00 00    ; DWORD propid == 7 (PID_SYMBOL)

0080    0E 00 00 00    ; DWORD cch - wcslen(L”Ticker Symbol\0”)

          	                 == 14

0084    L”Ticker Symbol\0” ; wchar_t wsz(14)

//The dictionary would continue, but may not contain entries

   //for every possible property, and may contain entries for

   //properties that are not present. Also, entries need not be in

   //order.


Property ID One
Property ID 1

Property ID 1 is reserved as an indicator of which code page (Windows) or Script (Macintosh) to use when interpreting the strings in the property set. All string values in the property set must be stored with the same code page. The originating operating system value in the property set header (PROPERTYSETHEADER::dwOSVer) determines whether the code page indicator corresponds to a Windows code page or Macintosh script.

When an application that is not the author of a property set changes a property of type string in the set, it should examine the code page indicator and take one of the following actions:

•	Write the string in the format specified by the code page indicator.

•	Replace and rewrite to change the code page.

If an application cannot understand this indicator, it should not modify the property. All creators of property sets must write a code page indicator; however, if the code page indicator is not present, the prevailing code page on the reader’s machine must be assumed.

Note  If the IPropertySetStorage interface is used to create a property set, the code page indicator is automatically written.

Possible values for the code page are given in the Win32 API (see the GetACP function) and Inside Macintosh Volume VI, §14-111. For example, the code page US ANSI is represented by 0x04E4 (1252 in decimal) while the code page for Unicode is 0x04B0 (1200 in decimal).

It is recommended that the Unicode code page be used whenever possible, and use VT_LPWSTR instead of VT_LPSTR to avoid multibyte <-> Unicode conversions during storage and retrieval. Using the same code page for all property sets is the only way to achieve interoperable property sets on a worldwide basis. In either the Unicode or non-Unicode code page, note that the count at the start of a VT_LPSTR or VT_BSTR is a byte count and not a character count. This byte count includes the one or two zero bytes at the end of the string (the string’s NULL terminator).

Property ID 1 is a VT_12 type and thus starts with a DWORD containing the value VT_12 followed by a USHORT indicating the code page.


Property ID 0x80000000

Property ID 0x80000000 (Locale Indicator) is reserved as an indication of the locale for which the property set is written. The default locale for a property set is the system’s default locale (LOCALE_SYSTEM_DEFAULT). See the Win32 SDK for more information on LOCALE_SYSTEM_DEFAULT. The default is used in the event that the locale indicator does not exist in the property set.

Applications can choose to support the locale or just get the default behavior. It is recommended that applications allow users to specify a working locale. Such applications should write the user-specified locale identifier to the property. Applications that use the user’s default locale (LOCALE_USER_DEFAULT) should write the user’s default locale identifier to the property. See the Win32 SDK for more information on LOCALE_USER_DEFAULT.

Note  If the IPropertySetStorage interface is used to create a property set, the user’s default locale is automatically written as the Locale Indicator.

Applications should also handle the case of a foreign object, which is one where the locale is not the application’s locale, the user’s locale, or the system’s locale.

The locale indicator property is of type VT_U14, and therefore consists of a DWORD containing VT_U14, followed by a DWORD containing the Locale Identifier (LCID), as defined in the Win32 SDK.


Other Reserved Property IDs
Other Reserved Property Identifiers

Property identifiers with the high bit set (that is, negative values) are reserved for future use by Microsoft.


Storing Property Sets

Applications can expose some of the state of their documents so that other applications can locate and read that information. Some examples are a property set describing the author, title, and keywords of a document created with a word processor, or the list of fonts used in a document. This facility is not restricted to documents; it can also be used on embedded objects. Generally, access to property sets should be through the IPropertySetStorage and IPropertyStorage interfaces, but this section describes the previously recommended way.

Note  If you are storing a property set that is internal to your application, you might not want to follow the guidelines described below. If you want to expose your property set to other applications, you need to follow these guidelines.

To store a property set in a compound file:

1.	Create an IStorage or IStream instance in the same level of the storage structure as its data streams. Prepend the name of your IStorage or IStream instance with “\005.” Stream and storage names that begin with 0x05 are reserved for common property sets that can be shared among applications. Also, streams beginning with that value are limited to 256K. The names can be selected from either published names and formats, or by assigning the property set a FMTID and deriving the name from the FMTID according to the conventions described in the section “Naming Property Sets”.

2.	A property set may be stored in a single IStream instance or in an IStorage instance containing multiple streams and storages. In the case of an IStorage instance, the contained stream named “Contents” is the primary stream containing property values, where some values may be names of other streams or storage instances within the storage for this property set.

3.	Specify the CLSID of the object class that can display and/or provide programmatic access to the property values. If there is no such class, the CLSID should be set to the property set’s format identifier. For a property set that uses an IStorage instance, either set the CLSID of the IStorage instance to be the same as that stored in the Contents stream or to CLSID_NULL (the value in a newly created IStorage instance).

4.	You have the option of specifying displayable names that form the contents of the dictionary.

Some applications can read only implementations of property sets stored as IStream instances. Applications should be written to expect that a property set may be stored in either an IStorage or IStream instance, unless the property set definition indicates otherwise. For example, the Summary Information property set’s definition says that it can only be stored in a named IStream instance. In cases where you are searching for a property set and don’t know whether it is a storage or stream, look for an IStream instance with your property set name first. If that fails, look for an IStorage instance.

To better understand storing property sets in an IStorage implementation, suppose there is a class of applications that edit information about animals. First, a CLSID (CLSID_AnimalApp) is defined for this set of applications, so they can indicate that they understand property sets containing animal information (FMTID_AnimalInfo), and others containing medical information (FMTID_MedicalInfo).

IStorage (File): "C:\OLE\REVO.DOC"

  IStorage: "\005AnimalInfo", CLSID = CLSID_AnimalApp

    IStream: "Contents"

      WORD wByteOrder, WORD wFmtVersion, DWORD dwOSVer,

      CLSID CLSID_AnimalApp, DWORD cSections...

      ...

      FMTID = FMTID_AnimalInfo

      Property: Type = PID_ANIMALTYPE, Type = VT_LPWSTR, Value = L"Dog"

      Property: Type = PID_ANIMALNAME, Type = VT_LPWSTR, Value = L"Revo"

      Property: Type = PID_MEDICALHISTORY, Type = VT_STREAMED_OBJECT,

              Value = "MedicalInfo"

      ...

    IStream: "MedicalInfo"

      WORD wByteOrder, WORD wFmtVersion, DWORD dwOSVer,

      CLSID CLSID_AnimalApp, DWORD cSections...

      ...

      FMTID = CLSID_MedicalInfo

      Property: Type = PID_VETNAME, Type = VT_LPWSTR, Value = L"Dr. Woof"

      Property: Type = PID_LASTEXAM, Type = VT_DATE, Value = ...

Note that the class identifiers of the IStorage interface and both property sets is CLSID_AnimalApp. This identifies any application that can display and/or provide programmatic access to these property sets. Any application can read the information within the property sets (the point behind property sets), but only applications identified with the class identifier of CLSID_AnimalApp can understand the meaning of the data in the property sets.


The DocumentSummaryInformation Property Set

The Microsoft Office Summary Information properties are stored in a separate stream from the standard Summary Information properties. The standard Summary Information property set is described in the section entitled “The Summary Information Property Set” under “Using Property Sets”. The name of the stream that contains the Document Summary Information is:

"\005DocumentSummaryInformation"

The FMTID for the Microsoft Office Summary Information property set is:

    D5CDD502-2E9C-101B-9397-08002B2CF9AE

Use the DEFINE_GUID macro to define the FMTID for the property set:

DEFINE_GUID(FMTID_DocumentSummaryInformation, 0xD5CDD502L, 0x2E9C,

0x101B, 0x93, 0x97, 0x08, 0x00, 0x2B, 0x2C, 0xF9, 0xAE);

This stream also has a separate section for the custom-defined properties. The format id for the section is

DEFINE_GUID(FMTID_UserDefinedProperties, 0xD5CDD505L, 0x2E9C, 0x101B,

0x93, 0x97, 0x08, 0x00, 0x2B, 0x2C, 0xF9, 0xAE);

The following table shows the added properties to the “DocumentSummaryInformation” stream for Office 95 applications.

Property Name	Property ID String	Property ID	VT Type
Category	PID_CATEGORY	0x00000002	VT_LPSTR
PresentationTarget	PID_PRESFORMAT	0x00000003	VT_LPSTR
Bytes	PID_BYTECOUNT	0x00000004	VT_I4
Lines	PID_LINECOUNT	0x00000005	VT_I4
Paragraphs	PID_PARCOUNT	0x00000006	VT_I4
Slides	PID_SLIDECOUNT	0x00000007	VT_I4
Notes	PID_NOTECOUNT	0x00000008	VT_I4
HiddenSlides	PID_HIDDENCOUNT	0x00000009	VT_I4
MMClips	PID_MMCLIPCOUNT	0x0000000A	VT_I4
ScaleCrop	PID_SCALE	0x0000000B	VT_BOOL
HeadingPairs	PID_HEADINGPAIR	0x0000000C	VT_VARIANT | VT_VECTOR
TitlesofParts	PID_DOCPARTS	0x0000000D	VT_LPSTR | VT_VECTOR
Manager	PID_MANAGER	0x0000000E	VT_LPSTR
Company	PID_COMPANY	0x0000000F	VT_LPSTR
LinksUpTo Date	PID_LINKSDIRTY	0x00000010	VT_BOOL
These properties have the following uses:

Category

A text string typed by the user indicating what category the file belongs to (memo, proposal etc.). It is useful for finding files of same type.

PresentationTarget

Target format for presentation (35mm, printer, video etc.), from PowerPoint.

Bytes

Number of bytes, from AFX.

Lines

Number of lines, from AFX.

Paragraphs

Number of paragraphs, from AFX.

Slides

Number of slides, from PowerPoint

Notes

Number of pages that contain notes, from PowerPoint

HiddenSlides

Number of slides that are hidden, from PowerPoint

MMClips

Number of sound or video clips, from PowerPoint

ScaleCrop

Set to True (-1) when scaling of the thumbnail is desired. If not set, cropping is desired. FindFile 2.0 needs this.

HeadingPairs

Internally used property indicating the grouping of different document parts and the number of items in each group.  The titles of the document parts are stored in the PID_DOCPARTS property. The HeadingPairs property is stored as a vector of variants, in repeating pairs of VT_LPSTR and VT_I4 values.  The VT_LPSTR value represents a heading name, and the VT_I4 value indicates the count of document parts under that heading. This property is used for providing the indentation for different groups on the 'sections' page.

TitlesofParts

Names of document parts, from AFX. For Excel this is sheet names, for PowerPoint this is slide titles, for a binder this is document names, for Word it is the names of the documents in the master document.

Manager

Manager of the project, from Project.

Company

Company name, from Project.

LinksUpToDate

Bool to indicate whether the custom links are dirty, for all applications.

Note  As described in “12.3. Serialized Format for Property Sets” of the OLE 2.0 Design Specification, vector elements in the HeadingPairs and TitlesofParts properties should be aligned on 32 bit boundaries. However, in the DocumentSummaryInformation property set, when the code page of the property set is not Unicode, these elements must be packed.


A

accessor function

A function that sets or retrieves the value of a property. Most properties have a pair of accessor functions. Properties that are read-only may have only one accessor function.

ActiveX

Microsoft’s brand name for the technologies that enable interoperability using the Component Object Model (COM). ActiveX technology includes, but is not limited to, OLE.

ActiveX client

Any program or piece of code that accesses the functionality and the content of an ActiveX or OLE object.

ActiveX component

Physical file that contains classes, which are definitions of objects. For example, a .dll, .exe or .ocx file.

ActiveX control

A user interface element created using ActiveX technology.

ActiveX object

Objects an application or programming tool exposes to ActiveX clients.

Application object

The top-level object in an application’s object hierarchy. The Application object identifies the application to the system, and typically becomes active when the application starts. Specified by the appobj attribute in the type library.

Automation

COM-based technology that enables interoperability among ActiveX components, including OLE components. Formerly referred to as OLE Automation.

Automation controller

An application, programming tool, or scripting language that accesses Automation objects. Visual Basic is an OLE Automation controller.

Automation object

An instance of a class defined within an application that is exposed for access by other applications or programming tools by Automation interfaces.

Automation server

An application, type library, or other source that makes Automation objects available for programming by other applications, programming tools, or scripting languages.


C

class identifier (CLSID)

A  universally unique ID (UUID) for an application class that identifies an object. An object registers its class ID (CLSID) in the system registration database so that it can be loaded and programmed by other applications.

class factory

An object that implements the IClassFactory interface, which allows it to create other objects of a specific class.

coclass

Component object model class. A top-level object in the object hierarchy.

collection object

A grouping of exposed objects. A collection object that can address multiple occurrences of an object as a unit (for example, to draw a set of points).

Component Object Model (COM)

The programming model and binary standard on which OLE is based. COM defines how objects and their clients interact within processes or across process boundaries.

compound document

A document that contains data of different formats, such as sound clips, spreadsheets, text, and bitmaps, created by different applications. Compound documents are stored by container applications.

container application

An OLE-based application that provides storage, a display site, and access to a compound document object.


D

Dispatch identifier (DISPID)

The number by which a member function, parameter, or data member of an object is known internally to the IDispatch interface.

dispinterface

An IDispatch interface that responds only to a certain fixed set of names. The properties and methods of the dispinterface are not in the virtual function table (VTBL) for the object.

dual interface

An interface that supports both IDispatch and VTBL binding.


E

event

An action recognized by an object, such as clicking the mouse or pressing a key, and for which you can write code to respond. In Automation, an event is a method that is called, rather than implemented, by an Automation object.

event sink

A function that handles events. The code associated with a Visual Basic form, which contains event handlers for one or more controls, is an event sink.

event source

A control that experiences events and calls an event handler to dispose of them.

exposed object

See Automation object.


H

HRESULT

A value returned from a function call to an interface, consisting of a severity code, context information, a facility code, and a status code that describes the result. For 16-bit Windows systems, the HRESULT is an opaque result handle defined to be zero for a successful return from a function, and nonzero if error or status information is to be returned. To convert an HRESULT into a more detailed SCODE (or return value), applications call GetSCode(). See SCODE.


I

ID binding

The ability to bind member names to dispatch IDs (DISPIDs) at compile time (for example, by obtaining the IDs from a type library). This approach eliminates the need for calls to IDispatch::GetIDsOfNames, and results in improved performance over late-bound calls. See also late binding.

in-place activation

The ability to activate an object from within an OLE control and to associate a verb with that activation (for example, edit, play, change). Sometimes referred to as in-place editing or visual editing.

in-process server

An object application that runs in the same process space as the Automation controller.

interface

One or more well-defined base classes providing member functions that, when implemented in an application, provide a specific service. Interfaces may include compiled support functions to simplify their implementation.


L

late binding

The ability to bind names to IDs at run time, rather than at compile time.

locale identifier (LCID)

A 32-bit value that identifies the human language preferred by a user, region, or application.


M

marshaling

The process of packaging and sending interface parameters across process boundaries.

member function

One of a group of related functions that make up an interface. See also method and property.

method

A member function of an exposed object that performs some action on the object, such as saving it to disk.

MIDL compiler

The Microsoft Interface Definition Library (MIDL) compiler can be used to generate a type library. For information about the MIDL compiler, refer to the Microsoft Interface Definition Language Programmer’s Guide and Reference in the Win32 Software Development Kit (SDK) section of the Microsoft Developer’s Network (MSDN).

multiple-document interface (MDI) application

An application that can support multiple documents from one application instance. MDI object applications can simultaneously service a user and one or more embedding containers. See also single-document interface (SDI) application.


O

object

A unit of information that resides in a compound document and whose behavior is constant no matter where it is located or used.

Object Description Language (ODL)

A scripting language used to describe exposed libraries, objects, types, and interfaces. ODL scripts are compiled into type libraries by the MkTypLib tool.

OLE

 Microsoft’s object-based technology for sharing information and services across process and machine boundaries (object linking and embedding).

Out-of process server

An object application implemented in an executable file that runs in a separate process space from the Automation controller.


P

programmable object

See Automation object.

property

A data member of an exposed object. Properties are set or returned by means of get and put accessor functions.

proxy

An interface-specific object that packages parameters for that interface in preparation for a remote method call. A proxy runs in the address space of the sender and communicates with a corresponding stub in the receiver’s address space. See also stub, marshaling, and unmarshaling.


S

safe array

An array that contains information about the number of dimensions and the bounds of its dimensions. Safe arrays are passed by IDispatch::Invoke within VARIANTARGs. Their base type is VT_tag | VT_ARRAY.

SCODE

A DWORD value that is used in 16-bit systems to pass detailed information to the caller of an interface member or API function. The status codes for OLE interfaces and APIs are defined in FACILITY_ITF. See HRESULT.

single-document interface (SDI) application

An application that can support only one document at a time. Multiple instances of an SDI application must be started to service both an embedded object and a user. See also multiple-document interface (MDI) application.

stub

An interface-specific object that unpackages the parameters for that interface after they are marshaled across the process boundary, and makes the requested method call. The stub runs in the address space of the receiver and communicates with a corresponding proxy in the sender’s address space. See proxy, marshaling, and unmarshaling.

type description

The information used to build the type information for one or more aspects of an application’s interface. Type descriptions are written in Object Description Language (ODL), and include both programmable and nonprogrammable interfaces.

type information

Information that describes the interfaces of an application. Type information is created from type descriptions using OLE Automation tools, such as MkTypLib or the CreateDispTypeInfo function. Type information can be accessed through the ITypeInfo interface.

type information element

A unit of information identified by one of these statements in a type description: typedef, enum, struct, module, interface, dispinterface, or coclass.

type library

A file or component within another file that contains type information about exposed objects. Type libraries are created from type descriptions using MkTypLib, and can be accessed through the ITypeLib interface.


U

unmarshaling

The process of unpackaging parameters that have been sent across process boundaries.


V

Value property

The property that defines the default behavior of an object when no other methods or properties are specified. Indicate the Value property by specifying the default attribute in ODL.

virtual function table (VTBL)

A table of function pointers, such as an implementation of a class in C++. The pointers in the VTBL point to the members of the interfaces that an object supports.


ACTIVATEFLAGS

The ACTIVATEFLAGS enumeration value indicates whether an object is activated as a windowless object. It is used in IOleInPlaceSiteEx::OnInPlaceActivateEx.

typedef enum tagACTIVATEFLAGS

{

    ACTIVATE_WINDOWLESS    = 1

} ACTIVATEFLAGS;

Elements

ACTIVATE_WINDOWLESS

If TRUE, indicates that the object is activated in place as a windowless object. In the IOleInPlaceSiteEx::OnInPlaceActivateEx method, the container uses this value returned in the dwFlags parameter instead of calling the GetWindow method in the IOleInPlaceObjectWindowless interface to determine if the object is windowless or not.


ADVF

The ADVF enumeration values are flags used by a container object to specify the requested behavior when setting up an advise sink or a caching connection with an object. These values have different meanings, depending on the type of connection in which they are used, and each interface uses its own subset of the flags.

typedef enum tagADVF

{

    ADVF_NODATA            = 1,

    ADVF_PRIMEFIRST        = 4,

    ADVF_ONLYONCE          = 2,

    ADVF_DATAONSTOP        = 64,

    ADVFCACHE_NOHANDLER    = 8,

    ADVFCACHE_FORCEBUILTIN = 16,

    ADVFCACHE_ONSAVE       = 32

} ADVF;

Elements

ADVF_NODATA

For data advisory connections (IDataObject::DAdvise or IDataAdviseHolder::Advise), this flag requests the data object not to send data when it calls IAdviseSink::OnDataChange. The recipient of the change notification can later request the data by calling IDataObject::GetData. The data object can honor the request by passing TYMED_NULL in the STGMEDIUM parameter, or it can provide the data anyway. For example, the data object might have multiple advisory connections, not all of which specified ADVF_NODATA, in which case the object might send the same notification to all connections. Regardless of the container’s request, its IAdviseSink implementation must check the STGMEDIUM parameter because it is responsible for releasing the medium if it is not TYMED_NULL.

For cache connections (IOleCache::Cache), this flag requests that the cache not be updated by changes made to the running object. Instead, the container will update the cache by explicitly calling IOleCache::SetData. This situation typically occurs when the iconic aspect of an object is being cached.

ADVF_NODATA is not a valid flag for view advisory connections (IViewObject::SetAdvise) and it returns E_INVALIDARG.

ADVF_PRIMEFIRST

Requests that the object not wait for the data or view to change before making an initial call to IAdviseSink::OnDataChange (for data or view advisory connections) or updating the cache (for cache connections). Used with ADVF_ONLYONCE, this parameter provides an asynchronous GetData call.

ADVF_ONLYONCE

Requests that the object make only one change notification or cache update before deleting the connection.

ADVF_ONLYONCE automatically deletes the advisory connection after sending one data or view notification. The advisory sink receives only one IAdviseSink call. A nonzero connection identifier is returned if the connection is established, so the caller can use it to delete the connection prior to the first change notification.

For data change notifications, the combination of ADVF_ONLYONCE and ADVF_PRIMEFIRST provides, in effect, an asynchronous IDataObject::GetData call.

When used with caching, ADVF_ONLYONCE updates the cache one time only, on receipt of the first OnDataChange notification. After the update is complete, the advisory connection between the object and the cache is disconnected. The source object for the advisory connection calls the IAdviseSink::Release method.

ADVF_DATAONSTOP

For data advisory connections, assures accessibility to data. This flag indicates that when the data object is closing, it should call IAdviseSink::OnDataChange, providing data with the call. Typically, this value is used in combination with ADVF_NODATA. Without this value, by the time an OnDataChange call without data reaches the sink, the source might have completed its shutdown and the data might not be accessible. Sinks that specify this value should accept data provided in OnDataChange if it is being passed, because they may not get another chance to retrieve it.

For cache connections, this flag indicates that the object should update the cache as part of object closure.

ADVF_DATAONSTOP is not a valid flag for view advisory connections.

ADVFCACHE_NOHANDLER

Synonym for ADVFCACHE_FORCEBUILTIN, which is used more often.

ADVFCACHE_FORCEBUILTIN

This value is used by DLL object applications and object handlers that perform the drawing of their objects. ADVFCACHE_FORCEBUILTIN instructs OLE to cache presentation data to ensure that there is a presentation in the cache. This value is not a valid flag for data or view advisory connections. For cache connections, this flag caches data that requires only code shipped with OLE (or the underlying operating system) to be present in order to produce it with IDataObject::GetData or IViewObject::Draw. By specifying this value, the container can ensure that the data can be retrieved even when the object or handler code is not available.

ADVFCACHE_ONSAVE

For cache connections, this flag updates the cached representation only when the object containing the cache is saved. The cache is also updated when the OLE object transitions from the running state back to the loaded state (because a subsequent save operation would require rerunning the object). This value is not a valid flag for data or view advisory connections.

Remarks

For a data or view advisory connection, the container uses the ADVF constants when setting up a connection between an IAdviseSink instance and and either an IDataObject or IViewObject instance. These connections are set up using the IDataObject::DAdvise, IDataAdviseHolder::Advise, or IViewObject::SetAdvise methods.

For a caching connection, the constants are specified in the IOleCache::Cache method to indicate the container’s requests on how the object should update its cache.

These constants are also used in the advf member of the STATDATA structure. This structure is used by IEnumSTATDATA to describe the enumerated connections, and the advf member indicates the flags that were specified when the advisory or cache connection was established. When STATDATA is used for an IOleObject::EnumAdvise enumerator, the advf member is indeterminate.

See Also

IDataAdviseHolder, IDataObject, IEnumSTATDATA, IOleCache, IViewObject


BIND_FLAGS

The BIND_FLAGS enumeration values are used to control aspects of moniker binding operations. The values are used in the BIND_OPTS structure. Callers of IMoniker methods can specify values from this enumeration, and implementers of IMoniker methods can use these values in determining what they should do.

typedef enum tagBIND_FLAGS

{

    BIND_MAYBOTHERUSER     = 1,

    BIND_JUSTTESTEXISTENCE = 2,

} BIND_FLAGS;

Elements

BIND_MAYBOTHERUSER

If this flag is specified, the moniker implementation can interact with the end user. If not present, the moniker implementation should not interact with the user in any way, such as by asking for a password for a network volume that needs mounting. If prohibited from interacting with the user when it otherwise would, a moniker implementation can use a different algorithm that does not require user interaction, or it can fail with the error MK_MUSTBOTHERUSER.

BIND_JUSTTESTEXISTENCE

If this flag is specified, the caller is not interested in having the operation carried out, but only in learning whether the operation could have been carried out had this flag not been specified. For example, this flag lets the caller indicate only an interest in finding out whether an object actually exists by using this flag in a IMoniker::BindToObject call. Moniker implementations can, however, ignore this possible optimization and carry out the operation in full. Callers must be able to deal with both cases.

See Also

BIND_OPTS, IBindCtx


BINDSPEED

The BINDSPEED enumeration values indicate approximately how long the caller will wait to bind to an object. Callers of the IOleItemContainer::GetObject method specify values from this enumeration, and implementers of that method use these values as a guideline for how quickly they must complete their operation.

typedef enum tagBINDSPEED

{

    BINDSPEED_INDEFINITE   = 1,

    BINDSPEED_MODERATE     = 2,

    BINDSPEED_IMMEDIATE    = 3

} BINDSPEED;

Elements

BINDSPEED_INDEFINITE

There is no time limit on the binding operation.

BINDSPEED_MODERATE

The IOleItemContainer::GetObject operation must be completed in a moderate amount of time. If this flag is specified, the implementation of IOleItemContainer::GetObject should return MK_E_EXCEEEDEDDEADLINE unless the object is one of the following:

•	Already in the running state

•	A pseudo-object (i.e., an object internal to the item container, such as a cell-range in a spreadsheet or a character-range in a word processor).

•	An object supported by an in-process server (so it is always in the running state when it is loaded). In this case, IOleItemContainer::GetObject should load the designated object, and, if the OleIsRunning function indicates that the object is running, return successfully.

BINDSPEED_IMMEDIATE

The caller will wait only a short time. In this case, IOleItemContainer::GetObject should return MK_E_EXCEEEDEDDEADLINE unless the object is already in the running state or is a pseudo-object.

Remarks

The system-supplied item moniker implementation is the primary caller of IOleItemContainer::GetObject. The BINDSPEED value that it specifies depends on the deadline specified by the caller of the moniker operation.

The deadline is stored in the dwTickCountDeadline field of the BIND_OPTS structure in the bind context passed to the moniker operation. This value is based on the return value of the GetTickCount function. If dwTickCountDeadline is zero, indicating no deadline, the item moniker implementation specifies BINDSPEED_INDEFINITE. (This is the default dwTickCountDeadline value for a bind context returned by the CreateBindCtx function.) If the difference between dwTickCountDeadline and the value returned by the GetTickCount function is greater than 2500, the item moniker implementation specifies BINDSPEED_MODERATE. If the difference is less than 2500, the item moniker implementation specifies BINDSPEED_IMMEDIATE.

Implementations of IOleItemContainer::GetObject can use the BINDSPEED value as a shortcut approximation of the binding deadline, or they can use the IBindCtx instance parameter to determine the exact deadline.

See Also

BIND_OPTS, IBindCtx::GetBindOptions, IOleItemContainer::GetObject


CALLTYPE

The CALLTYPE enumeration constant specifies the call types used by IMessageFilter::HandleInComingCall.

typedef enum tagCALLTYPE

{

    CALLTYPE_TOPLEVEL             = 1,

    CALLTYPE_NESTED               = 2,

    CALLTYPE_ASYNC                = 3,

    CALLTYPE_TOPLEVEL_CALLPENDING = 4,

    CALLTYPE_ASYNC_CALLPENDING    = 5

} CALLTYPE;

Elements

CALLTYPE_TOPLEVEL

A top-level call has arrived and that the object is not currently waiting for a reply from a previous outgoing call. Calls of this type should always be handled.

CALLTYPE_NESTED

A call has arrived bearing the same logical thread identifier as that of a previous outgoing call for which the object is still awaiting a reply. Calls of this type should always handled.

CALLTYPE_ASYNC

An aysnchronous call has arrived. Calls of this type cannot be rejected. OLE always delivers calls of this type.

CALLTYPE_TOPLEVEL_CALLPENDING

A new top-level call has arrived with a new logical thread identifier and that the object is currently waiting for a reply from a previous outgoing call. Calls of this type may be handled or rejected.

CALLTYPE_ASYNC_CALLPENDING

An asynchronous call has arrived with a new logical thread identifier and that the object is currently waiting for a reply from a previous outgoing call. Calls of this type cannot be rejected.

async call − can NOT be rejected

See Also

IMessageFilter::HandleInComingCall, IMessageFilter


CLSCTX

Values from the CLSCTX enumeration are used in activation calls to indicate the execution contexts in which an object is to be run. These values are also used in calls to CoRegisterClassObject to indicate the set of execution contexts in which a class object is to be made available for requests to construct instances.

typedef enum tagCLSCTX

{

    CLSCTX_INPROC_SERVER   = 1,

    CLSCTX_INPROC_HANDLER  = 2,

    CLSCTX_LOCAL_SERVER    = 4

    CLSCTX_REMOTE_SERVER = 16

} CLSCTX;

#define CLSCTX_SERVER    (CLSCTX_INPROC_SERVER | CLSCTX_LOCAL_SERVER | CLSCTX_REMOTE_SERVER)

#define CLSCTX_ALL       (CLSCTX_INPROC_HANDLER | CLSCTX_SERVER)

Elements

CLSCTX_INPROC_SERVER

The code that creates and manages objects of this class runs in the same process as the caller of the function specifying the class context.

CLSCTX_INPROC_HANDLER

The code that manages objects of this class is an in-process handler. This is a DLL that runs in the client process and implements client-side structures of this class when instances of the class are accessed remotely.

CLSCTX_LOCAL_SERVER

The EXE code that creates and manages objects of this class is loaded in a separate process space (runs on same machine but in a different process).

CLSCTX_REMOTE_SERVER

A remote machine context. The LocalServer32 or LocalService code that creates and manages objects of this class is run on a different machine.

Defined Terms

CLSCTX_SERVER

Indicates server code, whether in-process, local, or remote. This definition ORs CLSCTX_INPROC_SERVER, CLSCTX_LOCAL_SERVER, and CLSCTX_REMOTE_SERVER.

CLSCTX_ALL

Indicates all class contexts. This definition ORs CLSCTX_INPROC_HANDLER and CLSCTX_SERVER.

Remarks

Values from the CLSCTX enumeration are used in activation calls (CoCreateInstance, CoCreateInstanceEx, CoGetClassObject, etc.) to indicate the preferred execution contexts − in-process, local, or remote − in which an object is to be run. They are also used in calls to CoRegisterClassObject to indicate the set of execution contexts in which a class object is to be made available for requests to construct instances (IClassFactory::CreateInstance).

To indicate that more than one context is acceptable, you can string multiple values together with Boolean ORs. The contexts are tried in the order in which they are listed.

The following table shows how other OLE functions and methods that call CoGetClassObject use the CLSCTX values:

Function Called	Context Flag Used
OleLoad	CLSCTX_INPROC_HANDLER | CLSCTX_INPROC_SERVER Putting an OLE object into the loaded state requires in-process access; but, it doesn’t matter if all of the object’s function is presently available.
IRunnableObject::Run	CLSCTX_INPROC_SERVER | CLSCTX_LOCAL_SERVER Running an OLE object requires connecting to the full code of the object wherever it is located.
CoUnMarshalInterface	CLSCTX_INPROC_HANDLER   Unmarshaling needs the form of the class designed for remote access.
IMoniker::BindToObject, for a file moniker created through a call to CreateFileMoniker	In this case, uses CLSCTX_SERVER interally to create the instance after calling GetClassFile to determine the class to be instantiated.
The CLSCTX_REMOTE_SERVER value is added to the CLSCTX enumeration for distributed COM. The CLSCTX_SERVER and CLSCTX_ALL constants are further updated to include the CLSCTX_REMOTE_SERVER value.

Given a set of CLSCTX flags, dwClsCtx, the execution context to be used depends on the availability of registered class codes and other parameters according to the following algorithm:

The first part of the processing determines whether CLSCTX_REMOTE SERVER should be specified as follows:

1.	If the call specifies either

a)	an explicit COSERVERINFO structure indicating a machine different from the current machine, or

b)	there is no explicit COSERVERINFO structure specified, but the specified class is registered with either the RemoteServerName or ActivateAtStorage named-value.

then CLSCTX_REMOTE_SERVER is implied and is added to dwClsCtx. The second case allows applications written prior to the release of distributed COM to be the configuration of classes for remote activation to be used by client applications available prior to DCOM and the CLSCTX_REMOTE_SERVER flag. The cases in which there would be no explicit COSERVERINFO structure are 1) The value is specified as NULL, or 2) It is not one of the function parameters, as would be the case in calls to CoCreateInstance or CoGetClassObject in existing applications.

2.	If the explicit COSERVERINFO parameter indicates the current machine, CLSCTX_REMOTE_SERVER is removed (if present) from dwClsCtx.

The rest of the processing proceeds by looking at the value(s) of dwClsCtx in the following sequence.

1.	If dwClsCtx includes CLSCTX_REMOTE_SERVER and no COSERVERINFO parameter is specified, if the activation request indicates a persistent state from which to initialize the object (with CoGetInstanceFromFile, CoGetInstanceFromIStorage, or, for a file moniker, in a call to IMoniker::BindToObject) and the class has an ActivateAtStorage sub-key or no class registry information whatsoever, the request to activate and initialize is forwarded to the machine where the persistent state resides. (Refer to the remote activation functions listed in the See Also section for details.)

2.	If dwClsCtx includes CLSCTX_INPROC_SERVER, the class code in the DLL found under the class’s InprocServer32 key is used if this key exists. The class code will run within the same process as the caller.

3.	If dwClsCtx includes CLSCTX_INPROC_HANDLER, the class code in the DLL found under the class’s InprocHandler32 key is used if this key exists. The class code will run within the same process as the caller.

4.	If dwClsCtx includes CLSCTX_LOCAL_SERVER, the class code in the Win32 service found under the class’s LocalService key is used if this key exists. If no Win32 service is specified, but an EXE is specified under that same key, the class code associated with that EXE is used. The class code (in either case) will be run in a separate service process on the same machine as the caller.

5.	If dwClsCtx is set to CLSCTX_REMOTE_SERVER and an additional COSERVERINFO parameter to the function specifies a particular remote machine, a request to activate is forwarded to this remote machine with dwClsCtx modified to be CLSCTX_LOCAL_SERVER. The class code will run in its own process on this specific machine, which must be different from that of the caller.

6.	Finally, if dwClsCtx includes CLSCTX_REMOTE_SERVER and no COSERVERINFO parameter is specified, if a machine name is given under the class’s RemoteServerName named-value, the request to activate is forwarded to this remote machine with dwClsCtx modified to be CLSCTX_LOCAL_SERVER. The class code will run in its own process on this specific machine, which must be different from that of the caller.

See Also

CoCreateInstance, CoGetClassObject, CoRegisterClassObject, CoGetInstanceFromFile, CoGetInstanceFromIStorage, CoCreateInstanceEx, COSERVERINFO structure, Creating an Object through a Class Object, Registering a Running EXE Server


COINIT

A set of values from the COINIT enumeration is passed as the dwCoInit parameter to CoInitializeEx. This value determines the concurrency model used for incoming calls to objects created by this thread. This concurrency model can be either apartment-threaded or multi-threaded.

The COINIT enumeration is defined as follows:

typedef enum tagCOINIT{

  COINIT_APARTMENTTHREADED = 0x2,  // Apartment model

  COINIT_MULTITHREADED     = 0x0,  // OLE calls objects on any thread.

  COINIT_DISABLE_OLE1DDE   = 0x4,  // Don't use DDE for Ole1 support.

  COINIT_SPEED_OVER_MEMORY = 0x8,  // Trade memory for speed.

} COINIT;

Members

COINIT_MULTITHREADED

Initializes the thread for multi-threaded object concurrency (see Remarks).

COINIT_APARTMENTTHREADED

Initializes the thread for apartment-threaded object concurrency (see Remarks).

COINIT_DISABLE_OLE1DDE

Disables DDE for Ole1 support.

COINIT_SPEED_OVER_MEMORY

Trades memory for speed.

Remarks

When a thread is initialized through a call to CoInitializeEx, you choose whether to initialize it as apartment-threaded or multi-threaded by designating one of the members of COINIT as its second parameter. This designates how incoming calls to any object created by that thread are handled, that is, the object’s concurrency.

Apartment-threading, the default model for earlier versions of Windows NT, while allowing for multiple threads of execution, serializes all incoming calls by requiring that calls to methods of objects created by this thread always run on the same thread − the apartment/thread that created them. In addition, calls can arrive only at message-queue boundaries (i.e., only during a PeekMessage, SendMessage, DispatchMessage, etc.). Because of this serialization, it is not typically necessary to write concurrency control into the code for the object, other than to avoid calls to PeekMessage and SendMessage during processing that must not be interrupted by other method invocations or calls to other objects in the same apartment/thread.

Multi-threading (also called free-threading) allows calls to methods of objects created by this thread to be run on any thread. There is no serialization of calls − many calls may occur to the same method or to the same object or simultaneously. Multi-threaded object concurrency offers the highest performance and takes the best advantage of multi-processor hardware for cross-thread, cross-process, and cross-machine calling, since calls to objects are not serialized in any way. This means, however, that the code for objects must enforce its own concurrency model, typically through the use of Win32 synchronization primitives, such as critical sections, semaphores, or mutexes. In addition, because the object doesn’t control the lifetime of the threads that are accessing it, no thread-specific state may be stored in the object (in Thread-Local-Storage).

See Also

CoInitializeEx, Processes and Threads


DATADIR

The DATADIR enumeration values specify the direction of the data flow in the dwDirection parameter of the IDataObject::EnumFormatEtc method. This determines the formats that the resulting enumerator can enumerate.

typedef enum tagDATADIR

{

    DATADIR_GET            = 1,

    DATADIR_SET            = 2

} DATADIR;

Elements

DATADIR_GET

Requests that IDataObject::EnumFormatEtc supply an enumerator for the formats that can be specified in IDataObject::GetData.

DATADIR_SET

Requests that IDataObject::EnumFormatEtc supply an enumerator for the formats that can be specified in IDataObject::SetData.

See Also

IDataObject


DISCARDCACHE

The DISCARDCACHE enumeration values are used in the IOleCache2::DiscardCache method to specify what to do with caches that are to be discarded from memory if their dirty bit has been set. The dwDiscardOptions parameter specifies whether or not to save these caches.

Defined in the

typedef enum tagDISCARDCACHE

{

    DISCARDCACHE_SAVEIFDIRTY    = 0,

    DISCARDCACHE_NOSAVE         = 1

} DISCARDCACHE;

Elements

DISCARDCACHE_SAVEIFDIRTY

The cache is to be saved to disk.

DISCARDCACHE_NOSAVE

The cache can be discarded without saving it.

See Also

IOleCache2::DiscardCache


DROPEFFECT

The DoDragDrop function and many of the methods in the IDropSource and IDropTarget interfaces pass information about the effects of a drag-and-drop operation in a DROPEFFECT enumeration.

Valid drop-effect values are the result of applying the OR operation to the values contained in the DROPEFFECT enumeration:

typedef enum tagDROPEFFECT

{

    DROPEFFECT_NONE   = 0,

    DROPEFFECT_COPY   = 1,

    DROPEFFECT_MOVE   = 2,

    DROPEFFECT_LINK   = 4,

    DROPEFFECT_SCROLL = 0x80000000

}DROPEFFECT;

These values have the following meaning:

DROPEFFECT name	Value	Description
DROPEFFECT_NONE	0	Drop target cannot accept the data.
DROPEFFECT_COPY	1	Drop results in a copy. The original data is untouched by the drag source.
DROPEFFECT_MOVE	2	Drag source should remove the data.
DROPEFFECT_LINK	4	Drag source should create a link to the original data.
DROPEFFECT_SCROLL	0x80000000	Scrolling is about to start or is currently occurring in the target. This value is used in addition to the other values.
Note  Your application should always mask values from the DROPEFFECT enumeration to ensure compatibility with future implementations. Presently, only four of the 32-bit positions in a DROPEFFECT have meaning. In the future, more interpretations for the bits will be added. Drag sources and drop targets should carefully mask these values appropriately before comparing. They should never compare a DROPEFFECT against, say, DROPEFFECT_COPY by:

if (dwDropEffect == DROPEFFECT_COPY)...

Instead, the application should always mask for the value or values being sought:

if (dwDropEffect & DROPEFFECT_COPY) == DROPEFFECT_COPY)...

or

if (dwDropEffect & DROPEFFECT_COPY)...

This allows for the definition of new drop effects, while preserving backwards compatibility with existing code.

See Also

DoDragDrop, IDropSource, IDropTarget


DVASPECT

The DVASPECT enumeration values specify the desired data or view aspect of the object when drawing or getting data.

typedef enum tagDVASPECT

{

    DVASPECT_CONTENT    = 1,

    DVASPECT_THUMBNAIL  = 2,

    DVASPECT_ICON       = 4,

    DVASPECT_DOCPRINT   = 8

} DVASPECT;

Elements

DVASPECT_CONTENT

Provides a representation of an object so it can be displayed as an embedded object inside of a container. This value is typically specified for compound document objects. The presentation can be provided for the screen or printer.

DVASPECT_THUMBNAIL

Provides a thumbnail representation of an object so it can be displayed in a browsing tool. The thumbnail is approximately a 120 by 120 pixel, 16-color (recommended) device-independent bitmap potentially wrapped in a metafile.

DVASPECT_ICON

Provides an iconic representation of an object.

DVASPECT_DOCPRINT

Provides a representation of the object on the screen as though it were printed to a printer using the Print command from the File menu. The described data may represent a sequence of pages.

Remarks

Values of this enumeration are used to define the dwAspect field of the FORMATETC structure. Only one DVASPECT value can be used to specify a single presentation aspect in a FORMATETC structure. The FORMATETC structure is used in many OLE functions and interface methods that require information on data presentation.

See Also

IAdviseSink, IDataObject, IOleObject, IViewObject, IViewObject2, OleDraw, FORMATETC, OBJECTDESCRIPTOR


DVASPECT2

The DVASPECT2 enumeration value is used in IViewObject::Draw to specify new drawing aspects used to optimize the drawing process.

typedef enum tagDVASPECT2

{

    DVASPECT_OPAQUE         = 16,

    DVASPECT_TRANSPARENT    = 32

} DVASPECT2;

Elements

DVASPECT_OPAQUE

Represents the opaque, easy to clip parts of an object. Objects may or may not support this aspect.

DVASPECT_TRANSPARENT

Represents the transparent or irregular parts of on object, typically parts that are expensive or impossible to clip out. Objects may or may not support this aspect.

Remarks

To support drawing optimizations to reduce flicker, an object needs to be able to draw and return information about three separate aspects of itself:

DVASPECT_CONTENT

Same as before. Specifies the entire content of an object. All objects should support this aspect.

DVASPECT_OPAQUE

Represents the opaque, easy to clip parts of an object. Objects may or may not support this aspect.

DVASPECT_TRANSPARENT

Represents the transparent or irregular parts of on object, typically parts that are expensive or impossible to clip out. Objects may or may not support this aspect.

The container can determine which of these drawing aspects an object supports by calling the new method IViewObjectEx::GetViewStatus. Individual bits return information about which aspects are supported. If an object does not support the IViewObjectEx interface, it is assumed to support only DVASPECT_CONTENT.

Depending on which aspects are supported, the container can ask the object to draw itself during the front to back pass only, the back to front pass only, or both. The various possible cases are:

•	Objects supporting only DVASPECT_CONTENT should be drawn during the back to front pass, with all opaque parts of any overlapping object clipped out. Since all objects should support this aspect, a container not concerned about flickering - maybe because it is drawing in an offscreen bitmap - can opt to draw all objects that way and skip the front to back pass.

•	Objects supporting DVASPECT_OPAQUE may be asked to draw this aspect during the front to back pass. The container is responsible for clipping out the object’s opaque regions (returned by  IViewObjectEx::GetRegion) before painting any further object behind it.

•	Objects supporting DVASPECT_TRANSPARENT may be asked to draw this aspect during the back to front pass. The container is responsible for clipping out opaque parts of overlapping objects before letting an object draw this aspect.

Even when DVASPECT_OPAQUE and DVASPECT_TRANSPARENT are supported, the container is free to use these aspects or not. In particular, if it is painting in an offscreen bitmap and consequently is unconcerned about flicker, the container may use DVASPECT_CONTENT and a one-pass drawing only. However, in a two-pass drawing, if the container uses DVASPECT_OPAQUE during the front to back pass, then it must use DVASPECT_TRANSPARENT during the back to front pass to complete the rendering of the object.

See Also

IViewObject::Draw


DVASPECTINFOFLAG

The DVASPECTINFOFLAG enumeration value is used in the DVASPECTINFO structure to indicate whether an object can support optimized drawing of itself.

typedef enum tagDVASPECTINFOFLAG

{

    DVASPECTINFOFLAG_CANOPTIMIZE    = 1

} DVASPECTINFOFLAG;

Elements

DVASPECTINFOFLAG_CANOPTIMIZE

If TRUE, indicates that the object can support optimized rendering of itself. Since most objects on a form share the same font, background color, and border types, leaving these values in the device context allows the next object to use them without having to re-select them. Specifically, the object can leave the font, brush, and pen selected on return from the IViewObject::Draw method instead of deselecting these from the device context. The container then must deselect these values at the end of the overall drawing process. The object can also leave other drawing state changes in the device context, such as the background color, the text color, raster operation code, the current point, the line drawing, and the poly fill mode. The object cannot change state values unless other objects are capable of restoring them. For example, the object cannot leave a changed mode, transformation value, selected bitmap, clip region, or metafile.

See Also

DVASPECTINFO


DVEXTENTMODE

The DVEXTENTMODE enumeration values are used in IViewObjectEx::GetNaturalExtent.

typedef enum tagDVEXTENTMODE

{

    DVEXTENT_CONTENT               = 0,

    DVEXTENT_INTEGRAL              = 1

} DVEXTENTMODE;

Elements

DVEXTENT_CONTENT

Indicates that the container will ask the object how big it wants to be to exactly fit its content, for example, in snap-to-size operations.

DVEXTENT_INTEGRAL

Indicates that the container will provide a proposed size to the object for its use in resizing.

See Also

IViewObjectEx::GetNaturalExtent


EXTCONN

The EXTCONN enumeration specifies the type of external connection existing on an embedded object. Currently, the only supported type is EXTCONN_STRONG, meaning that the external connection is a link. This EXTCONN constant is used in the IExternalConnection::AddConnection and IExternalConnection::ReleaseConnection methods.

typedef enum tagEXTCONN

{

    EXTCONN_STRONG      = 0X0001,

    EXTCONN_WEAK        = 0X0002,

    EXTCONN_CALLABLE    = 0X0004

} EXTCONN;

Elements

EXTCONN_STRONG

If this value is specified, the external connection must keep the object alive until all strong external connections are cleared through IExternalConnection::ReleaseConnection.

EXTCONN_WEAK

This value is currently not used.

EXTCONN_CALLABLE

This value is currently not used.


GUIDKIND

The GUIDKIND enumeration values are flags used to specify the kind of information requested from an object in the IProvideClassInfo2.

typedef enum tagGUIDKIND

{

    GUIDKIND_DEFAULT_SOURCE_DISP_IID  =  1,

    GUIDKIND_DEFAULT_SOURCE_IID       =  2,

    GUIDKIND_DEFAULT_DISP_IID         =  3,

    GUIDKIND_DEFAULT_IID              =  4,

    GUIDKIND_TLBID                    =  5,

    GUIDKIND_CLSID                    =  6

} GUIDKIND;

Members

GUIDKIND_DEFAULT_SOURCE_DISP_IID

The interface identifier (IID) of the object’s outgoing dispinterface, labeled [source, default]. The outgoing interface in question must be derived from IDispatch.

GUIDKIND_DEFAULT_SOURCE_IID

The interface identifier (IID) of the object’s outgoing interface, labeled [source, default]. The outgoing interface can be any COM interface.

GUIDKIND_DEFAULT_DISP_IID

The interface identifier (IID) of the object’s [default] dispinterface that best represents the object as a whole. This dispinterface must be derived from IDispatch..

GUIDKIND_DEFAULT_IID

The interface identifier (IID) of the object’s [default] interface that best represents the object as a whole. This interface can be any COM interface.

GUIDKIND_TLBID

The GUID identifying the object’s current type library.

GUIDKIND_CLSID

The object’s CLSID.

See Also

IProvideClassInfo2


HITRESULT

The HITRESULT enumeration values are used in IViewObjectEx::QueryHitPoint and IViewObjectEx::QueryHitRect.

typedef enum tagHITRESULT

{

    HITRESULT_OUTSIDE               = 0,

    HITRESULT_TRANSPARENT           = 1,

    HITRESULT_CLOSE                 = 2,

    HITRESULT_HIT                   = 3

} HITRESULT;

Elements

HITRESULT_OUTSIDE

The specified location is outside the object and not close to the object.

HITRESULT_TRANSPARENT

The specified location is within the bounds of the object, but not close to the image. For example, a point in the middle of a transparent circle could be HITRESULT_TRANSPARENT.

HITRESULT_CLOSE

The specified location is inside the object or is outside the object but is close enough to the object to be considered inside. Small, thin or detailed objects may use this value. Even if a point is outside the bounding rectangle of an object it may still be close. This value is needed for hitting small objects.

HITRESULT_HIT

The specified location is within the image of the object

See Also

IViewObjectEx::QueryHitPoint, IViewObjectEx::QueryHitRect


KEYMODIFIERS

The KEYMODIFIERS enumeration values are flags used in calls to IOleControlSite::TranslateAccelerator to describe additional keyboard states that can modify the meaning of the keyboard messages that are also passed into IOleControlSite::TranslateAccelerator.

typedef enum tagKEYMODIFIERS

{

    KEYMOD_SHIFT       = 0x00000000,

    KEYMOD_CONTROL     = 0x00000001,

    KEYMOD_ALT         = 0x00000002

} KEYMODIFIERS;

Elements

KEYMOD_SHIFT

The Shift key is currently depressed.

KEYMOD_CONTROL

The Control key is currently depressed.

KEYMOD_ALT

The Alt key is currently depressed.

See Also

IOleControlSite::TranslateAccelerator


LOCKTYPE

The LOCKTYPE enumeration values indicate the type of locking requested for the specified range of bytes. The values are used in the ILockBytes::LockRegion and IStream::LockRegion methods.

typedef enum tagLOCKTYPE

{

    LOCK_WRITE      = 1,

    LOCK_EXCLUSIVE  = 2,

    LOCK_ONLYONCE   = 4

} LOCKTYPE;

Elements

LOCK_WRITE

If this lock is granted, the specified range of bytes can be opened and read any number of times, but writing to the locked range is prohibited except for the owner that was granted this lock.

LOCK_EXCLUSIVE

If this lock is granted, writing to the specified range of bytes is prohibited except for the owner that was granted this lock.

LOCK_ONLYONCE

If this lock is granted, no other LOCK_ONLYONCE lock can be obtained on the range. Usually this lock type is an alias for some other lock type. Thus, specific implementations can have additional behavior associated with this lock type.


MKRREDUCE

The MKRREDUCE enumeration constants are used to specify how far the moniker should be reduced. They are used in the IMoniker::Reduce method.

typedef enum tagMKRREDUCE

{

    MKRREDUCE_ONE          = 3<<16,

    MKRREDUCE_TOUSER       = 2<<16,

    MKRREDUCE_THROUGHUSER  = 1<<16,

    MKRREDUCE_ALL          = 0

} MKRREDUCE;

Elements

MKRREDUCE_ONE

Performs only one step of reducing the moniker. In general, the caller must have specific knowledge about the particular kind of moniker to take advantage of this option.

MKRREDUCE_TOUSER

Reduces the moniker to a form that the user identifies as a persistent object. If no such point exists, then this option should be treated as MKRREDUCE_ALL.

MKRREDUCE_THROUGHUSER

Reduces the moniker to where any further reduction would reduce it to a form that the user does not identify as a persistent object. Often, this is the same stage as MKRREDUCE_TOUSER.

MKRREDUCE_ALL

Reduces the moniker until it is in its simplest form, that is, reduce it to itself.

See Also

IMoniker::Reduce


MKSYS

The MKSYS enumeration constants indicate the moniker’s class. They are returned from the IMoniker::IsSystemMoniker method. MKSYS is defined in Objidl.h.

typedef enum tagMKSYS

{

    MKSYS_NONE               = 0,

    MKSYS_GENERICCOMPOSITE   = 1,

    MKSYS_FILEMONIKER        = 2,

    MKSYS_ANTIMONIKER        = 3,

    MKSYS_ITEMMONIKER        = 4,

    MKSYS_POINTERMONIKER     = 5,

    MKSYS_CLASSMONIKER       = 7

} MKSYS;

Elements

MKSYS_NONE

Indicates a custom moniker implementation.

MKSYS_GENERICCOMPOSITE

Indicates the system’s generic composite moniker class.

MKSYS_FILEMONIKER

Indicates the system’s file moniker class.

MKSYS_ANTIMONIKER

Indicates the system’s anti-moniker class.

MKSYS_ITEMMONIKER

Indicates the system’s item moniker class.

MKSYS_POINTERMONIKER

Indicates the system’s pointer moniker class.

MKSYS_CLASSMONIKER

Indicates the system’s class moniker class.

See Also

IMoniker::IsSystemMoniker


MSHCTX

The MSHCTX enumeration constants specify the destination context, which is the process in which the unmarshaling is to be done. These flags are used in the IMarshal and IStdMarshalInfo interfaces and in the CoMarshalInterface and CoGetStandardMarshal functions.

typedef enum tagMSHCTX

{

    MSHCTX_LOCAL              = 0,

    MSHCTX_NOSHAREDMEM        = 1,

    MSHCTX_DIFFERENTMACHINE   = 2,

    MSHCTX_INPROC             = 3

} MSHCTX;

Elements

MSHCTX_LOCAL

The unmarshaling process is local and has shared memory access with the marshaling process.

MSHCTX_NOSHAREDMEM

The unmarshaling process does not have shared memory access with the marshaling process.

MSHCTX_DIFFERENTMACHINE

The unmarshaling process is on a different machine. The marshaling code cannot assume that a particular piece of application code is installed on that machine.

MSHCTX_INPROC

The unmarshaling will be done in another apartment in the same process. If your object supports multiple threads, your custom marshaler can pass a direct pointer instead of creating a proxy object.

See Also

CoGetStandardMarshal, CoMarshalInterface, IMarshal, IStdMarshalInfo


MSHLFLAGS

The MSHLFLAGS enumeration constants determine why the marshaling is to be done. These flags are used in the IMarshal interface and the CoMarshalInterface and CoGetStandardMarshal functions.

typedef enum tagMSHLFLAGS

{

    MSHLFLAGS_NORMAL         = 0,

    MSHLFLAGS_TABLESTRONG    = 1,

    MSHLFLAGS_TABLEWEAK      = 2

} MSHLFLAGS;

Elements

MSHLFLAGS_NORMAL

The marshaling is occurring because an interface pointer is being passed from one process to another. This is the normal case. The data packet produced by the marshaling process will be unmarshaled in the destination process. The marshaled data packet can be unmarshaled just once, or not at all. If the receiver unmarshals the data packet successfully, the CoReleaseMarshalData function is automatically called on the data packet as part of the unmarshaling process. If the receiver does not or cannot unmarshal the data packet, the sender must call the CoReleaseMarshalData function on the data packet.

MSHLFLAGS_TABLESTRONG

The marshaling is occurring because the data packet is to be stored in a globally accessible table from which it can be unmarshaled one or more times, or not at all. The presence of the data packet in the table counts as a strong reference to the interface being marshaled, meaning that it is sufficient to keep the object alive. When the data packet is removed from the table, the table implementer must call the CoReleaseMarshalData function on the data packet.

MSHLFLAGS_TABLESTRONG is used by the RegisterDragDrop function when registering a window as a drop target. This keeps the window registered as a drop target no matter how many times the end user drags across the window. The RevokeDragDrop function calls CoReleaseMarshalData.

MSHLFLAGS_TABLEWEAK

The marshaling is occurring because the data packet is to be stored in a globally accessible table from which it can be unmarshaled one or more times, or not at all. However, the presence of the data packet in the table acts as a weak reference to the interface being marshaled, meaning that it is not sufficient to keep the object alive. When the data packet is removed from the table, the table implementer must call the CoReleaseMarshalData function on the data packet.

MSHLFLAGS_TABLEWEAK is typically used when registering an object in the Running Object Table (ROT). This prevents the object’s entry in the ROT from keeping the object alive in the absence of any other connections. See IRunningObjectTable::Register for more information.

See Also

CoGetStandardMarshal, CoMarshalInterface, CoReleaseMarshalData, IMarshal


OLECLOSE

The OLECLOSE enumeration constants are used in the IOleObject::Close method to determine whether the object should be saved before closing.

typedef enum tagOLECLOSE

{

    OLECLOSE_SAVEIFDIRTY  = 0,

    OLECLOSE_NOSAVE       = 1,

    OLECLOSE_PROMPTSAVE   = 2

} OLECLOSE;

Elements

OLECLOSE_SAVEIFDIRTY

The object should be saved if it is dirty.

OLECLOSE_NOSAVE

The object should not be saved, even if it is dirty. This flag is typically used when an object is being deleted.

OLECLOSE_PROMPTSAVE

If the object is dirty, the IOleObject::Close implementation should display a dialog box to let the end user determine whether to save the object. However, if the object is in the running state but its user interface is invisible, the end user should not be prompted, and the close should be handled as if OLECLOSE_SAVEIFDIRTY had been specified.

See Also

IOleObject::Close


OLECONTF

The OLECONTF enumeration indicates the kind of objects to be enumerated by the returned IEnumUnknown interface. OLECONTF contains a set of bitwise constants used in the IOleContainer::EnumObjects method.

typedef enum tagOLECONTF

{

    OLECONTF_EMBEDDINGS    = 1;

    OLECONTF_LINKS         = 2;

    OLECONTF_OTHERS        = 4;

    OLECONTF_ONLYUSER      = 8;

    OLECONTF_ONLYIFRUNNING = 16

} OLECONTF;

Elements

OLECONTF_EMBEDDINGS

Enumerates the embedded objects in the container.

OLECONTF_LINKS

Enumerates the linked objects in the container.

OLECONTF_OTHERS

Enumerates all objects in the container that are not OLE compound document objects (i.e., objects other than linked or embedded objects). Use this flag to enumerate the container’s pseudo-objects.

OLECONTF_ONLYUSER

Enumerates only those objects the user is aware of. For example, hidden named-ranges in Microsoft Excel would not be enumerated using this value.

OLECONTF_ONLYIFRUNNING

Enumerates only those linked or embedded objects that are currently in the running state for this container.

See Also

IEnumUnknown, IOleContainer::EnumObjects


OLECREATE

Values from the OLECREATE enumeration are passed as the dwFlags parameter to the OleCreateXXX functions to indicate how the creation operation should proceed.

typedef enum tagOLECREATE

{

    OLECREATE_LEAVERUNNING = 1,

} OLECREATE;

Elements

OLECREATE_LEAVERUNNING

Indicates that the newly created object should be left in the running state upon successful completion of the call.

See Also

OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx, OleCreateLinkFromDataEx


OLEDCFLAGS

The OLEDCFLAGS enumeration value supplies additional information to the container about the device context that the object has requested. It is used in IOleInPlaceSiteWindowless::GetDC.

typedef enum tagOLEDCFLAGS

{

    OLEDC_NODRAW      = 0x1,

    OLEDC_PAINTBKGND  = 0x2,

    OLEDC_OFFSCREEN   = 0x4

} OLEDCFLAGS;

Elements

OLEDC_NODRAW

Indicates that the object will not use the returned hDC for drawing but merely to get information about the display device. In this case, the container can simply pass the window’s device context without further processing.

OLEDC_PAINTBKGND

Requests that the container paint the background behind the object before returning the device context. Objects should use this flag when requesting a device context to paint a transparent area.

OLEDC_OFFSCREEN

Indicates that the object prefers to draw into an offscreen device context that should then be copied to the screen. The container can honor this request or not. If this bit is cleared, the container must return an on-screen device context allowing the object to perform direct screen operations such as showing a selection via an XOR operation. An object can specify this value when the drawing operation generates a lot of screen flicker.

See Also

IOleInPlaceSiteWindowless::GetDC


OLEGETMONIKER

The OLEGETMONIKER enumeration constants indicate the requested behavior of the IOleObject::GetMoniker and IOleClientSite::GetMoniker methods.

typedef enum tagOLEGETMONIKER

{

    OLEGETMONIKER_ONLYIFTHERE = 1,

    OLEGETMONIKER_FORCEASSIGN = 2,

    OLEGETMONIKER_UNASSIGN    = 3,

    OLEGETMONIKER_TEMPFORUSER = 4

} OLEGETMONIKER;

Elements

OLEGETMONIKER_ONLYIFTHERE

If a moniker for the object or container does not exist, GetMoniker should return E_FAIL and not assign a moniker.

OLEGETMONIKER_FORCEASSIGN

If a moniker for the object or container does not exist, GetMoniker should create one.

OLEGETMONIKER_UNASSIGN

IOleClientSite::GetMoniker can release the object’s moniker (although it is not required to do so). This constant is not valid in IOleObject::GetMoniker.

OLEGETMONIKER_TEMPFORUSER

If a moniker for the object does not exist, IOleObject::GetMoniker can create a temporary moniker that can be used for display purposes (IMoniker::GetDisplayName) but not for binding. This enables the object server to return a descriptive name for the object without incurring the overhead of creating and maintaining a moniker until a link is actually created.

Remarks

If the OLEGETMONIKER_FORCEASSIGN flag causes a container to create a moniker for the object, the container should notify the object by calling the IOleObject::SetMoniker method.

See Also

IMoniker, IOleClientSite::GetMoniker, IOleObject::GetMoniker


OLELINKBIND

The OLELINKBIND enumeration constants control binding operations to a link source. They are used in the IOleLink::BindToSource method.

typedef enum tagOLELINKBIND

{

    OLELINKBIND_EVENIFCLASSDIFF = 1,

} OLELINKBIND;

Element

OLELINKBIND_EVENIFCLASSDIFF

The binding operation should proceed even if the current class of the link source is different from the last time the link was bound. For example, the link source could be a Lotus spreadsheet that was converted to an Excel spreadsheet.

See Also

IOleLink::BindToSource


OLEMISC

The OLEMISC enumeration is a set of bitwise constants that can be combined to describe miscellaneous characteristics of an object or class of objects. A container can call the IOleObject::GetMiscStatus method to determine the OLEMISC bits set for an object. The values specified in an object server’s CLSID\MiscStatus entry in the registration database are based on the OLEMISC enumeration. These constants are also used in the dwStatus member of the OBJECTDESCRIPTOR structure.

typedef enum tagOLEMISC // bitwise

{

    OLEMISC_RECOMPOSEONRESIZE            = 1,

    OLEMISC_ONLYICONIC                   = 2,

    OLEMISC_INSERTNOTREPLACE             = 4,

    OLEMISC_STATIC                       = 8,

    OLEMISC_CANTLINKINSIDE               = 16,

    OLEMISC_CANLINKBYOLE1                = 32,

    OLEMISC_ISLINKOBJECT                 = 64,

    OLEMISC_INSIDEOUT                    = 128,

    OLEMISC_ACTIVATEWHENVISIBLE          = 256,

    OLEMISC_RENDERINGISDEVICEINDEPENDENT = 512,

    OLEMISC_INVISIBLEATRUNTIME           = 1024

    OLEMISC_ALWAYSRUN                    = 2048,

    OLEMISC_ACTSLIKEBUTTON               = 4096,

    OLEMISC_ACTSLIKELABEL                = 8192,

    OLEMISC_NOUIACTIVATE                 = 16384,

    OLEMISC_ALIGNABLE                    = 32768,

    OLEMISC_SIMPLEFRAME                  = 65536,

    OLEMISC_SETCLIENTSITEFIRST           = 131072,

    OLEMISC_IMEMODE                      = 262144,

    OLEMISC_IGNOREACTIVATEWHENVISIBLE    = 524288,

    OLEMISC_WANTSTOMENUMERGE             = 1048576,

    OLEMISC_SUPPORTSMULTILEVELUNDO       = 2097152

} OLEMISC;

Elements

OLEMISC_RECOMPOSEONRESIZE

When the container resizes the space allocated to displaying one of the object’s presentations, the object wants to recompose the presentation. This means that on resize, the object wants to do more than scale its picture. If this bit is set, the container should force the object to the running state and call IOleObject::SetExtent with the new size.

OLEMISC_ONLYICONIC

The object has no useful content view other than its icon. From the user’s perspective, the Display As Icon checkbox (in the Paste Special dialog box) for this object should always be checked, and should not be uncheckable. Note that such an object should still have a drawable content aspect; it will look the same as its icon view.

OLEMISC_INSERTNOTREPLACE

The object has initialized itself from the data in the container’s current selection. Containers should examine this bit after calling IOleObject::InitFromData to initialize an object from the current selection. If set, the container should insert the object beside the current selection rather than replacing the current selection. If this bit is not set, the object being inserted replaces the current selection.

OLEMISC_STATIC

This object is a static object, which is an object that contains only a presentation; it contains no native data. See OleCreateStaticFromData.

OLEMISC_CANTLINKINSIDE

This object cannot be the link source that when bound to activates (runs) the object. If the object is selected and copied to the clipboard, the object’s container can offer a link in a clipboard data transfer that, when bound, must connect to the outside of the object. The user would see the object selected in its container, not open for editing. Rather than doing this, the container can simply refuse to offer a link source when transferring objects with this bit set. Examples of objects that have this bit set include OLE1 objects, static objects, and links.

OLEMISC_CANLINKBYOLE1

This object can be linked to by OLE 1 containers. This bit is used in the dwStatus member of the OBJECTDESCRIPTOR structure transferred with the Object and Link Source Descriptor formats. An object can be linked to by OLE 1 containers if it is an untitled document, a file, or a selection of data within a file. Embedded objects or pseudo-objects that are contained within an embedded object cannot be linked to by OLE 1 containers (i.e., OLE 1 containers cannot link to link sources that, when bound, require more than one object server to be run.

OLEMISC_ISLINKOBJECT

This object is a link object. This bit is significant to OLE 1 and is set by the OLE 2 link object; object applications have no need to set this bit.

OLEMISC_INSIDEOUT

This object is capable of activating in-place, without requiring installation of menus and toolbars to run. Several such objects can be active concurrently. Some containers, such as forms, may choose to activate such objects automatically.

OLEMISC_ACTIVATEWHENVISIBLE

This bit is set only when OLEMISC_INSIDEOUT is set, and indicates that this object prefers to be activated whenever it is visible. Some containers may always ignore this hint.

OLEMISC_RENDERINGISDEVICEINDEPENDENT

This object does not pay any attention to target devices. Its presention data will be the same in all cases.

OLEMISC_INVISIBLEATRUNTIME

This value is used with controls. It indicates that the control has no run-time user interface, but that it should be visible at design time. For example, a timer control that fires a specific event periodically would not show itself at run time, but it needs a design-time user interface so a form designer can set the event period and other properties.

OLEMISC_ALWAYSRUN

This value is used with controls. It tells the container that this control always wants to be running. As a result, the container should call OleRun when loading or creating the object.

OLEMISC_ACTSLIKEBUTTON

This value is used with controls. It indicates that the control is buttonlike in that it understands and obeys the container’s DisplayAsDefault ambient property.

OLEMISC_ACTSLIKELABEL

This value is used with controls. It marks the control as a label for whatever control comes after it in the form’s ordering. Pressing a mnemonic key for a label control activates the control after it.

OLEMISC_NOUIACTIVATE

This value is used with controls. It indicates that the control has no UI active state, meaning that it requires no in-place tools, no shared menu, and no accelerators. It also means that the control never needs the focus.

OLEMISC_ALIGNABLE

This value is used with controls. It indicates that the control understands how to align itself within its display rectangle, according to alignment properties such as left, center, and right.

OLEMISC_SIMPLEFRAME

This value is used with controls. It indicates that the control is a simple grouping of other controls and does little more than pass Windows messages to the control container managing the form. Controls of this sort require the implementation of ISimpleFrameSite on the container’s site.

OLEMISC_SETCLIENTSITEFIRST

This value is used with controls. It indicates that the control wants to use IOleObject::SetClientSite as its initialization function, even before a call such as IPersistStreamInit::InitNew or IPersistStorage::InitNew. This allows the control to access a container’s ambient properties before loading information from persistent storage. Note that the current implementations of OleCreate, OleCreateFromData, OleCreateFromFile, OleLoad, and the default handler do not understand this value. Control containers that wish to honor this value must currently implement their own versions of these functions in order to establish the correct initialization sequence for the control.

OLEMISC_IMEMODE

Obsolete. A control that works with an Input Method Editor (IME) system component can control the state of the IME through the IMEMode property rather than using this value in the OLEMISC enumeration. You can use an IME component to enter information in Asian character sets with a regular keyboard. A Japanese IME, for example, allows you to type a word such as “sushi,” on a regular keyboard and when you hit the spacebar, the IME component converts that word to appropriate kanji or proposes possible choices. The OLEMISC_IMEMODE value was previously used to mark a control as capable of controlling an IME mode system component.

OLEMISC_IGNOREACTIVATEWHENVISIBLE

For new ActiveX controls to work in an older container, the control may need to have the OLEMISC_ACTIVATEWHENVISIBLE value set. However, in a newer container that understands and uses IPointerInactive, the control does not wish to be in-place activated when it becomes visible. To allow the control to work in both kinds of containers, the control can set this value. Then, the container ignores OLEMISC_ACTIVATEWHENVISIBLE and does not in-place activate the control when it becomes visible.

OLEMISC_WANTSTOMENUMERGE

A control that can merge its menu with its container sets this value.

OLEMISC_SUPPORTSMULTILEVELUNDO

A control that supports multi-level undo sets this value.

See Also

IOleObject::GetMiscStatus, OBJECTDESCRIPTOR


OLERENDER

The OLERENDER enumeration constants are used in the various object creation functions to indicate the type of caching requested for the newly created object.

typedef enum tagOLERENDER

{

    OLERENDER_NONE   = 0;

    OLERENDER_DRAW   = 1;

    OLERENDER_FORMAT = 2;

    OLERENDER_ASIS   = 3

} OLERENDER;

Elements

OLERENDER_NONE

The client is not requesting any locally cached drawing or data retrieval capabilities in the object. The pFormatEtc parameter of the calls is ignored when this value is specified for the renderopts parameter.

OLERENDER_DRAW

The client will draw the content of the object on the screen (a NULL target device) using IViewObject:Draw. The object itself determines the data formats that need to be cached. With this render option, only the ptd and dwAspect members of pFormatEtc are significant, since the object may cache things differently depending on the parameter values. However, pFormatEtc can legally be NULL here, in which case the object is to assume the display target device and the DVASPECT_CONTENT aspect.

OLERENDER_FORMAT

The client will pull one format from the object using IDataObject::GetData(). The format of the data to be cached is passed in pFormatEtc, which may not in this case be NULL.

OLERENDER_ASIS

The client is not requesting any locally cached drawing or data retrieval capabilities in the object. pFormatEtc is ignored for this option. The difference between this and the OLERENDER_FORMAT value is important in such functions as OleCreateFromData() and OleCreateLinkFromData().

See Also

OleCreate, OleCreateFromData, OleCreateFromFile, OleCreateLink, OleCreateLinkFromData, OleCreateLinkToFile, OleCreateStaticFromData


OLEUIPASTEFLAG

This enumeration is used to indicate the user options that are available to the user when pasting this format, and within which group or list of choices (Paste, Paste Link, etc.) this entry is to be available. OLEUIPASTEFLAG is used by the OLEUIPASTEENTRY structure.

typedef enum tagOLEUIPASTEFLAG

{

    OLEUIPASTE_ENABLEICON    = 2048,

    OLEUIPASTE_PASTEONLY     = 0,

    OLEUIPASTE_PASTE         = 512,

    OLEUIPASTE_LINKANYTYPE   = 1024,

    OLEUIPASTE_LINKTYPE1     = 1,

    OLEUIPASTE_LINKTYPE2     = 2,

    OLEUIPASTE_LINKTYPE3     = 4,

    OLEUIPASTE_LINKTYPE4     = 8,

    OLEUIPASTE_LINKTYPE5     = 16,

    OLEUIPASTE_LINKTYPE6     = 32,

    OLEUIPASTE_LINKTYPE7     = 64,

    OLEUIPASTE_LINKTYPE8     = 128

} OLEUIPASTEFLAG;

Elements

OLEUIPASTE_ENABLEICON

If the container does not specify this flag for the entry in the OLEUIPASTEENTRYarray passed as input to OleUIPasteSpecial, the DisplayAsIcon button will be unchecked and disabled when the user selects the format that corresponds to the entry.

OLEUIPASTE_PASTEONLY

The entry in the OLEUIPASTEENTRY array is valid for pasting only.

OLEUIPASTE_PASTE

The entry in the OLEUIPASTEENTRYarray is valid for pasting. It may also be valid for linking if any of the following linking flags are specified. If it is valid for linking, then the following flags indicate which link types are acceptable by OR’ing together the appropriate OLEUIPASTE_LINKTYPE<#> values. These values correspond as follows to the array of link types passed to OleUIPasteSpecial:

OLEUIPASTE_LINKTYPE1=arrLinkTypes[0]
OLEUIPASTE_LINKTYPE2=arrLinkTypes[1]
OLEUIPASTE_LINKTYPE3=arrLinkTypes[2]
OLEUIPASTE_LINKTYPE4=arrLinkTypes[3]
OLEUIPASTE_LINKTYPE5=arrLinkTypes[4]
OLEUIPASTE_LINKTYPE6=arrLinkTypes[5]
OLEUIPASTE_LINKTYPE7=arrLinkTypes[6]
OLEUIPASTE_LINKTYPE8=arrLinkTypes[7]

where,

UINT arrLinkTypes[8] is an array of registered clipboard formats for linking. A maximum of 8 link types is allowed.


OLEUPDATE

The OLEUPDATE enumeration constants are used to indicate whether the linked object updates the cached data for the linked object automatically or only when the container calls either the IOleObject::Update or IOleLink::Update methods. The constants are used in the IOleLink interface.

typedef enum tagOLEUPDATE

{

    OLEUPDATE_ALWAYS    = 1;

    OLEUPDATE_ONCALL    = 3

} OLEUPDATE;

typedef OLEUPDATE *LPOLEUPDATE;

Elements

OLEUPDATE_ALWAYS

Update the link object whenever possible, this option corresponds to the Automatic update option in the Links dialog box.

OLEUPDATE_ONCALL

Update the link object only when IOleObject::Update or IOleLink::Update is called, this option corresponds to the Manual update option in the Links dialog box.

See Also

IOleLink::SetUpdateOptions, IOleLink::GetUpdateOptions


OLEVERBATTRIB

The OLEVERBATTRIB enumeration constants are used in the OLEVERB structure to describe the attributes of a specified verb for an object. Values are used in the enumerator (which supports the IEnumOLEVERB interface) that is created by a call to IOleObject::EnumVerbs.

typedef enum tagOLEVERBATTRIB

{

    OLEVERBATTRIB_NEVERDIRTIES       = 1,

    OLEVERBATTRIB_ONCONTAINERMENU    = 2

} OLEVERBATTRIB;

Elements

OLEVERBATTRIB_NEVERDIRTIES

Executing this verb will not cause the object to become dirty and is therefore in need of saving to persistent storage.

OLEVERBATTRIB_ONCONTAINERMENU

Indicates a verb that should appear in the container’s menu of verbs for this object. OLEIVERB_HIDE, OLEIVERB_SHOW, and OLEIVERB_OPEN never have this value set.

See Also

IOleObject::EnumVerbs, IEnumOLEVERB, OLEVERB


OLEWHICHMK

The OLEWHICHMK enumeration constants indicate which part of an object’s moniker is being set or retrieved. These constants are used in the IOleObject and IOleClientSite interfaces.

typedef enum tagOLEWHICHMK

{

    OLEWHICHMK_CONTAINER    = 1,

    OLEWHICHMK_OBJREL       = 2,

    OLEWHICHMK_OBJFULL      = 3

} OLEWHICHMK;

Elements

OLEWHICHMK_CONTAINER

The moniker of the object’s container. Typically, this is a file moniker. This moniker is not persistently stored inside the object, since the container can be renamed even while the object is not loaded.

OLEWHICHMK_OBJREL

The moniker of the object relative to its container. Typically, this is an item moniker, and it is part of the persistent state of the object. If this moniker is composed on to the end of the container’s moniker, the resulting moniker is the full moniker of the object.

OLEWHICHMK_OBJFULL

The full moniker of the object. Binding to this moniker results in a connection to the object. This moniker is not persistently stored inside the object, since the container can be renamed even while the object is not loaded.

See Also

IOleClientSite::GetMoniker, IOleObject::GetMoniker, IOleObject::SetMoniker


PENDINGMSG

The PENDINGMSG enumeration constants are return values of IMessageFilter::MessagePending.

Defined in the IMessageFilter interface (msgflt.idl).

typedef enum tagPENDINGMSG

{

    PENDINGMSG_CANCELCALL        = 0,

    PENDINGMSG_WAITNOPROCESS     = 1,

    PENDINGMSG_WAITDEFPROCESS    = 2

} PENDINGMSG;

Elements

PENDINGMSG_CANCELCALL

Cancel the outgoing call.

PENDINGMSG_WAITNOPROCESS

Wait for the return and don’t dispatch the message.

PENDINGMSG_WAITDEFPROCESS

Wait and dispatch the message.

See Also

IMessageFilter::MessagePending


PENDINGTYPE

The PENDINGTYPE enumeration constants indicate the level of nesting in the IMessageFilter::MessagePending method.

typedef enum tagPENDINGTYPE

{

    PENDINGTYPE_TOPLEVEL    = 1,

    PENDINGTYPE_NESTED      = 2

} PENDINGTYPE;

Elements

PENDINGTYPE_TOPLEVEL

Top-level call.

PENDINGTYPE_NESTED

Nested call.

See Also

IMessageFilter::MessagePending


PICTURE

The PICTURE enumeration values describe attributes of a picture object as returned through the IPicture::get_Attributes method.

typedef enum tagPICTURE

{

    PICTURE_SCALABLE       = 0x00000001,

    PICTURE_TRANSPARENT    = 0x00000002

} PICTURE;

Elements

PICTURE_SCALABLE

The picture object is scalable, such that it can be redrawn with a different size than was used to create the picture originally. Metafile-based pictures are considered scalable; icon and bitmap pictures, while they can be scaled, do not express this attribute because both involve bitmap stretching instead of true scaling.

PICTURE_TRANSPARENT

The picture object contains an image that has transparent areas, such that drawing the picture will not necessarily fill in all the spaces in the rectangle it occupies. Metafile and icon pictures have this attribute; bitmap pictures do not.

See Also

IPicture::get_Attributes


PICTYPE

The PICTYPE enumeration values are used to describe the type of a picture object as returned by IPicture::get_Type, as well as to describe the type of picture in the picType field of the PICTDESC structure that is passed to OleCreatePictureIndirect.

typedef enum tagPICTYPE

{

    PICTYPE_UNINITIALIZED    = -1,

    PICTYPE_NONE             = 0,

    PICTYPE_BITMAP           = 1,

    PICTYPE_METAFILE         = 2,

    PICTYPE_ICON             = 3

    PICTYPE_ENHMETAFILE      = 4

} PICTYPE;

Elements

PICTYPE_UNINITIALIZED

The picture object is currently uninitialized. This value is only valid as a return value from IPicture::get_Type and is not valid with the PICTDESC structure.

PICTYPE_NONE

A new picture object is to be created without an initialized state. This value is valid only in the PICTDESC structure.

PICTYPE_BITMAP

The picture type is a bitmap. When this value occurs in the PICTDESC structure, it means that the bmp field of that structure contains the relevant initialization parameters.

PICTYPE_METAFILE

The picture type is a metafile. When this value occurs in the PICTDESC structure, it means that the wmf field of that structure contains the relevant initialization parameters.

PICTYPE_ICON

The picture type is an icon. When this value occurs in the PICTDESC structure, it means that the icon field of that structure contains the relevant initialization parameters.

PICTYPE_ENHMETAFILE

The picture type is a Win32-enhanced metafile. When this value occurs in the PICTDESC structure, it means that the emf field of that structure contains the relevant initialization parameters.

See Also

IPicture::get_Type, OleCreatePictureIndirect, PICTDESC


POINTERINACTIVE

The POINTERINACTIVE enumeration values indicate the activation policy of the object and are used in the IPointerInactive::GetActivationPolicy method.

typedef enum tagPOINTERINACTIVE

{

    POINTERINACTIVE_ACTIVATEONENTRY      = 1,

    POINTERINACTIVE_DEACTIVATEONLEAVE    = 2,

    POINTERINACTIVE_ACTIVATEONDRAG       = 4

} POINTERINACTIVE;

Elements

POINTERINACTIVE_ACTIVATEONENTRY

The object should be in-place activated when the mouse enters it during a mouse move operation.

POINTERINACTIVE_DEACTIVATEONLEAVE

The object should be deactivated when the mouse leaves the object during a mouse move operation.

POINTERINACTIVE_ACTIVATEONDRAG

The object should be in-place activated when the mouse is dragged over it during a drag and drop operation.

Remarks

For more information on using the POINTERINACTIVE_ACTIVATEONENTRY and POINTERINACTIVE_DEACTIVATEONLEAVE values, see the IPointerInactive::GetActivationPolicy method.

The POINTERINACTIVE_ACTIVATEONDRAG value can be used to support drag and drop operations on an inactive object. An inactive object has no window to register itself as a potential drop target. Most containers ignore embedded, inactive objects as drop targets because of the overhead associated with activating them.

As an alternative to activating an object when the mouse pointer is over it during a drag and drop operation, the container can first QueryInterface to determine if the inactive object supports IPointerInactive. Then, if the object does not support IPointerInactive, the container can assume that it is not a drop target. If the object does support IPointerInactive, the container calls the IPointerInactive::GetActivationPolicy method. If the POINTERINACTIVE_ACTIVATEONDRAG value is set, the container activates the object in-place so the object can register its own IDropTarget interface.

The container is processing its own IDropTarget::DragOver method when all these actions occur. To complete that method, the container returns DROPEFFECT_NONE for the pdwEffect parameter. Then, the drag and drop operation continues by calling the container’s IDropTarget::DragLeave and then calling the object’s IDropTarget::DragEnter.

Note  For windowless OLE objects this mechanism is slightly different. See IOleInPlaceSiteWindowless for more information on drag and drop operations for windowless objects.

If the drop occurs on the embedded object, the object is UI-activated and will get UI-deactivated when the focus changes again. If the drop does not occur on the object, the container should deactivate the object the next time it gets a call to its own IDropTarget::DragEnter. It is possible for the drop to occur on a third active object without an intervening call to the container’s IDropTarget::DragEnter. In this case, the container should try to deactivate the object as soon as it can, for example, when it UI-activates another object.

See Also

IDropTarget, IPointerInactive::GetActivationPolicy


PROPSETFLAG

The PROPSETFLAG enumeration values define characteristics of a property set. The values are used in the IPropertySetStorage::Create method.

typedef enum PROPSETFLAG {

    PROPSETFLAG_DEFAULT      = 0,

    PROPSETFLAG_NONSIMPLE    = 1,

    PROPSETFLAG_ANSI         = 2,

    } PROPSETFLAG

Members

PROPSETFLAG_NONSIMPLE

If specified, storage-valued and stream-valued properties are permitted in the newly created set. Otherwise, they are not permitted. In the compound file implementation, property sets may be transacted only if PROPSETFLAG_NONSIMPLE is specified.

PROPSETFLAG_ANSI

If specified, all string values in the property set that are not explicitly Unicode (those other than VT_LPWSTR) are stored with the current system ANSI code page (see the Win32 function GetACP). Use of this flag is not recommended, as described in the following Remarks section.

If this flag is absent, string values in the new property set are stored in Unicode. The degree of control afforded by this flag is necessary so clients using the property-related interfaces can interoperate well with standard property sets such as the OLE2 summary information, which may exist in the ANSI code page.

Remarks

These values can be set and checked for using bitwise operations, permitting up to four possible combinations: non-simple Unicode, simple Unicode, non-simple ANSI, and simple ANSI.

It is recommended that property sets be created as Unicode, by not setting the PROPSETFLAG_ANSI flag in the grfFlags parameter of IPropertySetStorage::Create. It is also recommended that you avoid using VT_LPSTR values, and use VT_LPWSTR values instead. When the property set code page is Unicode, VT_LPSTR string values are converted to Unicode when stored, and back to multibyte string values when retrieved. When the code page of the property set is not Unicode, property names, VT_BSTR strings, and non-simple property values are converted to multibyte strings when stored, and converted back to Unicode when retrieved, all using the current system ANSI code page.

See Also

IPropertySetStorage::Create, IPropertySetStorage::Open


QACONTAINERFLAGS

The QACONTAINERFLAGS enumeration value indicates ambient properties supplied by the container. It is used in the dwAmbientFlags member of the QACONTAINER structure.

typedef enum tagQACONTAINERFLAGS

{

    QACONTAINER_SHOWHATCHING       = 0x1,

    QACONTAINER_SHOWGRABHANDLES    = 0x2,

    QACONTAINER_USERMODE           = 0x4,

    QACONTAINER_DISPLAYASDEFAULT   = 0x8,

    QACONTAINER_UIDEAD             = 0x10,

    QACONTAINER_AUTOCLIP           = 0x20,

    QACONTAINER_MESSAGEREFLECT     = 0x40,

    QACONTAINER_SUPPORTSMNEMONICS  = 0x80

} QACONTAINERFLAGS;

Elements

QACONTAINER_SHOWHATCHING

Specifies the ShowHatching ambient property, which has a standard ambient DISPID of -712.

QACONTAINER_SHOWGRABHANDLES

Specifies the ShowGrabHandles ambient property, which has a standard ambient DISPID of -711.

QACONTAINER_USERMODE

Specifies the UserMode ambient property, which has a standard ambient DISPID of -709.

QACONTAINER_DISPLAYASDEFAULT

Specifies the DisplayAsDefault ambient property, which has a standard ambient DISPID of -713.

QACONTAINER_UIDEAD

Specifies the UIDead ambient property, which has a standard ambient DISPID of -710.

QACONTAINER_AUTOCLIP

Specifies the AutoClip ambient property, which has a standard ambient DISPID of -715.

QACONTAINER_MESSAGEREFLECT

Specifies the MessageReflect ambient property, which has a standard ambient DISPID of -706.

QACONTAINER_SUPPORTSMNEMONICS

Specifies the SupportsMnemonics ambient property, which has a standard ambient DISPID of -714.

Remarks

See the ActiveX Controls chapter in the OLE Programmer’s Guide for further information on standard ambient properties.

See Also

QACONTAINER


REGCLS

The REGCLS enumeration defines flags used in CoRegisterClassObject to control the type of connections to the class object. It is defined as follows:

typedef enum tagREGCLS

{

    REGCLS_SINGLEUSE         = 0,

    REGCLS_MULTIPLEUSE       = 1,

    REGCLS_MULTI_SEPARATE    = 2,

} REGCLS;

Elements

REGCLS_SINGLEUSE

Once an application has connected to the class object with CoGetClassObject, the class object is removed from public view so that no other applications can connect to it. This flag is commonly used for single document interface (SDI) applications. Specifying this flag does not affect the responsibility of the object application to call CoRevokeClassObject; it must always call CoRevokeClassObject when it is finished with an object class.

REGCLS_MULTIPLEUSE

Multiple applications can connect to the class object through calls to CoGetClassObject.

REGCLS_MULTI_SEPARATE

Similar to REGCLS_MULTIPLEUSE, except that REGCLS_MULTI_SEPARATE does not automatically register the class object as CLSCTX_INPROC_SERVER for a local server. Instead, it provides separate control over each context. When a class is registered this way, if that server tries to bind to an object with its own class identifier, it will start another copy of the server.

Remarks

In CoRegisterClassObject, members of both the REGCLS and the CLSCTX enumerations, taken together, determine how the class object is registered.

The following table summarizes the allowable flag combinations and the object registrations affected by the combinations.

	REGCLS_ SINGLEUSE	REGCLS_ MULTIPLEUSE	REGCLS_ MULTI_ SEPARATE	Other
CLSCTX_ INPROC_ SERVER	Error	Inproc	Inproc	Error
CLSCTX_ LOCAL_ SERVER	Local	Inproc/local	Local	Error
Both of the above	Error	Inproc/local	Inproc/local	Error
Other	Error	Error	Error	Error
REGCLS_MULTIPLEUSE in combination with CLSCTX_LOCAL_SERVER automatically registers the class object as an in-process server (CLSCTX_INPROC_SERVER). In contrast, registering a class object as a local server and specifying REGCLS_MULTIPLE_SEPARATE does not register the class object as an in-process server (registers the object with the CLSCTX_LOCAL_SERVER flag, but does not automatically add the CLSCTX_INPROC_SERVER flag, as is the case when you specify the REGCLS_MULTIPLEUSE flag. This distinction is important in applications that are both OLE containers and OLE embeddings, allowing a container/server to be inserted into itself.

In general, the following two registrations have the same effect -- they register class objects as both multiple-use and as in-process servers:

CLSCTX_LOCAL_SERVER, REGCLS_MULTIPLEUSE

(CLSCTX_INPROC_SERVER|CLSCTX_LOCAL_SERVER), REGCLS_MULTI_SEPARATE

The following registers the class object only as a multiple-use local server:

CLSCTX_LOCAL_SERVER, REGCLS_MULTI_SEPARATE

See Also

CoGetClassObject, CoRegisterClassObject, CoRevokeClassObject, DllGetClassObject


RPC_C_AUTHN_xxx

These values, along with the RPC_C_AUTHZ_xxx values, are assigned to the SOLE_AUTHENICATION_SERVICE structure, which is retrieved by the CoQueryAuthenticationServices function, and passed in to the CoInitializeSecurity function.

Note  Only RPC_C_AUTHN_WINNT is supported in NT 4.0.  The others may be supported with software purchased from other companies.

Values

RPC_C_AUTHN_NONE

No authentication.

RPC_C_AUTHN_DCE_PRIVATE

DCE private key authentication.

RPC_C_AUTHN_DCE_PUBLIC

DCE public key authentication.

RPC_C_AUTHN_DEC_PUBLIC

DEC public key authentication (reserved for future use).

RPC_C_AUTHN_WINNT

NT LM SSP (NT Security Service).

RPC_C_AUTHN_DEFAULT

The system default authentication service. Windows NT 4.0 defaults to DCE private key authentication (RPC_C_AUTHN_DCE_PRIVATE).

See Also

CoInitializeSecurity, CoQueryAuthenticationServices


RPC_C_AUTHN_LEVEL_xxx

Used in the security functions and interfaces to specify the authentication level.

Values

RPC_C_AUTHN_LEVEL_NONE

Performs no authentication.

RPC_C_AUTHN_LEVEL_CONNECT

Authenticates only when the client establishes a relationship with the server. Datagram transports always use RPC_AUTHN_LEVEL_PKT instead.

RPC_C_AUTHN_LEVEL_CALL

Authenticates only at the beginning of each remote procedure call when the server receives the request. Datagram transports use RPC_C_AUTHN_LEVEL_PKT instead.

RPC_C_AUTHN_LEVEL_PKT

Authenticates that all data received is from the expected client.

RPC_C_AUTHN_LEVEL_PKT_INTEGRITY

Authenticates and verifies that none of the data transferred between client and server has been modified.

RPC_C_AUTHN_LEVEL_PKT_PRIVACY

Authenticates all previous levels and encrypts the argument value of each remote procedure call.

Windows95:  While Windows95 can make calls at any level, it can only receive calls at NONE or CONNECT.  This applies to RPC today, although Windows95 does not support distributed COM at this time.

See Also

IClientSecurity, IServerSecurity


RPC_C_AUTHZ_xxx

These values define what the server authorizes, and are used by methods of the IClientSecurity interface. Along with the RPC_C_AUTHN_xxx values, these are the values assigned to the SOLE_AUTHENTICATION_SERVICE structure, which is retrieved by the CoQueryAuthenticationServices function, and passed in to the CoInitializeSecurity function.

Values

RPC_C_AUTHZ_NONE

Server performs no authorization.

RPC_C_AUTHZ_NAME

Server performs authorization based on the client’s principal name.

RPC_C_AUTHZ_DCE

Server performs authorization checking using the client's DCE privilege attribute certificate (PAC) information, which is sent to the server with each remote procedure call made using the binding handle. Generally, access is checked against DCE access control lists (ACLs).

See Also

SOLE_AUTHENTICATION_SERVICE


RPC_C_IMP_LEVEL_xxx

Used in the security functions and interfaces to specify the authentication level.

Values

RPC_C_IMP_LEVEL_ANONYMOUS

(Not supported in this release.) The client is anonymous to the server. The server process cannot obtain identification information about the client and it cannot impersonate the client.

RPC_C_IMP_LEVEL_IDENTIFY

The server can obtain the client’s identity. The server can impersonate the client for ACL checking, but cannot access system objects as the client. This information is obtained when the connection is established, not on every call.

Note  GetUserName will fail while impersonating at identify level.  The workaround is to impersonate, OpenThreadToken, revert, call GetTokenInformation, and finally, call LookupAccountSid.

RPC_C_IMP_LEVEL_IMPERSONATE

The server process can impersonate the client's security context while acting on behalf of the client. This information is obtained when the connection is established, not on every call.

RPC_C_IMP_LEVEL_DELEGATE

(Not supported in this release.) The server process can impersonate the client's security context while acting on behalf of the client. The server process can also make outgoing calls to other servers while acting on behalf of the client. This information is obtained when the connection is established, not on every call.

Comments

Only the RPC_C_IMP_LEVEL_IDENTIFY and RPC_C_IMP_LEVEL_IMPERSONATE levels are supported in NT 4.0.

See Also

CoInitializeSecurity


SERVERCALL

The SERVERCALL enumeration constants indicate the status of server call — returned by IMessageFilter::HandleInComingCall and passed to IMessageFilter::RetryRejectedCall.

Defined in the IMessageFilter interface (msgflt.idl).

typedef enum tagSERVERCALL

{

    SERVERCALL_ISHANDLED     = 0,

    SERVERCALL_REJECTED      = 1,

    SERVERCALL_RETRYLATER    = 2

} SERVERCALL;

Elements

SERVERCALL_ISHANDLED

The object may be able to process the call.

SERVERCALL_REJECTED

The object cannot handle the call due to an unforeseen problem, such as network unavailability.

SERVERCALL_RETRYLATER

The object cannot handle the call at this time. For example, an application might return this value when it is in a user-controlled modal state.

See Also

IMessageFilter::HandleInComingCall, IMessageFilter::RetryRejectedCall


STATFLAG

The STATFLAG enumeration values indicate whether the method should try to return a name in the pwcsName member of the STATSTG structure. The values are used in the ILockBytes::Stat, IStorage::Stat, and IStream::Stat methods to save memory when the pwcsName member is not needed.

Defined in the IOLETypes pseudo-interface (oletyp.idl).

typedef enum tagSTATFLAG

{

    STATFLAG_DEFAULT    = 0,

    STATFLAG_NONAME     = 1

} STATFLAG;

Elements

STATFLAG_DEFAULT

Requests that the statistics include the pwcsName member of the STATSTG structure.

STATFLAG_NONAME

Requests that the statistics not include the pwcsName member of the STATSTG structure. If the name is omitted, there is no need for the Stat methods to allocate and free memory for the string value for the name and the method can save an Alloc and Free operation.

See Also

ILockBytes::Stat, IStorage::Stat, IStream::Stat


STATSTATE

The STATSTATE enumeration values indicate state information about the storage object and are used as a mask. The values are used in the IStorage::SetStateBits method.

typedef enum tagSTATSTATE

{

    STATSTATE_DOC            = 1,

    STATSTATE_CONVERT        = 2,

    STATSTATE_FILESTGSAME    = 4

} STATSTATE;

Elements

STATSTATE_DOC

The storage object is a document file. This bit is set on the root storage object as part of a normal File/Save sequence. With nested storage objects, the application manages the storage objects and sets or clears this bit as appropriate. If the nested object is an embedded object, this bit can be ignored. It is cleared in a newly created storage object. However, some applications might use this bit to enable editing an embedded storage object without first copying the object to the file system. For example, a mail application might set this bit for attachments so the attachments can be edited without copying them first to a file.

STATSTATE_CONVERT

A convert operation was done on this storage object while it was in a passive state.

STATSTATE_FILESTGSAME

The embedded object and document representations for the storage object are the same. Thus, the storage object can be saved in a document file simply by copying the storage object bits.

See Also

IStorage::SetStateBits


STGC

The STGC enumeration constants specify the conditions for performing the commit operation in the IStorage::Commit and IStream::Commit methods.

Defined in the IOLETypes pseudo-interface (oletyp.idl).

typedef enum tagSTGC

{

    STGC_DEFAULT                               = 0,

    STGC_OVERWRITE                             = 1,

    STGC_ONLYIFCURRENT                         = 2,

    STGC_DANGEROUSLYCOMMITMERELYTODISKCACHE    = 4

} STGC;

Elements

STGC_DEFAULT

None of the other values apply. You can specify this condition or some combination of the other three. You would use this value mainly to make your code more readable.

STGC_OVERWRITE

The commit operation can overwrite existing data to reduce overall space requirements. This value is not recommended for typical usage because it is not as robust as the default case. In this case, it is possible for the commit to fail after the old data is overwritten but before the new data is completely committed. Then, neither the old version nor the new version of the storage object will be intact.

You can use this value in cases where:

•	the user has indicated a willingness to risk losing the data

•	the low memory save sequence will be used to safely save the storage object to a smaller file

•	a previous commit returned STG_E_MEDIUMFULL but overwriting the existing data would provide enough space to commit changes to the storage object

Note that the commit operation checks for adequate space before any overwriting occurs. Thus, even with this value specified, if the commit operation fails due to space requirements, the old data will remain safe. The case where data loss can occur is when the commit operation fails due to some reason other than lack of space and the STGC_OVERWRITE value was specified.

STGC_ONLYIFCURRENT

Prevents multiple users of a storage object from overwriting one another’s changes. The commit operation occurs only if there have been no changes to the saved storage object since the user most recently opened the storage object. Thus, the saved version of the storage object is the same version that the user has been editing. If other users have changed the storage object, the commit operation fails and returns the STG_E_NOTCURRENT value. You can override this behavior by calling the Commit method again using the STGC_DEFAULT value.

STGC_DANGEROUSLYCOMMITMERELYTODISKCACHE

Commits the changes to a write-behind disk cache, but does not save the cache to the disk. In a write-behind disk cache, the operation that writes to disk actually writes to a disk cache, thus increasing performance. The cache is eventually written to the disk, but usually not until after the write operation has already returned. The performance increase comes at the expense of an increased risk of losing data if a problem occurs before the cache is saved and the data in the cache is lost.

If you do not specify this value, then committing changes to root-level storage objects is robust even if a disk cache is used. The two-phase commit process ensures that data is stored on the disk and not just to the disk cache.

Remarks

You can specify STGC_DEFAULT or some combination of the other three values. Typically, you would use STGC_ONLYIFCURRENT to protect the storage object in cases where more than one user can edit the object simultaneously.

See Also

IPropertyStorage, IStorage, IStream


STGFMT

The STGFMT enumeration values indicate the format of a storage object and are used in the STATSTG structure and in the StgCreateDocFile and StgIsStorageFile functions.

typedef enum tagSTGFMT

{

    STGFMT_DOCUMENT     = 0,

    STGFMT_DIRECTORY    = 1,

    STGFMT_CATALOG      = 2,

    STGFMT_FILE         = 3

} STGFMT;

Elements

STGFMT_DOCUMENT

Indicates a document format.

STGFMT_DIRECTORY

Indicates a directory format.

STGFMT_CATALOG

Indicates a catalog format.

STGFMT_FILE

Indicates a file format.

See Also

STATSTG, StgCreateDocfile, StgIsStorageFile


STGM

The STGM enumeration values are used in the storage and stream interfaces to indicate the conditions for creating and deleting the object and access modes for the object.

The STGM values are used in the IStorage and IStream interfaces, and in the StgCreateDocfile and StgCreateDocfileOnILockBytes functions to indicate the conditions for creating and deleting the object and access modes for the object.

STGM values are as follows:

STGM_DIRECT	0x00000000L
STGM_TRANSACTED	0x00010000L
STGM_SIMPLE	0x08000000L
STGM_READ	0x00000000L
STGM_WRITE	0x00000001L
STGM_READWRITE	0x00000002L
STGM_SHARE_DENY_NONE	0x00000040L
STGM_SHARE_DENY_READ	0x00000030L
STGM_SHARE_DENY_WRITE	0x00000020L
STGM_SHARE_EXCLUSIVE	0x00000010L
STGM_PRIORITY	0x00040000L
STGM_DELETEONRELEASE	0x04000000L
STGM_CREATE	0x00001000L
STGM_CONVERT	0x00020000L
STGM_FAILIFTHERE	0x00000000L
STGM_NOSCRATCH	0x00100000L
Elements

STGM_DIRECT. STGM_TRANSACTED, STGM_SIMPLE group:

STGM_DIRECT

In direct mode, each change to a storage element is written as it occurs. This is the default.

STGM_TRANSACTED

In transacted mode, changes are buffered and are written only if an explicit commit operation is called. The changes can be ignored by calling the Revert method in the IStream or IStorage interfaces. The OLE compound file implementation does not support transacted streams, which means that streams can be opened only in direct mode, and you cannot revert changes to them. Transacted storages are, however, supported.

STGM_SIMPLE

STGM_SIMPLE is a mode that provides a much faster implementation of a compound file in a limited, but frequently used case. It is described in detail in the following Remarks section.

STGM_READ, STGM_WRITE, STGM_READWRITE group:

STGM_READ

For stream objects, STGM_READ allows you to call the IStream::Read method. For storage objects, you can enumerate the storage elements and open them for reading.

STGM_WRITE

STGM_WRITE lets you save changes to the object.

STGM_READWRITE

STGM_READWRITE is the combination of STGM_READ and STGM_WRITE.

STGM_SHARE_* group:

STGM_SHARE_DENY_NONE

Specifies that subsequent openings of the object are not denied read or write access.

STGM_SHARE_DENY_READ

Prevents others from subsequently opening the object in STGM_READ mode. It is typically used on a root storage object.

STGM_SHARE_DENY_WRITE

Prevents others from subsequently opening the object in STGM_WRITE mode. This value is typically used to prevent unnecessary copies made of an object opened by multiple users. If this value is not specified, a snapshot is made, independent of whether there are subsequent opens or not. Thus, you can improve performance by specifying this value.

STGM_SHARE_EXCLUSIVE

The combination of STGM_SHARE_DENY_READ and STGM_SHARE_DENY_WRITE.

STGM_PRIORITY

STGM_PRIORITY

Opens the storage object with exclusive access to the most recently committed version. Thus, other users cannot commit changes to the object while you have it open in priority mode. You gain performance benefits for copy operations, but you prevent others from committing changes. So, you should limit the time you keep objects open in priority mode. You must specify STGM_DIRECT and STGM_READ with priority mode.

STGM_DELETEONRELEASE

STGM_DELETEONRELEASE

Indicates that the underlying file is to be automatically destroyed when the root storage object is released. This capability is most useful for creating temporary files.

STGM_CREATE, STGM_CONVERT, STGM_FAILIFTHERE Group

STGM_CREATE

Indicates that an existing storage object or stream should be removed before the new one replaces it. A new object is created when this flag is specified, only if the existing object has been successfully removed.

This flag is used in three situations:

•	when you are trying to create a storage object on disk but a file of that name already exists

•	when you are trying to create a stream inside a storage object but a stream with the specified name already exists

•	when you are creating a byte array object but one with the specified name already exists

STGM_CONVERT

Creates the new object while preserving existing data in a stream named CONTENTS. In the case of a storage object or a byte array, the old data is flattened to a stream regardless of whether the existing file or byte array currently contains a layered storage object.

STGM_FAILIFTHERE

Causes the create operation to fail if an existing object with the specified name exists. In this case, STG_E_FILEALREADYEXISTS is returned. STGM_FAILIFTHERE applies to both storage objects and streams.

STGM_NOSCRATCH

Windows95 only: In transacted mode, a scratch file is usually used to save until the commit operation. Specifying STGM_NOSCRATCH permits the unused portion of the original file to be used as scratch space. This does not affect the data in the original file, and is a much more efficient use of memory.

Remarks

You can combine these flags but you can only choose one flag from each group of related flags. Groups are indicated under the headings in the previous section.

The STGM_SIMPLE flag is applicable only when combined with:

STGM_CREATE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

Note that direct mode is implied by the absence of STGM_TRANSACTED.

This mode is useful for applications that perform complete save operations. It has the following constraints:

1.	There is no support for substorages.

2.	Access to streams follows a linear pattern. Once a stream is released, that stream cannot be opened for read/write operations again. The IStorage::OpenStream method is not supported in this implementation.

3.	The storage and stream objects cannot be marshaled.

4.	Each stream is at least 4096 bytes in length. If fewer than 4096 bytes are written into a stream by the time the stream is released, the stream will be extended to contain 4096 bytes.

5.	In this compound file implementation, only a subset of the methods of IStorage and IStream are available.

Specifically, in simple mode, supported IStorage methods are QueryInterface, AddRef, Release, CreateStream, Commit, and SetClass. In addition, SetElementTimes is supported with a NULL name, allowing applications to set times on a root storage in simple mode.

Supported IStream methods are QueryInterface, AddRef, Release, Write, Seek, SetSize, and Read.

All the other methods of IStorage and IStream return STG_E_INVALIDFUNCTION.

See Also

StgCreateDocfile, IStream::Read, IStorage, StgCreateDocfileOnILockBytes, StgOpenStorage, StgOpenStorageOnILockBytes


STGMOVE

The STGMOVE enumeration values indicate whether a storage element is to be moved or copied. They are used in the IStorage::MoveElementTo method.

typedef enum tagSTGMOVE

{

    STGMOVE_MOVE    = 0,

    STGMOVE_COPY    = 1

} STGMOVE;

Elements

STGMOVE_MOVE

Indicates the method should move the data from the source to the destination.

STGMOVE_COPY

Indicates the method should copy the data from the source to the destination. A copy is the same as a move except the source element is not removed after copying the element to the destination. Copying an element on top of itself is undefined.

See Also

IStorage::MoveElementTo


STGTY

The STGTY enumeration values are used in the type member of the STATSTG structure to indicate the type of the storage element. A storage element is a storage object, a stream object, or a byte array object (LOCKBYTES).

typedef enum tagSTGTY

{

    STGTY_STORAGE      = 1,

    STGTY_STREAM       = 2,

    STGTY_LOCKBYTES    = 3,

    STGTY_PROPERTY     = 4

} STGTY;

Elements

STGTY_STORAGE

Indicates that the storage element is a storage object.

STGTY_STREAM

Indicates that the storage element is a stream object.

STGTY_LOCKBYTES

Indicates that the storage element is a byte array object.

STGTY_PROPERTY

Indicates that the storage element is a property storage object.

See Also

IStream, STATSTG


STREAM_SEEK

The STREAM_SEEK enumeration values specify the origin from which to calculate the new seek pointer location. They are used for the dworigin parameter in the IStream::Seek method. The new seek position is calculated using this value and the dlibMove parameter.

typedef enum tagSTREAM_SEEK

{

    STREAM_SEEK_SET    = 0,

    STREAM_SEEK_CUR    = 1,

    STREAM_SEEK_END    = 2

} STREAM_SEEK;

Elements

STREAM_SEEK_SET

The new seek pointer is an offset relative to the beginning of the stream. In this case, the dlibMove parameter is the new seek position relative to the beginning of the stream.

STREAM_SEEK_CUR

The new seek pointer is an offset relative to the current seek pointer location. In this case, the dlibMove parameter is the signed displacement from the current seek position.

STREAM_SEEK_END

The new seek pointer is an offset relative to the end of the stream. In this case, the dlibMove parameter is the new seek position relative to the end of the stream.

See Also

IStream::Seek


TYMED

The TYMED enumeration values indicate the type of storage medium being used in a data transfer. They are used in the STGMEDIUM or FORMATETC structures.

typedef [transmit_as(long)] enum tagTYMED

{

    TYMED_HGLOBAL     = 1;

    TYMED_FILE        = 2;

    TYMED_ISTREAM     = 4;

    TYMED_ISTORAGE    = 8;

    TYMED_GDI         = 16;

    TYMED_MFPICT      = 32;

    TYMED_ENHMF       = 64;

    TYMED_NULL        = 0

} TYMED;

Elements

TYMED_HGLOBAL

The storage medium is a global memory handle (HGLOBAL). Allocate the global handle with the GMEM_SHARE flag. If the STGMEDIUM punkForRelease member is NULL, the destination process should use GlobalFree to release the memory.

TYMED_FILE

The storage medium is a disk file identified by a path. If the STGMEDIUM punkForRelease member is NULL, the destination process should use OpenFile to delete the file.

TYMED_ISTREAM

The storage medium is a stream object identified by an IStream pointer. Use IStream::Read to read the data. If the STGMEDIUM punkForRelease member is NULL, the destination process should use IStream::Release to release the stream component.

TYMED_ISTORAGE

The storage medium is a storage component identified by an IStorage pointer. The data is in the streams and storages contained by this IStorage instance. If the STGMEDIUM punkForRelease member is NULL, the destination process should use IStorage::Release to release the storage component.

TYMED_GDI

The storage medium is a GDI component (HBITMAP). If the STGMEDIUM punkForRelease member is NULL, the destination process should use DeleteObject to delete the bitmap.

TYMED_MFPICT

The storage medium is a metafile (HMETAFILE). Use the Windows or WIN32 functions to access the metafile’s data. If the STGMEDIUM punkForRelease member is NULL, the destination process should use DeleteMetaFile to delete the bitmap.

TYMED_ENHMF

The storage medium is an enhanced metafile. If the STGMEDIUM punkForRelease member is NULL, the destination process should use DeleteEnhMetaFile to delete the bitmap.

TYMED_NULL

No data is being passed.

Remarks

During data transfer operations, a storage medium is specified. This medium must be released after the data transfer operation. The provider of the medium indicates its choice of ownership scenarios in the value it provides in the STGMEDIUM structure. A NULL value for the IUNKNOWN field indicates that the receiving body of code owns and can free the medium. A non-NULL pointer specifies that ReleaseStgMedium can always be called to free the medium.

See Also

FORMATETC, IAdviseSink, IDataObject, IOleCache, ReleaseStgMedium, STGMEDIUM


UASFLAGS

The UASFLAGS enumeration value supplies information about the parent undo unit. It is used in IOleParentUndoUnit::GetParentState.

typedef enum tagUASFLAGS

{

    UAS_NORMAL          = 0,

    UAS_BLOCKED         = 0x1,

    UAS_NOPARENTENABLE  = 0x2,

    UAS_MASK            = 0x3,

} UASFLAGS;

Elements

UAS_NORMAL

The currently open parent undo unit is in a normal, unblocked state and can accept any new units added through calls to its Open or Add methods.

UAS_BLOCKED

The currently open undo unit is blocked and will reject any undo units added through calls to its Open or Add methods. The caller need not create any new units since they will just be rejected.

UAS_NOPARENTENABLE

The currently open undo unit will accept new units, but the caller should act like there is no currently open unit. This means that if the new unit being created requires a parent, then this parent does not satisfy that requirement and the undo stack should be cleared.

UAS_MASK

When checking for a normal state, use this value to mask unused bits in the pdwState parameter to the GetParentState method for future compatibility. For example:

    fNormal = ((pdwState & UAS_MASK) == UAS_NORMAL)

See Also

IOleParentUndoUnit::GetParentState


USERCLASSTYPE

The USERCLASSTYPE enumeration constants indicate the different variants of the display name associated with a class of objects. They are used in the IOleObject::GetUserType method and the OleRegGetUserType function.

typedef enum tagUSERCLASSTYPE

{

    USERCLASSTYPE_FULL       = 1,

    USERCLASSTYPE_SHORT      = 2,

    USERCLASSTYPE_APPNAME    = 3,

} USERCLASSTYPE;

Elements

USERCLASSTYPE_FULL

The full type name of the class.

USERCLASSTYPE_SHORT

A short name (maximum of 15 characters) that is used for popup menus and the Links dialog box.

USERCLASSTYPE_APPNAME

The name of the application servicing the class and is used in the Result text in dialog boxes.

See Also

IOleObject::GetUserType, OleRegGetUserType


VIEWSTATUS

The VIEWSTATUS enumeration is used in IViewObjectEx::GetViewStatus to specify the opacity of the object and the drawing aspects supported by the object.

typedef enum tagVIEWSTATUS

{

    VIEWSTATUS_OPAQUE               = 1,

    VIEWSTATUS_SOLIDBKGND           = 2,

    VIEWSTATUS_DVASPECTOPAQUE       = 4,

    VIEWSTATUS_DVASPECTTRANSPARENT  = 8

} VIEWSTATUS;

Elements

VIEWSTATUS_OPAQUE

The object is completely opaque. So, for any aspect, it promises to draw the entire rectangle passed to the IViewObject::Draw method. If this value is not set, the object contains transparent parts. If it also support DVASPECT_TRANSPARENT, then this aspect may be used to draw the transparent parts only.

This bit applies only to CONTENT related aspects and not to DVASPECT_ICON or DVASPECT_DOCPRINT.

VIEWSTATUS_SOLIDBKGND

The object has a solid background (consisting in a solid color, not a brush pattern). This bit is meaningful only if VIEWSTATUS_OPAQUE is set.

This bit applies only to CONTENT related aspects and not to DVASPECT_ICON or DVASPECT_DOCPRINT.

VIEWSTATUS_DVASPECTOPAQUE

Object supports DVASPECT_OPAQUE. All IViewObjectEx methods taking a drawing aspect as a parameter can be called with this aspect.

VIEWSTATUS_DVASPECTTRANSPARENT

The object supports DVASPECT_TRANSPARENT. All IViewObjectEx methods taking a drawing aspect as a parameter can be called with this aspect.

See Also

IViewObjectEx::GetViewStatus


BindMoniker

Locates an object by means of its moniker, activates the object if it is inactive, and retrieves a pointer to the specified interface on that object.

HRESULT BindMoniker(

LPMONIKER pmk,	//Pointer to the object’s moniker
DWORD grfOpt,	//Reserved
REFIID iidResult,	//Interface identifier
LPVOID FAR *ppvResult	//Indirect pointer to requested interface
);
Parameters

pmk

[in] Pointer to the object’s moniker.

grfOpt

[in] Reserved for future use; must be zero.

iidResult

[in] Interface identifier to be used to communicate with the object.

ppvResult

[out] Indirect pointer to the requested interface. If an error occurs, ppvResult is NULL. If the call is successful, the caller is responsible for releasing the pointer with a call to the object’s IUnknown::Release.

Return Values

S_OK

The object was located and activated, if necessary, and that a pointer to the requested interface was returned.

MK_E_NOOBJECT

The object that the moniker object identified could not be found.

This function can also return any of the error values returned by the IMoniker::BindToObject method.

Remarks

BindMoniker is a helper function supplied as a convenient way for a client that has the moniker of an object to obtain a pointer to one of its interfaces. The BindMoniker function packages the following calls:

CreateBindCtx(0, &pbc);

pmk->BindToObject(pbc, NULL, riid, ppvObj);

CreateBindCtx creates a bind context object that supports the system implementation of IBindContext. The pmk parameter is actually a pointer to the IMoniker implementation on a moniker object. This implementation’s BindToObject method supplies the pointer to the requested interface pointer.

If you have several monikers to bind in quick succession, and if you know that those monikers will activate the same object, it may be more efficient to call the IMoniker::BindToObject method directly, which allows you to use the same bind context object for all the monikers. See the IBindCtx interface for more information.

Container applications that allow their documents to contain linked objects are a special client that generally does not make direct calls to IMoniker methods. Instead, the client manipulates the linked objects through the IOleLink interface. The default handler implements this interface and calls the appropriate IMoniker methods as needed.

See Also

CreateBindCtx, IMoniker::BindToObject


CLSIDFromProgID

Looks up a CLSID in the registry, given a ProgID.

HRESULT CLSIDFromProgID(

LPCOLESTR lpszProgID,	//Pointer to the ProgID
LPCLSID pclsid	//Pointer to the CLSID
);
Parameters

lpszProgID

[in] Pointer to the ProgID whose CLSID is requested.

pclsid

[out] Pointer to the retrieved CLSID on return.

Return Values

S_OK

The CLSID was retrieved successfully.

CO_E_CLASSSTRING

The registered CLSID for the ProgID is invalid.

REGDB_E_WRITEREGDB

An error occurred writing the CLSID to the registry. See “Remarks” below.

Remarks

Given a ProgID, CLSIDFromProgID looks up its associated CLSID in the registry. If the ProgID cannot be found in the registry, CLSIDFromProgID creates an OLE 1 CLSID for the ProgID and a CLSID entry in the registry. Because of the restrictions placed on OLE 1 CLSID values, CLSIDFromProgID and CLSIDFromString are the only two functions that can be used to generate a CLSID for an OLE 1 object.

See Also

ProgIDFromCLSID


CLSIDFromString

Converts a string generated by the StringFromCLSID function back into the original CLSID.

HRESULT CLSIDFromString(

LPOLESTR lpsz,	//Pointer to the string representation of the CLSID
LPCLSID pclsid	//Pointer to the CLSID
);
Parameters

lpsz

[in] Pointer to the string representation of the CLSID.

pclsid

[out] Pointer to the CLSID on return.

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

NOERROR

The CLSID was obtained successfully.

CO_E_CLASSTRING

The class string was improperly formatted.

REGDB_E_WRITEREGDB

The CLSID corresponding to the class string was not found in the registry.

Remarks

Because of the restrictions placed on OLE 1 CLSID values, CLSIDFromProgID and CLSIDFromString are the only two functions that can be used to generate a CLSID for an OLE 1 object.

See Also

CLSIDFromProgID, StringFromCLSID


CoAddRefServerProcess

Increments a global per-process reference count.

ULONG CoAddRefServerProcess(void);

Return Values

S_OK

The CLSID was retrieved successfully.

Remarks

Servers can call CoAddRefServerProcess to increment a global per-process reference count. This function is particularly helpful to servers that are implemented with multiple threads, either multi-apartmented or free-threaded. Servers of these types must coordinate the decision to shut down with activation requests across multiple threads. Calling CoAddRefServerProcess increments a global per-process reference count, and calling CoReleaseServerProcess decrements that count.

When that count reaches zero, OLE automatically calls CoSuspendClassObjects, which prevents new activation requests from coming in. This permits the server to deregister its class objects from its various threads without worry that another activation request may come in. New activation requests result in launching a new instance of the local server process.

The simplest way for a local server application to make use of these API functions is to call CoAddRefServerProcess in the constructor for each of it’s instance objects, and in each of its IClassFactory::LockServer methods when the fLock parameter is TRUE. The server application should also call CoReleaseServerProcess in the destruction of each of its instance objects, and in each of its IClassFactory::LockServer methods when the fLock parameter is FALSE. Finally, the server application should pay attention to the return code from CoReleaseServerProcess and if it returns 0, the server application should initiate its cleanup, which, for a server with multiple threads,  typically means that it should signal its various threads to exit their message loops and call CoRevokeClassObject and CoUninitialize.

If these APIs are used at all, they must be called in both the object instances and the LockServer method, otherwise the server application may be shut down prematurely. In-process servers typically should not call CoAddRefServerProcess or CoReleaseServerProcess.

See Also

CoReleaseServerProcess, IClassFactory::LockServer, Out-of-process Server Implementation Helpers


CoBuildVersion

This function is obsolete.


CoCopyProxy

Makes a private copy of the specified proxy.

HRESULT CoCopyProxy(

IUnknown *  punkProxy	//IUnknown pointer to the proxy to copy
IUnknown **  ppunkCopy	//Indirect IUnknown pointer to the copy
);
Parameter

punkProxy

[in] Points to the IUnknown interface on the proxy to be copied. May not be NULL.

ppunkCopy

[out] Points to the location of the IUnknown pointer to the copy of the proxy. It may not be NULL.

Return Values

S_OK

Success.

E_INVALIDARG

One or more arguments are invalid.

Remarks

CoCopyProxy makes a private copy of the specified proxy. Typically, this is called when a client needs to change the authentication information of its proxy through a call to either CoSetClientBlanket or IClientSecurity::SetBlanket without changing this information for other clients. CoSetClientBlanket affects all the users of an instance of a proxy, so creating a private copy of the proxy through a call to CoCopyProxy eliminates the problem.

This function encapsulates the following sequence of common calls (error handling excluded):

    pProxy->QueryInterface(IID_IClientSecurity, (void**)&pcs);

    pcs->CopyProxy(punkProxy, ppunkCopy);

    pcs->Release();

Local interfaces may not be copied. IUnknown and IClientSecurity are examples of existing local interfaces.

Copies of the same proxy have a special relationship with respect to QueryInterface. Given a proxy, a, of the IA interface of a remote object, suppose a copy of a is created, called b. In this case, calling QueryInterface from the b proxy for IID_IA will not retrieve the IA interface on b, but the one on a, the original proxy with the “default” security settings for the IA interface.

See Also

IClientSecurity::CopyProxy, Security in COM


CoCreateFreeThreadedMarshaler

Creates an aggregatable object capable of context-dependent marshaling.

HRESULT CoCreateFreeThreadedMarshaler(

LPUNKNOWN punkOuter,	// Pointer to object aggregating the marshaler object
LPUNKNOWN * ppunkMarshaler	// Indirect pointer to the marshaler object
);
Parameters

punkOuter

[in] Pointer to the aggregating object's controlling IUnknown.

ppunkMarshaler

[out] Indirect pointer to the aggregatable marshaler's IUnknown.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The marshaler was created.

Remarks

The CoCreateFreeThreadedMarshaler function enables an object to efficiently marshal interface pointers between threads in the same process. If your objects do not support interthread marshaling, you have no need to call this function.

The CoCreateFreeThreadedMarshaler function performs the following tasks:

1.	Creates a free-threaded marshaler object.

2.	Aggregates this marshaler to the object specified by the punkOuter parameter. This object is normally the one whose interface pointers are to be marshaled.

The aggregating object's implementation of IMarshal should delegate QueryInterface calls for IID_IMarshal to the IUnknown of the free-threaded marshaler. Upon receiving a call, the free-threaded marshaler performs the following tasks:

1.	Checks the destination context specified by the CoMarshalInterface function's dwDestContext parameter.

2.	If the destination context is MSHCTX_INPROC, copies the interface pointer into the marshaling stream.

3.	If the destination context is any other value, finds or creates an instance of COM's default (standard) marshaler and delegates marshaling to it.

Values for dwDestContext come from the MSHCTX enumeration. MSHCTX_INPROC indicates that the interface pointer is to be marshaled between different threads in the same process. Because both threads have access to the same address space, the client thread can dereference the pointer directly rather than having to direct calls to a proxy. In all other cases, a proxy is required, so CoCreateFreeThreadedMarshaler delegates the marshaling job to COM's default implementation.

See Also

CoMarshalInterThreadInterfaceInStream, CoGetInterfaceAndReleaseStream


CoCreateGuid

Creates a GUID, a unique 128-bit integer used for CLSIDs and interface identifiers.

HRESULT CoCreateGuid(

GUID  *pguid	//Pointer to the GUID on return
);
Parameter

pguid

[out] Pointer to the requested GUID on return.

Return Value

S_OK

The GUID was successfully created.

Win32 errors are returned by UuidCreate but wrapped as an HRESULT.

Remarks

The CoCreateGuid function calls the RPC function UuidCreate, which creates a GUID, a globally unique 128-bit integer. Use the CoCreateGuid function when you need an absolutely unique number that you will use as a persistent identifier in a distributed environment.To a very high degree of certainty, this function returns a unique value − no other invocation, on the same or any other system (networked or not), should return the same value.

See Also

UuidCreate (documented in the RPC Programmer’s Guide and Reference)


CoCreateInstance

Creates a single uninitialized object of the class associated with a specified CLSID. Call CoCreateInstance when you want to create only one object on the local system. To create a single object on a remote system, call CoCreateInstanceEx. To create multiple objects based on a single CLSID, refer to the CoGetClassObject function.

STDAPI CoCreateInstance(

REFCLSID rclsid,	//Class identifier (CLSID) of the object
LPUNKNOWN pUnkOuter,	//Pointer to whether object is or isn’t part of an aggregate
DWORD dwClsContext,	//Context for running executable code
REFIID riid,	//Reference to the identifier of the interface
LPVOID * ppv	//Indirect pointer to requested interface
);
Parameters

rclsid

[in] CLSID associated with the data and code that will be used to create the object.

pUnkOuter

[in] If NULL, indicates that the object is not being created as part of an aggregate. If non-NULL, pointer to the aggregate object’s IUnknown interface (the controlling IUnknown).

dwClsContext

[in] Context in which the code that manages the newly created object will run. The values are taken from the enumeration CLSCTX.

riid

[in] Reference to the identifier of the interface to be used to communicate with the object.

ppv

[out] Indirect pointer to the requested interface.

Return Values

S_OK

An instance of the specified object class was successfully created.

REGDB_E_CLASSNOTREG

A specified class is not registered in the registration database. Also can indicate that the type of server you requested in the CLSCTX enumeration is not registered or the values for the server types in the registry are corrupt.

CLASS_E_NOAGGREGATION

This class cannot be created as part of an aggregate.

Remarks

The CoCreateInstance helper function provides a convenient shortcut by connecting to the class object associated with the specified CLSID, creating an uninitialized instance, and releasing the class object. As such, it encapsulates the following functionality:

CoGetClassObject(rclsid, dwClsContext, NULL, IID_IClassFactory, &pCF);

hresult = pCF->CreateInstance(pUnkOuter, riid, ppvObj)

pCF->Release();

It is convenient to use CoCreateInstance when you need to create only a single instance of an object on the local machine. If you are creating an instance on remote machine, call CoCreateInstanceEx. When you are creating multiple instances, it is more efficient to obtain a pointer to the class object’s IClassFactory interface and use its methods as needed. In the latter case, you should use the CoGetClassObject function.

In the CLSCTX enumeration, you can specify the type of server used to manage the object. The constants can be CLSCTX_INPROC_SERVER, CLSTCTX_INPROC_HANDLER, CLSCTX_LOCAL_SERVER, or any combination of these values. The constant CLSCTX_ALL is defined as the combination of all three. For more information about the use of one or a combination of these constants, refer to CLSCTX.

See Also

CoGetClassObject, IClassFactory::CreateInstance, CoCreateInstanceEx, CLSCTX, Instance Creation Helper Functions


CoCreateInstanceEx

Creates an instance of a specific class on a specific machine.

HRESULT CoCreateInstanceEx(

REFCLSID  rclsid,	//CLSID of the object to be created
IUnknown *  punkOuter,	//If part of an aggregate, the controlling IUnknown
DWORD  dwClsCtx,	//CLSCTX values
COSERVERINFO* pServerInfo,	//Machine on which the object is to be instantiated
ULONG  cmq,	//Number of MULTI_QI structures in rgmqResults
MULTI_QI  rgmqResults	//Array of MULTI_QI structures
);
Parameters

rclsid

[in] CLSID of the object to be created.

punkOuter

[in] When non-NULL, indicates the instance is being created as part of an aggregate, and punkOuter is to be used as the new instance’s controlling IUnknown. Aggregation is currently not supported cross-process or cross-machine. When instantiating an object out of process, CLASS_E_NOAGGREGATION will be returned if punkOuter is non-NULL.

dwClsCtx

[in] Values taken from the CLSCTX enumeration.

pServerInfo

[in] Machine on which to instantiate the object. May be NULL, in which case the object is instantiated on the current machine or at the machine specified in the registry under the class’s RemoteServerName named-value, according to the interpretation of the dwClsCtx parameter. See the CLSCTX documentation for details).

cmq

[in] Number of MULTI_QI structures in rgmqResults. Must be greater than zero.

rgmqResults

Array of MULTI_QI structures. Each structure has three members: the identifier for a requested interface (pIID), the location to return the interface pointer (pItf) and the return value of the call to QueryInterface (hr).

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK

Indicates success.

CO_S_NOTALLINTERFACES

At least one, but not all of the interfaces requested in the rgmqResults array were successfully retrieved. The hr field of each of the MULTI_QI structures in rgmqResults indicates with S_OK or E_NOINTERFACE whether the specific interface was returned.

E_NOINTERFACE

None of the interfaces requested in the rgmqResults array were successfully retrieved.

Remarks

CoCreateInstanceEx creates a single uninitialized object associated with the given CLSID on a specified remote machine. This is an extension of the function CoCreateInstance, which creates an object on the local machine only. In addition, rather than requesting a single interface and obtaining a single pointer to that interface, CoCreateInstanceEx makes it possible to specify an array of structures, each pointing to an interface identifier (IID) on input, and, on return, containing (if available) a pointer to the requested interface and the return value of the QueryInterface call for that interface. This permits fewer round trips between machines.

The CoCreateInstanceEx helper function encapsulates three calls: first, to CoGetClassObject to connect to the class object associated with the specified CLSID, specifying the machine location of the class; second, to IClassFactory::CreateInstance to create an uninitialized instance, and finally, to IClassFactory::Release, to release the class object.

The object so created must still be initialized through a call to one of the initialization interfaces (such as IPersistStorage:::Load). The two helper functions, CoGetInstanceFromFile and CoGetInstanceFromIStorage encapsulate both the instance creation and initialization from the obvious sources.

See Also

CoGetInstanceFromFile, CoGetInstanceFromIStorage, CLSCTX, COSERVERINFO, Instance Creation Helper Functions


CoCreateStandardMalloc

This function is obsolete. Refer to CoGetMalloc.


CoDisconnectObject

Disconnects all remote process connections being maintained on behalf of all the interface pointers that point to a specified object. Only the process that actually manages the object should call CoDisconnectObject.

STDAPI CoDisconnectObject(

IUnknown * pUnk,	//Pointer to the interface on the object
DWORD dwReserved	//Reserved for future use
);
Parameters

pUnk

[in] Pointer to any IUnknown-derived interface on the object to be disconnected.

dwReserved

[in] Reserved for future use; must be zero.

Return Values

S_OK

All connections to remote processes were successfully deleted.

Remarks

The CoDisconnectObject function enables a server to correctly disconnect all external clients to the object specified by pUnk.

The CoDisconnectObject function performs the following tasks:

1.	Checks to see if the object to be disconnected implements the IMarshal interface. If so, it gets the pointer to that interface; if not, it gets a pointer to the standard marshaler’s (i.e., COM’s) IMarshal implementation.

2.	Using whichever IMarshal interface pointer it has acquired, the function then calls IMarshal::DisconnectObject to disconnect all out-of-process clients.

An object’s client does not call CoDisconnectObject to disconnect itself from the server (clients should use IUnknown::Release for this purpose). Rather, an OLE server calls CoDisconnectObject to forcibly disconnect an object’s clients, usually in response to a user closing the server application.

Similarly, an OLE container that supports external links to its embedded objects can call CoDisconnectObject to destroy those links. Again, this call is normally made in response to a user closing the application. The container should first call IOleObject::Close for all its OLE objects, each of which should send IAdviseSink::OnClose notifications to their various clients. Then the container can safely call CoDisconnectObject to close any existing connections.

See Also

IOleObject::Close, IMarshal::DisconnectObject


CoDosDateTimeToFileTime

Converts the MS-DOS representation of the time and date to a FILETIME structure, which Win32 uses to determine the date and time.

BOOL CoDosDateTimeToFileTime(

WORD nDosDate,	//16-bit MS-DOS date
WORD nDosTime,	//16-bit MS-DOS time
FILETIME * lpFileTime	//Pointer to the structure
);
Parameters

nDosDate

[in] 16-bit MS-DOS date.

nDosTime

[in] 16-bit MS-DOS time.

lpFileTime

[out] Pointer to the FILETIME structure.

Return Values

TRUE

The FILETIME structure was created successfully.

FALSE

The FILETIME structure was not created successfully, probably because of invalid arguments.

Remarks

The FILETIME structure and the CoDosDateTimeToFileTime and CoFileTimeToDosDateTime functions are part of the Win32 API definition. They are provided for compatibility in all OLE implementations, but are redundant on Win32 platforms.

MS-DOS records file dates and times as packed 16-bit values. An MS-DOS date has the following format:

Bits	Contents
0-4	Days of the month (1-31).
5-8	Months (1 = January, 2 = February, and so forth).
9-15	Year offset from 1980 (add 1980 to get actual year).
An MS-DOS time has the following format:

Bits	Contents
0-4	Seconds divided by 2.
5-10	Minutes (0-59).
11-15	Hours (0-23 on a 24-hour clock).
See Also

CoFileTimeToDosDateTime, CoFileTimeNow


CoFileTimeNow

Returns the current time as a FILETIME structure.

HRESULT CoFileTimeNow(

FILETIME  * lpFileTime	//Pointer to return the structure
);
Parameter

lpFileTime

[out] Pointer to return the FILETIME structure.

Return Values

S_OK

The current time was converted to a FILETIME structure.

See Also

CoDosDateTimeToFileTime, CoFileTimeToDosDateTime


CoFileTimeToDosDateTime

Converts a FILETIME into MS-DOS date and time values.

BOOL CoFileTimeToDosDateTime(

FILETIME  * lpFileTime,	//Pointer to the structure to be converted
LPWORD lpDosDate,	//Pointer to the 16-bit MS-DOS date
LPWORD lpDosTime	//Pointer to the 16-bit MS-DOS time
);
Parameters

lpFileTime

[in] Pointer to the FILETIME structure to be converted.

lpDosDate

[out] Pointer to the 16-bit MS-DOS date.

lpDosTime

[out] Pointer to the 16-bit MS-DOS time.

Return Values

TRUE

The FILETIME structure was converted successfully.

FALSE

The FILETIME structure was not converted successfully.

Remarks

This is the inverse of the operation provided by the CoDosDateTimeToFileTime function.

See Also

CoDosDateTimeToFileTime, CoFileTimeNow


CoFreeAllLibraries

Frees all the DLLs that have been loaded with the CoLoadLibrary function (called internally by CoGetClassObject), regardless of whether they are currently in use. This function is usually not called directly, because CoUninitialize and OleUninitialize call it internally.

void CoFreeAllLibraries();

Remarks

To unload libraries, CoFreeAllLibraries uses a list of loaded DLLs for each process that the COM library maintains. The CoUninitialize function calls CoFreeAllLibraries internally, so OLE applications usually have no need to call this function directly.

See Also

CoLoadLibrary, CoFreeLibrary, CoFreeUnusedLibraries, CoGetClassObject, CoUninitialize, OleUninitialize


CoFreeLibrary

Frees a library that, when loaded, was specified to be freed explicitly.

void CoFreeLibrary(

HINSTANCE  hInst	//Handle of the library module to be freed
);
Parameter

hInst

[in] Handle to the library module to be freed, as returned by CoLoadLibrary.

Remarks

The CoFreeLibrary function should be called to free a library that is to be freed explicitly. This is established when the library is loaded with the bAutoFree parameter of CoLoadLibrary set to FALSE. It is illegal to free a library explicitly when the corresponding CoLoadLibrary call specifies that it be freed automatically (the bAutoFree parameter is set to TRUE).

See Also

CoFreeAllLibraries, CoFreeUnusedLibraries, CoLoadLibrary


CoFreeUnusedLibraries

Unloads any DLLs that are no longer in use and that, when loaded, were specified to be freed automatically.

void CoFreeUnusedLibraries();

Remarks

Applications can call CoFreeUnusedLibraries periodically to free resources. It is most efficient to call it either at the top of a message loop or in some idle-time task. DLLs that are to be freed automatically have been loaded with the bAutoFree parameter of the CoLoadLibrary function set to TRUE.  CoFreeUnusedLibraries internally calls DllCanUnloadNow for DLLs that implement and export that function.

See Also

CoFreeLibrary, CoFreeUnusedLibraries, CoLoadLibrary, DLLCanUnloadNow


CoGetCallContext

Retrieves the context of the current call on the current thread.

HRESULT CoGetCallContext(

REFIID  riid,	//Interface identifier
void **  ppv	//Pointer to the requested interface
);
Parameters

riid

[in] Interface identifier (IID) of the call context that is being requested. If you are using the default call context supported by standard marshaling, only IID_IServerSecurity is available.

ppv

[out] Indirect pointer to the requested interface.

Return Values

S_OK

Success.

E_NOINTERFACE

The call context does not support the interface identified by riid.

Remarks

CoGetCallContext retrieves the context of the current call on the current thread. The riid parameter specifies the interface on the context to be retrieved. Currently, only IServerSecurity is available from the default call context supported by standard marshaling.

This is one of the functions provided to give the server access to any contextual information of the caller and to encapsulate common sequences of security checking and caller impersonation.

See Also

IServerSecurity, Security in COM


CoGetClassObject

Provides a pointer to an interface on a class object associated with a specified CLSID. CoGetClassObject locates, and if necessary, dynamically loads the executable code required to do this.

Call CoGetClassObject directly when you want to create multiple objects through a class object for which there is a CLSID in the system registry. You can also retrieve a class object from a specific remote machine. Most class objects implement the IClassFactory interface. You would then call IClassFactory::CreateInstance to create an uninitialized object. It is not always necessary to go through this process. To create a single object, call instead the either the CoCreateInstanceEx function, which allows you to create an instance on a remote machine. This replaces the CoCreateInstance function, which can still be used to create an instance on a local machine. Both functions encapsulate connecting to the class object, creating the instance, and releasing the class object. Two other functions, CoGetInstanceFromFile and CoGetInstanceFromIStorage, provide both instance creation on a remote system, and object activation. OLE also provides many other ways to create an object in the form of numerous helper functions and interface methods whose function is to create objects of a single type and provide a pointer to an interface on that object.

STDAPI CoGetClassObject(

REFCLSID rclsid,	//CLSID associated with the class object
DWORD dwClsContext,	//Context for running executable code
COSERVERINFO * pServerInfo,	//Pointer to machine on which the object is to be instantiated
REFIID riid,	//Reference to the identifier of the interface
LPVOID * ppv	//Indirect pointer to the interface
);
Parameters

rclsid

[in] CLSID associated with the data and code that you will use to create the objects.

dwClsContext

[in] Context in which the executable code is to be run. To enable a remote activation, CLSCTX_REMOTE_SERVER must be included. For more information on the context values and their use, see the CLSCTX enumeration.

pServerInfo

[in] Pointer to machine on which to instantiate the class object. May be NULL, in which case the class object is instantiated on the current machine or at the machine specified under the class’s RemoteServerName key in the registry, according to the interpretation of the dwClsCtx parameter (see the CLSCTX documentation for details).

riid

[in] Reference to the identifier of the interface, which will be supplied in ppv on successful return. This interface will be used to communicate with the class object. Typically this value is IID_IClassFactory, although other values − such as IID_IClassFactory2 which supports a form of licensing − are allowed. All OLE-defined interface IIDs are defined in the OLE header files as IID_interfacename, where interfacename is the name of the interface.

ppv

[out] On successful return, indirect pointer to the requested interface.

Return Values

S_OK

Location and connection to the specified class object was successful.

REGDB_E_CLASSNOTREG

CLSID is not properly registered. Can also indicate that the value you specified in dwClsContext is not in the registry.

E_NOINTERFACE

Either the object pointed to by ppv does not support the interface identified by riid, or the QueryInterface operation on the class object returned E_NOINTERFACE.

REGDB_E_READREGDB

Error reading the registration database.

CO_E_DLLNOTFOUND

In-process DLL or handler DLL not found (depends on context).

CO_E_APPNOTFOUND

EXE not found (CLSCTX_LOCAL_SERVER only).

E_ACCESSDENIED

General access failure (returned from LoadLib/CreateProcess).

CO_E_ERRORINDLL

EXE has error in image.

CO_E_APPDIDNTREG

EXE was launched, but it didn’t register class object (may or may not have shut down).

Remarks

A class object in OLE is an intermediate object that supports an interface that permits operations common to a group of objects. The objects in this group are instances derived from the same object definition represented by a single CLSID. Usually, the interface implemented on a class object is IClassFactory, through which you can create object instances of a given definition (class).

A call to CoGetClassObject creates, initializes, and gives the caller access (through a pointer to an interface specified with the riid parameter) to the class object. The class object is the one associated with the CLSID that you specify in the rclsid parameter. The details of how the system locates the associated code and data within a given machine are transparent to the caller, as is the dynamic loading of any code that is not already loaded.

If the class context is CLSCTX_REMOTE_SERVER, indicating remote activation is required, the COSERVERINFO structure provided in the pServerInfo parameter allows you to specify the machine on which the server is located. For information on the algorithm used to locate a remote server when pServerInfo is NULL, refer to the CLSCTX enumeration.

There are two places to find a CLSID for a given class:

•	The registry holds an association between CLSIDs and file suffixes, and between CLSIDs and file signatures for determining the class of an object.

•	When an object is saved to persistent storage, its CLSID is stored with its data.

To create and initialize embedded or linked OLE document objects, it is not necessary to call CoGetClassObject directly. Instead, call one of the OleCreate or OleCreateXxx helper functions. These functions encapsulate the entire object instantiation and initialization process, and call, among other functions, CoGetClassObject.

The riid parameter specifies the interface the client will use to communicate with the class object. In most cases, this interface is IClassFactory. This provides access to the IClassFactory::CreateInstance method, through which the caller can then create an uninitialized object of the kind specified in its implementation. All classes registered in the system with a CLSID must implement IClassFactory.

In rare cases, however, you may want to specify some other interface that defines operations common to a set of objects. For example, in the way OLE implements monikers, the interface on the class object is IParseDisplayName, used to transform the display name of an object into a moniker.

The dwClsContext parameter specifies the execution context, allowing one CLSID to be associated with different pieces of code in different execution contexts. The CLSCTX enumeration, defined in Compobj.H, specifies the available context flags. CoGetClassObject consults (as appropriate for the context indicated) both the registry and the class objects that are currently registered by calling the CoRegisterClassObject function.

To release a class object, use the class object’s Release method. The function CoRevokeClassObject is to be used only to remove a class object’s CLSID from the system registry.

See Also

CoCreateInstanceEx, CoRegisterClassObject, CoRevokeClassObject, OleLoad, CLSCTX, Creating an Object through a Class Object


CoGetCurrentProcess

Returns a value that is unique to the current thread. It can be used to avoid PROCESSID reuse problems.

DWORD CoGetCurrentProcess();

Return Value

DWORD value

Unique value for the current thread that can be used to avoid PROCESSID reuse problems.

Remarks

The CoGetCurrentProcess function returns a value that is effectively unique, because it is not used again until 2 (32 ) more threads have been created on the current workstation or until the workstation is rebooted.

Using the value returned from a call to CoGetCurrentProcess can help you maintain tables that are keyed by threads or in uniquely identifying a thread to other threads or processes.

Using the value returned by CoGetCurrentProcess is more robust than using the HTASK task handle value returned by the Win32 function GetCurrentTask, because Windows task handles can be reused relatively quickly when a window’s task dies.


CoGetInstanceFromFile

Creates a new object and initializes it from a file using IPersistFile::Load.

HRESULT CoGetInstanceFromFile(

COSERVERINFO *  pServerInfo,	//Pointer to COSERVERINFO struct indicating remote system
CLSID*  pclsid,	//Pointer to the class of the object to create
IUnknown * punkOuter,	//If part of an aggregate, pointer to the controlling IUnknown
DWORD dwClsCtx,	//CLSCTX values
OLECHAR* szName,	//File to initialize the object with
ULONG  cmq,	//Number of MULTI_QI structures in rgmqResults
MULTI_QI * rgmqResults	//Array of MULTI_QI structures
);
Parameters

pServerInfo

[in] Pointer to a COSERVERINFO structure that specifies the machine on which to instantiate the object and the authentication setting to be used. May be NULL, in which case the object is instantiated (1) on the current machine, (2) at the machine specified under the RemoteServerName named-value for the class in the registry, or (3) at the machine where the szName file resides if the ActivateAtStorage named-value is specified for the class in the registry or there is no local registry information.

pclsid

[in] Pointer to the class of the object to create. May be NULL, in which case there is a call to GetClassFile, using szName as its parameter to get the class of the object to be instantiated.

punkOuter

[in] When non-NULL, indicates the instance is being created as part of an aggregate, and punkOuter is to be used as the pointer to the new instance’s controlling IUnknown. Aggregation is currently not supported cross-process or cross-machine. When instantiating an object out of process, CLASS_E_NOAGGREGATION will be returned if punkOuter is non-NULL.

dwClsCtx

[in] Values taken from the CLSCTX enumeration.

szName

[in] File to initialize the object with using IPersistFile::Load. May not be NULL.

cmq

[in] Number of MULTI_QI structures in rgmqResults. Must be greater than zero.

rgmqResults

[in] Array of MULTI_QI structures. Each structure has three members: the identifier for a requested interface (pIID), the location to return the interface pointer (pItf) and the return value of the call to QueryInterface (hr).

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK

Indicates success.

CO_S_NOTALLINTERFACES

At least one, but not all of the interfaces requested in the rgmqResults array were successfully retrieved. The hr field of each of the MULTI_QI structures in rgmqResults indicates with S_OK or E_NOINTERFACE whether or not the specific interface was returned.

E_NOINTERFACE

None of the interfaces requested in the rgmqResults array were successfully retrieved.

Remarks

CoGetInstanceFromFile creates a new object and initializes it from a file using IPersistFile::Load. The result of this function is similar to creating an instance with a call to CoCreateInstanceEx, followed by an initializing call to IPersistFile::Load, with the following important distinctions:

•	Fewer network round trips are required by this function when instantiating an object on a remote machine.

•	In the case where dwClsCtx is set to CLSCTX_REMOTE_SERVER and pServerInfo is NULL, if the class is registered with the ActivateAtStorage sub-key or has no associated registry information, this function will instantiate an object on the machine where szName resides, providing the least possible network traffic. For example, if szName specified “\\myserver\users\johndo\file”, the object would be instantiated on the “myserver” machine, and the object would access the file directly.

See Also

CoCreateInstanceEx, CoGetInstanceFromIStorage, CLSCTX, Instance Creation Helper Functions


CoGetInstanceFromIStorage

Creates a new object and initializes it from a storage object through an internal call to IPersistStorage::Load.

HRESULT CoGetInstanceFromIStorage(

COSERVERINFO *  pServerInfo,	//Pointer to COSERVERINFO struct indicating remote system
CLSID *  pclsid,	//Pointer to the CLSID of the object to be created
IUnknown * punkOuter,	//If part of an aggregate, pointer to the controlling IUnknown
DWORD  dwClsCtx,	//Values taken from the CLSCTX enumeration
IStorage * pstg,	//Pointer to storage from which object is to be initialized
ULONG  cmq,	//Number of MULTI_QI structures in rgmqResults
MULTI_QI * rgmqResults	//Array of MULTI_QI structures
);
Parameters

pServerInfo

[in] Pointer to a COSERVERINFO structure that specifies the machine on which to instantiate the object and the authentication setting to be used. May be NULL, in which case the object is either instantiated (1) on the current machine, (2) at the machine specified under the RemoteServerName named-value for the class in the registry, or (3) at the machine where the storage object pointed to by pstg is located if the class is registered with ActivateAtStorage specified or has no local registry information.

pclsid

[in] Pointer to the class identifier (CLSID) of the object to be created. May be NULL, in which case there is a call to IStorage:Stat to find the class of the object.

punkOuter

[in] When non-NULL, indicates the instance is being created as part of an aggregate, and punkOuter is to be used as the pointer to the new instance’s controlling IUnknown. Aggregation is currently not supported cross-process or cross-machine. When instantiating an object out of process, CLASS_E_NOAGGREGATION will be returned if punkOuter is non-NULL.

dwClsCtx

Values taken from the CLSCTX enumeration.

pstg

Pointer to storage to initialize the object with using IPersistStorage::Load. May not be NULL.

cmq

Number of MULTI_QI structures in rgmqResults. Must be greater than zero.

rgmqResults

Array of MULTI_QI structures. Each structure has three members: the identifier for a requested interface (pIID), the location to return the interface pointer (pItf) and the return value of the call to QueryInterface (hr).

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK

Indicates success.

CO_S_NOTALLINTERFACES

At least one, but not all of the interfaces requested in the rgmqResults array were successfully retrieved. The hr field of each of the MULTI_QI structures in rgmqResults indicates with S_OK or E_NOINTERFACE whether the specific interface pointer was retrieved.

E_NOINTERFACE

None of the interfaces requested in the rgmqResults array were successfully retrieved.

Remarks

CoGetInstanceFromIStorage creates a new object and initializes it from a storage object through a call to IPersistStorage::Load. This function is similar to creating an instance using CoCreateInstanceEx followed by a call to IPersistStorage::Load, with the following important distinctions:

•	Fewer network round trips are required by thisfunction when instantiating remotely.

•	In the case where dwClsCtx is set to CLSCTX_REMOTE_SERVER and pServerInfo is NULL, if the class is registered with the ActivateAtStorage named value or has no associated registry information, this function will instantiate an object on the same machine where the storage object pointed to by pstg resides, providing the least possible network traffic. For example, if pstg were obtained through a call to StgCreateDocfile, specifying “\\myserver\users\johndo\file”, the object would be instantiated on the “myserver” machine, and the object would access the storage object directly.

See Also

CoCreateInstanceEx, CoGetInstanceFromFile, CLSCTX, Instance Creation Helper Functions


CoGetInterfaceAndReleaseStream

Unmarshals a buffer containing an interface pointer and releases the stream when an interface pointer has been marshaled from another thread to the calling thread.

HRESULT CoGetInterfaceAndReleaseStream(

LPSTREAM  pStm,	//Pointer to the stream from which the object is to be marshaled
REFIID riid,	//Reference to the identifier of the interface
LPVOID * ppv	//Indirect pointer to the interface
);
Parameters

pStm

[in] Pointer to the IStream interface on the stream to be unmarshaled.

riid

[in] Reference to the identifier of the interface requested from the unmarshaled object.

ppv

[out] Indirect pointer to the unmarshaled interface.

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK

Indicates the output interface was unmarshaled and the stream was released.

This function can also return any of the values returned by CoUnmarshalInterface.

Remarks

The CoGetInterfaceAndReleaseStream function performs the following tasks:

1.	Calls CoUnmarshalInterface to unmarshal an interface pointer previously passed in a call to CoMarshalInterThreadInterfaceInStream.

2.	Releases the stream pointer. Even if the unmarshaling fails, the stream is still released because there is no effective way to recover from a failure of this kind.

See Also

CoMarshalInterThreadInterfaceInStream, CoUnmarshalInterface


CoGetMalloc

Retrieves a pointer to the default OLE task memory allocator (which supports the system implementation of the IMalloc interface) so applications can call its methods to manage memory.

HRESULT CoGetMalloc(

DWORD dwMemContext,	//Indicates if memory is private or shared
LPMALLOC * ppMalloc	//Indirect pointer to memory allocator
);
Parameters

dwMemContext

[in] Reserved; value must be 1.

ppMalloc

[out] Indirect pointer to an IMalloc interface on the memory allocator.

Return Values

This function supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

S_OK

Indicates the allocator was retrieved successfully.

Remarks

The pointer to the IMalloc interface pointer received through the ppMalloc parameter cannot be used from a remote process—each process must have its own allocator.

See Also

IMalloc, CoTaskMemAlloc


CoGetMarshalSizeMax

Returns an upper bound on the number of bytes needed to marshal the specified interface pointer to the specified object.

STDAPI CoGetMarshalSizeMax(

ULONG *pulSize,	//Pointer to the upper-bound value
REFIID riid,	//Reference to the identifier of the interface
IUnknown * pUnk,	//Pointer to the interface to be marshaled
DWORD dwDestContext,	//Destination process
LPVOID pvDestContext,	//Reserved for future use
DWORD mshlflags	//Reason for marshaling
);
Parameters

pulSize

[out] Pointer to the upper-bound value on the size, in bytes, of the data packet to be written to the marshaling stream; a value of zero means that the size of the packet is unknown.

riid

[in] Reference to the identifier of the interface whose pointer is to be marshaled. This interface must be derived from the IUnknown interface.

pUnk

[in] Pointer to the interface to be marshaled; can be NULL. This interface must be derived from the IUnknown interface.

dwDestContext

[in] Destination context where the specified interface is to be unmarshaled. Values for dwDestContext come from the enumeration MSHCTX. Currently, unmarshaling can occur either in another apartment of the current process (MSHCTX_INPROC) or in another process on the same computer as the current process (MSHCTX_LOCAL).

pvDestContext

[in] Reserved for future use; must be NULL.

mshlflags

[in] Flag indicating whether the data to be marshaled is to be transmitted back to the client process—the normal case—or written to a global table, where it can be retrieved by multiple clients. Values come from the enumeration MSHLFLAGS.

Return Values

This function supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The upper bound was returned successfully.

CO_E_NOTINITIALIZED

The CoInitialize or OleInitialize function was not called on the current thread before this function was called.

Remarks

This function performs the following tasks:

1.	Queries the object for an IMarshal pointer or, if the object does not implement IMarshal, gets a pointer to COM’s standard marshaler.

2.	Using whichever pointer is obtained in the preceding step, calls IMarshal::GetMarshalSizeMax.

3.	Adds to the value returned by the call to GetMarshalSizeMax the size of the marshaling data header and, possibly, that of the proxy CLSID to obtain the maximum size in bytes of the amount of data to be written to the marshaling stream.

You do not explicitly call this function unless you are implementing IMarshal, in which case your marshaling stub should call this function to get the correct size of the data packet to be marshaled.

The value returned by this method is guaranteed to be valid only as long as the internal state of the object being marshaled does not change. Therefore, the actual marshaling should be done immediately after this function returns, or the stub runs the risk that the object, because of some change in state, might require more memory to marshal than it originally indicated.

See Also

CoMarshalInterface, IMarshal::GetMarshalSizeMax


CoGetPSClsid

This function returns the CLSID of the DLL that implements the proxy and stub for the specified interface.

WINOLEAPI CoGetPSClsid(

REFIID riid,	// Interface whose proxy/stub CLSID is to be returned
CLSID *pclsid	// Where to store returned proxy/stub CLSID
);
Parameters

riid

[in] The interface whose proxy/stub CLSID is to be returned.

pclsid

[out] Where to store the proxy/stub CLSID for the interface specified by riid.

Return Values

S_OK

The proxy/stub CLSID was successfully returned.

E_INVALIDARG

One of the parameters is invalid.

E_OUTOFMEMORY

There is insufficient memory to complete this operation.

Remarks

The CoGetPSClsid function looks at the HKEY_CLASSES_ROOT\Interfaces\{ string form of riid }\ProxyStubClsid32 key in the registry to determine the CLSID of the DLL to load in order to create the proxy and stub for the interface specified by riid. This function also returns the CLSID for any interface IID registered by CoRegisterPSClsid within the current process.

See Also

CoRegisterPSClsid


CoGetStandardMarshal

Creates a default, or standard, marshaling object in either the client process or the server process, depending on the caller, and returns a pointer to that object’s IMarshal implementation.

STDAPI CoGetStandardMarshal(

REFIID riid,	//Reference to the identifier of the interface
IUnknown * pUnk,	//Pointer to the interface to be marshaled
DWORD dwDestContext,	//Destination process
LPVOID pvDestContext,	//Reserved for future use
DWORD mshlflags,	//Reason for marshaling
LPMARSHAL * ppMarshal	//Indirect pointer to default IMarshal implementation
);
Parameters

riid

[in] Reference to the identifier of the interface whose pointer is to be marshaled. This interface must be derived from the IUnknown interface.

pUnk

[in] Pointer to the interface to be marshaled.

dwDestContext

[in] Destination context where the specified interface is to be unmarshaled. Values for dwDestContext come from the enumeration MSHCTX. Currently, unmarshaling can occur either in another apartment of the current process (MSHCTX_INPROC) or in another process on the same computer as the current process (MSHCTX_LOCAL).

pvDestContext

[in] Reserved for future use; must be NULL.

mshlflags

[in] Flag indicating whether the data to be marshaled is to be transmitted back to the client process—the normal case—or written to a global table, where it can be retrieved by multiple clients. Valid values come from the MSHLFLAGS enumeration.

ppMarshal

[out] Indirect pointer to the standard marshaler.

Return Values

This function supports the standard return values E_FAIL, E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The IMarshal instance was returned successfully.

CO_E_NOTINITIALIZED

The CoInitialize or OleInitialize function was not called on the current thread before this function was called.

Remarks

The CoGetStandardMarshal function creates a default, or standard, marshaling object in either the client process or the server process, as may be necessary, and returns that object’s IMarshal pointer to the caller. If you implement IMarshal, you may want your implementation to call CoGetStandardMarshal as a way of delegating to COM’s default implementation any destination contexts that you don’t fully understand or want to handle. Otherwise, you can ignore this function, which COM calls as part of its internal marshaling procedures.

When the COM library in the client process receives a marshaled interface pointer, it looks for a CLSID to be used in creating a proxy for the purposes of unmarshaling the packet. If the packet does not contain a CLSID for the proxy, COM calls CoGetStandardMarshal, passing a NULL pUnk value. This function creates a standard proxy in the client process and returns a pointer to that proxy’s implementation of IMarshal. COM uses this pointer to call CoUnmarshalInterface to retrieve the pointer to the requested interface.

If your OLE server application’s implementation of IMarshal calls CoGetStandardMarshal, you should pass both the IID of (riid), and a pointer to (pUnk), the interface being requested.

This function performs the following tasks:

1.	Determines whether pUnk is NULL.

2.	If pUnk is NULL, creates a standard interface proxy in the client process for the specified riid and returns the proxy’s IMarshal pointer.

3.	If pUnk is not NULL, checks to see if a marshaler for the object already exists, creates a new one if necessary, and returns the marshaler’s IMarshal pointer.

See Also

IMarshal


CoGetTreatAsClass

Returns the CLSID of an object that can emulate the specified object.

HRESULT CoGetTreatAsClass(

REFCLSID clsidOld,	//CLSID of object that is being emulated
LPCLSID pclsidNew	//Pointer to CLSID for object that can emulate clsidOld
);
Parameters

clsidOld

[in] CLSID of the object that can be emulated (treated as) an object with a different CLSID.

pclsidNew

[out] Pointer to where the CLSID that can emulate clsidOld objects is retrieved. This parameter cannot be NULL. If there is no emulation information for clsidOld objects, the clsidOld parameter is supplied.

Return Values

S_OK

A new CLSID was successfully returned.

S_FALSE

No emulation information for the clsidOld parameter and that the pclsidNew parameter is set to clsidOld.

REGDB_E_READREGDB

An error reading the registry.

This function can also return any of the error values returned by the CLSIDFromString function.

Remarks

CoGetTreatAsClass returns the TreatAs entry in the registry for the specified object. The TreatAs entry, if set, is the CLSID of a registered object (an application) that can emulate the object in question. The TreatAs entry is set through a call to the CoTreatAsClass function. Emulation allows an application to open and edit an object of a different format, while retaining the original format of the object. Objects of the original CLSID are activated and treated as objects of the second CLSID. When the object is saved, this may result in loss of edits not supported by the original format. If there is no TreatAs entry for the specfied object, this function returns the CLSID of the original object (clsidOld).

See Also

CoTreatAsClass


CoImpersonateClient

Allows the server to impersonate the client of the current call for the duration of the call.

HRESULT CoImpersonateClient()

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK

Indicates success.

Remarks

Allows the server to impersonate the client of the current call for the duration of the call. If you do not call CoRevertToSelf, OLE reverts automatically for you. This function will fail unless the object is being called with RPC_C_AUTHN_LEVEL_CONNECT or higher authentication in effect (any authentication level except RPC_C_AUTHN_LEVEL_NONE) This function encapsulates the following sequence of common calls (error handling excluded):

    CoGetCallContext(IID_IServerSecurity, (void**)&pss);

    pss->ImpersonateClient();

    pss->Release();

This helper function encapsulates the process of getting a pointer to an instance of IServerSecurity that contains data about the current call, calling its ImpersonateClient method, and then releasing the pointer.

See Also

IServerSecurity::ImpersonateClient, Security in COM


CoInitialize

The CoInitialize function initializes the Component Object Model(COM) library. You must initialize the library before you can call its functions. Applications must call CoInitialize before they make any other COM library calls except the CoGetMalloc function and memory allocation calls.

HRESULT CoInitialize(

LPVOID pvReserved	//Reserved, must be NULL
);
Parameter

pvReserved

[in] In 32-bit OLE, this parameter must be NULL. The 32-bit version of OLE does not support applications replacing OLE’s allocator and if the parameter is not NULL, CoInitialize returns E_INVALIDARG.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The library was initialized successfully.

S_FALSE

The library is already initialized or that it could not release the default allocator.

Remarks

You need to call this before you call any of the OLE library functions (except CoGetMalloc, to get a pointer to the standard allocator, and the memory allocation functions and methods) unless you call the OleInitialize function, which calls CoInitialize internally.

Typically, CoInitialize is called only once in the process that uses the OLE library. There can be multiple calls, but subsequent calls return S_FALSE. To close the library gracefully, each successful call to CoInitialize, including those that return S_FALSE, must be balanced by a corresponding call to its companion helper function, CoUninitialize.

See Also

CoUninitialize, OleInitialize, Processes and Threads


CoInitializeEx

Initializes the Component Object Model (COM) for use by the current thread. You can call CoinitializeEx in preference to calling CoInitialize, the implementation of which simply calls CoInitializeEx, specifying COINIT_APARTMENTTHREADED.

HRESULT CoInitializeEx(

void *  pvReserved,	//Reserved
DWORD  dwCoInit	//COINIT value
);
Parameters

pvReserved

[in] Reserved for future use; must be NULL.

dwCoInit

[in] This may contain any set of values from the COINIT enumeration except for both apartment and multi-threaded.

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK

Indicates success.

RPC_E_CHANGED_MODE

A previous call to CoInitializeEx specified a concurrency model for this thread different from the one currently specified for this thread.

Remarks

CoInitializeEx initializes the Component Object Model (COM) for use by the current thread. The dwCoInit parameter specifies the type of concurrency control − multi-threaded or apartment-threaded − required by objects created by this thread. A call to CoInitializeEx specifying COINIT_APARTMENTTHREADED is equivalent to a call to CoInitialize, because prior to NT 4.0, the default concurrency control required by objects was apartment-threaded.

Objects created on a multi-threaded COM thread must be able to receive calls on their methods from other threads at any time. Typically, you would implement some form of concurrency control in a multi-threaded object’s code using Win32 synchronization primitives, such as critical sections, semaphores, or mutexes, to protect the object’s data. Objects created on an apartment-threaded COM thread receive calls on their methods from their apartment’s thread only, so calls are serialized, and calls only arrive at message-queue boundaries (PeekMessage, SendMessage).

Applications must call CoInitializeEx or CoInitialize before making any other COM library calls except the CoGetMalloc function and other memory allocation calls (CoTaskMemAlloc, CoTaskMemFree, CoTaskMemReAlloc, and the IMalloc methods on the task allocator supplied by CoGetMalloc).

Typically, CoInitializeEx is called only once by each thread in the process that uses the OLE library. Multiple calls by the same thread are allowed so long as they pass the same concurrency flag, but subsequent valid calls return S_FALSE. To close the library gracefully, each successful call to CoInitialize or CoInitializeEx, including those that return E_INVALIDARG, must be balanced by a corresponding call to CoUninitialize.

Internally, the OleInitialize function calls CoInitializeEx with the COINIT_APARTMENTTHREADED flag. This implies that a thread that uses CoInitializeEx to initialize a thread for multi-threaded object concurrency may not use the features enabled by OleInitialize, because OleInitialize will fail.

See Also

COINIT, CoInitialize, Processes and Threads


CoInitializeSecurity

Registers security and sets the default security values. For legacy applications, COM automatically calls this function with values from the registry.

HRESULT CoInitializeSecurity(

PSECURITY_DESCRIPTOR   pVoid,	//Points to security descriptor
DWORD  cAuthSvc,	//Count of entries in asAuthSvc
SOLE_AUTHENTICATION_SERVICE * asAuthSvc,	//Array of names to register
void * pReserved1,	//Reserved for future use
DWORD  dwAuthnLevel,	//The default authentication level for proxies
DWORD  dwImpLevel,	//The default impersonation level for proxies
RPC_AUTH_IDENTITY_HANDLE  pAuthInfo,	//Reserved; must be set to NULL
DWORD  dwCapabilities,	//Additional client and/or server-side capabilities
void * pvReserved2	//Reserved for future use
);
Parameters

pVoid

[in] Security descriptor. If NULL, no ACL checking will be done. If not NULL, COM will check ACLs on new connections. If not NULL, dwAuthnLevel cannot be RPC_C_AUTHN_LEVEL_NONE.

cAuthSvc

[in] Count of entries in asAuthSvc. Zero means register no services. A value of -1 tells COM to choose which authentication services to register.

asAuthSvc

[in] Array of authentication/authorization/principal names to register. These values are registered to allow incoming calls. After that they are ignored. The default authentication/authorization/principal for each proxy will be negotiated regardless of whether these are set. For example, if the application registers RPC_C_AUTHN_WINNT and receives and interface from a machine that only supports RPC_C_AUTHN_DEC_PUBLIC, COM will choose RPC_C_AUTHN_DEC_PUBLIC if this machine supports it.

pReserved1

[in] Reserved for future use; must be NULL.

dwAuthnLevel

[in] The default authentication level for proxies. On the server side, COM will fail calls that arrive at a lower level. All calls to AddRef and Release are made at this level.

dwImpLevel

[in] The default impersonation level for proxies. This value is not checked on the server side. AddRef and Release calls are made with this impersonation level so even security aware apps should set this carefully. Setting IUnknown security only affects calls to QueryInterface, not AddRef or Release.

pAuthInfo

[in] Reserved for future use; must be NULL.

dwCapabilities

[in] Additional client and/or server-side capabilities. Any set of EOAC flags may be passed. Currently only EOAC_MUTUAL_AUTH, EOAC_SECURE_REFS, and EOAC_NONE are defined.

pReserved2

[in] Reserved for future use; must be zero.

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK

Indicates success.

Remarks

The CoInitializeSecurity layer initializes the security layer and sets the specified values as the security default. The pSecDesc parameter contains two ACLs. The discretionary ACL (DACL) indicates who is allowed to call this process and who is explicitly denied. The system ACL (SACL) contains audit information; this is not supported in the current release, so this portion of pSecDesc must be NULL, so there is no auditing.

A NULL DACL will allow calls from anyone. A DACL with no ACEs allows no access. For information on ACLs and ACEs, refer to Win32 Programmers Reference/Overviews/System Services/Security/Security/Security Model.

The owner and group of the SECURITY_DESCRIPTOR must be set — applications should call AccessCheck (not IsValidSecurityDescriptor) to ensure that their security descriptor is correctly formed prior to calling CoInitializeSecurity.

If the application passes a NULL security descriptor, COM will construct one that allows calls from the current user and local system. All new connections will be audited. Distributed COM will copy the security descriptor.

If mutual authentication is enabled all calls will fail unless the server identity is verified to match the principal name set on the proxy. Without mutual authentication, security only helps the server; the client has no idea who is handling his call. While CoInitializeSecurity takes principal names as parameters, that does not mean that the server can register any arbitrary name. The security provider verifies that the server has a right to use the names registered.

Secure references cause DCOM to make extra callbacks to insure that objects are not released maliciously.

See Also

RPC_C_IMP_LEVEL_xxx, RPC_C_AUTHN_LEVEL_xxx, Security in COM


CoIsHandlerConnected

Determines whether a remote object is connected to the corresponding in-process object.

BOOL CoIsHandlerConnected(

LPUNKNOWN pUnk	//Pointer to the remote object
);
Parameter

pUnk

[in] Pointer to the controlling IUnknown interface on the remote object.

Return Values

TRUE

The object is not remote or that it is remote and is still connected to its remote handler.

FALSE

The object is remote and is invalid (no longer connected to its remote handler).

Remarks

The CoIsHandlerConnected function determines the status of a remote object. You can use it to determine when to release a remote object. You specify the remote object by giving the function a pointer to its controlling IUnknown interface (the pUnk parameter). A TRUE returned from the function indicates either that the specified object is not remote, or that it is remote and is still connected to its remote handler. A FALSE returned from the function indicates that the object is remote but is no longer connected to its remote handler; in this case, the caller should respond by releasing the object.


CoIsOle1Class

Determines if a given CLSID represents an OLE 1 object.

BOOL CoIsOle1Class(

REFCLSID rclsid	//CLSID to check
);
Parameter

rclsid

[in] CLSID to check.

Return Values

S_TRUE

CLSID refers to an OLE 1 object.

S_FALSE

CLSID does not refer to an OLE 1 object.

Remarks

CoIsOle1Class determines whether an object class is from OLE 1. You can use it to prevent linking to embedded OLE 1 objects within a container, which OLE 1 objects do not support. Once a container has determined that copied data represents an embedded object, the container code can call CoIsOle1Class to determine whether the embedded object is an OLE 1 object. If CoIsOle1Class returns S_TRUE, the container does not offer CF_LINKSOURCE as one of its clipboard formats. This is one of several OLE compatibility functions. Other compatibility functions, listed below, can be used to convert the storage formats of objects between OLE 1 and OLE.

See Also

OleConvertIStorageToOLESTREAM, OleConvertIStorageToOLESTREAMEx, OleConvertOLESTREAMToIStorage, OleConvertOLESTREAMToIStorageEx


CoLoadLibrary

Loads a specific DLL into the caller’s process. The CoGetClassObject function calls CoLoadLibrary internally; applications should not call it directly.

HINSTANCE CoLoadLibrary(

LPOLESTR lpszLibName,	//Pointer to the name of the library to be loaded
BOOL bAutoFree	//Whether library is automatically freed
);
Parameters

lpszLibName

[in] Pointer to the name of the library to be loaded. The use of this name is the same as in the Win32 function LoadLibrary.

bAutoFree

[in] If TRUE, indicates that this library is freed when it is no longer needed, through a call to either the CoFreeUnusedLibraries or CoUninitialize functions. If FALSE, the library should be explicitly freed with the CoFreeLibrary function.

Return Values

Module Handle

Handle of the loaded library.

NULL

Library could not be loaded.

Remarks

The CoLoadLibrary function is called internally by the CoGetClassObject function when the class context (CLSCTX) indicates a DLL. CoLoadLibrary loads a DLL specified by the lpszLibName parameter into the process that called CoGetClassObject. Containers should not call CoLoadLibrary directly.

Internally, a reference count is kept on the loaded DLL, by using CoLoadLibrary to increment the count and the CoFreeLibrary function to decrement it.

See Also

CoFreeAllLibraries, CoFreeLibrary, CoFreeUnusedLibraries, CoGetClassObject


CoLockObjectExternal

Called either to lock an object to ensure that it stays in memory, or to release such a lock. Call CoLockObjectExternal to place a strong lock on an object to ensure that it stays in memory.

STDAPI CoLockObjectExternal(

IUnknown * pUnk,	//Pointer to object to be locked or unlocked
BOOL fLock,	//TRUE = lock, FALSE = unlock
BOOL fLastUnlockReleases	//TRUE = release all pointers to object
);
Parameters

pUnk

[in] Pointer to the IUnknown interface on the object to be locked or unlocked.

fLock

[in] Whether the object is to be locked or released. Specifying TRUE holds a reference to the object (keeping it in memory), locking it independently of external or internal AddRef/Release operations, registrations, or revocations. If fLock is TRUE, fLastLockReleases is ignored. FALSE releases a lock previously set with a call to this function.

fLastUnlockReleases

[in] Whether a given lock is the last reference that is supposed to keep an object alive. If it is, TRUE releases all pointers to the object (there may be other references that are not supposed to keep it alive).

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The object was locked successfully.

Remarks

The CoLockObjectExternal function prevents the reference count of an object from going to zero, thereby “locking” it into existence until the lock is released. The same function (with different parameters) releases the lock. The lock is implemented by having the system call IUnknown::AddRef on the object. The system then waits to call IUnknown::Release on the object until a later call to CoLockObjectExternal with fLock set to FALSE. This function can be used to maintain a reference count on the object on behalf of the end user, because it acts outside of the object, as does the user.

The CoLockObjectExternal function must be called in the process in which the object actually resides (the EXE process, not the process in which handlers may be loaded).

Calling CoLockObjectExternal sets a strong lock on an object. A strong lock keeps an object in memory, while a weak lock does not. Strong locks are required, for example, during a silent update to an OLE embedding. The embedded object’s container must remain in memory until the update process is complete. There must also be a strong lock on an application object to ensure that the application stays alive until it has finished providing services to its clients. All external references place a strong reference lock on an object.

The CoLockObjectExternal function is typically called in the following situations:

•	Object servers should call CoLockObjectExternal with both fLock and fLastLockReleases set to TRUE when they become visible. This call creates a strong lock on behalf of the user. When the application is closing, free the lock with a call to CoLockObjectExternal, setting fLock to FALSE and fLastLockReleases to TRUE.

•	A call to CoLockObjectExternal on the server can also be used in the implementation of IOleContainer::LockContainer.

There are several things to be aware of when you use CoLockObjectExternal in the implementation of IOleContainer::LockContainer. An embedded object would call IOleContainer::LockContainer on its container to keep it running (to lock it) in the absence of other reasons to keep it running. When the embedded object becomes visible, the container must weaken its connection to the embedded object with a call to the OleSetContainedObject function, so other connections can affect the object.

Unless an application manages all aspects of its application and document shutdown completely with calls to CoLockObjectExternal, the container must keep a private lock count in IOleContainer::LockContainer so that it exits when the lock count reaches zero and the container is invisible. Maintaining all aspects of shutdown, and thereby avoiding keeping a private lock count, means that CoLockObjectExternal should be called whenever one of the following conditions occur:

•	A document is created and destroyed or made visible or invisible.

•	An application is started and shut down by the user.

•	A pseudo-object is created and destroyed.

For debugging purposes, it may be useful to keep a count of the number of external locks (and unlocks) set on the application.

Note  The end user has explicit control over the lifetime of an application, even if there are external locks on it. That is, if a user decides to close the application (File, Exit), it must shut down. In the presence of external locks (such as the lock set by CoLockObjectExternal), the application can call the CoDisconnectObject function to force these connections to close prior to shutdown.

See Also

IOleContainer::LockContainer, OleSetContainedObject


CoMarshalHresult

Marshals an HRESULT to the specified stream, from which it can be unmarshaled using the CoUnmarshalHresult function.

STDAPI CoMarshalHresult(

IStream * pStm,	//Pointer to the marshaling stream
HRESULT hresult	//HRESULT to be marshaled
);
Parameters

pStm

[in] Pointer to the marshaling stream.

hresult

[in] HRESULT in the originating process.

Return Values

This function supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The HRESULT was marshaled successfully.

STG_E_INVALIDPOINTER

Bad pointer passed in for pStm.

STG_E_MEDIUMFULL

The medium is full.

Remarks

An HRESULT is process-specific, so an HRESULT that is valid in one process might not be valid in another. If you are writing your own implementation of IMarshal and need to marshal an HRESULT from one process to another, either as a parameter or a return code, you must call this function. In other circumstances, you will have no need to call this function.

This function perfoms the following tasks:

1.	Writes an HRESULT to a stream.

2.	Returns an IStream pointer to that stream.

See Also

CoUnmarshalHresult, IStream


CoMarshalInterface

Writes into a stream the data required to initialize a proxy object in some client process. The COM library in the client process calls the CoUnmarshalInterface function to extract the data and initialize the proxy. CoMarshalInterface can marshal only interfaces derived from IUnknown.

STDAPI CoMarshalInterface(

IStream *pStm,	//Pointer to the stream used for marshaling
REFIID riid,	//Reference to the identifier of the interface
IUnknown *pUnk,	//Pointer to the interface to be marshaled
DWORD dwDestContext,	//Destination context
void *pvDestContext,	//Reserved for future use
DWORD mshlflags	//Reason for marshaling
);
Parameters

pStm

[in] Pointer to the stream to be used during marshaling.

riid

[in] Reference to the identifier of the interface to be marshaled. This interface must be derived from the IUnknown interface.

pUnk

[in] Pointer to the interface to be marshaled; can be NULL if the caller does not have a pointer to the desired interface. This interface must be derived from the IUnknown interface.

dwDestContext

[in] Destination context where the specified interface is to be unmarshaled. Values for dwDestContext come from the enumeration MSHCTX. Currently, unmarshaling can occur either in another apartment of the current process (MSHCTX_INPROC) or in another process on the same computer as the current process (MSHCTX_LOCAL).

pvDestContext

[in] Reserved for future use; must be NULL.

mshlflags

[in] Flag specifying whether the data to be marshaled is to be transmitted back to the client process—the normal case—or written to a global table, where it can be retrieved by multiple clients. Values come from the MSHLFLAGS enumeration.

Return Values

This function supports the standard return values E_FAIL, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The interface pointer was marshaled successfully.

CO_E_NOTINITIALIZED

The CoInitialize or OleInitialize function was not called on the current thread before this function was called.

IStream errors

This function can also return any of the stream-access error values returned by the IStream interface.

Remarks

The CoMarshalInterface function marshals the interface referred to by riid on the object whose IUnknown implementation is pointed to by pUnk. To do so, the CoMarshalInterface function performs the following tasks:

1.	Queries the object for a pointer to the IMarshal interface. If the object does not implement IMarshal, meaning that it relies on COM to provide marshaling support, CoMarshalInterface gets a pointer to COM’s default implementation of IMarshal.

2.	Gets the CLSID of the object’s proxy by calling IMarshal::GetUnmarshalClass, using whichever IMarshal interface pointer has been returned.

3.	Writes the CLSID of the proxy to the stream to be used for marshaling.

4.	Marshals the interface pointer by calling IMarshal::MarshalInterface.

If you are implementing existing COM interfaces or defining your own interfaces using the Microsoft Interface Definition Language (MIDL), the MIDL-generated proxies and stubs call CoMarshalInterface for you. If you are writing your own proxies and stubs, your proxy code and stub code should each call CoMarshalInterface to correctly marshal interface pointers. Calling IMarshal directly from your proxy and stub code is not recommended.

If you are writing your own implementation of IMarshal, and your proxy needs access to a private object, you can include an interface pointer to that object as part of the data you write to the stream. In such situations, if you want to use COM’s default marshaling implementation when passing the interface pointer, you can call CoMarshalInterface on the object to do so.

See Also

CoUnmarshalInterface, IMarshal::MarshalInterface


CoMarshalInterThreadInterfaceInStream

Marshals an interface pointer from one thread to another thread in the same process.

HRESULT CoMarshalInterThreadInterfaceInStream(

REFIID riid,	//Reference to the identifier of the interface
LPUNKNOWN pUnk,	//Pointer to the interface to be marshaled
LPSTREAM * ppStm	//Indirect pointer
);
Parameters

riid

[in] Reference to the identifier of the interface to be marshaled.

pUnk

[in] Pointer to the interface to be marshaled, which must be derived from IUnknown; can be NULL.

ppStm

[out] Indirect pointer to the stream that contains the marshaled interface.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The interface was marshaled successfully.

Remarks

The CoMarshalInterThreadInterfaceInStream function enables an object to easily and reliably marshal an interface pointer to another thread in the same process. The stream returned in ppStm is guaranteed to behave correctly when a client running in the receiving thread attempts to unmarshal the pointer. The client can then call the CoGetInterfaceAndReleaseStream to unmarshal the interface pointer and release the stream object.

The CoMarshalInterThreadInterfaceInStream function performs the following tasks:

1.	Creates a stream object.

2.	Passes the stream object’s IStream pointer to CoMarshalInterface.

3.	Returns the IStream pointer to the caller.

See Also

CoGetInterfaceAndReleaseStream


CoQueryAuthenticationServices

Retrieves a list of the authentication services registered when the process called CoInitializeSecurity.

HRESULT CoQueryAuthenticationServices(

DWORD * pcAuthSvc,	//Pointer to the number of entries returned in the array
SOLE_AUTHENTICATION_SERVICE**  prgAuthSvc	//Pointer to an array of structures
);
Parameters

pcAuthSvc

[out] Pointer to return the number of entries returned in the rgAuthSvc array. May not be NULL.

prgAuthSvc

[out] Pointer to an array of SOLE_AUTHENTICATION_SERVICE structures. The list is allocated through a call to CoTaskMemAlloc. The caller must free the list when finished with it by calling CoTaskMemFree.

Return Values

This function supports the standard return values E_INVALIDARG and

E_OUTOFMEMORY, as well as the following:

S_OK

Indicates success.

Remarks

CoQueryAuthenticationServices retrieves a list of the authentication services currently registered. If the process calls CoInitializeSecurity, these are the services registered through that call; if not, those registered by default by OLE.

This function is primarily useful for custom marshalers, to determine which principal names an application can use.

Different authentication services support different levels of security. For example, NTLMSSP does not support delegation or mutual authentication while Kerberos does. The application is responsible only for registering authentication services that provide the features the application needs. This is the way to query which services have been registered with CoInitializeSecurity.

See Also

CoInitializeSecurity, SOLE_AUTHENTICATION_SERVICE structure, Security in COM


CoQueryClientBlanket

Called by the server to find out about the client that invoked the method executing on the current thread.

HRESULT CoQueryClientBlanket(

DWORD*  pAuthnSvc,	//Pointer to the current authentication service
DWORD*  pAuthzSvc,	//Pointer to the current authorization service
OLECHAR **  pServerPrincName,	//Pointer to the current principal name
DWORD * pAuthnLevel,	//Pointer to the current authentication level
DWORD * pImpLevel,	//Must be NULL
void **  ppPrivs,	//Pointer to unicode string identifying client
DWORD **  pCapabilities	//Pointer to flags indicating further capabilities of the proxy
);
Parameters

pAuthnSvc

[out] Pointer to a DWORD value defining the current authentication service. This will be a single value taken from the list of RPC_C_AUTHN_xxx constants. May be NULL, in which case the current authentication service is not returned.

pAuthzSvc

[out] Pointer to a DWORD value defining the current authorization service. This will be a single value taken from the list of RPC_C_AUTHZ_xxx constants. May be NULL, in which case the current authorization service is not returned.

pServerPrincName

[out] Pointer to the current principal name. The string will be allocated by the callee using CoTaskMemAlloc and must be freed by the caller using CoTaskMemFree when they are done with it. May be NULL, in which case the principal name is not returned.

pAuthnLevel

[out] Pointer to a DWORD value defining the current authentication level. This will be a single value taken from the list of RPC_C_AUTHN_LEVEL_xxx constants. May be NULL, in which case the current authentication level is not returned.

pImpLevel

[out] Must be NULL; does not supplythe current impersonation level is not returned.

pPrivs

[out] Pointer to a unicode string identifying the client. This string is not a copy, the user must not change it or free it. The string is not valid past the end of the call. For NTLMSSP the string is of the form domain\user.

pCapabilities

[out] Pointer to flags indicating further capabilities of the call. Currently, no flags are defined for this parameter and the value retrieved is EOAC_NONE. May be NULL, in which case no value is retrieved. EOAC_MUTUAL_AUTH is defined but not used by NTLMSSP. Third party security providers may return that flag.

Return Values

S_OK

Success.

E_INVALIDARG

One or more arguments are invalid.

E_OUTOFMEMORY

Insufficient memory to create the pServerPrincName out-parameter.

Remarks

CoQueryClientBlanket is called by the server to get security information about the client that invoked the method executing on the current thread. This function encapsulates the following sequence of common calls (error handling excluded):

    CoGetCallContext(IID_IServerSecurity, (void**)&pss);

    pss->QueryBlanket(pAuthnSvc, pAuthzSvc, pServerPrincName,

                pAuthnLevel, pImpLevel, pPrivs, pCapabilities);

    pss->Release();

See Also

IServerSecurity::QueryBlanket, Security in COM


CoQueryProxyBlanket

Retrieves the authentication information the client uses to make calls on the specified proxy.

HRESULT CoQueryProxyBlanket(

void*  pProxy,	//Location for the proxy to query
DWORD*  pAuthnSvc,	//Location for the the current authorization service
DWORD*  pAuthzSvc,	//Location for the the current authorization service
OLECHAR **  pServerPrincName,	//Location for the current principal name
DWORD * pAuthnLevel,	//Location for the current authentication level
DWORD * pImpLevel,	//Location for the current impersonation level
RPC_AUTH_IDENTITY_HANDLE **  ppAuthInfo,	//Location for the value passed to IClientSecurity::SetBlanket
DWORD **  pCapabilities	//Location for flags indicating further capabilities of the proxy
);
Parameters

pProxy

[in] Pointer to an interface on the proxy to query.

pAuthnSvc

[out] Pointer to a DWORD value defining the current authentication service. This will be a single value taken from the list of RPC_C_AUTHN_xxx constants. May be NULL, in which case the current authentication service is not retrieved.

pAuthzSvc

[out] Pointer to a DWORD value defining the current authorization service. This will be a single value taken from the list of RPC_C_AUTHZ_xxx constants. May be NULL, in which case the current authorization service is not retrieved.

pServerPrincName

[out] Pointer to the current principal name. The string will be allocated by the one called using CoTaskMemAlloc and must be freed by the caller using CoTaskMemFree when they are done with it. May be NULL, in which case the principal name is not retrieved.

pAuthnLevel

[out] Pointer to a DWORD value defining the current authentication level. This will be a single value taken from the list of RPC_C_AUTHN_LEVEL_xxx constants. May be NULL, in which case the current authentication level is not retrieved.

pImpLevel

[out] Pointer to a DWORD value defining the current impersonation level. This will be a single value taken from the list of RPC_C_IMP_LEVEL_xxx constants. May be NULL, in which case the current authentication level is not retrieved.

ppAuthInfo

[out] Pointer to the pointer value passed to IClientSecurity::SetBlanket indicating the identity of the client. Because this points to the value itself and is not a copy, it should not be manipulated. May be NULL, in which case the information is not retrieved.

pCapabilities

[out] Pointer to a DWORD of flags indicating further capabilities of the proxy. Currently, no flags are defined for this parameter and it will only return EOAC_NONE. May be NULL, in which case the flags indicating further capabilities are not retrieved.

Return Values

S_OK

Success.

E_INVALIDARG

One or more arguments are invalid.

E_OUTOFMEMORY

Insufficient memory to create the pasAuthnSvc out-parameter.

Remarks

CoQueryProxyBlanket is called by the client to retrieve the authentication information COM will use on calls made from the specified proxy. This function encapsulates the following sequence of common calls (error handling excluded):

pProxy->QueryInterface(IID_IClientSecurity, (void**)&pcs);

pcs->QueryBlanket(pProxy, pAuthnSvc, pAuthzSvc, pServerPrincName,

                 pAuthnLevel, pImpLevel, ppAuthInfo, pCapabilities);

pcs->Release();

This sequence calls QueryInterface on the proxy for IClientSecurity, and with the resulting pointer, calls IClientSecurity::QueryBlanket, and then releases the pointer.

In pProxy, you can pass any proxy, such as a proxy you get through a call to CoCreateInstance, CoUnmarshalInterface, or just passing an interface pointer as a parameter. It can be any interface. You cannot pass a pointer to something that is not a proxy. Thus you can’t pass a pointer to an interface that has the local keyword in its interface definition since no proxy is created for such an interface. IUnknown is the exception.

See Also

IClientSecurity::QueryBlanket, Security in COM


CoRegisterClassObject

Registers an EXE class object with OLE so other applications can connect to it. EXE object applications should call CoRegisterClassObject on startup. It can also be used to register internal objects for use by the same EXE or other code (such as DLLs) that the EXE uses.

STDAPI CoRegisterClassObject(

REFCLSID rclsid,	//Class identifier (CLSID) to be registered
IUnknown * pUnk,	//Pointer to the class object
DWORD dwClsContext,	//Context for running executable code
DWORD flags,	//How to connect to the class object
LPDWORD * lpdwRegister	//Pointer to the value returned
);
Parameters

rclsid

[in] CLSID to be registered.

pUnk

[in] Pointer to theIUnknown interface on the class object whose availability is being published.

dwClsContext

[in] Context in which the executable code is to be run. For information on these context values, see the CLSCTX enumeration.

flags

[in] How connections are made to the class object. For information on these flags, see the REGCLS enumeration.

lpdwRegister

[out] Pointer to a value that identifies the class object registered; later used by the CoRevokeClassObject function to revoke the registration.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The class object was registered successfully.

CO_E_OBJISREG

Already registered in the class object table.

Remarks

Only EXE object applications call CoRegisterClassObject. Object handlers or DLL object applications do not call this function — instead, they must implement and export the DllGetClassObject function.

At startup, a multiple-use EXE object application must create a class object (with the IClassFactory interface on it), and call CoRegisterClassObject to register the class object. Object applications that support several different classes (such as multiple types of embeddable objects) must allocate and register a different class object for each.

Multiple registrations of the same class object are independent and do not produce an error. Each subsequent registration yields a unique key in lpdwRegister.

Multiple document interface (MDI) applications must register their class objects. Single document interface (SDI) applications must register their class objects only if they can be started by means of the /Embedding switch.

The server for a class object should call CoRevokeClassObject to revoke the class object (remove its registration) when all of the following are true:

•	There are no existing instances of the object definition

•	There are no locks on the class object

•	The application providing services to the class object is not under user control (not visible to the user on the display).

After the class object is revoked, when its reference count reaches zero, the class object can be released, allowing the application to exit.

For information on the flags parameter, refer to the REGCLS enumeration.

See Also

CoGetClassObject, CoRevokeClassObject, DllGetClassObject, REGCLS, CLSCTX


CoRegisterMallocSpy

Registers an implementation of the IMallocSpy interface in OLE, thereafter requiring OLE to call its wrapper methods around every call to the corresponding IMalloc method. IMallocSpy is defined in OLE to allow developers to debug memory allocations.

HRESULT CoRegisterMallocSpy(

LPMALLOCSPY pMallocSpy	//Pointer to the interface
);
Parameter

pMallocSpy

[in] Pointer to an instance of the IMallocSpy implementation.

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK

The IMallocSpy object is successfully registered.

CO_E_OBJISREG

There is already a registered spy.

Remarks

The CoRegisterMallocSpy function registers the IMallocSpy object, which is used to debug calls to IMalloc methods. The function calls QueryInterface on the pointer pMallocSpy for the interface IID_IMallocSpy. This is to ensure that pMallocSpy really points to an implementation of IMallocSpy. By the rules of OLE, it is expected that a successful call to QueryInterface has added a reference (through the AddRef method) to the IMallocSpy object. That is, CoRegisterMallocSpy does not directly call AddRef on pMallocSpy, but fully expects that the QueryInterface call will.

When the IMallocSpy object is registered, whenever there is a call to one of the IMalloc methods, OLE first calls the corresponding IMallocSpy pre-method. Then, after executing the IMalloc method, OLE calls the corresponding IMallocSpy post-method. For example, whenever there is a call to IMalloc::Alloc, from whatever source, OLE calls IMallocSpy::PreAlloc, calls IMalloc::Alloc, and after that allocation is completed, calls IMallocSpy::PostAlloc.

See Also

IMallocSpy, CoRevokeMallocSpy, CoGetMalloc


CoRegisterMessageFilter

Registers with OLE the instance of an EXE application’s IMessageFilter interface, which is to be used for handling concurrency issues. DLL object applications cannot register a message filter.

HRESULT CoRegisterMessageFilter(

LPMESSAGEFILTER lpMessageFilter,	//Pointer to interface
LPMESSAGEFILTER * lplpMessageFilter	//Indirect pointer to prior instance if non-NULL
);
Parameters

lpMessageFilter

[in] Pointer to theIMessageFilter interface on the message filter supplied by the application. Can be NULL, indicating that the current IMessageFilter registration should be revoked.

lplpMessageFilter

[out] If a message filter has been previously registered, indirect pointer to an IMessageFilter interface to that instance. If the value of this parameter on return is NULL, this indicates that no previous IMessageFilter instance was registered. This parameter rarely returns NULL, however, returning instead a pointer to the default message filter.

Return Values

S_OK

The IMessageFilter instance registered or revoked successfully.

S_FALSE

Error registering or revoking IMessageFilter instance.


CoRegisterPSClsid

Enables a downloaded DLL to register its custom interfaces within its running process so that the marshaling code will be able to marshal those interfaces.

WINOLEAPI CoRegisterPSCLsid(

REFIID riid,	// Custom interface to be registered
REFCLSID rclsid	// DLL containing the proxy/stub code for riid
);
Parameters

riid

[in] Points to the IID of the interface to be registered.

rclsid

[in] Points to the CLSID of the DLL that contains the proxy/stub code for the custom interface specified by riid.

Return Values

S_OK

The custom interface was successfully registered.

E_INVALIDARG

One of the parameters is invalid.

E_OUTOFMEMORY

There is insufficient memory to complete this operation.

Remarks

Normally the code responsible for marshaling an interface pointer into the current running process reads the HKEY_CLASSES_ROOT\Interfaces section of the registry to obtain the CLSID of the DLL containing the ProxyStub code to be loaded. To obtain the ProxyStub CLSIDs for an existing interface, the code calls the CoGetPSClsid function.

In some cases, however, it may be desirable or necessary for an in-process handler or in-process server to make its custom interfaces available without writing to the registry. A DLL downloaded across a network may not even have permission to access the local registry, and because the code originated on another machine, the user, for security purposes, may want to run it in a restricted environment. Or a DLL may have custom interfaces that it uses to talk to a remote server and may also include the ProxyStub code for those interfaces. In such cases, a DLL needs an alternative way to register its interfaces. CoRegisterPSClsid, used in conjunction with CoRegisterClassObject, provides that alternative.

A DLL would normally call CoRegisterPSClsid as shown in the following code fragment:

HRESULT RegisterMyCustomInterface(DWORD *pdwRegistrationKey)
{
    HRESULT hr = CoRegisterClassObject(CLSID_MyProxyStubClsid,
        pIPSFactoryBuffer,
        CLSCTX_INPROC_SERVER,
        REGCLS_MULTIPLEUSE
        pdwRegistrationKey);
    if(SUCCEEDED)(hr))
    {
        hr = CoRegisterPSClsid(IID_MyCustomInterface, CLSID_MyProxyStubClsid);
    }

    return hr;
}

See Also

CoGetPSClsid, CoRegisterClassObject


CoReleaseMarshalData

Destroys a previously marshaled data packet.

STDAPI CoReleaseMarshalData(

IStream * pStm	//Pointer to stream containing data packet
);
Parameter

pStm

[in] Pointer to the stream that contains the data packet to be destroyed.

Return Values

This function supports the standard return values E_FAIL, E_INVALIDARG,

E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The data packet was successfully destroyed.

STG_E_INVALIDPOINTER

An IStream error dealing with the pStm parameter.

CO_E_NOTINITIALIZED

The CoInitialize or OleInitialize function was not called on the current thread before this function was called.

Remarks

The CoReleaseMarshalData function performs the following tasks:

1.	The function reads a CLSID from the stream.

2.	If COM’s default marshaling implementation is being used, the function gets an IMarshal pointer to an instance of the standard unmarshaler. If custom marshaling is being used, the function creates a proxy by calling the CoCreateInstance function, passing the CLSID it read from the stream, and requesings an IMarshal interface pointer to the newly created proxy.

3.	Using whichever IMarshal interface pointer it has acquired, the function calls IMarshal::ReleaseMarshalData.

You typically do not call this function. The only situation in which you might need to call this function is if you use custom marshaling (write and use your own implementation of IMarshal). Examples of when CoReleaseMarshalData should be called include the following situations:

•	An attempt was made to unmarshal the data packet, but it failed.

•	A marshaled data packet was removed from a global table.

As an analogy, the data packet can be thought of as a reference to the original object, just as if it were another interface pointer being held on the object. Like a real interface pointer, that data packet must be released at some point. The use of IMarshal::ReleaseMarshalData to release data packets is analogous to the use of IUnknown::Release to release interface pointers.

Note that you do not need to call CoReleaseMarshalData after a successful call of the CoUnmarshalInterface function; that function releases the marshal data as part of the processing that it does.

See Also

IMarshal::ReleaseMarshalData


CoReleaseServerProcess

Decrements the global per-process reference count

ULONG CoReleaseServerProcess(void);

Return Values

S_OK

The CLSID was retrieved successfully.

Remarks

Servers can call CoReleaseServerProcess to decrement a global per-process reference count incremented through a call to CoAddRefServerProcess

When that count reaches zero, OLE automatically calls CoSuspendClassObjects, which prevents new activation requests from coming in. This permits the server to deregister its class objects from its various threads without worry that another activation request may come in. New activation requests result in launching a new instance of the local server process.

The simplest way for a local server application to make use of these API functions is to call CoAddRefServerProcess in the constructor for each of its instance objects, and in each of its IClassFactory::LockServer methods when the fLock parameter is TRUE. The server application should also call CoReleaseServerProcess in the destruction of each of its instance objects, and in each of its IClassFactory::LockServer methods when the fLock parameter is FALSE. Finally, the server application must check the return code from CoReleaseServerProcess; if it returns 0, the server application should initiate its cleanup. This typically means that a server with multiple threads should signal its various threads to exit their message loops and call CoRevokeClassObject and CoUninitialize.

If these APIs are used at all, they must be called in both the object instances and the LockServer method, otherwise the server application may be shutdown prematurely. In-process Servers typically should not call CoAddRefServerProcess or CoReleaseServerProcess.

See Also

CoSuspendClassObjects, CoReleaseServerProcess, IClassFactory::LockServer, Out-of-process Server Implementation Helpers


CoResumeClassObjects

Called by a server that can register multiple class objects to inform the OLE SCM about all registered classes, and permits activation requests for those class objects.

WINOLEAPI CoResumeClassObjects(void);

Return Values

S_OK

The CLSID was retrieved successfully.

Remarks

Servers that can register multiple class objects call CoResumeClassObjects once, after having first called CoRegisterClassObject, specifying REGCLS_LOCAL_SERVER | REGCLS_SUSPENDED for each CLSID the server supports. This function causes OLE to inform the SCM about all the registered classes, and begins letting activation requests into the server process.

This reduces the overall registration time, and thus the server application startup time, by making a single call to the SCM, no matter how many CLSIDs are registered for the server. Another advantage is that if the server has multiple apartments with different CLSIDs registered in different apartments, or is a free-threaded server,  no activation requests will come in until the server calls CoResumeClassObjects. This gives the server a chance to register all of its CLSIDs and get properly set up before having to deal with activation requests, and possibly shutdown requests.

See Also

CoRegisterClassObject, CoSuspendClassObjects, Out-of-process Server Implementation Helpers


CoRevertToSelf

Restores the authentication information on a thread of execution to its previous identity.

HRESULT CoRevertToSelf()

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK

Indicates success.

Remarks

CoRevertToSelf restores the authentication information on a thread of execution to its previous identity after a previous server call to CoImpersonateClient. This is a helper function that encapsulates the following common sequence of calls (error handling excluded):

    CoGetCallContext(IID_IServerSecurity, (void**)&pss);

    pss->RevertToSelf();

    pss->Release();

See Also

IServerSecurity::RevertToSelf, CoGetCallContext, Security in COM


CoRevokeClassObject

Informs OLE that a class object, previously registered with the CoRegisterClassObject function, is no longer available for use.

HRESULT CoRevokeClassObject(

DWORD dwRegister	//Token on class object
);
Parameter

dwRegister

[in] Token previously returned from the CoRegisterClassObject function.

Return Values

This function supports the standard return values E_INVALIDARG,

E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The class object was successfully revoked.

Remarks

A successful call to CoRevokeClassObject means that the class object has been removed from the global class object table (although it does not release the class object). If other clients still have pointers to the class object and have caused the reference count to be incremented by calls to IUnknown::AddRef, the reference count will not be zero. When this occurs, applications may benefit if subsequent calls (with the obvious exceptions of IUnknown::AddRef and IUnknown::Release) to the class object fail.

An object application must call CoRevokeClassObject to revoke registered class objects before exiting the program. Class object implementers should call CoRevokeClassObject as part of the release sequence. You must specifically revoke the class object even when you have specified the flags value REGCLS_SINGLEUSE in a call to CoRegisterClassObject, indicating that only one application can connect to the class object.

See Also

CoGetClassObject, CoRegisterClassObject


CoRevokeMallocSpy

Revokes a registered IMallocSpy object.

HRESULT CoRevokeMallocSpy();

Return Values

S_OK

The IMallocSpy object is successfully revoked.

CO_E_OBJNOTREG

No spy is currently registered.

E_ACCESSDENIED

Spy is registered but there are outstanding allocations (not yet freed) made while this spy was active.

Remarks

The IMallocSpy object is released when it is revoked. This release corresponds to the call to IUnknown::AddRef in the implementation of the QueryInterface function by the CoRegisterMallocSpy function. The implementation of the IMallocSpy interface should then do any appropriate cleanup.

If the return code is E_ACCESSDENIED, there are still outstanding allocations that were made while the spy was active. In this case, the registered spy cannot be revoked at this time because it may have attached arbitrary headers and/or trailers to these allocations that only the spy knows about. Only the spy’s PreFree (or PreRealloc) method knows how to account for these headers and trailers. Before returning E_ACCESSDENIED, CoRevokeMallocSpy notes internally that a revoke is pending. When the outstanding allocations have been freed, the revoke proceeds automatically, releasing the IMallocSpy object. Thus, it is necessary to call CoRevokeMallocSpy only once for each call to CoRegisterMallocSpy, even if E_ACCESSDENIED is returned.

See Also

IMallocSpy, CoRegisterMallocSpy, CoGetMalloc


CoSetProxyBlanket

Sets the authentication information that will be used to make calls on the specified proxy.

HRESULT CoSetProxyBlanket(

void *  pProxy,	//Indicates the proxy to set
DWORD  dwAuthnSvc,	//Authentication service to use
DWORD  dwAuthzSvc,	//Authorization service to use
WCHAR * pServerPrincName,	//The server principal name to use with the authentication service
DWORD  dwAuthnLevel,	//The authentication level to use
DWORD  dwImpLevel,	//The impersonation level to use
RPC_AUTH_IDENTITY_HANDLE *  pAuthInfo,	//The identity of the client
DWORD  dwCapabilities	//Undefined — capability flags
);
Parameter

pProxy

[in] Pointer to an interface on the proxy for which this authentication information is to be set.

dwAuthnSvc

[in] A single DWORD value from the list of RPC_C_AUTHN_xxx constants indicating the authentication service to use. It may be RPC_C_AUTHN_NONE if no authentication is required.

dwAuthzSvc

[in] A single DWORD value from the list of RPC_C_AUTHZ_xxx constants indicating the authorization service to use. If you are using the system default authentication service, use RPC_C_AUTHZ_NONE.

pServerPrincName

[in] Points to a WCHAR string that indicates the server principal name to use with the authentication service. If you are using RPC_C_AUTHN_WINNT, the principal name must be NULL.

dwAuthnLevel

[in] A single DWORD value from the list of RPC_C_AUTHN_LEVEL_xxx constants indicating the authentication level to use.

dwImpLevel

[in] A single DWORD value from the list of RPC_C_IMP_LEVEL_xxx constants indicating the impersonation level to use. Currently, only RPC_C_IMP_LEVEL_IMPERSONATE and RPC_C_IMP_LEVEL_IDENTIFY are supported.

pAuthInfo

[in] Establishes the identity of the client. It is authentication service specific. Some authentication services allow the application to pass in a different user name and password. COM keeps a pointer to the memory passed in until COM is uninitialized or a new value is set. If NULL is specified COM uses the current identity (the process token). For NTLMSSP the structure is SEC_WINNT_AUTH_IDENTITY_W.

dwCapabilities

[in] Flags to establish indicating the further capabilities of this proxy. Currently, no capability flags are defined.

The caller should specify EOAC_NONE. EOAC_MUTUAL_AUTH is defined and may be used by other security providers, but is not supported by NTLMSSP. Thus, NTLMSSP will accept this flag without generating an error but without providing mutual authentication.

Return Values

S_OK

Success, append the headers.

E_INVALIDARG

One or more arguments is invalid.

Remarks

Sets the authentication information that will be used to make calls on the specified proxy. This function encapsulates the following sequence of common calls (error handling excluded):

    pProxy->QueryInterface(IID_IClientSecurity, (void**)&pcs);

    pcs->SetBlanket(pProxy, dwAuthnSvc, dwAuthzSvc, pServerPrincName,
        dwAuthnLevel, dwImpLevel, pAuthInfo, dwCapabilities);

    pcs->Release();

See Also

IClientSecurity::SetBlanket, CoQueryClientBlanket, Security in COM


CoSuspendClassObjects

Prevents any new activation requests from the SCM on all class objects registered within the process.

WINOLEAPI CoSuspendClassObjects(void);

Return Values

S_OK

The CLSID was retrieved successfully.

Remarks

CoSuspendClassObjects prevents any new activation requests from the SCM on all class objects registered within the process. Even though a process may call this API, the process still must call CoRevokeClassObject for each CLSID it has registered, in the apartment it registered in. Applications typically do not need to call this API, which is generally only called internally by OLE when used in conjunction with CoReleaseServerProcess.

See Also

CoRevokeClassObject, CoReleaseServerProcess, Out-of-process Server Implementation Helpers


CoTaskMemAlloc

Allocates a block of task memory in the same way that IMalloc::Alloc does.

LPVOID CoTaskMemAlloc(

ULONG cb	//Size in bytes of memory block to be allocated
);
Parameter

cb

[in] Size, in bytes, of the memory block to be allocated.

Return Values

Allocated memory block

Memory block allocated successfully.

NULL

Insufficient memory available.

Remarks

The CoTaskMemAlloc function uses the default allocator to allocate a memory block in the same way that IMalloc::Alloc does. It is not necessary to call the CoGetMalloc function before calling CoTaskMemAlloc.

The initial contents of the returned memory block are undefined − there is no guarantee that the block has been initialized. The allocated block may be larger than cb bytes because of the space required for alignment and for maintenance information.

If cb is zero, CoTaskMemAlloc allocates a zero-length item and returns a valid pointer to that item. If there is insufficient memory available, CoTaskMemAlloc returns NULL.

Note  Applications should always check the return value from this method, even when requesting small amounts of memory, because there is no guarantee the memory will be allocated.

See Also

IMalloc::Alloc, CoGetMalloc, CoTaskMemFree, CoTaskMemRealloc


CoTaskMemFree

Frees a block of task memory previously allocated through a call to the CoTaskMemAlloc or CoTaskMemRealloc function.

void CoTaskMemFree(

void pv	//Pointer to memory block to be freed
);
Parameter

pv

[in] Pointer to the memory block to be freed.

Remarks

The CoTaskMemFree function, using the default OLE allocator, frees a block of memory previously allocated through a call to the CoTaskMemAlloc or CoTaskMemRealloc function.

The number of bytes freed equals the number of bytes that were originally allocated or reallocated. After the call, the memory block pointed to by pv is invalid and can no longer be used.

Note  The pv parameter can be NULL, in which case this method has no effect.

See Also

CoTaskMemAlloc, CoTaskMemRealloc, CoGetMalloc, IMalloc::Free


CoTaskMemRealloc

Changes the size of a previously allocated block of task memory.

LPVOID CoTaskMemRealloc(

LPVOID pv,	//Pointer to memory block to be reallocated
ULONG cb	//Size of block to be reallocated
);
Parameters

pv

[in] Pointer to the memory block to be reallocated. It can be a NULL pointer, as discussed in the Remarks.

cb

[in] Size, in bytes, of the memory block to be reallocated. It can be zero, as discussed in the following remarks.

Return Values

Reallocated memory block

Memory block successfully reallocated.

NULL

Insufficient memory or cb is zero and pv is not NULL.

Remarks

The CoTaskMemRealloc function changes the size of a previously allocated memory block in the same way that IMalloc::Realloc does. It is not necessary to call the CoGetMalloc function to get a pointer to the OLE allocator before calling CoTaskMemRealloc.

The pv argument points to the beginning of the memory block. If pv is NULL, CoTaskMemRealloc allocates a new memory block in the same way as the CoTaskMemAlloc function. If pv is not NULL, it should be a pointer returned by a prior call to CoTaskMemAlloc.

The cb argument specifies the size (in bytes) of the new block. The contents of the block are unchanged up to the shorter of the new and old sizes, although the new block can be in a different location. Because the new block can be in a different memory location, the pointer returned by CoTaskMemRealloc is not guaranteed to be the pointer passed through the pv argument. If pv is not NULL and cb is zero, then the memory pointed to by pv is freed.

CoTaskMemRealloc returns a void pointer to the reallocated (and possibly moved) memory block. The return value is NULL if the size is zero and the buffer argument is not NULL, or if there is not enough memory available to expand the block to the given size. In the first case, the original block is freed; in the second, the original block is unchanged.

The storage space pointed to by the return value is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value.

See Also

CoTaskMemAlloc, CoTaskMemFree, CoGetMalloc, IMalloc::Realloc


CoTreatAsClass

Establishes or removes an emulation, in which objects of one class are treated as objects of a different class.

STDAPI CoTreatAsClass(

REFCLSID clsidOld,	//CLSID for the original object to be emulated
REFCLSID clsidNew	//CLSID for the new object that emulates the original
);
Parameters

clsidOld

[in] CLSID of the object to be emulated.

clsidNew

[in] CLSID of the object that should emulate the original object. This replaces any existing emulation for clsidOld. Can be CLSID_NULL, in which case any existing emulation for clsidOld is removed.

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK

The emulation was successfully established or removed.

REGDB_E_CLASSNOTREG

The clsidOld parameter is not properly registered in the registration database.

REGDB_E_READREGDB

Error reading from registration database.

REGDB_E_WRITEREGDB

Error writing to registration database.

Remarks

This function sets the TreatAs entry in the registry for the specified object, allowing the object to be emulated by another application. Emulation allows an application to open and edit an object of a different format, while retaining the original format of the object. After this entry is set, whenever any function like CoGetClassObject specifies the object’s original CLSID (clsidOld), it is transparently forwarded to the new CLSID (clsidNew), thus launching the application associated with the TreatAs CLSID. When the object is saved, it can be saved in its native format, which may result in loss of edits not supported by the original format.

You would call CoTreatAsClass in two situations if your application supports emulation:

•	In response to an end-user request (through a conversion dialog box) that a specified object be treated as an object of a different class (an object created under one application be run under another application, while retaining the original format information).

•	In a setup program, to register that one class of objects be treated as objects of a different class.

An example of the first case is that an end user might wish to edit a spreadsheet created by one application using a different application that can read and write the spreadsheet format of the original application. For an application that supports emulation, CoTreatAsClass can be called to implement a Treat As option in a conversion dialog box.

An example of the use of CoTreatAsClass in a setup program would be in an updated version of an application. When the application is updated, the objects created with the earlier version can be activated and treated as objects of the new version, while retaining the previous format information. This would allow you to give the user the option to convert when they save, or to save it in the previous format, possibly losing format information not available in the older version.

One result of setting an emulation is that when you enumerate verbs, as in the IOleObject::EnumVerbs method implementation in the default handler, this would enumerate the verbs from clsidNew instead of clsidOld.

To ensure that existing emulation information is removed when you install an application, your setup programs should call CoTreatAsClass, setting the clsidNew parameter to CLSID_NULL to remove any existing emulation for the classes they install.

If there is no CLSID assigned to the AutoTreatAs key in the registry, setting clsidNew and clsidOld to the same value removes the TreatAs entry, so there is no emulation. If there is a CLSID assigned to the AutoTreatAs key, that CLSID is assigned to the TreatAs key.

The CoTreatAsClass function does not validate whether an appropriate registry entry for clsidNew currently exists.

See Also

CoGetTreatAsClass


CoUninitialize

Closes the OLE Component Object Model (COM) library, freeing any resources that it maintains and forcing all RPC connections to close.

void CoUninitialize();

Remarks

The CoInitialize and CoUninitialize calls must be balanced − if there are multiple calls to the CoInitialize function, there must be the same number of calls to CoUninitialize. Only the CoUninitialize call corresponding to the CoInitialize call that initialized the library can close it.

The OleUninitialize function calls CoUninitialize internally, so applications that call OleUninitialize do not also need to call CoUninitialize.

CoUninitialize should be called on application shutdown, as the last call made to the COM library after the application hides its main windows and falls through its main message loop. If there are open conversations remaining, CoUninitialize starts a modal message loop and dispatches any pending messages from the containers or server for this OLE application. By dispatching the messages, CoUninitialize ensures that the application does not quit before receiving all of its pending messages. Non-OLE messages are discarded.

See Also

CoInitialize, OleUninitialize


CoUnmarshalHresult

Unmarshals an HRESULT type from the specified stream.

STDAPI CoUnmarshalHresult(

LPSTREAM pStm,	//Pointer to stream used for unmarshaling
HRESULT * phresult	//Pointer to the HRESULT
);
Parameters

pStm

[in] Pointer to the stream from which the HRESULT is to be unmarshaled.

phresult

[out] Pointer to the unmarshaled HRESULT.

Return Values

This function supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The HRESULT was unmarshaled successfully.

STG_E_INVALIDPOINTER

pStm is an invalid pointer.

Remarks

You do not explicitly call this function unless you are performing custom marshaling (that is, writing your own implementation of IMarshal), and your implementation needs to unmarshal an HRESULT.

You must use CoUnmarshalHresult to unmarshal HRESULTs previously marshaled by a call to the CoMarshalHresult function.

This function performs the following tasks:

1.	Reads an HRESULT from a stream.

2.	Returns the HRESULT.

See Also

CoMarshalHresult, IStream


CoUnmarshalInterface

Initializes a newly created proxy using data written into the stream by a previous call to the CoMarshalInterface function, and returns an interface pointer to that proxy.

STDAPI CoUnmarshalInterface(

IStream * pStm,	//Pointer to the stream
REFIID riid,	//Reference to the identifier of the interface
void ** ppv	//Indirect pointer to the unmarshaled interface
);
Parameters

pStm

[in] Pointer to the stream from which the interface is to be unmarshaled.

riid

[in] Reference to the identifier of the interface to be unmarshaled.

ppv

[out] Indirect pointer to the interface that was unmarshaled.

Return Values

This function supports the standard return value E_FAIL, as well as the following:

S_OK

The interface pointer was unmarshaled successfully.

STG_E_INVALIDPOINTER

pStm is an invalid pointer.

CO_E_NOTINITIALIZED

The CoInitialize or OleInitialize function was not called on the current thread before this function was called.

CO_E_OBJNOTCONNECTED

The object application has been disconnected from the remoting system (for example, as a result of a call to the CoDisconnectObject function).

REGDB_E_CLASSNOTREG

An error occurred reading the registration database.

E_NOINTERFACE

The final QueryInterface of this function for the requested interface returned E_NOINTERFACE.

CoCreateInstance errors

An error occurred when creating the handler.

Remarks

The CoUnmarshalInterface function performs the following tasks:

1.	Reads from the stream the CLSID to be used to create an instance of the proxy.

2.	Gets an IMarshal pointer to the proxy that is to do the unmarshaling. If the object uses COM’s default marshaling implementation, the pointer thus obtained is to an instance of the generic proxy object. If the marshaling is occurring between two threads in the same process, the pointer is to an instance of the in-process free threaded marshaler. If the object provides its own marshaling code, CoUnmarshalInterface calls the CoCreateInstance function, passing the CLSID it read from the marshaling stream. CoCreateInstance creates an instance of the object’s proxy and returns an IMarshal interface pointer to the proxy.

3.	Using whichever IMarshal interface pointer it has acquired, the function then calls IMarshal::UnmarshalInterface and, if appropriate, IMarshal::ReleaseMarshalData.

The primary caller of this function is COM itself, from within interface proxies or stubs that unmarshal an interface pointer. There are, however, some situations in which you might call CoUnmarshalInterface. For example, if you are implementing a stub, your implementation would call CoUnmarshalInterface when the stub receives an interface pointer as a parameter in a method call.

See Also

CoMarshalInterface, IMarshal::UnmarshalInterface


CreateAntiMoniker

Creates and supplies a new anti-moniker.

WINOLEAPI CreateAntiMoniker(

LPMONIKER FAR *ppmk	//Indirect pointer to the anti-moniker
);
Parameter

ppmk

[out] Indirect pointer to the IMoniker interface on the new anti-moniker. When successful, the function has called IUnknown::AddRef on the parameter and the caller is responsible for calling IUnknown::Release. When an error occurs, the pointer is NULL.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The anti-moniker has been created successfully.

Remarks

You would call this function only if you are writing your own moniker class (implementing the IMoniker interface). If you are writing a new moniker class that has no internal structure, you can use CreateAntiMoniker in your implementation of the IMoniker::Inverse method, and then check for an anti-moniker in your implementation of IMoniker::ComposeWith.

Like the “..” directory in MS-DOS file systems, which acts as the inverse to any directory name just preceding it in a path, an anti-moniker acts as the inverse of a simple moniker that precedes it in a composite moniker. An anti-moniker is used as the inverse of simple monikers with no internal structure. For example, the system-provided implementations of file monikers, item monikers, and pointer monikers all use anti-monikers as their inverse; consequently, an anti-moniker composed to the right of one of these monikers composes to nothing.

A moniker client (an object that is using a moniker to bind to another object) typically does not know the class of a given moniker, so the client cannot be sure that an anti-moniker is the inverse. Therefore, to get the inverse of a moniker, you would call IMoniker::Inverse rather than CreateAntiMoniker.

To remove the last piece of a composite moniker, you would do the following:

1.	Call IMoniker::Enum on the composite, specifying FALSE as the first parameter. This creates an enumerator that returns the component monikers in reverse order.

2.	Use the enumerator to retrieve the last piece of the composite.

3.	Call IMoniker::Inverse on that moniker. The moniker returned by IMoniker::Inverse will remove the last piece of the composite.

See Also

IMoniker::Inverse, IMoniker::ComposeWith, IMoniker - Anti-Moniker Implementation


CreateBindCtx

Supplies a pointer to an implementation of IBindCtx (a bind context object). This object stores information about a particular moniker-binding operation. The pointer this function supplies is required as a parameter in many methods of the IMoniker interface and in certain functions related to monikers.

WINOLEAPI CreateBindCtx(

DWORD reserved,	//Reserved for future use
LPBC FAR* ppbc	//Indirect pointer to the bind context
);
Parameters

reserved

[in] Reserved for future use; must be zero.

ppbc

[out] Indirect pointer to an IBindCtx interface on the new bind context object. When the function is successful, the caller is responsible for calling IUnknown::Release on the parameter. A NULL value indicates that an error occurred.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The bind context was allocated and initialized successfully.

Remarks

CreateBindCtx is most commonly used in the process of binding a moniker (locating and getting a pointer to an interface by identifying it through a moniker), as in the following steps:

1.	Get a pointer to a bind context by calling the CreateBindCtx function.

2.	Call the IMoniker::BindToObject method on the moniker, retrieving an interface pointer to the object to which the moniker refers.

3.	Release the bind context.

4.	Use the interface pointer.

5.	Release the interface pointer.

The following code fragment illustrates these steps:

// pMnk is an IMoniker * that points to a previously acquired moniker

IFoo *pFoo;

IBindCtx *pbc;

CreateBindCtx( 0, &pbc );

pMnk->BindToObject( pbc, NULL, IID_IFoo, &pFoo );

pbc->Release();

// pFoo now points to the object; safe to use pFoo

pFoo->Release();

Bind contexts are also used in other methods of the IMoniker interface besides IMoniker::BindToObject and in the MkParseDisplayName function.

A bind context retains references to the objects that are bound during the binding operation, causing the bound objects to remain active (keeping the object’s server running) until the bind context is released. Reusing a bind context when subsequent operations bind to the same object can improve performance. You should, however, release the bind context as soon as possible, because you could be keeping the objects activated unnecessarily.

A bind context contains a BIND_OPTS structure, which contains parameters that apply to all steps in a binding operation. When you create a bind context using CreateBindCtx, the fields of the BIND_OPTS structure are initialized to the following values:

cbStruct = sizeof(BIND_OPTS)

grfFlags = 0

grfMode = STGM_READWRITE

dwTickCountDeadline = 0.

You can call the IBindCtx::SetBindOptions method to modify these default values.

See Also

BIND_OPTS, IBindCtx, IMoniker, MkParseDisplayName


CreateClassMoniker

Creates a file moniker based on the specified path.

WINOLEAPI CreateClassMoniker(

REFCLSID rclsid,	//Class this moniker binds to
IMoniker **ppmk	//Indirect pointer to class moniker
);
Parameters

rclsid

[in] Reference to the CLSID of the object type to which this moniker binds.

ppmk

[out] When successful, indirect pointer to the IMoniker interface on the new class moniker. In this case, the function has called IUnknown::AddRef on the parameter and the caller is responsible for calling IUnknown::Release. When an error occurs, the value of the pointer is NULL.

Return Values

S_OK

The moniker has been created successfully.

E_INVALIDARG

One or more arguments are invalid.

Remarks

CreateClassMoniker creates a class moniker that refers to the given class. The class moniker will supports binding to a fresh instance of the class identified by the CLSID in rclsid..

See Also

IMoniker - Class Moniker Implementation


CreateDataAdviseHolder

Supplies a pointer to the OLE implementation of IDataAdviseHolder on the data advise holder object.

WINOLEAPI CreateDataAdviseHolder(

IDataAdviseHolder **ppDAHolder	//Indirect pointer to the advise holder object
);
Parameter

ppDAHolder

[out] Indirect pointer to the IDataAdviseHolder interface on the new advise holder object.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The advise holder object has been instantiated and the pointer supplied.

Remarks

Call CreateDataAdviseHolder in your implementation of IDataObject::DAdvise to get a pointer to the OLE implementation of IDataAdviseHolder interface. With this pointer, you can then complete the implementation of IDataObject::DAdvise by calling the IDataAdviseHolder::Advise method, which creates an advisory connection between the calling object and the data object.

See Also

IDataAdviseHolder


CreateDataCache

Supplies a pointer to a new instance of an OLE-provided implementation of a data cache.

WINOLEAPI CreateDataCache(

LPUNKNOWN pUnkOuter,	//Pointer to whether cache is to be aggregated
REFCLSID rclsid,	//CLSID used to generate icon labels
REFIID riid,	//Reference to the identifier of the interface
LPVOID FAR *ppvObj	//Indirect pointer to interface on supplied cache object
);
Parameters

pUnkOuter

[in] If the cache is to be created as part of an aggregate, pointer to the controlling IUnknown of the aggregate. If not, the parameter should be NULL.

rclsid

[in] CLSID used to generate icon labels. This value is typically CLSID_NULL.

riid

[in] Reference to the identifier of the interface the caller wants to use to communicate with the cache. This value is typically IID_IOleCache (defined in the OLE headers to equal the interface identifier for IOleCache).

ppvObj

[out] Iindirect points to the interface requested in riid on the cache object.

Return Values

This function supports the standard return values E_INVALIDARG and

E_OUTOFMEMORY, as well as the following:

S_OK

The OLE-provided cache was instantiated and the pointer supplied.

E_NOINTERFACE

The interface represented by riid is not supported by the object. The parameter ppvObj is set to NULL.

Remarks

The cache object created by CreateDataCache supports the IOleCache, IOleCache2, and IOleCacheControl interfaces for controlling the cache. It also supports the IPersistStorage, IDataObject (without advise sinks), IViewObject, and IViewObject2 interfaces.

See Also

IOleCache, IOleCache2, IOleCacheControl


CreateFileMoniker

Creates a file moniker based on the specified path.

WINOLEAPI CreateFileMoniker(

LPCOLESTR lpszPathName,	//Pointer to path to be used
LPMONIKER FAR *ppmk	//Indirect pointer to file moniker
);
Parameters

lpszPathName

[in] Pointer to a zero-terminated wide character string (two bytes per character) containing the path on which this moniker is based.

ppmk

[out] When successful, indirect pointer to the IMoniker interface on the new file moniker. In this case, the function has called IUnknown::AddRef on the parameter and the caller is responsible for calling IUnknown::Release. When an error occurs, the value of the pointer is NULL.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The moniker has been created successfully.

MK_E_SYNTAX

Error in the syntax of a path was encountered while creating a moniker.

Remarks

CreateFileMoniker creates a moniker for an object that is stored in a file. A moniker provider (an object that provides monikers to other objects) can call this function to create a moniker to identify a file-based object that it controls, and can then make the pointer to this moniker available to other objects. An object identified by a file moniker must also implement the IPersistFile interface so it can be loaded when a file moniker is bound.

When each object resides in its own file, as in an OLE server application that supports linking only to file-based documents in their entirety, file monikers are the only type of moniker necessary. To identify objects smaller than a file, the moniker provider must use another type of moniker (such as an item moniker) in addition to file monikers, creating a composite moniker. Composite monikers would be needed in an OLE server application that supports linking to objects smaller than a document (such as sections of a document or embedded objects).

The lpszPathName can be a relative path, a UNC path (e.g., \\server\share\path), or a drive-letter-based path (e.g., c:\). If based on a relative path, the resulting moniker must be composed onto another file moniker before it can be bound.

A file moniker can be composed to the right only of another file moniker when the first moniker is based on an absolute path and the other is a relative path, resulting in a single file moniker based on the combination of the two paths. A moniker composed to the right of another moniker must be a refinement of that moniker, and the file moniker represents the largest unit of storage. To identify objects stored within a file, you would compose other types of monikers (usually item monikers) to the right of a file moniker.

See Also

IMoniker - File Moniker Implementation


CreateGenericComposite

Performs a generic composition of two monikers and supplies a pointer to the resulting composite moniker.

WINOLEAPI CreateGenericComposite(

LPMONIKER pmkFirst,	//Pointer to the first moniker
LPMONIKER pmkRest,	//Pointer to the second moniker
LPMONIKER FAR *ppmkComposite	//Indirect pointer to the composite
);
Parameters

pmkFirst

[in] Pointer to the moniker to be composed to the left of the moniker that pmkRest points to. Can point to any kind of moniker, including a generic composite.

pmkRest

[in] Pointer to the moniker to be composed to the right of the moniker that pmkFirst points to. Can point to any kind of moniker compatible with the type of the pmkRest moniker, including a generic composite.

ppmkComposite

[out] Indirect pointer to the IMoniker interface on the composite moniker object that is the result of composing pmkFirst and pmkRest. This object supports the OLE composite moniker implementation of IMoniker. When successful, the function has called IUnknown::AddRef on the parameter and the caller is responsible for calling IUnknown::Release. If either pmkFirst or pmkRest are NULL, the supplied pointer is the one that is non-NULL. If both pmkFirst and pmkRest are NULL, or if an error occurs, the returned pointer is NULL.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The two input monikers were successfully composed.

MK_E_SYNTAX

The two monikers could not be composed due to an error in the syntax of a path (for example, if both pmkFirst and pmkRest are file monikers based on absolute paths).

Remarks

CreateGenericComposite joins two monikers into one. The moniker classes being joined can be different, subject only to the rules of composition. Call this function only if you are writing a new moniker class by implementing the IMoniker interface, within an implementation of IMoniker::ComposeWith that includes generic composition capability.

Moniker providers should call IMoniker::ComposeWith to compose two monikers together. Implementations of ComposeWith should (as do OLE implementations) attempt, when reasonable for the class, to perform non-generic compositions first, in which two monikers of the same class are combined. If this is not possible, the implementation can call CreateGenericComposite to do a generic composition, which combines two monikers of different classes, within the rules of composition. You can define new types of non-generic compositions if you write a new moniker class.

During the process of composing the two monikers, CreateGenericComposite makes all possible simplifications. Consider the example where pmkFirst is the generic composite moniker, A • B • C, and pmkRest is the generic composite moniker, C  (-1)  • B  (-1)  • Z (where C  (-1)  is the inverse of C). The function first composes C to C  (-1) , which composes to nothing. Then it composes B and B  (-1)  to nothing. Finally, it composes A to Z, and supplies a pointer to the generic composite moniker, A • Z.

See Also

IMoniker::ComposeWith, IMoniker - Generic Composite Moniker Implementation


CreateILockBytesOnHGlobal

Creates a byte array object that allows you use global memory as the physical device underneath a compound file implementation. This object supports an OLE implementation of the ILockBytes interface.

WINOLEAPI CreateILockBytesOnHGlobal(

HGLOBAL hGlobal,	//Memory handle for the byte array object
BOOL fDeleteOnRelease,	//Whether to free memory when the object is released
ILockBytes ** ppLkbyt	//Indirect pointer to the new byte array object
);
Parameters

hGlobal

[in] Memory handle allocated by the GlobalAlloc function. The handle must be allocated as moveable and nondiscardable. If the handle is to be shared between processes, it must also be allocated as shared. New handles should be allocated with a size of zero. If hGlobal is NULL, CreateILockBytesOnHGlobal internally allocates a new shared memory block of size zero.

fDeleteOnRelease

[in] IWhether the underlying handle for this byte array object should be automatically freed when the object is released.

ppLkbyt

[out] Indirect pointer to the ILockBytes interface on the new byte array object.

Return Values

This function supports the standard return values E_INVALIDARG and

E_OUTOFMEMORY, as well as the following:

S_OK

The byte array object was created successfully.

Remarks

The CreateILockBytesOnHGlobal function creates a byte array object based on global memory. This object supports an OLE implementation of the ILockBytes interface, and is intended to be used as the basis for a compound file. You can then use the supplied ILockBytes pointer in a call to the StgCreateDocfileOnILockBytes function to build a compound file on top of this byte array object. The ILockBytes instance calls the GlobalReAlloc function to grow the memory block as needed.

The current contents of the memory block are undisturbed by the creation of the new byte array object. After creating the ILockBytes instance, you can use the StgOpenStorageOnILockBytes function to reopen a previously existing storage object already contained in the memory block. You can also call GetHGlobalFromILockBytes to get the global memory handle associated with the byte array object created by CreateILockBytesOnHGlobal.

Note  If you free the hGlobal memory handle, the byte array object is no longer valid. You must call the ILockBytes::Release method before freeing the memory handle.

The value of the hGlobal parameter can be changed by a subsequent call to the GlobalReAlloc function; thus, you cannot rely on this value after the byte array object is created.

See Also

StgOpenStorageOnILockBytes, GetHGlobalFromILockBytes, ILockBytes


CreateItemMoniker

Creates an item moniker that identifies an object within a containing object (typically a compound document).

WINOLEAPI CreateItemMoniker(

LPCOLESTR lpszDelim,	//Pointer to delimiter string
LPCOLESTR lpszItem,	//Pointer to item name
LPMONIKER FAR *ppmk	//Indirect pointer to the item moniker
);
Parameters

lpszDelim

[in] Pointer to a wide character string (two bytes per character) zero-terminated string containing the delimiter (typically “!”) used to separate this item’s display name from the display name of its containing object.

lpszItem

[in] Pointer to a zero-terminated string indicating the containing object’s name for the object being identified. This name can later be used to retrieve a pointer to the object in a call to IOleItemContainer::GetObject.

ppmk

[out] Indirect pointer to an IMoniker interface on the new item moniker. When successful, the function has called IUnknown::AddRef on the pointer and the caller is responsible for calling IUnknown::Release. If an error occurs, the supplied pointer has a NULL value.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The moniker was created successfully.

Remarks

A moniker provider, which hands out monikers to identify its objects so they are accessible to other parties, would call CreateItemMoniker to identify its objects with item monikers. Item monikers are based on a string, and identify objects that are contained within another object and can be individually identified using a string. The containing object must also implement the IOleContainer interface.

Most moniker providers are OLE applications that support linking. Applications that support linking to objects smaller than file-based documents, such as a server application that allows linking to a selection within a document, should use item monikers to identify the objects. Container applications that allow linking to embedded objects use item monikers to identify the embedded objects.

The lpszItem parameter is the name used by the document to uniquely identify the object. For example, if the object being identified is a cell range in a spreadsheet, an appropriate name might be something like “A1:E7.” An appropriate name when the object being identified is an embedded object might be something like “embedobj1.” The containing object must provide an implementation of the IOleItemContainer interface that can interpret this name and locate the corresponding object. This allows the item moniker to be bound to the object it identifies.

Item monikers are not used in isolation. They must be composed with a moniker that identifies the containing object as well. For example, if the object being identified is a cell range contained in a file-based document, the item moniker identifying that object must be composed with the file moniker identifying that document, resulting in a composite moniker that is the equivalent of “C:\work\sales.xls!A1:E7.”

Nested containers are allowed also, as in the case where an object is contained within an embedded object inside another document. The complete moniker of such an object would be the equivalent of “C:\work\report.doc!embedobj1!A1:E7.” In this case, each containing object must call CreateItemMoniker and provide its own implementation of the IOleItemContainer interface.

See Also

IMoniker::ComposeWith, IOleItemContainer, IMoniker - Item Moniker Implementation


CreateOleAdviseHolder

Creates an advise holder object for managing compound document notifications. It returns a pointer to the object’s OLE implementation of the IOleAdviseHolder interface.

WINOLEAPI CreateOleAdviseHolder(

ppOAHolder	//Indirect pointer to the advise holder object
);
Parameter

ppOAHolder

[out] Indirect pointer to the IOleAdviseHolder interface on the new advise holder object.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The new OLE advise holder returned successfully.

Remarks

The function CreateOleAdviseHolder creates an instance of an advise holder, which supports the OLE implementation of the IOleAdviseHolder interface. The methods of this interface are intended to be used to implement the advisory methods of IOleObject, and, when advisory connections have been set up with objects supporting an advisory sink, to send notifications of changes in the object to the advisory sink. The advise holder returned by CreateOleAdviseHolder will suffice for the great majority of applications. The OLE-provided implementation does not, however, support IOleAdviseHolder::EnumAdvise, so if you need to use this method, you will need to implement your own advise holder.

See Also

IOleAdviseHolder, IOleObject


CreatePointerMoniker

Creates a pointer moniker based on a pointer to an object.

WINOLEAPI CreatePointerMoniker(

LPUNKNOWN punk,	//Pointer to the interface to be used
LPMONIKER FAR *ppmk	//Indirect pointer to the moniker
);
Parameters

punk

[in] Pointer to an IUnknown interface on the object to be identified by the resulting moniker.

ppmk

[out] Indirect pointer to the IMoniker interface on the new pointer moniker. When successful, the function has called IUnknown::AddRef on the parameter and the caller is responsible for calling IUnknown::Release. When an error occurs, the returned pointer has a NULL value.

Return Values

This function supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The pointer moniker was created successfully.

Remarks

A pointer moniker wraps an existing interface pointer in a moniker that can be passed to those interfaces that require monikers. Pointer monikers allow an object that has no persistent representation to participate in a moniker-binding operation.

Pointer monikers are not commonly used, so this function is not often called.

See Also

IMoniker - Pointer Moniker Implementation


CreateStreamOnHGlobal

Creates a stream object stored in global memory.

WINOLEAPI CreateStreamOnHGlobal(

HGLOBAL hGlobal,	//Memory handle for the stream object
BOOL fDeleteOnRelease,	//Whether to free memory when the object is released
LPSTREAM * ppstm	//Indirect pointer to the new stream object
);
Parameters

hGlobal

[in] Memory handle allocated by the GlobalAlloc function. The handle must be allocated as moveable and nondiscardable. If the handle is to be shared between processes, it must also be allocated as shared. New handles should be allocated with a size of zero. If hGlobal is NULL, the CreateStreamOnHGlobal function internally allocates a new shared memory block of size zero.

fDeleteOnRelease

[in] Whether the underlying handle for this stream object should be automatically freed when the stream object is released.

ppstm

[out] Indirect pointer to the IStream interface on the new stream object. Its value cannot be NULL.

Return Values

This function supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

S_OK

The stream object was created successfully.

Remarks

The CreateStreamOnHGlobal function creates a stream object in memory that supports the OLE implementation of the IStream interface. The returned stream object supports both reading and writing, is not transacted, and does not support locking.

The initial contents of the stream are the current contents of the memory block provided in the hGlobal parameter. If the hGlobal paramter is NULL, this function internally allocates memory.

The current contents of the memory block are undisturbed by the creation of the new stream object. Thus, you can use this function to open an existing stream in memory.

The initial size of the stream is the size of the memory handle returned by the Win32 GlobalSize function. Because of rounding, this is not necessarily the same size that was originally allocated for the handle. If the logical size of the stream is important, you should follow the call to this function with a call to the IStream::SetSize method.

After you have created the stream object with CreateStreamOnHGlobal, you can call GetHGlobalFromStream to get the global memory handle associated with the stream object.

See Also

CreateStreamOnHGlobal, GetHGlobalFromStream, IStream::SetSize, GlobalSize in Win32


DllCanUnloadNow

Determines whether the DLL that implements this function is in use. If not, the caller can safely unload the DLL from memory.

Note  OLE does not provide this function. DLLs that support the OLE Component Object Model (COM) should implement and export DllCanUnloadNow.

STDAPI DllCanUnloadNow();

Return Values

S_OK

The DLL can be unloaded.

S_FALSE

The DLL cannot be unloaded now.

Remarks

A call to DllCanUnloadNow determines whether the DLL from which it is exported is still in use. A DLL is no longer in use when it is not managing any existing objects (the reference count on all of its objects is 0).

Notes to Callers

You should not have to call DllCanUnloadNow directly. OLE calls it only through a call to the CoFreeUnusedLibraries function. When it returns S_OK, CoFreeUnusedLibraries safely frees the DLL.

Notes to Implementers

You need to implement DllCanUnloadNow in, and export it from, DLLs that are to be dynamically loaded through a call to the CoGetClassObject function. (You also need to implement and export the DllGetClassObject function in the same DLL).

If a DLL loaded through a call to CoGetClassObject fails to export DllCanUnloadNow, the DLL will not be unloaded until the application calls the CoUninitialize function to release the OLE libraries.

If the DLL links to another DLL, returning S_OK from DllCanUnloadNow will also cause the second, dependent DLL to be unloaded. To eliminate the possibility of a crash, the primary DLL should call the CoLoadLibrary function, specifying the path to the second DLL as the first parameter, and setting the auto free parameter to TRUE. This forces the COM library to reload the second DLL and set it up for a call to CoFreeUnusedLibraries to free it separately when appropriate.

DllCanUnloadNow should return S_FALSE if there are any existing references to objects that the DLL manages.

See Also

DllGetClassObject


DllGetClassObject

Retrieves the class object from a DLL object handler or object application. DllGetClassObject is called from within the CoGetClassObject function when the class context is a DLL.

Note  OLE does not provide this function. DLLs that support the OLE Component Object Model (COM) must implement DllGetClassObject in OLE object handlers or DLL applications.

STDAPI DllGetClassObject(

REFCLSID rclsid,	//CLSID for the class object
REFIID riid,	//Reference to the identifier of the interface that communicates with the class object
LPVOID  * ppv	//Indirect pointer to the communicating interface
);
Parameters

rclsid

[in] CLSID that will associate the correct data and code.

riid

[in] Reference to the identifier of the interface that the caller is to use to communicate with the class object. Usually, this is IID_IClassFactory (defined in the OLE headers as the interface identifier for IClassFactory).

ppv

[out] Indirect pointer to the requested interface or, if an error occurs, to NULL.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The object was retrieved successfully.

CLASS_E_CLASSNOTAVAILABLE

The DLL does not support the class (object definition).

Remarks

If a call to the CoGetClassObject function finds the class object that is to be loaded in a DLL, CoGetClassObject uses the DLL’s exported DllGetClassObject function.

Notes to Callers

You should not call DllGetClassObject directly. When an object is defined in a DLL, CoGetClassObject calls the CoLoadLibrary function to load the DLL, which, in turn, calls DllGetClassObject.

Notes to Implementers

You need to implement DllGetClassObject in (and export it from) DLLs that support the OLE Component Object Model.

Example

Following is an example (in C++) of an implementation of DllGetClassObject. In this example, DllGetClassObject creates a class object and calls its QueryInterface method to retrieve a pointer to the interface requested in riid. The implementation safely releases the reference it holds to the IClassFactory interface because it returns a reference-counted pointer to IClassFactory to the caller.

HRESULT_export  PASCAL DllGetClassObject

        (REFCLSID rclsid, REFIID riid, LPVOID * ppvObj)

{

    HRESULT hres = E_OUTOFMEMORY;

    *ppvObj = NULL;

    CClassFactory *pClassFactory = new CClassFactory(rclsid);

    if (pClassFactory != NULL)   {

        hRes = pClassFactory->QueryInterface(riid, ppvObj);

        pClassFactory->Release();

    }

    return hRes;

}

See Also

CoGetClassObject, DllCanUnloadNow


DllRegisterServer

Instructs an in-process server to create its registry entries for all classes supported in this server module. If this function fails, the state of the registry for all its classes is indeterminate.

STDAPI DllRegisterServer(void);

Return Values

This function supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The registry entries were created successfully.

SELFREG_E_TYPELIB

The server was unable to complete the registration of all the type libraries used by its classes.

SELFREG_E_CLASS

The server was unable to complete the registration of all the object classes.

Remarks

E_NOTIMPL is not a valid return code.

See Also

DllUnregisterServer


DllUnregisterServer

Instructs an in-process server to remove only those entries created through DllRegisterServer.

STDAPI DllUnregisterServer(void);

Return Values

This function supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The registry entries were created successfully.

S_FALSE

Unregistration of this server’s known entries was successful, but other entries still exist for this server’s classes.

SELFREG_E_TYPELIB

The server was unable to remove the entries of all the type libraries used by its classes.

SELFREG_E_CLASS

The server was unable to remove the entries of all the object classes.

Remarks

The server must not disturb any entries that it did not create which currently exist for its object classes. For example, between registration and unregistration, the user may have specified a TreatAs relationship between this class and another. In that case, unregistration can remove all entries except the TreatAs key and any others that were not explicitly created in DllRegisterServer. The Win32 registry functions specifically disallow the deletion of an entire populated tree in the registry. The server can attempt, as the last step, to remove the CLSID key, but if other entries still exist, the key will remain.

See Also

DllRegisterServer


DoDragDrop

Carries out an OLE drag and drop operation.

WINOLEAPI DoDragDrop(

IDataObject * pDataObject,	//Pointer to the data object
IDropSource * pDropSource,	//Pointer to the source
DWORD dwOKEffect,	//Effects allowed by the source
DWORD * pdwEffect	//Pointer to effects on the source
);
Parameters

pDataObject

[in] Pointer to the IDataObject interface on a data object that contains the data being dragged.

pDropSource

[in] Pointer to an implementation of the IDropSource interface, which is used to communicate with the source during the drag operation.

dwOKEffect

[in] Effects the source allows in the OLE drag-and-drop operation. Most significant is whether it permits a move. The dwOKEffect and pdwEffect parameters obtain values from the DROPEFFECT enumeration. For a list of values, see DROPEFFECT.

pdwEffect

[out] Pointer to a value that indicates how the OLE drag-and-drop operation affected the source data. The pdwEffect parameter is set only if the operation is not canceled.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

DRAGDROP_S_DROP

The OLE drag-and-drop operation was successful.

DRAGDROP_S_CANCEL

The OLE drag-and-drop operation was canceled.

E_UNSPEC

Unexpected error occurred.

Remarks

If you are developing an application that can act as a data source for an OLE drag-and-drop operation, you must call DoDragDrop when you detect that the user has started an OLE drag-and-drop operation.

The DoDragDrop function enters a loop in which it calls various methods in the IDropSource and IDropTarget interfaces. (For a successful drag-and-drop operation, the application acting as the data source must also implement IDropSource, while the target application must implement IDropTarget.)

1.	The DoDragDrop function determines the window under the current cursor location. It then checks to see if this window is a valid drop target.

2.	If the window is a valid drop target, DoDragDrop calls IDropTarget::DragEnter. This method supplies an effect code indicating what would happen if the drop actually occurred. For a list of valid drop effects, see the DROPEFFECT enumeration.

3.	DoDragDrop calls IDropSource::GiveFeedback with the effect code so that the drop source interface can provide appropriate visual feedback to the user. The pDropSource pointer passed into DoDragDrop specifies the appropriate IDropSource interface.

4.	DoDragDrop tracks mouse cursor movements and changes in the keyboard or mouse button state.

•	If the user moves out of a window, DoDragDrop calls IDropTarget::DragLeave.

•	If the mouse enters another window, DoDragDrop determines if that window is a valid drop target and then calls IDropTarget::DragEnter for that window.

•	If the mouse moves but stays within the same window, DoDragDrop calls IDropTarget::DragOver.

5.	If there is a change in the keyboard or mouse button state, DoDragDrop calls IDropSource::QueryContinueDrag and determines whether to continue the drag, to drop the data, or to cancel the operation based on the return value.

•	If the return value is S_OK, DoDragDrop first calls IDropTarget::DragOver to continue the operation. This method returns a new effect value and DoDragDrop then calls IDropSource::GiveFeedback with the new effect so appropriate visual feedback can be set. For a list of valid drop effects, see the DROPEFFECT enumeration. IDropTarget::DragOver and IDropSource::GiveFeedback are paired so that as the mouse moves across the drop target, the user is given the most up-to-date feedback on the mouse’s position.

•	If the return value is DRAGDROP_S_DROP, DoDragDrop calls IDropTarget::Drop. The DoDragDrop function returns the last effect code to the source, so the source application can perform the appropriate operation on the source data, for example, cut the data if the operation was a move.

•	If the return value is DRAGDROP_S_CANCEL, the DoDragDrop function calls IDropTarget::DragLeave.

See Also

IDropSource


FACILITY_NT_BIT

#define FACILITY_NT_BIT 0x10000000

Defines bits so macros are guaranteed to work.


FAILED

#define FAILED(Status) ((HRESULT)(Status)<0)

Provides a generic test for failure on any status value. Negative numbers indicate failure.


FreePropVariantArray

Calls PropVariantClear on each of the PROPVARIANTs in the rgvar array to zero the value of each of the members of the array.

HRESULT FreePropVariantArray(

ULONG cVariant,	//Count of elements in the structure
PROPVARIANT* rgvar[]	//Pointer to the PROPVARIANT structure
);
Parameters

cVariant

[in] Count of elements in the PROPVARIANT array (rgvar).

rgvar

[in] Pointer to an initialized array of PROPVARIANT structures for which any deallocatable elements are to be freed. On exit, all zeroes are written to the PROPVARIANT (thus tagging them as VT_EMPTY).

Return Values

S_OK

The variant types are recognized and all items that can be freed have been freed.

STG_E_INVALID_PARAMETER

One or more PROPVARIANTs has an unknown type.

Remarks

FreePropVariantArray calls PropVariantClear on an array of PROPVARIANTs to clear all the valid members. All valid PROPVARIANTS are freed. If any of the PROPVARIANTs contain illegal VT-types, valid members are freed and the function returns STG_E_INVALIDPARAMETER.

Passing NULL for rgvar is legal, and produces a return code of S_OK.

See Also

PropVariantClear


GetClassFile

Supplies the CLSID associated with the given filename.

WINOLEAPI GetClassFile(

LPCWSTR szFileName,	//Pointer to filename for which you are requesting a CLSID
CLSID * pclsid	//Pointer to location for returning the CLSID
);
Parameters

szFileName

[in] Points to the filename for which you are requesting the associated CLSID.

pclsid

[out] Points to the location where the associated CLSID is written on return.

Return Values

S_OK

Indicates the CLSID was successfully supplied.

MK_E_CANTOPENFILE

Indicates unable to open the specified filename.

MK_E_INVALIDEXTENSION

Indicates the specified extension in the registry is invalid.

Note  This function can also return any file system errors.

Comments

When given a filename, the GetClassFile function finds the CLSID associated with that file. Examples of its use are in OleCreateFromFile, which is passed a file name and requires an associated CLSID, and in the OLE implementation of IMoniker::BindToObject, which, when a link to a file-based document is activated, calls GetClassFile to locate the object application that can open the file.

GetClassFile uses the following strategies to determine an appropriate CLSID:

1.	If the file contains a storage object, as determined by a call to the StgIsStorageFile function, GetClassFile returns the CLSID that was written with the IStorage::SetClass method.

2.	If the file is not a storage object, the GetClassFile function attempts to match various bits in the file against a pattern in the registry. A pattern in the registry can contain a series of entries of the form:

regdb key = offset, cb, mask, value

The value of the offset item is an offset from the beginning or end of the file and the cb item is a length in bytes. These two values represent a particular byte range in the file. (A negative value for the offset item is interpreted from the end of the file). The mask value is a bit mask that is used to perform a logical AND operation with the byte range specified by offset and cb. The result of the logical AND operation is compared with the value item. If the mask is omitted, it is assumed to be all ones.

Each pattern in the registry is compared to the file in the order of the patterns in the database. The first pattern where each of the value items matches the result of the AND operation determines the CLSID of the file. For example, the pattern contained in the following entries of the registry requires that the first four bytes be AB CD 12 34 and that the last four bytes be FE FE FE FE:

HKEY_CLASSES_ROOT

FileType

  {12345678-0000-0001-C000-000000000095}

    0 = 0, 4, FFFFFFFF, ABCD1234

    1 = -4, 4, , FEFEFEFE

If a file contains such a pattern, the CLSID {12345678-0000-0001-C000-000000000095} will be associated with this file.

3.	If the above strategies fail, the GetClassFile function searches for the File Extension key in the registry that corresponds to the .ext portion of the filename. If the database entry contains a valid CLSID, this function returns that CLSID.

4.	If all strategies fail, the function returns MK_E_INVALIDEXTENSION.

See Also

WriteClassStg


GetConvertStg

Returns the current value of the convert bit for the specified storage object.

WINOLEAPI GetConvertStg(

IStorage * pStg	//Points to the IStorage interface on the storage object
);
Parameter

pStg

[in] IStorage pointer to the storage object from which the convert bit is to be retrieved.

Return Values

S_OK

Indicates the convert bit is set to TRUE.

S_FALSE

Indicates the convert bit is cleared (FALSE).

STG_E_ACCESSDENIED

Access denied because the caller has insufficient permission, or another caller has the file open and locked.

STG_E_LOCKVIOLATION

Access denied because another caller has the file open and locked.

IStorage::OpenStream, IStorage::OpenStorage, and IStream::Read storage and stream access errors.

Comments

The GetConvertStg function is called by object servers that support the conversion of an object from one format to another. The server must be able to read the storage object using the format of its previous CLSID and write the object using the format of its new CLSID to support the object’s conversion. For example, a spreadsheet created by one application can be converted to the format used by a different application.

The convert bit is set by a call to the SetConvertStg function. A container application can call this function on the request of an end user, or a setup program can call it when installing a new version of an application. An end user requests converting an object through the Convert To dialog box. When an object is converted, the new CLSID is permanently assigned to the object, so the object is subsequently associated with the new CLSID.

Then, when the object is activated, its server calls the GetConvertStg function to retrieve the value of the convert bit from the storage object. If the bit is set, the object’s CLSID has been changed, and the server must read the old format and write the new format for the storage object.

After retrieving the bit value, the object application should clear the convert bit by calling the SetConvertStg function with its fConvert parameter set to FALSE.

See Also

SetConvertStg


GetHGlobalFromILockBytes

Retrieves a global memory handle to a byte array object created using the CreateILockBytesOnHGlobal function.

WINOLEAPI GetHGlobalFromILockBytes(

ILockBytes * pLkbyt,	//Points to the byte array object
HGLOBAL * phglobal	//Points to the current memory handle for the specified byte array
);
Parameters

pLkbyt

[in] Points to the ILockBytes interface on the byte array object previously created by a call to the CreateILockBytesOnHGlobal function.

phglobal

[out] Points to the current memory handle used by the specified byte array object.

Return Values

S_OK

Indicates the handle was returned successfully.

E_INVALIDARG

Indicates invalid value specified for the pLkbyt parameter. It can also indicate that the byte array object passed in is not one created by the CreateILockBytesOnHGlobal function.

Comments

After a call to CreateILockBytesOnHGlobal, which creates a byte array object on global memory, GetHGlobalFromILockBytes retrieves a pointer to the handle of the global memory underlying the byte array object. The handle this function returns might be different from the original handle due to intervening calls to the GlobalRealloc function.

The contents of the returned memory handle can be written to a clean disk file, and then opened as a storage object using the StgOpenStorage function.

This function only works within the same process from which the byte array was created.

See Also

StgOpenStorage, CreateILockBytesOnHGlobal


GetHGlobalFromStream

Retrieves the global memory handle to a stream that was created through a call to the CreateStreamOnHGlobal function.

WINOLEAPI GetHGlobalFromStream(

IStream * pstm,	//Points to the stream object
HGLOBAL * phglobal	//Points to the current memory handle for the specified stream
);
Parameters

pstm

[in] IStream pointer to the stream object previously created by a call to the CreateStreamOnHGlobal function.

phglobal

[out] Points to the current memory handle used by the specified stream object.

Return Values

S_OK

Indicates the handle was successfully returned.

E_INVALIDARG

Indicates invalid value specified for the pstm parameter. It can also indicate that the stream object passed in is not one created by a call to the CreateStreamOnHGlobal function.

Comments

The handle this function returns may be different from the original handle due to intervening GlobalRealloc calls.

This function can be called only from within the same process from which the byte array was created.

See Also

CreateStreamOnHGlobal

GlobalRealloc in Win32


GetRunningObjectTable

Supplies a pointer to the IRunningObjectTable interface on the local Running Object Table (ROT).

WINOLEAPI GetRunningObjectTable(

DWORD reserved,	//Reserved
LPRUNNINGOBJECTTABLE *pprot	//Indirect pointer
);
Parameters

reserved

[in] Reserved for future use; must be zero.

pprot

[out] Indirect pointer to the IRunningObjectTable interface on the local ROT. When the function is successful, the caller is responsible for calling IUnknown::Release on the pointer. If an error occurs, pprot is undefined.

Return Values

This function supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

An IRunningObjectTable pointer was successfully returned.

Remarks

Each workstation has a local ROT that maintains a table of the objects that have been registered as running on that machine. This function returns an IRunningObjectTable interface pointer, which provides access to that table.

Moniker providers, which hand out monikers that identify objects so they are accessible to others, should call GetRunningObjectTable. Use the interface pointer returned by this function to register your objects when they begin running, to record the times that those objects are modified, and to revoke their registrations when they stop running. See the IRunningObjectTable interface for more information.

Compound-document link sources are the most common example of moniker providers. These include server applications that support linking to their documents (or portions of a document) and container applications that support linking to embeddings within their documents. Server applications that do not support linking can also use the ROT to cooperate with container applications that support linking to embeddings.

If you are implementing the IMoniker interface to write a new moniker class, and you need an interface pointer to the ROT, call IBindCtx::GetRunningObjectTable rather than the GetRunningObjectTable function. This allows future implementations of the IBindCtx interface to modify binding behavior.

See Also

IBindCtx::GetRunningObjectTable, IMoniker, IRunningObjectTable


GetScode

#define GetScode(hr) ((SCODE) (hr))

Extracts the SCODE from an HRESULT.

This macro is obsolete and should not be used.


HRESULT_CODE

#define HRESULT_CODE(hr) ((hr) & 0xFFFF)

Returns the error code part of the HRESULT.


HRESULT_FACILITY

#define HRESULT_FACILITY(hr) (((hr) >> 16) & 0x1fff)

Returns the facility from the HRESULT.


HRESULT_FROM_NT

#define HRESULT_FROM_NT(x) ((HRESULT) ((x) | FACILITY_NT_BIT))

Maps an NT status value into an HRESULT.


HRESULT_FROM_WIN32

#define HRESULT_FROM_WIN32(x) (x ? ((HRESULT) (((x) & 0x0000FFFF) | (FACILITY_WIN32 << 16) | 0x80000000)) : 0 )

Maps a WIN32 error value into an HRESULT. Note that this assumes WIN32 errors fall in the range of -32k to 32k.


HRESULT_SEVERITY

#define HRESULT_SEVERITY(hr) (((hr) >> 31) & 0x1)

Returns the severity bit from the HRESULT.


IIDFromString

Converts a string generated by the StringFromIID function back into the original interface identifier (IID).

WINOLEAPI IIDFromString(

LPOLESTR lpsz,	//Pointer to the string representation of the IID
LPIID lpiid	//Pointer to the requested IID on return
);
Parameters

lpsz

[in] Pointer to the string representation of the IID.

lpiid

[out] Pointer to the requested IID on return.

Return Values

This function supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

S_OK

The string was successfully converted.

Remarks

The function converts the interface identifier in a way that guarantees different interface identifiers will always be converted to different strings.

See Also

StringFromIID


IsAccelerator

Determines whether the keystroke maps to an accelerator in the given accelerator table.

BOOL IsAccelerator(

HACCEL hAccel,	//Handle to accelerator table
INT cAccelEntries,	//Number of entries in the accelerator table
LPMSG lpMsg,	//Pointer to the keystroke message to be translated
WORD * lpwCmd	//Pointer to return the corresponding command identifier
);
Parameters

hAccel

[in] Handle to the accelerator table.

cAccelEntries

[in] Number of entries in the accelerator table.

lpMsg

[in] Pointer to the keystroke message to be translated.

lpwCmd

[out] Pointer to where to return the corresponding command identifier if there is an accelerator for the keystroke. It may be NULL.

Return Values

TRUE

The message is for the object application.

FALSE

The message is not for the object and should be forwarded to the container.

Remarks

While an object is active in-place, the object always has first chance to translate the keystrokes into accelerators. If the keystroke corresponds to one of its accelerators, the object must not call the OleTranslateAccelerator function — even if its call to the Windows TranslateAccelerator function fails. Failure to process keystrokes in this manner can lead to inconsistent behavior.

If the keystroke is not one of the object’s accelerators, then the object must call OleTranslateAccelerator to let the container try its accelerator translation.

The object’s server can call IsAccelerator to determine if the accelerator message belongs to it. Some servers do accelerator translation on their own and do not call TranslateAccelerator. Those applications will not call IsAccelerator, because they already have the information.

See Also

OleTranslateAccelerator, TranslateAccelerator in Win32


IS_ERROR

#define IS_ERROR(Status) ((unsigned long)(Status) >> 31 == SEVERITY_ERROR)

Provides a generic test for errors on any status value.


IsEqualGUID

Determines whether two GUIDs are equal.

BOOL IsEqualGUID(

REFGUID rguid1,	//GUID to compare to rguid2
REFGUID rguid2	//GUID to compare to rguid1
);
Parameters

rguid1

[in] GUID to compare to rguid2.

rguid2

[in] GUID to compare to rguid1.

Return Values

TRUE

The GUIDs are equal.

FALSE

The GUIDs are not equal.

Remarks

IsEqualGUID is used by the IsEqualCLSID and IsEqualIID functions.

See Also

IsEqualCLSID, IsEqualIID


IsEqualCLSID

Determines whether two CLSIDs are equal.

BOOL IsEqualCLSID(

REFCLSID rclsid1,	//CLSID to compare to rclsid2
REFCLSID rclsid2	//CLSID to compare to rclsid1
);
Parameters

rclsid1

[in] CLSID to compare to rclsid2.

rclsid2

[in] CLSID to compare to rclsid1.

Return Values

TRUE

The CLSIDs are equal.

FALSE

The CLSIDs are not equal.

See Also

IsEqualGUID, IsEqualIID


IsEqualIID

Determines whether two interface identifiers are equal.

BOOL IsEqualIID(

REFGUID riid1,	//Interface identifier to compare to riid2
REFGUID riid2	//Interface identifier to compare to riid1
);
Parameters

riid1

[in] Interface identifier to compare with riid2.

riid2

[in] Interface identifier to compare with riid1.

Return Values

TRUE

The interface identifiers are equal.

FALSE

The interface identifiers are not equal.

See Also

IsEqualGUID, IsEqualCLSID


IsValidIid

This function is obsolete.


IsValidInterface

This function is obsolete.


IsValidPtrIn

This function is obsolete.


IsValidPtrOut

This function is obsolete.


MAKE_HRESULT

#define MAKE_HRESULT(sev,fac,code) \HRESULT) (((unsigned long)(sev)<<31) | ((unsigned long)(fac)<<16) | ((unsigned long)(code))) )

Creates an HRESULT value from component pieces of the 32-bit value.


MAKE_SCODE

#define MAKE_SCODE(sev,fac,code) \((SCODE) (((unsigned long)(sev)<<31) | ((unsigned long)(fac)<<16) | ((unsigned long)(code))) )

Returns an SCODE given an HRESULT.


MkParseDisplayName

Converts a string into a moniker that identifies the object named by the string. This is the inverse of the IMoniker::GetDisplayName operation, which retrieves the display name associated with a moniker.

WINOLEAPI MkParseDisplayName(

LPBC pbc,	//Pointer to the bind context object
LPCOLESTR szUserName,	//Pointer to display name
ULONG FAR *pchEaten,	//Pointer to the number of characters consumed
LPMONIKER FAR *ppmk	//Indirect pointer to the moniker
);
Parameters

pbc

[in] Pointer to the IBindCtx interface on the bind context object to be used in this binding operation.

szUserName

[in] Pointer to a zero-terminated wide character string (two bytes per character) containing the display name to be parsed.

pchEaten

[out] Pointer to the number of characters of szUserName that were consumed. If the function is successful, *pchEaten is the length of szUserName; otherwise, it is the number of characters successfully parsed.

ppmk

[out] Indirect pointer to the IMoniker implementation on the moniker that was built from szUserName. When successful, the function has called IUnknown::AddRef on the parameter and the caller is responsible for calling IUnknown::Release. If an error occurs, the supplied pointer value is NULL.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The parse operation was successful and the moniker was created.

MK_E_SYNTAX

Error in the syntax of a file name or an error in the syntax of the resulting composite moniker.

This function can also return any of the error values returned by IMoniker::BindToObject, IOleItemContainer::GetObject, or IParseDisplayName::ParseDisplayName.

Remarks

The MkParseDisplayName function parses a human-readable name into a moniker that can be used to identify a link source. The resulting moniker can be a simple moniker (such as a file moniker), or it can be a generic composite made up of the component moniker pieces. For example, the following display name:

"c:\mydir\somefile!item 1"

could be parsed into the following generic composite moniker:

(FileMoniker based on "c:\mydir\somefile") • (ItemMoniker based on "item 1")

The most common use of MkParseDisplayName is in the implementation of the standard Links dialog box, which allows an end user to specify the source of a linked object by typing in a string. You may also need to call MkParseDisplayName if your application supports a macro language that permits remote references (reference to elements outside of the document).

Parsing a display name often requires activating the same objects that would be activated during a binding operation, so it can be just as expensive (in terms of performance) as binding. Objects that are bound during the parsing operation are cached in the bind context passed to the function. If you plan to bind the moniker returned by MkParseDisplayName, it is best to do so immediately after the function returns, using the same bind context, which removes the need to activate objects a second time.

MkParseDisplayName parses as much of the display name as it understands into a moniker. The function then calls IMoniker::ParseDisplayName on the newly created moniker, passing the remainder of the display name. The moniker returned by IMoniker::ParseDisplayName is composed onto the end of the existing moniker and, if any of the display name remains unparsed, IMoniker::ParseDisplayName is called on the result of the composition. This process is repeated until the entire display name has been parsed.

The MkParseDisplayName function attempts the following strategies to parse the beginning of the display name, using the first one that succeeds:

1.	The function looks in the Running Object Table for file monikers corresponding to all prefixes of szDisplayName that consist solely of valid file name characters. This strategy can identify documents that are as yet unsaved.

2.	The function checks the maximal prefix of szDisplayName, which consists solely of valid file name characters, to see if an OLE 1 document is registered by that name (this may require some DDE broadcasts). In this case, the returned moniker is an internal moniker provided by the OLE 1 compatibility layer of OLE 2.

3.	The function consults the file system to check whether a prefix of szDisplayName matches an existing file. The file name can be drive-absolute, drive-relative, working-directory relative, or begin with an explicit network share name. This is the common case.

4.	If the initial character of szDisplayName is an ‘@’, the function finds the longest string immediately following it that conforms to the legal ProgID syntax. The function converts this string to a CLSID using the CLSIDFromProgID function. If the CLSID represents an OLE 2 class, the function loads the corresponding class object and asks for an IParseDisplayName interface pointer. The resulting IParseDisplayName interface is then given the whole string to parse, starting with the ‘@’. If the CLSID represents an OLE 1 class, then the function treats the string following the ProgID as an OLE1/DDE link designator having <filename>!<item> syntax.

See Also

IMoniker::ParseDisplayName, IMoniker::GetDisplayName, IParseDisplayName


MonikerCommonPrefixWith

Creates a new moniker based on the common prefix that this moniker (the one comprising the data of this moniker object) shares with another moniker. This function is intended to be called only in implementations of IMoniker::CommonPrefixWith.

WINOLEAPI MonikerCommonPrefixWith(

LPMONIKER pmkThis,	//Pointer to the first moniker being compared
LPMONIKER pmkOther,	//Pointer to the second moniker being compared
LPMONIKER FAR *ppmkCommon	//Indirect pointer to a moniker
);
Parameters

pmkThis

[in] Pointer to the IMoniker interface on one of the monikers for which a common prefix is sought; usually the moniker in which this call is used to implement IMoniker::CommonPrefixWith.

pmkOther

[in] Pointer to the IMoniker interface on the other moniker to compare with the first moniker.

ppmkCommon

[out] When successful, indirect pointer to an IMoniker interface on a moniker based on the common prefix of pmkThis and pmkOther. In this case, the function has called IUnknown::AddRef on the parameter and the caller is responsible for calling IUnknown::Release. If an error occurs, the supplied pointer value is NULL if an error occurs.

Return Values

This function supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

A common prefix exists that is neither pmkThis nor pmkOther.

MK_S_HIM

The entire pmkOther moniker is a prefix of the pmkThis moniker.

MK_S_ME

The entire pmkThis moniker is a prefix of the pmkOther moniker.

MK_S_US

The pmkThis and pmkOther monikers are equal.

MK_E_NOPREFIX

The monikers have no common prefix.

MK_E_NOTBINDABLE

This function was called on a relative moniker. It is not meaningful to take the common prefix of relative monikers.

Remarks

Call MonikerCommonPrefixWith only in the implementation of IMoniker::CommonPrefixWith for a new moniker class.

Your implementation of IMoniker::CommonPrefixWith should first check whether the other moniker is of a type that you recognize and handle in a special way. If not, you should call MonikerCommonPrefixWith, passing itself as pmkThis and the other moniker as pmkOther. MonikerCommonPrefixWith correctly handles the cases where either moniker is a generic composite.

You should call this function only if pmkThis and pmkOther are both absolute monikers (where an absolute moniker is either a file moniker or a generic composite whose leftmost component is a file moniker, and where the file moniker represents an absolute path). Do not call this function on relative monikers.

See Also

IMoniker::CommonPrefixWith


MonikerRelativePathTo

Provides a moniker that, when composed onto the end of the first specified moniker (or one with a similar structure), yields the second specified moniker. This function is intended for use only by IMoniker::RelativePathTo implementations.

WINOLEAPI MonikerRelativePathTo(

LPMONIKER pmkSrc,	//Pointer to the source identified by the moniker
LPMONIKER pmkDest,	//Pointer to the destination identified by the moniker
LPMONIKER FAR * ppmkRelPath,	//Indirect pointer to the relative moniker
BOOL dwReserved	//Reserved; must be non-zero
);
Parameters

pmkSrc

[in] Pointer to the IMoniker interface on the moniker that, when composed with the relative moniker to be created, produces pmkDest. This moniker identifies the “source” of the relative moniker to be created.

pmkDest

[in] Pointer to the IMoniker interface on the moniker to be expressed relative to pmkSrc. This moniker identifies the destination of the relative moniker to be created.

ppmkRelPath

[out] Indirect pointer to an IMoniker interface on the new relative moniker. When successful, the function has called IUnknown::AddRef on the parameter and the caller is responsible for calling IUnknown::Release. If an error occurs, the pointer value is NULL.

dwReserved

[in] Reserved; must be non-zero.

Return Values

This function supports the standard return value E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

A meaningful relative path has been returned.

MK_S_HIM

The only form of the relative path is the other moniker.

MK_E_NOTBINDABLE

Indicates that pmkSrc is a relative moniker, such as an item moniker, and must be composed with the moniker of its container before a relative path can be determined.

Remarks

Call MonikerRelativePathTo only in the implementation of IMoniker::RelativePathTo if you are implementing a new moniker class.

Your implementation of IMoniker::RelativePathTo should first check whether the other moniker is of a type you recognize and handle in a special way. If not, you should call MonikerRelativePathTo, passing itself as pmkThis and the other moniker as pmkOther. MonikerRelativePathTo correctly handles the cases where either moniker is a generic composite.

You should call this function only if pmkSrc and pmkDest are both absolute monikers, where an absolute moniker is either a file moniker or a generic composite whose leftmost component is a file moniker, and where the file moniker represents an absolute path. Do not call this function on relative monikers.

See Also

IMoniker::RelativePathTo


OleBuildVersion

This function is obsolete.


OleConvertIStorageToOLESTREAM

Converts the specified storage object from OLE 2 structured storage to the OLE 1 storage model but does not include the presentation data. This is one of several compatibility functions.

WINOLEAPI OleConvertIStorageToOLESTREAM(

IStorage * pStg,	//Pointer to the OLE 2 storage object to be converted
LPOLESTREAM lpolestream	//Pointer to the stream where the OLE1 storage is written
);
Parameters

pStg

[in] Pointer to the IStorage interface on the storage object to be converted to an OLE 1 storage.

lpolestream

[out] Pointer to an OLE 1 stream structure where the persistent representation of the object is saved using the OLE 1 storage model.

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK

The storage object was successfully converted and the OLESTREAM structure contains the persistent representation of an OLE 1 object.

CONVERT10_E_STG_NO_STD_STREAM

Object cannot be converted because its storage is missing a stream.

CONVERT10_S_NO_PRESENTATION

The specified storage object contains a Paintbrush object in DIB format and there is no presentation data in the OLESTREAM.

Remarks

This function converts an OLE 2 storage object to OLE 1 format. The OLESTREAM code implemented for OLE 1 must be available.

On entry, the stream pointed to by lpolestm should be created and positioned just as it would be for an OleSaveToStream call. On exit, the stream contains the persistent representation of the object using OLE 1 storage.

Note  Paintbrush objects are dealt with differently from other objects because their native data is in DIB format. When Paintbrush objects are converted using OleConvertIStorageToOLESTREAM, no presentation data is added to the OLESTREAM. To include presentation data, use the OleConvertIStorageToOLESTREAMEx function instead.

See Also

CoIsOle1Class, OleConvertIStorageToOLESTREAMEx, OleConvertOLESTREAMToIStorage, OleConvertOLESTREAMToIStorageEx


OleConvertIStorageToOLESTREAMEx

Converts the specified storage object from OLE 2 structured storage to the OLE 1 storage model, including the presentation data. This is one of several compatibility functions.

WINOLEAPI OleConvertIStorageToOLESTREAMEx(

IStorage  * pStg,	//Pointer to the OLE 2 storage object to be converted
CLIPFORMAT  cfFormat,	//Presentation data format
LONG  lWidth,	//Width in HIMETRIC
LONG  lHeight,	//Height in HIMETRIC
DWORD  dwSize,	//Size of data
STGMEDIUM  pmedium,	//Pointer to data
LPOLESTREAM  lpolestm	//Pointer to the stream where the OLE1 storage is written
);
Parameters

pStg

[in] Pointer to the IStorage interface on the storage object to be converted to an OLE 1 storage.

cfFormat

[in] Format of the presentation data. May be NULL, in which case the lWidth, lHeight, dwSize, and pmedium parameters are ignored.

lWidth

[in] Width of the object presentation data in HIMETRIC units.

lHeight

[in] Height of the object presentation data in HIMETRIC units.

dwSize

[in] Size of the data, in bytes, to be converted.

pmedium

[in] Pointer to the STGMEDIUM structure for the serialized data to be converted. See STGMEDIUM for more information.

lpolestm

[out] Pointer to a stream where the persistent representation of the object is saved using the OLE 1 storage model.

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK

The conversion was completed successfully.

DV_E_STGMEDIUM

The hGlobal member of STGMEDIUM is NULL.

DV_E_TYMED

The tymed member of the STGMEDIUM structure is not TYMED_HGLOBAL or TYMED_ISTREAM.

Remarks

The OleConvertIStorageToOLESTREAMEx function converts an OLE 2 storage object to OLE 1 format. It differs from the OleConvertIStorageToOLESTREAM function in that the presentation data to be written to the OLE 1 storage is passed in.

Because OleConvertIStorageToOLESTREAMEx can specify which presentation data to convert, it can be used by applications that do not use OLE default caching resources but do use OLE’s conversion resources.

The value of the tymed member of STGMEDIUM must be either TYMED_HGLOBAL or TYMED_ISTREAM; refer to the TYMED enumeration for more information. The medium is not released by OleConvertIStorageToOLESTREAMEx.

See Also

CoIsOle1Class, OleConvertIStorageToOLESTREAM, OleConvertOLESTREAMToIStorage, OleConvertOLESTREAMToIStorageEx, STGMEDIUM structure, TYMED enumeration


OleConvertOLESTREAMToIStorage

Converts the specified object from the OLE 1 storage model to an OLE 2 structured storage object without specifying presentation data. This is one of several compatibility functions.

WINOLEAPI OleConvertOLESTREAMToIStorage(

LPOLESTREAM lpolestream,	//Pointer to the stream where the OLE 1 storage is written
IStorage * pstg,	//Pointer to OLE 2 storage object
const DVTARGETDEVICE * ptd	//Pointer to target device
);
Parameters

lpolestream

[in] Pointer to a stream that contains the persistent representation of the object in the OLE 1 storage format.

pstg

[out] Pointer to the IStorage interface on the OLE 2 structured storage object.

ptd

[in] Pointer to the DVTARGETDEVICE structure specifying the target device for which the OLE 1 object is rendered.

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK

The object was successfully converted.

CONVERT10_S_NO_PRESENTATION

The object either has no presentation data or uses native data for its presentation.

DV_E_DVTARGETDEVICE or DV_E_DVTARGETDEVICE_SIZE

Invalid value for ptd.

Remarks

This function converts an OLE 1 object to an OLE 2 structured storage object. You can use this function to update OLE 1 objects to OLE 2 objects when a new version of the object application supports OLE 2.

On entry, the lpolestm parameter should be created and positioned just as it would be for an OleLoadFromStream function call. On exit, the lpolestm parameter is positioned just as it would be on exit from an OleLoadFromStream function, and the pstg parameter contains the uncommitted persistent representation of the OLE 2 storage object.

For OLE 1 objects that use native data for their presentation, the OleConvertOLESTREAMToIStorage function returns CONVERT10_S_NO_PRESENTATION. On receiving this return value, callers should call IOleObject::Update to get the presentation data so it can be written to storage.

Applications that do not use OLE’s default caching resources, but do use the conversion resources, can use an alternate function, OleConvertOLESTREAMToIStorageEx, which can specify which presentation data to convert. In the OleConvertOLESTREAMToIStorageEx function, the presentation data read from the OLESTREAM structure is passed out and the newly created OLE 2 storage object does not contain a presentation stream.

The following steps describe the conversion process using OleConvertOLESTREAMToIStorage:

1.	Create a root IStorage object by calling the StgCreateDocfile function(..., &pstg).

2.	Open the OLE 1 file (using OpenFile or another OLE 1 technique).

3.	Using the OLE 1 procedure for reading files, read from the file until an OLE object is encountered.

4.	Allocate an IStorage object from the root IStorage created in step 1:

pstg->lpVtbl->CreateStorage(...&pStgChild);

hRes = OleConvertIStorageToOLESTREAM(polestm, pStgChild);

hRes = OleLoad(pStgChild, &IID_IOleObject, pClientSite, ppvObj);

5.	Repeat step 3 until the file is completely read.

See Also

CoIsOle1Class, OleConvertIStorageToOLESTREAM, OleConvertIStorageToOLESTREAMEx, OleConvertOLESTREAMToIStorageEx,DVTARGETDEVICE structure, STGMEDIUM structure, TYMED enumeration


OleConvertOLESTREAMToIStorageEx

Converts the specified object from the OLE 1 storage model to an OLE 2 structured storage object including presentation data. This is one of several compatibility functions.

WINOLEAPI OleConvertOLESTREAMToIStorageEx(

LPOLESTREAM lpolestm,	//Pointer to the stream where the OLE1 storage is written
IStorage * pstg,	//Pointer to OLE 2 storage object
CLIPFORMAT * pcfFormat,	//Pointer to presentation data
LONG * plWidth,	//Points to width value
LONG * plHeight,	//Pointer to height value
DWORD * pdwSize,	//Pointer to size
STGMEDIUM pmedium	//Pointer to the structure
);
Parameters

lpolestm

[in] Pointer to the stream that contains the persistent representation of the object in the OLE 1 storage format.

pstg

[out] Pointer to the OLE 2 structured storage object.

pcfFormat

[out] Pointer to where the format of the presentation data is returned. May be NULL, indicating the absence of presentation data.

plWidth

[out] Pointer to where the width value (in HIMETRIC) of the presentation data is returned.

plHeight

[out] Pointer to where the height value (in HIMETRIC) of the presentation data is returned.

pdwSize

[out] Pointer to where the size in bytes of the converted data is returned.

pmedium

[out] Pointer to where the STGMEDIUM structure for the converted serialized data is returned.

Return Values

S_OK

The conversion was completed successfully.

DV_E_TYMED|

Value of the tymed member of STGMEDIUM is not TYMED_ISTREAM or TYMED_NULL.

Remarks

This function converts an OLE 1 object to an OLE 2 structured storage object. You can use this function to update OLE 1 objects to OLE 2 objects when a new version of the object application supports OLE 2.

This function differs from the OleConvertOLESTREAMToIStorage function in that the presentation data read from the OLESTREAM structure is passed out and the newly created OLE 2 storage object does not contain a presentation stream.

Since this function can specify which presentation data to convert, it can be used by applications that do not use OLE’s default caching resources but do use the conversion resources.

The tymed member of STGMEDIUM can only be TYMED_NULL or TYMED_ISTREAM. If it is TYMED_NULL, the data will be returned in a global handle through the hGlobal member of STGMEDIUM, otherwise data will be written into the pstm member of this structure.

See Also

CoIsOle1Class, OleConvertIStorageToOLESTREAM, OleConvertIStorageToOLESTREAMEx, OleConvertOLESTREAMToIStorage , STGMEDIUM structure, TYMED enumeration


OleCreate

Creates an embedded object identified by a CLSID. You use it typically to implement the menu item that allows the end user to insert a new object.

WINOLEAPI OleCreate(

REFCLSID rclsid,	//CLSID of embedded object to be created
REFIID riid,	//Reference to the identifier of the interface used to communicate with new object
DWORD renderopt,	//RENDEROPT value indicating cached capabilities
FORMATETC * pFormatEtc,	//Pointer to a FORMATETC structure
IOleClientSite * pClientSite,	//Pointer to request services from the container
IStorage * pStg,	//Pointer to storage for the object
void ** ppvObject	//Indirect pointer to new object
);
Parameters

rclsid

[in] CLSID of the embedded object that is to be created.

riid

[in] Reference to the identifier of the interface, usually IID_IOleObject (defined in the OLE headers as the interface identifier for IOleObject), through which the caller will communicate with the new object.

renderopt

[in] A value from the enumeration OLERENDER, indicating the locally cached drawing capabilities the newly created object is to have. The OLERENDER value chosen affects the possible values for the pFormatEtc parameter.

pFormatEtc

[in] Depending on which of the OLERENDER flags is used as the value of renderopt, pointer to one of the FORMATETC enumeration values. Refer to the OLERENDER enumeration for restrictions. This parameter, along with the renderopt parameter, specifies what the new object can cache initially.

pClientSite

[in] If you want OleCreate to call IOleObject::SetClientSite, pointer to the IOleClientSite interface on the container. The value may be NULL, in which case you must specifically call IOleClientSite::SetClientSite before attempting operations.

pStg

[in] Pointer to an instance of the IStorage interface on the storage object. This parameter may not be NULL.

ppvObject

[out] Upon successful return, indirect pointer to the interface requested in riid on the newly created object.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

Embedded object created successfully.

Remarks

The OleCreate function creates a new embedded object, and is typically called to implement the menu item Insert New Object. When OleCreate returns, the object it has created is blank (contains no data), unless renderopt is OLERENDER_DRAW or OLERENDER_FORMAT, and is loaded. Containers typically then call the OleRun function or IOleObject::DoVerb to show the object for initial editing.

The rclsid parameter specifies the CLSID of the requested object. CLSIDs of registered objects are stored in the system registry. When an application user selects Insert Object, a selection box allows the user to select the type of object desired from those in the registry. When OleCreate is used to implement the Insert Object menu item, the CLSID associated with the selected item is assigned to the rclsid parameter of OleCreate.

The riid parameter specifies the interface the client will use to communicate with the new object. Upon successful return, the ppvObject parameter holds a pointer to the requested interface.

The created object’s cache contains information that allows a presentation of a contained object when the container is opened. Information about what should be cached is passed in the renderopt and pFormatetc values. When OleCreate returns, the created object’s cache is not necessarily filled. Instead, the cache is filled the first time the object enters the running state. The caller can add additional cache control with a call to IOleCache::Cache after the return of OleCreate and before the object is run. If renderopt is OLERENDER_DRAW or OLERENDER_FORMAT, OleCreate requires that the object support the IOleCache interface. There is no such requirement for any other value of renderopt.

If pClientSite is non-NULL, OleCreate calls IOleObject::SetClientSite through the pClientSite pointer. IOleClientSite is the primary interface by which an object requests services from its container. If pClientSite is NULL, you must make a specific call to IOleObject::SetClientSite before attempting any operations.

See Also

OLERENDER, FORMATETC, IOleClientSite, IOleObject


OleCreateDefaultHandler

Creates a new instance of the default embedding handler. This instance is initialized so it creates a local server when the embedded object enters the running state.

WINOLEAPI OleCreateDefaultHandler(

REFCLSID clsid,	//OLE server to be loaded
LPUNKNOWN pUnkOuter,	//Pointer to controlling IUnknown if aggregated; else NULL
REFIID riid,	//Reference to the identifier of the interface for communicating with handler
LPVOID FAR * ppvObj	//Indirect pointer to interface on handler
);
Parameters

clsid

[in] CLSID identifying the OLE server to be loaded when the embedded object enters the running state.

pUnkOuter

[in] Pointer to the controlling IUnknown interface if the handler is to be aggregated; NULL if it is not to be aggregated.

riid

[in] Reference to the identifier of the interface, usually IID_IOleObject, through which the caller will communicate with the handler.

ppvObj

[out] Indirect pointer to the interface requested in riid on the newly created handler.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

NOERROR

The creation operation was successful.

Remarks

OleCreateDefaultHandler creates a new instance of the default embedding handler, initialized so it creates a local server identified by the clsid parameter when the embedded object enters the running state. If you are writing a handler and want to use the services of the default handler, call OleCreateDefaultHandler. OLE also calls it internally when the CLSID specified in an object creation call is not registered.

If the given class does not have a special handler, a call to OleCreateDefaultHandler produces the same results as a call to the CoCreateInstance function with the class context parameter assigned the value CLSCTX_INPROC_HANDLER.

See Also

CoCreateInstance, CLSCTX


OleCreateEmbeddingHelper

Creates an OLE embedding helper object using application-supplied code aggregated with pieces of the OLE default object handler. This helper object can be created and used in a specific context and role, as determined by the caller.

WINOLEAPI OleCreateEmbeddingHelper(

REFCLSID clsid,	//Identifier of the class to be helped
LPUNKNOWN pUnkOuter,	//Pointer to controlling IUnknown if aggregated; else NULL
DWORD flags,	//Purpose for the helper
LPCLASSFACTORY pCF,	//Pointer on the class object for the secondary object
REFIID riid,	//Reference to the identifier of the interface desired by the caller
LPVOID * ppvObj	//Indirect pointer to requested interface on helper
);
Parameters

clsid

[in] CLSID of the class to be helped.

pUnkOuter

[in] If the embedding helper is to be aggregated, pointer to the outer object’s controlling IUnknown interface. If it is not to be aggregated, although this is rare, the value should be NULL.

flags

[in] DWORD containing flags that specify the role and creation context for the embedding helper. For legal values, see the following Remarks section.

pCF

[in] Pointer to the IClassFactory interface on the class object the function uses to create the secondary object. In some situations, this value may be NULL. For more information, see the following Remarks section.

riid

[in] Reference to the identifier of the interface desired by the caller.

ppvObj

[out] Indirect pointer to the requested interface on the newly created embedding helper.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The OLE embedding helper was created successfully.

E_NOINTERFACE

The interface is not supported by the object.

Remarks

The OleCreateEmbeddingHelper function creates an object that supports the same interface implementations found in the default handler, but which has additional hooks that allow it to be used more generally than just as a handler object. The following two calls produce the same result:

OleCreateEmbeddingHelper(clsid, pUnkOuter, EMBDHLP_INPROC_HANDLER |

    EMBDHLP_CREATENOW, NULL, iid, ppvObj)

OleCreateDefaultHandler(clsid, pUnkOuter, iid, ppvObj)

The embedding helper is aggregatable; pUnkOuter is the controlling IUnknown of the aggregate of which the embedding helper is to be a part. It is used to create a new instance of the OLE default handler, which can be used to support objects in various roles. The caller passes a pointer to its IClassFactory implementation to OleCreateEmbeddingHelper. This object and the default handler are then aggregated to create the new embedding helper object.

The OleCreateEmbeddingHelper function is usually used to support one of the following implementations:

•	An EXE object application that is being used as both a container and a server, and which supports inserting objects into itself. For this case, CreateEmbeddingHelper allows the object to support the interfaces usually supported only in the handler. To accomplish this, the application must first register its CLSID for different contexts, making two registration calls to the CoRegisterClassObject function, rather than one, as follows:

    CoRegisterClassObject(clsidMe, pUnkCfLocal, CLSCTX_LOCAL_SERVER,

        REGCLS_MULTI_SEPARATE...)

    CoRegisterClassObject(clsidMe, pUnkCfInProc, CLSCTX_INPROC_SERVER,

        REGCLS_MULTI_SEPARATE...)

In these calls, you would pass along different class factory implementations to each of pUnkCfLocal and pUnkCfInProc. The class factory pointed to by pUnkCfLocal would be used to create objects that are to be embedded in a remote process, which is the normal case which uses a handler object associated with the client. However, when a server both creates an object and embeds it within itself, pUnkCfInProc points to a class object that can create an object that supports the handler interfaces. The local class is used to create the object and the in-process class creates the embedding helper, passing in the pointer to the first object’s class factory in pCF.

•	A custom in-process object handler, in which case, the DLL creates the embedding helper by passing in a pointer to a private implementation of IClassFactory in pCF.

The flags parameter indicates how the embedding helper is to be used and how and when the embedding helper is initialized. The values for flags are obtained by OR-ing together values from the following table:

Values for flags Parameter	Purpose
EMBDHLP_INPROC_HANDLER	Creates an embedding helper that can be used with DLL object applications; specifically, the helper exposes the caching features of the default object handler.
EMBDHLP_INPROC_SERVER	Creates an embedding helper that is to be used as part of an in-process server. pCF cannot be NULL.
EMBDHLP_CREATENOW	Creates the secondary object using pCF immediately; if pCF is null, the standard proxy manager is used.
EMBDHLP_DELAYCREATE	Delays creation of the secondary object until it is needed (when the helper is put into the running state) to enhance speed and memory use. pCF must not be NULL. The EMBDHLP_INPROC_HANDLER flag cannot be used with this flag.
See Also

OleCreateDefaultHandler


OleCreateEx

Extends OleCreate functionality by supporting more efficient instantiation of objects in containers requiring caching of multiple presentation formats or data, instead of the single format supported by OleCreate.

HRESULT OleCreateEx(

REFCLSID rclsid,	//Class of object to create
REFIID riid,	//Reference to the identifier of the interface of object to return
DWORD dwFlags,	//Value from OLECREATE enumeration
DWORD renderopt,	//Value from OLERENDER enumeration
ULONG cFormats,	//Number of FORMATETC structures in rgFormatEtc
DWORD rgAdvf,	//Points to an array of cFormats DWORD elements
LPFORMATETC rgFormatEtc,	//Points to an array of cFormats FORMATETC structures; NULL otherwise
LPADVISESINK pAdviseSink,	//IAdviseSink pointer (custom caching); NULL (default caching); NULL otherwise
DWORD* rgdwConnection,	//Location to return array of dwConnection values
LPOLECLIENTSITE pClientSite,	//Pointer to the primary interface the object will use to request services
LPSTORAGE pStg,	//Pointer to storage to use for object
LPVOID FAR* ppvObj	//Indirect pointer to location to return riid interface
);
Parameters

rclsid

Identifies the class of the object to create.

riid

Reference to the identifier of the interface of the object to return.

dwFlags

Value taken from the OLECREATE enumeration.

renderopt

Value taken from the RENDEROPT enumeration.

cFormats

When renderopt is OLERENDER_FORMAT, indicates the number of FORMATETC structures in the rgFormatEtc array, which must be at least one. In all other cases, this parameter must be zero.

rgAdvf

When renderopt is OLERENDER_FORMAT, points to an array of cFormats DWORD elements, each of which is a combination of values from the ADVF enumeration. Each element of this array is passed in as the advf parameter to a call to either IOleCache::Cache or IDataObject::DAdvise, depending on whether pAdviseSink is NULL or non-NULL (see below). In all other cases, this parameter must be NULL.

rgFormatEtc

When renderopt is OLERENDER_FORMAT, points to an array of cFormats FORMATETC structures. When pAdviseSink is NULL, each element of this array is passed as the pFormatEtc parameter to a call to the object’s IOleCache::Cache. This populates the data and presentation cache managed by the objects in-process handler (typically the default handler) with presentation or other cacheable data. When pAdviseSink is non-NULL, each element of this array is passed as the pFormatEtc parameter to a call to IDataObject::DAdvise. This allows the caller (typically an OLE Container) to do its own caching or processing of data received from the object. In all other cases, this parameter must be NULL.

pAdviseSink

When renderopt is OLERENDER_FORMAT, may be either a valid IAdviseSink pointer, indicating custom caching or processing of data advises, or NULL, indicating default caching of data formats. In all other cases, this parameter must be NULL.

rgdwConnection

Location to return the array of dwConnection values returned when the pAdviseSink interface is registered for each advisory connection using IDataObject::DAdvise, or NULL if the returned advisory connections are not needed. Must be NULL, if pAdviseSink is NULL.

pClientSite

Pointer to the primary interface through which the object will request services from its container. This parameter may be NULL, in which case it is the caller’s responsibility to establish the client site as soon as possible using IOleObject::SetClientSite.

pStg

Pointer to the storage to use for the object and any default data or presentation caching established for it. This parameter may not be NULL.

ppvObj

Location to return the riid interface of the newly created object.

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK

Success.

E_NOINTERFACE

The object does not support the riid interface.

Remarks

The following call to OleCreate:

    OleCreate(rclsid, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

is equivalent to the following call to OleCreateEx:

    DWORD    advf = ADVF_PRIMEFIRST;

    OleCreateEx(rclsid, riid, renderopt, 1, &advf, pFormatEtc, NULL, pClientSite, pStg, ppvObj);

Existing instantiation functions, (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLink, OleCreateLinkToFile, and OleCreateLinkFromData) create only a single presentation or data format cache in the default cache location (within the ‘\001OlePresXXX’ streams of the passed-in IStorage), during instantiation. Plus, these caches must be created when the object next enters the running state. Since most applications require caching at least two presentations (screen and printer) and may require caching data in a different format or location from the handler, applications must typically launch and shut down the object server multiple times in order to prime their data caches during object creation, i.e., Insert Object, Insert Object from File, and Paste Object.

Extended versions of these creation functions solve this problem. OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx, and OleCreateLinkFromDataEx contain the following new parameters: dwFlags to indicate additional options, cFormats to indicate how many formats to cache, rgAdvf, from the ADVF enumeration, to specify the advise flags for each format to be cached, pAdviseSink to indicate whether presentation (default-handler) or data (non-default-handler) caching is required, rgdwConnection to return IDataObject::DAdvise cookies, and pFormatEtc, an array of formats rather than a single format.

Containers requiring that multiple presentations be cached on their behalf by the object’s handler can simply call these functions and specify the number of formats in cFormats, the ADVF flags for each format in rgAdvf, and the set of formats in pFormatEtc. These containers pass NULL for pAdviseSink.

Containers performing all their own data- or presentation-caching perform these same steps, but pass a non-NULL pAdviseSink. They perform their own caching or manipulation of the object or data during IAdviseSink::OnDataChange. Typically such containers never establish the advisory connections with ADVF_NODATA, although they are not prevented from doing so.

These new functions are for OLE Compound Documents. Using these functions, applications can avoid the repeated launching and initialization steps required by the current functions. They are targeted at OLE Compound Document container applications that use default data- and presentation-caching, and also at applications that provide their own caching and data transfer from the underlying IDataObject::DAdvise support.

See Also

OleCreate, IOleCache::Cache, IDataObject::DAdvise, IOleObject::SetClientSite, IAdviseSink::OnDataChange, IStorage, OLERENDER, FORMATETC, ADVF


OleCreateFontIndirect

Creates and initializes a standard font object using an initial description of the font’s properties in a FONTDESC structure. The function returns an interface pointer to the new font object specified by caller in the riid parameter. A QueryInterface is built into this call. The caller is responsible for calling Release through the interface pointer returned.

STDAPI OleCreateFontIndirect(

FONTDESC* pFontDesc,	//Pointer to the structure of parameters for font
REFIID  riid,	//Reference to the identifier of the interface
VOID** ppvObj	//Indirect pointer to the object
);
Parameters

pFontDesc

[in] Pointer to a caller-allocated structure containing the initial state of the font.

riid

[in] Reference to the identifier of the interface describing the type of interface pointer to return in ppvObj.

ppvObj

[out] Indirect pointer to the initial interface pointer on the new object. If successful, the caller is responsible to call Release through this interface pointer when the new object is no longer needed. If unsuccessful, the value of ppvObj is set to NULL.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The new font was created successfully.

E_NOINTERFACE

The object does not support the interface specified in riid.

E_POINTER

The address in pFontDesc or ppvObj is not valid. For example, it may be NULL.

See Also

FONTDESC


OleCreateFromData

Creates an embedded object from a data transfer object retrieved either from the clipboard or as part of an OLE drag-and-drop operation. It is intended to be used to implement a paste from an OLE drag-and-drop operation.

WINOLEAPI OleCreateFromData(

LPDATAOBJECT pSrcDataObj,	//Pointer to the data transfer object
REFIID riid,	//Reference to the identifier of the interface to be used to communicate with the new object
DWORD renderopt,	//Value from OLERENDER
LPFORMATETC pFormatEtc,	//Pointer to value from FORMATETC, depending on renderopt
LPOLECLIENTSITE pClientSite,	//Pointer to interface
LPSTORAGE pStg,	//Pointer to storage of object
LPVOID FAR* ppvObj	//Indirect pointer to the interface requested in riid
);
Parameters

pSrcDataObj

[in] Pointer to the IDataObject interface on the data transfer object that holds the data from which the object is created.

riid

[in] Reference to the identifier of the interface the caller later uses to communicate with the new object (usually IID_IOleObject, defined in the OLE headers as the interface identifier for IOleObject).

renderopt

[in] Value from the enumeration OLERENDER that indicates the locally cached drawing or data-etrieval capabilities the newly created object is to have. Additional considerations are described in the following Remarks section.

pFormatEtc

[in] Pointer to a value from the enumeration OLERENDER that indicates the locally cached drawing or data-retrieval capabilities the newly created object is to have. The OLERENDER value chosen affects the possible values for the pFormatEtc parameter.

pClientSite

[in] Pointer to an instance of IOleClientSite, the primary interface through which the object will request services from its container. May be NULL.

pStg

[in] Pointer to the IStorage interface on the storage object. This parameter may not be NULL.

ppvObj

[out] Indirect pointer to the interface requested in riid on the newly created object.

Return Values

S_OK

The embedded object was created successfully.

OLE_E_STATIC

Indicates OLE can create only a static object.

DV_E_FORMATETC

No acceptable formats are available for object creation.

Remarks

The OleCreateFromData function creates an embedded object from a data transfer object supporting the IDataObject interface. The data object in this case is either the type retrieved from the clipboard with a call to the OleGetClipboard function or is part of an OLE drag-and-drop operation (the data object is passed to a call to IDropTarget::Drop).

If either the FileName or FileNameW clipboard format (CF_FILENAME) is present in the data transfer object, and CF_EMBEDDEDOBJECT or CF_EMBEDSOURCE do not exist, OleCreateFromData first attempts to create a package containing the indicated file. Generally, it takes the first available format. The Microsoft Windows NT File Manager places these formats on the clipboard when the user selects the File/Copy To Clipboard menu command.

If OleCreateFromData cannot create a package, it tries to create an object using the CF_EMBEDDEDOBJECT format. If that format is not available, OleCreateFromData tries to create it with the CF_EMBEDSOURCE format. If neither of these formats is available and the data transfer object supports the IPersistStorage interface, OleCreateFromData calls the object’s IPersistStorage::Save to have the object save itself.

If an existing linked object is selected, then copied, it appears on the clipboard as just another embeddable object. Consequently, a paste operation that invokes OleCreateFromData may create a linked object. After the paste operation, the container should call the QueryInterface function, requesting IID_IOleLink (defined in the OLE headers as the interface identifier for IOleLink), to determine if a linked object was created.

Use the renderopt and pFormatetc parameters to control the caching capability of the newly created object. For general information about using the interaction of these parameters to determine what is to be cached, refer to the OLERENDER enumeration. There are, however, some additional specific effects of these parameters on the way OleCreateFromData initializes the cache.

When OleCreateFromData uses either the CF_EMBEDDEDOBJECT or the CF_EMBEDSOURCE clipboard format to create the embedded object, the main difference between the two is where the cache-initialization data is stored:

•	CF_EMBEDDEDOBJECT indicates that the source is an existing embedded object. It already has in its cache the appropriate data, and OLE uses this data to initialize the cache of the new object.

•	CF_EMBEDSOURCE indicates that the source data object contains the cache-initialization information in formats other than CF_EMBEDSOURCE. OleCreateFromData uses these to initialize the cache of the newly embedded object.

The renderopt values affect cache initialization as follows:

Value	Description
OLERENDER_DRAW & OLERENDER_FORMAT	If the presentation information to be cached is currently present in the appropriate cache-initialization pool, it is used. (Appropriate locations are in the source data object cache for CF_EMBEDDEDOBJECT, and in the other formats in the source data object for CF_EMBEDSOURCE.) If the information is not present, the cache is initially empty, but will be filled the first time the object is run. No other formats are cached in the newly created object.
OLERENDER_NONE	Nothing is to be cached in the newly created object. If the source has the CF_EMBEDDEDOBJECT format, any existing cached data that has been copied is removed.
OLERENDER_ASIS	If the source has the CF_EMBEDDEDOBJECT format, the cache of the new object is to contain the same cache data as the source object. For CF_EMBEDSOURCE, nothing is to be cached in the newly created object.  This option should be used by more sophisticated containers. After this call, such containers would call IOleCache::Cache and IOleCache::Uncache to set up exactly what is to be cached. For CF_EMBEDSOURCE, they would then also call IOleCache::InitCache.
See Also

OleCreate, IDataObject


OleCreateFromDataEx

Extends OleCreateFromData functionality by supporting more efficient instantiation of objects in containers requiring caching of multiple formats of presentation or data, instead of the single format supported by OleCreateFromData.

HRESULT OleCreateFromDataEx(

LPDATAOBJECT pSrcDataObj,	//Pointer to data transfer object
REFIID riid,	//Reference to the identifier of the interface of object to return
DWORD dwFlags,	//Value from OLECREATE enumeration
DWORD renderopt,	//Value from OLERENDER enumeration
ULONG cFormats,	//Number of FORMATETCs in rgFormatEtc
DWORD rgAdvf,	//Points to an array of cFormats DWORD elements
LPFORMATETC rgFormatEtc,	//Points to an array of cFormats FORMATETC structures
LPADVISESINK pAdviseSink,	//IAdviseSink pointer, or NULL, indicating default data format caching
DWORD FAR* rgdwConnection,	//Location to return array of dwConnection values
LPCLIENTSITE pClientSite,	//Pointer to primary interface the object will use to request services
LPSTORAGE pStg,	//Pointer to storage to use for object
LPVOID FAR* ppvObj	///Indirect pointer to location to return riid interface
);
Parameters

pSrcDataObj

Pointer to the data transfer object holding the new data used to create the new object. (see OleCreateFromData).

riid

Reference to the identifier of the interface of the object to return.

dwFlags

Value taken from the OLECREATE enumeration.

renderopt

Value taken from the RENDEROPT enumeration.

cFormats

When renderopt is OLERENDER_FORMAT, indicates the number of FORMATETC structures in the rgFormatEtc array, which must be at least one. In all other cases, this parameter must be zero.

rgAdvf

When renderopt is OLERENDER_FORMAT, points to an array of cFormats DWORD elements, each of which is a combination of values from the ADVF enumeration. Each element of this array is passed in as the advf parameter to a call to either IOleCache::Cache or IDataObject::DAdvise, depending on whether pAdviseSink is NULL or non-NULL (see below). In all other cases, this parameter must be NULL.

rgFormatEtc

When renderopt is OLERENDER_FORMAT, points to an array of cFormats FORMATETC structures. When pAdviseSink is NULL, each element of this array is passed as the pFormatEtc parameter to a call to the object’s IOleCache::Cache. This populates the data and presentation cache managed by the object’s in-process handler (typically the default handler) with presentation or other cacheable data. When pAdviseSink is non-NULL, each element of this array is passed as the pFormatEtc parameter to a call to IDataObject::DAdvise. This allows the caller (typically an OLE Container) to do its own caching or processing of data received from the object.

pAdviseSink

When renderopt is OLERENDER_FORMAT, may be either a valid IAdviseSink pointer, indicating custom caching or processing of data advises, or NULL, indicating default caching of data formats.

rgdwConnection

Location to return the array of dwConnection values returned when the pAdviseSink interface is registered for each advisory connection using IDataObject::DAdvise, or NULL if the returned advisory connections are not needed. Must be NULL, if pAdviseSink is NULL.

pClientSite

Pointer to the primary interface through which the object will request services from its container. This parameter may be NULL, in which case it is the caller’s responsibility to establish the client site as soon as possible using IOleObject::SetClientSite.

pStg

Pointer to the storage to use for the object and any default data or presentation caching established for it.

ppvObj

Location to return the riid interface of the newly created object.

Return Values

S_OK

Success.

E_NOINTERFACE

The object does not support the riid interface.

E_INVALIDARG

One or more arguments are invalid.

Remarks

The following call to OleCreateFromData:

    OleCreateFromData(lpszFileName, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

is equivalent to the following call to OleCreateFromDataEx:

    DWORD    advf = ADVF_PRIMEFIRST;

    OleCreateFromFileEx(rclsid, lpszFileName, riid, renderopt, 1, &advf, pFormatEtc, NULL, pClientSite, pStg, ppvObj);

Existing instantiation functions (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLink, OleCreateLinkToFile, and OleCreateLinkFromData) create only a single presentation or data format cache in the default cache location (within the ‘\001OlePresXXX’ streams of the passed-in IStorage) during instantiation. Plus, these caches must be created when the object next enters the running state. Since most applications require caching at least two presentations (screen and printer) and may require caching data in a different format or location from the handler, applications must typically launch and shut down the object server multiple times in order to prime their data caches during object creation, i.e., Insert Object, Insert Object from File, and Paste Object.

Extended versions of these creation functions solve this problem. OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx, and OleCreateLinkFromDataEx, contain the following new parameters: dwFlags to indicate additional options, cFormats to indicate how many formats to cache, rgAdvf, from the ADVF enumeration, to specify the advise flags for each format to be cached, pAdviseSink to indicate whether presentation (default-handler) or data (non-default-handler) caching is required, rgdwConnection to return IDataObject::DAdvise cookies, and pFormatEtc, an array of formats rather than a single format.

Containers requiring that multiple presentations be cached on their behalf by the object’s handler can simply call these functions and specify the number of formats in cFormats, the ADVF flags for each format in rgAdvf, and the set of formats in pFormatEtc. These containers pass NULL for pAdviseSink.

Containers performing all their own data- or presentation-caching perform these same steps, but pass a non-NULL pAdviseSink. They perform their own caching or manipulation of the object or data during IAdviseSink::OnDataChange. Typically, such containers never establish the advisory connections with ADVF_NODATA, although they are not prevented from doing so.

These new functions are for OLE Compound Documents. Using these functions, applications can avoid the repeated launching and initialization steps required by the current functions. They are targeted at OLE Compound Document container applications that use default data- and presentation-caching, and also at applications that provide their own caching and data transfer from the underlying IDataObject::DAdvise support.

See Also

OleCreateFromData, IOleCache::Cache, IDataObject::DAdvise, IStorage, IAdviseSink::OnDataChange, IOleObject::SetClientSite, OLECREATE, OLERENDER, FORMATETC, ADVF


OleCreateFromFile

Creates an embedded object from the contents of a named file.

WINOLEAPI OleCreateFromFile(

REFCLSID rclsid,	//Reserved. Must be CLSID_NULL
LPCOLESTR lpszFileName,	//Pointer to full path of file used to create object
REFIID riid,	//Reference to the identifier of the interface to be used to communicate with new object
DWORD renderopt,	//Value from OLERENDER
LPFORMATETC pFormatEtc,	//Pointer to the FORMATETC structure
LPOLECLIENTSITE pClientSite,	//Pointer to an interface
LPSTORAGE pStg,	//Pointer tothe interface to be used as object storage
LPVOID FAR* ppvObj	//Indirect pointer to the interface requested in riid
);
Parameters

rclsid

[in] Reserved. Must be CLSID_NULL.

lpszFileName

[in] Pointer to a string specifying the full path of the file from which the object should be initialized.

riid

[in] Reference to the identifier of the interface the caller later uses to communicate with the new object (usually IID_IOleObject, defined in the OLE headers as the interface ID of IOleObject).

renderopt

[in] Value from the enumeration OLERENDER that indicates the locally cached drawing or data-retrieval capabilities the newly created object is to have. The OLERENDER value chosen affects the possible values for the pFormatEtc parameter.

pFormatEtc

[in] Depending on which of the OLERENDER flags is used as the value of renderopt, pointer to one of the FORMATETC enumeration values. Refer also to the OLERENDER enumeration for restrictions.

pClientSite

[in] Pointer to an instance of IOleClientSite, the primary interface through which the object will request services from its container. May be NULL.

pStg

[in] Pointer to the IStorage interface on the storage object. This parameter may not be NULL.

ppvObj

[out] Indirect pointer to the interface requested in riid on the newly created object on return.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

Embedded object successfully created.

STG_E_FILENOTFOUND

File not bound.

OLE_E_CANT_BINDTOSOURCE

Not able to bind to source.

STG_E_MEDIUMFULL

The medium is full.

DV_E_TYMED

Invalid TYMED.

DV_E_LINDEX

Invalid LINDEX.

DV_E_FORMATETC

Invalid FORMATETC structure.

Remarks

The OleCreateFromFile function creates a new embedded object from the contents of a named file. If the ProgID in the registration database contains the PackageOnFileDrop key, it creates a package. If not, the function calls the GetClassFile function to get the CLSID associated with the lpszFileName parameter, and then creates an OLE 2-embedded object associated with that CLSID. The rclsid parameter of OleCreateFromFile will always be ignored, and should be set to CLSID_NULL.

As for other OleCreateXxx functions, the newly created object is not shown to the user for editing, which requires a DoVerb operation. It is used to implement insert file operations, such as the Create from File command in Word for Windows.

See Also

GetClassFile


OleCreateFromFileEx

Extends OLeCreateFromFile functionality by supporting  more efficient instantiation of objects in containers requiring caching of multiple presentation formats or data, instead of the single format supported by OleCreateFromFile.

HRESULT OleCreateFromFileEx(

REFCLSID rclsid,	//Reserved; must be CLSID_NULL
LPCOLESTR lpszFileName,	//Pointer to name of file to initialize new object from
REFIID riid,	//Reference to the identifier of the interface of object to return
DWORD dwFlags,	//Value from OLECREATE enumeration
DWORD renderopt,	//Value from OLERENDER enumeration
ULONG cFormats,	//Number of FORMATETC structures in the rgFormatEtc array
DWORD rgAdvf,	//Points to an array of cFormats DWORD elements
LPFORMATETC rgFormatEtc,	//Points to an array of cFormats FORMATETC structures
LPADVISESINK pAdviseSink,	//IAdviseSink pointer (custom caching), or NULL (default caching)
DWORD FAR* rgdwConnection,	//Location to return the array of dwConnection values
LPCLIENTSITE pClientSite,	//Pointer to primary interface the object will use to request services
LPSTORAGE pStg,	//Pointer to storage to use for object
LPVOID FAR* ppvObj	//Indirect pointer to location to return riid interface
);
Parameters

rclsid

Reserved for future use; must be CLSID_NULL.

lpszFileName

Pointer to the name of the file from which the new object should be initialized.

riid

Reference to the identifier of the interface of the object to return.

dwFlags

Value taken from the OLECREATE enumeration.

renderopt

Value taken from the OLERENDER enumeration.

cFormats

When renderopt is OLERENDER_FORMAT, indicates the number of FORMATETC structures in the rgFormatEtc array, which must be at least one. In all other cases, this parameter must be zero.

rgAdvf

When renderopt is OLERENDER_FORMAT, points to an array of cFormats DWORD elements, each of which is a combination of values from the ADVF enumeration. Each element of this array is passed in as the advf parameter to a call to either IOleCache::Cache or IDataObject::DAdvise, depending on whether pAdviseSink is NULL or non-NULL (see below). In all other cases, this parameter must be NULL.

rgFormatEtc

When renderopt is OLERENDER_FORMAT, points to an array of cFormats FORMATETC structures. When pAdviseSink is NULL, each element of this array is passed as the pFormatEtc parameter to a call to the object’s IOleCache::Cache. This populates the data and presentation cache managed by the objects in-process handler (typically the default handler) with presentation or other cacheable data. When pAdviseSink is non-NULL, each element of this array is passed as the pFormatEtc parameter to a call to IDataObject::DAdvise. This allows the caller (typically an OLE Container) to do its own caching or processing of data received from the object.

pAdviseSink

When renderopt is OLERENDER_FORMAT, may be either a valid IAdviseSink pointer, indicating custom caching or processing of data advises, or NULL, indicating default caching of data formats.

rgdwConnection

Location to return the array of dwConnection values returned when the pAdviseSink interface is registered for each advisory connection using IDataObject::DAdvise, or NULL if the returned advisory connections are not needed. Must be NULL, if pAdviseSink is NULL.

pClientSite

Pointer to the primary interface through which the object will request services from its container. This parameter may be NULL, in which case it is the caller’s responsibility to establish the client site as soon as possible using IOleObject::SetClientSite.

pStg

Pointer to the storage to use for the object and any default data or presentation caching established for it.

ppvObj

Location to return the riid interface of the newly created object.

Return Values

S_OK

Success.

E_NOINTERFACE

The object does not support the riid interface.

E_INVALIDARG

One or more arguments are invalid.

Remarks

The following call to OleCreateFromFile:

    OleCreateFromFile(rclsid, lpszFileName, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

is equivalent to the following call to OleCreateFromFileEx:

    DWORD    advf = ADVF_PRIMEFIRST;

    OleCreateFromFileEx(rclsid, lpszFileName, riid, renderopt, 1, &advf, pFormatEtc, NULL, pClientSite, pStg, ppvObj);

Existing instantiation functions (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLink, OleCreateLinkToFile, and OleCreateLinkFromData) create only a single presentation or data format cache in the default cache location (within the ‘\001OlePresXXX’ streams of the passed-in IStorage), during instantiation. Plus, these caches must be created when the object next enters the running state. Since most applications require caching at least two presentations (screen and printer) and may require caching data in a different format or location from the handler, applications must typically launch and shut down the object server multiple times in order to prime their data caches during object creation, i.e., Insert Object, Insert Object from File, and Paste Object.

Extended versions of these creation functions solve this problem. OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx, and OleCreateLinkFromDataEx, contain the following new parameters: dwFlags to indicate additional options, cFormats to indicate how many formats to cache, rgAdvf, from the ADVF enumeration, to specify the advise flags for each format to be cached, pAdviseSink to indicate whether presentation (default-handler) or data (non-default-handler) caching is required, rgdwConnection to return IDataObject::DAdvise cookies, and pFormatEtc, an array of formats rather than a single format.

Containers requiring that multiple presentations be cached on their behalf by the object’s handler can simply call these functions and specify the number of formats in cFormats, the ADVF flags for each format in rgAdvf, and the set of formats in pFormatEtc. These containers pass NULL for pAdviseSink.

Containers performing all their own data- or presentation-caching perform these same steps, but pass a non-NULL pAdviseSink. They perform their own caching or manipulation of the object or data during IAdviseSink::OnDataChange. Typically, such containers never establish the advisory connections with ADVF_NODATA, although they are not prevented from doing so.

These new functions are for OLE Compound Documents. Using these functions, applications can avoid the repeated launching and initialization steps required by the current functions. They are targeted at OLE Compound Document container applications that use default data- and presentation-caching, and also at applications that provide their own caching and data transfer from the underlying IDataObject::DAdvise support.

See Also

OleCreateFromFile, IOleCache::Cache, IDataObject::DAdvise, IAdviseSink::OnDataChange, IOleObject::SetClientSite, IStorage, OLERENDER, FORMATETC, ADVF


OleCreateLink

Creates an OLE compound-document linked object.

WINOLEAPI OleCreateLink(

LPMONIKER pmkLinkSrc,	//Pointer to moniker indicating source of linked object
REFIID riid,	//Reference to the identifier of the interfacer to be used to communicate with the new object
DWORD renderopt,	//Value from OLERENDER
LPFORMATETC pFormatEtc,	//Pointer to a FORMATETC structure
LPOLECLIENTSITE pClientSite,	//Pointer to an interface
LPSTORAGE pStg,	//Pointer to the object’s storage
LPVOID FAR* ppvObj	//Indirect pointer to the interface requested in riid
);
Parameters

pmkLinkSrc

[in] Pointer to the IMoniker interface on the moniker that can be used to locate the the source of the linked object.

riid

[in] Reference to the identifier of the interface the caller later uses to communicate with the new object (usually IID_IOleObject, defined in the OLE headers as the interface identifier for IOleObject).

renderopt

[in] Specifies a value from the enumeration OLERENDER that indicates the locally cached drawing or data-retrieval capabilities the newly created object is to have. Additional considerations are described in the Remarks section below.

pFormatEtc

[in] Pointer to a value from the enumeration OLERENDER that indicates the locally cached drawing or data-retrieval capabilities the newly created object is to have. The OLERENDER value chosen affects the possible values for the pFormatEtc parameter.

pClientSite

[in] Pointer to an instance of IOleClientSite, the primary interface through which the object will request services from its container. May be NULL.

pStg

[in] Pointer to the IStorage interface on the storage object. This parameter may not be NULL.

ppvObj

[out] Indirect pointer to the interface requested in riid on the newly created object.

Return Values

S_OK

The compound-document linked object was created successfully.

OLE_E_CANT_BINDTOSOURCE

Not able to bind to source. Binding is necessary to get the cache’s initialization data.

Remarks

Call OleCreateLink to allow a container to create a link to an object.

See Also

IOleObject::SetMoniker, IOleClientSite::GetMoniker


OleCreateLinkEx

Extends OleCreateLink functionality by supporting more efficient instantiation of objects in containers requiring caching of multiple formats of presentations or data, instead of the single format supported by OleCreateLink.

HRESULT OleCreateFromLinkEx(

LPMONIKER pmkLinkSrc,	//Pointer to a moniker to object to create link to
REFIID riid,	//Reference to the identifier of the interface of the link object to return
DWORD dwFlags,	//Value from OLECREATE enumeration
DWORD renderopt,	//Value from OLERENDER enumeration
ULONG cFormats,	//Number of FORMATETCs in rgFormatEt
DWORD rgAdvf,	//Points to an array of cFormats DWORD elements
LPFORMATETC rgFormatEtc,	//Points to an array of cFormats FORMATETC structures
LPADVISESINK pAdviseSink,	//IAdviseSink pointer, or NULL, indicating default data format caching
DWORD FAR* rgdwConnection,	//Location to return array of dwConnection values
LPCLIENTSITE pClientSite,	//Pointer to the primary interface the object will to use to request services
LPSTORAGE pStg,	//Pointer to storage to use for the object
LPVOID FAR* ppvObj	//Indirect pointer to location to return riid interface
);
Parameters

pmkLinkSrc

Pointer to a moniker to the object to create a link to.

riid

Reference to the identifier of the interface of the object to return.

dwFlags

Value taken from the OLECREATE enumeration.

renderopt

Value taken from the OLERENDER enumeration.

cFormats

When renderopt is OLERENDER_FORMAT, indicates the number of FORMATETC structures in the rgFormatEtc array, which must be at least one. In all other cases, this parameter must be zero.

rgAdvf

When renderopt is OLERENDER_FORMAT, points to an array of cFormats DWORD elements, each of which is a combination of values from the ADVF enumeration. Each element of this array is passed in as the advf parameter to a call to either IOleCache::Cache or IDataObject::DAdvise, depending on whether pAdviseSink is NULL or non-NULL (see below). In all other cases, this parameter must be NULL.

rgFormatEtc

When renderopt is OLERENDER_FORMAT, points to an array of cFormats FORMATETC structures. When pAdviseSink is NULL, each element of this array is passed as the pFormatEtc parameter to a call to the object’s IOleCache::Cache. This populates the data and presentation cache managed by the objects in-process handler (typically the default handler) with presentation or other cacheable data. When pAdviseSink is non-NULL, each element of this array is passed as the pFormatEtc parameter to a call to IDataObject::DAdvise. This allows the caller (typically an OLE Container) to do its own caching or processing of data received from the object.

pAdviseSink

When renderopt is OLERENDER_FORMAT, may be either a valid IAdviseSink pointer, indicating custom caching or processing of data advises, or NULL, indicating default caching of data formats.

rgdwConnection

Location to return the array of dwConnection values returned when the pAdviseSink interface is registered for each advisory connection using IDataObject::DAdvise, or NULL if the returned advisory connections are not needed. Must be NULL, if pAdviseSink is NULL.

pClientSite

Pointer to the primary interface through which the object will request services from its container. This parameter may be NULL, in which case it is the caller’s responsibility to establish the client site as soon as possible using IOleObject::SetClientSite.

pStg

Pointer to the storage to use for the object and any default data or presentation caching established for it.

ppvObj

Indirect pointer to location to return the riid interface of the newly created object.

Return Values

S_OK

Success.

E_NOINTERFACE

The object does not support the riid interface.

E_INVALIDARG

One or more arguments are invalid.

Remarks

The following call to OleCreateLink:

    OleCreateLink(pmkLinkSrc, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

is equivalent to the following call to OleCreateLinkEx:

    DWORD    advf = ADVF_PRIMEFIRST;

    OleCreateFromFileEx(pmkLinkSrc, riid, renderopt, 1, &advf, pFormatEtc, NULL, NULL, pClientSite, pStg, ppvObj);

Existing instantiation functions (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLink, OleCreateLinkToFile, and OleCreateLinkFromData) create only a single presentation or data format cache in the default cache location (within the ‘\001OlePresXXX’ streams of the passed-in IStorage) during instantiation. Plus, these caches must be created when the object next enters the running state. Since most applications require caching in at least two presentations (screen and printer) and may require caching data in a different format or location from the handler, applications must typically launch and shut down the object server multiple times in order to prime their data caches during object creation, i.e., Insert Object, Insert Object from File, and Paste Object.

Extended versions of these creation functions solve this problem. OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx, and OleCreateLinkFromDataEx, contain the following new parameters: dwFlags to indicate additional options, cFormats to indicate how many formats to cache, rgAdvf, from the ADVF enumeration, to specify the advise flags for each format to be cached, pAdviseSink to indicate whether presentation (default-handler) or data (non-default-handler) caching is required, rgdwConnection to return IDataObject::DAdvise cookies, and pFormatEtc, an array of formats rather than a single format.

Containers requiring that multiple presentations be cached on their behalf by the object’s handler can simply call these functions and specify the number of formats in cFormats, the ADVF flags for each format in rgAdvf, and the set of formats in pFormatEtc. These containers pass NULL for pAdviseSink.

Containers performing all their own data- or presentation-caching perform these same steps, but pass a non-NULL pAdviseSink. They perform their own caching or manipulation of the object or data during IAdviseSink::OnDataChange. Typically, such containers never establish the advisory connections with ADVF_NODATA, although they are not prevented from doing so.

These new functions are for OLE Compound Documents. Using these functions, applications can avoid the repeated launching and initialization steps required by the current functions. They are targeted at OLE Compound Document container applications that use default data- and presentation-caching, and also at applications that provide their own caching and data transfer from the underlying IDataObject::DAdvise support.

See Also

OleCreateLink, IOleCache::Cache, IDataObject::DAdvise, IAdviseSink::OnDataChange, IOleObject::SetClientSite, OLECREATE, OLERENDER, FORMATETC, ADVF


OleCreateLinkFromData

Creates a linked object from a data transfer object retrieved either from the clipboard or as part of an OLE drag-and-drop operation.

WINOLEAPI OleCreateLinkFromData(

LPDATAOBJECT pSrcDataObj,	//Pointer to data transfer objectt
REFIID riid,	//Reference to the identifier of the interface to be used to communicate with the new object
DWORD renderopt,	//OLERENDER value
LPFORMATETC pFormatEtc,	//Pointer to a FORMATETC structure
LPOLECLIENTSITE pClientSite,	//Pointer to an interface
LPSTORAGE pStg,	//Pointer to the object storage
LPVOID FAR* ppvObj	//Indirect pointer to requested object
);
Parameters

pSrcDataObj

[in] Pointer to the IDataObject interface on the data transfer object from which the linked object is to be created.

riid

[in] Reference to the identifier of interface the caller later uses to communicate with the new object (usually IID_IOleObject, defined in the OLE headers as the interface identifier for IOleObject).

renderopt

[in] Value from the enumeration OLERENDER that indicates the locally cached drawing or data-retrieval capabilities the newly created object is to have. Additional considerations are described in the following Remarks section.

pFormatEtc

[in] Pointer to a value from the enumeration OLERENDER that indicates the locally cached drawing or data-retrieval capabilities the newly created object is to have. The OLERENDER value chosen affects the possible values for the pFormatEtc parameter.

pClientSite

[in] Pointer to an instance of IOleClientSite, the primary interface through which the object will request services from its container. May be NULL.

pStg

[in] Pointer to the IStorage interface on the storage object. This parameter may not be NULL.

ppvObj

[out] Indirect pointer to the interface requested in riid on the newly created object on return.

Return Values

S_OK

The linked object was created successfully.

CLIPBRD_E_CANT_OPEN

Not able to open the clipboard.

OLE_E_CANT_GETMONIKER

Not able to extract the object’s moniker.

OLE_E_CANT_BINDTOSOURCE

Not able to bind to source. Binding is necessary to get the cache’s initialization data.

Remarks

The OleCreateLinkFromData function is used to implement either a paste-link or a drag-link operation. Its operation is similar to that of the OleCreateFromData function, except that it creates a link, and looks for different data formats. If the CF_LINKSOURCE format is not present, and either the FileName or FileNameW clipboard format is present in the data transfer object, OleCreateLinkFromData creates a package containing the link to the indicated file.

You use the renderopt and pFormatetc parameters to control the caching capability of the newly created object. For general information on how to determine what is to be cached, refer to the OLERENDER enumeration for a description of the interaction between renderopt and pFormatetc. There are, however, some additional specific effects of these parameters on the way OleCreateLinkFromData initializes the cache, as follows:

Value	Description
OLERENDER_DRAW, OLERENDER_FORMAT	If the presentation information is in the other formats in the source data object, this information is used. If the information is not present, the cache is initially empty, but will be filled the first time the object is run. No other formats are cached in the newly created object.
OLERENDER_NONE, OLERENDER_ASIS	Nothing is to be cached in the newly created object.
See Also

OleCreateLink


OleCreateLinkFromDataEx

Extends OleCreateLinkFromData functionality by supporting  more efficient instantiation of objects in containers requiring caching of multiple formats of presentations or data, instead of the single format supported by OleCreateLinkFromData.

HRESULT OleCreateLinkFromDataEx(

LPDATAOBJECT pSrcDataObj,	//Pointer to the data object to create a link object from
REFIID riid,	//Reference to the identifier of the interface of the link object to return
DWORD dwFlags,	//Value from OLECREATE enumeration
DWORD renderopt,	//Value from OLERENDER enumeration
ULONG cFormats,	//Number of FORMATETCs in rgFormatEtc
DWORD rgAdvf,	//Points to an array of cFormats DWORD elements
LPFORMATETC rgFormatEtc,	//Points to an array of cFormats FORMATETC structures
LPADVISESINK pAdviseSink,	//IAdviseSink pointer (custom caching); NULL (default caching); NULL otherwise
DWORD FAR* rgdwConnection,	//Location to return array of dwConnection values
LPCLIENTSITE pClientSite,	//Pointer to the primary interface the object will use to request services
LPSTORAGE pStg,	//Pointer to storage to use for object
LPVOID FAR* ppvObj	//Indirect pointer to location to return riid interface
);
Parameters

pSrcDataObj

Pointer to the data object to create a link object from.

riid

Reference to the identifier of the interface of the object to return.

dwFlags

Value taken from the OLECREATE enumeration.

renderopt

Value taken from the RENDEROPT enumeration.

cFormats

When renderopt is OLERENDER_FORMAT, indicates the number of FORMATETC structures in the rgFormatEtc array, which must be at least one. In all other cases, this parameter must be zero.

rgAdvf

When renderopt is OLERENDER_FORMAT, points to an array of cFormats DWORD elements, each of which is a combination of values from the ADVF enumeration. Each element of this array is passed in as the advf parameter to a call to either IOleCache::Cache or IDataObject::DAdvise, depending on whether pAdviseSink is NULL or non-NULL (see below). In all other cases, this parameter must be NULL.

rgFormatEtc

When renderopt is OLERENDER_FORMAT, points to an array of cFormats FORMATETC structures. When pAdviseSink is NULL, each element of this array is passed as the pFormatEtc parameter to a call to the object’s IOleCache::Cache. This populates the data and presentation cache managed by the objects in-process handler (typically the default handler) with presentation or other cacheable data. When pAdviseSink is non-NULL, each element of this array is passed as the pFormatEtc parameter to a call to IDataObject::DAdvise. This allows the caller (typically an OLE Container) to do its own caching or processing of data received from the object.

pAdviseSink

When renderopt is OLERENDER_FORMAT, may be either a valid IAdviseSink pointer, indicating custom caching or processing of data advises, or NULL, indicating default caching of data formats.

rgdwConnection

Location to return the array of dwConnection values returned when the pAdviseSink interface is registered for each advisory connection using IDataObject::DAdvise, or NULL if the returned advisory connections are not needed. Must be NULL, if pAdviseSink is NULL.

pClientSite

Pointer to the primary interface through which the object will request services from its container. This parameter may be NULL, in which case it is the caller’s responsibility to establish the client site as soon as possible using IOleObject::SetClientSite.

pStg

Pointer to the storage to use for the object and any default data or presentation caching established for it.

ppvObj

Indirect pointer to location to return the riid interface of the newly created object.

Return Values

S_OK

Success.

E_NOINTERFACE

The object does not support the riid interface.

E_INVALIDARG

One or more arguments are invalid.

Remarks

The following call to OleCreateLinkFromData:

    OleCreateLinkFromData(pSrcDataObj, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

is equivalent to the following call to OleCreateLinkFromDataEx:

    DWORD    advf = ADVF_PRIMEFIRST;

    OleCreateLinkFromDataEx(pSrcDataObj, riid, renderopt, 1, &advf, pFormatEtc, NULL, NULL, pClientSite, pStg, ppvObj);

Existing instantiation functions (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLink, OleCreateLinkToFile, and OleCreateLinkFromData), create only a single presentation or data format cache in the default cache location (within the ‘\001OlePresXXX’ streams of the passed-in IStorage) during instantiation. Plus, these caches must be created when the object next enters the running state. Since most applications require caching at least two presentations (screen and printer) and may require caching data in a different format or location from the handler, applications must typically launch and shut down the object server multiple times in order to prime their data caches during object creation, i.e., Insert Object, Insert Object from File, and Paste Object.

Extended versions of these creation functions solve this problem. OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx, and OleCreateLinkFromDataEx, contain the following new parameters: dwFlags to indicate additional options, cFormats to indicate how many formats to cache, rgAdvf, from the ADVF enumeration, to specify the advise flags for each format to be cached, pAdviseSink to indicate whether presentation (default-handler) or data (non-default-handler) caching is required, rgdwConnection to return IDataObject::DAdvise cookies, and pFormatEtc, an array of formats rather than a single format.

Containers requiring that multiple presentations be cached on their behalf by the object’s handler can simply call these functions and specify the number of formats in cFormats, the ADVF flags for each format in rgAdvf, and the set of formats in pFormatEtc. These containers pass NULL for pAdviseSink.

Containers performing all their own data- or presentation-caching perform these same steps, but pass a non-NULL pAdviseSink. They perform their own caching or manipulation of the object or data during IAdviseSink::OnDataChange. Typically such containers never establish the advisory connections with ADVF_NODATA, although they are not prevented from doing so.

These new functions are for OLE Compound Documents. Using these functions, applications can avoid the repeated launching and initialization steps required by the current functions. They are targeted at OLE Compound Document container applications that use default data- and presentation-caching, and also at applications that provide their own caching and data transfer from the underlying IDataObject::DAdvise support.

See Also

OleCreateLinkFromData, IOleCache::Cache, IDataObject::DAdvise, IAdviseSink::OnDataChange, IOleObject::SetClientSite, OLECREATE, OLERENDER, FORMATETC, ADVF


OleCreateLinkToFile

Creates an object that is linked to a file.

WINOLEAPI OleCreateLinkToFile(

LPWSTR lpszFileName,	//Pointer to source of linked object
REFIID riid,	//Reference to the identifier of the interface to be used to communicate with the new object
DWORD renderopt,	//Value from OLERENDER
LPFORMATETC pFormatEtc,	//Pointer to a FORMATETC structure
IOleClientSite * pClientSite,	//Pointer to an interface
IStorage * pStg,	//Pointer to the object’s storage
void ** ppvObj	//Indirect pointer to the interface requested in riid
);
Parameters

lpszFileName

[in] Pointer to a string naming the source file to be linked to.

riid

[in] Reference to the identifier of the interface the caller later uses to communicate with the new object (usually IID_IOleObject, defined in the OLE headers as the interface identifier for IOleObject).

renderopt

[in] Value from the enumeration OLERENDER that indicates the locally cached drawing or data-retrieval capabilities the newly created object is to have. Additional considerations are described in the following Remarks section.

pFormatEtc

[in] Pointer to a value from the enumeration OLERENDER that indicates the locally cached drawing or data-retrieval capabilities the newly created object is to have. The OLERENDER value chosen affects the possible values for the pFormatEtc parameter.

pClientSite

[in] Pointer to an instance of IOleClientSite, the primary interface through which the object will request services from its container. May be NULL.

pStg

[in] Pointer to the IStorage interface on the storage object. This parameter may not be NULL.

ppvObj

[out] Indirect pointer to the interface requested in riid on the newly created object on return.

Return Values

S_OK

The object was created successfully.

STG_E_FILENOTFOUND

The file name is invalid.

OLE_E_CANT_BINDTOSOURCE

Not able to bind to source.

Remarks

The OleCreateLinkToFile function differs from the OleCreateLink function because it can create links both to files that are not aware of OLE, as well as to those that are using the Windows Packager.

See Also

OleCreateLink


OleCreateLinkToFileEX

Extends OleCreateLinkToFile functionality by supporting more efficient instantiation of objects in containers requiring caching of multiple formats of presentations or data, instead of the single format supported by OleCreateLinkToFile.

HRESULT OleCreateLinkToFileEx(

LPCOLESTR lpszFileName,	//Pointer to the name of the file to create a link to.
REFIID riid,	//Reference to the identifier of the interface of the link object to return
DWORD dwFlags,	//Value from OLECREATE enumeration
DWORD renderopt,	//Value from OLERENDER enumeration
ULONG cFormats,	//Number of FORMATETCs in rgFormatEtc
DWORD rgAdvf,	//Points to an array of cFormats DWORD elements
LPFORMATETC rgFormatEtc,	//Points to an array of cFormats FORMATETC structures
LPADVISESINK pAdviseSink,	///IAdviseSink pointer (custom caching); NULL (default caching); NULL otherwise
DWORD FAR* rgdwConnection,	//Location to return array of dwConnection values
LPCLIENTSITE pClientSite,	//Pointer to the primary interface the object will use to request services.
LPSTORAGE pStg,	//Pointer to storage to use for object
LPVOID FAR* ppvObj	//Indirect pointer to location to return riid interface
);
Parameters

lpszFileName

Pointer to the name of the file to create a link to.

riid

Reference to the identifier of the interface of the object to return.

dwFlags

Value taken from the OLECREATE enumeration.

renderopt

Value taken from the RENDEROPT enumeration.

cFormats

When renderopt is OLERENDER_FORMAT, indicates the number of FORMATETC structures in the rgFormatEtc array, which must be at least one. In all other cases, this parameter must be zero.

rgAdvf

When renderopt is OLERENDER_FORMAT, points to an array of cFormats DWORD elements, each of which is a combination of values from the ADVF enumeration. Each element of this array is passed in as the advf parameter to a call to either IOleCache::Cache or IDataObject::DAdvise, depending on whether pAdviseSink is NULL or non-NULL (see below). In all other cases, this parameter must be NULL.

rgFormatEtc

When renderopt is OLERENDER_FORMAT, points to an array of cFormats FORMATETC structures. When pAdviseSink is NULL, each element of this array is passed as the pFormatEtc parameter to a call to the object’s IOleCache::Cache. This populates the data and presentation cache managed by the objects in-process handler (typically the default handler) with presentation or other cacheable data. When pAdviseSink is non-NULL, each element of this array is passed as the pFormatEtc parameter to a call to IDataObject::DAdvise. This allows the caller (typically an OLE Container) to do its own caching or processing of data received from the object.

pAdviseSink

When renderopt is OLERENDER_FORMAT, may be either a valid IAdviseSink pointer, indicating custom caching or processing of data advises, or NULL, indicating default caching of data formats.

rgdwConnection

Location to return the array of dwConnection values returned when the pAdviseSink interface is registered for each advisory connection using IDataObject::DAdvise, or NULL if the returned advisory connections are not needed. Must be NULL, if pAdviseSink is NULL.

pClientSite

Pointer to the primary interface through which the object will request services from its container. This parameter may be NULL, in which case it is the caller’s responsibility to establish the client site as soon as possible using IOleObject::SetClientSite.

pStg

Pointer to the storage to use for the object and any default data or presentation caching established for it.

ppvObj

Location to return the riid interface of the newly created object.

Return Values

S_OK

Success.

E_NOINTERFACE

The object does not support the riid interface.

E_INVALIDARG

One or more arguments are invalid.

Remarks

The following call to OleCreateLinkToFile:

    OleCreateLinkToFile(lpszFileName, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

is equivalent to the following call to OleCreateLinkToFileEx:

    DWORD    advf = ADVF_PRIMEFIRST;

    OleCreateLinkToFileEx(lpszFileName, riid, renderopt, 1, &advf, pFormatEtc, NULL, NULL, pClientSite, pStg, ppvObj);

Existing instantiation functions (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLink, OleCreateLinkToFile, and OleCreateLinkFromData) create only a single presentation or data format cache in the default cache location (within the ‘\001OlePresXXX’ streams of the passed-in IStorage) during instantiation. Plus, these caches must be created when the object next enters the running state. Since most applications require caching at least two presentations (screen and printer) and may require caching data in a different format or location from the handler, applications must typically launch and shut down the object server multiple times in order to prime their data caches during object creation, i.e., Insert Object, Insert Object from File, and Paste Object.

Extended versions of these creation functions solve this problem. OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx, and OleCreateLinkFromDataEx, contain the following new parameters: dwFlags to indicate additional options, cFormats to indicate how many formats to cache, rgAdvf, from the ADVF enumeration, to specify the advise flags for each format to be cached, pAdviseSink to indicate whether presentation (default-handler) or data (non-default-handler) caching is required, rgdwConnection to return IDataObject::DAdvise cookies, and pFormatEtc, an array of formats rather than a single format.

Containers requiring that multiple presentations be cached on their behalf by the object’s handler can simply call these functions and specify the number of formats in cFormats, the ADVF flags for each format in rgAdvf, and the set of formats in pFormatEtc. These containers pass NULL for pAdviseSink.

Containers performing all their own data- or presentation-caching perform these same steps, but pass a non-NULL pAdviseSink. They perform their own caching or manipulation of the object or data during IAdviseSink::OnDataChange. Typically, such containers never establish the advisory connections with ADVF_NODATA, although they are not prevented from doing so.

These new functions are for OLE Compound Documents. Using these functions, applications can avoid the repeated launching and initialization steps required by the current functions. They are targeted at OLE Compound Document container applications that use default data- and presentation-caching, and also at applications that provide their own caching and data transfer from the underlying IDataObject::DAdvise support.

See Also

OleCreateLinkToFile, IOleCache::Cache, IDataObject::DAdvise, IStorage, IAdviseSink::OnDataChange, IOleObject::SetClientSite, OLECREATE, OLERENDER, FORMATETC, ADVF


OleCreateMenuDescriptor

Creates and returns an OLE menu descriptor (that is, an OLE-provided data structure that describes the menus) for OLE to use when dispatching menu messages and commands.

HOLEMENU OleCreateMenuDescriptor(

HMENU hmenuCombined,	//Handle to the combined menu
LPOLEMENUGROUPWIDTHS lpMenuWidths	//Pointer to the number of menus in each group
);
Parameters

hmenuCombined

[in] Handle to the combined menu created by the object.

lpMenuWidths

[in] Pointer to an array of six LONG values giving the number of menus in each group.

Return Value

Returns the handle to the descriptor, or NULL if insufficient memory is available.

Remarks

The OleCreateMenuDescriptor function can be called by the object to create a descriptor for the composite menu. OLE then uses this descriptor to dispatch menu messages and commands. To free the shared menu descriptor when it is no longer needed, the container should call the companion helper function, OleDestroyMenuDescriptor.

See Also

OleDestroyMenuDescriptor


OleCreatePictureIndirect

Creates a new picture object initialized according to a PICTDESC structure, which can be NULL to create an uninitialized object if the caller wishes to have the picture initialize itself through IPersistStream::Load. The fOwn parameter indicates whether the picture is to own the GDI picture handle for the picture it contains, so that the picture object will destroy its picture when the object itself is destroyed. The function returns an interface pointer to the new picture object specified by the caller in the riid parameter. A QueryInterface is built into this call. The caller is responsible for calling Release through the interface pointer returned.

STDAPI OleCreatePictureIndirect(

PICTDESC* pPictDesc,	//Pointer to the structure of parameters for picture
REFIID  riid,	//Reference to the identifier of the interface
BOOL fOwn,	//Whether the picture is to be destroyed
VOID** ppvObj	//Indirect pointer to the initial interface pointer on the new object
);
Parameters

pPictDesc

[in] Pointer to a caller-allocated structure containing the initial state of the picture.

riid

[in] Reference to the identifier of the interface describing the type of interface pointer to return in ppvObj.

fOwn

[in] If TRUE, the picture object is to destroy its picture when the object is destroyed. If FALSE, the caller is responsible for destroying the picture.

ppvObj

[out] Indirect pointer to the initial interface pointer on the new object. If the call is successful, the caller is responsible for calling Release through this interface pointer when the new object is no longer needed. If the call fails, the value of ppvObj is set to NULL.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The new picture object was created successfully.

E_NOINTERFACE

The object does not support the interface specified in riid.

E_POINTER

The address in pPictDesc or ppvObj is not valid. For example, it may be NULL.

See Also

OleLoadPicture, PICTDESC


OleCreatePropertyFrame

Invokes a new property frame, that is, a property sheet dialog box, whose parent is hwndOwner, where the dialog is positioned at the point (x,y) in the parent window and has the caption lpszCaption.

STDAPI OleCreatePropertyFrame(

HWND hwndOwner,	//Parent window of property sheet dialog box
UINT x,	//Horizontal position for dialog box
UINT y,	//Vertical position for dialog box
LPCOLESTR lpszCaption,	//Pointer to the dialog box caption
ULONG cObjects,	//Number of object pointers in lplpUnk
LPUNKNOWN FAR* lplpUnk,	//Pointer to the objects for property sheet
ULONG cPages,	//Number of property pages in lpPageClsID
LPCLSID lpPageClsID,	//Array of CLSIDs for each property page
LCID lcid,	//Locale identifier for property sheet locale
DWORD dwReserved,	//Reserved
LPVOID lpvReserved	//Reserved
);
Parameters

hwndOwner

[in] Parent window of the resulting property sheet dialog box.

x

[in] Horizontal position for the dialog box relative to hwndOwner.

y

[in] Vertical position for the dialog box relative to hwndOwner.

lpszCaption

[in] Pointer to the string used for the caption of the dialog box.

cObjects

[in] Number of object pointers passed in lplpUnk.

lplpUnk

[in] An array of IUnknown pointers on the objects for which this property sheet is being invoked. The number of elements in the array is specified by cObjects. These pointers are passed to each property page through IPropertyPage::SetObjects.

cPages

[in] Number of property pages specified in lpPageCIsID.

lpPageCIsID

[in] Array of size cPages containing the CLSIDs of each property page to display in the property sheet.

lcid

[in] Locale identifier to use for the property sheet. Property pages can retrieve this identifier through IPropertyPageSite::GetLocaleID.

dwReserved

[in] Reserved for future use; must be zero.

lpvReserved

[in] Reserved for future use; must be NULL.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The dialog box was invoked and operated successfully.

E_POINTER

The address in lpszCaption, lplpUnk, or lpPageCIsID is not valid. For example, any one of them may be NULL.

Remarks

The property pages to be displayed are identified with lpPageClsID, which is an array of cPages CLSID values. The objects that are affected by this property sheet are identified in lplpUnk, an array of size cObjects containing IUnknown pointers.

This function always creates a modal dialogbox  and does not return until the dialog box is closed.

See Also

OleCreatePropertyFrameIndirect


OleCreatePropertyFrameIndirect

Creates a property frame, that is, a property sheet dialog box, based on a structure (OCPFIPARAMS) that contains the parameters, rather than specifying separate parameters as when calling OleCreatePropertyFrame.

STDAPI OleCreatePropertyFrameIndirect(

OCPFIPARAMS* pParams	//Pointer to the structure of parameters for dialog box
);
Parameters

pParams

[in] Pointer to the caller-allocated structure containing the creation parameters for the dialog box.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The dialog box was invoked and operated successfully.

E_POINTER

The address in pParams is not valid. For example, it may be NULL.

Remarks

Besides cbStructSize (the size of the structure) and dispIDInitialProperty, all of the members of the OCPFIPARAMS structure have the same semantics as the parameters for OleCreatePropertyFrame. When dispIDInitialProperty is DISPID_UNKNOWN, the behavior of the two functions is identical.

Working in conjunction with IPerPropertyBrowsing and IPropertyPage2, dispIDInitialProperty allows the caller to specify which single property should be highlighted when the dialog box is made visible. This feature is not available when using OleCreatePropertyFrame. To determine the page and property to show initially, the property frame will do the following:

1.	Call (*lplpUnk)->QueryInterface(IID_IPerPropertyBrowsing, ...) to get an interface pointer to the first object.

2.	Call IPerPropertyBrowsing::MapPropertyToPage(dispIDInitialProperty, ...) to determine which page CLSID contains the property to be highlighted. All objects for which this frame is being invoked must support the set of properties displayed in the frame.

3.	When the dialog box is created, the property page with the CLSID retrieved in Step 2 is activated with IPropertyPage::Activate.

4.	The property frame queries the active page for IPropertyPage2.

5.	If successful, the frame calls IPropertyPage2::EditProperty(dispIDInitialProperty) to highlight the correct field in that dialog box.

See Also

OCPFIPARAMS, OleCreatePropertyFrame


OleCreateStaticFromData

Creates a static object (containing only a representation, with no native data) from a data transfer object.

WINOLEAPI OleCreateStaticFromData(

LPDATAOBJECT pSrcDataObj,	//Pointer to the data transfer object
REFIID riid,	//Reference to the identifier of the interface to be used to communicate with the new object
DWORD renderopt,	//Value from OLERENDER
LPFORMATETC pFormatEtc,	//Depending on renderopt, pointer to value from FORMATETC
LPOLECLIENTSITE pClientSite,	//Pointer to the interface
LPSTORAGE pStg,	//Pointer to store object
LPVOID FAR* ppvObj	//Indirect pointer to the interface requested in riid
);
Parameters

pSrcDataObj

[in] Pointer to the IDataObject interface on the data transfer object that holds the data from which the object will be created.

riid

[in] Reference to the identifier of the interface with which the caller is to communicate with the new object (usually IID_IOleObject, defined in the OLE headers as the interface identifier for IOleObject).

renderopt

[in] Value from the enumeration OLERENDER indicating the locally cached drawing or data-retrieval capabilities that the container wants in the newly created component. It is an error to pass the render options OLERENDER_NONE or OLERENDER_ASIS to this function.

pFormatEtc

[in] Depending on which of the OLERENDER flags is used as the value of renderopt, may be a pointer to one of the FORMATETC enumeration values. Refer to the OLERENDER enumeration for restrictions.

pClientSite

[in] Pointer to an instance of IOleClientSite, the primary interface through which the object will request services from its container. May be NULL.

pStg

[in] Pointer to the IStorage interface for storage for the object. This parameter may not be NULL.

ppvObj

[out] When the function returns successfully, indirect pointer to the interface requested in riid on the newly created object.

Return Value

S_OK

The object was successfully created.

Remarks

The OleCreateStaticFromData function can convert any object, as long as it provides an IDataObject interface, to a static object. It is useful in implementing the Convert To Picture option for OLE linking or embedding.

Static objects can be created only if the source supports one of the OLE-rendered clipboard formats: CF_METAFILEPICT, CF_DIB, or CF_ BITMAP, and CF_ENHMF.

You can also call OleCreateStaticFromData to paste a static object from the clipboard. To determine whether an object is static, call the OleQueryCreateFromData function, which returns OLE_S_STATIC if one of CF_METAFILEPICT, CF_DIB, or CF_BITMAP is present and an OLE format is not present. This indicates that you should call OleCreateStaticFromData rather than the OleCreateFromData function to create the object.

The new static object is of class CLSID_StaticMetafile (in the case of CF_METAFILEPICT) and CLSID_StaticDib (in the case of CF_DIB or CF_BITMAP). The static object sets the OLEMISC_STATIC and OLE_CANTLINKINSIDE bits returned from IOleObject::GetMiscStatus. The static object will have the aspect DVASPECT_CONTENT and a LINDEX of -1.

The pDataObject is still valid after OleCreateStaticFromData returns. It is the caller’s responsibility to free pDataObject — OLE does not release it.

There cannot be more than one presentation stream in a static object.

Note  The OLESTREAM<->IStorage conversion functions also convert static objects.

See Also

OleCreateFromData


OleDestroyMenuDescriptor

Called by the container to free the shared menu descriptor allocated by the OleCreateMenuDescriptor function.

void OleDestroyMenuDescriptor(

HOLEMENU holemenu	//Handle to the shared menu descriptor
);
Parameter

holemenu

[in] Handle to the shared menu descriptor that was returned by the OleCreateMenuDescriptor function.

Return Value

None. (This function does not indicate failure.)

See Also

OleCreateMenuDescriptor


OleDoAutoConvert

Automatically converts an object to a new class if automatic conversion for that object class is set in the registry.

WINOLEAPI OleDoAutoConvert(

IStorage * pStg,	//Pointer to storage object to be converted
LPCLSID pClsidNew	//Pointer to new CLSID of converted object
);
Parameters

pStg

[in] Pointer to the IStorage interface on the storage object to be converted.

pClsidNew

[out] Pointserto the new CLSID for the object being converted. If there was no automatic conversion, this may be the same as the original class.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

No conversion is needed or a conversion was successfully completed.

REGDB_E_KEYMISSING

The function cannot read a key from the registry.

This function can also return any of the error values returned by the OleGetAutoConvert function. When accessing storage and stream objects, see the IStorage::OpenStorage and IStorage::OpenStream methods for possible errors. When it is not possible to determine the existing CLSID or when it is not possible to update the storage object with new information, see the IStream interface for other error return values.

Remarks

The OleDoAutoConvert function automatically converts an object if automatic conversion has previously been specified in the registry by the OleSetAutoConvert function. Object conversion means that the object is permanently associated with a new CLSID. Automatic conversion is typically specified by the setup program for a new version of an object application, so that objects created by its older versions can be automatically updated.

A container application that supports object conversion should call OleDoAutoConvert each time it loads an object. If the container uses the OleLoad helper function, it need not call OleDoAutoConvert explicitly because OleLoad calls it internally.

OleDoAutoConvert first determines whether any conversion is required by calling the OleGetAutoConvert function, which, if no conversion is required, returns S_OK. If the object requires conversion, OleDoAutoConvert modifies and converts the storage object by activating the new object application. The new object application reads the existing data format, but saves the object in the new native format for the object application.

If the object to be automatically converted is an OLE 1 object, the ItemName string is stored in a stream called “\1Ole10ItemName.” If this stream does not exist, the object’s item name is NULL.

The storage object must be in the unloaded state when OleDoAutoConvert is called.

See Also

OleSetAutoConvert


OleDraw

The OleDraw helper function can be used to draw objects more easily. You can use it instead of calling IViewObject::Draw directly.

WINOLEAPI OleDraw(

IUnknown * pUnk,	//Pointer to the view object to be drawn
DWORD dwAspect,	//How the object is to be represented
HDC hdcDraw,	//Device context on which to draw
LPCRECT lprcBounds	//Pointer to the rectangle in which the object is drawn
);
Parameters

pUnk

[in] Pointer to the IUnknown interface on the view object that is to be drawn.

dwAspect

[in] How the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. Valid values are taken from the enumeration DVASPECT. See DVASPECT for more information.

hdcDraw

[in] Device context on which to draw. Cannot be a metafile device context.

lprcBounds

[in] Pointer to a RECT structure specifying the rectangle in which the object should be drawn. This parameter is converted to a RECTL structure and passed to IViewObject::Draw.

Return Values

This function supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

S_OK

Object was successfully drawn.

OLE_E_BLANK

No data to draw from.

E_ABORT

The draw operation was aborted.

VIEW_E_DRAW

An error occurred in drawing.

OLE_E_INVALIDRECT

The rectangle is invalid.

DV_E_NOIVIEWOBJECT

The object doesn't support the IViewObject interface.

Remarks

The OleDraw helper function calls the QueryInterface method for the object specified (pUnk), asking for an IViewObject interface on that object. Then, OleDraw converts the RECT structure to a RECTL structure, and calls IViewObject::Draw as follows:

lpViewObj->Draw(dwAspect,-1,0,0,0,hdcDraw,&rectl,0,0,0);

Do not use OleDraw to draw into a metafile because it does not specify the lprcWBounds parameter required for drawing into metafiles.

See Also

IViewObject::Draw


OleDuplicateData

Duplicates the data found in the specified handle and returns a handle to the duplicated data. The source data is in a clipboard format. Use this function to help implement some of the data transfer interfaces such as IDataObject.

HANDLE OleDuplicateData(

HANDLE hSrc,	//Handle of the source data
CLIPFORMAT cfFormat,	//Clipboard format of the source data
UINT uiFlags	//Flags used in global memory allocation
);
Parameters

hSrc

[in] Handle of the source data.

cfFormat

[in] Clipboard format of the source data.

uiFlags

[in] Flags to be used to allocate global memory for the copied data. These flags are passed to GlobalAlloc. If the value of uiFlags is NULL, GMEM_MOVEABLE is used as a default flag.

Return Values

handle

When the function is successful, contains the handle to the new data because data was successfully duplicated.

NULL

A NULL return value indicates that there was an error duplicating data.

Remarks

The CF_METAFILEPICT, CF_PALETTE, or CF_BITMAP formats receive special handling. They are GDI handles and a new GDI object must be created instead of just copying the bytes. All other formats are duplicated byte-wise. For the formats that are duplicated byte-wise, hSrc must be a global memory handle.


OleFlushClipboard

Carries out the clipboard shutdown sequence. It also releases the IDataObject pointer that was placed on the clipboard by the OleSetClipboard function.

WINOLEAPI OleFlushClipboard();

Return Values

S_OK

The clipboard has been flushed.

CLIPBRD_E_CANT_OPEN

The Windows OpenClipboard function used within OleFlushClipboard failed.

CLIPBRD_E_CANT_CLOSE

The Windows CloseClipboard function used within OleFlushClipboard failed.

Remarks

OleFlushClipboard renders the data from a data object onto the clipboard and releases the IDataObject pointer to the data object. While the application that put the data object on the clipboard is running, the clipboard holds only a pointer to the data object, thus saving memory. If you are writing an application that acts as the source of a clipboard operation, you can call the OleFlushClipboard function when your application is closed, such as when the user exits from your application. Calling OleFlushClipboard enables pasting and paste-linking of OLE objects after application shutdown.

Before calling OleFlushClipboard, you can easily determine if your data is still on the clipboard with a call to the OleIsCurrentClipboard function.

OleFlushClipboard leaves all formats offered by the data transfer object, including the OLE 1 compatibility formats, on the clipboard so they are available after application shutdown. In addition to OLE 1 compatibility formats, these include all formats offered on a global handle medium (all except for TYMED_FILE) and formatted with a NULL target device. For example, if a data-source application offers a particular clipboard format (say cfFOO) on an IStorage object, and calls the OleFlushClipboard function, the storage object is copied into memory and the hglobal memory handle is put on the Clipboard.

To retrieve the information on the clipboard, you can call the OleGetClipboard function from another application, which creates a default data object, and the hglobal from the clipboard again becomes a storage object. Furthermore, the FORMATETC enumerator and the IDataObject::QueryGetData method would all correctly indicate that the original clipboard format (cfFOO) is again available on a TYMED_ISTORAGE.

To empty the clipboard, call the OleSetClipboard function specifying a NULL value for its parameter. The application should call this when it closes if there is no need to leave data on the clipboard after shutdown, or if data will be placed on the clipboard using the standard Windows clipboard functions.

See Also

OleGetClipboard, OleSetClipboard, OleIsCurrentClipboard, IDataObject


OleGetAutoConvert

Determines whether the registry is set for objects of a specified CLSID to be automatically converted to another CLSID, and if so, retrieves the new CLSID.

WINOLEAPI OleGetAutoConvert(

REFCLSID clsidOld,	//CLSID of the object to be converted
LPCLSID pClsidNew	//Pointer to new CLSID for object being converted
);
Parameters

clsidOld

[in] CLSID for an object to determine whether that CLSID is set for automatic conversion.

pClsidNew

[out] Pointrt to where the new CLSID, if any, is written. If auto-conversion for clsidOld is not set in the registry, clsidOld is written to that location. The pClsidNew parameter is never NULL.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

IA value was successfully returned through the pclsidNew parameter.

REGDB_E_CLASSNOTREG

The clsidOld CLSID is not properly registered in the registry.

REGDB_E_READREGDB

Error reading the registry.

REGDB_E_KEYMISSING

Auto-convert is not active or there was no registry entry for the clsidOld parameter.

Remarks

The OleGetAutoConvert function returns the AutoConvertTo entry in the registry for the specified object. The AutoConvertTo subkey specifies whether objects of a given CLSID are to be automatically converted to a new CLSID. This is usually used to convert files created by older versions of an application to the current version. If there is no AutoConvertTo entry, this function returns the value of clsidOld.

The OleDoAutoConvert function calls OleGetAutoConvert to determine if the object specified is to be converted. A container application that supports object conversion should call OleDoAutoConvert each time it loads an object. If the container uses the OleLoad helper function, it need not call OleDoAutoConvert explicitly because OleLoad calls it internally.

To set up automatic conversion of a given class, you can call the OleSetAutoConvert function (typically in the setup program of an application installation). This function uses the AutoConvertTo subkey to tag a class of objects for automatic conversion to a different class of objects. This is a subkey of the CLSID key, and contains the following information:

CLSID\{clsid}=MainUserTypeName\AutoConvertTo = clsid

See Also

OleSetAutoConvert, OleDoAutoConvert


OleGetClipboard

Retrieves a data object that you can use to access the contents of the clipboard.

WINOLEAPI OleGetClipboard(

IDataObject ** ppDataObj	//Indirect pointer to the interface on the data object
);
Parameter

ppDataObj

[out] Indirect pointer to the IDataObject interface on the clipboard data object.

Return Values

This function supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

S_OK

The data object was successfully retrieved.

CLIPBRD_E_CANT_CLOSE

The Windows CloseClipboard function used within OleGetClipboard failed.

CLIPBRD_E_CANT_OPEN

The Windows OpenClipboard function used with OleGetClipboard failed.

Remarks

If you are writing an application that can accept data from the clipboard, call the OleGetClipboard function to get a pointer to the IDataObject interface that you can use to retrieve the contents of the clipboard.

OleGetClipboard handles three cases:

1.	The application that placed data on the clipboard with the OleSetClipboard function is still running.

2.	The application that placed data on the clipboard with the OleSetClipboard function has subsequently called the OleFlushClipboard function.

3.	There is data from a non-OLE application on the clipboard.

In the first case, the clipboard data object returned by OleGetClipboard may forward calls as necessary to the original data object placed on the clipboard and, thus, can potentially make RPC calls.

In the second case, OLE creates a default data object and returns it to the user. Because the data on the Clipboard originated from an OleSetClipboard call, the OLE-provided data object contains more accurate information about the type of data on the Clipboard. In particular, the original medium (TYMED) on which the data was offered is known. Thus, if a data-source application offers a particular clipboard format, for example cfFOO, on a storage object and calls the OleFlushClipboard function, the storage object is copied into memory and the hglobal memory handle is put on the Clipboard. Then, when the OleGetClipboard function creates its default data object, the hglobal from the clipboard again becomes an IStorage object. Furthermore, the FORMATETC enumerator and the IDataObject::QueryGetData method would all correctly indicate that the original clipboard format (cfFOO) is again available on a TYMED_ISTORAGE.

In the third case, OLE still creates a default data object, but there is no special information about the data in the Clipboard formats (particularly for application-defined Clipboard formats). Thus, if an hGlobal-based storage medium were put on the Clipboard directly by a call to the SetClipboardData function, the FORMATETC enumerator and the IDataObject::QueryGetData method would not indicate that the data was available on a storage medium. A call to the IDataObject::GetData method for TYMED_ISTORAGE would succeed, however. Because of these limitations, it is strongly recommended that OLE-aware applications interact with the Clipboard using the OLE Clipboard functions.

The clipboard data object created by the OleGetClipboard function has a fairly extensive IDataObject implementation. The OLE-provided data object can convert OLE 1 clipboard format data into the representation expected by an OLE 2 caller. Also, any structured data is available on any structured or flat medium, and any flat data is available on any flat medium. However, GDI objects (such as metafiles and bitmaps) are only available on their respective mediums.

Note that the tymed member of the FORMATETC structure used in the FORMATETC enumerator contains the union of supported mediums. Applications looking for specific information (such as whether CF_TEXT is available on TYMED_HGLOBAL) should do the appropriate bit masking when checking this value.

If you call the OleGetClipboard function, you should only hold on to the returned IDataObject for a very short time. It consumes resources in the application that offered it.

See Also

OleSetClipboard


OleGetIconOfClass

Returns a handle to a metafile containing an icon and a string label for the specified CLSID.

HGLOBAL OleGetIconOfClass(

REFCLSID rclsid,	//CLSID for which information is requested
LPOLESTR lpszLabel,	//Pointer to string to use as label for icon
BOOL fUseTypeAsLabel	//Whether to use CLSID’s user type name as icon label
);
Parameters

rclsid

[in] CLSID for which the icon and string are requested.

lpszLabel

[in] Pointer to a string to use as a label for the icon.

fUseTypeAsLabel

[in] Whether or not to use the user type string in the CLSID as the icon label.

Return Value

HGLOBAL

The hGlobal value returned when the function succeeds is a handle to a metafile that contains an icon and label for the specified CLSID. If the CLSID cannot be found in the registration database, NULL is returned.

See Also

OleGetIconOfFile, OleMetafilePictFromIconAndLabel


OleGetIconOfFile

Returns a handle to a metafile containing an icon and string label for the specified file name.

HGLOBAL OleGetIconOfFile(

LPOLESTR lpszPath,	//Pointer to string that specifies the file for which info is requested
BOOL fUseFileAsLabel	//Whether to use the file name as the icon label
);
Parameters

lpszPath

[in] Pointer to a file for which the icon and string are requested.

fUseFileAsLabel

[in] Whether or not to use the file name as the icon label.

Return Value

HGLOBAL

The hGlobal returned is a handle to a metafile that contains an icon and label for the specified file. If there is no CLSID in the registration database for the file, then the string “Document” is used. If the value of lpszPath is NULL, then NULL is returned.

See Also

OleGetIconOfClass, OleMetafilePictFromIconAndLabel


OleIconToCursor

Converts an icon to a cursor. For Win32 applications, this function calls the Win32 function CopyCursor(hIcon).

STDAPI OleIconToCursor(

HINSTANCE hinstExe,	//Ignored in Win32
HICON hIcon	//Handle to the icon
);
Parameters

hinstExe

[in] Ignored in Win32.

hIcon

[in] Handle to the icon to be converted to a cursor.

Remarks

The return value is an HCURSOR for the new cursor object. The caller is responsible for deleting this cursor with the Win32 function DestroyCursor. If the conversion could not be completed, the return value is NULL.


OleInitialize

The OleInitialize function initializes the OLE library. You must initialize the library before you can call OLE functions.

WINOLEAPI OleInitialize(

LPVOID pvReserved	//Reserved
);
Parameter

pvReserved

[in] In 32-bit OLE, reserved; must be NULL. The 32-bit version of OLE does not support applications replacing OLE’s allocator and if the parameter is not NULL, OleInitialize returns E_INVALIDARG.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The library was initialized successfully.

S_FALSE

The OLE library is already initialized; a pointer to the IMalloc implementation was not used.

OLE_E_WRONGCOMPOBJ

Indicates COMPOBJ.DLL is the wrong version for OLE2.DLL.

Remarks

Compound document applications must call OleInitialize before calling any other function in the OLE library. OleInitialize calls the CoInitialize function internally.

Typically, OleInitialize is called only once in the process that uses the OLE library. There can be multiple calls, but subsequent calls return S_FALSE. To close the library gracefully, each successful call to OleInitialize, including those that return S_FALSE, must be balanced by a corresponding call to the OleUninitialize function.

See Also

OleUninitialize, CoInitialize


OleIsCurrentClipboard

Determines whether the data object pointer previously placed on the clipboard by the OleSetClipboard function is still on the clipboard.

WINOLEAPI OleIsCurrentClipboard(

IDataObject * pDataObject	//Pointer to the data object previously copied or cut
);
Parameter

pDataObject

[in] Pointer to the IDataObject interface on the data object containing clipboard data of interest, which the caller previously placed on the clipboard.

Return Values

S_OK

The IDataObject pointer is currently on the clipboard and the caller is the owner of the clipboard.

S_FALSE

The indicated pointer is not on the clipboard.

Remarks

OleIsCurrentClipboard only works for the data object used in the OleSetClipboard function. It cannot be called by the consumer of the data object to determine if the object that was on the clipboard at the previous OleGetClipboard call is still on the clipboard.

See Also

OleFlushClipboard, OleSetClipboard


OleIsRunning

Determines whether a compound document object is currently in the running state.

BOOL OleIsRunning(

LPOLEOBJECT pObject	//Pointer to the interface
);
Parameter

pObject

[in] Pointer to the IOleObject interface on the object of interest.

Return Value

The return value is TRUE if the object is running; otherwise, it is FALSE.

Remarks

You can use OleIsRunning and IRunnableObject::IsRunning interchangeably. OleIsRunning queries the object for a pointer to the IRunnableObject interface and calls its IsRunning method. If successful, the function returns the results of the call to IRunnableObject::IsRunning.

Note  The implementation of OleIsRunning in earlier versions of OLE differs from that described here.

See Also

IRunnableObject::IsRunning


OleLoad

Loads into memory an object nested within a specified storage object.

WINOLEAPI OleLoad(

IStorage * pStg,	//Pointer to the storage object from which to load
REFIID riid,	//Reference to the identifier interface
IOleClientSite * pClientSite,	//Pointer to the client site for the object
LPVOID * ppvObj	//Indirect pointer to the newly loaded object
);
Parameters

pStg

[in] Pointer to the IStorage interface on the storage object from which to load the specified object.

riid

[in] Reference to the identifier of the interface that the caller wants to use to communicate with the object once it is loaded.

pClientSite

[in] Pointer to the IOleClientSite interface on the client site object being loaded.

ppvObj

[out] When successful, indirect pointer to the interface specified in riid on the newly loaded object.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The object was loaded successfully.

E_NOINTERFACE

The object does not support the specified interface.

This function can return any of the error values returned by the IPersistStorage::Load method.

Remarks

OLE containers load objects into memory by calling this function. When calling the OleLoad function, the container application passes in a pointer to the open storage object in which the nested object is stored. Typically, the nested object to be loaded is a child storage object to the container’s root storage object. Using the OLE information stored with the object, the object handler (usually, the default handler) attempts to load the object. On completion of the OleLoad function, the object is said to be in the loaded state with its object application not running.

Some applications load all of the object’s native data. Containers often defer loading the contained objects until required to do so. For example, until an object is scrolled into view and needs to be drawn, it does not need to be loaded.

The OleLoad function performs the following steps:

1.	If necessary, performs an automatic conversion of the object (see the OleDoAutoConvert function).

2.	Gets the CLSID from the open storage object by calling the IStorage::Stat method.

3.	Calls the CoCreateInstance function to create an instance of the handler. If the handler code is not available, the default handler is used (see the OleCreateDefaultHandler function).

4.	Calls the IOleObject::SetClientSite method with the pClientSite parameter to inform the object of its client site.

5.	Calls the QueryInterface method for the IPersistStorage interface. If successful, the IPersistStorage::Load method is invoked for the object.

6.	Queries and returns the interface identified by the riid parameter.

See Also

ReadClassStg, IClassFactory::CreateInstance, IPersistStorage::Load


OleLoadFromStream

Loads an object from the stream.

WINOLEAPI OleLoadFromStream(

IStream * pStm,	//Pointer to stream from which object is to be loaded
REFIID iidInterface,	//Interface identifier
void ** ppvObj	//Indirect pointer to the newly loaded object
);
Parameters

pStm

[in] Pointer to the IStream interface on the stream from which the object is to be loaded.

iidInterface

[in] Interface identifier (IID) the caller wants to use to communicate with the object once it is loaded.

ppvObj

[out] On successful return, indirect pointer to the interface requested in iidInterface on the newly loaded object.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The object was successfully loaded.

E_NOINTERFACE

The specified interface is not supported.

This function can also return any of the error values returned by the ReadClassStm and CoCreateInstance functions, and the IPersistStorage::Load method.

Remarks

This function can be used to load an object that supports the IPersistStream interface. The CLSID of the object must immediately precede the object’s data in the stream, which is accomplished by the companion function OleSaveToStream (or the operations it wraps, which are described under that topic).

If the CLSID for the stream is CLSID_NULL, the ppvObj parameter is set to NULL.

See Also

OleSaveToStream


OleLoadPicture

Creates a new picture object and initializes it from the contents of a stream. This is equivalent to calling OleCreatePictureIndirect(NULL, ...) followed by IPersistStream::Load.

STDAPI OleLoadPicture(

IStream * pStream,	//Pointer to the stream that contains picture’s data
LONG lSize,	//Number of bytes read from the stream
BOOL fRunmode,	//The opposite of the initial value of the picture’s property
REFIID riid,	//Reference to the identifier of the interface describing the type of interface pointer to return
VOID ppvObj	//Indirect pointer to the object
);
Parameters

pStream

[in] Pointer to the stream that contains the picture’s data.

lSize

[in] Number of bytes that should be read from the stream, or zero if the entire stream should be read.

fRunmode

[in] The opposite of the initial value of the KeepOriginalFormat property. If TRUE, KeepOriginalFormat is set to FALSE and vice-versa.

riid

[in] Reference to the identifier of the interface describing the type of interface pointer to return in ppvObj.

ppvObj

[out] Indirect pointer to the interface identified by riid on the storage of the object identified by the moniker. If ppvObj is non-NULL, the implementation must call IUnknown::AddRef on the parameter; it is the caller’s responsibility to call IUnknown::Release. If an error occurs, ppvObj is set to NULL.

Return Values

This function supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The picture was created successfully.

E_POINTER

The address in pStream or ppvObj is not valid. For example, either may be NULL.

E_NOINTERFACE

The object does not support the interface specified in riid.

Remarks

The stream must be in BMP (bitmap), WMF (metafile), or ICO (icon) format. A picture object created using OleLoadPicture always has ownership of its internal resources (fOwn==TRUE is implied).

See Also

OleCreatePictureIndirect, PICTDESC


OleLockRunning

Locks an already running object into its running state or unlocks it from its running state.

WINOLEAPI OleLockRunning(

LPUNKNOWN pUnknown,	//Pointer to interface
BOOL fLock,	//Flag indicating whether object is locked
BOOL fLastUnlockCloses	//Flag indicating whether to close object
);
Parameters

pUnknown

[in] Pointer to the IUnknown interface on the object, which the function uses to query for a pointer to IRunnableObject.

fLock

[in] TRUE locks the object into its running state. FALSE unlocks the object from its running state.

fLastUnlockCloses

[in] TRUE specifies that if the connection being released is the last external lock on the object, the object should close. FALSE specifies that the object should remain open until closed by the user or another process.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The object was successfully locked or unlocked.

Remarks

The OleLockRunning function saves you the trouble of calling the IRunnableObject::LockRunning method. You can use OleLockRunning and IRunnableObject::LockRunning interchangeably. With the IUnknown pointer passed in with the pUnknown parameter, OleLockRunning queries for an IRunnableObject pointer. If successful, it calls IRunnableObject::LockRunning and returns the results of the call.

Note  The implementation of OleLockRunning in earlier versions of OLE differs from that described here.

For more information on using this function, see IRunnableObject::LockRunning.

See Also

CoLockObjectExternal, IRunnableObject::LockRunning, OleNoteObjectVisible


OleMetafilePictFromIconAndLabel

Creates a METAFILEPICT structure that contains a metafile in which the icon and label are drawn.

HGLOBAL OleMetafilePictFromIconAndLabel(

HICON hIcon,	//Handle to the icon to be drawn into the metafile
LPOLESTR lpszLabel,	//Pointer to the string to be used as the icon label
LPOLESTR lpszSourceFile,	//Pointer to the string that contains the path to the icon file
UINT iIconIndex	//Index of icon in lpszSourceFile
);
Parameters

hIcon

[in] Handle to the icon that is to be drawn into the metafile.

lpszLabel

[in] Pointer to the string to be used as the icon label.

lpszSourceFile

[in] Pointer to the string that contains the path and file name of the icon file. This string can be obtained from the user or from the registration database.

iIconIndex

[in] Index to the icon within the lpszSourceFile file.

Return Value

HGLOBAL

An hGlobal handle to a METAFILEPICT structure containing the icon and label. The metafile uses the MM_ANISOTROPIC mapping mode.

See Also

OleGetIconOfClass, OleGetIconOfFile


OleNoteObjectVisible

Increments or decrements an external reference that keeps an object in the running state.

WINOLEAPI OleNoteObjectVisible(

LPUNKNOWN pUnknown,	//Pointer to the interface on the object in question
BOOL fVisible	//Whether object is visible
);
Parameters

pUnknown

[in] Pointer to the IUnknown interface on the object that is to be locked or unlocked.

fVisible

[in] Whether the object is visible. If TRUE, OLE increments the reference count to hold the object visible and alive regardless of external or internal IUnknown::AddRef and IUnknown::Release operations, registrations, or revocation. If FALSE, OLE releases its hold (decrements the reference count) and the object can be closed.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

Indicates the object was successfully locked or unlocked.

Remarks

The OleNoteObjectVisible function calls the CoLockObjectExternal function. It is provided as a separate function to reinforce the need to lock an object when it becomes visible to the user and to release the object when it becomes invisible. This creates a strong lock on behalf of the user to ensure that the object cannot be closed by its container while it is visible.

See Also

CoLockObjectExternal


OleQueryCreateFromData

Checks whether a data object has one of the formats that would allow it to become an embedded object through a call to either the OleCreateFromData or OleCreateStaticFromData function.

WINOLEAPI OleQueryCreateFromData(

IDataObject * pSrcDataObject	//Pointer to the data transfer object to be queried
);
Parameter

pSrcDataObject

[in] Pointer to the IDataObject interface on the data transfer object to be queried.

Return Values

S_OK

Formats that support embedded-object creation are present.

S_FALSE

No formats are present that support either embedded- or static-object creation.

OLE_S_STATIC

Formats that support static-object creation are present.

Remarks

When an application retrieves a data transfer object through a call to the OleGetClipboard function, the application should call OleQueryCreateFromData as part of the process of deciding to enable or disable the Edit/Paste or Edit/Paste Special... commands. It tests for the presence of the following formats in the data object:

CF_EMBEDDEDOBJECT
CF_EMBEDSOURCE
cfFileName
CF_METAFILEPICT
CF_DIB
CF_BITMAP

Determining that the data object has one of these formats does not absolutely guarantee that the object creation will succeed, but is intended to help the process.

If OleQueryCreateFromData finds one of the CF_METAFILEPICT, CF_BITMAP, or CF_DIB formats and none of the other formats, it returns OLE_S_STATIC, indicating that you should call the OleCreateStaticFromData function to create the embedded object.

If OleQueryCreateFromData finds one of the other formats (CF_EMBEDDEDOBJECT, CF_EMBEDSOURCE, or cfFileName), even in combination with the static formats, it returns S_OK, indicating that you should call the OleCreateFromData function to create the embedded object.

See Also

OleCreateFromData, OleCreateStaticFromData, OleQueryLinkFromData


OleQueryLinkFromData

The OleQueryLinkFromData function determines whether an OLE linked object (rather than an OLE embedded object) can be created from a clipboard data object.

WINOLEAPI OleQueryLinkFromData(

IDataObject * pSrcDataObject	//Pointer to the clipboard data object to be used to create the new object
);
Parameter

pSrcDataObject

[in] Pointer to the IDataObject interface on the clipboard data object from which the object is to be created.

Return Value

Returns S_OK if the OleCreateLinkFromData function can be used to create the linked object; otherwise S_FALSE.

Remarks

The OleQueryLinkFromData function is similar to the OleQueryCreateFromData function, but determines whether an OLE linked object (rather than an OLE embedded object) can be created from the clipboard data object. If the return value is S_OK, the application can then attempt to create the object with a call to OleCreateLinkFromData. A successful return from OleQueryLinkFromData does not, however, guarantee the successful creation of a link.


OleRegGetUserType

Gets the user type of the specified class from the registry. Developers of custom DLL object applications use this function to emulate the behavior of the OLE default handler.

WINOLEAPI OleRegGetUserType(

REFCLSID clsid,	//Class identifier
DWORD dwFormOfType,	//Specifies form of type name
LPOLESTR * pszUserType	//Pointer to storage of string pointer
);
Parameters

clsid

[in] Class identifier for which user type is requested.

dwFormOfType

[in] Value that describes the form of the user-presentable string from the enumeration USERCLASSTYPE.

pszUserType

[out] Pointer to a string that stores the user type on return.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The user type was returned successfully.

REGDB_E_CLASSNOTREG

There is no CLSID registered for the class object.

REGDB_E_READREGDB

There was an error reading the registry.

OLE_E_REGDB_KEY

The ProgID = MainUserTypeName and CLSID = MainUserTypeName keys are missing from the registry.

Remarks

Object applications can ask OLE to get the user type name of a specified class in one of two ways. One way is to call OleRegGetUserType. The other is to return OLE_S_USEREG in response to calls by the default object handler to IOleObject::GetUserType. OLE_S_USEREG instructs the default handler to call OleRegGetUserType. Because DLL object applications cannot return OLE_S_USEREG, they must call OleRegGetUserType, rather than delegating the job to the object handler.

The OleRegGetUserType function and its sibling functions, OleRegGetMiscStatus, OleRegEnumFormatEtc, and OleRegEnumVerbs, provide a way for developers of custom DLL object applications to emulate the behavior of OLE’s default object handler in getting information about objects from the registry. By using these functions, you avoid the considerable work of writing your own, and the pitfalls inherent in working directly in the registry. In addition, you get future enhancements and optimizations of these functions without having to code them yourself.

See Also

IOleObject::GetUserType, OleRegGetMiscStatus, OleRegEnumFormatEtc, OleRegEnumVerbs, USERCLASSTYPE


OleRegGetMiscStatus

Gets miscellaneous information about the presentation and behaviors supported by the specified CLSID from the registry. Used by developers of custom DLL object applications to emulate the behavior of the OLE default handler.

WINOLEAPI OleRegGetMiscStatus(

REFCLSID clsid,	//Class identifier
DWORD dwAspect,	//Value specifying aspect of requested class
DWORD * pdwStatus	//Pointer to returned status information
);
Parameters

clsid

[in] CLSID of the class for which status information is requested.

dwAspect

[in] DWORD specifying the presentation aspect of the class for which information is requested. Values are taken from the DVASPECT enumeration.

pdwStatus

[out] Pointer to the location of the status information on the function’s return.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The status information was returned successfully.

REGDB_E_CLASSNOTREG

No CLSID is registered for the class object.

REGDB_E_READREGDB

An error occurred reading the registry.

OLE_E_REGDB_KEY

The GetMiscStatus key is missing from the registry.

Remarks

Object applications can ask OLE to get miscellaneous status information in one of two ways. One way is to call OleRegGetMiscStatus. The other is to return OLE_S_USEREG in response to calls by the default object handler to IOleObject::GetMiscStatus. OLE_S_USEREG instructs the default handler to call OleRegGetMiscStatus. Because DLL object applications cannot return OLE_S_USEREG, they must call OleRegGetMiscStatus rather than delegating the job to the object handler.

OleRegGetMiscStatus and its sibling functions, OleRegGetUserType, OleRegEnumFormatEtc, and OleRegEnumVerbs, provide a way for developers of custom DLL object applications to emulate the behavior of OLE’s default object handler in getting information about objects from the registry. By using these functions, you avoid the considerable work of writing your own, and the pitfalls inherent in working directly in the registry. In addition, you get future enhancements and optimizations of these functions without having to code them yourself.

See Also

DVASPECT, FORMATETC, OLEMISC, IOleObject::GetMiscStatus, OleRegEnumFormatEtc, OleRegEnumVerbs, OleRegGetUserType


OleRegEnumFormatEtc

Supplies a pointer to an enumeration object that can be used to enumerate data formats that an OLE object server has registered in the system registry. An object application or object handler calls this function when it must enumerate those formats. Developers of custom DLL object applications use this function to emulate the behavior of the default object handler.

WINOLEAPI OleRegEnumFormatEtc(

REFCLSID clsid,	//Class identifier
DWORD dwDirection,	//Value specifying data formats
LPENUMFORMATETC * ppenumFormatetc	//Indirect pointer to returned format information
);
Parameters

clsid

[in] CLSID of the class whose formats are being requested.

dwDirection

[in] Whether to enumerate formats that can be passed to IDataObject::GetData or formats that can be passed to IDataObject::SetData. Valid values are taken from the enumeration DATADIR.

ppenumFormatetc

[out] Indirect pointer to the IEnumFORMATETC interface on the new enumeration object.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The enumerator was returned successfully.

REGDB_E_CLASSNOTREG

There is no CLSID registered for the class object.

REGDB_E_READREGDB

There was an error reading the registry.

OLE_E_REGDB_KEY

The DataFormats/GetSet key is missing from the registry.

Remarks

Object applications can ask OLE to create an enumeration object for FORMATETC structures to enumerate supported data formats in one of two ways. One way is to call OleRegEnumFormatEtc. The other is to return OLE_S_USEREG in response to calls by the default object handler to IDataObject::EnumFormatEtc. OLE_S_USEREG instructs the default handler to call OleRegEnumFormatEtc. Because DLL object applications cannot return OLE_S_USEREG, they must call OleRegEnumFormatEtc rather than delegating the job to the object handler. With the supplied IEnumFORMATETC pointer to the object, you can call the standard enumeration object methods to do the enumeration.

The OleRegEnumFormatEtc function and its sibling functions, OleRegGetUserType, OleRegGetMiscStatus, and OleRegEnumVerbs, provide a way for developers of custom DLL object applications to emulate the behavior of OLE’s default object handler in getting information about objects from the registry. By using these functions, you avoid the considerable work of writing your own, and the pitfalls inherent in working directly in the registry. In addition, you get future enhancements and optimizations of these functions without having to code them yourself.

See Also

IDataObject::EnumFormatEtc, IEnumFORMATETC


OleRegEnumVerbs

Supplies an enumeration of the registered verbs for the specified class. Developers of custom DLL object applications use this function to emulate the behavior of the default object handler.

WINOLEAPI OleRegEnumVerbs(

REFCLSID clsid,	//Class identifier
LPENUMOLEVERB * ppenumOleVerb	//Indirect pointer to returned enumerator
);
Parameters

clsid

[in] Class identifier whose verbs are being requested.

ppenumOleVerb

[out] On successful return, indirect pointer to an IEnumOLEVERB interface on the new enumeration object.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The enumerator was created successfully.

OLEOBJ_E_NOVERBS

No verbs are registered for the class.

REGDB_E_CLASSNOTREG

No CLSID is registered for the class object.

REGDB_E_READREGDB

An error occurred reading the registry.

OLE_E_REGDB_KEY

The DataFormats/GetSet key is missing from the registry.

Remarks

Object applications can ask OLE to create an enumeration object for OLEVERB structures to enumerate supported verbs in one of two ways. One way is to call OleRegEnumVerbs. The other way is to return OLE_S_USEREG in response to calls by the default object handler to IOleObject::EnumVerbs. OLE_S_USEREG instructs the default handler to call OleRegEnumVerbs. Because DLL object applications cannot return OLE_S_USEREG, they must call OleRegEnumVerbs rather than delegating the job to the object handler. With the supplied IEnumOLEVERB pointer to the object, you can call the standard enumeration object methods to do the enumeration.

The OleRegEnumVerbs function and its sibling functions, OleRegGetUserType, OleRegGetMiscStatus, and OleRegEnumFormatEtc, provide a way for developers of custom DLL object applications to emulate the behavior of OLE’s default object handler in getting information about objects from the registry. By using these functions, you avoid the considerable work of writing your own, and the pitfalls inherent in working directly in the registry. In addition, you get future enhancements and optimizations of these functions without having to code them yourself.

See Also

IOleObject::EnumVerbs, IEnumOLEVERB


OleRun

Puts an OLE compound document object into the running state.

WINOLEAPI OleRun(

LPUNKNOWN pUnknown	//Pointer to interface on the object
);
Parameter

pUnknown

[in] Pointer to the IUnknown interface on the object, with which it will query for a pointer to the IRunnableObject interface, and then call its Run method.

Return Values

This function supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The object was successfully placed in the running state.

OLE_E_CLASSDIFF

The source of an OLE link has been converted to a different class.

Remarks

The OleRun function puts an object in the running state. The implementation of OleRun was changed in OLE 2.01 to coincide with the publication of the IRunnableObject interface. You can use OleRun and IRunnableObject::Run interchangeably. OleRun queries the object for a pointer to IRunnableObject. If successful, the function returns the results of calling the IRunnableObject::Run method.

Note  The implementation of OleRun in earlier versions of OLE differs from that described here.

For more information on using this function, see IRunnableObject::Run.

See Also

IOleLink::BindToSource, IRunnableObject::Run


OleSave

Saves an object opened in transacted mode into the specified storage object.

WINOLEAPI OleSave(

IPersistStorage * pPS,	//Pointer to the object to be saved
IStorage * pStg,	//Pointer to the destination storage to which pPS is saved
BOOL fSameAsLoad	//Whether the object was loaded from pstg or not
);
Parameters

pPS

[in] Pointer to the IPersistStorage interface on the object to be saved.

pStg

[in] Pointer to the IStorage interface on the destination storage object to which the object indicated in pPS is to be saved.

fSameAsLoad

[in] TRUE indicates that pStg is the same storage object from which the object was loaded or created; FALSE indicates that pstg was loaded or created from a different storage object.

Return Values

S_OK

The object was successfully saved.

STG_E_MEDIUMFULL

The object could not be saved due to lack of disk space.

This function can also return any of the error values returned by the IPersistStorage::Save method.

Remarks

The OleSave helper function handles the common situation in which an object is open in transacted mode and is then to be saved into the specified storage object which uses the OLE-provided compound file implementation. Transacted mode means that changes to the object are buffered until either of the IStorage methods Commit or Revert is called. Callers can handle other situations by calling the IPersistStorage and IStorage interfaces directly.

OleSave does the following:

1.	Calls the IPersistStorage::GetClassID method to get the CLSID of the object.

2.	Writes the CLSID to the storage object using the WriteClassStg function.

3.	Calls the IPersistStorage::Save method to save the object.

4.	If there were no errors on the save; calls the IStorage::Commit method to commit the changes.

Note  Static objects are saved into a stream called CONTENTS. Static metafile objects get saved in “placeable metafile format” and static DIB data gets saved in “DIB file format.” These formats are defined to be the OLE standards for metafile and DIB. All data transferred using an IStream interface or a file (that is, via IDataObject::GetDataHere) must be in these formats. Also, all objects whose default file format is a metafile or DIB must write their data into a CONTENTS stream using these standard formats.

See Also

IStorage, IPersistStorage


OleSaveToStream

Saves an object with the IPersistStream interface on it to the specified stream.

WINOLEAPI OleSaveToStream(

IPersistStream * pPStm,	//Pointer to the interface on the object to be saved
IStream * pStm	//Pointer to the destination stream to which the object is saved
);
Parameters

pPStm

[in] Pointer to the IPersistStream interface on the object to be saved to the stream. Can be NULL, which has the effect of writing CLSID_NULL to the stream.

pStm

[in] Pointer to the IStream interface on the stream in which the object is to be saved.

Return Values

S_OK

The object was successfully saved.

STG_E_MEDIUMFULL

There is no space left on device to save the object.

This function can also return any of the error values returned by the WriteClassStm function or the IPersistStream::Save method.

Remarks

This function simplifies saving an object that implements the IPersistStream interface to a stream. In this stream, the object’s CLSID precedes its data. When the stream is retrieved, the CLSID permits the proper code to be associated with the data. The OleSaveToStream function does the following:

1.	Calls the IPersistStream::GetClassID method to get the object’s CLSID.

2.	Writes the CLSID to the stream with the WriteClassStm function.

3.	Calls the IPersistStream::Save method with fClearDirty set to TRUE, which clears the dirty bit in the object.

The companion helper, OleLoadFromStream, loads objects saved in this way.

See Also

OleLoadFromStream, IPersistStream, IStream


OleSetAutoConvert

Specifies a CLSID for automatic conversion to a different class when an object of that class is loaded.

WINOLEAPI OleSetAutoConvert(

REFCLSID clsidOld,	//CLSID to be converted
REFCLSID clsidNew	//New CLSID after conversion
);
Parameters

clsidOld

[in] CLSID of the object class to be converted.

clsidNew

[in] CLSID of the object class that should replace clsidOld. This new CLSID replaces any existing auto-conversion information in the registry for clsidOld. If this value is CLSID_NULL, any existing auto-conversion information for clsidOld is removed from the registry.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The object was tagged successfully.

REGDB_E_CLASSNOTREG

The CLSID is not properly registered in the registry.

REGDB_E_READREGDB

Error reading from the registry.

REGDB_E_WRITEREGDB

Error writing to the registry.

REGDB_E_KEYMISSING

Cannot read a key from the registry.

Remarks

The OleSetAutoConvert function goes to the system registry, finds the AutoConvertTo subkey under the CLSID specified by clsidOld, and sets it to clsidNew. This function does not validate whether an appropriate registry entry for clsidNew currently exists. These entries appear in the registry as subkeys of the CLSID key:

CLSID\{clsid}=MainUserTypeName\AutoConvertTo = clsid

Object conversion means that the object’s data is permanently associated with a new CLSID. Automatic conversion is typically specified in the setup program of a new version of an object application, so objects created by its older versions can be automatically updated to the new version.

For example, it may be necessary to convert spreadsheets that were created with earlier versions of a spreadsheet application to the new version. The spreadsheet objects from earlier versions have different CLSIDs than the new version. For each earlier version that you want automatically updated, you would call OleSetAutoConvert in the setup program, specifying the CLSID of the old version, and that of the new one. Then, whenever a user loads an object from a previous version, it would be automatically updated. To support automatic conversion of obects, a server that supports conversion must be prepared to manually convert objects that have the format of an earlier version of the server. Automatic conversion relies internally on this manual-conversion support.

Before setting the desired AutoConvertTo value, setup programs should also call OleSetAutoConvert to remove any existing conversion for the new class, by specifying the new class as the clsidOld parameter, and setting the clsidNew parameter to CLSID_NULL.

See Also

OleDoAutoConvert


OleSetClipboard

Places a pointer to a specific data object onto the clipboard. This makes the data object accessible to the OleGetClipboard function.

WINOLEAPI OleSetClipboard(

IDataObject * pDataObj	//Pointer to the data object being copied or cut
);
Parameter

pDataObj

[in] Pointer to the IDataObject interface on the data object from which the data to be placed on the clipboard can be obtained. This parameter can be NULL; in which case the clipboard is emptied.

Return Values

S_OK

The IDataObject pointer was placed on the clipboard.

CLIPBRD_E_CANT_OPEN

The Windows OpenClipboard function used within OleSetClipboard failed.

CLIPBRD_E_CANT_EMPTY

The Windows EmptyClipboard function used within OleSetClipboard failed.

CLIPBRD_E_CANT_CLOSE

The Windows CloseClipboard function used within OleSetClipboard failed.

Remarks

If you are writing an application that can act as the source of a clipboard operation, you must do the following:

1.	Create a data object (on which is the IDataObject interface) for the data being copied or cut to the clipboard. This object should be the same object used in OLE drag-and-drop operations.

2.	Call OleSetClipboard to place the IDataObject pointer onto the clipboard, so it is accessible to the OleGetClipboard function. OleSetClipboard also calls the IUnknown::AddRef method on your data object.

3.	If you wish, release the data object once you have placed it on the clipboard to free the IUnknown::AddRef counter in your application.

4.	If the user is cutting data (deleting it from the document and putting it on to the clipboard), remove the data from the document.

All formats are offered on the clipboard using delayed rendering (the clipboard contains only a pointer to the data object unless a call to OleFlushClipboard renders the data onto the clipboard). The formats necessary for OLE 1 compatibility are synthesized from the OLE 2 formats that are present and are also put on the clipboard.

The OleSetClipboard function assigns ownership of the clipboard to an internal OLE window handle. The reference count of the data object is increased by 1, to enable delayed rendering. The reference count is decreased by a call to the OleFlushClipboard function or by a subsequent call to OleSetClipboard specifying NULL as the parameter value (which clears the clipboard).

When an application opens the clipboard (either directly or indirectly by calling the Win32 OpenClipboard function), the clipboard cannot be used by any other application until it is closed. If the clipboard is currently open by another application, OleSetClipboard fails. The internal OLE window handle satisfies WM_RENDERFORMAT messages by delegating them to the IDataObject implementation on the data object that is on the clipboard.

Specifying NULL as the parameter value for OleSetClipboard empties the current clipboard. If the contents of the clipboard are the result of a previous OleSetClipboard call and the clipboard has been released, the IDataObject pointer that was passed to the previous call is released. The clipboard owner should use this as a signal that the data it previously offered is no longer on the clipboard.

If you need to leave the data on the clipboard after your application is closed, you should call OleFlushClipboard instead of OleSetClipboard.

See Also

OleFlushClipboard, OleGetClipboard, OleIsCurrentClipboard


OleSetContainedObject

Notifies an object that it is embedded in an OLE container, which ensures that reference counting is done correctly for containers that support links to embedded objects.

WINOLEAPI OleSetContainedObject(

LPUNKNOWN pUnk,	//Pointer to the interface on the embedded object
BOOL fContained	//Indicates if the object is embedded
);
Parameters

pUnk

[in] Pointer to the IUnknown interface of the object.

fContained

[in] TRUE if the object is an embedded object; FALSE otherwise.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The object was notified successfully.

Remarks

The OleSetContainedObject function notifies an object that it is embedded in an OLE container. The implementation of OleSetContainedObject was changed in OLE 2.01 to coincide with the publication of the IRunnableObject interface. You can use OleSetContainedObject and the IRunnableObject::SetContainedObject method interchangeably. The OleSetContainedObject function queries the object for a pointer to the IRunnableObject interface. If successful, the function returns the results of calling IRunnableObject::SetContainedObject.

Note  The implementation of OleSetContainedObject in earlier versions of OLE differs from that described here.

See Also

IRunnableObject::SetContainedObject


OleSetMenuDescriptor

Installs or removes OLE dispatching code from the container’s frame window.

WINOLEAPI OleSetMenuDescriptor(

HOLEMENU holemenu,	//Handle to the composite menu descriptor
HWND hwndFrame,	//Handle to the container’s frame window
HWND hwndActiveObject,	//Handle to the object’s in-place activation window
LPOLEINPLACEFRAME lpFrame,	//Pointer to the container’s frame window
LPOLEINPLACEACTIVEOBJECT lpActiveObj	//Active in-place object
);
Parameters

holemenu

[in] Handle to the composite menu descriptor returned by the OleCreateMenuDescriptor function. If NULL, the dispatching code is unhooked.

hwndFrame

[in] Handle to the container’s frame window where the in-place composite menu is to be installed.

hwndActiveObject

[in] Handle to the object’s in-place activation window. OLE dispatches menu messages and commands to this window.

lpFrame

[in] Pointer to the IOleInPlaceFrame interface on the container’s frame window.

lpActiveObj

[in] Pointer to the IOleInPlaceActiveObject interface on the active in-place object.

Return Values

This function supports the standard return values E_FAIL, E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The menu was installed correctly.

Remarks

The container should call OleSetMenuDescriptor to install the dispatching code on hwndFrame when the object calls the IOleInPlaceFrame::SetMenu method, or to remove the dispatching code by passing NULL as the value for holemenu to OleSetMenuDescriptor.

If both the lpFrame and lpActiveObj parameters are non-NULL, OLE installs the context-sensitive help F1 message filter for the application. Otherwise, the application must supply its own message filter.

See Also

OleCreateMenuDescriptor, IOleInPlaceFrame::SetMenu, IOleInPlaceActiveObject


OleTranslateAccelerator

Called by the object application, allows an object’s container to translate accelerators according to the container’s accelerator table.

WINOLEAPI OleTranslateAccelerator(

LPOLEINPLACEFRAME lpFrame,	//Pointer to send keystrokes
LPOLEINPLACEFRAMEINFO lpFrameInfo,	//Pointer to accelerator table obtained from container
LPMSG lpmsg	//Pointer to structure containing the keystroke
);
Parameters

lpFrame

[in] Pointer to the IOleInPlaceFrame interface to which the keystroke might be sent.

lpFrameInfo

[in] Pointer to an OLEINPLACEFRAMEINFO structure containing the accelerator table obtained from the container.

lpmsg

[in] Pointer to an MSG structure containing the keystroke.

Return Values

This function supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The keystroke was processed.

S_FALSE

The object should continue processing this message.

Remarks

Object servers call OleTranslateAccelerator to allow the object’s container to translate accelerator keystrokes according to the container’s accelerator table, pointed to by lpFrameInfo. While a contained object is the active object, the object’s server always has first chance at translating any messages received. If this is not desired, the server calls OleTranslateAccelerator to give the object’s container a chance. If the keyboard input matches an accelerator found in the container-provided accelerator table, OleTranslateAccelerator passes the message and its command identifier on to the container through the IOleInPlaceFrame::TranslateAccelerator method. This method returns S_OK if the keystroke is consumed; otherwise it returns S_FALSE.

The OleTranslateAccelerator function is intended to be called only by local server applications and not by in-process servers. For objects managed by local servers, keyboard input goes directly to the server’s message pump. If the object does not translate the key, OleTranslateAccelerator gives the container application an opportunity to do it. For objects managed by in-process servers, the keyboard input goes directly to the container’s message pump.

Note  Accelerator tables for containers should be defined so they will work properly with object applications that do their own accelerator keystroke translations. These tables should take the form:

"char", wID, VIRTKEY, CONTROL

This is the most common way to describe keyboard accelerators. Failure to do so can result in keystrokes being lost or sent to the wrong object during an in-place session.

Objects can call the IsAccelerator function to see whether the accelerator keystroke belongs to the object or the container.

See Also

IsAccelerator, IOleInPlaceFrame::TranslateAccelerator


OleTranslateColor

Converts an OLE_COLOR type to a COLORREF.

STDAPI OleTranslateColor (

OLE_COLOR clr,	//Color to be converted into a COLORREF
HPALETTE hpal,	//Palette used for conversion
COLORREF *pcolorref	//Pointer to the caller’s variable that receives the converted result
);
Parameters

clr

[in] The OLE color to be converted into a COLORREF.

hpal

[in] Palette used as a basis for the conversion.

pcolorref

[out] Pointer to the caller’s variable that receives the converted COLORREF result. This can be NULL, indicating that the caller wants only to verify that a converted color exists.

Return Values

This function supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The color was translated successfully.

Remarks

The following table describes the color conversion:

OLE_COLOR	hPal	Resulting COLORREF
invalid		Undefined (E_INVALIDARG)
0x800000xx, xx is not a valid Win32 GetSysColor index		Undefined (E_INVALIDARG)
	invalid	Undefined (E_INVALIDARG)
0x0100iiii, iiii is not a valid palette index	valid palette	Undefined (E_INVALIDARG)
0x800000xx, xx is a valid GetSysColor index	NULL	0x00bbggrr
0x0100iiii, iiii is a valid palette index	NULL	0x0100iiii
0x02bbggrr (palette relative)	NULL	0x02bbggrr
0x00bbggrr	NULL	0x00bbggrr
0x800000xx, xx is a valid GetSysColor index	valid palette	0x00bbggrr
0x0100iiii, iiii is a valid palette index in hPal	valid palette	0x0100iiii
0x02bbggrr (palette relative)	valid palette	0x02bbggrr
0x00bbggrr	valid palette	0x02bbggrr


OleUIAddVerbMenu

Adds the Verb menu for the specified object to the given menu.

BOOL OleUIAddVerbMenu(

LPOLEOBJECT *lpOleObj,	//Pointer to the object
LPCTSTR lpszShortType,	//Pointer to the short name corresponding to the object
HMENU hMenu,	//Handle to the menu to modify
UINT uPos,	//Position of the menu item.
UINT uIDVerbMin,	//Value at which to start the verbs
UINT uIDVerbMax,	//Maximum identifier value for object verbs
BOOL bAddConvert,	//Whether to add convert item
UINT idConvert,	//Value to use for the convert item
HMENU FAR * lphMenu	//Pointer to the cascading verb menu, if created
);
Parameters

lpOleObj

[in] Pointer to the IOleObject interface on the selected object. If this is NULL, then a default disabled menu item is created.

lpszShortType

[in] Pointer to the short name defined in the registry (AuxName==2) for the object identified with lpOleObj. If the string is NOT known, then NULL may be passed. If NULL is passed, IOleObject::GetUserType is called to retrieve it. If the caller has easy access to the string, it is faster to pass it in.

hMenu

[in] Handle to the menu in which to make modifications.

uPos

[in] Position of the menu item.

iIDVerbMin

[in] The UINT identifier value at which to start the verbs.

uIDVerbMax

[in] The UINT Maximum identifier value to be used for object verbs. If uIDVerbMax is 0, then no maximum identifier value is used.

bAddConvert

[in] The BOOL specifying whether or not to add a Convert item to the bottom of the menu (preceded by a separator).

idConvert

[in] The UINT identifier value to use for the Convert menu item, if bAddConvert is TRUE.

lphMenu

[out] An HMENU pointer to the cascading verb menu if it's created. If there is only one verb, this will be filled with NULL.

Return Values

TRUE

Indicates lpOleObj was valid and at least one verb was added to the menu.

FALSE

Indicates lpOleObj was NULL and a disabled default menu item was created.

Remarks

If the object has one verb, the verb is added directly to the given menu. If the object has multiple verbs, a cascading sub-menu is created.


OleUIBusy

Invokes the standard Busy dialog box, allowing the user to manage concurrency.

UINT OleUIBusy(

LPOLEUIBUSY  lpBZ	//Pointer to the initialization structure
);
Parameter

lpBZ

[in] Pointer to an OLEUIBUSY structure that contains information used to initialize the dialog box.

Return Values

Standard Success/Error Definitions

OLEUI_FALSE

Unknown failure (unused).

OLEUI_SUCCESS

No error, same as OLEUI_OK.

OLEUI_OK

The user pressed the OK button.

OLEUI_CANCEL

The user has pressed the Cancel button and that the caller should cancel the operation.

OLEUI_BZ_SWITCHTOSELECTED

The user has pressed Switch To and OleUIBusy was unable to determine how to switch to the blocking application. In this case, the caller should either take measures to attempt to resolve the conflict itself, if possible, or retry the operation. OleUIBusy will only return OLEUI_BZ_SWITCHTOSELECTED if the user has pressed the Switch To button, hTask is NULL and the BZ_NOTRESPONDING flag is set.

OLEUI_BZ_RETRYSELECTED

The user has either pressed the Retry button or attempted to resolve the conflict (probably by switching to the blocking application). In this case, the caller should retry the operation.

OLEUI_BZ_CALLUNBLOCKED

The dialog box has been informed that the operation is no longer blocked.

Standard Field Validation Errors

OLEUI_ERR_STANDARDMIN

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_ERR_STRUCTURENULL

The pointer to an OLEUIXXX structure passed into the function was NULL.

OLEUI_ERR_STRUCTUREINVALID

Insufficient permissions for read or write access to an OLEUIXXX structure.

OLEUI_ERR_CBSTRUCTINCORRECT

The cbstruct value is incorrect.

OLEUI_ERR_HWNDOWNERINVALID

The hWndOwner value is invalid.

OLEUI_ERR_LPSZCAPTIONINVALID

The lpszCaption value is invalid.

OLEUI_ERR_LPFNHOOKINVALID

The lpfnHook value is invalid.

OLEUI_ERR_HINSTANCEINVALID

The hInstance value is invalid.

OLEUI_ERR_LPSZTEMPLATEINVALID

The lpszTemplate value is invalid.

OLEUI_ERR_HRESOURCEINVALID

The hResource value is invalid.

Initialization Errors

OLEUI_ERR_FINDTEMPLATEFAILURE

Unable to find the dialog box template.

OLEUI_ERR_LOADTEMPLATEFAILURE

Unable to load the dialog box template.

OLEUI_ERR_DIALOGFAILURE

Dialog box initialization failed.

OLEUI_ERR_LOCALMEMALLOC

A call to LocalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_GLOBALMEMALLOC

A call to GlobalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_LOADSTRING

Unable to LoadString localized resources from the library.

OLEUI_ERR_OLEMEMALLOC

A call to the standard IMalloc allocator failed.

Function Specific Errors

OLEUI_ERR_STANDARDMAX

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_BZERR_HTASKINVALID

The hTask specified in the hTask member of the OLEUIBUSY structure is invalid.

Remarks

The standard OLE Server Busy dialog box notifies the user that the server application is not receiving messages. The dialog box then asks the user to cancel the operation, switch to the task that is blocked, or continue waiting.

See Also

OLEUIBUSY


OleUICanConvertOrActivateAs

Determines if there are any OLE object classes in the registry that can be used to convert or activate the specified CLSID from.

BOOL OleUICanConvertOrActivateAs(

REFCLSID rClsid,	//CLSID of the specified class
BOOL fIsLinkedObject,	//Whether the original object was a linked object
WORD wFormat	//Format of the original class
);
Parameters

rClsid

[in] The CLSID of the class for which the information is required.

fIsLinkedObject

[in] TRUE if the original object is a linked object; FALSE otherwise.

wFormat

[in] Format of the original class.

Return Values

TRUE

The specified class can be converted to or activated as another class.

FALSE

The specified class cannot be converted to or activated as another class.

Remarks

OleUICanConvertOrActivateAs searches the registry for classes that include wFormat in their \Conversion\Readable\Main, \Conversion\ReadWriteable\Main, and \DataFormats\DefaultFile entries.

This function is useful for determining if a Convert... menu item should be disabled. If the CF_DISABLEDISPLAYASICON flag is specified in the call to OleUIConvert, then the Convert... menu item should be enabled only if OleUICanConvertOrActivateAs returns TRUE.

See Also

OleUIConvert


OleUIChangeIcon

Invokes the standard Change Icon dialog box, which allows the user to select an icon from an icon file, executable, or DLL.

UINT OleUIChangeIcon(

LPOLEUICHANGEICON lpCI	//Pointer to the in-out structure for this dialog box
);
Parameter

lpCI

[in] Pointer to the in-out OLEUICHANGEICON structure for this dialog box.

Return Values

Standard Success/Error Definitions

OLEUI_FALSE

Unknown failure (unused).

OLEUI_SUCCESS

No error, same as OLEUI_OK.

OLEUI_OK

The user pressed the OK button.

OLEUI_CANCEL

The user pressed the Cancel button.

Standard Field Validation Errors

OLEUI_ERR_STANDARDMIN

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_ERR_STRUCTURENULL

The pointer to an OLEUIXXX structure passed into the function was NULL.

OLEUI_ERR_STRUCTUREINVALID

Insufficient permissions for read or write access to an OLEUIXXX structure.

OLEUI_ERR_CBSTRUCTINCORRECT

The cbstruct value is incorrect.

OLEUI_ERR_HWNDOWNERINVALID

The hWndOwner value is invalid.

OLEUI_ERR_LPSZCAPTIONINVALID

The lpszCaption value is invalid.

OLEUI_ERR_LPFNHOOKINVALID

The lpfnHook value is invalid.

OLEUI_ERR_HINSTANCEINVALID

The hInstance value is invalid.

OLEUI_ERR_LPSZTEMPLATEINVALID

The lpszTemplate value is invalid.

OLEUI_ERR_HRESOURCEINVALID

The hResource value is invalid.

Initialization Errors

OLEUI_ERR_FINDTEMPLATEFAILURE

Unable to find the dialog box template.

OLEUI_ERR_LOADTEMPLATEFAILURE

Unable to load the dialog box template.

OLEUI_ERR_DIALOGFAILURE

Dialog box initialization failed.

OLEUI_ERR_LOCALMEMALLOC

A call to LocalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_GLOBALMEMALLOC

A call to GlobalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_LOADSTRING

Unable to LoadString localized resources from the library.

OLEUI_ERR_OLEMEMALLOC

A call to the standard IMalloc allocator failed.

Function Specific Errors

OLEUI_ERR_STANDARDMAX

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_CIERR_MUSTHAVECLSID

The clsid member was not the current CLSID.

OLEUI_CIERR_MUSTHAVECURRENTMETAFILE

The hMetaPict member was not the current metafile.

OLEUI_CIERR_SZICONEXEINVALID

The szIconExe value was invalid.

Remarks

OleUIChangeIcon uses information contained in the OLEUICHANGEICON structure.

See Also

OLEUICHANGEICON


OleUIChangeSource

Invokes the Change Source dialog box, allowing the user to change the source of a link.

UINT OleUIChangeSource(

LPOLEUICHANGESOURCE lpCS	//Pointer to the in-out structure
);
Parameter

lpCS

[in] Pointer to the in-out OLEUICHANGESOURCE structure for this dialog box.

Return Values

Standard Success/Error Definitions

OLEUI_FALSE

Unknown failure (unused).

OLEUI_SUCCESS

No error, same as OLEUI_OK.

OLEUI_OK

The user pressed the OK button.

OLEUI_CANCEL

The user pressed the Cancel button.

Standard Field Validation Errors

OLEUI_ERR_STANDARDMIN

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_ERR_STRUCTURENULL

The pointer to an OLEUIXXX structure passed into the function was NULL.

OLEUI_ERR_STRUCTUREINVALID

Insufficient permissions for read or write access to an OLEUIXXX structure.

OLEUI_ERR_CBSTRUCTINCORRECT

The cbstruct value is incorrect.

OLEUI_ERR_HWNDOWNERINVALID

The hWndOwner value is invalid.

OLEUI_ERR_LPSZCAPTIONINVALID

The lpszCaption value is invalid.

OLEUI_ERR_LPFNHOOKINVALID

The lpfnHook value is invalid.

OLEUI_ERR_HINSTANCEINVALID

The hInstance value is invalid.

OLEUI_ERR_LPSZTEMPLATEINVALID

The lpszTemplate value is invalid.

OLEUI_ERR_HRESOURCEINVALID

The hResource value is invalid.

Initialization Errors

OLEUI_ERR_FINDTEMPLATEFAILURE

Unable to find the dialog box template.

OLEUI_ERR_LOADTEMPLATEFAILURE

Unable to load the dialog box template.

OLEUI_ERR_DIALOGFAILURE

Dialog box initialization failed.

OLEUI_ERR_LOCALMEMALLOC

A call to LocalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_GLOBALMEMALLOC

A call to GlobalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_LOADSTRING

Unable to LoadString localized resources from the library.

OLEUI_ERR_OLEMEMALLOC

A call to the standard IMalloc allocator failed.

Function Specific Errors

OLEUI_ERR_STANDARDMAX

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_CSERR_LINKCNTRNULL

The lpOleUILinkContainer value is NULL.

OLEUI_CSERR_LINKCNTRINVALID

The lpOleUILinkContainer value is invalid.

OLEUI_CSERR_FROMNOTNULL

The lpszFrom value is not NULL.

OLEUI_CSERR_TONOTNULL

The lpszTo value is not NULL.

OLEUI_CSERR_SOURCEINVALID

The lpszDisplayName or nFileLength value is invalid, or cannot retrieve the link source.

OLEUI_CSERR_SOURCEPARSEERROR

The nFilename value is wrong.

Remarks

The link source is not changed by the Change Source dialog box itself. Instead, it is up to the caller to change the link source using the returned file and item strings. The Edit Links dialog box typically does this for the caller.

See Also

OLEUICHANGESOURCE, OleUIEditLinks, IOleUILinkContainer


OleUIConvert

Invokes the standard Convert dialog box, allowing the user to change the type of a single specified object, or the type of all OLE objects of the specified object’s class.

UINT OleUIConvert(

LPOLEUICONVERT lpCV	//Pointer to initialization structure
);
Parameter

lpCV

[in] Pointer to an OLEUICONVERT structure that contains information used to initialize the dialog box.

Return Values

Standard Success/Error Definitions

OLEUI_FALSE

Unknown failure (unused).

OLEUI_SUCCESS

No error, same as OLEUI_OK.

OLEUI_OK

The user pressed the OK button.

OLEUI_CANCEL

The user pressed the Cancel button.

Standard Field Validation Errors

OLEUI_ERR_STANDARDMIN

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_ERR_STRUCTURENULL

The pointer to an OLEUIXXX structure passed into the function was NULL.

OLEUI_ERR_STRUCTUREINVALID

Insufficient permissions for read or write access to an OLEUIXXX structure.

OLEUI_ERR_CBSTRUCTINCORRECT

The cbstruct value is incorrect.

OLEUI_ERR_HWNDOWNERINVALID

The hWndOwner value is invalid.

OLEUI_ERR_LPSZCAPTIONINVALID

The lpszCaption value is invalid.

OLEUI_ERR_LPFNHOOKINVALID

The lpfnHook value is invalid.

OLEUI_ERR_HINSTANCEINVALID

The hInstance value is invalid.

OLEUI_ERR_LPSZTEMPLATEINVALID

The lpszTemplate value is invalid.

OLEUI_ERR_HRESOURCEINVALID

The hResource value is invalid.

Initialization Errors

OLEUI_ERR_FINDTEMPLATEFAILURE

Unable to find the dialog box template.

OLEUI_ERR_LOADTEMPLATEFAILURE

Unable to load the dialog box template.

OLEUI_ERR_DIALOGFAILURE

Dialog box initialization failed.

OLEUI_ERR_LOCALMEMALLOC

A call to LocalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_GLOBALMEMALLOC

A call to GlobalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_LOADSTRING

Unable to LoadString localized resources from the library.

OLEUI_ERR_OLEMEMALLOC

A call to the standard IMalloc allocator failed.

Function Specific Errors

OLEUI_ERR_STANDARDMAX

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_CTERR_CLASSIDINVALID

A clsid value was invalid.

OLEUI_CTERR_DVASPECTINVALID

The dvAspect value was invalid. This member specifies the aspect of the object.

OLEUI_CTERR_CBFORMATINVALID

The wFormat value was invalid. This member specifies the data format of the object.

OLEUI_CTERR_STRINGINVALID

A string value (for example, lpszUserType or lpszDefLabel) was invalid.

Remarks

OleUIConvert populates the Convert dialog box’s list box with object classes by traversing the Registry and looking for entries in the Readable and ReadWritable keys. Every class that includes the original class' default file format in its Readable key is added to the Convert list, and every class that includes the original class' default file format in its ReadWritable key is added to the Activate As list. The Convert list is shown in the dialog box's list box when the Convert radio button is selected (the default selection), and the Activate As list is shown when Activate As is selected.

Note that you can change the type of all objects of a given class only when CF_CONVERTONLY is not specified.

The convert command, which invokes this function, should only be made available to the user if OleUIConvertOrActivateAs returns S_OK.

See Also

OLEUICONVERT, OleUICanConvertOrActivateAs


OleUIEditLinks

Invokes the standard Links dialog box, allowing the user to make modifications to a container's linked objects.

UINT OleUIEditLinks(

LPOLEUIEDITLINKS lpEL	//Pointer to the initialization structure
);
Parameter

lpEL

[in] Pointer to an OLEUIEDITLINKS structure that contains information used to initialize the dialog box.

Return Values

Standard Success/Error Definitions

OLEUI_FALSE

Unknown failure (unused).

OLEUI_SUCCESS

No error, same as OLEUI_OK.

OLEUI_OK

The user pressed the OK button.

OLEUI_CANCEL

The user pressed the Cancel button.

Standard Field Validation Errors

OLEUI_ERR_STANDARDMIN

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_ERR_STRUCTURENULL

The pointer to an OLEUIXXX structure passed into the function was NULL.

OLEUI_ERR_STRUCTUREINVALID

Insufficient permissions for read or write access to an OLEUIXXX structure.

OLEUI_ERR_CBSTRUCTINCORRECT

The cbstruct value is incorrect.

OLEUI_ERR_HWNDOWNERINVALID

The hWndOwner value is invalid.

OLEUI_ERR_LPSZCAPTIONINVALID

The lpszCaption value is invalid.

OLEUI_ERR_LPFNHOOKINVALID

The lpfnHook value is invalid.

OLEUI_ERR_HINSTANCEINVALID

The hInstance value is invalid.

OLEUI_ERR_LPSZTEMPLATEINVALID

The lpszTemplate value is invalid.

OLEUI_ERR_HRESOURCEINVALID

The hResource value is invalid.

Initialization Errors

OLEUI_ERR_FINDTEMPLATEFAILURE

Unable to find the dialog box template.

OLEUI_ERR_LOADTEMPLATEFAILURE

Unable to load the dialog box template.

OLEUI_ERR_DIALOGFAILURE

Dialog box initialization failed.

OLEUI_ERR_LOCALMEMALLOC

A call to LocalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_GLOBALMEMALLOC

A call to GlobalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_LOADSTRING

Unable to LoadString localized resources from the library.

OLEUI_ERR_OLEMEMALLOC

A call to the standard IMalloc allocator failed.

Function Specific Errors

OLEUI_ERR_STANDARDMAX

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

See Also

OLEUIEDITLINKS, IOleUILinkContainer


OleUIInsertObject

Invokes the standard Insert Object dialog box, which allows the user to select an object source and class name, as well as the option of displaying the object as itself or as an icon.

UINT OleUIInsertObject(

LPOLEUIINSERTOBJECT lpIO	//Pointer to the in-out structure
);
Parameter

lpIO

[in] Pointer to the in-out OLEUIINSERTOBJECT structure for this dialog box.

Return Values

Standard Success/Error Definitions

OLEUI_FALSE

Unknown failure (unused).

OLEUI_SUCCESS

No error, same as OLEUI_OK.

OLEUI_OK

The user pressed the OK button.

OLEUI_CANCEL

The user pressed the Cancel button.

Standard Field Validation Errors

OLEUI_ERR_STANDARDMIN

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_ERR_STRUCTURENULL

The pointer to an OLEUIXXX structure passed into the function was NULL.

OLEUI_ERR_STRUCTUREINVALID

Insufficient permissions for read or write access to an OLEUIXXX structure.

OLEUI_ERR_CBSTRUCTINCORRECT

The cbstruct value is incorrect.

OLEUI_ERR_HWNDOWNERINVALID

The hWndOwner value is invalid.

OLEUI_ERR_LPSZCAPTIONINVALID

The lpszCaption value is invalid.

OLEUI_ERR_LPFNHOOKINVALID

The lpfnHook value is invalid.

OLEUI_ERR_HINSTANCEINVALID

The hInstance value is invalid.

OLEUI_ERR_LPSZTEMPLATEINVALID

The lpszTemplate value is invalid.

OLEUI_ERR_HRESOURCEINVALID

The hResource value is invalid.

Initialization Errors

OLEUI_ERR_FINDTEMPLATEFAILURE

Unable to find the dialog box template.

OLEUI_ERR_LOADTEMPLATEFAILURE

Unable to load the dialog box template.

OLEUI_ERR_DIALOGFAILURE

Dialog box initialization failed.

OLEUI_ERR_LOCALMEMALLOC

A call to LocalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_GLOBALMEMALLOC

A call to GlobalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_LOADSTRING

Unable to LoadString localized resources from the library.

OLEUI_ERR_OLEMEMALLOC

A call to the standard IMalloc allocator failed.

Function Specific Errors

OLEUI_ERR_STANDARDMAX

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_IOERR_LPSZFILEINVALID

The lpszFile value is invalid or user has insufficient write access permissions.. This lpszFile member points to the name of the file linked to or inserted.

OLEUI_IOERR_LPFORMATETCINVALID

The lpFormatEtc value is invalid. This member identifies the desired format.

OLEUI_IOERR_PPVOBJINVALID

The ppvOjb value is invalid. This member points to the location where the pointer for the object is returned.

OLEUI_IOERR_LPIOLECLIENTSITEINVALID

The lpIOleClientSite value is invalid. This member points to the client site for the object.

OLEUI_IOERR_LPISTORAGEINVALID

The lpIStorage value is invalid. This member points to the storage to be used for the object.

OLEUI_IOERR_SCODEHASERROR

The sc member of lpIO has additional error information.

OLEUI_IOERR_LPCLSIDEXCLUDEINVALID

The lpClsidExclude value is invalid. This member contains the list of CLSIDs to exclude.

OLEUI_IOERR_CCHFILEINVALID

The cchFile or lpszFile value is invalid. The cchFile member specifies the size of the lpszFile buffer. The lpszFile  member points to the name of the file linked to or inserted.

Remarks

OleUIInsertObject allows the user to select the type of object to be inserted from a list box containing the object applications registered on the user's system. To populate that list box, OleUIInsertObject traverses the registry, adding every object server it finds that meets the following criteria:

•	The registry entry does not include the NotInsertable key.

•	The registry entry includes an OLE 1.0 style Protocol\\StdFileEditing\\Server key.

•	The registry entry includes the Insertable key.

•	The object's CLSID is not included in the list of objects to exclude (the lpClsidExclude member of OLEUIINSERTOBJECT).

By default, OleUIInsertObject does not validate object servers, however, if the IOF_VERIFYSERVEREXIST flag is included in the dwFlags member of the OLEUIINSERTOBJECT structure, OleUIInsertObject verifies that the server exists. If it does not exist, then the server's object is not added to the list of available objects. Server validation is a time-extensive operation and is a significant performance factor.

To free an HMETAFILEPICT returned from the Insert Object or Paste Special dialog box, delete the attached metafile on the handle, as follows:

void FreeHmetafilepict(HMETAFILEPICT hmfp)

{

    if (hmfp != NULL)

        {

        LPMETAFILEPICT pmfp = GlobalLock(hmfp);

        DeleteMetaFile(pmfp->hMF);

        GlobalUnlock(hmfp);

        GlobalFree(hmfp);

        }

}  // FreeHmetafilepict

See Also

OLEUIINSERTOBJECT, OpenFile, DeleteMetaFile, GlobalUnlock, GlobalFree in Win32


OleUIObjectProperties

Invokes the Object Properties dialog box, which displays General, View, and Link information about an object.

UINT OleUIObjectProperties(

LPOLEUIOBJECTPROPS lpOP	//Pointer to the structure
);
Parameter

lpOP

[in] Pointer to the OLEUIOBJECTPROPS structure.

Return Values

Standard Success/Error Definitions

OLEUI_FALSE

Unknown failure (unused).

OLEUI_SUCCESS

No error, same as OLEUI_OK.

OLEUI_OK

The user pressed the OK button.

OLEUI_CANCEL

The user pressed the Cancel button.

Standard Field Validation Errors

OLEUI_ERR_STANDARDMIN

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_ERR_STRUCTURENULL

The pointer to an OLEUIXXX structure passed into the function was NULL.

OLEUI_ERR_STRUCTUREINVALID

Insufficient permissions for read or write access to an OLEUIXXX structure.

OLEUI_ERR_CBSTRUCTINCORRECT

The cbstruct value is incorrect.

OLEUI_ERR_HWNDOWNERINVALID

The hWndOwner value is invalid.

OLEUI_ERR_LPSZCAPTIONINVALID

The lpszCaption value is invalid.

OLEUI_ERR_LPFNHOOKINVALID

The lpfnHook value is invalid.

OLEUI_ERR_HINSTANCEINVALID

The hInstance value is invalid.

OLEUI_ERR_LPSZTEMPLATEINVALID

The lpszTemplate value is invalid.

OLEUI_ERR_HRESOURCEINVALID

The hResource value is invalid.

Initialization Errors

OLEUI_ERR_FINDTEMPLATEFAILURE

Unable to find the dialog box template.

OLEUI_ERR_LOADTEMPLATEFAILURE

Unable to load the dialog box template.

OLEUI_ERR_DIALOGFAILURE

Dialog box initialization failed.

OLEUI_ERR_LOCALMEMALLOC

A call to LocalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_GLOBALMEMALLOC

A call to GlobalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_LOADSTRING

Unable to LoadString localized resources from the library.

OLEUI_ERR_OLEMEMALLOC

A call to the standard IMalloc allocator failed.

Function Specific Errors

OLEUI_ERR_STANDARDMAX

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_OPERR_SUBPROPNULL

lpGP or lpVP is NULL, or dwFlags and OPF_OBJECTISLINK and lpLP are NULL.

OLEUI_OPERR_SUBPROPINVALID

Insufficient write-access permissions for the structures pointed to by lpGP, lpVP, or lpLP.

OLEUI_OPERR_PROPSHEETNULL

The lpLP value is NULL.

OLEUI_OPERR_PROPSHEETINVALID

Insufficient write access for one or more of the structures used by OLEUIOBJECTPROPS.

OLEUI_OPERR_SUPPROP

The sub-link property pointer, lpLP, is NULL.

OLEUI_OPERR_PROPSINVALID

Insufficient write access for the sub-link property pointer, lpLP.

OLEUI_OPERR_PAGESINCORRECT

Some sub-link properties of the lpPS member are incorrect.

OLEUI_OPERR_INVALIDPAGES

Some sub-link properties of the lpPS member are incorrect.

OLEUI_OPERR_NOTSUPPORTED

A sub-link property of the lpPS member is incorrect.

OLEUI_OPERR_DLGPROCNOTNULL

A sub-link property of the lpPS member is incorrect.

OLEUI_OPERR_LPARAMNOTZERO

A sub-link property of the lpPS member is incorrect.

OLEUI_GPERR_STRINGINVALID

A string value (for example, lplpszLabel or lplpszType) is invalid.

OLEUI_GPERR_CLASSIDINVALID

The clsid value is invalid.

OLEUI_GPERR_LPCLSIDEXCLUDEINVALID

The ClsidExcluded value is invalid.

OLEUI_GPERR_CBFORMATINVALID

The wFormat value is invalid.

OLEUI_VPERR_METAPICTINVALID

The hMetaPict value is invalid.

OLEUI_VPERR_DVASPECTINVALID

The dvAspect value is invalid.

OLEUI_OPERR_PROPERTYSHEET

The lpPS value is incorrect.

OLEUI_OPERR_OBJINFOINVALID

The lpObjInfo value is NULL or the calling process doesn’t have read access.

OLEUI_OPERR_LINKINFOINVALID

The lpLinkInfo value is NULL or the calling process doesn’t have read access.

Remarks

OleUIObjectProperties is passed an OLEUIOBJECTPROPS structure, which supplies the information needed to fill in the General, View, and Link tabs of the Object Properties dialog box.

See Also

IOleUIObjInfo, IOleUILinkInfo, OLEUIOBJECTPROPS, OLEUIGNRLPROPS, OLEUIVIEWPROPS, OLEUILINKPROPS


OleUIPasteSpecial

Invokes the standard Paste Special dialog box, allowing the user to select the format of the clipboard object to be pasted or paste-linked.

UINT OleUIPasteSpecial(*

LPOLEUIPASTESPECIAL lpPS	//Pointer to the in-out structure for this dialog box
);
Parameter

lpPS

[in] Pointer to the in-out OLEUIPASTESPECIAL structure for this dialog box.

Return Values

Standard Success/Error Definitions

OLEUI_FALSE

Unknown failure (unused).

OLEUI_SUCCESS

No error, same as OLEUI_OK.

OLEUI_OK

The user pressed the OK button.

OLEUI_CANCEL

The user pressed the Cancel button.

Standard Field Validation Errors

OLEUI_ERR_STANDARDMIN

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_ERR_STRUCTURENULL

The pointer to an OLEUIXXX structure passed into the function was NULL.

OLEUI_ERR_STRUCTUREINVALID

Insufficient permissions for read or write access to an OLEUIXXX structure.

OLEUI_ERR_CBSTRUCTINCORRECT

The cbstruct value is incorrect.

OLEUI_ERR_HWNDOWNERINVALID

The hWndOwner value is invalid.

OLEUI_ERR_LPSZCAPTIONINVALID

The lpszCaption value is invalid.

OLEUI_ERR_LPFNHOOKINVALID

The lpfnHook value is invalid.

OLEUI_ERR_HINSTANCEINVALID

The hInstance value is invalid.

OLEUI_ERR_LPSZTEMPLATEINVALID

The lpszTemplate value is invalid.

OLEUI_ERR_HRESOURCEINVALID

The hResource value is invalid.

Initialization Errors

OLEUI_ERR_FINDTEMPLATEFAILURE

Unable to find the dialog box template.

OLEUI_ERR_LOADTEMPLATEFAILURE

Unable to load the dialog box template.

OLEUI_ERR_DIALOGFAILURE

Dialog box initialization failed.

OLEUI_ERR_LOCALMEMALLOC

A call to LocalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_GLOBALMEMALLOC

A call to GlobalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_LOADSTRING

Unable to LoadString localized resources from the library.

OLEUI_ERR_OLEMEMALLOC

A call to the standard IMalloc allocator failed.

Function Specific Errors

OLEUI_ERR_STANDARDMAX

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_IOERR_SRCDATAOBJECTINVALID

The lpSrcDataObject field of OLEUIPASTESPECIAL is invalid.

OLEUI_IOERR_ARRPASTEENTRIESINVALID

The arrPasteEntries field of OLEUIPASTESPECIAL is invalid.

OLEUI_IOERR_ARRLINKTYPESINVALID

The arrLinkTypes field of OLEUIPASTESPECIAL is invalid.

OLEUI_PSERR_CLIPBOARDCHANGED

The clipboard contents changed while the dialog box was displayed.

OLEUI_PSERR_GETCLIPBOAARDFAILED

The lpSrcDataObj member is incorrect.

Remarks

The design of the Paste Special dialog box assumes that if you are willing to permit a user to link to an object, you are also willing to permit the user to embed that object. For this reason, if any of the OLEUIPASTE_LINKTYPE flags associated with the OLEUIPASTEFLAG enumeration are set, then the OLEUIPASTE_PASTE flag must also be set in order for the data formats to appear in the Paste Special dialog box.

The text displayed in the Source field of the standard Paste Special dialog box, which is implemented in OLEDLG32.DLL, is the null-terminated string whose offset in bytes is specified in the dwSrcofCopy field of the OBJECTDESCRIPTOR structure for the object to be pasted. If an OBJECTDESCRIPTOR structure is not available for this object, the dialog box displays whatever text may be associated with CF_LINKSOURCEDESCRIPTOR. If neither structure is available, the dialog box looks for CF_FILENAME. If CF_FILENAME is not found, the dialog box displays the string “Unknown Source”.

To free an HMETAFILEPICT returned from the Insert Object or Paste Special dialog box, delete the attached metafile on the handle, as follows:

void FreeHmetafilepict(HMETAFILEPICT hmfp)

{

    if (hmfp != NULL)

        {

        LPMETAFILEPICT pmfp = GlobalLock(hmfp);

        DeleteMetaFile(pmfp->hMF);

        GlobalUnlock(hmfp);

        GlobalFree(hmfp);

        }

}  // FreeHmetafilepict

See Also

OLEUIPASTEFLAG, DeleteMetaFile, GlobalUnlock, GlobalFree in Win32


OleUIPromptUser

Displays a dialog box with the specified template and returns the response (button identifier) from the user. This function is used to display OLE warning messages, for example, Class Not Registered.

int OleUIPromtUser(

int nTemplate,	//Resource number of dialog box
HWND hwndParent	//Handle to the parent window of the dialog box
);
Parameters

nTemplate

[in] Resource number of the dialog box to display. See Remarks.

hwndParent

[in] Handle to the parent window of the dialog box. Specifies zero or more optional arguments. These parameters are passed to wsprintf to format the message string.

Return Values

Returns the button identifier selected by the user (template dependent).

Standard Success/Error Definitions

OLEUI_FALSE

Unknown failure (unused).

OLEUI_SUCCESS

No error, same as OLEUI_OK.

OLEUI_OK

The user pressed the OK button.

OLEUI_CANCEL

The user pressed the Cancel button.

Standard Field Validation Errors

OLEUI_ERR_STANDARDMIN

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

OLEUI_ERR_STRUCTURENULL

The pointer to an OLEUIXXX structure passed into the function was NULL.

OLEUI_ERR_STRUCTUREINVALID

Insufficient permissions for read or write access to an OLEUIXXX structure.

OLEUI_ERR_CBSTRUCTINCORRECT

The cbstruct value is incorrect.

OLEUI_ERR_HWNDOWNERINVALID

The hWndOwner value is invalid.

OLEUI_ERR_LPSZCAPTIONINVALID

The lpszCaption value is invalid.

OLEUI_ERR_LPFNHOOKINVALID

The lpfnHook value is invalid.

OLEUI_ERR_HINSTANCEINVALID

The hInstance value is invalid.

OLEUI_ERR_LPSZTEMPLATEINVALID

The lpszTemplate value is invalid.

OLEUI_ERR_HRESOURCEINVALID

The hResource value is invalid.

Initialization Errors

OLEUI_ERR_FINDTEMPLATEFAILURE

Unable to find the dialog box template.

OLEUI_ERR_LOADTEMPLATEFAILURE

Unable to load the dialog box template.

OLEUI_ERR_DIALOGFAILURE

Dialog box initialization failed.

OLEUI_ERR_LOCALMEMALLOC

A call to LocalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_GLOBALMEMALLOC

A call to GlobalAlloc or the standard IMalloc allocator failed.

OLEUI_ERR_LOADSTRING

Unable to LoadString localized resources from the library.

OLEUI_ERR_OLEMEMALLOC

A call to the standard IMalloc allocator failed.

Function Specific Errors

OLEUI_ERR_STANDARDMAX

Errors common to all dialog boxes lie in the range OLEUI_ERR_STANDARDMIN to OLEUI_ERR_STANDARDMAX. This value allows the application to test for standard messages in order to display error messages to the user.

Remarks

The following dialog box templates are defined in Windows Interface Guidelines--A Guide for Designing Software. The nTemplate parameter must be a currently defined resource, however, additional templates can be added to prompt.dlg.

IDD_LINKSOURCEUNAVAILABLE

IDD_CANNOTUPDATELINK

IDD_SERVERNOTREG

IDD_CANNOTRESPONDVERB

IDD_SERVERNOTFOUND

IDD_UPDATELINKS

See Also

wsprintf in Win32


OleUIUpdateLinks

Updates all links in the link container and displays a dialog box that shows the progress of the updating process. The process is stopped if the user presses the Stop button or when all links are processed.

BOOL OleUIUpdateLink(

LPOLEUILINKCONTAINER lpOleUILinkCntr,	//Pointer to the link container
HWND hwndParent,	//Dialog box’s parent window
LPTSTR lpszTitle,	//pointer to the dialog box title
int cLinks	//Number of links
);
Parameters

lpOleUILinkCntr

[in] Pointer to the IOleUILinkContainer interface on the link container.

hwndParent

[in] Parent window of the dialog box.

lpszTitle

[in] Pointer to the title of the dialog box.

cLinks

[in] Total number of links.

Return Values

TRUE

The links were successfully updated.

FALSE

Unable to update the links.

See Also

IOleUILinkContainer::GetLinkUpdateOptions, IOleUILinkContainer::UpdateLink


OleUninitialize

Closes the OLE library, freeing any resources that it maintains.

void OleUninitialize();

Remarks

Call this function on application shutdown, as the last OLE library call. OleUninitialize calls the CoUninitialize function internally to shut down the OLE Component Object(COM) Library.

The OleInitialize and OleUninitialize calls must be balanced — if there are multiple calls to the OleInitialize function, there must be the same number of calls to OleUninitialize: Only the OleUninitialize call corresponding to the OleInitialize call that actually initialized the library can close it.

See Also

OleInitialize, CoUninitialize


ProgIDFromCLSID

Retrieves the ProgID for a given CLSID.

WINOLEAPI ProgIDFromCLSID(

REFCLSID clsid,	//CLSID for which the ProgID is requested
LPOLESTR * lplpszProgID	//Indirect pointer to the requested ProgID on return
);
Parameters

clsid

[in] Specifies the CLSID for which the ProgID is requested.

lplpszProgID

[out] Indirect pointer to the requested ProgID.

Return Values

S_OK

The ProgID was returned successfully.

REGDB_E_CLASSNOTREG

Class not registered in the registry.

REGDB_E_READREGDB

Error reading registry.

Remarks

Every OLE object class listed in the Insert Object dialog box must have a programmatic identifier (ProgID), a string that uniquely identifies a given class, stored in the registry. In addition to determining the eligibility for the Insert Object dialog box, the ProgID can be used as an identifier in a macro programming language to identify a class. Finally, the ProgID is also the class name used for an object of an OLE class that is placed in an OLE 1 container.

The ProgIDFromCLSID function uses entries in the registry to do the conversion. OLE application authors are responsible for ensuring that the registry is configured correctly in the application’s setup program.

The ProgID string must be different than the class name of any OLE 1 application, including the OLE 1 version of the same application, if there is one. In addition, a ProgID string must not contain more than 39 characters, start with a digit, or, except for a single period, contain any punctuation (including underscores).

The ProgID must never be shown to the user in the user interface. If you need a short displayable string for an object, call IOleObject::GetUserType.

Call the CLSIDFromProgID function to find the CLSID associated with a given ProgID. CLSIDs can be freed with the task allocator (refer to the CoGetMalloc function).

See Also

CLSIDFromProgID


PropagateResult

#define PropagateResult(hrPrevious, scBase) ((HRESULT) scBase)

PropagateResult is a NO-OP.

This macro is obsolete and should not be used.


PropVariantClear

Frees all elements that can be freed in a given PROPVARIANT structure.

HRESULT PropVariantClear(

PROPVARIANT* pvarg	//Pointer to a PROPVARIANT structure
);
Parameters

pvarg

[in] Pointer to an initialized PROPVARIANT structure for which any deallocatable elements are to be freed. On return, all zeroes are written to the PROPVARIANT.

Return Values

S_OK

The VT types are recognized and all items that can be freed have been freed.

STG_E_INVALID_PARAMETER

The variant has an unknown VT type.

Remarks

At any level of indirection, a NULL pointer is ignored. For example, in a VT_CF PROPVARIANT, the pvargpclipdatapClipData could be NULL. In this case, the pvargpclipdatapClipData  pointer would be ignored, but the pvargpclipdata pointer would be freed.

On return, this function writes zeroes to the specified PROPVARIANT, so the VT-type is VT_EMPTY.

Passing NULL as the pvarg parameter produces a return code of S_OK.

See Also

FreePropVariantArray


PropVariantCopy

Copies the contents of a PROPVARIANT structure to another.

HRESULT PropVariantCopy(

PROPVARIANT * pDest	//Pointer to uninitialized PROPVARIANT that is filled on return
PROPVARIANT *pvarg	//PROPVARIANT to be copied
);
Parameters

pDest

[in, out] Pointer to an uninitialized PROPVARIANT structure that receives the copy.

pvarg

[in] Pointer to the PROPVARIANT to be copied.

Return Values

S_OK

The copy was successfully completed.

STG_E_INVALID_PARAMETER

The variant has an unknown type.

Remarks

Copies a PROPVARIANT by value so the original pvarg and new pDest may be freed independently with calls to PropVariantClear. For non-simple PROPVARIANT types such as VT_STREAM, VT_STORAGE, etc, which require a subobject, the copy is made by reference. The pointer is copied and AddRef is called on it. It is illegal to pass NULL for either pDest or pvarg.

See Also

PROPVARIANT, PropVariantClear


ReadClassStg

Reads the CLSID previously written to a storage object with the WriteClassStg.

WINOLEAPI ReadClassStg(

IStorage * pStg,	//Pointer to the storage object containing the CLSID
CLSID * pclsid	//Pointer to return the CLSID
);
Parameters

pStg

[in] Pointer to the IStorage interface on the storage object containing the CLSID to be retrieved.

pclsid

[out] Pointer to where the CLSID is written. May return CLSID_NULL.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The CLSID was returned successfully.

This function also returns any of the error values returned by the IStorage::Stat method.

Remarks

This function is simply a helper function that calls the IStorage::Stat method and retrieves the CLSID previously written to the storage object with a call to WriteClassStg from the STATSTG structure.

See Also

OleLoad, WriteClassStg, IStorage::Stat, STATSTG structure.


ReadClassStm

Reads the CLSID previously written to a stream object with the WriteClassStm method.

WINOLEAPI ReadClassStm(

IStream * pStm,	//Pointer to the stream holding the CLSID
CLSID * pclsid	//Pointer to where the CLSID is to be written
);
Parameters

pStm

[in] Pointer to the IStream interface on the stream object containing the CLSID to be read. This CLSID must have been previously written to the stream object using WriteClassStm.

pclsid

[out] Pointer to where the CLSID is to be written.

Return Values

S_OK

The CLSID was successfully retrieved.

STG_E_READFAULT

End of file was reached.

This function also returns any of the error values returned by the IStream::Read method.

Remarks

Most applications do not call the ReadClassStm method directly. OLE calls it before making a call to an object’s IPersistStream::Load implementation.

See Also

WriteClassStm, ReadClassStg, WriteClassStg


ReadFmtUserTypeStg

Returns the clipboard format and user type previously saved with the WriteFmtUserTypeStg function.

WINOLEAPI ReadFmtUserTypeStg(

IStorage * pStg,	//Pointer to storage object holding the values
CLIPFORMAT * pcf,	//Pointer to return the clipboard format
LPWSTR * lplpszUserType	//Indirect pointer to return the user type string
);
Parameters

pStg

[in] Pointer to the IStorage interface on the storage object from which the information is to be read.

pcf

[out] Pointer to where the clipboard format is to be written on return. It can be NULL, indicating the format is of no interest to the caller.

lplpszUserType

[out] Indirect pointer to where the user type string is to be returned. It can be NULL, indicating that the user type is of no interest to the caller. This method allocates memory for the string. The caller is responsible for freeing the memory with CoTaskMemFree.

Return Values

This function supports the standard return values E_FAIL, E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

The requested information was read successfully.

This function also returns any of the error values returned by the IStream::Read method.

Remarks

This function returns the clipboard format and the user type string from the specified storage object. The WriteClassStg function must have been called before calling the ReadFmtUserTypeStg function.

See Also

CoTaskMemFree, WriteFmtUserTypeStg


RegisterDragDrop

Registers the specified window as one that can be the target of an OLE drag-and-drop operation and specifies the IDropTarget instance to use for drop operations.

WINOLEAPI RegisterDragDrop(

HWND hwnd,	//Handle to a window that can accept drops
IDropTarget * pDropTarget	//Pointer to object that is to be target of drop
);
Parameters

hwnd

[in] Handle to a window that can be a target for an OLE drag-and-drop operation.

pDropTarget

[in] Pointer to the IDropTarget interface on the object that is to be the target of a drag-and-drop operation in a specified window. This interface is used to communicate OLE drag-and-drop information for that window.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The application was registered successfully.

DRAGDROP_E_INVALIDHWND

Invalid handle returned in the hwnd parameter.

DRAGDROP_E_ALREADYREGISTERED

The specified window has already been registered as a drop target.

Remarks

If your application can accept dropped objects during OLE drag-and-drop operations, you must call the RegisterDragDrop function. Do this whenever one of your application windows is available as a potential drop target, i.e., when the window appears unobscured on the screen.

The RegisterDragDrop function only registers one window at a time, so you must call it for each application window capable of accepting dropped objects.

As the mouse passes over unobscured portions of the target window during an OLE drag-and-drop operation, the DoDragDrop function calls the specified IDropTarget::DragOver method for the current window. When a drop operation actually occurs in a given window, the DoDragDrop function calls IDropTarget::Drop.

The RegisterDragDrop function also calls the IUnknown::AddRef method on the IDropTarget pointer.

See Also

RevokeDragDrop


ReleaseStgMedium

Frees the specified storage medium.

void ReleaseStgMedium(

STGMEDIUM * pmedium	//Pointer to storage medium to be freed
);
Parameter

pmedium

[in] Pointer to the storage medium that is to be freed.

Return Value

None.

Remarks

The ReleaseStgMedium function calls the appropriate method or function to release the specified storage medium. Use this function during data transfer operations where storage medium structures are parameters, such as IDataObject::GetData or IDataObject::SetData. In addition to identifying the type of the storage medium, this structure specifies the appropriate IUnknown::Release method for releasing the storage medium when it is no longer needed.

It is common to pass a STGMEDIUM from one body of code to another, such as in IDataObject::GetData, in which the one called can allocate a medium and return it to the caller. ReleaseStgMedium permits flexibility in whether the receiving body of code owns the medium, or whether the original provider of the medium still owns it, in which case the receiving code needs to inform the provider that it can free the medium.

When the original provider of the medium is responsible for freeing the medium, the provider calls ReleaseStgMedium, specifying the medium and the appropriate IUnknown pointer as the punkForRelease structure member. Depending on the type of storage medium being freed, one of the following actions is taken, followed by a call to the Release method on the specified IUnknown pointer:

Medium	ReleaseStgMedium Action
TYMED_HGLOBAL	None.
TYMED_GDI	None.
TYMED_ENHMF	None.
TYMED_MFPICT	None.
TYMED_FILE	Frees the file name string using standard memory management mechanisms.
TYMED_ISTREAM	Calls IStream::Release.
TYMED_ISTORAGE	Calls IStorage::Release.
The provider indicates that the receiver of the medium is responsible for freeing the medium by specifying NULL for the punkForRelease structure member. Then the receiver calls ReleaseStgMedium, which makes a call as described in the following table depending on the type of storage medium being freed:

Medium	ReleaseStgMedium Action
TYMED_HGLOBAL	Calls the Win32 GlobalFree function on the handle.
TYMED_GDI	Calls the Win32 DeleteObject function on the handle.
TYMED_ENHMF	Deletes the enhanced metafile.
TYMED_MFPICT	The hMF that it contains is deleted with the Win32 DeleteMetaFile function; then the handle itself is passed to GlobalFree.
TYMED_FILE	Frees the disk file by deleting it. Frees the file name string by using the standard memory management paradigm.
TYMED_ISTREAM	Calls IStream::Release.
TYMED_ISTORAGE	Calls IStorage::Release.
In either case, after the call to ReleaseStgMedium, the specified storage medium is invalid and can no longer be used.

See Also

STGMEDIUM structure


ResultFromScode

#define ResultFromScode(sc) ((HRESULT) (sc))

Converts an SCODE into an HRESULT.

This macro is obsolete and should not be used.


RevokeDragDrop

Revokes the registration of the specified application window as a potential target for OLE drag-and-drop operations.

WINOLEAPI RevokeDragDrop(

HWND hwnd	//Handle to a window that can accept drops
);
Parameter

hwnd

[in] Handle to a window previously registered as a target for an OLE drag-and-drop operation.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

Registration as a target window was revoked successfully.

DRAGDROP_E_INVALIDHWND

Invalid handle returned in the hwnd parameter.

DRAGDROP_E_NOTREGISTERED

An attempt was made to revoke a drop target that has not been registered.

Remarks

When your application window is no longer available as a potential target for an OLE drag-and-drop operation, you must call RevokeDragDrop.

This function calls the IUnknown::Release method for your drop target interface.

See Also

RegisterDragDrop


SCODE_CODE

#define SCODE_CODE(sc) ((sc) & 0xFFFF)

Extracts the code part of the SCODE.


SCODE_FACILITY

#define SCODE_FACILITY(sc) (((sc) >> 16) & 0x1fff)

Extracts the facility from the SCODE.


SCODE_SEVERITY

#define SCODE_SEVERITY(sc) (((sc) >> 31) & 0x1)

Extracts the severity field from the SCODE.


SetConvertStg

Sets the convert bit in a storage object to indicate that the object is to be converted to a new class when it is opened. The setting can be retrieved with a call to the GetConvertStg function.

WINOLEAPI SetConvertStg(

IStorage * pStg,	//Points to storage object where the conversion bit is to be set
BOOL fConvert	//Indicates whether an object is to be converted
);
Parameters

pStg

IStorage pointer to the storage object in which to set the conversion bit.

fConvert

If TRUE, sets the conversion bit for the object to indicate the object is to be converted when opened. If FALSE, clears the conversion bit.

Return Values

S_OK

Indicates the object’s conversion bit was set successfully.

STG_E_ACCESSDENIED

Access denied because the caller has insufficient permission, or another caller has the file open and locked.

STG_E_LOCKVIOLATION

Access denied because another caller has the file open and locked.

E_OUTOFMEMORY

Indicates the conversion bit was not set due to a lack of memory.

E_INVALIDARG

Indicates one or more arguments are invalid.

E_UNEXPECTED

Indicates an unexpected error occurred.

See the IStorage::CreateStream, IStorage::OpenStream, IStream::Read, and IStream::Write methods for possible storage and stream access errors.

Remarks

The SetConvertStg function determines the status of the convert bit in a contained object. It is called by both the container application and the server in the process of converting an object from one class to another. When a user specifies through a Convert To dialogue (which the container produces with a call to the OleUIConvert function) that an object is to be converted, the container must take the following steps:

1.	Unload the object if it is currently loaded.

2.	Call WriteClassStg to write the new CLSID to the object storage.

3.	Call WriteFmtUserTypeStg to write the new user type name and the existing main format to the storage.

4.	Call SetConvertStg with the fConvert parameter set to TRUE to indicate that the object has been tagged for conversion to a new class the next time it is loaded.

5.	Just before the object is loaded, call OleDoAutoConvert to handle any needed object conversion, unless you call OleLoad, which calls it internally.

When an object is initialized from a storage object and the server is the destination of a Convert To operation, the object server should do the following:

1.	Call the GetConvertStg function to retrieve the value of the conversion bit.

2.	If the bit is set, the server reads the data out of the object according to the format associated with the new CLSID.

3.	When the object is asked to save itself, the object should call WriteFmtUserType() using the normal native format and user type of the object.

4.	The object should then call SetConvertStg with the fConvert parameter set to FALSE to reset the object’s conversion bit.

See Also

GetConvertStg


StgCreateDocfile

Creates a new compound file storage object using the OLE-provided compound file implementation for the IStorage interface.

WINOLEAPI StgCreateDocfile(

const WCHAR * pwcsName,	//Points to pathname of compound file to create
DWORD grfMode,	//Specifies the access mode for opening the storage object
DWORD reserved,	//Reserved; must be zero
IStorage ** ppstgOpen	//Points to location for returning the new storage object
);
Parameters

pwcsName

[in] Points to the pathname of the compound file to create. It is passed uninterpreted to the file system. This can be a relative name or NULL. If NULL, a temporary compound file is allocated with a unique name.

grfMode

[in] Specifies the access mode to use when opening the new storage object. For more information, see the STGM enumeration. If the caller specifies transacted mode together with STGM_CREATE or STGM_CONVERT, the overwrite or conversion takes place at the time the storage object is opened and therefore is not revertible.

reserved

[in] Reserved for future use; must be zero.

ppstgOpen

[out] Points to the location of the IStorage pointer to the new storage object.

Return Values

S_OK

Indicates the compound file was successfully created.

STG_E_ACCESSDENIED

Access denied because the caller has insufficient permission, or another caller has the file open and locked.

STG_E_LOCKVIOLATION

Access denied because another caller has the file open and locked.

STG_E_FILEALREADYEXISTS

Indicates the compound file already exists and grfMode is set to STGM_FAILIFTHERE.

STG_S_CONVERTED

Indicates the specified file was successfully converted to Storage format.

STG_E_INSUFFICIENTMEMORY

Indicates the compound file was not created due to a lack of memory.

STG_E_INVALIDNAME

Indicates bad name in the pwcsName parameter.

STG_E_INVALIDPOINTER

Indicates bad pointer in the pwcsName parameter or the ppStgOpen parameter.

STG_E_INVALIDFLAG

Indicates bad flag combination in the grfMode pointer.

STG_E_TOOMANYOPENFILES

Indicates the compound file was not created due to a lack of file handles.

See also any file system errors for other error return values.

Remarks

The StgCreateDocfile function creates a new storage object using the OLE-provided, compound-file implementation for the IStorage interface. The name of the open compound file can be retrieved by calling the IStorage::Stat method.

StgCreateDocfile creates the file if it does not exist. If it does exist, the use of the STGM_CREATE, STGM_CONVERT, and STGM_FAILIFTHERE flags in the grfMode parameter indicate how to proceed. See the STGM enumeration for more information on these values.

If the compound file is opened in transacted mode (the grfMode parameter specifies STGM_TRANSACTED) and a file with this name already exists, the existing file is not altered until all outstanding changes are committed. If the calling process lacks write access to the existing file (because of access control in the file system), the grfMode parameter can only specify STGM_READ and not STGM_WRITE or STGM_READWRITE. The resulting new open compound file can still be written to, but a commit operation will fail (in transacted mode, write permissions are enforced at commit time).

Specifying STGM_SIMPLE provides a much faster implementation of a compound file object in a limited, but frequently-used case. This can be used by applications that require a compound file implementation with multiple streams and no storages. The simple mode does not support all of the methods on IStorage. For more information, refer to the STGM enumeration.

If the grfMode parameter specifies STGM_TRANSACTED and no file yet exists with the name specified by the pwcsName parameter, the file is created immediately. In an access-controlled file system, the caller must have write permissions in the file system directory in which the compound file is created. If STGM_TRANSACTED is not specified, and STGM_CREATE is specified, an existing file with the same name is destroyed before creating the new file.

StgCreateDocfile can be used to create a temporary compound file by passing a NULL value for the pwcsName parameter. However, these files are temporary only in the sense that they have a system-provided unique name − likely one that is meaningless to the user. The caller is responsible for deleting the temporary file when finished with it, unless STGM_DELETEONRELEASE was specified for the grfMode parameter.

See Also

StgCreateDocFileOnILockBytes


StgCreateDocfileOnILockBytes

Creates and opens a new compound file storage object on top of a byte array object provided by the caller. The storage object supports the OLE-provided, compound-file implementation for the IStorage interface.

WINOLEAPI StgCreateDocfileOnILockBytes(

ILockBytes * plkbyt,	//Points to the ILockBytes interface on the byte array object
DWORD grfMode,	//Specifies the access mode
DWORD reserved,	//Reserved; must be zero
IStorage ** ppstgOpen	//Points to location for returning the new storage object
);
Parameters

plkbyt

[in] Points to the ILockBytes interface on the underlying byte array object on which to create a compound file.

grfMode

[in] Specifies the access mode to use when opening the new compound file. For more information, see the STGM enumeration.

reserved

[in] Reserved for future use; must be zero.

ppstgOpen

[out] Points to the location of the IStorage pointer on the new storage object.

Return Values

S_OK

Indicates the compound file was successfully created.

STG_E_ACCESSDENIED

Access denied because the caller has insufficient permission, or another caller has the file open and locked.

STG_E_LOCKVIOLATION

Access denied because another caller has the file open and locked.

STG_E_FILEALREADYEXISTS

Indicates the compound file already exists and the grfMode parameter is set to STGM_FAILIFTHERE.

STG_S_CONVERTED

Indicates the compound file was successfully converted. The original byte array object was successfully converted to IStorage format.

STG_E_INSUFFICIENTMEMORY

Indicates the storage object was not created due to a lack of memory.

STG_E_INVALIDPOINTER

Indicates a bad pointer was in the pLkbyt parameter or the ppStgOpen parameter.

STG_E_INVALIDFLAG

Indicates a bad flag combination was in the grfMode parameter.

STG_E_TOOMANYOPENFILES

Indicates the storage object was not created due to a lack of file handles.

See also any file system errors for other error return values.

See also the ILockBytes interface for other error return values.

Remarks

The StgCreateDocfileOnILockBytes function creates a storage object on top of a byte array object using the OLE-provided, compound-file implementation of the IStorage interface. StgCreateDocfileOnILockBytes can be used to store a document in a relational database. The byte array (indicated by the pLkbyt parameter, which points to the ILockBytes interface on the object) is used for the underlying storage in place of a disk file.

Except for specifying a programmer-provided byte-array object, StgCreateDocfileOnILockBytes is similar to the StgCreateDocfile function. For more information, refer to StgCreateDocfile.

The newly created compound file is opened according to the access modes in the grfMode parameter. For conversion purposes, the file is always considered to already exist. As a result, it is not useful to use the STGM_FAILIFTHERE value, because it always causes an error to be returned. However, STGM_CREATE and STGM_CONVERT are both still useful.

The ability to build a compound file on top of a byte array object is provided to support having the data (underneath an IStorage and IStream tree structure) live in a non-persistent space. Given this capability, there is nothing preventing a document that is stored in a file from using this facility. For example, a container might do this to minimize the impact on its file format caused by adopting OLE. However, it is recommended that OLE documents adopt the IStorage interface for their own outer-level storage. This has the following advantages:

•	The storage structure of the document is the same as its storage structure when it is an embedded object, reducing the number of cases the application needs to handle.

•	One can write tools to access the OLE embeddings and links within the document without special knowledge of the document’s file format. An example of such a tool is a copy utility that copies all the documents included in a container containing linked objects. A copy utility like this needs access to the contained links to determine the extent of files to be copied.

•	The IStorage implementation addresses the problem of how to commit the changes to the file. An application using the ILockBytes interface must handle these issues itself.

•	Future file systems will likely implement the IStorage and IStream interfaces as their native abstractions, rather than layer on top of a byte array as is done in compound files. Such a file system could be built so documents using the IStorage interface as their outer level containment structure would get an automatic efficiency gain by having the layering flattened when files are saved on the new file system.

See Also

StgCreateDocfile


StgGetIFillLockBytesOnFile

Opens a wrapper object on a temporary file.

WINOLEAPI StgGetIFillLockBytes(

OLECHAR *pwcsName	// Pointer to file specified by filename
IFillLockBytes **ppflb	// Pointer to new byte array wrapper object
);
Parameters

pwcsName

[in] Pointer to the name of  the file to be instantiated.

pflb

[out] Indirect pointer to new byte array wrapper object.

Remarks

The moniker that manages the downloading of the file specified in pwcsName calls this function in the course of creating the asynchronous storage necessary to manage the asynchronous downloading of data. The moniker first creates a temporary file, then calls this function to create the wrapper object on that file. Finally, the moniker calls StgOpenAsyncDocfileOnIFillLockBytes to open the root storage of the compound file that is to be downloaded into the temporary file.

See Also

IFillLockBytes, ILockBytes, StgOpenAsyncDocfileOnIFillLockBytes


StgGetIFillLockBytesOnILockBytes

Creates a new wrapper object on a byte array object provided by the caller.

WINOLEAPI StgOpenAsyncDocFileOnIFillLockBytes(

ILockBytes *pilb	// Pointer to existing byte array object
IFillLockBytes **ppflb	// Pointer to new byte array wrapper object
);
Parameters

pilb

[in] Pointer to an existing byte array object.

pflb

[out] Indirect pointer to new byte array wrapper object..

Return Values

This function supports the standard return values E_OUTOFMEMORY, E_UNEXPECTED, E_INVALIDARG, and E_FAIL, as well as the following:

Remarks

The StgGetIFillLockBytesOnILockBytes function makes it possible to create an asynchronous storage wrapper object on a custom byte array object. For example, if you wanted to implement asynchronous storage on a database for which you have already created a byte array object, you would call this function to create the wrapper object for the byte array. To do so, the function instantiates a new wrapper object and then initializes it by passing it a pointer to the existing byte array object.

See Also

IFillLockBytes, ILockBytes


StgIsStorageFile

Indicates whether a particular disk file contains a storage object.

WINOLEAPI StgIsStorageFile(

const WCHAR * pwcsName	//Points to a pathname of the file to check
);
Parameter

pwcsName

[in] Points to the name of the disk file to be examined. The pwcsName parameter is passed uninterpreted to the underlying file system.

Return Values

S_OK

Indicates the file contains a storage object.

S_FALSE

Indicates the file does not contain a storage object.

STG_E_INVALIDFILENAME

Indicates a bad filename was passed in the pwcsName parameter.

STG_E_FILENOTFOUND

Indicates the file was not found.

See also any file system errors for other error return values.

Remarks

At the beginning of the disk file underlying a storage object is a signature distinguishing a storage object from other file formats. The StgIsStorageFile function is useful to applications whose documents use a disk file format that might or might not use storage objects.

If a root compound file has been created in transacted mode but not yet committed, this method will still return S_OK.

See Also

StgIsStorageILockBytes


StgIsStorageILockBytes

Indicates whether the specified byte array contains a storage object.

WINOLEAPI StgIsStorageILockBytes(

ILockBytes * plkbyt	//ILockBytes pointer to the byte array to be examined
);
Parameter

plkbyt

ILockBytes pointer to the byte array to be examined.

Return Values

S_OK

Indicates the specified byte array contains a storage object.

S_FALSE

Indicates the specified byte array does not contain a storage object.

File system errors.

ILockBytes interface error return values.

Remarks

At the beginning of the byte array underlying a storage object is a signature distinguishing a storage object (supporting the IStorage interface) from other file formats. The StgIsStorageILockBytes function is useful to applications whose documents use a byte array (a bye array object supports the ILockBytes interface) that might or might not use storage objects.

See Also

StgIsStorageFile, ILockBytes


StgOpenAsyncDocfileOnIFillLockBytes

Opens an existing root asynchronous storage object on a byte array wrapper object provided by the caller.

WINOLEAPI StgOpenAsyncDocFileOnIFillLockBytes(

IFillLockBytes *pflb	// Pointer to byte array wrapper object
DWORD grfmode	// Storage access mode
DWORD asyncFlags	// Asynchronous storage flags
IStorage **ppstgOpen	// Indirect pointer to asynchronous storage
);
Parameters

pflb

[in] IFillLockBytes pointer to the byte array wrapper object that contains the storage object to be opened.

grfmode

[in] Specifies the access mode to use to open the storage object. The most common access mode, taken from the STGM enumeration, is STGM_READ.

asyncFlags

[in] Indicates whether a connection point on a storage will be inherited by its substorages and streams. ASYNC_MODE_COMPATIBILITY indicates that the connection point is inherited; ASYNC_MODE_DEFAULT indicates that the connection point is not inherited.

ppstgOpen

[out] Pointer to IStorage pointer on root asynchronous storage object.

Return Values

This function supports the standard return values E_OUTOFMEMORY, E_UNEXPECTED, E_INVALIDARG, and E_FAIL, as well as the following:

E_PENDING

Data is currently unavailable.

E_NOINTERFACE

A pointers was not returned to the requested interface.

STG_E_INSUFFICIENTMEMORY

There is insufficient memory to complete this operation.

Remarks

The root storage of the asynchronous storage object is opened according to the access mode in the grfMode parameter. A pointer to the IStorage interface on the opened storage object is supplied through the ppstgOpen parameter.

The byte array wrapper object must have been previously instantiated through a call to the StgGetIFillLockBytesOnFile function.

StgOpenAsyncDocFileOnIFillLockBytes does not support priority access mode or exclusions. Otherwise, it works in much the same way as the StgOpenStorageOnILockBytes function.

The returned storage object has a connection point for IProgressNotify.

See Also

IFillLockBytes, ILockBytes, StgGetIFillLockBytesOnFile, StgOpenStorageOnILockBytes.


StgOpenLayoutDocfile

Opens a compound file on an ILockBytes implementation that that is capable of monitoring sector information.

WINOLEAPI StgOpenLayoutDocfile(

OLECHAR *pwcsName	// Pointer to name of compound file to be opened
DWORD grfMode	// Access mode for the new storage object.
DWORD reserved	// Reserved for future use.
IStorage **ppstgOpen	// Indirect pointer to the new root storage object.
);
Parameters

pwcsName

[in] Pointer to the name of  the compound file to be opened.

grfMode

[in] Access mode to use when opening the newly created storage object. Values are taken from the STGM enumeration. Note that priority mode and exclusions are not supported. The most common access mode is likely to be STGM_DIRECT | STGM_READ | STGM_SHARE_EXCLUSIVE.

ppstgOpen

[out] Indirect pointer to the IStorage interface on the root object of the newly created root storage object.

Return Values

This function supports the standard return values E_OUTOFMEMORY, E_UNEXPECTED, E_INVALIDARG, and E_FAIL, as well as the following:

STG_E_INVALIDPARAMETER

One of the parameters is invalid

STG_E_INVALIDNAME

The name passed to this function is not a valid filename

STG_E_INSUFFICIENTMEMORY

There is insufficient memory to complete this operation.

This function can also return any of the error values returned by the StgOpenStorageOnILockBytes function.

Remarks

The compound file implementation created by this function exposes the ILayoutStorage interface on its root storage. Applications use this interface to express the optimal layout of their compound files for the purpose of more rapidly downloading and rendering data over a slow link. StgOpenLayoutDocfile returns a pointer to the IStorage interface on the root storage of the newly created compound file. Using this pointer, applications call QueryInterface to obtain a pointer to ILayoutStorage.

See Also

ILockBytes, IStorage, STGM


StgOpenStorage

Opens an existing root storage object in the file system. You can use this function to open compound files, but you cannot use it to open directories, files, or summary catalogs. Nested storage objects can only be opened using their parent's IStorage::OpenStorage method.

WINOLEAPI StgOpenStorage(

const WCHAR * pwcsName,	//Points to the pathname of the file containing storage object
IStorage * pstgPriority,	//Points to a previous opening of a root storage object
DWORD grfMode,	//Specifies the access mode for the object
SNB snbExclude,	//Points to an SNB structure specifying elements to be excluded
DWORD reserved,	//Reserved; must be zero
IStorage ** ppstgOpen	//Indirect IStorage pointer to the storage object on return
);
Parameters

pwcsName

[in] Points to the pathname of the storage object to open. This parameter is ignored if the pStgPriority parameter is not NULL.

pstgPriority

[in] Most often NULL. If not NULL, this parameter is used instead of the pwcsName parameter to specify the pointer to the IStorage interface on the storage object to open. It points to a previous opening of a root storage object, most often one that was opened in priority mode.

After the StgOpenStorage function returns, the storage object specified in the pStgPriority parameter on function entry is invalid, and can no longer be used. Use the one specified in the ppStgOpen parameter instead.

grfMode

[in] Specifies the access mode to use to open the storage object.

snbExclude

[in] If not NULL, this parameter points to a block of elements in this storage that are to be excluded as the storage object is opened. This exclusion occurs independent of whether a snapshot copy happens on the open. May be NULL.

reserved

[in] Indicates reserved for future use; must be zero.

ppstgOpen

[out] Points to the location of the IStorage pointer on the opened storage.

Return Values

S_OK

Indicates the storage object was successfully opened.

STG_E_FILENOTFOUND

Indicates the specified file does not exist.

STG_E_ACCESSDENIED

Access denied because the caller has insufficient permission, or another caller has the file open and locked.

STG_E_LOCKVIOLATION

Access denied because another caller has the file open and locked.

STG_E_FILEALREADYEXISTS

Indicates the file exists but is not a storage object.

STG_E_TOOMANYOPENFILES

Indicates the storage object was not opened because there are too many open files.

STG_E_INSUFFICIENTMEMORY

Indicates the storage object was not opened due to a lack of memory.

STG_E_INVALIDNAME

Indicates bad name in the pwcsName parameter.

STG_E_INVALIDPOINTER

Indicates bad pointer in one of the parameters: snbExclude, pwcsName, pstgPriority, or ppStgOpen.

STG_E_INVALIDFLAG

Indicates bad flag combination in the grfMode parameter.

STG_E_INVALIDFUNCTION

Indicates STGM_DELETEONRELEASE specified in the grfMode parameter.

STG_E_OLDFORMAT

Indicates the storage object being opened was created by the Beta 1 storage provider. This format is no longer supported.

STG_E_OLDDLL

Indicates the DLL being used to open this storage object is a version prior to the one used to create it.

STG_E_PATHNOTFOUND

Specified pathname does not exist.

Remarks

The StgOpenStorage function opens the specified root storage object according to the access mode in the grfMode parameter, and, if successful, supplies an IStorage pointer to the opened storage object in the ppstgOpen parameter.

Note  Opening a storage object in read and/or write mode without denying writer permission to others (the grfMode parameter specifies STGM_SHARE_DENY_WRITE) can be a time-consuming operation since the StgOpenStorage call must make a snapshot of the entire storage object.

Applications will often try to open storage objects with the following access permissions:

STGM_READ_WRITE | STGM_SHARE_DENY_WRITE

    // transacted vs. direct mode omitted for exposition

If the application succeeds, it will never need to do a snapshot copy. If it fails, the application can revert to using the permissions and make a snapshot copy:

STGM_READ_WRITE

    // transacted vs. direct mode omitted for exposition

In this case, the application should prompt the user before doing a time-consuming copy. Alternatively, if the document sharing semantics implied by the access modes are appropriate, the application could try to open the storage as follows:

STGM_READ | STGM_SHARE_DENY_WRITE

    // transacted vs. direct mode omitted for exposition

In this case, if the application succeeds, a snapshot copy will not have been made (because STGM_SHARE_DENY_WRITE was specified, denying others write access).

To reduce the expense of making a snapshot copy, applications can open storage objects in priority mode (grfMode specifies STGM_PRIORITY).

The snbExclude parameter specifies a set of element names in this storage object that are to be emptied as the storage object is opened: streams are set to a length of zero; storage objects have all their elements removed. By excluding certain streams, the expense of making a snapshot copy can be significantly reduced. Almost always, this approach will be used after first opening the storage object in priority mode, then completely reading the now-excluded elements into memory. This earlier priority mode opening of the storage object should be passed through the pstgPriority parameter to remove the exclusion implied by priority mode. The calling application is responsible for rewriting the contents of excluded items before committing. Thus, this technique is most likely only useful to applications whose documents do not require constant access to their storage objects while they are active.

See Also

IStorage, StgCreateDocfile


StgOpenStorageOnILockBytes

Opens an existing storage object that does not reside in a disk file, but instead has an underlying byte array provided by the caller.

WINOLEAPI StgOpenStorageOnILockBytes(

ILockBytes * plkbyt,	//Points to the ILockBytes interface on the underlying byte array
IStorage * pStgPriority,	//Points to a previous opening of a root storage object
DWORD grfMode,	//Specifies the access mode for the object
SNB snbExclude,	//Points to an SNB structure specifying elements to be excluded
DWORD reserved,	//Reserved, must be zero
IStorage ** ppstgOpen	//Points to location for returning the storage object
);
Parameters

plkbyt

[in] ILockBytes pointer to the underlying byte array object that contains the storage object to be opened.

pStgPriority

[in] Most often NULL. If not NULL, this parameter is used instead of the plkbyt parameter to specify the storage object to open. In this case, it points to the IStorage interface on a previously opened root storage object, most often one that was opened in priority mode.

After the StgOpenStorageOnILockBytes function returns, the storage object specified in the pStgPriority parameter on function entry is invalid, and can no longer be used; use the one specified in the ppStgOpen parameter instead.

grfMode

[in] Specifies the access mode to use to open the storage object.

snbExclude

[in] May be NULL. If not NULL, this parameter points to a block of elements in this storage that are to be excluded as the storage object is opened. This exclusion occurs independent of whether a snapshot copy happens on the open. .

reserved

[in] Indicates reserved for future use; must be zero.

ppstgOpen

[out] Points to the location of an IStorage pointer to the opened storage on successful return.

Return Values

S_OK

The storage object was successfully opened.

STG_E_FILENOTFOUND

The specified byte array does not exist.

STG_E_ACCESSDENIED

Access denied because the caller has insufficient permission, or another caller has the file open and locked.

STG_E_LOCKVIOLATION

Access denied because another caller has the file open and locked.

STG_E_FILEALREADYEXISTS

The byte array exists but is not a storage object.

STG_E_TOOMANYOPENFILES

The storage object was not opened because there are too many open files.

STG_E_INSUFFICIENTMEMORY

The storage object was not opened due to a lack of memory.

STG_E_INVALIDNAME

Either  pwcsName or snbExclude contains an invalid name.

STG_E_INVALIDPOINTER

Either snbExclude, pwcsName, pstgPriority, or ppStgOpen contains an invalid pointer.

STG_E_INVALIDFLAG

The grfMode parameter contains a bad flag combination.

STG_E_INVALIDFUNCTION

The access mode STGM_DELETEONRELEASE was specified in the grfMode parameter.

STG_E_OLDDLL

The DLL being used to open this storage object is a version prior to the one used to create it.

STG_E_OLDFORMAT

The storage object being opened was created by the Beta 1 storage provider. This format is no longer supported.

File system error return values.

ILockBytes interface error return values.

Remarks

StgOpenStorageOnILockBytes opens the specified root storage object. The storage object is opened according to the access mode in the grfMode parameter; a pointer to the IStorage interface on the opened storage object is supplied through the ppstgOpen parameter.

The storage object must have been previously created by the StgCreateDocfileOnILockBytes function.

Except for specifying a programmer-provided byte-array object, StgOpenStorageOnILockBytes is similar to the StgOpenStorage function. For more information, refer to StgOpenStorage.

See Also

StgOpenStorage, StgCreateDocfileOnILockBytes


StgSetTimes

Sets the creation, access, and modification times of the indicated file, if supported by the underlying file system.

WINOLEAPI StgSetTimes(

WCHAR const * lpszName,	//Points to the name of the file to be changed
FILETIME const * pctime,	//Points to the new value for the creation time
FILETIME const * patime,	//Points to the new value for the access time
FILETIME const * pmtime	//Points to the new value for the modification time
);
Parameters

lpszName

[in] Points to the name of the file to be changed.

pctime

[in] Points to the new value for the creation time.

patime

[in] Points to the new value for the access time.

pmtime

[in] Points to the new value for the modification time.

Return Values

S_OK

Indicates time values successfully set.

STG_E_FILENOTFOUND

Indicates element does not exist.

STG_E_INVALIDNAME

Indicates bad name passed in the lpszName parameter, or a file system error.

STG_E_ACCESSDENIED

Access denied because the caller has insufficient permission, or another caller has the file open and locked.

STG_E_LOCKVIOLATION

Access denied because another caller has the file open and locked.

File system error return values.

Remarks

The StgSetTimes function sets the time values for the specified file. Each of the time value parameters can be NULL, indicating no modification should occur.

It is possible that one or more of these time values are not supported by the underlying file system. This function sets the times that can be set and ignores the rest.


StringFromCLSID

Converts a CLSID into a string of printable characters. Different CLSIDs always convert to different strings.

WINOLEAPI StringFromCLSID(

REFCLSID rclsid,	//CLSID to be converted
LPOLESTR * ppsz	//Indirect pointer to the resulting string on return
);
Parameters

rclsid

[in] CLSID to be converted.

ppsz

[out] Pointer to the resulting string.

Return Values

This function supports the standard return value E_OUTOFMEMORY; as well as the following:

S_OK

Indicates the CLSID was successfully converted and returned.

Remarks

The StringFromCLSID function calls the StringFromGuid2 function to convert a globally unique identifier (GUID) into a string of printable characters.

See Also

CLSIDFromString, StringFromGuid2


StringFromGUID2

Converts a globally unique identifier (GUID) into a string of printable characters.

StringFromGUID2(

REFGUID rguid,	//Interface identifier to be converted
LPOLESTR lpsz,	//Pointer to the resulting string on return
int cbMax	//Maximum size the returned string is expected to be
);
Parameters

rguid

[in] Interface identifier to be converted.

lpsz

[out] Pointer to the resulting string on return.

cbMax

[in] Maximum size the returned string is expected to be.

Return Values

0 (zero)

Buffer is too small for returned string.

Non-zero value

The number of characters in the returned string, including the null terminator.

Remarks

The string that the lpsz parameter receives has a format like the following sample:

[c200e360-38c5-11ce-ae62-08002b2b79ef]

where the successive fields break the GUID into the form DWORD-WORD-WORD-WORD-WORD.DWORD covering the 128-bit GUID. The string includes enclosing braces, which are an OLE convention.

See Also

StringFromCLSID


StringFromIID

Converts an interface identifier into a string of printable characters.

WINOLEAPI StringFromIID(

REFIID rclsid	//Interface identifier to be converted
LPOLESTR * lplpsz	//Indirect pointer to the resulting string
);
Parameters

rclsid

[in] Interface identifier to be converted.

lplpsz

[out] Indirect pointer to the resulting string on return.

Return Values

This function supports the standard return value E_OUTOFMEMORY; as well as the following:

S_OK

The character string was successfully returned.

Remarks

The string returned by the function is freed in the standard way, using the task allocator (refer to the CoGetMallocfunction).

See Also

IIDFromString, CoGetMalloc


SUCCEEDED

#define SUCCEEDED(Status) ((HRESULT)(Status) >= 0)

Provides a generic test for success on any status value. Non-negative numbers indicate success.


WriteClassStg

Stores the specified CLSID in a storage object.

WINOLEAPI WriteClassStg(

IStorage * pStg,	//Points to the IStorage interface on the storage object
REFCLSID rclsid	//Specifies the CLSID to be stored in the storage object
);
Parameters

pStg

[in] IStorage pointer to the storage object that will get a new CLSID.

rclsid

[in] Points to the CLSID to be stored with the object.

Return Values

S_OK

Indicates the CLSID was successfully written to the file.

STG_E_MEDIUMFULL

Indicates the CLSID could not be written due to lack of memory.

IStorage::SetClass method error return values.

Remarks

The WriteClassStg function writes a CLSID to the specified storage object so it can be read by the ReadClassStg function. Container applications typically call this function before calling the IPersistStorage::Save method.

See Also

OleSave, ReadClassStg


WriteClassStm

Stores the specified CLSID in the stream.

WINOLEAPI WriteClassStm(

IStream * pStm,	//Points to the IStream interface on the stream object
REFCLSID rclsid	//Specifies the CLSID to be stored in the stream object
);
Parameters

pStm

[in] IStream pointer to the stream into which the CLSID is to be written.

rclsid

[in] Specifies the CLSID to write to the stream.

Return Values

S_OK

Indicates the CLSID was successfully written.

STG_E_MEDIUMFULL

The CLSID could not be written because there is no space left on device.

IStorage::SetClass method error return values.

Remarks

The WriteClassStm function writes a CLSID to the specified stream object so it can be read by the ReadClassStm function. Most applications do not call WriteClassStm directly. OLE calls it before making a call to an object’s IPersistStream::Save method.

See Also

ReadClassStm, WriteClassStg, ReadClassStg


WriteFmtUserTypeStg

Writes a clipboard format and user type to the storage object.

WINOLEAPI WriteFmtUserTypeStg(

IStorage * pStg,	//Points to the IStorage interface on the storage object
CLIPFORMAT cf,	//Specifies the clipboard format
LPWSTR * lpszUserType	//Points to the current user type
);
Parameters

pStg

[in] IStorage pointer to the storage object where the information is to be written.

cf

[in] Specifies the clipboard format that describes the structure of the native area of the storage object. The format tag includes the policy for the names of streams and substorages within this storage object and the rules for interpreting data within those streams.

lpszUserType

[in] Points to the object’s current user type. It cannot be NULL. This is the type returned by the IOleObject::GetUserType method. If this function is transported to a remote machine where the object class does not exist, this persistently stored user type can be shown to the user in dialog boxes.

Return Values

S_OK

Indicates the information was written successfully.

STG_E_MEDIUMFULL

Indicates information could not be written due to lack of space on the storage medium.

IStream::Write method error return values.

Remarks

The WriteFmtUserTypeStg function must be called in an object’s implementation of the IPersistStorage::Save method. It must also be called by document-level objects that use structured storage for their persistent representation in their save sequence.

To read the information saved, applications call the ReadFmtUserTypeStg function.

See Also

IPersistStorage::Save, ReadFmtUserTypeStg


OLE Glossary
Glossary

A

Activation

The process of loading an object in memory, which puts it into its running state. See also Binding.

Active state

A COM object that is in running state and has a visible user interface. See also Loaded state, Object state, Passive state, and Running state.

Absolute moniker

A moniker that specifies the absolute location of an object. An absolute moniker is analogous to a full path. See also Moniker.

Advisory holder

A COM object that caches, manages, and sends notifications of changes to container applications’ advisory sinks. See also Advisory sink.

Advisory sink

A COM object that can receive notifications of changes in an embedded object or linked object because it implements the IAdviseSink or IAdviseSink2 interface. Containers that need to be notified of changes in objects implement an advisory sink. Notifications originate in the server, which uses an advisory holder object to cache and manage notifications to containers. See also Advisory holder, Container application, and Object handler.

Aggregate object

A COM object that is made up of one or more other COM objects. One object in the aggregate is designated the controlling object, which controls which interfaces in the aggregate are exposed and which are private. This controlling object has a special implementation of IUnknown called the controlling IUnknown. All objects in the aggregate must pass calls to IUnknown methods through the controlling IUnknown. See also Aggregation.

Aggregation

A composition technique for implementing COM objects. It allows you to build a new object by reusing one or more existing objects’ interface implementations. The aggregate object chooses which interfaces to expose to clients, and the interfaces are exposed as if they were implemented by the aggregate object. Clients of the aggregate object communicate only with the aggregate object. See also Aggregate object. Contrast with Containment.

Ambient property

A run-time property that is managed and exposed by the container. Typically, an ambient property represents a characteristic of a form, such as background color, that needs to be communicated to a control so that the control can assume the look and feel of its surrounding environment. See also Run-time property.

Anti-moniker

The inverse of a file, item, or pointer moniker. An anti-moniker is added to the end of a file, item, or pointer moniker to nullify it. Anti-monikers are used in the construction of relative monikers. See also Relative Moniker.

Artificial reference counting

A technique used to safeguard an object before calling a function or method that could prematurely destroy it. A program calls IUnknown::AddRef to increment the object’s reference count before making the call that could free the object. After the function returns, the program calls IUnknown::Release to decrement the count.

Asynchronous binding

A type of binding in which it is necessary for the process to occur asynchronously to avoid performance degradation for the end user. Typically, asynchronous binding is used in distributed environments such as the World Wide Web. OLE supports asynchronous moniker classes and callback mechanisms that allow the process of locating and initializing an object in a distributed environment to occur while other operations are being carried out. See also Asynchronous moniker, and Binding.

Asynchronous call

A call to a function that is executed separately so that the caller can continue processing instructions without waiting for the function to return. Contrast with Synchronous call.

Asynchronous moniker

A moniker that supports asynchronous binding. For example, instances of the system-supplied URL moniker class are asynchronous monikers. See also Asynchronous binding, Moniker, and URL moniker.

Automation

A way to manipulate an application’s objects from outside the application. Automation is typically used to create applications that expose objects to programming tools and macro languages, create and manipulate one application’s objects from another applications, or to create tools for accessing and manipulating objects.

B

Bind context

A COM object that implements the IBindCtx interface. Bind contexts are used in moniker operations to hold references to the objects activated when a moniker is bound. The bind context contains parameters that apply to all operations during the binding of a generic composite moniker and provides the moniker implementation with access to information about its environment. See also Binding, Generic composite moniker, and Moniker.

Binding

Associating a name with its referent. Specifically, locating the object named by a moniker, putting it into its running state if it isn’t already, and returning an interface pointer to it. Objects can be bound at run time (also called late binding or dynamic binding) or at compile time (also called static binding). See also Moniker and Running state.

C

Cache

A (usually temporary) local store of information. In OLE, a cache contains information that defines the presentation of a linked or embedded object when the container is opened. See also Container, Embedded object, and Linked object.

Cache initialization

Filling a linked or embedded object’s cache with presentation data. The IOleCache interface provides methods that a container can call to control the data that gets cached for linked or embedded objects. See also Container, Embedded object, and Linked object.

Class

The definition of an object in code. In C++, the class of an object is defined as a data type, but this is not the case in other languages. Because OLE can be coded in any language, class is used to refer to the general object definition. See also Class factory.

Class factory

A COM object that implements the IClassFactory interface and that creates one or more instances of an object identified by a given class identifier(CLSID). See also Class identifier.

Class identifier (CLSID)

A globally unique identifier (GUID) associated with an OLE class object. If a class object will be used to create more than one instance of an object, the associated server application should register its CLSID in the system registry so that clients can locate and load the executable code associated with the object(s). Every OLE server or container that allows linking to its embedded objects must register a CLSID for each supported object definition. See also Class and Class factory.

Class object

In object-oriented programming, an object whose state is shared by all the objects in a class and whose behavior acts on that classwide state data. In COM, class objects are called class factories, and typically have no behavior except to create new instances of the class. See also Class factory.

Client

A COM object that requests services from another object. See also Container.

Client site

The display site for an embedded or linked object within a compound document. The client site is the principal means by which an object requests services from its container. See also Compound document and Container.

CLSID

See Class identifier.

Commit

To persistently save any changes made to a storage or stream object since it was opened or changes were last saved. See also Revert.

Component

An object that encapsulates both data and code, and provides a well-specified set of publicly available services.

Component Object Model (COM)

The OLE object-oriented programming model that defines how objects interact within a single process or between processes. In COM, clients have access to an object through interfaces implemented on the object. See also Interface.

Composite menu bar

A shared menu bar composed of menu groups from both a container application and an in-place-activated server application. See also In-place activation.

Composite moniker

A moniker that consists of two or more monikers that are treated as a unit. A composite moniker can be non-generic, meaning that its component monikers have special knowledge of each other, or generic, meaning that its component monikers know nothing about each other except that they are monikers. See also Generic composite moniker.

Compound document

A document that includes linked or embedded objects, as well as its own native data. See also Embedded object and Linked object.

Compound File

An OLE-provided Structured Storage implementation that includes the IStorage, IStream, and ILockBytes interfaces. The StgXxx helper functions create and manipulate compound files. See also Structured Storage.

COM object

An object that conforms to the OLE Component Object Model (COM). A COM object is an instance of an object definition, which specifies the object’s data and one or more implementations of interfaces on the object. Clients interact with a COM object only through its interfaces. See also Component Object Model and Interface.

Connectable object

A COM object that implements, at a minimum, the IConnectionPointContainer interface, for the management of connection point objects. Connectable objects support communication from the server to the client. A connectable object creates and manages one or more connection point subobjects, which receive events from interfaces implemented on other objects and send them on to the client. See also Connection point object and Advisory sink.

Connection point object

A COM object that is managed by a connectable object and that implements the IConnectionPoint interface. One or more connection point objects can be created and managed by a connectable object. Each connection point object manages incoming events from a specific interface on another object and sends those events on to the client. See also Connectable object, Advisory sink.

Container

See Container application.

Container application

An application that supports compound documents. The container application provides storage for an embedded or linked object, a site for its display, access to the display site, and an advisory sink for receiving notifications of changes in the object. See also Advisory sink, Compound document, Client site, Embedded object, and Linked object.

Containment

A composition technique for implementing COM objects. It allows one object to reuse some or all of the interface implementations of one or more other objects. The outer object acts as a client to the other objects, delegating implementation when it wishes to use the services of one of the contained objects. Contrast with Aggregation.

Control

An embeddable, reusable COM object that supports, at a minimum, the IOleControl interface. Controls are typically associated with the user interface. They also support communication with a container and can be reused by multiple clients, depending upon licensing criteria. See also Licensing.

Control container

An application that supports embedding of controls by implementing the IOleControlSite interface. See also Control.

Control property

A run-time property that is exposed and managed by the control itself. For example, the font and text size used by the control are control properties. See also Run-time property.

Controlling object

The object within an aggregate object that controls which interfaces within the aggregate object are exposed and which are private. The IUnknown interface of the controlling object is called the controlling IUnknown. Calls to IUnknown methods of other objects in the aggregate must be passed to the controlling IUnknown. See also Aggregate object.

Control site

A structure implemented by a control container for managing the display and storage of a control. Within a given container, each control has a corresponding control site. See also Control and Control container.

D

Data transfer object

An object that implements the IDataObject interface and contains data to be transferred from one object to another through either the Clipboard or drag-and-drop operations.

Default object handler

A DLL provided with OLE that acts as a surrogate in the processing space of the container application for the real object.

With the default object handler, it is possible to look at an object’s stored data without actually activating the object. The default object handler performs other tasks, such as rendering an object from its cached state when the object is loaded into memory.

Dependent object

A COM object that is typically initialized by another object (the host object). Although the dependent object’s lifetime may only make sense during the lifetime of the host object, the host object does not function as the controlling IUnknown for the dependent object. In contrast, an object is an aggregated object when its lifetime (by means of its reference count) is completely controlled by the managing object. See also Host object. Contrast with Aggregation and Containment.

Direct access mode

One of two access modes in which a storage object can be opened. In direct mode, all changes are immediately committed to the root storage object. See also Transacted access mode.

Document object

An OLE document that can display one or more in-place activated views of its data within a native or foreign frame, such as a browser, while retaining full control over its user interface. In addition to implementing the usual OLE document and in-place activation interfaces, a document object must implement IOleDocument, and each of its views (in the form of a document view object) must implement IOleDocumentView. See also Document view, Document view object, and Frame.

Document object container

A container application capable of displaying one or more views of one or more document objects and of managing all contained document objects within a file. Each document object is associated with a document site, and each document site contains one or more document view sites corresponding to the views supported by the document object. A document object container also includes a container frame, which handles menu and toolbar negotiation and the enumeration of contained objects. See also Document object, Document site, Document view, Document view site, and Frame.

Document object server

A server application capable of providing document objects. See also Document object and Document object container.

Document site

A client site implemented by a document object container for managing the display and storage of a document object. Each document object in a container has a corresponding document site. See also Document object and Document object container.

Document site object

A COM object that implements the IOleDocumentSite interface, in addition to the usual client-site interfaces (such as IOleClientSite). See also Document site.

Document view

A particular presentation of a document’s data. A single document object can have one or more views, but a single document view can belong to one and only one document object. See also Document object.

Document view object

A COM object that implements the IOleDocumentView interface and corresponds to a particular document view. An object with multiple document views aggregates a separate document view object for each view. See also Document view.

Document view site

An object aggregated by a document site object for managing the display space for a particular view of a document object. Within a given document site, each document view has a corresponding document view site. See also Document object, Document site object, and Document view.

Document view site object

A COM object that is aggregated in a document site object and implements the IOleInPlaceSite interface and, optionally, the IContinueCallback interface. See also Document site object.

Drag and drop

An operation in which the end user uses the mouse or other pointing device to move data to another location in the same window or another window.

E

Embed

To insert an object into a compound document in such a way as to preserve the data formats native to that object, and to enable it to be edited from within its container using tools exposed by its server.

Embedded object

An object whose data is stored in a compound document, but the object runs in the process space of its server. The default object handler provides a surrogate in the processing space of the container application for the real object. See also Default object handler, Compound document, and Container application.

.EXE server

See Out-of-process server.

Extended property

A run-time property, such as a control’s position and size, that a user would assume to be exposed by the control but is exposed and managed by the container. See also Run-time property.

F

File moniker

A moniker based on a path in the file system. File monikers can be used to identify objects that are saved in their own files. A file moniker is a COM object that supports the system-provided implementation of the IMoniker interface for the file moniker class. See also Item moniker, Generic composite moniker, and Moniker.

Font object

A COM object that provides access to Graphics Device Interface (GDI) fonts by implementing the IFont interface.

Format identifier

A GUID that identifies a persistent property set. Also referred to as FMTID. See also Property set.

Frame

The part of a container application responsible for negotiating menus, accelerator keys, toolbars, and other shared user-interface elements with an embedded COM object or a document object. See also Document object and Embedded object.

Frame object

A COM object that implements the IOleInPlaceFrame interface and, optionally, the IOleCommandTarget interface.

G

Generic composite moniker

A sequenced collection of monikers, starting with a file moniker to provide the document-level path and continuing with one or more item monikers that, taken as a whole, uniquely identifies an object. See also Composite moniker, Item moniker, and File moniker.

H

Helper function

A function that encapsulates calls to other functions and interface methods publicly available in the OLE SDK. Helper functions are a convenient way to call frequently used sequences of function and method calls that accomplish common tasks.

Host object

A COM object that forms a hierarchical relationship with one or more other COM objects, known as the dependent objects. Typically, the host object instantiates the dependent objects, and their existence only makes sense within the lifetime of the host object. However, the host object does not act as the controlling IUnknown for the dependent objects, nor does it directly delegate to the interface implementations of those objects. See also Dependent object.

HRESULT

An opaque result handle defined to be zero for a successful return from a function and nonzero if error or status information is returned. To convert an HRESULT into the more detailed SCODE, applications call GetScode(). See also SCODE.

Hyperlink object

A COM object that implements, at a minimum, the IHlink interface and acts as a link to an object at another location (the target). A hyperlink is made up of four parts: a moniker that identifies the target’s location; a string for the location within the target; a friendly, or displayable, name for the target; and a string that can contain additional parameters.

Hyperlink browse context

A COM object that implements the IHlinkBrowseContext interface and maintains the hyperlink navigation stack. The browse context object manages the hyperlink frame window and hyperlink target object’s window. See also Hyperlink target.

Hyperlink container

A container application that supports hyperlinks by implementing the IHlinkSite interface and, if the container’s objects can be targets of other hyperlinks, the IHlinkTarget interface. See also Container.

Hyperlink frame object

A COM object that implements the IHlinkFrame interface and controls the top-level navigation and display of hyperlinks for the frame’s container and the hyperlink target’s server.

Hyperlink site object

A COM object that implements the IHlinkSite interface and supplies either the moniker or interface identifier of its hyperlink container. One hyperlink site can serve multiple hyperlinks. See also Hyperlink and Hyperlink container.

Hyperlink target object

A COM object that implements the IHlinkTarget interface and supplies its moniker, friendly name, and other information that other hyperlink objects will use to navigate to it.

I

In parameter

A parameter that is allocated, set, and freed by the caller of a function or interface method. An In parameter is not modified by the called function. See also In/Out parameter and Out parameter.

In/Out parameter

A parameter that is initially allocated by the caller of a function or interface method, and set, freed, and reallocated, if necessary, by the process that is called. See also In parameter and Out parameter.

In-place activation

Editing an embedded object within the window of its container, using tools provided by the server. Linked objects do not support in-place activation; they are always edited in the window of the server. See also Embedded object and Linked object.

In-process server

A server implemented as a DLL that runs in the process space of the client. See also Out-of-process server, Local server, and Remote server.

Instance

An object for which memory is allocated or which is persistent.

Interface

A group of semantically related functions that provide access to a COM object. Each OLE interface defines a contract that allows objects to interact according to the Component Object Model (COM). While OLE provides many interface implementations, most interfaces can also be implemented by developers designing OLE applications. See also Component Object Model and COM object.

Interface identifier (IID)

A globally unique identifier (GUID) associated with an interface. Some functions take IIDs as parameters to allow the caller to specify which interface pointer should be returned.

Item moniker

A moniker based on a string that identifies an object in a container. Item monikers can identify objects smaller than a file, including embedded objects in a compound document, or a pseudo-object (like a range of cells in a spreadsheet). See also File moniker, Generic composite moniker, Moniker, and Pseudo-object.

L

Licensing

A feature of COM that provides control over object creation. Licensed objects can be created only by clients that are authorized to use them. Licensing is implemented in COM through the IClassFactory2 interface and by support for a license key that can be passed at run time.

Link object

A COM object that is created when a linked COM object is created or loaded. The link object is provided by OLE and implements the IOleLink interface.

Linked object

A COM object whose source data physically resides where it was initially created. Only a moniker that represents the source data and the appropriate presentation data are kept with the compound document. Changes made to the link source are automatically reflected in the linked object. See also Link source.

Link source

The data that is the source of a linked object. A link source may be a file or a portion of a file, such as a selected range of cells within a file (also called a pseudo object). See also Linked object.

Loaded state

The state of an object after its data structures have been loaded into memory and are accessible to the client process. See also Active state, Passive state, and Running state.

Local server

An out-of-process server implemented as an .EXE application running on the same machine as its client application. See also In-process server, Out-of-process server, and Remote server.

Lock

A pointer held to—and possibly, a reference count incremented on—a running object. OLE defines two types of locks that can be held on an object: strong and weak. To implement a strong lock, a server must maintain both a pointer and a reference count, so that the object will remain “locked” in memory at least until the server calls Release. To implement a weak lock, the server maintains only a pointer to the object, so that the object can be destroyed by another process.

M

Marshaling

Packaging and sending interface method calls across thread or process boundaries.

Media type

An extension of MIME that allows data format negotiation between a client and an object. See also Multipurpose Internet Mail Extension (MIME).

MIME

See Multipurpose Internet Mail Extension.

MIME content type

See Media type.

Multipurpose Internet Mail Extension (MIME)

An Internet protocol originally developed to allow exchange of electronic mail messages with rich content across heterogeneous network, machine, and e-mail environments. In practice, MIME has also been adopted and extended by non-mail applications.

Moniker

An object that implements the IMoniker interface. A moniker acts as a name that uniquely identifies a COM object. In the same way that a path identifies a file in the file system, a moniker identifies a COM object in the directory namespace. See also Binding.

Moniker class

An implementation of the IMoniker interface. System-supplied moniker classes include file monikers, item monikers, generic composite monikers, anti-monikers, pointer monikers, and URL monikers.

Moniker client

An application that uses monikers to acquire interface pointers to objects managed by another application.

Moniker provider

An application that makes available monikers that identify the objects it manages, so that the objects are accessible to other applications.

N

Namespace extension

An in-process COM object that implements IShellFolder, IPersistFolder, and IShellView, which are sometimes referred to as the namespace extension interfaces. A namespace extension is used either to extend the shell’s namespace or to create a separate namespace. Primary users are the Windows Explorer and common file dialog boxes.

Native data

The data used by an OLE server application when editing an embedded object. See also Presentation data.

O

Object

In OLE, a programming structure encapsulating both data and functionality that are defined and allocated as a single unit and for which the only public access is through the programming structure’s interfaces. A COM object must support, at a minimum, the IUnknown interface, which maintains the object’s existence while it is being used and provides access to the object’s other interfaces. See also COM and Interface.

Object handler

See Default object handler.

Object state

The relationship between a compound document object in its container and the application responsible for the object’s creation: active, passive, loaded, or running. Passive objects are stored on disk or in a database, and the object is not selected or active. In the loaded state, the object’s data structures have been loaded into memory, but they are not available for operations such as editing. Running objects are both loaded and available for all operations. Active objects are running objects that have a visible user interface.

Object type name

A unique identification string that is stored as part of the information available for an object in the registration database.

OLE

Microsoft’s object-based technology for sharing information and services across process and machine boundaries.

OLE Automation

See Automation.

OLE control

See Control.

Out-of-process server

A server, implemented as an .EXE application, which runs outside the process of its client, either on the same machine or a remote machine. See also Local server and Remote server.

Out parameter

A parameter that is allocated and freed by the caller, but its value is set by the function being called. See also In parameter and In/Out parameter.

P

Passive state

The state of a COM object when it is stored (on disk or in a database). The object is not selected or active. See also Active state, Loaded state, Object state, and Running state.

Persistent properties

Information that can be stored persistently as part of a storage object such as a file or directory. Persistent properties are grouped into property sets, which can be displayed and edited.

Persistent properties are different from the run-time properties of objects created with OLE Controls and Automation technologies, which can be used to affect system behavior. The PROPVARIANT structure defines all valid types of persistent properties, whereas the VARIANT structure defines all valid types of run-time properties. See also Compound files, Property, and Property sets.

Persistent storage

Storage of a file or object in a medium such as a file system or database so that the object and its data persist when the file is closed and then re-opened at a later time.

Picture object

A COM object that provides access to GDI images by implementing the IPicture interface.

Pointer moniker

A moniker that maps an interface pointer to an object in memory. Whereas most monikers identify objects that can be persistently stored, pointer monikers identify objects that cannot. They allow such objects to participate in a moniker binding operation.

Presentation data

The data used by a container to display embedded or linked objects. See also Native data.

Primary verb

The action associated with the most common or preferred operation users perform on an object. The primary verb is always defined as verb zero in the system registration database. An object’s primary verb is executed by double-clicking on the object.

Property

Information that is associated with an object. In OLE, properties fall into two categories: run-time properties and persistent properties. Run-time properties are typically associated with control objects or their containers. For example, background color is a run-time property set by a control’s container. Persistent properties are associated with stored objects. See also Persistent properties and Run-time properties.

Property frame

The user interface mechanism that displays one or more property pages for a control. The OLE Controls run-time system provides a standard implementation of a property frame that can be accessed by using the OleCreatePropertyFrame helper funtion. See also Control and Property page.

Property identifier

A four-byte signed integer that identifies a persistent property within a property set. See also Persistent property and Property set.

Property page

A COM object with its own CLSID that is part of a user interface, implemented by a control, and allows the control’s properties to be viewed and set. Property page objects implement the IPropertyPage interface. See also CLSID, Control.

Property page site

The location within a property frame where a property page is displayed. The property frame implements the IPropertyPageSite interface, which contains methods to manage the sites of each of the property pages supplied by a control. See also Property frame.

Property set

A logically related group of properties that is associated with a persistently stored object. To create, open, delete, or enumerate one or more property sets, implement the IPropertySetStorage interface. If you are using compound files, you can use OLE’s implementation of this interface rather than implementing your own. See also Persistent properties.

Property set storage

A COM storage object that holds a property set. A property set storage is a dependent object associated with and managed by a storage object. See also Dependent object, Property set.

Property sheet

A set of property pages for one or more objects. See also Property page.

Proxy

An interface-specific object that packages parameters for that interface in preparation for a remote method call. A proxy runs in the address space of the sender and communicates with a corresponding stub in the receiver’s address space. See also Stub, Marshaling, and Unmarshaling.

Proxy manager

In standard marshaling, a proxy that manages all the interface proxies for a single object. See also Marshaling, Proxy.

Pseudo-object

A portion of a document or embedded object, such as a range of cells in a spreadsheet, that can be the source for a COM object.

R

Reference counting

Keeping a count of each interface pointer held on an object to ensure that the object is not destroyed before all references to it are released. See also Lock.

Relative moniker

A moniker that specifies the location of an object  relative to the location of another object. A relative moniker is analogous to a relative path, such as ..\backup\report.old. See also Moniker.

Remote Server

A server application, implemented as an EXE, running on a different machine from the client application using it. See also In-process server, Local server, and Out-of-process server.

Revert

To discard any changes made to an object since the last time the changes were committed or the object’s storage was opened. See also Commit and Transacted access mode.

Root storage object

The outermost storage object in a document. A root storage object can contain other nested storage and stream objects. For example, a compound document is saved on disk as a series of storage and stream objects within a root storage object. See also Compound document, Storage object, and Stream object.

Running state

The state of a COM object when its server application is running and it is possible to access its interfaces and receive notification of changes. See also Active state, Loaded state, Passive state.

Running Object Table (ROT)

A globally accessible table on each computer that keeps track of all COM objects in the running state that can be identified by a moniker. Moniker providers register an object in the table, which increments the object’s reference count. Before the object can be destroyed, its moniker must be released from the table. See also Running state.

Run-time property

Discrete state information associated with a control object or its container. There are three types of run-time properties: ambient properties, control properties, and extended properties. See also Ambient property, Control property, and Extended property. Contrast with Persistent property.

S

SCODE

A DWORD value that is used to return detailed information to the caller of an interface method or function. See also HRESULT.

Self-registration

The process by which a server can perform its own registry operations.

Server application

An application that can create COM objects. Container applications can then embed or link to these objects. See also Container application.

Sink

See Advisory sink.

State

See Active state, Loaded state, Object state, Passive state, and Running state.

Static object

An object that contains only a presentation, with no native data. A container can treat a static object as though it were a linked or embedded object, except that it is not possible to edit a static object.

A static object can result, for example, from the breaking of a link on a linked object—that is, the server application is unavailable, or the user doesn’t want the linked object to be updated anymore. See also Native data.

Storage object

A COM object that implements the IStorage interface. A storage object contains nested storage objects or stream objects, resulting in the equivalent of a directory/file structure within a single file. See also Root storage object and Stream object.

Stream object

A COM object that implements the IStream interface. A stream object is analogous to a file in a directory/file system. See also Storage object.

Strong lock

See Lock.

Structured Storage

OLE’s technology for storing compound files in native file systems. See also Compound file, Storage object, and Stream object.

Stub

When a function’s or interface method’s parameters are marshaled across a process boundary, the stub is an interface-specific object that unpackages the marshaled parameters and calls the required method. The stub runs in the receiver’s address space and communicates with a corresponding proxy in the sender’s address space. See also Proxy, Marshaling, and Unmarshaling.

Stub manager

Manages all of the interface stubs for a single object.

Subobject

See Dependent object.

Synchronous call

A function call that does not allow further instructions in the calling process to be executed until the function returns. See also Asychronous call.

System registry

A system-wide repository of information supported by Windows, which contains information about the system and its applications, including OLE clients and servers.

T

Transacted access mode

One of two access modes in which a storage object can be opened. When opened in transacted mode, changes are stored in buffers until the root storage object commits its changes. See also Direct access mode, Commit, Revert, and Root storage object.

Type information

Information about an object’s class provided by a type library. To provide type information, a COM object implements the IProvideClassInfo interface.

U

Uniform data transfer

A model for transferring data via the Clipboard, drag and drop, or Automation. Objects conforming to this model implement the IDataObject interface. This model replaces DDE (dynamic data exchange). See also Data transfer object.

Unmarshaling

Unpacking parameters that have been sent to a proxy across process boundaries.

Universal resource locator (URL)

The identifier used by the World Wide Web for the names and locations of objects on the Internet. OLE provides a moniker class, URL moniker, whose implementation can be used to bind a client to objects identified by a URL. See also URL moniker.

URL moniker

A moniker based on a universal resource locator (URL). A client can use URL monikers to bind to objects that reside on the Internet. The system-supplied URL moniker class supports both synchronous and asynchronous binding. See also Asynchronous binding.

V

Virtual Table (VTBL)

An array of pointers to interface method implementations. See also Interface.

Visual Editing

A term in end-user documents that refers to the user’s ability to interact with a compound-document object in the context of its container. The term most often used by developers is in-place activation.

W

Weak lock

See Lock .


IAdviseSink

The IAdviseSink interface enables containers and other objects to receive notifications of data changes, view changes, and compound-document changes occurring in objects of interest. Container applications, for example, require such notifications to keep cached presentations of their linked and embedded objects up-to-date. Calls to IAdviseSink methods are asynchronous, so the call is sent and then the next instruction is executed without waiting for the call’s return.

For an advisory connection to exist, the object that is to receive notifications must implement IAdviseSink, and the objects in which it is interested must implement IOleObject::Advise and IDataObject::DAdvise. In-process objects and handlers may also implement IViewObject::SetAdvise. Objects implementing IOleObject must support all reasonable advisory methods. To simplify advisory notifications, OLE supplies implementations of the IDataAdviseHolder and IOleAdviseHolder, which keep track of advisory connections and send notifications to the proper sinks through pointers to their IAdviseSink interfaces. IViewObject (and its advisory methods) is implemented in the default handler.

As shown in the following table, an object that has implemented an advise sink registers its interest in receiving certain types of notifications by calling the appropriate method:

Call This Method	To Register for These Notifications
IOleObject::Advise	When a document is saved, closed, or renamed.
IDataObject::DAdvise	When a document’s data changes.
IViewObject::SetAdvise	When a document’s presentation changes.
When an event occurs that applies to a registered notification type, the object application calls the appropriate IAdviseSink method. For example, when an embedded object closes, it calls the IAdviseSink::OnClose method to notify its container. These notifications are asynchronous, occurring after the events that trigger them.

When to Implement

Objects, such as container applications and compound documents, implement IAdviseSink to receive notification of changes in data, presentation, name, or state of their linked and embedded objects. Implementers register for one or more types of notification, depending on their needs.

Notifications of changes to an embedded object originate in the server and flow to the container by way of the object handler. If the object is a linked object, the OLE link object intercepts the notifications from the object handler and notifies the container directly. All containers, the object handler, and the OLE link object register for OLE notifications. The typical container also registers for view notifications. Data notifications are usually sent to the OLE link object and object handler.

When to Use

Servers call the methods of IAdviseSink to notify objects with which they have an advisory connection of changes in an object’s data, view, name, or state.

Note  OLE does not permit synchronous calls in the implementation of asynchronous methods, so you cannot make synchronous calls within any of the the IAdviseSink interface’s methods. For example, an implementation of IAdviseSink::OnDataChange cannot contain a call to IDataObject::GetData.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IAdviseSink Methods	Description
OnDataChange	Advises that data has changed.
OnViewChange	Advises that view of object has changed.
OnRename	Advises that name of object has changed.
OnSave	Advises that object has been saved to disk.
OnClose	Advises that object has been closed.
See Also

IAdviseSink2, IDataAdviseHolder, IOleAdviseHolder, IOleObject::Advise, IOleObject::Unadvise, IOleObject::EnumAdvise


IAdviseSink::OnClose

Called by the server to notify all registered advisory sinks that the object has changed from the running to the loaded state.

Void OnClose();

Remarks

OnClose notification indicates that an object is making the transition from the running to the loaded state, so its container can take appropriate measures to ensure orderly shutdown. For example, an object handler must release its pointer to the object.

If the object that is closing is the last open object supported by its OLE server application, the application can also shut down.

In the case of a link object, the notification that the object is closing should always be interpreted to mean that the connection to the link source has broken.


IAdviseSink::OnDataChange

Called by the server to notify a data object’s currently registered advise sinks that data in the object has changed.

void OnDataChange(

FORMATETC * pFormatetc,	//Pointer to format information
STGMEDIUM * pStgmed	//Pointer to storage medium
);
Parameters

pFormatetc

[in] Pointer to the FORMATETC structure, which describes the format, target device, rendering, and storage information of the calling data object.

pStgmed

[in] Pointer to the STGMEDIUM structure, which defines the storage medium (global memory, disk file, storage object, stream object, GDI object, or undefined) and ownership of that medium for the calling data object.

Remarks

Object handlers and containers of link objects implement IAdviseSink::OnDataChange to take appropriate steps when notified that data in the object has changed. They also must call IDataObject::DAdvise to set up advisory connections with the objects in whose data they are interested. (See IDataObject::DAdvise for more information on how to specify an advisory connection for data objects.)

Containers that take advantage of OLE’s caching support do not need to register for data-change notifications, because the information necessary to update the container’s presentation of the object, including any changes in its data, are maintained in the object’s cache.

Notes to Implementers

If you implement IAdviseSink::OnDataChange for a container, remember that this method is asynchronous and that making synchronous calls within asynchronous methods is not valid. Therefore, you cannot call IDataObject::GetData to obtain the data you need to update your object. Instead, you either post an internal message, or invalidate the rectangle for the changed data by calling InvalidateRect and waiting for a WM_PAINT message, at which point you are free to get the data and update the object.

The data itself, which is valid only for the duration of the call, is passed using the storage medium pointed to by pmedium. Since the caller owns the medium, the advise sink should not free it. Also, if pmedium points to an IStorage or IStream interface, the sink must not increment the reference count.

See Also

IDataObject::DAdvise


IAdviseSink::OnRename

Called by the server to notify all registered advisory sinks that the object has been renamed.

Void OnRename(

IMoniker * pmk	//Pointer to the new moniker of the object
);
Parameter

pmk

[in] Pointer to the IMoniker interface on the new full moniker of the object.

Remarks

OLE link objects normally implement IAdviseSink::OnRename to receive notification of a change in the name of a link source or its container. The object serving as the link source calls OnRename and passes its new full moniker to the object handler, which forwards the notification to the link object. In response, the link object must update its moniker. The link object, in turn, forwards the notification to its own container.


IAdviseSink::OnSave

Called by the server to notify all registered advisory sinks that the object has been saved.

Void OnSave();

Remarks

Object handlers and link objects normally implement IAdviseSink::OnSave to receive notifications of when an object is saved to disk, either to its original storage (through a Save operation) or to new storage (through a Save As operation). Object Handlers and link objects register to be notified when an object is saved for the purpose of updating their caches, but then only if the advise flag passed during registration specifies ADVFCACHE_ONSAVE. Object handlers and link objects forward these notifications to their containers.


IAdviseSink::OnViewChange

Notifies an object’s registered advise sinks that its view has changed.

Void OnViewChange(

DWORD dwAspect,	//Value specifying aspect of object
LONG lindex	//Currently must be -1
);
Parameters

dwAspect

[in] The aspect, or view, of the object. Contains a value taken from the enumeration, DVASPECT.

lindex

[in] The portion of the view that has changed. Currently only -1 is valid.

Remarks

Containers register to be notified when an object’s view changes by calling IViewObject::SetAdvise. Once registered, the object will call the sink’s IAdviseSink::OnViewChange method when appropriate. OnViewChange can be called when the object is in either the loaded or running state.

Even though DVASPECT values are individual flag bits, dwAspect may represent only one value. That is, dwAspect cannot contain the result of an OR operation combining two or more DVASPECT values.

The lindex member represents the part of the aspect that is of interest. The value of lindex depends on the value of dwAspect. If dwAspect is either DVASPECT_THUMBNAIL or DVASPECT_ICON, lindex is ignored. If dwAspect is DVASPECT_CONTENT, lindex must be -1, which indicates that the entire view is of interest and is the only value that is currently valid.

See Also

IViewObject::SetAdvise


IAdviseSink2

The IAdviseSink2 interface is an extension of IAdviseSink, adding the method OnLinkSrcChange to the contract to handle a change in the moniker of a linked object. This avoids overloading the implementation IAdviseSink::OnRename to handle the renaming of both embedded objects and linked objects. In applications where different blocks of code might execute depending on which of these two similar events has occurred, using the same method for both events complicates testing and debugging.

When to Implement

If your application supports links, you should definitely implement IAdviseSink2. Even if your application does not support links, it may do so in future releases. In general, your code would implement just IAdviseSink2, which, because of contract inheritance, must include implementations of all of the IAdviseSink methods, along with the single additional method of IAdviseSink2.

When to Use

When a link source is renamed, the link object should notify its container by calling IAdviseSink::OnLinkSrcChange. If you are using the default handler, containing the OLE link object, you can still have both embedded and linked objects call IAdviseSink::OnRename, but for linked objects, the OLE link object maps the notification to IAdviseSink2::OnLinkSrcChange.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IAdviseSink Methods	Description
OnDataChange	Advises that data has changed.
OnViewChange	Advises that view of object has changed.
OnRename	Advises that name of object has changed.
OnSave	Advises that object has been saved to disk.
OnClose	Advises that object has been closed.
IAdviseSink2 Method	Description
OnLinkSrcChange	Advises that link source has changed.


IAdviseSink2::OnLinkSrcChange

Notifies the container that registered the advise sink that a link source has changed (either name or location), enabling the container to update the link’s moniker.

void OnLinkSrcChange(

IMoniker *pmk	//Pointer to the moniker of the new link source
);
Parameter

pmk

[in] Pointer to the IMoniker interface identifying the source of a linked object.

Remarks

A container of linked objects implements this method to receive notification in the event of a change in the moniker of its link source.

IAdviseSink2::OnLinkSrcChange is called by the OLE link object when it receives the OnRename notification from the link-source (object) application. The link object updates its moniker and sends the OnLinkSrcChange notification to containers that have implemented IAdviseSink2.

Notes to Implementers

Nothing prevents a link object from notifying its container of the moniker change by calling IAdviseSink::OnRename instead of OnLinkSrcChange. In practice, however, overloading OnRename to mean either that a link object’s moniker has changed or that an embedded object’s server name has changed makes it difficult for applications to determine which of these events has occurred. If the two events trigger different processing, as will often be the case, calling a different method for each makes the job of determining which event occurred much easier.

See Also

IAdviseSink::OnRename


IAdviseSinkEx

The IAdviseSinkEx interface is derived from IAdviseSink to provide extensions for notifying the sink of changes in an object’s view status.

When to Implement

Container applications and compound documents implement a site object with the IAdviseSinkEx interface to receive notification of changes in the view status of a contained object.

When to Use

A contained object, such as a control, calls the method of IAdviseSinkEx to notify its container of changes in its view status.

To determine which interface the sink supports, an object must call QueryInterface using the pointer that was passed to IViewObject::SetAdvise.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IAdviseSink Methods	Description
OnDataChange	Advises that data has changed.
OnViewChange	Advises that view of object has changed.
OnRename	Advises that name of object has changed.
OnSave	Advises that object has been saved to disk.
OnClose	Advises that object has been closed.
IAdviseSinkEx Methods	Description
OnViewStatusChange	Notifies the sink that a view status of an object has changed.
See Also

IAdviseSink, IViewObject::SetAdvise


IAdviseSinkEx::OnViewStatusChange

Notifies the sink that a view status of an object has changed.

HRESULT OnViewStatusChange(

DWORD dwViewStatus	//New view status
);
Parameters

dwViewStatus

[in] New view status specified in VIEWSTATUS enumeration values.

Return Values

S_OK

The sink was successfully notified of the new view status

Remarks

It is important that objects call the IAdviseSink:OnViewChange method whenever the object’s view changes even when the object is in place active. Containers rely on this notification to keep an object’s view up-to-date.

See Also

IAdviseSink:OnViewChange, VIEWSTATUS


IBindCtx

The IBindCtx interface provides access to a bind context, which is an object that stores information about a particular moniker binding operation. You pass a bind context as a parameter when calling many methods of IMoniker and in certain functions related to monikers.

A bind context includes the following information:

•	A BIND_OPTS structure containing a set of parameters that do not change during the binding operation. When a composite moniker is bound, each component uses the same bind context, so it acts as a mechanism for passing the same parameters to each component of a composite moniker.

•	A set of pointers to objects that the binding operation has activated. The bind context holds pointers to these bound objects, keeping them loaded and thus eliminating redundant activations if the objects are needed again during subsequent binding operations.

•	A pointer to the Running Object Table on the machine of the process that started the bind operation. Moniker implementations that need to access the Running Object Table should use the IBindCtx::GetRunningObjectTable method rather than using the GetRunningObjectTable function. This allows future enhancements to the system’s IBindCtx implementation to modify binding behavior.

•	A table of interface pointers, each associated with a string key. This capability enables moniker implementations to store interface pointers under a well-known string so that they can later be retrieved from the bind context. For example, OLE defines several string keys (e.g., “ExceededDeadline”, “ConnectManually”) that can be used to store a pointer to the object that caused an error during a binding operation.

When to Implement

You do not need to implement this interface. The system provides an IBindCtx implementation, accessible though a call to the CreateBindCtx function, that is suitable for all situations.

When to Use

Anyone writing a new moniker class by implementing the IMoniker interface must call IBindCtx methods in the implementation of several IMoniker methods. Moniker providers (servers that hand out monikers to identify their objects) may also need to call IBindCtx methods from their implementations of the IOleItemContainer or IParseDisplayName interfaces.

Moniker clients (objects that use monikers to acquire interface pointers to other objects) typically don’t call many IBindCtx methods. Instead, they simply pass a bind context as a parameter in a call to an IMoniker method. To acquire an interface pointer and activate the indicated object (called binding to an object), moniker clients typically do the following:

1.	Call the CreateBindCtx function to create a bind context and get a pointer to the IBindCtx interface on the bind context object..

2.	If desired (although this is rarely necessary), the moniker client can call IBindCtx::SetBindOptions to specify the bind options.

3.	Pass the bind context as a parameter to the desired IMoniker method (usually IMoniker::BindToObject).

4.	Call IUnknown::Release on the bind context to release it.

Although applications that act as link containers (container applications that allow their documents to contain linked objects) are moniker clients, they rarely call IMoniker methods directly. Generally, they manipulate linked objects through the system implementation (in the default handler) of the IOleLink interface. This implementation calls the appropriate IMoniker methods as needed, and, in doing so, passes pointers to IBindCtx interfaces on the proper bind context objects.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IBindCtx Methods	Description
RegisterObjectBound	Registers an object with the bind context.
RevokeObjectBound	Revokes an object’s registration.
ReleaseBoundObjects	Releases all registered objects.
SetBindOptions	Sets the binding options.
GetBindOptions	Retrieves the binding options.
GetRunningObjectTable	Retrieves a pointer to the Running Object Table.
RegisterObjectParam	Associates an object with a string key.
GetObjectParam	Returns the object associated with a given string key.
EnumObjectParam	Enumerates all the string keys in the table.
RevokeObjectParam	Revokes association between an object and a string key.
See Also

CreateBindCtx, IMoniker, IOleItemContainer, IParseDisplayName


IBindCtx::EnumObjectParam

Supplies a pointer to an IEnumString interface on an enumerator that can return the keys of the bind context’s string-keyed table of pointers.

HRESULT EnumObjectParam(

IEnumString **ppenum	//Indirect pointer to the enumerator object
);
Parameter

ppenum

[out] Indirect pointer to the IEnumString interface on the enumerator. If an error occurs, *ppenum is set to NULL. If *ppenum is non-NULL, the implementation calls IUnknown::AddRef on the parameter; it is the caller’s responsibility to call IUnknown::Release.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

An enumerator was successfully created and the pointer supplied.

Remarks

This method provides an IEnumString pointer to an enumerator that can return the keys of the bind context’s string-keyed table of pointers. The keys returned are the ones previously specified in calls to IBindCtx::RegisterObjectParam.

Notes to Callers

A bind context maintains a table of interface pointers, each associated with a string key. This enables communication between a moniker implementation and the caller that initiated the binding operation. One party can store an interface pointer under a string known to both parties so that the other party can later retrieve it from the bind context.

See Also

IBindCtx::RegisterObjectParam, IEnumString


IBindCtx::GetBindOptions

Returns the binding options stored in this bind context.

HRESULT GetBindOptions(

BIND_OPTS *pbindopts	//Pointer to a structure
);
Parameter

pbindopts

[in, out] Pointer to an initialized BIND_OPTS structure on entry that receives the current binding parameters on return.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The stored binding options were successfully returned.

Remarks

A bind context contains a block of parameters, stored in a BIND_OPTS structure, that are common to most IMoniker operations and that do not change as the operation moves from piece to piece of a composite moniker.

Notes to Callers

You typically call this method if you are writing your own moniker class (this requires that you implement the IMoniker interface). You call this method to retrieve the parameters specified by the moniker client.

You must initialize the BIND_OPTS structure that is filled in by this method. Before calling this method, you must initialize the cbStruct field of the structure to the size of the BIND_OPTS structure.

See Also

IBindCtx::SetBindOptions


IBindCtx::GetObjectParam

Retrieves the pointer associated with the specified key in the bind context’s string-keyed table of pointers.

HRESULT GetObjectParam(

LPOLESTR pszKey,	//Pointer to the key to be used
IUnknown **ppunk	//Indirect pointer to the object associated with the key
);
Parameters

pszKey

[in] Pointer to a zero-terminated wide character string (two bytes per character) containing the key to search for. Key string comparison is case-sensitive.

ppunk

[out] When successful, indirect pointer to the IUnknown interface on the object associated with pszKey. In this case, the implementation calls IUnknown::AddRef on the parameter. It is the caller’s responsibility to call IUnknown::Release. If an error occurs, ppunk is set to NULL.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The pointer associated with the specified key was successfully returned.

Remarks

A bind context maintains a table of interface pointers, each associated with a string key. This enables communication between a moniker implementation and the caller that initiated the binding operation. One party can store an interface pointer under a string known to both parties so that the other party can later retrieve it from the bind context.

The pointer this method retrieves must have previously been inserted into the table using the IBindCtx::RegisterObjectParam method.

Notes to Callers

Those writing a new moniker class (through an implementation of IMoniker) and some moniker clients (objects using a moniker to bind to an object) can call IBindCtx::GetObjectParam.

Objects using monikers to locate other objects can call this method when a binding operation fails to get specific information about the error that occurred. Depending on the error, it may be possible to correct the situation and retry the binding operation. See IBindCtx::RegisterObjectParam for more information.

Moniker implementations can call this method to deal with situations where a caller initates a binding operation and requests specific information. By convention, the implementer should use key names that begin with the string form of the CLSID of a moniker class (see the StringFromCLSID function).

See Also

IBindCtx::RegisterObjectParam, IBindCtx::EnumObjectParam


IBindCtx::GetRunningObjectTable

Provides an interface pointer to the Running Object Table (ROT) for the machine on which this bind context is running.

HRESULT GetRunningObjectTable(

IRunningObjectTable **pprot	//Indirect pointer to the Running Object Table
);
Parameter

pprot

[out] When successful, indirect pointer to the IRunningObjectTable interface on the Running Object Table. If an error occurs, *pprot is set to NULL. If *pprot is non-NULL, the implementation calls IUnknown::AddRef on the parameter; it is the caller’s responsibility to call IUnknown::Release.

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

A pointer to the ROT was returned successfully.

Remarks

The Running Object Table is a globally accessible table on each machine. It keeps track of all the objects that are currently running on the machine.

Notes to Callers

Typically, those implementing a new moniker class (through an implementation of IMoniker interface) call IBindCtx::GetRunningObjectTable. It is useful to call this method in an implementation of IMoniker::BindToObject or IMoniker::IsRunning to check whether a given object is currently running. You can also call this method in the implementation of IMoniker::GetTimeOfLastChange to learn when a running object was last modified.

Moniker implementations should call this method instead of using the GetRunningObjectTable function. This makes it possible for future implementations of IBindCtx to modify binding behavior.

See Also

IMoniker, IRunningObjectTable


IBindCtx::RegisterObjectBound

Calls IUnknown::AddRef on the specified object to ensure that the object remains active until the bind context is released. The method stores a pointer to the object in the bind context’s internal list of pointers.

HRESULT RegisterObjectBound(

IUnknown *punk	//Pointer to the object being registered
);
Parameter

punk

[in] Pointer to the IUnknown interface on the object that is being registered as bound.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The object was successfully registered.

Remarks

Notes to Callers

Those writing a new moniker class (through an implementation of the IMoniker interface), should call this method whenever the implementation activates an object. This happens most often in the course of binding a moniker, but it can also happen while retrieving a moniker’s display name, parsing a display name into a moniker, or retrieving the time that an object was last modified.

IBindCtx::RegisterObjectBound calls IUnknown::AddRef to create an additional reference to the object. You must, however, still release your own copy of the pointer. Note that calling this method twice for the same object creates two references to that object. You can release a reference obtained through a call to this method by calling IBindCtx::RevokeObjectBound. All references held by the bind context are released when the bind context itself is released.

Calling IBindCtx::RegisterObjectBound to register an object with a bind context keeps the object active until the bind context is released. Reusing a bind context in a subsequent binding operation (either for another piece of the same composite moniker, or for a different moniker) can make the subsequent binding operation more efficient because it doesn’t have to reload that object. This, however, improves performance only if the subsequent binding operation requires some of the same objects as the original one, so you need to balance the possible performance improvement of reusing a bind context against the costs of keeping objects activated unnecessarily.

IBindCtx does not provide a method to retrieve a pointer to an object registered using IBindCtx::RegisterObjectBound. Assuming the object has registered itself with the Running Object Table, moniker implementations can call IRunningObjectTable::GetObject to retrieve a pointer to the object.

See Also

IBindCtx::ReleaseBoundObjects, IBindCtx::RevokeObjectBound, IRunningObjectTable::GetObject


IBindCtx::RegisterObjectParam

Stores an IUnknown pointer on the specified object under the specified key in the bind context’s string-keyed table of pointers. The method must call IUnknown::AddRef on the stored pointer.

HRESULT RegisterObjectParam(

LPOLESTR pszKey,	//Pointer to the key to be used
IUnknown *punk	//Pointer to the object to be associated with the key
);
Parameters

pszKey

[in] Pointer to a zero-terminated wide character string (two bytes per character) containing the key under which the object is being registered. Key string comparison is case-sensitive.

punk

[in] Pointer to the IUnknown interface on the object that is to be registered.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The pointer was successfully registered under the specified string.

Remarks

A bind context maintains a table of interface pointers, each associated with a string key. This enables communication between a moniker implementation and the caller that initiated the binding operation. One party can store an interface pointer under a string known to both parties so that the other party can later retrieve it from the bind context.

Binding operations subsequent to the use of this method can use IBindCtx::GetObjectParam to retrieve the stored pointer.

Notes to Callers

IBindCtx::RegisterObjectParam is useful to those implementing a new moniker class (through an implementation of IMoniker) and to moniker clients (those who use monikers to bind to objects).

In implementing a new moniker class, you call this method when an error occurs during moniker binding to inform the caller of the cause of the error. The key that you would obtain with a call to this method would depend on the error condition. The following lists common moniker binding errors, describing for each the keys that would be appropriate:

MK_E_EXCEEDEDDEADLINE

If a binding operation exceeds its deadline because a given object is not running, you should register the object’s moniker using the first unused key from the list: “ExceededDeadline”, “ExceededDeadline1”, “ExceededDeadline2”, etc. If the caller later finds the moniker in the Running Object Table, the caller can retry the binding operation.

MK_E_CONNECTMANUALLY

The “ConnectManually” key indicates a moniker whose binding requires assistance from the end user. The caller can retry the binding operation after showing the moniker’s display name to request that the end user manually connect to the object. Common reasons for this error are that a password is needed or that a floppy needs to be mounted.

E_CLASSNOTFOUND

The “ClassNotFound” key indicates a moniker whose class could not be found (the server for the object identified by this moniker could not be located). If this key is used for an OLE compound-document object, the caller can use IMoniker::BindToStorage to bind to the object, and then try to carry out a Treat As... or Convert To... operation to associate the object with a different server. If this is successful, the caller can retry the binding operation.

If you’re a moniker client with detailed knowledge of the implementation of the moniker you’re using, you can also call this method to pass private information to that implementation.

You can define new strings as keys for storing pointers. By convention, you should use key names that begin with the string form of the CLSID of the moniker class (see the StringFromCLSID function).

If the pszKey parameter matches the name of an existing key in the bind context’s table, the new object replaces the existing object in the table.

When you register an object using this method, the object is not released until one of the following occurs:

•	It is replaced in the table by another object with the same key.

•	It is removed from the table by a call to IBindCtx::RevokeObjectParam.

•	The bind context is released. All registered objects are released when the bind context is released.

See Also

IBindCtx::GetObjectParam, IBindCtx::RevokeObjectParam, IBindCtx::EnumObjectParam


IBindCtx::ReleaseBoundObjects

Releases all pointers to all objects that were previously registered by calls to IBindCtx::RegisterObjectBound.

HRESULT ReleaseBoundObjects(void);

Return Value

S_OK

The objects were released successfully.

Remarks

You rarely call this method directly. The system’s IBindCtx implementation calls this method when the pointer to the IBindCtx interface on the bind context is released (the bind context is released). If a bind context is not released, all of the registered objects remain active.

If the same object has been registered more than once, this method calls the IUnknown::Release method on the object the number of times it was registered.

See Also

IBindCtx::RegisterObjectBound


IBindCtx::RevokeObjectBound

Releases the IUnknown pointer to the specified object and removes that pointer from the bind context’s internal list of pointers. This undoes a previous call to IBindCtx::RegisterObjectBound for the same object.

HRESULT RevokeObjectBound(

IUnknown *punk	//Pointer to the object whose registration is being revoked
);
Parameter

punk

[in] Pointer to the IUnknown interface on the object to be released.

Return Values

S_OK

The object was released successfully.

MK_E_NOTBOUND

Indicates that punk was not previously registered with a call to IBindCtx::RegisterObjectBound.

Remarks

You rarely call this method. This method is included for completeness.

See Also

IBindCtx::RegisterObjectBound


IBindCtx::RevokeObjectParam

Removes the specified key and its associated pointer from the bind context’s string-keyed table of objects. The key must have previously been inserted into the table with a call to IBindCtx::RegisterObjectParam.

HRESULT RevokeObjectParam(

LPOLESTR pszKey	//Pointer to the key to be revoked
);
Parameter

pszKey

[in] Pointer to a zero-terminated wide character string (two bytes per character) containing the key to remove. Key string comparison is case-sensitive.

Return Values

S_OK

The specified key was successfully removed from the table.

S_FALSE

No object has been registered with the specified key.

Remarks

A bind context maintains a table of interface pointers, each associated with a string key. This enables communication between a moniker implementation and the caller that initiated the binding operation. One party can store an interface pointer under a string known to both parties so that the other party can later retrieve it from the bind context.

This method is used to remove an entry from the table. If the specified key is found, the bind context also releases its reference to the object.

See Also

IBindCtx::RegisterObjectParam


IBindCtx::SetBindOptions

Specifies new values for the binding parameters stored in the bind context. Subsequent binding operations can call IBindCtx::GetBindOptions to retrieve the parameters.

HRESULT SetBindOptions(

BIND_OPTS *pbindopts	//Pointer to a structure
);
Parameter

pbindopts

[in] Pointer to a BIND_OPTS2 or a BIND_OPTS structure containing the binding parameters.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The parameters were stored successfully.

Remarks

A bind context contains a block of parameters, stored in a BIND_OPTS2 or a BIND_OPTS structure, that are common to most IMoniker operations. These parameters do not change as the operation moves from piece to piece of a composite moniker.

Notes to Callers

This method can be called by moniker clients (those who use monikers to acquire interface pointers to objects).

When you first create a bind context using the CreateBindCtx function, the fields of the BIND_OPTS structure are initialized to the following values:

cbStruct = sizeof(BINDOPTS);

grfFlags = 0;

grfMode = STGM_READWRITE;

dwTickCountDeadline = 0;

You can use the IBindCtx::SetBindOptions method to modify these values before using the bind context, if you want values other than the defaults. See BIND_OPTS for more information.

SetBindOptions only copies the struct members of BIND_OPTS2, but not the COSERVERINFO structure and the pointers it contains. Callers may not free any of these pointers until the bind context is released.

See Also

Bind_OPTS2, IBindCtx::GetBindOptions


IClassActivator

Specifies a method that retrieves a class object.

When to Implement

No implementation of a moniker or an object supporting IClassActivator currently exists within the system, however future versions of the operating system may contain such implementations. Implement the IClassActivator interface if you are writing a custom moniker type which you want to be able to compose to the left of a class moniker or any other moniker that supports binding to IClassActivator.

When to Use

Use IClassActivator if you write a custom moniker class that should behave similarly to class monikers when composed to the right of other monikers. File monikers also use this interface.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IClassActivator Method	Description
GetClassObject	Retrieves a class object.


IClassActivator::GetClassObject

Retrieves a class object. Similar to CoGetClassObject.

HRESULT GetClassObject(

REFCLSID *pClassID	//CLSID of class object desired
DWORD dwClsContext	//Values from CLSCTX
LCID locale	//LCID constant
REFIID riid	//IID of requested interface
void ** ppv	//Indirect pointer to requested interface
);
Parameter

pClassID

[in] Points to the CLSID that Identifies the class whose class object is to be retrieved.

dwClsContext

[in] The context in which the class is expected to run; values are taken from the CLSCTX enumeration.

locale

[in] Any LCID constant as defined in WINNLS.H.

riid

[in] IID of the interface on the object to which a pointer is desired.

ppv

[out] On successful return, an indirect pointer to the requested interface.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The CLSID was successfully returned.

Remarks

This method returns the class identifier (CLSID) for an object, used in later operations to load object-specific code into the caller’s context.

See Also

CoGetClassObject


IClassFactory

The IClassFactory interface contains two methods intended to deal with an entire class of objects, and so is implemented on the class object for a specific class of objects (identified by a CLSID). The first method, CreateInstance, creates an uninitialized object of a specified CLSID, and the second, LockServer, locks the object’s server in memory, allowing new objects to be created more quickly.

When to Implement

You must implement this interface for every class that you register in the system registry and to which you assign a CLSID, so objects of that class can be created.

When to Use

After calling the CoGetClassObject function to get an IClassFactory interface pointer to the class object, call the CreateInstance method of this interface to create a new uninitialized object.

It is not, however, always necessary to go through this process to create an object. To create a single uninitialized object, you can, instead, just call CoCreateInstance. OLE also provides numerous helper functions (with names of the form OleCreateXxx) to create compound document objects.

Call the LockServer method to keep the object server in memory and enhance performance only if you intend to create more than one object of the specified class.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IClassFactory Methods	Description
CreateInstance	Creates an uninitialized object.
LockServer	Locks object application open in memory.
See Also

CoGetClassObject, CoCreateInstance, OleCreate


IClassFactory::CreateInstance

Creates an uninitialized object.

HRESULT CreateInstance(

IUnknown * pUnkOuter,	//Pointer to whether object is or isn’t part of an aggregate
REFIID riid,	//Reference to the identifier of the interface
void ** ppvObject	//Indirect pointer to the interface
);
Parameters

pUnkOuter

[in] If the object is being created as part of an aggregate, pointer to the controlling IUnknown interface of the aggregate. Otherwise, pUnkOuter must be NULL.

riid

[in] Reference to the identifier of the interface to be used to communicate with the newly created object. If pUnkOuter is NULL, this parameter is frequently the IID of the initializing interface; if pUnkOuter is non-NULL, riid must be IID_IUnknown (defined in the header as the IID for IUnknown).

ppvObject

[out] Indirect pointer to the requested interface. If the object does not support the interface specified in riid, ppvObject must be set to NULL.

Return Values

This method supports the standard return values E_UNEXPECTED, E_OUTOFMEMORY, and E_INVALIDARG, as well as the following:

S_OK

The specified object was created.

CLASS_E_NOAGGREGATION

The pUnkOuter parameter was non-NULL and the object does not support aggregation.

E_NOINTERFACE

The object that ppvObject points to does not support the interface identified by riid.

Remarks

The IClassFactory interface is always on a class object. The CreateInstance method creates an uninitialized object of the class identified with the specified CLSID. When an object is created in this way, the CLSID must be registered in the system registry with CoRegisterClassObject.

The pUnkOuter parameter indicates whether the object is being created as part of an aggregate. Object definitions are not required to support aggregation — they must be specifically designed and implemented to support it.

The riid parameter specifies the IID (interface identifier) of the interface through which you will communicate with the new object. If pUnkOuter is non-NULL (indicating aggregation), the value of the riid parameter must be IID_IUnknown. If the object is not part of an aggregate, riid often specifies the interface though which the object will be initialized.

For OLE embeddings, the initialization interface is IPersistStorage, but in other situations, other interfaces are used. To initialize the object, there must be a subsequent call to an appropriate method in the initializing interface. Common initialization functions include IPersistStorage::InitNew (for new, blank embeddable components), IPersistStorage::Load (for reloaded embeddable components), IPersistStream::Load, (for objects stored in a stream object) or IPersistFile::Load (for objects stored in a file).

In general, if an application supports only one class of objects, and the class object is registered for single use, only one object can be created. The application must not create other objects, and a request to do so should return an error from IClassFactory::CreateInstance. The same is true for applications that support multiple classes, each with a class object registered for single use; a CreateInstance for one class followed by a CreateInstance for any of the classes should return an error.

To avoid returning an error, applications that support multiple classes with single-use class objects can revoke the registered class object of the first class by calling CoRevokeClassObject when a request for instantiating a second is received. For example, suppose there are two classes, A and B. When IClassFactory::CreateInstance is called for class A, revoke the class object for B. When B is created, revoke the class object for A. This solution complicates shutdown because one of the class objects might have already been revoked (and cannot be revoked twice).

See Also

CoRegisterClassObject, CoRevokeClassObject, CoCreateInstance, CoGetClassObject


IClassFactory::LockServer

Called by the client of a class object to keep a server open in memory, allowing instances to be created more quickly.

HRESULT LockServer(

BOOL fLock	//Increments or decrements the lock count
);
Parameter

fLock

[in] If TRUE, increments the lock count; if FALSE, decrements the lock count.

Return Values

This method supports the standard return values E_FAIL, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The specified object was either locked ( fLock = TRUE) or unlocked from memory ( fLock = FALSE).

Remarks

IClassFactory::LockServer controls whether an object’s server is kept in memory. Keeping the application alive in memory allows instances to be created more quickly.

Notes to Callers

Most clients do not need to call this function. It is provided only for those clients that require special performance in creating multiple instances of their objects.

Notes to Implementers

If the lock count is zero, there are no more objects in use, and the application is not under user control, the server can be closed. One way to implement IClassFactory::LockServer is to call CoLockObjectExternal.

The process that locks the object application is responsible for unlocking it. Once the class object is released, there is no mechanism that guarantees the caller connection to the same class later (as in the case where a class object is registered as single-use). It is important to count all calls, not just the last one, to IClassFactory::LockServer, because calls must be balanced before attempting to release the pointer to the IClassFactory interface on the class object or an error results. For every call to LockServer with fLock set to TRUE, there must be a call to LockServer with fLock set to FALSE. When the lock count and the class object reference count are both zero, the class object can be freed.

See Also

CoLockObjectExternal


IClassFactory2

The IClassFactory2 interface enables a class factory object, in any sort of object server, to control object creation through licensing. This interface is an extension to IClassFactory. This extension enables a class factory executing on a licensed machine to provide a license key that can be used later to create an object instance on an unlicensed machine. Such considerations are important for objects like controls that are used to build applications on a licensed machine. Subsequently, the application built must be able to run on an unlicensed machine. The license key gives only that one client application the right to instantiate objects through IClassFactory2 when a full machine license does not exist.

When to Implement

Implement this interface on a class factory object if you need to control object creation through a license. A class that supports licensing should be marked in an object’s type information with the [licensed] attribute on the object’s coclass entry.

The CreateInstance method inherited from IClassFactory is allowed to return CLASS_E_NOTLICENSED to indicate that object creation is controlled through licensing. The caller can create an instance of this object only through IClassFactory2::CreateInstanceLic if the caller has a license key obtained from IClassFactory2::RequestLicKey. Otherwise, no object creation is allowed.

When to Use

Use this interface to create licensed objects or to obtain a license key that can be used in later creations.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IClassFactory Methods	Description
CreateInstance	Creates an uninitialized object.
LockServer	Locks object application open in memory.
IClassFactory2 Methods	Description
GetLicInfo	Fills a LICINFO structure with information on the licensing capabilities of this class factory.
RequestLicKey	Creates and returns a license key that the caller can save and use later in calls to IClassFactory2::CreateInstanceLic.
CreateInstanceLic	Creates an instance of the licensed object given a license key from IClassFactory2::RequestLicKey.
See Also

IClassFactory


IClassFactory2::CreateInstanceLic

Creates an instance of the object class supported by this class factory, given a license key previously obtained from IClassFactory2::RequestLicKey. This method is the only possible means to create an object on an otherwise unlicensed machine.

HRESULT CreateInstanceLic(

IUnknown* pUnkOuter ,	//Pointer to controlling unknown of aggregated object
IUnknown* pUnkReserved ,	//Unused. Must be NULL.
REFIID riid ,	//Reference to the identifier of the interface
BSTR bstrKey ,	//License key provided by IClassFactory2::RequestLicKey
void** ppvObject	//Indirect pointer to the interface of the type specified in riid
);
Parameters

pUnkOuter

[in] Pointer to the controlling IUnknown interface on the outer unknown if this object is being created as part of an aggregate. If the object is not part of an aggregate, this parameter must be NULL.

pUnkReserved

[in] Unused. Must be NULL.

riid

[in] Reference to the identifier of the interface to be used to communicate with the newly created object.

bstrKey

[in] Run-time license key previously obtained from IClassFactory2::RequestLicKey that is required to create an object.

ppvObject

[out] Indirect pointer to the interface of the type specified in riid. This parameter is set to NULL on failure.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The license was successfully created.

E_NOTIMPL

This method is not implemented because objects can only be created on fully licensed machines through IClassFactory::CreateInstance.

E_POINTER

The pointers passed in bstrKey or ppvObject are not valid. For example, it may be NULL.

E_NOINTERFACE

The object can be created (and the license key is valid) except the object does not support the interface specified by riid.

CLASS_E_NOAGGREGATION

The pUnkOuter parameter is non-NULL, but this object class does not support aggregation.

CLASS_E_NOTLICENSED

The key provided in bstrKey is not a valid license key.

Remarks

Notes to Implementers

If the class factory does not provide a license key (that is, IClassFactory2::RequestLicKey returns E_NOTIMPL and the fRuntimeKeyAvail field in LICINFO is set to FALSE in IClassFactory2::GetLicInfo), then this method can also return E_NOTIMPL. In such cases, the class factory is implementing IClassFactory2 simply to specify whether or not the machine is licensed at all through the fLicVerified field of LICINFO.

See Also

IClassFactory2::GetLicInfo, IClassFactory2::RequestLicKey, LICINFO


IClassFactory2::GetLicInfo

Fills a caller-allocated LICINFO structure with information describing the licensing capabilities of this class factory.

HRESULT GetLicInfo(

LICINFO* pLicInfo	//Pointer to the structure
);
Parameters

pLicInfo

[out] Pointer to the caller-allocated LICINFO structure to be filled on output.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The LICINFO structure was successfully filled in.

E_POINTER

The address in pLicInfo is not valid. For example, it may be NULL.

Remarks

Notes to Implementers

E_NOTIMPL is not allowed as a return value since this method provides critical information for the client of a licensed class factory.

See Also

IClassFactory2::CreateInstanceLic, IClassFactory2::RequestLicKey, LICINFO


IClassFactory2::RequestLicKey

If the fRuntimeKeyAvail field in LICINFO has been returned as TRUE from IClassFactory2::GetLicInfo, then this method creates and returns a license key. The caller can save the license key persistently and use it later in calls to IClassFactory2::RequestLicKey.

HRESULT RequestLicKey(

DWORD dwReserved ,	//Unused. Must be zero.
BSTR* pbstrKey	//Pointer to the license key
);
Parameters

dwReserved

[in] Unused. Must be zero.

pbstrKey

[out] Pointer to the caller-allocated BSTR variable that receives the callee-allocated license key on successful return from this method. This parameter is set to NULL on any failure.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The license key was successfully created.

E_NOTIMPL

This class factory does not support run-time license keys.

E_POINTER

The address in pbstrKey is not valid. For example, it may be NULL.

CLASS_E_NOTLICENSED

This class factory supports run-time licensing, but the current machine itself is not licensed. Thus, a run-time key is not available on this machine.

Remarks

The caller can save the license key for subsequent calls to IClassFactory2::CreateInstanceLic to create objects on an otherwise unlicensed machine.

Notes to Callers

The caller must free the BSTR with SysFreeString when the key is no longer needed. The value of fRuntimeKeyAvail is returned through a previous call to IClassFactory2::GetLicInfo.

Notes to Implementers

This method allocates the BSTR key with SysAllocString or SysAllocString[Len], and the caller becomes responsible for this BSTR once this method returns successfully.

This method need not be implemented when a class factory does not support run-time license keys.

See Also

IClassFactory2::CreateInstanceLic, IClassFactory2::GetLicInfo, LICINFO


IClientSecurity

Gives the client control over the call-security of individual interfaces on a remote object.

All proxies generated by the COM MIDL compiler support the IClientSecurity interface automatically. If a call to QueryInterface for IClientSecurity fails, either the object is implemented in-process or it is remoted by a custom marshaler which does not support security (a custom marshaler may support security by offering the IClientSecurity interface to the client). The proxies passed as parameters to an IClientSecurity method must be from the same object as the IClientSecurity interface. That is, each object has a distinct IClientSecurity interface: calling IClientSecurity on one object and passing a proxy to another object will not work.

When to Implement

The system proxy manager provides an implementation to objects, so you would typically not implement this interface.

If, however, you are defining objects that support custom marshaling, you may choose to implement IClientSecurity on the objects’ custom proxy to maintain a consistent programming model for the objects’ client applications. You may also choose to support this interface on in-process objects.

When to Use

Call the methods of this interface to examine or modify the security settings of a particular connection to an out-of-process object. For example, you might temporarily establish a higher security level — one with complex encryption — only for the period when sensitive information or data is being sent to the object. Alternately, you might establish different proxies to the same object with different security levels and use them to support different clients that are calling your object, or to support different operations within your application.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IClientSecurity Methods	Description
IClientSecurity::QueryBlanket	Retrieves authentication information.
IClientSecurity::SetBlanket	Sets the authentication information that will be used to make calls on the specified proxy.
IClientSecurity::CopyProxy	Makes a copy of the specified proxy.
See Also

Security in COM


IClientSecurity::CopyProxy

Makes a private copy of the specified proxy.

HRESULT CopyProxy(

IUnknown *  punkProxy ,	//IUnknown pointer to the proxy to copy
IUnknown **  ppunkCopy	//Indirect IUnknown pointer to the copy
);
Parameter

punkProxy

[in] Points to the IUnknown interface on the proxy to be copied. May not be NULL.

ppunkCopy

[out] On successful return, points to the location of the IUnknown pointer to the copy of the proxy. It may not be NULL.

Return Values

S_OK

Success.

E_INVALIDARG

One or more arguments are invalid.

Remarks

IClientSecurity::CopyProxy makes a private copy of the specified proxy for the calling client. Its authentication information may be changed through a call to IClientSecurity::SetBlanket without affecting any other clients of the original proxy. The copy has the default values for the authentication information. The copy has one reference and must be released.

The helper function CoCopyProxy encapsulates a QueryInterface call on the proxy for a pointer to IClientSecurity, and with that pointer calls IClientSecurity::CopyProxy, and then releases the IClientSecurity pointer.

Local interfaces may not be copied. IUnknown and IClientSecurity are examples of existing local interfaces.

Copies of the same proxy have a special relationship with respect to QueryInterface. Given a proxy, a, of the IA interface of a remote object, suppose a copy of a is created, called b. In this case, calling QueryInterface from the b proxy for IID_IA will not retrieve the IA interface on b, but the one on a, the original proxy with the “default” security settings for the IA interface.

See Also

CoCopyProxy


IClientSecurity::QueryBlanket

Retrieves authentication information.

HRESULT QueryBlanket(

void*  pProxy ,	//Location for the proxy to query
DWORD*  pAuthnSvc ,	//Location for the current authentication service
DWORD*  pAuthzSvc ,	//Location for the current authorization service
OLECHAR **  pServerPrincName ,	//Location for the current principal name
DWORD * pAuthnLevel ,	//Location for the current authentication level
DWORD * pImpLevel ,	//Location for the current impersonation level
RPC_AUTH_IDENTITY_HANDLE **  ppAuthInfo ,	//Location for the value passed to IClientSecurity::SetBlanket
DWORD **  pCapabilities	//Location for flags indicating further capabilities of the proxy
);
Parameter

pProxy

[in] Pointer to the proxy to query.pAuthnSvc

[out] Pointer to a DWORD value defining the current authentication service. This will be a single value taken from the list of RPC_C_AUTHN_xxx constants. May be NULL, in which case the current authentication service is not retrieved.

pAuthzSvc

[out] Pointer to a DWORD value defining the current authorization service. This will be a single value taken from the list of RPC_C_AUTHZ_xxx constants. May be NULL, in which case the current authorization service is not retrieved.

pServerPrincName

[out] Pointer to the current principal name. The string will be allocated by the one called using CoTaskMemAlloc and must be freed by the caller using CoTaskMemFree when they are done with it. May be NULL, in which case the principal name is not retrieved.

pAuthnLevel

[out] Pointer to a DWORD value defining the current authentication level. This will be a single value taken from the list of RPC_C_AUTHN_LEVEL_xxx constants. May be NULL, in which case the current authentication level is not retrieved.

pImpLevel

[out] Pointer to a DWORD value defining the current impersonation level. This will be a single value taken from the list of RPC_C_IMP_LEVEL_xxx constants. May be NULL, in which case the current authentication level is not retrieved.

ppAuthInfo

[out] Pointer to the pointer value passed to IClientSecurity::SetBlanket indicating the identity of the client. Because this points to the value itself and is not a copy, it should not be manipulated. May be NULL, in which case the information is not retrieved.

pCapabilities

[out] Pointer to a DWORD of flags indicating further capabilities of the proxy. Currently, no flags are defined for this parameter and it will only return zero. May be NULL, in which case the flags indicating further capabilities are not retrieved.

Return Values

S_OK

Success.

E_INVALIDARG

One or more arguments are invalid.

E_OUTOFMEMORY

Insufficient memory to create the pServerPrincName out-parameter.

Remarks

IClientSecurity::QueryBlanket is called by the client to retrieve the authentication information COM will use on calls made from the specified proxy. With a pointer to an interface on the proxy, the client would first call QueryInterface for a pointer to IClientSecurity, then, with this pointer, would call IClientSecurity::QueryBlanket, followed by releasing the pointer.  This sequence of calls is encapsulated in the helper function CoQueryProxyBlanket.

In pProxy, you can pass any proxy, such as a proxy you get through a call to CoCreateInstance, CoUnmarshalInterface, or just passing an interface pointer as a parameter.  It can be any interface.  You cannot pass a pointer to something that is not a proxy.  Thus you can’t pass a pointer to an interface that has the local keyword in its interface definition since no proxy is created for such an interface.  IUnknown is the exception.

See Also

CoQueryProxyBlanket


IClientSecurity::SetBlanket

Sets the authentication information that will be used to make calls on the specified proxy.

HRESULT SetBlanket(

void *  pProxy ,	//Indicates the proxy to set
DWORD  dwAuthnSvc ,	//Authentication service to use
DWORD  dwAuthzSvc ,	//Authorization service to use
WCHAR * pServerPrincName ,	//The server principal name to use with the authentication service
DWORD  dwAuthnLevel ,	//The authentication level to use
DWORD  dwImpLevel ,	//The impersonation level to use
RPC_AUTH_IDENTITY_HANDLE *  pAuthInfo ,	//The identity of the client
DWORD  dwCapabilities	//Undefined — capability flags
);
Parameter

pProxy

[in] Indicates the proxy to set.

dwAuthnSvc

[in] A single DWORD value from the list of RPC_C_AUTHN_xxx constants indicating the authentication service to use. It may be RPC_C_AUTHN_NONE if no authentication is required. RPC_C_AUTHN_WINNT is the only value available on NT by default.

dwAuthzSvc

[in] A single DWORD value from the list of RPC_C_AUTHZ_xxx constants indicating the authorization service to use. If you are using the NT authentication service, use RPC_C_AUTHZ_NONE.

pServerPrincName

[in] Pointer to a WCHAR string that indicates the server principal name to use with the authentication service. If you are using RPC_C_AUTHN_WINNT, the principal name must be NULL.

dwAuthnLevel

[in] A single DWORD value from the list of RPC_C_AUTHN_LEVEL_xxx constants indicating the authentication level to use.

dwImpLevel

[in] A single DWORD value from the list of RPC_C_IMP_LEVEL_xxx constants indicating the impersonation level to use. Currently, only RPC_C_IMP_LEVEL_IMPERSONATE and RPC_C_IMP_LEVEL_IDENTIFY are supported by NTLMSSP.

pAuthInfo

[in] Pointer to an RPC_AUTH_IDENTITY_HANDLE value that establishes the identity of the client. It is authentication-service specific. Some authentication services allow the application to pass in a different user name and password. COM keeps a pointer to the memory passed in until COM is uninitialized or a new value is set. If NULL is specified COM uses the current identity (the process token ). For NTLMSSP the structure is SEC_WINNT_AUTH_IDENTITY_W. The format of this structure depends on the provider of the authentication service.

dwCapabilities

[in] A DWORD defining flags to establish indicating the further capabilities of this proxy. Currently, no capability flags are defined.

The caller should specify EOAC_NONE. EOAC_MUTUAL_AUTH is defined and may be used by other security providers, but is not supported by NTLMSSP. Thus, NTLMSSP will accept this flag without generating an error but without providing mutual authentication.

Return Values

S_OK

Success, append the headers.

E_INVALIDARG

One or more arguments is invalid.

Remarks

IClientSecurity::SetBlanket sets the authentication information that will be used to make calls on the specified proxy. The values specified here override the values chosen by automatic security. Calling this method changes the security values for all other users of the specified proxy. Call IClientSecurity::CopyProxy to make a private copy of the proxy.

By default, COM will choose the first available authentication service and authorization service available on both the client and server machines and the principal name which the server registered for that authentication service. Currently, COM will not try another authentication service if the first fails.

If pAuthInfo is NULL, it defaults to the current process token. dwAuthnLevel and dwImpLevel default to the values specified to CoInitializeSecurity. If CoInitializeSecurity is not called, the defaults are taken from the registry. The initial value for dwAuthnLevel on a proxy will be the higher of the value set on the client’s call to CoInitializeSecurity and the server’s call to CoInitializeSecurity .

Security information cannot be set on local interfaces. For example, it is illegal to set security on the IClientSecurity interface. However, since that interface is supported locally, there is no need for security. IUnknown is a special case. There are several cases.  First, IUnknown cannot be copied.  Thus all users of an object get the same security.  Second, SetBlanket can be used to set the security used for calls to QueryInterface.  However, since QueryInterface is heavily cached, the server might not see the call.  Third, AddRef and Release always use the security set with CoInitializeSecurity, never the values set with SetBlanket.

See Also

CoSetProxyBlanket, CoQueryProxyBlanket, RPC_C_AUTHN_xxx, RPC_C_AUTHZ_xxx, RPC_C_AUTHN_LEVEL_xxx, RPC_C_IMP_LEVEL_xxx


IConnectionPoint

The IConnectionPoint interface supports connection points for connectable objects.

Connectable objects support the following features:

•	Outgoing interfaces, such as event sets

•	The ability to enumerate the IIDs of the outgoing interfaces

•	The ability to connect and disconnect sinks to the object for those outgoing IIDs

•	The ability to enumerate the connections that exist to a particular outgoing interface

When to Implement

Implement this interface as part of support for connectable objects. To create a connectable object, you need to implement objects that provide four related interfaces:

•	IConnectionPointContainer

•	IEnumConnectionPoints

•	IConnectionPoint

•	IEnumConnections

The IConnectionPointContainer interface is implemented on the connectable object to indicate the existence of the outgoing interfaces. It provides access to an enumerator sub-object with the IEnumConnectionPoints interface. It also provides access to all the connection point sub-objects, each of which implements the IConnectionPoint interface. The IConnectionPoint interface provides access to an enumerator sub-object with the IEnumConnections interface.

Each connection point is a separate sub-object to avoid circular reference counting problems.

A connection point controls how many connections (one or more) it will allow in its implementation of IConnectionPoint::Advise. A connection point that allows only one interface can return E_NOTIMPL from the IConnectionPoint::EnumConnections method.

When to Use

A client can use the IConnectionPointContainer interface:

•	To obtain access to an enumerator sub-object with the IEnumConnectionPoints interface. The IEnumConnectionPoints interface can then be used to enumerate connection points for each outgoing IID.

•	To obtain access to connection point sub-objects with the IConnectionPoint interface for each outgoing IID. Through the IConnectionPoint interface, a client starts or terminates an advisory loop with the connectable object and the client’s own sink. The client can also use the IConnectionPoint interface to obtain an enumerator object with the IEnumConnections interface to enumerate the connections that it knows about.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IConnectionPoint Methods	Description
GetConnectionInterface	Returns the IID of the outgoing interface managed by this connection point.
GetConnectionPointContainer	Returns the parent (connectable) object’s IConnectionPointContainer interface pointer.
Advise	Creates a connection between a connection point and a client’s sink, where the sink implements the outgoing interface supported by this connection point.
Unadvise	Terminates a notification previously set up with Advise.
EnumConnections	Returns an object to enumerate the current advisory connections for this connection point.
See Also

IConnectionPoint, IConnectionPointContainer, IEnumConnectionPoints, IEnumConnections


IConnectionPoint::Advise

Establishes a connection between the connection point object and the client’s sink.

HRESULT Advise(

IUnknown *pUnk ,	//Pointer to the client’s advise sink
DWORD *pdwCookie	//Pointer to the connection point identifier used by Unadvise
);
Parameter

pUnk

[in] Pointer to the IUnknown interface on the client’s advise sink. The client’s sink receives outgoing calls from the connection point.

pdwCookie

[out] Pointer to a returned token that uniquely identifies this connection. The caller uses this token later to delete the connection by passing it to the IConnectionPoint::Unadvise method. If the connection was not successfully established, this value is zero.

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The connection has been established and *pdwCookie has the connection token.

E_POINTER

The value in pUnk or pdwCookie is not valid. For example, either pointer may be NULL.

CONNECT_E_ADVISELIMIT

The connection point has already reached its limit of connections and cannot accept any more.

CONNECT_E_CANNOTCONNECT

The sink does not support the interface required by this connection point.

Remarks

Advise establishes a connection between the connection point and the caller’s sink identified with pUnk.

The connection point must call pUnk->QueryInterface(iid, ...) to obtain the correct outgoing interface pointer to call when events occur, where iid is the IID for the outgoing interface managed by the connection point. When iid is passed to the IConnectionPointContainer::FindConnectionPoint method, an interface pointer to this same connection point is returned.

Notes to Implementers

The connection point must query the pUnk pointer for the correct outgoing interface. If this query fails, this method must return CONNECT_E_CANNOTCONNECT.

The pdwCookie value must be unique for each connection to any given instance of a connection point.

See Also

IConnectionPoint::Unadvise


IConnectionPoint::EnumConnections

Creates an enumerator object to iterate through the current connections for this connection point.

HRESULT EnumConnections(

IEnumConnections **ppEnum	//Indirect pointer to the newly created enumerator
);
Parameters

ppEnum

[out] Indirect pointer to the IEnumConnections interface on the newly created enumerator.

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The enumerator object was successfully created.

E_POINTER

The address in ppEnum is not valid. For example, it may be NULL.

E_NOTIMPL

The connection point does not support enumeration.

Remarks

Notes to Callers

The caller is responsible for calling (*ppEnum)->Release when the enumerator is no longer needed.

See Also

IEnumConnections


IConnectionPoint::GetConnectionInterface

Returns the IID of the outgoing interface managed by this connection point.

HRESULT GetConnectionInterface(

IID *pIID	//Pointer to an IID variable
);
Parameters

pIID

[out] Pointer to the identifier of the outgoing interface managed by this connection point.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The caller’s variable pIID contains the identifier of the outgoing interface managed by this connection point.

E_POINTER

The address in pIID is not valid. For example, it may be NULL.

Remarks

Using the IEnumConnectionPoints interface, a client can obtain a pointer to the IConnectionPoint interface. Using that pointer and the GetConnectionInterface method, the client can determine the IID of each connection point enumerated. The IID returned from this method must enable the caller to access this same connection point through IConnectionPointContainer::FindConnectionPoint.

Notes to Implementers

This method must be implemented in any connection point; E_NOTIMPL is not an acceptable return value.

See Also

IConnectionPoint, IConnectionPointContainer::FindConnectionPoint, IEnumConnectionPoints


IConnectionPoint::GetConnectionPointContainer

Retrieves the IConnectionPointContainer interface pointer for the parent connectable object.

HRESULT GetConnectionPointContainer(

IConnectionPointContainer **ppCPC	//Indirect pointer
);
Parameters

ppCPC

[out] Indirect pointer to the IConnectionPointContainer interface on the parent connectable object.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The IConnectionPointContainer pointer was successfully returned.

E_POINTER

The value in ppCPC is not a valid interface pointer. For example, it may be NULL.

Remarks

Notes to Callers

This method calls IConnectionPointContainer::AddRef. The caller is responsible for calling IConnectionPointContainer::Release to release this pointer when done.

Notes to Implementers

This method must call IConnectionPointContainer::AddRef before returning.

This method must be implemented in any connection point; E_NOTIMPL is not an acceptable return value.

See Also

IConnectionPoint, IConnectionPointContainer


IConnectionPoint::Unadvise

Terminates an advisory connection previously established through IConnectionPoint::Advise. The dwCookie parameter identifies the connection to terminate.

HRESULT Unadvise(

DWORD dwCookie	//Connection token
);
Parameters

dwCookie

[in] Connection token previously returned from IConnectionPoint::Advise.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The connection was successfully terminated.

CONNECT_E_NOCONNECTION

The value in dwCookie does not represent a valid connection.

Remarks

When an advisory connection is terminated, the connection point calls the Release method on the pointer that was saved for the connection during the IConnectionPoint::Advise method. This Release reverses the AddRef that was performed during the IConnectionPoint::Advise when the connection point calls the advisory sink’s QueryInterface.

See Also

IConnectionPoint::Advise


IConnectionPointContainer

The IConnectionPointContainer interface supports connection points for connectable objects.

Connectable objects support the following features:

•	Outgoing interfaces, such as event sets

•	The ability to enumerate the IIDs of the outgoing interfaces

•	The ability to connect and disconnect sinks to the object for those outgoing IIDs

•	The ability to enumerate the connections that exist to a particular outgoing interface

When to Implement

Implement this interface as part of support for connectable objects. To support connectable objects, you need to provide four related interfaces:

•	IConnectionPointContainer

•	IEnumConnectionPoints

•	IConnectionPoint

•	IEnumConnections

The IConnectionPointContainer interface indicates the existence of the outgoing interfaces. It provides access to an enumerator sub-object with the IEnumConnectionPoints interface. It also provides a connection point sub-object with the IConnectionPoint interface. The IConnectionPoint interface provides access to an enumerator sub-object with the IEnumConnections interface.

The connection point is a separate sub-object to avoid circular reference counting problems.

Implement the IConnectionPointContainer interface to make a connectable object, that is, an object with outgoing interfaces.

When to Use

Through IConnectionPointContainer, you can locate a specific connection point for one IID or obtain an enumerator to enumerate the connections points.

Use the IConnectionPointContainer interface to obtain access to:

•	Enumerator sub-objects with the IEnumConnectionPoints interface. The IEnumConnectionPoints interface can then be used to enumerate connection points for each outgoing IID.

•	Connection point sub-objects with the IConnectionPoint interface for each IID. Through the IConnectionPoint interface, a client starts or terminates an advisory loop with the connectable object and the client’s own sink. The client can also use the IConnectionPoint interface to obtain an enumerator object with the IEnumConnections interface to enumerate the connections it knows about.

When to Use

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IConnectionPointContainer Methods	Description
EnumConnectionPoints	Returns an object to enumerate all the connection points supported in the connectable object.
FindConnectionPoint	Returns a pointer to the IConnectionPoint interface for a specified connection point.
See Also

IConnectionPoint, IEnumConnectionPoints, IEnumConnections


IConnectionPointContainer::EnumConnectionPoints

Creates an enumerator object to iterate through all the connection points supported in the connectable object, one connection point per outgoing IID.

HRESULT EnumConnectionPoints(

IEnumConnectionPoints **ppEnum	//Indirect pointer to the newly created enumerator
);
Parameters

ppEnum

[out] Indirect pointer to the IEnumConnectionPoints interface on the newly created enumerator.

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The enumerator was successfully created.

E_POINTER

The value in ppEnum is not valid. For example, it may be NULL.

Remarks

Since IEnumConnectionPoints enumerates pointers to IConnectionPoint, the caller must use IConnectionPoint::GetConnectionInterface to determine the interface identifer of the outgoing interface that the connection point supports.

Notes to Callers

The caller is responsible for releasing the enumerator by calling (*ppEnum)->Release when it is no longer needed.

Notes to Implementers

Returning E_NOTIMPL is specifically disallowed because, with the exception of type information, there would be no other means through which a caller could find the IIDs of the outgoing interfaces. Since a connectable object typically has a fixed set of known outgoing interfaces, it is straightforward to implement the enumerator on top of a fixed length array of IIDs known at compile time.

See Also

IEnumConnectionPoints


IConnectionPointContainer::FindConnectionPoint

Returns a pointer to the IConnectionPoint interface of a connection point for a specified IID, if that IID describes a supported outgoing interface.

HRESULT FindConnectionPoint(

REFIID riid ,	//Requested connection point’s interface identifier
IConnectionPoint **ppCP	//Indirect pointer to the variable of the requested IID
);
Parameters

riid

[in] Interface identifier of the outgoing interface whose connection point object is being requested.

ppCP

[out] Indirect pointer to the IConnectionPoint interface on the connection point that supports riid. This parameter is set to NULL on failure of the call.

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The ppCP pointer has a valid interface pointer.

E_POINTER

The address in ppCP is not valid. For example, it may be NULL.

CONNECT_E_NOCONNECTION

This connectable object does not support the outgoing interface specified by riid.

Remarks

This method is the QueryInterface equivalent for an object’s outgoing interfaces, where the outgoing interface is specified with riid and where the interface pointer returned is always that of a connection point.

Notes to Callers

If the call is successful, the caller is responsible for releasing the connection point by calling (*ppCP)->Release when the connection point is no longer needed.

Notes to Implementers

E_NOTIMPL is not allowed as a return value for this method. Any implementation of IConnectionPointContainer must implement this method for the connectable object’s outgoing interfaces.

See Also

IConnectionPoint


IDataAdviseHolder

The IDataAdviseHolder interface contains methods that create and manage advisory connections between a data object and one or more advise sinks. Its methods are intended to be used to implement the advisory methods of IDataObject. IDataAdviseHolder is implemented on an advise holder object. Its methods establish and delete data advisory connections and send notification of change in data from a data object to an object that requires this notification, such as an OLE container, which must contain an advise sink.

Advise sinks are objects that require notification of change in the data the object contains and implement the IAdviseSink interface. Advise sinks are also usually associated with OLE compound document containers.

When to implement

Typically, you use the OLE-provided implementation of IDataAdviseHolder to simplify your implementation of the DAdvise, DUnadvise, and EnumDAdvise methods in the IDataObject interface, and to send notification of data change as appropriate. It would be necessary to implement IDataAdviseHolder only in the case where there may be a need for a custom data advise holder object, whose methods are to be used to implement the IDataObject methods in a set of servers.

When to use

Your implementation of the advisory methods of IDataObject can call the methods in IDataAdviseHolder. The first time you receive a call to IDataObject::DAdvise, call the function CreateDataAdviseHolder to create an instance of the OLE-provided advise holder and get a pointer to its IDataAdviseHolder interface. Then, in implementing the IDataObject interface on the data object, you delegate implementations of the DAdvise, DUnadvise, and EnumDAdvise methods to the corresponding methods in IDataAdviseHolder.

When the data of interest to an advise sink actually changes, you call IDataAdviseHolder::SendOnDataChange from the data object to carry out the necessary notifications.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IDataAdviseHolder Methods	Description
Advise	Creates a connection between an advise sink and a data object so the advise sink can receive notification of change in the data object.
Unadvise	Destroys a notification connection previously set up with the Advise method.
EnumAdvise	Returns an object that can be used to enumerate the current advisory connections.
SendOnDataChange	Sends a change notification back to each advise sink that is currently being managed.
See Also

IDataObject, IAdviseSink


IDataAdviseHolder::Advise

Creates a connection between an advise sink and a data object for receiving notifications.

HRESULT Advise(

IDataObject * pDataObject,	//Pointer to the data object for which notifications are requested
FORMATETC * pFormatetc,	//Pointer to the description of data to the advise sink
DWORD advf,	//Flags that specify how the notification takes place
IAdviseSink * pAdvSink,	//Pointer to the advise sink requesting notification
DWORD * pdwConnection	//Pointer to the connection token
);
Parameters

pDataObject

[in] Pointer to the IDataObject interface on the data object for which notifications are requested. If data in this object changes, a notification is sent to the advise sinks that have requested notification.

pFormatetc

[in] Pointer to the specified format, medium, and target device that is of interest to the advise sink requesting notification. For example, one sink may want to know only when the bitmap representation of the data in the data object changes. Another sink may be interested in only the metafile format of the same object. Each advise sink is notified when the data of interest changes. This data is passed back to the advise sink when notification occurs.

advf

[in] Contains a group of flags for controlling the advisory connection. Valid values are from the enumeration ADVF. However, only some of the possible ADVF values are relevant for this method. The following table briefly describes the relevant values; a more detailed description can be found in the description of the ADVF enumeration.

ADVF Value	Description
ADVF_NODATA	Asks that no data be sent along with the notification.
ADVF_ONLYONCE	Causes the advisory connection to be destroyed after the first notification is sent. An implicit call to IDataAdviseHolder::Unadvise is made on behalf of the caller to remove the connection.
ADVF_PRIMEFIRST	Causes an initial notification to be sent regardless of whether or not data has changed from its current state.
ADVF_DATAONSTOP	When specified with ADVF_NODATA, this flag causes a last notification with the data included to be sent before the data object is destroyed. When ADVF_NODATA is not specified, this flag has no effect.
pAdvSink

[in] Pointer to the IAdviseSink interface on the advisory sink that receives the change notification.

pdwConnection

[out] Pointer to a DWORD token that identifies this connection. The calling object can later delete the advisory connection by passing this token to IDataAdviseHolder::Unadvise. If this value is zero, the connection was not established.

Return Values

This method supports the standard return value E_INVALIDARG, as well as the following:

S_OK

The advisory connection was created.

Remarks

Through the connection established through this method, the advisory sink can receive future notifications in a call to IAdviseSink::OnDataChange.

An object issues a call to IDataObject::DAdvise to request notification on changes to the format, medium, or target device of interest. This data is specified in the pFormatetc parameter. The DAdvise method is usually implemented to call IDataAdviseHolder::Advise to delegate the task of setting up and tracking a connection to the advise holder. When the format, medium, or target device in question changes, the data object calls IDataAdviseHolder::SendOnDataChange to send the necessary notifications.

The established connection can be deleted by passing the value in pdwConnection in a call to IDataAdviseHolder::Unadvise.

See also

ADVF, CreateDataAdviseHolder, FORMATETC, IDataAdviseHolder::Unadvise, IDataObject::DAdvise


IDataAdviseHolder::EnumAdvise

Returns a pointer to an IEnumStatdata interface on an enumeration object that can be used to enumerate the current advisory connections.

HRESULT EnumAdvise(

IEnumSTATDATA ** ppenumAdvise	//Indirect pointer on the new enumerator object
);
Parameter

ppenumAdvise

[out] Indirect pointer to the IEnumStatdata interface on the new enumerator object. If this value is NULL, there are no connections to advise sinks at this time.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The enumerator object is successfully instantiated or there are no connections.

Remarks

This method must supply a pointer to an implementation of the IEnumSTATDATA interface, one of the standard enumerator interfaces that contain the Next, Reset, Clone, and Skip methods, on an enumerator object. Its methods allow you to enumerate the data stored in an array of STATDATA structures. You get a pointer to the OLE implementation of IDataAdviseHolder through a call to CreateDataAdviseHolder, and then call IDataAdviseHolder::EnumAdvise to implement IDataObject::EnumDAdvise.

Adding more advisory connections while the enumerator object is active has an undefined effect on the enumeration that results from this method.

See Also

IEnumXXXX, IEnumSTATDATA, IDataObject::EnumDAdvise


IDataAdviseHolder::SendOnDataChange

Sends notifications to each advise sink for which there is a connection established by calling the IAdviseSink::OnDataChange method for each advise sink currently being handled by this instance of the advise holder object.

HRESULT SendOnDataChange(

IDataObject * pDataObject,	//Pointer to the data object that has changed
DWORD dwReserved,	//Reserved
DWORD advf	//Advise flags
);
Parameters

pDataObject

[in] Pointer to the IDataObject interface on the data object in which the data has just changed. This pointer is used in subsequent calls to IAdviseSink::OnDataChange.

dwReserved

[in] Reserved for future use; must be zero.

advf

[in] Container for advise flags that specify how the call to IAdviseSink::OnDataChange is made. These flag values are from the enumeration ADVF. Typically, the value for advf is NULL. The only exception occurs when the data object is shutting down and must send a final notification that includes the actual data to sinks that have specified ADVF_DATAONSTOP and ADVF_NODATA in their call to IDataObject::DAdvise. In this case, advf contains ADVF_DATAONSTOP.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The call to IAdviseSink::OnDataChange was made.

Remarks

The data object must call this method when it detects a change that would be of interest to an advise sink that has previously requested notification.

Most notifications include the actual data with them. The only exception is if the ADVF_NODATA flag was previously specified when the connection was initially set up in the IDataAdviseHolder::Advise method.

Before calling the IAdviseSink::OnDataChange method for each advise sink, this method obtains the actual data by calling the IDataObject::GetData method through the pointer specified in the pDataObject parameter.

See Also

ADVF, IAdviseSink::OnDataChange


IDataAdviseHolder::Unadvise

Removes a connection between a data object and an advisory sink that was set up through a previous call to IDataAdviseHolder::Advise. IDataAdviseHolder::Unadvise is typically called in the implementation of IDataObject::DUnadvise.

HRESULT Unadvise(

DWORD dwConnection	//Connection to remove
);
Parameter

dwConnection

[in] DWORD token that specifies the connection to remove. This value was returned by IDataAdviseHolder::Advise when the connection was originally established.

Return Values

S_OK

The specified connection was successfully deleted.

OLE_E_NOCONNECTION

The specified dwConnection is not a valid connection.

See Also

IDataAdviseHolder::Advise, IDataObject::DUnadvise


IDataObject

The IDataObject interface specifies methods that enable data transfer and notification of changes in data. Data transfer methods specify the format of the transferred data along with the medium through which the data is to be transferred. Optionally, the data can be rendered for a specific target device. In addition to methods for retrieving and storing data, the IDataObject interface specifies methods for enumerating available formats and managing connections to advisory sinks for handling change notifications.

The term “data object” is used to mean any object that supports an implementation of the IDataObject interface. Implementations vary, depending on what the data object is required to do; in some data objects, the implementation of certain methods not supported by the object could simply be the return of E_NOTIMPL. For example, some data objects do not allow callers to send them data. Other data objects do not support advisory connections and change notifications. However, for those data objects that do support change notifications, OLE provides an object called a data advise holder. An interface pointer to this holder is available through a call to the helper function CreateDataAdviseHolder. A data object can have multiple connections, each with its own set of attributes. The OLE data advise holder simplifies the task of managing these connections and sending the appropriate notifications.

When to Implement

Implement the IDataObject interface if you are developing a container or server application that is capable of transferring data. For example, if your application allows its data to be pasted or dropped into another application, you must implement the IDataObject interface. OLE compound document object servers that support objects that can be embedded or linked must implement IDataObject.

OLE provides implementations in its default object handler and its cache.

When to Use

Any object that can receive data calls the methods in the IDataObject interface.

When you call the data transfer methods in the IDataObject interface, you specify a format, a medium, and, optionally, a target device for which the data should be rendered. Objects, such as containers, that want to be notified through their advise sinks when the data in the data object changes call the IDataObject advisory methods to set up an advisory connection through which notifications can be sent.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IDataObject Methods	Description
GetData	Renders the data described in a FORMATETC structure and transfers it through the STGMEDIUM structure.
GetDataHere	Renders the data described in a FORMATETC structure and transfers it through the STGMEDIUM structure allocated by the caller.
QueryGetData	Determines whether the data object is capable of rendering the data described in the FORMATETC structure.
GetCanonicalFormatEtc	Provides a potentially different but logically equivalent FORMATETC structure.
SetData	Provides the source data object with data described by a FORMATETC structure and an STGMEDIUM structure.
EnumFormatEtc	Creates and returns a pointer to an object to enumerate the FORMATETC supported by the data object.
DAdvise	Creates a connection between a data object and an advise sink so the advise sink can receive notifications of changes in the data object.
DUnadvise	Destroys a notification previously set up with the DAdvise method.
EnumDAdvise	Creates and returns a pointer to an object to enumerate the current advisory connections.


IDataObject::DAdvise

Called by an object supporting an advise sink to create a connection between a data object and the advise sink. This enables the advise sink to be notified of changes in the data of the object.

HRESULT DAdvise(

FORMATETC * pFormatetc,	//Pointer to data of interest to the advise sink
DWORD advf,	//Flags that specify how the notification takes place
IAdviseSink * pAdvSink,	//Pointer to the advise sink
DWORD * pdwConnection	//Pointer to a token that identifies this connection
);
Parameters

pFormatetc

[in] Pointer to a FORMATETC structure that defines the format, target device, aspect, and medium that will be used for future notifications. For example, one sink may want to know only when the bitmap representation of the data in the the data object changes. Another sink may be interested in only the metafile format of the same object. Each advise sink is notified when the data of interest changes. This data is passed back to the advise sink when notification occurs.

advf

[in] DWORD that specifies a group of flags for controlling the advisory connection. Valid values are from the enumeration ADVF. However, only some of the possible ADVF values are relevant for this method. The following table briefly describes the relevant values. Refer to ADVF for a more detailed description.

ADVF Value	Description
ADVF_NODATA	Asks the data object to avoid sending data with the notifications. Typically data is sent. This flag is a way to override the default behavior. When ADVF_NODATA is used, the TYMED member of the STGMEDIUM structure that is passed to OnDataChange will usually contain TYMED_NULL. The caller can then retrieve the data with a subsequent IDataObject::GetData call.
ADVF_ONLYONCE	Causes the advisory connection to be destroyed after the first change notification is sent. An implicit call to IDataObject::DUnadvise is made on behalf of the caller to remove the connection.
ADVF_PRIMEFIRST	Asks for an additional initial notification. The combination of ADVF_ONLYONCE and ADVF_PRIMEFIRST provides, in effect, an asynchronous IDataObject::GetData call.
ADVF_DATAONSTOP	When specified with ADVF_NODATA, this flag causes a last notification with the data included to to be sent before the data object is destroyed. If used without ADVF_NODATA, IDataObject::DAdvise can be implemented in one of the following ways:
	•   the ADVF_DATAONSTOP can be ignored.
	•   the object can behave as if ADVF_NODATA was specified.
	•   a change notification is sent only in the shutdown case. Data changes prior to shutdown do not cause a notification to be sent.
pAdvSink

[in] Pointer to the IAdviseSink interface on the advisory sink that will receive the change notification.

pdwConnection

[out] Pointer to a DWORD token that identifies this connection. You can use this token later to delete the advisory connection (by passing it to IDataObject::DUnadvise). If this value is zero, the connection was not established.

Return Values

This method supports the standard return values E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK

The advisory connection was created.

E_NOTIMPL

This method is not implemented on the data object.

DV_E_LINDEX

Invalid value for lindex; currently, only -1 is supported.

DV_E_FORMATETC

Invalid value for pFormatetc.

OLE_E_ADVISENOTSUPPORTED

The data object does not support change notification.

Remarks

IDataObject::DAdvise creates a change notification connection between a data object and the caller. The caller provides an advisory sink to which the notifications can be sent when the object’s data changes.

Objects used simply for data transfer typically do not support advisory notifications and return OLE_E_ADVISENOTSUPPORTED from IDataObject::DAdvise.

Notes to Callers

The object supporting the advise sink calls IDataObject::DAdvise to set up the connection, specifying the format, aspect, medium, and/or target device of interest in the FORMATETC structure passed in. If the data object does not support one or more of the requested attributes or the sending of notifications at all, it can refuse the connection by returning OLE_E_ADVISENOTSUPPORTED.

Containers of linked objects can set up advisory connections directly with the bound link source or indirectly through the standard OLE link object that manages the connection. Connections set up with the bound link source are not automatically deleted. The container must explicitly call IDataObject::DUnAdvise on the bound link source to delete an advisory connection. The OLE link object, manipulated through the IOleLink interface, is implemented in the default handler. Connections set up through the OLE link object are destroyed when the link object is deleted.

The OLE default link object creates a “wildcard advise” with the link source so OLE can maintain the time of last change. This advise is specifically used to note the time that anything changed. OLE ignores all data formats that may have changed, noting only the time of last change. To allow wildcard advises, set the FORMATETC members as follows before calling IDataObject::DAdvise:

cf == 0;

ptd == NULL;

dwAspect ==-1;

lindex == -1

tymed == -1;

The advise flags should also include ADVF_NODATA. Wildcard advises from OLE should always be accepted by applications.

Notes to Implementers

To simplify the implementation of DAdvise and the other notification methods in IDataObject (DUnadvise and EnumAdvise) that supports notification, OLE provides an advise holder object that manages the registration and sending of notifications. To get a pointer to this object, call the helper function CreateDataAdviseHolder on the first invocation of DAdvise. This supplies a pointer to the object’s IDataAdviseHolder interface. Then, delegate the call to the IDataAdviseHolder::Advise method in the data advise holder, which creates, and subsequently manages, the requested connection.

See Also

ADVF, FORMATETC, CreateDataAdviseHolder, IAdviseSink::OnDataChange, IDataObject::DUnAdvise


IDataObject::DUnadvise

Destroys a notification connection that had been previously set up.

HRESULT DUnadvise(

DWORD dwConnection	//Connection to remove
);
Parameter

dwConnection

[in] DWORD token that specifies the connection to remove. Use the value returned by IDataObject::DAdvise when the connection was originally established.

Return Values

S_OK

The specified connection was successfully deleted.

OLE_E_NOCONNECTION

The specified dwConnection is not a valid connection.

OLE_E_ADVISENOTSUPPORTED

This IDataObject implementation does not support notification.

Remarks

This methods destroys a notification created with a call to the IDataObject::DAdvise method.

If the advisory connection being deleted was initially set up by delegating the IDataObject::DAdvise call to IDataAdviseHolder::Advise, you must delegate this call to IDataAdviseHolder::Unadvise to delete it.

See Also

IDataObject::DAdvise, IDataAdviseHolder::Unadvise


IDataObject::EnumDAdvise

Creates an object that can be used to enumerate the current advisory connections.

HRESULT EnumDAdvise(

IEnumSTATDATA ** ppenumAdvise	//Indirect pointer
);
Parameter

ppenumAdvise

[out] Indirect pointer to the IEnumSTATDATA interface on the new enumerator object. If the supplied value is NULL, there are no connections to advise sinks at this time.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The enumerator object is successfully instantiated or there are no connections.

OLE_E_ADVISENOTSUPPORTED

Advisory notifications are not supported by this object.

Remarks

The enumerator object created by this method implements the IEnumSTATDATA interface, one of the standard enumerator interfaces that contain the Next, Reset, Clone, and Skip methods. IEnumSTATDATA permits the enumeration of the data stored in an array of STATDATA structures. Each of these structures provides information on a single advisory connection, and includes FORMATETC and ADVF information, as well as the pointer to the advise sink and the token representing the connection.

Notes to Callers

After getting a pointer through this method, the data object can call the appropriate enumeration methods. While the enumeration is in progress, the effect of adding more advisory connections on the subsequent enumeration is undefined.

Notes to Implementers

It is recommended that you use the OLE data advise holder object to handle advisory connections. With the pointer obtained through a call to CreateDataAdviseHolder, implementing IDataObject::EnumDAdvise becomes a simple matter of delegating the call to IDataAdviseHolder::EnumAdvise. This creates the enumerator and supplies the pointer to the OLE implementation of IEnumSTATDATA. At that point, you can call its methods to enumerate the current advisory connections.

See Also

IEnumSTATDATA, IDataAdviseHolder::EnumAdvise


IDataObject::EnumFormatEtc

Creates an object for enumerating the FORMATETC structures for a data object. These structures are used in calls to IDataObject::GetData or IDataObject::SetData.

HRESULT EnumFormatEtc(

DWORD dwDirection,	//Specifies a value from the enumeration DATADIR
IEnumFORMATETC ** ppenumFormatetc	//Indirect pointer to the new enumerator object
);
Parameters

dwDirection

[in] Direction of the data through a value from the enumeration DATADIR.

typedef enum tagDATADIR

{

    DATADIR_GET = 1,

    DATADIR_SET = 2,

} DATADIR;

The value DATADIR_GET enumerates the formats that can be passed in to a call to IDataObject::GetData. The value DATADIR_SET enumerates those formats that can be passed in to a call to IDataObject::SetData.

ppenumFormatetc

[out] Indirect pointer to the IEnumFORMATETC interface on the new enumerator object.

Return Values

This method supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

S_OK

Enumerator object was successfully created.

E_NOTIMPL

The direction specified by dwDirection is not supported.

OLE_S_USEREG

Requests that OLE enumerate the formats from the registry.

Remarks

IDataObject::EnumFormatEtc creates an enumerator object that can be used to determine all of the ways the data object can describe data in a FORMATETC structure, and supplies a pointer to its IEnumFORMATETC interface. This is one of the standard enumerator interfaces.

Notes to Callers

Having obtained the pointer, the caller can enumerate the FORMATETC structures by calling the enumeration methods of IEnumFORMATETC. Because the formats can change over time, there is no guarantee that an enumerated format is currently supported because the formats can change over time. Accordingly, applications should treat the enumeration as a hint of the format types that can be passed. The caller is responsible for calling IEnumFormatEtc::Release when it is finished with the enumeration.

IDataObject::EnumFormatEtc is called when one of the following actions occurs:

•	An application calls OleSetClipboard. OLE must determine what data to place on the Clipboard and whether it is necessary to put OLE 1 compatibility formats on the Clipboard.

•	Data is being pasted from the Clipboard or dropped. An application uses the first acceptable format.

•	The Paste Special dialog box is displayed. The target application builds the list of formats from the FORMATETC entries.

Notes to Implementers

Formats can be registered statically in the registry or dynamically during object initialization. If an object has an unchanging list of formats and these formats are registered in the registry, OLE provides an implementation of a FORMATETC enumeration object that can enumerate formats registered under a specific CLSID in the registry. A pointer to its IEnumFORMATETC interface is available through a call to the helper function OleRegEnumFormatEtc. In this situation, therefore, you can implement the EnumFormatEtc method simply with a call to this function.

EXE applications can effectively do the same thing by implementing the method to return the value OLE_S_USEREG. This return value instructs the default object handler to call OleRegEnumFormatEtc. Object applications that are implemented as DLL object applications cannot return OLE_S_USEREG, so must call OleRegEnumFormatEtc directly.

Private formats can be enumerated for OLE 1 objects, if they are registered with the RequestDataFormats or SetDataFormats keys in the registry. Also, private formats can be enumerated for OLE objects (all versions after OLE 1), if they are registered with the GetDataFormats or SetDataFormats keys.

For OLE 1 objects whose servers do not have RequestDataFormats or SetDataFormats information registered in the registry, a call to IDataObject::EnumFormatEtc passing DATADIR_GET only enumerates the Native and Metafile formats, regardless of whether they support these formats or others. Calling EnumFormatEtc passing DATADIR_SET on such objects only enumerates Native, regardless of whether the object supports being set with other formats.

The FORMATETC structure returned by the enumeration usually indicates a NULL target device (ptd). This is appropriate because, unlike the other members of FORMATETC, the target device does not participate in the object’s decision as to whether it can accept or provide the data in either a SetData or GetData call.

The TYMED member of FORMATETC often indicates that more than one kind of storage medium is acceptable. You should always mask and test for this by using a Boolean OR operator.

See Also

FORMATETC, OleRegEnumFormatEtc, IEnumFormatEtc, IDataObject::SetData, IDataObject::GetData


IDataObject::GetCanonicalFormatEtc

Provides a standard FORMATETC structure that is logically equivalent to one that is more complex. You use this method to determine whether two different FORMATETC structures would return the same data, removing the need for duplicate rendering.

HRESULT GetCanonicalFormatEtc(

FORMATETC * pFormatetcIn,	//Pointer to the FORMATETC structure
FORMATETC * pFormatetcOut	//Pointer to the canonical equivalent FORMATETC structure
);
Parameters

pFormatetcIn

[in] Pointer to the FORMATETC structure that defines the format, medium, and target device that the caller would like to use to retrieve data in a subsequent call such as IDataObject::GetData. The TYMED member is not significant in this case and should be ignored.

pFormatetcOut

[out] Pointer to a FORMATETC structure that contains the most general information possible for a specific rendering, making it canonically equivalent to pFormatetcIn. The caller must allocate this structure and the GetCanonicalFormatEtc method must fill in the data. To retrieve data in a subsequent call like IDataObject::GetData, the caller uses the supplied value of pFormatetcOut, unless the value supplied is NULL. This value is NULL if the method returns DATA_S_SAMEFORMATETC. The TYMED member is not significant in this case and should be ignored.

Return Values

This method supports the standard return values E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK

The returned FORMATETC structure is different from the one that was passed.

DATA_S_SAMEFORMATETC

The FORMATETC structures are the same and NULL is returned in pFormatetcOut.

DV_E_LINDEX

Invalid value for lindex; currently, only -1 is supported.

DV_E_FORMATETC

Invalid value for pFormatetc.

OLE_E_NOTRUNNING

Object application is not running.

Remarks

If a data object can supply exactly the same data for more than one requested FORMATETC structure, IDataObject::GetCanonicalFormatEtc can supply a “canonical”, or standard FORMATETC that gives the same rendering as a set of more complicated FORMATETC structures. For example, it is common for the data returned to be insensitive to the target device specified in any one of a set of otherwise similar FORMATETC structures.

Notes to Callers

A call to this method can determine whether two calls to IDataObject::GetData on a data object, specifying two different FORMATETC structures, would actually produce the same renderings, thus eliminating the need for the second call and improving performance. If the call to GetCanonicalFormatEtc results in a canonical format being written to the pFormatetcOut parameter, the caller then uses that structure in a subsequent call to IDataObject::GetData.

Notes to Implementers

Conceptually, it is possible to think of FORMATETC structures in groups defined by a canonical FORMATETC that provides the same results as each of the group members. In constructing the canonical FORMATETC, you should make sure it contains the most general information possible that still produces a specific rendering.

For data objects that never provide device-specific renderings, the simplest implementation of this method is to copy the input FORMATETC to the output FORMATETC, store a NULL in the ptd field of the output FORMATETC, and return DATA_S_SAMEFORMATETC.

See Also

IDataObject::GetData, FORMATETC


IDataObject::GetData

Called by a data consumer to obtain data from a source data object. The GetData method renders the data described in the specified FORMATETC structure and transfers it through the specified STGMEDIUM structure. The caller then assumes responsibility for releasing the STGMEDIUM structure.

HRESULT GetData(

FORMATETC * pFormatetc,	//Pointer to the FORMATETC structure
STGMEDIUM * pmedium	//Pointer to the STGMEDIUM structure
);
Parameters

pFormatetc

[in] Pointer to the FORMATETC structure that defines the format, medium, and target device to use when passing the data. It is possible to specify more than one medium by using the Boolean OR operator, allowing the method to choose the best medium among those specified.

pmedium

[out] Pointer to the STGMEDIUMstructure that indicates the storage medium containing the returned data through its tymed member, and the responsibility for releasing the medium through the value of its punkOuter member. If punkForRelease is NULL, the receiver of the medium is responsible for releasing it; otherwise, punkForRelease points to the IUnknown on the appropriate object so its Release method can be called. The medium must be allocated and filled in by IDataObject::GetData.

Return Values

This method supports the standard return values E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK

Data was successfully retrieved and placed in the storage medium provided.

DV_E_LINDEX

Invalid value for lindex; currently, only -1 is supported.

DV_E_FORMATETC

Invalid value for pFormatetc.

DV_E_TYMED

Invalid tymed value.

DV_E_DVASPECT

Invalid dwAspect value.

OLE_E_NOTRUNNING

Object application is not running.

STG_E_MEDIUMFULL

An error occurred when allocating the medium.

Remarks

A data consumer calls IDataObject::GetData to retrieve data from a data object, conveyed through a storage medium (defined through the STGMEDIUM structure).

Notes to Callers

You can specify more than one acceptable TYMED medium with the Boolean OR operator. IDataObject::GetData must choose from the OR’d values the medium that best represents the data, do the allocation, and indicate responsibility for releasing the medium.

Data transferred across a stream extends from position zero of the stream pointer through to the position immediately before the current stream pointer (that is, the stream pointer position upon exit).

Notes to Implementers

IDataObject::GetData must check all fields in the FORMATETC structure. It is important that IDataObject::GetData render the requested aspect and, if possible, use the requested medium. If the data object cannot comply with the information specified in the FORMATETC, the method should return DV_E_FORMATETC. If an attempt to allocate the medium fails, the method should return STG_E_MEDIUMFULL. It is important to fill in all of the fields in the STGMEDIUM structure.

Although the caller can specify more than one medium for returning the data, IDataObject::GetData can supply only one medium. If the initial transfer fails with the selected medium, this method can be implemented to try one of the other media specified before returning an error.

See Also

IDataObject::GetDataHere, IDataObject::SetData, FORMATETC, STGMEDIUM


IDataObject::GetDataHere

Called by a data consumer to obtain data from a source data object. This method differs from the GetData method in that the caller must allocate and free the specified storage medium.

HRESULT GetDataHere(

FORMATETC * pFormatetc,	//Pointer to the FORMATETC structure
STGMEDIUM * pmedium	//Pointer to the STGMEDIUM structure
);
Parameters

pFormatetc

[in] Pointer to the FORMATETC structure that defines the format, medium, and target device to use when passing the data. Only one medium can be specified in TYMED, and only the following TYMED values are valid: TYMED_STORAGE, TYMED_STREAM, TYMED_HGLOBAL, or TYMED_FILE.

pmedium

[out] Pointer to the STGMEDIUM structure that defines the storage medium containing the data being transferred. The medium must be allocated by the caller and filled in by IDataObject::GetDataHere. The caller must also free the medium. The implementation of this method must always supply a value of NULL for the punkForRelease member of the STGMEDIUM structure to which this parameter points.

Return Values

This method supports the standard return values E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK

Data was successfully retrieved and placed in the storage medium provided.

DV_E_LINDEX

Invalid value for lindex; currently, only -1 is supported.

DV_E_FORMATETC

Invalid value for pFormatetc.

DV_E_TYMED

Invalid tymed value.

DV_E_DVASPECT

Invalid dwAspect value.

OLE_E_NOTRUNNING

Object application is not running.

STG_E_MEDIUMFULL

The medium provided by the caller is not large enough to contain the data.

Remarks

The IDataObject::GetDataHere method is similar to IDataObject::GetData, except that the caller must both allocate and free the medium specified in pmedium. GetDataHere renders the data described in a FORMATETC structure and copies the data into that caller-provided STGMEDIUM structure. For example, if the medium is TYMED_HGLOBAL, this method cannot resize the medium or allocate a new hGlobal.

Some media are not appropriate in a call to GetDataHere, including GDI types such as metafiles. The GetDataHere method cannot put data into a caller-provided metafile. In general, the only storage media it is necessary to support in this method are TYMED_ISTORAGE, TYMED_ISTREAM, and TYMED_FILE.

When the transfer medium is a stream, OLE makes assumptions about where the data is being returned and the position of the stream’s seek pointer. In a GetData call, the data returned is from stream position zero through just before the current seek pointer of the stream (that is, the position on exit). For GetDataHere, the data returned is from the stream position on entry through just before the position on exit.

See Also

IDataObject::GetData, FORMATETC, STGMEDIUM


IDataObject::QueryGetData

Determines whether the data object is capable of rendering the data described in the FORMATETC structure. Objects attempting a paste or drop operation can call this method before calling IDataObject::GetData to get an indication of whether the operation may be successful.

HRESULT QueryGetData(

FORMATETC * pFormatetc	//Pointer to the FORMATETC structure
);
Parameter

pFormatetc

[in] Pointer to the FORMATETC structure defining the format, medium, and target device to use for the query.

Return Values

This method supports the standard return values E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK

Subsequent call to IDataObject::GetData would probably be successful.

DV_E_LINDEX

Invalid value for lindex; currently, only -1 is supported.

DV_E_FORMATETC

Invalid value for pFormatetc.

DV_E_TYMED

Invalid tymed value.

DV_E_DVASPECT

Invalid dwAspect value.

OLE_E_NOTRUNNING

Object application is not running.

Remarks

The client of a data object calls IDataObject::QueryGetData to determine whether passing the specified FORMATETC structure to a subsequent call to IDataObject::GetData is likely to be successful. A successful return from this method does not necessarily ensure the success of the subsequent paste or drop operation.

See Also

IDataObject::GetData, FORMATETC


IDataObject::SetData

Called by an object containing a data source to transfer data to the object that implements this method.

HRESULT SetData(

FORMATETC * pFormatetc,	//Pointer to the FORMATETC structure
STGMEDIUM * pmedium,	//Pointer to STGMEDIUM structure
BOOL fRelease	//Indicates which object owns the storage medium after the call is completed
);
Parameters

pFormatetc

[in] Pointer to the FORMATETC structure defining the format used by the data object when interpreting the data contained in the storage medium.

pmedium

[in] Pointer to the STGMEDIUM structure defining the storage medium in which the data is being passed.

fRelease

[in] If TRUE, the data object called, which implements IDataObject::SetData, owns the storage medium after the call returns. This means it must free the medium after it has been used by calling the ReleaseStgMedium function. If FALSE, the caller retains ownership of the storage medium and the data object called uses the storage medium for the duration of the call only.

Return Values

This method supports the standard return values E_FAIL, E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK

Data was successfully transferred.

E_NOTIMPL

This method is not implemented for the data object.

DV_E_LINDEX

Invalid value for lindex; currently, only -1 is supported.

DV_E_FORMATETC

Invalid value for pFormatetc.

DV_E_TYMED

Invalid tymed value.

DV_E_DVASPECT

Invalid dwAspect value.

OLE_E_NOTRUNNING

Object application is not running.

Remarks

IDataObject::SetData allows another object to attempt to send data to the implementing data object. A data object implements this method if it supports receiving data from another object. If it does not support this, it should be implemented to return E_NOTIMPL.

The caller allocates the storage medium indicated by the pmedium, in which the data is passed. The data object called does not take ownership of the data until it has successfully received it and no error code is returned. The value of the fRelease parameter indicates the ownership of the medium after the call returns. FALSE indicates the caller still owns the medium, and the data object only has the use of it during the call; TRUE indicates that the data object now owns it and must release it when it is no longer needed.

The type of medium (TYMED) specified in the pformatetc and pmedium parameters must be the same. For example, one cannot be an hGlobal (global handle) and the other a stream.

See Also

IDataObject::GetData, FORMATETC, STGMEDIUM


IDropSource

The IDropSource interface is one of the interfaces you implement to provide drag-and-drop operations in your application. It contains methods used in any application used as a data source in a drag-and-drop operation. The data source application in a drag-and-drop operation is responsible for:

•	Determining the data being dragged based on the user’s selection.

•	Initiating the drag-and-drop operation based on the user’s mouse actions.

•	Generating some of the visual feedback during the drag-and-drop operation, such as setting the cursor and highlighting the data selected for the drag-and-drop operation.

•	Canceling or completing the drag-and-drop operation based on the user’s mouse actions.

•	Performing any action on the original data caused by the drop operation, such as deleting the data on a drag move.

IDropSource contains the methods for generating visual feedback to the end user and for canceling or completing the drag-and-drop operation. You also need to call the DoDragDrop, RegisterDragDrop, and RevokeDragDrop functions in drag-and-drop operations.

When to Implement

Implement IDropSource if you are developing a container or server application that can act as a data source for a drag-and-drop operation. The IDropSource interface is only required during the drag-and-drop operation.

If you implement the IDropSource interface, you must also implement the IDataObject interface on the same object to represent the data being transferred.

You can use the same implementation of IDataObject for drag-and-drop data as for the data object offered to the clipboard. Once you have implemented clipboard operations in your application, you can add drag-and-drop operations with only a little extra work.

When to Use

You don’t usually call IDropSource methods directly. Instead, your data source calls the DoDragDrop function when it detects that the user has initiated a drag-and-drop operation. Then, DoDragDrop calls the IDropSource methods during the drag-and-drop operation.

For example, DoDragDrop calls IDropSource::GiveFeedback when you need to change the cursor shape or when you need to provide some other visual feedback. DoDragDrop calls IDropSource::QueryContinueDrag when there is a change in the mouse button state to determine if the drag-and-drop operation was canceled or completed.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IDropSource Methods	Description
QueryContinueDrag	Determines whether a drag-and-drop operation should continue.
GiveFeedback	Gives visual feedback to an end user during a drag-and-drop operation.
See Also

DoDragDrop, IDataObject, IDropTarget


IDropSource::GiveFeedback

Enables a source application to give visual feedback to the end user during a drag-and-drop operation by providing the DoDragDrop function with an enumeration value specifying the visual effect.

HRESULT GiveFeedback(

DWORD dwEffect	//Effect of a drop operation
);
Parameter

dwEffect

[in] The DROPEFFECT value returned by the most recent call to IDropTarget::DragEnter, IDropTarget::DragOver, or IDropTarget::DragLeave. For a list of values, see the DROPEFFECT enumeration.

Return Values

This method supports the standard return values E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK

The method completed its task successfully, using the cursor set by the source application.

DRAGDROP_S_USEDEFAULTCURSORS

Indicates successful completion of the method, and requests OLE to update the cursor using the OLE-provided default cursors.

Remarks

When your application detects that the user has started a drag-and-drop operation, it should call the DoDragDrop function. DoDragDrop enters a loop, calling IDropTarget::DragEnter when the mouse first enters a drop target window, IDropTarget::DragOver when the mouse changes its position within the target window, and IDropTarget::DragLeave when the mouse leaves the target window.

For every call to either IDropTarget::DragEnter or IDropTarget::DragOver, DoDragDrop calls IDropSource::GiveFeedback, passing it the DROPEFFECT value returned from the drop target call.

DoDragDrop calls IDropTarget::DragLeave when the mouse has left the target window. Then, DoDragDrop calls IDropSource::GiveFeedback and passes the DROPEFFECT_NONE value in the dwEffect parameter.

The dwEffect parameter can include DROPEFFECT_SCROLL, indicating that the source should put up the drag-scrolling variation of the appropriate pointer.

OLE defines a recommended set of cursor shapes that your application should use. See the User Interface Guidelines for more information.

Notes to Implementers

This function is called frequently during the DoDragDrop loop, so you can gain performance advantages if you optimize your implementation as much as possible.

IDropSource::GiveFeedback is responsible for changing the cursor shape or for changing the highlighted source based on the value of the dwEffect parameter. If you are using default cursors, you can return DRAGDROP_S_USEDEFAULTCURSORS, which causes OLE to update the cursor for you, using its defaults.

See Also

DoDragDrop, IDropTarget


IDropSource::QueryContinueDrag

Determines whether a drag-and-drop operation should be continued, canceled, or completed. You do not call this method directly. The OLE DoDragDrop function calls this method during a drag-and-drop operation.

HRESULT QueryContinueDrag(

BOOL fEscapePressed,	//Status of escape key since previous call
DWORD grfKeyState	//Current state of keyboard modifier keys
);
Parameters

fEscapePressed

[in] Specifies whether the Esc key has been pressed since the previous call to IDropSource::QueryContinueDrag or to DoDragDrop if this is the first call to QueryContinueDrag. A TRUE value indicates the end user has pressed the escape key; a FALSE value indicates it has not been pressed.

grfKeyState

[in] Current state of the keyboard modifier keys on the keyboard. Valid values can be a combination of any of the flags MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON.

Return Values

This method supports the standard return values E_UNEXPECTED and E_OUTOFMEMORY, as well as the following:

S_OK

The drag operation should continue. This result occurs if no errors are detected, the mouse button starting the drag-and-drop operation has not been released, and the Esc key has not been detected.

DRAGDROP_S_DROP

The drop operation should occur completing the drag operation. This result occurs if grfKeyState indicates that the key that started the drag-and-drop operation has been released.

DRAGDROP_S_CANCEL

The drag operation should be canceled with no drop operation occurring. This result occurs if fEscapePressed is TRUE, indicating the Esc key has been pressed.

Remarks

The DoDragDrop function calls IDropSource::QueryContinueDrag whenever it detects a change in the keyboard or mouse button state during a drag-and-drop operation. IDropSource::QueryContinueDrag must determine whether the drag-and-drop operation should be continued, canceled, or completed based on the contents of the parameters grfKeyState and fEscapePressed.

See Also

DoDragDrop


IDropTarget

The IDropTarget interface is one of the interfaces you implement to provide drag-and-drop operations in your application. It contains methods used in any application that can be a target for data during a drag-and-drop operation. A drop-target application is responsible for:

•	Determining the effect of the drop on the target application.

•	Incorporating any valid dropped data when the drop occurs.

•	Communicating target feedback to the source so the source application can provide appropriate visual feedback such as setting the cursor.

•	Implementing drag scrolling.

•	Registering and revoking its application windows as drop targets.

The IDropTarget interface contains methods that handle all these responsibilities except registering and revoking the application window as a drop target, for which you must call the RegisterDragDrop and the RevokeDragDrop functions.

When to Implement

Implement the IDropTarget interface if you are developing an application that can act as a target for a drag-and-drop operation. The IDropTarget interface is associated with your application windows and is implemented on your window objects. Call the RegisterDragDrop function to register your window objects as drop targets.

When to Use

You do not call the methods of IDropTarget directly. The DoDragDrop function calls the IDropTarget methods during the drag-and-drop operation.

For example, DoDragDrop calls IDropTarget::DragEnter when it detects the mouse has moved over a window that is registered as a drag target. Once the mouse has entered a drag-target window, DoDragDrop calls IDropTarget::DragOver as the mouse moves through the window and calls IDropTarget::DragLeave if the mouse leaves the target window or if the user cancels or completes the drag-and-drop operation. DoDragDrop calls IDropTarget::Drop if the drop finally occurs.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IDropTarget Methods	Description
DragEnter	Determines whether a drop can be accepted and its effect if it is accepted.
DragOver	Provides target feedback to the user through the DoDragDrop function.
DragLeave	Causes the drop target to suspend its feedback actions.
Drop	Drops the data into the target window.
See Also

DoDragDrop, IDropSource, RegisterDragDrop, RevokeDragDrop


IDropTarget::DragEnter

Indicates whether a drop can be accepted, and, if so, the effect of the drop.

HRESULT DragEnter(

IDataObject * pDataObject,	//Pointer to the interface of the source data object’
DWORD grfKeyState,	//Current state of keyboard modifier keys
POINTL pt,	//Pointer to the current cursor coordinates
DWORD * pdwEffect	//Pointer to the effect of the drag-and-drop operation
);
Parameters

pDataObject

[in] Pointer to the IDataObject interface on the data object. This data object contains the data being being transferred in the drag-and-drop operation. If the drop occurs, this data object will be incorporated into the target.

grfKeyState

[in] Current state of the keyboard modifier keys on the keyboard. Valid values can be a combination of any of the flags MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON.

pt

[in] Pointer to the current cursor coordinates in the coordinate space of the drop-target window.

pdwEffect

[in, out] On entry, pointer to the value of the pdwEffect parameter of the DoDragDrop function. On return, must contain one of the effect flags from the DROPEFFECT enumeration, which indicates what the result of the drop operation would be.

Return Values

This method supports the standard return values E_OUTOFMEMORY, E_INVALIDARG, and E_UNEXPECTED, as well as the following:

S_OK

The method completed its task successfully.

Remarks

You do not call IDropTarget::DragEnter directly; instead the DoDragDrop function calls it to determine the effect of a drop the first time the user drags the mouse into the registered window of a drop target.

To implement IDropTarget::DragEnter, you must determine whether the target can use the data in the source data object by checking three things:

•	The format and medium specified by the data object

•	The input value of pdwEffect

•	The state of the modifier keys

To check the format and medium, use the IDataObject pointer passed in the pDataObject parameter to call IDataObject::EnumFormatEtc so you can enumerate the FORMATETC structures the source data object supports. Then call IDataObject::QueryGetData to determine whether the data object can render the data on the target by examining the formats and medium specified for the data object.

On entry to IDropTarget::DragEnter, the pdwEffect parameter is set to the effects given to the pdwOkEffect parameter of the DoDragDrop function. The IDropTarget::DragEnter method must choose one of these effects or disable the drop.

The following modifier keys affect the result of the drop:

Key Combination	User-Visible Feedback	Drop Effect
CTRL + SHIFT	=	DROPEFFECT_LINK
CTRL	+	DROPEFFECT_COPY
No keys or SHIFT	None	DROPEFFECT_MOVE
On return, the method must write the effect, one of the members of the DROPEFFECT enumeration, to the pdwEffect parameter. DoDragDrop then takes this parameter and writes it to its pdwEffect parameter. You communicate the effect of the drop back to the source through DoDragDrop in the pdwEffect parameter. The DoDragDrop function then calls IDropSource::GiveFeedback so that the source application can display the appropriate visual feedback to the user through the target window.

See Also

DoDragDrop, IDropSource, IDropTarget, RegisterDragDrop, RevokeDragDrop


IDropTarget::DragLeave

Removes target feedback and releases the data object.

HRESULT DragLeave(void);

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The method completed its task successfully.

Remarks

You do not call this method directly. The DoDragDrop function calls this method in either of the following cases:

•	When the user drags the cursor out of a given target window.

•	When the user cancels the current drag-and-drop operation.

To implement IDropTarget::DragLeave, you must remove any target feedback that is currently displayed. You must also release any references you hold to the data transfer object.

See Also

DoDragDrop, IDropSource, IDropTarget, RegisterDragDrop, RevokeDragDrop


IDropTarget::DragOver

Provides target feedback to the user and communicates the drop’s effect to the DoDragDrop function so it can communicate the effect of the drop back to the source.

HRESULT DragOver(

DWORD grfKeyState,	//Current state of keyboard modifier keys
POINTL pt,	//Pointer to the current cursor coordinates
DWORD * pdwEffect	//Pointer to the effect of the drag-and-drop operation
);
Parameters

grfKeyState

[in] Current state of the keyboard modifier keys on the keyboard. Valid values can be a combination of any of the flags MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON.

pt

[in] Pointer to the current cursor coordinates in the coordinate space of the drop-target window.

pdwEffect

[in, out] Pointer to the current effect flag. Valid values are from the enumeration DROPEFFECT.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The method completed its task successfully.

Remarks

You do not call IDropTarget::DragOver directly. The DoDragDrop function calls this method each time the user moves the mouse across a given target window. DoDragDrop exits the loop if the drag-and-drop operation is canceled, if the user drags the mouse out of the target window, or if the drop is completed.

In implementing IDropTarget::DragOver, you must provide features similar to those in IDropTarget::DragEnter. You must determine the effect of dropping the data on the target by examining the FORMATETC defining the data object’s formats and medium, along with the state of the modifier keys. The mouse position may also play a role in determining the effect of a drop. The following modifier keys affect the result of the drop:

Key Combination	User-Visible Feedback	Drop Effect
CTRL + SHIFT	=	DROPEFFECT_LINK
CTRL	+	DROPEFFECT_COPY
No keys or SHIFT	None	DROPEFFECT_MOVE
You communicate the effect of the drop back to the source through DoDragDrop in pdwEffect. The DoDragDrop function then calls IDropSource::GiveFeedback so the source application can display the appropriate visual feedback to the user.

On entry to IDropTarget::DragOver, the pdwEffect parameter must be set to the allowed effects passed to the pdwOkEffect parameter of the DoDragDrop function. The IDropTarget::DragOver method must be able to choose one of these effects or disable the drop.

Upon return, pdwEffect is set to one of the members of the DROPEFFECT enumeration. This value is then passed to the pdwEffect parameter of DoDragDrop. Reasonable values are DROPEFFECT_COPY to copy the dragged data to the target, DROPEFFECT_LINK to create a link to the source data, or DROPEFFECT_MOVE to allow the dragged data to be permanently moved from the source application to the target.

You may also wish to provide appropriate visual feedback in the target window. There may be some target feedback already displayed from a previous call to IDropTarget::DragOver or from the initial IDropTarget::DragEnter. If this feedback is no longer appropriate, you should remove it.

For efficiency reasons, a data object is not passed in IDropTarget::DragOver. The data object passed in the most recent call to IDropTarget::DragEnter is available and can be used.

When IDropTarget::DragOver has completed its operation, the DoDragDrop function calls IDropSource::GiveFeedback so the source application can display the appropriate visual feedback to the user.

Notes to Implementers

This function is called frequently during the DoDragDrop loop so it makes sense to optimize your implementation of the DragOver method as much as possible.

See Also

DoDragDrop, IDropSource, IDropTarget, RegisterDragDrop, RevokeDragDrop


IDropTarget::Drop

Incorporates the source data into the target window, removes target feedback, and releases the data object.

HRESULT Drop(

IDataObject * pDataObject,	//Pointer to the interface for the source data
DWORD grfKeyState,	//Current state of keyboard modifier keys
POINTL pt,	//Pointer to the current cursor coordinates
DWORD * pdwEffect	//Pointer to the effect of the drag-and-drop operation
);
Parameters

pDataObject

[in] Pointer to the IDataObject interface on the data object being transferred in the drag-and-drop operation.

grfKeyState

[in] Current state of the keyboard modifier keys on the keyboard. Valid values can be a combination of any of the flags MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON.

pt

[in] Pointer to the current cursor coordinates in the coordinate space of the drop target window.

pdwEffect

[in, out] Pointer to the current effect flag. Valid values are from the enumeration DROPEFFECT.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The method completed its tasks successfully.

Remarks

You do not call this method directly. The DoDragDrop function calls this method when the user completes the drag-and-drop operation.

In implementing IDropTarget::Drop, you must incorporate the data object into the target. Use the formats available in IDataObject, available through pDataObject, along with the current state of the modifier keys to determine how the data is to be incorporated, such as linking or embedding.

In addition to incorporating the data, you must also clean up as you do in the IDropTarget::DragLeave method:

•	Remove any target feedback that is currently displayed.

•	Release any references to the data object.

You also pass the effect of this operation back to the source application through DoDragDrop, so the source application can clean up after the drag-and-drop operation is complete:

•	Remove any source feedback that is being displayed.

•	Make any necessary changes to the data, such as removing the data if the operation was a move.

See Also

DoDragDrop, IDropSource, IDropTarget, RegisterDragDrop, RevokeDragDrop


IEnumXXXX

To allow you to enumerate the number of items of a given type that an object maintains, OLE provides a set of enumeration interfaces, one for each type of item.

To use these interfaces, the client asks an object that maintains a collection of items to create an enumerator object. The interface on the enumeration object is one of the enumeration interfaces, all of which have a name of the form IEnumItem_name. The only difference between enumeration interfaces is what they enumerate — there must be a separate enumeration interface for each type of item enumerated. All have the same set of methods, and are used in the same way. For example, by repeatedly calling the Next method, the client gets successive pointers to each item in the collection.

The following table lists the set of enumeration interfaces that OLE defines, and the items enumerated.

Enumeration Interface Name	Item Enumerated
IEnumFORMATETC	An array of FORMATETC structures.
IEnumMoniker	The components of a moniker, or the monikers in a table.
IEnumOLEVERB	The different verbs available for an object, in order of ascending verb number.
IEnumSTATDATA	An array of STATDATA structures which contain advisory connection information for a data object.
IEnumSTATSTG	An array of STATSTG structures, which contain statistical information about a storage, stream, or LockBytes object
IEnumString	Strings
IEnumUnknown	Enumerates IUnknown interface pointers.
IEnumVARIANT	A collection of variants. It allows clients to enumerate heterogeneous collections of objects and intrinsic types when the clients cannot or do not know the specific type(s) of elements in the collection.
Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IEnumXXXX Methods	Description
Next	Retrieves a specified number of items in the enumeration sequence.
Skip	Skips over a specified number of items in the enumeration sequence.
Reset	Resets the enumeration sequence to the beginning.
Clone	Creates another enumerator that contains the same enumeration state as the current one.


IEnumXXXX::Clone

Creates another enumerator that contains the same enumeration state as the current one. Using this function, a client can record a particular point in the enumeration sequence, and then return to that point at a later time. The new enumerator supports the same interface as the original one.

HRESULT Clone(

IEnum<ELT_T> ** ppenum	//Indirect pointer to the enumeration interface on the object
);
Parameter

ppenum

[out] Indirect pointer to the enumeration interface on the enumeration object. If the method is unsuccessful, this parameter’s value is undefined.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED.


IEnumXXXX::Next

Retrieves the next celt items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements. The number of elements actually retrieved is returned through pceltFetched (unless the caller passed in NULL for that parameter).

HRESULT Next(

ULONG celt,	//Number of elements requested
ELT_T[ ] rgelt,	//Array of the elements
ULONG * pceltFetched	//Pointer to the number of elements actually supplied
);
Parameters

celt

[in] Number of elements being requested.

rgelt

[out] Array of size celt (or larger) of the elements of interest. The type of this parameter depends on the item being enumerated.

pceltFetched

[in, out] Pointer to the number of elements actually supplied in rgelt. Caller can pass in NULL if celt is one.

Return Value

S_OK if the number of elements supplied is celt; S_FALSE otherwise.


IEnumXXXX::Reset

Resets the enumeration sequence to the beginning.

HRESULT Reset(void);

Return Value

S_OK

Remarks

A call to this method, resetting the sequence, does not guarantee that the same set of objects will be enumerated after the reset, because it depends on the collection being enumerated. A static collection is reset to the beginning, but it can be too expensive for some collections, such as files in a directory, to guarantee this condition.


IEnumXXXX::Skip

Skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(

ULONG celt	//Number of elements to be skipped
);
Parameter

celt

[in] Number of elements to be skipped.

Return Value

S_OK if the number of elements skipped is celt; otherwise S_FALSE.


IEnumConnectionPoints

This interface enumerates connection points. Connectable objects support the following features:

•	Outgoing interfaces, such as event sets

•	The ability to enumerate the IIDs of the outgoing interfaces

•	The ability to connect and disconnect sinks to the object for those outgoing IIDs

•	The ability to enumerate the connections that exist to a particular outgoing interface

When to Implement

To support connectable objects, you need to provide four related interfaces:

•	IConnectionPointContainer

•	IEnumConnectionPoints

•	IConnectionPoint

•	IEnumConnections

The IConnectionPointContainer interface indicates the existence of the outgoing interfaces. It provides access to an enumerator sub-object with the IEnumConnectionPoints interface. It also provides a connection point sub-object with the IConnectionPoint interface. The IConnectionPoint interface provides access to an enumerator sub-object with the IEnumConnections interface.

The connection point is a separate sub-object to avoid circular reference counting problems.

A connectable object can be asked to enumerate its supported connection points through IConnectionPointContainer::EnumConnectionPoints. The resulting enumerator returned from this method implements the interface IEnumConnectionPoints, through which a client can access all the individual connection point sub-objects supported within the connectable object itself, where each connection point implements IConnectionPoint.

When enumerating connections through IEnumConnectionPoints, the enumerator is responsible for calling IUnknown::AddRef, and the caller is responsible for later calling IUnknown::Release when those pointers are no longer needed.

When to Use

Use the IEnumConnectionPoints interface to enumerate all the supported connection points for each outgoing IID.

The prototypes of the methods are as follows:

HRESULT Next(

ULONG cConnections ,	//[in]Number of IConnectionPoint values returned in rgpcn array
IConnectionPoint **rgpcn ,	//[out]Array to receive enumerated connection points
ULONG *pcFetched	//[out]Pointer to the actual number of connection points returned in rgpcn array
);
HRESULT Skip(

ULONG cConnections	//[in]Number of elements to skip
);
HRESULT Reset(void);

HRESULT Clone(

IEnumConnectionPoints **ppEnum	//[out]Indirect pointer to newly created enumerator
);
Remarks

IEnumConnectionPoints::Next

Enumerates the next cConnections elements (IConnectionPoint pointers) in the enumerator’s list, returning them in rgpcn along with the actual number of enumerated elements in pcFetched. The enumerator calls IConnectionPoint::AddRef for each returned pointer in rgpcn, and the caller is responsible for calling IConnectionPoint::Release through each pointer when those pointers are no longer needed.

E_NOTIMPL is not allowed as a return value. If an error value is returned, no entries in the rgpcn array are valid on exit and require no release.

IEnumConnectionPoints::Skip

Instructs the enumerator to skip the next cConnections elements in the enumeration so that the next call to IEnumConnectionPoints::Next will not return those elements.

IEnumConnectionPoints::Reset

Instructs the enumerator to position itself at the beginning of the list of elements.

There is no guarantee that the same set of elements will be enumerated on each pass through the list, nor will the elements necessarily be enumerated in the same order. The exact behavior depends on the collection being enumerated. It is too expensive for some collections, such as files in a directory, to maintain a specific state.

IEnumConnectionPoints::Clone

Creates another connection point enumerator with the same state as the current enumerator to iterate over the same list. This method makes it possible to record a point in the enumeration sequence in order to return to that point at a later time.

The caller must release this new enumerator separately from the first enumerator.

See Also

IConnectionPoint, IConnectionPointContainer, IEnumConnections, IEnumXxxx


IEnumConnections

This interface enumerates the current connections for a connectable object. Connectable objects support the following features:

•	Outgoing interfaces, such as event sets

•	The ability to enumerate the IIDs of the outgoing interfaces

•	The ability to connect and disconnect sinks to the object for those outgoing IIDs

•	The ability to enumerate the connections that exist to a particular outgoing interface

When to Implement

To support connectable objects, you need to provide four related interfaces:

•	IConnectionPointContainer

•	IEnumConnectionPoints

•	IConnectionPoint

•	IEnumConnections

The IConnectionPointContainer interface indicates the existence of the outgoing interfaces. It provides access to an enumerator sub-object with the IEnumConnectionPoints interface. It also provides a connection point sub-object with the IConnectionPoint interface. The IConnectionPoint interface provides access to an enumerator sub-object with the IEnumConnections interface.

The connection point is a separate sub-object to avoid circular reference counting problems.

Any individual connection point can support enumeration of its currently known connections through IConnectionPoint::EnumConnections. The enumerator created by this method implements the interface IEnumConnections which deals with the type CONNECTDATA. Each CONNECTDATA structure contains the IUnknown of a connected sink and the dwConnection that was returned by IConnectionPoint::Advise when that sink was connected. When enumerating connections through IEnumConnections, the enumerator is responsible for calling IUnknown::AddRef through the pointer in each enumerated structure, and the caller is responsible to later call IUnknown::Release when those pointers are no longer needed.

When to Use

Use the IEnumConnectionPoints interface to enumerate all the supported connection points for each outgoing IID.

The prototypes of the methods are as follows:

HRESULT Next(

ULONG cConnections ,	//[in]Number of CONNECTDATA structures returned in rgpcd
CONNECTDATA **rgpcd ,	//[out]Array to receive enumerated CONNECTDATA structures
ULONG *pcFetched	//[out]Pointer to actual number of CONNECTDATA structures
);
HRESULT Skip(

ULONG cConnections	//[in]Number of elements to skip
);
HRESULT Reset(void);

HRESULT Clone(

IEnumConnections **ppEnum	//[out]Indirect pointer to newly created enumerator
);
Remarks

IEnumConnections::Next

Enumerates the next cConnections elements (i.e., CONNECTDATA structures) in the enumerator’s list, returning them in rgpcd along with the actual number of enumerated elements in pcFetched.

The caller is responsible for calling CONNECTDATA.pUnk->Release for each element in the array once this method returns successfully. If cConnections is greater than one, the caller must also pass a non-NULL pointer to pcFetched to get the number of pointers it has to release.

E_NOTIMPL is not allowed as a return value. If an error value is returned, no entries in the rgpcd array are valid on exit and require no release.

IEnumConnections::Skip

Instructs the enumerator to skip the next cConnections elements in the enumeration so that the next call to IEnumConnections::Next will not return those elements.

IEnumConnections::Reset

Instructs the enumerator to position itself at the beginning of the list of elements.

There is no guarantee that the same set of elements will be enumerated on each pass through the list. It depends on the collection being enumerated. It is too expensive for some collections, such as files in a directory, to maintain a specific state.

IEnumConnections::Clone

Creates another connection point enumerator with the same state as the current enumerator to iterate over the same list. This method makes it possible to record a point in the enumeration sequence in order to return to that point at a later time.

The caller must release this new enumerator separately from the first enumerator.

See Also

CONNECTDATA, IConnectionPoint, IConnectionPointContainer, IEnumConnectionPoints, IEnumXxxx


IEnumFORMATETC

The IEnumFORMATETC interface is used to enumerate an array of FORMATETC structures. IEnumFORMATETC has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. For general information on these methods, refer to IEnumXXXX.

When to Implement

IEnumFORMATETC must be implemented by all data objects to support calls to IDataObject::EnumFormatEtc, which supplies a pointer to the enumerator’s IEnumFORMATETC interface. If the data object supports a different set of FORMATETC information depending on the direction of the data (whether a call is intended for the SetData or GetData method of IDataObject), the implementation of IEnumFORMATETC must be able to operate on both.

The order of formats enumerated through the IEnumFORMATETC object should be the same as the order that the formats would be in when placed on the clipboard. Typically, this order starts with private data formats and ends with presentation formats such as CF_METAFILEPICT.

When to Use

Call the methods of IEnumFORMATETC when you need to enumerate the FORMATETC structures defining the formats and media supported by a given data object. This is necessary in most data transfer operations, such as clipboard and drag-and-drop, so the object on the other end of the data transfer can determine whether the appropriate format and media for the data is supported.

The prototypes of the methods are as follows:

HRESULT Next(ULONG celt, FORMATETC * rgelt, ULONG * pceltFetched)

HRESULT Skip(ULONG celt)

HRESULT Reset(void)

HRESULT Clone(IEnumFORMATETC ** ppenum)

See Also

OleRegEnumFormatEtc, FORMATETC, IEnumXXXX


IEnumMoniker

The IEnumMoniker interface is used to enumerate the components of a moniker or to enumerate the monikers in a table of monikers. IEnumMoniker has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. For general information on these methods, refer to IEnumXXXX.

When to Implement

You need to implement IEnumMoniker if you are writing a new type of moniker and your monikers have an internal structure that can be enumerated. Your implementation of IMoniker::Enum must return an enumerator that implements IEnumMoniker and can enumerate your moniker’s components. If your moniker has no structure that can be enumerated, your IMoniker::Enum method can simply return a NULL pointer.

When to Use

Call the methods of the IEnumMoniker interface if you need to enumerate the components of a composite moniker, or to enumerate the monikers in a table.

OLE defines two interfaces that supply an IEnumMoniker interface pointer:

•	The IMoniker::Enum method gets a pointer to an IEnumMoniker implementation that can enumerate forwards or backwards through the components of the moniker. For a description of how two of the system-supplied types of monikers enumerate their components, see IMoniker − File Moniker Implementation and IMoniker − Generic Composite Moniker Implementation.

•	The IRunningObjectTable::EnumRunning method returns a pointer to an IEnumMoniker implementation that can enumerate the monikers registered in a Running Object Table.

The prototypes of the methods are as follows:

HRESULT Next(ULONG celt, IMoniker * rgelt, ULONG * pceltFetched)

HRESULT Skip(ULONG celt)

HRESULT Reset(void)

HRESULT Clone(IEnumMoniker ** ppenum)

See Also

IEnumXXXX, IMoniker::Enum, IRunningObjectTable::EnumRunning


IEnumOleUndoUnits

The IEnumOleUndoUnits interface enumerates the undo units on the undo or redo stack.

When to Implement

The undo manager implements this method to enumerate a list of undo units on the undo or redo stack.

When to Use

Use the IEnumOleUndoUnits interface to enumerate all the top level undo units on the undo or redo stack.

The prototypes of the methods are as follows:

HRESULT Next(

ULONG cUndoUnits ,	//[in]Number of undo units returned in rgpcd
CONNECTDATA **rgpcd ,	//[out]Array to receive enumerated undo units
ULONG *pcFetched	//[out]Pointer to actual number of undo units
);
HRESULT Skip(

ULONG cUndoUnits	//[in]Number of undo units to skip
);
HRESULT Reset(void);

HRESULT Clone(

IEnumOleUndoUnits** ppEnum	//[out]Indirect pointer to newly created enumerator
);
Remarks

IEnumOleUndoUnits::Next

Enumerates the next specified number of undo units in the enumerator’s list, returning them in rgpcd along with the actual number of enumerated elements in pcFetched.

The caller is responsible for calling the Release method for each element in the array once this method returns successfully. If cUndoUnits is greater than one, the caller must also pass a non-NULL pointer to pcFetched to get the number of pointers it has to release.

E_NOTIMPL is not allowed as a return value. If an error value is returned, no entries in the rgpcd array are valid on exit and require no release.

IEnumOleUndoUnits::Skip

Instructs the enumerator to skip the next specified number of elements in the enumerator so that the next call to IEnumOleUndoUnits::Next will not return those elements.

IEnumOleUndoUnits::Reset

Instructs the enumerator to position itself at the beginning of the list of elements.

There is no guarantee that the same set of elements will be enumerated on each pass through the list. It depends on the collection being enumerated. It is too expensive for some collections, such as files in a directory, to maintain a specific state.

IEnumOleUndoUnits::Clone

Creates another undo unit enumerator with the same state as the current enumerator to iterate over the same list. This method makes it possible to record a point in the enumeration sequence in order to return to that point at a later time.

The caller must release this new enumerator separately from the first enumerator.

See Also

IOleUndoManager, IOleUndoUnit


IEnumOLEVERB

The IEnumOLEVERB interface enumerates the different verbs available for an object in order of ascending verb number. An enumerator that implements the IEnumOLEVERB interface is returned by IOleObject::EnumVerbs. IEnumOLEVERB has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. For general information on these methods, refer to IEnumXXXX.

When to Implement

You typically do not have to implement this interface. The OLE default handler provides an implementation that supplies the entries in the registry. Because calls to IOleObject::EnumVerb are always routed through the default handler, an OLE application can let the default handler do the work by implementing IOleObject::EnumVerb as a stub that simply returns OLE_S_USEREG. This informs the default handler that it should create the enumerator for you.

When to Use

Call this interface if you need to list the verbs than an OLE object supports.

The prototypes of the methods are as follows:

HRESULT Next(ULONG celt, LPOLEVERB rgelt, ULONG * pceltFetched)

HRESULT Skip(ULONG celt)

HRESULT Reset(void)

HRESULT Clone(IEnumOLEVERB ** ppenum)

See Also

OLEVERB, IEnumXXXX


IEnumSTATDATA

The IEnumSTATDATA interface is used to enumerate through an array of STATDATA structures, which contain advisory connection information for a data object. IEnumSTATDATA has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. For general information on these methods, refer to IEnumXXXX.

When to Implement

IEnumSTATDATA is implemented to enumerate advisory connections. Most applications will not implement this directly, but will use the OLE-provided implementation. Pointers to this implementation are available in two ways:

•	In a data object, call CreateDataAdviseHolder to get a pointer to the OLE data advise holder object, and then, to implement IDataObject::EnumDAdvise, call IDataAdviseHolder::EnumAdvise, which creates the enumeration object and supplies a pointer to the implementation of IEnumSTATDATA.

•	In a compound document object, call CreateOLEAdviseHolder to get a pointer to the OLE advise holder object, and then, to implement IOleObject::EnumAdvise, call IOleAdviseHolder::EnumAdvise, which creates the enumeration object and supplies a pointer to the implementation of IEnumSTATDATA.

When to Use

Containers usually call methods that return a pointer to IEnumSTATDATA so the container can use its methods to enumerate the existing advisory connections, and use this information to instruct an object to release each of its advisory connections prior to closing down. IDataObject::EnumDAdvise, IDataAdviseHolder::EnumAdvise, IOleAdviseHolder::EnumAdvise, and IOleCache::EnumCache methods all supply a pointer to IEnumSTATDATA.

The prototypes of the methods are as follows:

HRESULT Next(ULONG celt, STATDATA * rgelt, ULONG * pceltFetched)

HRESULT Skip(ULONG celt)

HRESULT Reset(void)

HRESULT Clone(IEnumSTATDATA ** ppenum)

See Also

STATDATA, IEnumXXXX, IOleCache::EnumCache, IDataObject::EnumDAdvise, IDataAdviseHolder::EnumAdvise, IOleObject::EnumAdvise


IEnumSTATPROPSETSTG

The IEnumSTATPROPSETSTG interface is used to iterate through an array of STATPROPSETSTG structures, which contain statistical information about the property sets managed by the current instance of IPropertySetStorage. IEnumSTATPROPSETSTG has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. For general information on these methods, refer to IEnumXXXX.

The implementation defines the order in which the property sets are enumerated. Property sets that are present when the enumerator is created, and are not removed during the enumeration, will be enumerated only once. Property sets added or deleted while the enumeration is in progress may or may not be enumerated, but, if enumerated, will not be enumerated more than once.

For information on how the OLE compound document implementation of IEnumSTATPROPSETSTG:Next supplies members of the STATPROPSETSTG structure, refer to IEnumSTATPROPSETSTG--Compound File Implementation.

When to Implement

IEnumSTATPROPSETSTG is implemented to enumerate the property sets supported by the current property set storage object. If you are using the compound file implementation of the storage object, a pointer to which is available through a call to StgCreateDocfile, IEnumSTATPROPSETSTG is implemented on that object, and a pointer is returned through a call to IPropertySetStorage::Enum. If you are doing a custom implementation of IPropertySetStorage, you need to implement IEnumSTATPROPSETSTG to fill in a caller-allocated array of STATPROPSETSTG structures, each of which contains information about the nested elements in the storage object.

When to Use

Call IPropertySetStorage::Enum to return a pointer to IEnumSTATPROPSETSTG, the methods of which can then be called to enumerate STATPROSETSTG structures so the application can manage its property sets.

The prototypes of the methods are as follows:

HRESULT Next(ULONG celt, STATPROPSETSTG * rgelt, ULONG * pceltFetched)

HRESULT Skip(ULONG celt)

HRESULT Reset(void)

HRESULT Clone(IEnumSTATPROPSETSTG ** ppenum)

See Also

IPropertyStorage::Enum


IEnumSTATPROPSETSTG-Compound File Implementation

The compound file implementation of IEnumSTATPROPSETSTG interface is used to enumerate through an array of STATPROPSETSTG structures, which contain statistical information about the properties managed by the compound file implementation of IPropertySetStorage, which is associated with a current compound file storage object.

When to Use

Call the methods of IEnumSTATPROPSETSTG to enumerate STATPROPSETSTG structures, each of which provides information about one of the property sets associated with the compound file storage object.

Remarks

IEnumSTATPROPSETSTG::Next

Gets the next one or more STATPROPSETSTG structures (the number is specified by the celt parameter). The STATPROPSETSTG elements provided through a call to the compound file implementation of IEnumSTATPROPSETSTG::Next follow these rules:

•	If IEnumSTATPROPSETSTG::Next cannot provide STATPROPSETSTG.fmtid, zeros are written to that member. This occurs when the property set does not have a predefined name (such as \005SummaryInformation) and is not a legal value.

•	The DocumentSummaryInformation property set is special, in that it may have two property set sections.  This property set is described in the section titled The DocumentSummaryInformation Property Set. The second section is referred to as the User-Defined Properties.  Each section is identified with a unique Format ID.  When IPropertySetStorage::Enum is used to enumerate property sets, the User-Defined Property Set will not be enumerated.

Note  If you always create a property set using IPropertySetStorage::Create, then, since a “Character GUID” is created for the storage name, IEnumSTATPROPSETSTG::Next will return a nonzero, valid format identifier for the property set[STATPROPSETSTG.fmtid].

•	The STATPROPSETSTG.grfFlags member does not necessarily reflect whether the property set is ANSI or not. If PROPSETFLAG_ANSI is set, the property set is definitely ANSI. If PROPSETFLAG_ANSI is clear, the property set could be either Unicode or non-Unicode, because it is not possible to tell whether it is ANSI without opening it.

•	The STATPROPSETSTG.grfFlags member does reflect whether the property set is simple or not, so the setting of the PROPSETFLAG_NONSIMPLE flag is always valid.

•	If IEnumSTATPROPSETSTG::Next cannot provide STATPROPSETSTG.clsid, it is set to all zeroes (CLSID_NULL). In the OLE compound file implementation, this occurs when the property set is simple (the PROPSETFLAG_NONSIMPLE flag is not set), or is non-simple but the CLSID was not explicitly set. For non-simple property sets, the CLSID that is received is the one that is maintained by the underlying IStorage.

•	If IEnumSTATPROPSETSTG::Next cannot provide the time fields [ctime, mtime, atime], each non-supported time will be set to zeroes. In the OLE compound file implementation, getting these values depends on retrieving them from the underlying IStorage implementation.

IEnumSTATPROPSETSTG::Skip

Skips the number of elements specified in celt. Returns S_OK if the specified number of elements are skipped, returns S_FALSE if fewer elements than requested are skipped. In any other case, returns the appropriate error.

IEnumSTATPROPSETSTG::Reset

Sets the cursor to the beginning of the enumeration. If successful, returns S_OK, otherwise, returns STG_E_INVALIDHANDLE.

IEnumSTATPROPSETSTG::Clone

Copies the current enumeration state of this enumerator.


IEnumSTATPROPSTG

The IEnumSTATPROPSTG interface is used to iterate through an array of STATPROPSTG structures, which contain statistical information about an open property storage containing a property set. IEnumSTATPROPSTG has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. For general information on these methods, refer to IEnumXXXX.

The implementation defines the order in which the properties in the set are enumerated. Properties that are present when the enumerator is created, and are not removed during the enumeration, will be enumerated only once. Properties added or deleted while the enumeration is in progress may or may not be enumerated, but they will never be enumerated more than once.

Properties with property ID 0 (dictionary), property ID 1 (codepage indicator), or property ID greater than or equal to 0x80000000 are not enumerated.

Enumeration of a non-simple property does not necessarily indicate that the property can be read successfully through a call to IPropertyStorage::ReadMultiple. This is because the performance overhead of checking existence of the indirect stream or storage is prohibitive during property enumeration. A client of this interface should code accordingly.

When to Implement

Implement IEnumSTATPROPSTG to enumerate the properties within a property set. If you are using the compound file implementation of the storage object, a pointer to which is available through a call to StgCreateDocfile, you can then query for a pointer to IPropertySetStorage. After calling one of its methods either to open or create a property set, you can get a pointer to IEnumSTATPROPSTG through a call to IPropertyStorage::Enum. If you are doing a custom implementation of IPropertyStorage, you also need to implement IEnumSTATPROPSTG to fill in a caller-allocated array of STATPROPSTG structures. Each STATPROPSTG structure contains information about a simple property.

When to Use

Applications that support storage objects and persistent properties within those objects call IPropertyStorage::Enum to return a pointer to IEnumSTATPROPSTG to enumerate the properties in the current property set.

The prototypes of the methods are as follows:

HRESULT Next(ULONG celt, STATPROPSTG * rgelt, ULONG * pceltFetched)

HRESULT Skip(ULONG celt)

HRESULT Reset(void)

HRESULT Clone(IEnumSTATPROPSTG ** ppenum)

See Also

IPropertyStorage::Enum


IEnumSTATPROPSTG-Compound File Implementation

The compound file implementation of the IEnumSTATPROPSTG interface is used to enumerate through properties, resulting in STATPROPSTG structures, which contain statistical information about the properties managed by the compound file implementation of IPropertyStorage, which is associated with a current compound file storage object.

The constructor in the OLE implementation of IEnumSTATPROPSTG creates a class that reads the entire property set, and creates a static array which can be shared when IEnumSTATPROPSTG::Clone is called.

When to Use

Call the compound file implementation of IEnumSTATPROPSTG to enumerate the STATPROPSTG structures that contain information about the properties within the current property set. When you are using the compound file implementation of the property storage interfaces, call IPropertyStorage::Enum to return a pointer to IEnumSTATPROPSTG to manage the property storage object and the elements within it.

Remarks

IEnumSTATPROPSTG::Next

Gets the next one or more STATPROPSTG structures (the number is specified by the celt parameter). Returns S_OK if successful.

IEnumSTATPROPSTG::Skip

Skips the number of elements specified in celt. The next element to be enumerated through a call to Next then becomes the element after the ones skipped. Returns S_OK if celt elements were skipped; returns S_FALSE if fewer than celt elements were skipped.

IEnumSTATPROPSTG::Reset

Sets the cursor to the beginning of the enumeration. If successful, returns S_OK, otherwise, returns STG_E_INVALIDHANDLE.

IEnumSTATPROPSTG::Clone

Uses the constructor for the IEnumSTATPROPSTG to create a copy of the array. Because the class that constructs the static array actually contains the object, this function mainly adds to the reference count.

See Also

STATPROPSTG, IPropertyStorage::Enum


IEnumSTATSTG

The IEnumSTATSTG interface is used to enumerate through an array of STATSTG structures, which contain statistical information about an open storage, stream, or byte array object. IEnumSTATSTG has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. For general information on these methods, refer to IEnumXXXX.

When to Implement

IEnumSTATSTG is implemented to enumerate the elements of a storage object. If you are using the compound file implementation of the storage object, a pointer to which is available through a call to StgCreateDocfile, IEnumSTATSTG is implemented on that object, and a pointer is returned through a call to IStorage::EnumElements. If you are doing a custom implementation of a storage object, you need to implement IEnumSTATSTG to fill in a caller-allocated array of STATSTG structures, each of which contains information about the nested elements in the storage object.

When to Use

Containers call methods that return a pointer to IEnumSTATSTG so the container can manage its storage object and the elements within it. Calls to the IStorage::EnumElements method supplies a pointer to IEnumSTATDATA. The caller allocates an array of STATSTG structures and the IEnumSTATSTG methods fill in each structure with the statistics about one of the nested elements in the storage object. If present, the lpszName member of the STATSTG structure requires additional memory allocations through the IMalloc interface, and the caller is responsible for freeing this memory, if it is allocated, by calling the IMalloc::Free method. If the lpszName member is NULL, no memory is allocated, and, therefore, no memory needs to be freed.

The prototypes of the methods are as follows:

HRESULT Next(ULONG celt, STATSTG * rgelt, ULONG * pceltFetched)

HRESULT Skip(ULONG celt)

HRESULT Reset(void)

HRESULT Clone(IEnumSTATSTG ** ppenum)

See Also

CoGetMalloc, IEnumXXXX, IStorage::EnumElements, STATSTG


IEnumString

IEnumString is defined to enumerate strings. LPWSTR is the type that indicates a pointer to a zero-terminated string of wide, i.e., Unicode, characters. IEnumString has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. For general information on these methods, refer to IEnumXXXX.

When to Implement

It is usually not necessary to implement this interface unless you have use for a custom string enumerator. A system implementation in the bind context object on which is the IBindCtx interface also contains an implementation of IEnumString. IBindCtx::EnumObjectParam returns a pointer to this IEnumString interface on an enumerator that can return the keys of the bind context’s string-keyed table of pointers.

When to Use

Call the methods of IEnumString to enumerate through a set of strings.

The prototypes of the member functions are as follows:

HRESULT Next(ULONG celt, LPOLESTR * rgelt, ULONG * pceltFetched)

HRESULT Skip(ULONG celt)

HRESULT Reset(void)

HRESULT Clone(IEnumString ** ppenum)


IEnumUnknown

This enumerator enumerates objects with the IUnknown interface. It can be used to enumerate through the objects in a component containing multiple objects. IEnumUnknown has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. For general information on these methods, refer to IEnumXXXX.

When to Implement

You can implement this whenever you want a caller to be able to enumerate the objects contained in another object. You get a pointer to IEnumUnknown through a call to IOleContainer::EnumObjects.

When to Implement

Call the methods of IEnumUnknown to enumerate the objects in a compound document, when you get a pointer to the interface on the enumerator through a call to IOleContainer::EnumObjects.

The prototypes of the methods are as follows:

HRESULT Next(ULONG celt, IUnknown ** rgelt, ULONG * pceltFetched)

HRESULT Skip(ULONG celt)

HRESULT Reset(void)

HRESULT Clone(IEnumUnknown ** ppenum)

See Also

IOleContainer


IErrorLog

The IErrorLog interface is an abstraction for an error log that is used to communicate detailed error information between a client and an object. The caller of the single interface method, AddError, simply logs an error where the error is an EXCEPINFO structure related to a specific property. The implementer of the interface is responsible for handling the error in whatever way it desires.

IErrorLog is used in the protocol between a client that implements IPropertyBag and an object that implements IPersistPropertyBag.

When to Implement

A container implements IErrorLog to provide a control with a means of logging errors when the control is loading its properties from the container-provided property bag.

When to Use

A control logs calls the single method in this interface to log any errors that occur when it is loading its properties.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IErrorLog Method	Description
AddError	Logs an error, an EXCEPINFO structure, in the error log during the property load process for a named property.
See Also

IPersistPropertyBag, IPropertyBag


IErrorLog::AddError

Logs an error, an EXCEPINFO structure, in the error log during the property load process for a named property.

HRESULT AddError(

LPCOLESTR pszPropName,	//Pointer to the name of the property involved with the error
LPEXCEPINFO pException	//Pointer to the caller-initialized EXCEPINFO structure describing the error
);
Parameters

pszPropName

[in] Pointer to the name of the property involved with the error. Cannot be NULL.

pExcepInfo

[in] Pointer to the caller-initialized EXCEPINFO structure that describes the error to log. Cannot be NULL.

Return Values

S_OK

The error was logged successfully.

E_FAIL

There was a problem logging the error.

E_OUTOFMEMORY

There was not enough memory to log the error.

E_POINTER

The address in pszPropName or pExceptInfo is not valid (such as NULL). The caller must supply both.

Remarks

E_NOTIMPL is not a valid return code as the method is the only one in the entire interface.


IExternalConnection

The IExternalConnection interface enables an embedded object to keep track of external locks on it, thereby enabling the safe and orderly shutdown of the object following silent updates. An object that supports links either to itself or to some portion of itself (a range of cells in a spreadsheet, for example) should implement this interface to prevent possible loss of data during shutdown.

Such data loss can occur when an object happens to have unsaved changes at a time when its stub manager’s count of strong external references has reached zero. This situation would arise, for example, at the end of a silent update, when the final link client breaks its connection to the object. With the severing of this connection, the stub manager’s count of strong external references would reach zero, causing it to release its pointers to an interface on the object and initiate shutdown of the object. When the object calls IOleClientSite::SaveObject, its container’s return call to IPersistStorage::Save would fail because the stub manager would no longer have a pointer to any interface on the object. Any unsaved changes to the object would be lost.

If the object manages its own count of external locks, rather than relying on the stub manager to do so, it can save its data before the stub manager has a chance to release its pointers. An object can obtain a count of external connections by implementing the IExternalConnection interface. The stub manager calls this interface whenever a new strong external reference is added or deleted. The object combines this count with its own tally of strong internal references to maintain an accurate total of all locks.

When to Implement

All embeddable compound-document objects that support links to themselves or portions of themselves should implement IExternalConnection to prevent possible data loss during shutdown. In addition, an in-place container should call OleLockRunning to hold a strong lock on its embedded objects.

When to Use

An object’s stub manager should call IExternalConnection whenever an external connection is added or released.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IExternalConnection Methods	Description
AddConnection	Increments count of external locks.
ReleaseConnection	Decrements count of external locks.


IExternalConnection::AddConnection

Increments an object’s count of its strong external connections (links).

HRESULT AddConnection(

DWORD exconn,	//Type of external connection
DWORD dwreserved	//Used by OLE to pass connection information
);
Parameters

exconn

[in] Type of external connection to the object. The only type of external connection currently supported by this interface is strong, which means that the object must remain alive as long as this external connection exists. Strong external connections are represented by the value EXTCONN_STRONG = 0x0001, which is defined in the enumeration EXTCONN.

dwreserved

[in] Passes information about the connection. This parameter is reserved for use by OLE. Its value can be zero, but not necessarily. Therefore, implementations of AddConnection should not contain blocks of code whose execution depends on whether a zero value is returned.

Return Value

DWORD value

The number of reference counts on the object; used for debugging purposes only.

Remarks

An object created by a EXE object server relies on its stub manager to call IExternalConnection::AddConnection whenever a link client activates and therefore creates an external lock on the object. When the link client breaks the connection, the stub manager calls IExternalConnection::ReleaseConnection to release the lock.

Since DLL object applications exist in the same process space as their objects, they do not use RPC (remote procedure calls) and therefore do not have stub managers to keep track of external connections. Therefore, DLL servers that support external links to their objects must implement IExternalConnection so link clients can directly call the interface to inform them when connections are added or released.

The following is a typical implementation for the AddConnection method:

DWORD XX::AddConnection(DWORD extconn, DWORD dwReserved)
{
return extconn&EXTCONN_STRONG ? ++m_cStrong : 0;
}

See Also

IExternalConnection::ReleaseConnection, IRunnableObject::LockRunning, OleLockRunning


IExternalConnection::ReleaseConnection

Decrements an object’s count of its strong external connections (references).

HRESULT ReleaseConnection(

DWORD extconn,	//Type of external connection
DWORD dwreserved,	//Used by OLE to pass connection information
BOOL fLastReleaseCloses	//Indicates whether connection is last one or not
);
Parameters

extconn

[in] Type of external connection to the object. The only type of external connection currently supported by this interface is strong, which means that the object must remain alive as long as this external connection exists. Strong external connections are represented by the value EXTCONN_STRONG = 0x0001, which is defined in the enumeration EXTCONN.

dwreserved

[in] Passes information about the connection. This parameter is reserved for use by OLE. Its value can be zero, but not necessarily. Therefore, implementations of ReleaseConnection should not contain blocks of code whose execution depends on whether a zero value is returned.

fLastReleaseCloses

[in] TRUE specifies that if the connection being released is the last external lock on the object, the object should close. FALSE specifies that the object should remain open until closed by the user or another process.

Return Value

DWORD value

The number of connections to the object; used for debugging purposes only.

Remarks

If fLastReleaseCloses equals TRUE, calling ReleaseConnection causes the object to shut itself down. Calling this method is the only way in which a DLL object, running in the same process space as the container application, will know when to close following a silent update.

See Also

IExternalConnection::AddConnection


IFillLockBytes

The IFillLockBytes interface enables downloading code to write data asynchronously to a structured storage byte array. When the downloading code has new data available, it calls IFillLockBytes::FillAppend or IFillLockBytes::FillAt to write the data to the byte array. An application attempting to access this data, through calls to the ILockBytes interface, can do so even as the downloader continues to make calls to IFillLockBytes. If the application attempts to access data that has not already been downloaded through a call to IFillLockBytes, then ILockBytes returns a new error, E_PENDING.

When to Implement

You normally would not implement this interface. A system developer that wants to provide asynchronous storage for a protocol other than http might implement IFillLockBytes as part of the transport layer.

When to Use

You normally would not call this interface. Monikers or other downloading code that provide asynchronous storage use this interface to fill the byte array as data becomes available.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IFillLockBytes Methods	Description
FillAppend	Writes a new block of bytes to end of byte array.
FillAt	Writes a new block of bytes to specified location in byte array.
SetFillSize	Sets expected size of byte array.
Terminate	Notifies byte array wrapper of successful or unsuccessful termination of download.
See Also

IConnectionPoint, IConnectionPointContainer, ILockBytes, IProgressNotify, IStorage, IStream

Also see IBinding and IBindStatusCallback in the ActiveX™ SDK.


IFillLockBytes::FillAppend

Writes a new block of bytes to the end of a byte array.

HRESULT FillAppend(

void const *pv	// Data to be appended to byte array
ULONG cb	// Number of bytes to be appended
ULONG *pcbWritten	// Number of bytes that were successfully appended
);
Parameters

pv

[in] Points to the data to be appended to the end of an existing byte array.

cb

[in] Size of pv in bytes.

pcbWritten

[out] Number of bytes that were successfully written.

Return Values

This function supports the standard return values E_OUTOFMEMORY, E_UNEXPECTED, E_INVALIDARG, and E_FAIL.

Remarks

The FillAppend method is used for sequential downloading, where bytes are written to the end of the byte array in the order in which they are received. This method obtains the current size of the byte array (i.e., lockbytes object) and writes a new block of data to the end of the array. As each block of data becomes available, the downloader calls this method to write it to the byte array. Subsequent calls by the compound file implementation to ILockBytes::ReadAt return any available data or return E_PENDING if data is currently unavailable.

See Also

ILockBytes


IFillLockBytes::FillAt

Writes a new block of data to a specified location in the byte array.

HRESULT FillAt(

ULARGE_INTEGER uIOffset	// Offset from beginning of the byte array
void const *pv	// Data to be written
ULONG cb	// Number of bytes to be written
ULONG *pcbWritten	// Number of bytes that were successfully written
);
Parameters

uIOffset

[in] The offset, expressed in number of bytes, from the first element of the byte array.

pv

[in] Points to the data to be written at the location specified by uIOffset.

cb

[in] Size of pv in bytes.

pcbWritten

[out] Number of bytes that were successfully written.

Return Values

This function supports the standard return values E_OUTOFMEMORY, E_UNEXPECTED, E_INVALIDARG, and E_FAIL in addition to the following:

E_NOTIMPL

The byte array does not support FillAt.

Remarks

The FillAt method is used for nonsequential downloading (for example, http byte range requests). In nonsequential downloading the caller specifies ranges in the byte array where various blocks of data are to be written. Subsequent calls by the compound file implementation to ILockBytes::ReadAt are passed by the byte array wrapper object’s own implementation of ILockBytes to the underlying byte array. This method is not currently implemented and will return E_NOTIMPL.

Note  The system-supplied IFillLockBytes implementation does not support FillAt and returns E_NOTIMPL.

See Also

IFillLockBytes::FillAppend, IFillLockBytes - Implementation, ILockBytes::ReadAt


IFillLockBytes::SetFillSize

Sets the expected size of the byte array.

HRESULT SetFillSize(

ULARGE_INTEGER uISize	// Size in bytes of a byte array object
);
Parameters

uISize

[in] Size in bytes of the byte array object that is to be filled in subsequent calls to IFillLockBytes::FillAppend.

Return Values

This function supports the standard return values E_OUTOFMEMORY, E_UNEXPECTED, E_INVALIDARG, and E_FAIL.

Remarks

If SetFillSize has not been called, any call to ILockBytes::ReadAt that attempts to access data that has not yet been written using IFillLockBytes::FillAppend or IFillLockBytes::FillAt will return a new error message, E_PENDING. After SetFillSize has been called, any call to ReadAt that attempts to access data beyond the current size, as set by SetFillSize, returns E_FAIL instead of E_PENDING.

See Also

IFillLockBytes::FillAppend, IFillLockBytes::FillAt, ILockBytes::ReadAt


IFillLockBytes::Terminate

Informs the byte array that the download has been terminated, either successfully or unsuccessfully.

HRESULT Terminate(

BOOL bCanceled	// Indicates if download was successful
);
Parameters

bCanceled

[in] Download is complete. If TRUE, the download was terminated unsuccessfully. If FALSE, the download terminated successfully.

Return Values

This function supports the standard return values E_OUTOFMEMORY, E_UNEXPECTED, E_INVALIDARG, and E_FAIL.

Remarks

After this method has been called, the byte array will no longer return E_PENDING.


IFillLockBytes - Implementation

The system provides an IFillLockBytes implementation as part of its existing implementation of Compound Files. Downloading code can instantiate an asynchronous Compound File object by calling StgOpenAsyncDocFileOnIFillLockBytes and can instantiate an asynchronous byte array wrapper object on an existing file or byte array by calling either the StgGetIFillLockBytesOnFile function or the StgGetIFillLockBytesOnILockBytes function.

When to Use

Currently, URL monikers are the only users of OLE’s asynchronous storage implementation.

Remarks

FillAppend

Writes a new block of bytes to the end of a byte array.

FillAt

The system implementation does not support this method. Returns E_NOTIMPL.

SetFillSize

Sets size of byte array. Returns E_FAIL from calls to ILockBytes::ReadAt that attempts to access data beyond the upper bound specified

Terminate

Informs byte array that a download has been terminated, either successfully or unsuccessfully.


IFont

An OLE font object is an object wrapper around a Windows font object. The OLE font object supports a number of read-write properties as well as a set of methods through its IFont interface. It supports the same set of properties (but not the methods) through the dispatch interface IFontDisp, which is derived from IDispatch to provide access to the font’s properties through Automation. The system provides a standard implementation of the font object with both interfaces.

The font object also supports the outgoing interface IPropertyNotifySink so a client can determine when font properties change. Because the font object supports at least one outgoing interface, it also implements IConnectionPointContainer and related interfaces for this purpose.

The font object provides an hFont property, which is a Windows font handle that conforms to the other attributes specified for the font. The font object delays realizing this hFont object when possible, so consecutively setting two properties on a font won’t cause an intermediate font to be realized. In addition, as an optimization, the system-implemented font object maintains a cache of font handles. Two font objects in the same process that have identical properties will return the same font handle. The font object can remove font handles from this cache at will, which introduces special considerations for clients using the hFont property. See the description for IFont::get_hFont for more details.

The font object also supports IPersistStream so it can save and load itself from an instance of IStream. An object that uses a font object internally would normally save and load the font as part of the object’s own persistence handling.

In addition, the font object supports IDataObject, which can render a property set containing the font’s attributes, allowing a client to save these properties as text.

When to Implement

Typically, you use the OLE-provided font object, which implements the IFont interface as its primary interface. It allows the caller to manage font properties and to use that font in graphical rendering. Each property in the IFont interface includes a get_PropertyName method if the property supports read access and a put_PropertyName method if the property supports write access. Most of the properties support both read and write access, and thus expose both “get” and “put” methods for these properties.

Property	Type	Access  Allowed	Description
Name	BSTR	RW	The name of the font family, e.g. Arial.
Size	CY	RW	The point size of the font, expressed in a CY type to allow for fractional point sizes.
Bold	BOOL	RW	Indicates whether the font is boldfaced.
Italic	BOOL	RW	Indicates whether the font is italicized.
Underline	BOOL	RW	Indicates whether the font is underlined.
Strikethrough	BOOL	RW	Indicates whether the font is strikethrough.
Weight	short	RW	The boldness or weight of the font.
Charset	short	RW	The character set used in the font, such as ANSI_CHARSET, DEFAULT_CHARSET, or SYMBOL_CHARSET.
hFont	HFONT	R	The Windows font handle that can be selected into a device context for rendering.
When to Use

Use this interface to change or retrieve the properties of a font object.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IFont Methods	Description
get_Name	Gets the name of the font family.
put_Name	Sets a new name for the font family.
get_Size	Gets the point size for the font.
put_Size	Sets the point size for the font.
get_Bold	Indicates whether the font is bold or not.
put_Bold	Sets the boldness property for the font.
get_Italic	Indicates whether the font is italic or not.
put_Italic	Sets the italic property for the font.
get_Underline	Indicates whether the font is underlined or not.
put_Underline	Sets the underline property for the font.
get_Strikethrough	Indicates whether the font is strikethrough or not.
put_Strikethrough	Sets the strikethrough property for the font.
get_Weight	Gets the weight (boldness) for the font.
put_Weight	Sets the weight (boldness) for the font.
get_Charset	Gets the font’s character set.
put_Charset	Sets the font’s character set.
get_hFont	Returns a Windows HFONT handle for the font described by this font object.
Clone	Creates a duplicate font object with a state identical to the current font.
IsEqual	Compares this font object to another for equality.
SetRatio	Converts the scaling factor for this font between logical units and HIMETRIC units (in which is expressed the point size in the Size property).
QueryTextMetrics	Fills a TEXTMETRIC structure describing the font.
AddRefHfont	Notifies the font object that the previously realized font identified with hFont (from IFont::GetHfont) should remain valid until IFont::ReleaseHfont is called or the font object itself is released.
ReleaseHfont	Notifies the font object that the caller that previously locked this font in the cache with IFont::AddRefHfont no longer requires the lock.
SetHdc	Provides a device context handle to the font that describes the logical mapping mode.
See Also

IFont - Ole Implementation, IFontDisp


IFont::AddRefHfont

Notifies the font object that the previously realized font identified with hFont (obtained from IFont::get_hFont) should remain valid until IFont::ReleaseHfont is called or the font object itself is released completely.

HRESULT AddRefHfont(

HFONT hfont	//Font handle returned from IFont::GetHfont
);
Parameters

hfont

[in] Font handle previously realized through IFont::GetHfont to be locked in the font object’s cache.

Return Values

The method supports the standard return values E_UNEXPECTED and E_INVALIDARG, as well as the following:

S_OK

The font was successfully locked in the cache.

See Also

IFont::get hFont, IFont:ReleaseHfont


IFont::Clone

Creates a duplicate font object with a state identical to the current font.

HRESULT Clone(

IFont** ppfont	//Indirect pointer to the new font object
);
Parameters

ppfont

[out] Indirect pointer to the IFont interface on the new font object. The caller must call IFont::Release when this new font object is no longer needed.

Return Values

The method supports the standard return values E_UNEXPECTED and E_OUTOFMEMORY, as well as the following:

S_OK

The new font object was successfully created.

E_NOTIMPL

This font object does not support cloning.

E_POINTER

The address in ppfont is not valid. For example, it may be NULL.

Remarks

Notes to Callers

The new font object is entirely independent of the first. The caller is responsible for releasing this new object when it is no longer needed. This method does not affect the reference count of the font being cloned.


IFont::get_Bold

Indicates whether the font is bold or not.

HRESULT get_Bold(

BOOL* pbold	//Pointer to the font’s bold format
);
Parameters

pbold

[out] Pointer to a caller-allocated BOOL variable that indicates whether the font is bold or not.

Return Values

S_OK

The state was retrieved successfully. If the state is indeterminate, a font object should set *pbold to FALSE and return S_OK.

E_POINTER

The address in pbold is not valid. For example, it may be NULL.

See Also

IFont::put_Bold


IFont::get_Charset

Returns the character set used in the font. The character set can be any of those defined for Windows fonts.

HRESULT get_Charset(

short* pcharset	//Pointer to the character set
);
Parameters

pcharset

[out] Pointer to the caller-allocated short variable that receives the character set value.

Return Values

S_OK

The character set was retrieved successfully.

E_POINTER

The address in pcharset is not valid. For example, it may be NULL.

See Also

IFont::put_Charset


IFont::get_hFont

Returns a Windows HFONT handle for the font described by this font object.

HRESULT get_hFont(

HFONT* phfont	//Pointer to the font handle
);
Parameters

phfont

[out] Pointer to the caller-allocated HFONT variable that receives the font handle. The caller does not own this resource and must not attempt to destroy the font.

Return Values

The method supports the standard return values E_UNEXPECTED and E_OUTOFMEMORY, as well as the following:

S_OK

The font handle was retrieved successfully.

E_POINTER

The address in phfont is not valid. For example, it may be NULL.

Remarks

Notes to Callers

The font object maintains ownership of the HFONT and can destroy it at any time without prior notification. If the caller needs to secure this font for a limited period of time, it can call IFont::AddRefHfont and IFont::ReleaseHfont.

See Also

IFont::AddRefHfont, IFont::ReleaseHfont


IFont::get_Italic

Indicates whether the font is italic or not.

HRESULT get_Italic(

BOOL* pitalic	//Pointer to the font’s italic format
);
Parameters

pitalic

[out] Pointer to the caller-allocated BOOL variable that indicates whether the font is italic.

Return Values

S_OK

The state was retrieved successfully. If the state is indeterminate, a font object should set *pitalic to FALSE and return S_OK.

E_POINTER

The address in pitalic is not valid. For example, it may be NULL.

See Also

IFont::put_Italic


IFont::get_Name

Returns a copy of the name of the font family.

HRESULT get_Name(

BSTR* pname	//Pointer to the name of the font family
);
Parameters

pname

[out] Pointer to the caller-allocated variable that receives the copy of the name. This name must be freed with SysFreeString when it is no longer needed.

Return Values

The method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The name was returned successfully.

E_POINTER

The address in pname is not valid. For example, it may be NULL.

Remarks

Notes to Callers

The caller is responsible for freeing the memory allocated for the name with SysFreeString.

See Also

IFont::put_Name


IFont::get_Size

Retrieves the point size of the font expressed in a 64-bit CY variable. The upper 32-bits of this value contains the integer point size and the lower 32-bits contains the fractional point size.

HRESULT get_Size(

CY* psize	//Pointer to the font size.
);
Parameters

psize

[out] Pointer to the caller-allocated variable that receives the size.

Return Values

The method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The size was retrieved successfully.

E_POINTER

The address in psize is not valid. For example, it may be NULL.

See Also

IFont::put_Size


IFont::get_Strikethrough

Indicates whether the font has the strikethrough property or not.

HRESULT get_Strikethrough(

BOOL* pstrikethrough	//Pointer to the current strikethrough property for the font
);
Parameters

pstrikethrough

[out] Pointer to the caller-allocated BOOL variable that indicates the current strikethrough property for the font.

Return Values

S_OK

The state was retrieved successfully. If the state is indeterminate, a font object should set *pstrikethrough to FALSE and return S_OK.

E_POINTER

The address in pstrikethrough is not valid. For example, it may be NULL.

See Also

IFont::put_Strikethrough


IFont::get_Underline

Indicates whether the font is underlined or not.

HRESULT get_Underline(

BOOL* punderline	//Pointer to the font’s underlined property
);
Parameters

punderline

[out] Pointer to the caller-allocated BOOL variable that indicates whether the font is underlined.

Return Values

S_OK

The state was retrieved successfully. If the state is indeterminate, a font object should set *punderline to FALSE and return S_OK.

E_POINTER

The address in punderline is not valid. For example, it may be NULL.

See Also

IFont::put_Underline


IFont::get_Weight

Returns the font weight, where a weight is defined as any of the FW_* values that are valid for Windows fonts.

HRESULT get_Weight(

short* pweight	//Pointer to the font weight
);
Parameters

pweight

[out] Pointer to the caller-allocated short variable that receives the current font weight.

Return Values

S_OK

The weight was retrieved successfully. If the weight is indeterminate, a font object should store FW_NORMAL in *pweight and return S_OK.

E_POINTER

The address in pweight is not valid. For example, it may be NULL.

See Also

IFont::put_Weight


IFont::IsEqual

Compares this font object to another for equivalence.

HRESULT IsEqual(

IFont* pFontOther	//Pointer to the font to compare to this font
);
Parameters

pFontOther

[in] Pointer to the IFont interface on the font object to be compared to this font. The reference count of the object referred to by this pointer is not affected by the comparison operation.

Return Values

The method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The two fonts are equivalent.

S_FALSE

The two fonts are not equivalent.

E_POINTER

The address in pFontOther is not valid. For example, it may be NULL.


IFont::put_Bold

Sets the font’s current bold property. Changing the Bold property may also change the Weight property. Setting Bold to TRUE sets the Weight to FW_BOLD (700); setting Bold to FALSE sets Weight to FW_NORMAL (400).

HRESULT put_Bold(

BOOL bold	//Bold property for the font
);
Parameters

bold

[in] New bold property for the font.

Return Values

S_OK

The bold state was changed successfully.

S_FALSE

The font does not support a bold state. Note that this is not an error condition.

See Also

IFont::get_Bold


IFont::put_Charset

Sets the font’s character set.

HRESULT put_Charset(

short charset	//Character set
);
Parameters

charset

[in] New character set for the font.

Return Values

The method supports the standard return value E_INVALIDARG, as well as the following:

S_OK

The character set was changed successfully.

See Also

IFont::get_Charset


IFont::put_Italic

Sets the font’s current italic property.

HRESULT put_Italic(

BOOL italic	//Italic property for the font
);
Parameters

italic

[in] New italic property for the font.

Return Values

S_OK

The italic state was changed successfully.

S_FALSE

The font does not support an italic state. This value is not an error condition.

See Also

IFont::get_Italic


IFont::put_Name

Specifies a new name for the font family.

HRESULT put_Name(

BSTR name	//Name of the font family
);
Parameters

name

[in] New name of the font family. This BSTR value is both allocated and freed by the caller.

Return Values

The method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The name was changed successfully.

E_POINTER

The address in name is not valid. For example, it may be NULL.

Remarks

Notes to Callers

The string value is caller allocated and the caller is responsible for freeing it after this call returns.

See Also

IFont::get_Name


IFont::put_Size

Sets the current point size of the font given a CY structure.

HRESULT put_Size(

CY size	//Size of the font
);
Parameters

size

[in] New size of the font.

Return Values

The method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The font was resized successfully.

E_POINTER

The value of the size parameter is not valid. For example, it does not contain a usable font size.

See Also

IFont::get_Size


IFont::put_Strikethrough

Sets the font’s current strikethrough property.

HRESULT put_Strikethrough(

BOOL strikethrough	//Strikethrough property for the font
);
Parameters

strikethrough

[in] New strikethrough property for the font.

Return Values

S_OK

The strikethrough state was changed successfully.

S_FALSE

The font does not support a strikethrough state. This value is not an error condition.

See Also

IFont::get_Strikethrough


IFont::put_Underline

Sets the font’s current underline property.

HRESULT put_Underline(

BOOL underline	//Underline property for the font
);
Parameters

underline

[in] New underline property for the font.

Return Values

S_OK

The underline state was changed successfully.

S_FALSE

The font does not support an underline state. This value is not an error condition.

See Also

IFont::get_Underline


IFont::put_Weight

Sets the font’s weight. This property may affect the bold property as well. Bold is set to TRUE if the weight is greater than the average of FW_NORMAL (400) and FW_BOLD (700), that is 550.

HRESULT put_Weight(

short weight	//Weight for the font
);
Parameters

weight

[in] New weight for the font.

Return Values

S_OK

The weight was changed successfully.

S_FALSE

This font does not support different weights. This value is not an error condition.

See Also

IFont::get_Weight


IFont::QueryTextMetrics

Fills a caller-allocated TEXTMETRIC structure for the font. The TEXTMETRICOLE structure is defined as a TEXTMETRICW structure on Win32 platforms. For more information on this structure, consult the Win32 Programmer’s Reference.

HRESULT QueryTextMetrics(

TEXTMETRICOLE* ptm	//Pointer to font information structure to be filled
);
Parameters

ptm

[out] Pointer to the caller-allocated structure that receives the font information.

Return Values

The method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The text metrics were returned successfully.

E_POINTER

The address in ptm is not valid. For example, it may be NULL.

Remarks

Notes to Implementers

E_NOTIMPL is not a valid return value. Font objects must always provide their font information through this call unless other errors occur.


IFont::ReleaseHfont

Notifies the font object that the caller that previously locked this font in the cache with IFont::AddRefHfont no longer requires the lock.

HRESULT ReleaseHfont(

HFONT hfont	//Font handle returned from IFont::GetHfont
);
Parameters

hfont

[in] Font handle previously realized through IFont::GetHfont. This value was passed to a previous call to IFont::AddRefHfont to lock the font, and the caller would now like to unlock the font in the cache.

Return Values

The method supports the standard return values E_UNEXPECTED and E_INVALIDARG, as well as the following:

S_OK

The font was unlocked successfully.

S_FALSE

The font was not locked in the cache. This return value is a benign notification to the caller that it may have a font reference counting problem.

See Also

IFont::AddRefHfont


IFont::SetHdc

Provides a device context to the font that describes the logical mapping mode.

HRESULT SetHdc(

HDC hdc	//Device context handle
);
Parameters

hdc

[in] Handle to the device context in which to select the font.

Return Values

The method supports the standard return value E_INVALIDARG, as well as the following:

S_OK

The font was selected successfully.

E_NOTIMPL

The font selection is not supported through this font object.

Remarks

The logical mapping mode affects the font’s internal computation of its point size so that when the caller asks for a font handle by calling IFont::GetHfont, the font is already properly scaled to the device context.

Notes to Callers

The caller retains ownership of this device context which must remain valid for the lifetime of the font object. Thus, the device context passed should be a memory device context (from the Win32 function CreateCompatibleDC) and not a screen device context (from CreateDC, GetDC, or BeginPaint) because screen device contexts are a limited system resource.


IFont::SetRatio

Converts the scaling factor for this font between logical units and HIMETRIC units. HIMETRIC units are used to express the point size in the IFont::get_Size and IFont::put_Size methods. The values passed to IFont::SetRatio are used to compute the display size of the font in logical units from the value in the Size property:

    Display Size= (cyLogical/cyHimetric) * Size

HRESULT SetRatio(

long cyLogical ,	//Font size in logical units
long cyHimetric	//Font size in HIMETRIC units
);
Parameters

cyLogical

[in] Font size in logical units.

cyHimetric

[in] Font size in HIMETRIC units.

Return Values

The method supports the standard return values E_UNEXPECTED and E_INVALIDARG, as well as the following:

S_OK

The ratio was set successfully.

See Also

IFont::get_Size, IFont::put_Size


IFont - Ole Implementation

The system provides a standard implementation of a font object with the IFont interface on top of the underlying system font support. A font object is created through the OleCreateFontIndirect function. A font object supports a number of read-write properties, as well as a set of methods, through its IFont interface and supports the same set of properties (but not the methods) through a dispatch interface IFontDisp which is derived from IDispatch to provide access to the font’s properties through Automation. The system implementation of the font object supplies both interfaces.

Remarks

The OLE-provided font object implements the complete semantics of the IFont and IFontDisp interfaces.

See Also

IFont


IFontDisp

This interface exposes a font object’s properties through Automation. It provides a subset of the IFont methods.

When to Implement

A font object implements this interface along with IFont to provide access to the font’s properties through Automation. Typically, it is not necessary to implement this interface on your own object, since there is an OLE-provided implementation of the font object.

The following table describes the dispIDs for the various font properties.

Symbol	Value
DISPID_FONT_NAME	0
DISPID_FONT_SIZE	2
DISPID_FONT_BOLD	3
DISPID_FONT_ITALIC	4
DISPID_FONT_UNDER	5
DISPID_FONT_STRIKE	6
DISPID_FONT_WEIGHT	7
DISPID_FONT_CHARSET	8
Each property in the IFontDisp interface includes a get_PropertyName method if the property supports read access and a put_PropertyName method if the property supports write access. Most of the properties support both read and write access and thus expose both “get” and “put” methods for these properties.

Property	Type	Access Allowed	Description
Name	BSTR	RW	The facename of the font, e.g. Arial.
Size	CY	RW	The point size of the font, expressed in a CY type to allow for fractional point sizes.
Bold	BOOL	RW	Indicates whether the font is boldfaced.
Italic	BOOL	RW	Indicates whether the font is italicized.
Underline	BOOL	RW	Indicates whether the font is underlined.
Strikethrough	BOOL	RW	Indicates whether the font is strikethrough.
Weight	short	RW	The boldness of the font.
Charset	short	RW	The character set used in the font, such as ANSI_CHARSET, DEFAULT_CHARSET, or SYMBOL_CHARSET.
When to Use

Use this interface to change or retrieve the properties of a font object through the IDispatch::Invoke method in Automation.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
See Also

IFont


IFontDisp - Ole Implementation

The system provides a standard implementation of a font object with the IFontDisp interface on top of the underlying system font support. A font object is created through the function OleCreateFontIndirect. A font object supports a number of read-write properties as well as a set of methods through its interface IFont and supports the same set of properties (but not the methods) through a dispatch interface IFontDisp which is derived from IDispatch to provide access to the font’s properties through Automation. The system implementation of the font object supplies both interfaces.

See Also

IFont, IFontDisp


ILayoutStorage

The ILayoutStorage interface enables an application to optimize the layout of its compound files for efficient downloading across a slow link. The goal is to enable a browser or other application to download data in the order in which it will actually be needed.

To optimize a compound file an application first saves it, then calls StgOpenLayoutDocfile to reopen the file using a special Compound Files implementation that exposes ILayoutStorage on its root storage. Once the storage is open, the application queries for a pointer to ILayoutStorage.

Using this pointer, the application can either provide explicit layout instructions or obtain them by monitoring the pattern of access to the compound file as it is loaded into memory.

•	To monitor the order in which a compound file’s data is actually accessed, the application calls ILayoutStorage::BeginMonitor, after which the Compound Files implementation assumes that any operation performed on the storage or stream object is part of the desired access pattern. When the specified compound file is completely loaded, the application halts monitoring by calling ILayoutStorage::EndMonitor.

However the desired layout information is obtained, the application calls ILayoutStorage::ReLayoutDocfile to rewrite the compound file using either the explicit layout instructions or the monitored layout access patterns.

When to Implement

You do not need to implement this interface. A special implementation of Compound Files exposes ILayoutStorage on the root storage object.

When to Use

Use ILayoutStorage to optimize your application’s compound files. The interface is exposed in dflayout.dll, which is included with the Win32 SDK. If you are a web master, you can optimize compound files exposed in your web site by using the Docfile Layout Tool (dflayout.exe), which is also included with the Win32 SDK.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
ILayout Storage Method	Description
LayoutScript	Provides explicit layout instructions.
BeginMonitor	Monitors data access to a file.
EndMonitor	Ends monitoring of data access.
ReLayoutDocfile	Rewrites file using layout information.
See Also

ILayoutStorage


ILayoutStorage::LayoutScript

Provides explicit directions for reordering the storages, streams, and controls in a compound file to match the order in which they are accessed during the download.

HRESULT LayoutScript(

StorageLayout *pStorageLayout	// Pointer to first element in an array of structures.
DWORD nEntries	// Number of elements in the array
DWORD glfInterleavedFlag	// Reserved for future use
);
Parameters

pStorageLayout

[in] Pointer to an array of StorageLayout structures.

nEntries

[in] Number of entries in the array of StorageLayout structures.

glfInterleavedFlag

[in] Reserved for future use.

Return Values

This function supports the standard return values E_OUTOFMEMORY, E_UNEXPECTED, E_INVALIDARG, and E_FAIL, as well as the following:

STG_E_INVALIDPOINTER

The storage layout pointer is invalid.

STG_E_INVALIDFLAG

The value of glfInterleavedFlag is invalid.

STG_E_PATHNOTFOUND

The new docfile name specified is invalid.

STG_E_INSUFFICIENTMEMORY

There is insufficient memory to complete the operation.

STG_E_INVALIDPARAMETER

One of the parameters is invalid.

STG_E_INUSE

BeginMonitor was called while ILayoutStorage was already monitoring.

Remarks

To provide explicit layout instructions, the application calls ILayoutStorage::LayoutScript, passing an array of StorageLayout structures. Each structure defines a single storage or stream data block and specifies where the block is to be written in the ILockBytes byte array.

An application can combine scripted layout with monitoring, as the structure of a particular compound file may dictate.

When the optimal data-layout pattern of an entire compound file has been determined, the application calls ILayoutStorage::ReLayoutDocfile to restructure the compound file to match the order in which its data sectors were accessed.

See Also

ILayoutStorage::ReLayoutDocfile, ILockBytes, StorageLayout


ILayoutStorage::BeginMonitor

Allows monitoring of a loading operation to begin. When the operation is complete, the application must call ILayoutStorage::EndMonitor.

HRESULT BeginMonitor(void);

Return Values

This function supports the standard return values E_OUTOFMEMORY, E_UNEXPECTED, E_INVALIDARG, and E_FAIL, as well as the following:

STG_E_INUSE

BeginMonitor was called while ILayoutStorage was already monitoring.

Remarks

Normally an application calls BeginMonitor before the actual loading begins. Once this method has been called, the compound file implementation regards any operation performed on the files storages and streams as part of the desired access pattern. The result is a layout script like that created explicitly by calling ILayoutStorage::LayoutScript.

Applications will usually use monitoring to obtain the access pattern of embedded objects. Monitoring also makes possible generic layout tools, such as the Docfile Layout Tool (dflayout.exe) included in the Win32 SDK, that launch existing applications and monitor their access patterns.

A call to ILayoutStorage::EndMonitor ends monitoring. Multiple calls to BeginMonitor/EndMonitor are permitted. Monitoring can also be mixed with calls to ILayoutStorage::LayoutScript.

See Also

ILayoutStorage::EndMonitor, ILayoutStorage::LayoutScript


ILayoutStorage::EndMonitor

Ends monitoring of a compound file. Must be preceded by a call to ILayoutStorage::BeginMonitor.

HRESULT EndMonitor(void);

Return Values

This function supports the standard return values E_OUTOFMEMORY, E_UNEXPECTED, E_INVALIDARG, and E_FAIL, as well as all return values for CloseHandle.

Remarks

A call to EndMonitor is generally followed by a call to ILayoutStorage::RelayoutDocfile, which uses the access pattern detected by the monitoring to restructure the compound file.

See Also

ILayoutStorage::BeginMonitor, ILayoutStorage::ReLayoutDocfile


ILayoutStorage::ReLayoutDocfile

Rewrites the compound file, using the layout script obtained through monitoring, or provided through explicit layout scripting, to create a new compound file.

HRESULT ReLayoutDocfile(

OLECHAR *pwcsNewDfName	// Pointer to name of compound file to be rewritten.
);
Parameters

pwcsNewDfName

[in] Pointer to the name of the compound file to be rewritten. This name must be a valid filename, distinct from the name of the original compound file. The original compound file will be optimized and written to the new pwcsNewDfName.

Return Values

This function supports the standard return values E_OUTOFMEMORY, E_UNEXPECTED, E_INVALIDARG, and E_FAIL, as well as the following:

STG_E_INVALIDNAME

The name passed to this function is not a valid filename.

STG_E_UNKNOWN

The layout information has been corrupted and cannot be processed.


ILockBytes

The ILockBytes interface is implemented on a byte array object that is backed by some physical storage, such as a disk file, global memory, or a database. It is used by an OLE compound file storage object to give its root storage access to the physical device, while isolating the root storage from the details of accessing the physical storage.

When to Implement

Most applications will not implement the ILockBytes interface because OLE provides implementations for the two most common situations:

File-based implementation — If you call StgCreateDocfile function to create a compound file storage object, it contains an implementation of ILockBytes that is associated with a byte array stored in a physical disk file. The compound file storage object calls the ILockBytes methods—you do not call them directly in this implementation.

Memory-based implementation — OLE also provides a byte array object based on global memory that supports an implementation of ILockBytes. You can get a pointer through a call to the CreateILockBytesOnHGlobal function). Then, to create a compound file storage object on top of that byte array object, call the StgCreateDocfileOnILockBytes function. The compound file storage object calls the ILockBytes methods — you do not call them directly in this implementation.

There are situations in which it would be useful for an application to provide its own ILockBytes implementation. For example, a database application could implement ILockBytes to create a byte array object backed by the storage of its relational tables. However, it is strongly recommended that you use the OLE-provided implementations. For a discussion of the advantages of using the OLE implementations rather than creating your own, see the StgCreateDocfileOnILockBytes API function, which creates a compound file storage object on top of a caller-provided byte array object.

If you choose to implement your own ILockBytes interface, you should consider providing custom marshaling by implementing the IMarshal interface as part of your byte array object. The reason for this is that when the OLE-provided implementations of IStorage and IStream are marshaled to another process, their ILockBytes interface pointers are also marshaled to the other process. The default marshaling mechanism creates a proxy byte array object (on which is the ILockBytes interface) that transmits method calls back to the original byte array object. Custom marshaling can improve efficiency by creating a remote byte array object that can access the byte array directly.

When to Use

The ILockBytes methods are called by the OLE implementations of IStorage and IStream on the compound file object. Unless you are implementing IStorage and IStream, you would not need to call ILockBytes methods directly. If you write your own ILockBytes implementation, you can use the StgCreateDocfileOnILockBytes function to create a compound file storage object backed by your implementation of ILockBytes.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
ILockBytes Methods	Description
ReadAt	Reads a specified number of bytes starting at a specified offset from the beginning of the byte array.
WriteAt	Writes a specified number of bytes to a specified location in the byte array.
Flush	Ensures that any internal buffers maintained by the byte array object are written out to the backing storage.
SetSize	Changes the size of the byte array.
LockRegion	Restricts access to a specified range of bytes in the byte array.
UnlockRegion	Removes the access restriction on a range of bytes previously restricted with ILockBytes::LockRegion.
Stat	Retrieves a STATSTG structure for this byte array object.


ILockBytes::Flush

Ensures that any internal buffers maintained by the ILockBytes implementation are written out to the underlying physical storage.

HRESULT Flush(void);

Return Values

S_OK

The flush operation was successful.

STG_E_ACCESSDENIED

The caller does not have permission to access the byte array.

STG_E_MEDIUMFULL

The flush operation is not completed because there is no space left on the storage device.

E_FAIL

General failure writing data.

STG_E_TOOMANYFILESOPEN

Under certain circumstances, Flush does a dump-and-close to flush, which can lead to a return value of STG_E_TOOMANYFILESOPEN if no file handles are available.

STG_E_INVALIDHANDLE

An underlying file has been prematurely closed, or the correct floppy disk has been replaced by an invalid one.

Remarks

ILockBytes::Flush flushes internal buffers to the underlying storage device.

The OLE-provided implementation of compound files calls this method during a transacted commit operation to provide a two-phase commit process that protects against loss of data.

See Also

IStorage::Commit, ILockBytes—File-Based Implementation, ILockBytes—Global Memory Implementation


ILockBytes::LockRegion

Restricts access to a specified range of bytes in the byte array.

HRESULT LockRegion(

ULARGE_INTEGER libOffset,	//Specifies the byte offset for the beginning of the range
ULARGE_INTEGER cb,	//Specifies the length of the range in bytes
DWORD dwLockType	//Specifies the type of restriction on accessing the specified range
);
Parameters

libOffset

[in]Specifies the byte offset for the beginning of the range.

cb

[in]Specifies, in bytes, the length of the range to be restricted.

dwLockType

[in]Specifies the type of restrictions being requested on accessing the range. This parameter uses one of the values from the LOCKTYPE enumeration.

Return Values

S_OK

The specified range of bytes was locked.

STG_E_INVALIDFUNCTION

Locking is not supported at all or the specific type of lock requested is not supported.

STG_E_ACCESSDENIED

Access denied because the caller has insufficient permission, or another caller has the file open and locked.

STG_E_LOCKVIOLATION

Access denied because another caller has the file open and locked.

STG_E_INVALIDHANDLE

An underlying file has been prematurely closed, or the correct floppy disk has been replaced by an invalid one.

Remarks

ILockBytes::LockRegion restricts access to the specified range of bytes. Once a region is locked, attempts by others to gain access to the restricted range must fail with the STG_E_ACCESSDENIED error.

The byte range can extend past the current end of the byte array. Locking beyond the end of an array is useful as a method of communication between different instances of the byte array object without changing data that is actually part of the byte array. For example, an implementation of ILockBytes for compound files could rely on locking past the current end of the array as a means of access control, using specific locked regions to indicate permissions currently granted.

The dwLockType parameter specifies one of three types of locking, using values from the LOCKTYPE enumeration. The types are as follows: locking to exclude other writers, locking to exclude other readers or writers, and locking that allows only one requestor to obtain a lock on the given range. This third type of locking is usually an alias for one of the other two lock types, and permits an Implementer to add other behavior as well. A given byte array might support either of the first two types, or both.

To determine the lock types supported by a particular ILockBytes implementation, you can examine the grfLocksSupported member of the STATSTG structure returned by a call to ILockBytes::Stat.

Any region locked with ILockBytes::LockRegion must later be explicitly unlocked by calling ILockBytes::UnlockRegion with exactly the same values for the libOffset, cb, and dwLockType parameters. The region must be unlocked before the stream is released. Two adjacent regions cannot be locked separately and then unlocked with a single unlock call.

Notes to Callers

Since the type of locking supported is optional and can vary in different implementations of ILockBytes, you must provide code to deal with the STG_E_INVALIDFUNCTION error.

Notes to Implementers

Support for this method depends on how the storage object built on top of the ILockBytes implementation is used. If you know that only one storage object at any given time can be opened on the storage device that underlies the byte array, then your ILockBytes implementation does not need to support locking. However, if multiple simultaneous openings of a storage object are possible, then region locking is needed to coordinate them.

A LockRegion implementation can choose to support all, some, or none of the lock types. For unsupported lock types, the implementation should return STG_E_INVALIDFUNCTION.

See Also

ILockBytes::Stat, ILockBytes::UnlockRegion, IStream::LockRegion, LOCKTYPE, ILockBytes—File-Based Implementation, ILockBytes—Global Memory Implementation


ILockBytes::ReadAt

Reads a specified number of bytes starting at a specified offset from the beginning of the byte array object.

HRESULT ReadAt(

ULARGE_INTEGER ulOffset,	//Specifies the starting point for reading data
void *pv,	//Points to the buffer into which the data is read
ULONG cb,	//Specifies the number of bytes to read
ULONG *pcbRead	//Pointer to location that contains actual number of bytes read
);
Parameters

ulOffset

[in]Specifies the starting point from the beginning of the byte array for reading data.

pv

[in]Points to the buffer into which the byte array is read.

cb

[in]Specifies the number of bytes of data to attempt to read from the byte array.

pcbRead

[out]Pointer to a location where this method writes the actual number of bytes read from the byte array. You can set this pointer to NULL to indicate that you are not interested in this value. In this case, this method does not provide the actual number of bytes read.

Return Values

S_OK

Indicates that the specified number of bytes were read, or the maximum number of bytes were read up to the end of the byte array.

E_FAIL

Data could not be read from the byte array.

E_PENDING

Asynchronous Storage only: Part or all of the data to be read is currently unavailable. For more information see IFillLockBytes and [insert jump to asynchronous storage overview, which is to come].

STG_E_ACCESSDENIED

The caller does not have permission to access the byte array.

STG_E_READFAULT

The number of bytes to be read does not equal the number of bytes that were acutally read.

Remarks

ILockBytes::ReadAt reads bytes from the byte array object. It reports the number of bytes that were actually read. This value may be less than the number of bytes requested if an error occurs or if the end of the byte array is reached during the read.

It is not an error to read less than the specified number of bytes if the operation encounters the end of the byte array. Note that this is the same end-of-file behavior as found in MS-DOS FAT file system files.

See Also

ILockBytes::WriteAt, ILockBytes—File-Based Implementation, ILockBytes—Global Memory Implementation


ILockBytes::SetSize

Changes the size of the byte array.

HRESULT SetSize(

ULARGE_INTEGER cb	//Specifies the new size of the byte array in bytes
);
Parameter

cb

[in]Specifies the new size of the byte array as a number of bytes.

Return Values

S_OK

The size of the byte array was successfully changed.

STG_E_ACCESSDENIED

The caller does not have permission to access the byte array.

STG_E_MEDIUMFULL

The byte array size is not changed because there is no space left on the storage device.

Remarks

ILockBytes::SetSize changes the size of the byte array. If the cb parameter is larger than the current byte array, the byte array is extended to the indicated size by filling the intervening space with bytes of undefined value, as does ILockBytes::WriteAt, if the seek pointer is past the current end-of-stream.

If the cb parameter is smaller than the current byte array, the byte array is truncated to the indicated size.

Notes to Callers

Callers cannot rely on STG_E_MEDIUMFULL being returned at the appropriate time because of cache buffering in the operating system or network. However, callers must be able to deal with this return code because some ILockBytes implementations might support it.

See Also

ILockBytes::ReadAt, ILockBytes::WriteAt, ILockBytes—File-Based Implementation, ILockBytes—Global Memory Implementation


ILockBytes::Stat

Retrieves a STATSTG structure containing information for this byte array object.

HRESULT Stat(

STATSTG *pstatstg,	//Location for STATSTG structure
DWORD grfStatFlag	//Values taken from the STATFLAG enumeration
);
Parameters

pstatstg

[out]Points to a STATSTG structure in which this method places information about this byte array object. The pointer is NULL if an error occurs.

grfStatFlag

[in]Specifies whether this method should supply the pwcsName member of the STATSTG structure through values taken from the STATFLAG enumeration. If the STATFLAG_NONAME is specified, the pwcsName member of STATSTG is not supplied, thus saving a memory allocation operation. The other possible value, STATFLAG_DEFAULT, indicates that all STATSTG members be supplied.

Return Values

S_OK

The STATSTG structure was successfully returned at the specified location.

E_OUTOFMEMORY

The STATSTG structure was not returned due to a lack of memory for the name field in the structure.

STG_E_ACCESSDENIED

The STATSTG structure was not returned because the caller did not have access to the byte array.

STG_E_INSUFFICIENTMEMORY

The STATSTG structure was not returned, due to a lack of memory.

STG_E_INVALIDFLAG

The value for the grfStateFlag parameter is not valid.

STG_E_INVALIDPOINTER

The value for the pStatStg parameter is not valid.

Remarks

ILockBytes::Stat should supply information about the byte array object in a STATSTG structure.

See Also

STATFLAG, STATSTG, ILockBytes—File-Based Implementation, ILockBytes—Global Memory Implementation


ILockBytes::UnlockRegion

Removes the access restriction on a previously locked range of bytes.

HRESULT UnlockRegion(

ULARGE_INTEGER libOffset,	//Specifies the byte offset for the beginning of the range
ULARGE_INTEGER cb,	//Specifies the length of the range in bytes
DWORD dwLockType	//Specifies the access restriction previously placed on the range
);
Parameters

libOffset

[in]Specifies the byte offset for the beginning of the range.

cb

[in]Specifies, in bytes, the length of the range that is restricted.

dwLockType

[in]Specifies the type of access restrictions previously placed on the range. This parameter uses a value from the LOCKTYPE enumeration.

Return Values

S_OK

The byte range was unlocked.

STG_E_INVALIDFUNCTION

Locking is not supported at all or the specific type of lock requested is not supported.

STG_E_LOCKVIOLATION

The requested unlock cannot be granted.

Remarks

ILockBytes::UnlockRegion unlocks a region previously locked with a call to ILockBytes::LockRegion. Each region locked must be explicitly unlocked, using the same values for the libOffset, cb, and dwLockType parameters as in the matching calls to ILockBytes::LockRegion. Two adjacent regions cannot be locked separately and then unlocked with a single unlock call.

See Also

ILockBytes::LockRegion, LOCKTYPE, ILockBytes—File-Based Implementation, ILockBytes—Global Memory Implementation


ILockBytes::WriteAt

Writes the specified number of bytes starting at a specified offset from the beginning of the byte array.

HRESULT WriteAt(

ULARGE_INTEGER ulOffset,	//Specifies the starting point for writing data
void const *pv,	//Points to the buffer containing the data to be written
ULONG cb,	//Specifies the number of bytes to write
ULONG *pcbWritten	//Pointer to location that contains actual number of bytes written
);
Parameters

ulOffset

[in]Specifies the starting point from the beginning of the byte array for the data to be written.

pv

[in]Points to the buffer containing the data to be written.

cb

[in]Specifies the number of bytes of data to attempt to write into the byte array.

pcbRead

[out]Pointer to a location where this method specifies the actual number of bytes written to the byte array. You can set this pointer to NULL to indicate that you are not interested in this value. In this case, this method does not provide the actual number of bytes written.

Return Values

S_OK

Indicates that the specified number of bytes were written.

E_FAIL

A general failure occurred during the write.

E_PENDING

Asynchronous Storage only: Part or all of the data to be written is currently unavailable. For more information see IFillLockBytes and [insert jump to asynchronous storage overview, which is to come].

STG_E_ACCESSDENIED

The caller does not have sufficient permissions for writing this byte array.

STG_E_WRITEFAULT

The number of bytes to be written does not equal the number of bytes that were acutally written.

STG_E_MEDIUMFULL

The write operation was not completed because there is no space left on the storage device. The actual number of bytes written is still returned in pcbWritten.

Remarks

ILockBytes::WriteAt writes the specified data at the specified location in the byte array. The number of bytes actually written must always be returned in pcbWritten, even if an error is returned. If the byte count is zero bytes, the write operation has no effect.

If ulOffset is past the end of the byte array and cb is greater than zero, ILockBytes::WriteAt increases the size of the byte array. The fill bytes written to the byte array are not initialized to any particular value.

See Also

ILockBytes::ReadAt, ILockBytes::SetSize, ILockBytes—File-Based Implementation, ILockBytes—Global Memory Implementation


ILockBytes - File-Based Implementation

Implemented on a byte array object underlying an OLE compound file storage object, and designed to read and write directly to a disk file.

When to Use

Methods of ILockBytes are called from the compound file implementations of IStorage and IStream on the compound file storage object created through a call to StgCreateDocfile, so you do not need to call them directly.

Remarks

ILockBytes::ReadAt

This method queries the wrapped pointer for the requested interface.

ILockBytes::WriteAt

This method queries the wrapped pointer for the requested interface.

ILockBytes::Flush

This method queries the wrapped pointer for the requested interface.

ILockBytes::SetSize

This method queries the wrapped pointer for the requested interface.

ILockBytes::LockRegion

The dwLockTypes parameter is set to LOCK_ONLYONCE OR LOCK_EXCLUSIVE, which will allow or restrict access to locked regions.

ILockBytes::UnlockRegion

This method unlocks the region locked by ILockBytes::LockRegion.

ILockBytes::Stat

The OLE-provided IStorage::Stat implementation calls the ILockBytes::Stat method to retrieve information about the byte array object. If there is no reasonable name for the byte array, the OLE-provided ILockBytes::Stat method returns NULL in the pwcsName field of the STATSTG structure.

See Also

ILockBytes, IStorage, IStream


ILockBytes - Global Memory Implementation

Implemented on a byte array object underlying an OLE compound file storage object, and designed to read and write directly to global memory.

When to Use

Methods of ILockBytes are called from the compound file implementations of IStorage and IStream on the compound file storage object created through a call to StgCreateDocfile.

Remarks

ILockBytes::ReadAt

This method queries the wrapped pointer for the requested interface.

ILockBytes::WriteAt

This method queries the wrapped pointer for the requested interface.

ILockBytes::Flush

This method queries the wrapped pointer for the requested interface.

ILockBytes::SetSize

This method queries the wrapped pointer for the requested interface.

ILockBytes::LockRegion

This implementation does not support locking, so dwLocksType is set to zero. It is the caller’s responsibility to ensure accesses are valid and mutually exclusive.

ILockBytes::UnlockRegion

This implementation does not support locking.

ILockBytes::Stat

The OLE-provided IStorage::Stat implementation calls the ILockBytes::Stat method to retrieve information about the byte array object. If there is no reasonable name for the byte array, the OLE-provided ILockBytes::Stat method returns NULL in the pwcsName field of the STATSTG structure.

See Also

ILockBytes, IStorage, IStream


IMalloc

Allocates, frees, and manages memory.

When to Implement

In general, you should not implement IMalloc, instead using the OLE implementation, which is guaranteed to be thread-safe in managing task memory. You get a pointer to the OLE task allocator object’s IMalloc through a call to the CoGetMalloc function.

When to Use

Call the methods of IMalloc to allocate and manage memory. The OLE libraries and object handlers also call the IMalloc methods to manage memory. Object handlers should call CoGetMalloc to get a pointer to the IMalloc implementation on the task allocator object, and use the implementation of those methods to manage task memory.

The IMalloc methods Alloc, Free, and Realloc are similar to the C library functions malloc, free, and realloc. For debugging, refer to the functions CoRegisterMallocSpy and CoRevokeMallocSpy.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IMalloc Methods	Description
Alloc	Allocates a block of memory.
Realloc	Changes the size of a previously allocated block of memory.
Free	Frees a previously allocated block of memory.
GetSize	Returns the size in bytes of a previously allocated block of memory.
DidAlloc	Determines if this instance of IMalloc was used to allocate the specified block of memory.
HeapMinimize	Minimizes the heap by releasing unused memory to the operating system.
See Also

CoGetMalloc, IMallocSpy, CoRegisterMallocSpy, CoRevokeMallocSpy


IMalloc::Alloc

Allocates a block of memory.

void * Alloc(

ULONG cb	//Size of the requested memory block in bytes
);
Parameter

cb

[in] Size , in bytes, of the memory block to be allocated.

Return Values

If successful, Alloc returns a pointer to the allocated memory block.

NULL

If insufficient memory is available, Alloc returns NULL.

Remarks

The IMalloc::Alloc method allocates a memory block in essentially the same way that the C Library malloc function does.

The initial contents of the returned memory block are undefined − there is no guarantee that the block has been initialized, so you should initialize it in your code. The allocated block may be larger than cb bytes because of the space required for alignment and for maintenance information.

If cb is zero, IMalloc::Alloc allocates a zero-length item and returns a valid pointer to that item. If there is insufficient memory available, IMalloc::Alloc returns NULL.

Note  Applications should always check the return value from this method, even when requesting small amounts of memory, because there is no guarantee the memory will be allocated.

See Also

IMalloc::Free, IMalloc::Realloc, CoTaskMemAlloc


IMalloc::DidAlloc

Determines if this allocator was used to allocate the specified block of memory.

int DidAlloc(

void *pv	//Pointer to the memory block
);
Parameter

pv

[in] Pointer to the memory block; can be a NULL pointer, in which case, -1 is returned.

Return Values

1

The memory block was allocated by this IMalloc instance.

0

The memory block was not allocated by this IMalloc instance.

-1

DidAlloc is unable to determine whether or not it allocated the memory block.

Remarks

Calling IMalloc::DidAlloc is useful if a application is using multiple allocations, and needs to know whether a previously allocated block of memory was allocated by a particular allocation.

See Also

IMalloc::Alloc, IMalloc::HeapMinimize, IMalloc::Realloc


IMalloc::Free

Frees a previously allocated block of memory.

void Free(

void * pv	//Pointer to the memory block to be freed
);
Parameter

pv

[in] Pointer to the memory block to be freed.

Remarks

IMalloc:Free frees a block of memory previously allocated through a call to IMalloc::Alloc or IMalloc::Realloc. The number of bytes freed equals the number of bytes that were allocated. After the call, the memory block pointed to by pv is invalid and can no longer be used.

Note  The pv parameter can be NULL. If so, this method has no effect.

See Also

IMalloc::Alloc, IMalloc::Realloc, CoTaskMemFree


IMalloc::GetSize

Returns the size (in bytes) of a memory block previously allocated with IMalloc::Alloc or IMalloc::Realloc.

ULONG GetSize(

void *pv	//Pointer to the memory block for which the size is requested
);
Parameter

pv

[in] Pointer to the memory block for which the size is requested.

Return Value

The size of the allocated memory block in bytes or, if pv is a NULL pointer, -1.

Remarks

To get the size in bytes of a memory block, the block must have been previously allocated with IMalloc::Alloc or IMalloc::Realloc. The size returned is the actual size of the allocation, which may be greater than the size requested when the allocation was made.

See Also

IMalloc::Alloc, IMalloc::Realloc


IMalloc::HeapMinimize

Minimizes the heap as much as possible by releasing unused memory to the operating system, coalescing adjacent free blocks and committing free pages.

void HeapMinimize();

Remarks

Calling IMalloc::HeapMinimize is useful when an application has been running for some time and the heap may be fragmented.

See Also

IMalloc::Alloc, IMalloc::Free, IMalloc::Realloc


IMalloc::Realloc

Changes the size of a previously allocated memory block.

void *Realloc(

void *pv,	//Pointer to memory block to be reallocated
ULONG cb	//Size of the memory block in bytes
);
Parameters

pv

[in] Pointer to the memory block to be reallocated. The pointer can have a NULL value, as discussed in the following Remarks section.

cb

[in] Size of the memory block (in bytes) to be reallocated. It can be zero, as discussed in the following remarks.

Return Values

Reallocated memory block

Memory block successfully reallocated.

NULL

Insufficient memory or cb is zero and pv is not NULL.

Remarks

IMalloc::Realloc reallocates a block of memory, but does guarantee that the contents of the returned memory block are initialized. Therefore, the caller is responsible for intializing it in code, subsequent to the reallocation. The allocated block may be larger than cb bytes because of the space required for alignment and for maintenance information.

The pv argument points to the beginning of the memory block. If pv is NULL, IMalloc::Realloc allocates a new memory block in the same way that IMalloc::Alloc does. If pv is not NULL, it should be a pointer returned by a prior call to IMalloc::Alloc.

The cb argument specifies the size (in bytes) of the new block. The contents of the block are unchanged up to the shorter of the new and old sizes, although the new block can be in a different location. Because the new block can be in a different memory location, the pointer returned by IMalloc::Realloc is not guaranteed to be the pointer passed through the pv argument. If pv is not NULL and cb is zero, then the memory pointed to by pv is freed.

IMalloc::Realloc returns a void pointer to the reallocated (and possibly moved) memory block. The return value is NULL if the size is zero and the buffer argument is not NULL, or if there is not enough memory available to expand the block to the given size. In the first case, the original block is freed; in the second, the original block is unchanged.

The storage space pointed to by the return value is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value.

See Also

IMalloc::Alloc, IMalloc::Free


IMallocSpy

The IMallocSpy interface is a debugging interface that allows application developers to monitor (spy on) memory allocation, detect memory leaks and simulate memory failure in calls to IMalloc methods.

Caution  The IMallocSpy interface is intended to be used only to debug application code under development. Do not ship this interface to retail customers of your application, because it causes severe performance degradation and could conflict with user-installed software to produce unpredictable results.

When to Implement

Implement this interface to debug memory allocation during application development.

When to Use

When an implementation of IMallocSpy is registered with CoRegisterMallocSpy, OLE calls the pair of IMallocSpy methods around the corresponding IMalloc method. You would not make direct calls to IMallocSpy methods. The OLE SDK contains a sample implementation of IMallocSpy. The call to the pre-method through the return from the corresponding post-method is guaranteed to be thread-safe in multi-threaded operations.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IMallocSpy Methods	Description
PreAlloc	Called before invoking IMalloc::Alloc, and may extend or modify the allocation to store debug information.
PostAlloc	Called after invoking IMalloc::Alloc.
PreFree	Called before invoking IMalloc::Free.
PostFree	Called after invoking IMalloc::Free.
PreRealloc	Called before invoking IMalloc::Realloc.
PostRealloc	Called after invoking IMalloc::Realloc.
PreGetSize	Called before invoking IMalloc::GetSize.
PostGetSize	Called after invoking IMalloc::GetSize.
PreDidAlloc	Called before invoking IMalloc::DidAlloc.
PostDidAlloc	Called after invoking IMalloc::DidAlloc.
PreHeapMinimize	Called before invoking IMalloc::DidAlloc.
PostHeapMinimize	Called after invoking IMalloc::HeapMinimize.
See Also

IMalloc, CoGetMalloc, CoRegisterMallocSpy


IMallocSpy::PreAlloc

Called just prior to invoking IMalloc::Alloc.

ULONG PreAlloc(

ULONG cbRequest	//Byte count passed to IMalloc::Alloc
);
Parameter

cbRequest

[in] Number of bytes specified in the allocation request the caller is passing to IMalloc::Alloc.

Return Value

The byte count actually passed to IMalloc::Alloc, which should be greater than or equal to the value of cbRequest.

Remarks

The IMallocSpy::PreAlloc implementation may extend and/or modify the allocation to store debug-specific information with the allocation.

PreAlloc can force memory allocation failure by returning 0, allowing testing to ensure that the application handles allocation failure gracefully in all cases. In this case, PostAlloc is not called and Alloc returns NULL. Forcing allocation failure is effective only if cbRequest is not equal to 0. If PreAlloc is forcing failure by returning NULL, PostAlloc is not called. However, if IMalloc::Alloc encounters a real memory failure and returns NULL, PostAlloc is called.

The call to PreAlloc through the return from PostAlloc is guaranteed to be thread safe.

See Also

IMalloc::Alloc, IMallocSpy::PostAlloc, CoRegisterMallocSpy, CoRevokeMallocSpy


IMallocSpy::PostAlloc

Called just after invoking IMalloc::Alloc, taking as input a pointer to the IMalloc::Alloc caller’s allocation, and returning a pointer to the actual allocation.

void * PostAlloc(

void * pActual	//Pointer to the allocation actually done by IMalloc::Alloc
);
Parameter

pActual

[in] Pointer to the allocation done by IMalloc::Alloc.

Return Value

A pointer to the beginning of the memory block actually allocated. This pointer is also returned to the caller of IMalloc::Alloc. If debug information is written at the front of the caller’s allocation, this should be a forward offset from pActual. The value is the same as pActual if debug information is appended or if no debug information is attached.

Remarks

When a spy object implementing IMallocSpy is registered with CoRegisterMallocSpy, OLE calls IMallocSpy::PostAlloc after any call to IMalloc::Alloc. It takes as input a pointer to the allocation done by the call to IMalloc::Alloc, and returns a pointer to the beginning of the total allocation, which could include a forward offset from the other value if IMallocSpy::Prealloc was implemented to attach debug information to the allocation in this way. If not, the same pointer is returned, and also becomes the return value to the caller of IMalloc::Alloc.

See Also

IMalloc::Alloc, IMallocSpy::PreAlloc, CoRegisterMallocSpy, CoRevokeMallocSpy


IMallocSpy::PreDidAlloc

Called by OLE just prior to invoking IMalloc::DidAlloc.

void * PreDidAlloc(

void * pRequest,	//Pointer the caller is passing to IMalloc::DidAlloc
BOOL fSpyed	//Whether pRequest was allocated while this spy was active
);
Parameters

pRequest

[in] Pointer the caller is passing to IMalloc::DidAlloc.

fSpyed

[in] TRUE if the allocation was done while this spy was active.

Return Value

The pointer for which allocation status is determined. This pointer is passed to PostDidAlloc as the fActual parameter.

Remarks

When a spy object implementing IMallocSpy is registered with CoRegisterMallocSpy, OLE calls this method immediately before any call to IMalloc::DidAlloc. This method is included for completeness and consistency — it is not anticipated that developers will implement significant functionality in this method.

See Also

IMalloc::DidAlloc, IMallocSpy::PostDidAlloc, CoRegisterMallocSpy, CoRevokeMallocSpy


IMallocSpy::PostDidAlloc

Called just after invoking IMalloc::DidAlloc.

int PostDidAlloc(

void * pRequest,	//Original pointer passed to IMalloc::DidAlloc
BOOL fSpyed,	//Whether the allocation was done while this spy was active
int fActual	//Whether pRequest was actual value used in IMalloc call
);
Parameters

pRequest

[in] Pointer specified in the original call to IMalloc::DidAlloc.

fSpyed

[in] TRUE if the allocation was done while this spy was active.

fActual

[in] Actual value returned by IMalloc::DidAlloc.

Return Value

The value returned to the caller of IMalloc::DidAlloc.

Remarks

When a spy object implementing IMallocSpy is registered with CoRegisterMallocSpy, OLE calls this method immediately after any call to IMalloc::DidAlloc. This method is included for completeness and consistency — it is not anticipated that developers will implement significant functionality in this method.

For convenience, pRequest, the original pointer passed in the call to IMalloc::DidAlloc, is passed to PostDidAlloc. In addition, the parameter fActual is a boolean that indicates whether this value was actually passed to IMalloc::DidAlloc. If not, it would indicate that IMallocSpy::PreDidAlloc was implemented to alter this pointer for some debugging purpose.

The fSpyed parameter is a boolean that indicates whether the allocation was done while the current spy object was active.

See Also

IMalloc::DidAlloc, IMallocSpy::PreDidAlloc, CoRegisterMallocSpy, CoRevokeMallocSpy


IMallocSpy::PreFree

Called just before invoking IMalloc::Free to ensure that the pointer passed to IMalloc::Free points to the beginning of the actual allocation.

void * PreFree(

void * pRequest,	//Pointer is passing to IMalloc::Free
BOOL fSpyed	//TRUE if this memory was allocated while the spy was active
);
Parameters

pRequest

[in] Pointer to the block of memory that the caller is passing to IMalloc::Free.

fSpyed

[in] TRUE if the pRequest parameter of IMallocSpy::PreFree was allocated while the spy was installed. This value is also passed to IMallocSpy::PostFree.

Return Value

The actual pointer to pass to IMalloc::Free.

Remarks

If IMallocSpy::PreAlloc modified the original allocation request passed to IMalloc::Alloc (or IMalloc::Realloc), IMallocSpy::PreFree must supply a pointer to the actual allocation, which OLE will pass to IMalloc::Free. For example, if the PreAlloc/PostAlloc pair attached a header used to store debug information to the beginning of the caller’s allocation, PreFree must return a pointer to the beginning of this header, so all of the block that was allocated can be freed.

See Also

IMalloc::Free, IMallocSpy::PostFree, CoRegisterMallocSpy, CoRevokeMallocSpy


IMallocSpy::PostFree

Called just after invoking IMalloc::Free.

void PostFree(

BOOL fSpyed	//Whether the memory block to be freed was allocated while the spy is active
);
Parameter

fSpyed

[in] TRUE if the memory block to be freed was allocated while the current spy was active, otherwise FALSE.

Remarks

When a spy object implementing IMallocSpy is registered with CoRegisterMallocSpy, OLE calls this method immediately after any call to IMalloc::Free. This method is included for completeness and consistency — it is not anticipated that developers will implement significant functionality in this method. On return, the fSpyed parameter simply indicates whether the memory was freed while the current spy was active.

See Also

IMalloc::Free, IMallocSpy::PreFree, CoRegisterMallocSpy, CoRevokeMallocSpy


IMallocSpy::PreGetSize

Called by OLE just prior to any call to IMalloc::GetSize.

void * PreGetSize(

void * pRequest,	//Pointer the caller is passing to IMalloc::GetSize
BOOL fSpyed	//TRUE if allocation was done while this spy was active
);
Parameters

pRequest

[in] Pointer the caller is passing to IMalloc::GetSize.

fSpyed

[in] TRUE if the allocation was done while the spy was active.

Return Value

Pointer to the actual allocation for which the size is to be determined.

Remarks

The PreGetSize method receives as its pRequest parameter the pointer the caller is passing to IMalloc::GetSize. It must then return a pointer to the actual allocation, which may have altered pRequest in the implementation of either the PreAlloc or PreRealloc methods of IMallocSpy. The pointer to the true allocation is then passed to IMalloc::GetSize as its pv parameter.

IMalloc::GetSize then returns the size determined, and OLE passes this value to IMallocSpy::PostGetSize in cbActual.

Note  The size determined by IMalloc::GetSize is the value returned by the Win32 function HeapSize. On Windows NT, this is the size originally requested. On Windows 95, memory allocations are done on eight-byte boundaries. For example, a memory allocation request of 27 bytes on Windows NT would return an allocation of 32 bytes and GetSize would return 27. On Windows 95, the same request would return an allocation of 28 bytes and GetSize would return 28. Implementers of IMallocSpy::PostGetSize cannot assume, for example, that if cbActual is sizeof(debug_header), that the value is the actual size of the user’s allocation.

See Also

IMalloc::GetSize, IMallocSpy::PostGetSize, CoRegisterMallocSpy, CoRevokeMallocSpy


IMallocSpy::PostGetSize

Called just after invoking IMalloc::GetSize.

ULONG PostGetSize(

ULONG cbActual,	//Actual size of the allocation
BOOL fSpyed	//Whether the allocation was done while a spy was active
);
Parameters

cbActual

[in] Actual number of bytes in the allocation, as returned by IMalloc::GetSize.

fSpyed

[in] TRUE if the allocation was done while a spy was active.

Return Values

The same value returned by IMalloc::GetSize, which is the size of the allocated memory block in bytes.

Remarks

The size determined by IMalloc::GetSize is the value returned by the Win32 function HeapSize. On Windows NT, this is the size originally requested. On Windows 95, memory allocations are done on eight-byte boundaries. For example, a memory allocation request of 27 bytes on Windows NT would return an allocation of 32 bytes and GetSize would return 27. On Windows 95, the same request would return an allocation of 28 bytes and GetSize would return 28. Implementers of IMallocSpy::PostGetSize cannot assume, for example, that if cbActual is sizeof(debug_header), that the value is the actual size of the user’s allocation.

See Also

IMalloc::GetSize, IMallocSpy::PreGetSize, CoRegisterMallocSpy, CoRevokeMallocSpy


IMallocSpy::PreHeapMinimize

Called just prior to invoking IMalloc::HeapMinimize.

void PreHeapMinimize(void);

Remarks

This method is included for completeness; it is not anticipated that developers will implement significant functionality in this method.

See Also

IMalloc::HeapMinimize, IMallocSpy::PostHeapMinimize, CoRegisterMallocSpy, CoRevokeMallocSpy


IMallocSpy::PostHeapMinimize

Called just after invoking IMalloc::HeapMinimize.

void PostHeapMinimize(void);

Remarks

When a spy object implementing IMallocSpy is registered with CoRegisterMallocSpy, OLE calls this method immediately after any call to IMalloc::Free. This method is included for completeness and consistency — it is not anticipated that developers will implement significant functionality in this method.

See Also

IMalloc::HeapMinimize, IMallocSpy::PreHeapMinimize, CoRegisterMallocSpy, CoRevokeMallocSpy


IMallocSpy::PreRealloc

Called just before invoking IMalloc::Alloc.

ULONG PreRealloc(

void * pRequest,	//Pointer the caller is passing to IMalloc::Realloc
ULONG cbRequest,	//Byte count the caller is passing to IMalloc::Realloc
void ** ppNewRequest,	//Indirect pointer to be reallocated
BOOL fSpyed	//Whether the original allocation was “spyed”
);
Parameters

pRequest

[in] Pointer specified in the original call to IMalloc::Realloc, indicating the the memory block to be reallocated.

cbRequest

[in] Memory block’s byte count as specified in the original call to IMalloc::Realloc.

ppNewRequest

[out] Indirect pointer to the actual memory block to be reallocated. This may be different from the pointer in pRequest if the implementation of IMallocSpy::PreRealloc extends or modifies the reallocation. This is an out pointer and should always be stored by PreRealloc.

fSpyed

[in] TRUE if the original allocation was done while the spy was active.

Return Value

The actual byte count to be passed to IMalloc::Realloc.

Remarks

The IMallocSpy::PreRealloc implementation may extend and/or modify the allocation to store debug-specific information with the allocation. Thus, the ppNewRequest parameter may differ from pRequest, a pointer to the request specified in the original call to IMalloc::Realloc.

PreRealloc can force memory allocation failure by returning 0, allowing testing to ensure that the application handles allocation failure gracefully in all cases. In this case, PostRealloc is not called and Realloc returns NULL. However, if IMalloc::Realloc encounters a real memory failure and returns NULL, PostRealloc is called. Forcing allocation failure is effective only if cbRequest is not equal to 0.

See Also

IMalloc::Realloc, IMallocSpy::PostRealloc, CoRegisterMallocSpy, CoRevokeMallocSpy


IMallocSpy::PostRealloc

Called after invoking IMalloc::Realloc.

void * PostRealloc(

void * pActual,	//Pointer returned by IMalloc::Realloc
BOOL fSpyed	//Whether the original allocation was “spyed”
);
Parameters

pActual

[in] Pointer to the memory block reallocated by IMalloc::Realloc.

fSpyed

[in] If TRUE, the original memory allocation was done while the spy was active.

Return Values

A pointer to the beginning of the memory block actually allocated. This pointer is also returned to the caller of IMalloc::Realloc. If debug information is written at the front of the caller’s allocation, it should be a forward offset from pActual. The value should be the same as pActual if debug information is appended or if no debug information is attached.

See Also

IMalloc::Realloc, IMallocSpy::PreRealloc, CoRegisterMallocSpy, CoRevokeMallocSpy


IMarshal

The IMarshal interface enables an COM object to define and manage the marshaling of its interface pointers. The alternative is to use COM’s default implementation, the preferred choice in all but a few special cases (see “When to Implement”).

“Marshaling” is the process of packaging data into packets for transmission to a different process or machine. “Unmarshaling” is the process of recovering that data at the receiving end. In any given call, method arguments are marshaled and unmarshaled in one direction, while return values are marshaled and unmarshaled in the other.

Although marshaling applies to all data types, interface pointers require special handling. The fundamental problem is how client code running in one address space can correctly dereference a pointer to an interface on an object residing in a different address space. COM’s solution is for a client application to communicate with the original object through a surrogate object, or proxy, which lives in the client’s process. The proxy holds a reference to an interface on the original object and hands the client a pointer to an interface on itself. When the client calls an interface method on the original object, its call is actually going to the proxy. Therefore, from the client’s point of view, all calls are in-process.

On receiving a call, the proxy marshals the method arguments and, through some means of interprocess communication, such as RPC, passes them along to code in the server process, which unmarshals the arguments and passes them to the original object. This same code marshals return values for transmission back to the proxy, which unmarshals the values and passes them to the client application.

IMarshal provides methods for creating, initializing, and managing a proxy in a client process; it does not dictate how the proxy should communicate with the original object. COM’s default implementation of IMarshal uses RPC. When you implement this interface yourself, you are free to choose any method of interprocess communication you deem to be appropriate for your application — shared memory, named pipe, window handle, RPC — in short, whatever works.

When to Implement

Implement IMarshal only when you believe that you can realize significant optimizations to COM’s default implementation. In practice, this will rarely be the case. However, there are occasions where implementing IMarshal may be preferred:

•	The objects you are writing keep their state in shared memory. In this case, both the original process and the client process uses proxies that refer to the shared memory. This type of custom marshaling is possible only if the client process is on the same machine as the original process. OLE-provided implementations of IStorage and IStream are examples of this type of custom marshaling.

•	The objects you are writing are immutable, that is, their state does not change after creation. Instead of forwarding method calls to the original objects, you simply create copies of those objects in the client process. This technique avoids the cost of switching from one process to another. Some monikers are examples of immutable objects; if you are implementing your own moniker class, you should evaluate the costs and benefits of implementing IMarshal on your moniker objects.

•	Objects that themselves are proxy objects can use custom marshaling to avoid creating proxies to proxies. Instead, the existing proxy can refer new proxies back to the original object. This capability is important for the sake of both efficiency and robustness.

•	Your server application wants to manage how calls are made across the network without affecting the interface exposed to clients. For example, if an end user were making changes to a database record, the server might want to cache the changes until the user has committed them all, at which time the entire transaction would be forwarded in a single packet. Using a custom proxy would enable the caching and batching of changes in this way.

When you choose to implement IMarshal, you must do so for both your original object and the proxy you create for it. When implementing the interface on either object or proxy, you simply return E_NOTIMPL for the methods that are not implemented.

COM uses your implementation of IMarshal in the following manner: When it’s necessary to create a remote interface pointer to your object (that is, when a pointer to your object is passed as an argument in a remote function call), COM queries your object for the IMarshal interface. If your object implements it, COM uses your IMarshal implementation to create the proxy object. If your object does not implement IMarshal, COM uses its default implementation.

How you choose to structure the proxy is entirely up to you. You can write the proxy to use whatever mechanisms you deem appropriate for communicating with the original object. You can also create the proxy as either a stand-alone object or as part of a larger aggregation such as a handler. However you choose to structure the proxy, it must implement IMarshal to work at all. You must also generate a CLSID for the proxy to be returned by your implementation of IMarshal::GetUnmarshalClass on the original object.

When to Use

COM calls this interface as part of system-provided marshaling support. COM’s calls are wrapped in calls to CoMarshalInterface and CoUnmarshalInterface. Your code typically will not need to call this interface. Special circumstances where you might choose to do so are discussed in the “Notes to Callers” section for each method.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IMarshal Methods	Description
GetUnmarshalClass	Returns CLSID of unmarshaling code.
GetMarshalSizeMax	Returns size of buffer needed during marshaling.
MarshalInterface	Marshals an interface pointer.
UnmarshalInterface	Unmarshals an interface pointer.
ReleaseMarshalData	Destroys a marshaled data packet.
DisconnectObject	Severs all connections.
See Also

IStdMarshalInfo


IMarshal::DisconnectObject

Forcibly releases all external connections to an object. The object’s server calls the object’s implementation of this method prior to shutting down.

HRESULT DisconnectObject(

DWORD dwReserved	//Reserved for future use
);
Parameter

dwReserved

[in] Reserved for future use; must be zero. To ensure compatibility with future use, DisConnectObject must not check for zero.

Return Values

The method supports the standard return value E_FAIL, as well as the following:

S_OK

The object was disconnected successfully.

Remarks

This method is implemented on the object, not the proxy.

Notes to Callers

The usual case in which this method is called occurs when an end user forcibly closes an OLE server that has one or more running objects that implement IMarshal. Prior to shutting down, the server calls the CoDisconnectObject helper function to sever external connections to all its running objects. For each object that implements IMarshal, however, this function calls IMarshal::DisconnectObject, so that each object that manages its own marshaling can take steps to notify its proxy that it is about to shut down.

Notes to Implementers

As part of its normal shutdown code, a server should call the CoDisconnectObject function, which in turn calls IMarshal::DisconnectObject, on each of its running objects that implements IMarshal.

The outcome of any implementation of this method should be to enable a proxy to respond to all subsequent calls from its client by returning RPC_E_DISCONNECTED or CO_E_OBJECTNOTCONNECTED rather than attempting to forward the calls on to the original object. It is up to the client, of course, to destroy the proxy.

If you are implementing this method for an immutable object, such as a moniker, your implementation doesn’t need to do anything because such objects are typically copied whole into the client’s address space. Therefore, they have neither a proxy nor a connection to the original object. For more information on marshaling immutable objects, see IMarshal, “When to Implement.”

See Also

CoDisconnectObject


IMarshal::GetMarshalSizeMax

Returns an upper bound on the number of bytes needed to marshal the specified interface pointer on the specified object.

HRESULT GetMarshalSizeMax(

REFIID riid,	//Reference to the identifier of the interface to be marshaled
void *pv,	//Interface pointer to be marshaled
DWORD dwDestContext,	//Destination process
void * pvDestContext,	//Reserved for future use
DWORD mshlflags,	//Reason for marshaling
ULONG * pSize	//Pointer to upper-bound value
);
Parameters

riid

[in] Reference to the identifier of the interface to be marshaled.

pv

[in] Interface pointer to be marshaled; can be NULL.

dwDestContext

[in] Destination context where the specified interface is to be unmarshaled. Values for dwDestContext come from the enumeration MSHCTX. Currently, unmarshaling can occur either in another apartment of the current process (MSHCTX_INPROC) or in another process on the same computer as the current process (MSHCTX_LOCAL).

pvDestContext

[in] Reserved for future use; must be NULL.

mshlflags

[in] Flag indicating whether the data to be marshaled is to be transmitted back to the client process — the normal case — or written to a global table, where it can be retrieved by multiple clients. Valid values come from the MSHLFLAGS enumeration.

pSize

[out] Pointer to the upper bound on the amount of data to be written to the marshaling stream.

Return Values

The method supports the standard return value E_FAIL, as well as the following:

S_OK

The maximum size was returned successfully.

E_NOINTERFACE

The specified interface was not supported.

Remarks

This method is called indirectly, in a call to CoGetMarshalSizeMax, by whatever code in the server process is responsible for marshaling a pointer to an interface on an object. This marshaling code is usually a stub generated by COM for one of several interfaces that can marshal a pointer to an interface implemented on an entirely different object. Examples include the IClassFactory and IOleItemContainer interfaces. For purposes of discussion, the code responsible for marshaling a pointer is here called the “marshaling stub.”

To create a proxy for an object, COM requires two pieces of information from the original object: the amount of data to be written to the marshaling stream and the proxy’s CLSID.

The marshaling stub obtains these two pieces of information with successive calls to CoGetMarshalSizeMax and CoMarshalInterface.

Note to Callers

The marshaling stub, through a call to CoGetMarshalSizeMax, calls the object’s implementation of this method to preallocate the stream buffer that will be passed to IMarshal::MarshalInterface.

You do not explicitly call this method if you are:

•	Implementing existing COM interfaces, or

•	Defining your own custom interfaces, using the Microsoft Interface Definition Language (MIDL).

In both cases, the MIDL-generated stub automatically makes the call.

If you are not using MIDL to define your own interface (see “Writing a Custom Interface”), your marshaling stub does not have to call GetMarshalSizeMax, though doing so is highly recommended. An object knows better than an interface stub what the maximum size of a marshaling data packet is likely to be. Therefore, unless you are providing an automatically growing stream that is so efficient that the overhead of expanding it is insignificant, you should call this method even when implementing your own interfaces.

The value returned by this method is only guaranteed to be valid as long as the internal state of the object being marshaled does not change. Therefore, the actual marshaling should be done immediately after this function returns, or the stub runs the risk that the object, because of some change in state, might require more memory to marshal than it originally indicated.

Notes to Implementers

Your implementation of MarshalInterface will use this buffer to write marshaling data into the stream. If the buffer is too small, the marshaling operation will fail. Therefore, the value returned by this method must be a conservative estimate of the amount of data that will, in fact, be needed to marshal the interface. Violation of this requirement should be treated as a catastrophic error.

In a subsequent call to IMarshal::MarshalInterface, your IMarshal implementation cannot rely on the caller actually having called GetMarshalSizeMax beforehand. It must still be wary of STG_E_MEDIUMFULL errors returned by the stream and be prepared to handle them gracefully.

To ensure that your implementation of GetMarshalSizeMax will continue to work properly as new destination contexts are supported in the future, delegate marshaling to COM’s default implementation for all dwDestContext values that your implementation does not understand. To delegate marshaling to COM’s default implementation, call the CoGetStandardMarshal function.

See Also

CoGetMarshalSizeMax, IMarshal::MarshalInterface


IMarshal::GetUnmarshalClass

Returns the CLSID that COM uses to locate the DLL containing the code for the corresponding proxy. COM loads this DLL to create an uninitialized instance of the proxy.

HRESULT GetUnmarshalClass(

REFIID riid,	//Reference to the identifier of the interface to be marshaled
void * pv,	//Interface pointer being marshaled
DWORD dwDestContext,	//Destination process
void * pvDestContext,	//Reserved for future use
DWORD mshlflags,	//Reason for marshaling
CLSID * pCid	//Pointer to CLSID of proxy
);
Parameters

riid

[in] Reference to the identifier of the interface to be marshaled.

pv

[in] Pointer to the interface to be marshaled; can be NULL if the caller does not have a pointer to the desired interface.

dwDestContext

[in] “Destination context” where the specified interface is to be unmarshaled. Values for dwDestContext come from the enumeration MSHCTX. Currently, unmarshaling can occur either in another apartment of the current process (MSHCTX_INPROC) or in another process on the same computer as the current process (MSHCTX_LOCAL).

pvDestContext

[in] Reserved for future use; must be NULL.

mshlflags

[in] Whether the data to be marshaled is to be transmitted back to the client process — the normal case — or written to a global table, where it can be retrieved by multiple clients. Valid values come from the MSHLFLAGS enumeration.

pCid

[out] Pointer to the CLSID to be used to create a proxy in the client process.

Return Value

Returns S_OK if successful; otherwise, S_FALSE.

Remarks

This method is called by whatever code in the server process may be responsible for marshaling a pointer to an interface on an object. This marshaling code is usually a stub generated by COM for one of several interfaces that can marshal a pointer to an interface implemented on an entirely different object. Examples include the IClassFactory and IOleItemContainer interfaces. For purposes of this discussion, the code responsible for marshaling a pointer is called the “marshaling stub.”

To create a proxy for an object, COM requires two pieces of information from the original object: the amount of data to be written to the marshaling stream and the proxy’s CLSID.

The marshaling stub obtains these two pieces of information with successive calls to CoGetMarshalSizeMax and CoMarshalInterface.

Note to Callers

The marshaling stub calls the object’s implementation of this method to obtain the CLSID to be used in creating an instance of the proxy. The client, upon receiving the CLSID, loads the DLL listed for it in the system registry.

You do not explicitly call this method if you are:

•	Implementing existing COM interfaces, or

•	Defining your own interfaces using the Microsoft Interface Definition Language (MIDL).

In both cases, the stub automatically makes the call. See “Writing a Custom Interface.”

If you are not using MIDL to define your own interface, your stub must call this method, either directly or indirectly, to get the CLSID that the client-side COM Library needs to create a proxy for the object implementing the interface.

If the caller has a pointer to the interface to be marshaled, it should, as a matter of efficiency, use the pv parameter to pass that pointer. In this way, an implementation that may use such a pointer to determine the appropriate CLSID for the proxy does not have to call IUnknown::QueryInterface on itself. If a caller does not have a pointer to the interface to be marshaled, it can pass NULL.

Notes to Implementers

COM calls GetUnmarshalClass to obtain the CLSID to be used for creating a proxy in the client process. The CLSID to be used for a proxy is normally not that of the original object (see “Notes to Implementers” for the exception), but one you will have generated (using the GUIDGEN.EXE tool supplied with the Win32 SDK) specifically for your proxy object.

Implement this method for each object that provides marshaling for one or more of its interfaces. The code responsible for marshaling the object writes the CLSID, along with the marshaling data, to a stream; COM extracts the CLSID and data from the stream on the receiving side.

If your proxy implementation consists simply of copying the entire original object into the client process, thereby eliminating the need to forward calls to the original object, the CLSID returned would be the same as that of the original object. This strategy, of course, is advisable only for objects that are not expected to change.

If the pv parameter is NULL and your implementation needs an interface pointer, it can call IUnknown::QueryInterface on the current object to get it. The pv parameter exists merely to improve efficiency.

To ensure that your implementation of GetUnmarshalClass continues to work properly as new destination contexts are supported in the future, delegate marshaling to COM’s default implementation for all dwDestContext values that your implementation does not handle. To delegate marshaling to COM’s default implementation, call the CoGetStandardMarshal function.


IMarshal::MarshalInterface

Writes into a stream the data required to initialize a proxy object in some client process.

HRESULT MarshalInterface(

IStream *pStm,	//Pointer to stream used for marshaling
REFIID riid,	//Reference to the identifier of the interface to be marshaled
void *pv,	//Interface pointer to be marshaled
DWORD dwDestContext,	//Destination context
void *pvDestContext,	//Reserved for future use
DWORD mshlflags	//Reason for marshaling
);
Parameters

pStm

[in] Pointer to the stream to be used during marshaling.

riid

[in] Reference to the identifier of the interface to be marshaled. This interface must be derived from the IUnknown interface.

pv

[in] Pointer to the interface pointer to be marshaled; can be NULL if the caller does not have a pointer to the desired interface.

dwDestContext

[in] Destination context where the specified interface is to be unmarshaled. Values for dwDestContext come from the enumeration MSHCTX. Currently, unmarshaling can occur either in another apartment of the current process (MSHCTX_INPROC) or in another process on the same computer as the current process (MSHCTX_LOCAL).

pvDestContext

[in] Reserved for future use; must be zero.

mshlflags

[in] Whether the data to be marshaled is to be transmitted back to the client process — the normal case — or written to a global table, where it can be retrieved by multiple clients. Valid values come from the MSHLFLAGS enumeration.

Return Values

The method supports the standard return value E_FAIL, as well as the following:

S_OK

The interface pointer was marshaled successfully.

E_NOINTERFACE

The specified interface is not supported.

STG_E_MEDIUMFULL

The stream is full.

Remarks

This method is called indirectly, in a call to CoMarshalInterface, by whatever code in the server process may be responsible for marshaling a pointer to an interface on an object. This marshaling code is usually a stub generated by COM for one of several interfaces that can marshal a pointer to an interface implemented on an entirely different object. Examples include the IClassFactory and IOleItemContainer interfaces. For purposes of this discussion, the code responsible for marshaling a pointer is called the “marshaling stub.”

Notes to Callers

Normally, rather than calling IMarshal::MarshalInterface directly, your marshaling stub instead should call the CoMarshalInterface function, which contains a call to this method. The stub makes this call to command an object to write its marshaling data into a stream. The stub then either passes the marshaling data back to the client process or writes it to a global table, where it can be unmarshaled by multiple clients. The stub’s call to CoMarshalInterface is normally preceded by a call to CoGetMarshalSizeMax, to get the maximum size of the stream buffer into which the marshaling data will be written.

You do not explicitly call this method if you are:

•	Implementing existing COM interfaces, or

•	Defining your own interfaces using the Microsoft Interface Definition Language (MIDL).

In both cases, the MIDL-generated stub automatically makes the call.

If you are not using MIDL to define your own interface, your marshaling stub must call this method, either directly or indirectly.Your stub implementation should call MarshalInterface immediately after its previous call to IMarshal::GetMarshalSizeMax returns. Because the value returned by GetMarshalSizeMax is guaranteed to be valid only so long as the internal state of the object being marshaled does not change, a delay in calling MarshalInterface runs the risk that the object will require a larger stream buffer than originally indicated.

If the caller has a pointer to the interface to be marshaled, it should, as a matter of efficiency, use the pv parameter to pass that pointer. In this way, an implementation that may use such a pointer to determine the appropriate CLSID for the proxy does not have to call IUnknown::QueryInterface on itself. If a caller does not have a pointer to the interface to be marshaled, it can pass NULL.

Notes to Implementers

Your implementation of IMarshal::MarshalInterface must write to the stream whatever data is needed to initialize the proxy on the receiving side. Such data would include a reference to the interface to be marshaled, a MSHLFLAGS value specifying whether the data should be returned to the client process or written to a global table, and whatever is needed to connect to the object, such as a named pipe, handle to a window, or pointer to an RPC channel.

Your implementation should not assume that the stream is large enough to hold all the data. Rather, it should gracefully handle a STG_E_MEDIUMFULL error. Just before exiting, your implementation should position the seek pointer in the stream immediately after the last byte of data written.

If the pv parameter is NULL and your implementation needs an interface pointer, it can call IUnknown::QueryInterface on the current object to get it. The pv parameter exists merely to improve efficiency.

To ensure that your implementation of MarshalInterface continues to work properly as new destination contexts are supported in the future, delegate marshaling to COM’s default implementation for all dwDestContext values that your implementation does not handle. To delegate marshaling to COM’s default implementation, call the CoGetStandardMarshal helper function.

Using the MSHLFLAGS enumeration, callers can specify whether an interface pointer is to be marshaled back to a single client or written to a global table, where it can be unmarshaled by multiple clients. You must make sure that your object can handle calls from the multiple proxies that might be created from the same initialization data.

See Also

CoGetStandardMarshal, IMarshal::GetMarshalSizeMax, IMarshal::GetUnmarshalClass, IMarshal::UnmarshalInterface, Writing a Custom Interface


IMarshal::ReleaseMarshalData

Destroys a marshaled data packet.

HRESULT ReleaseMarshalData(

IStream * pStm	//Pointer to stream used for unmarshaling
);
Parameter

pStm

[in] Pointer to a stream that contains the data packet to be destroyed.

Return Values

The method supports the standard return value E_FAIL, as well as the following:

S_OK

The data packet was released successfully.

IStream errors

This function can also return any of the stream-access error values for the IStream interface.

Remarks

If an object’s marshaled data packet does not get unmarshaled in the client process space, and the packet is no longer needed. The client calls ReleaseMarshalData on the proxy’s IMarshal implementation to instruct the object to destroy the data packet. The call occurs within the CoReleaseMarshalData function. The data packet serves as an additional reference on the object, and releasing the data is like releasing an interface pointer by calling IUnknown::Release.

If the marshaled data packet somehow does not arrive in the client process, or ReleaseMarshalData is not successfully re-created in the proxy, COM can call this method on the object itself.

Notes to Callers

You will rarely if ever have occasion to call this method yourself. A possible exception would be if you were to implement IMarshal on a class factory for a class object on which you are also implementing IMarshal. In this case, if you are marshaling the object to a table, where it can be retrieved by multiple clients, you might, as part of your unmarshaling routine, call ReleaseMarshalData to release the data packet for each proxy.

Notes to Implementers

If your implementation stores state information about marshaled data packets, you can use this method to release the state information associated with the data packet represented by pStm. Your implementation should also position the seek pointer in the stream past the last byte of data.

See Also

CoUnMarshalInterface, CoReleaseMarshalData


IMarshal::UnmarshalInterface

Initializes a newly created proxy and returns an interface pointer to that proxy.

HRESULT UnmarshalInterface(

IStream * pStm,	//Pointer to the stream to be unmarshaled
REFIID riid,	//Reference to the identifier of the interface to be unmarshaled
void ** ppv	//Indirect pointer to interface
);
Parameters

pStm

[in] Pointer to the stream from which the interface pointer is to be unmarshaled.

riid

[in] Reference to the identifier of the interface to be unmarshaled.

ppv

[out] Indirect pointer to the interface.

Return Values

The method supports the standard return value E_FAIL, as well as the following:

S_OK

The interface pointer was unmarshaled successfully.

E_NOINTERFACE

The specified interface was not supported.

Remarks

The COM library in the process where unmarshaling is to occur calls the proxy’s implementation of this method.

Notes to Callers

You do not call this method directly. There are, however, some situations in which you might call it indirectly through a call to CoUnmarshalInterface. For example, if you are implementing a stub, your implementation would call CoUnmarshalInterface when the stub receives an interface pointer as a parameter in a method call.

Notes to Implementers

The proxy’s implementation should read the data written to the stream by the original object’s implementation of IMarshal::MarshalInterface and use that data to initialize the proxy object whose CLSID was returned by the marshaling stub’s call to the original object’s implementation of IMarshal::GetUnmarshalClass.

To return the appropriate interface pointer, the proxy implementation can simply call IUnknown::QueryInterface on itself, passing the riid and ppv parameters. However, your implementation of UnmarshalInterface is free to create a different object and, if necessary, return a pointer to it.

Just before exiting, even if exiting with an error, your implementation should reposition the seek pointer in the stream immediately after the last byte of data read.

See Also

IMarshal::GetUnmarshalClass, IMarshal::MarshalInterface


IMarshal - Default Implementation

COM uses its own internal implementation of the IMarshal interface to marshal any object that does not provide its own implementation. COM makes this determination by querying the object for IMarshal. If the interface is missing, COM defaults to its internal implementation.

COM’s default implementation of IMarshal uses a generic proxy for each object, and creates individual stubs and proxies, as they are needed, for each interface implemented on the object. This mechanism is necessary because COM cannot know in advance what particular interfaces a given object may implement. Developers who do not use COM’s default marshaling, electing instead to write their own proxy and marshaling routines, know at compile time all the interfaces to be found on their objects and therefore understand exactly what marshaling code is required. COM, in providing marshaling support for all objects, must do so at run time.

The interface proxy resides in the client process; the interface stub, in the server. Together, each pair handles all marshaling for its interface. The job of each interface proxy is to marshal arguments and unmarshal return values and out parameters that are passed back and forth in subsequent calls to its interface. The job of each interface stub is to unmarshal function arguments and pass them along to the original object, then marshal the return values and out parameters that the object returns.

Proxy and stub communicate by means of an RPC (remote procedure call) channel, which utilizes the system’s RPC infrastructure for interprocess communication. The RPC channel implements a single interface IRpcChannelBuffer, an internal interface to which both interface proxies and stubs hold a pointer. The proxy and stub call the interface to obtain a marshaling packet, send the data to their counterpart, and destroy the packet when they are done. The interface stub also holds a pointer to the original object.

For any given interface, the proxy and stub are both implemented as instances of the same class, which is listed for each interface in the system registry under the label ProxyStubClsid32 (or ProxyStubClsid on 16-bit systems). This entry maps the interface’s IID to the CLSID of its proxy and stub objects. When COM needs to marshal an interface, it looks in the system registry to obtain the appropriate CLSID. The server identified by this CLSID implements both the interface proxy and interface stub.

Most often, the class to which this CLSID refers is automatically generated by a tool whose input is a description of the function signatures and semantics of a given interface, written in some interface description language. While using such a language is highly recommended and encouraged for accuracy’s sake, doing so is by no means required. Proxies and stubs are merely Component Object Model components used by the RPC infrastructure and, as such, can be written in any manner desired so long as the correct external contracts are upheld. The programmer who designs a new interface is responsible for ensuring that all interface proxies and stubs that ever exist agree on the representation of their marshaled data.

When created, interface proxies are always aggregated into a larger proxy, which represents the object as a whole. This object proxy also aggregates COM’s generic proxy object, which is known as the proxy manager. The proxy manager implements two interfaces: IUnknown and IMarshal. All of the other interfaces that may be implemented on an object are exposed in its object proxy through the aggregation of individual interface proxies. A client holding a pointer to the object proxy “believes” it holds a pointer to the actual object.

A proxy representing the object as a whole is required in the client process so that a client can distinguish calls to the same interfaces implemented on entirely different objects. Such a requirement does not exist in the server process, however, where the object itself resides, because all interface stubs communicate only with the objects for which they were created. No other connection is possible.

Interface stubs, by contrast with interface proxies, are not aggregated, because there is no need that they appear to some external client to be part of a larger whole. When connected, an interface stub is given a pointer to the server object to which it should forward method invocations that it receives. Although it is useful to refer conceptually to a “stub manager,” meaning whatever pieces of code and state in the server-side RPC infrastructure that service the remoting of a given object, there is no direct requirement that the code and state take any particular, well-specified form.

The first time a client requests a pointer to an interface on a particular object, COM loads an IClassFactory stub in the server process and uses it to marshal the first pointer back to the client. In the client process, COM loads the generic proxy for the class factory object and calls its implementation of IMarshal to unmarshal that first pointer. COM then creates the first interface proxy and hands it a pointer to the RPC channel. Finally, COM returns the IClassFactory pointer to the client, which uses it to call IClassFactory::CreateInstance, passing it a reference to the interface.

Back in the server process, COM now creates a new instance of the object, along with a stub for the requested interface. This stub marshals the interface pointer back to the client process, where another object proxy is created, this time for the object itself. Also created is a proxy for the requested interface, a pointer to which is returned to the client. With subsequent calls to other interfaces on the object, COM will load the appropriate interface stubs and proxies as needed.

When a new interface proxy is created, COM hands it a pointer to the proxy manager’s implementation of IUnknown, to which it delegates all QueryInterface calls. Each interface proxy implements two interfaces of its own: the interface it represents and IRpcProxyBuffer. The interface proxy exposes its own interface directly to clients, which can obtain its pointer by calling QueryInterface on the proxy manager. Only COM, however, can call IRpcProxyBuffer, which it uses to connect and disconnect the proxy to the RPC channel. A client cannot query an interface proxy to obtain a pointer to the IRpcProxyBuffer interface.

On the server side, each interface stub implements IRpcStubBuffer, an internal interface. The server code acting as a stub manager calls IRpcStubBuffer::Connect and passes the interface stub the IUnknown pointer of its object.

When an interface proxy receives a method invocation, it obtains a marshaling packet from its RPC channel through a call to IRpcChannelBuffer::GetBuffer. The process of marshaling the arguments will copy data into the buffer. When marshaling is complete, the interface proxy invokes IRpcChannelBuffer::SendReceive to send the marshaled packet to the corresponding interface stub. When IRpcChannelBuffer::SendReceive returns, the buffer into which the arguments were marshaled will have been replaced by a new buffer containing the return values marshaled from the interface stub. The interface proxy unmarshals the return values, invokes IRpcChannelBuffer::FreeBuffer to free the buffer, then returns the return values to the original caller of the method.

It is the implementation of IRpcChannelBuffer::SendReceive that actually sends the request to the server process and that knows how to identify the server process and, within that process, the object to which the request should be sent. The channel implementation also knows how to forward the request on to the appropriate stub manager in that process. The interface stub unmarshals the arguments from the provided buffer, invokes the indicated method on the server object, and marshals the return values back into a new buffer, allocated by a call to IRpcchannelBuffer::GetBuffer. The channel then transmits the return data packet back to the interface proxy, which is still in the middle of IRpcchannelBuffer::SendReceive, which returns to the interface proxy.

A particular instance of an interface proxy can be used to service more than one interface, so long as two conditions are met. First, the IIDs of the affected interfaces must be mapped to the the appropriate ProxyStubClsid in the system registry. Second, the interface proxy must support calls to QueryInterface from one supported interface to the other interfaces, as usual, as well as from IUnknown and IRpcProxyBuffer.

A single instance of an interface stub can also service more than one interface, but only if that set of interfaces has a strict single-inheritance relationship. This restriction exists because the stub can direct method invocations to multiple interfaces only where it knows in advance which methods are implemented on which interfaces.

Both proxies and stubs will at various times have need to allocate or free memory. Interface proxies, for example, will need to allocate memory in which to return out parameters to their caller. In this respect, interface proxies and interface stubs are just normal COM components, in that they should use the standard task allocator (see CoGetMalloc).

When to Use

You should use COM’s default implementation of IMarshal except in those very few cases where your application has special requirements that COM’s default implementation does not address, or where you can achieve optimizations over the marshaling code COM has provided. For examples of such special cases, see IMarshal, “When to Implement.”

See Also

IMarshal


IMessageFilter

The IMessageFilter interface provides OLE servers and applications with the ability to selectively handle incoming and outgoing OLE messages while waiting for responses from synchronous calls. Filtering messages helps to ensure that calls are handled in a manner that improves performance and avoids deadlocks. OLE messages can be synchronous, asynchronous, or input-synchronized; the majority of interface calls are synchronous.

Synchronous calls require the caller to wait for a reply before continuing. OLE enters a modal loop while waiting for the reply. During this time, the caller is still able to receive and dispatch incoming messages.

Asynchronous calls allow the caller to proceed without waiting for a response from the called object. Today, in OLE, the only asynchronous calls are to an object’s IAdviseSink interface. While the object is processing an asynchronous call, it is prohibited from making any synchronous calls back to the calling object.

Input-synchronized calls require the called object to complete the call before relinquishing control, ensuring that behaviors such as focus management and type-ahead function correctly.

When to Implement

You will probably want to implement your own message filter. The default implementation provided by COM offers only minimal message filtering capability. Although message filtering is no longer as significant as it was with 16-bit applications, since the size of the message queue is now virtually unlimited, you still should implement IMessageFilter as a way of resolving deadlocks.

COM will call your implementation of IMessageFilter to find out if an application is blocking, so that you can task-switch to that application and give the user an opportunity to deal with the situation. For example, if you have Microsoft Word talking to Microsoft Excel, with Excel running in the background in formula mode, in which formulas are being applied to data on the worksheet to compute different or “what if” results, Excel won’t check all calls, thereby blocking further action. IMessageFilter would put up a dialog box indicating which task was blocking and provide the user with an opportunity to deal with the deadlock.

Although it is probably obvious from the method descriptions, it may still be useful to point out that HandleIncomingCall is an object-based method and RetryRejectedCall and MessagePending are client-based methods. Clearly, the object must have some way of handling incoming calls from external clients. HandleIncomingCall provides that functionality by allowing the object to handle or defer some incoming calls and reject others. The client also needs to know how an object is going to handle its call. so that it can respond appropriately. The client needs to know if a call has been rejected, or just deferred temporarily, so that it can retry rejected calls after some specified time. The client also needs to be able to respond to Windows messages, while at the same time waiting for replies to pending messages.

You will use CoRegisterMessageFilter to register your message filter. Once registered, COM then calls your message filter instead of the default implementation.

When to Use

You don’t call this interface directly. It’s provided by the OLE server or application and called by the COM.

Application Shutdown with WM_QUERYENDSESSION and WM_ENDSESSION

When a user exits Windows, each open application receives a WM_QUERYENDSESSION message followed by a WM_ENDSESSION message, provided the exit is not canceled. These messages are invoked with SendMessage, which unfortunately restricts the initiation of all outgoing LRPC calls. This is a problem for container applications that have open embedded objects when they receive the shutdown request because LRPC is needed to close those objects.

Container and container/server applications with open documents typically display a message box on receipt of the WM_QUERYENDSESSION message that asks if the user wants to save changes before exiting. A positive response is usually the default. The recommendation for dealing with the situation described above is for the application to display an alternate message box asking if the user wants to discard changes; a negative response should be the default. If the user chooses to discard the changes, TRUE should be returned for WM_QUERYENDSESSION, which .signals to Windows that it can terminate. If the user does not want to discard the changes, FALSE should be returned. No attempt should be made to close or release running embeddings.

Server applications should return TRUE for WM_QUERYENDSESSION without prompting the user.On receipt of a WM_ENDSESSION message, all OLE applications should execute the normal close sequence for each application's documents and/or objects. At the same time, you should ignore any errors resulting from any cross-process calls or calls to IUnknown::Release. All storage pointers (IStorage and IStream interface pointers) must be released to properly flush any temporary files maintained by the compound file implementation of structured storage.

See Also

CoRegisterMessageFilter

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IMessageFilter Methods	Description
HandleIncomingCall	Provides a single entry point for incoming calls.
RetryRejectedCall	Provides application with opportunity to display a dialog box offering retry or cancel or task switching options.
MessagePending	Indicates a Windows message has arrived while OLE is waiting to respond to a remote call.
See Also

OleUIBusy, OLEUIBUSY, In the WIN32 SDK: “Messages and Message Queues”


IMessageFilter::HandleInComingCall

An object-based method that provides the ability to filter or reject incoming calls (or call backs) to an object or a process. This method is called prior to each method invocation originating outside the current process.

DWORD HandleInComingCall(

DWORD dwCallType,	//Type of incoming call
HTASK threadIDCaller,	//Task handle calling this task
DWORD dwTickCount,	//Elapsed tick count
LPINTERFACEINFO lpInterfaceInfo	//Pointer to INTERFACEINFO structure
);
Parameters

dwCallType

[in] Kind of incoming call that has been received. Valid values are from the enumeration CALLTYPE. See the chapter on enumerations for details.

threadIDCaller

[in] Handle of the task calling this task.

dwTickCount

[in] Elapsed tick count since the outgoing call was made if dwCallType is not CALLTYPE_TOPLEVEL. If dwCallType is CALLTYPE_TOPLEVEL, dwTickCount should be ignored.

lpInterfaceInfo

[in] Pointer to an INTERFACEINFO structure, which identifies the object, the interface, and the method making the call. In the case of DDE calls, lpInterfaceInfo can be NULL because the DDE layer does not return interface information.

Return Values

SERVERCALL_ISHANDLED

The application might be able to process the call.

SERVERCALL_REJECTED

The application cannot handle the call due to an unforeseen problem, such as network unavailability, or if it is in the process of terminating.

SERVERCALL_RETRYLATER

The application cannot handle the call at this time. For example, an application might return this value when it is in a user-controlled modal state.

Remarks

If implemented, IMessageFilter::HandleInComingCall is called by OLE when an incoming OLE message is received.

Depending on an application’s current state, a call is either accepted and processed or rejected (permanently or temporarily). If SERVERCALL_ISHANDLED is returned, the application may be able to process the call, though success depends on the interface for which the call is destined. If the call cannot be processed, OLE returns RPC_E_CALL_REJECTED.

Input-synchronized and asynchronous calls are dispatched even if the application returns SERVERCALL_REJECTED or SERVERCALL_RETRYLATER.

IMessageFilter::HandleInComingCall should not be used to hold off updates to objects during operations such as band printing. For that purpose, use IViewObject::Freeze.

You can also use IMessageFilter::HandleInComingCall to set up the application’s state so the call can be processed in the future.

See Also

IViewObject::Freeze, CALLTYPE, INTERFACEINFO


IMessageFilter::MessagePending

A client-based method called by COM when a Windows message appears in an OLE application’s message queue while the application is waiting for a reply to a remote call. Handling input while waiting for an outgoing call to finish can introduce complications. The application should determine whether to process the message without interrupting the call, continue waiting, or cancel the operation.

DWORD MessagePending(

HTASK threadIDCallee,	//Called applications task handle
DWORD dwTickCount,	//Elapsed tick count
DWORD dwPendingType	//Call type
);
Parameters

threadIDCallee

[in] Task handle of the called application that has not yet responded.

dwTickCount

[in] Number of ticks since the call was made. It is calculated from the Windows GetTickCount function.

dwPendingType

[in] Type of call made during which a message or event was received. Valid values are from the enumeration PENDINGTYPE (where PENDINGTYPE_TOPLEVEL means the outgoing call was not nested within a call from another application and PENDINTGYPE_NESTED means the outgoing call was nested within a call from another application).

Return Values

PENDINGMSG_CANCELCALL

Cancel the outgoing call. This should be returned only under extreme conditions. Canceling a call that has not replied or been rejected can create orphan transactions and lose resources. OLE fails the original call and returns RPC_E_CALL_CANCELLED.

PENDINGMSG_WAITNOPROCESS

Continue waiting for the reply and do not dispatch the message unless it is a task-switching or window-activation message. A subsequent message will trigger another call to IMessageFilter::MessagePending. Leaving messages or events in the queue enables them to be processed normally, if the outgoing call is completed. Note that returning PENDINGMSG_WAITNOPROCESS can cause the message queue to fill.

PENDINGMSG_WAITDEFPROCESS

Because of the increased resources available in 32-bit systems, you are unlikely to get this return value. It now indicates the same state as PENDINGMSG_WAITNOPROCESS.

Keyboard and mouse messages are no longer dispatched, as was done with PENDINGMSG_WAITDEFPROCESS. However there are some cases where mouse and keyboard messages could cause the system to deadlock, and in these cases, mouse and keyboard messages are discarded. WM_PAINT messages are dispatched. Task-switching and activation messages are handled as before.

Remarks

OLE calls IMessageFilter::MessagePending after an application has made an OLE method call and a Windows message occurs before the call has returned. A Windows message is sent, for example, when the user selects a menu command or double-clicks an object. Before OLE makes the IMessageFilter::MessagePending call, it calculates the elapsed time since the original OLE method call was made. OLE delivers the elapsed time in the dwTickCount parameter. In the meantime, OLE does not remove the message from the queue.

Windows messages that appear in the caller’s queue should remain in the queue until sufficient time has passed to ensure that the messages are probably not the result of typing ahead, but are, instead, an attempt to get attention. Set the delay with the dwTickCount parameter — a two- or three-second delay is recommended. If that amount of time passes and the call has not been completed, the caller should flush the messages from the queue, and the OLE UI busy dialog box should be displayed offering the user the choice of retrying the call (continue waiting) or switching to the task identified by the threadIDCallee parameter. This ensures that:

•	If calls are completed in a reasonable amount of time, type ahead will be treated correctly.

•	If the callee does not respond, type ahead is not misinterpreted and the user is able to act to solve the problem. For example, OLE 1 servers can queue up requests without responding when they are in modal dialog boxes.

Handling input while waiting for an outgoing call to finish can introduce complications. The application should determine whether to process the message without interrupting the call, continue waiting, or cancel the operation.

When there is no response to the original OLE call, the application can cancel the call and restore the OLE object to a consistent state by calling IStorage::Revert on its storage. The object can be released when the container can shut down. However, canceling a call can create orphaned operations and resource leaks. Canceling should be used only as a last resort. It is strongly recommended that applications not allow such calls to be canceled.

See Also

IStorage::Revert, IStorage::Revert, OleUIBusy, OLEUIBUSY, In the WIN32 SDK: GetTickCount


IMessageFilter::RetryRejectedCall

A client-based method that gives the application an opportunity to display a dialog box so the user can retry or cancel the call, or switch to the task identified by threadIDCallee.

DWORD RetryRejectedCall(

HTASK threadIDCallee,	//Server task handle
DWORD dwTickCount,	//Elapsed tick count
DWORD dwRejectType	//Returned rejection message
);
Parameters

threadIDCallee

[in] Handle of the server task that rejected the call.

dwTickCount

[in] Number of elapsed ticks since the call was made.

dwRejectType

[in] Specifies either SERVERCALL_REJECTED or SERVERCALL_RETRYLATER, as returned by the object application.

Return Values

-1

The call should be canceled. OLE then returns RPC_E_CALL_REJECTED from the original method call.

Value >= 0 and <100

The call is to be retried immediately.

Value >= 100

OLE will wait for this many milliseconds and then retry the call.

Remarks

OLE calls RetryRejectedCall on the caller’s IMessageFilter immediately after receiving SERVERCALL_RETRYLATER or SERVERCALL_REJECTED from the IMessageFilter::HandleInComingCall method on the callee’s IMessageFilter.

If a called task rejects a call, the application is probably in a state where it cannot handle such calls, possibly only temporarily. When this occurs, OLE returns to the caller and issues IMessageFilter::RetryRejectedCall to determine if it should retry the rejected call.

Applications should silently retry calls that have returned with SERVERCALL_RETRYLATER. If, after a reasonable amount of time has passed, say about 30 seconds, the application should display the busy dialog box; a standard implementation of this dialog box is available in the OLEDLG library. The callee may momentarily be in a state where calls can be handled. The option to wait and retry is provided for special kinds of calling applications, such as background tasks executing macros or scripts, so that they can retry the calls in a nonintrusive way.

If, after a dialog box is displayed, the user chooses to cancel, RetryRejectedCall returns -1 and the call will appear to fail with RPC_E_CALL_REJECTED.


IMoniker

The IMoniker interface contains methods that allow you to use a moniker object, which contains information that uniquely identifies a COM object. An object that has a pointer to the moniker object’s IMoniker interface can locate, activate, and get access to the identified object without having any other specific information on where the object is actually located in a distributed system.

Like a path to a file in a file system, a moniker contains information that allows a COM object to be located and activated. Monikers can identify any type of COM object, from a document object stored in a file to a selection within an embedded object. OLE provides a set of moniker classes that allow you to create moniker objects identifying the objects most commonly found in the system. For example, there might be an object representing a range of cells in a spreadsheet which is itself embedded in a text document stored in a file. In a distributed system, this object’s moniker would identify the location of the object’s system, the file’s physical location on that system, the storage of the embedded object within that file, and, finally, the location of the range of cells within the embedded object.

A moniker object supports the IMoniker interface, which is derived from the IPersistStream interface, and uniquely identifies a single object in the system. Once an object providing a moniker has created the moniker object, this information cannot be changed within that object. If the moniker provider changes the information, it can only do so by creating a new moniker object, which would then uniquely identify the object in question.

Monikers have two important capabilites:

•	Monikers can be saved to a persistent storage. When a moniker is loaded back into memory, it still identifies the same object.

•	Monikers support an operation called “binding,” which is the process of locating the object named by the moniker, activating it (loading it into memory) if it is not already active, and returning a pointer to a requested interface on that object.

Monikers are used as the basis for linking in OLE. A linked object contains a moniker that identifies its source. When the user activates the linked object to edit it, the moniker is bound; this loads the link source into memory.

When to Implement

Implement IMoniker only if you are writing a new moniker class. This is necessary only if you need to identify objects that cannot be identified using one of the OLE-supplied moniker classes described below.

The OLE-supplied moniker classes are sufficient for most situations. Before considering writing your own moniker class, you should make sure that your requirements cannot be satisified by these classes.

If you decide you need to write your own implementation of IMoniker, you must also implement the IROTData interface on your moniker class. This interface allows your monikers to be registered with the Running Object Table (ROT).

When to Use

Two kinds of objects call the methods of IMoniker:

•	A component that contains one or more objects to be identified with a moniker and must provide the moniker to other objects

•	A client object that must bind to the object identified by the moniker

The component providing a moniker makes it accessible to other objects. It is important to understand the differences between the various system-supplied moniker classes to know which are appropriate for a given object. OLE also provides functions for creating monikers using the OLE-supplied moniker classes.

•	File monikers — based on a path in the file system. File monikers can be used to identify objects that are saved as files. The associated creation function is CreateFileMoniker.

•	Item monikers — based on a string that identifies an object in a container. Item monikers can be used to identify objects smaller than a file, such as embedded objects in a compound document and pseudo-objects (like a range of cells in a spreadsheet). The associated creation function is CreateItemMoniker.

•	Generic composite monikers — consists of two or more monikers of arbitrary type that have been composed together. Generic composite monikers allow monikers of different classes to be used in combination. The associated creation function is CreateGenericComposite.

•	Anti-monikers— the inverse of file, item, or pointer monikers. Anti-monikers are used primarily for constructing relative monikers, which are analogous to relative path (such as “..\backup\report.old”), and which specify a location of an object relative to the location of another object). The associated creation function is CreateAntiMoniker.

•	Pointer monikers — a non-persistent moniker that wraps an interface pointer to an object loaded in memory. Whereas most monikers identify objects that can be saved to persistent storage, pointer monikers identify objects that cannot. The associated creation function is CreatePointerMoniker.

A moniker provider must also implement other interfaces to allow the monikers it hands out to be bound. OLE objects that commonly provide monikers are link sources. These include server applications that support linking and container applications that support linking to their embedded objects.

Binding to an object means that a client uses a moniker to locate the object, activate it when necessary, and get a pointer to one of the active object’s interfaces. The client of the moniker does not need to be aware of the class of the moniker — it must just get a pointer to the correct moniker’s IMoniker interface. Monikers are used most often in this way by container applications that allow their documents to contain linked objects. However, link containers rarely call IMoniker methods directly. Instead, they generally manipulate linked objects through the default handler’s implementation of the IOleLink interface, which calls the appropriate IMoniker methods as needed.

•	Class monikers — these represent an object class. Class monikers bind to the class object of the class for which they are created. The associated creation function is CreateClassComposite.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IPersist Methods	Description
GetClassID	Returns the object’s CLSID.
IPersistStream Methods	Description
IsDirty	Checks whether object has been modified.
Load	Loads the object from a stream.
Save	Saves the object to a stream.
GetSizeMax	Returns the buffer size needed to save the object.
IMoniker Methods	Description
BindToObject	Binds to the object named by the moniker.
BindToStorage	Binds to the object’s storage.
Reduce	Reduces the moniker to simplest form.
ComposeWith	Composes with another moniker.
Enum	Enumerates component monikers.
IsEqual	Compares with another moniker.
Hash	Returns a hash value.
IsRunning	Checks whether object is running.
GetTimeOfLastChange	Returns time the object was last changed.
Inverse	Returns the inverse of the moniker.
CommonPrefixWith	Finds the prefix that the moniker has in common with another moniker.
RelativePathTo	Constructs a relative moniker between the moniker and another.
GetDisplayName	Returns the display name.
ParseDisplayName	Converts a display name into a moniker.
IsSystemMoniker	Checks whether moniker is one of the system-supplied types.
See Also

BindMoniker, CreateBindCtx, CreateGenericComposite, CreateFileMoniker, CreateItemMoniker, CreateAntiMoniker, CreatePointerMoniker, IOleLink, IPersistStream, IROTData, IMoniker—AntiMoniker Implementation, IMoniker—File Moniker Implementation, IMoniker—Item Moniker Implementation, IMoniker—Generic Composite Moniker Implementation, IMoniker—Pointer Moniker Implementation


IMoniker::BindToObject

Uses the moniker to bind to the object it identifies. The binding process involves finding the object, putting it into the running state if necessary, and supplying the caller with a pointer to a specified interface on the identified object.

HRESULT BindToObject(

IBindCtx *pbc,	//Pointer to bind context object to be used
IMoniker *pmkToLeft,	//Pointer to moniker that precedes this one in the composite
REFIID riidResult,	//IID of interface pointer requested
void **ppvResult	//Indirect pointer to the specified interface on the object
);
Parameters

pbc

[in] Pointer to the IBindCtx interface on the bind context object, which is used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment.

pmkToLeft

[in] If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL.

riidResult

[in] IID of the interface the client wishes to use to communicate with the object that the moniker identifies.

ppvResult

[out] When successful, indirect pointer to the interface specified in riidResult on the object the moniker identifies. In this case, the implementation must call IUnknown::AddRef on this pointer. It is the caller’s responsibility to release the object with a call to IUnknown::Release. If an error occurs, ppvResult should return NULL.

Return Values

The method supports the standard return values E_UNEXPECTED and E_OUTOFMEMORY, as well as the following:

S_OK

The binding operation was successful.

MK_E_NOOBJECT

The object identified by this moniker, or some object identified by the composite moniker of which this moniker is a part, could not be found.

MK_E_EXCEEDEDDEADLINE

The binding operation could not be completed within the time limit specified by the bind context’s BIND_OPTS structure.

MK_E_CONNECTMANUALLY

The binding operation requires assistance from the end user. The most common reasons for returning this value are that a password is needed or that a floppy needs to be mounted. When this value is returned, retrieve the moniker that caused the error with a call to IBindCtx::GetObjectParam with the key “ConnectManually”. You can then call IMoniker::GetDisplayName to get the display name, display a dialog box that communicates the desired information, such as instructions to mount a floppy or a request for a password, and then retry the binding operation.

MK_E_INTERMEDIATEINTERFACENOTSUPPORTED

An intermediate object was found but it did not support an interface required to complete the binding operation. For example, an item moniker returns this value if its container does not support the IOleItemContainer interface.

STG_E_ACCESSDENIED

Unable to access the storage object.

IOleItemContainer::GetObject errors

If the moniker used to bind to an object contains an item moniker, errors associated with this method can be returned.

Remarks

IMoniker::BindToObject implements the primary function of a moniker, which is to locate the object identified by the moniker and return a pointer to one of its interfaces.

Notes to Callers

If you are using a moniker as a persistent connection between two objects, you activate the connection by calling IMoniker::BindToObject.

You typically call IMoniker::BindToObject during the following process:

1.	Create a bind context object with a call to the CreateBindCtx function.

2.	Call IMoniker::BindToObject using the moniker, retrieving a pointer to a desired interface on the identified object.

3.	Release the bind context.

4.	Through the acquired interface pointer, perform the desired operations on the object.

5.	When finished with the object, release the object’s interface pointer.

The following code fragment illustrates these steps:

// pMnk is an IMoniker * that points to a previously acquired moniker

// ICellRange is a custom interface designed for an object that is a

//            range of spreadsheet cells

ICellRange *pCellRange;

IBindCtx *pbc;

CreateBindCtx( 0, &pbc );

pMnk->BindToObject( pbc, NULL, IID_ICellRange, &pCellRange );

pbc->Release();

// pCellRange now points to the object; safe to use pCellRange

pCellRange->Release();

You can also use the BindMoniker function when you only intend one binding operation and don’t need to retain the bind context object. This helper function encapsulates the creation of the bind context, calling IMoniker::BindToObject, and releasing the bind context.

OLE containers that support links to objects use monikers to locate and get access to the linked object, but typically do not call IMoniker::BindToObject directly. Instead, when a user activates a link in a container, the link container usually calls IOleObject::DoVerb, using the link handler’s implementation, which calls IMoniker::BindToObject on the moniker stored in the linked object (if it cannot handle the verb).

Notes to Implementers

What your implementation does depends on whether you expect your moniker to have a prefix, that is, whether you expect the pmkToLeft parameter to be NULL or not. For example, an item moniker, which identifies an object within a container, expects that pmkToLeft identifies the container. An item moniker consequently uses pmkToLeft to request services from that container. If you expect your moniker to have a prefix, you should use the pmkToLeft parameter (for instance, calling IMoniker::BindToObject on it) to request services from the object it identifies.

If you expect your moniker to have no prefix, your IMoniker::BindToObject implementation should first check the Running Object Table (ROT) to see if the object is already running. To acquire a pointer to the ROT, your implementation should call IBindCtx::GetRunningObjectTable on the pbc parameter. You can then call the IRunningObjectTable::GetObject method to see if the current moniker has been registered in the ROT. If so, you can immediately call IUnknown::QueryInterface to get a pointer to the interface requested by the caller.

When your IMoniker::BindToObject implementation binds to some object, it should use the pbc parameter to call IBindCtx::RegisterObjectBound to store a reference to the bound object in the bind context. This ensures that the bound object remains running until the bind context is released, which can avoid the expense of having a subsequent binding operation load it again later.

If the bind context’s BIND_OPTS structure specifies the BINDFLAGS_JUSTTESTEXISTENCE flag, your implementation has the option of returning NULL in ppvResult (although you can also ignore the flag and perform the complete binding operation).

See Also

BindMoniker, IMoniker::BindToStorage


IMoniker::BindToStorage

Retrieves an interface pointer to the storage that contains the object identified by the moniker. Unlike the IMoniker::BindToObject method, this method does not activate the object identified by the moniker.

HRESULT BindToStorage(

IBindCtx *pbc,	//Pointer to bind context to be used
IMoniker *pmkToLeft,	//Pointer to moniker to the left of this one in the composite
REFIID riid,	//Reference to the identifier of the storage interface requested
void **ppvObj	//Indirect pointer to interface on storage object containing the identified object
);
Parameters

pbc

[in] Pointer to the IBindCtx interface on the bind context object to be used during this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment. For more information, see IBindCtx.

pmkToLeft

[in] If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL.

riid

[in] Reference to the identifier of the storage interface requested, whose pointer will be returned in ppvObj. Storage interfaces commonly requested include IStorage, IStream, and ILockBytes.

ppvObj

[out] Pointer to the interface identified by riid on the storage of the object identified by the moniker. If ppvObj is non-NULL, the implementation must call IUnknown::AddRef on the parameter; it is the caller’s responsibility to call IUnknown::Release. If an error occurs, ppvObj is set to NULL.

Return Values

The method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The binding operation was successful.

MK_E_NOSTORAGE

The object identified by this moniker does not have its own storage.

MK_E_EXCEEDEDDEADLINE

The operation could not be completed within the time limit specified by the bind context’s BIND_OPTS structure.

MK_E_CONNECTMANUALLY

The operation was unable to connect to the storage, possibly because a network device could not be connected to. For more information, see IMoniker::BindToObject.

MK_E_INTERMEDIATEINTERFACENOTSUPPORTED

An intermediate object was found but it did not support an interface required for an operation. For example, an item moniker returns this value if its container does not support the IOleItemContainer interface.

STG_E_ACCESSDENIED

Unable to access the storage object.

IOleItemContainer::GetObject errors

Binding to a moniker containing an item moniker can return any of the errors associated with this function.

Remarks

There is an important difference between the IMoniker::BindToObject and IMoniker::BindToStorage methods. If, for example, you have a moniker that identifies a spreadsheet object, calling IMoniker::BindToObject provides access to the spreadsheet object itself, while calling IMoniker::BindToStorage provides access to the storage object in which the spreadsheet resides.

Notes to Callers

Although none of the OLE moniker classes call this method in their binding operations, it might be appropriate to call it in the implementation of a new moniker class. You could call this method in an implementation of IMoniker::BindToObject that requires information from the object identified by the pmkToLeft parameter and can get it from the persistent storage of the object without activation. For example, if your monikers are used to identify objects that can be activated without activating their containers, you may find this method useful.

A client that can read the storage of the object its moniker identifies could also call this method.

Notes to Implementers

Your implementation should locate the persistent storage for the object identified by the current moniker and return the desired interface pointer. Some types of monikers represent pseudo-objects, which are objects that do not have their own persistent storage. Such objects comprise some portion of the internal state of its container; as, for example, a range of cells in a spreadsheet. If your moniker class identifies this type of object, your implementation of IMoniker::BindToStorage should return the error MK_E_NOSTORAGE.

If the bind context’s BIND_OPTS structure specifies the BINDFLAGS_JUSTTESTEXISTENCE flag, your implementation has the option of returning NULL in ppvObj (although it can also ignore the flag and perform the complete binding operation).

See Also

IMoniker::BindToObject


IMoniker::CommonPrefixWith

Creates a new moniker based on the common prefix that this moniker (the one comprising the data of this moniker object) shares with another moniker.

HRESULT CommonPrefixWith(

IMoniker *pmkOther,	//Pointer to moniker to be used for comparison
IMoniker **ppmkPrefix	//Indirect pointer to the prefix
);
Parameters

pmkOther

[in] Pointer to the IMoniker interface on another moniker to be compared with this one to determine whether there is a common prefix.

ppmkPrefix

[out] When successful, points to the IMoniker pointer to the moniker that is the common prefix of this moniker and pmkOther. In this case, the implementation must call IUnknown::AddRef on the parameter; it is the caller’s responsibility to call IUnknown::Release. If an error occurs or if there is no common prefix, the implementation should set ppmkPrefix to NULL.

Return Values

The method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

A common prefix exists that is neither this moniker nor pmkOther.

MK_S_NOPREFIX

No common prefix exists.

MK_S_HIM

The entire pmkOther moniker is a prefix of this moniker.

MK_S_US

The two monikers are identical.

MK_S_ME

This moniker is a prefix of the pmkOther moniker.

MK_E_NOTBINDABLE

This method was called on a relative moniker. It is not meaningful to take the common prefix on a relative moniker.

Remarks

IMoniker::CommonPrefixWith creates a new moniker that consists of the common prefixes of the moniker on this moniker object and another moniker. If, for example, one moniker represents the path “c:\projects\secret\art\pict1.bmp” and another moniker represents the path “c:\projects\secret\docs\chap1.txt,” the common prefix of these two monikers would be a moniker representing the path “c:\projects\secret.”

Notes to Callers

The IMoniker::CommonPrefixWith method is primarily called in the implementation of the IMoniker::RelativePathTo method. Clients using a moniker to locate an object rarely need to call this method.

Call this method only if pmkOther and this moniker are both absolute monikers. An absolute moniker is either a file moniker or a generic composite whose leftmost component is a file moniker that represents an absolute path. Do not call this method on relative monikers, because it would not produce meaningful results.

Notes to Implementers

Your implementation should first determine whether pmkOther is a moniker of a class that you recognize and for which you can provide special handling (for example, if it is of the same class as this moniker). If so, your implementation should determine the common prefix of the two monikers. Otherwise, it should pass both monikers in a call to the MonikerCommonPrefixWith function, which correctly handles the generic case.

See Also

IMoniker::RelativePathTo, MonikerCommonPrefixWith


IMoniker::ComposeWith

Combines the current moniker with another moniker, creating a new composite moniker.

HRESULT ComposeWith(

IMoniker *pmkRight,	//Pointer to moniker to be composed onto this one
BOOL fOnlyIfNotGeneric,	//Indicates if generic composition permissible
IMoniker **ppmkComposite	//Indirect pointer to the composite
);
Parameters

pmkRight

[in] Pointer to the IMoniker interface on the moniker to compose onto the end of this moniker.

fOnlyIfNotGeneric

[in] If TRUE, the caller requires a non-generic composition, so the operation should proceed only if pmkRight is a moniker class that this moniker can compose with in some way other than forming a generic composite. If FALSE, the method can create a generic composite if necessary.

ppmkComposite

[out] When the call is successful, indirect pointer to the location of the resulting composite moniker pointer. In this case, the implementation must call IUnknown::AddRef on the parameter; it is the caller’s responsibility to call IUnknown::Release. If an error occurs or if the monikers compose to nothing (e.g., composing an anti-moniker with an item moniker or a file moniker), ppmkComposite should be set to NULL.

Return Values

The method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The monikers were successfully combined.

MK_E_NEEDGENERIC

Indicates that fOnlyIfNotGeneric was TRUE, but the monikers could not be composed together without creating a generic composite moniker.

Remarks

Joining two monikers together is called composition. Sometimes two monikers of the same class can be combined in what is called non-generic composition. For example, a file moniker representing an incomplete path and another file moniker representing a relative path can be combined to form a single file moniker representing the complete path. Non-generic composition for a given moniker class can be handled only in the implementation of IMoniker::ComposeWith for that moniker class.

Combining two monikers of any class is called generic composition, which can be accomplished through a call to the CreateGenericComposite function.

Composition of monikers is an associative operation. That is, if A, B, and C are monikers, then, where Comp() represents the composition operation:

Comp( Comp( A, B ), C )

is always equal to

Comp( A, Comp( B, C ) )

Notes to Callers

To combine two monikers, you should call IMoniker::ComposeWith rather than calling the CreateGenericComposite function to give the first moniker a chance to perform a non-generic composition.

An object that provides item monkers to identify its objects would call IMoniker::ComposeWith to provide a moniker that completely identifies the location of the object. This would apply, for example, to a server that supports linking to portions of a document, or a container that supports linking to embedded objects within its documents. In such a situation, you would do the following:

1.	Create an item moniker identifying an object.

2.	Get a moniker that identifies the object’s container.

3.	Call IMoniker::ComposeWith on the moniker identifying the container, passing the item moniker as the pmkRight parameter.

Most callers of IMoniker::ComposeWith should set the fOnlyIfNotGeneric parameter to FALSE.

Notes to Implementers

You can use either non-generic or generic composition to compose the current moniker with the moniker that pmkRight points to. If the class of the moniker indicated by pmkRight is the same as that of the current moniker, it is possible to use the contents of pmkRight to perform a more intelligent non-generic composition.

In writing a new moniker class, you must decide if there are any kinds of monikers, whether of your own class or another class, to which you want to give special treatment. If so, implement IMoniker::ComposeWith to check whether pmkRight is a moniker of the type that should have this treatment. To do this, you can call the moniker’s GetClassID method (derived from the IPersist Interface), or, if you have defined a moniker object that supports a custom interface, you can call IUnknown::QueryInterface on the moniker for that interface. An example of special treatment would be the non-generic composition of an absolute file moniker with a relative file moniker. The most common case of a special moniker is the inverse for your moniker class (whatever you return from your implementation of IMoniker::Inverse).

If pmkRight completely negates the receiver so the resulting composite is empty, you should pass back NULL in ppmkComposite and return the status code S_OK.

If the pmkRight parameter is not of a class to which you give special treatment, examine fOnlyIfNotGeneric to determine what to do next. If fOnlyIfNotGeneric is TRUE, pass back NULL through ppmkComposite and return the status code MK_E_NEEDGENERIC. If fOnlyIfNotGeneric is FALSE, call the CreateGenericComposite function to perform the composition generically.

See Also

CreateGenericComposite, IMoniker::Inverse


IMoniker::Enum

Supplies a pointer to an enumerator that can enumerate the components of a composite moniker.

HRESULT Enum(

BOOL fForward,	//Specifies direction of enumeration
IEnumMoniker **ppenumMoniker	//Indirect pointer to the IEnumMoniker pointer
);
Parameters

fForward

[in] If TRUE, enumerates the monikers from left to right. If FALSE, enumerates from right to left.

ppenumMoniker

[out] When successful, indirect pointer to an IEnumMoniker enumerator on this moniker. In this case, the implementation must call IUnknown::AddRef on the parameter. It is the caller’s responsibility to call IUnknown::Release. If an error occurs or if the moniker has no enumerable components, the implementation sets ppenumMoniker to NULL.

Return Values

The method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

Indicates success. This value is returned even if the moniker does not provide an enumerator (if ppenumMoniker equals NULL).

Remarks

IMoniker::Enum must supply an IEnumMoniker pointer to an enumerator that can enumerate the components of a moniker. For example, the implementation of the IMoniker::Enum method for a generic composite moniker creates an enumerator that can determine the individual monikers that make up the composite, while the IMoniker::Enum method for a file moniker creates an enumerator that returns monikers representing each of the components in the path.

Notes to Callers

Call this method to examine the components that make up a composite moniker.

Notes to Implementers

If the new moniker class has no discernible internal structure, your implementation of this method can simply return S_OK and set ppenumMoniker to NULL.

See Also

IEnumXXXX


IMoniker::GetDisplayName

Gets the display name , which is a user-readable representation of this moniker.

HRESULT GetDisplayName(

IBindCtx *pbc,	//Pointer to bind context to be used
IMoniker *pmkToLeft,	//Pointer to moniker to the left in the composite
LPOLESTR *ppszDisplayName	//Indirect pointer to the display name
);
Parameters

pbc

[in] Pointer to the IBindCtx interface on the bind context to be used in this operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment. For more information, see IBindCtx.

pmkToLeft

[in] If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL.

ppszDisplayName

[out] When successful, indirect pointer to a zero-terminated wide character string (two bytes per character) containing the display name of this moniker. The implementation must use IMalloc::Alloc to allocate the string returned in ppszDisplayName, and the caller is responsible for calling IMalloc::Free to free it. Both the caller and and the one called use the OLE task allocator returned by CoGetMalloc. If an error occurs, ppszDisplayName should be set to NULL.

Return Values

The method supports the standard return value E_OUTOFMEMORY

, as well as the following:

S_OK

The display name was successfully supplied.

MK_E_EXCEEDEDDEADLINE

The binding operation could not be completed within the time limit specified by the bind context’s BIND_OPTS structure.

E_NOTIMPL

There is no display name.

Remarks

IMoniker::GetDisplayName provides a string that is a displayable representation of the moniker. A display name is not a complete representation of a moniker’s internal state; it is simply a form that can be read by users. As a result, it is possible (though rare) for two different monikers to have the same display name. While there is no guarantee that the display name of a moniker can be parsed back into that moniker when calling the MkParseDisplayName function with it, failure to do so is rare.

As examples, the file moniker implementation of this method supplies the path the moniker represents, and an item moniker’s display name is the string identifying the item that is contained in the moniker.

Notes to Callers

It is possible that retrieving a moniker’s display name may be an expensive operation. For efficiency, you may want to cache the results of the first successful call to IMoniker::GetDisplayName, rather than making repeated calls.

Notes to Implementers

If you are writing a moniker class in which the display name does not change, simply cache the display name and supply the cached name when requested. If the display name can change over time, getting the current display name might mean that the moniker has to access the object’s storage or bind to the object, either of which can be expensive operations. If this is the case, your implementation of IMoniker::GetDisplayName should return MK_E_EXCEEDEDDEADLINE if the name cannot be retrieved by the time specified in the bind context’s BIND_OPTS structure.

A moniker that is intended to be part of a generic composite moniker should include any preceding delimiter (such as ‘\’) as part of its display name. For example, the display name returned by an item moniker includes the delimiter specified when it was created with the CreateItemMoniker function. The display name for a file moniker does not include a delimiter because file monikers are always expected to be the leftmost component of a composite.

See Also

IMoniker::ParseDisplayName, MkParseDisplayName


IMoniker::GetTimeOfLastChange

Provides a number representing the time the object identified by this moniker was last changed. To be precise, the time returned is the earliest time OLE can identify after which no change has occurred, so this time may be later than the time of the last change to the object.

HRESULT GetTimeOfLastChange(

IBindCtx *pbc,	//Bind context to be used
IMoniker *pmkToLeft,	//Moniker to the left in the composite
FILETIME *pFileTime	//Receives the time of last change
);
Parameters

pbc

[in] Pointer to the bind context to be used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment. For more information, see IBindCtx.

pmkToLeft

[in] If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker Implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL.

pFileTime

[out] Pointer to the FILETIME structure receiving the time of last change. A value of {0xFFFFFFFF,0x7FFFFFFF} indicates an error (for example, exceeded time limit, information not available).

Return Values

The method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The method successfully returned a time.

MK_E_EXCEEDEDDEADLINE

The binding operation could not be completed within the time limit specified by the bind context’s BIND_OPTS structure.

MK_E_CONNECTMANUALLY

The operation was unable to connect to the storage for this object, possibly because a network device could not be connected to. For more information, see IMoniker::BindToObject.

MK_E_UNAVAILABLE

The time of the change is unavailable, and will not be available no matter what deadline is used.

Remarks

Notes to Callers

If you’re caching information returned by the object identified by the moniker, you may want to ensure that your information is up-to-date. To do so, you would call IMoniker::GetTimeOfLastChange and compare the time returned with the time you last retrieved information from the object.

For the monikers stored within linked objects, IMoniker::GetTimeOfLastChange is primarily called by the default handler’s implementation of IOleObject::IsUpToDate. Container applications call IOleObject::IsUpToDate to determine if a linked object (or an embedded object containing linked objects) is up-to-date without actually binding to the object. This enables an application to determine quickly which linked objects require updating when the end user opens a document. The application can then bind only those linked objects that need updating (after prompting the end user to determine whether they should be updated), instead of binding every linked object in the document.

Notes to Implementers

It is important to perform this operation quickly because, for linked objects, this method is called when a user first opens a compound document. Consequently, your IMoniker::GetTimeOfLastChange implementation should not bind to any objects. In addition, your implementation should check the deadline parameter in the bind context and return MK_E_EXCEEDEDDEADLINE if the operation cannot be completed by the specified time.

There are a number of strategies you can use in your implementations:

•	For many types of monikers, the pmkToLeft parameter identifies the container of the object identified by this moniker. If this is true of your moniker class, you can simply call IMoniker::GetTimeOfLastChange on the pmkToLeft parameter, since an object cannot have changed at a date later than its container.

•	You can get a pointer to the Running Object Table (ROT) by calling IBindCtx::GetRunningObjectTable on the pbc parameter, and then calling IRunningObjectTable::GetTimeOfLastChange, since the ROT generally records the time of last change.

•	You can get the storage associated with this moniker (or the pmkToLeft moniker) and return the storage’s last modification time with a call to IStorage::Stat.

See Also

IBindCtx::GetRunningObjectTable, IRunningObjectTable::GetTimeOfLastChange


IMoniker::Hash

Calculates a 32-bit integer using the internal state of the moniker.

HRESULT Hash(

DWORD *pdwHash	//Pointer to hash value
);
Parameter

pdwHash

[out] Pointer to the hash value.

Return Value

S_OK

Successfully received a 32-bit integer hash value.

Remarks

Notes to Callers

You can use the value returned by this method to maintain a hash table of monikers. The hash value determines a hash bucket in the table. To search such a table for a specified moniker, calculate its hash value and then compare it to the monikers in that hash bucket using IMoniker::IsEqual.

Notes to Implementers

The hash value must be constant for the lifetime of the moniker. Two monikers that compare as equal using IMoniker::IsEqual must hash to the same value.

Marshaling and then unmarshaling a moniker should have no effect on its hash value. Consequently, your implementation of IMoniker::Hash should rely only on the internal state of the moniker, not on its memory address.

See Also

IMoniker::IsEqual


IMoniker::Inverse

Provides a moniker that, when composed to the right of this moniker or one of similar structure, will destroy it (the moniker will compose to nothing).

HRESULT Inverse(

IMoniker **ppmk	//Indirect pointer to the inverse of the moniker
);
Parameter

ppmk

[out] When successful, indirect pointer to the IMoniker interface on a moniker that is the inverse of this moniker. In this case, the implementation must call IUnknown::AddRef on the parameter. It is the caller’s responsibility to call IUnknown::Release. If an error occurs, the implementation should set ppmk to NULL.

Return Values

The method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The inverse moniker has been returned successfully.

MK_E_NOINVERSE

The moniker class does not have an inverse.

Remarks

The inverse of a moniker is analogous to the “..” directory in MS-DOS file systems; the “..” directory acts as the inverse to any other directory name, because appending “..” to a directory name results in an empty path. In the same way, the inverse of a moniker typically is also the inverse of all monikers in the same class. However, it is not necessarily the inverse of a moniker of a different class.

The inverse of a composite moniker is a composite consisting of the inverses of the components of the original moniker, arranged in reverse order. For example, if the inverse of A is Inv( A ) and the composite of A, B, and C is Comp( A, B, C ), then

Inv( Comp( A, B, C ) )

is equal to

Comp( Inv( C ), Inv( B ), Inv( A ) ).

Not all monikers have inverses. Most monikers that are themselves inverses, such as anti-monikers, do not have inverses. Monikers that have no inverse cannot have relative monikers formed from inside the objects they identify to other objects outside.

Notes to Callers

An object that is using a moniker to locate another object usually does not know the class of the moniker it is using. To get the inverse of a moniker, you should always call IMoniker::Inverse rather than the CreateAntiMoniker function, because you cannot be certain that the moniker you’re using considers an anti-moniker to be its inverse.

The IMoniker::Inverse method is also called by the implementation of the IMoniker::RelativePathTo method, to assist in constructing a relative moniker.

Notes to Implementers

If your monikers have no internal structure, you can call the CreateAntiMoniker function in to get an anti-moniker in your implementation of IMoniker::Inverse. In your implementation of IMoniker::ComposeWith, you need to check for the inverse you supply in the implementation of IMoniker::Inverse.

See Also

CreateAntiMoniker, IMoniker::ComposeWith, IMoniker::RelativePathTo


IMoniker::IsEqual

Compares this moniker with a specified moniker and indicates whether they are identical.

HRESULT IsEqual(

IMoniker *pmkOtherMoniker	//Pointer to moniker to be used for comparison
);
Parameter

pmkOtherMoniker

[in] Pointer to the IMoniker interface on the moniker to be used for comparison with this one (the one from which this method is called).

Return Values

S_OK

The two monikers are identical.

S_FALSE

The two monikers are not identical.

Remarks

Previous implementations of the Running Object Table (ROT) called this method. The current implementation of the ROT uses the IROTData interface instead.

Notes to Callers

Call this method to determine if two monikers are identical or not. Note that the reduced form of a moniker is considered different from the unreduced form. You should call the IMoniker::Reduce method before calling IMoniker::IsEqual, because a reduced moniker is in its most specific form. IMoniker::IsEqual may return S_FALSE on two monikers before they are reduced, and S_OK after they are reduced.

Notes to Implementers

Your implementation should not reduce the current moniker before performing the comparison. It is the caller’s responsibility to call IMoniker::Reduce in order to compare reduced monikers.

Note that two monikers that compare as equal must hash to the same value using IMoniker::Hash.

See Also

IMoniker::Reduce, IMoniker::Hash, IROTData


IMoniker::IsRunning

Determines whether the object identified by this moniker is currently loaded and running.

HRESULT IsRunning(

IBindCtx *pbc,	//Pointer to bind context to be used
IMoniker *pmkToLeft,	//Pointer to moniker to the left in the composite
IMoniker *pmkNewlyRunning	//Pointer to moniker of a newly running object
);
Parameters

pbc

[in] Pointer to theIBindCtx interface on the bind context to be used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment. For more information, see IBindCtx.

pmkToLeft

[in] Pointer to theIMoniker interface on the moniker to the left of this moniker if this moniker is part of a composite. This parameter is primarily used by moniker Implementers to enable cooperation between the various components of a composite moniker; moniker clients can usually pass NULL.

pmkNewlyRunning

[in] Pointer to theIMoniker interface on the moniker most recently added to the Running Object Table (ROT). This can be NULL. If non-NULL, the implementation can return the results of calling IMoniker::IsEqual on the pmkNewlyRunning parameter, passing the current moniker. This parameter is intended to enable IMoniker::IsRunning implementations that are more efficient than just searching the ROT, but the implementation can choose to ignore pmkNewlyRunning without causing any harm.

Return Values

The method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The moniker is running.

S_FALSE

The moniker is not running.

Remarks

Notes to Callers

If speed is important when you’re requesting services from the object identified by the moniker, you may want those services only if the object is already running (because loading an object into the running state may be time-consuming). In such a situation, you’d call IMoniker::IsRunning to determine if the object is running.

For the monikers stored within linked objects, IMoniker::IsRunning is primarily called by the default handler’s implementation of IOleLink::BindIfRunning.

Notes to Implementers

To get a pointer to the Running Object Table (ROT), your implementation should call IBindCtx::GetRunningObjectTable on the pbc parameter. Your implementation can then call IRunningObjectTable::IsRunning to determine whether the object identified by the moniker is running. Note that the object identified by the moniker must have registered itself with the ROT when it first began running.

See Also

IOleLink::BindIfRunning, IBindCtx::GetRunningObjectTable, IRunningObjectTable::IsRunning


IMoniker::IsSystemMoniker

Indicates whether this moniker is of one of the system-supplied moniker classes.

HRESULT IsSystemMoniker(

DWORD *pdwMksys	//Pointer to value from MKSYS enumeration
);
Parameter

pdwMksys

[out] Pointer to an integer that is one of the values from the MKSYS enumeration, and refers to one of the OLE moniker classes. This parameter cannot be NULL.

Return Values

S_OK

The moniker is a system moniker.

S_FALSE

The moniker is not a system moniker.

Remarks

Notes to Callers

New values of the MKSYS enumeration may be defined in the future; therefore you should explicitly test for each value you are interested in.

Notes to Implementers

Your implementation of this method must return MKSYS_NONE. You cannot use this function to identify your own monikers (for example, in your implementation of IMoniker::ComposeWith). Instead, you should use your moniker’s implementation of IPersist::GetClassID or use IUnknown::QueryInterface to test for your own private interface.

See Also

IPersist::GetClassID, MKSYS


IMoniker::ParseDisplayName

Reads as many characters of the specified display name as it understands and builds a moniker corresponding to the portion read; this procedure is known as “parsing” the display name.

HRESULT ParseDisplayName(

IBindCtx *pbc,	//Pointer to bind context to be used
IMoniker *pmkToLeft,	//Pointer to moniker to the left in the composite
LPOLESTR pszDisplayName,	//Pointer to display name
ULONG *pchEaten,	//Pointer to number of characters consumed
IMoniker **ppmkOut	//Indirect pointer to moniker built from display name
);
Parameters

pbc

[in] Pointer to the IBindCtx interface on the bind context to be used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment. For more information, see IBindCtx.

pmkToLeft

[in] Pointer to the IMoniker interface on the moniker that has been built out of the display name up to this point.

pszDisplayName

[in] Pointer to a zero-terminated string containing the remaining display name to be parsed. For Win32 applications, the LPOLESTR type indicates a wide character string (two bytes per character); otherwise, the string has one byte per character.

pchEaten

[out] Pointer to the number of characters in pszDisplayName that were consumed in this step.

ppmkOut

[out] When successful, indirect pointer to the IMoniker interface on the moniker that was built from pszDisplayName. In this case, the implementation must call IUnknown::AddRef on the parameter; it is the caller’s responsibility to call IUnknown::Release. If an error occurs, the implementation sets ppmkOut to NULL.

Return Values

The method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The parsing operation was completed successfully.

MK_E_SYNTAX

An error in the syntax of the input components (pmkToLeft, this moniker, and pszDisplayName). For example, a file moniker returns this error if pmkToLeft is non-NULL, and an item moniker returns it if pmkToLeft is NULL.

IMoniker::BindToObject errors

Parsing display names may cause binding. Thus, any error associated with this function may be returned.

Remarks

Notes to Callers

Moniker clients do not typically call IMoniker::ParseDisplayName directly. Instead, they call the MkParseDisplayName function when they want to convert a display name into a moniker (for example, in implementing the Links dialog box for a container application, or for implementing a macro language that supports references to objects outside the document). That function first parses the initial portion of the display name itself.

It then calls IMoniker::ParseDisplayName on the moniker it has just created, passing the remainder of the display name and getting a new moniker in return; this step is repeated until the entire display name has been parsed.

Notes to Implementers

Your implementation may be able to perform this parsing by itself if your moniker class is designed to designate only certain kinds of objects. Otherwise, you must get an IParseDisplayName interface pointer for the object identified by the moniker-so-far (i.e., the composition of pmkToLeft and this moniker) and then return the results of calling IParseDisplayName::ParseDisplayName.

There are different strategies for getting an IParseDisplayName pointer:

•	You can try to get the object’s CLSID (by calling IPersist::GetClassID on the object), and then call the CoGetClassObject function, requesting the IParseDisplayName interface on the class factory associated with that CLSID.

•	You can try to bind to the object itself to get an IParseDisplayName pointer.

•	You can try binding to the object identified by pmkToLeft to get an IOleItemContainer pointer, and then call IOleItemContainer::GetObject to get an IParseDisplayName pointer for the item.

Any objects that are bound should be registered with the bind context (see IBindCtx::RegisterObjectBound) to ensure that they remain running for the duration of the parsing operation.

See Also

IParseDisplayName, MkParseDisplayName


IMoniker::Reduce

Returns a reduced moniker; that is, another moniker that refers to the same object as this moniker but can be bound with equal or greater efficiency.

HRESULT Reduce(

IBindCtx *pbc,	//Pointer to bind context to be used
DWORD dwReduceHowFar,	//How much reduction should be done
IMoniker **ppmkToLeft,	//Indirect pointer to moniker to the left in the composite
IMoniker **ppmkReduced	//Indirect pointer to the reduced moniker
);
Parameters

pbc

[in] Pointer to the IBindCtx interface on the bind context to be used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment. For more information, see IBindCtx.

dwReduceHowFar

[in] DWORD that specifies how far this moniker should be reduced. This parameter must be one of the values from the MKRREDUCE enumeration.

ppmkToLeft

[in, out] On entry, indirect pointer to the moniker to the left of this moniker, if this moniker is part of a composite. This parameter is primarily used by moniker Implementers to enable cooperation between the various components of a composite moniker; moniker clients can usually pass NULL.

On return, ppmkToLeft is usually set to NULL, indicating no change in the original moniker to the left. In rare situations ppmkToLeft indicates a moniker, indicating that the previous moniker to the left should be disregarded and the moniker returned through ppmkToLeft is the replacement. In such a situation, the implementation must call IUnknown::Release on the passed-in pointer and call IUnknown::AddRef on the returned moniker; the caller must release it later. If an error occurs, the implementation can either leave the parameter unchanged or set it to NULL.

ppmkReduced

[out] Indirect pointer to the IMoniker interface on the reduced form of this moniker, which can be NULL if an error occurs or if this moniker is reduced to nothing. If this moniker cannot be reduced, ppmkReduced is simply set to this moniker and the return value is MK_S_REDUCED_TO_SELF. If ppmkReduced is non-NULL, the implementation must call IUnknown::AddRef on the parameter; it is the caller’s responsibility to call IUnknown::Release. (This is true even if ppmkReduced is set to this moniker.)

Return Values

The method supports the standard return values E_UNEXPECTED and E_OUTOFMEMORY, as well as the following:

S_OK

This moniker was reduced.

MK_S_REDUCED_TO_SELF

This moniker could not be reduced any further, so ppmkReduced indicates this moniker.

MK_E_EXCEEDEDDEADLINE

The operation could not be completed within the time limit specified by the bind context’s BIND_OPTS structure.

Remarks

IMoniker::Reduce is intended for the following uses:

•	It enables the construction of user-defined macros or aliases as new kinds of moniker classes. When reduced, the moniker to which the macro evaluates is returned.

•	It enables the construction of a kind of moniker that tracks data as it moves about. When reduced, the moniker of the data in its current location is returned.

•	On file systems that support an identifier-based method of accessing files which is independent of file names; a file moniker could be reduced to a moniker which contains one of these identifiers.

The intent of the MKRREDUCE flags passed in the dwReduceHowFar parameter is to provide the ability to programmatically reduce a moniker to a form whose display name is recognizable to the user. For example, paths in the file system, bookmarks in word-processing documents, and range names in spreadsheets are all recognizable to users. In contrast, a macro or an alias encapsulated in a moniker are not recognizable to users.

Notes to Callers

The scenarios described above are not currently implemented by the system-supplied moniker classes.

You should call IMoniker::Reduce before comparing two monikers using the IMoniker::IsEqual method, because a reduced moniker is in its most specific form. IMoniker::IsEqual may return S_FALSE on two monikers before they are reduced and return S_OK after they are reduced.

Notes to Implementers

If the current moniker can be reduced, your implementation must not reduce the moniker in-place. Instead, it must return a new moniker that represents the reduced state of the current one. This way, the caller still has the option of using the non-reduced moniker (for example, enumerating its components). Your implementation should reduce the moniker at least as far as is requested.

See Also

IMoniker::IsEqual, MKRREDUCE


IMoniker::RelativePathTo

Supplies a moniker that, when composed onto the end of this moniker (or one with a similar structure), yields the specified moniker.

HRESULT RelativePathTo(

IMoniker *pmkOther,	//Pointer to moniker to which a relative path should be taken
IMoniker **ppmkRelPath	//Indirect pointer to the relative moniker
);
Parameters

pmkOther

[in] Pointer to the IMoniker interface on the moniker to which a relative path should be taken.

ppmkRelPath

[out] Iindirect pointer to the IMoniker interface on the relative moniker. When successful, the implementation must call IUnknown::AddRef on the parameter; it is the caller’s responsibility to call IUnknown::Release. If an error occurs, the implementation sets ppmkRelPath to NULL.

Return Values

The method supports the standard return values E_OUTOFMEMORY and

E_UNEXPECTED, as well as the following:

S_OK

A meaningful relative path has been returned.

MK_S_HIM

No common prefix is shared by the two monikers and the moniker returned in ppmkRelPath is pmkOther.

MK_E_NOTBINDABLE

This moniker is a relative moniker, such as an item moniker. This moniker must be composed with the moniker of its container before a relative path can be determined.

Remarks

A relative moniker is analogous to a relative path (such as “..\backup”). For example, suppose you have one moniker that represents the path “c:\projects\secret\art\pict1.bmp” and another moniker that represents the path “c:\projects\secret\docs\chap1.txt.” Calling IMoniker::RelativePathTo on the first moniker, passing the second one as the pmkOther parameter, would create a relative moniker representing the path “..\docs\chap1.txt.”

Notes to Callers

Moniker clients typically do not need to call IMoniker::RelativePathTo. This method is primarily called by the default handler for linked objects. Linked objects contain both an absolute and a relative moniker to identify the link source (this enables link tracking if the user moves a directory tree containing both the container and source files). The default handler calls this method to create a relative moniker from the container document to the link source (that is, it calls IMoniker::RelativePathTo on the moniker identifying the container document, passing the moniker identifying the link source as the pmkOther parameter).

If you do call IMoniker::RelativePathTo, call it only on absolute monikers; for example, a file moniker or a composite moniker whose leftmost component is a file moniker, where the file moniker represents an absolute path. Do not call this method on relative monikers.

Notes to Implementers

Your implementation of IMoniker::RelativePathTo should first determine whether pmkOther is a moniker of a class that you recognize and for which you can provide special handling (for example, if it is of the same class as this moniker). If so, your implementation should determine the relative path. Otherwise, it should pass both monikers in a call to the MonikerRelativePathTo function, which correctly handles the generic case.

The first step in determining a relative path is determining the common prefix of this moniker and pmkOther. The next step is to break this moniker and pmkOther into two parts each, say (P, myTail) and (P, otherTail) respectively, where P is the common prefix. The correct relative path is then the inverse of myTail composed with otherTail:

Comp( Inv( myTail ), otherTail )

Where Comp() represents the composition operation and Inv() represents the inverse operation.

Note that for certain types of monikers, you cannot use your IMoniker::Inverse method to construct the inverse of myTail. For example, a file moniker returns an anti-moniker as an inverse, while its IMoniker::RelativePathTo method must use one or more file monikers that each represent the path “..” to construct the inverse of myTail.

See Also

IMoniker::Inverse, IMoniker::CommonPrefixWith, MonikerRelativePathTo


IMoniker - Anti-Moniker Implementation

Anti-monikers are the inverse of the OLE implementations of file, item, and pointer monikers. That is, an anti-moniker composed to the right of a file moniker, item moniker, or pointer moniker composes to nothing.

When To Use

If you’re a moniker client, you typically do not need to use anti-monikers. When you need the inverse of a moniker, you should call IMoniker::Inverse. For example, if you need an inverse to remove the last piece of a composite moniker, use IMoniker::Enum to enumerate the pieces of the moniker and call IMoniker::Inverse on the rightmost piece. You shouldn’t use an anti-moniker for this purpose because you can’t be sure that the rightmost piece of a composite considers an anti-moniker to be its inverse.

The only situation in which you should explicitly use an anti-moniker is if you are writing a new moniker class and if you have no special requirements for constructing inverses to your monikers. In that situation, you can return anti-monikers from your implementation of IMoniker::Inverse. In your implementation of IMoniker::ComposeWith, you should then annihilate one of your monikers for every anti-moniker you encounter.

Remarks

IMoniker::BindToObject

This method is not implemented. It returns E_NOTIMPL.

IMoniker::BindToStorage

This method is not implemented. It returns E_NOTIMPL.

IMoniker::Reduce

This method returns MK_S_REDUCED_TO_SELF and passes back the same moniker.

IMoniker::ComposeWith

If fOnlyIfNotGeneric is TRUE, this method sets ppmkComposite to NULL moniker and returns MK_E_NEEDGENERIC; otherwise, the method returns the result of combining the two monikers into a generic composite. Note that composing a file, item, or pointer moniker to the right of an anti-moniker produces a generic composite rather than composing to nothing, as would be the case if the order of composition were reversed.

IMoniker::Enum

This method returns S_OK and sets *ppenumMoniker to NULL.

IMoniker::IsEqual

This method returns S_OK if both are anti-monikers; otherwise, it returns S_FALSE.

IMoniker::Hash

This method calculates a hash value for the moniker.

IMoniker::IsRunning

This method checks the ROT to see if the object is running.

IMoniker::GetTimeOfLastChange

This method is not implemented (that is, it returns E_NOTIMPL).

IMoniker::Inverse

This method returns MK_E_NOINVERSE and sets *ppmk to NULL.

IMoniker::CommonPrefixWith

If the other moniker is also an anti-moniker, the method returns MK_S_US and sets ppmkPrefix to this moniker. Otherwise, the method calls the MonikerCommonPrefixWith function. This function correctly handles the case where the other moniker is a generic composite.

IMoniker::RelativePathTo

This method returns MK_S_HIM and sets *ppmkRelPath to the other moniker.

IMoniker::GetDisplayName

For each anti-moniker contained in this moniker, this method return one instance of “\..”

IMoniker::ParseDisplayName

This method is not implemented (that is, it returns E_NOTIMPL).

IMoniker::IsSystemMoniker

This method returns S_OK and indicates MKSYS_ANTIMONIKER.

See Also

CreateAntiMoniker, IMoniker


IMoniker - Class Moniker Implementation

Class monikers are monikers that represent an object class. Class monikers bind to the class object of the class for which they are created.

Class monikers are most useful in composition with other types of monikers, such as file monikers or item monikers. Class monikers may also be composed to the right of monikers supporting binding to the IClassActivator interface. This allows IClassActivator to provide access to the class object and instances of the class.

When to Use

To use class monikers, you must use the CreateClassMoniker function to create the monikers.

Remarks

IMoniker::BindToObject

If pmkLeft is NULL, calls CoGetClassObject using the CLSID the class moniker was initialized with (in CreateClassMoniker or through MkParseDisplayName) and the CLSCTX of the current pbc (IBindContext).

If pmkLeft is non-NULL, calls pmkLeft->BindToObject for IClassActivator and calls IClassActivator::GetClassObject with the CLSID it was initialized with and the CLSCTX and LOCALE parameters from of the current pbc (IBindContext).

This process is very roughly sketched out in the following code:

    BIND_OPTS2    bindOpts;

    IClassActivator *pActivate;

    bindOpts.cbStruct = sizeof(bindOpts);

    pbc->GetBindOptions(&bindOpts);

    if (NULL == pmkToLeft)

        return CoGetClassObject(<clsid>, bindOpts.dwClassContext, NULL, riid, ppvResult);

    pmkToLeft->BindToObject(pbc, NULL, IID_IClassActivator, (void **) &pActivate);

    hr = pActivate->GetClassObject(<clsid>, bindOpts.dwClassContext, bindOpts.locale, iid, ppvResult);

    pActivate->Release();

    return hr;

IMoniker::BindToStorage

This method forwards to the class moniker’s BindToObject.

IMoniker::Reduce

This method returns MK_S_REDUCED_TO_SELF and passes back the same moniker.

IMoniker::ComposeWith

Follows the contract, and behaves like an Item Moniker in that it can return E_INVALIDARG and MK_E_NEEDGENERIC, etc.

IMoniker::Enum

This method returns S_OK and sets ppenumMoniker to NULL. May return E_INVALIDARG if ppenumMoniker is an invalid pointer.

IMoniker::IsEqual

This method returns S_OK if pmkOther is a class moniker constructed with the same CLSID information as itself. Otherwise, the method returns S_FALSE. May return E_INVALIDARG if pmkOther is an invalid pointer.

IMoniker::Hash

This method calculates a hash value for the moniker and returns S_OK. may return E_INVALIDARG if pdwHash is an invalid pointer.

IMoniker::IsRunning

Returns E_NOTIMPL.

IMoniker::GetTimeOfLastChange

Returns MK_E_UNAVAILABLE.

IMoniker::Inverse

This method returns an anti-moniker (i.e., the results of calling CreateAntiMoniker).

IMoniker::CommonPrefixWith

If pmkOther IsEqual to this moniker, retrives a pointer to this moniker and returns MK_S_US. If pmkOther is a class moniker but is not equal to this moniker, returns MK_E_NOPREFIX. Otherwise returns the result of calling MonikerCommonPrefixWith with itself as pmkThis, pmkOther and ppmkPrefix, which handles the case whre pmkOther is a generic composite moniker.

IMoniker::RelativePathTo

This method returns the result of calling This method returns the result of calling MonikerRelativePathTo with pmkSrc equal to this moniker, pmkOther, ppmkRelPath, and TRUE as dwReserved.

IMoniker::GetDisplayName

The display name for class monikers is of the form:

display-name = “CLSID:” string-clsid-no-curly-braces *[“;” clsid-options] “:”

clsid-options = clsid-param “=“ value

clsid-param = none currently defined

Example:

clsid:a7b90590-36fd-11cf-857d-00aa006d2ea4:

IMoniker::ParseDisplayName

This method parses the display name by binding to itself for IParseDisplayName and asking the bound object to parse the display name into a moniker, as follows:

    hr = BindToObject(pbc, pmkToLeft, IID_IParseDisplayName, (void**)&ppdn);

    if (SUCCEEDED(hr)) {

        hr = ppdn->ParseDisplayName(pbc, lpszDisplayName, pchEaten, ppmkOut);

        ppdn->Release();

        }

    return hr;

This method tries to acquire an IParseDisplayName pointer, first by binding to the class factory for the object identified by the moniker, and then by binding to the object itself. If either of these binding operations is successful, the file moniker passes the unparsed portion of the display name to the IParseDisplayName::ParseDisplayName method.

This method returns MK_E_SYNTAX if pmkToLeft is non-NULL.

IMoniker::IsSystemMoniker

This method returns S_OK, and passes back MKSYS_CLASSMONIKER.

See Also

CreateClassMoniker, IMoniker


IMoniker - File Moniker Implementation

File monikers are monikers that represent a path in the file system; a file moniker can identify any object that is saved in its own file. To identify objects contained within a file, you can compose monikers of other classes (for example, item monikers) to the right of a file moniker. However, the moniker to the left of a file moniker within a composite must be another file moniker, an anti-moniker, or a class moniker. It is illegal, for example, for an item moniker to appear to the left of a file moniker in a composite.

Note that an anti-moniker is the inverse of an entire file moniker, not the inverse of a component of the path that the moniker represents; that is, when you compose an anti-moniker to the right of a file moniker, the entire file moniker is removed. If you want to remove just the rightmost component of the path represented by a file moniker, you must create a separate file moniker based on the “..” path and then compose that to the end of the file moniker.

When to Use

If you’re a moniker client (that is, you’re using a moniker to get an interface pointer to an object), you typically don’t need to know the class of the moniker you’re using; you simply call methods using an IMoniker interface pointer.

If you’re a moniker provider (that is, you’re handing out monikers that identify your objects to make them accessible to moniker clients), you must use file monikers if the objects you’re identifying are stored in files. If each object resides in its own file, file monikers are the only type you need. If the objects you’re identifying are smaller than a file, you need to use another type of moniker (for example, item monikers) in addition to file monikers.

To use file monikers, you must use the CreateFileMoniker function to create the monikers. In order to allow your objects to be loaded when a file moniker is bound, your objects must implement the IPersistFile interface.

The most common example of moniker providers are OLE server applications that support linking. If your OLE server application supports linking only to file-based documents in their entirety, file monikers are the only type of moniker you need. If your OLE server application supports linking to objects smaller than a document (such as sections of a document or embedded objects), you must use item monikers as well as file monikers.

Remarks

IMoniker::BindToObject

When pmkToLeft is NULL, the method looks for the moniker in the ROT, and if found, queries the retrieved object for the requested interface pointer. If the moniker is not found in the ROT, the method loads the object from the file system and retrieves the requested interface pointer.

If pmkLeft is not NULL, then instead of determining the class to instantiate and initialize with the contents of the file referred to by the file moniker using GetClassFile (or other means), call pmkLeft->BindToObject for IClassFactory and IClassActivator, retrieve this pointer in pcf.

If this fails with E_NOINTERFACE, return MK_E_INTERMEDIATEINTERFACENOTSUPPORTED.

If the IClassFactory pointer is successfully retrieved, call pcf->CreateInstance(IID_IPersistFile, (void**)&ppf) to get a fresh instance of the class to be initialized and initialize it using IPersistFile or other appropriate means per the existing initialization paths of File moniker.

IMoniker::BindToStorage

This method opens the file specified by the path represented by the moniker and returns an IStorage pointer to that file. The method supports binding to IStorage interface only; if IStream or ILockBytes is requested in riid, the method returns E_UNSPEC, and if other interfaces are requested, this method returns E_NOINTERFACE. IStream and ILockBytes will be supported in future releases. Unless pmkToLeft is a class moniker, pmkToLeft should be NULL, as in the implementation of IMoniker::BindToObject. For situations where pmkToLeft is non-NULL, see the above description.

IMoniker::Reduce

This method returns MK_S_REDUCED_TO_SELF and passes back the same moniker.

IMoniker::ComposeWith

If pmkRight is an anti-moniker, the returned moniker is NULL. If pmkRight is a composite whose leftmost component is an anti-moniker, the returned moniker is the composite with the leftmost anti-moniker removed. If pmkRight is a file moniker, this method collapses the two monikers into a single file moniker, if possible. If not possible (e.g., if both file monikers represent absolute paths, as in d:\work and e:\reports), then the returned moniker is NULL and the return value is MK_E_SYNTAX. If pmkRight is neither an anti-moniker nor a file moniker, then the method checks the fOnlyIfNotGeneric parameter; if it is FALSE, the method combines the two monikers into a generic composite; if it is TRUE, the method sets *ppmkComposite to NULL and returns MK_E_NEEDGENERIC.

IMoniker::Enum

This method returns S_OK and sets ppenumMoniker to NULL.

IMoniker::IsEqual

This method returns S_OK if *pmkOther is a file moniker and the paths for both monikers are identical (using a case-insensitive comparison). Otherwise, the method returns S_FALSE.

IMoniker::Hash

This method calculates a hash value for the moniker.

IMoniker::IsRunning

If pmkNewlyRunning is non-NULL, this method returns TRUE if that moniker is equal to this moniker. Otherwise, the method asks the ROT whether this moniker is running. The method ignores pmkToLeft.

IMoniker::GetTimeOfLastChange

If this moniker is in the ROT, this method returns the last change time registered there; otherwise, it returns the last write time for the file. If the file cannot be found, this method returns MK_E_NOOBJECT.

IMoniker::Inverse

This method returns an anti-moniker (i.e., the results of calling CreateAntiMoniker).

IMoniker::CommonPrefixWith

If both monikers are file monikers, this method returns a file moniker that is based on the common components at the beginning of two file monikers. Components of a file moniker can be:

•	A machine name of the form \\server\share. A machine name is treated as a single component, so two monikers representing the paths “\\myserver\public\work” and “\\myserver\private\games” do not have “\\myserver” as a common prefix.

•	A drive designation (for example, “C:”).

•	A directory or file name.

If the other moniker is not a file moniker, this method passes both monikers in a call to the MonikerCommonPrefixWith function. This function correctly handles the case where the other moniker is a generic composite.

This method returns MK_E_NOPREFIX if there is no common prefix.

IMoniker::RelativePathTo

This method computes a moniker which when composed to the right of this moniker yields the other moniker. For example, if the path of this moniker is “C:\work\docs\report.doc” and if the other moniker is “C:\work\art\picture.bmp,” then the path of the computed moniker would be “..\..\art\picture.bmp.”

IMoniker::GetDisplayName

This method returns the path that the moniker represents. If this method is called by a 16-bit application, the method checks to see whether the specified file exists and, if so, returns a short name for that file because 16-bit applications are not equipped to handle long file names.

IMoniker::ParseDisplayName

This method tries to acquire an IParseDisplayName pointer, first by binding to the class factory for the object identified by the moniker, and then by binding to the object itself. If either of these binding operations is successful, the file moniker passes the unparsed portion of the display name to the IParseDisplayName::ParseDisplayName method.

This method returns MK_E_SYNTAX if pmkToLeft is non-NULL.

IMoniker::IsSystemMoniker

This method returns S_OK, and passes back MKSYS_FILEMONIKER.

See Also

CreateFileMoniker, IMoniker, IPersistFile


IMoniker - Generic Composite Moniker Implementation

A generic composite moniker is a composite moniker whose components have no special knowledge of each other.

Composition is the process of joining two monikers together. Sometimes two monikers of specific classes can be combined in a special manner; for example, a file moniker representing an incomplete path and another file moniker representing a relative path can be combined to form a single file moniker representing the complete path. This is an example of “non-generic” composition. “Generic” composition, on the other hand, can connect any two monikers, no matter what their classes. Because a non-generic composition depends on the class of the monikers involved, it can be performed only by a particular class’s implementation of the IMoniker::ComposeWith method. You can define new types of non-generic compositions if you write a new moniker class. By contrast, generic compositions are performed by the CreateGenericComposite function.

When to Use

If you’re a moniker client (that is, you’re using a moniker to get an interface pointer to an object), you typically don’t need to know the class of the moniker you’re using, or whether it is a generic composite or a non-generic composite; you simply call methods using an IMoniker interface pointer.

If you’re a moniker provider (that is, you’re handing out monikers that identify your objects to make them accessible to moniker clients), you may have to compose two monikers together. (For example, if you are using an item moniker to identify an object, you must compose it with the moniker identifying the object’s container before you hand it out.) You use the IMoniker::ComposeWith method to do this, calling the method on the first moniker and passing the second moniker as a parameter; this method may produce either a generic or a non-generic composite.

The only time you should explicitly create a generic composite moniker is if you are writing your own moniker class. In your implementation of IMoniker::ComposeWith, you should attempt to perform a non-generic composition whenever possible; if you cannot perform a non-generic composition and generic composition is acceptable, you can call the CreateGenericComposite function to create a generic composite moniker.

Remarks

IMoniker::BindToObject

If pmkToLeft is NULL, this method looks for the moniker in the ROT, and if found, queries the retrieved object for the requested interface pointer. If pmkToLeft is not NULL, the method recursively calls IMoniker::BindToObject on the rightmost component of the composite, passing the rest of the composite as the pmkToLeft parameter for that call.

IMoniker::BindToStorage

This method recursively calls BindToStorage on the rightmost component of the composite, passing the rest of the composite as the pmkToLeft parameter for that call.

IMoniker::Reduce

This method recursively calls Reduce for each of its component monikers. If any of the components reduces itself, the method returns S_OK and passes back a composite of the reduced components. If no reduction occurred, the method passes back the same moniker and returns MK_S_REDUCED_TO_SELF.

IMoniker::ComposeWith

If fOnlyIfNotGeneric is TRUE, this method sets *pmkComposite to NULL and returns MK_E_NEEDGENERIC; otherwise, the method returns the result of combining the two monikers by calling the CreateGenericComposite function.

IMoniker::Enum

If successful, this method returns S_OK and passes back an enumerator that enumerates the component monikers that make up the composite; otherwise, the method returns E_OUTOFMEMORY.

IMoniker::IsEqual

This method returns S_OK if the components of both monikers are equal when compared in the left-to-right order.

IMoniker::Hash

This method calculates a hash value for the moniker.

IMoniker::IsRunning

If pmkToLeft is non-NULL, this method composes pmkToLeft with this moniker and calls IsRunning on the result.

If pmkToLeft is NULL, this method returns TRUE if pmkNewlyRunning is non-NULL and is equal to this moniker.

If pmkToLeft and pmkNewlyRunning are both NULL, this method checks the ROT to see whether the moniker is running. If so, the method returns S_OK; otherwise, it recursively calls IMoniker::IsRunning on the rightmost component of the composite, passing the remainder of the composite as the pmkToLeft parameter for that call. This handles the case where the moniker identifies a pseudo-object that is not registered as running; see the Item Moniker implementation of IMoniker::IsRunning.

IMoniker::GetTimeOfLastChange

This method creates a composite of pmkToLeft (if non-NULL) and this moniker and uses the ROT to retrieve the time of last change. If the object is not in the ROT, the method recursively calls IMoniker::GetTimeOfLastChange on the rightmost component of the composite, passing the remainder of the composite as the pmkToLeft parameter for that call.

IMoniker::Inverse

This method returns a composite moniker that consists of the inverses of each of the components of the original composite, stored in reverse order. For example, if the inverse of A is A  (-1)  , then the inverse of the composite A  (°)  B  (°)  C is C  (-1)   (°)  B  (-1)   (°)  A  (-1) .

IMoniker::CommonPrefixWith

If the other moniker is a composite, this method compares the components of each composite from left to right. The returned common prefix moniker might also be a composite moniker, depending on how many of the leftmost components were common to both monikers. If the other moniker is not a composite, the method simply compares it to the leftmost component of this moniker.

If the monikers are equal, the method returns MK_S_US and sets ppmkPrefix to this moniker. If the other moniker is a prefix of this moniker, the method returns MK_S_HIM and sets ppmkPrefix to the other moniker. If this moniker is a prefix of the other, this method returns MK_S_ME and sets ppmkPrefix to this moniker.

If there is no common prefix, this method returns MK_E_NOPREFIX and sets ppmkPrefix to NULL.

IMoniker::RelativePathTo

This method finds the common prefix of the two monikers and creates two monikers that consist of the remainder when the common prefix is removed. Then it creates the inverse for the remainder of this moniker and composes the remainder of the other moniker on the right of it.

IMoniker::GetDisplayName

This method returns the concatenation of the display names returned by each component moniker of the composite.

IMoniker::ParseDisplayName

This method recursively calls IMoniker::ParseDisplayName on the rightmost component of the composite, passing everything else as the pmkToLeft parameter for that call.

IMoniker::IsSystemMoniker

This method returns S_OK and indicates MKSYS_GENERICCOMPOSITE.

See Also

CreateGenericComposite, IMoniker


IMoniker - Item Moniker Implementation

Item monikers are used to identify objects within containers, such as a portion of a document, an embedded object within a compound document, or a range of cells within a spreadsheet. Item monikers are often used in combination with file monikers; a file moniker is used to identify the container while an item moniker is used to identify the item within the container.

An item moniker contains a text string; this string is used by the container object to distinguish the contained item from the others. The container object must implement the IOleItemContainer interface; this interface enables the item moniker code to acquire a pointer to an object, given only the string that identifies the object.

When to Use

If you’re a moniker client (that is, you’re using a moniker to get an interface pointer to an object), you typically don’t need to know the class of the moniker you’re using; you simply call methods using an IMoniker interface pointer.

If you’re a moniker provider (that is, you’re handing out monikers that identify your objects to make them accessible to moniker clients), you must use item monikers if the objects you’re identifying are contained within another object and can be individually identified using a string. You’ll also need to use another type of moniker (for example, file monikers) in order to identify the container object.

To use item monikers, you must use the CreateItemMoniker function to create the monikers. In order to allow your objects to be loaded when an item moniker is bound, the container of your objects must implement the IOleItemContainer interface.

The most common example of moniker providers are OLE applications that support linking. If your OLE application supports linking to objects smaller than a file-based document, you need to use item monikers. For a server application that allows linking to a selection within a document, you use the item monikers to identify those objects. For a container application that allows linking to embedded objects, you use the item monikers to identify the embedded objects.

Remarks

IMoniker::BindToObject

If pmkToLeft is NULL, this method returns E_INVALIDARG. Otherwise, the method calls IMoniker::BindToObject on the pmkToLeft parameter, requesting an IOleItemContainer interface pointer. The method then calls IOleItemContainer::GetObject, passing the string contained within the moniker, and returns the requested interface pointer.

IMoniker::BindToStorage

If pmkToLeft is NULL, this method returns E_INVALIDARG. Otherwise, the method calls IMoniker::BindToObject on the pmkToLeft parameter, requesting an IOleItemContainer interface pointer. The method then calls IOleItemContainer::GetObjectStorage for the requested interface.

IMoniker::Reduce

This method returns MK_S_REDUCED_TO_SELF and passes back the same moniker.

IMoniker::ComposeWith

If pmkRight is an anti-moniker, the returned moniker is NULL; if pmkRight is a composite whose leftmost component is an anti-moniker, the returned moniker is the composite after the leftmost anti-moniker is removed. If pmkRight is not an anti-moniker, the method combines the two monikers into a generic composite if fOnlyIfNotGeneric is FALSE; if fOnlyIfNotGeneric is TRUE, the method returns a NULL moniker and a return value of MK_E_NEEDGENERIC.

IMoniker::Enum

This method returns S_OK and sets *ppenumMoniker to NULL.

IMoniker::IsEqual

This method returns S_OK if both monikers are item monikers and their display names are identical (using a case-insensitive comparison); otherwise, the method returns S_FALSE.

IMoniker::Hash

This method calculates a hash value for the moniker.

IMoniker::IsRunning

If pmkToLeft is NULL, this method returns TRUE if pmkNewlyRunning is non-NULL and is equal to this moniker. Otherwise, the method checks the ROT to see whether this moniker is running.

If pmkToLeft is non-NULL, the method calls IMoniker::BindToObject on the pmkToLeft parameter, requesting an IOleItemContainer interface pointer. The method then calls IOleItemContainer::IsRunning, passing the string contained within this moniker.

IMoniker::GetTimeOfLastChange

If pmkToLeft is NULL, this method returns MK_E_NOTBINDABLE. Otherwise, the method creates a composite of pmkToLeft and this moniker and uses the ROT to access the time of last change. If the object is not in the ROT, the method calls IMoniker::GetTimeOfLastChange on the pmkToLeft parameter.

IMoniker::Inverse

This method returns an anti-moniker (i.e., the results of calling CreateAntiMoniker).

IMoniker::CommonPrefixWith

If the other moniker is an item moniker that is equal to this moniker, this method sets *ppmkPrefix to this moniker and returns MK_S_US; otherwise, the method calls the MonikerCommonPrefixWith function. This function correctly handles the case where the other moniker is a generic composite.

IMoniker::RelativePathTo

This method returns MK_E_NOTBINDABLE and sets *ppmkRelPath to NULL.

IMoniker::GetDisplayName

This method returns the concatenation of the delimiter and the item name that were specified when the item moniker was created.

IMoniker::ParseDisplayName

If pmkToLeft is NULL, this method returns MK_E_SYNTAX. Otherwise, the method calls IMoniker::BindToObject on the pmkToLeft parameter, requesting an IOleItemContainer interface pointer. The method then calls IOleItemContainer::GetObject, requesting an IParseDisplayName interface pointer to the object identified by the moniker, and passes the display name to IParseDisplayName::ParseDisplayName.

IMoniker::IsSystemMoniker

This method returns S_OK and indicates MKSYS_ITEMMONIKER.

See Also

CreateItemMoniker, IMoniker, IOleItemContainer


IMoniker - Pointer Moniker Implementation

A pointer moniker essentially wraps an interface pointer so that it looks like a moniker and can be passed to those interfaces that require monikers. Binding a pointer moniker is done by calling the pointer’s QueryInterface method.

Instances of pointer monikers refuse to be serialized, that is, IPersistStream::Save will return an error. These monikers can, however, be marshaled to a different process in an RPC call; internally, the system marshals and unmarshals the pointer using the standard paradigm for marshaling interface pointers.

When to Use

Pointer monikers are rarely needed. Use pointer monikers only if you need monikers to identify objects that have no persistent representation. Pointer monikers allow such objects to participate in a moniker-binding operation.

Remarks

IMoniker::BindToObject

This method queries the wrapped pointer for the requested interface.

IMoniker::BindToStorage

This method queries the wrapped pointer for the requested interface.

IMoniker::Reduce

This method returns MK_S_REDUCED_TO_SELF and passes back the same moniker.

IMoniker::ComposeWith

If pmkRight is an anti-moniker, the returned moniker is NULL; if pmkRight is a composite whose leftmost component is an anti-moniker, the returned moniker is the composite after the leftmost anti-moniker is removed. If fOnlyIfNotGeneric is FALSE, the returned moniker is a generic composite of the two monikers; otherwise, the method sets *ppmkComposite to NULL and returns MK_E_NEEDGENERIC.

IMoniker::Enum

This method is not implemented (that is, it returns E_NOTIMPL).

IMoniker::IsEqual

This method returns S_OK only if both are pointer monikers and the interface pointers that they wrap are identical.

IMoniker::Hash

This method calculates a hash value for the moniker.

IMoniker::IsRunning

This method always returns S_OK, because the object identified by a pointer moniker must always be running.

IMoniker::GetTimeOfLastChange

This method is not implemented (that is, it returns E_NOTIMPL).

IMoniker::Inverse

This method returns an anti-moniker (i.e., the results of calling CreateAntiMoniker).

IMoniker::CommonPrefixWith

If the two monikers are equal, this method returns MK_S_US and sets *ppmkPrefix to this moniker. Otherwise, the method returns MK_E_NOPREFIX and sets *ppmkPrefix to NULL.

IMoniker::RelativePathTo

This method is not implemented (that is, it returns E_NOTIMPL).

IMoniker::GetDisplayName

This method is not implemented (that is, it returns E_NOTIMPL).

IMoniker::ParseDisplayName

This method queries the wrapped pointer for the IParseDisplayName interface and passes the display name to IParseDisplayName::ParseDisplayName.

IMoniker::IsSystemMoniker

This method returns S_OK and indicates MKSYS_POINTERMONIKER.

See Also

IMoniker, CreatePointerMoniker


IMultiQI

The IMultiQI interface enables a client to query an object proxy, or handler, for multiple interfaces, using a single RPC call. By using this interface, instead of relying on separate calls to IUnknown::QueryInterface, clients can reduce the number of RPC calls that have to cross thread, process, or machine boundaries and, therefore, the amount of time required to obtain the requeseted interface pointers.

When to Implement

You never have to implement this interface because there is no situation in which it is required. OLE server applications that rely on COM’s standard remoting support get the interface for free because COM implements it on every object proxy. The only situation in which you might want to implement this interface yourself is if you are writing a custom marshaler that handles interface remoting. Even here, implementing IMultiQI yourself is not recommended, particularly if your object is aggregatable.

When to Use

When more than one interface pointer is sought, client applications should QueryInterface for IMultiQI and use it if available.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IMultiQI Methods	Description
QueryMultipleInterfaces	Queries for multiple interfaces.
See Also

IUnknown::QueryInterface


IMultiQI::QueryMultipleInterfaces

Fills a caller-provided array of structures with pointers to multiple interfaces.Calling this method is equivalent to issuing a series of separate QueryInterface calls except that you do not incur the overhead of a corresponding number of RPC calls. In multithreaded applications and distributed environments, keeping RPC calls to a minimum is essential for optimal performance.

HRESULT QueryMultipleInterfaces(

ULONG cMQIs	// Number of structures in array
MULTI_QI *pMQIs	// Pointer to first structure in array
);
Parameters

cMQIs

[in] Pointer to the number of elements in an array of MULTI_QI structures, each of which contains the IID of a single interface.

pMQIs

[in, out] Pointer to the first MULTI_QI strucutre in the array.

Return Value

S_OK

Pointers were returned to all requested interfaces.

S_FALSE

Pointers were returned to some, but not all, of the requested interfaces.

E_NOINTERFACE

Pointers were returned to none of the requested interfaces.

Remarks

The QueryMultipleInterfaces method takes as input an array of MULTI_QI structures. Each structure specifies an interface IID and contains two additional blank fields for receiving an interface pointer and return value.

This method obtains as many requested interface pointers as possible directly from the object proxy. For each interface not implemented on the proxy, the method calls the server to obtain a pointer. Upon receiving an interface pointer from the server, the method builds a corresponding interface proxy and returns its pointer along with pointers to the interfaces it already implements.

Notes to Callers

A caller should begin by querying the object proxy for the IMultiQI interface. If the object proxy returns a pointer to this interface, the caller should then create a MULTI_QI structure for each interface it wants to obtain. Each structure should specify an interface IID and set its pItf member to NULL. Failure to set the pItf member to NULL will cause the object proxy to ignore the structure.

On return, QueryMultipleInterfaces writes the requested interface pointer and a return value into each MULTI_QI structure in the client’s array. The pItf field receives the pointer; the hr field receives the return value.

If the value returned from a call to QueryMultipleInterfaces is S_OK, then pointers were returned for all requested interfaces. If the return value is E_NOINTERFACE, then pointers were returned for none of the requested interfaces. If the return value is S_FALSE, then pointers to one or more requested interfaces were not returned.In this event, the client should check the hr field of each MULTI_QI structure to determine which interfaces were acquired and which were not.

If a client knows ahead of time that it will be using several of an object’s interfaces, it can call QueryMultipleInterfaces up front and then, later, if a QueryInterface is done for one of the interfaces already acquired through QueryMultipleInterfaces, no RPC call will be necessary.

On return, the caller should check the hr field of each MULTI_QI structure to determine which interface pointers were and were not returned.

The client is responsible for releasing each of the acquired interfaces by calling IUnknown::Release.

See Also

IUnknown


IObjectWithSite

The IObjectWithSite interface provides a simple way to support communication between an object and its site in the container.

Often an object needs to communicate directly with a container site object and, in effect, manage the site object itself. Outside of IOleObject::SetClientSite, there is no generic means through which an object becomes aware of its site. IObjectWithSite provides simple objects with a simple siting mechanism (lighter than IOleObject) This interface should only be used when IOleObject is not already in use.

Through IObjectWithSite, a container can pass the IUnknown pointer of its site to the object through IObjectWithSite::SetSite. Callers can also retrieve the latest site passed to IObjectWithSite::SetSite through IObjectWithSite::GetSite. This latter method is included as a hooking mechanism, allowing a third party to intercept calls from the object to the site.

When to Implement

An object implements this interface so it’s container can supply it with an interface pointer for its site object. Then, the object can communicate directly with its site.

When to Use

A container calls the SetSite method on this interface to provide an object with an interface pointer for its site.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IObjectWithSite Methods	Description
SetSite	Provides the site’s IUnknown pointer to the object being managed.
GetSite	Retrieves the last site set with IObjectWithSite::SetSite.


IObjectWithSite::GetSite

Retrieves the last site set with IObjectWithSite::SetSite. If there’s no known site, the object return a failure code.

HRESULT GetSite(

REFIID riid,	//IID of interface pointer being requested
void** ppvSite	//Indirect pointer to caller’s void
);
Parameters

riid

[in] The IID of the interface pointer that should be returned in ppvSite.

ppvSite

[out] Indirect pointer to the caller’s void * variable in which the object stores the interface pointer of the site last seen in IObjectWithSite::SetSite. The specific interface returned depends on the riid argument—in essence, the two arguments act identically to those in IUnknown::QueryInterface. If the appropriate interface pointer is available, the object must call IUnknown::AddRef on that pointer before returning successfully. If no site is available, or the requested interface is not supported, the object sets this argument to NULL and returns a failure code.

Return Values

S_OK

The site was returned successfully and the caller is responsible for calling IUnknown::Release when the site is no longer needed.

E_FAIL

There is no site in which case *ppvSite contains NULL on return.

E_NOINTERFACE

There is a site but it does not support the interface requested by riid.

Remarks

E_NOTIMPL is not allowed—any object implementing this interface must be able to return the last site seen in IObjectWithSite::SetSite.


IObjectWithSite::SetSite

Provides the site’s IUnknown pointer to the object. The object should hold onto this pointer, calling IUnknown::AddRef in doing so. If the object already has a site, it should call that existing site’s IUnknown::Release, save the new site pointer, and call the new site’s IUnknown::AddRef.

HRESULT SetSite(

IUnknown* pUnkSite	//Pointer to IUnknown of the site managing this object
);
Parameter

pUnkSite

[in] Pointer to the IUnknown interface pointer of the site managing this object. If NULL, the object should call IUnknown::Release on any existing site at which point the object no longer knows its site.

Return Value

S_OK

Returned in all circumstances.

Remarks

E_NOTIMPL is not allowed—without implementation of the SetSite method, the IObjectWithSite interface is unnecessary.

See Also

IObjectWithSite::GetSite


IOleAdviseHolder

The IOleAdviseHolder interface contains methods that manage advisory connections and compound document notifications in an object server. Its methods are intended to be used to implement the advisory methods of IOleObject. IOleAdviseHolder is implemented on an advise holder object. Its methods establish and delete advisory connections from the object managed by the server to the object’s container, which must contain an advise sink (support the IAdviseSink interface). The advise holder object must also keep track of which advise sinks are interested in which notifications and pass along the notifications as appropriate.

When to Implement

It is unlikely that you would choose to implement this interface. OLE provides an implementation of the OLE advise holder as a convenience to programmers.Few applications will require notification capabilities beyond those which the default advise holder provides. In general, a single server application that requires different notification capabilities would simply implement the advisory functionality in its IOleObject advisory methods. It would be necessary to implement IOleAdviseHolder only in the case where there may be a need for a custom advise holder object, whose methods are to be used to implement the IOleObject methods in a set of servers.

When to Use

Call the methods of IOleAdviseHolder to implement the advisory methods of IOleObject. Applications instantiate an OLE advise holder by calling the OLE function CreateOleAdviseHolder. (OLE also provides a data advise holder to manage data notifications. Applications create a data advise holder by calling the OLE function CreateDataAdviseHolder.)

Containers and other objects that need to receive compound document notifications must implement the IAdviseSink interface to receive those notifications, and call the IOleAdviseHolder interface methods to establish an advisory connection and inform the object of what specific notifications it wishes to receive.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IOleAdviseHolder Methods	Description
Advise	Establishes advisory connection with sink.
Unadvise	Deletes advisory connection with sink.
EnumAdvise	Supplies an IEnumSTATDATA pointer to an enumeration object that can be used to determine current advisory connections.
SendOnRename	Advises sink that name of object has changed.
SendOnSave	Advises sink that object has been saved.
SendOnClose	Advises sink that object has been closed.
See Also

CreateOleAdviseHolder, IDataAdviseHolder, CreateDataAdviseHolder, IAdviseSink, IOleObject


IOleAdviseHolder::Advise

Establishes an advisory connection between an OLE object and the calling object’s advise sink. Through that sink, the calling object can receive notification when the OLE object is renamed, saved, or closed.

HRESULT Advise(

IAdviseSink * pAdvise,	//Pointer to the advise sink on the calling object
DWORD * pdwConnection	//Pointer to a token
);
Parameters

pAdvise

[in] Pointer to the IAdviseSink interface on the advisory sink that should be informed of changes.

pdwConnection

[out] Pointer to a token that can be passed to the IOleAdviseHolder::Unadvise method to delete the advisory connection. The calling object is responsible for calling both IUnknown::AddRef and IUnknown::Release on this pointer.

Return Values

This method supports the standard return value E_INVALIDARG, as well as the following:

S_OK

Advisory connections set up successfully.

Remarks

Containers, object handlers, and link objects all create advise sinks to receive notification of changes in compound-document objects of interest, such as embedded or linked objects. OLE objects of interest to these objects must implement the IOleObject interface, which includes several advisory methods, including IOleObject::Advise. A call to this method must set up an advisory connection with any advise sink that calls it, and maintain each connection until it is closed. It must be able to handle more than one advisory connection at a time.

IOleAdviseHolder::Advise is intended to be used to simplify the implementation of IOleObject::Advise. You can get a pointer to the OLE implementation of IOleAdviseHolder by calling CreateOleAdviseHolder, and then, to implement IOleObject::Advise, just delegate the call to IOleAdviseHolder::Advise. Other IOleAdviseHolder methods are intended to implement other IOleObject advisory methods.

If the attempt to establish an advisory connection is successful, the object receiving the call returns a nonzero value through pdwConnection. If the attempt fails, the object returns a zero. To delete an advisory connection, the object with the advise sink passes this nonzero token back to the object by calling IOleAdviseHolder::Unadvise.

See Also

IOleAdviseHolder::UnAdvise, IOleAdviseHolder::EnumAdvise, IOleObject::Advise


IOleAdviseHolder::EnumAdvise

Creates an enumerator that can be used to enumerate the advisory connections currently established for an object, and supplies a pointer to its IEnumSTATDATA interface.

HRESULT EnumAdvise(

IEnumSTATDATA ** ppenumAdvise	//Indirect pointer to the new enumerator
);
Parameter

ppenumAdvise

[out] Indirect pointer to the IEnumSTATDATA interface on the new enumerator. A NULL value indicates that there are presently no advisory connections on the object, or that an error occured. The advise holder is responsible for incrementing the reference count on the IEnumSTATDATA pointer this method supplies. It is the caller’s responsibility to call IUnknown::Release when it is done with the pointer.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

Enumerator created successfully.

E_NOTIMPL

EnumAdvise is not implemented.

Remarks

IOleAdviseHolder::EnumAdvise creates an enumerator that can be used to enumerate an object’s established advisory connections. The method supplies a pointer to the IEnumSTATDATA interface on this enumerator. Advisory connection information for each connection is stored in the STATDATA structure, and the enumerator must be able to enumerate these structures, defined as follows:

typedef struct tagSTATDATA {

    FORMATETC         Formatetc;

    DWORD             grfAdvf;

    IAdviseSink *     pAdvise;

    DWORD             dwConnection;

    }STATDATA;

For this method, the only relevant structure members are pAdvise and dwConnection. Other members contain data advisory information. When you call the enumeration methods, and while an enumeration is in progress, the effect of registering or revoking advisory connections on what is to be enumerated is undefined.

See Also

IOleAdviseHolder::Advise, IOleAdviseHolder::UnAdvise, IOleObject::EnumAdvise, IDataAdviseHolder::EnumAdvise, STATDATA structure


IOleAdviseHolder::SendOnClose

Sends notification that the object has closed to all advisory sinks currently registered with the advise holder.

HRESULT SendOnClose();

Return Value

S_OK

Advise sinks were notified of the close operation through a call to the IAdviseSink::OnClose method.

Remarks

IOleAdviseHolder::SendOnClose must call IAdviseSink::OnClose on all advise sinks that have a valid advisory connection with the object, whenever the object goes from the running state to the loaded state. This occurs through a call to IOleObject::Close, so you can call IOleAdviseHolder::SendOnClose when you determine that a Close operation has been successful.

See Also

IAdviseSink::OnClose


IOleAdviseHolder::SendOnRename

Sends IAdviseSink::OnRename notifications to all advisory sinks currently registered with the advise holder.

HRESULT SendOnRename(

IMoniker *pmk	//Pointer to an interface on the new moniker
);
Parameter

pmk

[in] Pointer to the new full moniker of the object.

Return Value

S_OK

Advise sinks were sent IAdviseSink::OnRename notifications.

Remarks

IOleAdviseHolder::SendOnRename calls IAdviseSink::OnRename to advise the calling object, which must have already established an advisory connection, that the object has a new moniker. If you are using the OLE advise holder (having obtained a pointer through a call to CreateOleAdviseHolder), you can call IOleAdviseHolder::SendOnRename in the implementation of IOleObject::SetMoniker, when you have determined that the operation is successful.

See Also

IAdviseSink::OnRename


IOleAdviseHolder::SendOnSave

Sends IAdviseSink::OnSave notifications to all advisory sinks currently registered with the advise holder.

HRESULT SendOnSave();

Return Value

S_OK

Advise sinks were sent IAdviseSink::OnSave notifications.

Remarks

IOleAdviseHolder::SendOnSave calls IAdviseSink::OnSave to advise the calling object (client), which must have already established an advisory connection, that the object has been saved. If you are using the OLE advise holder (having obtained a pointer through a call to CreateOleAdviseHolder), you can call IOleAdviseHolder::SendOnSave whenever you save the object the advise holder is associated with.

To take the object from the running state to the loaded state, the client calls IOleObject::Close. Within that implementation, if the user wants to save the object to persistent storage, the object calls IOleClientSite::SaveObject, followed by the call to IOleAdviseHolder::SendOnSave.

See Also

IAdviseSink::OnSave


IOleAdviseHolder::Unadvise

Deletes a previously established advisory connection.

HRESULT Unadvise(

DWORD dwConnection	//Value identifying an established advisory connection
);
Parameter

dwConnection

[in] Contains a nonzero DWORD previously returned by IOleAdviseHolder::Advise in pdwConnection.

Return Values

S_OK

Advisory connection deleted successfully.

OLE_E_NOCONNECTION

The dwConnection parameter does not represent a valid advisory connection.

Remarks

IOleAdviseHolder::Unadvise is intended to be used to implement IOleObject::Unadvise to delete an advisory connection. In general, you would use the OLE advise holder having obtained a pointer through a call to CreateOleAdviseHolder.

Normally, containers call this method at shutdown or when an object is deleted. In certain cases, containers could call this method on objects that are running but not currently visible, as a way of reducing the overhead of maintaining multiple advisory connections.

See Also

IOleAdviseHolder::Advise, IOleAdviseHolder::EnumAdvise, IOleObject::Unadvise


IOleCache

The IOleCache interface provides control of the presentation data that gets cached inside of an object. Cached presentation data is available to the container of the object even whenthe  server application is not running or is unavailable.

When to Implement

The IOleCache interface can be implemented by an object handler and an in-process server. In general, however, the methods of IOleCache are implemented as part of the IOleCache2 interface, which inherits the IOleCache definition, and adds methods for selectively updating the cache. Rather than implementing, however, it is typical to use or aggregate the OLE implementation, a pointer to which is available through a call to CreateDataCache.

When to Use

A client calls the methods of IOleCache to control what the data cache holds. A typical client would be an OLE Documents container that would cache an object’s presentation so it is available without the object actually being active.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleCache Methods	Description
Cache	Adds a presentation to the data or view cache.
Uncache	Removes a presentation previously added with IOleCache::Cache.
EnumCache	Returns an object to enumerate the current cache connections.
InitCache	Fills the cache with all the presentation data from the data object.
SetData	Fills the cache with specified format of presentation data.


IOleCache::Cache

Specifies the format and other data to be cached inside an embedded object.

HRESULT Cache(

FORMATETC * pFormatetc,	//Pointer to the format and data to be cached
DWORD advf,	//Flags that control the caching
DWORD * pdwConnection	//Pointer to the connection for future calls to uncache
);
Parameters

pFormatetc

[in] Pointer to the format and other data to be cached. View caching is specified by passing a zero clipboard format in pFormatetc.

advf

[in] Contains a group of flags that control the caching. Valid values can be derived by using an OR operation on the values in the ADVF enumeration. When used in this context, for a cache, these values have specific meanings, which are outlined in the Remarks. Refer to the ADVF enumeration for a more detailed description.

pdwConnection

[out] Pointer to a returned DWORD token that identifies this connection and can later be used to turn caching off (by passing it to IOleCache::Uncache). If this value is zero, the connection was not established. The OLE-provided implementation uses nonzero numbers for connection identifiers.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

Requested data or view successfully cached.

CACHE_S_FORMATETC_NOTSUPPORTED

The cache was created, but the object application does not support the specified format. Cache creation succeeds even if the format is not supported, allowing the caller to fill the cache. If, however, the caller does not need to keep the cache, call IOleCache::UnCache.

CACHE_S_SAMECACHE

A cache already exists for the FORMATETC passed to IOleCache::Uncache. In this case, the new advise flags are assigned to the cache, and the previously assigned connection identifier is returned.

DV_E_LINDEX

Invalid value for lindex; currently only -1 is supported.

DV_E_TYMED

The value is not valid for pFormatetc->tymed.

DV_E_DVASPECT

The value is not valid for pFormatetc->dwAspect.

DV_E_CLIPFORMAT

The value is not valid for pFormatetc->cfFormat.

CO_E_NOTINITIALIZED

The cache’s storage is not initialized.

DV_E_DVTARGETDEVICE

The value is not valid for pFormatetc->ptd.

OLE_E_STATIC

The cache is for a static object and it already has a cache node.

Remarks

IOleCache::Cache can specify either data caching or view (presentation) caching. To specify data caching, a valid data format must be passed in pFormatetc. For view caching, the cache object itself decides on the format to cache, so a caller would pass a zero data format in pFormatetc as follows:

pFormatetc->cfFormat == 0

A custom object handler can choose not to store data in a given format. Instead, it can synthesize it on demand when requested.

The advf value specifies a member of the ADVF enumeration. When one of these values (or an OR’d combination of more than one value) is used in this context, these values mean the following:

ADVF Value	Description
ADVF_NODATA	The cache is not to be updated by changes made to the running object. Instead, the container will update the cache by explicitly calling IOleCache::SetData, IDataObject::SetData, or IOleCache2::UpdateCache. This flag is usually used when the iconic aspect of an object is being cached.
ADVF_ONLYONCE	Update the cache one time only. After the update is complete, the advisory connection between the object and the cache is disconnected. The source object for the advisory connection calls the IAdviseSink::Release method.
ADVF_PRIMEFIRST	The object is not to wait for the data or view to change before updating the cache. OR’d with ADVF_ONLYONCE, this parameter provides an asynchronous GetData call.
ADVFCACHE_NOHANDLER	Synonym for ADVFCACHE_FORCEBUILTIN.
ADVFCACHE_FORCEBUILTIN	Used by DLL object applications and object handlers that draw their objects to cache presentation data to ensure that there is a presentation in the cache. This ensures that the data can be retrieved even when the object or handler code is not available.
ADVFCACHE_ONSAVE	Updates the cached representation only when the object containing the cache is saved. The cache is also updated when the OLE object changes from the running state back to the loaded state (because a subsequent save operation would require running the object again).
See Also

ADVF, IOleCache::Uncache


IOleCache::EnumCache

Returns a pointer to an enumeration object that can be used to enumerate the current cache connections.

HRESULT EnumCache(

IEnumSTATDATA ** ppenumSTATDATA	//Indirect pointer to enumerator object
);
Parameter

ppenumSTATDATA

[out] Indirect pointer to the IEnumSTATDATA interface on the new enumerator object. If this value is NULL, there are currently no cache connections at this time.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The enumerator object is successfully instantiated or there are no cache connections. Check the ppenumSTATDATA parameter to determine which result occurred. If the ppenumSTATDATA parameter is NULL, then there are no cache connections at this time.

Remarks

The enumerator object returned by this method implements the IEnumSTATDATA interface, one of the standard enumerator interfaces that contain the Next, Reset, Clone, and Skip methods. IEnumSTATDATA enumerates the data stored in an array of STATDATA structures containing information about current cache connections.

See Also

IEnumXXXX, IEnumSTATDATA, IOleCache::Cache


IOleCache::InitCache

Fills the cache as needed using the data provided by the specified data object.

HRESULT InitCache(

IDataObject * pDataObject	//Pointer to the data object from which the cache is initialized
);
Parameter

pDataObject

[in] Pointer to the IDataObject interface on the data object from which the cache is to be initialized.

Return Values

This method supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

S_OK

The cache was filled using the data provided.

OLE_E_NOTRUNNING

The cache is not running.

CACHE_E_NOCACHE_UPDATED

None of the caches were updated.

CACHE_S_SOMECACHES_NOTUPDATED

Only some of the existing caches were updated.

Remarks

IOleCache::InitCache is usually used when creating an object from a drag-and-drop operation or from a clipboard paste operation. It fills the cache as needed with presentation data from all the data formats provided by the data object provided on the clipboard or in the drag-and-drop operation. Helper functions like OleCreateFromData or OleCreateLinkFromData call this method when needed. If a container does not use these helper functions to create compound document objects, it can use IOleCache::Cache to set up the cache entries which are then filled by IOleCache::InitCache.

See Also

IOleCache::Cache


IOleCache::SetData

Initializes the cache with data in a specified format and on a specified medium.

HRESULT SetData(

FORMATETC * pFormatetc,	//Pointer to the format of the presentation data to be placed in the cache
STGMEDIUM * pmedium,	//Pointer to the storage medium containing the data to be placed in the cache
BOOL fRelease	//Ownership of the storage medium after this method is completed
);
Parameters

pFormatetc

[in] Pointer to the format of the presentation data being placed in the cache.

pmedium

[in] Pointer to the storage medium that contains the presentation data.

fRelease

[in] Ownership of the storage medium after completion of the method. If fRelease is TRUE, the cache takes ownership, freeing the medium when it is finished using it. When fRelease is FALSE, the caller retains ownership and is responsible for freeing the medium. The cache can only use the storage medium for the duration of the call.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The cache was filled.

DV_E_LINDEX

The value is not valid for pFormatetc->lindex. Currently, only -1 is supported.

DV_E_FORMATETC

The FORMATETC structure is invalid.

DV_E_TYMED

The value is not valid for pFormatetc->tymed.

DV_E_DVASPECT

The value is not valid for pFormatetc->dwAspect.

OLE_E_BLANK

Uninitialized object.

DV_E_TARGETDEVICE

The object is static and pFormatetc->ptd is non-NULL.

STG_E_MEDIUMFULL

The storage medium is full.

Remarks

IOleCache::SetData is usually called when an object is created from the Clipboard or through a drag-and-drop operation, and Embed Source data is used to create the object.

IOleCache::SetData and IOleCache::InitCache are very similar. There are two main differences. The first difference is that while IOleCache::InitCache initializes the cache with the presentation format provided by the data object, IOleCache::SetData initializes it with a single format. Second, the IOleCache::SetData method ignores the ADVF_NODATA flag while IOleCache::InitCache obeys this flag.

A container can use this method to maintain a single aspect of an object, such as the icon aspect of the object.

See Also

IDataObject::SetData, IOleCache::Cache, ADVF enumeration


IOleCache::Uncache

Removes a cache connection created in a prior call to IOleCache::Cache.

HRESULT Uncache(

DWORD dwConnection	//Cache connection to remove
);
Parameter

dwConnection

[in] Cache connection to remove. This nonzero value was returned by IOleCache::Cache when the cache was originally established.

Return Values

S_OK

The cache connection was deleted.

OLE_E_NOCONNECTION

No cache connection exists for dwConnection.

Remarks

The IOleCache::Uncache method removes a cache connection that was created in a prior call to IOleCache::Cache. It uses the dwConnection parameter that was returned by the prior call to IOleCache::Cache.

See Also

IOleCache::Cache


IOleCache2

The IOleCache2 interface allows object clients to selectively update each cache that was created with IOleCache::Cache.

When to Implement

The IOleCache2 interface can be implemented by an object handler and an in-process server. Rather than implementing, however, it is typical to use or aggregate the OLE implementation in the default handler, a pointer to which is available through a call to CreateDataCache.

When to Use

The OLE-provided implementation includes implementations of the IOleCache interface methods, from which IOleCache2 inherits its contract definition. The IOleCache2 interface is called by container applications, object handlers, or in process servers to update one or more of the caches that were created with the IOleCache::Cache method. This extended interface was added so client applications can exercise precise control over updates to the caches being maintained.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleCache Methods	Description
Cache	Adds a presentation to the data or view cache.
Uncache	Removes a presentation previously added with IOleCache::Cache.
EnumCache	Returns an object to enumerate the current cache connections.
InitCache	Fills the cache with all the presentation data from the data object.
SetData	Fills the cache with specified format of presentation data.
IOleCache2 Methods	Description
UpdateCache	Updates the specified cache(s).
DiscardCache	Discards cache(s) found in memory.


IOleCache2::DiscardCache

Discards the caches in memory.

HRESULT DiscardCache(

DWORD dwDiscardOptions	//Save options
);
Parameter

dwDiscardOptions

[in] DWORD value from the DISCARDCACHE enumeration that indicates whether data is to be saved prior to being discarded. Containers that have drawn a large object and need to free up memory can specify DISCARDCACHE_SAVEIFDIRTY so that the newest presentation is saved for the next time the object must be drawn.

Containers that have activated an embedded object, made some changes, and then called IOleObject::Close(OLECLOSE_NOSAVE) to roll back the changes can specify DISCARDCACHE_NOSAVE to ensure that the native and presentation data are not out of synchronization.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The cache(s) were discarded according to the value specified in dwDiscardOptions.

OLE_E_NOSTORAGE

There is no storage available for saving the data in the cache.

STG_E_MEDIUMFULL

The storage medium is full.

Remarks

The IOleCache2::DiscardCache method is commonly used to handle low memory conditions by freeing memory currently being used by presentation caches.

Once discarded, the cache will satisfy subsequent IDataObject::GetData calls by reverting to disk-based data.

See Also

DISCARDCACHE, IOleCache, IOleCacheControl


IOleCache2::UpdateCache

Updates specified cache(s). It updates the cache according to the value of a parameter. This method is used when the application needs precise control over caching.

HRESULT UpdateCache(

IDataObject * pDataObject,	//Pointer to the data object from which the cache is updated
DWORD grfUpdt,	//Type of cache to update
LPVOID pReserved	//Reserved
);
Parameters

pDataObject

[in] Pointer to the IDataObject interface on the data object from which the cache is updated. Object handlers and in-process servers typically pass a non-NULL value. A container application usually passes NULL, and the source is obtained from the currently running object.

grfUpdt

[in] Type of cache to update. The value is obtained by combining values from the following table:

Cache Control Values	Description
UPDFCACHE_NODATACACHE	Updates caches created by using ADVF_NODATA in the call to IOleCache::Cache.
UPDFCACHE_ONSAVECACHE	Updates caches created by using ADVFCACHE_ONSAVE in the call to IOleCache::Cache.
UPDFCACHE_ONSTOPCACHE	Updates caches created by using ADVFCACHE_ONSTOP in the call to IOleCache::Cache.
UPDFCACHE_NORMALCACHE	Dynamically updates the caches (as is normally done when the object sends out OnDataChange notices).
UPDFCACHE_IFBLANK	Updates the cache if blank, regardless of any other flag specified.
UPDFCACHE_ONLYIFBLANK	Updates only caches that are blank.
UPDFCACHE_ IFBLANKORONSAVECACHE	The equivalent of using an OR operation to combine UPDFCACHE_IFBLANK and UPDFCACHE_ONSAVECACHE.
UPDFCACHE_ALL	Updates all caches.
UPDFCACHE_ ALLBUTNODATACACHE	Updates all caches except those created with ADVF_NODATA in the call to IOleCache::Cache.  Thus, you can control updates to the caches created with the ADVF_NODATA flag and only update these caches explicitly.
pReserved

[in] Reserved for future use; must be NULL.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The cache(s) were updated according to the value specified in grfUpdt.

OLE_E_NOTRUNNING

The specified pDataObject is not running.

CACHE_E_NOCACHE_UPDATED

None of the caches were updated.

CACHE_S_SOMECACHES_NOTUPDATED

Some of the caches were updated.

See Also

IOleCache, IOleCacheControl, IDataObject


IOleCacheControl

The IOleCacheControl interface provides proper maintenance of caches. It maintains the caches by connecting the running object’s IDataObject implementation to the cache, allowing the cache to receive notifications from the running object.

When to Implement

The OLE-provided implementation is used by most handlers and in-process servers. You can get a pointer to the OLE data cache object through a call to CreateDataCache.

When to Use

Object handlers and in-process servers use this interface internally to connect the cache part of the handler to the IDataObject implementation on the running object. Container applications have no need for this interface; they use IRunnableObject or OleRun instead.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleCacheControl Methods	Description
OnRun	Notifies the cache when the data object is running so the cache object can establish advise sinks as needed.
OnStop	Notifies the cache to terminate any existing advise sinks.


IOleCacheControl::OnRun

Notifies the cache that the data source object has now entered its running state.

HRESULT OnRun(

DATAOBJECT * pDataObject	//Pointer to the object that is now running
);
Parameter

pDataObject

[in] Pointer to the IDataObject interface on the object that is entering the running state.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The cache was notified and pDataObject is valid.

Remarks

When IOleCacheControl::OnRun is called, the cache sets up advisory connections as necessary with the source data object so it can receive notifications. The advisory connection created between the running object and the cache is destroyed when IOleCacheControl::OnStop is called.

Some object handlers or in-process servers might use the cache passively, and not call IOleCacheControl::OnRun. These applications must call IOleCache2::UpdateCache, IOleCache::InitCache, or IOleCache::SetData to fill the cache when necessary to ensure that the cache gets updated.

IOleCacheControl::OnRun does not add a reference count on the pointer to IDataObject passed in pDataObject. Because it is the responsibility of the caller of OleRun to ensure that the lifetime of the pDataObject pointer lasts until OnStop is called, the caller must be holding a pointer to IDataObject on the data object of interest.

See Also

IOleCache2::UpdateCache, IOleCacheControl::OnStop


IOleCacheControl::OnStop

Notifies the cache it should terminate any existing connection previously given to it by using IOleCacheControl::OnRun. No indication is given as to whether a connection existed or not.

HRESULT OnStop( );

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The cache was notified and the advisory connection was successfully removed.

Remarks

The data advisory connection between the running object and the cache is destroyed as part of calling IOleCacheControl::OnStop.

See Also

IOleCacheControl::OnRun


IOleClientSite

The IOleClientSite interface is the primary means by which an embedded object obtains information about the location and extent of its display site, its moniker, its user interface, and other resources provided by its container. An object server calls IOleClientSite to request services from the container. A container must provide one instance of IOleClientSite for every compound-document object it contains.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IOleClientSite Methods	Description
SaveObject	Saves embedded object.
GetMoniker	Requests object’s moniker.
GetContainer	Requests pointer to object’s container.
ShowObject	Asks container to display object.
OnShowWindow	Notifies container when object becomes visible or invisible
RequestNewObjectLayout	Asks container to resize display site.


IOleClientSite::GetContainer

Returns a pointer to the container’s IOleContainer interface.

HRESULT GetContainer(

LPOLECONTAINER FAR* ppContainer	//Indirect pointer to the interface on the object
);
Parameter

ppContainer

[out] Indirect pointer to where the IOleContainer interface on the object should be returned. If an error is returned, this parameter must be set to NULL.

Return Values

S_OK

The pointer to the container’s IOleContainer interface was successfully returned.

OLE_E_NOT_SUPPORTED

Client site is in OLE 1 container.

E_NOINTERFACE

The container does not implement the IOleContainer interface.

Remarks

If a container supports links to its embedded objects, implementing IOleClientSite::GetContainer enables link clients to enumerate the container’s objects and recursively traverse a containment hierarchy. This method is optional but recommended for all containers that expect to support links to their embedded objects.

Link clients can traverse a hierarchy of compound-document objects by recursively calling IOleClientSite::GetContainer to get a pointer to the link source’s container; followed by IOleContainer::QueryInterface to get a pointer to the container’s IOleObject interface and, finally, IOleObject::GetClientSite to get the container’s client site in its container.

Simple containers that do not support links to their embedded objects probably do not need to implement this method. Instead, they can return E_NOINTERFACE and set ppContainer to NULL.


IOleClientSite::GetMoniker

Returns a moniker to an object’s client site. An object can force the assignment of its own or its container’s moniker by specifying a value for dwAssign.

HRESULT GetMoniker(

DWORD dwAssign,	//Value specifying how moniker is assigned
DWORD dwWhichMoniker,	//Value specifying which moniker is assigned
IMoniker ** ppmk	//Indirect pointer to moniker
);
Parameters

dwAssign

[in] Specifies whether to get a moniker only if one already exists, force assignment of a moniker, create a temporary moniker, or remove a moniker that has been assigned. In practice, you will usually request that the container force assignment of the moniker. Values defining these choices are contained in the enumeration OLEGETMONIKER.

dwWhichMoniker

[in] DWORD that specifies whether to return the container’s moniker, the object’s moniker relative to the container, or the object’s full moniker. In practice, you will usually request the object’s full moniker. Values defining these choices are contained in the enumeration OLEWHICHMK.

ppmk

[out] Indirect pointer to the IMoniker interface on the moniker for the object’s client site. If an error is returned, this parameter must be set to NULL. Each time a container receives a call to IOleClientSite::GetMoniker, it must increase the reference count on the pointer it returns. It is the caller’s responsibility to call Release when it is done with the pointer.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK

Requested moniker returned successfully.

E_NOTIMPL

This container cannot assign monikers to objects. This is the case with OLE 1 containers.

Remarks

Containers implement IOleClientSite::GetMoniker as a way of passing out monikers for their embedded objects to clients wishing to link to those objects.

When a link is made to an embedded object or to a pseudo-object within it (a range of cells in a spreadsheet, for example), the object needs a moniker to construct the composite moniker indicating the source of the link. If the embedded object does not already have a moniker, it can call IOleClientSite::GetMoniker to request one.

Every container that expects to contain links to embeddings should support IOleClientSite::GetMoniker to give out OLEWHICHMK_CONTAINER, thus enabling link tracking when the link client and link source files move, but maintain the same relative position.

An object must not persistently store its full moniker or its container’s moniker, because these can change while the object is not loaded. For example, either the container or the object could be renamed, in which event, storing the container’s moniker or the object’s full moniker would make it impossible for a client to track a link to the object.

In some very specialized cases, an object may no longer need a moniker previously assigned to it and may wish to have it removed as an optimization. In such cases, the object can call IOleClientSite::GetMoniker with OLEGETMONIKER_UNASSIGN to have the moniker removed.

See Also

IOleObject::GetMoniker, IOleObject::SetMoniker


IOleClientSite::OnShowWindow

Notifies a container when an embedded object’s window is about to become visible or invisible. This method does not apply to an object that is activated in place and therefore has no window separate from that of its container.

HRESULT OnShowWindow(

BOOL fShow	//Value indicating if window is becoming visible
);
Parameter

fShow

[in] Value that indicates whether an object’s window is open (TRUE) or closed (FALSE).

Return Value

S_OK

Shading or hatching has been successfully added or removed.

Remarks

An embedded object calls IOleClientSite::OnShowWindow to keep its container informed when the object is open in a window. This window may or may not be currently visible to the end user. The container uses this information to shade the object’s client site when the object is displayed in a window, and to remove the shading when the object is not. A shaded object, having received this notification, knows that it already has an open window and therefore can respond to being double-clicked by bringing this window quickly to the top, instead of launching its application in order to obtain a new one.


IOleClientSite::RequestNewObjectLayout

Asks container to allocate more or less space for displaying an embedded object.

HRESULT RequestNewObjectLayout();

Return Values

S_OK

Request for new layout succeeded.

E_NOTIMPL

Client site does not support requests for new layout.

Remarks

Currently, there is no standard mechanism by which a container can negotiate how much room an object would like. When such a negotiation is defined, responding to this method will be optional for containers.


IOleClientSite::SaveObject

Saves the object associated with the client site. This function is synchronous; by the time it returns, the save will be completed.

HRESULT SaveObject();

Parameter

HRESULT SaveObject(void)

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The object was saved.

Remarks

An embedded object calls IOleClientSite::SaveObject to ask its container to save it to persistent storage when an end user chooses the File Update or Exit commands. The call is synchronous, meaning that by the time it returns, the save operation will be completed.

Calls to IOleClientSite::SaveObject occur in most implementations of IOleObject::Close. Normally, when a container tells an object to close, the container passes a flag specifying whether the object should save itself before closing, prompt the user for instructions, or close without saving itself. If an object is instructed to save itself, either by its container or an end user, it calls IOleClientSite::SaveObject to ask the container application to save the object’s contents before the object closes itself. If a container instructs an object not to save itself, the object should not call SaveObject.

See Also

IOleObject::Close


IOleClientSite::ShowObject

Tells the container to position the object so it is visible to the user. This method ensures that the container itself is visible and not minimized.

HRESULT ShowObject();

Return Values

S_OK

Container has tried to make the object visible.

OLE_E_NOT_SUPPORTED

Client site is in an OLE 1 container.

Remarks

After a link client binds to a link source, it commonly calls IOleObject::DoVerb on the link source, usually requesting the source to perform some action requiring that it display itself to the user. As part of its implementation of DoVerb, the link source can call IOleClientSite::ShowObject, which forces the client to show the link source as best it can. If the link source’s container is itself an embedded object, it will recursively invoke IOleClientSite::ShowObject on its own container.

Having called the ShowObject method, a link source has no guarantee of being appropriately displayed because its container may not be able to do so at the time of the call. The ShowObject method does not guarantee visibility, only that the container will do the best it can.

See Also

IOleObject::DoVerb


IOleContainer

The IOleContainer interface is used to enumerate objects in a compound document or lock a container in the running state. Container and object applications both implement this interface.

When to Implement

Applications that support links and links to embedded objects implement this interface to provide object enumeration, name parsing, and silent updates of link sources. Simple, nonlinking containers do not need to implement IOleContainer if it is useful mainly to support links to embedded objects.

When to Use

Call IOleContainer to enumerate the objects in a compound document or to lock a container so that silent updates of link sources can be carried out safely.

Many applications inherit the functions of IOleContainer by implementing IOleItemContainer, which is used to bind item monikers.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IParseDisplayName Method	Description
ParseDisplayName	Parses object’s display name to form moniker.
IOleContainer Methods	Description
EnumObjects	Enumerates objects in a container.
LockContainer	Keeps container running until explicitly released.
See Also

IOleItemContainer, IParseDisplayName


IOleContainer::EnumObjects

Enumerates objects in the current container.

HRESULT EnumObjects(

DWORD grfFlags,	//Value specifying what is to be enumerated
IEnumUnknown **ppenum	//Indirect pointer to enumerator object
);
Parameters

grfFlags

[in] Value that specifies which objects in a container are to be enumerated, as defined in the enumeration OLECONTF.

ppenum

[out] When successful, indirect pointer to the IEnumUnknown interface on the enumerator object. Each time a container receives a successful call to EnumObjects, it must increase the reference count on the pointer the method returns. It is the caller’s responsibility to call IUnknown::Release when it is done with the pointer. If an error is returned, this parameter must be set to NULL.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

Enumerator successfully returned.

E_NOTIMPL

Object enumeration not supported.

Remarks

A container should implement EnumObjects to enable programmatic clients to find out what objects it holds. This method, however, is not called in standard linking scenarios.

See Also

IEnumUnknown, IOleItemContainer, OLECONTF


IOleContainer::LockContainer

Keeps an embedded object’s container running.

HRESULT LockContainer(

BOOL fLock	//Value indicating lock or unlock
);
Parameter

fLock

[in] Value that specifies whether to lock (TRUE) or unlock (FALSE) a container.

Return Values

This method supports the standard return values E_FAIL and E_OUTOFMEMORY, as well as the following:

S_OK

Container was locked successfully.

Remarks

An embedded object calls IOleContainer::LockContainer to keep its container running when the object has link clients that require an update. If an end user selects File Close from the container’s menu, however, the container ignores all outstanding LockContainer locks and closes the document anyway.

Notes to Callers

When an embedded object changes from the loaded to the running state, it should call IOleContainer::LockContainer with the fLock parameter set to TRUE. When the embedded object shuts down (transitions from running to loaded), it should call IOleContainer::LockContainer with the fLock parameter set to FALSE.

Each call to LockContainer with fLock set to TRUE must be balanced by a call to LockContainer with fLock set to FALSE. Object applications typically need not call LockContainer; the default handler makes these calls automatically for object applications implemented as .EXEs as the object makes the transition to and from the running state. Object applications not using the default handler, such as DLL object applications, must make the calls directly.

An object should have no strong locks on it when it registers in the Running Object Table, but it should be locked as soon as the first external client connects to it. Therefore, following registration of the object in the Running Object Table, object handlers and DLL object applications, as part of their implementation of IRunnableObject::Run, should call IOleContainer::LockContainer(TRUE) to lock the object.

Notes to Implementers

The container must keep track of whether and how many calls to LockContainer(TRUE) have been made. To increment or decrement the reference count, IOleContainer::LockContainer calls CoLockObjectExternal with a flag set to match fLock.

See Also

CoLockObjectExternal, IRunnableObject::Run


IOleControl

The IOleControl interface provides the features for supporting keyboard mnemonics (GetControlInfo, OnMnemonic), ambient properties (OnAmbientPropertyChange), and events (FreezeEvents) in control objects.

When to Implement

Implement this interface for a control object to communicate with the control’s container, for example, when managing keyboard activity or obtaining the container’s ambient properties.

When to Use

A control container uses this interface to work with keyboard mnemonics, ambient properties, and events of a contained control object.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IOleControl Methods	Description
GetControlInfo	Fills in a CONTROLINFO structure with information about the control’s keyboard behavior.
OnMnemonic	Informs the control that the user has pressed a keystroke that the control specified through GetControlInfo. The control takes whatever action is appropriate for the keystroke.
OnAmbientPropertyChange	Informs an control that one or more of the container’s ambient properties has changed.
FreezeEvents	Indicates whether or not the container ignores or accepts events from the control.
See Also

IOleControlSite, ISimpleFrameSite


IOleControl::FreezeEvents

Indicates whether the container is ignoring or accepting events from the control.

HRESULT FreezeEvents(

BOOL bFreeze	//Indicates whether to ignore or process events
);
Parameters

bFreeze

[out] Indicates whether the container will ignore (TRUE) or now process (FALSE) events from the control.

Return Values

S_OK

Returned in all cases.

Remarks

The control is not required to stop sending events when bFreeze is TRUE. However, the container is not going to process them in this case. If a control depends on the container’s processing -- as with request events that return information from the container -- the control must either discard the event or queue the event to send later when IOleControl::FreezeEvents returns FALSE.

Notes to Implementers

As with IOleControl::OnAmbientPropertyChange, S_OK is returned in all cases in order to prevent a container from making assumptions about a control’s behavior based on return values.


IOleControl::GetControlINfo

Fills in a CONTROLINFO structure with information about a control’s keyboard mnemonics and keyboard behavior.

HRESULT GetControlInfo(

CONTROLINFO* pCI	//Pointer to structure
);
Parameters

pCI

[in, out] Pointer to the caller-allocated CONTROLINFO structure to be filled in.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The structure was filled successfully.

E_NOTIMPL

The control has no mnemonics.

E_POINTER

The address in pCI is not valid. For example, it may be NULL.

See Also

CONTROLINFO


IOleControl::OnAmbientPropertyChange

Informs a control that one or more of the container’s ambient properties (available through the control site’s IDispatch) has changed.

HRESULT OnAmbientPropertyChange(

DISPID dispID	//Dispatch identifier of the ambient property
);
Parameters

dispID

[in] Dispatch identifier of the ambient property that changed. If the dispID parameter is DISPID_UNKNOWN, it indicates that multiple properties changed. In this case, the control should check all the ambient properties of interest to obtain their current values.

Return Values

S_OK

Returned in all cases.

Remarks

Notes to Implementers

S_OK is returned in all cases even when the control does not support ambient properties or some other failure has occurred. The caller sending the notification cannot attempt to use an error code (such as E_NOTIMPL) to determine whether to send the notification in the future. Such semantics are not part of this interface.


IOleControl::OnMnemonic

Informs a control that the user has pressed a keystroke that matches one of the ACCEL entries in the mnemonic table returned through IOleControl::GetControlInfo. The control takes whatever action is appropriate for the keystroke.

HRESULT OnMnemonic(

LPMSG pMsg	//Pointer to structure
);
Parameters

pMsg

[in] Pointer to the MSG structure describing the keystroke to be processed.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The control accepted the mnemonic.

E_NOTIMPL

The control doesn’t handle any mnemonics. This indicates an unexpected condition and a caller error. For example, the caller has mismatched which control has which mnemonic.

Remarks

Notes to Implementers

If a control changes the contents of its CONTROLINFO structure, it must notify its container by calling IOleControlSite::OnControlInfoChanged.

Notes to Callers

A container of a control is allowed to cache the control’s CONTROLINFO structure, provided that the container implements IOleControlSite::OnControlInfoChanged to know when it must update its cached information.

See Also

IOleControl::GetControlInfo, IOleControlSite::OnControlInfoChanged


IOleControlSite

The IOleControlSite interface provides the methods that enable a site object to manage each embedded control within a container. A site object provides IOleControlSite as well as other site interfaces such as IOleClientSite and IOleInPlaceSite. When a control requires the services expressed through this interface, it will query one of the other client site interfaces for IOleControlSite.

When to Implement

Implement this interface on an in-place capable site object to support the embedding of controls in the site.

When to Use

A control uses this interface to work with a control-aware container.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IOleControlSite Methods	Description
OnControlInfoChanged	Informs the container that the control’s CONTROLINFO structure has changed and that the container should call the control’s IOleControl::GetControlInfo for an update.
LockInPlaceActive	Indicates whether or not this control should remain in-place active, regardless of possible deactivation events.
GetExtendedControl	Requests an IDispatch pointer to the extended control that the container uses to wrap the real control.
TransformCoords	Converts between a POINTL structure expressed in HIMETRIC units (as is standard in OLE) and a POINTF structure expressed in units the container specifies.
TranslateAccelerator	Instructs the container to process a specified keystroke.
OnFocus	Indicates whether the embedded control in this control site has gained or lost the focus.
ShowPropertyFrame	Instructs the container to show a property page frame for the control object if the container so desires.
See Also

IOleControl, ISimpleFrameSite


IOleControlSite::GetExtendedControl

Requests an IDispatch pointer to the extended control that the container uses to wrap the real control.

HRESULT GetExtendedControl(

IDispatch** ppDisp	//Indirect pointer to the interface of the extended control
);
Parameters

ppDisp

[out] Indirectly pointer to the extended control’s IDispatch interface. This parameter is set to NULL on failure. On success, the caller is responsible for calling IDispatch::Release when this pointer is no longer needed.

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The extended control’s IDispatch is returned in ppDisp.

E_NOTIMPL

The container does not implement extended controls.

E_POINTER

The address in ppDisp or *ppDisp is not valid. For example, it may be NULL.

Remarks

This method gives the real control access to whatever properties and methods the container maintains in the extended control. These properties and methods would otherwise be inaccessible to the control.

Notes to Callers

The returned pointer is the responsibility of the caller, which must release it when it is no longer needed.


IOleControlSite::LockInPlaceActive

Indicates whether or not a control should remain in-place active. Calls to this method typically nest an event to ensure that the object’s activation state remains stable throughout the processing of the event.

HRESULT LockInPlaceActive(

BOOL fLock	//Indicates whether to ensure the active state
);
Parameters

fLock

[in] Indicates whether to ensure the in-place active state (TRUE) or to allow activation to change (FALSE). When TRUE, a supporting container must not deactivate the in-place object until this method is called again with FALSE.

Return Values

S_OK

The lock or unlock was made successfully.

E_NOTIMPL

The container does not support in-place locking.

Remarks

This method affects the control’s in-place active state but not its UI-active state.


IOleControlSite::OnControlInfoChanged

Informs the container that the control’s CONTROLINFO structure has changed and that the container should call the control’s IOleControl::GetControlInfo for an update.

HRESULT OnControlInfoChanged(void);

Return Values

S_OK

Returned in all cases.

See Also

IOleControl::GetControlInfo


IOleControlSite::OnFocus

Indicates whether the control managed by this control site has gained or lost the focus, according to the fGotFocus parameter. The container uses this information to update the state of Default and Cancel buttons according to how the control with the focus processes Return or Esc keys. A control’s behavior regarding the Return and Esc keys is specified in the control’s CONTROLINFO structure. See IOleControl::GetControlInfo.

HRESULT OnFocus(

BOOL fGotFocus	//Indicates whether the control gained focus
);
Parameters

fGotFocus

[in] Indicates whether the control gained (TRUE) or lost the focus (FALSE).

Return Values

S_OK

Returned in all cases.

See Also

IOleControl::GetControlInfo


IOleControlSite::ShowPropertyFrame

Instructs a container to display a property sheet for the control embedded in this site.

HRESULT ShowPropertyFrame(void);

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The container successfully displayed property pages for this control and the control must not show its own.

E_NOTIMPL

The container does not need to show property pages itself.

Remarks

A control must always call this method in the container first when it intends to show its own property pages. Calling this method gives the container a chance to have those property pages work with the container’s extended controls. The container may include its own property pages as well in such cases, which doesn’t affect the control at all. If the container does not implement this method or if it returns a failure of any kind, the control can show its property pages directly. Otherwise, the container has shown the pages.


IOleControlSite::TransformCoords

Converts between a POINTL structure expressed in HIMETRIC units (as is standard in OLE) and a POINTF structure expressed in units specified by the container. By converting the methods, the control can ensure that it sends coordinate information to the container in units that are directly usable in the container without additional conversion.

HRESULT TransformCoords(

POINTL* pptlHimetric ,	//Indirect pointer to structure
POINTF* pptfContainer ,	//Indirect pointer to structure
DWORD dwFlags	//Flags indicating the exact conversion
);
Parameters

pptlHimetric

[in, out] Indirect pointer to a POINTL structure containing coordinates expressed in HIMETRIC units. This is an [in] parameter when dwFlags contains XFORMCOORDS_HIMETRICTOCONTAINER; it is [out] with XFORMCOORDS_CONTAINERTOHIMETRIC. In the latter case, the contents are undefined on error.

pptfContainer

[in, out] Indirect pointer to a caller-allocated POINTF structure that receives the converted coordinates. This is an [in] parameter when dwFlags contains XFORMCOORDS_CONTAINERTOHIMETRIC; it is [out] with XFORMCOORDS_HIMETRICTOCONTAINER. In the latter case, the contents are undefined on error.

dwFlags

[in] Flags indicating the exact conversion to perform. The dwFlags parameter can be any combination of the following values except where indicated:

Flag Value	Description
XFORMCOORDS_POSITION	The coordinates to convert represent a position point. Cannot be used with XFORMCOORDS_SIZE.
XFORMCOORDS_SIZE	The coordinates to convert represent a set of dimensions. Cannot be used with XFORMCOORDS_POSITION.
XFORMCOORDS_HIMETRICTOCONTAINER	The operation converts pptlHimetric into pptfContainer. Cannot be used with XFORMCOORDS_CONTAINERTOHIMETRIC.
XFORMCOORDS_CONTAINERTOHIMETRIC	The operation converts pptfContainer into pptlHimetric. Cannot be used with XFORMCOORDS_HIMETRICTOCONTAINER.
Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The conversion was performed successfully.

E_NOTIMPL

The container does not require any special coordinate conversions. The container deals completely in HIMETRIC.

E_POINTER

The address in pptlHimetric or pptfContainer is not valid. For example, it may be NULL.

Remarks

A control uses this method when it has to send coordinates to a container within an event or some other custom call or when the control has container coordinates that it needs to convert into HIMETRIC units.

See Also

POINTF


IOleControlSite::TranslateAccelerator

Instructs the control site to process the keystroke described in pMsg and modified by the flags in grfModifiers.

HRESULT TranslateAccelerator(

LPMSG pMsg ,	//Pointer to the structure
DWORD grfModifiers	//Flags describing the state of the keys
);
Parameters

pMsg

[in] Pointer to the MSG structure describing the keystroke to be processed.

grfModifiers

[in] Flags describing the state of the Control, Alt, and Shift keys. The value of the flag can be any valid KEYMODIFIERS enumeration values.

Return Values

S_OK

The container processed the message.

S_FALSE

The container did not process the message. This value must also be returned in all other error cases besides E_NOTIMPL.

E_NOTIMPL

The container does not implement accelerator support.

Remarks

This method is called by a control that can be UI-active. In such cases, a control can process all keystrokes first through IOleInPlaceActiveObject::TranslateAccelerator, according to normal OLE Compound Document rules. Inside that method, the control can give the container certain messages to process first by calling IOleControlSite::TranslateAccelerator and using the return value to determine if any processing took place. Otherwise, the control always processes the message first. If the control does not use the keystroke as an accelerator, it passes the keystroke to the container through this method.

See Also

IOleInPlaceActiveObject::TranslateAccelerator, KEYMODIFIERS


IOleInPlaceActiveObject

The IOleInPlaceActiveObject interface provides a direct channel of communication between an in-place object and the associated application’s outer-most frame window and the document window within the application that contains the embedded object. The communication involves the translation of messages, the state of the frame window (activated or deactivated), and the state of the document window (activated or deactivated). Also, it informs the object when it needs to resize its borders, and manages modeless dialog boxes.

When to Implement

This interface is implemented by object applications in order to provide support for their objects while they are active in-place.

When to Use

These methods are used by the in-place object’s top-level container to manipulate objects while they are active.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleWindow Methods	Description
GetWindow	Gets a window handle.
ContextSensitiveHelp	Controls enabling of context-sensitive help.
IOleInPlaceActiveObject Methods	Description
TranslateAccelerator	Translates messages.
OnFrameWindowActivate	State of container’s top-level frame.
OnDocWindowActivate	State of container document window.
ResizeBorder	Alert object of need to resize border space.
EnableModeless	Enable or disable modeless dialog boxes.
See Also

IOleWindow


IOleInPlaceActiveObject::EnableModeless

Enables or disables modeless dialog boxes when the container creates or destroys a modal dialog box.

HRESULT EnableModeless(

BOOL fEnable	//Enable or disable modeless dialog box windows
);
Parameter

fEnable

[in] TRUE to enable modeless dialog box windows; FALSE to disable them.

Return Value

S_OK

The method completed successfully.

Remarks

Notes to Callers

IOleInPlaceActiveObject::EnableModeless is called by the top-level container to enable and disable modeless dialog boxes that the object displays. For the container to display a modal dialog box, it must first call IOleInPlaceActiveObject::EnableModeless, specifying FALSE to disable the object’s modeless dialog box windows. When the container is through displaying its modal dialog box, it calls IOleInPlaceActiveObject::EnableModeless, specifying TRUE to reenable the object’s modeless dialog boxes.

See Also

IOleInPlaceFrame::EnableModeless


IOleInPlaceActiveObject::OnDocWindowActivate

Notifies the active in-place object when the container’s document window is activated or deactivated.

HRESULT OnDocWindowActivate(

BOOL fActivate	//State of MDI child document window
);
Parameter

fActivate

[in] State of the MDI child document window. It is TRUE if the window is in the act of activating; FALSE if it is in the act of deactivating.

Return Value

S_OK

The method completed successfully.

Remarks

Notes to Callers

Call IOleInPlaceActiveObject::OnDocWindowActivate when the MDI child document window is activated or deactivated and the object is currently the active object for the document.

Notes to Implementers

You should include code in this method that installs frame-level tools during object activation. These tools include the shared composite menu and/or optional toolbars and frame adornments. You should then take focus. When deactivating, the object should remove the frame-level tools. Note that if you do not call IOleInPlaceUIWindow::SetBorderSpace with pborderwidths set to NULL, you can avoid having to renegotiate border space.

Note  While executing IOleInPlaceActiveObject::OnDocWindowActivate, do not make calls to the Windows PeekMessage or GetMessage functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface methods and functions can be called from within OnDocWindowActivate.

See Also

PeekMessage, GetMessage in Win32


IOleInPlaceActiveObject::OnFrameWindowActivate

Notifies the object when the container’s top-level frame window is activated or deactivated.

HRESULT OnFrameWindowActivate(

BOOL fActivate	//State of container’s top-level window
);
Parameter

fActivate

[in] State of the container’s top-level frame window. TRUE if the window is activating; FALSE if it is deactivating.

Return Value

S_OK

The method notified the object successfully.

Remarks

Notes to Callers

The container must call IOleInPlaceActiveObject::OnFrameWindowActivate when the container’s top-level frame window is either being activated or deactivated and the object is the current, active object for the frame.

Note  While executing IOleInPlaceActiveObject::OnFrameWindowActivate, do not make calls to the Windows PeekMessage or GetMessage functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface methods and functions can be called from within OnFrameWindowActivate.

See Also

PeekMessage, GetMessage in Win32


IOleInPlaceActiveObject::ResizeBorder

Alerts the object that it needs to resize its border space.

HRESULT ResizeBorder(

LPCRECT prcBorder,	//Pointer to new outer rectangle for border space
IOleInPlaceUIWindow pUIWindow,	//Pointer to frame or document window border change
BOOL fFrameWindow	//Indicates whether frame window object calls ResizeBorder
);
Parameters

prcBorder

[in] Pointer to a RECT structure containing the new outer rectangle within which the object can request border space for its tools.

pUIWindow

[in] Pointer to the frame or document window object whose border has changed.

fFrameWindow

[in] TRUE if the frame window object is calling ResizeBorder; otherwise, FALSE.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The method alerted the object successfully.

Remarks

Notes to Callers

IOleInPlaceActiveObject::ResizeBorder is called by the top-level container’s document or frame window object when the border space allocated to the object should change. Because the active in-place object is not informed about which window has changed (the frame- or document-level window), IOleInPlaceActiveObject::ResizeBorder must be passed the pointer to the window’s IOleInPlaceUIWindow interface.

Notes to Implementers

In most cases, resizing only requires that you grow, shrink, or scale your object’s frame adornments. However, for more complicated adornments, you may be required to renegotiate for border space with calls to IOleInPlaceUIWindow::RequestBorderSpace and IOleInPlaceUIWindow::SetBorderSpace.

Note  While executing IOleInPlaceActiveObject::ResizeBorder, do not make calls to the Windows PeekMessage or GetMessage functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface methods and functions can be called from within ResizeBorder.

See Also

IOleInPlaceUIWindow::GetBorder

PeekMessage, GetMessage in Win32


IOleInPlaceActiveObject::TranslateAccelerator

Processes menu accelerator-key messages from the container’s message queue. This method should only be used for objects created by a DLL object application.

HRESULT TranslateAccelerator(

LPMSG lpmsg	//Pointer to message that may need translating
);
Parameter

lpmsg

[in] Pointer to the message that might need to be translated.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The message was translated successfully.

S_FALSE

The message was not translated.

Remarks

Notes to Callers

Active in-place objects must always be given the first chance at translating accelerator keystrokes. You can provide this opportunity by calling IOleInPlaceActiveObject::TranslateAccelerator from your container’s message loop before doing any other translation. You should apply your own translation only when this method returns S_FALSE.

If you call IOleInPlaceActiveObject::TranslateAccelerator for an object that is not created by a DLL object application, the default object handler returns S_FALSE.

Notes to Implementers

An object created by an EXE object application gets keystrokes from its own message pump, so the container does not get those messages.

If you need to implement this method, you can do so by simply wrapping the call to the Window’s TranslateAccelerator function.

See Also

OleTranslateAccelerator

TranslateAccelerator in Win32


IOleInPlaceFrame

The IOleInPlaceFrame interface controls the container’s top-level frame window. This control involves allowing the container to insert its menu group into the composite menu, install the composite menu into the appropriate window frame, and remove the container’s menu elements from the composite menu. It sets and displays status text relevant to the in-place object. It also enables or disables the frame’s modeless dialog boxes, and translates accelerator keystrokes intended for the container’s frame.

When to Implement

You will need to implement this interface if you are writing a container application that will be participating in in-place activation.

When to Use

This interface is used by object applications to control the display and placement of composite menus, keystroke accelerator translation, context-sensitive help mode, and modeless dialog boxes.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleWindow Methods	Description
GetWindow	Gets a window handle.
ContextSensitiveHelp	Controls enabling of context-sensitive help.
IOleInPlaceUIWindow Methods	Description
GetBorder	Translates messages.
RequestBorderSpace	State of container’s top-level frame.
SetBorderSpace	State of container document window.
SetActiveObject	Alert object of need to resize border space.
IOleInPlaceFrame Methods	Description
InsertMenus	Allows container to insert menus.
SetMenu	Adds a composite menu to window frame.
RemoveMenus	Removes a container’s menu elements.
SetStatusText	Sets and displays status text about.
EnableModeless	Enables or disables modeless dialog boxes.
TranslateAccelerator	Translates keystrokes.
See Also

IOleWindow, IOleInPlaceUIWindow


IOleInPlaceFrame::EnableModeless

Enables or disables a frame’s modeless dialog boxes.

HRESULT EnableModeless(

BOOL fEnable	//Enable or disable modeless dialog box windows
);
Parameter

fEnable

[in] Specifies whether the modeless dialog box windows are to be enabled by specifying TRUE or disabled by specifying FALSE.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The dialog box was either enabled or disabled successfully, depending on the value for fEnable.

Remarks

Notes to Callers

The active in-place object calls IOleInPlaceFrame::EnableModeless to enable or disable modeless dialog boxes that the container might be displaying. To display a modal dialog box, the object first calls IOleInPlaceFrame::EnableModeless, specifying FALSE to disable the container’s modeless dialog box windows. After completion, the object calls IOleInPlaceFrame::EnableModeless, specifying TRUE to reenable them.

Notes to Implementers

You should track the value of EnableModeless and check it before displaying a dialog box.

See Also

IOleInPlaceActiveObject::EnableModeless


IOleInPlaceFrame::InsertMenus

Allows the container to insert its menu groups into the composite menu to be used during the in-place session.

HRESULT InsertMenus(

HMENU hmenuShared,	//Handle to empty menu
LPOLEMENUGROUPWIDTHS lpMenuWidths	//Pointer to array
);
Parameters

hmenuShared

[in] Handle to an empty menu.

lpMenuWidths

[in, out] Pointer to an OLEMENUGROUPWIDTHS array of six LONG values. The container fills in elements 0, 2, and 4 to reflect the number of menu elements it provided in the File, View, and Window menu groups.

Return Values

S_OK

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The menu groups were inserted successfully.

Remarks

Notes to Callers

This method is called by object applications when they are first being activated. They call it in order to insert their menus into the frame-level user interface.

The object application asks the container to add its menus to the menu specified in hmenuShared and to set the group counts in the OLEMENUGROUPWIDTHS array pointed to by lpMenuWidths. The object application then adds its own menus and counts. Objects can call IOleInPlaceFrame::InsertMenus as many times as necessary to build up the composite menus. The container should use the initial menu handle associated with the composite menu for all menu items in the drop-down menus.


IOleInPlaceFrame::RemoveMenus

Gives the container a chance to remove its menu elements from the in-place composite menu.

HRESULT RemoveMenus(

HMENU hmenuShared	//Handle to in-place composite menu
);
Parameter

hmenuShared

[in] Handle to the in-place composite menu that was constructed by calls to IOleInPlaceFrame::InsertMenus and the Windows InsertMenu function.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTEDs, as well as the following:

S_OK

The method completed successfully.

Remarks

The object should always give the container a chance to remove its menu elements from the composite menu before deactivating the shared user interface.

Notes to Callers

Called by the object application while it is being UI-deactivated in order to remove its menus.

See Also

IOleInPlaceFrame::SetMenu

InsertMenu in Win32


IOleInPlaceFrame::SetMenu

Installs the composite menu in the window frame containing the object being activated in place.

HRESULT SetMenu(

HMENU hmenuShared,	//Handle to composite menu
HOLEMENU holemenu,	//Handle to menu descriptor
HWND hwndActiveObject	//Handle to object’s window
);
Parameters

hmenuShared

[in] Handle to the composite menu constructed by calls to IOleInPlaceFrame::InsertMenus and the Windows InsertMenu function.

holemenu

[in] Handle to the menu descriptor returned by the OleCreateMenuDescriptor function.

hwndActiveObject

[in] Handle to a window owned by the object and to which menu messages, commands, and accelerators are to be sent.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The method completed successfully.

Remarks

Notes to Callers

The object calls IOleInPlaceFrame::SetMenu to ask the container to install the composite menu structure set up by calls to IOleInPlaceFrame::InsertMenus.

Notes to Implementers

An SDI container’s implementation of this method should call the Windows SetMenu function. An MDI container should send a WM_MDISETMENU message, using hmenuShared as the menu to install. The container should call OleSetMenuDescriptor to install the OLE dispatching code.

When deactivating, the container must call IOleInPlaceFrame::SetMenu, specifying NULL to remove the shared menu. This is done to help minimize window repaints. The container should also call OleSetMenuDescriptor, specifying NULL to unhook the dispatching code. Finally, the object application calls OleDestroyMenuDescriptor to free the data structure.

Note  While executing IOleInPlaceFrame::SetMenu, do not make calls to the Windows PeekMessage or GetMessage functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface methods and functions can be called from within SetMenu.

See Also

IOleInPlaceFrame::InsertMenus, OleSetMenuDescriptor, OleDestroyMenuDescriptor

PeekMessage, GetMessage in Win32


IOleInPlaceFrame::SetStatusText

Sets and displays status text about the in-place object in the container’s frame window status line.

HRESULT SetStatusText(

LPCOLESTR pszStatusText	//Pointer to message to display
);
Parameter

pszStatusText

[in] Pointer to a null-terminated character string containing the message to display.

Return Values

This method supports the standard return values E_FAIL, E_INVALIDARG, and E_UNEXPECTED, as well as the following:

S_OK

The text was displayed.

S_TRUNCATED

Some text was displayed but the message was too long and was truncated.

Remarks

Notes to Callers

You should call SetStatusText when you need to ask the container to display object text in its frame’s status line, if it has one. Because the container’s frame window owns the status line, calling IOleInPlaceFrame::SetStatusText is the only way an object can display status information in the container’s frame window. If the container refuses the object’s request, the object application can, however, negotiate for border space to display its own status window.

Note  When switching between menus owned by the container and the in-place active object, the status bar text is not reflected properly if the object does not call the container’s IOleInPlaceFrame::SetStatusText method. For example, if, during an in-place session, the user were to select the File menu, the status bar would reflect the action that would occur if the user selected this menu. If the user then selects the Edit menu (which is owned by the in-place object), the status bar text would not change unless the IOleInPlaceFrame::SetStatusText happened to be called. This is because there is no way for the container to recognize that one of the object’s menus has been made active because all the messages that the container would trap are now going to the object.

Notes to Implementers

To avoid potential problems, all objects being activated in place should process the WM_MENUSELECT message and call IOleInPlaceFrame::SetStatusText — even if the object does not usually provide status information (in which case the object can just pass a NULL string for the requested status text).

Note  While executing IOleInPlaceFrame::SetStatusText, do not make calls to the Windows PeekMessage or GetMessage functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface methods and functions can be called from within GetBorder.

See Also

PeekMessage, GetMessage in Win32


IOleInPlaceFrame::TranslateAccelerator

Translates accelerator keystrokes intended for the container’s frame while an object is active in place.

HRESULT TranslateAccelerator(

LPMSG lpmsg,	//Pointer to structure
WORD wID	//Command identifier value
);
Parameters

lpmsg

[in] Pointer to the MSG structure containing the keystroke message.

wID

[in] Command identifier value corresponding to the keystroke in the container-provided accelerator table. Containers should use this value instead of translating again.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The keystroke was used.

S_FALSE

The keystroke was not used.

Remarks

Notes to Callers

The IOleInPlaceFrame::TranslateAccelerator method is called indirectly by OleTranslateAccelerator when a keystroke accelerator intended for the container (frame) is received.

Notes to Implementers

The container application should perform its usual accelerator processing, or use wID directly, and then return, indicating whether the keystroke accelerator was processed. If the container is an MDI application and the Windows TranslateAccelerator call fails, the container can call the Windows TranslateMDISysAccel function, just as it does for its usual message processing.

In-place objects should be given first chance at translating accelerator messages. However, because objects implemented by DLL object applications do not have their own message pump, they receive their messages from the container’s message queue. To ensure that the object has first chance at translating messages, a container should always call IOleInPlaceActiveObject::TranslateAccelerator before doing its own accelerator translation. Conversely, an executable object application should call OleTranslateAccelerator after calling TranslateAccelerator, calling TranslateMessage and DispatchMessage only if both translation functions fail.

Note  You should define accelerator tables for containers so they will work properly with object applications that do their own accelerator keystroke translations. Tables should be defined as follows:

"char", wID, VIRTKEY, CONTROL

This is the most common way to describe keyboard accelerators. Failure to do so can result in keystrokes being lost or sent to the wrong object during an in-place session.

See Also

OleTranslateAccelerator, IOleInPlaceActiveObject::TranslateAccelerator

TranslateAccelerator, TranslateMessage, DispatchMessage, TranslateMDISysAccel in Win32


IOleInPlaceObject

The IOleInPlaceObject interface manages the activation and deactivation of in-place objects, and determines how much of the in-place object should be visible.

You can obtain a pointer to IOleInPlaceObject by calling QueryInterface on IOleObject.

When to Implement

You must implement this interface if you are writing an object application that will participate in in-place activation.

When to Use

Used by an object’s immediate container to activate or deactivate the object.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleWindow Methods	Description
GetWindow	Gets a window handle.
ContextSensitiveHelp	Controls enabling of context sensitive help.
IOleInPlaceObject Methods	Description
InPlaceDeactivate	Deactivate active in-place object.
UIDeactivate	Deactivate and remove UI of active object.
SetObjectRects	Portion of in-place object to be visible.
ReactivateAndUndo	Reactivate previously deactivated object.
See Also

IOleObject, IOleWindow


IOleInPlaceObject::InPlaceDeactivate

Deactivates an active in-place object and discards the object’s undo state.

HRESULT InPlaceDeactivate();

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The object was successfully deactivated.

Remarks

Notes to Callers

This method is called by an active object’s immediate container to deactivate the active object and discard its undo state.

Notes to Implementers

On return from IOleInPlaceObject::InPlaceDeactivate, the object discards its undo state. The object application should not shut down immediately after this call. Instead, it should wait for an explicit call to IOleObject::Close or for the object’s reference count to reach zero.

Before deactivating, the object application should give the container a chance to put its user interface back on the frame window by calling IOleInPlaceSite::OnUIDeactivate.

If the in-place user interface is still visible during the call to InPlaceDeactivate, the object application should call its own IOleInPlaceObject::UIDeactivate method to hide the user interface. The in-place user interface can be optionally destroyed during calls to IOleInPlaceObject::UIDeactivate and IOleInPlaceObject::InPlaceDeactivate. But if the user interface has not already been destroyed when the container calls IOleObject::Close, then it must be destroyed during the call to IOleObject::Close.

During the call to IOleObject::Close, the object should check to see whether it is still active in place. If so, it should call InPlaceDeactivate.

See Also

IOleInPlaceSite::OnInPlaceDeactivate, IOleInPlaceSite::OnUIDeactivate, IOleObject::Close


IOleInPlaceObject::ReactivateAndUndo

Reactivates a previously deactivated object, undoing the last state of the object.

HRESULT ReactivateAndUndo();

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The object was successfully reactivated.

E_NOTUNDOABLE

Called when the Undo state is not available.

Remarks

If the user chooses the Undo command before the Undo state of the object is lost, the object’s immediate container calls IOleInPlaceObject::ReactivateAndUndo to activate the user interface, carry out the Undo operation, and return the object to the active state.


IOleInPlaceObject::SetObjectRects

Indicates how much of the in-place object is visible.

HRESULT SetObjectRects(

LPCRECT lprcPosRect,	//Pointer to the position of the in-place object
LPCRECT lprcClipRect	//Pointer to the outer rectangle containing the in-place object’s position rectangle
);
Parameters

lprcPosRect

[in] Pointer to the rectangle containing the position of the in-place object using the client coordinates of its parent window.

lprcClipRect

[in] Pointer to the outer rectangle containing the in-place object’s position rectangle (PosRect). This rectangle is relative to the client area of the object’s parent window.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The operation successfully indicated the rectangle.

Remarks

It is possible for lprcClipRect to change without lprcPosRect changing.

The size of an in-place object’s rectangle is always calculated in pixels. This is different from other OLE object’s visualizations, which are in HIMETRIC.

Note  While executing IOleInPlaceObject::SetObjectRects, do not make calls to the Windows PeekMessage or GetMessage functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface methods and functions can be called from within SetObjectRects.

Notes to Callers

The container should call IOleInPlaceObject::SetObjectRects whenever the window position of the in-place object and/or the visible part of the in-place object changes.

Notes to Implementers

The object must size its in-place window to match the intersection of lprcPosRect and lprcClipRect. The object must also draw its contents into the object’s in-place window so that proper clipping takes place.

The object should compare its width and height with those provided by its container (conveyed through lprcPosRect). If the comparison does not result in a match, the container is applying scaling to the object. The object must then decide whether it should continue the in-place editing in the scale/zoom mode or deactivate.

See Also

IOleInPlaceSite::OnPosRectChange

PeekMessage, GetMessage in Win32


IOleInPlaceObject::UIDeactivate

Deactivates and removes the user interface that supports in-place activation.

HRESULT UIDeactivate();

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The in-place UI was deactivated and removed.

Notes to Callers

This method is called by the object’s immediate container when, for example, the user has clicked in the client area outside the object.

If the container has called IOleInPlaceObject::UIDeactivate, it should later call IOleInPlaceObject::InPlaceDeactivate to properly clean up resources. The container can assume that stopping or releasing the object cleans up resources if necessary. The object must be prepared to do so if IOleInPlaceObject::InPlaceDeactivate has not been called. but either IOleInPlaceObject::UIDeactivate or IOleObject::Close has been called.

Notes to Implementers

Resources such as menus and windows can be either cleaned up or kept in a hidden state until your object is completely deactivated by calls to either IOleInPlaceObject::InPlaceDeactivate or IOleObject::Close. The object application must call IOleInPlaceSite::OnUIDeactivate before doing anything with the composite menus so that the container can first be detached from the frame window. On deactivating the in-place object’s user interface, the object is left in a ready state so it can be quickly reactivated. The object stays in this state until the undo state of the document changes. The container should then call IOleInPlaceObject::InPlaceDeactivate to tell the object to discard its undo state.

See Also

IOleInPlaceObject::InPlaceDeactivate, IOleInPlaceSite::OnUIDeactivate, IOleInPlaceObject::ReactivateAndUndo, IOleObject::Close


IOleInPlaceObjectWindowless

The IOleInPlaceObjectWindowless interface enables a windowless object to process window messages and participate in drag and drop operations. It is derived from and extends the IOleInPlaceObject interface.

A small object, such as a control, does not need a window of its own. Instead, it can rely on its container to dispatch window messages and help the object to participate in drag and drop operations. The container must implement the IOleInPlaceSiteWindowless interface. Otherwise, the object must act as a normal compound document object and create a window when it is activated.

When to Implement

Implement this interface on an object that can be in place activated without a window. This interface is derived from IOleInPlaceObject which, in turn, is derived from IOleWindow.

When to Use

A container calls the methods in this interface to dispatch window messages to an in-place-active windowless object and to assist the object in participating in drag and drop operations. The container must implement a site object with the IOleInPlaceSiteWindowless interface to support these activities. See the IOleInPlaceSiteWindowless interface for more information on operations involving windowless objects, such as drawing, drag and drop, and processing window messages.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleWindow Methods	Description
GetWindow	Gets a window handle.
ContextSensitiveHelp	Controls enabling of context sensitive help.
IOleInPlaceObject Methods	Description
InPlaceDeactivate	Deactivate active in-place object.
UIDeactivate	Deactivate and remove UI of active object.
SetObjectRects	Portion of in-place object to be visible.
ReactivateAndUndo	Reactivate previously deactivated object.
IOleInPlaceObjectWindowless Methods	Description
OnWindowMessage	Dispatches a message from the container to a windowless object.
GetDropTarget	Supplies the IDropTarget interface for a windowless object that supports drag and drop.
See Also

IOleInPlaceSiteWindowless


IOleInPlaceObjectWindowless::GetDropTarget

Supplies the IDropTarget interface for an in-place active, windowless object that supports drag and drop.

HRESULT GetDropTarget(

IDropTarget** ppDropTarget	//Indirect pointer to the IDropTarget interface
);
Parameters

ppDropTarget

[out] Indirect pointer to the windowless object’s IDropTarget interface.

Return Values

S_OK

The IDropTarget interface was successfully returned.

E_NOTIMPL

The windowless object does not support drag and drop.

Remarks

A windowed object registers its IDropTarget interface by calling the RegisterDragDrop function and supplying its window handle as a parameter. Registering its IDropTarget interface enables the object to participate in drag and drop operations. Because it does not have a window when active, a windowless object cannot register its IDropTarget interface. Therefore, it cannot directly participate in drag and drop operations without support from its container.

The following events occur during a drag and drop operation involving windowless objects:

•	The container registers its own IDropTarget interface through the RegisterDragDrop function.

•	In the container’s implementation of its own IDropTarget::DragEnter or IDropTarget::DragOver methods, the container detects whether the mouse pointer just entered an embedded object.

•	If the object is inactive, the container calls the object’s IPointerInactive::GetActivationPolicy method. The object returns the POINTERINACTIVE_ACTIVATEONDRAG flag. The container then activates the object in place. If the object was already active, the container does not have to do this step.

•	Once the object is active, the container must then obtain the object’s IDropTarget interface.

•	A windowless object that wishes to be a drop target still implements the IDropTarget interface, but does not register it and does not return it through calls to QueryInterface. Instead, the container can obtain this interface by calling the object’s IOleInPlaceObjectWindowless::GetDropTarget method. The object returns a pointer to its own IDropTarget interface if it wants to participate in drag and drop operations. The container can cache this interface pointer for later use. For example, on subsequent calls to the container’s IDropTarget::DragEnter or IDropTarget::DragLeave methods, the container can use the cached pointer instead of calling the object’s GetDropTarget method again.

•	The container then calls the object’s IDropTarget::DragEnter and passes the returned value for *pdwEffect from its own DragOver or DragEnter methods. From this point on, the container forwards all subsequent DragOver calls to the windowless object until the mouse leaves the object or a drop occurs on the object. If the mouse leaves the object, the container calls the object’s IDropTarget::DragLeave and then releases the object’s IDropTarget interface. If the drop occurs, the container forwards the IDropTarget::DragDrop call to the object.

•	Finally, the container in-place deactivates the object.

An object can return S_FALSE from its own IDropTarget::DragEnter to indicate that it does not accept any of the data formats in the data object. In that case, the container can decide to accept the data for itself and return an appropriate dwEffect from its own DragEnter or DragOver methods. Note that an object that returns S_FALSE from DragEnter should be prepared to receive subsequent calls to DragEnter without any DragLeave in between. Indeed, if the mouse is still over the same object during the next call to the container’s DragOver, the container may decide to try and call DragEnter again on the object.

Note to Callers

A container can cache the pointer to the object’s IDropTarget interface for later use.

See Also

IDropTarget, IPointerInactive::GetActivationPolicy, RegisterDragDrop


IOleInPlaceObjectWindowless::OnWindowMessage

Dispatches a message from a container to a windowless object that is in-place active.

HRESULT OnWindowMessage(

UINT msg,	//Message Identifier as provided by Windows
WPARAM wParam,	//Message parameter as provided by Windows
LPARAM lParam,	//Message parameter as provided by Windows
LRESULT* plResult	//Pointer to message result code
);
Parameters

msg

[in] Identifier for the window message provided to the container by Windows.

wParam

[in] Parameter for the window message provided to the container by Windows.

lParam

[in] Parameter for the window message provided to the container by Windows.

plResult

[out] Pointer to result code for the window message as defined in the Windows API.

Return Values

S_OK

The window message was successfully dispatched to the windowless object.

S_FALSE

The windowless object did not process the window message. The container should call the DefWindowProc for the message or process the message itself as described below.

Remarks

A container calls this method to send window messages to a windowless object that is in-place active. The container should dispatch messages according to the following guidelines:

•	For the following messages, the container should first dispatch the message to the windowless object that has captured the mouse, if any. Otherwise, the container should dispatch the message to the windowless object under the mouse cursor. If there is no such object, the container is free to process the message for itself.

WM_MOUSEMOVE
WM_SETCURSOR
WM_XBUTTONDOWN
WM_XBUTTONUP
WM_XBUTTONDBLCLK
•	For the following messages, the container should dispatch the message to the windowless object with the keyboard focus.

WM_KEYDOWN	WM_SYSKEYUP
WM_KEYUP	WM_SYSDEADCHAR
WM_CHAR	WM_IMExxx
WM_DEADCHAR	WM_HELP
WM_SYSKEYDOWN	WM_CANCELMODE
•	For all other messages, the container should process the message on its own.

The windowless object can return S_FALSE to this method to indicate that it did not process the message. Then, the container either performs the default behavior for the message by calling the Windows API function DefWindowProc, or processes the message itself.

The container must pass the following window messages to the default window procedure:

WM_MOUSEMOVE	WM_DEADCHAR
WM_XBUTTONxxx	WM_SYSKEYUP
WM_KEYDOWN	WM_SYSCHAR
WM_KEYUP	WM_SYSDEADCHAR
WM_CHAR	WM_IMExxx
The container must process the following window messages as its own:

WM_SETCURSOR
WM_CONTEXTMENU
WM_HELP
Note  For WM_SETCURSOR, the container can either set the cursor itself or do nothing.

Objects can also use IOleInPlaceSiteWindowless::OnDefWindowMessage to explicitly invoke the default message processing from the container. In the case of the WM_SETCURSOR message, this allows an object to take action if the container does not set the cursor.

All coordinates passed to the object in wParam and lParam are specified as client coordinates of the containing window.

See Also

IOleInPlaceSiteWindowless::SetCapture, IOleInPlaceSiteWindowless::OnDefWindowMessage


IOleInPlaceSite

The IOleInPlaceSite interface manages interaction between the container and the object’s in-place client site. Recall that the client site is the display site for embedded objects, and provides position and conceptual information about the object.

This interface provides methods that manage in-place objects. With IOleInPlaceSite, you can determine if an object can be activated and manage its activation and deactivation. You can notify the container when one of its objects is being activated and inform the container that a composite menu will replace the container’s regular menu. It provides methods that make it possible for the in-place object to retrieve the window object hierarchy, and the position in the parent window where the object should place its in-place activation window. Finally, it determines how the container scrolls the object, manages the object undo state, and notifies the object when its borders have changed.

When to Implement

You must implement this interface if you are writing a container application that will participate in in-place activation.

When to Use

Use this interface to allow your object to control in-place activation from within the container.

The IOleInPlaceSite interface pointer is obtained by calling QueryInterface on the object’s IOleClientSite interface.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleWindow Methods	Description
GetWindow	Gets a window handle.
ContextSensitiveHelp	Controls enabling of context-sensitive help.
IOleInPlaceSite Methods	Description
CanInPlaceActivate	Determines if the container can activate the object in place.
OnInPlaceActivate	Notifies the container that one of its objects is being activated in place.
OnUIActivate	Notifies the container that the object is about to be activated in place, and that the main menu will be replaced by a composite menu.
GetWindowContext	Enables an in-place object to retrieve window interfaces that form at the window object hierarchy, and the position in the parent window to locate the object’s in-place activation window.
Scroll	Specifies the number of pixels by which the container is to scroll the object.
OnUIDeactivate	Notifies the container to reinstall its user interface and take focus.
OnInPlaceDeactivate	Notifies the container that the object is no longer active in place.
DiscardUndoState	Instructs the container to discard its undo state.
DeactivateAndUndo	Deactivate the object and revert to undo state.
OnPosRectChange	Object’s extents have changed.
See Also

IOleWindow, IOleClientSite


IOleInPlaceSite::CanInPlaceActivate

Determines whether or not the container can activate the object in place.

HRESULT CanInPlaceActivate();

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The container allows in-place activation for this object.

S_FALSE

The container does not allow in-place activation for this object.

Remarks

Only objects being displayed as DVASPECT_CONTENT can be activated in place.

Notes to Callers

IOleInPlaceSite::CanInPlaceActivate is called by the client site’s immediate child object when this object must activate in place. This function allows the container application to accept or refuse the activation request.


IOleInPlaceSite::DeactivateAndUndo

Causes the container to end the in-place session, deactivate the object, and revert to its own saved undo state.

HRESULT IOleInPlaceSite::DeactivateAndUndo();

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The method completed successfully.

Remarks

Notes to Callers

Called by the active object when the user invokes undo just after activating the object.

Notes to Implementers

Upon completion of this call, the container should call IOleInPlaceObject::UIDeactivate to remove the user interface for the object, activate itself, and undo.


IOleInPlaceSite::DiscardUndoState

Tells the container that the object no longer has any undo state and that the container should not call IOleInPlaceObject::ReActivateAndUndo.

HRESULT IOleInPlaceSite::DiscardUndoState();

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The method completed successfully.

Remarks

If an object is activated in place and the object’s associated object application maintains only one level of undo, there is no need to have more than one entry on the undo stack. That is, once a change has been made to the active object that invalidates its undo state saved by the container, there is no need to maintain this undo state in the container.

Notes to Callers

IOleInPlaceSite::DiscardUndoState is called by the active object while performing some action that would discard the undo state of the object. The in-place object calls this method to notify the container to discard the object’s last saved undo state.

See Also

IOleInPlaceSite::DeactivateAndUndo


IOleInPlaceSite::GetWindowContext

Enables the in-place object to retrieve the window interfaces that form the window object hierarchy, and the position in the parent window where the object’s in-place activation window should be placed.

HRESULT GetWindowContext(

IOleInPlaceFrame **ppFrame,	//Indirect pointer to location of frame interface
IOleInPlaceUIWindow **ppDoc,	//Indirect pointer to location of document window interface
LPRECT lprcPosRect,	//Points to position of in-place object
LPRECT lprcClipRect,	//Points to in-place object’s position rectangle
LPOLEINPLACEFRAMEINFO lpFrameInfo	//Points to structure
);
Parameters

ppFrame

[out] Indirect pointer to where the IOleInPlaceFrame interface on the frame is to be returned. If an error is returned, this parameter must be set to NULL.

ppDoc

[out] Indirect pointer to where the IOleInPlaceUIWindow interface on the document window is to be returned. NULL is returned through the ppDoc pointer if the document window is the same as the frame window. In this case, the object can only use ppFrame or border negotiation. If an error is returned, this parameter must be set to NULL.

lprcPosRect

[out] Pointer to the rectangle containing the position of the in-place object in the client coordinates of its parent window. If an error is returned, this parameter must be set to NULL.

lprcClipRect

[out] Pointer to the outer rectangle containing the in-place object’s position rectangle (PosRect). This rectangle is relative to the client area of the object’s parent window. If an error is returned, this parameter must be set to NULL.

lpFrameInfo

[out] Pointer to an OLEINPLACEFRAMEINFO structure the container is to fill in with appropriate data. If an error is returned, this parameter must be set to NULL.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The method completed successfully.

Remarks

The OLEINPLACEFRAMEINFO structure provides data needed by OLE to dispatch keystroke accelerators to a container frame while an object is active in place.

When an object is activated, it calls GetWindowContext from its container. The container returns the handle to its in-place accelerator table through the OLEINPLACEFRAMEINFO structure. Before calling GetWindowContext, the object must provide the size of the OLEINPLACEFRAMEINFO structure by filling in the cb member, pointed to by lpFrameInfo.


IOleInPlaceSite::OnInPlaceActivate

Notifies the container that one of its objects is being activated in place.

HRESULT OnInPlaceActivate();

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The container allows the in-place activation.

Remarks

Notes to Callers

IOleInPlaceSite::OnInPlaceActivate is called by the active embedded object when it is activated in-place for the first time. The container should note that the object is becoming active.

Notes to Implementers

A container that supports linking to embedded objects must properly manage the running of its in-place objects when they are UI-inactive and running in the hidden state. To reactivate the in-place object quickly, a container should not call IOleObject::Close until the container’s IOleInPlaceSite::DeactivateAndUndo method is called. To safeguard against the object being left in an unstable state if a linking client updates silently, the container should call OleLockRunning to lock the object in the running state. This prevents the hidden in-place object from shutting down before it can be saved in its container.


IOleInPlaceSite::OnInPlaceDeactivate

Notifies the container that the object is no longer active in place.

HRESULT OnInPlaceDeactivate();

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The method successfully notified the container.

Remarks

Notes to Callers

IOleInPlaceSite::OnInPlaceDeactivate is called by an in-place object when it is fully deactivated. This function notifies the container that the object has been deactivated, and it gives the container a chance to run code pertinent to the object’s deactivation. In particular, IOleInPlaceSite::OnInPlaceDeactivate is called as a result of IOleInPlaceObject::InPlaceDeactivate being called. Calling IOleInPlaceSite::OnInPlaceDeactivate indicates that the object can no longer support Undo.

Notes to Implementers

If the container is holding pointers to the IOleInPlaceObject and IOleInPlaceActiveObject interface implementations, it should release them after the IOleInPlaceSite::OnInPlaceDeactivate call.

See Also

IOleInPlaceObject::InPlaceDeactivate


IOleInPlaceSite::OnPosRectChange

Indicates the object’s extents have changed.

HRESULT OnPosRectChange(

LPCRECT lprcPosRect	//Pointer to rectangle containing the position of in-place object
);
Parameter

lprcPosRect

[in] Pointer to the rectangle containing the position of the in-place object in the client coordinates of its parent window.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The method completed successfully.

Remarks

Notes to Callers

The IOleInPlaceSite::OnPosRectChange method is called by the in-place object.

Notes to Implementers

When the in-place object calls IOleInPlaceSite::OnPosRectChange, the container must call IOleInPlaceObject::SetObjectRects to specify the new position of the in-place window and the ClipRect. Only then does the object resize its window.

In most cases, the object grows to the right and/or down. There could be cases where the object grows to the left and/or up, as conveyed through lprcPosRect. It is also possible to change the object’s position without changing its size.

See Also

IOleInPlaceObject::SetObjectRects


IOleInPlaceSite::OnUIActivate

Notifies the container that the object is about to be activated in place and that the object is going to replace the container’s main menu with an in-place composite menu.

HRESULT IOleInPlaceSite::OnUIActivate();

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The container allows the in-place activation.

Remarks

Notes to Callers

The in-place object calls IOleInPlaceSite::OnUIActivate just before activating its user interface.

Notes to Implementers

The container should remove any user interface associated with its own activation. If the container is itself an embedded object, it should remove its document-level user interface.

If there is already an object active in place in the same document, the container should call IOleInPlaceObject::UIDeactivate before calling OnUIDeactivate.

See Also

IOleInPlaceObject::UIDeactivate


IOleInPlaceSite::OnUIDeactivate

Notifies the container on deactivation that it should reinstall its user interface and take focus, and whether or not the object has an undoable state.

HRESULT OnUIDeactivate(

BOOL fUndoable	//Specifies if object can undo changes
);
Parameter

fUndoable

[in] Specifies whether the object can undo changes. TRUE if the object can undo, FALSE if it cannot.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The method completed successfully.

Remarks

The object indicates whether it can undo changes through the fUndoable flag. If the object can undo changes, the container can (by the user invoking the Edit Undo command) call the IOleInPlaceObject::ReactivateAndUndo method to undo the changes.

Notes to Callers

IOleInPlaceSite::OnUIDeactivate is called by the site’s immediate child object when it is deactivating to notify the container that it should reinstall its own user interface components and take focus. The container should wait for the call to IOleInPlaceSite::OnUIDeactivate to complete before fully cleaning up and destroying any composite submenus.

See Also

IOleInPlaceObject::ReactivateAndUndo


IOleInPlaceSite::Scroll

Tells the container to scroll the view of the object by a specified number of pixels.

HRESULT Scroll(

SIZE scrollExtent	//Number of pixels
);
Parameter

scrollExtent

[in] Number of pixels by which to scroll in the X and Y directions.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The method successfully executed the view scroll instruction.

Remarks

As a result of scrolling, the object’s visible rectangle can change. If that happens, the container should give the new ClipRect to the object by calling IOleInPlaceObject::SetObjectRects. The intersection of the ClipRect and PosRect rectangles gives the new visible rectangle. See IOleInPlaceSite::GetWindowContext for a discussion of ClipRect and PosRect.

Notes to Callers

Called by an active, in-place object when it is asking the container to scroll.

See Also

IOleInPlaceObject::SetObjectRects


IOleInPlaceSiteEx

The IOleInPlaceSiteEx interface provides an additional set of activation and deactivation notification methods that enable an object to avoid unnecessary flashing on the screen when the object is activated and deactivated.

When an object is activated, it does not know if its visual display is already correct. When the object is deactivated, the container does not know if the visual display is correct. To avoid a redraw and the associated screen flicker in both cases, the container can provide this extension to IOleInPlaceSite.

When to Implement

Implement this interface on the client site in a container application that supports flicker-free activation and deactivation of embedded, in-place active objects.

When to Use

An embedded object, such as a control, calls the methods in this interface to determine if it needs to redraw itself on activation and to notify the container if the object needs to be redrawn on deactivation. By avoiding the redraw when it is not needed, you can reduce the amount of flashing on the screen.

If the site object does not support IOleInPlaceSiteEx, the object must call methods in the IOleInPlaceSite interface instead. In this case, the object must redraw itself on activation and deactivation.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleWindow Methods	Description
GetWindow	Gets a window handle.
ContextSensitiveHelp	Controls enabling of context-sensitive help.
IOleInPlaceSite Methods	Description
CanInPlaceActivate	Determines if the container can activate the object in place.
OnInPlaceActivate	Notifies the container that one of its objects is being activated in place.
OnUIActivate	Notifies the container that the object is about to be activated in place, and that the main menu will be replaced by a composite menu.
GetWindowContext	Enables an in-place object to retrieve window interfaces that form at the window object hierarchy, and the position in the parent window to locate the object’s in-place activation window.
Scroll	Specifies the number of pixels by which the container is to scroll the object.
OnUIDeactivate	Notifies the container to reinstall its user interface and take focus.
OnInPlaceDeactivate	Notifies the container that the object is no longer active in place.
DiscardUndoState	Instructs the container to discard its undo state.
DeactivateAndUndo	Deactivate the object and revert to undo state.
OnPosRectChange	Object’s extents have changed.
IOleInPlaceSiteEx Methods	Description
OnInPlaceActivateEx	Called by the embedded object to determine if it needs to redraw itself upon activation.
OnInPlaceDeactivateEx	Notifies the container of whether the object needs to be redrawn upon deactivation.
RequestUIActivate	Notifies the container that the object is about to enter the UI-active state.
See Also

IOleInPlaceSite


IOleInPlaceSiteEx::OnInPlaceActivateEx

Called by the embedded object to determine if it needs to redraw itself upon activation.

HRESULT OnInPlaceActivateEx(

BOOL* pfNoRedraw,	//Pointer to current redraw status
DWORD dwFlags	//Indicates whether the object is windowless
);
Parameters

pfNoRedraw

[out] Pointer to current redraw status. The status is TRUE if the object need not redraw itself upon activation; FALSE if the object needs to redraw upon activation. Windowless objects usually do not need the value returned by this parameter and may pass a NULL pointer to save the container the burden of computing this value.

dwFlags

[in] Indicates whether the object is activated as a windowless object. This parameter takes values from the ACTIVATEFLAGS enumeration. See IOleInPlaceSiteWindowless for more information on windowless objects.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The container allows the in-place activation.

Remarks

This method replaces IOleInPlaceSite::OnInPlaceActivate. If the older method is used, the object must always redraw itself on activation.

Windowless objects are required to use this method instead of IOleInPlaceSite::OnInPlaceActivate to notify the container of whether they are activating windowless or not.

Notes to Implementers

The container should carefully check the invalidation status of the object, its z-order, clipping and any other relevant parameters to determine the appropriate value to return in pfNoRedraw.

A container can cache the value of the ACTIVATEFLAGS enumeration instead of calling the GetWindow method in the IOleInPlaceObjectWindowless interface repeatedly.

See Also

ACTIVATEFLAGS, IOleInPlaceSite::OnInPlaceActivate, IOleInPlaceObjectWindowless IOleInPlaceSiteWindowless


IOleInPlaceSiteEx::OnInPlaceDeactivateEx

Notifies the container if the object needs to be redrawn upon deactivation.

HRESULT OnInPlaceDeactivateEx(

BOOL fNoRedraw	//Indicates whether the object needs to be redrawn
);
Parameter

fNoRedraw

[in] If TRUE, the container need not redraw the object after completing the deactivation; if FALSE the object must be redrawn after deactivation.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The method successfully notified the container.

Remarks

This method replaces IOleInPlaceSite::OnInPlaceDeactivate. If the older method is used, the object must always be redrawn on deactivation.

See Also

IOleInPlaceSite::OnInPlaceDeactivate


IOleInPlaceSiteEx::RequestUIActivate

Notifies the container that the object is about to enter the UI-active state.

HRESULT RequestUIActivate(void);

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The object can continue the activation process and call IOleInPlaceSite::OnUIActivate.

S_FALSE

The object cannot enter the UI-active state. The object must call IOleInPlaceSite::OnUIDeactivate so the container can perform its the necessary processing to restore the focus.

Remarks

An object calls this method to determine if it can enter the UI-active state and to notify the container that it is about to make this transition. The container can return S_FALSE to deny this request, for example, if the end user has canceled the operation or if the currently active object will not relinquish its active state.

If the object does not call RequestUIActivate, the container handles data validation and fires Enter and Exit events from IOleInPlaceSite::OnUIActivate.

See Also

IOleInPlaceSite::OnUIActivate, IOleInPlaceSite::OnUIDeactivate


IOleInPlaceSiteWindowless

The IOleInPlaceSiteWindowless interface is derived from and extends the IOleInPlaceSiteEx interface. IOleInPlaceSiteWindowless works with IOleInPlaceObjectWindowless which is implemented on the windowless object. Together, these two interfaces provide services to a windowless object from its container allowing the windowless object to:

•	process window messages

•	participate in drag and drop operations

•	perform drawing operations

Having a window can place unnecessary burdens on small objects, such as controls. It prevents an object from being non-rectangular. It prevents windows from being transparent. It prevents the small instance size needed by many small controls.

A windowless object can enter the in-place active state without requiring a window or the resources associated with a window. Instead, the object’s container provides the object with many of the services associated with having a window.

Windowless object model

Windowless objects are an extension of normal compound document objects. They follow the same in-place activation model and share the same definitions for the various OLE states, with the difference that they do not consume a window when they enter the in-place and UI active states. They are required to comply with the OLE compound document specification, including in-place and UI activation.

Windowless objects require special support from their container. In other words, the container has to be specifically written to support this new kind of object. However, windowless objects are backward compatible with down level containers. In such containers, they simply create a window when active and behave as a normal compound document object.

As with other compound document objects, windowless objects need to be in-place active to get mouse and keyboard messages. In fact, since an object needs to have the keyboard focus to receive keyboard messages, and having the keyboard focus implies being UI active for an object, only UI active objects will actually get keyboard messages. Non-active objects can still process keyboard mnemonics.

Since windowless objects do not have a window, they rely on their container to receive window messages for them. The container dispatches its own window messages to the appropriate embedded, windowless object through calls to IOleInPlaceObjectWindowless methods. Similarly, windowless objects can obtain services from their container such as capturing the mouse, setting the focus, getting a device context in which to paint, and so on. The control calls IOleInPlaceSiteWindowless methods. In addition, the container is responsible for drawing any border hatching as well as the grab handles for the control.

These two interfaces are derived from existing interfaces. By extending existing interfaces rather than creating new ones, no new VTable pointer is added to the object instance, helping to keep the instance size small.

Client and server negotiations with windowless objects

When a windowless object gets in-place activated, it should query its site for the IOleInPlaceSiteWindowless interface. If this interface is supported, the object calls IOleInPlaceSiteWindowless::CanWindowlessActivate to determine if it can proceed and in-place activate without a window.

If the container does not support IOleInPlaceSiteWindowless or if the IOleInPlaceSiteWindowless::CanWindowlessActivate method returns S_FALSE, the windowless object should behave like a normal compound document object and create a window.

The container can get the window handle for an embedded object by calling IOleWindow::GetWindow. This method should fail (return E_FAIL) for a windowless object. However, a container cannot be sure that the object is windowless by calling this method. The object may have a window but may not have created it yet. Many existing objects only create their window after calling the OnInPlaceActivate method on their site object.

Consequently, a windowless object must call the new IOleInPlaceSiteEx::OnInPlaceActivateEx method on its site object, instead of OnInPlaceActivate. The dwFlags parameter for this new method contains additional information in the ACTIVATEFLAGS enumeration. The ACTIVATE_WINDOWLESS enumeration value indicates that the object is activated without a window. Containers can cache this value instead of calling the GetWindow method on the IOleWindow interface repeatedly.

Message dispatching

Windowless objects rely on their containers to dispatch window messages to them, capture the mouse, and get the keyboard focus. The container calls IOleInPlaceObject::OnWindowMessage to dispatch a window message to a windowless object. This method is similar to the SendMessage Windows API function except that it does not require an HWND parameter and it returns both an HRESULT and a LRESULT.

A windowless object must not call the DefWindowProc Windows API function directly. Instead, it calls IOleInPlaceSiteWindowless::OnDefWindowMessage to invoke the default action, for example with WM_SETCURSOR or WM_HELP that should be propagated back up to the container. Thus, the container has a chance to handle the message before the object processes it.

For mouse messages, the object calls IOleInPlaceSiteWindowless::Set Capture to obtain the mouse capture and IOleInPlaceSiteWindowless::SetFocus to get the keyboard focus.

A windowless object handles accelerators and mnemonics as follows:

Accelerators

The UI active object checks for its own accelerators in IOleInPlaceActiveObject::TranslateAccelerator. A windowless object does the same. However, a windowless object cannot send a WM_COMMAND message to itself, as a windowed object would do. Therefore, instead of translating the key to a command, a windowless object should simply process the key right away.

Except for that one difference, windowless objects should implement the IOleInPlaceActiveObject::TranslateAccelerator method as defined in the OLE specifications. In particular, a windowless object should pass the accelerator message up to its site object if it does not wish to handle it. The windowless object and returns S_OK if the message got translated and S_FALSE if not. In the case of a windowless object, the message is processed instead of translated. Non translated messages will come back to the object through the IOleInPlaceObjectWindowless::OnWindowMessage method.

Note that because the container’s window gets all keyboard input, a UI active object should look for messages sent to that window to find those it needs to process in its IOleInPlaceActiveObject::TranslateAccelerator method. An object can get its container’s window by calling IOleWindow::GetWindow.

Mnemonics

Control mnemonics are handled the same way whether the control is windowless or not. The container gets the control mnemonic table by  calling IOleControl::GetControlInfo and then calls IOleControl::OnMnemonic when it receives a key combination that matches a control mnemonic.

Drag & drop onto windowless objects

Since a windowless object does not have a window when it is active, it cannot register its own IDropTarget interface with the RegisterDragDrop function. However, to participate in drag and drop operations, a windowless object still must implement this interface. The object supplies its container with a pointer to its IDropTarget interface through IOleInPlaceObjectWindowless::GetDropTarget instead of having the container call QueryInterface for it. See IOleInPlaceObjectWindowless::GetDropTarget for more information on drag and drop operations involving windowless objects.

In-place drawing for windowless objects

With windowed objects, the container is only responsible for drawing the object when it is inactive. Windowed objects have their own window when they are active and can draw themselves independently of their container.

A windowless object, however, needs services from its container to redraw itself even when it is active. The container must provide the object with information about its surrounding environment, such as the clipping region, the background, overlapping objects in front of the object being redrawn, and a device context in which to draw.

The IOleInPlaceSiteWindowless interface on the container’s site object provides these services: drawing the object, obtaining and releasing the device context, invalidating the object’s on-screen display, scrolling the object, or showing a caret when the object is active.

Note  All methods of IOleInPlaceSiteWindowless take position information in client coordinates of the containing window, that is, the window in which the object is being drawn.

Drawing windowless objects

To maintain compatibility with windowed objects, the container still uses IViewObject::Draw to redraw the in-place active, windowless object. See IViewObject::Draw for information on how the method is used with windowless objects.

Obtaining and releasing a device context

To draw on its own when in-place active, a windowless object must call its site’s IOleInPlaceSiteWindowless::GetDC method to get a device context in which to draw. Then, it draws into the device context and releases it by calling IOleInPlaceSiteWindowless::ReleaseDC.

Display Invalidation

In-place windowless objects may need to invalidate regions of their on-screen image. Even though the notification methods in IAdviseSinkEx can be used for that purpose, they are not ideal for in-place active objects because they take HIMETRIC coordinates. In order to simplify and speed up in-place drawing, the InvalidateRect and InvalidateRgn methods in the IOleInPlaceSiteWindowless interface provide the same functionality.

An object cannot call the Windows API functions InvalidateRect and InvalidateRgn directly on the window handle it gets from calling IOleInPlaceSiteWindowless::GetWindow on its site.

Scrolling

In-place active windowless objects may need to scroll a given rectangle of their on-screen image, for example, with a multi-line text control. Because of transparent and overlapping objects, the Windows API functions ScrollWindow and ScrollDC cannot be used. Instead, the IOleInPlaceSiteWindowless::ScrollRect method enables objects to perform scrolling.

Caret support

A windowless object cannot safely show a caret without first checking whether the caret is partially or totally hidden by overlapping objects. In order to make that possible, an object can submit a rectangle to its site object when it calls the site’s IOleInPlaceSiteWindowless::AdjustRect method to get a specified rectangle adjusted (usually, reduced) to ensure the rectangle fits in the clipping region.

When to Implement

Implement this interface on the container’s site object to support windowless objects.

When to Use

The windowless object calls the methods in this interface to process window messages, to participate in drag and drop operations, and to perform drawing operations.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleWindow Methods	Description
GetWindow	Gets a window handle.
ContextSensitiveHelp	Controls enabling of context-sensitive help.
IOleInPlaceSite Methods	Description
CanInPlaceActivate	Determines if the container can activate the object in place.
OnInPlaceActivate	Notifies the container that one of its objects is being activated in place.
OnUIActivate	Notifies the container that the object is about to be activated in place, and that the main menu will be replaced by a composite menu.
GetWindowContext	Enables an in-place object to retrieve window interfaces that form at the window object hierarchy, and the position in the parent window to locate the object’s in-place activation window.
Scroll	Specifies the number of pixels by which the container is to scroll the object.
OnUIDeactivate	Notifies the container to reinstall its user interface and take focus.
OnInPlaceDeactivate	Notifies the container that the object is no longer active in place.
DiscardUndoState	Instructs the container to discard its undo state.
DeactivateAndUndo	Deactivate the object and revert to undo state.
OnPosRectChange	Object’s extents have changed.
IOleInPlaceSiteEx Methods	Description
OnInPlaceActivateEx	Called by the embedded object to determine if it needs to redraw itself upon activation.
OnInPlaceDeactivateEx	Notifies the container of whether the object needs to be redrawn upon deactivation.
RequestUIActivate	Notifies the container that the object is about to enter the UI-active state.
IOleInPlaceSiteWindowless Methods	Description
CanWindowlessActivate	Informs an object if its container can support it as a windowless object that can be in-place activated.
GetCapture	Called by an in-place active, windowless object to determine if it still has the mouse capture or not.
SetCapture	Enables an in-place active, windowless object to capture all mouse messages.
GetFocus	Called by an in-place active, windowless object to determine if it still has the keyboard focus or not.
SetFocus	Sets the keyboard focus for a UI-active, windowless object.
GetDC	Provides an object with a handle to a device context for a screen or compatible device from its container.
ReleaseDC	Releases the device context previously obtained by a call to IOleInPlaceSiteWindowless::GetDC.
InvalidateRect	Enables an object to invalidate a specified rectangle of its in-place image on the screen.
InvalidateRgn	Enables an object to invalidate a specified region of its in-place image on the screen.
ScrollRect	Enables an object to scroll an area within its in-place active image on the screen.
AdjustRect	Adjusts a specified rectangle if it is entirely or partially covered by overlapping, opaque objects.
OnDefWindowMessage	Invokes the default processing for all messages passed to an object.
See Also

IAdviseSinkEx, IOleControl, IOleInPlaceActiveObject::TranslateAccelerator, IOleInPlaceObjectWindowless,


IOleInPlaceSiteWindowless::AdjustRect

Adjusts a specified rectangle if it is entirely or partially covered by overlapping, opaque objects.

HRESULT AdjustRect(

LPRECT prc	//Rectangle to adjust
);
Parameters

prc

[in,out] Rectangle to adjust.

Return Values

S_OK

The rectangle was adjusted successfully. Note S_OK means that the rectangle was not completely covered.

S_FALSE

The rectangle was adjusted successfully. Note S_FALSE means that the rectangle was completely covered. Its width and height are now NULL.

Remarks

The main use of this method is to adjust the size of the caret. An object willing to create a caret should submit the caret rectangle to its site object by calling this method and using the adjusted rectangle returned from it for the caret. If the caret is entirely hidden, this method will return S_FALSE and the caret should not be shown at all in this case.

In a situation where objects are overlapping this method should return the largest rectangle that is fully visible.

This method can also be used to figure whether a point or a rectangular area is visible or hidden by overlapping objects.


IOleInPlaceSiteWindowless::CanWindowlessActivate

Informs an object if its container can support it as a windowless object that can be in-place activated.

HRESULT CanWindowlessActivate(void);

Return Values

S_OK

The object can activate in place without a window.

Remarks

If this method returns S_OK, the container can dispatch events to it using IOleInPlaceObjectWindowless.

If this method returns S_FALSE, the object should create a window and behave as a normal compound document object.

See Also

IOleInPlaceObjectWindowless


IOleInPlaceSiteWindowless::GetCapture

Called by an in-place active, windowless object to determine if it still has the mouse capture or not.

HRESULT GetCapture(void);

Return Values

S_OK

The object currently has the mouse capture.

S_FALSE

The object does not currently have the mouse capture.

Remarks

As an alternative to calling this method, the object can cache information about whether it has the mouse capture or not.


IOleInPlaceSiteWindowless::GetDC

Provides an object with a handle to a device context for a screen or compatible device from its container.

HRESULT GetDC(

LPCRECT pRect,	//Pointer to rectangle
DWORD grfFlags,	//OLEDCFLAGS value
HDC* phDC	//Pointer to device context
);
Parameters

pRect

[in] Pointer to the rectangle that the object wants to redraw, in client coordinates of the containing window. If this parameter is NULL, the object’s full extent is redrawn.

grfFlags

[in] A combination of values from the OLEDCFLAGS enumeration.

phDC

[out] Pointer to a returned device context.

Return Values

S_OK

A device context was successfully returned.

OLE_E_NESTEDPAINT

The container is already in the middle of a paint session. That is, this method has already been called, and the ReleaseDC method has not yet been called.

Remarks

A device context obtained by this method should be released by calling IOleInPlaceSiteWindowless::ReleaseDC.

Like other methods in this interface, rectangles are specified in client coordinates of the containing window. The container is expected to intersect this rectangle with the object’s site rectangle and clip out everything outside the resulting rectangle. This prevents objects from inadvertently drawing where they are not supposed to.

Containers are also expected to map the device context origin so the object can draw in client coordinates of the containing window, usually the container’s window. If the container is merely passing its window device context, this occurs automatically. If it is returning another device context, for example, an offscreen memory device context, then the viewport origin should be set appropriately.

Notes to Implementers

Depending whether it is returning an on-screen or off-screen device context and depending on how sophisticated it is, container can use one of the following algorithms:

1.	On-screen, one pass drawing

In the GetDC method, the container should:

•	Get the window device context.

•	If OLEDC_PAINTBKGND is set, draw the DVASPECT_CONTENT aspect of every object behind the object requesting the device context.

•	Return the device context.

In the ReleaseDC method, the container should:

•	Draw the DVASPECT_CONTENT of every overlapping object.

•	Release the device context.

2.	On-screen, two pass drawing

In the GetDC method, the container should:

•	Get the window device context.

•	Clip out the opaque regions of any overlapping object. These regions do not need to be redrawn since they are already correct on the screen.

•	If OLEDC_PAINTBKGND is not set, return the device context.

•	Otherwise, clip out the opaque parts of the object requesting the device context and draw the opaque parts of every object behind it going front to back.

•	Draw the transparent aspects of every object behind going back to front, setting the clipping region appropriately each time.

•	Finally return the device context.

In the ReleaseDC method, the container should:

•	Draw the transparent parts of every overlapping object.

•	Release the device context.

3.	Off-screen drawing

In the GetDC method, the container should:

•	Create a screen compatible memory device context, containing a compatible bitmap of appropriate size.

•	Map the viewport origin of the device context to ensure that the calling object can draw using client area coordinates of the containing window.

•	If OLEDC_PAINTBKGND is set, draw the DVASPECT_CONTENT of every object behind the calling object.

•	Return the device context.

In the ReleaseDC method, the container should:

•	Draw the DVASPECT_CONTENT aspect of every overlapping object.

•	Copy the off-screen bitmap to the screen at the location the calling object originally requested in GetDC.

•	Delete and release the memory device context.

When this method returns, the clipping region in the device context should be set so that the object can’t paint in any area it is not supposed to. If the object is not opaque, the background should have been painted. If the device context is a screen, any overlapping opaque areas should be clipped out.

See Also

IOleInPlaceSiteWindowless::ReleaseDC, OLEDCFLAGS


IOleInPlaceSiteWindowless::GetFocus

Called by an in-place active, windowless object to determine if it still has the keyboard focus or not.

HRESULT GetFocus(void);

Return Values

S_OK

The object currently has the keyboard focus.

S_FALSE

The object does not currently have the keyboard focus.

Remarks

A windowless object calls this method to find out if it currently has the focus or not. As an alternative to calling this method, the object can cache information about whether it has the keyboard focus or not.


IOleInPlaceSiteWindowless::InvalidateRect

Enables an object to invalidate a specified rectangle of its in-place image on the screen.

HRESULT InvalidateRect(

LPCRECT pRect,	//Rectangle to be invalidated
BOOL fErase	//Indicates whether to erase the background
);
Parameters

pRect

[in] Rectangle to invalidate, in client coordinates of the containing window. If this parameter is NULL, the object’s full extent is invalidated.

fErase

[in] Specifies whether the background within the update region is to be erased when the region is updated. If this parameter is TRUE, the background is erased. If this parameter is FALSE, the background remains unchanged.

Return Values

S_OK

The specified rectangle was successfully invalidated.

Remarks

An object is only allowed to invalidate pixels contained in its own site rectangle. Any attempt to invalidate an area outside of that rectangle should result in a no-op.


IOleInPlaceSiteWindowless::InvalidateRgn

Enables an object to invalidate a specified region of its in-place image on the screen.

HRESULT InvalidateRgn(

HRGN hRGN,	//Region to be invalidated
BOOL fErase	//Indicates whether to erase the background
);
Parameters

hRGN

[in] Region to invalidate, in client coordinates of the containing window. If this parameter is NULL, the object’s full extent is invalidated.

fErase

[in] Specifies whether the background within the update region is to be erased when the region is updated. If this parameter is TRUE, the background is erased. If this parameter is FALSE, the background remains unchanged.

Return Values

S_OK

The specified region was successfully invalidated.

Remarks

An object is only allowed to invalidate pixels contained in its own site region. Any attempt to invalidate an area outside of that region should result in a no-op.


IOleInPlaceSiteWindowless::OnDefWindowMessage

Invokes the default processing for all messages passed to an object.

HRESULT OnDefWindowMessage(

UINT msg,	//Message Identifier as provided by Windows
WPARAM wParam,	//Message parameter as provided by Windows
LPARAM lParam,	//Message parameter as provided by Windows
LRESULT* plResult	//Pointer to message result code
);
Parameters

msg

[in] Identifier for the window message provided to the container by Windows.

wParam

[in] Parameter for the window message provided to the container by Windows.

lParam

[in] Parameter for the window message provided to the container by Windows.

plResult

[out] Pointer to result code for the window message as defined in the Windows API.

Return Values

S_OK

The container’s default processing for the window message was successfully invoked.

S_FALSE

The container’s default processing for the window message was not invoked. See Note to Implementers below.

Remarks

A windowless object can explicitly invoke the default processing for a window message by calling this method. A container dispatches window messages to its windowless objects by calling IOleInPlaceObjectWindowless::OnWindowMessage. The object usually returns S_FALSE to indicate that it did not process the message. Then, the container can perform the default behavior for the message by calling the Windows API function DefWindowProc.

Instead, the object can call this method on the container’s site object to explicitly invoke the default processing. Then, the object can take action on its own if the container does not handle the message.

Note to Implementers

The container must pass the following window messages to its default window procedure (the DefWindowProc Windows API function) and return S_OK. Note that *plResult should contain the value returned by DefWindowProc.

WM_MOUSEMOVE	WM_DEADCHAR
WM_XBUTTONxxx	WM_SYSKEYUP
WM_KEYDOWN	WM_SYSCHAR
WM_KEYUP	WM_SYSDEADCHAR
WM_CHAR	WM_IMExxx
The container can either process the window messages as its own and return S_OK or not do anything and return S_FALSE.

WM_SETCURSOR
WM_CONTEXTMENU
WM_HELP
If the container returns S_FALSE, the object can take action to process the window message on its own.

See Also

IOleInPlaceObjectWindowless::OnWindowMessage


IOleInPlaceSiteWindowless::ReleaseDC

Releases the device context previously obtained by a call to IOleInPlaceSiteWindowless::GetDC.

HRESULT ReleaseDC(

HDC hDC	//Device context to be released
);
Parameters

hDC

[in] Specifies the device context to be released.

Return Values

S_OK

The device context was successfully released.

Remarks

An object calls this method to notify its container that the object is done with the device context. If the device context was used for drawing, the container should ensure that all overlapping objects are repainted correctly. If the device context was an offscreen device context, its content should also be copied to the screen in the rectangle originally passed to IOleInPlaceSiteWindowless::GetDC. See IOleInPlaceSiteWindowless::GetDC for implementation notes relevant to ReleaseDC.

See Also

IOleInPlaceSiteWindowless::GetDC


IOleInPlaceSiteWindowless::ScrollRect

Enables an object to scroll an area within its in-place active image on the screen.

HRESULT ScrollRect(

int dx,	//Amount to scroll on the x-axis
int dy,	//Amount to scroll on the y-axis
LPCRECT pRectScroll,	//Rectangle to scroll
LPCRECT pRectClip	//Rectangle to clip
);
Parameters

dx

[in] Amount to scroll on the x-axis.

dy

[in] Amount to scroll on the y-axis.

pRectScroll

[in] Rectangle to scroll, in client coordinates of the containing window. NULL means the full object.

pRectClip

[in] Rectangle to clip to as defined for the Windows API function. Only pixels scrolling into this rectangle are drawn. Pixels scrolling out are not. If this parameter is NULL, the rectangle is not clipped.

Return Values

S_OK

The rectangle was successfully scrolled.

Remarks

This method should take in account the fact that the caller may be transparent and that there may be opaque or transparent overlapping objects. See Notes to Implementers below for suggestions on algorithms this method can use.

Note to Implementers

Containers can implement this method in a variety of ways. However, all of them should account for the possibility that the object requesting scrolling may be transparent or may not have a solid background. Containers should also take into account that there may be overlapping objects.

The simplest way to implement this method consists in simply redrawing the rectangle to scroll.

An added refinement to this simple implementation is to use the ScrollDC Windows API function when the object requesting the scroll is opaque, the object has a solid background, and there are no overlapping objects.

More sophisticated implementations can use the following procedure:

•	Check whether the object is opaque and has a solid background, using IViewObjectEx::GetViewStatus. If not, simply invalidate the rectangle to scroll. An added refinement is to check whether the scrolling rectangle is entirely in the opaque region of a partially transparent object.

•	Get the window device context.

•	Clip out the opaque parts of any overlapping object returned by IViewObjectEx::GetRect.

•	Clip out and invalidate the transparent parts of any overlapping object.

•	Finally, call the Windows API function ScrollDC.

•	Redraw the previously invalidated transparent parts of any overlapping object.

Regardless of the scrolling and clipping rectangle, only pixels contained in the object’s site rectangle will be painted. The area uncovered by the scrolling operation is invalidated and redrawn immediately, before this method returns.

All redraw generated by this method should happen synchronously before this method returns.

This method should automatically hide the caret during the scrolling operation and should move the caret by the scrolling amounts if it is inside the clip rectangle.

See Also

IViewObjectEx::GetViewStatus, IViewObjectEx::GetRect


IOleInPlaceSiteWindowless::SetCapture

Enables an in-place active, windowless object to capture all mouse messages.

HRESULT SetCapture(

BOOL fCapture	//Set or release mouse capture
);
Parameters

fCapture

[in] If TRUE, the container should capture the mouse for the object. If FALSE, the container should release mouse capture for the object.

Return Values

S_OK

Mouse capture was successfully granted to the object. If called to release the mouse capture, this method must not fail.

S_FALSE

Mouse capture was denied to the object.

Remarks

A windowless object captures the mouse input, by calling  IOleInPlaceSiteWindowless::SetCapture(TRUE) on its site object. The container can deny mouse capture, in which case this method returns S_FALSE. If the capture is granted, the container must set the Windows mouse capture to its own window and dispatch any subsequent mouse message to the object, regardless of whether the mouse cursor position is over this object or not.

The object can later release mouse capture by calling IOleInPlaceSiteWindowless::SetCapture(FALSE) on its site object. The capture can also be released because of an external event, such as the ESC key being pressed. In this case, the object is notified by a WM_CANCELMODE message that the container dispatches along with the keyboard focus.

Containers should dispatch all mouse messages, including WM_SETCURSOR, to the windowless OLE object that has captured the mouse. If no object has captured the mouse, the container should dispatch the mouse message to the object under the mouse cursor.

The container dispatches these window messages by calling IOleInPlaceObjectWindowless::OnWindowMessage on the windowless object. The windowless object can return S_FALSE to this method to indicate that it did not process the mouse message. Then, the container should perform the default behavior for the message by calling the Windows API function DefWindowProc. For WM_SETCURSOR, the container can either set the cursor itself or do nothing.

Objects can also use IOleInPlaceSiteWindowless::OnDefWindowMessage to invoke the default message processing from the container. In the case of the WM_SETCURSOR message, this allows an object to take action if the container does not set the cursor.

See Also

IOleInPlaceSiteWindowless::OnDefWindowMessage


IOleInPlaceSiteWindowless::SetFocus

Sets the keyboard focus for a UI-active, windowless object.

HRESULT SetFocus(

BOOL fFocus	//Set or release the keyboard focus
);
Parameters

fFocus

[in] If TRUE, sets the keyboard focus to the calling object. If FALSE, removes the keyboard focus from the calling object, provided that the object has the focus.

Return Values

S_OK

Keyboard focus was successfully given to the object. If this method is called to release the focus, it should never fail.

S_FALSE

Keyboard focus was denied to the object.

Remarks

A windowless object calls this method whenever a windowed object would call the Windows API function SetFocus. Through this call, the windowless object obtains the keyboard focus and can respond to window messages. Normally, this call is made during the UI activation process and within the notification methods IOleInPlaceActiveObject::OnDocWindowActivate(TRUE) and IOleInPlaceActiveObject::OnFrameWindowActivate(TRUE).

In response to this call, the container sets the Windows focus to the window being used to get keyboard messages (usually the container window) and redirects any subsequent keyboard messages to the windowless object that requested the focus.

A windowless object also calls the IOleInPlaceSiteWindowless::SetFocus method with the fFocus parameter set to FALSE to release the keyboard focus without assigning it to any other object. In this case, the container must call the Windows API function SetFocus with a NULL parameter so that no window has the focus.

See Also

IOleInPlaceActiveObject


IOleInPlaceUIWindow

The IOleInPlaceUIWindow interface is implemented by container applications and used by object applications to negotiate border space on the document or frame window. The container provides a RECT structure in which the object can place toolbars and other similar controls, determines if tools can in fact be installed around the object's window frame, allocates space for the border, and establishes a communication channel between the object and each frame and document window.

The document window may not exist in all applications. When this is the case, IOleInPlaceSite::GetWindowContext returns NULL for IOleInPlaceUIWindow.

When to Implement

You must implement this interface if you are writing a container application that will participate in in-place activation.

When to Use

Used by object applications to negotiate border space on the document or frame window when one of its objects is being activated, or to renegotiate border space if the size of the object changes.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleWindow Methods	Description
GetWindow	Gets a window handle.
ContextSensitiveHelp	Controls enabling of context-sensitive help.
IOleInPlaceUIWindow Methods	Description
GetBorder	Specifies a RECT structure for toolbars and controls.
RequestBorderSpace	Determines if tools can be installed around object's window frame.
SetBorderSpace	Allocates space for the border.
SetActiveObject	Provides for direct communication between the object and each document and frame window.
See Also

IOleWindow


IOleInPlaceUIWindow::GetBorder

Returns a RECT structure in which the object can put toolbars and similar controls while active in place.

HRESULT GetBorder(

LPRECT lprectBorder	//Pointer to structure
);
Parameter

lprectBorder

[out] Pointer to a RECT structure where the outer rectangle is to be returned. The RECT structure’s coordinates are relative to the window being represented by the interface.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The rectangle was successfully returned.

E_NOTOOLSPACE

The object cannot install toolbars in this window object.

Remarks

Notes to Callers

The IOleInPlaceUIWindow::GetBorder function, when called on a document or frame window object, returns the outer rectangle (relative to the window) where the object can put toolbars or similar controls.

If the object is to install these tools, it should negotiate space for the tools within this rectangle using IOleInPlaceUIWindow::RequestBorderSpace and then call IOleInPlaceUIWindow::SetBorderSpace to get this space allocated.

Note  While executing IOleInPlaceUIWindow::GetBorder, do not make calls to the Windows PeekMessage or GetMessage functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface methods and functions can be called from within GetBorder.

See Also

IOleInPlaceUIWindow::RequestBorderSpace, IOleInPlaceUIWindow::SetBorderSpace

PeekMessage, GetMessage in Win32


IOleInPlaceUIWindow::RequestBorderSpace

Determines if there is available space for tools to be installed around the object’s window frame while the object is active in place.

HRESULT RequestBorderSpace(

LPCBORDERWIDTHS pborderwidths	//Pointer to a structure
);
Parameter

pborderwidths

[in] Pointer to a BORDERWIDTHS structure containing the requested widths (in pixels) needed on each side of the window for the tools.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The requested space could be allocated to the object.

E_NOTOOLSPACE

The object cannot install toolbars in this window object because the implementation does not support toolbars, or there is insufficient space to install the toolbars.

Remarks

Notes to Callers

The active in-place object calls IOleInPlaceUIWindow::RequestBorderSpace to ask if tools can be installed inside the window frame. These tools would be allocated between the rectangle returned by IOleInPlaceUIWindow::GetBorder and the BORDERWIDTHS structure specified in the argument to this call.

The space for the tools is not actually allocated to the object until it calls IOleInPlaceUIWindow::SetBorderSpace, allowing the object to negotiate for space (such as while dragging toolbars around), but deferring the moving of tools until the action is completed.

The object can install these tools by passing the width in pixels that is to be used on each side. For example, if the object required 10 pixels on the top, 0 pixels on the bottom, and 5 pixels on the left and right sides, it would pass the following BORDERWIDTHS structure to IOleInPlaceUIWindow::RequestBorderSpace:

lpbw->top    = 10

lpbw->bottom =  0

lpbw->lLeft  =  5

lpbw->right  =  5

Note  While executing IOleInPlaceUIWindow::RequestBorderSpace, do not make calls to the Windows PeekMessage or GetMessage functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface methods and functions can be called from within RequestBorderSpace.

Notes to Implementers

If the amount of space an active object uses for its toolbars is irrelevant to the container, it can simply return NOERROR as shown in the following IOleInPlaceUIWindow::RequestBorderSpace example. Containers should not unduly restrict the display of tools by an active in-place object.

HRESULT InPlaceUIWindow_RequestBorderSpace(

    IOleInPlaceFrame *  lpThis,

    LPCBORDERWIDTHS     pborderwidths)

{

    /* Container allows the object to have as much border space as it

    ** wants.

    */

    return NOERROR;

}

See Also

IOleInPlaceUIWindow::GetBorder, IOleInPlaceUIWindow::SetBorderSpace PeekMessage, GetMessage in Win32


IOleInPlaceUIWindow::SetActiveObject

Provides a direct channel of communication between the object and each of the frame and document windows.

HRESULT SetActiveObject(

IOleInPlaceActiveObject *pActiveObject,	//Pointer to active in-place object
LPCOLESTR pszObjName	//Pointer tostring containing a name describing the object
);
Parameters

pActiveObject

[in] Pointer to the IOleInPlaceActiveObject interface on the active in-place object.

pszObjName

[in] Pointer to a string containing a name that describes the object an embedding container can use in composing its window title. It can be NULL if the object does not require the container to change its window titles. The Microsoft Windows User Interface Design Guide recommends that containers ignore this parameter and always use their own name in the title bar.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The method completed successfully.

Remarks

Generally, an embedded object should pass NULL for the pszObjName parameter (see “Notes to Implementers” below). However, if you are working in conjunction with a container that does display the name of the in-place active object in its title bar, then you should compose a string in the following form:

<application name> − <object short-type name>

Notes to Callers

IOleInPlaceUIWindow::SetActiveObject is called by the object to establish a direct communication link between itself and the document and frame windows.

When deactivating, the object calls IOleInPlaceUIWindow::SetActiveObject, passing NULL for the pActiveObject and pszObjName parameters.

An object must call IOleInPlaceUIWindow::SetActiveObject before calling IOleInPlaceFrame::SetMenu to give the container the pointer to the active object. The container then uses this pointer in processing IOleInPlaceFrame::SetMenu and to pass to OleSetMenuDescriptor.

Notes to Implementers

The Microsoft Windows User Interface Design Guide recommends that an in-place container ignore the pszObjName parameter passed in this method. The guide says “The title bar is not affected by in-place activation. It always displays the top-level container’s name.”

See Also

IOleInPlaceFrame::SetMenu, OleSetMenuDescriptor


IOleInPlaceUIWindow::SetBorderSpace

Allocates space for the border requested in the call to IOleInPlaceUIWindow::RequestBorderSpace.

HRESULT SetBorderSpace(

LPCBORDERWIDTHS pborderwidths	//Pointer to a structure
);
Parameter

pborderwidths

[in] Pointer to a BORDERWIDTHS structure containing the requested width (in pixels) of the tools. It can be NULL, indicating the object does not need any space.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The requested space has been allocated to the object.

OLE_E_INVALIDRECT

The rectangle does not lie within the specifications returned by IOleInPlaceUIWindow::GetBorder.

Remarks

The object must call IOleInPlaceUIWindow::SetBorderSpace. It can do any one of the following:

•	Use its own toolbars, requesting border space of a specific size, or,

•	Use no toolbars, but force the container to remove its toolbars by passing a valid BORDERWIDTHS structure containing nothing but zeros in the pborderwidths parameter, or,

•	Use no toolbars but allow the in-place container to leave its toolbars up by passing NULL as the pborderwidths parameter.

The BORDERWIDTHS structure used in this call would generally have been passed in a previous call to IOleInPlaceUIWindow::RequestBorderSpace, which must have returned S_OK.

If an object must renegotiate space on the border, it can call SetBorderSpace again with the new widths. If the call to SetBorderSpace fails, the object can do a full negotiation for border space with calls to GetBorder, RequestBorderSpace, and SetBorderSpace.

Note  While executing IOleInPlaceUIWindow::SetBorderSpace, do not make calls to the Windows PeekMessage or GetMessage functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface methods and functions can be called from within SetBorderSpace.

See Also

IOleInPlaceUIWindow::GetBorder, IOleInPlaceUIWindow::RequestBorderSpace PeekMessage, GetMessage in Win32


IOleItemContainer

The IOleItemContainer interface is used by item monikers when they are bound to the objects they identify.

When any container of objects uses item monikers to identify its objects, it must define a naming scheme for those objects. The container’s IOleItemContainer implementation uses knowledge of that naming scheme to retrieve an object given a particular name. Item monikers use the container’s IOleItemContainer implementation during binding.

When to Implement

You must implement IOleItemContainer if you’re a moniker provider handing out item monikers. Being a moniker provider means handing out monikers that identify your objects to make them accessible to moniker clients. You must use item monikers if the objects you’re identifying are contained within another object and can be individually identified using a string.

The most common example of moniker providers are OLE applications that support linking. If your OLE application supports linking to objects smaller than a file-based document, you need to use item monikers. For a server application that allows linking to a portion of a document (such as selections within a document), you use the item monikers to identify those objects. For a container application that allows linking to embedded objects, you use the item monikers to identify the embedded objects.

You must define a naming scheme for identifying the objects within the container; for example, embedded objects in a document could be identified with names of the form “embedobj1,” “embedobj2,” and so forth, while ranges of cells in a spreadsheet could be identified with names of the form “A1:E7,” “G5:M9,” and so forth. (Ranges of cells in a spreadsheet are examples of “pseudo-objects” because they do not have their own persistent storage, but simply represent a portion of the container’s internal state.) You create an item moniker that represents an object’s name using the CreateItemMoniker function and hand it out to a moniker client. When an item moniker is bound, your implementation of IOleItemContainer must be able to take a name and retrieve the corresponding object.

When to Use

Applications typically do not call IOleItemContainer methods directly. The item moniker implementation of IMoniker is the primary caller of IOleItemContainer methods.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IParseDisplayName Method	Description
ParseDisplayName	Parses object’s display name to form moniker.
IOleContainer Methods	Description
EnumObjects	Enumerates objects in a container.
LockContainer	Keeps container running until explicitly released.
IOleItemContainer Methods	Description
GetObject	Returns a pointer to a specified object.
GetObjectStorage	Returns a pointer to an object’s storage.
IsRunning	Checks whether an object is running.
See Also

CreateItemMoniker, IMoniker − Item Moniker Implementation


IOleItemContainer::GetObject

Returns a pointer to the object identified by the specified name.

HRESULT GetObject(

LPOLESTR pszItem,	//Pointer to name of the object requested
DWORD dwSpeedNeeded,	//Speed requirements on binding
IBindCtx *pbc,	//Pointer to bind context object to be used
REFIID riid,	//Reference to the identifier of the interface pointer desired
void **ppvObject	//Indirect pointer to interface
);
Parameters

pszItem

[in] Pointer to a zero-terminated string containing the container’s name for the requested object. For Win32 applications, the LPOLESTR type indicates a wide character string (two bytes per character); otherwise, the string has one byte per character.

dwSpeedNeeded

[in] Indicates approximately how long the caller will wait to get the object. The legal values for dwSpeedNeeded are taken from the enumeration BINDSPEED. For information on the BINDSPEED enumeration, see the “Data Structures” section.

pbc

[in] Pointer to the IBindCtx interface on the bind context object to be used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the binding implementation should retrieve information about its environment. For more information, see IBindCtx.

riid

[in] Reference to the identifier of the interface pointer requested.

ppvObject

[out] When successful, indirect pointer to the location of the interface specified in riid on the object named by pszItem. In this case, the implementation must call IUnknown::AddRef on the parameter; it is the caller’s responsibility to call IUnknown::Release. If an error occurs, the implementation sets ppvObject to NULL.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The specified object was successfully returned.

MK_E_EXCEEDEDDEADLINE

The binding operation could not be completed within the time limit specified by the bind context’s BIND_OPTS structure, or with the speed indicated by the dwSpeedNeeded parameter.

MK_E_NOOBJECT

The parameter pszItem does not identify an object in this container.

E_NOINTERFACE

The requested interface was not available.

Remarks

The item moniker implementation of IMoniker::BindToObject calls this method, passing the name stored within the item moniker as the pszItem parameter.

Notes to Implementers

Your implementation of IOleItemContainer::GetObject should first determine whether pszItem is a valid name for one of the container’s objects. If not, you should return MK_E_NOOBJECT.

If pszItem names an embedded or linked object, your implementation must check the value of the dwSpeedNeeded parameter. If the value is BINDSPEED_IMMEDIATE and the object is not yet loaded, you should return MK_E_EXCEEDEDDEADLINE. If the object is loaded, your implementation should determine whether the object is running (for example, by calling the OleIsRunning function). If it is not running and the dwSpeedNeeded value is BINDSPEED_MODERATE, your implementation should return MK_E_EXCEEDEDDEADLINE. If the object is not running and dwSpeedNeeded is BINDSPEED_INDEFINITE, your implementation should call the OleRun function to put the object in the running state. Then it can query the object for the requested interface. Note that it is important the object be running before you query for the interface.

If pszItem names a pseudo-object, your implementation can ignore the dwSpeedNeeded parameter because a pseudo-object is running whenever its container is running. In this case, your implementation can simply query for the requested interface.

If you want more specific information about the time limit than is given by dwSpeedNeeded, you can call IBindCtx::GetBindOptions on the pbc parameter to get the actual deadline parameter.

See Also

IMoniker::BindToObject, IBindCtx::GetBindOptions, OleIsRunning, OleRun


IOleItemContainer::GetObjectStorage

Returns a pointer to the storage for the object identified by the specified name.

HRESULT GetObjectStorage(

LPOLESTR pszItem,	//Name of the string containing the name of object whose storage is requested
IBindCtx *pbc,	//Pointer to bind context to be used
REFIID riid,	//Reference to the identifier of the interface pointer desired
void **ppvStorage	//Indirect pointer to object’s storage
);
Parameters

pszItem

[in] Pointer to a zero-terminated string containing the compound document’s name for the object whose storage is requested. For Win32 applications, the LPOLESTR type indicates a wide character string (two bytes per character); otherwise, the string has one byte per character.

pbc

[in] Pointer to the IBindCtx interface on the bind context to be used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the binding implementation should retrieve information about its environment. For more information, see IBindCtx.

riid

[in] Reference to the identifier of the interface to be used to communicate with the object, usually IStorage.

ppvStorage

[out] When successful, indirect pointer to the location of the interface specified in riid, on the storage for the object named by pszItem. In this case, the implementation must call IUnknown::AddRef on the parameter; it is the caller’s responsibility to call IUnknown::Release. If an error occurs, ppvStorage is set to NULL.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The storage of the specified object was successfully returned.

MK_E_NOOBJECT

The parameter pszItem does not identify a object in this container.

MK_E_NOSTORAGE

The object does not have its own independent storage.

E_NOINTERFACE

The requested interface is not available.

Remarks

The item moniker implementation of IMoniker::BindToStorage calls this method.

Notes to Implementers

If pszItem designates a pseudo-object, your implementation should return MK_E_NOSTORAGE, because pseudo-objects do not have their own independent storage. If pszItem designates an embedded object, or a portion of the document that has its own storage, your implementation should return the specified interface pointer on the appropriate storage object.

See Also

IMoniker - Item Moniker Implementation


IOleItemContainer::IsRunning

Indicates whether the object identified by the specified name is running.

HRESULT IsRunning(

LPOLESTR pszItem	//Pointer to string containing name of object
);
Parameter

pszItem

[in] Pointer to a zero-terminated wide character string (two bytes per character) containing the container’s name for the object.

Return Values

S_OK

The specified object is running.

S_FALSE

The object is not running.

MK_E_NOOBJECT

The parameter pszItem does not identify an object in this container.

Remarks

The item moniker implementation of IMoniker::IsRunning calls this method.

Notes to Implementers

Your implementation of IOleItemContainer::IsRunning should first determine whether pszItem identifies one of the container’s objects. If it does not, your implementation should return MK_E_NOOBJECT. If the object is not loaded, your implementation should return S_FALSE. If it is loaded, your implementation can call the OleIsRunning function to determine whether it is running.

If pszItem names a pseudo-object, your implementation can simply return S_OK because a pseudo-object is running whenever its container is running.

See Also

IMoniker::IsRunning


IOleLink

The IOleLink interface is the means by which a linked object provides its container with functions pertaining to linking. The most important of these functions is binding to the link source, that is, activating the connection to the document that stores the linked object’s native data. IOleLink also defines functions for managing information about the linked object, such as the location of the link source and the cached presentation data for the linked object.

A container application can distinguish between embedded objects and linked objects by querying for IOleLink; only linked objects implement IOleLink.

When to Implement

You do not have to implement this interface yourself; the system supplies an implementation of IOleLink that is suitable for all situations. This implementation is used automatically whenever you create or load a linked object.

When to Use

You must use IOleLink if you are writing a container application that allows its documents to contain linked objects. You primarily call IOleLink methods in order to implement the Links dialog box. If you use the OleUIEditLinks function to display the Links dialog box, your calls to IOleLink methods take place in your implementation of the IOleUILinkContainer interface.

Some IOleLink methods don’t have to be called directly. Instead, you call methods of IOleObject; the default linked object provides an implementation of IOleObject that often calls methods of IOleLink. For example, a container application typically activates a linked object by calling IOleObject::DoVerb, which in turn calls IOleLink::BindToSource.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleLink Methods	Description
SetUpdateOptions	Sets the update options.
GetUpdateOptions	Returns the update options.
SetSourceMoniker	Sets the moniker for the link source.
GetSourceMoniker	Returns the moniker for the link source.
SetSourceDisplayName	Sets the display name for the link source.
GetSourceDisplayName	Returns the display name for the link source.
BindToSource	Binds the moniker to the link source.
BindIfRunning	Binds the moniker if the source is running.
GetBoundSource	Returns a pointer to the link source if it’s running.
UnbindSource	Break connection to the link source.
Update	Update the cached views of the link source.
See Also

IOleObject, IOleUILinkContainer, OleUIEditLinks


IOleLink::BindIfRunning

Activates the connection between the linked object and the link source if the link source is already running.

HRESULT BindIfRunning(void);

Return Values

S_OK

The link source was bound.

S_FALSE

The link source is not running.

CreateBindCtx, IMoniker::IsRunning, or IOleLink::BindToSource errors

Binding the moniker might require calling these functions, therefore, errors generated by these functions may be returned.

Remarks

You typically do not need to call IOleLink::BindIfRunning. This method is primarily called by the linked object.

Notes on Provided Implementation

The linked object’s implementation of IOleLink::BindIfRunning checks the Running Object Table (ROT) to determine whether the link source is already running. It checks both the relative and absolute monikers. If the link source is running, IOleLink::BindIfRunning calls IOleLink::BindToSource to connect the linked object to the link source.

See Also

IOleLink::BindToSource


IOleLink::BindToSource

Activates the connection to the link source by binding the moniker stored within the linked object.

HRESULT BindToSource(

DWORD bindflags,	//Flag in case CLSID of link source is different
IBindCtx *pbc	//Pointer to bind context to be used
);
Parameters

bindflags

[in] Specifies how to proceed if the link source has a different CLSID from the last time it was bound. If this parameter is zero and the CLSIDs are different, the method fails and returns OLE_E_CLASSDIFF. If the OLELINKBIND_EVENIFCLASSDIFF value from the OLELINKBIND enumeration is specified and the CLSIDs are different, the method binds successfully and updates the CLSID stored in the linked object.

pbc

[in] Pointer to the IBindCtx interface on the bind context to be used in this binding operation. This parameter can be NULL. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the binding implementation should retrieve information about its environment. For more information, see IBindCtx.

Return Values

S_OK

The link source is bound.

OLE_E_CLASSDIFF

The link source was not bound because its CLSID has changed. This error is returned only if the OLELINKBIND_EVENIFCLASSDIFF flag is not specified in the bindflags parameter.

MK_E_NOOBJECT

The link source could not be found or (if the link source’s moniker is a composite) some intermediate object identified in the composite could not be found.

E_UNSPEC

The link’s moniker is NULL.

CreateBindCtx errors

Binding the moniker might require calling this function; therefore, this method may return errors generated by this function.

Remarks

Notes to Callers

Typically, your container application does not need to call the IOleLink::BindToSource method directly. When it’s necessary to activate the connection to the link source, your container typically calls IOleObject::DoVerb, IOleObject::Update, or IOleLink::Update. The linked object’s implementation of these methods calls IOleLink::BindToSource. Your container can also call the OleRun function, which — when called on a linked object — calls IOleLink::BindToSource.

In each of the examples listed previously, in which IOleLink::BindToSource is called indirectly, the bindflags parameter is set to zero. Consequently, these calls can fail with the OLE_E_CLASSDIFF error if the class of the link source is different from what it was the last time the linked object was bound. This could happen, for example, if the original link source was an embedded Lotus spreadsheet that an end user had subsequently converted (using the Change Type dialog box) to an Excel spreadsheet.

If you want your container to bind even though the link source now has a different CLSID, you can call IOleLink::BindToSource directly and specify OLELINKBIND_EVENIFCLASSDIFF for the bindflags parameter. This call binds to the link source and updates the link object’s CLSID. Alternatively, your container can delete the existing link and use the OleCreateLink function to create a new linked object.

Notes on Provided Implementation

The linked object caches the interface pointer to the link source acquired during binding.

The linked object’s IOleLink::BindToSource implementation first tries to bind using a moniker consisting of the compound document’s moniker composed with the link source’s relative moniker. If successful, it updates the link’s absolute moniker. Otherwise, it tries to bind using the absolute moniker, updating the relative moniker if successful.

If IOleLink::BindToSource binds to the link source, it calls the compound document’s IOleContainer::LockContainer implementation to keep the containing compound document alive while the link source is running. IOleLink::BindToSource also calls the IOleObject::Advise and IDataObject::DAdvise implementations of the link source to set up advisory connections. The IOleLink::UnbindSource implementation unlocks the container and deletes the advisory connections.

See Also

IDataObject::DAdvise, IOleContainer::LockContainer, IOleLink::Update, IOleLink::UnbindSource, IOleObject::Advise, IOleObject::DoVerb, IOleObject::Update, OleRun


IOleLink::GetBoundSource

Returns an IUnknown pointer to the link source if the connection is currently active.

HRESULT GetBoundSource(

IUnknown **ppunk	//Indirect pointer to location of the link source
);
Parameter

ppunk

[out] When successful, indirect pointer to the location of the IUnknown interface on the link source. In this case, the implementation must call IUnknown::AddRef on the parameter; it is the caller’s responsibility to call IUnknown::Release. If an error occurs, the implementation sets ppunk to NULL.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

A pointer was returned successfully.

Remarks

You typically do not need to call IOleLink::GetBoundSource.


IOleLink::GetSourceDisplayName

Retrieves the display name of the link source of the linked object.

HRESULT GetSourceDisplayName(

LPOLESTR *ppszDisplayName	//Indirect pointer to string containing display name of link source
);
Parameter

ppszDisplayName

[out] Indirect pointer to the location of a zero-terminated wide character string (two bytes per character) containing the display name of the link source. If an error occurs, ppszDisplayName is set to NULL; otherwise, the implementation must use IMalloc::Alloc to allocate the string returned in ppszDisplayName, and the caller is responsible for calling IMalloc::Free to free it. Both caller and called use the allocator returned by CoGetMalloc.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The display name was successfully retrieved.

CreateBindCtx and IMoniker::GetDisplayName errors

Retrieving the display name requires calling these functions; therefore, this method may return errors generated by these functions.

Remarks

Notes to Callers

Your container application can call IOleLink::GetSourceDisplayName in order to display the current source of a link.

The current source of a link is displayed in the Links dialog box. If you use the OleUIEditLinks function to display the Links dialog box, you must implement the IOleUILinkContainer interface. The dialog box calls your implementations of IOleUILinkContainer::GetLinkSource to get the string it should display. Your implementation of that method can call IOleLink::GetSourceDisplayName.

Notes on Provided Implementation

The linked object’s implementation of IOleLink::GetSourceDisplayName calls IOleLink::GetSourceMoniker to get the link source moniker, and then calls IMoniker::GetDisplayName to get that moniker’s display name. This operation is potentially expensive because it might require binding the moniker. All of the system-supplied monikers can return a display name without binding, but there is no guarantee that other moniker implementations can. Instead of making repeated calls to IOleLink::GetSourceDisplayName, your container application can cache the name and update it whenever the link source is bound.

See Also

IOleLink::SetSourceDisplayName, IOleUILinkContainer, IMoniker::GetDisplayName, OleUIEditLinks


IOleLink::GetSourceMoniker

Retrieves the moniker identifying the link source of a linked object.

HRESULT GetSourceMoniker(

IMoniker **ppmk	//Indirect pointer to a moniker identifying link source
);
Parameter

ppmk

[out] When successful, indirect pointer to the IMoniker interface on an absolute moniker that identifies the link source. In this case, the implementation must call IUnknown::AddRef on the parameter; it is the caller’s responsibility to call IUnknown::Release. May be NULL if an error occurs.

Return Values

S_OK

The moniker was returned successfully.

MK_E_UNAVAILABLE

No moniker is available.

Remarks

Notes to Callers

Your container application can call IOleLink::GetSourceMoniker to display the current source of a link in the Links dialog box. Note that this requires your container to use the IMoniker::GetDisplayName method to get the display name of the moniker. If you’d rather get the display name directly, your container can call IOleLink::GetSourceDisplayName instead of IOleLink::GetSourceMoniker.

If you use the OleUIEditLinks function to display the Links dialog box, you must implement the IOleUILinkContainer interface. The dialog box calls your implementations of IOleUILinkContainer::GetLinkSource to get the string it should display. Your implementation of that method can call IOleLink::GetSourceMoniker.

Notes on Provided Implementation

The linked object stores both an absolute and a relative moniker for the link source. If the relative moniker is non-NULL and a moniker is available for the compound document, IOleLink::GetSourceMoniker returns the moniker created by composing the relative moniker onto the end of the compound document’s moniker. Otherwise, it returns the absolute moniker or, if an error occurs, NULL.

The container specifies the absolute moniker when it calls one of the OleCreateLink functions to create a link. The application can call IOleLink::SetSourceMoniker or IOleLink::SetSourceDisplayName to change the absolute moniker. In addition, the linked object automatically updates the monikers whenever it successfully binds to the link source, or when it is bound to the link source and it receives a rename notification through the IAdviseSink::OnRename method.

See Also

IOleLink::SetSourceDisplayName, IOleLink::SetSourceMoniker


IOleLink::GetUpdateOptions

Retrieves a value indicating how often the linked object updates its cached data.

HRESULT GetUpdateOptions(

DWORD *pdwUpdateOpt	//Pointer to update option
);
Parameter

pdwUpdateOpt

[out] Pointer to a DWORD that specifies the current value for the linked object’s update option, indicating how often the linked object updates the cached data for the linked object. The legal values for pdwUpdateOpt are taken from the enumeration OLEUPDATE.

Return Value

S_OK

The update option was retrieved successfully.

Remarks

Notes to Callers

Your container application should call IOleLink::GetUpdateOptions to display the current update option for a linked object.

A linked object’s current update option is displayed in the Links dialog box. If you use the OleUIEditLinks function to display the Links dialog box, you must implement the IOleUILinkContainer interface. The dialog box calls your implementation of IOleUILinkContainer::GetLinkUpdateOptions to determine which update option it should display. Your implementation of that method should call IOleLink::GetUpdateOptions to retrieve the current update option.

See Also

IOleLink::SetUpdateOptions, IOleUILinkContainer, OleUIEditLinks


IOleLink::SetSourceDisplayName

Specifies the new link source of a linked object using a display name.

HRESULT SetSourceDisplayName(

LPCOLESTR pszStatusText	//Pointer to display name of new link source
);
Parameter

pszStatusText

[in] Pointer to the display name of the new link source. It may not be NULL.

Return Values

S_OK

The display name was set successfully.

MkParseDisplayName errors

Setting the display name requires calling this function; therefore, this method may return errors generated by this function.

Remarks

Notes to Callers

Your container application can call IOleLink::SetSourceDisplayName when the end user changes the source of a link or breaks a link. Note that this requires the linked object to create a moniker out of the display name. If you’d rather parse the display name into a moniker yourself, your container can call IOleLink::SetSourceMoniker instead of IOleLink::SetSourceDisplayName.

If you use the OleUIEditLinks function to display the Links dialog box, you must implement the IOleUILinkContainer interface. The dialog box calls your implementations of IOleUILinkContainer::SetLinkSource and IOleUILinkContainer::CancelLink. Your implementation of these methods can call IOleLink::SetSourceDisplayName.

If your container application is immediately going to bind to a newly specified link source, you should call MkParseDisplayName and IOleLink::SetSourceMoniker instead, and then call IOleLink::BindToSource using the bind context from the parsing operation. By reusing the bind context, you can avoid redundant loading of objects that might otherwise occur.

Notes on Provided Implementation

The contract for IOleLink::SetSourceDisplayName does not specify when the linked object will parse the display name into a moniker. The parsing can occur before IOleLink::SetSourceDisplayName returns, or the linked object can store the display name and parse it only when it needs to bind to the link source. Note that parsing the display name is potentially an expensive operation because it might require binding to the link source. The provided implementation of IOleLink::SetSourceDisplayName parses the display name and then releases the bind context used in the parse operation. This can result in running and then stopping the link source server.

If the linked object is bound to the current link source, the implementation of IOleLink::SetSourceDisplayName breaks the connection.

For more information on how the linked object stores and uses the moniker to the link source, see IOleLink::SetSourceMoniker.

See Also

IOleLink::SetSourceMoniker, IOleUILinkContainer, MkParseDisplayName, OleUIEditLinks


IOleLink::SetSourceMoniker

Specifies the new link source of a linked object using a moniker.

HRESULT SetSourceMoniker(

IMoniker *pmk,	//Pointer to a moniker identifying new link source
REFCLSID rclsid	//CLSID of link source
);
Parameters

pmk

[in] Pointer to the IMoniker interface on a moniker that identifies the new link source of the linked object. A value of NULL breaks the link.

rclsid

[in] Specifies the CLSID of the link source that the linked object should use to access information about the linked object when it is not bound.

Return Value

S_OK

The moniker was set successfully.

Remarks

Notes to Callers

Your container application can call IOleLink::SetSourceMoniker when the end user changes the source of a link or breaks a link. Note that this requires your container to use the MkParseDisplayName function to create a moniker out of the display name that the end user enters. If you’d rather have the linked object perform the parsing, your container can call IOleLink::SetSourceDisplayName instead of IOleLink::SetSourceMoniker.

The end user changes the source of a link or breaks a link using the Links dialog box. If you use the OleUIEditLinks function to display the Links dialog box, you must implement the IOleUILinkContainer interface. The dialog box calls your implementations of IOleUILinkContainer::SetLinkSource and IOleUILinkContainer::CancelLink; your implementation of these methods can call IOleLink::SetSourceMoniker.

If the linked object is currently bound to its link source, the linked object’s implementation of IOleLink::SetSourceMoniker closes the link before changing the moniker.

Notes on Provided Implementation

The IOleLink contract does not specify how the linked object stores or uses the link source moniker. The provided implementation stores the absolute moniker specified when the link is created or when the moniker is changed; it then computes and stores a relative moniker. Future implementations might manage monikers differently to provide better moniker tracking. The absolute moniker provides the complete path to the link source. The linked object uses this absolute moniker and the moniker of the compound document to compute a relative moniker that identifies the link source relative to the compound document that contains the link.

pmkCompoundDoc->RelativePathTo(pmkAbsolute, ppmkRelative)

When binding to the link source, the linked object first tries to bind using the relative moniker. If that fails, it tries to bind the absolute moniker.

When the linked object successfully binds using either the relative or the absolute moniker, it automatically updates the other moniker. The linked object also updates both monikers when it is bound to the link source and it receives a rename notification through the IAdviseSink::OnRename method. A container application can also use the IOleLink::SetSourceDisplayName method to change a link’s moniker.

The linked object’s implementation of IPersistStorage::Save saves both the relative and the absolute moniker.

See Also

IOleLink::GetSourceMoniker, IOleLink::SetSourceDisplayName, IOleUILinkContainer, OleUIEditLinks


IOleLink::SetUpdateOptions

Specifies how often a linked object should update its cached data.

HRESULT SetUpdateOptions(

DWORD dwUpdateOpt	//Update option
);
Parameter

dwUpdateOpt

[in] Specifies how often a linked object should update its cached data. The legal values for dwUpdateOpt are taken from the enumeration OLEUPDATE.

Return Values

This method supports the standard return value E_INVALIDARG, as well as the following:

S_OK

The update option was successfully set.

Remarks

Notes to Callers

Your container application should call IOleLink::SetUpdateOptions when the end user changes the update option for a linked object.

The end user selects the update option for a linked object using the Links dialog box. If you use the OleUIEditLinks function to display this dialog box, you must implement the IOleUILinkContainer interface. The dialog box calls your IOleUILinkContainer::SetLinkUpdateOptions method to specify the update option chosen by the end user. Your implementation of this method should call the IOleLink::SetUpdateOptions method to pass the selected option to the linked object.

Notes on Provided Implementation

The default update option is OLEUDPATE_ALWAYS. The linked object’s implementation of IPersistStorage::Save saves the current update option.

If OLEUDPATE_ALWAYS is specified as the update option, the linked object updates the link’s caches in the following situations:

•	When the update option is changed from manual to automatic, if the link source is running.

•	Whenever the linked object binds to the link source.

•	Whenever the link source is running and the linked object’s IOleObject::Close, IPersistStorage::Save, or IAdviseSink::OnSave implementations are called.

For both manual and automatic links, the linked object updates the cache whenever the container application calls IOleObject::Update or IOleLink::Update.

See Also

IOleObject::Update, IOleLink::GetUpdateOptions, IOleLink::Update, IOleUILinkContainer, OleUIEditLinks


IOleLink::UnbindSource

Deactivates the connection between a linked object and its link source.

HRESULT UnbindSource(void);

Return Value

S_OK

The connection was deactivated.

Remarks

You typically do not call IOleLink::UnbindSource directly. When it’s necessary to deactivate the connection to the link source, your container typically calls IOleObject::Close or IUnknown::Release; the linked object’s implementation of these methods calls IOleLink::UnbindSource. The linked object’s IAdviseSink::OnClose implementation also calls IOleLink::UnbindSource.

Notes on Provided Implementation

The linked object’s implementation of IOleLink::UnbindSource does nothing if the link source is not currently bound. If the link source is bound, IOleLink::UnbindSource calls the link source’s IOleObject::Unadvise and IDataObject::DUnadvise implementations to delete the advisory connections to the link source. The IOleLink::UnbindSource method also calls the compound document’s IOleClientSite::LockContainer implementation to unlock the containing compound document. This undoes the lock on the container and the advisory connections that were established in IOleLink::BindToSource. IOleLink::UnbindSource releases all the linked object’s interface pointers to the link source.

See Also

IAdviseSink::OnClose, IDataObject::DUnadvise, IOleObject::Close, IOleObject::Unadvise, IOleLink::BindToSource


IOleLink::Update

Updates the compound document’s cached data for a linked object. This involves binding to the link source, if it is not already bound.

HRESULT Update(

IBindCtx *pbc	//Pointer to bind context to be used
);
Parameter

pbc

[in] Pointer to the IBindCtx interface on the bind context to be used in binding the link source. This parameter can be NULL. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the binding implementation should retrieve information about its environment. For more information, see IBindCtx.

Return Values

S_OK

All caches were updated successfully.

CACHE_E_NOCACHE_UPDATED

The bind operation worked but no caches were updated.

CACHE_S_SOMECACHES_NOTUPDATED

The bind operation worked but not all caches were updated.

OLE_E_CANT_BINDTOSOURCE

Unable to bind to the link source.

Remarks

Notes to Callers

Your container application should call IOleLink::Update if the end user updates the cached data for a linked object.

The end user can update the cached data for a linked object by choosing the Update Now button in the Links dialog box. If you use the OleUIEditLinks function to display the Links dialog box, you must implement the IOleUILinkContainer interface. The dialog box calls your implementations of IOleUILinkContainer::UpdateLink when the end user chooses the Update Now button. Your implementation of that method can call IOleLink::Update.

Your container application can also call IOleObject::Update to update a linked object, because that method — when called on a linked object — calls IOleLink::Update.

This method updates both automatic links and manual links. For manual links, calling IOleLink::Update or IOleObject::Update is the only way to update the caches. For more information on automatic and manual links, see IOleLink::SetUpdateOptions.

Notes on Provided Implementation

If pbc is non-NULL, the linked object’s implementation of IOleLink::Update calls IBindCtx::RegisterObjectBound to register the bound link source. This ensures that the link source remains running until the bind context is released.

The current caches are left intact if the link source cannot be bound.

See Also

IBindCtx::RegisterObjectBound, IOleLink::SetUpdateOptions, IOleObject::Update, IOleUILinkContainer, OleUIEditLinks


IOleObject

The IOleObject interface is the principal means by which an embedded object provides basic functionality to, and communicates with, its container.

When to Implement

An object application must implement this interface, along with at least IDataObject and IPersistStorage, for each type of embedded object that it supports. Although this interface contains 21 methods, only three are nontrivial to implement and must be fully implemented: DoVerb, SetHostNames, and Close. Six of the methods provide optional functionality, which, if not desired, can be implemented to return E_NOTIMPL: SetExtent, InitFromData, GetClipboardData, SetColorScheme, SetMoniker, and GetMoniker. The latter two methods are useful mainly for enabling links to embedded objects.

When to Use

Call the methods of this interface to enable a container to communicate with an embedded object. A container must call DoVerb to activate an embedded object, SetHostNames to communicate the names of the container application and container document, and Close to move an object from a running to a loaded state. Calls to all other methods are optional.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IOleObject Methods	Description
SetClientSite	Informs object of its client site in container.
GetClientSite	Retrieves object’s client site.
SetHostNames	Communicates names of container application and container document.
Close	Moves object from running to loaded state.
SetMoniker	Informs object of its moniker.
GetMoniker	Retrieves object’s moniker.
InitFromData	Initializes embedded object from selected data.
GetClipboardData	Retrieves a data transfer object from the Clipboard.
DoVerb	Invokes object to perform one of its enumerated actions (“verbs”).
EnumVerbs	Enumerates actions (“verbs”) for an object.
Update	Updates an object.
IsUpToDate	Checks if object is up to date.
GetUserClassID	Returns an object’s class identifier.
GetUserType	Retrieves object’s user-type name.
SetExtent	Sets extent of object’s display area.
GetExtent	Retrieves extent of object’s display area.
Advise	Establishes advisory connection with object.
Unadvise	Destroys advisory connection with object.
EnumAdvise	Enumerates object’s advisory connections.
GetMiscStatus	Retrieves status of object.
SetColorScheme	Recommends color scheme to object application.


IOleObject::Advise

Establishes an advisory connection between a compound document object and the calling object’s advise sink, through which the calling object receives notification when the compound document object is renamed, saved, or closed.

HRESULT Advise(

IAdviseSink *pAdvSink,	//Pointer to advisory sink
DWORD *pdwConnection	//Pointer to a token
);
Parameters

pAdvSink

[in] Pointer to the IAdviseSink interface on the advise sink of the calling object.

pdwConnection

[out] Pointer to a DWORD token that can be passed to IOleObject::Unadvise to delete the advisory connection.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

Advisory connection is successfully established.

Remarks

The Advise method sets up an advisory connection between an object and its container, through which the object informs the container’s advise sink of close, save, rename, and link-source change events in the object. A container calls this method, normally as part of initializing an object, to register its advisory sink with the object. In return, the object sends the container compound-document notifications by calling IAdviseSink or IAdviseSink2.

If container and object successfully establish an advisory connection, the object receiving the call returns a nonzero value through pdwConnection to the container. If the attempt to establish an advisory connection fails, the object returns zero. To delete an advisory connection, the container calls IOleObject::Unadvise and passes this nonzero token back to the object.

An object can delegate the job of managing and tracking advisory events to an OLE advise holder, to which you obtain a pointer by calling CreateOleAdviseHolder. The returned IOleAdviseHolder interface has three methods for sending advisory notifications, as well as Advise, Unadvise, and EnumAdvise methods that are identical to those for IOleObject. Calls to IOleObject:Advise, Unadvise, or EnumAdvise are delegated to corresponding methods in the advise holder.

To destroy the advise holder, simply call Release on the IOleAdviseHolder interface.

See Also

CreateOleAdviseHolder, IOleObject::UnAdvise, IOleObject::EnumAdvise, IOleAdviseHolder::Advise


IOleObject::Close

Changes an embedded object from the running to the loaded state. Disconnects a linked object from its link source.

HRESULT Close(

DWORD dwSaveOption	//Indicates whether to save object before closing
);
Parameter

dwSaveOption

[in] DWORD that indicates whether the object is to be saved as part of the transition to the loaded state. Valid values are taken from the enumeration OLECLOSE.

Note  The OLE 2 user model recommends that object applications do not prompt users before saving linked or embedded objects, including those activated in place. This policy represents a change from the OLE 1 user model, in which object applications always prompt the user to decide whether to save changes.

Return Values

S_OK

The object closed successfully.

OLE_E_PROMPTSAVECANCELLED

The user was prompted to save but chose the Cancel button from the prompt message box.

Remarks

Notes to Callers

A container application calls IOleObject::Close when it wants to move the object from a running to a loaded state. Following such a call, the object still appears in its container but is not open for editing. Calling IOleObject::Close on an object that is loaded but not running has no effect. Closing a linked object simply means disconnecting it.

Notes to Implementers

Upon receiving a call to IOleObject::Close, a running object should do the following:

•	If the object has been changed since it was last opened for editing, it should request to be saved, or not, according to instructions specified in dwSaveOption. If the option is to save the object, then it should call its container’s IOleClientSite::SaveObject interface.

•	If the object has IDataObject::DAdvise connections with ADVF_DATAONSTOP flags, then it should send an OnDataChange notification. See IDataObject::DAdvise for details.

•	If the object currently owns the Clipboard, it should empty it by calling OleFlushClipboard.

•	If the object is currently visible, notify its container by calling IOleClientSite::OnShowWindow with the fshow argument set to FALSE.

•	Send IAdvise::OnClose notifications to appropriate advise sinks.

•	Finally, forcibly cut off all remoting clients by calling CoDisconnectObject.

If the object application is a local server (an EXE rather than a DLL), closing the object should also shut down the object application unless the latter is supporting other running objects or has another reason to remain in the running state. Such reasons might include the presence of IClassFactory::LockServer locks, end-user control of the application, or the existence of other open documents requiring access to the application.

Calling IOleObject::Close on a linked object disconnects it from, but does not shut down, its source application. A source application that is visible to the user when the object is closed remains visible and running after the disconnection and does not send an OnClose notification to the link container.

See Also

CoDisconnectObject, IAdviseSink::OnClose, IClassFactory::LockServer, IDataObject::DAdvise, IOleClientSite::OnShowWindow, IOleClientSite::SaveObject, OLECLOSE, OleFlushClipboard


IOleObject::DoVerb

Requests an object to perform an action in response to an end-user’s action. The possible actions are enumerated for the object in IOleObject::EnumVerbs.

HRESULT DoVerb(

LONG iVerb,	//Value representing verb to be performed
LPMSG lpmsg,	//Pointer to structure that describes Windows message
IOleClientSite *pActiveSite,	//Pointer to active client site
LONG lindex,	//Reserved
HWND hwndParent,	//Handle of window containing the object
LPCRECT lprcPosRect	//Pointer to object’s display rectangle
);
Parameters

iVerb

[in] Number assigned to the verb in the OLEVERB structure returned by IOleObject::EnumVerbs.

lpmsg

[in] Pointer to the MSG structure describing the event (such as a double-click) that invoked the verb. The caller should pass the MSG structure unmodified, without attempting to interpret or alter the values of any of the fields of lpmsg.

pActiveSite

[in] Pointer to the IOleClientSite interface on the object’s active client site, where the event occurred that invoked the verb.

lindex

[in] Reserved for future use; must be zero.

hwndParent

[in] Handle of the document window containing the object. This and lprcPosRect together make it possible to open a temporary window for an object, where hwndParent is the parent window in which the object’s window is to be displayed, and lprcPosRect defines the area available for displaying the object window within that parent. A temporary window is useful, for example, to a multimedia object that opens itself for playback but not for editing.

lprcPosRect

[in] Pointer to the RECT structure containing the coordinates, in pixels, that define an object’s bounding rectangle in hwndParent. This and hwndParent together enable opening multimedia objects for playback but not for editing.

Return Values

S_OK

Object successfully invoked specified verb.

OLE_E_NOT_INPLACEACTIVE

iVerb set to OLEIVERB_UIACTIVATE or OLEIVERB_INPLACEACTIVATE and object is not already visible.

OLE_E_CANT_BINDTOSOURCE

The object handler or link object cannot connect to the link source.

DV_E_LINDEX

Invalid lindex.

OLEOBJ_S_CANNOT_DOVERB_NOW

The verb is valid, but in the object’s current state it cannot carry out the corresponding action.

OLEOBJ_S_INVALIDHWND

DoVerb was successful but hwndParent is invalid.

OLEOBJ_E_NOVERBS

The object does not support any verbs.

OLEOBJ_S_INVALIDVERB

Object does not recognize a positive verb number. Verb is treated as OLEIVERB_PRIMARY.

MK_E_CONNECT

Link source is across a network that is not connected to a drive on this machine.

OLE_E_CLASSDIFF

Class for source of link has undergone a conversion.

E_NOTIMPL

Object does not support in-place activation or does not recognize a negative verb number.

Remarks

A “verb” is an action that an OLE object takes in response to a message from its container. An object’s container, or a client linked to the object, normally calls IOleObject::DoVerb in response to some end-user action, such as double-clicking on the object. The various actions that are available for a given object are enumerated in an OLEVERB structure, which the container obtains by calling IOleObject::EnumVerbs. IOleObject::DoVerb matches the value of iVerb against the iVerb member of the structure to determine which verb to invoke.

Through IOleObject::EnumVerbs, an object, rather than its container, determines which verbs (i.e., actions) it supports. OLE 2 defines seven verbs that are available, but not necessarily useful, to all objects. In addition, each object can define additional verbs that are unique to it. The following table describes the verbs defined by OLE:

Verb	Description
OLEIVERB_PRIMARY (0L)	Specifies the action that occurs when an end user double-clicks the object in its container. The object, not the container, determines this action. If the object supports in-place activation, the primary verb usually activates the object in place.
OLEIVERB_SHOW (-1)	Instructs an object to show itself for editing or viewing. Called to display newly inserted objects for initial editing and to show link sources. Usually an alias for some other object-defined verb.
OLEIVERB_OPEN (-2)	Instructs an object, including one that otherwise supports in-place activation, to open itself for editing in a window separate from that of its container. If the object does not support in-place activation, this verb has the same semantics as OLEIVERB_SHOW.
OLEIVERB_HIDE (-3)	Causes an object to remove its user interface from the view. Applies only to objects that are activated in-place.
OLEIVERB_UIACTIVATE (-4)	Activates an object in place, along with its full set of user-interface tools, including menus, toolbars, and its name in the title bar of the container window. If the object does not support in-place activation, it should return E_NOTIMPL.
OLEIVERB_INPLACEACTIVATE (-5)	Activates an object in place without displaying tools, such as menus and toolbars, that end users need to change the behavior or appearance of the object. Single-clicking such an object causes it to negotiate the display of its user-interface tools with its container. If the container refuses, the object remains active but without its tools displayed.
OLEIVERB_DISCARDUNDOSTATE (-6)	Used to tell objects to discard any undo state that they may be maintaining without deactivating the object.
Note to Callers

Containers call IOleObject::DoVerb as part of initializing a newly created object. Before making the call, containers should first call IOleObject::SetClientSite to inform the object of its display location and IOleObject::SetHostNames to alert the object that it is an embedded object and to trigger appropriate changes to the user interface of the object application in preparation for opening an editing window.

Like the OleActivate function in OLE 1, IOleObject::DoVerb automatically runs the OLE server application. If an error occurs during verb execution, the object application is shut down.

If an end user invokes a verb by some means other than selecting a command from a menu (say, by double-clicking or, more rarely, single-clicking an object), the object’s container should pass a pointer (lpmsg) to a Windows MSG structure containing the appropriate message. For example, if the end user invokes a verb by double-clicking the object, the container should pass a MSG structure containing WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK, or WM_RBUTTONDBLCLK. If the container passes no message, lpmsg should be set to NULL. The object should ignore the hwnd member of the passed MSG structure, but can use all the other MSG members.

If the object’s embedding container calls IOleObject::DoVerb, the client-site pointer (pClientSite) passed to DoVerb is the same as that of the embedding site. If the embedded object is a link source, the pointer passed to DoVerb is that of the linking client’s client site.

When IOleObject::DoVerb is invoked on an OLE link, it may return OLE_E_CLASSDIFF or MK_CONNECTMANUALLY. The link object returns the former error when the link source has been subjected to some sort of conversion while the link was passive. The link object returns the latter error when the link source is located on a network drive that is not currently connected to the caller’s computer. The only way to connect a link under these conditions is to first call QueryInterface, ask for IOleLink, allocate a bind context, and run the link source by calling IOleLink::BindToSource.

Container applications that do not support general in-place activation can still use the hwndParent and lprcPosRect parameters to support in-place playback of multimedia files. Containers must pass valid hwndParent and lprcPosRect parameters to IOleObject::DoVerb.

Some code samples pass a lindex value of -1 instead of zero. The value -1 works but should be avoided in favor of zero. The lindex parameter is a reserved parameter, and for reasons of consistency Microsoft recommends assigning a zero value to all reserved parameters.

Notes to Implementers

In addition to the above verbs, an object can define in its OLEVERB structure additional verbs that are specific to itself. Positive numbers designate these object-specific verbs. An object should treat any unknown positive verb number as if it were the primary verb and return OLE_S_INVALIDVERB to the calling function. The object should ignore verbs with negative numbers that it does not recognize and return E_NOTIMPL.

If the verb being executed places the object in the running state, you should register the object in the Running Object Table (ROT) even if its server application doesn’t support linking. Registration is important because the object at some point may serve as the source of a link in a container that supports links to embeddings. Registering the object with the ROT enables the link client to get a pointer to the object directly, instead of having to go through the object's container. To perform the registration, call IOleClientSite::GetMoniker to get the full moniker of the object, call the GetRunningObjectTable function to get a pointer to the ROT, and then call IRunningObjectTable::Register.

Note  When the object leaves the running state, remember to revoke the object's registration with the ROT by calling IOleObject::Close. If the object's container document is renamed while the object is running, you should revoke the object's registration and re-register it with the ROT, using its new name. The container should inform the object of its new moniker either by calling IOleObject::SetMoniker or by responding to the object’s calling IOleClientSite::GetMoniker.

When showing a window as a result of DoVerb, it is very important for the object to explicitly call SetForegroundWindow on its editing window. This ensures that the object’s window will be visible to the user even if another process originally obscured it. For more information about SetForegroundWindow and SetActiveWindow, see the Win32 SDK.

See Also

GetRunningObjectTable, IOleClientSite::GetMoniker, IOleLink::BindToSource, IOleObject::Close, IOleObject::EnumVerbs, IOleObject::GetMoniker, IOleObject::SetMoniker, IRunningObjectTable::Register, OleRun, SetForegroundWindow, SetActiveWindow in Win32


IOleObject::EnumAdvise

Retrieves a pointer to an enumerator that can be used to enumerate the advisory connections registered for an object, so a container can know what to release prior to closing down.

HRESULT EnumAdvise(

IEnumSTATDATA **ppenumAdvise	//Indirect pointer to enumerator object
);
Parameter

ppenumAdvise

[out] When there are existing advisory connections, indirect pointer to the location of the IEnumSTATDATA interface on the enumerator object. If the object does not have any advisory connections, the value will be NULL. NULL will also be the value if the method returns an error. Each time an object receives a successful call to EnumAdvise, it must increase the reference count on the pointer it returns. It is the caller’s responsibility to call Release when it is done with the pointer.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

Enumerator returned successfully.

E_NOTIMPL

EnumAdvise is not implemented.

Remarks

The EnumAdvise method supplies an enumerator that provides a way for containers to keep track of advisory connections registered for their objects. A container normally would call this function so that it can instruct an object to release each of its advisory connections prior to closing down.

The enumerator to which you get access through IOleObject::EnumAdvise enumerates items of type STATDATA. Upon receiving the pointer, the container can then loop through STATDATA and call IOleObject::Unadvise for each enumerated connection.

The usual way to implement this function is to delegate the call to the IOleAdviseHolder interface. Only the pAdvise and dwConnection members of STATDATA are relevant for IOleObject::EnumAdvise.

See Also

IOleObject::Advise, IOleObject::UnAdvise


IOleObject::EnumVerbs

Exposes a pull-down menu listing the verbs available for an object in ascending order by verb number.

HRESULT EnumVerbs(

IEnumOleVerb **ppEnumOleVerb	//Indirect pointer to storage of enumerator object
);
Parameter

ppEnumOleVerb

[out] When successful, indirect pointer to where the IEnumOLEVERB interface on the new enumerator should be returned. Each time an object receives a call to EnumVerbs, it must increase the reference count on the pointer the method returns. It is the caller’s responsibility to call Release when it is done with the pointer. If an error is returned, this parameter must be set to NULL.

Return Values

S_OK

Verb(s) enumerated successfully.

OLE_S_USEREG

Delegate to the default handler to use the entries in the registry to provide the enumeration.

OLEOBJ_E_NOVERBS

Object does not support any verbs.

Remarks

Notes to Callers

Containers call this method to expose a pull-down menu of the verbs available for their embedded objects. You may want your container to call IOleObject::EnumVerbs each and every time such a menu is selected in order to enable such objects as media clips, whose verbs may change while they are running, to update their menus. The default verb for a media clip, for example, changes from “Play” before it is activated to “Stop” once it is running.

Notes to Implementers

The default handler’s implementation of IOleObject::EnumVerbs uses the registry to enumerate an object’s verbs. If an object application is to use the default handler’s implementation, it should return OLE_S_USEREG.

The enumeration returned is of type IEnumOLEVERB:

typedef Enum < OLEVERB > IEnumOLEVERB;

where OLEVERB is defined as:

typedef struct tagOLEVERB

{

    LONG    iVerb;

    LPOLESTR   lpszVerbName;

    DWORD   fuFlags;

    DWORD   grfAttribs;

} OLEVERB;

The following table describes the members of the OLEVERB structure:

OLEVERB Member	Description
iVerb	Verb number being enumerated. If the object supports OLEIVERB_OPEN, OLEIVERB_SHOW and/or OLEIVERB_HIDE (or another predefined verb), these will be the first verbs enumerated, since they have the lowest verb numbers.
lpszVerbName	Name of the verb.  In Windows, this value, along with optional embedded ampersand characters to indicate accelerator keys, can be passed to the AppendMenu function. On the Macintosh, the following metacharacters may be passed along with this value:
	•   ! marks the menu item with the subsequent character
	•   < sets the character style of the item
	•   ( disables the item.
	The metacharacters / and ^ are not permitted.
fuFlags	In Windows, a group of flags taken from the flag constants beginning with MF_ defined in AppendMenu. Containers should use these flags in building an object’s verb menu. All Flags defined in AppendMenu are supported except for:
	•   MF_BITMAP
	•   MF_OWNERDRAW
	•   MF_POPUP
grfAttribs	In Windows, a group of flag bits taken from the enumeration OLEVERBATTRIB. The flag OLEVERBATTRIB_NEVERDIRTIES indicates that executing this verb will not cause the object to become dirty and is therefore in need of saving to persistent storage. OLEVERBATTRIB_ONCONTAINERMENU indicates that this verb should be placed on the container’s menu of object verbs when the object is selected. OLEIVERB_HIDE, OLEIVERB_SHOW, and OLEIVERB_OPEN never have this value set.
For more information on the Windows AppendMenu function, see the Microsoft Win32 SDK.

See Also

IOleObject::DoVerb, OleRegEnumVerbs


IOleObject::GetClientSite

Obtains a pointer to an embedded object’s client site.

HRESULT GetClientSite(

IOleClientSite **ppClientSite	//Indirect pointer to storage of object’s client site
);
Parameter

ppClientSite

[out] Indirect pointer to an IOleClientSite interface on the object’s client site. If an object does not yet know its client site, or an error has occurred, this parameter must be set to NULL. Each time an object receives a call to GetClientSite, it must increase the reference count on the pointer the method returns. It is the caller’s responsibility to call Release when it is done with the pointer.

Return Value

S_OK

Client site pointer returned successfully.

Remarks

Link clients most commonly call the IOleObject::GetClientSite method in conjunction with the IOleClientSite::GetContainer method to traverse a hierarchy of nested objects. A link client calls IOleObject::GetClientSite to get a pointer to the link source’s client site. The client then calls IOleClientSite::GetContainer to get a pointer to the link source’s container. Finally, the client calls IOleContainer::QueryInterface to get IOleObject and IOleObject::GetClientSite to get the container’s client site within its container. By repeating this sequence of calls, the caller can eventually retrieve a pointer to the master container in which all the other objects are nested.

Notes to Callers

The returned client-site pointer will be NULL if an embedded object has not yet been informed of its client site. This will be the case with a newly loaded or created object when a container has passed a NULL client-site pointer to one of the object-creation helper functions but has not yet called IOleObject::SetClientSite as part of initializing the object.

See Also

IOleObject::SetClientSite


IOleObject::GetClipboardData

Retrieves a data object containing the current contents of the embedded object on which this method is called. Using the pointer to this data object, it is possible to create a new embedded object with the same data as the original.

HRESULT GetClipboardData(

DWORD dwReserved,	//Reserved
IDataObject **ppDataObject	//Indirect pointer to storage of data object
);
Parameters

dwReserved

[in] Reserved for future use; must be zero.

ppDataObject

[out] Indirect pointer to the IDataObject interface on the data object. If an error is returned, this parameter must be set to NULL. Each time an object receives a call to GetClipboardData, it must increase the reference count on the pointer that the method returns. It is the caller’s responsibility to call Release when it is done with the pointer.

Return Values

S_OK

The data transfer object is successfully returned.

E_NOTIMPL

GetClipboardData is not supported.

OLE_E_NOTRUNNING

The object is not running.

Remarks

You can use the GetClipboardData method to convert a linked object to an embedded object, in which case the container application would call IOleObject::GetClipboardData and then pass the data received to OleCreateFromData. This method returns a pointer to a data object that is identical to what would have been passed to the Clipboard by a standard copy operation.

Notes to Callers

If you want a stable snapshot of the current contents of an embedded object, call IOleObject::GetClipboardData. Should the data change, you will need to call the function again for an updated snapshot. If you want the caller to be informed of changes that occur to the data, call IDataObject::QueryInterface, then call IDataObject::DAdvise.

Notes to Implementers

If you implement this function, you must return an IDataObject pointer for an object whose data will not change.

See Also

IDataObject, IOleObject::InitFromData, IUnknown::QueryInterface, OleCreateFromData


IOleObject::GetExtent

Retrieves a running object’s current display size.

HRESULT GetExtent(

DWORD dwDrawAspect,	//Value indicating object aspect
SIZEL *psizel	//Pointer to storage of object size limit
);
Parameters

dwDrawAspect

[in] Value indicating the aspect of the object whose limit is to be retrieved; the value is obtained from the enumerations DVASPECT and from DVASPECT2. Note that newer objects and containers that support optimized drawing interfaces support the DVASPECT2 enumeration values. Older objects and containers that do not support optimized drawing interfaces may not support DVASPECT2. The most common value for this method is DVASPECT_CONTENT, which specifies a full rendering of the object within its container.

psizel

[out] Pointer to where the object’s size is to be returned.

Return Values

This method supports the standard return value E_INVALIDARG, as well as the following:

S_OK

Extent information successfully returned.

Remarks

A container calls IOleObject::GetExtent on a running object to retrieve its current display size. If the container can accommodate that size, it will normally do so because the object, after all, knows what size it should be better than the container does. A container normally makes this call as part of initializing an object.

The display size returned by IOleObject::GetExtent may differ from the size last set by IOleObject::SetExtent because the latter method dictates the object’s display space at the time the method is called but does not necessarily change the object’s native size, as determined by its application.

Note  This method must return the same size as DVASPECT_CONTENT for all the new aspects in DVASPECT2. IViewObject2::GetExtent must do the same thing.

If one of the new aspects is requested in dwAspect, this method can either fail or return the same rectangle as for the DVASPECT_CONTENT aspect.

Notes to Callers

Because a container can make this call only to a running object, the container must instead call IViewObject2::GetExtent if it wants to get the display size of a loaded object from its cache.

Notes to Implementers

Implementation consists of filling the sizel structure with an object’s height and width.

See Also

DVASPECT, DVASPECT2, IOleObject::SetExtent, IViewObject2::GetExtent


IOleObject::GetMiscStatus

Returns a value indicating the status of an object at creation and loading.

HRESULT GetMiscStatus(

DWORD dwAspect,	//Value indicating object aspect
DWORD *pdwStatus	//Pointer to storage of status information
);
Parameters

dwAspect

[in] Value indicating the aspect of an object about which status information is being requested. The value is obtained from the enumeration DVASPECT (see “FORMATETC Data Structure”).

pdwStatus

[out] Pointer to where the status information is returned. May not be NULL.

Return Values

S_OK

Status information returned successfully.

OLE_S_USEREG

Delegate the retrieval of miscellaneous status information to the default handler’s implementation of this method.

CO_E_CLASSNOTREG

There is no CLSID registered for the object.

CO_E_READREGDB

Error accessing the registry.

Remarks

A container normally calls IOleObject::GetMiscStatus when it creates or loads an object in order to determine how to display the object and what types of behaviors it supports.

Objects store status information in the registry. If the object is not running, the default handler’s implementation of IOleObject::GetMiscStatus retrieves this information from the registry. If the object is running, the default handler invokes IOleObject::GetMiscStatus on the object itself.

The information that is actually stored in the registry varies with individual objects. The status values to be returned are defined in the enumeration OLEMISC.

Notes to Implementers

Implementation normally consists of delegating the call to the default handler.

See Also

DVASPECT, FORMATETC, OLEMISC


IOleObject::GetMoniker

Retrieves an embedded object’s moniker, which the caller can use to link to the object.

HRESULT GetMoniker(

DWORD dwAssign,	//Specifies how moniker is assigned to object
DWORD dwWhichMoniker,	//Specifies which moniker is assigned
IMoniker **ppmk	//Indirect pointer to location of object’s moniker
);
Parameters

dwAssign

[in] Determines how the moniker is assigned to the object. Depending on the value of dwAssign, IOleObject::GetMoniker does one of the following:

•	Obtains a moniker only if one has already been assigned,

•	Forces assignment of a moniker, if necessary, in order to satisfy the call, or

•	Obtains a temporary moniker.

Values for dwAssign are specified in the enumeration OLEGETMONIKER.

Note  You cannot pass OLEGETMONIKER_UNASSIGN when calling IOleObject::GetMoniker. This value is valid only when calling IOleClientSite::GetMoniker.

dwWhichMoniker

[in] Specifies the form of the moniker being requested. Valid values are taken from the enumeration OLEWHICHMK.

ppmk

[out] Indirect pointer to the location of the IMonikerinterface on the object’s moniker. If an error is returned, this parameter must be set to NULL. Each time an object receives a call to GetMoniker, it must increase the reference count on the pointer the method returns. It is the caller’s responsibility to call Release when it is done with the pointer.

Remarks

The IOleObject::GetMoniker method returns an object’s moniker. Like IOleObject::SetMoniker, this method is important only in the context of managing links to embedded objects and even in that case is optional. A potential link client that requires an object’s moniker to bind to the object can call this method to obtain that moniker. The default implementation of IOleObject::GetMoniker calls the IOleClientSite::GetMoniker, returning E_UNEXPECTED if the object is not running or does not have a valid pointer to a client site.

See Also

CreateItemMoniker, IOleClientSite::GetMoniker, IOleObject::SetMoniker, OLEGETMONIKER, OLEWHICHMK


IOleObject::GetUserClassID

Returns an object’s class identifier, the CLSID corresponding to the string identifying the object to an end user.

HRESULT GetUserClassID(

CLSID *pClsid	//Pointer to the class identifier
);
Parameter

pClsid

[out] Pointer to the class identifier (CLSID) to be returned. An object’s CLSID is the binary equivalent of the user-type name returned by IOleObject::GetUserType.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

CLSID returned successfully.

Remarks

GetUserClassID returns the CLSID associated with the object in the registration database. Normally, this value is identical to the CLSID stored with the object, which is returned by IPersist::GetClassID. For linked objects, this is the CLSID of the last bound link source. If the object is running in an application different from the one in which it was created and for the purpose of being edited is emulating a class that the container application recognizes, the CLSID returned will be that of the class being emulated rather than that of the object’s own class.

See Also

IOleObject::GetUserType, IPersist::GetClassID, OleDoAutoConvert, OleGetAutoConvert, OleSetAutoConvert, GetConvertStg, SetConvertStg


IOleObject::GetUserType

Retrieves the user-type name of an object for display in user-interface elements such as menus, list boxes, and dialog boxes.

HRESULT GetUserType(

DWORD dwFormOfType,	//Specifies form of type name
LPOLESTR *pszUserType	//Indirect pointer to storage of string
);
Parameters

dwFormOfType

[in] Value specifying the form of the user-type name to be presented to users. Valid values are obtained from the USERCLASSTYPE enumeration.

pszUserType

[out] Indirect pointer to where the user-type string will be placed. The caller must free lpszUserType using the current IMalloc instance. If an error is returned, this parameter must be set to NULL.

Return Values

S_OK

The object’s user-type name is successfully returned.

OLE_S_USEREG

Delegate to the default handler’s implementation using the registry to provide the requested information.

Remarks

Containers call IOleObject::GetUserType in order to represent embedded objects in list boxes, menus, and dialog boxes by their normal, user-recognizable names. Examples include “Word Document,” “Excel Chart,” and “Paintbrush Object.” The information returned by IOleObject::GetUserType is the user-readable equivalent of the binary class identifier returned by IOleObject::GetUserClassID.

Notes to Callers

The default handler’s implementation of IOleObject::GetUserType uses the object’s class identifier (the pClsid parameter returned by IOleObject::GetUserClassID) and the dwFormOfType parameter together as a key into the registry. If an entry is found that matches the key exactly, then the user type specified by that entry is returned. If only the CLSID part of the key matches, then the lowest-numbered entry available (usually the full name) is used. If the CLSID is not found, or there are no user types registered for the class, the user type currently found in the object’s storage is used.

You should not cache the string returned from GetUserType. Instead, call this method each and every time the string is needed. This guarantees correct results when the embedded object is being converted from one type into another without the caller’s knowledge. Calling this method is inexpensive because the default handler implements it using the registry.

Notes to Implementers

You can use the implementation provided by the default handler by returning OLE_S_USEREG as your application’s implementation of this method. If the user type name is an empty string, the message “Unknown Object” is returned.

You can call the OLE helper function OleRegGetUserType to return the appropriate user type.

See Also

IOleObject::SetHostNames, IOleObject::GetUserClassID, OleRegGetUserType, ReadFmtUserTypeStg, USERCLASSTYPE


IOleObject::InitFromData

Initializes a newly created object with data from a specified data object, which can reside either in the same container or on the Clipboard.

HRESULT InitFromData(

IDataObject *pDataObject,	//Pointer to data object
BOOL fCreation,	//Specifies how object is created
DWORD dwReserved	//Reserved
);
Parameters

pDataObject

[in] Pointer to the IDataObject interface on the data object from which the initialization data is to be obtained. This parameter can be NULL, which indicates that the caller wants to know if it is worthwhile trying to send data; that is, whether the container is capable of initializing an object from data passed to it. The data object to be passed can be based on either the current selection within the container document or on data transferred to the container from an external source.

fCreation

[in] TRUE indicates the container is inserting a new object inside itself and initializing that object with data from the current selection; FALSE indicates a more general programmatic data transfer, most likely from a source other than the current selection.

dwReserved

[in] Reserved for future use; must be zero.

Return Values

S_OK

If pDataObject is not NULL, the object successfully attempted to initialize itself from the provided data; if pDataObject is NULL, the object is able to attempt a successful initialization.

S_FALSE

If pDataObject is not NULL, the object made no attempt to initialize itself; if pDataObject is NULL, the object cannot attempt to initialize itself from the data provided.

E_NOTIMPL

The object does not support InitFromData.

OLE_E_NOTRUNNING

The object is not running and therefore cannot perform the operation.

Remarks

This method enables a container document to insert within itself a new object whose content is based on a current data selection within the container. For example, a spreadsheet document may want to create a graph object based on data in a selected range of cells.

Using this method, a container can also replace the contents of an embedded object with data transferred from another source. This provides a convenient way of updating an embedded object.

Notes to Callers

Following initialization, the container should call IOleObject::GetMiscStatus to check the value of the OLEMISC_INSERTNOTREPLACE bit. If the bit is on, the new object inserts itself following the selected data. If the bit is off, the new object replaces the selected data.

Notes to Implementers

A container specifies whether to base a new object on the current selection by passing either TRUE or FALSE to the fCreation parameter.

If fCreation is TRUE, the container is attempting to create a new instance of an object, initializing it with the selected data specified by the data object.

If fCreation is FALSE, the caller is attempting to replace the object’s current contents with that pointed to by pDataObject. The usual constraints that apply to an object during a paste operation should be applied here. For example, if the type of the data provided is unacceptable, the object should fail to initialize and return S_FALSE.

If the object returns S_FALSE, it cannot initialize itself from the provided data.

See Also

IOleObject::GetMiscStatus, IDataObject::SetData


IOleObject::IsUpToDate

Checks recursively whether or not an object is up to date.

HRESULT IsUpToDate();

Return Values

S_OK

Object is up to date.

S_FALSE

Object is not up to date.

OLE_E_UNAVAILABLE

Status of object cannot be determined in a timely manner.

Remarks

The IsUpToDate method provides a way for containers to check recursively whether or not all objects are up to date. That is, when the container calls this method on the first object, the object in turn calls it for all its own objects, and they in turn for all of theirs, until all objects have been checked.

Notes to Implementers

Because of the recursive nature of IOleObject:IsUpToDate, determining whether an object is out-of-date, particularly one containing one or more other objects, can be as time-consuming as simply updating the object in the first place. If you would rather avoid lengthy queries of this type, make sure that IOleObject::IsUpToDate returns OLE_E_UNAVAILABLE. In cases where the object to be queried is small and contains no objects itself, thereby making an efficient query possible, this method can return either S_OK or S_FALSE.

See Also

IOleObject::UpDate


IOleObject::SetClientSite

Informs an embedded object of its display location, called a “client site,” within its container.

HRESULT SetClientSite(

IOleClientSite *pClientSite	//Pointer to an embedded object’s client site
);
Parameter

pClientSite

[in] Pointer to the IOleClientSite interface on the container application’s client-site.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

Client site successfully set.

Remarks

Within a compound document, each embedded object has its own client site  — the place where it is displayed and through which it receives information about its storage, user interface, and other resources. IOleObject::SetClientSite is the only method enabling an embedded object to obtain a pointer to its client site.

Notes to Callers

A container can notify an object of its client site either at the time the object is created or, subsequently, when the object is initialized.

When creating or loading an object, a container may pass a client-site pointer (along with other arguments) to one of the following helper functions: OleCreate, OleCreateFromFile, OleCreateFromData or OleLoad. These helper functions load an object handler for the new object and call IOleObject::SetClientSite on the container’s behalf before returning a pointer to the new object.

Passing a client-site pointer informs the object handler that the client site is ready to process requests. If the client site is unlikely to be ready immediately after the handler is loaded, you may want your container to pass a NULL client-site pointer to the helper function. The NULL pointer says that that no client site is available and thereby defers notifying the object handler of the client site until the object is initialized. In response, the helper function returns a pointer to the object, but upon receiving that pointer the container must call SetClientSite as part of initializing the new object.

Notes to Implementers

Implementation consists simply of incrementing the reference count on, and storing, the pointer to the client site.

See Also

IOleClientSite, IOleObject::GetClientSite, OleCreate, OleCreateFromFile, OleCreateFromData, OleLoad


IOleObject::SetColorScheme

Specifies the color palette that the object application should use when it edits the specified object.

HRESULT SetColorScheme(

LOGPALETTE *pLogpal	//Pointer to a structure
);
Parameter

pLogpal

[in] Pointer to a LOGPALETTE structure that specifies the recommended palette.

Return Values

S_OK

Color palette received successfully.

E_NOTIMPL

Object does not support setting palettes.

OLE_E_PALETTE

Invalid LOGPALETTE structure pointed to by lpLogPal.

OLE_E_NOTRUNNING

Object must be running to perform this operation.

Remarks

The IOleObject::SetColorScheme method sends the container application’s recommended color palette to the object application, which is not obliged to use it.

Notes to Implementers

Upon receiving the palette, the object application should:

1.	Allocate and fill in its own LOGPALETTE structure with the colors specified in the container application’s LOGPALETTE structure.

2.	Call CreatePalette to create a palette from the resulting LOGPALETTE structure. This palette can be used to render objects and color menus as the user edits objects in the document.

The first palette entry in the LOGPALETTE structure specifies the foreground color recommended by the container. The second palette entry specifies the recommended background color. The first half of the remaining palette entries are fill colors and the second half are colors for the lines and text.

Container applications typically specify an even number of palette entries. If a container specifies an odd number of entries, the object application should assume that the first half of the total entries plus one designate fill colors, while the remainder designate line and text colors. For example, if there are five entries, the first three should be interpreted as fill colors and the last two as line and text colors.


IOleObject::SetExtent

Informs an object of how much display space its container has assigned it.

HRESULT SetExtent(

DWORD dwDrawAspect,	//DVASPECT value
SIZEL  *psizel	//Pointer to size limit for object
);
Parameters

dwDrawAspect

[in] DWORD that describes which form, or “aspect,” of an object is to be displayed. The object’s container obtains this value from the enumeration DVASPECT (refer to the FORMATETC enumeration). The most common aspect is DVASPECT_CONTENT, which specifies a full rendering of the object within its container. An object can also be rendered as an icon, a thumbnail version for display in a browsing tool, or a print version, which displays the object as it would be rendered using the File Print command.

psizel

[in] Pointer to the size limit for the object.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The object has resized successfully.

OLE_E_NOTRUNNING

The object is not running.

Remarks

A container calls IOleObject::SetExtent when it needs to dictate to an embedded object the size at which it will be displayed. Often, this call occurs in response to an end user resizing the object window. Upon receiving the call, the object, if possible, should recompose itself gracefully to fit the new window.

Whenever possible, a container seeks to display an object at its finest resolution, sometimes called the object’s native size. All objects, however, have a default display size specified by their applications, and in the absence of other constraints, this is the size they will use to display themselves. Since an object knows its optimum display size better than does its container, the latter normally requests that size from a running object by calling IOleObject::GetExtent. Only in cases where the container cannot accommodate the value returned by the object does it override the object’s preference by calling IOleObject::SetExtent.

Notes to Callers

You can call SetExtent on an object only when the object is running. If a container resizes an object while an object is not running, the container should keep track of the object’s new size but defer calling IOleObject::SetExtent until a user activates the object. If the OLEMISC_RECOMPOSEONRESIZE bit is set on an object, its container should force the object to run before calling OleObject::SetExtent.

As noted above, a container may want to delegate responsibility for setting the size of an object’s display site to the object itself, by calling IOleObject::GetExtent.

Notes to Implementers

You may want to implement this method so that your object rescales itself to match as closely as possible the maximum space available to it in its container.

If an object’s size is fixed, that is, if it cannot be set by its container, OleObject::SetExtent should return E_FAIL. This is always the case with linked objects, whose sizes are set by their link sources, not by their containers.

See Also

IAdviseSink::OnViewChange, IOleObject::GetExtent, IViewObject2::GetExtent


IOleObject::SetHostNames

Provides an object with the name of its container application and the compound document in which it is embedded.

HRESULT SetHostNames(

LPCOLESTR szContainerApp,	//Pointer to name of container application
LPCOLESTR szContainerObj	//Pointer to name of container document
);
Parameters

szContainerApp

[in] Pointer to the name of the container application in which the object is running.

szContainerObj

[in] Pointer to the name of the compound document that contains the object. If you do not wish to display the name of the compound document, you can set this parameter to NULL.

Return Value

S_OK

Window title information set successfully.

Remarks

When a container initializes an embedded object, it calls this function to inform the object of the names of both the container application and container document. When the object is opened for editing, it displays these names in the title bar of its window.

Notes to Callers

Call SetHostNames only for embedded objects, because for linked objects, the link source supplies its own separate editing window and title bar information.

Notes to Implementers

An object’s application of SetHostNames should include whatever modifications to its user interface may be appropriate to an object’s embedded state. Such modifications typically will include adding and removing menu commands and altering the text displayed in the title bar of the editing window.

The complete window title for an embedded object in an SDI container application or an MDI application with a maximized child window should appear as follows:

<object application name> − <object short type> in <container document>

Otherwise, the title should be:

<object application name> − <container document>

The “object short type” refers to a form of an object’s name short enough to be displayed in full in a list box.

Since these identifying strings are not stored as part of the persistent state of the object, IOleObject::SetHostNames must be called each time the object loads or runs.

See Also

IOleObject::GetUserType


IOleObject::SetMoniker

Notifies an object of its container’s moniker, the object’s own moniker relative to the container, or the object’s full moniker.

HRESULT SetMoniker(

DWORD dwWhichMoniker,	//Value specifying moniker being set
IMoniker *pmk	//Pointer to moniker
);
Parameters

dwWhichMoniker

[in] Value specifying which moniker is passed in pmk. Values are from the enumeration OLEWHICHMK.

pmk

[in] Pointer to where to return the moniker.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

Moniker successfully set.

Remarks

A container that supports links to embedded objects must be able to inform an embedded object when its moniker has changed. Otherwise, subsequent attempts by link clients to bind to the object will fail. The IOleObject::SetMoniker method provides one way for a container to communicate this information.

The container can pass either its own moniker, an object's moniker relative to the container, or an object's full moniker. In practice, if a container passes anything other than an object's full moniker, each object calls the container back to request assignment of the full moniker, which the object requires to register itself in the running object table.

The moniker of an object relative to its container is stored by the object handler as part of the object’s persistent state. The moniker of the object’s container, however, must not be persistently stored inside the object because the container can be renamed at any time.

Notes to Callers

A container calls IOleObject::SetMoniker when the container has been renamed, and the container’s embedded objects currently or can potentially serve as link sources. Containers call SetMoniker mainly in the context of linking because an embedded object is already aware of its moniker. Even in the context of linking, calling this method is optional because objects can call IOleClientSite::GetMoniker to force assignment of a new moniker.

Note to Implementers

Upon receiving a call to SetMoniker, an object should register its full moniker in the running object table and send OnRename notification to all advise sinks that exist for the object.

See Also

CreateItemMoniker, IAdviseSink::OnRename, IOleClientSite::GetMoniker, IOleObject::GetMoniker


IOleObject::Unadvise

Deletes a previously established advisory connection.

HRESULT Unadvise(

DWORD dwConnection	//Token
);
Parameter

dwConnection

[in] Contains a token of nonzero value, which was previously returned from IOleObject::Advise through its pdwConnection parameter.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

Advisory connection deleted successfully.

OLE_E_NOCONNECTION

dwConnection does not represent a valid advisory connection.

Remarks

Normally, containers call IOleObject::Unadvise at shutdown or when an object is deleted. In certain cases, containers can call this method on objects that are running but not currently visible as a way of reducing the overhead of maintaining multiple advisory connections. The easiest way to implement this method is to delegate the call to IOleAdviseHolder::Unadvise.

See Also

IOleObject::Advise, IOleObject::EnumAdvise, IOleAdviseHolder::Unadvise


IOleObject::Update

Updates an object handler’s or link object’s data or view caches.

HRESULT Update();

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

All caches are up to date.

OLE_E_CANT_BINDTOSOURCE

Cannot run object to get updated data. The object is for some reason unavailable to the caller.

CACHE_E_NOCACHE_UPDATED

No caches were updated.

CACHE_S_SOMECACHES_NOTUPDATED

Some caches were not updated.

Remarks

The Update method provides a way for containers to keep data updated in their linked and embedded objects. A link object can become out-of-date if the link source has been updated. An embedded object that contains links to other objects can also become out of date. An embedded object that does not contain links cannot become out of date because its data is not linked to another source.

Notes to Implementers

When a container calls a link object’s IOleObject::Update method, the link object finds the link source and gets a new presentation from it. This process may also involve running one or more object applications, which could be time-consuming.

When a container calls an embedded object’s IOleObject::Update method, it is requesting the object to update all link objects it may contain. In response, the object handler recursively calls IOleObject::Update for each of its own linked objects, running each one as needed.

See Also

IOleObject::IsUpToDate


IOleParentUndoUnit

The IOleParentUndoUnit interface enables undo units to contain child undo units. For example, a complex action can be presented to the end user as a single undo action even though a number of separate actions are involved. All the subordinate undo actions are contained within the top-level, parent undo unit.

A parent undo unit is initially created using the IOleUndoManager::Open method. Then, to add another parent unit nested within an existing parent unit, you call IOleParentUndoUnit::Open. While a parent unit is open, the undo manager adds undo units to it by calling IOleParentUndoUnit::Add. When the undo manager closes a top-level parent, the entire undo unit with its nested subordinates is placed on top of the undo stack.

This interface is derived from IOleUndoUnit and supports all the methods on that interface.

If an object needs to create a parent unit, there are several cases to consider:

•	To create an enabling parent unit, the object calls IOleUndoManager::GetOpenParentState on the undo manager and checks the return value. If the value is S_FALSE, then the object creates the enabling parent and opens it. If the return value is S_OK, then there is a parent already open. If the open parent is blocked (UAS_BLOCKED bit set), or an enabling parent (UAS_BLOCKED and UAS_NOPARENTENABLE bits not set), then there is no need to create the enabling parent. If the currently open parent is a disabling parent (UAS_NOPARENTENABLE bit set), then the enabling parent should be created and opened to re-enable adding undo units. Note that UAS_NORMAL has a value of zero, which means it is the absence of all other bits and is not a bit flag that can be set. If comparing *pdwState against UAS_NORMAL, mask out unused bits from *pdwState with UAS_MASK to allow for future expansion.

•	To create a blocked parent, the object calls IOleUndoManager::GetOpenParentState and checks for an open parent that is already blocked. If one exists, then there is no need to create the new blocking parent. Otherwise, the object creates it and opens it on the stack.

•	To create a disabling parent, the object calls IOleUndoManager::GetOpenParentState and checks for an open parent that is blocked or disabling. If either one exists it is unnecessary to create the new parent. Otherwise, the object creates the parent and opens it on the stack.

In the event that both the UAS_NOPARENTENABLE and UAS_BLOCKED flags are set, the flag that is most relevant to the caller should be used with UAS_NOPARENTENABLE taking precedence. For example, if an object is creating a simple undo unit, it should pay attention to the UAS_NOPARENTENABLE flag and clear the undo stack. If it is creating an enabling parent unit, then it should pay attention to the UAS_BLOCKED flag and skip the creation.

When the parent undo unit is marked blocked, it discards any undo units it receives.

When to Implement

An undo unit that is capable of containing child undo units implements this interface in addition to IOleUndoUnit.

When to Use

The undo manager calls the methods in this interface to add child undo units.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleUndoUnit Methods	Description
Do	Instructs the undo unit to carry out its action.
GetDescription	Returns a string that describes the undo unit and can be used in the undo or redo user interface.
GetUnitType	Returns the CLSID and a type identifier for the undo unit.
OnNextAdd	Notifies the last undo unit in the collection that a new unit has been added.
IOleParentUndoUnit Methods	Description
Open	Opens a new parent undo unit, which becomes part of the containing unit’s undo stack.
Close	Closes the most recently opened parent undo unit.
Add	Adds a simple undo unit to the collection.
FindUnit	Indicates if the specified unit is a child of this undo unit or one of its children, that is if the specified unit is part of the hierarchy in this parent unit.
GetParentState	Returns state information about the innermost open parent undo unit.
See Also

IOleUndoManager, IOleUndoUnit


IOleParentUndoUnit::Add

Adds a simple undo unit to the collection.

HRESULT Add(

IOleUndoUnit* pUU	//Pointer to undo unit to be added
);
Parameters

pUU

[in] Pointer to undo unit to be added.

Return Values

S_OK

The specified unit was successfully added or the parent unit was blocked.

Remarks

The parent undo unit or undo manager must accept any undo unit given to it, unless it is blocked. If it is blocked, it should do nothing but return S_OK.

See Also

IOleUndoManager::Add


IOleParentUndoUnit::Close

Closes the specified parent undo unit.

HRESULT Close(

IOleParentUndoUnit* pPUU,	//Pointer to the currently open parent unit
BOOL fCommit	//Indicates whether to keep or discard the unit
);
Parameters

pPUU

[in] Pointer to the currently open parent unit to be closed.

fCommit

[in] Indicates whether to keep or discard the unit. If TRUE, the unit is kept in the collection. If FALSE, the unit is discarded. This parameter is used to allow the client to discard an undo unit under construction if an error or a cancellation occurs.

Return Values

S_OK

The parent unit had open child units and it was successfully closed.

S_FALSE

The parent undo unit did not have an open child and it was successfully closed.

E_INVALIDARG

If pPUU does not match the currently open parent undo unit, then implementations of this method should return E_INVALIDARG without changing any internal state unless the parent unit is blocked.

Remarks

A parent undo unit knows it is being closed when it returns S_FALSE from this method. At that time, it should terminate any communication with other objects which may be giving data to it through private interfaces.

Note to Implementers

To process a Close, a parent undo unit first checks to see if it has an open child unit. If it does not, it returns S_FALSE.

If it does have a child unit open, it calls the Close method on the child. If the child returns S_FALSE, then the parent undo unit verifies that pPUU points to the child unit, and closes that child undo unit. If the child returns S_OK then it handled the Close internally and its parent should do nothing.

If the parent unit is blocked, it should check the pPUU parameter to determine the appropriate return code. If pPUU is pointing to itself, then it should return S_FALSE.

Otherwise, it should return S_OK; the fCommit parameter is ignored; and no action is taken.

If pPUU does not match the currently open parent undo unit, then implementations of this method should return E_INVALIDARG without changing any internal state. The only exception to this is if the unit is blocked.

Note to Callers

An error return indicates a fatal error condition.

The parent unit or undo manager must accept the undo unit if fCommit is TRUE.

See Also

IOleUndoManager::Close


IOleParentUndoUnit::FindUnit

Indicates if the specified unit is a child of this undo unit or one of its children, that is if the specified unit is part of the hierarchy in this parent unit.

HRESULT FindUnit(

IOleUndoUnit* pUU	//Pointer to the undo unit to be found
);
Parameters

pUU

[in] Pointer to the undo unit to be found.

Return Values

S_OK

The specified undo unit is in the hierarchy subordinate to this parent.

S_FALSE

The specified undo unit is not part of the hierarchy under this parent. An error indicates an RPC failure condition.

Remarks

This is typically called by the undo manager in its implementation of its DiscardFrom method in the rare event that the unit being discarded is not a top-level unit. The parent unit should look in its own list first, then delegate to each child that is also a parent unit, as determined by doing a QueryInterface for IOleParentUndoUnit.

See Also

IOleUndoManager::DiscardFrom


IOleParentUndoUnit::GetParentState

Returns state information about the innermost open parent undo unit.

HRESULT GetParentState(

DWORD* pdwState	//Pointer to state information
);
Parameters

pdwState

[out] Pointer to state information. This information is a value taken from the UASFLAGS enumeration.

Return Values

S_OK

The parent’s state was successfully returned.

Remarks

Note to Implementers

If the unit has an open child, it should delegate this method to that child. If not, it should fill in *pdwState values appropriately and return. Note that a parent unit must never be blocked while it has an open child. If this happened it could prevent the child unit from being closed, which would cause serious problems.

Note to Callers

When checking for a normal state, use the UAS_MASK value to mask unused bits in the pdwState parameter to this method for future compatibility. For example:

fNormal = ((pdwState & UAS_MASK) == UAS_NORMAL)

See Also

UASFLAGS


IOleParentUndoUnit::Open

Opens a new parent undo unit, which becomes part of the containing unit’s undo stack.

HRESULT Open(

IOleParentUndoUnit* pPUU	//Pointer to the parent undo unit to open
);
Parameters

pPUU

[in] Pointer to the parent undo unit to be opened.

Return Values

S_OK

The parent undo unit was successfully opened or it is currently blocked.

Remarks

The specified parent unit is created and remains open. The undo manager then calls the Add or Open methods on this parent unit to add new units to it. This parent unit receives any additional undo units until its Close method is called.

The parent unit specified by pPUU is not added to the undo stack until its Close method is called with the fCommit parameter set to TRUE.

The parent undo unit or undo manager must contain any undo unit given to it unless it is blocked. If it is blocked, it must return S_OK but should do nothing else.

See Also

IOleUndoManager::Open


IOleUILinkContainer

The IOleUILinkContainer interface is implemented by containers and used by OLE common dialog boxes. It supports these dialog boxes by providing the methods needed to manage a container’s links.

The IOleUILinkContainer methods enumerate the links associated with a container, and specify how they should be updated, automatically or manually. They change the source of a link and obtain information associated with a link. They also open a link’s source document, update links, and break a link to the source.

When to Implement

You must implement this interface if you are creating a container application that will use the Links, Change Source, or Update Links dialog boxes, as well as the Object Properties dialog box, which uses this interface indirectly. The Links dialog box calls back to the container application to perform OLE functions that manipulate the links within the container.

When to Use

OLE common dialog boxes use only this interface to manage the properties of a container’s links. They can also use it to manage non-OLE (DDE and other container-specific) links.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleUILinkContainer Methods	Description
GetNextLink	Enumerates the links in the container.
SetLinkUpdateOptions	Sets update options.
GetLinkUpdateOptions	Determines current update options for  the link.
SetLinkSource	Changes the source of the link.
GetLinkSource	Returns Links dialog box information about the link.
OpenLinkSource	Opens a link’s source.
UpdateLink	Forces a link to connect to its source and update.
CancelLink	Disconnects selected links.
See Also

OleUIEditLinks, OleUIChangeSource, OleUIUpdateLinks, OleUIObjectProperties, OLEUIEDITLINKS


IOleUILinkContainer::CancelLink

Disconnects the selected links.

HRESULT CancelLink(

DWORD dwLink	//Unique 32-bit link identifier
);
Parameter

dwLink

[in] Container-defined unique 32-bit identifier for a single link. Containers can use the pointer to the link's container site for this value.

Return Values

This method supports the standard return values E_FAIL,

E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

Successfully disconnected the selected links.

E_ACCESSDENIED

Insufficient access permissions.

Remarks

Notes To Callers

Call CancelLink when the user selects the Break Link button from the Links dialog box. The link should be converted to a picture. The Links dialog box will not be dismissed for OLE links.

Notes To Implementers

For OLE links, OleCreateStaticFromData can be used to create a static picture object using the IDataObject interface of the link as the source.

See Also

IDataObject, OleCreateStaticFromData


IOleUILinkContainer::GetLinkSource

Returns information about a link that can be displayed in the UI.

HRESULT GetLinkSource(

DWORD dwLink,	//Unique 32-bit link identifier
LPTSTR FAR* lplpszDisplayName,	//Indirect pointer to length of display name portion
ULONG FAR* lplenFileName,	//Pointer to length of file name portion
LPTSTR FAR* lplpszFullLinkType,	//Indirect pointer to full-link type string
LPTSTR FAR* lplpszShortLinkType,	//Indirect pointer to short-link type string
BOOL FAR* lpfSourceAvailable,	//Pointer to availability of link
BOOL FAR* lpfIsSelected	//Pointer to indicate that link entry should be selected in listbox
);
Parameters

dwLink

[in] Container-defined unique 32-bit identifier for a single link. See IOleUILinkContainer::GetNextLink.

lplpszDisplayName

[out] Indirect pointer to the allocated full-link source display name string. The Links dialog box will free this string.

lplenFileName

[out] Pointer to the length of the leading file name portion of the lplpszDisplayName string. If the link source is not stored in a file, then *lplenFileName should be 0. For OLE links, call IOleLink::GetSourceDisplayName.

lplpszFullLinkType

[out] Indirect pointer to the allocated full-link type string that is displayed at the bottom of the Links dialog box. The Links dialog box will free this string. For OLE links, this should be the full User Type name. Use IOleObject::GetUserType, specifying USERCLASSTYPE_FULL for dwFormOfType.

lplpszShortLinkType

[out] Indirect pointer to the allocated short-link type string that is displayed in the listbox of the Links dialog box. The Links dialog box will free this string. For OLE links, this should be the short User Type name. Use IOleObject::GetUserType, specifying USERCLASSTYPE_SHORT for dwFormOfType.

lpfSourceAvailable

[out] Pointer that returns FALSE if it is known that a link is unavailable since the link is to some known but unavailable document. Certain options, such as Update Now, are disabled (grayed in the UI) for such cases.

lpfIsSelected

[out] Pointer to a BOOL variable that tells the Edit Links dialog box that this link’s entry should be selected in the dialog’s multi-selection listbox. OleUIEditLinks calls this method at least once for each item to be placed in the links list. If none of them return TRUE, then none of them will be selected when the dialog box is first displayed. If all of them return TRUE, then all will be displayed. That is, it returns TRUE if this link is currently part of the selection in the underlying document, FALSE if not. Any links that are selected in the underlying document are selected in the dialog box; this way, the user can select a set of links and use the dialog box to update them or change their source(s) simultaneously.

Return Values

This method supports the standard return values E_FAIL,

E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

Successfully returned link information.

E_ACCESSDENIED

Insufficient access permissions.

Remarks

Notes To Callers

Call this method during dialog box initialization, after returning from the Change Source dialog box.

See Also

IOleLink::GetSourceDisplayName, IOleObject::GetUserType, USERCLASSTYPE, OleUIChangeSource, OLEUICHANGESOURCE_com_OLEUICHANGESOURCE_str


IOleUILinkContainer::GetLinkUpdateOptions

Determine the current update options for a link.

HRESULT GetNextLink(

DWORD dwLink,	//Unique 32-bit link identifier
DWORD FAR * lpdwUpdateOpt	//Pointer to address to return update option
);
Parameters

dwLink

[in] Container-defined unique 32-bit identifier for a single link. See IOleUILinkContainer::GetNextLink.

lpdwUpdateOpt

[out] Pointer to the location that the current update options will be written.

Return Values

This method supports the standard return values E_FAIL,

E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

Successfully determined update options.

E_ACCESSDENIED

Insufficient access permissions.

Remarks

Notes To Implementers

Containers can implement this method for OLE links simply by calling IOleLink::SetUpdateOptions on the link object.

See Also

IOleUILinkContainer::GetNextLink, IOleUILinkContainer::SetLinkUpdateOptions, IOleLink::SetUpdateOptions


IOleUILinkContainer::GetNextLink

Enumerates the links in a container.

DWORD GetNextLink(

DWORD dwLink	//Unique 32-bit linkidentifier
);
Parameter

dwLink

[in] Container-defined unique 32-bit identifier for a single link. This value is only passed to other methods on this interface, so it can be any value that uniquely identifies a link to the container. Containers frequently use the pointer to the link's container site object for this value.

Return Values

Returns a container’s link identifiers in sequence; NULL if it has returned the last link.

Remarks

Notes to Callers

Call this method to enumerate the links in a container. If the value passed in dwLink is NULL, then the container should return the first link’s 32-bit identifier. If dwLink identifies the last link in the container, then the container should return NULL.

See Also

IOleUILinkContainer::SetLinkUpdateOptions, IOleUILinkContainer::GetLinkUpdateOptions


IOleUILinkContainer::OpenLinkSource

Opens the link’s source.

HRESULT OpenLinkSource(

DWORD dwLink	//Unique 32-bit link identifier
);
Parameter

dwLink

[in] Container-defined unique 32-bit identifier for a single link. Containers can use the pointer to the link's container site for this value.

Return Values

This method supports the standard return values E_FAIL, E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

Successfully opened the link’s source.

E_ACCESSDENIED

Insufficient access permissions.

Remarks

Notes To Callers

The OpenLinkSource method is called when the Open Source button is selected from the Links dialog box. For OLE links, call IOleObject::DoVerb, specifying OLEIVERB_SHOW for iVerb.

See Also

IOleObject::DoVerb, OLEVERB


IOleUILinkContainer::SetLinkSource

Changes the source of a link.

HRESULT SetLinkSource(

DWORD dwLink,	//Unique 32-bit link identifier
LPTSTR lpszDisplayName,	//Pointer to source string to parse
ULONG FAR* lenFileName,	//Length of the file name portion
ULONG FAR* pchEaten,	//Pointer to number of characters successfully parsed
BOOL fValidateSource	//Specifies whether moniker should be validated
);
Parameters

dwLink

[in] Container-defined unique 32-bit identifier for a single link. See IOleUILinkContainer::GetNextLink .

lpszDisplayName

[in] Pointer to new source string to be parsed.

lenFileName

Length of the leading file name portion of the lpszDisplayName string. If the link source is not stored in a file, then lenFileName should be 0. For OLE links, call IOleLink::GetSourceDisplayName.

pchEaten

[out] Pointer to the number of characters successfully parsed in lpszDisplayName.

fValidateSource

[in] TRUE if the moniker should be validated; for OLE links, MkParseDisplayName should be called. FALSE if the moniker should not be validated. If possible, the link should accept the unvalidated source, and mark itself as unavailable.

Return Values

This method supports the standard return values E_FAIL,

E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

Successfully changed the links source.

E_ACCESSDENIED

Insufficient access permissions.

Remarks

Notes To Callers

Call this method from the Change Source dialog box, with fValidateSource initially set to TRUE. Change Source can be called directly or from the Links dialog box. If this call to SetLinkSource returns an error (e.g., MkParseDisplayName failed because the source was unavailable), then you should display an Invalid Link Source message, and the user should be allowed to decide whether or not to fix the source. If the user chooses to fix the source, then the user should be returned to the Change Source dialog box with the invalid portion of the input string highlighted. If the user chooses not to fix the source, then SetLinkSource should be called a second time with fValidateSource set to FALSE, and the user should be returned to the Links dialog box with the link marked Unavailable.

See Also

MkParseDisplayName


IOleUILinkContainer::SetLinkUpdateOptions

Sets a link’s update options to Automatic (OLEUPDATE_ALWAYS) or Manual (OLEUPDATE_ONCALL).

HRESULT SetLinkUpdate(

DWORD dwLink,	//Unique 32-bit link identifier
DWORD dwUpdateOpt	//Update options
);
Parameters

dwLink

[in] Container-defined unique 32-bit identifier for a single link. See IOleUILinkContainer::GetNextLink.

dwUpdateOpt

[in] Update options, which can be Automatic (OLEUPDATE_ALWAYS) or Manual (OLEUPDATE_ONCALL).

Return Values

This method supports the standard return values E_FAIL,

E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

Successfully set the links update options.

E_ACCESSDENIED

Insufficient access permissions.

Remarks

The user selects update options from the Links dialog box.

Notes To Implementers

Containers can implement this method for OLE links by simply calling IOleLink::SetUpdateOptions on the link object.

See Also

IOleUILinkContainer::GetNextLink, IOleUILinkContainer::GetLinkUpdateOptions, IOleLink::SetUpdateOptions


IOleUILinkContainer::UpdateLink

Forces selected links to connect to their source and retrieve current information.

HRESULT UpdateLink(

DWORD dwLink,	//Unique 32-bit link identifier
DWORD fErrorMessage,	//Determines whether or not caller should display error message
DWORD fReserved	//Reserved
);
Parameters

dwLink

[in] Container-defined unique 32-bit identifier for a single link. Containers can use the pointer to the link's container site for this value.

fErrorMessage

[in] Determines whether or not the caller (implementer of IOleUILinkContainer) should show an error message upon failure to update a link. The Update Links dialog box sets this to FALSE. The Object Properties and Links dialog boxes set it to TRUE.

fReserved

[in] Reserved for future use; must be set to FALSE.

Return Values

This method supports the standard return values E_FAIL, E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

Successfully updated linked objects.

E_ACCESSDENIED

Insufficient access permissions.

Remarks

Notes To Callers

Call this method with fErrorMessage set to TRUE in cases where the user expressly presses a button to have a link updated, that is, presses the Links’ Update Now button. Call it with FALSE in cases where the container should never display an error message, that is, where a large set of operations are being performed and the error should be propagated back to the user later, as might occur with the Update links progress meter. Rather than providing one message for each failure, assuming there are failures, provide a single message for all failures at the end of the operation.

Notes To Implementers

For OLE links, call IOleObject::Update.

See Also

IOleObject::Update


IOleUILinkInfo

The IOleUILinkInfo interface is an extension of the IOleUILinkContainer interface. It returns the time that an object was last updated, which is link information that IOleUILinkContainer does not provide.

When To Implement

You must implement this interface so your container can support the “Link” page of the Object Properties dialog box. If you are writing a container that does not implement links, you do not need to implement this interface.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleUILinkContainer Methods	Description
GetNextLink	Enumerates the links in the container.
SetLinkUpdateOptions	Sets update options.
GetLinkUpdateOptions	Determines current update options for the link.
SetLinkSource	Changes the source of the link.
GetLinkSource	Returns Links dialog box information about link.
OpenLinkSource	Opens a link’s source.
UpdateLink	Forces a link to connect to its source and update.
CancelLink	Breaks the link.
IOleUILinkInfo Methods	Description
GetLastUpdate	Determines the last time the object was updated, whether automatically or manually.


IOleUILinkInfo::GetLastUpdate

Indicates when the object was last updated.

HRESULT GetLastUpdate(

DWORD dwLink,	//Unique 32-bit link identifier
FILETIME FAR * lpLastUpdate	//Pointer to the time object was last updated
);
Parameters

dwLink

[in] Container-defined unique 32-bit identifier for a single link. Containers can use the pointer to the link's container site for this value.

lpLastUpdate

[out] Pointer to the time that the object was last updated.

Return Values

This method supports the standard return values E_FAIL, E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

Successfully returned link information.

E_ACCESSDENIED

Insufficient access permissions.

Remarks

Notes To Implementers

If the time that the object was last updated is known, copy it to lpLastUpdate. If it is not known, then leave lpLastUpdate unchanged and Unknown will be displayed in the link page.


IOleUIObjInfo

The IOleUIObjInfo interface is implemented by containers and used by the container’s Object Properties dialog box and by the Convert dialog box. It provides information used by the General and View pages of the Object Properties dialog box , which display information about the object’s size, location, type, and name. It also allows the object to be converted via the Convert dialog box. The View page allows the object’s icon to be modified from its original form, and its display aspect to be changed (iconic versus content). Optionally, you can have your implementation of this interface allow the scale of the object to be changed.

When To Implement

You must implement this interface so your container application can support the OleUIObjectProperties function and the dialog box that it implements.

When To Use

Use this interface when you need to get and set information required by the Object Properties dialog box , and to support the Convert dialog box.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleUILinkContainer Methods	Description
GetNextLink	Enumerates the links in the container.
SetLinkUpdateOptions	Sets update options.
GetLinkUpdateOptions	Determines current update options for the link.
SetLinkSource	Changes the source of the link.
GetLinkSource	Returns Links dialog box information about link.
OpenLinkSource	Opens a link’s source.
UpdateLink	Forces a link to connect to its source and update.
CancelLink	Breaks the link.
IOleUIObjInfo Methods	Description
GetObjectInfo	Gets general information about the object.
GetConvertInfo	Gets information that is used for the Convert dialog box.
ConvertObject	Converts the object once the user selects a destination type.
GetViewInfo	Gets the current icon, aspect, and scale of the object.
SetViewInfo	Sets the current icon, aspect, and scale of the object.
See Also

OleUIObjectProperties


IOleUIObjInfo::ConvertObject

Converts the object to the type of the new CLSID.

HRESULT ConvertObject(

DWORD dwObject,	//Unique 32-bit object identifier
REFCLSID clsidNew	//CLSID to convert the object to
);
Parameters

dwObject

[in] Unique 32-bit identifier for the object.

clsidNew

[in] CLSID to convert the object to.

Return Values

This method supports the standard return values E_FAIL,

E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

Successfully returned link information.

E_ACCESSDENIED

Insufficient access permissions.

Remarks

Notes To Implementers

Your implementation of ConvertObject needs to convert the object to the CLSID specified. The actions taken by the convert operation are similar to the actions taken after calling OleUIConvert.

See Also

OleUIConvert


IOleUIObjInfo::GetConvertInfo

Gets the conversion information associated with the specified object.

HRESULT GetConvertInfo(

DWORD dwObject,	//Unique 32-bit object identifier
CLSID FAR * lpClassID,	//Pointer to location of CLSID of the object
WORD FAR *lpwFormat,	//Pointer to clipboard format of the object
CLSID FAR * lpConvertDefaultClassID,	//Pointer to default class to convert object to
LPCLSID FAR * lplpClsidExclude,	//Indirect pointer to excluded CLSIDs
UINT FAR * lpcClsidExclude	//Pointer to number of CLSIDs in lplpClsidExclude
);
Parameters

dwObject

[in] Unique 32-bit identifier for the object.

lpClassID

[out] Pointer to the location to return the object’s CLSID.

lpwFormat

[out] Pointer to the clipboard format of the object.

lpConvertDefaultClassID

[out] Pointer to the default class, selected from the UI, to convert the object to.

lplpClsidExclude

[out] Indirect pointer to an array of CLSIDs that should be excluded from the UI for this object. May be NULL, if lpcClsidExclude is zero.

lpcClsidExclude

[out] Pointer to number of CLSIDs in lplpClsidExclude. May be zero.

Return Values

This method supports the standard return values E_FAIL, E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

Successfully returned link information.

E_ACCESSDENIED

Insufficient access permissions.

Remarks

Notes To Implementers

You must fill in the CLSID of the object at a minimum. lpwFormat may be left at zero if the format of the storage is unknown.


IOleUIObjInfo::GetObjectInfo

Gets size, type, name and location information about an object.

HRESULT GetObjectInfo(

DWORD dwObject,	//Unique 32-bit object identifier
DWORD FAR *lpdwObjSize,	//Pointer to object’s size
LPTSTR FAR *lplpszLabel,	//Indirect pointer to object’s label.
LPTSTR FAR * lplpszType,	//Indirect pointer to object’s “long” type
LPTSTR FAR * lplpszShortType,	//Indirect pointer to object’s “short” type
LPTSTR FAR * lplpszLocation	//Indirect pointer to the object’s source
);
Parameters

dwObject

[in] Unique 32-bit identifier for the object.

lpdwObjSize

[out] Pointer to the object’s size, in bytes, on disk. This may be an approximate value.

lplpszLabel

[out] Indirect pointer to the object’s label. May be NULL, which indicates that the implementation should not fill this in.

lplpszType

[out] Indirect pointer to the object’s “long” type. May be NULL, which indicates that the implementation should not fill this in.

lplpszShortType

[out] Indirect pointer to the object’s “short” type. May be NULL, which indicates that the implementation should not fill this in.

lplpszLocation

[out] Indirect pointer to the object’s source. May be NULL, which indicates that the implementation should not fill this in.

Return Values

This method supports the standard return values E_FAIL, E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

Successfully returned object information.

Remarks

The strings and the object’s size are displayed in the object properties “General” page.

Notes To Implementers

Your implementation of GetObjectInfo should place each of the object’s attributes in the out parameters provided. Set lpdwObjSize to (DWORD)-1 when the size of the object is unknown. Allocate all strings (the rest of the params) with the OLE task allocator obtained via CoGetMalloc, as is standard for all OLE interfaces with [out] string parameters, or you can simply use CoTaskMemAlloc.

See Also

CoGetMalloc, CoTaskMemAlloc


IOleUIObjInfo::GetViewInfo

Gets the view information associated with the object.

HRESULT GetViewInfo(

DWORD dwObject,	//Unique 32-bit object identifier
HGLOBAL FAR * phMetaPict,	//Pointer to object’s current icon
DWORD * pdvAspect,	///Pointer to object’s current aspect
int * pnCurrentScale	///Pointer to object’s current scale
);
Parameters

dwObject

[in] Unique 32-bit identifier for the object.

phMetaPict

[in] Pointer to the object’s current icon. Could be NULL, indicating that the caller is not interested in the object’s current presentation.

pdvAspect

[in] Pointer to the object’s current aspect. Could be NULL, indicating that the caller is not interested in the object’s current aspect, i.e., DVASPECT_ICONIC or DVASPECT_CONTENT.

pnCurrentScale

[in] Pointer to the object’s current scale. Could be NULL, indicating that the caller is not interested in the current scaling factor applied to the object in the container’s view.

Return Values

This method supports the standard return values E_FAIL, E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

Successfully returned link information.

E_ACCESSDENIED

Insufficient access permissions.

Remarks

Notes To Implementers

You must fill in the object’s current icon, aspect, and scale.

See Also

OLEUIVIEWPROPS


IOleUIObjInfo::SetViewInfo

Sets the view information associated with the object.

HRESULT SetViewInfo(

DWORD dwObject,	//Unique 32-bit object identifier
HGLOBAL hMetaPict,	//New icon for the object
DWORD dvAspect,	//New display aspect for the objec
int nCurrentScale,	//New scale for the objec
BOOL bRelativeToOrig	//Scale of the object relative to origin
);
Parameters

dwObject

[in] Unique 32-bit identifier for the object.

hMetaPict

[in] New icon for the object.

dvAspect

[in] Object’s new display aspect or view.

nCurrentScale

[in] Object’s new scale.

bRelativeToOrig

[in] Scale of the object, relative to the origin. This value is TRUE if the new scale should be relative to the original scale of the object. If FALSE, nCurrentScale applies to the object’s current size.

Return Values

This method supports the standard return values E_FAIL, E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

Successfully returned link information.

E_ACCESSDENIED

Insufficient access permissions.

Remarks

Notes To Implementers

You should apply the new attributes (icon, aspect, and scale) to the object. If bRelativeToOrig is set to TRUE, nCurrentScale (in percentage units) applies to the original size of the object before it was scaled. If bRelativeToOrig is FALSE, nCurrentScale applies to the object’s current size.

See Also

DVASPECT


IOleUndoManager

The IOleUndoManager interface enables containers to implement multi-level undo and redo operations for actions that occur within contained controls.

The control must create an undo unit with the IOleUndoUnit interface or a parent undo unit with the IOleParentUndoUnit interface derived from IOleUndoUnit. Both of these interfaces perform the undo action and the parent undo unit additionally can contain nested undo units.

The undo manager provides a centralized undo and redo service. It manages parent undo units and simple undo units on the undo and redo stacks. Whether an object is UI-active or not, it can deposit undo units on these stacks by calling methods in the undo manager.

The centralized undo manager then has the data necessary to support the undo and redo user interface for the host application and can discard undo information gradually as the stack becomes full.

The undo manager is implemented as a service and objects obtain a pointer to IOleUndoManger from the IServiceProvider interface. It is usually implemented by the container. The service manages two stacks, the undo stack and the redo stack, each of which contains undo units generated by embedded objects or by the container application itself.

Undo units are typically generated in response to actions taken by the end user. An object does not generate undo actions for programmatic events. In fact, programmatic events should clear the undo stack since the programmatic event can possibly invalidate assumptions made by the undo units on the stack.

When the object’s state changes, it creates an undo unit encapsulating all the information needed to undo that change. The object calls methods in the undo manager to place its undo units on the stack. Then, when the end user selects an Undo operation, the undo manager takes the top undo unit off the stack, invokes its action by calling its IOleUndoUnit::Do method, and then releases it. When an end user selects a Redo operation, the undo manager takes the top redo unit off the stack, invokes its action by calling its IOleUndoUnit::Do method, and then releases it.

The undo manager has three states: the base state, the undo state, and the redo state. It begins in the base state. To perform an action from the undo stack, it puts itself into the undo state, calls IOleUndoUnit::Do on the undo unit, and goes back to the base state. To perform an action from the redo stack, it puts itself into the redo state, calls IOleUndoUnit::Do on the undo unit, and goes back to the base state.

If the undo manager receives a new undo unit while in the base state, it places the unit on the undo stack and discards the entire redo stack. While it is in the undo state, it puts incoming units on the redo stack. While it is in the redo state, it places them on the undo stack without flushing the redo stack.

The undo manager also allows objects to discard the undo or redo stack starting from any object in either stack.

The host application determines the scope of an undo manager. For example, in one application, the scope might be at the document level; a separate undo manager is maintained for each document; and undo is managed independently for each document. However, another application maintain one undo manager, and therefore one undo scope, for the entire application.

Handling Errors

Having an undo operation fail and leaving the document in an unstable state is something the undo manager, undo units, and the application itself all have to work together to avoid. As a result, there are certain requirements that undo units, the undo manager, and the application or component using undo must conform to.

To perform an undo, the undo manager calls IOleUndoUnit::Do on one or more undo units which can, in turn, contain more units. If a unit somewhere in the hierarchy fails, the error will eventually reach the undo manager, which is responsible for making an attempt to roll back the state of the document to what it was before the call to the last top-level unit. The undo manager performs the rollback by calling IOleUndoUnit::Do on the unit that was added to the redo stack during the undo attempt. If the rollback also fails, then the undo manager is forced to abandon everything and return to the application. The undo manager indicates whether or not the rollback succeeded, and the application can take different actions based on this, such as reinitializing components so they’re in a known state.

All the steps in adding an undo unit to the stack should be performed atomically. That is, all steps must succeed or none of them should succeed.

The host application that provides the undo manager decides what action to take when undo fails. At the very least, it should inform the user of the failure. The host application will be told by the undo manager whether or not the undo succeeded and whether or not the attempted rollback succeeded. In case both the undo and rollback failed, the host application can present the user with several options, including immediately shutting down the application.

Simple undo units must not change the state of any object if they return failure. This includes the state of the redo stack or undo stack if performing a redo. They are also required to put a corresponding unit on the redo or undo stack if they succeed. The application should be stable before and after the unit is called.

Parent undo units have the same requirements as simple units, with one exception. If one or more children succeeded prior to another child’s failure, the parent unit must commit its corresponding unit on the redo stack and return the failure to its parent. If no children succeeded, the parent unit should commit its redo unit only if it has made a state change that needs to be rolled back. For example, suppose a parent unit contains three simple units. The first two succeed and added units to the redo stack, but the third one failed. At this point, the parent unit commits its redo unit and returns the failure.

As a side effect, the parent unit should never make state changes that depend on the success of their children. Doing this will cause the rollback behavior to break. If a parent unit makes state changes, it should do them before calling any children. Then, if the state change fails, it should not commit its redo unit, it should not call any children, and it should return the failure to its parent.

The undo manager has one primary requirement for error handling: to attempt rollback when an undo or redo fails.

Non-compliant Objects

Objects that do not support multi-level undo can cause serious problems for a global undo service. Since the object cannot be relied on to properly update the undo manager, any units submitted by other objects are also suspect, because their units may rely on the state of the non-compliant object. Attempting to undo a compliant object’s units may not be successful, because the state in the non-compliant object will not match.

To detect objects that do not support multi-level undo, check for the OLEMISC_SUPPORTSMULTILEVELUNDO value. An object that can participate in the global undo service sets this value.

When an object without this value is added to a user-visible undo context, the safest thing to do is disable the undo user interface for this context. Alternatively, a dialog could be presented to the user, asking them whether to attempt to provide partial undo support, working around the non-compliance of the new object.

In addition, non-compliant objects may be added to nested containers. In this case, the nested container needs to notify the undo manager that undo can no longer be safely supported by calling IOleUndoManager::Enable(FALSE).

When to Implement

Implement this interface to provide centralized undo services to the objects in a container.

When to Use

Call the methods in this interface to participate in global undo services.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleUndoManager Methods	Description
Open	Opens a new parent undo unit, which becomes part of its containing unit’s undo stack.
Close	Closes the specified parent undo unit.
Add	Adds a simple undo unit to the collection.
GetOpenParentState	Returns state information about the innermost open parent undo unit.
DiscardFrom	Instructs the undo manager to discard the specified undo unit and all undo units below it on the undo or redo stack.
UndoTo	Instructs the undo manager to perform actions back through the undo stack, down to and including the specified undo unit.
RedoTo	Instructs the undo manager to invoke undo actions back through the redo stack, down to and including the specified undo unit.
EnumUndoable	Creates an enumerator object that the caller can use to iterate through a series of top-level undo units from the undo stack.
EnumRedoable	Creates an enumerator object that the caller can use to iterate through a series of top-level undo units from the redo stack.
GetLastUndoDescription	Returns the description for the top-level undo unit that is on top of the undo stack.
GetLastRedoDescription	Returns the description for the top-level undo unit that is on top of the redo stack.
Enable	Enables or disables the undo manager.
See Also

IOleParentUndoUnit, IOleUndoUnit


IOleUndoManager::Add

Adds a simple undo unit to the collection.

HRESULT Add(

IOleUndoUnit* pUU	//Pointer to undo unit to be added
);
Parameters

pUU

[in] Pointer to undo unit to be added.

Return Values

S_OK

The specified unit was successfully added, the parent unit was blocked, or the undo manager is disabled.

Remarks

This method is implemented the same as IOleParentUndoUnit::Add. The parent undo unit or undo manager must accept any undo unit given to it, unless it is blocked. If it is blocked, it should do nothing but return S_OK.

Note to Implementers

If the undo manager is in the base state, it should put the new unit on the undo stack and discard the entire redo stack. If the undo manager is in the undo state, it should put new units on the redo stack. If the undo manager is in the redo state, it should put units on the undo stack without affecting the redo stack.

See Also

IOleParentUndoUnit::Add


IOleUndoManager::Close

Closes the specified parent undo unit.

HRESULT Close(

IOleParentUndoUnit* pPUU,	//Pointer to the currently open parent unit
BOOL fCommit	//Indicates whether to keep or discard the unit
);
Parameters

pPUU

[in] Pointer to the currently open parent unit to be closed.

fCommit

[in] Indicates whether to keep or discard the unit. If TRUE, the unit is kept in the collection. If FALSE, the unit is discarded. This parameter is used to allow the client to discard an undo unit under construction if an error or a cancellation occurs.

Return Values

S_OK

The parent unit had open child units and it was successfully closed. If the undo manager is disabled, it should immediately return S_OK and do nothing else.

S_FALSE

The parent undo unit did not have an open child and it was successfully closed.

E_INVALIDARG

If pPUU does not match the currently open parent undo unit, then implementations of this method should return E_INVALIDARG without changing any internal state unless the parent unit is blocked.

Remarks

This method is implemented the same as IOleParentUndoUnit::Close. A parent undo unit knows it is being closed when it returns S_FALSE from this method. At that time, it should terminate any communication with other objects which may be giving data to it through private interfaces.

Note to Implementers

To process a Close, a parent undo unit first checks to see if it has an open child unit. If it does not, it returns S_FALSE.

If it does have a child unit open, it calls the Close method on the child. If the child returns S_FALSE, then the parent undo unit verifies that pPUU points to the child unit, and closes that child undo unit. If the child returns S_OK then it handled the Close internally and its parent should do nothing.

If the parent unit is blocked, it should check the pPUU parameter to determine the appropriate return code. If pPUU is pointing to itself, then it should return S_FALSE.

Otherwise, it should return S_OK; the fCommit parameter is ignored; and no action is taken.

If pPUU does not match the currently open parent undo unit, then implementations of this method should return E_INVALIDARG without changing any internal state. The only exception to this is if the unit is blocked.

Note to Callers

An error return indicates a fatal error condition.

The parent unit or undo manager must accept the undo unit if fCommit is TRUE.

See Also

IOleParentUndoUnit::Close


IOleUndoManager::DiscardFrom

Instructs the undo manager to discard the specified undo unit and all undo units below it on the undo or redo stack.

HRESULT DiscardFrom(

IOleUndoUnit* pUU	//Pointer to undo unit to be discarded
);
Parameters

pUU

[in] Pointer to undo unit to be discarded. This parameter can be NULL to discard the entire undo or redo stack.

Return Values

S_OK

The specified undo unit was successfully discarded.

E_INVALIDARG

The specified undo unit was not found in the stacks.

E_UNEXPECTED

The undo manager is disabled.

Remarks

The undo manager first searches the undo stack for the given unit, and if not found there searches the redo stack. Once found, the given unit and all below it on the same stack are discarded. The undo unit may be a child of a parent unit contained by the undo manager, as determined by calling IOleParentUndoUnit::FindUnit. If it is a child unit, then the root unit containing the given unit and all units below it on the appropriate stack are discarded.

If there is an open parent unit and DiscardFrom(NULL) is called, the undo manager should immediately release and discard the open parent unit without calling the Close method first. When the object that opened the parent unit attempts to close it, IOleUndoManager::Close will return S_FALSE. If pUU is not NULL, then any open parent units should be left open.

See Also

IOleParentUndoUnit::FindUnit, IOleUndoManager::Close


IOleUndoManager::Enable

Enables or disables the undo manager.

HRESULT Enable(

BOOL fEnable	//Indicates whether to enable or disable the undo manager
);
Parameters

fEnable

[in] Indicates whether to enable or disable the undo manager. If TRUE, the undo manager should be enabled. If FALSE, the undo manager should be disabled.

Return Values

S_OK

The undo manager was successfully enabled or disabled.

E_UNEXPECTED

There is an open undo unit on the stack or the undo manager is currently performing an undo or a redo.

Remarks

The undo manager should clear both stacks when making the transition from enabled to disabled.

If the undo manager is disabled, each method in IOleUndoManager must behave as specified. See each method for details.

See Also

IOleUndoManager


IOleUndoManager::EnumRedoable

Creates an enumerator object that the caller can use to iterate through a series of top-level undo units from the redo stack.

HRESULT EnumRedoable(

IEnumOleUndoUnits** ppEnum	//Indirect pointer to new enumerator object
);
Parameters

ppEnum

[out] Indirect pointer to the IEnumOleUndoUnits interface on the enumerator object.

Return Values

S_OK

The enumerator object was successfully created and the interface pointer was returned.

E_UNEXPECTED

The undo manager is disabled.

Remarks

A new enumerator object is created each time this method is called. If the series of enumerated items changes over time, the results of enumeration operations can vary from one call to the next.

This method calls AddRef on the new enumerator object to increment its reference count. The caller is responsible for calling Release on the enumerator object when it is no longer needed.

See Also

IEnumOleUndoUnits


IOleUndoManager::EnumUndoable

Creates an enumerator object that the caller can use to iterate through a series of top-level undo units from the undo stack.

HRESULT EnumUndoable(

IEnumOleUndoUnits** ppEnum	//Indirect pointer to new enumerator object
);
Parameters

ppEnum

[out] Indirect pointer to the IEnumOleUndoUnits interface on the enumerator object.

Return Values

S_OK

The enumerator object was successfully created and the interface pointer was returned.

E_UNEXPECTED

The undo manager is disabled.

Remarks

A new enumerator object is created each time this method is called. If the series of enumerated items changes over time, the results of enumeration operations can vary from one call to the next.

This method calls AddRef on the new enumerator object to increment its reference count. The caller is responsible for calling Release on the enumerator object when it is no longer needed.

See Also

IEnumOleUndoUnits


IOleUndoManager::GetLastRedoDescription

Returns the description for the top-level undo unit that is on top of the redo stack.

HRESULT GetLastRedoDescription(

BSTR* pBstr	//Pointer to string
);
Parameters

pBstr

[out] Pointer to a string that contains a description of the top-level undo unit on the redo stack.

Return Values

S_OK

The string was successfully returned and it contains a valid description.

E_FAIL

The undo stack is empty.

E_UNEXPECTED

The undo manager is disabled.

Remarks

This method provides a convenient shortcut for the host application to add a description to its Edit Redo menu item. The *pbstr parameter is a string allocated with the standard string allocator. The caller is responsible for freeing this string.

See Also

IOleUndoManager::GetLastUndoDescription


IOleUndoManager::GetLastUndoDescription

Returns the description for the top-level undo unit that is on top of the undo stack.

HRESULT GetLastUndoDescription(

BSTR* pBstr	//Pointer to string
);
Parameters

pBstr

[out] Pointer to a string that contains a description of the top-level undo unit on the undo stack.

Return Values

S_OK

The string was successfully returned and it contains a valid description.

E_FAIL

The undo stack is empty.

E_UNEXPECTED

The undo manager is disabled.

Remarks

This method provides a convenient shortcut for the host application to add a description to its Edit Undo menu item. The *pbstr parameter is a string allocated with the standard string allocator. The caller is responsible for freeing this string.

See Also

IOleUndoManager::GetLastRedoDescription


IOleUndoManager::GetOpenParentState

Returns state information about the innermost open parent undo unit.

HRESULT GetOpenParentState(

DWORD* pdwState	//Pointer to state information
);
Parameters

pdwState

[out] Pointer to state information. This information is a value taken from the UASFLAGS enumeration.

Return Values

S_OK

There was an open parent unit and its state was successfully returned or the undo manager is disabled.

S_FALSE

There is no open parent unit.

Remarks

Note to Implementers

If there is an open parent unit, this method calls IOleParentUnit::GetParentState.

If the undo manager is disabled, it should fill the pdwState parameter with UAS_BLOCKED and return S_OK.

Note to Callers

When checking for a normal state, use the UAS_MASK value to mask unused bits in the pdwState parameter to this method for future compatibility. For example:

fNormal = ((pdwState & UAS_MASK) == UAS_NORMAL)

See Also

UASFLAGS


IOleUndoManager::Open

Opens a new parent undo unit, which becomes part of its containing unit’s undo stack.

HRESULT Open(

IOleParentUndoUnit* pPUU	//Pointer to the parent undo unit to open
);
Parameters

pPUU

[in] Pointer to the parent undo unit to be opened.

Return Values

S_OK

The parent undo unit was successfully opened or if a currently open unit is blocked. If the undo manager is currently disabled, it should return S_OK and do nothing else.

Remarks

This method is implemented the same as IOleParentUndoUnit::Open. The specified parent unit is created and remains open. The undo manager then calls the Add or Open methods on this parent unit to add new units to it. This parent unit receives any additional undo units until its Close method is called.

The parent unit specified by pPUU is not added to the undo stack until its Close method is called with the fCommit parameter set to TRUE.

The parent undo unit or undo manager must contain any undo unit given to it unless it is blocked. If it is blocked, it must return S_OK but should do nothing else.

See Also

IOleParentUndoUnit::Open


IOleUndoManager::RedoTo

Instructs the undo manager to invoke undo actions back through the redo stack, down to and including the specified undo unit.

HRESULT RedoTo(

IOleUndoUnit* pUU	//Pointer to the top level unit to redo
);
Parameters

pUU

[in] [in] Pointer to the top level unit to redo. If this parameter is NULL, the most recently added top level unit is used.

Return Values

S_OK

The specified undo unit was successfully invoked to perform its undo action.

E_INVALIDARG

The specified undo unit is not on the redo stack.

E_ABORT

Both the undo attempt and the rollback attempt failed. The undo manager should never propagate the E_ABORT obtained from a contained undo unit. Instead, it should map any E_ABORT values returned from other undo units to E_FAIL.

E_UNEXPECTED

The undo manager is disabled.

Remarks

This method calls the IOleUndoUnit::Do method on each top-level undo unit. Then, it releases that undo unit.

Note that the specified undo unit must be a top-level unit, typically retrieved through IOleUndoManager::EnumRedoable.

In case an error is returned from the undo unit, the undo manager needs to attempt to rollback the state of the document to recover from the error by performing actions on the redo stack.

No matter what the success of the rollback, the undo manager should always clear both stacks before returning the error.

If the undo manager has called the Do method on more than one top-level unit, it should only rollback the unit that returned the error. The top-level units that succeeded should not be rolled back.

The undo manager must also keep track of whether or not units were added to the opposite stack so it won’t attempt rollback if nothing was added. See the IOleUndoManager interface for detailed description of error handling.

See Also

IOleUndoManager::EnumRedoable, IOleUndoManager::UndoTo, IOleUndoUnit::Do


IOleUndoManager::UndoTo

Instructs the undo manager to invoke undo actions back through the undo stack, down to and including the specified undo unit.

HRESULT UndoTo(

IOleUndoUnit* pUU	//Pointer to the top level unit to undo
);
Parameters

pUU

[in] Pointer to the top level unit to undo. If this parameter is NULL, the most recently added top level unit is used.

Return Values

S_OK

The specified undo unit was successfully invoked to perform its undo action.

E_INVALIDARG

The specified undo unit is not on the undo stack.

E_ABORT

Both the undo attempt and the rollback attempt failed. The undo manager should never propagate the E_ABORT obtained from a contained undo unit. Instead, it should map any E_ABORT values returned from other undo units to E_FAIL.

E_UNEXPECTED

The undo manager is disabled.

Remarks

This method calls the IOleUndoUnit::Do method on each top-level undo unit. Then, it releases that undo unit.

Note that the specified undo unit must be a top-level unit, typically retrieved through IOleUndoManager::EnumUndoable.

In case an error is returned from the undo unit, the undo manager needs to attempt to rollback the state of the document to recover from the error by performing actions on the redo stack.

No matter what the success of the rollback, the undo manager should always clear both stacks before returning the error.

If the undo manager has called the Do method on more than one top-level unit, it should only rollback the unit that returned the error. The top-level units that succeeded should not be rolled back.

The undo manager must also keep track of whether or not units were added to the opposite stack so it won’t attempt rollback if nothing was added. See the IOleUndoManager interface for detailed description of error handling.

See Also

IOleUndoManager::EnumUndoable, IOleUndoManager::RedoTo, IOleUndoUnit::Do


IOleUndoUnit

The IOleUndoUnit interface is the main interface on an undo unit. An undo unit encapsulates the information necessary to undo or redo a single action.

When an object’s state changes and it needs to create an undo unit, it first needs to know what parent units are open. It calls the IOleUndoManager::GetOpenParentState method to determine this. If the call returns S_FALSE, then there is no enabling parent. If the call returns S_OK but the UAS_NOPARENTENABLE flag is set, then the open parent is a disabling parent. In either of these cases, the object calls IOleUndoManager::DiscardFrom(NULL) on the undo manager and skips creating the undo unit.

If the method returns S_OK, but the UAS_BLOCKED flag is set, then the open parent is a blocking parent. The object does not need to create an undo unit, since it would be immediately discarded. If the return value is S_OK and neither of the bit flags are set, then the object creates the undo unit and calls IOleUndoManager::Add on the undo manager.

The object should retain a pointer to the undo manager.

When to Implement

An object creates an undo unit that implements this interface when the end user has performed an action that can be undone. The object calls the IOleUndoManager::Add method to add the undo unit to the undo stack. Most controls can implement this interface to support the centralized undo operations. They do not have to implement IOleParentUndoUnit or IOleUndoManager. The undo manager with the IOleUndoManager interface is usually provided by the object container.

When to Use

The undo manager calls the Do and GetDescription methods in this interface to perform undo actions and to get strings that can be displayed in the user interface to describe the undo action. A parent undo unit can call the GetUnitType and OnNextAdd methods.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleUndoUnit Methods	Description
Do	Instructs the undo unit to carry out its action.
GetDescription	Returns a string that describes the undo unit and can be used in the undo or redo user interface.
GetUnitType	Returns the CLSID and a type identifier for the undo unit.
OnNextAdd	Notifies the last undo unit in the collection that a new unit has been added.
See Also

IOleParentUndoUnit, IOleUndoManager


IOleUndoUnit::Do

Instructs the undo unit to carry out its action. Note that if it contains child undo units, it must call their Do methods as well.

HRESULT Do(

IOleUndoManager* pUndoManager	//Pointer to the undo manager
);
Parameters

pUndoManager

[in] Pointer to the undo manager.

Return Values

S_OK

The undo unit successfully carried out its action.

Remarks

The undo unit is responsible for carrying out its action. Performing its own undo action results in another action that can potentially be reversed. However, if pUndoManager is NULL, the undo unit should perform its undo action but should not attempt to put anything on the redo or undo stack.

If pUndoManager is not NULL, then the unit is required to put a corresponding unit on the redo or undo stack. As a result, this method either moves itself to the redo or undo stack, or it creates a new undo unit and adds it to the appropriate stack. After creating a new undo unit, this undo unit calls IOleUndoManager::Open or IOleUndoManager::Add. The undo manager will put the new undo unit on the undo or redo stack depending on its current state.

A parent unit must pass to its children the same undo manager, possibly NULL, that was given to the parent. It is permissible, but not necessary, when pUndoManager is NULL to open a parent unit on the redo or undo stack as long as it is not committed. A blocked parent unit ensures that nothing is added to the stack by child units.

If this undo unit is a parent unit, it should put itself on the redo or undo stack before calling the Do on its children.

After calling this method, the undo manager must release the undo unit.

Note to Implementers

See the IOleUndoManager interface for error handling strategies for undo units. The error handling strategy affects the implementation of this method, particularly for parent units.

See Also

IOleUndoManager::Add, IOleUndoManager::Open


IOleUndoUnit::GetDescription

Returns a string that describes the undo unit and can be used in the undo or redo user interface.

HRESULT GetDescription(

BSTR* pbstr	//Pointer to string
);
Parameters

pbstr

[out] Pointer to string describing this undo unit.

Return Values

S_OK

The string was successfully returned.

Remarks

All units are required to provide a user-readable description of themselves.

Note to Callers

The *pbstr parameter is allocated with the standard string allocator. The caller is responsible for freeing this string.


IOleUndoUnit::GetUnitType

Returns the CLSID and a type identifier for the undo unit.

HRESULT GetUnitType(

CLSID* pClsid ,	//Pointer to CLSID for undo unit
LONG* plID	//Pointer to type identifier for undo unit
);
Parameters

pclsid

[out] Pointer to CLSID for the undo unit.

plID

[out] Pointer to the type identifier for the undo unit.

Return Values

S_OK

Both the CLSID and type identifier were successfully returned.

Remarks

A parent undo unit can call this method on its child units to determine whether it can apply special handling to them. The CLSID returned can be the CLSID of the undo unit itself, of its creating object, or an arbitrary GUID. The undo unit has the option of returning CLSID_NULL, in which case the caller can make no assumptions about the type of this unit. The only requirement is that the CLSID and type identifier together uniquely identify this type of undo unit.

Note that the undo manager and parent undo units do not have the option of accepting or rejecting child units based on their type.


IOleUndoUnit::OnNextAdd

Notifies the last undo unit in the collection that a new unit has been added.

HRESULT OnNextAdd(void);

Return Values

S_OK

Implementations of this method always return S_OK. The HRESULT return type is provided only for remotability.

Remarks

An object can create an undo unit for an action and add it to the undo manager but can continue inserting data into it through private interfaces. When the undo unit receives a call to this method, it communicates back to the creating object that the context has changed. Then, the creating object stops inserting data into the undo unit.

The parent undo unit calls this method on its most recently added child undo unit to notify the child unit that the context has changed and a new undo unit has been added.

For example, this method is used for supporting fuzzy actions, like typing, which do not have a clear point of termination but instead are terminated only when something else happens.

This method may not always be called if the undo manager or an open parent unit chooses to discard the unit by calling Release instead. Any connection which feeds data to the undo unit behind the scenes through private interfaces should not AddRef the undo unit.

Note to Implementers

Note that parent units merely delegate this method to their most recently added child unit. A parent unit should terminate communication through any private interfaces when it is closed. A parent unit knows it is being closed when it receives S_FALSE from calling IOleParentUndoUnit::Close.

See Also

IOleParentUndoUnit::Close


IOleWindow

The IOleWindow interface provides methods that allow an application to obtain the handle to the various windows that participate in in-place activation, and also to enter and exit context-sensitive help mode.

Several other in-place activation interfaces are derived from the IOleWindow interface. Containers and objects must implement and use these interfaces in order to support in-place activation. The following table briefly summarizes each of these interfaces:

IOleWindow	The base interface. Implemented and used by containers and objects to obtain window handles and manage context-sensitive help.
IOleInPlaceObject	Implemented by objects and used by an object’s immediate container to activate and deactivate the object.
IOleInPlaceActiveObject	Implemented by objects and used by the top-level container to manipulate the object while it is active. Provides a direct channel of communication between an active object and its frame and document windows.
IOleInPlaceUIWindow	Implemented by containers and used by objects to manipulate the container’s document window.
IOleInPlaceFrame	Implemented by containers and used by objects to control the container’s frame window.
IOleInPlaceSite	Implemented by containers and used by objects to interact with the in-place client site.
IOleInPlaceSiteEx	Implemented by containers and called by objects to optimize activation and deactivation.
IOleInPlaceSiteWIndowless	Implemented by containers and called by windowless object to obtain services from its container.
IOleInPlaceObjectWindowless	Implemented by windowless objects called by containers to support window message processing and drag and drop operations for windowless objects.
These interfaces can be arranged in three hierarchical levels with various interfaces implemented at each level. Calls that install user-interface menus commands and frame adornments, activate and switch between windows, and dispatch menu and keystrokes take place between the top-level container and the active object. Calls that support activating, deactivating, scrolling, or clipping span the containment hierarchy, with each level performing the correct actions.

When to Implement

The inherited methods of this interface are implemented by all in-place objects and containers.

When to Use

Use this interface to obtain the window handle to the windows associated with in-place activation (frame, document, parent, and in-place object). It is also used to enter and exit context-sensitive help.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOleWindow Methods	Description
GetWindow	Gets a window handle.
ContextSensitiveHelp	Controls enabling of context-sensitive help.
See Also

IOleInPlaceObject, IOleInPlaceActiveObject, IOleInPlaceUIWindow, IOleInPlaceFrame, IOleInPlaceSite, OleCreateMenuDescriptor, OleDestroyMenuDescriptor, OleTranslateAccelerator, IOleInPlaceSiteEx, IOleInPlaceSiteWIndowless, IOleInPlaceObjectWindowless


IOleWindow::ContextSensitiveHelp

Determines whether context-sensitive help mode should be entered during an in-place activation session.

HRESULT ContextSensitiveHelp(

BOOL fEnterMode	//Specifies whether or not to enter help mode
);
Parameter

fEnterMode

[in] TRUE if help mode should be entered; FALSE if it should be exited.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The help mode was entered or exited successfully, depending on the value passed in fEnterMode.

Remarks

Applications can invoke context-sensitive help when the user

•	Presses SHIFT+F1, then clicks a topic.

•	Presses F1 when a menu item is selected.

When SHIFT+F1 is pressed, either the frame or active object can receive the keystrokes. If the container’s frame receives the keystrokes, it calls its containing document’s IOleWindow::ContextSensitiveHelp method with fEnterMode set to TRUE. This propagates the help state to all of its in-place objects so they can correctly handle the mouse click or WM_COMMAND.

If an active object receives the SHIFT+F1 keystrokes, it calls the container’s IOleInPlaceSite::ContextSensitiveHelp method with fEnterMode TRUE, which then recursively calls each of its in-place sites until there are no more to be notified. The container then calls its document’s or frame’s ContextSensitiveHelp method with fEnterMode TRUE.

When in context-sensitive help mode, an object that receives the mouse click can either:

1.	Ignore the click if it does not support context-sensitive help, or

2.	Tell all the other objects to exit context-sensitive help mode with ContextSensitiveHelp set to FALSE and then provide help for that context.

An object in context-sensitive help mode that receives a WM_COMMAND should tell all the other in-place objects to exit context-sensitive help mode and then provide help for the command.

If a container application is to support context-sensitive help on menu items, it must either provide its own message filter so that it can intercept the F1 key or ask the OLE library to add a message filter by calling OleSetMenuDescriptor, passing valid, non-NULL values for the lpFrame and lpActiveObj parameters.

See Also

OleSetMenuDescriptor


IOleWindow::GetWindow

Returns the window handle to one of the windows participating in in-place activation (frame, document, parent, or in-place object window).

HRESULT GetWindow(

HWND * phwnd	//Pointer to where to return window handle
);
Parameter

phwnd

[out] Pointer to where to return the window handle.

Return Values

This method supports the standard return values E_FAIL, E_OUTOFMEMORY, E_INVALIDARG, and E_UNEXPECTED, as well as the following:

S_OK

The window handle was successfully returned.

Note  For windowless objects, this method should always fail and return E_FAIL.

Remarks

Five types of windows comprise the windows hierarchy. When a object is active in place, it has access to some or all of these windows:

Window	Description
Frame	The outermost main window where the container application’s main menu resides.
Document	The window that displays the compound document containing the embedded object to the user.
Pane	The subwindow of the document window that contains the object’s view. Applicable only for applications with split-pane windows.
Parent	The container window that contains that object’s view. The object application installs its window as a child of this window.
In-place	The window containing the active in-place object. The object application creates this window and installs it as a child of its hatch window, which is a child of the container’s parent window.
Each type of window has a different role in the in-place activation architecture. However, it is not necessary to employ a separate physical window for each type. Many container applications use the same window for their frame, document, pane, and parent windows.


IParseDisplayName

The IParseDisplayName interface parses a displayable name string to convert it into a moniker. Display name parsing is necessary when the end user inputs a string to identify a component, as in the following situations:

•	A compound document application that supports linked components typically supports the Edit:Links... dialog box. Through this dialog box, the end user can enter a display name to specify a new link source for a specified linked component. The compound document needs to have this input string converted into a moniker.

•	A script language such as the macro language of a spreadsheet can allow textual references to a component. The language’s interpreter needs to have such a reference converted into a moniker in order to execute the macro.

When to Implement

Compound document applications that support links to embedded components or to pseudo-objects within their documents must provide an implementation of the IOleItemContainer interface, which is derived indirectly from IParseDisplayName. In effect, such a compound document is providing a namespace for identifying its internal components; and its IOleItemContainer implementation (which includes the IParseDisplayName implementation) is the interface through which another application can access this namespace. Alternatively, the compound document application can implement IParseDisplayName as part of its class object, which is accessible through the CoGetClassObject function.

When to Use

If you are implementing your own moniker class, you might need to use this interface from your implementation of IMoniker::ParseDisplayName. If you call the MkParseDisplayName function, you are indirectly using IParseDisplayName.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IParseDisplayName Method	Description
ParseDisplayName	Parses the display name.
See Also

IMoniker::ParseDisplayName, IOleItemContainer, MkParseDisplayName


IParseDisplayName::ParseDisplayName

Parses the display name to extract a component of the string that it can convert into a moniker, using the maximum number of characters from the left side of the string.

HRESULT ParseDisplayName(

IBindCtx *pbc,	//Pointer to bind context
LPOLESTR pszDisplayName,	//Pointer to string containing display name
ULONG *pchEaten,	//Pointer to length, in characters, of display name
IMoniker **ppmkOut	//Indirect pointer to moniker that results
);
Parameters

pbc

[in] Pointer to the bind context to be used in this binding operation.

pszDisplayName

[in] Pointer to a zero-terminated string containing the display name to be parsed. For Win32 applications, the LPOLESTR type indicates a wide character string (two bytes per character); otherwise, the string has one byte per character.

pchEaten

[out Pointer to the number of characters in the display name that correspond to the ppmkOut moniker.

ppmkOut

[out] Indirect pointer to the resulting moniker. If an error occurs, the implementation sets *ppmkOut to NULL. If *ppmkOut is non-NULL, the implementation must call (*ppmkOut)->IUnknown::AddRef; so it is the caller’s responsibility to call (*ppmkOut)->IUnknown::Release.

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

Success.

MK_E_SYNTAX

Syntax error in the display name.

MK_E_NOOBJECT

The display name does not identify a component in this namespace.

See Also

MkParseDisplayName, IMoniker::ParseDisplayName


IPerPropertyBrowsing

The IPerPropertyBrowsing interface accesses the information in the property pages offered by an object.

When to Implement

Implement this interface on all objects that have property pages so that clients can access information about the properties.

When to Use

Use this interface to access information about an object’s properties.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IPerPropertyBrowsing Methods	Description
GetDisplayString	Returns a text string describing the specified property.
MapPropertyToPage	Returns the CLSID of the property page that allows manipulation of the specified property.
GetPredefinedStrings	Returns a counted array of strings (LPOLESTR pointers) listing the descriptions of the allowable values that the specified property can accept (i.e., the values returned from IPerPropertyBrowsing::GetPredefinedValue.
GetPredefinedValue	Returns a VARIANT containing the value of a property identified with dispID that is associated with a predefined string name as returned from IPerPropertyBrowsing::GetPredefinedStrings.
See Also

IPropertyPage, IPropertyPage2, IPropertyPageSite, ISpecifyPropertyPages


IPerPropertyBrowsing::GetDisplayString

Returns a text string describing the property identified with dispID in the caller’s user interface. In other words, the returned text is a displayable name describing the property and can be displayed in the caller’s user interface. The string itself is a BSTR allocated by this method with SysAllocString. Upon return, the string is the responsibility of the caller, which must free it with SysFreeString when it is no longer needed.

HRESULT GetDisplayString(

DISPID dispID ,	//Dispatch identifier for the property
BSTR *pbstr	//Receives a pointer to the displayable string describing the property
);
Parameters

dispID

[in] Dispatch identifier of the property whose display name is requested.

pbstr

[out] Pointer to the BSTR containing the display name for the property identified with dispID.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The display name was successfully returned.

E_NOTIMPL

The object does not provide display names for individual properties. The caller has the recourse to check the object’s type information for the text name of the object in this case.

E_POINTER

The address in pbstr is not valid. For example, it may be NULL.

Remarks

Notes to Implementers

The caller is responsible for freeing the pbstr string with SysFreeString when it is no longer needed.


IPerPropertyBrowsing::GetPredefinedStrings

Returns a counted array of string pointers (LPOLESTR pointers). The strings pointed to provide a list of names that each correspond to values that the property specified with dispID can accept.

HRESULT GetPredefinedStrings(

DISPID dispID ,	//Dispatch identifier for property
CALPOLESTR *pcaStringsOut ,	//Receives a pointer to an array of strings
CADWORD *pcaCookiesOut	//Receives a pointer to array of DWORDs
);
Parameters

dispID

[in] Dispatch identifier of the property for which the caller is requesting the string list.

pcaStringsOut

[out] Pointer to a caller-allocated, counted array structure that contains the element count and address of a method-allocated array of string pointers. This method also allocates memory for the string values containing the predefined names, and it stores the string pointers in the array. If the method fails, no memory is allocated, and the contents of the structure are undefined.

pcaCookiesOut

[out] Pointer to the caller-allocated, counted array structure that contains the element count and address of a method-allocated array of DWORDs. The DWORD values in the array can be passed to IPerPropertyBrowsing::GetPredefinedValue to retrieve the value associated with the name in the same array position inside pcaStringsOut. If the method fails, no memory is allocated, and the contents of the structure are undefined.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The arrays were allocated and filled successfully.

E_NOTIMPL

This method is not implemented and predefined names are not supported.

E_POINTER

The address in pcaStringsOut or pcaCookiesOut is not valid. For example, either may be NULL.

Remarks

Each string returned in the array pointed to by pcaStringsOut has a matching token in the counted array pointed to by pcaCookiesOut, where the token can be passed to IPerPropertyBrowsing::GetPredefinedValue to get the actual value (a VARIANT) corresponding to the string.

Using the predefined strings, a caller can obtain a list of strings for populating user interface elements, such as a drop-down listbox. When the end user selects one of these strings as a value to assign to a property, the caller can then obtain the corresponding value through IPerPropertyBrowsing::GetPredefinedValue.

Notes to Callers

Both the CALPOLESTR and CADWORD structures passed to this method are caller-allocated. The caller is responsible for freeing each string pointed to from the CALPOLESTR array as well as the CALPOLESTR structure.

All memory is allocated with CoTaskMemAlloc. The caller is responsible for freeing the strings and the array with CoTaskMemFree.

Upon return from this method, the caller is responsible for all this memory and must free it when it is no longer needed. Code to achieve this appears as follows:

CALPOLESTR     castr;

CWDWORD        cadw;

ULONG          i;

pIPerPropertyBrowsing->GetPredefinedStrings(dispID, &castr, &cadw);

//...Use the strings and the cookies

CoTaskMemFree((void *)cadw.pElems);

for (i=0; i < castr.cElems; i++)

    CoTaskMemFree((void *)castr.pElems[i]);

CoTaskMemFree((void *)castr.pElems);

Notes to Implementers

Support for predefined names and values is not required. If your object does not support these names, return E_NOTIMPL from this method. If this method is not implemented, IPerPropertyBrowsing::GetPredefinedValue must not be implemented either.

This method fills the cElems and pElems fields of the CADWORD and CALPOLESTR structures. It allocates the arrays pointed to by these structures with CoTaskMemAlloc and fills those arrays. In the CALPOLESTR case, this method also allocates each string with CoTaskMemAlloc, storing each string pointer in the array.

See Also

CADWORD, CALPOLESTR, CoTaskMemAlloc, CoTaskMemFree, IPerPropertyBrowsing::GetPredefinedValue


IPerPropertyBrowsing::GetPredefinedValue

Returns a VARIANT containing the value of the property specified by dispID. This property is associated with a predefined string name as returned from IPerPropertyBrowsing::GetPredefinedStrings. The predefined string is identified by a token returned from GetPredefinedStrings.

HRESULT GetPredefinedValue(

DISPID dispID ,	//Dispatch identifier for property
DWORD dwCookie ,	//Token returned
VARIANT *pVarOut	//Receives a pointer to a VARIANT value for the property
);
Parameters

dispID

[in] Dispatch identifier of the property for which a predefined value is requested.

dwCookie

[in] Token identifying which value to return. The token was previously returned in the pcaCookiesOut array filled by IPerPropertyBrowsing::GetPredefinedStrings.

pVarOut

[out] Pointer to the VARIANT value for the property.

Return Values

This method supports the standard return values E_INVALIDARG,

E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The value was returned successfully.

E_NOTIMPL

This object does not support predefined strings or predefined values.

E_POINTER

The address in pVarOut is not valid. For example, it may be NULL.

Remarks

Notes to Callers

The caller is responsible for freeing any allocations contained in the VARIANT. Unless the vt field of VARIANT is VT_VARIANT, the caller can free memory using a single call to VariantClear. Otherwise, the caller must recursively free the contained VARIANTs before freeing the outer VARIANT.

Notes to Implementers

Support for predefined names and values is not required. If your object does not support these names, return E_NOTIMPL from this method. If this method is not implemented, IPerPropertyBrowsing::GetPredefinedStrings must not be implemented either.

This method allocates any memory needed inside the VARIANT.

See Also

IPerPropertyBrowsing::GetPredefinedStrings


IPerPropertyBrowsing::MapPropertyToPage

Returns the CLSID of the property page associated with the specified property. In other words, this method maps a specified property to the property page that allows a user to manipulate that property. The CLSID returned from this method can be passed to OleCreatePropertyFrameIndirect to specify the initial page to display in the property sheet.

HRESULT MapPropertyToPage(

DISPID dispID ,	//Dispatch identifier for the property
CLSID *pclsid	//Receives a pointer to CLSID for property
);
Parameters

dispID

[in] Dispatch identifier of the property of interest.

pclsid

[out] Pointer to the CLSID identifying the property page associated with the property specified by dispID. If this method fails, *pclsid is set to CLSID_NULL.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The CLSID was successfully returned.

E_NOTIMPL

The object does not support property pages at all or doesn’t support mapping properties to the page CLSID. In other words, this feature of specific property browsing is not supported.

E_POINTER

The address in pclsid is not valid. For example, it may be NULL.


IPersist

The IPersist interface defines the single method GetClassID, which is designed to supply the CLSID of an object that can be stored persistently in the system. A call to this method can allow the object to specify which object handler to use in the client process, as it is used in the OLE default implementation of marshaling.

IPersist is the base interface for three other interfaces: IPersistStorage, IPersistStream, and IPersistFile. Each of these interfaces, therefore, includes the GetClassID method, and the appropriate one of these three interfaces is implemented on objects that can be serialized to a storage, a stream, or a file. The methods of these interfaces allow the state of these objects to be saved for later instantiations, and load the object using the saved state. Typically, the persistence interfaces are implemented by an embedded or linked object, and are called by the container application or the default object handler

When to Implement

You must implement the single method of IPersist in implementing any one of the other persistence interfaces: IPersistStorage, IPersistStream, or IPersistFile. Typically, for example, you would implement IPersistStorage on an embedded object, IPersistFile on a linked object, and IPersistStream on a new moniker class, although their uses are not limited to these objects. You could implement IPersist in a situation where all that is required is to obtain the CLSID of a persistent object, as it is used in marshaling.

When to Use

The single method of IPersist is rarely called directly in application code. It is called by the default object handler to get the CLSID of an embedded object, or an object to be marshaled. A container application, for example, would probably not call the GetClassID method directly unless it provided object handlers for specific classes of objects.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IPersist Method	Description
GetClassID	Returns the class identifier (CLSID) for the component object.


IPersist::GetClassID

Retrieves the class identifier (CLSID) of an object. The CLSID is a unique value that identifies the code that can manipulate the persistent data.

HRESULT GetClassID(

CLSID *pClassID	//Pointer to CLSID of object
);
Parameter

pClassID

[out]Points to the location of the CLSID on return. The CLSID is a globally unique identifier (GUID) that uniquely represents an object class that defines the code that can manipulate the object’s data.

Return Values

S_OK

The CLSID was successfully retrieved.

E_FAIL

The CLSID could not be retrieved.

Remarks

The GetClassID method retrieves the class identifier (CLSID) for an object, used in later operations to load object-specific code into the caller’s context.

Notes to Callers

A container application might call this method to retrieve the original CLSID of an object that it is treating as a different class. Such a call would be necessary if a user performed an editing operation that required the object to be saved. If the container were to save it using the treat-as CLSID, the original application would no longer be able to edit the object. .Typically, in this case, the container calls the OleSave helper function, which performs all the necessary steps. For this reason, most container applications have no need to call this method directly.

The exception would be a container that provides an object handler for certain objects. In particular, a container application should not get an object’s CLSID and then use it to retrieve class specific information from the registry. Instead, the container should use IOleObject and IDataObject interfaces to retrieve such class-specific information directly from the object.

Notes to Implementers

Typically, implementations of this method simply supply a constant CLSID for an object. If, however, the object’s TreatAs registry key has been set by an application that supports emulation (and so is treating the object as one of a different class), a call to IPersist::GetClassID must supply the CLSID specified in the TreatAs key. For more information on emulation, refer to CoTreatAsClass.

When an object is in the running state, the default handler calls an implementation of IPersist::GetClassID that delegates the call to the implementation in the object. When the object is not running, the default handler instead calls the ReadClassStg function to read the CLSID that is saved in the object’s storage.

If you are writing a custom object handler for your object, you might want to simply delegate this method to the default handler implementation (see OleCreateDefaultHandler).

See Also

IPersistStorage, IPersistStream, IPersistFile, ReadClassStg


IPersistFile

The IPersistFile interface provides methods that permit an object to be loaded from or saved to a disk file, rather than a storage object or stream. Because the information needed to open a file varies greatly from one application to another, the implementation of IPersistFile::Load on the object must also open its disk file.

The IPersistFile interface inherits its definition from IPersist, so all implementations must also include the GetClassID method of IPersist.

When to Implement

Implement IPersistFile when you want to read or write information from a separate file, which could be of any file format.

This interface should be implemented on any objects that support linking through a file moniker, including the following:

•	Any object that supports links to its files or to pseudo-objects within its files

•	A container application that supports links to objects within its compound file

Typically, you implement the IPersistFile interface as part of an aggregate object that includes other interfaces that are appropriate for the type of moniker binding that is supported.

For example, in either of the cases mentioned above, the moniker for the linked object can be a composite moniker. In the first case, a composite moniker identifies the pseudo-object contained within the file. In the second case, a composite moniker identifies the embedded object contained within the compound file. In either case of composite monikers, you must implement the IPersistFile interface as part of the same object on which the IOleItemContainer interface is implemented. Then, when the application for the linked object is run, OLE queries for the IOleItemContainer interface to locate the embedded object or the pseudo-object contained in the file.

As another example, if the moniker is a simple file moniker (i.e., the link is to the entire file), OLE queries for the interface that the initiator of the bind operation requested. Typically, this is one of the compound document interfaces, such as IOleObject, IDataObject, or IPersistStorage.

When to Use

Call methods in the IPersistFile interface to load or save a linked object in a specified file.

When IPersistFile is implemented on an object that supports linking through a file moniker and the application for the linked object is run, OLE calls IPersistFile::Load. Once the file is loaded, OLE calls IPersistFile::QueryInterface to get another interface pointer to the loaded object. The IPersistFile interface is typically part of an aggregate object that offers other interfaces.

In this case, the only IPersistFile method that OLE calls is the Load method to load a file linked to a container, running the application associated with the file. It would also be unusual for applications to call other methods in this case, which support saving an object to a file. Generally, it is left to the end user and the application for the linked object to decide when to save the object. This differs from the situation for an embedded object, in which the container application uses the IPersistStorage interface to provide the storage and to tell the object when to save itself.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IPersist Method	Description
GetClassID	Returns the class identifier (CLSID) for the component object.
IPersistFile Methods	Description
IsDirty	Checks an object for changes since it was last saved to its current file.
Load	Opens the specified file and initializes an object from the file contents.
Save	Saves the object into the specified file.
SaveCompleted	Notifies the object that it can revert from NoScribble mode to Normal mode.
GetCurFile	Gets the current name of the file associated with the object.


IPersistFile::GetCurFile

Retrieves either the absolute path to the object’s current working file or, if there is no current working file, the object’s default filename prompt.

HRESULT GetCurFile(

LPOLESTR *ppszFileName	//Pointer to the path for the current file or the default save prompt
);
Parameter

ppszFileName

[out]Points to the location of a pointer to a zero-terminated string containing the path for the current file or the default filename prompt (such as *.txt). If an error occurs, ppszFileName is set to NULL.

Return Values

S_OK

A valid absolute path was successfully returned.

S_FALSE

The default save prompt was returned.

E_OUTOFMEMORY

The operation failed due to insufficient memory.

E_FAIL

The operation failed due to some reason other than insufficient memory.

Remarks

This method returns the current filename or the default save prompt for the object.

This method allocates memory for the string returned in the ppszFileName parameter using the IMalloc::Alloc method. The caller is responsible for calling the IMalloc::Free method to free the string. Both the caller and this method use the OLE task allocator provided by a call to CoGetMalloc.

The LPOLESTR type indicates a wide character string (two bytes per character); otherwise, the string has one byte per character.

The filename returned in ppszFileName is the name specified in a call to IPersistFile::Load when the document was loaded; or in IPersistFile::SaveCompleted if the document was saved to a different file.

If the object does not have a current working file, it should supply the default filename prompt that it would display in a “Save As” dialog. For example, the default save prompt for a word processor object could be:

*.txt

Notes to Callers

OLE does not call the IPersistFile::GetCurFile method. Applications would not call this method unless they are also calling the save methods of this interface.

In saving the object, you can call this method before calling IPersistFile:Save to determine whether the object has an associated file. If this method returns S_OK, you can then call IPersistFile::Save with a NULL filename and a TRUE value for the fRemember parameter to tell the object to save itself to its current file. If this method returns S_FALSE, you can use the save prompt returned in the ppszFileName parameter to ask the end user to provide a filename. Then, you can call IPersistFile::Save with the filename that the user entered to perform a “Save As” operation.

See Also

IPersistFile::Load, IPersistFile::Save, IPersistFile::SaveCompleted


IPersistFile::IsDirty

Checks an object for changes since it was last saved to its current file.

HRESULT IsDirty(void);

Return Values

S_OK

The object has changed since it was last saved.

S_FALSE

The object has not changed since the last save.

Remarks

This method checks whether an object has changed since it was last saved. Call it to determine whether an object should be saved before closing it. The dirty flag for an object is conditionally cleared in the IPersistFile::Save method.

Notes to Callers

OLE does not call IPersistFile::IsDirty. Applications would not call it unless they are also saving an object to a file.

You should treat any error return codes as an indication that the object has changed. Unless this method explicitly returns S_FALSE, assume that the object must be saved.

Notes to Implementers

An object with no contained objects simply checks its dirty flag to return the appropriate result.

A container with one or more contained objects must maintain an internal dirty flag that is set when any of its contained objects has changed since it was last saved. To do this, the container should maintain an advise sink by implementing the IAdviseSink interface. Then, the container can register each link or embedding for data change notifications with a call to IDataObject::DAdvise. Then, the container can set its internal dirty flag when it receives an IAdviseSink::OnDataChange notification. If the container does not register for data change notifications, the IPersistFile::IsDirty implementation would call IPersistStorage::IsDirty for each of its contained objects to determine whether they have changed.

The container can clear its dirty flag whenever it is saved, as long as the file to which the object is saved is the current working file after the save. Therefore, the dirty flag would be cleared after a successful “Save” or “Save As” operation, but not after a “Save A Copy As . . .” operation.

See Also

IAdviseSink::OnDataChange, IDataObject::DAdvise, IPersistStorage::IsDirty


IPersistFile::Load

Opens the specified file and initializes an object from the file contents.

HRESULT Load(

LPCOLESTR pszFileName,	//Pointer to absolute path of the file to open
DWORD dwMode	//Specifies the access mode from the STGM enumeration
);
Parameters

pszFileName

[in]Points to a zero-terminated string containing the absolute path of the file to open.

dwMode

[in]Specifies some combination of the values from the STGM enumeration to indicate the access mode to use when opening the file. IPersistFile::Load can treat this value as a suggestion, adding more restrictive permissions if necessary. If dwMode is zero, the implementation should open the file using whatever default permissions are used when a user opens the file.

Return Values

S_OK

The object was successfully loaded.

E_OUTOFMEMORY

The object could not be loaded due to a lack of memory.

E_FAIL

The object could not be loaded for some reason other than a lack of memory.

IPersistFile::Load STG_E_* error codes.

Remarks

IPersistFile::Load loads the object from the specified file. This method is for initialization only and does not show the object to the end user. It is not equivalent to what occurs when an end user selects the File Open command.

Notes to Callers

The BindToObject method in file monikers calls this method to load an object during a moniker binding operation (when a linked object is run). Typically, applications do not call this method directly.

Notes to Implementers

Because the information needed to open a file varies greatly from one application to another, the object on which this method is implemented must also open the file specified by the pszFileName parameter. This differs from the IPersistStorage::Load and IPersistStream::Load, in which the caller opens the storage or stream and then passes an open storage or stream pointer to the loaded object.

For an application that normally uses OLE compound files, your IPersistFile::Load implementation can simply call the StgOpenStorage function to open the storage object in the specified file. Then, you can proceed with normal initialization. Applications that do not use storage objects can perform normal file-opening procedures.

When the object has been loaded, your implementation should register the object in the Running Object Table (see IRunningObjectTable::Register).

See Also

IRunningObjectTable::Register, StgOpenStorage


IPersistFile::Save

Saves a copy of the object into the specified file.

HRESULT Save(

LPCOLESTR pszFileName,	//Pointer to absolute path of the file where the object is saved
BOOL fRemember	//Specifies whether the file is to be the current working file or not
);
Parameters

pszFileName

[in]Points to a zero-terminated string containing the absolute path of the file to which the object should be saved. If pszFileName is NULL, the object should save its data to the current file, if there is one.

fRemember

[in]Indicates whether the pszFileName parameter is to be used as the current working file. If TRUE, pszFileName becomes the current file and the object should clear its dirty flag after the save. If FALSE, this save operation is a “Save A Copy As ...” operation. In this case, the current file is unchanged and the object should not clear its dirty flag. If pszFileName is NULL, the implementation should ignore the fRemember flag.

Return Values

S_OK

The object was successfully saved.

E_FAIL

The file was not saved.

IPersistFile::Save STG_E_* errors.

Remarks

This method can be called to save an object to the specified file in one of three ways:

Save

Call IPersistFile::GetCurFile first to determine whether the object has an associated filename. If so, call IPersistFile::Save specifying NULL for the pszFileName parameter in this method to indicate that the object should be saved to its current file. Then call IPersistFile::SaveCompleted to indicate completion.

Save As

Call IPersistFile::Save specifying TRUE in the fRemember parameter and a non-NULL value, indicating the name of the new file the object is to be saved to, for the pszFileName parameter . Then call IPersistFile::SaveCompleted to indicate completion.

Save a Copy As

Call IPersistFile::Save specifying FALSE in the fRemember parameter and a non-NULL value, indicating the name of the new file the object is to be copied to, for the pszFileName parameter.

The implementer must detect which type of save operation the caller is requesting. If the pszFileName parameter is NULL, a “Save” is being requested. If the pszFileName parameter is not NULL, use the value of the fRemember parameter to distinguish between a “Save As” and a “Save a Copy As”.

In “Save” or “Save As” operations, IPersistFile::Save clears the internal dirty flag after the save and sends IAdviseSink::OnSave notifications to any advisory connections (see also IOleAdviseHolder::SendOnSave). Also, in these operations, the object is in NoScribble mode until it receives an IPersistFile::SaveCompleted call. In NoScribble mode, the object must not write to the file.

In the “Save As” scenario, the implementation should also send IAdviseSink::OnRename notifications to any advisory connections (see also IOleAdviseHolder::SendOnRename).

In the “Save a Copy As” scenario, the implementation does not clear the internal dirty flag after the save.

Notes to Callers

OLE does not call IPersistFile::Save. Typically, applications would not call it unless they are saving an object to a file directly, which is generally left to the end-user.

See Also

IOleAdviseHolder::SendOnRename, IOleAdviseHolder::SendOnSave, IPersistFile::GetCurFile, IPersistFile::SaveCompleted


IPersistFile::SaveCompleted

Notifies the object that it can write to its file. It does this by notifying the object that it can revert from NoScribble mode (in which it must not write to its file), to Normal mode (in which it can). The component enters NoScribble mode when it receives an IPersistFile::Save call.

HRESULT SaveCompleted(

LPCOLESTR pszFileName	//Pointer to absolute path of the file where the object was saved
);
Parameter

pszFileName

[in]Points to the absolute path of the file where the object was previously saved.

Return Value

S_OK

Returned in all cases.

Remarks

IPersistFile::SaveCompleted is called when a call to IPersistFile::Save is completed, and the file that was saved is now the current working file (having been saved with “Save” or “Save As” operations). The call to Save puts the object into NoScribble mode so it cannot write to its file. When SaveCompleted is called, the object reverts to Normal mode, in which it is free to write to its file.

Notes to Callers

OLE does not call the IPersistFile::SaveCompleted method. Typically, applications would not call it unless they are saving objects directly to files, an operation which is generally left to the end-user.

See Also

IPersistFile::Save


IPersistMemory

The IPersistMemory interface operates exactly as IPersistStreamInit, except that it allows the caller to provide a fixed-size memory block (identified with a void *) as opposed to IPersistStreamInit which involves an arbitrarily expandable IStream.

The cbSize argument to the Load and Save methods indicate the amount of memory accessible through pvMem.

The IsDirty, GetSizeMax, and InitNew methods are semantically and syntactically identical to those in IPersistStreamInit. Only Load and Save differ.

When to Implement

An object implements this interface to save itself in memory.

When to Use

A container calls the methods of this interface to instruct an object to save and load itself in memory.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IPersist Method	Description
GetClassID	Returns the class identifier (CLSID) for the component object.
IPersistMemory Methods	Description
IsDirty	Checks the object for changes since it was last saved.
Load	Initializes an object from the memory block where it was previously saved.
Save	Saves an object into the specified memory block and indicates whether the object should reset its dirty flag.
GetSizeMax	Returns the size in bytes of the memory block needed to save the object.
InitNew	Initializes an object to a default state.


IPersistMemory::GetSizeMax

Returns the size in bytes of the memory block needed to save the object.

HRESULT GetSizeMax(

ULARGE_INTEGER* pcbSize	//Pointer to size of memory needed to save object
);
Parameter

pcbSize

[out]Pointer to a 64-bit unsigned integer value indicating the size in bytes of the memory needed to save this object.

Return Value

S_OK

The size was successfully returned.

Remarks

This method returns the size needed to save an object. You can call this method to determine the size and set the necessary buffers before calling the IPersistMemory::Save method.

Notes to Implementers

The GetSizeMax implementation must return a conservative estimate of the necessary size because the IPersistMemory::Save method uses a fixed size memory block.

See Also

IPersistMemory::Save


IPersistMemory::InitNew

Initializes the object to a default state. This method is called instead of IPersistMemory::Load.

HRESULT InitNew(void);

Return Values

S_OK

The object successfully initialized itself.

E_NOTIMPL

The object requires no default initialization. This error code is allowed because an object may choose to implement IPersistMemory simply for orthogonality or in anticipation of a future need for this method.

E_UNEXPECTED

This method was called after the object was already initialized with IPersistMemory::Load. Only one initialization is allowed per instance.

E_OUTOFMEMORY

There was not enough memory for the object to initialize itself.

Notes to Implementers

If the object has already been initialized with Load, then this method must return E_UNEXPECTED.

See Also

IPersistMemory::Load


IPersistMemory::IsDirty

Checks the object for changes since it was last saved.

HRESULT IsDirty(void);

Return Values

S_OK

The object has changed since it was last saved.

S_FALSE

The object has not changed since the last save.

Remarks

This method checks whether an object has changed since it was last saved so you can avoid losing information in objects that have not yet been saved. The dirty flag for an object is conditionally cleared in the IPersistMemory::Save method.

Notes to Callers

You should treat any error return codes as an indication that the object has changed. In other words, unless this method explicitly returns S_FALSE, you must assume that the object needs to be saved.

See Also

IPersistMemory::Save


IPersistMemory::Load

Instructs the object to load its persistent data from the memory pointed to by pvMem where cbSize indicates the amount of memory at pvMem. The object must not read past the address (BYTE*)((BYTE *)pvMem+cbSize).

HRESULT Load(

void* pvMem,	//Pointer to the stream from which the object should be loaded
ULONG cbSize	//Amount of memory from which the object can read its data
);
Parameters

pvMem

[in] Pointer to the address in memory from which the object can read up to cbSize bytes of its data.

cbSize

[in] The amount of memory available at pvMem from which the object can read its data.

Return Values

S_OK

The object successfully loaded its data.

E_UNEXPECTED

This method was called after the object was already initialized with IPersistMemory::Load. Only one initialization is allowed per instance.

E_POINTER

The pointer in pvMem is NULL.

Remarks

Any object that implements IPersistMemory has some information to load persistently, therefore E_NOTIMPL is not a valid return code.

See Also

IPersistMemory::InitNew


IPersistMemory::Save

Instructs the object to save its persistent data to the memory pointed to by pvMem where cbSize indicates the amount of memory available at pvMem. The object must not write past the address (BYTE*)((BYTE *)pvMem+cbSize). The fClearDirty flag determines whether the object is to clear its dirty state after the save is complete.

HRESULT Save(

void* pvMem,	//Pointer to the stream where the object is to be saved
BOOL fClearDirty,	//Specifies whether to clear the dirty flag
ULONG cbSize	//Amount of memory to which the object can write its data
);
Parameters

pvMem

[in] Pointer to the memory in which the object should save up to cbSize bytes of its data.

fClearDirty

[in] A flag indicating whether the object should clear its dirty state on return from Save or leave that state as-is.

cbSize

[in] The amount of memory available at pvMem to which the object can write its data.

Return Values

S_OK

The object successfully initialized itself.

E_UNEXPECTED

This method was called before the object was initialized with IPersistMemory::InitNew or IPersistMemory::Load.

E_INVALIDARG

The number of bytes indicated by cbSize is too small to allow the object to save itself completely.

E_POINTER

The pointer in pvMem is NULL.

Remarks

Any object that implements IPersistMemory has some information to save persistently, therefore E_NOTIMPL is not a valid return code.

The caller should ideally allocate as many bytes as the object returns from IPersistMemory::GetSizeMax.

See Also

IPersistMemory::InitNew, IPersistMemory::Load


IPersistPropertyBag

The IPersistPropertyBag interface works in conjunction with IPropertyBag and IErrorLog to define an individual property-based persistence mechanism. Whereas a mechanism like IPersistStream gives an object an IStream in which to store its binary data, IPersistPropertyBag provides an object with an IPropertyBag interface through which it can save and load individual properties. The implementer of IPropertyBag can then save those properties in whatever way it chooses, such as name/value pairs in a text file. Errors encountered in the process (on either side) are recorded in an error log through IErrorLog. This error reporting mechanism work on a per-property basis instead of an all properties as a whole basis through just the return value of IPersist*::Load or IPersist*::Save.

The basic mechanism is that a container tells the object to save or load its properties through IPersistPropertyBag. For each property, the object calls the container’s IPropertyBag interface passed to the IPersistPropertyBag methods. IPropertyBag::Write saves a property in whatever place the container wants to put it, and IPropertyBag::Read retrieves a property.

This protocol is essentially a means of sequentially communicating individual property values from the object to the container, which is useful for doing save-as-text operations and the like. The object gives the container the choice of the format in which each property is saved, while retaining itself the decision as to which properties are saved or loaded.

When to Implement

An object implements this interface to enable saving its properties persistently.

When to Use

A container calls the methods on this interface to instruct an object to load and save its properties to the supplied property bag.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IPersist Method	Description
GetClassID	Returns the class identifier (CLSID) for the component object.
IPersistPropertyBag Methods	Description
InitNew	Called by the container when the control is initialized to initialize the property bag.
Load	Called by the container to load the control’s properties.
Save	Called by the container to save the object’s properties.
See Also

IErrorLog, IPropertyBag


IPersistPropertyBag::InitNew

Called by the container when the control is initialized to initialize the property bag.

HRESULT InitNew(void);

Return Values

S_OK

The object successfully initialized itself. This should be returned even if the object doesn’t do anything in the method.

CO_E_ALREADYINITIALISED

The object has already been initialized.

E_OUTOFMEMORY

The storage object was not initialized due to a lack of memory.

E_UNEXPECTED

The storage object was not initialized due to some reason other than a lack of memory.

Remarks

This method informs the object that it is being initialized as a newly created object.

E_NOTIMPL should not be returned—use S_OK when the object has nothing to do in the method.

See Also

IPersistPropertyBag::Load


IPersistPropertyBag::Load

Called by the container to load the control’s properties.

HRESULT Load(

IPropertyBag* pPropBag,	//Pointer to caller’s property bag
IErrorLog* pErrorLog	//Pointer to error log
);
Parameters

pPropBag

[in] Pointer to the caller’s IPropertyBag interface bag that the control uses to read its properties. Cannot be NULL.

pErrorLog

[in] Pointer to the caller’s IErrorLog interface in which the object stores any errors that occur during initialization. Can be NULL in which case the caller is not interested in errors.

Return Values

S_OK

The object successfully initialized itself.

E_UNEXPECTED

This method was called after IPersistPropertyBag::InitNew has already been called. They two initialization methods are mutually exclusive.

E_OUTOFMEMORY

The properties were not loaded due to a lack of memory.

E_POINTER

The address in pPropBag is not valid (such as NULL) and therefore the object cannot initialize itself.

E_FAIL

The object was unable to retrieve a critical property that is necessary for the object’s successful operation. The object was therefore unable to initialize itself completely.

Remarks

This method instructs the object to initialize itself using the properties available in the property bag, notifying the provided error log object when errors occur. All property storage must take place within this method call as the object cannot hold the IPropertyBag pointer.

E_NOTIMPL is not a valid return code as any object implementing this interface must support the entire functionality of the interface.

See Also

IPersistPropertyBag::InitNew


IPersistPropertyBag::Save

Called by the container to save the object’s properties.

HRESULT Save(

IPropertyBag* pPropBag,	//Pointer to the caller’s property bag
BOOL fClearDirty,	//Specifies whether to clear the dirty flag
BOOL fSaveAllProperties	//Specifies whether to save all properties or just those that have changed
);
Parameters

pPropBag

[in] Pointer to the caller’s IPropertyBag interface through which the object can write properties. Cannot be NULL.

fClearDirty

[in] A flag indicating whether the object should clear its dirty flag when saving is complete. TRUE means clear the flag, FALSE means leave the flag unaffected. FALSE is used when the caller wishes to do a Save Copy As type of operation.

fSaveAllProperties

[in] A flag indicating whether the object should save all its properties (TRUE) or only those that have changed since the last save or initialization (FALSE).

Return Values

S_OK

The object successfully saved the requested properties itself.

E_FAIL

There was a problem saving one of the properties. The object can choose to fail only if a necessary property could not be saved, meaning that the object can assume default property values if a given property is not seen through IPersistPropertyBag::Load at some later time.

E_POINTER

The address in pPropBag is not valid (such as NULL) and therefore the object cannot initialize itself.

STG_E_MEDIUMFULL

The object was not saved because of a lack of space on the disk.

Remarks

This method instructs the object to save its properties to the specified property bag, optionally clearing the object’s dirty flag. The caller can request that the object save all properties or that the object save only those that are known to have changed.

E_NOTIMPL is not a valid return code as any object implementing this interface must support the entire functionality of the interface.

See Also

IPersistPropertyBag::InitNew, IPersistPropertyBag::Load


IPersistStorage

The IPersistStorage interface defines methods that enable a container application to pass a storage object to one of its contained objects and to load and save the storage object. This interface supports the structured storage model, in which each contained object has its own storage that is nested within the container’s storage.

The IPersistStorage contract inherits its definition from IPersist, so all implementations must also include the GetClassID method of IPersist.

When to Implement

Any object that can be embedded in a container must implement the IPersistStorage interface. This interface is one of the primary interfaces for a compound document object. Embeddable objects must also implement the IOleObject and IDataObject interfaces.

The OLE default handler for embedded objects provides an implementation of the IPersistStorage interface that is used when the object is in the loaded state. Similarly, the OLE default link handler provides an IPersistStorage implementation that manages storage for a linked object. These default handlers both interact with the OLE default cache implementation, which has its own IPersistStorage implementation.

If you are providing a custom embedding or link handler for your objects, the handler must include an implementation of IPersistStorage. You can delegate calls to the default handler so you can take advantage of the default cache implementation.

When to Use

When an OLE container creates a new object, loads an existing object from storage, or inserts a new object in a clipboard or a drag-and-drop operation, the container uses the IPersistStorage interface to initialize the object and put it in the loaded or running state. When an object is loaded or running, an OLE container calls other IPersistStorage methods to instruct the object to perform various save operations or to release its storage.

Typically, applications use helper functions such as OleLoad or OleCreate, rather than calling the IPersistStorage::Load or IPersistStorage::InitNew methods directly. Similarly, applications typically call the OleSave helper function rather than calling IPersistStorage::Save directly.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IPersist Method	Description
GetClassID	Returns the class identifier (CLSID) for the object on which it is implemented.
IPersistStorage Methods	Description
IsDirty	Indicates whether the object has changed since it was last saved to its current storage.
InitNew	Initializes a new storage object.
Load	Initializes an object from its existing storage.
Save	Saves an object, and any nested objects that it contains, into the specified storage object. The object enters NoScribble mode.
SaveCompleted	Notifies the object that it can revert from NoScribble or HandsOff mode, in which in must not write to its storage object, to Normal mode in which it can.
HandsOffStorage	Instructs the object to release all storage objects that have been passed to it by its container and to enter HandsOffAfterSave or HandsOffFromNormal mode.
See Also

IDataObject, IOleObject, OleCreate, OleLoad, OleSave


IPersistStorage::HandsOffStorage

Instructs the object to release all storage objects that have been passed to it by its container and to enter HandsOff mode, in which the object cannot do anything and the only operation that works is a close operation.

HRESULT HandsOffStorage(void);

Return Value

S_OK

The object has successfully entered HandsOff mode.

Remarks

This method causes an object to release any storage objects that it is holding and to enter the HandsOff mode until a subsequent IPersistStorage::SaveCompleted call. In HandsOff mode, the object cannot do anything and the only operation that works is a close operation.

A container application typically calls this method during a full save or low-memory full save operation to force the object to release all pointers to its current storage. In these scenarios, the HandsOffStorage call comes after a call to either OleSave or IPersistStorage::Save, putting the object in HandsOffAfterSave mode. Calling this method is necessary so the container application can delete the current file as part of a full save, or so it can call the IRootStorage::SwitchToFile method as part of a low-memory save.

A container application also calls this method when an object is in Normal mode to put the object in HandsOffFromNormal mode.

While the component object is in either HandsOffAfterSave or HandsOffFromNormal mode, most operations on the object will fail. Thus, the container should restore the object to Normal mode as soon as possible. The container application does this by calling the IPersistStorage::SaveCompleted method, which passes a storage pointer back to the component object for the new storage object.

Notes to Implementers

This method must release all pointers to the current storage object, including pointers to any nested streams and storages. If the object contains nested objects, the container application must recursively call this method for any nested objects that are loaded or running.

See Also

OleSave, IPersistStorage::Save, IPersistStorage::SaveCompleted, IRootStorage::SwitchToFile


IPersistStorage::InitNew

Initializes a new object, providing a pointer to the storage to be used for the object.

HRESULT InitNew(

IStorage *pStg	//Points to the new storage object
);
Parameter

pStg

[in]IStorage pointer to the new storage object to be initialized. The container creates a nested storage object in its storage object (see IStorage::CreateStorage). Then, the container calls the WriteClassStg function to initialize the new storage object with the object class identifier (CLSID).

Return Values

S_OK

The new storage object was successfully initialized.

CO_E_ALREADYINITIALIZED

The object has already been initialized by a previous call to either the IPersistStorage::Load method or the IPersistStorage::InitNew method.

E_OUTOFMEMORY

The storage object was not initialized due to a lack of memory.

E_FAIL

The storage object was not initialized for some reason other than a lack of memory.

Remarks

A container application can call this method when it needs to initialize a new object, for example, with an InsertObject command.

An object that supports the IPersistStorage interface must have access to a valid storage object at all times while it is running. This includes the time just after the object has been created but before it has been made persistent. The object’s container must provide the object with a valid IStorage pointer to the storage during this time through the call to IPersistStorage::InitNew. Depending on the container’s state, a temporary file might have to be created for this purpose.

If the object wants to retain the IStorage instance, it must call IUnknown::AddRef to increment its reference count.

After the call to IPersistStorage::InitNew, the object is in either the loaded or running state. For example, if the object class has an in-process server, the object will be in the running state. However, if the object uses the default handler, the container’s call to InitNew only invokes the handler’s implementation which does not run the object. Later if the container runs the object, the handler calls the IPersistStorage::InitNew method for the object.

Notes to Callers

Rather than calling IPersistStorage::InitNew directly, you typically call the OleCreate helper function which does the following:

1.	Calls the CoCreateInstance function to create an instance of the object class

2.	Queries the new instance for the IPersistStorage interface

3.	Calls the IPersistStorage::InitNew method to initialize the object

The container application should cache the IPersistStorage pointer to the object for use in later operations on the object.

Notes to Implementers

An implementation of IPersistStorage::InitNew should initialize the object to its default state, taking the following steps:

1.	Pre-open and cache the pointers to any streams or storages that the object will need to save itself to this storage.

2.	Call IPersistStorage::AddRef and cache the storage pointer that is passed in.

3.	Call the WriteFmtUserTypeStg function to write the native clipboard format and user type string for the object to the storage object.

4.	Set the dirty flag for the object.

The first two steps are particularly important for ensuring that the object can save itself in low memory situations. Pre-opening and holding onto pointers to the stream and storage interfaces guarantee that a save operation to this storage will not fail due to insufficient memory.

Your implementation of this method should return the CO_E_ALREADYINITIALIZED error code if it receives a call to either the IPersistStorage::InitNew method or the IPersistStorage::Load method after it is already initialized.

See Also

IPersistStorage::Load, OleCreate, WriteFmtUserTypeStg


IPersistStorage::IsDirty

Indicates whether the object has changed since it was last saved to its current storage.

HRESULT IsDirty(void);

Return Values

S_OK

The object has changed since it was last saved.

S_FALSE

The object has not changed since the last save.

Remarks

This method checks whether an object has changed since it was last saved so you can save it before closing it. The dirty flag for an object is conditionally cleared in the IPersistStorage::Save method.

For example, you could optimize a File:Save operation by calling the IPersistStorage::IsDirty method for each object and then calling the IPersistStorage::Save method only for those objects that are dirty.

Notes to Callers

You should treat any error return codes as an indication that the object has changed. In other words, unless this method explicitly returns S_FALSE, you must assume that the object needs to be saved.

Notes to Implementers

A container with one or more contained objects must maintain an internal dirty flag that is set whenever any of its contained objects are dirty.

See Also

IAdviseSink::OnDataChange, IDataObject::DAdvise, IPersistStorage::Save


IPersistStorage::Load

Loads an object from its existing storage.

HRESULT Load(

IStorage *pStg	//Pointer to existing storage for the object
);
Parameter

pStg

[in]IStorage pointer to the existing storage from which the object is to be loaded.

Return Values

S_OK

The object was successfully loaded.

CO_E_ALREADYINITIALIZED

The object has already been initialized by a previous call to the IPersistStorage::Load method or the IPersistStorage::InitNew method.

E_OUTOFMEMORY

The object was not loaded due to lack of memory.

E_FAIL

The object was not loaded due to some reason besides a lack of memory.

Remarks

This method initializes an object from an existing storage. The object is placed in the loaded state if this method is called by the container application. If called by the default handler, this method places the object in the running state.

Either the default handler or the object itself can hold onto the IStorage pointer while the object is loaded or running.

Notes to Callers

Rather than calling IPersistStorage::Load directly, you typically call the OleLoad helper function which does the following:

1.	Create an uninitialized instance of the object class

2.	Query the new instance for the IPersistStorage interface

3.	Call IPersistStorage::Load to initialize the object from the existing storage

You also call this method indirectly when you call the OleCreateFromData function or the OleCreateFromFile function to insert an object into a compound file (as in a drag-and-drop or clipboard paste operation).

The container should cache the IPersistStorage pointer for use in later operations on the object.

Notes to Implementers

Your implementation should perform the following steps to load an object:

1.	Open the object’s streams in the storage object, and read the necessary data into the object’s internal data structures.

2.	Clear the object’s dirty flag.

3.	Call the IPersistStorage::AddRef method and cache the passed in storage pointer.

4.	Keep open and cache the pointers to any streams or storages that the object will need to save itself to this storage.

5.	Perform any other default initialization required for the object.

Steps 3 and 4 are particularly important for ensuring that the object can save itself in low memory situations. Holding onto pointers to the storage and stream interfaces guarantees that a save operation to this storage will not fail due to insufficient memory.

Your implementation of this method should return the CO_E_ALREADYINITIALIZED error code if it receives a call to either the IPersistStorage::InitNew method or the IPersistStorage::Load method after it is already initialized.

See Also

GetConvertStg, IPersistStorage::InitNew, OleLoad, ReadFmtUserTypeStg, SetConvertStg, WriteFmtUserTypeStg


IPersistStorage::Save

Saves an object, and any nested objects that it contains, into the specified storage. The object is placed in NoScribble mode, and it must not write to the specified storage until it receives a call to its IPersistStorage::SaveCompleted method.

HRESULT Save(

IStorage *pStgSave,	//Pointer to storage object
BOOL fSameAsLoad	//Indicates whether the specified storage object is the current one
);
Parameters

pStgSave

[in]IStorage pointer to the storage into which the object is to be saved.

fSameAsLoad

[in]Indicates whether the specified storage is the current one, which was passed to the object by one of the following calls:

•	IPersistStorage::InitNew when it was created.

•	IPersistStorage::Load when it was loaded.

•	IPersistStorage::SaveCompleted when it was saved to a storage different from its current storage.

This parameter is set to FALSE when performing a Save As or Save A Copy To operation or when performing a full save. In the latter case, this method saves to a temporary file, deletes the original file, and renames the temporary file.

This parameter is set to TRUE to perform a full save in a low-memory situation or to perform a fast incremental save in which only the dirty components are saved.

Return Values

S_OK

The object was successfully saved.

STG_E_MEDIUMFULL

The object was not saved because of a lack of space on the disk.

E_FAIL

The object could not be saved due to errors other than a lack of disk space.

Remarks

This method saves an object, and any nested objects it contains, into the specified storage. It also places the object into NoScribble mode. Thus, the object cannot write to its storage until a subsequent call to the IPersistStorage::SaveCompleted method returns the object to Normal mode.

If the storage object is the same as the one it was loaded or created from, the save operation may be able to write incremental changes to the storage object. Otherwise, a full save must be done.

This method recursively calls the IPersistStorage::Save method, the OleSave function, or the IStorage::CopyTo method to save its nested objects.

This method does not call the IStorage::Commit method. Nor does it write the CLSID to the storage object. Both of these tasks are the responsibilities of the caller.

Notes to Callers

Rather than calling IPersistStorage::Save directly, you typically call the OleSave helper function which performs the following steps:

1.	Call the WriteClassStg function to write the class identifier for the object to the storage.

2.	Call the IPersistStorage::Save method.

3.	If needed, call the IStorage::Commit method on the storage object.

Then, a container application performs any other operations necessary to complete the save and calls the SaveCompleted method for each object.

If an embedded object passes the IPersistStorage::Save method to its nested objects, it must receive a call to its IPersistStorage::SaveCompleted method before calling this method for its nested objects.

See Also

IPersistStorage::InitNew, IPersistStorage::Load, IPersistStorage::SaveCompleted, OleSave, IStorage::Commit, IStorage::CopyTo, OleSave, WriteClassStg, WriteFmtUserTypeStg


IPersistStorage::SaveCompleted

Notifies the object that it can revert from NoScribble or HandsOff mode, in which it must not write to its storage object, to Normal mode, in which it can. The object enters NoScribble mode when it receives an IPersistStorage::Save call.

HRESULT SaveCompleted(

IStorage *pStgNew	//Pointer to the current storage object
);
Parameter

pStgNew

[in]IStorage pointer to the new storage object, if different from the storage object prior to saving. This pointer can be NULL if the current storage object does not change during the save operation. If the object is in HandsOff mode, this parameter must be non-NULL.

Return Values

S_OK

The object was successfully returned to Normal mode.

E_OUTOFMEMORY

The object remained in HandsOff mode or NoScribble mode due to a lack of memory. Typically, this error occurs when the object is not able to open the necessary streams and storage objects in pStgNew.

E_INVALIDARG

The pStgNew parameter is not valid. Typically, this error occurs if pStgNew is NULL when the object is in HandsOff mode.

E_UNEXPECTED

The object is in Normal mode, and there was no previous call to IPersistStorage::Save or IPersistStorage::HandsOffStorage.

Remarks

This method notifies an object that it can revert to Normal mode and can once again write to its storage object. The object exits NoScribble mode or HandsOff mode.

If the object is reverting from HandsOff mode, the pStgNew parameter must be non-NULL. In HandsOffFromNormal mode, this parameter is the new storage object that replaces the one that was revoked by the IPersistStorage::HandsOffStorage method. The data in the storage object is a copy of the data from the revoked storage object. In HandsOffAfterSave mode, the data is the same as the data that was most recently saved. It is not the same as the data in the revoked storage object.

If the object is reverting from NoScribble mode, the pStgNew parameter can be NULL or non-NULL. If NULL, the object once again has access to its storage object. If it is not NULL, the component object should simulate receiving a call to its IPersistStorage::HandsOffStorage method. If the component object cannot simulate this call, its container must be prepared to actually call the IPersistStorage::HandsOffStorage method.

The IPersistStorage::SaveCompleted method must recursively call any nested objects that are loaded or running.

If this method returns an error code, the object is not returned to Normal mode. Thus, the container object can attempt different save strategies.

See Also

IAdviseSink::OnSave, IOleObject::Close, IPersistStorage::HandsOffStorage, IPersistStorage::Save, IRootStorage::SwitchToFile


IPersistStream

The IPersistStream interface provides methods for saving and loading objects that use a simple serial stream for their storage needs. The IPersistStream interface inherits its definition from the IPersist interface, and so the includes the GetClassID method of IPersist.

One way in which it is used is to support OLE moniker implementations. Each of the OLE-provided moniker interfaces provides an IPersistStream implementation through which the moniker saves or loads itself. An instance of the OLE generic composite moniker class calls the IPersistStream methods of its component monikers to load or save the components in the proper sequence in a single stream.

OLE containers with embedded and linked component objects do not use this interface; they use the IPersistStorage interface instead.

When to Implement

Implement the IPersistStream interface on objects that are to be saved to a simple stream. Some objects of this type are monikers and some OLE controls, although generally, controls use the IPersistStreamInit interface, which has the same methods as IPersistStream, with one added method, IPersistStreamInit::InitNew. The IMoniker interface is derived from the IPersistStream interface, so you must implement the IPersistStream interface if you are implementing a new moniker class.

When to Use

Call methods of IPersistStream from a container application to save or load objects that are contained in a simple stream. When used to save or load monikers, typical applications do not call the methods directly, but allow the default link handler to make the calls to save and load the monikers that identify the link source. These monikers are stored in a stream in the storage for the linked object. If you are writing a custom link handler for your class of objects, you would call the methods of IPersistStream to implement the link handler.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IPersist Method	Description
GetClassID	Returns the class identifier (CLSID) for the component object.
IPersistStream Methods	Description
IsDirty	Checks the object for changes since it was last saved.
Load	Initializes an object from the stream where it was previously saved.
Save	Saves an object into the specified stream and indicates whether the object should reset its dirty flag.
GetSizeMax	Return the size in bytes of the stream needed to save the object.
See Also

IMoniker


IPersistStream::GetSizeMax

Returns the size in bytes of the stream needed to save the object.

HRESULT GetSizeMax(

ULARGE_INTEGER *pcbSize	//Pointer to size of stream needed to save object
);
Parameter

pcbSize

[out]Points to a 64-bit unsigned integer value indicating the size in bytes of the stream needed to save this object.

Return Value

S_OK

The size was successfully returned.

Remarks

This method returns the size needed to save an object. You can call this method to determine the size and set the necessary buffers before calling the IPersistStream::Save method.

Notes to Implementers

The GetSizeMax implementation should return a conservative estimate of the necessary size because the caller might call the IPersistStream::Save method with a non-growable stream.

See Also

IPersistStream::Save


IPersistStream::IsDirty

Checks the object for changes since it was last saved.

HRESULT IsDirty(void);

Return Values

S_OK

The object has changed since it was last saved.

S_FALSE

The object has not changed since the last save.

Remarks

This method checks whether an object has changed since it was last saved so you can avoid losing information in objects that have not yet been saved. The dirty flag for an object is conditionally cleared in the IPersistStream::Save method.

Notes to Callers

You should treat any error return codes as an indication that the object has changed. In other words, unless this method explicitly returns S_FALSE, you must assume that the object needs to be saved.

Note that the OLE-provided implementations of the IPersistStream::IsDirty method in the OLE-provided moniker interfaces always return S_FALSE because their internal state never changes.

See Also

IPersistStream::Save


IPersistStream::Load

Initializes an object from the stream where it was previously saved.

HRESULT Load(

IStream *pStm	//Pointer to the stream from which the object should be loaded
);
Parameter

pStm

[in]IStream pointer to the stream from which the object should be loaded.

Return Values

S_OK

The object was successfully loaded.

E_OUTOFMEMORY

The object was not loaded due to a lack of memory.

E_FAIL

The object was not loaded due to some reason other than a lack of memory.

Remarks

This method loads an object from its associated stream. The seek pointer is set as it was in the most recent IPersistStream::Save method. This method can seek and read from the stream, but cannot write to it.

On exit, the seek pointer must be in the same position it was in on entry, immediately past the end of the data.

Notes to Callers

Rather than calling IPersistStream::Load directly, you typically call the OleLoadFromStream function does the following:

1.	Calls the ReadClassStm function to get the class identifier from the stream.

2.	Calls the CoCreateInstance function to create an instance of the object.

3.	Queries the instance for IPersistStream.

4.	Calls IPersistStream::Load.

The OleLoadFromStream function assumes that objects are stored in the stream with a class identifier followed by the object data. This storage pattern is used by the generic, composite-moniker implementation provided by OLE.

If the objects are not stored using this pattern, you must call the methods separately yourself.

See Also

CoCreateInstance, OleLoadFromStream, ReadClassStm


IPersistStream::Save

Saves an object to the specified stream.

HRESULT Save(

IStream *pStm,	//Pointer to the stream where the object is to be saved
BOOL fClearDirty	//Specifies whether to clear the dirty flag
);
Parameters

pStm

[in]IStream pointer to the stream into which the object should be saved.

fClearDirty

[in]Indicates whether to clear the dirty flag after the save is complete. If TRUE, the flag should be cleared. If FALSE, the flag should be left unchanged.

Return Values

S_OK

The object was successfully saved to the stream.

STG_E_CANTSAVE

The object could not save itself to the stream. This error could indicate, for example, that the object contains another object that is not serializable to a stream or that an IStream::Write call returned STG_E_CANTSAVE.

STG_E_MEDIUMFULL

The object could not be saved because there is no space left on the storage device.

Remarks

IPersistStream::Save saves an object into the specified stream and indicates whether the object should reset its dirty flag.

The seek pointer is positioned at the location in the stream at which the object should begin writing its data. The object calls the IStream::Write method to write its data.

On exit, the seek pointer must be positioned immediately past the object data. The position of the seek pointer is undefined if an error returns.

Notes to Callers

Rather than calling IPersistStream::Save directly, you typically call the OleSaveToStream helper function which does the following:

1.	Calls IPersistStream::GetClassID to get the object’s CLSID.

2.	Calls the WriteClassStm function to write the object’s CLSID to the stream.

3.	Calls IPersistStream::Save.

If you call these methods directly, you can write other data into the stream after the CLSID before calling IPersistStream::Save.

The OLE-provided implementation of IPersistStream follows this same pattern.

Notes to Implementers

The IPersistStream::Save method does not write the CLSID to the stream. The caller is responsible for writing the CLSID.

The IPersistStream::Save method can read from, write to, and seek in the stream; but it must not seek to a location in the stream before that of the seek pointer on entry.

See Also

IPersist::GetClassID, IStream::Write, OleSaveToStream


IPersistStreamInit

The IPersistStreamInit interface is defined as a replacement for IPersistStream in order to add an initialization method, InitNew. This interface is not derived from IPersistStream; it is mutually exclusive with IPersistStream. An object chooses to support only one of the two interfaces, based on whether it requires the InitNew method. Otherwise, the signatures and semantics of the other methods are the same as the corresponding methods of IPersistStream, except as described below.

When to Implement

Implement this interface on any object that needs to support initialized stream-based persistence, regardless of whatever else the object does. The presence of the InitNew method requires some changes to other methods that are common to IPersistStream, as noted in the method descriptions.

When to Use

Use this interface to initialize a stream-based object and to save that object to a stream.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IPersistStreamInit Methods	Description
IsDirty	Checks the object for changes since it was last saved.
Load	Initializes an object from the stream where it was previously saved.
Save	Saves an object into the specified stream and indicates whether the object should reset its dirty flag.
GetSizeMax	Return the size in bytes of the stream needed to save the object.
InitNew	Initializes an object to a default state.
See Also

IPersistStream


IPersistStreamInit::GetSizeMax

Same as IPersistStream::GetSizeMax.

HRESULT GetSizeMax(

ULARGE_INTEGER* pcbSize	//Receives a pointer to the size of the stream needed to save object
);


IPersistStreamInit::InitNew

Initializes the object to a default state. This method is called instead of IPersistStreamInit::Load.

HRESULT InitNew(void);

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The object successfully initialized itself.

E_NOTIMPL

The object requires no default initialization. This error code is allowed because an object may choose to implement IPersistStreamInit simply for orthogonality or in anticipation of a future need for this method.

Remarks

Notes to Implementers

If the object has already been initialized with Load, then this method must return E_UNEXPECTED.

See Also

IPersistStreamInit::Load


IPersistStreamInit::IsDirty

Same as IPersistStream::IsDirty.

HRESULT IsDirty(void);


IPersistStreamInit::Load

Same as IPersistStream::Load.

HRESULT Load(

LPSTREAM pStm	//Pointer to the stream from which the object should be loaded
);
Remarks

Notes to Implementers

If the object has already been initialized with InitNew, then this method must return E_UNEXPECTED.


IPersistStreamInit::Save

Same as IPersistStream::Save.

HRESULT Save(

LPSTREAM pStm ,	//Pointer to the stream where the object is to be saved
BOOL fClearDirty	//Specifies whether to clear the dirty flag
);


IPicture

The IPicture interface manages a picture object and its properties. Picture objects provide a language-neutral abstraction for bitmaps, icons, and metafiles. As with the standard font object, the system provides a standard implementation of the picture object. Its primary interfaces are IPicture and IPictureDisp, the latter being derived from IDispatch to provide access to the picture’s properties through Automation. A picture object is created with OleCreatePictureIndirect.

The picture object also supports the outgoing interface IPropertyNotifySink, so a client can determine when picture properties change. Since the picture object supports at least one outgoing interface, it also implements IConnectionPointContainer and its associated interfaces for this purpose.

The picture object also supports IPersistStream so it can save and load itself from an instance of IStream. An object that uses a picture object internally would normally save and load the picture as part of the object’s own persistence handling. The function OleLoadPicture simplifies the creation of a picture object based on stream contents.

When to Implement

Typically, you use the OLE-provided picture object, which provides the IPicture and IPictureDisp interfaces for you. The IPicture interface is the primary interface implemented by the OLE-provided picture object. It allows the caller to manage picture properties and to use that picture in graphical rendering. Each property in the IPicture interface includes a get_PropertyName method if the property supports read access and a put_PropertyName method if the property supports write access. Most of the properties support only read access with the exception of hPal.

Property	Type	Access Allowed	Description
HANDLE	OLE_HANDLE (int)	R	The Windows GDI handle of the picture
hPal	OLE_HANDLE (int)	RW	The Windows handle of the palette used by the picture
Type	short	R	The type of picture (see below)
Width	OLE_XSIZE_HIMETRIC (long)	R	The width of the picture
Height	OLE_YSIZE_HIMETRIC (long)	R	The height of the picture
CurDC	HDC	R	The current device context
KeepOriginalFormat	BOOL	RW	If TRUE, the picture object maintains the entire original state of the picture in memory. If FALSE, any state not applicable to the user’s machine is discarded
Attributes	DWORD	R	Miscellaneous bit attributes of the picture (see below)
When to Use

Use this interface to change the properties of a picture object.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IPicture Methods	Description
get_Handle	Returns the Windows GDI handle of the picture managed within this picture object.
get_Hpal	Returns a copy of the palette currently used by the picture object.
get_Type	Returns the current type of the picture.
get_Width	Returns the current width of the picture in the picture object.
get_Height	Returns the current height of the picture in the picture object.
Render	Draws the specified portion of the picture onto the specified device context, positioned at the specified location.
set_Hpal	Sets the current palette of the picture.
get_CurDC	Returns the current device context into which this picture is selected.
SelectPicture	Selects a bitmap picture into a given device context, returning the device context in which the picture was previously selected as well as the picture’s GDI handle.
get_KeepOriginalFormat	Returns the current value of the picture object’s KeepOriginalFormat property.
put_KeepOriginalFormat	Sets the picture object’s KeepOriginalFormat property.
PictureChanged	Notifies the picture object that its picture resource changed.
SaveAsFile	Saves the picture’s data into a stream in the same format that it would save itself into a file.
get_Attributes	Returns the current set of the picture’s bit attributes.
See Also

IPicture - Ole Implementation, IPictureDisp


IPicture::get_Attributes

Returns the current set of the picture’s bit attributes.

HRESULT get_Attributes(

DWORD* pdwAttr	//Receives a pointer to attribute value.
);
Parameters

pdwAttr

[out] Pointer to the caller’s variable that receives the attribute value.

The Attributes property can contain any combination of the values from the PICTURE enumeration.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The attribute bits were returned successfully.

E_POINTER

The address in pdwAttr is not valid. For example, it may be NULL.

See Also

PICTURE


IPicture::get_CurDC

Returns the handle of the current device context. This property is valid only for bitmap pictures.

HRESULT get_CurDC(

HDC* phdcOut	//Receives a pointer to device context
);
Parameters

phdcOut

[out] Pointer to the caller’s variable to receive the device context.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The device context was returned successfully.

E_POINTER

The address in phdcOut is not valid. For example, it may be NULL.

Remarks

The CurDC property and the IPicture::SelectPicture method exist to circumvent restrictions in Windows; specifically, that an object can only be selected into exactly one device context at a time. In some cases, a picture object may be permanently selected into a particular device context (for example, a control may use a certain picture for a background). To use this picture property elsewhere, it must be temporarily deselected from its old device context, selected into the new device context for the operation, then reselected back into the old device context. The IPicture::get_CurDC method returns the device context handle into which the picture is currently selected. The IPicture::SelectPicture method selects the picture into a new device context, returning the old device context and the picture’s GDI handle. The caller should select the picture back into the old device context when the caller is done with it, as is normal for Windows code.

Notes to Callers

The caller always owns any device contexts passed between it and the picture object. Since the picture object maintains a copy of the HDC, the caller should use a memory device context (created with the Win32 function CreateCompatibleDC) and not a screen device context (from GetDC, CreateDC, or BeginPaint), because the screen device contexts are a limited system resource.

See Also

IPicture::SelectPicture


IPicture::get_Handle

Returns the Windows GDI handle of the picture managed within this picture object to a specified location.

HRESULT get_Handle(

OLE_HANDLE* phandle	//Receives a pointer to GDI handle
);
Parameters

phandle

[out] Pointer to the caller’s OLE_HANDLE variable that receives the handle. The caller is responsible for this handle upon successful return. The variable is set to NULL on failure.

Return Values

This method supports the standard return values E_FAIL and E_OUTOFMEMORY, as well as the following:

S_OK

The handle was returned successfully.

E_POINTER

The address in phandle is not valid. For example, it may be NULL.

Remarks

Notes to Callers

The picture object may retain ownership of the picture; however, the caller can be assured that the picture will remain valid until either the caller specifically destroys the picture or the picture object is itself destroyed. The fOwn parameter to OleCreatePictureIndirect determines ownership when the picture object is created. OleLoadPicture forces fOwn to TRUE.


IPicture::get_Height

Returns the current height of the picture in the picture object.

HRESULT get_Height(

OLE_YSIZE_HIMETRIC* pheight	//Receives a pointer to height
);
Parameters

pheight

[out] Pointer to the caller’s OLE_YSIZE_HIMETRIC variable that receives the height.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The height was returned successfully.

E_POINTER

The address in pheight is not valid. For example, it may be NULL.


IPicture::get_hPal

Returns a copy of the palette currently used by the picture object.

HRESULT get_hPal(

OLE_HANDLE* phpal	//Receives a pointer to palette handle
);
Parameters

phpal

[out] Pointer to the caller’s OLE_HANDLE variable to receive the palette handle. The variable is set to NULL on failure.

Return Values

This method supports the standard return values E_FAIL and E_OUTOFMEMORY, as well as the following:

S_OK

The handle was returned successfully.

S_FALSE

This picture has no palette. The parameter *phpal is set to NULL.

E_POINTER

The address in phpal is not valid. For example, it may be NULL.

Remarks

Notes to Callers

If the picture object has ownership of the picture, it also has ownership of the palette and will destroy it when the object is itself destroyed. Otherwise the caller owns the palette. The fOwn parameter to OleCreatePictureIndirect determines ownership. OleLoadPicture sets fOwn to TRUE to indicate that the picture object owns the palette.


IPicture::get_KeepOriginalFormat

Returns the current value of the picture’s KeepOriginalFormat property.

HRESULT get_KeepOriginalFormat(

BOOL* pfkeep	//Receives a pointer to the value of KeepOriginalFormat
);
Parameters

pfkeep

[out] Pointer to the caller’s BOOL variable that receives the value of the property.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The value of the KeepOriginalFormat property was returned successfully.

E_POINTER

The address in pfkeep is not valid. For example, it may be NULL.

See Also

IPicture::put_KeepOriginalFormat


IPicture::get_Type

Returns the current type of the picture contained in the picture object.

HRESULT get_Type(

short* ptype	//Receives a pointer to the picture type
);
Parameters

ptype

[out] Pointer to the caller’s short variable to receive the picture type. The Type property can have any one of the values contained in the PICTYPE enumeration.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The type was returned successfully.

E_POINTER

The address in ptype is not valid. For example, it may be NULL.

See Also

OleCreatePictureIndirect, PICTYPE


IPicture::get_Width

Returns the current width of the picture in the picture object.

HRESULT get_Width(

OLE_XSIZE_HIMETRIC* pwidth	//Receives a pointer to width
);
Parameters

pwidth

[out] Pointer to the caller’s OLE_XSIZE_HIMETRIC variable that receives the width.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The width was returned successfully.

E_POINTER

The address in pwidth is not valid. For example, it may be NULL.


IPicture::PictureChanged

Notifies the picture object that its picture resource has changed. On Win32, this method only sends an IPropertyNotifySink::OnChanged(DISPID_PICT_HANDLE) to any connected sinks.

HRESULT PictureChanged(void);

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

This value is returned in all cases except when the picture object is uninitialized.


IPicture::put_KeepOriginalFormat

Sets the value of the picture’s KeepOriginalFormat property.

HRESULT put_KeepOriginalFormat(

BOOL keep	//Specifies the new value of KeepOriginalFormat
);
Parameters

keep

[in] Specifies the new value to assign to the property.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The property was successfully changed.

See Also

IPicture::get_KeepOriginalFormat


IPicture::Render

Renders (draws) a specified portion of the picture defined by the offset (xSrc,ySrc) of the source picture and the dimensions to copy (cxSrc,xySrc). This picture is rendered onto the specified device context, positioned at the point (x,y), and scaled to the dimensions (cx,cy). The prcWBounds parameter specifies the position of this rendering if the destination device context is itself a metafile. Such information is necessary to place one metafile in another. For more information, see the prcWBounds parameter of IViewObject2::Draw.

HRESULT Render(

HDC hdc ,	//Handle of device context on which to render the image
long x ,	//Horizontal position of image in hdc
long y ,	//Vertical position of image in hdc
long cx ,	//Horizontal dimension of destination rectangle
long cy ,	//Vertical dimension of destination rectangle
OLE_XPOS_HIMETRIC xSrc ,	//Horizontal offset in source picture
OLE_YPOS_HIMETRIC ySrc ,	//Vertical offset in source picture
OLE_XSIZE_HIMETRIC cxSrc ,	//Amount to copy horizontally in source picture
OLE_YSIZE_HIMETRIC cySrc ,	//Amount to copy vertically in source picture
LPCRECT prcWBounds	//Pointer to position of destination for a metafile hdc
);
Parameters

hdc

[in] Handle of the device context on which to render the image.

x

[in] Horizontal coordinate in hdc at which to place the rendered image.

y

[in] Vertical coordinate in hdc at which to place the rendered image.

cx

[in] Horizontal dimension of the destination rectangle.

cy

[in] Vertical dimension of the destination rectangle.

xSrc

[in] Horizontal offset in the source picture from which to start copying.

ySrc

[in] Vertical offset in the source picture from which to start copying.

cxSrc

[in] Horizontal extent to copy from the source picture.

cySrc

[in] Vertical extent to copy from the source picture.

prcWBounds

[in] Pointer to a rectangle containing the position of the destination within a metafile device context if hdc is a metafile DC. Cannot be NULL in such cases.

Return Values

This method supports the standard return values E_FAIL, E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

The picture was rendered successfully.

E_POINTER

The address in prcWBounds is not valid when hdc contains a metafile device context.


IPicture::SaveAsFile

Saves the picture’s data into a stream in the same format that it would save itself into a file. Bitmaps use the BMP file format, metafiles the WMF format, and icons the ICO format. For more information, see the Win32 Programmer’s Reference.

HRESULT SaveAsFile(

IStream * pstream ,	//Pointer to stream where picture writes its data
BOOL fSaveMemCopy ,	//Indicates whether to save the picture in memory
LONG* pcbSize	//Receives a pointer to the number of bytes written to stream
);
Parameters

pstream

[in] Pointer to the stream into which the picture writes its data.

fSaveMemCopy

[in] Flag indicating whether or not to save a copy of the picture in memory.

pcbSize

[out] Pointer to the caller’s LONG variable to receive the number of bytes written into the stream. This value can be NULL, indicating that the caller does not require this information.

Return Values

This method supports the standard return values E_FAIL and E_INVALIDARG, as well as the following:

S_OK

The picture was saved successfully.


IPicture::SelectPicture

Selects a bitmap picture into a given device context, and returns the device context in which the picture was previously selected as well as the picture’s GDI handle. This method works in conjunction with IPicture::get_CurDC.

HRESULT SelectPicture(

HDC hdcIn ,	//New device context
HDC* phdcOut ,	//Receives a pointer to the previous device context
OLE_HANDLE* phbmpOut	//Receives a pointer to GDI handle of the picture
);
Parameters

hdcIn

[in] Device context in which to select the picture.

phdcOut

[out] Pointer to the caller’s HDC variable to receive the previous device context. This parameter can be NULL if the caller does not need this information. Ownership of the device context is always the responsibility of the caller.

phbmpOut

[out] Pointer to the caller’s HDC variable to receive the GDI handle of the picture. This parameter can be NULL if the caller does not need the handle. Ownership of this handle is determined by the fOwn parameter passed to OleCreatePictureIndirect. Pictures loaded from a stream always own their resources.

Return Values

This method supports the standard return valuesE_FAIL, E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

The picture was selected successfully.

See Also

IPicture::get_CurDC


IPicture::set_hPal

Assigns a GDI palette to the picture contained in the picture object.

HRESULT set_hPal(

OLE_HANDLE hpal	//Handle for GDI palette for the picture
);
Parameters

hpal

[in] Handle to the GDI palette assigned to the picture.

Return Values

This method supports the standard return values E_FAIL, E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

The palette was assigned successfully.

Remarks

Notes to Implementers

Ownership of the palette passed to this method depends on how the picture object was created, as specified by the fOwn parameter to OleCreatePictureIndirect. OleLoadPicture forces fOwn to TRUE; if the object owns the picture, then it takes over ownership of this palette.


IPicture - Ole Implementation

Picture objects provide a language-neutral abstraction for bitmaps, icons, and metafiles. As with the standard font object, the system provides a standard implementation of the picture object. Its primary interfaces are IPicture and IPictureDisp, the latter being derived from IDispatch to provide access to the picture’s properties through Automation. A picture object is created with OleCreatePictureIndirect and supports both the IPicture and the IPictureDisp interfaces.

Remarks

The OLE-provided picture object implements the complete semantics of the IPicture and IPictureDisp interfaces.

See Also

IPicture


IPictureDisp

The IPictureDisp interface exposes the picture object’s properties through Automation. It provides a subset of the functionality available through IPicture methods.

When to Implement

A picture object implements this interface along with IPicture to provide access to the picture’s properties through Automation. Typically, it is not necessary to implement this interface on your own object since there is an OLE-provided picture object.

The following table describes the dispIDs for the various picture properties.

Symbol	Value
DISPID_PICT_HANDLE	0
DISPID_PICT_HPAL	2
DISPID_PICT_TYPE	3
DISPID_PICT_WIDTH	4
DISPID_PICT_HEIGHT	5
DISPID_PICT_RENDER	6
Each property in the IPictureDisp interface includes a get_PropertyName method if the property supports read access and a put_PropertyName method if the property supports write access. Most of the properties support read access only with the exception of the hPal property.

Property	Type	Access Allowed	Description
Handle	OLE_HANDLE (int)	R	The Windows GDI handle of the picture
hPal	OLE_HANDLE (int)	RW	The Windows handle of the palette used by the picture.
Type	short	R	The type of picture (see below).
Width	OLE_XSIZE_HIMETRIC (long)	R	The width of the picture.
Height	OLE_YSIZE_HIMETRIC (long)	R	The height of the picture.
When to Use

Use this interface to change or retrieve the properties of a picture object.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
See Also

IPicture


IPictureDisp - Ole Implementation

Picture objects provide a language-neutral abstraction for bitmaps, icons, and metafiles. As with the standard font object, the system provides a standard implementation of the picture object. Its primary interfaces are IPicture and IPictureDisp, the latter being derived from IDispatch to provide access to the picture’s properties through Automation. A picture object is created with OleCreatePictureIndirect and supports both the IPicture and the IPictureDisp interfaces.

Remarks

The OLE-provided picture object implements the complete semantics of the IPicture and IPictureDisp interfaces.

See Also

IPicture, IPictureDisp


IPointerInactive

The IPointerInactive interface enables an object to remain inactive most of the time, yet still participate in interaction with the mouse, including drag and drop.

Objects can be active (in-place or UI active) or they can be inactive (loaded or running). An active object creates a window and can receive Windows mouse and keyboard messages. An inactive object can render itself and provide a representation of its data in a given format. While they provide more functionality, active objects also consume more resources than inactive objects. Typically, they are larger and slower than inactive objects. Thus, keeping an object inactive can provide performance improvements.

However, an object, such as a control, needs to be able to control the mouse pointer, fire mouse events, and act as a drop target so it can participate in the user interface of its container application.

When to Implement

Implement this interface on an object, such as a control, so the object can support a minimal level of interaction with the mouse and keyboard while it is in the inactive state. The object can control the mouse pointer, fire mouse events, and act as a drop target without being in the active state at all times. The object does not have to set the OLEMISC_ACTIVATEWHENVISIBLE enumeration value, does not have to have a window, and thus, can increase its performance.

If the object must work with down-level containers, it may have to set the OLEMISC_ACTIVATEWHENVISIBLE enumeration value. However, an updated container that supports objects that implement IPointerInactive can use the OLEMISC_IGNOREACTIVATEWHENVISIBLE enumeration value to override OLEMISC_ACTIVATEWHENVISIBLE.

When to Use

A container calls the methods in this interface for its embedded objects so that the embedded objects can participate in the user interface for the application.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns a pointer to a specified interface.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IPointerInactive Methods	Description
GetActivationPolicy	Returns the present activation policy for the object.
OnInactiveMouseMove	Notifies the object that the mouse pointer has moved over it so the object can fire mouse events.
OnInactiveSetCursor	Sets the mouse pointer for an inactive object.
See Also

OLEMISC


IPointerInactive::GetActivationPolicy

Returns the present activation policy for the object. This method is called by the container on receipt of a WM_SETCURSOR or WM_MOUSEMOVE message when an inactive object is under the mouse pointer.

HRESULT GetActivationPolicy(

DWORD* pdwPolicy	//Pointer to activation policy
);
Parameter

pdwPolicy

[out] Pointer to the activation policy as specified by the POINTERINACTIVE enumeration values.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The activation policy was successfully returned.

Remarks

A container calls this method when it receives a WM_SETCURSOR or WM_MOUSEMOVE message with the mouse pointer over an inactive object that supports IPointerInactive. The object returns its activation policy through the POINTERINACTIVE enumeration values.

The object can request to be in-place activated as soon as the mouse enters it through the POINTERINACTIVE_ACTIVATEONENTRY value. An object that provides more visual feedback than simply setting the mouse pointer would use this value. For example, if the object supports special visual feedback, it must enter the active state so it can draw the visual feedback that it supports.

An object can also use this method to request activation when the mouse is dragged over them during a drag and drop operation through the POINTERINACTIVE_ACTIVATEONDRAG. See the POINTERINACTIVE enumeration for more information.

If the object returns one of these values, the container should activate the object immediately and forward the Window message that triggered the call. The object then stays active and processes subsequent messages through its own window until the container gets another WM_SETCURSOR or WM_MOUSEMOVE. At this point, the container should deactivate the object.

Note  For windowless OLE objects this mechanism is slightly different. See IOleInPlaceSiteWindowless for more information on drag and drop operations for windowless objects.

If the object returns both the POINTERINACTIVE_ACTIVATEONENTRY and the POINTERINACTIVE_DEACTIVATEONLEAVE values, the object is activated only when the mouse is over the object. If the POINTERINACTIVE_ACTIVATEONENTRY value alone is set, the object is activated once when the mouse first enters it, and it remains active.

Note to Callers

The activation policy should not be cached. The container should call this method each time the mouse enters an inactive object.

See Also

IOleInPlaceSiteWindowless, POINTERINACTIVE


IPointerInactive::OnInactiveMouseMove

Notifies the object that the mouse pointer has moved over it so the object can fire mouse events. This method is called by the container on receipt of a WM_MOUSEMOVE method when an inactive object is under the mouse pointer.

HRESULT OnInactiveMouseMove(

LPCRECT pRectBounds,	//Object bounding rectangle
LONG x,	//Horizontal coordinate
LONG y,	//Vertical coordinate
DWORD grfKeyState	//
);
Parameter

pRectBounds

[in] The object bounding rectangle, in client coordinates of the containing window. This parameter tells the object its exact position and size on the screen when the WM_MOUSEMOVE message was received. This value is specified in units of the client’s coordinate system.

x

[in] Horizontal coordinate of mouse location in units of the client’s containing window.

y

[in] Vertical coordinate of mouse location in units of the client’s containing window.

grfKeyState

[in] Identifies the current state of the keyboard modifier keys on the keyboard. Valid values can be a combination of any of the values MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The mouse pointer was successfully set.

Remarks

The container calls this method to notify the object that the mouse pointer is over the object after checking the object’s activation policy by calling the IPointerInactive::GetActivationPolicy method. If the object has not requested to be activated in-place through that call, the container dispatches subsequent WM_MOUSEMOVE messages to the inactive object by calling OnInactiveMouseMove as long as the mouse pointer stays over the object. The object can then fire mouse move events.

To avoid rounding errors and to make the job easier on the object implementer, this method takes window coordinates in the units of its containing client window, that is, the window in which the object is displayed, instead of the usual HIMETRIC units. Thus, the same coordinates and code path can be used when the object is active and inactive. The window coordinates specify the mouse position. The bounding rectangle is also specified in the same coordinate system.

See Also

IPointerInactive::GetActivationPolicy


IPointerInactive::OnInactiveSetCursor

Sets the mouse pointer for an inactive object. This method is called by the container on receipt of a WM_SETCURSOR method when an inactive object is under the mouse pointer.

HRESULT OnInactiveSetCursor(

LPCRECT pRectBounds,	//Object bounding rectangle
LONG x,	//Horizontal coordinate
LONG y,	//Vertical coordinate
DWORD dwMouseMsg,	//Mouse message identifier
BOOL fSetAlways	//Indicates whether object must set the mouse pointer
);
Parameter

pRectBounds

[in] The object bounding rectangle specified in client coordinate units of the containing window. This parameter tells the object its exact position and size on the screen when the WM_SETCURSOR message was received. This value is specified in units of the client’s coordinate system.

x

[in] Horizontal coordinate of mouse location in units of the client’s containing window.

y

[in] Vertical coordinate of mouse location in units of the client’s containing window.

dwMouseMsg

[in] Identifier of the mouse message for which a WM_SETCURSOR occurred.

fSetAlways

[in] If this value is TRUE, the object must set the cursor; if this value is FALSE, the object is not obligated to set the cursor, and should return S_FALSE in that case.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

The mouse pointer was successfully set.

S_FALSE

The object did not set the cursor; the container should either set the cursor or call the object again with the parameter fSetAlways set to TRUE.

Remarks

The container calls this method to set the mouse pointer over an inactive object after checking the object’s activation policy by calling the IPointerInactive::GetActivationPolicy method. If the object has not requested to be activated in-place through that call, the container dispatches subsequent WM_SETCURSOR messages to the inactive object by calling OnInactiveSetCursor as long as the mouse pointer stays over the object.

To avoid rounding errors and to make the job easier on the object implementer, this method takes window coordinates in the units of its containing client window, that is, the window in which the object is displayed, instead of the usual HIMETRIC units. Thus, the same coordinates and code path can be used when the object is active and inactive. The window coordinates specify the mouse position. The bounding rectangle is also specified in the same coordinate system.

OnInactiveSetCursor takes an additional parameter (fSetAlways) indicating whether the object is obligated to set the cursor or not. Containers should first call this method with this parameter FALSE. The object may return S_FALSE to indicate that it did not set the cursor. In that case, the container should either set the cursor itself, or, if it does not wish to do this, call the OnInactiveSetCursor method again with fSetAlways being TRUE.

See Also

IPointerInactive::GetActivationPolicy


IProgressNotify

The IProgressNotify interface enables applications and other objects to receive notifications of changes in the progress of a downloading operation.

When to Implement

You do not need to implement IProgressNotify. The downloading code implements this interface, and the asynchronous storage implementation provides a connection point for dispatching notifications to it. An application can also register an IProgressNotify sink to receive progress notifications for individual streams.

When to Use

You do not need to call this interface. The Compound Files implementation uses IProgressNotify::OnProgress to control the blocking behavior of the asynchronous storage and to trigger additional byte range requests if applicable.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IProgressNotify Method	Description
OnProgress	Receives status information about progress of download operation.


IProgressNotify::OnProgress

Notifies registered objects and applications of the progress of a downloading operation.

HRESULT OnProgress(

DWORD dwProgressCurrent	// Amount of data available
DWORD dwProgressMaximum	// Total amount of data to be downloaded
BOOL fAccurate	// Reliability of notifications
BOOL fOwner	// Ownership of blocking behavior
);
Parameters

dwProgressCurrent

[in] The amount of data available.

dwProgressMaximum

[in] The total amount of data to be downloaded.

fAccurate

[in] Values in dwProgressCurrent and dwProgressMaximum are either reliable (TRUE) or unreliable (FALSE). The FALSE value indicates that control structures for determining the actual position of, or amount of, data yet to be downloaded are not available.

fOwner

[in] Indicates whether this OnProgress call can control the blocking behavior of the operation. If TRUE, the caller can use return values from OnProgress to block (STG_S_BLOCK), retry (STG_S_RETRYNOW), or monitor (STG_S_MONITORING) the operation. If FALSE, the return value from OnProgress has no influence on blocking behavior.

Return Values

This function supports the standard return values E_OUTOFMEMORY, E_UNEXPECTED, E_INVALIDARG, and E_FAIL, as well as the following:

STG_S_RETRYNOW

The caller is to retry the operation immediately. (This value is most useful for applications that do blocking from within the callback routine.)

STG_S_BLOCK

The caller is to block the download and retry the call as needed to determine if additional data is available. This is the default behavior if no sinks are registered on the connection point.

STG_S_MONITORING

The callback recipient reliquishes control of the downloading process to one of the other objects or applications that have registered progress notification sinks on the same stream. This is useful if the notification sink is interested only in gathering statistics.

E_PENDING

Data is currently unavailable. The caller is to try again after some desired interval. The notification sink returns this value if the asynchronous storage is to operate in nonblocking mode.

Remarks

Sinks may be inherited by any substorage or substream of a given storage. If no sink is registered, the thread will block until the requested data becomes available, or the download is canceled by the downloader.

Where multiple objects or applications have registered progress notification sinks on a single stream, only one of them can control the behavior of a download. Ownership of the download goes to:

1.	The first sink to register with the storage or stream.

2.	Any advise skinks that may have been inherited from the parent storage (if the storage was created with ASYNC_MODE_COMPATIBILITY.

Any one of the sinks can relinquish control to the next connection point by returning STG_S_MONITORING to the connection point making the current caller. Once a connection point obtains control (through receiving STG_S_BLOCK or STG_S_RETRYNOW), all subsequent connection points calling IProgressNotify::OnProgress will set fOwner  to FALSE.


IPropertyBag

The IPropertyBag interface provides an object with a property bag in which the object can persistently save its properties.

When a client wishes to have exact control over how individually named properties of an object are saved, it would attempt to use an object’s IPersistPropertyBag interface as a persistence mechanism. In that case the client supplies a property bag to the object in the form of an IPropertyBag interface.

When the object wishes to read a property in IPersistPropertyBag::Load it will call IPropertyBag::Read. When the object is saving properties in IPersistPropertyBag::Save it will call IPropertyBag::Write. Each property is described with a name in pszPropName whose value is exchanged in a VARIANT. This information allows a client to save the property values as text, for instance, which is the primary reason why a client might choose to support IPersistPropertyBag.

The client records errors that occur during reading into the supplied error log.

When to Implement

A container implements this interface to provide its object with a way to store their properties persistently.

When to Use

An object calls the methods on this interface to read and write its properties into the container provided property bag.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IPropertyBag Methods	Description
Read	Called by the control to read a property from the storage provided by the container.
Write	Called by the control to write each property in turn to the storage provided by the container.
See Also

IErrorLog, IPersistPropertyBag


IPropertyBag::Read

Called by the control to read a property from the storage provided by the container.

HRESULT Read(

LPCOLESTR pszPropName,	//Pointer to the property to be read
VARIANT* pVar,	//Pointer to the VARIANT to receive the property value
IErrorLog* pErrorLog	//Pointer to the caller’s error log
);
Parameters

pszPropName

[in] Pointer to the name of the property to read. Cannot be NULL.

pVar

[in, out] Pointer to the caller-initialized VARIANT that is to receive the property value on output. The method must set both type and value fields in the VARIANT before returning. If the caller initialized the pVar->vt field on entry, the property bag should attempt to coerce the value it knows into this type. If the caller sets pVar->vt to VT_EMPTY, the property bag can use whatever type is convenient.

pErrorLog

[in] Pointer to the caller’s IErrorLog interface in which the property bag stores any errors that occur during reads. Can be NULL in which case the caller is not interested in errors.

Return Values

S_OK

The property was read successfully. The caller becomes responsible for any allocations that are contained in the VARIANT in pVar.

E_POINTER

The address in pszPropName is not valid (such as NULL).

E_INVALIDARG

The property named with pszPropName does not exist in the property bag.

E_FAIL

The property bag was unable to read the specified property, such as if the caller specified a data type to which the property bag could not coerce the known value. If the caller supplied an error log, a more descriptive error was sent there.

Remarks

This method asks the property bag to read the property named with pszPropName into the caller-initialized VARIANT in pVar. Errors that occur are logged in the error log pointed to by pErrorLog. When pVar->vt specifies another object pointer (VT_UNKNOWN) then the property bag is responsible for creating and initializing the object described by pszPropName.

E_NOTIMPL is not a valid return code since any object implementing this interface must support the entire functionality of the interface.

See Also

IPropertyBag::Write


IPropertyBag::Write

Called by the control to write each property in turn to the storage provided by the container.

HRESULT Write(

LPCOLESTR pszPropName,	//Points to the property to be written
VARIANT* pVar	//Points to the VARIANT containing the property value and type
);
Parameters

pszPropName

[in] Pointer to the name of the property to write. Cannot be NULL.

pVar

[in] Pointer to the caller-initialized VARIANT that holds the property value to save. The caller owns this VARIANT and is responsible for all allocations therein. That is, the property bag itself does not attempt to free data in the VARIANT.

Return Values

S_OK

The property bag successfully saved the requested property.

E_FAIL

There was a problem writing the property. It is possible that the property bag does not understand how to save a particular VARIANT type.

E_POINTER

The address in pszPropName or pVar is not valid (such as NULL). The caller must supply both.

Remarks

This method asks the property bag to save the property named with pszPropName using the type and value in the caller-initialized VARIANT in pVar. In some cases the caller may be asking the property bag to save another object, that is, when pVar->vt is VT_UNKNOWN. In such cases, the property bag queries this object pointer for some persistence interface, like IPersistStream or even IPersistPropertyBag again and has that object save its data as well. Usually, this results in the property bag having some byte array for this object which can be saved as encoded text (hex string, MIME, etc.). When the property bag is later used to reinitialize a control, the client that owns the property bag must recreate the object when the caller asks for it, initializing that object with the previously saved bits.

This allows very efficient persistence operations for large BLOB properties like a picture, where the owner of the property bag itself directly asks the picture object (managed as a property in the control being saved) to save into a specific location. This avoids potential extra copy operations that would be involved with other property-based persistence mechanisms.

E_NOTIMPL is not a valid return code as any object implementing this interface must support the entire functionality of the interface.

See Also

IPropertyBag::Read


IPropertyNotifySink

The IPropertyNotifySink interface is implemented by a sink object to receive notifications about property changes from an object that supports IPropertyNotifySink as an “outgoing” interface. The client that needs to receive the notifications in this interface (from a supporting connectable object) creates a sink with this interface and connects it to the connectable object through the connection point mechanism. For more information on connection points, see IConnectionPointContainer.

The object is itself required to call the methods of IPropertyNotifySink only for those properties marked with the [bindable] and [requestedit] attributes in the object’s type information. When the object changes a [bindable] property, it is required to call IPropertyNotifySink::OnChanged. When the object is about to change a [requestedit] property, it must call IPropertyNotifySink::OnRequestEdit before changing the property and must also honor the action specified by the sink on return from this call.

The one exception to this rule is that no notifications are sent as a result of an object’s initialization or loading procedures. At initialization time, it is assumed that all properties change and that all must be allowed to change. Notifications to this interface are therefore meaningful only in the context of a fully initialized/loaded object.

When to Implement

Implement this interface for a sink object that receives notifications about property changes from an object that supports this kind of notification.

When to Use

Use this interface to notify a sink object about changes in a property.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IPropertyNotifySink Methods	Description
OnChanged	Notifies a sink that a bindable property has changed.
OnRequestEdit	Notifies a sink that a requestedit property is about to change.
See Also

IConnectionPoint, IConnectionPointContainer

Also, see the Automation branch of the help file for further explanations of type information, ODL files, and type libraries.


IPropertyNotifySink::OnChanged

Notifies a sink that the [bindable] property specified by dispID has changed. If dispID is DISPID_UNKNOWN, then multiple properties have changed together. The client (owner of the sink) should then retrieve the current value of each property of interest from the object that generated the notification.

HRESULT OnChanged(

DISPID dispID	//Dispatch identifier of the property that changed
);
Parameters

dispID

[in] Dispatch identifier of the property that changed, or DISPID_UNKNOWN if multiple properties have changed.

Return Values

S_OK

This return value is returned in all cases.

Remarks

S_OK is returned in all cases even when the sink does not need [bindable] properties or when some other failure has occurred. In short, the calling object simply sends the notification and cannot attempt to use an error code (such as E_NOTIMPL) to determine whether to not send the notification in the future. Such semantics are not part of this interface.

See Also

IPropertyNotifySink::OnRequestEdit


IPropertyNotifySink::OnRequestEdit

Notifies a sink that a [requestedit] property is about to change and that the object is asking the sink how to proceed.

HRESULT OnRequestEdit(

DISPID dispID	//Dispatch identifier of the property that is about to change
);
Parameters

dispID

[in] Dispatch identifier of the property that is about to change or DISPID_UNKNOWN if multiple properties are about to change.

Return Values

S_OK

The specified property or properties are allowed to change.

S_FALSE

The specified property or properties are not allowed to change. The caller must obey this return value by discarding the new property value(s). This is part of the contract of the [requestedit] attribute and this method.

Remarks

The sink may choose to allow or disallow the change to take place. For example, the sink may enforce a read-only state on the property. DISPID_UNKNOWN is a valid parameter to this method to indicate that multiple properties are about to change. In this case, the sink can enforce a global read-only state for all [requestedit] properties in the object, including any specific ones that the sink otherwise recognizes.

If the sink allows changes, the object must also make IPropertyNotifySink::OnChanged notifications for any properties that are marked [bindable] in addition to [requestedit].

This method cannot be used to implement any sort of data validation. At the time of the call, the desired new value of the property is unavailable and thus cannot be validated. This method’s only purpose is to allow the sink to enforce a read-only state on a property.

See Also

IPropertyNotifySink::OnChanged


IPropertyPage

The IPropertyPage interface provides the main features of a property page object that manages a particular page within a property sheet. A property page implements at least IPropertyPage and can optionally implement IPropertyPage2 if selection of a specific property is supported. See IPerPropertyBrowsing::MapPropertyToPage for more information on specific property browsing. The methods of IPropertyPage2 allow the property sheet or property frame to instruct the page when to perform specific actions, mostly based on user input such as switching between pages or pressing various buttons that the frame itself manages in the dialog box.

A property page manages a dialog box that contains only those controls that should be displayed for that one page within the property sheet itself. This means that the dialog box template used to define the page should only carry the WS_CHILD style and no others. It should not include any style related to a frame, caption, or system menus or controls.

When to Implement

Implement this interface on a property page object.

When to Use

Use this interface to manage a property page object. Typically, this method is called within the OLE-supplied property frame created through OleCreatePropertyFrame or OleCreatePropertyFrameIndirect. Using the methods in this interface, the frame can display the properties and process end-user changes to the property values.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IPropertyPage Methods	Description
SetPageSite	Initializes a property page and provides the page with a pointer to the IPropertyPageSite interface through which the property page communicates with the property frame.
Activate	Creates the dialog box window for the property page.
Deactivate	Destroys the window created with Activate.
GetPageInfo	Returns information about the property page.
SetObjects	Provides the property page with an array of IUnknown pointers for objects associated with this property page.
Show	Makes the property page dialog box visible or invisible.
Move	Positions and resizes the property page dialog box within the frame.
IsPageDirty	Indicates whether the property page has changed since activated or since the most recent call to Apply.
Apply	Applies current property page values to underlying objects specified through SetObjects.
Help	Invokes help in response to end-user request.
TranslateAccelerator	Provides a pointer to a MSG structure that specifies a keystroke to process.
See Also

IPerPropertyBrowsing, IPropertyPage2, IPropertyPageSite, ISpecifyPropertyPages, OleCreatePropertyFrame, OleCreatePropertyFrameIndirect


IPropertyPage::Activate

Creates the dialog box for the property page (without a frame, caption, or system menu/controls) using hWndParent as the parent window and prc as the positioning rectangle. The bModal flag indicates the modality of the dialog box frame (in the current implementation of OleCreatePropertyFrame and OleCreatePropertyFrameIndirect, this parameter is always TRUE). The text in the dialog should match the locale obtained through IPropertyPageSite::GetLocaleID.

The property page maintains the window handle created in this process, which it uses to destroy the dialog box within IPropertyPage::Deactivate.

HRESULT Activate(

HWND hWndParent ,	//Parent window handle
LPCRECT prc ,	//Pointer to RECT structure
BOOL bModal	//Dialog box frame is modal or modeless
);
Parameters

hWndParent

[in] Window handle of the parent of the dialog box that is being created.

prc

[in] Pointer to the RECT structure containing the positioning information for the dialog box. This method must create its dialog box with the placement and dimensions described by this rectangle, that is, origin point at (prc->left, prc->top) and dimensions of (prc->right-prc->Left, prc->bottom-prc->top).

bModal

[in] Indicates whether the dialog box frame is modal (TRUE) or modeless (FALSE).

Return Values

This method supports the standard return values E_OUTOFMEMORY and

E_UNEXPECTED, as well as the following:

S_OK

The page dialog box was created successfully.

E_POINTER

The address in prc is not valid. For example, it may be NULL.

Remarks

Notes to Implementers

E_NOTIMPL is not a valid return value.

See Also

IPropertyPage::Activate


IPropertyPage::Apply

Applies the current values to the underlying objects associated with the property page as previously passed to IPropertyPage::SetObjects.

HRESULT Apply(void);

Return Values

This method supports the standard return values E_OUTOFMEMORY and

E_UNEXPECTED, as well as the following:

S_OK

Changes were successfully applied and the property page is current with the underlying objects.

S_FALSE

Changes were applied, but the property page cannot determine if its state is current with the objects.

Remarks

The objects to be changed are provided through a previous call to IPropertyPage::SetObjects. By calling IPropertyPage::SetObjects prior to calling this method, the caller ensures that all underlying objects have the correct interfaces through which to communicate changes. Therefore, this method should not fail because of non-existent interfaces.

After applying its values, the property page should determine if its state is now current with the objects in order to properly implement IPropertyPage::IsPageDirty and to provide both S_OK and S_FALSE return values.

Notes to Implementers

E_NOTIMPL is not a valid return value.

See Also

IPropertyPage::IsPageDirty, IPropertyPage::SetObjects


IPropertyPage::Deactivate

Destroys the window created in IPropertyPage::Activate.

HRESULT Deactivate(void);

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The dialog was successfully destroyed.

Remarks

Notes to Implementers

It is important that property pages not keep the dialog box around as an optimization. In a property sheet with many property pages, memory consumption would become excessive if all property pages kept their dialog boxes created at all times. Destroying the dialog box prevents excessive memory consumption due to a very large number of created controls in the dialog boxes. If the frame wishes to keep pages alive while they are not visible, it can use IPropertyPage::Show for that purpose. The decision is ultimately left to the frame.

E_NOTIMPL is not a valid return value.

See Also

IPropertyPage::Activate


IPropertyPage::GetPageInfo

Fills a caller-allocated PROPPAGEINFO structure to provide the caller with information about the property page.

HRESULT GetPageInfo(

PROPPAGEINFO *pPageInfo	//Receives a pointer to property page information structure
);
Parameters

pPageInfo

[out] Pointer to the caller-allocated PROPPAGEINFO structure in which the property page stores its page information. All allocations stored in this structure become the responsibility of the caller.

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The structure was successfully filled.

E_POINTER

The address in pPageInfo is not valid. For example, it may be NULL.

Remarks

Notes to Implementers

E_NOTIMPL is not a valid return value.

See Also

PROPPAGEINFO


IPropertyPage::Help

Invokes the property page help in response to an end-user request.

HRESULT Help(

LPCOLESTR pszHelpDir	//Pointer to string from HelpDir key
);
Parameters

pszHelpDir

[in] Pointer to the string under the HelpDir key in the property page’s CLSID information in the registry. If HelpDir does not exist, this will be the path found in the InProcServer32 entry minus the server file name. (Note that LocalServer32 is not checked in the current implementation, since local property pages are not currently supported).

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The page displayed its own help.

E_NOTIMPL

Help is either not provided or is provided only through the information in PROPPAGEINFO.

Remarks

Notes to Callers

Calls to this method must occur between calls to IPropertyPage::Activate and IPropertyPage::Deactivate.

Notes to Implementers

If the page fails this method (such as E_NOTIMPL), then the frame will attempt to use the pszHelpFile and dwHelpContext fields of the PROPPAGEINFO structure obtained through IPropertyPage::GetPageInfo. Therefore, the page should either implement IPropertyPage::Help or return help information through IPropertyPage::GetPageInfo.

See Also

IPropertyPage::Activate, IPropertyPage::Deactivate, IPropertyPage::GetPageInfo, PROPPAGEINFO


IPropertyPage::IsPageDirty

Indicates whether the property page has changed its state since activation or since the last call to IPropertyPage::Apply. The property sheet uses this information to enable or disable the Apply button in the dialog box. There is no need to apply the values on a property page if those values are already current with the underlying objects.

HRESULT IsPageDirty(void);

Return Values

S_OK

The value state of the property page is dirty, that is, it has changed and is different from the state of the objects.

S_FALSE

The value state of the page has not changed and is current with that of the objects.

Remarks

Notes to Implementers

This method has no reason to return an error code, since the inability to determine if the page is dirty should return S_OK as a default. In this way, the user has a chance to update the values. The page should not return an error code, since an error code is not the same as S_OK and would indicate that the page is not dirty. Then, the property frame could potentially disable the Apply button, not allowing the user to make sure that the property values are current.

See Also

IPropertyPage::Apply


IPropertyPage::Move

Repositions and resizes the property page dialog box according to the contents of prc. The rectangle specified by prc is treated identically to that passed to IPropertyPage::Activate.

HRESULT Move(

LPCRECT prc	//Pointer to RECT structure
);
Parameters

prc

[in] Pointer to the RECT structure containing the positioning information for the page dialog box.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The page repositioned itself successfully.

E_POINTER

The address in prc is not valid. For example, it may be NULL.

Remarks

Notes to Callers

Calls to this method must occur after a call to IPropertyPage::Activate and before a corresponding call to IPropertyPage::Deactivate.

Notes to Implementers

The page must create its dialog box with the placement and dimensions described by this rectangle, that is, origin point at (prc->left,   prc->top) and dimensions of (prc->right-prc->Left,   prc->bottom-prc->top).

See Also

IPropertyPage::Activate, IPropertyPage::Deactivate


IPropertyPage::SetObjects

Provides the IUnknown pointers of the objects affected by the property sheet in which this property page is displayed. When the property page receives a call to IPropertyPage::Apply, it must send value changes to these objects through whatever interfaces are appropriate. The property page must query for those interfaces. This method can fail if the objects do not support the interfaces expected by the property page.

HRESULT SetObjects(

ULONG cObjects ,	//Number of IUnknown pointers in the ppUnk array
IUnknown **ppUnk	//Pointer to array
);
Parameters

cObjects

[in] Number of IUnknown pointers in the array pointed to by ppUnk. If zero, the property page must release any pointers previously passed to this method.

ppUnk

[in] Pointer to an array of IUnknown interface pointers where each pointer identifies a unique object affected by the property sheet in which this (and possibly other) property pages are displayed. The property page must cache these pointers calling IUnknown::AddRef for each pointer at that time. This array of pointers is the same one that was passed to OleCreatePropertyFrame or OleCreatePropertyFrameIndirect to invoke the property sheet.

Return Values

This method supports the standard return values E_FAIL, E_INVALIDARG,

E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The property page successfully saved the pointers it needed.

E_NOINTERFACE

One of the objects in ppUnk did not support the interface expected by this property page, and so this property page cannot communicate with it.

E_POINTER

The address in ppUnk is not valid. For example, it may be NULL.

Remarks

The property page is required to keep the pointers returned by this method or others queried through them. If these specific IUnknown pointers are held, the property page must call IUnknown::AddRef through each when caching them, until the time when IPropertyPage::SetObjects is called with cObjects equal to zero. At that time, the property page must call IUnknown::Release through each pointer, releasing any objects that it held.

The caller must provide the property page with these objects before calling IPropertyPage::Activate, and should call IPropertyPage::SetObjects with zero as the parameter when deactivating the page or when releasing the object entirely. Each call to SetObjects with a non-NULL ppUnk parameter must be matched with a later call to SetObjects with zero in the cObjects parameter.

Notes to Implementers

E_NOTIMPL is not a valid return value.

See Also

IPropertyPage::Activate, OCPFIPARAMS, OleCreatePropertyFrame, OleCreatePropertyFrameIndirect


IPropertyPage::SetPageSite

Initializes a property page and provides the property page object with the IPropertyPageSite interface through which the property page communicates with the property frame.

HRESULT SetPageSite(

IPropertyPageSite *pPageSite	//Pointer to the site object
);
Parameters

pPageSite

[in] Pointer to the IPropertyPageSite interface of the page site that manages and provides services to this property page within the entire property sheet.

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The page site was saved and the page object was fully initialized.

Remarks

Notes to Implementers

If the pPageSite parameter is NULL, this method must call pPageSite->Release on any IPropertyPageSite pointer passed during a previous call to this method. If non-NULL, this method must save the IPropertyPageSite pointer value and call pPageSite->AddRef. Two consecutive calls to this method with a non-NULL site pointer are not allowed and should cause the property page to return E_UNEXPECTED.

E_NOTIMPL is not a valid return value. All property pages must implement this method.

See Also

IPropertyPageSite


IPropertyPage::Show

Makes the property page dialog box visible or invisible according to the nCmdShow parameter. If the page is made visible, the page should set the focus to itself, specifically to the first property on the page.

HRESULT Show(

UINT nCmdShow	//Indicates whether to make the page visible or hidden
);
Parameters

nCmdShow

[in] Command describing whether to become visible (SW_SHOW or SW_SHOWNORMAL) or hidden (SW_HIDE). No other values are valid for this parameter.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The show command was successfully invoked.

Remarks

Notes to Callers

Calls to this method must occur after a call to IPropertyPage::Activate and before a corresponding call to IPropertyPage::Deactivate.

Notes to Implementers

E_NOTIMPL is not a valid return value. E_OUTOFMEMORY is not a valid return value, since no memory should be used in implementing this method.

See Also

IPropertyPage::Activate, IPropertyPage::Deactivate


IPropertyPage::TranslateAccelerator

Instructs the property page to process the keystroke described in pMsg.

HRESULT TranslateAccelerator(

LPMSG pMsg	//Pointer to MSG structure
);
Parameters

pMsg

[in] Pointer to the MSG structure describing the keystroke to process.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The property page handles the accelerator.

S_FALSE

The property page handles accelerators, but this one was not useful to it.

E_NOTIMPL

The property page does not handle accelerators.

E_POINTER

The address in pMsg is not valid. For example, it may be NULL.

Remarks

Notes to Callers

Calls to this method must occur after a call to IPropertyPage::Activate and before the corresponding call to IPropertyPage::Deactivate.

See Also

IPropertyPage::Activate, IPropertyPage::Deactivate


IPropertyPage2

The IPropertyPage2 interface is an extension to IPropertyPage to support initial selection of a property on a page. It works in conjunction with the implementation of IPerPropertyBrowsing::MapPropertyToPage on an object that supplies properties and specifies property pages through ISpecifyPropertyPages. This interface has only one extra method in addition to those in IPropertyPage. That method, IPropertyPage2::EditProperty tells the page which property to highlight.

When to Implement

Implement this interface if your property page object supports selection of a specific property.

When to Use

Use this interface to select a specific property in a property page.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IPropertyPage Methods	Description
SetPageSite	Initializes a property page and provides the page with a pointer to the IPropertyPageSite interface through which the property page communicates with the property frame.
Activate	Creates the dialog box window for the property page.
Deactivate	Destroys the window created with Activate.
GetPageInfo	Returns information about the property page.
SetObjects	Provides the property page with an array of IUnknown pointers for objects associated with this property page.
Show	Makes the property page dialog box visible or invisible.
Move	Positions and resizes the property page dialog box within the frame.
IsPageDirty	Indicates whether the property page has changed since activated or since the most recent call to Apply.
Apply	Applies current property page values to underlying objects specified through SetObjects.
Help	Invokes help in response to end-user request.
TranslateAccelerator	Provides a pointer to a MSG structure that specifies a keystroke to process.
IPropertyPage2 Methods	Description
EditProperty	Specifies which field is to receive the focus when the property page is activated.
See Also

IPerPropertyBrowsing, IPropertyPage, IPropertyPageSite, ISpecifyPropertyPages, IPerPropertyBrowsing::MapPropertyToPage


IPropertyPage2::EditProperty

Specifies in dispID the property’s control on the property page to receive the focus when the page is activated.

HRESULT EditProperty(

DISPID dispID	//Dispatch identifier for property
);
Parameters

dispID

[in] Identifies the property that is to receive the focus.

Return Values

This method supports the standard return value E_INVALIDARG, as well as the following:

S_OK

The property was successfully highlighted.

E_NOTIMPL

This method is not currently implemented; the interface is probably provided in anticipation of future work on this page.

Remarks

Notes to Implementers

If this method is called before a page is activated, the page should store the property and set the focus to it in the next call to IPropertyPage::Activate. If the page is already active, IPropertyPage2::EditProperty should set the focus to the specific property field.

See Also

IPropertyPage::Activate


IPropertyPageSite

The IPropertyPageSite interface provides the main features for a property page site object. For each property page created within a property frame, the frame creates a property page site to provide information to the property page and to receive notifications from the page when changes occur. This latter notification is used to initiate a call to IPropertyPage::IsPageDirty, the return value of which is then used to enable or disable the frame’s Apply button.

When to Implement

Implement this interface on a site object that will manage a property page on behalf of the property frame. Typically, the OLE-provided property frame created through OleCreatePropertyFrame and OleCreatePropertyFrameIndirect implements site objects.

When to Use

Use a site object with this interface to set up communications between the property frame and the property page object.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IPropertyPageSite Methods	Description
OnStatusChange	Indicates that the user has modified property values on the property page.
GetLocaleID	Returns the locale identifier so the property page can adjust itself to country-specific settings.
GetPageContainer	Returns an IUnknown pointer for the object representing the entire property frame dialog box that contains all the pages.
TranslateAccelerator	Passes a keystroke to the property frame for processing.
See Also

IPerPropertyBrowsing, IPropertyPage, IPropertyPage2, IPropertyPageSite - Ole Implementation, ISpecifyPropertyPages


IPropertyPageSite::GetLocaleID

Returns the locale identifier (an LCID) that a property page can use to adjust itself to the language in use and other country-specific settings.

HRESULT GetLocaleID(

LCID* pLocaleID	//Receives a pointer to the locale identifier
);
Parameters

pLocaleID

[out] Pointer to locale identifier.

Return Values

S_OK

The locale was returned successfully.

E_POINTER

The address in pLocaleID is not valid. For example, it may be NULL.

See Also

OCPFIPARAMS, PROPPAGEINFO


IPropertyPageSite::GetPageContainer

Returns an IUnknown pointer to the object representing the entire property frame dialog box that contains all the pages. Calling this method could potentially allow one page to navigate to another.

However, there are no “container” interfaces currently defined for this role, so this method always fails in the current property frame implementation.

HRESULT GetPageContainer(

IUnknown** ppUnk	//Indirect pointer to the interface of the container object
);
Parameters

ppUnk

[out] Indirect pointer to the IUnknown interface on the container objectSet to NULL on failure.

Return Values

E_NOTIMPL

This is the only return value allowed at this time.


IPropertyPageSite::OnStatusChange

Informs the frame that the property page managed by this site has changed its state, that is, one or more property values have been changed in the page. Property pages should call this method whenever changes occur in their dialog boxes.

HRESULT OnStatusChange(

DWORD dwFlags	//Indicates what changes have occurred
);
Parameters

dwFlags

[in] Flags to indicate what changes have occurred. The dwFlags parameter can contain either of these two values to indicate the type of status change:

Flag Value	Description
PROPPAGESTATUS_DIRTY	Values in pages have changed so the state of the Apply button should be updated.
PROPPAGESTATUS_VALIDATE	Now is an appropriate time to apply changes.
Return Values

This method supports the standard return value E_INVALIDARG, as well as the following:

S_OK

The status change was noted.


IPropertyPageSite::TranslateAccelerator

Instructs the page site to process a keystroke if it desires.

HRESULT TranslateAccelerator(

LPMSG pMsg	//Pointer to MSG structure
);
Parameters

pMsg

[in] Pointer to the MSG structure to be processed.

Return Values

S_OK

The page site processed the message.

S_FALSE

The page site did not process the message.

E_NOTIMPL

The page site does not support keyboard processing.


IPropertyPageSite - Ole Implementation

The system provides an implementation of the IPropertyPageSite interface through the OleCreatePropertyFrame or OleCreatePropertyFrameIndirect functions.

The current frame implementation provided through OleCreatePropertyFrame and OleCreatePropertyFrameIndirect only implements the OnStatusChange and GetLocaleID methods.

Remarks

OnStatusChange

Indicates that the property page has changed.

GetLocaleID

Returns the locale identifier so the property page can adjust itself to country-specific settings.

GetPageContainer

Returns E_NOTIMPL.

TranslateAccelerator

Returns E_NOTIMPL.

See Also

IPropertyPageSite


IPropertySetStorage

Creates, opens, deletes, and enumerates property set storages that support instances of the IPropertyStorage interface. The IPropertyStorage interface manages a single property set in a property storage subobject; the IPropertySetStorage interface manages the storage of groups of such property sets. IPropertySetStorage can be supported by any file system entity, and is currently implemented in the OLE compound file object.

The IPropertySetStorage and IPropertyStorage interfaces provide a uniform way to create and manage property sets, whether or not these sets reside in a storage object that supports IStorage. When called through an object supporting IStorage (such as structured and compound files and directories) or IStream, the property sets created conform to the OLE property set format, described in detail in Appendix C of the OLE Programming Guide. Similarly, properties written using IStorage to the OLE property set format are visible through IPropertySetStorage and IPropertyStorage. IPropertyStorage does not support extensions to the OLE serialized property set format or multiple sections, because you can get equivalent functionality as simply by creating new sets or by adding new properties to existing property sets.

IPropertySetStorage methods identify property sets through a GUID called a format identifier (FMTID). The FMTID for a property set identifies the set of property identifiers in the property set, their meaning, and any constraints on the values. The format identifier of a property set should also provide the means to manipulate that property set. Only one instance of a given FMTID may exist at a time within a single property storage.

When to Implement

Implement IPropertySetStorage to store persistent properties in the file system. If you are using the OLE compound files implementation, you can use the implementation on the compound file object created through a call to StgCreateDocfile or StgOpenStorage. Once you have a pointer to any of the interface implementations (such as IStorage) on this object, you can call QueryInterface to get a pointer to the IPropertySetStorage interface implementation.

When to Use

Call IPropertySetStorage methods to create, open, or delete one or more property sets, or to enumerate the property sets contained in this property set storage.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IPropertySetStorage Methods	Description
Create	Creates a new property set.
Open	Opens a previously created property set.
Delete	Deletes an existing property set.
Enum	Creates and retrieves a pointer to an object that can be used to enumerate property sets.
See Also

IPropertyStorage, IEnumSTATPROPSETSTG, STATPROPSETSTG, PROPVARIANT


IPropertySetStorage::Create

Creates and opens a new property set in the property set storage object.

HRESULT Create(

REFFMTID  fmtid,	//Format identifier of the property set to be created
CLSID * pclsid,	//Pointer to initial CLSID for this property set
DWORD grfFlags,	//PROPSETFLAG values
DWORD grfMode,	//Storage mode of new property set
IPropertyStorage**  ppPropStg	//Indirect pointer to property storage sub-object
);
Parameters

fmtid

[in] Format identifier of the property set to be created.

pclsid

[in] Pointer to the initial CLSID for this property set. May be NULL, in which case it is set to all zeroes.

grfFlags

[in] Values from the PROPSETFLAG enumeration.

grfMode

[in] Access mode in which the newly created property set is to be opened, taken from certain values of the STGM enumeration, as described in the Remarks.

ppPropStg

[out] Indirect pointer to the IPropertyStorage interface on the new property storage sub-object.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The property set was created.

STG_E_FILEALREADYEXISTS

A property set of the indicated name already exists, and STGM_CREATE was not specified.

STG_E_ACCESSDENIED

The requested access to the property storage object has been denied.

STG_E_INSUFFICIENTMEMORY

There is not sufficient memory to perform this operation.

STG_E_INVALIDPARAMETER

A parameter is invalid.

Remarks

IPropertySetStorage::Create creates and opens a new property set sub-object (supporting the IPropertyStorage interface) contained in this property set storage object. The property set automatically contains code page and locale ID properties. These are set to the current system default, and the current user default, respectively.

The grfFlags parameter is a combination of values taken from the enumeration PROPSETFLAG.

The grfMode parameter specifies the access mode in which the newly created set is to be opened. Values for this parameter are as in the like-named parameter to IPropertySetStorage::Open, with the addition of the following values:

Value	Meaning
STGM_FAILIFTHERE	If another property set with the specified fmtid already exists, the call fails. This is the default action; that is, unless STGM_CREATE is specified, STGM_FAILIFTHERE is implied.
STGM_CREATE	If another property set with the specified fmtid already exists, it is removed and replaced with this new one.
STGM_DIRECT	Open the property set without an additional level of transaction nesting. This is the default (the behavior if neither STGM_DIRECT nor STGM_TRANSACTED is specified).
STGM_TRANSACTED	Open the property set with an additional level of transaction nesting (beyond the transaction, if any, on this property set storage). This is possible only when you specify PROPSETFLAG_NONSIMPLE in the grfFlags parameter. Changes in the property set must be committed with IPropertyStorage::Commit before they are visible to the transaction on this property set storage.
STGM_READ	Read access is desired on the property set. Read permission is required on the property set storage.
STGM_WRITE	Write access is desired on the property set. Write permission is not required on the property set storage; however, such write permission is required for changes in the storage to be committed.
STGM_READWRITE	Read-write access is desired on the property set. Note that this flag is not the binary OR of the values STGM_READ and STGM_WRITE.
STGM_SHARE_EXCLUSIVE	Prevents others from subsequently opening the property set either in STGM_READ or STGM_WRITE mode.
Note  The only access mode supported by Create is STGM_SHARE_EXCLUSIVE. To use the resulting property set in an access mode other than STGM_SHARE_EXCLUSIVE, the caller should close the stream and then re-open it with a call to IPropertySetStorage::Open.

See Also

IPropertySetStorage::Open


IPropertySetStorage::Delete

Deletes one of the property sets contained in the property set storage object.

HRESULT Delete(

REFFMTID fmtid	//Format identifier of the property set to be deleted.
);
Parameters

fmtid

[in] Format identifier of the property set to be deleted.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The property set was successfully deleted.

STG_E_FILENOTFOUND

The specified property set does not exist.

STG_E_ACCESSDENIED

The requested access to the property set storage object has been denied.

STG_E_INSUFFICIENTMEMORY

There is not sufficient memory to perform this operation.

STG_E_INVALIDPARAMETER

The parameter is invalid.

Remarks

IPropertySetStorage::Delete deletes the property set specified by its format identifier. Specifying a property set that does not exist returns an error. Open substorages and streams (opened through one of the storage- or stream-valued properties) are put into the reverted state.


IPropertySetStorage::Enum

Creates an enumerator object which contains information on the property sets stored in this property set storage. On return, this method supplies a pointer to the IEnumSTATPROPSETSTG pointer on the enumerator object.

HRESULT Enum(

IEnumSTATPROPSETSTG**ppenum	//Indirect pointer to the new enumerator
);
Parameters

ppenum

[out] Indirect pointer to the IEnumSTATPROPSETSTG on the newly created enumeration object.

Return Values

S_OK

The enumerator object was successfully created.

STG_E_INSUFFICIENTMEMORY

There is not sufficient memory to perform this operation.

Remarks

IPropertySetStorage::Enum creates an enumerator object that can be used to iterate through STATPROPSETSTG structures. These sometimes provide information on the property sets managed by IPropertySetStorage. This method, on return, supplies a pointer to the IEnumSTATPROPSETSTG interface on this enumerator object on return.

See Also

IEnumSTATPROPSETSTG, IEnumSTATPROPSETSTG -- Compound File Implementation


IPropertySetStorage::Open

Opens a property set contained in the property set storage object.

HRESULT Open(

REFFMTID  fmtid,	//The format identifier of the property set to be opened
DWORD grfMode,	//Storage mode in which property set is to be opened
IPropertyStorage**  ppPropStg	//Indirect pointer to property storage object
);
Parameters

fmtid

[in] Format identifier of the property set to be opened.

grfMode

[in] Access mode in which the newly created property set is to be opened. These flags are taken from the STGM enumeration. Flags that may be used and their meanings in the context of this method are described in the Remarks.

ppPropStg

[in] Indirect pointer to the IPropertyStorage interface on the requested property storage sub-object.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

Success.

STG_E_FILENOTFOUND

A property set of the indicated name does not exist.

STG_E_ACCESSDENIED

The requested access to the property storage object has been denied, or the property set is corrupted.

STG_E_INSUFFICIENTMEMORY

There is not sufficient memory to perform this operation.

STG_E_INVALIDPARAMETER

A parameter is invalid.

Remarks

The mode in which the property set is to be opened is specified in the parameter grfMode. These flags are taken from the STGM enumeration, but, for this method, legal values and their meanings are as follows (only certain combinations of these flag values are legal).

Value	Meaning
STGM_DIRECT	Open the property set without an additional level of transaction nesting. This is the default (the behavior if neither STGM_DIRECT nor STGM_TRANSACTED is specified).
STGM_TRANSACTED	Open the property set with an additional level of transaction nesting (beyond the transaction, if any, on this property set storage object). Transacted mode is available only on non-simple property sets, because they use an IStorage with a contents stream. Changes in the property set must be committed with a call to IPropertyStorage::Commit before they are visible to the transaction on this property set storage.
STGM_READ	Open the property set with read access. Read permission is required on the property set storage.
STGM_WRITE	Open the property set with write access. Write permission is not required on the IPropertySetStorage; however, such write permission is required for changes in the storage to be committed.
STGM_READWRITE	Open the property set with read-write access. Note that this flag is not the binary OR of the values STGM_READ and STGM_WRITE.
STGM_SHARE_DENY_NONE	Subsequent openings of the property set are not denied read or write access. Not available in compound file implementation.
STGM_SHARE_DENY_READ	Subsequent openings of the property set in are denied read access. Not available in compound file implementation.
STGM_SHARE_DENY_WRITE	Subsequent openings of the property set are denied write access. This value is typically used to prevent making unnecessary copies of an object opened by multiple users. If this value is not specified, a snapshot is made, whether there are subsequent openings or not. Thus, you can improve performance by specifying this value. Not available in compound file implementation.
STGM_SHARE_EXCLUSIVE	The combination of STGM_SHARE_DENY_READ and STGM_SHARE_DENY_WRITE.


IPropertySetStorage-Compound File Implementation

The OLE compound file storage object implementation includes an implementation of both IPropertyStorage, the interface that manages a single persistent property set, and IPropertySetStorage, the interface that manages groups of persistent property sets.

To get a pointer to the compound file implementation of IPropertySetStorage, first call StgCreateDocfile to create a new compound file object or StgOpenStorage to open a previously created compound file. Both functions supply a pointer to the object’s IStorage interface. When you want to deal with persistent property sets, call IStorage::QueryInterface for the IPropertySetStorage interface, specifying the header-defined name for the interface identifier IID_IPropertySetStorage.

When to Use

Call the methods of IPropertySetStorage to create, open, or delete property sets in the current compound file property set storage. There is also a method that supplies a pointer to an enumerator that can be used to enumerate the property sets in the storage.

Remarks

IPropertySetStorage::Create

Creates a new property set in the current compound file storage and, on return, supplies an indirect pointer to the IPropertyStorage compound file implementation. In this implementation, property sets may be transacted only if PROPSETFLAG_NONSIMPLE is specified.

IPropertySetStorage::Open

Opens an existing property set in the current property storage. On return, it supplies an indirect pointer to the compound file implementation of IPropertyStorage.

IPropertySetStorage::Delete

Deletes a property set in this property storage.

IPropertySetStorage::Enum

Creates an object that can be used to enumerate STATPROPSETSTG structures. Each STATPROPSETSTG structure provides information about a single property set. The implementation calls the constructor for IEnumSTATPROPSETSTG, which, in turn, uses the pointer to the IStorage interface to create a STATSTG enumerator, which is then used over the actual storage to get the information about the property sets.

Note  The DocumentSummaryInformation property set is special, in that it may have two property set sections. This property set is described in the OLE Programmer’s Reference, in the section titled The DocumentSummaryInformation Property Set. The second section is referred to as the User-Defined Properties. Each section is identified with a unique Format ID, for example FMTID_DocumentSummaryInformation and FMTID_UserDefinedProperties.

When IPropertySetStorage::Create is called to create the User-Defined Property Set, the first section is created automatically. Thus once FMTID_UserDefinedProperties is created, FMTID_DocumentSummaryInformation need not be created, but can be opened with a call to IPropertySetStorage::Open. Note that creating the first section does not automatically create the second section. It is not possible to open both sections simultaneously.

When IPropertySetStorage::Create is called to create the User-Defined Property Set, the first section is created automatically. Thus once FMTID_UserDefinedProperties is created, FMTID_DocumentSummaryInformation need not be created, but can be opened with a call to IPropertySetStorage::Open. Note that creating the first section does not automatically create the second section. It is not possible to open both sections simultaneously.

Alternately, when IPropertySetStorage::Delete is called to delete the first section, both sections are deleted. That is, calling IPropertySetStorage::Delete with FMTID_DocumentSummaryInformation, causes both that section and the FMTID_UserDefinedProperties section to be deleted. Note that deleting the second section does not automatically delete the first section.

Finally, when IPropertySetStorage::Enum is used to enumerate property sets, the User-Defined Property Set will not be enumerated.

See Also

IPropertyStorage, IPropertySetStorage - Compound File Implementation, STATPROPSETSTG structure, PROPSETFLAG enumeration, IStorage::EnumElements


IPropertyStorage

Manages the persistent properties of a single property set. Persistent properties consist of information that can be stored persistently in a property set, such as the summary information associated with a file. This contrasts with run-time properties associated with Controls and Automation, which can be used to affect system behavior. Use the methods of the IPropertySetStorage interface to create or open a persistent property set. An IPropertySetStorage instance can manage zero or more IPropertyStorage instances.

Each property within a property set is identified by a property identifier, a four-byte ULONG value unique to that set. You can also assign a string name to a property through the IPropertyStorage interface.

Property identifiers are different from the dispatch identifiers used in Automation dispid property name tags. One difference is that the general-purpose use of property identifier values zero and one is prohibited in IPropertyStorage, while no such restriction exists in IDispatch. In addition, while there is significant overlap in the data types for property values that may be used in IPropertyStorage and IDispatch, the sets are not identical. Persistent property data types used in IPropertyStorage methods are defined in the PROPVARIANT structure.

When to Implement

Implement IPropertyStorage when you want to store properties in the file system. If you are using the OLE compound files implementation, the compound file object created through a call to StgCreateDocfile includes an implementation of IPropertySetStorage, which allows access to the implementation of IPropertyStorage. Once you have a pointer to any of the interface implementations (such as IStorage) on this object, you can call QueryInterface to get a pointer to the IPropertySetStorage interface implementation, and then call either the Open or Create method, as appropriate to obtain a pointer to the IPropertyStorage interface managing the specified property set.

When to Use

Use IPropertyStorage to create and manage properties that are stored in a given property set.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IPropertyStorage Methods	Description
ReadMultiple	Reads property values in a property set.
WriteMultiple	Writes property values in a property set.
DeleteMultiple	Deletes properties in a property set.
ReadPropertyNames	Gets corresponding string names for given property identifiers.
WritePropertyNames	Creates or changes string names corresponding to given property identifiers.
DeletePropertyNames	Deletes string names for given property identifiers.
SetClass	Assigns a CLSID to the property set.
Commit	As in IStorage::Commit, flushes or commits changes to the property storage object.
Revert	When the property storage is opened in transacted mode, discards all changes since the last commit.
Enum	Creates and gets a pointer to an enumerator for properties within this set.
Stat	Receives statistics about this property set.
SetTimes	Sets modification, creation, and access times for the property set.
See Also

IPropertySetStorage, IEnumSTATPROPSTG, IEnumSTATPROPSETSTG, STATPROPSTG, STATPROPSETSTG, PROPVARIANT


IPropertyStorage::Commit

Saves any changes made to a property storage object to the parent storage object.

HRESULT Commit(

DWORD  grfCommitFlags	//Flags specifying conditions for the commit
);
Parameters

grfCommitFlags

[in] Flags specifying the conditions under which the commit is to be performed. Specific flags and their meanings are described in the following Remarks section.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The changes were saved successfully.

STG_E_NOTCURRENT

STGC_ONLYIFCURRENT was specified, but the optimistic concurrency control failed.

STG_E_ACCESSDENIED

The requested access to the property storage object has been denied.

STG_E_INSUFFICIENTMEMORY

There is not sufficient memory to perform this operation.

STG_E_INVALIDPARAMETER

One or more flags specified in grfCommitFlags is invalid.

Remarks

As in IStorage::Commit, ensures that any changes made to a property storage object are reflected in the parent storage.

In direct mode in the compound file implementation, this call causes any changes currently buffered up in memory to be flushed to the underlying property stream. In the compound file implementation for non-simple property sets, IStorage::Commit is also called on the underlying substorage object with the passed grfCommitFlags parameter.

In transacted mode, this method causes the changes to be permanently reflected in the persistent image of the storage object. The changes that are committed must have been made to this property set since it was opened or since the last commit on this opening of the property set. One could think of the action of committing as publishing the changes that this level currently knows about one more layer outwards. Of course, this is still subject to any outer level transaction that may be present on the object in which this property set is contained. Write permission must be specified when the property set is opened (through IPropertySetStorage) on the property set opening for the commit operation to succeed.

If the commit operation fails for any reason, the state of the property storage object is as it was before the commit.

This call has no effect on existing storage- or stream-valued properties opened from this property storage, but it does commit them.

Valid values for the grfCommitFlags parameter are as follows:

Value	Meaning
STGC_DEFAULT	Commit per the usual transaction semantics. Last writer wins. This flag may not be specified with other flag values.
STGC_ONLYIFCURRENT	Commit the changes only if the current persistent contents of the property set are the ones on which the changes about to be committed are based. That is, do not commit changes if the contents of the property set have been changed by a commit from another opening of the property set. The error STG_E_NOTCURRENT is returned if the commit does not succeed for this reason.
STGC_OVERWRITE	Only useful when committing a transaction which has no further outer nesting level of transactioning, though legal in all cases. Indicates that the caller is willing to take some risk of data corruption at the expense of a decreased usage of disk on the destination volume. This flag is potentially useful in low disk space scenarios, though should be used only with caution.
See Also

IPropertyStorage::ReadMultiple, IStorage::Commit


IPropertyStorage::DeleteMultiple

Deletes as many of the indicated properties as exist in this property set.

HRESULT DeleteMultiple(

ULONG cpspec,	//Count of properties to be deleted
PROPSPEC const rgpspec[]	//Array of properties to be deleted
);
Parameters

cpspec

[in] Count of properties being deleted. May legally be zero, though this is a no-op, deleting no properties.

rgpspec[]

[in] Properties to be deleted. A mixture of property identifiers and string-named properties is permitted. There may be duplicates, and there is no requirement that properties be specified in any order.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

All of the specified properties that exist in the property set have been deleted.

STG_E_ACCESSDENIED

The requested access to the property storage object has been denied. No properties were deleted.

STG_E_INSUFFICIENTMEMORY

There is not sufficient memory to perform this operation. Some properties may not have been deleted.

STG_E_INVALIDPARAMETER

At least one of the parameters is invalid, as when one of the PROPSPECs contains an illegal ulKind value. Some properties may not have been deleted.

STG_E_INVALIDPOINTER

May be returned when at least one of the pointers passed in is invalid. Some properties may not have been written. More frequently, an invalid pointer will instead result in an access violation.

Remarks

IPropertyStorage::DeleteMultiple must delete as many of the indicated properties as are in the current property set. If a deletion of a stream- or storage-valued property occurs while that property is open, the deletion will succeed and place the previously returned IStream or IStorage pointer in the reverted state.


IPropertyStorage::DeletePropertyNames

Deletes specified string names from the current property set.

HRESULT DeletePropertyNames(

ULONG cpropid,	//Size of the rgpropid array
PROPID const rgpropid[]	//Property identifiers for which string names are to be deleted
);
Parameters

cpropid

[in] The size on input of the array rgpropid. If 0, no property names are deleted.

rgpropid[]

[in] Property identifiers for which string names are to be deleted.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

Success. The names of all of the indicated properties that exist in this set have been deleted.

STG_E_ACCESSDENIED

The requested access to the property storage object has been denied. No property names were deleted.

STG_E_INSUFFICIENTMEMORY

There is not sufficient memory to perform this operation. Some property names may not have been deleted.

STG_E_INVALIDPARAMETER

At least one of the parameters is invalid. Some property names may not have been deleted.

Remarks

For each property identifier in rgpropid, IPropertyStorage::DeletePropertyNames removes the corresponding name-to-property identifier mapping, if any. An attempt to delete the name of a property that either does not exist or does not presently have a string name associated with it is silently ignored. This method has no effect on the properties themselves.

Note  All the stored string property names can be deleted by deleting property identifier zero, but cpropid must be equal to 1 for this to not be an invalid parameter error.

See Also

IPropertyStorage::ReadPropertyNames


IPropertyStorage::Enum

Creates an enumerator object designed to enumerate data of type STATPROPSTG, which contains information on the current property set. On return, this method supplies a pointer to the IEnumSTATPROPSTG pointer on this object.

HRESULT Enum(

IEnumSTATPROPSTG**  ppenum	//Indirect pointer to new enumerator
);
Parameters

ppenum

[out] Indirect pointer to the IEnumSTATPROPSTG interface on the new enumeration object.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

A pointer to the enumerator has been retrieved.

STG_E_ACCESSDENIED

The requested access to the property storage object has been denied.

STG_E_INSUFFICIENTMEMORY

There is not sufficient memory to perform this operation.

STG_E_INVALIDPARAMETER

The parameter is invalid.

STG_E_READFAULT

Error reading storage.

Remarks

IPropertyStorage::Enum creates an enumeration object that can be used to iterate STATPROPSTG structures. On return, this method supplies a pointer to an instance of IEnumSTATPROPSTG interface on this objects whose methods you can call to obtain information on the current property set.

See Also

IEnumSTATPROPSTG, IEnumSTATPROPSTG -- Compound File Implementation


IPropertyStorage::ReadMultiple

Reads specified properties from the current property set.

HRESULT ReadMultiple(

ULONG cpspec,	//Count of properties being read.
PROPSPEC const rgpspec[],	//Array of the properties to be read
PROPVARIANT rgvar[]	//Array of PROPVARIANTs containing the property values on return
);
Parameters

cpspec

[in] Count of properties specified in the rgpspec array. May legally be zero, though this is a no-op, reading no properties.

rgpspec[]

[in] The properties to be read in the PROPSPEC structures. Properties can be specified either by property identifier or by optional string name. It is not necessary to specify properties in any particular order in the array. The array can contain duplicate properties, resulting in duplicate property values on return for simple properties. Non-simple properties should return access denied on an attempt to open them a second time. The array can contain a mixture of property identifiers and string identifiers.

rgvar[]

[in, out] Caller-allocated array of PROPVARIANTs that, on return, contains the values of the properties specified by rgpspec. The array must be able to receive at least cpspec PROPVARIANTs. The caller does not need to initialize these PROPVARIANTs in any particular way; the implementation must fill in all field members correctly on return. If there is no other appropriate value, the implementation must set the vt member of each PROPVARIANT to VT_EMPTY.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

Success. At least some of the requested properties were retrieved.

S_FALSE

All the property names or identifiers had valid syntax, but none of them exist in this property set. Accordingly, no properties were retrieved., and each PROPVARIANT structure is set to VT_EMPTY.

STG_E_ACCESSDENIED

The requested access to the property set has been denied, or, when one or more of the properties is a stream or storage object, access to that substorage or substream has been denied. (The storage or stream may already be open). No properties were retrieved.

STG_E_INSUFFICIENTMEMORY

There is not sufficient memory to perform this operation. No properties were retrieved.

STG_E_INVALIDPARAMETER

At least one of the parameters is invalid, such as when one of the PROPSPECs contains an illegal ulKind value. No properties were retrieved.

STG_E_INVALIDPOINTER

At least one of the pointers passed in is invalid. No properties were retrieved.

HRESULT_FROM_WIN32(ERROR_NO_UNICODE_TRANSLATION)

There was a failed attempt to translate a Unicode string to or from Ansi.

Remarks

IPropertyStorage::ReadMultiple reads as many of the properties specified in the rgpspec array as are found in the property set. As long as any of the properties requested is read, a request to retrieve a property that does not exist is not an error. Instead, this must cause VT_EMPTY to be written for that property to the rgvar[] array on return. When none of the requested properties exist, the method should return S_FALSE, and set VT_EMPTY in each PROPVARIANT. If any other error is returned, no property values are retrieved, and the caller need not worry about releasing them.

The rgpspec parameter is an array of PROPSPEC structures, which specify for each property either its property identifier or, if one is assigned, a string identifier. You can map a string to a property identifier by calling IPropertyStorage::WritePropertyNames. The use of property identifiers is, however, likely to be significantly more efficient than the use of strings.

Properties that are requested by string name (PRSPEC_LPWSTR) are mapped case-insensitively to property identifiers as they are specified in the current property set (and according to the current system locale).

All propvariants, except for those that are pointers to streams and storages, are called simple propvariants. These simple propvariants receive data by value, so a call to IPropertyStorage::ReadMultiple supplies a copy of the data that the caller then owns. To create or update these properties, call IPropertyStorage::WriteMultiple.

In contrast, the variant types VT_STREAM, VT_STREAMEDOBJECT, VT_STORAGE, and VT_STOREDOBJECT are non-simple properties, because rather than supplying a value, the method retrieves a pointer to the indicated interface, from which the data can then be read. These types permit the storage of large amounts of information through a single property. There are several issues that arise in using non-simple properties.

To create these properties, as for the other properties, call IPropertyStorage::WriteMultiple. Rather than calling the same method to update, however, it is more efficient to first call IPropertyStorage::ReadMultiple to get the interface pointer to the stream or storage, then write data using the IStream or IStorage methods. A stream or storage opened through a property is always opened in direct mode, so an additional level of nested transaction is not introduced. There may, however, still be a transaction on the property set as a whole, depending on how it was opened or created through IPropertySetStorage. Further, the access and share mode tags specified when the property set is opened or created, are passed to property-based streams or storages.

The lifetimes of property-based stream or storage pointers, although theoretically independent of their associated IPropertyStorage and IPropertySetStorage pointers, in fact, effectively depend on them. The data visible through the stream or storage is related to the transaction on the property storage object from which it is retrieved, just as for a storage object (supporting IStorage) with contained stream and storage sub-objects. If the transaction on the parent object is aborted, existing IStream and IStorage pointers subordinate to that object enter a “zombie” state. Because IPropertyStorage is the only interface on the property storage object, the useful lifetime of the contained IStream and IStorage pointers is bounded by the lifetime of the IPropertyStorage interface.

The implementation must also deal with the situation where the same stream- or storage-valued property is requested multiple times through the same IPropertyStorage interface instance. For example, in the OLE compound file implementation, the open will succeed or fail depending on whether or not the property is already open.

Another issue is multiple opens in transacted mode. The result depends on the isolation level that was specified through a call to IPropertySetStorage methods, (either the Open or Create method, through the STGM flags) at the time that the property storage was opened .

If the call to open the property set specifies read-write access, IStorage- and IStream-valued properties are always opened with read-write access. Data can then be written through these interfaces, changing the value of the property, which is the most efficient way to update these properties. The property value itself does not have an additional level of transaction nesting, so changes are scoped under the transaction (if any) on the property storage object.

See Also

IPropertySetStorage, IPropertyStorage::WriteMultiple, IPropertyStorage::WritePropertyNames


IPropertyStorage::ReadPropertyNames

Retrieves any existing string names for the specified property identifiers.

HRESULT ReadPropertyNames(

ULONG  cpropid,	//Number of elements in rgpropid
PROPID const  rgpropid[],	//Property identifiers for which names are to be retrieved.
LPWSTR  rglpwstrName[]	//Array of returned string names
);
Parameters

cpropid

[in] Number of elements on input of the array rgpropid. May legally be zero, though this is a no-op, reading no property names.

rgpropid[]

[in] Array of property identifiers for which names are to be retrieved.

rglpwstrName[]

[in, out] Caller-allocated array of size cpropid of LPWSTRs. On return, the implementation fills in this array. A given entry contains either the corresponding string name of a property identifier or NULL if the property identifier has no string name.

Each LPWSTR member of the array should be freed using CoTaskMemFree.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

One or more string names were retrieved and all members of rglpwstrName are valid (either NULL or a valid LPWSTR).

S_FALSE

No string names were retrieved because none of the requested property identifiers have string names presently associated with them in this property storage object (this result does not address whether the given property identifiers presently exist in the set).

STG_E_INVALIDHEADER

The property name dictionary was not found.

STG_E_READFAULT

Error reading the storage.

STG_E_ACCESSDENIED

The requested access to the property storage object has been denied. No string names were retrieved.

STG_E_INSUFFICIENTMEMORY

There is not sufficient memory to perform this operation. No string names were retrieved.

STG_E_INVALIDPARAMETER

A parameter is invalid. No string names were retrieved.

HRESULT_FROM_WIN32(ERROR_NO_UNICODE_TRANSLATION)

There was a failed attempt to translate a Unicode string to or from Ansi.

Remarks

For each property identifier in the list of property identifiers supplied in the rgpropid array, IPropertyStorage::ReadPropertyNames retrieves the corresponding string name, if there is one. String names are created either by specifying the names in calls to IPropertyStorage::WriteMultiple when you are creating the property, or through a call to IPropertyStorage::WritePropertyNames. In any case, the string name is optional; all properties must have a property identifier.

String names mapped to property identifiers must be unique within the set.

See Also

IPropertyStorage::WritePropertyNames, IPropertyStorage::WriteMultiple


IPropertyStorage::Revert

Discards all changes to the property set it was opened or changes were last committed. Has no effect on a direct-mode property set.

HRESULT Revert();

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

Success.

Remarks

For transacted-mode property sets, discards all changes that have been made in this property set since set was opened or the time it was last committed (depending on which is later). After this operation, any existing storage- or stream-valued properties that have been opened from the property set being reverted are invalid and can no longer be used. The error STG_E_REVERTED will be returned on all calls except Release using these streams or storages.

For direct-mode property sets, this request is ignored and returns S_OK.

See Also

IPropertyStorage::Commit


IPropertyStorage::Stat

Retrieves information about the current open property set.

HRESULT Stat(

STATPROPSTG*  pstatpsstg	//Pointer to a filled-in STATPROPSETSTG structure
);
Parameters

pstatpsstg

[out] Pointer to a STATPROPSETSTG structure, which contains statistics about the current open property set.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

Statistics were successfully obtained.

STG_E_ACCESSDENIED

The requested access to the property storage object has been denied.

STG_E_INSUFFICIENTMEMORY

There is not sufficient memory to perform this operation.

STG_E_INVALIDPARAMETER

The parameter is invalid.

Remarks

IPropertyStorage::Stat fills in and returns a pointer to a STATPROPSETSTG structure, containing statistics about the current property set. STATPROPSETSTG fields have the following meanings:

Field	Meaning
fmtid	The FMTID of this property set, specified when the property set was initially created.
clsid	The CLSID of this property set, specified when the property set was initially created and possibly modified thereafter with IPropertyStorage::SetClass. If not set, the value will be CLSID_NULL.
grfFlags	The flag values this set was created with. For details, see IPropertySetStorage::Create.
mtime	The time in UTC (FILETIME) at which this property set was last modified. Not all IPropertyStorage implementations maintain modification times on property sets; those who do not will return zero for this value.
ctime	The time in UTC (FILETIME) at which this property set was created. Not all IPropertyStorage implementations maintain creation times on property sets; those that do not will set this value to 0.
atime	The time in UTC (FILETIME) at which this property set was last accessed. Not all IPropertyStorage implementations maintain last access times on property sets; those that do not will set this value to 0.
See Also

STATPROPSETSTG structure, IPropertySetStorage::Enum, FILETIME structure


IPropertyStorage::SetClass

Assigns a new CLSID to the current property storage object, and persistently stores the CLSID with the object.

HRESULT SetClass(

REFCLSID  clsid	//New CLSID for the property set
);
Parameters

clsid

[in] New CLSID to be associated with the property set.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The CLSID has been assigned.

STG_E_ACCESSDENIED

The requested access to the IPropertyStorage interface has been denied. The CLSID was not assigned.

STG_E_INSUFFICIENTMEMORY

There is not sufficient memory to perform this operation. The CLSID was not assigned.

STG_E_INVALIDPARAMETER

The parameter is invalid. The CLSID was not assigned.

Remarks

Assigns a CLSID to the current property storage object. The CLSID has no relationship to the stored property identifiers. Assigning a CLSID allows a piece of code to be associated with a given instance of a property set; such code, for example, might manage the user interface. Different CLSIDs can be associated with different property set instances that have the same FMTID.

If the property set is created with NULL specified as the IPropertySetStorage::Create pclsid parameter, the CLSID is set to all zeroes.

The current CLSID on a property storage object can be retrieved with a call to IPropertyStorage::Stat. The initial value for the CLSID can be specified at the time that the storage is created with a call to IPropertySetStorage::Create.

Setting the CLSID on a non-simple property set (one that can legally contain storage- or stream-valued properties, as described in IPropertySetStorage::Create) also sets the CLSID on the underlying sub-storage.

See Also

IPropertySetStorage::Create, IPropertyStorage::Stat


IPropertyStorage::SetTimes

Sets the modification, access, and creation times of this property set, if supported by the implementation. Not all implementations support all these time values.

HRESULT SetTimes(

FILETIME const *  pctime,	//New creation time for the property set
FILETIME const *  patime,	//New access time for the property set
FILETIME const *  pmtime	//New modification time for the property set
);
Parameters

pctime

[in] Pointer to the new creation time for the property set. May be NULL, indicating that this time is not to be modified by this call.

patime

[in] Pointer to the new access time for the property set. May be NULL, indicating that this time is not to be modified by this call.

pmtime

[in] Pointer to the new modification time for the property set. May be NULL, indicating that this time is not to be modified by this call.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

All the requested times have been successfully updated.

STG_E_ACCESSDENIED

The requested access to the property storage object has been denied; no times have been updated.

STG_E_INSUFFICIENTMEMORY

There is not sufficient memory to perform this operation.

STG_E_INVALIDPARAMETER

The parameter is invalid. This error is returned if an attempt is made to set a time value which is not supported by this implementation.

Remarks

Sets the modification, access, and creation times of the current open property set, if supported by the implementation (not all implementations support all these time values). Unsupported timestamps are always reported as zero, enabling the caller to test for support. A call to IPropertyStorage::Stat supplies (among other information) timestamp information.

Notice that this functionality is provided as an IPropertyStorage method on a property storage object that is already open, in contrast to being provided as a method in IPropertySetStorage. Normally, when the SetTimes method is not explicitly called, the access and modification times are updated as a side effect of reading and writing the property set. When SetTimes is used, the latest specified times supersede either default times or time values specified in previous calls to SetTimes.

See Also

IPropertyStorage::Stat, FILETIME structure


IPropertyStorage::WriteMultiple

Writes a specified group of properties to the current property set. If a property with a specified name already exists, it is replaced, even when the old and new types for the property value are different. If a property of a given name or property identifier does not exist, it is created.

HRESULT WriteMultiple(

ULONG cpspec,	//The number of properties being set.
PROPSPEC const rgpspec[],	//Property specifiers
PROPVARIANT const rgvar[],	//Array of PROPVARIANT values
PROPID propidNameFirst	//Minimum value for property identifiers when they must be allocated
);
Parameters

cpspec

[in] The number of properties being set. May legally be zero, though this is a no-op, writing no properties.

rgpspec[]

[in] Array of the specifiers to which properties are to be set. These are in no particular order, and may legally contain duplicates (the last specified is to take effect). A mixture of property identifiers and string names is permitted.

rgvar[]

[in] An array (of size cpspec) of PROPVARIANTs that contain the property values to be written. The array must be of the size specified by cpspec.

propidNameFirst

[in] Specifies the minimum value for the property identifiers the method must assign if the rgpspec parameter specifies string-named properties for which no property identifiers currently exist. If all string-named properties specified already exist in this set, and thus already have property identifiers, this value is ignored. When not ignored, this value must be at least two (property identifiers 0and 1 are reserved for special uses) and less than 0x80000000 (property identifier values beyond that are reserved for special use).

HRESULT_FROM_WIN32(ERROR_NO_UNICODE_TRANSLATION)

There was a failed attempt to translate a Unicode string to or from Ansi.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

All of the indicated properties were successfully written.

STG_E_ACCESSDENIED

The requested access to the property storage object has been denied. No properties have been written. The property set was opened in STGM_READ mode.

STG_E_INSUFFICIENTMEMORY

There is not sufficient memory to perform this operation. Some properties may or may not have been written.

STG_E_INVALIDPARAMETER

At least one of the parameters is invalid. Some properties may not have been written. This error would be returned in several situations, for example: 1) rgvar may be NULL; 2) a stream- or storage-valued property is present in rgpspec but the property set was created without PROPSETFLAG_NONSIMPLE; 3) one or more property variant types may be invalid; 4) one of the PROPSPECs contains an illegal ulKind value.

STG_E_INVALIDPOINTER

May be returned when at least one of the pointers passed in is invalid. Some properties may or may not have been written. More frequently, an invalid pointer will instead result in an access violation.

STG_E_WRITEFAULT

Error writing the storage.

STG_E_REVERTED

The property set was reverted. For example, if the property set is deleted while open (by using IPropertySetStorage::Delete) this status would be returned.

STG_E_MEDIUMFULL

The disk is full. Some properties may or may not have been written.

STG_E_PROPSETMISMATCHED

An attempt was made to write a non-simple (stream- or storage-valued) property to a simple property set.

Remarks

If a specified property already exists, it’s value is replaced with the new one, even when the old and new types for the property value are different. If you specify a property identifier that does not exist, that property is created. If a string name is supplied for a property which does not exist, the method will allocate a property identifier for that property, and the name will be added to the dictionary.

When allocating a property identifier, the implementation can choose any value not currently in use in the property set for a property identifier, as long as it is not 0 or 1 or greater than 0x80000000, all of which are reserved values. The propidNameFirst parameter establishes a minimum value for property identifiers within the set, and must be greater than 1 and less than 0x80000000.

If there is an attempt to write a property that already exists with an invalid parameter, the method should return STG_E_INVALIDPARAMETER; if the property does not exist, it should not be created. This behavior facilitates the use of a ReadMultiple − update − WriteMultiple sequence to update a group of properties without requiring that the calling code ensure that all the requested properties in the call to ReadMultiple were retrieved.

It is recommended that property sets be created as Unicode, by not setting the PROPSETFLAG_ANSI flag in the grfFlags parameter of IPropertySetStorage::Create. It is also recommended that you avoid using VT_LPSTR values, and use VT_LPWSTR values instead. When the property set code page is Unicode, VT_LPSTR string values are converted to Unicode when stored, and back to multibyte string values when retrieved. When the code page of the property set is not Unicode, property names, VT_BSTR strings, and non-simple property values are converted to multibyte strings when stored, and converted back to Unicode when retrieved, all using the current system ANSI code page.

To create stream or storage object as a property in a nonsimple property set, call IPropertyStorage::WriteMultiple. While you would also call this method to update simple properties, it is not an efficient way to update stream and storage objects in a property set. This is because updating one of these properties through a call to WriteMultiple creates in the property storage object a copy of the passed-in data, and the IStorage or IStream pointers are not retained beyond the duration of this call. It is usually more efficient to update stream or storage objects by first calling IPropertyStorage::ReadMultiple to get the interface pointer to the stream or storage, then writing data through the IStream or IStorage methods.

A stream or storage opened through a property is always opened in direct mode, so an additional level of nested transaction is not introduced. There is still likely to be a transaction on the property set as a whole. Further, a property-based stream or storage is opened in read-write mode, if possible, given the mode on the property set; otherwise, read mode is used.

When the copy is made, the underlying CopyTo operation on VT_STREAM properties operates on the current seek position of the source. The seek position is destroyed on failure, but on success it is at EOF.

If a stream or storage property does not exist, passing an IStream or IStorage pointer with a value of NULL creates an empty stream or storage property value. If a stream or storage property is already open from a call to ReadMultiple, a NULL value must cause the WriteMultiple operation to truncate it and return S_OK, placing the previously returned stream- and storage-valued pointers into the reverted state (as happens in the compound file implementation.)

Storage- and stream-valued properties always manifest themselves to downlevel clients as sibling streams or storages to the stream containing the main contents of the property set—they are never stored directly in-line in the property set. This allows smooth interoperability and control when down-level clients interact with up-level clients. Thus, from a downlevel perspective, property sets containing IStream or IStorage valued properties are always stored in a storage object, not a stream. The specific name of the sibling used is completely under the control of the IPropertyStorage implementation, as long as the name is from the non-reserved part of the IStorage name space. See Appendix C of the OLE Programmer’s Guide for a discussion of the serialized property set format for further details. As is described there, the string name is stored in the same format as a VT_BSTR. Refer also to the earlier discussion in this method of multibyte to Unicode conversions for property names.

If the WriteMultiple method returns an error when writing stream- or storage-valued properties (indirect properties), the amount of data actually written is undefined. If the caller requires consistency of the property set and its indirect properties when writing stream- and/or storage-valued properties, use of transacted mode is advised.

If an implicit deletion of a stream- or storage-valued property occurs while that property is open, (as, for example, when a VT_I4 is written over a VT_STREAM), the deletion will succeed and place the previously returned IStream pointer in the reverted state.

See Also

IPropertySetStorage::Create, IPropertyStorage::ReadMultiple


IPropertyStorage::WritePropertyNames

Assigns string names to a specified array of property IDs in the current property set.

HRESULT WritePropertyNames(

ULONG  cpropid,	//Size on input of the array rgpropid
PROPID const  rgpropid[],	//Property identifiers for which names are to be set
LPWSTR const  rglpwstrName[],	//New names of the corresponding property identifiers
);
Parameters

cpropid

[in] Size on input of the array rgpropid. May legally be zero, though this is a no-op, writing no property names.

rgpropid[]

[in] Array of the property identifiers for which names are to be set.

rglpwstrName[]

[in] Array of new names to be assigned to the corresponding property identifiers in the rgpropid array. These names may not exceed 255 characters (not including the NULL terminator).

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

Success. All of the indicated string names were successfully set.

STG_E_INVALIDNAME

At least one of the indicated property identifier values does not exist in this property set. No names were set.

STG_E_ACCESSDENIED

The requested access to the property storage object has been denied. No property names have been changed in the storage.

STG_E_INSUFFICIENTMEMORY

There is not sufficient memory to perform this operation. Some names may not have been set.

STG_E_INVALIDPARAMETER

A parameter is invalid. Some names may not have been set.

HRESULT_FROM_WIN32(ERROR_NO_UNICODE_TRANSLATION)

There was a failed attempt to translate a Unicode string to or from Ansi.

Remarks

IPropertyStorage::WritePropertyNames assigns string names to property identifiers passed to the method in the rgpropid array. It associates each string name in the rglpwstrName array with the respective property identifier in rgpropid. It is explicitly valid to define a name for a property identifier that is not currently present in the property storage object.

It is also valid to change the mapping for an existing string name (determined by a case-insensitive match). That is, you can use the WritePropertyNames method to map an existing name to a new property identifier, or to map a new name to a property identifier that already has a name in the dictionary. In either case, the original mapping is deleted. Property names must be unique (as are property identifiers) within the property set.

The storage of string property names preserves the case. String property names are limited in length to 128 characters. Property names that begin with the binary Unicode characters 0x0001 through 0x001F are reserved for future use.

See Also

IPropertyStorage::ReadPropertyNames, IPropertyStorage::ReadMultiple, IPropertyStorage::WriteMultiple


IPropertyStorage-Compound File Implementation

The OLE implementation of the Structured Storage architecture is called compound files. Storage objects as implemented in compound files include an implementation of both IPropertyStorage, the interface that manages a single persistent property set, and IPropertySetStorage, the interface that manages groups of persistent property sets.

To get a pointer to the compound file implementation of IPropertyStorage, first call StgCreateDocfile to create a new compound file object or StgOpenStorage, to open a previously created compound file. Both functions supply a pointer to the object’s IStorage interface. When you want to deal with persistent property sets, call QueryInterface for the IPropertySetStorage interface, specifying the header-defined name for the interface identifier IID_IPropertySetStorage. Calling either the Create or Open method of that interface, you get a pointer to the IPropertyStorage interface, which you can use to call any of its methods.

When to Use

Use IPropertyStorage to manage properties within a single property set. Its methods support reading, writing, and deleting both properties and the optional string names that can be associated with property identifiers. Other methods support the standard commit and revert storage operations. There is also a method that allows you to set times associated with the property storage, and another that permits the assignment of a CLSID that can be used to associate other code, such as user interface code, with the property set. Calling the Enum method supplies a pointer to the compound file implementation of IEnumSTATPROPSTG, which allows you to enumerate the properties in the set.

Remarks

The compound file implementation of IPropertyStorage caches open property sets in memory in order to improve performance. As a result, changes to a property set are not written to the compound file until the Commit or Release (last reference) methods are called.

IPropertyStorage::ReadMultiple

Reads the properties specified in the rgpspec array and supplies the values of all valid properties in the rgvar array of PROPVARIANTs. In the OLE compound file implementation, duplicate property identifiers that refer to stream- or storage-types result in multiple calls to IStorage::OpenStream or IStorage::OpenStorage and the success or failure of ReadMultiple depends on the underlying storage implementation’s ability to share opens. Because in a compound file STGM_SHARE_EXCLUSIVE is forced, multiple opens will fail. Opening the same storage object more than once from the same parent storage is not supported. The STGM_SHARE_EXCLUSIVE flag must be specified.

In addition, to ensure thread-safe operation if the same stream- or storage-valued property is requested multiple times through the same IPropertyStorage pointer in the OLE compound file implementation, the open will succeed or fail depending on whether or not the property is already open and on whether the underlying file system handles multiple opens of a stream or storage. Thus, the ReadMultiple operation on a stream- or storage-valued property always results in a call to IStorage::OpenStream, or IStorage::OpenStorage, passing the access (STGM_READWRITE, etc.) and share flags (STGM_SHARE_EXCLUSIVE, etc) specified when the original property set was opened or created.

If the method fails, the values written to rgvar[] are undefined. If some stream- or storage-valued properties are opened successfully but an error occurs before execution is complete, these should be released before the method returns.

IPropertyStorage::WriteMultiple

Writes the properties specified in the rgpspec[] array, assigning them the PROPVARIANT tags and values specified in rgvar[]. Properties that already exist are assigned the specified PROPVARIANT values, and properties that do not currently exist are created.

IPropertyStorage::DeleteMultiple

Deletes the properties specified in the rgpspec[].

IPropertyStorage::ReadPropertyNames

Reads existing string names associated with the property identifiers specified in the rgpropid[] array.

IPropertyStorage::WritePropertyNames

Assigns string names specified in the rglpwstrName array to property identifiers specified in the rgpropid array.

IPropertyStorage::DeletePropertyNames

Deletes the string names of the property identifiers specified in the rgpropid array by writing NULL to the property name.

IPropertyStorage::SetClass

Sets the CLSID field of the property set stream. In this implementation, setting the CLSID on a non-simple property set (one that can legally contain storage- or stream-valued properties, as described in IPropertySetStorage::Create) also sets the CLSID on the underlying sub-storage so that it can be obtained through a call to IStorage::Stat.

IPropertyStorage::Commit

For both simple and non-simple property sets, flushes the memory image to the disk subsystem. In addition, for non-simple transacted-mode property sets, this method performs a commit (as in IStorage::Commit) on the property set.

IPropertyStorage::Revert

For non-simple property sets only, calls the underlying storage's Revert method and re-opens the 'contents' stream. For simple property sets, returns E_OK.

IPropertyStorage::Enum

Constructs an instance of IEnumSTATPROPSTG, the methods of which can be called to enumerate the STATPROPSTG structures that provide information about each of the properties in the set. This implementation creates an array into which the entire property set is read and which can be shared when IEnumSTATPROPSTG::Clone is called.

IPropertyStorage::Stat

Fills in the fields of a STATPROPSETSTG structure, which contains information about the property set as a whole. On return, supplies a pointer to the structure. For non-simple storage sets, this implementation calls IStorage::Stat (or IStream::Stat) to get the times from the underlying storage or stream. For simple storage sets, no times are maintained.

IPropertyStorage::SetTimes

For non-simple property sets only, sets the times supported by the underlying storage. The compound file storage implementation supports all three: modification, access, and creation. This implementation of SetTimes calls the IStorage::SetElementTimes method of the underlying storage to retrieve these times.

See Also

IPropertyStorage, IStorage::SetElementTimes


IProvideClassInfo

The IProvideClassInfo interface provides a single method for accessing the type information for an object’s coclass entry in its type library.

When to Implement

Implement this interface on any object that can provide type information for its entire class, that is, the coclass entry in the type library.

When to Use

Use this interface to access the coclass type information for an object.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IProvideClassInfo Methods	Description
GetClassInfo	Returns the ITypeInfo interface for the object’s coclass type information.


IProvideClassInfo::GetClassInfo

Returns a pointer to the ITypeInfo interface for the object’s type information. The type information for an object corresponds to the object’s coclass entry in a type library.

HRESULT GetClassInfo(

ITypeInfo** ppTI	//Indirect pointer to object’s type information
);
Parameters

ppTI

[out] Indirect pointer to object’s type information. The caller is responsible for calling ITypeInfo::Release on the returned pointer if this method returns successfully.

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The type information was successfully returned.

E_POINTER

The address in ppTI is not valid. For example, it may be NULL.

Remarks

Notes to Callers

The caller is responsible for calling ITypeInfo::Release when the returned interface pointer is no longer needed.

Notes to Implementers

This method must call ITypeInfo::AddRef before returning. If the object loads the type information from a type library, the type library itself will call AddRef in creating the pointer.

Because the caller cannot specify a locale identifier (LCID) when calling this method, this method must assume the neutral language, that is, LANGID_NEUTRAL, and use this value to determine what locale-specific type information to return.

This method must be implemented; E_NOTIMPL is not an acceptable return value.


IProvideClassInfo2

The IProvideClassInfo2 interface is a simple extension to IProvideClassInfo for the purpose of making it quick and easy to retrieve an object’s outgoing interface IID for its default event set. The mechanism, the added GetGUID method, is extensible for other types of GUIDs as well.

When to Implement

An object implements this interface to provide type information for its outgoing interfaces.

When to Use

Call the method in this interface to obtain type information on an object’s outgoing interfaces.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IProvideClassInfo Method	Description
GetClassInfo	Returns the ITypeInfo interface for the object’s coclass type information.
IProvideClassInfo2 Method	Description
GetGUID	Returns the GUID for the object’s outgoing IID for its default event set.


IProvideClassInfo2::GetGUID

Returns a GUID corresponding to the specified dwGuidKind. The dwGuidKind parameter has several values defined. See GUIDKIND. Additional flags can be defined at a later time and will be recognized by an IProvideClassInfo2 implementation.

HRESULT GetGUID(

DWORD dwGuidKind,	//Desired GUID
GUID* pGUID	//Pointer to the desired GUID
);
Parameters

dwGuidKind

[in] Specifies the GUID desired on return. This parameter takes a value from the GUIDKIND enumeration.

pGUID

[out] Pointer to the caller’s variable in which to store the GUID associated with dwGuidKind.

Return Values

S_OK

The GUID was successfully returned in *pGUID.

E_POINTER

The address in pGUID is not valid (such as NULL).

E_UNEXPECTED

An unknown error occurred.

E_INVALIDARG

The dwGuidKind value does not correspond to a supported GUID kind.

Remarks

E_NOTIMPL is not a valid return code since it would be pointless to implement this interface without implementing this method.

See Also

GUIDKIND


IQuickActivate

The IQuickActivate interface allows controls and containers to avoid performance bottlenecks on loading controls. It combines the load-time or initialization-time handshaking between the control and its container into a single call.

When to Implement

Implement this interface on controls to achieve performance improvements during activation of the control.

If this interface is supported then all methods of this interface must be implemented.

When to Use

Containers call this interface on controls to achieve performance improvements in activating the control.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IQuickActivate Methods	Description
QuickActivate	Quick activates a control.
SetContentExtent	Sets the content extent of a control.
GetContentExtent	Gets the content extent of a control.


IQuickActivate::GetContentExtent

Gets the content extent of the control.

HRESULT GetContentExtent(

LPSIZEL psizel	//Pointer to size of the content extent
);
Parameters

psizel

[out] Pointer to size of the content extent.

Return Values

S_OK

The content extent was successfully returned.


IQuickActivate::QuickActivate

Quick activates a control.

HRESULT QuickActivate(

QACONTAINER* pQaContainer,	//Pointer to container information structure
QACONTROL* pQaControl	//Pointer to control information structure
);
Parameters

pQaContainer

[in] Pointer to a structure containing information about the container.

pQaControl

[out] Pointer to a structure filled in by the control to return information about the control to the container. The container calling this method must reserve memory for this structure.

Return Values

S_OK

The quick activation is proceeding and the QACONTROL structure has been completed.

E_FAIL

An unexpected error occurred. The quick activation is not completed.

Remarks

If the control does not support IQuickActivate, the container performs certain handshaking operations when it loads the control. The container calls certain interfaces on the control and the control, in turn, calls back to certain interfaces on the container’s client site. First, the container creates the control object and calls QueryInterface to query for interfaces that it needs. Then, the container calls IOleObjectSetClientSite on the control, passing a pointer to its client site. Next, the control calls QueryInterface on this site, retrieving a pointer to additional necessary interfaces.

Using the new IQuickActivate::QuickActivate method, the container passes a pointer to a QACONTAINER structure. The structure contains pointers to interfaces which are needed by the control and the values of some ambient properties that the control may need. Upon return, the control passes a pointer to a QACONTROL structure that contains pointers to its own interfaces that the container requires, and additional status information.

The IPersist*::Load and IPersist*::InitNew methods should be called after quick activation occurs. The control should establish its connections to the container’s sinks during quick activation. However, these connections are not live until IPersist*::Load or IPersist*::InitNew has been called.

See Also

QACONTROL


IQuickActivate::SetContentExtent

Sets the content extent of the control.

HRESULT SetContentExtent(

LPSIZEL psizel	//Size of the content extent
);
Parameter

psizel

[in] Size of the content extent.

Return Values

S_OK

The extent was successfully set.

E_FAIL

The object’s size is fixed and the extent cannot be set.


IRootStorage

The IRootStorage interface contains a single method that switches a storage object to a different underlying file and saves the storage object to that file. The save operation occurs even with low memory conditions and uncommitted changes to the storage object. A subsequent call to IStorage::Commit is guaranteed to not consume any additional memory.

When to Implement

Storage objects that are based on a file should implement IRootStorage in addition to the IStorage interface. For storage objects that are not file-based, this interface is not necessary.

OLE provides an implementation of a storage object, including the IRootStorage interface, as part of its compound file implementation.

When to Use

The primary use for the IRootStorage interface is to save a storage object to a file during low memory conditions. Typically, the container application calls the IRootStorage interface to switch to a new file.

If you have an IStorage pointer to a compound file object, you can call IStorage::QueryInterface with IID_IRootStorage to obtain a pointer to the IRootStorage interface.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IRootStorage Method	Description
SwitchToFile	Copy the file underlying this root storage object, then associate this storage with the copied file.
See Also

IStorage, StgCreateDocfile


IRootStorage::SwitchToFile

Copies the current file associated with the storage object to a new file. The new file is then used for the storage object and any uncommitted changes.

HRESULT SwitchToFile(

LPOLESTR pszFile	//Filename for the new file
);
Parameter

pszFile

Specifies the filename for the new file. It cannot be the name of an existing file. If NULL, this method creates a temporary file with a unique name, and you can call IStorage::Stat to retrieve the name of the temporary file.

Return Values

S_OK

The file was successfully copied.

STG_E_MEDIUMFULL

The file was not copied because of insufficient space on the storage device.

STG_E_ACCESSDENIED

The file was not copied because the caller does not have permission to access storage device.

STG_E_INVALIDPOINTER

The file was not copied because the pszFile pointer is invalid.

STG_E_FILEALREADYEXISTS

The file was not copied because the new filename (pszFile) points to an existing file.

Remarks

The IRootStorage::SwitchToFile method copies the file associated with the storage object. An OLE container calls SwitchToFile to perform a full save on a file in a low-memory situation. Typically, this is done only after a normal full save operation (i.e., save to temporary file, delete original file, rename temporary file) has failed with an E_OUTOFMEMORY error.

It is illegal to call SwitchToFile if the storage object or anything contained within it has been marshalled to another process. As a consequence, before calling SwitchToFile, the container must call the IPersistStorage::HandsOffStorage method for any element within the storage object that is loaded or running. The HandsOffStorage method forces the element to release its storage pointers and enter the hands-off storage mode. The container must also release all pointers to streams or storages that are contained in this root storage. After the full save operation is completed, the container returns the contained elements to normal storage mode.

Notes to Implementers

If you are implementing your own storage objects, the IRootStorage methods (including QueryInterface, AddRef, and Release) must not consume additional memory or file handles.

See Also

IPersistStorage::HandsOffStorage, IPersistStorage::SaveCompleted, IStorage::Commit, IStorage::Stat


IRootStorage - Compound File Implementation

OLE’s compound file implementation of IRootStorage provides a way to support saving files in low-memory or low disk-space situations. For information on how this interface behaves, see IRootStorage.

When to Use

Use the system-supplied implementation of IRootStorage only to support saving files under low memory conditions.

Remarks

It is possible to call OLE’s implementation of IRootStorage::SwitchToFile to do a normal Save As operation to

another file. Applications that do so, however, may not be compatible with future generations of OLE storage. To avoid this possibility, applications performaing a Save As operation should manually create the second docfile and invoke

IStorage::CopyTo. IRootStorage::SwitchToFile should beused only in emergency (low memory or disk space) situations.

See Also

IRootStorage; IRootStorage::SwitchToFile


IROTData

The IROTData interface is implemented by monikers to enable the Running Object Table (ROT) to compare monikers against each other.

The ROT uses the IROTData interface to test whether two monikers are equal. The ROT must do this when, for example, it checks whether a specified moniker is registered as running.

When to Implement

You must implement IROTData if you are writing your own moniker class (that is, writing your own implementation of the IMoniker interface), and if your monikers are meant to be registered in the ROT.

When to Use

You typically do not need to use this interface. This interface is used by the system’s implementation of the ROT.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IROTData Method	Description
GetComparisonData	Retrieve data to allow moniker to be compared with another.
See Also

IMoniker, IRunningObjectTable


IROTData::GetComparisonData

Retrieves data from a moniker that can be used to test the moniker for equality against another moniker.

HRESULT GetComparisonData(

PVOID *ppvData,	//Indirect pointer to a buffer that receives the comparison data
ULONG cbMax,	//Length of buffer
PULONG pcbData	//Pointer to the length of the comparison data
);
Parameters

ppvData

[out] Indirect pointer to a buffer that receives the comparison data.

cbMax

[in] Length of the buffer specified in ppvData.

pcbData

[out] Pointer to the length of the comparison data.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The comparison data was successfully returned.

Remarks

The IROTData::GetComparisonData method is primarily called by the Running Object Table (ROT). The comparison data returned by the method is tested for binary equality against the comparison data returned by another moniker. The pcbData parameter enables the ROT to locate the end of the data returned.

Notes to Implementers

The comparison data that you return must uniquely identify the moniker, while still being as short as possible. The comparison data should include information about the internal state of the moniker, as well as the moniker’s CLSID. For example, the comparison data for a file moniker would include the path name stored within the moniker, as well as the CLSID of the file moniker implementation. This makes it possible to distinguish two monikers that happen to store similar state information but are instances of different moniker classes.

The comparison data for a moniker cannot exceed 2048 bytes in length. For composite monikers, the total length of the comparison data for all of its components cannot exceed 2048 bytes; consequently, if your moniker can be a component within a composite moniker, the comparison data you return must be significantly less than 2048 bytes.

If your comparison data is longer than the value specified by the cbMax parameter, you must return an error. Note that when IROTData::GetComparisionData is called on the components of a composite moniker, the value of cbMax becomes smaller for each moniker in sequence.

See Also

IMoniker, IRunningObjectTable


IRunnableObject

The IRunnableObject interface enables a container to control the running of its embedded objects. In the case of an object implemented with a local server, calling IRunnableObject::Run launches the server’s .EXE file. In the case of an object implemented with an in-process server, calling the Run method causes the object .DLL file to transition into the running state.

When to Implement

Object handlers should implement IRunnableObject to provide their containers with a way to run them and manage their running state. DLL object applications should implement IRunnableObject to support silent updates of their objects.

When to Use

Containers call IRunnableObject to determine if an embedded object is running, to force an object to run, to lock an object into the running state, or to inform an object handler whether its object is being run as either a simple embedding or as a link source.

Methods VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IRunnableObject Methods	Description
GetRunningClass	Returns CLSID of a running object.
Run	Forces an object to run.
IsRunning	Determines if an object is running.
LockRunning	Locks an object into running state.
SetContainedObject	Indicates that an object is embedded.


IRunnableObject::GetRunningClass

Returns the CLSID of a running object.

HRESULT GetRunningClass(

LPCLSID lpClsid	//Pointer to an object’s CLSID
);
Parameter

lpClsid

[out] Pointer to the object’s class identifier.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

CLSID was returned successfully.

Remarks

If an embedded document was created by an application that is not available on the user’s computer, the document, by a call to CoTreatAsClass, may be able to display itself for editing by emulating a class that is supported on the user’s machine. In this case, the CLSID returned by a call to IRunnableObject::GetRunningClass will be that of the class being emulated, rather than the document’s native class.

See Also

CoTreatAsClass


IRunnableObject::IsRunning

Determines whether an object is currently in the running state.

BOOL IsRunning();

Return Values

TRUE

The object is in the running state.

FALSE

The object is not in the running state.

Remarks

A container application could call IRunnableObject::IsRunning when it needs to know if the server is immediately available. For example, a container’s implementation of the IOleItemContainer::GetObject method would return an error if the server is not running and the bindspeed parameter specifies BINDSPEED_IMMEDIATE.

An object handler could call IRunnableObject::IsRunning when it wants to avoid conflicts with a running server or when the running server might have more up-to-date information. For example, a handler’s implementation of IOleObject::GetExtent would delegate to the object server if it is running, because the server’s information might be more current than that in the handler’s cache.

OleIsRunning is a helper function that conveniently repackages the functionality offered by IRunnableObject::IsRunning. With the release of OLE 2.01, the implementation of OleIsRunning was changed so that it calls QueryInterface, asks for IRunnableObject, and then calls IRunnableObject::IsRunning. In other words, you can use the interface and the helper function interchangeably.

See Also

OleIsRunning


IRunnableObject::LockRunning

Locks an already running object into its running state or unlocks it from its running state.

HRESULT LockRunning(

BOOL fLock,	//Flag indicating whether object is locked
BOOL fLastUnlockCloses	//Flag indicating whether to close object
);
Parameters

fLock

[in] TRUE locks the object into its running state. FALSE unlocks the object from its running state.

fLastUnlockCloses

[in] TRUE specifies that if the connection being released is the last external lock on the object, the object should close. FALSE specifies that the object should remain open until closed by the user or another process.

Return Values

This method supports the standard return values E_FAIL, E_INVALIDARG, E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

If the value of fLock is TRUE, the object was successfully locked; if the value of fLock is FALSE, the object was successfully unlocked.

Remarks

Most implementations of IRunnableObject::LockRunning call CoLockObjectExternal.

OleLockRunning is a helper function that conveniently repackages the functionality offered by IRunnableObject::LockRunning. With the release of OLE 2.01, the implementation of OleLockRunning was changed to call QueryInterface, ask for IRunnableObject, and then call IRunnableObject::LockRunning. In other words, you can use the interface and the helper function interchangeably.

See Also

CoLockObjectExternal


IRunnableObject::Run

Runs an object.

HRESULT Run(

LPBC lpbc	//Pointer to binding context
);
Parameter

lpbc

[in] Pointer to the binding context of the run operation. May be NULL.

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The object was successfully placed in the running state.

Remarks

Containers call IRunnableObject::Run to force their objects to enter the running state. If the object is not already running, calling IRunnableObject::Run can be an expensive operation, on the order of many seconds. If the object is already running, then this method has no effect on the object.

Notes to Callers

When called on a linked object that has been converted to a new class since the link was last activated, IRunnableObject::Run may return OLE_E_CLASSDIFF. In this case, the client should call IOleLink::BindToSource.

OleRun is a helper function that conveniently repackages the functionality offered by IRunnableObject::Run. With the release of OLE 2.01, the implementation of OleRun was changed so that it calls QueryInterface, asks for IRunnableObject, and then calls IRunnableObject::Run. In other words, you can use the interface and the helper function interchangeably.

Notes to Implementers

The object should register in the running object table if it has a moniker assigned. The object should not hold any strong locks on itself; instead, it should remain in the unstable, unlocked state. The object should be locked when the first external connection is made to the object.

An embedded object must hold a lock on its embedding container while it is in the running state. The Default handler provided by OLE 2 takes care of locking the embedding container on behalf of objects implemented by an EXE object application. Objects implemented by a DLL object application must explicitly put a lock on their embedding containers, which they do by first calling IOleClientSite::Getcontainer to get a pointer to the container, then calling IOleContainer::LockContainer to actually place the lock. This lock must be released when IOleObject::Close is called.

See Also

IOleLink::BindToSource, OleRun


IRunnableObject::SetContainedObject

Notifies an object that it is embedded in an OLE container, which ensures that reference counting is done correctly for containers that support links to embedded objects.

HRESULT SetContainedObject(

BOOL fContained	//Flag indicating whether object is embedded
);
Parameter

fContained

[in] TRUE specifies that the object is contained in an OLE container. FALSE indicates that it is not.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY AND E_UNEXPECTED, as well as the following:

S_OK

Object has been marked as a contained embedding.

Remarks

The IRunnableObject::SetContainedObject method enables a container to inform an object handler that it is embedded in the container, rather than acting as a link. This call changes the container’s reference on the object from strong, the default for external connections, to weak. When the object is running visibly, this method is of little significance because the end user has a lock on the object. During a silent update of an embedded link source, however, the container should not be able to hold an object in the running state after the link has been broken. For this reason, the container’s reference to the object must be weak.

Notes to Callers

A container application must call IRunnableObject::SetContainedObject if it supports linking to embedded objects. It normally makes the call immediately after calling OleLoad or OleCreate and never calls the method again, even before it closes. Moreover, a container almost always calls this method with fContained set to TRUE. The use of this method with fContained set to FALSE is rare.

Calling IRunnableObject::SetContainedObject is optional only when you know that the embedded object will not be referenced by any client other than the container. If your container application does not support linking to embedded objects; it is preferable, but not necessary, to call IRunnableObject::SetContainedObject.

OleSetContainedObject is a helper function that conveniently repackages the functionality offered by IRunnableObject::SetContainedObject. With the release of OLE 2.01, the implementation of OleSetContainedObject was changed to call QueryInterface, ask for IRunnableObject, and then call IRunnableObject::SetContainedObject. In other words, you can use the interface and the helper function interchangeably.

See Also

OleSetContainedObject, OleNoteObjectVisible, CoLockObjectExternal


IRunningObjectTable

The IRunningObjectTable interface manages access to the Running Object Table (ROT), a globally accessible look-up table on each workstation. A workstation’s ROT keeps track of those objects that can be identified by a moniker and that are currently running on the workstation. When a client tries to bind a moniker to an object, the moniker checks the ROT to see if the object is already running; this allows the moniker to bind to the current instance instead of loading a new one.

The ROT contains entries of the form:

(pmkObjectName, pUnkObject)

The pmkObjectName element is a pointer to the moniker that identifies the running object. The pUnkObject element is a pointer to the running object itself. During the binding process, monikers consult the pmkObjectName entries in the Running Object Table to see if an object is already running.

Objects that can be named by monikers must be registered with the ROT when they are loaded and their registration must be revoked when they are no longer running.

When to Implement

You do not need to implement this interface. The system provides an implementation of the Running Object Table that is suitable for all situations.

When to Use

You typically use the ROT if you’re a moniker provider (that is, you hand out monikers identifying your objects to make them accessible to others) or if you’re writing your own moniker class (that is, implementing the IMoniker interface).

If you are a moniker provider, you register your objects with the ROT when they begin running and revoke their registrations when they are no longer running. This enables the monikers that you hand out to be bound to running objects. You should also use the ROT to record the object’s last modification time. You can get an IRunningObjectTable interface pointer to the local ROT by calling the GetRunningObjectTable function.

The most common type of moniker provider is a compound-document link source. This includes server applications that support linking to their documents (or portions of a document) and container applications that support linking to embeddings within their documents. Server applications that do not support linking can also use the ROT to cooperate with container applications that support linking to embeddings.

If you are writing your own moniker class, you use the ROT to determine whether a object is running and to retrieve the object’s last modification time. You can get an IRunningObjectTable interface pointer to the local ROT by calling the IBindCtx::GetRunningObjectTable method on the bind context for the current binding operation. Moniker implementations should always use the bind context to acquire a pointer to the ROT; this allows future implementations of IBindCtx to modify binding behavior. Note that you must also implement the IROTData interface on your moniker class in order to allow your monikers to be registered with the ROT.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IRunningObjectTable Methods	Description
Register	Registers an object with the ROT.
Revoke	Revokes an object’s registration with the ROT.
IsRunning	Checks whether an object is running.
GetObject	Returns a pointer to an object given its moniker.
NoteChangeTime	Notifies the ROT that an object has changed.
GetTimeOfLastChange	Returns the time an object was last changed.
EnumRunning	Returns an enumerator for the ROT.
See Also

IBindCtx::GetRunningObjectTable, IROTData, GetRunningObjectTable


IRunningObjectTable::EnumRunning

Creates and returns a pointer to an enumerator that can list the monikers of all the objects currently registered in the Running Object Table (ROT).

HRESULT EnumRunning(

IEnumMoniker **ppenumMoniker	//Indirect pointer to the enumerator for ROT
);
Parameter

ppenumMoniker

[out] When successful, indirect pointer to the IEnumMoniker interface on the new enumerator. In this case, the implementation calls IUnknown::AddRef on the parameter; it is the caller’s responsibility to call IUnknown::Release. If an error occurs; the implementation sets ppenumMoniker to NULL.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

An enumerator was successfully returned.

Remarks

IRunningObjectTable::EnumRunning must create and return a pointer to an IEnumMoniker interface on an enumerator object. The standard enumerator methods can then be called to enumerate the monikers currently registered in the registry. The enumerator cannot be used to enumerate monikers that are registered in the ROT after the enumerator has been created.

The EnumRunning method is intended primarily for the use by the system in implementing the Alert Object Table. Note that OLE 2 does not include an implementation of the Alert Object Table.

See Also

IEnumXXXX, IEnumMoniker


IRunningObjectTable::GetObject

Determines whether the object identified by the specified moniker is running, and if it is, retrieves a pointer to that object. This method looks for the moniker in the Running Object Table (ROT), and retrieves the pointer registered there.

HRESULT GetObject(

IMoniker *pmkObjectName,	//Pointer to the moniker on the object
IUnknown **ppunkObject	//Indirect pointer to the object
);
Parameters

pmkObjectName

[in] Pointer to the moniker to search for in the Running Object Table.

ppunkObject

[out] When successful. indirect pointer to the IUnknown interface on the running object. In this case, the implementation calls IUnknown::AddRef on the parameter; it is the caller’s responsibility to call IUnknown::Release. If the object is not running or if an error occurs, the implementation sets ppunkObject to NULL.

Return Values

S_OK

Indicates that pmkObjectName was found in the ROT and a pointer was returned.

S_FALSE

There is no entry for pmkObjectName in the ROT, or that the object it identifies is no longer running (in which case, the entry is revoked).

Remarks

This method checks the ROT for the moniker specified by pmkObjectName. If that moniker had previously been registered with a call to IRunningObjectTable::Register, this method returns the pointer that was registered at that time.

Notes to Callers

Generally, you call the IRunningObjectTable::GetObject method only if you are writing your own moniker class (that is, implementing the IMoniker interface). You typically call this method from your implementation of IMoniker::BindToObject.

However, note that not all implementations of IMoniker::BindToObject need to call this method. If you expect your moniker to have a prefix (indicated by a non-NULL pmkToLeft parameter to IMoniker::BindToObject), you should not check the ROT. The reason for this is that only complete monikers are registered with the ROT, and if your moniker has a prefix, your moniker is part of a composite and thus not complete. Instead, your moniker should request services from the object identified by the prefix (for example, the container of the object identified by your moniker).

See Also

IMoniker::BindToObject


IRunningObjectTable::GetTimeOfLastChange

Returns the time that an object was last modified. The object must have previously been registered with the Running Object Table (ROT). This method looks for the last change time recorded in the ROT.

HRESULT GetTimeOfLastChange(

IMoniker *pmkObjectName,	//Pointer to moniker on the object whose status is desired
FILETIME *pfiletime	//Pointer to structure that receives object’s last change time
);
Parameters

pmkObjectName

[in] Pointer to the IMoniker interface on the moniker to search for in the ROT.

pfiletime

[out] Pointer to a FILETIME structure that receives the object’s last change time.

Return Values

S_OK

The last change time was successfully retrieved.

S_FALSE

There is no entry for pmkObjectName in the ROT, or that the object it identifies is no longer running (in which case, the entry is revoked).

Remarks

This method returns the change time that was last reported for this object by a call to IRunningObjectTable::NoteChangeTime. If IRunningObjectTable::NoteChangeTime has not been called previously, the method returns the time that was recorded when the object was registered.

This method is provided to enable checking whether a connection between two objects (represented by one object holding a moniker that identifies the other) is up-to-date. For example, if one object is holding cached information about the other object, this method can be used to check whether the object has been modified since the cache was last updated. See IMoniker::GetTimeOfLastChange.

Notes to Callers

Generally, you call IRunningObjectTable::GetTimeOfLastChange only if you are writing your own moniker class (that is, implementing the IMoniker interface). You typically call this method from your implementation of IMoniker::GetTimeOfLastChange. However, you should do so only if the pmkToLeft parameter of IMoniker::GetTimeOfLastChange is NULL. Otherwise, you should call IMoniker::GetTimeOfLastChange on your pmkToLeft parameter instead.

See Also

IMoniker::GetTimeOfLastChange, IRunningObjectTable::NoteChangeTime


IRunningObjectTable::IsRunning

Determines whether the object identified by the specified moniker is currently running. This method looks for the moniker in the Running Object Table (ROT).

HRESULT IsRunning(

IMoniker *pmkObjectName	//Pointer to the moniker of the object whose status is desired
);
Parameter

pmkObjectName

[in] Pointer to the IMoniker interface on the moniker to search for in the Running Object Table.

Return Values

S_OK

The object identified by pmkObjectName is running.

S_FALSE

There is no entry for pmkObjectName in the ROT, or that the object it identifies is no longer running (in which case, the entry is revoked).

Remarks

This method simply indicates whether a object is running. To retrieve a pointer to a running object, use the IRunningObjectTable::GetObject method.

Notes to Callers

Generally, you call the IRunningObjectTable::IsRunning method only if you are writing your own moniker class (that is, implementing the IMoniker interface). You typically call this method from your implementation of IMoniker::IsRunning. However, you should do so only if the pmkToLeft parameter of IMoniker::IsRunning is NULL. Otherwise, you should call IMoniker::IsRunning on your pmkToLeft parameter instead.

See Also

IMoniker::IsRunning


IRunningObjectTable::NoteChangeTime

Records the time that a running object was last modified. The object must have previously been registered with the Running Object Table (ROT). This method stores the time of last change in the ROT.

HRESULT NoteChangeTime(

DWORD dwRegister,	//Value identifying registration being updated
FILETIME *pfiletime	//Pointer to structure containing object’s last change time
);
Parameters

dwRegister

[in] Value identifying the ROT entry of the changed object. This value was previously returned by IRunningObjectTable::Register.

pfiletime

[in] Pointer to a FILETIME structure containing the object’s last change time.

Return Values

This method supports the standard return value E_INVALIDARG, as well as the following:

S_OK

The change time was recorded successfully.

Remarks

The time recorded by this method can be retrieved by calling IRunningObjectTable::GetTimeOfLastChange.

This method is provided to enable a program to check whether a connection between two objects (represented by one object holding a moniker that identifies the other) is up-to-date. For example, if one object is holding cached information about the other object, this method can be used to check whether the object has been modified since the cache was last updated. See IMoniker::GetTimeOfLastChange.

Notes to Callers

If you’re a moniker provider (that is, you hand out monikers identifying your objects to make them accessible to others), you must call the IRunningObjectTable::NoteChangeTime method whenever your objects are modified. You must have previously called IRunningObjectTable::Register and stored the identifier returned by that method; you use that identifier when calling IRunningObjectTable::NoteChangeTime.

The most common type of moniker provider is a compound-document link source. This includes server applications that support linking to their documents (or portions of a document) and container applications that support linking to embeddings within their documents. Server applications that do not support linking can also use the ROT to cooperate with container applications that support linking to embeddings.

When an object is first registered in the ROT, the ROT records its last change time as the value returned by calling IMoniker::GetTimeOfLastChange on the moniker being registered.

See Also

IRunningObjectTable::GetTimeOfLastChange, IMoniker::GetTimeOfLastChange


IRunningObjectTable::Register

Registers an object and its identifying moniker in the Running Object Table (ROT).

HRESULT Register(

DWORD grfFlags,	//Specifies a weak or a strong reference
IUnknown *punkObject,	//Pointer to the object being registered
IMoniker *pmkObjectName,	//Pointer to the moniker of the object being registered
DWORD *pdwRegister	//Pointer to the value identifying the registration
);
Parameters

grfFlags

[in] Specifies whether the ROT’s reference to punkObject is weak or strong. This value must be either zero, indicating a weak reference that does not call IUnknown::AddRef; or ROTFLAGS_REGISTRATIONKEEPSALIVE, indicating a strong reference that calls IUnknown::AddRef and can keep the object running. If a strong reference is registered, a strong reference is released when the object’s registration is revoked. Most callers specify zero, indicating a weak reference.

punkObject

[in] Pointer to the object that is being registered as running.

pmkObjectName

[in] Pointer to the moniker that identifies punkObject.

pdwRegister

[out] Pointer to a 32-bit value that can be used to identify this ROT entry in subsequent calls to IRunningObjectTable::Revoke or IRunningObjectTable::NoteChangeTime. The caller cannot specify NULL for this parameter. If an error occurs, *pdwRegister is set to zero.

Return Values

This method supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

S_OK

The object was successfully registered.

MK_S_MONIKERALREADYREGISTERED

The moniker/object pair was successfully registered, but that another object (possibly the same object) has already been registered with the same moniker.

Remarks

This method registers a pointer to an object under a moniker that identifies the object. The moniker is used as the key when the table is searched with IRunningObjectTable::GetObject.

Registering a second object with the same moniker, or re-registering the same object with the same moniker, creates a second entry in the ROT. In this case, IRunningObjectTable::Register returns MK_S_MONIKERALREADYREGISTERED. Each call to IRunningObjectTable::Register must be matched by a call to IRunningObjectTable::Revoke because even duplicate entries have different pdwRegister identifiers. A problem with duplicate registrations is that there is no way to determine which object will be returned if the moniker is specified in a subsequent call to IRunningObjectTable::IsRunning.

Notes to Callers

If you’re a moniker provider (that is, you hand out monikers identifying your objects to make them accessible to others), you must call the IRunningObjectTable::Register method to register your objects when they begin running. You must also call this method if you rename your objects while they are loaded.

The most common type of moniker provider is a compound-document link source. This includes server applications that support linking to their documents (or portions of a document) and container applications that support linking to embeddings within their documents. Server applications that do not support linking can also use the ROT to cooperate with container applications that support linking to embeddings.

If you’re writing a server application, you should register an object with the ROT when it begins running, typically in your implementation of IOleObject::DoVerb. The object must be registered under its full moniker, which requires getting the moniker of its container document using IOleClientSite::GetMoniker. You should also revoke and re-register the object in your implementation of IOleObject::SetMoniker, which is called if the container document is renamed.

If you’re writing a container application that supports linking to embeddings, you should register your document with the ROT when it is loaded. If your document is renamed, you should revoke and re-register it with the ROT and call IOleObject::SetMoniker for any embedded objects in the document to give them an opportunity to re-register themselves.

You must cache the identifier returned in pdwRegister, and use it in a call to IRunningObjectTable::Revoke to revoke the registration when the object is no longer running or when its moniker changes. This revocation is important because there is no way for the system to automatically remove entries from the ROT.

The system’s implementation of IRunningObjectTable::Register calls IMoniker::Reduce on the pmkObjectName parameter to ensure that the moniker is fully reduced before registration. If a object is known by more than one fully reduced moniker, then it should be registered under all such monikers.

See Also

IMoniker::Reduce, IOleClientSite::GetMoniker, IOleObject::SetMoniker, IRunningObjectTable::IsRunning, IRunningObjectTable::Revoke


IRunningObjectTable::Revoke

Removes from the Running Object Table (ROT) an entry that was previously registered by a call to IRunningObjectTable::Register.

HRESULT Revoke(

DWORD dwRegister	//Value identifying registration to be revoked
);
Parameter

dwRegister

[in] Value identifying the ROT entry to revoke. This value was previously returned by IRunningObjectTable::Register.

Return Values

This method supports the standard return value E_INVALIDARG, as well as the following:

S_OK

The object’s registration was successfully revoked.

Remarks

This method undoes the effect of a call to IRunningObjectTable::Register, removing both the moniker and the pointer to the object identified by that moniker.

Notes to Callers

If you’re a moniker provider (that is, you hand out monikers identifying your objects to make them accessible to others), you must call the IRunningObjectTable::Revoke method to revoke the registration of your objects when they stop running. You must have previously called IRunningObjectTable::Register and stored the identifier returned by that method; you use that identifier when calling IRunningObjectTable::Revoke.

The most common type of moniker provider is a compound-document link source. This includes server applications that support linking to their documents (or portions of a document) and container applications that support linking to embeddings within their documents. Server applications that do not support linking can also use the ROT to cooperate with container applications that support linking to embeddings.

If you’re writing a container application, you must revoke a document’s registration when the document is closed. You must also revoke a document’s registration before re-registering it when it is renamed.

If you’re writing a server application, you must revoke an object’s registration when the object is closed. You must also revoke an object’s registration before re-registering it when its container document is renamed (see IOleObject::SetMoniker).

See Also

IOleObject::SetMoniker, IRunningObjectTable::Register


IServerSecurity

Used by a server to help identify the client and to manage impersonation of the client. IServerSecurity:QueryBlanket and IServerSecurity::ImpersonateClient may only be called before the ORPC call completes. The interface pointer must be released when it is no longer needed.

When a client calls a server, the server can call CoGetCallContext until the server sends the reply back to the client.  The pointer to the instance of IServerSecurity returned by CoGetCallContext is automaticly deleted when the server sends the reply back to the client.

When to Implement

The stub managment code in the system provides an implementation of IServerSecurity for objects by default as part of each incoming call, so typically you would not implement this interface.

You may choose to implement IServerSecurity on the custom stubs of objects that support custom marshaling to maintain a consistent programming model for their objects.

When to Use

The methods of the IServerSecurity interface are called by the server/object to examine or alter the security level of the connection between the caller and this particular object. Its most common use is for impersonation (IServerSecurity::ImpersonateClient and ::RevertToSelf), where the server impersonates the client to test the privilege level of the calling client with an AccessCheck call. The information obtained through IServerSecurity also allows an object to implement its own security framework, perhaps not based on the Access Control Lists (ACLs) that impersonation is geared toward. A different implementation could base its security framework on the client name or other information available through a call to the QueryBlanket method.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IServerSecurity Methods	Description
QueryBlanket	Called by the server to find out about the client that invoked one of its methods.
ImpersonateClient	Allows a server to impersonate a client for the duration of a call.
RevertToSelf	Restores the authentication information on a thread to the process’s identity.
IsImpersonating	Indicates whether  the server is currently impersonating the client.
See Also

Security in COM


IServerSecurity::ImpersonateClient

Allows a server to impersonate a client for the duration of a call.

HRESULT ImpersonateClient()

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

Success.

Remarks

IServerSecurity::ImpersonateClient allows a server to impersonate a client for the duration of a call. What the server may do depends on the impersonation level, specified through one of the RPC_C_IMP_LEVEL_xxx constants. The server may impersonate the client on any secure call at identify, impersonate, or delegate level. At identify level, the server may only find out the client name and perform ACL checks; it may not access system objects as the client. At delegate level, the server may make off-machine calls while impersonating the client. The impersonation information only lasts until the end of the current method call. At that time, IServerSecurity::RevertToSelf will automatically be called if necessary.

Traditionally, impersonation information is not nested − the last call to any Win32 impersonation mechanism overrides any previous impersonation. However, in the apartment model, impersonation is maintained during nested calls. Thus if the server A receives a call from B, impersonates, calls C, receives a call from D, impersonates, reverts, and receives the reply from C, the impersonation will be set back to B, not A.

Distributed COM currently does not support dynamic impersonation. The only way to change the client token associated with remote OLE calls is to use IClientSecurity::SetBlanket on the proxy being called. Calling IServerSecurity::ImpersonateClient to impersonate your client and then making a remote call to another server will not affect the token the second server sees when it impersonates on your call.

See Also

CoImpersonateClient


IServerSecurity::IsImpersonating

Indicates whether IServerSecurity::ImpersonateClient has been called without a matching call to IServerSecurity::RevertToSelf.

BOOL IsImpersonating()

Return Values

TRUE

This thread has called IServerSecurity::ImpersonateClient and is currently impersonating the client of this call.

FALSE

This thread is not currently impersonating the client of this call.

See Also

IServerSecurity::RevertToSelf.


IServerSecurity::QueryBlanket

Called by the server to find out about the client that invoked one of its methods.

HRESULT QueryBlanket(

DWORD*  pAuthnSvc,	//Pointer to the current authentication service
DWORD*  pAuthzSvc,	//Pointer to the current authorization service
OLECHAR **  pServerPrincNam,	//Pointer to the current principal name
DWORD * pAuthnLevel,	//Pointer to the current authentication level
DWORD * pImpLevel,	//Must be NULL
RPC_AUTHZ_HANDLE *  pPrivs,	//Pointer to string identifying client
DWORD **  pCapabilities	//Pointer to flags indicating further capabilities of the proxy
);
Parameter

pAuthnSvc

[out] Pointer to the current authentication service. This will be a single value taken from the list of RPC_C_AUTHN_xxx constants. May be NULL, in which case the current authentication service is not returned.

pAuthzSvc

[out] Pointer to the current authorization service. This will be a single value taken from the list of RPC_C_AUTHZ_xxx constants. May be NULL, in which case the current authorization service is not returned.

pServerPrincName

[out] Pointer to the current principal name. The string will be allocated by the callee using CoTaskMemAlloc, and must be freed by the caller using CoTaskMemFree when they are done with it. May be NULL, in which case the principal name is not returned.

pAuthnLevel

[out] Pointer to the current authentication level. This will be a single value taken from the list of RPC_C_AUTHN_LEVEL_xxx constants. May be NULL, in which case the current authorization level is not returned.

pImpLevel

[out] Must be NULL; the current authentication level is not supplied.

pPrivs

[out] Pointer to a string identifying the client.  For NTLMSSP the string is of the form domain\user. This is not a copy, and so should not be modified or freed, and is not valid after the ORPC call completes.

pCapabilities

[out] Pointer to return flags indicating further capabilities of the call. Currently, no flags are defined for this parameter and it will only return EOAC_NONE. May be NULL, in which case the flags indicating further capabilities are not returned.

Return Values

This method supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

S_OK

Success.

Remarks

IServerSecurity::QueryBlanket is used by the server to find out about the client that invoked one of its methods. To get a pointer to IServerSecurity for the current call on the current thread, call CoGetCallContext, specifying IID_IServerSecurity. This interface pointer may only be used in the same apartment as the call for the duration of the call.

See Also

CoGetCallContext


IServerSecurity::RevertToSelf

Restores the authentication information on a thread to the process’s identity.

HRESULT RevertToSelf()

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK

Success.

Remarks

IServerSecurity::RevertToSelf restores the authentication information and reverts an impersonation on a thread to the process’s identity. This method will only revert impersonation changes made by IServerSecurity::ImpersonateClient. If the thread token is modified by other means (through the SetThreadToken or RpcImpersonateClient Win32 functions) the result of this function is undefined.

In the apartment model, CoRevertToSelf (IServerSecurity::RevertToSelf) affects only the current method invocation. If there are nested method invocations, they each may have their own impersonation and COM will correctly restore the impersonation before returning to them (regardless of whether or not CoRevertToSelf/IServerSecurity::RevertToSelf was called).

See Also

CoRevertToSelf


IServiceProvider [New - Windows NT]
IServiceProvider

[New - Windows NT]

The IServiceProvider interface locates a service specified by its GUID and returns the interface pointer for the requested interface on the service.

When to Implement

An object that provides services should implement the IServiceProvider interface as a general way to supply its clients with interface pointers to the interfaces on the service.

A service is often provided through a separate object from the client site. For example, the service can be provided through a separate control or some other object that the client can communicate with.

Usually, the client communicates through its client site object in the container. The container calls IOleObject::SetClientSite to provide a pointer to the IOleClientSite interface for the embedded object’s client site. Then, the client must call methods in the IOleClientSite interface to find out about services that its container supports. Thus, the client site must provide a way for the client to access the service when necessary, even if the service is provided through a separate object.

For example, an in-place object calls IOleInPlaceSite::GetWindowContext to obtain interface pointers for the document object that contains the site and for the frame object that contains the document. Both of these interface pointers are on objects separate from the site object, so the client cannot call IOleInPlaceSite::QueryInterface to obtain these interface pointers.

The IServiceProvider interface is a general way to provide interface pointers for services, so that the site object need not implement ad hoc solutions as the need arises.

When to Use

This interface itself has only one method, IServiceProvider::QueryService. The caller specifies a GUID for the service and the IID of the requested interface. The interface pointer is returned in a caller-supplied variable.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IServiceProvider Methods	Description
QueryService	Returns an interface pointer to the requested interface on a service.
See Also


IServiceProvider::QueryService

Creates or accesses the specified service and returns an interface pointer to the specified interface for the service.

HRESULT QueryService(

REFGUID guidService,	//Unique identifier for the requested service
REFIID riid,	//Unique identifier for the requested interface
void** ppv	//Indirect pointer to the interface on the service
);
Parameter

guidService

[in] Unique identifier for the requestedservice.

riid

[in] Unique identifier for the requested interface on the service.

ppv

[out] Indirect pointer to the interface on the service.

Return Values

S_OK

The service was successfully created or retrieved.

E_OUTOFMEMORY

There is not enough memory to create the service.

E_UNEXPECTED

An unknown error occurred.

E_NOINTERFACE

The service exists but the requested interface is not provided by the service.

SVC_E_UNKNOWNSERVICE

The service identified with guidService is not recognized.

Note to Callers

The caller is responsible for releasing the interface pointer when it is no longer needed.

Note to Implementers

Because there is only one method in this interface, E_NOTIMPL is not a valid return code.


ISimpleFrameSite

The ISimpleFrameSite interface supports simple frame controls that act as simple containers for other nested controls. Some controls merely contain other controls. In such cases, the simple control container, called a simple frame, doesn’t have to implement all container requirements. It can delegate most of the interface calls from its contained controls to the outer container that manages the simple frame. To support what are called simple frame controls, a container implements this interface as well as other site interfaces such as IOleControlSite.

An example of a simple frame control is a group box that only needs to capture a few keystrokes for its contained controls to implement the correct tab or arrow key behavior, but does not want to handle every other message. Through the two methods of this interface, the simple frame control passes messages to its control site both before and after its own processing. If that site is itself a simple frame, it can continue to pass messages up the chain.

When to Implement

Implement this interface on a control object to support nested controls without requiring the control to itself be a full container.

When to Use

Use this interface to pass messages to a container for processing.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
ISimpleFrameSite Methods	Description
PreMessageFilter	Sends the simple frame site a message that is received by a control’s own window before the control itself does any processing.
PostMessageFilter	Sends the simple frame site a message that is received by a control’s own window after the control does its own processing.
See Also

IOleControl, IOleControlSite


ISimpleFrameSite::PostMessageFilter

Sends the simple frame site a message that is received by a control’s own window after both ISimpleFrameSite::PreMessageFilter and the control have had a chance to process the message.

HRESULT PostMessageFilter(

HWND hWnd ,	//Handle of window receiving message
UINT msg ,	//Received message
WPARAM wp ,	//WPARAM of message
LPARAM lp ,	//LPARAM of message
LRESULT* plResult ,	//Pointer to variable to receive result
DWORD dwCookie	//Token returned by PreMessageFilter
);
Parameters

hWnd

[in] Handle of the control window receiving the message.

msg

[in] Message received by the simple frame site.

wp

[in] The WPARAM of the message.

lp

[in] The LPARAM of the message.

plResult

[out] Pointer to the variable that receives the result of the message processing.

dwCookie

[in] The DWORD value that was returned by ISimpleFrameSite::PreMessageFilter through its pdwCookie parameter.

Return Values

S_OK

The site processed the message.

S_FALSE

The site did not process the message.

E_NOTIMPL

The site does not filter any messages.

See Also

ISimpleFrameSite:PreMessageFilter


ISimpleFrameSite::PreMessageFilter

Provides a site with the opportunity to process a message that is received by a control’s own window before the control itself does any processing.

HRESULT PreMessageFilter(

HWND hWnd ,	//Handle of window receiving message
UINT msg ,	//Received message
WPARAM wp ,	//WPARAM of message
LPARAM lp ,	//LPARAM of message
LRESULT* plResult ,	//Pointer to variable to receive result of message processing
DWORD* pdwCookie	//Pointer to a variable used later
);
Parameters

hWnd

[in] Handle of the control window receiving the message.

msg

[in] Message received by the simple frame site.

wp

[in] The WPARAM of the message.

lp

[in] The LPARAM of the message.

plResult

[out] Pointer to the address of the result variable to receive the result of the message processing.

pdwCookie

[out] Pointer to the DWORD variable that will be passed to PostMessageFilter if it is called later. This parameter should only contain allocated data if this method returns S_OK so it will also receive a call to PostMessageFilter which can free the allocation. The caller is not in any way responsible for anything returned in this parameter.

Return Values

S_OK

The simple frame site will not use the message in this filter so more processing can take place.

S_FALSE

The site has processed the message and no further processing should occur.

E_NOTIMPL

The site does not do any message filtering, indicating that PostMessageFilter need not be called later.

E_POINTER

The addresses in plResultor pdwCookie are not valid.

Remarks

Successful return values indicate whether the site wishes to allow further processing. S_OK indicates further processing, whereas S_FALSE means do not process further. S_OK also indicates that the control must later call ISimpleFrameSite::PostMessageFilter.

See Also

ISimpleFrameSite::PostMessageFilter


ISpecifyPropertyPages

The ISpecifyPropertyPage interface indicates that an object supports property pages. OLE property pages enable an object to display its properties in a tabbed dialog box known as a property sheet. An end user can then view and change the object’s properties. An object can display its property pages independent of its client, or the client can manage the display of property pages from a number of contained objects in a single property sheet. Property pages also provide a means for notifying a client of changes in an object’s properties.

A property page object manages a particular page within a property sheet. A property page implements at least IPropertyPage and can optionally implement IPropertyPage2 if selection of a specific property is supported.

An object specifies its support for property pages by implementing ISpecifyPropertyPages. Through this interface the caller can obtain a list of CLSIDs identifying the specific property pages that the object supports. If the object specifies a property page CLSID, the object must be able to receive property changes from the property page.

When to Implement

Implement this interface on an object to indicate support for a property sheet and at least one property page.

When to Use

Use this interface to obtain a list of property page CLSIDs that this object supports. The CLSID list can be later passed to OleCreatePropertyFrame or OleCreatePropertyFrameIndirect to invoke a property sheet. If a caller wants to display a property sheet for multiple objects, it must first obtain the CLSID list for each object, then create a list containing only the intersection of the set of CLSID in each separate list. In other words, whoever invokes a property sheet for any number of objects must guarantee that each property page CLSID was specified by all objects for which the sheet is being displayed. This avoids the possibility that a property page is displayed for an object that doesn’t understand that page; if this were allowed, it would result in problems when the page sent unknown and unexpected information to an object.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
ISpecifyPropertyPages Methods	Description
GetPages	Fills an array of CLSIDs for each property page that can be displayed in this object’s property sheet.
See Also

IPerPropertyBrowsing, IPropertyPage, IPropertyPage2, IPropertyPageSite, OleCreatePropertyFrame, OleCreatePropertyFrameIndirect


ISpecifyPropertyPages::GetPages

Fills a counted array of GUID values where each GUID specifies the CLSID of each property page that can be displayed in the property sheet for this object.

HRESULT GetPages(

CAUUID *pPages	//Pointer to structure
);
Parameters

pPages

[out] Pointer to a caller-allocated CAUUID structure that must be initialized and filled before returning. The pElems field in the CAUUID structure is allocated by the callee with CoTaskMemAlloc and freed by the caller with CoTaskMemFree.

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The array was filled successfully.

E_POINTER

The address in pPages is not valid. For example, it may be NULL.

Remarks

The CAUUID structure is caller-allocated, but is not initialized by the caller. The ISpecifyPropertyPages::GetPages method fills the cElements field in the CAUUID structure. This method also allocates memory for the array pointed to by the pElems field in CAUUID using CoTaskMemAlloc. Then, it fills the newly allocated array. After this method returns successfully, the structure contains a counted array of UUIDs, each UUID specifying a property page CLSID.

Notes to Callers

The caller must release the memory pointed to by the pElems field of CAUUID, using CoTaskMemFree when it is no longer needed.

Notes to Implementers

E_NOTIMPL is not allowed as a return value since an object with no property pages should not expose the ISpecifyPropertyPages interface at all.

See Also

CAUUID, CoTaskMemAlloc, CoTaskMemFree, OleCreatePropertyFrame, OleCreatePropertyFrameIndirect


IStdMarshalInfo

The IStdMarshalInfo interface returns the CLSID identifying the handler to be used in the destination process during standard marshaling.

An object that uses OLE’s default implementation of IMarshal does not provide its own proxy but, by implementing IStdMarshalInfo, can nevertheless specify a handler to be loaded in the client process. Such a handler would typically handle certain requests in-process and use OLE’s default marshaling to delegate others back to the original object.

To create an instance of an object in some client process, COM must first determine whether the object uses default marshaling or its own implementation. If the object uses default marshaling, COM then queries the object to determine whether it uses a special handler or, simply, OLE’s default proxy. To get the CLSID of the handler to be loaded, COM queries the object for the IStdMarshalInfo interface and then the IPersist interface. If neither interface is supported, a standard handler is used.

When to Implement

If you are writing a server application that supports class emulation (that is, if your server can manipulate objects of another type in response to the Activate As option in the Convert dialog box), you must implement the IStdMarshalInfo interface in order to return the CLSID of the handler to be used for the object.

Note that your handler must aggregate the default handler.

When to Use

You typically don’t call this interface yourself. COM queries for this interface when performing standard marshaling.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IStdMarshalInfo Method	Description
GetClassForHandler	Obtains the class identifier of the object handler in the destination process.
See Also

IMarshal


IStdMarshalInfo::GetClassForHandler

Retrieves the CLSID of the object handler to be used in the destination process during standard marshaling.

HRESULT GetClassForHandler(

DWORD dwDestContext,	//Destination process
void * pvDestContext,	//Reserved
CLSID * pClsid	//Pointer to the CLSID
);
Parameters

dwDestContext

[in] Destination context, that is, the process in which the unmarshaling will be done. The legal values for dwDestContext are taken from the enumeration MSHCTX. For information on the MSHCTX enumeration, see the “Data Structures” section.

pvDestContext

[in] Reserved for future use; must be NULL.

pClsid

[out] Pointer to the handler’s CLSID.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The CLSID was retrieved successfully.

Remarks

Notes to Implementers

Your implementation of IStdMarshalInfo::GetClassForHandler must return your own CLSID. This allows an object created by a different server to behave as one your server created.


IStorage

The IStorage interface supports the creation and management of structured storage objects. Structured storage allows hierarchical storage of information within a single file, and is often referred to as “a file system within a file”. Elements of a structured storage object are storages and streams. Storages are analogous to directories, and streams are analogous to files. Within a structured storage there will be a primary storage object that may contain substorages, possibly nested, and streams. Storages provide the structure of the object, and streams contain the data, which is manipulated through the IStream interface.

The IStorage interface provides methods for creating and managing the root storage object, child storage objects, and stream objects. These methods can create, open, enumerate, move, copy, rename, or delete the elements in the storage object.

An application must release its IStorage pointers when it is done with the storage object to deallocate memory used. There are also methods for changing the date and time of an element.

There are a number of different modes in which a storage object and its elements can be opened, determined by setting values from the STGM enumeration. One aspect of this is how changes are committed. You can set direct mode, in which in which changes to an object are immediately written to it, or transacted mode, in which changes are written to a buffer until explicitly committed. The IStorage interface provides methods for committing changes and reverting to the last-committed version. Other storage modes set, for example, a stream can be opened in read only mode or read/write mode. For more information, refer to the STGM enumeration.

Other methods provide a means to gain access to information about a storage object and its elements through the STATSTG structure.

When to Implement

Generally, you would not implement this interface unless you were defining a new storage scheme for your system. OLE provides a compound file implementation of the IStorage interface that supports transacted access. OLE provides a set of helper APIs to facilitate using the compound file implementation of storage objects. Refer to IStorage - Compound File Implementation.

When to Use

Call the methods of IStorage to manage substorages or streams within the current storage. This management includes creating, opening, or destroying sub-storages or streams, as well as managing aspects such as time stamps, names, etc. You can also commit changes or revert to previous version for storages opened in transacted mode. The methods of IStorage do not include means to read and write data—this is reserved for IStream, which manages the actual data. While the IStorage and IStream interfaces are used to manipulate the storage object and its elements, the IPersistStorage interface contains methods that are called to serialize the storage object and its elements to a disk file.

Methods VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IStorage Methods	Description
CreateStream	Creates and opens a stream object with the specified name contained in this storage object.
OpenStream	Opens an existing stream object within this storage object using the specified access permissions in grfMode.
CreateStorage	Creates and opens a new storage object within this storage object.
OpenStorage	Opens an existing storage object with the specified name according to the specified access mode.
CopyTo	Copies the entire contents of this open storage object into another storage object. The layout of the destination storage object may differ.
MoveElementTo	Copies or moves a substorage or stream from this storage object to another storage object.
Commit	Reflects changes for a transacted storage object to the parent level.
Revert	Discards all changes that have been made to to the storage object since the last commit operation.
EnumElements	Returns an enumerator object that can be used to enumerate the storage and stream objects contained within this storage object.
DestroyElement	Removes the specified storage or stream from this storage object.
RenameElement	Renames the specified storage or stream in this storage object.
SetElementTimes	Sets the modification, access, and creation times of the indicated storage element, if supported by the underlying file system.
SetClass	Assigns the specified CLSID to this storage object.
SetStateBits	Stores up to 32 bits of state information in this storage object.
Stat	Returns the STATSTG structure for this open storage object.


IStorage::Commit

Ensures that any changes made to a storage object open in transacted mode are reflected in the parent storage; for a root storage, reflects the changes in the actual device, for example, a file on disk. For a root storage object opened in direct mode, this method has no effect except to flush all memory buffers to the disk. For non-root storage objects in direct mode, this method has no effect.

HRESULT Commit(

DWORD grfCommitFlags	//Specifies how changes are to be committed
);
Parameter

grfCommitFlags

[in] Controls how the changes are committed to the storage object. See the STGC enumeration for a definition of these values.

Return Values

S_OK

Changes to the storage object were successfully committed to the parent level.

E_PENDING

Asynchronous Storage only: Part or all of the data to be committed is currently unavailable. For more information, see IFillLockBytes and Asynchronous Storage.

STG_E_INVALIDFLAG

The value for the grfCommitFlags parameter is not valid.

STG_E_INVALIDPARAMETER

One of the parameters was not valid.

STG_E_NOTCURRENT

Another open instance of the storage object has committed changes. Thus, the current commit operation may overwrite previous changes.

STG_E_MEDIUMFULL

No space left on device to commit.

STG_E_TOOMANYOPENFILES

The commit operation could not be completed because there are too many open files.

STG_E_REVERTED

The storage object has been invalidated by a revert operation above it in the transaction tree.

Remarks

IStorage::Commit makes permanent changes to a storage object that is in transacted mode, in which changes are accumulated in a buffer, and not reflected in the storage object until there is a call to this method. The alternative is to open an object in direct mode, in which changes are immediately reflected in the storage object and so does not require a commit operation. Calling this method on a storage opened in direct mode has no effect, unless it is a root storage, in which case it ensures that changes in memory buffers are written to the underlying storage device.

The commit operation publishes the current changes in this storage object and its children to the next level up in the storage hierarchy. To undo current changes before committing them, call IStorage::Revert to roll back to the last-committed version.

Calling IStorage::Commit has no effect on currently-opened nested elements of this storage object. They are still valid and can be used. However, the IStorage::Commit method does not automatically commit changes to these nested elements. The commit operation publishes only known changes to the next higher level of the storage hierarchy. Thus, transactions to nested levels must be committed to this storage object before they can be committed to higher levels.

In commit operations, you need to take steps to ensure that data is protected during the commit process:

•	When committing changes to root storage objects, the caller must check the return value to determine whether the operation has been completed successfully, and if not, that the old committed contents of the IStorage are still intact and can be restored.

•	If this storage object was opened with some of its items excluded, then the caller is responsible for rewriting them before calling commit. Write mode is required on the storage opening for the commit to succeed.

•	Unless prohibiting multiple simultaneous writers on the same storage object, an application calling this method should specify at least STGC_ONLYIFCURRENT in the grfCommitFlags parameter to prevent the changes made by one writer from inadvertently overwriting the changes made by another.

See Also

IStorage - Compound File Implementation, STGC, IStorage::Revert


IStorage::CopyTo

Copies the entire contents of an open storage object to another storage object.

HRESULT CopyTo(

DWORD ciidExclude,	//Number of elements in rgiidExclude
IID const * rgiidExclude,	//Array of interface identifiers (IIDs)
SNB snbExclude,	//Points to a block of stream names in the storage object
IStorage * pstgDest	//Points to destination storage object
);
Parameters

ciidExclude

[in] The number of elements in the array pointed to by rgiidExclude. If rgiidExclude is NULL, then ciidExclude is ignored.

rgiidExclude

[in] An array of interface identifiers that either the caller knows about and does not want to be copied or  that the storage object does not support but whose state the caller will later explicitly copy. The array can include IStorage, indicating that only stream objects are to be copied, and IStream, indicating that only storage objects are to be copied. An array length of zero indicates that only the state exposed by the IStorage object is to be copied; all other interfaces on the object are to be ignored. Passing NULL indicates that all interfaces on the object are to be copied.

snbExclude

[in] A string name block (refer to SNB) that specifies a block of storage or stream objects that are not to be copied to the destination. These elements are not created at the destination. If IID_IStorage is in the rgiidExclude array, this parameter is ignored. This parameter may be NULL.

pstgDest

[in] Points to the open storage object into which this storage object is to be copied. The destination storage object can be a different implementation of the IStorage interface from the source storage object. Thus, IStorage::CopyTo can only use publicly available methods of the destination storage object. If pstgDest is open in transacted mode, it can be reverted by calling its IStorage::Revert method.

Return Values

S_OK

The storage object was successfully copied.

E_PENDING

Asynchronous Storage only: Part or all of the data to be copied is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_ACCESSDENIED

The destination storage object is a child of the source storage object.

STG_E_INSUFFICIENTMEMORY

The copy was not completed due to a lack of memory.

STG_E_INVALIDPOINTER

The pointer specified for the storage object was invalid.

STG_E_INVALIDPARAMETER

One of the parameters was invalid.

STG_E_TOOMANYOPENFILES

The copy was not completed because there are too many open files.

STG_E_REVERTED

The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_MEDIUMFULL

The copy was not completed because the storage medium is full.

Remarks

This method merges elements contained in the source storage object with those already present in the destination. The layout of the destination storage object may differ from the source storage object.

The copy process is recursive, invoking IStorage::CopyTo and IStream::CopyTo on the elements nested inside the source.

When copying a stream on top of an existing stream with the same name, the existing stream is first removed and then replaced with the source stream.  When copying a storage on top of an existing storage with the same name, the existing storage is not removed. As a result,, after the copy operation, the destination IStorage contains older elements, unless they were replaced by newer ones with the same names.

A storage object may expose interfaces other than IStorage, including IRootStorage, IPropertyStorage, or IPropertySetStorage. The  rgiidExclude parameter provides a way to exclude any or all of these additional interfaces from the copy operation.

A caller with a newer or more efficient copy of an existing substorage or stream object may want to exclude the current versions of these objects from the copy operation. The snbExclude and rgiidExclude parameters provide two different ways of excluding a storage objects existing storages or streams.

Note to Callers

The most common way to use this method is to copy everything possible from the source to the destination, as in most Full Save and SaveAs operations. The following example illustrates this call:

pstg->CopyTo(0, Null, Null, pstgDest)

See Also

IStorage - Compound File Implementation, IStorage::MoveElementTo, IStorage::Revert


IStorage::CreateStorage

Creates and opens a new storage object nested within this storage object.

HRESULT CreateStorage(

const WCHAR * pwcsName,	//Points to the name of the new storage object
DWORD grfMode,	//Access mode for the new storage object
DWORD reserved1,	//Reserved; must be zero
DWORD reserved2,	//Reserved; must be zero
IStorage ** ppstg	//Points to new storage object
);
Parameters

pwcsName

[in] Points to a wide character string that contains the name of the newly created storage object. This name can be used later to reopen the storage object.

grfMode

[in] Specifies the access mode to use when opening the newly created storage object. See the STGM enumeration values for descriptions of the possible values.

reserved1

[in] Reserved for future use; must be zero.

reserved2

[in] Reserved for future use; must be zero.

ppstg

[out] When successful, points to the location of the IStorage pointer to the newly-created storage object. This parameter is set to NULL if an error occurs.

Return Values

S_OK

The storage object was created successfully.

E_PENDING

Asynchronous Storage only: Part or all of the necessary data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_ACCESSDENIED

Insufficient permissions to create storage object.

STG_E_FILEALREADYEXISTS

The name specified for the storage object already exists in the storage object and the grfmode flag includes the flag STGM_FAILIFTHERE.

STG_E_INSUFFICIENTMEMORY

The storage object was not created due to a lack of memory.

STG_E_INVALIDFLAG

The value specified for the grfMode flag is not a valid STGM enumeration value.

STG_E_INVALIDFUNCTION

The specified combination of grfMode flags is not supported.

STG_E_INVALIDNAME

Invalid value for pwcsName.

STG_E_INVALIDPOINTER

The pointer specified for the storage object was invalid.

STG_E_INVALIDPARAMETER

One of the parameters was invalid.

STG_E_REVERTED

The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_TOOMANYOPENFILES

The storage object was not created because there are too many open files.

STG_S_CONVERTED

The existing stream with the specified name was replaced with a new storage object containing a single stream called CONTENTS. The new storage object will be added.

Remarks

If a storage with the name specified in the pwcsName parameter already exists within the parent storage object, and the grfMode parameter includes the STGM_CREATE flag, the existing storage is replaced by the new one. If the grfMode parameter includes the STGM_CONVERT flag, the existing element is converted to a stream object named CONTENTS and the new storage object is created containing the CONTENTS stream object. The destruction of the old element and the creation of the new storage object are both subject to the transaction mode on the parent storage object.

If a storage object with the same name already exists and grfMode is set to STGM_FAILIFTHERE, this method fails with the return value STG_E_FILEALREADYEXISTS.

See Also

IStorage - Compound File Implementation, IStorage::OpenStorage


IStorage::CreateStream

Creates and opens a stream object with the specified name contained in this storage object. All elements within a storage object — both streams and other storage objects — are kept in the same name space.

HRESULT CreateStream(

const WCHAR * pwcsName,	//Points to the name of the new stream
DWORD grfMode,	//Access mode for the new stream
DWORD reserved1,	//Reserved; must be zero
DWORD reserved2,	//Reserved; must be zero
IStream ** ppstm	//Points to new stream object
);
Parameters

pwcsName

[in] Points to a wide character string that contains the name of the newly created stream. This name can be used later to open or reopen the stream.

grfMode

[in] Specifies the access mode to use when opening the newly created stream. See the STGM enumeration values for descriptions of the possible values.

reserved1

[in] Reserved for future use; must be zero.

reserved2

[in] Reserved for future use; must be zero.

ppstm

[out] On return, points to the location of the new IStream interface pointer. This is only valid if the operation is successful. When an error occurs, this parameter is set to NULL.

Return Values

S_OK

The new stream was successfully created

E_PENDING

Asynchronous Storage only: Part or all of the necessary data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_ACCESSDENIED

Insufficient permissions to create stream.

STG_E_FILEALREADYEXISTS

The name specified for the stream already exists in the storage object and the grfmode flag includes the flag STGM_FAILIFTHERE.

STG_E_INSUFFICIENTMEMORY

The stream was not created due to a lack of memory.

STG_E_INVALIDFLAG

The value specified for the grfMode flag is not a valid STGM enumeration value.

STG_E_INVALIDFUNCTION

The specified combination of grfMode flags is not supported. For example, if this method is called without the STGM_SHARE_EXCLUSIVE flag.

STG_E_INVALIDNAME

Invalid value for pwcsName.

STG_E_INVALIDPOINTER

The pointer specified for the stream object was invalid.

STG_E_INVALIDPARAMETER

One of the parameters was invalid.

STG_E_REVERTED

The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_TOOMANYOPENFILES

The stream was not created because there are too many open files.

Remarks

If a stream with the name specified in the pwcsName parameter already exists and the grfMode parameter includes the STGM_CREATE flag, the existing stream is replaced by a newly created one. Both the destruction of the old stream and the creation of the new stream object are subject to the transaction mode on the parent storage object.

If the stream already exists and grfMode is set to STGM_FAILIFTHERE, this method fails with the return value STG_E_FILEALREADYEXISTS.

See Also

IStorage - Compound File Implementation, IStorage::OpenStream, IStream


IStorage::DestroyElement

Removes the specified storage or stream from this storage object.

HRESULT DestroyElement(

wchar * pwcsName	//Points to the name of the element to be removed
);
Parameter

pwcsName

[in] Points to a wide character string that contains the name of the storage or stream to be removed.

Return Values

S_OK

The element was successfully removed.

E_PENDING

Asynchronous Storage only: Part or all of the element’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_ACCESSDENIED

The caller does not have sufficient permissions for removing the element.

STG_E_FILENOTFOUND

The element with the specified name does not exist.

STG_E_INSUFFICIENTMEMORY

The element was not removed due to a lack of memory.

STG_E_INVALIDNAME

Invalid value for pwcsName.

STG_E_INVALIDPOINTER

The pointer specified for the element was invalid.

STG_E_INVALIDPARAMETER

One of the parameters was invalid.

STG_E_REVERTED

The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_TOOMANYOPENFILES

The element was not removed because there are too many open files.

Remarks

The DestroyElement method deletes a substorage or stream from the current storage object. After a successful call to DestroyElement, any open instance of the destroyed element from the parent storage becomes invalid.

If a storage object is opened in transacted mode, destruction of an element requires that the call to DestroyElement be followed by a call to IStorage::Commit.

See Also

IStorage - Compound File Implementation


IStorage::EnumElements

Retrieves a pointer to an enumerator object that can be used to enumerate the storage and stream objects contained within this storage object.

HRESULT EnumElements(

DWORD reserved1,	//Reserved; must be zero
void * reserved2,	//Reserved; must be NULL
DWORD reserved3,	//Reserved; must be zero
IEnumSTATSTG ** ppenum	//Indirect pointer to IEnumSTATSTG
);
Parameters

reserved1

[in] Reserved for future use; must be zero.

reserved2

[in] Reserved for future use; must be NULL.

reserved3

[in] Reserved for future use; must be zero.

ppenum

[out] When successful, points to the location of an IEnumSTATSTG pointer to new enumerator object.

Return Values

S_OK

The enumerator object was successfully returned.

E_PENDING

Asynchronous Storage only: Part or all of the element’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_INSUFFICIENTMEMORY

The enumerator object could not be created due to lack of memory.

STG_E_INVALIDPARAMETER

One of the parameters was not valid.

STG_E_REVERTED

The storage object has been invalidated by a revert operation above it in the transaction tree.

Remarks

The enumerator object returned by this method implements the IEnumSTATSTG interface, one of the standard enumerator interfaces that contain the Next, Reset, Clone, and Skip methods. IEnumSTATSTG enumerates the data stored in an array of STATSTG structures.

The storage object must be open in read mode to allow the enumeration of its elements.

The order in which the elements are enumerated and whether the enumerator is a snapshot or always reflects the current state of the storage object, and depends on the IStorage implementation.

See Also

IStorage - Compound File Implementation, IEnumXXXX, IEnumSTATSTG, STATSTG


IStorage::MoveElementTo

Copies or moves a substorage or stream from this storage object to another storage object.

HRESULT MoveElementTo(

const WCHAR * pwcsName,	//Name of the element to be moved
IStorage * pstgDest,	//Points to destination storage object
LPWSTR pwcsNewName,	//Points to new name of element in destination
DWORD grfFlags	//Specifies a copy or a move
);
Parameters

pwcsName

[in] Points to a wide character string that contains the name of the element in this storage object to be moved or copied.

pstgDest

[in] IStorage pointer to the destination storage object.

pwcsNewName

[in] Points to a wide character string that contains the new name for the element in its new storage object.

grfFlags

[in] Specifies whether the operation should be a move (STGMOVE_MOVE) or a copy (STGMOVE_COPY). See the STGMOVE enumeration.

Return Values

S_OK

The storage object was successfully copied or moved.

E_PENDING

Asynchronous Storage only: Part or all of the element’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_ACCESSDENIED

The destination storage object is a child of the source storage object.

STG_E_FILENOTFOUND

The element with the specified name does not exist.

STG_E_FILEALREADYEXISTS

The specified file already exists.

STG_E_INSUFFICIENTMEMORY

The copy or move was not completed due to a lack of memory.

STG_E_INVALIDFLAG

The value for the grfFlags parameter is not valid.

STG_E_INVALIDNAME

Invalid value for pwcsName.

STG_E_INVALIDPOINTER

The pointer specified for the storage object was invalid.

STG_E_INVALIDPARAMETER

One of the parameters was invalid.

STG_E_REVERTED

The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_TOOMANYOPENFILES

The copy or move was not completed because there are too many open files.

Remarks

The IStorage::MoveElementTo method is typically the same as invoking the IStorage::CopyTo method on the indicated element and then removing the source element. In this case, the MoveElementTo method uses only the publicly available functions of the destination storage object to carry out the move.

If the source and destination storage objects have special knowledge about each other’s implementation (they could, for example, be different instances of the same implementation), this method can be implemented more efficiently.

Before calling this method, the element to be moved must be closed, and the destination storage must be open.

See Also

IStorage - Compound File Implementation, STGMOVE, IStorage::CopyTo


IStorage::OpenStorage

Opens an existing storage object with the specified name in the specified access mode.

HRESULT OpenStorage(

const WCHAR * pwcsName,	//Points to the name of the storage object to open
IStorage * pstgPriority,	//Points to previous opening of the storage object
DWORD grfMode,	//Access mode for the new storage object
SNB snbExclude,	//Points to a block of stream names in the storage object
DWORD reserved,	//Reserved; must be zero
IStorage ** ppstg	//Points to opened storage object
);
Parameters

pwcsName

[in] Points to a wide character string that contains the name of the storage object to open. It is ignored if pstgPriority is non-NULL.

pstgPriority

[in] If the pstgPriority parameter is not NULL, it is an IStorage pointer to a previous opening of an element of the storage object, usually one that was opened in priority mode. The storage object should be closed and re-opened according to grfMode. When the IStorage::OpenStorage method returns, pstgPriority is no longer valid. Use the value supplied in the ppstg parameter. If the pstgPriority parameter is NULL, it is ignored.

grfMode

[in] Specifies the access mode to use when opening the storage object. See the STGM enumeration values for descriptions of the possible values. Whatever other modes you may choose, you must at least specify STGM_SHARE_EXCLUSIVE when calling this method.

snbExclude

[in] Must be NULL. A non-NULL value will return STG_E_INVALIDPARAMETER.

reserved

[in] Reserved for future use; must be zero.

ppstg

[out] When the operation is successful, points to the location of an IStorage pointer to the opened storage object. This parameter is set to NULL if an error occurs.

Return Values

S_OK

The storage object was opened successfully.

E_PENDING

Asynchronous Storage only: Part or all of the storage’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_ACCESSDENIED

Insufficient permissions to open storage object.

STG_E_FILENOTFOUND

The storage object with the specified name does not exist.

STG_E_INSUFFICIENTMEMORY

The storage object was not opened due to a lack of memory.

STG_E_INVALIDFLAG

The value specified for the grfMode flag is not a valid STGM enumeration value.

STG_E_INVALIDFUNCTION

The specified combination of grfMode flags is not supported.

STG_E_INVALIDNAME

Invalid value for pwcsName.

STG_E_INVALIDPOINTER

The pointer specified for the storage object was invalid.

STG_E_INVALIDPARAMETER

One of the parameters was invalid.

STG_E_REVERTED

The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_TOOMANYOPENFILES

The storage object was not created because there are too many open files.

STG_S_CONVERTED

The existing stream with the specified name was replaced with a new storage object containing a single stream called CONTENTS. In direct mode, the new storage is immediately written to disk. In transacted mode, the new storage is written to a temporary storage in memory and later written to disk when it is committed.

Remarks

Storage objects can be opened with STGM_DELETEONRELEASE, in which case the object is destroyed when it receives its final release. This is useful for creating temporary storage objects.

See Also

IStorage - Compound File Implementation, IStorage::CreateStorage


IStorage::OpenStream

Opens an existing stream object within this storage object in the specified access mode.

HRESULT OpenStream(

const WCHAR * pwcsName,	//Points to name of stream to open
void * reserved1,	//Reserved; must be NULL
DWORD grfMode,	//Access mode for the new stream
DWORD reserved2,	//Reserved; must be zero
IStream ** ppstm	//Indirect pointer to opened stream object
);
Parameters

pwcsName

[in] Points to a wide character string that contains the name of the stream to open.

reserved1

[in] Reserved for future use; must be NULL.

grfMode

[in] Specifies the access mode to be assigned to the open stream. See the STGM enumeration values for descriptions of the possible values. . Whatever other modes you may choose, you must at least specify STGM_SHARE_EXCLUSIVE when calling this method.

reserved2

[in] Reserved for future use; must be zero.

ppstm

[out] On successful return, points to the location of an IStream pointer to the newly-opened stream object. This parameter is set to NULL if an error occurs.

Return Values

S_OK

The stream was successfully opened.

E_PENDING

Asynchronous Storage only: Part or all of the stream’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_ACCESSDENIED

Insufficient permissions to open stream.

STG_E_FILENOTFOUND

The stream with specified name does not exist.

STG_E_INSUFFICIENTMEMORY

The stream was not opened due to a lack of memory.

STG_E_INVALIDFLAG

The value specified for the grfMode flag is not a valid STGM enumeration value.

STG_E_INVALIDFUNCTION

The specified combination of grfMode flags is not supported. For example, if this method is called without the STGM_SHARE_EXCLUSIVE flag.

STG_E_INVALIDNAME

Invalid value for pwcsName.

STG_E_INVALIDPOINTER

The pointer specified for the stream object was invalid.

STG_E_INVALIDPARAMETER

One of the parameters was invalid.

STG_E_REVERTED

The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_TOOMANYOPENFILES

The stream was not opened because there are too many open files.

Remarks

IStorage::OpenStream opens an existing stream object within this storage object in the access mode specified in grfMode. There are restrictions on the permissions that can be given in grfMode. For example, the permissions on this storage object restrict the permissions on its streams. In general, access restrictions on streams should be stricter than those on their parent storages. Compound-file streams must be opened with STGM_SHARE_EXCLUSIVE.

See Also

IStorage - Compound File Implementation, IStorage::CreateStream, IStream


IStorage::RenameElement

Renames the specified substorage or stream in this storage object.

HRESULT RenameElement(

const WCHAR * pwcsOldName,	//Points to the name of the element to be changed
const WCHAR * pwcsNewName	//Points to the new name for the specified element
);
Parameters

pwcsOldName

[in] Points to a wide character string that contains the name of the substorage or stream to be changed.

pwcsNewName

[in] Points to a wide character string that contains the new name for the specified sustorage or stream.

Return Values

S_OK

The element was successfully renamed.

E_PENDING

Asynchronous Storage only: Part or all of the element’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_ACCESSDENIED

The caller does not have sufficient permissions for renaming the element.

STG_E_FILENOTFOUND

The element with the specified old name does not exist.

STG_E_FILEALREADYEXISTS

The element specified by the new name already exists.

STG_E_INSUFFICIENTMEMORY

The element was not renamed due to a lack of memory.

STG_E_INVALIDNAME

Invalid value for one of the names.

STG_E_INVALIDPOINTER

The pointer specified for the element was invalid.

STG_E_INVALIDPARAMETER

One of the parameters was invalid.

STG_E_REVERTED

The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_TOOMANYOPENFILES

The element was not renamed because there are too many open files.

Remarks

IStorage::RenameElement renames the specified substorage or stream in this storage object. An element in a storage object cannot be renamed while it is open. The rename operation is subject to committing the changes if the storage is open in transacted mode.

The IStorage::RenameElement method is not guaranteed to work in low memory with storage objects open in transacted mode. It may work in direct mode.

See Also

IStorage - Compound File Implementation


IStorage::Revert

Discards all changes that have been made to the storage object since the last commit.

HRESULT Revert(void);

Return Values

S_OK

The revert operation was successful.

E_PENDING

Asynchronous Storage only: Part or all of the storage’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_INSUFFICIENTMEMORY

The revert operation could not be completed due to a lack of memory.

STG_E_TOOMANYOPENFILES

The revert operation could not be completed because there are too many open files.

STG_E_REVERTED

The storage object has been invalidated by a revert operation above it in the transaction tree.

Remarks

For storage objects opened in transacted mode, the IStorage::Revert method discards any uncommitted changes to this storage object or changes that have been committed to this storage object from nested elements.

After this method returns, any existing elements (substorages or streams) that were opened from the reverted storage object are invalid and can no longer be used. Specifying these reverted elements in any call except IStorage::Release returns the error STG_E_REVERTED

This method has no effect on storage objects opened in direct mode.

See Also

IStorage - Compound File Implementation, IStorage::Commit


IStorage::SetClass

Assigns the specified CLSID to this storage object.

HRESULT SetClass(

REFCLSID clsid	//Class identifier to be assigned to the storage object
);
Parameter

clsid

[in] The class identifier (CLSID) that is to be associated with the storage object.

Return Values

S_OK

The CLSID was successfully assigned.

E_PENDING

Asynchronous Storage only: Part or all of the storage’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_ACCESSDENIED

The caller does not have sufficient permissions for assigning a class identifier to the storage object.

STG_E_MEDIUMFULL

Not enough space was left on device to complete the operation.

STG_E_REVERTED

The storage object has been invalidated by a revert operation above it in the transaction tree.

Remarks

When first created, a storage object has an associated CLSID of CLSID_NULL. Call this method to assign a CLSID to the storage object.

Call the IStorage::Stat method to retrieve the current CLSID of a storage object.

See Also

IStorage - Compound File Implementation, IStorage::Stat


IStorage::SetElementTimes

Sets the modification, access, and creation times of the specified storage element, if supported by the underlying file system.

HRESULT SetElementTimes(

const WCHAR * pwcsName,	//Points to name of element to be changed
FILETIME const * pctime,	//New creation time for element, or NULL
FILETIME const * patime,	//New access time for element, or NULL
FILETIME const * pmtime	//New modification time for element, or NULL
);
Parameters

pwcsName

[in] The name of the storage object element whose times are to be modified. If NULL, the time is set on the root storage rather than one of its elements.

pctime

[in] Either the new creation time for the element or NULL if the creation time is not to be modified.

patime

[in] Either the new access time for the element or NULL if the access time is not to be modified.

pmtime

[in] Either the new modification time for the element or NULL if the modification time is not to be modified.

Return Values

S_OK

The time values were successfully set.

E_PENDING

Asynchronous Storage only: Part or all of the element’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_ACCESSDENIED

The caller does not have sufficient permissions for changing the element.

STG_E_FILENOTFOUND

The element with the specified name does not exist.

STG_E_INSUFFICIENTMEMORY

The element was not changed due to a lack of memory.

STG_E_INVALIDNAME

Invalid value for the element name.

STG_E_INVALIDPOINTER

The pointer specified for the element was invalid.

STG_E_INVALIDPARAMETER

One of the parameters was invalid.

STG_E_TOOMANYOPENFILES

The element was not changed because there are too many open files.

STG_E_REVERTED

The storage object has been invalidated by a revert operation above it in the transaction tree.

Remarks

This method sets time statistics for the specified storage element within this storage object.

Not all file systems support all of the time values. This method sets those times that are supported and ignores the rest. Each of the time value parameters can be NULL; indicating that no modification should occur.

Call the IStorage::Stat method to retrieve these time values.

See Also

IStorage - Compound File Implementation, IStorage::Stat


IStorage::SetStateBits

Stores up to 32 bits of state information in this storage object.

HRESULT SetStateBits(

DWORD grfStateBits,	//Specifies new values of bits
DWORD grfMask	//Specifies mask that indicates which bits are significant
);
Parameters

grfStateBits

[in] Specifies the new values of the bits to set. No legal values are defined for these bits; they are all reserved for future use and must not be used by applications.

grfMask

[in] A binary mask indicating which bits in grfStateBits are significant in this call.

Return Values

S_OK

The state information was successfully set.

E_PENDING

Asynchronous Storage only: Part or all of the storage’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_ACCESSDENIED

The caller does not have sufficient permissions for changing this storage object.

STG_E_INVALIDFLAG

The value for the grfStateBits or grfMask parameters are not valid.

STG_E_INVALIDPARAMETER

One of the parameters was invalid.

Remarks

This interface is reserved for future use. The values for the state bits are not currently defined.

See Also

IStorage - Compound File Implementation, IStorage::Stat


IStorage::Stat

Retrieves the STATSTG structure for this open storage object.

HRESULT Stat(

STATSTG * pstatstg,	//Location for STATSTG structure
DWORD grfStatFlag	//Values taken from the STATFLAG enumeration
);
Parameters

pstatstg

[out] On return, points to a STATSTG structure where this method places information about the open storage object. This parameter is NULL if an error occurs.

grfStatFlag

[in] Specifies that some of the fields in the STATSTG structure are not returned, thus saving a memory allocation operation. Values are taken from the STATFLAG enumeration.

Return Values

S_OK

The STATSTG structure was successfully returned at the specified location.

E_PENDING

Asynchronous Storage only: Part or all of the storage’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_ACCESSDENIED

The caller does not have sufficient permissions for accessing statistics for this storage object.

STG_E_INSUFFICIENTMEMORY

The STATSTG structure was not returned due to a lack of memory.

STG_E_INVALIDFLAG

The value for the grfStateFlag parameter is not valid.

STG_E_INVALIDPARAMETER

One of the parameters was invalid.

Remarks

IStorage::Stat retrieves the STATSTG structure for the current storage. This structure contains statistical information about the storage. IStorage::EnumElements creates an enumerator object with the IEnumSTATSTG interface, though which you can enumerate the substorages and streams of a storage through the STATSTG structure of each.

See Also

IStorage - Compound File Implementation, STATFLAG, STATSTG, IEnumSTATSTG, IStorage::SetClass, IStorage::SetElementTimes, IStorage::SetStateBits


IStorage - Compound File Implementation

The compound file implementation of IStorage allows you to create and manage substorages and streams within a storage object residing in a compound file object. To create a compound file object and get an IStorage pointer, call the API function StgCreateDocfile. To open an existing compound file object and get its root IStorage pointer, call StgOpenStorage.

When to Use

Most applications use this implementation to to create and manage storages and streams.

Remarks

IStorage::CreateStream

Creates and opens a stream object with the specified name contained in this storage object. The OLE-provided compound file implementation of the IStorage::CreateStream method does not support the following behaviors:

•	The STGM_DELETEONRELEASE flag is not supported.

•	Transacted mode is not supported for stream objects.

•	Opening the same stream more than once from the same storage is not supported. The STGM_SHARE_EXCLUSIVE flag must be specified.

IStorage::OpenStream

Opens an existing stream object within in this storage object using the specified access modes specified in the grfMode parameter. The OLE-provided compound file implementation of the IStorage::OpenStream method does not support the following behavior:

•	The STGM_DELETEONRELEASE flag is not supported.

•	Transacted mode is not supported for stream objects.

•	Opening the same stream more than once from the same storage is not supported. The STGM_SHARE_EXCLUSIVE flag must be specified.

IStorage::CreateStorage

The OLE-provided compound file implementation of the IStorage::CreateStorage method does not support the STGM_DELETEONRELEASE flag. Specifying this flag causes the method to return STG_E_INVALIDFLAG.

IStorage::OpenStorage

Opens an existing storage object with the specified name in the specified access mode. The OLE-provided compound file implementation of the IStorage::OpenStorage method does not support the following behavior:

•	The STGM_PRIORITY flag is not supported for non-root storages.

•	Opening the same storage object more than once from the same parent storage is not supported. The STGM_SHARE_EXCLUSIVE flag must be specified.

•	The STGM_DELETEONRELEASE flag is not supported. If this flag is specified, the function returns STG_E_INVALIDFUNCTION.

IStorage::CopyTo

Copies only the substorages and streams of this open storage object into another storage object. The rgiidExclude parameter can be set to IID_IStream to copy only substorages, or to IID_IStorage to copy only streams.

IStorage::MoveElementTo

Copies or moves a substorage or stream from this storage object to another storage object.

IStorage::Commit

Ensures that any changes made to a storage object open in transacted mode are reflected in the parent storage; for a root storage, reflects the changes in the actual device, for example, a file on disk. For a root storage object opened in direct mode, this method has no effect except to flush all memory buffers to the disk. For non-root storage objects in direct mode, this method has no effect.

The OLE-provided compound files implementation uses a two phase commit process unless STGC_OVERWRITE is specified in the grfCommitFlags parameter. This two-phase process ensures the robustness of data in case the commit operation fails. First, all new data is written to unused space in the underlying file. If necessary, new space is allocated to the file. Once this step has been successfully completed, a table in the file is updated using a single sector write to indicate that the new data is to be used in place of the old. The old data becomes free space to be used at the next commit. Thus, the old data is available and can be restored in case an error occurs when committing changes. If STGC_OVERWRITE is specified, a single phase commit operation is used.

IStorage::Revert

Discards all changes that have been made to the storage object since the last commit.

IStorage::EnumElements

Creates and retrieves a pointer to an enumerator object that can be used to enumerate the storage and stream objects contained within this storage object.The OLE-provided compound file implementation takes a snapshot.

IStorage::DestroyElement

Removes the specified element (substorage or stream) from this storage object.

IStorage::RenameElement

Renames the specified substorage or stream in this storage object.

IStorage::SetElementTimes

Sets the modification, access, and creation times of the specified storage element. The OLE-provided compound file implementation maintains modification and change times for internal storage objects. For root storage objects, whatever is supported by the underlying file system (or ILockBytes) is supported. The compound file implementation does not maintain any time stamps for internal streams. Unsupported time stamps are reported as zero, enabling the caller to test for support.

IStorage::SetClass

Assigns the specified CLSID to this storage object.

IStorage::SetStateBits

Stores up to 32 bits of state information in this storage object. The state set by this method is for external use only. The OLE-provided compound file implementation does not perform any action based on the state.

IStorage::Stat

Retrieves the STATSTG structure for this open storage object.

See Also

IStorage, IStream, StgCreateDocfile, StgOpenStorage, IFillLockBytes, ILockBytes, IRootStorage


IStream

The IStream interface supports reading and writing data to stream objects. Stream objects contain the data in a structured storage object, where storages provide the structure. Simple data can be written directly to a stream, but most frequently, streams are elements nested within a storage object. They are similar to standard files.

The IStream interface defines methods similar to the MS-DOS FAT file functions. For example, each stream object has its own access rights and a seek pointer. The main difference between a stream object and a DOS file is that streams are not opened using a file handle, but through an IStream interface pointer.

The methods in this interface present your object’s data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams open in transacted mode and methods for restricting access to a range of bytes in the stream.

Streams can remain open for long periods of time without consuming file system resources. The IStream::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.

When to Implement

Implement IStream on a container or object application when you require functionality not provided by the OLE compound file implementation. The specification of IStream defines more functionality that the OLE implementation supports. In addition, if you are creating a stream object that is larger than the heap in your machine’s memory and you are using a global memory handle, the compound file implementation calls GlobalRealloc internally whenever it needs more memory, which can be extremely inefficient. In this case, the preferred solution is to implement an IStream that uses memory allocated by VirtualAlloc instead of GlobalAlloc. This can reserve a large chunk of virtual address space and then commit memory within that address space as required. No data copying occurs and memory is committed only as it is needed. For more information, refer to IStream - Compound File Implementation.

When to Use

Call the methods of the IStream interface from a container or application to read and write the data for an object. Since stream objects can be marshaled to other processes, applications can share the data in storage objects without having to use global memory.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IStream Methods	Description
Read	Reads a specified number of bytes from the stream object into memory starting at the current seek pointer.
Write	Writes a specified number from bytes into the stream object starting at the current seek pointer.
Seek	Changes the seek pointer to a new location relative to the beginning of the stream, the end of the stream, or the current seek pointer.
SetSize	Changes the size of the stream object.
CopyTo	Copies a specified number of bytes from the current seek pointer in the stream to the current seek pointer in another stream.
Commit	Ensures that any changes made to a stream object open in transacted mode are reflected in the parent storage object.
Revert	Discards all changes that have been made to a transacted stream since the last IStream::Commit call.
LockRegion	Restricts access to a specified range of bytes in the stream. Supporting this functionality is optional since some file systems do not provide it.
UnlockRegion	Removes the access restriction on a range of bytes previously restricted with IStream::LockRegion.
Stat	Retrieves the STATSTG structure for this stream.
Clone	Creates a new stream object that references the same bytes as the original stream but provides a separate seek pointer to those bytes.


IStream::Clone

Creates a new stream object with its own seek pointer that references the same bytes as the original stream.

HRESULT Clone(

IStream ** ppstm	//Points to location for pointer to the new stream object
);
Parameter

ppstm

[out] When successful, points to the location of an IStream pointer to the new stream object. If an error occurs, this parameter is NULL.

Return Values

S_OK

The stream was successfully cloned.

E_PENDING

Asynchronous Storage only: Part or all of the stream’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_INSUFFICIENT_MEMORY

The stream was not cloned due to a lack of memory.

STG_E_INVALIDPOINTER

The ppStm pointer is not valid.

STG_E_REVERTED

The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

This method creates a new stream object for accessing the same bytes but using a separate seek pointer. The new stream object sees the same data as the source stream object. Changes written to one object are immediately visible in the other. Range locking is shared between the stream objects.

The initial setting of the seek pointer in the cloned stream instance is the same as the current setting of the seek pointer in the original stream at the time of the clone operation.

See Also

IStream - Compound File Implementation, IStream::CopyTo


IStream::Commit

Ensures that any changes made to a stream object open in transacted mode are reflected in the parent storage. If the stream object is open in direct mode, IStream::Commit has no effect other than flushing all memory buffers to the next level storage object. The OLE compound file implementation of streams does not support opening streams in transacted mode.

HRESULT Commit(

DWORD grfCommitFlags	//Specifies how changes are committed
);
Parameter

grfCommitFlags

[in] Controls how the changes for the stream object are committed. See the STGC enumeration for a definition of these values.

Return Values

S_OK

Changes to the stream object were successfully committed to the parent level.

E_PENDING

Asynchronous Storage only: Part or all of the stream’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_MEDIUMFULL

The commit operation failed due to lack of space on the storage device.

STG_E_REVERTED

The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

This method ensures that changes to a stream object opened in transacted mode are reflected in the parent storage. Changes that have been made to the stream since it was opened or last committed are reflected to the parent storage object. If the parent is opened in transacted mode, the parent may still revert at a later time rolling back the changes to this stream object. The compound file implementation does not support opening streams in transacted mode, so this method has very little effect other than to flush memory buffers. For more information, refer to IStream - Compound File Implementation.

If the stream is open in direct mode, this method ensures that any memory buffers have been flushed out to the underlying storage object. This is much like a flush in traditional file systems.

The IStream::Commit method is useful on a direct mode stream when the implementation of the IStream interface is a wrapper for underlying file system APIs. In this case, IStream::Commit would be connected to the file system’s flush call.

See Also

IStream - Compound File Implementation, IStorage::Commit


IStream::CopyTo

Copies a specified number of bytes from the current seek pointer in the stream to the current seek pointer in another stream.

HRESULT CopyTo(

IStream * pstm,	//Points to the destination stream
ULARGE_INTEGER cb,	//Specifies the number of bytes to copy
ULARGE_INTEGER * pcbRead,	//Pointer to the actual number of bytes read from the source
ULARGE_INTEGER * pcbWritten	//Pointer to the actual number of bytes written to the destination
);
Parameters

pstm

[in] Points to the destination stream. The stream pointed to by pstm can be a new stream or a clone of the source stream.

cb

[in] Specifies the number of bytes to copy from the source stream.

pcbRead

[out] Pointer to the location where this method writes the actual number of bytes read from the source. You can set this pointer to NULL to indicate that you are not interested in this value. In this case, this method does not provide the actual number of bytes read.

pcbWritten

[out] Pointer to the location where this method writes the actual number of bytes written to the destination. You can set this pointer to NULL to indicate that you are not interested in this value. In this case, this method does not provide the actual number of bytes written.

Return Values

S_OK

The stream object was successfully copied.

E_PENDING

Asynchronous Storage only: Part or all of the data to be copied is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_INVALIDPOINTER

The value of one of the pointer parameters is not valid.

STG_E_MEDIUMFULL

The stream is not copied because there is no space left on the storage device.

STG_E_REVERTED

The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

This method copies the specified bytes from one stream to another. The seek pointer in each stream instance is adjusted for the number of bytes read or written. This method is equivalent to reading cb bytes into memory using IStream::Read and then immediately writing them to the destination stream using IStream::Write, although IStream::CopyTo will be more efficient.

The destination stream can be a clone of the source stream created by calling the IStream::Clone method.

If IStream::CopyTo returns an error, you cannot assume that the seek pointers are valid for either the source or destination. Additionally, the values of pcbRead and pcbWritten are not meaningful even though they are returned.

If IStream::CopyTo returns successfully, the actual number of bytes read and written are the same.

To copy the remainder of the source from the current seek pointer, specify the maximum large integer value for the cb parameter. If the seek pointer is the beginning of the stream, this technique copies the entire stream.

See Also

IStream - Compound File Implementation, IStream::Read, IStream::Write, IStream::Clone


IStream::LockRegion

Restricts access to a specified range of bytes in the stream. Supporting this functionality is optional since some file systems do not provide it.

HRESULT LockRegion(

ULARGE_INTEGER libOffset,	//Specifies the byte offset for the beginning of the range
ULARGE_INTEGER cb,	//Specifies the length of the range in bytes
DWORD dwLockType	//Specifies the restriction on accessing the specified range
);
Parameters

libOffset

[in] Integer that specifies the byte offset for the beginning of the range.

cb

[in] Integer that specifies the length of the range, in bytes, to be restricted.

dwLockType

[in] Specifies the restrictions being requested on accessing the range.

Return Values

S_OK

The specified range of bytes was locked.

E_PENDING

Asynchronous Storage only: Part or all of the stream’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_INVALIDFUNCTION

Locking is not supported at all or the specific type of lock requested is not supported.

STG_E_LOCKVIOLATION

Requested lock is supported, but cannot be granted because of an existing lock.

STG_E_REVERTED

The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

The byte range can extend past the current end of the stream. Locking beyond the end of a stream is useful as a method of communication between different instances of the stream without changing data that is actually part of the stream.

Three types of locking can be supported: locking to exclude other writers, locking to exclude other readers or writers, and locking that allows only one requestor to obtain a lock on the given range, which is usually an alias for one of the other two lock types. A given stream instance might support either of the first two types, or both. The lock type is specified by dwLockType, using a value from the LOCKTYPE enumeration.

Any region locked with IStream::LockRegion must later be explicitly unlocked by calling IStream::UnlockRegion with exactly the same values for the libOffset, cb, and dwLockType parameters. The region must be unlocked before the stream is released. Two adjacent regions cannot be locked separately and then unlocked with a single unlock call.

Notes to Callers

Since the type of locking supported is optional and can vary in different implementations of IStream, you must provide code to deal with the STG_E_INVALIDFUNCTION error.

This method has no effect in the compound file implementation, because the implementation does not support range locking.

Notes to Implementers

Support for this method is optional for implementations of stream objects since it may not be supported by the underlying file system. The type of locking supported is also optional. The STG_E_INVALIDFUNCTION error is returned if the requested type of locking is not supported.

See Also

IStream - Compound File Implementation, LOCKTYPE, IStream::UnlockRegion


IStream::Read

Reads a specified number of bytes from the stream object into memory starting at the current seek pointer.

HRESULT Read(

void * pv,	//Pointer to buffer into which the stream is read
ULONG cb,	//Specifies the number of bytes to read
ULONG * pcbRead	//Pointer to location that contains actual number of bytes read
);
Parameters

pv

[in] Points to the buffer into which the stream is read. If an error occurs, this value is NULL.

cb

[in] Specifies the number of bytes of data to attempt to read from the stream object.

pcbRead

[out] Pointer to a location where this method writes the actual number of bytes read from the stream object. You can set this pointer to NULL to indicate that you are not interested in this value. In this case, this method does not provide the actual number of bytes read.

Return Values

S_OK

Data was successfully read from the stream object.

S_FALSE

The data could not be read from the stream object.

E_PENDING

Asynchronous Storage only: Part or all of the data to be read is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_ACCESSDENIED

The caller does not have sufficient permissions for reading this stream object.

STG_E_INVALIDPOINTER

One of the pointer values is invalid.

STG_E_REVERTED

The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

This method reads bytes from this stream object into memory. The stream object must be opened in STGM_READ mode. This method adjusts the seek pointer by the actual number of bytes read.

The number of bytes actually read is returned in the pcbRead parameter.

Notes to Callers

The actual number of bytes read can be fewer than the number of bytes requested if an error occurs or if the end of the stream is reached during the read operation.

Some implementations might return an error if the end of the stream is reached during the read. You must be prepared to deal with the error return or S_OK return values on end of stream reads.

See Also

IStream - Compound File Implementation, STGMOVE, IStorage::OpenStream, IStream::Write


IStream::Revert

Discards all changes that have been made to a transacted stream since the last IStream::Commit call. On streams open in direct mode and streams using the OLE compound file implementation of IStream::Revert, this method has no effect.

HRESULT Revert(void);

Return Values

S_OK

The stream was successfully reverted to its previous version.

E_PENDING

Asynchronous Storage only: Part or all of the stream’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

Remarks

This method discards changes made to a transacted stream since the last commit operation.

See Also

IStream - Compound File Implementation, IStream::Commit


IStream::Seek

Changes the seek pointer to a new location relative to the beginning of the stream, to the end of the stream, or to the current seek pointer.

HRESULT Seek(

LARGE_INTEGER dlibMove,	//Offset relative to dwOrigin
DWORD dwOrigin,	//Specifies the origin for the offset
ULARGE_INTEGER * plibNewPosition	//Pointer to location containing new seek pointer
);
Parameters

dlibMove

[in] Displacement to be added to the location indicated by dwOrigin. If dwOrigin is STREAM_SEEK_SET, this is interpreted as an unsigned value rather than signed.

dwOrigin

[in] Specifies the origin for the displacement specified in dlibMove. The origin can be the beginning of the file, the current seek pointer, or the end of the file. See the STREAM_SEEK enumeration for the values.

plibNewPosition

[out] Pointer to the location where this method writes the value of the new seek pointer from the beginning of the stream. You can set this pointer to NULL to indicate that you are not interested in this value. In this case, this method does not provide the new seek pointer.

Return Values

S_OK

The seek pointer has been successfully adjusted.

E_PENDING

Asynchronous Storage only: Part or all of the stream’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_INVALIDPOINTER

The value of the plibNewPosition parameter is not valid.

STG_E_INVALIDFUNCTION

The value of the dwOrigin parameter is not valid.

STG_E_REVERTED

The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

IStream::Seek changes the seek pointer so subsequent reads and writes can take place at a different location in the stream object. It is an error to seek before the beginning of the stream. It is not, however, an error to seek past the end of the stream. Seeking past the end of the stream is useful for subsequent writes, as the stream will at that time be extended to the seek position immediately before the write is done.

You can also use this method to obtain the current value of the seek pointer by calling this method with the dwOrigin parameter set to STREAM_SEEK_CUR and the dlibMove parameter set to 0 so the seek pointer is not changed. The current seek pointer is returned in the plibNewPosition parameter.

See Also

IStream - Compound File Implementation, STREAM_SEEK, IStream::Read, IStream::Write


IStream::SetSize

Changes the size of the stream object.

HRESULT SetSize(

ULARGE_INTEGER libNewSize	//Specifies the new size of the stream object
);
Parameter

libNewSize

[in] Specifies the new size of the stream as a number of bytes.

Return Values

S_OK

The size of the stream object was successfully changed.

E_PENDING

Asynchronous Storage only: Part or all of the stream’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_MEDIUMFULL

The stream size is not changed because there is no space left on the storage device.

STG_E_INVALIDFUNCTION

The value of the libNewSize parameter is not valid. Since streams cannot be greater than 232 bytes in the OLE-provided implementation, the high DWORD of libNewSize must be 0. If it is nonzero, this parameter is not valid.

STG_E_REVERTED

The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

IStream::SetSize changes the size of the stream object. Call this method to preallocate space for the stream. If the libNewSize parameters larger than the current stream size, the stream is extended to the indicated size by filling the intervening space with bytes of undefined value. This operation is similar to the IStream::Write method if the seek pointer is past the current end-of-stream.

If the libNewSize parameter is smaller than the current stream, then the stream is truncated to the indicated size.

The seek pointer is not affected by the change in stream size.

Calling IStream::SetSize can be  an effective way of trying to obtain a large chunk of contiguous space.

See Also

IStream - Compound File Implementation, IStream::Write


IStream::Stat

Retrieves the STATSTG structure for this stream.

HRESULT Stat(

STATSTG * pstatstg,	//Location for STATSTG structure
DWORD grfStatFlag	//Values taken from the STATFLAG enumeration
);
Parameters

pstatstg

[out] Points to a STATSTG structure where this method places information about this stream object. This pointer is NULL if an error occurs.

grfStatFlag

[in] Specifies that this method does not return some of the fields in the STATSTG structure, thus saving a memory allocation operation. Values are taken from the STATFLAG enumeration.

Return Value

S_OK

The STATSTG structure was successfully returned at the specified location.

E_PENDING

Asynchronous Storage only: Part or all of the stream’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_ACCESSDENIED

The caller does not have sufficient permissions for accessing statistics for this storage object.

STG_E_INSUFFICIENTMEMORY

The STATSTG structure was not returned due to a lack of memory.

STG_E_INVALIDFLAG

The value for the grfStateFlag parameter is not valid.

STG_E_INVALIDPOINTER

The pStatStg pointer is not valid.

STG_E_REVERTED

The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

IStream::Stat retrieves a pointer to the STATSTG structure that contains information about this open stream. When this stream is within a structured storage and IStorage::EnumElements is called, it creates an enumerator object with the IEnumSTATSTG interface on it, which can be called to enumerate the storages and streams through the STATSTG structures associated with each of them.

See Also

IStream - Compound File Implementation, STATFLAG, STATSTG


IStream::UnlockRegion

Removes the access restriction on a range of bytes previously restricted with IStream::LockRegion.

HRESULT UnlockRegion(

ULARGE_INTEGER libOffset,	//Specifies the byte offset for the beginning of the range
ULARGE_INTEGER cb,	//Specifies the length of the range in bytes
DWORD dwLockType	//Specifies the access restriction previously placed on the range
);
Parameters

libOffset

[in] Specifies the byte offset for the beginning of the range.

cb

[in] Specifies, in bytes, the length of the range to be restricted.

dwLockType

[in] Specifies the access restrictions previously placed on the range.

Return Values

S_OK

The byte range was unlocked.

E_PENDING

Asynchronous Storage only: Part or all of the stream’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_INVALIDFUNCTION

Locking is not supported at all or the specific type of lock requested is not supported.

STG_E_LOCKVIOLATION

The requested unlock cannot be granted.

STG_E_REVERTED

The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

IStream::UnlockRegion unlocks a region previously locked with the IStream::LockRegion method. Locked regions must later be explicitly unlocked by calling IStream::UnlockRegion with exactly the same values for the libOffset, cb, and dwLockType parameters. The region must be unlocked before the stream is released. Two adjacent regions cannot be locked separately and then unlocked with a single unlock call.

See Also

IStream - Compound File Implementation, LOCKTYPE, IStream::LockRegion


IStream::Write

Writes a specified number from bytes into the stream object starting at the current seek pointer.

HRESULT Write(

void const* pv,	//Pointer to buffer from which stream is written
ULONG cb,	//Specifies the number of bytes to write
ULONG * pcbWritten	//Specifies the actual number of bytes written
);
Parameters

pv

[in] Points to the buffer from which the stream should be written.

cb

[in] The number of bytes of data to attempt to write into the stream.

pcbWritten

[out] Pointer to a location where this method writes the actual number of bytes written to the stream object. The caller can set this pointer to NULL, in which case, this method does not provide the actual number of bytes written.

Return Values

S_OK

The data was successfully written into the stream object.

E_PENDING

Asynchronous Storage only: Part or all of the data to be written is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.

STG_E_MEDIUMFULL

The write operation was not completed because there is no space left on the storage device.

STG_E_ACCESSDENIED

The caller does not have sufficient permissions for writing this stream object.

STG_E_CANTSAVE

Data cannot be written for reasons other than no access or space.

STG_E_INVALIDPOINTER

One of the pointer values is invalid.

STG_E_REVERTED

The object has been invalidated by a revert operation above it in the transaction tree.

STG_E_WRITEFAULT

The write operation was not completed due to a disk error.

Remarks

IStream::Write writes the specified data to a stream object. The seek pointer is adjusted for the number of bytes actually written. The number of bytes actually written is returned in the pcbWrite parameter. If the byte count is zero bytes, the write operation has no effect.

If the seek pointer is currently past the end of the stream and the byte count is non-zero, this method increases the size of the stream to the seek pointer and writes the specified bytes starting at the seek pointer. The fill bytes written to the stream are not initialized to any particular value. This is the same as the end-of-file behavior in the MS-DOS FAT file system.

With a zero byte count and a seek pointer past the end of the stream, this method does not create the fill bytes to increase the stream to the seek pointer. In this case, you must call the IStream::SetSize method to increase the size of the stream and write the fill bytes.

The pcbWrite parameter can have a value even if an error occurs.

In the OLE-provided implementation, stream objects are not sparse. Any fill bytes are eventually allocated on the disk and assigned to the stream.

See Also

IStream - Compound File Implementation


IStream - Compound File Implementation

The IStream interface supports reading and writing data to stream objects. Stream objects contain the data in a structured storage object, where storages provide the structure. Simple data can be written directly to a stream, but most frequently, streams are elements nested within a storage object. They are similar to standard files.

The specification of IStream defines more functionality that the OLE implementation supports. For example, the IStream interface defines streams up to 264 bytes in length requiring a 64-bit seek pointer. However, the OLE implementation only supports streams up to 232 bytes in length and read and write operations are always limited to 232 bytes at a time. The OLE implementation also does not support stream transactioning or region locking.

When you want to create a simple stream based on global memory, you can get an IStream pointer by calling the API function CreateStreamOnHGlobal. To get an IStream pointer within a compound file object, call either StgCreateDocfile or StgOpenStorage. These functions retrieve an IStorage pointer, with which you can then call CreateStream/OpenStream for an IStream pointer. In either case, the same IStream implementation code is used.

When to Use

Call the methods of IStream to read and write data to a stream.

Since stream objects can be marshaled to other processes, applications can share the data in storage objects without having to use global memory. In the OLE compound file implementation of stream objects, the custom marshaling facilities in OLE create a remote version of the original object in the new process when the two processes have shared memory access. Thus, the remote version does not need to communicate with the original process to carry out its functions.

The remote version of the stream object shares the same seek pointer as the original stream. If you do not want to share the seek pointer, you should use the IStream::Clone method to provide a copy of the stream object for the remote process.

Note  If you are creating a stream object that is larger than the heap in your machine’s memory and you are using an HGLOBAL, the stream object calls GlobalRealloc internally whenever it needs more memory. Because GlobalRealloc always copies data from the source to the destination, increasing a stream object from 20M to 25M, for example, consumes immense amounts of time. This is due to the size of the increments copied and is worsened if there is less than 45M of memory on the machine because of disk swapping.

The preferred solution is to implement an IStream that uses memory allocated by VirtualAlloc instead of GlobalAlloc. This can reserve a large chunk of virtual address space and then commit memory within that address space as required. No data copying occurs and memory is committed only as it is needed.

Another alternative is to call the IStream::SetSize method on the stream object to increase the memory allocation in advance. This is not, however, as efficient as using VirtualAlloc as described above.

Remarks

IStream::Read

Reads a specified number of bytes from the stream object into memory starting at the current seek pointer. This implementation returns S_OK if the end of the stream was reached during the read. (This is the same as the “end of file” behavior found in the MS-DOS FAT file system.

IStream::Write

Writes a specified number from bytes into the stream object starting at the current seek pointer. In this implementation, stream objects are not sparse. Any fill bytes are eventually allocated on the disk and assigned to the stream.

IStream::Seek

Changes the seek pointer to a new location relative to the beginning of the stream, to the end of the stream, or to the current seek pointer.

IStream::SetSize

Changes the size of the stream object. In this implementation, there is no guarantee that the space allocated will be contiguous

IStream::CopyTo

Copies a specified number of bytes from the current seek pointer in the stream to the current seek pointer in another stream.

IStream::Commit

The compound file implementation of IStream supports opening streams only in direct mode, not transacted mode. Therefore, the method has no effect when called other than to flush all memory buffers to the next storage level.

In this implementation, it does not matter if you commit changes to streams, you need only commit changes for storage objects.

IStream::Revert

This implementation does not support transacted streams, so a call to this method has no effect.

IStream::LockRegion

Range-locking is not supported by this implementation, so a call to this method has no effect.

IStream::UnlockRegion

Removes the access restriction on a range of bytes previously restricted with IStream::LockRegion.

IStream::Stat

Retrieves the STATSTG structure for this stream

IStream::Clone

Creates a new stream object with its own seek pointer that references the same bytes as the original stream.

See Also

IStream, IStorage, CreateStreamOnHGlobal, StgCreateDocfile, StgOpenStorage


IUnknown

The IUnknown interface lets clients get pointers to other interfaces on a given object through the QueryInterface method, and manage the existence of the object through the IUnknown::AddRef and IUnknown::Release methods. All other COM interfaces are inherited, directly or indirectly, from IUnknown. Therefore, the three methods in IUnknown are the first entries in the VTable for every interface.

When to Implement

You must implement IUnknown as part of every interface. If you are using C++ multiple inheritance to implement multiple interfaces, the various interfaces can share one implementation of IUnknown. If you are using nested classes to implement multiple interfaces, you must implement IUnknown once for each interface you implement.

When to Use

Use IUnknown methods to switch between interfaces on an object, add references, and release objects.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.


IUnknown::AddRef

The IUnknown::AddRef method increments the reference count for an interface on an object. It should be called for every new copy of a pointer to an interface on a given object.

ULONG AddRef(void);

Return Value

Returns an integer from 1 to n, the value of the new reference count. This information is meant to be used for diagnostic/testing purposes only, because, in certain situations, the value may be unstable.

Remarks

Objects use a reference counting mechanism to ensure that the lifetime of the object includes the lifetime of references to it. You use IUnknown::AddRef to stabilize a copy of an interface pointer. It can also be called when the life of a cloned pointer must extend beyond the lifetime of the original pointer. The cloned pointer must be released by calling IUnknown::Release.

Objects must be able to maintain (2 (31) )-1 outstanding pointer references. Therefore, the internal reference counter that IUnknown::AddRef maintains must be a 32-bit unsigned integer.

Notes to Callers

Call this function for every new copy of an interface pointer that you make. For example, if you are passing a copy of a pointer back from a function, you must call IUnknown::AddRef on that pointer. You must also call IUnknown::AddRef on a pointer before passing it as an in-out parameter to a function; the function will call IUnknown::Release before copying the out-value on top of it.

See Also

IUnknown::Release


IUnknown::QueryInterface

Returns a pointer to a specified interface on an object to which a client currently holds an interface pointer. This function must call IUnknown::AddRef on the pointer it returns.

HRESULT QueryInterface(

REFIID iid,	//Identifier of the requested interface
void ** ppvObject	//Indirect pointer to the object
);
Parameters

iid

[in] Identifier of the interface being requested.

ppvObject

[out] Indirectly points to the interface specified in iid. If the object does not support the interface specified in iid, *ppvObject is set to NULL.

Return Value

S_OK if the interface is supported, E_NOINTERFACE if not.

Remarks

The QueryInterface method gives a client access to other interfaces on an object.

For any one object, a specific query for the IUnknown interface on any of the object’s interfaces must always return the same pointer value. This allows a client to determine whether two pointers point to the same component by calling QueryInterface on both and comparing the results. It is specifically not the case that queries for interfaces (even the same interface through the same pointer) must return the same pointer value.

There are four requirements for implementations of QueryInterface (In these cases, “must succeed” means “must succeed barring catastrophic failure.”):

•	The set of interfaces accessible on an object through IUnknown::QueryInterface must be static, not dynamic. This means that if a call to QueryInterface for a pointer to a specified interface succeeds the first time, it must succeed again, and if it fails the first time, it must fail on all subsequent queries.

•	It must be symmetric — if a client holds a pointer to an interface on an object, and queries for that interface, the call must succeed.

•	It must be reflexive — if a client holding a pointer to one interface queries successfully for another, a query through the obtained pointer for the first interface must succeed.

•	It must be transitive — if a client holding a pointer to one interface queries successfully for a second, and through that pointer queries successfully for a third interface, a query for the first interface through the pointer for the third interface must succeed.


IUnknown::Release

Decrements the reference count for the calling interface on a object. If the reference count on the object falls to 0, the object is freed from memory.

ULONG Release(void);

Return Value

Returns the resulting value of the reference count, which is used for diagnostic/testing purposes only. If you need to know that resources have been freed, use an interface with higher-level semantics.

Remarks

If IUnknown::AddRef has been called on this object’s interface n times and this is the n+1th call to IUnknown::Release, the implementation of IUnknown::AddRef must cause the interface pointer to free itself. When the released pointer is the only existing reference to an object (whether the object supports single or multiple interfaces), the implementation must free the object.

Note  Aggregation of objects restricts the ability to recover interface pointers.

Notes to Callers

Call this function when you no longer need to use an interface pointer. If you are writing a function that takes an in-out parameter, call IUnknown::Release on the pointer you are passing in before copying the out-value on top of it.

See Also

IUnknown::AddRef


IViewObject

The IViewObject interface enables an object to display itself directly without passing a data object to the caller. In addition, this interface can create and manage a connection with an advise sink so the caller can be notified of changes in the view object.

The caller can request specific representations and specific target devices. For example, a caller can ask for either an object’s content or an iconic representation. Also, the caller can ask the object to compose a picture for a target device that is independent of the drawing device context. As a result, the picture can be composed for one target device and drawn on another device context. For example, to provide a print preview operation, you can compose the drawing for a printer target device but actually draw the representation on the display.

The IViewObject interface is similar to IDataObject; except that IViewObject places a representation of the data onto a device context while IDataObject places the representation onto a transfer medium.

Unlike most other interfaces, IViewObject cannot be marshaled to another process. This is because device contexts are only effective in the context of one process.

When to Implement

Object handlers and in-process servers that manage their own presentations implement IViewObject for use by compound document containers. OLE provides an IViewObject implementation for its default object handler’s cache.

When to Use

You call IViewObject from a container application if you need to draw a contained object on a specific device context. For example, if you want to print the object to a printer, you call the Draw method in the IViewObject interface.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IViewObject Methods	Description
Draw	Draws a representation of the object onto a device context.
GetColorSet	Returns the logical palette the object uses for drawing.
Freeze	Freezes the drawn representation of an object so it will not change until a subsequent Unfreeze.
Unfreeze	Unfreezes the drawn representation of an object.
SetAdvise	Sets up a connection between the view object and an advise sink so that the advise sink can receive notifications of changes in the view object.
GetAdvise	Returns the information on the most recent SetAdvise.


IViewObject::Draw

Draws a representation of an object onto the specified device context.

HRESULT Draw(

DWORD dwAspect,	//Aspect to be drawn
LONG lindex,	//Part of the object of interest in the draw operation
void * pvAspect,	//Pointer to DVASPECTINFO structure or NULL
DVTARGETDEVICE * ptd,	//Pointer to target device in a structure
HDC hicTargetDev,	//Information context for the target device
HDC hdcDraw,	//Device context on which to draw
const LPRECTL lprcBounds,	//Pointer to the rectangle in which the object is drawn
const LPRECTL lprcWBounds,	//Pointer to the window extent and window origin when drawing a metafile
BOOL (*) (DWORD) pfnContinue,	//Pointer to the callback function for canceling or continuing the drawing
DWORD dwContinue	//Value to pass to the callback function
);
Parameters

dwAspect

[in] Specifies the aspect to be drawn, that is, how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. Valid values are taken from the enumerations DVASPECT and DVASPECT2. Note that newer objects and containers that support optimized drawing interfaces support the DVASPECT2 enumeration values. Older objects and containers that do not support optimized drawing interfaces may not support DVASPECT2. Windowless objects allow only DVASPECT_CONTENT, DVASPECT_OPAQUE, and DVASPECT_TRANSPARENT.

lindex

[in] Portion of the object that is of interest for the draw operation. Its interpretation varies depending on the value in the dwAspect parameter. See the DVASPECT enumeration for more information.

pvAspect

[in] Pointer to additional information in a DVASPECTINFO structure that enables drawing optimizations depending on the aspect specified. Note that newer objects and containers that support optimized drawing interfaces support this parameter as well. Older objects and containers that do not support optimized drawing interfaces always specify NULL for this parameter.

ptd

[in] Pointer to the DVTARGETDEVICE structure that describes the device for which the object is to be rendered. If NULL, the view should be rendered for the default target device (typically the display). A value other than NULL is interpreted in conjunction with hicTargetDev and hdcDraw. For example, if hdcDraw specifies a printer as the device context, the ptd parameter points to a structure describing that printer device. The data may actually be printed if hicTargetDev is a valid value or it may be displayed in print preview mode if hicTargetDev is NULL.

hicTargetDev

[in] Information context for the target device indicated by the ptd parameter from which the object can extract device metrics and test the device’s capabilities. If ptd is NULL; the object should ignore the value in the hicTargetDev parameter.

hdcDraw

[in] Device context on which to draw. For a windowless object, the hdcDraw parameter should be in MM_TEXT mapping mode with its logical coordinates matching the client coordinates of the containing window. For a windowless object, the device context should be in the same state as the one normally passed by a WM_PAINT message.

lprcBounds

[in] Pointer to a RECTL structure specifying the rectangle on hdcDraw and in which the object should be drawn. This parameter controls the positioning and stretching of the object. This parameter should be NULL to draw a windowless in-place active object. In every other situation, NULL is not a legal value and should result in an E_INVALIDARG error code. If the container passes a non-NULL value to a windowless object, the object should render the requested aspect into the specified device context and rectangle. A container can request this from a windowless object to render a second, non-active view of the object or to print the object.

lprcWBounds

[in] If hdcDraw is a metafile device context, pointer to a RECTL structure specifying the bounding rectangle in the underlying metafile. The rectangle structure contains the window extent and window origin. These values are useful for drawing metafiles. The rectangle indicated by lprcBounds is nested inside this lprcWBounds rectangle; they are in the same coordinate space.

If hdcDraw is not a metafile device context; lprcWBounds will be NULL.

pfnContinue

[in] Pointer to a callback function that the view object should call periodically during a lengthy drawing operation to determine whether the operation should continue or be canceled. This function returns TRUE to continue drawing. It returns FALSE to stop the drawing in which case IViewObject::Draw returns DRAW_E_ABORT.

dwContinue

[in] Value to pass as a parameter to the function pointed to by the pfnContinue parameter. Typically, dwContinue is a pointer to an application-defined structure needed inside the callback function.

Return Values

This method supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

S_OK

The object was drawn successfully.

OLE_E_BLANK

No data to draw from.

DRAW_E_ABORT

Draw operation aborted.

VIEW_E_DRAW

Error in drawing.

DV_E_LINDEX

Invalid value for lindex; currently only -1 is supported.

DV_E_DVASPECT

Invalid value for dwAspect.

OLE_E_INVALIDRECT

Invalid rectangle.

Remarks

A container application issues a call to IViewObject::Draw to create a representation of a contained object. This method draws the specified piece (lindex) of the specified view (dwAspect and pvAspect) on the specified device context (hdcDraw). Formatting, fonts, and other rendering decisions are made on the basis of the target device specified by the ptd parameter.

There is a relationship between the dwDrawAspect value and the lprcbounds value. The lprcbounds value specifies the rectangle on hdcDraw into which the drawing is to be mapped. For DVASPECT_THUMBNAIL, DVASPECT_ICON, and DVASPECT_SMALLICON, the object draws whatever it wants to draw, and it maps it into the space given in the best way. Some objects might scale to fit while some might scale to fit but preserve the aspect ratio. In addition, some might scale so the drawing appears at full width, but the bottom is cropped. The container can suggest a size via IOleObject::SetExtent, but it has no control over the rendering size. In the case of DVASPECT_CONTENT, the Draw implementation should either use the extents given by IOleObject::SetExtent or use the bounding rectangle given in the lprcBounds parameter.

For newer objects that support optimized drawing techniques and for windowless objects, this method should be used as follows:

•	New drawing aspects are supported in dwAspect as defined in DVASPECT2.

•	The pvAspect parameter can be used to pass additional information allowing drawing optimizations through the DVASPECTINFO structure.

•	The Draw method can be called to redraw a windowless in-place active object by setting the lrpcBounds parameter to NULL. In every other situation, NULL is an illegal value and should result in an E_INVALIDARG error code. A windowless object uses the rectangle passed by the activation verb or calls IOleInPlaceSite::SetObjectRects instead of using this parameter. If the container passes a non-NULL value to a windowless object, the object should render the requested aspect into the specified device context and rectangle. A container can request this from a windowless object to render a second, non-active view of the object or to print the object. See the IOleInPlaceSiteWindowless interface for more information on drawing windowless objects.

•	For windowless objects, the dwAspect parameter only allows the DVASPECT_CONTENT, DVASPECT_OPAQUE, and DVASPECT_TRANSPARENT aspects.

•	For a windowless object, the hdcDraw parameter should be in MM_TEXT mapping mode with its logical coordinates matching the client coordinates of the containing window. For a windowless object, the device context should be in the same state as the one normally passed by a WM_PAINT message.

To maintain compatibility with older objects and containers that do not support drawing optimizations, all objects, rectangular or not, are required to maintain an origin and a rectangular extent. This allows the container to still consider all its embedded objects as rectangles and to pass them appropriate rendering rectangles in IViewObjectEx::Draw.

An object’s extent depends on the drawing aspect. For non-rectangular objects, the extent should be the size of a rectangle covering the entire aspect. By convention, the origin of an object is the top-left corner of the rectangle of the DVASPECT_CONTENT aspect. In other words, the origin always coincides with the top-left corner of the rectangle maintained by the object’s site, even for a non-rectangular object.

Note to Callers

The value of hicTargetDevice is typically an information context for the target device. However, it may be a full device context instead.

Note to Implementers

If you are writing an object handler (such as the default handler) that implements IViewObject::Draw by playing a metafile, you have to treat SetPaletteEntries metafile records in a special way because of Windows’ behavior. The Windows function PlayMetaFile sets these palette entries to the foreground. You must override this default by setting them to the background palette. Use EnumMetaFile to do this. Enhanced metafiles are always recorded with the background palette so there is no need to do it manually.

See Also

DVASPECT, DVASPECT2, DVASPECTINFO, IOleInPlaceSiteWindowless, OleDraw


IViewObject::Freeze

Freezes a certain aspect of the object’s presentation so that it does not change until the IViewObject::Unfreeze method is called. The most common use of this method is for banded printing.

HRESULT Freeze(

DWORD dwAspect,	//How the object is to be represented
LONG lindex,	//Part of the object of interest in the draw operation
void * pvAspect,	//Always NULL
DWORD * pdwFreeze	//Points to location containing an identifying key
);
Parameters

dwAspect

[in] Specifies how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. Valid values are taken from the enumeration DVASPECT. See the DVASPECT enumeration for more information.

lindex

[in] Portion of the object that is of interest for the draw operation. Its interpretation varies with dwAspect. See the DVASPECT enumeration for more information.

pvAspect

[in] Pointer to additional information about the view of the object specified in dwAspect. Since none of the current aspects support additional information, pvAspect must always be NULL.

pdwFreeze

[out] Pointer to where an identifying DWORD key is returned. This unique key is later used to cancel the freeze by calling IViewObject::Unfreeze. This key is an index that the default cache uses to keep track of which object is frozen.

Return Values

S_OK

The presentation was successfully frozen.

VIEW_S_ALREADYFROZEN

Presentation has already been frozen. The value of pdwFreeze is the identifying key of the already frozen object.

OLE_E_BLANK

Presentation not in cache.

DV_E_LINDEX

Invalid value for lindex; currently; only -1 is supported.

DV_E_DVASPECT

Invalid value for dwAspect.

Remarks

The IViewObject::Freeze method causes the view object to freeze its drawn representation until a subsequent call to IViewObject::Unfreeze releases it. After calling IViewObject::Freeze, successive calls to IViewObject::Draw with the same parameters produce the same picture until IViewObject::Unfreeze is called.

IViewObject::Freeze is not part of the persistent state of the object and does not continue across unloads and reloads of the object.

The most common use of this method is for banded printing.

While in a frozen state, view notifications are not sent. Pending view notifications are deferred to the subsequent call to IViewObject::Unfreeze.

See Also

DVASPECT, IViewObject::Unfreeze


IViewObject::GetAdvise

Retrieves the existing advisory connection on the object if there is one. This method simply returns the parameters used in the most recent call to the IViewObject::SetAdvise method.

HRESULT GetAdvise(

DWORD * pdwAspect,	//Pointer to where dwAspect parameter from previous SetAdvise call is returned
DWORD * padvf,	//Pointer to where advf parameter from previous SetAdvise call is returned
IAdviseSink ** ppAdvSink	//Indirect pointer to interface on an advise sink
);
Parameters

pdwAspect

[out] Pointer to where the dwAspect parameter from the previous SetAdvise call is returned. If this pointer is NULL, the caller does not permit this value to be returned.

padvf

[out] Pointer to where the advf parameter from the previous SetAdvise call is returned. If this pointer is NULL, the caller does not permit this value to be returned.

ppAdvSink

[out] Indirect pointer to an IAdviseSink interface on an advise sink. The connection to this advise sink must have been established with a previous SetAdvise call, which provides the pAdvSink parameter. If this pointer is NULL, there is no established advisory connection.

Return Values

This method supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

S_OK

The existing advisory connection was retrieved.

See Also

ADVF, IAdviseSink, IViewObject::SetAdvise


IViewObject::GetColorSet

Returns the logical palette that the object will use for drawing in its IViewObject::Draw method with the corresponding parameters.

HRESULT GetColorSet(

DWORD dwAspect,	//How the object is to be represented
LONG lindex,	//Part of the object of interest in the draw operation
void * pvAspect,	//Always NULL
DVTARGETDEVICE * ptd,	//Pointer to target device in a structure
HDC hicTargetDev,	//Information context for the target device
LOGPALETTE ** ppColorSet	//Indirect pointer to a structure
);
Parameters

dwAspect

[in] Specifies how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. Valid values are taken from the enumeration DVASPECT. See the DVASPECT enumeration for more information.

lindex

[in] Portion of the object that is of interest for the draw operation. Its interpretation varies with dwAspect. See the DVASPECT enumeration for more information.

pvAspect

[in] Pointer to additional information about the view of the object specified in dwAspect. Since none of the current aspects support additional information, pvAspect must always be NULL.

ptd

[in] Pointer to the DVTARGETDEVICE structure that describes the device for which the object is to be rendered. If NULL, the view should be rendered for the default target device (typically the display). A value other than NULL is interpreted in conjunction with hicTargetDev and hdcDraw. For example, if hdcDraw specifies a printer as the device context, ptd points to a structure describing that printer device. The data may actually be printed if hicTargetDev is a valid value or it may be displayed in print preview mode if hicTargetDev is NULL.

hicTargetDev

[in] Information context for the target device indicated by the ptd parameter from which the object can extract device metrics and test the device’s capabilities. If ptd is NULL, the object should ignore the hicTargetDev parameter.

ppColorSet

[out] Indirect pointer to where a LOGPALETTE structure is returned. The LOGPALETTE structure contains the set of colors that would be used if IViewObject::Draw were called with the same parameters for dwAspect, lindex, pvAspect, ptd, and hicTargetDev. A NULL pointer to the LOGPALETTE structure means that the object does not use a palette.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK

The set of colors was returned successfully.

S_FALSE

Set of colors is empty or the object will not give out the information.

OLE_E_BLANK

No presentation data for object.

DV_E_LINDEX

Invalid value for lindex; currently only -1 is supported.

DV_E_DVASPECT

Invalid value for dwAspect.

Remarks

The IViewObject::GetColorSet method recursively queries any nested objects and returns a color set that represents the union of all colors requested. The color set eventually percolates to the top-level container that owns the window frame. This container can call IViewObject::GetColorSet on each of its embedded objects to obtain all the colors needed to draw the embedded objects. The container can use the color sets obtained in conjunction with other colors it needs for itself to set the overall color palette.

The OLE-provided implementation of IViewObject::GetColorSet looks at the data it has on hand to draw the picture. If CF_DIB is the drawing format, the palette found in the bitmap is used. For a regular bitmap, no color information is returned. If the drawing format is a metafile, the object handler enumerates the metafile looking for a CreatePalette metafile record. If one is found, the handler uses it as the color set.

Note to Implementers

Object applications that rely on the default handler for drawing and that use metafiles for doing so should provide a SetPaletteEntries record when they generate their metafiles. If a SetPaletteEntries record is not found, the default object handler returns S_FALSE.

See Also

DVASPECT


IViewObject::SetAdvise

Sets up a connection between the view object and an advise sink so that the advise sink can be notified about changes in the object’s view.

HRESULT SetAdvise(

DWORD dwAspect,	//View for which notification is being requested
DWORD advf,	//Information about the advise sink
IAdviseSink * pAdvSink	//Pointer to the advise sink that is to receive change notifications
);
Parameters

dwAspect

[in] View for which the advisory connection is being set up. Valid values are taken from the enumeration DVASPECT. See the DVASPECT enumeration for more information.

advf

[in] Contains a group of flags for controlling the advisory connection. Valid values are from the enumeration ADVF. However, only some of the possible ADVF values are relevant for this method. The following table briefly describes the relevant values. See the ADVF enumeration for a more detailed description.

ADVF Value	Description
ADVF_ONLYONCE	Causes the advisory connection to be destroyed after the first notification is sent.
ADVF_PRIMEFIRST	Causes an initial notification to be sent  regardless of whether data has changed from its current state.
Note that the ADVF_ONLYONCE and ADVF_PRIMEFIRST can be combined to provide an asynchronous call to IDataObject::GetData.

pAdvSink

[out] Pointer to the IAdviseSink interface on the advisory sink that is to be informed of changes. A NULL value deletes any existing advisory connection.

Return Values

This method supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

S_OK

The advisory connection was successfully established.

OLE_E_ADVISENOTSUPPORTED

Advisory notifications are not supported.

DV_E_DVASPECT

Invalid value for dwAspect.

Remarks

A container application that is requesting a draw operation on a view object can also register with the IViewObject::SetAdvise method to be notified when the presentation of the view object changes. To find out about when an object’s underlying data changes, you must call IDataObject::DAdvise separately.

To remove an existing advisory connection, call the IViewObject::SetAdvise method with pAdvSink set to NULL.

If the view object changes, a call is made to the appropriate advise sink through its IAdviseSink::OnViewChange method.

At any time, a given view object can support only one advisory connection. Therefore, when IViewObject::SetAdvise is called and the view object is already holding on to an advise sink pointer, OLE releases the existing pointer before the new one is registered.

See Also

ADVF, IAdviseSink, IViewObject::GetAdvise


IViewObject::Unfreeze

Releases a previously frozen drawing. The most common use of this method is for banded printing.

HRESULT Unfreeze(

DWORD dwFreeze	//Contains key that determines view object to unfreeze
);
Parameter

dwFreeze

[in] Contains a key previously returned from IViewObject::Freeze that determines which view object to unfreeze.

Return Values

S_OK

The drawing was unfrozen successfully.

OLE_E_NOCONNECTION

Error in the unfreezing process or the object is currently not frozen.

See Also

IViewObject::Freeze


IViewObject2

The IViewObject2 interface is an extension to the IViewObject interface which returns the size of the drawing for a given view of an object. You can prevent the object from being run if it isn’t already running by calling this method instead of IOleObject::GetExtent.

Like the IViewObject interface, IViewObject2 cannot be marshaled to another process. This is because device contexts are only effective in the context of one process.

The OLE-provided default implementation provides the size of the object in the cache.

When to Implement

Object handlers and in-process servers that manage their own presentations implement IViewObject2 for use by compound document containers.

When to Use

A container application or object handler calls the GetExtent method in the IViewObject2 interface to get the object’s size from its cache.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IViewObject Methods	Description
Draw	Draws a representation of the object onto a device context.
GetColorSet	Returns the logical palette the object uses for drawing.
Freeze	Freezes the drawn representation of an object so it will not change until a subsequent Unfreeze.
Unfreeze	Unfreezes the drawn representation of an object.
SetAdvise	Sets up a connection between the view object and an advise sink so that the advise sink can receive notifications of changes in the view object.
GetAdvise	Returns the information on the most recent SetAdvise.
IViewObject2 Method	Description
GetExtent	Returns the size of the view object from the cache.


IViewObject2::GetExtent

Returns the size that the specified view object will be drawn on the specified target device.

HRESULT GetExtent(

DWORD dwAspect,	//View object for which the size is being requested
DWORD lindex,	//Part of the object to draw
DVTARGETDEVICE ptd,	//Pointer to the target device in a structure
LPSIZEL lpsizel	//Pointer to size of object
);
Parameters

dwAspect

[in] Requested view of the object whose size is of interest. Valid values are taken from the enumerations DVASPECT and from DVASPECT2. Note that newer objects and containers that support optimized drawing interfaces support the DVASPECT2 enumeration values. Older objects and containers that do not support optimized drawing interfaces may not support DVASPECT2.

lindex

[in] Portion of the object that is of interest. Currently only -1 is valid.

ptd

[in] Pointer to the DVTARGETDEVICE structure defining the target device for which the object’s size should be returned.

lpsizel

[out] Pointer to where the object’s size is returned.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK

The object’s extent was successfully returned.

OLE_E_BLANK

An appropriate cache is not available.

Remarks

The OLE-provided implementation of IViewObject2::GetExtent searches the cache for the size of the view object.

The GetExtent method in the IOleObject interface provides some of the same information as IViewObject2::GetExtent.

Note  This method must return the same size as DVASPECT_CONTENT for all the new aspects in DVASPECT2. IOleObject::GetExtent must do the same thing.

If one of the new aspects is requested in dwAspect, this method can either fail or return the same rectangle as for the DVASPECT_CONTENT aspect.

Note to Callers

To prevent the object from being run if it isn’t already running, you can call IViewObject2::GetExtent rather than IOleObject::GetExtent to determine the size of the presentation to be drawn.

See Also

DVASPECT, DVASPECT2, IOleObject::GetExtent, IViewObject


IViewObjectEx

The IViewObjectEx interface is an extension derived from IViewObject2 to provide support for:

•	enhanced, flicker-free drawing for non-rectangular objects and transparent objects

•	hit testing for non-rectangular objects

•	control sizing

Flicker free drawing

Containers can now choose between a variety of drawing algorithms, depending on their sophistication and the situation.

Flicker is created by redrawing the background before letting an object redraw its foreground as in the back to front drawing algorithm known as the Painter’s Algorithm. There are essentially two ways to avoid flickering:

•	Draw into an offscreen bitmap and then copy the resulting image to the screen in one chunk. This technique might require significant additional resources to store the offscreen image, depending on the size of the region to drawn, the resolution, and the number of colors.

•	Draw front to back, instead of back to front, excluding each rectangular area from the clipping region as soon as its has been painted. One benefit of this technique is that each pixel is painted only once. Speed depends essentially on the performance of the clipping support.

Each technique has advantages and disadvantages, depending on the specific situation. There is no single algorithm that is most efficient in all situations. Depending on the situation and their sophistication, containers may choose to use one or another, or a mix of both. The IViewObjectEx interface provides methods to support both techniques or a mixture of the two. Simple containers can implement a simplistic back to front painting algorithm directly to the screen. The speed is likely to be high but so will flicker. If flicker is to be reduced to a minimum, painting to an off-screen device context is the solution of choice. If memory consumption is a problem, containers can use clipping to reduce the use of off screen bitmaps.

To draw as flicker-free as possible without using an offscreen bitmap, the container will have to paint in two passes. The first pass is done front to back. During that pass, each object draws regions of itself that are cheap enough to clip out efficiently and that it can entirely obscure. These regions are known as opaque. After each object is done, the container clips out the regions just painted to ensure that subsequent objects will not modify the bits on the screen.

During the second pass, which occurs back to front, each object draws its remaining parts - irregular, oblique or in general difficult to clip out, such as text on transparent background. Such parts are known as transparent. At this point, the container is responsible for clipping out any opaque, already painted regions in front of the object currently drawing. The less painting during this second pass, the less flicker on the screen.

Clipping during the second pass may be very inefficient, since the clipping region needs to be recreated for every object that has something to draw. This might be acceptable if not too many overlapping objects have irregular or transparent parts. An object can tell its container ahead of time whether it wants to be called during this second pass or not.

If the container provides an offscreen bitmap to paint into, then it can skip the first pass and ask every object to render itself entirely during the second pass. In certain cases, the container may also decide than flicker is not a problem and use that same technique while painting directly on screen. For example, flicker might be acceptable when painting a form for the first time, but not when repainting.

Note  Although documented here two pass drawing is not currently utilized by any containers.

Hit testing for non-rectangular objects

The IViewEx interface supports hit detection for non-rectangular objects. Using the QueryHitPoint and QueryHitRect methods, the object can participate in the hit-test logic with the container.

Control Sizing

The IViewEx interface allows controls to provide sizing hints as the user resizes the control. The control can specify a minimum and maximum size and can specify the nearest good size to a size requested by the user.

When to Implement

Implement this interface on objects that need to support efficient flicker-free drawing, non-rectangular hit testing, or control sizing. This interface is derived from the IViewObject2 interface which, in turn, is derived from IViewObject.

All IViewObjectEx methods described in this document that take or return a position assume that the location is expressed in HIMETRIC units relative to the origin of the object.

When to Use

Containers call the methods of this interface to draw objects in an efficient, flicker free manner, test whether points or rectangles are within the object, or to resize controls.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IViewObject Methods	Description
Draw	Draws a representation of the object onto a device context.
GetColorSet	Returns the logical palette the object uses for drawing.
Freeze	Freezes the drawn representation of an object so it will not change until a subsequent Unfreeze.
Unfreeze	Unfreezes the drawn representation of an object.
SetAdvise	Sets up a connection between the view object and an advise sink so that the advise sink can receive notifications of changes in the view object.
GetAdvise	Returns the information on the most recent SetAdvise.
IViewObject2 Method	Description
GetExtent	Returns the size that the specified view object will be drawn on the specified target device.
IViewObjectEx Methods	Description
GetRect	Returns a rectangle describing a requested drawing aspect.
GetViewStatus	Returns information about the opacity of the object, and what drawing aspects are supported.
QueryHitPoint	Indicates whether a point is within a given aspect of an object.
QueryHitRect	Indicates whether any point in a rectangle is within a given drawing aspect of an object.
GetNaturalExtent	Provides sizing hints from the container for the object to use as the user resizes it.
See Also

IViewObject2


IViewObjectEx::GetNaturalExtent

Provides sizing hints from the container for the object to use as the user resizes it.

HRESULT GetNaturalExtent(

DWORD dwAspect,	//Requested drawing aspect
LONG lindex,	//Portion of object for draw operation
DVTARGETDEVICE* ptd,	//Pointer to structure describing target device
HDC hicTargetDev,	//Information context for ptd
DVEXTENTINFO* pExtentInfo,	//Structure specifying sizing data
LPSIZEL* pSizel,	//Pointer to sizing data returned by object
);
Parameters

dwAspect

[in] Requested drawing aspect. It can be any of the values from the DVASPECT enumeration.

lindex

[in] Indicates the portion of the object that is of interest for the draw operation. Its interpretation varies depending on the value in the dwAspect parameter. See the DVASPECT enumeration for more information.

ptd

[in] Pointer to the target device structure that describes the device for which the object is to be rendered. If NULL, the view should be rendered for the default target device (typically the display). A value other than NULL is interpreted in conjunction with hicTargetDev and hdcDraw. For example, if hdcDraw specifies a printer as the device context, the ptd parameter points to a structure describing that printer device. The data may actually be printed if hicTargetDev is a valid value or it may be displayed in print preview mode if hicTargetDev is NULL.

hicTargetDev

[in] Specifies the information context for the target device indicated by the ptd parameter from which the object can extract device metrics and test the device's capabilities. If ptd is NULL; the object should ignore the value in the hicTargetDev parameter.

pExtentInfo

[in] Pointer to DVEXTENTINFO structure that specifies the sizing data.

pSizel

[out] Pointer to sizing data returned by the object. The returned sizing data is set to -1 for any dimension that was not adjusted. That is if cx is -1 then the width was not adjusted, if cy is -1 then the height was not adjusted. If E_FAIL is returned indicating no size was adjusted then psizel may be NULL.

Return Values

S_OK

The sizing hints were successfully returned.

E_FAIL

This method is not implemented for the specified dwAspect, or the size was not adjusted.

E_NOTIMPL

This method was not implemented.

Remarks

There are two general approaches to sizing a control. The first approach gives the control responsibility for sizing itself; the second approach gives the container responsibility for sizing the control. The first approach is called autosizing. There are two alternatives involved in the second approach: content sizing and integral sizing.

The IViewObjectEx::GetNaturalExtent method supports both content and integral sizing. In content sizing, the container passes the DVEXTENTINFO structure to the object into which the object returns a suggested size. In integral sizing, the container passes a preferred size to the object in DVEXTENTINFO, and the object actually adjusts its height. Integral sizing is used when the user rubberbands a new size in design mode.

Autosizing typically occurs with objects such as the Label control which resizes if the autosize property was enabled and the associated text changed. Autosizing is handled differently depending on the state of the object.

If the object is inactive, the following occurs:

1.	The object calls IOleClientSite::RequestNewObjectLayout.

2.	The container calls IOleObject::GetExtent and retrieves the new extents

3.	The container calls IOleObject::SetExtent and adjusts the new extents.

If the object is active, the following occurs:

1.	The object calls IOleInPlaceSite::OnPosRectChange to specify that it requires resizing.

2.	The container calls IOleInPlaceObject::SetObjectRects and specifies the new size.

The values of the dwAspect parameter can be one of the following DVASPECT enumeration values:

DVASPECT_CONTENT

Provide a representation of the control so it can be displayed as an embedded object inside of a container. This value is typically specified for compound document objects. The presentation can be provided for the screen or printer.

DVASPECT_DOCPRINT

Provide a representation of the control on the screen as though it were printed to a printer using the Print command from the File menu. The described data may represent a sequence of pages..

DVASPECT_ICON

Provide an iconic representation of the control.

DVASPECT_THUMBNAIL

Provide a thumbnail representation of an object so it can be displayed in a browsing tool. The thumbnail is approximately a 120 by 120 pixel, 16-color (recommended) device-independent bitmap potentially wrapped in a metafile.

See Also

DVASPECT, DVEXTENTINFO, IOleClientSite::RequestNewObjectLayout, IOleInPlaceObject::SetObjectRects, IOleInPlaceSite::OnPosRectChange, IOleObject::GetExtent, IOleObject::SetExtent,


IViewObjectEx::GetRect

Returns a rectangle describing a requested drawing aspect.

HRESULT GetRect(

DWORD dwAspect,	//Requested drawing aspect
LPRECTL pRect	//Pointer to the rectangle
);
Parameters

dwAspect

[in] Drawing aspect requested.

pRect

[out] Pointer to the rectangle describing the requested drawing aspect.

Return Values

S_OK

The rectangle was successfully returned.

DV_E_DVASPECT

The method does not support the specified aspect. Either the object does not support the aspect requested or the aspect is not rectangular.

Remarks

This method returns a rectangle describing the specified drawing aspect. The returned rectangle is in HIMETRIC units, relative to the object’s origin. The rectangle returned depends on the drawing aspect as follows:

DVASPECT_CONTENT

Objects should return the bounding rectangle of the whole object. The top-left corner is at the object’s origin and the size is equal to the extent returned by IViewObject2::GetExtent.

DVASPECT_OPAQUE

Objects with a rectangular opaque region should return that rectangle. Others should fail and return error code DV_E_DVASPECT.

If a rectangle is returned, it is guaranteed to be completely obscured by calling IViewObject::Draw for that aspect. The container should use that rectangle to clip out the object’s opaque parts before drawing any object behind it during the back to front pass. If this method fails on an object with a non-rectangular opaque region, the container should draw the entire object in the back to front part using the DVASPECT_CONTENT aspect.

DVASPECT_TRANSPARENT

Objects should return the rectangle covering all transparent or irregular parts. If the object does not have any transparent or irregular parts, it may return DV_E_ASPECT. A container may use this rectangle to determine whether there are other objects overlapping the transparent parts of a given object.


IViewObjectEx::GetViewStatus

Returns information about the opacity of the object, and what drawing aspects are supported.

HRESULT GetViewStatus(

DWORD* pdwStatus,	//Pointer to the view status
);
Parameters

pdwStatus

[out] Pointer to the view status. This information is returned as a combination of the VIEWSTATUS enumeration values.

Return Values

S_OK

The view status was successfully returned. This method should never fail or return an error code.

Remarks

In order to optimize the drawing process, the container needs to be able to determine whether an object is opaque and whether it has a solid background. It is not necessary to redraw objects that are entirely covered by a completely opaque object. Other operations, such as scrolling for example, can also be highly optimized if an object is opaque and has a solid background.

The IViewObjectEx::GetViewStatus method returns whether the object is entirely opaque or not (VIEWSTATUS_OPAQUE bit) and whether its background is solid (VIEWSTATUS_SOLIDBKGND bit). This information may change in time. An object may be opaque at a given time and become totally or partially transparent later on, for example, because of a change of the BackStyle property. An object should notify its sites when it changes using IAdviseSinkEx::OnViewStatusChange so the sites can cache this information for high speed access.

Objects not supporting IViewObjectEx are considered to be always transparent.

The IViewObjectEx::GetViewStatus method also returns a combination of bits indicating which aspects are supported.

If a given drawing aspect is not supported, all IViewObjectEx methods taking a drawing aspect as an input parameter should fail and return E_INVALIDARG. The IViewObjectEx::GetViewStatus method allows the container to get back information about all drawing aspects in one quick call. Normally the set of supported drawing aspects should not change with time. However, if this was not the case, an object should notify its container using IAdviseSinkEx::OnViewStatusChange.

Which drawing aspects are supported is independent of whether the object is opaque, partially transparent, or totally transparent. In particular, a transparent object that does not support DVASPECT_TRANSPARENT should be drawn correctly during the back to front pass using DVASPECT_CONTENT. However, this is likely to result in more flicker.

See Also

IAdviseSinkEx::OnViewStatusChange, VIEWSTATUS


IViewObjectEx::QueryHitPoint

Indicates whether a point is within a given aspect of an object.

HRESULT QueryHitPoint(

DWORD dwAspect,	//Requested drawing aspect
LPRECT pRectBounds,	//Object bounding rectangle
POINTL ptlLoc,	//Hit location
LONG lCloseHint,	//Suggested distance considered close
DWORD* pHitResult	//Pointer to returned hit information
);
Parameters

dwAspect

[in] Requested drawing aspect.

pRectBounds

[in] Object bounding rectangle in client coordinates of the containing window. This rectangle is computed and passed by the container so that the object can meaningfully interpret the hit location.

ptlLoc

[in] Hit location in client coordinates of the containing window.

lCloseHint

[in] Suggested distance in HIMETRIC units that the container considers close. This value is a hint, and objects can interpret it in their own way. Objects can also use this hint to roughly infer output resolution to choose expansiveness of hit test implementation.

pHitResult

[out] Pointer to returned information about the hit expressed as the HITRESULT enumeration values.

Return Values

S_OK

The hit information was successfully returned in pHitResult.

E_FAIL

This method is not implemented for the requested aspect. Use DVASPECT_CONTENT instead.

Remarks

To support hit detection on non-rectangular objects, the container needs a reliable way to ask an object whether or not a given location is inside one of its drawing aspects. This function is provided by IViewObjectEx::QueryHitPoint.

Note that since this method is part of the IViewObjectEx interface, the container can figure whether an mouse hit is over an object without having to necessarily launch the server. If the hit happens to be inside the object, then it is likely that the object will be in-place activated and the server started.

Typically, the container first quickly determines whether a given location is within the rectangular extent of an object. If the location is within the rectangular extent of an object, the container calls IViewObjectEx::QueryHitPoint to get confirmation that the location is actually inside the object. The hit location is passed in client coordinates of the container window. Since the object may be inactive when this method is called, the bounding rectangle of the object in the same coordinate system is also passed to this method, similarly to what happens in IPointerInactive::OnInactiveSetCursor.

Possible returned values include:

•	outside, on a transparent region

•	close enough to be considered a hit (may be used by small or thin objects)

•	hit

QueryHitPoint is not concerned by the sub-objects of the object it is called for. It merely indicates whether the mouse hit was within the object or not.

QueryHitPoint can be called for any of the drawing aspects an object supports. It should fail if the it is not supported for the requested drawing aspect.

Transparent objects may wish to implement a complex hit-detection mechanism where the user can select either the transparent object or an object behind it, depending on where exactly the click happens inside the object. For example, a transparent TextBox showing big enough text may let the user select the object behind, for example, a bitmap, when the user clicks between the characters. For this reason, the information returned by QueryHitPoint includes indication about whether the hit happens on an opaque or transparent region.

An example of non-rectangular and transparent hit detection is a transparent circle control with an object behind it (a line in the example below):

The values shown are for hit tests against the circle; gray regions are not part of the control, but are shown here to indicate an area around the image considered close. Each object implements its own definition of close but is assisted by a hint provided by the container so that closeness can be adjusted as images zoom larger or smaller.

In the picture above, the points marked “Hit”, “Close” and “Transparent” would all be hits of varying strength on the circle, with the exception of the one marked “Transparent, (but for the line, close).” This illustrates the effect of the different strength of hits. Since the circle responds “transparent” while the line claims “close,” and transparent is weaker than close, the line takes the hit.

Note to Implementers

An object supporting IViewObjectEx is required to implement this method at least for the DVASPECT_CONTENT aspect. The object should not take any other action in response to this method other than to return the information; there should be no side-effects.

See Also

IPointerInactive::OnInactiveSetCursor, HITRESULT


IViewObjectEx::QueryHitRect

Indicates whether any point in a rectangle is within a given drawing aspect of an object.

HRESULT QueryHitRect(

DWORD dwAspect,	//Requested drawing aspect
LPRECT pRectBounds,	//Object bounding rectangle
LPRECT pRectLoc,	//Hit location
LONG lCloseHint,	//Suggested distance considered close
DWORD* pHitResult	//Pointer to returned hit information
);
Parameters

dwAspect

[in] Requested drawing aspect.

pRectBounds

[in] Object bounding rectangle in client coordinates of the containing window. This rectangle is computed and passed by the container so that the object can meaningfully interpret the hit location.

pRectLoc

[in] Hit test rectangle in specified in HIMETRIC units, relative to the top-left corner of the object.

lCloseHint

[in] Suggested distance in HIMETRIC units that the container considers close. This value is a hint, and objects can interpret it in their own way. Objects can also use this hint to roughly infer output resolution to choose expansiveness of hit test implementation.

pHitResult

[out] Pointer to returned information about the hit expressed as the HITRESULT enumeration values.

Return Values

S_OK

The hit information was successfully returned in pHitInfo.

E_FAIL

This method is not implemented for the requested aspect. Use DVASPECT_CONTENT instead.

Remarks

Containers may need to test whether an object overlaps a given drawing aspect of another object. They can determine whether the objects overlap by requesting a region or at least a bounding rectangle of the aspect in question. However, a quicker way to do this is to call IViewObjectEx::QueryHitRect to ask the object whether a given rectangle intersects one of its drawing aspects.

Note  Unlike IViewObjectEx::QueryHitPoint, this method does not return HITRESULT_TRANSPARENT or HITRESULT_CLOSE. It is strictly hit or miss, returning HITRESULT_OUTSIDE if no point in the rectangle is hit and HITRESULT_HIT if at least one point in the rectangle is a hit.

Note to Implementers

An object supporting IViewObjectEx is required to implement this method at least for the DVASPECT_CONTENT aspect. The object should not take any other action in response to this method other than to return the information; there should be no side-effects. If there is any ambiguity about whether a point is a hit, for instance due to coordinates not converting exactly, the object should return HITRESULT_HIT whenever any point in the rectangle might be a hit on the object. That is, it is permissible to claim a hit for a point that is not actually rendered, but never correct to claim a miss for any point that is in the rendered image of the object.

See Also

HITRESULT


OLE Registry Entries

To become functional, OLE servers and containers must add information to the system registry. Most of that information is stored in keys and named values under the HKEY_LOCAL_MACHINE\SOFTWARE\Classes and HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\OLE keys. This section discusses these  registry keys and information Orequired to support OLE functionality. For general information on the registry, the structure of registry entries, and registry functions, search for Registry topics in the Microsoft Win32 Programmer’s Reference.

Note that HKEY_CLASSES_ROOT is equivalent to  HKEY_LOCAL MACHINE\SOFTWARE\Classes and that these keys can be used interchangeably. HKEY_CLASSES_ROOT also provides compatibility with Windows 3.1 and Windows 95.

Installation and Setup

Your installation/setup program must add information to the registry, and its associated subkeys, if it is to perform any of the three following types of installations:

Installing an OLE server application.

Installing an OLE container/server application.

Installing a container application that allows linking to its embedded objects.

In all three cases, you must register OLE 2 library (DLL) information as well as application-specific information.

For information on registering COM servers, see Registering COM Servers..

OLE Registry Functions

For information about OLE registry functions, refer to the following API functions:

CoGetTreatAsClass

CoTreatAsClass

OleDoAutoConvert

OleGetAutoConvert

OleSetAutoConvert

SetConvertStg

GetConvertStg

OleRegGetUserType

OleRegEnumFormatEtc

OleRegGetMiscStatus

OleRegEnumVerbs

Registering OLE 2 Libraries

The OLE 2 libraries require that many internal interfaces be registered. If your installation program installs the OLE 2 libraries on a machine that does not already have them, it should register OLE 2-specific information during installation.

If your installation program does not install OLE 2 libraries when it finds more recent libraries on the user’s drive, it should not register the OLE 2 interface information.

Note  When checking the version stamp (using VER.DLL) on existing OLE 2 libraries to determine whether or not to replace them on the user’s hard drive, check on a per file basis.

Checking Registration During Run Time

An application should check its registration at application load time, noting the following issues:

•	If the CLSID(s) that the application services is not present in the registry, the application should register as it does during the original setup.

•	If the application’s CLSID is present, but has no OLE 2-related information in it, the application should register as it does during the original setup.

•	If the path containing server entries (LocalServer and LocalServer32, InprocServer and InprocServer32, and DefaultIcon) does not point to the location in which the application is currently installed, the application should rewrite the path entries to point to its current location.

 Specifying Unknown User Types

It is possible to facilitate product localization by adding a key to the registry. This key allows functions to return a specified string instead of a default value or “Unknown."

The OLE 2 default handler’s implementation of IOleObject::GetUserType first examines the registry by calling OleRegGetUserType. If the object’s class is not found in the registry, the User Type from the object’s IStorage instance is returned. If the class is not found in the object’s IStorage instance, the string “Unknown” is returned.

By inserting the

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\OLE2
\UnknownUserType = <usertype>

key in the registry, the IOleObject::GetUserType method returns the value of the string specified by <usertype>. This string can be localized for a different language user-type name, instead of using the “Unknown” string, for the User Type.

 Conventions Used in Examples

In the registry examples in this appendix, boldface indicates a literal standard key or subkey, <italics> indicates an application-supplied string or value, and <boldface-italics> indicates an application-supplied key or subkey. In the first example, “OLE1ClassName,” “OLE1UserTypeName,” and “CLSID” are all supplied by the application.


HKEY_LOCAL_MACHINE\SOFTWARE\Classes

The subkeys and named values associated with key contain information about an application that is needed to support OLE functionality. This information includes such topics as supported data formats, compatibility information, programmatic identifiers, distributed com, and controls.


AppID Key

Application identifiers (AppIDs), group the configuration options, a set of named-values, for one or more distributed COM objects into one centralized location in the registry. Distributed COM objects hosted by the same executable are grouped into one AppID to simplify the management of common security and configuration settings. The HKEY_LOCAL_MACHINE\SOFTWARE\Classes key corresponds to the HKEY_CLASSES_ROOT, which definition was retained for compatibility with earlier versions of OLE.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\AppID\
                                    {AppID_value}\named_value = value

Comments

AppIDs are located in a newly created registry key hierarchy. The AppID_value is a 128-bit Globally Unique Identifier (GUID) that uniquely identifies the AppID.

AppIDs are mapped to executables and classes using two different mechanisms.

Classes indicate their corresponding AppID in their CLSID key. A named-value “AppID” of type REG_SZ contains the string value corresponding to the AppID_value under the AppID sub-key. This mapping is used during activation.

Executables are registered under the AppID key in a named-value indicating the module name (such as “MYOLDAPP.EXE”). This named-value is of type REG_SZ and contains the stringized AppID associated with the executable. This mapping is used to obtain the default access permissions.

Named Values:

\RemoteServerName = value	Sets name of remote server
\ActivateAtStorage = value	Configures client to activate on same system as persistent storage
\LocalService = value	Sets the application as a Win32 service
\ServiceParameters = value	Sets parameters to be passed to a LocalService on invocation
\RunAs = value	Sets an application to run only as a given user.
\LaunchPermission = value	Sets an ACL that determines who can launch the application
\AccessPermission = value	Sets an ACL that determines access
See Also

CLSID key, OLE Registry Entries, Registering COM Servers


RemoteServerName

A server may install the RemoteServerName named-value on client machines to configure the client to request the object be run at a particular machine whenever an activation function is called for which a COSERVERINFO structure is not specified.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\APPID\
                                    {AppID_value}\RemoteServerName = server_name

Remarks

As described in the documentation for the CLSCTX enumeration and the COSERVERINFO structure, one of the parameters of the distributed COM activation is a pointer to a COSERVERINFO structure. When this value is not NULL, the information in the COSERVERINFO structure  overrides the setting of the RemoteServerName key for the function call.

RemoteServerName allows simple configuration management of client applications − they may be written without hard-coded server names, and can be configured by modifying the RemoteServerName registry values of the classes of objects they use.

See Also

CLSCTX enumeration, COSERVERINFO structure, CoCreateInstanceEx, CoGetInstanceFromFile, CoGetInstanceFromIStorage, Registering COM Servers


ActivateAtStorage

Servers can install this named-value on client machines. When this value is not overridden by certain parameters passed to distributed COM activation API functions, the ActivateAtStorage named-value configures the client to instantiate objects on the same machine as the persistent state they are using or from which they are initialized.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\APPID\
                                    {AppID_value}\ActivateAtStorage = value

Remarks

The ActivateAtStorage named-value can be set by the server to configure the client to instantiate its objects on the same machine as the persistent state used or from which the objects are initialized. The value is a REG_SZ; any value beginning with Y or y means that ActivageAtStorage should be used.

When a value is set for ActivateAtStorage, this becomes the default behavior in calls to the CoGetInstanceFromFile and CoGetInstanceFromIStorage functions, as well as to the file moniker implementation of IMoniker::BindToObject.

In all of these calls, specifying a COSERVERINFO structure overrides the setting of ActivateAtStorage for the duration of the function call. The caller can pass COSERVERINFO information to IMoniker::BindToObject through the BIND_OPTS2 structure.

The value set for ActivateAtStorage is also the default behavior when CLSCTX_REMOTE_SERVER is specified if no registry information for the class is installed on the client’s machine. Client applications written to take advantage of ActivateAtStorage may therefore require less administration.

The ActivateAtStorage capability provides a transparent way to allow clients to locate running objects on the same machine as the data that they use. This reduces network traffic, because the object performs local file-system calls instead of calls across the network.

See Also

CoGetInstanceFromFile, CoGetInstanceFromIStorage, IMoniker::BindToObject, COSERVERINFO structure, CLSCTX, Registering COM Servers


LocalService

Allows an object to be installed as a Win32 service.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\APPID\
                                    {AppID_value}\LocalService = service_name

Remarks

In addition to running as a local server executable (EXE), a COM object may also choose to package itself to run as a Win32 service when activated by a local or remote client. Win32 services support numerous useful and UI-integrated administrative features, including local and remote starting, stopping, pausing, and restarting, as well as the ability to establish the server to run under a specific user account and Window Station, and optionally interactive with the desktop.

An object written as a Win32 service is installed for use by OLE by establishing a LocalService named-value under its CLSID key and performing a standard service installation (refer to the Win32 documentation and the SECSVR distributed COM sample application for more information on writing, installing, and debugging Win32 services.). The LocalService named-value must be set to the service name − as configured in HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services − as the default REG_SZ value.

Additionally, when LocalService is set, any string assigned to the named REG_SZ value, ServiceParameters, will be passed on the command line to the service as it is being launched.

For example, the following keys register the c:\mydb\mydb.exe executable to launch as the MyDatabase service when activated remotely. When launched as a service, the process receives “-Service” on its command-line.

HKEY_CLASSES_ROOT\APPID\{c5b7ac20-523f-11cf-8117-00aa00389b71}\LocalService = MyDatabase

HKEY_CLASSES_ROOT\APPID\{c5b7ac20-523f-11cf-8117-00aa00389b71}\ServiceParameters = -Service

The service configuration is preferred in many situations where the capabilities of the local and remote service management APIs and user interface might be useful for the services that the object provides. For example, if the object is long-lived, or readily supports concepts such as starting, stopping, resetting, or pausing, leveraging the existing administrative framework of the service architecture should be an obvious choice.

Services can be dynamically configured using the ‘Services’ application in the Control Panel, and can be configured to run automatically when the machine boots, or to be launched when requested by a client application.

There are several additional points you should be aware of if you are implementing classes as services:

•	The LocalService named-value is used in preference to the LocalServer32 key for local and remote activation requests − if LocalService exists and refers to a valid service, the LocalServer32 key is ignored.

•	Currently only a single instance of a Win32 service may be running at a given time on a machine. OLE services must therefore register their class objects on launch using REGCLS_MULTIPLEUSE to support multiple clients.

•	OLE services configured to run automatically when a machine boots must include “RPCSS” in their list of dependent services in order to launch and initialize properly.

•	Although services may be configured to interact with the interactive user, they are always run in a separate window-station and desktop from the interactive user. This prevents service processes from being automatically terminated when the interactive user logs off.

See Also

ServiceParameters, Registering COM Servers


ServiceParameters

When an object is written as a Win32 service and installed for use by OLE through setting the LocalService named value under the AppID key, the ServiceParameters named-value can be set to pass the given parameter on the command line when the service is launched.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\APPID\
                                    {AppID_value}\ServiceParameters = parameter

Remarks

The parameter value for the ServiceParameters named-value is any REG_SZ string value. This string is passed on the command line to the service as it is being launched.

For example, the following keys register the c:\mydb\mydb.exe executable to launch as the MyDatabase service when activated remotely. When launched as a service, the process receives “-Service” on its command-line.

HKEY_CLASSES_ROOT\APPID\{c5b7ac20-523f-11cf-8117-00aa00389b71}\LocalService = MyDatabase

HKEY_CLASSES_ROOT\APPID\{c5b7ac20-523f-11cf-8117-00aa00389b71}\ServiceParameters = -Service

Refer to the Win32 SDK documentation about services and the SECSVR sample Distributed COM application for more information about writing, installing, and debugging Win32 services.

See Also

LocalService, Registering COM Servers


RunAs

Configures a class to run under a specific user account when activated by a remote client without being written as a Win32 service. To do this, the RunAs named-value is set for the class to a user-name and optionally a password. These are then used when the Service Control Manager launches its local server process.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\APPID\
                                    {AppID_value}\RunAs = value

Remarks

The value specifies the user name, and must either of the form username, domain\username, or the string Interactive User.

Classes configured to RunAs a particular user may not be registered under any other identity, so calls to CoRegisterClassObject with this CLSID will fail unless the process was launched by OLE on behalf of an actual activation request.

The user-name is taken from the RunAs named-value under the class’s AppID key. If the user-name is “Interactive User”, the server is run in the identity of the user currently logged on and is connected to the interactive desktop.

Otherwise, the password is retrieved from a secret and safe portion of the registry available only to administrators of the machine and to the system. The user-name and password are then used to create a logon-session  in which the server is run. When launched in this way, the user  runs with its own desktop and window-station, and does not share window-handles, the clipboard, or other UI elements with the interactive user or other user running in other user accounts.

To establish a password for a RunAs class, you must use the DCOMCNFG administrative tool installed in the system directory.

For RunAs identities used by DCOM servers, the user account specified in the value must have the rights to log on as a batch job. This right can be added using the NT User Manager, under Policies-User Rights. Click on the Show Advanced User Rights box, select log on as a batch job, and add the RunAs user account.

The RunAs value is not used for servers configured to be run as services.  COM services that wish to run under an identity other than LocalSystem should set the appropriate user name and password using the services control panel applet.

See Also

Registering COM Servers


LaunchPermission

Contains data describing the Access Control List (ACL) of the principals that can start new servers for this class. The LaunchPermission named-value may be added under any AppID key to limit activation by remote clients of specific classes.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\APPID\
                                    {AppID_value}\LaunchPermission = ACL

Remarks

The LaunchPermission named-value is REG_BINARY. Upon receiving a local or remote request to launch the server of this class, the ACL described by this value is checked while impersonating the client, and its success either allows or disallows the launching of the server. If this value does not exist, the machine-wide DefaultLaunchPermission value is checked in the same way as a default to determine if the class code can be launched.

See Also

DefaultLaunchPermission, Security in COM


AccessPermission

Contains data describing the Access Control List (ACL) of the principals that can access instances of this class. This ACL is only used by applications that do not call CoInitializeSecurity.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\APPID\
                                    {AppID_value}\AccessPermission = ACL

Remarks

This named-value is a REG_BINARY. It contains data describing the Access Control List (ACL) of the principals that can access instances of this class. Upon receiving a request to connect to an existing object of this class, the ACL is checked by the application being called while impersonating the caller. If the access-check fails the connection is disallowed. If this named-value does not exist, the machine-wide DefaultAccessPermission ACL is tested in an identical manner (see above) as a default to determine if the connection is to be allowed.

See Also

DefaultAccessPermission, Security in COM


CLSID Key

A CLSID is a globally unique identifier that identifies an OLE class object. If your server or container allows linking to its embedded objects, then you need to register a CLSID for each supported class of objects.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID =  <CLSID>

Value Entries

<CLSID>

Specifies a name that can be displayed in the user interface.

Remarks

The CLSID key contains information used by the default OLE handler to return information about a class when it is in the running state.

To obtain a CLSID for your application, you can use the UUIDGEN.EXE found in the \TOOLs directory of the OLE 2 Toolkit, or use CoCreateGuid.

The CLSID is a 128 bit number, spelled in hex, within a pair of brarces.

SubKeys and Named Values

\CLSID = <CLSID>

\<CLSID>	Human readable name
\AppID	Application identifiers
\AutoConvertTo	Automatic object class conversion
\AutoTreatAs	Assigns the TreatAs value.
\AuxUserType	Identifies object as a control
\Control	Displayable application name.
\Conversion	Conversion used by the Convert dialog
\DataFormats	Formats supported by applications.
\DefaultIcon	Provides default icon information
\InprocHandler	Registers a 16-bit handler DLL.
\InprocHandler32	Registers a 32-bit handler DLL.
\InprocServer	Registers a 16-bit in-process server DLL
\InprocServer32	Registers a 32-bit in-process server DLL
\Insertable	Indicates object is insertable in OLE 2 applications
\Interface	Associates interface name with IID
\LocalServer	Full path to a 16- or 32-bit application
\LocalServer32	Full path to a  32-bit application
\MiscStatus	Default status used for all aspects
\ProgID	Programmatic identifier for a class
\ToolBoxBitmap32	Module name and resourdeID for a 16 x 16 bitmap
\TreatAs	OlLE1 / OLE 2 compatibility.
\Verb	Verbs associated with an application
\Version	Version number of the control
See Also

CoCreateGuid


<CLSID>

A globally unique identifier (GUID) used to map information about a component class.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \<CLSID>= HumanReadableName

Value Entries

HumanReadableName

Specifies a name that can be displayed in the user interface.

Remarks

COM uses the information mapped by the CLSID to locate and create an instance the object associated with the CLISID.

See Also

CoCreateGuid


AppID

Associate an AppID with a CLSID.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \AppID = <CLSID>

Value Entries

<CLSID>

The AppID to associate with this CLSID.

See Also

AppID


AutoConvertTo

Specifies the automatic conversion of a given class of objects (ClsidOld) to a new class of objects (pClsidNew).

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \AutoConvertTo = <CLSID>

Value Entries

<CLSID>

The class identifier of the object to which a given object or class of objects should be converted.

Remarks

This key is typically used to automatically convert files created by an older version of an application to a newer version of the application.

See Also

OleGetAutoConvert, OleDoAutoConvert, OleSetAutoConvert


AutoTreatAs

Automatically sets the CLSID for the TreatAs key to the specified value.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \AutoTreatAs = <CSID>

Value Entries

MCLSID>

The CLSID that will automatically be assigned to the TreatAs entry.

See Also

CoTreatAsClass


AuxUserType

Specifies an application’s short display name and application names.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \AuxUserType
        \2 = <ShortDisplayName>
        \3 = <ApplicationName>

Value Entries

<ShortDisplayName>

Specifies an application’s short display name, used in menus, including pop-ups.

<ApplicationName>

Specifies an application name, used in the Results field of the Paste Special dialog box.

Remarks

The recommended maximum length for the short display name is 15 characters. For example:

HKEY_CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \AuxUserType\2 = In-Place Outline

The application name should contain the actual name of the application (such as “Acme Draw 2.0”). For example:

HKEY_CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \AuxUserType\3 = Ole 2 In-Place Server

See Also

IOleObject::GetUserType


Control

Identifies an object as an OLE Control.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \Control

Remarks

This optional entry is used  by containers to fill in dialog boxes. The container uses this subkey to determine whether to include an object in a dialog box that displays OLE Controls.. A control can omit this entry if it is only designed to work with a specific container and thus does not wish to be inserted in other containers.


Conversion

Used by the Convert Dialog to determines the formats an application can read and write.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \Conversion
        \Readable
            \Main = <forma>t, ...
        \ReadWritable
            \Main = <format>, ...

Value Entries

<format>

The file format an application can read (convert from).

<format>

The file format an application can read and write (activate as).

Remarks

Conversion information is used by the Convert dialog box to determine what formats an application can read and write. A comma-delimited file format is indicated by a number if it is one of the Clipboard formats defined in WINDOWS.H. A string indicates the format is not one defined in WINDOWS.H (private). In this case, the readable and writable format is CF_OUTLINE (private).

The following is a \Readable entry:

KEY_CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \Conversion\Readable\Main = Outline,1

The following is a \ReadWritable entry:

HKEY_CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \Conversion\Readwritable\Main = Outline,1


DataFormats

Specifies the default and main data formats supported by an application.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \DataFormats
            \DefaultFile = <defaultfile/objectformat>
            \GetSet
                 \ n = <default formats for EnumFormatEt>

Value Entries

<default file/object format>

Specifies the default, main file or object format for objects of this class.

<default formats for EnumFormatEtc>

Specifies a list of formats for default implementations of EnumFormatEtc, where <n> is a zero-based integer index. For example, <n> = <format ,aspect, medium, flag>, where format is a clipboard format, aspect is one or more members of DVASPECT, medium is one or more members of TYMED, and flag is one or more members of DATADIR.

Remarks

Information associated with this entry is used by: IDataObject::GetData, IDataObject::SetData and IDataObject::EnumFormatEtc methods.

The values defined in the following example entry are CF_TEXT, DVASPECT_CONTENT, TYMED_HGLOBAL, and DATADIR_GET | DATADIR_SET.

HKEY_CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \DataFormats\GetSet\0 = 1,1,1,3

The values defined in the following entry are: CF_METAFILEPICT DVASPECT_CONTENT, TYMED_MFPICT, DATADIR_GET.

HKEY_CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \DataFormats\GetSet\1 = 3,1,32,1

The values defined in the following entry are: 2 = cfEmbedSource, DVASPECT_CONTENT, TYMED_ISTORAGE, and DATADIR_GET.

HKEY_CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \DataFormats\GetSet\2 = Embed Source,1,8,1

The values defined in the following entry are: 3 = cfOutline, DVASPECT_CONTENT, TYMED_HGLOBAL, and DATADIR_GET | DATADIR_SET.

HKEY_CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \DataFormats\GetSet\3 = Outline,1,1,3

The following entry declares that the default File Format supported by this application is CF_OUTLINE.

HKEY_CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \DataFormats\DefaultFile = Outline

See Also

IDataObject::GetData, IDataObject::SetData, IDataObject::EnumFormatEtc


DefaultIcon

Provides default icon information for iconic presentations of objects.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \DefaultIcon = <full path to exe, resoruce id>

Value Entries

<full path to exe, resource id>

Specifies the full path to the executable name of the object application and the resourceID of the icon within the executable.

Remarks

DefaultIcon identifies the icon to use when, for  example, a control is minimized to an icon. This entry contains the full path to the executable name of the server application and the resourceID of the icon within the executable. Applications can use the information provided by DefaultIcon to obtain an icon handle with ExtractIcon.

HKEY_CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \DefaultIcon = c:\samp\isvrotl.exe,0

See Also

ExtractIcon


InprocHandler

Specifies whether or not an application uses a custom handler.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \InprocHandler = <handler.dll>

Value Entries

<handler.dll>

Specifies the custom handler used by the application.

Remarks

If A custom handler is not used, the entry should be set to OLE2.DLL, as shown in the following example.

HKEY_-CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \InprocHandler = ole2.dll

If a container is searching the registry for an InprocHandler, the 16-bit version has priority with a 16-bit container, and the 32-bit version has priority with a 32-bit container.

See Also

InprocHandler32


InprocHandler32

Specifies whether or not an application uses a custom handler.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \InprocHandler32 = <handler.dll>

Value Entries

<handler.dll>

Specifies the custom handler used by the application.

Remarks

If A custom handler is not used, the entry should be set to OLE32.DLL, as shown in the following example.

HKEY_-CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \InprocHandler = ole32.dll

If a container is searching the registry for an InprocHandler, the 16-bit version has priority with a 16-bit container, and the 32-bit version has priority with a 32-bit container.

See Also

InprocHandler


InprocServer

Specifies the path to the inprocess-server DLL.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \InprocServer = <full path>

Value Entries

<full path>

Specifies the path to the inprocess server DLL.

Remarks

The InprocServer entry is relatively rare for insertable classes.

If a container is searching the registry for an InprocServer, the 16-bit version has priority with a 16-bit container, and 32-bit version has priority with a 32-bit container.

See Also

InprocServer32


InprocServer32

Registers a 32-bit in-process server DLL and specifies the threading model.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \InprocServer32 =  <path to 32-bit inproc server dll>
            \ThreadingModel = <threading model>

Value Entries

<path to 32-bit inproc server dll>

Specifies the path to the 32-bit inproc server.

<threading model>

Specifies the threading model. In-process servers do not CoInitialize call or CoInitializeEx; they must use the registry to specify an applications threading model. Threading models used for this purpose are:

•	ThreadingModel = no value specified: Supports single threading model.

•	ThreadingModel=Apartment. Supports apartment model.

•	ThreadingModel=Both. Supports apartment model and free threading.

•	ThreadingModel=Free. Supports only free threading...

Currently the ThreadingModel value must be the same for all objects

provided by an inproc server.

Remarks

For a 32-bit InprocServer, the required entries are InprocHandler32, InprocServer, InprocServer32, and Insertable. Note that InprocServer entry provides backward compatibility. If it is missing, the class will still work, but can’t be inserted in 16-bit applications.

If a container is searching the registry for an InprocServer, the 16-bit version has priority with a 16-bit container, and 32-bit version has priority with a 32-bit container.

The required entries for 32-bit InprocServers are InprocHandler32, InprocServer, InProcServer32, and Insertable. Note that LocalServer and InprocServer entries provide backward compatibility. If they are missing, the class will work, but cannot be inserted into 16-bit applications.

See Also

InprocServer, CoInitialize, CoInitializeEx


Insertable

Indicates that objects of this class should appear in the Insert Object dialog box’s list box when used by OLE 2 container applications.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \Insertable

Remarks

This key is a required entry for 32-bit OLE applications whose objects can be inserted into existing 16-bit applications. Existing 16-bit applications look in the registry for this key, which informs the application that the server supports embeddings. If the Insertable key exists, 16-bit applications may also attempt to verify that the server exists on the machine. 16-bit applications typically will retrieve the value of the LocalServer key from the class and check to see if it is a valid file on the system. Therefore, for a 32-bit application to be insertable by a 16-bit application, the 32-bit application should register the LocalServer subkey in addition to registering LocalServer32.

Used with controls, this entry indicates that an object can act only as an in-place embedded object with no special control features. Objects that have this key appear in the Insert Object dialog box fo their container.  When used with controls, this entry also indicates the control has been tested with non-control containers. This entry is also optional and can be omitted when a control is not designed to work with older containers that do not understand controls.

Note that this key is not present for internal classes like the moniker classes.

See Also

ProgID


Interface

An optional entry that specifies all interface IDs (IIDs) supported by the associated class.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\Interface
    \<IID> = <name of interface1>
    \<IID> = <name of interface2>
    \...

Value Entries

<name of interface1>, <name of interface2>, ...

Interfaces supported by this class.

Remarks

If an interface name is not present in this list, then the interface can never be supported by an instance of this class.

See Also

Interface


LocalServer

Specifies the full path to a 16-bit local server application.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \LocalServer = <full path>

Value Entries

<full path>

Specifies the full path to the local server, and can include command-line arguments.

Remarks

OLE 2 appends the “-Embedding” flag to the string, so the application that uses flags must parse the whole string and check for the -Embedding flag.

HKEY_CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \LocalServer = c:\samp\isvrotl.exe

To run an OLE object server in a separate memory space (Windows NT 3.5 and above only), change the LocalServer key in the registry for the CLSID to the following:

cmd /c start /separate <path.exe

If a container is searching the registry for a local server, a 32-bit local server has priority over a 16-bit local server.

See Also

LocalServer32


LocalServer32

Specifies the full path to a 32-bit local server application.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \LocalServer32 = <full path>

Value Entries

<full path>

Specifies the full path to the 32-bit local server, and can include command-line arguments.

Remarks

OLE 2 appends the “-Embedding” flag to the string, so the application that uses flags will need to parse the whole string and check for the -Embedding flag.

HKEY_CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \LocalServer32 = c:\samp\isvrotl.exe

When OLE starts a 32-bit local server, the server must register a class object within an elapsed time set by the user. By default, the elapsed time value must be at least five minutes, in milliseconds, but cannot exceed the number of milliseconds in 30 days. Applications typically should not set this value which is in the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\OLE2\ServerStartElapsedTime entry.

The required entries for 32-bit local servers are InprocHandler32, LocalServer, LocalServer32, and Insertable.

If a container is searching the registry for a local server, a 32-bit local server has priority over a 16-bit local server.

See Also

LocalServer


MiscStatus

Specifies how to create and display an object.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \MiscStatus = <object description>
        \n = value

Value Entries

object description

The value or combination of values from OLEMISC that describe the object.

value

Specifies a value from the OLEMISC enumeration.

Remarks

Information used to describe objects is found in the OLEMISC enumeration.

The following is an example of a MiscStatus entry. Refer to the IOleObject::GetMiscStatus method description for information on the different settings.

HKEY_CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \MiscStatus = 2

See Also

IOleObject::GetMiscStatus, OLEMISC


ProgID

Associates a ProgID with a CLSID.

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \ProgID = <programatic identifier>

Value Entries

<programatic identifier>

Specifies the ProgID: <vendor>.<component>.<version>.

Remarks

Every insertable object class has a <ProgID>. For information on creating a <ProgID>, see the <ProgID> key.

See Also

VersionIndependentProgID, <ProgID>


ToolBoxBitmap32

Identifies the module name and resourdeID for a 16 x 16 bitmap to use for the face of a toolbar or toolbox button.

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \ToolBoxBitmap32 = <filename>.<ext>, resourceID

Value Entries

<filename>.<ext>, resourceID>

Specifies the module name and the resorucID for the bitmap.

Remarks

The standard Windows icon size is too large to be used for this purpose. This specifically supports control containers that have a design mode in which one selects controls and places them on a form being designed. For example, in Visual Basic, the control’s icon is displayed in the Visual Basic Toolbox during design mode.


TreatAs

Specifies the CLSID of a class that can emulate the current class.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \TreatAs = <CLSID>

Value Entries

<CLSID>

Class that is to perform the emulation.

Remarks

Emulation is the ability of one application to open and edit an object of a different class, while retaining the original format of the object.

See Also

CoTreatAsClass, CoGetTreatAsClass, AutoTreatAs, IOleObject::EnumVerbs


Verb

Specifies the verbs to be registered for an application.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \Verb
        \1 = <verb1>
        \2 = <verb2>
        \3 =

Value Entries

<verb1>, <verb2>, ...

Each value specifies a verb, and its associated menu and verb flags. Each verb is specified by its own NamedValue / Value pair, as in verb number = <name, menu flag, verb flag> For example:
    \Verb
         0 = &Edit, 0, 2    // primary verb; on menu, possibly dirties object,
         1 = &Play, 0, 3   // other verb; on menu; leaves object clean
        -3 = Hide,  0, 1    // pseudo verb, hides window; not on menu, opt.
        -2 = Open, 0, 1    // pseudo verb, opens in sep. window; not on menu, opt.
        -1 = Show, 0, 1   // pseudo verb, show in preferred state; not on menu, opt.

See IOleObject::DoVerb for general information about verbs, descriptions of OLE predefined verbs, and positive and negative verbs, plus other material.

Remarks

Verbs must be numbered consecutively. The first value after the verb string describes how the verb is appended by an AppendMenu function call.

The second value indicates whether the verb will dirty the object. It also indicates whether the verb should appear in the menu, as defined by OLEVERBATTRIB enumeration, used by the OLEVERB structure.

For still more information, see IOleObject::EnumVerbs and OleRegEnumVerbs.

Following are two example entries:

Verb 0: “Edit”, MF_UNCHECKED | MF_ENABLED, no OLEVERATTRIB flags:

HKEY_CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \Verb\0 = &Edit,0,0

Verb 1: “Open”, MF_UNCHECKED | MF_ENABLED, no OLEVERATTRIB flags:

HKEY_CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \Verb\1 = &Open,0,0

See Also

IOleObject::EnumVerbs, OleRegEnumVerbs, AppendMenu, OLEVERB, OLEVERBATTRIB


Version

Specifies the version number of the control.

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
    \Version = <VersionNumber>

Value Entries

<ersionNumber>

The version number of the control.

Remarks

The version number should match the version of the type library associated with the control.


ProgID Key

A ProgID, or programmatic identifier, is a registry entry that can be associated with a CLSID. The format of a ProgID is <Vendor>.<Component>.<Version>, separated by periods and with no spaces, as in Word.Document.6. Like the CLSID, the ProgID identifies a class, but with less precision.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\<ProgID> =

You can use a ProgID in programming situations where it is not possible to use a CLSID. ProgIDs should not appear in the user interface. ProgIDs are not guaranteed to be unique so they can be used only where name collisions are manageable.

The <ProgID> must:

•	Have no more than 39 characters.

•	Contain no punctuation (including underscores) except one or more periods.

•	Not start with a digit.

•	Be different from the class name of any OLE 1 application, including the OLE 1 version of the same application, if there is one.

Since the <ProgID> should not appear in the user interface, you can obtain a displayable name by calling IOleObject::GetUserType. Also, see OleRegGetUserType>

The value of the <ProgID> is a human readable name such as Microsoft Word Document, and is displayed in dialog boxes.

SubKeys and Named Values

\<ProgID> = <HumanReadableNamen>

\CLSID	Object’s CLSID
\Insertable	Indicates that class is insertable in OLE 2 containers
\Protocol	Indicates class is insertable in OLE 1 container
\Shell	Windows 3.1 File Manager information
See Also

IOleObject::GetUserType, OleRegGetUserType


CLSID

Associates a ProgID with a CLSID.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\ProgID
    \CLSID = <CLSID>

Value Entries

<CLSID>

The object’s CLSID.

See Also

GetClassFile


Insertable

Indicates that this class is insertable in OLE 2 containers.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\ProgID
    \Insertable

Remarks

This is a required entry for objects that are insertable in OLE 2 containers.


Protocol

Indicates that this OLE 2 class is insertable in OLE 1 containers.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\ProgID
    \Protocol
        \StdFileEditing
            \Server = <full path to OLE 2 server app>
            \Verb =
                \0 = <verb value0>
                \1 = <verb value>
                \, ...

Value Entries

<full path to OLE 2 server app>

Specifies the full path to the OLE 2 server application.

<verb value>

The primary verb; must start with zero.

<verb value>, ...

Additional verb, numbered consecutively.

Remarks

The StdFileEditing entry is specifies OLE 1 compatibility information. It should be present only if, objects of this class are insertable in OLE 1 containers.


Shell

Provides Windows 3.1 shell printing and File Open information.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\ProgID
    \Shell
        \Open
            \command = <path to application exe %1>
        \Print
            \command = <path to application exe %1>

Value Entries

<path to application exe %1>

Specifies the path to the executable.

Remarks

These entries should provide the path and filename of the application. The examples provided here are simple entries. More complex entries could contain DDE entries.

HKEY_CLASSES_ROOT\OLE2ISvrOtl\Shell\Print\Command =

    c:\svr\isvrotl.exe %1

HKEY_CLASSES_ROOT\OLE2ISvrOtl\Shell\Open\Command =

    c:\svr\isvrotl.exe %1


VersionIndependentProgID Key

The values associated with this key associate a ProgID with a CLSID. Used to determine the latest version of an object application.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes
    \<VersionIndependentProgID> = <Vendor>.<Component>
        \CLSID = <CLSID>
        \CurVer  = <ProgID>

Value Entries

<Vendor>.<Component>

The name of the latest version of the object application.

<CLSID>

The CLSID of the newest installed version of the class.

<ProgID>

The <ProgID> of the newest installed version of the class.

Remarks

The format or the <VersionIndependentProgID> is <Vendor>.<Component>, separated by periods, no spaces, and no version number. The version-independent ProgID, like the ProgID, can be registered with a human readable name.

Applications must register a version-independent programmatic identifier under the VersionIndependentProgID key. The <VersionIndependentProgID> refers to the application’s class, and does not change from version to version, instead remaining constant across all versions, for example, Microsoft Word Document. It is used with macro languages and refers to the currently installed version of the application’s class. The <VersionIndependentProgID> must correspond to the name of the latest version of the object application.

The <VersionIndependentProgID> is used when, for example, a container application creates  a chart or table with a toolbar button. In this situation the application can  use the <VersionIndependentProgID> to determine the latest version of the needed object application.

The <VersionIndependentProgID> is stored and maintained solely by application code. When given the VersionIndependentProgID, the CLSIDFromProgID function returns the CLSID of the current version.

You can use CLSIDFromProgID and ProgIDFromCLSID to convert between these two representations.

You can use IOleObject::GetUserType or OleRegGetUserType to change the identifier to a displayable string.

If A custom handler is not used, the entry should be set to OLE32.DLL, as shown in the following example.

HKEY_-CLASSES_ROOT\CLSID\{00000402-0000-0000-C000-000000000046}

    \InprocHandler = ole32.dll

In addition to the preceding registry entry, you should add the following corresponding entry under the CLSID key:

\CLSID
    \<CLSID>  = <human readable name>
        \<VersionIndependentProgID> = human readable name

See Also

ProgID, CLSIDFromProgID, ProgIDFromCLSID, IOleObject::GetUserType, OleRegGetUserType


File Extension Key

Associates a file extension with a ProgID, indicating that an OLE 2 application can handle requests from the Windows 3.1 File Manager.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes
    \<.ext> = <ProgID>

Value Entries

<ProgID>

The ProgID associated with

Remarks

The information contained in the file extension key is used by both File Manager and File Monikers. GetClassFile uses the file extension key to supply the associated CLSID.

See Also

GetClassFile


(Non-Compound) FileType Key

Used by GetClassFile to match patterns against various file bytes in a non-compound file.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\
    \FileType
        \<CLSID>
            \<n> = <offset, cb, mask, value>

Value Entries

<offset, cb, mask, value>

Offset and cb are limited to 16 bits. Offset is from the beginning or end of the file, with a negative value for offset being interpreted from the end of the file; cb is a the length in bytes. Together, these values represent a particular byte range in the file. mask is a bit mask used to perform a logical AND operation, using the byte range spedified by offsert and cb. The result of the AND operation is compared with If mask is omitted, it is assumed to all ones. offset and cb are decimal unless preceded by "0x". mask and pattern are always hex.

Remarks

Entries under the FileType key are used by the GetClassFile function to match patterns against various file bytes in a non-compound file. FileType has CLSID subkeys, each of which has a series of subkeys \0, \1, \2, ... These values contain a pattern that, if matched, should yield the indicated CLSID. See also the GetClassFile function.

Following are examples of FileType entries.
        \0 = 0, 4, FFFFFFFF, ABCD1234
where the first 4 bytes must be ABCD12 34, in that order, or
        \1 = 0, 4, FFFFFFFF, 9876543
where they must match 9876543, or .
        \2 = -4, 4, FEFEFEFE
where  the last four bytes in the file must be FEFEFEFE.

See Also

GetClassFile, File Extension


Interface Key

Registers new interfaces by associating an interface name with an interface ID (IID).

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Interface

If your application adds a new interface, the Interface key must be completed for OLE 2 to register the new interface. There must be one IID subkey for each new interface.

Note that you must use ProxyStubCLSID32 because the IID-to-CLSID mapping may be different for 16-and 32-bit interfaces. The IID-to-CLSID depends on the way the interface proxies are packaged into a set of proxy DLLs.

SubKeys and Named Values

\Interface

<IID>	Interface identifier
\BaseInterface	Interface derived from
\NumMethods	Number of methods
\ProsyStubCLSID	Maps IID to CLSiD (16-bit DLLs)
\ProsyStubCLSID32	Maps IID to CLSiD (32-bit DLLs)
See Also

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\Interface


<IID>

Associates an interface ID (IID) with a textual name for the interface.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes
    \Interface
        \<IID> = name of interface

Value Entries

<name of interface>

Textual name for a given interface. For example:
\{00000112-0000-0000-C000-0000000000-46} = IOleObject

Remarks

If your application adds a new interface, the interface key must be completed for OLE 2 to register the new interface. There must be one entry for each new interface.


BaseInterface

Identifies the interface from which the current interface is derived.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Interface
    \BaseInterface = <name of interface>

Value Entries

<name of interface>

Identifies the name of the interface from which the current interface is derived.


NumMethods

Contains the number of interfaces in the associated interface.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes
    \Interface
        \NumMethods =  <number of methods>

Value Entries

<number of methods>

Specifies the number of methods in the interface.


ProxyStubClsid

Maps an IID to a CLSID in 16-bit proxy DLLs.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes
    \Interface
        \ProxyStubClsid = <CLSID>

Value Entries

<CLSID>

Specifies the CLSID to map the IID to.

Remarks

If you add interfaces, you must use this entry to register them (16-bit systems) so that OLE can find the appropriate remoting code to establish interprocess communication.

See Also

ProxyStubClsid32


ProxyStubClsid32

Maps an IID to a CLSID in 32-bit proxy DLLs.

Registry Entry

HKEY_LOCAL_MACHINE\SOFTWARE\Classes
    \Interface
        \ProxyStubClsid32 = <CLSID>

Value Entries

<CLSID>

Specifies the CLSID to map the IID to.

Remarks

This is a required entry since the IID-to-CLSID mapping may be different for 16- and 32-bit interfaces. The IID-to-CLSID mapping depends on the way the interface proxies are packaged into a set of proxy DLLs.

If you add interfaces, you must use this entry to register them (32-bit systems)so that OLE can find the appropriate remoting code to establish interprocess communication.

See Also

ProxyStubClsid, IMarshal


HKEY_LOCAL_MACHINE\Software\Microsoft\OLE

The named-values under the HKEY_LOCAL_MACHINE\Software\Microsoft\OLE key control Distributed COM’s default launch and access permission settings and call-level security capabilities for applications that do not call CoInitializeSecurity. Only machine administrators and the system have full-access to this portion of the registry. All other users have only read-access.

HKEY_LOCAL_MACHINE\Software\Microsoft\OLE\named_value = value

Named Values:

\EnableDCOM = value	Sets the global activation policy for the machine
\DefaultLaunchPermission = value	Defines default ACL for the machine
\DefaultAccessPermission = value	Defines default access permission list for the machine
\LegacyAuthenticationLevel = value	Sets the default authentication level
\LegacyImpersonationLevel = value	Sets the default impersonation level
\LegacyMutualAuthentication = value	Determines if mutual authentication is enabled
\LegacySecureReferences = value	Determines if AddRef/Release invocations are secure
See Also

Security in COM


EnableDCOM

The EnableDCOM controls the global activation policies of the machine. Only machine administrators and the system have full-access to this portion of the registry. All other users have only read-access.

Registry Entry

HKEY_LOCAL_MACHINE\Software\Microsoft\OLE\
              EnableDCOM = value

Remarks

This named-value is a REG_SZ, and has two possible values.

N (or n)

No remote clients may launch servers or connect to objects on this machine. Local launching of class code and connecting to objects is allowed on a per-class basis according to the value and access permissions of the class’s AppID\{…}\LaunchPermission key and the global DefaultLaunchPermission key. See the description of these keys, below.

Y (or y)

Launching of servers and connecting to objects by remote clients is allowed on a per-class basis according to the value and access permissions of the class’s LaunchPermission named-value and the global DefaultLaunchPermission named-value.

See Also

LaunchPermission, DefaultLaunchPermission, Security in COM


DefaultLaunchPermission

Defines the Access Control List (ACL) of the principals that can launch classes that do not specify their own ACL through the LaunchPermission named-value

Registry Entry

HKEY_LOCAL_MACHINE\Software\Microsoft\OLE\named_value

Remarks

The value for the DefaultLaunchPermission named-value is a REG_BINARY that contains the Access Control List (ACL) of the principals who can launch classes on the current system. If the LaunchPermission named-value is set for a server, it takes precedence over the DefaultLaunchPermission named-value. Upon receiving a local or remote request to launch a server whose APPID key has no LaunchPermission value of its own, the ACL described by this value is checked while impersonating the client, and its success either allows or disallows the launching of the class code.

This entry supports a simple level of centralized administration of the default launching access to otherwise unadministered classes on a machine. For example, an administrator might use the DCOMCNFG tool to configure the system to allow read-access only for power-users of the machine. OLE would therefore restrict requests to launch class code to members of the power-users group. The administrator could subsequently configure launch permissions for individual classes to grant the ability to launch class code to other groups or individual users as needed.

The access-permissions in this named-value default to the following:

•	machine-administrators: allow-launch

•	SYSTEM: allow-launch

•	INTERACTIVE: allow-launch

See Also

LaunchPermission, Registering COM Servers


DefaultAccessPermission

Sets the Access Control List (ACL) of the principals that can access classes for which there is no AccessPermission setting. This ACL is only used by applications that don’t call CoInitializeSecurity and do not have an AccessPermission value under their AppID.

Registry Entry

HKEY_LOCAL_MACHINE\Software\Microsoft\OLE\DefaultAccessPermission = ACL

Remarks

The DefaultAccessPermission is a named-value that is set to a REG_BINARY that contains data describing the Access Control List (ACL) of the principals who can access classes for which there is no AccessPermission named-value. In this case, the server checks the ACL described by this value while impersonating the caller that is attempting to connect to the object, and its success determines if the access is allowed or disallowed. If the access-check fails, the connection to the object is disallowed.  If this named value does not exist, only the ID of the server and local system are allowed to call the server.

This key supports a simple level of centralized administration of the default connection access to running objects on a machine.

The access-permissions on this key default to the following:

•	machine-administrators: allow-access

•	SYSTEM: allow-access

•	INTERACTIVE: allow-access

See Also

AccessPermission, Registering COM Servers


LegacyAuthenticationLevel

Sets the default authentication level for applications that do not call CoInitializeSecurity.

Registry Entry

HKEY_LOCAL_MACHINE\Software\Microsoft\OLE\
              LegacyAuthenticationLevel= default_authentication_level

Remarks

LegacyAuthenticationLevel is a named-value is a REG_WORD that sets the default level of authentication for all applications which do not call CoInitializeSecurity. Values are from 1 through 6, and correspond to the RPC_C_AUTHN_LEVEL_xxx constants:

Value	Meaning
1	RPC_C_AUTHN_LEVEL_NONE
2	RPC_C_AUTHN_LEVEL_CONNECT
3	RPC_C_AUTHN_LEVEL_CALL
4	RPC_C_AUTHN_LEVEL_PKT
5	RPC_C_AUTHN_LEVEL_PKT_INTEGRITY
6	RPC_C_AUTHN_LEVEL_PKT_PRIVACY
When this named-value is not present, the default authentication level established by the system is 2 (RPC_C_AUTHN_CONNECT).

See Also

CoInitializeSecurity, RPC_C_AUTHN_LEVEL_xxx, Registering COM Servers


LegacyImpersonationLevel

Sets the default level of impersonation for applications that do not call CoInitializeSecurity.

Registry Entry

HKEY_LOCAL_MACHINE\Software\Microsoft\OLE\LegacyImpersonationLevel= default_impersonation_level

Remarks

The LegacyImpersonationLevel named-value is a REG_WORD that sets the default level of impersonation. The values, from 1 through 4, correspond to the values of the RPC_C_IMP_LEVEL_xxx constants.

Value	Meaning
1	RPC_C_IMP_LEVEL_ANONYMOUS
2	RPC_C_IMP_LEVEL_IDENTIFY
3	RPC_C_IMP_LEVEL_IMPERSONATE
4	RPC_C_IMP_LEVEL_DELEGATE
When this named-value is not present, the default impersonation level established by the system is 2 (RPC_C_IMP_LEVEL_IDENTIFY). NTLMSSP on Windows NT 4.0 supports only RPC_C_IMP_LEVEL_IDENTIFY and RPC_C_IMP_LEVEL_IMPERSONATE.

See Also

RPC_C_IMP_LEVEL_xxx, Registering COM Servers


LegacyMutualAuthentication

Determines whether mutual authentication is enabled.

Note  Mutual authentication is not supported and is not available by default with Windows NT 4.0. This named-value is only useful if the network administrator installs a security provider that supports mutual authentication.

Registry Entry

HKEY_LOCAL_MACHINE\Software\Microsoft\OLE\LegacyMutualAuthentication= value

Remarks

The LegacyMutualAuthentication named-value is a REG_SZ that provides the default setting for use of mutual authentication for all applications that do not call CoInitializeSecurity. Values of “Y” or “y” indicate that mutual authentication is enabled. Any other value or the lack of this named-value implies that mutual authentication is disabled.

See Also

CoInitializeSecurity, Registering COM Servers


LegacySecureReferences

Determines whether AddRef/Release invocations are secure for applications that do not call CoInitializeSecurity.

Registry Entry

HKEY_LOCAL_MACHINE\Software\Microsoft\OLE\LegacySecureReferences= ACL

Remarks

HKEY_LOCAL_MACHINE\Software\Microsoft\OLE

The LegacySecureReferences named-value is a REG_SZ that provides the default setting for securing IUnknown::AddRef and IUnknown::Release method invokations for all applications that do not call CoInitializeSecurity. Values of “Y” or “y” indicate that AddRef/Release is secured. Any other value or the lack of this named-value implies that AddRef/Release is not secured. Enabling secure references slows COM.

See Also

CoInitializeSecurity, Registering COM Servers


BIND_OPTS

Contains parameters used during a moniker-binding operation. The BIND_OPTS2 structure may be used in its place. A BIND_OPTS structure is stored in a bind context; the same bind context is used by each component of a composite moniker during binding, allowing the same parameters to be passed to all components of a composite moniker. See IBindCtx for more information about bind contexts.

If you’re a moniker client (that is, you use a moniker to acquire an interface pointer to an object), you typically do not need to specify values for the fields of this structure. The CreateBindCtx function creates a bind context with the bind options set to default values that are suitable for most situations; the BindMoniker function does the same thing when creating a bind context for use in binding a moniker. If you want to modify the values of these bind options, you can do so by passing a BIND_OPTS structure to the IBindCtx::SetBindOptions method. Moniker implementers can pass a BIND_OPTS structure to the IBindCtx::GetBindOptions method to retrieve the values of these bind options.

The BIND_OPTS structure is defined in OBJIDL.IDL.

typedef struct tagBIND_OPTS

{

    DWORD cbStruct;

    DWORD grfFlags;

    DWORD grfMode;

    DWORD dwTickCountDeadline;

} BIND_OPTS, *LPBIND_OPTS;

Members

cbStruct

Size of this structure in bytes (that is, the size of the BIND_OPTS structure).

grfFlags

Flags that control aspects of moniker binding operations. This value is any combination of the bit flags in the BINDFLAGS enumeration. New values may be defined in the future, so moniker implementations should ignore any bits in this field that they do not understand. The CreateBindCtx function initializes this field to zero.

grfMode

Flags that should be used when opening the file that contains the object identified by the moniker. The values are taken from the STGM enumeration. The binding operation uses these flags in the call to IPersistFile::Load when loading the file. If the object is already running, these flags are ignored by the binding operation. The CreateBindCtx function initializes this field to STGM_READWRITE.

dwTickCountDeadline

Clock time (in milliseconds, as returned by the GetTickCount function) by which the caller would like the binding operation to be completed. This member lets the caller limit the execution time of an operation when speed is of primary importance. A value of zero indicates that there is no deadline. Callers most often use this capability when calling the IMoniker::GetTimeOfLastChange method, though it can be usefully applied to other operations as well. The CreateBindCtx function initializes this field to zero.

Typical deadlines allow for a few hundred milliseconds of execution. This deadline is a recommendation, not a requirement; however, operations that exceed their deadline by a large amount may cause delays for the end user. Each moniker implementation should try to complete its operation by the deadline, or fail with the error MK_E_EXCEEDEDDEADLINE.

If a binding operation exceeds its deadline because one or more objects that it needs are not running, the moniker implementation should register the objects responsible in the bind context using the IBindCtx::RegisterObjectParam. The objects should be registered under the parameter names “ExceededDeadline”, “ExceededDeadline1”, “ExceededDeadline2”, and so on. If the caller later finds the object in the Running Object Table, the caller can retry the binding operation.

The GetTickCount function indicates the number of milliseconds since system startup, and wraps back to zero after 2^31 milliseconds. Consequently, callers should be careful not to inadvertently pass a zero value (which indicates no deadline), and moniker implementations should be aware of clock wrapping problems (see the GetTickCount function for more information).

See Also

BIND_OPTS2, BIND_FLAGS, CreateBindCtx, IBindCtx::SetBindOptions


BIND_OPTS2

Contains parameters used during a moniker-binding operation. A BIND_OPTS2 structure is stored in a bind context; the same bind context is used by each component of a composite moniker during binding, allowing the same parameters to be passed to all components of a composite moniker. See IBindCtx for more information about bind contexts. BIND_OPTS2 replaces the previously defined BIND_OPTS structure, including the previously defined members, and adding four new members.

Moniker clients (those using a moniker to acquire an interface pointer to an object) typically do not need to specify values for the fields of this structure. The CreateBindCtx function creates a bind context with the bind options set to default values that are suitable for most situations. The BindMoniker function does the same thing when creating a bind context for use in binding a moniker. If you want to modify the values of these bind options, you can do so by passing a BIND_OPTS2 structure to the IBindCtx::SetBindOptions method. Moniker implementers can pass a BIND_OPTS2 structure to the IBindCtx::GetBindOptions method to retrieve the values of these bind options.

The BIND_OPTS2 structure is defined in OBJIDL.IDL

typedef struct tagBIND_OPTS2 {

    DWORD           cbStruct;       //  sizeof(BIND_OPTS2)

    DWORD           grfFlags;

    DWORD           grfMode;

    DWORD           dwTickCountDeadline;

    DWORD           dwTrackFlags;

    DWORD           dwClassContext;

    LCID            locale;

    COSERVERINFO *  pServerInfo;

} BIND_OPTS2, * LPBIND_OPTS2;

Members

cbStruct

Size of this structure in bytes (that is, the size of the BIND_OPTS2 structure).

grfFlags

Flags that control aspects of moniker binding operations. This value is any combination of the bit flags in the BINDFLAGS enumeration. New values may be defined in the future, so moniker implementations should ignore any bits in this field that they do not understand. The CreateBindCtx function initializes this field to zero.

grfMode

Flags that should be used when opening the file that contains the object identified by the moniker. The values are taken from the STGM enumeration. The binding operation uses these flags in the call to IPersistFile::Load when loading the file. If the object is already running, these flags are ignored by the binding operation. The CreateBindCtx function initializes this field to STGM_READWRITE.

dwTickCountDeadline

Clock time (in milliseconds, as returned by the GetTickCount function) by which the caller would like the binding operation to be completed. This member lets the caller limit the execution time of an operation when speed is of primary importance. A value of zero indicates that there is no deadline. Callers most often use this capability when calling the IMoniker::GetTimeOfLastChange method, though it can be usefully applied to other operations as well. The CreateBindCtx function initializes this field to zero.

Typical deadlines allow for a few hundred milliseconds of execution. This deadline is a recommendation, not a requirement; however, operations that exceed their deadline by a large amount may cause delays for the end user. Each moniker implementation should try to complete its operation by the deadline, or fail with the error MK_E_EXCEEDEDDEADLINE.

If a binding operation exceeds its deadline because one or more objects that it needs are not running, the moniker implementation should register the objects responsible in the bind context using the IBindCtx::RegisterObjectParam. The objects should be registered under the parameter names “ExceededDeadline”, “ExceededDeadline1”, “ExceededDeadline2”, and so on. If the caller later finds the object in the Running Object Table, the caller can retry the binding operation.

The GetTickCount function indicates the number of milliseconds since system startup, and wraps back to zero after 2^31 milliseconds. Consequently, callers should be careful not to inadvertently pass a zero value (which indicates no deadline), and moniker implementations should be aware of clock wrapping problems (see the GetTickCount function for more information).

dwTrackFlags

A moniker can use this value during link tracking. If the original persisted data that the moniker is referencing has been moved, the moniker can attempt to reestablish the link by searching for the original data though some adequate mechanism. dwTrackFlags provides additional information on how the link should be resolved. See the documentation of the fFlags parameter in IShellLink::Resolve in the Win32 SDK for more details.

COM's file moniker implementation uses the shell link mechanism to reestablish links and passes these flags to IShellLink::Resolve.

dwClassContext

The class context, taken from the CLSCTX enumeration, that is to be used for instantiating the object. Monikers typically pass this value to the dwClsContext parameter of CoCreateInstance.

locale

The LCID value indicating the client’s preference for the locale to be used by the object to which they are binding. A moniker passes this value to IClassActivator::GetClassObject.

pServerInfo

Points to a COSERVERINFO structure. This member allows clients calling IMoniker::BindToObject to specify server information. Clients may pass a BIND_OPTS2 structure to the IBindCtx::SetBindOptions method. If a server name is specified in the COSERVERINFO struct, the moniker bind will be forwarded to the specified machine. SetBindOptions only copies the struct members of BIND_OPTS2, not the COSERVERINFO structure and the pointers it contains. Callers may not free any of these pointers until the bind context is released. COM's new class moniker does not currently honor the pServerInfo flag.

See Also

BIND_OPTS, BIND_FLAGS, CreateBindCtx, IBindCtx::SetBindOptions


CADWORD

The CADWORD structure is a counted array of DWORDs. It is used, for example, in the IPerPropertyBrowsing::GetPredefinedStrings method. The values returned in this counted array can be passed into the IPerPropertyBrowsing::GetPredefinedValue method to obtain the value corresponding to one of the predefined strings for a property.

typedef struct tagCADWORD

{

    ULONG      cElems;

    DWORD FAR* pElems;

} CADWORD;

Members

cElems

Size of the array pointed to by pElems.

pElems

Pointer to an array of DWORD values, each of which can be passed to the IPerPropertyBrowsing::GetPredefinedValue method to obtain the corresponding value for one of the property’s predefined strings. This array is allocated by the callee using CoTaskMemAlloc and is freed by the caller using CoTaskMemFree.

See Also

CALPOLESTR, IPerPropertyBrowsing::GetPredefinedStrings, IPerPropertyBrowsing::GetPredefinedValue


CALPOLESTR

The CALPOLESTR structure is a counted array of LPOLESTR types, that is, a counted array of pointers to strings. It is used, for example, in the IPerPropertyBrowsing::GetPredefinedStrings method to specify the predefined strings that a property can accept.

typedef struct tagCALPOLESTR

{

    ULONG         cElems;

    LPOLESTR FAR* pElems;

} CALPOLESTR;

Members

cElems

Size of the array pointed to by pElems.

pElems

Pointer to an array of LPOLESTR values, each of which corresponds to an allowable value that a particular property can accept. The caller can use these string values in user interface elements, such as drop-down list boxes. This array, as well as the strings in the array, are allocated by the callee using CoTaskMemAlloc and is freed by the caller using CoTaskMemFree.

See Also

IPerPropertyBrowsing::GetPredefinedStrings


CAUUID

The CAUUID structure is a Counted Array of UUID or GUID types. It is used, for example, in the ISpecifyPropertyPages::GetPages method to receive an array of CLSIDs for the property pages that the object wants displayed.

typedef struct tagCAUUID

{

    ULONG     cElems;

    GUID FAR* pElems;

} CAUUID;

Members

cElems

Size of the array pointed to by pElems.

pElems

Pointer to an array of UUID values, each of which specifies a CLSID of a particular property page. This array is allocated by the callee using CoTaskMemAlloc and is freed by the caller using CoTaskMemFree.

See Also

ISpecifyPropertyPages::GetPages


COAUTHINFO

Determines the authentication settings used while making a remote activation request from the client scm to the server.

typedef struct _COAUTHINFO

{

    DWORD               dwAuthnSvc;

    DWORD               dwAuthzSvc;

    [string] WCHAR *    pwszServerPrincName;

    DWORD               dwAuthnLevel;

    DWORD               dwImpersonationLevel;

    AUTH_IDENTITY  *    pAuthIdentityData;

    DWORD               dwCapabilities;

} COAUTHINFO;

Members

dwAuthnSvc

[in] A single DWORD value from the list of RPC_C_AUTHN_xxx constants indicating the authentication service to use. It may be RPC_C_AUTHN_NONE if no authentication is required.

dwAuthzSvc

[in] A single DWORD value from the list of RPC_C_AUTHZ_xxx constants indicating the authorization service to use. If you are using the NT authentication service, use RPC_C_AUTHZ_NONE.

pwszServerPrincName

Pointer to a WCHAR string that indicates the server principal name to use with the authentication service. If you are using RPC_C_AUTHN_WINNT, the principal name must be NULL.

dwAuthnLevel

[in] A single DWORD value from the list of RPC_C_AUTHN_LEVEL_xxx constants indicating the authentication level to use.

dwImpersonationLevel

[in] A single DWORD value from the list of RPC_C_IMP_LEVEL_xxx constants indicating the impersonation level to use. Currently, only RPC_C_IMP_LEVEL_IMPERSONATE and RPC_C_IMP_LEVEL_IDENTIFY are supported.

pAuthIdentityData

Pointer to an AUTH_IDENTITY structure that establishes the identity of the client. It is authentication-service specific. It is in the form of Windows NT's SEC_WINNT_AUTH_IDENTITY, as follows:

typedef struct _AUTH_IDENTITY

{

  [size_is(UserLength+1)] USHORT *        User;

  ULONG                    UserLength;

  [size_is(DomainLength+1)] USHORT *      Domain;

  ULONG                    DomainLength;

  [size_is(PasswordLength+1)] USHORT *    Password;

  ULONG                    PasswordLength;

  ULONG                    Flags;

} AUTH_IDENTITY;

dwCapabilities

[in] A DWORD defining flags to establish indicating the further capabilities of this proxy. Currently, no capability flags are defined.

Remarks

The values of the COAUTHINFO structure determine the authentication settings used while making a remote activation request from the client's scm to the server's scm.  This structure is defined by default for NTLMSSP, and is described only for cases that need it to allow DCOM activations to work correctly with security providers other than NTLMSSP, or to specify additional security information used during remote activations for interoperability with alternate implementations of distributed COM. Currently, the impersonation level must be set to RPC_C_IMP_LEVEL_IMPERSONATE, or the result will be a failed activation when the server is running WindowsNT.

See Also

COSERVERINFO


CONNECTDATA

The CONNECTDATA structure is the type enumerated through the IEnumConnections::Next method. Each structure describes a connection that exists to a given connection point.

typedef struct tagCONNECTDATA

{

    IUnknown*  pUnk;

    DWORD      dwCookie;

} CONNECTDATA;

Members

pUnk

Pointer to the IUnknown interface on a connected advisory sink. The caller must call IUnknown::Release using this pointer when the CONNECTDATA structure is no longer needed. The caller is responsible for calling Release for each CONNECTDATA structure enumerated through IEnumConnections::Next.

dwCookie

Connection where this value is the same token that is returned originally from calls to IConnectionPoint::Advise. This token can be used to disconnect the sink pointed to by a pUnk by passing dwCookie to IConnectionPoint::Unadvise.

See Also

IConnectionPoint, IEnumConnections


CONTROLINFO

The CONTROLINFO structure contains parameters that describe a control’s keyboard mnemonics and keyboard behavior. The structure is filled during the IOleControl::GetControlInfo method.

typedef struct tagCONTROLINFO

    {

    ULONG  cb;

    HACCEL hAccel;

    USHORT cAccel;

    DWORD  dwFlags;

    } CONTROLINFO;

Members

cb

Size of the CONTROLINFO structure.

hAccel

Handle to an array of Windows ACCEL structures, each structure describing a keyboard mnemonic. The array is allocated with the GlobalAlloc function. The control always maintains the memory for this array; the caller of IOleControl::GetControlInfo should not attempt to free the memory.

cAccel

Number of mnemonics described in the hAccel field. This value can be zero to indicate no mnemonics.

dwFlags

Flags that indicate the keyboard behavior of the control. The possible values are:

CTRLINFO_EATS_RETURN

When the control has the focus, it will process the Return key.

CTRLINFO_EATS_ESCAPE

When the control has the focus, it will process the Escape key.

When the control has the focus, the dialog box containing the control cannot use the Return or Escape keys as mnemonics for the default and cancel buttons.

See Also

IOleControl::GetControlInfo


COSERVERINFO

Identifies a remote machine resource to the new or enhanced activation functions. The structure is defined as follows in the Wtypes.h header file:

typedef struct  _COSERVERINFO

    {

    DWORD dwReserved1;

    LPWSTR pwszName;

    COAUTHINFO  *pAuthInfo;

    DWORD dwReserved2;

    }   COSERVERINFO;

Members

dwReserved1

Reserved for future use. Must be 0.

pszName

Pointer to the name of the machine to be used.

pAuthInfo

When using NTLMSSP, this value must be set to zero. A non-zero value, which is a pointer to a COAUTHINFO structure, would only be used when a security package other than NTLMSSP is being used.

dwReserved2

Reserved for future use. Must be 0.

Remarks

The COSERVERINFO structure is used primarily to identify a remote system in object creation functions. Machine resources are named using the naming scheme of the network transport. By default, all UNC (“\\server” or “server”) and DNS names (“server.com”, “www.foo.com”, or “135.5.33.19”) names are allowed.

If you are using the NTLMSSP security package, the default case, the pAuthinfo parameter should be set to zero. If you are a vendor supporting another security package, refer to COAUTHINFO. The mechanism described there is intended to allow DCOM activations to work correctly with security providers other than NTLMSSP, or to specify additional security information used during remote activations for interoperability with alternate implementations of DCOM. If pAuthInfo is set, those values will be used to specify the authentication settings for the remote call.  These settings will be passed to RpcBindingSetAuthInfoEx.

If the pAuthInfo field is not specified, any values in the AppID section of the registry will be used to override the following default authentication settings:

dwAuthnSvc	RPC_C_AUTHN_WINNT
dwAuthzSvc	RPC_C_AUTHZ_NONE
pszServerPrincName	NULL
dwAuthnLevel	RPC_C_AUTHN_LEVEL_CONNECT
dwImpersonationLevel	RPC_C_IMP_LEVEL_IMPERSONATE
pvAuthIdentityData	NULL
dwCapabilities	RPC_C_QOS_CAPABILITIES_DEFAULT
See Also

CLSCTX, CoGetClassObject, CoGetInstanceFromFile, CoGetInstanceFromIStorage, CoCreateInstanceEx, Locating a Remote Object


DVASPECTINFO

The DVASPECTINFO structure is used in the IViewObject::Draw method to optimize rendering of an inactive object by making more efficient use of the GDI. The pvAspect parameter in IViewObject::Draw points to this structure. It is defined as follows:

typedef struct STRUCT tagDVASPECTINFO

{

    UNIT  cb;

    DWORD  dwFlags;

} DVASPECTINFO;

Members

cb

Size of the structure in bytes. The size includes this member as well as the dwFlags member.

dwFlags

A value taken from the DVASPECTINFOFLAG enumeration.

See Also

DVASPECTINFOFLAG


DVEXTENTINFO

The DVEXTENTINFO structure is used in IViewObjectEx::GetNaturalExtent.

typedef struct tagDVEXTENTINFO

{

    ULONG cb;

    DWORD dwExtentMode;

    SIZEL sizelProposed;

}DVEXTENTINFO;

Members

cb

Size of the structure in bytes. The size includes this member as well as the dwExtentMode and sizelProposed members.

dwExtentMode

Indicates whether the sizing mode is content or integral sizing. See the DVEXTENTMODE enumeration for these values.

sizelProposed

Specifies the proposed size in content sizing or the preferred size in integral sizing.

See Also

DVEXTENTMODE


DVTARGETDEVICE

Use the DVTARGETDEVICE structure to specify information about the target device for which data is being composed. DVTARGETDEVICE contains enough information about a Windows target device so a handle to a device context (hDC) can be created using the Windows CreateDC function.

typedef struct tagDVTARGETDEVICE

{

    DWORD tdSize;

    WORD  tdDriverNameOffset;

    WORD  tdDeviceNameOffset;

    WORD  tdPortNameOffset;

    WORD  tdExtDevmodeOffset;

    BYTE  tdData[1];

}DVTARGETDEVICE;

Members

tdSize

Size, in bytes, of the DVTARGETDEVICE structure. The initial size is included so the structure can be copied more easily.

tdDriverNameOffset

Offset, in bytes, from the beginning of the structure to the device driver name, which is stored as a NULL-terminated string in the tdData buffer.

tdDeviceNameOffset

Offset, in bytes, from the beginning of the structure to the device name, which is stored as a NULL-terminated string in the tdData buffer. This value can be zero to indicate no device name.

tdPortNameOffset

Offset, in bytes, from the beginning of the structure to the port name, which is stored as a NULL-terminated string in the tdData buffer. This value can be zero to indicate no port name.

tdExtDevmodeOffset

Offset, in bytes, from the beginning of the structure to the DEVMODE structure retrieved by calling ExtDeviceMode.

tdData

Aray of bytes containing data for the target device. It is not necessary to include empty strings in tdData (for names where the offset value is zero).

Remarks

Some OLE 1 client applications incorrectly construct target devices by allocating too few bytes in the DEVMODE structure for the OLETARGETDEVICE. They typically only supply the number of bytes in the DEVMODE.dmSize member. The number of bytes to be allocated should be the sum of DEVMODE.dmSize + DEVMODE.dmDriverExtra. When a call is made to the CreateDC function with an incorrect target device, the printer driver tries to access the additional bytes and unpredictable results can occur. To protect against a crash and make the additional bytes available, OLE pads the size of OLE 2 target devices created from OLE 1 target devices.

See Also

FORMATETC, IEnumFORMATETC, IViewObject, OleConvertOLESTREAMToIStorage


FILETIME

The FILETIME data structure is a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601. It is the means by which Win32 determines the date and time. FILETIME is used by the CoDosDateTimeToFileTime, CoFileTimeToDosDateTime, and CoFileTimeNow functions. It is defined as follows:

typedef struct STRUCT tagFILETIME

{

    DWORD  dwLowDateTime;

    DWORD  dwHighDateTime;

} FILETIME;

Members

dwLowDateTime

The low 32 bits of the Win32 date/time value.

dwHighDateTime

The upper 32 bits of the Win32 date/time value.

Remarks

The FILETIME data structure is used in the time conversion functions between DOS and Win32.

See Also

CoDosDateTimeToFileTime, CoFileTimeNow, CoFileTimeToDosDateTime


FONTDESC

The FONTDESC structure contains parameters used to create a font object through the OleCreateFontIndirect function.

typedef struct tagFONTDESC

    {

    UINT cbSizeOfStruct;

    LPOLESTR lpstrName;

    CY cySize;

    SHORT sWeight;

    SHORT sCharset;

    BOOL fItalic;

    BOOL fUnderline;

    BOOL fStrikethrough;

    } FONTDESC;

Members

cbSizeOfStruct

Size of the FONTDESC structure.

lpstrName

Pointer to the caller-owned string specifying the font name.

cySize

Initial point size of the font in CY units.

sWeight

Initial weight of the font. If the weight is below 550 (the average of FW_NORMAL, 400, and FW_BOLD, 700), then the Bold property is also initialized to FALSE. If the weight is above 550, the Bold property is set to TRUE.

sCharset

Initial character set of the font.

fItalic

Initial italic state of the font.

fUnderline

Initial underline state of the font.

fStrikethrough

Initial strikethrough state of the font.

See Also

OleCreateFontIndirect


FORMATETC

The FORMATETC structure is a generalized Clipboard format. It is enhanced to encompass a target device, the aspect or view of the data, and a storage medium indicator. Where one might expect to find a Clipboard format, OLE uses a FORMATETC data structure instead. This structure is used as a parameter in OLE functions and methods that require data format information.

typedef struct tagFORMATETC

{

    CLIPFORMAT      cfFormat;

    DVTARGETDEVICE  *ptd;

    DWORD           dwAspect;

    LONG            lindex;

    DWORD           tymed;

}FORMATETC, *LPFORMATETC;

Members

cfFormat

Particular clipboard format of interest. There are three types of formats recognized by OLE:

•	Standard interchange formats, such as CF_TEXT.

•	Private application formats understood only by the application offering the format, or by other applications offering similar features.

•	OLE formats, which are used to create linked or embedded objects.

ptd

Pointer to a DVTARGETDEVICE structure containing information about the target device for which the data is being composed. A NULL value is used whenever the specified data format is independent of the target device or when the caller doesn’t care what device is used. In the latter case, if the data requires a target device, the object should pick an appropriate default device (often the display for visual components). Data obtained from an object with a NULL target device, such as most metafiles, is independent of the target device. The resulting data is usually the same as it would be if the user chose the Save As command from the File menu and selected an interchange format.

dwAspect

One of the DVASPECT enumeration constants that indicate how much detail should be contained in the rendering. A single clipboard format can support multiple aspects or views of the object. Most data and presentation transfer and caching methods pass aspect information. For example, a caller might request an object’s iconic picture, using the metafile clipboard format to retrieve it. Note that only one DVASPECT value can be used in dwAspect. That is, dwAspect cannot be the result of a BOOLEAN OR operation on several DVASPECT values.

lindex

Part of the aspect when the data must be split across page boundaries. The most common value is -1, which identifies all of the data. For the aspects DVASPECT_THUMBNAIL and DVASPECT_ICON, lindex is ignored.

tymed

One of the TYMED enumeration constants which indicate the type of storage medium used to transfer the object’s data. Data can be transferred using whatever medium makes sense for the object. For example, data can be passed using global memory, a disk file, or structured storage objects. For more information, see the TYMED enumeration.

Remarks

The FORMATETC structure is used by methods in the data transfer and presentation interfaces as a parameter specifying the data being transferred. For example, the IDataObject::GetData method uses the FORMATETC structure to indicate exactly what kind of data the caller is requesting.

See Also

DVASPECT, IDataAdviseHolder, IDataObject, IEnumFORMATETC, IOleCache, OleCreate, OleCreateFromData, OleCreateLinkFromData, OleCreateStaticFromData, OleCreateLink, OleCreateLinkToFile, OleCreateFromFile, STATDATA, STGMEDIUM, TYMED


INTERFACEINFO

The INTERFACEINFO structure contains information about incoming calls. The structure is defined as follows:

typedef struct tagINTERFACEINFO

{

    LPUNKNOWN  pUnk;

    IID        iid;

    WORD       wMethod;

} INTERFACEINFO,  * LPINTERFACEINFO;

Members

pUnk

Pointer to the IUnknown interface on the object.

iid

Identifier of the requested interface

wMethod

Interface method.

See Also

IMessageFilter::HandleIncomingCall


LICINFO

The LICINFO structure contains parameters that describe the licensing behavior of a class factory that supports licensing. The structure is filled during the IClassFactory2::GetLicInfo method.

typedef struct tagLICINFO

    {

    ULONG cbLicInfo;

    BOOL  fRuntimeKeyAvail;

    BOOL  fLicVerified;

    } LICINFO;

Members

cbLicInfo

Size of the LICINFO structure.

fRuntimeKeyAvail

Whether this class factory allows the creation of its objects on a unlicensed machine through the use of a license key. If TRUE, IClassFactory2::RequestLicKey can be called to obtain the key. If FALSE, objects can be created only on a fully licensed machine.

fLicVerified

Whether a full machine license exists so that calls to IClassFactory::CreateInstance and IClassFactory2::RequestLicKey will succeed. If TRUE, the full machine license exists. Thus, objects can be created freely. and a license key is available if fRuntimeKeyAvail is also TRUE. If FALSE, this class factory cannot create any instances of objects on this machine unless the proper license key is passed to IClassFactory2::CreateInstanceLic.

See Also

IClassFactory::CreateInstance, IClassFactory2::CreateInstanceLic, IClassFactory2::GetLicInfo, IClassFactory2::RequestLicKey


MULTI_QI

To optimize network performance, most remote activation functions take an array of MULTI_QI structures rather than just a single IID as input and a single pointer to the requested interface on the object as output, as do local machine activation functions. This allows a set of pointers to interfaces to be returned from the same object in a single round-trip to the server. In network scenarios, requesting multiple interfaces at the time of object construction can save considerable time over using a number of calls to the QueryInterface method for unique interfaces, each of which would require a round-trip to the server.

typedef struct _MULTI_QI {

        const IID*    pIID;

        IUnknown *    pItf;

        HRESULT       hr;

    } MULTI_QI;

Members

pIID

[in] Pointer to an interface identifier.

pItf

[out] Pointer to the interface requested in pIID. Must be set to NULL on entry.

hr

[out] Return value of the QueryInterface call made to satisfy the request for the interface requested in pIID. Common return values are S_OK and E_NOINTERFACE. Must be set to zero on entry.

See Also

CoGetInstanceFromFile, CoGetInstanceFromIStorage, CoCreateInstanceEx


OBJECTDESCRIPTOR

The OBJECTDESCRIPTOR structure is the data structure used for the CF_OBJECTDESRIPTOR and CF_LINKSRCDESCRIPTOR file formats. These formats provide user interface information during data transfer operations, for example, the Paste Special dialog box or target feedback information during drag-and-drop operations.

typedef struct tagOBJECTDESCRIPTOR

{

    ULONG  cbSize;

    CLSID  clsid;

    DWORD  dwDrawAspect;

    SIZEL  sizel;

    POINTL pointl;

    DWORD  dwStatus;

    DWORD  dwFullUserTypeName;

    DWORD  dwSrcOfCopy;

    /* variable sized string data may appear here */

} OBJECTDESCRIPTOR;

Members

cbSize

Size of structure in bytes.

clsid

CLSID of the object being transferred. The clsid is used to obtain the icon for the Display As Icon option in the Paste Special dialog box and is applicable only if the Embed Source or Embedded Object formats are offered. If neither is offered, the value of clsid should be CLSID_NULL. The clsid can be retrieved by the source by loading the object and calling the IOleObject::GetUserClassID method. Note that for link objects, this value is not the same as the value returned by the IPersist::GetClassID method.

dwDrawAspect

Display aspect of the object. Typically, this value is DVASPECT_CONTENT or DVASPECT_ICON. If the source application did not draw the object originally, the dwDrawAspect field contains a zero value (which is not the same as DVASPECT_CONTENT).

sizel

True extent of the object (without cropping or scaling) in HIMETRIC units. Setting this field is optional. The value can be (0,0) for applications that do not draw the object being transferred. This field is used primarily by targets of drag-and-drop operations, so they can give appropriate feedback to the user.

pointl

Offset in HIMETRIC units from the upper-left corner of the object where a drag-and-drop operation was initiated. This field is only meaningful for a drag-and-drop transfer operation since it corresponds to the point where the mouse was clicked to initiate the drag-and-drop operation. The value is (0,0) for other transfer situations, such as a Clipboard copy and paste.

dwStatus

Copy of the status flags for the object. These flags are defined by the OLEMISC enumeration. If an embedded object is being transferred, they are returned by calling the IOleObject::GetMiscStatus method.

dwFullUserTypeName

Offset for finding the full user type name of the object being transferred. It specifies the offset, in bytes, from the beginning of the OBJECTDESCRIPTOR data structure to the null-terminated string that specifies the full user type name of the object being transferred. The value is zero if the string is not present. This string is used by the destination of a data transfer to create labels in the Paste Special dialog box. The destination application must be able to handle the cases when this string is omitted.

dwSrcOfCopy

Offset, in bytes, from the beginning of the data structure to the null-terminated string that specifies the source of the transfer. The dwSrcOfCopy field is typically implemented as the display name of the temporary moniker that identifies the data source. The value for dwSrcOfCopy is displayed in the Source line of the Paste Special dialog box. A zero value indicates that the string is not present. If dwSrcOfCopy is zero, the string “Unknown Source” is displayed in the Paste Special dialog box.

See Also

IDataObject, FORMATETC


OCPFIPARAMS

The OCPFIPARAMS structure contains parameters used to invoke a property sheet dialog box through the OleCreatePropertyFrameIndirect function.

typedef struct tagOCPFIPARAMS

{

    ULONG          cbStructSize;

    HWND           hWndOwner;

    int            x;

    int            y;

    LPCOLESTR      lpszCaption;

    ULONG          cObjects;

    LPUNKNOWN FAR* lplpUnk;

    ULONG          cPages;

    CLSID FAR*     lpPages;

    LCID           lcid;

    DISPID         dispIDInitialProperty;

} OCPFIPARAMS;

Members

cbStructsize

Size of the OCPFIPARAMS structure.

hWndOwner

Parent window of the resulting property sheet dialog box.

x

Horizontal position for the dialog box relative to hWndOwner.

y

Vertical position for the dialog box relative to hWndOwner.

lpszCaption

Pointer to the string used for the caption of the dialog.

cObjects

Number of object pointers passed in lplpUnk.

lplpUnk

Array of IUnknown pointers on the objects for which this property sheet is being invoked. The number of elements inthe aray is specified by cObject. These pointers are passed to each property page through IPropertyPage::SetObjects.

cPages

Number of property pages specified in lpPages.

lpPages

Pointer to an array of size cPages containing the CLSIDs of each property page to display in the property sheet.

lcid

Locale identifier for the property sheet. This value will be returned through IPropertyPageSite::GetLocaleID.

dispIDInitialProperty

Property that is highlighted when the dialog box is made visible.

See Also

IPropertyPage::SetObjects, IPropertyPageSite::GetLocaleID, OleCreatePropertyFrameIndirect


OLEINPLACEFRAMEINFO

The OLEINPLACEFRAMEINFO structure contains information about the accelerators supported by a container during an in-place session. The structure is used in the IOleInPlaceSite::GetWindowContext method and the OleTranslateAccelerator function.

typedef struct tagOIFI

{

    UINT   cb;

    BOOL   fMDIApp;

    HWND   hwndFrame;

    HACCEL haccel;

    UINT   cAccelEntries;

} OLEINPLACEFRAMEINFO, *LPOLEINPLACEFRAMEINFO;

Members

cb

Size in bytes of this structure. The object server must specify sizeof(OLEINPLACEFRAMEINFO) in the structure it passes to IOleInPlaceSite::GetWindowContext. The container can then use this size to determine the structure’s version.

fMDIApp

Whether the container is an MDI application.

hwndFrame

Handle to the container’s top-level frame window.

haccel

Handle to the accelerator table that the container wants to use during an in-place editing session.

cAccelEntries

Number of accelerators in haccel.

Remarks

When an object is being in-place activated, its server calls the container’s IOleInPlaceSite::GetWindowContext method, which fills in an OLEINPLACEFRAMEINFO structure. During an in-place session, the message loop of an EXE server passes a pointer to the OLEINPLACEFRAMEINFO structure to OleTranslateAccelerator. OLE uses the information in this structure to determine whether a message maps to one of the container’s accelerators.

See Also

IOleInPlaceSite::GetWindowContext, OleTranslateAccelerator


OLEMENUGROUPWIDTHS

The OLEMENUGROUPWIDTHS structure is the mechanism for building a shared menu. It indicates the number of menu items in each of the six menu groups of a menu shared between a container and an object server during an in-place editing session.

The structure is defined in the IOleInPlaceFrame interface (inplcf.idl). It is used in the IOleInPlaceFrame::InsertMenus and ICDStandardForm::SetMenu methods, and the OleCreateMenuDescriptor function.

typedef struct tagOleMenuGroupWidths

{

    LONG width[6];

} OLEMENUGROUPWIDTHS, * LPOLEMENUGROUPWIDTHS;

Member

width

An array whose elements contain the number of menu items in each of the six menu groups of a shared in-place editing menu. Each menu group can have any number of menu items. The container uses elements 0, 2, and 4 to indicate the number of menu items in its File, View, and Window menu groups. The object server uses elements 1, 3, and 5 to indicate the number of menu items in its Edit, Object, and Help menu groups.

Remarks

A container application and an object server use this structure to build a shared menu. The object server initializes to zeros the array elements in an OLEMENUGROUPWIDTHS structure and passes a pointer to it along with a menu handle to the container in a call to IOleInPlaceFrame::InsertMenus. The container adds its menu items to the menu, and fills in the structure with the number of items in each of its groups (indexes 0, 2, and 4). The server then uses the group width values returned by the container to insert its menu items in the appropriate position in the menu. The server fills in the structure with the number of items in each of its groups (indexes 1, 3, and 5), and then passes the structure to OLE in a call to the OleCreateMenuDescriptor function. This enables OLE to intercept the container’s menu messages and redirect the messages generated by the server’s menus.

See Also

IOleInPlaceFrame::InsertMenus, OleCreateMenuDescriptor


OLEUIBUSY

The OLEUIBUSY structure contains information that the OLE User Interface Library uses to initialize the Busy dialog box, and space for the library to return information when the dialog box is dismissed.

typedef struct tagOLEUIBUSY

{

// These IN fields are standard across all OLEUI dialog box functions.

    DWORD          cbStruct;

    DWORD          dwFlags;

    HWND           hWndOwner;

    LPCSTR         lpszCaption;

    LPFNOLEUIHOOK  lpfnHook;

    LPARAM         lCustData;

    HINSTANCE      hInstance;

    LPCSTR         lpszTemplate;

    HRSRC          hResource;

// Specifics for OLEUIBUSY.

    HTASK  hTask;

    HWND FAR *  lphWndDialog;

} OLEUICHANGEICON, *POLEUICHANGEICON, FAR *LPOLEUICHANGEICON;

Members

cbStruct

Size of the structure in bytes. This field must be filled on input.

dwFlags

On input, specifies the initialization and creation flags. On exit, it specifies the user’s choices. It may be a combination of the following flags:

BZ_DISABLECANCELBUTTON

Input only: This flag disables the Cancel button.

BZ_DISABLESWITCHTOBUTTON

Input only: This flag disables the Switch To... button.

BZ_DISABLERETRYBUTTON

Input only: This flag disables the Retry button.

BZ_NOTRESPONDINGDIALOG

Input only: This flag generates a Not Responding dialog box instead of a Busy dialog box. The text is slightly different, and the Cancel button is disabled.

hWndOwner

Window that owns the dialog box. It should not be NULL.

lpszCaption

Pointer to a string to be used as the title of the dialog box. If NULL, then the library uses Busy.

lpfnHook

Pointer to a hook function that processes messages intended for the dialog box. The hook function must return zero to pass a message that it didn’t process back to the dialog box procedure in the library. The hook function must return a non-zero value to prevent the library’s dialog box procedure from processing a message it has already processed.

lCustData

Application-defined data that the library passes to the hook function pointed to by the lpfnHook member. The library passes a pointer to the OLEUIBUSY structure in the lParam parameter of the WM_INITDIALOG message; this pointer can be used to retrieve the lCustData member.

hInstance

Instance that contains a dialog box template specified by the lpTemplateName member.

lpszTemplate

Pointer to a null-terminated string that specifies the name of the resource file for the dialog box template that is to be substituted for the library’s Busy dialog box template.

hResource

Customized template handle.

hTask Input only:

Handle to the task that is blocking.

lphWndDialog

Pointer to the dialog box’s HWND.

See Also

OleUIBusy


OLEUICHANGEICON

The OLEUICHANGEICON structure contains information that the OLE User Interface Library uses to initialize the Change Icon dialog box, and it contains space for the library to return information when the dialog box is dismissed.

typedef struct tagOLEUICHANGEICON

{

// These IN fields are standard across all OLEUI dialog box functions.

    DWORD          cbStruct;

    DWORD          dwFlags;

    HWND           hWndOwner;

    LPCSTR         lpszCaption;

    LPFNOLEUIHOOK  lpfnHook;

    LPARAM         lCustData;

    HINSTANCE      hInstance;

    LPCSTR         lpszTemplate;

    HRSRC          hResource;

 // Specifics for OLEUICHANGEICON.

    HGLOBAL  hMetaPict;

    CLSID    clsid;

    char     szIconExe[OLEUI_CCHPATHMAX];

    int      cchIconExe;

} OLEUICHANGEICON, *POLEUICHANGEICON, FAR *LPOLEUICHANGEICON;

Members

cbStruct

Size of the structure in bytes. This field must be filled on input.

dwFlags

On input, specifies the initialization and creation flags. On exit, it specifies the user’s choices. It can be a combination of the following flags:

CIF_SHOWHELP

Dialog box will display a Help button.

CIF_SELECTCURRENT

On input, selects the Current radio button on initialization. On exit, specifies that the user selected Current.

CIF_SELECTDEFAULT

On input, selects the Default radio button on initialization. On exit, specifies that the user selected Default.

CIF_SELECTFROMFILE

On input, selects the From File radio button on initialization. On exit, specifies that the user selected From File.

CIF_USEICONEXE

Input only. Extracts the icon from the executable specified in the szIconExe member, instead of retrieving it from the class. This is useful for OLE embedding or linking to non-OLE files.

hWndOwner

Window that owns the dialog box. It should not be NULL.

lpszCaption

Pointer to a string to be used as the title of the dialog box. If NULL, then the library uses Change Icon.

lpfnHook

Pointer to a hook function that processes messages intended for the dialog box. The hook function must return zero to pass a message that it didn’t process back to the dialog box procedure in the library. The hook function must return a non-zero value to prevent the library’s dialog box procedure from processing a message it has already processed.

lCustData

Application-defined data that the library passes to the hook function pointed to by the lpfnHook member. The library passes a pointer to the OLEUICHANGEICON structure in the lParam parameter of the WM_INITDIALOG message; this pointer can be used to retrieve the lCustData member.

hInstance

Instance that contains a dialog box template specified by the lpTemplateName member.

lpszTemplate

Pointer to a null-terminated string that specifies the name of the resource file for the dialog box template that is to be substituted for the library’s Change Icon dialog box template.

hResource

Customized template handle.

hMetaPict

Current and final image. The source of the icon is embedded in the metafile itself.

clsid

Input only. The class to use to get the Default icon.

szIconExe

Input only. Pointer to the executable to extract the default icon from. This member is ignored unless CIF_USEICONEXE is included in the dwFlags parameter and an attempt to retrieve the class icon from the specified CLSID fails.

cchIconExe

Input only. The number of characters in szIconExe. This member is ignored unless CIF_USEICONEXE is included in the dwFlags member.

See Also

OleUIChangeIcon


OLEUICHANGESOURCE

This structure is used to initialize the standard Change Source dialog box. It allows the user to modify the destination or source of a link. This may simply entail selecting a different file name for the link, or possibly changing the item reference within the file, for example, changing the destination range of cells within the spreadsheet that the link is to.

typedef struct tagOLEUICHANGESOURCEW

{

// These IN fields are standard across all OLEUI dialog box functions.

    DWORD          cbStruct;

    DWORDT         dwFlags;

    HWND           hWndOwner;

    LPCWSTR        lpszCaption;

    LPFNOLEUIHOOK  lpfnHook;

    LPARAM         lCustData;

    HINSTANCE      hInstance;

    LPCWSTR        lpszTemplate;

    HRSRC          hResource;

// INTERNAL ONLY: do not modify these members

    OPENFILENAMEW*     lpOFN;

    DWORD              dwReserved1[4];

// Specifics for OLEUICHANGESOURCE.

    LPOLEUILINKCONTAINERW  lpOleUILinkContainer;

    DWORD                  dwLink;

    LPTSTR                 lpszDisplayName;

    ULONG                  nFileLength;

    LPTSTR                 lpszFrom;

    LPTSTR                 lpszTo;

} OLEUICHANGESOURCEW, *POLEUICHANGESOURCEW, FAR *LPOLEUICHANGESOURCEW;

Members

cbStruct

Size of the structure in bytes.

dwFlags

On input, this field specifies the initialization and creation flags. On exit, it specifies the user’s choices. It may be a combination of the following flags:

CSF_SHOWHELP

Enables or shows the Help button.

CSF_VALIDSOURCE

Indicates that the link was validated.

CSF_ONLYGETSOURCE

Disables automatic validation of the link source when the user presses OK. If you specify this flag, you should validate the source when the dialog box returns OK.

hWndOwner

Window that owns the dialog box.

lpszCaption

Pointer to a string to be used as the title of the dialog box. If NULL, then the library uses Change Source.

lpfnHook

Pointer to a hook function that processes messages intended for the dialog box. The hook function must return zero to pass a message that it didn’t process back to the dialog box procedure in the library. The hook function must return a non-zero value to prevent the library’s dialog box procedure from processing a message it has already processed.

lCustData

Application-defined data that the library passes to the hook function pointed to by the lpfnHook member. The library passes a pointer to the OLEUICHANGEICON structure in the lParam parameter of the WM_INITDIALOG message; this pointer can be used to retrieve the lCustData member.

hInstance

Instance that contains a dialog box template specified by the lpszTemplate member. This member is ignored if the lpszTemplate member is NULL or invalid.

lpszTemplate

Pointer to a null-terminated string that specifies the name of the resource file for the dialog box template that is to be substituted for the library’s Convert dialog box template.

hResource

Resource handle for a custom dialog box. If this member is NULL, then the library uses the standard Convert dialog box template, or if it is valid, the template named by the lpszTemplate member.

lpOFN

Pointer to the OPENFILENAME structure, which contains information used by the operating system to initialize the system-defined Open or Save As dialog boxes.

dwReserved1[4]

Reserved for future use.

lpOleUILinkContainer

Pointer to the container’s implementation of the IOleUILinkContainer interface, used to validate the link source. The Edit Links dialog box uses this to allow the container to manipulate its links.

dwLink

Container-defined unique 32-bit link identifier used to validate link sources. Used by lpOleUILinkContainer.

lpszDisplayName

Pointer to the complete source display name.

nFileLength

File moniker portion of lpszDisplayName.

lpszFrom

Pointer to the prefix of the source that was changed from.

lpszTo

Pointer to the prefix of the source to be changed to.

See Also

IOleUILinkContainer, OleUIChangeSource


OLEUICONVERT

The OLEUICONVERT structure contains information that the OLE User Interface Library uses to initialize the Convert dialog box, and space for the library to return information when the dialog box is dismissed.

typedef struct tagOLEUICONVERT

{

// These IN fields are standard across all OLEUI dialog functions.

    DWORD          cbStruct

    DWORD          dwFlags

    HWND           hWndOwner

    LPCSTR         lpszCaption

    LPFNOLEUIHOOK  lpfnHook

    LPARAM         lCustData

    HINSTANCE      hInstance

    LPCSTR         lpszTemplate

    HRSRC          hResource

// Specifics for OLEUICONVERT.

    CLSID    clsid;

    CLSID    clsidConvertDefault;

    CLSID    clsidActivateDefault;

    CLSID    clsidNew;

    DWORD    dvAspect;

    WORD     wFormat;

    BOOL     fIsLinkedObject;

    HGLOBAL  hMetaPict;

    LPTSTR   lpszUserType;

    BOOL     fObjectsIconChanged;

    LPTSTR   lpszDefLabel

    UINT     cClsidExclude

    LPCLSID  lpClsidExclude

} OLEUICONVERT, *POLEUICONVERT, FAR *LPOLEUICONVERT;

Members

cbStruct

Size of the structure, in bytes. This field must be filled on input.

dwFlags

On input, this field specifies the initialization and creation flags. On exit, it specifies the user’s choices. It may be a combination of the following flags:

CF_SHOWHELPBUTTON

Dialog box will display a Help button. This flag is set on input.

CF_SETCONVERTDEFAULT

Class whose CLSID is specified by clsidConvertDefault will be used as the default selection. This selection appears in the class listbox when the Convert To radio button is selected. This flag is set on input.

CF_SETACTIVATEDEFAULT

Class whose CLSID is specified by clsidActivateDefault will be used as the default selection. This selection appears in the class listbox when the Activate As radio button is selected. This flag is set on input.

CF_SELECTCONVERTTO

On input, this flag specifies that Convert To will be initially selected (default behavior). This flag is set on output if Convert To was selected when the user dismissed the dialog box.

CF_SELECTACTIVATEAS

On input, this flag specifies that Activate As will be initially selected. This flag is set on output if Activate As was selected when the user dismissed the dialog box.

CF_DISABLEDISPLAYASICON

The Display As Icon button will be disabled on initialization.

CF_DISABLEACTIVATEAS

The Activate As radio button will be disabled on initialization.

CF_HIDECHANGEICON

The Change Icon button will be hidden in the Convert dialog box.

CF_CONVERTONLY

The Activate As radio button will be disabled in the Convert dialog box.

hWndOwner

Window that owns the dialog box. It should not be NULL.

lpszCaption

Pointer to a string to be used as the title of the dialog box. If NULL, then the library uses Convert.

lpfnHook

Pointer to a hook function that processes messages intended for the dialog box. The hook function must return zero to pass a message that it didn’t process back to the dialog box procedure in the library. The hook function must return a non-zero value to prevent the library’s dialog box procedure from processing a message it has already processed.

lCustData

Application-defined data that the library passes to the hook function pointed to by the lpfnHook member. The library passes a pointer to the OLEUICONVERT structure in the lParam parameter of the WM_INITDIALOG message; this pointer can be used to retrieve the lCustData member.

hInstance

Instance that contains a dialog box template specified by the lpszTemplate member. This member is ignored if the lpszTemplate member is NULL or invalid.

lpszTemplate

Pointer to a null-terminated string that specifies the name of the resource file for the dialog box template that is to be substituted for the library’s Convert dialog box template.

hResource

Resource handle for a custom dialog box. If this member is NULL, then the library uses the standard Convert dialog box template, or if it is valid, the template named by the lpszTemplate member.

clsid

The CLSID of the object to be converted or activated. This member is set on input.

clsidConvertDefault

The CLSID to use as the default class when Convert To is selected. This member is ignored if the dwFlags member does not include CF_SETCONVERTDEFAULT. This member is set on input.

clsidActivateDefault

The CLSID to use as the default class when Activate As is selected. This member is ignored if the dwFlags member does not include CF_SETACTIVATEDEFAULT. This member is set on input.

clsidNew

The CLSID of the selected class. This member is set on output.

dvAspect

Aspect of the object. This must be either DVASPECT_CONTENT or DVASPECT_ICON. If dvAspect is DVASPECT_ICON on input, then the Display As Icon box is checked and the object’s icon is displayed. This member is set on input and output.

wFormat

Data format of the object to be converted or activated.

fIsLinkedObject

TRUE if the object is linked. This member is set on input.

hMetaPict

The METAFILEPICT containing the iconic aspect. This member is set on input and output.

lpszUserType

Pointer to the User Type name of the object to be converted or activated. If this value is NULL, then the dialog box will retrieve the User Type name from the registry. This string is freed on exit.

fObjectsIconChanged

TRUE if the object’s icon changed. (that is, if OleUIChangeIcon was called and not canceled.). This member is set on output.

lpszDefLabel

Pointer to the default label to use for the icon. If NULL, the short user type name will be used. If the object is a link, the caller should pass the Display Name of the link source. This is freed on exit.

cClsidExclude

Number of CLSIDs in lpClsidExclude.

lpClsidExclude

Pointer to the list of CLSIDs to exclude from the list.

See Also

OleUIConvert, OleUIChangeIcon


OLEUIEDITLINKS

The OLEUIEDITLINKS structure contains information that the OLE User Interface Library uses to initialize the Edit Links dialog box, and contains space for the library to return information when the dialog box is dismissed.

typedef struct tagOLEUIEDITLINKS

{

// These IN fields are standard across all OLEUI dialog box functions.

    DWORD          cbStruct;

    DWORD          dwFlags;

    HWND           hWndOwner;

    LPCSTR         lpszCaption;

    LPFNOLEUIHOOK  lpfnHook;

    LPARAM         lCustData;

    HINSTANCE      hInstance;

    LPCSTR         lpszTemplate;

    HRSRC          hResource;

// Specifics for OLEUIEDITLINKS.

    LPOLEUILINKCONTAINER      lpOleUILinkContainer;

} OLEUIEDITLINKS, *POLEUIEDITLINKS, FAR *LPOLEUIEDITLINKS;

Members

cbStruct

Size of the structure in bytes. This field must be filled on input.

dwFlags

On input, dwFlags specifies the initialization and creation flags. It may be a combination of the following flags:

ELF_SHOWHELP

Specifies that the dialog box will display a Help button.

ELF_DISABLEUPDATENOW

Specifies that the Update Now button will be disabled on initialization.

ELF_DISABLEOPENSOURCE

Specifies that the Open Source button will be disabled on initialization.

ELF_DISABLECHANGESOURCE

Specifies that the Change Source button will be disabled on initialization.

ELF_DISABLECANCELLINK

Specifies that the Cancel Link button will be disabled on initialization.

hWndOwner

Window that owns the dialog box. It should not be NULL.

lpszCaption

Pointer to a string to be used as the title of the dialog box. If NULL, then the library uses Links.

lpfnHook

Pointer to a hook function that processes messages intended for the dialog box. The hook function must return zero to pass a message that it didn’t process back to the dialog box procedure in the library. The hook function must return a non-zero value to prevent the library’s dialog box procedure from processing a message it has already processed.

lCustData

Application-defined data that the library passes to the hook function pointed to by the lpfnHook member. The library passes a pointer to the OLEUIEDITLINKS structure in the lParam parameter of the WM_INITDIALOG message; this pointer can be used to retrieve the lCustData member.

hInstance

Instance that contains a dialog box template specified by the lpTemplateName member.

lpszTemplate

Pointer to a null-terminated string that specifies the name of the resource file for the dialog box template that is to be substituted for the library’s Edit Links dialog box template.

hResource

Customized template handle.

lpOleUILinkContainer

Pointer to the container’s implementation of the IOleUILinkContainer Interface. The Edit Links dialog box uses this to allow the container to manipulate its links.

See Also

IOleUILinkContainer, OleUIEditLinks


OLEUIGNRLPROPS

This structure is used to initialize the General tab of the Object Properties dialog box. A reference to it is passed in as part of the OLEUIOBJECTPROPS structure to the OleUIObjectProperties function. This tab shows the type and size of an OLE embedding and allows it the user to tunnel to the Convert dialog box. This tab also shows the link destination if the object is a link.

typedef struct tagOLEUIGNRLPROPS

{

// These IN fields are standard across all OLEUI property pages.

    DWORD          cbStruct;

    DWORD          dwFlags;

    DWORD          dwReserved1[2];

    LPFNOLEUIHOOK  lpfnHook;

    LPARAM         lCustData;

    DWORD          dwReserved2[3];

    struct tagOLEUIOBJECTPROPSW* lpOP;

} OLEUIGNRLPROPSW, *POLEUIGNRLPROPSW, FAR* LPOLEUIGNRLPROPSW;

Members

cbStruct

Size of the structure in bytes. This field must be filled on input.

dwFlags

Currently no flags associated with this member. It should be set to 0 (zero).

dwReserved1[2]

Reserved for future use.

lpfnHook

Pointer to a hook function that processes messages intended for the dialog box. The hook function must return zero to pass a message that it didn’t process back to the dialog box procedure in the library. The hook function must return a non-zero value to prevent the library’s dialog box procedure from processing a message it has already processed.

lCustData

Application-defined data that the library passes to the hook function pointed to by the lpfnHook member during WM_INITDIALOG.

dwReserved2[3]

Reserved for future use.

lpOP

Used internally.

See Also

OleUIObjectProperties, OLEUIOBJECTPROPS


OLEUIINSERTOBJECT

The OLEUIINSERTOBJECT structure contains information that the OLE User Interface Library uses to initialize the Insert Object dialog box, and space for the library to return information when the dialog box is dismissed.

typedef struct tagOLEUIINSERTOBJECT

{

// These IN fields are standard across all OLEUI dialog box functions.

    DWORD          cbStruct;

    DWORD          dwFlags;

    HWND           hWndOwner;

    LPCSTR         lpszCaption;

    LPFNOLEUIHOOK  lpfnHook;

    LPARAM         lCustData;

    HINSTANCE      hInstance;

    LPCSTR         lpszTemplate;

    HRSRC          hResource;

    CLSID          clsid;

// Specifics for OLEUIINSERTOBJECT.

    LPTSTR         lpszFile;

    UINT           cchFile;

    UINT           cClsidExclude;

    LPCLSID        lpClsidExclude;

    IID            iid;

// Specific to create objects if flags say so

    DWORD            oleRender;

    LPFORMATETC      lpFormatEtc;

    LPOLECLIENTSITE  lpIOleClientSite;

    LPSTORAGE        lpIStorage;

    LPVOID FAR *     ppvObj;

    SCODE            sc;

    HGLOBAL          hMetaPict;

} OLEUIINSERTOBJECT, *POLEUIINSERTOBJECT, FAR *LPOLEUIINSERTOBJECT;

Members

cbStruct

Size of the structure in bytes. This field must be filled on input.

dwFlags

On input, specifies the initialization and creation flags. On exit, specifies the user’s choices. It can be a combination of the following flags:

IOF_SHOWHELP

The dialog box will display a Help button.

IOF_SELECTCREATENEW

The Create New radio button will initially be checked. This cannot be used with IOF_SELECTCREATEFROMFILE.

IOF_SELECTCREATEFROMFILE

The Create From File radio button will initially be checked. This cannot be used with IOF_SELECTCREATENEW.

IOF_CHECKLINK

The Link check box will initially be checked.

IOF_CHECKDISPLAYASICON

The Display As Icon check box will initially be checked, the current icon will be displayed, and the Change Icon button will be enabled.

IOF_CREATENEWOBJECT

A new object should be created when the user selects OK to dismiss the dialog box and the Create New radio button was selected.

IOF_CREATEFILEOBJECT

A new object should be created from the specified file when the user selects OK to dismiss the dialog box and the Create From File radio button was selected.

IOF_CREATELINKOBJECT

A new linked object should be created when the user selects OK to dismiss the dialog box and the user checked the Link check box.

IOF_DISABLELINK

The Link check box will be disabled on initialization.

IOF_VERIFYSERVERSEXIST

The dialog box should validate the classes it adds to the listbox by ensuring that the server specified in the registration database exists. This is a significant performance factor.

IOF_DISABLEDISPLAYASICON

The Display As Icon check box will be disabled on initialization.

IOF_HIDECHANGEICON

The Change Icon button will be hidden in the Insert Object dialog box.

IOF_SHOWINSERTCONTROL

Displays the Insert Control radio button.

IOF_SELECTCREATECONTROL

Displays the Create Control radio button.

hWndOwner

Window that owns the dialog box. It should not be NULL.

lpszCaption

Pointer to a string to be used as the title of the dialog box. If NULL, then the library uses Insert Object.

lpfnHook

Pointer to a hook function that processes messages intended for the dialog box. The hook function must return zero to pass a message that it didn’t process back to the dialog box procedure in the library. The hook function must return a non-zero value to prevent the library’s dialog box procedure from processing a message it has already processed.

lCustData

Application-defined data that the library passes to the hook function pointed to by the lpfnHook member. The library passes a pointer to the OLEUIINSERTOBJECT structure in the lParam parameter of the WM_INITDIALOG message; this pointer can be used to retrieve the lCustData member.

hInstance

Instance that contains a dialog box template specified by the lpTemplateName member.

lpszTemplate

Pointer to a null-terminated string that specifies the name of the resource file for the dialog box template that is to be substituted for the library’s Insert Object dialog box template.

hResource

Customized template handle.

clsid

CLSID for class of the object to be inserted. Filled on output.

lpszFile

Pointer to the name of the file to be linked or embedded. Filled on output.

cchFile

Size of lpszFile buffer; will not exceed OLEUI_CCHPATHMAX.

cClsidExclude

Number of CLSIDs included in the lpClsidExclude list. Filled on input.

lpClsidExclude

Pointer to a list of CLSIDs to exclude from listing.

iid

Identifier of the requested interface. If OleUIInsertObject creates the object, then it will return a pointer to this interface. This parameter is ignored if OleUIInsertObject does not create the object.

oleRender

Rendering option. If OleUIInsertObject creates the object, then it selects the rendering option when it creates the object. This parameter is ignored if OleUIInsertObject does not create the object.

lpFormatEtc

Desired format. If OleUIInsertObject creates the object, then it selects the format when it creates the object. This parameter is ignored if OleUIInsertObject does not create the object.

lpIOleClientSite

Pointer to the client site to be used for the object. This parameter is ignored if OleUIInsertObject does not create the object.

lpIStorage

Pointer to the storage to be used for the object. This parameter is ignored if OleUIInsertObject does not create the object.

ppvObj

Indirect pointer to where the object is returned. This parameter is ignored if OleUIInsertObject does not create the object.

sc

Result of creation calls. This parameter is ignored if OleUIInsertObject does not create the object.

hMetaPict

MetafilePict structure containing the iconic aspect, if it wasn’t placed in the object’s cache.

See Also

OleUIInsertObject


OLEUILINKPROPS

This structure is used to initialize the Link tab of the Object Properties dialog box. A reference to it is passed in as part of the OLEUIOBJECTPROPS structure to the OleUIObjectProperties function. This tab shows the location, update status, and update time for a link. It allows the user to change the source of the link, toggle its update status between automatic and manual update, open the source, force an update of the link, or break the link (convert it to a static picture).

// These IN fields are standard across all OLEUI property pages.

typedef struct tagOLEUILINKPROPSW

{

// These IN fields are standard across all OLEUI property pages.

    DWORD          cbStruct;

    DWORD          dwFlags;

    DWORD          dwReserved1[2];

    LPFNOLEUIHOOK  lpfnHook;

    LPARAM         lCustData;

    DWORD          dwReserved2[3];

    struct tagOLEUIOBJECTPROPSW* lpOP;

} OLEUILINKPROPSW, *POLEUILINKPROPSW, FAR* LPOLEUILINKPROPSW;

Members

cbStruct

Size of the structure in bytes.

dwFlags

Contains in/out flags specific to the Links page.

dwReserved1[2]

Reserved for future use.

lpfnHook

Pointer to the hook callback (not used in this dialog box).

lCustData

Custom data to pass to hook (not used in this dialog box).

dwReserved2[3]

Reserved for future use.

lpOP

Used internally.

See Also

OleUIObjectProperties, OLEUIOBJECTPROPS


OLEUIOBJECTPROPS

This structure is used to initialize the standard Object Properties dialog box. It contains references to interfaces used to gather information about the embedding or link, references to three structures that are used to initialize the default tabs—General (OLEUIGNRLPROPS), View (OLEUIVIEWPROPS), and Link (OLEUILINKPROPS), if appropriate—and a standard property-sheet extensibility interface that allows the caller to add additional custom property sheets to the dialog box.

typedef struct tagOLEUIOBJECTPROPS

{

// These IN fields are standard across all OLEUI property sheets.

    DWORD    cbStruct;

    DWORD    dwFlags;

// Standard PROPSHEETHEADER used for extensibility

    LPPROPSHEETHEADER        lpPS;

// Data which allows manipulation of the object

    DWORD    dwObject;

    LPOLEUIOBJINFO        lpObjInfo;

// Data which allows manipulation of the link

    DWORD    dwLink;

    LPOLEUILINKINFO        lpLinkInfo;

// Data specfic to each page

    LPOLEUIGNRLPROPS        lpGP;

    LPOLEUIVIEWPROPS        lpVP;

    LPOLEUILINKPROPS        lpLP;

} OLEUIOBJECTPROPS, *POLEUIOBJECTPROPS, FAR* LPOLEUIOBJECTPROPS;

Members

cbStruct

Size of the structure in bytes.

dwFlags

Contains in/out global flags for the property sheet.

OPF_OBJECTISLINK

Object is a link object and therefore has a link property page.

OPF_NOFILLDEFAULT

Do not fill in default values for the object.

OPF_SHOWHELP

Dialog box will display a Help button.

OPF_DISABLECONVERT

The Convert button will be disabled on the general property page.

lpPS

[in] Pointer to the standard property sheet header (PROPSHEETHEADER), used for extensibility.

//Data which allows manipulation of the object

dwObject

[in] Identifier for the object.

lpObjInfo

[in] Pointer to the interface to manipulate object.

//Data which allows manipulation of the link

dwLink;

[in] Container-defined unique 32-bit identifier for a single link. Containers can use the pointer to the link’s container site for this value.

lpLinkInfo

[in] Pointer to the interface to manipulate link.

// Data specific to each page

lpGP

[in] Pointer to the general page data.

lpVP

[in] Pointer to the view page data.

lpLP

[in] Pointer to the link page data.

See Also

OleUIObjectProperties, OLEUIGNRLPROPS, OLEUIVIEWPROPS, OLEUILINKPROPS


OLEUIPASTEENTRY

This structure is an array of OLEUIPASTEENTRY entries specified in the OLEUIPASTESPECIAL structure for the Paste Special dialog box. Each entry includes a FORMATETC which specifies the formats that are acceptable, a string that is to represent the format in the dialog box’s listbox, a string to customize the result text of the dialog box, and a set of flags from the OLEUIPASTEFLAG enumeration. The flags indicate if the entry is valid for pasting only, linking only or both pasting and linking. If the entry is valid for linking, the flags indicate which link types are acceptable by OR’ing together the appropriate OLEUIPASTE_LINKTYPE<#> values. These values correspond to the array of link types as follows:

OLEUIPASTE_LINKTYPE1=arrLinkTypes[0]
OLEUIPASTE_LINKTYPE2=arrLinkTypes[1]
OLEUIPASTE_LINKTYPE3=arrLinkTypes[2]
OLEUIPASTE_LINKTYPE4=arrLinkTypes[3]
OLEUIPASTE_LINKTYPE5=arrLinkTypes[4]
OLEUIPASTE_LINKTYPE6=arrLinkTypes[5]
OLEUIPASTE_LINKTYPE7=arrLinkTypes[6]
OLEUIPASTE_LINKTYPE8=arrLinkTypes[7]

arrLinkTypes[] is an array of registered clipboard formats for linking. A maximum of eight link types are allowed.

typedef struct tagOLEUIPASTEENTRY

{

    FORMATETC   fmtetc;

    LPCSTR      lpstrFormatName;

    LPCSTR      lpstrResultText;

    DWORD       dwFlags;

    DWORD       dwScratchSpace;

} OLEUIPASTEENTRY, *POLEUIPASTEENTRY, FAR *LPOLEUIPASTEENTRY;

Members

fmtetc

Format that is acceptable. The Paste Special dialog box checks if this format is offered by the object on the clipboard and if so, offers it for selection to the user.

lpstrFormatName

Pointer to the string that represents the format to the user. Any %s in this string is replaced by the FullUserTypeName of the object on the clipboard and the resulting string is placed in the list box of the dialog box. Only one %s is allowed. The presence or absence of %s specifies whether the result-text is to indicate that data is being pasted or that an object that can be activated by an application is being pasted. If %s is present, the resulting text says that an object is being pasted. Otherwise, it says that data is being pasted.

lpstrResultText

Pointer to the string used to customize the resulting text of the dialog box when the user selects the format corresponding to this entry. Any %s in this string is replaced by the application name or FullUserTypeName of the object on the clipboard. Only one %s is allowed.

dwFlags

Values from OLEUIPASTEFLAG enumeration.

dwScratchSpace

Scratch space available to routines that loop through an IEnumFORMATETC to mark if the PasteEntry format is available. This field CAN be left uninitialized.

See Also

OLEUIPASTEFLAG, OleUIPasteSpecial, OLEUIPASTESPECIAL


OLEUIPASTESPECIAL

The OLEUIPASTESPECIAL structure contains information that the OLE User Interface Library uses to initialize the Paste Special dialog box, as well as space for the library to return information when the dialog box is dismissed.

typedef struct tagOLEUIPASTESPECIAL

{

// These IN fields are standard across all OLEUI dialog box functions.

    DWORD          cbStruct;

    DWORD          dwFlags;

    HWND           hWndOwner;

    LPCSTR         lpszCaption;

    LPFNOLEUIHOOK  lpfnHook;

    LPARAM         lCustData;

    HINSTANCE      hInstance;

    LPCSTR         lpszTemplate;

    HRSRC          hResource;

// Specifics for       OLEUIPASTESPECIAL.

    LPDATAOBJECT       lpSrcDataObj;

    LPOLEUIPASTEENTRY  arrPasteEntries;

    int                cPasteEntries;

    UINT FAR *         arrLinkTypes;

    int                cLinkTypes;

    UINT               cClsidExclude;

    LPCLSID            lpClsidExclude;

    int                nSelectedIndex;

    BOOL               fLink;

    HGLOBAL            hMetaPict;

    SIZEL              sizel;

} OLEUIPASTESPECIAL, *POLEUIPASTESPECIAL, FAR *LPOLEUIPASTESPECIAL;

Members

cbStruct

Size of the structure, in bytes. This field must be filled on input.

dwFlags

On input, dwFlags specifies the initialization and creation flags. On exit, it specifies the user’s choices. It may be a combination of the following flags:

PSF_SHOWHELP

Dialog box will display a Help button.

PSF_SELECTPASTE

The Paste radio button will be selected at dialog box startup. This is the default, if PSF_SELECTPASTE or PSF_SELECTPASTELINK are not specified. Also, it specifies the state of the button on dialog termination. IN/OUT flag.

PSF_SELECTPASTELINK

The PasteLink radio button will be selected at dialog box startup. Also, specifies the state of the button on dialog termination. IN/OUT flag.

PSF_CHECKDISPLAYASICON

Whether the Display As Icon radio button was checked on dialog box termination. OUT flag.

PSF_DISABLEDISPLAYASICON

The Display As Icon check box will be disabled on initialization.

HIDECHANGEICON

Used to disable the change-icon button in the dialog box , which is available to users when they’re pasting an OLE object by default. See STAYONCLIPBOARDCHANGE otherwise.

STAYONCLIPBOARDCHANGE

Used to tell the dialog box to stay up if the clipboard changes while the dialog box is up. If the user switches to another application and copies or cuts something, the dialog box will, by default, perform a cancel operation, which will remove the dialog box since the options it’s in the middle of presenting to the user are no longer up-to-date with respect to what’s really on the clipboard.

NOREFRESHDATAOBJECT

Used in conjunction with STAYONCLIPBOARDCHANGE (it doesn’t do anything otherwise). If the clipboard changes while the dialog box is up and STAYONCLIPBOARDCHANGE is specified, then NOREFRESHDATAOBJECT indicates that the dialog box should NOT refresh the contents of the dialog box to reflect the new contents of the clipboard. This is useful if the application is using the paste-special dialog box on an IDataObject besides the one on the clipboard, for example, as part of a right-click drag-and-drop operation.

hWndOwner

Wwindow that owns the dialog box. It should not be NULL.

lpszCaption

Pointer to a string to be used as the title of the dialog box. If NULL, then the library uses Paste Special.

lpfnHook

Pointer to a hook function that processes messages intended for the dialog box. The hook function must return zero to pass a message that it didn’t process back to the dialog box procedure in the library. The hook function must return a non-zero value to prevent the library’s dialog box procedure from processing a message it has already processed.

lCustData

Application-defined data that the library passes to the hook function pointed to by the lpfnHook member. The library passes a pointer to the OLEUIPASTESPECIAL structure in the lParam parameter of the WM_INITDIALOG message; this pointer can be used to retrieve the lCustData member.

hInstance

Instance that contains a dialog box template specified by the lpTemplateName member.

lpszTemplate

Pointer to a null-terminated string that specifies the name of the resource file for the dialog box template that is to be substituted for the library’s Paste Special dialog box template.

hResource

Customized template handle.

lpSrcDataObj

Pointer to the IDataObject* interface of the data object to be pasted (from the clipboard). This field is filled on input. If lpSrcDataObj is NULL when OleUIPasteSpecial is called, then OleUIPasteSpecial will attempt to retrieve a pointer to an IDataObject from the clipboard. If OleUIPasteSpecial succeeds, it is the caller’s responsibility to free the IDataObject returned in lpSrcDataObj.

arrPasteEntries

The OLEUIPASTEENTRY array which specifies acceptable formats. This field is filled on input.

cPasteEntries

Number of OLEUIPASTEENTRY array entries. This field is filled on input.

arrLinkTypes

List of link types that are acceptable. Link types are referred to using OLEUIPASTEFLAG in arrPasteEntries. This field is filled on input.

cLinkTypes

Number of link types. This field is filled on input.

cClsidExclude

Number of CLSIDs in lpClsidExclude. This field is filled on input.

lpClsidExclude

Pointer to an array of CLSIDs to exclude from the list of available server objects for a Paste operation. Note that this does not affect Paste Link. An application can prevent embedding into itself by listing its own CLSID in this list. This field is filled on input.

nSelectedIndex

Index of arrPasteEntries[] that the user selected. This field is filled on output.

fLink

Whether Paste or Paste Link was selected by the user. This field is filled on output.

hMetaPict

Handle to the Metafile containing the icon and icon title selected by the user. This field is filled on output.

sizel

Size of object as displayed in its source, if the display aspect chosen by the user matches the aspect displayed in the source. If the user chooses a different aspect, then sizel.cx and sizel.cy are both set to zero. The size of the object as it is displayed in the source is retrieved from the ObjectDescriptor if fLink is FALSE and from the LinkSrcDescriptor if fLink is TRUE. This field is filled on output.

See Also

OleUIPasteSpecial, OLEUIPASTEENTRY, OLEUIPASTEFLAG


OLEUIVIEWPROPS

This structure is used to initialize the View tab of the Object properties dialog box. A reference to it is passed in as part of the OLEUIOBJECTPROPS structure to the OleUIObjectProperties function. This tab allows the user to toggle between “content” and “iconic” views of the object, and change its scaling within the container. It also allows the user to tunnel to the change icon dialog box when the object is being displayed iconically.

// These IN fields are standard across all OLEUI property pages.

typedef struct tagOLEUIVIEWPROPSA

{

// These IN fields are standard across all OLEUI property pages.

    DWORD          cbStruct;

    DWORD          dwFlags;

    DWORD          dwReserved1[2];

    LPFNOLEUIHOOK  lpfnHook;

    LPARAM         lCustData;

    DWORD          dwReserved2[3];

struct tagOLEUIOBJECTPROPS* lpOP;

    int       nScaleMin;

    int       nScaleMax;

} OLEUIVIEWPROPSA, *POLEUIVIEWPROPSA, FAR* LPOLEUIVIEWPROPSA;

Members

cbStruct

Size of the structure in bytes.

dwFlags

IN-OUT: flags specific to view page

VPF_SELECTRELATIVE

[in] Relative to origin.

VPF_DISABLERELATIVE

[in] Disable relative to origin.

VPF_DISABLESCALE

[in] Disable scale option.

dwReserved1[2]

Reserved for future use.

lpfnHook

Pointer to hook callback (not used in this dialog box).

lCustData

Custom data to pass to hook (not used in this dialog box).

dwReserved2[3];

Reserved for future use.

lpOP;

Used internally.

nScaleMin

Minimum value for the scale range.

nScaleMax

Maximum value for the scale range.

See Also

OleUIObjectProperties, OLEUIOBJECTPROPS


OLEVERB

The OLEVERB structure defines a verb that an object supports. The IOleObject::EnumVerbs method creates an enumerator that can enumerate these structures for an object, and supplies a pointer to the enumerator’s IEnumOLEVERB.

typedef struct tagOLEVERB

{

    LONG     lVerb;

    LPWSTR   lpszVerbName;

    DWORD    fuFlags;

    DWORD    grfAttribs;

} OLEVERB, * LPOLEVERB;

Members

lVerb

Integer identifier associated with this verb.

lpszVerbName

Pointer to a string that contains the verb’s name.

fuFlags

In Windows, a group of flags taken from the flag constants beginning with MF_ defined in AppendMenu. Containers should use these flags in building an object’s verb menu. All Flags defined in AppendMenu are supported except for MF_BITMAP, MF_OWNERDRAW, and MF_POPUP.

grfAttribs

Combination of the verb attributes in the OLEVERBATTRIB enumeration.

See Also

IEnumOLEVERB, IOleObject::EnumVerbs


PICTDESC

The PICTDESC structure contains parameters to create a picture object through the OleCreatePictureIndirect function.

typedef struct tagPICTDESC

{

    UINT cbSizeOfStruct;

    UINT picType;

    union

    {

        struct

        {

            HBITMAP hbitmap;

            HPALETTE hpal;

        } bmp;

        struct

        {

            HMETAFILE hmeta;

            int xExt;

            int yExt;

        } wmf;

        struct

        {

            HICON hicon;

        } icon;

        struct

        {

            HENHMETAFILE hemf;

        } emf;

    } ;

} PICTDESC;

Members

cbSizeOfStruct

Size of the PICTDESC structure.

picType

Type of picture described by this structure, which can be any value from the PICTYPE enumeration.

bmp

Structure containing bitmap information if picType is PICTYPE_BITMAP.

bmp.hbitmap

The HBITMAP identifying the bitmap assigned to the picture object.

bmp.hpal

The HPALETTE identifying the color palette for the bitmap.

wmf

Structure containing metafile information if picType is PICTYPE_METAFILE.

wmf.hmeta

The HMETAFILE handle identifying the metafile assigned to the picture object.

wmf.xExt

Horizontal extent of the metafile in HIMETRIC units.

wmf.yExt

Vertical extent of the metafile in HIMETRIC units.

icon

Identifies a structure containing icon information if picType is PICTYPE_ICON.

icon.hicon

The HICON identifying the icon assigned to the picture object.

emf

Structure containing enhanced metafile information if picType is PICTYPE_ENHMETAFILE.

emf.hemf

The HENHMETAFILE identifying the enhanced metafile to assign to the picture object.

See Also

OleCreatePictureIndirect, PICTYPE


POINTF

The POINTF structure is used in the IOleControlSite::TransformCoords method to convert between container units, expressed in floating point, and control units, expressed in HIMETRIC. The POINTF structure specifically holds the floating point container units. Controls do not attempt to interpret either value in the structure.

typedef struct tagPOINTF

{

    float x;

    float y;

} POINTF;

Members

x

The x-coordinates of the point in units that the container finds convenient.

y

The y coordinates of the point in units that the container finds convenient.

See Also

IControlOleSite::TransformCoords


PROPPAGEINFO

The PROPPAGEINFO structure contains parameters used to describe a property page to a property frame. A property page fills a caller-provided structure in the IPropertyPage::GetPageInfo method.

The pszTitle, pszDocString, and the pszHelpFile members specified in this structure should contain text sensitive to the locale obtained through IPropertyPageSite::GetLocaleID.

typedef struct tagPROPPAGEINFO

{

    ULONG     cb;

    LPOLESTR  pszTitle;

    SIZE      size;

    LPOLESTR  pszDocString;

    LPOLESTR  pszHelpFile;

    DWORD     dwHelpContext;

} PROPPAGEINFO;

Members

cb

Size of the PROPPAGEINFO structure.

pszTitle

Pointer to the string that appears in the tab for this page. The string must be allocated with CoTaskMemAlloc. The caller of IPropertyPage::GetPageInfo is responsible for freeing the memory with CoTaskMemFree.

size

Required dimensions of the page’s dialog box, in pixels.

pszDocString

Pointer to a text string describing the page, which can be displayed in the property sheet dialog box (current frame implementation doesn’t use this field). The text must be allocated with CoTaskMemAlloc. The caller of IPropertyPage::GetPageInfo is responsible for freeing the memory with CoTaskMemFree.

pszHelpFile

Pointer to the simple name of the help file that describes this property page used instead of implementing IPropertyPage::Help. When the user presses Help, the Help method is normally called. If that method fails, the frame will open the help system with this help file (prefixed with the value of the HelpDir key in the property page’s registry entries under its CLSID) and will instruct the help system to display the context described by the dwHelpContext field. The path must be allocated with CoTaskMemAlloc. The caller of IPropertyPage::GetPageInfo is responsible for freeing the memory with CoTaskMemFree.

dwHelpContext

Context identifier for the help topic within pszHelpFile that describes this page.

See Also

CoTaskMemAlloc, CoTaskMemFree, IPropertyPageSite::GetLocaleID, IPropertyPage::GetPageInfo, IPropertyPage::Help


PROPSPEC

The PROPSPEC structure is used by many of the methods of IPropertyStorage to specify a property either by its property identifier or the associated string name. The structure and related definitions are defined as follows in the header files:

const ULONG    PRSPEC_LPWSTR = 0

const ULONG    PRSPEC_PROPID = 1

typedef ULONG    PROPID

typedef struct tagPROPSPEC

{

    ULONG ulKind;        // PRSPEC_LPWSTR or PRSPEC_PROPID

    union

    {

    PROPID      propid;

    LPOLESTR    lpwstr;

    }

} PROPSPEC

Members

ulKind

If ulKind is set to PRSPEC_LPWSTR, lpwstr is used and set to a string name. If ulKind is set to PRSPEC_PROPID, propid is used and set to a property identifier value.

propid

Specifies the value of the property identifier. Use either this value or the following lpwstr, not both.

lpwstr

Specifies the string name of the property as a null-terminated Unicode string.

Remarks

String names are optional and can be assigned to a set of properties when the property is created with a call to IPropertyStorage::WriteMultiple, or later, with a call to IPropertyStorage::WritePropertyNames.

See Also

IPropertyStorage


PROPVARIANT

The PROPVARIANT structure is used in most of the methods of IPropertyStorage to define the type tag and the value of a property in a property set. There are five members. The first, the value type tag, and the last, the value of the property, are significant. The middle three are reserved for future use. The PROPVARIANT structure is defined as follows:

Note  The bool member in previous definitions of this structure has been renamed to boolVal, since some compilers now recognize bool as a keyword.

struct PROPVARIANT{

    VARTYPE        vt;          // value type tag

    WORD           wReserved1;

    WORD           wReserved2;

    WORD           wReserved3;

    union {

    // none                     // VT_EMPTY, VT_NULL, VT_ILLEGAL

    unsigned char  bVal;        // VT_UI1

    short          iVal;        // VT_I2

    USHORT         uiVal;       // VT_UI2

    long           lVal;        // VT_I4

    ULONG          ulVal;       // VT_UI4

    LARGE_INTEGER  hVal;        // VT_I8

    ULARGE_INTEGER uhVal;       // VT_UI8

    float          fltVal;      // VT_R4

    double         dblVal;      // VT_R8

    CY             cyVal;       // VT_CY

    DATE           date;        // VT_DATE

    BSTR           bstrVal;     // VT_BSTR

    VARIANT_BOOL   boolVal;        // VT_BOOL

    SCODE          scode;       // VT_ERROR

    FILETIME       filetime;    // VT_FILETIME

    LPSTR          pszVal;      // VT_LPSTR     // string in the current system Ansi code page

    LPWSTR         pwszVal;     // VT_LPWSTR    // string in Unicode

    CLSID*         puuid;       // VT_CLSID

    CLIPDATA*      pclipdata;   // VT_CF

    BLOB           blob;        // VT_BLOB, VT_BLOBOBJECT

    IStream*       pStream;     // VT_STREAM, VT_STREAMED_OBJECT

    IStorage*      pStorage;    // VT_STORAGE, VT_STORED_OBJECT

    CAUB           caub;         // VT_VECTOR | VT_UI1

    CAI            cai;          // VT_VECTOR | VT_I2

    CAUI           caui;         // VT_VECTOR | VT_UI2

    CAL            cal;          // VT_VECTOR | VT_I4

    CAUL           caul;         // VT_VECTOR | VT_UI4

    CAH            cah;          // VT_VECTOR | VT_I8

    CAUH           cauh;         // VT_VECTOR | VT_UI8

    CAFLT          caflt;        // VT_VECTOR | VT_R4

    CADBL          cadbl;        // VT_VECTOR | VT_R8

    CACY           cacy;         // VT_VECTOR | VT_CY

    CADATE         cadate;       // VT_VECTOR | VT_DATE

    CABSTR         cabstr;       // VT_VECTOR | VT_BSTR

    CABOOL         cabool;       // VT_VECTOR | VT_BOOL

    CASCODE        cascode;      // VT_VECTOR | VT_ERROR

    CALPSTR        calpstr;      // VT_VECTOR | VT_LPSTR

    CALPWSTR       calpwstr;     // VT_VECTOR | VT_LPWSTR

    CAFILETIME     cafiletime;   // VT_VECTOR | VT_FILETIME

    CACLSID        cauuid;       // VT_VECTOR | VT_CLSID

    CACLIPDATA     caclipdata;   // VT_VECTOR | VT_CF

    CAPROPVARIANT  capropvar;    // VT_VECTOR | VT_VARIANT

    }} PROPVARIANT

Remarks

PROPVARIANT is the fundamental data type by which property values are read and written through the IPropertyStorage interface.

The data type PROPVARIANT is related to the data type VARIANT, defined as part of Automation in OLE2 and defined in the Win32 SDK header file oleauto.h. Several definitions are reused from Automation, as follows:

typedef struct  tagCY {

    unsigned long      Lo;

    long               Hi;

    } CY

typedef CY             CURRENCY;

typedef short          VARIANT_BOOL;

typedef unsigned short VARTYPE;

typedef double         DATE;

typedef OLECHAR*       BSTR;

typedef struct         tagCLIPDATA {

    ULONG              cbSize;  //Includes sizeof(ulClipFmt)

    long               ulClipFmt;

    BYTE*              pClipData;

    } CLIPDATA

In addition, several new data types that define counted arrays of other data types are required. The data types of all counted arrays begin with the letters CA (such as CAUB) and have an ORed vt value. The counted array structure has the following form (where name is the specific name of the counted array):

#define TYPEDEF_CA(type, name)

    typedef struct tag ## name {\

        ULONG cElems;\

        type *pElems;\

        } name

Propvariant Type	Code	Propvariant Member	Value Representation
VT_EMPTY	0	None	A property with a type indicator of VT_EMPTY has no data associated with it; that is, the size of the value is zero.
VT_NULL	1	None	This is like a pointer to NULL.
VT_UI1	17	bVal	1-byte unsigned integer
VT_I2	2	iVal	Two bytes representing a 2-byte signed integer value.
VT_UI2	18	uiVal	2-byte unsigned integer
VT_I4	3	lVal	4-byte signed integer value
VT_UI4	19	ulVal	4-byte unsigned integer
VT_I8	20	hVal	8-byte signed integer
VT_UI8	21	uhVal	8-byte unsigned integer
VT_R4	4	fltVal	32-bit IEEE floating point value
VT_R8	5	dblVal	64-bit IEEE floating point value
VT_CY	6	cyVal	8-byte two's complement integer (scaled by 10,000). This type is commonly used for currency amounts.
VT_DATE	7	date	A 64-bit floating point number representing the number of days (not seconds) since December 31, 1899. For example, January 1, 1900 is 2.0, January 2, 1900 is 3.0, and so on). This is stored in the same representation as VT_R8.
VT_BSTR	8	bstrVal	Pointer to a null terminated Unicode string. The string is immediately preceded by a DWORD representing the byte count, but bstrVal points past this DWORD to the first character of the string. BSTRs must be allocated and freed using the OLE Automation SysAllocString and SysFreeString calls.
VT_BOOL	11	boolVal (bool in earlier designs)	Boolean value, a WORD containing 0 (false) or -1 (true).
VT_ERROR	10	scode	A DWORD containing a status code.
VT_FILETIME	64	filetime	64-bit FILETIME structure as defined by Win32. It is recommended that all times be stored in Universal Coordinate Time (UTC).
VT_LPSTR	30	pszVal	Pointer to a null terminated ANSI string in the system default code page.
VT_LPWSTR	31	pwszVal	Pointer to a null terminated Unicode string in the user’s default locale.
VT_CLSID	72	puuid	Pointer to a CLSID (or other GUID).
VT_CF	71	pclipdata	Pointer to a CLIPDATA structure, described above.
VT_BLOB	65	blob	DWORD count of bytes, followed by that many bytes of data. The byte count does not include the four bytes for the length of the count itself; an empty BLOB would have a count of zero, followed by zero bytes. This is similar to VT_BSTR but does not guarantee a null byte at the end of the data.
VT_BLOBOBJECT	70	blob	A BLOB containing a serialized object in the same representation as would appear in a VT_STREAMED_OBJECT. That is, a DWORD byte count (where the byte count does not include the size of itself) which is in the format of a class identifier followed by initialization data for that class. The only significant difference between VT_BLOB_OBJECT and VT_STREAMED_OBJECT is that the former does not have the system-level storage overhead that the latter would have, and is therefore more suitable for scenarios involving numbers of small objects.
VT_STREAM	66	pStream	Pointer to an IStream interface, representing a stream which is a sibling to the “Contents” stream.
VT_STREAMED_ OBJECT	68	pStream	As in VT_STREAM, but indicates that the stream contains a serialized object, which is a CLSID followed by initialization data for the class. The stream is a sibling to the Contents stream that contains the property set.
VT_STORAGE	67	pStorage	Pointer to an IStorage interface, representing a storage object that is a sibling to the “Contents” stream.
VT_STORED_ OBJECT	69	pStorage	As in VT_STORAGE, but indicates that the designated IStorage contains a loadable object.
VT_VECTOR	0x1000	ca*	If the type indicator is one of the simple propvariant types ORed with this one, the value is one of the counted array values. This is a DWORD count of elements, followed by that many repetitions of the value. For example, a type indicator of VT_LPSTR|VT_VECTOR has a DWORD element count, a DWORD byte count, the first string data, padding bytes for 32-bit alignment (see below), a DWORD byte count, the second string data, and so on. Nonsimple types cannot be ORed with VT_VECTOR. These types are VT_STREAM, VT_STREAM_OBJECT, VT_STORAGE, VT_STORAGE_OBJECT. VT_BLOB and VT_BLOB_OBJECT types also cannot be ORed with VT_VECTOR.
VT_VARIANT	12	capropvar	A DWORD type indicator followed by the corresponding value. VT_VARIANT can be used only with VT_VECTOR.
VT_TYPEMASK	0xFFF		Used as a mask for VT_VECTOR and other modifiers to extract the raw VT value.
Clipboard format identifiers, stored with the tag VT_CF, use one of five different representations (identified in the ulClipFmt member of the CLIPDATA structure):

ulClipFmt Value	pClipData value
-1L	a DWORD containing a built-in Windows clipboard format value.
-2L	a DWORD containing a Macintosh clipboard format value.
-3L	a GUID containing a format identifier (rarely used).
any positive value	a null-terminated string containing a Windows clipboard format name, one suitable for passing to RegisterClipboardFormat. The code page used for characters in the string is per the code page indicator. The “positive value” here is the length of the string, including the null byte at the end.
0L	no data (rarely used)
Within a vector of values, each repetition of a value is to be aligned to 32-bit boundaries. The exception to this rule is scalar types which are less than 32 bits:  VT_UI1, VT_12, VT_U12, and VT_BOOL. Vectors of these values are packed.

Therefore, a value with type tag VT_I2 | VT_VECTOR would be a DWORD element count, followed by a sequence of packed 2-byte integers with no padding between them.

However, a value with type tag VT_LPSTR | VT_VECTOR would be a DWORD element count, followed by a sequence of (DWORD cch, char rgch[]) strings, each of which may be followed by null padding to round to a 32-bit boundary.


QACONTAINER

The QACONTAINER structure is used in IQuickActivate::QuickActivate to specify container information.

typedef struct tagQACONTAINER

{

    ULONG                  cbSize;

    IOleClientSite*        pClientSite;

    IAdviseSinkEx*         pAdviseSink;

    IPropertyNotifySink*   pPropertyNotifySink;

    IUnknown*              pUnkEventSink;

    DWORD                 dwAmbientFlags;

    OLE_COLOR             colorFore;

    OLE_COLOR             colorBack;

    IFont*                pFont;

    IOleUndoManager*      pUndoMgr;

    DWORD                dwAppearance;

    LONG                 lcid;

    HPALETTE             hpal;

    struct IBindHost*    pBindHost;

}    QACONTAINER;

Members

cbsize

Specifies the size of the structure in bytes.

pClientSite

Pointer to an IOleClientSite interface in the container.

pAdviseSink

Pointer to an IAdviseSinkEx interface in the container.

pPropertyNotifySink

Pointer to an IPropertyNotifySink interface in the container.

pUnkEventSink

Pointer to an IUnknown interface on the container’s sink object.

dwAmbientFlags

Specifies a number of ambient properties supplied by the container using values from the QACONTAINERFLAGS enumeration.

colorFore

Specifies ForeColor, an ambient property supplied by the container with a DISPID = -704.

colorBack

Specifies BackColor, an ambient property supplied by the container with a DISPID = -701.

pFont

Specifies Font, an ambient property supplied by the container with a DISPID = -703.

pUndoMgr

Pointer to an IOleUndoManager interface in the container.

dwAppearance

Specifies Appearance, an ambient property supplied by the container with a DISPID = -716.

lcid

Specifies LocaleIdentifier, an ambient property supplied by the container with a DISPID = -705.

hPal

Specifies Palette, an ambient property supplied by the container with a DISPID = -726.

pBindHost

Pointer to an IBindHost interface in the container.

Remarks

If an interface pointer in the QACONTAINER structure is NULL it does not indicate that the interface is not supported. In this situation, the control should use QueryInterface to obtain the interface pointer in the standard manner.

See Also

IQuickActivate::QuickActivate, QACONTAINERFLAGS


QACONTROL

The QACONTROL structure is used in IQuickActivate::QuickActivate to specify control information.

typedef struct tagQACONTROL

{

    ULONG    cbSize;

    DWORD    dwMiscStatus;

    DWORD    dwViewStatus;

    DWORD    dwEventCookie;

    DWORD    dwPropNotifyCookie;

    DWORD    dwPointerActivationPolicy;

}QACONTROL;

Members

cbsize

Size of the structure in bytes.

dwMiscStatus

Specifies the control’s miscellaneous status bits that can also be returned by IOleObject::GetMiscStatus. See OLEMISC for more information.

dwViewStatus

Specifies the control’s view status that can also be returned by IViewObjectEx::GetViewStatus. See VIEWSTATUS for more information.

dwEventCookie

Unique identifier for control-defined events.

dwPropNotifyCookie

Unique identifier for control-defined properties.

dwPointerActivationPolicy

Specifies the control’s activation policy that can also be returned by IPointerInactive::GetActivationPolicy. If all the bits of dwPointerActivationPolicy are set, then the IPointerInactive interface may not be supported. The container should QueryInterface to obtain the interface pointer in the standard manner.

See Also

IQuickActivate::QuickActivate


RemSNB

The RemSNB structure is used for marshaling the SNB data type.

Defined in the IStorage interface (storag.idl).

typedef struct tagRemSNB {

    unsigned                long     ulCntStr;

    unsigned                long     ulCntChar;

    [size_is(ulCntChar)]    wchar_t  rgString[];

} RemSNB;

typedef [transmit_as(RemSNB)] wchar_t  **SNB;

Members

ulCntStr

Number of strings in the rgString buffer.

ulCntChar

Size in bytes of the rgString buffer.

rgString

Pointer to an array of bytes containing the stream name strings from the SNB.

See Also

IStorage


SNB

A string name block (SNB) is a pointer to an array of pointers to strings, that ends in a NULL pointer. String name blocks are used by the IStorage interface and by function calls that open storage objects. The strings point to contained storage objects or streams that are to be excluded in the open calls.

typedef OLESTR **SNB

Remarks

The SNB should be created by allocating a contiguous block of memory in which the pointers to strings are followed by a NULL pointer, which is then followed by the actual strings.

The marshaling of a string name block is based on the assumption that the SNB passed in was created this way. Although it could be stored in other ways, the SNB created in this manner has the advantage of requiring only one allocation operation and one freeing of memory for all the strings.

See Also

IStorage


SOLE_AUTHENTICATION_SERVICE

Identifies an authentication service. This structure is retrieved through a call to CoQueryAuthenticationServices, and passed in to CoInitializeSecurity.

    typedef struct tagSOLE_AUTHENTICATION_SERVICE {

        DWORD       dwAuthnSvc;

        DWORD       dwAuthzSvc;

        OLECHAR*    pPrincipalName;

        HRESULT     hr;

    } SOLE_AUTHENTICATION_SERVICE;

Members

dwAuthnSvc

The authentication service. It may contain a single value taken from the list of RPC_C_AUTHN_xxx constants defined in rpcdce.h. RPC_C_AUTHN_NONE turns off authentication. On Win32, RPC_C_AUTHN_DEFAULT causes COM to use the RPC_C_AUTHN_WINNT authentication.

dwAuthzSvc

The authorization service. It may contain a single value taken from the list of RPC_C_AUTHZ_xxx constants defined in rpcdce.h. The validity and trustworthiness of authorization data, like any application data, depends on the authentication service and authentication level selected. This parameter is ignored when using the RPC_C_AUTHN_WINNT authentication service.

pPrincipalName

Principal name to be used with the authentication service. If the principal name is NULL, COM assumes the current user identifier. A NULL principal name is allowed for NT LM SSP and kerberos authentication services, but may not work for other authentication services.

hr

When used in CoInitializeSecurity, set on return to indicate the status of the call to register the authentication services.

See Also

RPC_C_AUTHN_xxx, RPC_C_AUTHZ_xxx, CoInitializeSecurity


STATDATA

The STATDATA structure is the data structure used to specify each advisory connection. It is used for enumerating current advisory connections. It holds data returned by the IEnumSTATDATA enumerator. This enumerator interface is returned by IDataObject:DAdvise. Each advisory connection is specified by a unique STATDATA structure.

typedef struct tagSTATDATA

{

    FORMATETC     formatetc;

    DWORD         grfAdvf;

    IAdviseSink*  pAdvSink;

    DWORD         dwConnection;

} STATDATA;

Members

formatetc

The FORMATETC structure for the data of interest to the advise sink. The advise sink receives notification of changes to the data specified by this FORMATETC structure.

grfAdvf

The ADVF enumeration value that determines when the advisory sink is notified of changes in the data.

pAdvSink

The pointer for the IAdviseSink interface that will receive change notifications.

dwConnection

The token that uniquely identifies the advisory connection. This token is returned by the method that sets up the advisory connection.

See Also

IEnumSTATDATA


STATPROPSETSTG

Contains information about a property set. To get this information, call IPropertyStorage::Stat, which fills in a buffer containing the information describing the current property set. To enumerate the STATPROPSETSTG structures for the property sets in the current property set storage, call IPropertySetStorage::Enum to get a pointer to an enumerator. You can then call the enumeration methods of the IEnumSTATPROPSETSTG interface on the enumerator. The structure is defined as follows:

typedef struct tagSTATPROPSETSTG {

    FMTID       fmtid;

    CLSID       clsid;

    DWORD       grfFlags;

    FILETIME    mtime;

    FILETIME    ctime;

    FILETIME    atime;

    } STATPROPSETSTG

Members

fmtid

Format identifier of the current property set.

clsid

The CLSID associated with this property set.

grfFlags

Flag values of the property set, as specified in IPropertySetStorage::Create.

mtime

Time in Universal Coordinated Time (UTC) that the property set was last modified.

ctime

Time in UTC at which this property set was created.

atime

Time in UCT at which this property set was last accessed.

See Also

IPropertySetStorage::Create, IEnumSTATPROPSETSTG, IPropertyStorage::Stat, FILETIME structure


STATPROPSTG

Each STATPROPSTG structure contains information about a single property in a property set. This information is the property identifier and type tag, and the optional string name that may be associated with the property.

IPropertyStorage::Enum supplies a pointer to the IEnumSTATPROPSTG interface on an enumerator object that can be used to enumerate through the STATPROPSTG structures for the properties in the current property set. STATPROPSTG is defined as follows:

typedef struct    tagSTATPROPSTG {

    LPWSTR        lpwstrName;

    PROPID        propid;

    VARTYPE       vt;

} STATPROPSTG

Members

lpwstrName

Wide-character string containing the optional string name that can be associated with the property. May be NULL. This member must be freed using CoTaskMemFree.

propid

A 32-bit identifier that uniquely identifies the property within the property set. All properties within property sets must have unique property identifiers.

vt

Type of the property.

See Also

IPropertyStorage::Enum, IEnumSTATPROPSTG


STATSTG

The STATSTG structure contains statistical information about an open storage, stream, or byte array object. This structure is used in the IEnumSTATSTG, ILockBytes, IStorage, and IStream interfaces.

typedef struct tagSTATSTG

{

    LPWSTR          pwcsName;

    DWORD           type;

    ULARGE_INTEGER  cbSize;

    FILETIME        mtime;

    FILETIME        ctime;

    FILETIME        atime;

    DWORD           grfMode;

    DWORD           grfLocksSupported;

    CLSID           clsid;

    DWORD           grfStateBits;

    DWORD           reserved;

} STATSTG;

Members

pwcsName

Points to a NULL-terminated string containing the name. Space for this string is allocated by the method called and freed by the caller (refer to CoTaskMemFree). You can specify not to return this member by specifying the STATFLAG_NONAME value when you call a method that returns a STATSTG structure, except for calls to IEnumSTATSTG::Next, which provides no way to specify this value.

type

Indicates the type of storage object. This is one of the values from the STGTY enumeration.

cbSize

Specifies the size in bytes of the stream or byte array.

mtime

Indicates the last modification time for this storage, stream, or byte array.

ctime

Indicates the creation time for this storage, stream, or byte array.

atime

Indicates the last access time for this storage, stream or byte array.

grfMode

Indicates the access mode specified when the object was opened. This member is only valid in calls to Stat methods.

grfLocksSupported

Indicates the types of region locking supported by the stream or byte array. See the LOCKTYPES enumeration for the values available. This member is not used for storage objects.

clsid

Indicates the class identifier for the storage object; set to CLSID_NULL for new storage objects. This member is not used for streams or byte arrays.

grfStateBits

Indicates the current state bits of the storage object, that is, the value most recently set by the IStorage::SetStateBits method. This member is not valid for streams or byte arrays.

dwStgFmt

Indicates the format of the storage object. This is one of the values from the STGFMT enumeration.

See Also

IStorage::SetElementTimes


STORAGELAYOUT

The STORAGELAYOUT structure describes a single block of data, including its name, location, and length. To optimize a compound file, an application or layout tool passes an array of StorageLayout structures in a call to ILayoutStorage::LayoutScript.

typedef struct tagSTORAGELAYOUT

{

    DWORD           LayoutType;

    OLECHAR*        pwcsElementName;

    LARGE_INTEGER   cOffset;

    LARGE_INTEGER   cBytes;

} STORAGELAYOUT;

Members

LayoutType

The type of element to be written. Values are taken from the STGTY enumeration. STGTY_STREAM means read the block of data named by pwcsElementName. STGTY_STORAGE means open the storage specified in pwcsElementName. STGTY_REPEAT is used in multimedia applications to interlace audio, video, text, and other elements. An opening STGTY_REPEAT elements means that the elements that follow are to be repeated a specified number of times. The closing STGTY_REPEAT element marks the end of those elements that are to be repeated. Nested STGY_REPEAT pairs are permitted.

pwcsElementName

The name of the storage or stream. If the element is a substorage or embedded object, the fully qualified storage path must be specified; for example:RootStorageName\SubStorageName\Substream.

cOffset

Where LayoutType is STGTY_STREAM, this flag specifies the beginning offset into the steam named in pwscElementName.

Where LayoutType is STGTY_STORAGE, this flag should be set to zero.

Where LayoutType is STGTY_REPEAT, this flag should be set to zero.

cBytes

Length in bytes of the data block named in pwcsElementName.

Where LayoutType is STGTY_STREAM, cBytes specifies the number of bytes to read at offset cOffset from the stream nemaed in pwcsElementName.

Where LayoutType is STGTY_STORAGE, this flag is ignored.

Where LayoutType is STGTY_REPEAT, a positive cBytes specifies the beginning of a repeat block. STGTY_REPEAT with zero cBytes marks the end of a repeat block.

A beginning block value of STG_TOEND specifies that elements in a following block are to be repeated after each stream has been completely read.

An array of StorageLayout structures might appear as follows:

StorageLayout arrScript[]=

    // Read first 2k of “WordDocument” stream

    {STGTY_STREAM,L”WordDocument”,{0,0},{0,2048}},

    //Test if “ObjectPool\88112233” storage exists

    {STGTY_STORAGE,L”ObjectPool\\88112233”,{0,0},{0,0}},

    //Read 2k at offset 1048 of “WordDocument” stream

    {STGTY_STREAM,L”WordDocument”,{0,10480},{0,2048}},

    //Interlace “Audio”, “Video”, and “Caption” streams

    {STGTY_REPEAT,NULL,0,STG_TOEND},

        {STGTY_STREAM,L”Audio”, {0,0},{0,2048}},    // 2k of Audio

        {STGTY_STREAM,L”Video”, {0,0},{0,65536}},   // 64k of Video

        {STGTY_STREAM,L”Caption”, {0,0},{0,128}},   // 128b of text

    {STGTY_REPEAT,NULL, {0,0},{0,0}}

};

Note  The parameters cOffest and cBytes are LARGE_INTEGER structures and they must be represented as a structure with {LARGE_INTEGER} or {DWORD lowpart, LONG highpart}.

See Also

ILayoutStorage::LayoutScript


STGMEDIUM

The STGMEDIUM structure is a generalized global memory handle used for data transfer operations by the IAdviseSink, IDataObject, and IOleCache interfaces.

typedef struct tagSTGMEDIUM

{

    DWORD tymed;

    [switch_type(DWORD), switch_is((DWORD) tymed)]

    union {

        [case(TYMED_GDI)]      HBITMAP        hBitmap;

        [case(TYMED_MFPICT)]   HMETAFILEPICT  hMetafilePict;

        [case(TYMED_ENHMF)]    HENHMETAFILE   hEnhMetaFile;

        [case(TYMED_HGLOBAL)]  HGLOBAL        hGlobal;

        [case(TYMED_FILE)]     LPWSTR         lpszFileName;

        [case(TYMED_ISTREAM)]  IStream        *pstm;

        [case(TYMED_ISTORAGE)] IStorage       *pstg;

        [default] ;

    };

    [unique] IUnknown *pUnkForRelease;

}STGMEDIUM;

typedef STGMEDIUM *LPSTGMEDIUM;

Members

tymed

Type of storage medium. The marshaling and unmarshaling routines use this value to determine which union member was used. This value must be one of the elements of the TYMED enumeration.

union member

Handle, string, or interface pointer that the receiving process can use to access the data being transferred. If tymed is TYMED_NULL, the union member is undefined; otherwise, it is one of the following:

hBitmap

Bitmap handle. The tymed member is TYMED_GDI.

hMetafilePict

Metafile handle. The tymed member is TYMED_MFPICT.

hEnhMetaFile

Enhanced metafile handle. The tymed member is TYMED_ENHMF.

hGlobal

Global memory handle. The tymed member is TYMED_HGLOBAL.

lpszFileName

Pointer to the path of a disk file that contains the data. The tymed member is TYMED_FILE.

pstm

Pointer to an IStream interface. The tymed member is TYMED_ISTREAM.

pstg

Pointer to an IStorage interface. The tymed member is TYMED_ISTORAGE.

pUnkForRelease

Pointer to an interface instance that allows the sending process to control the way the storage is released when the receiving process calls the ReleaseStgMedium function. If pUnkForRelease is NULL, ReleaseStgMedium uses default procedures to release the storage; otherwise, ReleaseStgMedium uses the specified IUnknown interface.

See Also

FORMATETC, IAdviseSink, IDataObject, IOleCache, ReleaseStgMedium


Objects, Properties, and Methods

This reference contains property and method information for the OLE Messaging Library objects.

The following table summarizes each object’s properties and methods.

Object	Available in version	Properties	Methods
AddressEntries collection	1.1	Application, Class, Count, Filter, Item, Parent, Session	Add, Delete, GetFirst, GetLast, GetNext, GetPrevious
AddressEntry	1.0	Address, Application, Class, DisplayType, Fields, ID, Members, Name, Parent, Session, Type	Delete, Details, IsSameAs, Update
AddressEntryFilter	1.1	Address, Application, Class, Fields, Name, Not, Or, Parent, Session	IsSameAs
AddressList	1.1	AddressEntries, Application, Class, ID, Index, IsReadOnly, Name, Parent, Session	IsSameAs
AddressLists collection	1.1	Application, Class, Count, Item, Parent, Session	(none)
Attachment	1.0	Application, Class, Fields, Index, Name, Parent, Position, Session, Source, Type	Delete, IsSameAs, ReadFromFile, WriteToFile
Attachments collection	1.0	Application, Class, Count, Item, Parent, Session	Add, Delete
Field	1.0	Application, Class, ID, Index, Name, Parent, Session, Type, Value	Delete, ReadFromFile, WriteToFile
Fields collection	1.0	Application, Class, Count, Item, Parent, Session	Add, Delete, SetNamespace
Folder	1.0	Application, Class, Fields, FolderID, Folders, ID, MAPIOBJECT*, Messages, Name, Parent, Session, StoreID	CopyTo, Delete, IsSameAs, MoveTo, Update
Folders collection	1.0	Application, Class, Count, Item, Parent, Session	Add, Delete, GetFirst, GetLast, GetNext, GetPrevious
InfoStore	1.0	Application, Class, ID, Index, Name, Parent, ProviderName, RootFolder, Session	IsSameAs
InfoStores collection	1.0	Application, Class, Count, Item, Parent, Session	(none)
Message	1.0	Application, Attachments, Class, Conversation, ConversationIndex, ConversationTopic, DeliveryReceipt, Encrypted, Fields, FolderID, ID, Importance, MAPIOBJECT*, Parent, ReadReceipt, Recipients, Sender, Sent, Session, Signed, Size, StoreID, Subject, Submitted, Text, TimeReceived, TimeSent, Type, Unread	CopyTo, Delete, IsSameAs, MoveTo, Options, Send, Update
MessageFilter	1.1	Application, Class, Conversation, Fields, Importance, Not, Or, Parent, Recipients, Sender, Sent, Session, Size, Sort, Subject, Text, TimeFirst, TimeLast, Type, Unread	IsSameAs
Messages collection	1.0	Application, Class, Count, Filter, Item, Parent, Session	Add, Delete, GetFirst, GetLast, GetNext, GetPrevious, Sort
Recipient	1.0	Address, AddressEntry, Application, Class, DisplayType, Index, Name, Parent, Session, Type	Delete, IsSameAs Resolve
Recipients collection	1.0	Application, Class, Count, Item, Parent, Resolved, Session	Add, Delete, Resolve
Session	1.0	AddressLists, Application, Class, CurrentUser, Inbox, InfoStores, MAPIOBJECT*, Name, OperatingSystem, Outbox, Parent, Session, Version	AddressBook, CompareIDs, DeliverNow, GetAddressEntry, GetFolder, GetInfoStore, GetMessage, Logoff, Logon
* The MAPIOBJECT property is not available to Visual Basic applications. For more information, see the reference for the MAPIOBJECT property.

This reference is organized by object, consisting of a summary of each object that lists its properties and methods, followed by reference documentation for the individual properties and methods. The properties and methods are organized alphabetically.

To avoid duplication, the section All OLE Messaging Library Objects describes the properties that have the same meaning for all OLE Messaging Library objects. These are:

•	Application

•	Class

•	Parent

•	Session


Object Model

The object model for the OLE Messaging Library is a hierarchical model. In the following table, each indented object is considered a child of the object under which it is indented. An object is the parent of every object at the next level of indentation under it. For example, an Attachments collection and a Recipients collection are both child objects of a Message object, and a Messages collection is a parent object of a Message object. However, a Messages collection is not a parent object of a Recipients collection.

Session
     AddressLists collection
          AddressList
               AddressEntries collection
                    AddressEntry
                         Fields collection
                              Field
                    AddressEntryFilter
                         Fields collection
                              Field
     Folder (Inbox or Outbox)
          Fields collection
               Field
          Folders collection
               Folder
                    … Folder …
          Messages collection
               Message
                    Attachments collection
                         Attachment
                    Fields collection
                         Field
                    Recipients collection
                         Recipient
                              AddressEntry
                                   Fields collection
                                        Field
               MessageFilter
                    Fields collection
                         Field
     InfoStores collection
          InfoStore
               Folder
                    … Folder …

The notation “… Folder …” signifies that a folder can contain other folders, which in turn can contain more folders, nested to an indefinite level.


All OLE Messaging Library Objects

All OLE Messaging Library objects contain the properties Application, Class, Parent, and Session. The Application and Session properties have the same values for all objects within a given session. The Parent property indicates the immediate parent of the object, and the Class property is an integer value that identifies the OLE Messaging Library object.

All four of these common properties have read-only access in all objects. Note that for the Session object, the Parent and Session properties are assigned the value Nothing. The Session object represents the highest level in the OLE Messaging Library object hierarchy and has no parent.

To reduce duplication, the detailed reference for these properties appears only once, in this section. The following table lists the properties that are common to all OLE Messaging Library objects and that have the same meaning for all objects.

Properties

Property name	Type	Access
Application	String	Read-only
Class	Long	Read-only
Parent	Object	Read-only
Session	Session object	Read-only
Several objects also have a Type property, but it is not defined for all objects and its meaning varies depending on the object. The following table summarizes the Type property.

Object	Description of the Type property
AddressEntry	The messaging system: SMTP, FAX, and so on
Attachment	The attachment type: mapiFileData, mapiFileLink, mapiOLE, or mapiEmbeddedMessage
Field	The field data type: vbInteger, vbLong, and so on
Message	The MAPI message class: IPM.Note, and so on
MessageFilter	The MAPI message class: IPM.Note, and so on
Recipient	The recipient type: To, Cc, or Bcc line
For detailed information about the Type property, see the reference documentation within each object.


Application Property

The Application property returns the name of the active application, which is the OLE Messaging Library, “OLE/Messaging”. Read-only.

Syntax

object.Application

Data Type

String

Remarks

The Application property always contains the string “OLE/Messaging”.

Note that this behavior for the Microsoft OLE Messaging Library differs from other implementations of OLE Automation servers. Many OLE Automation servers are based on executables (files that take the extension .EXE) and return an object value. The OLE Messaging Library is based on the MAPI subsystem, which is implemented by dynamic link libraries (files that take the extension .DLL).

As of version 1.1, the OLE Messaging Library is an in-process server, residing in a .DLL file and linking directly with the calling modules. In comparison with the former local server architecture, this removes the need for RPCs across process boundaries and greatly improves the performance of OLE Messaging Library calls.

Example

' Function: Session_Application

' Purpose: Display the Application property of the Session object

' See documentation topic: Application property

Function Session_Application()

Dim objSession As Object

    ' error handling

    Set objSession = CreateObject("MAPI.Session")

    If Not objSession Is Nothing Then

        MsgBox "Session’s Application property = " _

            & objSession.Application

    End If

    ' error handling

End Function

See Also

Version Property (Session Object)


Class Property

The Class property returns the object class of the object. Read-only.

Syntax

object.Class

Data Type

Long

Remarks

The Class property contains a numeric constant that identifies the OLE Messaging Library object. The following values are defined:

OLE Messaging Library object	Class ID value	Value
AddressEntries collection	21	mapiAddressEntries
AddressEntry	8	mapiAddressEntry
AddressEntryFilter	9	mapiAddressFilter
AddressList	7	mapiAddressList
AddressLists collection	20	mapiAddressLists
Attachment	5	mapiAttachment
Attachments collection	18	mapiAttachments
Field	6	mapiField
Fields collection	19	mapiFields
Folder	2	mapiFolder
Folders collection	15	mapiFolders
InfoStore	1	mapiInfoStore
InfoStores collection	14	mapiInfoStores
Message	3	mapiMsg
MessageFilter	10	mapiMessageFilter
Messages collection	16	mapiMessages
Recipient	4	mapiRecipient
Recipients collection	17	mapiRecipients
Session	0	mapiSession
Example

' Function: Util_DecodeObjectClass

' Purpose: Decode the long integer class value,

'          show the related object name

' See documentation topic: Class property

Function Util_DecodeObjectClass(lClass As Long)

    ' error handling here...

    Select Case (lClass)

        Case mapiSession:

            MsgBox ("Session object; class = " & lClass)

        Case mapiMsg:

            MsgBox ("Message object; class = " & lClass)

    End Select

    ' error handling

End Function

' Function: TestDrv_Util_DecodeObjectClass

' Purpose: Call the utility function DecodeObjectClass for Class values

' See documentation topic: Class property

Function TestDrv_Util_DecodeObjectClass()

    ' error handling here...

    If objSession Is Nothing Then

        MsgBox "Need to set the Session object: Session->Logon"

        Exit Function

    End If

    ' expect type mapiSession = 0 for Session object

    Util_DecodeObjectClass (objSession.Class)

    Set objMessages = objSession.Inbox.Messages

    Set objOneMsg = objSession.Inbox.Messages.GetFirst

    If objOneMsg Is Nothing Then  ' empty inbox

        Exit Function

    End If

    ' expect type mapiMessage = 3 for Message object

    Util_DecodeObjectClass (objOneMsg.Class)

    ' error handling here...

End Function

See Also

All OLE Messaging Library Objects


Parent Property

The Parent property returns the parent of the object. Read-only.

Syntax

object.Parent

Data Type

Object

Remarks

The Parent property in the OLE Messaging Library returns the immediate parent of an object. For example, the immediate parent for each object is shown in the following table.

OLE Messaging Library object	Immediate parent in object hierarchy
AddressEntries collection	AddressList object
AddressEntry (returned by Session.CurrentUser)	AddressEntries collection
AddressEntry (all others)	Recipient object
AddressEntryFilter	AddressEntries collection
AddressList	AddressLists collection
AddressLists collection	Session object
Attachment	Attachments collection
Attachments collection	Message object
Field	Fields collection
Fields collection	AddressEntry, AddressEntryFilter, Folder (Inbox or Outbox), Message, or MessageFilter object
Folder (Inbox or Outbox)	Session object
Folder (all others)	Folders collection or InfoStore object
Folders collection	Folder (Inbox or Outbox)
InfoStore	InfoStores collection
InfoStores collection	Session object
Message	Messages collection
MessageFilter	Messages collection
Messages collection	Folder (Inbox or Outbox)
Recipient	Recipients collection
Recipients collection	Message object
Session	Set to Nothing
Note that the Parent property represents the immediate parent of the object, rather than the logical parent. For example, a folder contains a Messages collection, which contains Message objects. The Parent property for a message is the immediate parent, the Messages collection, rather than the logical parent, the Folder object.

The Session Object object represents the highest level in the hierarchy of OLE Messaging Library objects and its Parent property is set to Nothing.

For more information on the OLE Messaging Library object hierarchy, see Object Model.

Example

This code fragment displays the name of the parent Messages collection of a Message object:

' Function: Message_Parent

Function Message_Parent()

    ' error handling here

    If objOneMsg Is Nothing Then

        MsgBox "Need to select a message; see Messages->Get*"

        Exit Function

    End If

    ' Immediate parent of message is the messages collection

    MsgBox "Message immediate parent class = " & objOneMsg.Parent.Class

    ' error handling code

End Function

To get to the Folder object, you have to take the parent of the Messages collection object:

' Function: Messages_Parent

' Purpose: Display the Messages collection Parent class value

' See documentation topic: Parent property

Function Messages_Parent()

    ' error handling here...

    If objMessages Is Nothing Then

        MsgBox "No active messages collection"

        Exit Function

    End If

    MsgBox "Messages collection parent has class value: " & _

            objMessages.Parent.Class

    Exit Function

    ' error handling here...

End Function


Session Property

The Session property returns the top-level Session object associated with the specified OLE Messaging Library object. Read-only.

Syntax

Set objSession = object.Session

Data Type

Object

Remarks

The Session object represents the highest level in the OLE Messaging Library object hierarchy. Its Session property is set to Nothing.

Example

' Function: Folder_Session

' Purpose: Access the Folder's Session property and display its name

' See documentation topic: Session property

Function Folder_Session()

Dim objSession2 As Object   ' session object to get the property

    ' error handling here...

    If objFolder Is Nothing Then

        MsgBox "No active folder; please select Session->Inbox"

        Exit Function

    End If

    Set objSession2 = objFolder.Session

    If objSession2 Is Nothing Then

        MsgBox "Unable to access Session property"

        Exit Function

    End If

    MsgBox "Folder's Session property name = " & objSession2.Name

    Set objSession2 = Nothing

    ' error handling here...

End Function


AddressEntries Collection Object

The AddressEntries collection object contains one or more AddressEntry objects.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.1
Parent objects:	AddressList
Child objects:	AddressEntry  AddressEntryFilter
Default property:	Item
An AddressEntries collection is considered a large collection, which means that the Count and Item properties have limited validity, and your best option is to use an AddressEntry object identifier value or the Get methods to access an individual AddressEntry object within the collection.

Properties

Property name	Available in version	Type	Access
Application	1.1	String	Read-only
Class	1.1	Long	Read-only
Count	1.1	Long	Read-only
Filter	1.1	AddressEntryFilter object	Read/write
Item	1.1	AddressEntry object	Read-only
Parent	1.1	AddressList object	Read-only
Session	1.1	Session object	Read-only
Methods

Method name	Available in version	Parameters
Add	1.1	emailtype as String,  (optional) name as String,  (optional) address as String
Delete	1.1	(none)
GetFirst	1.1	(none)
GetLast	1.1	(none)
GetNext	1.1	(none)
GetPrevious	1.1	(none)
Remarks

Each AddressEntry object in the collection holds information representing a person or process to which the messaging system can deliver messages. An AddressEntries collection provides access to the entries in a MAPI address book.


Add Method (AddressEntries Collection)

The Add method creates and returns a new AddressEntry object in the AddressEntries collection.

Syntax

Set objAddressEntry = objAddrEntriesColl.Add(emailtype [, name, address ] )

Parameters

objAddressEntry

On successful return, contains the new AddressEntry object.

objAddrEntriesColl

Required. The AddressEntries collection object.

emailtype

Required. String. The address type of the address entry.

name

Optional. String. The display name or alias of the address entry.

address

Optional. String. The full messaging address of the address entry.

Remarks

The emailtype parameter corresponds to the PR_ADDRTYPE property and qualifies the address parameter by specifying which messaging system the address is valid in. Typical values are SMTP, FAX, and X400.

The name and address parameters correspond to the Name and Address properties of the AddressEntry object.

The user must have permission to Add or Delete an AddressEntry object. Most users have this permission only for their personal address list (PAL).

The new AddressEntry object is saved in the MAPI system when you call its Update method.

Example

This code fragment adds a new entry to a user’s personal address list (PAL):

' get AddressEntries collection of PAL AddressList

Set myList = MAPI.Session.AddressLists(“Personal Address List”)

' add new AddressEntry to AddressEntries collection

Set newEntry = myList.Add “FAX”, “John Doe”

' add FaxNumber field to new AddressEntry and give it a value

newEntry.Fields.Add “FaxNumber”, vbString

newEntry.Fields(“FaxNumber”) = “+1-206-555-7069”

' commit new entry, field, and value to PAL AddressList

newEntry.Update


Count Property (AddressEntries Collection)

The Count property returns the number of AddressEntry objects in the collection, or a very large number if the exact count is not available. Read-only.

Syntax

objAddrEntriesColl.Count

Data Type

Long

Remarks

The Count property is useful for determining whether an AddressEntries collection is empty or not.

A large collection cannot always maintain an accurate count of its members, and the Count property cannot be used as the collection’s size when it has a very large value such as mapiMaxCount. Programmers needing to access individual objects in a large collection are strongly advised to use the Visual Basic For Each statement or the Get methods.

The recommended procedures for traversing a large collection are, in decreasing order of preference:

1.	Global selection, such as the Visual Basic For Each statement

2.	The Get methods, particularly GetFirst and GetNext

3.	An indexed loop, such as the Visual Basic For ... Next construction

If the address book provider cannot supply the precise number of AddressEntry objects, the OLE Messaging Library returns a very large number for the Count property. On 32-bit platforms, this value is mapiMaxCount, which equals 2^31 - 1, or 2147483647. On other platforms, mapiMaxCount is not defined, and the OLE Messaging Library returns -1. A program on such a platform must be careful that -1 does not prematurely terminate any iteration based on the Count property.

Programmers using an indexed loop terminating on the Count property must also check each returned object for a value of Nothing. The loop must proceed forward from the beginning of the collection, and the index must have initial and increment values of 1. Results are undefined for any other procedure.

The use of the Item property in conjunction with the Count property in a large collection can be seen in the following example.

Example

This code fragment counts the AddressEntry objects in a user’s personal address list (PAL):

Dim i As Integer ' loop index / object counter

Dim myPAL as Object ' personal address list

' get AddressEntries collection of PAL AddressList

Set myPAL = MAPI.Session.AddressLists.Item(“Personal Address List”)

' make sure returned collection object is valid

If myPAL Is Nothing Then

    ' MsgBox "PAL object is invalid"

    ' Exit

End If

' see if PAL is empty

i = 0

If 0 = myPAL.Count Then

    ' MsgBox "No items in PAL"

    ' Exit; i = 0 is correct value

End If

' get exact count of AddressEntry members in PAL

For i = 1 To myPAL.Count Step 1

    If myPAL.Item(i) Is Nothing Then

    i = i - 1 ' rectify count

    ' Exit; value of Nothing means end of collection

    End If

Next i


Delete Method (AddressEntries Collection)

The Delete method deletes all the address entries in the AddressEntries collection.

Syntax

objAddrEntriesColl.Delete()

Parameters

objAddrEntriesColl

Required. The AddressEntries collection object.

Remarks

Be cautious using the Delete method with a collection, since it deletes all the collection’s member objects. To delete only one AddressEntry object, use the Delete method specific to that object.

The Delete method on a large collection takes effect immediately and is permanent. Any object once deleted cannot be recovered.


Filter Property (AddressEntries Collection)

The Filter property returns an AddressEntryFilter object for the AddressEntries collection. Read/write.

Syntax

objAddrEntriesColl.Filter

Data Type

Object

Remarks

An AddressEntryFilter object with no criteria is created by default for every AddressEntries collection.


GetFirst Method (AddressEntries Collection)

The GetFirst method returns the first AddressEntry object in the AddressEntries collection. It returns Nothing if no first object exists.

Syntax

Set objAddressEntry = objAddrEntriesColl.GetFirst()

Parameters

objAddressEntry

On successful return, represents the first AddressEntry object in the collection.

objAddrEntriesColl

Required. The AddressEntries collection object.

Remarks

The Get methods are similar to the Find and Move methods used with Microsoft Access databases. The Get methods have different names because they use a different syntax.


GetLast Method (AddressEntries Collection)

The GetLast method returns the last AddressEntry object in the AddressEntries collection. It returns Nothing if no last object exists.

Syntax

Set objAddressEntry = objAddrEntriesColl.GetLast()

Parameters

objAddressEntry

On successful return, represents the last AddressEntry object in the collection.

objAddrEntriesColl

Required. The AddressEntries collection object.

Remarks

The Get methods are similar to the Find and Move methods used with Microsoft Access databases. The Get methods have different names because they use a different syntax.


GetNext Method (AddressEntries Collection)

The GetNext method returns the next AddressEntry object in the AddressEntries collection. It returns Nothing if no next object exists, for example if already positioned at the end of the collection.

Syntax

Set objAddressEntry = objAddrEntriesColl.GetNext()

Parameters

objAddressEntry

On successful return, represents the next AddressEntry object in the collection.

objAddrEntriesColl

Required. The AddressEntries collection object.

Remarks

The Get methods are similar to the Find and Move methods used with Microsoft Access databases. The Get methods have different names because they use a different syntax.


GetPrevious Method (AddressEntries Collection)

The GetPrevious method returns the previous AddressEntry object in the AddressEntries collection. It returns Nothing if no previous object exists, for example if already positioned at the beginning of the collection.

Syntax

Set objAddressEntry = objAddrEntriesColl.GetPrevious()

Parameters

objAddressEntry

On successful return, represents the previous AddressEntry object in the collection.

objAddrEntriesColl

Required. The AddressEntries collection object.

Remarks

The Get methods are similar to the Find and Move methods used with Microsoft Access databases. The Get methods have different names because they use a different syntax.


Item Property (AddressEntries Collection)

The Item property returns a single AddressEntry object from an AddressEntries collection. Read-only.

Syntax

objAddrEntriesColl.Item(index)

objAddrEntriesColl.Item(prefix)

index

A long integer ranging from 1 to the size of the AddressEntries collection.

prefix

A string representing a prefix substring of an AddressEntry object’s Name property.

Data Type

Object

Remarks

The Item property is useful for satisfying syntax requirements when obtaining a member of an AddressEntries collection.

A large collection cannot support true integer indexing, and the Item(index) syntax cannot be used for arbitrary selection of members of the collection. Programmers needing to access individual objects in a large collection are strongly advised to use the Visual Basic For Each statement or the Get methods, particularly GetFirst and GetNext.

The Item(index) syntax is provided solely as a placeholder in an indexed loop, such as the For ... Next construction in Visual Basic. Such a loop must proceed forward from the beginning of the collection, and the index must have initial and increment values of 1. Results are undefined for any other procedure.

For more information on using the Count and Item properties in a large collection, see the example in the Count property.

The Item(prefix) syntax returns the first AddressEntry object whose Name property begins with the string specified by prefix.

The Item property is the default property of an AddressEntries collection, meaning that AddressEntries(prefix) is syntactically equivalent to AddressEntries.Item(prefix) in Visual Basic code.


AddressEntry Object

The AddressEntry object defines valid addressing information for a given messaging system. An address usually represents a person or process to which the messaging system can deliver messages.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.0
Parent objects:	AddressEntries collection  Recipient
Child objects:	Fields collection
Default property:	Name
When an AddressEntry object is used as a child object of a Recipient object, it represents a copy of valid addressing information that is obtained from the address book during a call to the Recipient object’s Resolve method. When you obtain the AddressEntry object in this context, you should not modify its properties.

Properties

Name	Available in version	Type	Access
Address	1.0	String	Read/write
Application	1.0	String	Read-only
Class	1.0	Long	Read-only
DisplayType	1.0	Long	Read-only
Fields	1.0	Field object or Fields collection object	Read-only
ID	1.0	String	Read-only
Members	1.0.a	AddressEntries collection object	Read-only
Name	1.0	String	Read/write
Parent	1.0	AddressEntries collection object or Recipient object	Read-only
Session	1.0	Session object	Read-only
Type	1.0	String	Read/write
Methods

Name	Available in version	Parameters
Delete	1.0	(none)
Details	1.0	(optional) parentWindow as Long
IsSameAs	1.1	(required) object as Object
Update	1.0	(optional) makePermanent as Boolean,  (optional) refreshObject as Boolean


Address Property (AddressEntry Object)

The Address property specifies the messaging address of an address list entry or message recipient. Read/write.

Syntax

objAddressEntry.Address

Data Type

String

Remarks

The AddressEntry object’s Address property provides a unique string to identify a message recipient and routing information for messaging systems. The format of the address string is specific to each messaging system.

The AddressEntry object’s Address and Type properties combine to form the full address, the complete messaging address that appears in the Recipient object’s Address property. The Recipient object’s Address property uses the following syntax:

TypeValue:AddressValue

The AddressEntry object’s Address property corresponds to the MAPI property PR_EMAIL_ADDRESS.

Example

' Set up a series of object variables

' Set the Folder and Messages variables; from Session_Inbox

    Set objFolder = objSession.Inbox

    Set objMessages = objFolder.Messages

' Set the Message object variable; from Messages_GetFirst()

    Set objOneMsg = objMessages.GetFirst

' Set the Recipients collection variable; from Message_Recipients()

    Set objRecipColl = objOneMsg.Recipients

' Set the Recipient object variable; from Recipients_FirstItem()

    If 0 = objRecipColl.Count Then

        MsgBox "No recipients in the list"

        Exit Function

    End If

    iRecipCollIndex = 1

    Set objOneRecip = objRecipColl.Item(iRecipCollIndex)

' set the AddressEntry object variable; from Recipient_AddressEntry()

    Set objAddrEntry = objOneRecip.AddressEntry

' from Util_CompareFullAddressParts()

' display the values

    strMsg = "Recipient full address = " & objOneRecip.Address

    strMsg = strMsg & "; AddressEntry type = " & objAddrEntry.Type

    strMsg = strMsg & "; AddressEntry address = " & objAddrEntry.Address

    MsgBox strMsg

See Also

Address Property (Recipient Object)


Delete Method (AddressEntry Object)

The Delete method deletes the specified address from the address book.

Note  The OLE Messaging Library supports the Delete method only for the personal address book.

Syntax

objAddressEntry.Delete()

Parameters

objAddressEntry

Required. The AddressEntry object.

Remarks

The Delete method fails if both the Address and ID properties are empty.

Example

Function AddressEntry_Delete()

    ' error handling here...

    If objAddrEntry Is Nothing Then

        MsgBox "must select an AddressEntry object"

        Exit Function

    End If

    objAddrEntry.Delete

    Set objAddrEntry = Nothing

    Exit Function

    ' error handling

End Function

See Also

Add Method (Recipients Collection)


Details Method (AddressEntry Object)

The Details method displays a dialog box that provides detailed information about an AddressEntry object.

Syntax

objAddressEntry.Details( [parentWindow] )

Parameters

objAddressEntry

Required. The AddressEntry object.

parentWindow

Optional. Long. The parent window handle for the details dialog box. A value of 0 (the default, when no value is supplied) specifies a modal dialog box.

Remarks

The dialog box always contains at least the display name and address of the address entry. For AddressEntry objects, the method fails if both the Address and ID properties are empty.

The parentWindow parameter value must be valid or the OLE Messaging Library will not display the dialog box.

The following methods can also invoke MAPI dialog boxes: Delete and Details methods (AddressEntry object), Options and Send methods (Message object), Resolve method (Recipient object and Recipients collection), AddressBook and Logon methods (Session object).

See Also

Update Method (AddressEntry Object)


DisplayType Property (AddressEntry Object)

The DisplayType property returns the type of the address entry. This property enables special processing based on the type, such as displaying an icon associated with that type. Read-only.

Syntax

objAddressEntry.DisplayType

Data Type

Long

Remarks

You can use the display type to sort or to filter address entries.

The following values are defined:

Displaytype value	Description
mapiUser	Local user
mapiDistList	Distribution list
mapiForum	Public folder
mapiAgent	Agent
mapiOrganization	Organization
mapiPrivateDistList	Private distribution list
mapiRemoteUser	Remote user
See Also

Add Method (Recipients Collection)


Fields Property (AddressEntry Object)

The Fields property returns a single Field object or a Fields collection object. Read-only.

Syntax

objAddressEntry.Fields

objAddressEntry.Fields(index)

objAddressEntry.Fields(proptag)

objAddressEntry.Fields(name)

index

Short integer (less than or equal to 65535). Specifies the index within the collection.

proptag

Long integer (greater than or equal to 65536). Specifies the property tag value for the MAPI property to be retrieved.

name

String. Specifies the name of the custom MAPI property.

Data Type

Object

Remarks

The Fields property returns one or more of the fields associated with an AddressEntry object. Each field typically corresponds to a MAPI property.

The Fields property provides a generic access mechanism that allows Visual Basic and Visual C++ programmers to retrieve the value of any MAPI property using either a name or a MAPI property tag. For access with the property tag, use AddressEntry.Fields(proptag), where proptag is the 32-bit MAPI property tag associated with the property, such as PR_MESSAGE_CLASS. To access a named property, use AddressEntry.Fields(name), where name is a string that represents the custom property name.


ID Property (AddressEntry Object)

The ID property returns the unique identifier of the object as a string. Read-only.

Syntax

objAddressEntry.ID

Data Type

String

Remarks

You can use the AddressEntry object’s ID property as a parameter to the Recipient object’s Add method.

MAPI systems assign a permanent, unique ID string when an object is created. These identifiers do not change from one MAPI session to another.

The ID property corresponds to the MAPI property PR_ENTRYID, converted to a string of hexadecimal characters.

Example

This example copies information from an AddressEntry object to a Recipient object:

' Function: Recipients_Add_EntryID

' Purpose: Add a new recipient to the collection using AddressEntry ID

Function Recipients_Add_EntryID()

Dim strID As String      ' ID from Message.Sender

Dim strName As String    ' name from Message.Sender

Dim objNewMsg As Object  ' new msg; set its recipient using ID

Dim objNewRecip As Object ' Recipient of new message, set from ID, name

    ' error handling

    strID = objOneMsg.Sender.Id   'Address Entry object ID

    strName = objOneMsg.Sender.Name

    Set objNewMsg = objSession.Outbox.Messages.Add

    If objNewMsg Is Nothing Then

        MsgBox "Could not create a new message"

        Exit Function

    End If

    objNewMsg.Subject = "Sample message from OLE Messaging Library"

    objNewMsg.Text = "Called Recipients.Add method w/ entryID parameter"

    Set objNewRecip = objNewMsg.Recipients.Add( _

                      entryID:=strID, _

                      Name:=strName)

    If objNewRecip Is Nothing Then

        MsgBox "Could not create a new recipient"

        Exit Function

    End If

    objNewMsg.Update

    objNewMsg.Send showDialog:=False

    MsgBox "Created a new message in the Outbox and sent it"

    Exit Function

    ' error handling

End Function

See Also

Add Method (Recipients Collection)


IsSameAs Method (AddressEntry Object)

The IsSameAs method returns True if this AddressEntry object is the same as the AddressEntry object being compared against.

Syntax

objAddressEntry.IsSameAs(objAddrEntry2)

Parameters

objAddressEntry

Required. This AddressEntry object.

objAddrEntry2

Required. The AddressEntry object being compared against.

Remarks

Two AddressEntry objects are considered to be the same if and only if they are instantiations of the same physical (persistent) object. Two objects with the same value are still considered different if they do not instantiate the same physical object, for example if one is a copy of the other. In such a case IsSameAs returns False.

The IsSameAs method ultimately calls one of the MAPI CompareEntryIDs methods to determine if two objects are the same. A generic comparison of any two object identifiers is also available with the Session object’s CompareIDs method.


Members Property (AddressEntry Object)

The Members property returns an AddressEntries collection that contains the members of a distribution list. Read-only.

Syntax

objAddressEntry.Members

Data Type

Object

Remarks

The Members property returns a collection of all the members of the AddressEntry object if it is a distribution list. You can browse the returned AddressEntries collection, and you can add and delete entries if you have change access.

If the AddressEntry object is not a distribution list, the Members property returns Nothing.


Name Property (AddressEntry Object)

The Name property returns or sets the display name or alias of the AddressEntry object as a string. Read/write.

Syntax

objAddressEntry.Name

Data Type

String

Remarks

The AddressEntry object is typically used as a copy of valid addressing information obtained from the address book after you have called the Recipient object’s Resolve method.

When you obtain the AddressEntry object in this context, you should not modify its properties. To request resolution of a display name, use the Recipient object’s Name property instead. Set the Name property and call the Recipient object’s Resolve method.

The Name property corresponds to the MAPI property PR_DISPLAY_NAME.

The Name property is the default property of an AddressEntry object, meaning that AddressEntry is syntactically equivalent to AddressEntry.Name in Visual Basic code.

Example

' for values of variables, see AddressEntry Address property

' Recipient and AddressEntry display names are the same

    strMsg = "Recipient name = " & objOneRecip.Name

    strMsg = strMsg & "; AddressEntry name = " & objAddrEntry.Name

    MsgBox strMsg

See Also

Recipient Object, Resolve Method (Recipient Object), Using Addresses


Type Property (AddressEntry Object)

The Type property specifies the address type, such as SMTP, Fax, or X.400. Read/write.

Syntax

objAddressEntry.Type

Data Type

String

Remarks

The AddressEntry object’s Type property specifies the address type. This is usually a tag referring to the messaging system that routes messages to this address, such as SMTP or Fax.

The AddressEntry object’s Address and Type properties combine to form the full address, the complete messaging address that appears in the Recipient object’s Address property. The Recipient Address uses the following syntax:

TypeValue:AddressValue

The Type property corresponds to the MAPI property PR_ADDRTYPE.

Example

See the example for the AddressEntry object’s Address property.

See Also

Address Property (AddressEntry Object), Address Property (Recipient Object)


Update Method (AddressEntry Object)

The Update method saves AddressEntry object changes in the MAPI system.

Syntax

objAddressEntry.Update( [makePermanent, refreshObject] )

Parameters

objAddressEntry

Required. The AddressEntry object.

makePermanent

Optional. Boolean. TRUE indicates that the property cache is flushed and all changes are committed in the underlying message store. FALSE indicates that the property cache is flushed and not committed to the message store. The default value is TRUE.

refreshObject

Optional. Boolean. TRUE indicates that the property cache is reloaded from the values in the underlying message store. FALSE indicates that the property cache is not reloaded. The default value is FALSE.

Remarks

Changes to objects are not permanently saved in the MAPI system until you call the Update method with the makePermanent parameter set to TRUE.

For improved performance, the OLE Messaging Library caches property changes in private storage and updates either the object or the underlying message store only when you explicitly request such an update. For efficiency, you should make only one call to Update with its makePermanent parameter set to TRUE.

The makePermanent and refreshObject parameters combine to cause the following changes:

	refreshObject = TRUE	refreshObject = FALSE
makePermanent = TRUE	Commit all changes, flush the cache, and reload the cache from the message store.	Commit all changes and flush the cache.
makePermanent = FALSE	Flush the cache and reload the cache from the message store.	Flush the cache.
Call Update(FALSE, TRUE) to flush the cache and then reload the values from the message store.

Example

The following example changes the display name for the valid AddressEntry address:

' Function: AddressEntry_Update

' Purpose: Demonstrate the Update method

'    (Note: OLE Messaging Library only affects the PAB)

Function AddressEntry_Update()

Dim objRecipColl As Object   ' Recipients collection

Dim objNewRecip As Object    ' New recipient

    ' error handling omitted...

    Set objRecipColl = objSession.AddressBook

    If objRecipColl Is Nothing Then

        MsgBox "must select someone from the address book"

        Exit Function

    End If

    Set objNewRecip = objRecipColl.Item(1)

    With objNewRecip.AddressEntry

        .Name = .Name & " the Magnificent"

        .Type = "X.500"   ' you can also change the Type

        .Update

    End With

    MsgBox "Updated an address entry name: " & _

            objNewRecip.AddressEntry.Name

    Exit Function

    ' error handling omitted

End Function

See Also

Recipient Object


AddressEntryFilter Object

The AddressEntryFilter object specifies criteria for restricting a search on an AddressEntries collection.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.1
Parent objects:	AddressEntries collection
Child objects:	Fields collection
Default property:	Name
Properties

Property name	Available in version	Type	Access
Address	1.1	String	Read/write
Application	1.1	String	Read-only
Class	1.1	Long	Read-only
Fields	1.1	Field object or Fields collection object	Read-only
Name	1.1	String	Read/write
Not	1.1	Boolean	Read/write
Or	1.1	Boolean	Read/write
Parent	1.1	AddressEntries collection object	Read-only
Session	1.1	Session object	Read-only
Methods

Method name	Available in version	Parameters
IsSameAs	1.1	object as Object
Remarks

An AddressEntryFilter object with no criteria is created by default for every AddressEntries collection. This means that initially the filter’s properties are unset and its child Fields collection is empty. You specify the filter by setting values for its properties, and by adding fields to its Fields collection and setting a value for each added field.

The filter is invoked when the AddressEntries collection is traversed with the Get methods. Each field participates in a MAPI search restriction comparing the field’s Value property against the value of the AddressEntry property specified by the field’s ID property.

For fields of data type other than String, the MAPI search restriction type is RES_PROPERTY with relational operator RELOP_EQ. For fields of data type String, the restriction type is RES_CONTENT with fuzzy level options FL_SUBSTRING, FL_IGNORECASE, and FL_LOOSE.

The results of the individual restrictions are normally ANDed together to form the final filter value. You can change this by setting the Or property, which causes all the results to be ORed instead of ANDed. You can also set the Not property to specify that the result of each individual restriction is to be negated before being ANDed or ORed into the final filter value.

The AddressEntryFilter object is persistent within its parent AddressEntries collection. It is not deleted even when it is released, and it remains attached to the AddressEntries collection until the collection’s Filter property is set to Nothing or the collection is itself released.


Address Property (AddressEntryFilter object)

The Address property specifies the full address for the AddressEntry object being filtered. Read/write.

Syntax

objAddressEntryFilter.Address

Data Type

String

Remarks

The AddressEntryFilter object’s Address property is a concatenation of the address type and messaging address in the following format:

AddressType:AddressValue

where AddressType and AddressValue represent the AddressEntry object’s Type and Address properties.

The AddressEntryFilter object’s Address property corresponds to a combination of the MAPI properties PR_ADDRTYPE and PR_EMAIL_ADDRESS. It represents the full address, that is, the complete messaging address used by the MAPI system.

The Address property can be copied from the Address property of a Recipient. The advantage of doing this is that the value of the Recipient object’s Address property has already been computed by the OLE Messaging Library from its Name property and the Resolve method.


Fields Property (AddressEntryFilter object)

The Fields property returns a single Field object or a Fields collection object. Read-only.

Syntax

objAddressEntryFilter.Fields

objAddressEntryFilter.Fields(index)

objAddressEntryFilter.Fields(proptag)

objAddressEntryFilter.Fields(name)

index

Short integer (less than or equal to 65535). Specifies the index within the Fields collection.

proptag

Long integer (greater than or equal to 65536). Specifies the property tag value for the MAPI property to be retrieved.

name

String. Specifies the name of the custom MAPI property.

Data Type

Object

Remarks

The Fields property returns one or more of the fields associated with an AddressEntryFilter object. Each field typically corresponds to a MAPI property, and together the fields that have been added to the collection specify the filter.

The Fields property provides a generic access mechanism that allows Visual Basic and Visual C++ programmers to retrieve the value of a MAPI property using either its name or its MAPI property tag. For access with the property tag, use AddressEntryFilter.Fields(proptag), where proptag is the 32-bit MAPI property tag associated with the property, such as PR_MESSAGE_CLASS. To access a named property, use AddressEntryFilter.Fields(name), where name is a string that represents the custom property name.


IsSameAs Method (AddressEntryFilter object)

The IsSameAs method returns True if this AddressEntryFilter object is the same as the AddressEntryFilter object being compared against.

Syntax

objAddressEntryFilter.IsSameAs(objAddrEntryFilter2)

Parameters

objAddressEntryFilter

Required. This AddressEntryFilter object.

objAddrEntryFilter2

Required. The AddressEntryFilter object being compared against.

Remarks

Two AddressEntryFilter objects are considered to be the same if and only if they are instantiations of the same physical (persistent) object. Two objects with the same value are still considered different if they do not instantiate the same physical object, for example if one is a copy of the other. In such a case IsSameAs returns False.

The IsSameAs method ultimately calls one of the MAPI CompareEntryIDs methods to determine if two objects are the same. A generic comparison of any two object identifiers is also available with the Session object’s CompareIDs method.


Name Property (AddressEntryFilter object)

The Name property specifies a value for use in an ANR (ambiguous name resolution) restriction on an AddressEntry object. Read/write.

Syntax

objAddressEntryFilter.Name

Data Type

String

Remarks

The Name property contains an ambiguous name resolution (ANR) string that can be compared against each AddressEntry object using a provider-defined algorithm. The property or properties used in the comparison are chosen by the provider as part of the algorithm; the PR_DISPLAY_NAME property is the most commonly used.

The Name property corresponds to the MAPI property PR_ANR.

The Name property is the default property of an AddressEntryFilter object, meaning that AddressEntryFilter is syntactically equivalent to AddressEntryFilter.Name in Visual Basic code.


Not Property (AddressEntryFilter object)

The Not property specifies that all restriction values are to be negated before being ANDed or ORed to specify the address entry filter. Read/write.

Syntax

objAddressEntryFilter.Not

Data Type

Boolean

Remarks

If the Not property is False, the restriction values are treated normally. If it is True, each value is toggled (between True and False) before being used.


Or Property (AddressEntryFilter object)

The Or property specifies that the restriction values are to be ORed instead of ANDed to specify the address entry filter. Read/write.

Syntax

objAddressEntryFilter.Or

Data Type

Boolean

Remarks

If the Or property is False, all the restriction values are ANDed together. If it is True, the values are ORed together.


AddressList Object

The AddressList object supplies a list of address entries to which a messaging system can deliver messages.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.1
Parent objects:	AddressLists collection
Child objects:	AddressEntries collection
Default property:	Name
Properties

Property name	Available in version	Type	Access
AddressEntries	1.1	AddressEntries collection object	Read-only
Application	1.1	String	Read-only
Class	1.1	Long	Read-only
ID	1.1	String	Read-only
Index	1.1	Long	Read-only
IsReadOnly	1.1	Boolean	Read-only
Name	1.1	String	Read-only
Parent	1.1	AddressLists collection object	Read-only
Session	1.1	Session object	Read-only
Methods

Method name	Available in version	Parameters
IsSameAs	1.1	object as Object
Remarks

An AddressList object represents one address book available under the MAPI address book hierarchy for the current session.


AddressEntries Property (AddressList Object)

The AddressEntries property returns a single AddressEntry object or an AddressEntries collection object. Read-only.

Syntax

Set objAddrEntriesColl = objAddressList.AddressEntries

Set objOneAddrEntry = objAddressList.AddressEntries(index)

objAddrEntriesColl

Object. An AddressEntries collection object.

objAddressList

Object. The AddressList object.

objOneAddrEntry

Object. A single AddressEntry object.

index

Long. Specifies the number of the address entry within the AddressEntries collection. Ranges from 1 to the size of the collection.

Data Type

Object

Remarks

An AddressEntries collection is a large collection, and its size cannot necessarily be determined from its Count property. It is not safe to use the index parameter with the AddressEntries property unless an indexed loop has determined that an address entry at that position in the collection actually exists.


ID Property (AddressList Object)

The ID property returns the unique identifier of this AddressList object as a string. Read-only.

Syntax

objAddressList.ID

Data Type

String

Remarks

MAPI assigns a permanent, unique identifier string when an object is created. These identifiers do not change from one MAPI session to another.

The ID property corresponds to the MAPI property PR_ENTRYID, converted to a string of hexadecimal characters.

Example

This code fragment displays the value of the AddressList object’s permanent identifier:

Dim strAddressListID as String ' hex string version of ID

Dim objAddressList as Object ' assume valid for this example

strAddressListID = objAddressList.ID ' global variable

MsgBox "Address Book ID = " & strAddressListID


Index Property (AddressList Object)

The Index property returns the index number for this AddressList object within the AddressLists collection. Read-only.

Syntax

objAddressList.Index

Data Type

Long

Remarks

The Index property indicates this object’s position within the parent AddressLists Collection.

Example

Function AddressListsGetByIndex()

Dim rqIndex As Long ' requested index value within collection

Dim svIndex As Long ' saved index value within collection

Dim objOneAddressList As Object

    ' set error handler here

    If objAddressListsColl Is Nothing Then

        MsgBox "must select a valid AddressLists collection"

        Exit Function

    End If

    If 0 = objAddressListsColl.Count Then

        MsgBox "must select collection with 1 or more address lists"

        Exit Function

    End If

    ' prompt user for rqIndex

    Set objOneAddressList = objAddressListsColl.Item(rqIndex)

    MsgBox "Selected address list: " & objOneAddressList.Name

    svIndex = objOneAddressList.Index ' save index for later

    ' get same AddressList object later

    Set objOneAddressList = objAddressListsColl.Item(svIndex)

    If objOneAddressList Is Nothing Then

        MsgBox "Error: could not reselect the address list"

    Else

        MsgBox "Reselected address list (" & svIndex & _

            ") using saved index: " & objOneAddressList.Name

    End If

    Exit Function


IsReadOnly Property (AddressList Object)

The IsReadOnly property indicates that this AddressList object cannot be modified. Read-only.

Syntax

objAddressList.IsReadOnly

Data Type

Boolean

Remarks

The IsReadOnly property refers to adding and deleting the entries in the address book container represented by the AddressList object. The property is True if no entries can be added or deleted, and False if the container can be modified, that is, if address entries can be added to and deleted from the container.

IsReadOnly refers to the address book entries in the context of the address book container. It does not indicate whether the contents of the individual entries themselves can be modified.


IsSameAs Method (AddressList Object)

The IsSameAs method returns True if this AddressList object is the same as the AddressList object being compared against.

Syntax

objAddressList.IsSameAs(objAddrList2)

Parameters

objAddressList

Required. This AddressList object.

objAddrList2

Required. The AddressList object being compared against.

Remarks

Two AddressList objects are considered to be the same if and only if they are instantiations of the same physical (persistent) object. Two objects with the same value are still considered different if they do not instantiate the same physical object, for example if one is a copy of the other. In such a case IsSameAs returns False.

The IsSameAs method ultimately calls one of the MAPI CompareEntryIDs methods to determine if two objects are the same. A generic comparison of any two object identifiers is also available with the Session object’s CompareIDs method.


Name Property (AddressList Object)

The Name property returns the name of this AddressList object as a string. Read-only.

Syntax

objAddressList.Name

Data Type

String

Remarks

The Name property corresponds to the MAPI property PR_DISPLAY_NAME for the address book container represented by the AddressList object.

The Name property is the default property of an AddressList object, meaning that AddressList is syntactically equivalent to AddressList.Name in Visual Basic code.

Example

Dim objAddressList As Object ' assume valid address list object

MsgBox "Address book container name = " & objAddressList.Name


AddressLists Collection Object

The AddressLists collection object contains one or more AddressList objects.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.1
Parent objects:	Session
Child objects:	AddressList
Default property:	Item
An AddressLists collection is considered a small collection, which means that it supports count and index values that let you access an individual AddressList object through the Item property. The AddressLists collection supports the Visual Basic For Each statement.

Properties

Property name	Available in version	Type	Access
Application	1.1	String	Read-only
Class	1.1	Long	Read-only
Count	1.1	Long	Read-only
Item	1.1	AddressList object	Read-only
Parent	1.1	Session object	Read-only
Session	1.1	Session object	Read-only
Methods

(None.)

Remarks

The AddressLists collection provides access to the root of the MAPI address book hierarchy for the current session. You can use the Count and Item properties to traverse the hierarchy for all available address books, or you can use the Item property to select a particular AddressList object. The type of access you obtain depends on the access granted to you by each available address book provider.

Each AddressList object represents one MAPI address book container. The AddressLists collection contains only those AddressList objects that contain recipients, and not those containing only subcontainers. For more information on the different types of containers, see the description of the PR_CONTAINER_FLAGS property in the MAPI SDK.


Count Property (AddressLists Collection)

The Count property returns the number of AddressList objects in the collection. Read-only.

Syntax

objAddrListsColl.Count

Data Type

Long

Example

This code fragment uses the Count and Item properties to determine how many AddressList objects are available in the collection:

Dim i As Integer ' loop counter

Set hierarchy = MAPI.Session.AddressLists

' make sure returned collection object is valid

If hierarchy Is Nothing Then

    ' Exit "Address book hierarchy is invalid"

End If

' see if hierarchy is empty

i = hierarchy.Count ' count of address books in hierarchy

If 0 = i Then

    ' Exit "No available address books"

End If

' precautionary loop to make sure address books are all valid

For i = 1 To hierarchy.Count Step 1

    If Nothing = hierarchy.Item(i) Then

    ' Exit "Address book is invalid"

    End If

Next i


Item Property (AddressLists Collection)

The Item property returns a single AddressList object from the collection. Read-only.

Syntax

objAddrListsColl.Item(index)

objAddrListsColl.Item(name)

index

A long integer ranging from 1 to objAddrListsColl.Count.

name

A string representing the value of the Name property of an AddressList object.

Data Type

Object

Remarks

The Item property works like an accessor property for small collections.

The Item(index) syntax selects an arbitrary AddressList object within the AddressLists collection. The example in the Count property shows how these two properties can be used together to traverse the collection.

The Item(name) syntax returns the first AddressList object whose Name property matches the string specified by name.

The Item property is the default property of an AddressLists collection, meaning that AddressLists(index) is syntactically equivalent to AddressLists.Item(index) in Visual Basic code.


Attachment Object

The Attachment object represents a document that is an attachment of a message.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.0
Parent objects:	Attachments collection
Child objects:	(none)
Default property:	Name
Properties

Property name	Available in version	Type	Access
Application	1.0	String	Read-only
Class	1.0	Long	Read-only
Fields	1.1	Field object or Fields collection object	Read-only
Index	1.0	Long	Read-only
Name	1.0	String	Read/write
Parent	1.0	Attachments collection object	Read-only
Position	1.0	Long	Read/write
Session	1.0	Session object	Read-only
Source	1.0	String or Message object	Read/write
Type	1.0	Long	Read/write
Methods

Method name	Available in version	Parameters
Delete	1.0	(none)
IsSameAs	1.1	object as Object
ReadFromFile	1.0	fileName as String
WriteToFile	1.0	fileName as String


Delete Method (Attachment Object)

The Delete method deletes this attachment.

Syntax

objAttachment.Delete()

Parameters

objAttachment

Required. The Attachment object.

Remarks

The Attachment object is set to Nothing and is removed from memory, but the change is not permanent until you use the Update, Send, or Delete method on the parent Message object.

See Also

Delete Method (Attachments Collection)


Fields Property (Attachment Object)

The Fields property returns a single Field object or a Fields collection object. Read-only.

Syntax

objAttachment.Fields

objAttachment.Fields(index)

objAttachment.Fields(proptag)

objAttachment.Fields(name)

index

Short integer (less than or equal to 65535). Specifies the index within the Fields collection.

proptag

Long integer (greater than or equal to 65536). Specifies the property tag value for the MAPI property to be retrieved.

name

String. Specifies the name of the custom MAPI property.

Data Type

Object

Remarks

The Fields property returns one or more of the fields associated with an Attachment object. Each field typically corresponds to a MAPI property.

The Fields property provides a generic access mechanism that allows Visual Basic and Visual C++ programmers to retrieve the value of a MAPI property using either its name or its MAPI property tag. For access with the property tag, use Attachment.Fields(proptag), where proptag is the 32-bit MAPI property tag associated with the property, such as PR_MESSAGE_CLASS. To access a named property, use Attachment.Fields(name), where name is a string that represents the custom property name.


Index Property (Attachment Object)

The Index property returns the index number for the Attachment object within the Attachments collection. Read-only.

Syntax

objAttachment.Index

Data Type

Long

Remarks

The Index property indicates the attachment’s position within the parent Attachments collection.

An index value should not be considered to be a static value that remains constant for the duration of a session. The index can change whenever an update occurs to a parent object, such as the message or folder.

Example

Function Attachments_GetByIndex()

Dim lIndex As Long

Dim objOneAttach As Object  ' assume valid attachment

    ' set error handler here

    If objAttachColl Is Nothing Then

        MsgBox "must select an Attachments collection"

        Exit Function

    End If

    If 0 = objAttachColl.Count Then

        MsgBox "must select collection with 1 or more attachments"

        Exit Function

    End If

    ' prompt user for index; for now, use 1

    Set objOneAttach = objAttachColl.Item(1)

    MsgBox "Selected attachment 1: " & objOneAttach.Name

    lIndex = objOneAttach.Index  ' save index to retrieve this later

    ' ...get same attachment object later

    Set objOneAttach = objAttachColl.Item(lIndex)

    If objOneAttach Is Nothing Then

        MsgBox "Error, could not reselect the attachment"

    Else

        MsgBox "Reselected attachment " & lIndex & _

            " using index: " & objOneAttach.Name

    End If

    Exit Function

See Also

Attachments Collection, Item Property (Attachments Collection)


IsSameAs Method (Attachment Object)

The IsSameAs method returns True if this Attachment object is the same as the Attachment object being compared against.

Syntax

objAttachment.IsSameAs(objAttach2)

Parameters

objAttachment

Required. This Attachment object.

objAttach2

Required. The Attachment object being compared against.

Remarks

Two Attachment objects are considered to be the same if and only if they are instantiations of the same physical (persistent) object. Two objects with the same value are still considered different if they do not instantiate the same physical object, for example if one is a copy of the other. In such a case IsSameAs returns False.

The IsSameAs method ultimately calls one of the MAPI CompareEntryIDs methods to determine if two objects are the same. A generic comparison of any two object identifiers is also available with the Session object’s CompareIDs method.


Name Property (Attachment Object)

The Name property returns or sets the display name of the Attachment object as a string. Read/write.

Syntax

objAttachment.Name

Data Type

String

Remarks

The Name property corresponds to the MAPI property PR_ATTACH_FILENAME.

The Name property is the default property of an Attachment object, meaning that Attachment is syntactically equivalent to Attachment.Name in Visual Basic code.

Example

See the example for the Attachment object’s Index property.

See Also

Attachment Object


Position Property (Attachment Object)

The Position property returns or sets the position of the attachment within the body text of the message. Read/write.

Syntax

objAttachment.Position

Data Type

Long

Remarks

The Position property is a long integer describing where the attachment should be placed in the message body. The attachment overwrites the character present at that position. Applications cannot place two attachments in the same location within a message, and attachments cannot be placed beyond the end of the message body.

The OLE Messaging Library does not manage rendering of the attachment within the message. The Position property simply provides directions for the rendering application.

The value -1 indicates that the attachment is present, but is not rendered. The value 0 and other positive values indicate an index to the text character within the message.

The Position property corresponds to the MAPI property PR_RENDERING_POSITION.

Example

' from the function Attachments_Add()

    Set objAttach = objAttachColl.Add         ' add an attachment

    With objAttach

        .Type = mapiFileLink

        .Position = 0   ' place at beginning of message

        .Source = "\\server\bitmaps\honey.bmp"  ' UNC name

    End With

    ' must update the message to save the new info

    objOneMsg.Update   ' update the message

    MsgBox "Added an attachment of type mapiFileLink"

See Also

Add Method (Attachments Collection), Text Property (Message Object)


ReadFromFile Method (Attachment Object)

The ReadFromFile method loads the contents of an attachment from a file.

Syntax

objAttachment.ReadFromFile(fileName)

Parameters

objAttachment

Required. The Attachment object.

fileName

Required. The full path and file name to read. For example, C:\DOCUMENT\BUDGET.XLS.

Remarks

The ReadFromFile method replaces the existing contents of the Attachment object, if any.

The ReadFromFile method operates differently, depending on the value of the Attachment object’s Type property. The following table describes its operation:

Attachment Type property	ReadFromFile operation
mapiFileData	Copies the contents of the specified file to the attachment.
mapiFileLink	Not supported; generates the run-time error MAPI_E_NO_SUPPORT.
mapiOLE	The specified file must be a valid OLE docfile, such as a file previously written by the WriteToFile method with a mapiOLE type setting.
mapiEmbeddedMessage	Copies the embedded message to the attachment.
The term “OLE docfile” indicates that the file is written by an application such as Microsoft Word 6.0 or later that writes files using the OLE IStorage and IStream interfaces.

Note  OLE Messaging Library version 1.0 does not support ReadFromFile for mapiFileLink attachments. This call generates the run-time error MAPI_E_NO_SUPPORT.

See Also

Add Method (Attachments Collection)


Source Property (Attachment Object)

The Source property returns or sets the full path and filename, OLE class name, or unique message identifier for the attachment. Read/write.

Syntax

objAttachment.Source

Data Type

String

Remarks

The Source property returns or sets the full path and filename of the attachment data file for mapiFileData and mapiFileLink attachments. It returns or sets the OLE class name of the attachment for mapiOLE attachments. For mapiEmbeddedMessage attachments, the Source property is set with the ID property of the message to be embedded, and it returns the Message object.

The OLE Messaging Library does not synchronize the Source property and the ReadFromFile method. For mapiFileData and mapiOLE attachments, when you change the Source property to indicate a different file, you must also explicitly call the ReadFromFile method to update the object data. Similarly, when you call ReadFromFile with data from a different file, you must change the Source property.

The return value of the Source property depends on the value of the Type property, as described in the following table:

Type property	Source property
mapiFileData	Not used; contains an empty string.
mapiFileLink	Specifies a full path name in a universal naming convention (UNC) format, such as \\SALES\INFO\PRODUCTS\NEWS.DOC.
mapiOLE	Specifies the registered OLE class name of the attachment, such as “Word.Document” or “PowerPoint.Show.”
mapiEmbeddedMessage	Specifies the embedded Message object.
The UNC format is suitable for sending attachments to recipients who have access to a common file server.

The Source property corresponds to the MAPI property PR_ATTACH_PATHNAME.

Example

' from the function Attachments_Add()

    Set objAttach = objAttachColl.Add         ' add an attachment

    With objAttach

        .Type = mapiFileLink

        .Position = 0   ' place at end of message

        .Source = "\\server\bitmaps\honey.bmp"  ' UNC name

    End With

    ' must update the message to save the new info

    objOneMsg.Update   ' update the message

    MsgBox "Added an attachment of type mapiFileLink"

See Also

Add Method (Attachments Collection)


Type Property (Attachment Object)

The Type property describes the attachment type. Read/write.

Syntax

objAttachment.Type

Data Type

Long

Remarks

The following attachment types are supported:

Type property	Value	Description
mapiFileData	1	Attachment is the contents of a file. (Default value.)
mapiFileLink	2	Attachment is a link to a file.
mapiOLE	3	Attachment is an OLE object.
mapiEmbeddedMessage	4	Attachment is an embedded message.
The value of the Type property determines the valid values for the Source property.

The Attachment object Type property corresponds to the MAPI property PR_ATTACH_METHOD.

Example

' from the function Attachments_Add()

    Set objAttach = objAttachColl.Add         ' add an attachment

    With objAttach

        .Type = mapiFileLink

        .Position = 0   ' place at end of message

        .Source = "\\server\bitmaps\honey.bmp"  ' UNC name

    End With

    ' must update the message to save the new info

    objOneMsg.Update   ' update the message

    MsgBox "Added an attachment of type mapiFileLink"

See Also

Add Method (Attachments Collection), ReadFromFile Method (Attachment Object), WriteToFile Method (Attachment Object)


WriteToFile Method (Attachment Object)

The WriteToFile method saves the attachment to a file in the file system. Note that if the file already exists, this method overwrites it without warning.

Syntax

objAttachment.WriteToFile(file name)

Parameters

objAttachment

Required. The Attachment object.

file name

Required. String. The full path and file name for the saved attachment. For example, C:\DOCUMENT\BUDGET.XLS.

Remarks

The WriteToFile method overwrites the file without warning if a file of that name already exists. Your application should check for the existence of the file before calling WriteToFile.

The WriteToFile method operates differently, depending on the value of the Attachment object’s Type property. The following table describes its operation:

Attachment Type property	WriteToFile operation
mapiFileData	Copies the contents of the specified file to the attachment.
mapiFileLink	(Not supported)
mapiOLE	Writes the file as an OLE docfile format.
mapiEmbeddedMessage	(Not supported)
WriteToFile does not support mapiFileLink or mapiEmbeddedMessage attachments.

See Also

ReadFromFile Method (Attachment Object)


Attachments Collection Object

The Attachments collection object contains one or more Attachment objects.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.0
Parent objects:	Message
Child objects:	Attachment
Default property:	Item
An Attachments collection is considered a small collection, which means that it supports count and index values that let you access an individual Attachment objects through the Item property. The Attachments collection supports the Visual Basic For Each statement.

Properties

Property name	Available in version	Type	Access
Application	1.0	String	Read-only
Class	1.0	Long	Read-only
Count	1.0	Long	Read-only
Item	1.0	Attachment object	Read-only
Parent	1.0	Message object	Read-only
Session	1.0	Session object	Read-only
Methods

Method name	Available in version	Parameters
Add	1.0	(optional) name as String,  (optional) position as Long,  (optional) type as Long,  (optional) source as String
Delete	1.0	(none)


Add Method (Attachments Collection)

The Add method creates a new Attachment object in the Attachments collection.

Syntax

Set objAttachment = objAttachColl.Add( [ name, position, type, source ] )

Parameters

objAttachment

On successful return, contains the new Attachment object.

objAttachColl

Required. The Attachments collection object.

name

Optional. String. The display name of the attachment. The default value is an empty string. To allow a user to click on the attachment that appears in the message and activate an associated application, supply the full filename, including the file extension.

position

Optional. Long. The position of the attachment within the body text of the message. The default value is 0.

type

Optional. Long. The type of attachment; either mapiFileData, mapiFileLink, mapiOLE, or mapiEmbeddedMessage. The default value is mapiFileData.

source

Optional. String. The path and filename of the file containing the data for the attachment, or the unique identifier of the message to be embedded. The path and filename must be in the appropriate format for the attachment type, specified by the type parameter. The default value is an empty string.

Remarks

The Add method parameters correspond to the Name, Position, Type, and Source properties of the Attachment object. The source parameter is also closely related to the ReadFromFile method’s filename parameter.

You can supply the data for the attachment at the same time that you add the attachment to the collection. The Add method operates differently, depending on the value of the type parameter. The following table describes its operation.

Value of type parameter	Value of source parameter
mapiFileData	Specifies a full path and filename that contains the data for the attachment, for example C:\DOCUMENT\BUDGET.XLS. The data is read into the attachment.
mapiFileLink	Specifies a full path and filename in a universal naming convention (UNC) format, such as \\SALES\INFO\PRODUCTS\NEWS.DOC. The attachment is a link, so the Add method does not read the data.
mapiOLE	Specifies a full path and filename to a valid OLE docfile, for example C:\DOCUMENT\BUDGET2.XLS. The data is read into the attachment.
mapiEmbeddedMessage	Specifies the ID property of the message to be embedded. The message is read into the attachment.
When the type parameter has the value mapiFileLink, the source parameter is a full path and filename in a UNC format. This is suitable for sending attachments to recipients who have access to a common file server. Note that when you use the type mapiFileLink, the OLE Messaging Library does not validate the filename.

If you do not specify the type and source parameters when you call the Add method, you must later explicitly set these properties. For mapiFileData and mapiOLE types, you must also call the ReadFromFile method on the new Attachment object to load the attachment’s content.

The Index property of the new Attachment object equals the new Count property of the Attachments collection.

The attachment is saved in the MAPI system when you Update or Send the parent Message object.


Count Property (Attachments Collection)

The Count property returns the number of Attachment objects in the collection. Read-only.

Syntax

objAttachColl.Count

Data Type

Long

Example

This example stores in an array the names of all Attachment objects in the collection:

' from the sample function, TstDrv_Util_SmallCollectionCount

' objAttachColl is an Attachments collection

x = Util_SmallCollectionCount(objAttachColl)

Function Util_SmallCollectionCount(objColl As Object)

Dim strItemName(100) As String      ' Names of objects in collection

Dim i As Integer                    ' loop counter

    On Error GoTo error_olemsg

    If objColl Is Nothing Then

        MsgBox "Must supply a valid collection object as a parameter"

        Exit Function

    End If

    If 0 = objColl.Count Then

        MsgBox "No items in the collection"

        Exit Function

    End If

    For i = 1 To objColl.Count Step 1

        strItemName(i) = objColl.Item(i).Name

        If 100 = i Then ' max size of string array

            Exit Function

        End If

    Next i

    ' error handling here...

End Function

See Also

Item Property (Attachments Collection)


Delete Method (Attachments Collection)

The Delete method deletes all the attachments in the Attachments collection.

Syntax

objAttachColl.Delete()

Parameters

objAttachColl

Required. The Attachments collection object.

Remarks

Be cautious using the Delete method with a collection, since it deletes all the collection’s member objects. To delete only one Attachment object, use the Delete method specific to that object.

The effect of the Delete method is not permanent until you use the Update, Send, or Delete method on the parent Message object containing the Attachments collection.


Item Property (Attachments Collection)

The Item property returns a single Attachment object from the collection. Read-only.

Syntax

objAttachColl.Item(index)

index

A long integer that ranges from 1 to object.Count, or a string that specifies the name of the object.

Data Type

Object

Remarks

The Item property works like an accessor property for small collections.

The Item property is the default property of an Attachments collection, meaning that Attachments(index) is syntactically equivalent to Attachments.Item(index) in Visual Basic code.

Example

' from Util_SmallCollectionCount(objColl As Object)

' This sample obtains the collection as a variable

' so it *must* use the Item property

Dim strItemName(100) as String

    ' error handling omitted from this fragment...

    For i = 1 To objColl.Count Step 1

        strItemName(i) = objColl.Item(i).Name

        If 100 = i Then ' max size of string array

            Exit Function

        End If

    Next i

See Also

Count Property (Attachments Collection)


Field Object

A Field object represents a property of an object. The Field object gives you the ability to add or access properties of an AddressEntry, AddressEntryFilter, Folder, Message, or MessageFilter object.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.0
Parent objects:	Fields collection
Child objects:	(none)
Default property:	Value
Properties

Property name	Available in version	Type	Access
Application	1.0	String	Read-only
Class	1.0	Long	Read-only
ID	1.0	Long	Read-only
Index	1.0	Long	Read-only
Name	1.0	String	Read-only
Parent	1.0	Fields collection object	Read-only
Session	1.0	Session object	Read-only
Type	1.0	Integer	Read-only
Value	1.0	Variant	Read/write
Methods

Method name	Available in version	Parameters
Delete	1.0	(none)
ReadFromFile	1.0	fileName as String
WriteToFile	1.0	fileName as String
Remarks

You can add additional properties tailored for your specific application with the Fields collection object. Before adding a field for a Message, Folder, or AddressEntry object, please review the properties that are already provided by the OLE Messaging Library. Many of the most common attributes are already offered. For example, Subject and Priority are already defined as Message object properties.

Note that the predefined MAPI properties are unnamed when they are accessed in Field objects. For these MAPI properties, the Name property is an empty string.

The Field object also supports multivalued MAPI properties. The multivalued property appears to the Visual Basic application as a variant array; that is, you can use the For ... Next statement to access individual array entries, as shown in the following sample program.

    Dim rgstr(0 To 9) As String

    ' Build array of values for MV prop

    For i = 0 To 9

        rgstr(i) = "String" + Str(i)

    Next

    ' Create MV field on the message. Note that we don't specify

    ' the array as third argument to Fields.Add, but add separately.

    Set f = msg.Fields.Add("FancyName", vbString + vbArray)

    f.Value = rgstr     ' Set value of the new field.

    ' Save/send the message, logoff, etc.

... ' code that reads the multivalued properties

    Dim rgstr As Variant

    Set f = msg.Fields.Item("FancyName") ' Get MV Field from the message

    rgstr = f.Value     ' Get array of values into a variant

    For i = LBound(rgret) To UBound(rgret)

        MsgBox rgret(i)

    Next i

For more information about MAPI properties, see the reference documentation for the Fields Collection and the MAPI Programmer’s Reference.

See Also

Fields Collection


Delete Method (Field Object)

The Delete method deletes the user-defined or optional Field object.

Syntax

objField.Delete

Parameters

objField

Required. The Field object.

Remarks

This method only deletes user-defined fields and fields that represent properties considered optional by the underlying provider.

The object or collection is set to Nothing and it is removed from memory, but the change is not permanent until you use the Update, Send, or Delete method on the parent object (either the parent Folder or Message object) that contained the deleted Field object.

See Also

Add Method (Fields Collection)


ID Property (Field Object)

The ID property returns the unique identifier of the object as a long integer. Read-only.

Syntax

objField.ID

Data Type

Long

Remarks

The Field object ID property is unique among identifier properties supported in the OLE Messaging Library. The Field object identifier is a long integer that corresponds to a MAPI property tag value. All other identifier properties are hexadecimal strings.

Example

' The ID property is a long value, not a string

' fragment from the function Field_ID()

'   verify that objOneField is valid, then access

    MsgBox "ID is high-order word: 0x" & Hex(objOneField.Id)

See Also

Type Property (Field Object)

Value Property (Field Object)


Index Property (Field Object)

The Index property returns the index number of this Field object within the Fields collection. Read-only.

Syntax

objField.Index

Data Type

Long

Remarks

An index value should not be considered to be a static value that remains constant for the duration of a session. The index can change whenever an update occurs to a parent object, such as the message or folder.

Example

' set up a variable as an index to access a small collection

' fragment from the functions Fields_FirstItem, Fields_NextItem

    If objFieldsColl Is Nothing Then

        MsgBox "must first select a Fields collection"

        Exit Function

    End If

    If 0 = objFieldsColl.Count Then

        MsgBox "No fields in the collection"

        Exit Function

    End If

' Fragment from Fields_FirstItem

    iFieldsCollIndex = 1

    Set objOneField = objFieldsColl.Item(iFieldsCollIndex)

    ' verify that the Field object is valid...

' Fragment from Fields_NextItem

    If iFieldsCollIndex >= objFieldsColl.Count Then

        iFieldsCollIndex = objFieldsColl.Count

        MsgBox "Already at end of Fields collection"

        Exit Function

    End If

    iFieldsCollIndex = iFieldsCollIndex + 1

    Set objOneField = objFieldsColl.Item(iFieldsCollIndex)

    ' verify that the Field object is valid...

See Also

Count Property (Fields Collection)

Fields Collection


Name Property (Field Object)

The Name property returns the name of the field as a string. Read-only.

Syntax

objField.Name

Data Type

String

Remarks

The Name property is read-only. You set the name of the Field object at the time you create it, when you call the Fields collection’s Add method.

Note that Field objects used to access MAPI properties do not have names. Names can appear only on the custom properties that you create. For more information, see the Item property documentation for the Fields collection.

Example

' fragment from Fields_Add

Dim objNewField As Object ' new Field object

    Set objNewField = objFieldsColl.Add( _

                      Name:="Keyword", _

                      Class:=vbString, _

                      Value:="Peru")

    If objNewField Is Nothing Then

        MsgBox "could not create new Field object"

        Exit Function

    End If

    cFields = objFieldsColl.Count

    MsgBox "new Fields collection count = " & cFields

' fragment from Field_Name; modified to use objNewField for active Field

    If "" = objNewField.Name Then

        MsgBox "Field has no name; ID = " & objNewField.Id

    Else

        MsgBox "Field name = " & objNewField.Name

    End If

See Also

Add Method (Fields Collection)


ReadFromFile Method (Field Object)

The ReadFromFile method loads the value of a string or binary field from the specified file.

Syntax

objField.ReadFromFile(fileName)

Parameters

objField

Required. The Field object.

fileName

Required. The full path and file name to read. For example, C:\DOCUMENT\BUDGET.XLS.

Remarks

The ReadFromFile method reads the string or binary value from the specified file name and stores it as the value of the Field object. It replaces any previously existing value for the field.

Note that ReadFromFile is not supported for simple types, such as Integer, Long, and Boolean. Visual Basic provides common functions to read and write these base types to and from files. The ReadFromFile method fails if the Type property of the Field object is not a string or binary type.

Note that some binary types are converted to a hexadecimal string format when they are stored as Field values. Comparison operations on the Value property and the actual contents of the file can return “not equal,” even though the values are equivalent.

ReadFromFile returns MAPI_E_INTERFACE_NOT_SUPPORTED for Field objects obtained from a Folder object’s Fields collection.

See Also

WriteToFile Method (Field Object)


Type Property (Field Object)

The Type property returns or sets the data type of the Field object. Read/write.

Syntax

objField.Type

Data Type

Integer

Remarks

The Type property specifies the data type of the Field object and determines the range of valid values that can be supplied for the Value property. You can set the value of the Type property by calling the Fields collection’s Add method.

Valid data types are as follows:

Type	Description	Decimal value	OLE variant type	MAPI property type
vbNull	Null	1	VT_NULL	PT_NULL
vbInteger	Integer	2	VT_I2	PT_I2
vbLong	Long integer	3	VT_I4	PT_LONG
vbSingle	4-byte real (floating point)	4	VT_R4	PT_R4
vbDouble	Double (8-byte real)	5	VT_R8	PT_DOUBLE, PT_I8
vbCurrency	Currency	6	VT_CY	PT_CURRENCY
vbDate	Date/time (8-byte)	7	VT_DATE	PT_APPTIME, PT_SYSTIME
vbString	String	8	VT_BSTR	PT_TSTRING, PT_BINARY
vbBoolean	Boolean	11	VT_BOOL	PT_BOOLEAN
vbDataObject	Data object	13	VT_UNKNOWN	PT_OBJECT
vbBlob	Binary (unknown format)	65	VT_BLOB	PT_BINARY
Note that the types vbNull and vbDataObject are not supported in version 1.0.

Note that MAPI stores all custom properties that represent date and time information using Greenwich Mean Time (GMT). The OLE Messaging Library converts these properties so that the values appear to the user in local time.

Example

' Fragment from Fields_Add; uses the type "vbString"

    Set objNewField = objFieldsColl.Add( _

                      Name:="Keyword", _

                      Class:=vbString, _

                      Value:="Peru")

'  verify that objNewField is a valid Field object

' Fragment from Field_Type; display the decimal type value

    MsgBox "Field type = " & objOneField.Type


Value Property (Field Object)

The Value property returns or sets the value of the Field object. Read/write.

Syntax

objField.Value

Data Type

Variant

Remarks

The value of the Field object represents a value of the type specified by the Type property. For example, when the Field object has the Type property vbBoolean, the Value property can take the value TRUE or FALSE. When the Field object has the Type property vbInteger, the Value property can contain a short integer.

The Value property is the default property of a Field object, meaning that Field is syntactically equivalent to Field.Name in Visual Basic code.

Example

' fragment from function Field_Type()

' after validating the Field object objOneField

    MsgBox "Field type = " & objOneField.Type

' fragment from function Field_Value()...

    MsgBox "Field value = " & objOneField.Value

See Also

ID Property (Field Object)

Type Property (Field Object)


WriteToFile Method (Field Object)

The WriteToFile method saves the field value to a file in the file system.

Syntax

objField.WriteToFile(fileName)

Parameters

objField

Required. The Field object.

fileName

Required. The full path and file name for the saved field; for example, C:\DOCUMENT\BUDGET.XLS.

Remarks

The WriteToFile method writes the string or binary value of the Field object to the specified file name. It overwrites any existing information in that file.

Note that WriteToFile is not supported for simple types, such as Integer, Long, and Boolean. Visual Basic provides common functions to read and write these base types to and from files. The WriteToFile method fails if the Type property of the Field is not a string or binary type.

Note that some binary types are represented in hexadecimal string format by the OLE Messaging Library and written in binary format. Comparison operations on the Value property and the actual contents of the file can return “not equal,” even though the values are equivalent.

In addition, support for types can vary among providers. Not all providers support both the String and Binary property types.

See Also

ReadFromFile Method (Field Object)


Fields Collection Object

The Fields collection object contains one or more Field objects. Field objects give you the ability to access properties of the object. These include the predefined underlying MAPI properties and your own custom user-defined properties.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.0
Parent objects:	AddressEntry  AddressEntryFilter  Folder (Inbox or Outbox)  Message  MessageFilter
Child objects:	Field
Default property:	Item
A Fields collection is considered a small collection, which means that it supports count and index values that let you access an individual Field object through the Item property. The Fields collection supports the Visual Basic For Each statement.

Properties

Property name	Available in version	Type	Access
Application	1.0	String	Read-only
Class	1.0	Long	Read-only
Count	1.0	Long	Read-only
Item	1.0	Field object	Read-only
Parent	1.0	AddressEntry object, Inbox or Outbox folder object, or Message object	Read-only
Session	1.0	Session object	Read-only
Methods

Method name	Available in version	Parameters
Add	1.0	name as String,  Class as Long,  PropTag as Long,  (optional) value as Variant,  (optional) PropsetID as String
Delete	1.0	(none)
SetNamespace	1.0	(optional) PropsetID as String
Remarks

MAPI defines a set of properties with identifiers less than the value 0x8000. These are known as unnamed properties because they are usually accessed using the identifier rather than a name. You can access these MAPI-defined properties using the Fields collection. All MAPI properties are accessible except those of types PT_OBJECT and PT_CLSID.

You can also extend the properties available through MAPI by defining your own properties. These user-defined properties, defined using a name and automatically assigned an identifier value greater than 0x8000 by the OLE Messaging Library, are known as named properties. (C++ programmers can access the property name in the MAPI structure MAPINAMEID and convert it to the property tag value.)

All named properties are defined as part of a property set, which is also known in the context of the OLE Messaging Library as a namespace.

A property set is defined by a GUID, or unique identifier. The OLE Messaging Library represents this GUID as a string of hexadecimal characters. Such identifiers are usually referenced using a constant that starts with the characters PS_, such as PS_PUBLIC_STRINGS, the default property set for all properties created using the OLE Messaging Library.

You can also choose to organize your custom properties within their own semantic space by defining your own property set. The Add and SetNamespace methods and the Item property let you specify the property set identifier to be used for property access. When creating your own property set, you should be aware that MAPI reserves several property set identifiers for specific purposes. The following table lists reserved property sets:

Reserved Property Set	Description
PS_PUBLIC_STRINGS	Default property set for custom properties added using the OLE Messaging Library.
PS_MAPI	Allows providers to supply names for the unnamed properties (properties with identifiers less than 0x8000).
PS_ROUTING_DISPLAY_NAME	Display name properties that are translated  between messaging domains.
PS_ROUTING_EMAIL_ADDRESSES	E-mail addresses that are translated between messaging domains.
PS_ROUTING_ADDRTYPE	E-mail address types that are translated between messaging domains.
PS_ROUTING_ENTRYID	Long-term entry identifiers that are translated between messaging domains.
PS_ROUTING_SEARCH_KEY	Search keys that are translated between messaging domains.
To create your own GUID that identifies your property set, you can either use the Win32 command-line utility UUIDGEN or you can call the OLE function CoCreateGuid to supply one for you, as demonstrated in the following code:

' declarations required for the call to CoCreateGuid

Type GUID

    Guid1 As Long

    Guid2 As Long

    Guid3 As Long

    Guid4 As Long

End Type

Declare Function CoCreateGuid Lib "OLE32.DLL" (pGuid As GUID) As Long

Global Const S_OK = 0

Dim strPropID as String

Dim lResult As Long

Dim lGuid As GUID

' call CoCreateGuid, then convert the result to a hex string

    lResult = CoCreateGuid(lGuid)

    If lResult = S_OK Then

        strPropID =  Hex$(lGuid.Guid1) & Hex$(lGuid.Guid2)

        strPropID = myHexString & Hex$(lGuid.Guid3)

        strPropID = myHexString & Hex$(lGuid.Guid4)

    Else

        ‘ ... handle error...

    End If

'

Note that MAPI stores all custom properties that represent date and time information using Greenwich Mean Time (GMT). The OLE Messaging Library converts these properties so that the values appear to the user in local time.

For more information about properties and property sets, see the topic, “About Named Properties,” in the MAPI Programmer’s Reference. For more information about UUIDGEN and CoCreateGuid, see the Win32 SDK documentation.

Example

To uniquely identify Field objects in the Fields collection, use the Field object’s Name property or an index:

Set objOneField = objFolder.Fields.Item("BalanceDue")

Set objAnotherField = objMessage.Fields.Item("Keyword")

Set objThirdField = objMessage.Fields.Item(3)

See Also

SetNamespace Method (Fields Collection), Object Collections


Add Method (Fields Collection)

The Add method creates a new Field object in the Fields collection.

Syntax

Set objField = objFieldsColl.Add (name, Class [, value] [, PropsetID] )

Set objfield = objFieldsColl.Add (PropTag [, value] )

Parameters

objField

On successful return, contains the new Field object.

objFieldsColl

Required. The Fields collection object.

name

Required. A string that represents the display name of the field.

Class

Required. A constant long integer that represents the data type for the field, such as string or integer. The Class parameter represents the same values as the Field object’s Type property. The following types are allowed:

Type property	Description	Numeric value	OLE variant type
vbNull	Null	1	VT_NULL
vbInteger	Integer	2	VT_I2
vbLong	Long integer	3	VT_I4
vbSingle	4-byte real (floating point)	4	VT_R4
vbDouble	Double (8-byte real)	5	VT_R8
vbCurrency	Currency	6	VT_CY
vbDate	Date	7	VT_DATE
vbString	String	8	VT_BSTR
vbBoolean	Boolean	11	VT_BOOL
vbDataObject	Data object	13	VT_UNKNOWN
vbBlob	Blob	65	VT_BLOB
PropTag

Required. Long. The property tag for the corresponding MAPI property.

value

Optional. Variant. The value of the field, of the data type specified in the Class parameter. When no value is supplied, no data is present for the object. You must make subsequent calls to the Field object’s ReadFromFile method.

PropsetID

Optional. String. Specifies the identifier of the property set, represented as a string of hexadecimal characters. When the identifier is not present, the property is created within the default property set. The default property set is either the property set specified to the SetNamespace method, or the initial default property set value, PS_PUBLIC_STRINGS.

Remarks

Support for the Add method is provider-dependent. The second syntax should be used when adding a MAPI property to the Fields collection.

The name, Class, and value parameters in the first syntax correspond to the Name, Type, and Value properties of the Field object.

The PropTag parameter in the second syntax contains the 32-bit MAPI property tag associated with the property and corresponds to the ID property of the Field object. The property tag contains the property identifier in its high-order 16 bits and the property type in its low-order 16 bits.

The Index property of the new Field object equals the new Count property of the Fields collection.

The field is saved in the MAPI system when you Update the parent object, or Send it if the parent is a Message object.

When you use the vbBlob type, you supply the value in the form of a hexadecimal string that contains the hexadecimal representation of the bytes in the binary object (such as a hexadecimal dump of the object).

Note that MAPI stores all custom properties that represent date and time information using Greenwich Mean Time (GMT). The OLE Messaging Library converts these properties so that the values appear to the user in local time.

The OLE Messaging Library does not support MAPI properties of types PT_OBJECT and PT_CLSID. All others, however, are available through the Fields collection.

Example

' Fragment from Fields_Add; uses the type "vbString"

    Set objNewField = objFieldsColl.Add( _

                      Name:="Keyword", _

                      Class:=vbString, _

                      Value:="Peru")

'  verify that objNewField is a valid Field object

' Fragment from Field_Type; display the integer type value

    MsgBox "Field type = " & objOneField.Type


Count Property (Fields Collection)

The Count property returns the number of Field objects in the collection. Read-only.

Syntax

objFieldsColl.Count

Data Type

Long

Example

This example maintains a global variable as an index into the small collection, and uses the Count property to check its validity:

' from Fields_NextItem

' iFieldsCollIndex is an integer used as an index

'   check for empty collection...

'   check index upper bound

    If iFieldsCollIndex >= objFieldsColl.Count Then

        iFieldsCollIndex = objFieldsColl.Count

        MsgBox "Already at end of Fields collection"

        Exit Function

    End If

    ' index is < count; can be incremented by 1

    iFieldsCollIndex = iFieldsCollIndex + 1

    Set objOneField = objFieldsColl.Item(iFieldsCollIndex)

    If objOneField Is Nothing Then

        MsgBox "Error, cannot get this Field object"

        Exit Function

    Else

        MsgBox "Selected field " & iFieldsCollIndex

    End If

See Also

Field Object


Delete Method (Fields Collection)

The Delete method deletes all user-defined fields of the Fields collection object.

Syntax

objFieldsColl.Delete

Parameters

objFieldsColl

Required. The Fields collection object.

Remarks

The Delete method deletes all user-defined fields and all fields considered optional by the underlying provider.

Be cautious using the Delete method with a collection, since it deletes all the collection’s member objects. To delete only one Field Object object, use the Delete method specific to that object.

The effect of the Delete method is not permanent until you use the Update method on the parent object containing the Fields collection, or the Send or Delete method if the parent is a Message object.


Item Property (Fields Collection)

The Item property returns a single Field object from the collection. Read-only.

Syntax

objFieldsColl.Item(index)

objFieldsColl.Item(proptag)

objFieldsColl.Item(name [, propsetID])

objFieldsColl

Required. Specifies the Fields collection object.

index

Short integer (less than or equal to 65535; &Hffff). Specifies the index within the collection.

proptag

Long integer (greater than or equal to 65536). Specifies the property tag value for the MAPI property to be retrieved.

name

String. Specifies the name of the user-defined property.

propsetID

Optional. String. Contains the unique identifier for the property set, represented as a string of hexadecimal characters. When propsetID is not supplied, the property set used for the access is the default property set value set by this collection’s SetNamespace method, or the initial default property set value, PS_PUBLIC_STRINGS.

Data Type

Object

Remarks

The Item property works like an accessor property for small collections. In the Fields collection object it allows access to the predefined MAPI properties and to your own custom user-defined properties.

The long value greater than 65,535 represents a property tag. A property tag is a 32-bit unsigned integer that contains the property identifier in its high-order 16 bits and the property type (its underlying data type) in the low-order 16 bits. All MAPI properties are accessible except those of types PT_OBJECT and PT_CLSID.

Several macros for C/C++ programmers are available in the MAPI SDK to help manipulate the property tag data structure. The macros PROP_TYPE and PROP_ID extract the property type and property identifer from the property tag. The macro PROP_TAG builds the property tag from the provided type and identifier components.

For example, you can use the following function to access a custom user-defined property using its property name:

' from the function Fields_ItemByName()

    ' error handling here...

    If objFieldsColl Is Nothing Then

        MsgBox "must first select Fields collection"

        Exit Function

    End If

    Set objOneField = objFieldsColl.Item("Keyword")

    If objOneField Is Nothing Then

        MsgBox "could not select Field object"

        Exit Function

    End If

    If "" = objOneField.Name Then

        MsgBox "Field has no name; ID = " & objOneField.Id

    Else

        MsgBox "Field name = " & objOneField.Name

    End If

You can also use the Item property to access MAPI properties. Note that the built-in MAPI properties are unnamed properties that can only be accessed using the numeric value. They cannot be accessed using a string that represents the name. The following example accesses the MAPI property PR_MESSAGE_CLASS:

' from the function Fields_Selector()

    ' ... error handling here

    ' you can provide a dialog to allow entry for MAPI proptags

    ' or select property names from a list; for now, hard-coded

    lValue = &h1a001e ' &H1a = PR_MESSAGE_CLASS;

                      ' &H001e = 30 = PT_STRING8

    ' high-order 16 bits is property id; low-order is property type

    Set objOneField = objFieldsColl.Item(lValue)

    If objOneField Is Nothing Then

        MsgBox "Could not get the Field using the value " & lValue

        Exit Function

    Else

        strMsg = "Used " & lValue & " to access the MAPI property "

        strMsg = strMsg & "PR_MESSAGE_CLASS: type = " & objOneField.Type

        strMsg = strMsg & "; value = " & objOneField.Value

        MsgBox strMsg

    End If

The OLE Messaging Library also supports multivalued MAPI properties.

You can also choose to access properties from other property sets, including your own, by either setting the propsetID parameter or by calling the SetNamespace method to set that property set’s unique identifier.

The Item property is the default property of a Fields collection, meaning that Fields(index) is syntactically equivalent to Fields.Item(index) in Visual Basic code.

See Also

Customizing a Folder or Message, Viewing MAPI Properties


SetNamespace Method (Fields Collection)

The SetNamespace method selects the property set that is to be used for subsequent property accesses using the Add method and Item property.

Syntax

objFieldsColl.SetNamespace PropsetID

Parameters

objFieldsColl

Required. The Fields collection object.

PropsetID

Required. String. Contains a unique identifier that identifies the property set, represented as a string of hexadecimal characters. The PropsetID identifies the property set to be used for subsequent property accesses using the Field object and Fields collection. An empty string resets the default to the property set PS_PUBLIC_STRINGS.

Remarks

The initial default value for the property set is PS_PUBLIC_STRINGS. To create your own property set for your named properties, supply a unique property set identifier to SetNamespace. This property set then replaces PS_PUBLIC_STRINGS as the default property set for all subsequent named property accesses using this object. The default property set is used unless explicitly overridden by the optional PropsetID parameter. The value is set only for the current object; to continue using the same property set for all objects, you must call SetNamespace for each Message object.

To define a new property set, obtain a string that contains hexadecimal characters representing a unique identifier. You can obtain this identifier using either the Win32 command-line utility UUIDGEN or by calling the Win32 function CoCreateGuid.

See Also

Fields Collection


Folder Object

The Folder object represents a folder or container within the MAPI system. Folders can contain subfolders and messages.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.0
Parent objects:	Folders collection  InfoStore
Child objects:	Folder
Default property:	Messages
Properties

Property name	Available in version	Type	Access
Application	1.0	String	Read-only
Class	1.0	Long	Read-only
Fields	1.0	Field object or Fields collection object	Read-only
FolderID	1.0	String	Read-only
Folders	1.0	Folders collection object	Read-only
ID	1.0	String	Read-only
MAPIOBJECT	1.0	Object	Read/write (Note: Not available to Visual Basic applications)
Messages	1.0	Messages collection object	Read-only
Name	1.0	String	Read/write
Parent	1.0	Folders collection object or InfoStore object	Read-only
Session	1.0	Session object	Read-only
StoreID	1.0	String	Read-only
Methods

Method name	Available in version	Parameters
CopyTo	1.1	folderID as String,  (optional) storeID as String,  (optional) name as String,  (optional) copySubfolders as Boolean
Delete	1.0.a	(none)
IsSameAs	1.1	object as Object
MoveTo	1.1	folderID as String,  (optional) storeID as String
Update	1.0	(optional) makePermanent as Boolean,  (optional) refreshObject as Boolean
Remarks

A Folder object is considered a top-level object, meaning it can be created directly from a Visual Basic program, through either late binding or early binding.

Changes to the folder are not saved by MAPI until you call the Update method.


CopyTo Method (Folder Object)

The CopyTo method makes a copy of this Folder object at another folder hierarchy location.

Syntax

Set objCopiedFolder = objFolder.CopyTo(folderID [, storeID, name, copySubfolders ] )

Parameters

objCopiedFolder

On successful return, contains the copied Folder object.

objFolder

Required. This Folder object.

folderID

Required. String. The unique identifier of the new parent Folder object, that is, the Folder object under which the copy of this folder is to appear as a subfolder.

storeID

Optional. String. The unique identifier of the InfoStore object in which the folder copy is to appear, if different from this folder’s InfoStore.

name

Optional. String. The name to be assigned to the folder copy, if different from this folder’s name.

copySubfolders

Optional. Boolean. If True, all subfolders contained within this folder are to be copied along with the folder.

Remarks

All Message objects contained within this folder are copied along with the folder itself. This also applies to messages contained in the subfolders if the copySubfolders parameter is True.

The copy operation takes effect immediately. This Folder object, together with all its contents, remains unchanged by the CopyTo method.


Delete Method (Folder Object)

The Delete method deletes this Folder object from its parent Folders collection or InfoStore object.

Syntax

objFolder.Delete()

Parameters

objFolder

Required. This Folder object.

Remarks

The action of the Delete method is permanent, and the Folder object cannot be recovered.

The ability to delete any object depends on the permissions granted to the user. The Delete method returns an error if called with insufficient permissions.

Example

Function Folder_Delete()

    ' error handling here

    If objFolder Is Nothing Then

        MsgBox "must select a valid Folder object"

        Exit Function

    End If

    objFolder.Delete ()

    Set objFolder = Nothing

    Exit Function

End Function


Fields Property (Folder Object)

The Fields property returns a single Field object or a Fields collection object. Read-only.

Syntax

objFolder.Fields

objFolder.Fields(index)

objFolder.Fields(proptag)

objFolder.Fields(name)

index

Short integer (less than or equal to 65535). Specifies the index within the collection.

proptag

Long integer (greater than or equal to 65536). Specifies the property tag value for the MAPI property to be retrieved.

name

String. Specifies the name of the custom MAPI property.

Data Type

Object

Remarks

The Fields property returns one or more of the fields associated with a Folder object. Each field typically corresponds to a MAPI property.

The Fields property provides a generic access mechanism that allows Visual Basic and Visual C++ programmers to retrieve the value of a MAPI property using either its name or its MAPI property tag. For access with the property tag, use Folder.Fields(proptag), where proptag is the 32-bit MAPI property tag associated with the property, such as PR_MESSAGE_CLASS. To access a named property, use Folder.Fields(name), where name is a string that represents the custom property name.

Example

This example displays the field name or identifier value of all Field objects within the collection:

' many properties are MAPI properties and have no names

' for those properties, display the ID

' fragment from Field_Name

' assume objFieldColl, objOneField are valid objects

For i = 1 to objFieldColl.Count Step 1

    Set objOneField = objFieldColl.Index(i)

    If "" = objOneField.Name Then

        MsgBox "Field has no name; ID = " & objOneField.Id

    Else

        MsgBox "Field name = " & objOneField.Name

    End If

Next i

See Also

Field Object


FolderID Property (Folder Object)

The FolderID property returns the unique identifier of this subfolder’s parent folder as a string. Read-only.

Syntax

objFolder.FolderID

Data Type

String

Remarks

MAPI systems assign a permanent, unique identifier string when an object is created. These identifiers do not change from one MAPI session to another.

Note that MAPI systems do not require identifier values to be binary comparable. Accordingly, two identifier values can be different, yet refer to the same object. You can compare identifiers using the MAPI CompareEntryIDs method. For more information, see the MAPI Programmer’s Reference.

The FolderID property corresponds to the MAPI property PR_PARENT_ENTRYID, converted to a string of hexadecimal characters.

Example

'          fragment from Session_Inbox

    Set objFolder = objSession.Inbox

'          fragment from Folder_FolderID

    strFolderID = objFolder.FolderID

    MsgBox "Parent Folder ID = " & strFolderID

'          can later restore using objSession.GetFolder(strFolderID)

'          fragment from Session_GetFolder

    If "" = strFolderID Then

        MsgBox ("Must first set folder ID variable; see Folder->ID")

        Exit Function

    End If

    Set objFolder = objSession.GetFolder(strFolderID)

    ' error checking here...

See Also

ID Property (Folder Object)


Folders Property (Folder Object)

The Folders property specifies a collection of subfolders within the parent folder. Read-only.

Syntax

objFolder.Folders

Data Type

Object

Example

This example lists all the names of all subfolders of the specified folder:

' fragment from Session_Inbox

    Set objFolder = objSession.Inbox

' from TstDrv_Util_ListFolders

   If 2 = objFolder.Class Then  ' verify Folder object

        x = Util_ListFolders(objFolder)  ' use current global folder

   End If

' complete function for Util_ListFolders

Function Util_ListFolders(objParentFolder As Object)

Dim objFoldersColl As Object ' the child Folders collection

Dim objOneSubfolder As Object 'a single Folder object

    ' set up error handler here

    If Not objParentFolder Is Nothing Then

        MsgBox ("Folder name = " & objParentFolder.Name)

        Set objFoldersColl = objParentFolder.Folders

        If Not objFoldersColl Is Nothing Then ' loop through all

            Set objOneSubfolder = objFoldersColl.GetFirst

            While Not objOneSubfolder Is Nothing

                x = Util_ListFolders(objOneSubfolder)

                Set objOneSubfolder = objFoldersColl.GetNext

            Wend

        End If

    End If

    Exit Function

    ' error handler here

End Function

See Also

Folders Collection


ID Property (Folder Object)

The ID property returns the unique identifier of this Folder object as a string. Read-only.

Syntax

objFolder.ID

Data Type

String

Remarks

MAPI systems assign a permanent, unique identifier string when an object is created. These identifiers do not change from one MAPI session to another.

The ID property corresponds to the MAPI property PR_ENTRYID, converted to a string of hexadecimal characters.

Example

' save the current ID and restore using Session.GetFolder

'          fragment from Session_Inbox

    Set objFolder = objSession.Inbox

'          fragment from Folder_FolderID

    strFolderID = objFolder.ID

    MsgBox "Current Folder ID = " & strFolderID

'          can later restore using objSession.GetFolder(strFolderID)

'          fragment from Session_GetFolder

    If "" = strFolderID Then

        MsgBox ("Must first set folder ID variable; see Folder->ID")

        Exit Function

    End If

    Set objFolder = objSession.GetFolder(strFolderID)

    ' error checking here...

See Also

Folders Property (Folder Object), GetFolder Method (Session Object)


IsSameAs Method (Folder Object)

The IsSameAs method returns True if this Folder object is the same as the Folder object being compared against.

Syntax

objFolder.IsSameAs(objFolder2)

Parameters

objFolder

Required. This Folder object.

objFolder2

Required. The Folder object being compared against.

Remarks

Two Folder objects are considered to be the same if and only if they are instantiations of the same physical (persistent) object. Two objects with the same value are still considered different if they do not instantiate the same physical object, for example if one is a copy of the other. In such a case IsSameAs returns False.

The IsSameAs method ultimately calls one of the MAPI CompareEntryIDs methods to determine if two objects are the same. A generic comparison of any two object identifiers is also available with the Session object’s CompareIDs method.


MAPIOBJECT Property (Folder Object)

The MAPIOBJECT property returns an IUnknown pointer to this Folder object. Not available to Visual Basic applications. Read/write.

Syntax

objFolder.MAPIOBJECT

Data Type

Variant (VT_UNKNOWN)

Remarks

The MAPIOBJECT property is not available to Visual Basic programs. It is available only to C/C++ programs that use the OLE Messaging Library. The MAPIOBJECT property is an IUnknown object, which is not supported by Visual Basic. Visual Basic supports IDispatch objects. For more information, see the Microsoft OLE Programmer’s Reference.

See Also

Introduction to OLE Automation

How Programmable Objects Work


Messages Property (Folder Object)

The Messages property returns a Messages collection object within the folder. Read-only.

Syntax

objFolder.Messages

Data Type

Object

Remarks

The Messages property is the default property of a Folder object, meaning that Folder is syntactically equivalent to Folder.Name in Visual Basic code.

Example

' from the QuickStart sample

' use the Messages property of the Outbox folder

    Set objSession = CreateObject("MAPI.Session")

    objSession.Logon

    Set objMessage = objSession.Outbox.Messages.Add

See Also

ID Property (Message Object), Message Object, Messages Collection


MoveTo Method (Folder Object)

The MoveTo method relocates this Folder object to another folder hierarchy location.

Syntax

Set objMovedFolder = objFolder.MoveTo(folderID [, storeID ] )

Parameters

objMovedFolder

On successful return, contains the moved Folder object.

objFolder

Required. This Folder object.

folderID

Required. String. The unique identifier of the new parent Folder object, that is, the Folder object under which this folder is to appear as a subfolder.

storeID

Optional. String. The unique identifier of the InfoStore object in which this folder is to appear, if different from its current InfoStore.

Remarks

All subfolders of this folder, together with all Message objects contained within this folder and its subfolders, are moved along with the folder itself.

The move operation takes effect immediately. This Folder object is no longer accessible at its former location once the MoveTo method returns.


Name Property (Folder Object)

The Name property returns or sets the name of the Folder object as a string. Read/write.

Syntax

objFolder.Name

Data Type

String

Remarks

The Name property corresponds to the MAPI property PR_DISPLAY_NAME.

Example

Dim objFolder As Object  ' assume valid folder

MsgBox "Folder name = " & objFolder.Name

See Also

GetFolder Method (Session Object)


StoreID Property (Folder Object)

The StoreID property returns the identifier of the InfoStore object in which this Folder object resides. Read-only.

Syntax

objFolder.StoreID

Data Type

String

Remarks

The StoreID property corresponds to the MAPI property PR_STORE_ENTRYID, converted to a string of hexadecimal characters.

Note that MAPI systems do not require identifier values to be binary comparable. Accordingly, two identifier values can be different, yet refer to the same object. You can compare identifiers using the MAPI method CompareEntryIDs. For more information, see the MAPI Programmer’s Reference.

Example

' from the sample function Folder_ID

    strFolderID = objFolder.ID

' from the sample function Folder_StoreID

    strFolderStoreID = objFolder.storeID

'  can use these IDs with Session.GetFolder()

'  from the sample function Session_GetFolder

    Set objFolder = objSession.GetFolder(folderID:=strFolderID, _

                                      storeID:=strFolderStoreID)

See Also

GetFolder Method (Session Object)


Update Method (Folder Object)

The Update method saves the folder in the MAPI system.

Syntax

objFolder.Update( [makePermanent, refreshObject] )

Parameters

objFolder

Required. The Folder object.

makePermanent

Optional. Boolean. TRUE indicates that the property cache is flushed and all changes are committed in the underlying message store. FALSE indicates that the property cache is flushed and not committed to the message store. The default value is TRUE.

refreshObject

Optional. Boolean. TRUE indicates that the property cache is reloaded from the values in the underlying message store. FALSE indicates that the property cache is not reloaded. The default value is FALSE.

Remarks

Changes to Folder objects are not permanently saved in the MAPI system until you call the Update method with the makePermanent parameter set to TRUE.

For improved performance, the OLE Messaging Library caches property changes in private storage and updates either the object or the underlying message store only when you explicitly request such an update. For efficiency, you should make only one call to Update with its makePermanent parameter set to TRUE.

The makePermanent and refreshObject parameters combine to cause the following changes:

	refreshObject = TRUE	refreshObject = FALSE
makePermanent = TRUE	Commit all changes, flush the cache, and reload the cache from the message store.	Commit all changes and flush the cache.
makePermanent = FALSE	Flush the cache and reload the cache from the message store.	Flush the cache.
Call Update(FALSE, TRUE) to flush the cache and then reload the values from the message store.

See Also

Folders Collection


Folders Collection Object

The Folders collection object contains one or more Folder objects.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.0
Parent objects:	Folder (Inbox or Outbox)
Child objects:	Folder
Default property:	Item
A Folders collection is considered a large collection, which means that the Count and Item properties have limited validity, and your best option is to use a Folder object identifier value or the Get methods to access an individual Folder object within the collection.

Properties

Property name	Available in version	Type	Access
Application	1.0	String	Read-only
Class	1.0	Long	Read-only
Count	1.1	Long	Read-only
Item	1.1	Folder object	Read-only
Parent	1.0	Inbox or Outbox folder object	Read-only
Session	1.0	Session object	Read-only
Methods

Method name	Available in version	Parameters
Add	1.1	name as String
Delete	1.1	(none)
GetFirst	1.0	(none)
GetLast	1.0	(none)
GetNext	1.0	(none)
GetPrevious	1.0	(none)
Remarks

Large collections, such as the Folders collection, cannot always maintain an accurate count of the number of objects in the collection. It is strongly recommended that you use the GetFirst, GetNext, GetLast, and GetPrevious methods to access individual items in the collection. You can also access a specific folder by using the Session object’s GetFolder method.

Example

To refer to a unique Folder object within the Folders collection, use the collection’s GetFirst and GetNext methods or use the FolderID value as the index.

The following code sample demonstrates the Get methods. The sample assumes that you have three subfolders within your Inbox and three subfolders within your Outbox. After this code runs, the three folders in the Inbox are named Blue, Red, and Orange (in that order), and the three folders in the Outbox are named Gold, Purple, and Yellow (in that order).

Dim objSession As Object

Dim objMessage As Object

Dim objFolder As Object

Set objSession = CreateObject("MAPI.Session")

objSession.Logon "User", "", True

With objSession.Inbox.Folders

   Set objFolder = .GetFirst

   objFolder.Name = "Blue"

   Set objFolder = .GetNext

   objFolder.Name = "Red"

   Set objFolder = .GetLast

   objFolder.Name = "Orange"

End With

With objSession.Outbox.Folders

   Set objFolder = .GetFirst

   objFolder.Name = "Gold"

   Set objFolder = .GetNext

   objFolder.Name = "Purple"

   Set objFolder = .GetLast

   objFolder.Name = "Yellow"

End With

objSession.Logoff

See Also

Object Collections


Add Method (Folders Collection)

The Add method creates and returns a new Folder object in the Folders collection.

Syntax

Set objFolder = objFoldersColl.Add(name)

Parameters

objFolder

On successful return, contains the new Folder object.

objFoldersColl

Required. The Folders collection object.

name

Required. String. The display name of the folder.

Remarks

The name parameter corresponds to the Name property of the Folder object.

The user must have permission to Add or Delete a Folder object. Most users have this permission only for their personal folders.

The new Folder object is saved in the MAPI system when you call its Update method.

Example

This code fragment adds a new folder to a user’s Inbox:

Dim myInbox, newFolder As Object

Set myInbox = MAPI.Session.Inbox

' add new folder to Inbox

Set newFolder = myInbox.Add “Personal Messages”

' commit new folder to collection

myInbox.Update


Count Property (Folders Collection)

The Count property returns the number of Folder objects in the collection, or a very large number if the exact count is not available. Read-only.

Syntax

objFoldersColl.Count

Data Type

Long

Remarks

The Count property is useful for determining whether a Folders collection is empty or not.

A large collection cannot always maintain an accurate count of its members, and the Count property cannot be used as the collection’s size when it has a very large value such as mapiMaxCount. Programmers needing to access individual objects in a large collection are strongly advised to use the Visual Basic For Each statement or the Get methods.

The recommended procedures for traversing a large collection are, in decreasing order of preference:

1.	Global selection, such as the Visual Basic For Each statement

2.	The Get methods, particularly GetFirst and GetNext

3.	An indexed loop, such as the Visual Basic For ... Next construction

If the message store provider cannot supply the precise number of Folder objects, the OLE Messaging Library returns a very large number for the Count property. On 32-bit platforms, this value is mapiMaxCount, which equals 2^31 - 1, or 2147483647. On other platforms, mapiMaxCount is not defined, and the OLE Messaging Library returns -1. A program on such a platform must be careful that -1 does not prematurely terminate any iteration based on the Count property.

Programmers using an indexed loop terminating on the Count property must also check each returned object for a value of Nothing. The loop must proceed forward from the beginning of the collection, and the index must have initial and increment values of 1. Results are undefined for any other procedure.

The use of the Item property in conjunction with the Count property in a large collection can be seen in the following example.

Example

This code fragment searches for a Folder object called “Resumes”:

Dim i As Integer ' loop index / object counter

Dim collFolders as Object ' folders collection; assume already given

If collFolders Is Nothing Then

    ' MsgBox "Folders collection object is invalid"

    ' Exit

End If

' see if collection is empty

If 0 = collFolders.Count Then

    ' MsgBox "No folders in collection"

    ' Exit

End If

' look for folder called “Resumes” in collection

For i = 1 To collFolders.Count Step 1

    If collFolders.Item(i) Is Nothing Then

    ' MsgBox "No such folder found in collection"

    ' Exit ' no more folders in collection

    End If

    If collFolders.Item(i).Name = “Resumes” Then

    ' MsgBox "Desired folder is at index " & i

    ' Exit

    End If

Next i


Delete Method (Folders Collection)

The Delete method deletes all the folders in the Folders collection.

Syntax

objFoldersColl.Delete()

Parameters

objFoldersColl

Required. The Folders collection object.

Remarks

Be cautious using the Delete method with a collection, since it deletes all the collection’s member objects. To delete only one Folder object, use the Delete method specific to that object.

The Delete method on a large collection takes effect immediately and is permanent. Any object once deleted cannot be recovered.


GetFirst Method (Folders Collection)

The GetFirst method returns the first Folder Object in the Folders collection. It returns Nothing if no first object exists.

Syntax

Set objFolder = objFoldersColl.GetFirst()

Parameters

objFolder

On successful return, represents the first Folder object in the collection.

objFoldersColl

Required. The Folders collection object.

Remarks

The Get methods are similar to the Find and Move methods used with Microsoft Access databases. The Get methods have different names because they use a different syntax.


GetLast Method (Folders Collection)

The GetLast method returns the last Folder Object in the Folders collection. It returns Nothing if no last object exists.

Syntax

Set objFolder = objFoldersColl.GetLast()

Parameters

objFolder

On successful return, represents the last Folder object in the collection.

objFoldersColl

Required. The Folders collection object.

Remarks

The Get methods are similar to the Find and Move methods used with Microsoft Access databases. The Get methods have different names because they use a different syntax.


GetNext Method (Folders Collection)

The GetNext method returns the next Folder Object in the Folders collection. It returns Nothing if no next object exists, for example if already positioned at the end of the collection.

Syntax

Set objFolder = objFoldersColl.GetNext()

Parameters

objFolder

On successful return, represents the next Folder object in the collection.

objFoldersColl

Required. The Folders collection object.

Remarks

The Get methods are similar to the Find and Move methods used with Microsoft Access databases. The Get methods have different names because they use a different syntax.


GetPrevious Method (Folders Collection)

The GetPrevious method returns the previous Folder Object in the Folders collection. It returns Nothing if no previous object exists, for example if already positioned at the beginning of the collection.

Syntax

Set objFolder = objFoldersColl.GetPrevious()

Parameters

objFolder

On successful return, represents the previous Folder object in the collection.

objFoldersColl

Required. The Folders collection object.

Remarks

The Get methods are similar to the Find and Move methods used with Microsoft Access databases. The Get methods have different names because they use a different syntax.


Item Property (Folders Collection)

The Item property returns a single Folder object from a Folders collection. Read-only.

Syntax

objFoldersColl.Item(index)

objFoldersColl.Item(prefix)

index

A long integer ranging from 1 to the size of the Folders collection.

prefix

A string representing a prefix substring of a Folder object’s Name property.

Data Type

Object

Remarks

The Item property is useful for satisfying syntax requirements when obtaining a member of a Folders collection.

A large collection cannot support true integer indexing, and the Item(index) syntax cannot be used for arbitrary selection of members of the collection. Programmers needing to access individual objects in a large collection are strongly advised to use the Visual Basic For Each statement or the Get methods, particularly GetFirst and GetNext.

The Item(index) syntax is provided solely as a placeholder in an indexed loop, such as the For ... Next construction in Visual Basic. Such a loop must proceed forward from the beginning of the collection, and the index must have initial and increment values of 1. Results are undefined for any other procedure.

For more information on using the Count and Item properties in a large collection, see the example in the Count property.

The Item(prefix) syntax returns the first Folder object whose Name property begins with the string specified by prefix.

The Item property is the default property of a Folders collection, meaning that Folders(prefix) is syntactically equivalent to Folders.Item(prefix) in Visual Basic code.


InfoStore Object

The InfoStore object provides access to the root folder for that message store.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.0
Parent objects:	InfoStores collection
Child objects:	Folder
Default property:	Name
Properties

Property name	Available in version	Type	Access
Application	1.0	String	Read-only
Class	1.0	Long	Read-only
ID	1.0	String	Read-only
Index	1.0	Long	Read-only
Name	1.0	String	Read-only
Parent	1.0	InfoStores collection object	Read-only
ProviderName	1.0	String	Read-only
RootFolder	1.0	Folder object	Read-only
Session	1.0	Session object	Read-only
Methods

Method name	Available in version	Parameters
IsSameAs	1.1	object as Object
Remarks

The message store provides access to its folder hierarchy through the RootFolder property. This property contains the Folder object that represents the root of the IPM tree.

You can also retrieve an InfoStore object with a known identifier by calling the Session object’s GetInfoStore method.

Example

Dim objInfoStore as Object

Set objInfoStore = objSession.InfoStores.Item(1)

Set objFolder = objInfoStore.RootFolder

See Also

GetInfoStore Method (Session Object), InfoStores Collection


ID Property (InfoStore Object)

The ID property returns the unique identifier of this InfoStore object as a string. Read-only.

Syntax

objInfoStore.ID

Data Type

String

Remarks

MAPI systems assign a permanent, unique identifier string when an object is created. These identifiers do not change from one MAPI session to another. The InfoStore identifier can be used in subsequent calls to the Session object’s GetInfoStore method.

The ID property corresponds to the MAPI property PR_ENTRYID, converted to a string of hexadecimal characters.

Example

Dim strInfoStoreID as String  ' hex string version of ID

Dim objInfoStore as Object    ' assume valid

    strInfoStoreID = objInfoStore.Id   ' global variable

    MsgBox "InfoStore ID = " & strInfoStoreID

'...this ID can be used as the parameter to the Session method

    Set objInfoStore = objSession.GetInfoStore(strInfoStoreID)

See Also

InfoStores Collection


Index Property (InfoStore Object)

The Index property returns the index number for the InfoStore object within the parent InfoStores collection. Read-only.

Syntax

objInfoStore.Index

Data Type

Long

Remarks

The Index property indicates this object’s position within the parent InfoStores Collection.

Example

Function InfoStoresGetByIndex()

Dim lIndex As Long

Dim objOneInfoStore As Object  ' assume valid InfoStore

    ' set error handler here

    If objInfoStoreColl Is Nothing Then

        MsgBox "must select an InfoStores collection"

        Exit Function

    End If

    If 0 = objInfoStoreColl.Count Then

        MsgBox "must select collection with 1 or more InfoStores"

        Exit Function

    End If

    ' prompt user for index; for now, use 1

    Set objOneInfoStore = objInfoStoreColl.Item(1)

    MsgBox "Selected InfoStore 1: " & objOneInfoStore.Name

    lIndex = objOneInfoStore.Index  ' save index to retrieve this later

    ' ...get same InfoStore object later

    Set objOneInfoStore = objInfoStoreColl.Item(lIndex)

    If objOneInfoStore Is Nothing Then

        MsgBox "Error, could not reselect the InfoStore"

    Else

        MsgBox "Reselected InfoStore " & lIndex & _

            " using index: " & objOneInfoStore.Name

    End If

    Exit Function

See Also

Item property


IsSameAs Method (InfoStore Object)

The IsSameAs method returns True if this InfoStore object is the same as the InfoStore object being compared against.

Syntax

objInfoStore.IsSameAs(objInfoStore2)

Parameters

objInfoStoret

Required. This InfoStore object.

objInfoStore2

Required. The InfoStore object being compared against.

Remarks

Two InfoStore objects are considered to be the same if and only if they are instantiations of the same physical (persistent) object. Two objects with the same value are still considered different if they do not instantiate the same physical object, for example if one is a copy of the other. In such a case IsSameAs returns False.

The IsSameAs method ultimately calls one of the MAPI CompareEntryIDs methods to determine if two objects are the same. A generic comparison of any two object identifiers is also available with the Session object’s CompareIDs method.


Name Property (InfoStore Object)

The Name property returns the name of the InfoStore object as a string. The string “Public Folders” is the name of the InfoStore object that contains the public folders. Read-only.

Syntax

objInfoStore.Name

Data Type

String

Remarks

The Name property corresponds to the MAPI property PR_DISPLAY_NAME.

The Name property is the default property of an InfoStore object, meaning that InfoStore is syntactically equivalent to InfoStore.Name in Visual Basic code.

Example

Dim objInfoStore As Object  ' assume valid InfoStore object

MsgBox "InfoStore name = " & objInfoStore.Name

See Also

GetInfoStore Method (Session Object)


ProviderName Property (InfoStore Object)

The ProviderName property returns the name of the InfoStore provider as a string. Read-only.

Syntax

objInfoStore.ProviderName

Data Type

String

Remarks

The ProviderName property corresponds to the MAPI property PR_PROVIDER_DISPLAY.

Example

Dim objInfoStore As Object  ' assume valid InfoStore object

MsgBox "InfoStore name = " & objInfoStore.Name

See Also

GetInfoStore Method (Session Object)


RootFolder Property (InfoStore Object)

The RootFolder property returns a folder object representing the root of the IPM tree for this InfoStore object. Read-only.

Syntax

set objFolder = objInfoStore.RootFolder

Data Type

Object (Folder object)

Remarks

The RootFolder property provides a convenient way to get to this commonly used Folder object.

In addition to the general ability to navigate through the formal collection and object hierarchy, the OLE Messaging Library supports properties that allow your application to directly access the most common folder objects:

•	The IPM subtree

•	Inbox

•	Outbox

Some message stores also support a way to obtain the root folder. For more information, see the documentation for the Session object’s GetFolder method.

Example

' from InfoStores_RootFolder

    If objInfoStore Is Nothing Then

        MsgBox "must first select an InfoStore object"

        Exit Function

    End If

    Set objFolder = objInfoStore.RootFolder

    If objFolder Is Nothing Then

        MsgBox "Unable to retrieve InfoStore root folder"

        Set objMessages = Nothing

        Exit Function

    End If

    If objFolder.Name = "" Then

        MsgBox "Folder set to folder with no name, ID = " & objFolder.Id

    Else

        MsgBox "Folder set to: " & objFolder.Name

    End If

    Set objMessages = objFolder.Messages

    Exit Function

See Also

Folder Object, GetFolder Method (Session Object), Inbox Property (Session Object), Outbox Property (Session Object)


InfoStores Collection Object

The InfoStores collection object contains one or more InfoStore objects.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.0
Parent objects:	Session object
Child objects:	InfoStore
Default property:	Item
An InfoStores collection is considered a small collection, which means that it supports count and index values that let you access an individual InfoStore object through the Item property. The InfoStores collection supports the Visual Basic For Each statement.

Properties

Property name	Available in version	Type	Access
Application	1.0	String	Read-only
Class	1.0	Long	Read-only
Count	1.0	Long	Read-only
Item	1.0	InfoStore object	Read-only
Parent	1.0	Session object	Read-only
Session	1.0	Session object	Read-only
Methods

(None.)

Remarks

An InfoStores collection provides access to all InfoStore objects available to this session. Each InfoStore object in turn offers access to the root of the folder hierarchy in that message store. This is used primarily to obtain access to the public folders.

The OLE Messaging Library does not support methods to add or remove InfoStore objects from the collection.

In general, you cannot assume that the InfoStore object’s Name properties are unique. This means that you cannot rely on the name to retrieve the InfoStore from the collection. However, you can iterate through all objects in the collection using the InfoStores collection object’s Item property, and then examine properties of the individual InfoStore objects. You can also rely on the InfoStore object’s ID property, which is guaranteed to be unique.


Count Property (InfoStores Collection)

The Count property returns the number of InfoStore objects in the collection. Read-only.

Syntax

objInfoStoresColl.Count

Data Type

Long

Example

This example maintains a global variable as an index into the small collection, and uses the Count property to check its validity:

' from InfoStores_NextItem

' iInfoStoresCollIndex is an integer used as an index

'   check for empty collection...

'   check index upper bound

    If iInfoStoresCollIndex >= objInfoStoresColl.Count Then

        iInfoStoresCollIndex = objInfoStoresColl.Count

        MsgBox "Already at end of InfoStores collection"

        Exit Function

    End If

    ' index is < count; can be incremented by 1

    iInfoStoresCollIndex = iInfoStoresCollIndex + 1

    Set objInfoStore = objInfoStoresColl.Item(iInfoStoresCollIndex)

    If objInfoStore Is Nothing Then

        MsgBox "Error, cannot get this InfoStore object"

        Exit Function

    Else

        MsgBox "Selected InfoStore " & iInfoStoresCollIndex

    End If

See Also

InfoStore Object


Item Property (InfoStores Collection)

The Item property returns a single InfoStore object from the collection. Read-only.

Syntax

objInfoStoresColl.Item(index)

objInfoStoresColl

Required. Specifies the InfoStores collection object.

index

A long integer that ranges from 1 to objInfoStoresColl.Count.

Data Type

Object

Remarks

The Item property works like an accessor property for small collections.

The Item property is the default property of a InfoStores collection, meaning that InfoStores(index) is syntactically equivalent to InfoStores.Item(index) in Visual Basic code.

Example

' from InfoStores_NextItem

' iInfoStoresCollIndex is an integer used as an index

'   check for empty collection...

'   check index upper bound

    If iInfoStoresCollIndex >= objInfoStoresColl.Count Then

        iInfoStoresCollIndex = objInfoStoresColl.Count

        MsgBox "Already at end of InfoStores collection"

        Exit Function

    End If

    ' index is < count; can be incremented by 1

    iInfoStoresCollIndex = iInfoStoresCollIndex + 1

    Set objInfoStore = objInfoStoresColl.Item(iInfoStoresCollIndex)

    If objInfoStore Is Nothing Then

        MsgBox "Error, cannot get this InfoStore object"

        Exit Function

    Else

        MsgBox "Selected InfoStore " & iInfoStoresCollIndex

    End If

See Also

InfoStore Object


Message Object

The Message object represents a single message, item, document, or form in a folder.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.0
Parent objects:	Messages collection
Child objects:	Attachments collection  Fields collection  Recipients collection
Default property:	Subject
Properties

Property name	Available in version	Type	Access
Application	1.0	String	Read-only
Attachments	1.0	Attachments collection object	Read-only
Class	1.0	Long	Read-only
Conversation	1.0	(Obsolete. Do not use.)	Read/write
ConversationIndex	1.0	String	Read/write
ConversationTopic	1.0	String	Read/write
DeliveryReceipt	1.0	Boolean	Read/write
Encrypted	1.0	Boolean	Read/write
Fields	1.0	Field object or Fields collection object	Read-only
FolderID	1.0	String	Read-only
ID	1.0	String	Read-only
Importance	1.0	Long	Read/write
MAPIOBJECT	1.0	(Not for use with Visual Basic.)	Read/write (Note: Not available to Visual Basic applications)
Parent	1.0	Attachments collection object, Fields collection object, or Recipients collection object	Read-only
ReadReceipt	1.0	Boolean	Read/write
Recipients	1.0	Recipients object or Recipients collection object	Read/write
Sender	1.0	AddressEntry object	Read-only
Sent	1.0	Boolean	Read/write
Session	1.0	Session object	Read-only
Signed	1.0	Boolean	Read/write
Size	1.0	Long	Read-only
StoreID	1.0	String	Read-only
Subject	1.0	String	Read/write
Submitted	1.0	Boolean	Read/write
Text	1.0	String	Read/write
TimeReceived	1.0	Variant (vbDate format)	Read/write
TimeSent	1.0	Variant (vbDate format)	Read/write
Type	1.0	String	Read/write
Unread	1.0	Boolean	Read/write
Methods

Method name	Available in version	Parameters
CopyTo	1.1	folderID as String,  (optional) storeID as String
Delete	1.0	(none)
IsSameAs	1.1	object as Object
MoveTo	1.1	folderID as String,  (optional) storeID as String
Options	1.0	(optional) parentWindow as Long
Send	1.0	(optional) saveCopy as Boolean,  (optional) showDialog as Boolean,  (optional) parentWindow as Long
Update	1.0	(optional) makePermanent as Boolean,  (optional) refreshObject as Boolean
Remarks

A Message object is considered a top-level object, meaning it can be created directly from a Visual Basic program, through either late binding or early binding.

Visual Basic programmers can create new message objects using the Messages collection’s Add method.

C/C++ programmers can create new message objects using the OLE function CoCreateInstance.

See Also

GetMessage Method (Session Object), Messages Property (Folder Object)


Attachments Property (Message Object)

The Attachments property returns a single Attachment object or an Attachments collection object. Read-only.

Syntax

Set objAttachColl = objMessage.Attachments

Set objOneAttach = objMessage.Attachments(index)

objAttachColl

Object. An Attachments collection object.

objMessage

Object. The Message object.

objOneAttach

Object. A single Attachment object.

index

Long. Specifies the number of the attachment within the Attachments collection. Ranges from 1 to the value specified by the Attachments collection’s Count property.

Example

This example uses the Attachments property to retrieve an attachment for the message:

' from the sample function Message_Attachments

    Set objAttachColl = objOneMsg.Attachments

    If objAttachColl Is Nothing Then

        MsgBox "unable to set Attachments collection"

        Exit Function

    Else

        MsgBox "Attachments count for this msg: " & objAttachColl.Count

        iAttachCollIndex = 0    ' reset global index variable

    End If

' from the sample function Attachments_FirstItem

    iAttachCollIndex = 1

    Set objAttach = objAttachColl.Item(iAttachCollIndex)

See Also

Attachment Object

Attachments Collection


Conversation Property (Message Object)

The Conversation property is obsolete. It has been replaced by the ConversationIndex and ConversationTopic properties.

See Also

Working With Conversations


ConversationIndex Property (Message Object)

The ConversationIndex property specifies the index to the conversation thread of the message. Read/write.

Syntax

objMessage.ConversationIndex

Data Type

String

Remarks

The ConversationIndex property is a string that represents a hexadecimal number. Valid characters within the string include the numbers 0 through 9 and the letters A through F (uppercase or lowercase).

A conversation is a group of related messages that have the same ConversationTopic property value. In a discussion application, for example, users can save original messages and response messages. Messages can be tagged with the ConversationIndex property so that users can group messages by conversation.

You can use your own convention to decide how this index should be used. However, it is recommended that you adopt the same convention that is used by the Microsoft Exchange Client message viewer, so that you can use that viewer’s user interface to show the relationships between messages in a conversation.

By convention, Microsoft Exchange Server uses ConversationIndex values that represent concatenated time stamp values. The first time stamp in the string represents the original message. When a new message represents a reply to a conversation message, it copies the ConversationIndex string of the message it is replying to, and then appends a time stamp value to the end of the string. The new string value is used as the ConversationIndex value of the new message.

When you use this convention, you can see relationships among messages when you sort the messages by ConversationIndex values.

The ConversationIndex property corresponds to the MAPI property PR_CONVERSATION_INDEX.

Example

The following example takes advantage of an OLE function that is available on computers that run the OLE Messaging Library. The CoCreateGUID function returns a value that consists of a time stamp and a machine identifier; this sample code saves the part that contains the time stamp.

' declarations section

Type GUID  ' global unique identifier; contains a time stamp

    Guid1 As Long

    Guid2 As Long

    Guid3 As Long

    Guid4 As Long

End Type

' function appears in OLE32.DLL on Windows/NT and Windows 95

Declare Function CoCreateGuid Lib "COMPOBJ.DLL" (pGuid As GUID) As Long

Global Const S_OK = 0   ' return value from CoCreateGuid

Function Util_GetEightByteTimeStamp() As String

Dim lResult As Long

Dim lGuid As GUID

    ' Exchange conversation is a unique 8-byte value

    ' Exchange client viewer sorts by concatenated properties

    On Error GoTo error_olemsg

    lResult = CoCreateGuid(lGuid)

    If lResult = S_OK Then

        Util_GetEightByteTimeStamp = _

            Hex$(lGuid.Guid1) & Hex$(lGuid.Guid2)

    Else

        Util_GetEightByteTimeStamp = "00000000"   ' zeroes

    End If

    Exit Function

error_olemsg:

    MsgBox "Error " & Str(Err) & ": " & Error$(Err)

    Util_GetEightByteTimeStamp = "00000000"

    Exit Function

End Function

Function Util_NewConversation()

Dim i As Integer

Dim objNewMsg As Object      ' new message object

Dim strNewIndex As String    ' value for ConversationIndex

' ... error handling...

    Set objNewMsg = objSession.Outbox.Messages.Add

' ... error handling...

    With objNewMsg

        .Subject = "used space vehicle wanted"

        .ConversationTopic = .Subject

        .ConversationIndex = Util_GetEightByteTimeStamp() ' utility

        .Text = "Wanted: Apollo or Mercury spacecraft with low mileage."

           ' or you could pick the public folder from the address book

        Set objOneRecip = .Recipients.Add(Name:="Car Ads", Type:=mapiTo)

        If objOneRecip Is Nothing Then

            MsgBox "Unable to create the public folder recipient"

            Exit Function

        End If

        .Recipients.Resolve

        .Update

        .Send showDialog:=False

    End With

End Function

A subsequent reply to a message should copy the ConversationTopic property and append its own time stamp to the original message’s time stamp, as shown in the following example:

Function Util_ReplyToConversation()

Dim objPublicFolder As Object

Dim i As Integer

Dim objOriginalMsg As Object ' original message in public folder

Dim objNewMsg As Object      ' new message object for reply

Dim strPublicFolderID As String ' ID for public folder

    Set objNewMsg = objSession.Outbox.Messages.Add

'   error checking...obtain objOriginalMsg and check that it is valid

    With objNewMsg

        .Text = "How about a slightly used Gemini?"   ' new text

        .Subject = objOriginalMsg.Subject   ' copy original properties

        .ConversationTopic = objOriginalMsg.ConversationTopic

        ' append time stamp; compatible with Microsoft Exchange client

        .ConversationIndex = objOriginalMsg.ConversationIndex & _

                              Util_GetEightByteTimeStamp() ' append new

        ' message was sent to a public folder so can copy recipient

        Set objOneRecip = .Recipients.Add( _

                         Name:=objOriginalMsg.Recipients.Item(1).Name, _

                         Type:=mapiTo)

       ' ...more error handling

        .Recipients.Resolve

        .Update

        .Send showDialog:=False

    End With

' ... error handling

End Function

See Also

Conversation Property, ConversationTopic Property (Message Object), Working With Conversations


ConversationTopic Property (Message Object)

The ConversationTopic property specifies the name of the conversation thread. Read/write.

Syntax

objMessage.ConversationTopic

Data Type

String

Remarks

A conversation is a group of related messages. The ConversationTopic property is the string that describes the overall topic of the conversation. To be defined as messages within the same conversation, the messages must have the same value in their ConversationTopic property. The ConversationIndex property represents an index that indicates a sequence of messages within that conversation.

When you start an initial message, set the ConversationTopic property to an appropriate value that will apply to all messages within the conversation. For many applications, the message Subject property is appropriate.

Note that the OLE Messaging Library does not automatically copy the ConversationTopic property to other messages. When your application manages messages that represent replies to an original message, you should set the ConversationTopic property to the same value as the original message.

To change the ConversationTopic for all messages in a conversation thread, you must change the property within each message in that thread.

The ConversationTopic property corresponds to the MAPI property PR_CONVERSATION_TOPIC.

Example

See the example for the ConversationIndex property.

See Also

Conversation Property, ConversationIndex Property (Message Object), Working With Conversations


CopyTo Method (Message Object)

The CopyTo method makes a copy of this Message object in another folder.

Syntax

Set objCopiedMessage = objMessage.CopyTo(folderID [, storeID] )

Parameters

objCopiedMessage

On successful return, contains the copied Message object.

objMessage

Required. This Message object.

folderID

Required. String. The unique identifier of the destination Folder object in which the copy of this message is to appear.

storeID

Optional. String. The unique identifier of the InfoStore object in which the message copy is to appear, if different from this message’s InfoStore.

Remarks

All properties that have been set on this message are copied, whether they have read-only or read/write access. Each property is copied with its value and access unchanged.

The copy operation takes effect immediately. This Message object remains unchanged by the CopyTo method.


Delete Method (Message Object)

The Delete method deletes the Message object.

Syntax

objMessage.Delete

Parameters

objMessage

Required. The Message object.

Remarks

The Delete method permanently deletes the message from the system. Such a deleted message cannot be recovered. Before calling the Delete method, the application can prompt the user to verify whether the message should be permanently deleted.

See Also

Delete Method (Messages Collection)


DeliveryReceipt Property (Message Object)

The DeliveryReceipt property is TRUE if a delivery-receipt notification message is requested. Read/write.

Syntax

objMessage.DeliveryReceipt

Data Type

Boolean

Remarks

Set the DeliveryReceipt property to TRUE to obtain a message when the recipients receive the message. The default setting for the OLE Messaging Library is FALSE.

The DeliveryReceipt property corresponds to the MAPI property PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED.

See Also

Making Sure The Message Gets There

ReadReceipt Property (Message Object)


Encrypted Property (Message Object)

The Encrypted property is TRUE if the message has been encrypted. Read/write.

Syntax

objMessage.Encrypted

Data Type

Boolean

Remarks

The OLE Messaging Library does not encrypt or digitally sign the message. The Encrypted property is dependent upon the message store provider.

The Encrypted property corresponds to the SECURITY_ENCRYPTED flag of the MAPI property PR_SECURITY.

See Also

Securing Messages

Signed Property (Message Object)


Fields Property (Message Object)

The Fields property returns a single Field object or a Fields collection object. Read-only.

Syntax

objMessage.Fields

objMessage.Fields(index)

objMessage.Fields(proptag)

objMessage.Fields(name)

index

Short integer (less than or equal to 65535). Specifies the index within the Fields collection.

proptag

Long integer (greater than or equal to 65536). Specifies the property tag value for the MAPI property to be retrieved.

name

String. Specifies the name of the custom MAPI property.

Data Type

Object

Remarks

The Fields property returns one or more of the fields associated with a Message object. Each field typically corresponds to a MAPI property.

The Fields property provides a generic access mechanism that allows Visual Basic and Visual C++ programmers to retrieve the value of a MAPI property using either its name or its MAPI property tag. For access with the property tag, use Message.Fields(proptag), where proptag is the 32-bit MAPI property tag associated with the property, such as PR_MESSAGE_CLASS. To access a named property, use Message.Fields(name), where name is a string that represents the custom property name.

Example

' get the message’s Fields collection

    Set objFieldsColl = objOneMsg.Fields

' get the first field of the Fields collection of the message

    i = 1

    Set objOneField = objFieldsColl.Item(i)

    If objOneField Is Nothing Then

        MsgBox "error; cannot get this Field object"

    Else

        MsgBox "Selected Field " & i

    End If


FolderID Property (Message Object)

The FolderID property returns the unique identifier of the folder in which the message resides. Read-only.

Syntax

objMessage.FolderID

Data Type

String

Remarks

Save the folder identifier to retrieve the folder at a later time using the Session object’s GetFolder method.

MAPI systems assign a permanent, unique identifier string when an object is created. These identifiers do not change from one MAPI session to another.

The FolderID property corresponds to the MAPI property PR_PARENT_ENTRYID, converted to a string of hexadecimal characters.

See Also

GetFolder Method (Session Object)


ID Property (Message Object)

The ID property returns the unique identifier of this message object. Read-only.

Syntax

objMessage.ID

Data Type

String

Remarks

MAPI systems assign a permanent, unique identifier string when an object is created. These identifiers do not change from one MAPI session to another.

The ID property corresponds to the MAPI property PR_ENTRYID, converted to a string of hexadecimal characters.

Example

'     Save id of last message accessed; use at startup

'     from the sample function Message_ID

    strMessageID = objOneMsg.Id

' ... on shutdown, save the ID to storage

' ... on startup, get the ID from storage and restore

'     from the sample function Session_GetMessage

    Set objOneMsg = objSession.GetMessage(strMessageID)

See Also

GetMessage Method (Session Object)


Importance Property (Message Object)

The Importance property returns or sets the importance of the message as one of mapiNormal (the default), mapiLow, or mapiHigh. Read/write.

Syntax

objMessage.Importance

Data Type

Long

Remarks

The following values are defined:

Constant	Value	Description
mapiLow	0	Low importance
mapiNormal	1	Normal importance (default)
mapiHigh	2	High importance
The Importance property corresponds to the MAPI property PR_IMPORTANCE.

Example

This example sets the importance of a message as high:

' from the sample function QuickStart:

    Set objMessage = objSession.Outbox.Messages.Add

    '  error checking here to verify the message was created...

    objMessage.Subject = "Gift of droids"

    objMessage.Text = "Help us, Obi-wan. You are our only hope."

    objMessage.Importance = mapiHigh

    objMessage.Send

See Also

Send Method (Message Object)


IsSameAs Method (Message Object)

The IsSameAs method returns True if this Message object is the same as the Message object being compared against.

Syntax

objMessage.IsSameAs(objMessage2)

Parameters

objMessage

Required. This Message object.

objMessage2

Required. The Message object being compared against.

Remarks

Two Message objects are considered to be the same if and only if they are instantiations of the same physical (persistent) object. Two objects with the same value are still considered different if they do not instantiate the same physical object, for example if one is a copy of the other. In such a case IsSameAs returns False.

The IsSameAs method ultimately calls one of the MAPI CompareEntryIDs methods to determine if two objects are the same. A generic comparison of any two object identifiers is also available with the Session object’s CompareIDs method.


MAPIOBJECT Property (Message Object)

The MAPIOBJECT property returns an IUnknown pointer to this Message object. Not available to Visual Basic applications. Read/write.

Syntax

objMessage.MAPIOBJECT

Data Type

Variant (VT_UNKNOWN)

Remarks

The MAPIOBJECT property is not available to Visual Basic programs. It is available only to C/C++ programs that use the OLE Messaging Library. The MAPIOBJECT property is an IUnknown object, which is not supported by Visual Basic. Visual Basic supports IDispatch objects. For more information, see the Microsoft OLE Programmer’s Reference.

See Also

Introduction to OLE Automation

How Programmable Objects Work


MoveTo Method (Message Object)

The MoveTo method relocates this Message object to another folder.

Syntax

Set objMovedMessage = objMessage.MoveTo(folderID [, storeID ] )

Parameters

objMovedMessage

On successful return, contains the moved Message object.

objMessage

Required. This Message object.

folderID

Required. String. The unique identifier of the destination Folder object in which this message is to appear.

storeID

Optional. String. The unique identifier of the InfoStore object in which the message is to appear, if different from this current InfoStore.

Remarks

All properties that have been set on this message are moved, whether they have read-only or read/write access. Each property is moved with its value and access unchanged.

The move operation takes effect immediately. This Message object is no longer accessible at its former location once the MoveTo method returns.


Options Method (Message Object)

The Options method displays a message options dialog box where the user can change the submission options for a message.

Syntax

objMessage.Options( [parentWindow] )

Parameters

objMessage

Required. The Message object.

parentWindow

Optional. Long. The parent window handle for the options dialog box. A value of 0 (the default) specifies an application-modal dialog box.

Remarks

The options are provider-specific and are registered by the provider. Providers are not required to register option sheets. When providers do not register options, the Options method returns the error code MAPI_E_NOT_FOUND.

Per-message options are properties of a message that control its behavior after submission. The per-message options are part of the message envelope, not its content.

The following methods can also invoke MAPI dialog boxes: Delete and Details methods (AddressEntry object), Send method (Message object), Resolve method (Recipient object and Recipients collection), AddressBook and Logon methods (Session object).

See Also

Send Method (Message Object)


ReadReceipt Property (Message Object)

The ReadReceipt property is TRUE if a read-receipt notification message is requested. Read/write.

Syntax

objMessage.ReadReceipt

Data Type

Boolean

Remarks

The ReadReceipt property corresponds to the MAPI property PR_READ_RECEIPT_REQUESTED.

See Also

DeliveryReceipt Property (Message Object)

Making Sure The Message Gets There


Recipients Property (Message Object)

The Recipients property returns a single Recipient object or a Recipients collection object. Read/write.

Syntax

Set objRecipColl = objMessage.Recipients

Set objOneRecip = objMessage.Recipients(index)

objRecipColl

Object. A Recipients collection object.

objMessage

Object. The Message object.

objOneRecip

Object. A single Recipient object.

index

Long. Specifies the number of the recipient within the Recipients collection. Ranges from 1 to the value specified by the Recipients collection’s Count property.

Data Type

Object

Example

The Recipients property itself is read-only, indicating that you cannot set the value of this property to indicate another collection. However, you can change individual Recipient objects within the collection, add Recipient objects to the collection, and remove Recipient objects from the collection.

This example copies each of the recipients from the original message objOneMsg to the copy objCopyMsg:

' from the sample function Util_CopyMessage

    For i = 1 To objOneMsg.Recipients.Count Step 1

        strRecipName = objOneMsg.Recipients.Item(i).Name

        If strRecipName <> "" Then

            Set objOneRecip = objCopyMsg.Recipients.Add

            If objOneRecip Is Nothing Then

                MsgBox "unable to create recipient in message copy"

                Exit Function

            End If

            objOneRecip.Name = strRecipName

        End If

    Next i


Send Method (Message Object)

The Send method sends the message to the recipients via the MAPI system.

Syntax

objMessage.Send( [saveCopy, showDialog, parentWindow] )

Parameters

objMessage

Required. The Message object.

saveCopy

Optional. Boolean. If TRUE or omitted, saves a copy of the Message in a user folder, such as the Sent Messages folder.

showDialog

Optional. Boolean. If TRUE, displays a Send Message dialog box where the user can change the message contents or recipients. The default value is FALSE.

parentWindow

Optional. Long. The parent window handle for the Send Message dialog box. A value of 0 (the default) specifies that any dialog box displayed is application-modal. The parentWindow parameter is ignored unless showDialog is TRUE.

Remarks

The Send method is similar to the Update method, except Send ignores the parent Folder object of the message and saves the message in the current user’s default Outbox folder. Messaging systems retrieve messages from the Outbox and transport them to the recipients.

Note that the Send method invalidates the Message object. Attempts to access the original Message object result in an error. The original Message object does not have to be set to Nothing, but it should not be used for subsequent operations. Use a new Message object to obtain the message from the Outbox or from the Sent Messages folder.

Note that there is one case in which the OLE Messaging Library does not display the dialog box when showDialog is set to TRUE: The dialog box is not displayed when the recipient has a null display name. The dialog box is displayed for a null recipient (when the Recipient object is set to Nothing).

The following methods can also invoke MAPI dialog boxes: Delete and Details methods (AddressEntry object), Options method (Message object), Resolve method (Recipient object and Recipients collection), AddressBook and Logon methods (Session object).

See Also

Creating and Sending a Message, Posting Messages to a Public Folder, Sent Property (Message Object), Submitted Property (Message Object)


Sender Property (Message Object)

The Sender property returns the sender of a message as an AddressEntry object. Read-only.

Syntax

Set objAddrEntry = objMessage.Sender

objAddrEntry

Object. The returned AddressEntry object that represents the messaging user that sent the message.

objMessage

Object. The Message object.

Data Type

Object

Remarks

The Sender property corresponds to the MAPI property PR_SENDER_ENTRYID.

Example

This example displays the name of the sender of a message:

' from the sample function Message_Sender

    Set objAddrEntry = objOneMsg.Sender

    If objAddrEntry Is Nothing Then

        MsgBox "Could not set the address entry object from the Sender"

        Exit Function

    End If

    MsgBox "Message was sent by " & objAddrEntry.Name

See Also

TimeReceived Property (Message Object)


Sent Property (Message Object)

The Sent property is TRUE if the message has been sent through the MAPI system. Read/write.

Syntax

objMessage.Sent

Data Type

Boolean

Remarks

In general, there are three different kinds of messages: messages that get sent, messages that get posted, and messages that get saved. Messages that get sent are characterized by traditional e-mail messages sent to a recipient or public folder. Messages that get posted are characterized by messages created in a public folder. Messages that get saved are characterized by messages that are created and saved without either sending or posting.

For all three kinds of messages, you use the Submitted, Sent, and Unread properties and the Send or Update methods.

The following table summarizes the use of the message properties and methods for these three kinds of messages.

Kind of message	Method	Submitted property	Sent property	Unread property
Gets sent	Send	Send method sets TRUE	Spooler sets TRUE	Spooler sets TRUE
Gets posted	Update	Application sets FALSE	Application sets TRUE	Application sets TRUE
Gets saved	Update	Application sets FALSE	Application sets FALSE	Application sets TRUE
For messages that get sent, the Sent property can be written until the time that you call the Send or Update method. Note that changing the Sent property to TRUE does not cause the message to be sent. Only the Send method actually causes the message to be transmitted. After you call the Send method, the messaging system controls the Sent property and changes it to a read-only property.

A common use for writing a value to the Sent property is to set the property to FALSE so that an electronic mail system can save pending, unsent messages in an Outbox folder, or to save work-in-progress messages in a Pending folder before committing the messages to a public information store. Note that you can cause an error if you set the property incorrectly.

The Sent property is changed using the following sequence. When you call the Send method to send a message to a recipient, the message is moved to the Outbox and the Message object’s Submitted property is set to TRUE. When the messaging system spooler actually starts transporting the message, the Sent property is set to TRUE.

When the message is not sent using the Send method, the MAPI system does not change the Sent property.  For posted and saved messages that call the Update method, you should set the value of the Sent property to TRUE just before you post the message.

The Sent property corresponds to the MAPI property PR_MESSAGE_FLAGS and the flag MSGFLAG_UNSEND.

See Also

Creating and Sending a Message

Posting Messages to a Public Folder

Submitted Property (Message Object)


Signed Property (Message Object)

The Signed property is TRUE if the message has been tagged with a digital signature. Read/write.

Syntax

objMessage.Signed

Data Type

Boolean

Remarks

The Signed property is dependent upon the message store provider. The OLE Messaging Library does not actually encrypt or digitally sign the message.

The Signed property corresponds to the SECURITY_SIGNED flag of the MAPI property PR_SECURITY.

See Also

Encrypted Property (Message Object)

Securing Messages


Size Property (Message Object)

The Size property returns the approximate size in bytes of the message. Read-only.

Syntax

objMessage.Size

Data Type

Long

Remarks

The Size property is not valid until after the first Update or Send operation.

The Size property corresponds to the MAPI property PR_MESSAGE_SIZE.

See Also

Attachments Property (Message Object)

Text Property (Message Object)


StoreID Property (Message Object)

The StoreID property represents the unique identifier for the message store that contains this message. Read-only.

Syntax

objMessage.StoreID

Data Type

String

Remarks

The StoreID property corresponds to the MAPI property PR_STORE_ENTRYID, converted to a string of hexadecimal characters.

See Also

GetMessage Method (Session Object), Sent Property (Message Object)


Subject Property (Message Object)

The Subject property returns or sets the subject of the message as a string. Read/write.

Syntax

objMessage.Subject

Data Type

String

Remarks

The Subject property corresponds to the MAPI property PR_SUBJECT.

The Subject property is the default property of a Message object, meaning that Message is syntactically equivalent to Message.Subject in Visual Basic code.

Example

This example sets the subject of a message:

Dim objMessage As Object  ' assume valid message

objMessage.Subject = "Microsoft Bob: Check It Out"

See Also

Text Property (Message Object)


Submitted Property (Message Object)

The Submitted property is TRUE when the message has been submitted. Read/write.

Syntax

objMessage.Submitted

Data Type

Boolean

Remarks

In general, there are three different kinds of messages: messages that get sent, messages that get posted, and messages that get saved. Messages that get sent are characterized by traditional e-mail messages sent to a recipient or public folder. Messages that get posted are characterized by messages created in a public folder. Messages that get saved are characterized by messages that are created and saved without either sending or posting.

For all three kinds of messages, you use the Submitted, Sent, and Unread properties and the Send or Update methods.

The following table summarizes the use of the message properties and methods for these three kinds of messages.

Kind of message	Method	Submitted property	Sent property	Unread property
Gets sent	Send	Send method sets TRUE	Spooler sets TRUE	Spooler sets TRUE
Gets posted	Update	Application sets FALSE	Application sets TRUE	Application sets TRUE
Gets saved	Update	Application sets FALSE	Application sets FALSE	Application sets TRUE
For messages that get sent, you create the message and then call the Send method. When the Send method is successful, the Submitted property is set to TRUE. The value does not change after that point. For messages sent to a public folder, the Send method sets the Submitted property (rather than the Sent property) to TRUE.

For messages that get posted, you create the message directly within a public folder and call Update. When you create the message within the public folder, some viewers do not allow the message to become visible to others until you set the Submitted property to TRUE.

The Submitted property corresponds to the MAPI property PR_MESSAGE_FLAGS.

See Also

Send Method (Message Object)

Sent Property (Message Object)


Text Property (Message Object)

The Text property returns or sets the body text of the message as a string. Read/write.

Syntax

objMessage.Text

Data Type

String

Remarks

The maximum size of the body text can be limited by the tool that you use to manipulate string variables (such as Microsoft Visual Basic).

Note that the Text property is a plain text representation of the message body and does not support formatted text.

The Text property corresponds to the MAPI property PR_BODY.

Example

This example sets the body text of a message:

Dim objMessage As Object    ' assume valid message

objMessage.Text = "Thank you for buying Microsoft Home(TM) products."

See Also

Subject Property (Message Object)


TimeReceived Property (Message Object)

The TimeReceived property sets or returns the date and time the message was received as a vbDate variant data type. Read/write.

Syntax

objMessage.TimeReceived

Data Type

Variant (vbDate format)

Remarks

The TimeReceived and TimeSent properties set and return dates and times as the local time for the user’s system.

When you send messages using the Message object’s Send method, the MAPI system sets the TimeReceived and TimeSent properties for you. However, when you post messages in a public folder, you must first explicitly set these properties. For a message posted to a public folder, set both properties to the same time value.

Note that the TimeReceived and TimeSent properties represent local time. However, when you access MAPI time properties through the Fields collection’s Item property, the time values represent Greenwich Mean Time.

The TimeReceived property corresponds to the MAPI Property PR_MESSAGE_DELIVERY_TIME.

Example

This example displays the date and time a message was sent and received:

' from the sample function Message_TimeSentAndReceived

   ' verify that objOneMsg is valid, then...

    With objOneMsg

        strMsg = "Message sent " & Format(.TimeSent, "Short Date")

        strMsg = strMsg & ", " & Format(.TimeSent, "Long Time")

        strMsg = strMsg & "; received "

        strMsg = strMsg & Format(.TimeReceived, "Short Date") & ", "

        strMsg = strMsg & Format(.TimeReceived, "Long Time")

        MsgBox strMsg

    End With

See Also

Item Property (Fields Collection)

TimeSent Property (Message Object)


TimeSent Property (Message Object)

The TimeSent property sets or returns the date and time the message was sent as a vbDate variant data type. Read/write.

Syntax

objMessage.TimeSent

Data Type

Variant (vbDate format)

Remarks

The TimeReceived and TimeSent properties return dates and times as the local time for the user’s system.

When you send messages using the Message object’s Send method, the MAPI system sets the TimeReceived and TimeSent properties for you. However, when you post messages in a public folder, you must first explicitly set these properties. For a message posted to a public folder, set both properties to the same time value.

Note that the TimeReceived and TimeSent properties represent local time. However, when you access MAPI time properties through the Fields collection Item property, the time values represent Greenwich Mean Time.

The TimeSent property corresponds to the MAPI Property PR_CLIENT_SUBMIT_TIME.

Example

This example displays the date a message was sent and received:

' from the sample function Message_TimeSentAndReceived

   ' verify that objOneMsg is valid, then...

    With objOneMsg

        strMsg = "Message sent " & Format(.TimeSent, "Short Date")

        strMsg = strMsg & ", " & Format(.TimeSent, "Long Time")

        strMsg = strMsg & "; received "

        strMsg = strMsg & Format(.TimeReceived, "Short Date") & ", "

        strMsg = strMsg & Format(.TimeReceived, "Long Time")

        MsgBox strMsg

    End With

See Also

Item Property (Fields Collection)

TimeReceived Property (Message Object)


Type Property (Message Object)

The Type property returns or sets the MAPI message class for the message. Read/write.

Syntax

objMessage.Type

Data Type

String

Remarks

The Type property returns or sets the MAPI message class for the message. By default, the OLE Messaging Library sets the Type value of new messages to the MAPI message class IPM.Note.

The OLE Messaging Library does not impose any restrictions on this value except that it be a valid string value. You can set the value to any string that is meaningful for your application. MAPI uses message class strings in the form IPM.application.subClass or IPC.application.subClass.

For more information about MAPI message classes, see the MAPI Programmer’s Reference.

The Type property corresponds to the MAPI property PR_MESSAGE_CLASS.

See Also

GetFirst Method (Messages Collection)


Unread Property (Message Object)

The Unread property is TRUE if the message has not been read by the current user. Read/write.

Syntax

objMessage.Unread

Data Type

Boolean

Remarks

When you post a message to a public folder, you should set the Unread, Submitted, and Sent properties to TRUE before calling the Send or Update method.

The Unread property corresponds to the MAPI property PR_MESSAGE_FLAGS.

See Also

Posting a Message to a Public Folder

Sent Property (Message Object)


Update Method (Message Object)

The Update method saves the message in the MAPI system.

Syntax

objMessage.Update( [makePermanent, refreshObject] )

Parameters

objMessage

Required. The Message object.

makePermanent

Optional. Boolean. TRUE indicates that the property cache is flushed and all changes are committed to the underlying message store. FALSE indicates that the property cache is flushed and not committed to the message store. The default value is TRUE.

refreshObject

Optional. Boolean. TRUE indicates that the property cache is reloaded from the values in the underlying message store. FALSE indicates that the property cache is not reloaded. The default value is FALSE.

Remarks

Changes to Message objects are not permanently saved in the MAPI system until you call the Update method with the makePermanent parameter set to TRUE.

For improved performance, the OLE Messaging Library caches property changes in private storage and updates either the object or the underlying message store only when you explicitly request such an update. For efficiency, you should make only one call to Update with its makePermanent parameter set to TRUE.

The makePermanent and refreshObject parameters combine to cause the following changes:

	refreshObject = TRUE	refreshObject = FALSE
makePermanent = TRUE	Commit all changes, flush the cache, and reload the cache from the message store.	Commit all changes and flush the cache.
makePermanent = FALSE	Flush the cache and reload the cache from the message store.	Flush the cache.
Call Update(FALSE, TRUE) to flush the cache and then reload the values from the message store.

Example

This example changes the subject of the first message in a folder:

Set objMessage = objSession.Inbox.GetFirst

' ... verify message

objMessage.Subject = "This is the new subject"

objMessage.Update

To add a new Message object, use the Add method followed by the Update method. This example saves a new message:

Dim objMessage As Object   ' message object

' ...

Set objMessage = objSession.Outbox.Messages.Add

objMessage.Subject = "Microsoft Bob(TM)"

objMessage.Text = "This is incredible, you've got to see it!"

objMessage.Update makePermanent:=True

See Also

Send Method (Message Object)


MessageFilter Object

The MessageFilter object specifies criteria for restricting a search on a Messages collection.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.1
Parent objects:	Messages collection
Child objects:	Fields collection
Default property:	Subject
Properties

Property name	Available in version	Type	Access
Application	1.1	String	Read-only
Class	1.1	Long	Read-only
Conversation	1.1	String	Read/write
Fields	1.1	Field object or Fields collection object	Read-only
Importance	1.1	Long	Read/write
Not	1.1	Boolean	Read/write
Or	1.1	Boolean	Read/write
Parent	1.1	Messages collection object	Read-only
Recipients	1.1	Recipient object or Recipients collection object	Read/write
Sender	1.1	AddressEntry object	Read/write
Sent	1.1	Boolean	Read/write
Session	1.1	Session object	Read-only
Size	1.1	Long	Read/write
Subject	1.1	String	Read/write
Text	1.1	String	Read/write
TimeFirst	1.1	Variant (vbDate format)	Read/write
TimeLast	1.1	Variant (vbDate format)	Read/write
Type	1.1	String	Read/write
Unread	1.1	Boolean	Read/write
Methods

Method name	Available in version	Parameters
IsSameAs	1.1	object as Object
Remarks

A MessageFilter object with no criteria is created by default for every Messages collection. This means that initially the filter’s properties are unset and its child Fields collection is empty. You specify the filter by setting values for its properties, and by adding fields to its Fields collection and setting a value for each added field.

The filter is invoked when the Messages collection is traversed with the Get methods. Each field participates in a MAPI search restriction comparing the field’s Value property against the value of the Message property specified by the field’s ID property.

For fields of data type other than String, the MAPI search restriction type is RES_PROPERTY with relational operator RELOP_EQ. For fields of data type String, the restriction type is RES_CONTENT with fuzzy level options FL_SUBSTRING, FL_IGNORECASE, and FL_LOOSE.

The results of the individual restrictions are normally ANDed together to form the final filter value. You can change this by setting the Or property, which causes all the results to be ORed instead of ANDed. You can also set the Not property to specify that the result of each individual restriction is to be negated before being ANDed or ORed into the final filter value.

The MessageFilter object is persistent within its parent Messages collection. It is not deleted even when it is released, and it remains attached to the Messages collection until the collection’s Filter property is set to Nothing or the collection is itself released.


Conversation Property (MessageFilter Object)

The Conversation property sets filtering on a message’s conversation topic. Read/write.

Syntax

objMessageFilter.Conversation

Data Type

String

Remarks

The ConversationTopic property specifies that the message filter should pass only messages whose ConversationTopic exactly matches the value of ConversationTopic.

A conversation is a group of related messages. The Message object’s ConversationTopic property is the string that describes the overall topic of the conversation. To be defined as messages within the same conversation, the messages must have the same value in their ConversationTopic property. The ConversationIndex property represents an index that indicates a sequence of messages within that conversation.

The ConversationTopic property corresponds to the MAPI property PR_CONVERSATION_TOPIC.

See Also

Working With Conversations


Fields Property (MessageFilter Object)

The Fields property returns a single Field object or a Fields collection object. Read-only.

Syntax

objMessageFilter.Fields

objMessageFilter.Fields(index)

objMessageFilter.Fields(proptag)

objMessageFilter.Fields(name)

index

Short integer (less than or equal to 65535). Specifies the index within the Fields collection.

proptag

Long integer (greater than or equal to 65536). Specifies the property tag value for the MAPI property to be retrieved.

name

String. Specifies the name of the custom MAPI property.

Data Type

Object

Remarks

The Fields property returns one or more of the fields associated with a MessageFilter object. Each field typically corresponds to a MAPI property, and together the fields that have been added to the collection specify the filter.

The Fields property provides a generic access mechanism that allows Visual Basic and Visual C++ programmers to retrieve the value of a MAPI property using either its name or its MAPI property tag. For access with the property tag, use MessageFilter.Fields(proptag), where proptag is the 32-bit MAPI property tag associated with the property, such as PR_MESSAGE_CLASS. To access a named property, use MessageFilter.Fields(name), where name is a string that represents the custom property name.


Importance Property (MessageFilter Object)

The Importance property sets filtering on a message’s importance to mapiNormal (the default), mapiLow, or mapiHigh. Read/write.

Syntax

objMessageFilter.Importance

Data Type

Long

Remarks

The following values are defined:

Constant	Value	Description
mapiLow	0	Low importance
mapiNormal	1	Normal importance (default)
mapiHigh	2	High importance
The Importance property corresponds to the MAPI property PR_IMPORTANCE.


IsSameAs Method (MessageFilter Object)

The IsSameAs method returns True if this MessageFilter object is the same as the MessageFilter object being compared against.

Syntax

objMessageFilter.IsSameAs(objMsgFilter2)

Parameters

objMessageFilter

Required. This MessageFilter object.

objMsgFilter2

Required. The MessageFilter object being compared against.

Remarks

Two MessageFilter objects are considered to be the same if and only if they are instantiations of the same physical (persistent) object. Two objects with the same value are still considered different if they do not instantiate the same physical object, for example if one is a copy of the other. In such a case IsSameAs returns False.

The IsSameAs method ultimately calls one of the MAPI CompareEntryIDs methods to determine if two objects are the same. A generic comparison of any two object identifiers is also available with the Session object’s CompareIDs method.


Not Property (MessageFilter Object)

The Not property specifies that all restriction values are to be negated before being ANDed or ORed to specify the message filter. Read/write.

Syntax

objMessageFilter.Not

Data Type

Boolean

Remarks

If the Not property is False, the restriction values are treated normally. If it is True, each value is toggled (between True and False) before being used.


Or Property (MessageFilter Object)

The Or property specifies that the restriction values are to be ORed instead of ANDed to specify the message filter. Read/write.

Syntax

objMessageFilter.Or

Data Type

Boolean

Remarks

If the Or property is False, all the restriction values are ANDed together. If it is True, the values are ORed together.


Recipients Property (MessageFilter Object)

The Recipients property sets filtering on whether a message’s recipients include a particular Recipient object. Read/write.

Syntax

Set objOneRecip = objMessageFilter.Recipients(index)

objOneRecip

Object. A single Recipient object.

objMessageFilter

Object. This MessageFilter object.

index

Long. Specifies the number of the recipient within the Recipients collection. Ranges from 1 to the value specified by the Recipients collection’s Count property.

Data Type

Object

Remarks

Although the Recipients property nominally deals with a Recipients collection, only the first member participates in message filtering. You should not maintain more than one Recipient object in the collection.

The Recipients property specifies that the message filter should pass only messages with a recipient corresponding to the Recipients property. The comparison uses the Name property of both Recipient objects. The filter passes the message if the Name property of any of its recipients contains the filter recipient’s Name property as a substring.

Example

This example copies the first valid recipient from an original message to a message filter in order to restrict the Messages collection to messages containing that recipient:

Dim objOneRecip as Object

' assume objMessage and objMessageFilter are valid

objMessageFilter.Recipients.Delete ' remove any filter recipients

For I

    strRecipName = objMessage.Recipients.Item(1).Name

    If strRecipName <> "" Then

        Set objOneRecip = objMessageFilter.Recipients.Add

        If objOneRecip Is Nothing Then

            MsgBox "unable to create recipient in message filter"

            Exit Function

        End If

        objOneRecip.Name = strRecipName

        objOneRecip.Address = objMessage.Recipients.Item(i).Address

        objOneRecip.Type = objMessage.Recipients.Item(i).Type

    End If

Next i


Sender Property (MessageFilter Object)

The Sender property sets filtering on a message’s sender to an AddressEntry object. Read/write.

Syntax

Set objAddrEntry = objMessageFilter.Sender

objAddrEntry

Object. The AddressEntry object that represents the messaging user that sent the message.

objMessageFilter

Object. The MessageFilter object.

Data Type

Object

Remarks

The Sender property corresponds to the MAPI property PR_SENDER_ENTRYID.


Sent Property (MessageFilter Object)

The Sent property sets filtering on whether a message was sent through the MAPI system or not. Read/write.

Syntax

objMessageFilter.Sent

Data Type

Boolean

Remarks

A message’s Sent property is True if it was sent through the MAPI system and False if it was posted or saved.

In general, there are three different kinds of messages: messages that get sent, messages that get posted, and messages that get saved. Sent messages are characterized by traditional e-mail messages sent to a recipient or public folder. Posted messages are characterized by messages created in a public folder. Saved messages are characterized by messages that are created and saved without either sending or posting.

For all three kinds of messages, you can use the Unread property. For more information, see the Message object’s Sent property.


Size Property (MessageFilter Object)

The Size property sets filtering on a message’s approximate total size in bytes. Read/write.

Syntax

objMessageFilter.Size

Data Type

Long

Remarks

The Size property specifies that the message filter should pass only messages with approximate total size greater than the value of Size.

The Size property represents the sum of all the message’s MAPI properties, including the Subject, Text, Attachments, and Recipients.

The Size property corresponds to the MAPI property PR_MESSAGE_SIZE.


Subject Property (MessageFilter Object)

The Subject property sets filtering on a message’s subject. Read/write.

Syntax

objMessageFilter.Subject

Data Type

String

Remarks

The Subject property specifies that the message filter should pass only messages in which the subject contains the string in Subject as a substring.

The Subject property corresponds to the MAPI property PR_SUBJECT.

The Subject property is the default property of a MessageFilter object, meaning that MessageFilter is syntactically equivalent to MessageFilter.Subject in Visual Basic code.


Text Property (MessageFilter Object)

The Text property sets filtering on a message’s main content. Read/write.

Syntax

objMessageFilter.Text

Data Type

String

Remarks

The Text property specifies that the message filter should pass only messages in which the text contains the string in Text as a substring.

Note that the Text property is a plaintext representation of the main portion of the message’s content, and does not support formatted text.

The Text property corresponds to the MAPI property PR_BODY.


TimeFirst Property (MessageFilter Object)

The TimeFirst property sets filtering on whether a message was received at or since the specified date and time. Read/write.

Syntax

objMessageFilter.TimeFirst

Data Type

Variant (vbDate format)

Remarks

If the TimeFirst property is not set, the message filter passes all messages received at or before the date and time in the TimeLast property. If neither property is set, the filter passes messages regardless of their date and time of reception.

Note that the TimeFirst and TimeLast properties represent local time. However, when you access MAPI time properties through a Fields collection’s Item property, the time values represent Greenwich Mean Time (GMT).

The TimeFirst property corresponds to the MAPI Property PR_MESSAGE_DELIVERY_TIME.


TimeLast Property (MessageFilter Object)

The TimeLast property sets filtering on whether a message was received at or before the specified date and time. Read/write.

Syntax

objMessageFilter.TimeLast

Data Type

Variant (vbDate format)

Remarks

If the TimeLast property is not set, the message filter passes all messages received at or since the date and time in the TimeFirst property. If neither property is set, the filter passes messages regardless of their date and time of reception.

Note that the TimeFirst and TimeLast properties represent local time. However, when you access MAPI time properties through a Fields collection’s Item property, the time values represent Greenwich Mean Time (GMT).

The TimeLast property corresponds to the MAPI Property PR_MESSAGE_DELIVERY_TIME.


Type Property (MessageFilter Object)

The Type property sets filtering on a message’s MAPI message class. Read/write.

Syntax

objMessageFilter.Type

Data Type

String

Remarks

The Type property specifies that the message filter should pass only messages with a Type exactly matching a particular MAPI message class. By default, the OLE Messaging Library sets the Type value of new messages to the MAPI message class IPM.Note.

The Type property corresponds to the MAPI property PR_MESSAGE_CLASS.


Unread Property (MessageFilter Object)

The Unread property sets filtering on whether a message has been read or not. Read/write.

Syntax

objMessageFilter.Unread

Data Type

Boolean

Remarks

A message’s Unread property is True if it has not been read by the current user.

The Unread property corresponds to the MSGFLAG_READ flag not being set in the MAPI property PR_MESSAGE_FLAGS.


Messages Collection Object

The Messages collection object contains one or more Message objects.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.0
Parent objects:	Folder (Inbox or Outbox)
Child objects:	Message  MessageFilter
Default property:	Item
A Messages collection is considered a large collection, which means that the Count and Item properties have limited validity, and your best option is to use a Message object identifier value or the Get methods to access an individual Message object within the collection.

Properties

Property name	Available in version	Type	Access
Application	1.0	String	Read-only
Class	1.0	Long	Read-only
Count	1.1	Long	Read-only
Filter	1.1	MessageFilter object	Read/write
Item	1.1	Message object	Read-only
Parent	1.0	Inbox or Outbox folder object	Read-only
Session	1.0	Session object	Read-only
Methods

Method name	Available in version	Parameters
Add	1.0	(optional) subject as String,  (optional) text as String,  (optional) type as String,  (optional) importance as Long
Delete	1.0	(none)
GetFirst	1.0	(optional) filter as String
GetLast	1.0	(optional) filter as String
GetNext	1.0	(none)
GetPrevious	1.0	(none)
Sort	1.0	sortOrder as Long
Remarks

The collection does not maintain a count of the number of Message objects in the collection. Use the GetFirst, GetLast, GetNext, and GetPrevious methods to access the Message objects in the collection.

The order in which items are returned by GetFirst, GetNext, GetPrevious, and GetLast depends on whether the messages are sorted or not. The Message objects within a collection can be sorted by delivery time, either ascending or descending.

When the items are unsorted, these methods do not return the items in any specified order. The best programming approach to use with unsorted collections is to assume that you can access all items within the collection, but that the order of the objects is undefined.

See Also

Object Collections


Add Method (Messages Collection)

The Add method creates and returns a new Message object in the Messages collection.

Syntax

Set objMessage = objMsgColl.Add( [subject, text, type, importance] )

Parameters

objMessage

On successful return, represents the new Message object added to the collection.

objMsgColl

Required. The Messages collection object.

subject

Optional. String. The subject of the message. When this parameter is not supplied, the default value is an empty string.

text

Optional. String. The body text of the message. When this parameter is not supplied, the default value is an empty string.

type

Optional. String. The message class of the message, such as the default, IPM.Note.

importance

Optional. Long. The importance of the message. The following values are defined:

Constant	Value	Description
mapiLow	0	Low importance
mapiNormal	1	Normal importance (default)
mapiHigh	2	High importance
Remarks

The method parameters correspond to the Subject, Text, Type, and Importance properties of the Message object.

You should create new messages in the Outbox folder.

The user must have permission to Add or Delete a Message object. Most users have this permission in all .

The new Message object is saved in the MAPI system when you call its Update method.

Example

This code fragment adds a new message to a folder:

' from the sample function Util_ReplyToConversation

Set objNewMsg = objSession.Outbox.Messages.Add

' verify objNewMsg created successfully...then supply properties

With objNewMsg

    .Text = "How about a slightly used Gemini?" ' new text

    .Subject = objOriginalMsg.Subject ' copy original properties

    .ConversationTopic = objOriginalMsg.ConversationTopic

    ' append time stamp; compatible with Microsoft Exchange client

    Set objOneRecip = .Recipients.Add( _

                      Name:=objOriginalMsg.Recipients.Item(1).Name, _

                      Type:=mapiTo)

    .Recipients.Resolve

    .Update

    .Send showDialog:=False

End With


Count Property (Messages Collection)

The Count property returns the number of Message objects in the collection, or a very large number if the exact count is not available. Read-only.

Syntax

objMsgColl.Count

Data Type

Long

Remarks

The Count property is useful for determining whether a Messages collection is empty or not.

A large collection cannot always maintain an accurate count of its members, and the Count property cannot be used as the collection’s size when it has a very large value such as mapiMaxCount. Programmers needing to access individual objects in a large collection are strongly advised to use the Visual Basic For Each statement or the Get methods.

The recommended procedures for traversing a large collection are, in decreasing order of preference:

1.	Global selection, such as the Visual Basic For Each statement

2.	The Get methods, particularly GetFirst and GetNext

3.	An indexed loop, such as the Visual Basic For ... Next construction

If the message store provider cannot supply the precise number of Message objects, the OLE Messaging Library returns a very large number for the Count property. On 32-bit platforms, this value is mapiMaxCount, which equals 2^31 - 1, or 2147483647. On other platforms, mapiMaxCount is not defined, and the OLE Messaging Library returns -1. A program on such a platform must be careful that -1 does not prematurely terminate any iteration based on the Count property.

Programmers using an indexed loop terminating on the Count property must also check each returned object for a value of Nothing. The loop must proceed forward from the beginning of the collection, and the index must have initial and increment values of 1. Results are undefined for any other procedure.

The use of the Item property in conjunction with the Count property in a large collection can be seen in the following example.

Example

This code fragment searches for a Mesage object with subject “Bonus”:

Dim i As Integer ' loop index / object counter

Dim collMessages as Object ' Messages collection; assume already given

If collMessages Is Nothing Then

    ' MsgBox "Messages collection object is invalid"

    ' Exit

End If

' see if collection is empty

If 0 = collMessages.Count Then

    ' MsgBox "No messages in collection"

    ' Exit

End If

' look for message about “Bonus” in collection

For i = 1 To collMessages.Count Step 1

    If collMessages.Item(i) Is Nothing Then

    ' MsgBox "No such message found in collection"

    ' Exit ' no more messages in collection

    End If

    If collMessages.Item(i).Subject = “Bonus” Then

    ' MsgBox "Desired message is at index " & i

    ' Exit

    End If

Next i


Delete Method (Messages Collection)

The Delete method deletes all the messages in the Messages collection.

Syntax

objMsgColl.Delete()

Parameters

objMsgColl

Required. The Messages collection object.

Remarks

The Delete method moves the deleted messages to the Deleted Items folder, if the user has enabled this option. If the option is not enabled, or if the messages are already in the Deleted Items folder, the Delete method permanently deletes them, and they cannot be recovered.

Be cautious using the Delete method with a collection, since it deletes all the collection’s member objects. To delete only one Message object, use the Delete method specific to that object.

The Delete method on a large collection takes effect immediately and is permanent. Any object once deleted cannot be recovered.

For example, this code fragment deletes all of the messages in a folder:

objFolder.Messages.Delete

See Also

Add Method (Messages Collection)


Filter Property (Messages Collection)

The Filter property returns a MessageFilter object for the Messages collection. Read/write.

Syntax

objMsgColl.Filter

Data Type

Object

Remarks

A MessageFilter object with no criteria is created by default for every Messages collection.


GetFirst Method (Messages Collection)

The GetFirst method returns the first object in the collection. Returns Nothing if no first object exists.

Syntax

Set objMessage = objMsgColl.GetFirst( [filter] )

Parameters

objMessage

On successful return, represents the first Message object in the collection.

objMsgColl

Required. The Messages collection object.

filter

Optional. String. Specifies the message class of the object, such as the default value, IPM.Note. Corresponds to the Type property of the Message object.

Remarks

The Get methods are similar to the Find and Move methods that are used with Microsoft Access databases. The Get methods take a different name from these methods because they use a different syntax.

See Also

Message Object


GetLast Method (Messages Collection)

The GetLast method returns the last object in the collection. Returns Nothing if no last object exists.

Syntax

Set objMessage = objMsgColl.GetLast( [filter] )

Parameters

objMessage

On successful return, represents the last Message object in the collection.

objMsgColl

Required. The Messages collection object.

filter

Optional. String. Specifies the message class of the object, such as the default value, IPM.Note. Corresponds to the Type property of the Message object.

Remarks

The Get methods are similar to the Find and Move methods that are used with Microsoft Access databases. The Get methods take a different name from these methods because they use a different syntax.

See Also

Update Method (Message Object)


GetNext Method (Messages Collection)

The GetNext method returns the next object in the Messages collection. Returns Nothing if no next object exists.

Syntax

Set objMessage = objMsgColl.GetNext( )

Parameters

objMessage

On successful return, represents the next Message object in the collection.

objMsgColl

Required. The Messages collection object.

Remarks

The Get methods are similar to the Find and Move methods that are used with Microsoft Access databases. The Get methods take a different name from these methods because they use a different syntax.

See Also

Update Method (Message Object)


GetPrevious Method (Messages Collection)

The GetPrevious method returns the previous object in the collection. Returns Nothing if no previous object exists.

Syntax

Set objMessage = objMsgColl.GetPrevious( )

Parameters

objMessage

On successful return, represents the previous Message object in the collection.

objMsgColl

Required. The Messages collection object.

Remarks

The Get methods are similar to the Find and Move methods that are used with Microsoft Access databases. The Get methods take a different name from these methods because they use a different syntax.

See Also

Update Method (Message Object)


Item Property (Messages Collection)

The Item property returns a single Message object from a Messages collection. Read-only.

Syntax

objMsgColl.Item(index)

objMsgColl.Item(prefix)

index

A long integer ranging from 1 to the size of the Messages collection.

prefix

A string representing a prefix substring of a Message object’s Subject property.

Data Type

Object

Remarks

The Item property is useful for satisfying syntax requirements when obtaining a member of a Messages collection.

A large collection cannot support true integer indexing, and the Item(index) syntax cannot be used for arbitrary selection of members of the collection. Programmers needing to access individual objects in a large collection are strongly advised to use the Visual Basic For Each statement or the Get methods, particularly GetFirst and GetNext

The Item(index) syntax is provided solely as a placeholder in an indexed loop, such as the For ... Next construction in Visual Basic. Such a loop must proceed forward from the beginning of the collection, and the index must have initial and increment values of 1. Results are undefined for any other procedure.

For more information on using the Count and Item properties in a large collection, see the example in the Count property.

The Item(prefix) syntax returns the first Message object whose Subject property begins with the string specified by prefix.

The Item property is the default property of a Messages collection, meaning that Messages(index) is syntactically equivalent to Messages.Item(index) in Visual Basic code.


Sort Method (Messages Collection)

The Sort method sorts the messages in the collection according to the specified sort order.

Syntax

objMsgColl.Sort(sortOrder)

Parameters

objMsgColl

Required. The Messages collection object.

sortOrder

Required. Long. The specified sort order, one of the following values:

Value	Numeric value	Description
mapiNone	0	No sort
mapiAscending	1	Ascending sort
mapiDescending	2	Descending sort
See Also

Update Method (Message Object)


Recipient Object

The Recipient object represents a recipient of a message.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.0
Parent objects:	Recipients collection
Child objects:	AddressEntry
Default property:	Name
Properties

Property name	Available in version	Type	Access
Address	1.0	String	Read/write
AddressEntry	1.0	AddressEntry object	Read/write
Application	1.0	String	Read-only
Class	1.0	Long	Read-only
DisplayType	1.0	Long	Read-only
Index	1.0	Long	Read-only
Name	1.0	String	Read/write
Parent	1.0	Recipients collection object	Read-only
Session	1.0	Session object	Read-only
Type	1.0	Long	Read/write
Methods

Method name	Available in version	Parameters
Delete	1.0	(none)
IsSameAs	1.1	object as Object
Resolve	1.0	(optional) showDialog as Boolean


Address Property (Recipient Object)

The Address property specifies the full address for this recipient. Read/write.

Syntax

objRecipient.Address

Data Type

String

Remarks

Sets the value of the Recipient object’s Address property to specify a custom address. The Recipient Address uses the following syntax:

TypeValue:AddressValue

where TypeValue and AddressValue correspond to the values of the AddressEntry object’s Type and Address properties.

The Recipient object’s Address property represents the full address, the complete messaging address used by the MAPI system.

The OLE Messaging Library sets the value of the Recipient object’s Address property for you when you supply the Name property and call its Resolve method.

The Address property corresponds to the MAPI properties PR_ADDRTYPE and PR_EMAIL_ADDRESS.

Example

' from the sample function Util_CompareAddressParts

    strMsg = "Recipient full address = " & objOneRecip.Address

    strMsg = strMsg & "; AddressEntry type = " & objAddrEntry.Type

    strMsg = strMsg & "; AddressEntry address = " & objAddrEntry.Address

    MsgBox strMsg    ' compare address components


AddressEntry Property (Recipient Object)

The AddressEntry property specifies the AddressEntry object for this recipient. Read/write.

Syntax

objRecipient.AddressEntry

Data Type

Object (AddressEntry object)

Remarks

The AddressEntry property indicates the AddressEntry object for this recipient. For a complete description of the relationship between the AddressEntry object and the Recipient object, see Using Addresses.

Accessing the AddressEntry property forces resolution of an unresolved recipient name. If the name cannot be resolved, the OLE Messaging Library reports an error. For example, when the recipient contains an empty string, the resolve operation returns MAPI_E_AMBIGUOUS_RECIP.

Example

This example compares the Address property of the Recipient object with the Address and Type properties of its child AddressEntry object, accessible through its AddressEntry property, to demonstrate the relationships between these properties.

' from the sample function Session_AddressEntry

    If objOneRecip Is Nothing Then

        MsgBox "must select a recipient"

        Exit Function

    End If

    Set objAddrEntry = objOneRecip.AddressEntry

    If objAddrEntry Is Nothing Then

        MsgBox "no valid AddressEntry for this recipient"

        Exit Function

    End If

' from the sample function Util_CompareAddressParts

    strMsg = "Recipient full address = " & objOneRecip.Address

    strMsg = strMsg & "; AddressEntry type = " & objAddrEntry.Type

    strMsg = strMsg & "; AddressEntry address = " & objAddrEntry.Address

    MsgBox strMsg    ' compare address components

    strMsg = "Recipient name = " & objOneRecip.Name

    strMsg = strMsg & "; AddressEntry name = " & objAddrEntry.Name

    MsgBox strMsg    ' compare display names (should be same)

See Also

AddressEntry Object


Delete Method (Recipient Object)

The Delete method deletes the Recipient object.

Syntax

objRecipient.Delete()

Parameters

objRecipient

Required. The Recipient object.

Remarks

The object is set to Nothing and it is removed from memory. The change is not permanent until you use the Update, Send, or Delete method on the parent Message object.

See Also

Send Method (Message Object)

Update Method (Message Object)


DisplayType Property (Recipient Object)

The DisplayType property identifies the recipient type. This property enables special processing based on the type, such as displaying an icon associated with that type. Read-only.

Syntax

objRecipient.DisplayType

Parameters

objRecipient

Required. The Recipient object.

Data Type

Long

Remarks

You can use the display type to sort or to filter recipients.

The following values are defined:

DisplayType value	Description
mapiUser	Local user
mapiDistList	Distribution list
mapiForum	Public folder
mapiAgent	Agent
mapiOrganization	Organization
mapiPrivateDistList	Private distribution list
mapiRemoteUser	Remote user
See Also

Item Property (Recipients Collection)


Index Property (Recipient Object)

The Index property returns the index number of this Recipient object within the Recipients collection. Read-only.

Syntax

objRecipient.Index

Data Type

Long

Remarks

The index number indicates an index within the array of Recipients collection object.

An index value should not be considered to be a static value that remains constant for the duration of a session. The index can change whenever an update occurs to a parent object, such as the message or folder.

Example

' from the sample function Recipients_NextItem

'   after some similar validation...

    If iRecipCollIndex >= objRecipColl.Count Then

        iRecipCollIndex = objRecipColl.Count

        MsgBox "Already at end of recipient list"

        Exit Function

    End If

    ' index is < count; can be incremented by 1

    iRecipCollIndex = iRecipCollIndex + 1

    Set objOneRecip = objRecipColl.Item(iRecipCollIndex)

' from the sample function Recipient_Index

    If objOneRecip Is Nothing Then

        MsgBox "must first select a recipient"

        Exit Function

    End If

    MsgBox "Recipient index = " & objOneRecip.Index

See Also

Count Property (Recipients Collection), Item Property (Recipients Collection)


IsSameAs Method (Recipient Object)

The IsSameAs method returns True if this Recipient object is the same as the Recipient object being compared against.

Syntax

objRecipient.IsSameAs(objRecip2)

Parameters

objRecipient

Required. This Recipient object.

objRecip2

Required. The Recipient object being compared against.

Remarks

Two Recipient objects are considered to be the same if and only if they are instantiations of the same physical (persistent) object. Two objects with the same value are still considered different if they do not instantiate the same physical object, for example if one is a copy of the other. In such a case IsSameAs returns False.

The IsSameAs method ultimately calls one of the MAPI CompareEntryIDs methods to determine if two objects are the same. A generic comparison of any two object identifiers is also available with the Session object’s CompareIDs method.


Name Property (Recipient Object)

The Name property specifies the name of this Recipient object. Read/write.

Syntax

objRecipient.Name

Data Type

String

Remarks

The Name property corresponds to the MAPI property PR_DISPLAY_NAME.

The Name property is the default property of a Recipient object, meaning that Recipient is syntactically equivalent to Recipient.Name in Visual Basic code.

Example

' from the sample function Util_CompareFullAddressParts()

Dim strMsg As String

    ' validate objects... then display

    strMsg = "Recipient full address = " & objOneRecip.Address

    strMsg = strMsg & "; AddressEntry type = " & objAddrEntry.Type

    strMsg = strMsg & "; AddressEntry address = " & objAddrEntry.Address

    MsgBox strMsg    ' compare address parts

    strMsg = "Recipient name = " & objOneRecip.Name

    strMsg = strMsg & "; AddressEntry name = " & objAddrEntry.Name

    MsgBox strMsg    ' compare display names (should be same)


Resolve Method (Recipient Object)

The Resolve method resolves address information. When the Recipient object’s Name property is supplied, looks up the corresponding address from the address book. When the Recipient object’s Address property is supplied, resolves as a custom address.

Syntax

objRecipient.Resolve( [ showDialog ] )

Parameters

objRecipient

Required. The Recipient object.

showDialog

Optional. Boolean. If TRUE (the default value), displays a dialog box to prompt the user to resolve ambiguous names.

Remarks

The Resolve method operates when the AddressEntry property is set to Nothing. Its operation depends on whether you supply the Recipient Name or Address property.

When you supply the Name property, Resolve looks up the Recipient object’s Name property in the address book. When a recipient is resolved, the recipient object’s Address property contains the full address and its AddressEntry property contains a reference to an AddressEntry object that represents a copy of information in the address book.

Note that the Resolve method does not validate the Recipient object’s Type property.

When you specify a custom address by supplying the Recipient object’s Address property, the Resolve method does not attempt to compare the address against the address book.

To avoid delivery errors, clients should always resolve recipients before submitting a message to the MAPI system. Resolving the recipient name means either finding a matching address in an address list or having the user select an address from a dialog box.

The Resolve method uses the address list specified in the profile, such as the global address book or the personal address book.

The following methods can also invoke MAPI dialog boxes: Delete and Details methods (AddressEntry object), Options and Send methods (Message object), Resolve method (Recipient object and Recipients collection), AddressBook and Logon methods (Session object).

See Also

Resolve Method (Recipients Collection)

Resolved Property (Recipients Collection)


Type Property (Recipient Object)

The Type property specifies the type of the Recipient object; an integer value that indicates either To, Cc, or Bcc. Read/write.

Syntax

objRecipient.Type

Data Type

Long

Remarks

The Type property applies to all Recipient objects in the Recipients collection. The property has the following defined values:

Recipient type	Value	Description
mapiTo	1	The recipient is on the To line.
mapiCc	2	The recipient is on the Cc line.
mapiBcc	3	The recipient is on the Bcc line.
The Type property corresponds to the MAPI property PR_RECIPIENT_TYPE.

See Also

Address Property (Recipient Object)

Resolve Method (Recipient Object)


Recipients Collection Object

The Recipients collection object contains one or more Recipient objects and specifies the recipients of a message.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.0
Parent objects:	Message
Child objects:	Recipient
Default property:	Item
A Recipients collection is considered a small collection, which means that it supports count and index values that let you access an individual Recipient object through the Item property. The Recipients collection supports the Visual Basic For Each statement.

Properties

Property name	Available in version	Type	Access
Application	1.0	String	Read-only
Class	1.0	Long	Read-only
Count	1.0	Long	Read-only
Item	1.0	Recipient object	Read-only
Parent	1.0	Message object	Read-only
Resolved	1.0	Boolean	Read-only
Session	1.0	Session object	Read-only
Methods

Method name	Available in version	Parameters
Add	1.0	(optional) name as String,  (optional) address as String,  (optional) type as Long,  (optional) entryID as String
Delete	1.0	(none)
Resolve	1.0	(optional) showDialog as Boolean
See Also

Object Collections


Add Method (Recipients Collection)

The Add method creates and returns a new Recipient object in the Recipients collection.

Syntax

Set objRecipient = objRecipColl.Add( [name, address, type] | [entryID] )

Parameters

objRecipient

On successful return, represents the new Recipient object added to the collection.

objRecipColl

Required. The Recipients collection object.

name

Optional. String. The display name of the recipient. When this parameter is not present, the property of the new object is set to an empty string.

address

Optional. String. The address of the recipient. When this parameter is not present, the property of the new object is set to an empty string.

type

Optional. Long. The type of recipient; the initial value for the Recipient object’s Type property. The following values are valid:

Recipient type	Value	Description
mapiTo	1	The recipient is on the To line.
mapiCc	2	The recipient is on the Cc line.
mapiBcc	3	The recipient is on the Bcc line.
When this parameter is not present, the object uses the default value mapiTo.

entryID

Optional. String. The identifier of a valid AddressEntry object for this recipient. No default value is supplied for the entryID parameter. When present, the other parameters are not used. When not present, the method uses the name, address, and type parameters to determine the recipient.

Remarks

The name, address, and type parameters correspond to the Recipient object’s Name, Address, and Type properties, respectively. The entryID parameter corresponds to the child AddressEntry object’s ID property. When the entryID parameter is present, the other parameters are not used.

When no parameters are present, an empty Recipient object is created.

You can access the child AddressEntry object through the Recipient object’s AddressEntry property.

Call the Resolve method after you add a recipient.

The Index property of the new Recipient object equals the new Count property of the Recipients collection.

The recipient is saved in the MAPI system when you Update or Send the parent Message object.

Example

This example adds three recipients to a message. The address for the first recipient is resolved using the display name. The second recipient is a custom address, so the resolve operation does not modify it. The third recipient is taken from an existing valid AddressEntry object. The Resolve operation does not affect this recipient.

' from the sample function "Using Addresses"

    ' add 3 recipient objects to a valid message object

    ' 1. look up entry in address book

    Set objOneRecip = objNewMessage.Recipients.Add( _

        Name:=strName, _

        Type:=mapiTo)

    ' error handling...verify objOneRecip

    objOneRecip.Resolve

    ' 2. add a custom recipient

    Set objOneRecip = objNewMessage.Recipients.Add( _

        Address:="SMTP:davidhef@microsoft.com", _

        Type:=mapiTo)

    If objOneRecip Is Nothing Then

        MsgBox "Unable to add recipient using custom addressing"

        Exit Function

    End If

    objOneRecip.Resolve

    ' 3. add a valid address entry object, such as Message.Sender

    ' assume valid address entry ID, name from an existing message

    Set objOneRecip = objNewMessage.Recipients.Add( _

        entryID:=strAddrEntryID, _

        Name:=strName, _

        Type:=mapiTo)

    If objOneRecip Is Nothing Then

        MsgBox "Unable to add recipient using existing AddressEntry ID"

        Exit Function

    End If

    objNewMessage.Text = "expect 3 different recipients"

    MsgBox ("count = " & objNewMessage.Recipients.Count)


Count Property (Recipients Collection)

The Count property returns the number of Recipient objects in the collection. Read-only.

Syntax

objRecipColl.Count

Data Type

Long

Example

This example uses the Count property as a loop counter to copy all recipients from one Recipients collection to another.

' from the sample function Util_CopyMessage

' Copy all Recipient objects from one collection to another

'  ... verify valid message object objOneMsg

   For i = 1 To objOneMsg.Recipients.Count Step 1

        strRecipName = objOneMsg.Recipients.Item(i).Name

        If strRecipName <> "" Then

            Set objOneRecip = objCopyMsg.Recipients.Add

            If objOneRecip Is Nothing Then

                MsgBox "unable to create recipient in message copy"

                Exit Function

            End If

            objOneRecip.Name = strRecipName

        End If

    Next i

See Also

Item Property (Recipients Collection)


Delete Method (Recipients Collection)

The Delete method deletes all the recipients in the Recipients collection.

Syntax

objRecipColl.Delete()

Parameters

objRecipColl

Required. The Recipients collection object.

Remarks

Be cautious using the Delete method with a collection, since it deletes all the collection’s member objects. To delete only one Recipient object, use the Delete method specific to that object.

The effect of the Delete method is not permanent until you use the Update, Send, or Delete method on the parent Message object containing the Recipients collection.


Item Property (Recipients Collection)

The Item property returns a single Recipient object from the collection. Read-only.

Syntax

objRecipColl.Item(index)

objRecipCol

Required. Specifies the Recipients collection object.

index

A long integer that ranges from 1 to objRecipColl.Count, or a string that specifies the name of the object.

Data Type

Object

Remarks

The Item property works like an accessor property for small collections.

The Item property is the default property of a Recipients collection, meaning that Recipients(index) is syntactically equivalent to Recipients.Item(index) in Visual Basic code.

Example

'  list all recipient names in the collection

    strRecips = ""  ' initialize string

    Set objRecipsColl = objOriginalMsg.Recipients

    Count = objRecipsColl.Count

    For i = 1 To Count Step 1

        Set objOneRecip = objRecipsColl.Item(i)

        strRecips = strRecips & objOneRecip.Name & "; "

    Next i

    MsgBox "Message recipients: " & strRecips

See Also

Count Property (Recipients Collection)


Resolve Method (Recipients Collection)

The Resolve method searches the Recipients collection to resolve names.

Syntax

objRecipColl.Resolve( [ showDialog ] )

Parameters

objRecipColl

Required. The Recipients collection object.

showDialog

Optional. Boolean. If True (the default value), displays a dialog box to prompt the user to resolve ambiguous names.

Remarks

Calling the Recipients collection’s Resolve method is similar to calling the Resolve method for each Recipient object in the collection; any ambiguous addresses are resolved as unambiguous addresses. However, calling the Resolve method on the Recipients collection also forces an update to the Count and Item properties and to all Recipient objects in the collection. Any Recipient variable previously set to an object in the collection is invalidated by the Resolve call and should be retrieved again from the collection.

The Resolve method of the Recipient object itself does not invalidate the object. For more information about the individual Resolve operation, see the reference documentation for the Recipient object’s Resolve method.

The following methods can also invoke MAPI dialog boxes: Delete and Details methods (AddressEntry object), Options and Send methods (Message object), Resolve method (Recipient object), AddressBook and Logon methods (Session object).

Example

' from the sample function Util_NewConversation

'   create a valid new message object in the Outbox

    With objNewMsg

        .Subject = "used space vehicle wanted"

        ' ... set other properties here...

        Set objOneRecip = .Recipients.Add(Name:="Car Ads", Type:=mapiTo)

        If objOneRecip Is Nothing Then

            MsgBox "Unable to create the public folder recipient"

            Exit Function

        End If

        .Recipients.Resolve

    End With

See Also

Resolve Method (Recipient Object)

Resolved Property (Recipients Collection)


Resolved Property (Recipients Collection)

The Resolved property contains True if all of the recipients in the collection are resolved. Read-only.

Syntax

objRecipColl.Resolved

Data Type

Boolean

Remarks

All Recipient objects in the collection are considered resolved when all Recipient objects have a valid AddressEntry object in the AddressEntry property.

You should resolve all addresses.  Whenever you supply a display name to obtain an address from the address book or supply a custom address, you should call the Resolve method to ensure that the AddressEntry property is valid.

When the Recipients collection’s Resolved property is not TRUE, use either the collection’s Resolve method or the Resolve method for each Recipient object in the collection.

When you use existing valid AddressEntry objects, you do not need to explicitly call the Recipient object’s Resolve method.

See Also

Resolve Method (Recipient Object)


Session Object

The Session object contains session-wide settings and options. It also contains properties that return top-level objects, such as CurrentUser.

Quick Info

Specified in header file:	MDISP.ODL
First available in version:	OLE Messaging Library 1.0
Parent objects:	(none)
Child objects:	AddressLists collection  Folder (Inbox or Outbox)  InfoStores collection
Default property:	Name
Properties

Property name	Available in version	Type	Access
AddressLists	1.1	AddressList object or AddressLists collection object	Read-only
Application	1.0	String	Read-only
Class	1.0	Long	Read-only
CurrentUser	1.0	AddressEntry object	Read-only
Inbox	1.0	Folder object	Read-only
InfoStores	1.0	InfoStores object	Read-only
MAPIOBJECT	1.0	Object	Read/write (Note: Not available to Visual Basic applications.)
Name	1.0	String	Read-only
OperatingSystem	1.0	String	Read-only
Outbox	1.0	Folder object	Read-only
Parent	1.0	Object; set to Nothing	Read-only
Session	1.0	Object; set to Nothing	Read-only
Version	1.0	String	Read-only
Methods

Method name	Available in version	Parameters
AddressBook	1.0	(optional) recipients as Object,  (optional) title as String,  (optional) oneAddress as Boolean,  (optional) forceResolution as Boolean,  (optional) recipLists as Long,  (optional) toLabel as String,  (optional) ccLabel as String,  (optional) bccLabel as String,  (optional) parentWindow as Long
CompareIDs	1.1	ID1 as Object,  ID2 as Object
DeliverNow	1.1	(none)
GetAddressEntry	1.0	entryID as String
GetFolder	1.0	folderID as String,  storeID as String
GetInfoStore	1.0	storeID as String
GetMessage	1.0	messageID as String,  storeID as String
Logoff	1.0	(none)
Logon	1.0	(optional) profileName as String,  (optional) profilePassword as String,  (optional) showDialog as Boolean,  (optional) newSession as Boolean,  (optional) parentWindow as Long
Remarks

A Session object is considered a top-level object, meaning it can be created directly from a Visual Basic program. The following sample code fragment creates a Session object through early binding:

Dim objSession as MAPI.Session

objSession.Logon

The following sample code fragment creates a Session object through late binding:

Dim objSession As Object

Set objSession = CreateObject ( “MAPI.Session” )

objSession.Logon

After you create a new Session object, use the Logon method to initiate a session with MAPI.


AddressBook Method (Session Object)

The AddressBook method displays the MAPI dialog box that allows the user to select entries from the address book. The selections are returned in a Recipients collection object.

Syntax

Set objRecipients = objSession.AddressBook( [ recipients, title, oneAddress, forceResolution, recipLists, toLabel, ccLabel, bccLabel, parentWindow ] )

Parameters

objRecipients

On successful return, the Recipients collection object. When the user does not select any names from the dialog box, AddressBook returns Nothing.

objSession

Required. The Session object.

recipients

Optional. Object. A Recipients collection object that provides the initial value for the recipient list boxes in the address book. (Note: This initial Recipient collection is ignored in the OLE Messaging Library.)

title

Optional. String. The title or caption of the address book dialog box. The default value is an empty string.

oneAddress

Optional. Boolean. Allows the user to enter or select only one address. The default value is FALSE.

forceResolution

Optional. Boolean. If TRUE, attempts to resolve all names before closing the address book. Prompts the user to resolve any ambiguous names. The default value is TRUE.

recipLists

Optional. Long. The number of recipient list boxes to display in the address book dialog box:

recipLists	Action
0	Displays no list boxes. The user can interact with the address book dialog box but no recipients are returned by this method.
1	Displays one list box (default) for mapiTo recipients.
2	Displays two list boxes; mapiTo and mapiCc recipients.
3	Displays three list boxes; mapiTo, mapiCc, and mapiBcc recipients.
toLabel

Optional. String. The caption for the button associated with the first list box. Ignored if recipLists is less than 1. If omitted, the default value “To:” is displayed.

ccLabel

Optional. String. The caption for the button associated with the second list box. Ignored if recipLists is less than 2. If omitted, the default value “CC:” is displayed.

bccLabel

Optional. String. The caption for the button associated with the third list box. Ignored if recipLists is less than 3. If omitted, the default value “BCC:” is displayed.

parentWindow

Optional. Long. The parent window handle for the address book dialog box. A value of 0 (the default) specifies that any dialog box displayed is application modal.

Remarks

The AddressBook method returns Nothing if the user cancels the dialog box.

To provide an access key for the list boxes, include an ampersand (&) character in the string for the label argument. For example, if toLabel is “&Attendees:”, users can press ALT+A to move the focus to the first recipient list box.

When you use the AddressBook method to let the user select recipients for a new message, you must use two different Recipients collections. This is required because the Recipients property of the Message object is read-only. Use the following procedure:

1.	Call Session.AddressBook, which returns a new Recipients collection.

2.	Call Messages.Add to create a new message.

3.	Loop through the Recipients collection returned by Session.AddressBook, adding each recipient to the message’s Recipients collection by calling the message’s Recipients.Add method.

Note that you must update both the Recipient and the AddressEntry properties of the destination Recipient object, as demonstrated in the following example:

Dim objNewRecip(MAX_RECIPS) as Object   ' array of new recipients

'...

    Set objNewMessage = objSession.Outbox.Messages.Add

    Set objRecipColl = objSession.AddressBook( _

           Title:="Select Recipients", _

           recipLists:=3) 'use default labels

    ' now add to the new message

    Count = objRecipColl.Count   ' error checking omitted...

    With objNewMessage.Recipients

        For i = 1 To Count Step 1

            Set objRecip = objRecipColl.Item(i)

            Set objNewRecip(i) = .Add( _

                entryID:=objRecip.AddressEntry.ID, _

                type:=objRecip.type)

            objNewRecip(i).Name = objNewRecip(i).AddressEntry.Name

            objNewRecip(i).address = objNewRecip(i).AddressEntry.type _

                & ":" & objNewRecip(i).AddressEntry.address

            objNewRecip(i).Resolve

        Next i

    End With

    objNewMessage.Update  'save it

The following methods can also invoke MAPI dialog boxes: Delete and Details methods (AddressEntry object), Options and Send methods (Message object), Resolve method (Recipient object and Recipients collection), Logon method (Session object).

Note  The initial Recipients collection, as specified in the recipients parameter, is not used in the OLE Messaging Library.

Example

The following example displays an address book dialog box labeled “Select Attendees” with three recipient lists:

    If objSession Is Nothing Then

        MsgBox "must first create MAPI session and logon"

        Exit Function

    End If

    Set objRecipColl = objSession.AddressBook( _

        Title:="Select Attendees", _

        forceResolution:=True, _

        recipLists:=3, _

        toLabel:="&Very Important People")  ' on button

        ccLabel:="&Carbon Recipients")

        bccLabel:="&Secret Recipients")

    ' Note: initial value not used in version 1.0

    ' parameter not used in call: Recipients:=objInitRecipColl

    MsgBox "Name of first recipient = " & objRecipColl.Item(1).Name

    Exit Function

See Also

AddressEntry Object, Recipients Collection


AddressLists Property (Session Object)

The AddressLists property returns a single AddressList object or an AddressLists collection object. Read-only.

Syntax

Set objAddrListsColl = objSession.AddressLists

Set objOneAddrList = objSession.AddressLists(index)

objAddrListsColl

Object. An AddressLists collection object.

objSession

Object. The Session object.

objOneAddrList

Object. A single AddressList object.

index

Long. Specifies the number of the address list within the AddressLists collection. Ranges from 1 to the value specified by the AddressLists collection’s Count property.

Data Type

Object

Remarks

The AddressLists collection represents the root of the MAPI address book hierarchy for the current session. A particular AddressList object represents one of the available address books. The type of access you obtain depends on the access granted to you by each individual address book provider.


CompareIDs Method (Session Object)

The CompareIDs method determines whether two OLE Messaging Library objects are the same object.

Syntax

objSession.CompareIDs(ID1, ID2)

Parameters

objSession

Required. The Session object.

ID1

Required. The identifier of the first object to be compared.

ID2

Required. The identifier of the second object to be compared.

Remarks

The CompareIDs method compares the identifiers of two arbitrary OLE Messaging Library objects and returns True if they are the same object. Two objects are considered to be the same if and only if they are instantiations of the same physical (persistent) object. Two objects with the same value are still considered different if they do not instantiate the same physical object, for example if one is a copy of the other. In such a case CompareIDs returns False.

The CompareIDs method ultimately calls one of the MAPI CompareEntryIDs methods to determine if two objects are the same. Several OLE Messaging Library objects also provide the IsSameAs method for a comparison of two identifiers of that particular object type.


CurrentUser Property (Session Object)

The CurrentUser property returns the active user as an AddressEntry object. Read-only.

Syntax

objSession.CurrentUser

Data Type

Object

Remarks

The CurrentUser property returns Nothing when no user is logged on.

Example

The example logs on if necessary, then creates strings containing information about the current user:

    If objSession Is Nothing Then

        MsgBox ("Must log on first")

        Exit Function

    End If

    Set objAddrEntry = objSession.CurrentUser

    If objAddrEntry Is Nothing Then

        MsgBox "Could not set the address entry object"

        Exit Function

    Else

        MsgBox "full address = " & objAddrEntry.Type & ":" _

                 & objAddrEntry.Address

    End If

See Also

AddressEntry Object


DeliverNow Method (Session Object)

The DeliverNow method requests immediate delivery of all undelivered messages submitted in the current session.

Syntax

objSession.DeliverNow()

Parameters

objSession

Required. The Session object.

Remarks

The DeliverNow method ultimately calls the MAPI spooler’s IMAPIStatus::FlushQueues method to request that all messages in all inbound and outbound queues be received or delivered immediately. FlushQueues is invoked synchronously, and performance degradation is possible during the processing of this request.


GetAddressEntry Method (Session Object)

The GetAddressEntry method returns an AddressEntry object.

Syntax

Set objAddressEntry = objSession.GetAddressEntry(entryID)

Parameters

objAddressEntry

On successful return, represents the AddressEntry object specified by entryID.

objSession

Required. The Session object.

entryID

Required. String that specifies the unique identifier of the address entry.

Example

The following example displays the name of a user from a MAPI address list:

' from the function Session_GetAddressEntry

    If objSession Is Nothing Then

        MsgBox "No active session, must log on"

        Exit Function

    End If

    If "" = strAddressEntryID Then

        MsgBox ("Must first set string variable; see AddressEntry->ID")

        Exit Function

    End If

    Set objAddrEntry = objSession.GetAddressEntry(strAddressEntryID)

    MsgBox "full address = " & objAddrEntry.Type & ":" _

            & objAddrEntry.Address

See Also

Using Addresses

AddressEntry Object

GetFolder Method (Session Object)

GetMessage Method (Session Object)


GetFolder Method (Session Object)

The GetFolder method returns a Folder object from a MAPI message store.

Syntax

Set objFolder = objSession.GetFolder(folderID [, storeID] )

Parameters

objFolder

On successful return, contains the Folder object with the specified identifier. When the folder does not exist, GetFolder returns Nothing.

objSession

Required. The Session object.

folderID

Required. String that specifies the unique identifier of the folder. When you provide an empty string, some providers return the root folder. See the remarks for more information.

storeID

Optional. String that specifies the unique identifier of the message store. The default value is an empty string, which corresponds to the default message store.

Remarks

The GetFolder method allows you to obtain any folder for which you know the identifier.

For some message stores, you can also obtain the root folder by supplying an empty string as the value for folderID. When the message store does not support returning the root folder, the call returns the error value MAPI_E_NOT_FOUND.

The root folder is the parent of the folder that represents the IPM subtree. The IPM subtree is the hierarchy of folders for all messages whose message class starts with IPM, such as IPM.Note.

Note that the root folder differs from the IPM root folder. You can obtain the IPM root folder with the InfoStores object’s RootFolder property, or when you use the Parent property to trace up through the hierarchy of folders. You can only obtain the root folder by calling GetFolder with the empty string supplied for the folderID parameter.

Example

The following example uses the GetFolder method to obtain a specific folder from a MAPI message store:

' from the function Session_GetFolder

' requires a global variable that contains the folder ID

' uses a global variable that contains the message store ID if present

    If strFolderID = "" Then

        MsgBox ("Must first set folder ID variable; see Folder->ID")

        Exit Function

    End If

    If strFolderStoreID = "" Then ' if it's not there, don't use it

        Set objFolder = objSession.GetFolder(strFolderID)

    Else

        Set objFolder = objSession.GetFolder(folderID:=strFolderID, _

                                    storeID:=strFolderStoreID)

    End If

    If objFolder Is Nothing Then

        Set objMessages = Nothing

        MsgBox "Unable to retrieve folder with specified ID"

        Exit Function

    End If

    MsgBox "Folder set to " & objFolder.Name

    Set objMessages = objFolder.Messages

See Also

Folder Object

ID Property (Folder Object)


GetInfoStore Method (Session Object)

The GetInfoStore method returns an InfoStore object that can be used to navigate through both public folders and the user’s personal folders.

Syntax

Set objInfoStore = objSession.GetInfoStore(storeID)

Parameters

objInfoStore

On successful return, contains the InfoStore object with the specified identifier. When the InfoStore object does not exist, GetInfoStore returns Nothing.

objSession

Required. The Session object.

storeID

Required. String that specifies the unique identifier of the InfoStore to retrieve.

Remarks

The GetInfoStore method allows you to obtain any message store for which you know the identifier.

Example

The following example uses the GetInfoStore method to obtain a specific message store:

' from the function Session_GetInfoStore

' requires a global variable that contains the InfoStore ID

Dim strInfoStoreID as String ' ID as hex string

Dim objInfoStore As Object  ' InfoStore object

    If strInfoStoreID = "" Then

        MsgBox ("Must first set InfoStore ID variable")

        Exit Function

    End If

    Set objInfoStore = objSession.GetInfoStore(

                          storeID:=strInfoStoreID)

    ' error handling...

    MsgBox "InfoStore set to " & objInfoStore.Name

See Also

Folder Object

ID Property (Folder Object)


GetMessage Method (Session Object)

The GetMessage method returns a Message object from a MAPI message store.

Syntax

Set objMessage = objSession.GetMessage(messageID [, storeID] )

Parameters

objMessage

On successful return, GetMessage returns a Message object. When the specified messageID does not exist, GetMessage returns Nothing.

objSession

Required. The Session object.

messageID

Required. String that specifies the unique identifier of the message.

storeID

Optional. String that specifies the unique identifier of the message store. The default value is an empty string, which corresponds to the default message store.

Example

The following example displays the subject of a message from a MAPI message store:

' fragment from Session_GetMessage

' requires the parameter strMessageID;

' also uses strMessageStoreID if it is defined

    If strMessageID = "" Then

        MsgBox ("Must first set message ID variable; see Message->ID")

        Exit Function

    End If

    If strMessageStoreID = "" Then ' not present

        Set objOneMsg = objSession.GetMessage(strMessageID)

    Else

        Set objOneMsg = objSession.GetMessage(messageID:=strMessageID, _

                                    storeID:=strMessageStoreID)

    End If

See Also

ID Property (Message Object)

Message Object


Inbox Property (Session Object)

The Inbox property returns a Folder object representing the current user’s default Inbox folder. Read-only.

Syntax

objSession.Inbox

Data Type

Object (Folder object)

Remarks

This property returns Nothing when the current user does not have an Inbox folder.

In addition to the general ability to navigate through the formal collection and object hierarchy, the OLE Messaging Library supports properties that let your application directly access the most common folder objects:

•	The IPM subtree

•	Inbox

•	Outbox

The following sample code uses the Session object’s Inbox property to initialize a Folder object:

' from the function Session_Inbox

    '   make sure the Session object is valid...

    Set objFolder = objSession.Inbox

    If objFolder Is Nothing Then

        MsgBox "Failed to open Inbox"

        Exit Function

    End If

    MsgBox "Folder name = " & objFolder.Name

    Set objMessages = objFolder.Messages

    If objMessages Is Nothing Then

        MsgBox "Failed to open folder's Messages collection"

        Exit Function

    End If

See Also

Folder Object

Outbox Property (Session Object)


InfoStores Property (Session Object)

The InfoStores property returns an InfoStores object representing a collection of available message stores. Each InfoStore object contains a root folder object. Read-only.

Syntax

objSession.InfoStores

Data Type

Object (InfoStores object)

Remarks

You can access public folders through the InfoStores collection. The public folders are maintained in their own InfoStore object that is distinct from the InfoStore object that contains the user’s personal messages.

When you know the unique identifier for the InfoStore object, you can also call the Session object’s GetInfoStore method.

For more information, see the reference documentation for the InfoStores collection and the InfoStore object.

Example

' from the functions Session_InfoStores, InfoStores_FirstItem,

' and InfoStore.Name

'   make sure the Session object is valid...

Dim objSession as Object         ' Session object

Dim objInfoStoresColl as Object  ' InfoStores collection

Dim objInfoStore as Object       ' InfoStore object

' assume valid Session object

    Set objInfoStoresColl = objSession.InfoStores

    If objInfoStoresColl Is Nothing Then

        MsgBox "Could not set InfoStores collection"

        Exit Function

    End If

    If 0 = objInfoStoresColl.Count Then

        MsgBox "No InfoStores in the collection"

        Exit Function

    End If

    iInfoStoresCollIndex = 1

    Set objInfoStore = objInfoStoresColl.Item(iInfoStoresCollIndex)

    If objInfoStore Is Nothing Then

        MsgBox "error, cannot get this InfoStore object"

        Exit Function

    Else

        MsgBox "Selected InfoStores " & iInfoStoresCollIndex

    End If

    If "" = objInfoStore.Name Then

        MsgBox "Active InfoStore has no name; ID = " & objInfoStore.Id

    Else

        MsgBox "Active InfoStore has name: " & objInfoStore.Name

    End If

See Also

InfoStores Collection

InfoStore Object


Logoff Method (Session Object)

The Logoff method logs off from the MAPI system.

Syntax

objSession.Logoff()

Parameters

objSession

Required. The Session object.

Example

The following example logs off from the MAPI system:

' from the function Session_Logoff

    If Not objSession Is Nothing Then

        objSession.Logoff

        MsgBox "Logged off; reset global variables"

    Else

        MsgBox "No active session"

    End If

See Also

Logon Method (Session Object)


Logon Method (Session Object)

The Logon method logs on to the MAPI system.

Syntax

objSession.Logon( [ profileName, profilePassword, showDialog, newSession, parentWindow ] )

Parameters

objSession

Required. The Session object.

profileName

Optional. A string specifying the user’s logon name. To prompt the user to enter a logon name, omit profileName and set showDialog to TRUE. The default value is an empty string.

profilePassword

Optional. A string specifying the user’s logon password. To prompt the user to enter a logon password, omit profilePassword and set showDialog to TRUE. The default value is an empty string.

showDialog

Optional. Boolean. If TRUE, displays a logon dialog box. The default value is TRUE.

newSession

Optional. Boolean. Determines whether the application opens a new MAPI session or uses the current shared MAPI session. If a shared MAPI session does not exist, newSession is ignored and a new session is opened. If the shared MAPI session does exist, this argument takes the following action:

Value	Action
TRUE	Opens an new MAPI session.
FALSE (default)	Uses the current shared MAPI session.
parentWindow

Optional. Long (HWND). Specifies the parent window handle for the logon dialog box. A value of 0 (the default) specifies that any dialog box displayed is application modal. The parentWindow parameter is ignored unless showDialog is TRUE.

Remarks

The user must log on before your application can use most MAPI objects.

The common MAPI dialog boxes automatically handle many of the error cases that can be encountered during logon. When you call Logon and do not supply the optional profile name parameter, the Choose Profile dialog box appears, asking the user to select a profile. When the profileName parameter is supplied but is not valid, common dialog boxes indicate the error and prompt the user to enter a valid name from the Choose Profile dialog box. When no profiles are defined, the Profile Wizard walks the user through the creation of a new profile.

When your application calls the Logon method after the user has already successfully logged on, the OLE Messaging Library generates the error MAPI_E_LOGON_FAILURE.

The following methods can also invoke MAPI dialog boxes: Delete and Details methods (AddressEntry object), Options and Send methods (Message object), Resolve method (Recipient object and Recipients collection), AddressBook method (Session object).

Example

The first example displays a logon dialog box that prompts the user to enter a logon password. The second example supplies the profileName parameter and does not display the dialog box:

' from the function Session_Logon

    Set objSession = CreateObject("MAPI.Session")

    If Not objSession Is Nothing Then

        objSession.Logon showDialog:=True

    End If

' from the function Session_Logon_NoDialog

Function Session_Logon_NoDialog()

    On Error GoTo error_olemsg

    ' can set strProfileName, strPassword from a custom form

    ' adjust these parameters for your configuration

    ' create a Session object if necessary here...

    '

    If Not objSession Is Nothing Then

        ' configure these parameters for your needs...

        objSession.Logon profileName:=strProfileName, showDialog:=False

    End If

    Exit Function

error_olemsg:

    If 1273 = Err Then

        MsgBox "cannot logon: incorrect profile name or password; change global variable strProfileName in Util_Initialize"

        Exit Function

    End If

    MsgBox "Error " & Str(Err) & ": " & Error$(Err)

    Resume Next

End Function

See Also

Starting an OLE Messaging Session, Logoff Method (Session Object)


MAPIOBJECT Property (Session Object)

The MAPIOBJECT property returns an IUnknown pointer to this Session object. Not available to Visual Basic applications. Read/write.

Syntax

objSession.MAPIOBJECT

Data Type

Variant (VT_UNKNOWN)

Remarks

The MAPIOBJECT property is not available to Visual Basic programs. It is available only to C/C++ programs that use the OLE Messaging Library. The MAPIOBJECT property is an IUnknown object, which is not supported by Visual Basic. Visual Basic supports IDispatch objects. For more information, see the Microsoft OLE Programmer’s Reference.

See Also

Introduction to OLE Automation


Name Property (Session Object)

The Name property returns the name of the profile logged on to this session. Read-only.

Syntax

objSession.Name

Data Type

String

Remarks

The Name property corresponds to the MAPI property PR_DISPLAY_NAME.

The Name property is the default property of a Session object, meaning that Session is syntactically equivalent to Session.Name in Visual Basic code.

Examples

' from the function Session_Name

    If objSession Is Nothing Then

        MsgBox "Must log on first: see Session menu"

        Exit Function

    End If

    MsgBox "Session name = " & objSession.Name

See Also

Session Object


OperatingSystem Property (Session Object)

The OperatingSystem property returns the name and version number of the current operating system. Read-only.

Syntax

objSession.OperatingSystem

Data Type

String

Remarks

The OLE Messaging Library returns strings in the following formats:

Operating system	String value
Microsoft Windows NT	Microsoft® Windows NT™ X.xx
Microsoft Windows for Workgroups	Microsoft® Windows™ X.xx
The X.xx values are replaced with the actual version numbers. Note that Microsoft Windows for Workgroups version 3.11 returns the string “Microsoft® Windows™ 3.10.” This is a feature of that operating system rather than a feature of the OLE Messaging Library.

Example

This example displays the name of the operating system:

' from the function Session_OperatingSystem

' assume objSession is a valid Session object

    MsgBox "Operating system = " & objSession.OperatingSystem

See Also

Version Property (Session Object)


Outbox Property (Session Object)

The Outbox property returns a Folder object representing the current user’s default Outbox folder. Read-only.

Syntax

objSession.Outbox

Data Type

Object

Remarks

The property returns Nothing if the current user does not have or has not enabled the Outbox folder.

In addition to the general ability to navigate through the formal collection and object hierarchy, the OLE Messaging Library supports properties that let your application directly access the most common folder objects:

•	The IPM subtree

•	Inbox

•	Outbox

Example

' from the function Session_Outbox

Dim objFolder As Object

' ...

    Set objFolder = objSession.Outbox

    If objFolder Is Nothing Then

        MsgBox "Failed to open Outbox"

        Exit Function

    End If

    MsgBox "Folder name = " & objFolder.Name

    Set objMessages = objFolder.Messages

See Also

Folder Object

Inbox Property (Session Object)


Version Property (Session Object)

The Version property returns the version number of the OLE Messaging Library as a string, for example, “1.1”. Read-only.

Syntax

objSession.Version

Data Type

String

Remarks

The version number for the OLE Messaging Library is represented by a string in the form n.xx, where n represents a major version number and xx represents a minor version number.

Example

' see the function Session_Version

    Dim objSession As Object

    Set objSession = CreateObject("MAPI.Session")

    ' error handling here...

    MsgBox "Version number is " & objSession.Version

MsgBox "Welcome to OLE Messaging Library version " & objSession.Version

See Also

OperatingSystem Property (Session Object)


PDH Reference

This section describes the PDH data types, functions, and structures.


PDH Data Types

All PDH string structures are shown as “TCHAR”, meaning that both Unicode and ANSI string structures are supported. Internally, the native or preferred code path inside the PDH is the Unicode string format, since it is built only for Windows NT. An ANSI version of each function is provided for those functions that have string arguments. They are, however, slightly less efficient since they must convert the ANSI string arguments to Unicode arguments before calling the Unicode version of the function.

The string data types expected are determined by the Unicode symbol when the application is compiled. If Unicode is defined, then the Unicode or wide character strings are expected. If the symbol is undefined, then the 8-bit or ANSI character strings are expected.

Data Type	Description
HQUERY	Handle to a query (HANDLE).
HCOUNTER	Handle to a counter. PDH maintains the linkage between counters and queries.
PDH_STATUS	LONG PDH status value.
Unless otherwise specified, all functions return a Win32 status value of ERROR_SUCCESS if the function completes successfully or a PDH error status value defined in the PDHMSG.H include file.

For data collection and formatting functions it is important to remember that the return value of the function indicates the success or error of the function call and not necessarily that of the counter data. Always check the CStatus field of the counter value returned to ensure that the data returned is valid before you use it. If the value of the CStatus field does not indicate success, do not use the data.


PDH Functions

This section describes the Performance Data Helper functions.


CounterPathCallback

The CounterPathCallback function processes the counter path strings read from the szReturnPathBuffer member of the PDH_BROWSE_DLG_CONFIG structure.

PDH_STATUS __stdcall CounterPathCallback(

IN DWORD dwArg	// Pointer to a PDH_BROWSE_DLG_CONFIG structure
);
Parameters

dwArg

The user-defined DWORD value passed to the callback function by the browser. This value is the dwCallBackArg member of the PDH_BROWSE_DLG_CONFIG structure passed to the browser by the caller.

Remarks

The following members in the PDH_BROWSE_DLG_CONFIG structure are used to communicate with the callback function:

szReturnPathBuffer

Contains the counter path strings currently selected by the user.

cchReturnPathLength

Contains the current maximum size of the szReturnPathBuffer member. If the callback function reallocates a new buffer, it must also update this value.

CallBackStatus

On entry to the callback function, this member contains the status of the path buffer. On exit, the callback function sets the status value resulting from processing.

If the buffer is too small to load the current selection, the browser will set this value to PDH_MORE_DATA. If the browser sets this member to ERROR_SUCCESS, then the szReturnPathBuffer member contains a valid counter path or counter path list.

If the callback function reallocates a new buffer, it should set this member to PDH_RETRY so that the browser will try to load the buffer with the selected paths and call the callback function again.

If some other error occurred, then the callback function should return the appropriate PDH error status value.

Return Values

If the function succeeds (processes the buffer and does not need to be called again), it returns ERROR_SUCCESS.

If the function fails (an error occurs and the function needs to be called again to retry the processing), it returns PDH_RETRY. This is usually the result of insufficient memory.

See Also

PdhBrowseCounters, PDH_BROWSE_DLG_CONFIG


PdhAddCounter

The PdhAddCounter function initializes a counter structure for the specified counter in the specified query.

PDH_STATUS PdhAddCounter(

IN HQUERY hQuery,	// handle to the query
IN LPCTSTR szFullCounterPath,	// path of the counter
IN DWORD dwUserData,	// user-defined value
IN HCOUNTER *phCounter	// pointer to the counter handle buffer
);
Parameters

hQuery

The handle of the query to which the new counter will be added.

szFullCounterPath

The fully qualified and resolved path of the counter to create. This path cannot contain wild card path strings or characters. See PDH_COUNTER_PATH_ELEMENTS.

dwUserData

A user-defined value, typically, a pointer or index to the user’s counter structure.

phCounter

A pointer to the buffer that is to receive the handle to the counter that is created.

Return Values

If the function succeeds, it returns ERROR_SUCCESS, creates a new counter, and returns the handle to the counter in the buffer pointed to by phCounter.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

PDH_CSTATUS_BAD_COUNTERNAME

The counter name path string could not be parsed or interpreted.

PDH_CSTATUS_NO_COUNTER

The specified counter was not found.

PDH_CSTATUS_NO_COUNTERNAME

An empty counter name path string was passed in.

PDH_CSTATUS_NO_MACHINE

A machine entry could not be created.

PDH_CSTATUS_NO_OBJECT

The specified object could not be found.

PDH_FUNCTION_NOT_FOUND

The calculation function for this counter could not be determined.

PDH_INVALID_ARGUMENT

One or more arguments are invalid.

PDH_INVALID_HANDLE

The query handle is not valid.

PDH_MEMORY_ALLOCATION_FAILURE

A memory buffer could not be allocated.

See Also

PdhRemoveCounter, PDH_COUNTER_PATH_ELEMENTS


PdhBrowseCounters

The PdhBrowseCounters function displays the counter browsing dialog box so that the user can select the counters to be returned to the caller.

PDH_STATUS PdhBrowseCounters(

IN PPDH_BROWSE_DLG_CONFIG pBrowseDlgData	// pointer to dialog structure
);
Parameters

pBrowseDlgData

Pointer to a PDH_BROWSE_DLG_CONFIG structure that specifies the behavior of the dialog box that receives the counter path strings.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H.

See Also

CounterPathCallback, PDH_BROWSE_DLG_CONFIG


PdhCalculateCounterFromRawValue

The PdhCalculateCounterFromRawValue function computes the current value of a counter as referenced by the hCounter parameter, using the raw counter data passed in the parameter list.

PDH_STATUS PdhCalculateCounterFromRawValue(

IN HCOUNTER hCounter,	// handle of the counter
IN DWORD dwFormat,	// format code
IN PPDH_RAW_COUNTER rawValue1,	// first raw counter
IN PPDH_RAW_COUNTER rawValue2,	// second raw counter
IN PPDH_FMT_COUNTERVALUE fmtValue	// calculated value
);
Parameters

hCounter

The handle of the counter used for the computation. This determines how the data will be computed.

dwFormat

The format code composed of the following values:

Value	Meaning
PDH_FMT_DOUBLE	Return the calculated value as a double-precision floating point real.
PDH_FMT_LARGE	Return the calculated value as a 64-bit integer.
PDH_FMT_LONG	Return the calculated value as a long integer.
The value selected from the previous table can be combined using the OR operator with one of the following scaling flags:

Flag	Meaning
PDH_FMT_NOSCALE	Do not apply the counter’s scaling factors in the calculation.
PDH_FMT_1000	Multiply the final value by 1000.
rawValue1

A pointer to the raw counter value used to compute the counter value. Some counters (for example, rate counters) require two raw values for a calculation. The format of the buffer depends on the type of counter to be processed.

rawValue2

A pointer to the raw counter value used in computations for counters that require two raw values (for example, rate counters). This value must be the older of the two raw values.

fmtValue

A pointer to the data buffer that will receive the calculated counter value.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

Value	Meaning
PDH_INVALID_ARGUMENT	An argument is not correct or is incorrectly formatted.
PDH_INVALID_HANDLE	The counter handle is not valid.
See Also

PdhGetFormattedCounterValue, PdhGetRawCounterValue, PdhSetCounterScaleFactor


PdhCloseQuery

The PdhCloseQuery function closes all counters contained in the specified query, closes all handles related to the query, and frees all memory associated with the query.

PDH_STATUS PdhCloseQuery(

IN HQUERY hQuery	// handle of the query to close and delete.
);
Parameters

hQuery

The handle of the query to close and delete.

Return Values

If the function succeeds, it returns ERROR_SUCCESS and closes and deletes the query.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following is a possible error value:

Value	Meaning
PDH_INVALID_HANDLE	The query handle is not valid.
See Also

PdhOpenQuery


PdhCollectQueryData

The PdhCollectQueryData function collects the current raw data value for all counters in the specified query and updates the status code of each counter.

PDH_STATUS PdhCollectQueryData(

IN HQUERY hQuery	// handle of the query
);
Parameters

hQuery

The handle of the query from which to collect data.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

Value	Meaning
PDH_INVALID_HANDLE	The query handle is not valid.
PDH_NO_DATA	The query does not currently have any counters.
Remarks

The PdhCollectQueryData function can succeed, but may not have collected data for all counters. Always check the status code of each counter in the query before using the data.

See Also

PdhOpenQuery


PdhComputeCounterStatistics

The PdhComputeCounterStatistics function computes statistics for a counter from an array of raw values.

PDH_STATUS PdhComputeCounterStatistics(

IN HCOUNTER hCounter,	// handle of the counter
IN DWORD dwFormat,	// format code
IN DWORD dwFirstEntry,	// first entry in the array
IN DWORD dwNumEntries,	// number of entries in the array
IN PPDH_RAW_COUNTER lpRawValueArray,	// array of raw counter values
IN PPDH_STATISTICS data	// buffer for counter statistics
);
Parameters

hCounter

The handle of the counter used for the computation. This determines how the data will be computed.

dwFormat

The formatting information sent by the caller to indicate how the calculated value should be returned. This parameter can be one of the following values:

PDH_FMT_DOUBLE

Return the calculated value as a double-precision floating point real.

PDH_FMT_LARGE

Return the calculated value as a 64-bit integer.

PDH_FMT_LONG

Return the calculated value as a long integer.

The value selected from the previous table can be combined using the OR operator with one of the following scaling flags:

PDH_FMT_NOSCALE

Do not apply the counter’s scaling factors in the calculation.

PDH_FMT_1000

Multiply the final value by 1000.

dwFirstEntry

The zero-based index of the first raw counter buffer to look at. This value must point to the oldest entry in the buffer. The PdhComputeCounterStatistics function starts at this entry and scans through the buffer, wrapping at the last entry back to the beginning of the buffer and up to the dwFirstEntry-1 entry, which is assumed to be the newest or most recent data.

dwNumEntries

The number of raw counter entries in the lpRawValueArray buffer.

lpRawValueArray

A pointer to the raw counter value or values used to compute the counter value. Some counters (for example, rate counters) require two values for a calculation. The format of the buffer is assumed to be an array of PDH_RAW_COUNTER structures that contain dwNumEntries entries.

data

A pointer to the PDH_STATISTICS buffer to receive the counter statistics.

Return Values

If the function succeeds, it returns ERROR_SUCCESS. The function can return successfully, but the returned data buffer can contain invalid data. Always check the CStatus member of the data buffer before using the returned statistics.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

PDH_INVALID_ARGUMENT

An argument is not correct or is incorrectly formatted.

PDH_INVALID_HANDLE

The counter handle is not valid.

See Also

PdhCalculateCounterFromRawValue, PdhGetRawCounterValue, PDH_RAW_COUNTER, PdhSetCounterScaleFactor, PDH_STATISTICS


PdhConnectMachine

The PdhConnectMachine function connects to the specified machine, and creates and initializes a machine entry in the PDH DLL.

PDH_STATUS PdhConnectMachine(

IN LPCTSTR szMachineName	// machine to browse
);
Parameters

szMachineName

The name of the machine to browse.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

PDH_CSTATUS_NO_MACHINE

Unable to connect to the specified machine. Could be caused by the machine not being on, not running Windows NT, not being connected to the network, or having the permissions set on the registry to not allow remote connections or remote performance monitoring by the user.

PDH_MEMORY_ALLOCATION_FAILURE

Unable to allocate a dynamic memory block. Occurs when there is a serious memory shortage in the system due to too many applications running on the system or an insufficient memory paging file.

Remarks

An application can call PdhConnectMachine to establish a connection to a remote machine at a more convenient time than when the application opens a query and adds counters.

See Also

PdhEnumMachines


PdhEnumMachines

The PdhEnumMachines function returns a list of the names of the machines that have been opened previously by the PDH DLL. The machines listed include those that are currently connected and online, as well as those that are offline or not returning performance data. For information about how to connect to a machine, see PdhConnectMachine.

PDH_STATUS PdhEnumMachines(

IN LPCTSR szReserved,	// reserved
IN LPTSTR mszMachineNameList,	// list of connected machines
IN LPDWORD pcchBufferLength	// pointer to buffer length
);
Parameters

szReserved

Reserved. Must be NULL.

mszMachineNameList

The buffer, allocated by the calling function, to receive the multi-SZ string list of machines to which the PDH DLL is currently connected. This parameter may be NULL if the value in the DWORD referenced by pcchBufferLength is 0.

pcchBufferLength

A pointer to the DWORD containing the size, in characters, of the available buffer on entry and the size of the returned buffer on exit. If the buffer size on entry is zero, then no data is returned in the mszMachineNameList buffer (and the pointer may be NULL), and the size of the buffer required, in characters, is returned in the DWORD pointed to by pcchBufferLength. The size returned includes both terminating NULL characters of the multi-SZ string.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

PDH_MORE_DATA

More data is available then the current buffer can hold. Some entries may be returned in the mszMachinenameList buffer.

PDH_INSUFFICIENT_BUFFER

The buffer provided is not large enough to contain any data.

PDH_INVALID_ARGUMENT

A required argument is invalid or a reserved argument is not NULL.

See Also

PdhConnectMachine


PdhEnumObjectItems

The PdhEnumObjectItems function returns the available counters and instances provided by the specified object on the specified machine.

PDH_STATUS PdhEnumObjectItems(

IN LPCTSTR szReserved,	// reserved
IN LPCTSTR szMachineName,	// machine name
IN LPCTSTR szObjectName,	// object name
IN LPTSTR mszCounterList,	// buffer for object’s counters
IN LPDWORD pcchCounterListLength,	// size of counter list buffer
IN LPTSTR mszInstanceList,	// buffer for object’s instances
IN LPDWORD pcchInstanceListLength,	// size of instance list buffer
IN DWORD dwDetailLevel,	// detail level
IN DWORD dwFlags	// formatting flag
);
Parameters

szReserved

Reserved. Must be NULL.

szMachineName

The name of the machine on which to list the object items. If the machine specified is not in the list of currently connected machines, the PDH will try to connect to it.

szObjectName

The name of the object on the specified machine from which the items are to be listed.

mszCounterList

The buffer allocated by the calling function that is to receive the multi-SZ list of performance counters provided by the specified object on the specified machine. This parameter can be NULL if the value of the DWORD referenced by pcchCounterListLength is 0.

pcchCounterListLength

A pointer to a DWORD containing the size, in characters, of the available buffer, and which returns the size of the buffer used. If the buffer size on entry is zero, then no data is returned in the mszCounterList buffer, and the size of the buffer required is returned in the DWORD pointed to by pdwCounterListLength. The size returned includes both terminating NULL characters of the multi-SZ string.

mszInstanceList

The buffer allocated by the calling function that is to receive the multi-SZ list of the instances of the specified object on the specified machine. This argument can be NULL if the value of the DWORD pointed to by pcchCounterListLength is 0.

pcchInstanceListLength

A pointer to the DWORD containing the size, in characters, of the available buffer, and which returns the size of the buffer used. If the buffer size on entry is zero, then no data is returned in the mszInstanceList buffer, and the size of the buffer required is returned in the DWORD pointed to by pcchInstanceListLength. The size returned includes both terminating NULL characters of the multi-SZ string. If the specified object does not support variable instances, then the returned value will be 0. If the specified object does support variable instances, but does not currently have any instances, then the value returned in this DWORD will be 2, which is the size, in characters, of an empty multi-SZ list string.

dwDetailLevel

The detail level of the performance items to return. All items that are of the specified detail level or less will be returned.

dwFlags

Must be 0.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

PDH_MORE_DATA

There are more entries available to return than there is room in the buffer. Some entries might be returned in the buffer, however.

PDH_INSUFFICIENT_BUFFER

The buffer provided is not large enough to contain any data.

PDH_INVALID_ARGUMENT

A required argument is invalid or a reserved argument is not NULL.

PDH_MEMORY_ALLOCATION_FAILURE

A required temporary buffer could not be allocated.

PDH_CSTATUS_NO_MACHINE

The specified machine is offline or unavailable.

PDH_CSTATUS_NO_OBJECT

The specified object could not be found on the specified machine.

See Also

PdhConnectMachine, PdhEnumObjects


PdhEnumObjects

The PdhEnumObjects function returns a list of objects available on the specified machine.

PDH_STATUS PdhEnumObjects(

IN LPCTSTR szReserved,	// reserved
IN LPCTSTR szMachineName,	// machine name
IN LPTSTR mszObjectList,	// buffer for objects
IN LPDWORD pcchBufferLength,	// size of buffer
IN DWORD dwDetailLevel,	// detail level
IN BOOL bRefresh	// refresh flag for connected machines
);
Parameters

szReserved

Reserved. Must be NULL.

szMachineName

The name of the machine on which to list the objects. If the machine specified is not in the list of currently connected machines, the PDH will try to connect to the machine and add it to the list.

mszObjectList

The buffer allocated by the calling function that is to receive the multi-SZ list of objects available on the specified machine. This parameter may be NULL if the value of the DWORD pointed to by pcchBufferLength is 0.

pcchBufferLength

A pointer to the DWORD containing the size, in characters, of the available buffer on entry and the size of the returned buffer on exit. If the buffer size on entry is zero, then no data is returned in the mszObjectList buffer, and that parameter may be NULL. However, the size of the buffer required, in characters, is returned in the DWORD pointed to by pcchBufferLength. The size returned includes both terminating NULL characters of the multi-SZ string.

dwDetailLevel

The detail level of the performance items to return. All items that are of the specified detail level or less will be returned.

bRefresh

Indicates that a new list of objects should be obtained from the specified machine. If the machine is not currently connected by the PDH, then this flag is ignored and the list is refreshed automatically.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

PDH_MORE_DATA

There are more entries available to return than there is room in the buffer. Some entries might be returned in the buffer, however.

PDH_INSUFFICIENT_BUFFER

The buffer provided is not large enough to contain any data.

PDH_INVALID_ARGUMENT

A required argument is invalid or a reserved argument is not NULL.

Remarks

When you request a required buffer size, the bRefresh flag should be FALSE for all subsequent calls to this function. Otherwise, the size might not be valid.

See Also

PdhConnectMachine, PdhEnumMachines


PdhExpandCounterPath

The PdhExpandCounterPath function examines the specified machine (or local machine if none is specified) for counters and instances of counters that match the wild card strings in the counter path. The counter path format is assumed to be:

\\machine\object(parent/instance#index)\countername

and the parent, instance, index, and countername elements may contain either a valid name or a wild card character.

PDH_STATUS PdhExpandCounterPath(

IN LPCTSTR szWildCardPath,	// counter path to expand
IN PPTSTR mszExpandedPathList,	// names that match
IN LPDWORD pcchPathListLength	// size of buffer
);
Parameters

szWildCardPath

The counter path to expand.

mszExpandedPathList

The buffer to receive the list of counter path names that match the wild card specification in the szWildCardPath buffer.

pcchPathListLength

The size of the mszExpandedPathList buffer, in characters, on entry and the size of the buffer used by the returned path strings on return.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H.

See Also

PdhMakeCounterPath


PdhGetCounterInfo

The PdhGetCounterInfo function retrieves information about a counter, such as data size, counter type, path, and user-supplied data values.

PDH_STATUS PdhGetCounterInfo(

IN HQUERY hCounter,	// handle of the counter
IN BOOLEAN bRetrieveExplainText,	// TRUE to retrieve explain text
IN LPDWORD pdwBufferSize,	// pointer to size of lpBuffer
IN PPDH_COUNTER_INFO lpBuffer	// buffer for counter information
);
Parameters

hCounter

The handle of the counter from which to retrieve the information.

bRetrieveExplainText

Determines whether explain text is retrieved. If you set this parameter to TRUE, then the explain text for the counter is retrieved. If you set this parameter to FALSE, the field in the returned buffer is NULL.

pdwBufferSize

A pointer to the size, in bytes, of the buffer passed in lpBuffer. If the counter requires a buffer larger than is indicated by pdwBufferSize, then PdhGetCounterInfo will return the required buffer size in this field. If the function succeeds, then this field will contain the size of the data returned in lpBuffer. If the size is zero, then no data will be returned in the buffer (in fact, lpBuffer can be NULL); and the size, in bytes, will be returned in the DWORD.

lpBuffer

A pointer to the data buffer to receive the counter information. The buffer returned is variable-length, because the string data is appended to the end of the fixed-format portion of the structure. This is done so that all data is returned in a single buffer allocated by the caller.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

PDH_INVALID_ARGUMENT

An argument is not correct or is incorrectly formatted.

PDH_INVALID_HANDLE

The counter handle is not valid.

PDH_MORE_DATA

The buffer supplied is not large enough to receive the requested data.

See Also

PDH_COUNTER_INFO


PdhGetDefaultPerfCounter

The PdhGetDefaultPerfCounter function retrieves the name of the default counter for the specified object. This can be used to set the initial selection of the counter browser list/combo box.

PDH_STATUS PdhGetDefaultPerfCounter(

IN LPCTSTR szReserved,	// reserved
IN LPCTSTR szMachineName,	// machine to query
IN LPCTSTR szObjectName,	// name of object
IN LPTSTR szDefaultCounterName,	// buffer to receive counter name
IN LPDWORD pcchBufferSize	// size of counter name
);
Parameters

szReserved

Reserved. Must be NULL.

szMachineName

The name of the machine to query.

szObjectName

The name of the object in szMachineName to query.

szDefaultCounterName

A pointer to the buffer that will receive the default counter name for the specified object. This parameter can be NULL if the value of the DWORD referenced by pcchBufferSize is 0.

pcchBufferSize

The size of the szDefaultCounterName buffer, in characters, when called, and the size of the counter name returned on return. If the value in the DWORD pointed to by this parameter is 0, then the required buffer size, in characters, for this object name will be returned in the DWORD and no data will be copied to the buffer.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

PDH_INSUFFICIENT_BUFFER

The buffer provided is not large enough for the available data.

PDH_INVALID_ARGUMENT

A required argument is invalid or a reserved argument is not NULL.

PDH_MEMORY_ALLOCATION_FAILURE

A required temporary buffer could not be allocated.

PDH_CSTATUS_NO_MACHINE

The specified machine is offline or unavailable.

PDH_CSTATUS_NO_COUNTERNAME

The default object name cannot be read or found.

PDH_CSTATUS_NO_OBJECT

The specified object could not be found on the specified machine.

PDH_CSTATUS_NO_COUNTER

The default counter was not found in the specified object.

See Also

PdhGetDefaultPerfObject


PdhGetDefaultPerfObject

The PdhGetDefaultPerfObject function retrieves the name of the default performance object. The name can be used to select the default entry in the object browser list box.

PDH_STATUS PdhGetDefaultPerfObject(

IN LPCTSTR szReserved,	// reserved
IN LPCTSTR szMachineName,	// machine to query
IN LPTSTR szDefaultObjectName,	// buffer to receive object
IN LPDWORD pcchBufferSize	// size of object name
);
Parameters

szReserved

Reserved. Must be NULL.

szMachineName

The name of the machine to query.

szDefaultObjectName

A pointer to the buffer to receive the default object name. This parameter can be NULL if the value of the DWORD referenced by pcchBufferSize is 0.

pcchBufferSize

The size of the szDefaultObjectName buffer, in characters, on entry and the size of the returned object name on exit. If the value in the DWORD referenced by this parameter is 0, then the required buffer size, in characters, for this object name will be returned in the DWORD and no data will be copied to the buffer.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

PDH_INSUFFICIENT_BUFFER

The buffer provided is not large enough for the available data.

PDH_INVALID_ARGUMENT

A required argument is invalid or a reserved argument is not NULL.

PDH_MEMORY_ALLOCATION_FAILURE

A required temporary buffer could not be allocated.

PDH_CSTATUS_NO_MACHINE

The specified machine is offline or unavailable.

PDH_CSTATUS_NO_COUNTERNAME

The default object name cannot be read or found.

See Also

PdhGetDefaultPerfCounter


PdhGetFormattedCounterValue

The PdhGetFormattedCounterValue function returns the current value of a specified counter in the format requested by the caller.

PDH_STATUS PdhGetFormattedCounterValue(

IN HCOUNTER hCounter,	// handle of the counter
IN DWORD dwFormat,	// formatting flag
IN LPDWORD lpdwType,	// counter type
IN PPDH_FMT_COUNTERVALUE pValue	// counter value
);
Parameters

hCounter

The handle of the counter whose current value is to be formatted and returned.

dwFormat

The formatting information sent by the caller to indicate how the data should be returned. This parameter can be one of the following values:

PDH_FMT_DOUBLE

Return data as a double-precision floating point real.

PDH_FMT_LARGE

Return data as a 64-bit integer.

PDH_FMT_LONG

Return data as a long integer.

The value selected from the previous table can be combined using the OR operator with one of the following scaling flags:

PDH_FMT_NOSCALE

Do not apply the default scaling factor.

PDH_FMT_1000

Multiply the actual value by 1000.

lpdwType

A pointer to a DWORD buffer that will receive the counter type. The possible counter types are described in WINPERF.H. This parameter is optional.

pValue

A pointer to the data buffer that will receive the counter value.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

PDH_INVALID_ARGUMENT

An argument is not correct or is incorrectly formatted.

PDH_INVALID_DATA

The specified counter does not contain valid data or a successful status code.

PDH_INVALID_HANDLE

The counter handle is not valid.

Remarks

The data for the counter is locked (protected) for the duration of the call to PdhGetFormattedCounterValue to prevent any changes during the processing of the call. Reading the data (calling this function successfully) clears the data-changed flag for the counter.

See Also

PdhGetRawCounterValue, PdhSetCounterScaleFactor


PdhGetRawCounterValue

The PdhGetRawCounterValue function returns the current raw value of the counter.

PDH_STATUS PdhGetRawCounterValue(

IN HCOUNTER hCounter,	// handle of the counter
IN LPDWORD lpdwType,	// counter type
IN PPDH_RAW_COUNTER pValue	// counter value
);
Parameters

hCounter

The handle of the counter from which to retrieve the current raw value.

lpdwType

A pointer to a DWORD buffer that will receive the counter type. The possible counter types are described in WINPERF.H. This parameter is optional. You can pass NULL if you don’t want the type information.

pValue

A pointer to the data buffer that will receive the counter value.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

PDH_INVALID_ARGUMENT

An argument is not correct or is incorrectly formatted.

PDH_INVALID_HANDLE

The counter handle is not valid.

Remarks

The data for the counter is locked (protected) for the duration of the call to PdhGetRawCounterValue to prevent any changes during processing of the call.

See Also

PdhGetFormattedCounterValue, PdhCalculateCounterFromRawValue


PdhMakeCounterPath

The PdhMakeCounterPath function creates a full counter path using the members specified in the structure passed in the parameter list.

PDH_STATUS PdhMakeCounterPath(

IN PDH_COUNTER_PATH_ELEMENTS *pCounterPathElements,	// counter path elements
IN LPTSTR szFullPathBuffer,	// path string buffer
IN LPDWORD pcchBufferSize,	// size of buffer
IN DWORD dwFlags	// reserved
);
Parameters

*pCounterPathElements

Pointer to a PDH_COUNTER_PATH_ELEMENTS structure that contains the individual members that are to make up the path. The following table indicates which members are required and which are optional:

Member	Required or Optional
LPTSTR szMachineName	optional
LPTSTR szObjectName	required
LPTSTR szInstanceName	optional
LPTSTR szParentInstance	optional
DWORD dwInstanceIndex	optional ((DWORD)−1 if no index)
LPTSTR szCounterName	required
If a required member is not present, then no path string will be constructed. If the szMachineName member is NULL, then no machine name will be included in the path (a generic path will be created). If the instance name argument is NULL, then no instance reference will be inserted into the path string and the szParentInstance and the dwInstanceIndex members will be ignored.

szFullPathBuffer

The buffer allocated by the caller that will receive the full path string created by this function.

pcchBufferSize

A pointer to the DWORD containing the size, in bytes, of the available buffer, and which returns with the size of the buffer used. If the buffer size on entry is zero, then no data is returned in the szFullPathBuffer buffer, however, the size of the buffer required is returned in the DWORD. The size returned includes the terminating NULL character of the string.

dwFlags

Reserved. Must be zero.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H.

See Also

PDH_COUNTER_PATH_ELEMENTS, PdhParseCounterPath


PdhOpenQuery

The PdhOpenQuery function creates and initializes a unique query structure that is used to manage collection of performance data.

PDH_STATUS PdhOpenQuery(

IN LPVOID pReserved,	// reserved
IN DWORD dwUserData,	// a value associated with this query
IN HQUERY *phQuery	// pointer to a buffer that will receive the query handle
);
Parameters

pReserved

Reserved. Must be NULL.

dwUserData

A user-defined DWORD value that is to be associated with this query. You can call PdhGetCounterInfo to retrieve the user data value for the query in which a counter resides.

phQuery

A pointer to the buffer to receive the handle to the query that is created.

Return Values

If the function succeeds, it returns ERROR_SUCCESS, creates a new query, and returns the handle to the query in the buffer pointed to by phQuery.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

PDH_INVALID_ARGUMENT

One or more arguments are invalid.

PDH_MEMORY_ALLOCATION_FAILURE

A memory buffer could not be allocated.

See Also

PdhCloseQuery, PdhGetCounterInfo


PdhParseCounterPath

The PdhParseCounterPath function parses the elements of the counter path and stores the results in the structure passed by the caller.

PDH_STATUS PdhParseCounterPath(

IN LPCTSTR szFullPathBuffer,	// path string buffer
IN PDH_COUNTER_PATH_ELEMENTS *pCounterPathElements,	// counter path elements
IN LPDWORD pdwBufferSize,	// size of buffer
IN DWORD dwFlags	// reserved
);
Parameters

szFullPathBuffer

The buffer containing the counter path to parse into individual components.

pCounterPathElements

A pointer to a PDH_COUNTER_PATH_ELEMENTS structure that will receive the individual components of the path referenced by the szFullPathBuffer parameter. The buffer space allocated for this should be large enough for the structure and the strings that will be referenced by the members in this structure. As this function parses the elements in the path, they are stored in the buffer after the PDH_COUNTER_PATH_ELEMENTS structure. This allows the calling function to allocate, and eventually free, only a single block of memory for this structure and the strings referenced by the members of this structure, rather than having the calling function allocate the structure and the string buffers separately.

pdwBufferSize

A pointer to the DWORD containing the size, in bytes, of the buffer referenced by pCounterPathElements and returns with the size of the buffer used. If the buffer size on entry is zero, then no data is returned in the pCounterPathElements buffer, however, the size of the buffer required is returned in the DWORD referenced by this pointer.

dwFlags

Reserved. Must be zero.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

PDH_INVALID_ARGUMENT

An argument is incorrect, or this function does not have the necessary access to that argument.

PDH_INSUFFICIENT_BUFFER

The buffer supplied is not large enough to accept the resulting data.

PDH_INVALID_PATH

The path is not formatted correctly and cannot be parsed.

PDH_MEMORY_ALLOCATION_FAILURE

A temporary buffer cannot be allocated.

See Also

PDH_COUNTER_PATH_ELEMENTS, PdhMakeCounterPath


PdhParseInstanceName

The PdhParseInstanceName function parses the elements of an instance string and returns them in the buffers supplied by the caller.

PDH_STATUS PdhParseInstanceName(

IN LPCTSTR szInstanceString,	// instance string
IN LPTSTR szInstanceName,	// parsed instance name
IN LPDWORD pcchInstanceNameLength,	// length of name
IN LPTSTR szParentName,	// name of parent index
IN LPDWORD pcchParentNameLength,	// length of parent name
IN LPDWORD lpIndex	// instance index
);
Parameters

szInstanceString

A pointer to the string containing the instance substring to parse into individual components. This string can contain the following formats, and is less than MAX_PATH characters in length:

instance
instance#index
parent/instance
parent/instance#index

szInstanceName

A pointer to the buffer that will receive the instance name parsed from the instance string. This pointer can be NULL if the DWORD referenced by the pcchInstanceNameLength parameter is 0.

pcchInstanceNameLength

A pointer to the DWORD that contains the length of the szInstanceName buffer. If the value of this DWORD is 0, then the buffer size required to hold the instance name will be returned.

szParentName

A pointer to the buffer that will receive the name of the parent index if one is specified. This parameter can be NULL if the value of the DWORD referenced by the pcchParentNameLength parameter is 0.

pcchParentNameLength

A pointer to the DWORD that contains the length of the szParentName buffer. If the value of this DWORD is 0, then the buffer size required to hold the instance name will be returned.

lpIndex

A pointer to the DWORD that will receive the index value of the instance. If an index entry is not present in the string, then this value will be 0. This argument can be NULL if this information is not needed.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

PDH_INVALID_ARGUMENT

An argument is invalid or incorrect.

PDH_INSUFFICIENT_BUFFER

One or both of the string buffers supplied is not large enough for the strings to be returned.

PDH_INVALID_INSTANCE

The instance string is incorrectly formatted, exceeds MAX_PATH characters in length, or cannot be parsed.

See Also

PdhMakeCounterPath


PdhRemoveCounter

The PdhRemoveCounter function removes a counter from a query.

PDH_STATUS PdhRemoveCounter(

IN HCOUNTER hCounter	// handle of the counter
);
Parameters

hCounter

The handle of the counter to remove from its query.

Return Values

If the function succeeds, it returns ERROR_SUCCESS and removes the specified counter from its query.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following is a possible error value:

PDH_INVALID_HANDLE

The counter handle is not valid.

Remarks

After you remove a counter, any references to it using the handle passed in hCounter will be invalid and will return an error.

See Also

PdhAddCounter, PdhOpenQuery


PdhSetCounterScaleFactor

The PdhSetCounterScaleFactor function sets the scale factor that is applied to the calculated value of the specified counter when you request the formatted counter value. If the PDH_FMT_NOSCALE flag is set, then this scale factor is ignored.

PDH_STATUS PdhSetCounterScaleFactor(

IN HCOUNTER hCounter,	// handle of the counter
IN LONG lFactor	// power of ten used to multiply value
);
Parameters

hCounter

The handle of the counter to receive the scale factor in lFactor.

lFactor

The power of ten by which to multiply the calculated value before returning it. The valid range of this parameter is PDH_MIN_SCALE (−7) (the returned value is the actual value times 10−7) to PDH_MAX_SCALE (+7) (the returned value is the actual value times 10+7). A value of zero will set the scale to one, so that the actual value is returned.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is an error status defined in PDHMSG.H. The following are possible error values:

PDH_INVALID_ARGUMENT

The scale value is out of range.

PDH_INVALID_HANDLE

The counter handle is not valid.

See Also

PdhCalculateCounterFromRawValue, PdhComputeCounterStatistics, PdhGetFormattedCounterValue


PdhValidatePath

The PdhValidatePath function validates that the specified counter is present on the machine specified in the counter path.

PDH_STATUS PdhValidatePath(

IN LPCTSTR szFullCounterPath	// counter path to validate
);
Parameters

szFullCounterPath

The counter path to validate.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMSG.H. The following are possible error values:

PDH_CSTATUS_NO_INSTANCE

The specified instance of the performance object was not found.

PDH_CSTATUS_NO_COUNTER

The specified counter was not found in the performance object.

PDH_CSTATUS_NO_OBJECT

The specified performance object was not found on the machine.

PDH_CSTATUS_NO_MACHINE

The specified machine could not be found or connected to.

PDH_CSTATUS_BAD_COUNTERNAME

The counter path string could not be parsed.

PDH_MEMORY_ALLOCATION_FAILURE

The function is unable to allocate a required temporary buffer.

See Also

PdhMakeCounterPath


PDH Functions for Visual Basic 4.0

The functions described in this section enable the Visual Basic programmer to use Windows NT Performance Data Helper within a Visual Basic application program.


PdhAddCounter (VB)

The Visual Basic PdhAddCounter function creates a counter entry in the specified query object, and returns the handle for that counter upon successful completion.

PdhAddCounter(

ByVal QueryHandle as Long,
ByVal CounterPath as String,
ByRef CounterHandle as Long)
as Long
Parameters

QueryHandle

The ID of the query to assign this counter to. This must be a value returned by a successful call to PdhOpenQuery.

CounterPath

The text string containing the name of the counter path to add to the query. The contents of this string must be a valid counter path, as obtained from the counter browser or other source.

CounterHandle

The unique reference that identifies this counter in the query. This variable must be initialized to zero before the function is called. It contains a valid value on return only if the function completes successfully.

Return Values

If the function succeeds, it returns a Long integer equal to ERROR_SUCCESS and a new handle in the CounterHandle variable.

If the function fails, the return value is a PDH error status defined in PDHDEFS.TXT. The following are possible error values:

PDH_INVALID_ARGUMENT

One or more of the arguments is invalid or incorrect.

PDH_MEMORY_ALLOCATION_FAILURE

A memory buffer could not be allocated.

PDH_INVALID_HANDLE

The query handle is not valid.

PDH_CSTATUS_NO_COUNTER

The specified counter was not found.

PDH_CSTATUS_NO_OBJECT

The specified object could not be found.

PDH_CSTATUS_NO_MACHINE

A machine entry could not be created.

PDH_CSTATUS_BAD_COUNTERNAME

An empty counter name path string was passed in.

PDH_FUNCTION_NOT_FOUND

The calculation function for this counter could not be determined.


PdhCloseQuery (VB)

The Visual Basic PdhCloseQuery function closes the specified query and all counters related to that query. All resources allocated for the query and its counters are freed. The handles of counters added to this query should be deleted or zeroed and not used after the query they belong to is deleted.

PdhCloseQuery(

ByVal QueryHandle as Long)
as Long
Parameters

QueryHandle

The ID of the query to close and delete. Closing a query closes all the counters associated with the query.

Return Values

If the function succeeds, it returns a Long integer equal to ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHDEFS.TXT. The following is a possible error value:

PDH_INVALID_HANDLE

The handle is invalid.


PdhCollectQueryData (VB)

The Visual Basic PdhCollectQueryData function collects the current raw value of each counter in the query referenced by the QueryHandle parameter and updates the internal buffers of each counter object.

PdhCollectQueryData(

ByVal QueryHandle as Long)
as Long
Parameters

QueryHandle

The ID of the query to update. This must be a value returned by a call to PdhOpenQuery.

Return Values

If the function succeeds, it returns a Long integer equal to ERROR_SUCCESS. Note that the function can return successfully, but some or all counters in the query may not have been updated.

If the function fails, the return value is a PDH error status defined in PDHDEFS.TXT. The following are possible error values:

PDH_INVALID_HANDLE

The query handle is not valid.

PDH_NO_DATA

The query does not have any counters defined yet.


PdhCreateCounterPathList (VB)

The Visual Basic PdhCreateCounterPathList function displays the performance counter browsing dialog box, which lets the user select several performance counters. Each selected counter path must then be read using the PdhGetCounterPathFromList function.

PdhCreateCounterPathList(

ByVal DetailLevel as Long,
ByVal CaptionString as String)
as Long
Parameters

DetailLevel

One of the following values defined in PDHDEFS.TXT. The selected value indicates the types of counters to be displayed in the dialog box:

Value	Counters Displayed
PERF_DETAIL_NOVICE	Only counters that the novice user is likely to understand.
PERF_DETAIL_ADVANCED	Counters that the advanced user is likely to understand, in addition to the novice-user counters.
PERF_DETAIL_EXPERT	Counters that the expert user and software developer is likely to understand, in addition to the counters for the novice and advanced users.
PERF_DETAIL_WIZARD	All counters in the system.
CaptionString

A string variable that contains the text that will be displayed in the caption bar of the dialog box.

Return Values

The function returns the number of counter paths that the user selected.


PdhGetCounterPathElements (VB)

The Visual Basic PdhGetCounterPathElements function parses a fully qualified performance counter path string into its individual elements. Each of the string variables must be the same size (BufferSize) and dimensioned and initialized before it is used in this function.

PdhGetCounterPathElements(

ByVal PathString as String,
ByVal MachineName as String,
ByVal ObjectName as String,
ByVal InstanceName as String,
ByVal ParentInstance as String,
ByVal CounterName as String,
ByVal BufferSize as Long)
as Long
Parameters

PathString

The counter path string that is to be broken up into its individual elements.

MachineName

The string to receive the Machine name element of the counter path specified in PathString.

ObjectName

The string to receive the Object element of the counter path specified in PathString.

InstanceName

The string to receive the Instance name element, if used, of the counter path specified in PathString.

ParentInstance

The string to receive the Parent Instance element, if used, of the counter path specified in PathString.

CounterName

The string to receive the Machine name element of the counter path specified in PathString.

BufferSize

The maximum size of each string variable used as a parameter to this function call.

Return Values

If the function succeeds, it returns a Long integer equal to ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHDEFS.TXT. The following are possible error values:

PDH_INVALID_ARGUMENT

One or more of the string buffers is not the correct size.

PDH_INSUFFICIENT_BUFFER

One or more of the counter path elements is too large for the return buffer length.

PDH_MEMORY_ALLOCATION_FAILURE

A temporary memory buffer could not be allocated.


PdhGetCounterPathFromList (VB)

The Visual Basic PdhGetCounterPathFromList function copies the counter path referenced by the Index parameter from a counter path list created by the user from the most recent call to the PdhCreateCounterPathList function.

PdhGetCounterPathFromList(

ByVal Index as Long,
ByVal Buffer as String,
ByVal BufferLength as Long)
as Long
Parameters

Index

The index of the counter path to retrieve. This must be a value that is greater than or equal to 1, and less than or equal to the value returned by the PdhCreateCounterPathList function.

Buffer

A dimensioned and initialized string that will receive the counter path that corresponds to the value of the Index parameter.

BufferLength

The maximum number of characters that will fit in the string referenced by Buffer.

Return Values

The function returns the number of characters copied to Buffer.


PdhGetDoubleCounterValue (VB)

The Visual Basic PdhGetDoubleCounterValue function returns the current value of the specified counter as a double-precision floating point value. You should check CounterStatus before using the returned number, because the counter may not be valid when it is read. Call PdhIsGoodStatus to check the CounterStatus.

PdhGetDoubleCounterValue(

ByVal CounterHandle as Long,
ByRef CounterStatus as Long)
as Double
Parameters

CounterHandle

The ID of the counter whose current value is to be read.

CounterStatus

The variable in which the current status of the counter value is returned to the caller. The returned data value is valid if and only if the value returned in CounterStatus is PDH_CSTATUS_VALID_DATA or PDH_CSTATUS_NEW_DATA (defined in PDHDEFS.TXT). If the value returned in CounterStatus is any other value, do not use the data.

Return Values

PdhGetDoubleCounterValue returns the double-precision floating point value of the current counter, computed and formatted as defined by the counter type.


PdhGetOneCounterPath (VB)

The Visual Basic PdhGetOneCounterPath function displays a dialog box that lets the user browse the available performance counters on a Windows NT system and select one counter. The counter selected is returned in the PathString variable. The PathString variable must be dimensioned and initialized before this function is called, and the dimensioned size must be indicated by the PathLength variable.

PdhGetOneCounterPath(

ByVal PathString as String,
ByVal PathLength as Long,
ByVal DetailLevel as Long,
ByVal CaptionString as String)
as Long
Parameters

PathString

The initialized string variable used to receive the counter path selected by the user.

PathLength

The length of the initialized PathString.

DetailLevel

One of the following values defined in PDHDEFS.TXT. The selected value indicates the types of counters to be displayed in the dialog box:

Value	Counters Displayed
PERF_DETAIL_NOVICE	Only counters that the novice user is likely to understand.
PERF_DETAIL_ADVANCED	Counters that the advanced user is likely to understand, in addition to the novice-user counters.
PERF_DETAIL_EXPERT	Counters that the expert user and software developer is likely to understand, in addition to the counters for the novice and advanced users.
PERF_DETAIL_WIZARD	All counters in the system.
CaptionString

A string variable that contains the text that will be displayed in the caption bar of the dialog box.

Return Values

The function returns the number of characters written to the PathString buffer.


PdhIsGoodStatus (VB)

The Visual Basic PdhIsGoodStatus function tests a status value to determine if it is a success or failure code. If the status value is a successful one, then the return value will be nonzero. If it is a failure status code, the return value will be zero.

PdhIsGoodStatus(

ByVal StatusValue as Long)
as Long
Parameters

StatusValue

The PDH status value returned by another PDH function that is to be tested.

Return Values

The function returns zero if the status code is a failure status code. It returns nonzero if the status code is a success status code.


PdhOpenQuery (VB)

The Visual Basic PdhOpenQuery function creates and initializes a unique query structure that is used to manage the collection of performance data.

PdhOpenQuery(

ByRef QueryHandle as Long)
as Long
Parameters

QueryHandle

A variable that is cleared (equals 0) before the function is called and, if the function is successful, contains the unique ID of the query that is created and opened. This handle is used in the subsequent calls to other PDH functions to identify the query.

Return Values

If the function succeeds, it returns a Long integer equal to ERROR_SUCCESS and a new handle in the QueryHandle variable.

If the function fails, the return value is a PDH error status defined in PDHDEFS.TXT. The following are possible error values:

PDH_INVALID_ARGUMENT

The argument is invalid or incorrect.

PDH_MEMORY_ALLOCATION_FAILURE

A temporary memory buffer could not be allocated.


PdhRemoveCounter (VB)

The Visual Basic PdhRemoveCounter function removes the counter entry identified by the CounterHandle parameter.

PdhRemoveCounter(

ByVal CounterHandle as Long)
as Long
Parameters

CounterHandle

The ID of the counter returned by the PdhAddCounter function.

Return Values

If the function succeeds, it returns a Long integer equal to ERROR_SUCCESS and the counter entry is deleted from the query.

If the function fails, the return value is a PDH error status defined in PDHDEFS.TXT. The following is a possible error value:

Value	Meaning
PDH_INVALID_HANDLE	The counter handle is not valid.


PDH Structures

The following are Performance Data Helper structures.


PDH_RAW_COUNTER

The PDH_RAW_COUNTER structure returns the data as it was collected from the counter provider. No translation, formatting, or other interpretation is performed on the data.

typedef struct _PDH_RAW_COUNTER {

    DWORD       CStatus;

    FILETIME    TimeStamp;

    LONGLONG    FirstValue;

    LONGLONG    SecondValue;

    DWORD       MultiCount;

} PDH_RAW_COUNTER, *PPDH_RAW_COUNTER;

Members

CStatus

The status of the last collection operation for this counter. See Counter Status versus Function Status.

TimeStamp

The local time this data was collected.

FirstValue

The first raw counter value.

SecondValue

The second (if necessary) raw counter value.

MultiCount

The multi count (normally 1).

See Also

PdhCalculateCounterFromRawValue, PdhComputeCounterStatistics, PdhGetRawCounterValue


PDH_FMT_COUNTERVALUE

The PDH_FMT_COUNTERVALUE structure is the most commonly used method of reading the data from within an application. The data type of the data returned (member of the union that will have meaningful data) is specified by the caller when requesting the data. The CStatus member provides the status of the counter. Check this member before using the data in a calculation or display. The counter, and therefore the data, could be invalid.

typedef struct _PDH_FMT_COUNTERVALUE {

    DWORD    CStatus;

    union {

        LONG        longValue;

        double      doubleValue;

        LONGLONG    largeValue;

    };

} PDH_FMT_COUNTERVALUE, *PPDH_FMT_COUNTERVALUE;

Members

CStatus

The status of last collection operation for this counter. See Counter Status versus Function Status.

See Also

PdhCalculateCounterFromRawValue, PdhGetFormattedCounterValue


PDH_STATISTICS

The PDH_STATISTICS structure is used to return the statistics of the values in an array of raw counters managed by the application program. The format of the data in the PDH_FMT_COUNTERVALUE structure is described in the dwFormat member.

typedef struct _PDH_STATISTICS {

    DWORD                   dwFormat;

    DWORD                   count;

    PDH_FMT_COUNTERVALUE    min;

    PDH_FMT_COUNTERVALUE    max;

    PDH_FMT_COUNTERVALUE    mean;

} PDH_STATISTICS, *PPDH_STATISTICS;

Members

dwFormat

The format of the data.

count

The number of values in the array.

min

The minimum of the values.

max

The maximum of the values.

mean

The mean of the values.

See Also

PdhComputeCounterStatistics, PDH_FMT_COUNTERVALUE


PDH_COUNTER_PATH_ELEMENTS

The PDH_COUNTER_PATH_ELEMENTS structure contains the parsed elements of a fully qualified counter path. The main purpose of this structure is to provide formatted text to the calling application for display.

typedef struct _PDH_COUNTER_PATH_ELEMENTS {

    LPTSTR  szMachineName;

    LPTSTR  szObjectName;

    LPTSTR  szInstanceName;

    LPTSTR  szParentInstance;

    DWORD   dwInstanceIndex;

    LPTSTR  szCounterName;

} PDH_COUNTER_PATH_ELEMENTS, *PPDH_COUNTER_PATH_ELEMENTS;

Members

szMachineName

The machine name, parsed from the counter path.

szObjectName

The object name, parsed from the counter path.

szInstanceName

The instance name, parsed from counter path.

szParentInstance

The parent instance name, parsed from counter path.

dwInstanceIndex

The index of duplicate instance names.

szCounterName

The counter name.

See Also

PdhMakeCounterPath, PdhParseCounterPath


PDH_COUNTER_INFO

The PDH_COUNTER_INFO structure contains information describing the properties of a counter. This information also includes the counter path. The format of this buffer is to have the structure described below followed by a variable-length buffer containing the string information referenced by the string pointers in the structure (szFullPath, szMachineName, szObjectName, szInstanceName, szParentInstance, szCounterName, and szExplainText).

typedef struct _PDH_COUNTER_INFO {

    DWORD   dwLength;

    DWORD   dwType;

    DWORD   CVersion;

    DWORD   CStatus;

    LONG    lScale;

    LONG    lDefaultScale;

    DWORD   dwUserData;

    DWORD   dwQueryUserData;

    LPTSTR  szFullPath;

    union   {

        PDH_COUNTER_PATH_ELEMENTS CounterPath;

        struct {

            LPTSTR   szMachineName;

            LPTSTR   szObjectName;

            LPTSTR   szInstanceName;

            LPTSTR   szParentInstance;

            DWORD    dwInstanceIndex;

            LPTSTR   szCounterName;

        };

    };

    LPTSTR  szExplainText;

    DWORD   DataBuffer[1];

} PDH_COUNTER_INFO, *PPDH_COUNTER_INFO;

Members

dwLength

The length of the structure, including strings.

dwType

The counter type.

CVersion

Counter version information.

CStatus

The current counter status. See Counter Status versus Function Status.

lScale

The current scale factor.

lDefaultScale

The recommended scale factor.

dwUserData

The value of the counter’s User Data field.

dwQueryUserData

The value of the User Data field for the query to which the counter belongs.

szFullPath

The full counter path.

CounterPath

See PDH_COUNTER_PATH_ELEMENTS.

szExplainText

The explain text for this counter.

DataBuffer[1]

The first byte of string data appended to the structure.

See Also

PDH_COUNTER_PATH_ELEMENTS, PdhGetCounterInfo


PDH_BROWSE_DLG_CONFIG

The PDH_BROWSE_DLG_CONFIG structure is used by the PdhBrowseCounters function to configure the PDH Browse Counters dialog box.

typedef struct _BrowseDlgConfig {

    // Configuration flags

    DWORD   bIncludeInstanceIndex:1,

            bSingleCounterPerAdd:1,

            bSingleCounterPerDialog:1,

            bLocalCountersOnly:1,

            bWildCardInstances:1,

            bHideDetailBox:1,

            bInitializePath:1,

            bReserved:25;

    HWND                hWndOwner;

    LPTSTR              szReserved;

    LPTSTR              szReturnPathBuffer;

    DWORD               cchReturnPathLength;

    CounterPathCallBack pCallBack;

    DWORD               dwCallBackArg;

    PDH_STATUS          CallBackStatus;

    DWORD               dwDefaultDetailLevel;

    LPTSTR              szDialogBoxCaption;

} PDH_BROWSE_DLG_CONFIG, *PPDH_BROWSE_DLG_CONFIG;

Members

Configuration Flags

The initial DWORD of the PDH_BROWSE_DLG_CONFIG structure contains the following configuration flag fields. The default value for each field is FALSE.

bIncludeInstanceIndex

TRUE: The returned counter path will include the instance index for the instance.

FALSE: The returned counter path will not contain an instance number.

bSingleCounterPerAdd

TRUE: Multiple selections are not permitted. Only one counter will be returned each time the ADD button is clicked.

FALSE: Multiple and wild card selections are permitted. Selected counters are returned as a multi-SZ string each time the ADD button is clicked.

bSingleCounterPerDialog

TRUE: The dialog box is closed after the ADD button is clicked the first time.

FALSE: The dialog box is not closed until the CLOSE button is clicked. The ADD button can be clicked, and counters can be added, multiple times.

bLocalCountersOnly

TRUE: The machine name will not prefix the counter path in the returned string.

FALSE: The machine name will prefix the counter path unless the user selects the Local Counters Only radio button.

bWildCardInstances

TRUE: If wild card instances (for example, ALL) are selected, then the returned counter path will include the wild-card syntax (for example, “*”) for the instance field.

FALSE: If All Instances has been selected, all the instances currently found for that object will be returned in a multi-SZ string.

bHideDetailBox

TRUE: Removes the Detail Level combo box from the dialog box so the user cannot change the detail level of the counters displayed in the dialog box. The detail level will be fixed to the value of the dwDefaultDetailLevel member.

FALSE: Displays the Detail Level combo box in the dialog box, allowing the user to change the detail level of the counters displayed.

Note that the counters displayed will be those whose detail level is less than or equal to the current detail level selection. Selecting a detail level of Wizard will display all counters and objects.

bInitializePath

TRUE: Selects the counter and object based on the first counter path contained in the szReturnPathBuffer member when the dialog box is first displayed, instead of using the default counter and object specified by the machine.

FALSE: Selects the initial counter and object using the default counter and object information returned by the machine.

hWndOwner

The handle of the calling function’s window.

szReserved

Reserved. Must be NULL.

szReturnPathBuffer

The buffer, allocated by the caller, that is used to initialize the first selection in the list boxes (bInitializePath == TRUE) and to return the selected counters to the calling function or the callback procedure.

cchReturnPathLength

The current maximum size, in characters, of the buffer referenced by the szReturnPathBuffer member.

pCallBack

The address of the callback function used to update application buffers and controls when a multiple-selection dialog box is configured.

dwCallBackArg

User-defined argument that is passed as the only argument to the callback function when it is called by the dialog box.

CallBackStatus

Status of the dialog box prior to calling the callback function.

dwDefaultDetailLevel

The default detail level to show on startup in the Detail Level combo box. If the Detail Level combo box is not shown, this is the detail level to use in filtering the displayed performance counters and objects.

szDialogBoxCaption

The optional caption to be displayed in the caption bar of the PDH Browse Counters dialog box. If this member is NULL, the caption will be Browse Performance Counters.

See Also

CounterPathCallback, PdhBrowseCounters


PERF_COUNTER_BLOCK

The PERF_COUNTER_BLOCK structure contains the length, in bytes, of the performance-counter data. This structure is followed by data for the number of counters specified in the PERF_OBJECT_TYPE structure.

typedef struct _PERF_COUNTER_BLOCK { // pcd

    DWORD ByteLength;

} PERF_COUNTER_BLOCK;

Members

ByteLength

Specifies the length, in bytes, of this structure, including the counters that follow.

Remarks

This structure is part of the performance data provided by the RegQueryValueEx function when the HKEY_PERFORMANCE_DATA key is used.

See Also

PERF_OBJECT_TYPE, RegQueryValueEx


PERF_COUNTER_DEFINITION

The PERF_COUNTER_DEFINITION structure describes a performance counter. The Unicode names in this structure must appear in a message file.

typedef struct _PERF_COUNTER_DEFINITION { // pcd

    DWORD  ByteLength;

    DWORD  CounterNameTitleIndex;

    LPWSTR CounterNameTitle;

    DWORD  CounterHelpTitleIndex;

    LPWSTR CounterHelpTitle;

    DWORD  DefaultScale;

    DWORD  DetailLevel;

    DWORD  CounterType;

    DWORD  CounterSize;

    DWORD  CounterOffset;

} PERF_COUNTER_DEFINITION;

Members

ByteLength

Contains the length, in bytes, of this structure.

CounterNameTitleIndex

Contains the index of the counter name in the title database of the registry.

CounterNameTitle

Points to the name of the counter. This member contains NULL, initially, but it can contain a pointer to the actual string once the string is located.

CounterHelpTitleIndex

Contains the index to the counter’s Help title in the title database of the registry.

CounterHelpTitle

Points to the title of Help. This member contains NULL, initially, but it can contain a pointer to the actual string once the string is located.

DefaultScale

Specifies the power of 10 by which to scale a chart line, assuming the vertical axis is 100. If this value is zero, the scale value is 1; if this value is 1, the scale value is 10; if this value is −1, the scale value is .10; and so on.

DetailLevel

Specifies the level of detail for the counter. Applications use this value to control display complexity. This member can be one of the following values:

Value	Meaning
PERF_DETAIL_NOVICE	The data can be understood by the uninformed user.
PERF_DETAIL_ADVANCED	The data is designed for the advanced user.
PERF_DETAIL_EXPERT	The data is designed for the expert user.
PERF_DETAIL_WIZARD	The data is designed for the system designer.
CounterType

Specifies the type of counter. This member is some combination of the following values.

These values indicate the counter’s data size:

Value	Meaning
PERF_SIZE_DWORD	The counter data is a doubleword.
PERF_SIZE_LARGE	The counter data is a large integer.
PERF_SIZE_ZERO	The counter data is a zero-length field.
PERF_SIZE_VARIABLE_LEN	The size of the counter data is in the CounterSize member.
These values indicate the additional contents of this member:

Value	Meaning
PERF_TYPE_NUMBER	The counter data is a number value but not a counter.
PERF_TYPE_COUNTER	The counter data is an increasing numeric value.
PERF_TYPE_TEXT	The counter data is a text field.
PERF_TYPE_ZERO	The counter data is always zero.
If PERF_TYPE_NUMBER is specified, one of these values is also specified to indicate the format of the number:

Value	Meaning
PERF_NUMBER_HEX	The counter data should be displayed as a hexadecimal value.
PERF_NUMBER_DECIMAL	The counter data should be displayed as a decimal value.
PERF_NUMBER_DEC_1000	The counter data should be divided by 1000 and displayed as a decimal value.
If PERF_TYPE_COUNTER is specified, one of these values is also specified to indicate the type of counter:

Value	Meaning
PERF_COUNTER_VALUE	The counter value is valid without additional calculation; that is, it should be displayed as is.
PERF_COUNTER_RATE	The counter value should be divided by the elapsed time.
PERF_COUNTER_FRACTION	The counter value should be divided by the base value indicated by the next counter if it is of type PERF_COUNTER_BASE or by the value of the counter subtype.
PERF_COUNTER_BASE	The counter value is the base value to use in fractions.
PERF_COUNTER_ELAPSED	The counter value is a start time to be subtracted from the current time.
PERF_COUNTER_QUEUELEN	The performance application should use the Queuelen counter — that is, the Queue Length Space-Time Product formula. The next counter is the number currently in the queue. Multiply it by the current time (units specified by this counter’s subtype). Add the product to the original value of the counter. To obtain the average queue length, divide the result of the addition by the delta time.
PERF_COUNTER_HISTOGRAM	The counter value begins or ends a histogram.
If PERF_TYPE_COUNTER is specified, one of these values is also specified to indicate the subtype of counter:

Value	Meaning
PERF_TIMER_TICK	The frequency of the high-resolution performance counter should be used as the base.
PERF_TIMER_100NS	The time base units of the 100-nanosecond timer should be used as the base.
PERF_OBJECT_TIMER	The object-timer frequency should be used as the base unit. This value is system-defined in this counter’s PERF_OBJECT_TYPE definition.
If PERF_TYPE_TEXT is specified, one of these values is also specified to indicate the type of text:

Value	Meaning
PERF_TEXT_UNICODE	The counter data contains Unicode text.
PERF_TEXT_ASCII	The counter data contains ASCII text.
These values indicate how to use the counter data in a calculation:

Value	Meaning
PERF_DELTA_COUNTER	The difference between the previous counter value and the current counter value is computed before proceeding.
PERF_DELTA_BASE	The difference between the previous base value and the current base value is computed before proceeding.
PERF_INVERSE_COUNTER	After other calculations, the counter should be inverted before displaying or converting to a percentage.
PERF_MULTI_COUNTER	This value is a sum of counters from several sources, the number of which is indicated by the next counter.
These values indicate the display suffix of the counter data:

Value	Meaning
PERF_DISPLAY_NO_SUFFIX	There is no display suffix.
PERF_DISPLAY_PER_SEC	The display suffix is ‘/sec’.
PERF_DISPLAY_PERCENT	The display suffix is ‘%’.
PERF_DISPLAY_SECONDS	The display suffix is ‘secs’.
PERF_DISPLAY_NOSHOW	The counter value should not be displayed.
CounterSize

Specifies the counter size, in bytes.

CounterOffset

Specifies the offset from the start of the PERF_COUNTER_BLOCK structure to the first byte of this counter.

Remarks

This structure is part of the performance data provided by the RegQueryValueEx function when the HKEY_PERFORMANCE_DATA key is used.

See Also

RegQueryValueEx


PERF_DATA_BLOCK

The PERF_DATA_BLOCK structure describes the performance data provided by RegQueryValueEx function. The data starts with a PERF_DATA_BLOCK structure and is followed by a PERF_OBJECT_TYPE structure and other object-specific data for each type of object monitored.

typedef struct _PERF_DATA_BLOCK { // pdb

    WCHAR         Signature[4];

    DWORD         LittleEndian;

    DWORD         Version;

    DWORD         Revision;

    DWORD         TotalByteLength;

    DWORD         HeaderLength;

    DWORD         NumObjectTypes;

    DWORD         DefaultObject;

    SYSTEMTIME    SystemTime;

    LARGE_INTEGER PerfTime;

    LARGE_INTEGER PerfFreq;

    LARGE_INTEGER PerfTime100nSec;

    DWORD         SystemNameLength;

    DWORD         SystemNameOffset;

} PERF_DATA_BLOCK;

Members

Signature

Contains the Unicode string PERF.

LittleEndian

Contains zero if the processor is big endian and one if it is little endian.

Version

Contains the version of the performance (PERF_) structures. This member is greater than or equal to one.

Revision

Contains the revision of the performance (PERF_) structures. This member is greater than or equal to zero.

TotalByteLength

Contains the total length, in bytes, of the performance data.

HeaderLength

Contains the length, in bytes, of this structure.

NumObjectTypes

Contains the number of object types being monitored.

DefaultObject

Contains the object title index of the default object whose performance data is to be displayed. This member can be −1 to indicate that no data is to be displayed.

SystemTime

Contains the time when the system is monitored. This member is in Coordinated Universal Time (UTC) format.

PerfTime

Contains the performance-counter value, in counts, for the system being monitored.

PerfFreq

Contains the performance-counter frequency, in counts per second, for the system being monitored.

PerfTime100nSec

Contains the performance-counter value, in 100 nanosecond units, for the system being monitored.

SystemNameLength

Contains the length, in bytes, of the system name.

SystemNameOffset

Contains the offset from the beginning of this structure to the name of the system being monitored.

See Also

PERF_OBJECT_TYPE, RegQueryValueEx


PERF_INSTANCE_DEFINITION

The PERF_INSTANCE_DEFINITION structure contains the instance-specific information for a block of performance data. There is one PERF_INSTANCE_DEFINITION structure for each instance specified in the PERF_OBJECT_TYPE structure.

typedef struct _PERF_INSTANCE_DEFINITION { // pid

    DWORD ByteLength;

    DWORD ParentObjectTitleIndex;

    DWORD ParentObjectInstance;

    DWORD UniqueID;

    DWORD NameOffset;

    DWORD NameLength;

} PERF_INSTANCE_DEFINITION;

Members

ByteLength

Specifies the length, in bytes, of this structure, including the subsequent name.

ParentObjectTitleIndex

Specifies the index of the name of the “parent” object in the title database. For example, if the object is a thread, the parent object type is a process, or if the object is a logical drive, the parent is a physical drive.

ParentObjectInstance

Specifies the index to an instance of the parent object type that is the parent of this instance. This member may be zero or greater.

UniqueID

Specifies the unique identifier used instead of the instance name. This member is PERF_NO_UNIQUE_ID if there is no such identifier.

NameOffset

Specifies the offset from the beginning of this structure to the Unicode name of this instance.

NameLength

Specifies the length, in bytes, of the instance name. This member is zero if the instance does not have a name.

See Also

PERF_OBJECT_TYPE


PERF_OBJECT_TYPE

The PERF_OBJECT_TYPE structure describes object-specific performance information. This structure is followed by a list of PERF_COUNTER_DEFINITION structures, one for each counter defined for the type of object.

typedef struct _PERF_OBJECT_TYPE {  // pot

    DWORD  TotalByteLength;

    DWORD  DefinitionLength;

    DWORD  HeaderLength;

    DWORD  ObjectNameTitleIndex;

    LPWSTR ObjectNameTitle;

    DWORD  ObjectHelpTitleIndex;

    LPWSTR ObjectHelpTitle;

    DWORD  DetailLevel;

    DWORD  NumCounters;

    DWORD  DefaultCounter;

    DWORD  NumInstances;

    DWORD  CodePage;

    LARGE_INTEGER PerfTime;

    LARGE_INTEGER PerfFreq;

} PERF_OBJECT_TYPE;

Members

TotalByteLength

Contains the length, in bytes, of the object-specific data. This value includes this structure, the PERF_COUNTER_DEFINITION structures, and the PERF_INSTANCE_DEFINITION and PERF_COUNTER_BLOCK structures for each instance. This member specifies the offset from the beginning of this structure to the next PERF_OBJECT_TYPE structure if one exists.

DefinitionLength

Contains the length, in bytes, of the object-specific data. This value includes this structure and the PERF_COUNTER_DEFINITION structures for this object. This member is the offset from the beginning of the PERF_OBJECT_TYPE structure to the first PERF_INSTANCE_DEFINITION structure or to the PERF_COUNTER_DEFINITION structures if there is no instance data.

HeaderLength

Contains the length, in bytes, of this structure. This member is the offset to the first PERF_COUNTER_DEFINITION structure for this object.

ObjectNameTitleIndex

Contains the index to the object’s name in the title database.

ObjectNameTitle

Points to the name of the object. This member initially contains NULL, but it can contain a pointer to the actual string once the string is located.

ObjectHelpTitleIndex

Contains the index to the object’s Help title in the title database.

ObjectHelpTitle

Points to the title of Help. This member initially contains NULL, but it can contain a pointer to the actual string once the string is located.

DetailLevel

Specifies the level of detail. Applications use this value to control display complexity. This value is the minimum detail level of all the counters for a given object. This member can be one of the following values:

Detail level	Meaning
PERF_DETAIL_NOVICE	No technical ability is required to understand the counter data.
PERF_DETAIL_ADVANCED	The counter data is provided for advanced users.
PERF_DETAIL_EXPERT	The counter data is provided for expert users.
PERF_DETAIL_WIZARD	The counter data is provided for system designers.
NumCounters

Specifies the number of counters in each counter block. There is one counter block per instance.

DefaultCounter

Specifies the default counter whose information is to be displayed when this object is selected. This member is typically greater than or equal to zero. However, this member may be −1 to indicate that there is no default.

NumInstances

Specifies the number of object instances for which counters are being provided.

CodePage

Specifies the code page. This member is zero if the instance strings are in Unicode. Otherwise, this member is the code-page identifier of the instance names.

PerfTime

Specifies the current value, in counts, of the high-resolution performance counter.

PerfFreq

Specifies the current frequency, in counts per second, of the high-resolution performance counter.

Remarks

If there is only one instance of the object type, the counter definitions are followed by a single PERF_COUNTER_BLOCK structure. This structure is followed by data for each counter. (The PERF_COUNTER_BLOCK structure contains the total length of the structure and the counter data that follows it.)

If there is more than one instance of the object type, the list of counter definitions is followed by a PERF_INSTANCE_DEFINITION structure and a PERF_COUNTER_BLOCK structure for each instance. The PERF_INSTANCE_DEFINITION structure includes the name, the identifier, and the name of the parent of the instance.

Following the counter data, there is a PERF_INSTANCE_DEFINITION structure and a PERF_COUNTER_BLOCK structure for each instance specified in the PERF_DATA_BLOCK structure that begins the performance-data area.

See Also

PERF_COUNTER_BLOCK, PERF_COUNTER_DEFINITION, PERF_INSTANCE_DEFINITION


Performance Data Helper

You can use the performance data provided by applications, services, and drivers to determine system bottlenecks and fine-tune system and application performance. The easiest way to display the performance data is to use the Performance Monitor application located in the Administrative Tools group.

If you need to collect performance data for your application, the easiest way to do this is to use the interface provided by the Performance Data Helper (PDH) interface. Applications that need more control over performance data collection can use the registry interface directly. This is the method that is used by the functions in PDH.DLL and by the Performance Monitor. It is more efficient for the Performance Monitor to use the registry interface, because it displays counters grouped by object. If you are retrieving individual counters, rather than a group of counters from a particular object, it is just as efficient to use the PDH interface.

This overview discusses both interfaces.

•	The PDH Interface

•	The Registry Interface

In addition, this overview discusses how to add your own performance counters, by creating an extensible performance DLL. For more information, see Adding Performance Counters.


The PDH Interface

•	Collecting Performance Data.

•	Checking PDH Return Values

•	Enumerating Process Objects Using PDH


Collecting Performance Data

PDH functions work with queries and counters. A query is a set of performance counters that are grouped together so that you can collect their data at the same time. A counter is a performance data item stored in the Windows NT Performance Registry. You can call the PdhBrowseCounters function to display the following PDH dialog box, which lets you browse the available counters.

For more information on counters, see Performance Objects and Counters.

A query can contain one or more counters, and a counter can be contained in more than one query. To use PDH, you must create queries and add counters to them, as shown in the following sections.

•	Creating a query

•	Collecting data

•	Displaying data

•	Ending data collection


Creating a Query

To create a new query, call the PdhOpenQuery function. The function returns a handle to the query to be used in other PDH function calls. You can create multiple queries to be used in your program.

After you create a query, call the PdhAddCounter function to add a counter to the query. Call PdhAddCounter for each counter to be added to the query. You can use one of the following methods to determine which counters to use.

•	Hard-code the counter name in the call to PdhAddCounter. Use this method if you always monitor the same counter.

•	Read the name from the registry or an initialization file. Use this method if the set of counters you monitor can change.

•	Call the PdhBrowseCounters function to display the PDH browse dialog box. The dialog box allows the user to browse and select performance counters. The function returns one or more counter path strings for use in a query. If you add the counter returned by PdhBrowseCounters to a query, you can use the PdhRemoveCounter function to remove the counter from the query.

Counter Paths

The counter names used by PDH are expressed as counter paths. A counter path uses a collection of hierarchical elements to describe a counter. In the same way that a file path includes drives, directories, subdirectories, and file names, a counter path includes machines, objects, instances, and counter names. The syntax for a counter path is:

\\Machine\PerfObject(ParentInstance/ObjectInstance#InstanceIndex)\Counter

The \\Machine component is optional; it specifies the name of the machine. If you do not supply this component, PDH uses the local machine name. Therefore, a single path string works on any machine that supports the counter.

The \PerfObject component is required; it specifies the performance object that contains the performance counter. These objects are listed in the PDH browse dialog box and in Performance Monitor Add To Chart dialog box, in the Objects combo box. If this object has a variable list of instances, then you must also specify an instance string.

The (ParentInstance/ObjectInstance#InstanceIndex) component is only required if the object supports multiple instances. If the instance supports a variable list of instances, then you must specify an instance string. The format of the string depends on the object type. If the object has simple instances, then the format is just the instance name enclosed in parentheses. For example:

(Explorer)

If the instance of this object requires a parent instance name as well, then the parent instance name must come before the object instance, and be separated by a forward slash character. For example:

(Explorer/0)

If the object has multiple instances that have the same name string, they can be indexed sequentially by specifying the instance index prefixed by a pound sign. Instance indexes are 0-based, so all instances have an implicit “0” index. For example:

(Explorer/0#1)

The \Counter component is required; it specifies the performance counter. The counter names are displayed in the PDH browse dialog box and in the Performance Monitor Add To Chart dialog box, in the Counters list box. The counters associated with the selected object are displayed.

The following are two common counters in the PDH counter path format:

\Processor(0)\% Processor Time

\System\% Total Processor Time


Collecting Data

After you have created a query and added counters to it, call the PdhCollectQueryData function to retrieve the current raw data for all counters in the query. Many counters, such as rate counters, require the following two data samples before a valid data value can be determined.

•	Call PdhCollectQueryData before entering the section of code that you are measuring, to provide a starting value.

•	Call PdhCollectQueryData again after exiting the section of code that you are measuring, to get the ending value.


Displaying Data

The raw value of many counters is not what the user would expect to see. To get the information in the form described by most counter names, you need to compute the displayable value based on this raw data. PDH does this for you. For example, the Page Faults/Sec counter simply counts page faults, so if you view the raw data, you see a running total of page faults. To get the rate implied by the counter name, page faults per second, you need to call the PdhGetFormattedCounterValue function. In this case, the function divides the difference between two samples by the time between the samples.

The PdhGetFormattedCounterValue function performs its computations on the most recent sample. If you need to recalculate and redisplay a sample, you must store the raw data and then call the PdhCalculateCounterFromRawValue function to perform the calculation on the stored data.


Displaying Statistical Data

Calculating statistical values can be difficult, because many counter values are the result of a change over time. The PDH provides functions that perform calculations (such as minimum, maximum, and average values) on the raw counter data for you.

After you have retrieved the raw data for a counter, call the PdhComputeCounterStatistics function to perform the necessary calculations on the raw data.


Ending Data Collection

After you are finished collecting data for a query, call the PdhCloseQuery function to close the query and release all allocated system resources. The function closes all counter handles associated with the query.


Checking PDH Return Values

The return value of PDH functions indicates the success or error of the function call, which is distinct from the status of the counter data. Always check the CStatus member of a counter value returned in the PDH structures to ensure that the data returned is valid before you use it. If the value of the CStatus member does not indicate success, do not use the data. The following are the possible status values for counters:

PDH_CSTATUS_NO_MACHINE

PDH was unable to connect to the machine specified in the counter path. If this status is returned when the counter is being added, the counter is not completely initialized. Each time the query is updated, PDH retries the connection. When the connection is established, normal data collection resumes.

PDH_CSTATUS_NO_OBJECT

The specified machine was found, but no matching performance object was found on that machine. If this status is returned when the counter is being added, the specified counter is not included in the query. If this status is returned by an active counter, the data for that counter is invalid. Each time the data is requested, PDH tries to obtain this counter data.

PDH_CSTATUS_NO_INSTANCE

The specified instance was not found in the object. If this status is returned while the counter is being added to the query, the counter is successfully added to the query, but no data is available until the specific instance appears and a successful status is returned.

PDH_CSTATUS_NO_COUNTER

The specified counter was not found in the specified object. If this status is returned when the counter is being added, then the counter is not added to the query. If this status is returned after a data update, the data for that counter is invalid. Each time the data is requested, PDH tries to obtain this counter data.

PDH_CSTATUS_INVALID_DATA

The counter was successfully found, but the data returned is not valid. One possible cause for this value is when the data of a normally increasing counter is less than the previous value. Another possible cause is a system timer that is not correct.

PDH_CSTATUS_VALID_DATA

The data for the counter was returned successfully, but is unchanged from the last time the counter was read.

PDH_CSTATUS_NEW_DATA

The data for the counter was returned successfully and is different from the last time the counter was read. PDH_CSTATUS_NEW_DATA can be returned on a rate counter even if the resulting rate is the same as the last sample. This is because the raw data value that is used in the determination of this status value has changed, not the computed rate.

PDH_CSTATUS_NO_COUNTERNAME

No counter path was specified.

PDH_CSTATUS_BAD_COUNTERNAME

The counter path format is incorrect.


Enumerating Process Objects Using PDH

The example in this topic uses the PDH interface to enumerate the process objects on the system.

#ifdef UNICODE

#ifndef _UNICODE

#define _UNICODE  1

#endif

#define tmain     wmain

#else

#define tmain     main

#endif

// This program only needs the essential windows header files.

#define WIN32_LEAN_AND_MEAN 1

#include <windows.h>

#include <winperf.h>

#include <malloc.h>

#include <stdio.h>

#include <tchar.h>

#include <pdh.h>

int

tmain ()

{

    PDH_STATUS  pdhStatus               = ERROR_SUCCESS;

    LPTSTR      szCounterListBuffer     = NULL;

    DWORD       dwCounterListSize       = 0;

    LPTSTR      szInstanceListBuffer    = NULL;

    DWORD       dwInstanceListSize      = 0;

    LPTSTR      szThisInstance          = NULL;

// Determine the required buffer size for the data.

    pdhStatus = PdhEnumObjectItems (

        NULL,                   // reserved

        NULL,                   // local machine

        TEXT("Process"),        // object to enumerate

        szCounterListBuffer,    // pass in NULL buffers

        &dwCounterListSize,     // an 0 length to get

        szInstanceListBuffer,   // required size

        &dwInstanceListSize,    // of the buffers in chars

        PERF_DETAIL_WIZARD,     // counter detail level

        0);

    if (pdhStatus == ERROR_SUCCESS)

    {

    // Allocate the buffers and try the call again.

        szCounterListBuffer = (LPTSTR)malloc (

            (dwCounterListSize * sizeof (TCHAR)));

        szInstanceListBuffer = (LPTSTR)malloc (

            (dwInstanceListSize * sizeof (TCHAR)));

        if ((szCounterListBuffer != NULL) &&

            (szInstanceListBuffer != NULL))

        {

            pdhStatus = PdhEnumObjectItems (

                NULL,   // reserved

                NULL,   // local machine

                TEXT("Process"), // object to enumerate

                szCounterListBuffer,    // pass in NULL buffers

                &dwCounterListSize,     // an 0 length to get

                szInstanceListBuffer,   // required size

                &dwInstanceListSize,    // of the buffers in chars

                PERF_DETAIL_WIZARD,     // counter detail level

                0);

            if (pdhStatus == ERROR_SUCCESS)

            {

                _tprintf (TEXT("\nRunning Processes:"));

            // Walk the return instance list.

                for (szThisInstance = szInstanceListBuffer;

                     *szThisInstance != 0;

                     szThisInstance += lstrlen(szThisInstance) + 1)

                {

                     _tprintf (TEXT("\n  %s"), szThisInstance);

                }

            }

        }

        else

        {

            _tprintf (TEXT("\nPROCLIST: unable to allocate buffers"));

        }

        if (szCounterListBuffer != NULL)

            free (szCounterListBuffer);

        if (szInstanceListBuffer != NULL)

            free (szInstanceListBuffer);

    }

    else

    {

        _tprintf(TEXT("\nUnable to determine required buffer size."));

    }

    return 0;

}


The Registry Interface

•	Performance Objects and Counters

•	The HKEY_PERFORMANCE_DATA_KEY

•	Performance Data Format

•	Navigating the Performance Data

•	Retrieving Counter Names and Explanations

•	Retrieving Selected Data

•	Displaying Object, Instance, and Counter Names

•	Adding Performance Counters


Performance Objects and Counters

The performance data is grouped by performance object to which it is related. A performance object consists of performance counters, which are used to measure various aspects of system, application, or device performance. For example, the Processor object includes the Processor Time counter to measure the percentage of time the processor spends executing threads that are not idle and the Interrupts/sec counter to measure the number of device interrupts the processor receives.

An instance is a unique copy of a particular object type. Not all object types support multiple instances. For example, a Memory object has only one instance, because a system has one memory. However, the Processor object supports multiple instances, because a system can have one or more processors.

Most performance counters in Windows NT increment and are never cleared. Therefore, to obtain performance data, use the following steps.

•	Take a snapshot of the relevant performance counters at the beginning of a time interval.

•	Take a snapshot of the same performance counters at the end of the time interval.

•	Find the difference between the counter values in the snapshots and apply the appropriate calculation function.

For a list of the system performance objects and performance counters, see Windows NT Performance Counters.


The HKEY_PERFORMANCE_DATA Key

The performance data is accessed through the registry key HKEY_PEFORMANCE_DATA. Each software component creates keys for its objects and counters when it is installed and writes counter data while it is executing. You can access this data as you would access any other registry data, using the registry functions. However, although you use the registry to collect performance data, the data is not stored in the registry database. Instead, calling the registry functions with the HKEY_PEFORMANCE_DATA key causes the system to collect the data from the appropriate system object managers.

To obtain performance data from the local system, use the RegQueryValueEx function, with the HKEY_PERFORMANCE_DATA key. The first call opens the key; you do not need to explicitly open the key first. However, be sure to use the RegCloseKey function to close the handle to the key when you are finished obtaining performance data. The user cannot install or remove a software component while its performance data is in use.

To obtain performance data from a remote system, you must use the RegConnectRegistry function, with the computer name of the remote system and the HKEY_PERFORMANCE_DATA key. This call retrieves a key representing the performance data for the remote system. To retrieve the data, call RegQueryValueEx using this key, rather than the HKEY_PERFORMANCE_DATA key.


Performance Data Format

The format of the data retrieved by the RegQueryValueEx function begins with a single header structure, PERF_DATA_BLOCK. The PERF_DATA_BLOCK structure describes the system and the performance data. The PERF_DATA_BLOCK structure is followed by a list of object information blocks (one per object).

PERF_DATA_BLOCK

Object 1 information

Object 2 information

Object 3 information

…

Object X information

Basic Performance Data Structure

Each object information block contains a PERF_OBJECT_TYPE structure, which describes the performance data for the object. The PERF_OBJECT_TYPE structure is followed by a list of PERF_COUNTER_DEFINITION structures, one for each counter defined for the object. For an object with only one instance, the list of PERF_COUNTER_DEFINITION structures is followed by a single PERF_COUNTER_BLOCK structure, followed by the data for each counter.

PERF_OBJECT_TYPE

PERF_COUNTER_DEFINITION 1

PERF_COUNTER_DEFINITION 2

PERF_COUNTER_DEFINITION 3

…

PERF_COUNTER_DEFINITION Y

PERF_COUNTER_BLOCK

Counter 1 data

Counter 2 data

Counter 3 data

…

Counter Y data

Structure of Object Information Block (One Instance)

For an object type that supports multiple instances, the list of PERF_COUNTER_DEFINITION structures is followed by a list of instance information blocks (one for each instance).

PERF_OBJECT_TYPE

PERF_COUNTER_DEFINITION 1

PERF_COUNTER_DEFINITION 2

PERF_COUNTER_DEFINITION 3

…

PERF_COUNTER_DEFINITION Y

Instance 1 Information

Instance 2 Information

Instance 3 Information

…

Instance Z Information

Structure of Object Information Block (Multiple Instances)

Each instance information block contains a PERF_INSTANCE_DEFINITION structure and a PERF_COUNTER_BLOCK structure.

PERF_INSTANCE_DEFINITION

Instance name

PERF_COUNTER_BLOCK

Counter Data 1

Counter Data 2

Counter Data 3

…

Counter Data Y

Structure of Instance Information Block


Navigating the Performance Data

The performance data contains information for a variable number of object types, instances per object, and counters per object type. Therefore, the number and size of blocks in the performance data varies. To ensure that your application correctly receives the performance data, you must use the offsets included in the performance structures to navigate through the data. Every offset is a count of bytes relative to the structure containing it.

For an example that navigates the registry, see Displaying Object, Instance, and Counter Names.

Note  The reason the system uses offsets instead of pointers is that pointers are not valid across process boundaries. The addresses that the process that installs the counters would store would not be valid for the process that reads the counters.


Retrieving Counter Names and Explanations

Object type names, counter names, object explanations, and counter explanations are not made directly available in the performance data structures. Instead, the performance data structures contain indices you can use to locate where the names and explanations for each object and counter can be found. The ObjectNameTitleIndex and ObjectHelpTitleIndex members of the PERF_OBJECT_TYPE structure contain the indices to the object name and explanation, respectively. The CounterNameTitleIndex and CounterHelpTitleIndex members of the PERF_COUNTER_DEFINITION structure contain the indices to the counter name and explanation, respectively.

To access the names and explanations, read the Counter and Help values in the following registry key.

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT
    \CurrentVersion\Perflib\langid

The langid is the ASCII representation of the 3-digit hexadecimal language identifier. For example, the U.S. English langid is 009. In a non-English version of Windows NT, counters are stored in both the native language of the system and in English.

The data is stored as MULTI_SZ strings. This data type consists of a list of Unicode strings, each terminated with UNICODE_NULL. The last string is followed by an additional UNICODE_NULL. The strings are listed in pairs. The first string of each pair is the Unicode string of the index, and the second string is the actual name of the index. The Counter data uses only even-numbered indexes, while the Help data has odd-numbered indexes. For example, the Counter data contains the following object and counter name strings.

2    System

4    Memory

6    % Processor Time

The Help data contains the following counter explanations.

3    The System object type includes those counters that...

5    The Memory object type includes those counters that...

7    Processor Time is expressed as a percentage of the...

To retrieve a name or explanation for an object type or counter, given its index, an application should perform the following steps.

1.	If the system is remote, call the RegConnectRegistry function.

2.	Use the RegOpenKeyEx function to open the registry key containing the name and explanation text.

3.	Use the RegQueryValueEx function, specifying either Counter or Help as the name of the value to query.

4.	Convert the index into Unicode or ASCII, depending on whether your application is Unicode or ASCII.

5.	Search the MULTI_SZ data for the appropriate index.

6.	Retrieve the string following the matching index. The string contains the name or explanation.

If you are going to be looking up a number of counters, you should build a table for faster and easier lookup. For an example, see Displaying Object, Instance, and Counter Names.


Retrieving Selected Data

Retrieving the performance data is not without cost to the system, especially in terms of processor and memory requirements. In cases where your application does not need all the performance data, you can use the lpszValueName parameter of the RegQueryValueEx function to indicate the amount of information to retrieve. The following table lists the values you can specify for lpszValueName. Note that the value strings are case-sensitive, and if a string includes more than one word, your words must be separated by a space.

Value	Description
Global	The function returns all data for counters on the local computer, except those included in the Costly category.
nnn xx yyy	Each of these is a Unicode string representing the decimal value for an object name index. The function only returns data about the specified object types on the local computer. For example, if your program were to use “2 4”, the System and Memory objects would be retrieved. Note that more object types can be returned than are requested. This occurs when the requested object type depends on another object type. For example, processes are needed to identify threads, so information for the Process object is also returned when you request information for the Thread object.
Foreign ssss	The string ssss is the name of a foreign computer, such as a Novell NetWare server or a UNIX system. If your system is capable of collecting data from a foreign computer, the function returns all data for counters on the foreign computer. Try this approach if the RegConnectRegistry function fails to connect to a foreign computer.
Foreign ssss nnn xx yyy	This format combines Foreign ssss and nnn xx yyy.
Costly	The function returns data for object types whose data is expensive to collect in terms of processor time or memory usage. Start a worker thread if your application needs to respond to the user during this lengthy data collection.


Calculations for Raw Counter Data

This section lists the types of performance counters and the calculations that the Performance Monitor uses to convert the raw data to the information you would expect from the counter name. The counter types and calculations are defined in WINPERF.H. For the calculations, the following key applies:

Symbol	Definition
N	Numerator
D	Denominator
TB	Time base (indicates the units of raw data if not used in calculation)
B	Base count (number of entries)
N0	Oldest or first sample taken (of the numerator in this case; D0 would be of the denominator)
N1	More recent sample
Nx	Most recent sample in calculation array (for average calculation)
PERF_100NSEC_MULTI_TIMER  Timer for when multiple instances are in use, so the result can exceed 100%. The number of instances is in the next counter.

Element	Value
Numerator	CounterData
Denominator	100NsTime
Time base	100Ns
Calculation	(N1-N0)/(D1-D0)
Average function	(Nx-N0)/(Dx-D0)
PERF_100NSEC_MULTI_TIMER_INV  The inverse of the timer for multiple instances (when the object is not in use).

Element	Value
Numerator	CounterData
Denominator	100NsTime
Time base	100Ns
Calculation	(B-((N1-N0)/(D1-D0)))
Average function	(B-((Nx-N0)/(Dx-D0)))
PERF_100NSEC_TIMER  Timer for when the object is in use.

Element	Value
Numerator	CounterData
Denominator	100NsTime
Time base	100Ns
Calculation	(N1-N0)/(D1-D0)
Average function	(Nx-N0)/(Dx-D0)
PERF_100NSEC_TIMER_INV  The inverse of the timer (when the object is not in use).

Element	Value
Numerator	CounterData
Denominator	100NsTime
Time base	100Ns
Calculation	(1-((N1-N0)/(D1-D0)))
Average function	(1-((Nx-N0)/(Dx-D0)))
PERF_AVERAGE_BASE  Used as the denominator in the computation of time or count averages.

Element	Value
Numerator	N/A
Denominator	N/A
Time base	N/A
Calculation	N/A
Average function	N/A
PERF_AVERAGE_BULK  A count which usually gives the bytes per operation when divided by the number of operations.

Element	Value
Numerator	CounterData
Denominator	BaseData
Time base	N/A
Calculation	(N1-N0)/(D1-D0)
Average function	(Nx-N0)/(Dx-D0)
PERF_AVERAGE_TIMER  A timer which usually gives time per operation when divided by the number of operations.

Element	Value
Numerator	CounterData
Denominator	BaseData
Time base	PerfFreq
Calculation	((N1-N0)/TB)/(D1-D0)
Average function	((Nx-N0)/TB)/(Dx-D0)
PERF_COUNTER_BULK_COUNT  Used to count byte transmission rates.

Element	Value
Numerator	CounterData
Denominator	PerfTime
Time base	PerfFreq
Calculation	(N1-N0)/((D1-D0)/TB)
Average function	(Nx-N0)/((Dx-D0)/TB)
PERF_COUNTER_COUNTER  Rate of counts. The most common counter.

Element	Value
Numerator	CounterData
Denominator	PerfTime
Time base	PerfFreq
Calculation	(N1-N0)/((D1-D0)/TB)
Average function	(Nx-N0)/((Dx-D0)/TB)
PERF_COUNTER_DELTA  Difference between two counters.

Element	Value
Numerator	CounterData
Denominator	N/A
Time base	N/A
Calculation	(N1-N0)
Average function	(Nx-N0)/x
PERF_COUNTER_LARGE_DELTA  Difference between two counters.

Element	Value
Numerator	CounterData
Denominator	N/A
Time base	N/A
Calculation	(N1-N0)
Average function	(Nx-N0)/x
PERF_COUNTER_LARGE_QUEUELEN_TYPE  Average count per time interval.

Element	Value
Numerator	CounterData
Denominator	PerfTime
Time base	PerfFreq
Calculation	(N1-N0)/(D1-D0)
Average function	(Nx-N0)/(Dx-D0)
PERF_COUNTER_LARGE_RAWCOUNT  Instantaneous counter value.

Element	Value
Numerator	CounterData
Denominator	N/A
Time base	N/A
Calculation	(N0)
Average function	SUM(N)/x
PERF_COUNTER_LARGE_RAWCOUNT_HEX  Instantaneous counter value, as a hexadecimal number.

Element	Value
Numerator	CounterData
Denominator	N/A
Time base	N/A
Calculation	(N0)
Average function	SUM(N)/x
PERF_COUNTER_MULTI_BASE  Base for MULTI counters.

Element	Value
Numerator	N/A
Denominator	N/A
Time base	N/A
Calculation	N/A
Average function	N/A
PERF_COUNTER_MULTI_TIMER  Timer for when multiple instances are in use, so the result can exceed 100%. The number of instances is in the next counter.

Element	Value
Numerator	CounterData
Denominator	PerfTime
Time base	PerfFreq
Calculation	(N1-N0)/(D1-D0)
Average function	(Nx-N0)/(Dx-D0)
PERF_COUNTER_MULTI_TIMER_INV  The inverse of the timer for multiple instances (when the object is not in use).

Element	Value
Numerator	CounterData
Denominator	PerfTime
Time base	PerfFreq
Calculation	(B-((N1-N0)/(D1-D0)))
Average function	(B-((Nx-N0)/(Dx-D0)))
PERF_COUNTER_NODATA  There is no data for this counter.

Element	Value
Numerator	0
Denominator	N/A
Time base	N/A
Calculation	0
Average function	0
PERF_COUNTER_QUEUELEN_TYPE  Average count per time interval.

Element	Value
Numerator	CounterData
Denominator	PerfTime
Time base	PerfFreq
Calculation	(N1-N0)/(D1-D0)
Average function	(Nx-N0)/(Dx-D0)
PERF_COUNTER_RAWCOUNT  Instantaneous counter value.

Element	Value
Numerator	CounterData
Denominator	N/A
Time base	N/A
Calculation	(N0)
Average function	SUM(N)/x
PERF_COUNTER_RAWCOUNT_HEX  Instantaneous counter value, as a hexadecimal number.

Element	Value
Numerator	CounterData
Denominator	N/A
Time base	N/A
Calculation	(N0)
Average function	SUM(N)/x
PERF_COUNTER_TEXT  Indicates the data is not a counter, but is Unicode text.

Element	Value
Numerator	N/A
Denominator	N/A
Time base	N/A
Calculation	N/A
Average function	N/A
PERF_COUNTER_TIMER  The most common timer.

Element	Value
Numerator	CounterData
Denominator	PerfTime
Time base	PerfFreq
Calculation	(N1-N0)/(D1-D0)
Average function	(Nx-N0)/(Dx-D0)
PERF_COUNTER_TIMER_INV  The inverse of the timer (when the object is not in use).

Element	Value
Numerator	CounterData
Denominator	PerfTime
Time base	PerfFreq
Calculation	(1-((N1-N0)/(D1-D0)))
Average function	(1-((Nx-N0)/(Dx-D0)))
PERF_ELAPSED_TIME  The data is the start time of the item being measured. For display, subtract the start time from the snapshot time to yield the elapsed time. The PerfTime member of the PERF_OBJECT_TYPE structure contains the sample time. Use the PerfFreq member of the PERF_OBJECT_TYPE structure to convert the time into seconds.

Element	Value
Numerator	CounterData
Denominator	ObjectTime
Time base	ObjectFreq
Calculation	(D0-N0)/TB
Average function	(Dx-N0)/TB
PERF_RAW_BASE  Used as a base. Check that this value is greater than zero before dividing.

Element	Value
Numerator	N/A
Denominator	N/A
Time base	N/A
Calculation	N/A
Average function	N/A
PERF_RAW_FRACTION  Instantaneous value, to be divided by the base.

Element	Value
Numerator	CounterData
Denominator	BaseData
Time base	N/A
Calculation	(N0/D0)
Average function	SUM(N/D)/x
PERF_SAMPLE_BASE  Used as a base. Check that this value is greater than zero before dividing.

Element	Value
Numerator	N/A
Denominator	N/A
Time base	N/A
Calculation	N/A
Average function	N/A
PERF_SAMPLE_COUNTER  A count that is sampled on each sampling interrupt. Must be divided by the base.

Element	Value
Numerator	CounterData
Denominator	PerfTime
Time base	PerfFreq
Calculation	(N1-N0)/((D1-D0)/TB)
Average function	(Nx-N0)/((Dx-D0)/TB)
PERF_SAMPLE_FRACTION  A count that is either 1 or 0 on each sampling interrupt.

Element	Value
Numerator	CounterData
Denominator	BaseData
Time base	N/A
Calculation	(N1-N0)/(D1-D0)
Average function	(Nx-N0)/(Dx-D0)


Displaying Object, Instance, and Counter Names

The following example displays the index and name of each object, along with the indices and names of its counters.

The object and counter names are stored in the registry, by index. This example creates a function, GetNameStrings, to load the indices and names of each object and counter from the registry into an array, so that they can be easily accessed. GetNameStrings uses the following standard registry functions to access the data: RegOpenKey, RegCloseKey, RegQueryInfoKey, and RegQueryValueEx.

This example creates the following functions for navigating the performance data: FirstObject, FirstInstance, FirstCounter, NextCounter, NextInstance, and NextCounter. These functions navigate the performance data by using the offsets stored in the performance structures.

#include <windows.h>

#include <stdio.h>

#include <stdlib.h>

#include <malloc.h>

#include <string.h>

#define TOTALBYTES    8192

#define BYTEINCREMENT 1024

LPSTR lpNameStrings;

LPSTR *lpNamesArray;

/*****************************************************************

 *                                                               *

 * Functions used to navigate through the performance data.      *

 *                                                               *

 *****************************************************************/

PPERF_OBJECT_TYPE FirstObject( PPERF_DATA_BLOCK PerfData )

{

    return( (PPERF_OBJECT_TYPE)((PBYTE)PerfData +

        PerfData->HeaderLength) );

}

PPERF_OBJECT_TYPE NextObject( PPERF_OBJECT_TYPE PerfObj )

{

    return( (PPERF_OBJECT_TYPE)((PBYTE)PerfObj +

        PerfObj->TotalByteLength) );

}

PPERF_INSTANCE_DEFINITION FirstInstance( PPERF_OBJECT_TYPE PerfObj )

{

    return( (PPERF_INSTANCE_DEFINITION)((PBYTE)PerfObj +

        PerfObj->DefinitionLength) );

}

PPERF_INSTANCE_DEFINITION NextInstance(

    PPERF_INSTANCE_DEFINITION PerfInst )

{

    PPERF_COUNTER_BLOCK PerfCntrBlk;

    PerfCntrBlk = (PPERF_COUNTER_BLOCK)((PBYTE)PerfInst +

        PerfInst->ByteLength);

    return( (PPERF_INSTANCE_DEFINITION)((PBYTE)PerfCntrBlk +

        PerfCntrBlk->ByteLength) );

}

PPERF_COUNTER_DEFINITION FirstCounter( PPERF_OBJECT_TYPE PerfObj )

{

    return( (PPERF_COUNTER_DEFINITION) ((PBYTE)PerfObj +

        PerfObj->HeaderLength) );

}

PPERF_COUNTER_DEFINITION NextCounter(

    PPERF_COUNTER_DEFINITION PerfCntr )

{

    return( (PPERF_COUNTER_DEFINITION)((PBYTE)PerfCntr +

        PerfCntr->ByteLength) );

}

/*****************************************************************

 *                                                               *

 * Load the counter and object names from the registry to the    *

 * global variable lpNamesArray.                                 *

 *                                                               *

 *****************************************************************/

void GetNameStrings( )

{

    HKEY hKeyPerflib;      // handle to registry key

    HKEY hKeyPerflib009;   // handle to registry key

    DWORD dwMaxValueLen;   // maximum size of key values

    DWORD dwBuffer;        // bytes to allocate for buffers

    DWORD dwBufferSize;    // size of dwBuffer

    LPSTR lpCurrentString; // pointer for enumerating data strings

    DWORD dwCounter;       // current counter index

// Get the number of Counter items.

    RegOpenKeyEx( HKEY_LOCAL_MACHINE,

        "SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Perflib",

        0,

        KEY_READ,

        &hKeyPerflib);

    dwBufferSize = sizeof(dwBuffer);

    RegQueryValueEx( hKeyPerflib,

        "Last Counter",

        NULL,

        NULL,

        (LPBYTE) &dwBuffer,

        &dwBufferSize );

    RegCloseKey( hKeyPerflib );

// Allocate memory for the names array.

    lpNamesArray = malloc( (dwBuffer+1) * sizeof(LPSTR) );

// Open key containing counter and object names.

    RegOpenKeyEx( HKEY_LOCAL_MACHINE,

    "SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Perflib\\009",

        0,

        KEY_READ,

        &hKeyPerflib009);

// Get the size of the largest value in the key (Counter or Help).

    RegQueryInfoKey( hKeyPerflib009,

        NULL,

        NULL,

        NULL,

        NULL,

        NULL,

        NULL,

        NULL,

        NULL,

        &dwMaxValueLen,

        NULL,

        NULL);

// Allocate memory for the counter and object names.

    dwBuffer = dwMaxValueLen + 1;

    lpNameStrings = malloc( dwBuffer * sizeof(CHAR) );

// Read Counter value.

    RegQueryValueEx( hKeyPerflib009,

        "Counter",

        NULL,

        NULL,

        lpNameStrings, &dwBuffer );

// Load names into an array, by index.

    for( lpCurrentString = lpNameStrings; *lpCurrentString;

         lpCurrentString += (lstrlen(lpCurrentString)+1) )

    {

        dwCounter = atol( lpCurrentString );

        lpCurrentString += (lstrlen(lpCurrentString)+1);

        lpNamesArray[dwCounter] = (LPSTR) lpCurrentString;

    }

}

/*****************************************************************

 *                                                               *

 * Display the indices and/or names for all performance objects, *

 * instances, and counters.                                      *

 *                                                               *

 *****************************************************************/

void main()

{

    PPERF_DATA_BLOCK PerfData = NULL;

    PPERF_OBJECT_TYPE PerfObj;

    PPERF_INSTANCE_DEFINITION PerfInst;

    PPERF_COUNTER_DEFINITION PerfCntr, CurCntr;

    PPERF_COUNTER_BLOCK PtrToCntr;

    DWORD BufferSize = TOTALBYTES;

    DWORD i, j, k;

// Get the name strings through the registry.

    GetNameStrings( );

// Allocate the buffer for the performance data.

    PerfData = (PPERF_DATA_BLOCK) malloc( BufferSize );

    while( RegQueryValueEx( HKEY_PERFORMANCE_DATA,

                               "Global",

                               NULL,

                               NULL,

                               (LPBYTE) PerfData,

                               &BufferSize ) == ERROR_MORE_DATA )

    {

    // Get a buffer that is big enough.

        BufferSize += BYTEINCREMENT;

        PerfData = (PPERF_DATA_BLOCK) realloc( PerfData, BufferSize );

    }

// Get the first object type.

    PerfObj = FirstObject( PerfData );

// Process all objects.

    for( i=0; i < PerfData->NumObjectTypes; i++ )

    {

    // Display the object by index and name.

        printf( "\nObject %ld: %s\n", PerfObj->ObjectNameTitleIndex,

            lpNamesArray[PerfObj->ObjectNameTitleIndex] );

    // Get the first counter.

        PerfCntr = FirstCounter( PerfObj );

        if( PerfObj->NumInstances > 0 )

        {

        // Get the first instance.

            PerfInst = FirstInstance( PerfObj );

        // Retrieve all instances.

            for( k=0; k < PerfObj->NumInstances; k++ )

            {

            // Display the instance by name.

                printf( "\n\tInstance %S: \n",

                    (char *)((PBYTE)PerfInst + PerfInst->NameOffset));

                CurCntr = PerfCntr;

            // Retrieve all counters.

                for( j=0; j < PerfObj->NumCounters; j++ )

                {

                // Display the counter by index and name.

                    printf("\t\tCounter %ld: %s\n",

                        CurCntr->CounterNameTitleIndex,

                        lpNamesArray[CurCntr->CounterNameTitleIndex]);

                // Get the next counter.

                    CurCntr = NextCounter( CurCntr );

                }

            // Get the next instance.

                PerfInst = NextInstance( PerfInst );

            }

        }

        else

        {

        // Get the counter block.

            PtrToCntr = (PPERF_COUNTER_BLOCK) ((PBYTE)PerfObj +

                            PerfObj->DefinitionLength );

        // Retrieve all counters.

            for( j=0; j < PerfObj->NumCounters; j++ )

            {

            // Display the counter by index and name.

                printf( "\tCounter %ld: %s\n", PerfCntr->CounterNameTitleIndex,

                    lpNamesArray[PerfCntr->CounterNameTitleIndex] );

            // Get the next counter.

                PerfCntr = NextCounter( PerfCntr );

            }

        }

    // Get the next object type.

        PerfObj = NextObject( PerfObj );

    }

}


Adding Performance Counters

Windows NT provides a mechanism for you to add performance objects and counters for your application and other software components. Performance counters specific to your application can help you tune performance while you develop and debug the application. After your application is complete and installed on target systems, the counters can help system administrators adjust configurable settings for your application.

To add an extended object and its counters, use the following steps.

1.	Design the object types and counters for the application. See Object and Counter Design.

2.	Create an initialization (.INI) file containing the names and descriptions of the counter objects and counters. See Adding Counter Names and Descriptions to the Registry.

3.	Create a header (.H) file containing the relative offsets at which the counter objects and counters will be installed in the registry. See Adding Counter Names and Descriptions to the Registry.

4.	Set up the necessary performance monitoring entries in the registry. This includes the following steps.

a.	Create a registry key in the Services key for the application. If you do not have such a node, create it under the following registry key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services. Creating the Application’s Performance Key

b.	Use the lodctr utility with the .INI and .H files to install the information in the registry. This utility succeeds only if a performance key exists in the Services key for the application. See Adding Counter Names and Descriptions to the Registry.

5.	Create a performance DLL containing a set of exported functions that provide the link between the application and a performance monitoring application. See Creating the Performance DLL.

6.	Modify the application’s setup file to automate adding information to the registry (as described in step 4) and move your performance DLL to the system directory at setup.

To view an extended object, its functions, and its counter, use the extensible counter list utility (EXCTRLST.EXE). For more information, see ExCtrLst.


Object and Counter Design

A performance object is an entity for which performance data is available. Performance counters define the type of data that is available for a counter object. An application can provide information for multiple performance objects, each with one or more counters.

An application can also define objects that have multiple instances. For example, a SCSI application could use a single set of counter definitions to define a drive object with two counters, such as Bytes Read and Bytes Written. The performance DLL for the application could report performance data for each drive controlled by the application.

The Windows NT Performance Monitor can show some counters as rates, such as Page Faults/sec, as well as a raw count. This gives context to the users, so they do not have to compare data from different time intervals. However, you do not have to take this into account when you design a counter. You increment the counter and let the monitor application do the work of converting raw counts to a rate.

The method you use to collect the data can be as simple as incrementing a counter each time a particular routine in the application is called, or it can involve time-consuming calculations. Counters and timers should increment and never be cleared. Counters can wrap, as long as they do not wrap twice between snapshots. Your application can collect and store data during its normal execution, as long as it does not affect the its performance.

For some types of data, it may be more efficient or appropriate to collect the data on demand. In this situation, the performance DLL must communicate to the application that the data has been requested. For data that is expensive to collect (in terms of processor time or memory usage), consider collecting data only when the performance monitoring program requests Costly data. This allows a custom performance monitoring program to routinely request data for all counters that are not costly. The data can be requested only when needed. The Windows NT Performance Monitor does not collect Costly data.


Updating the Registry

There are several updates that you must make to the registry when you install or uninstall your performance DLL.

•	Creating the application’s performance key

•	Adding counter names and descriptions to the registry.

•	Removing counter names and descriptions from the registry.

•	Creating other registry entries


Creating the Application's Performance Key
Creating the Application’s Performance Key

An application that supports performance counters must have a Performance key under the Services key. The following example shows the values you should include for this key.

HKEY_LOCAL_MACHINE

    \SYSTEM

        \CurrentControlSet

            \Services

                \Application_Name

                    \Performance

                        Library = DLL_Name

                        Open = Open_Function_Name

                        Collect = Collect_Function_Name

                        Close = Close_Function_Name

The Library value provides the name of the performance DLL, and the Open, Collect, and Close values provide the names of the functions exported from the performance DLL. When a performance monitoring application requests performance data, the system uses these values to determine which performance DLLs to load and which DLL functions to call.


Adding Counter Names and Descriptions to the Registry

The names and descriptions of all performance objects and their counters are stored using the registry. You must add this information for the objects and counters you add to the system.

The following example shows the registry location where performance counter names and descriptions are stored.

HKEY_LOCAL_MACHINE

    \SOFTWARE

        \Microsoft

            \Windows NT

                \CurrentVersion

                    \Perflib

                        Last Counter = highest counter index

                        Last Help = highest help index

                        \009

                            Counter = 2 System 4 Memory ...

                            Help = 3 The System object type ...

                        \supported language, other than U.S. English

                            Counter = ...

                            Help = ...

To add names and descriptions of the objects and counters for your application, use the lodctr utility included with Windows NT. The lodctr utility takes strings from an .INI file and adds them to the Counter and Help values under the appropriate language subkeys. It also updates the Last Counter and Last Help values. In addition to adding values under the PerfLib key, the lodctr utility also adds the following value entries to the Services node for the application.

\HKEY_LOCAL_MACHINE

    \SYSTEM

Error! Bookmark not defined.        \CurrentControlSet

            \Services

                \ApplicationName

                    \Performance

                        First Counter = lowest counter index

                        First Help = lowest help index

                        Last Counter = highest counter index

                        Last Help = highest help index

Using lodctr

The command-line syntax for lodctr is:

lodctr MyApplication.ini

Initialization (.INI) File

The .INI file used by lodctr has the following format:

[info]

applicationname=ApplicationName

symbolfile=SymbolFile

// One key (value optional) for each language supported.

[languages]

langid=

 .

 .

 .

// Name and description for each counter or counter object

[text]

offset_langid_NAME=Name         // “Counter” name string.

offset_langid_HELP=Description  // "Help" description string.

 .

 .

 .

The .INI file entries are variables with the following meanings:

Variable	Description
ApplicationName	The name of the application found under the CurrentControlSet\Services key.
SymbolFile	An .H file containing symbolic offsets of counters. The performance DLL also uses the offsets in this file along with the First Counter and First Help Registry values to determine the indexes of the various counters and counter objects.
Langid	An ID corresponding to the language subkey in the Registry (for example, 009 for U.S. English).
Offset	A symbolic constant defined in SymbolFile. Offsets must be consecutive, even numbers beginning with zero. These offsets determine the order in which the counters are installed in the Counter and Help values in the registry.
The following is an example SymbolFile.

// SYMFILE.H

#define OBJECT_1    0

#define DEVICE_COUNTER_1    2

#define DEVICE_COUNTER_2    4

The following is an example .INI file.

// begin .INI file example

[info]

applicationname=ApplicationName

symbolfile=symfile.h

[languages]

009=English

011=OtherLanguage

[text]

OBJECT_1_009_NAME=Device Name

OBJECT_1_009_HELP=Displays performance statistics on Device Name

OBJECT_1_011_NAME=Device Name in other language

OBJECT_1_011_HELP=Displays performance of Device Name in other language

DEVICE_COUNTER_1_009_NAME=Counter A

DEVICE_COUNTER_1_009_HELP=Displays the current value of Counter A

DEVICE_COUNTER_1_011_NAME=Counter A in other language

DEVICE_COUNTER_1_011_HELP=Displays the value of Counter A in other language

DEVICE_COUNTER_2_009_NAME=Counter B

DEVICE_COUNTER_2_009_HELP=Displays the current rate of Device B

DEVICE_COUNTER_2_011_NAME=Counter B in other language

DEVICE_COUNTER_2_011_HELP=Displays the rate of Device B in other language

If you run lodctr to add counters for an application and the application does not have a Services key, lodctr returns without modifying the Perflib values.

Note  The loading function of LODCTR, LoadPerfCounterTextStrings, is declared in LOADPERF.H and exported from LOADPERF.DLL. This allows you to call this function directly from your install program. For example

LoadPerfCounterTextStrings (MyApplication.ini, bQuietModeArg);

where MyApplication.ini is the name of your initialization file and bQuietModeArg is a Boolean parameter that indicates whether to display output during the loading of the counter text strings.


Removing Counter Names and Descriptions from the Registry

If you need to remove counter names and descriptions from the registry, use the unlodctr utility. This removes the registry entries made by lodctr.

Using unlodctr

The command-line syntax for unlodctr is:

unlodctr ApplicationName

The unlodctr utility looks up the First Counter and Last Counter values in the application’s Performance key to determine the indexes of the counter objects to remove. Using these indexes, it makes the following changes to the Perflib key.

HKEY_LOCAL_MACHINE

    \SOFTWARE

        \Microsoft

            \Windows NT

                \CurrentVersion

                    \Perflib

                        Last Counter = updated if changed

                        Last Help = updated if changed

                        \009

                            Counter = application text removed

                            Help    = application text removed

                        \supported language, other than U.S. English

                            Counter = application text removed

                            Help    = application text removed

The unlodctr utility also removes the First Counter, First Help, Last Counter, and Last Help values from the application’s Performance key.

Note  The unloading function of UNLODCTR, UnloadPerfCounterTextStrings, is declared in LOADPERF.H and exported from LOADPERF.DLL. This allows you to call this function directly from your uninstall program. For example

UnloadPerfCounterTextStrings (ApplicationName, bQuietModeArg);

where ApplicationName is the name of your application and bQuietModeArg is a Boolean parameter that indicates whether to display output during the unloading of the counter text strings.


Creating Other Registry Entries

To obtain the performance data for some applications (those that return counters using the DeviceIOControl function), it is necessary to use the CreateFile function to open the device associated with the application. In this case, the name specified in CreateFile must also be installed in the DOS Devices node of the registry, as shown here:

HKEY_LOCAL_MACHINE

    \SYSTEM

        \CurrentControlSet

            \Control

                \Session Manager

                    \DOS Devices

Applications that manage multiple device instances with performance data for each device, must put a Linkage key in the its Services key. The Linkage key contains an Export value whose data is a list of the device names. For example, a system with two Etherlink cards could have the following registry entries:

HKEY_LOCAL_MACHINE

    \SYSTEM

        \CurrentControlSet

            \Services

                \Elnkii

                    \Linkage

                        Export = "\Device\Elnk01" "\Device\Elnk02"

                    \Performance

                        Library = "ElnkStat.dll"

                        Open = "OpenElnkStats"

                        Collect = "GetElnkStats"

                        Close = "CloseElnkStats"

                \Elnk01

                    \Linkage

                    \Parameters

                \Elnk02

                    \Linkage

                    \Parameters

When the system calls the Open function in an application’s performance DLL, its argument is a string containing the list of device names from the application’s Export value, if it is present. The Open function can then use these names to determine the devices for which to collect performance data.


Creating the Performance DLL

Your application’s performance DLL defines the counter and object data structures that it uses to pass performance data to the performance monitor application. Your DLL also provides the following exported functions that are called by the system in response to requests for performance data.

Function	Description
Open	Initializes performance monitoring for the application.
Collect	Reports performance data when requested.
Close	Closes performance monitoring.
The prototypes for these functions, and the structures and constants used to define counters and counter objects, are defined in the WINPERF.H file distributed with the Win32 SDK.

Communication between an application and its performance DLL differs for user-mode and privileged-mode applications. The application’s performance DLL executes in user mode. Because of this, user-mode applications, such as print and display applications, can use any technique for interprocess communication, such as named pipes, file mapping, or RPC. However, privileged-mode applications must provide an IOCTL interface that returns the performance data to the performance DLL.


How the DLL Interfaces with a Performance Monitor Application

An application retrieves performance data by specifying HKEY_PERFORMANCE_DATA in a call to the RegQueryValueEx function. If successful, RegQueryValueEx fills a buffer of the application with the requested performance data.

The first time an application calls RegQueryValueEx, or if the application uses the RegOpenKey function to open HKEY_PERFORMANCE_DATA, the system calls the Open function for each application with the correct registry entries. This gives each performance DLL an opportunity to initialize its performance data structures. Then, if the Open function returns successfully (or if there is no Open function), the system calls the Collect function. Subsequent calls to RegQueryValueEx cause the system to call the Collect function.

When the application has finished collecting performance data, it specifies HKEY_PERFORMANCE_DATA in a call to the RegCloseKey function. This causes the system to call the Close function for each application. The performance DLLs are then unloaded.

Note  It is possible for multiple programs to collect performance data at the same time. The system calls Open and Close functions only once for each application requesting performance data. For remote measurement, the system limits access to these routines to one thread at a time, so synchronization is not a problem. However, for local measurement, because multiple processes may be making simultaneous calls, you must prevent any conflicts from multiple concurrent requests for data.


The Open Function

The system calls the Open function whenever an application first connects to the registry to collect performance data. This function performs the initialization required for the application to provide performance data.

Use the following function prototype for your Open function.

DWORD CALLBACK OpenPerformanceData(LPWSTR lpDeviceNames);

The name OpenPerformanceData is a place-holder for an application-defined name. The lpDeviceNames argument points to a buffer containing the Unicode strings stored in the Export value in the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\
ApplicationName\Linkage

The strings are REG_MULTI_SZ strings, separated by a UNICODE_NULL, and terminated by two UNICODE_NULL characters. If this entry does not exist, lpDeviceNames should be NULL. The strings are the names of the devices managed by this application. The Open function should call the CreateFile function to open a handle to each device named. If CreateFile fails, the Open function should return the error code returned by the GetLastError function; otherwise, it should return ERROR_SUCCESS.

The Open function initializes the data structures it returns to the performance monitor application. In particular, it examines the registry to get the Counter and Help indices of the objects and counters supported by the application. It then stores these indices in the appropriate members of the PERF_OBJECT_TYPE and PERF_COUNTER_DEFINITION structures.

Other initialization tasks that might be performed by the Open function include the following:

•	Open and map a file mapping object used by the program to store performance data. Create a mutex to prevent the application from changing a value while the performance DLL is reading it. This is one way to communicate performance data from the application to the performance DLL. If you are using another form of interprocess communication, substitute the appropriate steps to initialize that mechanism.

•	Initialize event logging, if the DLL uses event logging to report errors. This is the only way for the performance DLL to report error conditions to the user, other than through a debugger. For more information, see Event Logging.

•	Initialize the object and counter indexes. This must be done each time the performance DLL is loaded, because the indices vary from machine to machine.

•	Perform other initialization tasks necessary for the Collect function to collect performance data efficiently.

The Open function should write any error that prevents the function from completing successfully in the system event log.


The Collect Function

The system calls each application’s Collect function whenever a performance monitor program calls the RegQueryValueEx function to collect performance data. This function returns the application’s performance data.

Use the following function prototype for your Collect function.

DWORD WINAPI CollectPerformanceData(

    LPWSTR lpwszValue,

    LPVOID *lppData,

    LPDWORD lpcbBytes,

    LPDWORD lpcObjectTypes);

The name CollectPerformanceData is a place-holder for an application-defined name.

Argument	Description
lpwszValue	Points to a string specified by the performance monitor program in a call to the RegQueryValueEx function. The string uses one of the formats described in Retrieving Selected Data.
LppData	On input, points to a pointer to the location where the data is to be placed. On successful exit, set *lppData to the next byte in the buffer available for data, such as one byte past the last byte of your data. The data returned must be a multiple of a DWORD in length. It must conform to the PERF_OBJECT_TYPE structure, unless this is a collection from a foreign computer. If foreign, any PERF_OBJECT_TYPE structures returned must be preceded by a PERF_DATA_BLOCK structure for the foreign computer. If the Collect function fails for any reason, leave *lppData unchanged.
LpcbBytes	On input, points to a 32-bit value that specifies the size, in bytes, of the lppData buffer. On successful exit, set *lpcbBytes to the size, in bytes, of the data written to the lppData buffer. This must be a multiple of sizeof(DWORD) (a multiple of 4). If the Collect function fails for any reason, set *lpcbBytes to zero.
lpcObjectTypes	On successful exit, set *lpcObjectTypes to the number of object type definitions being returned. If the Collect function fails for any reason, it should set *lpcObjectTypes to zero.
If the requested data specified by lpwszValue does not correspond to any of the object indexes or foreign computers supported by your program, leave *lppData unchanged, and set *lpcbBytes and *lpcObjectTypes both to zero. This indicates that no data is returned. If your data collection is time-consuming, you should only respond to specific requests and Costly requests. You should also lower the priority of the thread collecting the data, so that it does not adversely affect system performance.

The Collect function must return one of the values shown in the following table.

Return value	Description
ERROR_MORE_DATA	Indicates that the size of the lppData buffer as specified by *lpcbBytes is not large enough to store the data to be returned. In this case, leave *lppData unchanged, and set *lpcbBytes and *lpcObjectTypes to zero. No attempt is made to indicate the required buffer size, because this may change before the next call.
ERROR_SUCCESS	Return this value in all other cases, even if no data is returned or an error occurs. To report errors other than insufficient buffer size, use the system event log, but do not flood the event log with errors on every data collection operation.
To provide more information to the user, the Collect function should write any error that prevents the function from completing successfully in the system event log. For more information, see Event Logging.

If the application collecting the data is running on another machine (remotely), then the extensible counter functions are called in the context of the Winlogon process, which handles the server side of the remote connection. This distinction is important when troubleshooting problems that only occur remotely. The Winlogon process may access the functions using multiple threads, usually one per remote connection. This means that the Open procedure can be called more than once. You should handle this in your code accordingly, so that initialization tasks are not performed more than necessary. The Collect function may also be called concurrently by multiple threads, so you should be careful how you initialize and use temporary data. Static variables should only be used if the data is intended to be shared across threads.

The connection to the machine providing the data should be tested each time data is requested. If the connection cannot be made, you need to return some sort of indication. One suggestion is to provide a Status counter for the object that indicates whether a valid connection exists. When the connection does not exist, set the Status counter and return the last set of valid data.

For foreign computer interfaces, the opening of a channel to the foreign computer must be done in the Collect function because the computer name is not provided to the Open function. The performance DLL should save a handle to the foreign computer to avoid reconnecting on each data collection call, which would significantly slow down system performance.

Once you get the data for a foreign computer, construct a PERF_DATA_BLOCK as the first thing in *lppData, so that your application can return the data. If the system you are measuring does not provide the requested information, provide a reasonable value. You should use values from the local system for time and counter frequency if they are not provided remotely. You may need to use the PerfTime and .PerfFreq members of the PERF_OBJECT_TYPE structure for some counters as well.

Other things that you might do in the Collect include:

•	Validate the shared memory pointer and check that the Open function had successfully completed. If the Open function failed, it should have already logged an event, so the Collect function need not report this error.

•	Determine the data request type, as described in Retrieving Selected Data. If the request is for Foreign data, it is ignored and the Collect function should return no data. If the request is for a specific object or list of objects, search for its index in the list of object and counter indices. If you do not find a match, the data from this object is not desired, so the function should return no data.

•	Request ownership of the mutex for the shared memory object. Wait to get access to the data in the shared memory block.

•	Estimate the size of the data to make sure there is enough room for the data in the buffer. If the estimated size is larger than the available size, return a status of ERROR_MORE_DATA. The system passes this error to the thread that issued the call to RegQueryValueEx to request the data.

•	Copy the performance data from the shared memory to the performance data structure to be returned.

•	When all data has been transferred from the shared memory file to the performance data buffer, release the shared memory mutex and update the pointers and counter fields. The updating of the pointers and counter fields is very important, to prevent an access violation from the application, monitor, or system due to misleading buffer length information.

After the collect procedure returns successfully, the system performs the following tests to try and catch logic errors in the collect procedure. The first test to fail will generate an event log message and, in most cases, the data is discarded to prevent any further problems due to invalid pointers. These tests are normally enabled though they can be disabled by changing a registry variable value as described below:

HKEY_LOCAL_MACHINE

    \Software

        \Microsoft

            \Windows NT

                \CurrentVersion

                    \Perflib

                        ExtCounterTestLevel = Test_Level

The Test_Level is a REG_DWORD that specifies the test level. Test level 1 requests all tests. Test level 2 requests basic tests. Test level 3 requests no tests. The default is test level 1.

The basic tests performed on the data buffer are as follows:

•	Is the BytesLeft return value consistent with the returned pointer? The returned value of the BytesLeft argument to the Collect procedure is compared to the returned buffer pointer. If all is consistent, the BytesLeft value added to the original buffer pointer passed in to the Collect procedure should be the same as the buffer pointer returned by the procedure. If they are not the same a warning message is logged and the BytesLeft parameter is replaced by the value computed by finding the difference between the buffer pointer after the function call and the buffer pointer before the function call. This is somewhat risky, in that it assumes the BytesLeft value is assumed to be the incorrect one, when in fact it could be that the buffer pointer is the incorrect one.

•	Has the returned buffer pointer exceeded the allocated buffer extent? The actual buffer passed to the collect function is allocated specifically for that function call by the performance library and contains a 1K-Byte Guard Page above and below the size indicated by the remaining size of the user’s buffer. A separate buffer is used to allow testing of the extensible counter DLL’s returned data without corrupting the caller’s buffer. If the returned buffer pointer (the pointer to the next byte after this object’s data) exceeds the size of this buffer (not including guard pages) then the buffer is assumed to be invalid and discarded since it is too large to be copied into the caller’s buffer. This test consists of two parts. If the buffer pointer exceeds the end of the buffer, but not the end of the guard page then a buffer overrun error is logged. If the buffer pointer is past the end of the guard page, then a heap error is logged since the heap that the buffer was allocated from could have been corrupted causing other memory errors.

•	Are the guard pages corrupted? The 1K byte Guard Pages above and below the block of memory passed to the collect procedure are initialized with a data pattern before the collect function is called. This data pattern is checked after the collect procedure returns. If any discrepancy is detected a buffer overrun  or other memory error is assumed and the buffer is discarded.

The following tests are performed only if test level 1 is used.

•	Test object TotalByteLength field consistency. This test walks the object(s) returned by the extensible counter to see if the sum of the length of all the objects returned is the same as the value of the size of the returned buffer. Since the Collect function generally returns one or more object structures (including the instance definitions, and counter definitions and data) the sum of each object’s length should be the same as the bytes returned. A failure here can indicate the object is not computing the value of the TotalByteLength field correctly. This can cause an application program using the data to fail by having it get lost in the data structures.

•	Test Instance ByteLength field consistency. This test is similar to the test above. The test walks the list of instances in each object that returns multiple instances, to see if the next object or end of buffer follows the last instance. As above, if an inconsistency is detected, the buffer is discarded to prevent the application program from crashing due to a lost pointer.


The Close Function

The system calls each application’s Close function when an application calls the RegCloseKey function to close the HKEY_PERFORMANCE_DATA key. This function performs any cleanup required by the application’s performance data collection mechanism. For example, the function could close device handles opened by the CreateFile function, or close a handle to a file mapping object.

Use the following function prototype for your Close function.

DWORD WINAPI ClosePerformanceData();

The name ClosePerformanceData is a place-holder for an application-defined name.

The function should return ERROR_SUCCESS.


Error Handling in the DLL

Use event logging to record errors that occur during any of the functions in the performance DLL. Logging error events aids in troubleshooting applications providing performance data during development and after installation. Be careful not to log error events on every Collect call, however, because data collection can be frequent.

The following errors are logged to the event log by the performance library if it has problems with the Open procedure. If one of the errors listed below occurs, then the performance library makes no further calls to this performance DLL. Instead, the DLL is unloaded and data for the object provided by the performance DLL is not returned with the performance data.

•	PERFLIB_OPEN_PROC_NOT_FOUND − Logged when the procedure name defined in the registry could not be found in the DLL as an exported function. This usually occurs when the performance counter DLL or the service is not installed correctly or the function name has been renamed without updating the installation procedure.

•	PERFLIB_OPEN_PROC_FAILURE − Logged when the open procedure returned an error status other than ERROR_SUCCESS. This usually occurs when an expected error condition has occurred in the open procedure. Should this happen, the Counter DLL should have also entered an event log entry describing the conditions that caused the failure.

•	PERFLIB_OPEN_PROC_EXCEPTION − Logged when the open procedure encounters an unhandled exception. This is usually due to an unexpected error condition encountered by the open procedure.


Performance DLL Sample

The Win32 SDK contains a sample performance DLL. This sample is located in the directory MSTOOLS\SAMPLES\WIN32\WINNT\PerfTool.


Performance Data Reference

The following functions and structures are supported for working with performance data.


Performance Data Functions

The following functions are supported for working with performance data.

PDH Interface

CounterPathCallback
PdhAddCounter
PdhBrowseCounters
PdhCalculateCounterFromRawValue
PdhCloseQuery
PdhCollectQueryData
PdhComputeCounterStatistics
PdhConnectMachine
PdhEnumMachines
PdhEnumObjectItems
PdhEnumObjects
PdhExpandCounterPath
PdhGetCounterInfo
PdhGetDefaultPerfCounter
PdhGetDefaultPerfObject
PdhGetFormattedCounterValue
PdhGetRawCounterValue
PdhMakeCounterPath
PdhOpenQuery
PdhParseCounterPath
PdhParseInstanceName
PdhRemoveCounter
PdhSetCounterScaleFactor
PdhValidatePath

PDH Interface (Visual Basic)

PdhAddCounter (VB)
PdhCloseQuery (VB)
PdhCollectQueryData (VB)
PdhCreateCounterPathList (VB)
PdhGetCounterPathElements (VB)
PdhGetCounterPathFromList (VB)
PdhGetDoubleCounterValue (VB)
PdhGetOneCounterPath (VB)
PdhIsGoodStatus (VB)
PdhOpenQuery (VB)
PdhRemoveCounter (VB)


Performance Data Structures

The following structures are supported for working with performance data.

PDH Interface

PDH_BROWSE_DLG_CONFIG
PDH_COUNTER_INFO
PDH_COUNTER_PATH_ELEMENTS
PDH_FMT_COUNTERVALUE
PDH_STATISTICS

Registry Interface

PERF_COUNTER_BLOCK
PERF_COUNTER_DEFINITION
PERF_DATA_BLOCK
PERF_INSTANCE_DEFINITION
PERF_OBJECT_TYPE


Pen Application Programming Interface Functions

This chapter provides a reference listing of the pen API functions, arranged in alphabetical order. Each entry describes a separate function organized under the following margin headings:

Margin heading	Description
Parameters	List of function parameters
Return Value	Possible return values and their meanings
Comments	Additional information about the function
See Also	Cross-reference to related API services
Next to each function name is a number that identifies the pen API version that supports the function — for example, 1.0 or 2.0.

The names of application callback functions appear in italics to indicate the names are placeholders. Callback functions can have any name.

Constants that pertain only to a specific function are listed in this chapter in the reference entry for that function. Generally, constants that pertain to two or more API services appear in Chapter 13, “Pen Application Programming Interface Constants.”


AddInksetInterval

2.0

Merges an interval into an inkset.

BOOL AddInksetInterval( HINKSET hinkset, LPINTERVAL lpiNew )

Parameters

hinkset

Handle to an inkset.

lpiNew

Address of an INTERVAL structure.

Return Value

Returns TRUE if successful; otherwise FALSE.

Comments

The inkset is reallocated to a larger size by this function. The interval merges with any existing intervals, changing the interval only when required. For example, if the new interval is a subset of an existing one, there will be no change. Similarly, if the new interval overlaps an existing one, the union is formed. The maximum number of intervals allowed is defined to be (65536 - sizeof(INKSET)) / sizeof(INTERVAL), which evaluates to 5460.

The ending time of the new interval must be greater than or equal to the beginning time. If the interval has a duration of 0, AddInksetInterval does nothing, but returns TRUE.

An inkset formed using this function is guaranteed to have the intervals in ascending chronological order.

See Also

GetInksetInterval, INTERVAL


AddPenDataHRC

2.0

Adds an HPENDATA object to an HRC object for recognition.

int AddPenDataHRC( HRC hrc, HPENDATA hpndt )

Parameters

hrc

Handle to the HRC object.

hpndt

Handle to the HPENDATA object.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_INVALIDPNDT	Invalid pen data object.
Comments

Before terminating, the application must free the pen data, using DestroyPenData. Because the recognizer copies any data it requires, the recognizer does not affect the original data.

Calling this function is equivalent to adding data to the recognition context by walking the pen data strokes from beginning to end in stroke order. (Note that the stroke order may not necessarily be in chronological order if insertions have been made.)

A recognizer is not required to use or maintain OEM data; that is, a recognizer may choose to ignore some or all of the OEM data it receives from AddPenDataHRC. This means that the HPENDATA object that the recognizer returns through its CreatePenDataHRC function may differ from hpndt in its OEM data.

See Also

CreatePenData, AddPenInputHRC


AddPenInputHRC

2.0

Adds pen data to an HRC object for recognition. A recognizer must export this function.

int AddPenInputHRC( HRC hrc, LPPOINT lppt, LPVOID lpvOem, UINT fuOem, LPSTROKEINFO lpsi )

Parameters

hrc

Handle to the HRC object.

lppt

Address of an array of POINT structures.

lpvOem

Address of a buffer containing OEM data, or NULL if there is no OEM data.

fuOem

Flags to specify which OEM data is valid.

lpsi

Address of a STROKEINFO structure.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
Comments

A recognizer is not required to use or maintain OEM data; that is, a recognizer may choose to ignore some or all of the OEM data it receives from AddPenInputHRC. This means that the HPENDATA object that the recognizer returns through its CreatePenDataHRC function may differ from hpndt in its OEM data.

See Also

GetPenInput, GetPenDataStroke


AddPointsPenData

1.0     2.0

Adds a set of data points to the pen data object.

HPENDATA AddPointsPenData( HPENDATA hpendata, LPPOINT lppt, LPVOID lpvOem, LPSTROKEINFO lpsiNew )

Parameters

hpendata

Handle to a pen data object.

lppt

Address of an array of POINT structures containing new data points to be added to the pen data. Zero points can be added to force a change of pen state or to set a new pen state.

lpvOem

OEM data. Can be set to NULL if there is no additional OEM data. The pen data header determines how the OEM data is interpreted.

lpsiNew

Address of a STROKEINFO structure for new stroke data. Contains the count of points from lppt to be added.

Return Value

Returns a handle to the pen data object. Normally, this is the same handle originally passed to the function. NULL is returned on error. The size of hpendata is limited to 64K.

Comments

A call to GetPenHwEventData or GetPenInput gets the lpsiNew and lpvOem values. A subsequent call to AddPointsPenData appends the set of points to the HPENDATA memory block identified by hpendata. The lpsiNew argument points to a STROKEINFO structure that describes the new points, and lpvOem points to the corresponding OEM data (if any) to be added along with the points.

The STROKEINFO structure indicates the pen state of the new points—that is, whether the pen is up or down. To avoid unnecessarily creating new strokes in the HPENDATA block, AddPointsPenData compares the pen state of the new points with the pen state of the last stroke in the HPENDATA block. If the new points have the same pen state as the last stroke, the function appends the points to the last stroke and updates the last STROKEINFO structure within the HPENDATA block. If the new points have a different pen state, AddPointsPenData appends them to the HPENDATA block as a new stroke, along with the STROKEINFO structure pointed to by lpsiNew.

AddPointsPenData does not scale the data points. The calling application must ensure that the added data points have the same scale as the rest of the HPENDATA block.

See Also

CreatePenData, GetPenHwEventData


AddWordsHWL

2.0

Adds words to a word list.

int AddWordsHWL( HWL hwl, LPSTR lpsz, UINT uType )

Parameters

hwl

Handle to a word list, or the constant HWL_SYSTEM for the recognizer’s master word list.

lpsz

A pointer to a source of words, depending on the uType parameter.

uType

Word list type. This can be one of the following values:

Constant	Description
WLT_STRING	lpsz points to a single null-terminated character string in memory.
WLT_STRINGTABLE	lpsz points to an array of null-terminated character strings in memory. The list is terminated by two null characters.
WLT_WORDLIST	lpsz is the handle of a previously created word list, cast as LPSTR.
Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
Comments

If a user wants to add a word to the system word list, which is available whenever the system dictionary is enabled (see EnableSystemDictionaryHRC), then hwl should be set to the predefined constant HWL_SYSTEM. Words that are not normally found in a dictionary, such as a person’s name, can be added to the system word list. How this list is implemented, its size, or if it even exists, depends on the recognizer. A typical recognizer might maintain a thousand-word list, replacing random entries on overflow.

The HWL_SYSTEM constant cannot be used in any of the other word-list functions. For example, it is not possible to destroy the system word list with the DestroyHWL function.

For a description of word lists and how a recognizer uses them, see “Configuring the HRC” in Chapter 5, “The Recognition Process.”

See Also

CreateHWL, EnableSystemDictionaryHRC


AnimateProc

2.0

The AnimateProc function is an application-defined callback function that provides information to DrawPenDataEx on a periodic basis. The name AnimateProc serves only as a placeholder; the function can have any name.

BOOL CALLBACK AnimateProc( HPENDATA hpndt, UINT iStrk, UINT cPnt, UINT FAR * lpuSpeedPct, LPARAM lParam )

Parameters

hpndt

Handle to the pen data currently being drawn.

iStrk

Zero-based index to the stroke being drawn, or about to be drawn.

cPnt

Count of points already drawn in this stroke.

lpuSpeedPct

Address of the speed-percent value.

lParam

Application-specific data passed to the callback. This value is specified in ANIMATEINFO.

Return Value

The callback function must return TRUE to continue drawing the pen data. Returning FALSE stops animation immediately.

Comments

One of the parameters of DrawPenDataEx provides the address of this callback function. The application must create an instance of this function using the MakeProcInstance function, and ensure that it is exported in the module-definition (.DEF) file.

The application can monitor the state of animation or provide the user with an opportunity to change the speed of animation, including pausing it, using the value addressed by lpuSpeedPct.

The application can also pass application-specific information to the callback in lParam. For example, a handle to the DC (device context) can be passed.

Callbacks are made at the beginning of the stroke or time interval, before any drawing is done. However, if AI_SKIPUPSTROKES is specified, a callback is not made before up strokes.

See Also

DrawPenDataEx,  ANIMATEINFO


AtomicVirtualEvent

1.0     2.0

Locks out pen packets.

void AtomicVirtualEvent( BOOL fBegin )

Parameters

fBegin

Flag for beginning or ending lockout. TRUE begins lockout, FALSE ends it.

Return Value

This function does not return a value.

Comments

AtomicVirtualEvent is used by the Pen Palette or a similar virtual-keyboard program to lock out pen packets while the application is posting simulated key or mouse events.

Calling AtomicVirtualEvent with a TRUE value blocks input from physical devices until they are freed with a call specifying FALSE. Applications should end the lockout as quickly as possible.

An interruptable thread should not call AtomicVirtualEvent.

Example

The following code fragment posts a mouse click:

AtomicVirtualEvent( TRUE );

PostVirtualMouseEvent( VWM_MOUSELEFTDOWN, xPos, yPos );

PostVirtualMouseEvent( VWM_MOUSEMOVE, xPos, yPos );

PostVirtualMouseEvent( VWM_MOUSELEFTUP, xPos, yPos );

AtomicVirtualEvent( FALSE );

See Also

PostVirtualKeyEvent, PostVirtualMouseEvent


BeginEnumStrokes

1.0     2.0

Locks a pen data block in memory in preparation for enumerating strokes.

Note  This function is provided only for compatibility with version 1.0 of the Pen API, and will not be supported in future versions.

LPPENDATA BeginEnumStrokes( HPENDATA hpendata )

Parameters

hpendata

Handle to an HPENDATA object.

Return Value

Returns a pointer to the locked pen data if successful. Returns NULL if hpendata is compressed or if the handle cannot be locked.

Comments

BeginEnumStrokes calls the GlobalLock function internally, returning a far pointer to the memory block in the global heap. This serves to lock the data in preparation for direct reading or calling GetPenDataStroke. The return value from BeginEnumStrokes is used as an argument for GetPenDataStroke. After calling BeginEnumStrokes to lock data, an application must unlock the data when finished by calling EndEnumStrokes.

An application should never modify data directly within an HPENDATA block. Doing so can invalidate other information in the block. To modify an HPENDATA block, use one of the Pen API functions listed in Chapter 4, “The Inking Process.”

See Also

EndEnumStrokes, GetPenDataStroke


BoundingRectFromPoints

1.0     2.0

Calculates a rectangle that bounds a range of points.

void BoundingRectFromPoints( LPPOINT lppt, UINT cPt, LPRECT lprect )

Parameters

lppt

Address of an array of POINT structures.

cPt

Number of POINT structures in the array. This parameter can be 0.

lprect

Address of a RECT structure that contains the bounding rectangle when the function returns.

Return Value

This function does not return a value.

Comments

The bounding rectangle is empty at [0,0] if there are no points. For a single point, the rectangle is empty at that point.


CharacterToSymbol

1.0     2.0

Converts an ANSI string to an array of SYV_ symbol values.

int CharacterToSymbol( LPSTR lpstr, int cSyv, LPSYV lpsyv )

Parameters

lpstr

Address of a null-terminated ANSI string to be converted.

cSyv

Maximum number of SYV_ symbols the array lpsyv can hold.

lpsyv

Address of an array of SYV_ symbol values into which CharacterToSymbol places the converted symbols. The array must be large enough to hold cSyv symbols.

Return Value

Returns the number of characters converted, or −1 if there is an error.

Comments

Conversion proceeds until a null byte is found in lpstr or until lpsyv has been filled with cSyv symbols. A null byte is converted to SYV_NULL.

See Also

SymbolToCharacter, SYG, SYV_


CompactPenData

1.0     2.0

Compacts pen data based on specified trim options.

Note  This function is provided for compatibility with version 1.0 of the Pen API and will not be supported in future versions. Use TrimPenData and CompressPenData instead.

HPENDATA CompactPenData( HPENDATA hpndt, UINT fuTrim )

Parameters

hpndt

Handle to a pen data object.

fuTrim

Data-trimming options:

PDTT_DEFAULT

Reallocates memory block to fit the data; does not trim the data. If you call CompactPenData with this trim option and then call the GlobalSize function with the pen data handle as a parameter, you can retrieve the size of the pen data.

PDTT_ALL

Removes the PENINFO structure from the header. Discards all data from pen-up points (points collected when the pen is not in contact with the tablet), and removes OEM data and collinear points.

PDTT_COLLINEAR

Removes successive identical (coincident) points and collinear points from the pen data. After the operation is performed, PDTS_NOCOLLINEAR is set in the wPndts member of the PENDATAHEADER structure. The collinear points can be removed with very little if any loss of recognition accuracy. If the collinear points are removed before the points are scaled to display coordinates, there may be a small change in the displayed image.

PDTT_COMPRESS

Compresses the data without losing any information. After the data has been compressed, the compressed handle to the pen data can be passed as a parameter only to the functions CompactPenData, GetPenDataInfo, and DuplicatePenData. CompactPenData uses a “lossless” compression method that retains the ability for an application to recognize the ink after subsequent decompression. You can use this option with other trim options, including PDTT_DECOMPRESS. In this case, compression is done after all other options have been satisfied.

PDTT_DECOMPRESS

Decompresses the data. You can use this option with other trim options, including PDTT_COMPRESS. In this case, decompression is performed first, followed by any other trim options specified, and followed by recompression if PDTT_COMPRESS is specified. Since the compression method used by CompactPenData does not lose information, the data is completely restored.

PDTT_OEMDATA

Removes all OEM data—this is data other than coordinates, such as pressure. This option does not affect delayed recognition unless a recognizer is being used that expressly requires OEM data. For example, signature recognizers often use pressure information.

PDTT_PENINFO

Removes the PENINFO structure from the header. You can use this option if there is no OEM data associated with the data points or if the application does not use any of the OEM data. This option has no effect on the pen data for delayed recognition. Any OEM data present is also removed.

PDTT_UPPOINTS

Removes all data from pen-up points (points collected when the pen is not in contact with the tablet). This option has no effect on delayed recognition. This option is not usually necessary because pen-up points are not a part of standard pen data.

Return Value

If successful, CompactPenData returns a handle to a pen data object; otherwise, it returns NULL. CompactPenData may fail and return NULL in low-memory situations if compression or decompression is requested.

Comments

The PDTS_ bits are set in the wPndts member of the PENDATAHEADER structure to indicate which operations have been performed.

See Also

CompressPenData, TrimPenData, CreatePenData, PENINFO, PENDATAHEADER


CompressPenData

2.0

Compresses or decompresses the data in an HPENDATA object.

int CompressPenData( HPENDATA hpndt, UINT fuFlags, DWORD dwReserved )

Parameters

hpndt

Handle to the HPENDATA object.

fuFlags

Specifies whether to compress or decompress the data, as follows:

Constant	Description
CMPD_COMPRESS	Compress the pen data.
CMPD_DECOMPRESS	Decompress the pen data.
dwReserved

Must be 0.

Return Value

This function returns one of the following:

Constant	Description
PDR_OK	Successful completion. Redundant operations, such as compressing an HPENDATA object that has already been compressed, are not errors.
PDR_ERROR	Illegal parameter or other error.
PDR_MEMERR	Memory error.
PDR_PNDTERR	Invalid pen data.
PDR_VERSIONERR	Could not convert old pen data.
Comments

This function replaces the the version 1.0 Pen API function CompactPenData, which is supported for compatibility only.

For a discussion of data compression, see “Compressing Pen Data” in Chapter 4, “The Inking Process.”

See Also

CompactPenData,  TrimPenData


ConfigHREC

2.0

Allows an application to set or query recognizer-specific values. All calls to ConfigHREC are serviced by the recognizer’s ConfigRecognizer function. In version 2.0 of the Pen API, applications must call ConfigHREC rather than ConfigRecognizer.

int ConfigHREC( HREC hrec, UINT uSubFunction, WPARAM wParam, LPARAM lParam )

Parameters

hrec

Module handle of the recognizer library. If this value is NULL, the system default recognizer is used.

uSubFunction

Recognizer subfunction identifier. See the “Comments” section below.

wParam

Depends on the value of uSubFunction.

lParam

Address of a buffer. The contents of the buffer depend on the value of uSubFunction.

Return Value

If successful, returns 0 or a positive value as described in the list of uSubfunction constants below; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Missing recognizer, invalid parameter, or other error.
HRCR_MEMERR	Insufficient memory.
Comments

The uSubFunction parameter contains one of the following WCR_ values that identifies the requested configuration service:

WCR_CONFIGDIALOG

Instructs the recognizer to open a dialog box to set any recognizer-specific parameters. (This is analogous to DEVMODE in printer drivers, which is called when a user sets up a printer.) Some examples of the kind of settings a recognizer might implement are whether or not to allow cursive input, how much to depend on stroke order, and how rapidly to modify prototypes based on the user’s own style.

The lParam parameter points to the name of the user currently selected in the Control Panel application. The wParam parameter is used by the recognizer as the parent window for any dialog boxes it displays. The return value is always TRUE.

WCR_DEFAULT

Returns TRUE if the recognizer is capable of being a default recognizer. A default recognizer must support the standard character set as well as standard gestures.

WCR_GETALCPRIORITY

Returns the current default alphabet priority being used by the recognizer. The lParam parameter points to a variable that specifies the alphabet priority as a bitwise-OR combination of ALC_ values. The wParam parameter is not used. This subfunction is used by the system; applications should instead get alphabet priority by calling GetAlphabetPriorityHRC. The return value is TRUE if successful.

WCR_GETANSISTATE

Returns TRUE if the recognizer can recognize all of the ANSI character set; otherwise, returns FALSE or HRCR_ERROR.

WCR_GETDIRECTION

If successful, returns the current writing direction assumed by the recognizer; otherwise, returns HRCR_ERROR.

WCR_GETHAND

If successful, returns 0 if the user writes with the right hand or nonzero if the user writes with the left hand; otherwise, returns HRCR_ERROR.

WCR_PRIVATE

Values above WCR_PRIVATE have a meaning dependent on the recognizer.

WCR_PWVERSION

Returns the version number of the Pen API for which this recognizer was created. This value is 2 for the current version.

WCR_QUERY

Returns TRUE if the recognizer supports a configuration dialog box.

WCR_QUERYLANGUAGE

The wParam parameter is not used. The lParam parameter points to a null-terminated language string. The return value is TRUE if the recognizer supports the language; otherwise, it is FALSE.

WCR_RECOGNAME

Retrieves an identification string from the recognizer. The lParam parameter is treated as a far pointer to a buffer that is filled with an identification string from the recognizer. The wParam parameter is the size of the buffer to fill. The identification string is a short description of the recognizer that Control Panel presents to the user. A sample string is “US English character set, cursive & print.” The return value is always 0.

WCR_SETALCPRIORITY

Sets the current default alphabet priority for the recognizer to the value in lParam. Note that setting a priority for individual characters is not supported for defaults. The wParam parameter is not used. This subfunction is used by the system; applications should set priority explicitly in an HRC with the SetAlphabetPriorityHRC function. The return value is TRUE if successful.

WCR_SETANSISTATE

Sets a flag to enable or disable recognition of the entire ANSI character set. Setting lParam to 1 enables recognition of the entire ANSI set; setting lParam to 0 allows recognition of only English (ASCII) characters. The wParam parameter is not used.

The WCR_SETANSISTATE subfunction determines the default setting when CreateCompatibleHRC creates an HRC. An application can explicitly override the setting for the HRC with the SetInternationalHRC function. The return value is TRUE if successful.

WCR_SETDIRECTION

Sets the current writing direction for the recognizer to the value in lParam, which can be an appropriate combination of the RCD_ values. The wParam parameter is not used. The return value is TRUE if successful.

WCR_SETHAND

Sets the current writing hand preference for the recognizer. The lParam parameter is 0 for a right-handed user or 1 for a left-handed user. The wParam parameter is not used. The return value is TRUE if successful.

WCR_TRAIN

This subfunction returns TRAIN_NONE if the recognizer does not support training. A return value of TRAIN_DEFAULT indicates support for the default trainer, including the capability of resetting its database to the original “factory” setting (see WCR_TRAINSAVE). A return value of TRAIN_CUSTOM indicates that the recognizer also provides its own custom trainer. A return value of TRAIN_BOTH indicates support for both kinds of training.

WCR_TRAINMAX

The recognizer returns the maximum number of SYV_ symbol values that it can train for any given shape.

The recognizer should return 0 if it can train any number of characters. For example, the Microsoft recognizer can train one character for a shape; a cursive recognizer may allow more.

WCR_TRAINSAVE

The trainer calls the ConfigHREC function with the parameters set to (WCR_TRAINSAVE, TRAIN_SAVE, 0) when it is time to save the data-base. This happens when the user closes the trainer. After this call, the recognizer should return TRUE if it can successfully save the database; otherwise, it should return FALSE.

The trainer calls the function with (WCR_TRAINSAVE, TRAIN_REVERT, 0) before it discards any changes made to the database that have not yet been saved to disk (that is, revert to saved). This happens when the user cancels the changes. The recognizer should return TRUE if it is successful.

The trainer can alternatively call ConfigHREC with (WCR_TRAINSAVE, TRAIN_RESET, 0) to reset the database to the original “factory” settings. The recognizer should return TRUE if it is successful.

WCR_TRAINDIRTY

The recognizer returns TRUE if the recognizer needs to save training. The recognizer returns FALSE if no training occurred, if the recognizer does not use a database for training, if the recognizer saves as it works, or if the recognizer cannot revert the training.

The hwnd parameter is a handle to the requesting window. The trainer can use this as the parent window for a dialog box, for example. If there has been a recent recognition, a pointer to it is passed in the lParam parameter, although this may be NULL.

The format for the WCR_TRAINDIRTY subfunction call is:

ConfigHREC( hrec, WCR_TRAINDIRTY, 0, 0 );

WCR_TRAINCUSTOM

If the recognizer returns TRAIN_CUSTOM or TRAIN_BOTH in response to WCR_TRAIN, it will receive a WCR_TRAINCUSTOM message when it is time to display its own training system.

The format for the WCR_TRAINCUSTOM subfunction call is:

ConfigHREC( hrec, WCR_TRAINCUSTOM, hwnd, lprcresult );

WCR_USERCHANGE

Notifies the recognizer of a change in user. The lParam parameter points to a null-terminated string containing the user’s name. The wParam parameter specifies the required modification:

A wParam value of CRUC_NOTIFY indicates a new user, the name of whom is in the string that lParam points to.

A wParam value of CRUC_REMOVE indicates that the user identified by lParam should be removed from the recognizer’s user list. If the recognizer has saved any files or settings for the user, they should be deleted in response to this notification.

WCR_VERSION

Returns the version number. The low-order byte of the return value specifies the major (version) number. The high-order byte specifies the minor (revision) number.

See Also

ConfigRecognizer, ALC_, SYV_


ConfigRecognizer

1.0     2.0

Provides system access to the configuration settings of a recognizer. In version 2.0 of the Pen API, only the pen system can call ConfigRecognizer. Applications must call ConfigHREC to query or set recognizer configuration values. The system routes ConfigHREC calls to the ConfigRecognizer function of the appropriate recognizer.

A recognizer must export ConfigRecognizer. The information in this entry is for recognizer developers only, not application developers.

UINT ConfigRecognizer( UINT uSubFunction, WPARAM wParam, LPARAM lParam )

Parameters

uSubFunction

Recognizer subfunction identifier. See ConfigHREC for descriptions of the WCR_ subfunctions that ConfigRecognizer must support. In addition, ConfigRecognizer must support the following two WCR_ subfunctions:

WCR_INITRECOGNIZER

When an application installs a recognizer by using InstallRecognizer, the system calls the recognizer’s ConfigRecognizer function with the WCR_INITRECOGNIZER subfunction. The wParam parameter is not used and lParam is a far pointer to an ASCII string containing the user’s name, as set in the system registry. If successful, the recognizer should return 1; otherwise, it should return 0 to indicate an error.

In response to the WCR_INITRECOGNIZER subfunction, the recognizer should perform any required initialization tasks. (This subfunction replaces the InitRecognizer function exported by version 1.0 recognizers.)

WCR_CLOSERECOGNIZER

When an application unloads a recognizer by using UninstallRecognizer, the system calls the recognizer’s ConfigRecognizer function with the WCR_CLOSERECOGNIZER subfunction. The wParam and lParam parameters are not used. If successful, the recognizer should return 1; otherwise, it should return 0 to indicate an error.

In response to the WCR_CLOSERECOGNIZER subfunction, the recognizer should perform any required cleanup tasks. (This subfunction replaces the CloseRecognizer function exported by version 1.0 recognizers.)

wParam

Depends on the value of uSubFunction.

lParam

A value, or an address of a buffer. The contents of the buffer depend on the value of uSubFunction.

Return Value

Returns 0 or a positive value, depending on uSubFunction.

Comments

ConfigRecognizer provides initialization and query services for the pen system. The parameter uSubFunction is a WCR_ value that specifies the configuration service that ConfigRecognizer must perform.

When an application calls ConfigHREC, the system determines the appropriate recognizer and passes the call to that recognizer’s ConfigRecognizer function. ConfigHREC exists only because its extra argument hrec identifies to the system the intended recognizer library. This information is necessary in version 2.0 of the Pen API, which allows multiple recognizer libraries to exist simultaneously. Thus, the names ConfigHREC and ConfigRecognizer refer to the same function. Applications refer to the function as ConfigHREC, while recognizers export it as ConfigRecognizer.

See Also

ConfigHREC, SYV_


CorrectWriting

1.0     2.0

Sends text to the CorrectText dialog box to allow the user to edit text using a single-line or multiline bedit control.

BOOL CorrectWriting( HWND hwnd, LPSTR lpText0, UINT cbText0, LPVOID lpvReserved, DWORD dwFlags, DWORD dwParam )

Parameters

hwnd

Handle of the owner of the CorrectText dialog box or writing tools used to edit the text.

lpText0

Far pointer to a buffer containing the text to be corrected.

When CorrectWriting returns, the lpText0 buffer holds the corrected text. As a general rule, this parameter should allow for growth by a factor of at least two or some maximum size that depends on the field of entry.

cbText0

Number of characters in lpText0. This value must be greater than 1 and include a byte for the string’s null terminator.

lpvReserved

This parameter is reserved and should be set to NULL.

dwFlags

Translation and style flags, formed by the low-order word and high-order word of dwFlags. The low-order word must be one or more of the following flags, combined with the bitwise-OR operator. Note that the CWR_REPLACECR and CWR_REPLACETAB flags replace CWR_STRIPTAB and CWR_STRIPCR, respectively; both flags are in version 1.0 of the Pen API.

Constant	Description
CWR_BOXES	Create bedit writing tool instead of keyboard. This flag can be used only for edit control and its derivatives. Use of this flag by applications is not recommended.
CWR_HEDIT	Indicates that the given hwnd is an edit control or a control derived from the edit control. This flag can be used only for edit control and its derivatives. Use of this flag by applications is not recommended.
CWR_INSERT	Use “Insert Text” instead of “Edit Text” as the title. CWR_TITLE overrides this flag.
CWR_KEYBOARD	Create keyboard writing tool instead of bedit lens. This flag can be used only for edit control and its derivatives. Use of this flag by applications is not recommended.
CWR_KKCONVERT	Initiate IME (Japanese version only).
CWR_REPLACECR	Replace carriage return characters in the text in the buffer by spaces just before the call returns.
CWR_REPLACETAB	Replace tabs in the text in the buffer by spaces just before the call returns.
CWR_SIMPLE	Use writing tool (simple dialog box). This flag can be used only for an edit control and its derivatives. Use of this flag by applications is not recommended.
CWR_SINGLELINEEDIT	Replace carriage returns and tabs with spaces and strip linefeeds from the text in the buffer just before the call returns.
CWR_STRIPLF	Strip linefeed characters from the text in the buffer just before the call returns.
CWR_TITLE	Interpret dwParam (see below) as a pointer to the title text string.
The high-order word must be one of the following values and cannot be combined with the bitwise-OR operator. The values determine the type of keyboard to show when the user clicks the keyboard button in the dialog box.

Constant	Description
CWRK_TELPAD	Use the telephone-type keyboard.
CWRK_BASIC	Use the basic keyboard.
CWRK_DEFAULT	Use the default keyboard type. The default keyboard type is currently the same as the basic keyboard type.
CWRK_FULL	Use the full keyboard.
CWRK_NUMPAD	Use the numeric keyboard.
dwParam

A far pointer to a text string that serves as the title of the dialog box if CWR_TITLE is present in dwFlags; otherwise, this parameter must be 0.

Return Value

Returns TRUE if the writing tool or CorrectWriting operation was successful. Otherwise, the return value is FALSE.

Comments

CorrectWriting sends a WM_PENMISC message with PMSC_GETHRC as the lParam to the specified window. This message requests the HRC handle associated with the window, which the system then uses for the dialog box. The window should return a copy of its HRC so that the system can destroy it before the call returns. If the window returns NULL to this message, the system creates a default HRC.

Note that in the Japanese version, CorrectWriting is supported but internally calls CorrectWritingEx, which opens a Dialog Input Window.


CorrectWritingEx

2.0

Sends text to the CorrectText dialog box to allow the user to edit text using the Japanese Data Input Window. (Japanese version only.)

INT CorrectWritingEx( HWND hwnd, LPSTR lpText, UINT cbText, LPCWX lpcwx )

Parameters

hwnd

Handle of the owner of the CorrectText dialog box or writing tool used to edit the text. This can be NULL.

lpText

Far pointer to a buffer containing text to correct. This is copied into the Data Input Window's edit control.  If lpText is NULL, a WM_GETTEXT message is sent to the text source window, specified by the hwndText member of lpcwx, or if lpcwx or its hwndText member is NULL, to hwnd.  On successful exit, a WM_SETTEXT message will be sent to that window with modified text.

cbText

Size of the lpText buffer. If the source of the text is an edit control constrained by EM_LIMITTEXT, cbText should reflect that size. If lpText is NULL, the cbText value will be used to limit text if it is greater than zero; otherwise, no limit is used and the returned text may be of arbitrary size.

lpcwx

Address of a CWX structure, or NULL. The structure is used to specify optional correction parameters; for a description of its members, see CWX. If this value is NULL, the following default assumptions are made:

•	The text window is the same as the owner window hwnd.

•	A default recognition context is used.

•	The edit control style is a combination of ES_LEFT and ES_MULTILINE.

•	All text is selected; the caption is "Edit Text".

•	Most recently use values for context flags, keyboard, keyboard states, position, and size are used.

Return Value

If there is a programming or memory error, the negative value CWXR_ERROR is returned. Otherwise, one of the following nonnegative values is returned:

Constant	Description
CWXR_MODIFIED	User pressed the OK button.
CWXR_UNMODIFIED	User pressed the Cancel button, or closed the dialog, or pressed the OK button but did not make any changes to the text.
Comments

An application must be sure to initialize the CWX structure properly if it is used. In particular, the cbSize member must be set to sizeof(CWX), and the remaining fields (at least up to dwSel) are typically set to zero.

Example

The following example shows how to initialize and call CorrectWritingEx when a button is pressed in a dialog:

CWX cwx = {sizeof(CWX), 0, NULL, NULL, {0}, 0L, 0L};

cwx.hwndText = GetDlgItem(hdlg, IDD_ETSL);	// dialog edit

cwx.dwEditStyle = GetWindowLong(cwx.hwndText, GWL_STYLE)

| ES_PASSWORD;

cwx.dwSel = SendMessage(cwx.hwndText, EM_GETSEL, 0, 0);

_fstrcpy((LPSTR)cwx.szCaption, (LPSTR)"Enter your password:");

// we specify kbd and context, but use MRU placement

cwx.wApplyFlags = CWXA_KBD | CWXA_STATE | CWXA_CONTEXT;

// don't update most-recently used settings for this one-shot:

cwx.wApplyFlags |= CWXA_NOUPDATEMRU;

cwx.ixkb = CWXK_QWERTY;

cwx.rgState[CWXK_QWERTY-CWXK_FIRST] = CWXKS_HAN | CWXKS_ROMA;

cwx.dwFlags = CWX_NOTOOLTIPS | CWX_TOPMOST;	// no distractions

if (CorrectWritingEx(hdlg, NULL, 0, &cwx) != CWXR_MODIFIED)

ErrBox(EB_WHOAREYOU);

// validate pwd in the text window etc...

See Also

CWX


CreateCompatibleHRC

2.0

Creates a handwriting recognition context HRC that can be used to do handwriting recognition, optionally compatible with an existing context template. A recognizer must export this function.

HRC CreateCompatibleHRC( HRC hrcTemplate, HREC hrec )

Parameters

hrcTemplate

Handle to an existing HRC object that can provide default settings for the recognition context being created. If NULL, this parameter is ignored and default settings are used.

hrec

Instance handle of the recognizer library. This is the value returned by the Windows function LoadLibrary. Note that the module handle returned by the Windows function GetModuleHandle does not work in this case. If this value is NULL, the system default recognizer is used by internally making a call to GetPenMiscInfo with PMI_SYSREC as the first argument.

Return Value

Returns a handle to a new HRC object if successful; otherwise, returns NULL.

Comments

The hrcTemplate parameter can be used to copy an old context into the new HRC object. This includes settings such as word lists, coercion, and GUIDE structure, but excludes any pen data that may be in the old context.

See Also

DestroyHRC, GetResultsHRC, SetMaxResultsHRC


CreateHWL

2.0

Creates a handle to a word list.

HWL CreateHWL( HREC hrec, LPSTR lpsz, UINT uType, DWORD dwReserved )

Parameters

hrec

Module handle of the recognizer library. If this value is NULL, the system default recognizer is used.

lpsz

A pointer to a source of words, depending on the uType parameter.

Type

Word-list type. This can be one of the following values:

Constant	Description
WLT_EMPTY	An empty word list is created. The lpsz parameter is ignored.
WLT_STRING	The lpsz parameter points to a single null-terminated character string in memory.
WLT_STRINGTABLE	The lpsz parameter points to an array of null-terminated character strings in memory. The list is terminated by two null characters.
dwReserved

Must be 0.

Return Value

If successful, returns the handle of a newly created word list; otherwise, returns NULL. If the recognizer does not support word lists, the return value is NULL.

Comments

CreateHWL creates a word list for constraining recognition. Word lists can be combined using the AddWordsHWL function.

To make a word list from words in a file, an application uses CreateHWL to create an empty word list, then reads the file into it with the ReadHWL function.

Any word lists created by an application must eventually be destroyed by calling DestroyHWL. Attempting to unload a recognizer that has open word lists results in an error.

For a description of word lists and how a recognizer uses them, see “Configuring the HRC” in Chapter 5, “The Recognition Process.”

Example

The following example demonstrates how to provide a word list to constrain recognition results to the words “Canada,” “USA,” or “Mexico”:

static char szNames[] = { "Canada",

  "USA",

  "Mexico"

};

HWL hwlCountries = CreateHWL( NULL,

(LPSTR)szNames,

WLT_STRINGS, 0L );	      // Create early for later use

.

.

.

if (hrc = CreateCompatibleHRC( NULL, NULL ))

{

   SetWordlistHRC( hrc, hwlCountries );       // Set list into HRC

   SetWordlistCoercionHRC( hrc, SCH_FORCE );  // Force match

   .

   .	   // Code that collects and recognizes input goes here

   .

}

See Also

AddWordsHWL, DestroyHWL, SetWordlistHRC


CreateInkset

2.0

Creates an empty inkset.

HINKSET CreateInkset( UINT gmemFlags )

Parameters

gmemFlags

Flag that specifies whether or not the Windows GlobalAlloc function should create a shared memory object when the inkset object is created. This flag should be either 0 or GMEM_DDESHARE. The GMEM_MOVEABLE and GMEM_ZEROINIT flags are added to this value, and other GMEM_ flags are ignored.

Return Value

Returns a handle to an inkset if successful; otherwise, the return value is NULL.

See Also

DestroyInkset, INTERVAL


CreateInksetHRCRESULT

2.0

Creates an inkset from parts of a recognition result.

HINKSET CreateInksetHRCRESULT( HRCRESULT hrcresult, UINT iSyv, UINT cSyv )

Parameters

hrcresult

Handle of an HRCRESULT object.

iSyv

Index to first symbol for inkset.

cSyv

Count of symbols.

Return Value

Returns the handle of a newly created inkset if successful. If the index to the first symbol iSyv is invalid, or some other error occurs, the return value is NULL.

Comments

The inkset spans a series of continuous symbols; disjoint sets are not allowed. Before terminating, the calling application must destroy the HINKSET object by calling DestroyInkset.

If the range of symbols specified by iSyv + cSyv exceeds the number of symbols available, the returned inkset is valid only for available symbols. This is not an error, so it is possible to assign cSyv a large value to get an inkset for all symbols after iSyv.

For a description of inksets, see “The HINKSET Object” in Chapter 4, “The Inking Process.”

See Also

DestroyInkset, GetResultsHRC


CreatePenData

1.0     2.0

Creates an empty HPENDATA block.

Note  This function is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions. Use CreatePenDataEx instead.

HPENDATA CreatePenData( LPPENINFO lppeninfo, int cbOem, UINT uScale, UINT gmemFlags )

Parameters

lppeninfo

Address of tablet information to be inserted into the PENINFO structure in the pen data header. If this parameter is NULL, the current tablet settings are retrieved from the hardware instead. If there is no tablet, the pen data will not have an embedded PENINFO section and the wPndts member in PENDATAHEADER will have the PDTS_NOPENINFO flag set.

cbOem

Width of OEM data packet. If this value is greater than or equal to 0, the OEM data overrides the contents of the PENINFO structure, if present; otherwise, a negative value such as −1 can be used to specify that the system should calculate the size of the OEM data packet.

uScale

Data-scaling metric value. This parameter can be one of the following values:

Constant	Description
PDTS_LOMETRIC	Each logical unit is mapped to 0.1 millimeter. Positive x is to the right; positive y is down.
PDTS_HIMETRIC	Each logical unit is mapped to 0.01 millimeter. Positive x is to the right; positive y is down.
PDTS_HIENGLISH	Each logical unit is mapped to 0.001 inch. Positive x is to the right; positive y is down.
PDTS_ARBITRARY	The application has done its own scaling of the data point.
PDTS_STANDARDSCALE	The standard scaling metric; equivalent to PDTS_HIENGLISH.
gmemFlags

Flag that specifies whether or not the Windows GlobalAlloc function should create a shared memory object when the pen data object is created. This should be either 0 or GMEM_DDESHARE. The GMEM_MOVEABLE and GMEM_ZEROINIT flags are added to this value, and other GMEM_ flags are ignored.

Return Value

Returns a handle to a new and empty pen data object if successful; otherwise, it returns NULL.

Comments

The application provides the PENINFO structure for the header, the real size of any OEM data stored with each coordinate, and the scale of the coordinates.

The uScale parameter specifies scaling values that are also used in the MetricScalePenData function and in the PENDATAHEADER structure member wPndts. The scaling values do not behave in the same way as the Windows scaling units with similar names. For example, a 1-inch line in MM_HIENGLISH will not necessarily be an inch long on the screen because GDI does not know the size of the monitor. However, with PDTS_HIENGLISH in MetricScalePenData, a line drawn an inch long is actually an inch long.

If lppeninfo is NULL, and if there is no tablet on the system (that is, if SendDriverMessage fails), it returns NULL.

The cbOem value must be less than or equal to 12, depending on the size of the OEM data packet. A value of 0 explicitly sets the amount of OEM information to none. A negative value indicates that the size of the OEM data packet is to be calculated by the system. Any existing value for the cbOemData member of PENINFO can be overwritten.

See Also

CreatePenDataEx, DestroyPenData, PDTS_


CreatePenDataEx

2.0

Creates a PENDATA structure with specified OEM data subsets.

HPENDATA CreatePenDataEx( LPPENINFO lppeninfo, UINT uScale, UINT fuOptions, UINT gmemFlags )

Parameters

lppeninfo

Address of tablet information to be inserted into the PENINFO structure in the pen data header. If this parameter is NULL, the current tablet settings are retrieved from the hardware instead. If there is no tablet, the pendata will not have an embedded PENINFO section and the wPndts member in PENDATAHEADER will have the PDTS_NOPENINFO flag set.

uScale

Data-scaling metric value. This parameter can be one of the following values:

Constant	Description
PDTS_LOMETRIC	Each logical unit is mapped to 0.1 millimeter. Positive x is to the right; positive y is down.
PDTS_HIMETRIC	Each logical unit is mapped to 0.01 millimeter. Positive x is to the right; positive y is down.
PDTS_HIENGLISH	Each logical unit is mapped to 0.001 inch. Positive x is to the right; positive y is down.
PDTS_ARBITRARY	The application has done its own scaling of the data point.
PDTS_STANDARDSCALE	The standard scaling metric is equivalent to PDTS_HIENGLISH.
fuOptions

Storage and trim options. If this parameter is 0, no timing, PDK_, or OEM data is stored. If it is CPD_DEFAULT, everything but user data is stored.

Otherwise, this parameter can explicitly specify subsets of OEM and other data. To do so, the parameter should be a combination of one of the CPD_USER values that allocate extra storage and any collection of PHW_ constants. (These values should be combined using the bitwise-OR operator.)

The following table lists the PHW_ values for the fuOptions parameter:

Constant	Description
PHW_PRESSURE	Report pressure in OEM data if available.
PHW_HEIGHT	Report height in OEM data if available.
PHW_ANGLEXY	Report XY-angle in OEM data if available.
PHW_ANGLEZ	Report Z-angle in OEM data if available.
PHW_BARRELROTATION	Report barrel rotation in OEM data if available.
PHW_OEMSPECIFIC	Report OEM-specific value in OEM data if available.
PHW_PDK	Report per-point PDK_ bits in OEM data.
PHW_ALL	Report all available OEM data. This flag is the sum of all other PHW_ flags. The following table lists the CPD_ values for the fuOptions parameter:
CPD_DEFAULT	Store timing, PDK, and all OEM data for each stroke.
CPD_USERBYTE	Set internal flag to add space for one byte of additional storage to be allocated for each stroke. Added space is for application use.
CPD_USERWORD	Set internal flag to add space for one word of additional storage to be allocated for each stroke. Added space is for application use.
CPD_USERDWORD	Set internal flag to add space for one doubleword of additional storage to be allocated for each stroke. Added space is for application use.
CPD_TIME	Maintain absolute time information for each stroke.
gmemFlags

Flag that specifies whether GlobalAlloc should create a shared memory object or not when the pen data object is created. This should be either 0 or GMEM_DDESHARE. The GMEM_MOVEABLE and GMEM_ZEROINIT flags are added to this value, and other GMEM_ flags are ignored.

Return Value

Returns the handle to the HPENDATA object if successful; otherwise, returns NULL.

Comments

CreatePenDataEx is an extension of CreatePenData that allows a more detailed specification of what is stored in each stroke of the pen data.

The fuOptions parameter is typically specified as CPD_DEFAULT to request collection and storage of all information generated by the tablet, including x-y data, absolute stroke timing information, and all available OEM data. The OEM data set that is actually stored in the pen data is the minimum set that satisfies both the request and what is physically available from the tablet (that is, intersection set).

If lppeninfo is NULL, and if there is no tablet on the system (that is, if the SendDriverMessage function fails), the pen data that is created will not have any hardware or OEM information and a default sampling rate of 100Hz will be used. This case is similar to removing PENINFO from the header using TrimPenData with a parameter of TPD_PENINFO.

A value of 0 for fuOptions is used to indicate that only coordinate data is required. While recognition of this type of pen data may suffer, this provides the least complicated type of pen data.

PHW_ bits can be specified to indicate which OEM values or per-point PDK_ pen state information is to be collected. Note that, except for PHW_PDK, which is always valid, this is only a request; if the hardware does not support certain types of OEM data, that data will be absent.

The uScale parameter specifies scaling values that are also used in the MetricScalePenData function and in the PENDATAHEADER structure member wPndts. The scaling values do not behave in the same way as the Windows scaling units with similar names. For example, a 1-inch line in MM_HIENGLISH will not necessarily be an inch long on the screen, because GDI does not know the size of the monitor. However, with PDTS_HIENGLISH in MetricScalePenData, a line drawn an inch long is actually an inch long.

See Also

CreatePenData, DestroyPenData, PDTS_, PDK_


CreatePenDataHRC

2.0

Returns the handle to the HPENDATA object containing the pen data in the HRC.

HPENDATA CreatePenDataHRC( HRC hrc )

Parameters

hrc

Handle to the HRC object.

Return Value

Returns a handle to the HPENDATA object if successful; otherwise, it returns NULL.

Comments

It is the responsibility of the caller to destroy the HPENDATA object.

A recognizer is not required to use or maintain OEM data; that is, a recognizer can choose to ignore some or all of the OEM data it receives from AddPenDataHRC or AddPenInputHRC. This means that the HPENDATA object the recognizer returns through CreatePenDataHRC may not contain all the OEM data originally provided by the application. Whether or not a recognizer uses the OEM data, it should store all such data it receives and forward it so that subsequent recognizers, if any, can use the data.

See Also

AddPenInputHRC, AddPenDataHRC


CreatePenDataRegion

2.0

Creates a region that envelops the point data in an HPENDATA object.

HRGN CreatePenDataRegion( HPENDATA hpndt, UINT uType )

Parameters

hpndt

Handle to the HPENDATA object.

uType

Type of region to create. This can be one of the following values:

CPDR_BOX

The bounding box of the pen data ink is converted to a region.

CPDR_LASSO

The pen data describes a lasso that makes up the boundary of the region. If the last point of the pen data does not coincide with the first point, a closed figure is created either by joining the endpoints with a straight line or by using the intersection point of the beginning and ending line segments, whichever is more appropriate. Only the first stroke is used; if the pen data has more than a single stroke, subsequent strokes are ignored.

Return Value

This function returns a handle to a region if successful; otherwise the return value is NULL.

Comments

The coordinates of the region are the same as those used in the pen data. It is the application’s responsibility to remove the region when the application is finished with it, using the Windows DeleteObject function.

CreatePenDataRegion enables an application to determine the screen area a gesture such as lasso or cut applies to. For an example of how to use the CreatePenDataRegion function to determine the area of a gesture, see the section “DoDefaultPenInput Messages” in Chapter 2, “Starting Out with System Defaults.”


DestroyHRC

2.0

Destroys an HRC object. A recognizer must export this function.

int DestroyHRC( HRC hrc )

Parameters

hrc

Handle to the HRC object.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
Comments

If the HRC contains other objects such as an HPENDATA object, the recognizer must destroy the contained objects as well. After DestroyHRC returns HRCR_OK, the handle hrc is no longer valid. The application should set hrc to NULL to ensure it is not inadvertently used again.

See Also

CreateCompatibleHRC, DestroyHRCRESULT


DestroyHRCRESULT

2.0

Destroys an HRCRESULT object. A recognizer must export this function.

int DestroyHRCRESULT( HRCRESULT hrcresult )

Parameters

hrcresult

Handle to the HRCRESULT object to destroy.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
Comments

A recognizer must maintain a count of the number of HRCRESULT objects it creates. If an application calls DestroyHRC, the recognizer should not remove the HRC from memory until the application has called DestroyHRCRESULT for all HRCRESULT objects associated with the HRC.

After DestroyHRCRESULT returns HRCR_OK, the handle hrcresult is no longer valid. The application should set hrcresult to NULL to ensure it is not inadvertently used again.

See Also

GetResultsHRC, DestroyHRC


DestroyHWL

2.0

Destroys a handle to a handwriting-recognition word list.

int DestroyHWL( HWL hwl )

Parameters

hwl

Word list to destroy.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

After DestroyHWL returns HRCR_OK, the handle hwl is no longer valid. The application should set hwl to NULL to ensure it is not inadvertently used again.

See Also

CreateHWL


DestroyInkset

2.0

Frees memory associated with an inkset.

BOOL DestroyInkset( HINKSET hinkset )

Parameters

hinkset

Handle of an inkset to destroy.

Return Value

Returns TRUE if successful; otherwise FALSE.

Comments

Once memory is freed, the handle hinkset is invalid. The application should set the handle to NULL.

See Also

CreateInkset, INTERVAL


DestroyPenData

1.0     2.0

Frees the memory associated with a specified pen data memory block.

BOOL DestroyPenData( HPENDATA hpndt )

Parameters

hpndt

Handle to a pen data memory block to destroy.

Return Value

Returns TRUE if the memory was successfully freed; otherwise, FALSE.

Comments

Once the memory block is destroyed, the HPENDATA handle is no longer valid. The application should set the handle to NULL.

See Also

CreatePenData, CreatePenDataEx


DictionarySearch

1.0     2.0

Performs a dictionary search for a version 1.0 recognizer.

Note  This function is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions.

BOOL DictionarySearch( LPRC lprc, LPSYE lpsye, int cSye, LPSYV lpsyv, int csyvMax )

Parameters

lprc

Address of an RC structure.

lpsye

Address of an array of SYE symbol elements that constitute the symbol graph.

cSye

Number of SYE structures in the array.

lpsyv

Output buffer of SYV types. This parameter contains the return results of the dictionary search. A SYV_NULL value is always appended at the end of this buffer. Therefore, this parameter must have enough space for csyvMax + 1 SYV symbol values.

csyvMax

Size of the output buffer.

Return Value

Returns TRUE if any enumeration is found in a dictionary. It returns FALSE if a NULL dictionary was requested or none of the enumerations was found in any dictionary.

Comments

The DictionarySearch function uses the symbol graph pointed to by lpsye, performs a dictionary search based on the options set in lprc, and returns the result as an array of SYV symbol values in the buffer pointed to by lpsyv. The function returns the number of SYV elements copied, limited by the maximum specified in the csyvMax parameter.

DictionarySearch first passes the symbol graph with DIRQ_SYMBOLGRAPH to all the dictionaries in the rglpdf array in the specified RC structure. If none succeeds, the function enumerates the symbol graph in lpsye and searches through all of the dictionary functions for a match. The calling application can get suggestions by setting the RCO_SUGGEST flag in the lRcOptions field in the RC structure. When this flag is set and no enumeration is found in any of the dictionaries in the rglpdf array, DictionarySearch tries to get a suggestion from the dictionaries on the path. DictionarySearch takes the first suggestion offered by any dictionary and returns that as the result of the search. If there are no suggestions, the function returns the best enumeration. The best enumeration is obtained using the FirstSymbolFromGraph function.

If the option RCO_NOSPACEBREAK is set in the lRcOptions field of the specified RC structure, DictionarySearch treats the entire lpsye array as a single symbol graph. If this flag is not set, the function breaks down the input symbol graph into tokens delimited by white space, performs the search sequence on each of them, and assembles the result in the lpsyv array.

This function uses the EnumSymbols function for enumeration and the wTryDictionary member in the RC structure to specify the maximum number of enumerations to search through for each symbol graph token.

See Also

EnumSymbols, FirstSymbolFromGraph, SYE, SYV_, RC


DoDefaultPenInput

2.0

Initiates default handling of pen input.

int DoDefaultPenInput( HWND hwnd, UINT wEventRef )

Parameters

hwnd

Handle to the window initiating the default processing.

wEventRef

An identifier of a pen event in the input stream, from which input is begun. This identifier is the value returned from the GetMessageExtraInfo function.

Return Value

Returns one of the following values:

Constant	Description
PCMR_OK	Pen collection was successfully started.
PCMR_ALREADYCOLLECTING	StartPenInput has already been called for this session.
PCMR_APPTERMINATED	The application aborted input.
PCMR_ERROR	Illegal parameter or unspecified error.
PCMR_INVALID_PACKETID	Invalid packet identifier.
PCMR_SELECT	Press-and-hold was detected. Collection is not started.
PCMR_TAP	A pen tap was detected. Collection is not started.
Comments

DoDefaultPenInput simplifies the pen input process by including the following capabilities in a single call:

•	Starts pen input by calling StartPenInput

•	Starts inking by calling StartInking

•	Saves the screen background overwritten by the ink

•	Collects the pen input data

•	Stops inking by calling StopInking

•	Stops pen input by calling StopPenInput

•	Targets the pen input data to windows

•	Recognizes results

•	Sends the recognition results to the targets

The default processing proceeds in three phases: initialization, data gathering, and termination. A set of submessages corresponds to each of the three phases.

•	During the initialization phase, the system sends the WM_PENEVENT sub-message PE_SETTARGETS and potentially several PE_GETPCMINFO and PE_GETINKINGINFO messages. After the target or the DefWindowProc function handles these messages and returns a value of PCMR_OK to indicate success, the data-gathering phase begins.

•	During the data-gathering phase, the window specified by the hwnd parameter starts to receive the core pen-input submessages PE_PENDOWN, PE_PENUP, and PE_PENMOVE. The window should let these submessages fall through to DefWindowProc, which translates them into the higher-level messages PE_BEGINDATA and PE_MOREDATA. These are sent to one of the windows specified in the htrgTarget members of the TARGET structures if targeting is in progress; otherwise, the messages are sent to hwnd.

•	The termination phase begins when the pen input terminates. The target window should let the core termination messages PE_TERMINATING and PE_TERMINATED fall through to DefWindowProc. The PE_ENDDATA, PE_RESULT, and PE_ENDINPUT submessages are sent by DefWindowProc while processing PE_TERMINATED.

A return value of LRET_ABORT to any of the WM_PENEVENT submessages aborts the entire process of default input.

See Also

WM_PENEVENT, StartPenInput, StartInking, StopPenInput, StopInking


DPtoTP

1.0     2.0

Converts an array of points in display coordinates to tablet coordinates.

BOOL DPtoTP( LPPOINT lppt, int cPnt )

Parameters

lppt

Address of an array of POINT structures to convert to tablet coordinates. This parameter cannot be NULL.

cPnt

Number of POINT structures to convert.

Return Value

Returns TRUE if the conversion was successful; otherwise, returns FALSE.

Comments

Because of possible rounding errors, the DPtoTP and TPtoDP functions are not guaranteed to be perfect inverses of each other.

The calling application must avoid overflow by passing in points that are within the limits of the current physical display.

See Also

TPtoDP


DrawPenData

1.0     2.0

Displays the pen data in an HPENDATA object as a trail of visible ink.

void DrawPenData( HDC hdc, LPRECT lprect, HPENDATA hpndt )

Parameters

hdc

Handle to a device context. This parameter can also be the handle of a metafile.

lprect

Bounding rectangle of ink, in client coordinates. Can be NULL.

hpndt

Handle to a pen data object.

Return Value

This function does not return a value. If hpndt is NULL, DrawPenData does nothing.

Comments

DrawPenData draws the pen data in the specified device context using the GDI Polyline function. The current settings in the device context rather than the ink characteristics determine how the data is rendered. This means the ink width and color specified in the PENDATAHEADER structure have no effect on how DrawPenData renders the ink. To alter the display characteristics of the ink, an application must call the appropriate Windows GDI functions to set the GDI drawing pen (not to be confused with the real pen).

The application using DrawPenData must either scale the data points or set the mapping appropriately if lprect is NULL.

If lprect is not NULL, the points are scaled into lprect as the drawing is done. Internally, nondestructive calls to the SetViewportExtEx, SetViewPortOrg, SetWindowOrg, and SetWindowExtEx functions are used to render the pen data in the device context within the bounds of the provided rectangle. An application must compute the proper pen width (if it is other than 1) before calling this function with a valid lprect parameter to account for the scaling that occurs.

DrawPenData draws the ink in the rectangle relative to the upper-left corner of the window. It ignores any changes that have been made to the origin of the device context by previous calls to the SetWindowOrg or SetViewportOrgEx functions. If the origin has changed, the rectangle passed to DrawPenData must be offset by the appropriate amount.

If the ink is to be drawn with a width of greater than 1 pixel, the width of the currently selected pen must be set to achieve the desired result. The width must be set in client coordinates if a mapping mode is set in the device context. For example, if the mapping mode has been set to MM_HIENGLISH, the pen width must be set to a number appropriate for the desired width in MM_HIENGLISH units to preserve the proper scale of the ink. This scaling is only an issue when the ink width is greater than 1.

The rendering of the ink data produced by DrawPenData generally does not exactly match the rendering produced by the display driver when the data was first collected. This discrepancy results because DrawPenData and the Polyline function use different algorithms to draw the data. The difference is an occasional “off by one” error that appears as a shifting of some pixels around the edges, depending on the rounding done by Polyline. An application that requires an exact replication of the original ink rendering should call the RedisplayPenData function.

The DrawPenDataEx function allows more control when drawing the contents of pen structures.

See Also

CreatePenData, DrawPenDataEx, DuplicatePenData, RedisplayPenData


DrawPenDataEx

2.0

An enhanced version of DrawPenData. Besides displaying the pen data in an HPENDATA object as a trail of visible ink, DrawPenDataEx can govern the speed at which the data is rendered, a process called animation.

int DrawPenDataEx( HDC hdc, LPRECT lprectVP, HPENDATA hpndt, UINT iStrkFirst, UINT iStrkLast, UINT iPntFirst, UINT iPntLast, ANIMATEPROC lpfnAnimateCB, LPANIMATEINFO lpai, UINT fuFlags )

Parameters

hdc

Handle to a device context.

lprectVP

Viewport rectangle, usually the bounding rectangle of the pen data, in client coordinates. The ink is scaled to fit the specified rectangle. If this parameter is NULL, the bounding rectangle of the ink in hpndt is used, in whatever coordinate system it happens to be in.

hpndt

Handle to a pen data object.

iStrkFirst

Index of the first stroke to display.

iStrkLast

Index of the last stroke to display.

iPntFirst

Index of the first point in the first stroke to display.

iPntLast

Index of the last point in the last stroke to display.

lpfnAnimateCB

Pointer to a callback function instance, or NULL. The callback function is called periodically during drawing, and animation is controlled by values in the structure addressed by the next parameter, lpai, which should not be NULL. If lpfnAnimateCB and the speed in the lpai structure parameters are NULL, the specified pen data is drawn without regard to timing information, and no callback functions are generated. See AnimateProc for a description of the callback function.

lpai

Address of an ANIMATEINFO structure that specifies animation parameters to control how the pen data is drawn. If this parameter is NULL, the function draws the specified pen data without regard to timing information, and no callback functions are generated; otherwise, the caller must initialize the cbSize member to sizeof( ANIMATEINFO ).

fuFlags

This flag can be 0 or one of the following values:

DPD_HDCPEN

Use the GDI pen already selected into the specified device context. If this flag is set, any pen formatting stored in hpndt is ignored and all strokes are drawn with a single width and color. The DrawPenData function uses this flag.

DPD_DRAWSEL

Paint selected strokes in the specified range. A solid pen is used, with a width slightly larger than the stroke width. This flag can be used only for drawing and is ignored for animation. It is incompatible with DPD_HDCPEN.

Return Value

Returns PDR_OK if successful. Attempting to draw an empty HPENDATA (containing no strokes) also returns PDR_OK. Otherwise, returns one of the following:

Constant	Description
PDR_ABORT	Drawing aborted because pen data became invalid after a callback or yield.
PDR_CANCEL	Callback cancel or impasse. An impasse occurs when the user attempts to animate with 0 percent speed (that is, pause),  but the callback interval is on a per-stroke basis.
PDR_COMPRESSED	Pen data is compressed.
PDR_ERROR	Bad animation structure, invalid sampling rate (0 or less) in pen data header, illegal flags, or other error.
PDR_MEMERR	Memory error.
PDR_PNDTERR	Invalid pen data. This value is also returned if the pen data is destroyed or corrupted during drawing or animation. This error can occur if an application is drawing a large pen data object and then destroys the data before drawing is complete.
PDR_PNTINDEXERR	Invalid point index.
PDR_STRKINDEXERR	Invalid stroke index.
PDR_VERSIONERR	Could not convert old pendata.
Comments

DrawPenDataEx is a general-purpose drawing function for rendering pen data objects. The calling application can use the timing information in the strokes to animate the pen data and specify which subset of the pen data should be drawn.

Partial pen data objects can be drawn by specifying first and last strokes and points with iStrkFirst, iStrkLast, iPntFirst, and iPntLast. Set beginning values to 0 and ending values to IX_END to display the entire pen data object. The function fails if any of these values lie outside the ranges available in the pen data. The stroke values must be between 0 and the total number of strokes in the pen data, and the point indices must be between 0 and the number of points in their stroke.

DrawPenDataEx can display only a set of sequential strokes with a single call. To draw nonsequential strokes—say, the second, fifth, and eighth strokes of the pen data—requires multiple calls to DrawPenDataEx.

Ink displayed by DrawPenDataEx differs slightly from the original rendering, as described in the DrawPenData topic. However, DrawPenDataEx can automatically display the ink with its original color and width, saving the application the burden of resetting the current GDI pen characteristics. To draw the ink according to the GDI settings, set fuFlags to DPD_HDCPEN.

If lpfnAnimateCB is not NULL, the specified callback function must return TRUE to continue drawing, or FALSE to terminate drawing.

An application can modify the pen data while it is being rendered, for example, during an animation callback, task switching, or internal yield. However, doing so can make internal pointers or data invalid and result in unpredictable behavior. For this reason, editing the pen data during rendering is not recommended.

See Also

AnimateProc, DrawPenData, RedisplayPenData, DrawPenDataFmt, ANIMATEINFO


DrawPenDataFmt

2.0

The DrawPenDataFmt macro is used to draw pen data using its stored stroke attributes.

int DrawPenDataFmt( HDC hdc, LPRECT lprectVP, HPENDATA hpndt )

Parameters

hdc

Handle to a device context.

lprectVP

Viewport rectangle, usually the bounding rectangle of the HPENDATA object, in client coordinates. The ink is scaled to fit the specified rectangle. If this parameter is NULL, the bounding rectangle of the ink in hpndt is used, in whatever coordinate system it happens to be in.

hpndt

Handle to an HPENDATA object.

Return Value

Returns PDR_OK if successful. Attempting to draw valid but empty pen data (containing no strokes) also returns PDR_OK. Otherwise, the return value is one of the following:

Constant	Description
PDR_COMPRESSED	Pen data is compressed.
PDR_ERROR	Invalid sampling rate (0 or less) in pen data header, or other error.
PDR_MEMERR	Memory error.
PDR_PNDTERR	Invalid pen data.
PDR_VERSIONERR	Could not convert old pen data.
Comments

The DrawPenDataFmt macro is a wrapper for DrawPenDataEx, providing default values for most of the parameters.

The definition is:

#define DrawPenDataFmt( hdc, lprectVP, hpndt )

DrawPenDataEx( hdc, lprectVP, hpndt, 0, IX_END, 0, IX_END, NULL,

   NULL, 0 );

These default values specify:

•	Full-speed rendering (no animation).

•	Entire data set is drawn (no stroke subsets).

See Also

DrawPenDataEx


DuplicatePenData

1.0     2.0

Duplicates an HPENDATA object, allowing an application to generate clones of existing pen data.

HPENDATA DuplicatePenData( HPENDATA hpendata, UINT gmemFlags )

Parameters

hpendata

Pen data to be duplicated.

gmemFlags

Flag that specifies whether or not the Windows GlobalAlloc function should create a shared memory object when the pen data object is created. This should be either 0 or GMEM_DDESHARE. The GMEM_MOVEABLE and GMEM_ZEROINIT flags are added to this value and other GMEM_ flags are ignored.

Return Value

Returns a handle to the duplicated pen data object if successful; otherwise, it returns NULL. It returns NULL if memory is not allocated successfully.

Comments

The DuplicatePenData function duplicates the data specified by the hpendata parameter by creating a second pen data memory block. The application is responsible for destroying this memory block by calling DestroyPenData.

See Also

CreatePenData, DestroyPenData


EmulatePen

1.0     2.0

Emulates a pen in an application that does not use the standard Windows I-beam cursor in text areas.

Note  This function is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions. Use DoDefaultPenInput or hedit controls instead.

void EmulatePen( BOOL fPen )

Parameters

fPen

Flag to set pen emulation. TRUE activates pen emulation; FALSE turns it off.

Return Value

This function does not return a value.

Comments

The application must call EmulatePen with fPen set to TRUE whenever the cursor is over a text input window. When the cursor leaves that area, the application must call EmulatePen with fPen set to FALSE.

EmulatePen is useful only for those applications that do not use other Pen API services and do not use the standard Windows I-beam cursor. Windows automatically provides pen-based input in edit controls that use the I-beam cursor, as described in Chapter 1.

See Also

DoDefaultPenInput


EnableGestureSetHRC

2.0

Enables or disables recognition of specific gestures or collections of gestures in an HRC object.

int EnableGestureSetHRC( HRC hrc, SYV syv, BOOL fEnable )

Parameters

hrc

Handle to the HRC object.

syv

Either a gesture SYV_ symbol value, such as SYV_COPY, or one or more of the following GST_ constants combined using the bitwise-OR operator. Note that individual SYV_ gesture symbol values cannot be combined with GST_ constants.

Constant	Description
GST_SEL	Selection and lasso.
GST_CLIP	Cut, copy, paste.
GST_WHITE	Space, tab, return.
GST_EDIT	Insert, correct, undo.
GST_CIRCLELO	Lowercase circle gestures.
GST_CIRCLEUP	Uppercase circle gestures.
GST_CIRCLE	All circle gestures.
GST_ALL	All gestures.
fEnable

Enable recognition flag. This flag must be set to TRUE to enable recognition of the gesture or gestures in syv, or to FALSE to disable recognition of the specified gestures.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

The results of EnableGestureSetHRC are cumulative. The function can be called several times in succession to refine the precise gesture set required. However, calling EnableGestureSetHRC with syv set to GST_ALL and fEnable set to FALSE disables all gestures.

By default, a recognition context HRC enables all gestures that its associated recognizer supports.

Example

The following example enables selection, Clipboard functions, and SYV_CIRCLEUPA:

EnableGestureSetHRC( hrc, GST_ALL, FALSE );	    // Disable all

EnableGestureSetHRC( hrc, GST_SEL | GST_CLIP, TRUE ); // Enable sets

EnableGestureSetHRC( hrc, SYV_CIRCLEUPA, TRUE );	    // Enable circle A

See Also

SetAlphabetHRC, SYV_


EnableSystemDictionaryHRC

2.0

Enables or disables a recognizer’s dictionary.

int EnableSystemDictionaryHRC( HRC hrc, BOOL fEnable )

Parameters

hrc

Handle to the HRC object for the recognizer.

fEnable

Enable recognition flag. This flag must be set to TRUE to enable use of the dictionary, or FALSE to disable its use.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter, no system dictionary, or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

The enable state of the system dictionary does not affect any word lists that may be set into the HRC object.

See Also

SetWordlistHRC


EndEnumStrokes

1.0     2.0

Unlocks an HPENDATA memory block previously locked with the function BeginEnumStrokes.

Note  This function is provided only for compatibility with version 1.0 of the Pen API, and will not be supported in future versions.

LPPENDATA EndEnumStrokes( HPENDATA hpndt )

Parameters

hpndt

Handle to the locked HPENDATA memory block.

Return Value

Returns NULL if the function is successful; otherwise, the return value is nonzero.

Comments

EndEnumStrokes internally calls the Windows GlobalUnlock function to unlock the memory block specified by hpndt. Calling EndEnumStrokes invalidates any pointers previously returned by the GetPenDataStroke function.

See Also

BeginEnumStrokes, GetPenDataStroke


EndPenInputHRC

2.0

Informs a recognizer that pen data input has been terminated. A recognizer must export this function.

int EndPenInputHRC( HRC hrc )

Parameters

hrc

Handle to the HRC object for the recognizer.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_MEMERR	Insufficient memory.
HRCR_ERROR	Invalid parameter or other error.
Comments

EndPenInputHRC does not instruct the recognizer to complete recognition; an application must call ProcessHRC to do that. However, an application that does not use DoDefaultPenInput must call EndPenInputHRC when it detects that input has finished. (DoDefaultPenInput calls EndPenInputHRC internally.)

The recognizer can terminate open-ended states and reduce ambiguity in searches when it knows that no more ink will arrive. For example, the recognizer can keep various options open for possible delayed strokes that can modify a character. EndPenInputHRC tells the recognizer that no more delayed strokes will arrive.

After calling EndPenInputHRC for an HRC, an application should cease adding pen input into the HRC. Some recognizers, such as the Microsoft Handwriting Recognizer (GRECO.DLL), do not accept late pen input. If the application calls AddPenInputHRC after having called EndPenInputHRC for the same HRC, the Microsoft Handwriting Recognizer returns HRCR_ERROR.

Other recognizers may differ. With such recognizers, a client may continue to add pen input without error into a recognition context, even after having called EndPenInputHRC. However, doing so is not efficient. In the worst case, the recognizer may be forced to reprocess all of the pen data from the beginning.

For an example of a normal termination sequence, see the code sample in GetSymbolsHRCRESULT.

See Also

ProcessHRC, DoDefaultPenInput


EnumSymbols

1.0     2.0

Enumerates strings in a symbol graph in order of most probable to least probable.

UINT EnumSymbols( LPSYG lpsyg, UINT cstrMax, ENUMPROC lpEnumFunc, LPVOID lvData )

Parameters

lpsyg

Address of the symbol graph SYG.

cstrMax

Maximum number of strings to enumerate.

lpEnumFunc

Address of enumeration function.

lvData

Application-specific data.

Return Value

Returns the number of strings enumerated.

Comments

The EnumSymbols function enumerates all symbol strings (to a maximum defined by cstrMax) contained in the symbol graph that lpsyg points to. The lpEnumFunc parameter points to the enumeration function called with each enumeration.

To generate all the symbols from a symbol graph, set cstrMax equal to the value retrieved by passing lpsyg to GetSymbolCount.

See Also

EnumSymbolsCallback, FirstSymbolFromGraph, SYG, SYV_


EnumSymbolsCallback

1.0     2.0

EnumSymbolsCallback is a callback function pointed to by the lpEnumFunc parameter of EnumSymbols. The callback function can have any name. The function’s name must appear in the EXPORT section of the application’s module definition file.

int CALLBACK EnumSymbolsCallback( LPSYV lpsyv, int csyv, FAR void * lvData )

Parameters

lpsyv

Symbol string.

csyv

Count of symbols in string.

lvData

Address of application-specific data from EnumSymbols.

Return Value

Returns TRUE to continue enumeration, or FALSE to stop enumeration.

See Also

EnumSymbols, SYV_


ExtractPenDataPoints

2.0

Extracts points from a specified stroke in an HPENDATA object.

int ExtractPenDataPoints( HPENDATA hpndt, UINT iStrk, UINT iPnt, UINT cPnts, LPPOINT lppt, LPVOID lpvOem, UINT fuOption )

Parameters

hpndt

Handle to an HPENDATA object.

iStrk

Zero-based index of the stroke to remove points from.

iPnt

Zero-based index to the first point to remove.

cPnts

Count of points to remove. If this value is greater than the number of points after iPnt, all the points from iPnt to the last point of the stroke are removed. ExtractPenDataPoints fails if iPnt is greater then the number of points in the stroke.

lppt

Array of POINT structures that receives the extracted points. This must be large enough to hold cPnts points.

lpvOem

Buffer to put extracted OEM data if it exists, or NULL. This must be large enough to hold cPnts OEM packets.

fuOption

Flags. This value can be EPDP_REMOVE to remove the points from the stroke in the pen data object.

Return Value

Returns PDR_OK if successful; otherwise, the return value can be one of the following negative values:

Constant	Description
PDR_COMPRESSED	Pen data is compressed.
PDR_ERROR	Parameter or other unspecified error.
PDR_MEMERR	Out of memory.
PDR_STRKINDEXERR	Invalid stroke index.
PDR_PNTINDEXERR	Invalid point index.
PDR_VERSIONERR	Could not convert old pen data object.
Comments

ExtractPenDataPoints extracts points (and OEM data, if any) from a specified stroke of the pen data object specified by hpndt. It copies the extracted points and the OEM data to the buffers pointed to by lppt and lpvOem.

Use ExtractPenDataStrokes to extract strokes from the pen data object or RemovePenDataStrokes to remove strokes from the pen data object.

See Also

InsertPenDataPoints, InsertPenDataStroke, RemovePenDataStrokes


ExtractPenDataStrokes

2.0

Creates a new HPENDATA object that is a subset of an existing object.

int ExtractPenDataStrokes( HPENDATA hpndt, UINT fuExtract, LPARAM lParam, LPHPENDATA lphpndtNew, UINT gmemFlags )

Parameters

hpndt

Handle to an existing pen data object.

fuExtract

Extraction options and modifiers. This value can be a combination of one of the principal EPDS_ options, with an optional comparison modifier, if appropriate, and the optional EPDS_REMOVE modifier. The flags should be combined using the bitwise-OR operator.

The following table gives the principal options. These options specify what the new pen data object will be based on.

Constant	Description
EPDS_INKSET	Based on a handle to an inkset. The EPDS_GT, EPDS_GTE, EPDS_LT, and EPDS_LTE comparison operators are ignored, because extraction is based on matching the inkset. (However, EPDS_NOT creates a pen data set with all stroke/inkset intersections that do not match the provided inkset.)
EPDS_PENTIP	Based on complete pen-tip characteristics.
EPDS_SELECT	Based on selected strokes.
EPDS_STROKEINDEX	Based on index.
EPDS_TIPCOLOR	Based on pen-tip color.
EPDS_TIPWIDTH	Based on pen-tip width.
EPDS_TIPNIB	Based on pen tip nib style.
EPDS_USER	Based on user-specific value. The following table gives the optional comparison modifiers and the optional removal modifier:
EPDS_LT	Less than comparison: extract all strokes with attribute less than the value specified in lParam.
EPDS_LTE	Less than or equal comparison: extract all strokes with attributes less than or equal to the value specified in lParam.
EPDS_GT	Greater than comparison: extract all strokes with attributes greater than the value specified in lParam.
EPDS_GTE	Greater than or equal comparison: extract all strokes with attributes greater than or equal to the value specified in lParam.
Constant	Description
EPDS_NOT	Negative comparison (alias EPDS_NE): extract all strokes with attributes not equal to the value specified by lParam. If combined with other EPDS_ constants, reverses the constant meaning (for example, EPDS_NE | EPDS_LT | EPDS_GT means not less than or not greater than). If lParam is EPDS_SELECT, EPDS_NOT means extract all unselected strokes.
EPDS_REMOVE	Remove matching strokes from source. If this flag is added, any strokes matching the criteria for extraction are removed from the source pen data.
lParam

Meaning is dependent on the value of the fuExtract parameter, as follows:

Constant	Description
EPDS_INKSET	lParam is a handle to an inkset.
EPDS_PENTIP	lParam is a pointer to a PENTIP structure to compare. Only equal or not-equal matches are supported. EPDS_LT, for example, is ignored.
EPDS_SELECT	lParam is not used and should be set to 0.
EPDS_STROKEINDEX	lParam is a zero-based stroke index to compare.
EPDS_TIPCOLOR	lParam is a pen tip color to compare.
EPDS_TIPNIB	lParam is a pen tip nib style to compare. Only equal or not-equal matches are supported.
EPDS_TIPWIDTH	lParam is a pen tip width to compare.
EPDS_USER	lParam is a user-specific value to compare, cast to a double-word value.
lphpndtNew

Address of a pen data handle if one is to be created; otherwise, NULL.

gmemFlags

Flag that specifies whether or not the Windows GlobalAlloc function should create a shared memory object when the pen data object is created. This should be either 0 or GMEM_DDESHARE. The GMEM_MOVEABLE and GMEM_ZEROINIT flags are added to this value, and other GMEM_ flags are ignored.

Return Value

Returns the number of strokes that match the comparison criteria if successful, or a negative error value. (The return value can be 0. The maximum is the largest integer value.)  The error value can be one of the following:

Constant	Description
PDR_COMPRESSED	Pen data is compressed.
PDR_ERROR	Parameter or other unspecified error.
PDR_INKSETERR	Invalid inkset and EPDS_INKSET specified.
PDR_MEMERR	Memory error.
PDR_NA	Option not available.
PDR_PNDTERR	Invalid pendata.
PDR_STRKINDEXERR	Invalid stroke index.
PDR_USERDATAERR	EPDS_USER was specified but there is no per-stroke user data.
PDR_VERSIONERR	Could not convert old pendata.
Comments

ExtractPenDataStrokes extracts strokes from an existing pen data object, optionally creating a new pen data object made up of the extracted strokes. The extraction can be a copy or move process; that is, the source pen data object can remain the same or contain only the remaining strokes not moved to the new structure. Modifier flags in fuExtract specify how the value in lParam compares with attributes of the pen data strokes (equal by default, greater than, less than, or none of these three).

If lphpndtNew is NULL, no pen data object is created. This is useful for modifying the original pen data object hpndt (when EPDS_REMOVE specified), or simply for determining a return value without modifying or creating a pen data object. If lphpndtNew is not NULL, the flags specified by gmemFlags are passed to the GlobalAlloc function when memory for the pen data memory block is created.

If EPDS_REMOVE is specified, any strokes with an attribute matching the comparison criteria are removed from the source pen data object, regardless of whether a new pen data is created. In the case of inksets, this may actually generate more strokes if there are multiple intersections with the inkset within any one stroke.

Example

To create an HPENDATA object consisting only of selected strokes:

ExtractPenDataStrokes( hpndt, EPDS_SELECT, 0, &hpndtDst, 0 );

To return the count of selected strokes:

ExtractPenDataStrokes( hpndt, EPDS_SELECT, 0, NULL, 0 );

To delete all but the selected strokes from the source:

ExtractPenDataStrokes( hpndt, EPDS_NOT | EPDS_SELECT | EPDS_REMOVE,

   0, NULL, 0 );

To copy strokes 0 through 10 inclusive to a new HPENDATA object:

ExtractPenDataStrokes( hpndt, EPDS_LTE | EPDS_STROKE, 10,

   &hpndtDst, 0 );

To move all but blue strokes to a separate HPENDATA object:

ExtractPenDataStrokes( hpndt, EPDS_NOT | EPDS_TIPCOLOR | EPDS_REMOVE,

   RGB_BLUE, &hpndtDst, 0 );

See Also

DuplicatePenData


FirstSymbolFromGraph

1.0     2.0

Retrieves an array of symbols that is the most likely interpretation of a specified symbol graph SYG.

void FirstSymbolFromGraph( LPSYG lpsyg, LPSYV lpsyv, int cSyvMax, LPINT lpcSyv )

Parameters

lpsyg

Address of the symbol graph.

lpsyv

Address of an empty array of SYV_ symbol values. FirstSymbolFromGraph fills this array with the likeliest interpretation from the graph.

cSyvMax

Size of the array that lpsyv points to.

lpcSyv

Number of symbols returned in lpsyv. This value is 0 if lpsyg is empty. It is −1 if the buffer is not large enough to hold the results.

Return Value

This function does not return a value.

Comments

The array of symbols is identical to the first string returned to the EnumSymbolsCallback callback function of EnumSymbols.

See Also

EnumSymbols, SYG, SYV_


GetAlphabetHRC

2.0

Retrieves the alphabet being used in a handwriting recognition context HRC.

int GetAlphabetHRC( HRC hrc, LPALC lpalc, LPBYTE rgbfAlc )

Parameters

hrc

Handle to the HRC object.

lpalc

Address of a buffer that receives the current ALC_ values. If NULL, this parameter is ignored.

rgbfAlc

Address of an array of bits or NULL. If NULL, this parameter is ignored. If lpalc contains ALC_USEBITMAP and rgbfAlc points to a valid array, the array is filled according to the bits set by the SetAlphabetHRC function.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

If rgbfAlc is not NULL, the array it points to must be large enough to accommodate 256 bits (32 bytes). If the nth bit is set, the nth ANSI character is recognizable. Bits representing characters with ASCII values less than 32 (the space character) currently have no meaning.

ALC_DEFAULT specifies the set of characters at or above ALC_SYSMINIMUM that the recognizer can accurately distinguish.

For a description of alphabets and their relationship to a recognizer, see “Configuring the HRC” in Chapter 5, “The Recognition Process.”

See Also

EnableGestureSetHRC, SetAlphabetHRC, GetAlphabetPriorityHRC, ALC_


GetAlphabetPriorityHRC

2.0

Retrieves the alphabet priority used in a handwriting recognition context HRC.

int GetAlphabetPriorityHRC( HRC hrc, LPALC lpalc, LPBYTE rgbfalc )

Parameters

hrc

Handle to the HRC object.

lpalc

Address of an ALC type that will be filled with the current ALC_ priority values.

rgbfalc

Address of a 256-bit (32-byte) buffer whose bits map to ANSI single-byte characters, or NULL if this information is not required.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
For a description of how a recognizer uses alphabet priority, see “Configuring the HRC” in Chapter 5, “The Recognition Process.”

See Also

GetAlphabetHRC, SetAlphabetPriorityHRC, ALC_


GetAlternateWordsHRCRESULT

2.0

Returns alternative word interpretations of a previous result. (Not supported in Japanese version.)

int GetAlternateWordsHRCRESULT( HRCRESULT hrcresult, UINT iSyv, UINT cSyv, LPHRCRESULT rghrcresults, UINT cResults )

Parameters

hrcresult

Handle of a results object.

iSyv

Index of the first of a span of symbols within the results object.

cSyv

The number of symbols in the original result, starting at iSyv, for which alternative words are required.

rghrcresults

Address of a result array. This address cannot be NULL.

cResults

The size of the rghrcresults array in results. This parameter must be greater than 0.

Return Value

Returns the number of results actually provided, if successful. This can be less than the space allocated in rghrcresults, and may be 0; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

GetAlternateWordsHRCRESULT provides alternative word interpretations of a previous result. The alternatives returned are strongly coerced to words in the recognizer’s dictionary, if enabled, and the word list, if any, of the HRC that processed the results.

The span of symbols defined by iSyv and cSyv need not fall on word boundaries. However, the recognizer returns only a single word per result. It is the application’s responsibility to ensure that embedding a full word within other symbols makes sense. (The application can also choose to let the user make that decision.) For example, finding alternatives for “polce” in the phrase “pig-in-a-polce” could legitimately return “poke” as an alternative, but alternatives for “kef” in “markefplace” would probably be meaningless.

See Also

GetResultsHRC


GetBoxMappingHRCRESULT

2.0

Returns the box indices for a range of symbols.

int GetBoxMappingHRCRESULT( HRCRESULT hrcresult, UINT iSyv, UINT cSyv, UINT FAR * rgi )

Parameters

hrcresult

Handle of a results object.

iSyv

Index of the first symbol of interest in the results object.

cSyv

The number of symbols following iSyv for which box indices are required. Note that the array rgi must be large enough to accommodate this many items of size UINT. A value of 0 is allowed, in which case the function simply returns 0.

rgi

Address of an index array. The array must be large enough to store cSyv indices. This address cannot be NULL.

Return Value

Returns the number of indices actually retrieved, if successful. This can be less than the space allocated in rgi if iSyv indexes an element near the end of the results array, and is 0 if iSyv indexes a nonexistent element; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

GetBoxMappingHRCRESULT is typically used with boxed input established by SetGuideHRC. If no guide structure has been set, the recognizer will return HRCR_ERROR.

It is possible to allocate a small buffer in rgi and call GetBoxMappingHRCRESULT repeatedly, incrementing the index iSyv each time by the number of indices returned in the previous call until GetBoxMappingHRCRESULT returns 0.

See Also

GetResultsHRC, SetGuideHRC


GetBoxResultsHRC

2.0

Encapsulates recognizer functionality for boxed input.

int GetBoxResultsHRC( HRC hrc, UINT cAlt, UINT iSyv, UINT cBoxRes, LPBOXRESULTS rgBoxResults, BOOL fGetInkset )

Parameters

hrc

Handle to the HRC object used for the boxed input.

cAlt

Count of alternatives expected in the BOXRESULTS structure. If this parameter is 0, the function returns 0.

iSyv

Index to the starting symbol.

cBoxRes

The count of BOXRESULTS structures that the rgBoxResults array can hold. This parameter must be greater than 0.

rgBoxResults

Address of an array of BOXRESULTS structures.

fGetInkset

Flag to request inksets for each result if TRUE. If FALSE, the recognizer provides no inksets.

Return Value

Returns the count of BOXRESULTS elements returned in the rgBoxResults structure, if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_INVALIDGUIDE	The guide structure is invalid.
HRCR_MEMERR	Insufficient memory.
HRCR_HOOKED	A hook preempted the result.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

GetBoxResultsHRC simplifies the task of boxed recognition by providing character alternatives on a per-box basis in one call.

If fGetInkset is TRUE, the recognizer assigns a valid inkset handle to the hinksetBox member of the BOXRESULTS structure addressed by rgBoxResults. It is the application’s responsibility to destroy these inksets with DestroyInkset.

Example

The following code sample gets results for 10 boxes at a time, with five alternatives per box:

HANDLE hMem = GlobalAlloc( GHND, 10 * (sizeof( BOXRESULTS )

 + (5-1) * sizeof( SYV )) );

LPBOXRESULTS rgBoxR = (LPBOXRESULTS)GlobalLock( hMem );

UINT indx = 0;

do

{

   int cRes = GetBoxResultsHRC( hrc, 5, indx, 10, rgBoxR, FALSE );

   .

   .	// Check for errors and use rgBoxR

   .

   indx += (UINT)cRes;

}

while (cRes == 10);

See Also

GetBoxMappingHRCRESULT, GetResultsHRC, DestroyInkset


GetGlobalRC

1.0     2.0

Queries the current default settings and fills an RC structure with the global values. In version 2.0 of the Pen API, RC is made obsolete by the HRC object.

Note  This function is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions.

UINT GetGlobalRC( LPRC lprc, LPSTR lpszDefRecog, LPSTR lpszDefDict, int cbDefDictMax )

Parameters

lprc

Address of an RC structure. This parameter can be NULL.

lpszDefRecog

Address of a character string in which the default recognizer module name is returned. This must be at least 128 bytes long. This parameter can be NULL.

lpszDefDict

Buffer in which the default dictionary path is returned. This path ends with two null characters. This parameter can be NULL.

cbDefDictMax

Size of lpszDefDict buffer to be filled.

Return Value

Returns GGRC_OK if successful; otherwise, the return value may be one of the following values:

Constant	Description
GGRC_PARAMERROR	One or more invalid parameters were detected. The call to GetGlobalRC has no effect.
GGRC_DICTBUFTOOSMALL	The size of the lpszDefDict buffer is not large enough to contain the entire dictionary path. The buffer is filled with as many complete dictionary module names as allowed by the size. The list is terminated by a null string.
Comments

GetGlobalRC fills the RC structure with global values. Values that have no default settings—for example, the bounding rectangle—are set to 0.

An application does not need to call this function to use the default values. When an application initializes an RC structure using InitRC, the system default values are set as the values for the structure members. This function returns the actual current values for RC members. The InitRC function returns the default values, which include placeholder values for some RC members.

See Also

InitRC,  SetGlobalRC,  RC


GetGuideHRC

2.0

Retrieves the guide structure being used in a recognition context HRC.

int GetGuideHRC( HRC hrc, LPGUIDE lpguide, UINT FAR * lpnFirstVisible )

Parameters

hrc

Handle to the HRC object.

lpguide

Address of a GUIDE structure; all coordinates are in screen coordinates. This parameter cannot be NULL.

lpnFirstVisible

Pointer to first visible character or line, or NULL. For boxed controls, this is the first visible box (leftmost and topmost for left-right, top-down languages like English). For other controls, this is the first visible character position (left-most for English) in a single-line control, and the first visible line (topmost for English) in multiline controls.

If set to NULL, lpnFirstVisible is ignored.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
See Also

GUIDE, SetGuideHRC


GetHotspotsHRCRESULT

2.0

Retrieves the hot spots for a particular symbol.

int GetHotspotsHRCRESULT( HRCRESULT hrcresult, UINT iSyv, LPPOINT lppt, UINT cPnts )

Parameters

hrcresult

Handle of a results object.

iSyv

Index of the symbol in the results object.

lppt

Address of an array of up to MAXHOTSPOT POINT structures.

cPnts

Actual size of lppt array in points.

Return Value

If successful, returns the count of hot spots; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

Any symbol can have hot spots, but they are usually of interest only for gestures. For example, if the user writes “X” for deletion, the center of the “X”—its hotspot —points to the item to be deleted. Hot spots are returned in tablet coordinates. The maximum number of hot spots allowed is provided in the PENWIN.H constant MAXHOTSPOT. The Microsoft Handwriting Recognizer (GRECO.DLL), supports this function for gesture symbols only.

If cPnts is smaller than the actual number of hot spots, only cPnts points are reported.


GetHRECFromHRC

2.0

Retrieves a handle to the recognizer bound to an HRC object. A recognizer must export this function.

HREC GetHRECFromHRC( HRC hrc )

Parameters

hrc

Handle to the HRC object.

Return Value

If successful, returns the handle to the recognizer used for the HRC object; otherwise, returns NULL.

See Also

CreateCompatibleHRC, InstallRecognizer


GetInksetInterval

2.0

Retrieves an interval from an inkset.

int GetInksetInterval( HINKSET hinkset, UINT uIndex, LPINTERVAL lpi )

Parameters

hinkset

Handle to an inkset.

uIndex

Zero-based index of an interval or IX_END.

lpi

Pointer to an INTERVAL structure. This can be NULL if the user merely wishes to find out how many intervals are in the inkset.

Return Value

GetInksetInterval returns the number of intervals in the inkset if successful; otherwise, the return value can be one of the following negative values:

Constant	Description
ISR_ERROR	The inkset handle is bad, or a parameter error.
ISR_BADINDEX	The interval index is bad.
ISR_BADINKSET	The inkset has been corrupted or contains bad intervals.
Comments

An application can use GetInksetInterval to enumerate all the intervals in an inkset.

See Also

GetInksetIntervalCount, INTERVAL


GetInksetIntervalCount

2.0

Returns the number of intervals in an inkset.

int GetInksetIntervalCount( HINKSET hinkset )

Parameters

hinkset

Handle to an inkset.

Return Value

Returns the number of intervals in the inkset is successful; otherwise, the return value can be one of the following negative values:

Constant	Description
ISR_ERROR	The inkset handle is bad, or a parameter error.
ISR_BADINKSET	The inkset has been corrupted or contains bad intervals.
Comments

An application uses GetInksetIntervalCount to determine how many intervals there are to enumerate in an inkset. This function can also be used to verify that an inkset is valid.

See Also

GetInksetInterval


GetInternationalHRC

2.0

Retrieves the country, language, script direction, and international preferences from a recognition context HRC object.

int GetInternationalHRC( HRC hrc, UINT FAR * lpuCountry, LPSTR lpszLangCode, UINT FAR * lpfuFlags, UINT FAR * lpuDir )

Parameters

hrc

Handle to the HRC object.

lpuCountry

The country code, or NULL to ignore this value.

lpszLangCode

A buffer large enough to receive a three-letter string (that is, 4 bytes) identifying the language (“enu”, “fra”, etc.). If set to NULL, lpszLangCode is ignored.

lpfuFlags

A pointer to a flags value or NULL to ignore this value. If GetInternationalHRC returns SIH_ALLANSICHAR in lpfuFlags, it means that the user intends to use the entire ANSI character set. If this is the case, the application should ignore the value returned in lpszLangCode, since all the ANSI-based languages are undifferentiated.

lpuDir

Address of a value for the script direction, or NULL to ignore this value. This value specifies which primary and secondary writing directions are in use. Possible values are:

Constant	Description
SSH_RD	To right and down (English).
SSH_RU	To right and up.
SSH_LD	To left and down (Hebrew).
SSH_LU	To left and up.
SSH_DL	Down and to the left (Chinese).
SSH_DR	Down and to the right (Chinese).
SSH_UL	Up and to the left.
SSH_UR	Up and to the right.
Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
See Also

SetInternationalHRC


GetMaxResultsHRC

2.0

Gets the maximum number of recognition results that a recognizer can generate in the current handwriting recognition context HRC object.

int GetMaxResultsHRC( HRC hrc )

Parameters

hrc

Handle to the HRC object.

Return Value

If successful, returns the maximum number of recognition results as a positive number; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
Comments

The default maximum number of results a recognizer can return is 1. An application must call SetMaxResultsHRC to set a different maximum value.

See Also

SetMaxResultsHRC


GetPenAppFlags

2.0

GetPenAppFlags returns task pen flags cached by RegisterPenApp.

UINT GetPenAppFlags(  )

Return Value

GetPenAppFlags returns the flags set by RegisterPenApp for the current task. It extends and replaces the functionality of the version 1.0 function IsPenAware, which will not be supported in future versions of the Pen API.

Applications written specifically for Windows 95 and later versions automatically get RPA_DEFAULT so that any edit controls created by such applications automatically become pen-aware.

If the registration cache has been destroyed (which indicates PENWIN.DLL has been unloaded), this function returns 0.

See Also

RegisterPenApp, IsPenAware


GetPenAsyncState

1.0     2.0

Gets the state of the pen barrel button.

BOOL GetPenAsyncState( UINT wPDK )

Parameters

wPDK

One of the PDK_ values for the barrel buttons. The following table lists the PDK_ values that GetPenAsyncState can query for:

Constant	Description
PDK_BARREL1	Get state of barrel button 1.
PDK_BARREL2	Get state of barrel button 2.
PDK_BARREL3	Get state of barrel button 3.
Return Value

Returns TRUE if the specified barrel button state is currently down; otherwise, the return value is FALSE.


GetPenDataAttributes

2.0

Retrieves information about an HPENDATA object.

int GetPenDataAttributes( HPENDATA hpndt, LPVOID lpvBuffer, UINT uOption )

Parameters

hpndt

Handle to the HPENDATA object.

lpvBuffer

Pointer to a structure whose type depends on uOption, or NULL if the uOption parameter does not require this buffer.

uOption

Specifies the attributes to retrieve. This parameter can be one of the following:

Constant	Description
GPA_MAXLEN	Retrieves the length (in points) of the longest stroke. lpvBuffer is unused and ignored.
GPA_POINTS	Retrieves the total number of points. lpvBuffer is unused and ignored.
GPA_PDTS	Retrieves the PDTS_ bits. lpvBuffer is unused and ignored.
GPA_RATE	Retrieves the sampling rate in samples per second. lpvBuffer is unused and ignored.
GPA_RECTBOUND	Retrieves the bounding rectangle of all pen-down points. lpvBuffer is the address of a RECT structure.
GPA_RECTBOUNDINK	Like GPA_RECTBOUND, retrieves the bounding rectangle of all pen-down points, but inflates the rectangle to accommodate ink width. lpvBuffer is the address of a RECT structure.
GPA_SIZE	Retrieves the size of the pen data memory block in bytes. Because of the potential large size of this value, the return value of the function is not used. Instead, lpvBuffer is the address of a DWORD variable to fill with the size.
GPA_STROKES	Retrieves the total number of strokes, including pen-up strokes. lpvBuffer is unused and ignored.
GPA_TIME	Retrieves the absolute time of creation of the pen data. lpvBuffer is the address of an ABSTIME structure.
GPA_USER	Retrieves the number of user bytes available per stroke: 0, 1, 2, or 4. lpvBuffer is unused and ignored.
GPA_VERSION	Retrieves the version number of the pen data. lpvBuffer is unused and ignored.
Return Value

Returns PDR_OK or an integer value if successful, depending on the uOption parameter.

Comments

GetPenDataAttributes provides enhancements of some of the capabilities of GetPenDataInfo. It also provides additional detailed information taken from the HPENDATA block.

See Also

GetStrokeAttributes, GetPenDataInfo


GetPenDataInfo

1.0     2.0

This function retrieves information from an HPENDATA memory block. It is superseded by the GetPenDataAttributes function.

BOOL GetPenDataInfo( HPENDATA hpndt, LPPENDATAHEADER lppdh, LPPENINFO lppeninfo, DWORD dwReserved )

Parameters

hpndt

Handle to a pen data object that receives the pen data information.

lppdh

Address of a PENDATAHEADER structure, or NULL if not required.

lppeninfo

Address of a PENINFO structure, or NULL if not required.

dwReserved

Reserved for future use. Must be set to 0.

Return Value

Returns TRUE if successful. The return value is FALSE if invalid parameters are used, or if the handle to the pen data is invalid, or if the requested PENINFO does not exist in the pen data.

Comments

This function retrieves the header and pen information in the pen data memory block. If lppeninfo is not NULL and the pen data does not contain pen information, the contents of lppeninfo are not changed. The wPndts member in the PENDATAHEADER structure can be checked to see if the HPENDATA object has a PENINFO structure associated with it (a value of PTDS_NOPENINFO indicates not). The amount of data allocated is contained in the cbSizeUsed member of the PENDATAHEADER structure.

See Also

GetPenDataAttributes


GetPenDataStroke

1.0     2.0

Returns a pointer to stroke data contained in an HPENDATA memory block previously locked with the BeginEnumStrokes function.

Note  This function is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions. Use other services such as GetPenDataAttributes, GetPointsFromPenData, or GetStrokeAttributes to examine an HPENDATA block.

BOOL GetPenDataStroke( LPPENDATA lppd, UINT iStrk, LPPOINT FAR * lplppt, LPVOID FAR * lplpvOem, LPSTROKEINFO lpsi )

Parameters

lppd

Address of the HPENDATA memory block. This parameter is the value returned by a previous call to the BeginEnumStrokes function.

iStrk

Zero-based index of the stroke to retrieve.

lplppt

Address of a pointer to a point. The pointer returned by the function will point to the first point of the stroke inside the pen data object. This parameter can be NULL if point data is not required.

lplpvOem

Address of a void pointer. The pointer returned by the function will point to the OEM data block of the stroke inside the pen data object. The format of the OEM data is specified by the rgoempeninfo member in the PENINFO structure. This parameter can be NULL if OEM data is not required.

lpsi

Address of a STROKEINFO structure. This parameter can be NULL if stroke information is not required.

Return Value

Returns TRUE if successful. If the stroke requested is out of range, the function returns FALSE.

Comments

GetPenDataStroke returns in lpsi a pointer to a STROKEINFO structure created from the stroke referenced by iStrk. The lpsi parameter does not point directly into the HPENDATA memory block.

However, the lplppt argument points to the first point of the stroke inside the HPENDATA block. For a description of how the GetPenDataStroke function has changed in version 2.0 of the Pen API, refer to AppendixA.

Applications must call BeginEnumStrokes before calling GetPenDataStroke. After the last call to GetPenDataStroke, the application must call EndEnumStrokes. Once EndEnumStrokes is called, the data that lplppt and lplpvOem point to is no longer valid.

Under no circumstances should an application modify data directly within an HPENDATA block. Doing so can invalidate other information in the block. To modify an HPENDATA block, use one of the Pen API functions listed in Chapter 4, “The Inking Process.”

See Also

BeginEnumStrokes, EndEnumStrokes, GetStrokeAttributes


GetPenHwEventData

1.0     2.0

Gets the pen data associated with events in a given range.

Note  This function is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions. Use DoDefaultPenInput or GetPenInput instead.

REC GetPenHwEventData( UINT wEventRefBeg, UINT wEventRefEnd, LPPOINT lppt, LPVOID lpvOemData, int cPntMax, LPSTROKEINFO lpsi )

Parameters

wEventRefBeg

Beginning pen event.

wEventRefEnd

Ending pen event.

lppt

Address of a an array of POINT structures. The size of the array must be at least sizeof( POINT ) multiplied by cPntMax.

lpvOemData

Buffer to fill with OEM-specific data. This can be NULL if no data is required.

cPntMax

Maximum number of samples to return.

lpsi

Address of a STROKEINFO structure that receives the stroke information, including the count of points and point state. Also included is the time stamp of the first point returned in the buffer, which is the number of milliseconds that have elapsed since Windows started.

Return Value

Returns REC_OK if successful; otherwise, the return value can be one of the following:

Constant	Description
REC_BUFFERTOOSMALL	The array identified by lppt is not large enough to hold all the points requested.
REC_PARAMERROR	Invalid parameter.
Comments

This function fetches all data collected from the pen event wEventRefBeg up to but not including the pen event wEventRefEnd. If wEventRefBeg equals wEventRefEnd, GetPenHwEventData retrieves the single pen event associated with wEventRefBeg.

The values for wEventRefBeg and wEventRefEnd are obtained by calling the Windows GetMessageExtraInfo function.

This function can be called directly from an application. If it returns REC_BUFFERTOOSMALL, no data is returned and the cPnt member of lpsi contains the number of points between wEventRefBeg and wEventRefEnd. If REC_OK is returned, the cPnt member contains the number of valid points placed in the array at lppt.

See Also

STROKEINFO


GetPenInput

2.0

Collects data after StartPenInput has started pen input.

int GetPenInput( HPCM hpcm, LPPOINT lppt, LPVOID lpvOem, UINT fuOemFlags, UINT cPntMax, LPSTROKEINFO lpsi )

Parameters

hpcm

Handle to the current collection. This is the return value from StartPenInput.

lppt

Address of an array of POINT structures. The array must consist of at least cPntMax structures.

lpvOem

The address of a buffer of OEM data associated with each point. This parameter can be NULL if the application does not require OEM data.

fuOemFlags

Flags specifying which OEM data to retrieve. If this parameter is NULL, all OEM data provided by the tablet is returned in the order specified by the rgoempeninfo array in PENINFO.

These flags have an implicit order. For example, if pressure and barrel rotation are specified, cPntMax pairs of these data are returned, in the order [pressure, rotation], [pressure, rotation], and so on.

Constant	Description
PHW_PRESSURE	Retrieve pressure data.
PHW_HEIGHT	Retrieve height data.
PHW_ANGLEXY	Retrieve data pertaining to the x- and y-coordinates.
PHW_ANGLEZ	Retrieve data pertaining to the z-coordinates.
PHW_BARRELROTATION	Retrieve barrel-rotation data.
PHW_OEMSPECIFIC	Retrieve OEM-specific data.
PHW_PDK	Retrieve per-point PDK_ information in OEM data.
cPntMax

The number of POINT structures in the array at lppt. This is the maximum number of points to return and also the maximum number of OEM items the buffer at lpvOem can hold.

lpsi

A pointer to a STROKEINFO structure. This structure receives information about the first point of the collection of points placed into the array at lppt. The cbPnts member contains the packet ID of the first point. All returned points in the collection have the same tip polarity (that is, up or down) as the first point.

Return Value

Returns 0 if there are no points available. If the return value is positive, the value is the number of points copied to the lppt (and, optionally, lpvOem) buffers. Otherwise, the return value is one of the following:

Constant	Description
PCMR_APPTERMINATED	Input has already terminated because the application called StopPenInput. There are no more points to retrieve.
PCMR_EVENTLOCK	An event must be taken out of the queue using the Windows functions PeekMessage or GetMessage before any more points can be retrieved using GetPenInput.
PCMR_INVALIDCOLLECTION	The hpcm handle is invalid because the calling application did not start input with StartPenInput.
PCMR_TERMTIMEOUT	Input has already terminated because the specified time-out period has elapsed.
PCMR_TERMRANGE	Input has already terminated because the pen has left the range of the tablet’s zone of sensitivity.
PCMR_TERMPENUP	Input has already terminated because the pen was lifted from the tablet.
PCMR_TERMEX	Input has already terminated because the pen went down in a specified exclusion rectangle or region.
PCMR_TERMBOUND	Input has already terminated because the pen went down outside a specified bounding rectangle or region.
Comments

Once an application initiates pen-input collection by calling StartPenInput, the application then calls the GetPenInput function frequently to retrieve the actual data arriving from the pen device. This can be done by responding to hardware events or by continuously polling.

In the polling model, the application repeatedly calls GetPenInput to get data. It is important for the application to yield periodically; for example, by calling PeekMessage. A fast loop can potentially process the points before the system can collect more. In this case, successive calls to GetPenInput return 0 until the user writes some more. Polling is typically terminated when GetPenInput detects and returns a termination condition specified in StartPenInput.

In the event model, the application calls GetPenInput on receipt of a WM_PENEVENT message. All points up to this event are returned to the caller. An application can retrieve all available data in a short loop, until GetPenInput returns PCMR_EVENTLOCK. The application then falls out of the loop and exits the window procedure. The process begins again when the window procedure is called in response to another WM_PENEVENT message in the application’s message queue.

If lpvOem is not NULL, the buffer must be large enough to hold cPntMax OEM data packets. The size of each packet is the width specified in the cbOemData member of the PENINFO structure, plus sizeof( UINT ) if PDK_ values are required.

Example

The following code example gathers more pen input for use by the recognizer. Assume the application has already called StartPenInput and is using the messaging collection model.

POINT	rgPnt[cbBuffer];

STROKEINFO	si;

// ... in WM_PENEVENT message handler:

switch (wParam)

{

.

.

.

case PE_PENUP:

case PE_PENMOVE:

case PE_TERMINATING:

// Get all the points collected since the last message

while ( (iRet = GetPenInput( hpcm, rgPnt, NULL, 0,

 cbBuffer, &si) ) > 0)

{

// Add pen data to recognition context and def process

AddPenInputHRC( vhrc, rgPnt, NULL, 0, &si );

ProcessHRC( vhrc, PH_DEFAULT );

}

break;

See Also

PeekPenInput,  StartPenInput,  PDK_


GetPenResource

2.0

The GetPenResource function retrieves a copy of a pen services resource. (Japanese version only.)

HANDLE GetPenResource( WPARAM wParam )

Parameters

wParam

Specifies the pen services resource for which to retrieve a handle. This may be one of the following:

Constant	Description
GPR_CURSPEN	Standard pen cursor.
GPR_CURSCOPY	Copy cursor.
GPR_CURSUNKNOWN	Unknown cursor.
GPR_CURSERASE	Erase cursor.
GPR_BMCRMONO	Monochrome Return bitmap.
GPR_BMLFMONO	Monochrome LineFeed bitmap.
GPR_BMTABMONO	Monochrome Tab bitmap.
GPR_BMDELETE	Delete bitmap.
GPR_BMLENSBTN	Lens buttonface bitmap.
GPR_BMHSPMONO	Hankaku space bitmap (Japanese version only).
GPR_BMZSPMONO	Zenkaku space bitmap (Japanese version only).
Comments

An application can use this function to get a copy of a cursor or bitmap used by pen services. It is the application's responsibility to destroy the object by calling either the DestroyCursor or DeleteObject Windows API.

Return Value

This function returns a handle to an object, depending on the index specified by wParam if successful. Otherwise the return value is NULL.


GetPenMiscInfo

1.0     2.0

Retrieves values pertaining to the pen system.

LONG GetPenMiscInfo( WPARAM wParam, LPARAM lParam )

Parameters

wParam

Specifies the identifier of the pen system value to retrieve. The pen system identifier must be a PMI_ value. See the table below for the possible PMI_ values in wParam.

lParam

Address of storage for data. This must not be NULL. The calling application must ensure that there is sufficient room to store the requested information. The type of storage object that lParam points to depends on wParam, as described in the following table. For each value of wParam in the first column, the second column describes the corresponding requirement for lParam:

wParam constant	LParam description
PMI_BEDIT	lParam is the address of a BOXEDITINFO structure. Boxed edit information.
PMI_CXTABLET	lParam is a far pointer to a UINT value specifying the width of tablet (in units of 0.001 inch) if present; otherwise,  the width of the screen.
PMI_CYTABLET	lParam is a far pointer to a UINT value specifying the height of tablet (in units of 0.001 inch) if present; otherwise,  the height of the screen.
PMI_INDEXFROMRGB	lParam is a far pointer to a DWORD value. On entry, lParam is the address of an RGB ink color value. On return, the low-order word of lParam is replaced with an index in the range 0 to 15 for the closest standard ink color and the high-order word is 0.
PMI_ENABLEFLAGS	lParam is a far pointer to a WORD value containing a flag describing whether certain Pen API features are enabled. The flags can be a combination of the following values: PWE_AUTOWRITE   Enable pen functionality where the I-Beam cursor is present. PWE_ACTIONHANDLES   Enable action handles in controls. PWE_INPUTCURSOR   Show cursor while writing. PWE_LENS   Enable pop-up letter guides (that is, the lens).
PMI_PENTIP	lParam is the address of a PENTIP structure.
PMI_RGBFROMINDEX	lParam is the address of a DWORD value. On entry, lParam is the address of an index in the range 0 to 15; on return, this value at this address is replaced with the standard RGB ink color value.
wParam constant	LParam description
PMI_SYSFLAGS	lParam is a far pointer to a WORD value containing a flag describing which pen system components are loaded. The flags can be a combination of the following values: PWF_RC1   Support available for Pen API version 1.0 Recognition Context (RC) and associated functions. PWF_PEN   Pen/tablet hardware is present. PWF_INKDISPLAY   Ink-compatible display driver is present. PWF_RECOGNIZER   System recognizer is present. PWF_BEDIT   Boxed edit (bedit) control is available. PWF_HEDIT   Handwriting edit (hedit) control is available. PWF_IEDIT   Ink edit (iedit) control is available. PWF_ENHANCED   Enhanced features, including gesture support and 1 millisecond timing, are available. PWF_FULL   All components listed above are present..
PMI_SYSREC	lParam is a far pointer to an HREC value which is the handle of the system recognizer, if present.
PMI_TICKREF	lParam is the address of an ABSTIME structure indicating  the absolute reference time that the system uses to calculate time-stamps for strokes in pen data objects and inkset
PMI_TIMEOUT	lParam is a far pointer to a UINT value indicating time-out value to end hand-writing input, in milliseconds.
PMI_TIMEOUTGEST	lParam is a far pointer to a UINT value indicating time-out value to end a gesture, in milliseconds.
PMI_TIMEOUTSEL	lParam is a far pointer to a UINT value indicating  the time-out value in milli-seconds for press-and-hold gesture. The range of permissible values is 0 to 5000. If press-and-hold has been disabled, this value is 65,535.
Return Value

The return value is PMIR_OK if successful; otherwise it is one of the following negative error values:

Constant	Description
PMIR_INDEX	wParam is out of range.
PMIR_NA	Support for this value of wParam is not available.
PMIR_VALUE	lParam is NULL or a invalid pointer.
Comments

The information type returned varies depending on the index. Note that if a UINT is expected, for example, it is an error to provide the address of a DWORD variable without explicitly setting the HIWORD to 0. This function only sets the LOWORD in this case, and since the variable is usually declared on the stack, there would be an unknown value in the HIWORD. See the examples below.

If wParam is PMI_INDEXFROMRGB or PMI_RGBFROMINDEX, the standard pen-tip color table is as follows:

00  black       RGB(  0,   0,   0)

01  dark blue   RGB(  0,   0, 127)

02  dark green  RGB(  0, 127,   0)

03  dark cyan   RGB(  0, 127, 127)

04  dark red    RGB(127,   0,   0)

05  purple      RGB(127,   0, 127)

06  brown       RGB(127, 127,   0)

07  gray        RGB(127, 127, 127)

08  light gray  RGB(192, 192, 192)

09  blue        RGB(  0,   0, 255)

10  green       RGB(  0, 255,   0)

11  cyan        RGB(  0, 255, 255)

12  red         RGB(255,   0,   0)

13  magenta     RGB(255,   0, 255)

14  yellow      RGB(255, 255,   0)

15  white       RGB(255, 255, 255)

Example

The following code sample retrieves the timeout and pen tip:

UINT uTimeout;

PENTIP tip;

GetPenMiscInfo( PMI_TIMEOUT, (LPARAM)(UINT FAR *)&utimeout );

GetPenMiscInfo( PMI_PENTIP, (LPARAM)(LPPENTIP)&tip );

Note that the following is an error, since the HIWORD is undefined:

DWORD dwTimeout;

GetPenMiscInfo( PMI_TIMEOUT, (LPARAM)&dwtimeout );	  // Wrong!

See Also

SetPenMiscInfo,  PMI_


GetPointsFromPenData

1.0     2.0

Retrieves a specified range of points.

BOOL GetPointsFromPenData( HPENDATA hpndt, UINT iStrk, UINT iPnt, UINT cPnts, LPPOINT lppt )

Parameters

hpndt

Handle to a pen data object.

iStrk

The zero-based stroke index from which points are retrieved.

iPnt

First point to retrieve from the specified stroke.

cPnts

Number of points to retrieve. If this value is 0, the function returns TRUE.

lppt

Address of buffer to fill with points.

Return Value

Returns TRUE if successful, or FALSE if the requested points are out of range.

Comments

GetPointsFromPenData performs a function similar to GetPenDataStroke in that it retrieves information from an HPENDATA memory block. But GetPointsFromPenData copies the required data to buffers supplied by the application, rather than simply returning pointers to the original data in the global heap.

An application can also request a copy of a particular subset of points within a stroke. In this case, iPnt identifies the first point and cPnts is the number of points to retrieve. This allows an application to digest the points in an HPENDATA block a few at a time to avoid having to allocate a large block of memory for the entire set of points.

GetPointsFromPenData returns the last point in a stroke if the iPnt argument is set to a value larger than the total number of points in the stroke. In the same manner, the function returns the points of the last stroke if iStrk exceeds the total number of strokes in the HPENDATA block. If the count of points to return is 1 and iPnt is beyond the last point in the stroke, the function returns the last point in the stroke.

See Also

GetPenDataStroke


GetResultsHRC

2.0

Retrieves results from a recognition context HRC. A recognizer must export this function.

int GetResultsHRC( HRC hrc, UINT uType, LPHRCRESULT rghrcresults, UINT cResults )

Parameters

hrc

Handle to the HRC object.

uType

Specifies the type of expected results. This can be one of the following values:

Constant	Description
GRH_ALL	Return all results.
GRH_GESTURE	Return results of type gesture only.
GRH_NONGESTURE	Return all results not of type gesture.
rghrcresults

Address of an array of HRCRESULT objects.

cResults

The size of the rghrcresults array, in objects. The actual size in bytes can be calculated by multiplying cResults by the size of HRCRESULT. This parameter must be greater than 0.

Return Value

Returns the actual number of results returned if successful. This can be 0; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_HOOKED	A hook preempted the result.
HRCR_MEMERR	Insufficient memory.
Comments

The actual number of results returned by this function may be less than the number specified by cResults. It is also less than or equal to the count specified at the creation of hrc by the cMaxResults parameter in SetMaxResultsHRC, regardless of the size of the rghrcresults array.

A return value of 0 indicates that the recognizer was not able to recognize any of the input, even if coerced by a word list set into the HRC. A recognizer should never return a result consisting entirely of SYV_UNKNOWN symbols.

The calling application must explicitly destroy each valid result using DestroyHRCRESULT. However, if the return value is 0 or negative, the contents of the rghrcresults array are undefined (though not NULL) and DestroyHRCRESULT must not be called.

See Also

DestroyHRCRESULT


GetStrokeAttributes

2.0

Retrieves information about a stroke in an HPENDATA object.

int GetStrokeAttributes( HPENDATA hpndt, UINT iStrk, LPVOID lpvBuffer, UINT uOption )

Parameters

hpndt

Handle to the HPENDATA object, which must not be compressed.

iStrk

Zero-based stroke index. If there are no strokes in the pen data, an index of 0 can be used to retrieve the default attributes for the pen data. A value of IX_END specifies the last available stroke in the pen data.

lpvBuffer

Pointer to a structure whose type depends on uOption, or NULL if the uOption parameter does not require this buffer.

uOption

Specifies the attributes to retrieve. This parameter has one of the following values:

Constant	Description
GSA_DOWN	Retrieve the up/down state of the pen tip for this stroke. Returns 1 if the stroke is a down-stroke or 0 if it is an up-stroke. lpvBuffer is unused and ignored.
GSA_PENTIP	Retrieve the pen-tip characteristics (color, width, nib) used by the stroke specified by iStrk. lpvBuffer is a pointer to a PENTIP structure. Return value is PDR_OK.
GSA_PENTIPCLASS	Retrieve the pen-tip characteristics (color, width, nib), if any, for the class of strokes of which the stroke specified by iStrk is a member. lpvBuffer is a pointer to a PENTIP structure. Return value is PDR_OK.
GSA_RECTBOUND	Retrieve the bounding rectangle of the specified stroke. lpvBuffer is a pointer to a RECT structure. Return value is PDR_OK.
GSA_SELECT	Retrieve the selection status of the specified stroke. lpvBuffer is unused and ignored. Returns a nonzero value if the stroke is selected; otherwise, the return value is 0.
GSA_SIZE	Retrieve size of stroke in points and bytes. lpvBuffer is a pointer to a double-word value, or NULL. LOWORD(*(LPDWORD)lpvBuffer) is the size in points, and HIWORD(*(LPDWORD)lpvBuffer) is the size in bytes. Return value is PDR_OK.
GSA_TIME	Retrieve the absolute time of the stroke. lpvBuffer is a pointer to an ABSTIME structure; it cannot be NULL. The sec field specifies the number of seconds since Jan 1, 1970, and the ms field specifies the number of milliseconds offset from that time to the beginning of the stroke. Return value is PDR_OK.
GSA_USER	Retrieve the user value, if any, for the stroke. lpvBuffer is a pointer to a double-word value, or NULL. Returns the number of bytes of user data available in the stroke: 0, 1, 2, or 4.
GSA_USERCLASS	Retrieve the user value, if any, for the class of strokes of which the stroke specified by iStrk is a member. lpvBuffer is a pointer to a double-word value, or NULL. The return value is 4 because the user value in the strokes class table is a doubleword value.
Return Value

Returns PDR_OK or an integer value if successful, as described for the uOption parameter. If an error occurs, returns one of the following:

Constant	Description
PDR_COMPRESSED	Pen data is compressed.
PDR_ERROR	Parameter or other unspecified error.
PDR_MEMERR	Memory error.
PDR_PNDTERR	Invalid pen data.
PDR_STRKINDEXERR	Invalid stroke index.
PDR_TIMESTAMPERR	Timing information was removed.
PDR_VERSIONERR	Could not convert old pen data.
See Also

CreatePenDataEx, GetStrokeTableAttributes, SetStrokeAttributes, SetStrokeTableAttributes, PENTIP


GetStrokeTableAttributes

2.0

Retrieves information about a stroke’s class from the table in the PENDATAHEADER of an HPENDATA object.

int GetStrokeTableAttributes( HPENDATA hpndt, UINT iTblEntry, LPVOID lpvBuffer, UINT uOption )

Parameters

hpndt

Handle to the HPENDATA object, which must not be compressed.

iTblEntry

Zero-based table index to the class entry in the pen data header.

lpvBuffer

Pointer to a structure whose type depends on uOption, or NULL if the uOption parameter does not require this buffer.

uOption

Specifies the attributes to retrieve. This parameter can be one of the following:

Constant	Description
GSA_PENTIPTABLE	Retrieve the pen-tip characteristics (color, width, nib) of the class of strokes specified by iTblEntry. lpvBuffer is a pointer to a PENTIP structure. Return value is the number of strokes using this class.
GSA_SIZETABLE	Retrieve the number of entries in the stroke class table. iTblEntry and lpvBuffer are unused and ignored. Return value is the number of classes used in the stroke class table.
GSA_USERTABLE	Retrieve the user value, if any, of the class of strokes specified by iTblEntry. lpvBuffer is a pointer to a doubleword value, or NULL. The number of bytes that are valid in lpvBuffer depends on flags set in CreatePenDataEx. This number is returned by the function, and can be 0 (no user value), 1 (byte value),  2 (word value), or 4 (doubleword value). Return value  is 4, because the user value in the stroke class table  is a doubleword value.
Return Value

Returns an integer if successful, depending on the value of uOption, as described above. If an error occurs, returns one of the following:

Constant	Description
PDR_COMPRESSED	Pen data is compressed.
PDR_ERROR	Parameter or other unspecified error.
PDR_MEMERR	Memory error.
PDR_PNDTERR	Invalid pen data.
PDR_VERSIONERR	Could not convert old pen data.
See Also

CreatePenDataEx, GetStrokeAttributes, SetStrokeAttributes, SetStrokeTableAttributes, PENTIP


GetSymbolCount

1.0     2.0

Returns the number of symbol strings contained in a symbol graph SYG.

int GetSymbolCount( LPSYG lpsyg )

Parameters

lpsyg

Address of the symbol graph.

Return Value

Returns the number of possible symbol strings that can be generated from the symbol graph. Returns −1 for any graph that can generate more than 32,767 symbol strings, or if there is a parameter error.

Example

For example, if the symbol graph pointed to by lpsyg is

ex {a | u} mple

GetSymbolCount returns the value 2 because the graph contains two symbol strings (“example” and “exumple”).

See Also

EnumSymbols, FirstSymbolFromGraph, GetSymbolMaxLength SYG, SYV_


GetSymbolCountHRCRESULT

2.0

Retrieves the count of symbols available in a recognition result. A recognizer must export this function.

int GetSymbolCountHRCRESULT( HRCRESULT hrcresult )

Parameters

hrcresult

Handle of a results object.

Return Value

Returns the count of symbols if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
Comments

This function is typically called before GetSymbolsHRCRESULT to determine the size of a buffer required to store the symbol values returned in a recognition result. To calculate the size of the buffer, multiply the value returned by this function by sizeof( SYV ).

See Also

GetSymbolsHRCRESULT, SYV_


GetSymbolMaxLength

1.0     2.0

Returns the length of the longest symbol string contained in a symbol graph SYG.

int GetSymbolMaxLength( LPSYG lpsyg )

Parameters

lpsyg

Address of the symbol graph.

Return Value

Returns the number of symbols in the longest symbol string that can be generated from the symbol graph, or −1 if there is a parameter error.

Example

For example, if the symbol graph pointed to by lpsyg is

ab {c | de} f

GetSymbolMaxLength returns 5 because the longest string is “abdef”.

See Also

EnumSymbols, FirstSymbolFromGraph, SYG, SYV_


GetSymbolsHRCRESULT

2.0

Retrieves an array of symbol values corresponding to a recognition result. A recognizer must export this function.

int GetSymbolsHRCRESULT( HRCRESULT hrcresult, UINT iSyv, LPSYV rgsyv, UINT cSyv )

Parameters

hrcresult

Handle of a results object.

iSyv

Index of the first symbol of interest in the results object.

rgsyv

Address of a buffer in which to put the symbols. The array must be large enough to store cSyv symbols.

cSyv

The size of rgsyv in symbols (not bytes). This is the number of symbols to be returned. A value of 0 is legal, in which case the function simply returns 0.

Return Value

Returns the count of symbols copied, if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
Comments

It is possible to allocate a small buffer in rgsyv and call this function repeatedly, incrementing the index iSyv each time by the number of symbols returned in the previous call, until the function returns 0.

Example

The following example gets a character result, using a small buffer:

#define CBCHBUF 1024	// Char buffer

#define CSYVMAX 32	// Relatively small symbol chunk

HRC	  vhrc; 	      // Handle to a handwriting context

HRCRESULT vhrcresult;	      // Handle to a recognition result

SYV	  vrgsyv[CSYVMAX];    // Symbol result buffer

char	  vrgcBuff[CBCHBUF];  // Buffer for recognition results

.

.	     // Code that creates HRC, gets input, etc....

.

EndPenInputHRC( vhrc );     // Tell recognizer no more ink

ProcessHRC( vhrc, PH_MAX ); // Finish recognition

.

.	     // Retrieve a handle to the results

.

if (GetResultsHRC( vhrc, &vhrcresult, 1 ) > 0)

{

int i = 0, cSyv;

// Retrieve some symbols

while ((cSyv = GetSymbolsHRCRESULT( vhrcresult,

i, vrgsyv, CSYVMAX )) > 0)

{

if (i + cSyv + 1 > CBCHBUF) // Don't overflow buffer

cSyv = CBCHBUF - i - 1;

if (cSyv > 0)	    // Still have something?

{

SymbolToCharacter( vrgsyv, cSyv, vrgcBuff + i, NULL );

i += cSyv;

}

if (i + 1 >= CBCHBUF)

break;

}

vrgcBuff[i] = chNull;	 // Terminate string

}

DestroyHRCRESULT( vhrcresult );  // We're finished with result

vhrcresult = NULL;

DestroyHRC( vhrc );	 // Finished with this HRC session

vhrc = NULL;

See Also

GetSymbolCountHRCRESULT, SYV_


GetVersionPenWin

1.0     2.0

Retrieves the Pen API version number.

UINT GetVersionPenWin(  )

Return Value

The low-order byte of the return value specifies the major (version) number. The high-order byte specifies the minor (revision) number.


GetWordlistCoercionHRC

2.0

Retrieves the current word list coercion setting in a handwriting-recognition context HRC.

int GetWordlistCoercionHRC( HRC hrc )

Parameters

hrc

Handle to the HRC object.

Return Value

If successful, returns one of the following values:

Constant	Description
SCH_ADVISE	The word list is a hint to the recognizer, and results are not strongly coerced to match the word list.
SCH_FORCE	If results do not match the word list, the closest fit is returned.
SCH_NONE	Do not coerce. This flag can be used to turn off a previous request.
Otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
See Also

SetWordlistCoercionHRC


GetWordlistHRC

2.0

Retrieves a word list from a recognition context HRC.

int GetWordlistHRC( HRC hrc, LPHWL lphwl )

Parameters

hrc

Handle to the HRC object.

lphwl

Address of a handle to a word list. The recognizer sets the handle to NULL if the recognition context does not contain a word list.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

An HRC can be configured for only one word list at a time. This is independent of the recognizer’s dictionary, which can be manipulated through the EnableSystemDictionaryHRC function.

For a description of word lists and how a recognizer uses them, see “Configuring the HRC” in Chapter 5, “The Recognition Process.”

See Also

SetWordlistHRC


HitTestPenData

2.0

Determines if a given point lies on or near the pen-down strokes contained in an HPENDATA object.

int HitTestPenData( HPENDATA hpndt, LPPOINT lppt, UINT dThresh, UINT FAR* lpiStrk, UINT FAR* lpiPnt )

Parameters

hpndt

Handle to the HPENDATA object. HitTestPenData does not alter the data in the HPENDATA object.

lppt

Address of a POINT structure containing the point to test.

dThresh

Threshold around the point given in lppt. The point lies at the center of a square with sides of length dThresh. If HitTestPenData finds a point in the HPENDATA object that lies in the square, it indicates a “hit.” dThresh must have the same scaling units as the points in the HPENDATA or the result will not be correct. If dThresh is 0, HitTestPenData assumes a default threshold value of 3.

lpiStrk

Stroke index from which to begin testing. After HitTestPenData returns from a successful test, the variable that lpiStrk points to contains the index of the hit stroke.

lpiPnt

Point index from which to begin testing. After HitTestPenData returns from a successful test, the variable that lpiPnt points to contains the index of the hit point in the stroke indicated by lpiStrk.

Return Value

Returns one of the following if successful:

Constant	Description
PDR_HIT	The point hits (intersects) the pen data or falls within the provided threshold around a particular point in the pen data as specified by the stroke and the point indices. The stroke and point values are returned in lpiStrk and lpiPnt, respectively.
PDR_NOHIT	The point does not hit (intersect) the pen data nor does it fall within the provided threshold around a particular point in the pen data as specified by the stroke and the point indices.
Otherwise, the function returns one of the following negative values:

Constant	Description
PDR_COMPRESSED	Pen data is compressed.
PDR_ERROR	Parameter or other unspecified error.
PDR_MEMERR	Memory error.
PDR_PNDTERR	Invalid pen data.
PDR_PNTINDEXERR	Invalid point index.
PDR_STRKINDEXERR	Invalid stroke index.
PDR_VERSIONERR	Could not convert old pen data.
Comments

HitTestPenData checks whether the point specified by lppt falls within the threshold specified by dThresh around a point in the pen data, depending on the zero-based starting stroke and point indices specified by lpiStrk and lpiPnt. This function tests only down strokes in the pen data. If lpiStrk is greater than the number of strokes in the pen data, testing starts from the first stroke.

Similarly, if lpiPnt is greater than the number of points in the stroke, testing starts from the first point in that stroke. The first point in the first stroke (from the specified indices) that meets the test condition is returned via lpiPnt and lpiStrk, respectively.

In any case, HitTestPenData accounts for the width of the ink trail. If the value given in dThresh is less than the ink width, HitTestPenData ignores the specified value of dThresh and instead uses the ink width as the threshold.

HitTestPenData does not consider pen-up strokes.


InitRC

1.0     2.0

Initializes an RC structure with default values.

Note  This function is provided only for compatibility with version 1.0 of the Pen API, and will not be supported in future versions.

void InitRC( HWND hwnd, LPRC lprc )

Parameters

hwnd

Handle to a window.

lprc

Address of the RC structure to initialize.

Return Value

This function does not return a value.

Comments

InitRC serves little purpose in applications that conform to version 2.0 of the Pen API. Under version 2.0, a recognizer maintains an HRC object, which makes the RC structure obsolete.

For suggestions on how to update a version 1.0 application to remove services that rely on RC, see the section “The RC Structure” in Appendix A.

InitRC initializes an RC structure with default values, many of which come from the global RC structure. The application can use the initialized RC structure when calling the Recognize function. Although an application can change any of these values, it should be careful about changing those items that can be set by the user through the Windows Control Panel.

InitRC sets the bounding rectangle to the client area of the window identified by hwnd. The bounding rectangle is valid only until the window is resized or moved. When this occurs, the application must again call InitRC to update the rectBound member of the RC structure or correct rectBound manually. If the window handle hwnd is NULL, the bounding rectangle and hwnd remain uninitialized. The application must set the hwnd member to a valid window before calling Recognize or RecognizeData.

The following table describes the default values used to initialize the RC structure. Values not listed in the table come from the global RC. Some of the global default values can be modified by the user in Control Panel.

Value	Description
rc.alc	ALC_DEFAULT. The function uses the complete alphabet and all gestures. The exact character set depends on the recognizer.
rc.lRcOptions	Zero.
rc.hwnd	hwnd (the first argument of InitRC).
rc.wResultMode	RRM_COMPLETE.
rc.rectBound	(0,0,0,0) or client rectangle of hwnd if hwnd is not NULL.
rc.lPcm	PCM_ADDDEFAULTS, or PCM_ADDDEFAULTS | PCM_RECTBOUND if hwnd is not NULL.
rc.rectExclude	(0,0,0,0).
rc.guide	(0,0,0,0,0,0,0).
rc.wRcOrient	RCOR_NORMAL.
rc.wRcDirect	0x0103
Members the user can change through the system Control Panel are filled with values indicating that the system default should be used. These placeholder values are RC_WDEFAULT or RC_LDEFAULT, depending on whether the member is a UINT or LONG value. During the processing of ProcessWriting, Recognize, or RecognizeData, these values are replaced with the current system defaults before the RC structure is passed to the recognizer. If the PCM_ADDDEFAULTS flag is set in lPcm, the values of the lPcm member in the global RC are combined with the current lPcm values with OR operators at the time the recognizer is called. If the high bit is set in wRcPreferences, the values of the wRcPreferences member in the global RC are combined with the current wRcPreferences values with bitwise-OR operators at the time the recognizer is called.

The following table gives the default values for the members of the RC structure:

Value	Description
rc.hrec	RC_WDEFAULT
rc.lpfnYield	RC_LDEFAULT
rc.lpUser	RC_LDEFAULT
rc.wCountry	RC_WDEFAULT
rc.wIntlPreferences	RC_WDEFAULTFLAGS
rc.lpLanguage	RC_LDEFAULT
rc.rglpdf	RC_LDEFAULT
rc.wTryDictionary	RC_WDEFAULT
rc.clErrorLevel	RC_WDEFAULT
rc.wTimeOut	RC_WDEFAULT
rc.wRcPreferences	RC_WDEFAULTFLAGS
rc.nInkWidth	RC_WDEFAULT
rc.rgbInk	RC_LDEFAULT
rc.alcPriority	ALC_NOPRIORITY
rc.rgbfAlc	Array initialized to 0
The RC structure pointed to in the RCRESULT structure is a copy of the original RC structure passed as a parameter to Recognize. In the copy, default values are replaced. All coordinates are in the tablet coordinate system and the lRcOptions member has the RCO_TABLETCOORD flag set.

See Also

Recognize,  RecognizeData,  RC,  ALC_,  PCM_,  RCO_


InsertPenData

2.0

Merges two blocks of pen data at the specified stroke index.

int InsertPenData( HPENDATA hpndtDst, HPENDATA hpndtSrc, UINT iStrk )

Parameters

hpndtDst

Handle of the pen data object to merge into. When this function returns, this is the handle of the merged data.

hpndtSrc

Handle of the pen data object to merge from.

iStrk

Stroke index. The merge operation occurs before this index. This parameter can also be IX_END to append hpndtSrc to the end of hpndtDst.

Return Value

Returns PDR_OK if successful; otherwise, the return value is one of the following negative values:

Constant	Description
PDR_COMPRESSED	Pen data is compressed.
PDR_ERROR	Parameter or other unspecified error.
PDR_MEMERR	Out of memory.
PDR_OEMDATAERR	Incompatible OEM data in the two pen data objects.
PDR_STRKINDEXERR	Invalid stroke index.
PDR_TIMESTAMPERR	Incompatible time fields in the two pen data objects.
PDR_USERDATAERR	Incompatible user space in the two pen data objects.
PDR_VERSIONERR	Could not convert old pen data object.
Comments

InsertPenData merges two blocks of pen data starting at the zero-based stroke index specified by iStrk of the destination pen data.

The blocks of pen data to be merged must be compatible. The calling application should ensure that the blocks of data are in the same scaling mode. The user space, if present, should be of the same size. OEM data, if present, must be compatible and of the same type. The application can use TrimPenData to delete certain information from either the source or the destination HPENDATA object to make it compatible. If hpndtDst has timing information and hpndtSrc does not, the merge fails. However, if hpndtDst does not have timing information and hpndtSrc does have it, the timing is stripped from hpndtSrc.

For a description of timing information, see “The HINKSET Object” in Chapter 4, “The Inking Process.”

See Also

InsertPenDataStroke, InsertPenDataPoints, MetricScalePenData, TrimPenData, CreatePenDataEx


InsertPenDataPoints

2.0

Inserts points into an existing HPENDATA object.

int InsertPenDataPoints( HPENDATA hpndt, UINT iStrk, UINT iPnt, UINT cPnts, LPPOINT lppt, LPVOID lpvOem )

Parameters

hpndt

Handle to an HPENDATA object.

iStrk

Zero-based index of the stroke into which the points are inserted. If this value is IX_END, the points are inserted in the last stroke.

iPnt

Zero-based index of the point in the stroke before which the points are inserted. If this value is IX_END, the points are appended to the end of the stroke.

cPnts

Total number of points to be inserted. If this is 0, the function returns PDR_OK without taking any other action.

lppt

Address of an array of POINT structures containing the points to be inserted.

lpvOem

Address of a buffer containing the OEM data to be inserted. This value can be NULL only if the HPENDATA object does not have OEM data or a PENINFO structure.

Return Value

Returns PDR_OK if successful; otherwise, the return value can be one of the following negative values:

Constant	Description
PDR_COMPRESSED	Pen data is compressed.
PDR_ERROR	Parameter or other unspecified error.
PDR_MEMERR	Out of memory.
PDR_STRKINDEXERR	Invalid stroke index.
PDR_PNTINDEXERR	Invalid point index.
PDR_VERSIONERR	Could not convert old pen data object.
Comments

InsertPenDataPoints inserts points into an existing stroke of the specified pen data object. It does not create a new stroke. (Use the InsertPenDataStroke function to insert new strokes into the pen data object.) The stroke attributes are not affected by the points added to the stroke.

The calling application must ensure that lppt and lpvOem are valid and that the points are in the same scale as those of the pen data object. InsertPenDataPoints performs no automatic scaling of the points.

InsertPenDataPoints does not make any timing adjustments after adding points. This can affect recognition accuracy and should be used judiciously.

For a description of timing information, see “The HINKSET Object” in Chapter 4, “The Inking Process.”

See Also

AddPointsPenData, ExtractPenDataPoints, InsertPenData, InsertPenDataStroke, RemovePenDataStrokes


InsertPenDataStroke

2.0

Inserts a stroke into an existing HPENDATA object.

int InsertPenDataStroke( HPENDATA hpndt, UINT iStrk, LPPOINT lppt, LPVOID lpvOem, LPSTROKEINFO lpsiNew )

Parameters

hpndt

Handle to the HPENDATA object that receives the inserted strokes.

iStrk

Zero-based index of the stroke at which the new stroke is to be inserted. If this value is IX_END, the stroke is appended at the end of the HPENDATA memory block.

lppt

Pointer to a buffer containing the points to be inserted.

lpvOem

Pointer to a buffer of OEM data. This value can be NULL only if the pen data object does not have OEM data or a PENINFO structure.

lpsiNew

Pointer to the STROKEINFO structure containing information about the stroke.

Return Value

Returns PDR_OK if successful; otherwise, the return value can be one of the following negative values:

Constant	Description
PDR_COMPRESSED	Pen data is compressed.
PDR_ERROR	Parameter or other unspecified error.
PDR_MEMERR	Out of memory.
PDR_STRKINDEXERR	Invalid stroke index.
PDR_TIMESTAMPERR	Timing error.
PDR_VERSIONERR	Could not convert old pen data object.
Comments

InsertPenDataStroke inserts an entire stroke into an HPENDATA object. Use InsertPenDataPoints to insert points into a particular stroke.

The inserted stroke assumes the default pen-tip attributes. SetStrokeAttributes should be called after inserting the stroke to change such stroke attributes as the pen-tip characteristics or user data.

The calling application must ensure that lppt and lpvOem are valid, and that the points in the stroke that is being added have compatible scaling modes.

Attempting to insert an empty stroke simply returns PDR_OK.

See Also

AddPointsPenData, ExtractPenDataPoints, InsertPenDataPoints, RemovePenDataStrokes, STROKEINFO


InstallRecognizer

1.0     2.0

Loads and initializes a specified recognizer.

HREC InstallRecognizer( LPSTR lpszRecogName )

Parameters

lpszRecogName

Name of recognizer to load. If lpszRecogName is NULL, the default recognizer is loaded. (An application should not set lpszRecogName to NULL, because Windows automatically loads the default recognizer on initialization.)

Return Value

Returns a handle to a recognizer if successful; otherwise, returns NULL.

Comments

The recognizer’s name is the name of the DLL to be loaded. Windows searches for the recognizer file according to the standard rules for searching for a DLL—that is, it first searches the current directory, then the Windows directory, the system subdirectory, the PATH directories, and so forth. The procedure fails if the library cannot be found, the load fails, or the loaded DLL is not a valid recognizer. The recognizer may decline to load if it requires hardware information such as pen pressure that the pen device cannot provide.

An application should not load the default recognizer. All recognizers installed by an application must be uninstalled by a call to UninstallRecognizer before the application terminates.

After loading a recognizer library, the system calls the recognizer’s ConfigRecognizer function with the subfunction WCR_INITRECOGNIZER.

An application can load a recognizer with a call to LoadLibrary instead of InstallRecognizer. However, the application must first link with an import library derived from the recognizer DLL. The recognizer’s import library must appear in the library section of the LINK command line before PENWIN.LIB. This forces the application’s calls to pass directly to the recognizer’s exported recognition functions instead of the system.

This procedure may facilitate debugging the recognizer, but otherwise serves no purpose. It prevents use of other recognizers, including the system default recognizer. For a discussion of import libraries, refer to the section on the IMPLIB utility described in the Environment and Tools manual of the Microsoft VisualC++ documentation.

See Also

ConfigRecognizer, ConfigHREC, UninstallRecognizer


IsPenAware

1.0     2.0

Checks the capability of an application to handle pen events by returning cached task pen flags.

Note  This function is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions. Use GetPenAppFlags instead.

UINT IsPenAware(  )

Return Value

Returns the registration flags word set by a previous call to the SetPenAppFlags function. If SetPenAppFlags has not been called, IsPenAware returns 0.

See Also

GetPenAppFlags, SetPenAppFlags


IsPenEvent

1.0     2.0

Checks whether a mouse event was generated by the pen driver.

BOOL IsPenEvent( UINT message, LONG lExtraInfo )

Parameters

message

Windows mouse message being queried.

lExtraInfo

Value returned by GetMessageExtraInfo for the given message.

Return Value

Returns TRUE if the mouse event referenced by the message parameter was generated by the pen driver; otherwise, returns FALSE.

Comments

Mouse drivers that have not been updated to be compatible with pens may produce an event that cannot be distinguished from a real pen event. This has a very low probability of occurring.


KKConvert

2.0

Activates the Kana-to-Kanji converter. (Japanese version only.)

BOOL KKConvert( HWND hwndConvert, HWND hwndCaller, LPSTR  lpBuf, UINT cbBuf, LPPOINT lpPoint )

Parameters

hwndConvert

Handle to the window with the text to be converted.

hwndCaller

Handle to the window that calls KKConvert.

lpBuf

The text to be converted.

cBuf

The number of bytes (greater than 1) in lpBuf.

lpPoint

The positition where the Kana-to-Kanji converter will appear.

Return Value

Returns TRUE if the text is successfully converted; otherwise, returns FALSE.

Comments

If lpBuf is NULL, the currently-selected text in the window specified by hwndConvert will be used for conversion and then replaced with the converted text. If lpBuf is not NULL, the text in lpBuf will be converted and replaced with the converted text. If the length of the converted text is longer than cbBuf, the text will be truncated.

If the window referenced by hwndConvert is of the bedit class, lpPnt is ignored; otherwise, the center of the Kana-to-Kanji conversion is displayed at lpPnt.

If the window referenced by hwndConvert is of the hedit class and lpPnt is NULL, then the current caret position is used; otherwise, the client position (0,0) in the window referenced by hwndConvert is used.


MetricScalePenData

1.0     2.0

Converts pen data points to one of the supported metric modes.

BOOL MetricScalePenData( HPENDATA hpndt, UINT wPndtNew )

Parameters

hpndt

Handle to a pen data object containing the points to be converted.

wPndtNew

Scaling metric to be used with the data, as listed here:

Constant	Description
PDTS_LOMETRIC	Each logical unit is mapped to 0.1 millimeter. Positive x is to the right; positive y is down.
PDTS_HIMETRIC	Each logical unit is mapped to 0.01 millimeter. Positive x is to the right; positive y is down.
PDTS_HIENGLISH	Each logical unit is mapped to 0.001 inch. Positive x is to the right; positive y is down. This is equivalent to PDTS_STANDARDSCALE.
PDTS_DISPLAY	This parameter scales the data, using DPtoTP. The pen data memory block is left in display coordinates.
Return Value

Returns TRUE if successful, or FALSE if hpndt is in a compressed state or if the data is not already in one of the metric modes such as PDTS_ARBITRARY.

Comments

The MetricScalePenData function converts pen coordinates between metric and English standard measurements. Metric units are 0.1 and 0.01 millimeter; English standard units are 0.001 inch. These scaling metrics form the same mapping mode set in the Windows function SetMapMode.

MetricScalePenData allows an application to transform pen data to the mapping mode set for a device context. This ensures that ink rendered in the device context appears in the proper scale.

Note the following caveats about MetricScalePenData:

•	Because of rounding errors, scaling is not precisely reversible between mapping modes. Rounding errors can also adversely affect recognition accuracy if the data is later given to a recognizer. The problem arises when transforming the standard ink scale of HIENGLISH to a scale of lower resolution, a transformation that loses some of the original data. The lost data cannot be recovered, even if the coordinates are converted back into HIENGLISH.

•	The scaling is not perfect and results in numerous “off-by-one” discrepancies, visible when displaying the scaled data.

Strictly speaking, the PDTS_DISPLAY scaling type is not a metric scale. To use it, the current scale of the data must be in PDTS_STANDARDSCALE units.

The effect of this call is similar to that of using the TPtoDP function on the array of points. A recognizer may not accurately recognize the resulting data. As with the other scales, the PDTS_DISPLAY is set in the wPndts member of the pen data header. If data is in PDTS_DISPLAY scale, MetricScalePenData cannot be called to scale it back to the other metric scales. No overflow checks are made. Because of rounding errors, scaling conversion is not perfectly reversible. Recognizers must recognize points that have been scaled to PDTS_STANDARDSCALE (equivalent to PDTS_HIENGLISH).

See Also

OffsetPenData, ResizePenData, PDTS_


OffsetPenData

1.0     2.0

Offsets the coordinates in an HPENDATA memory block to make them relative to another origin.

BOOL OffsetPenData( HPENDATA hpndt, int dx, int dy )

Parameters

hpndt

Handle to a pen data object.

dx

Offset of x-axis; that is, the amount to move left or right. To move left, the dx value must be negative.

dy

Offset of y-axis; that is, the amount to move up or down. To move up, the dy value must be negative.

Return Value

Returns TRUE if successful, or FALSE if hpndt is in a compressed state.

Comments

For every point in hpndt, dx is added to the x-coordinate and dy is added to the y-coordinate. No overflow checks are made.

An application can use OffsetPenData to make points at display resolution relative to a particular window. If the window is then moved, the application need only call OffsetPenData again to move the data by the same amount, as shown in the example.

Example

The following sample code illustrates using the OffsetPenData function.

DWORD	dwOrg;	// Store window origin

.

.

.

// After creating window, note its current position

dwOrg = GetWindowOrg( hWnd );

.

.

.

switch( wMsg )

{

case WM_MOVE:

dx    = (int) (LOWORD(lParam) - LOWORD(dwOrg));	// X increment

dy    = (int) (HIWORD(lParam) - HIWORD(dwOrg));	// Y increment

dwOrg = (DWORD) lParam;	// Keep new org

OffsetPenData( hpendata, dx, dy );

See Also

MetricScalePenData, ResizePenData


PeekPenInput

2.0

Retrieves information about a specified pen packet in the pen input queue. For a definition of pen packet, see the description of SetPenHook.

int PeekPenInput( HPCM hpcm, UINT idEvent, LPPOINT lppt, LPVOID lpvOem, UINT fuOemFlags )

Parameters

hpcm

Handle to a pen collection. This is the return value from StartPenInput.

idEvent

The identifier of the packet to be retrieved. The idEvent is the low-order word of the value returned from the Windows GetMessageExtraInfo function when processing a WM_LBUTTONDOWN message.

lppt

Far pointer to a POINT structure. PeekPenInput copies the point corresponding to idEvent into the buffer pointed to by lppt.

lpvOem

The address of a buffer of OEM data in the packet. This parameter can be NULL if no OEM data is required.

fuOemFlags

Flags specifying which OEM data to retrieve. If this parameter is NULL, all of the OEM data provided by the tablet is returned in the order specified by the rgoempeninfo array in PENINFO.

These flags have an implicit order. For example, if pressure and barrel rotation are specified in that order, cPntMax pairs of these data are returned in the same order: [pressure, rotation], [pressure, rotation], and so on. (cPntMax is the number of POINT structures specified in GetPenInput.)

Constant	Description
PHW_PRESSURE	Retrieve pressure data.
PHW_HEIGHT	Retrieve height data.
PHW_ANGLEXY	Retrieve data pertaining to the x- and y-coordinates.
PHW_ANGLEZ	Retrieve data pertaining to the z-coordinates.
PHW_BARRELROTATION	Retrieve barrel-rotation data.
PHW_OEMSPECIFIC	Retrieve OEM-specific data.
PHW_PDK	Retrieve PDK_ data.
Return Value

Returns PCMR_OK if successful; otherwise, the return value can be one of the following:

Constant	Description
PCMR_INVALIDCOLLECTION	The hpcm handle is invalid because the calling application did not start input with StartPenInput.
PCMR_INVALID_PACKETID	idEvent is invalid.
Comments

Unlike GetPenInput, this function does not remove data from the pen input queue. It only returns information about the packet specified by idEvent.

Whereas lppt points into the pen input queue, lpvOem does not. If lpvOem is not NULL, it points to a buffer provided by the caller into which the OEM data are copied from the pen input queue.

The buffer that lpvOem points to must be large enough to hold the requested OEM data copied from the packet. The size of each packet is the width specified in the cbOemData member of the PENINFO structure, plus sizeof( UINT ) if PDK_ values are required.

See Also

GetPenInput,  PENPACKET,  PDK_


PenDataFromBuffer

2.0

Creates a HPENDATA object from serial data in a buffer. The buffer must have been previously written by the PenDataToBuffer function.

LONG PenDataFromBuffer( LPHPENDATA lphpndt, UINT gmemFlags, LPBYTE lpBuffer, LONG cbBuf, LPDWORD lpdwState )

Parameters

lphpndt

Pointer to an uninitialized HPENDATA handle. If PenDataFromBuffer returns successfully, lphpndt points to a new HPENDATA object containing a copy of the serial points.

gmemFlags

Flag that specifies whether or not the Windows GlobalAlloc function should create a shared memory object when the pen data object is created. This should be either 0 or GMEM_DDESHARE. The GMEM_MOVEABLE and GMEM_ZEROINIT flags are added to this value and other GMEM_ flags are ignored.

lpBuffer

Pointer to a byte buffer containing serial data.

cbBuf

Size of the buffer, which must be at least 64 bytes in size. If the buffer serves as an intermediate holding area, it need not be as large as the final HPENDATA object. To create the object, the application must call PenDataFromBuffer successively, each time reading a new section of data into the buffer that lpBuffer points to before the call. The example below illustrates this technique by filling an HPENDATA object in stages, reading data from a file in cbBuf increments.

lpdwState

Address of a DWORD variable used by the system to maintain the transfer state. The DWORD variable must be initialized to 0 before the first call to PenDataFromBuffer. Between successive calls to PenDataFromBuffer, the application must not alter the value that lpdwState points to. lpdwState can be NULL to signify that the buffer contains the entire data set for the HPENDATA object. This implies that subsequent calls to PenDataFromBuffer are not necessary.

Return Value

If successful, PenDataFromBuffer returns the number of bytes transferred from the buffer. If the size of the pen data is larger than the buffer, the return value is equal to the buffer size passed in cbBuf. A value of 0 indicates no more data to transfer. If there is an error, one of the following negative values is returned:

Constant	Description
PDR_ERROR	Parameter or overflow error.
PDR_MEMERR	Memory error.
Comments

The data being provided by the application must have been previously written by the PenDataToBuffer function. The application cannot modify this data in any way. Embedded values within the first 64 bytes provide information to PenDataFromBuffer about the size of the pen data.

PenDataFromBuffer creates an HPENDATA object and provides a handle to it. The application must destroy the object when finished. The lphpndt argument points to a valid HPENDATA handle only if the function returns PDR_OK.

While this function is reconstituting the HPENDATA object, the application must not attempt to use it in any way because it will be invalid until the last buffer is read.

Example

The following example shows how to create a HPENDATA object from a file (hfile) that has already been opened for reading. Before reading the pen data, its length is retrieved from the file:

#define cbBufMax	1024

HPENDATA NEAR PASCAL ReadPenData( HFILE hfile )

{

HPENDATA	hpndt = NULL;

LONG	cb, cbRead, cbHpndt;

BYTE	lpbBuf[cbBufMax];	// Buffer

DWORD	dwState = 0L;	// Must initialize to 0

if (!hfile

|| (cb = _lread(hfile, &cbHpndt, sizeof(DWORD))) == HFILE_ERROR

|| cb != sizeof(LONG))

return NULL;

while (cbHpndt > 0)

{

if ((cbRead = _lread( hfile, lpbBuf, min(cbHpndt, cbBufMax )))

== HFILE_ERROR

|| PenDataFromBuffer( &hpndt, 0, lpbBuf,

  cbBufMax, &dwState ) < 0)

{

if (hpndt)

DestroyPenData( hpndt );

return NULL;

}

cbHpndt -= cbRead;

}

return hpndt;

}

See Also

PenDataToBuffer,  GetPenDataAttributes


PenDataToBuffer

2.0

Writes the data in an existing HPENDATA object to a serial buffer.

LONG PenDataToBuffer( HPENDATA hpndt, LPBYTE lpBuffer, LONG cbBuf, LPDWORD lpdwState )

Parameters

hpndt

Handle to the HPENDATA object.

lpBuffer

Pointer to an empty buffer.

cbBuf

Size of the buffer in bytes. The buffer must be at least 64 bytes in size. If the buffer serves as an intermediate holding area, it need not be as large as the HPENDATA object. To read all data from the object in this case, the application must call PenDataToBuffer successively, each time copying the data from the buffer that lpBuffer points to before the next call. The example below illustrates this technique by writing an HPENDATA object in cbBuf increments to a file.

lpdwState

Address of a DWORD variable used by the system to maintain the transfer state. The DWORD variable must be initialized to 0 before the first call to PenDataToBuffer. Between successive calls to PenDataToBuffer, the application must not alter the value that lpdwState points to. lpdwState can be NULL to signify that the buffer is large enough to contain the entire HPENDATA object. This implies that subsequent calls to PenDataToBuffer are not necessary.

Return Value

If successful, PenDataToBuffer returns the number of bytes transferred into the buffer. If the size of the pen data is larger than the buffer, the return value is equal to the buffer size passed in cbBuf until the final transfer, when it is typically some smaller value. A value of 0 indicates no more data to transfer. If there is an error, one of the following negative values is returned:

Constant	Description
PDR_ERROR	Parameter or other unspecified error.
PDR_MEMERR	Memory error.
PDR_PNDTERR	Invalid HPENDATA object.
PDR_VERSIONERR	Could not convert old HPENDATA object.
Comments

The buffer need not be large enough to accommodate the entire HPENDATA object. To allocate a buffer large enough for a single transfer, the application can determine the required size with the GetPenDataAttributes subfunction GPA_SIZE .

Example

The following example shows how to save an HPENDATA object to a file (hfile) that has already been opened for writing. The length of the pen data is saved in the file before writing the pen data itself:

#define cbBufMax	1024

BOOL NEAR PASCAL	WritePenData( HFILE hfile, HPENDATA hpndt )

{

BYTE    lpbBuf[cbBufMax];

DWORD   dwState = 0L;	// Must initialize to zero

LONG    cb;

LONG    cbSize;

if (!hfile || !hpndt)

return FALSE;

// Get size and save to file

if (GetPenDataAttributes(hpndt, (LPVOID)&cbSize, GPA_SIZE) < 0)

return FALSE;

// write size of pen data to file so that it can be used while reading it back

if (_lwrite(hfile, &cbSize, sizeof(LONG)) == HFILE_ERROR)

return FALSE;

// Write the pen data in chunks, and repeat until done

while ((cb = PenDataToBuffer(hpndt, lpbBuf,

  cbBufMax, &dwState )) > 0L)

{

if (_lwrite( hfile, lpbBuf, (UINT)cb ) == HFILE_ERROR)

return FALSE;

}

return (cb >= 0L);	// Return TRUE if cb >= 0

}

See Also

PenDataFromBuffer


PostVirtualKeyEvent

1.0     2.0

Posts a virtual key-code event to Windows.

void PostVirtualKeyEvent( UINT vk, BOOL fUp )

Parameters

vk

Virtual key. This argument takes a Windows VK_ constant as defined in the WINDOWS.H include file. Depending on the key, this is either the key scan code or the ASCII equivalent to represent a character key. For example, VK_A has the value “A.”

fUp

Key-transition flag. This parameter should be FALSE to specify that the key is down or TRUE to specify that it is up.

Return Value

This function does not return a value.

Comments

PostVirtualKeyEvent does not check the virtual key code for errors.

Normally, an application should follow a key-down message with a corresponding key-up message to accurately simulate the actual events from the keyboard. You can post repeating keys by calling PostVirtualKeyEvent consecutively, one call per repeat, with fUp set to FALSE. End the sequence with a single call to PostVirtualKeyEvent with fUp set to TRUE.

The events are posted to the system message queue. The application with the input focus can receive the messages by calling the Windows GetMessage or PeekMessage function.

See Also

AtomicVirtualEvent, PostVirtualMouseEvent


PostVirtualMouseEvent

1.0     2.0

Posts a virtual mouse code to Windows.

void PostVirtualMouseEvent( UINT wMouseFlags, int xPos, int yPos )

Parameters

wMouseFlags

Flags indicating the type of mouse event. This can be one or more of the following values, combined by a bitwise-OR operator.

Constant	Description
VWM_MOUSEMOVE	Simulates a change in the mouse cursor position. This flag can be combined with any of the other flags in this table.
VWM_MOUSELEFTDOWN	Simulates pushing the left mouse button.
VWM_MOUSELEFTUP	Simulates releasing the left mouse button.
VWM_MOUSERIGHTDOWN	Simulates pushing the right mouse button.
VWM_MOUSERIGHTUP	Simulates releasing the right mouse button.
xPos

The x-axis position in screen coordinates.

yPos

The y-axis position in screen coordinates.

Return Value

This function does not return a value.

Comments

The x- and y-axis positions are absolute positions in screen coordinates. Note that the x and y values should not exceed the screen-resolution limits. Values greater than the maximum resolution in the x-direction (640 for standard VGA) or the y-direction (480 for standard VGA) cause an overflow.

The events are posted to the system message queue. The application with the input focus can receive the messages by calling the Windows GetMessage or PeekMessage message.

Because of the way Windows interprets mouse messages, the calling application must be careful about the order in which events are sent to the system. A message that represents both a button-state transition and a move generates first a Windows event for the button transition at the current pointer location and then a move to the new location. To simulate a move to a new location followed by a button transition, the application must make separate calls to PostVirtualMouseEvent for each simulated event.

Example

When posting events, the caller should bracket the calls by calls to AtomicVirtualEvent, which locks out pen packets while the application is posting simulated mouse events. For example, the following code fragment posts a mouse event:

AtomicVirtualEvent(TRUE);

//

//  ... PostVirtualMouseEvent calls go here

//

AtomicVirtualEvent(FALSE);

The Windows GetMessageExtraInfo function returns 0 for any messages generated by PostVirtualMouseEvent.

See Also

AtomicVirtualEvent, PostVirtualKeyEvent


ProcessHRC

2.0

Gives a recognizer sufficient time for intermediate processing of pen input. A recognizer must export this function.

int ProcessHRC( HRC hrc, DWORD dwTimeMax )

Parameters

hrc

Handle to the HRC object for the recognizer.

dwTimeMax

The maximum time in milliseconds that the recognizer should process before returning from this call. This parameter can also be one of the following time-out codes:

Constant	Description
PH_MIN	The recognizer should take only a very small amount of time to process the input, typically 50 milliseconds.
PH_DEFAULT	The recognizer should take a moderate amount of time to process the input, typically 200 milliseconds.
PH_MAX	The recognizer should take as much time as required to complete recognition.
Return Value

If there are no errors, returns one of the following values:

Constant	Description
HRCR_OK	Processing is successful.
HRCR_INCOMPLETE	The recognizer is still processing the current batch of input.
HRCR_GESTURE	The recognizer has recognized a possible gesture.  This can be returned before the recognition process  is complete. If the processing completes, HRCR_COMPLETE is always returned, even for gestures.
HRCR_COMPLETE	The recognizer completed processing and does not expect any more input.
To indicate an error, ProcessHRC returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
Comments

ProcessHRC returns if the time specified by dwTimeMax elapses before recognition is complete.

In an operating environment that does not use threads, this function allows an application to provide some time for the recognizer to process input. By checking the return value, the application is able to monitor the progress, specifically whether a gesture is a recognition candidate. If the function returns HRCR_GESTURE, the application can call GetResultsHRC to determine whether the gesture should be acted on immediately.

Typically, the return value is HRCR_OK if the current batch of ink input has been processed by the recognizer, and HRCR_INCOMPLETE if the recognizer has not yet finished processing.

If ProcessHRC is called with PH_MAX, recognition is complete only if EndPenInputHRC has been called to notify the recognizer that no more results are expected. The return value in this case is HRCR_COMPLETE, and the application is free to get and display final results. If the application supplies further input at this point, it has the effect of canceling the EndPenInputHRC call, although this procedure is not recommended for reasons of efficiency.

However, PH_MAX may result in poorer performance, since further processing in the system is blocked until ProcessHRC returns. Instead, the application can call ProcessHRC in an idle loop or a separate thread, calling it repeatedly with smaller time allotments until the function returns HRCR_COMPLETE. Note that if a separate thread is used to finish processing, the main thread can call this function with PH_MIN from time to time to determine if processing has finished (that is, checking for the HRCR_COMPLETE return value).

The first time that ProcessHRC is called for a particular recognition context, functions that set its state cannot be used for the remainder of that context’s existence. The following functions return an error if they are called before ProcessHRC returns HRCR_COMPLETE:

•	EnableGestureSetHRC

•	EnableSystemDictionaryHRC

•	SetAlphabetHRC

•	SetAlphabetPriorityHRC

•	SetBoxAlphabetHRC

•	SetWordlistCoercionHRC

•	SetGuideHRC

•	SetInternationalHRC

•	SetMaxResultsHRC

•	SetWordlistHRC

See Also

EndPenInputHRC, GetResultsHRC


ProcessWriting

1.0     2.0

Processes handwriting.

Note  This function is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions. Use DoDefaultPenInput instead.

REC ProcessWriting( HWND hwnd, LPRC lprc )

Parameters

hwnd

Window to receive messages. This parameter must not be NULL.

lprc

Address of RC structure to use for recognition. This parameter can be NULL.

Return Value

Returns values less than 0 if the application should treat the event as a mouse event instead of a pen event. Return values less than 0 occur if the event did not come from a pen, the user performed a press-and-hold action (REC_POINTEREVENT), or an error occurred—for example, running out of memory.

Comments

The ProcessWriting function is similar to Recognize except that ProcessWriting also takes care of inking, removing the ink, and converting the results message to standard Windows messages.

Depending on the existing code in an application, ProcessWriting may not be suitable for making an application pen-aware. This function can also limit the power of a pen interface.

If lprc is NULL, a default RC structure is created for the application. The default RC structure contains all system defaults and the inking is constrained to the client area of hwnd. If lprc points to a valid RC structure, the rectBound member of the RC structure is used to constrain the inking. Regardless of whether the application provides an RC or not, ProcessWriting assumes a value of RRM_COMPLETE for the wResultMode member. See RC for a description of wResultMode and the RRM_ values.

After the writing is completed, the ink is removed before any messages are sent to hwnd. After the ink is removed, the screen is updated and hwnd receives a WM_RCRESULT message. If the application processes this message, it should return TRUE. In this case, no further messages are sent.

If the application returns FALSE, ProcessWriting performs the default conversion of the results message to standard Windows messages, as shown in the following table. The messages are sent rather than posted. Note that the DefWindowProc function returns 0 when processing the WM_RCRESULT message.

Results message	Windows message
SYV_BACKSPACE	WM_LBUTTONDOWN, followed by WM_LBUTTONUP at the hot spot of the gesture, followed by WM_CHAR specifying a backspace.
SYV_CLEAR	WM_CLEAR.
SYV_CLEARWORD	WM_LBUTTONDOWN, WM_LBUTTONUP, WM_LBUTTONDBLCLK, WM_LBUTTONUP at the same point, followed by WM_CLEAR.
SYV_COPY	WM_COPY.
Results message	Windows message
SYV_CORRECT	WM_LBUTTONDOWN, WM_LBUTTONUP, WM_LBUTTONDBLCLK, WM_LBUTTONUP at the hot spot of the gesture, followed by WM_COPY. At this point the Edit Text dialog box is activated; it retrieves text from the Clipboard. This uses the existing selection, if any. The previous contents of the Clipboard are lost.
SYV_CUT	WM_CUT.
SYV_EXTENDSELECT	WM_LBUTTONDOWN, followed by WM_LBUTTONUP at the hot spot of the gesture.  The MK_SHIFT flag is set for the wParam of these messages.
SYV_LASSO	WM_LBUTTONDOWN at upper-left corner of selected area, followed by WM_MOUSEMOVE message, followed by WM_LBUTTONUP at the lower-right corner of selected area.
SYV_PASTE	WM_LBUTTONDOWN, followed by WM_LBUTTONUP at the hot spot of the gesture, followed by WM_PASTE.
SYV_RETURN	WM_LBUTTONDOWN, followed by WM_LBUTTONUP at the hot spot of the gesture, followed by WM_CHAR specifying a carriage return.
SYV_SPACE	WM_LBUTTONDOWN, followed by WM_LBUTTONUP at the hot spot of the gesture, followed by WM_CHAR specifying a space.
SYV_TAB	WM_LBUTTONDOWN, followed by WM_LBUTTONUP at the hot spot of the gesture, followed by WM_CHAR specifying a tab.
SYV_UNDO	WM_UNDO.
text	One WM_CHAR message per character of text.
The SYV_ symbol values in the previous table identify gestures. To see a complete list of symbol values, refer to Chapter 13, “Pen Application Programming Interface Constants.”

The lParam of a WM_RCRESULT message generated by ProcessWriting is a far pointer to an RCRESULT structure. By default, when an application receives a WM_RCRESULT message, the hpendata member of the RCRESULT structure is NULL. If you need the HPENDATA handle, set the RCO_SAVEHPENDATA flag in the lRcOptions member of the RC structure. In this case, the calling application is responsible for destroying the HPENDATA object.

See Also

DoDefaultPenInput, InitRC, Recognize, REC_, SYV_, RCO_


ReadHWL

2.0

Reads a word list from a file.

int ReadHWL( HWL hwl, HFILE hfile )

Parameters

hwl

A handle to an empty word list.

hfile

A handle to a file previously opened for reading.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or file or other error.
HRCR_MEMERR	Insufficient memory.
Comments

The words are expected as ANSI text, one word per line, followed by a carriage return and linefeed. In this context, a word can represent a phrase and contain spaces or other noncharacters, such as “New York” and “ne’er-do-well.” Empty lines or lines containing only spaces or tabs are allowed but ignored.

The file that hfile refers to must already exist and be open for reading.

The hwl parameter must be the handle of an empty word list created by CreateHWL. If the word list is not empty, ReadHWL returns HRCR_ERROR.

Once the file is read, it can be closed immediately.

Example

The following example demonstrates how to provide a word list to constrain recognition results to the words contained in the fictitious file COUNTRY.LST:

HWL	  hwlCountries = CreateHWL( NULL, NULL, WLT_EMPTY, 0L );

OFSTRUCT	  ofStruct;

HFILE	  hfile = OpenFile( "country.lst", &ofStruct, OF_READ );

if (hfile != HFILE_ERROR)

{

ReadHWL(hwlCountries, hfile);

_lclose(hfile);

}

else

ErrorMsg(FILEOPEN);

.

.

.

if (hrc = CreateCompatibleHRC( NULL, NULL ))

{

SetWordlistHRC( hrc, hwlCountries );	    // Set list into HRC

SetWordlistCoercionHRC( hrc, SCH_FORCE );  // Force match

.

.     // Code that collects and recognizes input here

.

}

See Also

CreateHWL, WriteHWL


Recognize

1.0     2.0

Begins sampling pen data and converts tablet input to recognized symbols.

Note  This function is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions.

REC Recognize( LPRC lprc )

Parameters

lprc

Address of an RC structure.

Return Value

Returns an REC_ value. See the “Comments” section for a description of the return values.7

Comments

The RC structure that lprc points to contains the parameters that control recognition. The system sends recognition results via the WM_RCRESULT message to the window indicated by the hwnd member of the RC. All results messages are sent before Recognize returns. Multiple result messages can be sent if the application asks for results to be sent to the application before all input has been completed (as indicated by the wResultMode member of the RC structure).

An application that uses version 1.0 recognizers should call Recognize when the input session begins, signaled by the WM_LBUTTONDOWN message.

The value REC_OK is used in the wParam of the WM_RCRESULT message to indicate that more data is coming. Return values of greater than 0 signal normal successful completion. Return values of less than 0 indicate abnormal termination. Return values of less than REC_DEBUG are reserved for return values from

debugging versions of the system or recognizer. If an application creates a condition that would be caught in a debugging version while running a nondebugging version, the results are undefined.

Each return value can be the wParam value of the WM_RCRESULT message or the return value for Recognize. The wParam value of the last WM_RCRESULT message generated by a call to Recognize is the return value of Recognize. Some error conditions, such as REC_OOM or REC_NOTABLET, are returned without generating any corresponding WM_RCRESULT message.

All of the values listed in the following table are in the debug version only. No WM_RCRESULT message is generated if these values are returned by Recognize.

Constant	Description
REC_ALC	Invalid enabled alphabet.
REC_BADEVENTREF	Returned when the wEventRef member in the lprc structure is invalid.
REC_CLVERIFY	Invalid verification level.
REC_DEBUG	All debugging return values are less than this.
REC_DICT	Invalid dictionary parameters.
REC_ERRORLEVEL	Invalid error level.
REC_GUIDE	Invalid GUIDE structure.
REC_HREC	Invalid recognition handle.
REC_HWND	Invalid handle to window to send results to.
REC_INVALIDREF	Invalid data reference parameter.
REC_LANGUAGE	Returned by the recognizer when the lpLanguage member contains a language that is not supported  by the recognizer. Call ConfigRecognizer with the WCR_QUERYLANGUAGE subfunction to determine whether a particular language is supported.
REC_NOCOLLECTION	In version 1.0, was returned by GetPenHwData if collection mode has not been set. Not used now.
REC_OEM	Error codes less than or equal to REC_OEM are specific to the recognizer.
REC_PCM	Invalid lPcm member in the RC structure. There is no way for the recognition to end.
REC_RECTBOUND	Invalid rectangle.
REC_RECTEXCLUDE	Invalid rectangle.
REC_RESULTSMODE	Unsupported results mode requested.
See Also

InitRC, RecognizeData, GetPenHwEventData,  RC,  REC_


RecognizeData

1.0     2.0

Converts the data in an HPENDATA object to recognized symbols.

Note  This function is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions.

REC RecognizeData( LPRC lprc, HPENDATA hpndt )

Parameters

lprc

Address of an RC structure.

hpndt

Handle to an HPENDATA object.

Return Value

Returns REC_DONE if successful, or an REC_ error code if an error occurs.

Comments

RecognizeData recognizes data in an HPENDATA object and returns the results to the window specified in the RC structure. RecognizeData is similar to Recognize. The difference is that in RecognizeData, the input data comes from a buffer of points already collected instead of from the tablet driver. Members pertaining to the end of recognition in the RC structure are ignored.

RecognizeData can return REC_BUSY if the recognizer is not reentrant. A recognizer is not guaranteed to return the same results for identical input. This is because persistent states, such as the current average size of writing or the position of the baseline, can affect recognition results. In addition, training may change the prototypes against which the data is being compared.

RecognizeData attempts to convert the pen data to PDTS_STANDARDSCALE if it is not already in standard scale. If the conversion fails (for example, because the data was in an application-specific scale PDTS_ARBITRARY), the data is still passed to the recognizer. A recognizer may return an error code (REC_BADHPENDATA) for data in a scale it cannot handle.

See Also

InitRC, Recognize, GetPenHwEventData, RC, REC_,  PDTS_


RedisplayPenData

1.0     2.0

Redraws the pen data in the same manner as originally inked.

BOOL RedisplayPenData( HDC hdc, HPENDATA hpndt, LPPOINT lpDelta, LPPOINT lpExt, int nInkWidth, DWORD rgbColor )

Parameters

hdc

Handle to a device context. The mapping mode should be MM_TEXT.

hpndt

Handle to a pen data object. The pen data must be scaled to PDTS_DISPLAY or PDTS_STANDARDSCALE.

lpDelta

An offset, in logical units, that is subtracted from the pen data points to position the ink. If lpDelta is NULL, there is no offset.

lpExt

Extent, in logical units, for scaling. If lpExt is NULL, no scaling is performed.

nInkWidth

Width of the ink to be drawn, in pixels (1 to 15). If nInkWidth is −1, the strokes are rendered using the original ink width stored in the stroke header. An ink width of 0 causes the function to simply return TRUE.

rgbColor

RGB value of the color to draw the ink. If rgbColor is 0xFFFFFFFF, the strokes are rendered using the original ink color stored in the stroke header.

Return Value

Returns TRUE if successful; otherwise FALSE.

Comments

The nInkWidth and rgbColor values override the pen currently selected for the hdc device context.

If the mapping mode of the hdc device context is not MM_TEXT, two problems can occur:

•	RedisplayPenData uses TPtoDP to prepare the pen data points for rendering. After this, the points are in MM_TEXT coordinates; this assumes an MM_TEXT device context for display. If the device context is in a different mapping mode, the ink coordinates will not be correct. Even if you use the ink-scaling functions to bypass this problem, you will still encounter rounding-error problems between the two scalings.

•	No matter what scaling is done, rounding errors occur when converting between modes. These errors cause the ink to shift slightly when repainted.

For any rendering into a device context that represents anything other than a display device context, DrawPenDataEx should be used. This is because RedisplayPenData makes assumptions that are not optimal for other devices such as printers or metafiles.

RedisplayPenData provides the ability to re-create original inking perfectly. To do this, an application can use either of two methods:

•	After the input session ends and data is collected into an HPENDATA object, store the current origin of the window containing the ink. When calling RedisplayPenData to redraw the ink, supply the origin value in the lpDelta argument, set lpExt to NULL, and set the mapping mode of the device context to MM_TEXT. Only ink data with a common window origin can be merged into a single HPENDATA.

•	In the second method, the application must call two Pen functions immediately after collecting the data into an HPENDATA object. The first call to MetricScalePenData converts the pen data to display coordinates. The second call to OffsetPenData sets the display coordinates relative to the window containing the original ink. To display, the application must call RedisplayPenData with lpDelta and lpExt set to NULL and the mapping mode of the device context set to MM_TEXT. If the application adopts this method for multiple HPENDATA objects, it can later merge them to form a single HPENDATA object (up to the 64K limit).

The second method has the advantages of simplicity and data compression. See the description of MetricScalePenData for a discussion of the limitations of converting data to display resolution.

Since the pen data has the origin of (0,0) based on the upper-left corner of the display, applications must move from a screen-relative position to a position relative to the device context. To do this, subtract the origin of the device context (in screen coordinates) from the object currently residing in screen-coordinate space.

The lpDelta parameter enables the application to render ink relative to the window instead of relative to the screen. An application should call the ClientToScreen function for (0,0) to find the proper screen coordinates to be placed in the *lpDelta POINT structure. Once this is done, the pen data is rendered at the appropriate location in window coordinates. If lpDelta is NULL, no offset for the data is assumed.

The lpExt argument specifies the extents into which the data should be scaled. If extents are provided, data is scaled into a rectangle described by lpDelta and lpExt. The values of x and y in lpExt and lpDelta are in the mapping mode of the device context into which the data is rendered.

RedisplayPenData displays pen data with a square graphical device interface (GDI) pen brush for maximum drawing speed. When displaying wide lines of ink, this optimization can cause the ends of abutting lines to appear blocky. If you prefer a smoother look to the joints of wide lines at the expense of rendering speed, draw the ink with DrawPenData, DrawPenDataEx, or DrawPenDataFmt instead of RedisplayPenData. These functions draw wide lines by flood-filling a region, thus smoothing the ends.

See Also

DrawPenData,  DrawPenDataEx,  PDTS_


RegisterPenApp

1.0     2.0

Notifies the pen system that the application edit controls should be replaced with hedit controls. This function is required only for applications that specify EDIT class (instead of HEDIT class) for control windows with versions of Windows earlier than Windows 95.

Note that this function has been superseded by the SetPenAppFlags function in the 2.0 version of the Pen API, although calling RegisterPenApp is still supported. See SetPenAppFlags for more information.

void RegisterPenApp( UINT fuFlags, UINT uVersion )


RemovePenDataStrokes

2.0

Removes strokes from an HPENDATA object.

int RemovePenDataStrokes( HPENDATA hpndt, UINT iStrk, UINT cStrks )

Parameters

hpndt

Handle to the HPENDATA object.

iStrk

Zero-based index of the first stroke to remove. This value can be IX_END to remove the last stroke. The function fails if iStrk is greater than the number of strokes in the pen data object.

cStrks

Count of strokes to remove. If this value is greater than the number of strokes after the specified stroke index, the stroke indexed by iStrk and all following strokes are removed. cStrks can be IX_END to remove all strokes from iStrk onward.

Return Value

Returns PDR_OK if successful; otherwise, the return value can be one of the following negative values:

Constant	Description
PDR_COMPRESSED	Pen data is compressed.
PDR_ERROR	Parameter or other unspecified error.
PDR_MEMERR	Out of memory.
PDR_PNDTERR	Invalid pen data object.
PDR_STRKINDEXERR	Invalid stroke index.
PDR_VERSIONERR	Could not convert old pen data object.
Comments

RemovePenDataStrokes removes the number of strokes specified by cStrks, starting at the stroke specified by iStrk. Use ExtractPenDataPoints to remove points from a particular stroke of the pen data object.

See Also

ExtractPenDataPoints, InsertPenDataPoints, InsertPenDataStroke


ResizePenData

1.0     2.0

Scales ink in an HPENDATA object into an arbitrarily sized rectangle.

BOOL ResizePenData( HPENDATA hpndt, LPRECT lprect )

Parameters

hpndt

Handle to a pen data object.

lprect

Address of a bounding rectangle, or NULL.

Return Value

Returns TRUE if successful; otherwise, the return value is FALSE.

Comments

This function changes the physical size of the object without changing the meaning of the measurements. Use the MetricScalePenData function to convert the data to one of the supported metric modes of measurement.

ResizePenData physically resizes the data in hpndt to the bounding rectangle dimensions given by the lprect parameter. Data from hpndt is mapped to the new rectangle. If lprect is NULL, this function recalculates the bounding rectangle (the rectBound member in the PENDATAHEADER structure). For example, consider the case of pen data with PDTS_HIMETRIC scaling bounded by the square (500, 600, 1500, 1600). To double the size, set lprect to (500, 600, 2500, 2600).

See Also

OffsetPenData, MetricScalePenData, PDTS_


ResultsHookHREC

2.0

The ResultsHookHREC function is an application-defined callback function that provides the application with the opportunity to view all recognition results before they are returned to the application. The name ResultsHookHREC is a placeholder; the function can have any name.

BOOL CALLBACK ResultsHookHREC( HREC hrec, HRC hrc, WORD wHooktype, UINT cResults, UINT cAlt, LPVOID rgresults )

Parameters

hrec

Module handle of the recognizer library whose results are being hooked.

hrc

Handle to the HRC object for the recognizer that hrec refers to.

wHooktype

Type of hook. This can be one of the following values:

RHH_STD

Standard results generated by GetResultsHRC.

RHH_BOX

Boxed results generated by GetBoxResultsHRC.

cResults

Count of results available.

cAlt

Count of box alternatives. This is valid only if wHooktype is RHH_BOX.

rgresults

An array of result objects. The object type depends on wHooktype. If RHH_STD, rgresults should be cast as LPHRCRESULT and the array receives cResults HRCRESULT objects. If RHH_BOX, rgresults should be cast as LPBOXRESULTS and the array receives cResults BOXRESULTS structures.

Return Value

The application hook function should return TRUE to indicate that it has processed the data and that the recognizer should do no further processing. In this case, it is the application’s responsibility to destroy the results and inksets, if any; otherwise, the hook function should return FALSE.

See Also

SetResultsHookHREC


SetAlphabetHRC

2.0

Specifies which alphabet should be used in an HRC object.

int SetAlphabetHRC( HRC hrc, ALC alc, LPBYTE rgbfAlc )

Parameters

hrc

Handle to the HRC object.

alc

Alphabet. This value is one or more ALC_ values combined using the bitwise-OR operator.

rgbfAlc

Array of bits if alc contains ALC_USEBITMAP; otherwise, it can be NULL.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

Some recognizers may not support ALC_ values and alphabet priorities. An application should check for HRCR_UNSUPPORTED when using this function.

The following values may require Japanese, wide-character, or recognizer-specific support: ALC_DBCS, ALC_JIS1, ALC_KANJI, ALC_OEM, ALC_HIRAGANA, and ALC_KATAKANA. In addition, ALC_RESERVED is reserved for future use and is ignored. Recognizers, such as the Microsoft Handwriting Recognizer (GRECO.DLL) for default American English, can return HRCR_OK even if some of these values are set.

The size of the rgbfAlc array, if used, must be large enough to accommodate 256 bits (32 bytes). If the nth bit is set, then the nth ANSI character is recognizable. Bits representing characters less than 32 (space) currently have no meaning.

The ALC_GESTURE value is ignored, even if it is part of the alc parameter. See EnableGestureSetHRC.

For a description of alphabets and their relationship to a recognizer, see “Configuring the HRC” in Chapter 5, “The Recognition Process.” For a list of alphabet codes, see Chapter 13, “Pen API Constants.”

See Also

EnableGestureSetHRC, GetAlphabetHRC

SetAlphabetPriorityHRC, ALC_


SetAlphabetPriorityHRC

2.0

Specifies the priority of alphabet sets in an HRC object.

int SetAlphabetPriorityHRC( HRC hrc, ALC alc, LPBYTE rgbfalc )

Parameters

hrc

Handle to the HRC object.

alc

Alphabet priority. This value is one or more ALC_ values combined using the bitwise-OR operator.

rgbfalc

Address of a 256-bit (32-byte) buffer whose bits map to ANSI single-byte characters if alc contains ALC_USEBITMAP; otherwise, it can be NULL.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

Some recognizers may not support ALC_ values and priorities. An application should check for HRCR_UNSUPPORTED when using this function.

For a description of how a recognizer uses alphabet priority, see “Configuring the HRC” in Chapter 5, “The Recognition Process.” For a list of alphabet codes, see Chapter 13, “Pen Application Programming Interface Constants.”

See Also

GetAlphabetHRC, SetAlphabetHRC, GetAlphabetPriorityHRC, ALC_


SetBoxAlphabetHRC

2.0

Specifies the alphabet codes to use for a range of boxes.

int SetBoxAlphabetHRC( HRC hrc, LPALC rgalc, UINT cAlc )

Parameters

hrc

Handle to an HRC object.

rgalc

An array of cAlc ALC_ values. The array is mapped onto boxes starting at box zero.

cAlc

Number of ALC_ values in rgalc. This should match the number of boxes. If this parameter is 0, SetBoxAlphabetHRC simply returns 0.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

SetBoxAlphabetHRC applies only when an HRC has been configured for box guides with the SetGuideHRC function. Although SetAlphabetHRC can also specify an alphabet set for boxed input, it attaches the same alphabet setting to all boxes indiscriminately. SetBoxAlphabetHRC offers greater control by allowing an application to set different alphabets for individual boxes of a single HRC.

Example

For example, consider a boxed entry on a requisition form that expects a part number consisting of five characters. The first two characters are uppercase letters, the next two are numerals, and the last character can be either another numeral or a lowercase revision code. The following example demonstrates how to configure the HRC for this hypothetical scenario:

#define  PART_LEN    5                  // Five characters in entry

HRC      hrcPart;                       // HRC for parts entry

GUIDE    guidePart;                     // GUIDE for parts entry

ALC      alcPart[PART_LEN];             // Array of ALC_ codes for entry

.

.                                   // Initialize the GUIDE here

.

guidePart.cHorzBox = PART_LEN;          // Number of boxes in entry

guidePart.cVertBox = 1;                 // Single row

guidePart.cyMid    = 0;                 // No midline

iret = SetGuideHRC( hrcPart, (LPGUIDE)&guidePart, 0 );

if (iret == HRCR_OK)

{

alcPart[0] = alcPart[1] = ALC_UCALPHA;  // Uppercase in boxes 1-2

alcPart[2] = alcPart[3] = ALC_NUMERIC;  // Numerals in boxes 3-4

alcPart[4] = ALC_LCALPHA | ALC_NUMERIC; // Lower or numeral in box 5

// Map alphabet codes onto boxes of parts number entry

SetBoxAlphabet( hrcPart, (LPALC)&alcPart, PART_LEN );

}

See Also

GetAlphabetHRC, SetAlphabetHRC, ALC_


SetGlobalRC

1.0     2.0

Sets the current default settings for the global RC structure. In version 2.0 of the Pen API, the RC structure is made obsolete by the HRC object.

Note  This function is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions.

UINT SetGlobalRC( LPRC lprc, LPSTR lpszDefRecog, LPSTR lpszDefDict )

Parameters

lprc

Address of an RC structure or NULL.

lpszDefRecog

Address of string specifying the name of the default recognizer module (maximum 128 bytes).

lpszDefDict

Address of a string specifying the default dictionary path. The list should end with two null characters.

Return Value

Returns the value SGRC_OK if successful. If an error occurs, the return value consists of one or more of the following values, combined using the bitwise-OR operator.

Constant	Description
SGRC_USER	An invalid user name was found in the supplied RC structure. The call to SetGlobalRC has no effect.
SGRC_PARAMERROR	One or more invalid parameters were detected. The call to SetGlobalRC has no effect.
SGRC_RC	The supplied recognition context lprc has entries, other than the user name, that contain invalid settings for a global recognition context. The supplied recognition context is ignored.
SGRC_RECOGNIZER	The supplied recognizer module name lpszDefRecog is invalid or the recognizer cannot be loaded. The supplied recognizer module name is ignored.
SGRC_DICTIONARY	The supplied dictionary path lpszDefDict is invalid or some dictionaries on the path cannot be loaded. The supplied dictionary path is ignored.
SGRC_INIFILE	An error was encountered while saving the new global recognition context settings to the pen section of the system registry. The new settings are lost after rebooting Windows.
Comments

Because the default RC values are shared among all version 1.0 applications running, the values should be changed only through the Control Panel. Whenever a change is made to the global RC values, the WM_PENMISCINFO message is sent to all top-level windows. The wParam and lParam values are not used, and they are set to 0.

Any of the parameters can be NULL to indicate that the calling application does not want the value changed.

SetGlobalRC uses only the following members of the RC structure pointed to by the lprc parameter:

clErrorLevel lPcm (PCM_TIMEOUT and PCM_RANGE bits)  lpLanguage lpUser nInkWidth rgbInk wCountry wIntlPreferences wRcDirect wRcPreferences wTimeOut wTryDictionary

When InitRC is called for a new recognizer from within the SetGlobalRC call, the RC structure that is passed in contains the new values for all members except hrec and rglpdf. No new recognizer and dictionaries have been set up at this point.

When a version 1.0 application receives a WM_PENMISCINFO message, it should call ConfigRecognizer with a WCR_RCCHANGE subfunction request. This should be done for all recognizers that the application has loaded, excluding the default recognizer. The RC Manager calls ConfigRecognizer in the new default recognizer with a WCR_RCCHANGE subfunction request.

SetGlobalRC does not save the RCP_MAPCHAR flag in the wRcPreferences member of the RC structure to the system registry. The RCP_MAPCHAR flag is reflected in the global RC for the current session only.

See Also

InitRC,  GetGlobalRC,  RC


SetGuideHRC

2.0

Sets a guide structure into an HRC object.

int SetGuideHRC( HRC hrc, LPGUIDE lpguide, UINT nFirstVisible )

Parameters

hrc

Handle to the HRC object.

lpguide

Pointer to a GUIDE structure, or NULL. All coordinates are in screen coordinates.

nFirstVisible

For boxed controls, nFirstVisible refers to the first visible box (leftmost and topmost for left-right, top-down languages like English). For other controls, this is the first visible character position (leftmost for English) in a single-line control, and the first visible line (topmost for English) in multiline controls.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_INVALIDGUIDE	The guide structure is invalid.
HRCR_MEMERR	Insufficient memory.
Comments

This function is useful for doing boxed recognition. The GUIDE structure defines the size and position of the boxes. The nFirstVisible parameter notifies the recognizer which is the first visible character position (single-line controls) or line (multiline controls) in case the contents were scrolled. The writing direction affects the meaning of this value.

If lpguide is NULL, or if all the members in the GUIDE structure are 0, the recognizer does not use guides (free input).

See Also

GetGuideHRC, GUIDE


SetInternationalHRC

2.0

Sets the country, language, and script direction into a recognition context HRC.

int SetInternationalHRC( HRC hrc, UINT uCountry, LPCSTR lpszLangCode, UINT fuFlags, UINT uDir )

Parameters

hrc

Handle to the HRC object.

uCountry

The country code. A value of 0 indicates that this value should not be set.

lpszLangCode

A three-letter, null-terminated string identifying the language (for example, “enu” or “fra”), or NULL. A value of NULL indicates that the language code should not be changed. For a list of three-letter language identifiers, refer to Volume 1 of the Programmers Reference in the Windows Software Development Kit.

fuFlags

Flags. can be either SIH_ALLANSICHAR to indicate the user intends to use the entire ANSI character set, or 0.

uDir

The script direction. This parameter specifies which primary and secondary writing directions to set. The default directions are left to right for the primary direction and top to bottom for the secondary. A value of 0 indicates that the writing direction should not be changed. Possible values for uDir are:

Constant	Description
SSH_RD	Left to right and down (English).
SSH_RU	Left to right and up.
SSH_LD	Right to left and down (Hebrew).
SSH_LU	Right to left and up.
SSH_DL	Down and to the left (Chinese).
SSH_DR	Down and to the right (Chinese).
SSH_UL	Up and to the left.
SSH_UR	Up and to the right.
Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

Setting fuFlags to the value of SIH_ALLANSICHAR indicates the recognizer should interpret text written in any language based on ANSI characters. To constrain recognition to a particular language, an application should set fuFlags to 0 and provide the appropriate language code in lpszLangCode.

SetInternationalHRC overrides the default ALLANSICHAR setting in the recognizer set by ConfigHREC for the life of the HRC object. ConfigHREC should be used to change the default value.

See Also

GetInternationalHRC, ConfigHREC


SetMaxResultsHRC

2.0

Sets the maximum number of guesses a recognizer should make when interpreting pen data. When the recognizer formulates this number of results, the recognition process ends.

int SetMaxResultsHRC( HRC hrc, UINT cMaxResults )

Parameters

hrc

Handle to the HRC object for the recognizer.

cMaxResults

The maximum number of results a recognition context should generate. This value must be greater than 0.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

Subsequent calls to SetMaxResultsHRC override any previous settings. If the application does not call SetMaxResultsHRC to explicitly set a maximum value, the default number of results generated is 1.

See Also

GetMaxResultsHRC, CreateCompatibleHRC


SetPenAppFlags

2.0

An application calls this function to set pen-specific properties that apply globally to the application. This function replaces and enhances the RegisterPenApp function from version 1.0 of Pen Windows.

void SetPenAppFlags( UINT fuFlags, UINT uVersion )

Parameters

fuFlags

Flags specifying application options. The following flags can be combined by using the bitwise-OR operator:

Constant	Description
RPA_HEDIT	Specifies that the system should treat any EDIT-class controls in the application as having HEDIT class.
RPA_KANJIFIXEDBEDIT	Boxed edit controls are a fixed size appropriate for use with kanji. (Japanese version only.)
RPA_DBCSPRIORITY	By default, double-byte equivalents of single-byte characters (as used in Japan) are preferred in recognition results.
RPA_SBCSPRIORITY	By default, single-byte characters are preferred in recognition results. (Japanese version only.)
RPA_DEFAULT	Specifies default pen behavior for the application. This includes RPA_HEDIT.
uVersion

The Pen API version number. The nonzero value PENVER causes the application to be registered with Windows. A value of 0 unregisters the application.

Return Value

This function does not return a value.

Comments

SetPenAppFlags should be called when an application starts with PENVER for the uVersion parameter. PENVER is the Pen API version number, defined in PENWIN.H.

PENVER ensures that the structures used are appropriate for the version of the Pen API for which the application was compiled. In version 1.0, uVersion was a BOOL value, so by default the version number was 0x0001. Beginning with Pen API version 2.0, PENVER contains the major release number in the HIBYTE and the minor release number in the LOBYTE. Thus, for version 2.0, PENVER is defined as 0x0200.

When an application terminates, it should call SetPenAppFlags with uVersion set to 0. An application can unregister itself in this way more than once without error to accommodate alternative exit code paths.

An application can call GetPenAppFlags to determine which flags were set by an earlier call to SetPenAppFlags. However, normally only the system requires this information.

Applications written specifically for Windows 95 and later Windows versions automatically get RPA_DEFAULT so that any edit controls created by such applications become pen-aware.

See Also

GetPenAppFlags


SetPenHook

1.0     2.0

Installs and removes a pen packet hook. This function is typically used by system-level applications such as Control Panel applications.

BOOL SetPenHook( HKP hkpOp, LPFNRAWHOOK lpfn )

Parameters

hkpOp

Operation to be performed. This parameter can be HKP_SETHOOK to install a hook or HKP_UNHOOK to remove a function from the hook list.

lpfn

Pointer to callback function to handle pen packets.

Return Value

Returns TRUE if successful or FALSE if GetPenInput is unable to set or remove the hook. The callback function returns FALSE to cancel the processing of a pen packet.

Comments

The pen device generates approximately 100 hardware interrupts per second. At each interrupt, the device sends data to the pen driver, which organizes the data into a pen packet. Each packet contains the x- and y-coordinates of the current pen position, the time, and possibly extra OEM data such as pen pressure, angle, and so forth. The pen device may require more than one hardware interrupt to send all the information for a single packet, so the rate at which the driver sends pen packets may be less than the rate of interrupts generated by the pen hardware.

When it has created a pen packet, the driver passes it to the system, which buffers the packets in an internal queue as they arrive from the pen driver. The internal queue is informally known as the “ten-second buffer” to indicate how much data it can hold before overflowing. An application must call GetPenInput regularly to remove data from the queue.

SetPenHook enables an application to examine, modify, or cancel pen packets as they arrive from the pen driver before GetPenInput sees them.

See Also

SetPenHookCallback, SetResultsHookHREC, GetPenInput


SetPenHookCallback

1.0     2.0

SetPenHookCallback represents the name of the callback function that the lpfn argument of SetPenHook points to. An application can use any name.

BOOL lpfn SetPenHookCallback( LPPENPACKET lppp )

Parameters

lppp

Far pointer to the most recent pen packet received from the pen driver.

Return Value

Returns TRUE to continue processing, FALSE to cancel pen packet.

Comments

For a definition of pen packet, see the description for SetPenHook.

At each interrupt, the system adds the latest packet from the pen driver to an internal queue. It then calls the application’s SetPenHookCallback callback function, providing it with a pointer to the latest packet in the queue. This enables the callback function to examine, modify, or cancel each pen packet as it arrives from the pen driver.

To get the pen packet data from a version 2.0 pen driver, defined as OEM_PENPACKET, simply cast the LPPENPACKET value passed into this function to the type LPOEM_PENPACKET. The pen services detect the pen driver version automatically and return the correct data pen packet data type.

See Also

SetPenHook, PENPACKET


SetPenMiscInfo

1.0     2.0

Sets constants pertaining to the pen system.

LONG SetPenMiscInfo( UINT wParam, LPARAM lParam )

Parameters

wParam

Specifies the identifier of the pen system measurement to set. The identifier must be a PMI_ value, and may be combined with PMI_SAVE (to force an immediate initialization file update) using the bitwise-OR operator for some values. See the following table for the possible PMI_ values in wParam.

lParam

Specifies the value of the pen system measurement to set. Depending on the value of wParam (listed in the first column of the table below), lParam can be the address of a structure or a value, as described here:

wParam constant	lParam description
PMI_BEDIT	lParam is the address of a BOXEDITINFO structure.
PMI_ENABLEFLAGS	lParam is a WORD value.
PMI_PENTIP	lParam is the address of a PENTIP structure.
PMI_TIMEOUT	lParam is a UINT value.
PMI_TIMEOUTGEST	lParam is a UINT value.
PMI_TIMEOUTSEL	lParam is a UINT value.
Return Value

Returns PMIR_OK if successful; otherwise, returns one of the following negative error values:

Constant	Description
PMIR_INDEX	wParam is out of range.
PMIR_INIERROR	Error writing to PENWIN.INI file.
PMIR_INVALIDBOXEDITINFO	BOXEDITINFO structure is invalid.
PMIR_NA	Support for this value of wParam is not available.
PMIR_VALUE	lParam is invalid.
Comments

The type of information SetPenMiscInfo sets depends on wParam. The function is provided for system applications such as Control Panel. User applications should not generally call SetPenMiscInfo.

A WM_PENMISCINFO message is posted to all top-level windows whenever SetPenMiscInfo successfully changes a setting, forwarding the value for wParam. In the case of PMI_BEDIT, a WM_PENMISC message is also broadcast to ensure compatibility with version 1.0 of the Pen API. The wParam is set to PMSC_BEDITCHANGE and lParam is a far pointer to a BOXEDITINFO structure.

SetPenMiscInfo cannot set all the values available in GetPenMiscInfo because certain values are determined by the system. These values are PMI_SYSREC, PMI_CXTABLET, PMI_CYTABLET, PMI_SYSFLAGS, PMI_TICKREF, PMI_INDEXFROMRGB, and PMI_RGBFROMINDEX.

The flag PMI_SAVE can be combined with the wParam identifier for the following values: PMI_BEDIT, PMI_ENABLEFLAGS, PMI_PENTIP, PMI_TIMEOUT, PMI_TIMEOUTGEST, and PMI_TIMEOUTSEL. This forces Windows to immediately update its initialization information.

Example

The following code sample changes the pen color to red and the time out to a half second (500 milliseconds), then forces a save-file update:

PENTIP tip;

GetPenMiscInfo( PMI_PENTIP, (LPARAM)(LPPENTIP) &tip );

tip.rgb = RGB(255, 0, 0);

SetPenMiscInfo( PMI_PENTIP, (LPARAM)(LPPENTIP) &tip );

SetPenMiscInfo( PMI_TIMEOUT | PMI_SAVE, (LPARAM)500 );

See Also

GetPenMiscInfo,  WM_PENMISCINFO,  PMI_


SetRecogHook

1.0     2.0

Installs and removes a recognition hook. This function works only for Pen API version 1.0 recognizers accessed through Recognize or RecognizeData.

Note  This function is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions. Use SetResultsHookHREC instead.

BOOL SetRecogHook( UINT uScope, UINT uSetOp, HWND hwndHook )

Parameters

uScope

Scope of hook. The hook parameter uSetOp determines the scope of the hook. The following table lists the HWR_ values for uSetOp:

Constant	Description
HWR_RESULTS	The hook window receives a WM_HOOKRCRESULT message before a WM_RCRESULT message is sent to the target window.
HWR_APPWIDE	The hook window receives the message WM_HOOKRCRESULT before a WM_RCRESULT message is sent to the target window if the target window belongs to the same task as the window that set an HWR_APPWIDE hook. This is useful for implementing application-wide gestures.  The RCRT_ALREADYPROCESSED flag is set in the wResultsType member of the RCRESULTS structure sent with WM_RCRESULT if an application-wide hook has already processed the data.
uSetOp

Parameter to determine whether hook is set or removed. The operation parameter uSetOp determines whether the hook is set or removed. The following table lists the HKP_ values for uScope:

Constant	Description
HKP_SETHOOK	Installs a hook.
HKP_UNHOOK	Removes function from hook list.
hwndHook

Handle to a window.

Return Value

Returns TRUE if successful; otherwise, FALSE.

Comments

SetRecogHook enables a version 1.0 application to examine the results of recognition before they are sent to the target application.

The hook message is WM_HOOKRCRESULT. The wParam and lParam parameters are the same as for the WM_RCRESULT message. If the window procedure that receives the WM_HOOKRCRESULT message returns FALSE, the message WM_HOOKRCRESULT is not sent to any of the remaining hooks in the chain.

No drawing should occur during the processing of the WM_HOOKRCRESULT and before recognition is complete. Drawing at these times could cause timing problems, with ink reappearing in formerly invisible controls as they are redrawn.

See Also

SetResultsHookHREC


SetResultsHookHREC

2.0

Sets up a hook callback function for recognition results.

HRECHOOK SetResultsHookHREC( HREC hrec, HRCRESULTHOOKPROC lpfnHook )

Parameters

hrec

Module handle of the recognizer library whose results are to be hooked. If hrec is set to NULL, the hook function specified in lpfnHook receives results from the system default recognizer. If hrec is set to SRH_HOOKALL, the hook function receives results for all recognizers the application has installed, including the system recognizer.

lpfnHook

Address of the hook function.

Return Value

Returns a handle to the installed hook if successful; otherwise, the return value is NULL. The application must provide this handle when calling UnhookResultsHookHREC to remove the hook.

Comments

An application can set multiple hooks. The system calls the hooks in reverse order —that is, the most-recently-set hook is called first, then the previous hook, and so on. If a hook function captures a result, the function that requested the results returns HRCR_HOOKED to the application.

See Also

ResultsHookHREC, UnhookResultsHookHREC


SetStrokeAttributes

2.0

Sets attributes of a stroke or of a class of strokes in an HPENDATA object.

int SetStrokeAttributes( HPENDATA hpndt, UINT iStrk, LPARAM lParam, UINT uOption )

Parameters

hpndt

Handle to the HPENDATA object.

iStrk

Zero-based stroke index. A value of IX_END can be used to specify the last available stroke in the pen data.

lParam

A pointer to a structure (cast to the LPARAM type), or a byte, word, or double-word value, depending on uOption. This parameter cannot be NULL.

uOption

Specifies the attributes to set. This parameter has one of the following values:

Constant	Description
SSA_DOWN	Set the up and down state of the pen tip for the stroke specified by iStrk. lParam is nonzero to make it a downstroke or 0 to make it an upstroke.
SSA_PENTIP	Set the pen-tip characteristics (color, width, nib type) used by the stroke specified by iStrk. lParam is a pointer to a PENTIP structure. If this attribute does not already exist in the stroke class table, a new entry for this type of stroke is created. There can be up to 255 different types of strokes.
SSA_PENTIPCLASS	Set the pen-tip characteristics (color, width, nib) for all strokes of which the stroke specified by iStrk is a member. lParam is a pointer to a PENTIP structure. If the new type already exists in the stroke class table, the types are merged.
SSA_SELECT	Set the selection status of the stroke specified by iStrk. lParam is nonzero to select it or 0 to deselect it.
SSA_TIME	Set the absolute time of the stroke. lParam is a pointer to an ABSTIME structure. The sec member of the ABSTIME structure specifies the number of seconds since Jan 1, 1970, and the ms member specifies the number of milliseconds offset from that time to the beginning of the stroke.
SSA_USER	Set the user value for the stroke specified by iStrk. lParam is a BYTE, WORD, or DWORD value, and the pen data must have been created with the corresponding size allocated for user values.
SSA_USERCLASS	Set the user value for the class of strokes of which the stroke specified by iStrk is a member. lParam is a BYTE, WORD, or DWORD value, and the pen data must have been created with the corresponding size allocated for user values.
Return Value

Returns PDR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
PDR_COMPRESSED	Pen data is compressed.
PDR_ERROR	Parameter or other unspecified error.
PDR_MEMERR	Memory error.
PDR_PNDTERR	Invalid pen data.
PDR_SCTERR	Stroke class table may be full, or related error.
PDR_STRKINDEXERR	Invalid stroke index.
PDR_TIMESTAMPERR	Timing information was removed.
PDR_VERSIONERR	Could not convert old pen data.
Comments

The bounding rectangle of the pen data is recalculated each time the SSA_DOWN option is used, because the rectangle represents the bounds of only the pen-down points. Setting a pen-up point to the down state simply adds (union) the bounding rectangles of the existing pen data and the stroke. Setting a pen-down point to the up state is more calculation-intensive, however, since the bounding rectangle must be calculated from all of the remaining strokes.

See Also

CreatePenDataEx, GetStrokeAttributes, GetStrokeTableAttributes, SetStrokeTableAttributes, PENTIP


SetStrokeTableAttributes

2.0

Sets attributes of a stroke’s class within an HPENDATA object. (The class is an entry in a table stored in the PENDATAHEADER structure. Modifying the table entry affects all the strokes described by the entry.)

int SetStrokeTableAttributes( HPENDATA hpndt, UINT iTblEntry, LPARAM lParam, UINT uOption )

Parameters

hpndt

Handle to the HPENDATA object.

iTblEntry

Zero-based table index to the class entry in the pen data header.

lParam

A pointer to a structure (cast to the LPARAM type), or a byte, word, or doubleword value, depending on uOption. This parameter cannot be NULL.

uOption

Specifies the attributes to set. This parameter can be one of the following:

SSA_PENTIPTABLE

Set the pen-tip characteristics (color, width, nib) of the class of strokes specified by iTblEntry. lParam is a pointer to a PENTIP structure. All the strokes sharing this entry in the stroke class table receive the new pen-tip attribute.

SSA_USERTABLE

Set the user value, if any, of the class of strokes specified by iTblEntry. lParam is a byte, word, or doubleword value, and the pen data must have been created with the corresponding size allocated for user values. All the strokes sharing this stroke class table entry receive the new user value.

Return Value

Returns PDR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
PDR_COMPRESSED	Pen data is compressed.
PDR_ERROR	Parameter or other unspecified error.
PDR_MEMERR	Memory error.
PDR_PNDTERR	Invalid pen data.
PDR_SCTERR	Stroke class table may be full, or related error.
PDR_VERSIONERR	Could not convert old pen data.
See Also

CreatePenDataEx, GetStrokeAttributes, GetStrokeTableAttributes, SetStrokeAttributes, PENTIP


SetWordlistCoercionHRC

2.0

Specifies to what degree input must match a word list set into an HRC. SetWordlistCoercionHRC determines the influence a recognizer’s word list or dictionary has on the recognizer’s guesses.

int SetWordlistCoercionHRC( HRC hrc, UINT uCoercion )

Parameters

hrc

Handle to the HRC object.

uCoercion

Coercion flag. This can be one of the following:

SCH_ADVISE

The word list serves only to advise the recognizer, but lacks a strong degree of influence. Recognition results are not strongly coerced to match the word list.

SCH_FORCE

If the recognizer’s guess is not found in the word list, the closest matching entry in the list is returned. For example, if the recognizer interprets writing as “Cana”, it returns “Canada” from a word list of country names.

SCH_NONE

Do not coerce. This flag can be used to turn off a previous request.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error, including an attempt to set coercion with no word lists set into the recognition context.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

The default type of coercion a recognizer provides is SCH_ADVISE. That is, results are not strongly coerced to any word list that might be set into a recognition context.

Coercion is used only if a word list (HWL) has actually been set into an HRC with SetWordlistHRC, or if the recognizer’s dictionary is enabled by EnableSystemDictionaryHRC. If the HRC is configured with a word list and the recognizer’s dictionary is also enabled, coercion is done on both; the priority depends on the recognizer.

See Also

CreateHWL, GetWordlistCoercionHRC


SetWordlistHRC

2.0

Sets a word list into a recognition context HRC object.

int SetWordlistHRC( HRC hrc, HWL hwl )

Parameters

hrc

Handle to the HRC object.

hwl

Handle to a word list to use, or NULL. A value of NULL means that the recognizer should not constrain recognition based on any word list, including its own dictionary.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

Specifying NULL for hrc does not destroy the word list specified by hwl. Applications must call DestroyHWL to destroy a word list.

Only one word list can be set into an HRC at a time. This is independent of the recognizer’s dictionary, which can be manipulated through the function EnableSystemDictionaryHRC.

For a description of word lists and how a recognizer uses them, see “Configuring the HRC” in Chapter 5, “The Recognition Process.”

See Also

CreateHWL, DestroyHWL


ShowKeyboard

1.0     2.0

Shows or hides the on-screen keyboard. (Not supported in Japanese version.)

Note  This function is provided only for compatibility with version 1.0 of the Pen API, and will not be supported in future versions. It is not supported for 32-bit applications. Applications should interface directly with the on-screen keyboard.

BOOL ShowKeyboard( HWND hwnd, UINT wCommand, LPPOINT lppt, LPSKBINFO lpSKBInfo )

Parameters

hwnd

Handle of window invoking the on-screen keyboard.

wCommand

A show request and optional keypad. The values for the show requests are listed in the “Comments” section below.

lppt

Address of a POINT structure containing the keyboard position in screen coordinates. If NULL, the keyboard appears centered on the display.

lpSKBInfo

Address of an SKBINFO structure to be filled with values for the current keyboard. This parameter is ignored if NULL. If the hwnd member of the SKBINFO structure is NULL, no on-screen keyboard has been loaded.

Return Value

Returns TRUE if successful; otherwise FALSE.

Comments

Any user action on the keyboard itself overrides the function requests. For example, if the user closes the on-screen keyboard, the keyboard becomes unregistered for all windows in all applications. If the user minimizes the keyboard, the active SKBINFO structure is changed to reflect the new state.

ShowKeyboard tracks registration information for up to 20 window handles. If one application displays the keyboard and then another one does the same thing, both applications must request that the keyboard be hidden before it actually disappears.

The following SKB_ requests can be specified in the wCommand parameter:

Constant	Description
SKB_HIDE	Hides the on-screen keyboard. This request may not actually hide the keyboard if another application is also using it. The command decrements the use count for the keyboard. SKB_HIDE automatically loads the on-screen keyboard if it is not already present.
SKB_QUERY	Returns the current state of the keyboard pointed to  by the lpSKBInfo parameter without invoking a new keyboard state. This command does not automatically load the on-screen keyboard.
SKB_SHOW	Shows the on-screen keyboard in a restored state at  the most recently used screen location. This command increments a window-use count. SKB_SHOW automatically loads the on-screen keyboard if it is not present.
The SKB_SHOW command in the wCommand parameter can be combined using the bitwise-OR operator with any of the command or keypad requests listed in the following tables:

Constant	Description
SKB_CENTER	Centers the keyboard on the display. This command  has higher priority than SKB_MOVE.
SKB_MINIMIZE	Displays the on-screen keyboard in a minimized state. This command can be used with SKB_CENTER or SKB_MOVE. If it is used with SKB_MOVE, the location specified will be used when the keyboard is restored.
SKB_MOVE	Moves the keyboard to the location specified by the lppt parameter. If lppt is NULL, the keyboard is centered on the screen. If it is not NULL, lppt specifies a pointer to the x and y screen coordinates of the upper-left corner of the restored keyboard.
The following keypad requests can be used with SKB_SHOW in the wCommand parameter. The SKB_BASIC, SKB_FULL, and SKB_NUMPAD constants can not be combined with the OR operator:

Constant	Description
SKB_BASIC	Switches the keyboard to a partial keyboard with no extended keys.
SKB_FULL	Switches the keyboard to the full 101-key display.
SKB_NUMPAD	Switches the keyboard to a partial keyboard consisting only of ESC, TAB, SHIFT, and the numeric keypad.
The following three bitmaps are provided for owner-draw push buttons that can be used to invoke the on-screen keyboard. The application must process WM_DRAWITEM and other button-related code. On-screen keyboard push buttons should behave the same way as other standard buttons (for example, the Minimize button) and take the appropriate action when a button-up message is received following a button-down message.

Constant	Description
OBM_SKBBTNUP	Push button is up.
OBM_SKBBTNDOWN	Push button is down.
OBM_SKBBTNDISABLED	Push button is disabled.
Example

The up bitmap, for example, can be loaded as shown in the following code sample:

HANDLE hDLL = GetSystemMetrics( SM_PENWINDOWS );

HBITMAP hBitmap = LoadBitmap( hDLL,

MAKEINTRESOURCE(OBM_SKBBTNUP) );

The application must call the Windows DeleteObject function to delete each bit-map handle returned by the Windows LoadBitmap function.

The button should be left in the up state after it is released. If the user closes the keyboard and the buttons are up, they will still be up the next time the keyboard is opened. The following code sample retrieves the current keyboard and restores the current state:

#include <penwin.h>

if (ShowKeyboard( hwnd, SKB_SHOW, NULL, NULL)) // Nonzero: no error.

{

.

.                        // Perform some tasks.

.

ShowKeyboard( hwnd, SKB_HIDE, NULL, NULL );

}

else

ErrorMsg( "Unable to use Screen Keyboard" );

The following code sample moves the keyboard and then puts it back into its starting position:

SKBINFO skbinfo;

WORD wCommand = SKB_SHOW | SKB_MOVE;

POINT pnt;

pnt.x = wSKBLeft;    // Initialize point.

pnt.y = wSKBTop;

// Show the keyboard.

ShowKeyboard( hwnd, wCommand, &pnt, &skbinfo );

.

.

.

// Now restore the keyboard.

if (skbinfo.fVisible)

wCommand = SKB_SHOW | SKB_MOVE |

(skbinfo.fMinimized ? SKB_MINIMIZED : 0);

else

wCommand = SKB_HIDE;

ShowKeyboard( hwnd, wCommand, (LPPOINT)(&skbinfo.rect), NULL) ;


StartInking

2.0

Starts inking feedback while pen input is being collected.

int StartInking( HPCM hpcm, UINT idEvent, LPINKINGINFO lpinkinginfo )

Parameters

hpcm

Handle to the current collection. This is the return value from StartPenInput.

idEvent

The identifier of the packet at which to start inking.

lpinkinginfo

Address of an INKINGINFO structure, used to specify the characteristics of the ink. This parameter can be NULL to use the default ink characteristics. Otherwise, the structure’s cbSize member must be initialized with sizeof( INKINGINFO ).

Return Value

Returns PCMR_OK if inking started successfully; otherwise, returns one of the following:

Constant	Description
PCMR_DISPLAYERR	There is no display device, or it was unable to ink at this time, or there was an error in setting the pen-tip characteristics.
PCMR_ERROR	The INKINGINFO structure contains invalid values, or there was some other unspecified error.
PCMR_INVALIDCOLLECTION	The hpcm handle is invalid because the calling application did not start input by calling StartPenInput.
PCMR_INVALID_PACKETID	The idEvent parameter is invalid.
Comments

An application calls StartInking to track pen movement while the pen tip is down. When pen input is started by calling the StartPenInput function, Windows initializes the internal INKINGINFO structure as follows:

•	The wFlags member is set to PII_INKPENTIP | PII_INKCLIPRECT.

•	The tip member is set to the system default pen tip, as obtained by calling the GetPenMiscInfo function.

•	The rectClip member is set to the client area, in screen coordinates, of the window that was used in the call to the StartPenInput function.

The first call to StartInking with the lpinkinginfo parameter set to NULL starts inking with the settings listed above. If the calling application uses a non-NULL value for lpinkinginfo, the appropriate internal inking parameters are modified before inking starts, depending on the flags set in the wFlags member of the INKINGINFO structure.

Whenever StartInking is called, the current settings of the internal inking structure are added to or replaced. Specific values must be set in the members of INKINGINFO to disable them. Refer to the description of each member in the INKINGINFO structure for these values.

If a region is passed in for clipping or stopping the ink, the application must destroy the region. Since a copy is made, the region can be destroyed immediately following the call to StartInking. The application can specify either a clip region or a clip rectangle. Specifying both will result in the clip rectangle being ignored.

Example

The following code example changes the inking tip from the default (as set by a call to StartPenInput) to red ink, 5 pixels wide. It also adds an inkstop rectangle (inking stops if the pen touches down inside the inkstop rectangle). The clipping rectangle remains unchanged from the default settings.

INKINGINFO inkinginfo;

inkinginfo.cbSize           = sizeof( INKINGINFO );

inkinginfo.wFlags           = PII_INKPENTIP | PII_INKSTOPRECT;

inkinginfo.tip.cbSize       = sizeof( PENTIP );

inkinginfo.tip.rgb          = RGB( 255,0,0 );

inkinginfo.tip.bwidth       = 5;

inkinginfo.rectInkStop.left = rectInkTop.top = 0;

inkinginfo.rectInkStop.right = rectInkTop.bottom = 100;

ClientToScreen( hwnd, (LPPOINT)&(inkinginfo.rectInkStop) );

ClientToScreen( hwnd, (LPPOINT)&(inkinginfo.rectInkStop.right) );

StartInking( hpcm, wEventRef, &inkinginfo );

See Also

INKINGINFO, StartPenInput, StopInking


StartPenInput

2.0

Begins collecting information from the pen input stream.

HPCM StartPenInput( HWND hwnd, UINT idEvent, LPPCMINFO lppcmInfo, LPINT lpiErrRet )

Parameters

hwnd

Handle of the window that receives the WM_PENEVENT messages generated by StartPenInput.

idEvent

Identifies the packet in the global queue of pen packets maintained internally by the system. The idEvent is the low-order word of the value returned from the GetMessageExtraInfo function when processing a WM_LBUTTONDOWN message. For a definition of pen packet, see the description for SetPenHook.

lppcmInfo

Address of a PCMINFO structure. If NULL, the system creates a default PCMINFO structure with the following values:

Constant	Description
dwPcm	PCM_RECTBOUND | PCM_TIMEOUT | PCM_TAPNHOLD
rectBound	The bounding rectangle of the window identified by hwnd These values determine that the input session (a) terminates when pen activity ceases for a specified time-out period; (b) terminates when the pen moves outside the bounds of the window; or (c) does not begin at all if the user taps and holds the pen for a specified time-out period (about one-half second). This “tap-and-hold” gesture switches the system from input mode to selection mode. Usually, the cursor changes from a pen (indicating input) to an upside-down arrow (indicating selection) to acknowledge the switch. Subsequent pen movement then behaves as a mouse with the left button held down. This allows the user to make selections as though dragging the mouse.
lpiErrRet

Address of an integer that receives a return code when StartPenInput terminates. If NULL, no return code is provided. If not NULL, the return code is one of the following values:

Constant	Description
PCMR_OK	Pen collection was successfully started.
PCMR_ALREADYCOLLECTING	StartPenInput has already been called for this session.
PCMR_ERROR	Illegal parameter or unspecified error.
PCMR_INVALID_PACKETID	Invalid idEvent parameter.
PCMR_SELECT	Tap-and-hold gesture detected. Collection is not started, as described in the description of the lppcmInfo parameter.
PCMR_TAP	The pen has briefly tapped the tablet. This event may be inadvertent and in any case does not indicate that the user has started to write; therefore, collection is not started.
Return Value

Returns a handle to the application’s queue of pen packets, if successful. Returns NULL to indicate an error or the detection of a tap or press-and-hold condition.

Comments

When this function returns successfully, Windows creates a queue of pen packets for the calling application. All subsequent pen packets from the pen device, beginning with the packet identified by the idEvent argument, are placed into the queue. Until a termination condition occurs (as specified in the lppcmInfo parameter), or until the application calls StopPenInput, the queue continues to receive all the packets generated by the pen device as the pen moves.

An application can retrieve all the pen input in its queue of pen packets but should never destroy the queue.

In event mode (the default mode), the collection session specified by the hpcm of the GetPenInput function becomes invalid when the WM_PENEVENT message (with the PE_TERMINATED submessage) is removed from the application’s message queue. This message is posted to the application’s message queue either as a consequence of automatic termination or a call to StopPenInput.

In polling mode, the application’s queue of pen packets is destroyed (and the hpcm of GetPenInput becomes invalid) after a successful call to StopPenInput or a termination return value from the GetPenInput function.

If lppcmInfo is NULL, a default PCMINFO structure is established with the dwPcm member set to PCM_RECTBOUND | PCM_TIMEOUT | PCM_TAPHOLD, the rectBound member set to the bounds of hwnd, and the dwTimeout member set to the default system time out.

If the dwPcm member of PCMINFO does not have the PCM_DOPOLLING flag set, WM_PENEVENT messages are sent to the specified window for significant events such as pen down, pen up, or after some threshold number of points has been received. Otherwise, the application should poll for data using GetPenInput.

Other bits in the dwPcm member of PCMINFO can be used to determine which conditions, if any, terminate pen input. An application can also call StopPenInput to explicitly terminate the input.

Example

The following example initiates pen input in a window procedure on detection of pen down:

static HPCM vhpcm;

//... omitted ...

switch (message)

{

case WM_LBUTTONDOWN:

{

// Get extra info associated with event:

DWORD dwExtraInfo = GetMessageExtraInfo();

if (IsPenEvent( message, dwExtraInfo ))   // Checks PDK bits

{

PCMINFO pcminfo;        // Pen collection mode structure

pcminfo.cbSize    = sizeof( PCMINFO );

pcminfo.dwPcm     = PCM_RECTBOUND | PCM_TIMEOUT;

pcminfo.dwTimeout = dwTimeOutDefault;   // 1 second

// Set inclusion rect to client area, but in screen coords:

GetClientRect( hwnd, &pcminfo.rectBound );

ClientToScreen( hwnd, (LPPOINT) &pcminfo.rectBound );

ClientToScreen( hwnd, (LPPOINT) &pcminfo.rectBound.right );

// Start gathering input:

if (vhpcm = StartPenInput( hwnd,

LOWORD( dwExtraInfo ), &pcminfo, NULL ))

return 1L;                         // We handled it

}

// Else fall into DefWindowProc below...

}

break;

See Also

GetPenInput, StopPenInput, PCMINFO WM_PENEVENT, PCM_


StopInking

2.0

Stops inking feedback.

int StopInking( HPCM hpcm )

Parameters

hpcm

Handle to the current collection. This is the return value from StartPenInput.

Return Value

Returns PCMR_OK if successful; otherwise, returns the following value:

Constant	Description
PCMR_INVALIDCOLLECTION	The hpcm handle is invalid, or there is no collection, or inking has not been started.
Comments

Inking must have been started by using the StartInking function for this function to have any effect.

See Also

StartInking


StopPenInput

2.0

Terminates collection of pen input.

int StopPenInput( HPCM hpcm, UINT idEvent, int nTermReason )

Parameters

hpcm

Handle to the collection of the pen data gathered during the input session. HPCM stands for “handle to a pen collection mode.”

idEvent

The identifier of the packet in the task-specific queue at which the pen input should be terminated. If this value is PID_CURRENT, pen input stops immediately (that is, at the latest position in the task queue) and no further input is collected. The idEvent parameter is the low-order word of the value returned from the Windows GetMessageExtraInfo function when processing a WM_LBUTTONDOWN message.

nTermReason

The reason for termination. This value is passed to the termination message PE_TERMINATED. It can be one of the following:

Constant	Description
PCMR_APPTERMINATED	Application terminated input.
PCMR_TERMBOUND	Pen was pressed outside bounding rectangle or region.
PCMR_TERMEX	Pen was pressed inside exclusion rectangle or region.
PCMR_TERMPENUP	Pen was lifted from the tablet.
PCMR_TERMRANGE	Pen left the tablet’s range of sensitivity.
PCMR_TERMTIMEOUT	Time-out expired.
Return Value

Returns PCMR_OK if successful; otherwise, the return value can be one of the following:

Constant	Description
PCMR_INVALIDCOLLECTION	The hpcm handle is invalid because the calling application did not start input with StartPenInput.
PCMR_INVALID_PACKETID	idEvent is invalid.
Comments

This function allows an application to explicitly terminate pen collection without waiting for one of the conditions specified by StartPenInput in the dwPcm member of PCMINFO.

Due to the asynchronous nature of pen input messages, the application should wait for the WM_PENEVENT message with wParam set to PE_TERMINATED to make sure that the pen input process has completely terminated. This does not apply if the application is using the polling method of pen input.

See Also

StartPenInput


SymbolToCharacter

1.0     2.0

Converts an array of SYV_ symbol values to an ANSI string.

BOOL SymbolToCharacter( LPSYV lpsyv, int cSyv, LPSTR lpstr, LPINT lpnConv )

Parameters

lpsyv

Address of the array of SYV_ symbol values.

cSyv

Count of symbols in the lpsyv array, including the terminating SYV_NULL.

lpstr

Address of a buffer that receives the ANSI string. The buffer should be large enough to hold at least cSyv number of ANSI characters (including SYV_NULL).

lpnConv

If not NULL, lpnConv contains the number of symbols converted when the function returns. If NULL, this parameter is ignored.

Return Value

Returns TRUE if successful. If one or more symbols cannot be converted to ANSI, the return value is FALSE.

Comments

For ANSI characters, the size of the lpstr buffer must be at least cSyv bytes. For double-byte characters (kanji, for example), the buffer size must be at least (2 * cSyv) bytes. The SymbolToCharacter function converts at most cSyv symbol values from lpsyv and places the equivalent ANSI characters in the lpstr buffer. The conversion proceeds until an SYV_NULL value is encountered or until cSyv symbols have been converted. An SYV_NULL is converted to 0. The actual number of symbols converted is returned in lpnConv if lpnConv is not NULL.

See Also

CharacterToSymbol, SYG, SYV_


TargetPoints

2.0

Determines the target to which pen data belongs.

int TargetPoints( LPTARGINFO lptarginfo, LPPOINT lppt, DWORD dwReserved, UINT fuReserved, LPSTROKEINFO lpsi )

Parameters

lptarginfo

Address of a targeting data TARGINFO structure.

lppt

Address of a buffer of POINT structures in tablet coordinates.

dwReserved

This parameter is reserved for future use and its value is ignored.

fuReserved

This parameter is reserved for future use and its value is ignored.

lpsi

A pointer to a STROKEINFO structure. This structure holds information about the stroke being targeted.

Return Value

Returns an array index, starting from 0, of the target in the rgTarget array of the TARGINFO structure, if successful. If no suitable target is found, or if there are no points to target, TargetPoints returns −1.

Comments

To select the desired targeting behavior, the application should set the dwFlags member of the TARGINFO structure that lptarginfo points to.

See Also

GetPenInput,  TARGET,  TARGINFO


TPtoDP

1.0     2.0

Converts points in tablet coordinates to display (screen) coordinates.

BOOL TPtoDP( LPPOINT lppt, int cPnt )

Parameters

lppt

Address of an array of POINT structures to convert to display coordinates. This parameter cannot be NULL.

cPnt

Number of POINT structures to convert.

Return Value

Returns TRUE if the conversion was successful; otherwise, returns FALSE.

Comments

The conversion fails if some tablet points lie outside the region mapped to the screen.

Because of rounding errors, the DPtoTP and TPtoDP functions are not guaranteed to be perfect inverses of each other.

See Also

DPtoTP


TrainContext

1.0     2.0

Provides the recognizer a previous recognition result that may contain errors, plus the correct interpretation of the raw data.

Note  This function is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions. Use TrainHREC instead.

BOOL TrainContext( LPRCRESULT lprcresult, LPSYE lpsye, int csye, LPSYC lpsyc, int csyc )

Parameters

lprcresult

Address of the RCRESULT structure containing the handle to the pen data that contains the raw data and the recognizer’s original interpretation of that data. This parameter cannot be NULL.

lpsye

Address of an array of SYE structures that specify the correct interpretation of the raw data. The values of the  iSyc members of these structures index the SYC structures pointed to be the lpsyc parameter.

csye

The number of SYE structures in the lpsye array.

lpsyc

An array of SYC structures that establish the mapping between the raw data and the characters in the hpendata member of the structure pointed to by the lprcresult parameter.

csyc

The number of SYC structures in the lpsyc array.

Return Value

Returns TRUE if the ink is accepted for training; otherwise, returns FALSE.

Comments

TrainContext is called by an application with a recognition result that may contain mistakes, along with a correct interpretation, so that the recognizer can learn from the mistake and improve subsequent recognition. A second, simpler training function for 1.0 recognizers is provided by TrainInk.

TrainContext internally calls the function TrainContextInternal exported by the recognizer identified by the hrec member of the RC structure pointed to by the lprc member of the RCRESULT structure. A version 1.0 recognizer should export both TrainContextInternal and TrainInkInternal, but can simply return FALSE from both functions if the recognizer does not support this type of training.

When a training application is able to provide contextual information (such as segmentation suggestions) to the version 1.0 recognizer, it calls the TrainContext function. The lprcresult parameter points to an RCRESULT structure that contains the results of a previous recognition. The raw data is also contained in the hpendata member of the structure pointed to be lprcresult.

In addition to providing the incorrect interpretation of the data (by means of the symbol graph, the lpsyv member in the RCRESULT structure), a more detailed, correct interpretation is also provided by the SYE structures and SYC structures. Because the correct interpretation is passed by SYE structures, it is possible to suggest segmentation boundaries to the recognizer.

Suppose, for example, that a user writes “lc,” and the recognizer interprets it as “k”. A trainer calls TrainContext using, first, an array of SYC structures that point to the ink of the “lc” and, second, the two SYE structures with the SYV values “l” and “c”. These two SYE structures share the same index into the lpsyc array, indicating that both use the ink that was interpreted as “k”.

Segmentation errors can be corrected in the other direction as well. Suppose, for example, the user writes “k” and the recognizer interprets it as “lc”. A trainer could call TrainContext using a single SYE with SYV values equal to “k” and an array of SYC structures that incorporate the ink the recognizer had previously assigned to the “l” and the “c”.

To train several SYV symbol values to a single piece of ink (for example, a long stroke that is an “he” ligature), there will be two consecutive SYE structures—one for the “h” and one for the “e”. Both SYE structures have the same iSyc member; this means that the SYE structures both point to the same ink. A recognizer must take this into consideration to avoid training the two characters separately using the same ink for both; that would result in having “he” trained as “he he”.

A recognizer can supply its own custom training dialog boxes. An application should check whether the recognizer supports custom training by calling ConfigRecognizer with the WCR_TRAIN subfunction.

The trainer does not display an error message if TrainInk or TrainContext returns FALSE. Error messages that occur when training fails must be handled by the recognizer.

See Also

ConfigRecognizer, TrainInk, TrainHREC, SYC,  SYE,  SYV_


TrainHREC

2.0

Passes ink and its symbol interpretation to the recognizer for training.

int TrainHREC( HREC hrec, LPSYV lpsyv, UINT cSyv, HPENDATA hpndt, UINT uConflict )

Parameters

hrec

Module handle of the recognizer library. If this value is NULL, the system default recognizer is used.

lpsyv

Address of an array of symbols to train.

cSyv

Count of symbols in lpsyv. This must be greater than 0.

hpndt

Handle to an HPENDATA object.

uConflict

One of the following TH_ values that specify how to handle training conflicts:

Constant	Description
TH_QUERY	Query the user if the proposed training conflicts with symbols in the database.
TH_FORCE	Perform the training without querying the user, even if there is a conflict with the database.
TH_SUGGEST	Abandon the training if there is any conflict with the database and return an error (HRCR_CONFLICT).
Return Value

Returns HRCR_OK if training is successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_CONFLICT	TH_SUGGEST was specified but there was a conflict with the database. No training was done.
HRCR_INVALIDPNDT	Invalid HPENDATA object.
HRCR_MEMERR	Insufficient memory.
HRCR_UNSUPPORTED	The recognizer does not support this function.
Comments

Typically, an application calls TrainHREC to train a single symbol. In other words, lpsyv points to a single symbol that is followed by an SYV_NULL terminator. However, multiple symbols—for example, those representing the character string “ng”—may also be trainable, depending on the recognizer.

If uConflict is TH_QUERY, the recognizer is free to prompt the user with a dialog box to resolve training conflicts. If it is TH_FORCE, the training is performed regardless of conflicts and the original conflicting data may be lost. TH_SUGGEST trains the recognizer only if there are no conflicts; otherwise, the call fails and returns HRCR_CONFLICT.

If the user picks a meaning for some ink from a list of alternatives, such as in a boxed edit control, the application can elect to train the recognizer with this information. In this case, either TH_FORCE or TH_SUGGEST is a suitable value for uConflict.

Training gestures depends on the recognizer. The Microsoft Handwriting Recognizer (GRECO.DLL) does not support training for gestures.

See Also

CreateCompatibleHREC


TrainInk

1.0     2.0

Provides raw data and a correct interpretation of the data to the recognizer.

Note  This function is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions. Use TrainHREC instead.

BOOL TrainInk( LPRC lprc, HPENDATA hpndt, LPSYV lpsyv )

Parameters

lprc

Address of an RC structure, or NULL. If this parameter is NULL, the RC Manager replaces it with a pointer to the global RC structure, then calls the recognizer associated with the global RC. If lprc is not NULL, the RC Manager calls the recognizer identified by the hrec member of the RC structure.

hpndt

Handle to an HPENDATA object containing the ink to be trained. This parameter cannot be NULL.

lpsyv

Pointer to a string of SYV symbol values terminated by SYV_NULL. This parameter cannot be NULL.

Return Value

Returns TRUE if the ink described by the pen data could be trained; otherwise, it returns FALSE.

Comments

Applications call TrainInk with raw data accompanied by a correct interpretation of the data, so that the recognizer can improve subsequent recognition. A second, more complex training function for version 1.0 recognizers is provided by TrainContext.

TrainInk is called by an application to access the TrainInkInternal function in the recognizer library. A private 1.0 recognizer must export both TrainInkInternal and TrainContextInternal, but the functions can simply return FALSE if the recognizer does not support this type of training.

TrainInk provides the lowest level of basic shape training. It requests the recognizer to assign the meaning in lpsyv to the ink in hpndt. The recognizer should interpret the ink to meet that request.

In the most common case, lpsyv points to a single character, and the recognizer will train a new shape based on the ink and that character. In other cases, multiple SYV symbol values can be passed, indicating that the ink represents multiple characters. The recognizer must decide whether to simply add a new shape with a meaning based on multiple SYV symbol values or to segment the ink into separate shapes for each SYV.

An application should check whether a recognizer supports training by calling ConfigRecognizer with the WCR_TRAIN subfunction.

The trainer does not display an error message if TrainInk or TrainContext returns FALSE. Error messages that occur when training fails must be handled by the recognizer.

See Also

ConfigRecognizer,  TrainContext,  TrainHREC, SYV_


TrimPenData

2.0

Removes selected data from an HPENDATA object.

HPENDATA TrimPenData( HPENDATA hpndt, DWORD dwTrimOptions, DWORD dwReserved )

Parameters

hpndt

Handle to the HPENDATA object.

dwTrimOptions

The following option flags are listed in the order in which the trimming operations are performed. For example, OEM data is removed (TPD_OEMDATA) before duplicate points (TPD_COLLINEAR).

Constant	Description
TPD_RECALCSIZE	Recalculate size of pen data and reallocate if smaller.
TPD_UPPOINTS	Remove pen-up strokes from the HPENDATA object.
PHW_PRESSURE	Remove OEM pressure information.
PHW_HEIGHT	Remove OEM height information.
PHW_ANGLEXY	Remove OEM XY-angle information.
PHW_ANGLEZ	Remove OEM Z-angle information.
PHW_BARRELROTATION	Remove OEM barrel rotation information.
PHW_OEMSPECIFIC	Remove OEM-specific value information.
PHW_PDK	Remove per-point Pen Driver Kit (PDK_) information.
TPD_PHW	Remove all OEM and PDK information, but not stroke tick or user data.
TPD_OEMDATA	Remove all OEM values and PDK data.
TPD_PENINFO	Remove PENINFO structure from header. Note that any OEM information present is discarded.
TPD_COLLINEAR	Remove collinear and duplicate (coincident) points. There may not be any OEM data.
TPD_USER	Remove per-stroke user information.
TPD_TIME	Remove per-stroke timing information.
TPD_EMPTYSTROKES	Remove all strokes with 0 points.
TPD_EVERYTHING	Remove everything possible except pen-down strokes. This includes both TPD_ and PHW_ flags.
dwReserved

Must be 0.

Return Value

Returns PDR_OK if successful; otherwise, it returns one of the following negative values:

Constant	Description
PDR_COMPRESSED	The pen data was compressed.
PDR_ERROR	An unspecified memory error occurred.
PDR_MEMERR	Memory error.
PDR_OEMDATAERR	The pen data does not have specific pressure or height (PHW_) information. Thus, the specified PHW_ data could not be selectively trimmed. Use TPD_OEMDATA to remove all OEM information.
PDR_PNDTERR	Invalid pen data.
PDR_VERSIONERR	A version 1.0 pen data object could not be converted to the 2.0 format.
Comments

TrimPenData supplements the capabilities of CompressPenData. Together, these two functions replace the version 1.0 Pen API function CompactPenData, which is supported for compatibility only.

The data that hpndt points to must not be compressed. If it is, TrimPenData simply retrieves the original (untrimmed) pen data.

See Also

CompactPenData, CompressPenData, PDK_


UnhookResultsHookHREC

2.0

Unhooks a recognizer result hook set with the SetResultsHookHREC function.

int UnhookResultsHookHREC( HREC hrec, HRECHOOK hHook )

Parameters

hrec

Module handle of the recognizer library. If this value is NULL, the system default recognizer is used.

hHook

Handle of the hook function.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter or other error.
HRCR_MEMERR	Insufficient memory.
See Also

ResultsHookHREC, SetResultsHookHREC


UninstallRecognizer

1.0     2.0

Unloads a recognizer previously installed with InstallRecognizer.

void UninstallRecognizer( HREC hrec )

Parameters

hrec

Recognizer handle.

Return Value

This function does not return a value.

Comments

Windows maintains a use count for all installed recognizers and doesn’t unload a recognizer until the last remaining client application has called UninstallRecognizer. For every call an application makes to InstallRecognizer, it must must make a matching call to UninstallRecognizer.

Before unloading a recognizer library, the system calls the recognizer’s ConfigRecognizer function with the subfunction WCR_CLOSERECOGNIZER.

It is not necessary to uninstall the default recognizer; an application must uninstall all recognizers that it explicitly loads.

See Also

InstallRecognizer, ConfigHREC


UpdatePenInfo

1.0     2.0

Notifies the RC Manager that a PENINFO value has changed. This function is called by pen drivers compatible with version 1.0 of the Pen API.

Note  This function is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions.

void UpdatePenInfo( LPPENINFO lppeninfo )

Parameters

lppeninfo

Address of a PENINFO structure containing the new information.

Return Value

This function does not return a value.

Comments

A PENINFO value may change when the user alters the driver parameters in the configuration dialog box. When this happens, the pen driver must call UpdatePenInfo to notify the RC Manager of the change.

See Also

PENINFO


WriteHWL

2.0

Writes a word list to a file.

int WriteHWL( HWL hwl, HFILE hfile )

Parameters

hwl

Handle to a word list.

hfile

A handle to a file previously opened for writing.

Return Value

Returns HRCR_OK if successful; otherwise, returns one of the following negative values:

Constant	Description
HRCR_ERROR	Invalid parameter, or file or other error.
HRCR_MEMERR	Insufficient memory.
Comments

The words are saved as ANSI text, one word per line, followed by a carriage return and linefeed. The file must already exist and be open for writing. An application can append to the file by positioning the file pointer at the end before calling WriteHWL. In this context, a word can represent a phrase and contain spaces or other noncharacters, such as “New York” and “ne’re-do-well.”

For a description of word lists and how a recognizer uses them, see “Configuring the HRC” in Chapter 5, “The Recognition Process.”

See Also

CreateHWL, ReadHWL


Pen Application Programming Interface Structures

This chapter describes in alphabetical order the structures defined by the Pen Application Programming Interface (API). Each entry includes the structure typedef definition, descriptions of the structure members, and cross-references where appropriate. The entry heading identifies the Pen API version, such as 1.0 or 2.0, that supports the structure.


ABSTIME

2.0

Absolute time structure.

typedef struct {

DWORD sec;

UINT ms;

} ABSTIME;

Members

sec

Number of seconds since 12:00 A.M. of January 1, 1970, as returned by the C run time library time function.

ms

Additional offset in milliseconds. This member can be any value from 0 through 999.

See Also

GetStrokeAttributes, SetStrokeAttributes, INTERVAL


ANIMATEINFO

2.0

Animation information used by the DrawPenDataEx function for animation control.

typedef struct {

DWORD cbSize;

UINT uSpeedPct;

UINT uPeriodCB;

UINT fuFlags;

LPARAM lParam;

DWORD dwReserved;

} ANIMATEINFO;

Members

cbSize

Size of this structure in bytes.

uSpeedPct

Drawing speed, expressed as a percentage of the user’s entry speed. To redraw pen data at the same speed at which it was created, this value should be set to 100. A value of 0 halts drawing. Setting uSpeedPct to 0 is valid only if the lpfnAnimateCB parameter of DrawPenDataEx is defined. Otherwise, the drawing halts with no way to restart it. uSpeedPct can be changed by a call-back function.

uPeriodCB

Callback period in milliseconds. Typical values are 1 (very fast), 250 (fast), 1000 (slow), or 0 (never). Any value in uPeriodCB is ignored if the DrawPenDataEx argument lpfnAnimateCB is NULL. uPeriodCB may also be AI_CBSTROKE, to indicate that the callback should occur after each stroke is drawn.

fuFlags

Flags that control animation (can be 0). The AI_SKIPUPSTROKES option specifies that the time taken to account for the points in the up strokes should be ignored. If this flag is 0, and if the value in uSpeedPct is small enough, there will be a delay between pen-down strokes, reflecting the user’s inter-stroke delay during creation of the pen data.

lParam

Application value to pass to the callback function set up by the lpfnAnimateCB argument of DrawPenDataEx.

dwReserved

Must be 0.

Comments

Before using ANIMATEINFO, an application must initialize cbSize with sizeof( ANIMATEINFO ).

See Also

AnimateProc, DrawPenDataEx


BOXEDITINFO

2.0

Size information for boxed edit control.

typedef struct {

int cxBox;

int cyBox;

int cxBase;

int cyBase;

int cyMid;

BOXLAYOUT boxlayout;

UINT wFlags;

BYTE szFaceName[BEI_FACESIZE];

UINT wFontHeight;

UINT rgwReserved[8];

} BOXEDITINFO;

Members

cxBox

Width of a single box.

cyBox

Height of a single box.

cxBase

In-box x-margin to guideline.

cyBase

In-box y-offset from top to baseline.

cyMid

Reserved for future use; must be set to 0.

boxlayout

BOXLAYOUT structure.

wFlags

Flags specifying boxed edit options. Currently, the only defined option is BEIF_BOXCROSS.

szFaceName[BEI_FACESIZE]

Font face name, where BEI_FACESIZE is defined as 32.

wFontHeight

Font height.

rgwReserved[8]

Reserved for future use; must be set to 0.

See Also

BOXLAYOUT


BOXLAYOUT

1.0    2.0

Specifies some of the characteristics of a bedit control. The GUIDE and BOXEDITINFO structures determine the rest. The HE_GETBOXLAYOUT and HE_SETBOXLAYOUT wParam values of the WM_PENCTL message retrieve and set the BOXLAYOUT structure for a bedit control.

For more details, see the WM_PENCTL message.

typedef struct {

int cyCusp;

int cyEndCusp;

UINT style;

DWORD dwReserved1;

DWORD dwReserved2;

DWORD dwReserved3;

} BOXLAYOUT;

Members

cyCusp

Height of the box in pixels when BXS_RECT is specified; otherwise, height of the cusp in pixels (in comb style).

cyEndCusp

Height of cusps, in pixels, at extreme ends.

style

Bitwise-OR combination of the following BXS_ flags:

Constant	Description
BXS_NONE	Default comb style.
BXS_RECT	Rectangular boxes (instead of comb style).
BXS_BOXCROSS	(Japanese version only.) Rectangular boxes with a small cross at the center of each cell. Note that any state set via this flag (or the absence of it) may be overridden by the user’s selection of the BOXCROSS setting in the Bedit Control Panel.
dwReserved1

Reserved; must be set to 0.

dwReserved2

Reserved; must be set to 0.

dwReserved3

Reserved; must be set to 0.

Comments

The following table lists the default values for the BOXLAYOUT structure.

Value	Description
cyCusp	Equivalent in pixels of BXD_CUSPHEIGHT dialog units.
cyEndCusp	Equivalent in pixels of BXD_ENDCUSPHEIGHT dialog units.
style	Comb style.
Figure 11.1 shows the general layout of a boxed edit control. Some of the terms in the figure are explained in the reference entry for the GUIDE structure. Figure 11.2 shows an individual cell from a boxed edit control.

See Also

BOXEDITINFO, WM_PENCTL, GUIDE, BXD_


BOXRESULTS

2.0

Contains box results for the GetBoxResultsHRC function.

typedef struct {

int indxBox;

HINKSET hinksetBox;

SYV rgSyv[1];

} BOXRESULTS;

Members

indxBox

Index of the box with respect to the GUIDE structure.

hinksetBox

An inkset representing the pen data that belongs to the box, if requested by the GetBoxResultsHRC function. This member can be NULL.

rgSyv[1]

Variable-length array of alternative guesses made by the recognizer. The guesses are arranged in descending order of confidence, so that the first alternative in the array is the most likely choice.

See Also

GetBoxResultsHRC, GUIDE


CALBSTRUCT

1.0    2.0

Pen calibration information.

typedef struct {

int wOffsetX;

int wOffsetY;

int wDistinctWidth;

int wDistinctHeight;

} CALBSTRUCT;

Members

wOffsetX

Value in tablet units to add to x-coordinates for proper calibration.

wOffsetY

Value in tablet units to add to y-coordinates for proper calibration.

wDistinctWidth

Specifies the number of distinct x-coordinates the tablet can detect.

wDistinctHeight

Specifies the number of distinct y-coordinates the tablet can detect. The wDistinctWidth and wDistinctHeight members have the same meanings and values as the identically-named members in the PENINFO structure.


CTLINITBEDIT

2.0

Initialization information for a boxed edit (bedit) control.

typedef struct {

DWORD cbSize;

HWND hwnd;

int id;

int wSizeCategory;

WORD wFlags;

DWORD dwReserved;

} CTLINITBEDIT;

Members

cbSize

Size of this structure in bytes.

hwnd

Handle of a boxed edit window.

id

Control identifier.

wSizeCategory

Size category, which can be one of the following BESC_ constants:

Constant	Description
BESC_DEFAULT	Use the default size parameters to create the  boxed edit control. This results in the same behavior as BESC_KANJIFIXED for applications that have registered themselves through the  use of the SetPenAppFlags function with the RPI_KANJIFIXEDBEDIT flag. For all other applications, it results in the same behavior as BESC_ROMANFIXED.
BESC_ROMANFIXED	Comb-style bedit control with dimensions indicated by BXD_ constants (in dialog units). Meant for use with Roman characters.
BESC_KANJIFIXED	(Japanese version only.) Box-style bedit control with dimensions indicated by BXDK_ constants (in dialog units). Meant for use with kanji characters. This value should be used by applications that cannot handle user-defined box sizes.
BESC_USERDEFINED	A bedit control that can handle the box size parameters defined by the user. For further details, see the description for PMSC_BEDITCHANGE in the reference section for the WM_PENMISC message.
wFlags

Flags that determine certain properties of the boxed edit control. This can be a combination of the following values:

Constant	Description
CIB_NOGDMSG	(Not supported in Japanese version.)  Do not display the garbage-detection message box when writing in the bedit control.
CIB_NOACTIONHANDLE	Do not create action handles.
CIB_NOFLASHCURSOR	Do not change the cursor if tap-and-hold action is detected.
CIB_NOWRITING	(Japanese version only.) Do not allow pen input into the control. Other methods of inputting text, such as keyboard input or pasting from the keyboard, are allowed.
dwReserved

Reserved, should be set to 0.

Comments

Before using CTLINITBEDIT, an application must initialize cbSize with sizeof( CTLINITBEDIT ).

See Also

WM_CTLINIT


CTLINITHEDIT

2.0

Initialization information for a handwriting edit (hedit) control.

typedef struct {

DWORD cbSize;

HWND hwnd;

int id;

DWORD dwFlags;

DWORD dwReserved;

} CTLINITHEDIT;

Members

cbSize

Size of this structure in bytes.

hwnd

Handle of boxed edit window.

id

Control identifier.

dwFlags

Flags that determine some properties of the hedit control. This can be a combination of the following values:

Constant	Description
CIH_NOGDMSG	(Not supported in Japanese version.) Do not put up the garbage-detection message box when writing in this hedit control.
CIH_NOACTIONHANDLE	Do not create action handles for this hedit control.
CIH_NOEDITTEXT	Do not show the edit text, insert text, or  writing tool dialogs when writing in this hedit control.
CIH_NOFLASHCURSOR	Do not change the cursor while doing tap-and-hold selection in this hedit control.
dwReserved

Reserved, should be set to 0.

Comments

Before using CTLINITHEDIT, an application must initialize cbSize with sizeof( CTLINITHEDIT ).

See Also

WM_CTLINIT


CTLINITIEDIT

2.0

Specifies the initial settings and options of an ink edit (iedit) control. A pointer to this structure is passed to the parent window of the control as the lParam parameter of the WM_CTLINIT message. This forms the last step of the control’s processing of the WM_CREATE message.

typedef struct {

DWORD cbSize;

HWND hwnd;

int id;

WORD ieb;

WORD iedo;

WORD iei;

WORD ien;

WORD ierec;

WORD ies;

WORD iesec;

HPENDATA hpndt;

WORD pdts;

HGDIOBJ hgdiobj;

HPEN hpenGrid;

POINT ptOrgGrid;

WORD wVGrid;

WORD wHGrid;

DWORD dwApp;

DWORD dwReserved;

} CTLINITIEDIT;

Members

cbSize

Size of this structure in bytes.

hwnd

Handle to an ink edit window.

id

Control identifier.

ieb

Background IEB_ bit values (see IE_SETBKGND).

iedo

Draw options IEDO_ bit values (see IE_SETDRAWOPTS).

iei

Ink input IEI_ bit values (see IE_SETINKINPUT).

ien

Notification IEN_ bit values (see IE_SETNOTIFY).

ierec

Recognition IEREC_ bit values (see IE_SETRECOG).

ies

Style IES_ bit values (see IE_GETSTYLE).

iesec

Security IESEC_ bit values (see IE_SETSECURITY).

hpndt

Initial pen data.

pdts

Initial map mode.

hgdiobj

Brush or bitmap, depending on background bits option in ieb.

hpenGrid

Pen to use in drawing grid.

ptOrgGrid

Point of origin for the grid lines.

wVGrid

Vertical grid line spacing.

wHGrid

Horizontal grid line spacing.

dwApp

Application data.

dwReserved

Reserved.

Comments

Before using CTLINITIEDIT, an application must initialize cbSize with sizeof( CTLINITIEDIT ).

See Also

IE_SETBKGND, IE_SETDRAWOPTS, IE_SETNOTIFY, IE_SETRECOG, IE_SETSECURITY, IE_GETSTYLE, IE_SETDRAWOPTS, WM_CTLINIT


CWX

2.0

Specifies optional parameters for the CorrectWritingEx function. (Japanese version only.)

typedef struct {

DWORD cbSize;

WORD wApplyFlags;

HWND hwndText;

HRC hrc;

char szCaption[CBCAPTIONCWX];

DWORD dwEditStyle;

DWORD dwSel;

DWORD dwFlags;

WORD ixkb;

WORD rgState[CKBCWX];

POINT ptUL;

SIZE sizeHW;

} CWX;

Members

cbSize

Size of this structure in bytes. This field must be initialized to sizeof(CWX).

wApplyFlags

Options to specify which members of this structure are to be used to override the most-recently-used values provided by default; not all fields qualify. If this value is 0, the most-recently-used settings will be shown; otherwise, this value can be a combination of the following values:

Constant	Description
CWXA_CONTEXT	Use the dwFlags member to specify context.
CWXA_KBD	Use the ixkb member to specify a keyboard.
CWXA_STATE	Apply the states provided in the rgState array.
CWXA_PTUL	Move the dialog box upper corner to the screen position specified by the ptUL member.
CWXA_SIZE	Use the window size specified by the sizeHW member while using the handwriting recognition tab.
CWXA_NOUPDATEMRU	Do not update the registry with the last state of the correction dialog. This causes any changes made to the position and state of the Data Input Window to be discarded. This has no effect on user changes to the text, however.
hwndText

Text window to which to send WM_GETTEXT and WM_SETTEXT messages. If this is NULL, the owner of the Correct Writing dialog box will be used.

hrc

Handle to a recognition context. If this is NULL, a WM_PENMISC message with the wParam parameter of PMSC_GETHRC will be sent to the owner window to get a recognition context. If that too is NULL, then a default context will be used. The system will destroy its copy of hrc before the call returns.

szCaption[CBCAPTIONCWX]

A null-terminated array of characters to be used for a dialog caption. If this string has 0 length, then the default caption “Edit Text” will be used. The maximum length of caption allowed is specified by the CBCAPTIONCWX constant.

dwEditStyle

Style to use for the Data Input Window's edit control. By default this is ES_LEFT. If this style includes ES_MULTILINE, entry of Return and Tab characters is allowed; otherwise, they are not allowed. In any case, the style of the actual edit control will look like a multiline edit control.

dwSel

Specifies the selection. The low-order word (LOWORD) is the start position and the high-order word (HIWORD) is the end position. The default values are 0 for start and 0xFFFF for end, to select all text.

dwFlags

Specifies context flags, provided that the CWXA_CONTEXT bit is set in the wApplyFlags member; otherwise, the most-recently-used context flags are used and this field is ignored. On return, this field contains the updated flags. The flags may be CWX_DEFAULT (0), or a bitwise-OR combination of the following constant values:

Constant	Description
CWX_TOPMOST	Specifies that the dialog window is to be a topmost window. The window is not topmost by default.
CWX_NOTOOLTIPS	Disables showing tool tips for graphical buttons. They are shown by default.
CWX_JPERIOD	Specifies that the Japanese period is to be used on some keys on the Data Input Window keypads. The English period is used by default.
CWX_JCOMMA	Specifies that the Japanese comma is to be used on some keys on the Data Input Window keypads. The English comma is used by default.
CWX_DEFAULT	Zero; none of the above flags are set.
ixkb

Specifies which Data Input Window keyboard, or handwriting input, is to be used first, provided that the CWXA_KBD bit is set in the wApplyFlags member; otherwise, the most-recently use keyboard is used and this field is ignored. On return, this field contains the updated keyboard identifier. This may be one of the following values:

Constant	Description
CWXK_HW	Handwriting, not keyboard, input. If this value is specified, most of the dialog will be available for handwriting input, and the dialog will be sizable.
CWXK_50	50-On keyboard.
CWXK_QWERTY	QWERTY keyboard, including Hiragana, Katakana, and Romaji-to-Kana conversion alternative states.
CWXK_ROMAJI	Condensed Romaji-to-Kana keyboard, similar to some pocket computers.
CWXK_NUM	Numeric and Telephone keyboard.
CWXK_KANJI	Kanji keyboard, which provides a method of specifying a Kanji character based on its strokes.
CWXK_CODE	Kanji Code Finder keyboard, which allows the lookup of a Kanji character based on its JIS, Shift-JIS, or Kuten code value.
CWXK_YOMI	Kanji character finder based on the sound, or “reading” (Yomi) of the character.
rgState[CKBCWX]

An array of keyboard states with which to initialize the CKBCWX number of keyboards, provided that the CWXA_STATE bit is set in the wApplyFlags member; otherwise, the most-recently-used states are used and this member is ignored. On return, this member contains the updated states. Each element of the array may be CWXKS_DEFAULT (0, which is equivalent to CWXKS_HAN + CWXKS_ROMA), or a bitwise-OR combination of the following constants:

Constant	Description
CWXKS_CAPS	Set CAPSLOCK state on QWERTY keyboard.
CWXKS_HAN	Set Hankaku (single-byte) state.
CWXKS_ZEN	Set Zenkaku (double-byte) state.
CWXKS_ROMA	Set Romaji characters state.
CWXKS_HIRA	Set Hiragana characters state.
CWXKS_KATA	Set Katakana characters state.
ptUL

Specifies the upper-left corner of the dialog in screen coordinates, provided that the CWXA_PTUL bit is set in the wApplyFlags member; otherwise, the most-recently-used position is used and this member is ignored. On return, this member contains the updated screen position of the upper-left corner.

sizeHW

Specifies the size of the dialog when it is in handwriting input mode, provided that the CWXA_SIZE bit is set in the wApplyFlags member; otherwise, the most-recently-used size is used and this field is ignored. On return, this field contains the updated size.

Comments

Note that even if some bits are not set in wApplyFlags, the corresponding structure members are still updated with the last-used values on return.

See Also

CorrectWritingEx


GUIDE

1.0    2.0

Specifies the characteristics of any guidelines used in the writing area.

typedef struct {

int xOrigin;

int yOrigin;

int cxBox;

int cyBox;

int cxBase;

int cyBase;

int cHorzBox;

int cVertBox;

int cyMid;

} GUIDE;

Members

xOrigin

Position of left edge of the first box in screen coordinates.

yOrigin

Position of top edge of the first box in screen coordinates.

cxBox

Width of each box in screen pixels.

cyBox

Height of each box in screen pixels.

cxBase

Margin to the guideline. This is one-half the distance in pixels between adjacent boxes.

cyBase

Vertical distance in pixels from the baseline to the top of the box.

cHorzBox

Number of columns of boxes.

cVertBox

Number of rows of boxes.

cyMid

Distance in pixels from the baseline to the midline, or 0 if midline is not present.

Comments

If the application has drawn guidelines on the screen on which the user is expected to write, the application should set the values in the GUIDE structure to inform the recognizer. The GUIDE structure is for the recognizer’s use only. Setting the GUIDE structure does not by itself draw any visual clues on the display. It is the responsibility of the application or the control to draw the visual clues. The appearance of a boxed edit control is determined by the BOXLAYOUT and GUIDE structures together.

The xOrigin and yOrigin members are screen coordinates of the top-left corner of the area to write in. The cyBox and cxBox members are the height and width of the individual boxes to write in. The cHorzBox and cVertBox members specify the number of columns and rows. cyBase specifies a baseline within the box. (Setting cyBase to 0 indicates no baseline.) The cxBase member gives a horizontal displacement of the edge of the guideline from the edge of the box where writing is expected to start.

If only horizontal lines are present, set cxBox to 0. In this case, only yOrigin, cyBox, cyBase, and cyMid are valid. A default GUIDE structure has all elements set to 0.

To establish a guide, initialize a GUIDE structure and set it into an HRC with the SetGuideHRC function. This also applies to a standard bedit, as demonstrated in “The bedit Control” in Chapter 3.

For boxed input, the GetBoxMappingHRCRESULT function returns an index to the box containing the requested input character. This is numbered in zero-based row-major order. In Figure 11.3 below, for example, the “h” character is in box 12.

For best recognition results, the pair-wise ratios of cxBox, cyBox, and cyBase should be similar to the default ratios.

See Also

SetGuideHRC, BOXLAYOUT, BXD_


INKINGINFO

2.0

Provides information about where and how the system should display ink.

typedef struct {

DWORD cbSize;

UINT wFlags;

PENTIP tip;

RECT rectClip;

RECT rectInkStop;

HRGN hrgnClip;

HRGN hrgnInkStop;

} INKINGINFO;

Members

cbSize

Size of this structure in bytes.

wFlags

A bitwise-OR combination of the following PII_ flags:

Constant	Description
PII_INKPENTIP	Use tip for pen characteristics.
PII_INKCLIPRECT	Clip ink using rectClip.
PII_INKSTOPRECT	Terminate inking on a pen-down event inside rectInkStop.
PII_INKCLIPRGN	Clip ink using hrgnClip. If hrgnClip is set,  any value in rectClip is disregarded.
PII_INKSTOPRGN	Terminate inking on a pen-down event inside hrgnInkStop.
PII_SAVEBACKGROUND	Save the background that is being inked on.  The saved background is restored when the current input session terminates.
PII_CLIPSTOP	Directs Windows to stop inking if the pen  goes down outside rectClip or hrgnClip, if either have been set.
tip

A PENTIP structure defining the pen type, size, and color.

rectClip

Clipping rectangle for the ink. Setting rectClip to {−32767, −32767, 32767, 32767} is equivalent to having no clipping region.

rectInkStop

Rectangle in which a pen-down event stops inking. Setting rectInkStop to empty is equivalent to not having an ink stop region.

hrgnClip

Clipping region for the ink. Setting hrgnClip to NULL is equivalent to not having a clipping region.

hrgnInkStop

Region in which a pen-down event stops inking. Setting hrgnInkStop to NULL is equivalent to not having an ink stop region.

Comments

All areas are in screen coordinates.

The wFlags member specifies which of the other members contain valid information. For example, if PII_INKCLIPRECT is set in wFlags, the rectClip member specifies the clipping rectangle. Otherwise, a default value is used.

Before using INKINGINFO, an application must initialize cbSize with sizeof( INKINGINFO ).

See Also

PENTIP, StartInking, WM_PENEVENT


INPPARAMS

2.0

Describes a set of targets.

typedef struct {

DWORD cbSize;

DWORD dwFlags;

HPENDATA hpndt;

TARGET target;

} INPPARAMS;

Members

cbSize

Size of this structure in bytes.

dwFlags

Reserved for future use; must be 0.

hpndt

Handle to a pen data object.

target

A TARGET structure where input is directed.

Comments

Before using INPPARAMS, an application must initialize cbSize with sizeof( INPPARAMS ).

See Also

TARGET


INTERVAL

2.0

Interval structure for inksets.

typedef struct {

ABSTIME atBegin;

ABSTIME atEnd;

} INTERVAL;

Members

atBegin

Beginning of 1-millisecond granularity interval.

atEnd

Time at 1 millisecond past end of interval.

See Also

ABSTIME


OEMPENINFO

1.0    2.0

Structure containing original equipment manufacturer (OEM) hardware information for the pen or tablet.

typedef struct {

UINT wPdt;

UINT wValueMax;

UINT wDistinct;

} OEMPENINFO;

Members

wPdt

A combination of PDT_ values.

wValueMax

The largest value returned by the device.

wDistinct

The number of distinct readings possible.

Comments

The OEMPENINFO structure contains a description of the additional OEM information that the hardware can generate. It is a component of the PENINFO structure.

Besides capturing the x- and y- coordinates of the pen movement, a pen device has the option of providing a number of other types of input data, such as pen pressure, height of the pen tip above the tablet surface, angle of the pen, and so on. A pen driver can capture up to MAXOEMDATAWORDS types of data, where MAXOEMDATAWORDS is defined as six. An application can access the OEM data through the GetPenInput function. A recognizer can receive OEM data from an application through the AddPenInputHRC function. It is the up to the application whether to send this data or not.

Each pen event generates a packet of information from the pen driver that contains the current pen position and, optionally, other types of OEM information. The cbOemData member of the PENINFO structure specifies the width of the optional OEM data in bytes. Each type of data is one word wide. The type of data in the nth word of the OEM data packet is given by the nth element of the rgoempeninfo member (an array of OEMPENINFO structures) in the PENINFO structure.

For the wPdt member, PDT_NULL indicates no data. Values greater than PDT_OEMSPECIFIC are reserved for private use by drivers for data types not currently defined as standard. The wValueMax member contains the largest variable size the device can return for that data type. The wDistinct member is the number of distinct readings the device can take between 0 and wValueMax.

For a list of values for the wPdt member, see the entry for PDT_ values in Chapter 13, “Pen Application Programming Interface Constants.”

Example

As an example of how to use OEMPENINFO, consider a device that can sense both the height above the tablet surface and the Z-angle of the pen. Assume the device can sense 256 levels of height in a range from 0 to 10 centimeters and has a resolution of 1 degree on the angle of the pen. The two additional words of OEM information occupy 4 bytes, so the cbOemData and rgoempeninfo members of PENINFO look like this:

peninfo.cbOemData = 4

peninfo.rgoempeninfo[MAXOEMDATAWORDS] = {

{PDT_HEIGHT, 1000, 256},

{PDT_ANGLEZ, 1800, 180},

{PDT NULL, 0, 0},

{PDT_NULL, 0, 0},

{PDT_NULL, 0, 0},

{PDT_NULL, 0, 0} };

This optional information is saved by the pen driver in the same manner as the x- and y- coordinate data. There must be a one-to-one correspondence between the OEM event data and the coordinate data.

Figure 11.5 shows the pen in a position where both the Xy-angle and Z-angle are approximately 45 degrees.

See Also

PENINFO


OEM_PENPACKET

2.0

A pen packet used by Pen API, version 2.0, consisting of the information received from the pen device for a single sample. For a definition of pen packet, see SetPenHook.

typedef struct {

UINT wTabletX;

UINT wTabletY;

UINT wPDK;

UINT rgwOemData[MAXOEMDATAWORDS];

DWORD dwTime;

} PENPACKET;

Members

wTabletX

The x-dimension in raw tablet coordinates.

wTabletY

The y-dimension in raw tablet coordinates.

wPDK

Pen hardware state bits, expressed as a combination of PDK_ values.

rgwOemData[MAXOEMDATAWORDS]

Array of OEM-specific data. MAXOEMDATAWORDS is defined as 6.

dwTime

Time stamp indicating when the pen packet originated.

Comments

A pen packet is the basic unit of communication between the pen driver and Windows. A pen packet contains all of the information about a single logical event: x-y coordinate position, button states, and any optional information such as pressure or barrel rotation. Several physical events—that is, interrupts—may be needed to construct a single logical event.

The rgwOemData member contains the data relating to the OEM hardware, such as pen pressure, angle, and so forth.

See Also

SetPenHookCallback, OEMPENINFO, PENPACKET


PCMINFO

2.0

Pen collection mode information. All regions and rectangles are in screen coordinates. Time-out values are in milliseconds.

typedef struct {

DWORD cbSize;

DWORD dwPcm;

RECT rectBound;

RECT rectExclude;

HRGN hrgnBound;

HRGN hrgnExclude;

DWORD dwTimeout;

} PCMINFO;

Members

cbSize

Size of this structure in bytes.

dwPcm

A combination of PCM_ flags specifying options for pen collection.

rectBound

Bounding rectangle for pen collection.

rectExclude

Exclusion rectangle for pen collection.

hrgnBound

Bounding region for pen collection.

hrgnExclude

Exclusion region for pen collection.

dwTimeout

Time-out before terminating pen collection.

Comments

Before using PCMINFO, an application must initialize cbSize with sizeof( PCMINFO ).

See Also

StartPenInput, WM_PENEVENT, PCM_


PDEVENT

2.0

Provides details of the pointing-device event that is the subject of an IN_PDEVENT notification. A pointing-device event can be a pen tap, mouse double-click, and so on. This structure is returned by the IE_GETPDEVENT message.

typedef struct {

DWORD cbSize;

HWND hwnd;

UINT wm;

WPARAM wParam;

LPARAM lParam;

POINT pt;

BOOL fPen;

LONG lExInfo;

DWORD dwReserved;

} PDEVENT;

Members

cbSize

Size of this structure in bytes.

hwnd

Handle to ink edit window.

wm

Window WM_ message.

wParam

wParam of event.

lParam

lParam of event.

pt

Event point in ink edit client coordinates.

fPen

TRUE if pen event, FALSE if mouse event.

lExInfo

Windows GetMessageExtraInfo function return value.

dwReserved

Reserved.

Comments

Before using PDEVENT, an application must initialize cbSize with sizeof( PDEVENT ).

For descriptions of the WM_ messages that pertain to pen-based computing, refer to Chapter 12, “Pen Application Programming Interface Messages.”

See Also

IE_GETPDEVENT, IN_PDEVENT


PENDATAHEADER

1.0    2.0

Main header of an HPENDATA memory block.

typedef struct {

UINT wVersion;

UINT cbSizeUsed;

UINT cStrokes;

UINT cPnt;

UINT cPntStrokeMax;

RECT rectBound;

UINT wPndts;

int nInkWidth;

DWORD rgbInk;

} PENDATAHEADER;

Members

wVersion

Pen data format version. Same as the version number for the Pen API, which is currently 0x0002. Calling GetPenDataAttributes with the GPA_VERSION argument retrieves the value of wVersion.

cbSizeUsed

Size (in bytes) of pen data memory block.

cStrokes

Number of strokes in the block. (Each pen-down and pen-up sequence counts as a single stroke.)

cPnt

Count of all points in the block. Calling GetPenDataAttributes with the GPA_POINTS argument retrieves the value of cPnt.

cPntStrokeMax

Length (in points) of longest stroke. Calling GetPenDataAttributes with the GPA_MAXLEN argument retrieves the value of cPntStrokeMax.

rectBound

Bounding rectangle of all pen-down points.

wPndts

Data scaling metric value, expressed as a bitwise-OR combination of PDTS_ values.

nInkWidth

Ink width, in pixels.

rgbInk

Ink color.

Comments

The PENDATAHEADER structure describes the contents of an HPENDATA memory block. Use the GetPenDataInfo or GetPenDataAttributes function to retrieve information from a PENDATAHEADER structure.

For a description of the HPENDATA memory block, see “The HPENDATA Object” in Chapter 4, “The Inking Process.”

For a list of data scaling values, refer to the entry for PDTS_ values in Chapter 13, “Pen Application Programming Interface Constants.”

See Also

GetPenDataInfo, GetPenDataAttributes, PDTS_


PENINFO

1.0    2.0

Contains dimensions, sampling rate, and other information about the pen or tablet hardware.

typedef struct {

UINT cxRawWidth;

UINT cyRawHeight;

UINT wDistinctWidth;

UINT wDistinctHeight;

int nSamplingRate;

int nSamplingDist;

LONG lPdc;

int cPens;

int cbOemData;

OEMPENINFO rgoempeninfo[MAXOEMDATAWORDS];

UINT rgwReserved[7];

UINT fuOEM;

} PENINFO;

Members

cxRawWidth

Width of tablet in thousandths of an inch. Also specifies the maximum tablet x-coordinate.

cyRawHeight

Height of tablet in thousandths of an inch. Also specifies the maximum tablet y-coordinate.

wDistinctWidth

Number of distinct x-coordinates the hardware can detect.

wDistinctHeight

Number of distinct y-coordinates the hardware can detect. Together, the wDistinctWidth and wDistinctHeight members express the x-y resolution of the tablet. For example, if a tablet is 8 inches wide and has a resolution of 1/500 of an inch, cxRawWidth is 8000 and wDistinctWidth is 4000 because the tablet hardware can return 4000 distinct x-order values ranging from 0 to 8000.

nSamplingRate

Specifies the number of samples per second the tablet can return. This value may be less than the number of hardware interrupts per second the tablet generates because several interrupts may be required to create one pen packet sample. See the “Comments” section below for information on adjusting the sampling rate.

nSamplingDist

Specifies the distance in distinct tablet units a pen must travel before a new pen event is generated. See the “Comments” section below for information on adjusting the sampling distance.

lPdc

Pen-device capabilities, expressed as a bitwise-OR combination of the PDC_ flags.

cPens

Number of pens the tablet can simultaneously support.

cbOemData

Specifies the width, in bytes, of the additional OEM data passed in each pen packet. For example, if a tablet can detect pressure and Z-angle information, this information occupies two additional words of OEM data, so cbOemData is 4.

rgoempeninfo[MAXOEMDATAWORDS]

An array of OEMPENINFO structures. Each structure describes one word of additional OEM data contained in each pen packet. (MAXOEMDATAWORDS is defined as 6.)

rgwReserved[7]

Reserved for internal use.

fuOEM

Flags representing which OEM data to report in rgoempeninfo; used by applications to determine the OEM data used in an HPENDATA object. This member is set and used internally by the pen services and should never be modified by an application. This member is a bitwise-OR combination of the following values:

Constant	Description
PHW_ALL	Report all available OEM data.
PHW_PRESSURE	Report pressure if available.
PHW_HEIGHT	Report height if available.
PHW_ANGLEXY	Report Xy-angle if available.
PHW_ANGLEZ	Report Z-angle if available.
PHW_BARRELROTATION	Report barrel rotation if available.
PHW_OEMSPECIFIC	Report OEM-specific value if available.
PHW_PDK	Report per-point PDK_ values.
Comments

The DRV_GetPenInfo pen driver message fills a PENINFO structure with the current device parameters. DRV_GetPenInfo returns FALSE if a tablet is not present. If this occurs, the PENINFO structure that the message’s lParam1 points to is not valid. Note that an application should retrieve tablet information with the GetPenDataInfo and GetPenDataAttributes functions, rather than accessing the pen driver directly.

An application can also adjust the tablet sampling rate and sampling distance by sending the DRV_SetSamplingRate or DRV_SetSamplingDist messages to the device driver. For more information, see Appendix E, “Accessing the Pen Device Driver.”

For a list of state bits for the pen driver, refer to the entry for PDK_ values in Chapter 13, “Pen Application Programming Interface Constants.”

See Also

CreatePenDataEx, GetPenDataInfo, TrimPenData, UpdatePenInfo, OEMPENINFO


PENPACKET

1.0    2.0

A pen packet used by Pen Windows, version 1.0, consisting of the information received from the pen device for a single sample. For a definition of pen packet, see SetPenHook.

typedef struct {

UINT wTabletX;

UINT wTabletY;

UINT wPDK;

UINT rgwOemData[MAXOEMDATAWORDS];

} PENPACKET;

Members

wTabletX

The x-dimension in raw tablet coordinates.

wTabletY

The y-dimension in raw tablet coordinates.

wPDK

Pen hardware state bits, expressed as a combination of PDK_ values.

rgwOemData[MAXOEMDATAWORDS]

Array of OEM-specific data. MAXOEMDATAWORDS is defined as 6.

Comments

A pen packet is the basic unit of communication between the pen driver and Windows. A pen packet contains all of the information about a single logical event: x-y coordinate position, button states, and any optional information such as pressure or barrel rotation. Several physical events—that is, interrupts—may be needed to construct a single logical event.

The rgwOemData member contains the real-time values associated with the pen data types described in the entry for the OEMPENINFO structure.

See Also

SetPenHookCallback, OEMPENINFO, OEM_PENPACKET


PENTIP

2.0

Pen tip characteristics.

typedef struct {

DWORD cbSize;

BYTE btype;

BYTE bwidth;

BYTE bheight;

BYTE bOpacity;

COLORREF rgb;

DWORD dwFlags;

DWORD dwReserved;

} PENTIP;

Members

cbSize

Size of this structure in bytes.

btype

Pen nib type. Types in the range 0 through 63 are reserved for predefined standard types. An application can use values in the range 64 through 255.

bwidth

Pen nib width, in display device units (pixels).

bheight

Pen nib height, in display device units (pixels). In the current version of the Pen API, this member is ignored.

bOpacity

Opacity of the ink, which corresponds to the JOT standard. bOpacity must have one of the following values:

Constant	Description
PENTIP_OPAQUE	New ink overwrites any existing ink.
PENTIP_HILITE	New ink is visible but partly transparent, possibly interacting with underlying ink.
PENTIP_TRANSPARENT	Ink is completely transparent. There is no interaction with any underlying ink.
rgb

RGB pen color.

dwFlags

Reserved.

dwReserved

Reserved; must be set to 0.

Comments

Before using PENTIP, an application must initialize cbSize with sizeof( PENTIP ).

See Also

GetStrokeAttributes, SetStrokeAttributes, GetStrokeTableAttributes, SetStrokeTableAttributes, GetPenMiscInfo, SetPenMiscInfo, INKINGINFO


RC

1.0    2.0

Defines a recognition context (RC) for applications compatible with version 1.0 of the Pen API. Applications that do not call the superseded functions Recognize or RecognizeData do not use the RC structure. These applications instead use HRC objects, which render RC obsolete.

The RC structure is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions.

typedef struct {

HREC hrec;

HWND hwnd;

UINT wEventRef;

UINT wRcPreferences;

LONG lRcOptions;

RCYIELDPROC lpfnYield;

BYTE lpUser[cbRcUserMax];

UINT wCountry;

UINT wIntlPreferences;

char lpLanguage[cbRcLanguageMax];

LPDF rglpdf[MAXDICTIONARIES];

UINT wTryDictionary;

CL clErrorLevel;

ALC alc;

ALC alcPriority;

BYTE rgbfAlc[cbRcrgbfAlcMax];

UINT wResultMode;

UINT wTimeOut;

LONG lPcm;

RECT rectBound;

RECT rectExclude;

GUIDE guide;

UINT wRcOrient;

UINT wRcDirect;

int nInkWidth;

COLORREF rgbInk;

DWORD dwAppParam;

DWORD dwDictParam;

DWORD dwRecognizer;

UINT rgwReserved[cwRcReservedMax];

} RC;

Members

hrec

Handle of recognizer to use.

hwnd

Window to which results are sent.

wEventRef

Index into ink buffer.

wRcPreferences

Flags specifying preferences, described in “Comments” section.

lRcOptions

Recognition options, described in “Comments” section.

lpfnYield

Procedure called during processing of the Yield Windows function.

lpUser[cbRcUserMax]

Current writer.

wCountry

Country code.

wIntlPreferences

Flags for international preferences.

lpLanguage[cbRcLanguageMax]

Language strings.

rglpdf[MAXDICTIONARIES]

List of dictionary functions.

wTryDictionary

Maximum enumerations to search.

clErrorLevel

Level where recognizer should reject input.

alc

Enabled ALC_ alphabet codes.

alcPriority

Sets priority of the ALC_ codes.

rgbfAlc[cbRcrgbfAlcMax]

Bit field for enabled characters.

wResultMode

Result return mode specifying when to send (either as soon as possible or when complete). The RRM_ codes are described in “Comments” section.

wTimeOut

Recognition time-out in milliseconds.

lPcm

Bitwise-OR combination of PCM_ flags for ending the recognition session.

rectBound

Bounding rectangle for inking. By default, the rectangle is in screen coordinates.

rectExclude

A pen-down event inside this rectangle terminates recognition.

guide

GUIDE structure that defines guidelines for recognizer.

wRcOrient

Orientation of writing with regard to the tablet.

wRcDirect

Direction of writing.

nInkWidth

Ink width of 1−15 pixels. A value of 0 prevents display of the ink.

rgbInk

Ink color.

dwAppParam

For application use.

dwDictParam

For application use; to be passed on to dictionaries.

dwRecognizer

For application use; to be passed on to recognizer.

rgwReserved[cwRcReservedMax]

Reserved.

Comments

The following paragraphs discuss the RC members, listed in the order in which they appear in the preceding structure.

hrec

The hrec member is the handle of the recognizer to use. This value should be set to the value returned by a previous call to InstallRecognizer, or to RC_WDEFAULT for the default recognizer.

If hrec is NULL, no recognizer is used. WM_RCRESULT messages are generated as with a real recognizer, but the wResultsType member of RCRESULT is set to RCRT_NORECOG, and the hSyv and lpsyv members are set to NULL. (For a list of other values in wResultsType, see the entry for RCRT_ values in Chapter 13, “Pen Application Programming Interface Constants.”)

hwnd

The hwnd member specifies the window to send recognition results to. This member cannot be NULL. Also, the mouse capture is set to this window to clear the queue of pending mouse messages that were meant for recognition.

wEventRef

The value for wEventRef indicates which tablet data to begin recognition with. The wEventRef member is returned from the GetMessageExtraInfo function.

InitRC sets this member to RC_WDEFAULT. If Recognize is called during the processing of the WM_LBUTTONDOWN message that initiates the input session, the application need take no other action.

Before an application starts recognition on some other Windows event, it should use GetMessageExtraInfo to save the event reference of the appropriate mouse message and place this value in wEventRef before calling Recognize.

This member is not used on calls to RecognizeData.

wRcPreferences

The wRcPreferences member specifies the user preferences as a combination of RCP_ constants.

lRcOptions

The lRcOptions member specifies various options for recognition. It is a bitwise-OR combination of RCO_ constants.

lpfnYield

The lpfnYield member points to a callback function used by the recognizer before it yields. The application sets this to NULL for no yield processing. Recognition can often take more than a few seconds; therefore, a recognizer should periodically call the yield function to yield control to other Windows tasks. The default yield function is:

BOOL FAR PASCAL StandardYieldFunction()

{

Yield( );

return 1;

}

If Recognize or RecognizeData is called with lpfnYield set to RC_LDEFAULT, then the default yield function is called. If the lpfnYield member is not NULL, the recognizer calls lpfnYield every time before it yields.

lpUser

#define	cbRcUserMax	32

BYTE	lpUser[cbRcUserMax];

The lpUser member specifies the name of the current writer. The current writer is used to specify any custom prototype sets that might be available to the recognizer. If the lpUser member is NULL, it means that the recognizer should use the standard prototype set—that is, the prototype set as it existed before it was modified (through training, for example).

wCountry

The wCountry member contains the country code. The values for country code are the same as the values used by the International item of the Control Panel for the iCountry member in the [intl] section of the WIN.INI file.

wIntlPreferences

The wIntlPreferences member contains a combination of various RCIP_ flags. Currently, this member can be only 0 or RCIP_ALLANSICHAR. If 0, only characters from the current language or languages are enabled. If wIntlPreferences is RCIP_ALLANSICHAR, the entire ANSI character set is enabled.

lpLanguage

#define	cbRcLanguageMax	44

char	lpLanguage[cbRcLanguageMax]

The lpLanguage member is a list of language strings. Each string is null-terminated and the list ends with a null string.

The set of values for each language string is the same as the set used by the International item of the Control Panel for the sLanguage member in the [Intl] section of the WIN.INI file. These three-letter codes are documented in the Microsoft Windows Software Development Kit.

A recognizer should implement recognition of the ANSI character set and then use this information during recognition to limit a match to the appropriate subset. The lpLanguage member holds strictly optional information; a recognizer may choose to ignore it. By definition, the character set implied by a language string is the set of characters that can be generated from the country-specific keyboard without using the ALT+numeric keypad combinations. It is still possible to enter ANSI characters outside the given language through the use of the onscreen keyboard and ALT+numeric keypad combinations.

rglpdf

#define	MAXDICTIONARIES 16

LPDF	rglpdf[MAXDICTIONARIES]

The dictionary path member rglpdf specifies which dictionaries are called by the RC Manager to convert symbol graphs into strings.

If rglpdf[0] is NULL, the NULL dictionary path is used. The NULL dictionary path indicates that the first enumeration from the symbol graph is used as the best enumeration. The array of dictionary functions is null-terminated. During recognition, the dictionary functions are called in the order in which they appear. For more details, see the entry for the DictionarySearch function.

wTryDictionary

The wTryDictionary member specifies the maximum number of enumerations generated from the symbol graph during dictionary processing on the results of recognition. The minimum number allowed is 1 and the maximum is 4096. The default value is 100.

clErrorLevel

Recognition accuracy is defined as the percentage of times the recognizer accurately assigns a symbol to an input. There is no penalty or gain if the recognizer does not attempt a match and returns “unknown.” The value can range from 0 to 100.

There are situations in which a higher accuracy rating is preferable despite an increased number of unknown results. For example, in a forms application, the Social Security field must be correctly recognized. If the recognizer is unsure, it can get the application to prompt the user again for the input (or a portion of it). At other times, it is preferable that the recognizer make a guess, no matter how wild, in order to limit the number of unknown results. For example, while taking notes in a meeting, the user may not care whether all of the results are transcribed perfectly.

The clErrorLevel member allows the application to signal its preference to the recognizer. Recognizers should return the SYV_UNKNOWN symbol for any symbol having a confidence level below clErrorLevel.

alc

The alc member is used to define the enabled alphabet for any RC structure with ALC_ constants. Any of the ALC_ constants can be combined together with a bitwise-OR operator to form the desired set of characters.

The actual characters enabled depend on the language. For example, if the user has requested French language support, the letter “è” is included in the lowercase alphabet. In the same way, “£” replaces “$” if ALC_MONETARY is set in British systems. For a list of alphabet values, see the entry for ALC_ values in Chapter 13, “Pen Application Programming Interface Constants.”

Setting the RCIP_ALLANSICHAR flag in the wIntlPreferences member of the RC structure enables all characters of the appropriate set regardless of the language setting.

A recognizer that recognizes characters other than ANSI can ignore this member. If you want an application to pass character subset information to private non-ANSI recognizers, you can use the dwRecognizer member.

A recognizer should not return a symbol value outside the specified subset. However, a recognizer does not have to force a match to the subset; it can return SYV_UNKNOWN if a suitable match is not found.

alcPriority

The alcPriority member sets the priority of the ALC_ codes used to enable alphabets. It does this by telling the recognizer in which order to list options in the symbol graph.

The alcPriority member uses the same ALC_ codes used in the alc member. The bits set in alcPriority should be a subset of those set in alc. Bits set in alcPriority that are not also set in the alc member have no effect.

A recognizer can recognize a glyph that belongs to more than one enabled ALC_ subset. For example, a vertical stroke can be the letter “l” in the ALC_LCALPHA subset or the number “1” in the ALC_NUMERIC subset. The alcPriority member specifies that the recognizer should first return those interpretations that are in the subsets indicated in alcPriority. If no interpretations are in any of the alcPriority sets, or no priority members are set, the recognizer returns all possibilities within the enabled sets.

For example, suppose the user writes a symbol that looks like either a “q” or a “9.” The generated symbol graph contains {q | 9 }. The alcPriority member determines the exact look of the symbol graph. If alcPriority has the ALC_ALPHA bit set, the recognizer should return { q | 9 } in the symbol graph. If alcPriority has the ALC_NUMERIC bit set, the recognizer should return { 9 | q } in the symbol graph.

Note that alcPriority does not affect the dictionary processing directly.

If ALC_USEBITMAP is set, the rgbfAlc member indicates which characters have priority.

rgbfAlc

#define	cbRcrgbfAlcMax	32

BYTE	rgbfAlc[cbRcrgbfAlcMax];

The rgbfAlc member is the bit field used for enabled characters. For more details, see the description of ALC_ constants. If ALC_USEBITMAP is set, the 256-bit bit field in rgbfAlc is used to indicate which characters from the ANSI character set are currently enabled. Character 0 is the low bit of the low-order byte in the array. Characters thus indicated are connected by OR operators to any characters enabled using the other ALC_ codes. A “1” set in a bit array indicates that the character is enabled.

As an example, to enable the “$” character, set the fifth bit of byte four like this:

rgbfAlc[4] |= 0x10

A recognizer that recognizes characters other than ANSI can ignore this member. If an application wants to pass character subset information to private non-ANSI recognizers, it can use the dwRecognizer member of the RC structure.

A set of macros, defined in PENWIN.H, simplifies user setting and testing the rgbfAlc bits for an RC structure. The ANSI macros listed in the following table set (bit=1), clear (bit=0), or test (TRUE if bit==1, else FALSE) the appropriate bits in lprc->rgbfAlc corresponding to the index i, which is the ANSI value to use. The lprc is a pointer to the RC structure containing the rgbfAlc[] array.

Macro	Description
SetAlcBitAnsi( lprc, i )	Sets the bit specified by i in rgbfAlc of lprc to 1.
ResetAlcBitAnsi( lprc, i )	Resets the bit specified by i in rgbfAlc of lprc to 0.
IsAlcBitAnsi( lprc, i )	Returns TRUE if the bit specified by i in rgbfAlc of lprc is set.
Only the IsAlcBitAnsi macro returns a value (BOOL). The return values of the other macros are undefined.

Setting bits in rgbfAlc[] also requires combining ALC_USEBITMAP by an OR operator with alc for the bits to have meaning. The bits are used in addition to other alc settings. For example, adding ALC_NUMERIC does not also set the bits in rgbfAlc that correspond to 0 through 9. Thus, to recognize octal numbers (the set 0 to 7), use the following code:

RC rc;

int i;

rc.alc = ALC_USEBITMAP;                // Note no ALC_NUMERIC

for (i = (int)'0'; i <= (int)'7'; i++)

SetAlcBitAnsi( &rc, i );

wResultMode

The wResultMode member specifies the timing and granularity of the results messages to be sent back to the specified window. The following times are defined.

Constant	Description
RRM_WORD	The granularity is set at a word boundary. As soon as the recognizer sees a word break, it can send all symbols up to the point of the word break.
RRM_NEWLINE	The granularity is set at a new line. As soon as the recognizer sees a line break, it sends the result to that point.
RRM_COMPLETE	When recognition is completed by one of the methods (for example, time-out or barrel button), the results message is sent just before Recognize returns.
RRM_STROKE	The granularity is set at the stroke level. A result message is sent at each stroke. This is used in the NULL recognizer.
RRM_SYMBOL	The granularity is set at the symbol level. A result message is sent at each symbol. Default dictionary processing is disabled when this value is used.
A recognizer is free to send the messages any time after the requested time (defined in the preceding order), but it cannot send any messages sooner. Because of recognizer constraints, a recognizer may combine intermediate results messages. For example, if an application requests RRM_WORD, the recognizer may choose to return results on a line-by-line basis instead.

Results sent at a word boundary do not have to be sent strictly one word at a time. The requirements are as follows:

•	The raw data returned must be contiguous, and it must begin with a pen-down and end with a pen-up.

•	The returned “word” may contain spaces. For example, “fat{space | NULL}cat” would be resolved into two words, “fat cat.” This is also necessary if the raw data for successive words overlaps.

•	The recognizer should not send a word until it knows what follows the word. If the word is followed by a word on the same line, the word should be space-terminated. If the word is followed by text on a new line, the recognizer should append a soft newline symbol. The key point is that the recognizer must make it possible for the application to detect word and line spacing so it can display the recognized text appropriately.

•	Once a word has been sent, the recognizer cannot change the results because of the late arrival of more strokes.

The rules for returning results with RRM_NEWLINE are similar:

•	The new line should be included with the symbol graph in the result.

•	Once a word has been sent, the recognizer cannot change the results because of the late arrival of more strokes.

wTimeOut

The wTimeOut member specifies the time-out threshold. After the time-out threshold has passed, the recognizer stops the recognition process.

Time-out occurs if more than wTimeOut milliseconds elapse between the most recent pen-up and the next pen-down. If time-out occurs, the recognition context is closed. Closing a recognition context means no more data is accepted; the existing data is processed and the results are sent to the application. This value is ignored if lPcm does not enable time-out.

In general, applications should use the value set by the user in the Control Panel. This value can be set by setting this member to RC_WDEFAULT.

The maximum value allowed is 65,534 milliseconds. If wTimeOut is set to 0xFFFF (65,535), the system-level value is used.

lPcmrectBound
rectExclude

These three members of the RC structure set the conditions for ending recognition. The lPcm member sets the flags for ending recognition, expressed as a bitwise-OR combination of PCM_ values.

The two RECT members specify inclusive and exclusive rectangles for inking. The rectangle values are in screen coordinates or, if RCO_TABLETCOORD is set, in tablet coordinates. RCO_TABLETCOORD cannot be used with ProcessWriting.

When RCRESULT is returned, the rectBound and rectExclude values are converted from screen to tablet coordinates and the RCO_TABLETCOORD flag is set.

Only pen events within rectBound are collected as part of the recognition context. If PCM_RECTBOUND is set in lPcm, the first pen-down event outside the rectangle closes the context. Dragging the pen outside the rectangle after starting inside does not close the context; the data is still collected outside the rectangle.

If PCM_RECTEXCLUDE is set in lPcm, any pen-down event within rectExclude closes the context. The event that ends pen collection mode—that is, an event outside the bounding rectangle or inside the exclusion—is entered into Windows as a mouse event. For hit-testing the rectangles, the top and left borders are included, but not the right or bottom borders.

The bounding rectangle set by InitRC is valid only until the window is resized or moved. If the window is moved or resized, the application should specify again the rectBound member in the RC structure.

guide

The guide member is a structure of the GUIDE type. It contains information that specifies the placement of guidelines in the writing area for the recognizer’s use.

wRcOrient

The wRcOrient member specifies the orientation of the tablet, expressed as RCOR_ values. For a list of orientation values, see the entry for RCOR_ values in Chapter 13, “Pen Application Programming Interface Constants.”

wRcDirect

The wRcDirect member informs the recognizer of the direction of writing, expressed as RCOR_ values. There are both primary and secondary directions. For example, English is written from left to right (primary) and then down the page (secondary). Chinese is often written from the top down (primary) and then right to left across the page (secondary). For a list of direction values, see the entry for RCD_ values in Chapter 13, “Pen Application Programming Interface Constants.”

The high byte of the direction indicates primary direction; the low byte, secondary direction. A recognizer can choose to ignore this word and support only the natural direction of the given language. The default value is determined by the recognizer.

Not all recognizers can respond to this member.

nInkWidth
rgbInk

These two members specify the ink width and color to be used during inking. The nInkWidth member is the thickness in pixels of the pen to use during inking. If this value is 0, no ink is drawn. The current maximum value allowed is 15. The default is the ink width set in the global RC.

The rgbInk member is the color to use for inking. If this is not a solid color, it is mapped to the closest solid color. The default is the ink color set in the global RC.

dwAppParam
dwRecognizer

These two members are analogous to the dwDictParam member described below. The dwAppParam value is provided for use by the application and passed to the application by way of the lprc member in the RCRESULT structure.

The dwRecognizer value is passed to the recognizer specified in rc.hrec. Applications can use this to pass information to a private recognizer for functionality not directly supported.

These values are set to 0 by InitRC and should remain 0 if they are not used by the application or recognizer.

dwDictParam

The dwDictParam parameter is set by an application and passed on to the dictionary by the RC Manager. It is intended to provide for dictionary functionality not directly supported. For example, a dictionary can request that the application pass in a pointer to a structure that contains a given sentence. You can use this information to extend the dictionary functionality—to highlight misspelled words, for example.

If it is not used by the application, dwDictParam should be left to the value (0) set by InitRC.

rgwReserved[cwRcReservedMax]

The rgwReserved member is reserved. Applications should not change the values set by InitRC for this member.

See Also

GUIDE, PCMINFO

ALC_, RCRT_, PCM_, RCD_, RCOR_


RCRESULT

1.0    2.0

Applications that do not call the superseded functions RecognizeData or Recognize do not use the RCRESULT structure. In conforming to version 2.0 of the Pen API, applications instead use HRCRESULT objects, which render RCRESULT obsolete.

The RCRESULT structure is provided only for compatibility with version 1.0 of the Pen API, and will not be supported in future versions.

typedef struct {

SYG syg;

UINT wResultsType;

int cSyv;

LPSYV lpsyv;

HANDLE hSyv;

int nBaseLine;

int nMidLine;

HPENDATA hpendata;

RECT rectBoundInk;

POINT pntEnd;

LPRC lprc;

} RCRESULT;

Members

syg

Symbol graph.

wResultsType

An RCRT_ value.

cSyv

Number of symbol values, not including the NULL terminator.

lpsyv

Null-terminated pointer to the recognizer’s best guess.

hSyv

Globally shared handle to the symbol value specified by the lpsyv member.

nBaseLine

Zero or baseline of input writing.

nMidLine

Zero or midline of input writing.

hpendata

Handle to pen data.

rectBoundInk

Bounding rectangle for ink.

pntEnd

Point that terminated recognition.

lprc

Recognition context used.

Comments

When an application calls Recognize, RecognizeData, or ProcessWriting, the WM_RCRESULT message is sent to the appropriate window procedure when the recognizer has a result to return. The wParam parameter of the message contains the reason recognition ended (one of the REC_ codes). It is REC_OK if more results will be sent; otherwise, it is the same value for the last message returned by Recognize or RecognizeData. The lParam parameter is a far pointer to an RCRESULT structure. All of the data in the RCRESULT structure is in tablet coordinates.

 The following sections elaborate on the RCRESULT members. All of the members are allocated with GMEM_SHARE so they can be passed between processes.

syg

This member contains the raw results returned by the recognizer. These include the various possible interpretations of the pen input, the mapping of the results to the raw data, and locations of any hot spots if the result is a gesture. The syg.lpsyc member is not valid unless RCP_MAPCHAR was set in the RC structure when Recognize or RecognizeData was called.

wResultsType

This member indicates the type of recognition results, expressed as a bitwise-OR combination of RCRT_ values. The RCRT_ values are not mutually exclusive. Note that the recognizer should never have to set RCRT_GESTURETOKEYS, RCRT_ALREADYPROCESSED,  or RCRT_GESTURETRANSLATED. For a list of values, see the entry for RCRT_ values in Chapter 13, “Pen Application Programming Interface Constants.”

lpsyv

This member contains the symbols that are recognized. An application should use these values to display the text or gestures recognized. The lpsyv member is the result of any dictionary search on the SYG structure or further postprocessing. It is NULL if the NULL recognizer is used.

hpendata

This member contains the raw data captured during inking.

rectBoundInk

This is the bounding rectangle of the ink drawn during recognition. It is in coordinates of the window that receives the results. If the user attempts to draw ink outside rc.rectbound, the ink will not be displayed. However, rectBoundInk is calculated as though the ink were drawn.

If data is collected outside the bounding rectangle, the rectBound member of PENDATAHEADER reflects this. (Note that rectBound applies only to pen-down points.) This means, however, that a portion of the rectBoundInk rectangle lies outside the rc.rectBound rectangle. The actual ink drawn lies in the intersection of rectBoundInk and the rc.rectBound rectangle. Before calculating the intersection, convert rectBoundInk from tablet to screen coordinates. The bounding rectangle includes the width of the ink drawn.

pntEnd

If recognition ended on a tap outside the bounding rectangle or inside the exclusive rectangle, pntEnd contains the coordinates of those points in display coordinates.

lprc

This is the RC used for recognition. Any default values (RC_WDEFAULT or RC_LDEFAULT) are replaced by the correct default value.

See Also

RC, SYG, RCRT_


RECTOFS

1.0    2.0

Rectangle offset for nonisometric inflation of a rectangular writing area.

typedef struct {

int dLeft;

int dTop;

int dRight;

int dBottom;

} RECTOFS;

Members

dLeft

Inflation margin leftward from left side.

dTop

Inflation margin upward from top.

dRight

Inflation margin rightward from right.

dBottom

Inflation margin downward from bottom.

Comments

Inflation margins are in screen (pixel) coordinates. To inflate a window rectangle, dLeft and dTop should be negative (moving in the negative x- and y-directions, respectively) and dRight and dBottom should be positive. To deflate the rectangle, reverse the signs of the margins.

In addition to having the basic characteristics of an edit control, an hedit or bedit control must make allowances for the input of handwriting. The client rectangle often needs to be adjusted to a larger size to allow for easier writing.

For example, the cut gesture typically extends above the selected text it is deleting. If the gesture is arbitrarily clipped off at the edge of the client window, recognition accuracy suffers. Likewise, restricting handwriting input to stay within the lines can also hinder recognition accuracy. To correct this, rectangle offsets are used in hedit and bedit controls to make the writing area slightly larger than the client window size of a normal edit control. The HE_SETINFLATE and HE_GETINFLATE wParam values of the WM_PENCTL message are used for this purpose. These messages use a RECTOFS structure as a parameter. The values in the RECTOFS structure are added to the corresponding client area to create the bounding rectangle for the ink.

The inflation does not need to be symmetrical in every direction.

See Also

WM_PENCTL, HE_SETINFLATE, HE_GETINFLATE


SKBINFO

1.0    2.0

Stores information about the current onscreen keyboard.

typedef struct {

HWND hwnd;

UINT nPad;

BOOL fVisible;

BOOL fMinimized;

RECT rect;

DWORD dwReserved;

} SKBINFO;

Members

hwnd

Handle of window for onscreen keyboard.

nPad

Current view of the keypad. Either SKB_FULL, SKB_BASIC, or SKB_NUMPAD for full, basic, or numeric keypad, respectively.

fVisible

TRUE if the keyboard is available and visible, FALSE otherwise.

fMinimized

TRUE if the keyboard is minimized, FALSE otherwise.

rect

Screen coordinates or the restored keyboard rectangle.

dwReserved

Must be 0.

See Also

ShowKeyboard


STRKFMT

2.0

Provides a method for retrieving or changing the attributes of specified strokes in an iedit control. This structure is used by the IE_GETFORMAT and IE_SETFORMAT messages.

typedef struct {

DWORD cbSize;

UINT iesf;

UINT iStrk;

PENTIP tip;

DWORD dwUser;

DWORD dwReserved;

} STRKFMT;

Members

cbSize

Size of this structure in bytes.

iesf

Stroke format flags. Note that the first three flags cannot be combined with each other by the bitwise OR operator:

Constant	Description
IESF_ALL	Assume all strokes in the control.
IESF_SELECTION	Assume all selected strokes.
IESF_STROKE	Assume the stroke specified in the iStrk member, described in “Comments” section.
IESF_PENTIP	Set both pen tip color and width.
IESF_TIPCOLOR	Set only pen tip color.
IESF_TIPWIDTH	Set only pen tip width.
iStrk

Index of a specific stroke.

tip

PENTIP structure, containing ink tip attributes.

dwUser

User data for stroke.

dwReserved

Reserved.

Comments

When sending either IE_GETFORMAT or IE_SETFORMAT, the application initializes the iesf member with bit flags, indicating:

•	The strokes in the iedit control to which the IE_ messages refer.

•	The attributes (color and/or width) of those strokes.

Setting the IESF_STROKE bit flag in iesf limits action to the single stroke identified in iStrk. Setting IESF_SELECTION references all selected strokes. Setting IESF_ALL references all strokes in the control. These flags are mutually exclusive and cannot be combined.

The application must also set the bit flags IESF_TIPCOLOR or IESF_TIPWIDTH in the iesf member of the structure. These bit flags identify the stroke attribute to which the IE_ messages refer. For convenience, the defined value IESF_PENTIP combines IESF_TIPCOLOR and IESF_TIPWIDTH to identify both color and width.

With these bit flags, an application can alter stroke color and width at the same time or alter only one attribute while leaving the other unchanged.

Sending an IE_GETFORMAT message to the control produces the following results:

•	If the requested strokes have the same color and width, the returned STRKFMT contains the common color and width in the rgb and bwidth members of its PENTIP structure. The return value from IE_GETFORMAT is 0.

•	If the requested strokes do not all share the same attribute, the returned STRKFMT contains the attribute of the last stroke in the group. The return value from IE_GETFORMAT contains the bit flags IESF_TIPCOLOR and/or IESF_TIPWIDTH to indicate the attribute in which the strokes differ.

Before using STRKFMT, an application must initialize cbSize with sizeof( STRKFMT ).

See Also

IE_GETFORMAT, IE_SETFORMAT, PENTIP


STROKEINFO

1.0    2.0

Contains information about a sequence of pen data.

typedef struct {

UINT cPnt;

UINT cbPnts;

UINT wPdk;

DWORD dwTick;

} STROKEINFO;

Members

cPnt

Count of points in the stroke.

cbPnts

Used internally to contain length of compressed data. Applications should ignore this value.

wPdk

State of the stroke, expressed as a PDK_ value.

dwTick

Time at beginning of the stroke. dwTick holds the number of milliseconds that have elapsed since the system tick reference that Windows determines at startup.

Comments

The STROKEINFO structure serves two main purposes. First, it is returned by the  GetPenHwEventData functions with each piece of new data from the tablet. Second, it is used in certain pen data functions such as AddPenInputHRC, AddPointsPenData, and GetPenDataStroke as a header for each stroke. In both cases, it contains information about a sequence of data from the tablet.

For examples and further information about STROKEINFO and its members, see the section “Recognition Functions” in Chapter 8, “Writing a Recognizer.”

For a list of stroke state bits, refer to the entry for PDK_ values in Chapter 13, “Pen Application Programming Interface Constants.”

See Also

AddPenInputHRC, GetPenDataStroke, GetPenInput, GetPenHwEventData, InsertPenDataStroke, TargetPoints, PDK_


SYC

1.0    2.0

The SYC symbol correspondence structure is best described in context with the SYG symbol graph and SYE symbol element structures. For a description of the SYC structure, see the entry for SYG below.

The SYC structure is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions.

A single shape can be identified by one or more SYC structures.

typedef struct {

UINT    wStrokeFirst;

UINT    wPntFirst;

UINT    wStrokeLast;

UINT    wPntLast;

BOOL    fLastSyc;

} SYC;

Members

wStrokeFirst

Index number of the first stroke of the correspondence.

wPntFirst

Index number of the first point in the stroke identified by wStrokeFirst.

wStrokeLast

Index number of the last stroke of the correspondence.

wPntLast

Index number of the last point in the stroke identified by wStrokeLast.

fLastSyc

TRUE if there are no more SYC structures for the current SYE (symbol element).

Comments

All indexes are zero-based, so that an index of 0 indicates the first of a sequence.

Figure 11.6 illustrates the relationship of symbol values and symbol graphs. The first line shows that a symbol value is a single SYE symbol element. A series of symbol values can be connected by the SYV_OR value to create an OR string, as the second line illustrates. This OR string begins with the SYV_BEGINOR value and ends with a symbol value followed by SYV_ENDOR. The third line shows a symbol graph that is simply a symbol value or an OR string, in either case ending with the SYV_NULL value.

See Also

RCRESULT, TrainContext, SYV_


SYE

1.0    2.0

The SYE symbol element structure is best described in context with the SYG symbol graph and SYC symbol correspondence structures. For a description of the SYE structure, see the entry for SYG below.

The SYE structure is provided only for compatibility with version 1.0 of the Pen API, and will not be supported in future versions.

An SYE structure contains a symbol, which can be a character, gesture, or string.

typedef struct {

SYV     syv;

LONG    lRecogVal;

CL      cl;

int     iSyc;

} SYE;

Members

syv

Symbol value.

lRecogVal

Reserved.

cl

Confidence level.

iSyc

Index into array of SYC structures. The array identifies the raw data that makes up the symbol. It is possible for several SYE structures to use the same SYC structures.


SYG

1.0    2.0

A symbol graph, which represents the possible interpretations identified by the recognizer.

typedef struct {

POINT rgpntHotSpots[MAXHOTSPOT];

int cHotSpot;

int nFirstBox;

LONG lRecogVal;

LPSYE lpsye;

int cSye;

LPSYC lpsyc;

int cSyc;

SYV syv;

LONG lRecogVal;

CL cl;

int iSyc;

UINT wStrokeFirst;

UINT wPntFirst;

UINT wStrokeLast;

UINT wPntLast;

BOOL fLastSyc;

} SYG;

Members

rgpntHotSpots[MAXHOTSPOT]

Hot spots of the symbol (if any). MAXHOTSPOT is defined as 8.

cHotSpot

Number of valid hot spots in rgpntHotSpots.

nFirstBox

Row-major index to box of first character in result.

lRecogVal

Reserved.

lpsye

Pointer to array of SYE structures representing nodes of symbol graph.

cSye

Number of SYE structures in array lpsye.

lpsyc

Pointer to corresponding array of SYC symbol ink structures.

cSyc

Number of SYC structures in symbol graph.

Comments

All indexes are zero-based.

If a single entity recognized by the recognizer is mapped to a string of several symbol values, the recognizer creates multiple SYE. This is the case for recognizers that can recognize highly stylized sequences of characters—for example, “ing”—in which the individual characters are not necessarily recognized.

The nFirstBox member has no meaning for gestures. A gesture is applied to the location indicated by its hot spot.

The SYG, SYE, and SYC structures define the relationship between raw pen data and recognized results. However, in version 2.0 of the Pen API they are rarely of interest to applications for two reasons. First, API functions return recognition results without forcing the application to deal with the complexities of raw pen data. And second, SYG, SYE, and SYC apply mainly to recognizers.

All nontrivial recognizers should somehow track the pen strokes that form each character in the returned results. To be compatible with version 1.0, a recognizer must use the SYG, SYE, and SYC structures and return a symbol graph—an SYG structure—as a member of the RCRESULT structure. Version 2.0 does not mandate how a recognizer should map pen data to symbols. However, these three structures represent a viable method. Recognizer developers writing for version 2.0 may want to use the structures or create variations.

The following information applies to version 1.0 applications and recognizers, and to version 2.0 recognizers that employ symbol graphs to relate strokes to recognized symbols. For further information about SYG, SYE, and SYC, see “Returning Results” in Chapter 8, “Writing a Recognizer.”

A symbol graph is a representation of the possible interpretations identified by the recognizer. The RC Manager processes the symbol graph using the dictionary path to identify the best interpretation. This best interpretation is returned in the results message along with the symbol graph.

A symbol value is a 32-bit value that represents a glyph (such as a character or a gesture) recognized by a recognizer. This is sometimes referred to as a symbol. A symbol string is an array of symbols terminated with SYV_NULL.

Each element of the symbol graph, an SYE, contains information about the recognized character—for example, bounding rectangle and hot spots. The SYC structure maps SYE structures back to the corresponding raw data. If two or more consecutive SYE structures map to the same SYC, they represent an indivisible unit. For example, the user might teach the system of “th” with the crossbar of the “t” connected to the “h.” SYC structures are used primarily for training.

A version 1.0 application generally does not use the symbol graph directly. Instead, it uses the hSyv member of RCRESULT, which contains a symbol string that represents the best interpretation from the symbol graph. SYE and SYC structures work together with the HPENDATA memory block to identify strokes and meanings for ink. The following table lists the basic functions of these structures.

Structure	Description
HPENDATA	Contains raw data information: strokes, pen up, pen down, points, and so on.
SYC	A symbol character map. SYC structures delimit strokes in an HPENDATA. A single shape can be identified  by one or more SYC structures. Each SYC identifies a starting stroke, an ending stroke, a starting point, and an ending point. A flag also indicates whether subsequent SYC structures in the array contain additional strokes for the shape. (This feature is used for delayed strokes, such as the cross stroke of the letter “t.”)
SYE	A symbol element. An SYE contains a symbol, which can be a character, a gesture, or a string. The symbol  is denoted by an SYV. The SYE contains an index into an array of SYC structures; this array identifies the  raw data that makes up the symbol. It is possible for several SYEs to use the same SYC structures. The  SYC structures contain indexes into the raw data.
SYV	A symbol value.
SYG	A symbol graph.
A set of SYEs and SYCs, together with an HPENDATA structure, is sufficient to define ink and specify how that ink should be interpreted. The training functions TrainContext and TrainInk use this information in training.


TARGET

2.0

Contains information about a single target.

typedef struct {

DWORD dwFlags;

DWORD idTarget;

HTRG htrgTarget;

RECTL rectBound;

DWORD dwData;

RECTL rectBoundInk;

RECTL rectBoundLastInk;

} TARGET;

Members

dwFlags

Reserved for future extensions. Must be set to 0.

idTarget

Array index to the target within rgTarget array in TARGINFO structure.

htrgTarget

Handle to the owner window that receives messages on behalf of the target.

rectBound

Bounding rectangle of the target.

dwData

Target-specific extra information to be filled during data collection.

rectBoundInk

Reserved; must be 0.

rectBoundLastInk

Reserved; must be 0.

See Also

TargetPoints, TARGINFO, WM_PENEVENT, INPPARAMS


TARGINFO

2.0

A set of targets.

typedef struct {

DWORD cbSize;

DWORD dwFlags;

HTRG htrgOwner;

WORD cTargets;

WORD iTargetLast;

TARGET rgTarget[1];

} TARGINFO;

Members

cbSize

Size of this structure in bytes. Note that this is the original size, which assumes only a single TARGET structure in rgTarget. The value should be sizeof( TARGINFO ).

dwFlags

Flags have been defined to get different targeting behavior depending on the needs of the calling application. These flags work as hints for the targeting algorithm. The flags are considered by the Pen API in the order in which they appear in the following list. If none of the flags are set, the stroke is not assigned to any target.

TPT_TEXTUAL

When this flag is set, Windows applies textual heuristics, such as identifying word breaks, while deciding the target to which a stroke should be assigned.

If there is no text to intersect with, the input is disregarded completely. Therefore, this option should not generally be used by itself.

TPT_INTERSECTINK

Indicates that if the stroke being targeted intersects with the ink in a target, the stroke should be assigned to that target. Intersection is determined based on the bounding rectangle of the stroke and the bounding rectangle of the pen data assigned to a target. If there is no ink to intersect with, the input is disregarded completely. Therefore, this option should not generally be used by itself.

TPT_CLOSEST

Indicates that the stroke should be targeted to the target closest to the stroke. The bounding rectangle of the stroke and the bounding rectangle of the target are specified by the rectBound element of the TARGET structure.

htrgOwner

Handle to the owner target. Use the HtrgFromHwnd and HwndFromHtrg macros to convert a target handle of HTRG type to and from an HWND type.

cTargets

Number of targets.

iTargetLast

Last target. Used by the TargetPoints function during textual heuristics. iTargetLast contains the number of the target window that last received data. The system uses this value to optimize its determination of the next target. Applications can read but should not overwrite iTargetLast.

rgTarget[1]

Variable-length array of targets.

Comments

For best results, most applications should set all hints for targeting. That is, the dwFlags member of TARGINFO should be set to TPT_DEFAULT, which is the combination of TPT_TEXTUAL | TPT_INTERSECTINK | TPT_CLOSEST.

Before using TARGINFO, an application must initialize cbSize with sizeof( TARGINFO ).

See Also

TARGET, TargetPoints


Pen Application Programming Interface Messages

This chapter describes in alphabetical order many of the messages and submessages defined by the Pen Application Programming Interface. Each entry describes a separate message organized under the following topic headings:

Topic heading	Description
Parameters	Message wParam and lParam parameters.
Return Value	Return value from the Windows SendMessage function (if applicable).
Comments	Additional information about the message.
See Also	Cross-references to related API services.


HE_CANCELCONVERT

Cancels Kana-to-Kanji conversion. Submessage of WM_PENCTL. (Japanese version only.)

Parameters

wParam

HE_CANCELCONVERT.

lParam

Reserved and must be 0.

Return Value

Returns TRUE if there are no errors; otherwise, returns FALSE.


HE_CHAROFFSET

Converts the logical character position of a character in a control into a byte offset to the character. Submessage of WM_PENCTL.

Parameters

wParam

HE_CHAROFFSET.

lParam

The low-order word contains the logical character position. The high-order word is reserved and must be 0.

Return Value

If the supplied logical character position is less than the total number of logical characters in the control, the low-order word of the return value contains the requested byte offset of the position and the high-order word is 0. Otherwise, the low-order word contains the length of the text in bytes and the high word contains 0xFFFF.

Comments

This submessage is for bedit controls only. Both the logical character position and the byte offset are zero-based.

See Also

WM_PENCTL


HE_CHARPOSITION

Converts a byte offset in the text buffer of a control to the logical character position, which contains the byte specified by the byte offset. Submessage of WM_PENCTL.

Parameters

wParam

HE_CHARPOSITION.

lParam

The low-order word contains the byte offset. The high word is reserved and must be 0.

Return Value

If the supplied byte offset is less than the length of the text in bytes, the low-order word of the return value contains the logical character position and the high-order word is 0; otherwise, the low-order word contains the total number of logical characters in the text of the control and the high-order word contains 0xFFFF.

Comments

This submessage is for bedit controls only. Both the byte offset and the logical character position are zero-based.

See Also

HE_CHAROFFSET, WM_PENCTL


HE_DEFAULTFONT

Switches the font of a bedit control to the default font that the bedit control selected at the time of creation. Submessage of WM_PENCTL.

Parameters

wParam

HE_DEFAULTFONT.

lParam

If the low-order word is nonzero, the control is repainted.

Return Value

The return value is undefined.

Comments

This submessage is for bedit controls only.

See Also

WM_PENCTL


HE_ENABLEALTLIST

Enables or disables the alternate list in a bedit control. Submessage of WM_PENCTL.

Parameters

wParam

HE_ENABLEALTLIST.

lParam

If the low-order word is nonzero, the alternate list menu is enabled; otherwise, it is disabled.

Return Value

The return value is undefined.

Comments

This submessage is for bedit controls only.

See Also

HE_HIDEALTLIST, HE_SHOWALTLIST, WM_PENCTL


HE_FIXKKCONVERT

Confirm undetermined string and close Input Method Editor (IME). Submessage of WM_PENCTL. (Japanese version only.)

Parameters

wParam

HE_FIXKKCONVERT.

lParam

Reserved and must be 0.

Return Value

Returns TRUE if there are no errors; otherwise, returns FALSE.

Comments

When in preconversion mode, the marked conversion string area is removed. Marked conversion strings are indicated in the Input Method Editor (IME) in a different shade than standard edit control text selection. When in conversion mode (no marked string), the string is confirmed and the IME is closed. Available for bedits only.


HE_GETBOXLAYOUT

Retrieves the box layout for a control. Submessage of WM_PENCTL.

Parameters

wParam

HE_GETBOXLAYOUT.

lParam

Address of a BOXLAYOUT structure that is filled with the current box layout for the control.

Return Value

The return value is undefined.

Comments

This submessage is for bedit controls only.

See Also

BOXLAYOUT, WM_PENCTL


HE_GETCONVERTRANGE

Gets the range of the marked conversion string. Submessage of WM_PENCTL. (Japanese version only.)

Parameters

wParam

HE_GETCONVERTCHAR.

lParam

Not used.

Return Value

Returns a 32-bit value with the starting character position (not byte position) of the marked conversion string in the low-order word and the position of the last character of the marked conversion string plus 1 in the high-order word.

Comments

Available for bedits only. The message returns a valid value only when in preconversion mode; otherwise, it returns 0.


HE_GETINFLATE

Retrieves the inflation rectangle for a control. Submessage of WM_PENCTL.

Parameters

wParam

HE_GETINFLATE.

lParam

Address of a RECTOFS structure that is filled with the current values for the inflation rectangle.

Return Value

Returns TRUE if successful; otherwise, FALSE.

Comments

For a description of how to increase or decrease the writing area of a control, see “HE_SETINFLATE Submessage” in Chapter 3, “The Writing Process.”

See Also

HE_SETINFLATE, RECTOFS, WM_PENCTL


HE_GETINKHANDLE

Retrieves the ink handle for the current control. Submessage of WM_PENCTL.

Parameters

wParam

HE_GETINKHANDLE.

lParam

Unused.

Return Value

The low-order word of the return value contains a handle to the captured ink. If the return value is NULL, the control is not in ink mode.

Comments

The returned ink handle is valid only during the life of the control. The handle becomes invalid after the control is destroyed.

See Also

WM_PENCTL


HE_GETKKCONVERT

Determines if the Input Method Editor (IME) is in conversion mode. Submessage of WM_PENCTL. (Japanese version only.)

Parameters

wParam

HE_GETKKCONVERT.

lParam

Reserved and must be 0.

Return Value

Returns TRUE if the IME is in conversion mode; otherwise, returns FALSE.

Comments

Available for bedits only.


HE_GETKKSTATUS

Determines the mode of the Kana-to-Kanji conversion in the Input Method Editor (IME). Submessage of WM_PENCTL. (Japanese version only.)

Parameters

wParam

HE_GETKKSTATUS.

lParam

Reserved and must be 0.

Return Value

Returns one of the following values or FALSE:

Value	Current Status
HEKKR_PRECONVERT	In preconversion mode.
HEKKR_CONVERT	In conversion mode
HHEKKR_NOCONVERT	In nonconversion mode
Comments

The IME recognizes three modes: preconversion mode, conversion mode, and non-conversion mode. In preconversion mode, the user has entered text intended for conversion by the IME and the text is marked. When the user invokes the IME on the marked range of characters, the conversion mode is entered and the IME is active. Once the user confirms an IME conversion, the nonconversion mode (normal mode) is entered.

The term “marked” refers to the range of cells in the bedit that have been selected for character conversion. Characters marked for conversion appear differently to the user than normally selected characters.

This submessage is available for bedits only. This message can also be used to determine keyboard IME status by checking for HEKKR_CONVERT.


HE_GETUNDERLINE

Queries for the current underline mode. Submessage of WM_PENCTL.

Parameters

wParam

HE_GETUNDERLINE.

lParam

Unused.

Return Value

Returns TRUE if the underline mode is set; otherwise, FALSE.

Comments

This submessage is for hedit controls only.

See Also

WM_PENCTL


HE_HIDEALTLIST

Hides the alternate list in a bedit control, assuming an alternate list menu is being displayed. Submessage of WM_PENCTL.

Parameters

wParam

HE_HIDEALTLIST.

lParam

If the low-order word is HEAL_DEFAULT, the alternate list menu is hidden.

Return Value

The return value is undefined.

Comments

This submessage is for bedit controls only.

See Also

HE_ENABLEALTLIST, HE_SHOWTLIST, WM_PENCTL


HE_KKCONVERT

Starts Kana-to-Kanji conversion. Submessage of WM_PENCTL. (Japanese version only.)

Parameters

wParam

HE_KKCONVERT.

lParam

Must be one of the following values:

Value	Meaning
HEKK_DEFAULT	The first time the conversion is specified, the selected character string is replaced with the conversion result; the second time it is specified, the conversion candidate dialog box appears.
HEKK_CONVERT	The selected character string is replaced with the conversion result regardless of how many times conversion has been specified.
HEKK_CANDIDATE	Causes the conversion candidate dialog box to appear.
HEKK_DBCSCHAR	The SBCS characters (0x20 − 0x7E, 0xA1 − 0xDF) are replaced by their DBCS equivalents.
HEKK_SBCSCHAR	The DBCS characters in the selected character string or marked conversion string that have equivalent SBCS representations are replaced by their equivalent SBCS characters.
HEKK_HIRAGANA	The katakana characters (DBCS or SBCS) in the selected character string or marked conversion string are replaced with their hiragana equivalents.
HEKK_KATAKANA	The hiragana characters in the selected character string or marked conversion string are replaced with their DBCS katakana representation.
Return Value

Returns TRUE if there are no errors; otherwise, returns FALSE:

Comments

In this message, “marked conversion string” indicates the string in the Input Method Editor (IME) that is marked for conversion. Text marked for conversion is indicated by a different selection color than that used for normal text selection in a standard text edit control. Available for bedits only.


HE_PUTCONVERTCHAR

Sends a character to the Input Method Editor (IME) and marks it for conversion. Submessage of WM_PENCTL. (Japanese version only.)

Parameters

wParam

HE_PUTCONVERTCHAR.

lParam

The low-order word contains the character code, which can be an SBCS or DBCS character.

Return Value

Returns TRUE if there are no errors; otherwise, returns FALSE.

Comments

Posting this message is exactly like posting a WM_CHAR message to a bedit or edit control with the exception that the posted character also acquires the attribute of being a character marked for conversion in the Input Method Editor. This sub-message is available for bedits only.


HE_SETBOXLAYOUT

Sets the box layout for a control. Submessage of WM_PENCTL. Submessage of WM_PENCTL.

Parameters

wParam

HE_SETBOXLAYOUT.

lParam

Address of the BOXLAYOUT structure to be set.

Return Value

Returns TRUE if successful; otherwise, returns FALSE.

Comments

This submessage is for bedit controls only.

See Also

WM_PENCTL


HE_SETCONVERTRANGE

Sets the range of the marked conversion string. Submessage of WM_PENCTL. (Japanese version only.)

Parameters

wParam

HE_SETIMEDEFAULT.

lParam

The low-order word contains the starting character position (not byte position) of the marked conversion string. The high-order word contains the ending character position plus 1.

Return Value

Returns TRUE if there are no errors; otherwise, returns FALSE.

Comments

Available for bedits only. If the starting character position is 0 and the ending char-acter position is −1, all the text in the control becomes the marked conversion string. If the starting character is −1, the marked conversion string area is removed. When characters are marked for conversion, the Input Method Editor is said to be in preconversion mode.

Returns FALSE if in conversion mode. If there is a selection, the selection will be cleared. The caret will be moved to the end of the marked conversion string.


HE_SETINFLATE

Sets the inflation rectangle for a control. Submessage of WM_PENCTL.

Parameters

wParam

HE_SETINFLATE.

lParam

Address of a RECTOFS structure specifying the inflation margins for the writing window.

Return Value

Returns TRUE if successful, or FALSE if an invalid window rectangle is specified.

Comments

This is a submessage of the WM_PENCTL message.

For a description of how to increase or decrease the writing area of a control, see “HE_SETINFLATE Submessage” in Chapter 3, “The Writing Process.”

See Also

HE_GETINFLATE, RECTOFS, WM_PENCTL


HE_SETINKMODE

Starts ink data collection in a control. Submessage of WM_PENCTL.

Parameters

wParam

HE_SETINKMODE.

lParam

The low-order word is the initial HPENDATA object or NULL. If the initial HPENDATA is supplied, it must be relative to the top-left corner of the client rectangle of the control.

Return Value

Returns TRUE if successful; otherwise, returns FALSE.

Comments

This is a submessage of the WM_PENCTL message.

See Also

WM_PENCTL


HE_SETUNDERLINE

Sets or cancels underline mode in an hedit control. Submessage of WM_PENCTL.

Parameters

wParam

HE_SETUNDERLINE.

lParam

The low-order word is TRUE to set underline mode and FALSE to cancel it.

Return Value

Returns the current underline mode.

Comments

This submessage is for single-line hedit controls only.

See Also

WM_PENCTL


HE_SHOWALTLIST

Displays the alternate list menu for the current cell in a bedit control, assuming that alternate lists are enabled. Submessage of WM_PENCTL.

Parameters

wParam

HE_SHOWALTLIST.

lParam

If the low-order word is HEAL_DEFAULT, the alternate list menu is displayed.

Return Value

If more than one character is selected, the alternate list of the first character in the selection is displayed. If nothing is selected, the alternate list for the character to the right of the caret is displayed and the return value is TRUE.

Comments

This submessage is for bedit controls only. If more than one box is selected, the HE_SHOWALTLIST message will drop a word alternate list menu; otherwise, it will drop a character alternate list menu.

See Also

HE_ENABLEALTLIST, HE_HIDEALTLIST, WM_PENCTL


HE_STOPINKMODE

Stops ink collection in a control. Submessage of WM_PENCTL.

Parameters

wParam

HE_STOPINKMODE.

lParam

If the low-order word is HEP_RECOG, the control performs recognition and displays text. If the low-order word is HEP_NORECOG (0), the control removes the ink without performing recognition. If the low-order word is HEP_WAITFORTAP, the control performs recognition when the next tap in the writing area occurs.

Return Value

Returns TRUE if successful; otherwise, returns FALSE.

Comments

This is a submessage of the WM_PENCTL message.

See Also

WM_PENCTL


HN_BEGINDIALOG

Sent by a bedit or hedit control to its parent window just before the control puts up any kind of dialog, including the lens, edit text, or garbage-detection dialogs.

The control’s parent window receives this notification message through a WM_COMMAND message.

Parameters

wParam

Specifies the identifier of the hedit or bedit control.

lParam

Specifies the handle of the hedit or bedit control in the low-order word and the HN_BEGINDIALOG notification message in the high-order word.

Return Value

If the parent window returns TRUE to this notification message, the bedit or hedit control refrains from opening the dialog; otherwise, the dialog is opened. Note that the application can disable the hedit or bedit control’s ability to open a dialog by specificying CIH_NOEDITTEXT in the WM_CTLINIT message.


HN_ENDDIALOG

Sent by a bedit or hedit control to its parent window of the dialog when a dialog opened by the control is destroyed.

The control’s parent window receives this notification message through a WM_COMMAND message.

Parameters

wParam

Specifies the identifier of the hedit or bedit control.

lParam

Specifies the handle of the hedit or bedit control in the low-order word and the HN_ENDDIALOG notification message in the high-order word.

Return Value

The return value is ignored.


HN_ENDKKCONVERT

Sent after a bedit control has completed the Kana-to-Kanji conversion. Submessage of WM_PENCTL. (Japanese version only.)

The control’s parent window receives this notification message through a WM_COMMAND message.

Parameters

wParam

Specifies the identifier of the hedit or bedit control.

lParam

Specifies the handle of the hedit or bedit control in the low-order word and the HN_ENDKKCONVERT notification message in the high-order word.

Return Value

The return value is ignored.


HN_ENDREC

Sent after an hedit or bedit control has acted upon the results of recognition from a recognition session.

The control’s parent window receives this notification message through a WM_COMMAND message.

Parameters

wParam

Specifies the identifier of the hedit or bedit control.

lParam

Specifies the handle of the hedit or bedit control in the low-order word and the HN_ENDREC notification message in the high-order word.

Return Value

The return value is ignored.


HN_RESULT

Sent when an hedit or bedit control receives results of inking or recognition from a recognition session, but before the control absorbs the results into its internal data structures.

The control’s parent window receives this notification message through a WM_COMMAND message.

Parameters

wParam

Specifies the identifier of the hedit or bedit control.

lParam

Specifies the handle of the hedit or bedit control in the low-order word and the HN_RESULT notification message in the high-order word.

Return Value

The return value is ignored.

Comments

The application can get the results and optionally modify them using the WM_PENMISC message with the PMSC_GETSYMBOLCOUNT, PMSC_GETSYMBOLS, and the PMSC_SETSYMBOLS submessages.

See Also

WM_PENMISC


IE_CANUNDO

Retrieves an indication of whether the control can undo the last user operation.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

Returns one of the following values:

Constant	Description
IER_YES	The control can undo the last operation.
IER_NO	The control cannot undo the last operation or the control has security protection disallowing an undo operation.
IER_PARAMERR	wParam or lParam is invalid.


IE_DOCOMMAND

Causes an ink edit control to execute a command.

Parameters

wParam

Contains one of the following command message codes:

Constant	Description
IEM_CLEAR	Clear (delete) the selection.
IEM_COPY	Copy selected strokes.
IEM_CUT	Cut selected strokes.
IEM_ERASE	Use eraser mode to erase.
IEM_LASSO	Use lasso mode to select strokes.
IEM_PASTE	Paste Clipboard contents to the iedit control.
IEM_PROPERTIES	Invoke the properties dialog box on the selected strokes.
IEM_RESIZE	Resize selected strokes.
IEM_SELECTALL	Select all the strokes in the control.
IEM_UNDO	Undo the last action.
lParam

Not used; must be 0.

Return Value

Returns IER_OK if successful; otherwise, returns one of the following:

Constant	Description
IER_PARAMERR	wParam or lParam is invalid.
IER_MEMERR	A memory error occurred.
IER_SECURITY	The control has security protection disallowing the operation.
Comments

An application can use this message to force the ink edit control to execute a valid command. For example, an application might have a toolbar button or menu item that can be used to trigger a copy command. The IE_DOCOMMAND message can be used in response to the user’s pressing the button or selecting the menu item to have the iedit control copy the selected ink to the Clipboard.

The iedit control sends its parent an IN_COMMAND notification if the IEN_EDIT notify bit is set, to which the parent can respond in the usual ways. Sending a command that the iedit control cannot interpret (that is, a command code of IEM_USER or above) causes any specified notification but the iedit control takes no other action.

The IEN_EDIT bit is set by default. It should be cleared if the control’s parent does not want to receive the IN_COMMAND notification message.

See Also

IE_GETCOMMAND


IE_EMPTYUNDOBUFFER

Empties the undo buffer.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

Returns one of the following:

Constant	Description
IER_OK	Success.
IER_PARAMERR	wParam or lParam is invalid.
IER_SECURITY	The control has security protection disallowing the operation.
Comments

If there is nothing in the undo buffer, this message returns IER_OK but does nothing else. As long as the buffer remains empty after sending IE_EMPTYUNDOBUFFER, the messages IE_CANUNDO and WM_UNDO return FALSE.

See Also

IE_CANUNDO


IE_GETAPPDATA

Retrieves the application data saved in the ink edit control.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

Returns the contents of the application data area if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

An application can save any DWORD value with the ink edit control. The control does not use this data. The IE_SETAPPDATA and IE_GETAPPDATA messages provide the only means for an application to interact with the data.

See Also

IE_SETAPPDATA


IE_GETBKGND

Retrieves the current background painting options of an ink edit control.

Parameters

wParam

Not used; must be 0.

lParam

Address of a WORD variable that receives the current background options, as given in the following list:

Constant	Description
IEB_BIT_CENTER	Center supplied bitmap in control.
IEB_BIT_STRETCH	Stretch bitmap to fit control.
IEB_BIT_TILE	Tile supplied bitmap repeatedly in control.
IEB_BIT_UL	Align supplied bitmap to upper-left corner in the control. (UL stands for “upper left.”)
IEB_BRUSH	Use application-supplied brush in lParam.
IEB_DEFAULT	Do default background (use COLOR_WINDOW).
IEB_OWNERDRAW	Parent will draw background.
Return Value

If successful, returns a handle to the background bitmap or a brush, or NULL, according to the option specified in lParam; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

The returned handle is owned by the iedit control; the application should not delete it. If the application needs to preserve this information, it should copy the handle.

See Also

IE_SETBKGND, IE_GETGRIDPEN, IE_SETGRIDPEN


IE_GETCOMMAND

Retrieves the menu item number of a selected command.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

Returns the menu item number if successful; otherwise, returns one of the following:

Constant	Description
IER_PARAMERR	wParam or lParam is invalid.
IER_NOCOMMAND	Attempt to issue IE_GETCOMMAND when no command was selected.
Comments

The application sends the IE_GETCOMMAND message when it receives an IN_COMMAND notification to find out what menu item the user selected. This message can be sent only during processing of an IN_COMMAND notification. It returns the IER_NOCOMMAND error code if sent at any other time.

See Also

IE_DOCOMMAND


IE_GETCOUNT

Retrieves the count of strokes in the control.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

If successful, returns the total number of strokes in the control; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

See Also

IE_GETSELCOUNT


IE_GETDRAWOPTS

Retrieves the ink-drawing option.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

Returns one of the following ink-drawing options:

Constant	Description
IEDO_FAST	Drawing is done as fast as possible. This is the default setting.
IEDO_NONE	No drawing is done (disabled drawing).
IEDO_SAVEUPSTROKES	Save pen-up strokes in the HPENDATA object.
Comments

IEDO_FAST and IEDO_NONE are mutually exclusive options.

See Also

IE_SETDRAWOPTS


IE_GETERASERTIP

Retrieves the eraser pen tip.

Parameters

wParam

Not used; must be 0.

lParam

Address of a PENTIP structure.

Return Value

Returns IER_OK if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

The PENTIP structure is filled with the current pen tip used for erasing.

See Also

PENTIP, IE_SETERASERTIP


IE_GETFORMAT

Retrieves the current format of a stroke or a set of strokes in an iedit control.

Parameters

wParam

Not used; must be 0.

lParam

Address of a STRKFMT structure.

Return Value

If successful, returns bit flags that indicate whether the strokes identified in the STRKFMT structure have different color or width, as described in the “Comments” section.

If an error occurs, returns one of the following values:

Constant	Description
IER_ERROR	Unknown error.
IER_PARAMERR	wParam or lParam is invalid. Also returned when there is an invalid stroke index and the IESF_STROKE option is specified in the iesf member of the STRKFMT structure.
IER_SECURITY	The control has security protection disallowing the operation.
IER_SELECTION	No valid selection when the IESF_SELECTION option is specified in the iesf member of the STRKFMT structure.
Comments

If the value in the iesf member of the STRKFMT structure has the IESF_STROKE bit set, IE_GETFORMAT refers to the single stroke identified in the iStrk member. In this case:

•	The return value is 0.

•	The bwidth and rgb members in PENTIP specified in the STRKFMT structure contain the stroke’s color and width.

If either the bit IESF_SELECTION or IESF_ALL is set in iesf, IE_GETFORMAT retrieves format information for multiple strokes. In this case, the return value con-tains the IESF_TIPCOLOR or IESF_TIPWIDTH bit flags that indicate whether the multiple strokes share the same ink color and width.

For example, if the multiple requested strokes all have the same width, then

•	The IESF_TIPWIDTH bit of the return value is 0 to indicate the strokes all have the same width.

•	The bwidth member in PENTIP specified in the STRKFMT structure contains the common width.

If the strokes do not all have the same color, IE_GETFORMAT returns the following information:

•	The IESF_TIPCOLOR bit is set in the return value to indicate the strokes do not share a common color.

•	The rgb member in PENTIP specified in the STRKFMT structure contains the color of the last stroke in the group.

The caller must initialize the cbSize member of the STRKFMT structure to sizeof( STRKFMT ) before sending IE_GETFORMAT.

The supplied STRKFMT structure specifies the stroke or strokes for which the attributes are desired. The structure is filled according to the request and the actual stroke attributes.

See Also

IE_SETFORMAT, PENTIP, STRKFMT


IE_GETGESTURE

Retrieves the specifics of a gesture.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

Returns an HRCRESULT of the gesture if successful; otherwise, returns one of the following:

Constant	Description
IER_PARAMERR	wParam or lParam is invalid.
IER_NOGESTURE	Indicates an attempt to issue IE_GETGESTURE when no gesture was performed.
Comments

An application sends IE_GETGESTURE when it receives an IN_GESTURE notifi-cation, to retrieve the specifics of the user’s gesture. This message can be sent only during processing of an IN_GESTURE notification. It returns the error code IER_NOGESTURE if it is set at any other time.

If successful, the application receives an HRCRESULT, which can then be used to get information about the gesture specifics. This handle is still owned by the iedit control, however, and the application must neither delete the handle nor modify the data to which it refers.


IE_GETGRIDORIGIN

Retrieves the current origin of the rule or grid-line settings for the control.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

Returns the x-coordinate of the origin in the low-order word and the y-coordinate of the origin in the high-order word, if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

See Also

IE_GETBKGND, IE_GETGRIDORIGIN, IE_GETGRIDSIZE, IE_SETBKGND, IE_SETGRIDORIGIN, IE_SETGRIDPEN, IE_SETGRIDSIZE


IE_GETGRIDPEN

Retrieves the current GDI pen used to draw the rules or grid lines for the control.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

If successful, returns a handle to a GDI pen that is being used to draw the grid lines. This handle can be NULL; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

The handle of the GDI pen returned remains the property of the iedit control. The application must not delete this handle.

See Also

IE_GETBKGND, IE_GETGRIDORIGIN, IE_GETGRIDSIZE, IE_SETBKGND, IE_SETGRIDORIGIN, IE_SETGRIDPEN, IE_SETGRIDSIZE


IE_GETGRIDSIZE

Retrieves the current horizontal and vertical spacing of the rule or grid-line settings for the control.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

If successful, the low-order word has the horizontal spacing and the high-order word has the vertical spacing; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

See Also

IE_GETBKGND, IE_GETGRIDORIGIN, IE_GETGRIDPEN, IE_SETBKGND, IE_SETGRIDORIGIN, IE_SETGRIDPEN, IE_SETGRIDSIZE


IE_GETINK

Retrieves the contents of an ink edit control.

Parameters

wParam

IEGI_ALL to get the entire ink, or IEGI_SELECTION to get only the selected ink.

lParam

Not used; must be 0.

Return Value

Returns the handle to the HPENDATA structure if successful; otherwise, returns one of the following:

Constant	Description
IER_PARAMERR	wParam or lParam is invalid.
IER_MEMERR	A memory error occurred.
IER_SECURITY	The control has security protection disallowing the operation.
IER_SELECTION	Nothing is selected in the control; operation assumes a selection.
Comments

The returned HPENDATA structure becomes the property of the application, which must eventually destroy it. This handle is a copy of the handle used internally by the control. An application cannot change the control by modifying the pen data referred to by this handle, although the modified handle can subsequently be used in an IE_SETINK call, which modifies the control’s contents.

See Also

IE_SETINK


IE_GETINKINPUT

Retrieves the current ink input options for the control.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

Returns the current ink input bits if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

The ink input bits are as follows:

Constant	Description
IEI_MOVE	Move all ink inside the control.
IEI_RESIZE	Resize all ink to fit inside the control.
IEI_CROP	Crop all ink that falls outside the control.
IEI_DISCARD	Discard all ink if any falls outside the control.
See Also

IE_SETINKINPUT


IE_GETINKRECT

Retrieves the bounding rectangle of the ink.

Parameters

wParam

Not used; must be 0.

lParam

Address of a RECT structure.

Return Value

Returns IER_OK if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

The RECT structure is filled with the bounding rectangle of the current ink in the control. The rectangle is in the same coordinates as the scaling mode the HPENDATA object is in.


IE_GETMENU

Retrieves a handle to an ink edit control’s pop-up menu.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

Returns the handle to the menu if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

The iedit control continues to own the menu handle.

The application can perform standard menu operations upon the returned handle, including the addition, deletion, and modification of menu items. The application’s changes are reflected the next time the pop-up menu is invoked.


IE_GETMODE

Retrieves the current mode the control is in.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

If successful, returns one of the following values indicating the current control mode:

Constant	Description
IEMODE_READY	The control is ready for inking, moving strokes, tapping, resizing, and so on.
IEMODE_ERASE	The control is set to erasing mode.
IEMODE_LASSO	The control is set to lasso selection mode.
Otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

See Also

IE_SETMODE


IE_GETMODIFY

Queries whether the contents of the control have been modified since the control was created.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

Returns one of the following values:

Constant	Description
IER_YES	The control’s contents have been modified.
IER_NO	The control’s contents have not been modified.
IER_PARAMERR	wParam or lParam is invalid.
Comments

This command succeeds regardless of the security setting.

See Also

IE_SETMODIFY


IE_GETNOTIFY

Retrieves the current notification options for the control.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

If successful, returns the current notification bits, as listed here:

Constant	Description
IEN_EDIT	Require notifications of editing or command events.
IEN_FOCUS	Require notifications of focus events.
IEN_PAINT	Require notifications of painting events.
IEN_PDEVENT	Require notifications of pointing-device events (clicks and taps).
IEN_PROPERTIES	Require notifications before bringing up the properties dialog box.
IEN_SCROLL	Require notifications of scrolling events.
Otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

See Also

IE_SETNOTIFY


IE_GETPAINTDC

Retrieves the handle to the device context (HDC), which is used to paint an ink edit control. This HDC was supplied to the iedit control by BeginPaint; therefore, its clipping region is set according to those portions of the iedit control that have been invalidated.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

Returns the HDC if successful; otherwise, returns one of the following:

Constant	Description
IER_PARAMERR	wParam or lParam is invalid.
IER_NOTINPAINT	Attempted IE_GETPAINTDC outside of paint notification.
Comments

The application can send this message only when the parent window is processing one of the painting notifications: IN_PREPAINT, IN_PAINT, IN_POSTPAINT, or IN_ERASEBKGND. An attempt to send it at any other time will fail, returning IER_NOTINPAINT.

The clipping region is already appropriately set when sending IE_GETPAINTDC. The HDC is in the MM_TEXT mapping mode. The HDC must not be released; the iedit control does this after returning from the painting notification.


IE_GETPDEVENT

Retrieves the pointing-device event that triggered the IN_PDEVENT notification. This can be from a mouse, pen, or other device.

Parameters

wParam

Not used; must be 0.

lParam

Address of a PDEVENT structure that is filled by the control when it receives this message.

Return Value

Returns one of the following:

Constant	Description
IER_OK	Success.
IER_PARAMERR	wParam or lParam is invalid.
IER_NOPDEVENT	No event occurred.
Comments

This message can succeed only during the processing of an IN_PDEVENT notification. At all other times its use is invalid. The caller must initialize the cbSize member of the PDEVENT structure to sizeof( PDEVENT ) before sending this message.

The application can cause the event to be discarded by returning TRUE to the IN_PDEVENT notification.

See Also

IN_PDEVENT, PDEVENT


IE_GETPENTIP

Retrieves the default ink pen tip.

Parameters

wParam

Not used; must be 0.

lParam

Address of a PENTIP structure.

Return Value

Returns IER_OK if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

The PENTIP structure is filled with the current pen tip used for default inking.

See Also

PENTIP, IE_SETPENTIP


IE_GETRECOG

Retrieves the current recognition setting of the control.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

If successful, returns the following recognition flags, which can be combined using the bitwise-OR operator:

Constant	Description
IEREC_ALL	All recognition enabled.
IEREC_GESTURE	Gesture recognition enabled.
IEREC_NONE	Recognition disabled.
Otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

Currently, IEREC_GESTURE and IEREC_ALL are equivalent.

See Also

IE_SETRECOG


IE_GETSECURITY

Retrieves the current security setting of the control.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

If successful, returns the following security flags, which can be combined using the bitwise-OR operator:

Constant	Description
IESEC_NOCOPY	Copying not allowed.
IESEC_NOCUT	Cutting, deleting, and clearing not allowed.
IESEC_NOPASTE	Pasting disabled.
IESEC_NOUNDO	Undo not permitted.
IESEC_NOINK	Inking not allowed.
IESEC_NOERASE	Erasing not allowed.
IESEC_NOGET	The IE_GETINK message is disabled.
IESEC_NOSET	The IE_SETINK message is disabled.
Otherwise, returns IER_SECURITY to indicate that the control has security pro-tection disallowing the operation.

See Also

IE_SETSECURITY


IE_GETSEL

Retrieves the selection status of a particular stroke.

Parameters

wParam

Contains the zero-based index of the stroke whose selection status is queried.

lParam

Not used; must be 0.

Return Value

Returns one of the following values:

Constant	Description
IER_YES	The stroke is selected.
IER_NO	The stroke is not selected.
IER_PARAMERR	wParam or lParam is invalid.
See Also

IE_SETSEL


IE_GETSELCOUNT

Retrieves the number of selected strokes.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

If successful, returns the number of selected strokes; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

See Also

IE_GETSEL, IE_GETCOUNT


IE_GETSELITEMS

Retrieves a list of all selected strokes in the control.

Parameters

wParam

Size of the buffer passed in.

lParam

Address of a buffer of UINT variables that will be filled with the indices of the selected strokes in the control. This buffer must be large enough to hold all requested indices. The application can ensure this by first getting the number of selected strokes with the IE_GETSELCOUNT message and then calculating the required size of the buffer.

Return Value

Returns IER_OK if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

See Also

IE_GETSELCOUNT


IE_GETSTYLE

Retrieves the current style attributes of an ink edit control.

Parameters

wParam

Not used; must be 0.

lParam

Not used; must be 0.

Return Value

If successful, returns the following current style bits:

Constant	Description
IES_BORDER	Border drawn around control.
IES_HSCROLL	Horizontally scrollable control.
IES_VSCROLL	Vertically scrollable control.
IES_OWNERDRAW	Application will do all ink drawing.
Otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.


IE_SETAPPDATA

Sets the application data saved in the ink edit control.

Parameters

wParam

Not used; must be 0.

lParam

Data to be saved.

Return Value

Returns the previous contents of the application data area, if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

An application can save any DWORD value with the ink edit control. The control does not use this data. The IE_SETAPPDATA and IE_GETAPPDATA messages provide the only means for an application to interact with the data.

See Also

IE_GETAPPDATA


IE_SETBKGND

Sets the background painting options for the control.

Parameters

wParam

Specifies the background options, as given in the following list:

Constant	Description
IEB_BIT_CENTER	Center bitmap in control. The lParam parameter contains bitmap.
IEB_BIT_STRETCH	Stretch bitmap to fit control. The lParam parameter contains bitmap.
IEB_BIT_TILE	Tile supplied bitmap repeatedly in control. The lParam parameter contains bitmap.
IEB_BIT_UL	Align supplied bitmap to upper-left corner in the control. (UL stands for “upper left.”) The lParam parameter contains bitmap.
IEB_BRUSH	Use brush supplied in lParam.
IEB_DEFAULT	Do default background (use COLOR_WINDOW).
IEB_OWNERDRAW	Parent will draw background.
lParam

Contains a handle to the background bitmap or a brush, or is NULL, according to the specified option in wParam.

Return Value

Returns IER_OK if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

The application can change the background at any time. The control is synchro-nously repainted upon any change.

The HBITMAP or HBRUSH handle, if there is one, becomes the property of the iedit control. The application must make no further use of the handle if the message returns IER_OK. If the IEB_OWNERDRAW option is selected, the parent window must process the IN_ERASEBKGND notification. If an application must place such objects as icons or metafiles in the background, it must do so either in an owner-draw capacity or during the IN_PREPAINT notification.

See Also

IE_GETBKGND, IE_GETGRIDPEN, IE_SETGRIDPEN


IE_SETDRAWOPTS

Sets the ink drawing option.

Parameters

wParam

Contains the drawing option.

Constant	Description
IEDO_FAST	Drawing is done as fast as possible. This is the default setting.
IEDO_NONE	No drawing is done (disabled drawing).
IEDO_SAVEUPSTROKES	Save pen-up strokes in the HPENDATA object.
lParam

Not used; must be 0.

Return Value

Returns IER_OK if successful; the previous draw option is returned in the high-order word; otherwise, returns one of the following:

Constant	Description
IER_PARAMERR	wParam or lParam is invalid.
IER_OWNERDRAW	The control is an owner-draw control; setting draw options is invalid.
IER_SECURITY	The control has security protection disallowing the operation.
Comments

Unlike using the WM_SETREDRAW message, IEDO_NONE controls only the drawing of the ink. The control’s background, grid lines, and so forth are redrawn as usual. By default, pen-up strokes are not saved in the HPENDATA object.


IE_SETERASERTIP

Sets the eraser pen tip.

Parameters

wParam

Not used; must be 0.

lParam

Address of a PENTIP structure.

Return Value

Returns IER_OK if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

The pen tip specified by PENTIP is used for erasing in the control.

See Also

PENTIP, IE_GETERASERTIP


IE_SETFORMAT

Sets the format of a stroke or a set of strokes in an ink edit control.

Parameters

wParam

Not used; must be 0.

lParam

Address of a STRKFMT structure.

Return Value

Returns IER_OK if successful; otherwise, returns one of the following:

Constant	Description
IER_ERROR	Unknown error.
IER_PARAMERR	wParam or lParam is invalid. Also returned when there is an invalid stroke index and the IESF_STROKE option is specified in the iesf member of the STRKFMT structure.
IER_MEMERR	A memory error occurred.
IER_SECURITY	The control has security protection disallowing the operation.
IER_SELECTION	No valid selection with the IESF_SELECTION option in the iesf member of the STRKFMT structure.
Comments

The stroke or strokes indicated by the STRKFMT structure are modified as indicated and repainted (unless drawing has been turned off using the IEDO_NONE bit in IE_SETDRAWOPTS).

The iesf member of the STRKFMT structure contains the IESF_TIPCOLOR or IESF_TIPWIDTH bit flags to selectively adjust the color or width attributes of the ink. This allows setting only the color, for example, while leaving the width unchanged. If the value in iesf has either IESF_TIPCOLOR or IESF_TIPWIDTH set, the ink in the control adopts the new color or width given in the rgb or bwidth members of the PENTIP structure identified in the tip member of STRKFMT.

The caller must initialize the cbSize member of the STRKFMT structure to sizeof( STRKFMT ) before sending this message.

See Also

IE_GETFORMAT, IE_SETDRAWOPTS, STRKFMT


IE_SETGRIDORIGIN

Sets the origin of the rules or grid lines.

Parameters

wParam

Not used; must be 0.

lParam

The low-order word has the x-coordinate of the origin and the high-order word has the y-coordinate of the origin.

Return Value

Returns IER_OK if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

Rules and grids are painted after the background and before the ink (and the IN_PREPAINT notification), and are treated separately from both.

The default setting is for no grid lines. The grid lines act purely as guides for the user; the ink does not interact with the grid in any way. The specification of the grid lines is in the MM_TEXT mapping mode (that is, display pixel).

See Also

IE_GETBKGND, IE_GETGRIDPEN, IE_GETGRIDSIZE, IE_SETGRIDORIGIN, IE_SETGRIDPEN, IE_SETGRIDSIZE, IE_SETBKGND


IE_SETGRIDPEN

Sets the GDI pen for the background rules or grid lines.

Parameters

wParam

Not used; must be 0.

lParam

Contains a handle to a GDI pen used to draw the grid lines.

Return Value

Returns IER_OK if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

Rules and grids are painted after the background and before the ink (and the IN_PREPAINT notification), and are treated separately from both. A GDI pen, if specified, becomes the property of the ink edit control and must not be deleted or otherwise used by the application. If the application needs to change the settings, it must create a new pen each time it sends the IE_SETGRIDPEN message.

The default setting is for no grid lines. The grid lines act purely as guides for the user; the ink does not interact with the grid in any way. The specification of the grid lines is in the MM_TEXT mapping mode (that is, display pixel). If the GDI pen handle is NULL, the ink edit control will use a default pen. (The default pen attributes are a solid line, a width of 1 pixel, and the window grayed text color.) The maximum grid spacing is 255 pixels.

See Also

IE_GETBKGND, IE_GETGRIDORIGIN, IE_GETGRIDPEN, IE_GETGRIDSIZE, IE_SETGRIDORIGIN, IE_SETGRIDSIZE, IE_SETBKGND


IE_SETGRIDSIZE

Sets the vertical and horizontal spacing of the rules or grid lines.

Parameters

wParam

Not used; must be 0.

lParam

The low-order word has the horizontal spacing and the high-order word has the vertical spacing.

Return Value

Returns IER_OK if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

Rules and grids are painted after the background and before the ink (and the IN_PREPAINT notification), and are treated separately from both.

The default setting is for no grid lines. The grid lines act purely as guides for the user; the ink does not interact with the grid in any way. The specification of the grid lines is in the MM_TEXT mapping mode (that is, display pixel).

See Also

IE_GETBKGND, IE_GETGRIDORIGIN, IE_GETGRIDPEN, IE_GETGRIDSIZE, IE_SETGRIDORIGIN, IE_SETGRIDPEN, IE_SETBKGND


IE_SETINK

Sets the contents of an ink edit control.

Parameters

wParam

Contains IESI_REPLACE to replace any existing control contents with the supplied ink, or IESI_APPEND to append the supplied ink to the existing contents of the ink edit control.

lParam

Contains a handle to pen data with which to initialize or reinitialize the contents of the control. If NULL, the contents of the control are cleared; any pen data in the control is discarded.

Return Value

Returns IER_OK if successful; otherwise, returns one of the following:

Constant	Description
IER_PARAMERR	wParam or lParam is invalid.
IER_MEMERR	A memory error occurred.
IER_SECURITY	The control has security protection disallowing the operation.
IER_SCALE	Attempted to merge ink of incompatible scale factors.
Comments

The application can clear or change the contents of the control at any time with this function. During the creation of controls with existing contents, this message might be sent in response to the WM_CTLINIT message.

The HPENDATA handle becomes the property of the control; the application must make no further use of the handle if the message returns success. On a merge operation, the original HPENDATA is destroyed following a successful merge. If the result of IE_SETINK indicates there is no ink left in the control, the mode is reset to IEMODE_READY if the previous mode was either IEMODE_ERASE or IEMODE_LASSO. The corresponding IN_MODECHANGED notification is also sent at this time.

See Also

IE_GETINK


IE_SETINKINPUT

Sets the ink input options for an ink edit control.

Parameters

wParam

Consists of one or two flags specifying the new ink input option. Any one of the following flags can be used as the wParam value. If IEI_MOVE is specified, one (and only one) additional value can combined to indicate a secondary option if all ink will not fit inside the control when moved. For example, the combi-nation IEI_MOVE|IEI_RESIZE specifies to move ink into the control and resize the control to fit if necessary. Bitwise-OR combinations of constants not including IEI_MOVE are not valid.

Constant	Description
IEI_MOVE	Move all ink inside the control.
IEI_RESIZE	Resize all ink to fit inside the control.
IEI_CROP	Crop all ink that falls outside the control.
IEI_DISCARD	Discard all ink if any falls outside the control.
lParam

Not used; must be 0.

Return Value

Returns the previous ink input bits if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

An application can dynamically modify the ink input options. If more than 1 bit is set, the order of priority is as listed in the previous table.

See Also

IE_GETINKINPUT


IE_SETMODE

Sets the control to a particular mode.

Parameters

wParam

Specifies the mode to set the control to, as follows:

Constant	Description
IEMODE_READY	The control is ready for inking, moving strokes, tapping, and so forth.
IEMODE_ERASE	The control is set to erasing mode.
IEMODE_LASSO	The control is set to lasso selection mode.
lParam

Not used; must be 0.

Return Value

Returns one of the following values:

Constant	Description
IER_OK	Success.
IER_PARAMERR	wParam or lParam is invalid.
IER_PENDATA	Attempted to set erase or lasso mode with a null HPENDATA handle in the control.
See Also

IE_GETMODE


IE_SETMODIFY

Sets the modify bit in the control, indicating whether the contents of the control have been modified.

Parameters

wParam

The new value of the modify bit. Must be either TRUE or FALSE.

lParam

Not used; must be 0.

Return Value

Returns IER_OK if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

The modify bit is set in the control whenever the user takes some action that changes the ink in the control. Such actions include drawing new ink, erasing, pasting, changing attributes, and moving ink. Note that calling a function to change the contents of the control also sets the modify bit.

To preserve the value of the modify bit during some modifying action, the appli-cation must first retrieve the bit’s value with IE_GETMODIFY, then restore the value after completing the action.

This command succeeds regardless of the security setting.

See Also

IE_GETMODIFY


IE_SETNOTIFY

Sets the notification options for an ink edit control.

Parameters

wParam

Consists of flags specifying the kinds of notifications required:

Constant	Description
IEN_EDIT	Require notifications of editing or command events. Notifications sent: IN_CHANGE, IN_UPDATE, IN_GESTURE, IN_COMMAND.
IEN_FOCUS	Require notifications of focus events. Notifications sent: IN_SETFOCUS, IN_KILLFOCUS.
IEN_PAINT	Require notifications of painting events. Notifications sent: IN_PREPAINT, IN_POSTPAINT.
IEN_PDEVENT	Require notifications of pointing-device events (clicks and taps). Notification sent: IN_PDEVENT.
IEN_PROPERTIES	Require notifications before bringing up the properties dialog box. Notification sent: IN_PROPERTIES.
IEN_SCROLL	Require notifications of scrolling events. Notifications sent: IN_HSCROLL, IN_VSCROLL.
lParam

Not used; must be 0.

Return Value

Returns the previous notification bits if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

An application can dynamically modify the kinds of notifications and the frequency with which they are generated.

Unless otherwise specified, the parent window receives no notifications beyond the default messages sent by Windows to the parent of a child window.

See Also

IE_GETNOTIFY


IE_SETPENTIP

Sets the default ink pen tip.

Parameters

wParam

Not used; must be 0.

lParam

Address of a PENTIP structure.

Return Value

Returns IER_OK if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

The pen tip specified by PENTIP is used for all default inking in the control. Note that the new pen tip applies only to new ink entered into the control. It does not change the attributes of existing ink in the control.

See Also

PENTIP, IE_GETPENTIP


IE_SETRECOG

Sets the recognition options of the control.

Parameters

wParam

Contains bits designating the new recognition options, as listed here:

Constant	Description
IEREC_ALL	All recognition enabled.
IEREC_GESTURE	Gesture recognition enabled.
IEREC_NONE	Recognition disabled.
lParam

Not used; must be 0.

Return Value

Returns the previous recognition bits if successful; otherwise, returns IER_PARAMERR to indicate that wParam or lParam is invalid.

Comments

By default, all recognition is enabled. Currently, IEREC_GESTURE and IEREC_ALL are equivalent.

See Also

IE_GETRECOG


IE_SETSECURITY

Sets the security options of the control.

Parameters

wParam

Contains the new security bits. The high-order word is unused and must be 0. The security flags can be combined using the bitwise-OR operator.

Constant	Description
IESEC_NOCOPY	Copying not allowed.
IESEC_NOCUT	Cutting, deleting, and clearing not allowed.
IESEC_NOPASTE	Pasting disabled.
IESEC_NOUNDO	Undo not permitted.
IESEC_NOINK	Inking not allowed.
IESEC_NOERASE	Erasing not allowed.
IESEC_NOGET	The IE_GETINK message is disabled.
IESEC_NOSET	The IE_SETINK message is disabled.
lParam

Not used; must be 0.

Return Value

Returns the previous security bits if successful; otherwise, returns one of the following:

Constant	Description
IER_PARAMERR	wParam or lParam is invalid.
IER_SECURITY	The control has security protection disallowing the operation.
See Also

IE_GETSECURITY


IE_SETSEL

Sets the selection status of a particular stroke.

Parameters

wParam

Contains the zero-based index of the stroke whose selection status is to be set. A value of IX_END sets the selection status of all the strokes in the control.

lParam

lParam is TRUE to select the stroke or FALSE to remove the selection. Other values produce an IER_PARAMERR return value.

Return Value

Returns one of the following values:

Constant	Description
IER_YES	The stroke was previously selected.
IER_NO	The stroke was not previously selected.
IER_PARAMERR	wParam or lParam is invalid.
Comments

This message affects the selection status of only the specified stroke. The selection status of other strokes remains unchanged.

See Also

IE_GETSEL


IN_CHANGE

Sent after the contents of the control have been modified and repainted.

The control’s parent window receives this notification message through a WM_COMMAND message if the IEN_EDIT bit has been set using the IE_SETNOTIFY message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the iedit control in the low-order word and the IN_CHANGE notification message in the high-order word.

See Also

IE_SETNOTIFY


IN_CLOSE

Sent when the control is closing and about to be destroyed.

The control’s parent window receives this notification message through a WM_COMMAND message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the iedit control in the low-order word and the IN_CLOSE notification message in the high-order word.

Return Value

The application should return TRUE to prevent the control from being closed or FALSE for default handling.


IN_COMMAND

Sent when the user has selected an item from the pop-up menu.

The control’s parent window receives this notification message through a WM_COMMAND message if the IEN_EDIT bit has been set using the IE_SETNOTIFY message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the iedit control in the low-order word and the IN_COMMAND notification message in the high-order word.

Return Value

The application should return TRUE to discard the command selection or FALSE for default processing.

Comments

The application can retrieve details about the selection by using the IE_GETCOMMAND message.

See Also

IE_GETCOMMAND, IE_SETNOTIFY


IN_ERASEBKGND

Sent to the parents of ink edit controls that have the IEB_OWNERDRAW option to request the painting of the control background.

The control’s parent window receives this notification message through a WM_COMMAND message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the ink edit control in the low-order word and the IN_ERASEBKGND notification message in the high-order word.

Comments

The application should use the IE_GETPAINTDC message to retrieve such information as the correct device context and clipping region.

See Also

IE_GETPAINTDC


IN_GESTURE

Sent when the user has performed a gesture in the iedit control.

The control’s parent window receives this notification message through a WM_COMMAND message if the IEN_EDIT bit has been set using the IE_SETNOTIFY message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the ink edit control in the low-order word and the IN_GESTURE notification message in the high-order word.

Return Value

The application should return TRUE to discard the gesture or FALSE for default processing.

Comments

An application can retrieve details about the gesture by using the IE_GETGESTURE message.

See Also

IE_SETNOTIFY


IN_HSCROLL

The IN_HSCROLL notification message is sent when the user has clicked the ink edit control’s horizontal scroll bar.

The control’s parent window receives this notification message through a WM_COMMAND message if the IEN_SCROLL bit has been set using the IE_SETNOTIFY message. This bit is set by default and should be cleared if the control’s parent does not require this notification message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the ink edit control in the low-order word and the IN_HSCROLL notification message in the high-order word.

Return Value

The application should return TRUE to discard the scrolling request.

See Also

IE_SETNOTIFY


IN_KILLFOCUS

Sent to inform the parent window that the control is losing the focus.

The control’s parent window receives this notification message through a WM_COMMAND message if the IEN_FOCUS bit has been set using the IE_SETNOTIFY message. This bit is set by default and should be cleared if the control’s parent does not require this notification message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the iedit control in the low-order word and the IN_KILLFOCUS notification message in the high-order word.

Return Value

The application should return TRUE to prevent the control from losing the focus.

See Also

IE_SETNOTIFY


IN_MEMERR

Sent when the system is unable to satisfy a memory request made by the control.

The control’s parent window receives this notification message through a WM_COMMAND message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the ink edit control in the low-order word and the IN_MEMERR notification message in the high-order word.

Return Value

The application should return TRUE to retry the operation (generally after it frees memory). If it returns TRUE and the control still cannot perform the memory operation, another IN_MEMERR notification is generated.

Comments

The ink edit control does not display an error message of any kind. Any such error messages must be displayed by the application.


IN_MODECHANGED

Sent after the control mode has changed.

The control’s parent window receives this notification message through a WM_COMMAND message if the IEN_EDIT bit has been set using the IE_SETNOTIFY message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the ink edit control in the low-order word and the IN_MODECHANGED notification message in the high-order word.

See Also

IE_SETNOTIFY, IE_GETMODE, IE_SETMODE


IN_PAINT

Sent to the parent window of an owner-draw ink edit control to indicate that the control should be painted.

The control’s parent window receives this notification message through a WM_COMMAND message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the ink edit control in the low-order word and the IN_PAINT notification message in the high-order word.

Comments

The application should use the IE_GETPAINTDC message to retrieve the details of the required painting.

See Also

IE_GETPAINTDC


IN_PDEVENT

Sent when a pointing-device transition event (such as a tap, up-click, or double-tap) occurs.

The control’s parent window receives this notification message through a WM_COMMAND message if the IEN_PDEVENT bit has been set using the IE_SETNOTIFY message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the ink edit control in the low-order word and the IN_PDEVENT notification message in the high-order word.

Return Value

The application should return TRUE to discard the event, or FALSE for normal processing.

Comments

The application can retrieve a PDEVENT structure describing the event by sending the IE_GETPDEVENT message.

See Also

IE_GETPDEVENT, IE_SETNOTIFY


IN_POSTPAINT

Sent to inform the parent that painting is finished.

The control’s parent window receives this notification message through a WM_COMMAND message if the IEN_PAINT bit has been set using the IE_SETNOTIFY message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the ink edit control in the low-order word and the IN_POSTPAINT notification message in the high-order word.

Comments

The application can send the IE_GETPAINTDC message to retrieve a device con-text with the correct clipping region to perform any additional painting on top of the ink edit control.

See Also

IE_GETPAINTDC, IE_SETNOTIFY


IN_PREPAINT

Sent just before the control paints the ink.

The control’s parent window receives this notification message through a WM_COMMAND message if the IEN_PAINT bit has been set using the IE_SETNOTIFY message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the ink edit control in the low-order word and the IN_PREPAINT notification message in the high-order word.

Comments

The application can send the IE_GETPAINTDC message to retrieve a device context with the correct clipping region to perform any additional painting before the ink edit control paints.

See Also

IE_GETPAINTDC, IE_SETNOTIFY


IN_PROPERTIES

Signals the iedit control’s standard Properties dialog box is about to be displayed on the screen.

The control’s parent window receives the IN_PROPERTIES notification message through a WM_COMMAND message if the IEN_PROPERTIES bit has been set using the IE_SETNOTIFY message. This bit is set by default and should be cleared if the control’s parent does not require this notification message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the ink edit control in the low-order word and the IN_PROPERTIES notification message in the high-order word.

Return Value

The application should return TRUE to avoid displaying the iedit control’s standard Properties dialog box.

See Also

IE_SETNOTIFY


IN_SETFOCUS

Sent to inform the parent window that the control is gaining the focus.

The control’s parent window receives this notification message through a WM_COMMAND message if the IEN_FOCUS bit has been set using the IE_SETNOTIFY message. This bit is set by default and should be cleared if the control’s parent does not require this notification message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the ink edit control in the low-order word and the IN_SETFOCUS notification message in the high-order word.

Return Value

The application should return TRUE to prevent acquiring the focus.

See Also

IE_SETNOTIFY


IN_UPDATE

Sent when the contents of the control have been modified but not yet repainted.

The control’s parent window receives this notification message through a WM_COMMAND message if the IEN_EDIT bit has been set using the IE_SETNOTIFY message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the ink edit control in the low-order word and the IN_UPDATE notification message in the high-order word.

See Also

IE_SETNOTIFY


IN_VSCROLL

Sent when the user has clicked the ink edit control’s vertical scroll bar.

The control’s parent window receives this notification message through a WM_COMMAND message if the IEN_SCROLL bit has been set using the IE_SETNOTIFY message. This bit is set by default and should be cleared if the control’s parent does not require this notification message.

Parameters

wParam

Specifies the identifier of the ink edit control.

lParam

Specifies the handle of the ink edit control in the low-order word and the IN_VSCROLL notification message in the high-order word.

Return Value

The application should return TRUE to discard the scrolling request.

See Also

IE_SETNOTIFY


PE_BEGINDATA

Sent to the window specified by the htrgTarget member of the TARGET structure the first time any pen data is directed toward that window. Submessage of WM_PENEVENT.

Parameters

wParam

PE_BEGINDATA

lParam

Address of a TARGET structure.

Comments

A target window can initialize the dwData member of the TARGET structure with a handle to pen data (HPENDATA), a handwriting recognition object (HRC), or some private data type. If dwData is an HPENDATA object, the HPENDATA object should be in standard scale with no OEM data. For example, the HPENDATA object can be created as follows:

CreatePenDataEx(NULL, PDTS_STANDARDSCALE, CPD_TIME, 0);

The target window informs Windows of the type of data in the dwData member of the TARGET structure by returning LRET_HPENDATA, LRET_HRC, or LRET_PRIVATE (or LRET_DONE). If the application lets the message fall down to the Windows DefWindowProc function, then the function creates a handwriting recognition object (HRC) for this target.

The window can ignore all input except gestures. In this case, it must create a handwriting recognition object and customize it to recognize only gestures.

For an example of how an application can handle PE_BEGINDATA, see the source code for PENAPP.C in Chapter 7, “A Sample Pen Application.”

See Also

TARGET, WM_PENEVENT


PE_BEGININPUT

Begins default input processing. Submessage of WM_PENEVENT.

Parameters

wParam

PE_BEGININPUT

lParam

The high-order word is the handle of the window in which the pen first touched down, and the low-order word is the event reference identifier returned from GetMessageExtraInfo.

Return Value

Returns PCMR_OK if successful; otherwise, it returns one of the following values:

Constant	Description
PCMR_ALREADYCOLLECTING	StartPenInput has already been called for this session.
PCMR_APPTERMINATED	The application terminated input.
PCMR_ERROR	Parameter or unspecified error.
PCMR_INVALID_PACKETID	A packet identifier is invalid.
PCMR_SELECT	Press-and-hold action was detected. Collection is not started.
PCMR_TAP	A tap was detected. Collection is not started.
Comments

A control can initiate default pen-input processing by sending this message to its parent. If the parent allows the message to be processed by passing it to DefWindowProc, default pen-input behavior begins. The DoDefaultPenInput function uses this technique.

For further information about default processing, refer to Chapter 2, “Starting Out with System Defaults.”

See Also

DoDefaultPenInput, WM_PENEVENT


PE_BUFFERWARNING

Generated by the pen driver component of the system when the input queue is approximately half full. When an application receives PE_BUFFERWARNING, it should immediately call GetPenInput to drain the input queue. Submessage of WM_PENEVENT.

Parameters

wParam

PE_BUFFERWARNING.

lParam

Extra information encapsulating a reference to the event and the HPCM that generated it. Applications can use the EventRefFromWpLp and HpcmFromWpLp macros to retrieve these values.

Comments

If an application receives this message, it has fallen behind in processing the input. The buffer is in danger of overflowing. The application should repeatedly call GetPenInput to gather the unprocessed pen input.

See Also

GetPenInput, WM_PENEVENT


PE_ENDDATA

Sent at the termination of pen input to all windows specified by the htrgTarget member of the TARGET structure that have received a PE_BEGINDATA message. Submessage of WM_PENEVENT.

Parameters

wParam

PE_ENDDATA.

lParam

Address of a TARGET structure.

Comments

A target can inform the recognizer that pen input has ended and process the HRC in response to this message. If this message is allowed to fall through to the DefWindowProc function, default result processing is done if the value in the dwData member of the TARGET structure is of type HRC. EndPenInput is called followed by a call to ProcessHRC. Then the PE_RESULT submessage is sent to the target to allow the target to get results and process them.

If the dwData member of the TARGET structure has the HPENDATA or HRC type, the object is destroyed by DefWindowProc on completion of results processing.

See Also

TARGET, WM_PENEVENT


PE_ENDINPUT

Sent to indicate that the default collection has terminated. Submessage of WM_PENEVENT.

Parameters

wParam

PE_ENDINPUT.

lParam

Not used.

See Also

WM_PENEVENT


PE_GETINKINGINFO

Fills an INKINGINFO structure. Submessage of WM_PENEVENT.

Parameters

wParam

PE_GETINKINGINFO.

lParam

Address of an INKINGINFO structure, which is initialized with default values.

Return Value

The targeted windows in the application should return 1 to customize inking information. A return value of 0 results in default inking behavior.

Comments

Before beginning default pen input, Windows sends PE_GETINKINGINFO to all the windows specified by the htrgTarget member of the TARGET structure. (The TARGET structure is part of the TARGINFO structure created during processing of the earlier PE_SETTARGETS messages.)

The default values are the same as those used when StartInking is called with lpinkinginfo set to NULL, but the PII_SAVEBACKGROUND flag is forced on in the wFlags member of the INKINGINFO structure to automatically save and restore the inking background.

The hrgnClip member of the INKINGINFO structure temporarily contains the index of the target in the TARGINFO structure retrieved by the PE_SETTARGETS message. Note that this is an overloading of this member to identify the targets. If the htrgTarget window specified in the TARGET structure returns 1 to this message, the following actions are taken:

•	If both the PII_INKPENTIP and PII_RECTCLIP flags are set, the pen tip specified by the tip member of the INKINGINFO structure is saved and used whenever the pen goes down within the area defined by the rectClip member. In most cases, the ink color changes at or near the clipping boundary, even when the pen is dragged over it. Because inking is done on a per-segment basis, there may be a slight overlap of color near a common boundary.

•	If the width given in the tip member is 0, no ink will appear within the area specified by the rectClip member. Password fields can be implemented using this technique.

•	If the PII_SAVEBACKGROUND flag is clear (0), any ink dropped within the area specified by the rectClip member is not removed at the termination of the collection. The ink edit control, for example, uses this technique. However, the parent window can override this default behavior when it finally receives a PE_GETINKINGINFO message after all its targets have been called.

•	If the PII_INKSTOP flag is set, the rectInkStop member is folded into the region specified by the hrgnInkStop member, which is used in calls to the StartInking function. When inking stops due to a pen-down event in the rectInkStop rectangle, a WM_PENMISC message with the PMSC_INKSTOP submessage is sent to the window specified by the htrgTarget member of the TARGET structure. lParam is the same as in the PE_PENDOWN message that caused the inking to stop. As with PII_SAVEBACKGROUND, hwnd can override the preprocessed values accumulated by the targets.

For further information about PE_GETINKINGINFO, see Chapter 2, “Starting Out with System Defaults.”

See Also

INKINGINFO, PE_SETTARGETS, StartInking, TARGET, TARGINFO, WM_PENEVENT


PE_GETPCMINFO

Fills a PCMINFO structure, which is then used in a call to StartPenInput. Submessage of WM_PENEVENT.

Parameters

wParam

PE_GETPCMINFO.

lParam

Address of a PCMINFO structure, which is initialized with default values.

Comments

The default values are the same as those applied when StartPenInput is called with the lppcminfo parameter set to NULL:

•	Inking terminates when the time-out period elapses.

•	Inking terminates when a tap occurs outside the client rectangle of hwnd.

•	Inking does not start if the initial pen input consists of a press-and-hold gesture.

However, an exclusion region specified by the hrgnExclude member of the PCMINFO structure may have accumulated while processing PE_SETTARGETS messages. The window procedure can modify the values to customize the collection parameters before pen input begins.

If the PCM_DOPOLLING flag in the dwPcm member of the PCMINFO structure is set, it is disregarded and pen input remains in event mode.

See Also

PCMINFO, PE_SETTARGETS, StartPenInput, WM_PENEVENT


PE_MOREDATA

Sent to the window specified by the htrgTarget member of the TARGET structure to indicate that more pen data is available for that window. Submessage of WM_PENEVENT.

Parameters

wParam

PE_MOREDATA.

lParam

Address of an INPPARAMS structure.

Comments

DefWindowProc collects the pen input in response to the PE_PENDOWN, PE_PENUP, and PE_PENMOVE messages and sends the input on a stroke-by-stroke basis to one of the targets in the TARGINFO structure. On a pen-tip transition—that is, from pen-down to pen-up or vice versa — the Windows DefWindowProc function sends a PE_MOREDATA message to the window specified by the htrgTarget member of the TARGET structure identified in the PE_BEGINDATA message.

If it receives a PE_MOREDATA message, DefWindowProc uses AddPointsPendata or AddPenInputHRC, or does nothing, depending on whether the data type in the dwData member of the TARGET structure is a handle to an HPENDATA, an HRC handle for handwriting recognition, or some private data type.

See Also

AddPenInputHRC, AddPointsPendata, INPPARAMS, PE_PENMOVE, PE_PENDOWN, PE_PENUP, TARGET, TARGINFO, WM_PENEVENT


PE_PENDOWN

Generated by the pen driver component of the system when the pen tip touches the tablet surface. Submessage of WM_PENEVENT.

Parameters

wParam

PE_PENDOWN.

lParam

Extra information encapsulating a reference to the event and the HPCM that generated it. Applications can use the EventRefFromWpLp and HpcmFromWpLp macros to retrieve these values.

See Also

WM_PENEVENT


PE_PENMOVE

Generated by the pen driver component of the system when the pen moves, forcing more packets into the input queue. Submessage of WM_PENEVENT.

Parameters

wParam

PE_PENMOVE.

lParam

Extra information encapsulating a reference to the event and the HPCM that generated it. Applications can use the EventRefFromWpLp and HpcmFromWpLp macros to retrieve these values.

Comments

This message is analogous to WM_MOUSEMOVE. It provides notification that the pen is moving. Like its mouse counterpart, PE_PENMOVE messages are coalesced so that only a single such message exists in the application’s message queue. How-ever, the event the message represents is the first of these coalesced events, not the last event, as is the case with WM_MOUSEMOVE.

An application need not handle this message if transition events like PE_PENUP and PE_PENDOWN are sufficient notification. PE_PENMOVE is useful when an application must monitor pen movement with greater frequency than PE_PENUP or PE_PENDOWN allows.

See Also

WM_PENEVENT


PE_PENUP

Generated by the pen driver component of the system when the pen tip leaves the tablet surface. Submessage of WM_PENEVENT.

Parameters

wParam

PE_PENUP.

lParam

Extra information encapsulating a reference to the event and the HPCM that generated it. Applications can use the EventRefFromWpLp and HpcmFromWpLp macros to retrieve these values.

See Also

WM_PENEVENT


PE_RESULT

During the processing of the PE_ENDDATA submessage, sent to all windows specified by the htrgTarget member of the TARGET structure that have received a PE_BEGINDATA message. PE_RESULT applies only to recognition and is sent only if the value in the dwData member of the TARGET structure is of type HRC. Submessage of WM_PENEVENT.

Parameters

wParam

PE_RESULT.

lParam

HRC object for the recognition session.

Comments

A target can perform recognition-result processing in response to PE_RESULT. If it receives this message, the Windows DefWindowProc function performs default result processing. The first HRCRESULT object for the HRC is obtained using the GetResultsHRC function. The HRCRESULT handle is used to retrieve a string of symbols that are converted, one by one, into characters. The characters are then posted as WM_CHAR messages to the window specified by the htrgTarget member of the TARGET structure.

The clear, cut, copy, paste, and undo gestures are converted to WM_CLEAR, WM_CUT, WM_COPY, WM_PASTE, and WM_UNDO messages. They are posted to the htrgTarget target, together with appropriate mouse messages, so that the target can perform appropriate processing (such as selection) before applying the gestures.

See Also

TARGET, WM_PENEVENT


PE_SETTARGETS

Sent to an application window so that it can set its own targeting structure. Submessage of WM_PENEVENT.

Parameters

wParam

PE_SETTARGETS.

lParam

Address of a far pointer to a TARGINFO structure. (Note that lParam is a pointer to a pointer.)

Return Value

The application should return LRET_DONE to indicate that it has set up the targeting information for the child windows. A return of 0 indicates that the application is the only target. The application can also return LRET_ABORT to abort the targeting process altogether.

Comments

The DefWindowProc function enumerates all the descendants of the window specified in its first parameter and sends each one a PE_GETPCMINFO message. For every descendant that returns 1 to this message, the PCM_RECTBOUND and PCM_RECTEXCLUDE flags of the PCMINFO structure are examined. If the PCM_RECTBOUND flag is set, the descendant is included in the list of potential targets and the rectBound member in PCMINFO is copied to the rectBound member of the TARGET structure. If the PCM_RECTEXCLUDE flag is set, the rectExclude member of PCMINFO is added to an exclusion region that is passed (as the hrgnExclude member of the PCMINFO structure) to the StartInput call. If there are no descendants, or if the window procedure of hwnd returns 0, a TARGINFO structure is constructed with hwnd as the single target.

For default processing behavior, the application should allow PE_SETTARGETS to fall through to DefWindowProc. A PE_GETPCMINFO message will follow to establish targets or termination conditions (buttons, for example).

For further information about PE_SETTARGETS, see Chapter 2, “Starting Out with System Defaults.”

An application can replace the default targeting with a set of targets it defines itself. In this case, the application allocates enough memory for the TARGINFO structure plus all the TARGET structures.

Example

The following example illustrates how to handle PW_SETTARGETS for n targets, where each target is in the array rgHwnd. Notice the code increases the allocation by n−1 TARGET structures, since TARGINFO already contains one TARGET structure.

DWORD cbAlloc         = sizeof(TARGINFO) + (n-1) * sizeof(TARGET);

HGLOBAL hTargets      = GlobalAlloc( GHND, cbAlloc );

LPTARGINFO lptarginfo = GlobalLock( hTargets );

lptarginfo->cbSize    = sizeof(TARGINFO);

lptarginfo->cTargets  = n;                   // Number of targets

lptarginfo->htrgOwner = HtrgFromHwnd(hwnd);  // Macro in penwin.h

lptarginfo->dwFlags   = TPT_TEXTUAL;         // For text

for (i = 0; i < n; i++)

{

HWND hwnd = (HTRG)rgHwnd[i];	// Window of this target

lptarginfo->rgTarget[i].dwFlags    = 0;	// Reserved

lptarginfo->rgTarget[i].idTarget   = i;

lptarginfo->rgTarget[i].htrgTarget = HtrgFromHwnd(hwnd);

lptarginfo->rgTarget[i].dwData = 0;

// Use screen coords of each window:

  {

// Note: rectBound is a RECTL. In 16-bit code, one has to assign each

// field separately. In 32-bit code, you can use the rectBound directly.

  RECT rect;

GetClientRect( hwnd, &rect);

ClientToScreen( hwnd, (LPPOINT)&rectBound.left);

ClientToScreen( hwnd, (LPPOINT)&rectBound.right);

  lptarginfo->rgTarget[i].rectBound.left = rect.left;

  lptarginfo->rgTarget[i].rectBound.top = rect.top;

  lptarginfo->rgTarget[i].rectBound.right = rect.right;

  lptarginfo->rgTarget[i].rectBound.bottom = rect.bottom;

  }

}

// Return our structures:

*(LPTARGINFO FAR *)lParam = lptarginfo;

See Also

PCMINFO, TARGET, TARGINFO, WM_PENEVENT


PE_TERMINATED

Generated by the pen driver component of the system when pen input terminates. Submessage of WM_PENEVENT.

Parameters

wParam

PE_TERMINATED.

lParam

Extra information encapsulating a reason for termination and the current HPCM. Applications can use the TerminationFromWpLp and HpcmFromWpLp macros to retrieve these values.

Comments

When an application receives the PE_TERMINATED message, collection has already terminated and the HPCM handle returned from StartPenInput has become invalid. PE_TERMINATED indicates an application should perform such tasks as final results processing, repainting, and cleanup.

See Also

WM_PENEVENT


PE_TERMINATING

Generated by the pen driver component of the system when pen input is about to terminate. Submessage of WM_PENEVENT.

Parameters

wParam

PE_TERMINATING.

lParam

Extra information encapsulating a reason for termination and the current HPCM. Applications can use the TerminationFromWpLp and HpcmFromWpLp macros to retrieve these values.

Comments

When it receives PE_TERMINATING, the application must immediately retrieve any remaining points.

See Also

WM_PENEVENT


WM_CTLINIT

Sent to the parent of a bedit, hedit, or iedit control while the control is being created in order to get extra information about the control.

Parameters

wParam

Type of control. This parameter can be CTLINIT_BEDIT, CTLINIT_IEDIT, or CTLINIT_HEDIT.

lParam

Address of a control structure, depending on wParam. For values of CTLINIT_BEDIT, CTLINIT_HEDIT, or CTLINIT_IEDIT in wParam, lParam points to either a CTLINITBEDIT, CTLINITHEDIT, or CTLINITIEDIT structure, respectively.

Comments

Each of the CTLINIT structures has its first three members already initialized: cbSize (size of the structure), hwnd (handle to the control window), and id (child identifier of the control). The parent of the control can set appropriate values to the rest of the members in the structure and the control will then use those values when initializing itself.

See Also

CTLINITHEDIT, CTLINITBEDIT, CTLINITIEDIT


WM_GLOBALRCCHANGE

See WM_PENMISCINFO.


WM_HOOKRCRESULT

Sent to a window before WM_RCRESULT is sent to the target window.

The WM_HOOKRCRESULT message is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions.

Parameters

wParam

REC_ code indicating why recognition ended.

lParam

Address of an RCRESULT structure.

Comments

The application may examine the results in the RCRESULT structure. Changing any of the values leads to unpredictable results. The application should make a copy of any information it needs.

See Also

RCRESULT, SetRecogHook, WM_RCRESULT


WM_PENCTL

Performs several actions, including:

•	Converts a logical character position to a byte offset.

•	Converts a byte offset to a logical character position.

•	Switches the font in a bedit control to the default font.

Parameters

wParam

Submessage identifier as described in the following table. Each submessage is documented separately.

Constant	Description
HE_CANCELCONVERT	Cancels Kana-to-Kanji conversion. (Japanese version only.)
HE_CHAROFFSET	Converts logical character position of a character in the control to byte offset to the character. For bedit controls only.
HE_CHARPOSITION	Converts byte offset in the text buffer of the control to the logical character position, which contains the byte specified by the byte offset. For bedit controls only.
HE_DEFAULTFONT	Switches the font of the bedit control to the default font that the bedit selects at the time of creation. For bedit controls only.
HE_ENABLEALTLIST	Enables or disables the alternate list in a bedit control.
HE_FIXKKCONVERT	Confirm undetermined string and close Input Method Editor (IME). (Japanese version only.)
HE_GETBOXLAYOUT	Points to the BOXLAYOUT structure, which is filled with the current box layout for the control. For bedit controls only.
HE_GETCONVERTRANGE	Gets the range of the marked conversion string. (Japanese version only.)
HE_GETINFLATE	LPRECTOFS filled with current value.
HE_GETINKHANDLE	Retrieves a handle to the captured ink.
HE_GETKKCONVERT	Determines if the Input Method Editor (IME) is in pen (or keyboard) conversion mode. (Japanese version only.)
HE_GETKKSTATUS	Determines the mode of the Kana-to-Kanji conversion. (Japanese version only.)
HE_GETRC	Fills an RC structure, whose address is passed in the lParam, with current values. See the note that follows.
HE_GETUNDERLINE	Queries whether underline mode is set. For hedit controls only.
HE_HIDEALTLIST	Hides the alternate list in a bedit control, assuming it is being displayed.
HE_KKCONVERT	Starts Kana-to-Kanji conversion. (Japanese version only.)
HE_PUTCONVERTCHAR	Sends a character, marked for conversion, to the IME. (Japanese version only.)
HE_SETBOXLAYOUT	Sets a BOXLAYOUT structure. For bedit controls only.
HE_SETCONVERTRANGE	Sets the range of the marked conversion string. (Japanese version only.)
HE_SETINFLATE	Specifies adjustments to the control window to specify the size of the writing window.
HE_SETINKMODE	Starts the collection of inking.
HE_SETRC	Sets the RC structure, whose address is passed in the lParam. See the note that follows.
HE_SETUNDERLINE	Sets or cancels underline mode. For hedit controls only.
HE_SHOWALTLIST	Displays the alternate list menu in a bedit control, assuming that alternate lists are enable.
HE_STOPINKMODE	Stops the collection of ink.
The HE_GETRC and HE_SETRC submessages are provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions.

lParam

Depends on wParam. See the individual HE_ submessage descriptions for more information.

Comments

Any control message (a message with the EM_ prefix) that can be sent to an edit control can also be sent to an hedit window. Most of these control messages are also supported by bedit controls.

The HE_ submessages are also common to both hedit and bedit controls except as noted in the preceding table. In a bedit control, each cell contains one logical character. Carriage return (CR) and line-feed (LF) bytes together form one logical character.

Before using the HE_SETBOXLAYOUT or HE_SETINFLATE submessages, it is often useful to retrieve the current structure associated with the control using the HE_GETBOXLAYOUT or HE_GETINFLATE submessages. You should then change the appropriate members in the retrieved structure. This procedure reduces the risk of inadvertent changes to the structure.

In older applications compatible with version 1.0 of the Pen API, placing the value RRM_SYMBOL in wResultMode of the RC structure disables all default diction-ary processing in a bedit control. The 1.0 application can perform dictionary pro-cessing on its own by retrieving the recognition results during the processing of the HN_RESULT notification and calling the DictionarySearch function.

See Also

HE_CANCELCONVERT, HE_CHAROFFSET, HE_CHARPOSITION, HE_DEFAULTFONT, HE_ENABLEALTLIST, HE_FIXKKCONVERT, HE_GETBOXLAYOUT, HE_GETIMEDEFAULT, HE_GETINFLATE, HE_GETINKHANDLE, HE_GETKKCONVERT, HE_GETKKSTATUS, HE_GETUNDERLINE, HE_SETBOXLAYOUT, HE_SETIMEDEFAULT, HE_SETINFLATE, HE_SETINKMODE, HE_SETUNDERLINE, HE_SHOWALTLIST, HE_STOPINKMODE


WM_PENEVENT

Sent to an application after StartPenInput has initiated a pen collection.

Parameters

wParam

Submessage identifier as described in the following table. Each submessage is documented separately.

Constant	Description
PE_BEGINDATA	Initialization message to all targets.
PE_BEGININPUT	Begin default input.
PE_BUFFERWARNING	The input queue is getting full. The application should call GetPenInput.
PE_ENDDATA	Termination message to all targets.
PE_RESULT	Recognition result message to all targets.
PE_ENDINPUT	Input termination message to window.
PE_GETINKINGINFO	Get inking information.
PE_GETPCMINFO	Get input collection information.
PE_MOREDATA	Target gets more data.
PE_PENMOVE	The pen moved, placing more packets into the input queue without a tip transition. This mes-sage is coalesced with other PE_PENMOVE messages, so the Windows queue has only a single such message waiting.
PE_PENDOWN	The pen tip went down.
PE_PENUP	The pen tip went up.
PE_SETTARGETS	Set TARGINFO target data structure.
PE_TERMINATED	Pen input terminated. The HPCM handle for the current collection has become invalid.
PE_TERMINATING	Pen input is about to terminate. The application must retrieve any remaining points immediately.
lParam

Depends on wParam. In most cases, this is extra information encapsulating a reference to the event and the HPCM that generated it. These are retrieved using the EventRefFromWpLp and HpcmFromWpLp macros.

Comments

This message is not sent if polling is used—that is, if the dwPcm member of the PCMINFO structure contains the PCM_DOPOLLING flag.

See Also

GetPenInput, StartPenInput, TARGINFO


WM_PENMISC

Sent to notify an application of some pen-related change, such as a change in a bedit control. WM_PENMISC is also used to get information from a window about pen-related attributes.

Parameters

wParam

One of the following subfunctions:

PMSC_BEDITCHANGE

Indicates that system settings for bedit controls have been changed. When it receives this message, a bedit control updates its state according to the settings indicated by the BOXEDITINFO structure that lParam points to.

PMSC_GETHRC

Return a copy of the HRC handle associated with the window. lParam is unused and should be set to 0. If a window has no associated HRC structure, NULL is returned. It is the caller’s responsibility to destroy any HRC the message returns.

PMSC_GETINKINGINFO

Retrieve the INKINGINFO structure associated with the window and copy it to the structure pointed to by lParam. The message is ignored if lParam is NULL.

PMSC_GETPCMINFO

Retrieve the PCMINFO structure associated with the window and copy it to the structure pointed to by lParam. If a window has no associated PCMINFO structure, NULL is returned. The message is ignored if lParam is NULL. The system initializes PCMINFO as follows:

•	dwPcm is a combination of the PCM_RECTBOUND, PCM_TIMEOUT, and PCM_TAPNHOLD flags.

•	rectBound is the client area of hwnd, in screen coordinates.

•	dwTimeout is the current writing time-out in milliseconds, as reported by GetPenMiscInfo using PMI_TIMEOUT.

•	All other members are 0.

PMSC_INKSTOP

Inking has stopped because of a pen-down event. lParam contains the HPCM handle corresponding to the collection and the event reference at which the inking stopped. An application can retrieve these values with the HpcmFromWpLp and EventRefFromWpLp macros, respectively.

PMSC_KKCTLENABLE

WM_PENMISC is broadcast when kana-kanji controls are enabled. (Japanese version only.)

PMSC_LOADPW

WM_PENMISC is broadcast when PENWIN.DLL loads or unloads. lParam is one of the following:

•	PMSCL_LOADED (PENWIN.DLL just loaded).

•	PMSCL_UNLOADED (PENWIN.DLL just unloaded).

•	PMSCL_UNLOADING (PENWIN.DLL is about to unload).

PMSC_PENUICHANGE

Broadcast to indicate that the pen user interface DLL (PENUI) has been changed. (Japanese version only.)

PMSC_SETHRC

Associate the HRC handle in lParam with the window. The window makes a copy of the HRC for itself so that the sender of the message can destroy its copy. Returns nonzero if successful; otherwise, returns 0.

PMSC_SETINKINGINFO

Associate the INKINGINFO structure pointed to by lParam with the window. Returns nonzero if successful; otherwise, returns 0.

PMSC_SETPCMINFO

Associate the PCMINFO structure pointed to by lParam with the window. The cbSize member of the structure must be initialized with sizeof( PCMINFO ). Returns nonzero if successful; otherwise, returns 0.

PMSC_SUBINPCHANGE

Indicates the character finder DLL (SUBINPUT) has been changed. (Japanese version only.)

PMSC_GETSYMBOLCOUNT

Retrieve the number of symbols contained in the last recognition result. lParam should be 0. This message should be sent by the window that received the HN_RESULT notification before returning from the notification message.

PMSC_GETSYMBOLS

Retrieve the symbols contained in the last recognition result. lParam should be a pointer to a buffer large enough to accommodate the number of symbols contained in the result followed by SYV_NULL. The number of symbols in the result can be obtained by sending the WM_PENMISC message to the window with the PMSC_GETSYMBOLCOUNT submessage. This message should be sent by the window that received the HN_RESULT notification before returning from the notification message. A nonzero value is returned to indicate success.

PMSC_SETSYMBOLS

Change the symbols for the last recognition result. lParam should be a pointer to a buffer containing the array of symbols to be set terminated by SYV_NULL. lParam may be NULL to indicate an empty result. The control receiving this message should not perform any garbage detection on results set in this manner. This allows the application to perform its own garbage detection. In the case of the bedits controls, the number of symbols set must be the same as the number of symbols obtained using the WM_PENMISC message with the PMSC_GETSYMBOLCOUNT submessage. If not, the symbols are not set. This message should be sent by the window that received the HN_RESULT notification before returning from the notifi-cation message. A nonzero value is returned to indicate success.

lParam

Depends on wParam.

See Also

BOXEDITINFO, INKINGINFO, PCMINFO


WM_PENMISCINFO

Posted to all top-level windows whenever a pen system change is made.

Parameters

wParam

PMI_ value that identifies the system change.

lParam

New value, depending on wParam.

Comments

This message is broadcast to all top-level windows whenever a new global pen default is set by a call to the SetPenMiscInfo function. (Control Panel is the principal source of these changes.) A series of WM_PENMISCINFO broadcasts is typically made after a Control Panel application is closed.

In version 2.0 of the Pen API, the message parameters have been defined and the name of this message has been changed from WM_GLOBALRCCHANGE to WM_PENMISCINFO, although the value is the same for compatibility with version 1.0. The wParam and lParam parameters are the same as the parameter values provided to the SetPenMiscInfo function.

For version 1.0 compatibility, a call to the SetGlobalRC function also causes a posted broadcast of this message to all top-level windows, but the parameters are both 0. PMI_RCCHANGE may be used as an alias for 0 for wParam; however, PMI_RCCHANGE is not a valid parameter to GetPenMiscInfo or SetPenMiscInfo.

See Also

SetPenMiscInfo, GetPenMiscInfo, SetGlobalRC, PMI_


WM_RCRESULT

Sent to an application by a recognizer with the results of a recognition.

The WM_RCRESULT message is provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions.

Parameters

wParam

REC_ code indicating why recognition ended.

lParam

Address of an RCRESULT structure.

See Also

ProcessWriting, RCRESULT, Recognize, RecognizeData


Pen Application Programming Interface Constants

This chapter describes some of the many manifest constants defined by the Pen Application Programming Interface, listed alphabetically. Constants listed in this chapter are primarily those that do not contain a complete listing in any individual function or message description elsewhere in this documentation. Constants that pertain to individual functions or messages can be found with the descriptions of those functions or messages.

Each entry includes a complete description of the constant. For a comprehensive list of the Pen API constants, see Chapter 9, “Summary of the Pen Application Programming Interface,” or refer to the PENWIN.H header file. Refer to the index to locate the descriptions of any of the Pen API constants.


ALC_ Alphabet Codes

The ALC_ constants enable a subset of the active character set, depending on the current language.

For example, the French language includes “h” in the lowercase alphabet. In the same way, “£” replaces “$” if ALC_MONETARY is set in British systems. For more information about alphabets, see “Specifying an Alphabet Set” in Chapter 8 and “Alphabet” in Chapter 5.

Comments

The following ALC_ constants are are supported:

Constant	Description
ALC_ALL	All characters except Japanese characters.
ALC_ALPHA	ALC_LCALPHA | ALC_UCALPHA.
ALC_ALPHANUMERIC	ALC_LCALPHA | ALC_UCALPHA | ALC_NUMERIC.
ALC_ASCII	Seven-bit characters ASCII #20−ASCII #0x7F
ALC_DBCS	Allow double-byte character set (DBCS) variety of single-byte character set (SBCS).
ALC_DEFAULT	Default value; uses complete set of recognizable char-acters and gestures. The set of these is defined by the recognizer. It is the set of characters at or above ALC_SYSMINIMUM that the recognizer can accurately distinguish. If an application sets ALC_DEFAULT in the HRC object, and the recognizer is an alphanumeric system recognizer, the recognizer must at least support ALC_SYSMINIMUM as a default. ALC_DEFAULT should be the same character set as the complete character set for the given language minus the ALC_OTHER characters. If an application combines ALC_DEFAULT with other ALC_ values, ALC_DEFAULT is ignored.
ALC_GESTURE	Gestures.
ALC_GLOBALPRIORITY	Specifies that the global recognition priorities (from Tool Palette) are to be used during recognition. An application can control its own recognition priority in a control by clearing this flag and then setting its own priorities in the HRC.
ALC_HIRAGANA	Hiragana characters. (Japanese version only.)
ALC_JIS1	All Kanji Shift JIS level 1 characters. (Japanese version only.)
ALC_KANJI	Kanji characters, Shift JIS levels 1, 2, and 3. (Japanese version only.)
ALC_KANJIALL	ALC_ALL | ALC_HIRAGANA | ALC_KATAKANA | ALC_KANJI. (Japanese version only.)
ALC_KANJISYSMINIMUM	Minimum set of characters needed for Japanese system recognizer. Same as ALC_SYSMINIMUM | ALC_HIRAGANA | ALC_KATAKANA | ALC_JIS1. (Japanese version only.)
ALC_KATAKANA	Katakana characters. (Japanese version only.)
ALC_LCALPHA	Lowercase letters a−z.
ALC_MATH	Math symbols:  %^*()-+={}<>,/.
ALC_MONETARY	Monetary symbols:  ,.$ or appropriate currency desig-nation such as the yen or pound sterling symbol, accord-ing to the current language setting.
ALC_NONPRINT	Space, tab, carriage-return, and control glyphs.
ALC_NOPRIORITY	No priority. This value means the application has no preference for one type of symbol over another.
ALC_NUMERIC	Numerals 0−9.
ALC_OEM	Bits reserved for recognizer capabilities specific to the original equipment manufacturer (OEM).
ALC_OTHER	Other symbols:  @ # | _ ~ [ ]. That is, all other symbols not included in ALC_ALPHANUMERIC, ALC_MONETARY, ALC_MATH, and ALC_PUNC.
ALC_PUNC	Punctuation:  !-;`"?()&.,\.
ALC_RESERVED	Reserved.
ALC_SYSMINIMUM	Minimum set of characters needed for Roman alphabet system recognizers:  ALPHANUMERIC | ALC_PUNC | ALC_WHITE | ALC_GEST.
ALC_UCALPHA	Uppercase letters A−Z.
ALC_USEBITMAP	(Description follows table.)
ALC_WHITE	White space. If this value is not set in the HRC object, the recognizer should ignore any white space left between characters. Thus, ALC_WHITE is included in the ALC_DEFAULT. For example, in the zip code field of the Hform sample application, where ALC_NUMERIC | ALC_GESTURE is set, the user does not have to worry about getting any extraneous spaces.
If ALC_USEBITMAP is set, it indicates the recognizer should adopt an alphabet set defined by the application. The defined set specifies individual characters of an alphabet by setting bits in a 256-bit bitfield. The lowest bit corresponds to the first character of the alphabet, the second bit to the second character, and so forth.

An application passes the bitfield to a recognizer through the SetAlphabetHRC or SetBoxAlphabetHRC functions. The following code shows how. Assume the array rgbfSet holds the desired bit values.

HRC     hrc;                         // HRC handle

BYTE    rgbfSet[cbRcrgbfAlcMax]      // 256-bit bitfield

SetAlphabetHRC( hrc, ALC_USEBITMAP, (LPBYTE) rgbSet );

ALC_USEBITMAP can be combined with other ALC_ values using the bitwise-OR operator. An application can thus, for example, select certain letters with a defined bitmap and combine them with all numerals and punctuation.

For Asian languages other than Japanese, refer to the appropriate subsets within the language: phonetic symbols for words within the language, phonetic symbols for words outside the language, and native pictographs. For example, in Korean, ALC_HANGUEL equals ALC_KATAKANA, and ALC_HANJA equals ALC_KANJI.

For kanji and other Asian encodings, different effects are possible depending on the state of ALC_DBCS. These effects are described in the following table.

Character in	ALC_DBCS = 0	ALC_DBCS = 1
ALC_HIRAGANA	N/A	Shift JIS characters 0x8154, 0x8155, and 0x829F − 0x82F1.
ALC_JIS1	N/A	All Kanji Shift JIS level 1 characters.
ALC_KATAKANA	0xA1 - 0xDF	Shift JIS characters 0x814A, 0x814B, 0x8152, 0x8153, 0x815B, and 0x8340 − 0x8396.
ALC_KANJI	N/A	All Kanji characters, Shift JIS levels 1, 2, and 3.
The following table shows the characters in Shift-JIS in each ALC_ set supported in the Japanese version:

ALC_ value	Shift JIS Code
ALC_HIRAGANA	0x8154, 0x8155, and 0x829F − 0x82F1
ALC_JIS1	0x8156 − 0x815A, 0x889F − 0x9872
ALC_KANJI	0x8156 − 0x815A, 0x889F − 0xEAA4, 0xED40 − 0xEDFC, 0xEE40 − 0xEEFC, 0xF040 − 0xF9FC, 0xFAF0 − 0xFAFC, 0xFB40 − 0xFBFC, 0xFC40 − 0xFC4B
ALC_KATAKANA	0x814A, 0x814B, 0x8152, 0x8153, 0x815B, 0x8340 − 0x8396
ALC_LCALPHA	0x8281 − 0x829A
ALC_MATH	0x8143, 0x8144, 0x814F, 0x815E, 0x8169, 0x816A, 0x816F, 0x8170, 0x817B − 0x817E, 0x8180 − 0x8188, 0x8193, 0x8196
ALC_MONETARY	0x8143, 0x8144, 0x818F − 0x8192
ALC_NONPRINT	0x8140
ALC_NUMERIC	0x824F − 0x8258
ALC_OTHER	0x814C − 0x814E, 0x8150, 0x8151, 0x8160 − 0x8164, 0x816B, 0x816C, 0x8171 − 0x8174, 0x8179, 0x817A, 0x817F,  0x8189 − 0x818E, 0x8194, 0x8197 − 0x81FC, 0x8240 − 0x824E, 0x8259 − 0x825F, 0x827A − 0x8280, 0x829B − 0x829E, 0x82F2 − 0x82FC, 0x837F, 0x897 − 0x83FC, 0x8840 − 0x84FC, 0x8740 − 0x879D
ALC_PUNC	0x8141 − 0x8149, 0x815B − 0x815F, 0x8165 − 0x816A, 0x816D − 0x8170, 0x8175 − 0x8178, 0x817C, 0x8195
ALC_UCALPHA	0x8260 − 0x8279
ALC_WHITE	0x8140
A recognizer must not return a symbol value outside the specified subset. However, a recognizer does not have to force a match to the subset; it can instead return “unknown” if a suitable match is not found.

You can set the ALC_ value for an hedit or bedit control in a dialog box by insert-ing a special string in the .RC file’s CONTROL statement. This string is in the form ALC<xxxx> where xxxx represents a case-independent hexadecimal ALC_ code, without a preceding 0x qualifier. You can append normal window text after the ALC_ entry.

The following line demonstrates setting the ALC_ value for an hedit control using a CONTROL statement:

CONTROL "ALC<402C>Dollars", IDD_PAID, "hedit", ES_LEFT | ... etc.

In the above example, the ALC<402C> value is stripped out with “Dollars” left as window text. The number 402C is the hexadecimal equivalent of:

ALC_NUMERIC | ALC_PUNC | ALC_MONETARY | ALC_GESTURE

The following example allows only kanji characters, katakana characters, and gestures; it does not specify initial window text:

CONTROL "ALC<74000>", IDD_J, "hedit", ES_LEFT | ... etc.


BXD_ Boxed Edit Control

The BXD_ values define the initial dimensions of the various components of a boxed edit (bedit) control. These are constants defined in terms of dialog units. They are converted to pixel dimensions by the bedit control before use.

For more information, see the entries for the BOXLAYOUT and GUIDE structures in Chapter 11, “Pen Application Programming Interface Structures.”

The following table lists the BXD_ values.

Constant	Value	Description
BXD_BASEHEIGHT	13	Initial value for cyBase in GUIDE structure after conversion from dialog units to pixels.
BXD_BASEHORZ	0	Initial value for cxBase in GUIDE structure after conversion from dialog units to pixels.
BXD_CELLHEIGHT	16	Initial value for cyBox in GUIDE structure after conversion from dialog units to pixels.
BXD_CELLWIDTH	12	Initial value for cxBox in GUIDE structure after conversion from dialog units to pixels.
BXD_CUSPHEIGHT	2	Initial value for cyCusp in BOXLAYOUT structure after conversion from dialog units to pixels.
BXD_ENDCUSPHEIGHT	4	Initial value for cyEndCusp in BOXLAYOUT structure after conversion from dialog units to pixels.
BXD_MIDFROMBASE	0	Same as BXD_BASEHORZ.


BXDK_ Japanese Boxed Edit Control

The BXDK_ values define the initial dimensions of the various components of a Japanese boxed edit (bedit) control. These are constants defined in terms of dialog units. They are converted to pixel dimensions by the bedit control before use.

For more information, see the entries for the BOXLAYOUT and GUIDE structures in Chapter 11, “Pen Application Programming Interface Structures.”

The following table lists the BXDK_ values.

Constant	Value	Description
BXDK_BASEHEIGHT	28	Initial value for cyBase in GUIDE structure after conversion from dialog units to pixels.
BXDK_BASEHORZ	0	Initial value for cxBase in GUIDE structure after conversion from dialog units to pixels.
BXDK_CELLHEIGHT	32	Initial value for cyBox in GUIDE structure after conversion from dialog units to pixels.
BXDK_CELLWIDTH	32	Initial value for cxBox in GUIDE structure after conversion from dialog units to pixels.
BXDK_CUSPHEIGHT	28	Initial value for cyCusp in BOXLAYOUT structure after conversion from dialog units to pixels.
BXDK_ENDCUSPHEIGHT	10	Initial value for cyEndCusp in BOXLAYOUT structure after conversion from dialog units to pixels.


IDC_ Display Cursor

A pen-aware display driver must define the following new cursor types.

Constant	Value	Description
IDC_ALTSELECT	32501	Upside-down standard arrow used for tap-and-hold selection.
IDC_PEN	32631	Default pen. Pen points up and to the left.
Example

You can access the tap-and-hold cursor with the following code:

HANDLE	hPenDLL = GetSystemMetrics( SM_PENWINDOW);

if (hPenDLL)

SetCursor( LoadCursor( hPenDLL, IDC_ALTSELECT ) );


PCM_ Pen Collection Mode

Pen collection mode values define the condition that terminates an input session. (The system is said to be in “pen collection mode” during an input session when pen movement generates input data instead of being interpreted as mouse movement.) Pen collection can be stopped on any of the following conditions set by the PCM_ values in the dwPcm member of the PCMINFO structure:

Constant	Description
PCM_ADDDEFAULTS	Combine the default termination conditions with those specified by the application.
PCM_DOPOLLING	Request polling mode, rather than the default WM_PENEVENT messages.
PCM_INVERT	Stop pen collection if the user touches the “eraser” end of the pen to the tablet. Not all tablets can detect this event.
PCM_PENUP	Stop pen collection when the pen is lifted from the tablet.
PCM_RANGE	Stop pen collection when the pen leaves tablet’s range of sensitivity. Not all tablets can detect this event.
PCM_RECTBOUND	Stop when the pen is placed down outside the inclusion rectangle. The inclusion rectangle is specified in the rectBound member of the PCMINFO structure.
PCM_RECTEXCLUDE	Stop when the pen touches inside the exclusion rectangle. The exclusion rectangle is specified in the rectExclude member of the PCMINFO structure.
PCM_RGNBOUND	Stop when the pen touches outside the bounding region specified in the hrgnBound member of the PCMINFO structure.
PCM_RGNEXCLUDE	Stop when the pen touches inside the exclusion region specified in the hrgnExclude member of the PCMINFO structure.
PCM_TAPNHOLD	Enable detection of the tap-and-hold gesture.
PCM_TIMEOUT	Stop pen collection if there is no pen activity for a specified time-out. The time-out value is specified in the dwTimeout member of the PCMINFO structure.


PDC_ Pen Device Capabilities

The following table lists the values for the lPdc member of the PENINFO structure:

Constant	Description
PDC_BARREL1	Barrel button 1 is present.
PDC_BARREL2	Barrel button 2 is present.
PDC_BARREL3	Barrel button 3 is present.
PDC_INTEGRATED	Tablet surface is also a display monitor.
PDC_INVERT	The tablet can detect when the “eraser” end of the pen is in contact with the tablet.
PDC_PROXIMITY	The tablet can detect when the pen is near but not in contact with the tablet surface.
PDC_RANGE	The tablet can detect when the pen leaves or enters the tablet’s range of sensitivity.
PDC_RELATIVE	The pen driver can generate only relative coordinates.
For additional details, see the entry for the PENINFO structure in Chapter 11, “Pen Application Programming Interface Structures.”


PDK_ State Bits for Pen Driver Kit

The PDK_ values inform the system when a mouse event is being generated by pen movement, as well as the current state of any barrel buttons. This information is contained in the wPDK and wPdk members of the STROKEINFO and PENPACKET structures, respectively. The GetPenAsyncState function also accepts a PDK_ value as its only argument. The following table lists the PDK_ values:

Constant	Value	Description
PDK_NULL	0x0000	No flags set (default).
PDK_UP	0x0000	Same as PDK_NULL.
PDK_BARREL1	0x0002	Barrel button 1 is depressed.
PDK_BARREL2	0x0004	Barrel button 2 is depressed.
PDK_BARREL3	0x0008	Barrel button 3 is depressed.
PDK_DOWN	0x0001	Pen is in contact with the tablet.
PDK_SWITCHES	0x000F	All of the above.
PDK_TIPMASK	0x0001	Mask for testing PDK_DOWN.
PDK_TRANSITION	0x0010	Only has meaning if set by pen services. This bit is set if the first point in the sequence being returned is in a different pen-tip state (up or down) from the previous points returned. If set on a call to AddPointsPenData, a new stroke is created even if the previous call to AddPointsPenData appended points of the same pen state. By default, a sub-sequent call to AddPointsPenData adding points of the same state as the previous call appends the points to the last stroke instead of creating a new stroke.
PDK_EVENT	0x0010	Alias for PDK_TRANSITION.
PDK_PENIDMASK	0x0F00	Mask for bits 8−11 (see paragraph following table).
PDK_INVERTED	0x0080	Pen is upside down (“eraser” end is in contact with tablet).
PDK_INKSTOPPED	0x2000	Inking has stopped.
PDK_OUTOFRANGE	0x4000	Set if the tablet detects the pen leaving the range of detection. If set, other information in the packet is invalid.
PDK_DRIVER	0x8000	Set if event is generated by the pen driver (as opposed to the mouse driver).
For PDK_ values other than PDK_PENIDMASK, bits 8 through 11 contain the identification number of the physical pen that generated the event. Pen numbering begins at 0.

See Also

PENPACKET, STROKEINFO


PDT_ OEM-Specific Data

PDT_ values provide information specific to the tablet hardware. These values are used in the wPdt member of the OEMPENINFO structure.

Constant	Value	Description
PDT_NULL	0	Null value.
PDT_PRESSURE	1	Tablet can detect change in pen pressure.
PDT_HEIGHT	2	Tablet can detect height of pen above surface.
PDT_ANGLEXY	3	Tablet can detect change in pen horizontal angle.
PDT_ANGLEZ	4	Tablet can detect change in pen vertical angle.
PDT_BARRELROTATION	5	Tablet can detect rotation of pen barrel.
PDT_OEMSPECIFIC	16	Maximum number of values allowed.
For additional information, see the PENINFO and OEMPENINFO structures in Chapter 11, “Pen Application Programming Interface Structures.”


PDTS_ Pen Data Scaling

The PDTS_ data scaling units are used in the uScale and wPndtNew arguments of the CreatePenData and MetricScalePenData functions, respectively. These units are used for the wPndts member of the PENDATAHEADER structure. Positive x-coordinate is to the right; positive y-coordinate is down.

The following table lists the PDTS_ values. These values cannot be combined with the bitwise-OR operator.

Constant	Description
PDTS_ARBITRARY	The application has done its own scaling of the data point.
PDTS_COMPRESS2NDDERIV	The second derivative between points is stored.
PDTS_DISPLAY	Each logical unit is equivalent to a display pixel. Positive x is to the right; positive y is down.
PDTS_HIENGLISH	Each logical unit is mapped to 0.001 inch. Positive x is to the right; positive y is down.
PDTS_HIMETRIC	Each logical unit is mapped to 0.001 millimeter. Positive x is to the right; positive y is down.
PDTS_LOMETRIC	Each logical unit is mapped to 0.01 millimeter. Positive x is to the right; positive y is down.
PDTS_STANDARDSCALE	The standard scaling metric, equivalent to PDTS_HIENGLISH. Standard recognizers scale to this value.
The following table lists the PDTS_ bit settings. These bit settings can be combined using the bitwise-OR operator.

Constant	Description
PDTS_COMPRESSED	The data is compressed.
PDTS_NOCOLLINEAR	All redundant points removed.
PDTS_NOEMPTYSTROKES	All empty strokes removed.
PDTS_NOOEMDATA	OEM data removed.
PDTS_NOPENINFO	The PENINFO structure has been trimmed from the header.
PDTS_NOTICK	Timing information removed.
PDTS_NOUPPOINTS	All pen-up strokes removed.
PDTS_NOUSER	User information removed.
The following table lists the PDTS_ mask values:

Constant	Description
PDTS_COMPRESSMETHOD	Bits encode the compression scheme that is used.
PDTS_SCALEMASK	Mask scaling bits for hardware information.
For additional information, see the entries for the CompactPenData and MetricScalePenData functions in Chapter 10, “Pen Application Programming Interface Functions.”


PDTT_ Pen Data Trimming

PDTT_ values are used as arguments for the CompactPenData function. The following table describes the PDTT_ values:

Constant	Description
PDTT_DEFAULT	Reallocates memory block to fit data; does not trim the data.
PDTT_ALL	Removes PENINFO structure from header, all pen-up points, OEM data, and collinear points.
PDTT_COLLINEAR	Removes coincident and collinear points from the pen data.
PDTT_COMPRESS	Compresses the data without losing any information.
PDTT_DECOMPRESS	Decompresses the data.
PDTT_OEMDATA	Removes all OEM data.
PDTT_PENINFO	Removes PENINFO structure from header.
PDTT_UPPOINTS	Removes all data from pen-up points (points collected when the pen is not in contact with the tablet).
For additional information, see the CompactPenData function in Chapter 10, “Pen Application Programming Interface Functions.”


PMI_ Pen Miscellaneous Information

The PMI_ values are used as arguments for the GetPenMiscInfo and SetPenMiscInfo functions. The WM_PENMISCINFO message also uses PMI_ values in its wParam parameter.

The following table describes the PMI_ values:

Constant	Description
PMI_BEDIT	Boxed edit information.
PMI_CXTABLET	Width of tablet (in units of 0.001 inch) if present, else the width of the screen.
PMI_CYTABLET	Height of tablet (in units of 0.001 inch) if present, else the height of the screen.
PMI_ENABLEFLAGS	Flags describing whether certain Pen API features are enabled. The flags can be a combination of the following values: PWE_AUTOWRITE   Enable pen functionality where the I-Beam cursor is present.  PWE_ACTIONHANDLES   Enable action handles in controls.  PWE_INPUTCURSOR   Show cursor while writing.  PWE_LENS   Enable pop-up letter guides (that is, the lens).
PMI_INDEXFROMRGB	A standard RGB pen-tip color value from 0 to 0xFFFFFF.
PMI_PENTIP	Address of current pen-tip structure.
PMI_RGBFROMINDEX	An integer index from 0 to 15 for the standard pen-tip color table.
PMI_SAVE	Save settings to file.
PMI_SYSFLAGS	Flags describing which pen system components are loaded. The flags can be a combination of the following values: PWF_RC1   Support available for Pen API version 1.0 Recognition Context (RC) and associated functions.  PWF_PEN   Pen/tablet hardware is present.  PWF_INKDISPLAY   Ink-compatible display driver is present.  PWF_RECOGNIZER   System recognizer is present.  PWF_BEDIT   Boxed edit (bedit) control is available.  PWF_HEDIT   Handwriting edit (hedit) control is available.  PWF_IEDIT   Ink edit (iedit) control is available.  PWF_ENHANCED   Enhanced features, including gesture support and 1 millisecond timing, are available.  PWF_FULL   All components listed above are present.
PMI_SYSREC	Handle to system recognizer, if present.
PMI_TICKREF	Absolute reference time that the system uses to calculate time-stamps for strokes in pen data objects and inksets.
PMI_TIMEOUT	Time-out value to end handwriting input, in milliseconds.
PMI_TIMEOUTGEST	Time-out value to end a gesture, in milliseconds.
PMI_TIMEOUTSEL	Time-out value in milliseconds for press-and-hold gesture. The range of permissible values is 0 to 5000. If press-and-hold has been disabled, this value is 65,535.
For additional information, see the entries for the GetPenMiscInfo and SetPenMiscInfo functions in Chapter 10, “Pen Application Programming Interface Functions.”


RCD_ Writing Direction

RCD_ values are used in the wRcDirect member of the global RC structure. The RC structure is passed to a version 1.0 recognizer in the lpRC argument of InitRC and informs the recognizer of the writing direction. To set the writing direction differently than the default direction, call SetGlobalRC with the desired RCD_ value in wRcDirect.

RCD_ constants are provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions.

The writing direction consists of both primary and secondary directions. For example, English is written from left to right (primary) and then down the page (secondary). Chinese is often written from the top down (primary) and then right to left across the page (secondary).

The high byte of the direction indicates primary direction; the low byte indicates secondary direction. A recognizer can choose to ignore this word and support only the natural direction of the given language. The default value is determined by the recognizer.

The following table lists the RCD_ values:

Constant	Description
RCD_DEFAULT	Default value.
RCD_BT	Bottom to top.
RCD_LR	Left to right.
RCD_RL	Right to left.
RCD_TB	Top to bottom.
Example

For example, the value for standard English writing direction is defined as follows:

#define wRcDirectRoman  ((RCD_LR<<8) | RCD_TB)

See Also

RC


RCO_ Recognition Options

RCO_ values apply only to recognizers compatible with version 1.0 of the Pen API. They are used in the lRcOptions member of the RC structure, which specifies various options for recognition. RCO_ values can be combined with a logical-OR operator.

Constant	Description
RCO_BOXCROSS	Display a plus sign (+) at center of each box in a bedit control.
RCO_BOXED	Set if the writer is expected to write in boxes and the GUIDE structure contains valid data.
RCO_COLDRECOG	Set in results messages if the result is coming from cold recognition.
RCO_DISABLEGESMAP	Disables gesture mapping during the Recognize function call.
RCO_NOFLASHCURSOR	No flash cursor feedback.
RCO_NOFLASHUNKNOWN	If set in the RC structure and nothing was recognized, the cursor will not momentarily change to a question-mark cursor shape.
RCO_NOHIDECURSOR	If set, doesn’t remove cursor while inking.
RCO_NOHOOK	Prevents application-wide and system-wide hooks from being called.
RCO_NOPOINTEREVENT	If set, the RC Manager will not try to recognize a pointer event but will pass on all data to the recog-nizer. This is useful, for example, if the application has installed a shape recognizer so the user can enter dots of ink. If the null recognizer is selected into the RC, RCO_NOPOINTEREVENT is assumed to be set.
RCO_NOSPACEBREAK	If set, indicates that the results passed back from the recognizer should be passed on to the dictionaries without breaking at space boundaries.
RCO_SAVEALLDATA	Saves all the pen data in the RCRESULT structure that is generated by the tablet, including any data for pen-up strokes and optional data such as pressure. By default, only data used by the recognizer is saved. The Microsoft recognizer collects all data from first to last pen-down stroke, including pen-up strokes in between, and any available OEM data for each stroke.
RCO_SAVEHPENDATA	Saves the pen data. If this is set, the recognizer does not delete the data when the application returns from WM_RCRESULT. It is the application’s responsibility to free the pen data.
RCO_SUGGEST	If set, the following actions take place: After all dictionaries have been unsuccessfully searched with strings from the symbol graph, each dictionary is called with DIRQ_SUGGEST to allow the diction-aries to make suggestions. If a string is not yet identified by a dictionary, the null dictionary is used to create a symbol string from the symbol graph.
RCO_TABLETCOORD	If set, indicates that the members representing coordi-nate values in the RC structure are in tablet coordi-nates instead of screen coordinates. This can be used to collect recognition data on the portion of the tablet not mapped to the screen.


RCOR_ Tablet Orientation

RCOR_ values are used in the wRcOrient member of the global RC structure. The RC structure is passed to a version 1.0 recognizer in the lpRC argument of InitRC and informs the recognizer of the tablet orientation. The recognizer can optionally use the orientation to direct the transformation of tablet coordinates to ideal coordi-nates used for recognition.

RCOR_ constants are provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions.

The following table lists the RCOR_ values:

Constant	X-coordinate	Y-coordinate
RCOR_NORMAL	X = X'	Y = Y'
RCOR_LEFT	X = yMax - Y'	Y = X'
RCOR_RIGHT	X = Y'	Y = xMax - X'
RCOR_UPSIDEDOWN	X = xMax - X'	Y = yMax - Y'
As with the preceding values, direction is provided as a clue to the recognizer. A recognizer may attempt to identify the direction of writing by itself.

See Also

RC


RCP_ User Preferences

RCP_ values are used in the wRcPreferences member of the global RC structure. The RC structure is passed to a version 1.0 recognizer in the lpRC argument of InitRC and informs the recognizer of the user preferences.

RCP_ constants are provided only for compatibility with version 1.0 of the Pen API and will not be supported in future versions.

The following table lists the RCP_ values:

Constant	Description
RCP_LEFTHAND	User writes with left hand.
RCP_MAPCHAR	Tells a version 1.0 recognizer to fill in segmentation information in the lpsyc member of the SYG structure. This value cannot be set by the user because there is no Control Panel access to it. RCP_MAPCHAR is used by the Trainer.
See Also

RC


RCRT_ Results Type

RCRT_ values apply only to recognizers compatible with version 1.0 of the Pen API. They are used in the wResultsType member of the RCRESULT structure, which specifies the type of results as described in the following table:

Constant	Description
RCRT_ALREADYPROCESSED	Set by a hook if the result has already been acted upon. If an application receives a result with this bit already set, it should erase the ink and perform no other pro-cessing. An application-wide hook can set this flag. The Hform sample application demonstrates its use.
RCRT_DEFAULT	Normal return type.
RCRT_GESTURE	Result is a gesture symbol.
RCRT_NORECOG	Nothing recognized; only the data is returned. No recognition was attempted.
RCRT_NOSYMBOLMATCH	Nothing recognized. The ink drawn did not match any enabled symbols.
RCRT_PRIVATE	Recognizer-specific symbol recognized.
RCRT_UNIDENTIFIED	Result contained unidentified results.
Example

The code below shows an example of how to use RCRT_ values:

if ((lpr->wResultsType & (RCRT_NOSYMBOLMATCH | RCRT_ALREADYPROCESSED |

   RCRT_NORECOG | RCRT_PRIVATE ) ) == 0 )

{

// A gesture or character

if (lpr->wResultsType & RCRT_GESTURE)

{

.

.	// Handle Gesture

.

}

else

{

.

.	// Character results

.

}

}

else

{

.	// Handle special cases as necessary.  In general,

.	// should just ignore.  This is what hedits do.

.

}


REC_ Recognition Functions

The REC_ constants specify return values from the GetPenHwEventData and GetPenHwData functions. They are also returned from the obsolete functions Recognize, RecognizeData, and ProcessWriting, and as the wParam value of the WM_RCRESULT message. Return values less than REC_DEBUG are provided for debugging purposes only and represent abnormal termination.

Constant	Description
REC_OK	This result message to be followed by other results before Recognize terminates. This is a valid wParam value for WM_RCRESULT, but it can never be the return value for Recognize.
REC_ABORT	Recognition stopped by a call to EndPenCollection with this value. The lpPnt data is not valid.
REC_BADHPENDATA	Returned if HPENDATA cannot be locked or has an invalid header. This value is also returned if HPENDATA has no data in it or if the data is in an incorrect scale or compressed.
REC_BUFFERTOOSMALL	Returned by GetPenHwEventData.
REC_BUSY	Returned if another task is currently performing recognition.
REC_DONE	Returned by RecognizeData upon normal completion.
REC_NA	Function not available.
REC_NOINPUT	Returned by RecognizeData if the buffer contains no data, or returned by Recognize if recognition ended before any data was collected. For example, a pen-down stroke may have occurred outside the bounding rectangle before any data was collected.
REC_NOTABLET	Tablet not physically present.
REC_OOM	Out-of-memory error.
REC_OVERFLOW	Data overflow during execution of the call.
REC_POINTEREVENT	Returned if the user makes contact with the tablet surface and lifts the pen before the pen tip travels a short distance. This value is also returned if the user does a press-and-hold action; that is, the pen makes contact with the tablet and remains in that position for a short period of time. REC_POINTEREVENT informs the application it should begin selection actions rather than inking or recognition. If REC_POINTEREVENT is returned, no WM_RCRESULT message is generated and no ink is displayed.
REC_TERMBOUND	Recognition ended because of a hit test outside the bounding rectangle. The pntEnd member of RCRESULT is filled with the point causing the stop.
REC_TERMEX	Recognition ended because of a hit test inside the exclusion rectangle. The pntEnd member of RCRESULT is filled with the point causing the stop.
REC_TERMOEM	Values greater than or equal to 512 reserved for recognizer-specific termination reasons.
REC_TERMPENUP	Recognition ended on pen up. ThepntEnd member of RCRESULT is filled with the pen-up point that terminated recognition.
REC_TERMRANGE	Recognition ended because the pen left the proximity range.
REC_TERMTIMEOUT	Recognition ended on time-out. (The pen was up con-tinuously for a given amount of time.)


Debugging Values

All of the values listed in the following table are in the debug version of PENWIN.DLL only. No WM_RCRESULT message is generated if these values are returned by Recognize.

Constant	Description
REC_DEBUG	All debugging return values are less than or equal to this.
REC_ALC	Invalid enabled alphabet.
REC_BADEVENTREF	Returned when the wEventRef member in the RC structure is invalid.
REC_CLVERIFY	Invalid verification level.
REC_DICT	Invalid dictionary parameters.
REC_ERRORLEVEL	Invalid error level.
REC_GUIDE	Invalid GUIDE structure.
REC_HREC	Invalid recognition handle.
REC_HWND	Invalid handle to window to send results to.
REC_INVALIDREF	Invalid data reference parameter.
REC_LANGUAGE	Returned by the recognizer when the lpLanguage member of RC contains a language that is not supported by the recognizer. Call ConfigRecognizer with the WCR_QUERYLANGUAGE subfunction to determine whether or not a particular language is supported.
REC_NOCOLLECTION	Returned by GetPenHwData if collection mode has not been set.
REC_OEM	Error values below REC_OEM (−1024) are specific to the recognizer.
REC_PCM	Invalid lPcm member in RC structure. There is no way for the recognition to end.
REC_PARAMERR	Invalid parameter.
REC_RECTBOUND	Invalid rectangle.
REC_RECTEXCLUDE	Invalid rectangle.
REC_RESULTMODE	Unsupported results mode requested.


SYV_ Symbol Values

Each glyph a recognizer can identify has an associated symbol value. It is this value that is returned to the application by the recognizer.

The high-order and low-order words of a symbol value have the following meanings:

High-order word	Low-order word
0	System symbols.
1	ANSI character code.
2	Gestures.
3	Shift character codes (kanji).
4	Shapes.
5	Unicode.
6	Virtual keys.
7-0x7EFF	Reserved for future use.
0x7F00-0x7FFF	Recognizer-specific symbols.
>=0x8000	Character code for given code page. The low 15 bits of the high-order word indicate the code page.
Recognizers for the European market should return symbol values using ANSI and gesture symbol values (ANSI is the native character set for Windows in the European market). For the Japanese market, recognizers can use Shift JIS Level 1 and gestures. When writing a recognizer, bear in mind that symbol values outside these ranges cannot be interpreted by all Windows applications.


System Symbol Values

The following system symbol values are supported for recognizers:

Constant	Description
SYV_BEGINOR	Begins a list of choices; in the bedit guide, displayed as an opening brace character ({).
SYV_EMPTY	Empty.
SYV_ENDOR	Ends a list of choices. In the bedit guide, displayed as a closing brace character (}).
SYV_NULL	Null terminator.
SYV_OR	Separator for list of choices; in the bedit guide, displayed as a vertical bar (|).
SYV_SOFTNEWLINE	Translated to a space by SymbolToCharacter.
SYV_SPACENULL	Used in a symbol graph to indicate an alternative to a space.
SYV_UNKNOWN	Unrecognized glyph.


Gesture Symbol Values

All system recognizers are expected to recognize a special set of glyphs used as commands. In the following table, the “Windows Equivalent” column shows the mouse and keyboard equivalents in Windows.

Constant	Value	Description	Windows equivalent
. . .	00−0x00FF	Command gesture given. The low byte specifies which ANSI character was modified by the command gesture.	Nonstandard (usually CTRL+key).
SYV_BACKSPACE	0x00020008	Deletes character under gesture and sets insertion point.	BACKSPACE.
SYV_CLEAR	0x0002FFD5	Clears the selection.	DEL.
SYV_CLEARCHAR	0x0002FFD2	Clears the selection.	DEL.
SYV_CLEARWORD	0x0002FFDD	Deletes word or object under gesture.	Double-click, DEL.
SYV_COPY	0x0002FFDA	Copies selection to Clipboard.	CTRL+INS.
SYV_CORRECT	0x0002FFDF	Corrects selection or word under gesture.	None.
SYV_CONTEXT	0x0002FFD7	Displays a context menu	Right mouse click.
SYV_CUT	0x0002FFDB	Cuts selection and places it on Clipboard.	SHIFT+DEL.
SYV_EXTENDSELECT	0x0002FFD8	For linear selection (text), selects all text between current insertion point and point of extend-selection gesture. For nonlinear selection (objects), adds object under gesture to selection.	SHIFT+mouse click.
SYV_INSERT	0x0002FFD6	Opens the lens to allow text to be inserted.	None
SYV_KKCONVERT	0x0002FFD4	Starts Kana-to-Kanji converter. (Japanese version only.)	N/A
SYV_PASTE	0x0002FFDC	Pastes selection at point indicated by hot spot of paste gesture.	Click (place insertion point) followed by SHIFT+INS.
SYV_RETURN	0x0002000D	Enters carriage-return key.	Click, RETURN.
SYV_SPACE	0x00020020	Adds space character.	Click, SPACEBAR.
SYV_TAB	0x00020009	Enters tab.	Click, TAB.
SYV_UNDO	0x0002FFD9	Undoes previous action.	ALT+BACKSPACE.
SYV_USER	0x0002FFDE	Any circle gesture.	See the following section.


Circle Gesture Symbol Values

A circle gesture consists of a circled letter, either uppercase or lowercase. The Pen API version 2.0 does not explicitly support circle gestures. They are defined only for application or recognizer use.

The following table lists the SYV_ values for the circle gestures. Intervening values correspond to the letters between “a” and “z”.

Constant	Value	Description
SYV_APPGESTUREMASK	0x00020000	Mask value for circle gestures.
SYV_CIRCLELOA	0x000224D0	Lowercase “a” circle gesture.
SYV_CIRCLELOZ	0x000224E9	Lowercase “z” circle gesture.
SYV_CIRCLEUPA	0x000224B6	Uppercase “A” circle gesture.
SYV_CIRCLEUPZ	0x000224CF	Uppercase “Z” circle gesture.


Selection Symbol Values

The following table lists the SYV_values for selection symbol gestures.

Constant	Value	Description
SYV_SELECTFIRST	0x0002FFC2	Minimum value for section SYVs.
SYV_LASSO	0x0002FFC1	Lasso selection (equivalent to double-click).
SYV_SELECTLEFT	0x0002FFC2	Select text to the left (not supported by the Microsoft Handwriting Recognizer).
SYV_SELECTRIGHT	0x0002FFC3	Select text to the right (not supported by the Microsoft Handwriting Recognizer).
SYV_SELECTLAST	0X0002FFCF	Maximum value for selection SYVs.


Shape Symbol Values

These values should be used by shape recognizers.

Constant	Value	Description
SYV_SHAPELINE	0x00040001	Shape recognized as a line.
SYV_SHAPEELLIPSE	0x00040002	Shape recognized as an ellipse.
SYV_SHAPERECT	0x00040003	Shape recognized as a rectangle.
SYV_SHAPEMIN	0x00040001	Minimum value for recognized shape SYVs.
SYV_SHAPEMAX	0x00040003	Maximum value for recognized shape SYVs.


A

action handle

A small icon provided in edit controls that facilitates an editing tasks such as dragging or insertion.


B

baseline

An imaginary horizontal line on which handwritten text rests. Analogous to the lines of lined notebook paper.


C

comb

A form of writing guide, such as those used in many common forms and questionnaires, consisting of a horizontal line with spaced tick marks. The guide gets its name from the resemblance of the tick marks to the teeth of a comb. The user writes in a comb guide with individual characters separated by the tick marks.

confidence level

A value assigned by a recognizer to indicate its degree of certainty in the results of a recognition. For example, in recognizing the word “clear,” a recognizer assigns a confidence level to each of the five letters and can also assign a confidence level to the entire word. Word lists and dictionaries can influence confidence levels. See also recognizer.


D

dictionary

A list of words or phrases private to a recognizer. A recognizer can use its dictionaries to verify recognition guesses, as directed through the EnableSystemDictionary


G

gesture

A predefined pen motion that signifies some desired action, such as a “lasso” to select or an X to delete. See also lasso.


H

hook

A callback function provided by an application that receives certain data before the normal recipient of the data. The hook function can thus examine or modify the data before passing it on.

hot spots

Critical points on symbols, particularly gestures, identified by a recognizer during recognition. See also gesture, recognizer, symbol.


I

ink

(1) A trail of colored pixels left on the screen that marks the path of the pen’s motion. (2) Input data generated by the moving pen; pen data.

inkset

An object that maps data points to time intervals. The points recorded in an inkset object may describe one or more strokes. See also stroke.

irreversible compression

A data-compression technique that produces a high degree of compression, but at the cost of lost information. After uncompression, the pen data can be redisplayed but recognition accuracy may be reduced. See also reversible compression.


L

lasso

A gesture formed by circling a section of text or other displayed data. See also gesture.

lens

A standard Windows pen interface dialog box that offers an on-screen keyboard or letter guides and is used for entering and editing text.

lossless compression

See reversible compression.

lossy compression

See irreversible compression.


O

OEM data

Data about pen pressure, angle, height, and other aspects of pen input that is collected in addition to data points. The specific OEM data collected depends on the hardware and the data it reports.

on-screen keyboard

(1) An image of a keyboard displayed on the screen. (2) The applet (Screen Keyboard or SKB) that displays the image. The user “types” on the on-screen keyboard by pressing the pen on the desired keys, as though typing on a real keyboard.


P

packet

A collection of pen data sent by the pen driver at a frequency determined by the sampling rate. Each packet contains the current coordinates of the pen, the time, and, optionally, other information. Collectively, the packets represent a digitized history of the pen’s movement. See also sampling rate.

pen collection mode

The system state in which pen movement generates data, instead of being interpreted as mouse movement. Also known as input session.

pen-down stroke

Data points collected while the pen is in contact with the tablet. Together, these points comprise a stroke. See also pen state, pen tip transition, pen-up points, proximity stroke.

pen packet

See packet.

pen state

The condition of the pen relative to the tablet surface — either up or down, depending on whether the pen is in contact with the tablet.

pen tip transition

The act of touching a pen to or lifting the pen from the tablet surface. The former begins a pen-down stroke, while the latter ends a pen-down stroke and begins a pen-up stroke. See also stroke, proximity stroke.

pen-up stroke

Data points received when the pen is not in actual contact with the tablet, but near enough for the tablet to sense movement. Together, these points comprise a proximity stroke. See also pen-down points, pen state, pen tip transition, proximity stroke.

proximity stroke

A stroke formed while the pen is near but not on the tablet surface. Also called “pen-up stroke.” Not all pen tablets can detect proximity strokes. See also pen tip transition, pen-up points, stroke.


R

real time

In the context of pen-based computing, real time means “while the pen is moving.”

recognition function

One of the 43 Pen Application Programming Interface (API) functions exported by a recognizer dynamic-link library. See also recognizer.

recognizer

A dynamic-link library of functions that collectively serve to recognize ink data as characters, numerals, words, foreign script, or other symbols.

reentrancy

The condition in which a function is interrupted during execution and restarted from its beginning in response to another caller.

reversible compression

A data-compression technique that loses no information, so data can be redisplayed and recognized with no loss of accuracy after uncompression. See also irreversible compression.


S

sampling rate

The frequency at which the pen driver sends packets to the pen system. A typical sampling rate is 100 − 120 packets per second, but does not necessarily equal the rate of hardware interrupts generated by the pen tablet. See also packets.

Screen Keyboard

See on-screen keyboard.

SKB

See on-screen keyboard.

stroke

The pen data generated between two pen tip transitions. For example, when the pen touches the tablet (pen down), all data generated as the pen moves comprises a pen-down stroke until the pen leaves the tablet. If the tablet can sense proximity strokes, the pen movement above the tablet surface forms a separate pen-up stroke until the pen either leaves the tablet’s range of sensitivity or touches down again. Thus, in noncursive printing, the letter “c” is formed as a single stroke while the letter “E” requires several pen-down strokes separated by pen-up strokes. See also pen-down points, pen tip transitions, pen-up points, proximity strokes.

symbol

An element interpreted by a recognizer from raw pen data. For example, the default system recognizer sees an individual letter or numeral as a symbol. A word is thus a string of symbols. A recognizer for cursive writing, however, may see an entire word as a single symbol without distinguishing each letter of the word. See also recognizer.

symbol correspondence

A map of the ink data that forms a recognized symbol. See also symbol element.

symbol element

An SYE structure containing a symbol value, its confidence level, and an identification of the ink data that forms the symbol. See also confidence level, symbol value.

symbol value

A numerical value that represents a recognized character or set of characters. A symbol value is internal to the recognizer and by itself has little meaning to the application. To translate a symbol value to a character such as a letter or numeral, an application must call the SymbolToCharacter function.


T

target

A window or writing area that receives pen input data.

trainer

An application that trains a recognizer. The trainer application may operate in the background, which is known as “passive training,” or be activated by the user, which is “active training.” See also recognizer, training.

training

The process used to update a recognizer’s database so that it better reflects the individual style and writing characteristics of a particular user, thus increasing the recognizer’s accuracy in handwriting interpretation. See also recognizer, trainer.


A

aliasing

In RPC, having two or more pointers to the same data object.

AppleTalk Data Stream Protocol (ADSP)

A network protocol for interprocess communication between Apple Macintosh computers and other platforms.

attribute

Any keyword of the Interface Definition Language that describes a property of a data type or remote procedure call.


B

bind

In RPC, the process through which a logical connection is established between a client and a server in order to direct a remote procedure call to that server.

binding

A relationship between a client and a server that is established over a specific protocol sequence to a specific host system and endpoint. Also used as a short form of binding handle.

binding handle

A data structure that represents the logical connection between a client and a server.

binding vector

An RPC data structure that contains a list of binding handles over which a server application can receive remote procedure calls.


C

Cell Directory Service (CDS)

The name-service provider for the Open Software Foundation’s Distributed Computing Environment.

client stub

MIDL-generated C-language source code that contains all the functions necessary for the client application to make remote procedure calls using the model of a traditional function call in a standalone application. The client stub is responsible for marshaling the input parameters and unmarshaling the output parameters. See also server stub, proxy stub.

conformant array

In RPC, an array whose size is determined at run time by another parameter, structure field, or expression.

connection-oriented

Describes a communications protocol or transport that provides a virtual circuit through which data packets are received in the same order as they were transmitted. If the connection between machines fails, the application is notified. TCP and SPX are examples of connection-oriented protocols. See also datagram.

connectionless

See datagram.

context rundown

A server notification that results from an unexpected termination of the binding between client and server applications.


D

datagram

Describes a communications protocol or transport in which data packets are routed independently of each other and may follow different routes and arrive in a different order from which they were sent. UDP and IPX are examples of transport-layer datagram protocols. See also connection-oriented.

discriminated union

(or variant record) A union that includes a discriminator as part of the data structure so that the currently valid data type is transmitted along with the union. See also encapsulated union, non-encapsulated union.

Distributed Computing Environment (DCE)

The Open Software Foundation’s specification for a set of integrated services, including remote procedure calls, distributed file systems, and security services. The OSF-DCE RPC standard is the basis for Microsoft RPC.

dynamic endpoint

An endpoint (network-specific server address) that is requested and assigned at run time. See also well-known endpoint.


E

encoding services

MIDL-generated stub routines that provide support for data encoding and decoding (also known as “pickling” or “serialization”). These services allow you to control the buffers containing the data to be marshaled and unmarshaled. See also type serialization, procedure serialization.

endpoint

A network-specific address of a server process for remote procedure calls. The actual name of the endpoint depends on the protocol sequence being used. See also dynamic endpoint and well-known endpoint.

endpoint mapper

(or endpoint-mapping service) Part of the RPC subsystem (RPCSS) that allows the run-time library to dynamically assign and resolve endpoints. See also endpoint.

encapsulated union

A MIDL construct that allows unions to be passed as part of a remote procedure call by embedding the union in a structure in which the discriminant is the first field of the structure, and the union is the second (and final) field of the structure. The IDL keyword switch specifies that a union is encapsulated. See also non-encapsulated union.

entry point vector (EPV)

An array of pointers to functions that implement the operations specified in the interface. Each element in the array corresponds to a function defined in the IDL file. Entry-point vectors allow distributed applications to support more than one implementation of the functions defined in the IDL file.


F

firewall

A control system that prevents unauthorized users from gaining access to a local network that is connected to the Internet.

full pointer

In RPC, a pointer that has all the capabilities normally associated with pointers in C/C++. Specifically, a full pointer can be null and can be aliased to another pointer parameter. The ptr attribute designates a full pointer. See also unique pointer and reference pointer.

fully bound handle

A binding handle that includes endpoint information. See also partially bound handle.


I

idempotent

In RPC, describes a remote procedure call that does not change a state and returns the same information each time it is called with the same input parameters.

input parameter

In a remote procedure call, a parameter containing data that the client application is transmitting to the server application. The in attribute designates an input parameter.

Interface Definition Language (IDL)

The OSF-DCE standard language for specifying the interface for remote procedure calls. See also MIDL.

Internet Protocol (IP)

A connectionless network-layer communications protocol. See also datagram.

Internetwork Packet Exchange (IPX)

A Novell NetWare communication protocol that uses datagram sockets to route information packets over local-area and wide-area networks.

intranet

A private network that uses Internet products and technologies (for example, web servers), but is not available to external Internet users.


L

local remote procedure call (LRPC)

In RPC, describes a remote procedure call to another process on the same machine as the calling process.

Locator

The Microsoft® Windows NT® name-service provider. See also name service.


M

major version number

See version number.

manager

In RPC, a set of server routines that implements the interface operations.

marshaling

The process through which operation parameters are packaged into NDR format so that they may be transmitted across process boundaries.

Microsoft Interface Definition Language (MIDL)

Microsoft’s implementation and extension of OSF-DCE Interface Definition Language.

minor version number

See version number.


N

name service

A service that maps names to objects and stores the name/object pairs in a database. For example, the RPC name service maps a logical name to a binding handle so client applications can refer to that logical name, rather than a protocol sequence and network address. See also nsid, CDS, Locator.

Network Computing Architecture (NCA)

A collection of guidelines for distributed computing. The RPC communication protocols follow these guidelines.

Name Service Independent (NSI)

A standard for API functions that allows a distributed application to access RPC name-service database elements through various name-service providers, such as OSF-DCE Cell Directory Service or the Microsoft Locator. See also name-service interface daemon (nsid).

name-service interface daemon (nsid)

A service that provides an interface between the Microsoft Locator and the OSF-DCE Cell Directory Service name service databases for RPC name-service functions.

named pipe

A connection-oriented protocol, based on Server Message Blocks (SMBs) and NetBIOS, used for communication between a server process and one or more client processes.

NetBIOS Extended User Interface (NetBEUI)

LAN Manager’s native transport protocol and network device driver. See also NetBIOS.

Network Basic Input/Output System (NetBIOS)

A software interface between the Microsoft® MS-DOS® operating system, the I/O bus, and a local area network.

Network Data Representation (NDR)

A standard format used during network transmission that is independent of the data-type format on any particular computer architecture. Transmitted data includes information that specifies its NDR format.

network address

An address that identifies a server on a network.

non-encapsulated union

A discriminated union that is less restrictive than an encapsulated union in that the discriminant and the union are not tightly bound. If the union is a parameter, the discriminant is another parameter; if the union is a structure field, the discriminant is another structure field. The IDL keywords switch_is and switch_type identify the discriminant and its type. See also encapsulated union.

non-idempotent

In RPC, indicates that a remote procedure call cannot be executed more than once because it will return a different value or change a state.


O

open array

In RPC, an array that is both conformant and varying; that is, both its size and the range of transmitted elements are determined at run time by other parameters, structure fields, or expressions.

Open Software Foundation (OSF)

A consortium of companies, formed to define the distributed computing environment (DCE).

Object Description Language (ODL)

A subset of MIDL attributes, keywords, statements, and directives used to define type libraries for OLE Automation applications.

output parameter

In a remote procedure call, a parameter containing data that the server application is transmitting to the client application. The out attribute designates an output parameter.


P

partially bound handle

A binding handle that does not include endpoint information. See also fully bound handle.

pickling

See serialization.

pipe

An IDL type constructor that supports transmission of an open-ended stream of data between client and server applications.

procedure serialization

Data serialization that uses a MIDL-generated serialization stub to accomplish encoding and decoding of one or more types with a single procedure call. Procedure serialization is accomplished by applying the encode and decode attributes to a function prototype in the ACF file. See also type serialization.

protocol sequence

A character string that represents a valid combination of an RPC protocol, a network layer protocol, and a transport layer protocol. For example, the protocol sequence ncacn_ip_tcp describes an NCA connection over an Internet Protocol with a Transmission Control Protocol as transport.

proxy stub

MIDL-generated C or C++ language source code that contains all the functions necessary for a custom OLE interface.


R

RPC object

Server instances or other resources, such a devices, database, and queues, that are operated on and managed by RPC server applications. Each object is uniquely identified by one or more object UUIDs.

RPC Subsystem (RPCSS)

A Windows NT subsystem that includes a variety of RPC and OLE services, including the endpoint mapper, OLE Service Control Manager (SCM), and the DCOM Object Resolver. Do not confuse this with the RPC-specific memory allocator package, RpcSs.

reference pointer

In RPC, the simplest pointer type. A reference pointer always points to valid storage and that storage does not change (although the contents may change). A reference pointer cannot be aliased. The ref attribute designates a reference pointer. See also unique pointer and full pointer.


S

Sequenced Packet Protocol (SPP)

Banyan Vines connection-oriented communication protocol for routing information packets over local area networks.

Sequenced Packet Exchange (SPX)

A Novell NetWare connection-oriented communication protocol for routing information packets over local area and wide area networks.

serialization

(or pickling) In RPC, the process of marshaling data to (encoding) and unmarshaling data from (decoding) buffers that you control. This is in contrast to traditional RPC usage, where the stubs and the RPC runtime control the marshaling buffers. See also procedure serialization, type serialization.

server stub

MIDL-generated C-language source code that contains all the functions necessary for the server application to handle remote requests using local procedure calls. See also client stub.

session

In RPC, an established relationship between a client application and a server application. See also bind, binding handle.

static callback function

A remote procedure that is part of the client side of a distributed application and that a server can call to obtain information from the client. The callback attribute designates a static callback function.

string binding

A character string that consists of the object UUID, protocol sequence, network address, endpoint, and endpoint options, all of which can be used to create a binding handle to the specified server.


T

Transmission Control Protocol (TCP)

A connection-oriented network transport layered on top of IP.

type serialization

Data serialization that uses MIDL-generated routines to size, encode, and decode objects of a specified type. The client application calls these routines to serialize the data. Type serialization is accomplished by applying the encode and decode attributes to a single data type, or to an interface, in the ACF file. See also procedure serialization.


U

User Datagram Protocol (UDP)

A network transport that uses connectionless datagram sockets and is layered on top of IP.

unbind

In RPC, to terminate the logical connection between a client and server.

unique pointer

In RPC, a pointer that can be null or point to existing data and whose value can change during a remote procedure call. A unique pointer cannot be aliased. The unique attribute designates a unique pointer. See also full pointer, reference pointer.

Universal Unique Identifier (UUID)

(or GUID) A 128-bit value used in cross-process communication to identify entities such as client and server interfaces, manager entry-point vectors, and RPC objects. See also uuidgen.

uuidgen

A utility program, provided with the Win32 SDK, that uses a time value and your machine’s network card ID to generate UUIDs that are guaranteed to be unique.


V

varying array

In RPC, an array whose range of transmitted elements is determined at run time by another parameter, structure field, or expression. See also conformant array and open array.

version number

In RPC, two numbers, separated by a decimal point, that identify the version of an interface. To be compatible, the major version number (the number to the left of the decimal point) must be the same for both client and server, and the minor version number of the server must be greater than or equal to the minor version number of the client.


W

well-known endpoint

An endpoint that does not change. Well-known endpoint information is stored as part of the binding handle, or within the name-service database server entry. See also dynamic endpoint.


RPC Data Types and Structures

This section defines the following constants, data types, and data structures used by the Microsoft RPC run-time functions:

Data type/structure	Description
RPC_C_AUTHN_LEVEL*	Authentication-level constants
RPC_C_AUTHN*	Authentication-service constants
RPC_C_AUTHZ*	Authorization-service constants
GUID	Globally unique identifier (UUID)
PROTSEQ	Protocol sequence string
RPC_AUTH_IDENTITY_HANDLE	Authorization-identity handle
RPC_AUTH_KEY_RETRIEVAL_FN	Authorization-key retrieval function
RPC_AUTHZ_HANDLE	Authorization handle
RPC_BINDING_HANDLE	Binding handle
RPC_BINDING_VECTOR	Count and array of binding handles
RPC_IF_HANDLE	Interface handle
RPC_IF_ID	Interface identifier
RPC_IF_ID_VECTOR	Count and array of interface identifiers
RPC_MGR_EPV	Manager entry-point vector
RPC_NS_HANDLE	Name-service handle
RPC_OBJECT_INQ_FN	Object-inquiry function
RPC_POLICY	Set port allocation and NIC binding policies
RPC_PROTSEQ_VECTOR	Count and array of protocol sequences
RPC_STATS_VECTOR	Statistics vector
RPC_STATUS	Status
SEC_WINNT_AUTH_IDENTITY	Authentication
String binding	String representation of a binding
String UUID	Unique identifier string
UUID	Universally unique identifier
UUID_VECTOR	Count and array of unique identifiers


Authentication-Level Constants

The AuthnLevel argument represents the authentication level supplied to the RpcBindingInqAuthInfo and RpcBindingSetAuthInfo run-time functions.

The levels are listed in order of increasing authentication. Each new level adds to the authentication provided by the previous level. If the RPC run-time library does not support the specified level, it automatically upgrades to the next higher supported level.

The following constants represent valid values for the AuthnLevel argument:

Constant	Description
RPC_C_AUTHN_LEVEL_DEFAULT	Uses the default authentication level for the specified authentication service.
RPC_C_AUTHN_LEVEL_NONE	Performs no authentication.
RPC_C_AUTHN_LEVEL_CONNECT	Authenticates only when the client establishes a relationship with a server.
RPC_C_AUTHN_LEVEL_CALL	Authenticates only at the beginning of each remote procedure call when the server receives the request. Does not apply to remote procedure calls made using the connection-based protocol sequences (those that start with the prefix “ncacn”). If the protocol sequence in a binding handle is a connection-based protocol sequence and you specify this level, this routine instead uses the RPC_C_AUTHN_LEVEL_PKT constant.
RPC_C_AUTHN_LEVEL_PKT	Authenticates that all data received is from the expected client.
RPC_C_AUTHN_LEVEL_PKT _INTEGRITY	Authenticates and verifies that none of the data transferred between client and server has been modified.
RPC_C_AUTHN_LEVEL_PKT _PRIVACY	Authenticates all previous levels and encrypts the argument value of each remote procedure call.
Note  RPC_C_AUTHN_LEVEL_CALL, RPC_C_AUTHN_LEVEL_PKT, RPC_C_AUTHN_LEVEL_PKT_INTEGRITY, and RPC_C_AUTHN_LEVEL_PKT_PRIVACY are only supported for clients communicating with a Windows NT server. A Windows 95 server can only accept incoming calls at the RPC_C_AUTHN_LEVEL_CONNECT level.

See Also

RpcBindingInqAuthInfo, RpcBindingSetAuthInfo


Authentication-Service Constants

The AuthnSvc argument represents the authentication service supplied to the RpcBindingInqAuthInfo and RpcBindingSetAuthInfo run-time functions.

The following constants represent valid values for the AuthnSvc argument:

Constant	Value	Service
RPC_C_AUTHN_DCE_PRIVATE	1	DCE private key authentication
RPC_C_AUTHN_DCE_PUBLIC	2	DCE public key authentication (reserved for future use)
RPC_C_AUTHN_DEC_PUBLIC	4	DEC public key authentication (reserved for future use)
RPC_C_AUTHN_DEFAULT	0xffffffff	Default authentication service
RPC_C_AUTHN_NONE	0	No authentication
RPC_C_AUTHN_WINNT	10	NTLMSSP (NT LAN Manager Security Support Provider)
Specify RPC_C_AUTHN_NONE to turn off authentication for remote procedure calls made using the binding handle.

When you specify RPC_C_AUTHN_DEFAULT, the RPC run-time library uses the RPC_C_AUTHN_DCE_PRIVATE authentication service for remote procedure calls made using the binding handle.

See Also

RpcBindingInqAuthInfo, RpcBindingSetAuthInfo


Authorization-Service Constants

The AuthzSvc argument represents the authorization service supplied to the RpcBindingInqAuthInfo and RpcBindingSetAuthInfo run-time functions.

The following constants represent valid values for the AuthzSvc argument:

Constant	Value	Service
RPC_C_AUTHZ_NONE	0	Server performs no authorization.
RPC_C_AUTHZ_NAME	1	Server performs authorization based on the client’s principal name.
RPC_C_AUTHZ_DCE	2	Server performs authorization checking using the client’s DCE privilege attribute certificate (PAC) information, which is sent to the server with each remote procedure call made using the binding handle. Generally, access is checked against DCE access control lists (ACLs).
See Also

RpcBindingInqAuthInfo, RpcBindingSetAuthInfo


GUID

typedef struct _GUID {

    unsigned long Data1;

    unsigned short Data2;

    unsigned short Data3;

    unsigned char Data4[8];

} GUID;

typedef GUID UUID;

Data1

Specifies the first eight hexadecimal digits of the UUID.

Data2

Specifies the first group of four hexadecimal digits of the UUID.

Data3

Specifies the second group of four hexadecimal digits of the UUID.

Data4

Specifies an array of eight elements that contains the third and final group of eight hexadecimal digits of the UUID in elements 0 and 1, and the final 12 hexadecimal digits of the UUID in elements 2 through 7.

Remarks

GUIDs are globally unique identifiers and are a Microsoft implementation of the DCE UUID.

UUIDs uniquely identify objects, such as interfaces, manager entry-point vectors, and client objects. The RPC run-time libraries use UUIDs to check for compatibility between clients and servers and to select among multiple implementations of an interface.

See Also

UUID, UUID_VECTOR


PROTSEQ

unsigned char *  Protseq[1];

Protseq

Points to a character string identifying the network protocol used to communicate between client and server.

Remarks

The protocol sequence is a character string that represents a valid combination of an RPC protocol (such as “ncacn”), a transport protocol (such as “tcp”), and a network protocol (such as “ip”). Microsoft RPC supports the following protocol sequences:

Protocol sequence	Description	Supporting Platforms
ncacn_nb_tcp	Connection-oriented NetBIOS over TCP	client only: MS-DOS, Windows 3.x client and server: Windows NT
ncacn_nb_ipx	Connection-oriented NetBIOS over IPX	client only: MS-DOS, Windows 3.x client and server: Windows NT
ncacn_nb_nb	Connection-oriented NetBEUI	client only: MS-DOS, Windows 3.x client and server: Windows NT, Windows 95
ncacn_ip_tcp	Connection-oriented TCP/IP	client only: MS-DOS,Windows 3.x, and Apple Macintosh client and server: Windows 95 and Windows NT
ncacn_np	Connection-oriented named pipes	client only: MS-DOS, Windows 3.x, Windows 95 client and server: Windows NT
ncacn_spx	Connection-oriented SPX	client only: MS-DOS, Windows 3.x client and server: Windows NT, Windows 95
ncacn_dnet_nsp	Connection-oriented DECnet transport	client only: MS-DOS, Windows 3.x
ncacn_at_dsp	Connection-oriented AppleTalk DSP	client: Apple Macintosh server: Windows NT
ncacn_vns_spp	Connection-oriented Vines SPP transport	client only: MS-DOS, Windows 3.x client and server: Windows NT
ncadg_ip_udp	Datagram (connectionless) UDP/IP	client only: MS-DOS, Windows 3.x client and server: Windows NT
ncadg_ipx	Datagram (connectionless) IPX	client only: MS-DOS, Windows 3.x client and server: Windows NT
ncalrpc	Local procedure call	client and server: Windows NT and Windows 95
A server application can use a particular protocol sequence only when the RPC run-time library and operating-system software support that protocol. A server chooses to accept remote procedure calls over some or all of the supported protocol sequences.

Several server routines allow server applications to register protocol sequences with the run-time library. Microsoft RPC functions that require a protocol-sequence argument use the data type unsigned char.

A client can use the protocol-sequence strings to construct a string binding using the RpcStringBindingCompose routine.

Note  The ncalrpc protocol sequence is supported only for 32-bit Windows applications.

The ncacn_dnet_nsp protocol sequence is supported only for MS-DOS, and 16-bit Windows client applications. This release of Microsoft RPC does not include support for the ncacn_dnet_nsp protocol sequence with 32-bit client or server applications.

16-bit Windows client applications that use the ncacn_spx or ncadg_ipx protocol sequences require that the file NWIPXSPX.DLL be installed in order to run under the Windows NT Windows on Windows (WOW) subsystem. Contact Novell to obtain this file.

The ncacn_vns_spp protocol sequence requires that Banyan’s Enterprise Client For Windows NT be installed. Contact Banyan for more information.

See Also

RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf, RpcStringBindingCompose


RPC_AUTH_IDENTITY_HANDLE

typedef void *  RPC_AUTH_IDENTITY_HANDLE;

Remarks

An identity handle points to the data structure that contains the client's authentication and authorization credentials specified for remote procedure calls.

See Also

RpcBindingInqAuthInfo, RpcBindingSetAuthInfo


RPC_AUTH_KEY_RETRIEVAL_FN

typedef void ( * RPC_AUTH_KEY_RETRIEVAL_FN)
(   void *  Arg,
    unsigned char *  ServerPrincName,
    unsigned long  KeyVer,
    void * *  Key,
    RPC_STATUS *  Status
);

Arg

Points to a user-defined argument to the user-supplied encryption key acquisition function. The RPC run-time library uses the Arg argument supplied to RpcServerRegisterAuthInfo.

ServerPrincName

Points to the principal name to use for the server when authenticating remote procedure calls. The RPC run-time library uses the ServerPrincName argument supplied to RpcServerRegisterAuthInfo.

KeyVer

Specifies the value that the RPC run-time library automatically provides for the key-version argument. When the value is 0, the acquisition function must return the most recent key available.

Key

Points to a pointer to the authentication key returned by the user-supplied function.

Status

Points to the status returned by the acquisition function when it is called by the RPC run-time library to authenticate the client RPC request. If the status is other than RPC_S_OK, the request fails and the run-time library returns the error status to the client application.

Remarks

An authorization key retrieval function specifies the address of a server-application-provided routine returning encryption keys.

See Also

RpcServerRegisterAuthInfo


RPC_AUTHZ_HANDLE

typedef void *  RPC_AUTHZ_HANDLE;

Remarks

An authorization handle points to the privileges information for the client application that made the remote procedure call.

See Also

RpcBindingInqAuthClient


RPC_BINDING_HANDLE

typedef RPC_BINDING_HANDLE handle_t;

Remarks

A binding handle is a pointer-sized opaque variable containing information that the RPC run-time library uses to access binding information. The run-time library uses binding information to establish a client-server relationship that allows the execution of remote procedure calls.

Based on the context in which a binding handle is created, the binding handle is considered a server binding handle or a client binding handle.

A server binding handle contains the information necessary for a client to establish a relationship with a specific server. Any number of RPC API run-time routines return a server binding handle that can be used for making a remote procedure call.

A client binding handle cannot be used to make a remote procedure call. The RPC run-time library creates and provides a client binding handle to a called server procedure (also called a server manager routine) as the RPC_BINDING_HANDLE parameter. The client binding handle contains information about the calling client.

The RpcBinding* and RpcNsBinding* routines return the status code RPC_S_WRONG_KIND_OF_BINDING when an application provides the incorrect binding-handle type.

An application can share a single binding handle across multiple threads of execution. The RPC run-time library manages concurrent remote procedure calls that use a single binding handle. However, the application is responsible for binding-handle concurrency control for operations that modify a binding handle. These operations include the following routines:

•	RpcBindingFree

•	RpcBindingReset

•	RpcBindingSetAuthInfo

•	RpcBindingSetObject

For example, if an application shares a binding handle across two threads of execution and resets the binding-handle endpoint in one of the threads by calling RpcBindingReset, the binding handle in the other thread is also reset. Similarly, freeing the binding handle in one thread by calling RpcBindingFree frees the binding handle in the other thread.

If you don’t want concurrency, you can design an application to create a copy of a binding handle by calling RpcBindingCopy. In this case, an operation to the first binding handle has no effect on the second binding handle.

Routines requiring a binding handle as an argument show a data type of RPC_BINDING_HANDLE. Binding-handle arguments are passed by value.


RPC_BINDING_VECTOR

#define rpc_binding_vector_t RPC_BINDING_VECTOR

typedef struct _RPC_BINDING_VECTOR {

    unsigned long       Count;

    RPC_BINDING_HANDLE  BindingH[1];

}   RPC_BINDING_VECTOR;

Count

Specifies the number of binding handles present in the binding-handle array BindingH.

BindingH

Specifies an array of binding handles that contains Count elements.

Remarks

The binding-vector data structure contains a list of binding handles over which a server application can receive remote procedure calls.

The binding vector contains a count member (Count), followed by an array of binding-handle (BindingH) elements.

The RPC run-time library creates binding handles when a server application registers protocol sequences. To obtain a binding vector, a server application calls the RpcServerInqBindings routine.

A client application obtains a binding vector of compatible servers from the name-service database by calling the RpcNsBindingLookupNext routine.

In both routines, the RPC run-time library allocates memory for the binding vector. An application calls the RpcBindingVectorFree routine to free the binding vector.

To remove an individual binding handle from the vector, the application must set the value in the vector to NULL. When setting a vector element to NULL, the application must:

•	Free the individual binding

•	Not change the value of Count

Calling the RpcBindingFree routine allows an application to both free the unwanted binding handle and set the vector entry to a NULL value.

See Also

RpcBindingVectorFree, RpcEpRegister, RpcEpRegisterNoReplace, RpcEpUnregister, RpcNsBindingExport, RpcNsBindingLookupNext, RpcNsBindingSelect, RpcServerInqBindings


RPC_CLIENT_INTERFACE

Remarks

The RPC_CLIENT_INTERFACE data structure is part of the private interface between the run-time libraries and the stubs. Most distributed applications that use Microsoft RPC do not need this data structure.

The data structure is defined in the header file RPCDCEP.H.


RPC_DISPATCH_TABLE

Remarks

The RPC_DISPATCH_TABLE data structure is part of the private interface between the run-time libraries and the stubs. Most distributed applications that use Microsoft RPC do not need this data structure.

The data structure is defined in the header file RPCDCEP.H.


RPC_IF_HANDLE

typedef void *  RPC_IF_HANDLE;

Remarks

An interface handle is an opaque variable containing information the RPC run-time library uses to access the interface-specification data structure.

The MIDL compiler automatically creates an interface-specification data structure from each IDL file and creates a global variable of type RPC_IF_HANDLE for the interface specification.

The MIDL compiler includes an interface handle in each .H file generated for the interface.

Routines requiring the interface specification as an argument show a data type of RPC_IF_HANDLE.

The form of each interface handle name is as follows:

•	if-name_ClientIfHandle (for the client)

•	if-name_ServerIfHandle (for the server)

if-name

Specifies the interface identifier in the IDL file.

For example:

hello_ClientIfHandle

hello_ServerIfHandle

Note  The maximum length of the interface handle name is 31 characters.

Because the _ClientIfHandle and _ServerIfHandle parts of the names require 15 characters, the if-name element can be no more than 16 characters long.


RPC_IF_ID

typedef struct _RPC_IF_ID {

    UUID  Uuid;

    unsigned short  VersMajor;

    unsigned short  VersMinor;

}   RPC_IF_ID;

Uuid

Specifies the interface UUID.

VersMajor

Specifies the major version number, an integer from 0 to 65535, inclusive.

VersMinor

Specifies the minor version number, an integer from 0 to 65535, inclusive.

Remarks

The interface-identification (ID) data structure contains the interface UUID and major and minor version numbers of an interface. The interface identification is a subset of the data contained in the interface-specification structure.

Routines that require an interface ID structure show a data type of RPC_IF_ID. In those routines, the application is responsible for providing memory for the structure.

See Also

RpcIfInqId


RPC_IF_ID_VECTOR

typedef struct _RPC_IF_ID_VECTOR {

    unsigned long  Count;

    RPC_IF_ID *  IfHandl[1];

}   RPC_IF_ID_VECTOR;

Count

Specifies the number of interface-identification data structures present in the array IfHandl.

IfHandl

Specifies an array of pointers to interface-identification data structures that contains Count elements.

Remarks

The interface-identification (ID) vector data structure contains a list of interfaces offered by a server. The interface ID vector contains a count member (Count), followed by an array of pointers to interface IDs (RPC_IF_ID).

The interface ID vector is a read-only vector. To obtain a vector of the interface IDs registered by a server with the run-time library, an application calls the RpcMgmtInqIfIds routine. To obtain a vector of the interface IDs exported by a server, an application calls the RpcNsMgmtEntryInqIfIds routine.

The RPC run-time library allocates memory for the interface ID vector. The application calls the RpcIfIdVectorFree routine to free the interface ID vector.

See Also

RpcIfIdVectorFree, RpcMgmtInqIfIds, RpcNsMgmtEntryInqIfIds


RPC_MGR_EPV

typedef void RPC_MGR_EPV;

typedef _if-name_SERVER_EPV {
    return-type (* Functionname) (param-list);
    ...    // one entry for each function in IDL file
}   if-name_SERVER_EPV;

if-name

Specifies the name of the interface indicated in the IDL file.

return-type

Specifies the type returned by the function Functionname indicated in the IDL file.

Functionname

Specifies the name of the function indicated in the IDL file.

param-list

Specifies the arguments indicated for the function Functionname in the IDL file.

Remarks

The manager entry-point vector (EPV) is an array of function pointers. The array contains pointers to the implementations of the functions specified in the IDL file. The number of elements in the array is set to the number of functions specified in the IDL file. An application can also have multiple EPVs, representing multiple implementations of the functions specified in the interface.

The MIDL compiler generates a default EPV data type named if-name_SERVER_EPV, where if-name specifies the interface identifier in the IDL file. The MIDL compiler initializes this default EPV to contain function pointers for each of the procedures specified in the IDL file.

When the server offers multiple implementations of the same interface, the server application must declare and initialize one variable of type if-name_SERVER_EPV for each implementation of the interface. Each EPV must contain one entry point (function pointer) for each procedure defined in the IDL file.

See Also

RpcServerRegisterIfEx


RPC_NS_HANDLE

typedef void * RPC_NS_HANDLE;

Remarks

A name-service handle is an opaque variable containing information the RPC run-time library uses to return the following RPC data from the name-service database:

•	Server binding handles

•	UUIDs of resources offered by server profile members

•	Group members

The scope of a name-service handle is from a Begin routine through the corresponding Done routine.

Applications are responsible for concurrency control of name-service handles across threads.

See Also

RpcNsBindingImportBegin, RpcNsBindingImportDone, RpcNsBindingImportNext, RpcNsBindingLookupBegin, RpcNsBindingLookupDone, RpcNsBindingLookupNext


RPC_OBJECT_INQ_FN

typedef void RPC_OBJECT_INQ_FN(
    UUID *  ObjectUuid,
    UUID *  TypeUuid,
    RPC_STATUS *  Status
);

ObjectUuid

Points to the variable that specifies the object UUID that is to be mapped to a type UUID.

TypeUuid

Points to the address of the variable that is to contain the type UUID derived from the object UUID. The type UUID is returned by the function.

Status

Points to a return value for the function.

Remarks

The developer can replace the default mapping function that maps object UUIDs to type UUIDs by calling RpcObjectSetInqFn and supplying a pointer to a function of type RPC_OBJECT_INQ_FN. The supplied function must match the function prototype specified by the type definition: a function with three parameters and the function return value of void.

See Also

RpcObjectSetInqFn


RPC_POLICY

typedef struct _RPC_POLICY {

    unsigned int Length;

    unsigned long EndpointFlags;

    unsigned long NICFlags;

}   RPC_POLICY, __RPC_FAR  *  PRPC_POLICY;

Length

Specifies the size, in bytes, of the RPC_POLICY structure.

EndpointFlags

Specifies Internet or intranet (local network) ports for endpoint assignments.

NICFlags

Controls binding to network interface cards (NICs).

Remarks

The RPC_Policy structure contains flags that allow you to restrict port allocation for dynamic ports and that allow multihomed machines to selectively bind to Network Interface Cards (NICs). The values in this structure are ignored if the client and server are using a protocol other than tcp/ip (protocol sequence ncacn_ip_tcp). See Configuring the Windows NT Registry for Port Allocations and Selective Binding for a description of the registry settings that are affected by the RPC_POLICY flags.

The Length member allows compatibility with future versions of this structure, which may contain additional fields. Set Length = sizeof(RPC_POLICY) when initializing the RPC_POLICY structure in your code.

The EndpointFlags member controls endpoint assignments. Allowable values for this field are:

0	(Specifies the system default)
1	RPC_C_USE_INTERNET_PORT
2	RPC_C_USE_INTRANET_PORT
Note  If the registry does not contain any of the keys that specify the default policy for port allocation, then the EndpointFlags member will have no effect at run time. If a key is missing or contains an invalid value, then the entire configuration is marked as invalid and all RpcServerUseProtseq(ncacn_ip_tcp) calls will fail.

The NICFlags member tells RPC to either bind to NICs based on the settings in the registry, or to override the registry settings and bind to all NICs. Allowable values for this field are:

0	Bind to NICs on the basis of the registry settings
1	RPC_C_BIND_TO_ALL_NICS
Note  If the Bind key is missing from the registry, then the NICFlags member will have no effect at run time. If the key contains an invalid value, then the entire configuration is marked as invalid and all RpcServerUseProtseq*(ncacn_ip_tcp) calls will fail.

See Also

Configuring the Windows NT Registry for Port Allocations and Selective Binding, RpcServerUseAllProtseqsEx, RpcServerUseAllProtseqsIfEx, RpcServerUseProtseqEx, RpcServerUseProtseqEpEx, RpcServerUseProtseqIfEx


RPC_PROTSEQ_VECTOR

typedef struct _RPC_PROTSEQ_VECTOR {

    unsigned long  Count;

    unsigned char *  Protseq[1];

}   RPC_PROTSEQ_VECTOR;

Count

Specifies the number of protocol-sequence strings present in the array Protseq.

Protseq

Specifies an array of pointers to protocol-sequence strings. The number of pointers present is specified by the Count field.

Remarks

The protocol-sequence vector data structure contains a list of protocol sequences the RPC run-time library uses to send and receive remote procedure calls. The protocol-sequence vector contains a count member (Count), followed by an array of pointers to protocol-sequence strings (Protseq).

The protocol-sequence vector is a read-only vector. To obtain a protocol-sequence vector, a server application calls the RpcNetworkInqProtseqs routine. The RPC run-time library allocates memory for the protocol-sequence vector. The server application calls the RpcProtseqVectorFree routine to free the protocol-sequence vector.

See Also

RpcNetworkInqProtseqs, RpcProtseqVectorFree


RPC_STATS_VECTOR

typedef struct {

    unsigned int   Count;

    unsigned long  Stats[1];

}   RPC_STATS_VECTOR;

Count

Specifies the number of statistics values present in the array Stats.

Stats

Specifies an array of unsigned long integers representing server statistics that contains Count elements.

Remarks

The statistics vector contains statistics from the RPC run-time library on a per-server basis. The statistics vector contains a count member (Count), followed by an array of statistics. Each array element contains an unsigned long value. The following list describes the statistics indexed by the specified constant:

Constant	Statistics
RPC_C_STATS_CALLS_IN	The number of remote procedure calls received by the server
RPC_C_STATS_CALLS_OUT	The number of remote procedure calls initiated by the server
RPC_C_STATS_PKTS_IN	The number of network packets received by the server
RPC_C_STATS_PKTS_OUT	The number of network packets sent by the server
To obtain run-time statistics, an application calls the RpcMgmtInqStats routine. The RPC run-time library allocates memory for the statistics vector. The application calls the RpcMgmtStatsVectorFree routine to free the statistics vector.

See Also

RpcMgmtInqStats, RpcMgmtStatsVectorFree


RPC_STATUS

typedef long RPC_STATUS;  // Win32 definition
typedef unsigned short RPC_STATUS;  // MS-DOS, Win16 definition

Remarks

The type RPC_STATUS represents a platform-specific status code type. The RPC_STATUS type is returned by most RPC functions and is part of the RPC_OBJECT_INQ_FN function type definition.

See Also

RPC_OBJECT_INQ_FN


SEC_WINNT_AUTH_IDENTITY

For Windows 3.x and MS-DOS:

typedef struct _SEC_WINNT_AUTH_IDENTITY{

  char __RPC_FAR * User;

  char __RPC_FAR * Domain;

  char __RPC_FAR * Password;

} SEC_WINNT_AUTH_IDENTITY;

For Windows NT, Windows 95, and Macintosh:

typedef struct _SEC_WINNT_AUTH_IDENTITY {

  unsigned short __RPC_FAR * User;

  unsigned long UserLength;

  unsigned short __RPC_FAR * Domain;

  unsigned long DomainLength;

  unsigned short __RPC_FAR * Password;

  unsigned long PasswordLength;

  unsigned long Flags;                      //value may be 0x1 or 0x2

} SEC_WINNT_AUTH_IDENTITY, * PSEC_WINNT_AUTH_IDENTITY;

User

String containing the user name.

Domain

String containing the domain name or the workgroup name.

Password

String containing the user’s password in the domain or workgroup.

Flags

Long value specifying that the strings are ANSI (0x1) or Unicode (0x2).

Remarks

The SEC_WINNT_AUTH_IDENTITY structure allows you to pass a particular user name and password to the runtime library for the purpose of authentication. Note that this structure must remain valid for the lifetime of the binding handle.

For Windows 95, Windows 3.x and MS-DOS, the strings are ANSI; for Windows NT, the strings may be ANSI or Unicode, depending on the value you assign to the Flags field. For Windows NT, Windows 95, and Macintosh, the values for UserLength; DomainLength, and PasswordLength are the length of the corresponding string without the terminating 0X0000.


String Binding

ObjectUUID@ProtocolSequence:NetworkAddress[Endpoint,Option]

ObjectUUID

Specifies the UUID of the object operated on by the remote procedure call. At the server, the RPC run-time library maps the object type to a manager entry-point vector (an array of function pointers) to invoke the correct manager routine. For a discussion of how to map object UUIDs to manager entry-point vectors, see RpcServerRegisterIfEx.

Protocol Sequence

Specifies a character string that represents a valid combination of an RPC protocol (such as “ncacn”), a transport protocol (such as “tcp”), and a network protocol (such as “ip”). Microsoft RPC supports the following protocol sequences:

Protocol sequence	Description	Supporting Platforms
ncacn_nb_tcp	Connection-oriented NetBIOS over TCP	client only: MS-DOS, Windows 3.x client and server: Windows NT
ncacn_nb_ipx	Connection-oriented NetBIOS over IPX	client only: MS-DOS, Windows 3.x client and server: Windows NT
ncacn_nb_nb	Connection-oriented NetBEUI	client only: MS-DOS, Windows 3.x client and server: Windows NT, Windows 95
ncacn_ip_tcp	Connection-oriented TCP/IP	client only: MS-DOS,Windows 3.x, and Apple Macintosh client and server: Windows 95 and Windows NT
ncacn_np	Connection-oriented named pipes	client only: MS-DOS, Windows 3.x, Windows 95 client and server: Windows NT
ncacn_spx	Connection-oriented SPX	client only: MS-DOS, Windows 3.x client and server: Windows NT, Windows 95
ncacn_dnet_nsp	Connection-oriented DECnet transport	client only: MS-DOS, Windows 3.x
ncacn_at_dsp	AppleTalk DSP	client: Apple Macintosh server: Windows NT
ncacn_vns_spp	Connection-oriented Vines SPP transport	client only: MS-DOS, Windows 3.x client and server: Windows NT
ncadg_ip_udp	Datagram (connectionless) UDP/IP	client only: MS-DOS, Windows 3.x client and server: Windows NT
ncadg_ipx	Datagram (connectionless) IPX	client only: MS-DOS, Windows 3.x client and server: Windows NT
ncalrpc	Local procedure call	client and server: Windows NT and Windows 95
NetworkAddress

Specifies the network address of the system to receive remote procedure calls. The format and content of the network address depend on the specified protocol sequence as follows:

Protocol sequence	Network address	Examples
ncacn_nb_tcp	Windows NT machine name	myserver
ncacn_nb_ipx	Windows NT machine name	myserver
ncacn_nb_nb	Windows NT or Windows 95 machine name	myserver
ncacn_ip_tcp	four-octet internet address, or host name	128.10.2.30 anynode.microsoft.com
ncacn_np	Windows NT server name (leading double backslashes are optional)	myserver \\myotherserver
ncacn_spx	IPX internet address, or Windows NT server name	~0000000108002B30612C myserver
ncacn_dnet_nsp	Area and node syntax	4.120
ncacn_at_dsp	Windows NT machine name, optionally followed by @ and the AppleTalk zone name. Defaults to @*, the client’s zone, if no zone provided	servername@zonename servername
ncacn_vns_spp	StreetTalk server name of the form item@group@organization	printserver@sdkdocs@microsoft
ncadg_ip_udp	four-octet internet address, or host name	128.10.2.30 anynode.microsoft.com
ncadg_ipx	IPX internet address, or Windows NT server name	~0000000108002B30612C myserver
ncalrpc	Machine name	thismachine
The network-address field is optional. When you do not specify a network address, the string binding refers to your local host. It is possible to specify the name of the local machine when you use the ncalrpc protocol sequence, however doing so is completely unnecessary.

Endpoint

Specifies the endpoint, or address, of the process to receive remote procedure calls. An endpoint can be preceded by the keyword endpoint=. Specifying the endpoint is optional if the server has registered its bindings with the endpoint mapper. See RpcEpRegister.

The format and content of an endpoint depend on the specified protocol sequence as shown in the Endpoint/Option Table, below.

Option

Specifies protocol-specific options.. The option field is not required. Each option is specified by a {name, value} pair that uses the syntax option name=option value. Options are defined for each protocol sequence as shown in the Endpoint/Option Table, below.

Protocol sequence	Endpoint	Examples	Option name
ncacn_nb_tcp	Integer between 0 and 255. Many values between 0 and 32 are reserved by Microsoft.	100	None
ncacn_nb_ipx	(as above)	(as above)	None
ncacn_nb_nb	(as above)	(as above)	None
ncacn_ip_tcp	Internet port number	1025	None
ncacn_np	Windows NT named pipe. Name must start with “\\pipe”.	\\pipe\\pipename	Security  (NT only)
ncacn_spx	Integer between 1 and 65535.	5000	None
ncacn_dnet_nsp	DECnet phase IV object number (must be preceded by the # character), or object name	mailserver #17	None
ncacn_at_dsp	A character string, up to 22 bytes long	myservicesendpoint	None
ncacn_vns_spp	Vines SPP port number between 250 and 511	500	None
ncadg_ip_udp	Internet port number	1025	Security (32-bit only)
ncadg_ipx	Integer between 1 and 65535.	5000	Security (32-bit only)
ncalrpc	String specifying application or service name. The string cannot include any backslash characters.	my_printer	Security  (NT only)
The Security option name, supported for the ncalrpc, ncacn_np, ncadg_ip_udp, and ncadg_ipx protocol sequences, takes the following option values:

Option name	Option value
Security	{identification | anonymous | impersonation} {dynamic | static} {true | false}
If the Security option name is specified, one entry from each of the sets of Security option values must also be supplied. The option values must be separated by a single-space character. For example, the following Option fields are valid:

Security=identification dynamic true

Security=impersonation static true

The Security option values have the following meanings:

Security option value	Description
Anonymous	The client is anonymous to the server.
Dynamic	A pointer to the security token is maintained. Security settings represent current settings and include changes made after the endpoint was created.
False	Effective = FALSE; all Windows NT security settings, including those set to OFF, are included in the token.
Identification	The server has information about client but cannot impersonate.
Impersonation	The server is the client on the client’s behalf.
Static	Security settings associated with the endpoint represent a copy of the security information at the time the endpoint was created. The settings do not change.
True	Effective = TRUE; only Windows NT security settings set to ON are included in the token.
For more information about Microsoft Windows NT security options, see your Microsoft Windows NT programming documentation.

Remarks

The string binding is an unsigned character string composed of strings that represent the binding object UUID, the RPC protocol sequence, the network address, and the endpoint and endpoint options. White space is not allowed in string bindings except where required by the Option syntax.

Default settings for the NetworkAddress, Endpoint, and Option fields vary according to the value of the ProtocolSequence field.

For all string-binding fields, a single backslash character (\) is interpreted as an escape character. To specify a single literal backslash character, you must supply two backslash characters (\\).

The following are examples of valid string bindings. In these examples, obj-uuid is used for convenience to represent a valid UUID in string form. Instead of showing the UUID 308FB580-1EB2-11CA-923B-08002B1075A7, the examples show obj-uuid.

obj-uuid@ncacn_ip_tcp:16.20.16.27[2001]

obj-uuid@ncacn_ip_tcp:16.20.16.27[endpoint=2001]

obj-uuid@ncacn_nb_nb:

obj-uuid@ncacn_nb_nb:[100]

obj-uuid@ncacn_np:

obj-uuid@ncacn_np:[\\pipe\\p3,Security=impersonation static true]

obj-uuid@ncacn_np:\\\\marketing[\\pipe\\p2\\p3\\p4]

obj-uuid@ncacn_np:\\\\marketing[endpoint=\\pipe\\p2\\p3\\p4]

obj-uuid@ncacn_np:\\\\sales

obj-uuid@ncacn_np:\\\\sales[\\pipe\\p1,Security=identification dynamic true]

obj-uuid@ncalrpc:

obj-uuid@ncalrpc:[object1_name_demonstrating_that_these_can_be_lengthy]

obj-uuid@ncalrpc:[object2_name,Security=anonymous static true]

obj-uuid@ncacn_vns_spp:server@group@org[500]

obj-uuid@ncacn_dnet_nsp:took[elf_server]

obj-uuid@ncacn_dnet_nsp:took[endpoint=elf_server]

obj-uuid@ncadg_ip_udp:128.10.2.30

obj-uuid@ncadg_ip_udp:maryos.microsoft.com[1025]

obj-uuid@ncadg_ipx: ~0000000108002B30612C[5000]

obj-uuid@ncadg_ipx:printserver

obj-uuid@ncacn_spx:annaw[4390]

obj-uuid@ncacn_spx:~0000000108002B30612C

A string binding contains the character representation of a binding handle and sometimes portions of a binding handle. String bindings are convenient for representing portions of a binding handle, but they can’t be used for making remote procedure calls. They must first be converted to a binding handle by calling the RpcBindingFromStringBinding routine.

Additionally, a string binding does not contain all of the information from a binding handle. For example, the authentication information, if any, associated with a binding handle is not translated into the string binding returned by calling the RpcBindingToStringBinding routine.

During the development of a distributed application, servers can communicate their binding information to clients using string bindings to establish a client-server relationship without using the endpoint-map database or name-service database. To establish such a relationship, use the function RpcBindingToStringBinding to convert one or more binding handles from a binding-handle vector to a string binding, and provide the string binding to the client.

See Also

RpcBindingFromStringBinding, RpcBindingToStringBinding, RpcEpRegister


String UUID

A string UUID contains the character-array representation of a UUID. A string UUID is composed of multiple fields of hexadecimal characters. Each field has a fixed length, and fields are separated by the hyphen character. For example:

989C6E5C-2CC1-11CA-A044-08002B1BB4F5

When providing a string UUID as an input argument to a RPC run-time routine, enter the alphabetic hexadecimal characters as either uppercase or lowercase characters. However, when a run-time routine returns a string UUID, the hexadecimal characters are always lowercase.

See Also

UUID


UUID

typedef struct _GUID {

    unsigned long Data1;

    unsigned short Data2;

    unsigned short Data3;

    unsigned char Data4[8];

} GUID;

typedef GUID UUID;

#define uuid_t UUID

Data1

Specifies the first eight hexadecimal digits of the UUID.

Data2

Specifies the first group of four hexadecimal digits of the UUID.

Data3

Specifies the second group of four hexadecimal digits of the UUID.

Data4

Specifies an array of eight elements that contains the third and final group of four hexadecimal digits of the UUID in elements 0 and 1, and the final 12 hexadecimal digits of the UUID in elements 2 through 7.

Remarks

UUIDs uniquely identify objects such as interfaces, manager entry-point vectors, and client objects. The RPC run-time libraries use UUIDs to check for compatibility between clients and servers and to select among multiple implementations of an interface.

See Also

GUID, UUID_VECTOR


UUID_VECTOR

typedef struct _UUID_VECTOR {

    unsigned long  Count;

    UUID *  Uuid[1];

}   UUID_VECTOR;

Count

Specifies the number of UUIDs present in the array Uuid.

Uuid

Specifies an array of pointers to UUIDs that contains Count elements.

Remarks

The UUID vector data structure contains a list of UUIDs. The UUID vector contains a count member followed by an array of pointers to UUIDs.

An application constructs a UUID vector to contain object UUIDs to be exported or unexported from the name service.

See Also

RpcEpRegister, RpcEpRegisterNoReplace, RpcEpUnregister, RpcNsBindingExport, RpcNsBindingUnexport


Function Reference

This section contains an alphabetical list of the functions supported in this version of Microsoft RPC. The documentation for each function includes a statement about the function’s purpose, the syntax, a description of the function’s input parameters, a description of its values, and additional remarks that can help you use the function in an application.

All pointers passed to RPC functions must include the _ _RPC_FAR attribute. For example, the pointer RPC_BINDING_HANDLE * becomes RPC_BINDING_HANDLE _ _RPC_FAR * and char * * Ptr becomes char _ _RPC_FAR * _ _RPC_FAR * Ptr.


DceErrorInqText

The DceErrorInqText function returns the message text for a status code.

This function is supported by both 32-bit platforms — Windows NT and Windows 95. Note that it is supported in ANSI only on Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY DceErrorInqText(

unsigned long  StatusToConvert,
unsigned char *  ErrorText
);
Parameters

StatusToConvert

Specifies the status code to convert to a text string.

ErrorText

Returns the text corresponding to the error code.

Value	Meaning
RPC_S_OK	Operation completed successfully
RPC_S_INVALID_ARG	Unknown error code
Remarks

The DceErrorInqText routine returns a null-terminated character string message for a particular status code. If the call is not successful, DceErrorInqText returns a message as well as a failure code in Status.


MesBufferHandleReset

The MesBufferHandleReset function re-initializes the handle for buffer serialization.

#include <rpc.h>

#include <midles.h>

RPC_STATUS RPC_ENTRY MesBufferHandleReset(

handle_t  Handle,
unsigned long  HandleStyle,
MIDL_ES_CODE  OpCode,
char  *  *  ppBuffer,
unsigned long  BufferSize,
unsigned long *  pEncodedSize
);
Parameters

Handle

The handle to be initialized.

HandleStyle

Specifies the style of handle. Valid styles are MES_FIXED_BUFFER_HANDLE or MES_DYNAMIC_BUFFER_HANDLE.

OpCode

Specifies the operation. Valid operations are MES_ENCODE or MES_DECODE.

ppBuffer

For MES_DECODE, points to a pointer to the buffer containing the data to be decoded.

For MES_ENCODE, points to a pointer to the buffer for fixed buffer style, and points to a pointer to return the buffer address for dynamic buffer style.

BufferSize

Specifies the number of bytes of data to be decoded in the buffer. Note that this is used only for the fixed buffer style of serialization.

pEncodedSize

Points to the size of the completed encoding. Note that this is used only when the operation is MES_ENCODE.

Remarks

The MesBufferHandleReset routine is used by applications to re-initialize a buffer style handle and save memory allocations.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_ARG	Invalid argument
See Also

MesEncodeFixedBufferHandleCreate, MesEncodeDynBufferHandleCreate


MesDecodeBufferHandleCreate

The MesDecodeBufferHandleCreate function creates a decoding handle and initializes it for a (fixed) buffer style of serialization.

#include <rpc.h>

#include <midles.h>

RPC_STATUS RPC_ENTRY MesDecodeBufferHandleCreate(

char  *  Buffer,
unsigned long  BufferSize,
handle_t *  pHandle
);
Parameters

Buffer

Points to the buffer containing the data to decode.

BufferSize

Specifies the number of bytes of data to decode in the buffer.

pHandle

Points to the address to which the handle will be written.

Remarks

The MesDecodeBufferHandleCreate routine is used by applications to create a serialization handle and initialize the handle for the (fixed) buffer style of decoding. When using the fixed buffer style of decoding, the user supplies a single buffer containing all the encoded data. This buffer must have an address which is aligned at 8, and must be a multiple of 8 bytes in size. Further, it must be large enough to hold all of the data to decode.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_ARG	Invalid argument
RPC_S_OUT_OF_MEMORY	Out of memory
RPC_X_INVALID_BUFFER	Invalid buffer
See Also

MesEncodeFixedBufferHandleCreate, MesHandleFree


MesDecodeIncrementalHandleCreate

The MesDecodeIncrementalHandleCreate function creates a decoding handle for the incremental style of serialization.

#include <rpc.h>

#include <midles.h>

RPC_STATUS RPC_ENTRY MesDecodeIncrementalHandleCreate(

void *  UserState,
MIDL_ES_READ  ReadFn,
handle_t  *  pHandle
);
Parameters

UserState

Points to the user-supplied state object that coordinates the Alloc, Write, and Read routines.

ReadFn

Points to the Read routine.

pHandle

Pointer to the newly-created handle.

Remarks

The MesDecodeIncrementalHandleCreate routine is used by applications to create the handle and initialize it for the incremental style of decoding. When using the incremental style of decoding, the user supplies a Read routine to provide a buffer containing the next part of the data to be decoded. The buffer must be aligned at eight, and the size of the buffer must be a multiple of eight. For additional information on the user-supplied Alloc, Write and Read routines, see Using Encoding Services.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_ARG	Invalid argument
RPC_S_OUT_OF_MEMORY	Out of memory
See Also

MesIncrementalHandleReset, MesHandleFree


MesEncodeDynBufferHandleCreate

The MesEncodeDynBufferHandleCreate function creates an encoding handle and then initializes it for a dynamic buffer style of serialization.

#include <rpc.h>

#include <midles.h>

RPC_STATUS RPC_ENTRY MesEncodeDynBufferHandleCreate(

char  *  *  ppBuffer,
unsigned long  *  pEncodedSize,
handle_t *  pHandle
);
Parameters

ppBuffer

Points to a pointer to the stub-supplied buffer containing the encoding after serialization is complete.

pEncodedSize

Specifies a pointer to the size of the completed encoding. The size will be written to the pointee by the subsequent encoding operation(s).

pHandle

Points to the address to which the handle will be written.

Remarks

The MesEncodeDynBufferHandleCreate routine is used by applications to allocate the memory and initialize the handle for the dynamic buffer style of encoding. When using the dynamic buffer style of encoding, the buffer into which all the encoded data will be placed is supplied by the stub. This buffer will be allocated by the current client memory-management mechanism.

There can be performance implications when using this style for multiple encodings with the same handle. A single buffer is returned from an encoding and data is copied from intermediate buffers. The buffers are released when necessary.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_ARG	Invalid argument
RPC_S_OUT_OF_MEMORY	Out of memory
See Also

MesBufferHandleReset, MesHandleFree


MesEncodeFixedBufferHandleCreate

The MesEncodeFixedBufferHandleCreate function creates an encoding handle and then initializes it for a fixed buffer style of serialization.

#include <rpc.h>

#include <midles.h>

RPC_STATUS RPC_ENTRY MesEncodeFixedBufferHandleCreate(

char *  Buffer,
unsigned long  BufferSize,
unsigned long *  pEncodedSize,
handle_t *  pHandle
);
Parameters

Buffer

Points to the user-supplied buffer.

BufferSize

Specifies the size of the user-supplied buffer.

pEncodedSize

Specifies a pointer to the size of the completed encoding. The size will be written to the pointee by the subsequent encoding operation(s).

pHandle

Points to the newly-created handle.

Remarks

The MesEncodeFixedBufferHandleCreate routine is used by applications to create and initialize the handle for the fixed buffer style of encoding. When using the fixed buffer style of encoding, the user supplies a single buffer into which all the encoded data is placed. This buffer must have an address which is aligned at eight, and must be a multiple of eight bytes in size. Further, it must be large enough to hold an encoding of all the data, along with an encoding header for each routine being encoded.

When the handle is used for multiple encoding operations, the encoded size is cumulative.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_ARG	Invalid argument
RPC_S_OUT_OF_MEMORY	Out of memory
See Also

MesDecodeBufferHandleCreate, MesHandleFree


MesEncodeIncrementalHandleCreate

The MesEncodeIncrementalHandleCreate function creates an encoding and then initializes it for the incremental style of serialization.

#include <rpc.h>

#include <midles.h>

RPC_STATUS RPC_ENTRY MesEncodeIncrementalHandleCreate(

void *  UserState,
MIDL_ES_ALLOC  AllocFn,
MIDL_ES_WRITE  WriteFn,
handle_t  *  pHandle
);
Parameters

UserState

Points to the user-supplied state object that coordinates the Alloc, Write, and Read routines.

AllocFn

Points to the Alloc routine.

WriteFn

Points to the Write routine.

pHandle

Points to the newly-created handle.

Remarks

The MesEncodeIncrementalHandleCreate routine is used by applications to create and initialize the handle for the incremental style of encoding or decoding. When using the incremental style of encoding, the user supplies an Alloc routine to provide an empty buffer into which the encoded data is placed, and a Write routine to call when the buffer is full or the encoding is complete. For additional information on the user-supplied Alloc, Write and Read routines, see Using Encoding Services.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_ARG	Invalid argument
RPC_S_OUT_OF_MEMORY	Out of memory
See Also

MesIncrementalHandleReset, MesHandleFree


MesHandleFree

The MesHandleFree function frees the memory allocated by the serialization handle.

#include <rpc.h>

#include <midles.h>

RPC_STATUS RPC_ENTRY MesHandleFree(

handle_t  Handle
);
Parameters

Handle

The handle to be freed.

Remarks

The MesHandleFree routine is used by applications to free the resources of the handle after encoding or decoding data.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

MesEncodeFixedBufferHandleCreate, MesDecodeBufferHandleCreate, MesEncodeDynBufferHandleCreate, MesEncodeIncrementalHandleCreate


MesIncrementalHandleReset

The MesIncrementalHandleReset function re-initializes the handle for incremental serialization.

#include <rpc.h>

#include <midles.h>

RPC_STATUS RPC_ENTRY MesIncrementalHandleReset(

handle_t  Handle,
void  *  UserState,
MIDL_ES_ALLOC  AllocFn,
MIDL_ES_WRITE  WriteFn,
MIDL_ES_READ  ReadFn,
MIDL_ES_CODE  OpCode
);
Parameters

Handle

The handle to be re-initialized.

UserState

Depending on the function, points to the user-supplied block that coordinates successive calls to the Alloc, Write, and Read routines.

AllocFn

Points to the Alloc routine. This argument can be NULL if the operation does not require it, or if the handle was previously initiated with the pointer.

WriteFn

Points to the Write routine. This argument can be NULL if the operation does not require it, or if the handle was previously initiated with the pointer.

ReadFn

Points to the Read routine. This argument can be NULL if the operation does not require it, or if the handle was previously initiated with the pointer.

OpCode

Specifies the operation. Valid operations are MES_ENCODE or MES_DECODE.

Remarks

The MesIncrementalHandleReset routine is used by applications to re-initialize the handle for the incremental style of encoding or decoding. For additional information on the user-supplied Alloc, Write and Read routines, see Using Encoding Services.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_ARG	Invalid argument
RPC_S_OUT_OF_MEMORY	Out of memory
See Also

MesEncodeIncrementalHandleCreate, MesHandleFree


MesInqProcEncodingId

The MesInqProcEncodingId function provides the identity of an encoding.

#include <rpc.h>

#include <midles.h>

RPC_STATUS RPC_ENTRY MesInqProcEncodingId(

handle_t  Handle,
PRPC_SYNTAX_IDENTIFIER  pInterfaceId,
unsigned long  *  pProcNum
);
Parameters

Handle

Specifies an encoding or decoding handle.

pInterfaceId

Points to the address in which the identity of the interface used to encode the data will be written. pInterfaceId consists of the interface UUID and the version number.

pProcNum

Specifies the number of the routine used to encode the data.

Remarks

The MesInqProcEncodingId routine is used by applications to obtain the identity of the routine used to encode the data before calling a routine to decode it. When called with an encoding handle, it returns the identity of the last encoding operation. When called with a decoding handle, it returns the identity of the next decoding operation by pre-reading the buffer.

This routine can only be used to check the identity of a procedure encoding; it cannot be used to check the identity for a type encoding.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_ARG	Invalid argument
RPC_S_OUT_OF_MEMORY	Out of memory
RPC_S_UNKNOWN_IF	Unknown interface
RPC_S_UNSUPPORTED_TRANS_SYN	Transfer syntax not supported by server
RPC_X_INVALID_ES_ACTION	Invalid operation for a given handle
RPC_X_WRONG_ES_VERSION	Incompatible version of the serializing package
RPC_X_SS_INVALID_BUFFER	Invalid buffer


RpcAbnormalTermination

The RpcAbnormalTermination function determines whether termination statements are being executed due to an exception or not.

#include <rpc.h>

void RpcAbnormalTermination(VOID);

Remarks

The RpcAbnormalTermination function should only be called from within the termination-statements section of an RpcFinally termination handler.

Return Values

Value	Meaning	Description
Zero	No exception	Termination statements are not being executed due to an exception
Nonzero	Exception	Termination statements are being executed due to an exception
See Also

RpcFinally


RpcBindingCopy

The RpcBindingCopy function copies binding information and creates a new binding handle.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcBindingCopy(

RPC_BINDING_HANDLE  SourceBinding,
RPC_BINDING_HANDLE *  DestinationBinding
);
Parameters

SourceBinding

Specifies the server binding handle whose referenced binding information is copied.

DestinationBinding

Returns a pointer to the server binding handle that refers to the copied binding information.

Remarks

Note  Microsoft RPC supports RpcBindingCopy only in client applications, not in server applications.

The RpcBindingCopy routine copies the server-binding information referenced by the SourceBinding argument. RpcBindingCopy uses the DestinationBinding argument to return a new server binding handle for the copied binding information. RpcBindingCopy also copies the authentication information from the SourceBinding argument to the DestinationBinding argument.

An application uses RpcBindingCopy when it wants to keep a change made to binding information by one thread from affecting the binding information used by other threads.

Once an application calls RpcBindingCopy, operations performed on the SourceBinding binding handle do not affect the binding information referenced by the DestinationBinding binding handle. Similarly, operations performed on the DestinationBinding binding handle do not affect the binding information referenced by the SourceBinding binding handle.

If an application wants one thread’s changes to binding information to affect the binding information used by other threads, the application should share a single binding handle across the threads. In this case, the application is responsible for binding-handle concurrency control.

When an application is finished using the binding handle specified by the DestinationBinding argument, the application should call the RpcBindingFree routine to release the memory used by the DestinationBinding binding handle and its referenced binding information.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
See Also

RpcBindingFree


RpcBindingFree

The RpcBindingFree function releases binding-handle resources.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcBindingFree(

RPC_BINDING_HANDLE *  Binding
);
Parameters

Binding

Points to the server binding to free.

Remarks

Note  Microsoft RPC supports RpcBindingFree only in client applications, not in server applications.

The RpcBindingFree routine releases memory used by a server binding handle. Referenced binding information that was dynamically created during program execution is released as well. An application calls the RpcBindingFree routine when it is finished using the binding handle.

Binding handles are dynamically created by calling the following routines:

•	RpcBindingCopy

•	RpcBindingFromStringBinding

•	RpcServerInqBindings

•	RpcNsBindingImportNext

•	RpcNsBindingSelect

If the operation successfully frees the binding, the Binding argument returns a value of NULL.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
See Also

RpcBindingCopy, RpcBindingFromStringBinding, RpcBindingVectorFree, RpcNsBindingImportNext, RpcNsBindingLookupNext, RpcNsBindingSelect, RpcServerInqBindings


RpcBindingFromStringBinding

The RpcBindingFromStringBinding function returns a binding handle from a string representation of a binding handle.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcBindingFromStringBinding(

unsigned char *  StringBinding,
RPC_BINDING_HANDLE *  Binding
);
Parameters

StringBinding

Points to a string representation of a binding handle.

Binding

Returns a pointer to the server binding handle.

Remarks

The RpcBindingFromStringBinding routine creates a server binding handle from a string representation of a binding handle.

The StringBinding argument does not have to contain an object UUID. In this case, the returned binding contains a nil UUID.

If the provided StringBinding argument does not contain an endpoint field, the returned Binding argument is a partially bound binding handle.

If the provided StringBinding argument contains an endpoint field, the endpoint is considered to be a well-known endpoint.

If the provided StringBinding argument does not contain a host address field, the returned Binding argument references the local host.

An application creates a string binding by calling the RpcStringBindingCompose routine or by providing a character-string constant.

When an application is finished using the Binding argument, the application should call the RpcBindingFree routine to release the memory used by the binding handle.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_STRING_BINDING	Invalid string binding
RPC_S_PROTSEQ_NOT_SUPPORTED	Protocol sequence not supported on this host
RPC_S_INVALID_RPC_PROTSEQ	Invalid protocol sequence
RPC_S_INVALID_ENDPOINT_FORMAT	Invalid endpoint format
RPC_S_STRING_TOO_LONG	String too long
RPC_S_INVALID_NET_ADDR	Invalid network address
RPC_S_INVALID_ARG	Invalid argument
RPC_S_INVALID_NAF_ID	Invalid network-address-family ID
See Also

RpcBindingCopy, RpcBindingFree, RpcBindingToStringBinding, RpcStringBindingCompose


RpcBindingInqAuthClient

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcBindingInqAuthClient(

RPC_BINDING_HANDLE  ClientBinding,
RPC_AUTHZ_HANDLE *  Privs,
unsigned char * *  ServerPrincName,
unsigned long *  AuthnLevel,
unsigned long *  AuthnSvc,
unsigned long *  AuthzSvc
);
Parameters

ClientBinding

Specifies the client binding handle of the client that made the remote procedure call. This value can be zero (see Remarks).

Privs

Returns a pointer to a handle to the privileged information for the client application that made the remote procedure call on the ClientBinding binding handle.

The server application must cast the ClientBinding binding handle to the data type specified by the AuthzSvc argument. The data referenced by this argument is read-only and should not be modified by the server application. If the server wants to preserve any of the returned data, the server must copy the data into server-allocated memory. This parameter is not used by the RPC_C_AUTHN_WINNT authentication service. The returned pointer will always be NULL.

ServerPrincName

Returns a pointer to a pointer to the server principal name specified by the client application that made the remote procedure call on the ClientBinding binding handle. The content of the returned name and its syntax are defined by the authentication service in use.

Specify a null value to prevent RpcBindingInqAuthClient from returning the ServerPrincName argument. In this case, the application does not call the RpcStringFree routine.

AuthnLevel

Returns a pointer to the level of authentication requested by the client application that made the remote procedure call on the ClientBinding binding handle.

Specify a null value to prevent RpcBindingInqAuthClient from returning the AuthnLevel argument.

AuthnSvc

Returns a pointer to the authentication service requested by the client application that made the remote procedure call on the ClientBinding binding handle. For a list of the RPC-supported authentication levels, see Authentication-Level Constants.

Specify a null value to prevent RpcBindingInqAuthClient from returning the AuthnSvc argument. This parameter is not used by the RPC_C_AUTHN_WINNT authentication service. The returned value will always be RPC_S_AUTHZ_NONE.

AuthzSvc

Returns a pointer to the authorization service requested by the client application that made the remote procedure call on the Binding binding handle. For a list of possible returns, see RpcMgmtInqDefaultProtectLevel.

Specify a null value to prevent RpcBindingInqAuthClient from returning the AuthnSvc argument.

Remarks

A server application calls the RpcBindingInqAuthClient routine to obtain the principal name or privilege attributes of the authenticated client that made the remote procedure call. In addition, RpcBindingInqAuthClient returns the authentication service, authentication level, and server principal name specified by the client. The server can use the returned data for authorization purposes.

The RPC run-time library allocates memory for the returned ServerPrincName argument. The application is responsible for calling the RpcStringFree routine for the returned argument string.

For clients using the MIDL auto_handle or implicit_handle attribute, the server application should use zero as the value for the ClientBinding parameter. Using zero retrieves the authentication and authorization information from the currently executing remote procedure call.

Return Values

value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
RPC_S_BINDING_HAS_NO_AUTH	Binding has no authentication information
See Also

RpcBindingSetAuthInfo, RpcStringFree


RpcBindingInqAuthInfo

The RpcBindingInqAuthInfo function returns authentication and authorization information from a binding handle.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcBindingInqAuthInfo(

RPC_BINDING_HANDLE  Binding,
unsigned char * *  ServerPrincName,
unsigned long *  AuthnLevel,
unsigned long *  AuthnSvc,
RPC_AUTH_IDENTITY_HANDLE *  AuthIdentity,
unsigned long *  AuthzSvc
);
Parameters

Binding

Specifies the server binding handle from which authentication and authorization information is returned.

ServerPrincName

Returns a pointer to a pointer to the expected principal name of the server referenced in the Binding argument. The content of the returned name and its syntax are defined by the authentication service in use.

Specify a null value to prevent RpcBindingInqAuthInfo from returning the ServerPrincName argument. In this case, the application does not call the RpcStringFree routine.

AuthnLevel

Returns a pointer to the level of authentication used for remote procedure calls made using the Binding binding handle.  For a list of the RPC-supported authentication levels, see Authentication-Level Constants. Specify a null value to prevent the routine from returning the AuthnLevel argument.

The level returned in the AuthnLevel argument may be different from the level specified when the client called the RpcBindingSetAuthInfo routine. This discrepancy happens when the authentication level specified by the client was not supported by the RPC run-time library and the run-time library automatically upgraded to the next higher level.

AuthnSvc

Returns a pointer to the authentication service specified for remote procedure calls made using the Binding binding handle.  For a list of the RPC-supported authentication services, see Authentication-Service Constants.

Specify a null value to prevent RpcBindingInqAuthInfo from returning the AuthnSvc argument.

AuthIdentity

Returns a pointer to a handle to the data structure that contains the client’s authentication and authorization credentials specified for remote procedure calls made using the Binding binding handle.

Specify a null value to prevent RpcBindingInqAuthInfo from returning the AuthIdentity argument.

AuthzSvc

Returns a pointer to the authorization service requested by the client application that made the remote procedure call on the Binding binding handle.  For a list of the RPC-supported authentication services, see Authentication-Service Constants.

Specify a null value to prevent RpcBindingInqAuthInfo from returning the AuthzSvc argument.

Remarks

A client application calls the RpcBindingInqAuthInfo routine to view the authentication and authorization information associated with a server binding handle. The client specifies the data by calling the RpcBindingSetAuthInfo routine.

The RPC run-time library allocates memory for the returned ServerPrincName argument. The application is responsible for calling the RpcStringFree routine for that returned argument string.

When a client application does not know a server’s principal name, calling RpcBindingInqAuthInfo after making a remote procedure call provides the server’s principal name. For example, clients that import from a group or profile may not know a server’s principal name when calling the RpcBindingSetAuthInfo routine.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
RPC_BINDING_HAS_NO_AUTH	Binding has no authentication information
See Also

RpcBindingSetAuthInfo, RpcStringFree


RpcBindingInqObject

The RpcBindingInqObject function returns the object UUID from a binding handle.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcBindingInqObject(

RPC_BINDING_HANDLE  Binding,
UUID *  ObjectUuid
);
Parameters

Binding

Specifies a client or server binding handle.

ObjectUuid

Returns a pointer to the object UUID found in the Binding argument. ObjectUuid is a unique identifier of an object to which a remote procedure call can be made.

Remarks

An application calls the RpcBindingInqObject routine to see the object UUID associated with a client or server binding handle.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
See Also

RpcBindingSetObject


RpcBindingReset

The RpcBindingReset function resets a binding handle so that the host is specified but the server on that host is unspecified.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcBindingReset(

RPC_BINDING_HANDLE Binding
);
Parameters

Binding

Specifies the server binding handle to reset.

Remarks

A client calls the RpcBindingReset routine to disassociate a particular server instance from the server binding handle specified in the Binding argument. The RpcBindingReset routine dissociates a server instance by removing the endpoint portion of the server address in the binding handle. The host remains unchanged in the binding handle. The result is a partially bound server binding handle.

RpcBindingReset does not affect the Binding argument’s authentication information, if there is any.

If a client is willing to be serviced by any compatible server instance on the host specified in the binding handle, the client calls the RpcBindingReset routine before making a remote procedure call using the Binding binding handle.

When the client makes the next remote procedure call using the reset (partially bound) binding, the client’s RPC run-time library uses a well-known endpoint from the client’s interface specification, if any. Otherwise, the client’s run-time library automatically communicates with the endpoint-mapping service on the specified remote host to obtain the endpoint of a compatible server from the endpoint-map database. If a compatible server is located, the RPC run-time library updates the binding with a new endpoint. If a compatible server is not found, the remote procedure call fails. For calls using a connection protocol (ncacn), the RPC_S_NO_ENDPOINT_FOUND status code is returned to the client. For calls using a datagram protocol (ncadg), the RPC_S_COMM_FAILURE status code is returned to the client.

Server applications should register all binding handles by calling RpcEpRegister and RpcEpRegisterNoReplace if the server wants to be available to clients that make a remote procedure call on a reset binding handle.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
See Also

RpcEpRegister, RpcEpRegisterNoReplace


RpcBindingServerFromClient

The RpcBindingServerFromClient function converts a client binding handle to a server binding handle.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcBindingServerFromClient(

RPC_BINDING_HANDLE  ClientBinding,
RPC_BINDING_HANDLE *  ServerBinding
);
Parameters

ClientBinding

Specifies the client binding handle to convert to a server binding handle.

ServerBinding

Returns a server binding handle.

Remarks

An application calls the RpcBindingServerFromClient routine to convert a client binding handle into a partially-bound server binding handle.

The RpcBindingServerFromClient routine is supported for the following protocol sequences:

•	ncadg_ip_udp

•	ncadg_ipx

•	ncacn_ip_tcp

•	ncacn_spx.

An application gets a client binding handle from the RPC runtime. When the RPC arrives at a server, the runtime creates a client binding handle that contains information about the calling client. This handle is passed by the runtime to the server manager routine as the first argument.

The following information pertains to the server binding handle that is returned by RpcBindingServerFromClient:

•	The returned handle is a partially bound handle. It contains a network address for the calling client, but lacks an endpoint.

•	The returned handle contains the same object UUID used by the calling client. This can be the nil UUID. For more information on how a client specifies an object UUID for a call, see RpcBindingsetObject, RpcNsBindingImportBegin, RpcNsBindingLookupBegin, and RpcBindingFromStringBinding.

•	The returned handle contains no authentication information.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
RPC_S_CANNOT_SUPPORT	Cannot determine the client’s host (not TCP or SPX)
See Also

RpcBindingFree, RpcBindingSetObject, RpcEpRegister, RpcEpRegisterNoReplace, RpcNsBindingImportBegin, RpcNsBindingLookupBegin, RpcBindingFromStringBinding


RpcBindingSetAuthInfo

The RpcBindingSetAuthInfo function sets authentication and authorization information into a binding handle.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcBindingSetAuthInfo(

RPC_BINDING_HANDLE  Binding,
unsigned char *  ServerPrincName,
unsigned long  AuthnLevel,
unsigned long  AuthnSvc,
RPC_AUTH_IDENTITY_HANDLE  AuthIdentity,
unsigned long  AuthzSvc
);
Parameters

Binding

Specifies the server binding handle into which authentication and authorization information is set.

ServerPrincName

Points to the expected principal name of the server referenced by the binding handle specified in the Binding argument. The content of the name and its syntax are defined by the authentication service in use.

AuthnLevel

Specifies the level of authentication to be performed on remote procedure calls made using the Binding binding handle.  For a list of the RPC-supported authentication levels, see Authentication-Level Constants.

AuthnSvc

Specifies the authentication service to use.  For a list of the RPC-supported authentication services, see Authentication-Service Constants.

Specify RPC_C_AUTHN_NONE to turn off authentication for remote procedure calls made using the Binding binding handle.

If RPC_C_AUTHN_DEFAULT is specified, the RPC run-time library uses the RPC_C_AUTHN_WINNT authentication service for remote procedure calls made using the Binding binding handle.

AuthIdentity

Specifies a handle for the data structure that contains the client’s authentication and authorization credentials appropriate for the selected authentication and authorization service.

When using the RPC_C_AUTHN.WINNT authentication service AuthIdentity should be a pointer to a SEC_WINNT_AUTH_IDENTITY structure (defined in rpcdce.h).

Specify a null value to use the security login context for the current address space.

AuthzSvc

Specifies the authorization service implemented by the server for the interface of interest. The validity and trustworthiness of authorization data, like any application data, depends on the authentication service and authentication level selected. This parameter is ignored when using the RPC_C_AUTHN_WINNT authentication service.

 For a list of the RPC-supported authentication services, see Authentication-Service Constants.

Remarks

A client application calls the RpcBindingSetAuthInfo routine to set up a server binding handle for making authenticated remote procedure calls.

Unless a client calls RpcBindingSetAuthInfo, all remote procedure calls on the Binding binding handle are unathenticated. A client is not required to call this routine.

Note  As long as the binding handle exists, RPC maintains a pointer to AuthIdentity. Be sure it is not on the stack and is not freed until the binding handle is freed. If the binding handle is copied, or if a context handle is created from the binding handle, then the AuthIdentity pointer will also be copied.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
RPC_S_UNKNOWN_AUTHN_SERVICE	Unknown authentication service
See Also

RpcBindingInqAuthInfo, RpcServerRegisterAuthInfo


RpcBindingSetObject

The RpcBindingSetObject function sets the object UUID value in a binding handle.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcBindingSetObject(

RPC_BINDING_HANDLE  Binding,
UUID *  ObjectUuid
);
Parameters

Binding

Specifies the server binding into which the ObjectUuid is set.

ObjectUuid

Points to the UUID of the object serviced by the server specified in the Binding argument. ObjectUuid is a unique identifier of an object to which a remote procedure call can be made.

Remarks

An application calls the RpcBindingSetObject routine to associate an object UUID with a server binding handle. The set-object operation replaces the previously associated object UUID with the UUID in the ObjectUuid argument.

To set the object UUID to the nil UUID, specify a null value or the nil UUID for the ObjectUuid argument.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
See Also

RpcBindingFromStringBinding, RpcBindingInqObject


RpcBindingToStringBinding

The RpcBindingToStringBinding function returns a string representation of a binding handle.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcBindingToStringBinding(

RPC_BINDING_HANDLE  Binding,
unsigned char * *  StringBinding
);
Parameters

Binding

Specifies a client or server binding handle to convert to a string representation of a binding handle.

StringBinding

Returns a pointer to a pointer to the string representation of the binding handle specified in the Binding argument.

Specify a null value to prevent RpcBindingToStringBinding from returning the StringBinding argument. In this case, the application does not call the RpcStringFree routine.

Remarks

The RpcBindingToStringBinding routine converts a client or server binding handle to its string representation.

The RPC run-time library allocates memory for the string returned in the StringBinding argument. The application is responsible for calling the RpcStringFree routine to deallocate that memory.

If the binding handle in the Binding argument contained a nil object UUID, the object UUID field is not included in the returned string.

To parse the returned StringBinding argument, call the RpcStringBindingParse routine.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
See Also

RpcBindingFromStringBinding, RpcStringBindingParse, RpcStringFree


RpcBindingVectorFree

The RpcBindingVectorFree function frees the binding handles contained in the vector and the vector itself.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcBindingVectorFree(

RPC_BINDING_VECTOR * *  BindingVector
);
Parameters

BindingVector

Points to a pointer to a vector of server binding handles. On return, the pointer is set to NULL.

Remarks

An application calls the RpcBindingVectorFree routine to release the memory used to store a vector of server binding handles. The routine frees both the binding handles and the vector itself.

A server obtains a vector of binding handles by calling the RpcServerInqBindings routine. A client obtains a vector of binding handles by calling the RpcNsBindingLookupNext routine.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_ARG	Invalid argument
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
See Also

RpcNsBindingLookupNext, RpcServerInqBindings


RpcCancelThread

The RpcCancelThread function cancels a thread.

This function is supported only by Windows NT.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcCancelThread(

HANDLE  ThreadHandle
);
Parameters

ThreadHandle

Specifies the handle of the thread to cancel.

Remarks

The RpcCancelThread routine allows one client thread to cancel an RPC in progress on another client thread. When the routine is called, the server runtime is informed of the cancel operation. The server stub can determine if the call has been cancelled by calling RpcTestCancel. If the call has been cancelled, the server stub should clean up and return control to the client.

By default, the client waits forever for the server to return control after a cancel. To reduce this time, call RpcMgmtSetCancelTimeout, specifying the number of seconds to wait for a response. If the server does not return within this interval, the call fails at the client with an RPC_S_CALL_FAILED exception. The server stub continues to execute.

Note  This routine is only supported for Windows NT clients.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_ACCESS_DENIED	Thread handle does not have privilege
RPC_S_CANNOT_SUPPORT	Called by an MS-DOS or Windows 3.x client


RpcEndExcept

See

RpcExcept


RpcEndFinally

See

RpcFinally


RpcEpRegister

The RpcEpRegister function adds to or replaces server address information in the local endpoint-map database.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcEpRegister(

RPC_IF_HANDLE  IfSpec,
RPC_BINDING_VECTOR *  BindingVector,
UUID_VECTOR *  UuidVector,
unsigned char *  Annotation
);
Parameters

IfSpec

Specifies an interface to register with the local endpoint-map database.

BindingVector

Points to a vector of binding handles over which the server can receive remote procedure calls.

UuidVector

Points to a vector of object UUIDs offered by the server. The server application constructs this vector.

A null argument value indicates there are no object UUIDs to register.

Annotation

Points to the character-string comment applied to each cross-product element added to the local endpoint-map database. The string can be up to 64 characters long, including the null terminating character. Specify a null value or a null-terminated string (“\0”) if there is no annotation string.

The annotation string is used by applications for information only. RPC does not use this string to determine which server instance a client communicates with or for enumerating elements in the endpoint-map database.

Remarks

The RpcEpRegister routine adds or replaces entries in the local host’s endpoint-map database. For an existing database entry that matches the provided interface specification, binding handle, and object UUID, this routine replaces the entry’s endpoint with the endpoint in the provided binding handle.

A server uses RpcEpRegister rather than RpcEpRegisterNoReplace when only a single instance of the server will run on the server’s host. In other words, use this routine when no more than one server instance will offer the same interface UUID, object UUID, and protocol sequence at any one time.

When entries are not replaced, stale data accumulates each time a server instance stops running without calling RpcEpUnregister. Stale entries increase the likelihood that a client will receive endpoints to nonexistent servers. The client will spend time trying to communicate with a nonexistent server before obtaining another endpoint.

Using RpcEpRegister to replace existing endpoint-map database entries reduces the likelihood that a client will be given the endpoint of a nonexistent server instance. A server application calls this routine to register endpoints specified by calling any of the following routines:

•	RpcServerUseAllProtseqs

•	RpcServerUseProtseq

•	RpcServerUseProtseqEp

A server that calls only RpcServerUseAllProtseqsIf or RpcServerUseProtseqIf does not need to call RpcEpRegister. In this case, the client’s run-time library uses an endpoint from the client’s interface specification to fill in a partially bound binding handle.

If the server also exports to the name-service database, the server calls RpcEpRegister with the same IfSpec, BindingVector, and UuidVector that the server uses when calling the RpcNsBindingExport routine.

For automatically started servers running over one of the connection-based protocol sequences (ncacn_np, ncacn_nb, ncacn_ip_tcp, ncacn_osi_dns), the RPC run-time library automatically generates a dynamic endpoint. In this case, the server can call RpcServerInqBindings followed by RpcEpRegister to make itself available to multiple clients. Otherwise, the automatically started server is known only to the client for which the server was started.

Each element added to the endpoint-map database logically contains the following:

•	Interface UUID

•	Interface version (major and minor)

•	Binding handle

•	Object UUID (optional)

•	Annotation (optional)

RpcEpRegister creates a cross-product from the IfSpec, BindingVector, and UuidVector arguments and adds each element in the cross-product as a separate registration in the endpoint-map database.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NO_BINDINGS	No bindings
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
See Also

RpcBindingFromStringBinding, RpcEpRegisterNoReplace, RpcEpUnregister, RpcNsBindingExport, RpcServerInqBindings, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf


RpcEpRegisterNoReplace

The RpcEpRegisterNoReplace function adds server-address information to the local endpoint-map database.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcEpRegisterNoReplace(

RPC_IF_HANDLE  IfSpec,
RPC_BINDING_VECTOR *  BindingVector,
UUID_VECTOR *  UuidVector,
unsigned char *  Annotation
);
Parameters

IfSpec

Specifies an interface to register with the local endpoint-map database.

BindingVector

Points to a vector of binding handles over which the server can receive remote procedure calls.

UuidVector

Points to a vector of object UUIDs offered by the server. The server application constructs this vector.

A null argument value indicates there are no object UUIDs to register.

Annotation

Points to the character-string comment applied to each cross-product element added to the local endpoint-map database. The string can be up to 64 characters long, including the null terminating character. Specify a null value or a null-terminated string (“\0”) if there is no annotation string.

The annotation string is used by applications for information only. RPC does not use this string to determine which server instance a client communicates with or to enumerate elements in the endpoint-map database.

Remarks

The RpcEpRegisterNoReplace routine adds entries to the local host’s endpoint-map database. This routine does not replace existing database entries.

A server uses RpcEpRegisterNoReplace rather than RpcEpRegister when multiple instances of the server will run on the same host. In other words, use this routine when more than one server instance will offer the same interface UUID, object UUID, and protocol sequence at any one time.

Because entries are not replaced when calling RpcEpRegisterNoReplace, servers must unregister themselves before they stop running. Otherwise, stale data accumulates each time a server instance stops running without calling RpcEpUnregister. Stale entries increase the likelihood that a client will receive endpoints to nonexistent servers. The client will spend time trying to communicate with a nonexistent server before obtaining another endpoint.

A server application calls RpcEpRegisterNoReplace to register endpoints specified by calling any of the following routines:

•	RpcServerUseAllProtseqs

•	RpcServerUseProtseq

•	RpcServerUseProtseqEp

A server that calls only RpcServerUseAllProtseqsIf or RpcServerUseProtseqIf is not required to call RpcEpRegisterNoReplace. In this case, the client’s run-time library uses an endpoint from the client’s interface specification to fill in a partially bound binding handle.

If the server also exports to the name-service database, the server calls RpcEpRegisterNoReplace with the same IfSpec, BindingVector, and UuidVector arguments that the server uses when calling the RpcNsBindingExport routine.

For automatically started servers running over one of the connection-based protocol sequences (ncacn_np, ncacn_nb, ncacn_ip_tcp, ncacn_osi_dns), the RPC run-time library automatically generates a dynamic endpoint. In this case, the server can call RpcServerInqBindings followed by RpcEpRegisterNoReplace to make itself available to multiple clients. Otherwise, the automatically started server is known only to the client for which the server was started.

Each element added to the endpoint-map database logically contains the following:

•	Interface UUID

•	Interface version (major and minor)

•	Binding handle

•	Object UUID (optional)

•	Annotation (optional)

RpcEpRegisterNoReplace creates a cross-product from the IfSpec, BindingVector, and UuidVector arguments and adds each element in the cross-product as a separate registration in the endpoint-map database.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NO_BINDINGS	No bindings
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
See Also

RpcBindingFromStringBinding, RpcEpRegister, RpcEpUnregister, RpcNsBindingExport, RpcServerInqBindings, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf


RpcEpResolveBinding

The RpcEpResolveBinding function resolves a partially bound server binding handle into a fully bound server binding handle.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcEpResolveBinding(

RPC_BINDING_HANDLE  Binding,
RPC_IF_HANDLE  IfSpec
);
Parameters

Binding

Specifies a partially bound server binding handle to resolve to a fully bound server binding handle.

IfSpec

Specifies a stub-generated data structure specifying the interface of interest.

Remarks

An application calls the RpcEpResolveBinding routine to resolve a partially bound server binding handle into a fully bound binding handle.

Resolving binding handles requires an interface UUID and an object UUID (which may be nil). The RPC run-time library asks the endpoint-mapping service on the host specified by the Binding argument to look up an endpoint for a compatible server instance. To find the endpoint, the endpoint-mapping service looks in the endpoint-map database for the interface UUID in the IfSpec argument and the object UUID in the Binding argument, if any.

How the resolve-binding operation functions depends on whether the specified binding handle is partially or fully bound. When the client specifies a partially bound handle, the resolve-binding operation has the following possible outcomes:

•	If no compatible server instances are registered in the endpoint-map database, the resolve-binding operation returns the EPT_S_NOT_REGISTERED status code.

•	If a compatible server instance is registered in the endpoint-map database, the resolve-binding operation returns a fully bound binding and the RPC_S_OK status code.

When the client specifies a fully bound binding handle, the resolve-binding operation returns the specified binding handle and the RPC_S_OK status code. The resolve-binding operation does not contact the endpoint-mapping service.

In neither the partially nor the fully bound binding case does the resolve-binding operation contact a compatible server instance.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
See Also

RpcBindingFromStringBinding, RpcBindingReset, RpcEpRegister, RpcEpRegisterNoReplace, RpcNsBindingImportBegin, RpcNsBindingImportDone, RpcNsBindingImportNext


RpcEpUnregister

The RpcEpUnregister function removes server-address information from the local endpoint-map database.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcEpUnregister(

RPC_IF_HANDLE  IfSpec,
RPC_BINDING_VECTOR *  BindingVector,
UUID_VECTOR *  UuidVector
);
Parameters

IfSpec

Specifies an interface to unregister from the local endpoint-map database.

BindingVector

Points to a vector of binding handles to unregister.

UuidVector

Points to an optional vector of object UUIDs to unregister. The server application constructs this vector. RpcEpUnregister unregisters all endpoint-map database elements that match the specified IfSpec and BindingVector arguments and the object UUID(s).

A null argument value indicates there are no object UUIDs to unregister.

Remarks

The RpcEpUnregister routine removes elements from the local host’s endpoint-map database. A server application calls this routine only when the server has previously registered endpoints and the server wants to remove that address information from the endpoint-map database.

Specifically, RpcEpUnregister allows a server application to remove its own endpoint-map database elements (server-address information) based on the interface specification or on both the interface specification and the object UUID(s) of the resource(s) offered.

The server calls the RpcServerInqBindings routine to obtain the required BindingVector argument. To unregister selected endpoints, the server can prune the binding vector prior to calling this routine.

RpcEpUnregister creates a cross-product from the IfSpec, BindingVector, and UuidVector arguments and removes each element in the cross-product from the endpoint-map database.

Use RpcEpUnregister cautiously: removing elements from the endpoint-map database may make servers unavailable to client applications that have not previously communicated with the server.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NO_BINDINGS	No bindings
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
See Also

RpcEpRegister, RpcEpRegisterNoReplace, RpcNsBindingUnexport, RpcServerInqBindings


RpcExcept

The RpcExcept function specifies exception handling.

RpcTryExcept
{
guarded statements
}
RpcExcept(expression)
{
exception statements
}
RpcEndExcept;

Parameters

guarded statements

Specifies program statements that are guarded or monitored for exceptions during execution.

expression

Specifies an expression that is evaluated when an exception occurs. If expression evaluates to a non-zero value, the exception statements are executed. If expression evaluates to a zero value, unwinding continues to the next RpcTryExcept or RpcTryFinally routine.

exception statements

Specifies statements that are executed when the expression evaluates to a non-zero value.

Remarks

If an exception does not occur, the expression and exception statements are skipped and execution continues at the statement following the RpcEndExcept keyword.

RpcExceptionCode can be used in both expression and exception statements to determine which exception occurred.

The following restrictions apply.

•	Jumping (via a goto) into guarded statements is not allowed.

•	Jumping (via a goto) into exception statements is not allowed.

•	Returning or jumping (via a goto) from guarded statements is not allowed.

•	Returning or jumping (via a goto) from exception statements is not allowed.

See Also

RpcExceptionCode, RpcFinally, RpcRaiseException


RpcExceptionCode

The RpcExceptionCode function returns the exception code of an exception.

unsigned long RpcExceptionCode(VOID);

Remarks

The RpcExceptionCode function can only be called from within the expression and exception statements of an RpcTryExcept exception handler.

Return Values

No value is returned.

See Also

RpcExcept, RpcFinally


RpcFinally

The RpcFinally function specifies termination handlers.

RpcTryFinally
{
guarded statements
}
RpcFinally
{
termination statements
}
RpcEndFinally;

Parameters

guarded statements

Specifies statements that are executed while exceptions are being monitored. If an exception occurs during the execution of these statements, termination statements will be executed, then unwinding continues to the next RpcTryExcept or RpcTryFinally routine.

termination statements

Specifies statements that are executed when an exception occurs. After the termination statements are complete, the exception is raised again.

Remarks

The RpcAbnormalTermination function can be used in termination statements to determine whether termination statements is being executed because an exception occurred. A non-zero return from RpcAbnormalTermination indicates that an exception occurred. A value of zero indicates that no exception occurred.

The following restrictions apply:

•	Jumping (via a goto) into guarded statements is not allowed.

•	Jumping (via a goto) into termination statements is not allowed.

•	Returning or jumping (via a goto) from guarded statements is not allowed.

•	Returning or jumping (via a goto) from termination statements is not allowed.

See Also

RpcAbnormalTermination


RpcIfIdVectorFree

The RpcIfIdVectorFree function frees the vector and the interface-identification structures contained in the vector.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcIfIdVectorFree(

RPC_IF_ID_VECTOR * *  IfIdVec
);
Parameters

IfIdVec

Specifies the address of a pointer to a vector of interface information. On return, the pointer is set to NULL.

Remarks

An application calls the RpcIfIdVectorFree routine to release the memory used to store a vector of interface identifications. RpcIfIdVectorFree frees memory containing the interface identifications and the vector itself. On return, this routine sets the IfIdVec argument to NULL.

An application obtains a vector of interface identifications by calling the RpcNsMgmtEntryInqIfIds and RpcMgmtInqIfIds routines.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_ARG	Invalid argument
See Also

RpcIfInqId, RpcMgmtInqIfIds, RpcNsMgmtEntryInqIfIds


RpcIfInqId

The RpcIfInqId function returns the interface-identification part of an interface specification.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcIfInqId(

RPC_IF_HANDLE  RpcIfHandle,
RPC_IF_ID *  RpcIfId
);
Parameters

RpcIfHandle

Specifies a stub-generated data structure specifying the interface to inquire.

RpcIfId

Returns a pointer to the interface identification. The application provides memory for the returned data.

Remarks

An application calls the RpcIfInqId routine to obtain a copy of the interface identification from the provided interface specification.

The returned interface identification consists of the interface UUID and interface version numbers (major and minor) specified in the IfSpec argument from the IDL file.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcServerInqIf, RpcServerRegisterIf


RpcImpersonateClient

A server thread that is processing client remote procedure calls can call the RpcImpersonateClient function to impersonate the active client.

This function is supported only by Windows NT.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcImpersonateClient(

RPC_BINDING_HANDLE  CallHandle
);
Parameters

CallHandle

Specifies a binding handle on the server that represents a binding to a client. The server impersonates the client indicated by this handle. If a value of zero is specified, the server impersonates the client that is being served by this server thread.

Return Values

Value	Meaning
RPC_S_OK	Success.
RPC_S_NO_CALL_ACTIVE	No client is active on this server thread.
RPC_S_CANNOT_SUPPORT	The function is not supported for either the operating system, the transport, or this security subsystem.
RPC_S_INVALID_BINDING	Invalid binding handle.
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation.
RPC_S_NO_CONTEXT_AVAILABLE	The server does not have permission to impersonate the client.
Remarks

In a multithreaded application, if the call to RpcImpersonateClient is with a handle to another client thread, you must call RpcRevertToSelfEx with the handle to that thread to end impersonation.

See Also

RpcRevertToSelf, Impersonation


RpcMacSetYieldInfo

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMacSetYieldInfo(

MACYIELDCALLBACK  pfnCallback
);
Parameters

pfnCallback

Pointer to a callback function.

typedef void (RPC_ENTRY *MACYIELDCALLBACK)(short *);

Remarks

The RpcMacSetYieldInfo function configures Macintosh client applications to yield to other applications during remote procedure calls.

If a yielding function is not registered, an RPC will not yield on the Mac. Register a yielding function by calling RpcMacSetYieldInfo.

The yielding function must yield until *pStatus is not equal to 1. For example:

void RPC_ENTRY MacCallbackFunc (short *pStatus)

{

    MSG msg;

    while (*pStatus == 1)

    {

    if(PeekMessage(&msg, NULL, 0, 0, PM_REMOVE))

        {

        TranslateMessage(&msg);

        DispatchMessage(&msg);

        }

    }

}

Note that rpc.h must be included before winerror.h (or any files that include it, such as winbase.h, windows.h, and so on).

Return Values

Value	Meaning
RPC_S_OK	The information was set successfully.


RpcMgmtEnableIdleCleanup

The RpcMgmtEnableIdleCleanup function closes idle resources, such as network connections, on the client. Connection-oriented protocols set five minutes as the default waiting period to determine whether a resource is idle.

This function is supported by the Windows NT, Windows 95 and Windows 3.x platforms. It is not supported by MS-DOS.

Note  RpcMgmtEnableIdleCleanup is a Microsoft extension to the DCE API set.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtEnableIdleCleanup(VOID);

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_OUT_OF_THREADS	Out of threads
RPC_S_OUT_OF_RESOURCES	Out of resources
RPC_S_OUT_OF_MEMORY	Out of memory
See Also

RpcServerUnregisterIf


RpcMgmtEpEltInqBegin

The RpcMgmtEpEltInqBegin function creates an inquiry context for viewing the elements in an endpoint map.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtEpEltInqBegin(

RPC_BINDING_HANDLE  EpBinding,
unsigned long  InquiryType,
RPC_IF_ID *  IfId,
unsigned long  VersOption,
UUID *  ObjectUuid,
RPC_EP_INQ_HANDLE *  InquiryContext
);
Parameters

EpBinding

Specifies the host whose endpoint map elements will be viewed. Specify NULL to view elements from the local host.

InquiryType

Specifies an integer value that indicates the type of inquiry to perform on the endpoint map. The following are valid inquiry types:

Value	Description
RPC_C_EP_ALL_ELTS	Returns every element from the endpoint map. The IfId, VersOption, and ObjectUuid parameters are ignored.
RPC_C_EP_MATCH_BY_IF	Searches the endpoint map for those elements that contain the interface identifier specified by the IfId and VersOption values.
RPC_C_EP_MATCH_BY_OBJ	Searches the endpoint map for those elements that contain the object UUID specified by ObjectUuid.
RPC_C_EP_MATCH_BY_BOTH	Searches the endpoint map for those elements that contain the interface identifier and object UUID specified by IfId, VersOption, and ObjectUuid.
IfId

Specifies the interface identifier of the endpoint map elements to be returned by RpcMgmtEpEltInqNext. This parameter is only used when InquiryType is either RPC_C_EP_MATCH_BY_IF or RPC_C_EP_MATCH_BY_BOTH. Otherwise, it is ignored.

VersOption

Specifies how RpcMgmtEpEltInqNext uses the IfId parameter. This parameter is only used when InquiryType is either RPC_C_EP_MATCH_BY_IF or RPC_C_EP_MATCH_BY_BOTH. Otherwise, it is ignored. The following are valid values for this parameter:

Value	Description
RPC_C_VERS_ALL	Returns endpoint map elements that offer the specified interface UUID, regardless of the version numbers.
RPC_C_VERS_COMPATIBLE	Returns endpoint map elements that offer the same major version of the specified interface UUID and a minor version greater than or equal to the minor version of the specified interface UUID.
RPC_C_VERS_EXACT	Returns endpoint map elements that offer the specified version of the specified interface UUID.
RPC_C_VERS_MAJOR_ONLY	Returns endpoint map elements that offer the same major version of the specified interface UUID and ignores the minor version.
RPC_C_VERS_UPTO	Returns endpoint map elements that offer a version of the specified interface UUID less than or equal to the specified major and minor version.
ObjectUuid

Specifies the object UUID that RpcMgmtEpEltInqNext looks for in endpoint map elements. This parameter is used only when InquiryType is either RPC_C_EP_MATCH_BY_OBJ or RPC_C_EP_MATCH_BY_BOTH.

InquiryContext

Returns an inquiry context for use with RpcMgmtEpEltInqNext and RpcMgmtEpEltInqDone.

Remarks

The RpcMgmtEpEltInqBegin routine creates an inquiry context for viewing server address information stored in the endpoint map. Using InquiryType and VersOption, an application specifies which of the following endpoint map elements are to be returned from calls to RpcMgmtEpEltInqNext:

•	All elements.

•	Those elements with the specified interface identifier.

•	Those elements with the specified object UUID.

•	Those elements with both the specified interface identifier and object UUID.

Before calling RpcMgmtEpEltInqNext, the application must first call this routine to create an inquiry context. After viewing the endpoint map elements, the application calls RpcMgmtEpEltInqDone to delete the inquiry context.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcEpRegister


RpcMgmtEpEltInqDone

The RpcMgmtEpEltInqDone function deletes the inquiry context for viewing the elements in an endpoint map.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtEpEltInqDone(

RPC_EP_INQ_HANDLE *  InquiryContext
);
Parameters

InquiryContext

Specifies the inquiry context to delete and returns the value NULL.

Remarks

The RpcMgmtEpEltInqDone routine deletes an inquiry context created by RpcMgmtEpEltInqBegin. An application calls this routine after viewing local endpoint map elements using RpcMgmtEpEltInqNext.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcEpRegister


RpcMgmtEpEltInqNext

The RpcMgmtEpEltInqNext function returns one element from an endpoint map.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtEpEltInqNext(

RPC_EP_INQ_HANDLE  InquiryContext,
RPC_IF_ID * IfId,
RPC_BINDING_HANDLE * Binding
UUID *  ObjectUuid,
unsigned char * *  Annotation
);
Parameters

InquiryContext

Specifies an inquiry context. The inquiry context is returned from RpcMgmtEpEltInqBegin.

IfId

Returns the interface identifier of the endpoint map element.

Binding

Optional. Returns the binding handle from the endpoint map element.

ObjectUuid

Optional. Returns the object UUID from the endpoint map element.

Annotation

Optional. Returns the annotation string for the endpoint map element. When there is no annotation string in the endpoint map element, the empty string ("") is returned.

Remarks

The RpcMgmtEpEltInqNext routine returns one element from the endpoint map. Elements selected depend on the inquiry context. The selection criteria are determined by InquiryType of the RpcMgmtEpEltInqBegin routine that returned InquiryContext.

An application can view all the selected endpoint map elements by repeatedly calling RpcMgmtEpEltInqNext. When all the elements have been viewed, this routine returns an RPC_X_NO_MORE_ENTRIES status. The returned elements are unordered.

When the respective arguments are non-NULL, the RPC run-time function library allocates memory for Binding and Annotation on each call to this routine. The application is responsible for calling RpcBindingFree for each returned Binding and RpcStringFree for each returned Annotation.

After viewing the endpoint map’s elements, the application must call RpcMgmtEpEltInqDone to delete the inquiry context.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcEpRegister


RpcMgmtEpUnregister

The RpcMgmtEpUnregister function removes server address information from an endpoint map.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtEpUnregister(

RPC_BINDING_HANDLE  EpBinding,
RPC_IF_ID *  IfId,
RPC_BINDING_HANDLE  Binding,
UUID *  ObjectUuid
);
Parameters

EpBinding

Specifies the host whose endpoint map elements are to be unregistered. To remove elements from the same host as the calling application, the application specifies NULL. To remove elements from another host, the application specifies a server binding handle for any server residing on that host. Note that the application can specify the same binding handle it is using to make other remote procedure calls.

IfId

Specifies the interface identifier to remove from the endpoint map.

Binding

Specifies the binding handle to remove.

ObjectUuid

Specifies the optional object UUID to remove. The value NULL indicates there is no object UUID to remove.

Remarks

The RpcMgmtEpUnregister routine unregisters an element from the endpoint map. A management program calls this routine to remove addresses of servers that are no longer available, or to remove addresses of servers that support objects that are no longered offered.

The EpBinding parameter must be a full binding. The object UUID associated with the EpBinding parameter must be a nil UUID. Specifying a non-nil UUID causes the routine to fail with the status code EPT_S_CANT_PERFORM_OP. Other than the host information and object UUID, all information in this argument is ignored.

An application calls RpcMgmtEpEltInqNext to view local endpoint map elements. The application can then remove the elements using RpcMgmtEpUnregister.

Note  Use this routine with caution. Removing elements from the local endpoint map may make servers unavailable to client applications that do not already have a fully bound binding handle to the server.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_CANT_PERFORM_OP	Cannot perform the requested operation
See Also

RpcEpRegister, RpcEpUnregister


RpcMgmtInqComTimeout

The RpcMgmtInqComTimeout function returns the binding-communications timeout value in a binding handle.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtInqComTimeout(

RPC_BINDING_HANDLE  Binding,
unsigned int *  Timeout
);
Parameters

Binding

Specifies a binding.

Timeout

Returns a pointer to the timeout value from the Binding argument.

Remarks

A client application calls RpcMgmtInqComTimeout to view the timeout value in a server binding handle. The timeout value specifies the relative amount of time that should be spent to establish a binding to the server before giving up. The table below shows the timeout values.

A client calls RpcMgmtSetComTimeout to change the timeout value.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
See Also

RpcMgmtInqStats, RpcMgmtSetComTimeout


RpcMgmtInqDefaultProtectLevel

The RpcMgmtInqDefaultProtectLevel function returns the default authentication level for an authentication service.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtInqDefaultProtectLevel(

unsigned int  AuthnSvc,
unsigned int  *  AuthnLevel
);
Parameters

AuthnSvc

Specifies the authentication service for which to return the default authentication level. Possible values are as follows:

Value	Description
RPC_C_AUTHN_NONE	No authentication
RPC_C_AUTHN_WINNT	32-bit Windows authentication service
AuthnLevel

Returns the default authentication level for the specified authentication service. The authentication level determines the degree to which authenticated communications between the client and server are protected. Possible values are as follows:

Value	Description
RPC_C_AUTHN_LEVEL_DEFAULT	Uses the default authentication level for the specified authentication service.
RPC_C_AUTHN_LEVEL_NONE	Performs no authentication.
RPC_C_AUTHN_LEVEL_CONNECT	Authenticates only when the client establishes a relationship witha server.
RPC_C_AUTHN_LEVEL_CALL	Authenticates only at the beginning of each remote procedure call when the server receives the request. Does not apply to remote procedure calls made using the connection-based protocol sequences that start with the prefix “ncacn.” If the protocol sequence in a binding is a connection-based protocol sequence and you specify this level, this routine instead uses the RPC_C_AUTHN_LEVEL_PKT constant.
RPC_C_AUTHN_LEVEL_PKT	Authenticates that all data received is from the expected client.
RPC_C_AUTHN_LEVEL_PKT _INTEGRITY	Authenticates and verifies that none of the data transferred between client and server has been modified.
RPC_C_AUTHN_LEVEL_PKT _PRIVACY	Authenticates all previous levels and encrypts the argument value of each remote procedure call.
Note  RPC_C_AUTHN_LEVEL_CALL, RPC_C_AUTHN_LEVEL_PKT, RPC_C_AUTHN_LEVEL_PKT_INTEGRITY, and RPC_C_AUTHN_LEVEL_PKT_PRIVACY are only supported for clients communicating with a Windows NT server. A Windows 95 server can only accept incoming calls at the RPC_C_AUTHN_LEVEL_CONNECT level.

Remarks

An application calls the RpcMgmtInqDefaultProtectLevel routine to obtain the default authentication level for a specified authentication service.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_UNKNOWN_AUTH_SERVICE	Unknown authentication service


RpcMgmtInqIfIds

The RpcMgmtInqIfIds function returns a vector containing the identifiers of the interfaces offered by the server.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtInqIfIds(

RPC_BINDING_HANDLE  Binding,
RPC_IF_ID_VECTOR * *  IfIdVector
);
Parameters

Binding

To receive interface identifiers about a remote application, specify a server binding handle for that application. To receive interface information about your own application, specify a value of NULL.

IfIdVector

Returns the address of an interface identifier vector.

Remarks

An application calls the RpcMgmtInqIfIds routine to obtain a vector of interface identifiers about the specified server from the RPC run-time library.

The RPC run-time library allocates memory for the interface identifier vector. The application is responsible for calling the RpcIfIdVectorFree routine to release the memory used by this vector.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation


RpcMgmtInqServerPrincName

The RpcMgmtInqServerPrincName function returns a server’s principal name.

This function is supported by both 32-bit platforms — Windows NT and Windows 95. Note that it is supported only in ANSI on Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtInqServerPrincName(

RPC_BINDING_HANDLE  Binding,
unsigned int  AuthnSvc,
unsigned char * *  ServerPrincName
);
Parameters

Binding

To receive the principal name for a server, specify a server binding handle for that server. To receive the principal name for your own (local) application, specify a value of NULL.

AuthnSvc

Specifies the authentication service for which a principal name is returned. Possible values are as follows:

Value	Description
RPC_C_AUTHN_NONE	No authentication
RPC_C_AUTHN_WINNT	Windows NT authentication service
ServerPrincName

Returns a principal name that is registered for the authentication service in AuthnSvc by the server referenced in Binding. If multiple names are registered, only one name is returned.

Remarks

An application calls the RpcMgmtInqServerPrincName routine to obtain the principal name of a server that is registered for a specified authentication service.

The RPC run-time library allocates memory for string returned in ServerPrincName. The application is responsible for calling the RpcStringFree routine to release the memory used by this routine.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation


RpcMgmtInqStats

The RpcMgmtInqStats function returns RPC run-time statistics.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtInqStats(

RPC_BINDING_HANDLE  Binding,
RPC_STATS_VECTOR * *  Statistics
);
Parameters

Binding

To receive statistics about a remote application, specify a server binding handle for that application. To receive statistics about your own (local) application, specify a value of NULL.

Statistics

Returns a pointer to a pointer to the statistics about the server specified by the Binding argument. Each statistic is an unsigned long value.

Remarks

An application calls the RpcMgmtInqStats routine to obtain statistics about the specified server from the RPC run-time library.

Each array element in the returned statistics vector contains an unsigned long value. The following list describes the statistics indexed by the specified constant:

Statistic	Description
RPC_C_STATS_CALLS_IN	The number of remote procedure calls received by the server
RPC_C_STATS_CALLS_OUT	The number of remote procedure calls initiated by the server
RPC_C_STATS_PKTS_IN	The number of network packets received by the server
RPC_C_STATS_PKTS_OUT	The number of network packets sent by the server
The RPC run-time library allocates memory for the statistics vector. The application is responsible for calling the RpcMgmtStatsVectorFree routine to release the memory used by the statistics vector.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
See Also

RpcEpResolveBinding, RpcMgmtStatsVectorFree


RpcMgmtIsServerListening

The RpcMgmtIsServerListening function tells whether a server is listening for remote procedure calls.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtIsServerListening(

RPC_BINDING_HANDLE  Binding
);
Parameters

Binding

To determine whether a remote application is listening for remote procedure calls, specify a server binding handle for that application. To determine whether your own (local) application is listening for remote procedure calls, specify a value of NULL.

Remarks

An application calls the RpcMgmtIsServerListening routine to determine whether the server specified in the Binding argument is listening for remote procedure calls.

RpcMgmtIsServerListening returns a true value if the server has called the RpcServerListen routine.

Return Values

Value	Meaning
RPC_S_OK	Server listening for remote procedure calls
RPC_S_SERVER_NOT_LISTENING	Server not listening for remote procedure calls
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
See Also

RpcEpResolveBinding, RpcServerListen


RpcMgmtSetAuthorizationFn

The RpcMgmtSetAuthorizationFn function establishes an authorization function for processing remote calls to a server’s management routines.

This function is supported only by Windows NT.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtSetAuthorizationFn(

RPC_MGMT_AUTHORIZATION_FN  AuthorizationFn
);
Parameters

AuthorizationFn

Specifies an authorization function. The RPC server run-time library automatically calls this function whenever the server runtime receives a client request to execute one of the remote management routines. The server must implement this function. Applications specify NULL to unregister a previously registered authorization function. After such a call, default authorizations are used.

Remarks

Server applications call the RpcMgmtSetAuthorizationFn routine to establish an authorization function that controls access to the server’s remote management routines. When a server has not called RpcMgmtSetAuthorizationFn, or calls with a NULL value for AuthorizationFn, the server run-time library uses the following default authorizations:

Remote routine	Default authorization
RpcMgmtInqIfIds	Enabled
RpcMgmtInqServerPrincName	Enabled
RpcMgmtInqStats	Enabled
RpcMgmtIsServerListening	Enabled
RpcMgmtStopServerListening	Disabled
In the above table, “Enabled” indicates that all clients can execute the remote routine, and “Disabled” indicates that all clients are prevented from executing the remote routine.

The following example shows the prototype for authorization function that the server must implement:

typedef boolean32  (*RPC_MGMT_AUTHORIZATION_FN)

   (

   RPC_BINDING_HANDLE      ClientBinding               /* in */

   unsigned long           RequestedMgmtOperation      /* in */

   RPC_STATUS *            Status                      /* out */

   );

When a client requests one of the server’s remote management functions, the server run-time library calls the authorization function with ClientBinding and RequestedMgmtOperation. The authorization function uses these parameters to determine whether the calling client can execute the requested management routine.

The value for RequestedMgmtOperation depends on the remote routine requested, as shown in the following:

Called remote routine	RequestedMgmtOperation value
RpcMgmtInqIfIds	RPC_C_MGMT_INQ_IF_IDS
RpcMgmtInqServerPrincName	RPC_C_MGMT_INQ_PRINC_NAME
RpcMgmtInqStats	RPC_C_MGMT_INQ_STATS
RpcMgmtIsServerListening	RPC_C_MGMT_IS_SERVER_LISTEN
RpcMgmtStopServerListening	RPC_C_MGMT_STOP_SERVER_LISTEN
The authorization function must handle all of these values.

The authorization function returns a Boolean value to indicate whether the calling client is allowed access to the requested management function. If the authorization function returns TRUE, the management routine can execute. If the authorization function returns FALSE, the management routine cannot execute. If this is the case, the routine returns a Status value to the client:

•	If Status is either 0 (zero) or RPC_S_OK, the Status value RPC_S_ACCESS_DENIED is returned to the client by the remote management routine.

•	If the authorization function returns any other value for Status, that Status value is returned to the client by the remote management routine.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcMgmtInqStats, RpcMgmtIsServerListening, RpcMgmtStopServerListening, RpcMgmtWaitServerListen


RpcMgmtSetCancelTimeout

The RpcMgmtSetCancelTimeout function sets the lower bound on the time to wait before timing out after forwarding a cancel.

This function is supported only by Windows NT.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtSetCancelTimeout(

signed int  Seconds
);
Parameters

Seconds

An integer specifying the number of seconds to wait for a server to acknowledge a cancel. To specify that a client waits an indefinite amount of time, supply the value RPC_C_CANCEL_INFINITE_TIMEOUT.

Remarks

An application calls the RpcMgmtSetCancelTimeout routine to reset the amount of time the run-time library waits for a server to acknowledge a cancel. The application specifies either to wait forever or to wait a specified length of time in seconds. If the value of Seconds is 0 (zero), the call is immediately abandoned upon a cancel and control returns to the client application. The default value is RPC_C_CANCEL_INFINITE_TIMEOUT, which specifies waiting forever for the call to complete.

The value for the cancel time-out applies to all remote procedure calls made in the current thread. To change the time-out value, a multithreaded client must call this routine in each thread of execution.

Note  This routine is only supported for Windows NT clients.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_CANNOT_SUPPORT	Called from an MS-DOS or Windows 3.x client


RpcMgmtSetComTimeout

The RpcMgmtSetComTimeout function sets the binding-communications timeout value in a binding handle.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtSetComTimeout(

RPC_BINDING_HANDLE  Binding,
unsigned int  Timeout
);
Parameters

Binding

Specifies the server binding handle whose timeout value is set.

Timeout

Specifies the communications timeout value.

Remarks

A client application calls RpcMgmtSetComTimeout to change the communications timeout value for a server binding handle. The timeout value specifies the relative amount of time that should be spent to establish a relationship to the server before giving up. Depending on the protocol sequence for the specified binding handle, the timeout value acts only as a hint to the RPC run-time library.

After the initial relationship is established, subsequent communications for the binding handle revert to not less than the default timeout for the protocol service. This means that after setting a short initial timeout establishing a connection, calls in progress will not be timed out any more aggressively than the default.

The timeout value can be any integer value from 0 to 10. For convenience, constants are provided for certain values in the timeout range. The following table contains the RPC-defined values that an application can use for the timeout argument:

Manifest	Value	Description
RPC_C_BINDING_INFINITE_TIMEOUT	10	Keep trying to establish communications forever.
RPC_C_BINDING_MIN_TIMEOUT	0	Try the minimum amount of time for the network protocol being used. This value favors response time over correctness in determining whether the server is running.
RPC_C_BINDING_DEFAULT_TIMEOUT	5	Try an average amount of time for the network protocol being used. This value gives correctness in determining whether a server is running and gives response time equal weight. This is the default value.
RPC_C_BINDING_MAX_TIMEOUT	9	Try the longest amount of time for the network protocol being used. This value favors correctness in determining whether a server is running over response time.
Note  The values in the preceding table are not in seconds. These values represent a relative amount of time on a scale of zero to 10.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_INVALID_TIMEOUT	Invalid timeout value
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
See Also

RpcMgmtInqComTimeout


RpcMgmtSetServerStackSize

The RpcMgmtSetServerStackSize function specifies the stack size for each server thread.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtSetServerStackSize(

unsigned int  ThreadStackSize
);
Parameters

ThreadStackSize

Specifies the stack size in bytes allocated for each thread created by RpcServerListen. This value is applied to all threads created for the server. Select this value based on the stack requirements of the remote procedures offered by the server.

Remarks

A server application calls the RpcMgmtSetServerStackSize routine to specify the thread stack size to use when the RPC run-time library creates call threads for executing remote procedure calls. The MaxCalls argument in the RpcServerListen routine specifies the number of call threads created.

Servers that know the stack requirements of all the manager routines in the interfaces it offers can call the RpcMgmtSetServerStackSize routine to ensure that each call thread has the necessary stack size.

Calling RpcMgmtSetServerStackSize is optional. However, when used, it must be called before the server calls RpcServerListen. If a server does not call RpcMgmtSetServerStackSize, the default per thread stack size from the underlying threads package is used.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_ARG	Invalid argument
See Also

RpcServerListen


RpcMgmtStatsVectorFree

The RpcMgmtStatsVectorFree function frees a statistics vector.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtStatsVectorFree(

RPC_STATS_VECTOR * *  StatsVector
);
Parameters

StatsVector

Points to a pointer to a statistics vector. On return, the pointer is set to NULL.

Remarks

An application calls the RpcMgmtStatsVectorFree routine to release the memory used to store statistics.

An application obtains a vector of statistics by calling the RpcMgmtInqStats routine.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcMgmtInqStats


RpcMgmtStopServerListening

The RpcMgmtStopServerListening function tells a server to stop listening for remote procedure calls. This function will not affect auto-listen interfaces. See RpcServerRegisterIfEx for more details.

This function is supported by both server platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtStopServerListening(

RPC_BINDING_HANDLE  Binding
);
Parameters

Binding

To direct a remote application to stop listening for remote procedure calls, specify a server binding handle for that application. To direct your own (local) application to stop listening for remote procedure calls, specify a value of NULL.

Remarks

An application calls the RpcMgmtStopServerListening routine to direct a server to stop listening for remote procedure calls. If DontWait was true, the application should call RpcMgmtWaitServerListen to wait for all calls to complete.

When it receives a stop-listening request, the RPC run-time library stops accepting new remote procedure calls for all registered interfaces. Executing calls are allowed to complete, including callbacks.

After all calls complete, the RpcServerListen routine returns to the caller. If DontWait is true, the application calls RpcMgmtServerListen for all calls to complete.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
Note  From the client-side, RpcMgmtStopServerListening is disabled by default. To enable this routine, create an authorization function in your server application that returns TRUE (to allow a remote shutdown) whenever RpcMgmtStopServerListening is called. Use RpcMgmtSetAuthorizationFn to give the client access to the management function.

See Also

RpcEpResolveBinding, RpcMgmtWaitServerListen, RpcServerListen, RpcServerRegisterIfEx


RpcMgmtWaitServerListen

The RpcMgmtWaitServerListen function performs the wait operation usually associated with RpcServerListen.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcMgmtWaitServerListen(VOID);

Remarks

Note  RpcMgmtWaitServerListen is a Microsoft extension to the DCE API set.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

When the RpcServerListen flag parameter DontWait has a nonzero value, the RpcServerListen function returns to the server application without performing the wait operation. In this case, the wait can be performed by RpcMgmtWaitServerListen.

Applications must call RpcServerListen with a nonzero value for the DontWait parameter before calling RpcMgmtWaitServerListen.

RpcMgmtWaitServerListen returns after the server application calls RpcMgmtStopServerListening and all active remote procedure calls complete, or after a fatal error occurs in the RPC run-time library.

Return Values

Value	Meaning
RPC_S_OK	All remote procedure calls are complete.
RPC_S_ALREADY_LISTENING	Another thread has called RpcMgmtWaitServerListen and has not yet returned.
RPC_S_NOT_LISTENING	The server application must call RpcServerListen before calling RpcMgmtWaitServerListen.
See Also

RpcMgmtStopServerListening, RpcServerListen


RpcNetworkInqProtseqs

The RpcNetworkInqProtseqs function returns all protocol sequences supported by both the RPC run-time library and the operating system.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNetworkInqProtseqs(

RPC_PROTSEQ_VECTOR * *  ProtSeqVector
);
Parameters

ProtSeqVector

Returns a pointer to a pointer to a protocol sequence vector.

Remarks

Note  RpcNetworkInqProtseqs is available for server applications, not client applications, using Microsoft RPC. Use RpcNetworkIsProtseqValid in client applications.

A server application calls the RpcNetworkInqProtseqs routine to obtain a vector containing the protocol sequences supported by both the RPC run-time library and the operating system. If there are no supported protocol sequences, this routine returns the RPC_S_NO_PROTSEQS status code and a ProtSeqVector argument value of NULL.

The server is responsible for calling the RpcProtseqVectorFree routine to release the memory used by the vector.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NO_PROTSEQS	No supported protocol sequences
See Also

RpcProtseqVectorFree


RpcNetworkIsProtseqValid

The RpcNetworkIsProtseqValid function tells whether the specified protocol sequence is supported by both the RPC run-time library and the operating system.

For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNetworkIsProtseqValid(

unsigned char *  Protseq
);
Parameters

Protseq

Points to a string identifier of the protocol sequence to be checked.

If the Protseq argument is not a valid protocol sequence string, RpcNetworkIsProtseqValid returns RPC_S_INVALID_RPC_PROTSEQ.

Remarks

Note  RpcNetworkIsProtseqValid is available for client applications, not for server applications. Use RpcNetworkInqProtseqs for server applications.

An application calls the RpcNetworkIsProtseqValid routine to determine whether an individual protocol sequence is available for making remote procedure calls.

A protocol sequence is valid if both the RPC run-time library and the operating system support the specified protocols. For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

An application calls RpcNetworkInqProtseqs to see all of the supported protocol sequences.

Return Values

Value	Meaning
RPC_S_OK	Success; protocol sequence supported
RPC_S_PROTSEQ_NOT_SUPPORTED	Protocol sequence not supported on this host
RPC_S_INVALID_RPC_PROTSEQ	Invalid protocol sequence
See Also

RpcNetworkInqProtseqs


RpcNsBindingExport

The RpcNsBindingExport function establishes a name-service database entry with multiple binding handles and multiple objects for a server.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsBindingExport(

unsigned long  EntryNameSyntax,
unsigned char *  EntryName,
RPC_IF_HANDLE  IfSpec,
RPC_BINDING_VECTOR *  BindingVec,
UUID_VECTOR *  ObjectUuidVec
);
Parameters

EntryNameSyntax

Specifies an unsigned long value that indicates the syntax of the next argument, EntryName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

EntryName

Points to the entry name to which binding handles and object UUIDs are exported. You may not provide a null or empty string.

To use the entry name specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultEntry, provide a null pointer or an empty string. In this case, the EntryNameSyntax parameter is ignored and the run-time library uses the default syntax EntryName.

IfSpec

Specifies a stub-generated data structure specifying the interface to export. A null argument value indicates there are no binding handles to export (only object UUIDs are to be exported) and the BindingVec argument is ignored.

BindingVec

Points to server bindings to export. A null argument value indicates there are no binding handles to export (only object UUIDs are to be exported).

ObjectUuidVec

Points to a vector of object UUIDs offered by the server. The server application constructs this vector. A null argument value indicates there are no object UUIDs to export (only binding handles are to be exported).

Remarks

The RpcNsBindingExport routine allows a server application to publicly offer an interface in the name-service database for use by any client application.

To export an interface, the server application calls the RpcNsBindingExport routine with an interface and the server binding handles a client can use to access the server.

A server application also calls the RpcNsBindingExport routine to publicly offer the object UUID(s) of resource(s) it offers, if any, in the name-service database.

A server can export interfaces and objects in a single call to RpcNsBindingExport, or it can export them separately.

If the name-service database entry specified by the EntryName argument does not exist, the RpcNsBindingExport routine tries to create it. In this case, the server application must have the privilege to create the entry.

In addition to calling RpcNsBindingExport, a server that called the RpcServerUseAllProtseqs or RpcServerUseProtseq routine must also register with the local endpoint-map database by calling either the RpcEpRegister or RpcEpRegisterNoReplace routine.

A server is not required to export its interface(s) to the name-service database. When a server does not export, only clients that privately know of that server’s binding information can access its interface(s). For example, a client that has the information needed to construct a string binding can call the RpcBindingFromStringBinding to create a binding handle for making remote procedure calls to a server.

Before calling the RpcNsBindingExport routine, a server must do the following:

•	Register one or more protocol sequences with the local RPC run-time library by calling one of the following routines:

•	RpcServerUseAllProtseqs

•	RpcServerUseProtseq

•	RpcServerUseAllProtseqsIf

•	RpcServerUseProtseqIf

•	RpcServerUseProtseqEp

•	Obtain a list of server bindings by calling the RpcServerInqBindings routine.

The vector returned from the RpcServerInqBindings routine becomes the Binding argument for RpcNsBindingExport. To prevent a binding from being exported, set the selected vector element to a null value.

If a server exports to the same name-service database entry multiple times, the second and subsequent calls to RpcNsBindingExport add the binding information and object UUIDs when that data is different from the binding information already in the server entry. Existing data is not removed from the entry.

To remove binding handles and object UUIDs from the name-service database, a server application calls the RpcNsBindingUnexport routine.

A server entry must have at least one binding handle to exist. As a result, exporting only UUIDs to a non-existing entry has no effect, and unexporting all binding handles deletes the entry.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NOTHING_TO_EXPORT	Nothing to export
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_NO_NS_PRIVILEGE	No privilege for name-service operation
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcBindingFromStringBinding, RpcEpRegister, RpcEpRegisterNoReplace, RpcNsBindingUnexport, RpcServerInqBindings, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf


RpcNsBindingImportBegin

The RpcNsBindingImportBegin function creates an import context for an interface and an object.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsBindingImportBegin(

unsigned long  EntryNameSyntax,
unsigned char *  EntryName,
RPC_IF_HANDLE  IfSpec,
UUID *  ObjUuid,
RPC_NS_HANDLE *  ImportContext
);
Parameters

EntryNameSyntax

Specifies an unsigned long value that indicates the syntax of the next argument, EntryName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

EntryName

Points to an entry name at which the search for compatible binding handles begins.

To use the entry name specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultEntry, provide a null pointer or an empty string. In this case, the EntryNameSyntax parameter is ignored and the run-time library uses the default syntax EntryName.

IfSpec

Specifies a stub-generated data structure indicating the interface to import. If the interface specification has not been exported or is of no concern to the caller, specify a null value for this argument. In this case, the bindings returned are only guaranteed to be of a compatible and supported protocol sequence and to contain the specified object UUID. The desired interface may not be supported by the contacted server.

ObjUuid

Points to an optional object UUID.

For a non-nil UUID, compatible binding handles are returned from an entry only if the server has exported the specified object UUID.

When the ObjUuid argument has a null pointer value or a nil UUID, the returned binding handles contain one of the object UUIDs exported by the compatible server. If the server did not export any object UUIDs, the returned compatible binding handles contain a nil object UUID.

ImportContext

Specifies a returned name-service handle for use with the RpcNsBindingImportNext and RpcNsBindingImportDone routines.

Remarks

The RpcNsBindingImportBegin routine creates an import context for importing client-compatible binding handles for servers that offer the specified interface and object.

Before calling the RpcNsBindingImportNext routine, the client application must first call RpcNsBindingImportBegin to create an import context. The arguments to this routine control the operation of the RpcNsBindingImportNext routine.

When finished importing binding handles, the client application calls the RpcNsBindingImportDone routine to delete the import context.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_ENTRY_NOT_FOUND	Name-service entry not found
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
RPC_S_INVALID_OBJECT	Invalid object
See Also

RpcNsBindingImportDone, RpcNsBindingImportNext


RpcNsBindingImportDone

The RpcNsBindingImportDone function signifies that a client has finished looking for a compatible server and deletes the import context.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsBindingImportDone(

RPC_NS_HANDLE *  ImportContext
);
Parameters

ImportContext

Points to a name-service handle to free. The name-service handle ImportContext points to is created by calling the RpcNsBindingImportBegin routine.

An argument value of NULL is returned.

Remarks

The RpcNsBindingImportDone routine frees an import context created by calling the RpcNsBindingImportBegin routine.

Typically, a client application calls RpcNsBindingImportDone after completing remote procedure calls to a server using a binding handle returned from the RpcNsBindingImportNext routine. However, a client application is responsible for calling RpcNsBindingImportDone for each created import context regardless of the status returned from the RpcNsBindingImportNext routine or the success in making remote procedure calls.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcNsBindingImportBegin, RpcNsBindingImportNext


RpcNsBindingImportNext

The RpcNsBindingImportNext function looks up an interface, and optionally an object, from a name-service database and returns a binding handle of a compatible server (if found).

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsBindingImportNext(

RPC_NS_HANDLE  ImportContext,
RPC_BINDING_HANDLE *  Binding
);
Parameters

ImportContext

Specifies a name-service handle returned from the RpcNsBindingImportBegin routine.

Binding

Returns a pointer to a client-compatible server binding handle for a server.

Remarks

The RpcNsBindingImportNext routine returns one client-compatible server binding handle for a server offering the interface and object UUID specified by the IfSpec and ObjUuid arguments in the RpcNsBindingImportBegin routine. The RpcNsBindingImportNext routine communicates only with the name-service database, not directly with servers.

The returned compatible binding handle always contains an object UUID. Its value depends on the ObjUuid argument value specified in the RpcNsBindingImportBegin routine as follows:

•	If a non-nil object UUID was specified, the returned binding handle contains that object UUID.

•	If a nil object UUID or null value was specified, the object UUID returned in the binding handle depends on how the server exported object UUIDs:

•	If the server did not export any object UUIDs, the returned binding handle contains a nil object UUID.

•	If the server exported one object UUID, the returned binding handle contains that object UUID.

•	If the server exported multiple object UUIDs, the returned binding handle contains one of the object UUIDs. The import-next operation selects the returned object UUID in a non-deterministic fashion. As a result, a different object UUID can be returned for each compatible binding handle from a single server entry.

The RpcNsBindingImportNext routine selects and returns one server binding handle from the compatible binding handles found. The client application can use that binding handle to attempt to make a remote procedure call to the server. If the client fails to establish a relationship with the server, it can call the RpcNsBindingImportNext routine again.

Each time the client calls the RpcNsBindingImportNext routine, the routine returns another server binding handle. The returned binding handles are unordered.

A client application calls the RpcNsBindingInqEntryName routine to obtain the name-service database in the entry name from which the binding handle came.

When the search reaches the end of the name-service database, the routine returns a status of RPC_S_NO_MORE_BINDINGS and returns a binding argument value of NULL.

The RpcNsBindingImportNext routine allocates storage for the data referenced by the returned Binding argument. When a client application finishes with the binding handle, it must call the RpcBindingFree routine to deallocate the storage. Each call to the RpcNsBindingImportNext routine requires a corresponding call to the RpcBindingFree routine.

The client is responsible for calling the RpcNsBindingImportDone routine. RpcNsBindingImportDone deletes the import context. The client also calls the RpcNsBindingImportDone routine if the application wants to start a new search for compatible servers (by calling the RpcNsBindingImportBegin routine). The order of binding handles returned is different for each new search. This means the order in which binding handles are returned to an application can be different each time the application is run.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NO_MORE_BINDINGS	No more bindings
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcBindingFree, RpcNsBindingImportBegin, RpcNsBindingImportDone, RpcNsBindingInqEntryName, RpcNsBindingLookupBegin, RpcNsBindingLookupDone, RpcNsBindingLookupNext, RpcNsBindingSelect


RpcNsBindingInqEntryName

The RpcNsBindingInqEntryName function returns the entry name from which the binding handle came.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsBindingInqEntryName(

RPC_BINDING_HANDLE  Binding,
unsigned long  EntryNameSyntax,
unsigned char * *  EntryName
);
Parameters

Binding

Specifies the binding handle whose name-service database entry name is returned.

EntryNameSyntax

Specifies an unsigned long value that indicates the syntax used in the returned argument, EntryName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

EntryName

Returns a pointer to a pointer to the name of the name-service database entry in which Binding was found.

Specify a null value to prevent RpcNsBindingInqEntryName from returning the EntryName argument. In this case, the application does not call the RpcStringFree routine.

Remarks

The RpcNsBindingInqEntryName routine returns the name of the name-service database entry from which a client-compatible binding handle came.

The RPC run-time library allocates memory for the string returned in the EntryName argument. The application is responsible for calling the RpcStringFree routine to deallocate that memory.

An entry name is associated only with binding handles returned from the RpcNsBindingImportNext, RpcNsBindingLookupNext, and RpcNsBindingSelect routines.

If the binding handle specified in the Binding argument was not returned from a name-service database entry (for example, if the binding handle was created by calling RpcBindingFromStringBinding), RpcNsBindingInqEntryName returns an empty string (“\0”) and an RPC_S_NO_ENTRY_NAME status code.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_NO_ENTRY_NAME	No entry name for binding
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
See Also

RpcBindingFromStringBinding, RpcNsBindingImportNext, RpcNsBindingLookupNext, RpcNsBindingSelect, RpcStringFree


RpcNsBindingLookupBegin

The RpcNsBindingLookupBegin function creates a lookup context for an interface and an object.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsBindingLookupBegin(

unsigned long  EntryNameSyntax,
unsigned char *  EntryName,
RPC_IF_HANDLE  IfSpec,
UUID *  ObjUuid,
unsigned long  BindingMaxCount,
RPC_NS_HANDLE *  LookupContext
);
Parameters

EntryNameSyntax

Specifies an unsigned long value that indicates the syntax of the next argument, EntryName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

EntryName

Points to an entry name at which the search for compatible bindings begins.

To use the entry name specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultEntry, provide a null pointer or an empty string. In this case, the EntryNameSyntax parameter is ignored and the run-time library uses the default syntax EntryName.

IfSpec

Specifies a stub-generated data structure indicating the interface to look up. If the interface specification has not been exported or is of no concern to the caller, specify a null value for this argument. In this case, the bindings returned are only guaranteed to be of a compatible and supported protocol sequence and to contain the specified object UUID. The desired interface may not be supported by the contacted server.

ObjUuid

Points to an optional object UUID.

For a non-nil UUID, compatible binding handles are returned from an entry only if the server has exported the specified object UUID.

For a null pointer value or a nil UUID for this argument, the returned binding handles contain one of the object UUIDs exported by the compatible server. If the server did not export any object UUIDs, the returned compatible binding handles contain a nil object UUID.

BindingMaxCount

Specifies the maximum number of bindings to return in the BindingVec argument from the RpcNsBindingLookupNext routine.

Specify a value of zero to use the default count of RPC_C_BINDING_MAX_COUNT_DEFAULT.

LookupContext

Returns a pointer to a name-service handle for use with the RpcNsBindingLookupNext and RpcNsBindingLookupDone routines.

Remarks

The RpcNsBindingLookupBegin routine creates a lookup context for locating client-compatible binding handles to servers that offer the specified interface and object.

Before calling the RpcNsBindingLookupNext routine, the client application must first call RpcNsBindingLookupBegin to create a lookup context. The arguments to this routine control the operation of the RpcNsBindingLookupNext routine.

When finished locating binding handles, the client application calls the RpcNsBindingLookupDone routine to delete the lookup context.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_ENTRY_NOT_FOUND	Name-service entry not found
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
RPC_S_INVALID_OBJECT	Invalid object
See Also

RpcNsBindingLookupDone, RpcNsBindingLookupNext


RpcNsBindingLookupDone

The RpcNsBindingLookupDone function signifies that a client has finished looking for compatible servers and deletes the lookup context.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsBindingLookupDone(

RPC_NS_HANDLE *  LookupContext
);
Parameters

LookupContext

Points to the name-service handle to free. The name-service handle LookupContext points to is created by calling the routine RpcNsBindingLookupBegin.

An argument value of NULL is returned.

Remarks

The RpcNsBindingLookupDone routine frees a lookup context created by calling the RpcNsBindingLookupBegin routine.

Typically, a client application calls RpcNsBindingLookupDone after completing remote procedure calls to a server using a binding handle returned from the RpcNsBindingLookupNext routine. However, a client application is responsible for calling RpcNsBindingLookupDone for each created lookup context, regardless of the status returned from the RpcNsBindingLookupNext routine or the success in making remote procedure calls.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcNsBindingLookupBegin, RpcNsBindingLookupNext


RpcNsBindingLookupNext

The RpcNsBindingLookupNext function returns a list of compatible binding handles for a specified interface and optionally an object.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsBindingLookupNext(

RPC_NS_HANDLE  LookupContext,
RPC_BINDING_VECTOR * *  BindingVec
);
Parameters

LookupContext

Specifies the name-service handle returned from the RpcNsBindingLookupBegin routine.

BindingVec

Returns a pointer to a pointer to a vector of client-compatible server binding handles.

Remarks

The RpcNsBindingLookupNext routine returns a vector of client-compatible server binding handles for a server offering the interface and object UUID specified by the IfSpec and ObjUuid arguments in the RpcNsBindingLookupBegin routine.

The RpcNsBindingLookupNext routine communicates only with the name-service database, not directly with servers.

The RpcNsBindingLookupNext routine traverses name-service database entries collecting client-compatible server binding handles from each entry. If the entry at which the search begins (see the EntryName argument in RpcNsBindingLookupBegin) contains binding handles as well as an RPC group and/or a profile, RpcNsBindingLookupNext returns the binding handles from EntryName before searching the group or profile. This means that RpcNsBindingLookupNext can return a partially full vector before processing the members of the group or profile. Each binding handle in the returned vector always contains an object UUID. Its value depends on the ObjUuid argument value specified in the RpcNsBindingLookupBegin routine as follows:

•	If a non-nil object UUID was specified, each returned binding handle contains that object UUID.

•	If a nil object UUID or null value was specified, the object UUID returned in each binding handle depends on how the server exported object UUIDs:

•	If the server did not export any object UUIDs, each returned binding handle contains a nil object UUID.

•	If the server exported one object UUID, each returned binding handle contains that object UUID.

•	If the server exported multiple object UUIDs, each binding handle contains one of the object UUIDs. The lookup-next operation selects the returned object UUID in a non-deterministic fashion. For this reason, a different object UUID can be returned for each compatible binding handle from a single server entry.

From the returned vector of server binding handles, the client application can employ its own criteria for selecting individual binding handles, or the application can call the RpcNsBindingSelect routine to select a binding handle. The RpcBindingToStringBinding and RpcStringBindingParse routines will be helpful for a client creating its own selection criteria.

The client application can use the selected binding handle to attempt to make a remote procedure call to the server. If the client fails to establish a relationship with the server, it can select another binding handle from the vector. When all of the binding handles in the vector have been used, the client application calls the RpcNsBindingLookupNext routine again.

Each time the client calls the RpcNsBindingLookupNext routine, the routine returns another vector of binding handles. The binding handles returned in each vector are unordered. The vectors returned from multiple calls to this routine are also unordered.

A client calls the RpcNsBindingInqEntryName routine to obtain the name-service database server entry name that the binding came from.

When the search reaches the end of the name-service database, RpcNsBindingLookupNext returns a status of RPC_S_NO_MORE_BINDINGS and returns a BindingVec argument value of NULL.

The RpcNsBindingLookupNext routine allocates storage for the data referenced by the returned BindingVec argument. When a client application finishes with the vector, it must call the RpcBindingVectorFree routine to deallocate the storage. Each call to the RpcNsBindingLookupNext routine requires a corresponding call to the RpcBindingVectorFree routine.

The client is responsible for calling the RpcNsBindingLookupDone routine. RpcNsBindingLookupDone deletes the lookup context. The client also calls the RpcNsBindingLookupDone routine if the application wants to start a new search for compatible servers (by calling the RpcNsBindingLookupBegin routine). The order of binding handles returned can be different for each new search.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NO_MORE_BINDINGS	No more bindings
RPC_S_NAME_SERVICE_UNAVAILABLE	Name-service unavailable
See Also

RpcBindingToStringBinding, RpcBindingVectorFree, RpcNsBindingInqEntryName, RpcNsBindingLookupBegin, RpcNsBindingLookupDone, RpcStringBindingParse


RpcNsBindingSelect

The RpcNsBindingSelect function returns a binding handle from a list of compatible binding handles.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsBindingSelect(

RPC_BINDING_VECTOR *  BindingVec,
RPC_BINDING_HANDLE *  Binding
);
Parameters

BindingVec

Points to the vector of client-compatible server binding handles from which a binding handle is selected. The returned binding vector no longer references the selected binding handle, which is returned separately in the Binding argument.

Binding

Returns a pointer to a selected binding handle.

Remarks

The RpcNsBindingSelect routine chooses and returns a client-compatible server binding handle from a vector of server binding handles.

Each time the client calls the RpcNsBindingSelect routine, the routine operation returns another binding handle from the vector.

When all of the binding handles have been returned from the vector, the routine returns a status of RPC_S_NO_MORE_BINDINGS and returns a Binding argument value of NULL.

The select operation allocates storage for the data referenced by the returned Binding argument. When a client finishes with the binding handle, it should call the RpcBindingFree routine to deallocate the storage. Each call to the RpcNsBindingSelect routine requires a corresponding call to the RpcBindingFree routine.

Clients can create their own select routines implementing application-specific selection criteria. In this case, the RpcStringBindingParse routine provides access to the fields of a binding.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NO_MORE_BINDINGS	No more bindings
See Also

RpcBindingFree, RpcNsBindingLookupNext, RpcStringBindingParse


RpcNsBindingUnexport

The RpcNsBindingUnexport function removes the binding handles for an interface and objects from an entry in the name-service database.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsBindingUnexport(

unsigned long  EntryNameSyntax,
unsigned char *  EntryName,
RPC_IF_HANDLE  IfSpec,
UUID_VECTOR *  ObjectUuidVec
);
Parameters

EntryNameSyntax

Specifies an unsigned long value that indicates the syntax of the next argument, EntryName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

EntryName

Points to the entry name from which to remove binding handles and object UUIDs.

IfSpec

Specifies an interface. A null argument value indicates not to unexport any binding handles (only object UUIDs are to be unexported).

ObjectUuidVec

Points to a vector of object UUIDs that the server no longer wants to offer. The application constructs this vector. A null argument value indicates there are no object UUIDs to unexport (only binding handles are to be unexported).

Remarks

The RpcNsBindingUnexport routine allows a server application to remove the following from a name-service database entry:

•	All the binding handles for a specific interface

•	One or more object UUIDs of resources

•	Both the binding handles and object UUIDs of resources

The RpcNsBindingUnexport routine unexports only the binding handles that match the interface UUID and the major and minor interface version numbers found in the IfSpec argument.

A server application can unexport the specified interface and objects in a single call to RpcNsBindingUnexport, or it can unexport them separately.

If RpcNsBindingUnexport does not find any binding handles for the specified interface, the routine returns an RPC_S_INTERFACE_NOT_FOUND status code and does not unexport the object UUIDs, if any were specified.

If one or more binding handles for the specified interface are found and unexported without error, RpcNsBindingUnexport unexports the specified object UUIDs, if any.

If any of the specified object UUIDs were not found, RpcNsBindingUnexport returns the RPC_S_NOT_ALL_OBJS_UNEXPORTED status code.

In addition to calling RpcNsBindingUnexport, a server should also call the RpcEpUnregister routine to unregister the endpoints the server previously registered with the local endpoint-map database.

A server entry must have at least one binding handle to exist. As a result, exporting only UUIDs to a non-existing entry has no effect, and unexporting all binding handles deletes the entry.

Use RpcNsBindingUnexport judiciously. To keep an automatically activated server available, you must leave its binding handles in the name-service database between the times when server processes are activated. Therefore, reserve this routine for when you expect a server to be unavailable for an extended time — for example, when it is being permanently removed from service.

Note  Name-service databases are designed to be relatively stable. In replicated name-service databases, frequent use of the RpcNsBindingExport and RpcNsBindingUnexport routines causes the name-service database to repeatedly remove and replace the same entry and can cause performance problems.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_VERS_OPTION	Invalid version option
RPC_S_NOTHING_TO_UNEXPORT	Nothing to unexport
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_ENTRY_NOT_FOUND	Name-service entry not found
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
RPC_S_INTERFACE_NOT_FOUND	Interface not found
RPC_S_NOT_ALL_OBJS_UNEXPORTED	Not all objects unexported
See Also

RpcEpUnregister, RpcNsBindingExport


RpcNsEntryExpandName

The RpcNsEntryExpandName function expands a name-service entry name.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsEntryExpandName(

unsigned long  EntryNameSyntax,
unsigned char *  EntryName,
unsigned char * *  ExpandedName
);
Parameters

EntryNameSyntax

Specifies an integer value that indicates the syntax of the next argument, EntryName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

EntryName

Points to the entry name to expand.

ExpandedName

Returns a pointer to a pointer to the expanded version of EntryName.

Remarks

Note  This DCE function is not supported by the Microsoft Locator version 1.0.

An application calls the RpcNsEntryExpandName routine to obtain a fully expanded entry name.

The RPC run-time library allocates memory for the returned ExpandedName argument. The application is responsible for calling the RpcStringFree routine for that returned argument string.

The returned expanded entry name accounts for local name translations and for differences in locally defined naming schemas.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INCOMPLETE_NAME	Incomplete name
See Also

RpcStringFree


RpcNsEntryObjectInqBegin

The RpcNsEntryObjectInqBegin function creates an inquiry context for a name-service database entry’s objects.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsEntryObjectInqBegin(

unsigned long  EntryNameSyntax,
unsigned char *  EntryName,
RPC_NS_HANDLE *  InquiryContext
);
Parameters

EntryNameSyntax

Specifies an integer value that indicates the syntax to use in the next argument, EntryName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

EntryName

Points to the name-service database entry name for which object UUIDs are to be viewed.

InquiryContext

Returns a pointer to a name-service handle for use with the RpcNsEntryObjectInqNext and RpcNsEntryObjectInqDone routines.

Remarks

The RpcNsEntryObjectInqBegin routine creates an inquiry context for viewing the object UUIDs exported to EntryName.

Before calling the RpcNsEntryObjectInqNext routine, the application must first call RpcNsEntryObjectInqBegin to create an inquiry context.

When finished viewing the object UUIDs, the application calls the RpcNsEntryObjectInqDone routine to delete the inquiry context.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_ENTRY_NOT_FOUND	Name-service entry not found
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcNsBindingExport, RpcNsEntryObjectInqDone, RpcNsEntryObjectInqNext


RpcNsEntryObjectInqDone

The RpcNsEntryObjectInqDone function deletes the inquiry context for a name-service database entry’s objects.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsEntryObjectInqDone(

RPC_NS_HANDLE *  InquiryContext
);
Parameters

InquiryContext

Points to a name-service handle specifying the object UUIDs exported to the EntryName argument specified in the RpcNsEntryObjectInqBegin routine.

An argument value of NULL is returned.

Remarks

The RpcNsEntryObjectInqDone routine frees an inquiry context created by calling the RpcNsEntryObjectInqBegin routine.

An application calls RpcNsEntryObjectInqDone after viewing exported object UUIDs using the RpcNsEntryObjectInqNext routine.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcNsEntryObjectInqBegin, RpcNsEntryObjectInqNext


RpcNsEntryObjectInqNext

The RpcNsEntryObjectInqNext function returns one object at a time from a name-service database entry.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsEntryObjectInqNext(

RPC_NS_HANDLE  InquiryContext,
UUID *  ObjUuid
);
Parameters

InquiryContext

Specifies a name-service handle that indicates the object UUIDs for a name-service database entry.

ObjUuid

Returns a pointer to an exported object UUID.

Remarks

The RpcNsEntryObjectInqNext routine returns one of the object UUIDs exported to the name-service database entry specified by the EntryName argument in the RpcNsEntryObjectInqBegin routine.

An application can view all of the exported object UUIDs by repeatedly calling the RpcNsEntryObjectInqNext routine. When all the object UUIDs have been viewed, this routine returns an RPC_S_NO_MORE_MEMBERS status code. The returned object UUIDs are unordered.

The application supplies the memory for the object UUID returned in the ObjUuid argument.

After viewing the object UUIDs, the application must call the RpcNsEntryObjectInqDone routine to release the inquiry context.

The order in which object UUIDs are returned can be different for each viewing of an entry. This means that the order in which object UUIDs are returned to an application can be different each time the application is run.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NO_MORE_MEMBERS	No more members
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_ENTRY_NOT_FOUND	Name-service entry not found
RPC_S_NAME_SERVICE_UNAVAILABLE	Name-service unavailable
See Also

RpcNsBindingExport, RpcNsEntryObjectInqBegin, RpcNsEntryObjectInqDone


RpcNsGroupDelete

The RpcNsGroupDelete function deletes a group attribute.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsGroupDelete(

unsigned long  GroupNameSyntax,
unsigned char *  GroupName
);
Parameters

GroupNameSyntax

Specifies an integer value that indicates the syntax of the next parameter, GroupName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

GroupName

Points to the name of the RPC group to delete.

Remarks

Note  This DCE function is not supported by the Microsoft Locator.

The RpcNsGroupDelete routine deletes the group attribute from the specified name-service database entry.

Neither the specified name-service database entry nor the group members are deleted.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_ENTRY_NOT_FOUND	Name-service entry not found
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcNsGroupMbrAdd, RpcNsGroupMbrRemove


RpcNsGroupMbrAdd

The RpcNsGroupMbrAdd function adds an entry name to a group. If necessary, it creates the entry.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsGroupMbrAdd(

unsigned long  GroupNameSyntax,
unsigned char *  GroupName,
unsigned long  MemberNameSyntax,
unsigned char *  MemberName
);
Parameters

GroupNameSyntax

Specifies an integer value that indicates the syntax of the next argument, GroupName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

GroupName

Points to the name of the RPC group to receive a new member.

MemberNameSyntax

Specifies an integer value that indicates the syntax to use in the MemberName argument.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

MemberName

Points to the name of the new RPC group member.

Remarks

Note  This DCE function is not supported by the Microsoft Locator.

The RpcNsGroupMbrAdd adds a name-service database entry name as a member to the RPC group attribute.

If the GroupName entry does not exist, RpcNsGroupMbrAdd tries to create the entry with a group attribute and adds the group member specified by the MemberName argument. In this case, the application must have the privilege to create the entry. Otherwise, a management application with the necessary privilege should create the entry by calling the RpcNsMgmtEntryCreate routine before the application is run.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcNsGroupMbrRemove, RpcNsMgmtEntryCreate


RpcNsGroupMbrInqBegin

The RpcNsGroupMbrInqBegin function creates an inquiry context for viewing group members.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsGroupMbrInqBegin(

unsigned long  GroupNameSyntax,
unsigned char *  GroupName,
unsigned long  MemberNameSyntax,
RPC_NS_HANDLE *  InquiryContext
);
Parameters

GroupNameSyntax

Specifies an integer value that indicates the syntax of the next argument, GroupName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

GroupName

Points to the name of the RPC group to view.

MemberNameSyntax

Specifies an integer value that indicates the syntax of the return argument, MemberName, in the RpcNsGroupMbrInqNext routine.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

InquiryContext

Returns a pointer to a name-service handle for use with the RpcNsGroupMbrInqNext and RpcNsGroupMbrInqDone routines.

Remarks

Note  This DCE function is not supported by the Microsoft Locator.

The RpcNsGroupMbrInqBegin routine creates an inquiry context for viewing the members of an RPC group.

Before calling the RpcNsGroupMbrInqNext routine, the application must first call RpcNsGroupMbrInqBegin to create an inquiry context.

When finished viewing the RPC group members, the application calls the RpcNsGroupMbrInqDone routine to delete the inquiry context.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_ENTRY_NOT_FOUND	Name-service entry not found
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcNsGroupMbrAdd, RpcNsGroupMbrInqDone, RpcNsGroupMbrInqNext


RpcNsGroupMbrInqDone

The RpcNsGroupMbrInqDone function deletes the inquiry context for a group.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsGroupMbrInqDone(

RPC_NS_HANDLE *  InquiryContext
);
Parameters

InquiryContext

Points to a name-service handle to free. An argument value of NULL is returned.

Remarks

Note  This DCE function is not supported by the Microsoft Locator.

The RpcNsGroupMbrInqDone routine frees an inquiry context created by calling the RpcNsGroupMbrInqBegin routine.

An application calls RpcNsGroupMbrInqDone after viewing RPC group members using the RpcNsGroupMbrInqNext routine.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NS_HANDLE	Invalid name-service handle
See Also

RpcNsGroupMbrInqBegin, RpcNsGroupMbrInqNext


RpcNsGroupMbrInqNext

The RpcNsGroupMbrInqNext function returns one entry name from a group at a time.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsGroupMbrInqNext(

RPC_NS_HANDLE  InquiryContext,
unsigned char * *  MemberName
);
Parameters

InquiryContext

Specifies a name-service handle.

MemberName

Returns a pointer to a pointer to an RPC group member name.

The syntax of the returned name was specified by the MemberNameSyntax argument in the RpcNsGroupMbrInqBegin routine.

Specify a null value to prevent RpcNsGroupMbrInqNext from returning the MemberName argument. In this case, the application does not call the RpcStringFree routine.

Remarks

Note  This DCE function is not supported by the Microsoft Locator.

The RpcNsGroupMbrInqNext routine returns one member of the RPC group specified by the GroupName argument in the RpcNsGroupMbrInqBegin routine.

An application can view all the members of an RPC group set by repeatedly calling the RpcNsGroupMbrInqNext routine. When all the group members have been viewed, this routine returns an RPC_S_NO_MORE_MEMBERS status code. The returned group members are unordered.

On each call to RpcNsGroupMbrInqNext that returns a member name, the RPC run-time library allocates memory for the returned MemberName. The application is responsible for calling the RpcStringFree routine for each returned MemberName string.

After viewing the RPC group’s members, the application must call the RpcNsGroupMbrInqDone routine to release the inquiry context.

The order in which group members are returned can be different for each viewing of a group. This means that the order in which group members are returned to an application can be different each time the application is run.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NS_HANDLE	Invalid name-service handle
RPC_S_NO_MORE_MEMBERS	No more members
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcNsGroupMbrInqBegin, RpcNsGroupMbrInqDone, RpcStringFree


RpcNsGroupMbrRemove

The RpcNsGroupMbrRemove function removes an entry name from a group.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsGroupMbrRemove(

unsigned long  GroupNameSyntax,
unsigned char *  GroupName,
unsigned long  MemberNameSyntax,
unsigned char *  MemberName
);
Parameters

GroupNameSyntax

Specifies an integer value that indicates the syntax of the next argument, GroupName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

GroupName

Points to the name of the RPC group from which to remove the member name.

MemberNameSyntax

Specifies an integer value that indicates the syntax to use in the MemberName argument.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

MemberName

Points to the name of the member to remove from the RPC group attribute in the entry GroupName.

Remarks

Note  This DCE function is not supported by the Microsoft Locator.

The RpcNsGroupMbrRemove routine removes a member from the RPC group attribute in the GroupName argument.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_ENTRY_NOT_FOUND	Name-service entry not found
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
RPC_S_GROUP_MEMBER_NOT_FOUND	Group member not found
See Also

RpcNsGroupMbrAdd


RpcNsMgmtBindingUnexport

The RpcNsMgmtBindingUnexport function removes multiple binding handles and objects from an entry in the name-service database.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsMgmtBindingUnexport(

unsigned long  EntryNameSyntax,
unsigned char *  EntryName,
RPC_IF_ID *  IfId,
unsigned long  VersOption,
UUID_VECTOR *  ObjectUuidVec
);
Parameters

EntryNameSyntax

Specifies an integer value that indicates the syntax of the next argument, EntryName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

EntryName

Points to the name of the entry from which to remove binding handles and object UUIDs.

IfId

Points to an interface identification. A null argument value indicates not to unexport any binding handles (only object UUIDs are to be unexported).

VersOption

Specifies how the RpcNsMgmtBindingUnexport routine uses the VersMajor and VersMinor fields of the IfId argument.

The following table describes valid values for the VersOption argument:

VersOption values	Description
RPC_C_VERS_ALL	Unexports all bindings for the interface UUID in IfId, regardless of the version numbers. For this value, specify 0 for both the major and minor versions in IfId.
RPC_C_VERS_IF_ID	Unexports the bindings for the compatible interface UUID in IfId with the same major version and with a minor version greater than or equal to the minor version in IfId.
RPC_C_VERS_EXACT	Unexports the bindings for the interface UUID in IfId with the same major and minor versions as in IfId.
RPC_C_VERS_MAJOR_ONLY	Unexports the bindings for the interface UUID in IfId with the same major version as in IfId (ignores the minor version). For this value, specify 0 for the minor version in IfId.
RPC_C_VERS_UPTO	Unexports the bindings that offer a version of the specified interface UUID less than or equal to the specified major and minor version. (For example, if the IfId contained V2.0 and the name-service database entry contained binding handles with the versions V1.3, V2.0, and V2.1, the RpcNsMgmtBindingUnexport routine unexports the binding handles with V1.3 and V2.0.)
ObjectUuidVec

Points to a vector of object UUIDs that the server no longer wants to offer. The application constructs this vector. A null argument value indicates there are no object UUIDs to unexport (only binding handles are to be unexported).

Remarks

The RpcNsMgmtBindingUnexport routine allows a management application to remove one of the following from a name-service database entry:

•	All the binding handles for a specified interface UUID, qualified by the interface version numbers (major and minor)

•	One or more object UUIDs of resources

•	Both binding handles and object UUIDs of resources

A management application can unexport interfaces and objects in a single call to RpcNsMgmtBindingUnexport, or it can unexport them separately.

If RpcNsMgmtBindingUnexport does not find any binding handles for the specified interface, the routine returns an RPC_S_INTERFACE_NOT_FOUND status code and does not unexport the object UUIDs, if any were specified.

If one or more binding handles for the specified interface are found and unexported without error, RpcNsMgmtBindingUnexport unexports the specified object UUIDs, if any.

If any of the specified object UUIDs were not found, RpcNsMgmtBindingUnexport returns the RPC_S_NOT_ALL_OBJS_UNEXPORTED status code.

In addition to calling RpcNsMgmtBindingUnexport, a management application should also call the RpcMgmtEpUnregister routine to unregister the servers that have registered with the endpoint-map database.

Note  Name-service databases are designed to be relatively stable. In replicated name services, frequent use of the RpcNsBindingExport and RpcNsBindingUnexport routines causes the name service to repeatedly remove and replace the same entry and can cause performance problems.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_VERS_OPTION	Invalid version option
RPC_S_NOTHING_TO_UNEXPORT	Nothing to unexport
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_ENTRY_NOT_FOUND	Name-service entry not found
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
RPC_S_INTERFACE_NOT_FOUND	Interface not found
RPC_S_NOT_ALL_OBJS_UNEXPORTED	Not all objects unexported
See Also

RpcMgmtEpUnregister, RpcNsBindingExport, RpcNsBindingUnexport


RpcNsMgmtEntryCreate

The RpcNsMgmtEntryCreate function creates a name-service database entry.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsMgmtEntryCreate(

unsigned long  EntryNameSyntax,
unsigned char *  EntryName
);
Parameters

EntryNameSyntax

Specifies an integer value that indicates the syntax of the next argument, EntryName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

EntryName

Points to the name of the entry to create.

Remarks

Note  This DCE function is not supported by the Microsoft Locator.

The RpcNsMgmtEntryCreate routine creates an entry in the name-service database.

A management application can call RpcNsMgmtEntryCreate to create a name-service database entry for use by another application that does not itself have the necessary name-service database privileges to create an entry.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_ENTRY_ALREADY_EXISTS	Name-service entry already exists
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcNsMgmtEntryDelete


RpcNsMgmtEntryDelete

The RpcNsMgmtEntryDelete function deletes a name-service database entry.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsMgmtEntryDelete(

unsigned long  EntryNameSyntax,
unsigned char *  EntryName
);
Parameters

EntryNameSyntax

Specifies an integer value that indicates the syntax of the next argument, EntryName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

EntryName

Points to the name of the entry to delete.

Remarks

The RpcNsMgmtEntryDelete routine removes an entry from the name-service database.

Management applications use this routine only when an entry is no longer needed — for example, when a server is being permanently removed from service.

Because name-service databases are designed to be relatively stable, the frequent use of the RpcNsMgmtEntryDelete routine in client or server applications can result in performance problems. Creating and deleting entries in client or server applications causes the name-service database to repeatedly remove and replace the same entry. This can lead to performance problems in replicated name-service databases.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_ENTRY_NOT_FOUND	Name-service entry not found
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
RPC_S_NOT_RPC_ENTRY	Not an RPC entry
See Also

RpcNsMgmtEntryCreate


RpcNsMgmtEntryInqIfIds

The RpcNsMgmtEntryInqIfIds function returns the list of interfaces exported to a name-service database entry.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsMgmtEntryInqIfIds(

unsigned long  EntryNameSyntax,
unsigned char *  EntryName,
RPC_IF_ID_VECTOR * *  IfIdVec
);
Parameters

EntryNameSyntax

Specifies an integer value that indicates the syntax of the next argument, EntryName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

EntryName

Points to the name-service database entry name for which an interface identification vector is returned.

IfIdVec

Returns a pointer to a pointer to the interface-identification vector.

Remarks

The RpcNsMgmtEntryInqIfIds routine returns an interface-identification vector containing the interfaces of binding handles exported by a server to EntryName.

RpcNsMgmtEntryInqIfIds uses an expiration age of 0, causing an immediate update of the local copy of name-service data.

The calling application is responsible for calling the RpcIfIdVectorFree routine to release memory used by the vector.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_ENTRY_NOT_FOUND	Name-service entry not found
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcIfIdVectorFree, RpcIfInqId, RpcNsBindingExport


RpcNsMgmtHandleSetExpAge

The RpcNsMgmtHandleSetExpAge function sets the expiration age of a name-service handle for local copies of name-service data.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsMgmtHandleSetExpAge(

RPC_NS_HANDLE  NsHandle,
unsigned long  ExpirationAge
);
Parameters

NsHandle

Specifies a name-service handle that an expiration age is set for. A name-service handle is returned from a name-service “begin” operation.

ExpirationAge

Specifies an integer value in seconds that sets the expiration age of local name-service data read by all “next” routines using the specified NsHandle argument.

An expiration age of 0 causes an immediate update of the local name-service data.

Remarks

The RpcNsMgmtHandleSetExpAge routine sets a handle-expiration age for a specified name-service handle (NsHandle). The expiration age is the amount of time that a local copy of data from a name-service attribute can exist before a request from the application for the attribute requires updating the local copy. When an application begins running, the RPC run-time library specifies a random value of two hours as the default expiration age. The default is global to the application. A handle-expiration age applies only to a specific name-service handle and temporarily overrides the current global expiration age.

Normally, you should avoid using RpcNsMgmtHandleSetExpAge; instead, you should rely on the application’s global expiration age.

A handle-expiration age is used exclusively by name-service “next” operations (which read data from name-service attributes). A “next” operation normally starts by looking for a local copy of the attribute data being requested by an application. In the absence of a local copy, the “next” operation creates one with fresh attribute data from the name-service database. If a local copy already exists, the operation compares its actual age to the expiration age being used by the application (which in this case is the expiration age set for the name-service handle). If the actual age exceeds the handle-expiration age, the operation automatically tries to update the local copy with fresh attribute data. If updating is impossible, the old local data remains in place and the “next” operation fails, returning the RPC_S_NAME_SERVICE_UNAVAILABLE status code.

The scope of a handle-expiration age is a single series of “next” operations. The RpcNsMgmtHandleSetExpAge routine operates within the following context:

•	A “begin” operation creates a name-service handle.

•	A call to the RpcNsMgmtHandleSetExpAge routine creates an expiration age for the handle.

•	A series of “next” operations for the name-service handle uses the handle expiration age.

•	A “done” operation for the name-service handle deletes both the handle and its expiration age.

Setting the handle-expiration age to a small value causes the name-service “next” operations to frequently update local data for any name-service attribute requested by your application. For example, setting the expiration age to 0 forces the “next” operation to update local data for the name-service attribute requested by your application. Therefore, setting a small handle-expiration age can create performance problems for your application. Furthermore, if your application is using a remote name-service server, a small expiration age can adversely affect network performance for all applications.

Limit the use of RpcNsMgmtHandleSetExpAge to the following situations:

•	When you must always get accurate name-service data.

For example, during management operations to update a profile, you may need to always see the profile’s current contents. In this case, before beginning to inquire about a profile, your application should call the RpcNsMgmtHandleSetExpAge routine and specify 0 for the ExpirationAge argument.

•	When a request using the default expiration age has failed, and your application needs to retry the operation.

For example, a client application using name-service “import” operations should first try to obtain bindings using the application’s default expiration age. However, sometimes the “import-next” operation returns either no binding handles or an insufficient number of them. In this case, the client could retry the “import” operation and, after the RpcNsBindingImportBegin call, include a RpcNsMgmtHandleSetExpAge call and specify 0 for the ExpirationAge argument. When the client calls the “import-next” routine again, the small handle-expiration age causes the “import-next” operation to update the local attribute data.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcNsBindingImportBegin, RpcNsMgmtInqExpAge, RpcNsMgmtSetExpAge


RpcNsMgmtInqExpAge

The RpcNsMgmtInqExpAge function returns the global expiration age for local copies of name-service data.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsMgmtInqExpAge(

unsigned long *  ExpirationAge
);
Parameters

ExpirationAge

Returns a pointer to the default expiration age, in seconds. This value is used by all name-service “read” operations (that is, all “next” operations).

Remarks

The RpcNsMgmtInqExpAge routine returns the expiration age that the application is using. The expiration age is the amount of time in seconds that a local copy of data from a name-service attribute can exist before a request from the application for the attribute requires updating the local copy. When an application begins running, the RPC run-time library specifies a random value of two hours as the default expiration age. The default is global to the application.

An expiration age is used by name-service “next” operations (which read data from name-service attributes). A “next” operation normally starts by looking for a local copy of the attribute data being requested by an application. In the absence of a local copy, the “next” operation creates one with fresh attribute data from the name-service database. If a local copy already exists, the operation compares its actual age to the expiration age being used by the application. If the actual age exceeds the expiration age, the operation automatically tries to update the local copy with fresh attribute data. If updating is impossible, the old local data remains in place and the “next” operation fails.

Applications normally should use only the default expiration age. For special cases, however, an application can substitute a user-supplied global expiration age for the default by calling the RpcNsMgmtSetExpAge routine. The RpcNsMgmtInqExpAge routine returns the current global expiration age, whether a default or a user-supplied value.

An application can also override the global expiration age temporarily by calling the RpcNsMgmtHandleSetExpAge routine.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcNsMgmtHandleSetExpAge, RpcNsMgmtSetExpAge


RpcNsMgmtSetExpAge

The RpcNsMgmtSetExpAge function modifies the application’s global expiration age for local copies of name-service data.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsMgmtSetExpAge(

unsigned long  ExpirationAge
);
Parameters

ExpirationAge

Specifies an integer value in seconds that indicates the default expiration age for local name-service data. This expiration age is applied to all name-service “read” operations (that is, all “next” operations).

An expiration age of 0 causes an immediate update of the local name-service data.

To reset the expiration age to an RPC-assigned random value of two hours, specify a value of RPC_C_NS_DEFAULT_EXP_AGE.

Remarks

The RpcNsMgmtSetExpAge routine modifies the global expiration age of an application. The expiration age is the amount of time that a local copy of data from a name-service attribute can exist before a request from the application for the attribute requires updating the local copy. When an application begins running, the RPC run-time library specifies a random value of between 8 and 12 hours as the default expiration age. The default is global to the application.

Normally, you should avoid using RpcNsMgmtSetExpAge; instead, you should rely on the default expiration age.

An expiration age is used by name-service “next” operations (which read data from name-service attributes). A “next” operation normally starts by looking for a local copy of the attribute data being requested by an application. In the absence of a local copy, the “next” operation creates one with fresh attribute data from the name-service database. If a local copy already exists, the operation compares its actual age to the expiration age being used by the application. If the actual age exceeds the expiration age, the operation automatically tries to update the local copy with fresh attribute data. If updating is impossible, the old local data remains in place and the “next” operation fails, returning the RPC_S_NAME_SERVICE_UNAVAILABLE status code.

Setting the expiration age to a small value causes the name-service “next” operations to frequently update local data for any name-service attribute requested by your application. For example, setting the expiration age to 0 forces all “next” operations to update local data for the name-service attribute requested by your application. Therefore, setting small expiration ages can create performance problems for your application and increase network traffic. Furthermore, if your application is using a remote name-service server, a small expiration age can adversely affect network performance for all applications.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcNsMgmtHandleSetExpAge


RpcNsProfileDelete

The RpcNsProfileDelete function deletes a profile attribute.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsProfileDelete(

unsigned long  ProfileNameSyntax,
unsigned char *  ProfileName
);
Parameters

ProfileNameSyntax

Specifies an integer value that indicates the syntax of the next argument, ProfileName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

ProfileName

Points to the name of the profile to delete.

Remarks

Note  This DCE function is not supported by the Microsoft Locator.

The RpcNsProfileDelete routine deletes the profile attribute from the specified name-service entry (ProfileName).

Neither ProfileName nor the entry names included as members in each profile element are deleted.

Use RpcNsProfileDelete cautiously; deleting a profile can have the unwanted effect of breaking a hierarchy of profiles.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_ENTRY_NOT_FOUND	Name-service entry not found
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcNsProfileEltAdd, RpcNsProfileEltRemove


RpcNsProfileEltAdd

The RpcNsProfileEltAdd function adds an element to a profile. If necessary, it creates the entry.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsProfileEltAdd(

unsigned long  ProfileNameSyntax,
unsigned char *  ProfileName,
RPC_IF_ID *  IfId,
unsigned long  MemberNameSyntax,
unsigned char *  MemberName,
unsigned long  Priority,
unsigned char *  Annotation
);
Parameters

ProfileNameSyntax

Specifies an integer value that indicates the syntax of the next argument, ProfileName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

ProfileName

Points to the name of the profile to receive a new element.

IfId

Points to the interface identification of the new profile element. To add or replace the default profile element, specify a null value.

MemberNameSyntax

Specifies an integer value that indicates the syntax of the next argument, MemberName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

MemberName

Points to a name-service entry name to include in the new profile element.

Priority

Specifies an integer value (0 through 7) that indicates the relative priority for using the new profile element during the “import” and “lookup” operations. A value of 0 is the highest priority; a value of 7 is the lowest priority.

When adding a default profile member, use a value of 0.

Annotation

Points to an annotation string stored as part of the new profile element. The string can be up to 17 characters long. Specify a null value or a null-terminated string if there is no annotation string.

The string is used by applications for informational purposes only. For example, an application can use this string to store the interface-name string specified in the IDL file.

RPC does not use the annotation string during “lookup” or “import” operations or for enumerating profile elements.

Remarks

Note  This DCE function is not supported by the Microsoft Locator.

The RpcNsProfileEltAdd routine adds an element to the profile attribute of the name-service entry specified by the ProfileName argument.

If the ProfileName entry does not exist, RpcNsProfileEltAdd tries to create the entry with a profile attribute and adds the profile element specified by the IfId, MemberName, Priority, and Annotation arguments. In this case, the application must have the privilege to create the entry. Otherwise, a management application with the necessary privileges should create the entry by calling the RpcNsMgmtEntryCreate routine before the application is run.

If an element with the specified member name and interface identification is already in the profile, RpcNsProfileEltAdd updates the element’s priority and annotation string using the values provided in the Priority and Annotation arguments.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcIfInqId, RpcNsMgmtEntryCreate, RpcNsProfileEltRemove


RpcNsProfileEltInqBegin

The RpcNsProfileEltInqBegin function creates an inquiry context for viewing the elements in a profile.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsProfileEltInqBegin(

unsigned long  ProfileNameSyntax,
unsigned char *  ProfileName,
unsigned long  InquiryType,
RPC_IF_ID *  IfId,
unsigned long  VersOption,
unsigned long  MemberNameSyntax,
unsigned char *  MemberName,
RPC_NS_HANDLE *  InquiryContext
);
Parameters

ProfileNameSyntax

Specifies an integer value that indicates the syntax of the next argument, ProfileName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

ProfileName

Points to the name of the profile to view.

InquiryType

Specifies an integer value indicating the type of inquiry to perform on the profile. The following table lists valid inquiry types:

Inquiry type	Description
RPC_C_PROFILE_DEFAULT_ELT	Searches the profile for the default profile element, if any. The IfId, VersOption, and MemberName arguments are ignored.
RPC_C_PROFILE_ALL_ELTS	Returns every element from the profile. The IfId, VersOption, and MemberName arguments are ignored.
RPC_C_PROFILE_MATCH_BY_IF	Searches the profile for the elements that contain the interface identification specified by the IfId and VersOption values. The MemberName argument is ignored.
RPC_C_PROFILE_MATCH_BY_MBR	Searches the profile for the elements that contain the member name specified by the MemberName argument. The IfId and VersOption arguments are ignored.
RPC_C_PROFILE_MATCH_BY_BOTH	Searches the profile for the elements that contain the interface identification and member identified by the IfId, VersOption, and MemberName arguments.
IfId

Points to the interface identification of the profile elements to be returned by the RpcNsProfileEltInqNext routine.

The IfId argument is used only when specifying a value of RPC_C_PROFILE_MATCH_BY_IF or RPC_C_PROFILE_MATCH_BY_BOTH for the InquiryType argument. Otherwise, IfId is ignored and a null value can be specified.

VersOption

Specifies how the RpcNsProfileEltInqNext routine uses the IfId argument.

The VersOption argument is used only when specifying a value of RPC_C_PROFILE_MATCH_BY_IF or RPC_C_PROFILE_MATCH_BY_BOTH for the InquiryType argument. Otherwise, this argument is ignored and a 0 value can be specified.

The following table describes valid values for the VersOption argument.

Values	Description
RPC_C_VERS_ALL	Returns profile elements that offer the specified interface UUID, regardless of the version numbers. For this value, specify 0 for both the major and minor versions in IfId.
RPC_C_VERS_COMPATIBLE	Returns profile elements that offer the same major version of the specified interface UUID and a minor version greater than or equal to the minor version of the specified interface UUID.
RPC_C_VERS_EXACT	Returns profile elements that offer the specified version of the specified interface UUID.
RPC_C_VERS_MAJOR_ONLY	Returns profile elements that offer the same major version of the specified interface UUID (ignores the minor version). For this value, specify 0 for the minor version in IfId.
RPC_C_VERS_UPTO	Returns profile elements that offer a version of the specified interface UUID less than or equal to the specified major and minor version. (For example, if the IfId contained V2.0 and the profile contained elements with V1.3, V2.0, and V2.1, the RpcNsProfileEltInqNext routine returns the elements with V1.3 and V2.0.)
MemberNameSyntax

Specifies an integer value that indicates the syntax of the next argument, MemberName, and of the return argument MemberName in the RpcNsProfileEltInqNext routine.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

MemberName

Points to the member name that the RpcNsProfileEltInqNext routine looks for in profile elements.

The MemberName argument is used only when specifying a value of RPC_C_PROFILE_MATCH_BY_MBR or RPC_C_PROFILE_MATCH_BY_BOTH for the InquiryType argument. Otherwise, MemberName is ignored and a null value can be specified.

InquiryContext

Returns a pointer to a name-service handle for use with the RpcNsProfileEltInqNext and RpcNsProfileEltInqDone routines.

Remarks

Note  This DCE function is not supported by the Microsoft Locator.

The RpcNsProfileEltInqBegin routine creates an inquiry context for viewing the elements in a profile.

Using the InquiryType argument, an application specifies which of the following profile elements are to be returned from calls to the RpcNsProfileEltInqNext routine:

•	The default element

•	All elements

•	Elements with the specified interface identification

•	Elements with the specified member name

•	Elements with both the specified interface identification and member name

Before calling the RpcNsProfileEltInqNext routine, the application must first call RpcNsProfileEltInqBegin to create an inquiry context.

When finished viewing the profile elements, the application calls the RpcNsProfileEltInqDone routine to delete the inquiry context.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_VERS_OPTION	Invalid version option
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_ENTRY_NOT_FOUND	Name-service entry not found
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcIfInqId, RpcNsProfileEltInqDone, RpcNsProfileEltInqNext


RpcNsProfileEltInqDone

The RpcNsProfileEltInqDone function deletes the inquiry context for viewing the elements in a profile.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsProfileEltInqDone(

RPC_NS_HANDLE *  InquiryContext
);
Parameters

InquiryContext

Points to a name-service handle to free. The name-service handle InquiryContext points to is created by calling the RpcNsProfileEltInqBegin routine.

An argument value of NULL is returned.

Remarks

Note  This DCE function is not supported by the Microsoft Locator.

The RpcNsProfileEltInqDone routine frees an inquiry context created by calling the RpcNsProfileEltInqBegin routine.

An application calls RpcNsProfileEltInqDone after viewing profile elements using the RpcNsProfileEltInqNext routine.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcNsProfileEltInqBegin, RpcNsProfileEltInqNext


RpcNsProfileEltInqNext

The RpcNsProfileEltInqNext function returns one element at a time from a profile.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsProfileEltInqNext(

RPC_NS_HANDLE  InquiryContext,
RPC_IF_ID *  IfId,
unsigned char * *  MemberName,
unsigned long *  Priority,
unsigned char * *  Annotation
);
Parameters

InquiryContext

Specifies a name-service handle returned from the RpcNsProfileEltInqBegin routine.

IfId

Returns a pointer to the interface identification of the profile element.

MemberName

Returns a pointer to a pointer to the profile element’s member name.

The syntax of the returned name was specified by the MemberNameSyntax argument in the RpcNsProfileEltInqBegin routine.

Specify a null value to prevent RpcNsProfileEltInqNext from returning the MemberName argument. In this case, the application does not call the RpcStringFree routine.

Priority

Returns a pointer to the profile-element priority.

Annotation

Returns a pointer to a pointer to the annotation string for the profile element. If there is no annotation string in the profile element, the string “\0” is returned.

Specify a null value to prevent RpcNsProfileEltInqNext from returning the Annotation argument. In this case, the application does not need to call the RpcStringFree routine.

Remarks

Note  This DCE function is not supported by the Microsoft Locator.

The RpcNsProfileEltInqNext routine returns one element from the profile specified by the ProfileName argument in the RpcNsProfileEltInqBegin routine. Regardless of the value specified for the InquiryType argument in RpcNsProfileEltInqBegin, RpcNsProfileEltInqNext returns all the components (interface identification, member name, priority, annotation string) of a profile element.

An application can view all the selected profile entries by repeatedly calling the RpcNsProfileEltInqNext routine. When all the elements have been viewed, this routine returns a RPC_S_NO_MORE_ELEMENTS status code. The returned elements are unordered.

On each call to RpcNsProfileEltInqNext that returns a profile element, the RPC run-time library allocates memory for the returned member name and annotation string. The application is responsible for calling the RpcStringFree routine for each returned member name and annotation string.

After viewing the profile’s elements, the application must call the RpcNsProfileEltInqDone routine to release the inquiry context.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
RPC_S_NO_MORE_ELEMENTS	No more elements
See Also

RpcNsProfileEltInqBegin, RpcNsProfileEltInqDone, RpcStringFree


RpcNsProfileEltRemove

The RpcNsProfileEltRemove function removes an element from a profile.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcNsProfileEltRemove(

unsigned long  ProfileNameSyntax,
unsigned char *  ProfileName,
RPC_IF_ID *  IfId,
unsigned long  MemberNameSyntax,
unsigned char *  MemberName
);
Parameters

ProfileNameSyntax

Specifies an integer value that indicates the syntax of the next argument, ProfileName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

ProfileName

Points to the name of the profile from which to remove an element.

IfId

Points to the interface identification of the profile element to be removed.

Specify a null value to remove the default profile member.

MemberNameSyntax

Specifies an integer value that indicates the syntax of the next argument, MemberName.

To use the syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

MemberName

Points to the name-service entry name in the profile element to remove.

Remarks

Note  This DCE function is not supported by the Microsoft Locator.

The RpcNsProfileEltRemove routine removes a profile element from the profile attribute in the ProfileName entry. The RpcNsProfileEltRemove routine requires an exact match of the MemberName and IfId arguments in order to remove a profile element.

The entry (MemberName) included as a member in the profile element is not deleted.

Use RpcNsProfileEltRemove cautiously: removing elements from a profile can have the unwanted effect of breaking a hierarchy of profiles.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_ENTRY_NOT_FOUND	Name-service entry not found
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcNsProfileDelete, RpcNsProfileEltAdd


RpcObjectInqType

The RpcObjectInqType function returns the type of an object.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcObjectInqType(

UUID *  ObjUuid,
UUID *  TypeUuid
);
Parameters

ObjUuid

Points to the object UUID whose associated type UUID is returned.

TypeUuid

Returns a pointer to the type UUID of the ObjUuid argument.

Specify an argument value of NULL to prevent the return of a type UUID. In this way, an application can determine (from the returned status) whether ObjUuid is registered without specifying an output type UUID variable.

Remarks

A server application calls the RpcObjectInqType routine to obtain the type UUID of an object.

If the object was registered with the RPC run-time library using the RpcObjectSetType routine, the registered type is returned.

Optionally, an application can privately maintain an object/type registration. In this case, if the application has provided an object inquiry function (see RpcObjectSetInqFn), the RPC run-time library uses that function to determine an object’s type.

The RpcObjectInqType routine obtains the returned type UUID as described in the following table:

Object UUID  registered	Inquiry function  registered	Return  value
Yes (RpcObjectSetType)	Ignored	The object’s registered type UUID
No	Yes (RpcObjectSetInqFn)	The type UUID returned from the inquiry function
No	No	The nil UUID
Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_OBJECT_NOT_FOUND	Object not found
See Also

RpcObjectSetInqFn, RpcObjectSetType


RpcObjectSetInqFn

The RpcObjectSetInqFn function registers an object-inquiry function. A null value turns off a previously registered object-inquiry function.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcObjectSetInqFn(

RPC_OBJECT_INQ_FN  InquiryFn
);
Parameters

InquiryFn

Specifies an object-type inquiry function. When an application calls the RpcObjectInqType routine and the RPC run-time library finds that the specified object is not registered, the run-time library automatically calls RpcObjectSetInqFn to determine the object’s type.

The following C-language definition for RPC_OBJECT_INQ_FN illustrates the prototype for the object-inquiry function:

typedef void ( *   RPC_OBJECT_INQ_FN) (

     UUID  *       ObjectUuid,

     UUID  *       TypeUuid,

     RPC_STATUS *  Status);

The TypeUuid and Status values are returned as the output from the RpcObjectInqType routine.

Remarks

A server application calls the RpcObjectSetInqFn routine to specify a function to determine an object’s type. If an application privately maintains an object/type registration, the specified inquiry function returns the type UUID of an object.

The RPC run-time library automatically calls the inquiry function when the application calls RpcObjectInqType and the object of interest was not previously registered with the RpcObjectSetType routine.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcObjectInqType, RpcObjectSetType


RpcObjectSetType

The RpcObjectSetType function assigns the type of an object.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcObjectSetType(

UUID *  ObjUuid,
UUID *  TypeUuid
);
Parameters

ObjUuid

Points to an object UUID to associate with the type UUID in the TypeUuid argument.

TypeUuid

Points to the type UUID of the ObjUuid argument.

Specify an argument value of NULL or a nil UUID to reset the object type to the default association of object UUID/nil type UUID.

Remarks

A server application calls the RpcObjectSetType routine to assign a type UUID to an object UUID.

By default, the RPC run-time library automatically assigns all object UUIDs with the nil type UUID. A server application that contains one implementation of an interface (one manager entry-point vector [EPV]) does not need to call RpcObjectSetType provided the server registered the interface with the nil type UUID (see RpcServerRegisterIf).

A server application that contains multiple implementations of an interface (multiple manager EPVs — that is, multiple type UUIDs) calls RpcObjectSetType once for each different object UUID/non-nil type UUID association the server supports. Associating each object with a type UUID tells the RPC run-time library which manager EPV (interface implementation) to use when the server receives a remote procecure call for a non-nil object UUID.

The RPC run-time library allows an application to set the type for an unlimited number of objects.

To remove the association between an object UUID and its type UUID (established by calling RpcObjectSetType), a server calls RpcObjectSetType again specifying a null value or a nil UUID for the TypeUuid argument. This resets the object UUID/type UUID association to the default association of object UUID/nil type UUID.

A server cannot assign a type to the nil object UUID. The RPC run-time library automatically assigns the nil object UUID a nil type UUID.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_OBJECT	Invalid object
RPC_S_ALREADY_REGISTERED	Object already registered
See Also

RpcServerRegisterIf


RpcProtseqVectorFree

The RpcProtseqVectorFree function frees the protocol sequences contained in the vector and the vector itself.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcProtseqVectorFree(

RPC_PROTSEQ_VECTOR * *  ProtSeqVector
);
Parameters

ProtSeqVector

Points to a pointer to a vector of protocol sequences. On return, the pointer is set to NULL.

Note  RpcProtseqVectorFree is available for server applications, not client applications, using Microsoft RPC.

Remarks

A server calls the RpcProtseqVectorFree routine to release the memory used to store a vector of protocol sequences and the individual protocol sequences. RpcProtseqVectorFree sets the ProtSeqVector argument to a null value.

A server obtains a vector of protocol sequences by calling the RpcNetworkInqProtseqs routine.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcNetworkInqProtseqs


RpcRaiseException

Use the RpcRaiseException function to raise an exception. The RpcRaiseException function does not return to the caller.

void RPC_ENTRY RpcRaiseException (

RPC_STATUS  Exception
);
Parameters

Exception

Specifies the exception code for the exception. The following exception codes are defined:

Exception code	Description
RPC_S_ACCESS_DENIED	Access denied
RPC_S_ADDRESS_ERROR	An addressing error occurred in the RPC server
RPC_S_ALREADY_LISTENING	Server already listening
RPC_S_ALREADY_REGISTERED	Object already registered
RPC_S_BINDING_HAS_NO_AUTH	Binding has no authentication
RPC_S_BINDING_INCOMPLETE	The binding handle is a required parameter.
RPC_S_BUFFER_TOO_SMALL	Insufficient buffer
RPC_S_CALL_CANCELLED	The remote procedure call exceeded the cancel timeout and was canceled.
RPC_S_CALL_FAILED	Call failed
RPC_S_CALL_FAILED_DNE	Call failed and did not execute
RPC_S_CALL_IN_PROGRESS	Call already in progress for this thread
RPC_S_CANNOT_SUPPORT	Operation is not supported
RPC_S_CANT_CREATE_ENDPOINT	Cannot create endpoint
RPC_S_COMM_FAILURE	Unable to communicate with the server
RPC_S_DUPLICATE_ENDPOINT	Endpoint already exists
RPC_S_ENTRY_ALREADY_EXISTS	Name-service entry already exists
RPC_S_ENTRY_NOT_FOUND	Name-service entry not found
RPC_S_FP_DIV_ZERO	A floating-point operation in the server caused a division by zero
RPC_S_FP_OVERFLOW	Floating-point overflow has occurred in the RPC server
RPC_S_FP_UNDERFLOW	Floating-point underflow has occurred in the server
RPC_S_GROUP_MEMBER_NOT_FOUND	Group member not found
RPC_S_INCOMPLETE_NAME	Incomplete name
RPC_S_INTERFACE_NOT_FOUND	Interface not found
RPC_S_INTERNAL_ERROR	Internal error
RPC_S_INVALID_ARG	Invalid argument
RPC_S_INVALID_AUTH_IDENTITY	Invalid authentication
RPC_S_INVALID_BINDING	Invalid binding handle
RPC_S_INVALID_BOUND	Invalid bound
RPC_S_INVALID_ENDPOINT_FORMAT	Invalid endpoint format
RPC_S_INVALID_INQUIRY_CONTEXT	Invalid inquiry context
RPC_S_INVALID_INQUIRY_TYPE	Invalid inquiry type
RPC_S_INVALID_LEVEL	Invalid parameter
RPC_S_INVALID_NAF_IF	Invalid network-address family ID
RPC_S_INVALID_NAME_SYNTAX	Invalid name syntax
RPC_S_INVALID_NET_ADDR	Invalid network address
RPC_S_INVALID_NETWORK_OPTIONS	Invalid network options
RPC_S_INVALID_OBJECT	Invalid object
RPC_S_INVALID_RPC_PROTSEQ	Invalid protocol sequence
RPC_S_INVALID_SECURIT_DESC	Invalid security descriptor
RPC_S_INVALID_STRING_BINDING	Invalid string binding
RPC_S_INVALID_STRING_UUID	Invalid string UUID
RPC_S_INVALID_TAG	Invalid tag
RPC_S_INVALID_TIMEOUT	Invalid timeout value
RPC_S_INVALID_VERS_OPTION	Invalid version option
RPC_S_MAX_CALLS_TOO_SMALL	Maximum-calls value too small
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
RPC_S_NO_BINDINGS	No bindings
RPC_S_NO_CALL_ACTIVE	No remote procedure active in this thread
RPC_S_NO_CONTEXT_AVAILABLE	No security context is available to perform impersonation
RPC_S_NO_ENDPOINT_FOUND	No endpoint found
RPC_S_NO_ENTRY_NAME	No entry name for binding
RPC_S_NO_ENV_SETUP	No environment variable is set up
RPC_S_NO_INTERFACES	No interfaces are registered
RPC_S_NO_INTERFACES_EXPORTED	No interfaces have been exported
RPC_S_NO_MORE_BINDINGS	No more bindings
RPC_NO_MORE_ELEMENTS	There are no more elements.
RPC_S_NO_MORE_MEMBERS	No more members
RPC_S_NO_NS_PRIVILEGE	No privilege for name-service operation
RPC_S_NO_PRINC_NAME	No principal name is registered
RPC_S_NO_PROTSEQS	No supported protocol sequences
RPC_S_NO_PROTSEQS_REGISTERED	No protocol sequences registered
RPC_S_NOT_ALL_OBJS_UNEXPORTED	Not all objects unexported
RPC_S_NOT_CANCELLED	The thread is not canceled
RPC_S_NOT_LISTENING	Server not listening
RPC_S_NOT_RPC_ERROR	The status code requested is not valid
RPC_S_NOTHING_TO_EXPORT	Nothing to export
RPC_S_NOTHING_TO_UNEXPORT	Nothing to unexport
RPC_S_OBJECT_NOT_FOUND	Object not found
RPC_S_OK	Success
RPC_S_OUT_OF_MEMORY	Out of memory
RPC_S_OUT_OF_RESOURCES	Out of resources
RPC_S_OUT_OF_THREADS	Out of threads
RPC_S_PROCNUM_OUT_OF_RANGE	Procedure number is out of range
RPC_S_PROTOCOL_ERROR	An RPC protocol error occurred
RPC_S_PROTSEQ_NOT_FOUND	Protocol sequence not found
RPC_S_PROTSEQ_NOT_SUPPORTED	Protocol sequence not supported
RPC_S_SERVER_OUT_OF_MEMORY	Server out of memory
RPC_S_SERVER_TOO_BUSY	Server too busy
RPC_S_SERVER_UNAVAILABLE	The server is unavailable
RPC_S_STRING_TOO_LONG	String too long
RPC_S_TYPE_ALREADY_REGISTERED	Type UUID already registered
RPC_S_UNKNOWN_AUTHN_LEVEL	Unknown authentication level
RPC_S_UNKNOWN_AUTHN_SERVICE	Unknown authentication service
RPC_S_UNKNOWN_AUTHN_TYPE	Unknown authentication type
RPC_S_UNKNOWN_IF	Unknown interface
RPC_S_UNKNOWN_MGR_TYPE	Unknown manager type
RPC_S_UNSUPPORTED-TRANS_SYN	Transfer syntax is not supported by the server
RPC_S_UNSUPPORTED_NAME_SYNTAX	Unsupported name syntax
RPC_S_UNSUPPORTED_TYPE	Unsupported UUID type
RPC_S_UUID_LOCAL_ONLY	The UUID that is only valid for this computer has been allocated
RPC_S_UUID_NO_ADDRESS	No network address is available to use to construct a UUID
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation
RPC_S_ZERO_DIVIDE	Attempt to divide an integer by zero
RPC_X_BAD_STUB_DATA	The stub received bad data
RPC_X_BYTE_COUNT_TOO_SMALL	Byte count is too small
RPC_X_ENUM_VALUE_OUT_OF RANGE	The enumeration value is out of range
RPC_X_ENUM_VALUE_TOO_LARGE	The enumeration value is out of range
RPC_X_INVALID_BOUND	Specified bounds of an array inconsistent
RPC_X_INVALID_TAG	Discriminant value does not match any case values; no default case
RPC_X_NO_MEMORY	Insufficient memory available to set up necessary data structures
RPC_X_NO_MORE_ENTRIES	List of servers available for AutoHandle binding has been exhausted
RPC_X_NULL_REF_POINTER	A null reference pointer was passed to the stub
RPC_X_SS_BAD_ES_VERSION	The operation for the serializing handle is not valid
RPC_X_SS_CANNOT_GET_CALL_HANDLE	The stub is unable to get the remote procedure call handle
RPC_X_SS_CHAR_TRANS_OPEN_FAIL	File designated by DCERPCCHARTRANS cannot be opened
RPC_X_SS_CHAR_TRANS_SHORT_FILE	File containing character-translation table has fewer than 512 bytes
RPC_X_SS_CONTEXT_DAMAGED	Only raised on caller side; UUID in in, out context handle changed during call
RPC_X_SS_CONTEXT_MISMATCH	Only raised on callee side; UUID in in handle does not correspond to any known context
RPC_X_SS_HANDLES_MISMATCH	The binding handles passed to a remote procedure call don’t match
RPC_X_SS_IN_NULL_CONTEXT	Null context handle passed in in parameter position
RPC_X_SS_INVALID_BUFFER	The buffer is not valid for the operation.
RPC_X_SS_WRONG_ES_VERSION	The software version is incorrect
RPC_X_SS_WRONG_STUB_VERSION	The stub version is incorrect
Remarks

The RpcRaiseException routine raises an exception; this exception can then be handled by the exception handler.

Return Values

No value is returned.

See Also

RpcAbnormalTermination, RpcExcept, RpcFinally


RpcRevertToSelf

After calling RpcImpersonateClient and completing any tasks that require client impersonation, the server calls RpcRevertToSelf to end impersonation and to reestablish its own security identity.

This function is supported only by Windows NT.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcRevertToSelf (VOID);

Return Values

Value	Meaning
RPC_S_OK	Success.
RPC_S_NO_CALL_ACTIVE	Server does not have a client to impersonate.
RPC_S_INVALID_BINDING	Invalid binding handle.
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation.
RPC_S_CANNOT_SUPPORT	Not supported for this operating system, this transport, or this security subsystem.
Remarks

In a multithreaded application, if the call to RpcImpersonateClient is with a handle to another client thread, you must call RpcRevertToSelfEx with the handle to that thread to end impersonation.

See Also

RpcImpersonateClient, Impersonation


RpcRevertToSelfEx

After calling RpcImpersonateClient and completing any tasks that require client impersonation, the server calls RpcRevertToSelfEx to end impersonation and to reestablish its own security identity.

This function is supported only by Windows NT.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcRevertToSelf Ex(

RPC_BINDING_HANDLE  CallHandle
);
Parameters

CallHandle

Specifies a binding handle on the server that represents a binding to the client that the server impersonated. A value of zero specifies the client handle of the current thread; in this case the functionality of RpcRevertToSelfEx is identical to that of RpcRevertToSelf.

Return Values

Value	Meaning
RPC_S_OK	Success.
RPC_S_NO_CALL_ACTIVE	Server does not have a client to impersonate.
RPC_S_INVALID_BINDING	Invalid binding handle.
RPC_S_WRONG_KIND_OF_BINDING	Wrong kind of binding for operation.
RPC_S_CANNOT_SUPPORT	Not supported for this operating system, this transport, or this security subsystem.
Remarks

RpcRevertToSelfEx allows a server to impersonate a client and then revert in a multithreaded operation where the call to impersonate a client can come from a thread other than the thread originally dispatched from the RPC. For example, consider a primary thread, called thread1, which is dispatched from a remote client and which wakes up a worker thread, called thread2. If thread2 requires that the server impersonate the client, the server calls RpcImpersonateClient(THREAD1_CALL_HANDLE), performs the required task, calls RpcRevertToSelfEx(THREAD1_CALL_HANDLE) to end the impersonation, and then wakes up thread1.

See Also

RpcImpersonateClient, RpcRevertToSelf, Impersonation


RpcServerInqBindings

The RpcServerInqBindings function returns the binding handles over which remote procedure calls can be received.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerInqBindings(

RPC_BINDING_VECTOR * *  BindingVector
);
Parameters

BindingVector

Returns a pointer to a pointer to a vector of server binding handles.

Remarks

A server application calls the RpcServerInqBindings routine to obtain a vector of server binding handles. Binding handles are created by the RPC run-time library when a server application calls the following routines to register protocol sequences:

•	RpcServerUseAllProtseqs

•	RpcServerUseProtseq

•	RpcServerUseAllProtseqsIf

•	RpcServerUseProtseqIf

•	RpcServerUseProtseqEp

The returned binding vector can contain binding handles with dynamic endpoints or binding handles with well-known endpoints, depending on which of the above routines the server application called.

A server uses the vector of binding handles for exporting to the name service, for registering with the local endpoint-map database, or for conversion to string bindings.

If there are no binding handles (no registered protocol sequences), this routine returns the RPC_S_NO_BINDINGS status code and a BindingVector argument value of NULL.

The server is responsible for calling the RpcBindingVectorFree routine to release the memory used by the vector.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NO_BINDINGS	No bindings
See Also

RpcBindingVectorFree, RpcEpRegister, RpcEpRegisterNoReplace, RpcNsBindingExport, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf


RpcServerInqDefaultPrincName

The RpcServerInqDefaultPrincName function obtains the default principal name from the server.

This function is supported only by Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerInqDefaultPrincName(

unsigned long  AuthnSvc,
RPC_CHAR * *  PrincName,
);
Parameters

AuthnSvc

Specifies an authentication service to use when the server receives a request for a remote procedure call.

PrincName

Points to the principal name to use for the server when authenticating remote procedure calls using the service specified by the AuthnSvc argument. The content of the name and its syntax are defined by the authentication service in use.

Remarks

In a NetWare-only environment, server application calls the RpcServerInqDefaultPrincName routine to obtain the name of the NetWare server when authenticated RPC is required. The value obtained from this routine is then passed to RpcServerRegisterAuthInfo.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_OUT_OF_MEMORY	Insufficient memory to complete the operation
See Also

RpcBindingSetAuthInfo, RpcServerRegisterAuthInfo


RpcServerInqIf

The RpcServerInqIf function returns the manager entry-point vector (EPV) registered for an interface.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerInqIf(

RPC_IF_HANDLE  IfSpec,
UUID *  MgrTypeUuid,
RPC_MGR_EPV * *  MgrEpv
);
Parameters

IfSpec

Specifies the interface whose manager EPV is returned.

MgrTypeUuid

Points to the manager type UUID whose manager EPV is returned.

Specifying an argument value of NULL (or a nil UUID) signifies to return the manager EPV registered with IfSpec and the nil manager type UUID.

MgrEpv

Returns a pointer to the manager EPV for the requested interface.

Remarks

A server application calls the RpcServerInqIf routine to determine the manager EPV for a registered interface and manager type UUID.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_UNKNOWN_IF	Unknown interface
RPC_S_UNKNOWN_MGR_TYPE	Unknown manager type
See Also

RpcServerRegisterIf


RpcServerListen

The RpcServerListen function tells the RPC run-time library to listen for remote procedure calls. This function will not affect auto-listen interfaces. See RpcServerRegisterIfEx for more details.

This function is supported by both server platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerListen(

unsigned int  MinimumCallThreads,
unsigned int  MaxCalls,
unsigned int  DontWait
);
Parameters

MinimumCallThreads

Specifies the minimum number of call threads.

MaxCalls

Specifies the recommended maximum number of concurrent remote procedure calls the server can execute. To allow efficient performance, the RPC run-time libraries interpret the MaxCalls parameter as a suggested limit rather than as an absolute upper bound.

Use RPC_C_LISTEN_MAX_CALLS_DEFAULT to specify the default value.

DontWait

Specifies a flag controlling the return from RpcServerListen. A value of non-zero indicates that RpcServerListen should return immediately after completing function processing. A value of zero indicates that RpcServerListen should not return until RpcMgmtStopServerListening has been called and all remote calls have completed.

Remarks

Note  The Microsoft RPC implementation of RpcServerListen includes two new, additional parameters that do not appear in the DCE specification: DontWait and MinimumCallThreads.

A server calls the RpcServerListen routine when the server is ready to process remote procedure calls. RPC allows a server to simultaneously process multiple calls. The MaxCalls argument recommends the maximum number of concurrent remote procedure calls the server should execute.

The MaxCalls value should be equal to or greater than the largest MaxCalls value specified to the routines RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf, RpcServerUseAllProtseqs, and RpcServerUseAllProtseqsIf.

A server application is responsible for concurrency control between the server manager routines because each routine executes in a separate thread.

When the DontWait parameter has a value of zero, the RPC run-time library continues listening for remote procedure calls (that is, the routine does not return to the server application) until one of the following events occurs:

•	One of the server application’s manager routines calls the RpcMgmtStopServerListening routine.

•	A client calls a remote procedure provided by the server that directs the server to call RpcMgmtStopServerListening.

•	A client calls RpcMgmtStopServerListening with a binding handle to the server.

Once it receives a stop-listening request, the RPC run-time library stops accepting new remote procedure calls for all registered interfaces. Executing calls are allowed to complete, including callbacks.

After all calls complete, the RpcServerListen routine returns to the caller.

When the DontWait parameter has a non-zero value, RpcServerListen returns to the server immediately after processing all the instructions associated with the function. You can use the RpcMgmtWaitServerListen routine to perform the “wait” operation usually associated with RpcServerListen.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_ALREADY_LISTENING	Server already listening
RPC_S_NO_PROTSEQS_REGISTERED	No protocol sequences registered
RPC_S_MAX_CALLS_TOO_SMALL	Maximum calls value too small
See Also

RpcMgmtStopServerListening, RpcMgmtWaitServerListen, RpcServerRegisterIf, RpcServerRegisterIfEx, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf


RpcServerRegisterAuthInfo

The RpcServerRegisterAuthInfo function registers authentication information with the RPC run-time library.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerRegisterAuthInfo(

unsigned char *  ServerPrincName,
unsigned long  AuthnSvc,
RPC_AUTH_KEY_RETRIEVAL_FN  GetKeyFn,
void *  Arg
);
Parameters

ServerPrincName

Points to the principal name to use for the server when authenticating remote procedure calls using the service specified by the AuthnSvc argument. The content of the name and its syntax are defined by the authentication service in use.

AuthnSvc

Specifies an authentication service to use when the server receives a request for a remote procedure call.

GetKeyFn

Specifies the address of a server-application-provided routine that returns encryption keys.

Specify a NULL argument value to use the default method of encryption-key acquisition. In this case, the authentication service specifies the default behavior. Set this parameter to NULL when using the RPC_C_AUTHN_WINNT authentication service.

Authentication service	GetKeyFn	Arg	Run-time behavior
RPC_C_AUTHN_DCE _PRIVATE	NULL	Non-null	Uses default method of encryption-key acquisition from specified key table; specified argument is passed to default acquisition function
RPC_C_AUTHN_DCE _PRIVATE	Non-null	NULL	Uses specified encryption-key acquisition function to obtain keys from default key table
RPC_C_AUTHN_DCE _PRIVATE	Non-null	Non-null	Uses specified encryption-key acquisition function to obtain keys from specified key table; specified argument is passed to acquisition function
RPC_C_AUTHN_DEC _PUBLIC	Ignored	Ignored	Reserved for future use
RPC_C_AUTHN_WINNT	Ignored	Ignored	Does not support
The following C-language definition for RPC_AUTH_KEY_RETRIEVAL_FN illustrates the prototype for RpcServerRegisterAuthInfo:

typedef void (* RPC_AUTH_KEY_RETRIEVAL_FN)(

    void * arg, /* in */

    unsigned char * ServerPrincName, /* in */

    unsigned int key_ver, /* in */

    void * * key, /* out */

    unsigned int * status /* out */);

The RPC run-time library passes the ServerPrincName argument value from RpcServerRegisterAuthInfo as the ServerPrincName argument value to the GetKeyFn acquisition function.

The RPC run-time library automatically provides a value for the key version (KeyVer) argument. For a KeyVer argument value of zero, the acquisition function must return the most recent key available.

The retrieval function returns the authentication key in the Key argument.

If the acquisition function called from RpcServerRegisterAuthInfo returns a status other than RPC_S_OK, RpcServerRegisterAuthInfo fails and returns an error code to the server application.

If the acquisition function called by the RPC run-time library while authenticating a client’s remote procedure call request returns a status other than RPC_S_OK, the request fails and the RPC run-time library returns an error code to the client application.

Arg

Points to an argument to pass to the GetKeyFn routine, if specified.

Remarks

A server application calls the RpcServerRegisterAuthInfo routine to register an authentication service to use for authenticating remote procedure calls. A server calls this routine once for each authentication service and/or principal name the server wants to register.

The authentication service specified by a client application (using RpcBindingSetAuthInfo or RpcServerRegisterAuthInfo) must be one of the authentication services specified by the server application. Otherwise, the client’s remote procedure call fails and an RPC_S_UNKNOWN_AUTHN_SERVICE status code is returned.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_UNKNOWN_AUTHN_SERVICE	Unknown authentication service
See Also

RpcBindingSetAuthInfo


RpcServerRegisterIf

The RpcServerRegisterIf function registers an interface with the RPC run-time library.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerRegisterIf(

RPC_IF_HANDLE  IfSpec,
UUID *  MgrTypeUuid,
RPC_MGR_EPV *  MgrEpv
);
Parameters

IfSpec

Specifies a MIDL-generated data structure indicating the interface to register.

MgrTypeUuid

Points to a type UUID to associate with the MgrEpv argument. Specifying a null argument value (or a nil UUID) registers IfSpec with a nil type UUID.

MgrEpv

Specifies the manager routines’ entry-point vector (EPV). To use the MIDL-generated default EPV, specify a null value.

Remarks

A server can register an unlimited number of interfaces with the RPC run-time library. Registration makes an interface available to clients using a binding handle to the server.

To register an interface, the server application code calls the RpcServerRegisterIf routine. For each implementation of an interface offered by a server, it must register a separate manager EPV.

To register an interface, the server provides the following information:

•	Interface specification

The interface specification is a data structure that the MIDL compiler generates. The server specifies the interface using the IfSpec argument.

•	Manager type UUID and manager EPV

The manager type UUID and the manager EPV determine which manager routine executes when a server receives a remote procedure call request from a client.

The server specifies the manager type UUID and EPV using the MgrTypeUuid and MgrEpv arguments. Note that when specifying a non-nil manager type UUID, the server must also call the RpcObjectSetType routine to register objects of this non-nil type.

If your server application needs to register an auto-listen interface or use a callback function for authentication purposes, use RpcServerRegisterIfEx.

See Also

Registering the Interface, RpcBindingFromStringBinding, RpcBindingSetObject, RpcNsBindingExport, RpcNsBindingImportBegin, RpcNsBindingLookupBegin, RpcObjectSetType, RpcServerUnregisterIf


RpcServerRegisterIfEx

The RpcServerRegisterIfEx function registers an interface with the RPC run-time library.

This function is supported by both server platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerRegisterIfEx(

RPC_IF_HANDLE  IfSpec,
UUID *  MgrTypeUuid,
RPC_MGR_EPV *  MgrEpv,
unsigned int Flags,
unsigned int MaxCalls,
RPC_IF_CALLBACK_FN* IfCallback
);
Parameters

IfSpec

Specifies a MIDL-generated data structure indicating the interface to register.

MgrTypeUuid

Points to a type UUID to associate with the MgrEpv argument. Specifying a null argument value (or a nil UUID) registers IfSpec with a nil type UUID.

MgrEpv

Specifies the manager routines’ entry-point vector (EPV). To use the MIDL-generated default EPV, specify a null value.

Flags

The following flags are defined:

Value	Meaning
0	standard interface semantics
RPC_IF_AUTOLISTEN	This is an auto-listen interface. See Remarks for more details.
RPC_IF_OLE	Reserved for OLE. Do not use this flag.
MaxCalls

Specifies the maximum number of concurrent remote procedure call requests the server can accept. The RPC run-time library guarantees that the server can accept at least this number of concurrent call requests. The actual number can be greater and can vary for each protocol sequence. Use RPC_C_PROTSEQ_MAX_REQS_DEFAULT to specify the default value.

IfCallback

Specifies a security callback function, or NULL for no callback. Each registered interface can have a different callback function. See Remarks for more details.

Remarks

The parameters and effects of RpcServerRegisterIfEx subsume those of RpcServerRegisterIf. The difference is the ability to register an auto-listen interface and to specify a security callback function.

The server application code calls the RpcServerRegisterIfEx routine to register an interface. To register an interface, the server provides the following information:

•	Interface specification.

The interface specification is a data structure that the MIDL compiler generates.

•	Manager type UUID and manager EPV

The manager type UUID and the manager EPV determine which manager routine executes when a server receives a remote procedure call request from a client. For each implementation of an interface offered by a server, it must register a separate manager EPV.

Note that when specifying a non-nil manager type UUID, the server must also call the RpcObjectSetType routine to register objects of this non-nil type.

Specifying the RPC_IF_AUTOLISTEN flags marks the interface as an auto-listen interface. The runtime begins listening for calls as soon as the interface is registered, and stops listening when the interface is unregistered. A call to RpcServerUnregisterIf for this interface will wait for the completion of all pending calls on this interface. Calls to RpcServerListen and RpcServerStopServerListening will not affect the interface, nor will a call to RpcServerUnregisterIf with IfSpec == NULL. This allows a DLL to register and unregister RPC interfaces without changing the main application’s RPC state.

Specifying a security callback function allows the server application to restrict access to its interfaces on a per-client basis. Remember that, by default, security is optional; the server runtime will dispatch unsecured calls even if the server has called RpcServerRegisterAuthInfo. If the server wants to accept only authenticated clients, each server stub must call RpcServerInqAuthClient to retrieve the security level, or attempt to impersonate the client with RpcImpersonateClient.

When a server app specifies a security callback function for its interface(s), the RPC runtime automatically rejects unauthenticated calls to that interface. In addition, the runtime records the interfaces that each client has used. When a client makes an RPC to a heretofore unused interface, the RPC runtime will call the interface’s security callback function.

The signature for the callback function is as follows:

typedef RPC_STATUS

RPC_IF_CALLBACK_FN (

    IN RPC_IF_ID * Interface,

    IN void * Context

    ) ;

Interface contains the UUID and version of the interface in question.

Context is a server binding handle representing the client. The callback function may pass this handle to RpcImpersonateClient or RpcBindingServerToClient to gain information about the client.

The callback function should return RPC_S_OK if the client is allowed to call methods in this interface. Any other return code will cause the client to receive the exception RPC_S_ACCESS_DENIED.

In some cases the RPC runtime may call the security callback function more than once per client per interface. Be sure your callback function can handle this possibility.

See Also

Registering the Interface, RpcBindingFromStringBinding, RpcBindingSetObject, RpcNsBindingExport, RpcNsBindingImportBegin, RpcNsBindingLookupBegin, RpcObjectSetType, RpcServerRegisterIf, RpcServerUnregisterIf


RpcServerUnregisterIf

The RpcServerUnregisterIf function unregisters an interface from the RPC run-time library.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerUnregisterIf(

RPC_IF_HANDLE  IfSpec,
UUID *  MgrTypeUuid,
unsigned int  WaitForCallsToComplete
);
Parameters

IfSpec

Specifies the interface to unregister.

Specify a null value to unregister all interfaces previously registered with the type UUID value specified in the MgrTypeUuid argument.

MgrTypeUuid

Points to the type UUID of the manager entry-point vector (EPV) to unregister. The value of MgrTypeUuid should be the same value as was provided in a call to the RpcServerRegisterIf or RpcServerRegisterIfEx routine.

Specify a null value to unregister the interface specified in the IfSpec argument for all previously registered type UUIDs.

Specify a nil UUID to unregister the MIDL-generated default manager EPV. In this case, all manager EPVs registered with a non-nil type UUID remain registered.

WaitForCallsToComplete

Specifies a flag that indicates whether to unregister immediately or to wait until all current calls are complete.

Specify a value of zero to disregard calls in progress and unregister immediately. Specify any non-zero value to wait until all active calls complete.

Remarks

A server calls the RpcServerUnregisterIf routine to remove the association between an interface and a manager EPV.

Specify the manager EPV to remove in the MgrTypeUuid argument by providing the type UUID value that was specified in a call to the RpcServerRegisterIf routine. Once unregistered, an interface is no longer available to client applications.

When an interface is unregistered, the RPC run-time library stops accepting new calls for that interface. Executing calls on the interface are allowed to complete, including callbacks.

The following table summarizes the behavior of RpcServerUnregisterIf:

IfSpec	MgrTypeUuid	Behavior
Non-null	Non-null	Unregisters the manager EPV associated with the specified arguments.
Non-null	NULL	Unregisters all manager EPVs associated with the IfSpec argument.
NULL	Non-null	Unregisters all manager EPVs associated with the MgrTypeUuid argument.
NULL	NULL	Unregisters all manager EPVs. This call has the effect of preventing the server from receiving any new remote procedure calls because all the manager EPVs for all interfaces have been unregistered.
Note  If IfSpec is NULL, this function will leave auto-listen interfaces registered. Auto-listen interfaces must be individually unregistered. See RpcServerRegisterIfEx for more details.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_UNKNOWN_MGR_TYPE	Unknown manager type
RPC_S_UNKNOWN_IF	Unknown interface
See Also

RpcServerRegisterIf, RpcServerRegisterIfEx


RpcServerUseAllProtseqs

The RpcServerUseAllProtseqs function tells the RPC run-time library to use all supported protocol sequences for receiving remote procedure calls.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerUseAllProtseqs(

unsigned int  MaxCalls,
void *  SecurityDescriptor
);
Parameters

MaxCalls

Specifies the maximum number of concurrent remote procedure call requests the server can accept.

The RPC run-time library guarantees that the server can accept at least this number of concurrent call requests. The actual number can be greater and can vary for each protocol sequence.

Use RPC_C_PROTSEQ_MAX_REQS_DEFAULT to specify the default value.

SecurityDescriptor

Points to an optional parameter provided for the Microsoft Windows NT security subsystem.Note that this parameter does not appear in the DCE specification for this API.

Remarks

A server application calls the RpcServerUseAllProtseqs routine to register all of the supported protocol sequences with the RPC run-time library. To receive remote procedure calls, a server must register at least one protocol sequence with the RPC run-time library.

For each protocol sequence registered by a server, the RPC run-time library creates one or more binding handles through which the server receives remote procedure call requests. The RPC run-time library creates different binding handles for each protocol sequence. Each binding handle contains an endpoint dynamically generated by the RPC run-time library or the operating system.

The MaxCalls argument allows the server to specify the maximum number of concurrent remote procedure call requests the server wants to be able to handle.

See Server Application RPC API Calls for a description of the routines that a server will typically call after registering protocol sequences.

To selectively register protocol sequences, a server calls the RpcServerUseProtseq, RpcServerUseProtseqIf, or RpcServerUseProtseqEp routine.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NO_PROTSEQS	No supported protocol sequences
RPC_S_OUT_OF_MEMORY	Insufficient memory available
RPC_S_INVALID_SECURITY_DESC	Security descriptor invalid
See Also

RpcBindingToStringBinding, RpcBindingVectorFree, RpcEpRegister, RpcEpRegisterNoReplace, RpcNsBindingExport, RpcServerInqBindings, RpcServerListen, RpcServerRegisterIf, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf


RpcServerUseAllProtseqsEx

The RpcServerUseAllProtseqsEx function tells the RPC run-time library to use all supported protocol sequences for receiving remote procedure calls. For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

This function is supported only on Windows NT 4.0.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerUseAllProtseqsEx(

unsigned int  MaxCalls,
void *  SecurityDescriptor,
PRPC_POLICY Policy
);
Parameters

MaxCalls

Specifies the maximum number of concurrent remote procedure call requests the server can accept.

The RPC run-time library guarantees that the server can accept at least this number of concurrent call requests. The actual number can be greater and can vary for each protocol sequence. Use RPC_C_PROTSEQ_MAX_REQS_DEFAULT to specify the default value.

SecurityDescriptor

Points to an optional parameter provided for the Microsoft Windows NT security subsystem.

Policy

Points to the RPC_POLICY structure, which allows you to override the default policies for dynamic port allocation and binding to network interface cards (NICs) on multihomed machines.

Remarks

The parameters and effects of RpcServerUseAllProtseqsEx subsume those of RpcServerUseAllProtseqs. The difference is the Policy parameter, which allows you to restrict port allocation for dynamic ports and allows multihomed machines to selectively bind to specified NICs.

Setting the NICFlags field of the RPC_POLICY structure to zero makes this extended API functionally equivalent to the original RpcServerUseAllProtseqs, and the server will bind to NICs based on the settings in the system registry. For information on how the registry settings define the available Internet and intranet ports, see Configuring the Windows NT Registry for Port Allocations and Selective Binding.

Note  The flag settings in the Policy field are effective only when the ncacn_ip_tcp protocol sequence is in use. For all other protocol sequences, the RPC run time ignores these values.

A server application calls the RpcServerUseAllProtseqsEx routine to register all of the supported protocol sequences with the RPC run-time library. To receive remote procedure calls, a server must register at least one protocol sequence with the RPC run-time library.

For each protocol sequence registered by a server, the RPC run-time library creates one or more binding handles through which the server receives remote procedure call requests. The RPC run-time library creates different binding handles for each protocol sequence. Each binding handle contains an endpoint dynamically generated by the RPC run-time library or the operating system.

The MaxCalls argument allows the server to specify the maximum number of concurrent remote procedure call requests the server wants to handle.

To selectively register protocol sequences, a server calls the RpcServerUseProtseqEx, RpcServerUseProtseqIfEx, or RpcServerUseProtseqEpEx routine.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NO_PROTSEQS	No supported protocol sequences
RPC_S_OUT_OF_MEMORY	Insufficient memory available
RPC_S_INVALID_SECURITY_DESC	Security descriptor is invalid
See Server Application RPC API Calls for a description of the routines that a server will typically call after registering protocol sequences.

See Also

Configuring the Windows NT Registry for Port Allocations and Selective Binding, RpcServerUseAllProtseqsIfEx, RpcServerUseProtseqEx, RpcServerUseProtseqEpEx, RpcServerUseProtseqIfEx


RpcServerUseAllProtseqsIf

The RpcServerUseAllProtseqsIf function tells the RPC run-time library to use all the specified protocol sequences and endpoints in the interface specification for receiving remote procedure calls.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerUseAllProtseqsIf(

unsigned int  MaxCalls,
RPC_IF_HANDLE  IfSpec,
void *  SecurityDescriptor
);
Parameters

MaxCalls

Specifies the maximum number of concurrent remote procedure call requests the server can accept.

The RPC run-time library guarantees that the server can accept at least this number of concurrent call requests. The actual number can be greater and can vary for each protocol sequence.

Use RPC_C_PROTSEQ_MAX_REQS_DEFAULT to specify the default value.

IfSpec

Specifies the interface containing the protocol sequences and corresponding endpoint information to use in creating binding handles.

SecurityDescriptor

Points to an optional parameter provided for the Microsoft Windows NT security subsystem. Note that this parameter does not appear in the DCE specification for this API.

Remarks

A server application calls the RpcServerUseAllProtseqsIf routine to register with the RPC run-time library all the protocol sequences and associated endpoint-address information provided in the IDL file.

To receive remote procedure call requests, a server must register at least one protocol sequence with the RPC run-time library.

For each protocol sequence registered by a server, the RPC run-time library creates one or more binding handles through which the server receives remote procedure call requests. The RPC run-time library creates different binding handles for each protocol sequence.

The MaxCalls argument allows the server to specify the maximum number of concurrent remote procedure call requests the server wants to handle.

See Server Application RPC API Calls for a description of the routines that a server will typically call after registering protocol sequences.

To register selected protocol sequences specified in the IDL file, a server calls the RpcServerUseProtseqIf routine.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NO_PROTSEQS	No supported protocol sequences
RPC_S_INVALID_ENDPOINT_FORMAT	Invalid endpoint format
RPC_S_OUT_OF_MEMORY	Out of memory
RPC_S_DUPLICATE_ENDPOINT	Endpoint is duplicate
RPC_S_INVALID_SECURITY_DESC	Security descriptor invalid
RPC_S_INVALID_RPC_PROTSEQ	RPC protocol sequence invalid
See Also

RpcBindingVectorFree, RpcEpRegister, RpcEpRegisterNoReplace, RpcNsBindingExport, RpcServerInqBindings, RpcServerListen, RpcServerRegisterIfEx, RpcServerRegisterIf, RpcServerUseAllProtseqs, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf


RpcServerUseAllProtseqsIfEx

The RpcServerUseAllProtseqsIfEx function tells the RPC run-time library to use all the specified protocol sequences and endpoints in the interface specification for receiving remote procedure calls. For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

This function is supported only on Windows NT 4.0.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerUseAllProtseqsIfEx(

unsigned int  MaxCalls,
RPC_IF_HANDLE  IfSpec,
void *  SecurityDescriptor,
PRPC_POLICY Policy
);
Parameters

MaxCalls

Specifies the maximum number of concurrent remote procedure call requests the server can accept.

The RPC run-time library guarantees that the server can accept at least this number of concurrent call requests. The actual number can be greater and can vary for each protocol sequence. Use RPC_C_PROTSEQ_MAX_REQS_DEFAULT to specify the default value.

IfSpec

Specifies the interface containing the protocol sequences and corresponding endpoint information to use in creating binding handles.

SecurityDescriptor

Points to an optional parameter provided for the Microsoft Windows NT security subsystem.

Policy

Points to the RPC_POLICY structure, which contains flags to restrict port allocation for dynamic ports and which allow multihomed machines to selectively bind to network interface cards.

Remarks

The parameters and effects of RpcServerUseAllProtseqsIfEx subsume those of RpcServerUseAllProtseqsIf. The difference is the Policy field, which allows you to restrict port allocation for dynamic ports and allows multihomed machines to selectively bind to network interface cards.

Setting the NICFlags field of the RPC_POLICY structure to zero makes this extended function functionally equivalent to the original RpcServerUseAllProtseqsIf, and the server will bind to NICs based on the settings in the system registry. For information on how the registry settings define the available Internet and intranet ports, see Configuring the Windows NT Registry for Port Allocations and Selective Binding.

Note  The flag settings in the Policy field are effective only when the ncacn_ip_tcp protocol sequence is in use. For all other protocol sequences, the RPC run time ignores these values.

A server application calls the RpcServerUseAllProtseqsIfEx routine to register with the RPC run-time library all the protocol sequences and associated endpoint-address information provided in the IDL file.

To receive remote procedure call requests, a server must register at least one protocol sequence with the RPC run-time library.

For each protocol sequence registered by a server, the RPC run-time library creates one or more binding handles through which the server receives remote procedure call requests. The RPC run-time library creates different binding handles for each protocol sequence.

The MaxCalls argument allows the server to specify the maximum number of concurrent remote procedure call requests the server wants to handle.

To register selected protocol sequences specified in the IDL file, a server calls the RpcServerUseProtseqIfEx routine.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_NO_PROTSEQS	No supported protocol sequences
RPC_S_INVALID_ENDPOINT_FORMAT	Invalid endpoint format
RPC_S_OUT_OF_MEMORY	Out of memory
RPC_S_DUPLICATE_ENDPOINT	Endpoint is a duplicate
RPC_S_INVALID_SECURITY_DESC	Security descriptor is invalid
RPC_S_INVALID_RPC_PROTSEQ	RPC protocol sequence is invalid
See Server Application RPC API Calls for a description of the routines that a server will typically call after registering protocol sequences.

See Also

Configuring the Windows NT Registry for Port Allocations and Selective Binding, RpcServerUseAllProtseqsEx, RpcServerUseProtseqEx, RpcServerUseProtseqEpEx, RpcServerUseProtseqIfEx


RpcServerUseProtseq

The RpcServerUseProtseq function tells the RPC run-time library to use the specified protocol sequence for receiving remote procedure calls.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerUseProtseq(

unsigned char *  ProtSeq,
unsigned int  MaxCalls,
void *  SecurityDescriptor
);
Parameters

ProtSeq

Points to a string identifier of the protocol sequence to register with the RPC run-time library.

MaxCalls

Specifies the maximum number of concurrent remote procedure call requests the server wants to handle.

The RPC run-time library guarantees that the server can accept at least this number of concurrent call requests. The actual number can be greater, depending on the selected protocol sequence.

Use RPC_C_PROTSEQ_MAX_REQS_DEFAULT to specify the default value.

SecurityDescriptor

Points to an optional parameter provided for the Microsoft Windows NT security subsystem. Note that this parameter does not appear in the DCE specification for this API.

Remarks

A server application calls the RpcServerUseProtseq routine to register one protocol sequence with the RPC run-time library. To receive remote procedure call requests, a server must register at least one protocol sequence with the RPC run-time library. A server application can call RpcServerUseProtseq multiple times to register additional protocol sequences.

For each protocol sequence registered by a server, the RPC run-time library creates one or more binding handles through which the server receives remote procedure call requests. The RPC run-time library creates different binding handles for each protocol sequence. Each binding handle contains an endpoint dynamically generated by the RPC run-time library.

The MaxCalls argument allows the server to specify the maximum number of concurrent remote procedure call requests the server wants to handle.

See Server Application RPC API Calls for a description of the routines that a server will typically call after registering protocol sequences.

To register all protocol sequences, a server calls the RpcServerUseAllProtseqs routine.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_PROTSEQ_NOT_SUPPORTED	Protocol sequence not supported on this host
RPC_S_INVALID_RPC_PROTSEQ	Invalid protocol sequence
RPC_S_OUT_OF_MEMORY	Out of memory
RPC_S_INVALID_SECURITY_DESC	Security descriptor invalid
See Also

RpcBindingVectorFree, RpcEpRegister, RpcEpRegisterNoReplace, RpcNetworkIsProtseqValid, RpcNsBindingExport, RpcServerInqBindings, RpcServerListen, RpcServerRegisterIfEx, RpcServerRegisterIf, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseqEp, RpcServerUseProtseqIf


RpcServerUseProtseqEx

The RpcServerUseProtseqEx function tells the RPC run-time library to use the specified protocol sequence for receiving remote procedure calls. For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

This function is supported only on Windows NT 4.0.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerUseProtseq(

unsigned char *  ProtSeq,
unsigned int  MaxCalls,
void *  SecurityDescriptor,
PRPC_POLICY Policy
);
Parameters

ProtSeq

Points to a string identifier of the protocol sequence to register with the RPC run-time library.

MaxCalls

Specifies the maximum number of concurrent remote procedure call requests the server wants to handle.

The RPC run-time library guarantees that the server can accept at least this number of concurrent call requests. The actual number can be greater, depending on the selected protocol sequence. Use RPC_C_PROTSEQ_MAX_REQS_DEFAULT to specify the default value.

SecurityDescriptor

Points to an optional parameter provided for the Microsoft Windows NT security subsystem.

Policy

Points to the RPC_POLICY structure, which contains flags to restrict port allocation for dynamic ports and which allow multihomed machines to selectively bind to network interface cards.

Remarks

The parameters and effects of RpcServerUseProtseqEx subsume those of RpcServerUseProtseq. The difference is the Policy field, which allows you to restrict port allocation for dynamic ports and allows multihomed machines to selectively bind to network interface cards.

Setting the NICFlags field of the RPC_POLICY structure to zero makes this extended function functionally equivalent to the original RpcServerUseProtseq, and the server will bind to NICs based on the settings in the system registry. For information on how the registry settings define the available Internet and intranet ports, see Configuring the Windows NT Registry for Port Allocations and Selective Binding.

Note  The flag settings in the Policy field are effective only when the ncacn_ip_tcp protocol sequence is in use. For all other protocol sequences, the RPC run time ignores these values.

A server application calls the RpcServerUseProtseqEx routine to register one protocol sequence with the RPC run-time library. To receive remote procedure call requests, a server must register at least one protocol sequence with the RPC run-time library. A server application can call RpcServerUseProtseqEx multiple times to register additional protocol sequences.

For each protocol sequence registered by a server, the RPC run-time library creates one or more binding handles through which the server receives remote procedure call requests. The RPC run-time library creates different binding handles for each protocol sequence. Each binding handle contains an endpoint dynamically generated by the RPC run-time library.

The MaxCalls argument allows the server to specify the maximum number of concurrent remote procedure call requests the server wants to handle.

To register all protocol sequences, a server calls the RpcServerUseAllProtseqsEx routine.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_PROTSEQ_NOT_SUPPORTED	Protocol sequence is not supported on this host
RPC_S_INVALID_RPC_PROTSEQ	Invalid protocol sequence
RPC_S_OUT_OF_MEMORY	Out of memory
RPC_S_INVALID_SECURITY_DESC	Security descriptor is invalid
See Server Application RPC API Calls for a description of the routines that a server will typically call after registering protocol sequences.

See Also

Configuring the Windows NT Registry for Port Allocations and Selective Binding, RpcServerUseAllProtseqsEx, RpcServerUseAllProtseqsIfEx, RpcServerUseProtseqEpEx, RpcServerUseProtseqIfEx


RpcServerUseProtseqEp

The RpcServerUseProtseqEp function tells the RPC run-time library to use the specified protocol sequence combined with the specified endpoint for receiving remote procedure calls.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerUseProtseqEp(

unsigned char *  Protseq,
unsigned int  MaxCalls,
unsigned char *  Endpoint,
void *  SecurityDescriptor
);
Parameters

Protseq

Points to a string identifier of the protocol sequence to register with the RPC run-time library.

MaxCalls

Specifies the maximum number of concurrent remote procedure call requests the server wants to handle.

The RPC run-time library guarantees that the server can accept at least this number of concurrent call requests. The actual number can be greater, depending on the selected protocol sequence.

Use RPC_C_PROTSEQ_MAX_REQS_DEFAULT to specify the default value.

Endpoint

Points to the endpoint-address information to use in creating a binding for the protocol sequence specified in the Protseq argument.

SecurityDescriptor

Points to an optional parameter provided for the Microsoft Windows NT security subsystem. Note that this parameter does not appear in the DCE specification for this API.

Remarks

A server application calls the RpcServerUseProtseqEp routine to register one protocol sequence with the RPC run-time library. With each protocol sequence registration, RpcServerUseProtseqEp includes the specified endpoint-address information.

To receive remote procedure call requests, a server must register at least one protocol sequence with the RPC run-time library. A server application can call this routine multiple times to register additional protocol sequences and endpoints.

For each protocol sequence registered by a server, the RPC run-time library creates one or more binding handles through which the server receives remote procedure call requests.

The MaxCalls argument allows the server to specify the maximum number of concurrent remote procedure call requests the server wants to be able to handle.

See Server Application RPC API Calls for a description of the routines that a server will typically call after registering protocol sequences.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_PROTSEQ_NOT_SUPPORTED	Protocol sequence not supported on this host
RPC_S_INVALID_RPC_PROTSEQ	Invalid protocol sequence
RPC_S_INVALID_ENDPOINT_FORMAT	Invalid endpoint format
RPC_S_OUT_OF_MEMORY	Out of memory
RPC_S_DUPLICATE_ENDPOINT	Endpoint is duplicate
RPC_S_INVALID_SECURITY_DESC	Security descriptor invalid
See Also

RpcBindingVectorFree, RpcEpRegister, RpcEpRegisterNoReplace, RpcNsBindingExport, RpcServerInqBindings, RpcServerListen, RpcServerRegisterIf, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqIf


RpcServerUseProtseqEpEx

The RpcServerUseProtseqEpEx function tells the RPC run-time library to use the specified protocol sequence combined with the specified endpoint for receiving remote procedure calls. For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

This function is supported only on Windows NT 4.0.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerUseProtseqEpEx(

unsigned char *  Protseq,
unsigned int  MaxCalls,
unsigned char *  Endpoint,
void *  SecurityDescriptor,
PRPC_POLICY Policy
);
Parameters

Protseq

Points to a string identifier of the protocol sequence to register with the RPC run-time library.

MaxCalls

Specifies the maximum number of concurrent remote procedure call requests the server wants to handle.

The RPC run-time library guarantees that the server can accept at least this number of concurrent call requests. The actual number can be greater, depending on the selected protocol sequence. Use RPC_C_PROTSEQ_MAX_REQS_DEFAULT to specify the default value.

Endpoint

Points to the endpoint-address information to use in creating a binding for the protocol sequence specified in the Protseq argument.

SecurityDescriptor

Points to an optional parameter provided for the Microsoft Windows NT security subsystem.

Policy

Points to the RPC_POLICY structure, which contains flags to restrict port allocation for dynamic ports and which allow multihomed machines to selectively bind to network interface cards.

Remarks

The parameters and effects of RpcServerUseProtseqEpEx subsume those of RpcServerUseProtseqEp. The difference is the Policy field, which allows you to restrict port allocation for dynamic ports and allows multihomed machines to selectively bind to network interface cards.

Setting the NICFlags field of the RPC_POLICY structure to zero makes this extended function functionally equivalent to the original RpcServerUseProtseqEp, and the server will bind to NICs based on the settings in the system registry. For information on how the registry settings define the available Internet and intranet ports, see Configuring the Windows NT Registry for Port Allocations and Selective Binding.

Note  The flag settings in the Policy field are effective only when the ncacn_ip_tcp protocol sequence is in use. For all other protocol sequences, the RPC run time ignores these values.

A server application calls the RpcServerUseProtseqEpEx routine to register one protocol sequence with the RPC run-time library. With each protocol sequence registration, RpcServerUseProtseqEpEx includes the specified endpoint-address information.

To receive remote procedure call requests, a server must register at least one protocol sequence with the RPC run-time library. A server application can call this routine multiple times to register additional protocol sequences and endpoints.

For each protocol sequence registered by a server, the RPC run-time library creates one or more binding handles through which the server receives remote procedure call requests.

The MaxCalls argument allows the server to specify the maximum number of concurrent remote procedure call requests the server wants to handle.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_PROTSEQ_NOT_SUPPORTED	Protocol sequence is not supported on this host
RPC_S_INVALID_RPC_PROTSEQ	Invalid protocol sequence
RPC_S_INVALID_ENDPOINT_FORMAT	Invalid endpoint format
RPC_S_OUT_OF_MEMORY	Out of memory
RPC_S_DUPLICATE_ENDPOINT	Endpoint is a duplicate
RPC_S_INVALID_SECURITY_DESC	Security descriptor is invalid
See Server Application RPC API Calls for a description of the routines that a server will typically call after registering protocol sequences.

See Also

Configuring the Windows NT Registry for Port Allocations and Selective Binding, RpcServerUseAllProtseqsEx, RpcServerUseAllProtseqsIfEx, RpcServerUseProtseqEx, RpcServerUseProtseqIfEx


RpcServerUseProtseqIf

The RpcServerUseProtseqIf function tells the RPC run-time library to use the specified protocol sequence combined with the endpoints in the interface specification for receiving remote procedure calls.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerUseProtseqIf(

unsigned char *  Protseq,
unsigned int  MaxCalls,
RPC_IF_HANDLE  IfSpec,
void *  SecurityDescriptor
);
Parameters

Protseq

Points to a string identifier of the protocol sequence to register with the RPC run-time library.

MaxCalls

Specifies the maximum number of concurrent remote procedure call requests the server wants to be able to handle.

The RPC run-time library guarantees that the server can accept at least this number of concurrent call requests. The actual number can be greater, depending on the selected protocol sequence.

Use RPC_C_PROTSEQ_MAX_REQS_DEFAULT to specify the default value.

IfSpec

Specifies the interface containing endpoint information to use in creating a binding for the protocol sequence specified in the Protseq argument.

SecurityDescriptor

Points to an optional parameter provided for the Microsoft Windows NT security subsystem.

Remarks

Note  The Microsoft RPC implementation of RpcServerUseProtseqIf includes a new, additional parameter, SecurityDescriptor, that does not appear in the DCE specification.

A server application calls the RpcServerUseProtseqIf routine to register one protocol sequence with the RPC run-time library. With each protocol-sequence registration, the routine includes the endpoint-address information provided in the IDL file.

To receive remote procedure call requests, a server must register at least one protocol sequence with the RPC run-time library. A server application can call this routine multiple times to register additional protocol sequences.

For each protocol sequence registered by a server, the RPC run-time library creates one or more binding handles through which the server receives remote procedure call requests.

The MaxCalls argument allows the server to specify the maximum number of concurrent remote procedure call requests the server wants to be able to handle.

See Server Application RPC API Calls for a description of the routines that a server will typically call after registering protocol sequences.

To register all protocol sequences from the IDL file, a server calls the RpcServerUseAllProtseqsIf routine.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_PROTSEQ_NOT_FOUND	The endpoint for this protocol sequence not specified in the IDL file
RPC_S_PROTSEQ_NOT_SUPPORTED	Protocol sequence not supported on this host
RPC_S_INVALID_RPC_PROTSEQ	Invalid protocol sequence
RPC_S_INVALID_ENDPOINT_FORMAT	Invalid endpoint format
RPC_S_OUT_OF_MEMORY	Out of memory
RPC_S_INVALID_SECURITY_DESC	Security descriptor invalid
See Also

RpcBindingVectorFree, RpcEpRegister, RpcEpRegisterNoReplace, RpcNsBindingExport, RpcServerInqBindings, RpcServerListen, RpcServerRegisterIf, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp


RpcServerUseProtseqIfEx

The RpcServerUseProtseqIfEx function tells the RPC run-time library to use the specified protocol sequence combined with the endpoints in the interface specification for receiving remote procedure calls. For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

This function is supported only on Windows NT 4.0.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerUseProtseqIfEx(

unsigned char *  Protseq,
unsigned int  MaxCalls,
RPC_IF_HANDLE  IfSpec,
void *  SecurityDescriptor,
PRPC_POLICY Policy
);
Parameters

Protseq

Points to a string identifier of the protocol sequence to register with the RPC run-time library.

MaxCalls

Specifies the maximum number of concurrent remote procedure call requests the server wants to handle.

The RPC run-time library guarantees that the server can accept at least this number of concurrent call requests. The actual number can be greater, depending on the selected protocol sequence.

Use RPC_C_PROTSEQ_MAX_REQS_DEFAULT to specify the default value.

IfSpec

Specifies the interface containing endpoint information to use in creating a binding for the protocol sequence specified in the Protseq argument.

SecurityDescriptor

Points to an optional parameter provided for the Microsoft Windows NT security subsystem.

Policy

Points to the RPC_POLICY structure, which contains flags to restrict port allocation for dynamic ports and that allow multi-homed machines to selectively bind to network interface cards.

Remarks

The parameters and effects of RpcServerUseProtseqsIfEx subsume those of RpcServerUseProtseqsIf. The difference is the Policy field, which allows you to restrict port allocation for dynamic ports and allows multi-homed machines to selectively bind to network interface cards.

Setting the NICFlags field of the RPC_POLICY structure to 0 makes this extended API functionally equivalent to the original RpcServerUseProtseqIf, and the server will bind to NICs based on the settings in the system registry. For information on how the registry settings define the available Internet and intranet ports, see Configuring the Windows NT Registry for Port Allocations and Selective Binding.

Note  The flag settings in the Policy field are effective only when the ncacn_ip_tcp protocol sequence is in use; for all other protocol sequences, the RPC runtime ignores these values.

A server application calls the RpcServerUseProtseqIfEx routine to register one protocol sequence with the RPC run-time library. With each protocol-sequence registration, the routine includes the endpoint-address information provided in the IDL file.

To receive remote procedure call requests, a server must register at least one protocol sequence with the RPC run-time library. A server application can call this routine multiple times to register additional protocol sequences.

For each protocol sequence registered by a server, the RPC run-time library creates one or more binding handles through which the server receives remote procedure call requests.

The MaxCalls argument allows the server to specify the maximum number of concurrent remote procedure call requests the server wants to handle.

To register all protocol sequences from the IDL file, a server calls the RpcServerUseAllProtseqsIfEx routine.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_PROTSEQ_NOT_FOUND	The endpoint for this protocol sequence is not specified in the IDL file
RPC_S_PROTSEQ_NOT_SUPPORTED	Protocol sequence is not supported on this host
RPC_S_INVALID_RPC_PROTSEQ	Invalid protocol sequence
RPC_S_INVALID_ENDPOINT_FORMAT	Invalid endpoint format
RPC_S_OUT_OF_MEMORY	Out of memory
RPC_S_INVALID_SECURITY_DESC	Security descriptor is invalid
See Server Application RPC API Calls for a description of the routines that a server will typically call after registering protocol sequences.

See Also

Configuring the Windows NT Registry for Port Allocations and Selective Binding RpcServerUseAllProtseqsEx, RpcServerUseAllProtseqsIfEx, RpcServerUseProtseqEx, RpcServerUseProtseqEpEx


RpcSmAllocate

The RpcSmAllocate function allocates memory within the RPC stub memory management function and returns a pointer to the allocated memory or NULL.

#include <rpc.h>

void * RPC_ENTRY RpcSmAllocate(

size_t Size,
RPC_STATUS* pStatus
);
Parameters

Size

Specifies the size of memory to allocate (in bytes).

pStatus

Specifies a pointer to the returned status.

Remarks

The RpcSmAllocate routine allows an application to allocate memory within the RPC stub memory management environment. Prior to calling RpcSmAllocate, the memory management environment must already be established. For memory management called within the stub, the server stub itself may establish the necessary environment. See RpcSmEnableAllocate for more information. When using RpcSmAllocate to allocate memory not called from the stub, the application must call RpcSmEnableAllocate to establish the required memory management environment.

The RpcSmAllocate routine returns a pointer to the allocated memory if the call is successful. Otherwise, a NULL is returned.

When the stub establishes the memory management, it frees any memory allocated by RpcSmAllocate. The application can free such memory before returning to the calling stub by calling RpcSmFree.

By contrast, when the application establishes the memory management, it must free any memory allocated. It does so by calling either RpcSmFree or RpcSmDisableAllocate.

To manage the same memory within the stub memory management environment, multiple threads can call RpcSmAllocate and RpcSmFree. In this case, the threads must share the same stub memory management thread handle. Applications pass thread handles from thread to thread by calling RpcSmGetThreadHandle and RpcSmSetThreadHandle.

See Memory Management for a complete discussion of the various memory management conditions supported by RPC.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_OUT_OF_MEMORY	Out of Memory
See Also

RpcSmEnableAllocate, RpcSmDisableAllocate, RpcSmFree, RpcSmGetThreadHandle, RpcSmSetThreadHandle


RpcSmClientFree

The RpcSmClientFree function frees memory returned from a client stub.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcSmClientFree(

void  *  NodeToFree
);
Parameters

NodeToFree

Specifies a pointer to memory returned from a client stub.

Remarks

The RpcSmClientFree routine releases memory allocated and returned from a client stub. The memory management handle of the thread calling this routine must match the handle of the thread that made the RPC call. Use RpcSmGetThreadHandle and RpcSmSetThreadHandle to pass handles from thread to thread.

Note that using RpcSmClientFree allows a routine to free dynamically-allocated memory returned by an RPC call without knowing the memory management environment from which it was called.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcSmFree, RpcSmGetThreadHandle, RpcSmSetClientAllocFree, RpcSmSetThreadHandle, RpcSmSwapClientAllocFree


RpcSmDestroyClientContext

The RpcSmDestroyClientContext function reclaims the client memory resources for a context handle and makes the context handle NULL.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcSmDestroyClientContext(

void* *  ContextHandle
);
Parameters

ContextHandle

Specifies the context handle that can no longer be used.

Remarks

The RpcSmDestroyClientContext routine is used by client applications to reclaim resources used for an inactive context handle. Applications can call RpcSmDestroyClientContext after a communications error makes the context handle unusable.

Note that when this routine reclaims the memory resources, it also makes the context handle NULL.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_X_SS_CONTEXT_MISMATCH	Invalid handle
See Also

RpcSmFree, RpcSmGetThreadHandle, RpcSmSetClientAllocFree, RpcSmSetThreadHandle, RpcSmSwapClientAllocFree


RpcSmDisableAllocate

The RpcSmDisableAllocate function frees resources and memory within the stub memory management environment.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcSmDisableAllocate (VOID);

Remarks

The RpcSmDisableAllocate routine frees all the resources used by a call to RpcSmEnableAllocate. It also releases memory that was allocated by a call to RpcSmAllocate after the call to RpcSmEnableAllocate.

Note that RpcSmEnableAllocate and RpcSmDisableAllocate must be used together as matching pairs.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcSmAllocate, RpcSmEnableAllocate


RpcSmEnableAllocate

The RpcSmEnableAllocate function establishes the stub memory management environment.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcSmEnableAllocate (VOID);

Remarks

In cases where the stub memory management is not enabled by the server stub itself, applications call the RpcSmEnableAllocate routine to establish the stub memory management environment. This environment must be established prior to making a call to RpcSmAllocate. In OSF-compatibility (/osf) mode, for server manager code called from the stub, the memory management environment may be established by the server stub itself by using pointer manipulation or the enable_allocate attribute. In default (Microsoft-extended) mode, the environment is established only upon request by using the enable_allocate attribute (see The MIDL Reference.) Otherwise, call RpcSmEnableAllocate before calling RpcSmAllocate. See Memory Management for a complete discussion of the memory management conditions used by RPC.

RpcSmGetThreadHandle and RpcSmSetThreadHandle

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_OUT_OF_MEMORY	Out of memory
See Also

RpcSmAllocate, RpcSmDisableAllocate


RpcSmFree

The RpcSmFree function releases memory allocated by RpcSmAllocate.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcSmFree(

void  *  NodeToFree
);
Parameters

NodeToFree

Specifies a pointer to memory allocated by RpcSmAllocate or RpcSsAllocate.

Remarks

The RpcSmFree routine is used by applications to free memory allocated by RpcSmAllocate. In cases where the stub allocates the memory for the application, the RpcSmFree routine can also be used to release memory. See Memory Management for a complete discussion of memory management conditions supported by RPC.

Note that the handle of the thread calling RpcSmFree must match the handle of the thread that allocated the memory by calling RpcSmAllocate. Use RpcSmGetThreadHandle and RpcSmSetThreadHandle to pass handles from thread to thread.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcSmAllocate, RpcSmGetThreadHandle, RpcSmSetThreadHandle


RpcSmGetThreadHandle

The RpcSmGetThreadHandle function returns a thread handle, or NULL, for the stub memory management environment.

#include <rpc.h>

RPC_SS_THREAD_HANDLE RPC_ENTRY RpcSmGetThreadHandle (

RPC_STATUS *  pStatus
);
Parameters

pStatus

Specifies a pointer to the returned status.

Remarks

The RpcSmGetThreadHandle routine is called by applications to obtain a thread handle for the stub memory management environment. A thread used to manage memory for the stub memory management environment uses RpcSmGetThreadHandle to receive a handle for its memory environment. In this way, another thread that calls RpcSmSetThreadHandle by using this handle can then use the same memory management environment.

The same memory management thread handle must be used by multiple threads calling RpcSmAllocate and RpcSmFree in order to manage the same memory. Before spawning new threads to manage the same memory, the thread that established the memory management environment (parent thread) calls RpcSmGetThreadHandle to obtain a thread handle for this environment. Then, the spawned threads call RpcSmSetThreadHandle with the new manager handle provided by the parent thread.

Note that the RpcSmGetThreadHandle routine is usually called by a server manager procedure before additional threads are spawned. The stub sets up the memory management environment for the manager procedure, and the manager calls RpcSmGetThreadHandle to make this environment available to the other threads.

A thread can also call RpcSmGetThreadHandle and RpcSmSetThreadHandle to save and restore its memory management environment.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcSmAllocate, RpcSmFree, RpcSmSetThreadHandle


RpcSmSetClientAllocFree

The RpcSmSetClientAllocFree function enables the memory allocation and release mechanisms used by the client stubs.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcSmSetClientAllocFree(

RPC_CLIENT_ALLOC  *  pfnAllocate,
RPC_CLIENT_FREE  *  pfnFree
);
Parameters

pfnAllocate

Specifies the routine used to allocate memory.

pfnFree

Specifies the routine used to release memory and used with the routine specified by pfnAllocate.

Remarks

By overriding the default routines used by the client stub to manage memory, the RpcSmSetClientAllocFree routine establishes the memory allocation and memory freeing mechanisms. Note that the default routines are free and malloc, unless the remote call occurs within manager code. In this case, the default memory management routines are RpcSmFree and RpcSmAllocate.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_OUT_OF_MEMORY	Out of memory
See Also

RpcSmAllocate, RpcSmFree


RpcSmSetThreadHandle

The RpcSmSetThreadHandle function sets a thread handle for the stub memory management environment.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcSmSetThreadHandle (

RPC_SS_THREAD_HANDLE  Handle
);
Parameters

Handle

Specifies a thread handle returned by a call to RpcSmGetThreadHandle.

Remarks

The RpcSmSetThreadHandle routine is called by an application to set a thread handle for the stub memory management environment. A thread used to manage memory for the stub memory management environment calls RpcSmGetThreadHandle to obtain a handle for its memory environment. In this way, another thread that calls RpcSmSetThreadHandle by using this handle can then use the same memory management environment.

The same memory management thread handle must be used by multiple threads calling RpcSmAllocate and RpcSmFree in order to manage the same memory. Before spawning new threads to manage the same memory, the thread that established the memory management environment (parent thread) calls RpcSmGetThreadHandle to obtain a thread handle for this environment. Then, the spawned threads call RpcSmSetThreadHandle with the new manager handle provided by the parent thread.

Note that the RpcSmSetThreadHandle routine is usually called by a thread spawned by a server manager procedure. The stub sets up the memory management environment for the manager procedure, and the manager calls RpcSmGetThreadHandle to obtain a thread handle. Then, each spawned thread calls RpcSmGetThreadHandle to get access to the manager’s memory management environment.

A thread can also call RpcSmGetThreadHandle and RpcSmSetThreadHandle to save and restore its memory management environment.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcSmAllocate, RpcSmGetThreadHandle, RpcSmFree


RpcSmSwapClientAllocFree

The RpcSmSwapClientAllocFree function exchanges the memory allocation and release mechanisms used by the client stubs with one supplied by the client.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcSmSwapClientAllocFree(

RPC_CLIENT_ALLOC  *  pfnAllocate,
RPC_CLIENT_FREE  *  pfnFree,
RPC_CLIENT_ALLOC **  pfnOldAllocate,
RPC_CLIENT_FREE  **  pfnOldFree
);
Parameters

pfnAllocate

Specifies a new routine to allocate memory.

pfnFree

Specifies a new routine to release memory.

pfnOldAllocate

Returns the previous routine to allocate memory before the call to this routine.

pfnOldFree

Returns the previous routine to release memory before the call to this routine.

Remarks

The RpcSmSwapClientAllocFree routine exchanges the current memory allocation and memory freeing mechanisms with those supplied by the client.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_ARG	Invalid argument(s)
See Also

RpcSmAllocate, RpcSmFree, RpcSmSetClientAllocFree


RpcSsAllocate

The RpcSsAllocate function allocates memory within the RPC stub memory management function, and returns a pointer to the allocated memory or NULL.

#include <rpc.h>

void __RPC_FAR * RPC_ENTRY RpcSsAllocate(

size_t  Size
);
Parameters

Size

Specifies the size of memory to allocate (in bytes).

Remarks

The RpcSsAllocate routine allows an application to allocate memory within the RPC stub memory management function. Prior to calling RpcSsAllocate, the memory management environment must already be established. For memory management called within the stub, the stub itself usually establishes the necessary environment. See Chapter 8, “Memory Management,” for a complete discussion of the various memory management conditions supported by RPC. When using RpcSsAllocate to allocate memory not called from the stub, the application must call RpcSsEnableAllocate to establish the required memory management environment.

The RpcSsAllocate routine returns a pointer to the allocated memory, if the call was successful. Otherwise, it raises an exception.

When the stub establishes the memory management, it frees any memory allocated by RpcSsAllocate. The application can free such memory before returning to the calling stub by calling RpcSsFree.

By contrast, when the application establishes the memory management, it must free any memory allocated. It does so by calling either RpcSsFree or RpcSsDisableAllocate.

To manage the same memory within the stub memory management environment, multiple threads can call RpcSsAllocate and RpcSsFree. In this case, the threads must share the same stub memory management thread handle. Applications pass thread handles from thread to thread by calling RpcSsGetThreadHandle and RPCSsSetThreadHandle.

Note  The RpcSsAllocate routine raises exceptions, while the RpcSmAllocate routine returns the error code.

Return Values

Value	Meaning
RPC_S_OUT_OF_MEMORY	Out of memory
See Also

RpcSmAllocate, RpcSsDisableAllocate, RpcSsEnableAllocate, RpcSsFree, RpcSsGetThreadHandle, RpcSsSetThreadHandle


RpcSsDestroyClientContext

The RpcSsDestroyClientContext function destroys a context handle no longer needed by the client without contacting the server.

#include <rpc.h>

void RPC_ENTRY RpcSsDestroyClientContext(

void  * * ContextHandle
);
Parameters

ContextHandle

Specifies the context handle to be destroyed. The handle is set to NULL before RpcSsDestroyClientContext returns.

Remarks

RpcSsDestroyClientContext is used by the client application to reclaim the memory resources used to maintain a context handle on the client. This function is used when ContextHandle is no longer valid, such as when a communication failure has occurred and the server is no longer available. The context handle is set to NULL.

Do not use RpcSsDestroyClientContext to replace a server function that closes the context handle.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_X_SS_CONTEXT_MISMATCH	Invalid context handle
See Also

RpcBindingReset


RpcSsDisableAllocate

The RpcSsDisableAllocate function frees resources and memory within the stub memory management environment.

#include <rpc.h>

void RPC_ENTRY RpcSsDisableAllocate (VOID);

Remarks

The RpcSsDisableAllocate routine frees all the resources used by a call to RpcSsEnableAllocate. It also releases memory that was allocated by a call to RpcSsAllocate after the call to RpcSsEnableAllocate.

RpcSsEnableAllocate and RpcSsDisableAllocate must be used together as matching pairs.

See Also

RpcSmDisableAllocate, RpcSsAllocate, RpcSsEnableAllocate


RpcSsDontSerializeContext

The RpcSsDontSerializeContext function disables runtime serialization of multiple calls dispatched to server manager routines on the same context handle.

#include <rpc.h>

void RPC_ENTRY RpcSsDontSerializeContext(void);

Remarks

Normally RPC runtime serializes calls on the same context handle dispatched to server manager routines. Context handles are maintained on a per client basis and typically represent the server-side state. This means that your server manager does not have to guard against another thread from the same client changing the context or from the context running down while a call is dispatched.

Calling the RpcSsDontSerializeContext routine prevents RPC runtime from performing this serialization service.

Note  A call to RpcSsDontSerializeContext affects the entire process and is unrevertable. If you use this routine you should expect, and provide routines to handle, asynchronous context rundowns.


RpcSsEnableAllocate

The RpcSsEnableAllocate function establishes the stub memory management environment.

#include <rpc.h>

void RPC_ENTRY RpcSsEnableAllocate (VOID);

Remarks

In cases where the stub memory management is not enabled by the stub itself, the RpcSsEnableAllocate routine is called by applications to establish the stub memory management environment. This environment must be established prior to making a call to RpcSsAllocate. For server manager code called from the stub, the memory management environment is usually established by the stub itself. Otherwise, call RpcSsEnableAllocate before calling RpcSsAllocate. See Memory Management for a complete discussion of the memory management conditions used by RPC. To learn how spawned threads use a stub memory management environment, see RpcSsGetThreadHandle and RpcSsSetThreadHandle later in this section.

Note  The RpcSsEnableAllocate routine raises exceptions, while the RpcSmEnableAllocate routine returns the error code.

Return Values

Value	Meaning
RPC_S_OUT_OF_MEMORY	Out of memory
See Also

RpcSmEnableAllocate, RpcSsAllocate, RpcSsDisableAllocate


RpcSsFree

The RpcSsFree function releases memory allocated by RpcSsAllocate.

#include <rpc.h>

void RPC_ENTRY RpcSsFree(

void *  NodeToFree
);
Parameters

NodeToFree

Specifies a pointer to memory allocated by RpcSsAllocate or RpcSmAllocate.

Remarks

The RpcSsFree routine is used by applications to free memory allocated by RpcSsAllocate. In cases where the stub allocates the memory for the environment, the RpcSsFree routine can also be used to release memory. See Memory Management for a complete discussion of memory management conditions supported by RPC.

Note that the handle of the thread calling RpcSsFree must match the handle of the thread that allocated the memory by calling RpcSsAllocate. Use RpcSsGetThreadHandle and RpcSsSetThreadHandle to pass handles from thread to thread.

See Also

RpcSmFree, RpcSsAllocate, RpcSsGetThreadHandle, RpcSsSetThreadHandle


RpcSsGetThreadHandle

The RpcSsGetThreadHandle function returns a thread handle for the stub memory management environment.

#include <rpc.h>

RPC_SS_THREAD_HANDLE RPC_ENTRY RpcSsGetThreadHandle (VOID);

Remarks

The RpcSsGetThreadHandle routine is called by applications to obtain a thread handle for the stub memory management environment. A thread used to manage memory for the stub memory management environment uses RpcSsGetThreadHandle to receive a handle for its memory environment. In this way, another thread that calls RpcSsSetThreadHandle by using this handle can then use the same memory management environment.

The same thread handle must be used by multiple threads calling RpcSsAllocate and RpcSsFree in order to manage the same memory. Before spawning new threads to manage the same memory, the thread that established the memory management environment (parent thread) calls RpcSsGetThreadHandle to obtain a thread handle for this environment. Then, the spawned threads call RpcSsSetThreadHandle with the handle provided by the parent thread.

The RpcSsGetThreadHandle routine is usually called by a server manager procedure before additional threads are spawned. The stub sets up the memory management environment for the manager procedure, and the manager calls RpcSsGetThreadHandle to make this environment available to the other threads.

A thread can also call RpcSsGetThreadHandle and RpcSsSetThreadHandle to save and restore its memory management environment.

Note  The RpcSsGetThreadHandle routine raises exceptions, while the RpcSmGetThreadHandle routine returns the error code.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcSmGetThreadHandle, RpcSsAllocate, RpcSsFree, RpcSsSetThreadHandle


RpcSsSetClientAllocFree

The RpcSsSetClientAllocFree function enables the memory allocation and release mechanisms used by the client stubs.

#include <rpc.h>

void RPC_ENTRY RpcSsSetClientAllocFree(

RPC_CLIENT_ALLOC *  pfnAllocate,
RPC_CLIENT_FREE  *  pfnFree
);
Parameters

pfnAllocate

Specifies the routine used to allocate memory.

pfnFree

Specifies the routine used to release memory and used with the routine specified by pfnAllocate.

Remarks

By overriding the default routines used by the client stub to manage memory, the RpcSsSetClientAllocFree routine establishes the memory allocation and memory freeing mechanisms. Note that the default routines are free and malloc, unless the remote call occurs within manager code. In this case, the default memory management routines are RpcSsFree and RpcSsAllocate.

Note that when this routine reclaims the memory resources, it also makes the context handle NULL.

Note  The RpcSsSetClientAllocFree routine raises exceptions, while the RpcSmSetClientAllocFree routine returns the error code.

Return Values

Value	Meaning
RPC_S_OUT_OF_MEMORY	Out of memory
See Also

RpcSmSetClientAllocFree, RpcSsAllocate, RpcSsFree


RpcSsSetThreadHandle

The RpcSsSetThreadHandle function sets a thread handle for the stub memory management environment.

#include <rpc.h>

void RPC_ENTRY RpcSsSetThreadHandle(

RPC_SM_THREAD_HANDLE  Handle
);
Parameters

Handle

Specifies a thread handle returned by a call to RpcSsGetThreadHandle.

Remarks

The RpcSsSetThreadHandle routine is called by an application to set a thread handle for the stub memory management environment. A thread used to manage memory for the stub memory management environment calls RpcSsGetThreadHandle to obtain a handle for its memory environment. In this way, another thread that calls RpcSsSetThreadHandle by using this handle can then use the same memory management environment.

The same thread handle must be used by multiple threads calling RpcSsAllocate and RpcSsFree in order to manage the same memory. Before spawning new threads to manage the same memory, the thread that established the memory management environment (parent thread) calls RpcSsGetThreadHandle to obtain a thread handle for this environment. Then, the spawned threads call RpcSsSetThreadHandle with the handle provided by the parent thread.

The RpcSsSetThreadHandle routine is usually called by a thread spawned by a server manager procedure. The stub sets up the memory management environment for the manager procedure, and the manager calls RpcSsGetThreadHandle to obtain a thread handle. Then, each spawned thread calls RpcSsGetThreadHandle to get access to the manager’s memory management environment.

A thread can also call RpcSsGetThreadHandle and RpcSsSetThreadHandle to save and restore its memory management environment.

Note  The RpcSsSetThreadHandle routine raises exceptions, while the RpcSmSetThreadHandle routine returns the error code.

See Also

RpcSmSetThreadHandle, RpcSsAllocate, RpcSsFree, RpcSsGetThreadHandle


RpcSsSwapClientAllocFree

The RpcSsSwapClientAllocFree function exchanges the memory allocation and release mechanisms used by the client stubs with one supplied by the client.

#include <rpc.h>

void RPC_ENTRY RpcSsSwapClientAllocFree(

RPC_CLIENT_ALLOC*  pfnAllocate,
RPC_CLIENT_FREE*  pfnFree,
RPC_CLIENT_ALLOC**  pfnOldAllocate,
RPC_CLIENT_FREE**  pfnOldFree
);
Parameters

pfnAllocate

Specifies a new routine to allocate memory.

pfnFree

Specifies a new routine to release memory.

pfnOldAllocate

Returns the previous routine to allocate memory before the call to this routine.

pfnOldFree

Returns the previous routine to release memory before the call to this routine.

Remarks

The RpcSsSwapClientAllocFree routine exchanges the current memory allocation and memory freeing mechanisms with those supplied by the client.

Note  The RpcSsSwapClientAllocFree routine raises exceptions, while the RpcSmSwapClientAllocFree routine returns the error code.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_OUT_OF_MEMORY	Out of memory
See Also

RpcSmSwapClientAllocFree, RpcSsAllocate, RpcSsFree, RpcSsSetClientAllocFree


RpcStringBindingCompose

The RpcStringBindingCompose function combines the components of a string binding into a string binding.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcStringBindingCompose(

unsigned char *  ObjUuid,
unsigned char *  ProtSeq,
unsigned char *  NetworkAddr,
unsigned char *  EndPoint,
unsigned char *  Options,
unsigned char * *  StringBinding
);
Parameters

ObjUuid

Points to a NULL-terminated string representation of an object UUID. For example, the string “6B29FC40-CA47-1067-B31D-00DD010662DA” represents a valid UUID.

ProtSeq

Points to a NULL-terminated string representation of a protocol sequence.

For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

NetworkAddr

Points to a NULL-terminated string representation of a network address. The network-address format is associated with the protocol sequence. For more information, see the RPC data types and structures reference entry for string binding.

EndPoint

Points to a NULL-terminated string representation of an endpoint. The endpoint format and content are associated with the protocol sequence. For example, the endpoint associated with the protocol sequence ncacn_np is a pipe name in the format “\pipe\pipename”. For more information, see the RPC data types and structures reference entry for string binding.

Options

Points to a NULL-terminated string representation of network options. The option string is associated with the protocol sequence. For more information, see the RPC data types and structures reference entry for string binding.

StringBinding

Returns a pointer to a pointer to a NULL-terminated string representation of a binding handle.

Specify a null value to prevent RpcStringBindingCompose from returning the StringBinding argument. In this case, the application does not call the RpcStringFree routine. For more information, see the RPC data types and structures reference entry for string binding.

Remarks

An application calls the RpcStringBindingCompose routine to combine the components of a string-binding handle into a string-binding handle.

The RPC run-time library allocates memory for the string returned in the StringBinding argument. The application is responsible for calling the RpcStringFree routine to deallocate that memory.

Specify a null argument value or provide an empty string (“\0”) for each input string that has no data.

Literal backslash characters within C-language strings must be quoted. The actual C string for the server name appears as “\\\\servername”, and the actual C string for a pipe name appears as “\\pipe\\pipename”.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_STRING_UUID	String representation of the UUID not valid.
See Also

RpcBindingFromStringBinding, RpcBindingToStringBinding, RpcStringBindingParse, RpcStringFree


RpcStringBindingParse

The RpcStringBindingParse function returns the object UUID part and the address parts of a string binding as separate strings.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcStringBindingParse(

unsigned char *  StringBinding,
unsigned char * *  ObjectUuid,
unsigned char * *  ProtSeq,
unsigned char * *  NetworkAddr,
unsigned char * *  EndPoint,
unsigned char * *  NetworkOptions
);
Parameters

StringBinding

Points to a NULL-terminated string representation of a binding.

ObjectUuid

Returns a pointer to a pointer to a NULL-terminated string representation of an object UUID.

Specify a null value to prevent RpcStringBindingParse from returning the ObjectUuid argument. In this case, the application does not call the RpcStringFree routine.

ProtSeq

Returns a pointer to a pointer to a NULL-terminated string representation of a protocol sequence.

For a list of Microsoft RPC’s supported protocol sequences, see the reference topic String Binding in RPC Data Types and Structures.

Specify a null value to prevent RpcStringBindingParse from returning the ProtSeq argument. In this case, the application does not call the RpcStringFree routine.

NetworkAddr

Returns a pointer to a pointer to a NULL-terminated string representation of a network address.

Specify a null value to prevent RpcStringBindingParse from returning the NetworkAddr argument. In this case, the application does not call the RpcStringFree routine.

EndPoint

Returns a pointer to a pointer to a NULL-terminated string representation of an endpoint.

Specify a null value to prevent RpcStringBindingParse from returning the EndPoint argument. In this case, the application does not call the RpcStringFree routine.

NetworkOptions

Returns a pointer to a pointer to a NULL-terminated string representation of network options.

Specify a null value to prevent RpcStringBindingParse from returning the NetworkOptions argument. In this case, the application does not call the RpcStringFree routine.

Remarks

An application calls the RpcStringBindingParse routine to parse a string representation of a binding handle into its component fields.

The RPC run-time library allocates memory for each component string returned. The application is responsible for calling the RpcStringFree routine once for each returned string to deallocate the memory for that string.

If any field of the StringBinding argument is empty, the RpcStringBindingParse routine returns an empty string (“\0”) in the corresponding output argument.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_STRING_BINDING	Invalid string binding
See Also

RpcBindingFromStringBinding, RpcBindingToStringBinding, RpcStringBindingCompose, RpcStringFree


RpcStringFree

The RpcStringFree function frees a character string allocated by the RPC run-time library.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcStringFree(

unsigned char * *  String
);
Parameters

String

Points to a pointer to the character string to free.

Remarks

The RpcStringFree routine deallocates the memory containing a NULL-terminated character string returned by the RPC run-time library.

An application is responsible for calling RpcStringFree once for each character string allocated and returned by calls to other RPC run-time library routines.

Return Values

Value	Meaning
RPC_S_OK	Success
See Also

RpcBindingToStringBinding, RpcNsBindingInqEntryName, RpcStringBindingParse


RpcTestCancel

The RpcTestCancel function checks for a cancel indication.

This function is supported only by Windows NT.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcTestCancel(VOID);

Remarks

An application server stub calls the RpcTestCancel routine to determine whether the call has been cancelled. If the call has been cancelled, RPC_S_OK is returned; otherwise, another value is returned.

This routine should be called periodically by the server stub so that it can respond to cancels in a timely fashion. If the routine returns RPC_S_OK, the stub should clean up its data structures and return to the client.

Return Values

Value	Meaning
RPC_S_OK	Call has been cancelled
Other values	Call has not been cancelled


RpcTryExcept

See

RpcExcept


RpcTryFinally

See

RpcFinally


RpcWinSetYieldInfo

The RpcWinSetYieldInfo function configures Microsoft Windows 3.x client applications to yield to other applications during remote procedure calls.

Note  This function is only available for 16-bit Windows client applications. A 32-bit application should take advantage of the preemptive multitasking and multithreading support that the 32-bit Windows operating systems provide.

#include <rpc.h>

RPC_STATUS

RpcWinSetYieldInfo(

HWND  hWnd,
BOOL  fCustomYield,
WORD  wMsg,
DWORD  dwOtherInfo
);
Parameters

hWnd

Identifies the application window that receives messages relating to yielding. Applications should usually specify the parent window of the dialog box.

Standard yield applications receive messages for both the start and end of the yield period. Custom yield applications receive messages that indicate when the RPC operation has completed.

fCustomYield

Specifies the yielding method. The following values are defined:

Value	Yield method
TRUE	Custom yield
FALSE	Standard yield
wMsg

Specifies the message that is posted by the RPC run-time library to notify the application of RPC events. The message value should be in the range beginning with WM_USER. If a zero value is specified, no message is posted.

For standard-yield applications, the message indicates the beginning or end of the yield period. This allows the application to refrain from performing operations that are illegal during an RPC operation. Standard-yield applications use the following values of wParam and lParam with this message:

Parameter	Value	Description
wParam	1	Yield period beginning
wParam	0	Yield period ending
lParam	−	Unused
For a custom-yield application, the wMsg message notifies the application that the RPC operation is complete. When the application receives this message, it should immediately return control to the RPC run-time library by having the callback function return. The values of wParam and lParam are set to zero and are not used.

dwOtherInfo

Specifies additional information about the yielding behavior.

For standard-yield applications, dwOtherInfo contains an optional HANDLE to an application-supplied dialog-box resource. This handle is passed as the second parameter to the DialogBoxIndirect function. If the handle specified by dwOtherInfo is zero, the default dialog box supplied by the RPC run-time library is used. For more informatin about DialogBoxIndirect, see your Windows API reference documentation.

For custom-yield applications, dwOtherInfo contains the procedure-instance address of the application-supplied callback function.

Remarks

The RpcWinSetYieldInfo function supports two yielding methods:

•	Standard yield method. The RPC run-time library provides a standard modal dialog box that includes a single push-button control with an IDCANCEL ID. The dialog box prevents direct user input, such as mouse and keyboard events, from being sent to the application. The application continues to receive messages while the dialog box is present. The IDCANCEL message indicates that the application user wants to end the remote procedure.

•	Custom yield method. The application provides a callback function that the RPC run-time library calls while a remote operation is in progress. The callback function must retrieve messages from the message queue (including mouse and keyboard messages) and must process messages (both queued and non-queued). The RPC run-time library posts a message to the application’s queue when the RPC operation is complete. The callback function returns a boolean value to the RPC run-time library.

When a conventional RPC client application makes a remote procedure call, the MIDL-generated stub calls the RPC run-time library and the library calls the appropriate transport. These calls are synchronous and block until the server side sends back a response. In the cooperatively multitasked Windows 3.x environment, an active, blocked application prevents Windows and other Windows applications from running. The RpcWinSetYieldInfo function allows you to direct the application to yield to Windows and other Windows applications while waiting for an RPC operation to finish.

Windows RPC client applications can be organized into three classes that correspond to levels of yielding support: no yielding, standard yielding, and custom yielding.

•	Some applications do not yield. RPC calls block until completion.

•	Standard-yield applications are RPC-aware applications that yield but do not need to perform special handling.

•	Custom-yield applications are those that are RPC aware and want to perform special handling while an RPC operation is in progress.

You can replace the provided dialog-box resource with an application-specified dialog-box resource. The resource must use the same style as the default and must contain a single push-button control with an IDCANCEL ID. The dialog-box function is part of the RPC run-time library and cannot be replaced.

To yield in a well-behaved manner from within the context of a pending RPC operation, applications must observe the following rules:

•	Do not make another RPC call. If the RPC run-time library detects that a new call is being made during the yielding period, it returns an error to the caller. This is particularly important if the application makes RPC calls in response to common messages, such as WM_PAINT.

•	Do not exit the application. Do not close the window specified by the hWnd handle parameter. Your application can process WM_CLOSE messages in the window procedure and not call DefWindowProc during the yielding period. For more information about DefWindowProc, see your Windows API reference documentation.

•	Return FALSE in response to WM_QUERYENDSESSION messages. Alternatively, a custom-yield application can use this message as a signal to cause YieldFunctionName to return FALSE to the RPC run-time library and end the yielding period.

There is no guarantee that any code that supports yielding will be invoked. Whether or not an application yields depends on the specific call, the current state of the underlying system, and the implementation of the underlying RPC transport. Applications should not rely on this code to do anything other than manage yielding.

The RpcWinSetYieldInfo function can be called more than once by an application. Each call simply replaces the information stored in the previous calls.

Return Values

Value	Meaning
RPC_S_OK	The information was set successfully.
RPC_S_OUT_OF_MEMORY	Memory could not be allocated to store the information for this task.
See Also

DefWindowProc, DialogBoxIndirect, MakeProcInstance, YieldFunctionName


RpcWinSetYieldTimeout

The RpcWinSetYieldTimeout function configures the amount of time an RPC call will wait for the server to respond before invoking the application’s RPC yielding mechanism. This function is only available for Windows 3.x applications.

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcWinSetYieldTimeout (

unsigned int  Timeout
);
Parameters

Timeout

Specifies the timeout value in milliseconds. If this function is not called, the default is 500 milliseconds.

Remarks

Depending on the type of yielding specified in RpcWinSetYieldInfo, this can either produce a dialog box or signal the application.

If the Timeout value is small, the yielding mechanism can be invoked too often. This results in loss of performance. Conversely, if the value specified for Timeout is too large, the application and system will be frozen for the timeout period. To avoid this, use timeouts in the range of 500 to 2000 milliseconds.

The RpcWinSetYieldTimeout function can be called more than once by an application. Each call simply replaces the information stored in the previous calls.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_CANNOT_SUPPORT	RpcWinSetYieldInfo must be called prior to RpcWinSetYieldTimeout.
See Also

RpcWinSetYieldInfo


UuidCompare

The UuidCompare function compares two UUIDs.

#include <rpc.h>

signed int RPC_ENTRY UuidCompare(

UUID *  Uuid1,
UUID *  Uuid2,
RPC_STATUS *  Status
);
Parameters

Uuid1

Specifies a pointer to a UUID. This UUID is compared with the UUID specified in the Uuid2 argument.

Uuid2

Specifies a pointer to a UUID. This UUID is compared with the UUID specified in the Uuid1 argument.

Status

Returns any errors that may occur, and will normally be set by the function to RPC_S_OK upon return.

Remarks

An application calls the UuidCompare routine to compare two UUIDs and determine their order. To determine order, one of the following is returned:

Returned Value	Meaning
-1	The Uuid1 argument is less than the Uuid2 argument.
0	The Uuid1 argument is equal to the Uuid2 argument.
1	The Uuid1 argument is greater than the Uuid2 argument.
See Also

UuidCreate


UuidCreate

The UuidCreate function creates a new UUID.

#include <rpc.h>

RPC_STATUS RPC_ENTRY UuidCreate(

UUID *  Uuid
);
Parameters

Uuid

Returns a pointer to the created UUID.

Remarks

An application calls the UuidCreate routine to create a new UUID.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_UUID_NO_ADDRESS	Cannot get Ethernet or token-ring hardware address for this computer
See Also

UuidFromString, UuidToString


UuidCreateNil

The UuidCreateNil function creates a nil-valued UUID.

#include <rpc.h>

RPC_ENTRY UuidCreateNil(

UUID *  Nil_Uuid,
RPC_STATUS *  Status
);
Parameters

Nil_Uuid

Returns a nil-valued UUID.

Status

Returns any errors that may occur. The parameter is typically set by the function to RPC_S_OK upon return.

Remarks

An application calls the UuidCreateNil routine to create a nil-valued UUID.


UuidEqual

The UuidEqual function determines if two UUIDs are equal.

#include <rpc.h>

int RPC_ENTRY UuidEqual(

UUID *  Uuid1,
UUID *  Uuid2,
RPC_STATUS *  Status
);
Parameters

Uuid1

Specifies a pointer to a UUID. This UUID is compared with the UUID specified in the Uuid2 argument.

Uuid2

Specifies a pointer to a UUID. This UUID is compared with the UUID specified in the Uuid1 argument.

Status

Returns any errors that may occur, and will normally be set by the function to RPC_S_OK upon return.

Remarks

An application calls the UuidEqual routine to compare two UUIDs and determine whether they are equal. Upon completion, one of the following is returned:

Returned Value	Meaning
TRUE	The Uuid1 argument is equal to the Uuid2 argument.
FALSE	The Uuid1 argument is not equal to the Uuid2 argument.
See Also

UuidCreate


UuidFromString

The UuidFromString function converts a string to a UUID.

#include <rpc.h>

RPC_STATUS RPC_ENTRY UuidFromString(

unsigned char *  StringUuid,
UUID *  Uuid
);
Parameters

StringUuid

Points to a string representation of a UUID.

Uuid

Returns a pointer to a UUID in binary form.

Remarks

An application calls the UuidFromString routine to convert a string UUID to a binary UUID.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_INVALID_STRING_UUID	The string UUID is invalid
See Also

UuidToString


UuidHash

The UuidHash function creates a hash value for a UUID.

#include <rpc.h>

unsigned short RPC_ENTRY UuidHash(

UUID *  Uuid,
RPC_STATUS *  Status
);
Parameters

Uuid

Specifies the UUID for which a hash value is created.

Status

Returns any errors that may occur, and will normally be set by the function to RPC_S_OK upon return.

Remarks

An application calls the UuidHash routine to generate a hash value for a specified UUID. The hash value returned is implementation dependent and may vary from implementation to implementation.

See Also

UuidCreate


UuidIsNil

The UuidIsNil function determines if a UUID is a nil-valued UUID.

#include <rpc.h>

int RPC_ENTRY UuidIsNil(

UUID *  Uuid,
RPC_STATUS *  Status
);
Parameters

Uuid

Specifies a UUID to test for nil value.

Status

Returns any errors that may occur, and will typically be set by the function to RPC_S_OK upon return.

Remarks

An application calls the UuidIsNil routine to determine whether the specified UUID is a nil-valued UUID. This routine acts as though the application called the UuidCreateNil routine, and then called the UuidEqual routine to compare the returned nil-value UUID to the UUID specified in the Uuid argument.

Upon completion, one of the following is returned:

Returned Value	Meaning
TRUE	The Uuid argument is a nil-valued UUID.
FALSE	The Uuid argument is not a nil-valued UUID.
See Also

UuidCreate


UuidToString

The UuidToString function converts a UUID to a string.

#include <rpc.h>

RPC_STATUS RPC_ENTRY UuidToString(

UUID *  Uuid,
unsigned char * *  StringUuid
);
Parameters

Uuid

Points to a binary UUID.

StringUuid

Returns a pointer to a pointer to the string representation of the UUID specified in the Uuid argument.

Specify a null value to prevent UuidToString from returning the StringUuid argument. In this case, the application does not call the RpcStringFree routine.

Remarks

An application calls UuidToString to convert a binary UUID to a string UUID. The RPC run-time library allocates memory for the string returned in the StringUuid argument. The application is responsible for calling the RpcStringFree routine to deallocate that memory.

Return Values

Value	Meaning
RPC_S_OK	Success
RPC_S_OUT_OF_MEMORY	No memory
See Also

RpcStringFree, UuidFromString


YieldFunctionName

YieldFunctionName is a placeholder name for the application-supplied function name provided as a parameter to the RpcWinSetYieldInfo routine.

BOOL FAR PASCAL  YieldFunctionName(VOID);

Remarks

The callback function must retrieve messages from the message queue (including mouse and keyboard messages) and must process messages, both queued and non-queued.

YieldFunctionName should return TRUE when the application is notified that the RPC operation has completed (by receiving the wMsg message). It is an error for YieldFunctionName to return TRUE if it has not been notified that the RPC operation has completed.

YieldFunctionName should return FALSE if the user wants to cancel the RPC operation in progress. The RPC run-time library then attempts to abort the current operation, which is likely to result in the RPC call returning an error to the application. Note that due to race conditions, the operation can complete successfully even if YieldFunctionName returns FALSE.

See Also

RpcWinSetYieldInfo


Overview

The Setup API provides a set of functions that your setup application can call to perform installation operations.

These setup functions work closely with Windows® 95- and Windows NT® 4.0- style INF files to provide the following setup functionality.

For information about…	See…
Queueing files	File Queues
Installing files	File Queues INF Files Creating Setup Applications
Handling errors and prompting for media	Disk Prompting and Error Handling
Updating registry entries	INF Files
Logging installed files	File Log
Storing the most recently used source paths	MRU Source List
Unicode and ANSI versions are available for most setup functions. You can use the ANSI setup functions to create setup applications for the Windows 95 operating system. For Windows NT setup applications, you can use either ANSI or Unicode versions.

Note  Unicode text files should contain the standard 0XFEFF byte-order mark to enable setup functions to identify the file as Unicode text.

Although the Setup API supports prompting for new media and basic error-handling dialog boxes, the setup functions do not provide wizard functionality or a generic user interface.


Setup Applications

Typically, before you create a setup application, you create an INF file. An INF file is a text file that contains information used by your setup application during an installation. For more information, see INF Files.

After creating an INF file, you write the source code for your setup application. You can use the setup functions in your setup application to access the information in the INF file and perform installation operations. For more information about using the setup functions in an application, see Creating Setup Applications.


File Version Comparisions

If the SP_COPY_NEWER flag is specified during a file copy operation, the setup functions check for an existing copy of the file in the target directory. If an existing copy is found, the functions compare the versions of the target and source file to determine which is newer.

The file version information used during version checks is that specified in the dwFileVersionMS and dwFileVersionLS members of a VS_FIXEDFILEINFO structure, used by the Win32 version functions. If one of the files does not have version resources specified or if they have the same version information, the source file is treated as the newer file.


INF Files

Information (INF) files store information in a specific format. The setup functions retrieve information from the INF file to use when performing installation operations.

Examples of the type of information stored in an INF file include INI and registry changes, filenames, and locations of the source files on source media.


About INF Files

The following topics describe the new cross-platform INF file format used for Windows 95 and Windows NT 4.0. This new format replaces the script-based INF files used with Windows NT 3.x.

Also discussed are the types of sections in the new INF files, and how they fit together to provide the information that the setup functions use during an installation.


Introducing INF Files

Before you develop a Windows NT or Windows 95 setup application, you will probably want to create an information (INF) file.

An INF file is made up of different types of sections. Each type of section has a particular purpose; for example, to copy files or to add entries to the registry. Each line in a section contributes to that section’s purpose. The number and type of sections used in an INF file depends on the installation procedure.

Each section type has a particular format. The setup functions use this format to retrieve information from the INF file. This format is described in the following topics.

To be used by the operating system installer, an INF section must contain one or more items.

In addition to the formatted INF sections, an INF file can contain private sections. You can use a private section to store specialized information required by your setup application. The format of a private section will depend on your application.

The Setup API includes low-level functions that you can use to retrieve information from these private sections. Low-level setup functions, such as the SetupGetLineText and SetupGetIntField functions, retrieve information from the INF file at the line and field level.

Additional sections types are used when installing device drivers. For more information about these other sections, see the DDK Programmer’s Guide.


INF File Format

The new INF file format contains many types of named sections. Some of these are only used when installing device drivers and are not described in this document. For more information about these sections, see the DDK Programmer’s Guide.

When you create an INF file, you do not have to include every type of section. The sections you use will depend on your installation procedure.

The setup functions use the following INF sections.

Add Registry	Contains information used to add subkeys or value names to the registry.
Copy Files	Contains source filenames and can specify additional copying behavior.
Delete Registry	Contains information used to delete a subkey or value name from the registry.
Delete Files	Contains the filenames of files to delete, and can specify additional deletion behavior.
DestinationDirs	Maps Copy Files sections to a destination directory.
EventLog Install	Contains information used to add an event message to the registry.
INI File to Registry	Contains information used to move lines or sections from an INI file to the registry.
Install	Contains a list of the INF sections that the setup functions process during the installation.
Rename Files	Contains the source and target filenames for renaming operations.
Service Install	Contains information used to install the service listed in the AddService key of the Services section.
Services	Lists the services to add or install.
SourceDisksFiles	Maps the source files to their source location.
SourceDisksNames	Assigns an ordinal value to the source disks and can store additional information about the source disks.
Strings	Maps string keys (values in the INF file surrounded by percent signs (%)) to replacement strings.
Update INI Fields	Contains information used to replace, add, or delete fields in an INI entry.
Update INI File	Contains information used to replace, add, or delete an INI entry.
Version	Contains information about the INF file.
The only section that must be included is the Version section. The setup functions use this section to recognize an INF file as formatted for Windows 95 and Windows NT.

Each section title in the INF file, must be enclosed by square brackets ([ ]). In general, you can specify the title for an INF section. The exceptions to this are the DestinationDirs, SourceDisksFiles, SourceDisksNames, Strings, and Version sections. The titles of these sections must be identical to the section type. For example:

[DestinationDirs]

The SourceDisksNames and SourceDisksFiles sections can be specified with a platform-specific suffix. The following example shows an Intel-specific SourceDisksNames section.

[SourceDisksNames.x86]

The setup functions programmatically determine the platform of the user’s system. If the setup functions find platform-specific SourceDisksNames and SourceDisksFiles sections that match the user’s platform, the setup functions use the platform-specific sections. Otherwise the setup functions use the default (non-suffixed) SourceDisksNames and SourceDisksFiles sections.

The formatting of lines in a section varies according with its type. For more information about the format of a particular section, see INF File Format Reference.


INF File Sections

The different sections of an INF file fit together to provide the information used by the setup functions during an installation. The central section that defines the steps of the installation is the Install section.

The Install section provides an overview of the installation process. Each line of an Install section has two parts. On the left of the equals sign (=) is the key. On the right hand side, is a list of one or more section titles. The key specifies the type of the sections that are listed on the right.

To better understand this, consider the following example of an Install section.

[MyInstallSection]

Copyfiles=DataFiles, ProgramFiles

Delfiles=OldFiles

UpdateInis=NewIniInfo

AddReg=NewRegistryInfo, MoreNewRegistryInfo

DelReg=OldRegistryInfo, MoreOldRegistryInfo

In the preceding example, the CopyFiles key is given the values DataFiles and ProgramFiles. These specify two Copy Files sections in the INF file that contain the source filenames for the copying operations necessary for the installation. You can specify one or more Copy Files sections for the CopyFiles key of an Install section.

Simliarly, the Delfiles key specifies Delete Files sections that contain information relevant to file deletion operations. The UpdateInis key specifies Update INI File sections that contain information about updating entries in the INI file, and the AddReg and DelReg keys specify Add Registry and Delete Registry sections that contain information about adding or deleteing registry information.

For more information about the types of sections that can be specified in an Install section, see the INF File Format Reference.

The DestinationDirs section defines the target directory for files listed in Copy Files, Rename Files, or Delete Files sections.

The SourceDisksNames section assigns an ordinal value to each source disk. You can store additional information about the source disks, such as a human-readable description in this section.

The SourceDisksFiles section maps the source files to the ordinal values assigned in the SourceDisksNames section.

You can have multiple platform-specific SourceDisksNames and SourceDisksFiles sections in an INF file. You add a platform-specific suffix to the title of a SourceDisksNames or SourceDisksFiles section to indicate that the information listed in that section is platform-specific.

If the setup functions find platform-specific SourceDisksNames and SourceDisksFiles sections that match the user’s platform, the setup functions use the platform-specific sections. Otherwise the setup functions use the default (non-suffixed) SourceDisksNames and SourceDisksFiles sections.

For example, consider the following sections from an INF file.

[SourceDisksNames]

1=“NT CD”, \default

[SourceDisksNames.mips]

1=“NT CD”, \mips

[SourceDisksNames.alpha]

1=“NT CD”, \alpha

If the user’s machine was a MIPS-based system, the setup functions use the information listed in the section titled SourceDisksNames.mips and look for source files in the \mips directory of the specified source media.

For an Intel-based system, no platform-specific section exists, and the setup functions use the information listed in SourceDisksNames and look for source files in the \default directory.

The Strings section maps strings keys, values used as place-holders in an INF file and enclosed by percent signs (%), to the printable strings they represent. You can use strings keys as placeholders in an INF file for information that changes frequently or needs to be localized.


INF File Format Reference

The following sections describe the syntax and meaning of the items used in each type of INF file section. INF files must follow these general rules:

•	Sections begin with the section name enclosed in brackets.

•	A Version section must be included in any INF file formatted for Windows 95 and Windows NT 4.0. The Version section contains information about the INF file itself.

•	Values may be expressed as replaceable strings using the form %strkey%. To use a % character in the string, use %%. The strkey must be defined in a Strings section of the INF file.

The following INF sections can be used with the setup functions to create an installation application. For information about INF sections used to install device drivers see the DDK Programmer’s Guide.

Add Registry

Copy Files

Delete Registry

Delete Files

DestinationDirs

EventLog Install

INI File to Registry

Install

Rename Files

Service Install

Services

SourceDisksFiles

SourceDisksNames

Strings

Update INI Fields

Update INI File

Version


Add Registry

The Add Registry section adds subkeys or value names to the registry, optionally setting the value. The add-registry-section name must appear in an AddReg item in an Install section.

[add-registry-section]

reg-root-string, [subkey], [value-name], [flags], [value]

[reg-root-string, [subkey], [value-name], [flags], [value]]

.

.

.

reg-root-string

Registry root name. This parameter can be one of the following values.

HKCR	Same as HKEY_CLASSES_ROOT.
HKCU	Same as HKEY_CURRENT_USER.
HKLM	Same as HKEY_LOCAL_MACHINE.
HKU	Same as HKEY_USERS.
HKR	Relative to the key passed into SetupInstallFromInfSection.
subkey

Optional. Identifies the subkey to set. Has the form key1\key2\key3....

value-name

Optional. Identifies the value name for the subkey. For string type, if the value-name parameter is left empty, the value of the subkey is set to the default value for that registry entry.

flags

Optional. Establishes the value data type and the AddReg item action. The flag value is a bitmap where the low word contains basic flags that define the general data type and AddReg item action. The high word contains values that more specifically identify the data type of the registry value. The high word is ignored by the 16-bit Windows 95 setup functions in SETUPX.DLL. The flags are defined as follows:

Value	Meaning
FLG_ADDREG_BINVALUETYPE	The value is “raw” data.
FLG_ADDREG_NOCLOBBER	Do not overwrite the registry key if it already exists.
FLG_ADDREG_DELVAL	Delete the value from the registry.
FLG_ADDREG_APPEND	Append a value to an existing value. This flag is currently supported only for REG_MULTI_SZ values.
FLG_ADDREG_TYPE_MASK	Mask.
FLG_ADDREG_TYPE_SZ	Registry data type REG_SZ.
FLG_ADDREG_TYPE_MULTI_SZ	Registry data type REG_MULTI_SZ.
FLG_ADDREG_TYPE_EXPAND_SZ	Registry data type REG_EXPAND_SZ.
FLG_ADDREG_TYPE_BINARY	Registry data type REG_BINARY.
FLG_ADDREG_TYPE_DWORD	Registry data type REG_DWORD.
FLG_ADDREG_TYPE_NONE	Registry data type REG_NONE.
Bit 0 of the flag distinguishes between character and binary data as it does in the Windows 95 setup functions, thus a Windows 95 installation program will see the extended data types as REG_SZ or REG_BINARY. To allow REG_DWORD entries to be compatible with both operating systems, the following formats are supported.

•	Non compatible format. If compatibility with Windows 95 setup functions is not required, a REG_DWORD entry can contain a single data value field. This value can be prefixed with a sign and can be either decimal or hexadecimal. For example:

HKLM,"Software\Microsoft\Windows NT\CurrentVersion\FontDPI","LogPixels",0x10001,120

•	Windows 95-compatible format. If compatibility with Windows 95 setup functions is required, the data of a FLG_ADDREG_TYPE_DWORD entry must be formatted like REG_BINARY. The Windows NT setup functions recognize a REG_DWORD line with exactly four data elements as compatible with Windows 95. The setup functions interpret the four data elements as one DWORD. Hexadecimal number fields are only supported by the Windows 95 setup functions as members of a REG_BINARY data list, in which case the data is assumed to be in hexadecimal format (the 0x prefix must not be used). The previously listed example can be written in Windows 95-compatible format as follows:

HKLM,"Software\Microsoft\Windows NT\CurrentVersion\FontDPI","LogPixels", 65537,78,0,0,0

To represent a number with a data type other than the predefined REG_* types, you can specify the type number in the flag's high word and specify binary type in its low word. You must enter the data in binary format, one byte per field. For example, to store 16 bytes of data with a new data type of 0x38, you would have an AddReg item as follows:

HKR,,MYValue,0x00380001,0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F

You can use this technique for any data type except REG_EXPAND_SZ, REG_MULTI_SZ, REG_NONE, and REG_SZ.

value

Optional. Value to set. This parameter can be either a string or a number in hexadecimal notation. At least two fields are required; however, one can be null. Therefore, at least one comma is required when using this form.

The two items in the following example Add Registry section, which is named sermouse_EventLog_AddReg, add two value names to the registry, EventMessageFile and TypesSupported, and set the value of these names.

[sermouse_EventLog_AddReg]

HKR,,EventMessageFile,0x00020000,"%%SystemRoot%%\System32\IoLogMsg.dll;%%SystemRoot%%\System32\drivers\sermouse.sys"

HKR,,TypesSupported,0x00010001,7


Copy Files

A Copy Files section lists the files to copy from a source disk to a destination directory. The source disk and destination directory associated with each file are specified in other sections of the INF file. The file-list-section name must appear in the CopyFiles item of an Install section.

You can copy a single file with the CopyFiles item of an Install section, without building a Copy Files section. For more information, see Install Section.

[file-list-section]

destination-file-name[,source-file-name][,temporary-file-name][,flag]

[destination-file-name[,source-file-name][,temporary-file-name]][,flag]

.

.

.

destination-file-name

Name of the destination file. If no source filename is given, this is also the name of the source file.

source-file-name

Name of the source file. If the source and destination filenames for the file copy operation are the same, source-file-name is not required.

temporary-file-name

This value is ignored. The setup functions automatically generate names for temporary files.

flag

Optional. These flags can be used to control how files are copied. You must specify the actual numerical value in the INF file.

COPYFLG_WARN_IF_SKIP  (0x00000001)

Display a warning if the user tries to skip a file after an error has occurred.

COPYFLG_NOSKIP  (0x00000002)

Do not allow the user to skip copying the file.

COPYFLG_NOVERSIONCHECK  (0x00000004)

Ignore file versions and write over existing files in the destination directory.

COPYFLG_FORCE_FILE_IN_USE  (0x00000008)

Force file-in-use behavior.  Handle the file as if it was in use during the file copying operation.

COPYFLG_NO_OVERWRITE  (0x00000010)

Do not overwrite an existing file in the destination directory.

COPYFLG_NO_VERSION_DIALOG  (0x00000020)

Do not overwrite a file in the destination directory if the existing file is newer than the source file.

COPYFLG_REPLACEONLY  (0x00000040)

Copy the source file to the destination directory only if the file is already present in the destination directory.

The following example copies two files:

[CopyTheseFilesSec]

file11                        ; copies file11

file31, file32                ; copies file32 to file31

All the source filenames used in this example must be defined in a SourceDisksFiles section and the Directory identifiers that appear in the SourceDisksFiles section must be defined in a SourceDisksNames section. As an alternative, you can use a layout INF file specified in the Version section to supply this information.  A layout INF file is a file that contains a SourceDisksFiles section and a SourceDisksNames section.


Delete Registry

A Delete Registry section deletes a subkey or value name from the registry. The del-registry-section name must appear in a DelReg item in an Install section.

A Delete Registry section can contain any number of items. Each item deletes one subkey or value name from the registry.

[del-registry-section]

reg-root-string, subkey, [value-name]

[reg-root-string, subkey, [value-name]]

.

.

.

reg-root-string

Registry root name. This parameter can be one of the following values:

HKCR	Same as HKEY_CLASSES_ROOT.
HKCU	Same as HKEY_CURRENT_USER.
HKLM	Same as HKEY_LOCAL_MACHINE.
HKU	Same as HKEY_USERS.
HKR	Relative from the key passed into SetupInstallFromInfSection.
subkey

Identifies the subkey to delete. Has the form key1\key2\key3... This parameter can be expressed as a replaceable string. For example, you could use %Subkey1% where the string to replace %Subkey1% is defined in the Strings section of the INF file.

value-name

Optional. Identifies the value name for the subkey. The value-name parameter can be expressed as a replaceable string. For example, you could use %Valname1% where the string to replace %Valname1% is defined in the Strings section of the INF file.


Delete Files

A Delete Files section lists the files to be deleted. The file-list-section name must appear in the Delfiles item of an Install section.

[file-list-section]

file-name[,,,flag]

.

.

.

file-name

Identifies a file to be deleted. File-name must be defined in a SourceDisksFiles section.

flag

Optional. These flags can be used to control how files are copied. You must specify the actual numerical value in the INF file.

DELFLG_IN_USE  (0x00000001)

If the file is in use when SetupCommitFileQueue is called, queue the file to be deleted when the system is rebooted.

Note  If you do not use this flag along with a file-name parameter and the file is in use when the Delete Files section is executed, the file will not be deleted from the system.

DELFLG_IN_USE1  (0x00010000)

This flag is a high-word version of the DELFLG_IN_USE. Setting DELFLG_IN_USE1 causes the same behavior as setting DELFLG_IN_USE with the difference that it enables you to use the same section as both a Copy Files and Delete Files section without causing conflicts if the COPYFLG_WARN_IF_SKIP flag is used.

The following example deletes three files:

[DeleteOldFilesSec]

file1

file2

file3


DestinationDirs

The DestinationDirs section defines the destination directories for the operations specified in file-list sections (Copy Files, Rename Files, or Delete Files). As an option, you can specify a default destination directory for any Copy Files, Rename Files, or Delete Files sections in the INF file that are not explicitly named in the DestinationDirs section.

[DestinationDirs]

file-list-section=drid[,subdir]

.

.

.

[DefaultDestDir=drid[,subdir]]

file-list-section

Name of a Copy Files, Rename Files, or Delete Files section. Typically, you will refer to this section in the CopyFiles, RenFiles, or DelFiles line of an Install section.

drid

A directory identifier (DRID). The installer replaces a DIRID with an actual name during installation.

A DIRID has the form %dirid% where dirid is one of the predefined identifiers or an identifier defined in the DestinationDirs section. When using a DIRID, you should use the backslash in a path. For example, %11%\card.ini can be used to reference card.ini in the system32 directory.

A DIRID can be one of the following values:

-01, 0xffff	The directory from which the INF was installed.
01	SourceDrive:\path.
10	Windows directory.
11	System directory. (%windir%\system on Windows 95, %windir%\system32 on Windows NT)
12	Drivers directory.(%windir%\system32\drivers on Windows NT)
17	INF file directory.
18	Help directory.
20	Fonts directory.
21	Viewers directory.
24	Applications directory.
25	Shared directory.
30	Root directory of the boot drive.
50	%windir%\system
51	Spool directory.
52	Spool drivers directory.
53	User Profile directory.
54	Path to ntldr or OSLOADER.EXE
subdir

Name of the directory, within the directory named by drid, to be the destination directory.

The optional DefaultDestDir item provides a default destination for any CopyFiles items that use the direct copy (@filename) notation or any Copy Files, Rename Files, or Delete Files sections not specified in the DestinationDirs section. If a DefaultDestDir is not used in a DestinationDirs section, the default directory is set to drid_system.

This example sets the default directory for all the sections of the INF file to the drivers directory:

[DestinationDirs]

DefaultDestDir = 12 ; DIRID_DRIVERS


EventLog Install

The EventLog Install section adds an event message file to the registry. You can also use an EventLog Install section to remove an event message file.

[install-section-name_EventLogInstallSection]

AddReg=add-registry-section

DelReg=del-registry-section

add-registry-section

The section of the INF file that specifies subkeys to add to the registry to install the event message file.

del-registry-section

The section of the INF file that specifies subkeys to delete from the registry to remove the event message file.

The following is an example of a typical EventLog Install section:

[sermouse_EventLog_Inst]

AddReg=sermouse_EventLog_AddReg

[sermouse_EventLog_AddReg]

HKR,EventMessageFile,0x00020000,"%%SystemRoot%%\System32\IoLogMsg.dll\;%%SystemRoot%%\System32\drivers\sermouse.sys"

HKR,,TypesSupported,0x00010001,7


INI File to Registry

The INI File to Registry section moves lines or sections from an INI file to the registry, creating or replacing a registry entry under the specified key in the registry. The section name ini-to-registry-section must appear in an Ini2Reg item in an Install section of the INF file.

[ini-to-registry-section]

ini-file, ini-section, [ini-key],reg-root-string,subkey[,flags]

.

.

.

ini-file

Name of the INI file containing the key to copy. For more information about specifying the INI filename, see the Update Ini File section.

ini-section

Name of the section in the INI file containing the key to copy.

ini-key

Name of the key in the INI file to copy to the registry. If ini-key is empty, the whole section is transferred to the specified registry key.

reg-root-string

Registry root name. This parameter can be one of the following values:

HKCR	Same as HKEY_CLASSES_ROOT.
HKCU	Same as HKEY_CURRENT_USER.
HKLM	Same as HKEY_LOCAL_MACHINE.
HKU	Same as HKEY_USERS.
HKR	Relative from the key passed into SetupInstallFromInfSection.
subkey

Identifies the subkey to receive the value. Has the form key1\key2\key3...

flags

Indicates whether to delete the INI key after transfer to the registry and whether to overwrite the value in the registry if the registry key already exists. This parameter can be one of the following values.

Bit	Value	Meaning
0	0	(Default) Do not delete the INI entry from the INI file after moving the information in the entry to the registry.
0	1	Delete the INI entry from the INI file after moving the information in the entry to the registry.
1	0	(Default) If the registry subkey exists, do not replace its current value.
1	1	If the registry subkey exists, replace its current value with the value from the INI file entry.


Install

The Install section identifies the sections in the INF file that contain instructions for installing files.

[install-section-name]

LogConfig=log-config-section-name[,log-config-section-name]...

Copyfiles=file-list-section[,file-list-section]...

Renfiles=file-list-section[,file-list-section]...

Delfiles=file-list-section[,file-list-section]...

UpdateInis=update-ini-section[,update-ini-section]...

UpdateIniFields=update-inifields-section[,update-inifields-section]...

AddReg=add-registry-section[,add-registry-section]...

DelReg=del-registry-section[,del-registry-section]...

Ini2Reg=ini-to-registry-section[,ini-to-registry-section]...

Not all the types of items shown in the syntax are needed or required in an Install section. Section names must consist of printable characters. An item can contain more than one section ; each name after the first must be preceded with a comma. Items must specify the name of the corresponding section in the INF file. The only exception to this is the CopyFiles item, which need not specify a section if only one file is to be copied.

Note  You only use Log Config sections when installing a device driver. For more information, see the DDK Programmer’s Guide.

You can use a special notation in the CopyFiles item to copy a single file directly from the CopyFiles line. You can copy individual by prefixing the filename with an @ symbol. The destination for any file copied using this notation is the DefaultDestDir item, as defined in a DestinationDirs section. This is demonstrated in the following example.

[MyInstall]

CopyFiles=@MyFile.exe

By appending an extension to the name of the Install section, you can have different Install sections for different operating systems or platforms, if necessary. The Setup routines recognize the following extensions:

.Win	Windows 95
.NT	Windows NT (all platforms)
.NTx86	Windows NT (x86 only)
.NTMIPS	Windows NT (MIPS only)
.NTAlpha	Windows NT (Alpha only)
.NTPPC	Windows NT (PPC only)

The following example Install section consists of a single line that lists two Copy Files sections:

[Ser_Inst]

CopyFiles=Ser_CopyFiles, mouclass_CopyFiles

[Ser_CopyFiles]

sermouse.sys

[mouclass_CopyFiles]

mouclass.sys


Rename Files

A Rename Files section lists the names of files to be renamed. The name of the section must appear in a Renfiles item in an Install section of the INF file.

[rename-files-section-name]

new-file-name,old-file-name

.

.

.

new-file-name

New name of the file.

old-file-name

Old name of the file. The old-file-name parameter must be defined in a SourceDisksFiles section.

The following example renames file42 to file41, file52 to file51, and file62 to file61:

[RenameOldFilesSec]

file41, file42

file51, file52

file61, file62


Service Install

The Service Install section installs the service listed in the AddService entry of the Services section:

[install-section-name_ServiceInstallSection]

DisplayName=[name]

ServiceType=type-code

StartType=start-code

ErrorControl=error-control-level

ServiceBinary=path-to-service

LoadOrderGroup=[load-order-group-name]

Dependencies=+depend-on-group-name[[,depend-on-service-name]...]

StartName=[driver-object-name]

name

Optional. A friendly name for the service.

type-code

Specifies the type of driver. This can be any type allowed by the CreateService function.

start-code

Specifies when to start the driver. This parameter can be one of the following values:

SERVICE_BOOT_START (0x0)

Indicates a driver started by the operating system loader. Use this code only for drivers essential to loading the operating system.

SERVICE_SYSTEM_START (0x1)

Indicates a driver started during system initialization.

SERVICE_AUTO_START (0x2)

Indicates a driver started by the Service Control Manager during system startup.

SERVICE_DEMAND_START (0x3)

Indicates a driver that the Service Control Manager starts on demand.

SERVICE_DISABLED (0x4)

Indicates a driver that cannot be started.

error-control-level

Specifies the level of error control. This parameter can be one of the following values:

CRITICAL (0x3)

If the driver fails to load, fail the attempted startup. If the startup is not using the LastKnownGood control set, switch to LastKnownGood. If the startup attempt is using LastKnownGood, run a bug-check routine.

SEVERE (0x2)

If the startup is not using the LastKnownGood control set, switch to LastKnownGood. If the startup attempt is using LastKnownGood, continue on in case of error.

NORMAL (0x1)

If the driver fails to load or initialize, startup should proceed, but display a warning.

IGNORE (0x0)

If the driver fails to load or intialize, startup proceeds. No warning is displayed.

path

The path to the binary for the service.

load-order-group-name

Optional. Identifies the load order group of which this driver is a member. Examples of groups are: pointer, port, primary disk, and so forth.

+depend-on-group-name

Optional. Specifies a load order group on which the driver depends. The driver is started only if at least one member of the specified group has been started.

depend-on-service-name

Optional. Specifies a service that must be running before this driver is started.

driver-object-name

Optional. If type-code specifies a Kernel driver or a file system driver, this name is the Windows NT driver object name that the I/O Manager uses to load the device driver.

The following example shows a typical Service Install section:

[mouclass_Service_Inst]

DisplayName    = %mouclass.SvcDesc%

ServiceType    = 1                  ; SERVICE_KERNEL_DRIVER

StartType      = 1                  ; SERVICE_SYSTEM_START

ErrorControl   = 1                  ; SERVICE_ERROR_NORMAL

ServiceBinary  = %12%\mouclass.sys

LoadOrderGroup = Pointer Class


Services

The Services section lists services to add to a computer. You can remove services by including a DelService entry in the Services section.

[install-section-name.Services]

AddService=ServiceName,flag,service-install-section[,event-log-install-section]

DelService=ServiceName

ServiceName

The service to install or delete.

flag

Specifies how to add the service. This parameter is only used with the AddService key and can be one of the following flags.

SPSVCINST_TAGTOFRONT (0x1)

Move the service’s tag to the front of its group order list.

SPSVCINST_ASSOCSERVICE (0x2)

Associate the service in this AddService item with the device to be installed by this INF file.

service-install-section

The name of the Service Install section.

event-log-install-section

The name of the EventLog Install section.

The following example shows a typical Services section:

[Ser_Inst.Services]

AddService = sermouse, 0x00000002, sermouse_Service_Inst, sermouse_EventLog_Inst ; Port Driver

AddService = mouclass,, mouclass_Service_Inst, mouclass_EventLog_Inst

                       ; Class Driver


SourceDisksFiles

The SourceDisksFiles section names the source files used during installation and identifies the source disks that contain the files. The source disks are listed in SourceDisksNames.

In order to allow multi-platform distribution of source files, you can construct a platform-specific SourceDisksFiles section. For example, on a MIPS platform, all setup functions that use a SourceDisksFiles section will first look for a SourceDisksFiles.Mips section. If the setup functions do not find a SourceDisksFiles.Mips section, or the specified line is not found in that section, the setup functions will use the SourceDisksFiles section. This behavior affects any setup function that directly or indirectly references a SourceDisksFiles section as part of its processing.

The suffixes are not case sensitive and can be one of the following.

•	alpha

•	mips

•	ppc

•	x86

[SourceDisksFiles]

filename=disk-number[,subdir][,size]

.

.

.

filename

Name of the file on the source disk.

disk-number

Ordinal of the source disk that contains the file. This ordinal must be defined in a SourceDisksNames section, and must have a value greater than or equal to 1.

subdir

Optional parameter that specifies the subdirectory on the source disk where the file resides. If this parameter is not used, the source disk root directory is the default.

size

Optional parameter that specifies the uncompressed size of the file.

The following example SourceDisksFiles section identifies a single source file, SRS01.x86, on the disk with the ordinal of 1.

[SourceDisksFiles]

SRS01.x86 = 1


SourceDisksNames

The SourceDisksNames section identifies and names the disk that contains the source files for file copying and renaming operations. The source files are listed in SourceDisksFiles.

In order to allow multi-platform distribution of source files, you can construct a platform-specific SourceDisksNames section. For example, on a MIPS platform, all setup functions that use a SourceDisksNames section will first look for a SourceDisksNames.Mips section. If the setup functions do not find a SourceDisksNames.Mips section, or the specified line is not found in that section, the setup functions will use the SourceDisksFiles section. This behavior affects any setup function that directly or indirectly references a SourceDisksFiles section as part of its processing.

The suffixes are not case sensitive and can be one of the following.

•	alpha

•	mips

•	ppc

•	x86

[SourceDisksNames]

disk-ordinal="disk-description",disk-label,unused[,path]

.

.

.

disk-ordinal

A unique number that identifies a source disk. If there is more than one source disk, each must have a unique ordinal.

disk-description

A string or strings key describing the content or purpose of the disk. The installer displays this string to the user to identify the disk. The description must be enclosed in double quotation marks.

disk-label

The volume label of the source disk that is set when the source disk is formatted.

unused

This parameter is not used.

path

Optional parameter that specifies the absolute path to the source files. If this parameter is not used, the root directory is the default.

In the following example, the write.exe file is the same for all platforms and is located in the \common directory on the compact disc. The disk-number of 1 directs the setup functions to the \common directory, regardless of which platform the files are being installed on. The CMD.EXE file is a platform-specific file that is distributed for all platforms. The disk-number of 2 directs the setup functions to the correct directory for each platform. The HALNECMP.DLL file is specific to the MIPS platform.

[SourceDisksNames]

1 = “Windows NT CD-ROM”, Instd1,, \common

[SourceDisksNames.Alpha]

2 = “Windows NT CD-ROM”, Instd1,, \alpha

[SourceDisksNames.Mips]

2 = “Windows NT CD-ROM”, Instd1,, \mips

[SourceDisksNames.x86]

2 = “Windows NT CD-ROM”, Instd1,, \x86

[SourceDisksNames.ppc]

2 = “Windows NT CD-ROM”, Instd1,, \ppc

[SourceDisksFiles]

write.exe = 1

cmd.exe = 2

[SourceDisksFiles.Mips]

halnecmp.dll = 2


Strings

The Strings section defines one or more strings keys. A strings key is a name that represents a string of printable characters. Although the Strings section is usually the last section in an INF file, a strings key defined in a Strings section can be used anywhere in the INF file that uses the string. The installer expands the string key to the specified string and uses it for further processing. When a strings key is used, it must be enclosed by percent signs (%). To use a % character in the string, use %%.

[Strings]

strings-key=value

.

.

.

strings-key

A unique name consisting of letters and digits.

value

A string consisting of letters, digits, or other printable characters. It should be enclosed in double quotation marks if the corresponding strings key is used in a type of item that requires double quotation marks.

The Strings section simplifies translation of strings for international markets by placing all strings that can be displayed at the user interface in a single section of the INF file. Strings keys should be used whenever possible. The following example shows the Strings section of a typical INF file.

[Strings]

String0="Corporation X"

String1="Corporation X"

String2="CS2590 SCSI Adapter"


Update INI Fields

The Update INI Fields section replaces, adds, and deletes fields in the value of an INI entry. Unlike an Update INI File section, an Update INI Fields section replaces, adds, or deletes portions of a value in an INI file entry rather than the whole value. The section name, update-inifields-section-name, must appear in the UpdateIniFields item in an Install section of the INF file.

[update-inifields-section-name]

ini-file,ini-section,profile-name,[old-field],[new-field],[flags]

.

.

.

ini-file

Name of the INI file containing the entry to change. For more information about specifying the INI filename, see Update INI File Section.

ini-section

Name of the INI file section containing the entry to change.

profile-name

Name of the entry to change.

old-field

Field value to delete.

new-field

Field value to add, if it does not exist.

flags

Specifies whether to treat the old-field and new-field arguments as though they have a wild card character. The parameter specifies which separator character to use when appending a new field to an INI file entry. The flags argument can be any of the following values.

Bit	Value	Meaning
0	0	(Default) Treat the asterisk (*) character literally and not as a wild card character when matching fields .
0	1	Treat the asterisk (*) character as a wild card character when matching fields.
1	0	(Default) Use a blank ( ) as a separator when adding a new field to an entry.
1	1	Use a comma (,) as a separator when adding a new field to an entry.
The setup functions remove any comments in the INI file line because they might not be applicable after changes. When looking for fields in the line in the INI file, the setup functions search for spaces, tabs, and commas as field delimiters. However, a space is used as the separator when the new field is appended to the line.


Update INI File

The Update INI File section replaces, deletes, or adds complete entries in the INI file. The section name, update-ini-section-name, must appear in the UpdateInis item in the Install section of the INF file.

[update-ini-section-name]

ini-file,ini-section,[old-ini-entry],[new-ini-entry],[flags]

.

.

.

ini-file

The INI file containing the entry to change.

ini-section

Name of the section containing the entry to change.

old-ini-entry

Optional. Usually in the form key=value.

new-ini-entry

Optional. Usually in the form key=value. Either the key or value may specify replaceable strings. For example, either the key or value specified in the new-ini-entry parameter may be %String1%, where the string that replaces %String1% is defined in the Strings section of the INF file.

flags

Optional action flags. The flags parameter can be one of the following values:

Value	Meaning
0	Default. If old-ini-entry key is present in an INI file entry, that entry is replaced with new-ini-entry. Only the keys of the old-ini-entry parameter and the INF file entry must match; the value of each entry is ignored. To add new-ini-entry to the INI file unconditionally, set old-ini-entry to NULL. To delete old-ini-entry from the INI file unconditionally, set new-ini-entry to NULL.
1	If both key and value of old-ini-entry exist in an INI file entry, that entry is replaced with new-ini-entry. The old-ini-entry parameter and the INF file entry must match on both key and value for the replacement to be made (this is in contrast to using an action flag value of 0, where only the keys must match for the replacement to be made).
2	If the key in the old-ini-entry parameter does not exist in the INI file, no operation is performed on the INI file. If the key in the old-ini-entry parameter exists in an INI file entry and the key in the new-ini-entry parameter exists in an INI file entry, the INI file entry that matches the key in the new-ini-entry parameter is deleted, and the key of the INI file entry that matches the old-ini-entry parameter is replaced with the key in the new-ini-entry parameter. If the key in the old-ini-entry parameter exists in an INI file entry and the key in the new-ini-entry parameter does not exist in an INI file entry, an entry made up of the key in the new-ini-entry parameter and the old value is added to the INI file. The match of the old-ini-entry parameter and an INI file entry is based on key alone, not key and value.
3	Same as the flags parameter value of 2 described preceding, except the match of the old-ini-entry parameter and an entry in the INF file is based on matching both key and value, not just the key.
You can use the wild card character (*) in specifying the key and value and they will be interpreted correctly.

The ini-filename can be a string or a strings key. A strings key has the form %strkey% where strkey is defined in the Strings section in the INF file. The name must be a valid filename.

The ini-filename should include the name of the directory containing the file, but the directory name should be given as a directory identifier rather than an actual name. The installer replaces a directory identifier with an actual name during installation.

A directory identifier has the form %dirid% where dirid is one of the predefined identifiers or an identifier set by SetupSetDirectoryId. When using a directory identifier, you should use the backslash in a path. For example, you can use %11%\card.ini to reference CARD.INI in the System32 directory.

The following examples illustrate individual items in an Update INI File section:

%11%\sample.ini, Section1,, Value1=2             ; adds new entry

%11%\sample.ini, Section2, Value3=*,             ; deletes old entry

%11%\sample.ini, Section4, Value5=1, Value5=4    ; replaces old entry


Version

The Version section must be included in all INF files formatted for use with Windows 95 and Windows NT 4.0.

[Version]

Signature="signature-name"

Class=class-name

ClassGUID=GUID

Provider=INF-creator

LayoutFile=filename.inf[,filename.inf]...

signature-name

This parameter can be either $Windows NT$, $Chicago$, or $Windows 95$. If signature-name is not one of these strings, the file is not accepted as an INF file for the classes of devices recognized by Windows NT. Signature string recognition is case-insensitive.

class-name

This parameter is only used when installing device drivers. For more information see the DDK Programmer’s Guide.

GUID

This parameter is only used when installing device drivers. For more information see the DDK Programmer’s Guide.

INF-creator

Identifies the creator of the INF file. Typically, this is the name of the organization that creates the INF file.

filename.inf

The INF file that contains the SourceDisksFiles and SourceDisksNames sections required for installing this the application. This file is usually named LAYOUT.INF. If filename.inf is not specified, the SourceDisksNames and SourceDisksFiles sections must be included in the current INF file.

The following example shows a typical Version section:

[Version]

Signature="$Windows NT$"

Class=Mouse

ClassGUID={4D36E96F-E325-11CE-BFC1-08002BE10318}

Provider=%Provider%

LayoutFile=layout.inf

[Strings]

Provider="Corporation X"


Using INF Files

After you create an INF file for the installation process, the setup functions can access that information to use when copying, deleting, or renaming files and updating INIs and registry entries.

The following topics describe how to use the setup functions to retrieve information from INF files and how to perform installation operations by referencing an INF file.


Opening and Closing an INF file

Before the setup functions can access information in the INF, you must open it with a call to the SetupOpenInfFile function. This function returns a handle to the INF file.

If you do not know the name of the INF file that you need to open, you can use the SetupGetInfFileList function to obtain a list of all the INF files of a particular type (either old Windows NT 3.x script-based files, or new Windows 95- and Windows NT 4.0-style INF files, or both) in a directory.

After you open an INF file, you can append additional INF files to the opened INF file by using the SetupOpenAppendInfFile function. This is functionally similar to an include statement. When subsequent setup functions reference an open INF file, they will also be able to access any information stored in the appended files.

If you do not specify an INF file during the call to the SetupOpenAppendInfFile function, SetupOpenAppendInfFile appends the file(s) specified by the LayoutFile key in the Version section of the open INF file.

When you no longer need the information in the INF file, call the SetupCloseInfFile functionto release resources allocated during the call to SetupOpenInfFile.


Retrieving Information From an INF File

After you have a handle to an INF file, you can retrieve information from it in a variety of ways. Functions such as SetupGetInfInformation, SetupQueryInfFileInformation, and SetupQueryInfVersionInformation retrieve information about the INF file itself.

Other functions such as SetupGetSourceInfo and SetupGetTargetPath acquire information about the source files and target directories.

Low-level functions like SetupGetLineText and SetupGetStringField enable you to directly access information stored in a line or field of an INF file. These functions are used internally by the higher-level functions, but are also available should you need to access INF information at the line or field level.


Installing From an INF File

After you retrieve installation information from an INF file, there are several file-handling functions that you can use to install the files listed in an INF section. Low-level functions such as SetupInstallFile and SetupInstallFileEx install a single file.

There are also functions to handle compressed files. The SetupGetFileCompressionInfo function returns information about compressed files. This information can then be used by SetupDecompressOrCopyFile to copy and, if necessary, expand the file.

High-level functions such as SetupInstallFromInfSection, SetupInstallFilesFromInfSection, and SetupInstallServicesFromInfSection process the installation operations in an INF section. Of these, SetupInstallFromInfSection is the most versatile because it can perform any type of installation operation listed in the Install section of an INF file. This includes the registry and INI operations listed in the AddReg, DelReg, UpdateInis, or UpdateIniField lines of an Install section.

The SetupInstallFilesFromInfSection and SetupInstallServicesFromInfSection functions queue operations from an INF section to an existing file queue. For more information, see File Queues.

In contrast, the SetupInstallFromInfSection function creates and destroys its own internal queue. A common use for SetupInstallFromInfSection is to call it after all files have been successfully copied to perform the registry and INI transactions.

In addition to the functions previously listed, the Setup API includes functions that queue file installation operations, either by file, or by INF section. For more information, see File Queues.


INF File Reference

The following topics list the data types, structures, functions and notifications used with INF files.


INF File Data Types

The following data type is used with INF files.

HINF	Handle to a loaded INF file.


INF File Structures

The following structures are used with INF files.

INFCONTEXT	Positional context in an INF file.
SP_INF_INFORMATION	Information about the INF file
Note  The structure INFCONTEXT is used internally by the setup functions and must not be altered or referenced by setup applications. It is included here for informational purposes only.


INF File Functions

The following functions are used with INF files.

SetupCloseInfFile	Frees resources and closes the INF handle.
SetupDecompressOrCopyFile	Copies a file and, if necessary, decompresses it.
SetupFindFirstLine	Finds a the first line in a section of an INF file or, if a key is specified, the first line that matches that key. It updates the Line member of an INFCONTEXT structure.
SetupFindNextLine	Returns the next line in a section relative to the Line member of the specified INFCONTEXT structure.
SetupFindNextMatchLine	Returns the next line in a section relative to the Line member of the specified INFCONTEXT that matches a specified key.
SetupGetBinaryField	Retrieves data from a line whose fields are in binary format.
SetupGetFieldCount	Returns the number of fields in a line.
SetupGetFileCompressionInfo	Retrieves file compression information from an INF file.
SetupGetInfFileList	Gets a list of the types of INF files in a specified directory.
SetupGetInfInformation	Returns information about an INF file (by Line member of an INFCONTEXT or filename).
SetupGetIntField	Returns the specified integer field of a line in an INF file.
SetupGetLineByIndex	Updates the Line member of an INFCONTEXT for the line at a specified index in the specified section.
SetupGetLineCount	Returns the number of lines in the specified section.
SetupGetLineText	Retrieves the content of a specified line from an INF file.
SetupGetMultiSzField	Returns a list of strings, starting at the specified field of a line in an INF file.
SetupGetSourceFileLocation	Gets the source disk ordinal and path (relative to source root) where the source file is located
SetupGetSourceFileSize	Gets the file size for an individual source file or a Copy Files section of an INF file.
SetupGetSourceInfo	Retrieves the path, tag file, or description for a source.
SetupGetStringField	Returns the specified string field of a line in an INF file.
SetupGetTargetPath	Gets the target path for a Copy Files section in an INF file.
SetupInstallFile	Installs a file.
SetupInstallFileEx	Installs a file and returns a variable indicating whether or not the file was in use.
SetupInstallFilesFromInfSection	Queues all the files in an INF file Copy Files section.
SetupInstallFromInfSection	Performs the directives specified in an INF file Install section.
SetupInstallServicesFromInfSection	Performs service installation and deletion operations as specified in a Service Install section of an INF file.
SetupOpenAppendInfFile	Opens an INF file and append it to an existing INF handle.
SetupOpenInfFile	Opens an INF file and returns a handle to it.
SetupOpenMasterInf	Windows NT only: Opens the INF file that contains file and layout information for files shipped with Windows NT.
SetupQueryInfFileInformation	Queries an INF information structure about its associated INF filename(s).
SetupQueryInfVersionInformation	Queries an INF information structure for version information on one of its constituent INF files.
SetupSetDirectoryId	Associates a new directory identifier with a particular directory.


INF File Notifications

The following notifications are used with the SetupInstallFile, SetupInstallFileEx, and SetupInstallFromInfSection functions. For more information about the format and use of notifications, see Notifications.

SPFILENOTIFY_FILEOPDELAYED	The file is in use, and the current operation is delayed until the system is rebooted.
SPFILENOTIFY_LANGMISMATCH	The language of the current file does not match the system language.
SPFILENOTIFY_TARGETEXISTS	A copy of the specified file already exists on the target.
SPFILENOTIFY_TARGETNEWER	A newer version of the specified file exists on the target.
Note  Because SetupInstallFromInfSection creates and commits an internal file queue, it also uses the File Queue Notifications.


Disk Prompting and Error Handling

There are four setup functions that provide basic functionality to prompt the user for a new source disk, or to create error dialog boxes. The following sections describe these dialog boxes and how to use them in setup applications and in callback routines.


About Disk Prompting and Error Handling

Though the setup functions do not provide a user interface, there are four setup functions that generate dialog boxes to handle common installation situations and gather information from the user. These are: SetupPromptForDisk, SetupCopyError, SetupRenameError, and SetupDeleteError.

Callback routines can call these functions to create dialog boxes to aid in processing notifications sent by other setup functions such as SetupCommitFileQueue and SetupInstallFile.

The SetupPromptForDisk function prompts the user to insert removable media, specify a new source path, or cancel the installation. The application can offer additional options to the user, depending on the flags specified when the function is called. These include skipping the current file, or browsing for a new source path.

The three functions, SetupCopyError, SetupRenameError, and SetupDeleteError, create dialog boxes that interact with the user to gather information from the user on how to proceed when an error has occurred.

The SetupCopyError function generates a dialog box that asks the user how to recover from a copy error. The user can specify a new source path for the copy operation or cancel the installation. Depending on the flags specified during the call to SetupCopyError, the user may also be able to browse for a new source path, view error details, or skip the current file.

A dialog box that asks the user how to process errors that occur during a file renaming operation can be generated by calling SetupRenameError. With this dialog box, the user has the opportunity to retry the operation, skip the current rename operation, or abort.

The SetupDeleteError function generates a dialog box that can gather input on how the user wishes to handle an error that occurred during a file deletion operation. The user is given the options to retry the operation, skip the current delete operation, or abort.

The default queue callback routine, SetupDefaultQueueCallback, uses the previously mentioned four functions to generate parts of its user interface and to handle errors and prompt for new media.


Using Disk Prompting and Error Handling

The dialog boxes created by the setup functions, SetupPromptForDisk, SetupCopyError, SetupDeleteError, and SetupRenameError can be used by a setup application, or by callback routines. The following sections describe using the functions in an application, and their corresponding notifications.


Prompting For a Disk

To generate a dialog box that prompts the user to insert the next disk or specify a new source path, call SetupPromptForDisk. This function is used by callback routines to generate a user interface when the notification, SPFILENOTIFY_NEEDMEDIA, is sent to the callback routine.

The dialog box generated by SetupPromptForDisk gives the user the option to insert a disk, specify a new source path, or cancel the installation.

You can use flags specified during the call to SetupPromptForDisk to alter the layout and behavior of the dialog box. Using these flags, you can control whether the dialog box includes buttons that allow the user to browse for a new source path, or skip the current file. The flags also enable you to control dialog box behavior such as beeping when first displayed, and the ability be displayed as a foreground window.


Error Handling

There are three functions that generate dialog boxes to handle errors: SetupCopyError, SetupDeleteError, and SetupRenameError.

Callback routines can use these functions to generate a user interface to handle SPFILENOTIFY_COPYERROR, SPFILENOTIFY_DELETEERROR, and SPFILENOTIFY_RENAMEERROR notifications.

Each of these error-handling functions generates a dialog box that asks the user for information on how to proceed. As with SetupPromptForDisk, you can modify the dialog box’s layout and behavior by specifying flags during the function call.


Disk Prompting and Error Handling Reference

The following sections list the functions that create dialog boxes for basic disk prompting and error handling.


Disk Prompting and Error Handling Functions

The following functions provide disk prompting and an error handling user interface.

SetupCopyError	Generates a dialog box that informs the user of a copy error.
SetupDeleteError	Generates a dialog box that informs the user of a deletion error.
SetupPromptForDisk	Generates a dialog box that prompts the user for a media disk or source file location.
SetupRenameError	Generates a dialog box that informs the user of a rename error.


File Queues

The setup functions include file queue functionality. A file queue is a list of file copying, renaming, and deletion operations. These operations can be sent to the queue in any order. When the queue is committed, these operations are processed as a batch, in order of the operation type.

The following sections explain what a queue is and how to use it when creating a setup application. Also discussed is the order in which the enqueued file operations are processed as the queue commits and what notifications the queue sends to a callback routine at each stage.


About File Queues

A file queue is a list of file operations that are processed at one time. The file operations in the queue may be copy, rename, or delete operations. The file queue organizes file operations by type, creating copy, rename, and delete subqueues.

These operations may be sent to the queue in any order, and the enqueueing process need not be contiguous.  When the queue is committed, the SetupCommitFileQueue function performs file operations in order of the operation type.

Typically, all of the file operations necessary for an entire installation are queued to the file queue, and then processed in a single batch when the queue is committed.

One advantage of queueing file operations over installing files section-by-section from an INF file is that you can streamline the installation process. Instead of having to obtain information from the user for each section to be installed, you can obtain installation information from the user for all the files to be installed while building the queue. This frees the user to pursue other activities while the time-intensive copy operations are processed by the SetupCommitFileQueue function.

Another advantage of file queues is that you can track the progress of the installation as a whole. When installing section-by-section from an INF file, progress indicators such as progress bars can track only the current INF section. When the next section is installed, the progress bar starts over. With a queue, the total number of files to be processed during the entire installation is known before the queue is committed, and thus, a progress bar can be generated to track the entire installation.


Order of Queue Commitment

When the SetupCommitFileQueue function commits the file queue, it processes the file operations in the following order: file deletion operations, then file renaming operations, and finally, file copying operations. The following figure illustrates the life cycle of a queue’s commitment process.

start the queue

    start the delete subqueue
        start a file delete operation        < - - repeat for each
        finish a file delete operation       < - - queued file delete
    finish the delete subqueue

    start the rename subqueue
        start a file rename operation        < - - repeat for each
        finish a file rename operation       < - - queued file rename
    finish the rename subqueue

    start the copy subqueue
        start a file copy operation          < - - repeat for each
        finish a file copy operation         < - - queued file copy
    finish the copy subqueue
finish the queue

At each step, or if an error occurs, the SetupCommitFileQueue function sends a notification to the callback routine. The callback routine can use the information sent by the queue to track the installation progress and, if necessary, interact with the user.

For example, if a file copy operation needed a source file that was not available at the current path, SetupCommitFileQueue would send a SPFILENOTIFY_NEEDMEDIA notification to the callback routine, along with information about the file and media required. The callback routine could use this information to generate a dialog box that prompts the user to insert the next disk by calling SetupPromptForDisk

A default queue callback routine, SetupDefaultQueueCallback, is included with the Setup API. This routine handles queue notifications and generates error dialog boxes and progress bars for the installation. You can use the default queue callback routine as it is, or write a filter callback routine to handle a subset of the notifications and pass the others on to the default queue callback routine.

If none of the functionality of the callback routine suits your needs, you can write a self-contained custom callback routine that does not call the default queue callback routine.

For more information about queue callback routines, see Default Queue Callback Routine, and Creating a Custom Queue Callback Routine.


Queue Notifications

After a queue is committed by calling SetupCommitFileQueue, it will begin to process the queued operations. At each step, the queue sends a notification to the callback routine specified in the call to SetupCommitFileQueue.

Following is the syntax that SetupCommitFileQueue uses to send a notification to the callback routine.

MsgHandler(          //the specified callback routine
    Context,         //context used by the callback routine
    Notification,    //queue notification code
    Param1,          //additional notification information
    Param2	           //additional notification information
);

The values of Param1 and Param2 contain additional information relevant to the notification being sent to the callback routine. Each notification, its Param1 and Param2 values, and how the default queue callback routine handles that notification, is described in detail in File Queue Notifications.


Using File Queues

The following sections describe how to use the setup functions to create a queue, add file operations to a queue, and commit the queue.

These sections also describe how the setup functions process the platform-specific sections of an INF file and how to override this functionality.


Opening and Closing a Queue

Before you can queue file operations, you must open a file queue. Calling the SetupOpenFileQueue function returns a handle to a queue file. This handle is used by subsequent queue functions to reference the open queue and add operations to it or scan it.

After all the specified file operations have been queued and committed, you must call the SetupCloseFileQueue function to release resources allocated during the call to SetupOpenFileQueue.

Note  The SetupCloseFileQueue function does not commit the file queue. Any operations that are uncommitted when SetupCloseFileQueue is called will not be performed.


Queueing Files

After you have obtained a handle to a file queue by calling the SetupOpenFileQueue function, you can add file operations to the queue, either file-by-file, or by queueing all the files in an INF section.

To add a copy operation for an individual file to the file queue, call the SetupQueueCopy function. If you want to queue a file copy operation using the default source media and target destinations specified in an INF file, you can call the SetupQueueDefaultCopy function.

You can add an individual file delete or rename operation to the open file queue, by calling the SetupQueueDelete or SetupQueueRename function.


Queueing an INF Section

In addition to queueing file operations individually, you can also queue all the files listed in an INF section.

You can queue all the files listed in a Copy Files section of an INF file by calling SetupQueueCopySection. For this function to be successful, the Copy Files section must be in the proper format and the INF file, or one of its appended files, must contain the SourceDisksFiles and SourceDisksNames sections.

Similarly, if you want to delete all the files specified in a Delete Files section of an INF file, you can call SetupQueueDeleteSection. To rename all the files in a Rename Files section of an INF file use SetupQueueRenameSection.


Committing a Queue

After all the desired file operations have been queued, the queue must be committed. This causes the enqueued file operations to be processed.

To commit the file queue, call the SetupCommitFileQueue function, specifying a callback routine. The callback routine will receive notifications from SetupCommitFileQueue as the file operations are processed. If you want to use the default queue callback routine, you must first initialize the necessary context by calling either SetupInitDefaultQueueCallback or SetupInitDefaultQueueCallbackEx. For more information about the default queue callback routine, see Default Queue Callback Routine.

Note  SetupCommitFileQueue should be called before the queue is closed. Any operations that are uncommitted when SetupCloseFileQueue is called will not be performed.


Platform Path Override

After a platform path override is set by a call to SetupSetPlatformPathOverride, any setup function that queues file copy operations will examine the final component of the source path. If the final component matches the name of the user’s platform, the setup function will replace it with the override string set by SetPlatformPathOverride.

For example, when installing printer drivers onto a MIPS server, you might want to install drivers for all supported platforms. Queueing the files normally would install the files specified in the MIPS-dependent sections of the INF file, with source paths such as \\root\source\mips.

To install the files for a second platform, you must call SetupSetPlatformPathOverride to set a platform override. The following example shows the specific function call to set the platform to Alpha.

test = SetupSetPlatformPathOverride(“alpha”);

After you set the platform to Alpha, file copy operations sent to the queue with a source path of \\root\source\mips would have their source path changed to \\root\source\alpha. You would repeat this process for each platform of interest.


File Queue Reference

The following sections list the data types, functions, and notifications used with file queues.


File Queue Data Types

The following data type is used with file queues.

HSPFILEQ	Handle to a file queue.


File Queue Functions

The following functions are used with file queues

SetupCloseFileQueue	Terminates the queue. Any remaining transactions are not committed.
SetupCommitFileQueue	Commits all queued transactions.
SetupOpenFileQueue	Initializes and returns a handle to the file queue.
SetupPromptReboot	Prompts the user to reboot his or her computer, if necessary.
SetupQueueCopy	Queues a file copy.
SetupQueueCopySection	Queues the files in an INF Copy Files section.
SetupQueueDefaultCopy	Queues the files in an INF Copy Files section using the default information specified in an INF file.
SetupQueueDelete	Queues a file deletion.
SetupQueueDeleteSection	Queues the files in an INF Delete Files section.
SetupQueueRename	Queues a file rename.
SetupQueueRenameSection	Queues the files in an INF Rename Files section.
SetupScanFileQueue	Scans the file queue.
SetupSetPlatformPathOverride	Sets the platform path override.


File Queue Notifications

The following notifications are used with file queues.  For more information about the format and use of notifications, see Notifications.

SPFILENOTIFY_COPYERROR	An error occurred during a file copying operation.
SPFILENOTIFY_DELETEERROR	An error occurred during a file deletion operation.
SPFILENOTIFY_ENDCOPY	A file copying operation has ended.
SPFILENOTIFY_ENDDELETE	A file deletion operation has ended.
SPFILENOTIFY_ENDQUEUE	The queue has finished committing.
SPFILENOTIFY_ENDRENAME	A file rename operation has ended.
SPFILENOTIFY_ENDSUBQUEUE	A subqueue (either copy, rename or delete) has ended.
SPFILENOTIFY_FILEOPDELAYED	The file was in use, and the current operation has been delayed until the system is rebooted.
SPFILENOTIFY_LANGMISMATCH	The language of the current operation does not match the system language.
SPFILENOTIFY_NEEDMEDIA	New source media is needed.
SPFILENOTIFY_QUEUESCAN	A node in the file queue has been scanned. (SetupScanFileQueue only)
SPFILENOTIFY_RENAMEERROR	An error occurred during a file renaming operation.
SPFILENOTIFY_STARTCOPY	A file copy operation has started.
SPFILENOTIFY_STARTDELETE	A file delete operation has started.
SPFILENOTIFY_STARTQUEUE	The queue has started to commit.
SPFILENOTIFY_STARTRENAME	A file rename operation has started.
SPFILENOTIFY_STARTSUBQUEUE	A subqueue (either copy, rename or delete) has started.
SPFILENOTIFY_TARGETEXISTS	A copy of the specified file already exists on the target.
SPFILENOTIFY_TARGETNEWER	A newer version of the specified file exists on the target.


Default Queue Callback Routine

Included with the setup functions is a default callback routine, SetupDefaultQueueCallback, that you can use to process notifications returned by SetupCommitFileQueue.

The following sections discuss the format of the default queue callback routine, using the default queue callback routine with SetupCommitFileQueue, and how to create a filter callback routine that builds on the functionality provided by the default queue callback routine.


About the Default Queue Callback Routine

The default queue callback routine handles notifications sent by SetupCommitFileQueue in a generic manner. By using the default routine, you get a ready-made user interface to create common setup dialog boxes. It is recommended that you use the default queue callback routine, both for ease of use, and to ensure a consistent appearance and behavior of dialog boxes generated during the installation.

The default callback routine requires a context structure for internal record keeping. In addition, the queue passes additional information relevant to the current notification in a set of parameters, Param1 and Param2.

For example, if the queue sends an SPFILENOTIFY_NEEDMEDIA notification to the default callback routine, Param1 points to a SOURCE_MEDIA structure that contains information about the media needed, and Param2 points to a character array that can receive new path information from the user.

The default callback routine uses this information to prompt the user to either insert the needed source media, specify a new path, skip copying the current file, or cancel the current operation. The default queue callback routine returns FILEOP_NEWPATH, FILEOP_DOIT , FILEOP_SKIP, or FILEOP_ABORT to the queue, depending on which action the user took.

For information on how the default queue callback routine handles each queue notification, see File Queue Notifications.


Creating a Custom Queue Callback Routine

In addition to using the default queue callback, you can write a custom callback routine. This function must have the same form as those pointed to by SP_FILE_CALLBACK. This is useful if you need a callback routine to handle a notification in a manner other than that provided by the default queue callback routine.

If only a small portion of the default queue callback routine’s behavior needs to be changed, you can create a custom callback routine to filter the notifications, handling only those that require special behavior and calling SetupDefaultQueueCallback for the others.

For example, if you wanted to custom-handle file delete errors, you could create a custom callback function, MyCallback. This function would intercept and process SPFILENOTIFY_DELETEERROR notifications, and call the default queue callback function for all other notifications. MyCallback returns a value for the delete error notifications. For all other notifications, MyCallback passes whatever value the default queue callback routine returned to the queue.

This flow of control is illustrated in the following diagram.

For an example of a setup application that uses a custom callback function, see the Win32 Code Samples.

Important  If the custom callback function calls the default queue callback routine, it must pass the void pointer returned by SetupInitDefaultQueueCallback or SetupInitDefaultQueueCallbackEx to the default callback routine.


Using the Default Queue Callback Routine

The default queue callback routine can be specified to handle notifications sent by SetupCommitFileQueue, or it can be called by a custom callback routine that builds on the functionality of the default queue callback routine.

The following sections explain how to initialize and terminate the context used by a default queue callback routine. The sections also describe how to use the default queue callback routine with SetupCommitFileQueue or a custom callback routine.


Initializing and Terminating the Callback Context

Before the default queue callback routine can be used, either by specifying it as the callback routine when committing a file queue, or by calling it from a custom callback routine, it must be initialized.

The SetupInitDefaultQueueCallback function builds the context structure that is used by the default queue callback routine. It returns a void pointer to that structure. This structure is essential for the default callback routine’s operation and must be passed to the callback routine. You do can this either by specifying the void pointer as the context in a call to SetupCommitFileQueue, or by specifying the void pointer as the context parameter when calling SetupDefaultQueueCallback from a custom callback routine. This context structure must not be altered or referenced by the setup application.

The SetupInitDefaultQueueCallbackEx function also initializes a context for the default queue callback routine, but it specifies a second window to receive a caller-specified progress message each time the queue sends a notification. This enables you to use the default disk prompting and error dialog boxes, and to also embed a progress bar in a second window, for example, in a page of an installation wizard.

Regardless of whether you initialized the context used by the default queue callback routine with SetupInitDefaultQueueCallback or SetupInitDefaultQueueCallbackEx, after the queued operations have finished processing, call SetupTermDefaultQueueCallback to release the resources allocated in initializing the context structure.


Calling the Default Queue Callback Routine

If the default queue callback routine is initialized and specified when SetupCommitFileQueue is called, the queue calls the the default queue callback routine internally and you need do nothing more.

If you create a filter callback routine that relies on the default queue callback routine to handle a subset of the queue notifications, your filter callback routine must call SetupDefaultQueueCallback explicitly.

Important  When you call SetupDefaultQueueCallback explicitly, you must pass in the void pointer returned by either SetupInitDefaultQueueCallback or SetupInitDefaultQueueCallbackEx.

One way to do this is to create a context structure for your custom callback routine that includes as one of its members the void pointer returned by SetupInitDefaultQueueCallback or SetupInitDefaultQueueCallbackEx.


Default Queue Callback Routine Reference

The following sections list the functions used with the default queue callback routine.


Default Queue Callback Routine Functions

The following functions are used with the default queue callback routine.

SetupDefaultQueueCallback	The default queue callback routine.
SetupInitDefaultQueueCallback	Initializes context information needed by the default queue callback routine.
SetupInitDefaultQueueCallbackEx	Initializes context information needed by the default queue callback routine and specifies an alternate window to display progress messages.
SetupTermDefaultQueueCallback	Releases resources allocated by SetupInitDefaultQueueCallback and SetupInitDefaultQueueCallbackEx.


Cabinet Files

Cabinet files provide a compact and organized way to store compressed source files. The following topics describe what cabinet files are and how they are processed by the setup functions.


About Cabinet Files

A cabinet is a single file, usually suffixed with .CAB, that stores compressed files in a file library. A compressed file can be spread over several cabinet files. During installation, the setup application decompresses the files stored in a cabinet and copies them to the user’s system.

If cabinet files are used, the setup functions use the name of the cabinet as the tag file for the source disk it resides on.


Using Cabinet Files

The setup functions handle cabinets internally. To explicitly enumerate and extract files from a cabinet, you can call the SetupIterateCabinet function.

The following topic describes the cabinet processing internal to the setup functions and how to use SetupIterateCabinet.

Also discussed are the notifications sent by SetupIterateCabinet and the required format of a cabinet callback routine to process those notifications.


Extracting Files from Cabinets

You can extract files from a cabinet in two ways. The first and simplest way is to take advantage of the automatic cabinet processing built into the setup functions.

The installation functions, such as SetupCommitFileQueue, SetupInstallFile, and SetupInstallFromInfSection, check the compression on each file. If the file is in a cabinet, the functions first search for a file of that name outside the cabinet. If found, the functions install the external file, ignoring the file inside the cabinet. This enables you to update a single file inside the cabinet without rebuilding the cabinet.

The setup functions also track which files in a cabinet have been retrieved, so that a file is extracted only once, even if it is installed several times.

The second way to extract files from a cabinet is by using SetupIterateCabinet. This function iterates through each file in a cabinet, sending a notification to a callback routine for each file found. The callback routine then returns a value that indicates whether the file should be extracted or skipped.

Note  The Setup API does not supply a default callback routine to handle cabinet notifications. If you call SetupIterateCabinet explicitly, you must supply a callback routine to process the cabinet notifications that the function returns.


Creating a Cabinet Callback Routine

Because the Setup API does not supply a default cabinet callback routine, you need to supply a routine. The callback routine that the SetupIterateCabinet function requires must have the same form as those pointed to by SP_FILE_CALLBACK.

Following is the syntax that SetupIterateCabinet uses to send a notification to the callback routine.

MsgHandler(          //the specified callback routine
    Context,         //context used by the callback routine
    Notification,    //cabinet notification
    Param1,          //additional notification information
    Param2	           //additional notification information
);

The Context parameter is a void pointer to a context variable or structure that can be used by the callback routine to store information that needs to persist between subsequent calls to the callback routine.

This context’s implementation is specified by the callback routine, and it is never referenced or altered by SetupIterateCabinet.

The Notification parameter is an unsigned integer and will be one of the following values.

SPFILENOTIFY_FILEEXTRACTED	The file has been extracted from the cabinet.
SPFILENOTIFY_FILEINCABINET	A file is encountered in the cabinet.
SPFILENOTIFY_NEEDNEWCABINET	The current file is continued in the next cabinet.
The final two parameters, Param1 and Param2, are also unsigned integers and contain additional information relevant to the notification. For more information about the notifications sent by SetupIterateCabinet, see Cabinet File Notifications.

A SP_FILE_NOTIFY_CALLBACK routine returns an unsigned integer. The cabinet callback routine should return one of the following values depending on the notification.

For the SPFILENOTIFY_FILEINCABINET notification, SetupIterateCabinet expects one of the following values to be returned by the callback routine.

FILEOP_ABORT	Abort cabinet processing.
FILEOP_DOIT	Extract the current file.
FILEOP_SKIP	Skip the current file.
For SPFILENOTIFY_NEEDNEWCABINET and SPFILENOTIFY_FILEEXTRACTED notifications, SetupIterateCabient expects one of the following values to be returned by the callback routine.

NO_ERROR	No error was encountered, continue processing the cabinet.
ERROR_XXX	An error of the specified type occurred. The SetupIterateCabinet function will return FALSE, and the specified error code will be returned by a call to GetLastError.
If the callback routine returns FILEOP_DOIT, the routine must also provide a full target path. For more information see SPFILENOTIFY_FILEINCABINET.


Cabinet File Reference

The following sections list the structures, functions, and notifications used with cabinet files.


Cabinet File Structures

The following structures are used with cabinets.

CABINET_INFO	Cabinet file information.
FILE_IN_CABINET_INFO	Information about a file in a cabinet.


Cabinet File Functions

The following function is used with cabinets.

SetupIterateCabinet	Returns a notification for each file stored in a cabinet file.


Cabinet File Notifications

The following notifications are sent by SetupIterateCabinet. For more information about the format and use of notifications, see Notifications.

SPFILENOTIFY_FILEEXTRACTED	The file has been extracted from the cabinet.
SPFILENOTIFY_FILEINCABINET	A file is encountered in the cabinet, does the application want to extract it?
SPFILENOTIFY_NEEDNEWCABINET	The current file is continued in the next cabinet.


MRU Source List

The Setup API provides functions that store the most recently used (MRU) source directories. This information is stored on the user’s system and can be accessed by subsequent installations.

The following topics describe the MRU source list and how to use the setup functions to open, modify, scan, and close it.


About the MRU Source List

The most recently used (MRU) source list remains resident on the user’s system. The setup functions internally handle the creation of new source lists and their location on the user’s machine. The setup functions use this list to store information about source paths used in previous installations.

You can use this information when prompting the user for a source path. For example, you could create a drop-down list of the network connections used as source paths in previous installations.

Depending on your permissions, you can create a user list, one that is specific to a particular user, or a system list, one that is the same for all users. In addition to system and user source lists you can create a temporary source list that is discarded when the setup application exits.


Using the MRU Source List

The SetupSetSourceList function will open or create a source list on the user’s system. You can specify to set the user list, the system list, a combination of the user and system lists, or a temporary list as the MRU source list. If a temporary list is used, it will be the only list available to the setup application until SetupCancelTemporarySourceList is called, or SetupSetSourceList is called a second time.

After a list is set, you can query the source list by using SetupQuerySourceList to obtain an array of the source paths. When the source list array is no longer needed, you must call the SetupFreeSourceList function to free the resources allocated by SetupQuerySourceList.

To add a path to a source list, either one that is resident on the user’s system, or a temporary list, call SetupAddToSourceList. If the source list specified is not temporary, that source will remain on the user’s system and is accessible to subsequent installations.

To remove a path from the source path, call the SetupRemoveFromSourceList function.


MRU Source List Reference

The following topics list the setup functions that provide MRU functionality.


MRU Source Functions

The following functions are used with MRU source file lists.

SetupAddToSourceList	Adds an entry to a source list.
SetupCancelTemporarySourceList	Cancels any temporary list or no-browse behavior and reestablishes standard list behavior.
SetupFreeSourceList	Frees resources allocated to a source list.
SetupQuerySourceList	Queries the current list of installation sources.
SetupRemoveFromSourceList	Removes an entry from an installation source list.
SetupSetSourceList	Sets the installation source list to the system MRU list, the user MRU list, or a temporary list.


File Log

The file log is resident on the user’s system and stores information about the files copied during an installation. The following topics describe the types of file logs and how to use the setup functions to open, modify, and close them.


About the File Log

A file log records information about the files copied to a system during an installation. It can be used for emergency repair or as a diagnostic tool.

The file used to log file installations can either be the system log, the file used by the system to store a record of the files installed with the Windows NT operating system, or any other file log that you specify.


Using the File Log

Before you can use a file log, you must call SetupInitializeFileLog to open or create it. When you call this function, you can specify flags to create or overwrite a file log, open the system log, or open a file log as read-only.

After SetupInitializeFileLog returns a handle to a file log, you can add an entry by calling SetupLogFile, delete an entry by calling SetupRemoveFileLogEntry, or retrieve information about a particular file in a file log by calling SetupQueryFileLog.

When the file log is no longer needed, SetupTerminateFileLog should be called to release the resources allocated during the call to SetupInitializeFileLog.


File Log Reference

The following sections lists the setup functions that provide file log functionality.


File Log Functions

The following functions are used with file logs.

SetupInitializeFileLog	Initializes a log file for use.
SetupLogFile	Adds an entry to the log file.
SetupQueryFileLog	Retrieves information from a log file.
SetupRemoveFileLogEntry	Removes an entry from a log file.
SetupTerminateFileLog	Releases resources allocated to a log file.


Creating Setup Applications

After you create an INF file, you will typically write the source code for your setup application. You call the setup functions from your setup application to perform many installation operations.

The following sections discuss the steps of a typical installation, and provide specific examples of how you can use the setup functions to perform stage of the installation.

For an example of a complete setup application that implements the following setup procedure, see DOINST.C, included with the Win32 Code Samples.


Steps of an Installation Program

The following list outlines one way to use setup functions to create a setup application. You can use this example as a starting point, or develop your own installation algorithm.

Each step is described in detail in following topics.

Initialization

•	Open the INF and, if appropriate, append other INF files.

•	Extract file information from the INF file.

•	Gather setup information from the user.

•	Create a queue.

Install files

•	Commit the queue, specifying a callback routine.

•	Update registry information.

Clean up

•	Close the file queue and INF.

•	Release any other system resources and end the program.


Opening the INF File

You must use the SetupOpenInfFile function to open the INF file before you can retrieve information from it, or append other INF files to it.

The following example opens an INF file.

HINF MyInf;                //variable to hold the INF handle

PUINT ErrorLine;           //variable to point to errors returned

BOOL test;                 //variable to receive function success

MyInf = SetupOpenInfFile (

      szInfFileName,       //the filename of the inf file to open

      NULL,                //optional class information

      INF_STYLE_WIN4,      //the inf style

      ErrorLine            //line number of the syntax error

);

In the preceding example, MyInf is the handle returned by SetupOpenInfFile to the opened INF file. The parameter szInfFileName specifies the name of the INF file to open. The INF class is specified as NULL. This indicates that the Class key should be ignored. The INF_STYLE_WIN4 value specifies that the INF file is formatted in the INF format used with Windows 95 and Windows NT 4.0. The ErrorLine parameter is a pointer to a variable that receives the line number of an error that the SetupOpenInfFile function generates.

After an INF file is opened, you can call the SetupOpenAppendInfFile function to append a file to the open INF file. To append several files, repeat this process.

If you call the SetupOpenAppendInfFile function and the filename passed to it is NULL, then the function will search the Version section of the open INF file (and any appended INF files) for a LayoutFile key. If the function finds a key, it will append the file specified by that key (usually LAYOUT.INF). When multiple INF files have been combined, SetupOpenAppendInfFile starts with the last appended INF file when it searches for a Version section.

The following example appends the szSecondInfFileName file to the open file, szInfFileName.

test = SetupOpenAppendInfFile (

      szSecondInfFileName,    //name of the inf file to append
                              //to the open inf file, if NULL,
                              //the fn searches for the LayoutInf
                              //key in the version section, and
                              //appends the file specified there.

      MyInf,                  //handle of the open inf file

      ErrorLine               //pointer to an unsigned integer that
                              //receives error information

);

In the example, szSecondInfFileName is the name of the file to append to the open INF file. MyInf is the handle to the open INF file returned by the previous call to the SetupOpenInfFile function. The parameter ErrorLine points to a variable that will receive any error information generated by the SetupOpenAppendInfFile function.


Extracting File Information from the INF file

After the INF file is opened, you can gather information from it to build the user interface, or to direct the installation process. The setup functions provide several levels of functionality for gathering information from an INF file.

To gather information…	Use these functions…
About the INF file	SetupGetInfInformation
	SetupQueryInfFileInformation
	SetupQueryInfVersionInformation.
About source and target files	SetupGetSourceFileLocation
	SetupGetSourceFileSize
	SetupGetTargetPath
	SetupGetSourceInfo
From a line of an INF file	SetupGetLineText
	SetupFindNextLine
	SetupFindNextMatchLine
	SetupGetLineByIndex
	SetupFindFirstLine
From a field of a line in an INF file	SetupGetStringField
	SetupGetIntField,
	SetupGetBinaryField
	SetupGetMultiSzField
The following example uses the SetupGetSourceInfo function to retrieve the human-readable description of a source media from an INF file.

test = SetupGetSourceInfo (

     MyInf,                   \\Handle to the INF file to access

     SourceId,                \\Id of the source media

     SRCINFO_DESCRIPTION,     \\which information to retrieve

     Buffer,                  \\a pointer to the buffer to

                              \\  receive the information

     MaxBufSize,              \\the size allocated for the buffer

     &BufSize                 \\buffer size actually needed

);

In the example, MyInf is the handle to the open INF file. SourceId is the identifier for a specific source media. The value SRCINFO_DESCRIPTION specifies that the SetupGetSourceInfo function should retrieve the source media description. Buffer points to a string that will receive the description, MaxBufSize indicates the resources allocated to the buffer, and BufSize indicates the resources necessary to store the buffer.

If BufSize is greater than MaxBufSize, the function will return FALSE, and a subsequent call to GetLastError will return ERROR_INSUFFICIENT_BUFFER.


Gathering Setup Information from the User

It is highly recommended that your setup application include a user interface that acquires any necessary information from the user. This functionality is not supplied by the setup functions and must be implemented by your setup application, usually in the form of an installation wizard.


Creating a Queue and Queueing File Operations

Queuing the file operations is useful because it enables you to process the installation as a whole, instead of by INF section.

To create a file queue, declare a variable to store the queue handle, then call the SetupOpenFileQueue function.

HSPFILEQ MyQueue;                   \\variable to hold the queue
                                    \\handle

MyQueue = SetupOpenFileQueue();     \\create the queue

In the example, MyQueue is the handle to the queue created by SetupOpenFileQueue.

After the queue is created, you can queue copy, rename, and delete operations, as well as scan the file queue to verify enqueued operations.

To add single file operations to the queue, use the SetupQueueCopy, SetupQueueRename, and SetupQueueDelete functions.

All the file operations listed in a Copy Files, Delete Files, or Rename Files section can be added to the queue by using SetupQueueCopySection, SetupQueueDeleteSection, or SetupQueueRenameSection, respectively.

Another way to queue all the files in a Copy Files section of an INF is to use the function, SetupInstallFilesFromInfSection.

The following example uses the SetupQueueCopySection function to enqueue copy operations for all the files listed in a Copy Files section of an INF file.

test = SetupQueueCopySection(

     MyQueue,                  \\Handle of the open queue

     “A:\”,                    \\Source root path

     MyInf,                    \\Inf containing the source info

     NULL,                     \\specifies that MyInf contains

                               \\  the section to copy as well

     MySection,                \\the name of the section to queue

                               \\flags specifying the copy style

     SP_COPY_NO_SKIP | SP_COPY_NO_BROWSE,

);

In the example, MyQueue is the queue to add copy operations to, “A:\” specifies the path to the source, and MyInf is the handle to the open INF file. The parameter ListInfHandle is set to NULL, indicating that the section for copying is in MyInf. MySection is the section in MyInf containing the files to queue for copying.

The flags SP_COPY_NO_SKIP and SP_COPY_NO_BROWSE have been combined using an OR operator to indicate that the user should not be offered options to skip or browse for files if errors occur.


Committing the Queue

If the default callback function is going to be called during the queue commitment, the context for it must be initialized using the SetupInitDefaultQueueCallback or SetupInitDefaultQueueCallbackEx functions. If you are using a custom callback function that never calls the default callback function, this step is not necessary.

PVOID Context;          \\variable to store the context returned

                        \\initialize the context

Context = SetupInitDefaultQueueCallback( OwnerWindow );

In the example, OwnerWindow is the handle to the window that is to become the parent window of any dialog boxes that the default callback function generates.

After the queue is built and the callback function that will process queue notifications has been initialized, you can call SetupCommitFileQueue to commit the operations that have been enqueued.

The following example uses SetupCommitFileQueue to commit the queue using the default callback routine.

test = SetupCommitFileQueue (

     OwnerWindow,          //window that will own dialog boxes

                           //created by the callback routine

     MyQueue,              //the queue to commit

                           //use the default callback routine
     SetupDefaultQueueCallback

     Context               //context information that will be
                           //  used by the callback routine

);

In the preceding example, MyQueue is the queue to commit, OwnerWindow is the window that will own any dialog boxes created by the default callback routine, SetupDefaultQueueCallback specifies that the default callback function will be used, and Context is a pointer to the structure returned by the previous call to SetupInitDefaultQueueCallback.


Updating Registry Information

After the queue has successfully committed, you will need to update registry information for the product you are installing. It is reccommended that you wait until all necessary file copy operations have been successfully completed before altering registry information.

One way to update the registry is to call SetupInstallFromInfSection with the SPINST_INIFILES, SPINST_REGISTRY, or SPINST_INI2REG flags specified. These flags can be combined in one call to SetupInstallFromInfSection.

The following example uses SPINST_ALL^SPINST_FILES to indicate that the function should process all of the listed operations except file operations. Since only INI, registry, and file operations are listed in the Install section, this is a shorthand method of specifying the function should process all INI and registry operations.

The following example shows how to install registry information using the SetupInstallFromINFSection function.

Test = SetupInstallFromINFSection (

     NULL,                     \\Window to own any dialog boxes
                               \\  created

     MyInf,                    \\INF file containing the section

     MySection,                \\the section to install

     SPINST_ALL ^ SPINST_FILES,\\which installation operations

                               \\  to process

     NULL,                     \\the relative root key

     “A:\”,                    \\the source root path

     0,                        \\copy style

     NULL,                     \\Message handler routine

     NULL,                     \\Context

     NULL,                     \\Device info set

     NULL                      \\device info data

);

In the example, OwnerWindow is NULL because only file operations generate dialog boxes, and thus a parent window is not needed. MyInf is the INF file containing the section to process. The parameter, MySection, specifies the section to be installed. The combined flags, SPINST_ALL ^ SPINST_FILES, specify which installation operations to process, in this case, all operations except file operations. The source root path is specified as “A:\”.

Since no copy operations are being processed, the CopyFlags, MsgHandler, Context, DeviceInfoSet, and DeviceInfoData parameters are not specified.


Closing the File Queue and INF File

After the queue has finished committing its operations, it should be closed so that resources allocated to the queue can be released.

SetupCloseFileQueue(MyQueue);             //close file queue

Where MyQueue is the handle to the queue created by SetupOpenFileQueue.

If a default context was initiated for use by the default callback routine, it should also be terminated by calling SetupTermDefaultQueueCallback.

SetupTermDefaultQueueCallback(Context);   //release default context
                                          //  resources

In the example Context is a pointer to the structure returned by the SetupInitDefaultQueueCallback function.

When access to the INF information is no longer needed, call the SetupCloseInfFile function to free system resources.

SetupCloseInfFile(MyInf);                 //close inf file

MyInf is the handle to the open INF file returned by the SetupOpenInfFile function.


Releasing Other System Resources

If a source list or log file was used, resources should be released by calling SetupFreeSourceList or SetupTerminateFileLog.


Reference

The following sections describe in detail the data types, structures, functions, and notifications of the Setup API.


Data Types

The following data types are used by the setup functions.

HINF	Handle to a loaded INF file.
HSPFILELOG	Handle to a log file.
HSPFILEQ	Handle to a setup file queue.
SP_FILE_CALLBACK	Pointer to a callback routine.


SP_FILE_CALLBACK [New - Windows NT]
SP_FILE_CALLBACK

[New - Windows NT]

The SP_FILE_CALLBACK data type is a pointer to a callback routine that has the format expected by the setup functions. For information on how to build a callback routine, see Notifications, Creating a Custom Queue Callback Routine, and Creating a Cabinet Callback Routine.

typedef UINT (*PSP_FILE_CALLBACK)(
    PVOID Context,          //context used by the callback routine
    UINT Notification,      //notification sent to callback routine
    UINT Param1,            //additional notification information
    UINT Param2             //additional notification information

);

Members

Context

Supplies context information about the queue notification being returned to the callback function.

Notification

Specifies the occurrence that triggered the call to the callback function.

Param1

Specifies additional notification information; the value is dependent on which notification is being returned.

Param2

Specifies additional notification information; the value is dependent on which notification is being returned.

See Also

SetupCommitFileQueue, SetupInstallFile, SetupInstallFileEx, SetupInstallFromInfSection, SetupIterateCabinet


Structures

The following structures are used by the setup functions.

CABINET_INFO
FILE_IN_CABINET_INFO
FILEPATHS
INFCONTEXT
SOURCE_MEDIA
SP_INF_INFORMATION


CABINET_INFO [New - Windows NT]
CABINET_INFO

[New - Windows NT]

The CABINET_INFO structure stores information about a cabinet file. The SetupIterateCabinet function specifies this structure as a parameter when it sends a SPFILENOTIFY_NEEDNEWCABINET notification to the cabinet callback routine.

typedef struct _CABINET_INFO {
    PCTSTR CabinetPath;
    PCTSTR CabinetFile;
    PCTSTR DiskName;
    USHORT SetId;
    USHORT CabinetNumber;
} CABINET_INFO, *PCABINET_INFO;

Members

CabinetPath

The path to the cabinet file.

CabinetFile

The name of the cabinet file.

DiskName

The name of the source media that contains the cabinet file.

SetId

The identifier of the current set. This number is generated by the software that builds the cabinet.

CabinetNumber

The number of the cabinet. This number is generated by the software that builds the cabinet and is generally a 0- or 1-based index indicating the ordinal of the position of the cabinet within a set.

See Also

SPFILENOTIFY_NEEDNEWCABINET, FILE_IN_CABINET_INFO


FILE_IN_CABINET_INFO [New - Windows NT]
FILE_IN_CABINET_INFO

[New - Windows NT]

The FILE_IN_CABINET_INFO structure provides information about a file found in the cabinet. The SetupIterateCabinet function sends this structure as one of the parameters when it sends a SPFILENOTIFY_FILEINCABINET notification to the cabinet callback routine.

typedef struct _FILE_IN_CABINET_INFO {
    PCTSTR NameInCabinet;
    DWORD  FileSize;
    DWORD  Win32Error;
    WORD   DosDate;
    WORD   DosTime;
    WORD   DosAttribs;
    TCHAR  FullTargetName[MAX_PATH];
} FILE_IN_CABINET_INFO, *PFILE_IN_CABINET_INFO;

Members

NameInCabinet

Specifies the filename as it exists within the cabinet file.

FileSize

Specifies the uncompressed size of the file in the cabinet.

Win32Error

If applicable, the Win32 error value associated with the file in the cabinet.

DosDate

The date that the file was last saved.

DosTime

The MS-DOS timestamp of the file in the cabinet.

DosAttribs

The attributes of the file in the cabinet.

FullTargetName[MAX_PATH]

The target path and filename.

See Also

CABINET_INFO


FILEPATHS [New - Windows NT]
FILEPATHS

[New - Windows NT]

The FILEPATHS structure stores source and target path information. The setup functions send the FILEPATHS structure as a parameter in several of the notifications sent to callback routines. For more information, see Notifications.

typedef struct _FILEPATHS {
    PCTSTR Target;
    PCTSTR Source;
    UINT   Win32Error;
    DWORD  Flags;
} FILEPATHS, *PFILEPATHS;

Members

Target

The path to the target file.

Source

The path to the source file. This member is not used when the FILEPATHS structure is used with a file delete operation.

Win32Error

If an error occurs, this parameter takes the Win32 error value associated with the specified paths. If no error has occurred, it takes the value NO_ERROR.

Flags

Specifies additional information that depends on the notification sent with the FILEPATHS structure.

For SPFILENOTIFY_COPYERROR notifications, Flags specifies dialog box behavior and can be one of the following values.

SP_COPY_WARNIFSKIP

Inform the user that skipping the file may affect the installation.

SP_COPY_NOSKIP

Do not offer the user the option to skip the file.

SP_COPY_NOBROWSE

Do not offer the user the option to browse.

For SPFILENOTIFY_FILEOPDELAYED notifications, Flags specifies the type of file operation delayed and can be one of the following values.

FILEOP_DELETE	A file delete operation was delayed.
FILEOP_COPY	A file copy operation was delayed.


INFCONTEXT [New - Windows NT]
INFCONTEXT

[New - Windows NT]

The INFCONTEXT structure stores context information that functions such as SetupGetLineText use to navigate INF files.

typedef struct _INFCONTEXT {
    HINF Inf;                  //handle of the open INF file
    HINF CurrentInf;           //handle of the current INF file
    UINT Section;              //a section of the current INF file
    UINT Line;                 //a line of the INF section
} INFCONTEXT, *PINFCONTEXT;

Members

Inf

A handle to the INF file returned by SetupOpenInfFile.

CurrentInf

A pointer to the current INF file. The Inf member may point to multiple files if they were appended to the open INF file using SetupOpenAppendInfFile.

Section

Specifies a section in the current INF file.

Line

Specifies a line of the current section in the INF file.

Important  The setup functions use this structure internally and it must not be accessed or modified by applications. It is included here for informational purposes only.

See Also

SetupFindFirstLine, SetupFindNextLine, SetupFindNextMatchLine


SOURCE_MEDIA [New - Windows NT]
SOURCE_MEDIA

[New - Windows NT]

The SOURCE_MEDIA structure is used with the SPFILENOTIFY_NEEDMEDIA notification to pass source media information.

typedef struct _SOURCE_MEDIA {
    PCTSTR Reserved;
    PCTSTR Tagfile;
    PCTSTR Description;
    PCTSTR SourcePath;
    PCTSTR SourceFile;
    DWORD  Flags;
} SOURCE_MEDIA, *PSOURCE_MEDIA;

Members

Reserved

This member is not currently used.

Tagfile

This optional member specifies the tag file that can be used to identify the source media.

Description

The human-readable description of the source media.

SourcePath

The path to the source that needs the new media.

SourceFile

The source file to be retrieved from the new media.

Flags

Specifies copy style information that modifies how errors are handled. This member can be one or more of the following values:

SP_COPY_WARNIFSKIP

Inform the user that skipping the file may affect the installation.

SP_COPY_NOSKIP

Do not offer the user the option to skip the file.

SP_FLAG_CABINETCONTINUATION

The current source file is continued in another cabinet file.

SP_COPY_NOBROWSE

Do not offer the user the option to browse.

See Also

SPFILENOTIFY_NEEDMEDIA


SP_INF_INFORMATION [New - Windows NT]
SP_INF_INFORMATION

[New - Windows NT]

The SP_INF_INFORMATION structure stores information about an INF file, including the style, number of constituent INF files, and version data.

typedef struct _SP_INF_INFORMATION {
    DWORD InfStyle;            //the style of the INF file
    DWORD InfCount;            //number of constituent INF files
    BYTE  VersionData[ANYSIZE_ARRAY];
                               //array to store the INF information
} SP_INF_INFORMATION, *PSP_INF_INFORMATION;

Members

InfStyle

Specifies the style of the INF file. This member can be one of the following values.

Value	Meaning
INF_STYLE_NONE	Specifies that the style of the INF file is unrecognized or nonexistent.
INF_STYLE_OLDNT	Specifies a Windows NT 3.x style INF file.
INF_STYLE_WIN4	Specifies a Windows 95- or Windows NT-style INF file.
InfCount

Specifies the number of constituent INF files.

VersionData[ANYSIZE_ARRAY]

Stores information from the Version section of an INF file in an array of ANYSIZE_ARRAY bytes.

See Also

SetupGetInfInformation, SetupQueryInfFileInformation, SetupQueryInfVersionInformation


Functions

The following functions are used in the Setup API.

SetupAddToSourceList
SetupCancelTemporarySourceList
SetupCloseFileQueue
SetupCloseInfFile
SetupCommitFileQueue
SetupCopyError
SetupDecompressOrCopyFile
SetupDefaultQueueCallback
SetupDeleteError
SetupFindFirstLine
SetupFindNextLine
SetupFindNextMatchLine
SetupFreeSourceList
SetupGetBinaryField
SetupGetFieldCount
SetupGetFileCompressionInfo
SetupGetInfFileList
SetupGetInfInformation
SetupGetIntField
SetupGetLineByIndex
SetupGetLineCount
SetupGetLineText
SetupGetMultiSzField
SetupGetSourceFileLocation
SetupGetSourceFileSize
SetupGetSourceInfo
SetupGetStringField
SetupGetTargetPath
SetupInitDefaultQueueCallback
SetupInitDefaultQueueCallbackEx
SetupInitializeFileLog
SetupInstallFile
SetupInstallFileEx
SetupInstallFilesFromInfSection
SetupInstallFromInfSection
SetupInstallServicesFromInfSection
SetupIterateCabinet
SetupLogFile
SetupOpenAppendInfFile
SetupOpenFileQueue
SetupOpenInfFile
SetupOpenMasterInf
SetupPromptForDisk
SetupPromptReboot
SetupQueryFileLog
SetupQueryInfFileInformation
SetupQueryInfVersionInformation
SetupQuerySourceList
SetupQueueCopy
SetupQueueCopySection
SetupQueueDefaultCopy
SetupQueueDelete
SetupQueueDeleteSection
SetupQueueRename
SetupQueueRenameSection
SetupRemoveFileLogEntry
SetupRemoveFromSourceList
SetupRenameError
SetupScanFileQueue
SetupSetDirectoryId
SetupSetPlatformPathOverride
SetupSetSourceList
SetupTermDefaultQueueCallback
SetupTerminateFileLog


SetupAddToSourceList [New - Windows NT]
SetupAddToSourceList

[New - Windows NT]

The SetupAddToSourceList function appends a value to the list of installation sources for either the current user or the system. If the value already exists, it is removed first, so that duplicate entries are not created.

BOOL SetupAddToSourceList(

DWORD Flags,	// specifies a list to append to
PCTSTR Source	// the source to add to the list
);
Parameters

Flags

Specifies which list to append the source to. This parameter can be any combination of the following values:

SRCLIST_SYSTEM

Add the source to the per-system list. The caller must be an administrator.

SRCLIST_USER

Add the source to the per-user list.

SRCLIST_SYSIFADMIN

If the caller is an administrator, the source is added to the per-system list; if the caller is not a member of the administrators local group, the source is added to the per-user list for the current user.

Note If a temporary list is currently in use (see SetupSetSourceList), the preceding flags are ignored and the source is added to the temporary list.

SRCLIST_APPEND

Add the source to the end of the list. If this flag is not specified, the source is added to the beginning of the list.

Source

Pointer to the source to add to the list.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

See Also

SetupRemoveFromSourceList, SetupSetSourceList


SetupCancelTemporarySourceList [New - Windows NT]
SetupCancelTemporarySourceList

[New - Windows NT]

The SetupCancelTemporarySourceList function cancels any temporary list and no-browse behavior and reestablishes standard list behavior.

BOOL SetupCancelTemporarySourceList(

VOID	// takes no parameters
);
Parameters

None.

Return Values

If a temporary list was in effect, the return value is TRUE. Otherwise, the return value is FALSE.

See Also

SetupSetSourceList


SetupCloseFileQueue [New - Windows NT]
SetupCloseFileQueue

[New - Windows NT]

The SetupCloseFileQueue function destroys a setup file queue.

VOID SetupCloseFileQueue(

HSPFILEQ QueueHandle	// handle to the file queue to close
);
Parameters

QueueHandle

Handle to an open setup file queue.

Remarks

The SetupCloseFileQueue function does not flush the queue; pending operations are not performed. To commit a file queue before closing it call SetupCommitFileQueue.

See Also

SetupCommitFileQueue, SetupInstallFile, SetupQueueCopy, SetupQueueDefaultCopy, SetupQueueDelete, SetupQueueRename


SetupCloseInfFile [New - Windows NT]
SetupCloseInfFile

[New - Windows NT]

The SetupCloseInfFile function closes the INF file opened by a call to SetupOpenInfFile and any INF files appended to it by SetupOpenAppendInfFile.

VOID SetupCloseInfFile(

HINF InfHandle	// handle to the INF file to close
);
Parameters

InfHandle

Handle to the INF file to close.

See Also

SetupOpenInfFile, SetupOpenAppendInfFile


SetupCommitFileQueue [New - Windows NT]
SetupCommitFileQueue

[New - Windows NT]

The SetupCommitFileQueue function performs file operations enqueued on a setup file queue.

BOOL SetupCommitFileQueue(

HWND Owner,	// optional; parent window
HSPFILEQ QueueHandle,	// handle to the file queue
PSP_FILE_CALLBACK MsgHandler,	// callback routine to use
PVOID Context	// passed to callback routine
);
Parameters

Owner

This optional parameter supplies the handle of a window to use as the parent of any progress dialog boxes.

QueueHandle

Supplies a handle to a setup file queue, as returned by SetupOpenFileQueue.

MsgHandler

Supplies a callback routine to be notified of various significant events in the queue processing. For more information, see “Default Queue Callback Routine.”

Context

Supplies a value that is passed to the callback function supplied by the MsgHandler parameter. If the default callback routine has been specified as MsgHandler, this context must be the context returned from SetupInitDefaultQueueCallback or SetupInitDefaultQueueCallbackEx.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The callback routine specified in MsgHandler should be compatible with the the parameters that SetupCommitFileQueue passed to it during a queue commit.

If Unicode is defined in your callback application, and you specifiy MsgHandler as the default queue callback routine, the callback routine will expect Unicode parameters. Otherwise, the default queue callback routine will expect ANSI parameters.

See Also

SetupCloseFileQueue


SetupCopyError [New - Windows NT]
SetupCopyError

[New - Windows NT]

The SetupCopyError function generates a dialog box to notify the user of a copy file error.

UINT SetupCopyError(

HWND hwndParent,	// parent window for this dialog box
PCTSTR DialogTitle,	// optional, title for this dialog box
PCTSTR DiskName,	// optional, name of disk to insert
PCTSTR PathToSource,	// failed source path
PCTSTR SourceFile,	// source file of copy error
PCTSTR TargetPathFile,	// optional, target file of copy error
UINT Win32ErrorCode,	// error information
DWORD Style,	// dialog box formatting and display
PTSTR PathBuffer,	// optional, receives new path info
DWORD PathBufferSize,	// size of supplied buffer
PDWORD PathRequiredSize	// optional, buffer size needed
);
Parameters

hwndParent

Handle to the parent window for this dialog box.

DialogTitle

This optional parameter points to a null-terminated string specifying the dialog box title. If this parameter is NULL, the default title of “Copy Error” (localized to the system language) is used.

DiskName

This optional parameter points to a null-terminated string specifying the name of the disk to insert. If this parameter is NULL, the default name “(Unknown)” (localized to the system language) is used.

PathToSource

Pointer to the path component of the source file on which the operation failed; for example, F:\mips.

SourceFile

Pointer to a null-terminated string specifying the filename part of the file on which the operation failed. This filename is displayed if the user clicks on the Details or Browse buttons. The SetupCopyError function looks for the file using its compressed form names; therefore, you can pass cmd.exe and not worry that the file actually exists as cmd.ex_ on the source media.

TargetPathFile

This optional parameter points to a null-terminated string that specifies the full path of the target file for rename and copy operations. If TargetPathFile is not specified, “(Unknown)” (localized to the system language) is used.

Win32ErrorCode

The Win32 error code encountered during the file operation. For information about Win32 error codes, see the WINERROR.H file included with the Win32 SDK.

Style

Specifies flags that control display formatting and behavior of the dialog box. This parameter can be one of the following flags:

IDF_NOBROWSE

Do not display the browse option.

IDF_NOSKIP

Do not display the skip file option.

IDF_NODETAILS

Do not display the details option. If this flag is set, the TargetPathFile and Win32ErrorCode parameters can be omitted.

IDF_NOCOMPRESSED

Do not check for compressed versions of the source file.

IDF_OEMDISK

The operation source is a disk provided by a hardware manufacturer.

IDF_NOBEEP

Prevent the dialog box from beeping to get the user’s attention when it first appears.

IDF_NOFOREGROUND

Prevent the dialog box from becoming the foreground window.

IDF_WARNIFSKIP

Warn the user that skipping a file can affect the installation.

PathBuffer

This optional parameter points to a caller-supplied variable in which this function returns the path (not including the filename) of the location specified by the user through the dialog box.

PathBufferSize

Specifies the size of the buffer pointed to by PathBuffer. It should be at least MAX_PATH in length.

PathRequiredSize

This optional parameter points to a caller-supplied variable in which this function returns the required buffer size.

Return Values

The function returns one of the following values:

DPROMPT_SUCCESS

The requested disk/file is present and accessible. If PathBuffer was specified, it contains the path to the file (not including the filename).

DPROMPT_CANCEL

The user clicked on the Cancel button.

DPROMPT_SKIPFILE

The user clicked on the Skip File button.

DPROMPT_BUFFERTOOSMALL

The provided PathBuffer is too small. Check PathRequiredSize for the actual size needed.

DPROMPT_OUTOFMEMORY

There is insufficient memory to process the request.

Remarks

For the Unicode version of this function, the buffer sizes ReturnBufferSize and RequiredSize are specified in number of characters. This number includes the null terminator. For the ANSI version of this function, the sizes are specified in number of bytes.

If this function is called with a ReturnBuffer of NULL and a ReturnBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by RequiredSize. If the function succeeds in this, the return value is NO_ERROR. Otherwise, the return value is one of the values specified preceding.

To avoid insufficient buffer errors, ReturnBuffer should be at least MAX_PATH.

See Also

SetupDeleteError, SetupPromptForDisk, SetupRenameError


SetupDecompressOrCopyFile [New - Windows NT]
SetupDecompressOrCopyFile

[New - Windows NT]

The SetupDecompressOrCopyFile function copies a file, decompressing it if necessary.

DWORD SetupDecompressOrCopyFile(

PCTSTR SourceFileName,	// filename of the source file
PCTSTR TargetFileName,	// filename after copy operation
PUINT CompressionType	// optional, source file compression
);
Parameters

SourceFileName

Filename of the file to copy. If CompressionType is not specified and the SetupDecompressOrCopyFile function does not find the file specified in SourceFileName, the function searches for the file with up to two alternate, “compressed-form” names. For example, if the file is F:\mips\cmd.exe and it is not found, the function searches for F:\mips\cmd.ex_ and, if that is not found, F:\mips\cmd.ex$ is searched for. If CompressionType is specified, no additional processing is performed on the filename; the file must exist exactly as specified or the function fails.

TargetFileName

Supplies the exact name of the target file that will be created by decompressing or copying the source file.

CompressionType

This optional parameter points to the compression type used on the source file. You can determine the compression type by calling SetupGetFileCompressionInfo. If this value is FILE_COMPRESSION_NONE, the file is copied (not decompressed) regardless of any compression in use on the source. If CompressionType is not specified, this routine determines the compression type automatically.

Return Values

The SetupDecompressOrCopyFile function returns a Win32 error code that indicates the outcome of the operation. For more information about Win32 error codes, see the WINERROR.H header file included with the Win32 SDK.

See Also

SetupGetFileCompressionInfo


SetupDefaultQueueCallback [New - Windows NT]
SetupDefaultQueueCallback

[New - Windows NT]

The SetupDefaultQueueCallback function is the default queue callback routine included with the Setup API. You can use it to process notifications sent by the SetupCommitFileQueue function.

UINT SetupDefaultQueueCallback(

PVOID Context,	// context used by the default callback routine
UINT Notification,	// queue notification
UINT Param1,	// additional notification information
UINT Param2	// additional notification information
);
Parameters

Context

Supplies a pointer to the context initialized by the SetupInitDefaultQueueCallback or SetupInitDefaultQueueCallbackEx functions.

Notification

Supplies the notification of a queue action. This parameter can be one of the following values:

SPFILENOTIFY_STARTQUEUE	Started enqueued file operations.
SPFILENOTIFY_ENDQUEUE	Finished enqueued file operations.
SPFILENOTIFY_STARTSUBQUEUE	Started a copy, rename, or delete subqueue.
SPFILENOTIFY_ENDSUBQUEUE	Finished a copy, rename, or delete subqueue.
SPFILENOTIFY_STARTRENAME	Started a rename operation.
SPFILENOTIFY_ENDRENAME	Finished a rename operation.
SPFILENOTIFY_RENAMEERROR	Encountered an error while renaming a file.
SPFILENOTIFY_STARTDELETE	Started a delete operation.
SPFILENOTIFY_ENDDELETE	Finished a delete operation.
SPFILENOTIFY_DELETEERROR	Encountered an error while deleting a file.
SPFILENOTIFY_STARTCOPY	Started a copy operation.
SPFILENOTIFY_ENDCOPY	Finished a copy operation.
SPFILENOTIFY_COPYERROR	Encountered an error while copying a file.
SPFILENOTIFY_NEEDMEDIA	New media is required.
SPFILENOTIFY_LANGMISMATCH	Existing target file is in a different language than the source.
SPFILENOTIFY_TARGETEXISTS	Target file exists.
SPFILENOTIFY_TARGETNEWER	Existing target file is newer than source.
Param1

Specifies additional message information. The content of this parameter depends on the value of the Notification parameter.

Param2

Specifies additional message information. The content of this parameter depends on the value of the Notification parameter.

Return Values

Returns an unsigned integer to SetupCommitFileQueue that can be the following values.

File Directive	Description
FILEOP_ABORT	Abort the operation.
FILEOP_DOIT	Perform the file operation.
FILEOP_SKIP	Skip the operation.
FILEOP_RETRY	Retry the operation.
FILEOP_NEWPATH	Get a new path for the operation.
Remarks

The SetupDefaultQueueCallback function is usually only called explicitly by a custom queue callback routine. The custom callback handles a subset of the queue commit notifications and calls the SetupDefaultQueueCallback function to handle the rest of the notifications.

For more information see, Queue Notifications.

See Also

SetupCommitFileQueue


SetupDeleteError [New - Windows NT]
SetupDeleteError

[New - Windows NT]

The SetupDeleteError function generates a dialog box that informs the user of a delete error.

UINT SetupDeleteError(

HWND hwndParent,	// parent window for this dialog box
PCTSTR DialogTitle,	// optional, title for this dialog box
PCTSTR File,	// file that caused the delete error
UINT Win32ErrorCode,	// specifies the error that occurred
DWORD Style	// specifies formatting for the dialog box
);
Parameters

hwndParent

Handle to the parent window for this dialog box.

DialogTitle

This optional parameter points to a null-terminated string specifying the error dialog box title. If this parameter is NULL, the default title of “Delete Error” (localized) is used.

File

Pointer to a null-terminated string specifying the full path of the file on which the delete operation failed.

Win32ErrorCode

The Win32 error code encountered during the file operation.

Style

Specifies flags that control display formatting and behavior of the dialog box. This parameter can be one of the following flags:

IDF_NOBEEP

Prevent the dialog box from beeping to get the user’s attention when it first appears.

IDF_NOFOREGROUND

Prevent the dialog box from becoming the foreground window.

Return Values

This function returns one of the following values:

DPROMPT_SUCCESS

The user retried the operation and it was successful.

DPROMPT_CANCEL

The user clicked the Cancel button.

DPROMPT_SKIPFILE

The user clicked the Skip File button.

DPROMPT_OUTOFMEMORY

There is insufficient memory to process the request.

See Also

SetupCopyError, SetupPromptForDisk, SetupRenameError


SetupFindFirstLine [New - Windows NT]
SetupFindFirstLine

[New - Windows NT]

The SetupFindFirstLine function locates a line in the specified section of an INF file. If the Key parameter is NULL, SetupFindFirstLine returns the first line of the section.

BOOL SetupFindFirstLine(

HINF InfHandle,	// handle to an INF file
PCTSTR Section,	// section in which to find a line
PCTSTR Key,	// optional, key to search for
PINFCONTEXT Context	// context of the found line
);
Parameters

InfHandle

Handle to the INF file to query.

Section

Pointer to a null-terminated string specifying the section of the INF file(s) to search in.

Key

This optional parameter points to a null-terminated string specifying the key to search for within the section. If Key is NULL, the first line in the section is returned.

Context

Pointer to a structure in which this function returns the context information used internally by the INF handle. Applications must not overwrite values in this structure.

Return Values

If the function could not find a line, the return value is FALSE.

Remarks

If the InfHandle parameter references multiple INF files that have been appended together using SetupOpenAppendInfFile, the SetupFindFirstLine function searches across the specified section in all of the files referenced by the specified HINF.

See Also

SetupFindNextLine, SetupFindNextMatchLine, SetupGetLineByIndex


SetupFindNextLine [New - Windows NT]
SetupFindNextLine

[New - Windows NT]

The SetupFindNextLine returns the location of the next line in an INF file section relative to ContextIn.Line.

BOOL SetupFindNextLine(

PINFCONTEXT ContextIn,	// starting context in an INF file
PINFCONTEXT ContextOut	// context of the next line
);
Parameters

ContextIn

Pointer to the INF file context retrieved by a call to the SetupFindFirstLine function.

ContextOut

Pointer to a caller-supplied variable in which this function returns the context of the found line. ContextOut can point to ContextIn if the caller wishes.

Return Values

If this function finds the next line, the return value is TRUE. Otherwise, the return value is FALSE.

Remarks

If ContextIn.Inf references multiple INF files that have been appended together using SetupOpenAppendInfFile, this function searches across the specified section in all files referenced by the HINF to locate the next line.

See Also

SetupFindFirstLine, SetupFindNextMatchLine, SetupGetLineByIndex


SetupFindNextMatchLine [New - Windows NT]
SetupFindNextMatchLine

[New - Windows NT]

The SetupFindNextMatchLine function returns the location of the next line in an INF file relative to ContextIn.Line that matches a specified key.

BOOL SetupFindNextMatchLine(

PINFCONTEXT ContextIn,	// starting context in an INF file
PCTSTR Key,	// optional, key to match
PINFCONTEXT ContextOut	// context of the the found line
);
Parameters

ContextIn

Specifies a pointer to an INF file context, as retrieved by a call to the SetupFindFirstLine function.

Key

If this optional parameter is specified, it supplies a key to match. If Key is not specified, the SetupFindNextMatchLine  function is equivalent to the SetupFindNextLine function.

ContextOut

Pointer to a caller-supplied variable in which this function returns the context of the found line. ContextOut can point to ContextIn if the caller wishes.

Return Values

The function returns TRUE if it finds a matching line. Otherwise, the return value is FALSE.

Remarks

If ContextIn.Inf references multiple INF files that have been appended together using SetupOpenAppendInfFile, the SetupFindNextMatchLine function searches across the specified section in all files referenced by the HINF to locate the next matching line.

See Also

SetupFindFirstLine, SetupFindNextLine, SetupGetLineByIndex


SetupFreeSourceList [New - Windows NT]
SetupFreeSourceList

[New - Windows NT]

The SetupFreeSourceList function frees the system resources allocated to a source list.

BOOL SetupFreeSourceList(

PCTSTR **List,	// an array of sources to free
UINT Count	// the number of sources in the array
);
Parameters

List

Specifies a pointer to an array of sources from SetupQuerySourceList. When the function returns, this pointer is set to NULL.

Count

Specifies the number of sources in the list.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

See Also

SetupCancelTemporarySourceList, SetupSetSourceList


SetupGetBinaryField [New - Windows NT]
SetupGetBinaryField

[New - Windows NT]

The SetupGetBinaryField function retrieves binary data from a line in an INF file section, from the specified field to the end of the line.

BOOL SetupGetBinaryField(

PINFCONTEXT Context,	// context of a line in an INF file
DWORD FieldIndex,	// index of the starting field
BYTE * ReturnBuffer,	// optional, receives the fields
DWORD ReturnBufferSize,	// size of the supplied buffer
LPDWORD RequiredSize	// optional, buffer size needed
);
Parameters

Context

Supplies INF context for the line.

FieldIndex

The 1-based index of the starting field within the specified line from which the binary data should be retrieved. The binary data is built from each field, starting at this point to the end of the line. Each field corresponds to 1 byte and is in hexadecimal notation. A FieldIndex of 0 is not valid with this function.

ReturnBuffer

This optional parameter points to a caller-supplied buffer that receives the binary data.

ReturnBufferSize

Specifies the size of the buffer pointed to by ReturnBuffer.

RequiredSize

This optional parameter points to a caller-supplied variable that receives the required size for the buffer pointed to ReturnBuffer. If the size needed is larger than the value specified by ReturnBufferSize, the function fails and a call to GetLastError returns ERROR_INSUFFICIENT_BUFFER.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

GetLastError returns ERROR_INVALID_DATA if a field that SetupGetBinaryField retrieves is not a valid hexadecimal number in the range 0-FF.

Remarks

To better understand how this function works, consider the following line from an INF file.

X=34,FF,00,13

If SetupGetBinaryField was called on the preceding line, the binary values 34, FF, 00, and 13 would be put into the buffer specified by ReturnBuffer.

For the Unicode version of this function, the buffer sizes ReturnBufferSize and RequiredSize are specified in number of characters. This number includes the null terminator. For the ANSI version of this function, the sizes are specified in number of bytes.

If this function is called with a ReturnBuffer of NULL and a ReturnBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by RequiredSize. If the function succeeds in this, the return value is TRUE. Otherwise, the return value is FALSE and extended error information can be obtained by calling GetLastError.

Thus, you can call the function once to get the required buffer size, allocate the necessary memory, and then call the function a second time to retrieve the data. Using this technique, you can avoid errors due to an insufficient buffer size.

See Also

SetupGetIntField, SetupGetMultiSzField, SetupGetStringField


SetupGetFieldCount [New - Windows NT]
SetupGetFieldCount

[New - Windows NT]

The SetupGetFieldCount function retrieves the number of fields in the specified line in an INF file.

DWORD SetupGetFieldCount(

PINFCONTEXT Context	//specifies the line to count fields in
);
Parameters

Context

Pointer to the context for a line in an INF file.

Return Values

This function returns the number of fields on the line. If Context is invalid, 0 is returned.

See Also

SetupGetLineCount


SetupGetFileCompressionInfo [New - Windows NT]
SetupGetFileCompressionInfo

[New - Windows NT]

The SetupGetFileCompressionInfo function examines a physical file to determine if it is compressed and gets its full path, size, and the size of the uncompressed target file.

DWORD SetupGetFileCompressionInfo(

PCTSTR SourceFileName,	// file to investigate
PTSTR *ActualSourceFileName,	// receives compressed name
PDWORD SourceFileSize,	// receives compressed size
PDWORD TargetFileSize,	// receives uncompressed size
PUINT CompressionType	// receives compression type
);
Parameters

SourceFileName

Filename of the file about which information is required. If the file is not found on the source media exactly as named, the file is searched for with up to two alternate “compressed-form” names. For example, if the file is F:\mips\cmd.exe and it is not found, F:\mpis\cmd.ex_ is searched for and, if that is not found, F:\mips\cmd.ex$ is searched for.

ActualSourceFileName

Supplies a pointer to a caller-supplied variable in which this function returns the full path of the file that was actually located. The caller can free the pointer with a call to LocalFree. The path is valid only if the function returns NO_ERROR.

SourceFileSize

Supplies a pointer to a caller-supplied variable in which this function returns the size of the file in its current form which is the current size of the filenamed by ActualSourceFileName. The size is determined by examining the source file; it is not retrieved from an INF file. The source file size is valid only if the function returns NO_ERROR.

TargetFileSize

Supplies a pointer to a caller-supplied variable in which this function returns the size the file will occupy when it is uncompressed or copied. If the file is not compressed, this value will be the same as SourceFileSize. The size is determined by examining the file; it is not retrieved from an INF file. The target file size is valid only if the function returns NO_ERROR.

CompressionType

Supplies a pointer to a caller-supplied variable in which this function returns a value indicating the type of compression used on ActualSourceFileName. The compression type is valid only if the function returns NO_ERROR. The value can be one of the following flags:

FILE_COMPRESSION_NONE

The source file is not compressed with a recognized compression algorithm.

FILE_COMPRESSION_WINLZA

The source file is compressed with winlza (using compress.exe without the -z switch or LZXxx Win32 functions).

FILE_COMPRESSION_MSZIP

The source file is compressed with mszip (using compress.exe with the -z switch).

Return Values

The function returns a Win32 error code that indicates the outcome of the file search. The error code can be one of the following:

ERROR_FILE_NOT_FOUND

The file cannot be found.

NO_ERROR

The file was located and the output parameters were filled in.

Remarks

Because SetupGetFileCompressionInfo determines the compression by referencing the physical file, your setup application should ensure that the file is present before calling SetupGetFileCompressionInfo.

See Also

SetupDecompressOrCopyFile


SetupGetInfFileList [New - Windows NT]
SetupGetInfFileList

[New - Windows NT]

The SetupGetInfFileList function returns a list of INF files located in a caller-specified directory to a call-supplied buffer.

BOOL SetupGetInfFileList(

PCTSTR DirectoryPath,	// optional, the directory path
DWORD InfStyle,	// style of the INF file
PTSTR ReturnBuffer,	// optional, receives the file list
DWORD ReturnBufferSize,	// size of the supplied buffer
PDWORD RequiredSize	// optional, buffer size needed
);
Parameters

DirectoryPath

An optional parameter that points to a null-terminated string containing the path of the directory in which to search. If this value is NULL, the %windir%\inf directory is used.

InfStyle

Specifies the style of INF file to search for. May be a combination of the following flags.

INF_STYLE_OLDNT

Windows NT 3.x script-based INF files.

INF_STYLE_WIN4

Windows 95- or Windows NT 4.0-style INF files.

ReturnBuffer

If not NULL, points to a caller-supplied buffer in which this function returns the list of all INF files of the desired style(s) that were found in the specified subdirectory. Filenames are null-terminated, with an extra null at the end of the list. The filenames do not include the path.

ReturnBufferSize

Specifies the size of the buffer pointed to by the ReturnBuffer parameter. If ReturnBuffer is not specified, ReturnBufferSize is ignored.

RequiredSize

If not NULL, points to a caller-supplied variable in which this function returns the required size for the buffer pointed to by the ReturnBuffer parameter. If ReturnBuffer is specified and the size needed is larger than ReturnBufferSize, the function fails and a call to GetLastError returns ERROR_INSUFFICIENT_BUFFER.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

For the Unicode version of this function, the buffer sizes ReturnBufferSize, and RequiredSize are specified in number of characters. This number includes the null terminator. For the ANSI version of this function, the sizes are specified in number of bytes.

If this function is called with a ReturnBuffer of NULL and a ReturnBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by RequiredSize. If the function succeeds in this, the return value is TRUE. Otherwise, the return value is FALSE and extended error information can be obtained by calling GetLastError.

Thus, you can call the function once to get the required buffer size, allocate the necessary memory, and then call the function a second time to retrieve the data. Using this technique, you can avoid errors due to an insufficient buffer size.

If multiple INF file styles are returned by this function, the style of a particular INF file can be determined by calling the SetupGetInfInformation function.

See Also

SetupGetInfInformation


SetupGetInflnformation [New - Windows NT]
SetupGetInflnformation

[New - Windows NT]

The SetUpGetInfInformation function returns the SP_INF_INFORMATION structure for the specified INF file to a caller-supplied buffer.

BOOL SetupGetInflnformation(

LPCVOID InfSpec,	// handle or filename of the INF file
DWORD SearchControl,	// how to search for the INF file
PSP_INF_INFORMATION Return Buffer,	// optional, receives the INF info
DWORD ReturnBufferSize,	// size of the supplied buffer
PDWORD RequiredSize	// optional, buffer size needed
);
Parameters

InfSpec

A handle or a filename for an INF file, depending on the value of SearchControl.

SearchControl

This parameter can be one of the following constants:

INFINFO_INF_SPEC_IS_HINF

InfSpec is an INF handle. A single INF handle may reference multiple INF files if they have been append-loaded together. If it does, the structure returned by this function contains multiple sets of information.

INFINFO_INF_NAME_IS_ABSOLUTE

The string specified for InfSpec is a full path. No further processing is performed on InfSpec.

INFINFO_DEFAULT_SEARCH

Search the default locations for the INF file specified for InfSpec, which is assumed to be a filename only. The default locations are %windir%\inf, followed by %windir%\system32.

INFINFO_REVERSE_DEFAULT_SEARCH

Same as INFINFO_DEFAULT_SEARCH, except the default locations are searched in reverse order.

INFINFO_INF_PATH_LIST_SEARCH

Search for the INF in each of the directories listed in the DevicePath value entry under:

  HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion

ReturnBuffer

If not NULL, ReturnBuffer points to a caller-supplied buffer in which this function returns the SP_INF_INFORMATION structure.

ReturnBufferSize

Size of the ReturnBuffer.

RequiredSize

If not NULL, points to a caller-supplied variable in which this function returns the required size for the buffer pointed to by ReturnBuffer. If ReturnBuffer is specified and the size needed is larger than ReturnBufferSize, the function fails and a call to GetLastError returns ERROR_INSUFFICIENT_BUFFER.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

If the INF file could not be located, the function returns FALSE and a subsequent call to GetLastError returns ERROR_FILE_NOT_FOUND.

Remarks

For the Unicode version of this function, the buffer sizes ReturnBufferSize and RequiredSize are specified in number of characters. This number includes the null terminator. For the ANSI version of this function, the sizes are specified in number of bytes.

If this function is called with a ReturnBuffer of NULL and a ReturnBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by RequiredSize. If the function succeeds in this, the return value is TRUE. Otherwise, the return value is FALSE and extended error information can be obtained by calling GetLastError.

Thus, you can call the function once to get the required buffer size, allocate the necessary memory, and then call the function a second time to retrieve the data. Using this technique, you can avoid errors due to an insufficient buffer size.

See Also

SetupQueryInfFileInformation, SetupQueryInfVersionInformation


SetupGetIntField [New - Windows NT]
SetupGetIntField

[New - Windows NT]

The SetupGetIntField function retrieves an integer value from the specified field of a line in an INF file.

BOOL SetupGetIntField(

PINFCONTEXT Context,	// context of a line in an INF file
DWORD FieldIndex,	// index of an integer field in the line
PINT IntegerValue	// receives the retreived integer field
);
Parameters

Context

Pointer to the context for a line in an INF file.

FieldIndex

The 1-based index of the field within the specified line from which the integer should be retrieved.

A FieldIndex of 0 can be used to retrieve an integer key (For example, consider the following INF line, 431 = 1, 2, 4. The value 431 would be put into the variable pointed at by IntegerValue if SetupGetIntField was called with a FieldIndex of 0).

Integer Value

Pointer to a caller-supplied variable that receives the integer. If the field is not an integer, the function fails and a call to GetLastError returns ERROR_INVALID_DATA.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The integer field may start with a positive (+) or negative (-) sign. It will be interpreted as a decimal number, unless it is prefixed in the file with 0x or 0X, in which case it is hexadecimal.

See Also

SetupGetBinaryField, SetupGetMultiSzField, SetupGetStringField


SetupGetLineByIndex [New - Windows NT]
SetupGetLineByIndex

[New - Windows NT]

The SetupGetLineByIndex function locates a line by its index value in the specified section in the INF file.

BOOL SetupGetLineByIndex(

HINF InfHandle,	// handle to the INF file
PCTSTR Section,	// section that contains the line
DWORD Index,	// the index of the line to find
PINFCONTEXT Context	// context that specifies the found line
);
Parameters

InfHandle

Handle of the INF file.

Section

Pointer to a null-terminated string specifying the section of the INF file to search.

Index

Specifies the index of the line to be located. The total number of lines in a particular section can be found with a call to SetupGetLineCount.

Context

Points to a caller-supplied variable in which the function returns the context information for the found line.

Return Values

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

Remarks

If InfHandle references multiple INF files that have been appended together using SetupOpenAppendInfFile, this function searches across the specified section in all files referenced by the HINF to locate the indexed line.

See Also

SetupFindFirstLine, SetupFindNextLine, SetupFindNextMatchLine


SetupGetLineCount [New - Windows NT]
SetupGetLineCount

[New - Windows NT]

The SetupGetLineCount function returns the number of lines in a specified section of an INF file.

LONG SetupGetLineCount(

HINF InfHandle,	// handle to the INF file
PCTSTR Section	// the section in which to count lines
);
Parameters

InfHandle

Handle of the INF file.

Section

Pointer to a null-terminated string that specifies the section in which you want to count the lines.

Return Values

If InfHandle references multiple INF files that have been appended together using SetupOpenAppendInfFile, this function returns the sum of the lines in all the INF files containing the specified section. A return value of 0 specifies an empty section. If the section does not exist, the function returns -1.


SetupGetLineText [New - Windows NT]
SetupGetLineText

[New - Windows NT]

The SetupGetLineText function returns the contents of a line in an INF file in a compact form. The line to retrieve can be specified by an INFCONTEXT structure returned from a SetupFindLineXXX function, or by explicitly passing in the INF handle, section, and key of the desired line.

BOOL SetupGetLineText(

PINFCONTEXT Context,	// optional, context of an INF file
HINF InfHandle,	// optional, handle to an INF file
PCTSTR Section,	// optional, section in an INF file
PCTSTR Key,	// optional, key to look for
PTSTR ReturnBuffer,	// optional, receives the line text
DWORD ReturnBufferSize,	// size of the supplied buffer
PDWORD RequiredSize	// optional, buffer size needed
);
Parameters

Context

Supplies context for a line in an INF file whose text is to be retrieved. If Context is NULL, InfHandle, Section, and Key must be specified.

InfHandle

Handle of the INF file to query. This parameter is used only if Context is NULL.

Section

Pointer to a null-terminated string that specifies the section containing the key name of the line whose text is to be retrieved. This parameter is used only if Context is NULL.

Key

Pointer to a null-terminated string containing the key name whose associated string is to be retrieved. This parameter is used only if Context is NULL.

ReturnBuffer

If not NULL, points to a caller-supplied buffer in which this function returns the contents of the line.

ReturnBufferSize

Specifies the size of the buffer pointed to by the ReturnBuffer parameter.

RequiredSize

If not NULL, points to a caller-supplied variable in which this function returns the required size for the buffer pointed to by the ReturnBuffer parameter. If ReturnBuffer is specified and the size needed is larger than the value specified in the ReturnBufferSize parameter, the function fails and does not store data in the buffer.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

For the Unicode version of this function, the buffer sizes ReturnBufferSize and RequiredSize are specified in number of characters. This number includes the null terminator. For the ANSI version of this function, the sizes are specified in number of bytes.

If this function is called with a ReturnBuffer of NULL and a ReturnBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by RequiredSize. If the function succeeds in this, the return value is TRUE. Otherwise, the return value is FALSE and extended error information can be obtained by calling GetLastError.

Thus, you can call the function once to get the required buffer size, allocate the necessary memory, and then call the function a second time to retrieve the data. Using this technique, you can avoid errors due to an insufficient buffer size.

This function returns the contents of a line in a compact format. All extraneous white space is removed and multi-line values are converted into a single contiguous string. For example, this line:

HKLM, , PointerClass0, 1 \

; This is a comment

01, 02, 03

would be returned as:

HKLM,,PointerClass0,1,01,02,03

See Also

SetupFindFirstLine, SetupFindNextLine, SetupFindNextMatchLine, SetupGetLineByIndex


SetupGetMultiSzField [New - Windows NT]
SetupGetMultiSzField

[New - Windows NT]

The SetupGetMultiSzField function retrieves multiple strings stored in a line of an INF file, from the specified field to the end of the line.

BOOL SetupGetMultiSzField(

PINFCONTEXT Context,	// context of a line in an INF file
DWORD FieldIndex,	// index of the starting field
PTSTR ReturnBuffer,	// optional, receives the fields
DWORD ReturnBufferSize,	// size of the supplied buffer
LPDWORD RequiredSize	// optional, buffer size needed
);
Parameters

Context

Pointer to the context for a line in an INF file.

FieldIndex

The 1-based index of the starting field within the specified line from which the strings should be retrieved. The string list is built from each field starting at this point to the end of the line. A FieldIndex of 0 is not valid with this function.

ReturnBuffer

This optional parameter points to a caller-supplied character buffer that receives the strings. Each string is null-terminated, with an extra null at the end of the string list.

ReturnBufferSize

Specifies the size of the buffer pointed to by ReturnBuffer.

RequiredSize

This optional parameter points to a caller-supplied variable that receives the size required for the buffer pointed to by ReturnBuffer. If the size needed is larger than the value specified by ReturnBufferSize, the function fails and a call to GetLastError returns ERROR_INSUFFICIENT_BUFFER.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

For the Unicode version of this function, the buffer sizes ReturnBufferSize and RequiredSize are specified in number of characters. This number includes the null terminator. For the ANSI version of this function, the sizes are specified in number of bytes.

If this function is called with a ReturnBuffer of NULL and a ReturnBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by RequiredSize. If the function succeeds in this, the return value is TRUE. Otherwise, the return value is FALSE and extended error information can be obtained by calling GetLastError.

Thus, you can call the function once to get the required buffer size, allocate the necessary memory, and then call the function a second time to retrieve the data. Using this technique, you can avoid errors due to an insufficient buffer size.

See Also

SetupGetBinaryField, SetupGetIntField, SetupGetStringField


SetupGetSourceFileLocation [New - Windows NT]
SetupGetSourceFileLocation

[New - Windows NT]

The SetupGetSourceFileLocation function retrieves the location of a source file listed in an INF file.

BOOL SetupGetSourceFileLocation(

HINF InfHandle,	// handle of an INF file
PINFCONTEXT InfContext,	// optional, context of an INF file
PCTSTR FileName,	// optional, source file to locate
PUINT SourceId,	// receives the source media ID
PTSTR ReturnBuffer,	// optional, receives the location
DWORD ReturnBufferSize,	// size of the supplied buffer
PDWORD Required Size	// optional, buffer size needed
);
Parameters

InfHandle

Handle of the INF file that contains the SourceDisksNames and SourceDisksFiles sections. If platform-specific sections exist for the user’s system (for example, SourceDisksNames.mips and SourceDisksFiles.mips), the platform-specific section will be used.

InfContext

This optional parameter points to the context of a line in a Copy Files section for which the full source path is to be retrieved. If this parameter is NULL, FileName is searched for in the SourceDisksFiles section of the INF file specified by InfHandle.

FileName

This optional parameter points to a null-terminated string containing the filename (no path) for which to return the full source location. Either this parameter or InfContext must be specified.

SourceId

Points to a caller-supplied variable that receives the source identifier of the media where the file is located from the SourceDisksNames section of the INF file.

ReturnBuffer

This optional parameter points to a caller-supplied buffer to receive the relative source path. The source path does not include the filename itself, nor does it include a drive letter/network share name. The path does not start or end with a backslash (\), so the empty string specifies the root directory.

ReturnBufferSize

Specifies the size of the buffer pointed to by ReturnBuffer.

RequiredSize

This optional parameter points to a caller-supplied variable that receives the required size for the buffer pointed to by the ReturnBuffer parameter. If the required size is larger than the value specified by ReturnBufferSize, the function fails and GetLastError returns ERROR_INSUFFICIENT_BUFFER.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

For the Unicode version of this function, the buffer sizes ReturnBufferSize, and ReturnBufferSize are specified in number of characters. This number includes the null terminator. For the ANSI version of this function, the sizes are specified in number of bytes.

If this function is called with a ReturnBuffer of NULL and a ReturnBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by RequiredSize. If the function succeeds in this, the return value is TRUE. Otherwise, the return value is FALSE and extended error information can be obtained by calling GetLastError.

Thus, you can call the function once to get the required buffer size, allocate the necessary memory, and then call the function a second time to retrieve the data. Using this technique, you can avoid errors due to an insufficient buffer size.

See Also

SetupGetSourceInfo, SetupGetSourceFileSize


SetupGetSourceFileSize [New - Windows NT]
SetupGetSourceFileSize

[New - Windows NT]

The SetupGetSourceFileSize function reads the uncompressed size of a source file listed in an INF file.

BOOL SetupGetSourceFileSize(

HINF InfHandle,	// handle of the INF file
PINFCONTEXT InfContext,	// optional, context of the INF file
PCTSTR FileName,	// optional, filename to find size of
PCTSTR Section,	//optional, section in an INF file
PDWORD FileSize,	// receives the size of the file
UINT RoundingFactor	// optional, round to a muliple of this
);
Parameters

InfHandle

Handle of the loaded INF file that contains the SourceDisksNames and SourceDisksFiles sections. If platform-specific sections exist for the user’s system (for example, SourceDisksNames.mips and SourceDisksFiles.mips), the platform-specific section will be used.

InfContext

This optional parameter points to a context for a line in a Copy Files section for which the size is to be retrieved. If InfContext is NULL, the FileName parameter is used.

FileName

This optional parameter points to a null-terminated string containing the filename (no path) for which to return the size. If this parameter is NULL as well as InfContext, then the Section parameter is used.

Section

This optional parameter points to a null-terminated string containing the name of a Copy Files section. If this parameter is specified, the total size of all files listed in the section is computed.

FileSize

Pointer to a caller-supplied variable that receives the size, in bytes, of the specified file(s).

RoundingFactor

This optional parameter supplies a value for rounding file sizes. All file sizes are rounded up to a multiple of this number before being added to the total size. Rounding is useful for more exact determinations of the space that a file will occupy on a given volume, because it allows the caller to have file sizes rounded up to a multiple of the cluster size. Rounding does not occur unless RoundingFactor is specified.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

One and only one of the optional parameters, InfContext, FileName, and Section, must be specified.

See Also

SetupGetSourceFileLocation


SetupGetSourceInfo [New - Windows NT]
SetupGetSourceInfo

[New - Windows NT]

The SetupGetSourceInfo function retrieves the path, tag file, or media description for a source listed in an INF file.

BOOL SetupGetSourceInfo(

HINF InfHandle,	// handle to the INF file
UINT SourceId,	// ID of the source media
UINT InfoDesired,	// information to retrieve
PTSTR ReturnBuffer,	// optional, receives the info
DWORD ReturnBufferSize,	// size of the supplied buffer
LPDWORD RequiredSize	// optional, buffer size needed
);
Parameters

InfHandle

Handle of an open INF file that contains a SourceDisksNames section. If platform-specific sections exist for the user’s system (for example, SourceDisksNames.mips), the platform-specific section will be used.

SourceId

Identifier for a source media. This value is used to search by key in the SourceDisksNames section.

InfoDesired

A value indicating what information is desired. Only one value may be specified per function call, and they cannot be combined. The following types of information can be retrieved from a SourceDisksNames section:

SRCINFO_PATH

The path specified for the source. This is not a full path, but the path relative to the installation root.

SRCINFO_TAGFILE

The tag file that identifies the source media, or if cabinets are used, the name of the cabinet file.

SRCINFO_DESCRIPTION

A description for the media.

ReturnBuffer

This optional parameter points to a caller-supplied buffer to receive the retrieved information. Path returns are guaranteed not to end with \.

ReturnBufferSize

Specifies the size of the buffer pointed to by ReturnBuffer.

RequiredSize

This optional parameter points to a caller-supplied variable that receives the required size for the buffer specified by ReturnBuffer. If ReturnBuffer is specified and the actual size needed is larger than the value specified by ReturnBufferSize, the function fails and a call to GetLastError returns ERROR_INSUFFICIENT_BUFFER.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

For the Unicode version of this function, the buffer sizes ReturnBufferSize and RequiredSize are specified in number of characters. This number includes the null terminator. For the ANSI version of this function, the sizes are specified in number of bytes.

If this function is called with a ReturnBuffer of NULL and a ReturnBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by RequiredSize. If the function succeeds in this, the return value is TRUE. Otherwise, the return value is FALSE and extended error information can be obtained by calling GetLastError.

Thus, you can call the function once to get the required buffer size, allocate the necessary memory, and then call the function a second time to retrieve the data. Using this technique, you can avoid errors due to an insufficient buffer size.

See Also

SetupGetSourceFileLocation, SetupGetSourceFileSize, SetupGetTargetPath


SetupGetStringField [New - Windows NT]
SetupGetStringField

[New - Windows NT]

The SetupGetStringField function retrieves a string from the specified field of a line in an INF file.

BOOL SetupGetStringField(

PINFCONTEXT Context,	// context of the INF file
DWORD FieldIndex,	// index of the field to get
PTSTR ReturnBuffer,	// optional, receives the field
DWORD ReturnBufferSize,	// size of the provided buffer
PDWORD RequiredSize	// optional, buffer size needed
);
Parameters

Context

Pointer to the context for a line in an INF file.

FieldIndex

The 1-based index of the field within the specified line from which the string should be retrieved. Use a FieldIndex of 0 to retrieve a string key, if present.

ReturnBuffer

This optional parameter points to a caller-supplied buffer to which this function returns the string.

ReturnBufferSize

The size of the buffer pointed to by ReturnBuffer.

RequiredSize

This optional parameter points to a caller-supplied variable to which SetupGetStringField returns the required size for the buffer pointed to by the ReturnBuffer parameter. If ReturnBuffer is specified and the actual size needed is larger than the value specified by ReturnBufferSize, the function fails and does not store the string in the buffer. In this case, a call to GetLastError returns ERROR_INSUFFICIENT_BUFFER.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

For the Unicode version of this function, the buffer sizes ReturnBufferSize, and ReturnBufferSize are specified in number of characters. This number includes the null terminator. For the ANSI version of this function, the sizes are specified in number of bytes.

If this function is called with a ReturnBuffer of NULL and a ReturnBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by RequiredSize. If the function succeeds in this, the return value is TRUE. Otherwise, the return value is FALSE and extended error information can be obtained by calling GetLastError.

Thus, you can call the function once to get the required buffer size, allocate the necessary memory, and then call the function a second time to retrieve the data. Using this technique, you can avoid errors due to an insufficient buffer size.

See Also

SetupGetIntField, SetupGetBinaryField, SetupGetMultiSzField


SetupGetTargetPath [New - Windows NT]
SetupGetTargetPath

[New - Windows NT]

The SetupGetTargetPath function determines the target directory for a file list section. The file list section can be a Copy Files section, a Delete Files section, or a Rename Files section. All the files in the section must be in a single directory that is listed in a DestinationDirs section of the INF file.

BOOL SetupGetTargetPath(

HINF InfHandle,	// handle of the INF file
PINFCONTEXT InfContext,	// optional, context of the INF file
PCTSTR Section,	// optional, section in the INF file
PTSTR ReturnBuffer,	// optional, receives the path info
DWORD ReturnBufferSize,	// size of the supplied buffer
PDWORD RequiredSize	// optional, buffer size needed
);
Parameters

InfHandle

Handle of the load INF file that contains a DestinationDirs section.

InfContext

This optional parameter points to a INF context that specifies a line in a file list section whose destination directory is to be retrieved. If InfContext is NULL, then the Section parameter is used.

Section

This optional parameter specifies the name of a section of the INF file whose handle is InfHandle. SetupGetTargetPath retrieves the target directory for this section. The Section parameter is ignored if InfContext is specified. If neither InfContext nor Section is specified, the function retrieves the default target path from the INF file.

ReturnBuffer

This optional parameter points to a caller-supplied buffer to receive the fully qualified Win32 target path. The path is guaranteed not to end with \.

ReturnBufferSize

Specifies the size of the buffer pointed to by ReturnBuffer.

RequiredSize

This optional parameter points to a caller-supplied variable that receives the required size for the buffer pointed to by ReturnBuffer. If the actual size needed is larger than the value specified by ReturnBufferSize, the function fails and a call to GetLastError returns ERROR_INSUFFICIENT_BUFFER.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

For the Unicode version of this function, the buffer sizes ReturnBufferSize and RequiredSize are specified in number of characters. This number includes the null terminator. For the ANSI version of this function, the sizes are specified in number of bytes.

If this function is called with a ReturnBuffer of NULL and a ReturnBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by RequiredSize. If the function succeeds in this, the return value is TRUE. Otherwise, the return value is FALSE and extended error information can be obtained by calling GetLastError.

Thus, you can call the function once to get the required buffer size, allocate the necessary memory, and then call the function a second time to retrieve the data. Using this technique, you can avoid errors due to an insufficient buffer size.

See Also

SetupGetSourceFileLocation, SetupGetSourceInfo, SetupGetSourceFileSize


SetupInitDefaultQueueCallback [New - Windows NT]
SetupInitDefaultQueueCallback

[New - Windows NT]

The SetupInitDefaultQueueCallback function initializes the context used by the default queue callback routine included with the Setup API.

PVOID SetupInitDefaultQueueCallback(

HWND OwnerWindow	// parent window of any dialog boxes created by the callback routine
);
Parameters

OwnerWindow

Supplies the handle of the window to use as the parent of any dialog boxes generated by the default callback routine.

Return Values

A pointer to the context used by the default queue callback routine.

See Also

SetupDefaultQueueCallback, SetupInitDefaultQueueCallbackEx


SetupInitDefaultQueueCallbackEx [New - Windows NT]
SetupInitDefaultQueueCallbackEx

[New - Windows NT]

The SetupInitDefaultQueueCallback function initializes the context used by the default queue callback routine included with the Setup API in the same manner as SetupInitDefaultQueueCallback, except that an additional window is provided to the callback function to accept progress messages.

PVOID SetupInitDefaultQueueCallbackEx(

HWND OwnerWindow,	// parent of callback dialog boxes
HWND AlternateProgressWindow,	// handle to progress window
UINT ProgressMessage,	// specifies progress message
DWORD Reserved1,	// wParam of a window message
PVOID Reserved2	// lParam of a window message
);
Parameters

OwnerWindow

Supplies the handle of the window to use as the parent of any dialog boxes generated by the default callback routine.

AlternateProgressWindow

Supplies the handle to a window that will receive the progress messages.

ProgressMessage

The message that is sent to AlternateProgressWindow once when the copy queue is started, and each time a file is copied.

Reserved1

This parameter is the first message parameter that will be sent to the AlternateProgressWindow by the default callback routine.

Reserved2

This parameter is the second message parameter that will be sent to the AlternateProgressWindow by the default callback routine.

Return Values

A pointer to the context used by the default queue callback routine.

Remarks

When the queue starts to commit the copy sub queue, the default queue callback routine will send a message to the window specified in AlternateProgressWindow. Reserved1 will have the value 0, and Reserved2 will contain a pointer to the number of enqueued file copy operations.

For each file copy operation completed, the default queue callback routine will send a message to AlternateProgressWindow, which can be used to ‘tick’ the progress bar. Reserved1 will have the value 1, and Reserved2 will be 0.

SetupInitDefaultQueueCallbackEx can be used to get the default behavior for disk prompting, error handling, and so on, and also provide a gauge embedded in a wizard page or other specialized dialog box.

See Also

SetupInitDefaultQueueCallback


SetupInitializeFileLog [New - Windows NT]
SetupInitializeFileLog

[New - Windows NT]

The SetupInitializeFileLog function initializes a file to record installation operations and outcomes. This can be the system log, where the system tracks the files installed as part of Windows NT, or any other file.

HSPFILELOG SetupInitializeFileLog(

PCTSTR LogFileName,	// optional, name of a log file to use
DWORD Flags	// controls initialization
);
Parameters

LogFileName

This optional parameter supplies the filename of the file to use as the log file. The LogFileName parameter must be specified if Flags does not include SPFILELOG_SYSTEMLOG. The LogFileName parameter must not be specified if Flags includes SPFILELOG_SYSTEMLOG.

Flags

A set of flags that controls the log file initialization. This parameter can be a combination of the following:

SPFILELOG_SYSTEMLOG

Use the Windows NT system file log which is used to track what files are installed as part of Windows NT. The user must be Administrator to specify this option unless SPFILELOG_QUERYONLY is specified and LogFileName is not specified. Do not specify SPFILELOG_SYSTEMLOG in combination with SPFILELOG_FORCENEW.

SPFILELOG_FORCENEW

If the log file exits, overwrite it. If the log file exists and this flag is not specified, any new files that are installed are added to the list in the existing log file. Do not specify in combination with SPFILELOG_SYSTEMLOG.

SPFILELOG_QUERYONLY

Open the log file for querying only.

Return Values

The function returns the handle to the log file if it is successful. Otherwise, the the return value is INVALID_HANDLE_VALUE and the logged error can be retrieved by a call to GetLastError.

See Also

SetupTerminateFileLog, SetupLogFile


SetupInstallFile [New - Windows NT]
SetupInstallFile

[New - Windows NT]

The SetupInstallFile function installs a file as specified either by an INFCONTEXT returned by SetupFindXXXLine or explicitly by the filename and path information.

BOOL SetupInstallFile(

HINF InfHandle,	// optional, handle to the INF file
PINFCONTEXT InfContext,	// optional, context for a INF file line
PCTSTR SourceFile,	// optional, name of file to copy
PCTSTR SourcePathRoot,	// optional, root path to source
PCTSTR DestinationName,	// optional, filename after copy
DWORD CopyStyle,	// specifies copy behavior
PSP_FILE_CALLBACK CopyMsgHandler,	// optional, callback routine to use
PVOID Context	// optional, callback routine context
);
Parameters

InfHandle

This optional parameter points to the handle of an INF file that contains SourceDisksNames and SourceDisksFiles sections. If platform-specific sections exist for the user’s system (for example, SourceDisksNames.mips and SourceDisksFiles.mips), the platform-specific section will be used. If InfContext is NULL and CopySyle includes SP_COPY_SOURCE_ABSOLUTE or SP_COPY_SOURCEPATH_ABSOLUTE, InfHandle is ignored.

InfContext

This optional parameter points to the context of a line in a Copy Files section in an INF file. The routine looks this file up in the SourceDisksFiles section of InfHandle to get file copy information. If InfContext is not specified, SourceFile must be.

SourceFile

This optional parameter supplies the filename (no path) of the file to copy. The file is looked up in the SourceDisksFiles section. The SourceFile parameter must be specified if InfContext is not, and is ignored if InfContext is specified.

SourcePathRoot

This optional parameter supplies the root path for the file to be copied (for example, A:\ or F:\). Paths in the SourceDisksNames section are appended to this path. The SourcePathRoot parameter is ignored if CopyStyle includes the SP_COPY_SOURCE_ABSOLUTE flag.

DestinationName

This optional parameter supplies the filename only (no path) of the target file. This parameter can be NULL to indicate that the target file should have the same name as the source file. If InfContext is not specified, DestinationName supplies the full target path and filename for the target.

CopyStyle

Flags that control the behavior of the file copy operation. These flags may be a combination of the following values:

SP_COPY_DELETESOURCE

Delete the source file upon successful copy. The caller is not notified if the delete fails.

SP_COPY_REPLACEONLY

Copy the file only if doing so would overwrite a file at the destination path. If the target doesn’t exist, the function returns FALSE and GetLastError returns NO_ERROR.

SP_COPY_NEWER

Examine each file being copied to see if its version resources indicate that it is not newer than an existing copy on the target.

The file version information used during version checks is that specified in the dwFileVersionMS and dwFileVersionLS members of a VS_FIXEDFILEINFO structure, as filled in by the Win32 version functions. If one of the files does not have version resources, or if they have identical version information, the source file is considered newer.

If the source file is not newer, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied.

SP_COPY_NOOVERWRITE

Check whether the target file exists, and, if so, notify the caller who may veto the copy. If CopyMsgHandler is not specified, the file is not overwritten.

SP_COPY_NODECOMP

Do not decompress the file. When this flag is set, the target file is not given the uncompressed form of the source name (if appropriate). For example, copying f:\mips\cmd.ex_ to \\install\temp results in a target file of \\install\temp\cmd.ex_. If the SP_COPY_NODECOMP flag was not specified, the file would be decompressed and the target would be called \\install\temp\cmd.exe. The filename part of DestinationName, if specified, is stripped and replaced with the filename of the source file. When SP_COPY_NODECOMP is specified, SP_COPY_LANGUAGEAWARE and SP_COPY_NEWER are ignored.

SP_COPY_LANGUAGEAWARE

Examine each file being copied to see if its language differs from the language of any existing file already on the target. If so, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied.

SP_COPY_SOURCE_ABSOLUTE

SourceFile is a full source path. Do not look it up in the SourceDisksNames section of the INF file.

SP_COPY_SOURCEPATH_ABSOLUTE

SourcePathRoot is the full path part of the source file. Ignore the relative source specified in the SourceDisksNames section of the INF file for the source media where the file is located. This flag is ignored if SP_COPY_SOURCE_ABSOLUTE is specified.

SP_COPY_FORCE_IN_USE

If the target exists, behave as if it is in use and queue the file for copying on the next system reboot.

SP_COPY_FORCE_NOOVERWRITE

Check whether the target file exists, and, if so, the file is not overwritten. The caller is not notified.

SP_COPY_FORCE_NEWER

Examine each file being copied to see if its version resources (or timestamps for non-image files) indicate that it is not newer than an existing copy on the target. If the file being copied is not newer, the file is not copied. The caller is not notified. The function returns FALSE, and GetLastError returns NO_ERROR.

CopyMsgHandler

This optional parameter points to a callback function to be notified of various conditions that may arise during the file copy.

Context

This optional parameter points to a caller-defined value that is passed as the first parameter of the callback function.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

If GetLastError returns NO_ERROR, the file copy operation was not completed because the callback function returned FALSE.

Remarks

If a UNC directory is specified as the target directory of a file installation, you must ensure it exists before you call SetupInstallFile. The setup functions do not check for the existence of and do not create UNC directories. If the target UNC directory does not exist, the file installation will fail.

See Also

SetupCloseFileQueue, SetupCommitFileQueue, SetupOpenFileQueue, SetupQueueCopy


SetupInstallFileEx [New - Windows NT]
SetupInstallFileEx

[New - Windows NT]

The SetupInstallFileEx function installs a file as specified either by an INFCONTEXT returned by SetupFindXXXLine or explicitly by the filename and path information. This function is the same as SetupInstallFile, except that a BOOL is returned indicating whether or not the file was in use.

BOOL SetupInstallFileEx(

HINF InfHandle,	// optional, handle to the INF file
PINFCONTEXT InfContext,	// optional, context of an INF file
PCTSTR SourceFile,	// optional, filename of the source
PCTSTR SourcePathRoot,	// optional, root path to the source
PCTSTR DestinationName,	// optional, filename after copy
DWORD CopyStyle,	// specifies copy behavior
PSP_FILE_CALLBACK CopyMsgHandler,	// optional, callback routine to use
PVOID Context,	// optional, callback routine context
PBOOL FileWasInUse	// receives the file in use information
);
Parameters

InfHandle

This optional parameter points to the handle of an INF file that contains the SourceDisksNames and SourceDisksFiles sections. If platform-specific sections exist for the user’s system (for example, SourceDisksNames.mips and SourceDisksFiles.mips), the platform-specific section will be used. If InfContext is not specified and CopySyle includes SP_COPY_SOURCE_ABSOLUTE or SP_COPY_SOURCEPATH_ABSOLUTE, InfHandle is ignored.

InfContext

This optional parameter supplies context for a line in a Copy Files section in an INF file. The routine looks this file up in the SourceDisksFiles section of InfHandle to get file copy information. If InfContext is not specified, SourceFile must be.

SourceFile

This optional parameter supplies the filename (no path) of the file to copy. The file is looked up in the SourceDisksFiles section. The SourceFile parameter must be specified if InfContext is not. However, SourceFile is ignored if InfContext is specified.

SourcePathRoot

This optional parameter supplies the root path for the file to be copied (for example, A:\ or F:\). Paths in the SourceDisksNames section are appended to this path. The SourcePathRoot parameter is ignored if CopyStyle includes the SP_COPY_SOURCE_ABSOLUTE flag.

DestinationName

This optional parameter can be used to specify a new name for the copied file. If InfContext is specified, DestinationName supplies the filename only (no path) of the target file. This parameter can be NULL to indicate that the target file should have the same name as the source file. If InfContext is not specified, DestinationName supplies the full target path and filename for the target.

CopyStyle

Flags that control the behavior of the file copy operation. These flags may be a combination of the following values:

SP_COPY_DELETESOURCE

Delete the source file upon successful copy. The caller is not notified if the delete fails.

SP_COPY_REPLACEONLY

Copy the file only if doing so would overwrite a file at the destination path.

SP_COPY_NEWER

Examine each file being copied to see if its version resources indicate that it is not newer than an existing copy on the target.

The file version information used during version checks is that specified in the dwFileVersionMS and dwFileVersionLS members of a VS_FIXEDFILEINFO structure, as filled in by the Win32 version functions. If one of the files does not have version resources, or if they have identical version information, the source file is considered newer.

If the source file is not newer, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied.

SP_COPY_NOOVERWRITE

Check whether the target file exists, and, if so, notify the caller who may veto the copy. If CopyMsgHandler is not specified, the file is not overwritten.

SP_COPY_NODECOMP

Do not decompress the file. When this flag is set, the target file is not given the uncompressed form of the source name (if appropriate). For example, copying f:\mips\cmd.ex_ to \\install\temp results in a target file of \\install\temp\cmd.ex_. If the SP_COPY_NODECOMP flag was not specified, the file would be decompressed and the target would be called \\install\temp\cmd.exe. The filename part of DestinationName, if specified, is stripped and replaced with the filename of the source file. When SP_COPY_NODECOMP is specified, SP_COPY_LANGUAGEAWARE and SP_COPY_NEWER are ignored.

SP_COPY_LANGUAGEAWARE

Examine each file being copied to see if its language differs from the language of any existing file already on the target. If so, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied.

SP_COPY_SOURCE_ABSOLUTE

SourceFile is a full source path. Do not look it up in the SourceDisksNames section of the INF file.

SP_COPY_SOURCEPATH_ABSOLUTE

SourcePathRoot is the full path part of the source file. Ignore the relative source specified in the SourceDisksNames section of the INF file for the source media where the file is located. This flag is ignored if SP_COPY_SOURCE_ABSOLUTE is specified.

SP_COPY_FORCE_IN_USE

If the target exists, behave as if it is in use and queue the file for copying on the next system reboot.

SP_COPY_IN_USE_NEEDS_REBOOT

If the file was in use during the copy operation, alert the user that the system needs to be rebooted.

SP_COPY_NO_SKIP

Do not give the user the option to skip a file.

SP_COPY_FORCE_NOOVERWRITE

Check whether the target file exists, and, if so, the file is not overwritten. The caller is not notified.

SP_COPY_FORCE_NEWER

Examine each file being copied to see if its version resources (or timestamps for non-image files) indicate that it is not newer than an existing copy on the target. If the file being copied is not newer, the file is not copied. The caller is not notified.

SP_COPY_WARNIFSKIP

If the user tries to skip a file, warn them that skipping a file may affect the installation. (Used for system-critical files.)

CopyMsgHandler

This optional parameter points to a callback function to be notified of various conditions that may arise during the file copy.

Context

Pointer to a caller-defined value that is passed as the first parameter of the callback function.

FileWasInUse

This optional parameter points to a caller-supplied variable in which this function returns a flag indicating whether the file was in use.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

If GetLastError returns NO_ERROR, the file copy operation was not completed because the callback function returned FALSE.

Remarks

This API is typically used when installing new versions of system files that are likely to be in use. It updates a BOOL value that indicates whether the file was in use. If the file was in use, then the file copy operation is post-poned until the system is rebooted.

If a UNC directory is specified as the target directory of a file installation, you must ensure it exists before you call SetupInstallFileEx. The setup functions do not check for the existence of and do not create UNC directories. If the target UNC directory does not exist, the file installation will fail.

See Also

SetupCloseFileQueue, SetupCommitFileQueue, SetupInstallFile, SetupOpenFileQueue, SetupQueueCopy, SetupPromptReboot


SetupInstallFilesFromInfSection [New - Windows NT]
SetupInstallFilesFromInfSection

[New - Windows NT]

The SetupInstallFilesFromInfSection function queues all the files in an INF file Copy Files section to be installed.

BOOL SetupInstallFilesFromInfSection(

HINF InfHandle,	// handle to the INF file
HINF LayoutInfHandle,	// optional, layout INF handle
HSPFILEQ FileQueue,	// handle to the file queue
PCTSTR SectionName,	// section to install files from
PCTSTR SourceRootPath,	// optional, root path to source files
UINT CopyFlags	// optional, specifies copy behavior
);
Parameters

InfHandle

Specifies a handle to an INF file that contains the section to be installed. The INF file must be a Windows 95- or Windows NT 4.0-style INF file; script-based INF files are not supported by SetupInstallFilesFromInfSection.

LayoutInfHandle

This optional parameter supplies a handle to the INF file that contains the SourceDisksFiles and SourceDisksNames sections. If LayoutInfHandle is not specified, then the SourceDisksFiles and SourceDisksNames sections from InfHandle will be used.

FileQueue

Supplies a handle to the queue to add installation operations to.

SectionName

Supplies the name of the section in InfHandle to operate on.

SourceRootPath

This optional parameter specifies a root path to the source files to copy. An example would be A:\ or \\pegasus\win\install.

CopyFlags

This optional parameter specifies a set of flags that control the behavior of the file copy operation. These flags may be a combination of the following values:

SP_COPY_DELETESOURCE

Delete the source file upon successful copy. The caller is not notified if the delete fails.

SP_COPY_REPLACEONLY

Copy the file only if doing so would overwrite a file at the destination path.

SP_COPY_NEWER

Examine each file being copied to see if its version resources indicate that it is not newer than an existing copy on the target.

The file version information used during version checks is that specified in the dwFileVersionMS and dwFileVersionLS members of a VS_FIXEDFILEINFO structure, as filled in by the Win32 version functions. If one of the files does not have version resources, or if they have identical version information, the source file is considered newer.

If the source file is not newer, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied.

SP_COPY_NOOVERWRITE

Check whether the target file exists, and, if so, notify the caller who may veto the copy. If CopyMsgHandler is not specified, the file is not overwritten.

SP_COPY_NODECOMP

Do not decompress the file. When this flag is set, the target file is not given the uncompressed form of the source name (if appropriate). For example, copying f:\mips\cmd.ex_ to \\install\temp results in a target file of \\install\temp\cmd.ex_. If the SP_COPY_NODECOMP flag was not specified, the file would be decompressed and the target would be called \\install\temp\cmd.exe. The filename part of DestinationName, if specified, is stripped and replaced with the filename of the source file. When SP_COPY_NODECOMP is specified, SP_COPY_LANGUAGEAWARE and SP_COPY_NEWER are ignored.

SP_COPY_LANGUAGEAWARE

Examine each file being copied to see if its language differs from the language of any existing file already on the target. If so, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied.

SP_COPY_SOURCE_ABSOLUTE

SourceFile is a full source path. Do not look it up in the SourceDisksNames section of the INF file.

SP_COPY_SOURCEPATH_ABSOLUTE

SourcePathRoot is the full path part of the source file. Ignore the relative source specified in the SourceDisksNames section of the INF file for the source media where the file is located. This flag is ignored if SP_COPY_SOURCE_ABSOLUTE is specified.

SP_COPY_FORCE_IN_USE

If the target exists, behave as if it is in use and queue the file for copying on the next system reboot.

SP_COPY_IN_USE_NEEDS_REBOOT

If the file was in use during the copy operation, alert the user that the system needs to be rebooted.

SP_COPY_NO_SKIP

Do not give the user the option to skip a file.

SP_COPY_FORCE_NOOVERWRITE

Check whether the target file exists, and, if so, the file is not overwritten. The caller is not notified.

SP_COPY_FORCE_NEWER

Examine each file being copied to see if its version resources (or timestamps for non-image files) indicate that it is not newer than an existing copy on the target. If the file being copied is not newer, the file is not copied. The caller is not notified.

SP_COPY_WARNIFSKIP

If the user tries to skip a file, warn them that skipping a file may affect the installation. (Used for system-critical files.)

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

SetupInstallFilesFromInfSection can be called multiple times to queue the files specified in multiple INF sections. After the queue has been successfully committed and the files have been copied, renamed, and/or deleted, SetupInstallFromInfSection can be called to perform registry and INI installation operations.

If a UNC directory is specified as the target directory of a file installation, you must ensure it exists before you call SetupInstallFilesFromInfSection. The setup functions do not check for the existence of and do not create UNC directories. If the target UNC directory does not exist, the file installation will fail.

See Also

SetupInstallServicesFromInfSection, SetupInstallFromInfSection


SetupInstallFromInfSection [New - Windows NT]
SetupInstallFromInfSection

[New - Windows NT]

The SetupInstallFromInfSection function carries out directives in an INF file Install section.

BOOL SetupInstallFromInfSection(

HWND Owner,	// optional, handle of a parent window
HINF InfHandle,	// handle to the INF file
PCTSTR SectionName,	// section of the INF file to install
UINT Flags,	// which lines to install from section
HKEY RelativeKeyRoot,	// optional, key for registry installs
PCTSTR SourceRootPath,	// optional, path for source files
UINT CopyFlags,	// optional, specifies copy behavior
PSP_FILE_CALLBACK MsgHandler,	// optional, specifies callback routine
PVOID Context,	// optional, callback routine context
HDEVINFO DeviceInfoSet,	// optional, device information set
PSP_DEVINFO_DATA DeviceInfoData	// optional, device info structure
);
Parameters

Owner

This optional parameter specifies the window handle of the window that owns any dialog boxes that are generated during installation, such as for disk prompting or file copying. If Owner is not specified, these dialog boxes become top-level windows.

InfHandle

Specifies the handle to the INF file that contains the section to be processed. The INF file must be a Windows 95- or Windows NT 4.0-style file; legacy INF files are not supported by SetupInstallFromInfSection.

SectionName

Supplies the name of the Install section in the INF file to process.

Flags

A set of flags that indicates what actions to perform. The flags can be a combination of the following:

SPINST_INIFILES

Perform INI-file operations (UpdateInis, UpdateIniFields lines in the Install section being processed).

SPINST_REGISTRY

Perform registry operations (AddReg, DelReg lines in the Install section being processed).

SPINST_INI2REG

Perform INI-file to registry operations (Ini2Reg lines in the Install section being processed).

SPINST_LOGCONFIG

This flag is only used when installing a device driver.

Perform logical configuration operations (LogConf lines in the Install section being processed). This flag is only used if DeviceInfoSet and DeviceInfoData are specified.

For more information about installing device drivers, LogConf, DeviceInfoSet, or DeviceInfoData, see the DDK Programmer’s Guide.

SPINST_FILES

Perform file operations (CopyFiles, DelFiles, RenFiles lines in the Install section being processed).

SPINST_ALL

Perform all installation operations.

RelativeKeyRoot

This optional parameter must be specified if Flags includes SPINST_REGISTRY or SPINST_INI2REG. Specifies a handle to a registry key to be used as the root when the INF file specifies HKR as the key.

SourceRootPath

Specifies the source root for file copies. An example would be A:\ or \\pegasus\win\install. If Flags includes SPINST_FILES, and SourceRootPath is NULL, the system provides a default root path.

CopyFlags

This optional parameter must be specified if Flags includes SPINST_FILES. Specifies flags to be passed to the SetupQueueCopySection function when files are queued for copy. These flags may be a combination of the following values:

SP_COPY_DELETESOURCE

Delete the source file upon successful copy. The caller is not notified if the delete fails.

SP_COPY_REPLACEONLY

Copy the file only if doing so would overwrite a file at the destination path.

SP_COPY_NEWER

Examine each file being copied to see if its version resources indicate that it is not newer than an existing copy on the target.

The file version information used during version checks is that specified in the dwFileVersionMS and dwFileVersionLS members of a VS_FIXEDFILEINFO structure, as filled in by the Win32 version functions. If one of the files does not have version resources, or if they have identical version information, the source file is considered newer.

If the source file is not newer, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied.

SP_COPY_NOOVERWRITE

Check whether the target file exists, and, if so, notify the caller who may veto the copy. If CopyMsgHandler is not specified, the file is not overwritten.

SP_COPY_NODECOMP

Do not decompress the file. When this flag is set, the target file is not given the uncompressed form of the source name (if appropriate). For example, copying f:\mips\cmd.ex_ to \\install\temp results in a target file of \\install\temp\cmd.ex_. If the SP_COPY_NODECOMP flag was not specified, the file would be decompressed and the target would be called \\install\temp\cmd.exe. The filename part of DestinationName, if specified, is stripped and replaced with the filename of the source file. When SP_COPY_NODECOMP is specified, SP_COPY_LANGUAGEAWARE and SP_COPY_NEWER are ignored.

SP_COPY_LANGUAGEAWARE

Examine each file being copied to see if its language differs from the language of any existing file already on the target. If so, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied.

SP_COPY_SOURCE_ABSOLUTE

SourceFile is a full source path. Do not look it up in the SourceDisksNames section of the INF file.

SP_COPY_SOURCEPATH_ABSOLUTE

SourcePathRoot is the full path part of the source file. Ignore the relative source specified in the SourceDisksNames section of the INF file for the source media where the file is located. This flag is ignored if SP_COPY_SOURCE_ABSOLUTE is specified.

SP_COPY_FORCE_IN_USE

If the target exists, behave as if it is in use and queue the file for copying on the next system reboot.

SP_COPY_IN_USE_NEEDS_REBOOT

If the file was in use during the copy operation inform the user that the system needs to be rebooted. This flag is only used when later calling SetupPromptReboot or SetupScanFileQueue.

SP_COPY_NO_SKIP

Do not give the user the option to skip a file.

SP_COPY_FORCE_NOOVERWRITE

Check whether the target file exists, and, if so, the file is not overwritten. The caller is not notified.

SP_COPY_FORCE_NEWER

Examine each file being copied to see if its version resources (or timestamps for non-image files) indicate that it is not newer than an existing copy on the target. If the file being copied is not newer, the file is not copied. The caller is not notified.

SP_COPY_WARNIFSKIP

If the user tries to skip a file, warn them that skipping a file may affect the installation. (Used for system-critical files.)

MsgHandler

This optional parameter must be specified if Flags includes SPINST-FILES. Specifies a callback function to be used when the file queue built by this routine internally is committed with the SetupCommitFileQueue function.

Context

This optional parameter must be specified if Flags includes SPINST_FIlLES. Specifies a value to be passed to the callback function when the file queue built by this routine internally is committed via SetupCommitFileQueue.

DeviceInfoSet

This optional parameter supplies a handle to a device information set. For more information about the Device Installer setup functions, see the DDK Programmer’s Guide.

DeviceInfoData

This optional parameter supplies a pointer to the SP_DEVINFO_DATA structure that provides a context to a specific element in the set specified by DeviceInfoSet. For more information about the Device Installer setup functions, see the DDK Programmer’s Guide.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

If a UNC directory is specified as the target directory of a file copy operation, you must ensure it exists before you call SetupInstallFromInfSection. The setup functions do not check for the existence of and do not create UNC directories. If the target UNC directory does not exist, the file installation will fail.

See Also

SetupInstallFilesFromInfSection, SetupInstallServicesFromInfSection


SetupInstallServicesFromInfSection [New - Windows NT]
SetupInstallServicesFromInfSection

[New - Windows NT]

The SetupInstallServicesFromInfSection function performs service installation and deletion operations specified in a Service Install section of an INF file.

BOOL SetupInstallServicesFromInfSection(

HINF InfHandle,	// handle to the open INF file
PCTSTR SectionName,	// section to install
DWORD Flags	// controls installation procedure
);
Parameters

InfHandle

Supplies the handle of an INF file that contains a Service Install section.

SectionName

Supplies the name of the Service Install section to process.

Flags

A flag that controls the installation.

SPSVCINST_TAGTOFRONT

Move the service's tag to the front of its group order list.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

See Also

SetupInstallFromInfSection, SetupInstallFilesFromInfSection


SetupIterateCabinet [New - Windows NT]
SetupIterateCabinet

[New - Windows NT]

The SetupIterateCabinet function iterates through all the files in a cabinet and sends a notification to a callback function for each file found.

BOOL SetupIterateCabinet(

PCTSTR CabinetFile,	// name of the cabinet file
DWORD Reserved,	// this parameter is not used
PSP_FILE_CALLBACK MsgHandler,	// callback routine to use
PVOID Context	// callback routine context
);
Parameters

CabinetFile

Specifies the cabinet (.CAB) file to iterate through.

Reserved

Not currently used.

MsgHandler

Supplies a pointer to a routine that will process the notifications SetupIterateCabinet returns as it iterates through the files in the cabinet file. The callback routine may then return a value specifying whether to decompress, copy, or skip the file.

Context

Specifies the context value that is passed into the routine specified in MsgHandler. This enables the callback routine to track values between notifications, without having to use global variables.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.


SetupLogFile [New - Windows NT]
SetupLogFile

[New - Windows NT]

The SetupLogFile function adds an entry to the log file.

BOOL SetupLogFile(

HSPFILELOG FileLogHandle,	// handle to the log file
PCTSTR LogSectionName,	// optional, name to group files by
PCTSTR SourceFileName,	// filename on source media
PCTSTR TargetFileName,	// filename in target directory
DWORD Checksum,	// optional, 32-bit checksum value
PCTSTR  DiskTagfile,	// optional, source media tag file
PCTSTR DiskDescription,	// optional, media description
PCTSTR OtherInfo,	// optional, additional information
DWORD Flags	// indicates whether OEM file
);
Parameters

FileLogHandle

Supplies the handle to the file log as returned by SetupInitializeFileLog. The caller must not have passed SPFILELOG_QUERYONLY when the log file was initialized.

LogSectionName

This optional parameter supplies the name for a logical grouping of names within the log file. Required if SPFILELOG_SYSTEMLOG was not passed when the file log was initialized. Otherwise, LogSectionName is optional.

SourceFileName

Supplies the name of the file as it exists on the source media from which it was installed. This name should be in whatever format is meaningful to the caller.

TargetFileName

Supplies the name of the file as it exists on the target. This name should be in whatever format is meaningful to the caller.

Checksum

This optional parameter supplies a 32-bit checksum value. Required for the system log.

DiskTagfile

This optional parameter specifies the tagfile for the media from which the file was installed. Required for the system log if SPFILELOG_OEMFILE is specified. Ignored for the system log if SPFILELOG_OEMFILE is not specified.

DiskDescription

This optional parameter provides the human-readable description of the media from which the file was installed. Required for the system log if SPFILELOG_OEMFILE is specified in the Flags parameter. Ignored for the system log if SPFILELOG_OEMFILE is not specified in the Flags parameter.

OtherInfo

This optional parameter supplies additional information to be associated with the file.

Flags

This parameter can be SPFILELOG_OEMFILE, which is meaningful only for the system log and indicates that the file is not supplied by Microsoft. This parameter can be used to convert an existing file's entry, such as when an OEM overwrites a Microsoft-supplied system file.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

See Also

SetupRemoveFileLogEntry


SetupOpenAppendInfFile [New - Windows NT]
SetupOpenAppendInfFile

[New - Windows NT]

The SetupOpenAppendInfFile function appends the information in an INF file to an INF file previously opened by SetupOpenInfFile.

BOOL SetupOpenAppendInfFile(

PCTSTR FileName,	// optional, name of the file to append
HINF InfHandle,	// handle of the file to append to
PUINT ErrorLine	// optional, receives error information
);
Parameters

FileName

If not NULL, FileName points to a null-terminated string containing the name (and optionally the path) of the INF file to be opened. If the filename does not contain path separator characters, it is searched for, first in the %windir%\inf directory, and then in the %windir%\system32 directory. If the filename contains path separator characters, it is assumed to be a full path specification and no further processing is performed on it. If FileName is NULL, the INF filename is retrieved from the LayoutFile value of the Version section in the existing INF file. The same search logic is applied to the filename retrieved from the LayoutFile key.

InfHandle

Existing INF handle to which this INF file will be appended.

ErrorLine

An optional parameter that points to a caller-supplied variable to which this function returns the (1-based) line number where an error occurred during loading of the INF file. This value is generally reliable only if GetLastError does not return ERROR_NOT_ENOUGH_MEMORY. If an out-of-memory condition does occur, ErrorLine may be 0.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

If FileName was not specified and there was no LayoutFile value in the Version section of the existing INF File, GetLastError returns ERROR_INVALID_DATA.

Remarks

This function can only be called for Windows 95- or Windows NT 4.0-style INF files. Otherwise, the function returns FALSE and GetLastError will return ERROR_INVALID_PARAMETER. The main purpose of this function is to combine an INF file with the source file location information contained in the file specified in the LayoutFile entry of the Version section (typically, LAYOUT.INF).

See Also

SetupOpenInfFile, SetupCloseInfFile


SetupOpenFileQueue [New - Windows NT]
SetupOpenFileQueue

[New - Windows NT]

The SetupOpenFileQueue function creates a setup file queue.

HSPFILEQ SetupOpenFileQueue(

VOID	// takes no parameters
);
Parameters

None.

Return Values

If the function succeeds, it returns a handle to a setup file queue. If there is not enough memory to create the queue, the function returns INVALID_HANDLE_VALUE.

Remarks

After the file queue has been committed and is no longer needed, SetupCloseFileQueue should be called to release the resources allocated during SetupOpenFileQueue.

See Also

SetupCloseFileQueue, SetupCommitFileQueue, SetupInstallFile, SetupQueueCopy, SetupQueueDelete, SetupQueueRename


SetupOpenInfFile [New - Windows NT]
SetupOpenInfFile

[New - Windows NT]

The SetupOpenInfFile function opens an INF file and returns a handle to it.

HINF SetupOpenInfFile(

PCTSTR FileName,	// name of the INF to open
PCTSTR InfClass,	// optional, the class of the INF file
DWORD InfStyle,	// specifies the style of the INF file
PUINT ErrorLine	// optional, receives error information
);
Parameters

FileName

Points to a null-terminated string containing the name (and optional path) of the INF file to be opened. If the filename does not contain path separator characters, it is searched for, first in the %windir%\inf directory, and then in the %windir%\system32 directory. If the filename contains path separator characters, it is assumed to be a full path specification and no further processing is performed on it.

InfClass

An optional parameter that points to a null-terminated string containing the class of INF file desired. For legacy INF files, this string must match the type specified in the OptionType value of the Identification section in the INF file (for example, OptionType=NetAdapter). For Windows 95- or Windows NT 4.0-style INF files, this string must match the Class value of the Version section (for example, Class=Net). If there is no entry in the Class value, but there is an entry for ClassGUID in the Version section, the corresponding class name for that GUID is retrieved and used for the comparison.

InfStyle

Specifies the style of INF file to open. May be a combination of the following flags:

INF_STYLE_OLDNT

Windows NT 3.x script-based INF files.

INF_STYLE_WIN4

Windows 95- or Windows NT 4.0-style INF files.

ErrorLine

An optional parameter that points to a caller-supplied variable to which this function returns the (1-based) line number where an error occurred during loading of the INF file. This value is generally reliable only if GetLastError does not return ERROR_NOT_ENOUGH_MEMORY. If an out-of-memory condition does occur, ErrorLine may be 0.

Return Values

The function returns a handle to the opened INF file if it is successful. Otherwise, the return value is INVALID_HANDLE_VALUE. Extended error information can be retrieved by a call to GetLastError.

Remarks

If the load fails because the INF file type does not match InfClass, the function returns FALSE and a call to GetLastError returns ERROR_CLASS_MISMATCH.

If multiple INF file styles are specified, the style of the INF file opened can be determined by calling the SetupGetInfInformation function.

Since there may be more than one class GUID with the same class name, callers interested in INF files of a particular class (that is, a particular class GUID) should retrieve the ClassGUID value from the INF file by calling SetupQueryInfVersionInformation.

See Also

SetupOpenAppendInfFile, SetupCloseInfFile, SetupGetInfInformation


SetupOpenMasterInf [New - Windows NT]
SetupOpenMasterInf

[New - Windows NT]

The SetupOpenMasterInf function opens the master INF file that contains file and layout information for files shipped with Windows NT.

HINF SetupOpenMasterInf(

VOID	// takes no parameters
);
Parameters

None.

Return Values

If SetupOpenMasterInf is successful, it returns a handle to the opened INF file that contains file/layout information for files shipped with Windows NT. Otherwise, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

See Also

SetupOpenInfFile, SetupOpenAppendInfFile


SetupPromptForDisk [New - Windows NT]
SetupPromptForDisk

[New - Windows NT]

The SetupPromptForDisk function displays a dialog box that prompts the user for a disk.

UINT SetupPromptForDisk(

HWND hwndParent,	// parent window of the dialog box
PCTSTR DialogTitle,	// optional, title of the dialog box
PCTSTR DiskName,	// optional, name of disk to insert
INPCTSTR PathToSource,	// optional, expected source path
PCTSTR FileSought,	// name of file needed
PCTSTR TagFile,	// optional, source media tag file
DWORD DiskPromptStyle,	// specifies dialog box behavior
PTSTR PathBuffer,	// receives the source location
DWORD PathBufferSize,	// size of the supplied buffer
PDWORD PathRequiredSize	// optional, buffer size needed
);
Parameters

hwndParent

Handle to the parent window for this dialog box.

DialogTitle

This optional parameter points to a null-terminated string specifying the dialog title. If this parameter is NULL, the default of ““%s--Files Needed”” (localized) is used. The “%s” is replaced with the text retrieved from the parent window. If no text is retrieved from the parent window, the title is “Files Needed”.

DiskName

This optional parameter points to a null-terminated string specifying the name of the disk to insert. If this parameter is NULL, the default “(Unknown)” (localized) is used.

PathToSource

This optional parameter points to a null-terminated string specifying the path part of the expected location of the file, for example, F:\mips. If not specified, the path where SetupPromptForDisk most recently successfully located a file is used. If that list is empty, a system default is used.

FileSought

Pointer to a null-terminated string specifying the name of the file needed (filename part only). The filename is displayed if the user clicks on the Browse button. This routine looks for the file using its compressed form names; therefore, you can pass cmd.exe and not worry that the file actually exists as cmd.ex_ on the source media.

TagFile

This optional parameter points to a null-terminated string specifying a tag file (filename part only) that identifies the presence of a particular removable media volume. If the currently selected path would place the file on removable media and a tag file is specified, SetupPromptForDisk looks for the tag file at the root of the drive to determine whether to continue.

For example, if PathToSource is A:\i386, the tagfile is disk1.tag, and the user types B:\i386 into the edit control of the prompt dialog box, the routine looks for B:\disk1.tag to determine whether to continue. If the tag file is not found, the function looks for the tagfile using PathToSource.

If a tag file is not specified, removable media works just like non-removable media and FileSought is looked for before continuing.

DiskPromptStyle

Specifies the behavior of the dialog box. This can be a combination of the following flags:

IDF_CHECKFIRST

Check for the file/disk before displaying the prompt dialog box, and, if present, return DPROMPT_SUCCESS immediately.

IDF_NOBEEP

Prevent the dialog box from beeping to get the user’s attention when it first appears.

IDF_NOBROWSE

Do not display the browse option.

IDF_NOCOMPRESSED

Do not check for compressed versions of the source file.

IDF_NODETAILS

Do not display detail information.

IDF_NOFOREGROUND

Prevent the dialog box from becoming the foreground window.

IDF_NOSKIP

Do not display the skip option.

IDF_OEMDISK

Prompt for a disk supplied by a hardware manufacturer.

IDF_WARNIFSKIP

Warn the user that skipping a file may affect the installation.

PathBuffer

This optional parameter points to a caller-supplied buffer that, upon return, receives the path (no filename) of the location specified by the user through the dialog box.

PathBufferSize

Specifies the size of the buffer pointed to by PathBuffer. It should be at least MAX_PATH long.

PathRequiredSize

This optional parameter points to a caller-supplied variable that receives the required size for PathBuffer.

Return Values

The function returns one of the following values:

DPROMPT_SUCCESS

The requested disk/file is present and accessible. If PathBuffer was specified, it contains the path to the file (not including the filename).

DPROMPT_CANCEL

The user clicked on the Cancel button.

DPROMPT_SKIPFILE

The user clicked on the Skip File button.

DPROMPT_BUFFERTOOSMALL

The provided PathBuffer is too small. Check PathRequiredSize for the actual size needed for the buffer.

DPROMPT_OUTOFMEMORY

There is insufficient memory to process the request.

Remarks

For the Unicode version of this function, the buffer sizes ReturnBufferSize and RequiredSize are specified in number of characters. This number includes the null terminator. For the ANSI version of this function, the sizes are specified in number of bytes.

If this function is called with a ReturnBuffer of NULL and a ReturnBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by RequiredSize. If the function succeeds in this, the return value is NO_ERROR. Otherwise, the return value is one of the values specified preceding.

Thus, you can call the function once to get the required buffer size, allocate the necessary memory, and then call the function a second time to retrieve the data. Using this technique, you can avoid errors due to an insufficient buffer size.

See Also

SetupCopyError, SetupDeleteError, SetupRenameError


SetupPromptReboot [New - Windows NT]
SetupPromptReboot

[New - Windows NT]

The SetupPromptReboot function asks the user if he wants to reboot the system, optionally dependent on whether any files in a committed file queue were in use during a file operation. If the user answers "yes" to the prompt, shutdown is initiated before this routine returns.

INT SetupPromptReboot(

HSPFILEQ FileQueue,	// optional, handle to a file queue
HWND Owner,	// parent window of this dialog box
BOOL ScanOnly	// optional, do not prompt user
);
Parameters

FileQueue

This optional parameter supplies a handle to the file queue upon which to base the decision about whether shutdown is necessary. If FileQueue is not specified, SetupPromptReboot assumes shutdown is necessary and asks the user what to do.

Owner

Supplies the handle for the parent window to own windows created by this function.

ScanOnly

This optional parameter enables you to specify whether or not to prompt the user when SetupPromptReboot is called.

If TRUE, the user is never asked about rebooting, and system shutdown is not initiated. In this case, FileQueue must be specified. If ScanOnly is FALSE, the user is asked about rebooting, as previously described.

Use ScanOnly to determine if shutdown is necessary separately from actually initiating a shutdown.

Return Values

The function returns a combination of the following flags or -1 if an error occurred:

SPFILEQ_FILE_IN_USE

At least one file was in use during the queue commit process and there are delayed file operations pending. This flag will only be set if FileQueue is specified.

SPFILEQ_REBOOT_RECOMMENDED

The system should be rebooted. Depending on other flags and user response to the shutdown query, shutdown may be underway.

SPFILEQ_REBOOT_IN_PROGRESS

System shutdown is in progress.

See Also

SetupPromptForDisk


SetupQueryFileLog [New - Windows NT]
SetupQueryFileLog

[New - Windows NT]

The SetupQueryFileLog function returns information from a setup file log.

BOOL SetupQueryFileLog(

HSPFILELOG FileLogHandle,	// handle to the log file
PCTSTR LogSectionName,	// optional, name to group by
PCTSTR TargetFileName,	// name of target file
SetupFileLogInfo DesiredInfo,	// specifies info to return
PTSTR DataOut,	// optional, receives info
DWORD ReturnBufferSize,	// size of supplied buffer
PDWORD RequiredSize	// optional, needed buffer size
);
Parameters

FileLogHandle

Supplies the handle to the file log as returned by SetupInitializeLogFile.

LogSectionName

This optional parameter supplies the section name for the log file in a format that is meaningful to the caller. Required for non-system logs. If no LogSectionName is specified for a system log, a default is supplied.

TargetFileName

Supplies the name of the file for which log information is desired.

DesiredInfo

Indicates what information should be returned to the DataOut buffer. It can take one of the following enumerated values:

Value	Meaning
SetupFileLogSourceFilename	The name of the source file as it exists on the source media
SetupFileLogChecksum	A 32-bit checksum value used by the system log
SetupFileLogDiskTagfile	The name of the tag file of the media source containing the source file
SetupFileLogDiskDescription	The human-readable description of the media where the source file resides
SetupFileLogOtherInfo	Additional information associated with the logged file
DataOut

This optional parameter points to a caller-supplied buffer in which this function returns the requested information for the file. Not all information is provided for every file. An error is not returned if an empty entry for the file exists in the log.

ReturnBufferSize

Supplies the size of the buffer, pointed to by DataOut. If the buffer is too small and DataOut is specified, data is not stored in the buffer and the function returns FALSE. If DataOut is not specified, the ReturnBufferSize parameter is ignored.

RequiredSize

This optional parameter points to a caller-supplied variable in which this function returns the required size of DataOut.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

For the Unicode version of this function, the buffer sizes ReturnBufferSize, and ReturnRequiredSize are specified in number of characters. This number includes the null terminator. For the ANSI version of this function, the sizes are specified in number of bytes.

If this function is called with a ReturnBuffer of NULL and a ReturnBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by RequiredSize. If the function succeeds in this, the return value is TRUE. Otherwise, the return value is FALSE and extended error information can be obtained by calling GetLastError.

Thus, you can call the function once to get the required buffer size, allocate the necessary memory, and then call the function a second time to retrieve the data. Using this technique, you can avoid errors due to an insufficient buffer size.

Remarks

If the value of DesiredInfo is greater than SetupFileLogOtherInfo the function will fail, and GetLastError will return ERROR_INVALID_PARAMETER.

See Also

SetupLogFile


SetupQueryInfFileInformation [New - Windows NT]
SetupQueryInfFileInformation

[New - Windows NT]

The SetupQueryInfFileInformation function returns an INF filename from an SP_INF_INFORMATION structure to a caller-supplied buffer.

BOOL SetupQueryInfFileInformation(

PSP_INF_INFORMATION InfInformation,	// structure that contains the INF info
UINT InfIndex,	// index of the file to investigate
PTSTR ReturnBuffer,	// optional, receives the information
DWORD ReturnBufferSize,	// size of the supplied buffer
PDWORD Required Size	// optional, buffer size needed
);
Parameters

InfInformation

Points to an SP_INF_INFORMATION structure returned from a call to the SetupGetInfInformation function.

InfIndex

The index of the constituent INF filename to retrieve. This index can be in the range [0, InfInformation.InfCount). Meaning that the values zero through, but not including, InfInformation.InfCount are valid.

ReturnBuffer

If not NULL, ReturnBuffer supplies a pointer to a caller-supplied buffer in which this function returns the full INF filename.

ReturnBufferSize

Specifies the size of the buffer pointed to by the ReturnBuffer parameter.

RequiredSize

If not NULL, points to a caller-supplied variable in which this function returns the required size for the buffer pointed to by the ReturnBuffer parameter. If ReturnBuffer is specified and the actual size is larger than ReturnBufferSize, the function fails and a call to GetLastError returns ERROR_INSUFFICIENT_BUFFER.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

For the Unicode version of this function, the buffer sizes PathBufferSize, and PathRequiredSize are specified in number of characters. This number includes the null terminator. For the ANSI version of this function, the sizes are specified in number of bytes.

If this function is called with a ReturnBuffer of NULL and a ReturnBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by RequiredSize. If the function succeeds in this, the return value is TRUE. Otherwise, the return value is FALSE and extended error information can be obtained by calling GetLastError.

Thus, you can call the function once to get the required buffer size, allocate the necessary memory, and then call the function a second time to retrieve the data. Using this technique, you can avoid errors due to an insufficient buffer size.

See Also

SetupGetInfInformation, SetupQueryInfVersionInformation


SetupQueryInfVersionInformation [New - Windows NT]
SetupQueryInfVersionInformation

[New - Windows NT]

The SetupQueryInfVersionInformation function returns INF file version information from an SP_INF_INFORMATION structure to a caller-supplied buffer.

BOOL SetupQueryInfVersionInformation(

PSP_INF_INFORMATION InfInformation,	// structure that contains INF info
UINT InfIndex,	// index of the file to investigate
PCTSTR Key,	// optional, the key to retrieve
PTSTR ReturnBuffer,	// optional, receives the version info
DWORD ReturnBufferSize,	// size of the supplied buffer
PDWORD RequiredSize	// optional, buffer size needed
);
Parameters

InfInformation

Points to an SP_INF_INFORMATION structure previously returned from a call to the SetupGetInfInformation function.

InfIndex

Specifies the index of the constituent INF file to retrieve version information from. This index can be in the range [0, InfInformation.InfCount).   Meaning that the values zero through, but not including, InfInformation.InfCount are valid.

Key

An optional parameter that points to a null-terminated string containing the key name whose associated string is to be retrieved. If this parameter is NULL, all resource keys are copied to the supplied buffer. Each string is null-terminated, with an extra null at the end of the list.

ReturnBuffer

If not NULL, ReturnBuffer points to a call-supplied character buffer in which this function returns the INF file style.

ReturnBufferSize

Specifies the size of the buffer pointed to by the ReturnBuffer parameter.

RequiredSize

If not NULL, points to a caller-supplied variable in which this function returns the size required for the buffer pointed to by the ReturnBuffer parameter. If ReturnBuffer is specified and the actual size is larger than the value specified by ReturnBufferSize, the function fails and a call to GetLastError returns ERROR_INSUFFICIENT_BUFFER.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

For the Unicode version of this function, the buffer sizes ReturnBufferSize, and ReturnRequiredSize are specified in number of characters. This number includes the null terminator. For the ANSI version of this function, the sizes are specified in number of bytes.

If this function is called with a ReturnBuffer of NULL and a ReturnBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by RequiredSize. If the function succeeds in this, the return value is TRUE. Otherwise, the return value is FALSE and extended error information can be obtained by calling GetLastError.

Thus, you can call the function once to get the required buffer size, allocate the necessary memory, and then call the function a second time to retrieve the data. Using this technique, you can avoid errors due to an insufficient buffer size.

If SetupQueryInfVersionInformation is called on a Windows NT 3.x INF file, then version information is generated from the Windows NT 3.x INF file in the following manner:

1.	The OptionType key in the Identification section of the Windows NT 3.x INF file is returned as the Class key value.

2.	The FileType key in the Signature section of the Windows NT 3.x INF file becomes the Signature key value.

3.	If the value of the FileType key of the Windows NT 3.x INF file is MICROSOFT_FILE, then the Provider key value is set to “Microsoft”.

The following table summarizes how the information is translated before it is passed into the SP_INF_INFORMATION structure.

Windows NT 3.x information	mapped to Windows 95 or Windows NT 4.0 data
[Identification] OptionType = Mouse	[Version] Class=Mouse
[Signature] FileType = MICROSOFT_FILE	Signature=MICROSOFT_FILE
(if the FileType is MICROSOFT_FILE)	Provider=“Microsoft”
See Also

SetupGetInfInformation, SetupQueryInfFileInformation


SetupQuerySourceList [New - Windows NT]
SetupQuerySourceList

[New - Windows NT]

The SetupQuerySourceList function queries the current list of installation sources. The list is built from the system and user-specific lists, and potentially overridden by a temporary list (see SetupSetSourceList).

BOOL SetupQuerySourceList(

DWORD Flags,	// specifies the list to query
PCTSTR **List,	// receives an array of sources
PUINT Count	// number of sources in the array
);
Parameters

Flags

These flags specify which list to query. This parameter can be any combination of the following values:

SRCLIST_SYSTEM

Query the system list.

SRCLIST_USER

Query the per-user list.

Note If the system and the user lists are both retrieved, they are merged with those items in the system list that appear first.

If none of the preceding flags are specified, the entire current (merged) list is returned.

SRCLIST_NOSTRIPPLATFORM

Normally, all paths are stripped of a platform-specific component if it is the final component. For example, a path stored in the registry as f:\mips is returned as f:\. If this flag is specified, the platform-specific component is not stripped.

List

Supplies a pointer to a caller-supplied variable in which this function returns a pointer to an array of sources. The caller must free this array with a call to SetupFreeSourceList.

Count

Supplies a pointer to a caller-supplied variable in which this function returns the number of sources in the list.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

See Also

SetupSetSourceList


SetupQueueCopy [New - Windows NT]
SetupQueueCopy

[New - Windows NT]

The SetupQueueCopy function adds a single file copy operation to a setup file queue.

BOOL SetupQueueCopy(

HSPFILEQ QueueHandle,	// handle to the file queue
PCTSTR SourceRootPath,	// path to the source file
PCTSTR SourcePath,	// optional, additional path info
PCTSTR SourceFileName,	// name of file to copy
PCTSTR SourceDescription,	// optional, source description
PCTSTR SourceTagFile,	// optional, source media tag file
PCTSTR TargetDirectory,	// directory to copy file to
PCTSTR TargetFileName,	// optional, name for copied file
DWORD CopyStyle	// specifies copy behavior
);
Parameters

QueueHandle

Supplies a handle to a setup file queue, as returned by SetupOpenFileQueue.

SourceRootPath

Supplies the root of the source for this copy, such as A:\.

SourcePath

This optional parameter supplies the path relative to SourceRootPath where the file can be found.

SourceFileName

Supplies the filename part of the file to be copied.

SourceDescription

This optional parameter supplies a description of the source media to be used during disk prompts.

SourceTagFile

This optional parameter supplies a tag file whose presence at SourceRootPath indicates the presence of the source media. If not specified, the file itself will be used as the tag file if required.

TargetDirectory

Supplies the directory where the file is to be copied.

TargetFileName

This optional parameter supplies the name of the target file. If not specified, the target file will have the same name as the source file.

CopyStyle

Flags that control the behavior of the file copy operation. These flags may be a combination of the following values:

SP_COPY_DELETESOURCE

Delete the source file upon successful copy. The caller is not notified if the delete fails.

SP_COPY_REPLACEONLY

Copy the file only if doing so would overwrite a file at the destination path. The caller is not notified.

SP_COPY_NEWER

Examine each file being copied to see if its version resources indicate that it is not newer than an existing copy on the target.

The file version information used during version checks is that specified in the dwFileVersionMS and dwFileVersionLS members of a VS_FIXEDFILEINFO structure, as filled in by the Win32 version functions. If one of the files does not have version resources, or if they have identical version information, the source file is considered newer.

If the source file is not newer, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied.

SP_COPY_NOOVERWRITE

Check whether the target file exists, and, if so, notify the caller who may veto the copy. If CopyMsgHandler is not specified, the file is not overwritten.

SP_COPY_NODECOMP

Do not decompress the file. When this flag is set, the target file is not given the uncompressed form of the source name (if appropriate). For example, copying f:\mips\cmd.ex_ to \\install\temp results in a target file of \\install\temp\cmd.ex_. If the SP_COPY_NODECOMP flag was not specified, the file would be decompressed and the target would be called \\install\temp\cmd.exe. The filename part of DestinationName, if specified, is stripped and replaced with the filename of the source file. When SP_COPY_NODECOMP is specified, SP_COPY_LANGUAGEAWARE and SP_COPY_NEWER are ignored.

SP_COPY_LANGUAGEAWARE

Examine each file being copied to see if its language differs from the language of any existing file already on the target. If so, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied.

SP_COPY_SOURCE_ABSOLUTE

SourceFile is a full source path. Do not look it up in the SourceDisksNames section of the INF file.

SP_COPY_SOURCEPATH_ABSOLUTE

SourcePathRoot is the full path part of the source file. Ignore the relative source specified in the SourceDisksNames section of the INF file for the source media where the file is located. This flag is ignored if SP_COPY_SOURCE_ABSOLUTE is specified.

SP_COPY_FORCE_IN_USE

If the target exists, behave as if it is in use and queue the file for copying on the next system reboot.

SP_COPY_IN_USE_NEEDS_REBOOT

If the file was in use during the copy operation, alert the user that the system needs to be rebooted.

SP_COPY_NO_SKIP

Do not give the user the option to skip a file.

SP_COPY_FORCE_NOOVERWRITE

Check whether the target file exists, and, if so, the file is not overwritten. The caller is not notified.

SP_COPY_FORCE_NEWER

Examine each file being copied to see if its version resources (or timestamps for non-image files) indicate that it is not newer than an existing copy on the target. If the file being copied is not newer, the file is not copied. The caller is not notified.

SP_COPY_WARNIFSKIP

If the user tries to skip a file, warn them that skipping a file may affect the installation. (Used for system-critical files.)

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

If a UNC directory is specified as the target directory of a file copy operation, you must ensure it exists before the queue is committed. The setup functions do not check for the existence of and do not create UNC directories. If the target UNC directory does not exist, the file copy will fail.

See Also

SetupQueueCopySection, SetupQueueDefaultCopy, SetupQueueDelete, SetupQueueRename


SetupQueueCopySection [New - Windows NT]
SetupQueueCopySection

[New - Windows NT]

The SetupQueueCopySection function places all the files in a section of an INF file in a setup queue for copying. The section must be in the correct Copy Files format and the INF file must contain SourceDisksFiles and SourceDisksNames sections (or have had the INF files containing those sections appended).

BOOL SetupQueueCopySection(

HSPFILEQ QueueHandle,	// handle of the file queue
PCTSTR SourceRootPath,	// path to the source media
HINF InfHandle,	// handle to the master INF file
HINF ListInfHandle,	// optional, handle to section INF
PCTSTR Section,	// INF section w/files to copy
DWORD CopyStyle	// specifies copy behavior
);
Parameters

QueueHandle

Supplies a handle to a setup file queue, as returned by SetupOpenFileQueue.

SourceRootPath

Supplies the root of the source for this copy, such as A:\.

InfHandle

This optional parameter points to the handle of an open INF file that contains the SourceDisksFiles and SourceDisksNames sections, and, if ListInfHandle is not specified, contains the section names. If platform-specific sections exist for the user’s system (for example, SourceDisksNames.mips and SourceDisksFiles.mips), the platform-specific section will be used. This handle must be for a Windows 95- or Windows NT 4.0-style INF file.

ListInfHandle

If specified, supplies a handle to an open INF file that contains the section to queue for copying. If ListInfHandle is not specified, InfHandle is assumed to contain the section.

Section

Supplies the name of the section to be queued for copy.

CopyStyle

Flags that control the behavior of the file copy operation. These flags may be a combination of the following values:

SP_COPY_DELETESOURCE

Delete the source file upon successful copy. The caller is not notified if the delete fails.

SP_COPY_REPLACEONLY

Copy the file only if doing so would overwrite a file at the destination path.

SP_COPY_NEWER

Examine each file being copied to see if its version resources indicate that it is not newer than an existing copy on the target.

The file version information used during version checks is that specified in the dwFileVersionMS and dwFileVersionLS members of a VS_FIXEDFILEINFO structure, as filled in by the Win32 version functions. If one of the files does not have version resources, or if they have identical version information, the source file is considered newer.

If the source file is not newer, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied.

SP_COPY_NOOVERWRITE

Check whether the target file exists, and, if so, notify the caller who may veto the copy. If CopyMsgHandler is not specified, the file is not overwritten.

SP_COPY_NODECOMP

Do not decompress the file. When this flag is set, the target file is not given the uncompressed form of the source name (if appropriate). For example, copying f:\mips\cmd.ex_ to \\install\temp results in a target file of \\install\temp\cmd.ex_. If the SP_COPY_NODECOMP flag was not specified, the file would be decompressed and the target would be called \\install\temp\cmd.exe. The filename part of DestinationName, if specified, is stripped and replaced with the filename of the source file. When SP_COPY_NODECOMP is specified, SP_COPY_LANGUAGEAWARE and SP_COPY_NEWER are ignored.

SP_COPY_LANGUAGEAWARE

Examine each file being copied to see if its language differs from the language of any existing file already on the target. If so, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied.

SP_COPY_SOURCE_ABSOLUTE

SourceFile is a full source path. Do not look it up in the SourceDisksNames section of the INF file.

SP_COPY_SOURCEPATH_ABSOLUTE

SourcePathRoot is the full path part of the source file. Ignore the relative source specified in the SourceDisksNames section of the INF file for the source media where the file is located. This flag is ignored if SP_COPY_SOURCE_ABSOLUTE is specified.

SP_COPY_FORCE_IN_USE

If the target exists, behave as if it is in use and queue the file for copying on the next system reboot.

SP_COPY_IN_USE_NEEDS_REBOOT

If the file was in use during the copy operation, alert the user that the system needs to be rebooted.

SP_COPY_NO_SKIP

Do not give the user the option to skip a file.

SP_COPY_FORCE_NOOVERWRITE

Check whether the target file exists, and, if so, the file is not overwritten. The caller is not notified.

SP_COPY_FORCE_NEWER

Examine each file being copied to see if its version resources (or timestamps for non-image files) indicate that it is not newer than an existing copy on the target. If the file being copied is not newer, the file is not copied. The caller is not notified.

SP_COPY_WARNIFSKIP

If the user tries to skip a file, warn them that skipping a file may affect the installation. (Used for system-critical files.)

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

If a UNC directory is specified as the target directory of a file copy operation, you must ensure it exists before the queue is committed. The setup functions do not check for the existence of and do not create UNC directories. If the target UNC directory does not exist, the file copy will fail.

See Also

SetupQueueCopy, SetupQueueDefaultCopy


SetupQueueDefaultCopy [New - Windows NT]
SetupQueueDefaultCopy

[New - Windows NT]

The SetupQueueDefaultCopy function adds a single file to a setup file queue for copying, using the default source media and destination as specified in an INF file.

BOOL SetupQueueDefaultCopy(

HSPFILEQQueueHandle,	// handle to the file queue
HINF InfHandle,	// handle to the INF file
PCTSTR SourceRootPath,	// path to the source media
PCTSTR SourceFileName,	// name of the file to copy
PCTSTR TargetFileName,	// name of the copied file
DWORD CopyStyle	// specifies copy behavior
);
Parameters

QueueHandle

Supplies a handle to a setup file queue, as returned by SetupOpenFileQueue.

InfHandle

Supplies a handle to an open INF file that contains the SourceDisksFiles and SourceDisksNames sections. If platform-specific sections exist for the user’s system (for example, SourceDisksNames.mips and SourceDisksFiles.mips), the platform-specific section will be used. This handle must be for a Windows 95- or Windows NT 4.0-style INF file.

SourceRootPath

Supplies the root directory of the source for this copy such as A:\.

SourceFileName

Supplies the filename of the file to be copied.

TargetFileName

Supplies the filename of the target file.

CopyStyle

Flags that control the behavior of the file copy operation. These flags may be a combination of the following values:

SP_COPY_DELETESOURCE

Delete the source file upon successful copy. The caller is not notified if the delete fails.

SP_COPY_REPLACEONLY

Copy the file only if doing so would overwrite a file at the destination path.

SP_COPY_NEWER

Examine each file being copied to see if its version resources indicate that it is not newer than an existing copy on the target.

The file version information used during version checks is that specified in the dwFileVersionMS and dwFileVersionLS members of a VS_FIXEDFILEINFO structure, as filled in by the Win32 version functions. If one of the files does not have version resources, or if they have identical version information, the source file is considered newer.

If the source file is not newer, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied.

SP_COPY_NOOVERWRITE

Check whether the target file exists, and, if so, notify the caller who may veto the copy. If CopyMsgHandler is not specified, the file is not overwritten.

SP_COPY_NODECOMP

Do not decompress the file. When this flag is set, the target file is not given the uncompressed form of the source name (if appropriate). For example, copying f:\mips\cmd.ex_ to \\install\temp results in a target file of \\install\temp\cmd.ex_. If the SP_COPY_NODECOMP flag was not specified, the file would be decompressed and the target would be called \\install\temp\cmd.exe. The filename part of DestinationName, if specified, is stripped and replaced with the filename of the source file. When SP_COPY_NODECOMP is specified, SP_COPY_LANGUAGEAWARE and SP_COPY_NEWER are ignored.

SP_COPY_LANGUAGEAWARE

Examine each file being copied to see if its language differs from the language of any existing file already on the target. If so, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied.

SP_COPY_SOURCE_ABSOLUTE

SourceFile is a full source path. Do not look it up in the SourceDisksNames section of the INF file.

SP_COPY_SOURCEPATH_ABSOLUTE

SourcePathRoot is the full path part of the source file. Ignore the relative source specified in the SourceDisksNames section of the INF file for the source media where the file is located. This flag is ignored if SP_COPY_SOURCE_ABSOLUTE is specified.

SP_COPY_FORCE_IN_USE

If the target exists, behave as if it is in use and queue the file for copying on the next system reboot.

SP_COPY_IN_USE_NEEDS_REBOOT

If the file was in use during the copy operation, alert the user that the system needs to be rebooted.

SP_COPY_NO_SKIP

Do not give the user the option to skip a file.

SP_COPY_FORCE_NOOVERWRITE

Check whether the target file exists, and, if so, the file is not overwritten. The caller is not notified.

SP_COPY_FORCE_NEWER

Examine each file being copied to see if its version resources (or timestamps for non-image files) indicate that it is not newer than an existing copy on the target. If the file being copied is not newer, the file is not copied. The caller is not notified.

SP_COPY_WARNIFSKIP

If the user tries to skip a file, warn them that skipping a file may affect the installation. (Used for system-critical files.)

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

If a UNC directory is specified as the target directory of a file copy operation, you must ensure it exists before the queue is committed. The setup functions do not check for the existence of and do not create UNC directories. If the target UNC directory does not exist, the file copy will fail.

The default destination used by this function is specified by the DefaultDestDir key in the DestinationDirs section of an INF file.

See Also

SetupQueueCopy, SetupQueueCopySection


SetupQueueDelete [New - Windows NT]
SetupQueueDelete

[New - Windows NT]

The SetupQueueDelete function places an individual file delete operation on a setup file queue.

BOOL SetupQueueDelete(

HSPFILEQ QueueHandle,	// handle to the file queue
PCTSTR PathPart1,	// path to the file to delete
PCTSTR PathPart2	// optional, additional path info
);
Parameters

QueueHandle

Supplies a handle to a setup file queue, as returned by SetupOpenFileQueue.

PathPart1

Supplies the first part of the path of the file to be deleted. If PathPart2 is not specified, PathPart1 is the full path of the file to be deleted.

PathPart2

This optional parameter supplies the second part of the path of the file to be deleted. This is appended to PathPart1 to form the full path of the file to be deleted. The function checks for and collapses duplicated path separators when it combines PathPart1 and PathPart2.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

Since delete operations are assumed to take place on fixed media, the user will not be prompted when the queue is committed.

See Also

SetupQueueCopy, SetupQueueDeleteSection, SetupQueueRename


SetupQueueDeleteSection [New - Windows NT]
SetupQueueDeleteSection

[New - Windows NT]

The SetupQueueDeleteSection function queues all the files in a section of an INF file for deletion. The section must be in the correct Delete Files format and the INF file must contain a DestinationDirs section.

BOOL SetupQueueDeleteSection(

HSPFILEQ QueueHandle,	// handle to the file queue
HINF InfHandle,	// handle to the INF file
HINF ListInfHandle,	// optional, handle to section INF
PCTSTR Section	// INF section that lists the files to delete
);
Parameters

QueueHandle

Supplies a handle to a setup file queue, as returned by SetupOpenFileQueue.

InfHandle

Supplies a handle to an open INF file that contains the DestinationDirs section. If ListInfHandle is not specified, InfHandle contains the section name. This handle must be for a Windows 95- or Windows NT 4.0-style INF file.

ListInfHandle

This optional parameter points to the handle of an open INF file that contains the section to queue for deletion. If ListInfHandle is not specified, InfHandle is assumed to contain the section name.

Section

Supplies the name of the section to be queued for deletion.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

See Also

SetupQueueCopySection, SetupQueueDelete, SetupQueueRenameSection


SetupQueueRename [New - Windows NT]
SetupQueueRename

[New - Windows NT]

The SetupQueueRename function places an individual file rename operation on a setup file queue.

BOOL SetupQueueRename(

HSPFILEQ QueueHandle,	// handle to the file queue
PCTSTR SourcePath,	// path to the file to rename
PCTSTR SourceFileName,	// optional, source filename
PCTSTR TargetPath,	// optional, new path for file
PCTSTR TargetFileName	// optional, new name for file
);
Parameters

QueueHandle

Supplies a handle to a setup file queue, as returned by SetupOpenFileQueue.

SourcePath

Supplies the source path of the file to be renamed. If SourceFileName is not specified, SourcePath is assumed to be the full path.

SourceFileName

This optional parameter supplies the filename part of the file to be renamed. If not specified, SourcePath is the full path.

TargetPath

This optional parameter supplies the target directory and the rename operation is actually a mover operation. If TargetPath is not specified, the file is renamed but remains in its current location.

TargetFileName

This optional parameter supplies the name of the new name for the source file.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

Since rename operations are assumed to take place on fixed media, the user will not be prompted when the queue is committed.

See Also

SetupQueueDelete, SetupQueueCopy, SetupQueueRenameSection


SetupQueueRenameSection [New - Windows NT]
SetupQueueRenameSection

[New - Windows NT]

The SetupQueueRenameSection function queues a section in an INF file for renaming. The section must be in the correct rename list section format and the INF file must contain a DestinationDirs section.

BOOL SetupQueueRenameSection(

HSPFILEQ QueueHandle,	// handle to the file queue
HINF InfHandle,	// handle to the INF file
HINF ListInfHandle,	// optional, section INF handle
PCTSTR Section	// section that lists the files to rename
);
Parameters

QueueHandle

Supplies a handle to a setup file queue, as returned by SetupOpenFileQueue.

InfHandle

A handle to the INF file that contains the DestinationDirs section. If ListInfHandle is not specified, InfHandle contains the section name. This handle must be for a Windows 95- or Windows NT 4.0-style INF file.

ListInfHandle

This optional parameter supplies a handle to an INF file that contains the section to queue for renaming. If ListInfHandle is not specified, InfHandle is assumed to contain the section name.

Section

Supplies the name of the section to be queued for renaming.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

You cannot queue file moves with SetupQueueRenameSection because the form of a rename list section limits section renaming to within the same directory.

See Also

SetupQueueCopySection, SetupQueueDeleteSection, SetupQueueRename


SetupRemoveFileLogEntry [New - Windows NT]
SetupRemoveFileLogEntry

[New - Windows NT]

The SetupRemoveFileLogEntry function removes an entry or section from a file log.

BOOL SetupRemoveFileLogEntry(

HSPFILELOG FileLogHandle,	// handle to the log file
PCTSTR LogSectionName,	// optional, name to group by
PCTSTR TargetFileName	// optional, name in target dir
);
Parameters

FileLogHandle

Supplies the handle to the file log as returned by SetupInitializeFileLog. The caller must not have passed SPFILELOG_QUERYONLY when the log file was initialized.

LogSectionName

This optional parameter supplies the name for a logical grouping of names within the log file. Required for non-system logs. Otherwise, LogSectionName is optional.

TargetFileName

This optional parameter supplies the name of the file as it exists on the target. This name should be in whatever format is meaningful to the caller. If not specified, the section specified by LogSectionName is removed. The main section for Windows NT files cannot be removed.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

See Also

SetupLogFile


SetupRemoveFromSourceList [New - Windows NT]
SetupRemoveFromSourceList

[New - Windows NT]

The SetupRemoveFromSourceList function removes a value from the list of installation sources for either the current user or the system. The system and user lists are merged at run time.

BOOL SetupRemoveFromSourceList(

DWORD Flags,	// the list to remove the source from
PCTSTR Source	// the source to remove
);
Parameters

Flags

These flags specify which list to remove the source from. This parameter can be any combination of the following values:

SRCLIST_SYSTEM

Remove the source to the per-system list. The caller must be an administrator.

SRCLIST_USER

Remove the source to the per-user list.

SRCLIST_SYSIFADMIN

If the caller is an administrator, the source is removed from the per-system list; if the caller is not an administrator, the source is removed from the per-user list for the current user.

Note  If a temporary list is currently in use (see SetupSetSourceList), the preceding flags are ignored and the source is removed from the temporary list.

SRCLIST_SUBDIRS

Remove all subdirectories of the source.

Source

Pointer to the source to remove from the list.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

See Also

SetupAddToSourceList, SetupSetSourceList


SetupRenameError [New - Windows NT]
SetupRenameError

[New - Windows NT]

The RenameError function generates a dialog box that informs the user of a file renaming error.

UINT SetupRenameError(

HWND hwndParent,	// parent window for this dialog box
PCTSTR DialogTitle,	// optional, title for this dialog box
PCTSTR SourceFile,	// source file of the rename error
PCTSTR TargetFile,	// target file of the rename error
UINT Win32ErrorCode,	// the error encountered
DWORD Style	// specifies formatting for this dialog box
);
Parameters

hwndParent

Handle to the parent window for this dialog box.

DialogTitle

This optional parameter points to a null-terminated string specifying the error dialog box title. If this parameter is NULL, the default title of “Rename Error” (localized) is used.

SourceFile

Pointer to a null-terminated string specifying the full path of the source file on which the operation failed.

TargetFile

Pointer to a null-terminated string specifying the full path of the target file on which the operation failed.

Win32ErrorCode

The Win32 error code encountered during the file operation. For information about Win32 error codes, see the WINERROR.H file included with the Win32 SDK.

Style

Specifies flags that control display formatting and behavior of the dialog box. This parameter can be one of the following flags:

IDF_NOBEEP

Prevent the dialog box from beeping to get the user’s attention when it first appears.

IDF_NOFOREGROUND

Prevent the dialog box from becoming the foreground window.

Return Values

This function returns one of the following values:

DPROMPT_SUCCESS

The user retried the operation and it was successful.

DPROMPT_CANCEL

The user clicked on the Cancel button.

DPROMPT_SKIPFILE

The user clicked on the Skip File button.

DPROMPT_OUTOFMEMORY

There is insufficient memory to process the request.

See Also

SetupCopyError, SetupDeleteError, SetupPromptForDisk


SetupScanFileQueue [New - Windows NT]
SetupScanFileQueue

[New - Windows NT]

The SetupScanFileQueue function scans a setup file queue, performing an operation on each node in its copy list. The operation is specified by a set of flags. This function can be called either before or after the queue has been committed

BOOL SetupScanFileQueue(

HSPFILEQ FileQueue,	// handle to the file queue
DWORD Flags,	// control scan operation
HWND Window,	// optional, specifies a parent window
PSP_FILE_CALLBACK CallbackRoutine,	// optional, callback routine to use
PVOID CallbackContext,	// optional, callback routine context
PDWORD Result	// receives scan result
);
Parameters

FileQueue

Supplies a handle to the setup file queue whose copy list is to be scanned/iterated.

Flags

Values that control how the scan operation is carried out. Flags can be a combination of the following values:

SPQ_SCAN_FILE_PRESENCE

Determine whether all target files in the copy queue are already present on the target.

SPQ_SCAN_USE_CALLBACK

For each node of the queue, call the callback routine. If the callback routine returns non-0, queue processing stops and SetupScanFileQueue returns FALSE immediately.

Either SPQ_SCAN_FILE_PRESENCE, or SPQ_SCAN_USE_CALLBACK must be specified.

SPQ_INFORM_USER

If this flag is specified and all the files in the queue pass the presence/validity check, SetupScanFileQueue informs the user that the operation being attempted requires files but they are already present on the target. This flag is ignored if SPQ_SCAN_FILE_PRESENCE is not specified.

Window

This optional parameter specifies the window to own dialog boxes that are presented. The Window parameter is not used if the Flags parameter does not contain SPQ_SCAN_FILE_PRESENCE or if Flags does not contain SPQ_SCAN_INFORM_USER.

CallbackRoutine

This optional parameter specifies a callback function to be called on each node of the copy queue. The notification code passed to the callback function is SPFILENOTIFY_QUEUESCAN. This parameter is required if Flags includes SPQ_SCAN_USE_CALLBACK.

Note  You must supply the callback routine specified by CallbackRoutine. The default queue callback routine does not support SetupScanFileQueue.

CallbackContext

This optional parameter points to a context that contains caller-defined data passed to the callback routine pointed to by CallbackRoutine.

Result

Supplies a pointer to a caller-supplied variable in which this function returns the result of the scan operation.

Return Values

The function returns TRUE if all nodes in the queue were processed.

If the SPQ_SCAN_USE_CALLBACK flag was set, the value in Result is 0. The callback routine specified by CallbackRoutine is sent the notification SPFILENOTIFY_QUEUESCAN. CallbackRoutine.Param1 specifies a pointer to an array that contains the target path information. The pointer has been cast to an unsigned integer and must be recast to an TCHAR array of MAX_PATH elements before a callback routine can access the information. CallbackRoutine.Param2 is set to SPQ_DELAYED_COPY if the current queue node is in use and cannot be copied until the system is rebooted. Otherwise, CallbackRoutine.Param2 takes the value 0.

If SPQ_SCAN_USE_CALLBACK was not set, Result indicates whether the queue passed the presence/validity check as shown in the following table.

Result	Meaning
0	The queue failed the check or it passed the check but SPQ_SCAN_INFORM_USER was specified and the user wants new copies of the files.
1	The queue passed the check and, if SPQ_SCAN_INFORM_USER was specified, the user indicated that copying is not required. The copy queue is empty and there are no elements on the delete or rename queues, so the caller can skip queue commit.
2	The queue passed the check and, if SPQ_SCAN_INFORM_USER was specified, the user indicated that copying is not required. The copy queue is empty but there are elements on the delete or rename queues, so the call cannot skip queue commit.
The function returns FALSE if an error occurred or the callback function returned non-0. If Result is non-0, it is the value returned by the callback function that stopped queue processing. If Result is 0, extended error information can be retrieved by a call to GetLastError.

See Also

SetupCommitFileQueue, SetupDefaultQueueCallback


SetupSetDirectoryId [New - Windows NT]
SetupSetDirectoryId

[New - Windows NT]

The SetupSetDirectoryId function associates a directory identifier in an INF file with a particular directory.

BOOL SetupSetDirectoryId(

HINF InfHandle,	// handle to the INF file
DWORD Id,	// optional, DIRID to assign to Directory
PCTSTR Directory	// optional, directory to map to identifier
);
Parameters

InfHandle

Handle for a loaded INF file.

Id

This optional parameter supplies the directory identifier (DIRID) to use for the association. This DIRID must be greater than or equal to DIRID_USER. If an association already exists for this DIRID, it is overwritten. If Id is not specified, the Directory parameter is ignored and the current set of user-defined DIRIDs is deleted.

Directory

This optional parameter supplies the directory path to associate with Id. If Directory is NULL, any directory associated with Id is unassociated. No error results if Id is not currently associated with a directory.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

ERROR_NOT_ENOUGH_MEMORY

Indicates that a memory allocation failed.

ERROR_INVALID_PARAMETER

The Id parameter is not greater than or equal to DIRID_USER or Directory is not a valid string.

Remarks

SetupSetDirectoryId can be used prior to queueing file copy operations, to specify a target location that is only known at runtime.

After setting the directory identifier, this function traverses all appended INF files, and, if any of them have unresolved string substitutions, attempts to re-apply string substitution to them based on the new DIRID mapping. Because of this, some INF values may change after calling SetupSetDirectoryId.

DIRID_ABSOLUTE_16BIT is not a valid value for Id. This ensures compatibility with 16-bit setupx.


SetupSetPlatformPathOverride [New - Windows NT]
SetupSetPlatformPathOverride

[New - Windows NT]

The SetupSetPlatformPathOverride function sets the platform path override or removes it if none is specified.

BOOL SetupSetPlatformPathOverride(

PCTSTR Override	// optional, platform replacement string
);
Parameters

Override

This optional parameter points to a string that contains the replacement platform information. For example, “mips”, “alpha”, “ppc”, or “i386”.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

If GetLastError returns ERROR_NOT_ENOUGH_MEMORY, SetupSetPlatformPathOverride was unable to store the Override string.

Remarks

SetPlatformPathOverride is used to change the source path when queuing files. If a platform path override has been set by a call to SetPlatformPathOverride, any setup function that queues file copy operations will examine the final component of the source path and if the final component matches the name of the user’s platform, replace it with the override string set by SetPlatformPathOverride.

For example, consider a MIPS-platform machine where the platform has been set to Alpha by a call to SetPlatformPathOverride. After the platform path override has been set, a file copy operation is queued with a source path of \\foo\bar\baz\mips\x.exe, the path will be changed to \\foo\bar\baz\alpha\x.exe.

The paths of file copy operations queued before the path override is set are not changed.

See Also

SetupSetDirectoryId


SetupSetSourceList [New - Windows NT]
SetupSetSourceList

[New - Windows NT]

The SetupSetSourceList function allows the caller to set the list of installation sources for either the current user or the system (common to all users).

BOOL SetupSetSourceList(

DWORD Flags,	// type of source list
PCTSTR *SourceList,	// array of sources listed
UINT SourceCount	// number of sources in the array
);
Parameters

Flags

These flags specify the type of list. This parameter can be a combination of the following values:

SRCLIST_SYSTEM

The list is the per-system Most Recently Used (MRU) list stored in the registry. The caller must be a member of the administrators local group.

SRCLIST_USER

The list is the per-user MRU list stored in the registry.

SRCLIST_TEMPORARY

The specified list is temporary and will be the only list accessible to the current process until SetupCancelTemporarySourceList is called or SetSourceList is called again.

Important

If a temporary list is set, sources will not be added to or deleted from the system or user lists, even if subsequent calls to SetupAddToSourceList or SetupRemoveFromSourceList explicitly specify those lists.

Note One of the SRCLIST_SYSTEM, SRCLIST_USER, or SRCLIST_TEMPORARY flags must be specified. SRCLIST_NOBROWSE

The user is not allowed to add or change sources when SetupPromptForDisk is used. This flag is typically used in combination with the SRCLIST_TEMPORARY flag.

SourceList

Pointer to an array of strings to use as the source list, as specified by the Flags parameter.

SourceCount

Specifies the number of elements in the array pointed to by SourceList.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

See Also

SetupAddToSourceList, SetupCancelTemporarySourceList, SetupRemoveFromSourceList


SetupTermDefaultQueueCallback [New - Windows NT]
SetupTermDefaultQueueCallback

[New - Windows NT]

The SetupTermDefaultQueueCallback function is called after a queue has finished committing. It frees resources allocated by previous calls to SetupInitDefaultQueueCallback or SetupInitDefaultQueueCallbackEx.

VOID SetupTermDefaultQueueCallback(

PVOID Context	// context used by the default callback routine
);
Parameters

Context

Supplies a pointer to the context used by the default callback routine.

Return Values

Does not return a value.

See Also

SetupInitDefaultQueueCallback, SetupInitDefaultQueueCallbackEx


SetupTerminateFileLog [New - Windows NT]
SetupTerminateFileLog

[New - Windows NT]

The SetupTerminateFileLog function releases resources associated with a file log.

BOOL SetupTerminateFileLog(

HSPFILELOG FileLogHandle	// handle of the log file to close
);
Parameter

FileLogHandle

Supplies the handle to the log file as returned by a call to SetupInitializeFileLog.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

See Also

SetupLogFile, SetupInitializeFileLog


Notifications

Notifications are values that a setup function sends to a callback routine to specify a state or event. Two parameters, Param1 and Param2, are sent with the notification, and contain additional information relevant to the notification.

The callback routine processes the notification and returns an unsigned integer to the setup function. Depending on the setup function, you can use this value may be used to specify an operation or user selection, or you may ignore it.

The setup functions send notifications to callback routines using the following syntax.

MsgHandler(          //the specified callback routine
    Context,         //context used by the callback routine
    Notification,    //notification code
    Param1,          //additional notification information
    Param2	           //additional notification information
);

The Context parameter is a void pointer to a context variable or structure that the callback routine can use to store information that must persist between subsequent calls to the callback routine.

Because the callback routine specifies the context’s implementation, and it is never referenced or altered by the setup functions, the context is not documented in the reference material for the notification messages that follow.

The Notification parameter specifies an unsigned integer value for an event or state that causes the setup function to call the callback routine.

Param1 and Param2 are optional parameters that can contain additional information relevant to the notification. These parameters are unsigned integers. If Param1 or  Param2 return information that is not an unsigned integer, it will be cast to an unsigned integer and must be recast to its original data type before it can be used by the callback routine.

Note  The following notifications represent every notification used by the setup functions. Individual functions will use a subset of these notifications. In other words, not every notification is used by every function.

The following notifications are used by the setup functions.

SPFILENOTIFY_COPYERROR	An error occurred during a file copying operation.
SPFILENOTIFY_DELETEERROR	An error occurred during a file deletion operation.
SPFILENOTIFY_ENDCOPY	A file copying operation has ended.
SPFILENOTIFY_ENDDELETE	A file deletion operation has ended.
SPFILENOTIFY_ENDQUEUE	The queue has finished committing.
SPFILENOTIFY_ENDRENAME	A file rename operation has ended.
SPFILENOTIFY_ENDSUBQUEUE	A subqueue (either copy, rename or delete) has ended.
SPFILENOTIFY_FILEEXTRACTED	The file has been extracted from the cabinet.
SPFILENOTIFY_FILEINCABINET	A file is encountered in the cabinet.
SPFILENOTIFY_FILEOPDELAYED	The file was in use, and the current operation has been delayed until the system is rebooted.
SPFILENOTIFY_LANGMISMATCH	The language of the current operation does not match the system language.
SPFILENOTIFY_NEEDMEDIA	New source media is needed.
SPFILENOTIFY_NEEDNEWCABINET	The current file is continued in the next cabinet.
SPFILENOTIFY_QUEUESCAN	A node in the file queue has been scanned.
SPFILENOTIFY_RENAMEERROR	An error occurred during a file renaming operation.
SPFILENOTIFY_STARTCOPY	A file copy operation has started.
SPFILENOTIFY_STARTDELETE	A file delete operation has started.
SPFILENOTIFY_STARTQUEUE	The queue has started to commit.
SPFILENOTIFY_STARTRENAME	A file rename operation has started.
SPFILENOTIFY_STARTSUBQUEUE	A subqueue (either copy, rename or delete) has started.
SPFILENOTIFY_TARGETEXISTS	A copy of the specified file already exists on the target.
SPFILENOTIFY_TARGETNEWER	A newer version of the specified file exists on the target.


SPFILENOTIFY_COPYERROR [New - Windows NT]
SPFILENOTIFY_COPYERROR

[New - Windows NT]

The SPFILENOTIFY_COPYERROR notification is sent to the callback routine if an error occurs during a file copy operation.

SPFILENOTIFY_COPYERROR

    Param1 = (UINT) FilePathInfo;

    Param2 = (UINT) ReturnBuffer;

Parameters

Param1

Pointer to a FILEPATHS structure.

Param2

Pointer to a buffer, of size MAX_PATH TCHAR elements, that stores new path information specified by the user.

Return Values

The callback should return one of the following values.

Value	Meaning
FILEOP_ABORT	Queue processing should be cancelled. SetupCommitFileQueue returns FALSE and GetLastError returns extended error information such as ERROR_CANCELLED (if the user canceled) or ERROR_NOT_ENOUGH_MEMORY.
FILEOP_NEWPATH	Retry the copy operation using the path the callback function placed in the buffer pointed to by the Param2 parameter. The callback routine should ensure that the path does not overflow the buffer size of a TCHAR array of MAX_PATH elements.
FILEOP_RETRY	The user chose to attempt the the copy operation again.
FILEOP_SKIP	The user chose to skip the file copy operation.
See Also

FILEPATHS, SetupCommitFileQueue, SetupDefaultQueueCallback


SPFILENOTIFY_DELETEERROR [New - Windows NT]
SPFILENOTIFY_DELETEERROR

[New - Windows NT]

The SPFILENOTIFY_DELETEERROR notification is sent to the callback routine if an error occurs during a file delete operation.

SPFILENOTIFY_DELETEERROR

    Param1 = (UINT) FilePathInfo;

    Param2 = (UINT) 0;

Parameters

Param1

Pointer to a FILEPATHS structure.

Param2

Unused.

Return Values

The callback routine should return one of the following values.

Value	Meaning
FILEOP_ABORT	Queue processing should be canceled. SetupCommitFileQueue returns FALSE and GetLastError returns extended error information such as ERROR_CANCELLED (if the user canceled) or ERROR_NOT_ENOUGH_MEMORY.
FILEOP_RETRY	The user chose to attempt the delete operation again.
FILEOP_SKIP	The user chose to skip the file delete operation.
See Also

FILEPATHS, SetupCommitFileQueue, SetupDefaultQueueCallback


SPFILENOTIFY_ENDCOPY [New - Windows NT]
SPFILENOTIFY_ENDCOPY

[New - Windows NT]

The SPFILENOTIFY_ENDCOPY notification is passed to the callback function when the queue completes a copy operation. This notification is sent even if the user cancels or if an error occurs.

SPFILENOTIFY_ENDCOPY

    Param1 = (UINT) FilePathInfo;

    Param2 = (UINT) 0;

Parameters

Param1

Pointer to a FILEPATHS structure. The Win32Error member of the FILEPATHS structure indicates the outcome of the copy operation.

Param2

Unused.

Return Values

The return code is ignored.

See Also

FILEPATHS, SetupCommitFileQueue, SetupDefaultQueueCallback


SPFILENOTIFY_ENDDELETE [New - Windows NT]
SPFILENOTIFY_ENDDELETE

[New - Windows NT]

The SPFILENOTIFY_ENDDELETE notification is returned to the callback routine when a queue completes a delete operation. This notification is sent even if the user cancels or if an error occurs.

SPFILENOTIFY_ENDDELETE

    Param1 = (UINT) FilePathInfo;

    Param2 = (UINT) 0;

Parameters

Param1

Pointer to a FILEPATHS structure. The Win32Error member of the FILEPATHS structure indicates the outcome of a copy operation.

Param2

Unused.

Return Values

The return code is ignored.

See Also

FILEPATHS, SetupCommitFileQueue, SetupDefaultQueueCallback


SPFILENOTIFY_ENDQUEUE [New - Windows NT]
SPFILENOTIFY_ENDQUEUE

[New - Windows NT]

The SPFILENOTIFY_ENDQUEUE notification is sent to the callback routine when all of the queued operations have been completed.

SPFILENOTIFY_ENDQUEUE

    Param1 = (UINT) Result;

    Param2 = (UINT) 0;

Parameters

Param1

TRUE if the queue was processed successfully, FALSE otherwise.

Param2

Unused.

Return Values

The return value is ignored.

See Also

SetupCommitFileQueue, SetupDefaultQueueCallback


SPFILENOTIFY_ENDRENAME [New - Windows NT]
SPFILENOTIFY_ENDRENAME

[New - Windows NT]

The SPFILENOTIFY_ENDRENAME notification is sent to the callback routine when the queue completes a rename operation. This notification is sent even if the user cancels or if an error occurs.

SPFILENOTIFY_ENDRENAME

    Param1 = (UINT) FilePathInfo;

    Param2 = (UINT) 0;

Parameters

Param1

Pointer to a FILEPATHS structure. The Win32Error member of the FILEPATHS structure indicates the outcome of the copy operation.

Param2

Unused.

Return Values

The return value is ignored.

See Also

FILEPATHS, SetupCommitFileQueue, SetupDefaultQueueCallback


SPFILENOTIFY_ENDSUBQUEUE [New - Windows NT]
SPFILENOTIFY_ENDSUBQUEUE

[New - Windows NT]

The SPFILENOTIFY_ENDSUBQUEUE notification is sent to the callback function when the queue completes all the operations in the delete, rename, or copy subqueue.

SPFILENOTIFY_ENDSUBQUEUE

    Param1 = (UINT) SubQueue;

    Param2 = (UINT) 0;

Parameters

Param1

Specifies which subqueue has been completed. This parameter can be one of the following values FILEOP_DELETE, FILEOP_RENAME, or FILEOP_COPY.

Param2

Unused.

Return Values

The return value is ignored.

See Also

SetupCommitFileQueue, SetupDefaultQueueCallback


SPFILENOTIFY_FILEEXTRACTED [New - Windows NT]
SPFILENOTIFY_FILEEXTRACTED

[New - Windows NT]

The SPFILENOTIFY_FILEEXTRACTED notification is sent to a callback routine by SetupIterateCabinet to indicate either that a file was extracted from the cabinet or that an extraction failed and cabinet processing has been canceled.

SPFILENOTIFY_FILEEXTRACTED

    Param1 = (UINT) FilePathInfo;

    Param2 = (UINT) 0;

Parameters

Param1

Pointer to a FILEPATHS structure that contains path information for the extracted file.  The SourceFile member of the FILEPATHS structure contains the full Win32 source path of the cabinet. The TargetFile member supplies the full Win32 target path of the file to be installed on the system.

Param2

Unused.

Return Values

The cabinet callback routine should return one of the following values.

Value	Meaning
NO_ERROR	No error was encountered, continue processing the cabinet.
ERROR_XXX	An error of the specified type occurred. SetupIterateCabinet will return FALSE. GetLastError will return the specified error code.
Note  There is no default cabinet callback routine supplied with the Setup API. Your setup application should supply a callback routine to handle the notifications sent by the SetupIterateCabinet function.

See Also

FILEPATHS, SetupIterateCabinet


SPFILENOTIFY_FILEINCABINET [New - Windows NT]
SPFILENOTIFY_FILEINCABINET

[New - Windows NT]

The SPFILENOTIFY_FILEINCABINET notification is sent to a callback routine by SetupIterateCabinet for each file found in the cabinet. The callback routine must return a value indicating whether to extract the file.

SPFILENOTIFY_FILEINCABINET

    Param1 = (UINT) FileInCabinetInfo;

    Param2 = (UINT) CabinetFile;

Parameters

Param1

Specifies the address to a FILE_IN_CABINET_INFO structure that contains information about the file in the cabinet.

Param2

Pointer to a null-terminated string that contains the filename of the cabinet file.

Return Values

Your callback routine should return one of the following.

Value	Meaning
FILEOP_SKIP	Do not extract the file, skip it.
FILEOP_DOIT	Extract the file.
If your callback routine returns FILEOP_DOIT, the name to use for the extracted file should be specified in the FullTargetName member of the FILE_IN_CABINET_INFO structure passed to the routine in Param1.

Note  There is no default cabinet callback routine. The setup application should supply a callback routine to handle the notifications sent by SetupIterateCabinet.

See Also

FILE_IN_CABINET_INFO,
SetupIterateCabinet


SPFILENOTIFY_FILEOPDELAYED [New - Windows NT]
SPFILENOTIFY_FILEOPDELAYED

[New - Windows NT]

The SPFILENOTIFY_FILEOPDELAYED notification is sent by SetupInstallFileEx or SetupCommitFileQueue to a callback routine when a file operation was delayed because the file was in use. The operation will be processed the next time the system is rebooted.

SPFILENOTIFY_FILEOPDELAYED

    Param1 = (UINT) FilePathInfo;

    Param2 = (UINT) 0;

Parameters

Param1

Pointer to a FILEPATHS structure.

If the delayed operation is a file copy operation, the FILEPATHS structure contains the following information.

FILEPATH member	Value
Win32Error	NO_ERROR
Flags	FILEOP_COPY
Source	The full Win32 path of the temporary file.  This temporary file will be copied to the target directory when the system is rebooted. The setup functions automatically generate a path for the temporary file.
Target	Specifies the full Win32 path of the actual target file.
If the delayed operation is a file delete operation, the FILEPATHS structure contains the following information.

FILEPATH member	Value
Win32Error	NO_ERROR
Flags	FILEOP_DELETE
Source	NULL
Target	Specifies the full Win32 path of the file to be deleted.
Param2

Is not used.

Return Values

The return value is ignored.

See Also

FILEPATHS, SetupCommitFileQueue, SetupInstallFile, SetupInstallFileEx, SetupInstallFromInfSection


SPFILENOTIFY_LANGMISMATCH [New - Windows NT]
SPFILENOTIFY_LANGMISMATCH

[New - Windows NT]

The SPFILENOTIFY_LANGMISMATCH notification is sent to the callback routine if the language of the file to be copied does not match the language of an existing target file. It can be sent to the callback routine alone or combined, by using the OR operator, with SPFILENOTIFY_TARGETEXISTS and/or SPFILENOTIFY_TARGETNEWER.

SPFILENOTIFY_LANGMISMATCH

    Param1 = (UINT) FilePathInfo;

    Param2 = (UINT) LanguageInfo;

Parameters

Param1

Pointer to a FILEPATHS structure that contains information about the paths of the source and target files.

Param2

An unsigned 32-bit value that contains information about the mis-matched languages. This DWORD stores the language identifier of the source file in the low word, and the language identifier of the existing target file in the high word.

Return Values

The callback routine should return one of the following values.

Value	Meaning
TRUE	Copy the file and overwrite the existing file.
FALSE	Skip the copy operation. Do not overwrite the existing file.
See Also

FILEPATHS, SetupCommitFileQueue, SetupDefaultQueueCallback, SetupInstallFile, SetupInstallFileEx, SetupInstallFromInfSection


SPFILENOTIFY_NEEDMEDIA [New - Windows NT]
SPFILENOTIFY_NEEDMEDIA

[New - Windows NT]

The SPFILENOTIFY_NEEDMEDIA notification is sent to the callback routine when new media or a new cabinet file is required.

SPFILENOTIFY_NEEDMEDIA

    Param1 = (UINT) SourceMediaInfo;

    Param2 = (UINT) NewPathInfo;

Parameters

Param1

Pointer to a SOURCE_MEDIA structure.

Param2

Pointer to a character array to store new path information supplied by the user.  The buffer size is a TCHAR array of MAX_PATH elements. The path information returned by your setup application should not exceed this size.

Return Values

The callback routine should return one of the following.

Value	Meaning
FILEOP_NEWPATH	The media is present and the requested file is available at the win32 path specified in the buffer pointed to by Param2.
FILEOP_SKIP	Skip the requested file
FILEOP_ABORT	Abort queue processing. The SetupCommitFileQueue function returns FALSE. GetLastError returns extended error information, such as ERROR_CANCELLED if the user canceled.
FILEOP-DOIT	The media is available.
See Also

SetupCommitFileQueue, SetupDefaultQueueCallback, SOURCE_MEDIA


SPFILENOTIFY_NEEDNEWCABINET [New - Windows NT]
SPFILENOTIFY_NEEDNEWCABINET

[New - Windows NT]

The SPFILENOTIFY_NEEDNEWCABINET notification is sent by SetupIterateCabinet to indicate that the current file continues in another cabinet. Your callback routine can then call SetupPromptForDisk, or create its own dialog box to prompt the user to insert the next disk.

SPFILENOTIFY_NEEDNEWCABINET

    Param1 = (UINT) CabinetInfo;

    Param2 = (UINT) NewPath;

Parameters

Param1

Pointer to a CABINET_INFO structure that contains information about the cabinet and the file to be extracted.

Param2

If the callback returns NO_ERROR, this parameter is a pointer to a null-terminated string. If the string is not empty, it specifies a new path to the cabinet.

Return Values

Your routine should return one of the following values.

Value	Meaning
NO_ERROR	No error was encountered, continue processing the cabinet.
ERROR_XXX	An error of the specified type occurred. The SetupIterateCabinet function will return FALSE, and the specified error code will be returned by a call to GetLastError.
Note  There is no default cabinet callback routine; thus, you must supply a callback routine to handle the notifications sent by SetupIterateCabinet.

Remarks

If the callback routine returns NO_ERROR, SetupIterateCabinet checks the buffer pointed to by Param2. If the buffer is not empty, then it contains a new source path. If the buffer is empty, the source path is assumed to be unchanged.

Your callback function should ensure that the cabinet is accessible before it returns, calling the SetupPromptForDisk function, if new media needs to be inserted.

See Also

CABINET_INFO, SetupIterateCabinet


SPFILENOTIFY_QUEUESCAN [New - Windows NT]
SPFILENOTIFY_QUEUESCAN

[New - Windows NT]

The SPFILENOTIFY_QUEUESCAN notification is sent to a callback routine by SetupScanFileQueue for each node in the copy subqueue of the file queue. This only occurs if the SetupScanFileQueue function was called specifiying the flag SPQ_SCAN_USE_CALLBACK.

SPFILENOTIFY_QUEUESCAN

    Param1 = (UINT) TargetPath;

    Param2 = (UINT) DelayFlag;

Parameters

Param1

Specifies a null-terminated string that specifies the target path information for the file queued in the current node.

Param2

If the file in the current node of the queue is in use, Param2 takes the value SPQ_DELAYED_COPY. If the file is not in use, the value is zero.

Return Values

The callback routine should return a Win32 error code.

If the callback routine returns NO_ERROR, the queue scan continues.  If the routine returns any other Win32 error code, the queue scan aborts and SetupScanFileQueue returns FALSE.

Note  This notification is not handled by the SetupDefaultQueueCallback function.

See Also

SetupScanFileQueue


SPFILENOTIFY_RENAMEERROR [New - Windows NT]
SPFILENOTIFY_RENAMEERROR

[New - Windows NT]

The SPFILENOTIFY_RENAMEERROR notification is sent to the callback routine if an error occurs during a file rename operation.

SPFILENOTIFY_RENAMEERROR

    Param1 = (UINT) FilePathInfo;

    Param2 = (UINT) 0;

Parameters

Param1

Pointer to a FILEPATHS structure. The Win32Error member of the FILEPATHS structure specifies the error that occurred during the rename operation.

Param2

Unused.

Return Values

The callback routine should return one of the following.

Value	Meaning
FILEOP_RETRY	The user chose to attempt the rename operation again.
FILEOP_SKIP	The user chose to skip the file rename operation.
FILEOP_ABORT	Stop the queue commit. SetupCommitFileQueue returns FALSE. GetLastError returns extended error information such as ERROR_CANCELLED (if the user canceled) or ERROR_NOT_ENOUGH_MEMORY.
See Also

FILEPATHS, SetupCommitFileQueue, SetupDefaultQueueCallback


SPFILENOTIFY_STARTCOPY [New - Windows NT]
SPFILENOTIFY_STARTCOPY

[New - Windows NT]

The SPFILENOTIFY_STARTCOPY notification is sent to the callback function when the queue starts a file copy operation.

SPFILENOTIFY_STARTCOPY

    Param1 = (UINT) FilePathInfo;

    Param2 = (UINT) Operation;

Parameters

Param1

Pointer to a FILEPATHS structure.

Param2

Always has the value FILEOP_COPY.

Return Values

The callback routine should return one of the following values.

Value	Meaning
FILEOP_ABORT	Abort the queue commit process. The callback routine should call SetLastError to indicate the reason for termination. The SetupCommitFileQueue function returns FALSE and a subsequent call to GetLastError returns the error code set by the callback routine during the call to SetLastError.
FILEOP_DOIT	Perform the file copy operation.
FILEOP_SKIP	Skip the current copy operation.
See Also

FILEPATHS, SetupCommitFileQueue, SetupDefaultQueueCallback


SPFILENOTIFY_STARTDELETE [New - Windows NT]
SPFILENOTIFY_STARTDELETE

[New - Windows NT]

The SPFILENOTIFY_STARTDELETE notification is sent to the callback function when the queue starts a file delete operation.

SPFILENOTIFY_STARTDELETE

    Param1 = (UINT) FilePathInfo;

    Param2 = (UINT) Operation;

Parameters

Param1

Pointer to a FILEPATHS structure.

Param2

Always has the value FILEOP_DELETE.

Return Values

The callback routine should return one of the following values.

Value	Meaning
FILEOP_ABORT	Abort the queue commit. The callback routine should call SetLastError to indicate the reason for aborting. SetupCommitFileQueue returns FALSE and a subsequent call to GetLastError returns the error code set by the callback routine during the call to SetLastError.
FILEOP_DOIT	Perform the file copy operation.
FILEOP_SKIP	Skip the current copy operation.
See Also

FILEPATHS, SetupCommitFileQueue, SetupDefaultQueueCallback


SPFILENOTIFY_STARTQUEUE [New - Windows NT]
SPFILENOTIFY_STARTQUEUE

[New - Windows NT]

The SPFILENOTIFY_STARTQUEUE notification is sent to the callback routine when the queue commitment process starts.

SPFILENOTIFY_STARTQUEUE

    Param1 = (UINT) OwnerWindow;

    Param2 = (UINT) 0;

Parameters

Param1

Handle to the window that is to own the dialog boxes that the callback routine generates.

Param2

Unused.

Return Values

If an error occurs, the callback routine should call SetLastError, specifying the error, and then return 0.  The SetupCommitFileQueue function will return FALSE and a subsequent call to GetLastError will return the error code set by the callback routine.

If no error occurs, the callback routine should return a nonzero value.

See Also

SetupCommitFileQueue, SetupDefaultQueueCallback


SPFILENOTIFY_STARTRENAME [New - Windows NT]
SPFILENOTIFY_STARTRENAME

[New - Windows NT]

The SPFILENOTIFY_STARTRENAME notification is sent to the callback function when the queue starts a file rename operation.

SPFILENOTIFY_STARTRENAME

    Param1 = (UINT) FilePathInfo;

    Param2 = (UINT) Operation;

Parameters

Param1

Pointer to a FILEPATHS structure.

Param2

Always has the value FILEOP_RENAME.

Return Values

The callback routine should return one of the following values.

Value	Meaning
FILEOP_ABORT	Abort the queue commit. The callback routine should call SetLastError to indicate the reason for termination. SetupCommitFileQueue returns FALSE and a subsequent call to GetLastError returns the error code set by the callback routine during the call to SetLastError.
FILEOP_DOIT	Perform the file copy operation.
FILEOP_SKIP	Skip the current copy operation.
See Also

FILEPATHS, SetupCommitFileQueue, SetupDefaultQueueCallback


SPFILENOTIFY_STARTSUBQUEUE [New - Windows NT]
SPFILENOTIFY_STARTSUBQUEUE

[New - Windows NT]

The SPFILENOTIFY_STARTSUBQUEUE notification is sent to the callback function when the queue starts to process the operations in the delete, rename, or copy subqueue.

SPFILENOTIFY_STARTSUBQUEUE

    Param1 = (UINT) SubQueue;

    Param2 = (UINT) NumOperations;

Parameters

Param1

Specifies which subqueue has been started. This parameter can be any one of the values FILEOP_DELETE, FILEOP_RENAME, or FILEOP_COPY.

Param2

Specifies the number of file copy, rename, or delete operations in the subqueue.

Return Values

If an error occurs, the callback routine should call SetLastError, specifying the error, and then return 0.  The SetupCommitFileQueue function will return FALSE and a subsequent call to GetLastError will return the error code set by the callback routine.

If no error occurs, the callback routine should return a nonzero value.

See Also

SetupCommitFileQueue, SetupDefaultQueueCallback


SPFILENOTIFY_TARGETEXISTS [New - Windows NT]
SPFILENOTIFY_TARGETEXISTS

[New - Windows NT]

The SPFILENOTIFY_TARGETEXISTS notification is sent to the callback routine if the file to be copied was queued with the SP_COPY_NOOVERWRITE flag and that file already exists in the target directory. It can be sent to the callback routine alone or combined, by using the OR operator, with the SPFILENOTIFY_LANGMISMATCH and/or SPFILENOTIFY_TARGETNEWER notifications.

SPFILENOTIFY_TARGETEXISTS

    Param1 = (UINT) FilePathInfo;

    Param2 = (UINT) 0;

Parameters

Param1

Pointer to a FILEPATHS structure that contains information about the paths for the source and target files.

Param2

This parameter is not used unless this notification is combined, by using the OR operator, with the SPFILENOTIFY_LANGMISMATCH notification.

Return Values

The callback routine should return one of the following values.

Value	Meaning
TRUE	Overwrite the file in the target directory.
FALSE	Skip the current copy operation.
See Also

FILEPATHS, SetupCommitFileQueue, SetupDefaultQueueCallback, SetupInstallFile, SetupInstallFileEx, SetupInstallFromInfSection


SPFILENOTIFY_TARGETNEWER [New - Windows NT]
SPFILENOTIFY_TARGETNEWER

[New - Windows NT]

The SPFILENOTIFY_TARGETNEWER notification is sent to the callback routine if the file to be copied was queued with the SP_COPY_NEWER or SP_COPY_FORCE_NEWER flags specified and a newer version of the file already exists in the target directory. It can be sent to the callback routine alone or ORed together with SPFILENOTIFY_LANGMISMATCH and/or SPFILENOTIFY_TARGETEXISTS.

SPFILENOTIFY_TARGETNEWER

    Param1 = (UINT) FilePathInfo;

    Param2 = (UINT) 0;

Parameters

Param1

Pointer to a FILEPATHS structure that contains information about the paths for source and target files.

Param2

This parameter is not used unless this notification is combined, by using the OR operator, with SPFILENOTIFY_LANGMISMATCH.

Return Values

The callback routine should return one of the following values.

Value	Meaning
TRUE	Overwrite the file in the target directory.
FALSE	Skip the current copy operation.
See Also

FILEPATHS, SetupCommitFileQueue, SetupDefaultQueueCallback, SetupInstallFile, SetupInstallFileEx, SetupInstallFromInfSection


Errors

The following errors are specific to the Setup API.


Error Codes

The following error codes are specific to the Setup API.

INF Parsing Errors	Description
ERROR_EXPECTED_SECTION_NAME	A section name was expected, and not found.
ERROR_BAD_SECTION_NAME_LINE	The section name was not of the correct format.  (For example, a name not terminated by a right-hand bracket ( ] ).
ERROR_SECTION_NAME_TOO_LONG	The section name exceeded the maximum length of MAX_SECT_NAME_LEN.
ERROR_GENERAL_SYNTAX	The general syntax is incorrect.
INF Runtime Errors	Description
ERROR_WRONG_INF_STYLE	The INF is not of the type specified in the function call.  (This error will also be returned if an Windows NT 3.x INF file is passed into SetupOpenAppendInfFile).
ERROR_SECTION_NOT_FOUND	The section was not found in the INF file.
ERROR_LINE_NOT_FOUND	The line was not found in the INF section.


Constants

This section contains the reference for line device, phone device, and assisted telephony constants.


Line Device Constants

This section describes the constants used by the Telephony API. They are listed in alphabetical order.


LINEADDRCAPFLAGS_ Constants

The LINEADDRCAPFLAGS_ bit-flag constants are used in the dwAddrCapFlags field of the LINEADDRESSCAPS data structure to describe various Boolean address capabilities.

LINEADDRCAPFLAGS_FWDNUMRINGS

Specifies whether the number of rings for a no-answer can be specified when forwarding calls on no answer. If TRUE, the valid range is provided in LINEADDRESSCAPS.

LINEADDRCAPFLAGS_PICKUPGROUPID

Specifies whether a group ID is required for call pickup.

LINEADDRCAPFLAGS_SECURE

Specifies whether calls on this address can be made secure at call-setup time.

LINEADDRCAPFLAGS_BLOCKIDDEFAULT

Specifies whether the network by default sends or blocks caller ID information when making a call on this address. If TRUE, ID information is blocked by default; if FALSE, ID information is transmitted by default.

LINEADDRCAPFLAGS_BLOCKIDOVERRIDE

Specifies whether the default setting for sending or blocking of caller ID information can be overridden per call. If TRUE, override is possible; if FALSE, override is not possible.

LINEADDRCAPFLAGS_DIALED

Specifies whether a destination address can be dialed on this address for making a call. TRUE if a destination address must be dialed; FALSE if the destination address is fixed (as with a "hot phone").

LINEADDRCAPFLAGS_ORIGOFFHOOK

Specifies whether the originating party's phone can automatically be taken offhook when making calls.

LINEADDRCAPFLAGS_DESTOFFHOOK

Specifies whether the called party's phone can automatically be forced offhook when making calls.

LINEADDRCAPFLAGS_FWDCONSULT

Specifies whether call forwarding involves the establishment of a consultation call.

LINEADDRCAPFLAGS_SETUPCONFNULL

Specifies whether setting up a conference call starts out with an initial call (FALSE) or with no initial call (TRUE).

LINEADDRCAPFLAGS_AUTORECONNECT

Specifies whether dropping a consultation call automatically reconnects to the call on consultation hold. TRUE if reconnect happens automatically; otherwise, FALSE.

LINEADDRCAPFLAGS_COMPLETIONID

Specifies whether the completion IDs returned by lineCompleteCall are useful and unique. TRUE if useful; otherwise, FALSE.

LINEADDRCAPFLAGS_TRANSFERHELD

Specifies whether a hard-held call can be transferred. Often, only calls on consultation hold can be transferred.

LINEADDRCAPFLAGS_TRANSFERMAKE

Specifies whether an entirely new call can be established for use as a consultation call on transfer.

LINEADDRCAPFLAGS_CONFERENCEHELD

Specifies whether a hard-held call can be conferenced to. Often, only calls on consultation hold can be added to as a conference call.

LINEADDRCAPFLAGS_CONFERENCEMAKE

Specifies whether an entirely new call can be established for use as a consultation call (to add) on conference.

LINEADDRCAPFLAGS_PARTIALDIAL

Specifies whether partial dialing is available.

LINEADDRCAPFLAGS_FWDSTATUSVALID

Specifies whether the forwarding status in the LINEADDRESSSTATUS structure for this address is valid or is at most a "best estimate," given absence of accurate confirmation by the switch or network.

LINEADDRCAPFLAGS_FWDINTEXTADDR

Specifies whether internal and external calls can be forwarded to different forwarding addresses. This flag is meaningful only if forwarding of internal and external calls can be controlled separately. This flag is TRUE if internal and external calls can be forwarded to different destination addresses; otherwise, it is FALSE.

LINEADDRCAPFLAGS_FWDBUSYNAADDR

Specifies whether call forwarding for busy and for no answer can use different forwarding addresses. This flag is meaningful only if forwarding for busy and for no answer can be controlled separately. This flag is TRUE if forwarding for busy and for no answer can use different destination addresses; otherwise, it is FALSE.

LINEADDRCAPFLAGS_ACCEPTTOALERT

TRUE if an offering call must be accepted using lineAccept to start alerting the users at both ends of the call; otherwise, FALSE. This is typically only used with ISDN.

LINEADDRCAPFLAGS_CONFDROP

TRUE if lineDrop on a conference call parent also has the side effect of dropping (that is, disconnecting) the other parties involved in the conference call; FALSE if dropping a conference call still allows the other parties to talk among themselves.

LINEADDRCAPFLAGS_PICKUPCALLWAIT

TRUE if linePickup can be used to pick up a call detected by the user as a call-waiting call; otherwise, FALSE.

LINEADDRCAPFLAGS_PREDICTIVEDIALER

This address has enhanced call progress monitoring capabilities which can be applied to outbound calls to determine call states such as ringback, busy, specialinfo, and connected, or the media mode of the device answering the call. It may also have the ability to automatically transfer outbound calls to another address when a call reaches any of a predefined set of states.

LINEADDRCAPFLAGS_QUEUE

This address is not associated with a particular station or physical device, but is a holding place where calls wait for further processing. The calls placed in the queue may receive a particular treatment. They may also be automatically transferred when a particular resource becomes available (for example, if the queue is an ACD queue and calls are waiting for an available agent).

LINEADDRCAPFLAGS_ROUTEPOINT

This address is not associated with a particular station or physical device, but is a holding place where calls wait for routing by the application (the application examines the called address, and can redirect the call to another address). The call may also be automatically transferred if a routing timeout expires (the switch usually assumes a default routing).

LINEADDRCAPFLAGS_HOLDMAKESNEW

When a call on this address is placed on hold (using lineHold or external action), a new call is automatically created (most likely in LINECALLSTATE_DIALTONE).

LINEADDRCAPFLAGS_NOINTERNALCALLS

The address is associated with a direct CO line (trunk), and cannot be used to make internal calls on a PBX. The application can use this indication to assist the user in selecting the correct call appearance to use for making a call. When this bit is off, it does not necessarily indicate that the address can be used to make internal calls, because the service provider may not be cognizant of the line type.

LINEADDRCAPFLAGS_NOEXTERNALCALLS

The address is associated with an internal line on a PBX that is restricted in such a way that it cannot be used to place calls to an address outside the switch (for example, it is an intercom). The application can use this indication to assist the user in selecting the correct call appearance to use for making a call. When this bit is off, it does not necessarily indicate that the address can be used to make external calls, because the service provider may not be cognizant of the line type.

LINEADDRCAPFLAGS_SETCALLINGID

The application may choose to set the CallingPartyID member in LINECALLPARAMS when calling lineMakeCall and other functions that accept a LINECALLPARAMS structure. The service provider will, if the content of the ID is acceptable and a path is available, pass the ID along to the called party to indicate the identity of the calling party.

No extensibility. All 32 bits are reserved.


LINEADDRESSMODE_ Constants

The LINEADDRESSMODE_ bit-flag constants describe various ways of identifying an address on a line device.

LINEADDRESSMODE_ADDRESSID

The address is specified with a small integer in the range 0 to dwNumAddresses minus one, where dwNumAddresses is the value in the line's device capabilities.

LINEADDRESSMODE_DIALABLEADDR

The address is specified through its phone number.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

This constant is used to select an address on a line on which to originate a call. The usual model would select the address by means of its address ID. Address IDs are the mechanism used to identify addresses throughout TAPI. However, in some environments, when making a call, it is often more practical to identify a call's originating address by phone number rather than by address ID. One example is in the possible modeling of large numbers of stations (third party) on the switch by means of one line device with many addresses. The line represents the set of all stations, and each station is mapped to an address with its own primary phone number and address ID.


LINEADDRESSSHARING_ Constants

The LINEADDRESSSHARING_ bit-flag constants describe various ways an address can be shared between lines.

LINEADDRESSSHARING_PRIVATE

The address is private to the user's line; it is not assigned to any other station.

LINEADDRESSSHARING_BRIDGEDEXCL

The address is bridged to one or more other stations. The first line to activate a call on the line will have exclusive access to the address and calls that may exist on it. Other lines will not be able to use the bridged address while it is in use.

LINEADDRESSSHARING_BRIDGEDNEW

The address is bridged with one or more other stations. The first line to activate a call on the line will have exclusive access to only the corresponding call. Other applications that use the address will result in new and separate call appearances.

LINEADDRESSSHARING_BRIDGEDSHARED

The address is bridged with one or more other lines. All bridged parties can share in calls on the address, which then functions as a conference.

LINEADDRESSSHARING_MONITORED

This is an address whose idle/busy status is made available to this line.

No extensibility. All 32 bits are reserved.

The way in which an address is shared across lines can affect the behavior of that address. LINE_CALLSTATE and LINE_ADDRESSSTATE messages are sent to the application in response to activities by the bridging stations. It is through these messages that an application can track the status of the address.


LINEADDRESSSTATE_ Constants

The LINEADDRESSSTATE_ bit-flag constants describe various address status items.

LINEADDRESSSTATE_OTHER

Address-status items other than those listed below have changed. The application should check the current address status to determine which items have changed.

LINEADDRESSSTATE_DEVSPECIFIC

The device-specific item of the address status has changed.

LINEADDRESSSTATE_INUSEZERO

The address has changed to idle (it is not in use by any stations).

LINEADDRESSSTATE_INUSEONE

The address has changed from idle or in use by many bridged stations to being in use by just one station.

LINEADDRESSSTATE_INUSEMANY

The monitored or bridged address has changed from being in use by one station to being in use by more than one station.

LINEADDRESSSTATE_NUMCALLS

The number of calls on the address has changed. This is the result of events such as a new inbound call, an outbound call on the address, or a call changing its hold status. This flag covers changes in any of the fields dwNumActiveCalls, dwNumOnHoldCalls and dwNumOnHoldPendingCalls in the LINEADDRESSSTATUS structure. The application should check all three of these fields when it receives a LINE_ADDRESSSTATE (numCalls) message.

LINEADDRESSSTATE_FORWARD

The forwarding status of the address has changed, including possibly the number of rings for determining a no-answer condition. The application should check the address status to determine details about the address's current forwarding status.

LINEADDRESSSTATE_TERMINALS

The terminal settings for the address have changed.

LINEADDRESSSTATE_CAPSCHANGE

Indicates that, due to configuration changes made by the user or other circumstances, one or more of the fields in the LINEADDRESSCAPS structure for the address have changed. The application should use lineGetAddressCaps to read the updated structure. If a service provider sends a LINE_ADDRESSSTATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI to obtain the updated information.

No extensibility. All 32 bits are reserved.

An application is notified about changes to these status items in the LINE_ADDRESSSTATE message. The address's device capabilities indicate which address state changes can possibly be reported for this address.


LINEADDRFEATURE_ Constants

The LINEADDRFEATURE_ constants list the operations that can be invoked on an address.

LINEADDRFEATURE_FORWARD

The address can be forwarded.

LINEADDRFEATURE_MAKECALL

An outbound call can be placed on the address.

LINEADDRFEATURE_PICKUP

A call can be picked up at the address.

LINEADDRFEATURE_SETMEDIACONTROL

Media control can be set on this address.

LINEADDRFEATURE_SETTERMINAL

The terminal modes for this address can be set.

LINEADDRFEATURE_SETUPCONF

A conference call with a NULL initial call can be set up at this address.

LINEADDRFEATURE_UNCOMPLETECALL

Call completion requests can be canceled at this address.

LINEADDRFEATURE_UNPARK

Calls can be unparked using this address.

LINEADDRFEATURE_PICKUPHELD

The linePickup function (with a null destination address) can be used to pick up a call that is held on the address. This is normally used only in a bridged-exclusive arrangement.

LINEADDRFEATURE_PICKUPGROUP

The linePickup function can be used to pick up a call in the group.

LINEADDRFEATURE_PICKUPDIRECT

The linePickup function can be used to pick up a call on a specific address.

LINEADDRFEATURE_PICKUPWAITING

The linePickup function (with a null destination address) can be used to pick up a call waiting call. Note that this does not necessarily indicate that a waiting call is actually present, because it is often impossible for a telephony device to automatically detect such a call; it does, however, indicate that the hook-flash function will be invoked to attempt to switch to such a call.

Note  If none of the new modified "PICKUP" bits is set in the dwAddressFeatures member in LINEADDRESSSTATUS but the LINEADDRFEATURE_PICKUP bit is set, then any of the pickup modes may work; the service provider has simply not specified which ones.

LINEADDRFEATURE_FORWARDFWD

The lineForward function can be used to forward calls on the address to other numbers. LINEADDRFEATURE_FORWARD will also be set.

LINEADDRFEATURE_FORWARDDND

The lineForward function (with an empty destination address) can be used to turn on the Do Not Disturb feature on the address. LINEADDRFEATURE_FORWARD will also be set.

Note  If neither of the new modified "FORWARD" bits is set in the dwAddressFeatures member in LINEADDRESSSTATUS but the LINEADDRFEATURE_FORWARD bit is set, then any of the forward modes may work; the service provider has simply not specified which ones.

No extensibility. All 32 bits are reserved.

This constant is used both in LINEADDRESSCAPS (returned by lineGetAddressCaps) and in LINEADDRESSSTATUS (returned by lineGetAddressStatus). LINEADDRESSCAPS reports the availability of the address features by the service provider (mainly the switch) for a given address. An application would make this determination when it initializes. The LINEADDRESSSTATUS structure reports, for a given address, which address features can actually be invoked while the address is in the current state. An application would make this determination dynamically after address-state changes, typically caused by call-related activities on the address.


LINEAGENTFEATURE_ Constants

The LINEAGENTFEATURE_ constants list features that are available for an agent on an address.

LINEAGENTFEATURE_SETAGENTGROUP

The lineSetAgentGroup function may be invoked on this address.

LINEAGENTFEATURE_SETAGENTSTATE

The lineSetAgentState function may be invoked on this address.

LINEAGENTFEATURE_SETAGENTACTIVITY

The lineSetAgentActivity function may be invoked on this address.

LINEAGENTFEATURE_AGENTSPECIFIC

The lineAgentSpecific function may be invoked on this address.

LINEAGENTFEATURE_GETAGENTACTIVITYLIST

The lineGetAgentActivityList function may be invoked on this address.

LINEAGENTFEATURE_GETAGENTGROUPLIST

The lineGetAgentGroupList function may be invoked on this address.


LINEAGENTSTATE_ Constants

The LINEAGENTSTATE_ constants list the state of an agent on an address.

LINEAGENTSTATE_LOGGEDOFF

No agent is logged in on the address.

LINEAGENTSTATE_NOTREADY

The agent is logged in, but occupied with a task other than serving a call (such as on a break). No additional calls should be routed to the agent.

LINEAGENTSTATE_READY

The agent is ready to accept calls.

LINEAGENTSTATE_BUSYACD

The agent is busy handling a call routed from an ACD queue.

LINEAGENTSTATE_BUSYINCOMING

The agent is busy handling an inbound call that was not transferred to the agent from an ACD queue in which the agent is logged in.

LINEAGENTSTATE_BUSYOUTBOUND

The agent is busy handling an outbound call, such as one routed from a predictive dialing queue.

LINEAGENTSTATE_BUSYOTHER

The agent is busy handling another type of call, such as an outbound personal call not transferred to the agent by a predictive dialer. This value may also be used when the agent is known to be busy on a call but the type of call is unknown.

LINEAGENTSTATE_WORKINGAFTERCALL

The agent has completed the preceding call, but is still occupied with work related to that call. The agent should not receive additional calls.

LINEAGENTSTATE_UNKNOWN

The agent state is currently unknown, but may become known later. This may be a transitional state when a line or address is first opened.

LINEAGENTSTATE_UNAVAIL

The agent state is unknown and will never become known. In LINEADDRESSSTATUS, this condition may also be represented by the dwAgentState field being set to 0.

The upper 16-bits of this set of constants are reserved for device-specific extensions.


LINEAGENTSTATUS_ Constants

The LINEAGENTSTATUS_ constants list the update status of the members of the LINEAGENTSTATUS for an agent.

LINEAGENTSTATE_GROUP

The Group List in LINEAGENTSTATUS has been updated.

LINEAGENTSTATE_STATE

The dwState member in LINEAGENTSTATUS has been updated.

LINEAGENTSTATE_NEXTSTATE

The dwNextState member in LINEAGENTSTATUS has been updated.

LINEAGENTSTATE_ACTIVITY

The ActivityID, ActivitySize, or ActivityOffset members in LINEAGENTSTATUS has been updated.

LINEAGENTSTATE_ACTIVITYLIST

The List member in LINEAGENTACTIVITYLIST has been updated. The application can call lineGetAgentActivityList to get the updated list.

LINEAGENTSTATE_GROUPLIST

The List member in LINEAGENTGROUPLIST has been updated. The application can call lineGetAgentGroupList to get the updated list.

LINEAGENTSTATE_CAPSCHANGE

The capabilities in LINEAGENTCAPS have been updated. The application can call lineGetAgentCaps to get the updated list.

LINEAGENTSTATE_VALIDSTATES

The dwValidStates member in LINEAGENTSTATUS has been updated.

LINEAGENTSTATE_VALIDNEXTSTATES

The dwValidNextStates member in LINEAGENTSTATUS has been updated.


LINEANSWERMODE_ Constants

The LINEANSWERMODE_ bit-flag constants describe how an existing active call on a line device is affected by answering another offering call on the same line.

LINEANSWERMODE_NONE

Answering another call on the same line has no effect on the existing active call on the line.

LINEANSWERMODE_DROP

The currently active call will automatically be dropped.

LINEANSWERMODE_HOLD

The currently active call will automatically be placed on hold.

No extensibility. All 32 bits are reserved.

If a call comes in (is offered) at the time another call is already active, the new call is connected to by invoking lineAnswer. The effect this has on the existing active call depends on the line's device capabilities. The first call may be unaffected, it may automatically be dropped, or it may automatically be placed on hold.


LINEBEARERMODE_ Constants

The LINEBEARERMODE_ bit-flag constants describe different bearer modes of a call. When an application makes a call, it can request a specific bearer mode. These modes are used to select a certain quality of service for the requested connection from the underlying telephone network. Bearer modes available on a given line are a device capability of the line.

LINEBEARERMODE_VOICE

This is a regular 3.1 kHz analog voice-grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.

LINEBEARERMODE_SPEECH

This corresponds to G.711 speech transmission on the call. The network may use processing techniques such as analog transmission, echo cancellation, and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.

LINEBEARERMODE_MULTIUSE

The multiuse mode defined by ISDN.

LINEBEARERMODE_DATA

The unrestricted data transfer on the call. The data rate is specified separately.

LINEBEARERMODE_ALTSPEECHDATA

The alternate transfer of speech or unrestricted data on the same call (ISDN).

LINEBEARERMODE_NONCALLSIGNALING

This corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a media stream by TAPI).

LINEBEARERMODE_PASSTHROUGH

When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.

LINEBEARERMODE_RESTRICTEDDATA

Bearer service for digital data in which only the low-order seven bits of each octet may contain user data (for example, for Switched 56kbit/s service).

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Note that bearer mode and media mode are different notions. The bearer mode of a call is an indication of the quality of the telephone connection as provided primarily by the network. The media mode of a call is an indication of the type of information stream that is exchanged over that call. Group 3 fax or data modem are media modes that use a call with a 3.1 kHz voice bearer mode.


LINEBUSYMODE_ Constants

The LINEBUSYMODE_ bit-flag constants describe different busy signals that the switch or network may generate. These busy signals typically indicate that a different resource that is required to make a call is currently in use.

LINEBUSYMODE_STATION

The busy signal indicates that the called party's station is busy. This is usually signaled with a normal busy tone.

LINEBUSYMODE_TRUNK

The busy signal indicates that a trunk or circuit is busy. This is usually signaled with a fast busy tone.

LINEBUSYMODE_UNKNOWN

The busy signal's specific mode is currently unknown but may become known later.

LINEBUSYMODE_UNAVAIL

The busy signal's specific mode is unavailable and will not become known.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Note that busy signals may be sent as inband tones or out-of-band messages. TAPI makes no assumption about the specific signaling mechanism.


LINECALLCOMPLCOND_ Constants

The LINECALLCOMPLCOND_ bit-flag constants describe the conditions under which a call can be completed.

LINECALLCOMPLCOND_BUSY

Completion of the call under busy conditions.

LINECALLCOMPLCOND_NOANSWER

Completion of the call under ringback no answer conditions.

No extensibility. All 32 bits are reserved.


LINECALLCOMPLMODE_ Constants

The LINECALLCOMPLMODE_ bit-flag constants describe different ways in which a call can be completed.

LINECALLCOMPLMODE_CAMPON

Queues the call until the call can be completed.

LINECALLCOMPLMODE_CALLBACK

Requests the called station to return the call when it returns to idle.

LINECALLCOMPLMODE_INTRUDE

Adds the application to the existing call at the called station (barge in).

LINECALLCOMPLMODE_MESSAGE

Leaves a short predefined message for the called station (Leave Word Calling). The message to be sent is specified separately.

No extensibility. All 32 bits are reserved.


LINECALLFEATURE_ Constants

The LINECALLFEATURE_ constants list the operations that can be invoked on a call using this API.

Each of the LINECALLFEATURE_ values correspond to the TAPI operations with the same name. The list is not repeated here.

No extensibility. All 32 bits are reserved.

This constant is used both in LINEADDRESSCAPS (returned by lineGetAddressCaps) and in LINECALLSTATUS (returned by lineGetCallStatus). LINEADDRESSCAPS reports the availability of the call features on the specified address. An application would use this information when it initializes to determine what it may be able to do later when calls exist. For the specified call, LINECALLSTATUS reports which call features can be invoked while the call is in the current call state. The latter takes call privileges into account. An application would make this determination dynamically, after call state changes.

The LINECALLFEATURE_RELEASEUSERUSER value is new. No backward compatibility considerations. A service provider may elect to return this value in relevant fields (in LINEADDRESSCAPS and LINECALLSTATUS) even when older API versions have been negotiated on the line device.

The LINECALLFEATURE_SETTREATMENT, LINECALLFEATURE_SETQOS, and LINECALLFEATURE_SETCALLDATA constants are available for API versions 0x00020000 and greater.


LINECALLFEATURE2_ Constants

The LINECALLFEATURE2_ constants list the supplemental features available for conferencing, transferring, and parking calls.

LINECALLFEATURE2_NOHOLDCONFERENCE

If this bit is on, a "no hold conference" can be created by using the LINECALLPARAMFLAGS_NOHOLDCONFERENCE option with lineSetupConference. The LINECALLFEATURE_SETUPCONF bit will also be on in the dwCallFeatures member.

LINECALLFEATURE2_ONESTEPTRANSFER

If this bit is on, "one step transfer" can be created by using the LINECALLPARAMFLAGS_ONESTEPTRANSFER option with lineSetupTransfer. The LINECALLFEATURE_SETUPTRANSFER bit will also be on in the dwCallFeatures member.

LINECALLFEATURE2_COMPLCAMPON

If this bit is on, the "camp on" feature can be invoked by using the LINECOMPLMODE_CAMPON option with lineCompleteCall. The LINECALLFEATURE_COMPLETECALL bit will also be on in the dwCallFeatures member.

LINECALLFEATURE2_COMPLCALLBACK

If this bit is on, the "callback" feature can be invoked by using the LINECOMPLMODE_CALLBACK option with lineCompleteCall. The LINECALLFEATURE_COMPLETECALL bit will also be on in the dwCallFeatures member.

LINECALLFEATURE2_COMPLINTRUDE

If this bit is on, the "intrude" feature can be invoked by using the LINECOMPLMODE_INTRUDE option with lineCompleteCall. The LINECALLFEATURE_COMPLETECALL bit will also be on in the dwCallFeatures member.

LINECALLFEATURE2_COMPLMESSAGE

If this bit is on, the "leave message" feature can be invoked by using the LINECOMPLMODE_MESSAGE option with lineCompleteCall. The LINECALLFEATURE_COMPLETECALL bit will also be on in the dwCallFeatures member.

Note  If none of the "COMPL" bits is specified in the dwCallFeature2 member in LINECALLSTATUS but LINECALLFEATURE_COMPLETECALL is specified, then it is possible that any of them will work, but the service provider has not specified which.

LINECALLFEATURE2_TRANSFERNORM

If this bit is on, the lineCompleteTransfer function can be used to resolve the transfer as a normal transfer. The LINECALLFEATURE_COMPLETETRANSF bit will also be on in the dwCallFeatures member.

LINECALLFEATURE2_TRANSFERCONF

If this bit is on, the lineCompleteTransfer function can be used to resolve the transfer as a three-way conference. The LINECALLFEATURE_COMPLETETRANSF bit will also be on in the dwCallFeatures member.

Note  If neither TRANSFERNORM nor TRANSFERCONF is specified in the dwCallFeature2 member in LINECALLSTATUS but LINECALLFEATURE_COMPLETETRANSF is specified, then it is possible that either will work, but the service provider has not specified which.

LINECALLFEATURE2_PARKDIRECT

If this bit is on, the "directed park" feature can be invoked by using the LINEPARKMODE_DIRECTED option with linePark. The LINECALLFEATURE_PARK bit will also be on in the dwCallFeatures member.

LINECALLFEATURE2_PARKNONDIRECT

If this bit is on, the "non-directed park" feature can be invoked by using the LINEPARKMODE_NONDIRECTED option with linePark. The LINECALLFEATURE_PARK bit will also be on in the dwCallFeatures field.

Note  If neither PARKDIRECT nor PARKNONDIRECT is specified in the dwCallFeature2 member in LINECALLSTATUS but LINECALLFEATURE_PARK is specified, then it is possible that either will work, but the service provider has not specified which.


LINECALLINFOSTATE_ Constants

The LINECALLINFOSTATE_ bit-flag constants describe various call information items about which an application may be notified in the LINE_CALLINFO message.

LINECALLINFOSTATE_OTHER

Call information items other than those listed below have changed. The application should check the current call information to determine which items have changed.

LINECALLINFOSTATE_DEVSPECIFIC

The device-specific field of the call-information record.

LINECALLINFOSTATE_BEARERMODE

The bearer mode field of the call-information record.

LINECALLINFOSTATE_RATE

The rate field of the call-information record.

LINECALLINFOSTATE_MEDIAMODE

The media-mode field of the call-information record.

LINECALLINFOSTATE_APPSPECIFIC

The application-specific field of the call-information record.

LINECALLINFOSTATE_CALLID

The call ID field of the call-information record.

LINECALLINFOSTATE_RELATEDCALLID

The related call ID field of the call-information record.

LINECALLINFOSTATE_ORIGIN

The origin field of the call-information record.

LINECALLINFOSTATE_REASON

The reason field of the call-information record.

LINECALLINFOSTATE_COMPLETIONID

The completion ID field of the call-information record.

LINECALLINFOSTATE_NUMOWNERINCR

The number of owner field in the call-information record was increased.

LINECALLINFOSTATE_NUMOWNERDECR

The number of owner field in the call-information record was decreased.

LINECALLINFOSTATE_NUMMONITORS

The number of monitors field in the call-information record has changed.

LINECALLINFOSTATE_TRUNK

The trunk field of the call-information record.

LINECALLINFOSTATE_CALLERID

One of the callerID-related fields of the call-information record.

LINECALLINFOSTATE_CALLEDID

One of the calledID-related fields of the call-information record.

LINECALLINFOSTATE_CONNECTEDID

One of the cconnectedID-related fields of the call-information record.

LINECALLINFOSTATE_REDIRECTIONID

One of the redirectionID-related fields of the call-information record.

LINECALLINFOSTATE_REDIRECTINGID

One of the redirectingID-related fields of the call-information record.

LINECALLINFOSTATE_DISPLAY

The display field of the call-information record.

LINECALLINFOSTATE_USERUSERINFO

The user-to-user information of the call-information record.

LINECALLINFOSTATE_HIGHLEVELCOMP

The high level compatibility field of the call-information record.

LINECALLINFOSTATE_LOWLEVELCOMP

The low level compatibility field of the call-information record.

LINECALLINFOSTATE_CHARGINGINFO

The charging information of the call-information record.

LINECALLINFOSTATE_TERMINAL

The terminal mode information of the call-information record.

LINECALLINFOSTATE_DIALPARAMS

The dial parameters of the call-information record.

LINECALLINFOSTATE_MONITORMODES

One or more of the digit, tone, or media monitoring fields in the call-information record.

LINECALLINFOSTATE_TREATMENT

The CallTreatment member in LINECALLINFO has been updated. This may occur in response to a lineSetCallTreatment function, a call state change, a call "vector" or other script controlling the call, or upon completion of playback of a recorded message (ordinarily, indicating a change to "silence" or "music").

LINECALLINFOSTATE_QOS

One or more of the QOS members in LINECALLINFO has been updated.

LINECALLINFOSTATE_CALLDATA

The CallData member in LINECALLINFO has been updated.

No extensibility. All 32 bits are reserved.

When changes occur in this data structure, a LINE_CALLINFO message is sent to the application. The parameters to this message are a handle to the call and an indication of the information item that has changed. The LINEADDRESSCAPS data structure also indicates which of these call information elements are valid for every call on the address.


LINECALLORIGIN_ Constants

The LINECALLORIGIN_ constants describe the origin of a call.

LINECALLORIGIN_OUTBOUND

The call originated from this station as an outbound call.

LINECALLORIGIN_INTERNAL

The call originated as an inbound call at a station internal to the same switching environment.

LINECALLORIGIN_EXTERNAL

The call originated as an inbound call on an external line.

LINECALLORIGIN_UNKNOWN

The call origin is currently unknown but may become known later.

LINECALLORIGIN_UNAVAIL

The call origin is not available and will never become known for this call.

LINECALLORIGIN_CONFERENCE

The call handle is for a conference call, that is, it is the application's connection to the conference bridge in the switch.

LINECALLORIGIN_INBOUND

The call originated as an inbound call, but the service provider is unable to determine whether it came from another station on the same switch or from an external line.

No extensibility. All 32 bits are reserved.

The origin of a call is stored in the dwOrigin field of the call's LINECALLINFO structure.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use the LINECALLORIGIN_INBOUND value if it is not supported on the negotiated version (LINECALLORIGIN_UNAVAIL may be substituted).


LINECALLPARAMFLAGS_ Constants

The LINECALLPARAMFLAGS_ constants describe various status flags about a call.

LINECALLPARAMFLAGS_SECURE

The call should be set up as secure.

LINECALLPARAMFLAGS_IDLE

The call should be originated on an idle call appearance and not join a call in progress. When using the lineMakeCall function, if the LINECALLPARAMFLAGS_IDLE value is not set and there is an existing call on the line, the function breaks into the existing call if necessary to make the new call. If there is no existing call, the function makes the new call as specified.

LINECALLPARAMFLAGS_BLOCKID

The originator identity should be concealed (block caller ID).

LINECALLPARAMFLAGS_ORIGOFFHOOK

The originator's phone should be automatically taken offhook.

LINECALLPARAMFLAGS_DESTOFFHOOK

The called party's phone should be automatically taken offhook.

LINECALLPARAMFLAGS_NOHOLDCONFERENCE

This bit is used only in conjunction with lineSetupConference and linePrepareAddToConference. The address to be conferenced with the current call is specified in the TargetAddress member in LINECALLPARAMS. The consultation call does not physically draw dial tone from the switch, but will progress through various call establishment states (for example, dialing, proceeding). When the consultation call reaches the connected state, the conference is automatically established; the original call, which had remained in the connected state, enters the conferenced state; the consultation call enters the conferenced state; the hConfCall enters the connected state. If the consultation call fails (enters the disconnected state followed by idle), the hConfCall also enters the idle state, and the original call (which may have been an existing conference, in the case of linePrepareAddToConference) remains in the connected state. The original party (or parties) never perceive the call has having gone onhold. This feature is often used to add a supervisor to an ACD agent call when necessary to monitor interactions with an irate caller.

LINECALLPARAMFLAGS_PREDICTIVEDIAL

This bit is used only when placing a call on an address with predictive dialing capability (LINEADDRCAPFLAGS_PREDICTIVEDIALER is on in the dwAddrCapFlags member in LINEADDRESSCAPS). The bit must be on to enable the enhanced call progress and/or media device monitoring capabilities of the device. If this bit is not on, the call will be placed without enhanced call progress or media mode monitoring, and no automatic transfer will be initiated based on call state.

LINECALLPARAMFLAGS_ONESTEPTRANSFER

This bit is used only in conjunction with lineSetupTransfer. It combines the operation of lineSetupTransfer followed by lineDial on the consultation call into a single step. The address to be dialed is specified in the TargetAddress member in LINECALLPARAMS. The original call is placed in onholdpendingtranfer state, just as if lineSetupTransfer were called normally, and the consultation call is established normally. The application must still call lineCompleteTransfer to effect the transfer. This feature is often used when invoking a transfer from a server over a third-party call control link, because such links frequently do not support the normal two-step process.

No extensibility. All 32 bits are reserved.


LINECALLPARTYID_ Constants

The LINECALLPARTYID_ bit-flag constants describe the nature of the information available about the parties involved in a call.

LINECALLPARTYID_BLOCKED

Party ID information is not available because it has been blocked by the remote party.

LINECALLPARTYID_OUTOFAREA

Caller ID information for the call is not available since it is not propagated all the way by the network.

LINECALLPARTYID_NAME

Party ID information consists of the party's name (as, for example, from a directory kept inside the switch).

LINECALLPARTYID_ADDRESS

Party ID information consists of the party's address in either canonical address format or dialable address format.

LINECALLPARTYID_PARTIAL

Party ID information is valid but it is limited to partial information only.

LINECALLPARTYID_UNKNOWN

Party ID information is currently unknown but may become known later.

LINECALLPARTYID_UNAVAIL

Party ID information is not available and will not become available later. Information may be unavailable for unspecified reasons. For example, the information was not delivered by the network, it was ignored by the service provider, and so forth.

No extensibility. All 32 bits are reserved.

For each of the possible parties involved in a call, the LINECALLPARTYID_ constants describe how the party ID information is formatted. This information is supplied in the LINECALLINFO data structure.


LINECALLPRIVILEGE_ Constants

The LINECALLPRIVILEGE_ bit-flag constants describe the kinds of access rights or privileges an application with a call handle may have to the corresponding call.

LINECALLPRIVILEGE_NONE

The application has no privileges to the call. The application's handle is void and should not be used.

LINECALLPRIVILEGE_MONITOR

The application has monitor privileges to the call. These privileges allow the application to monitor state changes and query information and status about the call.

LINECALLPRIVILEGE_OWNER

The application has owner privileges to the call. These privileges allow the application to manipulate the call in ways that affect the state of the call.

No extensibility. All 32 bits are reserved.

When a call handle is first provided to an application or whenever call privileges of that application are modified, the LINE_CALLSTATE message is sent to the application. When an application hands off a call, and if the receiving application does not already have a handle with owner privileges, then this message informs the application about its new privileges to the call.


LINECALLREASON_ Constants

The LINECALLREASON_ bit-flag constants describe the reason for a call.

LINECALLREASON_DIRECT

This is a direct inbound or outbound call.

LINECALLREASON_FWDBUSY

This call was forwarded from another extension that was busy at the time of the call.

LINECALLREASON_FWDNOANSWER

The call was forwarded from another extension that didn't answer the call after some number of rings.

LINECALLREASON_FWDUNCOND

The call was forwarded unconditionally from another number.

LINECALLREASON_PICKUP

The call was picked up from another extension.

LINECALLREASON_UNPARK

The call was retrieved as a parked call.

LINECALLREASON_REDIRECT

The call was redirected to this station.

LINECALLREASON_CALLCOMPLETION

The call was the result of a call completion request.

LINECALLREASON_TRANSFER

The call has been transferred from another number.

LINECALLREASON_REMINDER

The call is a reminder (or "recall") that the user has a call parked or on hold for (potentially) a long time.

LINECALLREASON_UNKNOWN

The reason for the call is currently unknown but may become known later.

LINECALLREASON_UNAVAIL

The reason for the call is unavailable and will not become known later.

LINECALLREASON_INTRUDE

The call intruded onto the line, either by a call completion action invoked by another station or by operator action. Depending on switch implementation, the call may appear either in the connected state, or conferenced with an existing active call on the line.

LINECALLREASON_PARKED

The call was parked on the address. Usually, it appears initially in the onhold state.

LINECALLREASON_CAMPEDON

The call was camped on the address. Usually, it appears initially in the onhold state, and can be switched to using lineSwapHold. If an active call becomes idle, the camped-on call may change to the offering state and the device start ringing.

LINECALLREASON_ROUTEREQUEST

The call appears on the address because the switch needs routing instructions from the application. The application should examine the CalledID member in LINECALLINFO, and use the lineRedirect function to provide a new dialable address for the call. If the call is to be blocked instead, the application may call lineDrop. If the application fails to take action within a switch-defined timeout period, a default action will be taken.

No extensibility. All 32 bits are reserved.

The LINECALLREASON_ constants are used in the dwReason field of the LINECALLINFO data structure.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use these LINECALLREASON_ values if not supported on the negotiated version (LINECALLREASON_UNAVAIL may be substituted).


LINECALLTREATMENT_ Constants

The LINECALLTREATMENT_ constants lists the manner in which calls of a certain state are treated and the sounds the calling party hears.

LINECALLTREATMENT_BUSY

When the call is not actively connected to a device (offering or onhold), the party hears busy signal.

LINECALLTREATMENT_MUSIC

When the call is not actively connected to a device (offering or onhold), the party hears music.

LINECALLTREATMENT_RINGBACK

When the call is not actively connected to a device (offering or onhold), the party hears ringback tone.

LINECALLTREATMENT_SILENCE

When the call is not actively connected to a device (offering or onhold), the party hears silence.

The value 0x00000000 is reserved to indicate that the service provider does not support call treatments. Values in the range 0x00000005 through 0x000000FF are reserved for future definition. Values in the range 0x00000100 through 0xFFFFFFFF are reserved for assignment by service providers, and may include identification of specific musical selections or recorded announcements.


LINECALLSELECT_ Constants

The LINECALLSELECT_ bit-flag constants describe which calls are to be selected.

LINECALLSELECT_LINE

Selects calls on the specified line device.

LINECALLSELECT_ADDRESS

Selects call on the specified address.

LINECALLSELECT_CALL

Selects related calls to the specified call. For example, the parties in a conference call.

No extensibility. All 32 bits are reserved.

This constant is used in lineGetNewCalls and to specify a selection (scope) of the calls that are requested.


LINECALLSTATE_ Constants

The LINECALLSTATE_ bit-flag constants describe the call states a call can be in.

LINECALLSTATE_IDLE

The call is idle—no call exists.

LINECALLSTATE_OFFERING

The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user because alerting is done by the switch instructing the line to ring. It does not affect any call states.

LINECALLSTATE_ACCEPTED

The call was offering and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also initiates alerting to both parties.

LINECALLSTATE_DIALTONE

The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.

LINECALLSTATE_DIALING

Destination address information (a phone number) is being sent to the switch over the call. Note that lineGenerateDigits does not place the line into the dialing state.

LINECALLSTATE_RINGBACK

The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.

LINECALLSTATE_BUSY

The call is receiving a busy tone. A busy tone indicates that the call cannot be completed—either a circuit (trunk) or the remote party's station are in use.

LINECALLSTATE_SPECIALINFO

Special information is sent by the network. Special information is typically sent when the destination cannot be reached.

LINECALLSTATE_CONNECTED

The call has been established and the connection is made. Information is able to flow over the call between the originating address and the destination address.

LINECALLSTATE_PROCEEDING

Dialing has completed and the call is proceeding through the switch or telephone network.

LINECALLSTATE_ONHOLD

The call is on hold by the switch.

LINECALLSTATE_CONFERENCED

The call is currently a member of a multi-party conference call.

LINECALLSTATE_ONHOLDPENDCONF

The call is currently on hold while it is being added to a conference.

LINECALLSTATE_ONHOLDPENDTRANSFER

The call is currently on hold awaiting transfer to another number.

LINECALLSTATE_DISCONNECTED

The remote party has disconnected from the call.

LINECALLSTATE_UNKNOWN

The state of the call is not known. This may be due to limitations of the call-progress detection implementation.

The high-order 8 bits can define a device-specific substate of any of the predefined states, provided that one of the LINECALLSTATE_ bits defined above is also set. The low-order 24 bits are reserved for predefined states.

The LINECALLSTATE_ constants are used as parameters by the LINE_CALLSTATE message sent to the application. The message carries the new call state that the call transitioned to. These constants are also used as fields in the LINECALLSTATUS structure returned by the lineGetCallStatus function.


LINECARDOPTION_ Constants

The LINECARDOPTION_ constants define values used in the dwOptions field of the LINECARDENTRY structure returned as part of the LINETRANSLATECAPS structure returned by lineGetTranslateCaps. The LINECARDOPTION_ constant has the following values:

LINECARDOPTION_PREDEFINED

This calling card is one of the predefined calling card definitions included by Microsoft with Win32 Telephony. It cannot be removed entirely using Dial Helper; if the user attempts to remove it, it will become HIDDEN. It thus continues to be accessible for copying of dialing rules.

LINECARDOPTION_HIDDEN

This calling card has been hidden by the user. It is not shown by Dial Helper in the main listing of available calling cards, but will be shown in the list of cards from which dialing rules can be copied.

Not extensible. All 32 bits are reserved.


LINECONNECTEDMODE_ Constants

The LINECONNECTEDMODE_ bit-flag constants describe different substates of a connected call. A mode is available as call status to the application after the call state transitions to connected, and within the LINE_CALLSTATE message indicating the call is in LINECALLSTATE_CONNECTED. These values are used when the call is on an address that is shared (bridged) with other stations (see the LINEADDRESSSHARING_ constants), primarily electronic key systems. The LINECONNECTEDMODE_ constants have the following values:

LINECONNECTEDMODE_ACTIVE

Indicates that the call is connected at the current station (the current station is a participant in the call). If the call state mode is 0 (zero), the application should assume that the value is "active" (which would be the situation on a non-bridged address). The mode may switch between ACTIVE and INACTIVE during a call if the user joins and leaves the call through manual action. In such a bridged situation, a lineDrop or lineHold operation may possibly not actually drop the call or place it on hold, because the status of other stations on the call may govern (for example, attempting to "hold" a call when other stations are participating won't be possible); instead, the call may simply be changed to the INACTIVE mode if it remains CONNECTED at other stations.

LINECONNECTEDMODE_INACTIVE

Indicates that the call is active at one or more other stations, but the current station is not a participant in the call. If the call state mode is ZERO, the application should assume that the value is "active" (which would be the situation on a non-bridged address). A call in the INACTIVE state may be joined using lineAnswer. Many operations that are valid in calls in the CONNECTED state may be impossible in the INACTIVE mode, such as monitoring for tones and digits, because the station is not actually participating in the call; monitoring is usually suspended (although not canceled) while the call is in the INACTIVE mode.

LINECONNECTEDMODE_ACTIVEHELD

Indicates that the station is an active participant in the call, but that the remote party has placed the call on hold (the other party considers the call to be in the onhold state). Normally, such information is available only when both endpoints of the call fall within the same switching domain.

LINECONNECTEDMODE_INACTIVEHELD

Indicates that the station is not an active participant in the call, and that the remote party has placed the call on hold.

LINECONNECTEDMODE_CONFIRMED

Indicates that the service provider received affirmative notification that the call has entered the connected state (for example, through answer supervision or similar mechanisms).

Not extensible. All 32 bits are reserved.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use these LINECONNECTEDMODE_ values if not supported on the negotiated version. It should be noted that applications which are not cognizant of LINECONNECTEDMODE_ will most likely assume that a call that is in LINECALLSTATE_CONNECTED is in LINECONNECTEDMODE_ACTIVE.

The LINECONNECTEDMODE_ACTIVE and LINECONNECTEDMODE_INACTIVE values are used when the call is on an address that is shared with other stations (bridged; see LINEADDRESSSHARING_ constants), primarily electronic key systems. If the connected call state mode is "active," it means that the call is connected at the current station (the current station is a participant in the call). If the call state mode is "inactive," the call is active at one or more other stations, but the current station is not a participant in the call. If the call state mode is ZERO, the application should assume that the value is "active" (which would be the situation on a non-bridged address). The mode may switch between ACTIVE and INACTIVE during a call if the user joins and leaves the call through manual action.

In such a bridged situation, a lineDrop or lineHold operation may possibly not actually drop the call or place it on hold, because the status of other stations on the call may govern (for example, attempting to "hold" a call when other stations are participating will not be possible); instead, the call may simply be changed to the INACTIVE mode if it remains connected at other stations. A call in the INACTIVE state may be joined using the lineAnswer.

Many operations that are valid in calls in the connected state may be impossible in the INACTIVE mode, such as monitoring for tones and digits, because the station is not actually participating in the call; monitoring is usually suspended (although not canceled) while the call is in the INACTIVE mode.


LINEDEVCAPFLAGS_ Constants

The LINEDEVCAPFLAGS_ bit-flag constants are a collection of Booleans describing various line device capabilities.

LINEDEVCAPFLAGS_CROSSADDRCONF

Specifies whether calls on different addresses on this line can be conferenced.

LINEDEVCAPFLAGS_HIGHLEVCOMP

Specifies whether high-level compatibility information elements are supported on this line.

LINEDEVCAPFLAGS_LOWLEVCOMP

Specifies whether low-level compatibility information elements are supported on this line.

LINEDEVCAPFLAGS_MEDIACONTROL

Specifies whether media-control operations are available for calls at this line.

LINEDEVCAPFLAGS_MULTIPLEADDR

Specifies whether lineMakeCall or lineDial are able to deal with multiple addresses at once (as for inverse multiplexing).

LINEDEVCAPFLAGS_CLOSEDROP

Specifies what happens when an open line is closed while the application has calls active on the line. If TRUE, the service provider drops (clears) all active calls on the line when the last application that has opened the line closes it with lineClose. If FALSE, the service provider does not drop active calls in such cases. Instead, the calls remain active and under control of external devices. A service provider typically sets this bit to FALSE if there is some other device that can keep the call alive, for example, if an analog line has the computer and phoneset both connect directly to them in a party-line configuration, the offhook phone will automatically keep the call active even after the computer powers down.

Applications should check this flag to determine whether to warn the user (with an OK/Cancel dialog box) that active calls will be lost.

LINEDEVCAPFLAGS_DIALBILLING

LINEDEVCAPFLAGS_DIALQUIET

LINEDEVCAPFLAGS_DIALDIALTONE

These flags indicate whether the "$", "@", or "W" dialable string modifier is supported for a given line device. It is TRUE if the modifier is supported; otherwise, FALSE. The "?" (prompt user to continue dialing) is never supported by a line device. These flags allow an application to determine up front which modifiers would result in the generation of a LINEERR. The application has the choice of pre-scanning dialable strings for unsupported characters or of passing the "raw" string from lineTranslateAddress directly to the provider as part of functions such as lineMakeCall or lineDial and let the function generate an error to tell it which unsupported modifier occurs first in the string.

No extensibility. All 32 bits are reserved.


LINEDEVSTATE_ Constants

The LINEDEVSTATE_ bit-flag constants describe various line status events.

LINEDEVSTATE_OTHER

Device-status items other than those listed below have changed. The application should check the current device status to determine which items have changed.

LINEDEVSTATE_RINGING

The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending LINE_LINEDEVSTATE messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds.

LINEDEVSTATE_CONNECTED

The line was previously disconnected and is now connected to TAPI.

LINEDEVSTATE_DISCONNECTED

This line was previously connected and is now disconnected from TAPI.

LINEDEVSTATE_MSGWAITON

The message waiting indicator is turned on.

LINEDEVSTATE_MSGWAITOFF

The message waiting indicator is turned off.

LINEDEVSTATE_INSERVICE

The line is connected to TAPI. This happens when TAPI is first activated or when the line wire is physically plugged in and in-service at the switch while TAPI is active.

LINEDEVSTATE_OUTOFSERVICE

The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.

LINEDEVSTATE_MAINTENANCE

Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.

LINEDEVSTATE_OPEN

The line has been opened by another application.

LINEDEVSTATE_CLOSE

The line has been closed by another application.

LINEDEVSTATE_NUMCALLS

The number of calls on the line device has changed.

LINEDEVSTATE_NUMCOMPLETIONS

The number of outstanding call completions on the line device has changed.

LINEDEVSTATE_TERMINALS

The terminal settings have changed. This may happen, for example, if multiple line devices share terminals among them (for example, two lines sharing a phone terminal).

LINEDEVSTATE_ROAMMODE

The roam mode of the line device has changed.

LINEDEVSTATE_BATTERY

The battery level has changed significantly (cellular).

LINEDEVSTATE_SIGNAL

The signal level has changed significantly (cellular).

LINEDEVSTATE_DEVSPECIFIC

The line's device-specific information has changed.

LINEDEVSTATE_REINIT

Items have changed in the configuration of line devices. To become aware of these changes (as for the appearance of new line devices) the application should reinitialize its use of TAPI.

LINEDEVSTATE_LOCK

The locked status of the line device has changed. (For more information, see LINEDEVSTATUSFLAGS_LOCKED in the following topic, LINEDEVSTATUSFLAGS_ Constants.)

LINEDEVSTATE_CAPSCHANGE

Indicates that, due to configuration changes made by the user or other circumstances, one or more of the fields in the LINEDEVCAPS structure for the address have changed. The application should use lineGetDevCaps to read the updated structure. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI to obtain the updated information.

LINEDEVSTATE_CONFIGCHANGE

Indicates that configuration changes have been made to one or more of the media devices associated with the line device. The application, if it desires, may use lineGetDevConfig to read the updated information. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will not receive any notification.

LINEDEVSTATE_TRANSLATECHANGE

Indicates that, due to configuration changes made by the user or other circumstances, one or more of the fields in the LINETRANSLATECAPS structure have changed. The application should use lineGetTranslateCaps to read the updated structure. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI to obtain the updated information.

LINEDEVSTATE_COMPLCANCEL

Indicates that the call completion identified by the completion ID contained in the dwParam2 parameter of the LINE_LINEDEVSTATE message has been externally canceled and is no longer considered valid (if that value were to be passed in a subsequent call to lineUncompleteCall, the function would fail with LINEERR_INVALCOMPLETIONID). If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will not receive any notification.

LINEDEVSTATE_REMOVED

Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A LINE_LINEDEVSTATE message with this value will normally be immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized will result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will not receive any notification.

No extensibility. All 32 bits are reserved.


LINEDEVSTATUSFLAGS_ Constants

The LINEDEVSTATUSFLAGS_ bit-flag constants describe a collection of Boolean line device status items.

LINEDEVSTATUSFLAGS_CONNECTED

Specifies whether the line is connected to TAPI. If TRUE, the line is connected and TAPI is able to operate on the line device. If FALSE, the line is disconnected and the application is unable to control the line device through TAPI.

LINEDEVSTATUSFLAGS_MSGWAIT

Indicates whether the line has a message waiting. If TRUE, a message is waiting; if FALSE, no message is waiting.

LINEDEVSTATUSFLAGS_INSERVICE

Indicates whether the line is in service. If TRUE, the line is in service; if FALSE, the line is out of service.

LINEDEVSTATUSFLAGS_LOCKED

Indicates whether the line is locked or unlocked. This bit is most often used with line devices associated with cellular phones. Many cellular phones have a security mechanism that requires the entry of a password to enable the phone to place calls. This bit may be used to indicate to applications that the phone is locked and cannot place calls until the password is entered on the user interface of the phone so that the application can present an appropriate alert to the user.

No extensibility. All 32 bits are reserved.

LINEDEVSTATUSFLAGS_ constants are used within the dwDevStatusFlags field of the LINEDEVSTATUS data structure.


LINEDIALTONEMODE_ Constants

The LINEDIALTONEMODE_ bit-flag constants describe different types of dial tones. A special dial tone typically carries a special meaning (as with message waiting).

LINEDIALTONEMODE_NORMAL

This is a normal dial tone, which typically is a continuous tone.

LINEDIALTONEMODE_SPECIAL

This is a special dial tone indicating that a certain condition (known by the switch or network) is currently in effect. Special dial tones typically use an interrupted tone. As with a normal dial tone, this indicates that the switch is ready to receive the number to be dialed.

LINEDIALTONEMODE_INTERNAL

This is an internal dial tone, as within a PBX.

LINEDIALTONEMODE_EXTERNAL

This is an external (public network) dial tone.

LINEDIALTONEMODE_UNKNOWN

The dial tone mode is not currently known but may become known later.

LINEDIALTONEMODE_UNAVAIL

The dial tone mode is unavailable and will not become known.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

The LINEDIALTONEMODE_ constants are used within the LINECALLSTATUS data structure for a call in the dialtone state.


LINEDIGITMODE_ Constants

The LINEDIGITMODE_ constants describe different types of inband digit generation.

LINEDIGITMODE_PULSE

Uses rotary pulse sequences to signal digits. Valid digits are 0 through 9.

LINEDIGITMODE_DTMF

Uses DTMF tones to signal digits. Valid digits are 0 through 9, '*', '#', 'A', 'B', 'C', and 'D'.

LINEDIGITMODE_DTMFEND

Uses DTMF tones to signal digits and detect the down edges. Valid digits are 0 through 9, '*', '#', 'A', 'B', 'C', and 'D'.

No extensibility. All 32 bits are reserved.

A digit mode can be specified when generating or detecting digits. Note that pulse digits are generated by making and breaking the local loop circuit. These pulses are absorbed by the switch. The remote end merely observes this as a series of inband audio clicks. Detecting digits sent as pulses must therefore be able to detect these sequences of 1 to 10 audible clicks.


LINEDISCONNECTMODE_ Constants

The LINEDISCONNECTMODE_ bit-flag constants describe different reasons for a remote disconnect request. A disconnect mode is available as call status to the application after the call state transitions to disconnected.

LINEDISCONNECTMODE_NORMAL

This is a normal disconnect request by the remote party. The call was terminated normally.

LINEDISCONNECTMODE_UNKNOWN

The reason for the disconnect request is unknown but may become known later.

LINEDISCONNECTMODE_REJECT

The remote user has rejected the call.

LINEDISCONNECTMODE_PICKUP

The call was picked up from elsewhere.

LINEDISCONNECTMODE_FORWARDED

The call was forwarded by the switch.

LINEDISCONNECTMODE_BUSY

The remote user's station is busy.

LINEDISCONNECTMODE_NOANSWER

The remote user's station does not answer.

LINEDISCONNECTMODE_BADADDRESS

The destination address is invalid.

LINEDISCONNECTMODE_UNREACHABLE

The remote user could not be reached.

LINEDISCONNECTMODE_CONGESTION

The network is congested.

LINEDISCONNECTMODE_INCOMPATIBLE

The remote user's station equipment is incompatible with the type of call requested.

LINEDISCONNECTMODE_UNAVAIL

The reason for the disconnect is unavailable and will not become known later.

LINEDISCONNECTMODE_NODIALTONE

A dial tone was not detected within a service-provider defined timeout, at a point during dialing when one was expected (such as at a "W" in the dialable string). This can also occur without a service-provider-defined timeout period or without a value specified in the dwWaitForDialTone member of the LINEDIALPARAMS structure.

LINEDISCONNECTMODE_NUMBERCHANGED

The call could not be connected because the destination number has been changed, but automatic redirection to the new number is not provided.

LINEDISCONNECTMODE_OUTOFORDER

The call could not be connected or was disconnected because the destination device is out of order (hardware failure).

LINEDISCONNECTMODE_TEMPFAILURE

The call could not be connected or was disconnected because of a temporary failure in the network; the call can be reattempted later and will eventually complete.

LINEDISCONNECTMODE_QOSUNAVAIL

The call could not be connected or was disconnected because the minimum quality of service could not be obtained or sustained. This differs from LINEDISCONNECTMODE_INCOMPATIBLE in that the lack of resources may be a temporary condition at the destination.

LINEDISCONNECTMODE_BLOCKED

The call could not be connected because calls from the origination address are not being accepted at the destination address. This differs from LINEDISCONNECTMODE_REJECT in that blocking is implemented in the network (a passive reject) while a rejection is implemented in the destination equipment (an active reject). The blocking may be due to a specific exclusion of the origination address, or because the destination accepts calls from only a selected set of origination address (closed user group).

LINEDISCONNECTMODE_DONOTDISTURB

The call could not be connected because the destination has invoked the Do Not Disturb feature.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

A remote disconnect request for a given call results in the call state transitioning to the disconnected state and a LINE_CALLSTATE message is sent to the application. The LINEDISCONNECTMODE_ information provides details about the remote disconnect request. It is available in the call's LINECALLSTATUS structure when the call is in the disconnected state. While a call is in this state, the application is still allowed to query the call's information and status. For example, user-to-user information that is received as part of the remote disconnect is available then. The application can clear a disconnected call by dropping the call.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use this LINEDISCONNECTMODE_ value if it is not supported on the negotiated version (LINEDISCONNECTMODE_NORMAL or _UNKNOWN could be used instead).


LINEERR_ Constants

This is the list of error codes that TAPI may return when invoking operations on lines, addresses, or calls. Consult the individual function descriptions to determine which of these error codes a particular function may return.

LINEERR_ADDRESSBLOCKED

The specified address is blocked from being dialed on the specified call.

LINEERR_ALLOCATED

The line cannot be opened due to a persistent condition, such as that of a serial port being exclusively opened by another process.

LINEERR_BADDEVICEID

The specified device ID or line device ID (such as in a dwDeviceID parameter) is invalid or out of range.

LINEERR_BEARERMODEUNAVAIL

The call's bearer mode cannot be changed to the specified bearer mode.

LINEERR_CALLUNAVAIL

All call appearances on the specified address are currently in use.

LINEERR_COMPLETIONOVERRUN

The maximum number of outstanding call completions has been exceeded.

LINEERR_CONFERENCEFULL

The maximum number of parties for a conference has been reached, or the requested number of parties cannot be satisfied.

LINEERR_DIALBILLING

The dialable address parameter contains dialing control characters that are not processed by the service provider.

LINEERR_DIALQUIET

The dialable address parameter contains dialing control characters that are not processed by the service provider.

LINEERR_DIALDIALTONE

The dialable address parameter contains dialing control characters that are not processed by the service provider.

LINEERR_DIALPROMPT

The dialable address parameter contains dialing control characters that are not processed by the service provider.

LINEERR_INCOMPATIBLEAPIVERSION

The application requested an API version or version range that is either incompatible or cannot be supported by the Telephony API implementation and/or corresponding service provider.

LINEERR_INCOMPATIBLEEXTVERSION

The application requested an extension version range that is either invalid or cannot be supported by the corresponding service provider.

LINEERR_INIFILECORRUPT

The TELEPHON.INI file cannot be read or understood properly by TAPI because of internal inconsistencies or formatting problems. For example, the [Locations], [Cards], or [Countries] section of the TELEPHON.INI file may be corrupted or inconsistent.

LINEERR_INUSE

The line device is in use and cannot currently be configured, allow a party to be added, allow a call to be answered, allow a call to be placed, or allow a call to be transferred.

LINEERR_INVALADDRESS

A specified address is either invalid or not allowed. If invalid, the address contains invalid characters or digits, or the destination address contains dialing control characters (W, @, $, or ?) that are not supported by the service provider. If not allowed, the specified address is either not assigned to the specified line or is not valid for address redirection.

LINEERR_INVALADDRESSID

The specified address ID is either invalid or out of range.

LINEERR_INVALADDRESSMODE

The specified address mode is invalid.

LINEERR_INVALADDRESSSTATE

dwAddressStates contains one or more bits that are not LINEADDRESSSTATE_ constants.

LINEERR_INVALAGENTACTIVITY

The specified agent activity is not valid.

LINEERR_INVALAGENTGROUP

The specified agent group information is not valid or contains errors. The requested action has not been carried out.

LINEERR_INVALAGENTID

The specified agent identifier is not valid.

LINEERR_INVALAGENTSKILL

The specified agent skill information is not valid.

LINEERR_INVALAGENTSTATE

The specified agent state is not valid or contains errors. No changes have been made to the agent state of the specified address.

LINEERR_INVALAGENTSUPERVISOR

The specified agent supervisor information is not valid.

LINEERR_INVALAPPHANDLE

The application handle (such as specified by a hLineApp parameter) or the appliction registration handle is invalid.

LINEERR_INVALAPPNAME

The specified application name is invalid. If an application name is specified by the application, it is assumed that the string does not contain any non-displayable characters, and is zero-terminated.

LINEERR_INVALBEARERMODE

The specified bearer mode is invalid.

LINEERR_INVALCALLCOMPLMODE

The specified completion is invalid.

LINEERR_INVALCALLHANDLE

The specified call handle is not valid. For example, the handle is not NULL but does not belong to the given line. In some cases, the specified call device handle is invalid.

LINEERR_INVALCALLPARAMS

The specified call parameters are invalid.

LINEERR_INVALCALLPRIVILEGE

The specified call privilege parameter is invalid.

LINEERR_INVALCALLSELECT

The specified select parameter is invalid.

LINEERR_INVALCALLSTATE

The current state of a call is not in a valid state for the requested operation.

LINEERR_INVALCALLSTATELIST

The specified call state list is invalid.

LINEERR_INVALCARD

The permanent card ID specified in dwCard could not be found in any entry in the [Cards] section in the registry.

LINEERR_INVALCOMPLETIONID

The completion ID is invalid.

LINEERR_INVALCONFCALLHANDLE

The specified call handle for the conference call is invalid or is not a handle for a conference call.

LINEERR_INVALCONSULTCALLHANDLE

The specified consultation call handle is invalid.

LINEERR_INVALCOUNTRYCODE

The specified country code is invalid.

LINEERR_INVALDEVICECLASS

The line device has no associated device for the given device class, or the specified line does not support the indicated device class.

LINEERR_INVALDIGITLIST

The specified digit list is invalid.

LINEERR_INVALDIGITMODE

The specified digit mode is invalid.

LINEERR_INVALDIGITS

The specified termination digits are not valid.

LINEERR_INVALFEATURE

The dwFeature parameter is invalid.

LINEERR_INVALGROUPID

The specified group ID is invalid.

LINEERR_INVALLINEHANDLE

The specified call, device, line device, or line handle is invalid.

LINEERR_INVALLINESTATE

The device configuration may not be changed in the current line state. The line may be in use by another application or a dwLineStates parameter contains one or more bits that are not LINEDEVSTATE_ constants. The LINEERR_INVALLINESTATE value can also indicate that the device is DISCONNECTED or OUTOFSERVICE. These states are indicated by setting the bits corresponding to the LINEDEVSTATUSFLAGS_CONNECTED and LINEDEVSTATUSFLAGS_INSERVICE values to 0 in the dwDevStatusFlags member of the LINEDEVSTATUS structure returned by the lineGetLineDevStatus function.

LINEERR_INVALLOCATION

The permanent location ID specified in dwLocation could not be found in any entry in the [Locations] section in the registry.

LINEERR_INVALMEDIALIST

The specified media list is invalid.

LINEERR_INVALMEDIAMODE

The list of media types to be monitored contains invalid information, the specified media mode parameter is invalid, or the service provider does not support the specified media mode. The media modes supported on the line are listed in the dwMediaModes field in the LINEDEVCAPS structure.

LINEERR_INVALMESSAGEID

The number given in dwMessageID is outside the range specified by the dwNumCompletionMessages field in the LINEADDRESSCAPS structure.

LINEERR_INVALPARAM

A parameter (such as dwTollListOption, dwTranslateOptions, dwNumDigits, or a structure pointed to by lpDeviceConfig) contains invalid values, a country code is invalid, a window handle is invalid, or the specified forward list parameter contains invalid information.

LINEERR_INVALPARKMODE

The specified park mode is invalid.

LINEERR_INVALPASSWORD

The specified password is not correct and the requested action has not been carried out.

LINEERR_INVALPOINTER

One or more of the specified pointer parameters (such as lpCallList, lpdwAPIVersion, lpExtensionID, lpdwExtVersion, lphIcon, lpLineDevCaps, and lpToneList) are invalid, or a required pointer to an output parameter is NULL.

LINEERR_INVALPRIVSELECT

An invalid flag or combination of flags was set for the dwPrivileges parameter.

LINEERR_INVALRATE

The specified bearer mode is invalid.

LINEERR_INVALREQUESTMODE

The specified request mode is invalid.

LINEERR_INVALTERMINALID

The specified terminal mode parameter is invalid.

LINEERR_INVALTERMINALMODE

The specified terminal modes parameter is invalid.

LINEERR_INVALTIMEOUT

Timeouts are not supported or the values of either or both of the parameters dwFirstDigitTimeout or dwInterDigitTimeout fall outside the valid range specified by the call's line-device capabilities.

LINEERR_INVALTONE

The specified custom tone does not represent a valid tone or is made up of too many frequencies or the specified tone structure does not describe a valid tone.

LINEERR_INVALTONELIST

The specified tone list is invalid.

LINEERR_INVALTONEMODE

The specified tone mode parameter is invalid.

LINEERR_INVALTRANSFERMODE

The specified transfer mode parameter is invalid.

LINEERR_LINEMAPPERFAILED

LINEMAPPER was the value passed in the dwDeviceID parameter, but no lines were found that match the requirements specified in the lpCallParams parameter.

LINEERR_NOCONFERENCE

The specified call is not a conference call handle or a participant call.

LINEERR_NODEVICE

The specified device ID, which was previously valid, is no longer accepted because the associated device has been removed from the system since TAPI was last initialized. Alternately, the line device has no associated device for the given device class.

LINEERR_NODRIVER

Either TAPIADDR.DLL could not be located or the telephone service provider for the specified device found that one of its components is missing or corrupt in a way that was not detected at initialization time. The user should be advised to use the Telephony Control Panel to correct the problem.

LINEERR_NOMEM

Insufficient memory to perform the operation, or unable to lock memory.

LINEERR_NOMULTIPLEINSTANCE

A Telephony Service Provider which does not support multiple instances is listed more than once in the [Providers] section in the registry. The application should advise the user to use the Telephony Control Panel to remove the duplicated driver.

LINEERR_NOREQUEST

There currently is no request pending of the indicated mode, or the application is no longer the highest-priority application for the specified request mode.

LINEERR_NOTOWNER

The application does not have owner privilege to the specified call.

LINEERR_NOTREGISTERED

The application is not registered as a request recipient for the indicated request mode.

LINEERR_OPERATIONFAILED

The operation failed for an unspecified or unknown reason.

LINEERR_OPERATIONUNAVAIL

The operation is not available, such as for the given device or specified line.

LINEERR_RATEUNAVAIL

The service provider currently does not have enough bandwidth available for the specified rate.

LINEERR_REINIT

If TAPI reinitialization has been requested, for example as a result of adding or removing a Telephony service provider, then lineInitialize, lineInitializeEx, or lineOpen requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown), at which time the new configuration becomes effective and applications are once again permitted to call lineInitialize or lineInitializeEx.

LINEERR_RESOURCEUNAVAIL

Insufficient resources to complete the operation. For example, a line cannot be opened due to a dynamic resource overcommitment.

LINEERR_STRUCTURETOOSMALL

The dwTotalSize field indicates insufficient space to contain the fixed portion of the specified structure.

LINEERR_TARGETNOTFOUND

A target for the call handoff was not found. This may occur if the named application did not open the same line with the LINECALLPRIVILEGE_OWNER bit in the dwPrivileges parameter of lineOpen. Or, in the case of media-mode handoff, no application has opened the same line with the LINECALLPRIVILEGE_OWNER bit in the dwPrivileges parameter of lineOpen and with the media mode specified in the dwMediaMode parameter having been specified in the dwMediaModes parameter of lineOpen.

LINEERR_TARGETSELF

The application invoking this operation is the target of the indirect handoff. That is, TAPI has determined that the calling application is also the highest priority application for the given media mode.

LINEERR_UNINITIALIZED

The operation was invoked before any application called lineInitialize , lineInitializeEx.

LINEERR_USERUSERINFOTOOBIG

The string containing user-to-user information exceeds the maximum number of bytes specified in the dwUUIAcceptSize, dwUUIAnswerSize, dwUUIDropSize, dwUUIMakeCallSize, or dwUUISendUserUserInfoSize field of LINEDEVCAPS, or the string containing user-to-user information is too long.

The values 0xC0000000 through 0xFFFFFFFF are available for device-specific extensions. The values 0x80000000 through 0xBFFFFFFF are reserved, while 0x00000000 through 0x7FFFFFFF are used as request IDs.

If an application gets an error return that it does not specifically handle (such as an error defined by a device-specific extension), it should treat the error as a LINEERR_OPERATIONFAILED (for an unspecified reason).


LINEFEATURE_ Constants

The LINEFEATURE_ constants list the operations that can be invoked on a line using this API.

LINEFEATURE_DEVSPECIFIC

Device-specific operations can be used on the line.

LINEFEATURE_DEVSPECIFICFEAT

Device-specific features can be used on the line.

LINEFEATURE_FORWARD

Forwarding of all addresses can be used on the line.

LINEFEATURE_MAKECALL

An outbound call can be placed on this line using an unspecified address.

LINEFEATURE_SETMEDIACONTROL

Media control can be set on this line.

LINEFEATURE_SETTERMINAL

Terminal modes for this line can be set.

LINEFEATURE_SETDEVSTATUS

The lineSetLineDevStatus function may be invoked on the line device.

LINEFEATURE_FORWARDFWD

The lineForward function can be used to forward calls on all address on the line to other numbers. LINEFEATURE_FORWARD will also be set.

LINEFEATURE_FORWARDDND

The lineForward function (with an empty destination address) can be used to turn on the Do Not Disturb feature on all addresses on the line. LINEFEATURE_FORWARD will also be set.

Note  If neither of the new modified "FORWARD" bits is set in the dwLineFeatures member in LINEDEVSTATUS but the LINEFEATURE_FORWARD bit is set, then any of the forward modes may work; the service provider has simply not specified which ones.

No extensibility. All 32 bits are reserved.

The LINEFEATURE_ constants are used in LINEDEVSTATUS (returned by lineGetLineDevStatus). LINEDEVSTATUS reports, for a given line, which line features can actually be invoked while the line is in the current state. An application would make this determination dynamically after line state changes, typically caused by address or call-related activities on the line.


LINEFORWARDMODE_ Constants

The LINEFORWARDMODE_ bit-flag constants describe the conditions under which calls to an address can be forwarded.

LINEFORWARDMODE_UNCOND

Forward all calls unconditionally, irrespective of their origin. Use this value when unconditional forwarding for internal and external calls cannot be controlled separately. Unconditional forwarding overrides forwarding on busy and/or no answer conditions.

LINEFORWARDMODE_UNCONDINTERNAL

Forward all internal calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.

LINEFORWARDMODE_UNCONDEXTERNAL

Forward all external calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.

LINEFORWARDMODE_UNCONDSPECIFIC

Unconditionally forward all calls that originated at a specified address (selective call forwarding).

LINEFORWARDMODE_BUSY

Forward all calls on busy, irrespective of their origin. Use this value when forwarding for internal and external calls on busy and on no answer cannot be controlled separately.

LINEFORWARDMODE_BUSYINTERNAL

Forward all internal calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.

LINEFORWARDMODE_BUSYEXTERNAL

Forward all external calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.

LINEFORWARDMODE_BUSYSPECIFIC

Forward on busy all calls that originated at a specified address (selective call forwarding).

LINEFORWARDMODE_NOANSW

Forward all calls on no answer, irrespective of their origin. Use this value when call forwarding for internal and external calls on no answer cannot be controlled separately.

LINEFORWARDMODE_NOANSWINTERNAL

Forward all internal calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.

LINEFORWARDMODE_NOANSWEXTERNAL

Forward all external calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.

LINEFORWARDMODE_NOANSWSPECIFIC

Forward on no answer all calls that originated at a specified address (selective call forwarding).

LINEFORWARDMODE_BUSYNA

Forward all calls on busy/no answer, irrespective of their origin. Use this value when forwarding for internal and external calls on busy and on no answer cannot be controlled separately.

LINEFORWARDMODE_BUSYNAINTERNAL

Forward all internal calls on busy/no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.

LINEFORWARDMODE_BUSYNAEXTERNAL

Forward all external calls on busy/no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.

LINEFORWARDMODE_BUSYNASPECIFIC

Forward on busy/no answer all calls that originated at a specified address (selective call forwarding).

LINEFORWARDMODE_UNKNOWN

Calls are forwarded, but the conditions under which forwarding will occur are not known at this time. It is possible that the conditions may become known at a future time.

LINEFORWARDMODE_UNAVAIL

Calls are forwarded, but the conditions under which forwarding will occur are not known, and will never be known by the service provider.

No extensibility. All 32 bits are reserved.

The bit flags defined by LINEFORWARDMODE_ are not orthogonal. Unconditional forwarding ignores any specific condition such as busy or no answer. If unconditional forwarding is not in effect, then forwarding on busy and on no answer can be controlled separately or not separately. If controlled separately, the LINEFORWARDMODE_BUSY and LINEFORWARDMODE_NOANSW flags can be used separately. If not controlled separately, the flag LINEFORWARDMODE_BUSYNA must be used. Similarly, if forwarding of internal and external calls can be controlled separately, then LINEFORWARDMODE_INTERNAL and LINEFORWARDMODE_EXTERNAL flags can be used separately; otherwise the combination is used.

Address capabilities indicate which forwarding modes are available for each address assigned to a line. An application can use lineForward to set forwarding conditions at the switch.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use these LINEFORWARDMODE_ values if i not supported on the negotiated version.


LINEGATHERTERM_ Constants

The LINEGATHERTERM_ bit-flag constants describe the conditions under which buffered digit gathering is terminated.

LINEGATHERTERM_BUFFERFULL

The requested number of digits has been gathered. The buffer is full.

LINEGATHERTERM_TERMDIGIT

One of the termination digits matched a received digit. The matched termination digit is the last digit in the buffer.

LINEGATHERTERM_FIRSTTIMEOUT

The first digit timeout expired. The buffer contains no digits.

LINEGATHERTERM_INTERTIMEOUT

The inter-digit timeout expired. The buffer contains at least one digit.

LINEGATHERTERM_CANCEL

The request was canceled by this application, by another application, or because the call terminated.

No extensibility. All 32 bits are reserved.


LINEGENERATETERM_ Constants

The LINEGENERATETERM_ bit-flag constants describe the conditions under which digit or tone generation is terminated.

LINEGENERATETERM_DONE

The requested number of digits or requested tones have been generated for the requested duration.

LINEGENERATETERM_CANCEL

The digit or tone generation request was canceled by this application, by another application, or because the call terminated. This value may also be returned when digit or tone generation cannot be completed due to internal failure of the service provider.

No extensibility. All 32 bits are reserved.


LINELOCATIONOPTION_ Constants

The LINELOCATIONOPTION_ constants define values used in the dwOptions field of the LINELOCATIONENTRY structure returned as part of the LINETRANSLATECAPS structure returned by lineGetTranslateCaps.

LINELOCATIONOPTION_PULSEDIAL

The default dialing mode at this location is pulse dialing. If this bit is set, lineTranslateAddress will insert a "P" dial modifier at the beginning of the dialable string returned when this location is selected. If this bit is not set, lineTranslateAddress will insert a "T" dial modifier at the beginning of the dialable string.

Not extensible. All 32 bits are reserved.


LINEINITIALIZEEXOPTION_ Constants

The LINEINITIALIZEEXOPTION_ constants specify which event notification mechanism to use when initializing a session.

LINEINITIALIZEEXOPTION_USECOMPLETIONPORT

The application desires to use the Completion Port event notification mechanism.

LINEINITIALIZEEXOPTION_USEEVENT

The application desires to use the Event Handle event notification mechanism.

LINEINITIALIZEEXOPTION_USEHIDDENWINDOW

The application desires to use the Hidden Window event notification mechanism.

See lineInitializeEx for further details on the operation of these options.


LINEMEDIACONTROL_ Constants

The LINEMEDIACONTROL_ bit-flag constants describe a set of generic operations on media streams. The interpretations are determined by the media stream. The line device must have the media-control capability for any media-control operation to be effective.

LINEMEDIACONTROL_NONE

No change is to be made to the media stream.

LINEMEDIACONTROL_START

Start the media stream.

LINEMEDIACONTROL_RESET

Reset the media stream. Equivalent to an end-of-input. All buffers are released.

LINEMEDIACONTROL_PAUSE

Temporarily pause the media stream.

LINEMEDIACONTROL_RESUME

Resume a paused media stream.

LINEMEDIACONTROL_RATEUP

The speed of the media stream is increased by some stream-defined quantity.

LINEMEDIACONTROL_RATEDOWN

The speed of the media stream is decreased by some stream-defined quantity.

LINEMEDIACONTROL_RATENORMAL

The speed of the media stream is returned to normal.

LINEMEDIACONTROL_VOLUMEUP

The amplitude of the media stream is increased by some stream-defined quantity.

LINEMEDIACONTROL_VOLUMEDOWN

The amplitude of the media stream is decreased by some stream-defined quantity.

LINEMEDIACONTROL_VOLUMENORMAL

The amplitude of the media stream is returned to normal.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Media control is provided to improve performance of actions on media streams in response to telephony-related events. The application should normally manage a media stream through the media-specific API. The media-control functionality provided here is not intended to replace the native media APIs.

Media-control actions can be associated with the detection of digits, the detection of tones, the transition into a call state, and the detection of a media mode. Consult a line's device capabilities to determine whether media control is available on the line.


LINEMEDIAMODE_ Constants

The LINEMEDIAMODE_ constants describe media modes (the data type of a media stream) on calls.

LINEMEDIAMODE_UNKNOWN

A media stream exists but its mode is not currently known and may become known later. This would correspond to a call with an unclassified media type. In typical analog telephony environments, an inbound call's media mode may be unknown until after the call has been answered and the media stream has been filtered to make a determination.

If the unknown media-mode flag is set, other media flags may also be set. This is used to signify that the media is unknown but that it is likely to be one of the other selected media modes.

LINEMEDIAMODE_INTERACTIVEVOICE

The presence of voice energy on the call, and the call is treated as an interactive call with humans on both ends.

LINEMEDIAMODE_AUTOMATEDVOICE

The presence of voice energy on the call and the voice is locally handled by an automated application.

LINEMEDIAMODE_DATAMODEM

A data modem session on the call.

LINEMEDIAMODE_G3FAX

A group 3 fax is being sent or received over the call.

LINEMEDIAMODE_TDD

A TDD (Telephony Devices for the Deaf) session on the call.

LINEMEDIAMODE_G4FAX

A group 4 fax is being sent or received over the call.

LINEMEDIAMODE_DIGITALDATA

Digital data is being sent or received over the call.

LINEMEDIAMODE_TELETEX

A teletex session on the call. Teletex is one of the telematic services.

LINEMEDIAMODE_VIDEOTEX

A videotex session on the call. Videotex is one the telematic services.

LINEMEDIAMODE_TELEX

A telex session on the call. Telex is one of the telematic services.

LINEMEDIAMODE_MIXED

A mixed session on the call. Mixed is one of the ISDN telematic services.

LINEMEDIAMODE_ADSI

An ADSI (Analog Display Services Interface) session on the call.

LINEMEDIAMODE_VOICEVIEW

The media mode of the call is VoiceView.

All 32 bits are reserved.

Note that bearer mode and media mode are different notions. The bearer mode of a call is an indication of the quality of the telephone connection as provided primarily by the network. The media mode of a call is an indication of the type of information stream that is exchanged over that call. Group 3 fax or data modem are media modes that use a call with a 3.1 kHz voice bearer mode.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use this LINEMEDIAMODE_ value if not supported on the negotiated version.


LINEOFFERINGMODE_ Constants

The LINEOFFERINGMODE_ bit-flag constants describe different substates of an offering call. A mode is available as call status to the application after the call state transitions to offering, and within the LINE_CALLSTATE message indicating the call is in LINECALLSTATE_OFFERING. These values are used when the call is on an address that is shared (bridged) with other stations (see LINEADDRESSSHARING_ Constants), primarily electronic key systems.

LINEOFFERINGMODE_ACTIVE

Indicates that the call is alerting at the current station (will be accompanied by LINEDEVSTATE_RINGING messages), and if any application is set up to automatically answer, it may do so. If the call state mode is ZERO, the application should assume that the value is active (which would be the situation on a non-bridged address).

LINEOFFERINGMODE_INACTIVE

Indicates that the call is being offered at more than one station, but the current station is not alerting (for example, it may be an attendant station where the offering status is advisory, such as blinking a light); software at the station set for automatic answering should preferably not answer the call, because this should be the prerogative at the primary (alerting) station, but lineAnswer may be used to connect the call.

Not extensible. All 32 bits are reserved.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use these LINEOFFERINGMODE_ values if not supported on the negotiated version. It should be noted that applications which are not cognizant of LINEOFFERINGMODE_ will most likely assume that a call that is in LINECALLSTATE_OFFERING is in LINEOFFERINGMODE_ACTIVE.

The LINEOFFERINGMODE_ACTIVE and LINEOFFERINGMODE_INACTIVE values are used when the call is on an address that is shared with other stations (bridged; see LINEADDRESSSHARING_ Constants), primarily electronic key systems. If the offering call state mode is "active," it means that the call is alerting at the current station (will be accompanied by LINEDEVSTATE_RINGING messages), and if any application is set up to automatically answer, it may do so. If the call state mode is "inactive," the call is being offered at more than one station, but the current station is not alerting (for example, it may be an attendant station where the offering status is advisory, such as blinking a light); software at the station set for automatic answering should preferably not answer the call, because this should be the prerogative at the primary (alerting) station, but lineAnswer may be used to connect the call. If the call state mode is ZERO, the application should assume that the value is active (which would be the situation on a non-bridged address).


LINEOPENOPTION_ Constants

The LINEOPENOPTION_ constants list the available options for opening a line.

LINEOPENOPTION_SINGLEADDRESS

The application should be informed of new calls created on the line device only if those calls appear on the address specified in the dwAddressID member in the LINECALLPARAMS structure pointed to by the lpCallParams parameter.

LINEOPENOPTION_PROXY

The application is willing to handle requests from other applications that have the line open.

See lineOpen for further details on the operation of these options.


LINEPARKMODE_ Constants

The LINEPARKMODE_ bit-flag constants describe different ways of parking calls.

LINEPARKMODE_DIRECTED

Specifies directed call park. The address where the call is to be parked must be supplied to the switch.

LINEPARKMODE_NONDIRECTED

Specifies nondirected call park. The address where the call is parked is selected by the switch and provided by the switch to the application.

No extensibility. All 32 bits are reserved.

The LINEPARKMODE_ constants are used when parking a call. Consult a line's address device capabilities to find out which park mode is available.


LINEPROXYREQUEST_ Constants

These constants are used in two contexts. First, they may be used in an array of DWORD values in the LINECALLPARAMS structure passed in with lineOpen when the LINEOPENOPTION_PROXY option is specified, to indicate which functions the application is willing to handle. Second, they are used in the LINEPROXYBUFFER passed to the handler application by a LINE_PROXYREQUEST message to indicate the type of request that is to be processed and the format of the data in the buffer.

LINEPROXYREQUEST_SETAGENTGROUP

Associated with lineSetAgentGroup.

LINEPROXYREQUEST_SETAGENTSTATE

Associated with lineSetAgentState.

LINEPROXYREQUEST_SETAGENTACTIVITY

Associated with lineSetAgentActivity.

LINEPROXYREQUEST_GETAGENTCAPS

Associated with lineGetAgentCaps.

LINEPROXYREQUEST_GETAGENTSTATUS

Associated with lineGetAgentStatus.

LINEPROXYREQUEST_AGENTSPECIFIC

Associated with lineAgentSpecific.

LINEPROXYREQUEST_GETAGENTACTIVITYLIST

Associated with lineGetAgentActivityList.

LINEPROXYREQUEST_GETAGENTGROUPLIST

Associated with lineGetAgentGroupList.


LINEREMOVEFROMCONF_ Constants

The LINEREMOVEFROMCONF_ scalar constants describe how parties participating in a conference call can be removed from a conference call.

LINEREMOVEFROMCONF_NONE

Parties cannot be removed from the conference call.

LINEREMOVEFROMCONF_LAST

Only the most recently added party can be removed from the conference call

LINEREMOVEFROMCONF_ANY

Any participating party can be removed from the conference call.

No extensibility. All 32 bits are reserved.


LINEREQUESTMODE_ Constants

The LINEREQUESTMODE_ bit-flag constants describe different types of telephony requests that can be made from one application to another.

LINEREQUESTMODE_MAKECALL

A tapiRequestMakeCall request.

No extensibility. All 32 bits are reserved.


LINEROAMMODE_ Constants

The LINEROAMMODE_ bit-flag constants describe the roaming status of a line device.

LINEROAMMODE_UNKNOWN

The roam mode is currently unknown but may become known later.

LINEROAMMODE_UNAVAIL

The roam mode is unavailable and will not be known.

LINEROAMMODE_HOME

The line is connected to the home network node.

LINEROAMMODE_ROAMA

The line is connected to the Roam-A carrier and calls are charged accordingly.

LINEROAMMODE_ROAMB

The line is connected to the Roam-B carrier and calls are charged accordingly.

No extensibility. All 32 bits are reserved.


LINESPECIALINFO_ Constants

The LINESPECIALINFO_ bit-flag constants describes special information signals that the network may use to report various reporting and network observation operations. They are special coded tone sequences transmitted at the beginning of network advisory recorded announcements.

LINESPECIALINFO_NOCIRCUIT

This special information tone precedes a no circuit or an emergency announcement (trunk blockage category).

LINESPECIALINFO_CUSTIRREG

This special information tone precedes a vacant number, AIS, Centrex number change and nonworking station, access code not dialed or dialed in error, or manual intercept operator message (customer irregularity category). LINESPECIALINFO_CUSTIRREG is also reported when billing information is rejected and when the dialed address is blocked at the switch.

LINESPECIALINFO_REORDER

This special information tone precedes a reorder announcement (equipment irregularity category). LINESPECIALINFO_REORDER is also reported when the telephone is kept offhook too long.

LINESPECIALINFO_UNKNOWN

Specifics about the special information tone are currently unknown but may become known later.

LINESPECIALINFO_UNAVAIL

Specifics about the special information tone are unavailable and will not become known.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Special information tones are defined for advisory messages and are not normally used for billing or supervisory purpose.


LINETERMDEV_ Constants

The LINETERMDEV_ bit-flag constants describe different types of terminal devices.

LINETERMDEV_PHONE

The terminal is a phone set.

LINETERMDEV_HEADSET

The terminal is a headset.

LINETERMDEV_SPEAKER

The terminal is an external speaker and microphone.

No extensibility. All 32 bits are reserved.

These constants are used to characterize a line's terminal device and help an application to determine the nature of a terminal device.


LINETERMMODE_ Constants

The LINETERMMODE_ bit-flag constants describe different types of events on a phone line that can be routed to a terminal device.

LINETERMMODE_BUTTONS

These are button-press events sent from the terminal to the line.

LINETERMMODE_LAMPS

These are lamp events sent from the line to the terminal.

LINETERMMODE_DISPLAY

This is display information sent from the line to the terminal.

LINETERMMODE_RINGER

This is ringer-control information sent from the switch to the terminal.

LINETERMMODE_HOOKSWITCH

These are hookswitch events sent from the terminal to the line.

LINETERMMODE_MEDIATOLINE

This is the unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIAFROMLINE

This is the unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIABIDIRECT

This is the bidirectional media stream associated with a call on the line and the terminal. Use this value when the routing of both unidirectional channels of a call's media stream cannot be controlled independently.

No extensibility. All 32 bits are reserved.

These constants describe the classes of control and information streams that can be routed directly between a line device and a terminal device (such as a phone set).


LINETERMSHARING_ Constants

The LINETERMSHARING_ bit-flag constants describe different ways in which a terminal can be shared between line devices, addresses, or calls.

LINETERMSHARING_PRIVATE

The terminal device is private to a single line device.

LINETERMSHARING_SHAREDEXCL

The terminal device can be used by multiple lines. The last line device to do a lineSetTerminal to the terminal for a given terminal mode will have exclusive connection to the terminal for that mode.

LINETERMSHARING_SHAREDCONF

The terminal device can be used by multiple lines. The lineSetTerminal requests of the various terminals end up being merged or conferenced at the terminal.

No extensibility. All 32 bits are reserved.

These constants describe the classes of control and information streams that can be routed directly between a line device and a terminal device (such as a phone set).


LINETOLLLISTOPTION_ Constants

The LINETOLLLISTOPTION_ bit-flag constants describe options for manipulating a toll list.

LINETOLLLISTOPTION_ADD

A prefix is to be added to the toll list.

LINETOLLLISTOPTION_REMOVE

A prefix is to be removed from the toll list.

No extensibility. All 32 bits are reserved.


LINETONEMODE_ Constants

The LINETONEMODE_ constants describe different selections that are used when generating line tones.

LINETONEMODE_CUSTOM

The tone is a custom tone defined by its component frequencies, of type LINEGENERATETONE.

LINETONEMODE_RINGBACK

The tone is ringback tone. Exact definition is service-provider defined.

LINETONEMODE_BUSY

The tone is a busy tone. Exact definition is service-provider defined.

LINETONEMODE_BEEP

The tone is a beep, such as that used to announce the beginning of a recording. Exact definition is service-provider defined.

LINETONEMODE_BILLING

The tone is a billing information tone such as a credit card prompt tone. Exact definition is service-provider defined.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

These constants are used to define tones to be generated inband over a call to the remote party. Note that tone detection of non-custom tones does not use these constants.


LINETRANSFERMODE_ Constants

The LINETRANSFERMODE_ bit-flag constants describe different ways of resolving call transfer requests.

LINETRANSFERMODE_TRANSFER

The transfer is resolved by transferring the initial call to the consultation call. Both calls will become idle to the application.

LINETRANSFERMODE_CONFERENCE

The transfer is resolved by establishing a three-way conference between the application, the party connected to the initial call, and the party connected to the consultation call. A conference call is created when this option is selected.

No extensibility. All 32 bits are reserved.


LINETRANSLATEOPTION_ Constants

The LINETRANSLATEOPTION_ bit-flag constant describes an option used by address translation.

LINETRANSLATEOPTION_CARDOVERRIDE

The default calling card is to be overidden with a specified one.

LINETRANSLATEOPTION_CANCELCALLWAITING

If a Cancel Call Waiting string is defined for the location, setting this bit will cause that string to be inserted at the beginning of the dialable string. This is commonly used by data modem and fax applications to prevent interruption of calls by call waiting beeps. If no Cancel Call Waiting string is defined for the location, this bit has no affect. Note that applications using this bit are advised to also set the LINECALLPARAMFLAGS_SECURE bit in the dwCallParamFlags field of the LINECALLPARAMS structure passed in to lineMakeCall through the lpCallParams parameter, so that if the line device uses a mechanism other than dialable digits to suppress call interrupts that that mechanism will be invoked.

LINETRANSLATEOPTION_FORCELOCAL

If the number is local but would have been translated as a long distance call (LINETRANSLATERESULT_INTOLLLIST bit set in the LINETRANSLATEOUTPUT structure), this option will force it to be translated as local. This is a temporary override of the toll list setting.

LINETRANSLATEOPTION_FORCELD

If the address could potentially have been a toll call, but would have been translated as a local call (LINETRANSLATERESULT_NOTINTOLLLIST bit set in the LINETRANSLATEOUTPUT structure), this option will force it to be translated as long distance. This is a temporary override of the toll list setting.

No extensibility. All 32 bits are reserved.


LINETRANSLATERESULT_ Constants

The LINETRANSLATERESULT_ bit-flag constants describe various results of an address translation.

LINETRANSLATERESULT_CANONICAL

Indicates that the input string was in valid canonical format.

LINETRANSLATERESULT_INTERNATIONAL

Indicates that the call is being treated as an international call (country code specified in the destination address is different from the country code specified for the CurrentLocation).

LINETRANSLATERESULT_LONGDISTANCE

Indicates that the call is being treated as a long distance call (country code specified in the destination address is the same but area code is different from those specified for the CurrentLocation).

LINETRANSLATERESULT_LOCAL

Indicates that the call is being treated as a local call (country code and area code specified in the destination address are the same as those specified for the CurrentLocation).

LINETRANSLATERESULT_INTOLLLIST

Indicates that the local call is being dialed as long distance because the country has toll calling and the prefix appears in the TollPrefixList of the CurrentLocation.

LINETRANSLATERESULT_NOTINTOLLLIST

Indicates that the country supports toll calling but the prefix does not appear in the TollPrefixList, so the call is dialed as a local call. Note that if both INTOLLIST and NOTINTOLLIST are off, the current country does not support toll prefixes, and user-interface elements related to toll prefixes should not be presented to the user; if either such bit is on, the country does support toll lists, and the related user-interface elements should be enabled.

LINETRANSLATERESULT_DIALBILLING

Indicates that the returned address contains a "$".

LINETRANSLATERESULT_DIALQUIET

Indicates that the returned address contain a "@".

LINETRANSLATERESULT_DIALDIALTONE

Indicates that the returned address contains a "W".

LINETRANSLATERESULT_DIALPROMPT

Indicates that the returned address contains a "?".

LINETRANSLATERESULT_VOICEDETECT

Indicates that the returned dialable address contains a ":".

Note  The ":" (colon) character will be added to the list of characters which can be embedded in a dialable string and passed into destination addresses. Attempting to pass it from an application to a line device that supports an API version less than 0x00020000 will most likely result in LINEERR_INVALADDRESS, or possibly in the character being ignored entirely. The meaning of this character is "Pause until a voice prompt is detected, then continue dialing"; it is intended for use when automatically dialing into systems that give voice prompts, such as long distance calling card processors.

No extensibility. All 32 bits are reserved.


LINETSPIOPTION_ Constants

LINETSPIOPTION_NONREENTRANT

TAPI should call functions in this service provider one at a time; it should wait from each function to return (but not for asynchronous functions to complete) before calling the same or another function, either on the same or a different thread, on the same or a different processor.


Phone Device Constants

The following reference contains the constants for phone devices.


PHONEBUTTONFUNCTION_ Constants

The PHONEBUTTONFUNCTION_ scalar constants describe the functions commonly assigned to buttons on telephone sets.

PHONEBUTTONFUNCTION_UNKNOWN

A "dummy" function assignment that indicates that the exact function of the button is unknown or has not been assigned.

PHONEBUTTONFUNCTION_CONFERENCE

Initiates a conference call or adds a call to a conference call.

PHONEBUTTONFUNCTION_TRANSFER

Initiates a call transfer or completes the transfer of a call.

PHONEBUTTONFUNCTION_DROP

Drops the active call.

PHONEBUTTONFUNCTION_HOLD

Places the active call on hold.

PHONEBUTTONFUNCTION_RECALL

Unholds a call.

PHONEBUTTONFUNCTION_DISCONNECT

Disconnects a call, such as after initiating a transfer.

PHONEBUTTONFUNCTION_CONNECT

Reconnects a call that is on consultation hold.

PHONEBUTTONFUNCTION_MSGWAITON

Turns on a message waiting lamp.

PHONEBUTTONFUNCTION_MSGWAITOFF

Turns off a message waiting lamp.

PHONEBUTTONFUNCTION_SELECTRING

Allows the user to select the ring pattern of the phone.

PHONEBUTTONFUNCTION_ABBREVDIAL

The number to be dialed will be indicated using a short, abbreviated number consisting of one digit or a few digits.

PHONEBUTTONFUNCTION_FORWARD

Initiates or changes call forwarding to this phone.

PHONEBUTTONFUNCTION_PICKUP

Picks up a call ringing on another phone.

PHONEBUTTONFUNCTION_RINGAGAIN

Initiates a request to be notified if a call cannot be completed normally because of a busy signal or no answer.

PHONEBUTTONFUNCTION_PARK

Parks the active call on another phone, placing it on hold there.

PHONEBUTTONFUNCTION_REJECT

Rejects an inbound call before the call has been answered.

PHONEBUTTONFUNCTION_REDIRECT

Redirects an inbound call to another extension before the call has been answered.

PHONEBUTTONFUNCTION_MUTE

Mutes the phone's microphone device.

PHONEBUTTONFUNCTION_VOLUMEUP

Increases the volume of audio through the phone's handset speaker or speakerphone.

PHONEBUTTONFUNCTION_VOLUMEDOWN

Decreases the volume of audio through the phone's handset speaker or speakerphone.

PHONEBUTTONFUNCTION_SPEAKERON

Turns the phone's external speaker on.

PHONEBUTTONFUNCTION_SPEAKEROFF

Turns the phone's external speaker off.

PHONEBUTTONFUNCTION_FLASH

Generates the equivalent of an onhook/offhook sequence. A flash typically indicates that any digits typed next are to be understood as commands to the switch. On many switches, places an active call on consultation hold.

PHONEBUTTONFUNCTION_DATAON

Indicates that the next call is a data call.

PHONEBUTTONFUNCTION_DATAOFF

Indicates that the next call is not a data call.

PHONEBUTTONFUNCTION_DONOTDISTURB

Places the phone in "do not disturb" mode; incoming calls receive a busy signal or are forwarded to an operator or voice mail system.

PHONEBUTTONFUNCTION_INTERCOM

Connects to the intercom to broadcast a page.

PHONEBUTTONFUNCTION_BRIDGEDAPP

Selects a particular appearance of a bridged address.

PHONEBUTTONFUNCTION_BUSY

Makes the phone appear "busy" to incoming calls.

PHONEBUTTONFUNCTION_CALLAPP

Selects a particular call appearance.

PHONEBUTTONFUNCTION_DATETIME

Causes the phone to display current date and time; this information would be sent by the switch.

PHONEBUTTONFUNCTION_DIRECTORY

Calls up directory service from the switch.

PHONEBUTTONFUNCTION_COVER

Forwards all calls destined for this phone to another phone used for coverage.

PHONEBUTTONFUNCTION_CALLID

Requests display of caller ID on the phone's display.

PHONEBUTTONFUNCTION_LASTNUM

Redials last number dialed.

PHONEBUTTONFUNCTION_NIGHTSRV

Places the phone in the mode it is configured for during night hours.

PHONEBUTTONFUNCTION_SENDCALLS

Sends all calls to another phone used for coverage; same as PHONEBUTTONFUNCTION_COVER.

PHONEBUTTONFUNCTION_MSGINDICATOR

Controls the message indicator lamp.

PHONEBUTTONFUNCTION_REPDIAL

Repertory dialing—the number to be dialed is provided as a shorthand following pressing of this button.

PHONEBUTTONFUNCTION_SETREPDIAL

Programs the shorthand-to-phone number mappings accessible by means of repertory dialing (the "REPDIAL" button).

PHONEBUTTONFUNCTION_SYSTEMSPEED

The number to be dialed is provided as a shorthand following pressing of this button. The mappings for system speed dialing are configured inside the switch.

PHONEBUTTONFUNCTION_STATIONSPEED

The number to be dialed is provided as a shorthand following pressing of this button. The mappings for station speed dialing are specific to this station (phone).

PHONEBUTTONFUNCTION_CAMPON

Camps-on an extension that returns a busy indication. When the remote station returns to idle, the phone will be rung with a distinctive patterns. Picking up the local phone reinitiates the call.

PHONEBUTTONFUNCTION_SAVEREPEAT

When pressed while a call or call attempt is active, it will remember that call's number or command. When pressed while no call is active (such as during dial tone), it repeats the most saved command.

PHONEBUTTONFUNCTION_QUEUECALL

Queues a call to an outside number after it encounters a trunk-busy indication. When a trunk becomes later available, the phone will be rung with a distinctive pattern. Picking up the local phone reinitiates the call.

PHONEBUTTONFUNCTION_NONE

A "dummy" function assignment that indicates that the button does not have a function.

Values in the range 0x80000000 to 0xFFFFFFFF can be assigned for device-specific extensions; values in the range 0x00000000 to 0x7FFFFFFF are reserved.

The PHONEBUTTONFUNCTION_ constants have values commonly found on current telephone sets. These button functions can be used to invoke the corresponding function from the switch using lineDevSpecificFeature. Note that TAPI does not define the semantics of the button functions; it only provides access to the corresponding function. The behavior associated with each of the function values above is generic and may vary based on the telephony environment.


PHONEBUTTONMODE_ Constants

The PHONEBUTTONMODE_ bit-flag constants describe the button classes.

PHONEBUTTONMODE_DUMMY

This value is used to describe a button/lamp position that has no corresponding button but has only a lamp.

PHONEBUTTONMODE_CALL

The button is assigned to a call appearance.

PHONEBUTTONMODE_FEATURE

The button is assigned to requesting features from the switch, such as hold, conference, and transfer.

PHONEBUTTONMODE_KEYPAD

The button is one of the twelve keypad buttons, 0 through 9, '*', and '#'.

PHONEBUTTONMODE_LOCAL

The button is a local function button, such as mute or volume control.

PHONEBUTTONMODE_DISPLAY

The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.

No extensibility. All 32 bits are reserved.

This enumeration type is used in the PHONECAPS data structure to describe the meaning associated with the phone's buttons.


PHONEBUTTONSTATE_ Constants

The PHONEBUTTONSTATE_ bit-flag constants describe the button's positions.

PHONEBUTTONSTATE_UP

The button is in the "up" state.

PHONEBUTTONSTATE_DOWN

The button is in the "down" state (pressed down).

PHONEBUTTONSTATE_UNKNOWN

Indicates that the up or down state of the button is not known at this time, but may become known at a future time.

PHONEBUTTONSTATE_UNAVAIL

Indicates that the up or down state of the button is not known to the service provider, and will not become known at a future time.

No extensibility. All 32 bits are reserved.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the phone, and to not use these PHONEBUTTONSTATE_ values if not supported on the negotiated version.


PHONEERR_ Constants

This is the list of error codes that the implementation may return when invoking operations on phone devices. Consult the individual function descriptions to determine which of these error codes each function may return.

PHONEERR_ALLOCATED

The specified resource is already allocated.

PHONEERR_BADDEVICEID

The specified device ID is invalid or out of range.

PHONEERR_INCOMPATIBLEAPIVERSION

The application requested an API version or version range that cannot be supported by the Telephony API implementation and/or corresponding service provider.

PHONEERR_INCOMPATIBLEEXTVERSION

The application requested an extension version or version range that cannot supported by the service provider.

PHONEERR_INIFILECORRUPT

Because of internal inconsistencies or formatting problems in the TELEPHON.INI file, it cannot be read and understood properly by TAPI.

PHONEERR_INUSE

The device is currently in use. The device cannot be configured.

PHONEERR_INVALAPPHANDLE

The application's specified usage handle or registration handle is invalid.

PHONEERR_INVALAPPNAME

The specified application name is invalid. If an application name is specified by the application, it is assumed that the string does not contain any nondisplayable characters and is NULL-terminated.

PHONEERR_INVALBUTTONLAMPID

The specified button/lamp ID is out of range or invalid.

PHONEERR_INVALBUTTONMODE

The button mode parameter is invalid.

PHONEERR_INVALBUTTONSTATE

The button states parameter is invalid.

PHONEERR_INVALDATAID

The specified data ID is invalid.

PHONEERR_INVALDEVICECLASS

The specified phone does not support the indicated device class.

PHONEERR_INVALHOOKSWITCHDEV

The hookswitch device parameter is invalid.

PHONEERR_INVALHOOKSWITCHMODE

The hookswitch mode parameter is invalid.

PHONEERR_INVALLAMPMODE

The specified lamp mode parameter is invalid.

PHONEERR_INVALPARAM

A parameter, such as a row or column value or a window handle, is invalid or out of range.

PHONEERR_INVALPHONEHANDLE

The specified device handle is invalid.

PHONEERR_INVALPHONESTATE

The phone device is not in a valid state for the requested operation.

PHONEERR_INVALPOINTER

One or more of the specified pointer parameters are invalid.

PHONEERR_INVALPRIVILEGE

The dwPrivilege parameter is invalid.

PHONEERR_INVALRINGMODE

The ring mode parameter is invalid.

PHONEERR_NODEVICE

The specified device ID, which was previously valid, is no longer accepted because the associated device has been removed from the system since TAPI was last initialized.

PHONEERR_NODRIVER

The telephone service provider for the specified device found that one of its components is missing or corrupt in a way that was not detected at initialization time. The user should be advised to use the Telephony Control Panel to correct the problem.

PHONEERR_NOMEM

Insufficient memory to complete the requested operation, or unable to allocate or lock memory.

PHONEERR_NOTOWNER

The application does not have owner privilege to the specified phone device.

PHONEERR_OPERATIONFAILED

The operation failed for an unspecified reason.

PHONEERR_OPERATIONUNAVAIL

The operation is not available.

PHONEERR_REINIT

If TAPI reinitialization has been requested, for example as a result of adding or removing a telephony service provider, then phoneInitialize, phoneInitializeEx or phoneOpen requests are rejected with this error until the last application shuts down its usage of the API (using phoneShutdown), at which time the new configuration becomes effective and applications are once again permitted to call phoneInitialize or phoneInitializeEx.

PHONEERR_RESOURCEUNAVAIL

The operation cannot be completed because of resource overcommitment.

PHONEERR_STRUCTURETOOSMALL

The specified phone caps structure is too small.

PHONEERR_UNINITIALIZED

The operation was invoked before any application called phoneInitialize, phoneInitializeEx.

The values 0xC0000000 through 0xFFFFFFFF are available for device-specific extensions; the values 0x80000000 through 0xBFFFFFFF are reserved; and 0x00000000 through 0x7FFFFFFF are used as request IDs.

If an application gets an error return that it does not specifically handle (such as an error defined by a device-specific extension), it should treat the error as a PHONEERR_OPERATIONFAILED (for an unspecified reason).


PHONEFEATURE_ Constants

The PHONEFEATURE_ constants list the operations that can be invoked on a phone using this API. Each of the PHONEFEATURE_ values correspond to a TAPI function with an identical or similar name.

PHONEFEATURE_GETBUTTONINFO (0x00000001)

PHONEFEATURE_GETDATA (0x00000002)

PHONEFEATURE_GETDISPLAY (0x00000004)

PHONEFEATURE_GETGAINHANDSET (0x00000008)

PHONEFEATURE_GETGAINSPEAKER (0x00000010)

PHONEFEATURE_GETGAINHEADSET (0x00000020)

PHONEFEATURE_GETHOOKSWITCHHANDSET (0x00000040)

PHONEFEATURE_GETHOOKSWITCHSPEAKER (0x00000080)

PHONEFEATURE_GETHOOKSWITCHHEADSET (0x00000100)

PHONEFEATURE_GETLAMP (0x00000200)

PHONEFEATURE_GETRING (0x00000400)

PHONEFEATURE_GETVOLUMEHANDSET (0x00000800)

PHONEFEATURE_GETVOLUMESPEAKER (0x00001000)

PHONEFEATURE_GETVOLUMEHEADSET (0x00002000)

PHONEFEATURE_SETBUTTONINFO (0x00004000)

PHONEFEATURE_SETDATA (0x00008000)

PHONEFEATURE_SETDISPLAY (0x00010000)

PHONEFEATURE_SETGAINHANDSET (0x00020000)

PHONEFEATURE_SETGAINSPEAKER (0x00040000)

PHONEFEATURE_SETGAINHEADSET (0x00080000)

PHONEFEATURE_SETHOOKSWITCHHANDSET (0x00100000)

PHONEFEATURE_SETHOOKSWITCHSPEAKER (0x00200000)

PHONEFEATURE_SETHOOKSWITCHHEADSET (0x00400000)

PHONEFEATURE_SETLAMP (0x00800000)

PHONEFEATURE_SETRING (0x01000000)

PHONEFEATURE_SETVOLUMEHANDSET (0x02000000)

PHONEFEATURE_SETVOLUMESPEAKER (0x04000000)

PHONEFEATURE_SETVOLUMEHEADSET (0x08000000)


PHONEHOOKSWITCHDEV_ Constants

The PHONEHOOKSWITCHDEV_ bit-flag constants describe various audio I/O devices each with its own hookswitch controllable from the computer.

PHONEHOOKSWITCHDEV_HANDSET

This is the ubiquitous, handheld, ear- and mouthpiece.

PHONEHOOKSWITCHDEV_SPEAKER

This is a built-in loudspeaker and microphone. This could also be an externally connected adjunct speaker to the telephone set.

PHONEHOOKSWITCHDEV_HEADSET

This is a headset connected to the phone set.

No extensibility. All 32 bits are reserved.

These constants are used in the PHONECAPS data structure to indicate the hookswitch device capabilities of a phone device. The PHONESTATUS structure reports the state of the phone's hookswitch devices. The function phoneSetHookSwitch and phoneGetHookSwitch use it as a parameter to select the phone's I/O device.


PHONEHOOKSWITCHMODE_ Constants

The PHONEHOOKSWITCHMODE_ bit-flag constants describe the microphone and speaker components of a hookswitch device.

PHONEHOOKSWITCHMODE_ONHOOK

The device's microphone and speaker are both onhook.

PHONEHOOKSWITCHMODE_MIC

The device's microphone is active, the speaker is mute.

PHONEHOOKSWITCHMODE_SPEAKER

The device's speaker is active, the microphone is mute.

PHONEHOOKSWITCHMODE_MICSPEAKER

The device's microphone and speaker are both active.

PHONEHOOKSWITCHMODE_UNKNOWN

The device's hookswitch mode is currently unknown.

No extensibility. All 32 bits are reserved.

These constants are used to provide an individual level of control over the microphone and speaker components of a phone device.


PHONEINITIALIZEEXOPTION_ Constants

The PHONEINITIALIZEEXOPTION_ constants specify which event notification mechanism to use when initializing a session.

PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW

The application desires to use the Hidden Window event notification mechanism.

PHONEINITIALIZEEXOPTION_USEEVENT

The application desires to use the Event Handle event notification mechanism.

PHONEINITIALIZEEXOPTION_USECOMPLETIONPORT

The application desires to use the Completion Port event notification mechanism.

See phoneInitializeEx for further details on the operation of these options.


PHONELAMPMODE_ Constants

The PHONELAMPMODE_ bit-flag constants describe various ways in which a phone's lamp can be lit.

PHONELAMPMODE_DUMMY

This value is used to describe a button/lamp position that has no corresponding lamp.

PHONELAMPMODE_OFF

The lamp is off.

PHONELAMPMODE_STEADY

Steady means the lamp is continuously lit.

PHONELAMPMODE_WINK

Wink means normal rate on and off.

PHONELAMPMODE_FLASH

Flash means slow on and off.

PHONELAMPMODE_FLUTTER

Flutter means fast on and off.

PHONELAMPMODE_BROKENFLUTTER

Broken flutter is the superposition of flash and flutter.

PHONELAMPMODE_UNKNOWN

The lamp mode is currently unknown.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Where the exact on and off cadences may differ across phone sets from different vendors, mapping of actual lamp lighting patterns for most phones onto the values listed above should be straightforward.


PHONEPRIVILEGE_ Constants

The PHONEPRIVILEGE_ bit-flag constants describe the various ways in which a phone device can be opened.

PHONEPRIVILEGE_MONITOR

An application that opens a phone device with the monitor privilege is informed about events and state changes occurring on the phone. The application cannot invoke any operations on the phone device that would change its state, so only status operations can be invoked. Multiple applications can monitor a phone device at any given time.

PHONEPRIVILEGE_OWNER

An application that opens a phone device with the owner privilege is allowed to change the state of the lamps, ringer, display, hookswitch, and data blocks of the phone. Opening a phone device in owner mode also provides monitoring of the phone device. Only one application is allowed to be the owner of a phone device at any given time.

No extensibility. All 32 bits are reserved.


PHONESTATE_ Constants

The PHONESTATE_ bit-flag constants describe various status items for a phone device.

PHONESTATE_OTHER

Phone-status items other than those listed below have changed. The application should check the current phone status to determine which items have changed.

PHONESTATE_CONNECTED

The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked or when the wire connecting the phone to the PC is plugged in with TAPI active.

PHONESTATE_DISCONNECTED

The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the PC is unplugged while TAPI is active.

PHONESTATE_OWNER

The number of owners for the phone device.

PHONESTATE_MONITORS

The number of monitors for the phone device.

PHONESTATE_DISPLAY

The display of the phone has changed.

PHONESTATE_LAMP

A lamp of the phone has changed.

PHONESTATE_RINGMODE

The ring mode of the phone has changed.

PHONESTATE_RINGVOLUME

The ring volume of the phone has changed.

PHONESTATE_HANDSETHOOKSWITCH

The handset hookswitch state has changed.

PHONESTATE_HANDSETVOLUME

The handset's speaker volume setting has changed.

PHONESTATE_HANDSETGAIN

The handset's microphone gain setting has changed.

PHONESTATE_SPEAKERHOOKSWITCH

The speakerphone's hookswitch state has changed.

PHONESTATE_SPEAKERVOLUME

The speakerphone's speaker volume setting has changed.

PHONESTATE_SPEAKERGAIN

The speakerphone's microphone gain setting state has changed.

PHONESTATE_HEADSETHOOKSWITCH

The headset's hookswitch state has changed.

PHONESTATE_HEADSETVOLUME

The headset's speaker volume setting has changed.

PHONESTATE_HEADSETGAIN

The headset's microphone gain setting has changed.

PHONESTATE_SUSPEND

The application's use of the phone is temporarily suspended.

PHONESTATE_RESUME

The application's use of the phone device is resumed after having been suspended for some time.

PHONESTATE_DEVSPECIFIC

The phone's device-specific information has changed.

PHONESTATE_REINIT

Items have changed in the configuration of phone devices. To become aware of these changes (as for the appearance of new phone devices), the application should reinitialize its use of TAPI.

PHONESTATE_CAPSCHANGE

Indicates that, due to configuration changes made by the user or other circumstances, one or more of the fields in the PHONECAPS structure have changed. The application should use phoneGetDevCaps to read the updated structure. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will receive PHONE_STATE messages specifying PHONESTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI to obtain the updated information.

PHONESTATE_REMOVED

Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A PHONE_STATE message with this value will normally be immediately followed by a PHONE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized will result in PHONEERR_NODEVICE being returned to the application. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will not receive any notification.

No extensibility. All 32 bits are reserved.


PHONESTATUSFLAGS_ Constants

The PHONESTATUSFLAGS_ bit-flag constants describe a variety of phone device status information.

PHONESTATUSFLAGS_CONNECTED

Specifies whether the phone is currently connected to TAPI. TRUE if connected, FALSE otherwise.

PHONESTATUSFLAGS_SUSPENDED

Specifies whether TAPI's manipulation of the phone device is suspended. TRUE if suspended, FALSE otherwise. An application's use of a phone device may be temporarily suspended when the switch wants to manipulate the phone in a way that cannot tolerate interference from the application.

No extensibility. All 32 bits are reserved.


STRINGFORMAT_ Constants

The STRINGFORMAT_ enumeration constants describe different string formats.

STRINGFORMAT_ASCII

Specifies standard ASCII character format using one byte per character.

STRINGFORMAT_DBCS

Specifies standard DBCS character format using two bytes per character.

STRINGFORMAT_UNICODE

Specifies standard Unicode character format using two bytes per character.

STRINGFORMAT_BINARY

This is an array of unsigned characters; could be used for numeric values.

No extensibility. All 32 bits are reserved.


Assisted Telephony Constants

The following constants are used by Assisted Telephony.


TAPI Error Values

TAPIERR_INVALDESTADDRESS

The pointer to the destination address is not valid, is NULL, or the destination address string is too long.

TAPIERR_INVALPOINTER

The pointer does not reference a valid memory location. One or more of the pointers lpszDestAddress, lpszAppName, lpszCalledParty, or lpszComment have been specified but are invalid.

TAPIERR_NOREQUESTRECIPIENT

No recipient application is available to handle the request. The user should start the recipient application and try again.

TAPIERR_REQUESTFAILED

The request failed for unspecified reasons.

TAPIERR_REQUESTQUEUEFULL

A recipient application is active, but the request queue is full or there is insufficient memory to expand the queue. The application can try again later.

Any other TAPIERR_ values are nonfunctional in Win32-based applications and must not be used.


Device Classes

A device class is a group of related physical devices or device drivers through which applications send and receive the information or data that makes up a call. Every device class has a device class name that uniquely identifies the class, and provides information about the programming interface and commands that can be used to open and communicate with the devices in the class.

The Telephony application programming interface (TAPI) associates devices from one or more device classes to each line or phone device. You access one of these devices by retrieving the device identifier for the device using the lineGetID or phoneGetID function. You supply the device class name, and the function returns the specific port name, device name, device handle, or device identifier that you need to open and access the device. The format of the information returned depends on the device class and is described in subsequent topics of this section.

Note  The device identifier definitions apply to 16-bit and 32-bit TAPI. In some cases, the data type of a media handle in the device identifier definition may be different from that specified by the Microsoft® Windows® operating system version 3.x or Microsoft® Win32® application programming interface. For example, Windows version 3.x and Win32 define wave device identifiers with the UINT type, but TAPI defines this device identifier with the DWORD type. In such cases, you should cast the media handle to the appropriate data type when using it with the Windows version 3.x or Win32 API.

You also use device class names with the lineConfigDialog and phoneConfigDialog functions to enable the user to set configuration options for the given device, with the lineGetIcon and phoneGetIcon functions to retrieve an icon to represent the given device, and with the lineGetDevConfig and lineSetDevConfig functions to directly retrieve and set configuration options for the given device.

By default, there are the following device class names.

Device Class Name	Description
comm	Communications port.
comm/datamodem	Modem through a communications port.
comm/datamodem/portname	Name of the device to which a modem is connected.
wave/in	Wave audio device (input only).
wave/out	Wave audio device (output only).
midi/in	Midi sequencer (input only).
midi/out	Midi sequencer (output only).
tapi/line	Line device.
tapi/phone	Phone device.
ndis	Network device.
tapi/terminal	Terminal device.
Note  These names are not case sensitive; you can use any combination of uppercase and lowercase letters.

Additional device classes and device class names may be available on a given system. In general, if a device does not belong to one of the default device classes, the manufacturer typically defines a new device class and assigns a unique device class name. Check the documentation for the device to determine what additional device classes are available for it. Note, however, that although the device class and media mode are related, they are not the same. A media mode describes a format of information on a call, and a device class defines the programming interface used to manage that information. So, even if a manufacturer defines a new media mode, it is not necessarily true that the manufacturer also needs to define a new device class to support the mode.

The format of the configuration data used with the lineSetDevConfig and lineGetDevConfig functions also depends on the device class. In general, you use lineGetDevConfig to save a copy of the current device configuration data and then later use lineSetDevConfig with the saved configuration data to restore the device configuration to the previous state. This is a convenient way to temporarily change the configuration without requiring the user to manually restore it to the previous state. Because the exact format of the device configuration data may be different with each service provider, you should not use lineSetDevConfig and lineGetDevConfig to manipulate the device configuration data directly. Some formats are provided only for information.


comm

The comm device class consists of communications ports. You access these devices by using the Win32 file and communications functions.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_ASCII value and appending a null-terminated string that specifies the name of the communication port (such as COM1). You use this port name in a call to the CreateFile function to open the communication device for the line or phone.


comm/datamodem

The comm/datamodem device class consists of modem devices. You access these devices by using the Win32 file and communications functions. Devices in this class are associated with line devices that support the LINEMEDIAMODE_DATAMODEM media mode, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting dwStringFormat to the STRINGFORMAT_BINARY value and appending these additional members:

HANDLE hComm;            // handle of open comm. device

CHAR   szDeviceName[1];  // name of comm. device

The hComm member is the handle of the open communications port. This member is NULL if the port is not yet open or if the dwSelect parameter of lineGetID is not the LINECALLSELECT_CALL value. If a call is active, the service provider typically opens the port itself to get direct control of the communications hardware, but is only required to return a valid handle if the line is connected. The service provider opens the port using the FILE_FLAG_OVERLAPPED value and then configures the port using the settings specified by the lineSetDevConfig function. You can set additional configuration options for the device by using Win32 functions with the returned handle.

The szDeviceName member is a null-terminated ASCII string that specifies the name of the communications port associated with the line, address, or call.

If hComm is a valid handle, you can use it in subsequent calls to Win32 file functions, such as ReadFile and WriteFile, to send and receive data on the call. When you are finished using the communications port and preferably before you use the lineDeallocateCall function to deallocate the call, you must close the port by using the CloseHandle function.

When using the lineGetDevConfig and lineSetDevConfig functions, some service providers require that the configuration data for this device class have the following format:

typedef struct  tagDEVCFG  {

  DEVCFGHDR   dfgHdr;

  COMMCONFIG  commconfig;

} DEVCFG, *PDEVCFG, FAR* LPDEVCFG;

// Device setting information

typedef struct  tagDEVCFGDR  {

  DWORD       dwSize;

  DWORD       dwVersion;

  WORD        fwOptions;

  WORD        wWaitBong;

} DEVCFGHDR;

The following is device configuration information for use with the lineGetDevConfig and lineSetDevConfig functions.

dwSize

Sum of the size of the DEVCFGHDR structure and the actual size of COMMCONFIG structure.

dwVersion

Version number of the Unimodem DevConfig structure. This member can be MDMCFG_VERSION (0x00010003).

dwOptions

Option flags that appear on the Unimodem Option page. This member can be a combination of these values:

TERMINAL_PRE (1)

Displays the pre-terminal screen.

TERMINAL_POST (2)

Displays the post-terminal screen.

MANUAL_DIAL (4)

Dials the phone manually, if capable of doing so.

LAUNCH_LIGHTS (8)

Displays the modem tray icon.

Only the LAUNCH_LIGHTS value is set by default

WWaitBong

Number of seconds (in two seconds granularity) to replace the wait for credit tone ($).

Commconfig

COMMCONFIG structure that can be used with the Win32 communications and MCX functions.


comm/datamodem/portname

The comm/datamodem/portname device class consists of the device names to which modems are attached. When this device name is specified in a call to the lineGetID function, the function fills the VARSTRING structure with a null-terminated ANSI (not UNICODE) string specifying the name of the port to which the specified modem is attached, such as "COM1\0". This is intended primarily for identification purposes in the user interface, but could be used under some circumstances to open the device directly, bypassing the service provider (if the service provider does not already have the device open itself). If there is no port associated with the device, a null string ("\0") is returned in the VARSTRING structure (with a string length of 1).


wave/in

The wave/in device class consists of audio devices for low-level wave audio input. You access these devices by using the wave functions, which are described in the Microsoft Win32 Software Development Kit (SDK). Devices in this class are associated with line devices that support the LINEMEDIAMODE_AUTOMATEDVOICE media modem, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of audio device

The DeviceId member is the identifier of a closed audio device. You use this identifier in a call to the waveInOpen function to open the device for input. You can use the resulting device handle to record digitized audio data from the line or phone device.

Although a "wave" device class also exists for low-level wave audio devices, you should always use the wave/in device class for low-level wave input.


wave/out

The wave/out device class consists of audio devices for low-level wave audio output. You access these devices by using the wave functions, which are described in the Win32 SDK. Devices in this class are associated with line devices that support the LINEMEDIAMODE_AUTOMATEDVOICE media mode, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of audio device

The DeviceId member is the identifier of a closed audio device. You use this identifier in a call to the waveOutOpen function to open the device for output. You can use the resulting device handle to play digitized audio data at the line or phone device.

Although a "wave" device class also exists for low-level wave audio devices, you should always use the wave/out device class for low-level wave output.


midi/in

The midi/in device class consists of MIDI sequencers that are used for input. You access these devices by using the MIDI functions, which are described in the Win32 SDK.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of MIDI device

The DeviceId member is the identifier of a closed MIDI device. You use this identifier in a call to the midiInOpen function to open the device for input. You can use the resulting device handle to record MIDI data from the line or phone device.


midi/out

The midi/out device class consists of MIDI sequencers that are used for output. You access these devices by using the MIDI functions, which are described in the Win32 SDK.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of MIDI device

The DeviceId member is the identifier of a closed MIDI device. You use this identifier in a call to the midiOutOpen function to open the device for output. You can use the resulting device handle to play MIDI data at the line or phone device.


tapi/line

The tapi/line device class consists of all line devices. You access these devices using the TAPI line functions.

The lineGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member.

DWORD dwDeviceI;  // line device identifier

The dwDeviceId member is the identifier of the line device associated with the line handle given by lineGetID.

The phoneGetID function also fills a VARSTRING structure, setting dwStringFormat to STRINGFORMAT_BINARY and appending this additional member:

DWORD adwDeviceIds[];  // array of line device identifiers

The adwDeviceIds member is an array containing the device identifiers of all line devices that are associated with the phone device. If there are no associated line devices, phoneGetID returns the PHONEERR_INVALDEVICECLASS value.


tapi/phone

The tapi/phone device class consists of all phone devices. You access these devices by using the TAPI phone functions.

The phoneGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD dwDeviceI;  // phone device identifier

The dwDeviceId member is the identifier of the phone device associated with the phone handle given by phoneGetID.

The lineGetID function also fills a VARSTRING structure, setting dwStringFormat to STRINGFORMAT_BINARY and appending this additional member:

DWORD adwDeviceIds[];  // array of phone device identifiers

The adwDeviceIds member is an array containing the device identifiers of all phone devices that are associated with the given line device. If there are no associated phone devices, lineGetID returns the LINEERR_INVALDEVICECLASS value.


ndis

The ndis device class consists of devices that can be associated with network driver interface specification (NDIS) media access control (MAC) drivers to support network communications. You access these devices by using functions.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending these additional members:

HANDLE  hDevice;          // NDIS connection identifier

CHAR    szDeviceType[1];  // name of device

The hDevice member is the identifier to pass to a MAC, such as the asynchronous MAC for dial-up networking, to associate a network connection with the call/modem connection. The szDeviceType member is a null-terminated ASCII string specifying the name of the device associated with the identifier. For more information, see documentation about writing NDIS MAC drivers for use with dial-up networking.


tapi/terminal

The tapi/terminal device class consists of the phone devices associated with each terminal on a line or the terminal on each line associated with a phone device. You access these devices by using the TAPI line or phone functions.

The lineGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD adwDeviceId[];  // array of phone device identifiers

The adwDeviceId member is an array of phone device identifiers. There is one array element for each terminal specified by the dwNumTerminals member in the LINEDEVCAPS structure for the given line device. Each element specifies the identifier of the phone device associated with the corresponding terminal on the line. If there is no phone device associated with a terminal, the element is set to −1 (0xFFFFFFFF).

The phoneGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD adwTerminalID[];  // array of terminal identifiers

The adwTerminalID member is an array of terminal identifiers. There is one array element for each line device identifier specified by the lineInitialize or lineInitializeEx function. Each array element contains the terminal identifier associated with the phone device for the given line device. If there is no phone device, the element is set to −1 (0xFFFFFFFF). The terminal identifiers range in value from zero to one less than the number specified by the dwNumTerminals member in the LINEDEVCAPS structure.


Reference

This section includes the telephony API function, message, structure, and constant references for line devices, phone devices, and assisted telephony.


Functions

This section contains an alphabetical list of the line device, phone device, and assisted telephony functions in the Telephony applications programming interface (API).

The information for each function includes a list of the valid call states on entry of the function and typical call state transitions when the request completes. Note that the actual states in which a function may be performed may be further limited by the capabilities of the service provider. Applications must check the dwCallFeatures field in the LINECALLSTATUS structure, the dwAddressFeatures field in the LINEADDRESSSTATUS structure, and the dwLineFeatures field in the LINEDEVSTATUS structure to determine whether or not a function is permitted at that point in time.


Line Device Functions

This section contains the functions for line devices.


lineAccept

The lineAccept function accepts the specified offered call. It may optionally send the specified user-to-user information to the calling party.

LONG lineAccept(

HCALL hCall,
LPCSTR lpsUserUserInfo,
DWORD dwSize
);
Parameters

hCall

A handle to the call to be accepted. The application must be an owner of the call. Call state of hCall must be offering.

lpsUserUserInfo

A pointer to a string containing user-to-user information to be sent to the remote party as part of the call accept. This pointer can be left NULL if no user-to-user information is to be sent. User-to-user information is only sent if supported by the underlying network (see LINEDEVCAPS). The protocol discriminator field for the user-to-user information, if required, should appear as the first byte of the buffer pointed to by lpsUserUserInfo, and must be accounted for in dwSize.

dwSize

The size in bytes of the user-to-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-to-user information is sent to the calling party and dwSize is ignored.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful, or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG.

Remarks

The lineAccept function is used in telephony environments like Integrated Services Digital Network (ISDN) that allow alerting associated with incoming calls to be separate from the initial offering of the call. When a call comes in, it is first offered. For some small amount of time, the application may have the option to reject the call using lineDrop, redirect the call to another station using lineRedirect, answer the call using lineAnswer, or accept the call using lineAccept. After a call has been successfully accepted, alerting at both the called and calling device begins. After a call has been accepted by an application, the call state typically transitions to accepted.

Alerting is reported to the application by the LINE_LINEDEVSTATE message with the ringing indication.

The lineAccept function may also be supported by non-ISDN service providers. The call state transition to accepted can be used by other applications as an indication that another application has claimed responsibility for the call and has presented the call to the user.

The application has the option to send user-to-user information at the time of the accept. Even if user-to-user information is sent, there is no guarantee that the network will deliver this information to the calling party. An application should consult a line's device capabilities to determine whether call accept is available.

For information about the listing of service dependencies, see Service Dependencies..

See Also

LINE_REPLY, lineAnswer, LINEDEVCAPS, lineDrop, lineRedirect


lineAddProvider

The lineAddProvider function installs a new Telephony Service Provider into the Telephony system.

LONG lineAddPr ovider(

LPCSTR lpszProviderFilename,
HWND hwndOwner,
LPDWORD lpdwPermanentProviderID
);
Parameters

lpszProviderFilename

A pointer to a NULL-terminated string containing the path of the service provider to be added.

hwndOwner

A handle to a window to which any dialogs which need to be displayed as part of the installation process (for example, by the service provider's TSPI_providerInstall function) would be attached. Can be NULL to indicate that any window created during the function should have no owner window.

lpdwPermanentProviderID

A pointer to a DWORD-sized memory location into which TAPI writes the permanent provider ID of the newly installed service provider.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM, LINEERR_NOMULTIPLEINSTANCE, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED.

Remarks

During this function call, TAPI checks to ensure that it can access the service provider by calling its TSPI_providerInstall function; if this is unsuccessful (if the DLL or function cannot be found, or if TSPI_providerInstall returns an error), the function fails and the provider is not added to the telephony system. If this is successful, and the Win32 Telephony system is active (one or more applications have called lineInitialize or lineInitializeEx), TAPI does not attempt to launch the newly-added service provider. Instead, in order to activate the new service provider, TAPI issues a message to restart Windows. When the activation succeeds, applications will be informed of any new devices created by way of LINE_CREATE or PHONE_CREATE messages, or by a LINE_LINEDEVSTATE message requesting reinitialization (if the application does not support the CREATE messages).

This function copies no files—not the service provider DLL itself nor any supporting files; it is the responsibility of the application managing the addition of the provider to ensure that the provider is installed in a directory where it can be found by TAPI (for example, \WINDOWS, \WINDOWS\SYSTEM, or elsewhere on the path), and that all other files necessary for operation.

Although this is a new function which older applications would not be expected to call, for backward compatibility, they should not be prevented from doing so; the function will work the same way for all applications.

See Also

LINE_CREATE, LINE_LINEDEVSTATE, lineInitialize, lineInitializeEx, PHONE_CREATE


lineAddToConference

The lineAddToConference function adds the call specified by hConsultCall to the conference call specified by hConfCall.

LONG lineAddToConference(

HCALL hConfCall,
HCALL hConsultCall
);
Parameters

hConfCall

A handle to the conference call. The application must be an owner of this call. Any monitoring (media, tones, digits) on a conference call applies only to the hConfCall, not to the individual participating calls. Call state of hConfCall must be onHoldPendingConference or onHold.

hConsultCall

A handle to the call to be added to the conference call. The application must be an owner of this call. This call cannot be a parent of another conference or a participant in any conference. Depending on the device capabilities indicated in LINEADDRESSCAPS, the hConsultCall may not necessarily have been established using lineSetupConference or linePrepareAddToConference. The call state of hConsultCall must be connected, onHold, proceeding, or ringback. Many PBXs allow calls to be added to conferences before they are actually answered.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful, or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_CONFERENCEFULL, LINEERR_NOTOWNER, LINEERR_INVALCONFCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

If LINEERR_INVALCALLHANDLE is returned, the specified call handle for the added call is invalid, hConsultCall is a parent of another conference or already a participant in a conference, hConsultCall cannot be added for other reasons (such as, it must have been established using lineSetupConference or linePrepareAddToConference), or hConsultCall and hConfCall are calls on different open lines.

The call handle of the added party remains valid after adding the call to a conference. Its state typically changes to conferenced while the state of the conference call typically becomes connected. Using lineGetConfRelatedCalls, you can obtain a list of call handles that are part of the same conference call as the specified call. The specified call is either a conference call or a participant call in a conference call. New handles are generated for those calls for which the application does not already have handles, and the application is granted monitor privilege to those calls. The handle to an individual participating call can be used later to remove that party from the conference call using lineRemoveFromConference.

Note that if lineGetConfRelatedCalls is called immediately after lineAddToConference, it may not return a complete list of related calls because TAPI waits to receive a LINE_CALLSTATE message indicating that the call has entered LINECALLSTATE_CONFERENCED before it considers the call to actually be part of the conference (that is, the conferenced state is confirmed by the service provider). Once the application has received the LINE_CALLSTATE message, lineGetConfRelatedCalls returns complete information. Note that all calls that are part of a conference must exist on the same open line.

The call states of the calls participating in a conference are not independent. For example, when dropping a conference call, all participating calls may automatically become idle. An application should consult the line's device capabilities to determine what form of conference removal is available. The application should track the LINE_CALLSTATE messages to determine what happened to the calls involved.

The conference call is established either by lineSetupConference or lineCompleteTransfer. The call added to a conference is typically established using lineSetupConference or linePrepareAddToConference. Some switches may allow adding arbitrary calls to the conference, and such a call may have been set up using lineMakeCall and be on (hard) hold. The application may examine the dwAddrCapFlags field of the LINEADDRESSCAPS structure to determine the permitted operations.

See Also

LINE_CALLSTATE, LINEADDRESSCAPS, lineCompleteTransfer, lineGetConfRelatedCalls, lineMakeCall, linePrepareAddToConference, lineSetupConference, lineRemoveFromConference


lineAgentSpecific

The lineAgentSpecific function allows the application to access proprietary handler-specific functions of the agent handler associated with the address. The meaning of the extensions are specific to the agent handler. Each set of agent-related extensions is identified by a universally unique 128-bit extension ID which must be obtained, along with the specification for the extension, from the promulgator of that extension (usually the author of the agent handler software on the telephony server). The list of extensions supported by the agent handler is obtained from the LINEAGENTCAPS structure returned by lineGetAgentCaps.

LONG lineAgentSpecific(

HLINE hLine,
DWORD dwAddressID,
DWORD dwAgentExtensionIDIndex,
LPVOID lpParams,
DWORD dwSize
);
Parameters

hLine

A handle to the open line device.

dwAddressID

An address on the open line device.

dwAgentExtensionIDIndex

The position in the ExtensionIDList structure in LINEAGENTCAPS of the agent handler extension being invoked.

lpParams

A pointer to a memory area used to hold a parameter block. The format of this parameter block is device specific and its contents are passed by TAPI to and from the agent handler application on the telephony server. This parameter block must specify the function to be invoked and include sufficient room for any data to be returned.

dwSize

The size in bytes of the parameter block area.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALAGENTID, LINEERR_INVALLINEHANDLE, LINEERR_INVALPARAM, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_UNINITIALIZED.

Additional return values are specific to the agent handler.

Remarks

This operation is part of the Extended Telephony services. It provides access to an agent handler-specific feature without defining its meaning.

This function provides a generic parameter profile. The interpretation of the parameter structure is handler specific. Indications and replies sent back to the application that are handler specific should use the LINE_AGENTSPECIFIC message.

An agent handler can provide access to handler-specific functions by defining parameters for use with this function. Applications that want to make use of these extensions should consult the vendor-specific documentation that describes what extensions are defined. An application that relies on these extensions will typically not be able to work with other agent handler environments.

See Also

LINEAGENTCAPS, lineGetAgentCaps


lineAnswer

The lineAnswer function answers the specified offering call.

LONG lineAnswer(

HCALL hCall,
LPCSTR lpsUserUserInfo,
DWORD dwSize
);
Parameters

hCall

A handle to the call to be answered. The application must be an owner of this call. The call state of hCall must be offering or accepted.

lpsUserUserInfo

A pointer to a string containing user-to-user information to be sent to the remote party at the time of answering the call. This pointer can be left NULL if no user-to-user information is to be sent. User-to-user information is only sent if supported by the underlying network (see LINEDEVCAPS). The protocol discriminator field for the user-to-user information, if required, should appear as the first byte of the buffer pointed to by lpsUserUserInfo, and must be accounted for in dwSize.

dwSize

The size in bytes of the user-to-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-to-user information is sent to the calling party and dwSize is ignored.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG, LINEERR_NOTOWNER.

Remarks

When a new call arrives, applications with an interest in the call are sent a LINE_CALLSTATE message to provide the new call handle and to inform the application about the call's state and the privileges to the new call (such as monitor or owner). The application with owner privilege for the call can answer this call using lineAnswer. After the call has been successfully answered, the call typically transitions to the connected state. Initially, only one application is given owner privilege to the inbound call.

In some telephony environments (like ISDN), where user alerting is separate from call offering, the application may have the option to accept a call prior to answering or to reject or redirect the offering call.

If a call comes in (is offered) at the time another call is already active, the new call is connected to by invoking lineAnswer. The effect this has on the existing active call depends on the line's device capabilities. The first call may be unaffected, it may automatically be dropped, or it may automatically be placed on hold. The appropriate LINE_CALLSTATE messages report state transitions to the application about both calls.

In a bridged situation, if a call is connected but in the LINECONNECTEDMODE_INACTIVE state, it may be joined using the lineAnswer function.

The application has the option to send user-to-user information at the time of the answer. Even if user-to-user information can be sent, there is no guarantee that the network will deliver this information to the calling party. An application should consult a line's device capabilities to determine whether sending user-to-user information upon answering the call is available.

See Also

LINE_CALLSTATE, LINE_REPLY, LINEDEVCAPS


lineBlindTransfer

The lineBlindTransfer function performs a blind or single-step transfer of the specified call to the specified destination address.

LONG lineBlindTransfer(

HCALL hCall,
LPCSTR lpszDestAddress,
DWORD dwCountryCode
);
Parameters

hCall

A handle to the call to be transferred. The application must be an owner of this call. The call state of hCall must be connected.

lpszDestAddress

A pointer to a NULL-terminated string identifying where the call is to be transferred to. The destination address uses the standard dialable number format.

dwCountryCode

The country code of the destination. This is used by the implementation to select the call progress protocols for the destination address. If a value of zero is specified, a default call-progress protocol defined by the service provider is used.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_INVALCOUNTRYCODE, LINEERR_INVALCALLSTATE, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL, LINEERR_NOTOWNER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALADDRESS, LINEERR_UNINITIALIZED, LINEERR_ADDRESSBLOCKED, LINEERR_OPERATIONFAILED.

Remarks

If LINEERR_INVALADDRESS is returned, no dialing has occurred.

Blind transfer differs from a consultation transfer in that no consultation call is made visible to the application. After the blind transfer successfully completes, the specified call is typically cleared from the application's line, and it transitions to the idle state. Note that the application's call handle remains valid after the transfer has completed. The application must deallocate its handle when it is no longer interested in the transferred call. It uses lineDeallocateCall for this purpose.

See Also

LINE_REPLY, lineDeallocateCall


lineClose

The lineClose function closes the specified open line device.

LONG lineClose(

HLINE hLine
);
Parameters

hLine

A handle to the open line device to be closed. After the line has been successfully closed, this handle is no longer valid.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL.

Remarks

If an application calls lineClose while it still has active calls on the opened line, the application's ownership of these calls is revoked. If the application was the sole owner of these calls, the calls are dropped as well. It is good programming practice for an application to dispose of the calls it owns on an opened line by explicitly relinquishing ownership and/or by dropping these calls prior to closing the line.

If the close was successful, a LINE_LINEDEVSTATE message is sent to all applications that are monitoring the line status of open/close changes. Outstanding asynchronous replies are suppressed.

Service providers may find it useful or necessary to forcibly reclaim line devices from an application that has the line open. This may be useful to prevent a misbehaved application from monopolizing the line device for too long. If this happens, a LINE_CLOSE message is sent to the application, specifying the line handle of the line device that was closed.

The lineOpen function allocates resources to the invoking application, and applications may be prevented from opening a line if resources are unavailable. Therefore, an application that only occasionally uses a line device (such as for making outbound calls) should close the line to free resources and allow other applications to open the line.

See Also

LINE_CLOSE, LINE_LINEDEVSTATE, lineOpen


lineCompleteCall

The lineCompleteCall function specifies how a call that could not be connected normally should be completed instead. The network or switch may not be able to complete a call because network resources are busy or the remote station is busy or doesn't answer. The application can request that the call be completed in one of a number of ways.

LONG lineCompleteCall(

HCALL hCall,
LPDWORD lpdwCompletionID,
DWORD dwCompletionMode,
DWORD dwMessageID
);
Parameters

hCall

A handle to the call whose completion is requested. The application must be an owner of the call. The call state of hCall must be busy, ringback.

lpdwCompletionID

A pointer to a DWORD-sized memory location. The completion ID is used to identify individual completion requests in progress. A completion ID becomes invalid and may be reused after the request completes or after an outstanding request is canceled.

dwCompletionMode

The way in which the call is to be completed. Note that dwCompletionMode is allowed to have only a single flag set. This parameter uses the following LINECALLCOMPLMODE_ constants:

LINECALLCOMPLMODE_CAMPON

Queues the call until the call can be completed. The call remains in the busy state while queued.

LINECALLCOMPLMODE_CALLBACK

Requests the called station to return the call when it returns to idle.

LINECALLCOMPLMODE_INTRUDE

Adds the application to the existing physical call at the called station (barge in).

LINECALLCOMPLMODE_MESSAGE

Leave a short predefined message for the called station ("Leave Word Calling"). The message to be sent is specified by dwMessageID.

dwMessageID

The message that is to be sent when completing the call using LINECALLCOMPLMODE_MESSAGE. This ID selects the message from a small number of predefined messages.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_COMPLETIONOVERRUN, LINEERR_NOMEM, LINEERR_INVALCALLCOMPLMODE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMESSAGEID, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.

Remarks

This function is considered complete when the request has been accepted by the network or switch; not when the request is fully completed in the way specified. After this function completes, the call typically transitions to idle. When the called station or network enters a state where the call can be completed as requested, the application will be notified by a LINE_CALLSTATE message with the call state equal to offering. The call's LINECALLINFO record lists the reason for the call as CALLCOMPLETION and provide the completion ID as well. It is possible to have multiple call completion requests outstanding at any given time; the maximum number is device dependent. The completion ID is also used to refer to each individual request so requests can be canceled by calling lineUncompleteCall.

See Also

LINE_CALLSTATE, LINE_REPLY, LINECALLINFO, lineUncompleteCall


lineCompleteTransfer

The lineCompleteTransfer function completes the transfer of the specified call to the party connected in the consultation call.

LONG lineCompleteTransfer(

HCALL hCall,
HCALL hConsultCall,
LPHCALL lphConfCall,
DWORD dwTransferMode
);
Parameters

hCall

A handle to the call to be transferred. The application must be an owner of this call. The call state of hCall must be onHold, onHoldPendingTransfer.

hConsultCall

A handle to the call that represents a connection with the destination of the transfer. The application must be an owner of this call. The call state of hConsultCall must be connected, ringback, busy, or proceeding.

lphConfCall

A pointer to a memory location where an HCALL handle can be returned. If dwTransferMode is LINETRANSFERMODE_CONFERENCE, the newly created conference call is returned in lphConfCall and the application becomes the sole owner of the conference call. Otherwise, this parameter is ignored by TAPI.

dwTransferMode

Specifies how the initiated transfer request is to be resolved. This parameter uses the following LINETRANSFERMODE_ constants:

LINETRANSFERMODE_TRANSFER

Resolve the initiated transfer by transferring the initial call to the consultation call.

LINETRANSFERMODE_CONFERENCE

Resolve the initiated transfer by conferencing all three parties into a three-way conference call. A conference call is created and returned to the application.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCONSULTCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALTRANSFERMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

The LINE_REPLY message sent in response to a call to the lineCompleteTransfer function is based on the status of the call specified by the hCall parameter.

This operation completes the transfer of the original call, hCall, to the party currently connected by hConsultCall. The consultation call will typically have been dialed on the consultation call allocated as part of lineSetupTransfer, but it may be any call to which the switch is capable of transferring hCall.

The transfer request can be resolved either as a transfer or as a three-way conference call. When resolved as a transfer, the parties connected by hCall and hConsultCall are connected to each other, and both hCall and hConsultCall are typically cleared from the application's line and transition to the idle state. Note that the application's call handle remains valid after the transfer has completed. The application must deallocate its handle with lineDeallocateCall when it is no longer interested in the transferred call.

When resolved as a conference, all three parties enter into a conference call. Both existing call handles remain valid but will transition to the conferenced state. A conference call handle will be created and returned, and it will transition to the connected state.

If lineGetConfRelatedCalls is called immediately after lineCompleteTransfer with the result that the calls are conferenced, lineGetConfRelatedCalls may not return a complete list of related calls. This is because TAPI waits to receive a LINE_CALLSTATE message indicating that the call has entered LINECALLSTATE_CONFERENCED before it considers the call to actually be part of the conference. That is, it waits for the service provider to confirm the conferenced state. Once the application has received the LINE_CALLSTATE message, lineGetConfRelatedCalls returns complete information.

It may also be possible to perform a blind transfer of a call using lineBlindTransfer.

See Also

LINE_CALLSTATE, LINE_REPLY, lineBlindTransfer, lineDeallocateCall, lineGetConfRelatedCalls, lineSetupTransfer


lineConfigDialog

The lineConfigDialog function causes the provider of the specified line device to display a dialog (attached to hwndOwner of the application) to allow the user to configure parameters related to the line device.

LONG lineConfigDialog(

DWORD dwDeviceID,
HWND hwndOwner,
LPCSTR lpszDeviceClass
);
Parameters

dwDeviceID

The line device to be configured.

hwndOwner

A handle to a window to which the dialog is to be attached. Can be NULL to indicate that any window created during the function should have no owner window.

lpszDeviceClass

A pointer to a NULL-terminated string that identifies a device class name. This device class allows the application to select a specific subscreen of configuration information applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest level configuration is selected.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONFAILED, LINEERR_INVALDEVICECLASS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_UNINITIALIZED, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_NODEVICE.

Remarks

The lineConfigDialog function causes the service provider to display a modal dialog (attached to hwndOwner of the application) to allow the user to configure parameters related to the line specified by dwDeviceID. The lpszDeviceClass parameter allows the application to select a specific subscreen of configuration information applicable to the device class in which the user is interested; the permitted strings are the same as for lineGetID. For example, if the line supports the Comm API, passing "COMM" as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, start at the corresponding point in a multilevel configuration dialog chain, so the user doesn't have to "dig" to find the parameters of interest).

The lpszDeviceClass parameter would be "tapi/line" , "", or NULL to cause the provider to display the highest level configuration for the line.

See Also

lineGetID


lineConfigDialogEdit

The lineConfigDialogEdit function causes the provider of the specified line device to display a dialog (attached to hwndOwner of the application) to allow the user to configure parameters related to the line device.

LONG lineConfigDialogEdit(

DWORD dwDeviceID,
HWND hwndOwner,
LPCSTR lpszDeviceClass,
LPVOID const lpDeviceConfigIn,
DWORD dwSize,
LPVARSTRING lpDeviceConfigOut
);
Parameters

dwDeviceID

The line device to be configured.

hwndOwner

A handle to a window to which the dialog is to be attached. Can be NULL to indicate that any window created during the function should have no owner window.

lpszDeviceClass

A pointer to a NULL-terminated string that identifies a device class name. This device class allows the application to select a specific subscreen of configuration information applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest level configuration is selected.

lpDeviceConfigIn

A pointer to the opaque configuration data structure that was returned by lineGetDevConfig (or a previous invocation of lineConfigDialogEdit) in the variable portion of the VARSTRING structure.

dwSize

The number of bytes in the structure pointed to by lpDeviceConfigIn. This value will have been returned in the dwStringSize field in the VARSTRING structure returned by lineGetDevConfig or a previous invocation of lineConfigDialogEdit.

lpDeviceConfigOut

A pointer to the memory location of type VARSTRING where the device configuration structure is returned. Upon successful completion of the request, this location is filled with the device configuration. The dwStringFormat field in the VARSTRING structure will be set to STRINGFORMAT_BINARY. Prior to calling lineGetDevConfig (or a future invocation of lineConfigDialogEdit), the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_OPERATIONFAILED, LINEERR_INVALDEVICECLASS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM, LINEERR_NODEVICE.

Remarks

If LINEERR_STRUCTURETOOSMALL is returned, the dwTotalSize field of the VARSTRING structure pointed to by lpDeviceConfigOut does not specify enough memory to contain the entire configuration structure. The dwNeededSize field has been set to the amount required. To the extent that user entries were reflected in information that could not be returned due to insufficient space, those edits are lost; applications should therefore allocate the maximum amount of space that may be needed by the device class to return its configuration structure (for more information, see documentation for the device class).

The lineConfigDialogEdit function causes the service provider to display a modal dialog (attached to hwndOwner of the application) to allow the user to configure parameters related to the line specified by dwDeviceID.

The lpszDeviceClass parameter allows the application to select a specific subscreen of configuration information applicable to the device class in which the user is interested; the permitted strings are the same as for lineGetID. For example, if the line supports the Comm API, passing "COMM" as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, start at the corresponding point in a multilevel configuration dialog chain, so the user doesn't have to "dig" to find the parameters of interest).

The lpszDeviceClass parameter would be "tapi/line" , "", or NULL to cause the provider to display the highest level configuration for the line.

The difference between this function and lineConfigDialog is the source of the parameters to edit and the result of the editing. In lineConfigDialog, the parameters edited are those currently in use on the device (or set for use on the next call), and any changes made have (to the maximum extent possible) an immediate impact on any active connection; also, the application must use lineGetDevConfig to fetch the result of parameter changes from lineConfigDialog. With lineConfigDialogEdit, the parameters to edit are passed in from the application, and the results are returned to the application, with no impact on active connections; the results of the editing are returned with this function, and the application does not need to call lineGetDevConfig. Thus, lineConfigDialogEdit permits an application to provide the ability for the user to set up parameters for future calls without having an impact on any active call. Note, however, the output of this function can be passed to lineSetDevConfig to affect the current call or next call.

Although this is a new function which older applications would not be expected to call, for backward compatibility, they should not be prevented from doing so; the function will work the same way for all applications.

See Also

lineConfigDialog, lineGetDevConfig, lineGetID, lineSetDevConfig, VARSTRING


lineConfigProvider

The lineConfigProvider function causes a service provider to display its configuration dialog.

LONG lineConfigProvider(

HWND hwndOwner,
DWORD dwPermanentProviderID
);
Parameters

hwndOwner

A handle to a window to which the configuration dialog (displayed by TSPI_providerConfig) will be attached. Can be NULL to indicate that any window created during the function should have no owner window.

dwPermanentProviderID

The permanent provider ID of the service provider to be configured.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED.

Remarks

This is basically a straight pass-through to TSPI_providerConfig.

Although this is a new function that older applications would not be expected to call, for backward compatibility, they should not be prevented from doing so; the function will work the same way for all applications.


lineDeallocateCall

The lineDeallocateCall function deallocates the specified call handle.

LONG lineDeallocateCall(

HCALL hCall
);
Parameters

hCall

The call handle to be deallocated. An application with monitoring privileges for a call can always deallocate its handle for that call. An application with owner privilege for a call can deallocate its handle except when the application is the sole owner of the call and the call is not in the idle state. The call handle is no longer valid after it has been deallocated.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

The deallocation does not affect the call state of the physical call. It does, however, release internal resources related to the call.

In API versions less than 0x00020000, if the application is the sole owner of a call and the call is not in the idle state, LINEERR_INVALCALLSTATE is returned. In this case, the application can first drop the call using lineDrop and deallocate its call handle afterwards. An application that has monitor privilege for a call can always deallocate its handle for the call.

In API versions 0x0002000 and greater, the sole owner of the call can deallocate its handle even though the call is not in the idle state. (This allows for distributed control of the call in a client/server environment.) Be aware that leaving the call without an owner may result in the user being unable to terminate the call if there are monitoring applications open preventing TAPI from calling TSPI_lineCloseCall. Use this feature only if the application can determine that the call can be controlled externally by the user (see LINEADDRCAPFLAGS_CLOSEDROP).

In API versions less than 0x00020000, when the lineDeallocateCall function deallocates a call handle, it also suspends further processing of any outstanding LINE_REPLY messages for the call. An application must be designed not to wait indefinitely for LINE_REPLY messages for each corresponding call to an asynchronous function if it also uses the lineDeallocateCall function to deallocate handles.

In API versions 0x0002000 and greater, lineDeallocateCall does not suspend outstanding LINE_REPLY messages; every asynchronous function that returns a dwRequestID to the application always results in the delivery of the associated LINE_REPLY message unless the application calls lineShutdown.

See Also

LINE_REPLY, lineDrop, lineShutdown


lineDevSpecific

The lineDevSpecific function enables service providers to provide access to features not offered by other TAPI functions. The meaning of the extensions are device specific, and taking advantage of these extensions requires the application to be fully aware of them.

LONG lineDevSpecific(

HLINE hLine,
DWORD dwAddressID,
HCALL hCall,
LPVOID lpParams,
DWORD dwSize
);
Parameters

hLine

A handle to a line device. This parameter is required.

dwAddressID

An address ID on the given line device.

hCall

A handle to a call. This parameter is optional, but if it is specified, the call it represents must belong to the hLine line device. The call state of hCall is device specific.

lpParams

A pointer to a memory area used to hold a parameter block. The format of this parameter block is device specific and its contents are passed by TAPI to or from the service provider.

dwSize

The size in bytes of the parameter block area.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful, or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Additional return values are device specific.

Remarks

This operation is part of the Extended Telephony services. It provides access to a device-specific feature without defining its meaning. This operation is only available if the application has successfully negotiated a device-specific extension version.

This function provides a generic parameter profile. The interpretation of the parameter structure is device specific. Whether dwAddressID and/or hCall are expected to be valid is device-specific. If specified, they must belong to hLine. Indications and replies sent back the application that are device specific should use the LINE_DEVSPECIFIC message.

A service provider can provide access to device-specific functions by defining parameters for use with this function. Applications that want to make use of these device-specific extensions should consult the device-specific (in this case, vendor-specific) documentation that describes what extensions are defined. An application that relies on these device-specific extensions will typically not be able to work with other service provider environments.

See Also

LINE_DEVSPECIFIC, LINE_REPLY


lineDevSpecificFeature

The lineDevSpecificFeature function enables service providers to provide access to features not offered by other TAPI functions. The meaning of these extensions are device specific, and taking advantage of these extensions requires the application to be fully aware of them.

LONG lineDevSpecificFeature(

HLINE hLine,
DWORD dwFeature,
LPVOID lpParams,
DWORD dwSize
);
Parameters

hLine

A handle to the line device.

dwFeature

The feature to invoke on the line device. This parameter uses the PHONEBUTTONFUNCTION_ constants.

lpParams

A pointer to a memory area used to hold a feature-dependent parameter block. The format of this parameter block is device specific and its contents are passed through by TAPI to or from the service provider.

dwSize

The size of the buffer in bytes.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALFEATURE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Additional return values are device specific.

Remarks

This operation is part of the Extended Telephony services. It provides access to a device-specific feature without defining its meaning. This operation is only available if the application has successfully negotiated a device-specific extension version.

This function provides the application with phone feature-button emulation capabilities. When an application invokes this operation, it specifies the equivalent of a button-press event. This method of invoking features is device dependent, as TAPI does not define their meaning. Note that an application that relies on these device-specific extensions will typically not work with other service provider environments.

Note also that the structure pointed to by lpParams should not contain any pointers because they would not be properly translated (thunked) when running a 16-bit application in a 32-bit version of TAPI and vice versa.

See Also

LINE_REPLY


lineDial

The lineDial function dials the specified dialable number on the specified call.

LONG lineDial(

HCALL hCall,
LPCSTR lpszDestAddress,
DWORD dwCountryCode
);
Parameters

hCall

A handle to the call on which a number is to be dialed. The application must be an owner of the call. The call state of hCall can be any state except idle and disconnected.

lpszDestAddress

The destination to be dialed using the standard dialable number format.

dwCountryCode

The country code of the destination. This is used by the implementation to select the call progress protocols for the destination address. If a value of zero is specified, a service provider-defined default call progress protocol is used.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_ADDRESSBLOCKED, LINEERR_INVALPOINTER, LINEERR_DIALBILLING, LINEERR_NOMEM, LINEERR_DIALDIALTONE, LINEERR_NOTOWNER, LINEERR_DIALPROMPT, LINEERR_OPERATIONFAILED, LINEERR_DIALQUIET, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_UNINITIALIZED, LINEERR_INVALCOUNTRYCODE.

Remarks

If LINEERR_INVALADDRESS is returned, no dialing has been done. If LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT is returned, none of the actions otherwise performed by lineDial have occurred. For example, none of the dialable addresses prior to the offending character has been dialed, no hookswitch state has changed, and so on.

The lineDial function is used for dialing on an existing call appearance. For example, after a call has been set up for transfer or conference, a consultation call is automatically allocated, and the lineDial function would be used to perform the dialing of this consultation call. Note that lineDial may be invoked multiple times in the course of multistage dialing, if the line's device capabilities allow it. Also, multiple addresses may be provided in a single dial string separated by CRLF. Service providers that provide inverse multiplexing can establish individual physical calls with each of the addresses and can return a single call handle to the aggregate of all calls to the application. All addresses would use the same country code.

Dialing is considered complete after the address has been passed to the service provider; not after the call is finally connected. Service providers that provide inverse multiplexing may allow multiple addresses to be provided at once. The service provider sends LINE_CALLSTATE messages to the application to inform it about the progress of the call. To abort a call attempt while a call is being established, the invoking application should use lineDrop.

An application can set the lpszDestAddress parameter of the lineDial function to the address of an empty string to indicate that dialing is complete, but only if the previous calls to the lineMakeCall and lineDial functions have had the strings specified by lpszDestAddress terminated with semicolons.

See Also

LINE_CALLSTATE, LINE_REPLY, lineDrop, lineMakeCall


lineDrop

The lineDrop function drops or disconnects the specified call. The application has the option to specify user-to-user information to be transmitted as part of the call disconnect.

LONG lineDrop(

HCALL hCall,
LPCSTR lpsUserUserInfo,
DWORD dwSize
);
Parameters

hCall

A handle to the call to be dropped. The application must be an owner of the call. The call state of hCall can be any state except idle.

lpsUserUserInfo

A pointer to a string containing user-to-user information to be sent to the remote party as part of the call disconnect. This pointer can be left NULL if no user-to-user information is to be sent. User-to-user information is only sent if supported by the underlying network (see LINEDEVCAPS). The protocol discriminator field for the user-to-user information, if required, should appear as the first byte of the buffer pointed to by lpsUserUserInfo, and must be accounted for in dwSize.

dwSize

The size in bytes of the user-to-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-to-user information is sent to the calling party and dwSize is ignored.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_NOTOWNER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_USERUSERINFOTOOBIG, LINEERR_INVALCALLSTATE, LINEERR_UNINITIALIZED.

Remarks

When invoking lineDrop, related calls may sometimes be affected as well. For example, dropping a conference call may drop all individual participating calls. LINE_CALLSTATE messages are sent to the application for all calls whose call state is affected. A dropped call typically transitions to the idle state. Invoking lineDrop on a call in the offering state rejects the call. Not all telephone networks provide this capability.

A call in the onholdpending state will typically revert to the connected state. When dropping the consultation call to the third party for a conference call or when removing the third party in a previously established conference call, the provider (and switch) may release the conference bridge and revert the call back to a normal two-party call. If this is the case, hConfCall transitions to the idle state, and the only remaining participating call will transition to the connected state. Some switches automatically "unhold" the other call.

The application has the option to send user-to-user information at the time of the drop. Even if user-to-user information can be sent, there is no guarantee that the network will deliver this information to the remote party.

Note that in various bridged or party-line configurations when multiple parties are on the call, lineDrop may not actually clear the call. For example, in a bridged situation, a lineDrop operation may possibly not actually drop the call because the status of other stations on the call may govern; instead, the call may simply be changed to the LINECONNECTEDMODE_INACTIVE mode if it remains connected at other stations.

See Also

LINE_CALLSTATE, LINE_REPLY, LINEDEVCAPS


lineForward

The lineForward function forwards calls destined for the specified address on the specified line, according to the specified forwarding instructions. When an originating address (dwAddressID) is forwarded, the specified incoming calls for that address are deflected to the other number by the switch. This function provides a combination of forward and do-not-disturb features. This function can also cancel forwarding currently in effect.

LONG lineForward(

HLINE hLine,
DWORD bAllAddresses,
DWORD dwAddressID,
LPLINEFORWARDLIST const lpForwardList,
DWORD dwNumRingsNoAnswer,
LPHCALL lphConsultCall,
LPLINECALLPARAMS const lpCallParams
);
Parameters

hLine

A handle to the line device.

bAllAddresses

Specifies whether all originating addresses on the line or just the one specified is to be forwarded. If TRUE, all addresses on the line are forwarded and dwAddressID is ignored; if FALSE, only the address specified as dwAddressID is forwarded.

dwAddressID

The address on the specified line whose incoming calls are to be forwarded. This parameter is ignored if bAllAddresses is TRUE.

lpForwardList

A pointer to a variably sized data structure that describes the specific forwarding instructions, of type LINEFORWARDLIST.

dwNumRingsNoAnswer

The number of rings before a call is considered a "no answer." If dwNumRingsNoAnswer is out of range, the actual value is set to the nearest value in the allowable range.

lphConsultCall

A pointer to an HCALL location. In some telephony environments, this location is loaded with a handle to a consultation call that is used to consult the party that is being forwarded to, and the application becomes the initial sole owner of this call. This pointer must be valid even in environments where call forwarding does not require a consultation call. This handle will be set to NULL if no consultation call is created.

lpCallParams

A pointer to a structure of type LINECALLPARAMS. This pointer is ignored unless lineForward requires the establishment of a call to the forwarding destination (and lphConsultCall is returned, in which case lpCallParams is optional). If NULL, default call parameters are used. Otherwise, the specified call parameters are used for establishing hConsultCall.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPARAM, LINEERR_UNINITIALIZED.

Remarks

A successful forwarding indicates only that the request has been accepted by the service provider, not that forwarding is set up at the switch. A LINE_ADDRESSSTATE (forwarding) message provides confirmation for forwarding having been set up at the switch.

Forwarding of the address(es) remains in effect until this function is called again. The most recent forwarding list replaces the old one. Forwarding can be canceled by specifying a NULL pointer as lpForwardList. If a NULL destination address is specified for an entry in the forwarding list, the operation acts as a do-not-disturb.

Forwarding status of an address may also be affected externally; for example, by administrative actions at the switch or by a user from another station. It may not be possible for the service provider to be aware of this state change, and it may not be able to keep in synchronization with the forwarding state known to the switch.

Because a service provider may not know the forwarding state of the address "for sure" (that is, it may have been forwarded or unforwarded in an unknown way), lineForward will succeed unless it fails to set the new forwarding instructions. In other words, a request that all forwarding be canceled at a time that there is no forwarding in effect will be successful. This is because there is no "unforwarding"—you can only change the previous set of forwarding instructions.

The success or failure of this operation does not depend on the previous set of forwarding instructions, and the same is true when setting different forwarding instructions. The provider should "unforward everything" prior to setting the new forwarding instructions. Because this may take time in analog telephony environments, a provider may also want to compare the current forwarding with the new one, and only issue instructions to the switch to get to the final state (leaving unchanged forwarding unaffected).

Invoking lineForward when LINEFORWARDLIST has dwNumEntries set to zero has the same effect as providing a NULL lpForwardList parameter. It cancels all forwarding currently in effect.

See Also

LINE_ADDRESSSTATE, LINE_REPLY, LINECALLPARAMS, LINEFORWARDLIST


lineGatherDigits

The lineGatherDigits function initiates the buffered gathering of digits on the specified call. The application specifies a buffer in which to place the digits and the maximum number of digits to be collected.

LONG lineGatherDigits(

HCALL hCall,
DWORD dwDigitModes,
LPSTR lpsDigits,
DWORD dwNumDigits,
LPCSTR lpszTerminationDigits,
DWORD dwFirstDigitTimeout,
DWORD dwInterDigitTimeout
);
Parameters

hCall

A handle to the call on which digits are to be gathered. The application must be an owner of the call. The call state of hCall can be any state.

dwDigitModes

The digit mode(s) to be monitored. Note that dwDigitModes is allowed to have one or more flags set. This parameter uses the following LINEDIGITMODE_ constants:

LINEDIGITMODE_PULSE

Detect digits as audible clicks that are the result of the use of rotary pulse sequences. Valid digits for pulse mode are '0' through '9'.

LINEDIGITMODE_DTMF

Detect digits as DTMF tones. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.

lpsDigits

A pointer to the buffer where detected digits are to be stored as ASCII characters. Digits may not show up in the buffer one at a time as they are collected. Only after a LINE_GATHERDIGITS message is received should the content of the buffer be assumed to be valid. If lpsDigits is NULL, the digit gathering currently in progress on the call is terminated and dwNumDigits is ignored. Otherwise, lpsDigits is assumed to have room for dwNumDigits digits.

dwNumDigits

The number of digits to be collected before a LINE_GATHERDIGITS message is sent to the application. The dwNumDigits parameter is ignored when lpsDigits is NULL. This function fails if dwNumDigits is zero.

lpszTerminationDigits

Specifies a NULL-terminated string of termination digits as ASCII characters. If one of the digits in the string is detected, that termination digit is appended to the buffer, digit collection is terminated, and the LINE_GATHERDIGITS message is sent to the application.

Valid characters for pulse mode are '0' through '9'. Valid characters for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'. If this pointer is NULL, or if it points to an empty string, the function behaves as though no termination digits were supplied.

dwFirstDigitTimeout

The time duration in milliseconds in which the first digit is expected. If the first digit is not received in this timeframe, digit collection is aborted and a LINE_GATHERDIGITS message is sent to the application. The buffer only contains the NULL character, indicating that no digits were received and the first digit timeout terminated digit gathering. The call's line-device capabilities specify the valid range for this parameter or indicate that timeouts are not supported.

dwInterDigitTimeout

The maximum time duration in milliseconds between consecutive digits. If no digit is received in this timeframe, digit collection is aborted and a LINE_GATHERDIGITS message is sent to the application. The buffer only contains the digits collected up to this point followed by a NULL character, indicating that an interdigit timeout terminated digit gathering. The call's line-device capabilities specify the valid range for this parameter or indicate that timeouts are not supported.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_NOTOWNER, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_INVALTIMEOUT.

Remarks

Digit collection is terminated when the requested number of digits has been collected. It is also terminated when one of the digits detected matches a digit in szTerminationDigits before the specified number of digits has been collected. The detected termination digit is also placed in the buffer and the partial buffer is returned.

Another way of cancelling digit collection is when one of the timeouts expires. The dwFirstDigitTimeout expires if the first digit is not received in this time period. The dwInterDigitTimout expires if the second, third, (and so forth) digit is not received within that time period from the previously detected digit, and a partial buffer is returned.

A fourth method for terminating digit detection is by calling this function again while collection is in progress. The old collection session is terminated, any digits collected up to that point are copied to the buffer supplied from the previous call to this function, and the buffer is delivered when the LINE_GATHERDIGITS message is sent to the application. The mechanism for terminating digit gathering without initiating another gathering of the digits is by invoking this function with lpsDigits equal to NULL.

This function is considered successful if digit collection has been correctly initiated, not when digit collection has terminated. In all cases where a partial buffer is returned, valid digits (if any) are followed by an ASCII NULL character.

Although this function can be invoked in any call state, digits can typically only be gathered while the call is in the connected state.

The message LINE_GATHERDIGITS is sent only to the application that initiated the request. It is also sent when partial buffers are returned because of timeouts or matching termination digits, or when the request is canceled by another lineGatherDigits request on the call. Only one gather—digits request can be active on a call at any given time across all applications that are owners of the call. Given the asynchronous behavior of the operation, an application that issues multiple lineGatherDigits in quick succession may be able to do so and receive several LINE_GATHERDIGITS messages later. While this would be unusual application behavior, the application will be able to count the number of these messages to allow cancel messages to be matched with the earlier requests. In any case, only the most recent request should be assumed to be valid.

An application can use lineMonitorDigits to enable or disable unbuffered digit detection. Each time a digit is detected in this fashion, a LINE_MONITORDIGITS message is sent to the application. Both buffered and unbuffered digit detection can be enabled for the same call simultaneously.

Gathering of digits on a conference call applies only to the hConfCall, not to the individual participating calls.

If the lineGatherDigits function is used to cancel a previous request to gather digits, the function copies any digits collected up to that point to the buffer specified in the original function call and sends a LINE_GATHERDIGITS message to the application, regardless of whether the lpszDigits parameter in the second call specifies a NULL or different address.

See Also

LINE_GATHERDIGITS, LINE_MONITORDIGITS, lineMonitorDigits


lineGenerateDigits

The lineGenerateDigits function initiates the generation of the specified digits on the specified call as inband tones using the specified signaling mode. Invoking this function with a NULL value for lpszDigits aborts any digit generation currently in progress. Invoking lineGenerateDigits or lineGenerateTone while digit generation is in progress aborts the current digit generation or tone generation and initiates the generation of the most recently specified digits or tone.

LONG lineGenerateDigits(

HCALL hCall,
DWORD dwDigitMode,
LPCSTR lpszDigits,
DWORD dwDuration
);
Parameters

hCall

A handle to the call. The application must be an owner of the call. Call state of hCall can be any state.

dwDigitMode

The format to be used for signaling these digits. Note that dwDigitMode is allowed to have only a single flag set. This parameter uses the following LINEDIGITMODE_ constants:

LINEDIGITMODE_PULSE

Uses pulse/rotary for digit signaling. Valid digits for pulse mode are '0' through '9'.

LINEDIGITMODE_DTMF

Uses DTMF tones for digit signaling. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.

lpszDigits

A pointer to a NULL-terminated character buffer that contains the digits to be generated. Valid characters for pulse mode are '0' through '9' and ',' (comma). Valid characters for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#', and ',' (comma). A comma injects an extra delay between the signaling of the previous and next digits it separates. The duration of this pause is configuration defined, and the line's device capabilities indicate what this duration is. Multiple commas may be used to inject longer pauses. Invalid digits are ignored during the generation, rather than being reported as an error. The exclamation character (!) is a valid character in the string specifed by the lpszDigits parameter for both DTMF and pulse mode. This character causes a "hookflash" operation, as described for dialable addresses.

dwDuration

Both the duration in milliseconds of DTMF digits and pulse and DTMF inter-digit spacing. A value of zero will use a default value. The dwDuration parameter must be within the range specified by MinDialParams and MaxDialParams in LINEDEVCAPS. If out of range, the actual value is set to the nearest value in the range.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

The lineGenerateDigits function is considered to have completed successfully when the digit generation has been successfully initiated, not when all digits have been generated. In contrast to lineDial, which dials digits in a network-dependent fashion, lineGenerateDigits guarantees to produce the digits as inband tones over the voice channel using DTMF or hookswitch dial pulses when using pulse. The lineGenerateDigits function is generally not suitable for making calls or dialing. It is intended for end-to-end signaling over an established call.

After all digits in lpszDigits have been generated, or after digit generation has been aborted or canceled, a LINE_GENERATE message is sent to the application.

Only one inband generation request (tone generation or digit generation) is allowed to be in progress per call across all applications that are owners of the call. Digit generation on a call is canceled by initiating either another digit generation request or a tone generation request. To cancel the current digit generation, the application can invoke lineGenerateDigits and specify NULL for the lpszDigits parameter.

Depending on the service provider and hardware, the application may monitor the digits it generates itself. If that is not desired, the application can disable digit monitoring while generating digits.

See Also

LINE_GENERATE, LINEDEVCAPS, lineDial, lineGenerateTone


lineGenerateTone

The lineGenerateTone function generates the specified inband tone over the specified call. Invoking this function with a zero for dwToneMode aborts the tone generation currently in progress on the specified call. Invoking lineGenerateTone or lineGenerateDigits while tone generation is in progress aborts the current tone generation or digit generation and initiates the generation of the newly specified tone or digits.

LONG lineGenerateTone(

HCALL hCall,
DWORD dwToneMode,
DWORD dwDuration,
DWORD dwNumTones,
LPLINEGENERATETONE const lpTones
);
Parameters

hCall

A handle to the call on which a tone is to be generated. The application must be an owner of the call. The call state of hCall can be any state.

dwToneMode

Defines the tone to be generated. Tones can be either standard or custom. A custom tone is composed of a set of arbitrary frequencies. A small number of standard tones are predefined. The duration of the tone is specified with dwDuration for both standard and custom tones. Note that dwToneMode can only have one bit set. If no bits are set (the value 0 is passed), tone generation is canceled. This parameter uses the following LINETONEMODE_ constants:

LINETONEMODE_CUSTOM

The tone is a custom tone, defined by the specified frequencies.

LINETONEMODE_RINGBACK

The tone to be generated is ring tone. The exact ringback tone is service provider defined.

LINETONEMODE_BUSY

The tone is a standard (station) busy tone. The exact busy tone is service provider defined.

LINETONEMODE_BEEP

The tone is a beep, as used to announce the beginning of a recording. The exact beep tone is service provider defined.

LINETONEMODE_BILLING

The tone is billing information tone such as a credit card prompt tone. The exact billing tone is service provider defined.

A value of zero for dwToneMode cancels tone generation.

dwDuration

Duration in milliseconds during which the tone should be sustained. A value of zero for dwDuration uses a default duration for the specified tone. Default values are:

CUSTOM: infinite

RINGBACK: infinite

BUSY: infinite

BEEP: infinite

BILLING: fixed (single cycle)

dwNumTones

The number of entries in the lpTones array. This field is ignored if dwToneMode is not equal to CUSTOM.

lpTones

A pointer to a LINEGENERATETONE array that specifies the tone's components. This parameter is ignored for non-custom tones. If lpTones is a multi-frequency tone, the various tones are played simultaneously.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALTONEMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTONE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

The lineGenerateTone function is considered to have completed successfully when the tone generation has been successfully initiated, not when the generation of the tone is done. The function allows the inband generation of several predefined tones, such as ring back, busy tones, and beep. It also allows for the fabrication of custom tones by specifying their component frequencies, cadence, and volume. Because these tones are generated as inband tones, the call would typically have to be in the connected state for tone generation to be effective. When the generation of the tone is complete, or when tone generation is canceled, a LINE_GENERATE message is sent to the application.

Only one inband generation request (tone generation or digit generation) is allowed to be in progress per call across all applications that are owners of the call. This implies that if tone generation is currently in progress on a call, invoking lineGenerateDigits cancels the tone generation.

If the LINEERR_INVALPOINTER error value is returned, the specified lpTones parameter is invalid or the value specified by the dwNumTones parameter is too large.

See Also

LINE_GENERATE, lineGenerateDigits, LINEGENERATETONE


lineGetAddressCaps

The lineGetAddressCaps function queries the specified address on the specified line device to determine its telephony capabilities.

LONG lineGetAddressCaps(

HLINEAPP hLineApp,
DWORD dwDeviceID,
DWORD dwAddressID,
DWORD dwAPIVersion,
DWORD dwExtVersion,
LPLINEADDRESSCAPS lpAddressCaps
);
Parameters

hLineApp

The handle to the application's registration with TAPI.

dwDeviceID

The line device containing the address to be queried.

dwAddressID

The address on the given line device whose capabilities are to be queried.

dwAPIVersion

The version number of the Telephony API to be used. The high-order word contains the major version number; the low-order word contains the minor version number. This number is obtained by lineNegotiateAPIVersion.

dwExtVersion

The version number of the service provider-specific extensions to be used. This number can be left zero if no device-specific extensions are to be used. Otherwise, the high-order word contains the major version number; and the low-order word contains the minor version number.

lpAddressCaps

A pointer to a variably sized structure of type LINEADDRESSCAPS. Upon successful completion of the request, this structure is filled with address capabilities information. Prior to calling lineGetAddressCaps, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALAPPHANDLE, LINEERR_UNINITIALIZED, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_NODRIVER, LINEERR_NODEVICE.

Remarks

Valid address IDs range from zero to one less than the number of addresses returned by lineGetDevCaps. The version number to be supplied is the version number that was returned as part of the line's device capabilities by lineGetDevCaps.

See Also

LINEADDRESSCAPS, lineGetDevCaps, lineNegotiateAPIVersion


lineGetAddressID

The lineGetAddressID function returns the address ID associated with an address in a different format on the specified line.

LONG lineGetAddressID(

HLINE hLine,
LPDWORD lpdwAddressID,
DWORD dwAddressMode,
LPCSTR lpsAddress,
DWORD dwSize
);
Parameters

hLine

A handle to the open line device.

lpdwAddressID

A pointer to a DWORD-sized memory location where the address ID is returned.

dwAddressMode

The address mode of the address contained in lpsAddress. The dwAddressMode parameter is allowed to have only a single flag set. This parameter uses the following LINEADDRESSMODE_ constants:

LINEADDRESSMODE_DIALABLEADDR

The address is specified by its dialable address. The lpsAddress parameter is the dialable address or canonical address format.

lpsAddress

A pointer to a data structure holding the address assigned to the specified line device. The format of the address is determined by dwAddressMode. Because the only valid value is LINEADDRESSMODE_DIALABLEADDR, lpsAddress uses the common dialable number format and is NULL-terminated.

dwSize

The size of the address contained in lpsAddress.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALADDRESS, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

The lineGetAddressID function is used to map a phone number (address) assigned to a line device back to its dwAddressID in the range 0 to the number of addresses minus one returned in the line's device capabilities. The lineMakeCall function allows the application to make a call by specifying a line handle and an address on the line. The address can be specified as a dwAddressID, as a phone number, or as a device-specific name or identifier. Using a phone number may be practical in environments where a single line is assigned multiple addresses. Note that LINEADDRESSMODE_ADDRESSID may not be used with lineGetAddressID.

See Also

lineMakeCall


lineGetAddressStatus

The lineGetAddressStatus function allows an application to query the specified address for its current status.

LONG lineGetAddressStatus(

HLINE hLine,
DWORD dwAddressID,
LPLINEADDRESSSTATUS lpAddressStatus
);
Parameters

hLine

A handle to the open line device.

dwAddressID

An address on the given open line device. This is the address to be queried.

lpAddressStatus

A pointer to a variably sized data structure of type LINEADDRESSSTATUS. Prior to calling lineGetAddressStatus, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL, LINEERR_OPERATIONFAILED.

See Also

LINEADDRESSSTATUS


lineGetAgentActivityList

The lineGetAgentActivityList function obtains the identities of activities which the application can select using lineSetAgentActivity to indicate what function the agent is actually performing at the moment.

LONG lineGetAgentActivityList(

HLINE hLine,
DWORD dwAddressID,
LPLINEAGENTACTIVITYLIST lpAgentActivityList
);
Parameters

hLine

A handle to the open line device.

dwAddressID

The address on the open line device whose agent status is to be queried.

lpAgentAcvitityList

A pointer to a variably sized structure of type LINEAGENTACTIVITYLIST. Upon successful completion of the request, this structure is filled with a list of the agent activity codes which can be selected using lineSetAgentActivity. Prior to calling lineGetAgentActivityList, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALAGENTID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

See Also

LINEAGENTACTIVITYLIST, lineSetAgentActivity


lineGetAgentCaps

The lineGetAgentCaps function obtains the agent-related capabilities supported on the specified line device. If a specific agent is named, the capabilities will include a listing of ACD groups into which the agent is permitted to log in.

LONG lineGetAgentCaps(

HLINEAPP hLineApp,
DWORD dwDeviceID,
DWORD dwAddressID,
DWORD dwAppAPIVersion,
LPLINEAGENTCAPS lpAgentCaps
);
Parameters

hLineApp

The handle to the application's registration with TAPI.

dwDeviceID

The line device containing the address to be queried.

dwAddressID

The address on the given line device whose capabilities are to be queried.

dwAppAPIVersion

The highest API version supported by the application. This should not be the value negotiated using lineNegotiateAPIVersion on the device being queried.

lpAgentCaps

A pointer to a variably sized structure of type LINEAGENTCAPS. Upon successful completion of the request, this structure is filled with agent capabilities information. Prior to calling lineGetAgentCaps, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NODRIVER, LINEERR_UNINITIALIZED, LINEERR_NODEVICE.

See Also

LINEAGENTCAPS, lineNegotiateAPIVersion


lineGetAgentGroupList

The lineGetAgentGroupList function obtains the identities of agent groups (combination of queue, supervisor, skill level, and so on) into which the agent currently logged in on the workstation is permitted to log into on the automatic call distributor.

LONG lineGetAgentGroupList(

HLINE hLine,
DWORD dwAddressID,
LPLINEAGENTGROUPLIST lpAgentGroupList
);
Parameters

hLine

A handle to the open line device.

dwAddressID

The address on the open line device whose agent status is to be queried.

lpAgentGroupList

A pointer to a variably sized structure of type LINEAGENTGROUPLIST. Upon successful completion of the request, this structure is filled with a list of the agent groups into which the agent may log in at this time (which should include any groups into which the agent is already logged in, if any). Prior to calling lineGetAgentGroupList, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALAGENTID, LINEERR_INVALLINEHANDLE, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_UNINITIALIZED.

See Also

LINEAGENTGROUPLIST


lineGetAgentStatus

The lineGetAgentStatus function obtains the agent-related status on the specified address.

LONG lineGetAgentStatus(

HLINE hLine,
DWORD dwAddressID,
LPLINEAGENTSTATUS lpAgentStatus
);
Parameters

hLine

A handle to the open line device.

dwAddressID

The address on the open line device whose agent status is to be queried.

lpAgentStatus

A pointer to a variably sized structure of type LINEAGENTSTATUS. Upon successful completion of the request, this structure is filled with agent status information. Prior to calling lineGetAgentStatus, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALLINEHANDLE, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_UNINITIALIZED.

See Also

LINEAGENTSTATUS


lineGetAppPriority

The lineGetAppPriority function allows an application to determine whether or not it is in the handoff priority list for a particular media mode or Assisted Telephony request mode, and, if so, its position in the priority list.

LONG lineGetAppPriority(

LPCSTR lpszAppFilename,
DWORD dwMediaMode,
LPLINEEXTENSIONID const lpExtensionID,
DWORD dwRequestMode,
LPVARSTRING lpExtensionName,
LPDWORD lpdwPriority
);
Parameters

lpszAppFilename

A pointer to a string containing the application executable module filename (without directory information). In API versions 0x00020000 and greater, the parameter can be in either long or 8.3 filename format. In API versions less than 0x00020000, the parameter must specify a filename in the 8.3 format; long filenames cannot be used.

dwMediaMode

The media mode for which the priority information is to be obtained. The value may be one of the LINEMEDIAMODE_ constants; only a single bit may be on. The value 0 should be used if checking application priority for Assisted Telephony requests.

lpExtensionID

A pointer to structure of type LINEEXTENSIONID. This parameter is ignored.

dwRequestMode

If the dwMediaMode parameter is 0, this parameter specifies the Assisted Telephony request mode for which priority is to be checked. It must be either LINEREQUESTMODE_MAKECALL or LINEREQUESTMODE_MEDIACALL. This parameter is ignored if dwMediaMode is non-zero.

lpExtensionName

This parameter is ignored.

lpdwPriority

A pointer to a DWORD-size memory location into which TAPI will write the priority of the application for the specified media or request mode. The value 0 will be returned if the application is not in the stored priority list and does not currently have any line device open with ownership requested of the specified media mode or having registered for the specified request mode.

In API versions less than 0x00020000, the value −1 (0xFFFFFFFF) is returned if the application has the line open for the specified media mode or has registered for the specified requests, but the application is not in the stored priority list (that is, it is in the temporary priority list only). In API versions 0x00020000 and greater, the value 0 is returned to indicate this condition.

Otherwise, the value will indicate the application's position in the list (with 1 being highest priority, and increasing values indicating decreasing priority).

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_INVALREQUESTMODE, LINEERR_INVALAPPNAME, LINEERR_NOMEM, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL.

Remarks

If LINEERR_INVALMEDIAMODE is returned, the value specified in dwMediaMode is not 0, not a valid extended media mode, and not a LINEMEDIAMODE_ constant, or more than one bit is on in the parameter value.

Also, long filenames are now permitted for lpszAppFilename; 8.3 names are acceptable, but no longer required.

Although this is a new function which older applications would not be expected to call, for backward compatibility, they should not be prevented from doing so; the function will work the same way for all applications.

See Also

LINEEXTENSIONID, VARSTRING


lineGetCallInfo

The lineGetCallInfo function enables an application to obtain fixed information about the specified call.

LONG lineGetCallInfo(

HCALL hCall,
LPLINECALLINFO lpCallInfo
);
Parameters

hCall

A handle to the call to be queried. The call state of hCall can be any state.

lpCallInfo

A pointer to a variably sized data structure of type LINECALLINFO. Upon successful completion of the request, this structure is filled with call-related information. Prior to calling lineGetCallInfo, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL.

Remarks

A separate LINECALLINFO structure exists for every inbound or outbound call. The structure contains primarily fixed information about the call. An application would typically be interested in checking this information when it receives its handle for a call by the LINE_CALLSTATE message, or each time it receives notification by a LINE_CALLINFO message that parts of the call information structure have changed. These messages supply the handle for the call as a parameter.

See Also

LINE_CALLINFO, LINE_CALLSTATE, LINECALLINFO


lineGetCallStatus

The lineGetCallStatus function returns the current status of the specified call.

LONG lineGetCallStatus(

HCALL hCall,
LPLINECALLSTATUS lpCallStatus
);
Parameters

hCall

A handle to the call to be queried. The call state of hCall can be any state.

lpCallStatus

A pointer to a variably sized data structure of type LINECALLSTATUS. Upon successful completion of the request, this structure is filled with call status information. Prior to calling lineGetCallStatus, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL.

Remarks

The lineGetCallStatus function returns the dynamic status of a call, whereas lineGetCallInfo returns primarily static information about a call. Call status information includes the current call state, detailed mode information related to the call while in this state (if any), as well as a list of the available API functions the application can invoke on the call while the call is in this state. An application would typically be interested in requesting this information when it receives notification about a call state change by the LINE_CALLSTATE message.

See Also

LINE_CALLSTATE, LINECALLSTATUS, lineGetCallInfo


lineGetConfRelatedCalls

The lineGetConfRelatedCalls function returns a list of call handles that are part of the same conference call as the specified call. The specified call is either a conference call or a participant call in a conference call. New handles are generated for those calls for which the application does not already have handles, and the application is granted monitor privilege to those calls.

LONG lineGetConfRelatedCalls(

HCALL hCall,
LPLINECALLLIST lpCallList
);
Parameters

hCall

A handle to a call. This is either a conference call or a participant call in a conference call. For a conference parent call, the call state of hCall can be any state. For a conference participant call, it must be in the conferenced state.

lpCallList

A pointer to a variably sized data structure of type LINECALLLIST. Upon successful completion of the request, call handles to all calls in the conference call are returned in this structure. The first call in the list is the conference call, the other calls are the participant calls. The application is granted monitor privilege to those calls for which it does not already have handles; the privileges to calls in the list for which the application already has handles is unchanged. Prior to calling lineGetConfRelatedCalls, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOCONFERENCE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

The specified call can either be a conference call handle or a handle to a participant call. For example, a consultation call that has not yet been added to a conference call is not part of a conference. The first entry in the list that is returned is the conference call handle, the other handles are all the participant calls. The specified call is always one of the calls returned in the list. Calls in the list to which the application does not already have a call handle are assigned monitor privilege; privileges to calls for which the application already has handles are unchanged. The application can use lineSetCallPrivilege to change the privilege of the call.

Note that if lineGetConfRelatedCalls is called immediately after a call is added to a conference using lineCompleteTransfer, lineGetConfRelatedCalls may not return a complete list of related calls because TAPI waits to receive a LINE_CALLSTATE message indicating that the call has entered LINECALLSTATE_CONFERENCED before it considers the call to actually be part of the conference (that is, the conferenced state is confirmed by the service provider). Once the application has received the LINE_CALLSTATE message, lineGetConfRelatedCalls returns complete information.

The application can invoke lineGetCallInfo and lineGetCallStatus for each call in the list to determine the call's information and status, respectively.

See Also

LINE_CALLSTATE, lineCompleteTransfer, lineGetCallInfo, lineGetCallStatus, lineSetCallPrivilege


lineGetCountry

The lineGetCountry function fetches the stored dialing rules and other information related to a specified country, the first country in the country list, or all countries.

LONG lineGetCountry(

DWORD dwCountryID,
DWORD dwAPIVersion,
LPLINECOUNTRYLIST lpLineCountryList
);
Parameters

dwCountryID

The country ID (not the country code) of the country for which information is to be obtained. If the value 1 is specified, information on the first country in the country list is obtained. If the value 0 is specified, information on all countries is obtained (which may require a great deal of memory—20Kbytes or more).

dwAPIVersion

The highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).

lpLineCountryList

A pointer to a location to which a LINECOUNTRYLIST structure will be loaded. Prior to calling lineGetCountry, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INIFILECORRUPT, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER.

Remarks

Although this is a new function which older applications would not be expected to call, for backward compatibility, they should not be prevented from doing so. The function will work the same way for all applications.

See Also

LINECOUNTRYLIST, lineNegotiateAPIVersion


lineGetDevCaps

The lineGetDevCaps function queries a specified line device to determine its telephony capabilities. The returned information is valid for all addresses on the line device.

LONG lineGetDevCaps(

HLINEAPP hLineApp,
DWORD dwDeviceID,
DWORD dwAPIVersion,
DWORD dwExtVersion,
LPLINEDEVCAPS lpLineDevCaps
);
Parameters

hLineApp

The handle to the application's registration with TAPI.

dwDeviceID

The line device to be queried.

dwAPIVersion

The version number of the Telephony API to be used. The high-order word contains the major version number; the low-order word contains the minor version number. This number is obtained by lineNegotiateAPIVersion.

dwExtVersion

The version number of the service provider-specific extensions to be used. This number is obtained by lineNegotiateExtVersion. It can be left zero if no device-specific extensions are to be used. Otherwise, the high-order word contains the major version number; the low-order word contains the minor version number.

lpLineDevCaps

A pointer to a variably sized structure of type LINEDEVCAPS. Upon successful completion of the request, this structure is filled with line device capabilities information. Prior to calling lineGetDevCaps, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALAPPHANDLE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NODEVICE.

Remarks

Before using lineGetDevCaps, the application must negotiate the API version number to use, and, if desired, the extension version to use.

The API and extension version numbers are those under which TAPI and the service provider must operate. If version ranges do not overlap, the application, API, or service-provider versions are incompatible and an error is returned.

One of the fields in the LINEDEVCAPS structure returned by this function contains the number of addresses assigned to the specified line device. The actual address IDs used to reference individual addresses vary from zero to one less than the returned number. The capabilities of each address may be different. Use lineGetAddressCaps for each available <dwDeviceID, dwAddressID> combination to determine the exact capabilities of each address.

See Also

LINEDEVCAPS, lineGetAddressCaps, lineNegotiateAPIVersion, lineNegotiateExtVersion


lineGetDevConfig

The lineGetDevConfig function returns an "opaque" data structure object, the contents of which are specific to the line (service provider) and device class. The data structure object stores the current configuration of a media-stream device associated with the line device.

LONG lineGetDevConfig(

DWORD dwDeviceID,
LPVARSTRING lpDeviceConfig,
LPCSTR lpszDeviceClass
);
Parameters

dwDeviceID

The line device to be configured.

lpDeviceConfig

A pointer to the memory location of type VARSTRING where the device configuration structure is returned. Upon successful completion of the request, this location is filled with the device configuration. The dwStringFormat field in the VARSTRING structure will be set to STRINGFORMAT_BINARY. Prior to calling lineGetDevConfig, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

lpszDeviceClass

A pointer to a NULL-terminated ASCII string that specifies the device class of the device whose configuration is requested. Valid device class lineGetID strings are the same as those specified for the function.

Return Values

Returns zero if the function is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NODEVICE.

Remarks

Call states are device specific.

The lineGetDevConfig function can be used to retrieve a data structure from TAPI that specifies the configuration of a media stream device associated with a particular line device. For example, the contents of this structure could specify data rate, character format, modulation schemes, and error control protocol settings for a "datamodem" media device associated with the line.

Typically, an application will call lineGetID to identify the media stream device associated with a line, and then call lineConfigDialog to allow the user to set up the device configuration. It could then call lineGetDevConfig, and save the configuration information in a phone book (or other database) associated with a particular call destination. When the user later wishes to call the same destination again, lineSetDevConfig can be used to restore the configuration settings selected by the user. The functions lineSetDevConfig, lineConfigDialog, and lineGetDevConfig can be used, in that order, to allow the user to view and update the settings.

The exact format of the data contained within the structure is specific to the line and media stream API (device class), is undocumented, and is undefined. The structure returned by this function cannot be directly accessed or manipulated by the application, but can only be stored intact and later used in lineSetDevConfig to restore the settings. The structure also cannot necessarily be passed to other devices, even of the same device class (although this may work in some instances, it is not guaranteed).

See Also

lineConfigDialog, lineGetID, lineSetDevConfig, VARSTRING


lineGetIcon

The lineGetIcon function allows an application to retrieve a service line device-specific (or provider-specific) icon for display to the user.

LONG lineGetIcon(

DWORD dwDeviceID,
LPCSTR lpszDeviceClass,
LPHICON lphIcon
);
Parameters

dwDeviceID

The line device whose icon is requested.

lpszDeviceClass

A pointer to a NULL-terminated string that identifies a device class name. This device class allows the application to select a specific sub-icon applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest-level icon associated with the line device rather than a specified media stream device would be selected.

lphIcon

A pointer to a memory location in which the handle to the icon is returned.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALDEVICECLASS, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_NODEVICE.

Remarks

The lineGetIcon function causes the provider to return a handle (in lphIcon) to an icon resource (obtained from LoadIcon) that is associated with the specified line. The icon handle is for a resource associated with the provider. The application must use CopyIcon if it wishes to reference the icon after the provider is unloaded, which is unlikely to happen as long as the application has the line open.

The lpszDeviceClass parameter allows the provider to return different icons based on the type of service being referenced by the caller. The permitted strings are the same as for lineGetID. For example, if the line supports the Comm API, passing "COMM" as lpszDeviceClass causes the provider to return an icon related specifically to the Comm device functions of the service provider. The parameters "tapi/line", "", or NULL may be used to request the icon for the line service.

For applications using an API version less than 0x00020000, if the provider does not return an icon (whether because the given device class is invalid or the provider does not support icons), TAPI substitutes a generic Win32 Telephony line device icon. For applications using API version 0x00020000 or greater, TAPI substitutes the default line icon only if the lpszDeviceClass parameter is "tapi/line", "" or NULL. For any other device class, if the given device class is not valid or the provider does not support icons for the class, lineGetIcon returns LINEERR_INVALDEVICECLASS.

See Also

lineGetID


lineGetID

The lineGetID function returns a device ID for the specified device class associated with the selected line, address, or call.

LONG lineGetID(

HLINE hLine,
DWORD dwAddressID,
HCALL hCall,
DWORD dwSelect,
LPVARSTRING lpDeviceID,
LPCSTR lpszDeviceClass
);
Parameters

hLine

A handle to an open line device.

dwAddressID

An address on the given open line device.

hCall

A handle to a call.

dwSelect

Specifies whether the requested device ID is associated with the line, address or a single call. The dwSelect parameter can only have a single flag set. This parameter uses the following LINECALLSELECT_ constants:

LINECALLSELECT_LINE

Selects the specified line device. The hLine parameter must be a valid line handle; hCall and dwAddressID are ignored.

LINECALLSELECT_ADDRESS

Selects the specified address on the line. Both hLine and dwAddressID must be valid; hCall is ignored.

LINECALLSELECT_CALL

Selects the specified call. hCall must be valid; hLine and dwAddressID are both ignored.

lpDeviceID

A pointer to a memory location of type VARSTRING, where the device ID is returned. Upon successful completion of the request, this location is filled with the device ID. The format of the returned information depends on the method used by the device class API for naming devices. Prior to calling lineGetID, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

lpszDeviceClass

A pointer to a NULL-terminated ASCII string that specifies the device class of the device whose ID is requested. Valid device class strings are those used in the SYSTEM.INI section to identify device classes.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSELECT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NODEVICE, LINEERR_UNINITIALIZED.

Remarks

The lineGetID function can be used to retrieve a line-device ID when given a line handle. This is useful after a line device has been opened using LINEMAPPER as a device ID in order to determine the real line-device ID of the opened line. This function can also be used to obtain the device ID of a phone device or media device (for device classes such as COM, wave, MIDI, phone, line, or NDIS) associated with a call, address or line. This ID can then be used with the appropriate API (such as phone, midi, wave) to select the corresponding media device associated with the specified call.

See Device Classes in TAPI for device class names.

A vendor that defines a device-specific media mode also needs to define the corresponding device-specific (proprietary) API to manage devices of the media mode. To avoid collisions on device class names assigned independently by different vendors, a vendor should select a name that uniquely identifies both the vendor and, following it, the media type. For example: "intel/video".

See Also

VARSTRING


lineGetLineDevStatus

The lineGetLineDevStatus function enables an application to query the specified open line device for its current status.

LONG lineGetLineDevStatus(

HLINE hLine,
LPLINEDEVSTATUS lpLineDevStatus
);
Parameters

hLine

A handle to the open line device to be queried.

lpLineDevStatus

A pointer to a variably sized data structure of type LINEDEVSTATUS. Upon successful completion of the request, this structure is filled with the line's device status. Prior to calling lineGetLineDevStatus, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL.

Remarks

An application uses lineGetLineDevStatus to query the line device for its current line status. This status information applies globally to all addresses on the line device. Use lineGetAddressStatus to determine status information about a specific address on a line.

See Also

LINEDEVSTATUS, lineGetAddressStatus


lineGetMessage

The lineGetMessage function returns the next TAPI message that is queued for delivery to an application that is using the Event Handle notification mechanism (see lineInitializeEx for further details).

LONG lineGetMessage(

HLINEAPP hLineApp,
LPLINEMESSAGE lpMessage,
DWORD dwTimeout
);
Parameters

hLineApp

The handle returned by lineInitializeEx. The application must have set the LINEINITIALIZEEXOPTION_USEEVENT option in the dwOptions member of the LINEINITIALIZEEXPARAMS structure.

lpMessage

A pointer to a LINEMESSAGE structure. Upon successful return from this function, the structure will contain the next message which had been queued for delivery to the application.

dwTimeout

The time-out interval, in milliseconds. The function returns if the interval elapses, even if no message can be returned. If dwTimeout is zero, the function checks for a queued message and returns immediately. If dwTimeout is INFINITE, the function's time-out interval never elapses.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_NOMEM.

Remarks

If the lineGetMessage function has been called with a non-zero timeout and the application calls lineShutdown on another thread, this function will return immediately with LINEERR_INVALAPPHANDLE.

If the timeout expires (or was zero) and no message could be fetched from the queue, the function returns with the error LINEERR_OPERATIONFAILED.

See Also

lineInitializeEx, LINEINITIALIZEEXPARAMS, LINEMESSAGE, lineShutdown


lineGetNewCalls

The lineGetNewCalls function returns call handles to calls on a specified line or address for which the application currently does not have handles. The application is granted monitor privilege to these calls.

LONG lineGetNewCalls(

HLINE hLine,
DWORD dwAddressID,
DWORD dwSelect,
LPLINECALLLIST lpCallList
);
Parameters

hLine

A handle to an open line device.

dwAddressID

An address on the given open line device.

dwSelect

The selection of calls that are requested. Note that dwSelect can only have one bit set. This parameter uses the following LINECALLSELECT_ constants:

LINECALLSELECT_LINE

Selects calls on the specified line device. The hLine parameter must be a valid line handle; dwAddressID is ignored.

LINECALLSELECT_ADDRESS

Selects calls on the specified address on the specified line device. Both hLine and dwAddressID must be valid.

lpCallList

A pointer to a variably sized data structure of type LINECALLLIST. Upon successful completion of the request, call handles to all selected calls are returned in this structure. Prior to calling lineGetNewCalls, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSELECT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

An application can use lineGetNewCalls to obtain handles to calls for which it currently has no handles. The application can select the calls for which handles are to be returned by basing this selection on scope (calls on a specified line, or calls on a specified address). For example, an application can request call handles to all calls on a given address for which it currently has no handle. The application is always given monitor privilege to the new call handles. Also, when opening a line, an application uses this function to become aware of existing calls.

The application can invoke lineGetCallInfo and lineGetCallStatus for each call in the list to determine the call's information and status, respectively. It can use lineSetCallPrivilege to change its privilege to owner.

See Also

LINECALLLIST, lineGetCallInfo, lineGetCallStatus, lineSetCallPrivilege


lineGetNumRings

The lineGetNumRings function determines the number of rings an inbound call on the given address should ring prior to answering the call.

LONG lineGetNumRings(

HLINE hLine,
DWORD dwAddressID,
LPDWORD lpdwNumRings
);
Parameters

hLine

A handle to the open line device.

dwAddressID

An address on the line device.

lpdwNumRings

The number of rings that is the minimum of all current lineSetNumRings requests.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

The lineGetNumRings and lineSetNumRings functions, when used in combination, provide a mechanism to support the implementation of toll-saver features across multiple independent applications.

An application that receives a handle for a call in the offering state and a LINE_LINEDEVSTATE ringing message should wait a number of rings equal to the number returned by lineGetNumRings before answering the call in order to honor the toll-saver settings across all applications. The lineGetNumRings function returns the minimum of all application's number of rings specified by lineSetNumRings. Because this number may vary dynamically, an application should invoke lineGetNumRings each time it has the option to answer a call. If no application has called lineSetNumRings, the number or rings returned is 0xFFFFFFFF. A separate LINE_LINEDEVSTATE ringing message is sent to the application for each ring cycle.

If call classification is performed by TAPI of answering all calls of unknown media mode and filtering the media stream, TAPI honors this number as well.

Note that this operation is purely informational and does not in itself affect the state of any calls on the line device.

See Also

LINE_LINEDEVSTATE, lineSetNumRings


lineGetProviderList

The lineGetProviderList function returns a list of service providers currently installed in the telephony system.

LONG lineGetProviderList(

DWORD dwAPIVersion,
LPLINEPROVIDERLIST lpProviderList
);
Parameters

dwAPIVersion

The highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).

lpProviderList

A pointer to a memory location where TAPI will return a LINEPROVIDERLIST structure. Prior to calling lineGetProviderList, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INIFILECORRUPT, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL.

Remarks

Although this is a new function which older applications would not be expected to call, for backward compatibility, they should not be prevented from doing so. The function will work the same way for all applications.

See Also

lineNegotiateAPIVersion, LINEPROVIDERLIST


lineGetRequest

The lineGetRequest function retrieves the next by-proxy request for the specified request mode.

LONG lineGetRequest(

HLINEAPP hLineApp,
DWORD dwRequestMode,
LPVOID lpRequestBuffer
);
Parameters

hLineApp

The application's usage handle for the line portion of TAPI.

dwRequestMode

The type of request that is to be obtained. Note that dwRequestMode can only have one bit set. This parameter uses the following LINEREQUESTMODE_ constants:

LINEREQUESTMODE_MAKECALL

A tapiRequestMakeCall request.

lpRequestBuffer

A pointer to a memory buffer where the parameters of the request are to be placed. The size of the buffer and the interpretation of the information placed in the buffer depends on the request mode. The application-allocated buffer is assumed to be of sufficient size to hold the request.

If dwRequestMode is LINEREQUESTMODE_MAKECALL, interpret the content of the request buffer using the LINEREQMAKECALL structure.

If dwRequestMode is LINEREQUESTMODE_MEDIACALL, interpret the content of the request buffer using the LINEREQMEDIACALL structure.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALAPPHANDLE, LINEERR_NOTREGISTERED, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALREQUESTMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOREQUEST.

Remarks

A telephony-enabled application can request that a call be placed on its behalf by invoking tapiRequestMakeCall. These requests are queued by TAPI and the highest priority application that has registered to handle the request is sent a LINE_REQUEST message with indication of the mode of the request that is pending. Typically, this application is the user's call-control application. The LINE_REQUEST message indicates that zero or more requests may be pending for the registered application to process; after receiving LINE_REQUEST, it is the responsibility of the recipient application to call lineGetRequest until LINEERR_NOREQUEST is returned, indicating that no more requests are pending.

Next, the call-control application that receives this message invokes lineGetRequest, specifying the request mode and a buffer that is large enough to hold the request. The call-control application then interprets and executes the request.

After execution of lineGetRequest, TAPI purges the request from its internal queue, making room available for a subsequent request. It is therefore possible for a new LINE_REQUEST message to be received immediately upon execution of lineGetRequest, should the same or another application issue another request. It is the responsibility of the request recipient application to handle this scenario by some mechanism (for example, by making note of the additional LINE_REQUEST and deferring a subsequent lineGetRequest until processing of the preceding request completes, by getting the subsequent request and buffer as necessary, or by another appropriate means).

Note that the subsequent LINE_REQUEST should not be ignored because it will not be repeated by TAPI.

See Also

LINE_REQUEST, LINEREQMAKECALL, tapiRequestMakeCall


lineGetStatusMessages

The lineGetStatusMessages function enables an application to query which notification messages the application is set up to receive for events related to status changes for the specified line or any of its addresses.

LONG lineGetStatusMessages(

HLINE hLine,
LPDWORD lpdwLineStates,
LPDWORD lpdwAddressStates
);
Parameters

hLine

A handle to the line device.

lpdwLineStates

A bit array that identifies for which line device status changes a message is to be sent to the application. If a flag is TRUE, that message is enabled; if FALSE, it is disabled. Note that multiple flags can be set. This parameter uses the following LINEDEVSTATE_ constants:

LINEDEVSTATE_OTHER

Device-status items other than those listed below have changed. The application should check the current device status to determine which items have changed.

LINEDEVSTATE_RINGING

The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending LINE_LINEDEVSTATE messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds.

LINEDEVSTATE_CONNECTED

The line was previously disconnected and is now connected to TAPI.

LINEDEVSTATE_NUMCOMPLETIONS

The number of outstanding call completions on the line device has changed.

LINEDEVSTATE_DISCONNECTED

This line was previously connected and is now disconnected from TAPI.

LINEDEVSTATE_MSGWAITON

The "message waiting" indicator is turned on.

LINEDEVSTATE_MSGWAITOFF

The "message waiting" indicator is turned off.

LINEDEVSTATE_INSERVICE

The line is connected to TAPI. This happens when TAPI is first activated or when the line wire is physically plugged in and in service at the switch while TAPI is active.

LINEDEVSTATE_OUTOFSERVICE

The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.

LINEDEVSTATE_MAINTENANCE

Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.

LINEDEVSTATE_OPEN

The line has been opened by some application.

LINEDEVSTATE_CLOSE

The line has been closed by some application.

LINEDEVSTATE_NUMCALLS

The number of calls on the line device has changed.

LINEDEVSTATE_TERMINALS

The terminal settings have changed.

LINEDEVSTATE_ROAMMODE

The roam mode of the line device has changed.

LINEDEVSTATE_BATTERY

The battery level has changed significantly (cellular).

LINEDEVSTATE_SIGNAL

The signal level has changed significantly (cellular).

LINEDEVSTATE_DEVSPECIFIC

The line's device-specific information has changed.

LINEDEVSTATE_REINIT

Items have changed in the configuration of line devices. To become aware of these changes (for example, the appearance of new line devices) the application should reinitialize its use of TAPI. The hDevice parameter of the LINE_LINEDEVSTATE message is left NULL for this state change as it applies to any of the lines in the system.

LINEDEVSTATE_LOCK

The locked status of the line device has changed.

LINEDEVSTATE_REMOVED

The device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A LINE_LINEDEVSTATE message with this value will normally be immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized will result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will not receive any notification.

lpdwAddressStates

A bit array that identifies for which address status changes a message is to be sent to the application. If a flag is TRUE, that message is enabled; if FALSE, disabled. Multiple flags can be set. This parameter uses the following LINEADDRESSSTATE_ constants:

LINEADDRESSSTATE_OTHER

Address-status items other than those listed below have changed. The application should check the current address status to determine which items have changed.

LINEADDRESSSTATE_DEVSPECIFIC

The device-specific item of the address status has changed.

LINEADDRESSSTATE_INUSEZERO

The address has changed to idle (it is now in use by zero stations).

LINEADDRESSSTATE_INUSEONE

The address has changed from being idle or from being in use by many bridged stations to being in use by just one station.

LINEADDRESSSTATE_INUSEMANY

The monitored or bridged address has changed from being in use by one station to being used by more than one station.

LINEADDRESSSTATE_NUMCALLS

The number of calls on the address has changed. This is the result of events such as a new inbound call, an outbound call on the address, or a call changing its hold status.

LINEADDRESSSTATE_FORWARD

The forwarding status of the address has changed, including the number of rings for determining a "no answer" condition. The application should check the address status to determine details about the address's current forwarding status.

LINEADDRESSSTATE_TERMINALS

The terminal settings for the address have changed.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

TAPI defines a number of messages that notify applications about events occurring on lines and addresses. An application may not be interested in receiving all address and line status change messages. The lineSetStatusMessages function can be used to select which messages the application wants to receive. By default, address status and line status reporting is disabled.

See Also

LINE_CLOSE, LINE_LINEDEVSTATE, lineSetStatusMessages


lineGetTranslateCaps

The lineGetTranslateCaps function returns address translation capabilities.

LONG lineGetTranslateCaps(

HLINEAPP hLineApp,
DWORD dwAPIVersion,
LPLINETRANSLATECAPS lpTranslateCaps
);
Parameters

hLineApp

The application handle returned by lineInitializeEx. If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.

dwAPIVersion

The highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).

lpTranslateCaps

A pointer to a location to which a LINETRANSLATECAPS structure will be loaded. Prior to calling lineGetTranslateCaps, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INIFILECORRUPT, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NODRIVER.

See Also

lineInitializeEx, lineNegotiateAPIVersion, LINETRANSLATECAPS


lineHandoff

The lineHandoff function gives ownership of the specified call to another application. The application can be either specified directly by its filename or indirectly as the highest priority application that handles calls of the specified media mode.

LONG lineHandoff(

HCALL hCall,
LPCSTR lpszFileName,
DWORD dwMediaMode
);
Parameters

hCall

A handle to the call to be handed off. The application must be an owner of the call. The call state of hCall can be any state.

lpszFileName

A pointer to a NULL-terminated ASCII string. If this pointer parameter is non-NULL, it contains the filename of the application that is the target of the handoff. If NULL, the handoff target is the highest priority application that has opened the line for owner privilege for the specified media mode. A valid filename does not include the path of the file.

dwMediaMode

The media mode used to identify the target for the indirect handoff. The dwMediaMode parameter indirectly identifies the target application that is to receive ownership of the call. This parameter is ignored if lpszFileName is not NULL. Only a single flag may be set in the dwMediaMode parameter at any one time. This parameter uses the following LINEMEDIAMODE_ constants:

LINEMEDIAMODE_UNKNOWN

The target application is the one that handles calls of unknown media mode (unclassified calls).

LINEMEDIAMODE_INTERACTIVEVOICE

The target application is the one that handles calls with the interactive voice media mode (live conversations).

LINEMEDIAMODE_AUTOMATEDVOICE

Voice energy is present on the call and the voice is locally handled by an automated application.

LINEMEDIAMODE_DATAMODEM

The target application is the one that handles calls with the data modem media mode.

LINEMEDIAMODE_G3FAX

The target application is the one that handles calls with the group 3 fax media mode.

LINEMEDIAMODE_TDD

The target application is the one that handles calls with the TDD (Telephony Devices for the Deaf) media mode.

LINEMEDIAMODE_G4FAX

The target application is the one that handles calls with the group 4 fax media mode.

LINEMEDIAMODE_DIGITALDATA

The target application is the one that handles calls that are digital data calls.

LINEMEDIAMODE_TELETEX

The target application is the one that handles calls with the teletex media mode.

LINEMEDIAMODE_VIDEOTEX

The target application is the one that handles calls with the videotex media mode.

LINEMEDIAMODE_TELEX

The target application is the one that handles calls with the telex media mode.

LINEMEDIAMODE_MIXED

The target application is the one that handles calls with the ISDN mixed media mode.

LINEMEDIAMODE_ADSI

The target application is the one that handles calls with the ADSI (Analog Display Services Interface) media mode.

LINEMEDIAMODE_VOICEVIEW

The media mode of the call is VoiceView.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_TARGETNOTFOUND, LINEERR_INVALPOINTER, LINEERR_TARGETSELF, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOTOWNER.

Remarks

The lineHandoff function returns LINEERR_TARGETSELF if the calling application attempted an indirect handoff (that is, set the lpszFileName parameter to NULL) and TAPI determined that the application is itself the highest priority application for the given media mode. If LINEERR_TARGETNOTFOUND is returned, a target for the call handoff was not found. This may occur if the named application did not open the same line with the LINECALLPRIVILEGE_OWNER bit in the dwPrivileges parameter of lineOpen. Or, in the case of media-mode handoff, no application has opened the same line with the LINECALLPRIVILEGE_OWNER bit in the dwPrivileges parameter of lineOpen and with the media mode specified in the dwMediaMode parameter having been specified in the dwMediaModes parameter of lineOpen.

Call handoff allows ownership of a call to be passed among applications. There are two types of handoff. In the first type, if the application knows the filename of the target application, it can simply specify the filename of that application. If an instance of the target application has opened the line device, ownership of the call will be passed to the other application; otherwise, the handoff will fail and an error is returned. This form of handoff will succeed if the call handle is handed off to the same file name as the application requesting the handoff.

The second type of handoff is based on media mode. In this case, the application indirectly specifies the target application by means of a media mode. The highest priority application that has currently opened the line device for that media mode is the target for the handoff. If there is no such application, the handoff fails and an error is returned.

The lineHandoff function does not change the media mode of a call. To change the media mode of a call, the application should use lineSetMediaMode on the call, specifying the new media mode. This changes the call's media as stored in the call's LINECALLINFO structure.

If handoff is successful, the receiving application will receive a LINE_CALLSTATE message for the call. This message indicates that the receiving application has owner privilege to the call (dwParam3). In addition, the number of owners and/or monitors for the call may have changed. This is reported by the LINE_CALLINFO message, and the receiving application can then invoke lineGetCallStatus and lineGetCallInfo to retrieve more information about the received call.

The receiving application should first check the media mode in LINECALLINFO. If only a single media mode flag is set, the call is officially of that media mode, and the application can act accordingly. If UNKNOWN and other media mode flags are set, then the media mode of the call is officially UNKNOWN but is assumed to be of one of the media modes for which a flag is set in LINECALLINFO. The application should assume that it ought to probe for the highest priority media mode.

If the probe succeeds (either for that media mode or for another one), the application should set the media mode field in LINECALLINFO to just the single media mode that was recognized. If the media mode is for that media mode, the application can act accordingly; otherwise, if it makes a determination for another media mode, it must first hand off the call to that media mode.

If the probe fails, the application should clear the corresponding media mode flag in LINECALLINFO and hand off the call, specifying dwMediaMode as LINEMEDIAMODE_UNKNOWN. It should also deallocate its call handle (or revert back to monitoring).

If none of the media modes succeeded in making a determination, only the UNKNOWN flag will remain set in the media mode field of LINECALLINFO at the time the media application attempts to hand off the call back to UNKNOWN. The final lineHandoff will fail if the application is the only remaining owner of the call. This informs the application that it should drop the call and deallocate its handle, in which case the call is abandoned. The privileges of the invoking application to the call are unchanged by this operation, but the application can change its privileges to a call with lineSetCallPrivilege.

See Also

LINECALLINFO, lineGetCallStatus, lineOpen, lineSetCallPrivilege, lineSetMediaMode


lineHold

The lineHold function places the specified call on hold.

LONG lineHold(

HCALL hCall
);
Parameters

hCall

A handle to the call to be placed on hold. The application must be an owner of the call. The call state of hCall must be connected.

Return Values

Returns a positive request ID if the function will be completed asynchronously or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Remarks

The call on hold is temporarily disconnected allowing the application to use the line device for making or answering other calls. The lineHold function performs a so-called "hard hold" of the specified call (as opposed to a "consultation call"). A call on hard hold typically cannot be transferred or included in a conference call, but a consultation call can. Consultation calls are initiated using lineSetupTransfer, lineSetupConference, or linePrepareAddToConference.

After a call has been successfully placed on hold, the call state typically transitions to onHold. A held call is retrieved by lineUnhold. While a call is on hold, the application may receive LINE_CALLSTATE messages about state changes of the held call. For example, if the held party hangs up, the call state may transition to disconnected.

In a bridged situation, a lineHold operation may possibly not actually place the call on hold, because the status of other stations on the call may govern (for example, attempting to "hold" a call when other stations are participating will not be possible); instead, the call may simply be changed to the LINECONNECTEDMODE_INACTIVE mode if it remains connected at other stations.

See Also

LINE_CALLSTATE, linePrepareAddToConference, lineSetupConference, lineSetupTransfer, lineUnhold


lineInitialize

The lineInitialize function is obsolete. It continues to be exported by TAPI.DLL and TAPI32.DLL for backward compatibility with applications using API versions 0x00010003 and 0x00010004.

Applications using API version 0x00020000 or greater must use lineInitializeEx instead.

For Windows 95 applications only

The lineInitialize function initializes the application's use of TAPI.DLL for subsequent use of the line abstraction. It registers the application's specified notification mechanism and returns the number of line devices available to the application. A line device is any device that provides an implementation for the line-prefixed functions in the Telephony API.

LONG lineInitialize(

LPHLINEAPP lphLineApp,
HINSTANCE hInstance,
LINECALLBACK lpfnCallback,
LPCSTR lpszAppName,
LPDWORD lpdwNumDevs
);
Parameters

lphLineApp

A pointer to a location that is filled with the application's usage handle for TAPI.

hInstance

The instance handle of the client application or DLL.

lpfnCallback

The address of a callback function that is invoked to determine status and events on the line device, addresses, or calls. For more information see lineCallbackFunc.

lpszAppName

A pointer to a NULL-terminated ASCII string that contains only displayable ASCII characters. If this parameter is not NULL, it contains an application-supplied name for the application. This name is provided in the LINECALLINFO structure to indicate, in a user-friendly way, which application originated, or originally accepted or answered the call. This information can be useful for call logging purposes. If lpszAppName is NULL, the application's filename is used instead.

lpdwNumDevs

A pointer to a DWORD-sized location. Upon successful completion of this request, this location is filled with the number of line devices available to the application.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NODRIVER, LINEERR_NODEVICE, LINEERR_NOMEM, LINEERR_NOMULTIPLEINSTANCE.

Remarks

If LINEERR_REINIT is returned and TAPI reinitialization has been requested (for example as a result of adding or removing a Telephony service provider), then lineInitialize requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown). At that time, the new configuration becomes effective and applications are once again permitted to call lineInitialize. If the LINEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.

The application can refer to individual line devices by using line device IDs that range from zero to dwNumDevs minus one. An application should not assume that these line devices are capable of anything beyond what is specified by the Basic Telephony subset without first querying their device capabilities using lineGetDevCaps and lineGetAddressCaps.

Applications should not invoke lineInitialize without subsequently opening a line (at least for monitoring). If the application is not monitoring and not using any devices, it should call lineShutdown so that memory resources allocated by TAPI.DLL can be released if unneeded, and TAPI.DLL itself can be unloaded from memory while not needed.

Another reason for performing a lineShutdown is that if a user changes the device configuration (adds or removes a line or phone), there is no way for TAPI to notify an application that has a line or phone handle open at the time. Once a reconfiguration has taken place, causing a LINEDEVSTATE_REINIT message to be sent, no applications can open a device until all applications have performed a lineShutdown. If any service provider fails to initialize properly, this function fails and returns the error indicated by the service provider.

On all TAPI platforms, lineInitialize is equivalent to lineInitializeEx() using the LINEINITIALIZEEXOPTION_USEHIDDENWINDOW option.


lineInitializeEx

The lineInitializeEx function initializes the application's use of TAPI for subsequent use of the line abstraction. It registers the application's specified notification mechanism and returns the number of line devices available to the application. A line device is any device that provides an implementation for the line-prefixed functions in the Telephony API.

LONG lineInitializeEx(

LPHLINEAPP lphLineApp,
HINSTANCE hInstance,
LINECALLBACK lpfnCallback,
LPCSTR lpszFriendlyAppName,
LPDWORD lpdwNumDevs,
LPDWORD lpdwAPIVersion,
LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);
Parameters

lphLineApp

A pointer to a location that is filled with the application's usage handle for TAPI.

hInstance

The instance handle of the client application or DLL. The application or DLL may pass NULL for this parameter, in which case TAPI will use the module handle of the root executable of the process (for purposes of identifying call handoff targets and media mode priorities).

lpfnCallback

The address of a callback function that is invoked to determine status and events on the line device, addresses, or calls, when the application is using the "hidden window" method of event notification (for more information see lineCallbackFunc). This parameter is ignored and should be set to NULL when the application chooses to use the "event handle" or "completion port" event notification mechanisms.

lpszFriendlyAppName

A pointer to a NULL-terminated ASCII string that contains only displayable ASCII characters. If this parameter is not NULL, it contains an application-supplied name of the application. This name is provided in the LINECALLINFO structure to indicate, in a user-friendly way, which application originated, or originally accepted or answered the call. This information can be useful for call logging purposes. If lpszFriendlyAppName is NULL, the application's module filename is used instead (as returned by the Windows API GetModuleFileName).

lpdwNumDevs

A pointer to a DWORD-sized location. Upon successful completion of this request, this location is filled with the number of line devices available to the application.

lpdwAPIVersion

A pointer to a DWORD-sized location. The application must initialize this DWORD, before calling this function, to the highest API version it is designed to support (for example, the same value it would pass into dwAPIHighVersion parameter of lineNegotiateAPIVersion). Artificially high values must not be used; the value must be accurately set (for this release, to 0x00020000). TAPI will translate any newer messages or structures into values or formats supported by the application's version. Upon successful completion of this request, this location is filled with the highest API version supported by TAPI (for this release, 0x00020000), thereby allowing the application to detect and adapt to having been installed on a system with an older version of TAPI.

lpLineInitializeExParams

A pointer to a structure of type LINEINITIALIZEEXPARAMS containing additional parameters used to establish the association between the application and TAPI (specifically, the application's selected event notification mechanism and associated parameters).

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_INVALPARAM.

Remarks

Applications must select one of three mechanisms by which TAPI notifies the application of telephony events: Hidden Window, Event Handle, or Completion Port.

The Hidden Window mechanism is selected by specifying LINEINITIALIZEEXOPTION_USEHIDDENWINDOW in the dwOptions field in the LINEINITIALIZEEXPARAMS structure. In this mechanism (which is the only mechanism available to TAPI 1.x applications), TAPI creates a window in the context of the application during the lineInitializeEx function, and subclasses the window so that all messages posted to it are handled by a WNDPROC in TAPI itself. When TAPI has a message to deliver to the application, TAPI posts a message to the hidden window. When the message is received (which can happen only when the application calls the Windows GetMessage API), Windows switches the process context to that of the application and invokes the WNDPROC in TAPI. TAPI then delivers the message to the application by calling the LineCallbackProc, a pointer to which the application provided as a parameter in its call to lineInitializeEx (or lineInitialize, for TAPI 1.3 and 1.4 applications). This mechanism requires the application to have a message queue (which is not desirable for service processes) and to service that queue regularly to avoid delaying processing of telephony events. The hidden window is destroyed by TAPI during the lineShutdown function.

The Event Handle mechanism is selected by specifying LINEINITIALIZEEXOPTION_USEEVENT in the dwOptions field in the LINEINITIALIZEEXPARAMS structure. In this mechanism, TAPI creates an event object on behalf of the application, and returns a handle to the object in the hEvent field in LINEINITIALIZEEXPARAMS. The application must not manipulate this event in any manner (for example, must not call SetEvent, ResetEvent, CloseHandle, and so on) or undefined behavior will result; the application may only wait on this event using functions such as WaitForSingleObject or MsgWaitForMultipleObjects. TAPI will signal this event whenever a telephony event notification is pending for the application; the application must call lineGetMessage to fetch the contents of the message. The event is reset by TAPI when no events are pending. The event handle is closed and the event object destroyed by TAPI during the lineShutdown function. The application is not required to wait on the event handle that is created; the application could choose instead to call lineGetMessage and have it block waiting for a message to be queued.

The Completion Port mechanism is selected by specifying LINEINITIALIZEEXOPTION_USECOMPLETION PORT in the dwOptions field in the LINEINITIALIZEEXPARAMS structure. In this mechanism, whenever a telephony event needs to be sent to the application, TAPI will send it to the application using PostQueuedCompletionStatus to the completion port that the application specified in the hCompletionPort field in LINEINITIALIZEEXPARAMS, tagged with the completion key that the application specified in the dwCompletionKey field in LINEINITIALIZEEXPARAMS. The application must have previously created the completion port using CreateIoCompletionPort. The application retrieves events using GetQueuedCompletionStatus. Upon return from GetQueuedCompletionStatus, the application will have the specified dwCompletionKey written to the DWORD pointed to by the lpCompletionKey parameter, and a pointer to a LINEMESSAGE structure returned to the location pointed to by lpOverlapped. After the application has processed the event, it is the application's responsibility to call LocalFree to release the memory used to contain the LINEMESSAGE structure. Because the application created the completion port (thereby allowing it to be shared for other purposes), the application must close it; the application must not close the completion port until after calling lineShutdown.

When a multi-threaded application is using the Event Handle mechanism and more than one thread is waiting on the handle, or the Completion Port notification mechanism and more than one thread is waiting on the port, it is possible for telephony events to be processed out of sequence. This is not due to the sequence of delivery of events from TAPI, but would be caused by the time slicing of threads or the execution of threads on separate processors.

If LINEERR_REINIT is returned and TAPI reinitialization has been requested, for example as a result of adding or removing a Telephony service provider, then lineInitializeEx requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown), at which time the new configuration becomes effective and applications are once again permitted to call lineInitializeEx.

If the LINEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.

The application can refer to individual line devices by using line device IDs that range from zero to dwNumDevs minus one. An application should not assume that these line devices are capable of any particular TAPI function without first querying their device capabilities by lineGetDevCaps and lineGetAddressCaps.

See Also

lineCallbackFunc, LINECALLINFO, lineGetAddressCaps, lineGetDevCaps, lineGetMessage, lineInitialize, LINEINITIALIZEEXPARAMS, LINEMESSAGE, lineNegotiateAPIVersion, lineShutdown


lineCallbackFunc

The lineCallbackFunc function is a placeholder for the application-supplied function name.

VOID FAR PASCAL lineCallbackFunc(

DWORD hDevice,
DWORD dwMsg,
DWORD dwCallbackInstance,
DWORD dwParam1,
DWORD dwParam2,
DWORD dwParam3
);
Parameters

hDevice

A handle to either a line device or a call associated with the callback. The nature of this handle (line handle or call handle) can be determined by the context provided by dwMsg. Applications must use the DWORD type for this parameter because using the HANDLE type may generate an error.

dwMsg

A line or call device message.

dwCallbackInstance

Callback instance data passed back to the application in the callback. This DWORD is not interpreted by TAPI.

dwParam1

A parameter for the message.

dwParam2

A parameter for the message.

dwParam3

A parameter for the message.

Remarks

For information about parameter values passed to this function, see Line Device Messages.

All callbacks occur in the application's context. The callback function must reside in a DLL or application module.


lineMakeCall

The lineMakeCall function places a call on the specified line to the specified destination address. Optionally, call parameters can be specified if anything but default call setup parameters are requested.

LONG lineMakeCall(

HLINE hLine,
LPHCALL lphCall,
LPCSTR lpszDestAddress,
DWORD dwCountryCode,
LPLINECALLPARAMS const lpCallParams
);
Parameters

hLine

A handle to the open line device on which a call is to be originated.

lphCall

A pointer to an HCALL handle. The handle is only valid after the LINE_REPLY message is received by the application indicating that the lineMakeCall function successfully completed. Use this handle to identify the call when invoking other telephony operations on the call. The application will initially be the sole owner of this call. This handle is void if the function returns an error (synchronously or asynchronously by the reply message).

lpszDestAddress

A pointer to the destination address. This follows the standard dialable number format. This pointer can be NULL for non-dialed addresses (as with a hot phone) or when all dialing will be performed using lineDial. In the latter case, lineMakeCall allocates an available call appearance that would typically remain in the dialtone state until dialing begins. Service providers that have inverse multiplexing capabilities may allow an application to specify multiple addresses at once.

dwCountryCode

The country code of the called party. If a value of zero is specified, a default is used by the implementation.

lpCallParams

A pointer to a LINECALLPARAMS structure. This structure allows the application to specify how it wants the call to be set up. If NULL is specified, a default 3.1 kHz voice call is established and an arbitrary origination address on the line is selected. This structure allows the application to select elements such as the call's bearer mode, data rate, expected media mode, origination address, blocking of caller ID information, and dialing parameters.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_ADDRESSBLOCKED, LINEERR_INVALLINEHANDLE, LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_CALLUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_DIALBILLING, LINEERR_INVALPARAM, LINEERR_DIALDIALTONE, LINEERR_INVALPOINTER, LINEERR_DIALPROMPT, LINEERR_INVALRATE, LINEERR_DIALQUIET, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_RATEUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALBEARERMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALCALLPARAMS, LINEERR_UNINITIALIZED, LINEERR_INVALCOUNTRYCODE, LINEERR_USERUSERINFOTOOBIG.

Remarks

If LINEERR_INVALLINESTATE is returned, the line is currently not in a state in which this operation can be performed. A list of currently valid operations can be found in the dwLineFeatures field (of the type LINEFEATURE_) in the LINEDEVSTATUS structure. Calling lineGetLineDevStatus updates the information in LINEDEVSTATUS. If LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT is returned, none of the actions otherwise performed by lineMakeCall have occurred; for example, none of the dialable address prior to the offending character has been dialed, no hookswitch state has changed, and so on.

After dialing has completed, several LINE_CALLSTATE messages are usually sent to the application to notify it about the progress of the call. No generally valid sequence of call-state transitions is specified, as no single fixed sequence of transitions can be guaranteed in practice. A typical sequence may cause a call to transition from dialtone, dialing, proceeding, ringback, to connected. With non-dialed lines, the call may typically transition directly to connected state.

An application has the option to specify an originating address on the specified line device. A service provider that models all stations on a switch as addresses on a single line device allows the application to originate calls from any of these stations using lineMakeCall.

The call parameters allow the application to make non-voice calls or request special call setup options that are not available by default.

An application can partially dial using lineMakeCall and continue dialing using lineDial. To abandon a call attempt, use lineDrop.

After lineMakeCall returns a success reply message to the application, a LINE_CALLSTATE message is sent to the application to indicate the current state of the call. This state will not necessarily be LINECALLSTATE_DIALTONE.

See Also

LINE_CALLSTATE, LINE_REPLY, LINECALLPARAMS, LINEDEVSTATUS, lineDial, lineDrop, lineGetLineDevStatus


lineMonitorDigits

The lineMonitorDigits function enables and disables the unbuffered detection of digits received on the call. Each time a digit of the specified digit mode is detected, a message is sent to the application indicating which digit has been detected.

LONG lineMonitorDigits(

HCALL hCall,
DWORD dwDigitModes
);
Parameters

hCall

A handle to the call on which digits are to be detected. The call state of hCall can be any state except idle or disconnected.

dwDigitModes

The digit mode or modes that are to be monitored. If dwDigitModes is zero, digit monitoring is canceled. This parameter can have multiple flags set, and uses the following LINEDIGITMODE_ constants:

LINEDIGITMODE_PULSE

Detect digits as audible clicks that are the result of rotary pulse sequences. Valid digits for pulse are '0' through '9'.

LINEDIGITMODE_DTMF

Detect digits as DTMF tones. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.

LINEDIGITMODE_DTMFEND

Detect and provide application notification of DTMF down edges. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

This function is considered successful if digit monitoring has been correctly initiated; not when digit monitoring has terminated. Digit monitoring remains in effect until it is explicitly disabled by calling lineMonitorDigits with dwDigitModes set to zero, until the call transitions to idle, or when the application deallocates its call handle for the call. Although this function can be invoked in any call state, digits are usually detected only while the call is in the connected state.

Each time a digit is detected, a LINE_MONITORDIGITS message is sent to the application passing the detected digit as a parameter.

An application can use lineMonitorDigits to enable or disable unbuffered digit detection. It can use lineGatherDigits for buffered digit detection. After buffered digit gathering is complete, a LINE_GATHERDIGITS message is sent to the application. Both buffered and unbuffered digit detection can be enabled on the same call simultaneously.

Monitoring of digits on a conference call applies only to the hConfCall, not to the individual participating calls.

See Also

LINE_GATHERDIGITS, LINE_MONITORDIGITS, lineGatherDigits


lineMonitorMedia

The lineMonitorMedia function enables and disables the detection of media modes on the specified call. When a media mode is detected, a message is sent to the application.

LONG lineMonitorMedia(

HCALL hCall,
DWORD dwMediaModes
);
Parameters

hCall

A handle to the call. The call state of hCall can be any state except idle.

dwMediaModes

The media modes to be monitored. A value of zero for the dwMediaModes parameter cancels all media mode detection. This parameter can have multiple flags set. This parameter uses the following LINEMEDIAMODE_ constants:

LINEMEDIAMODE_INTERACTIVEVOICE

The application wants to handle calls of the interactive voice media type (it manages live voice calls).

LINEMEDIAMODE_AUTOMATEDVOICE

Voice energy is present on the call and the voice is locally handled by an automated application.

LINEMEDIAMODE_DATAMODEM

The application wants to handle calls with the data modem media mode.

LINEMEDIAMODE_G3FAX

The application wants to handle calls of the group 3 fax media type.

LINEMEDIAMODE_TDD

The application wants to handle calls with the TDD (Telephony Devices for the Deaf) media mode.

LINEMEDIAMODE_G4FAX

The application wants to handle calls of the group 4 fax media type.

LINEMEDIAMODE_DIGITALDATA

The application wants to handle calls of the digital data media type

LINEMEDIAMODE_TELETEX

The application wants to handle calls with the teletex media mode.

LINEMEDIAMODE_VIDEOTEX

The application wants to handle calls with the videotex media mode.

LINEMEDIAMODE_TELEX

The application wants to handle calls with the telex media mode.

LINEMEDIAMODE_MIXED

The application wants to handle calls with the ISDN mixed media mode.

LINEMEDIAMODE_ADSI

The application wants to handle calls with the ADSI (Analog Display Services Interface) media mode.

LINEMEDIAMODE_VOICEVIEW

The media mode of the call is VoiceView.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

The media modes specified with lineOpen relate only to enabling the detection of these media modes by the service provider for the purpose of handing off new incoming calls to the proper application. They do not impact any of the media-mode notification messages that are expected because of a previous invocation of lineMonitorMedia.

This function is considered successful if media-mode monitoring has been correctly initiated, not when media mode monitoring has terminated. Media monitoring for a given media mode remains in effect until it is explicitly disabled by calling lineMonitorMedia with a dwMediaModes parameter set to zero, until the call transitions to idle, or when the application deallocates its call handle for the call. The lineMonitorMedia function is primarily an event reporting mechanism. The media mode of call, as indicated in LINECALLINFO, is not affected by the service provider's detection of the media mode. Only the controlling application can change a call's media mode.

Default media monitoring performed by the service provider corresponds to the union of all media modes specified on lineOpen.

Although this function can be invoked in any call state, a call's media mode can typically only be detected while the call is in certain call states. These states may be device specific. For example, in ISDN, a message may indicate the media mode of the media stream before the media stream exists. Similarly, distinctive ringing or the called ID information about the call can be used to identify the media mode of a call. Otherwise, the call may have to be answered (call in the connected state) to allow a service provider to determine the call's media mode by filtering the media stream. Because filtering a call's media stream implies a computational overhead, applications should disable media monitoring when not required. By default, media monitoring is enabled for newly inbound calls, because a call's media mode selects the application that should handle the call.

An outbound application that deals with voice media modes may want to monitor the call for silence (a tone) to distinguish who or what is at the called end of a call. For example, a person at home may answer calls with just a short "hello." A person in the office may provide a longer greeting, indicating name and company name. An answering machine may typically have an even longer greeting.

Because media-mode detection enabled by lineMonitorMedia is implemented as a read-only operation of the call's media stream, it is not disruptive.

Monitoring of media on a conference call applies only to the hConfCall, not to the individual participating calls

See Also

LINECALLINFO, lineOpen


lineMonitorTones

The lineMonitorTones function enables and disables the detection of inband tones on the call. Each time a specified tone is detected, a message is sent to the application.

LONG lineMonitorTones(

HCALL hCall,
LPLINEMONITORTONE const lpToneList,
DWORD dwNumEntries
);
Parameters

hCall

A handle to the call on whose voice channel tones are to be monitored. The call state of hCall can be any state except idle.

lpToneList

A list of tones to be monitored, of type LINEMONITORTONE. Each tone in this list has an application-defined tag field that is used to identify individual tones in the list report a tone detection. Tone monitoring in progress is canceled or changed by calling this operation with either NULL for lpToneList or with another tone list.

dwNumEntries

The number of entries in lpToneList. This parameter is ignored if lpToneList is NULL.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE, LINEERR_INVALPOINTER, LINEERR_INVALTONE, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

Remarks

This function is successful if tone monitoring has been correctly initiated, not when tone monitoring has terminated. Tone monitoring will remain in effect until it is explicitly disabled by calling lineMonitorTones with another tone list (or NULL), until the call transitions to idle, or when the application deallocates its call handle for the call.

Although this function can be invoked in any call state, tones can typically only be detected while the call is in the connected state. Tone detection typically requires computational resources. Depending on the service provider and other activities that compete for such resources, the number of tones that can be detected may vary over time. Also, an equivalent amount of resources may be consumed for monitoring a single triple frequency tone versus three single frequency tones. If resources are overcommitted, the LINEERR_RESOURCEUNAVAIL error is returned.

Note that lineMonitorTones is also used to detect silence. Silence is specified as a tone with all zero frequencies.

Monitoring of tones on a conference call applies only to the hConfCall, not to the individual participating calls

If the LINEERR_INVALPOINTER error value is returned, the specified lpToneList parameter is invalid or the value specified by the dwNumEntries parameter is too large.

See Also

LINEMONITORTONE


lineNegotiateAPIVersion

The lineNegotiateAPIVersion function allows an application to negotiate an API version to use.

LONG lineNegotiateAPIVersion(

HLINEAPP hLineApp,
DWORD dwDeviceID,
DWORD dwAPILowVersion,
DWORD dwAPIHighVersion,
LPDWORD lpdwAPIVersion,
LPLINEEXTENSIONID lpExtensionID
);
Parameters

hLineApp

The handle to the application's registration with TAPI.

dwDeviceID

The line device to be queried.

dwAPILowVersion

The least recent API version the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.

dwAPIHighVersion

The most recent API version the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.

lpdwAPIVersion

A pointer to a DWORD-sized location that contains the API version number that was negotiated. If negotiation is successful, this number will be in the range between dwAPILowVersion and dwAPIHighVersion.

lpExtensionID

A pointer to a structure of type LINEEXTENSIONID. If the service provider for the specified dwDeviceID supports provider-specific extensions, then, upon a successful negotiation, this structure is filled with the extension ID of these extensions. This structure contains all zeros if the line provides no extensions. An application can ignore the returned parameter if it does not use extensions.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL, LINEERR_NODEVICE.

Remarks

Use lineInitializeEx to determine the number of line devices present in the system. The device ID specified by dwDeviceID varies from zero to one less than the number of line devices present.

The lineNegotiateAPIVersion function is used to negotiate the API version number to use. It also retrieves the extension ID supported by the line device, and returns zeros if no extensions are supported. If the application wants to use the extensions defined by the returned extension ID, it must call lineNegotiateExtVersion to negotiate the extension version to use.

The API version number negotiated is that under which TAPI can operate. If version ranges do not overlap, the application and API or service provider versions are incompatible and an error is returned.

See Also

LINEEXTENSIONID, lineInitializeEx, lineNegotiateExtVersion


lineNegotiateExtVersion

The lineNegotiateExtVersion function allows an application to negotiate an extension version to use with the specified line device. This operation need not be called if the application does not support extensions.

LONG lineNegotiateExtVersion(

HLINEAPP hLineApp,
DWORD dwDeviceID,
DWORD dwAPIVersion,
DWORD dwExtLowVersion,
DWORD dwExtHighVersion,
LPDWORD lpdwExtVersion
);
Parameters

hLineApp

The handle to the application's registration with TAPI.

dwDeviceID

The line device to be queried.

dwAPIVersion

The API version number that was negotiated for the specified line device using lineNegotiateAPIVersion.

dwExtLowVersion

The least recent extension version of the extension ID returned by lineNegotiateAPIVersion that the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.

dwExtHighVersion

The most recent extension version of the extension ID returned by lineNegotiateAPIVersion that the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.

lpdwExtVersion

A pointer to a DWORD-sized location that contains the extension version number that was negotiated. If negotiation is successful, this number will be in the range between dwExtLowVersion and dwExtHighVersion.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODEVICE, LINEERR_OPERATIONUNAVAIL.

Remarks

Use lineInitializeEx to determine the number of line devices present in the system. The device ID specified by dwDeviceID varies from zero to one less than the number of line devices present.

The lineNegotiateAPIVersion function negotiates the API version number to use. It also retrieves the extension ID supported by the line device, which is zeros if no extensions are provided. Version numbers should be incremented by one for each release. Leaving gaps in release version numbering may cause unexpected results.

If the application wants to use the extensions defined by the returned extension ID, it must call lineNegotiateExtVersion to negotiate the extension version to use.

The extension version number negotiated is that under which the application and service provider must both operate. If version ranges do not overlap, the application and service provider versions are incompatible and an error is returned.

See Also

lineInitializeEx, lineNegotiateAPIVersion


lineOpen

The lineOpen function opens the line device specified by its device ID and returns a line handle for the corresponding opened line device. This line handle is used in subsequent operations on the line device.

LONG lineOpen(

HLINEAPP hLineApp,
DWORD dwDeviceID,
LPHLINE lphLine,
DWORD dwAPIVersion,
DWORD dwExtVersion,
DWORD dwCallbackInstance,
DWORD dwPrivileges,
DWORD dwMediaModes,
LPLINECALLPARAMS const lpCallParams
);
Parameters

hLineApp

A handle to the application's registration with TAPI.

dwDeviceID

Identifies the line device to be opened. It can either be a valid device ID or the value:

LINEMAPPER

This value is used to open a line device in the system that supports the properties specified in lpCallParams. The application can use lineGetID to determine the ID of the line device that was opened.

lphLine

A pointer to an HLINE handle, which is then loaded with the handle representing the opened line device. Use this handle to identify the device when invoking other functions on the open line device.

dwAPIVersion

The API version number under which the application and Telephony API have agreed to operate. This number is obtained with lineNegotiateAPIVersion.

dwExtVersion

The extension version number under which the application and the service provider agree to operate. This number is zero if the application does not use any extensions. This number is obtained with lineNegotiateExtVersion.

dwCallbackInstance

User-instance data passed back to the application with each message associated with this line or addresses or calls on this line. This parameter is not interpreted by the Telephony API.

dwPrivileges

The privilege the application wants for the calls it is notified for. This parameter can be a combination of the LINECALLPRIVILEGE_ constants. For applications using API version 0x00020000 or greater, values for this parameter can also be combined with the LINEOPENOPTION_ constants:

LINECALLPRIVILEGE_NONE

The application wants to make only outbound calls.

LINECALLPRIVILEGE_MONITOR

The application only wants to monitor inbound and outbound calls.

LINECALLPRIVILEGE_OWNER

The application wants to own inbound calls of the types specified in dwMediaModes.

LINECALLPRIVILEGE_MONITOR + LINECALLPRIVILEGE_OWNER

The application wants to own inbound calls of the types specified in dwMediaModes, but if it cannot be an owner of a call, it wants to be a monitor.

LINEOPENOPTION_SINGLEADDRESS

The application is interested only in new calls that appear on the address specified by the dwAddressID field in the LINECALLPARAMS structure pointed to by the lpCallParams parameter (which must be specified). If LINEOPENOPTION_SINGLEADDRESS is specified but either lpCallParams is invalid or the included dwAddressID does not exist on the line, the open fails with LINERR_INVALADDRESSID.

In addition to setting the dwAddressID member of the LINECALLPARAMS structure to the desired address, the application must also set dwAddressMode in LINECALLPARAMS to LINEADDRESSMODE_ADDRESSID.

The LINEOPENOPTION_SINGLEADDRESS option affects only TAPI's assignment of initial call ownership of calls created by the service provider using a LINE_NEWCALL message. An application that opens the line with LINECALLPRIVILEGE_MONITOR will continue to receive monitoring handles to all calls created on the line. Furthermore, the application is not restricted in any way from making calls or performing other operations that affect other addresses on the line opened.

LINEOPENOPTION_PROXY

The application is willing to handle certain types of requests from other applications that have the line open, as an adjunct to the service provider. Requests will be delivered to the application using LINE_PROXYREQUEST messages; the application responds to them by calling lineProxyResponse, and can also generate TAPI messages to other applications having the line open by calling lineProxyMessage.

When this option is specified, the application must also specify which specific proxy requests it is prepared to handle. It does so by passing, in the lpCallParams parameter, a pointer to a LINECALLPARAMS structure in which the dwDevSpecificSize and dwDevSpecificOffset members have been set to delimit an array of DWORDs. Each element of this array shall contain one of the LINEPROXYREQUEST_ constants. For example, a proxy handler application that supports all five of the Agent-related functions would pass in an array of five DWORDs (dwDevSpecificSize would be 20 decimal) containing the five defined LINEPROXYREQUEST_ values.

The proxy request handler application can run on any machine that has authorization to control the line device. However, requests will always be routed through the server on which the service provider is executing that actually controls the line device. Thus, it is most efficient if the application handling proxy requests (such as ACD agent control) executes directly on the server along with the service provider.

Subsequent attempts, by the same application or other applications, to open the line device and register to handle the same proxy requests as an application that is already registered fail with LINEERR_NOTREGISTERED.

To stop handling requests on the line, the application simply calls lineClose.

Other flag combinations return the LINEERR_INVALPRIVSELECT error.

dwMediaModes

The media mode or modes of interest to the application. This parameter is used to register the application as a potential target for inbound call and call handoff for the specified media mode. This parameter is meaningful only if the bit LINECALLPRIVILEGE_OWNER in dwPrivileges is set (and ignored if it is not). This parameter uses the following LINEMEDIAMODE_ constants:

LINEMEDIAMODE_UNKNOWN

The application wants to handle calls of unknown media type (unclassified calls).

LINEMEDIAMODE_INTERACTIVEVOICE

The application wants to handle calls of the interactive voice media type. That is, it manages voice calls with the human user on this end of the call.

LINEMEDIAMODE_AUTOMATEDVOICE

Voice energy is present on the call. The voice is locally handled by an automated application.

LINEMEDIAMODE_DATAMODEM

The application wants to handle calls with the data-modem media mode.

LINEMEDIAMODE_G3FAX

The application wants to handle calls of the group 3 fax media type.

LINEMEDIAMODE_TDD

The application wants to handle calls with the TDD (Telephony Devices for the Deaf) media mode.

LINEMEDIAMODE_G4FAX

The application wants to handle calls of the group 4 fax media type.

LINEMEDIAMODE_DIGITALDATA

The application wants to handle calls of the digital-data media type.

LINEMEDIAMODE_TELETEX

The application wants to handle calls with the teletex media mode.

LINEMEDIAMODE_VIDEOTEX

The application wants to handle calls with the videotex media mode.

LINEMEDIAMODE_TELEX

The application wants to handle calls with the telex media mode.

LINEMEDIAMODE_MIXED

The application wants to handle calls with the ISDN mixed media mode.

LINEMEDIAMODE_ADSI

The application wants to handle calls with the ADSI (Analog Display Services Interface) media mode.

LINEMEDIAMODE_VOICEVIEW

The media mode of the call is VoiceView.

lpCallParams

A pointer to a structure of type LINECALLPARAMS. This pointer is only used if LINEMAPPER is used; otherwise lpCallParams is ignored. It describes the call parameter that the line device should be able to provide.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_ALLOCATED, LINEERR_LINEMAPPERFAILED, LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_INVALPRIVSELECT, LINEERR_REINIT, LINEERR_NODEVICE, LINEERR_OPERATIONUNAVAIL.

Remarks

If LINEERR_ALLOCATED is returned, the line cannot be opened due to a "persistent" condition, such as that of a serial port being exclusively opened by another process. If LINEERR_RESOURCEUNAVAIL is returned, the line cannot be opened due to a dynamic resource overcommitment such as in DSP processor cycles or memory. This overcommitment may be transitory, caused by monitoring of media mode or tones, and changes in these activities by other applications may make it possible to reopen the line within a short time period. If LINEERR_REINIT is returned and TAPI reinitialization has been requested, for example as a result of adding or removing a Telephony service provider, then lineOpen requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown), at which time the new configuration becomes effective and applications are once again permitted to call lineInitializeEx.

Opening a line always entitles the application to make calls on any address available on the line. The ability of the application to deal with inbound calls or to be the target of call handoffs on the line is determined by the dwMediaModes parameter. The lineOpen function registers the application as having an interest in monitoring calls or receiving ownership of calls that are of the specified media modes. If the application just wants to monitor calls, then it can specify LINECALLPRIVILEGE_MONITOR. If the application just wants to make outbound calls, it can specify LINECALLPRIVILEGE_NONE. If the application is willing to control unclassified calls (calls of unknown media mode), it can specify LINECALLPRIVILEGE_OWNER and LINEMEDIAMODE_UNKNOWN. Otherwise, the application should specify the media mode it is interested in handling.

The media modes specified with lineOpen add to the default value for the provider's media mode monitoring for initial inbound call type determination. The lineMonitorMedia function modifies the mask that controls LINE_MONITORMEDIA messages. If a line device is opened with owner privilege and an extension media mode is not registered, then the error LINEERR_INVALMEDIAMODE is returned.

An application that has successfully opened a line device can always initiate calls using lineMakeCall, lineUnpark, linePickup, lineSetupConference (with a NULL hCall), as well as use lineForward (assuming that doing so is allowed by the device capabilities, line state, and so on).

A single application may specify multiple flags simultaneously to handle multiple media modes. Conflicts may arise if multiple applications open the same line device for the same media mode. These conflicts are resolved by a priority scheme in which the user assigns relative priorities to the applications. Only the highest priority application for a given media mode will ever receive ownership (unsolicited) of a call of that media mode. Ownership can be received when an inbound call first arrives or when a call is handed off.

Any application (including any lower priority application) can always acquire ownership with lineGetNewCalls or lineGetConfRelatedCalls. If an application opens a line for monitoring at a time that calls exist on the line, LINE_CALLSTATE messages for those existing calls are not automatically generated to the new monitoring application. The application can query the number of current calls on the line to determine how many calls exist, and, if it wants, it can call lineGetNewCalls to obtain handles to these calls.

An application that handles automated voice should also select the interactive voice open mode and be assigned the lowest priority for interactive voice. The reason for this is that service providers will report all voice media modes as interactive voice. If media mode determination is not performed by the application for the UNKNOWN media type, and no interactive voice application has opened the line device, voice calls would be unable to reach the automated voice application, but be dropped instead.

The same application, or different instantiations of the same application, may open the same line multiple times with the same or different parameters.

When an application opens a line device it must specify the negotiated API version and, if it wants to use the line's extensions, it should specify the line's device-specific extension version. These version numbers should have been obtained with lineNegotiateAPIVersion and lineNegotiateExtVersion. Version numbering allows the mixing and matching of different application versions with different API versions and service provider versions.

LINEMAPPER allows an application to select a line indirectly—by means of the services it wants from it. When opening a line device using LINEMAPPER, the following is true: All fields from beginning of the LINECALLPARAMS data structure through dwAddressMode are relevant. If dwAddressMode is LINEADDRESSMODE_ADDRESSID it means that any address on the line is acceptable, otherwise if dwAddressMode is LINEADDRESSMODE_DIALABLEADDR, indicating that a specific originating address (phone number) is searched for, or if it is a provider-specific extension, then dwOrigAddressSize/Offset and the portion of the variable part they refer to are also relevant. If dwAddressMode is a provider-specific extension additional information may be contained in the dwDeviceSpecific variably sized field.

See Also

LINE_CALLSTATE, LINE_MONITORMEDIA, LINE_PROXYREQUEST, LINECALLPARAMS, lineClose, lineForward, lineGetConfRelatedCalls, lineGetNewCalls, lineInitializeEx, lineMakeCall, lineMonitorMedia, lineNegotiateAPIVersion, lineNegotiateExtVersion, linePickup, lineProxyMessage, lineProxyResponse, lineSetupConference, lineShutdown, lineUnpark


linePark

The linePark function parks the specified call according to the specified park mode.

LONG linePark(

HCALL hCall,
DWORD dwParkMode,
LPCSTR lpszDirAddress,
LPVARSTRING lpNonDirAddress
);
Parameters

hCall

A handle to the call to be parked. The application must be an owner of the call. The call state of hCall must be connected.

dwParkMode

The park mode with which the call is to be parked. This parameter can have only a single flag set, and it uses the following LINEPARKMODE_ constants:

LINEPARKMODE_DIRECTED

The application specifies at which address the call is to be parked in lpszDirAddress.

LINEPARKMODE_NONDIRECTED

This operation reports to the application where the call has been parked in lpNonDirAddress.

lpszDirAddress

A pointer to a NULL-terminated string that indicates the address where the call is to be parked when using directed park. The address is in dialable number format. This parameter is ignored for nondirected park.

lpNonDirAddress

A pointer to a structure of type VARSTRING. For nondirected park, the address where the call is parked is returned in this structure. This parameter is ignored for directed park. Within the VARSTRING structure, dwStringFormat must be set to STRINGFORMAT_ASCII (an ASCII string buffer containing a NULL-terminated string), and the terminating NULL must be accounted for in the dwStringSize. Prior to calling linePark, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALADDRESS, LINEERR_NOTOWNER, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALPARKMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

With directed park, the application determines the address at which it wants to park the call. With nondirected park, the switch determines the address and provides this to the application. In either case, a parked call can be unparked by specifying this address.

The parked call typically enters the idle state after it has been successfully parked and the application should then deallocate its handle to the call. If the application performs a lineUnpark on the parked call, a new call handle will be created for the unparked call even if the application has not deallocated its old call handle.

Some switches may remind the user after a call has been parked for some long amount of time. The application will see an offering call with a call reason set to reminder.

On a nondirected park, if the dwTotalSize member in the VARSTRING structure does not specify a sufficient amount of memory to receive the park address, the corresponding reply message returns a LINEERR_STRUCTURETOOSMALL error value. In such cases, there is no way to retrieve the complete park address. Note that when a LINEERR_STRUCTURETOOSMALL error value is returned, the dwNeededSize field of the NonDirAddress structure does not contain a valid value. If a LINEERR_STRUCTURETOOSMALL error value is received from a nondirected linePark, then increase the size of the buffer and call linePark again until it returns either success or a different LINEERR_XXX result.

See Also

LINE_REPLY, lineUnpark, VARSTRING


linePickup

The linePickup function picks up a call alerting at the specified destination address and returns a call handle for the picked-up call. If invoked with NULL for the lpszDestAddress parameter, a group pickup is performed. If required by the device, lpszGroupID specifies the group ID to which the alerting station belongs.

LONG linePickup(

HLINE hLine,
DWORD dwAddressID,
LPHCALL lphCall,
LPCSTR lpszDestAddress,
LPCSTR lpszGroupID
);
Parameters

hLine

A handle to the open line device on which a call is to be picked up.

dwAddressID

The address on hLine at which the pickup is to be originated.

lphCall

A pointer to a memory location where the handle to the picked up call will be returned. The application will be the initial sole owner of the call.

lpszDestAddress

A pointer to a NULL-terminated character buffer that contains the address whose call is to be picked up. The address is in standard dialable address format.

lpszGroupID

A pointer to a NULL-terminated character buffer containing the group ID to which the alerting station belongs. This parameter is required on some switches to pick up calls outside of the current pickup group.

Note that lpszGroupID can be specified by itself with a NULL pointer for lpszDestAddress. Alternatively, lpszGroupID can be specified in addition to lpszDestAddress, if required by the device.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALADDRESS, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALGROUPID, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.

Remarks

When a call has been picked up successfully, the application is notified by the LINE_CALLSTATE message about call state changes. The LINECALLINFO structure supplies information about the call that was picked up. It will list the reason for the call as pickup. This structure is available using lineGetCallInfo.

If LINEADDRCAPFLAGS_PICKUPCALLWAIT is TRUE, linePickup can be used to pick up a call for which the user has audibly detected the call-waiting signal but for which the provider is unable to perform the detection. This gives the user a mechanism to "answer" a waiting call even though the service provider was unable to detect the call-waiting signal. Both lpszDestAddress and lpszGroupID pointer parameters must be NULL to pick up a call-waiting call. The linePickup function will create a new call handle for the waiting call and pass that handle to the user. dwAddressID will most often be zero (particularly in single-line residential cases).

Once linePickup has been used to pick up the second call, lineSwapHold can be used to toggle between them. The lineDrop function can be used to drop one (and toggle to the other), and so forth. If the user wants to drop the current call and pick up the second call, they should call lineDrop when they get the call-waiting beep, wait for the second call to ring, and then call lineAnswer on the new call handle. The LINEADDRFEATURE_PICKUP flag in the dwAddressFeatures field in LINEADDRESSSTATUS indicates when pickup is actually possible.

See Also

LINE_CALLSTATE, LINE_REPLY, LINEADDRESSSTATUS, lineAnswer, LINECALLINFO, lineDrop, lineGetCallInfo, lineSwapHold


linePrepareAddToConference

The linePrepareAddToConference function prepares an existing conference call for the addition of another party.

LONG linePrepareAddToConference(

HCALL hConfCall,
LPHCALL lphConsultCall,
LPLINECALLPARAMS const lpCallParams
);
Parameters

hConfCall

A handle to a conference call. The application must be an owner of this call. The call state of hConfCall must be connected.

lphConsultCall

A pointer to an HCALL handle. This location is then loaded with a handle identifying the consultation call to be added. Initially, the application will be the sole owner of this call.

lpCallParams

A pointer to call parameters to be used when establishing the consultation call. This parameter may be set to NULL if no special call setup parameters are desired.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_CALLUNAVAIL, LINEERR_INVALRATE, LINEERR_CONFERENCEFULL, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_NOTOWNER, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALBEARERMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLPARAMS, LINEERR_RATEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCONFCALLHANDLE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALLINESTATE, LINEERR_USERUSERINFOTOOBIG, LINEERR_INVALMEDIAMODE, LINEERR_UNINITIALIZED.

Remarks

If LINEERR_INVALLINESTATE is returned, the line is currently not in a state in which this operation can be performed. A list of currently valid operations can be found in the dwLineFeatures field (of the type LINEFEATURE_) in the LINEDEVSTATUS structure. (Calling lineGetLineDevStatus updates the information in LINEDEVSTATUS.)

A conference call handle can be obtained with lineSetupConference or with lineCompleteTransfer that is resolved as a three-way conference call. The function linePrepareAddToConference typically places the existing conference call in the onHoldPendingConference state and creates a consultation call that can be added later to the existing conference call with lineAddToConference.

The consultation call can be canceled using lineDrop. It may also be possible for an application to swap between the consultation call and the held conference call with lineSwapHold.

See Also

LINE_REPLY, lineAddToConference, lineCompleteTransfer, LINEDEVSTATUS, lineDrop, lineGetLineDevStatus, lineSetupConference, lineSwapHold


lineProxyMessage

The lineProxyMessage function is used by a registered proxy request handler to generate TAPI messages related to its role. For example, an ACD agent handler can use this function to generate LINE_AGENTSTATUS messages that will be received by all applications that have the specified line open. TAPI suppresses generation of the message on the hLine specified in the function parameters.

LONG lineProxyMessage(

HLINE hLine,
HCALL hCall,
DWORD dwMsg,
DWORD dwParam1,
DWORD dwParam2,
DWORD dwParam3
);
Parameters

hLine

A handle to the open line device. This will be converted by TAPI into the correct hLine for each application that receives the message.

hCall

If the message is related to a specific call (which it is not, in the case of LINE_AGENTSTATUS), specifies the proxy handler's handle to that call; shall be set to NULL for messages not related to a specific call. This will be converted by TAPI into the correct hCall for each application that receives the message.

dwMsg

The TAPI message to be generated. This must be a message that is permitted to be generated by proxy handlers.

dwParam1

dwParam2

dwParam3

The parameters associated with the message to be sent.

Return Values

Returns zero if the function is successful or one of these negative error values:

LINEERR_INVALLINEHANDLE, LINEERR_INVALCALLHANDLE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_NOTREGISTERED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

See Also

LINE_AGENTSTATUS


lineProxyResponse

The lineProxyResponse function indicates completion of a proxy request by a registered proxy handler such as an ACD agent handler on a server.

LONG lineProxyResponse(

HLINE hLine,
LPLINEPROXYREQUEST lpProxyRequest,
DWORD dwResult
);
Parameters

hLine

A handle to the open line device.

lpProxyRequest

The pointer to the proxy request buffer that was given to the application by TAPI in a LINE_PROXYREQUEST message. In the case of proxy requests that return data to the client application, the proxy handler shall have filled in the necessary structure in this buffer before calling this function. The dwNeededSize and dwUsedSize fields of the structure to be returned must have been set appropriately.

dwResult

The function result that is to be returned to the calling application in a LINE_REPLY message (generated automatically by TAPI). Must be 0 or one of the negative error values defined for the function invoked.

Return Values

Returns zero if the function is successful or one of these negative error values:

LINEERR_INVALLINEHANDLE, LINEERR_INVALPARAM, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_NOTREGISTERED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.


lineRedirect

The lineRedirect function redirects the specified offering call to the specified destination address.

LONG lineRedirect(

HCALL hCall,
LPCSTR lpszDestAddress,
DWORD dwCountryCode
);
Parameters

hCall

A handle to the call to be redirected. The application must be an owner of the call. The call state of hCall must be offering.

lpszDestAddress

A pointer to the destination address. This follows the standard dialable number format.

dwCountryCode

The country code of the party the call is redirected to. If a value of zero is specified, a default is used by the implementation.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALADDRESS, LINEERR_NOTOWNER, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

Call redirection allows an application to deflect an offering call to another address without first answering the call. Call redirect differs from call forwarding in that call forwarding is performed by the switch without the involvement of the application; redirection can be done on a call-by-call basis by the application, for example, driven by caller ID information. It differs from call transfer in that transferring a call requires the call first be answered.

After a call has been successfully redirected, the call typically transitions to idle.

Besides redirecting an incoming call, an application may have the option to accept the call using lineAccept, reject the call using lineDrop, or answer the call using lineAnswer. The availability of these operations is dependent on device capabilities.

See Also

LINE_REPLY, lineAccept, lineAnswer, lineDrop


lineRegisterRequestRecipient

The lineRegisterRequestRecipient function registers the invoking application as a recipient of requests for the specified request mode.

LONG lineRegisterRequestRecipient(

HLINEAPP hLineApp,
DWORD dwRegistrationInstance,
DWORD dwRequestMode,
DWORD bEnable
);
Parameters

hLineApp

The application's usage handle for the line portion of TAPI.

dwRegistrationInstance

An application-specific DWORD that is passed back as a parameter of the LINE_REQUEST message. This message notifies the application that a request is pending. This parameter is ignored if bEnable is set to zero. This parameter is examined by TAPI only for registration, not for deregistration. The dwRegistrationInstance value used while deregistering need not match the dwRegistrationInstance used while registering for a request mode.

dwRequestMode

The type or types of request for which the application registers. One or both bits may be set. This parameter uses the following LINEREQUESTMODE_ constants:

LINEREQUESTMODE_MAKECALL

A tapiRequestMakeCall request.

bEnable

If TRUE, the application registers; if FALSE, the application deregisters for the specified request modes.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALREQUESTMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

A telephony-enabled application can request that a call be placed on its behalf by invoking tapiRequestMakeCall. Additionally, other applications can request that information be logged with a given call. The tapiRequestMakeCall requests are queued by TAPI, and the highest priority application that has registered to handle the request is sent a LINE_REQUEST message with an indication of the mode of the request that is pending. This application is typically the user's call-control application.

Next, the call-control application that receives this message invokes lineGetRequest, specifying the request mode and a buffer that is large enough to hold the request. The call-control application then interprets and executes the request.

The recipient application is also automatically deregistered for all requests when it does a lineShutdown.

See Also

LINE_REQUEST, lineGetRequest, lineShutdown, tapiRequestMakeCall


lineReleaseUserUserInfo

The lineReleaseUserUserInfo function informs the service provider that the application has processed the user-to-user information contained in the LINECALLINFO structure, and that subsequently received user-to-user information can now be written into that structure. The service provider will send a LINE_CALLINFO message indicating LINECALLINFOSTATE_USERUSERINFO when new information is available.

LONG lineReleaseUserUserInfo(

HCALL hCall
);
Parameters

hCall

A handle to the call. The application must be an owner of the call. The call state of hCall can be any state.

Return Values

Returns a positive request ID if the function will be completed asynchronously or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED, LINEERR_OPERATIONUNAVAIL.

Remarks

The lineReleaseUserUserInfo function allows the application to control the flow of incoming user-user information on an ISDN connection. When a new, complete user-user information message is received, the service provider informs the application using a LINE_CALLINFO message (specifying LINECALLINFOSTATE_USERUSERINFO). Any number of applications may examine the information (using lineGetCallInfo), but the application owning the call controls when the information is released so that subsequent information can be reported. The service provider will not overwrite previous user-user information in LINECALLINFO with newer information until after lineReleaseUserUserInfo has been called. It is the responsibility of the service provider to buffer subsequently received user-user information until the previous information is released by the application owning the call.

Although this is a new function which older applications would not be expected to call, for backward compatibility, they should not be prevented from doing so. The function will work the same way for all applications.

See Also

LINE_CALLINFO, LINE_REPLY, LINECALLINFO, lineGetCallInfo


lineRemoveFromConference

The lineRemoveFromConference function removes the specified call from the conference call to which it currently belongs. The remaining calls in the conference call are unaffected.

LONG lineRemoveFromConference(

HCALL hCall
);
Parameters

hCall

A handle to the call to be removed from the conference. The application must be an owner of this call. Call state of hCall must be conferenced.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Remarks

This operation removes a party that currently belongs to a conference call. After the call has been successfully removed, it may be possible to further manipulate it using its handle. The availability of this operation and its result are likely to be limited in many implementations. For example, in many implementations, only the most recently added party may be removed from a conference, and the removed call may be automatically dropped (becomes idle). Consult the line's device capabilities to determine the available effects of removing a call from a conference.

If the removal of a participant from a conference is supported, the participant call, after it is removed from the conference, will enter the call-state listed in the dwRemoveFromConfState field in LINEADDRESSCAPS.

See Also

LINE_REPLY, LINEADDRESSCAPS


lineRemoveProvider

The lineRemoveProvider function removes an existing Telephony Service Provider from the Telephony system.

LONG lineRemoveProvider(

DWORD dwPermanentProviderID,
HWND hwndOwner
);
Parameters

dwPermanentProviderID

The permanent provider ID of the service provider to be removed.

hwndOwner

A handle to a window to which any dialogs which need to be displayed as part of the removal process (for example, a confirmation dialog by the service provider's TSPI_providerRemove function) would be attached. Can be a NULL value to indicate that any window created during the function should have no owner window.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED.

Remarks

If the call to TSPI_providerRemove is successful, and the telephony system is active at the time, TAPI calls TSPI_lineShutdown and/or TSPI_phoneShutdown on the service provider (depending on which device types are active). Any line or phone handles still held by applications on associated devices are forcibly closed with LINE_CLOSE or PHONE_CLOSE messages (it is preferable for service providers themselves to issue these messages as part of TSPI_providerRemove, after verification with the user). The devices previously under the control of that provider are then marked as "unavailable", so that any future attempts by applications to reference them by device ID result in LINEERR_NODRIVER.

Although this is a new function which older applications would not be expected to call, for backward compatibility, they should not be prevented from doing so. The function will work the same way for all applications.

See Also

LINE_CLOSE, PHONE_CLOSE


lineSecureCall

The lineSecureCall function secures the call from any interruptions or interference that may affect the call's media stream.

LONG lineSecureCall(

HCALL hCall
);
Parameters

hCall

A handle to the call to be secured. The application must be an owner of the call. The call state of hCall can be any state.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Remarks

A call can be secured to avoid interference. For example, in an analog environment, call-waiting tones may destroy a fax or modem session on the original call. The lineSecureCall function allows an existing call to be secured. The lineMakeCall function provides the option to secure the call from the time of call setup. The securing of a call remains in effect for the duration of the call.

See Also

LINE_REPLY, lineMakeCall


lineSendUserUserInfo

The lineSendUserUserInfo function sends user-to-user information to the remote party on the specified call.

LONG lineSendUserUserInfo(

HCALL hCall,
LPCSTR lpsUserUserInfo,
DWORD dwSize
);
Parameters

hCall

A handle to the call on which to send user-to-user information. The application must be an owner of the call. The call state of hCall must be connected, offering, accepted, or ringback.

lpsUserUserInfo

A pointer to a string containing user-to-user information to be sent to the remote party. User-to-user information is only sent if supported by the underlying network (see LINEDEVCAPS). The protocol discriminator field for the user-user information, if required, should appear as the first byte of the buffer pointed to by lpsUserUserInfo, and must be accounted for in dwSize.

dwSize

The size in bytes of the user-to-user information in lpsUserUserInfo.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Remarks

This function can be used to send user-to-user information at any time during a connected call. If the size of the specified information to be sent is larger than what may fit into a single network message (as in ISDN), the service provider is responsible for dividing the information into a sequence of chained network messages (using "more data").

User-to-user information can also be sent as part of call accept, call reject, and call redirect, and when making calls. User-to-user information can also be received. The received information is available through the call's call-information record. Whenever user-to-user information arrives after call offering or prior to call disconnect, a LINE_CALLINFO message with a UserUserInfo parameter will notify the application that user-to-user information in the call-information record has changed. If multiple network messages are chained, the information is assembled by the service provider and a single message is sent to the application.

See Also

LINE_CALLINFO, LINE_REPLY, LINEDEVCAPS


lineSetAgentActivity

The lineSetAgentActivity function sets the agent activity code associated with a particular address.

LONG lineSetAgentActivity(

HLINE hLine,
DWORD dwAddressID,
DWORD dwActivityID
);
Parameters

hLine

Handle of the line device.

dwAddressID

Identifier of the address for which the agent activity code is to be changed.

dwActivityID

The new agent activity. The meaning of all values of this parameter are specific to the application and call center server.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALADDRESSSTATE, LINEERR_INVALAGENTACTIVITY, LINEERR_INVALLINEHANDLE, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.


lineSetAgentGroup

The lineSetAgentGroup function sets the agent groups into which the agent is logged into on a particular address.

LONG lineSetAgentGroup(

HLINE hLine,
DWORD dwAddressID,
LPLINEAGENTGROUPLIST lpAgentGroupList
);
Parameters

hLine

Handle of the line device.

dwAddressID

Identifier of the address for which the agent information is to be changed.

lpAgentList

Pointer to a LINEAGENTGROUPLIST structure identifying the groups into which the current agent is to be logged in on the address. If the pointer is NULL or the number of groups in the indicated structure is 0, then the agent is logged out of any ACD groups into which the agent is then logged in.

Note that the "Name" fields in the LINEAGENTGROUPENTRY items in the list are ignored for purposes of this function; the control of the logged-in groups is based on the group ID values only.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALADDRESSSTATE, LINEERR_INVALAGENTGROUP, LINEERR_INVALAGENTID, LINEERR_INVALAGENTSKILL, LINEERR_INVALAGENTSUPERVISOR, LINEERR_INVALLINEHANDLE, LINEERR_INVALPARAM, LINEERR_INVALPASSWORD, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

See Also

LINEAGENTGROUPENTRY, LINEAGENTGROUPLIST


lineSetAgentState

The lineSetAgentState function sets the agent state associated with a particular address.

LONG lineSetAgentState(

HLINE hLine,
DWORD dwAddressID,
DWORD dwAgentState,
DWORD dwNextAgentState
);
Parameters

hLine

Handle of the line device.

dwAddressID

Identifier of the address for which the agent information is to be changed.

dwAgentState

The new agent state. Must be one of the LINEAGENTSTATE_ constants, or 0 to leave the agent state unchanged and modify only the next state.

dwNextAgentState

The agent state that should be automatically set when the current call on the address becomes idle. For example, if it is known that after-call work must be performed, this field can be set to LINEAGENTSTATE_WORKAFTERCALL so that a new call will not be assigned to the agent after the current call. Must be one of the LINEAGENTSTATE_ constants, or 0 to use the default next state configured for the agent.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALADDRESSSTATE, LINEERR_INVALAGENTSTATE, LINEERR_INVALLINEHANDLE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.


lineSetAppPriority

The lineSetAppPriority function allows an application to set its priority in the handoff priority list for a particular media mode or Assisted Telephony request mode or to remove itself from the priority list.

LONG lineSetAppPriority(

LPCSTR lpszAppFilename,
DWORD dwMediaMode,
LPLINEEXTENSIONID const lpExtensionID,
DWORD dwRequestMode,
LPCSTR lpszExtensionName,
DWORD dwPriority
);
Parameters

lpszAppFilename

A pointer to a string containing the application executable module filename (without directory information). In API versions 0x00020000 and greater, the parameter can specify a filename in either long or 8.3 filename format.

dwMediaMode

The media mode for which the priority of the application is to be set. The value may be one of the LINEMEDIAMODE_ constants; only a single bit may be on. The value 0 should be used to set the application priority for Assisted Telephony requests.

lpExtensionID

A pointer to structure of type LINEEXTENSIONID. This parameter is ignored.

dwRequestMode

If the dwMediaMode parameter is 0, this parameter specifies the Assisted Telephony request mode for which priority is to be set. It must be either LINEREQUESTMODE_MAKECALL or LINEREQUESTMODE_MEDIACALL. This parameter is ignored if dwMediaMode is non-zero.

lpszExtensionName

This parameter is ignored.

dwPriority

The new priority for the application. If the value 0 is passed, the application is removed from the priority list for the specified media or request mode (if it was already not present, no error is generated). If the value 1 is passed, the application is inserted as the highest-priority application for the media or request mode (and removed from a lower-priority position, if it was already in the list). Any other value generates an error.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_INVALREQUESTMODE, LINEERR_INVALAPPNAME, LINEERR_NOMEM, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER.

Remarks

If LINEERR_INVALMEDIAMODE is returned, the value specified in dwMediaMode is not 0 and not a LINEMEDIAMODE_ constant, or more than one bit is on in the parameter value.

This function updates to stored priority list. If the telephony system is initialized, it also sets the current, active priorities for applications then running; the new priority will be used on the next incoming call or lineHandoff based on media mode.

Although this is a new function which older applications would not be expected to call, for backward compatibility, they should not be prevented from doing so. The function will work the same way for all applications.

See Also

LINEEXTENSIONID, lineHandoff


lineSetAppSpecific

The lineSetAppSpecific function enables an application to set the application-specific field of the specified call's call-information record.

LONG lineSetAppSpecific(

HCALL hCall,
DWORD dwAppSpecific
);
Parameters

hCall

A handle to the call whose application-specific field needs to be set. The application must be an owner of the call. The call state of hCall can be any state.

dwAppSpecific

The new content of the dwAppSpecific field for the call's LINECALLINFO structure. This value is not interpreted by the Telephony API.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOTOWNER, LINEERR_OPERATIONUNAVAIL, LINEERR_OPERATIONFAILED.

Remarks

The application-specific field in the LINECALLINFO data structure that exists for each call is not interpreted by the Telephony API or any of its service providers. Its usage is entirely defined by the applications. The field can be read from the LINECALLINFO record returned by lineGetCallInfo. However, lineSetAppSpecific must be used to set the field so that changes become visible to other applications. When this field is changed, all other applications with call handles are sent a LINE_CALLINFO message with an indication that the dwAppSpecific field has changed.

See Also

LINE_CALLINFO, LINECALLINFO, lineGetCallInfo


lineSetCallData

The lineSetCallData function sets the CallData member in LINECALLINFO. Depending on the service provider implementation, the CallData member may be propagated to all applications having handles to the call, including those on other machines (through the server), and may travel with the call when it is transferred.

LONG lineSetCallData(

HCALL hCall,
LPVOID lpCallData,
DWORD dwSize
);
Parameters

hCall

Handle to the call. The application must have OWNER privilege.

lpCallData

Address of the data to be copied to the CallData member in LINECALLINFO, replacing any existing data.

dwSize

Number of bytes of data to be copied. A value of 0 causes any existing data to be removed.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE, LINEERR_INVALPARAM, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_NOTOWNER, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

See Also

LINECALLINFO


lineSetCallParams

The lineSetCallParams function allows an application to change bearer mode and/or the rate parameters of an existing call.

LONG lineSetCallParams(

HCALL hCall,
DWORD dwBearerMode,
DWORD dwMinRate,
DWORD dwMaxRate,
LPLINEDIALPARAMS const lpDialParams
);
Parameters

hCall

A handle to the call whose parameters are to be changed. The application must be an owner of the call. The call state of hCall can be any state except idle and disconnected.

dwBearerMode

The new bearer mode for the call. This parameter can have only a single bit set, and it uses the following LINEBEARERMODE_ constants:

LINEBEARERMODE_VOICE

A regular 3.1 kHz analog voice-grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.

LINEBEARERMODE_SPEECH

This corresponds to G.711 speech transmission on the call. The network may use processing techniques such as analog transmission, echo cancellation, and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.

LINEBEARERMODE_MULTIUSE

The multi-use mode defined by ISDN.

LINEBEARERMODE_DATA

The unrestricted data transfer on the call. The data rate is specified separately.

LINEBEARERMODE_ALTSPEECHDATA

The alternate transfer of speech or unrestricted data on the same call (ISDN).

LINEBEARERMODE_NONCALLSIGNALING

Corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a media stream by the Telephony API).

LINEBEARERMODE_PASSTHROUGH

When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.

dwMinRate

A lower bound for the call's new data rate. The application is willing to accept a new rate as low as this one.

dwMaxRate

An upper bound for the call's new data rate. This is the maximum data rate the application can accept. If an exact data rate is required, dwMinRate and dwMaxRate should be equal.

lpDialParams

A pointer to the new dial parameters for the call, of type LINEDIALPARAMS. This parameter can be left NULL if the call's current dialing parameters are to be used.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_BEARERMODEUNAVAIL, LINEERR_NOTOWNER, LINEERR_INVALBEARERMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RATEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALRATE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

This operation is used to change the parameters of an existing call. Examples of its usage include changing the bearer mode and/or the data rate of an existing call.

See Also

LINE_REPLY, LINEDIALPARAMS


lineSetCallPrivilege

The lineSetCallPrivilege function sets the application's privilege to the specified privilege.

LONG lineSetCallPrivilege(

HCALL hCall,
DWORD dwCallPrivilege
);
Parameters

hCall

A handle to the call whose privilege is to be set. The call state of hCall can be any state.

dwCallPrivilege

The privilege the application wants to have for the specified call. Only a single flag can be set. This parameter uses the following LINECALLPRIVILEGE_ constants:

LINECALLPRIVILEGE_MONITOR

The application requests monitor privilege to the call. These privileges allow the application to monitor state changes and to query information and status about the call.

LINECALLPRIVILEGE_OWNER

The application requests owner privilege to the call. These privileges allow the application to manipulate the call in ways that affect the state of the call.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLPRIVILEGE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

If the application is the sole owner of a non-idle call and wants to change its privilege to monitor, a LINEERR_INVALCALLSTATE error is returned. If the application wants to, it can first drop the call using lineDrop to make the call transition to the idle state and then change its privilege.

See Also

lineDrop


lineSetCallQualityOfService

The lineSetCallQualityOfService function allows the application to attempt to change the quality of service parameters (reserved capacity and performance guarantees) for an existing call. Except for basic parameter validation, this is a straight pass-through to a service provider.

LONG lineSetCallQualityOfService(

HCALL hCall,
LPVOID lpSendingFlowspec,
DWORD dwSendingFlowspecSize,
LPVOID lpReceivingFlowspec,
DWORD dwReceivingFlowspecSize
);
Parameters

hCall

Handle to the call. The application must have OWNER privilege.

lpSendingFlowspec

Pointer to memory containing a WinSock2 FLOWSPEC structure followed by provider-specific data. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory in the application process, because TAPI will not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the service provider.

dwSendingFlowspecSize

The total size in bytes of the FLOWSPEC structure and accompanying provider-specific data, equivalent to what would have been stored in SendingFlowspec.len in a WinSock2 QOS structure.

lpReceivingFlowspec

Pointer to memory containing a WinSock2 FLOWSPEC structure followed by provider-specific data. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory in the application process, because TAPI will not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the service provider.

dwReceivingFlowspecSize

The total size in bytes of the FLOWSPEC and accompanying provider-specific data, equivalent to what would have been stored in ReceivingFlowspec.len in a WinSock2 QOS structure.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE, LINEERR_INVALPARAM, LINEERR_INVALPOINTER, LINEERR_INVALRATE, LINEERR_NOMEM, LINEERR_NOTOWNER, LINEERR_OPERATIONUNAVAIL, LINEERR_OPERATIONFAILED, LINEERR_RATEUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.


lineSetCallTreatment

The lineSetCallTreatment function sets what sounds a party on a call that is unanswered or on hold will hear. Except for basic parameter validation, it is a straight pass-through by TAPI to the service provider.

LONG lineSetCallTreatment(

HCALL hCall,
DWORD dwCallTreatment
);
Parameters

hCall

Handle to the call. The application must have OWNER privilege.

dwCallTreatment

One of the call treatments supported on the address on which the call appears, as indicated by LINEADDRESSCAPS. LINEERR_INVALPARAM is returned if the specified treatment is not supported.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_NOTOWNER, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

Remarks

The use of call treatment functionality should be limited to controlling of legacy equipment. New equipment is generally designed so that instead of call treatments being generated by external switching equipment, calls would be connected to PC-based audio sources and signals generating using standard Win32 functions such as the multimedia Wave API.

See Also

LINEADDRESSCAPS


lineSetCurrentLocation

The lineSetCurentLocation function sets the location used as the context for address translation.

LONG lineSetCurrentLocation(

HLINEAPP hLineApp,
DWORD dwLocation
);
Parameters

hLineApp

The application handle returned by lineInitializeEx. If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.

dwLocation

Specifies a new value for the CurrentLocation entry in the [Locations] section in the registry. It must contain a valid permanent ID of a Location entry in the [Locations] section, as obtained from lineGetTranslateCaps. If it is valid, the CurrentLocation entry is updated.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALLOCATION, LINEERR_RESOURCEUNAVAIL, LINEERR_NODRIVER, LINEERR_UNINITIALIZED.

See Also

lineGetTranslateCaps, lineInitializeEx


lineSetDevConfig

The lineSetDevConfig function allows the application to restore the configuration of a media stream device on a line device to a setup previously obtained using lineGetDevConfig. For example, the contents of this structure could specify data rate, character format, modulation schemes, and error control protocol settings for a "datamodem" media device associated with the line.

LONG lineSetDevConfig(

DWORD dwDeviceID,
LPVOID const lpDeviceConfig,
DWORD dwSize,
LPCSTR lpszDeviceClass
);
Parameters

dwDeviceID

The line device to be configured.

lpDeviceConfig

A pointer to the opaque configuration data structure that was returned by lineGetDevConfig in the variable portion of the VARSTRING structure.

dwSize

The number of bytes in the structure pointed to by lpDeviceConfig. This value will have been returned in the dwStringSize field in the VARSTRING structure returned by lineGetDevConfig.

lpszDeviceClass

A pointer to a NULL-terminated ASCII string that specifies the device class of the device whose configuration is to be set. Valid device class strings are the same as those specified for the lineGetID function.

Return Values

Returns zero if the function is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_NODEVICE.

Remarks

Call states are device specific.

Typically, an application will call lineGetID to identify the media stream device associated with a line, and then call lineConfigDialog to allow the user to set up the device configuration. It could then call lineGetDevConfig and save the configuration information in a phone book or other database associated with a particular call destination. When the user wants to call the same destination again, this function lineSetDevConfig can be used to restore the configuration settings selected by the user. The lineSetDevConfig, lineConfigDialog, and lineGetDevConfig functions can be used, in that order, to allow the user to view and update the settings.

The exact format of the data contained within the structure is specific to the line and media stream API (device class), is undocumented, and is undefined. The application must treat it as "opaque" and not manipulate the contents directly. Generally, the structure can be sent using this function only to the same device from which it was obtained. Certain Telephony service providers may, however, permit structures to be interchanged between identical devices (that is, multiple ports on the same multi-port modem card). Such interchangeability is not guaranteed in any way, even for devices of the same device class.

Note that some service providers may permit the configuration to be set while a call is active, and others may not.

See Also

lineConfigDialog, lineGetDevConfig, lineGetID, VARSTRING


lineSetLineDevStatus

The lineSetLineDevStatus function sets the line device status. Except for basic parameter validation, it is a straight pass-through to the service provider. The service provider will send a LINE_LINEDEVSTATUS message to inform applications of the new state, when set; TAPI does not synthesize these messages.

LONG WINAPI lineSetLineDevStatus(

DWORD hLine,
DWORD dwStatusToChange,
DWORD fStatus
);
Parameters

hLine

Handle to the line device.

dwStatusToChange

One or more of the LINEDEVSTATUSFLAGS_ values.

fStatus

TRUE (−1) to turn on the indicated status bit(s), FALSE (0) to turn off.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALLINEHANDLE, LINEERR_INVALLINESTATE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL, LINEERR_OPERATIONFAILED, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.


lineSetMediaControl

The lineSetMediaControl function enables and disables control actions on the media stream associated with the specified line, address, or call. Media control actions can be triggered by the detection of specified digits, media modes, custom tones, and call states.

LONG lineSetMediaControl(

HLINE hLine,
DWORD dwAddressID,
HCALL hCall,
DWORD dwSelect,
LPLINEMEDIACONTROLDIGIT const lpDigitList,
DWORD dwDigitNumEntries,
LPLINEMEDIACONTROLMEDIA const lpMediaList,
DWORD dwMediaNumEntries,
LPLINEMEDIACONTROLTONE const lpToneList,
DWORD dwToneNumEntries,
LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
DWORD dwCallStateNumEntries
);
Parameters

hLine

SAa handle to an open line device.

dwAddressID

An address on the given open line device.

hCall

A handle to a call. The application must be an owner of the call. The call state of hCall can be any state.

dwSelect

Specifies whether the media control requested is associated with a single call, is the default for all calls on an address, or is the default for all calls on a line. This parameter can only have a single flag set, and it uses the following LINECALLSELECT_ constants:

LINECALLSELECT_LINE

Selects the specified line device. The hLine parameter must be a valid line handle; hCall and dwAddressID are ignored.

LINECALLSELECT_ADDRESS

Selects the specified address on the line. Both hLine and dwAddressID must be valid; hCall is ignored.

LINECALLSELECT_CALL

Selects the specified call. hCall must be valid; hLine and dwAddressID are both ignored.

lpDigitList

A pointer to the array that contains the digits that are to trigger media control actions, of type LINEMEDIACONTROLDIGIT. Each time a digit in the digit list is detected, the specified media control action is carried out on the call's media stream.

Valid digits for pulse mode are '0' through '9'. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.

dwDigitNumEntries

The number of entries in the lpDigitList.

lpMediaList

A pointer to an array with entries of type LINEMEDIACONTROLMEDIA. The array has dwMediaNumEntries entries. Each entry contains a media mode to be monitored, media-type specific information (such as duration), and a media control field. If a media mode in the list is detected, the corresponding media control action is performed on the call's media stream.

dwMediaNumEntries

The number of entries in lpMediaList.

lpToneList

A pointer to an array with entries of type LINEMEDIACONTROLTONE. The array has dwToneNumEntries entries. Each entry contains a description of a tone to be monitored, duration of the tone, and a media-control field. If a tone in the list is detected, the corresponding media control action is performed on the call's media stream.

dwToneNumEntries

The number of entries in lpToneList.

lpCallStateList

A pointer to an array with entries are of type LINEMEDIACONTROLCALLSTATE. The array has dwCallStateNumEntries entries. Each entry contains a call state and a media control action. Whenever the given call transitions into one of the call states in the list, the corresponding media control action is invoked.

dwCallStateNumEntries

The number of entries in lpCallStateList.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_NOMEM, LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSELECT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATELIST, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITLIST, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_UNINITIALIZED, LINEERR_INVALMEDIALIST, LINEERR_INVALPOINTER, LINEERR_INVALTONELIST.

Remarks

The lineSetMediaControl function is considered successful if media control has been correctly initiated, not when any media control has taken effect. Media control in progress is changed or is canceled by calling this function again with either different parameters or NULLs. If one or more of the parameters lpDigitList, lpMediaList, lpToneList, and lpCallStateList are NULL, then the corresponding digit, media mode, tone, or call state-triggered media control is disabled. To modify just a portion of the media control parameters while leaving the remaining settings in effect, the application should invoke lineSetMediaControl supplying the previous parameters for those portions that must remain in effect, and new parameters for those parts that are to be modified.

If hCall is selected and the call terminates or the application deallocates its handle, media control on that call is canceled.

All applications that are owners of the call are in principle allowed to make media control requests on the call. Only a single media control request can be outstanding on a call across all applications that own the call. Each time lineSetMediaControl is called, the new request overrides any media control then in effect on the call, whether set by the calling application or any other owning application.

Depending on the service provider and other activities that compete for such resources, the amount of simultaneous detections that can be made may vary over time. If service provider resources are overcommitted, the LINEERR_RESOURCEUNAVAIL error is returned.

Whether or not media control is supported by the service provider is a device capability.

See Also

LINEMEDIACONTROLCALLSTATE, LINEMEDIACONTROLDIGIT, LINEMEDIACONTROLMEDIA, LINEMEDIACONTROLTONE


lineSetMediaMode

The lineSetMediaMode function sets the media mode(s) of the specified call in its LINECALLINFO structure.

LONG lineSetMediaMode(

HCALL hCall,
DWORD dwMediaModes
);
Parameters

hCall

A handle to the call whose media mode is to be changed. The application must be an owner of the call. The call state of hCall can be any state.

dwMediaModes

The new media mode(s) for the call. As long as the UNKNOWN media mode flag is set, other media mode flags may be set as well. This is used to identify a call's media mode as not fully determined, but narrowed down to one of a small set of specified media modes. If the UNKNOWN flag is not set, only a single media mode can be specified. This parameter uses the following LINEMEDIAMODE_ constants:

LINEMEDIAMODE_UNKNOWN

The target application is the one that handles calls of unknown media mode (unclassified calls).

LINEMEDIAMODE_INTERACTIVEVOICE

The target application is the one that handles calls with the interactive voice media mode (live conversations).

LINEMEDIAMODE_AUTOMATEDVOICE

Voice energy is present on the call, and the voice is locally handled by an automated application.

LINEMEDIAMODE_DATAMODEM

The target application is the one that handles calls with the data modem media mode.

LINEMEDIAMODE_G3FAX

The target application is the one that handles calls with the group 3 fax media mode.

LINEMEDIAMODE_TDD

The target application is the one that handles calls with the TDD (Telephony Devices for the Deaf) media mode.

LINEMEDIAMODE_G4FAX

The target application is the one that handles calls with the group 4 fax media mode.

LINEMEDIAMODE_DIGITALDATA

The target application is the one that handles calls that are digital data calls.

LINEMEDIAMODE_TELETEX

The target application is the one that handles calls with the teletex media mode.

LINEMEDIAMODE_VIDEOTEX

The target application is the one that handles calls with the videotex media mode.

LINEMEDIAMODE_TELEX

The target application is the one that handles calls with the telex media mode.

LINEMEDIAMODE_MIXED

The target application is the one that handles calls with the ISDN mixed media mode.

LINEMEDIAMODE_ADSI

The target application is the one that handles calls with the ADSI (Analog Display Services Interface) media mode.

LINEMEDIAMODE_VOICEVIEW

The media mode of the call is VoiceView.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONUNAVAIL.

Remarks

The lineSetMediaMode function changes the call's media mode in its LINECALLINFO structure. Typical usage of this operation is either to set a call's media mode to a specific known media mode or to exclude possible media modes as long as the call's media mode is officially unknown (the UNKNOWN media mode flag is set).

See Also

LINECALLINFO


lineSetNumRings

The lineSetNumRings function sets the number of rings that must occur before an incoming call is answered. This function can be used to implement a toll-saver-style function. It allows multiple independent applications to each register the number of rings. The function lineGetNumRings returns the minimum number of all number of rings requested. It can be used by the application that answers inbound calls to determine the number of rings it should wait before answering the call.

LONG lineSetNumRings(

HLINE hLine,
DWORD dwAddressID,
DWORD dwNumRings
);
Parameters

hLine

A handle to the open line device.

dwAddressID

An address on the line device.

dwNumRings

The number of rings before a call should be answered in order to honor the toll-saver requests from all applications.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESSID, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

The lineGetNumRings and lineSetNumRings functions, when used in combination, provide a mechanism to support the implementation of toll-saver features across multiple independent applications. If no application ever calls lineSetNumRings, lineGetNumRings will return 0xFFFFFFFF.

An application that is the owner of a call in the offering state and that received a LINE_LINEDEVSTATE ringing message should wait a number of rings equal to the number returned by lineGetNumRings before answering the call in order to honor the toll-saver settings across all applications. A separate LINE_LINEDEVSTATE ringing message is sent to the application for each ring cycle, so the application should count these messages. If this call disconnects before being answered, and another call comes in shortly thereafter, the LINE_CALLSTATE message should allow the application to determine that ringing is related to the second call.

If call classification is performed by TAPI by means of answering inbound calls of unknown media mode and filtering the media stream, TAPI will honor this number as well.

Note that this operation is purely informational and does not affect the state of any calls on the line device.

See Also

LINE_CALLSTATE, LINE_LINEDEVSTATE, lineGetNumRings


lineSetStatusMessages

The lineSetStatusMessages enables an application to specify which notification messages the application wants to receive for events related to status changes for the specified line or any of its addresses.

LONG lineSetStatusMessages(

HLINE hLine,
DWORD dwLineStates,
DWORD dwAddressStates
);
Parameters

hLine

A handle to the line device.

dwLineStates

A bit array that identifies for which line-device status changes a message is to be sent to the application. This parameter uses the following LINEDEVSTATE_ constants:

LINEDEVSTATE_OTHER

Device-status items other than those listed below have changed. The application should check the current device status to determine which items have changed.

LINEDEVSTATE_RINGING

The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending LINE_LINEDEVSTATE messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds.

LINEDEVSTATE_CONNECTED

The line was previously disconnected and is now connected to TAPI.

LINEDEVSTATE_DISCONNECTED

This line was previously connected and is now disconnected from TAPI.

LINEDEVSTATE_MSGWAITON

The "message waiting" indicator is turned on.

LINEDEVSTATE_MSGWAITOFF

The "message waiting" indicator is turned off.

LINEDEVSTATE_INSERVICE

The line is connected to TAPI. This happens when TAPI is first activated, or when the line wire is physically plugged in and in service at the switch while TAPI is active.

LINEDEVSTATE_OUTOFSERVICE

The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.

LINEDEVSTATE_MAINTENANCE

Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.

LINEDEVSTATE_OPEN

The line has been opened by some application.

LINEDEVSTATE_CLOSE

The line has been closed by some application.

LINEDEVSTATE_NUMCALLS

The number of calls on the line device has changed.

LINEDEVSTATE_NUMCOMPLETIONS

The number of outstanding call completions on the line device has changed.

LINEDEVSTATE_TERMINALS

The terminal settings have changed.

LINEDEVSTATE_ROAMMODE

The roam mode of the line device has changed.

LINEDEVSTATE_BATTERY

The battery level has changed significantly (cellular).

LINEDEVSTATE_SIGNAL

The signal level has changed significantly (cellular).

LINEDEVSTATE_DEVSPECIFIC

The line's device-specific information has changed.

LINEDEVSTATE_REINIT

Items have changed in the configuration of line devices. To become aware of these changes (as with the appearance of new line devices) the application should reinitialize its use of TAPI. New lineInitialize, lineInitializeEx and lineOpen requests are denied until applications have shut down their usage of TAPI. The hDevice parameter of the LINE_LINEDEVSTATE message is left NULL for this state change as it applies to any of the lines in the system. Because of the critical nature of LINEDEVSTATE_REINIT, such messages cannot be masked, so the setting of this bit is ignored and the messages are always delivered to the application.

LINEDEVSTATE_LOCK

The locked status of the line device has changed.

LINEDEVSTATE_REMOVED

Indicates that the device is being removed from the system by the service provider (most likely through user action, via a control panel or similar utility). A LINE_LINEDEVSTATE message with this value will normally be immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized will result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated API TAPI version 0x00010004 or above; applications negotiating a previous API version will not receive any notification.

dwAddressStates

A bit array that identifies for which address status changes a message is to be sent to the application. This parameter uses the following LINEADDRESSSTATE_ constants:

LINEADDRESSSTATE_OTHER

Address-status items other than those listed below have changed. The application should check the current address status to determine which items have changed.

LINEADDRESSSTATE_DEVSPECIFIC

The device-specific item of the address status has changed.

LINEADDRESSSTATE_INUSEZERO

The address has changed to idle (it is now in use by zero stations).

LINEADDRESSSTATE_INUSEONE

The address has changed from idle or from being in use by many bridged stations to being in use by just one station.

LINEADDRESSSTATE_INUSEMANY

The monitored or bridged address has changed from being in use by one station to being used by more than one station.

LINEADDRESSSTATE_NUMCALLS

The number of calls on the address has changed. This is the result of events such as a new inbound call, an outbound call on the address, or a call changing its hold status.

LINEADDRESSSTATE_FORWARD

The forwarding status of the address has changed (including the number of rings for determining a no-answer condition). The application should check the address status to determine details about the address's current forwarding status.

LINEADDRESSSTATE_TERMINALS

The terminal settings for the address have changed.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALADDRESSSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL.

Remarks

TAPI defines a number of messages that notify applications about events occurring on lines and addresses. An application may not be interested in receiving all address and line status change messages. The lineSetStatusMessages function can be used to select which messages the application wants to receive. By default, address and line status reporting is disabled.

See Also

LINE_CLOSE, LINE_LINEDEVSTATE, lineInitialize, lineInitializeEx, lineOpen


lineSetTerminal

The lineSetTerminal function enables an application to specify which terminal information related to the specified line, address, or call is to be routed. The lineSetTerminal function can be used while calls are in progress on the line to allow an application to route these events to different devices as required.

LONG lineSetTerminal(

HLINE hLine,
DWORD dwAddressID,
HCALL hCall,
DWORD dwSelect,
DWORD dwTerminalModes,
DWORD dwTerminalID,
DWORD bEnable
);
Parameters

hLine

A handle to an open line device.

dwAddressID

An address on the given open line device.

hCall

A handle to a call. The call state of hCall can be any state, if dwSelect is CALL.

dwSelect

Specifies whether the terminal setting is requested for the line, the address, or just the specified call. If line or address is specified, events either apply to the line or address itself or serves as a default initial setting for all new calls on the line or address. This parameter uses the following LINECALLSELECT_ constants:

LINECALLSELECT_LINE

Selects the specified line device. The hLine parameter must be a valid line handle; hCall and dwAddressID are ignored.

LINECALLSELECT_ADDRESS

Selects the specified address on the line. Both hLine and dwAddressID must be valid; hCall is ignored.

LINECALLSELECT_CALL

Selects the specified call. hCall must be valid; hLine and dwAddressID are both ignored.

dwTerminalModes

The class or classes of low-level events to be routed to the given terminal. This parameter uses the following LINETERMMODE_ constants:

LINETERMMODE_BUTTONS

The button presses from the terminal to the line.

LINETERMMODE_DISPLAY

The display events from the line to the terminal.

LINETERMMODE_LAMPS

The lamp lighting events from the line to the terminal.

LINETERMMODE_RINGER

The ring requests from the line to the terminal.

LINETERMMODE_HOOKSWITCH

The hookswitch events between the terminal and the line.

LINETERMMODE_MEDIATOLINE

This is the unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIAFROMLINE

This is the unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIABIDIRECT

This is the bidirectional media stream associated with a call on the line and the terminal. Use this value when routing of both unidirectional channels of a call's media stream cannot be controlled independently. Note that MEDIABIDIRECT is mutually exclusive with MEDIATOLINE and MEDIAFROMLINE

dwTerminalID

The device ID of the terminal device where the given events are to be routed. Terminal IDs are small integers in the range of 0 to one less than dwNumTerminals, where dwNumTerminals, and the terminal modes each terminal is capable of handling, are returned by lineGetDevCaps. Note that these terminal IDs have no relation to other device IDs and are defined by the service provider using device capabilities.

bEnable

If TRUE, dwTerminalID is valid and the specified event classes are routed to or from that terminal. If FALSE, these events are not routed to or from the terminal device with ID equal to dwTerminalID.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_NOMEM, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSELECT, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTERMINALID, LINEERR_UNINITIALIZED, LINEERR_INVALTERMINALMODE.

Remarks

An application can use this function to route certain classes of low-level line events to the specified terminal device or to suppress the routing of these events. For example, voice may be routed to an audio I/O device (headset); lamps and display events may be routed to the local phone device, and button events and ringer events may be suppressed altogether.

This function can be called at any time, even when a call is active on the given line device. This allows a user to switch from using the local phone set to another audio I/O device. This function may be called multiple times to route the same events to multiple terminals simultaneously. To reroute events to a different terminal, the application should first disable routing to the existing terminal and then route the events to the new terminal.

Terminal ID assignments are made by the line's service provider. Device capabilities indicate only which terminal IDs the service provider has available. Service providers that do not support this type of event routing would indicate that they have no terminal devices (dwNumTerminals in LINEDEVCAPS would be zero).

Invoking lineSetTerminal on a line or address affects all existing calls on that line or address, but does not affect calls on other addresses. It also sets the default for future calls on that line or address. A line or address that has multiple connected calls active at one time may have different routing in effect for each call.

Disabling the routing of low-level events to a terminal when these events are not currently routed to or from that terminal will not necessarily generate an error so long after the function succeeds (the specified events are not routed to or from that terminal).

TAPI routes call progress tones and messages to the same location as set by the lineSetTerminal function for "media". For example, if audio signals are going to the phone, then so will busy signals (analog) or Q.931 messages indicating busy (digital).

See Also

LINE_REPLY, LINEDEVCAPS, lineGetDevCaps


lineSetTollList

The lineSetTollList function manipulates the toll list.

LONG lineSetTollList(

HLINEAPP hLineApp,
DWORD dwDeviceID,
LPCSTR lpszAddressIn,
DWORD dwTollListOption
);
Parameters

hLineApp

The application handle returned by lineInitializeEx.  If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.

dwDeviceID

The device ID for the line device upon which the call is intended to be dialed, so that variations in dialing procedures on different lines can be applied to the translation process.

lpszAddressIn

A pointer to a NULL-terminated ASCII string containing the address from which the prefix information is to be extracted for processing. This parameter must not be NULL, and it must be in the canonical address format.

dwTollListOption

The toll list operation to be performed. Only a single flag can be set. This parameter uses the following LINETOLLLISTOPTION_ constants:

LINETOLLLISTOPTION_ADD

Causes the prefix contained within the string pointed to by lpszAddressIn to be added to the toll list for the current location.

LINETOLLLISTOPTION_REMOVE

Causes the prefix to be removed from the toll list of the current location. If toll lists are not used or relevant to the country indicated in the current location, the operation has no affect.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INVALAPPHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INIFILECORRUPT, LINEERR_UNINITIALIZED, LINEERR_INVALLOCATION.

See Also

lineInitializeEx


lineSetupConference

The lineSetupConference function sets up a conference call for the addition of the third party.

LONG lineSetupConference(

HCALL hCall,
HLINE hLine,
LPHCALL lphConfCall,
LPHCALL lphConsultCall,
DWORD dwNumParties,
LPLINECALLPARAMS const lpCallParams
);
Parameters

hCall

The initial call that identifies the first party of a conference call. In some environments (as described in device capabilities), a call must exist to start a conference call, and the application must be an owner of this call. In other telephony environments, no call initially exists, hCall must be left NULL, and hLine must be specified to identify the line on which the conference call is to be initiated. The call state of hCall must be connected.

hLine

A handle to the line. This handle is used to identify the line device on which to originate the conference call if hCall is NULL. The hLine parameter is ignored if hCall is non-NULL.

lphConfCall

A pointer to an HCALL handle. This location is then loaded with a handle identifying the newly created conference call. The application will be the initial sole owner of this call. The call state of hConfCall is not applicable.

lphConsultCall

A pointer to an HCALL handle. When setting up a call for the addition of a new party, a new temporary call (consultation call) is automatically allocated. Initially, the application will be the sole owner for this call.

dwNumParties

The expected number of parties in the conference call. This number is passed to the service provider. The service provider is free to do as it pleases with this number: ignore it, use it as a hint to allocate the right size conference bridge inside the switch, and so on.

lpCallParams

A pointer to call parameters to be used when establishing the consultation call. This parameter may be set to NULL if no special call setup parameters are desired.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_BEARERMODEUNAVAIL, LINEERR_UNINITIALIZED, LINEERR_CALLUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_CONFERENCEFULL, LINEERR_INVALPOINTER, LINEERR_INUSE, LINEERR_INVALRATE, LINEERR_INVALADDRESSMODE, LINEERR_NOMEM, LINEERR_INVALBEARERMODE, LINEERR_NOTOWNER, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLPARAMS, LINEERR_RATEUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_STRUCTURETOOSMALL, LINEERR_USERUSERINFOTOOBIG.

Remarks

If LINEERR_INVALLINESTATE is returned, the line is currently not in a state in which this operation can be performed. A list of currently valid operations can be found in the dwLineFeatures field (of the type LINEFEATURE) in the LINEDEVSTATUS structure. (Calling lineGetLineDevStatus updates the information in LINEDEVSTATUS.) If LINEERR_INVALMEDIAMODE is returned, check for supported media modes on the line in the dwMediaModes field in the LINEDEVCAPS structure.

The lineSetupConference function provides two ways to establish a new conference call, depending on whether a normal two-party call is required to pre-exist or not. When setting up a conference call from an existing two-party call, the hCall parameter is a valid call handle that is initially added to the conference call by the lineSetupConference request; hLine is ignored. On switches where conference call setup does not start with an existing call, hCall must be NULL and hLine must be specified to identify the line device on which to initiate the conference call. In either case, a consultation call is allocated for connecting to the party that is to be added to the call. The application can then use lineDial to dial the address of the other party.

The conference call typically transitions into the onHoldPendingConference state, the consultation call into the dialtone state, and the initial call (if there is one) into the conferenced state.

A conference call can also be set up by a lineCompleteTransfer that is resolved into a three-way conference. The application may be able to toggle between the consultation call and the conference call using lineSwapHold.

A consultation call can be canceled by invoking lineDroponit. When dropping a consultation call, the existing conference call typically transitions back to the connected state. The application should observe the LINE_CALLSTATE messages to determine exactly what happens to the calls. For example, if the conference call reverts back to a regular two-party call, the conference call will become idle and the original participant call may revert to connected.

If an application specifies the handle of the original call (hCall) in a call to the lineUnhold function, both the conference call and the consultation call typically go to idle.

See Also

LINE_CALLSTATE, lineCompleteTransfer, LINEDEVCAPS, LINEDEVSTATUS, lineDial, lineGetLineDevStatus, lineSwapHold, lineUnhold


lineSetupTransfer

The lineSetupTransfer function initiates a transfer of the call specified by hCall. It establishes a consultation call, lphConsultCall, on which the party can be dialed that can become the destination of the transfer. The application acquires owner privilege to lphConsultCall.

LONG lineSetupTransfer(

HCALL hCall,
LPHCALL lphConsultCall,
LPLINECALLPARAMS const lpCallParams
);
Parameters

hCall

The handle of the call to be transferred. The application must be an owner of the call. The call state of hCall must be connected.

lphConsultCall

A pointer to an HCALL handle. This location is then loaded with a handle identifying the temporary consultation call. When setting up a call for transfer, another call (a consultation call) is automatically allocated to enable the application to dial the address (using lineDial) of the party to where the call is to be transferred. The originating party can carry on a conversation over this consultation call prior to completing the transfer. Call state of hConsultCall is not applicable.

This transfer procedure may not be valid for some line devices. The application may need to ignore the new consultation call and unhold an existing held call (using lineUnhold) to identify the destination of the transfer. On switches that support cross-address call transfer, the consultation call may exist on a different address than the call to be transferred. It may also be necessary that the consultation call be set up as an entirely new call, by lineMakeCall, to the destination of the transfer. Which forms of transfer are available are specified in the call's address capabilities.

lpCallParams

A pointer to call parameters to be used when establishing the consultation call. This parameter may be set to NULL if no special call setup parameters are desired.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_NOTOWNER, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALBEARERMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_RATEUNAVAIL, LINEERR_INVALCALLPARAMS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALLINESTATE, LINEERR_UNINITIALIZED, LINEERR_INVALMEDIAMODE, LINEERR_USERUSERINFOTOOBIG, LINEERR_INVALPOINTER.

Remarks

The lineSetupTransfer function sets up the transfer of the call specified by hCall. The setup phase of a transfer establishes a consultation call that enables the application to send the address of the destination (the party to be transferred to) to the switch, while the call to be transferred is kept on hold. This new call is referred to as a consultation call (hConsultCall) and can be dropped or otherwise manipulated independently of the original call.

When the consultation call has reached the dialtone call state, the application may proceed transferring the call either by dialing the destination address and tracking its progress, or by unholding an existing call. The transfer of the original call to the selected destination is completed using lineCompleteTransfer.

While the consultation call exists, the original call typically transitions to the onholdPendingTransfer state. The application may be able to toggle between the consultation call and the original call by using lineSwapHold. A consultation call can be canceled by invoking lineDrop on it. After dropping a consultation call, the original call will typically transition back to the connected state. If the call state of the original call is onHoldPendingTransfer, the lineUnhold function can be used to recover the call. In this case, the call state of the consultation call is set to idle.

The application may also transfer calls in a single step, without having to deal with the intervening consultation call by using lineBlindTransfer.

See Also

LINE_REPLY, lineBlindTransfer, lineCompleteTransfer, lineDial, lineDrop, lineMakeCall, lineSwapHold, lineUnhold


lineShutdown

The lineShutdown function shuts down the application's usage of the line abstraction of API.

LONG lineShutdown(

HLINEAPP hLineApp
);
Parameters

hLineApp

The application's usage handle for the line API.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

If this function is called when the application has lines open or calls active, the call handles are deleted and TAPI automatically performs the equivalent of a lineClose on each open line. However, it is recommended that applications explicitly close all open lines before invoking lineShutdown. If shutdown is performed while asynchronous requests are outstanding, those requests will be canceled.

See Also

lineClose


lineSwapHold

The lineSwapHold function swaps the specified active call with the specified call on consultation hold.

LONG lineSwapHold(

HCALL hActiveCall,
HCALL hHeldCall
);
Parameters

hActiveCall

The handle to the active call. The application must be an owner of the call. The call state of hActiveCall must be connected.

hHeldCall

The handle to the consultation call. The application must be an owner of the call. The call state of hHeldCall can be onHoldPendingTransfer, onHoldPendingConference, onHold .

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Remarks

Swapping the active call with the call on consultation hold allows the application to alternate or toggle between these two calls. This is typical in call waiting.

See Also

LINE_REPLY


lineTranslateAddress

The lineTranslateAddress function translates the specified address into another format.

LONG lineTranslateAddress(

HLINEAPP hLineApp,
DWORD dwDeviceID,
DWORD dwAPIVersion,
LPCSTR lpszAddressIn,
DWORD dwCard,
DWORD dwTranslateOptions,
LPLINETRANSLATEOUTPUT lpTranslateOutput
);
Parameters

hLineApp

The application handle returned by lineInitializeEx. If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.

dwDeviceID

The device ID for the line device upon which the call is intended to be dialed, so that variations in dialing procedures on different lines can be applied to the translation process.

dwAPIVersion

Indicates the highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).

lpszAddressIn

A pointer to a NULL-terminated ASCII string containing the address from which the information is to be extracted for translation. Must be in either the canonical address format, or an arbitrary string of dialable digits (non-canonical). This parameter must not be NULL. If the AddressIn contains a subaddress or name field, or additional addresses separated from the first address by ASCII CR and LF characters, only the first address is translated, and the remainder of the string is returned to the application without modification.

dwCard

The credit card to be used for dialing. This field in only valid if the CARDOVERRIDE bit is set in dwTranslateOptions. This field specifies the permanent ID of a Card entry in the [Cards] section in the registry (as obtained from lineTranslateCaps) which should be used instead of the PreferredCardID specified in the definition of the CurrentLocation. It does not cause the PreferredCardID parameter of the current Location entry in the registry to be modified; the override applies only to the current translation operation. This field is ignored if the CARDOVERRIDE bit is not set in dwTranslateOptions.

dwTranslateOptions

The associated operations to be performed prior to the translation of the address into a dialable string. This parameter uses the following LINETRANSLATEOPTION_ constants:

LINETRANSLATEOPTION_CARDOVERRIDE

If this bit is set, dwCard specifies the permanent ID of a Card entry in the [Cards] section in the registry (as obtained from lineTranslateCaps) which should be used instead of the PreferredCardID specified in the definition of the CurrentLocation. It does not cause the PreferredCardID parameter of the current Location entry in the registry to be modified; the override applies only to the current translation operation. The dwCard field is ignored if the CARDOVERRIDE bit is not set.

LINETRANSLATEOPTION_CANCELCALLWAITING

If a Cancel Call Waiting string is defined for the location, setting this bit will cause that string to be inserted at the beginning of the dialable string. This is commonly used by data modem and fax applications to prevent interruption of calls by call waiting beeps. If no Cancel Call Waiting string is defined for the location, this bit has no affect. Note that applications using this bit are advised to also set the LINECALLPARAMFLAGS_SECURE bit in the dwCallParamFlags field of the LINECALLPARAMS structure passed in to lineMakeCall through the lpCallParams parameter, so that if the line device uses a mechanism other than dialable digits to suppress call interrupts that that mechanism will be invoked.

LINETRANSLATEOPTION_FORCELOCAL

If the number is local but would have been translated as a long distance call (LINETRANSLATERESULT_INTOLLLIST bit set in the LINETRANSLATEOUTPUT structure), this option will force it to be translated as local. This is a temporary override of the toll list setting.

LINETRANSLATEOPTION_FORCELD

If the address could potentially have been a toll call, but would have been translated as a local call (LINETRANSLATERESULT_NOTINTOLLLIST bit set in the LINETRANSLATEOUTPUT structure), this option will force it to be translated as long distance. This is a temporary override of the toll list setting.

lpTranslateOutput

A pointer to an application-allocated memory area to contain the output of the translation operation, of type LINETRANSLATEOUTPUT. Prior to calling lineTranslateAddress, the application should set the dwTotalSize field of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_INVALPOINTER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NODRIVER, LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCARD, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPARAM.

See Also

lineInitializeEx, LINECALLPARAMS, lineNegotiateAPIVersion, LINETRANSLATEOUTPUT


lineTranslateDialog

The lineTranslateDialog function displays an application-modal dialog which allows the user to change the current location, adjust location and calling card parameters, and see the effect on a phone number about to be dialed.

LONG lineTranslateDialog(

HLINEAPP hLineApp,
DWORD dwDeviceID,
DWORD dwAPIVersion,
HWND hwndOwner,
LPCSTR lpszAddressIn
);
Parameters

hLineApp

The application handle returned by lineInitializeEx.  If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.

dwDeviceID

The device ID for the line device upon which the call is intended to be dialed, so that variations in dialing procedures on different lines can be applied to the translation process.

dwAPIVersion

Indicates the highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on the line device indicated by dwDeviceID).

hwndOwner

A handle to a window to which the dialog is to be attached. Can be a NULL value to indicate that any window created during the function should have no owner window.

lpszAddressIn

A pointer to a NULL-terminated ASCII string containing a phone number which will be used, in the lower portion of the dialog, to show the effect of the user's changes to the location parameters. The number must be in canonical format; if non-canonical, the phone number portion of the dialog will not be displayed. This pointer can be left NULL, in which case the phone number portion of the dialog will not be displayed. If the AddressIn contains a subaddress or name field, or additional addresses separated from the first address by ASCII CR and LF characters, only the first address is used in the dialog.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_INVALPARAM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_INVALPOINTER, LINEERR_INIFILECORRUPT, LINEERR_NODRIVER, LINEERR_INUSE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED.

Remarks

In API versions 0x00020000 and greater, it is possible for multiple instances of this dialog to be opened. In API versions less than 0x00020000, LINEERR_INUSE is returned if the dialog is already displayed by another application (cannot be open more than once). In these versions, TAPI brings the existing dialog to the front, and the error indicates that any particulars related to the address passed in by the current application have not been handled, because that address was not processed by the function.

The application must call lineGetTranslateCaps after this function to obtain any changes the user made to the telephony address translation parameters, and call lineTranslateAddress to obtain a dialable string based on the user's new selections.

If any function related to address translation (for example, lineGetTranslateCaps or lineTranslateAddress) returns LINEERR_INIFILECORRUPT, the application should call lineTranslateDialog. The lineTranslateDialog function will detect the errors and correct them, and report the action taken to the user. Note that LINEERR_INIFILECORRUPT will be returned the first time any of these functions are used after installation of Windows 95, because the parameters will be uninitialized (lineTranslateDialog will take care of initializing them, using the user-specified default country to select the default country code).

Although this is a new function which older applications would not be expected to call, for backward compatibility, they should not be prevented from doing so; the full range of API versions supported by TAPI (0x00010003 to 0x00010004) should work the same way.

See Also

lineGetTranslateCaps, lineInitializeEx, lineNegotiateAPIVersion, lineTranslateAddress


lineUncompleteCall

The lineUncompleteCall function cancels the specified call completion request on the specified line.

LONG lineUncompleteCall(

HLINE hLine,
DWORD dwCompletionID
);
Parameters

hLine

A handle to the line device on which a call completion is to be canceled.

dwCompletionID

The completion ID for the request that is to be canceled.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCOMPLETIONID, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONUNAVAIL.

See Also

LINE_REPLY


lineUnhold

The lineUnhold function retrieves the specified held call.

LONG lineUnhold(

HCALL hCall
);
Parameters

hCall

The handle to the call to be retrieved. The application must be an owner of this call. The call state of hCall must be onHold, onHoldPendingTransfer, or onHoldPendingConference.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

See Also

LINE_REPLY


lineUnpark

The lineUnpark function retrieves the call parked at the specified address and returns a call handle for it.

LONG lineUnpark(

HLINE hLine,
DWORD dwAddressID,
LPHCALL lphCall,
LPCSTR lpszDestAddress
);
Parameters

hLine

A handle to the open line device on which a call is to be unparked.

dwAddressID

The address on hLine at which the unpark is to be originated.

lphCall

A pointer to the location of type HCALL where the handle to the unparked call is returned. This handle is unrelated to any other handle which might have been previously associated with the retrieved call, such as the handle that might have been associated with the call when it was originally parked. The application will be the initial sole owner of this call.

lpszDestAddress

A pointer to a NULL-terminated character buffer that contains the address where the call is parked. The address is in standard dialable address format.

Return Values

Returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

See Also

LINE_REPLY


Phone Device Functions

This section contains the telephony API phone device functions.


phoneClose

The phoneClose function closes the specified open phone device.

LONG phoneClose(

HPHONE hPhone
);
Parameters

hPhone

A handle to the open phone device to be closed. If the function is successful, the handle is no longer valid.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_OPERATIONFAILED, PHONEERR_RESOURCEUNAVAIL, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED.

Remarks

After the open phone device has been successfully closed, the implementation sends a PHONE_CLOSE message to the application. Note that these messages can also be sent unsolicited as a result of the phone device being reclaimed somehow. An application should therefore be prepared to handle these unsolicited close messages. At the time the phone device is closed, any outstanding asynchronous replies are suppressed.

See Also

PHONE_CLOSE


phoneConfigDialog

The phoneConfigDialog function causes the provider of the specified phone device to display a modal dialog (attached to the application's hwndOwner) that allows the user to configure parameters related to the phone device specified by dwDeviceID.

LONG phoneConfigDialog(

DWORD dwDeviceID,
HWND hwndOwner,
LPCSTR lpszDeviceClass
);
Parameters

dwDeviceID

The phone device to be configured.

hwndOwner

A handle to a window to which the dialog is to be attached. Can be a NULL value to indicate that any window created during the function should have no owner window.

lpszDeviceClass

A pointer to a NULL-terminated string that identifies a device class name. This device class allows the application to select a specific subscreen of configuration information applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest level configuration is selected.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_BADDEVICEID, PHONEERR_NOMEM, PHONEERR_INUSE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPARAM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALDEVICECLASS, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED, PHONEERR_NODEVICE.

Remarks

The lpszDeviceClass parameter allows the application to select a specific subscreen of configuration information applicable to the device class in which the user is interested; the permitted strings are the same as for phoneGetID. For example, if the phone supports the wave API, passing "wave/in" as lpszDeviceClass would cause the provider to display the parameters related specifically to wave (or at least to start at the corresponding point in a multilevel configuration dialog chain, eliminating the need to search for relevant parameters).

The lpszDeviceClass parameter should be "tapi/phone", "", or NULL to cause the provider to display the highest level configuration for the phone.

See Also

phoneGetID


phoneDevSpecific

The phoneDevSpecific function Is used as a general extension mechanism to enable a Telephony API implementation to provide features not described in the other TAPI functions. The meanings of these extensions are device specific.

LONG phoneDevSpecific(

HPHONE hPhone,
LPVOID lpParams,
DWORD dwSize
);
Parameters

hPhone

A handle to a phone device.

lpParams

A pointer to a memory area used to hold a parameter block. Its interpretation is device specific. The contents of the parameter block are passed unchanged to or from the service provider by TAPI.

dwSize

The size in bytes of the parameter block area.

Return Values

Returns a positive request ID if the function will be completed asynchronously or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONFAILED.

Additional return values are device specific.

Remarks

This operation provides a generic parameter profile. The interpretation of the parameter block is device specific. Indications and replies that are device specific should use the PHONE_DEVSPECIFIC message.

A service provider can provide access to device-specific functions by defining parameters for use with this operation. Applications that want to make use of these device-specific extensions should consult the device-specific (vendor-specific) documentation that describes which extensions are defined. Note that an application that relies on these device-specific extensions will typically not be portable to work with other service-provider environments.

See Also

PHONE_DEVSPECIFIC, PHONE_REPLY


phoneGetButtonInfo

The phoneGetButtonInfo function returns information about the specified button.

LONG phoneGetButtonInfo(

HPHONE hPhone,
DWORD dwButtonLampID,
LPPHONEBUTTONINFO lpButtonInfo
);
Parameters

hPhone

A handle to the open phone device.

dwButtonLampID

A button on the phone device.

lpButtonInfo

A pointer to a variably sized structure of type PHONEBUTTONINFO. This data structure describes the mode, the function, and provides additional descriptive text corresponding to the button.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALBUTTONLAMPID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_STRUCTURETOOSMALL, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED.

See Also

PHONEBUTTONINFO


phoneGetData

The phoneGetData function uploads the information from the specified location in the open phone device to the specified buffer.

LONG phoneGetData(

HPHONE hPhone,
DWORD dwDataID,
LPVOID lpData,
DWORD dwSize
);
Parameters

hPhone

A handle to the open phone device.

dwDataID

Where in the phone device the buffer is to be uploaded from.

lpData

A pointer to the memory buffer where the data is to be uploaded.

dwSize

The size of the data buffer in bytes.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALDATAID, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Remarks

The function uploads a maximum of dwSize bytes from the phone device into the memory area pointed to by lpData. If dwSize is zero, nothing is copied. The size of each data area is listed in the phone's device capabilities.


phoneGetDevCaps

The phoneGetDevCaps function queries a specified phone device to determine its telephony capabilities.

LONG phoneGetDevCaps(

HPHONEAPP hPhoneApp,
DWORD dwDeviceID,
DWORD dwAPIVersion,
DWORD dwExtVersion,
LPPHONECAPS lpPhoneCaps
);
Parameters

hPhoneApp

The handle to the application's registration with TAPI.

dwDeviceID

The phone device to be queried.

dwAPIVersion

The version number of the Telephony API to be used. The high-order word contains the major version number; the low-order word contains the minor version number. This number is obtained with the function phoneNegotiateAPIVersion.

dwExtVersion

The version number of the service provider-specific extensions to be used. This number is obtained with the function phoneNegotiateExtVersion. It can be left zero if no device-specific extensions are to be used. Otherwise, the high-order word contains the major version number; the low-order word contains the minor version number.

lpPhoneCaps

A pointer to a variably sized structure of type PHONECAPS. Upon successful completion of the request, this structure is filled with phone device capabilities information.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_INVALPOINTER, PHONEERR_BADDEVICEID, PHONEERR_OPERATIONFAILED, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_NOMEM, PHONEERR_STRUCTURETOOSMALL, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODRIVER, PHONEERR_UNINITIALIZED, PHONEERR_NODEVICE.

Remarks

Before using phoneGetDevCaps, the application must negotiate the TAPI version number to use, and optionally, the extension version to use.

TAPI and extension version numbers are those under which TAPI, Telephony DLL, and service provider must operate. If version ranges do not overlap, the application and API or service-provider versions are incompatible and an error is returned.

See Also

PHONECAPS, phoneNegotiateAPIVersion, phoneNegotiateExtVersion


phoneGetDisplay

The phoneGetDisplay function returns the current contents of the specified phone display.

LONG phoneGetDisplay(

HPHONE hPhone,
LPVARSTRING lpDisplay
);
Parameters

hPhone

A handle to the open phone device.

lpDisplay

A pointer to the memory location where the display content is to be stored, of type VARSTRING.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_STRUCTURETOOSMALL, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED, PHONEERR_NOMEM.

Remarks

The lpDisplay memory area should be at least (dwDisplayNumRows * dwDisplayNumColumns) elements in size to receive all of the display information. dwDisplayNumRows and dwDisplayNumColumns are available in the PHONECAPS structure returned by phoneGetDevCaps.

See Also

PHONECAPS, phoneGetDevCaps, VARSTRING


phoneGetGain

The phoneGetGain function returns the gain setting of the microphone of the specified phone's hookswitch device.

LONG phoneGetGain(

HPHONE hPhone,
DWORD dwHookSwitchDev,
LPDWORD lpdwGain
);
Parameters

hPhone

A handle to the open phone device.

dwHookSwitchDev

The hookswitch device whose gain level is queried. Note that dwHookSwitchDev can have only one bit set. This parameter uses the following PHONEHOOKSWITCHDEV_ constants:

PHONEHOOKSWITCHDEV_HANDSET

The phone's handset.

PHONEHOOKSWITCHDEV_SPEAKER

The phone's speakerphone or adjunct.

PHONEHOOKSWITCHDEV_HEADSET

The phone's headset.

lpdwGain

A pointer to a DWORD-sized location containing the current gain setting of the hookswitch microphone component. The dwGain parameter specifies the volume level of the hookswitch device. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of gain settings in this range are service provider specific.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.


phoneGetHookSwitch

The phoneGetHookSwitch function returns the current hookswitch mode of the specified open phone device.

LONG phoneGetHookSwitch(

HPHONE hPhone,
LPDWORD lpdwHookSwitchDevs
);
Parameters

hPhone

A handle to the open phone device.

lpdwHookSwitchDevs

A pointer to a DWORD-sized location to be filled with the mode of the phone's hookswitch devices. If a bit position is FALSE, the corresponding hookswitch device is on-hook; if TRUE, the microphone and/or speaker part of the corresponding hookswitch device is offhook. To find out whether the microphone and/or speaker are enabled, the application can use phoneGetStatus. This parameter uses the following PHONEHOOKSWITCHDEV_ constants:

PHONEHOOKSWITCHDEV_HANDSET

The phone's handset.

PHONEHOOKSWITCHDEV_SPEAKER

The phone's speakerphone or adjunct.

PHONEHOOKSWITCHDEV_HEADSET

The phone's headset.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED.

Remarks

After the hookswitch state of a device changes, and if hookswitch monitoring is enabled, the application is sent a PHONE_STATE message.

See Also

PHONE_STATE, phoneGetStatus


phoneGetIcon

The phoneGetIcon function allows an application to retrieve a service phone device-specific (or provider-specific) icon that can be displayed to the user.

LONG phoneGetIcon(

DWORD dwDeviceID,
LPCSTR lpszDeviceClass,
LPHICON lphIcon
);
Parameters

dwDeviceID

The phone device whose icon is requested.

lpszDeviceClass

A pointer to a NULL-terminated string that identifies a device class name. This device class allows the application to select a specific sub-icon applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest-level icon associated with the phone device rather than a specified media stream device would be selected.

lphIcon

A pointer to a memory location in which the handle to the icon is returned.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_BADDEVICEID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALDEVICECLASS, PHONEERR_UNINITIALIZED, PHONEERR_NOMEM, PHONEERR_NODEVICE.

Remarks

The phoneGetIcon causes the provider to return a handle (in lphIcon) to an icon resource (obtained from LoadIcon) associated with the specified phone. The icon handle will be for a resource associated with the provider; the application must use CopyIcon if it wishes to reference the icon after the provider is unloaded, which is unlikely to happen as long as the application has the phone open.

The lpszDeviceClass parameter allows the provider to return different icons based on the type of service being referenced by the caller. The permitted strings are the same as for phoneGetID. For example, if the phone supports the Comm API, passing "COMM" as lpszDeviceClass causes the provider to return an icon related specifically to the Comm device functions of the service provider. The parameters "tapi/phone", "", or NULL may be used to request the icon for the phone service.

For applications using an API version less than 0x00020000, if the provider does not return an icon (whether because the given device class is invalid or the provider does not support icons), TAPI substitutes a generic Win32 Telephony phone device icon. For applications using API version 0x00020000 or greater, TAPI substitutes the default phone icon only if the lpszDeviceClass parameter is "tapi/phone", "" or NULL. For any other device class, if the given device class is not valid or the provider does not support icons for the class, phoneGetIcon returns PHONEERR_INVALDEVICECLASS.

See Also

phoneGetID


phoneGetID

The phoneGetID function returns a device ID for the given device class associated with the specified phone device.

LONG phoneGetID(

HPHONE hPhone,
LPVARSTRING lpDeviceID,
LPCSTR lpszDeviceClass
);
Parameters

hPhone

A handle to an open phone device.

lpDeviceID

A pointer to a data structure of type VARSTRING where the device ID is returned. Upon successful completion of the request, this location is filled with the device ID. The format of the returned information depends on the method used by the device class (API) for naming devices.

lpszDeviceClass

A pointer to a NULL-terminated string that specifies the device class of the device whose ID is requested. Valid device class strings are those used in the SYSTEM.INI section to identify device classes.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALDEVICECLASS, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONFAILED, PHONEERR_STRUCTURETOOSMALL, PHONEERR_OPERATIONUNAVAIL.

Remarks

The phoneGetID function can be used to retrieve a phone device ID given a phone handle. It can also be used to obtain the device ID of the media device (for device classes such as COM, wave, MIDI, phone, line, or NDIS) associated with the opened phone device. The names of these device class are not case sensitive. This ID can then be used with the appropriate media API to select the corresponding device.

See Device Classes in TAPI for device class names.

A vendor that defines a device-specific media mode also needs to define the corresponding device-specific (proprietary) API to manage devices of the media mode. To avoid collisions on device class names assigned independently by different vendors, a vendor should select a name that uniquely identifies both the vendor and, following it, the media type. For example: "intel/video".

See Also

VARSTRING


phoneGetLamp

The phoneGetLamp function returns the current lamp mode of the specified lamp.

LONG phoneGetLamp(

HPHONE hPhone,
DWORD dwButtonLampID,
LPDWORD lpdwLampMode
);
Parameters

hPhone

A handle to the open phone device.

dwButtonLampID

The ID of the lamp to be queried.

lpdwLampMode

A pointer to a memory location that will hold the lamp mode status of the given lamp. Note that lpdwLampMode can have at most one bit set. This parameter uses the following PHONELAMPMODE_ constants:

PHONELAMPMODE_BROKENFLUTTER

Broken flutter is the superposition of flash and flutter.

PHONELAMPMODE_FLASH

Flash means slow on and off.

PHONELAMPMODE_FLUTTER

Flutter means fast on and off.

PHONELAMPMODE_OFF

The lamp is off.

PHONELAMPMODE_STEADY

The lamp is continuously lit.

PHONELAMPMODE_WINK

The lamp is winking.

PHONELAMPMODE_UNKNOWN

The lamp mode is currently unknown.

PHONELAMPMODE_DUMMY

This value is used to describe a button/lamp position that has no corresponding lamp.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALBUTTONLAMPID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Remarks

Phone sets that have multiple lamps per button should be modeled using multiple button/lamps pairs. Each extra button/lamp pair should use a DUMMY button.


phoneGetMessage

The phoneGetMessage function returns the next TAPI message that is queued for delivery to an application that is using the Event Handle notification mechanism (see phoneInitializeEx for further details).

LONG phoneGetMessage(

HPHONEAPP hPhoneApp,
LPPHONEMESSAGE lpMessage,
DWORD dwTimeout
);
Parameters

hPhoneApp

The handle returned by phoneInitializeEx. The application must have set the PHONEINITIALIZEEXOPTION_USEEVENT option in the dwOptions field of the PHONEINITIALIZEEXPARAMS structure.

lpMessage

A pointer to a PHONEMESSAGE structure. Upon successful return from this function, the structure will contain the next message which had been queued for delivery to the application.

dwTimeout

The time-out interval, in milliseconds. The function returns if the interval elapses, even if no message can be returned. If dwTimeout is zero, the function checks for a queued message and returns immediately. If dwTimeout is INFINITE, the function's time-out interval never elapses.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPOINTER, PHONEERR_NOMEM.

Remarks

If this function has been called with a non-zero timeout and the application calls phoneShutdown on another thread, this function will return immediately with PHONEERR_INVALAPPHANDLE.

If the timeout expires (or was zero) and no message could be fetched from the queue, the function returns with the error PHONEERR_OPERATIONFAILED.

See Also

PHONEINITIALIZEEXPARAMS, PHONEMESSAGE, phoneShutdown


phoneGetRing

The phoneGetRing function enables an application to query the specified open phone device as to its current ring mode.

LONG phoneGetRing(

HPHONE hPhone,
LPDWORD lpdwRingMode,
LPDWORD lpdwVolume
);
Parameters

hPhone

A handle to the open phone device.

lpdwRingMode

The ringing pattern with which the phone is ringing. Zero indicates that the phone is not ringing.

lpdwVolume

The volume level with which the phone is ringing. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service-provider specific.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPHONESTATE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED.

Remarks

The service provider defines the actual audible ringing patterns corresponding to each of phone's ring modes.


phoneGetStatus

The phoneGetStatus function enables an application to query the specified open phone device for its overall status.

LONG phoneGetStatus(

HPHONE hPhone,
LPPHONESTATUS lpPhoneStatus
);
Parameters

hPhone

A handle to the open phone device to be queried.

lpPhoneStatus

A pointer to a variably sized data structure of type PHONESTATUS, which is loaded with the returned information about the phone's status.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_OPERATIONFAILED, PHONEERR_STRUCTURETOOSMALL, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED.

Remarks

An application can use this function to determine the current state of an open phone device. The status information describes information about the phone device's hookswitch devices, ringer, volume, display, and lamps of the open phone.

See Also

PHONESTATUS


phoneGetStatusMessages

The phoneGetStatusMessages function returns which phone-state changes on the specified phone device will generate a callback to the application.

LONG phoneGetStatusMessages(

HPHONE hPhone,
LPDWORD lpdwPhoneStates,
LPDWORD lpdwButtonModes,
LPDWORD lpdwButtonStates
);
Parameters

hPhone

A handle to the open phone device to be monitored.

lpdwPhoneStates

A pointer to a PHONESTATE_ constant. These flags specify the set of phone status changes and events for which the application wishes to receive notification messages. The lpdwPhoneStates parameter can return a value with zero, one, or multiple bits set. Monitoring can be individually enabled and disabled for:

PHONESTATE_OTHER

Phone-status items other than those listed below have changed. The application should check the current phone status to determine which items have changed.

PHONESTATE_CONNECTED

The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked or when the wire connecting the phone to the computer is plugged in while TAPI is active.

PHONESTATE_DISCONNECTED

The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the computer is unplugged while TAPI is active.

PHONESTATE_OWNER

The number of owners for the phone device has changed.

PHONESTATE_MONITORS

The number of monitors for the phone device has changed.

PHONESTATE_DISPLAY

The display of the phone has changed.

PHONESTATE_LAMP

A lamp of the phone has changed.

PHONESTATE_RINGMODE

The ring mode of the phone has changed.

PHONESTATE_RINGVOLUME

The ring volume of the phone has changed.

PHONESTATE_HANDSETHOOKSWITCH

The handset hookswitch state has changed.

PHONESTATE_HANDSETVOLUME

The handset's speaker volume setting has changed.

PHONESTATE_HANDSETGAIN

The handset's microphone gain setting has changed.

PHONESTATE_SPEAKERHOOKSWITCH

The speakerphone's hookswitch state has changed.

PHONESTATE_SPEAKERVOLUME

The speakerphone's speaker volume setting has changed.

PHONESTATE_SPEAKERGAIN

The speakerphone's microphone gain setting state has changed.

PHONESTATE_HEADSETHOOKSWITCH

The headset's hookswitch state has changed.

PHONESTATE_HEADSETVOLUME

The headset's speaker volume setting has changed.

PHONESTATE_HEADSETGAIN

The headset's microphone gain setting has changed.

PHONESTATE_SUSPEND

The application's use of the phone is temporarily suspended.

PHONESTATE_RESUME

The application's use of the phone device is resumed after having been suspended for some time.

PHONESTATE_DEVSPECIFIC

The phone's device-specific information has changed.

PHONESTATE_REINIT

Items have changed in the configuration of phone devices. To become aware of these changes (as with the appearance of new phone devices) the application should reinitialize its use of TAPI. The hDevice parameter of the PHONE_STATE message is left NULL for this state change, as it applies to any of the phones in the system.

PHONESTATE_CAPSCHANGE

Indicates that, due to configuration changes made by the user or other circumstances, one or more of the fields in the PHONECAPS structure have changed. The application should use phoneGetDevCaps to read the updated structure. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will receive PHONE_STATE messages specifying PHONESTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI in order to obtain the updated information.

PHONESTATE_REMOVED

Indicates that the device is being removed from the system by the service provider (most likely through user action, via a control panel or similar utility). A PHONE_STATE message with this value will normally be immediately followed by a PHONE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized will result in PHONEERR_NODEVICE being returned to the application. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will not receive any notification.

lpdwButtonModes

A pointer to a . These flags specify the set of phone-button modes for which the application wishes to receive notification messages. The lpdwButtonModes parameter can return a value with zero, one, or multiple bits set. This parameter uses the following PHONEBUTTONMODE_ constants:

PHONEBUTTONMODE_CALL

The button is assigned to a call appearance.

PHONEBUTTONMODE_FEATURE

The button is assigned to requesting features from the switch, such as hold, conference, and transfer.

PHONEBUTTONMODE_KEYPAD

The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.

PHONEBUTTONMODE_LOCAL

The button is a local function button, such as mute or volume control.

PHONEBUTTONMODE_DISPLAY

The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.

lpdwButtonStates

A pointer to a DWORD-sized location that contains flags specifying the set of phone button state changes for which the application wishes to receive notification messages. The lpdwButtonStates field can return a value with zero, one or multiple bits set. This parameter uses the following PHONEBUTTONSTATE_ constants:

PHONEBUTTONSTATE_UP

The button is in the "up" state.

PHONEBUTTONSTATE_DOWN

The button is in the "down" state (pressed down).

PHONEBUTTONSTATE_UNKNOWN

Indicates that the up or down state of the button is not known at this time, but may become known at a future time.

PHONEBUTTONSTATE_UNAVAIL

Indicates that the up or down state of the button is not known to the service provider, and will not become known at a future time.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_OPERATIONFAILED, PHONEERR_UNINITIALIZED.

Remarks

An application can use phoneGetStatusMessages to query the generation of the corresponding messages. Message generation can be controlled by phoneSetStatusMessages. All phone status messages are disabled by default.

See Also

PHONE_CLOSE, PHONE_STATE, PHONECAPS, phoneGetDevCaps, phoneSetStatusMessages


phoneGetVolume

The phoneGetVolume function returns the volume setting of the specified phone's hookswitch device.

LONG phoneGetVolume(

HPHONE hPhone,
DWORD dwHookSwitchDev,
LPDWORD lpdwVolume
);
Parameters

hPhone

A handle to the open phone device.

dwHookSwitchDev

A single hookswitch device whose volume level is queried. This parameter uses the following PHONEHOOKSWITCHDEV_ constants:

PHONEHOOKSWITCHDEV_HANDSET

This is the phone's handset.

PHONEHOOKSWITCHDEV_SPEAKER

This is the phone's speakerphone or adjunct.

PHONEHOOKSWITCHDEV_HEADSET

This is the phone's headset.

lpdwVolume

A pointer to a DWORD-sized location containing the current volume setting of the hookswitch device. dwVolume specifies the volume level of the hookswitch device. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service-provider specific.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPHONESTATE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.


phoneInitialize

The phoneInitialize function is obsolete. It continues to be exported by TAPI.DLL and TAPI32.DLL for backward compatibility with applications using API versions 0x00010003 and 0x00010004.

Applications using API version 0x00020000 or greater must use phoneInitializeEx instead.


phoneInitializeEx

The phoneInitializeEx function initializes the application's use of TAPI for subsequent use of the phone abstraction. It registers the application's specified notification mechanism and returns the number of phone devices available to the application. A phone device is any device that provides an implementation for the phone-prefixed functions in the Telephony API.

LONG phoneInitializeEx(

LPHPHONEAPP lphPhoneApp,
HINSTANCE hInstance,
PHONECALLBACK lpfnCallback,
LPCSTR lpszFriendlyAppName,
LPDWORD lpdwNumDevs,
LPDWORD lpdwAPIVersion,
LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams
);
Parameters

lphPhoneApp

A pointer to a location that is filled with the application's usage handle for TAPI.

hInstance

The instance handle of the client application or DLL. The application or DLL may pass NULL for this parameter, in which case TAPI will use the module handle of the root executable of the process.

lpfnCallback

The address of a callback function that is invoked to determine status and events on the line device, addresses, or calls, when the application is using the "hidden window" method of event notification (for more information see phoneCallbackFunc). This parameter is ignored and should be set to NULL when the application chooses to use the "event handle" or "completion port" event notification mechanisms.

lpszFriendlyAppName

A pointer to a NULL-terminated ASCII string that contains only displayable ASCII characters. If this parameter is not NULL, it contains an application-supplied name of the application. This name is provided in the PHONESTATUS structure to indicate, in a user-friendly way, which application has ownership of the phone device. If lpszFriendlyAppName is NULL, the application's module file name is used instead (as returned by the Windows API GetModuleFileName).

lpdwNumDevs

A pointer to a DWORD-sized location. Upon successful completion of this request, this location is filled with the number of phone devices available to the application.

lpdwAPIVersion

A pointer to a DWORD-sized location. The application must initialize this DWORD, before calling this function, to the highest API version it is designed to support (for example, the same value it would pass into dwAPIHighVersion parameter of phoneNegotiateAPIVersion). Artificially high values must not be used; the value must be accurately set (for this release, to 0x00020000). TAPI will translate any newer messages or structures into values or formats supported by the application's version. Upon successful completion of this request, this location is filled with the highest API version supported by TAPI (for this release, 0x00020000), thereby allowing the application to detect and adapt to having been installed on a system with an older version of TAPI.

lpPhoneInitializeExParams

A pointer to a structure of type PHONEINITIALIZEEXPARAMS containing additional parameters used to establish the association between the application and TAPI (specifically, the application's selected event notification mechanism and associated parameters).

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_INVALPARAM.

Remarks

Applications must select one of three mechanisms by which TAPI notifies the application of telephony events: Hidden Window, Event Handle, or Completion Port.

The Hidden Window mechanism is selected by specifying PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW in the dwOptions field in the PHONEINITIALIZEEXPARAMS structure. In this mechanism (which is the only mechanism available to TAPI 1.x applications), TAPI creates a window in the context of the application during the phoneInitializeEx function, and subclasses the window so that all messages posted to it are handled by a WNDPROC in TAPI itself. When TAPI has a message to deliver to the application, TAPI posts a message to the hidden window. When the message is received (which can happen only when the application calls the Windows GetMessage API), Windows switches the process context to that of the application and invokes the WNDPROC in TAPI. TAPI then delivers the message to the application by calling the PhoneCallbackProc, a pointer to which the application provided as a parameter in its call to phoneInitializeEx (or phoneInitialize, for TAPI 1.3 and 1.4 applications). This mechanism requires the application to have a message queue (which is not desirable for service processes) and to service that queue regularly to avoid delaying processing of telephony events. The hidden window is destroyed by TAPI during the phoneShutdown function.

The Event Handle mechanism is selected by specifying PHONEINITIALIZEEXOPTION_USEEVENT in the dwOptions field in the PHONEINITIALIZEEXPARAMS structure. In this mechanism, TAPI creates an event object on behalf of the application, and returns a handle to the object in the hEvent field in PHONEINITIALIZEEXPARAMS. The application must not manipulate this event in any manner (for example, must not call SetEvent, ResetEvent, CloseHandle, and so on) or undefined behavior will result; the application may only wait on this event using functions such as WaitForSingleObject or MsgWaitForMultipleObjects. TAPI will signal this event whenever a telephony event notification is pending for the application; the application must call phoneGetMessage to fetch the contents of the message. The event is reset by TAPI when no events are pending. The event handle is closed and the event object destroyed by TAPI during the phoneShutdown function. The application is not required to wait on the event handle that is created; the application could choose instead to call phoneGetMessage and have it block waiting for a message to be queued.

The Completion Port mechanism is selected by specifying PHONEINITIALIZEEXOPTION_USECOMPLETION PORT in the dwOptions field in the PHONEINITIALIZEEXPARAMS structure. In this mechanism, whenever a telephony event needs to be sent to the application, TAPI will send it to the application using PostQueuedCompletionStatus to the completion port that the application specified in the hCompletionPort field in PHONEINITIALIZEEXPARAMS, tagged with the completion key that the application specified in the dwCompletionKey field in PHONEINITIALIZEEXPARAMS. The application must have previously created the completion port using CreateIoCompletionPort. The applications retrieves events using GetQueuedCompletionStatus. Upon return from GetQueuedCompletionStatus, the application will have the specified dwCompletionKey written to the DWORD pointed to by the lpCompletionKey parameter, and a pointer to a PHONEMESSAGE structure returned to the location pointed to by lpOverlapped. After the application has processed the event, it is the application's responsibility to call LocalFree to release the memory used to contain the PHONEMESSAGE structure. Because the application created the completion port (thereby allowing it to be shared for other purposes), the application must close it; the application must not close the completion port until after calling phoneShutdown.

When a multithreaded application is using the Event Handle mechanism and more than one thread is waiting on the handle, or the Completion Port notification mechanism and more than one thread is waiting on the port, it is possible for telephony events to be processed out of sequence. This is not due to the sequence of delivery of events from TAPI, but would be caused by the time slicing of threads or the execution of threads on separate processors.

If PHONEERR_REINIT is returned and TAPI reinitialization has been requested, for example as a result of adding or removing a Telephony service provider, then phoneInitializeEx requests are rejected with this error until the last application shuts down its usage of the API (using phoneShutdown), at which time the new configuration becomes effective and applications are once again permitted to call phoneInitializeEx.

If the PHONEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.

The application can refer to individual phone devices by using phone device IDs that range from zero to dwNumDevs minus one. An application should not assume that these phone devices are capable of any particular TAPI function without first querying their device capabilities by phoneGetDevCaps.

For information about the listing of service dependencies, see Service Dependencies.

See Also

phoneCallbackFunc, phoneGetDevCaps, phoneGetMessage, PHONEINITIALIZEEXPARAMS, PHONEMESSAGE, phoneNegotiateAPIVersion, phoneShutdown, PHONESTATUS


phoneCallbackFunc

The phoneCallbackFunc function is a placeholder for the application-supplied function name.

VOID FAR PASCAL phoneCallbackFunc(

HANDLE hDevice,
DWORD dwMsg,
DWORD dwCallbackInstance,
DWORD dwParam1,
DWORD dwParam2,
DWORD dwParam3
);
Parameters

hDevice

A handle to a phone device associated with the callback.

dwMsg

A line or call device message.

dwCallbackInstance

Callback instance data passed back to the application in the callback. This DWORD is not interpreted by TAPI.

dwParam1

A parameter for the message.

dwParam2

A parameter for the message.

dwParam3

A parameter for the message.

Remarks

For more information about the parameters passed to this callback function, see Messages later in this section.

All callbacks occur in the application's context. The callback function must reside in a dynamic-link library (DLL) or application module and be exported in the module-definition file.


phoneNegotiateAPIVersion

The phoneNegotiateAPIVersion allows an application to negotiate an API version to use for the specified phone device.

LONG phoneNegotiateAPIVersion(

HPHONEAPP hPhoneApp,
DWORD dwDeviceID,
DWORD dwAPILowVersion,
DWORD dwAPIHighVersion,
LPDWORD lpdwAPIVersion,
LPPHONEEXTENSIONID lpExtensionID
);
Parameters

hPhoneApp

The handle to the application's registration with TAPI.

dwDeviceID

The phone device to be queried.

dwAPILowVersion

The least recent API version the application is compliant with. The high-order word is the major version number, the low-order word is the minor version number.

dwAPIHighVersion

The most recent API version the application is compliant with. The high-order word is the major version number, the low-order word is the minor version number.

lpdwAPIVersion

A pointer to a DWORD-sized location that contains the API version number that was negotiated. If negotiation is successful, this number will be in the range dwAPILowVersion and dwAPIHighVersion.

lpExtensionID

A pointer to a structure of type PHONEEXTENSIONID. If the service provider for the specified dwDeviceID supports provider-specific extensions, this structure is filled with the extension ID of these extensions when negotiation is successful. This structure contains all zeros if the line provides no extensions. An application can ignore the returned parameter if it does not use extensions.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_BADDEVICEID, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NODRIVER, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_UNINITIALIZED, PHONEERR_NODEVICE.

Remarks

The phoneNegotiateAPIVersion function is used to negotiate the API version number to use with the specified phone device. It returns the extension ID supported by the phone device; zeros if no extensions are provided.

If the application wants to use the extensions defined by the returned Extension ID, it must call phoneNegotiateExtVersion to negotiate the extension version to use.

Use phoneInitializeEx to determine the number of phone devices present in the system. The device ID specified by dwDeviceID varies from zero to one less than the number of phone devices present.

The API version number negotiated is that under which TAPI can operate. If version ranges do not overlap, the application, API, or service-provider versions are incompatible and an error is returned.

See Also

PHONEEXTENSIONID, phoneInitializeEx, phoneNegotiateExtVersion


phoneNegotiateExtVersion

The phoneNegotiateExtVersion function allows an application to negotiate an extension version to use with the specified phone device. This operation need not be called if the application does not support extensions.

LONG phoneNegotiateExtVersion(

HPHONEAPP hPhoneApp,
DWORD dwDeviceID,
DWORD dwAPIVersion,
DWORD dwExtLowVersion,
DWORD dwExtHighVersion,
LPDWORD lpdwExtVersion
);
Parameters

hPhoneApp

The handle to the application's registration with TAPI.

dwDeviceID

The phone device to be queried.

dwAPIVersion

The API version number that was negotiated for the specified phone device using phoneNegotiateAPIVersion.

dwExtLowVersion

The least recent extension version of the Extension ID returned by phoneNegotiateAPIVersion that the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.

dwExtHighVersion

The most recent extension version of the Extension ID returned by phoneNegotiateAPIVersion that the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.

lpdwExtVersion

A pointer to a DWORD-sized location that contains the extension version number that was negotiated. If negotiation is successful, this number will be in the range dwExtLowVersion and dwExtHighVersion.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_BADDEVICEID, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NODRIVER, PHONEERR_NOMEM, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_UNINITIALIZED, PHONEERR_INVALPOINTER, PHONEERR_NODEVICE.

Remarks

The function phoneNegotiateAPIVersion is used to negotiate the API version number to use. It returns the extension ID supported by the phone device, or zeros if no extensions are provided.

If the application wants to use the extensions defined by the returned Extension ID, it must call phoneNegotiateExtVersion to negotiate the extension version to use.

Use phoneInitializeEx to determine the number of phone devices present in the system. The device ID specified by dwDeviceID varies from zero to one less than the number of phone devices present.

The extension version number negotiated is that under which the application and service provider must both operate. If version ranges do not overlap, the application and service-provider versions are incompatible and an error is returned.

See Also

phoneInitializeEx, phoneNegotiateAPIVersion


phoneOpen

The phoneOpen function opens the specified phone device. A phone device can be opened using either owner privilege or monitor privilege. An application that opens the phone with owner privilege can control the phone's lamps, display, ringer, and hookswitch or hookswitches. An application that opens the phone device with monitor privilege is notified only about events that occur at the phone, such as hookswitch changes or button presses. Ownership of a phone device is exclusive. In other words, only one application can have a phone device opened with owner privilege at a time. The phone device can, however, be opened multiple times with monitor privilege.

LONG phoneOpen(

HPHONEAPP hPhoneApp,
DWORD dwDeviceID,
LPHPHONE lphPhone,
DWORD dwAPIVersion,
DWORD dwExtVersion,
DWORD dwCallbackInstance,
DWORD dwPrivilege
);
Parameters

hPhoneApp

A handle to the application's registration with TAPI.

dwDeviceID

The phone device to be opened.

lphPhone

A pointer to an HPHONE handle, which identifies the open phone device. Use this handle to identify the device when invoking other phone control functions.

dwAPIVersion

The API version number under which the application and Telephony API have agreed to operate. This number is obtained from phoneNegotiateAPIVersion.

dwExtVersion

The extension version number under which the application and the service provider agree to operate. This number is zero if the application does not use any extensions. This number is obtained from phoneNegotiateExtVersion.

dwCallbackInstance

User instance data passed back to the application with each message. This parameter is not interpreted by the Telephony API.

dwPrivilege

The privilege requested. The dwPrivilege parameter can have only one bit set. This parameter uses the following PHONEPRIVILEGE_ constants:

PHONEPRIVILEGE_MONITOR

An application that opens a phone device with this privilege is informed about events and state changes occurring on the phone. The application cannot invoke any operations on the phone device that would change its state.

PHONEPRIVILEGE_OWNER

An application that opens a phone device in this mode is allowed to change the state of the lamps, ringer, display, and hookswitch devices of the phone. Having owner privilege to a phone device automatically includes monitor privilege as well.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_ALLOCATED, PHONEERR_NODRIVER, PHONEERR_BADDEVICEID, PHONEERR_NOMEM, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_OPERATIONFAILED, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALAPPHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED, PHONEERR_INVALPRIVILEGE, PHONEERR_REINIT, PHONEERR_INUSE, PHONEERR_NODEVICE, PHONEERR_INIFILECORRUPT.

Remarks

When opening a phone device with monitor privileges, the application is sent messages when events occur that change the status of the phone. Messages sent to the application include PHONE_BUTTON and PHONE_STATE. The latter provides an indication of the phone's status item that has changed.

When opening a phone with owner privilege, the phone device can be manipulated in ways that affect the state of the phone device. An application should only open a phone using owner privilege if it actively wants to manipulate the phone device, and it should close the phone device when done to allow other applications to control the phone.

When an application opens a phone device, it must specify the negotiated API version and, if it wants to use the phone's extensions, the phone's device-specific extension version. This version number should have been obtained with the function phoneNegotiateAPIVersion and phoneNegotiateExtVersion. Version numbering allows the mix and match of different application versions with different API versions and service-provider versions.

See Also

PHONE_BUTTON, PHONE_STATE, phoneNegotiateAPIVersion, phoneNegotiateExtVersion


phoneSetButtonInfo

The phoneSetButtonInfo function sets information about the specified button on the specified phone.

LONG phoneSetButtonInfo(

HPHONE hPhone,
DWORD dwButtonLampID,
LPPHONEBUTTONINFO const lpButtonInfo
);
Parameters

hPhone

A handle to the open phone device. The application must be the owner of the phone device.

dwButtonLampID

A button on the phone device.

lpButtonInfo

A pointer to a variably sized structure of type PHONEBUTTONINFO. This data structure describes the mode, the function, and provides additional descriptive text about the button.

Return Values

Returns a positive request ID if the function will be completed asynchronously or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALBUTTONLAMPID, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONEHANDLE, PHONEERR_STRUCTURETOOSMALL, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED, PHONEERR_NOTOWNER, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_RESOURCEUNAVAIL.

See Also

PHONE_REPLY, PHONEBUTTONINFO


phoneSetData

The phoneSetData function downloads the information in the specified buffer to the opened phone device at the selected data ID.

LONG phoneSetData(

HPHONE hPhone,
DWORD dwDataID,
LPVOID const lpData,
DWORD dwSize
);
Parameters

hPhone

A handle to the open phone device. The application must be the owner of the phone.

dwDataID

Where in the phone device the buffer is to be downloaded.

lpData

A pointer to the memory location where the data is to be downloaded from.

dwSize

The size of the buffer in bytes.

Return Values

Returns a positive request ID if the function will be completed asynchronously or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOTOWNER, PHONEERR_NOMEM, PHONEERR_INVALDATAID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED.

Remarks

The phoneSetData function downloads a maximum of dwSize bytes from lpData to the phone device. The format of the data, its meaning to the phone device, and the meaning of the data ID are service-provider specific. The data in the buffer or the selection of a data ID may act as commands to the phone device.

See Also

PHONE_REPLY


phoneSetDisplay

The phoneSetDisplay function causes the specified string to be displayed on the specified open phone device.

LONG phoneSetDisplay(

HPHONE hPhone,
DWORD dwRow,
DWORD dwColumn,
LPCSTR lpsDisplay,
DWORD dwSize
);
Parameters

hPhone

A handle to the open phone device. The application must be the owner of the phone.

dwRow

The row on the display where the new text is to be displayed.

dwColumn

The column position on the display where the new text is to be displayed.

lpsDisplay

A pointer to the memory location where the display content is stored. The display information must have the format specified in the dwStringFormat field of the phone's device capabilities.

dwSize

The size in bytes of the information pointed to by lpsDisplay.

Return Values

Returns a positive request ID if the function will be completed asynchronously or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOTOWNER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_UNINITIALIZED, PHONEERR_INVALPOINTER, PHONEERR_NOMEM, PHONEERR_INVALPARAM, PHONEERR_RESOURCEUNAVAIL.

Remarks

The specified display information is written to the phone's display, starting at the specified positions. This operation overwrites previously displayed information. If the amount of information exceeds the size of the display, the information will be truncated. The amount of information that can be displayed is at most (dwNumRows * dwNumColumns) elements in size. dwNumRows and dwNumColumns are available in the PHONECAPS structure, which is returned by phoneGetDevCaps; they are zero-based.

See Also

PHONE_REPLY, PHONECAPS, phoneGetDevCaps


phoneSetGain

The phoneSetGain function sets the gain of the microphone of the specified hookswitch device to the specified gain level.

LONG phoneSetGain(

HPHONE hPhone,
DWORD dwHookSwitchDev,
DWORD dwGain
);
Parameters

hPhone

A handle to the open phone device. The application must be the owner of the phone.

dwHookSwitchDev

The hookswitch device whose microphone's gain is to be set. The dwHookswitchDev parameter can only have a single bit set. This parameter uses the following PHONEHOOKSWITCHDEV_ constants:

PHONEHOOKSWITCHDEV_HANDSET

The phone's handset.

PHONEHOOKSWITCHDEV_SPEAKER

The phone's speakerphone or adjunct.

PHONEHOOKSWITCHDEV_HEADSET

The phone's headset.

dwGain

A pointer to a DWORD-sized location containing the current gain setting of the device. The dwGain parameter specifies the gain level of the hookswitch device. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of gain settings in this range are service-provider specific. A value for dwGain that is out of range is set to the nearest value in the range.

Return Values

Returns a positive request ID if the function will be completed asynchronously or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_NOTOWNER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

See Also

PHONE_REPLY


phoneSetHookSwitch

The phoneSetHookSwitch function sets the hook state of the specified open phone's hookswitch devices to the specified mode. Only the hookswitch state of the hookswitch devices listed is affected.

LONG phoneSetHookSwitch(

HPHONE hPhone,
DWORD dwHookSwitchDevs,
DWORD dwHookSwitchMode
);
Parameters

hPhone

A handle to the open phone device. The application must be the owner of the phone.

dwHookSwitchDevs

The device or devices whose hookswitch mode is to be set. This parameter uses the following PHONEHOOKSWITCHDEV_ constants:

PHONEHOOKSWITCHDEV_HANDSET

The phone's handset.

PHONEHOOKSWITCHDEV_SPEAKER

The phone's speakerphone or adjunct.

PHONEHOOKSWITCHDEV_HEADSET

The phone's headset.

dwHookSwitchMode

The hookswitch mode to set. The dwHookSwitchMode parameter can have only a single bit set. This parameter uses the following PHONEHOOKSWITCHMODE_ constants:

PHONEHOOKSWITCHMODE_ONHOOK

The device's microphone and speaker are both onhook.

PHONEHOOKSWITCHMODE_MIC

The device's microphone is active, the speaker is mute.

PHONEHOOKSWITCHMODE_SPEAKER

The device's speaker is active, the microphone is mute.

PHONEHOOKSWITCHMODE_MICSPEAKER

The device's microphone and speaker are both active.

Return Values

Returns a positive request ID if the function will be completed asynchronously or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOTOWNER, PHONEERR_NOMEM, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALHOOKSWITCHMODE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_UNINITIALIZED.

Remarks

The hookswitch mode is the same for all devices specified. If different settings are desired, this function can be invoked multiple times with a different set of parameters. A PHONE_STATE message is sent to the application after the hookswitch state has changed.

See Also

PHONE_REPLY, PHONE_STATE


phoneSetLamp

The phoneSetLamp function causes the specified lamp to be lit on the specified open phone device in the specified lamp mode.

LONG phoneSetLamp(

HPHONE hPhone,
DWORD dwButtonLampID,
DWORD dwLampMode
);
Parameters

hPhone

A handle to the open phone device. The application must be the owner of the phone.

dwButtonLampID

The button whose lamp is to be lit.

dwLampMode

How the lamp is to be lit. The dwLampMode parameter can have only a single bit set. This parameter uses the following PHONELAMPMODE_ constants:

PHONELAMPMODE_BROKENFLUTTER

Broken flutter is the superposition of flash and flutter.

PHONELAMPMODE_FLASH

Flash means slow on and off.

PHONELAMPMODE_FLUTTER

Flutter means fast on and off.

PHONELAMPMODE_OFF

The lamp is off.

PHONELAMPMODE_STEADY

The lamp is continuously lit.

PHONELAMPMODE_WINK

The lamp is winking.

PHONELAMPMODE_DUMMY

This value is used to describe a button/lamp position that has no corresponding lamp.

Return Values

Returns a positive request ID if the function will be completed asynchronously or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOTOWNER, PHONEERR_NOMEM, PHONEERR_INVALBUTTONLAMPID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALLAMPMODE, PHONEERR_UNINITIALIZED.

See Also

PHONE_REPLY


phoneSetRing

The phoneSetRing function rings the specified open phone device using the specified ring mode and volume.

LONG phoneSetRing(

HPHONE hPhone,
DWORD dwRingMode,
DWORD dwVolume
);
Parameters

hPhone

A handle to the open phone device. The application must be the owner of the phone device.

dwRingMode

The ringing pattern with which to ring the phone. This parameter must be within the range of 0 to the value of the dwNumRingModes field in the PHONECAPS structure. If dwNumRingModes is 0, the ring mode of the phone cannot be controlled; if dwNumRingModes is 1, a value of 0 for dwRingMode indicates that the phone should not be rung (silence), and other values from 1 to dwNumRingModes are valid ring modes for the phone device.

dwVolume

The volume level with which the phone is ringing. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service-provider specific. A value for dwVolume that is out of range is set to the nearest value in the range.

Return Values

Returns a positive request ID if the function will be completed asynchronously or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_NOTOWNER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALRINGMODE, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Remarks

The service provider defines the actual audible ringing patterns corresponding to each of the phone's ring modes.

See Also

PHONE_REPLY, PHONECAPS


phoneSetStatusMessages

The phoneSetStatusMessages function enables an application to monitor the specified phone device for selected status events.

LONG phoneSetStatusMessages(

HPHONE hPhone,
DWORD dwPhoneStates,
DWORD dwButtonModes,
DWORD dwButtonStates
);
Parameters

hPhone

A handle to the open phone device to be monitored.

dwPhoneStates

These flags specify the set of phone status changes and events for which the application wishes to receive notification messages. This parameter can have zero, one, or more bits set. This parameter uses the following PHONESTATE_ constants:

PHONESTATE_OTHER

Phone-status items other than those listed below have changed. The application should check the current phone status to determine which items have changed.

PHONESTATE_CONNECTED

The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked or when the wire connecting the phone to the PC is plugged in while TAPI is active.

PHONESTATE_DISCONNECTED

The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the PC is unplugged while TAPI is active.

PHONESTATE_OWNER

The number of owners for the phone device has changed.

PHONESTATE_MONITORS

The number of monitors for the phone device has changed.

PHONESTATE_DISPLAY

The display of the phone has changed.

PHONESTATE_LAMP

A lamp of the phone has changed.

PHONESTATE_RINGMODE

The ring mode of the phone has changed.

PHONESTATE_RINGVOLUME

The ring volume of the phone has changed.

PHONESTATE_HANDSETHOOKSWITCH

The handset hookswitch state has changed.

PHONESTATE_HANDSETVOLUME

The handset's speaker volume setting has changed.

PHONESTATE_HANDSETGAIN

The handset's microphone gain setting has changed.

PHONESTATE_SPEAKERHOOKSWITCH

The speakerphone's hookswitch state has changed.

PHONESTATE_SPEAKERVOLUME

The speakerphone's speaker volume setting has changed.

PHONESTATE_SPEAKERGAIN

The speakerphone's microphone gain setting state has changed.

PHONESTATE_HEADSETHOOKSWITCH

The headset's hookswitch state has changed.

PHONESTATE_HEADSETVOLUME

The headset's speaker volume setting has changed.

PHONESTATE_HEADSETGAIN

The headset's microphone gain setting has changed.

PHONESTATE_SUSPEND

The application's use of the phone is temporarily suspended.

PHONESTATE_RESUME

The application's use of the phone device is resumed after having been suspended for some time.

PHONESTATE_DEVSPECIFIC

The phone's device-specific information has changed.

PHONESTATE_REINIT

Items have changed in the configuration of phone devices. To become aware of these changes (as with the appearance of new phone devices) the application should reinitialize its use of TAPI. New phoneInitialize, phoneInitializeEx and phoneOpen requests are denied until applications have shut down their usage of TAPI. The hDevice parameter of the PHONE_STATE message is left NULL for this state change, because it applies to any of the lines in the system. Because of the critical nature of PHONESTATE_REINIT, such messages cannot be masked, so the setting of this bit is ignored and the messages are always delivered to the application.

PHONESTATE_CAPSCHANGE

Indicates that, due to configuration changes made by the user or other circumstances, one or more of the fields in the PHONECAPS structure have changed. The application should use phoneGetDevCaps to read the updated structure. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 0x0001004 or above; applications negotiating a previous API version will receive PHONE_STATE messages specifying PHONESTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI in order to obtain the updated information.

PHONESTATE_REMOVED

Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A PHONE_STATE message with this value will normally be immediately followed by a PHONE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized will result in PHONEERR_NODEVICE being returned to the application. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will not receive any notification.

dwButtonModes

The set of phone-button modes for which the application wishes to receive notification messages. This parameter can have zero, one, or more bits set. This parameter uses the following PHONEBUTTONMODE_ constants:

PHONEBUTTONMODE_CALL

The button is assigned to a call appearance.

PHONEBUTTONMODE_FEATURE

The button is assigned to requesting features from the switch, such as hold, conference, and transfer.

PHONEBUTTONMODE_KEYPAD

The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.

PHONEBUTTONMODE_LOCAL

The button is a local function button, such as mute or volume control.

PHONEBUTTONMODE_DISPLAY

The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.

dwButtonStates

The set of phone-button state changes for which the application wants to receive notification messages. If the dwButtonModes parameter is 0, dwButtonStates is ignored. If dwButtonModes has one or more bits set, this parameter must also have at least one bit set. This parameter uses the following PHONEBUTTONSTATE_ constants:

PHONEBUTTONSTATE_UP

The button is in the "up" state.

PHONEBUTTONSTATE_DOWN

The button is in the "down" state (pressed down).

PHONEBUTTONSTATE_UNKNOWN

Indicates that the up or down state of the button is not known at this time, but may become known at a future time.

PHONEBUTTONSTATE_UNAVAIL

Indicates that the up or down state of the button is not known to the service provider, and will not become known at a future time.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPHONESTATE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALBUTTONMODE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALBUTTONSTATE, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Remarks

An application can use the phoneSetStatusMessages function to enable or disable the generation of the corresponding messages. All phone status messages are disabled by default.

See Also

PHONE_CLOSE, PHONE_STATE, PHONECAPS, phoneGetDevCaps, phoneInitialize, phoneInitializeEx, phoneOpen


phoneSetVolume

The phoneSetVolume sets the volume of the speaker component of the specified hookswitch device to the specified level.

LONG phoneSetVolume(

HPHONE hPhone,
DWORD dwHookSwitchDev,
DWORD dwVolume
);
Parameters

hPhone

A handle to the open phone device. The application must be the owner of the phone.

dwHookSwitchDev

The hookswitch device whose speaker's volume is to be set.

PHONEHOOKSWITCHDEV_HANDSET

The phone's handset.

PHONEHOOKSWITCHDEV_SPEAKER

The phone's speakerphone or adjunct.

PHONEHOOKSWITCHDEV_HEADSET

The phone's headset.

dwVolume

The current volume setting of the device. The dwVolume parameter specifies the volume level of the hookswitch device. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service-provider specific. A value for dwVolume that is out of range is set to the nearest value in the range.

Return Values

Returns a positive request ID if the function will be completed asynchronously or a negative error number if an error has occurred. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function is successful or it is a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_NOTOWNER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

See Also

PHONE_REPLY


phoneShutdown

The phoneShutdown function shuts down the application's usage of TAPI's phone abstraction.

LONG phoneShutdown(

HPHONEAPP hPhoneApp
);
Parameters

hPhoneApp

The application's usage handle for TAPI.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_NOMEM, PHONEERR_UNINITIALIZED, PHONEERR_RESOURCEUNAVAIL.

Remarks

If this function is called when the application has open phone devices. These devices will be closed.


Assisted Telephony Functions

The functions in this section are used by Assisted Telephony.


tapiRequestMakeCall

The tapiRequestMakeCall function requests the establishment of a voice call. A call-manager application is responsible for establishing the call on behalf of the requesting application, which is then controlled by the user's call-manager application.

LONG tapiRequestMakeCall(

LPCSTR lpszDestAddress,
LPCSTR lpszAppName,
LPCSTR lpszCalledParty,
LPCSTR lpszComment
);
Parameters

lpszDestAddress

A pointer to a memory location where the NULL-terminated destination address of the call request is located. The address can use the canonical address format (address formats are discussed in Line Devices Overview) or the dialable address format. Validity of the specified address is not checked by this operation. The maximum length of the address is TAPIMAXDESTADDRESSSIZE characters, which includes the NULL terminator.

lpszAppName

A pointer to a memory location where the ASCII NULL-terminated user-friendly application name of the call request is located. This pointer may be left NULL if the application does not wish to supply an application name. The maximum length of the address is TAPIMAXAPPNAMESIZE characters, which includes the NULL terminator. Longer strings are truncated.

lpszCalledParty

A pointer to a memory location where the ASCII NULL-terminated called party name for the called party of the call is located. This pointer may be left NULL if the application does not wish to supply this information. The maximum length of the string is TAPIMAXCALLEDPARTYSIZE characters, which includes the NULL terminator. Longer strings are truncated.

lpszComment

A pointer to a memory location where the ASCII NULL-terminated comment about the call is located. This pointer may be left NULL if the application does not wish to supply a comment. The maximum length of the address is TAPIMAXCOMMENTSIZE characters, which includes the NULL terminator. Longer strings are truncated.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible error return value are:

TAPIERR_NOREQUESTRECIPIENT, TAPIERR_INVALDESTADDRESS, TAPIERR_REQUESTQUEUEFULL, TAPIERR_INVALPOINTER.

Remarks

A telephony-enabled application can request that a call be placed on its behalf by invoking tapiRequestMakeCall, providing only the destination address for the call. This request is forwarded to the user's call-control application, which places the call on behalf of the original application. A default call-control application is provided as part of Win32 Telephony. Users can replace this with a call-control application of their choice.

Invoking tapiRequestMakeCall when no call control application is running returns the TAPIERR_NOREQUESTRECIPIENT error indication. If the call control application is not running, TAPI will attempt to launch the highest-priority call control application (which is listed for RequestMakeCall in the registry ). Invoking this function when the Assisted TAPI request queue is full returns the TAPIERR_REQUESTQUEUEFULL error.


tapiRequestMediaCall

The tapiRequestMediaCall function is nonfunctional in Win32-based applications and obsolete for all classes of Windows-based applications. It should not be used.


tapiGetLocationInfo

The tapiGetLocationInfo function returns the country code and city (area) code which the user has set in the current location parameters in the Telephony control panel. The application may use this information to assist the user in forming proper canonical telephone numbers, such as by offering these as defaults when new numbers are entered in a phone book entry or database record.

LONG tapiGetLocationInfo(

LPCSTR lpszCountryCode,
LPCSTR lpszCityCode
);
Parameters

lpszCountryCode

A pointer to a memory location where a NULL-terminated ASCII string specifying the country code for the current location is to be returned. The application should allocate at least 8 bytes of storage at this location to hold the string (TAPI will not return more than 8 bytes, including the terminating NULL). An empty string (\0) will be returned if the country code has not been set for the current location.

lpszCityCode

A pointer to a memory location where a NULL-terminated ASCII string specifying the city (area) code for the current location is to be returned. The application should allocate at least 8 bytes of storage at this location to hold the string (TAPI will not return more than 8 bytes, including the terminating NULL). An empty string (\0) will be returned if the city code has not been set for the current location.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are TAPIERR_REQUESTFAILED.


tapiRequestDrop

The tapiRequestDrop function is nonfunctional in Win32 -based applications and obsolete for all classes of Windows-based applications. It should not be used.


Messages

This section contains the reference for line device, phone device, and assisted telephony messages.


Line Device Messages

This section contains a list of the messages in the Telephony API. Messages are used to notify the application of the occurrence of asynchronous events. All of these messages are sent to the application via the message notification mechanism the applicaiton specified in lineInitializeEx.

The message always contains a handle to the relevant object (phone, line, or call). The application can determine the type of the handle from the message type.

Certain messages are used to notify the application about a change in an object's status. These messages provide the object handle and give an indication of which status item has changed. The application can call the appropriate "get status" function of the object to obtain the object's full status.

When an event occurs, messages may be sent to zero, one, or more applications. The target applications for a message are determined by a number of different factors including the meaning of the message, the application's privilege to the object, whether or not the application initiated the request for which the message is a direct result, and the message masking that has been set by the application. Note the following points about messages:

•	Asynchronous reply messages are only sent to the application that originated the request and cannot be masked.

•	Messages that signal the completion of digit or tone generation or the gathering of digits are only sent to the application that requested the digit or tone generation.

•	Messages that indicate line or address state changes are sent to all applications that have opened the line, so long as the message has been enabled via lineSetStatusMessages.

•	Messages that indicate call state and call information changes are sent to all applications that have a handle to the call.

•	Messages that signal a digit detection, tone detection, or media mode detection are sent to the application(s) that requested monitoring of that event.


LINE_ADDRESSSTATE

The LINE_ADDRESSSTATE message is sent when the status of an address changes on a line that is currently open by the application. The application can invoke lineGetAddressStatus to determine the current status of the address.

LINE_ADDRESSSTATE
    dwDevice = (DWORD) hLine;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) idAddress;

    dwParam2 = (DWORD) AddressState;

    dwParam3 = (DWORD) 0;

Parameters

dwDevice

A handle to the line device.

dwCallbackInstance

The callback instance supplied when opening the line.

dwParam1

The address ID of the address that changed status.

dwParam2

The address state that changed. Can be a combination of these values:

LINEADDRESSSTATE_OTHER

Address-status items other than those listed below have changed. The application should check the current address status to determine which items have changed.

LINEADDRESSSTATE_DEVSPECIFIC

The device-specific item of the address status has changed.

LINEADDRESSSTATE_INUSEZERO

The address has changed to idle (it is now in use by zero stations).

LINEADDRESSSTATE_INUSEONE

The address has changed from idle or from being used by many bridged stations to being used by just one station.

LINEADDRESSSTATE_INUSEMANY

The monitored or bridged address has changed from being used by one station to being used by more than one station.

LINEADDRESSSTATE_NUMCALLS

The number of calls on the address has changed. This is the result of events such as a new inbound call, an outbound call on the address, or a call changing its hold status.

LINEADDRESSSTATE_FORWARD

The forwarding status of the address has changed, including the number of rings for determining a no answer condition. The application should check the address status to determine details about the address's current forwarding status.

LINEADDRESSSTATE_TERMINALS

The terminal settings for the address have changed.

LINEADDRESSSTATE_CAPSCHANGE

Indicates that, due to configuration changes made by the user or other circumstances, one or more of the fields in the LINEADDRESSCAPS structure for the address have changed. The application should use lineGetAddressCaps to read the updated structure. Applications which support API versions less than 0x00010004 will receive a LINEDEVSTATE_REINIT message, requiring them to shutdown and reinitialize their connection to TAPI in order to obtain the updated information.

dwParam3

Unused.

Return Values

No return value.

Remarks

The LINE_ADDRESSSTATE message is sent to any application that has opened the line device and that has enabled this message. The sending of this message for the various status items can be controlled and queried using lineGetStatusMessages and lineSetStatusMessages. By default, address status reporting is disabled.

See Also

LINEADDRESSCAPS, lineGetAddressCaps, lineGetAddressStatus, lineGetStatusMessages, lineSetStatusMessages


LINE_AGENTSPECIFIC

The LINE_AGENTSPECIFIC message is sent when the status of an ACD agent changes on a line the application currently has open. The application can invoke lineGetAgentStatus to determine the current status of the agent.

LINE_AGENTSPECIFIC
    dwDevice = (DWORD) hLine;

    dwCallbackInstance = (DWORD) dwInstanceData;

    dwParam1 = (DWORD) dwAgentExtensionIDIndex;

    dwParam2 = (DWORD) dwHandlerSpecific1;

    dwParam3 = (DWORD) dwHandlerSpecific2;

Parameters

dwDevice

The application's handle to the line device.

dwCallbackInstance

The callback instance supplied when opening the call's line.

dwParam1

The index into the array of handler extension IDs in LINEAGENTCAPS structure of the handler extension with which the message is associated:

dwParam2

Specific to the handler extension. Generally, this value will be used to cause the application to invoke a lineAgentSpecific function to fetch further details of the message.

dwParam3

Specific to the handler extension.

Return Values

No return value.

Remarks

The LINE_AGENTSPECIFIC message is not sent to applications which support older versions of TAPI.

See Also

LINEAGENTCAPS, lineAgentSpecific, lineGetAgentStatus


LINE_AGENTSTATUS

The LINE_AGENTSTATUS message is sent when the status of an ACD agent changes on a line the application currently has open. The application can invoke lineGetAgentStatus to determine the current status of the agent.

LINE_AGENTSTATUS
dwDevice = (DWORD) hLine;

    dwCallbackInstance = (DWORD) dwInstanceData;

    dwParam1 = (DWORD) dwAddressID;

    dwParam2 = (DWORD) AgentStatus;

    dwParam3 = (DWORD) AgentStatusDetail;

Parameters

dwDevice

The application's handle to the line device on which the agent status has changed.

dwCallbackInstance

The callback instance supplied when opening the call's line.

dwParam1

Identifier of the address on the line on which the agent status changed.

dwParam2

Specifies the agent status that has changed; can be a combination of LINEAGENTSTATUS_ constant values:

dwParam3

If dwParam2 includes the LINEAGENTSTATUS_STATE bit, then dwParam3 indicates the new value of dwState member in LINEAGENTSTATUS. Otherwise, this parameter is set to 0.

Return Values

No return value.

Remarks

The LINE_AGENTSTATUS message is not sent to applications which support older versions of TAPI.

See Also

LINEAGENTSTATUS, lineGetAgentStatus


LINE_APPNEWCALL

The LINE_APPNEWCALL message is sent to inform an application when a new call handle has been spontaneously created on its behalf (other than through an API call from the application, in which case the handle would have been returned through a pointer parameter passed into the function).

LINE_APPNEWCALL
dwDevice = (DWORD) hLine;

    dwCallbackInstance = (DWORD) dwInstanceData;

    dwParam1 = (DWORD) dwAddressID;

    dwParam2 = (DWORD) hCall;

    dwParam3 = (DWORD) dwPrivilege;

Parameters

dwDevice

The application's handle to the line device on which the call has been created.

dwCallbackInstance

The callback instance supplied when opening the call's line.

dwParam1

Identifier of the address on the line on which the call appears.

dwParam2

The application's handle to the new call.

dwParam3

The applications privilege to the new call (LINECALLPRIVILEGE_OWNER or LINECALLPRIVILEGE_MONITOR).

Return Values

No return value.

Comments and Backward Compatibility

Applications supporting TAPI version 0x00020000 or above are sent a LINE_APPNEWCALL message whenever the application is spontaneously given a handle to a new call. Because the message includes the hLine and dwAddressID on which the call exists, the application can readily create a new call object in the correct context. The LINE_APPNEWCALL message will always be immediately followed by a LINE_CALLSTATE message indicating the initial state of the call.

Older applications (which negotiated an API version prior to 0x00020000) are sent only a LINE_CALLSTATE message, as documented in previous versions of the API. Such applications would create a new call object upon receiving a LINE_CALLSTATE message which has dwParam3 set to a non-zero value and containing a call handle not presently known by the application. The disadvantages are that (a) the application must call lineGetCallInfo to determine the hLine and dwAddressID associated with the call, (b) the application must scan all known call handles to determine that the call is a new call, and (c) it is possible, under certain conditions, for the application to think it is receiving a new call handle when in reality it has just deallocated its handle to the call (for example, the application has just deallocated a call handle, but a LINE_CALLSTATE message giving the application ownership of the call due to a lineHandoff from another application was already in the application's TAPI message queue).

See Also

LINE_CALLSTATE, lineGetCallInfo, lineHandoff


LINE_CALLINFO

The LINE_CALLINFO message is sent when the call information about the specified call has changed. The application can invoke lineGetCallInfo to determine the current call information.

LINE_CALLINFO
dwDevice = (DWORD) hCall;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) CallInfoState;

    dwParam2 = (DWORD) 0;

    dwParam3 = (DWORD) 0;

Parameters

dwDevice

A handle to the call.

dwCallbackInstance

The callback instance supplied when opening the call's line.

dwParam1

The call information item that has changed. Can be a combination of these values:

LINECALLINFOSTATE_OTHER

Information items other than those listed below have changed. The application should check the current call information to determine which items have changed.

LINECALLINFOSTATE_DEVSPECIFIC

The device-specific field of the call-information record has changed.

LINECALLINFOSTATE_BEARERMODE

The bearer mode field of the call-information record has changed.

LINECALLINFOSTATE_RATE

The rate field of the call-information record has changed.

LINECALLINFOSTATE_MEDIAMODE

The media mode field of the call-information record has changed.

LINECALLINFOSTATE_APPSPECIFIC

The application-specific field of the call-information record has changed.

LINECALLINFOSTATE_CALLID

The call ID field of the call-information record has changed.

LINECALLINFOSTATE_RELATEDCALLID

The related call ID field of the call-information record has changed.

LINECALLINFOSTATE_ORIGIN

The origin field of the call-information record has changed.

LINECALLINFOSTATE_REASON

The reason field of the call-information record has changed.

LINECALLINFOSTATE_COMPLETIONID

The completion ID field of the call-information record has changed.

LINECALLINFOSTATE_NUMOWNERINCR

The number of owner fields in the call-information record was increased.

LINECALLINFOSTATE_NUMOWNERDECR

The number of owner fields in the call-information record was decreased.

LINECALLINFOSTATE_NUMMONITORS

The number of monitors fields in the call-information record has changed.

LINECALLINFOSTATE_TRUNK

The trunk field of the call information record has changed.

LINECALLINFOSTATE_CALLERID

One of the callerID-related fields of the call information record has changed.

LINECALLINFOSTATE_CALLEDID

One of the calledID-related fields of the call information record has changed.

LINECALLINFOSTATE_CONNECTEDID

One of the connectedID-related fields of the call information record has changed.

LINECALLINFOSTATE_REDIRECTIONID

One of the redirectionID-related fields of the call information record has changed.

LINECALLINFOSTATE_REDIRECTINGID

One of the redirectingID-related fields of the call information record has changed.

LINECALLINFOSTATE_DISPLAY

The display field of the call information record has changed.

LINECALLINFOSTATE_USERUSERINFO

The user-to-user information of the call information record has changed.

LINECALLINFOSTATE_HIGHLEVELCOMP

The high-level compatibility field of the call information record has changed.

LINECALLINFOSTATE_LOWLEVELCOMP

The low-level compatibility field of the call information record has changed.

LINECALLINFOSTATE_CHARGINGINFO

The charging information of the call information record has changed.

LINECALLINFOSTATE_TERMINAL

The terminal mode information of the call information record has changed.

LINECALLINFOSTATE_DIALPARAMS

The dial parameters of the call information record has changed.

LINECALLINFOSTATE_MONITORMODES

One or more of the digit, tone, or media monitoring fields in the call information record has changed.

dwParam2

Unused.

dwParam3

Unused.

Return Values

No return value.

Remarks

A LINE_CALLINFO message with a NumOwnersIncr, NumOwnersDecr, and/or NumMonitorsChanged indication is sent to applications that already have a handle for the call. This can be the result of another application changing ownership or monitorship to a call with lineOpen, lineClose, lineShutdown, lineSetCallPrivilege, lineGetNewCalls, and lineGetConfRelatedCalls.

These LINE_CALLINFO messages are not sent when a notification of a new call is provided in a LINE_CALLSTATE message, because the call information already reflects the correct number of owners and monitors at the time the LINE_CALLSTATE messages are sent. LINE_CALLINFO messages are also suppressed in the case where a call is offered by TAPI to monitors through the LINECALLSTATE_UNKNOWN mechanism.

Note  The application which causes a change in the number of owners or monitors (for example, by invoking lineDeallocateCall or lineSetCallPrivilege) will not itself receive a message indicating that the change has been done.

No LINE_CALLINFO messages are sent for a call after the call has entered the idle state. Specifically, changes in the number of owners and monitors are not reported as applications deallocate their handles for the idle call.

See Also

lineClose, lineDeallocateCall, lineGetCallInfo, lineGetConfRelatedCalls, lineGetNewCalls, lineOpen, lineSetCallPrivilege, lineShutdown


LINE_CALLSTATE

The LINE_CALLSTATE message is sent when the status of the specified call has changed. Several such messages will typically be received during the lifetime of a call. Applications are notified of new incoming calls with this message; the new call will be in the offering state. The application can use lineGetCallStatus to retrieve more detailed information about the current status of the call.

LINE_CALLSTATE
dwDevice = (DWORD) hCall;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) CallState;

    dwParam2 = (DWORD) CallStateDetail;

    dwParam3 = (DWORD) CallPrivilege;

Parameters

dwDevice

A handle to the call.

dwCallbackInstance

The callback instance supplied when opening the call's line.

dwParam1

The new call state. This parameter must be one and only one of the following LINECALLSTATE_ values:

LINECALLSTATE_IDLE

The call is idle—no call actually exists.

LINECALLSTATE_OFFERING

The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user. Alerting is done by the switch instructing the line to ring; it does not affect any call states.

LINECALLSTATE_ACCEPTED

The call was offering and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also indicates that alerting to both parties has started.

LINECALLSTATE_DIALTONE

The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.

LINECALLSTATE_DIALING

Destination address information (a phone number) is being sent to the switch over the call. Note that lineGenerateDigits does not place the line into the dialing state.

LINECALLSTATE_RINGBACK

The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.

LINECALLSTATE_BUSY

The call is receiving a busy tone. Busy tone indicates that the call cannot be completed—either a circuit (trunk) or the remote party's station are in use.

LINECALLSTATE_SPECIALINFO

Special information is sent by the network. Special information is typically sent when the destination cannot be reached.

LINECALLSTATE_CONNECTED

The call has been established and the connection is made. Information is able to flow over the call between the originating address and the destination address.

LINECALLSTATE_PROCEEDING

Dialing has completed and the call is proceeding through the switch or telephone network.

LINECALLSTATE_ONHOLD

The call is on hold by the switch.

LINECALLSTATE_CONFERENCED

The call is currently a member of a multiparty conference call.

LINECALLSTATE_ONHOLDPENDCONF

The call is currently on hold while it is being added to a conference.

LINECALLSTATE_ONHOLDPENTRANSFER

The call is currently on hold awaiting transfer to another number.

LINECALLSTATE_DISCONNECTED

The remote party has disconnected from the call.

LINECALLSTATE_UNKNOWN

The state of the call is not known. This may be due to limitations of the call-progress detection implementation.

dwParam2

Call-state-dependent information.

If dwParam1 is LINECALLSTATE_BUSY, dwParam2 contains details about the busy mode. This parameter uses the following LINEBUSYMODE_ constants:

LINEBUSYMODE_STATION

The busy signal indicates that the called party's station is busy. This is usually signaled by means of a "normal" busy tone.

LINEBUSYMODE_TRUNK

The busy signal indicates that a trunk or circuit is busy. This is usually signaled with a "long" busy tone.

LINEBUSYMODE_UNKNOWN

The busy signal's specific mode is currently unknown, but may become known later.

LINEBUSYMODE_UNAVAIL

The busy signal's specific mode is unavailable and will not become known.

If dwParam1 is LINECALLSTATE_CONNECTED, dwParam2 contains details about the connected mode. This parameter uses the following LINECONNECTEDMODE_ constants:

LINECONNECTEDMODE_ACTIVE

Indicates that the call is connected at the current station (the current station is a participant in the call).

LINECONNECTEDMODE_INACTIVE

Indicates that the call is active at one or more other stations, but the current station is not a participant in the call.

If dwParam1 is LINECALLSTATE_DIALTONE, dwParam2 contains the details about the dial tone mode. This parameter uses the following LINEDIALTONEMODE_ constants:

LINEDIALTONEMODE_NORMAL

This is a "normal" dial tone, which typically is a continuous tone.

LINEDIALTONEMODE_SPECIAL

This is a special dial tone indicating that a certain condition is currently in effect.

LINEDIALTONEMODE_INTERNAL

This is an internal dial tone, as within a PBX.

LINEDIALTONEMODE_EXTERNAL

This is an external (public network) dial tone.

LINEDIALTONEMODE_UNKNOWN

The dial tone mode is currently unknown, but may become known later.

LINEDIALTONEMODE_UNAVAIL

The dial tone mode is unavailable and will not become known.

If dwParam1 is LINECALLSTATE_OFFERING, dwParam2 contains details about the connected mode. This parameter uses the following LINEOFFERINGMODE_ constants:

LINEOFFERINGMODE_ACTIVE

Indicates that the call is alerting at the current station (will be accompanied by LINEDEVSTATE_RINGING messages), and if any application is set up to automatically answer, it may do so.

LINEOFFERINGMODE_INACTIVE

Indicates that the call is being offered at more than one station, but the current station is not alerting (for example, it may be an attendant station where the offering status is advisory, such as blinking a light).

If dwParam1 is LINECALLSTATE_SPECIALINFO, dwParam2 contains the details about the special information mode. This parameter uses the following LINESPECIALINFO_ constants:

LINESPECIALINFO_NOCIRCUIT

This special information tone precedes a "no circuit" or emergency announcement (trunk blockage category).

LINESPECIALINFO_CUSTIRREG

This special information tone precedes a vacant number, AIS, Centrex number change and nonworking station, access code not dialed or dialed in error, or manual intercept operator message (customer irregularity category).

LINESPECIALINFO_REORDER

This special information tone precedes a reorder announcement (equipment irregularity category).

LINESPECIALINFO_UNKNOWN

Specifics about the special information tone are currently unknown but may become known later.

LINESPECIALINFO_UNAVAIL

Specifics about the special information tone are unavailable and will not become known.

If dwParam1 is LINECALLSTATE_DISCONNECTED, dwParam2 contains details about the disconnect mode. This parameter uses the following LINEDISCONNECTMODE_ constants:

LINEDISCONNECTMODE_NORMAL

This is a "normal" disconnect request by the remote party, the call was terminated normally.

LINEDISCONNECTMODE_UNKNOWN

The reason for the disconnect request is unknown.

LINEDISCONNECTMODE_REJECT

The remote user has rejected the call.

LINEDISCONNECTMODE_PICKUP

The call was picked up from elsewhere.

LINEDISCONNECTMODE_FORWARDED

The call was forwarded by the switch.

LINEDISCONNECTMODE_BUSY

The remote user's station is busy.

LINEDISCONNECTMODE_NOANSWER

The remote user's station does not answer.

LINEDISCONNECTMODE_NODIALTONE

A dial tone was not detected within a service-provider defined timeout, at a point during dialing when one was expected (such as at a "W" in the dialable string). This can also occur without a service-provider-defined timeout period or without a value specified in the dwWaitForDialTone member of the LINEDIALPARAMS structure.

LINEDISCONNECTMODE_BADADDRESS

The destination address in invalid.

LINEDISCONNECTMODE_UNREACHABLE

The remote user could not be reached.

LINEDISCONNECTMODE_CONGESTION

The network is congested.

LINEDISCONNECTMODE_INCOMPATIBLE

The remote user's station equipment is incompatible for the type of call requested.

LINEDISCONNECTMODE_UNAVAIL

The reason for the disconnect is unavailable and will not become known later.

If dwParam1 is LINECALLSTATE_CONFERENCED, dwParam2 contains the hConfCall of the parent call of the conference of which the subject hCall is a member. If the call specified in dwParam2 was not previously considered by the application to be a parent conference call (hConfCall), the application must do so as a result of this message. If the application does not have a handle to the parent call of the conference (because it has previously called lineDeallocateCall on that handle) dwParam2 will be set to null.

dwParam3

If zero, this parameter indicates that there has been no change in the application's privilege for the call.

If non-zero, it specifies the application's privilege to the call. This will occur in the following situations: (1) The first time that the application is given a handle to this call; (2) When the application is the target of a call handoff (even if the application already was an owner of the call). This parameter uses the following LINECALLPRIVILEGE_ constants:

LINECALLPRIVILEGE_MONITOR

The application has monitor privilege.

LINECALLPRIVILEGE_OWNER

The application has owner privilege.

Return Values

No return value.

Remarks

This message is sent to any application that has a handle for the call. The LINE_CALLSTATE message also notifies applications that monitor calls on a line about the existence and state of outbound calls established by other applications or manually by the user (for example, on an attached phone device). The call state of such calls reflects the actual state of the call, which will not be offering. By examining the call state, the application can determine whether the call is an inbound call that needs to be answered or not.

A LINE_CALLSTATE message with an unknown call state may be sent to a monitoring application as the result of a successful lineMakeCall, lineForward, lineUnpark, lineSetupTransfer, linePickup, lineSetupConference, or linePrepareAddToConference that has been requested by another application. At the same time that the requesting application is sent a LINE_REPLY (success) for the requested operation, any monitoring applications on the line will be sent the LINE_CALLSTATE (unknown) message. A LINE_CALLSTATE indicating the "real" call state of the newly generated call will be sent (using information provided by the service provider) to the requesting and monitoring applications shortly thereafter.

A LINE_CALLSTATE (unknown) message is sent to monitoring applications only if lineCompleteTransfer causes calls to be resolved into a three-way conference.

For backward compatibility, older applications will not be expecting any particular value in dwParam2 of a LINECALLSTATE_CONFERENCED message. TAPI will therefore pass the parent call hConfCall in dwParam2 regardless of the API version of the application receiving the message. In the case of a conference call initiated by the service provider, the older application will not be aware that the parent call has become a conference call unless it happens to spontaneously examine other information (for example, call lineGetConfRelatedCalls)

This message cannot be disabled.

See Also

LINE_REPLY, lineCompleteTransfer, lineDeallocateCall, LINEDIALPARAMS, lineForward, lineGenerateDigits, lineGetCallStatus, lineGetConfRelatedCalls, lineMakeCall, linePickup, linePrepareAddToConference, lineSetupTransfer, lineUnpark


LINE_CLOSE

The LINE_CLOSE message is sent when the specified line device has been forcibly closed. The line device handle or any call handles for calls on the line are no longer valid once this message has been sent.

LINE_CLOSE
dwDevice = (DWORD) hLine;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) 0;

    dwParam2 = (DWORD) 0;

    dwParam3 = (DWORD) 0;

Parameters

dwDevice

A handle to the line device that was closed. This handle is no longer valid.

dwCallbackInstance

The callback instance supplied when opening the line.

dwParam1

Unused.

dwParam2

Unused.

dwParam3

Unused.

Return Values

No return value.

Remarks

The LINE_CLOSE message is only sent to any application after an open line has been forcibly closed. This may be done to prevent a single application from monopolizing a line device for too long. Whether or not the line can be reopened immediately after a forced close is device-specific.

A line device may also be forcibly closed after the user has modified the configuration of that line or its driver. If the user wants the configuration changes to be effective immediately (as opposed to after the next system restart), and they affect the application's current view of the device (such as a change in device capabilities), then a service provider may forcibly close the line device.


LINE_CREATE

The LINE_CREATE message is sent to inform the application of the creation of a new line device.

dwDevice = (DWORD) 0;

    dwCallbackInstance = (DWORD) 0;

    dwParam1 = (DWORD) idDevice;

    dwParam2 = (DWORD) 0;

    dwParam3 = (DWORD) 0;

Parameters

dwDevice

Unused.

dwCallbackInstance

Unused.

dwParam1

The dwDeviceID of the newly-created device.

dwParam2

Unused.

dwParam3

Unused.

Return Values

No return value.

Remarks

Older applications (which negotiated TAPI version 0x00010003) are sent a LINE_LINEDEVSTATE message specifying LINEDEVSTATE_REINIT, which requires them to shut down their use of the API and call lineInitialize again to obtain the new number of devices. Unlike previous versions of TAPI, however, this version does not require all applications to shut down before allowing applications to reinitialize; reinitialization can take place immediately when a new device is created (complete shutdown is still required when a service provider is removed from the system).

Applications supporting TAPI version 0x00010004 or above are sent a LINE_CREATE message. This informs them of the existence of the new device and its new device ID. The application can then choose whether or not to attempt working with the new device at its leisure. This message will be sent to all applications supporting this or subsequent versions of the API which have called lineInitialize or lineInitalizeEx, including those that do not have any line devices open at the time.

See Also

LINE_LINEDEVSTATE, lineInitialize, lineInitializeEx


LINE_DEVSPECIFIC

The LINE_DEVSPECIFIC message is sent to notify the application about device-specific events occurring on a line, address, or call. The meaning of the message and the interpretation of the parameters are device specific.

LINE_DEVSPECIFIC
dwDevice = (DWORD) hLineOrCall;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) DeviceSpecific1;

    dwParam2 = (DWORD) DeviceSpecific2;

    dwParam3 = (DWORD) DeviceSpecific3;

Parameters

dwDevice

A handle to either a line device or call. This is device specific.

dwCallbackInstance

The callback instance supplied when opening the line.

dwParam1

Device specific.

dwParam2

Device specific.

dwParam3

Device specific.

Return Values

No return value.

Remarks

The LINE_DEVSPECIFIC message is used by a service provider in conjunction with the lineDevSpecific function. Its meaning is device specific.


LINE_DEVSPECIFICFEATURE

The LINE_DEVSPECIFICFEATURE message is sent to notify the application about device-specific events occurring on a line, address, or call. The meaning of the message and the interpretation of the parameters are device specific.

LINE_DEVSPECIFICFEATURE
dwDevice = (DWORD) hLineOrCall;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) DeviceSpecific1;

    dwParam2 = (DWORD) DeviceSpecific2;

    dwParam3 = (DWORD) DeviceSpecific3;

Parameters

dwDevice

A handle to either a line device or call. This is device specific.

dwCallbackInstance

The callback instance supplied when opening the line.

dwParam1

Device specific.

dwParam2

Device specific.

dwParam3

Device specific.

Return Values

No return value.

Remarks

The LINE_DEVSPECIFICFEATURE message is used by a service provider in conjunction with the lineDevSpecificFeature function. Its meaning is device specific.


LINE_GATHERDIGITS

The LINE_GATHERDIGITS message is sent when the current buffered digit-gathering request has terminated or is canceled. The digit buffer may be examined after this message has been received by the application.

LINE_GATHERDIGITS
dwDevice = (DWORD) hCall;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) GatherTermination;

    dwParam2 = (DWORD) 0;

    dwParam3 = (DWORD) 0;

Parameters

dwDevice

A handle to the call.

dwCallbackInstance

The callback instance supplied when opening the line.

dwParam1

The reason why digit gathering was terminated. This parameter must be one and only one of the following LINEGATHERTERM_ constants:

LINEGATHERTERM_BUFFERFULL

The requested number of digits has been gathered. The buffer is full.

LINEGATHERTERM_TERMDIGIT

One of the termination digits matched a received digit. The matched termination digit is the last digit in the buffer.

LINEGATHERTERM_FIRSTTIMEOUT

The first digit timeout expired. The buffer contains no digits.

LINEGATHERTERM_INTERTIMEOUT

The inter-digit timeout expired. The buffer contains at least one digit.

LINEGATHERTERM_CANCEL

The request was canceled by this application, by another application, or because the call terminated.

dwParam2

Unused.

dwParam3

The "tick count" (number of milliseconds since Windows started) at which the digit gathering completed. For API versions prior to 0x0002000, this parameter is unused.

Return Values

No return value.

Remarks

The LINE_GATHERDIGITS message is only sent to the application that initiated the digit gathering on the call using lineGatherDigits.

If the lineGatherDigits function is used to cancel a previous request to gather digits, TAPI sends a LINE_GATHERDIGITS message with dwParam1 set to LINEGATHERTERM_CANCEL to the application indicating that the originally specified buffer contains the digits gathered up to the cancellation.

Because the timestamp specified by dwParam3 may have been generated on a computer other than the one on which the application is executing, it is useful only for comparison to other similarly timestamped messages generated on the same line device (LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORMEDIA, LINE_MONITORTONE), in order to determine their relative timing (separation between events). The tick count can "wrap around" after approximately 49.7 days; applications must take this into account when performing calculations.

If the service provider does not generate the timestamp (for example, if it was created using an earlier version of TAPI), then TAPI will provide a timestamp at the point closest to the service provider generating the event so that the synthesized timestamp is as accurate as possible.

See Also

LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORMEDIA, LINE_MONITORTONE, lineGatherDigits


LINE_GENERATE

The LINE_GENERATE message is sent to notify the application that the current digit or tone generation has terminated. Only one such generation request can be in progress an a given call at any time. This message is also sent when digit or tone generation is canceled.

LINE_GENERATE
dwDevice = (DWORD) hCall;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) GenerateTermination;

    dwParam2 = (DWORD) 0;

    dwParam3 = (DWORD) 0;

Parameters

dwDevice

A handle to the call.

dwCallbackInstance

The callback instance supplied when opening the line.

dwParam1

The reason why digit or tone generation was terminated. This parameter must be one and only one of the following LINEGENERATETERM_ constants:

LINEGENERATETERM_DONE

The requested number of digits have been generated, or the requested tones have been generated for the requested duration.

LINEGENERATETERM_CANCEL

The digit or tone generation request was canceled by this application, by another application, or because the call terminated.

dwParam2

Unused.

dwParam3

The "tick count" (number of milliseconds since Windows started) at which the digit or tone generation completed. For API versions prior to 0x00020000, this parameter is unused.

Return Values

No return value.

Remarks

The LINE_GENERATE message is only sent to the application that requested the digit or tone generation.

Because the timestamp specified by dwParam3 may have been generated on a computer other than the one on which the application is executing, it is useful only for comparison to other similarly timestamped messages generated on the same line device (LINE_GATHERDIGITS, LINE_MONITORDIGITS, LINE_MONITORMEDIA, LINE_MONITORTONE), in order to determine their relative timing (separation between events). The tick count can "wrap around" after approximately 49.7 days; applications must take this into account when performing calculations.

If the service provider does not generate the timestamp (for example, if it was created using an earlier version of TAPI), then TAPI will provide a timestamp at the point closest to the service provider generating the event so that the synthesized timestamp is as accurate as possible.

See Also

LINE_GATHERDIGITS, LINE_MONITORDIGITS, LINE_MONITORMEDIA, LINE_MONITORTONE


LINE_LINEDEVSTATE

The LINE_LINEDEVSTATE message is sent when the state of a line device has changed. The application can invoke lineGetLineDevStatus to determine the new status of the line.

LINE_LINEDEVSTATE
dwDevice = (DWORD) hLine;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) DeviceState;

    dwParam2 = (DWORD) DeviceStateDetail1;

    dwParam3 = (DWORD) DeviceStateDetail2;

Parameters

dwDevice

A handle to the line device. This parameter is NULL when dwParam1 is LINEDEVSTATE_REINIT.

dwCallbackInstance

The callback instance supplied when opening the line. If the dwParam1 parameter is LINEDEVSTATE_REINIT, the dwCallbackInstance parameter is not valid and is set to zero.

dwParam1

The line device status item that has changed. The parameter can be a combination of the following LINEDEVSTATE_ constants:

LINEDEVSTATE_OTHER

Device-status items other than those listed below have changed. The application should check the current device status to determine which items have changed.

LINEDEVSTATE_RINGING

The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds.

LINEDEVSTATE_CONNECTED

The line was previously disconnected and is now connected to TAPI.

LINEDEVSTATE_DISCONNECTED

This line was previously connected and is now disconnected from TAPI.

LINEDEVSTATE_MSGWAITON

The "message waiting" indicator is turned on.

LINEDEVSTATE_MSGWAITOFF

The "message waiting" indicator is turned off.

LINEDEVSTATE_NUMCOMPLETIONS

The number of outstanding call completions on the line device has changed.

LINEDEVSTATE_INSERVICE

The line is connected to TAPI. This happens when TAPI is first activated, or when the line wire is physically plugged in and in service at the switch while TAPI is active.

LINEDEVSTATE_OUTOFSERVICE

The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.

LINEDEVSTATE_MAINTENANCE

Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.

LINEDEVSTATE_OPEN

The line has been opened by another application.

LINEDEVSTATE_CLOSE

The line has been closed by another application.

LINEDEVSTATE_NUMCALLS

The number of calls on the line device has changed.

LINEDEVSTATE_TERMINALS

The terminal settings have changed.

LINEDEVSTATE_ROAMMODE

The roaming state of the line device has changed.

LINEDEVSTATE_BATTERY

The battery level has changed significantly (cellular).

LINEDEVSTATE_SIGNAL

The signal level has changed significantly (cellular).

LINEDEVSTATE_DEVSPECIFIC

The line's device-specific information has changed.

LINEDEVSTATE_REINIT

Items have changed in the configuration of line devices. To become aware of these changes (as with the appearance of new line devices), the application should reinitialize its use of TAPI. The dwDevice parameter is left NULL for this state change as it applies to any of the lines in the system.

LINEDEVSTATE_LOCK

The locked status of the line device has changed. (For more information, refer to the description of the LINEDEVSTATUSFLAGS_LOCKED bit of the LINEDEVSTATUSFLAGS_ constants.)

LINEDEVSTATE_CAPSCHANGE

Indicates that, due to configuration changes made by the user or other circumstances, one or more of the fields in the LINEDEVCAPS structure for the address have changed. The application should use lineGetDevCaps to read the updated structure.

LINEDEVSTATE_CONFIGCHANGE

Indicates that configuration changes have been made to one or more of the media devices associated with the line device. The application, if it desires, may use lineGetDevConfig to read the updated information.

LINEDEVSTATE_TRANSLATECHANGE

Indicates that, due to configuration changes made by the user or other circumstances, one or more of the fields in the LINETRANSLATECAPS structure have changed. The application should use lineGetTranslateCaps to read the updated structure.

LINEDEVSTATE_COMPLCANCEL

Indicates that the call completion identified by the completion ID contained in parameter dwParam2 of the LINE_LINEDEVSTATE message has been externally canceled and is no longer considered valid (if that value were to be passed in a subsequent call to lineUncompleteCall, the function would fail with LINEERR_INVALCOMPLETIONID).

LINEDEVSTATE_REMOVED

Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A LINE_LINEDEVSTATE message with this value will normally be immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized will result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will not receive any notification.

dwParam2

The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam2 contains the ring mode with which the switch instructs the line to ring. Valid ring modes are numbers in the range one to dwNumRingModes, where dwNumRingModes is a line device capability.

If dwParam1 is LINEDEVSTATE_REINIT, and the message was issued by TAPI as a result of translation of a new API message into a REINIT message, then dwParam2 contains the dwMsg parameter of the original message (for example, LINE_CREATE or LINE_LINEDEVSTATE). If dwParam2 is zero, this indicates that the REINIT message is a "real" REINIT message that requires the application to call lineShutdown at its earliest convenience.

dwParam3

The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam3 contains the ring count for this ring event. The ring count starts at zero.

If dwParam1 is LINEDEVSTATE_REINIT, and the message was issued by TAPI as a result of translation of a new API message into a REINIT message, then dwParam3 contains the dwParam1 parameter of the original message (for example, LINEDEVSTATE_TRANSLATECHANGE or some other LINEDEVSTATE_ value, if dwParam2 is LINE_LINEDEVSTATE, or the new device ID, if dwParam2 is LINE_CREATE).

Return Values

No return value.

Remarks

The sending of the LINE_LINEDEVSTATE message can be controlled with lineSetStatusMessages. An application can indicate status item changes about which it wants to be notified. By default, all status reporting will be disabled except for LINEDEVSTATE_REINIT, which cannot be disabled. This message is sent to all applications that have a handle to the line, including those that called lineOpen with the dwPrivileges parameter set to LINECALLPRIVILEGE_NONE, LINECALLPRIVILEGE_OWNER, LINECALLPRIVILEGE_MONITOR, or permitted combinations of these.

See Also

LINE_CLOSE, LINE_CREATE, LINEDEVCAPS, lineGetDevCaps, lineGetDevConfig, lineGetTranslateCaps, lineInitialize, lineOpen, lineSetStatusMessages, lineShutdown, LINETRANSLATECAPS, lineUncompleteCall


LINE_MONITORDIGITS

The LINE_MONITORDIGITS message is sent when a digit is detected. The sending of this message is controlled with the lineMonitorDigits function.

LINE_MONITORDIGITS
    dwDevice = (DWORD) hCall;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) Digit;

    dwParam2 = (DWORD) DigitMode;

    dwParam3 = (DWORD) 0;

Parameters

dwDevice

A handle to the call.

dwCallbackInstance

The callback instance supplied when opening the call's line.

dwParam1

The low-order byte contains the last digit received in ASCII.

dwParam2

The digit mode that was detected. This parameter must be one and only one of the following LINEDIGITMODE_ constants:

LINEDIGITMODE_PULSE

Detect digits as audible clicks that are the result of rotary pulse sequences. Valid digits for pulse are '0' through '9'.

LINEDIGITMODE_DTMF

Detect digits as DTMF tones. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.

LINEDIGITMODE_DTMFEND

Detect and provide application notification of DTMF down edges. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.

dwParam3

The "tick count" (number of milliseconds since Windows started) at which the specified digit was detected. For API versions prior to 0x00020000, this parameter is unused.

Return Values

No return value.

Remarks

The LINE_MONITORDIGITS message is sent to the application that has enabled digit monitoring.

Because this timestamp may have been generated on a computer other than the one on which the application is executing, it is useful only for comparison to other similarly timestamped messages generated on the same line device (LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORMEDIA, LINE_MONITORTONE), in order to determine their relative timing (separation between events). The tick count can "wrap around" after approximately 49.7 days; applications must take this into account when performing calculations.

If the service provider does not generate the timestamp (for example, if it was created using an earlier version of TAPI), then TAPI will provide a timestamp at the point closest to the service provider generating the event so that the synthesized timestamp is as accurate as possible.

See Also

LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORMEDIA, LINE_MONITORTONE, lineMonitorDigits


LINE_MONITORMEDIA

The LINE_MONITORMEDIA message is sent when a change in the call's media mode is detected. The sending of this message is controlled with the lineMonitorMedia function.

LINE_MONITORMEDIA
    dwDevice = (DWORD) hCall;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) MediaMode;

    dwParam2 = (DWORD) 0;

    dwParam3 = (DWORD) 0;

Parameters

dwDevice

A handle to the call.

dwCallbackInstance

The callback instance supplied when opening the line.

dwParam1

The new media mode. This parameter must be one and only one of the following LINEMEDIAMODE_ constants:

LINEMEDIAMODE_INTERACTIVEVOICE

The presence of voice energy has been detected and the call is treated as an interactive call with humans on both ends.

LINEMEDIAMODE_AUTOMATEDVOICE

The presence of voice energy has been detected and the call is locally handled by an automated application.

LINEMEDIAMODE_DATAMODEM

A data modem session has been detected.

LINEMEDIAMODE_G3FAX

A group 3 fax has been detected.

LINEMEDIAMODE_TDD

A TDD (Telephony Devices for the Deaf) session has been detected.

LINEMEDIAMODE_G4FAX

A group 4 fax has been detected.

LINEMEDIAMODE_DIGITALDATA

Digital data has been detected.

LINEMEDIAMODE_TELETEX

A teletex session has been detected. Teletex is one of the telematic services.

LINEMEDIAMODE_VIDEOTEX

A videotex session has been detected. Videotex is one the telematic services.

LINEMEDIAMODE_TELEX

A telex session has been detected. Telex is one the telematic services.

LINEMEDIAMODE_MIXED

A mixed session has been detected. Mixed is one the telematic services.

LINEMEDIAMODE_ADSI

An ADSI (Analog Display Services Interface) session has been detected.

LINEMEDIAMODE_VOICEVIEW

The media mode of the call is VoiceView.

dwParam2

Unused.

dwParam3

The "tick count" (number of milliseconds since Windows started) at which the specified media was detected. For API versions prior to 0x00020000, this parameter is unused.

Return Values

No return value.

Remarks

The LINE_MONITORMEDIA message is sent to the application that has enabled media monitoring for the media mode detected.

Because this timestamp may have been generated on a computer other than the one on which the application is executing, it is useful only for comparison to other similarly timestamped messages generated on the same line device (LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORTONE), in order to determine their relative timing (separation between events). The tick count can "wrap around" after approximately 49.7 days; applications must take this into account when performing calculations.

If the service provider does not generate the timestamp (for example, if it was created using an earlier version of TAPI), then TAPI will provide a timestamp at the point closest to the service provider generating the event so that the synthesized timestamp is as accurate as possible.

See Also

LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORTONE


LINE_MONITORTONE

The LINE_MONITORTONE message is sent when a tone is detected. The sending of this message is controlled with the lineMonitorTones function.

LINE_MONITORTONE
    dwDevice = (DWORD) hCall;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) dwAppSpecific;

    dwParam2 = (DWORD) 0;

    dwParam3 = (DWORD) 0;

Parameters

dwDevice

A handle to the call.

dwCallbackInstance

The callback instance supplied when opening the call's line.

dwParam1

The application-specific dwAppSpecific field of the LINEMONITORTONE structure for the tone that was detected.

dwParam2

Unused.

dwParam3

The "tick count" (number of milliseconds since Windows started) at which the tone was detected. For API versions prior to 0x00020000, this parameter is unused.

Return Values

No return value.

Remarks

The LINE_MONITORTONE message is only sent to the application that has requested the tone be monitored.

Because this timestamp may have been generated on a computer other than the one on which the application is executing, it is useful only for comparison to other similarly timestamped messages generated on the same line device (LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORTONE), in order to determine their relative timing (separation between events). The tick count can "wrap around" after approximately 49.7 days; applications must take this into account when performing calculations.

If the service provider does not generate the timestamp (for example, if it was created using an earlier version of TAPI), then TAPI will provide a timestamp at the point closest to the service provider generating the event so that the synthesized timestamp is as accurate as possible.

See Also

LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORTONE, LINEMONITORTONE, lineMonitorTones


LINE_PROXYREQUEST

The LINE_PROXYREQUEST message delivers a request to a registered proxy function handler.

LINE_PROXYREQUEST
    dwDevice = (DWORD) hLine;

    dwCallbackInstance = (DWORD) dwInstanceData;

    dwParam1 = (DWORD) lpProxyRequest;

    dwParam2 = (DWORD) 0;

    dwParam3 = (DWORD) 0;

Parameters

dwDevice

The application's handle to the line device on which the agent status has changed.

dwCallbackInstance

The callback instance supplied when opening the call's line.

dwParam1

Pointer to a LINEPROXYREQUEST structure containing the request to be processed by the proxy handler application.

dwParam2

Reserved.

dwParam3

Reserved.

Return Values

No return value.

Remarks

The LINE_PROXYREQUEST message is sent only to the first application that registered to handle proxy requests of the type being delivered.

The application should process the request contained in the proxy buffer and call lineProxyResponse to return data or deliver results. Processing of the request should be done within the context of the application's TAPI callback function only if it can be performed immediately, without waiting for response from any other entity. If the application needs to communicate with other entities (for example, a service provider to handle PBX-based ACD, or any other system service which might result in blocking), then the request should be queued within the application and the callback function exited to avoid delaying the receipt of further TAPI messages by the application.

At the time the LINE_PROXYREQUEST is delivered to the proxy handler, TAPI has already returned a positive dwRequestID function result to the original application and unblocked the calling thread to continue execution. The application is awaiting a LINE_REPLY message, which is automatically generated when the proxy handler application calls lineProxyResponse.

The application shall not free the memory pointed to by lpProxyRequest. TAPI will free the memory during the execution of lineProxyResponse. The application shall call lineProxyResponse exactly once for each LINE_PROXYREQUEST message.

If the application receives a LINE_CLOSE message while it has pending proxy requests, it should call lineProxyResponse for each pending request, passing in an appropriate dwResult value (such as LINEERR_OPERATIONFAILED).

See Also

LINE_CLOSE, LINE_REPLY, LINEPROXYREQUEST, lineProxyResponse


LINE_REMOVE

The LINE_REMOVE message is sent to inform an application of the removal (deletion from the system) of a line device. Generally, this is not used for temporary removals, such as extraction of PCMCIA devices, but only for permanent removals in which the device would no longer be reported by the service provider if TAPI were reinitialized.

LINE_REMOVE
    dwDevice = (DWORD) 0;

    dwCallbackInstance = (DWORD) 0;

    dwParam1 = (DWORD) dwDeviceID;

    dwParam2 = (DWORD) 0;

    dwParam3 = (DWORD) 0;

Parameters

dwDevice

Reserved; set to 0.

dwCallbackInstance

Reserved; set to 0.

dwParam1

Identifier of the line device that was removed.

dwParam2

Reserved; set to 0.

dwParam3

Reserved; set to 0.

Return Values

No return value.

Comments and Backward Compatibility

Applications supporting TAPI version 0x00020000 or above are sent a LINE_REMOVE message. This informs them that the device has been removed from the system. The LINE_REMOVE message will have been preceded by a LINE_CLOSE message on each line handle, if the application had the line open. This message will be sent to all applications supporting TAPI version 0x00020000 or above which have called lineInitializeEx, including those that do not have any line devices open at the time.

Older applications are sent a LINE_LINEDEVSTATE message specifying LINEDEVSTATE_REMOVED, followed by a LINE_CLOSE message. Unlike the LINE_REMOVE message, however, these older applications can receive these messages only if they have the line open when it is removed. If they do not have the line open, their only indication that the device was removed would be receiving a LINEERR_NODEVICE when they attempt to access the device.

After a device has been removed, any attempt to access the device by its device ID will result in a LINEERR_NODEVICE error. After all TAPI applications have shutdown so that TAPI can restart, when TAPI is reinitialized, the removed device will no longer occupy a device ID.

Implementation Note  It is TAPI that will return this LINEERR_NODEVICE; after a LINE_REMOVE message is received from a service provider; no further calls will be made to that service provider using that line device ID.

See Also

LINE_CLOSE, LINE_LINEDEVSTATE, lineInitializeEx


LINE_REPLY

The LINE_REPLY message is sent to report the results of function calls that completed asynchronously.

LINE_REPLY
    dwDevice = (DWORD) 0;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) idRequest;

    dwParam2 = (DWORD) Status;

    dwParam3 = (DWORD) 0;

Parameters

dwDevice

Not used.

dwCallbackInstance

Returns the application's callback instance.

dwParam1

The request ID for which this is the reply.

dwParam2

The success or error indication. The application should cast this parameter into a LONG. Zero indicates success; a negative number indicates an error.

dwParam3

Unused.

Return Values

No return value.

Remarks

Functions that operate asynchronously return a positive request ID value to the application. This request ID is returned with the reply message to identify the request that was completed. The other parameter for the LINE_REPLY message carries the success or failure indication. Possible errors are the same as those defined by the corresponding function. This message cannot be disabled.

In some cases, an application may fail to receive the LINE_REPLY message corresponding to a call to an asynchronous function. This occurs if the corresponding call handle is deallocated before the message has been received.


LINE_REQUEST

The LINE_REQUEST message is sent to report the arrival of a new request from another application.

LINE_REQUEST
    dwDevice = (DWORD) 0;

    dwCallbackInstance = (DWORD) hRegistration;

    dwParam1 = (DWORD) RequestMode;

    dwParam2 = (DWORD) RequestModeDetail1;

    dwParam3 = (DWORD) RequestModeDetail2;

Parameters

dwDevice

Not used.

dwCallbackInstance

The registration instance of the application specified on lineRegisterRequestRecipient.

dwParam1

The request mode of the newly pending request. This parameter uses the following LINEREQUESTMODE_ constants:

LINEREQUESTMODE_MAKECALL

A tapiRequestMakeCall request.

dwParam2

If dwParam1 is set to LINEREQUESTMODE_DROP, dwParam2 contains the hWnd of the application requesting the drop. Otherwise, dwParam2 is unused.

dwParam3

If dwParam1 is set to LINEREQUESTMODE_DROP, the low-order word of dwParam3 contains the wRequestID as specified by the application requesting the drop. Otherwise, dwParam3 is unused.

Return Values

No return value.

Remarks

The LINE_REQUEST message is sent to the highest priority application that has registered for the corresponding request mode. This message indicates the arrival of an Assisted Telephony request of the specified request mode. If dwParam1 is LINEREQUESTMODE_MAKECALL or LINEREQUESTMODE_MEDIACALL, the application can invoke lineGetRequest using the corresponding request mode to receive the request. If dwParam1 is LINEREQUESTMODE_DROP, the message contains all of the information the request recipient needs in order to perform the request.

See Also

lineGetRequest, lineRegisterRequestRecipient, tapiRequestMakeCall


Phone Device Messages

The following section contains the reference for phone device messages.


PHONE_BUTTON

The PHONE_BUTTON message is sent to notify the application that button press monitoring is enabled if it has detected a button press on the local phone.

PHONE_BUTTON
hPhone = (HPHONE) hPhoneDevice;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) idButtonOrLamp;

    dwParam2 = (DWORD) ButtonMode;

    dwParam3 = (DWORD) ButtonState;

Parameters

hPhone

A handle to the phone device.

dwCallbackInstance

The application's callback instance provided when opening the phone device.

dwParam1

The button/lamp ID of the button that was pressed. Note that button IDs 0 through 11 are always the KEYPAD buttons, with '0' being button ID 0, '1' being button ID 1 (and so on through button ID 9), and with '*' being button ID 10, and '#' being button ID 11. Additional information about a button ID is available with phoneGetDevCaps and phoneGetButtonInfo.

dwParam2

The button mode of the button. This parameter uses the following PHONEBUTTONMODE_ constants:

PHONEBUTTONMODE_CALL

The button is assigned to a call appearance.

PHONEBUTTONMODE_FEATURE

The button is assigned to requesting features from the switch, such as hold, conference, and transfer.

PHONEBUTTONMODE_KEYPAD

The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.

PHONEBUTTONMODE_LOCAL

The button is a local function button, such as mute or volume control.

PHONEBUTTONMODE_DISPLAY

The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.

dwParam3

Specifies whether this is a button-down event or a button-up event. This parameter uses the following PHONEBUTTONSTATE_ constants:

PHONEBUTTONSTATE_UP

The button is in the "up" state.

PHONEBUTTONSTATE_DOWN

The button is in the "down" state (pressed down).

PHONEBUTTONSTATE_UNKNOWN

Indicates that the up or down state of the button is not known at this time, but may become known at a future time.

PHONEBUTTONSTATE_UNAVAIL

Indicates that the up or down state of the button is not known to the service provider, and will not become known at a future time.

Return Values

No return value.

Remarks

A PHONE_BUTTON message is sent whenever a button changes state. An application is guaranteed that for each button down event, it will eventually be sent a corresponding button up event. A service provider that is incapable of detecting the actual button up is required to generate the button up message shortly after the button down message for each button press.

See Also

phoneGetButtonInfo, phoneGetDevCaps


PHONE_CLOSE

The PHONE_CLOSE message is sent when an open phone device has been forcibly closed as part of resource reclamation. The device handle is no longer valid once this message has been sent.

PHONE_CLOSE
hPhone = (HPHONE) hPhoneDevice;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) 0;

    dwParam2 = (DWORD) 0;

    dwParam3 = (DWORD) 0;

Parameters

hPhone

A handle to the open phone device that was closed. The handle is no longer valid after this message has been sent

dwCallbackInstance

The application's callback instance provided when opening the phone device.

dwParam1

Unused.

dwParam2

Unused.

dwParam3

Unused.

Return Values

No return value.

Remarks

The PHONE_CLOSE message is only sent to an application after an open phone has been forcibly closed. This may be done to prevent a single application from monopolizing a phone device for too long. Whether the phone can be reopened immediately after a forced close is device specific.

An open phone device may also be forcibly closed after the user has modified the configuration of that phone or its driver. If the user wants the configuration changes to be effective immediately (as opposed to after the next system restart), and these changes affect the application's current view of the device (such as a change in device capabilities), then a service provider may forcibly close the phone device.


PHONE_CREATE

The PHONE_CREATE message is sent to inform applications of the creation of a new phone device.

PHONE_CREATE
hPhone = (HPHONE) hPhoneDev;

    dwCallbackInstance = (DWORD) 0;

    dwParam1 = (DWORD) idDevice;

    dwParam2 = (DWORD) 0;

    dwParam3 = (DWORD) 0;

Parameters

hPhone

Unused.

dwCallbackInstance

Unused.

dwParam1

The dwDeviceID of the newly-created device.

dwParam2

Unused.

dwParam3

Unused.

Return Values

No return value.

Remarks

Applications that negotiated API versoin 0x00010003 are sent a PHONE_STATE message specifying PHONESTATE_REINIT, which requires them to shut down their use of the API and call phoneInitialize again to obtain the new number of devices. However, TAPI version 1.4 and above do not require all applications to shut down before allowing applications to reinitialize; reinitialization can take place immediately when a new device is created.

Applications supporting TAPI version 0x00010004 or above are sent a PHONE_CREATE message. This informs them of the existence of the new device and its new device ID. The application can then choose whether or not to attempt working with the new device at its leisure.

See Also

PHONE_STATE, phoneInitialize, phoneInitializeEx


PHONE_DEVSPECIFIC

The implementation sends the PHONE_DEVSPECIFIC message to an application to notify the application about device-specific events occurring at the phone. The meaning of the message and the interpretation of the parameters is implementation-defined.

PHONE_DEVSPECIFIC
hPhone = (HPHONE) hPhoneDevice;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) DeviceSpecific1;

    dwParam2 = (DWORD) DeviceSpecific2;

    dwParam3 = (DWORD) DeviceSpecific3;

Parameters

hPhone

A handle to the phone device.

dwCallbackInstance

The application's callback instance provided when opening the phone device.

dwParam1

Device specific.

dwParam2

Device specific.

dwParam3

Device specific.

Return Values

No return value.


PHONE_REMOVE

The PHONE_REMOVE message is sent to inform an application of the removal (deletion from the system) of a phone device. Generally, this is not used for temporary removals, such as extraction of PCMCIA devices, but only for permanent removals in which the device would no longer be reported by the service provider if TAPI were reinitialized.

PHONE_REMOVE
    dwDevice = (DWORD) 0;

    dwCallbackInstance = (DWORD) 0;

    dwParam1 = (DWORD) dwDeviceID;

    dwParam2 = (DWORD) 0;

    dwParam3 = (DWORD) 0;

Parameters

dwDevice

Reserved; set to 0.

dwCallbackInstance

Reserved; set to 0.

dwParam1

Identifier of the phone device that was removed.

dwParam2

Reserved; set to 0.

dwParam3

Reserved; set to 0.

Return Values

No return value.

Comments and Backward Compatibility

Applications TAPI version 0x00020000 and above are sent a PHONE_REMOVE message. This informs them that the device has been removed from the system. The PHONE_REMOVE message will have been preceded by a PHONE_CLOSE message on each phone handle, if the application had the phone open. This message will be sent to all applications supporting TAPI version 0x00020000 or above which have called phoneInitializeEx, including those that do not have any phone devices open at the time.

Older applications (which negotiated TAPI version 0x00010004 or below) are sent a PHONE_STATE message specifying PHONESTATE_REMOVED, followed by a PHONE_CLOSE message. Unlike the PHONE_REMOVE message, however, these older applications can receive these messages only if they have the phone open when it is removed. If they do not have the phone open, their only indication that the device was removed would be receiving a PHONEERR_NODEVICE when they attempt to access the device.

After a device has been removed, any attempt to access the device by its device ID will result in a PHONEERR_NODEVICE error. After all TAPI applications have shutdown so that TAPI can restart, when TAPI is reinitialized, the removed device will no longer occupy a device ID.

Implementation Note  It is TAPI that will return this PHONEERR_NODEVICE after a PHONE_REMOVE message is received from a service provider; no further calls will be made to that service provider using that phone device ID.

See Also

PHONE_CLOSE, PHONE_STATE, phoneInitialize, phoneInitializeEx


PHONE_REPLY

The PHONE_REPLY message is sent to an application' to report the results of function call that completed asynchronously.

PHONE_REPLY
hPhone = (HPHONE) 0;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) idRequest;

    dwParam2 = (DWORD) Status;

    dwParam3 = (DWORD) 0;

Parameters

hDevice

Unused.

dwCallbackInstance

Returns the application's callback instance.

dwParam1

The request ID for which this is the reply.

dwParam2

The success or error indication. The application should cast this parameter into a LONG. Zero indicates success; a negative number indicates an error.

dwParam3

Unused.

Return Values

No return value.

Remarks

Functions that operate asynchronously return a positive request ID value to the application. This request ID is returned with the reply message to identify the request that was completed. The other parameter for the PHONE_REPLY message carries the success or failure indication. Possible errors are the same as those defined by the corresponding function. This message cannot be disabled.


PHONE_STATE

TAPI sends the PHONE_STATE message to an application whenever the status of a phone device changes.

PHONE_STATE
hPhone = (HPHONE) hPhoneDevice;

    dwCallbackInstance = (DWORD) hCallback;

    dwParam1 = (DWORD) PhoneState;

    dwParam2 = (DWORD) PhoneStateDetails;

    dwParam3 = (DWORD) 0;

Parameters

hPhone

A handle to the phone device.

dwCallbackInstance

The application's callback instance provided when opening the phone device.

dwParam1

The phone state that has changed. This parameter uses the following PHONESTATE_ constants:

PHONESTATE_OTHER

Phone-status items other than those listed below have changed. The application should check the current phone status to determine which items have changed.

PHONESTATE_CONNECTED

The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked or when the wire connecting the phone to the computer is plugged in with TAPI active.

PHONESTATE_DISCONNECTED

The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the computer is unplugged while TAPI is active.

PHONESTATE_OWNER

The number of owners for the phone device has changed.

PHONESTATE_MONITORS

The number of monitors for the phone device has changed.

PHONESTATE_DISPLAY

The display of the phone has changed.

PHONESTATE_LAMP

A lamp of the phone has changed.

PHONESTATE_RINGMODE

The ring mode of the phone has changed.

PHONESTATE_RINGVOLUME

The ring volume of the phone has changed.

PHONESTATE_HANDSETHOOKSWITCH

The handset hookswitch state has changed.

PHONESTATE_HANDSETVOLUME

The handset's speaker volume setting has changed.

PHONESTATE_HANDSETGAIN

The handset's microphone gain setting has changed.

PHONESTATE_SPEAKERHOOKSWITCH

The speakerphone's hookswitch state has changed.

PHONESTATE_SPEAKERVOLUME

The speakerphone's speaker volume setting has changed.

PHONESTATE_SPEAKERGAIN

The speakerphone's microphone gain setting state has changed.

PHONESTATE_HEADSETHOOKSWITCH

The headset's hookswitch state has changed.

PHONESTATE_HEADSETVOLUME

The headset's speaker volume setting has changed.

PHONESTATE_HEADSETGAIN

The headset's microphone gain setting has changed.

PHONESTATE_SUSPEND

The application's use of the phone device is temporarily suspended.

PHONESTATE_RESUME

The application's use of the phone device is resumed after having been suspended for some time.

PHONESTATE_DEVSPECIFIC

The phone's device-specific information has changed.

PHONESTATE_REINIT

Items have changed in the configuration of phone devices. To become aware of these changes (as with the appearance of new phone devices), the application should reinitialize its use of TAPI. The hDevice parameter of the PHONE_STATE message is left NULL for this state change as it applies to any of the phones in the system.

PHONESTATE_CAPSCHANGE

Indicates that, due to configuration changes made by the user or other circumstances, one or more of the fields in the PHONECAPS structure have changed. The application should use phoneGetDevCaps to read the updated structure.

PHONESTATE_REMOVED

Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A PHONE_STATE message with this value will normally be immediately followed by a PHONE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized will result in PHONEERR_NODEVICE being returned to the application. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 0x00010004 or higher; applications negotiating a previous API version will not receive any notification.

dwParam2

Phone-state-dependent information detailing the status change. This field is not used if multiple flags are set in dwParam1, because multiple status items have changed. The application should invoke phoneGetStatus to obtain complete set of information.

If dwParam1 is PHONESTATE_OWNER, dwParam2 contains the new number of owners.

If dwParam1 is PHONESTATE_MONITORS, dwParam2 contains the new number of monitors.

If dwParam1 is PHONESTATE_LAMP, dwParam2 contains the button/lamp ID of the lamp that has changed.

If dwParam1 is PHONESTATE_RINGMODE, dwParam2 contains the new ring mode.

If dwParam1 is PHONESTATE_HANDSET, SPEAKER or HEADSET, dwParam2 contains the new hookswitch mode of that hookswitch device. This parameter uses the following PHONEHOOKSWITCHMODE_ constants:

PHONEHOOKSWITCHMODE_ONHOOK

The device's microphone and speaker are both onhook.

PHONEHOOKSWITCHMODE_MIC

The device's microphone is active, the speaker is mute.

PHONEHOOKSWITCHMODE_SPEAKER

The device's speaker is active, the microphone is mute.

PHONEHOOKSWITCHMODE_MICSPEAKER

The device's microphone and speaker are both active.

dwParam3

Unused.

Return Values

No return value.

Remarks

Sending the PHONE_STATE message to the application can be controlled and queried using phoneSetStatusMessages and phoneGetStatusMessages. By default, this message is disabled for all state changes except for PHONESTATE_REINIT, which cannot be disabled. This message is sent to all applications that have a handle to the phone, including those that called phoneOpen with the dwPrivileges parameter set to PHONEPRIVILEGE_OWNER or PHONEPRIVILEGE_MONITOR.

A PHONE_STATE message with an Owners and/or Monitors indication is sent to applications that already have a handle for the phone. This can be the result of another application changing ownership or monitorship of the phone device with phoneOpen, phoneClose or phoneShutdown.

See Also

PHONE_CLOSE, PHONECAPS, phoneClose, phoneGetDevCaps, phoneGetStatus, phoneGetStatusMessages, phoneInitialize, phoneInitializeEx, phoneOpen, phoneSetStatusMessages, phoneShutdown


Assisted Telephony Messages

The following messages are used by Assisted Telephony.


Formatted Error Messages

This section discusses the TAPIERROR_FORMATMESSAGE() macro. This macro generates an identifier for standard TAPI error message text strings that can be obtained by Win32 applications using the Win32 FormatMessage() function.

This mechanism should be used only for displaying information on errors for which the application has no defined method of recovery (that is, unexpected or internal errors). In most cases (unlike the simplified example below), it is desirable to include additional text informing the user of actions the application will take (or the user should take) as a result of the unhandled error.

If the application gets an error result from any TAPI function, the error value can be passed through the TAPIERROR_FORMATMESSAGE() macro, which in turn generates the real value to be passed to FormatMessage(). FormatMessage() produces an error string corresponding to the error in a buffer. For example:

lResult = lineClose(hLine);

if (lResult < 0)

{

        FormatMessage(FORMAT_MESSAGE_FROM_HMODULE,

                    (LPCVOID)GetModuleHandle(“TAPI32.DLL”),

                    TAPIERROR_FORMATMESSAGE(lResult),

                    0,

                    (LPTSTR)pBuf,

                    BUFSIZE,

                    NULL);

        MessageBox(hWnd,pBuf,”TAPI ERROR”,MB_OK);

}


TAPI_REPLY

The TAPI_REPLY message is nonfunctional in Win32 -based applications and obsolete for all classes of Windows-based applications. It should not be used.


Quick Function Reference

The following is the quick function reference for basic telephony services, supplementary telephony services, assisted telephony, and extended telephony services.


Basic Telephony Services Functions

The Basic Telephony functions are listed by category in the following tables. A function is identified as asynchronous if it will indicate completion in a REPLY message to the application. If the function always returns its result to the application immediately, the function is considered synchronous.

TAPI Initialization and Shutdown

lineInitializeEx	Initializes the Telephony API line abstraction for use by the invoking application. Synchronous.
lineShutdown	Shuts down the application's use of the line Telephony API. Synchronous.
Line Version Negotiation

lineNegotiateAPIVersion	Allows an application to negotiate an API version to use. Synchronous.
Line Status and Capabilities

lineGetDevCaps	Returns the capabilities of a given line device. Synchronous.
lineGetDevConfig	Returns configuration of a media stream device. Synchronous.
lineGetLineDevStatus	Returns current status of the specified open line device. Synchronous.
lineSetDevConfig	Sets the configuration of the specified media stream device. Synchronous.
lineSetStatusMessages	Specifies the status changes for which the application wants to be notified. Synchronous.
lineGetStatusMessages	Returns the application's current line and address status message settings. Synchronous.
lineGetID	Retrieves a device ID associated with the specified open line, address, or call. Synchronous.
lineGetIcon	Allows an application to retrieve an icon for display to the user. Synchronous.
lineConfigDialog	Causes the provider of the specified line device to display a dialog box that allows the user to configure parameters related to the line device. Synchronous.
lineConfigDialogEdit	Displays a dialog box allowing the user to change configuration information for a line device. Synchronous. Version 0x00010004.
Addresses

lineGetAddressCaps	Returns the telephony capabilities of an address. Synchronous.
lineGetAddressStatus	Returns current status of a specified address. Synchronous.
lineGetAddressID	Retrieves the address ID of an address specified using an alternate format. Synchronous.
Opening and Closing Line Devices

lineOpen	Opens a specified line device for providing subsequent monitoring and/or control of the line. Synchronous.
lineClose	Closes a specified opened line device. Synchronous.
Address Formats

lineTranslateAddress	Translates between an address in canonical format and an address in dialable format. Synchronous.
lineSetCurrentLocation	Sets the location used as the context for address translation. Synchronous.
lineSetTollList	Manipulates the toll list. Synchronous.
lineGetTranslateCaps	Returns address translation capabilities. Synchronous.
Call States and Events

lineGetCallInfo	Returns mostly constant information about a call. Synchronous.
lineGetCallStatus	Returns complete call status information for the specified call. Synchronous.
lineSetAppSpecific	Sets the application-specific field of a call's information structure. Synchronous.
Request Recipient Services

These functions are used only in support of assisted telephony.

LineRegisterRequestRecipient	Registers or deregisters the application as a request recipient for the specified request mode. Synchronous.
lineGetRequest	Gets the next request from the Telephony DLL. Synchronous.
Making Calls

lineMakeCall	Makes an outbound call and returns a call handle for it. Asynchronous.
lineDial	Dials (parts of one or more) dialable addresses. Asynchronous.
Answering Inbound Calls

lineAnswer	Answers an inbound call. Asynchronous.
Toll Saver Support

lineSetNumRings	Indicates the number of rings after which inbound calls are to be answered. Synchronous.
lineGetNumRings	Returns the minimum number of rings requested with lineSetNumRings. Synchronous.
Call Privilege Control

lineSetCallPrivilege	Sets the application's privilege to the privilege specified. Synchronous.
Call Drop

lineDrop	Disconnects a call, or abandons a call attempt in progress. Asynchronous.
lineDeallocateCall	Deallocates the specified call handle. Synchronous.
Call Handle Manipulation

lineHandoff	Hands off call ownership and/or changes an application's privileges to a call. Synchronous.
lineGetNewCalls	Returns call handles to calls on a specified line or address for which the application does not yet have handles. Synchronous.
lineGetConfRelatedCalls	Returns a list of call handles that are part of the same conference call as the call specified as a parameter. Synchronous.
Location and Country Information

lineTranslateDialog	Displays a dialog box allowing the user to change location and calling card information. Synchronous. Version 0x00010004.
lineGetCountry	Retrieves dialing rules and other information about a given country. Synchronous. Version 0x00010004.


Supplementary Telephony Services Functions

The supplementary telephony functions are listed by category in the following tables. Line services are listed first, phone services next. A function is identified as asynchronous if it will indicate completion in a REPLY message to the application. If the function always returns its result to the application immediately, the function is considered synchronous.


Line Services

Bearer Mode and Rate

lineSetCallParams	Requests a change in the call parameters of an existing call. Synchronous.
Media Monitoring

lineMonitorMedia	Enables or disables media mode notification on a specified call. Synchronous.
Digit Monitoring and Gathering

lineMonitorDigits	Enables or disables digit detection notification on a specified call. Synchronous.
lineGatherDigits	Performs the buffered gathering of digits on a call. Synchronous.
Tone Monitoring

lineMonitorTones	Specifies which tones to detect on a specified call. Synchronous.
Media Control

lineSetMediaControl	Sets up a call's media stream for media control. Synchronous.
lineSetMediaMode	Sets the media mode(s) of the specified call in its LINECALLINFO structure. Synchronous.
Generating Inband Digits and Tones

lineGenerateDigits	Generates inband digits on a call. Synchronous.
lineGenerateTone	Generates a given set of tones inband on a call. Synchronous.
Call Accept and Redirect

lineAccept	Accepts an offered call and starts alerting both caller (ringback) and called party (ring). Asynchronous.
lineRedirect	Redirects an offering call to another address. Asynchronous.
Call Reject

lineDrop	See Call Drop table under Basic Telephony Services. Asynchronous.
Call Hold

lineHold	Places the specified call on hard hold. Asynchronous.
lineUnhold	Retrieves a held call. Asynchronous.
Making Calls

lineSecureCall	Secures an existing call from interference by other events such as call-waiting beeps on data connections. Asynchronous.
Call Transfer

lineSetupTransfer	Prepares a specified call for transfer to another address. Asynchronous.
lineCompleteTransfer	Transfers a call that was set up for transfer to another call, or enters a three-way conference. Asynchronous.
lineBlindTransfer	Transfers a call to another party. Asynchronous.
lineSwapHold	Swaps the active call with the call currently on consultation hold. Asynchronous.
Call Conference

lineSetupConference	Prepares a given call for the addition of another party. Asynchronous.
LinePrepareAddToConference	Prepares to add a party to an existing conference call by allocating a consultation call that can later be added to the conference call that is placed on conference hold. Asynchronous.
LineAddToConference	Adds a consultation call to an existing conference call. Asynchronous.
LineRemoveFromConference	Removes a party from a conference call. Asynchronous.
Call Park

linePark	Parks a given call at another address. Asynchronous.
lineUnpark	Retrieves a parked call. Asynchronous.
Call Forwarding

lineForward	Sets or cancels call forwarding requests. Asynchronous.
Call Pickup

linePickup	Picks up a call that is alerting at another number. Picks up a call alerting at another destination address and returns a call handle for the picked-up call (linePickup can also be used for call waiting). Asynchronous.
Sending Information to Remote Party

lineReleaseUserUserInfo	Releases user-to-user information, permitting the system to overwrite this storage with new information. Asynchronous. Version 0x00010004.
lineSendUserUserInfo	Sends user-to-user information to the remote party on the specified call. Asynchronous.
Call Completion

lineCompleteCall	Places a call completion request. Asynchronous.
lineUncompleteCall	Cancels a call completion request. Asynchronous.
Setting a Terminal for Phone Conversations

lineSetTerminal	Specifies the terminal device to which the specified line, address events, or call media stream events are routed. Asynchronous.
Application Priority

lineGetAppPriority	Retrieves handoff and/or Assisted Telephony priority information for an application. Synchronous. Version 0x00010004.
lineSetAppPriority	Sets the handoff and/or Assisted Telephony priority for an application. Synchronous. Version 0x00010004.
Service Provider Management

lineAddProvider	Installs a Telephony service provider. Synchronous. Version 0x00010004.
lineConfigProvider	Displays configuration dialog box of a service provider. Synchronous. Version 0x00010004.
lineRemoveProvider	Removes an existing Telephony service provider. Synchronous. Version 0x00010004.
lineGetProviderList	Retrieves a list of installed service providers. Synchronous. Version 0x00010004.
Agents

lineAgentSpecific	Allows the application to access proprietary handler-specific functions of the agent handler associated with the address. Asynchronous. Version 0x00020000.
LineGetAgentActivityList	Obtains the list of activities from which an application selects the functions an agent is performing. Asynchronous. Version 0x00020000.
lineGetAgentCaps	Obtains the agent-related capabilities supported on the specified line device. Asynchronous. Version 0x00020000.
LineGetAgentGroupList	Obtains the list of agent groups into which an agent can log into on the automatic call distributor. Asynchronous. Version 0x00020000.
lineGetAgentStatus	Obtains the agent-related status on the specified address. Asynchronous. Version 0x00020000.
lineSetAgentActivity	Sets the agent activity code associated with a particular address. Asynchronous. Version 0x00020000.
lineSetAgentGroup	Sets the agent groups into which the agent is logged into on a particular address. Asynchronous. Version 0x00020000.
lineSetAgentState	Sets the agent state associated with a particular address. Asynchronous. Version 0x00020000.
Proxies

lineProxyMessage	Used by a registered proxy request handler to generate TAPI messages. Synchronous. Version 0x00020000.
lineProxyResponse	Indicates completion of a proxy request by a registered proxy handler. Synchronous. Version 0x00020000.
Quality of Service

lineSetCallQualityOfService	Requests a change of the quality of service parameters for an existing call. Asynchronous. Version 0x00020000.
Miscellaneous

lineSetCallData	Sets the CallData member of the LINECALLINFO structure. Asynchronous. Version 0x00020000.
lineSetCallTreatment	Sets the sounds the user hears when a call is unanswered or on hold. Asynchronous. Version 0x00020000. lineSetLineDevStatus
	Sets the line device status. Asynchronous. Version 0x00020000.


Phone Services

TAPI Initialization and Shutdown

phoneInitializeEx	Initializes the Telephony API phone abstraction for use by the invoking application. Synchronous.
phoneShutdown	Shuts down the application's use of the phone Telephony API. Synchronous.
Phone Version Negotiation

phoneNegotiateAPIVersion	Allows an application to negotiate an API version to use. Synchronous.
Opening and Closing Phone Devices

phoneOpen	Opens the specified phone device, giving the application either owner or monitor privileges. Synchronous.
phoneClose	Closes a specified open phone device. Synchronous.
Phone Status and Capabilities

phoneGetDevCaps	Returns the capabilities of a given phone device. Synchronous.
phoneGetID	Returns a device ID for the given device class associated with the specified phone device. Synchronous.
phoneGetIcon	Allows an application to retrieve an icon for display to the user. Synchronous.
phoneConfigDialog	Causes the provider of the specified phone device to display a dialog box that allows the user to configure parameters related to the phone device. Synchronous.
Hookswitch Devices

phoneSetHookSwitch	Sets the hookswitch mode of one or more of the hookswitch devices of an open phone device. Asynchronous.
phoneGetHookSwitch	Queries the hookswitch mode of a hookswitch device of an open phone device. Synchronous.
phoneSetVolume	Sets the volume of a hookswitch device's speaker of an open phone device. Asynchronous.
phoneGetVolume	Returns the volume setting of a hookswitch device's speaker of an open phone device. Synchronous.
phoneSetGain	Sets the gain of a hookswitch device's mic of an open phone device. Asynchronous.
phoneGetGain	Returns the gain setting of a hookswitch device's mic of an opened phone. Synchronous.
Display

phoneSetDisplay	Writes information to the display of an open phone device. Asynchronous.
phoneGetDisplay	Returns the current contents of a phone's display. Synchronous.
Ring

phoneSetRing	Rings an open phone device according to a given ring mode. Asynchronous.
phoneGetRing	Returns the current ring mode of an opened phone device. Synchronous.
Buttons

phoneSetButtonInfo	Sets the information associated with a button on a phone device. Asynchronous.
phoneGetButtonInfo	Returns information associated with a button on a phone device. Synchronous.
Lamps

phoneSetLamp	Lights a lamp on a specified open phone device in a given lamp lighting mode. Asynchronous.
phoneGetLamp	Returns the current lamp mode of the specified lamp. Synchronous.
Data Areas

phoneSetData	Downloads a buffer of data to a given data area in the phone device. Asynchronous.
phoneGetData	Uploads the contents of a given data area in the phone device to a buffer. Synchronous.
Status

phoneSetStatusMessages	Specifies the status changes for which the application wants to be notified. Synchronous.
phoneGetStatusMessages	Returns the status changes for which the application wants to be notified. Synchronous.
phoneGetStatus	Returns the complete status of an open phone device. Synchronous.


Assisted Telephony Services Functions

The Assisted Telephony Services functions are:

tapiRequestMakeCall	Submits a request to place a voice call.
tapiRequestMediaCall	Obsolete. Do not use.
tapiRequestDrop	Obsolete. Do not use.
tapiGetLocationInfo	Returns country code and city/area code information.


Extended Telephony Services Functions

The following tables list by category the extended telephony functions for both line and phone devices.

Extended Line Services

lineNegotiateExtVersion	Allows an application to negotiate an extension version to use with the specified line device. Asynchronous.
lineDevSpecific	Device-specific escape function. Synchronous.
lineDevSpecificFeature	Device-specific escape function to allow sending switch features to the switch. Asynchronous.
Extended Phone Services

phoneDevSpecific	Device-specific escape function to allow vendor-dependent extensions. Asynchronous.
PhoneNegotiateExtVersion	Allows an application to negotiate an extension version to use with the specified phone device. Synchronous.


Structures

This section contains the reference for structures for line devices and phone devices.


Line Device Structures

The following topics describe the data structures used by the Telephony API. They are listed in alphabetical order.


Memory Allocation

Memory for all data structures used by the API must be allocated by the application. The application passes a pointer to the API function that returns the information, and the function fills the data structure with the requested information. If the operation is asynchronous, then the information is not available until the asynchronous reply message indicates success.

All data structures used to pass information between the application and the Telephony API are flattened. This means that data structures do not contain pointers to substructures that contain variably sized components of information. Instead, data structures that are used to pass variable amounts of information back to the application have the following meta structure:

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

      <fixed size fields>

    DWORD  dw<VarSizeField1>Size;

    DWORD  dw<VarSizeField1>Offset;

      <fixed size fields>

    DWORD  dw<VarSizeField2>Size;

    DWORD  dw<VarSizeField2>Offset;

      <common extensions>

      <var sized field1>

      <var sized field2>

The dwTotalSize field is the size in bytes allocated to this data structure. It marks the end of the data structure and is set by the application before it invokes the function that uses this data structure. The function will not read or write beyond this size. An application must set the dwTotalSize field to indicate the total number of bytes allocated for TAPI to return the contents of the structure.

The dwNeededSize field is filled in by TAPI. It indicates how many bytes are needed to return all the information requested. The existence of variably sized fields often makes it impossible for the application to estimate the data structure size it needs to allocate. This field simply returns the number of bytes actually needed for the information. This number could be smaller than, equal to, or larger than dwTotalSize, and it includes space for the dwTotalSize field itself. If larger, the returned structure is only partially filled. If the fields the application is interested in are available in the partial structure, nothing else must be done. Otherwise, the application should allocate a structure at least the size of dwNeededSize and invoke the function again. Usually, enough space will be available this time to return all the information, although it is possible the size could have increased again.

The dwUsedSize field is filled in by TAPI if it returns information to the application to indicate the actual size in bytes of the portion of the data structure that contains useful information. If, for example, a structure that was allocated was too small and the truncated field is a variably sized field, dwNeededSize will be larger than dwTotalSize, and the truncated field will be left empty. The dwUsedSize field could therefore be smaller than dwTotalSize. Partial field values are not returned.

Following this header is the fixed part of the data structure. It contains regular fields and size/offset pairs that describe the actual variably sized fields. The offset field contains the offset in bytes of the variably sized field from the beginning of the record. The size field contains the size in bytes of the variably sized field. If a variably sized field is empty, then the size field is zero and the offset is set to zero. Variably sized fields that would be truncated if the total structure size is insufficient are left empty. That is, their size field is set to zero and the offset is set to zero. The variably sized fields follow the fixed fields.


Variably Sized Data Structures

When variably sized data structures are used to transmit information between TAPI and the application, the application is responsible for allocating the necessary memory. The amount of memory allocated must be at least large enough for the fixed portion of the data structure, and is set by the application in the dwTotalSize field of the data structure. The dwUsedSize and dwNeededSize fields are filled in by TAPI. If dwTotalSize is less than the size of the fixed portion, then LINEERR/ PHONEERR_STRUCTURETOOSMALL is returned. If a function returns success, then all the fields in the fixed portion have been filled in. The dwUsedSize and dwNeededSize fields can be compared to determine if all variable parts have been filled in, and how much space would be required to fill them all in.

If dwNeededSize is equal to dwUsedSize, then all fixed and variable parts have been filled in. If dwNeededSize is larger than dwUsedSize, some variable parts may have been filled in, but exactly which variably sized fields have been filled in is undefined. No variable part is ever truncated, and variable parts that would have been truncated due to insufficient space are indicated by having both of their corresponding "Offset" and "Size" parts set to zero. If these are not both zero (and no error was returned), they indicate the offset and size of valid, nontruncated variable-part data.

An application can always guarantee that all variable parts are filled in by allocating and indicating dwNeededSize bytes for the structure and calling the "Get" function again until the function returns success and dwNeededSize "covers" dwUsedSize. This should happen on the second try except for race conditions that cause changes in the size of variable parts between calls, which should be a rare occurrence.

Note  All ASCII, DBCS, and Unicode strings that occur in variable-sized structures should be NULL-terminated according to normal C string handling conventions.


Extensibility

Provisions are made for extending constants and structures both in a device-independent way and in a device-specific (vendor-specific) way. In constants that are scalar enumerations, a range of values is reserved for future common extensions. The remainder of values are identified as device specific. A vendor can define meanings for these values in any way desired. Their interpretation is keyed to the extension ID provided in the LINEDEVCAPS data structure. For constants that are defined as bit flags, a range of low-order bits are reserved, where the high-order bits can be extension specific. It is recommended that extended values and bit arrays use bits from the highest value or high-order bit down. This leaves the option to move the border between the common portion and extension portion if there is a need to do so in the future. Extensions to data structures are assigned a variably sized field with size/offset being part of the fixed part. TAPI describes for each data structure what device-specific extensions are allowed.

In addition to recognizing a specific extension ID, the application must negotiate the extension version number that the application and the service provider will operate under. This is done in the second version negotiation phase of the lineGetDevCaps function.

An extension ID is a globally unique identifier. There is no central registry for extension IDs. Instead, they are generated locally by the manufacturer by a utility that is available with the toolkit. The number is made up of parts such as a unique LAN address, time of day, and random number, to guarantee global uniqueness. Globally Unique Identifiers are designed to be distinguishable from HP/DEC universally unique identifiers and are thus fully compatible with them.


LINEADDRESSCAPS

The LINEADDRESSCAPS structure describes the capabilities of a specified address.

typedef struct lineaddresscaps_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwLineDeviceID;

    DWORD  dwAddressSize;

    DWORD  dwAddressOffset;

    DWORD  dwDevSpecificSize;

    DWORD  dwDevSpecificOffset;

    DWORD  dwAddressSharing;

    DWORD  dwAddressStates;

    DWORD  dwCallInfoStates;

    DWORD  dwCallerIDFlags;

    DWORD  dwCalledIDFlags;

    DWORD  dwConnectedIDFlags;

    DWORD  dwRedirectionIDFlags;

    DWORD  dwRedirectingIDFlags;

    DWORD  dwCallStates;

    DWORD  dwDialToneModes;

    DWORD  dwBusyModes;

    DWORD  dwSpecialInfo;

    DWORD  dwDisconnectModes;

    DWORD  dwMaxNumActiveCalls;

    DWORD  dwMaxNumOnHoldCalls;

    DWORD  dwMaxNumOnHoldPendingCalls;

    DWORD  dwMaxNumConference;

    DWORD  dwMaxNumTransConf;

    DWORD  dwAddrCapFlags;

    DWORD  dwCallFeatures;

    DWORD  dwRemoveFromConfCaps;

    DWORD  dwRemoveFromConfState;

    DWORD  dwTransferModes;

    DWORD  dwParkModes;

    DWORD  dwForwardModes;

    DWORD  dwMaxForwardEntries;

    DWORD  dwMaxSpecificEntries;

    DWORD  dwMinFwdNumRings;

    DWORD  dwMaxFwdNumRings;

    DWORD  dwMaxCallCompletions;

    DWORD  dwCallCompletionConds;

    DWORD  dwCallCompletionModes;

    DWORD  dwNumCompletionMessages;

    DWORD  dwCompletionMsgTextEntrySize;

    DWORD  dwCompletionMsgTextSize;

    DWORD  dwCompletionMsgTextOffset;

    DWORD  dwAddressFeatures;

    DWORD  dwPredictiveAutoTransferStates;

    DWORD  dwNumCallTreatments;

    DWORD  dwCallTreatmentListSize;

    DWORD  dwCallTreatmentListOffset;

    DWORD  dwDeviceClassesSize;

    DWORD  dwDeviceClassesOffset;

    DWORD  dwMaxCallDataSize;

    DWORD  dwCallFeatures2;

    DWORD  dwMaxNoAnswerTimeout;

    DWORD  dwConnectedModes;

    DWORD  dwOfferingModes;

    DWORD  dwAvailableMediaModes;

} LINEADDRESSCAPS, FAR *LPLINEADDRESSCAPS;

Members

dwTotalSize

The total size in bytes allocated to this data structure.

dwNeededSize

The size in bytes for this data structure that is needed to hold all the returned information.

dwUsedSize

The size in bytes of the portion of this data structure that contains useful information.

dwLineDeviceID

The device ID of the line device with which this address is associated.

dwAddressSize

dwAddressOffset

The size in bytes of the variably sized address field and the offset in bytes from the beginning of this data structure.

dwDevSpecificSize

dwDevSpecificOffset

The size in bytes of the variably sized device-specific field and the offset in bytes from the beginning of this data structure.

dwAddressSharing

The sharing mode of the address. Values are:

LINEADDRESSSHARING_PRIVATE

An address with private sharing mode is only assigned to a single line or station.

LINEADDRESSSHARING_BRIDGEDEXCL

An address with a bridged-exclusive sharing mode is assigned to one or more other lines or stations. The exclusive portion refers to the fact that only one of the bridged parties can be connected with a remote party at any given time.

LINEADDRESSSHARING_BRIDGEDNEW

An address with a bridged-new sharing mode is assigned to one or more other lines or stations. The new portion refers to the fact that activities by the different bridged parties result in the creation of new calls on the address.

LINEADDRESSSHARING_BRIDGEDSHARED

An address with a bridged-shared sharing mode is also assigned to one or more other lines or stations. The shared portion refers to the fact that if one of the bridged parties is connected with a remote party, the remaining bridged parties can share in the conversation (as in a conference) by activating that call appearance.

LINEADDRESSSHARING_MONITORED

An address with a monitored address mode simply monitors the status of that address. The status is either idle or in use. The message LINE_ADDRESSSTATE notifies the application about these changes.

dwAddressStates

This field contains the address states changes for which the application may get notified in the LINE_ADDRESSSTATE message. It uses the following LINEADDRESSSTATE_ constants:

LINEADDRESSSTATE_OTHER

Address status items other than those listed below have changed. The application should check the current address status to determine which items have changed.

LINEADDRESSSTATE_DEVSPECIFIC

The device-specific item of the address status has changed.

LINEADDRESSSTATE_INUSEZERO

The address has changed to idle (it is not in use by any stations).

LINEADDRESSSTATE_INUSEONE

The address has changed from being idle or from being in use by many bridged stations to being in use by just one station.

LINEADDRESSSTATE_INUSEMANY

The monitored or bridged address has changed to being in use by one station to being used by more than one station.

LINEADDRESSSTATE_NUMCALLS

The number of calls on the address has changed. This is the result of events such as a new inbound call, an outbound call on the address, or a call changing its hold status.

LINEADDRESSSTATE_FORWARD

The forwarding status of the address has changed, including the number of rings for determining a "no answer" condition. The application should check the address status to retrieve details about the address's current forwarding status.

LINEADDRESSSTATE_TERMINALS

The terminal settings for the address have changed.

LINEADDRESSSTATE_CAPSCHANGE

Indicates that, due to configuration changes made by the user or other circumstances, one or more of the fields in the LINEADDRESSCAPS structure for the address have changed. The application should use lineGetAddressCaps to read the updated structure. If a service provider sends a LINE_ADDRESSSTATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI in order to obtain the updated information.

dwCallInfoStates

This field describes the call information elements that are meaningful for all calls on this address. An application may get notified about changes in some of these states in LINE_CALLINFO messages. It uses the following LINECALLINFOSTATE_ constants:

LINECALLINFOSTATE_OTHER

Call information items other than those listed below have changed. The application should check the current call information to determine which items have changed.

LINECALLINFOSTATE_DEVSPECIFIC

The device-specific field of the call information.

LINECALLINFOSTATE_BEARERMODE

The bearer mode field of the call information record.

LINECALLINFOSTATE_RATE

The rate field of the call information record.

LINECALLINFOSTATE_MEDIAMODE

The media-mode field of the call information record.

LINECALLINFOSTATE_APPSPECIFIC

The application-specific field of the call information record.

LINECALLINFOSTATE_CALLID

The call ID field of the call information record.

LINECALLINFOSTATE_RELATEDCALLID

The related call ID field of the call information record.

LINECALLINFOSTATE_ORIGIN

The origin field of the call information record.

LINECALLINFOSTATE_REASON

The reason field of the call information record.

LINECALLINFOSTATE_COMPLETIONID

The completion ID field of the call information record.

LINECALLINFOSTATE_NUMOWNERINCR

The number of owner field in the call information record was increased.

LINECALLINFOSTATE_NUMOWNERDECR

The number of owner field in the call information record was decreased.

LINECALLINFOSTATE_NUMMONITORS

The number of monitors field in the call information record has changed.

LINECALLINFOSTATE_TRUNK

The trunk field of the call information record has changed.

LINECALLINFOSTATE_CALLERID

One of the callerID-related fields of the call information record has changed.

LINECALLINFOSTATE_CALLEDID

One of the calledID-related fields of the call information record has changed.

LINECALLINFOSTATE_CONNECTEDID

One of the connectedID-related fields of the call information record has changed.

LINECALLINFOSTATE_REDIRECTIONID

One of the redirectionID-related fields of the call information record has changed.

LINECALLINFOSTATE_REDIRECTINGID

One of the redirectingID-related fields of the call information record has changed.

LINECALLINFOSTATE_DISPLAY

The display field of the call information record.

LINECALLINFOSTATE_USERUSERINFO

The user-to-user information of the call information record.

LINECALLINFOSTATE_HIGHLEVELCOMP

The high-level compatibility field of the call information record.

LINECALLINFOSTATE_LOWLEVELCOMP

The low-level compatibility field of the call information record.

LINECALLINFOSTATE_CHARGINGINFO

The charging information of the call information record.

LINECALLINFOSTATE_TERMINAL

The terminal mode information of the call information record.

LINECALLINFOSTATE_DIALPARAMS

The dial parameters of the call information record.

LINECALLINFOSTATE_MONITORMODES

One or more of the digit, tone, or media monitoring fields in the call information record has changed.

dwCallerIDFlags

dwCalledIDFlags

dwConnectedIDFlags

dwRedirectionIDFlags

dwRedirectingIDFlags

These fields describe the various party ID information types that may be provided for calls on this address. It uses the following LINECALLPARTYID_ constants:

LINECALLPARTYID_BLOCKED

Caller ID information for the call has been blocked by the caller but would otherwise have been available.

LINECALLPARTYID_OUTOFAREA

Caller ID information for the call is not available because it is not propagated all the way by the network.

LINECALLPARTYID_NAME

The caller ID information for the call is the caller's name (from a table maintained inside the switch). It is provided in the caller ID name variably sized field.

LINECALLPARTYID_ADDRESS

The caller ID information for the call is the caller's number and is provided in the caller ID variably sized field.

LINECALLPARTYID_PARTIAL

Caller ID information for the call is valid but is limited to partial number information.

LINECALLPARTYID_UNKNOWN

Caller ID information is currently unknown; it may become known later.

LINECALLPARTYID_UNAVAIL

Caller ID information is unavailable and will not become known later.

dwCallStates

This field describes the various call states that can possibly be reported for calls on this address. This parameter uses the following LINECALLSTATE_ constants:

LINECALLSTATE_IDLE

The call is idle—no call exists.

LINECALLSTATE_OFFERING

The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user; alerting is done by the switch instructing the line to ring. It does not affect any call states.

LINECALLSTATE_ACCEPTED

The call was offering and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also initiates alerting to both parties.

LINECALLSTATE_DIALTONE

The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.

LINECALLSTATE_DIALING

Destination address information (a phone number) is being sent to the switch over the call. Note that the operation lineGenerateDigits does not place the line into the dialing state.

LINECALLSTATE_RINGBACK

The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.

LINECALLSTATE_BUSY

The call is receiving a busy tone. Busy tone indicates that the call cannot be completed—either a circuit (trunk) or the remote party's station are in use.

LINECALLSTATE_SPECIALINFO

Special information is sent by the network. Special information is typically sent when the destination cannot be reached.

LINECALLSTATE_CONNECTED

The call has been established and the connection is made. Information is able to flow over the call between the originating address and the destination address.

LINECALLSTATE_PROCEEDING

Dialing has completed and the call is proceeding through the switch or telephone network.

LINECALLSTATE_ONHOLD

The call is on hold by the switch.

LINECALLSTATE_CONFERENCED

The call is currently a member of a multiparty conference call.

LINECALLSTATE_ONHOLDPENDCONF

The call is currently on hold while it is being added to a conference.

LINECALLSTATE_ONHOLDPENDTRANSF

The call is currently on hold awaiting transfer to another number.

LINECALLSTATE_DISCONNECTED

The remote party has disconnected from the call.

LINECALLSTATE_UNKNOWN

The state of the call is not known. This may be due to limitations of the call progress detection implementation.

dwDialToneModes

This field describes the various dial tone modes that can possibly be reported for calls made on this address. This field is meaningful only if the dialtone call state can be reported. It uses the following LINEDIALTONEMODE_ constants:

LINEDIALTONEMODE_NORMAL

This is a "normal" dial tone, which typically is a continuous tone.

LINEDIALTONEMODE_SPECIAL

This is a special dial tone indicating a certain condition is currently in effect.

LINEDIALTONEMODE_INTERNAL

This is an internal dial tone, as within a PBX.

LINEDIALTONEMODE_EXTERNAL

This is an external (public network) dial tone.

LINEDIALTONEMODE_UNKNOWN

The dial tone mode is currently unknown but may become known later.

LINEDIALTONEMODE_UNAVAIL

The dial tone mode is unavailable and will not become known.

wBusyModes

This field describes the various busy modes that can possibly be reported for calls made on this address. This field is meaningful only if the busy call state can be reported. It uses the following LINEBUSYMODE_ constants:

LINEBUSYMODE_STATION

The busy signal indicates that the called party's station is busy. This is usually signaled with a "normal" busy tone.

LINEBUSYMODE_TRUNK

The busy signal indicates that a trunk or circuit is busy. This is usually signaled with a "long" busy tone.

LINEBUSYMODE_UNKNOWN

The busy signal's specific mode is currently unknown but may become known later.

LINEBUSYMODE_UNAVAIL

The busy signal's specific mode is unavailable and will not become known.

dwSpecialInfo

This field describes the various special information types that can possibly be reported for calls made on this address. This field is meaningful only if the specialInfo call state can be reported. It uses the following LINESPECIALINFO_ constants:

LINESPECIALINFO_NOCIRCUIT

This special information tone precedes a no-circuit or emergency announcement (trunk blockage category).

LINESPECIALINFO_CUSTIRREG

This special information tone precedes a vacant number, AIS, Centrex number change and nonworking station, access code not dialed or dialed in error, manual intercept operator message (customer irregularity category).

LINESPECIALINFO_REORDER

This special information tone precedes a reorder announcement (equipment irregularity category).

LINESPECIALINFO_UNKNOWN

Specifics about the special information tone are currently unknown but may become known later.

LINESPECIALINFO_UNAVAIL

Specifics about the special information tone are unavailable and will not become known.

dwDisconnectModes

This field describes the various disconnect modes that can possibly be reported for calls made on this address. This field is meaningful only if the disconnected call state can be reported. It uses the following LINEDISCONNECTMODE_ constants:

LINEDISCONNECTMODE_NORMAL

This is a "normal" disconnect request by the remote party; the call was terminated normally.

LINEDISCONNECTMODE_UNKNOWN

The reason for the disconnect request is unknown.

LINEDISCONNECTMODE_REJECT

The remote user has rejected the call.

LINEDISCONNECTMODE_PICKUP

The call was picked up from elsewhere.

LINEDISCONNECTMODE_FORWARDED

The call was forwarded by the switch.

LINEDISCONNECTMODE_BUSY

The remote user's station is busy.

LINEDISCONNECTMODE_NOANSWER

The remote user's station does not answer.

LINEDISCONNECTMODE_NODIALTONE

A dial tone was not detected within a service-provider defined timeout, at a point during dialing when one was expected (such as at a "W" in the dialable string). This can also occur without a service-provider-defined timeout period or without a value specified in the dwWaitForDialTone member of the LINEDIALPARAMS structure.

LINEDISCONNECTMODE_BADADDRESS

The destination address in invalid.

LINEDISCONNECTMODE_UNREACHABLE

The remote user could not be reached.

LINEDISCONNECTMODE_CONGESTION

The network is congested.

LINEDISCONNECTMODE_INCOMPATIBLE

The remote user's station equipment is incompatible with the type of call requested.

LINEDISCONNECTMODE_UNAVAIL

The reason for the disconnect is unavailable and will not become known later.

dwMaxNumActiveCalls

This field contains the maximum number of active call appearances that the address can handle. This number does not include calls on hold or calls on hold pending transfer or conference.

dwMaxNumOnHoldCalls

This field contains the maximum number of call appearances at the address that can be on hold.

dwMaxNumOnHoldPendingCalls

This field contains the maximum number of call appearances at the address that can be on hold pending transfer or conference.

dwMaxNumConference

This field contains the maximum number of parties that can be conferenced in a single conference call on this address.

dwMaxNumTransConf

This field specifies the number of parties (including "self") that can be added in a conference call that is initiated as a generic consultation call using lineSetupTransfer.

dwAddrCapFlags

This field contains a series of packed bit flags that describe a variety of address capabilities. It uses the following LINEADDRCAPFLAGS_ constants:

LINEADDRCAPFLAGS_FWDNUMRINGS

Specifies whether the number of rings for a "no answer" can be specified when forwarding calls on no answer.

LINEADDRCAPFLAGS_PICKUPGROUPID

Specifies whether or not a group ID is required for call pickup.

LINEADDRCAPFLAGS_SECURE

Specifies whether or not calls on this address can be made secure at call-setup time.

LINEADDRCAPFLAGS_BLOCKIDDEFAULT

Specifies whether the network by default sends or blocks caller ID information when making a call on this address. If TRUE, ID information is blocked by default; if FALSE, ID information is transmitted by default.

LINEADDRCAPFLAGS_BLOCKIDOVERRIDE

Specifies whether the default setting for sending or blocking of caller ID information can be overridden per call. If TRUE, override is possible; if FALSE, override is not possible.

LINEADDRCAPFLAGS_DIALED

Specifies whether a destination address can be dialed on this address for making a call. TRUE if a destination address must be dialed; FALSE if the destination address is fixed (as with a "hot phone").

LINEADDRCAPFLAGS_ORIGOFFHOOK

Specifies whether the originating party's phone can automatically be taken offhook when making calls.

LINEADDRCAPFLAGS_DESTOFFHOOK

Specifies whether the called party's phone can automatically be forced offhook when making calls.

LINEADDRCAPFLAGS_FWDCONSULT

Specifies whether call forwarding involves the establishment of a consultation call.

LINEADDRCAPFLAGS_SETUPCONFNULL

Specifies whether setting up a conference call starts out with an initial call (FALSE) or with no initial call (TRUE).

LINEADDRCAPFLAGS_AUTORECONNECT

Specifies whether dropping a consultation call automatically reconnects to the call on consultation hold. TRUE if reconnect happens automatically; otherwise, FALSE.

LINEADDRCAPFLAGS_COMPLETIONID

Specifies whether the completion IDs returned by lineCompleteCall are useful and unique. TRUE is useful; otherwise, FALSE.

LINEADDRCAPFLAGS_TRANSFERHELD

Specifies whether a (hard) held call can be transferred. Often, only calls on consultation hold may be able to be transferred.

LINEADDRCAPFLAGS_CONFERENCEHELD

Specifies whether a (hard) held call can be conferenced to. Often, only calls on consultation hold may be able to be added to as a conference call.

LINEADDRCAPFLAGS_ PARTIALDIAL

Specifies whether partial dialing is available.

LINEADDRCAPFLAGS_FWDSTATUSVALID

Specifies whether the forwarding status in the LINEADDRESSSTATUS structure for this address is valid.

LINEADDRCAPFLAGS_ FWDINTEXTADDR

Specifies whether internal and external calls can be forwarded to different forwarding addresses. This flag is meaningful only if forwarding of internal and external calls can be controlled separately. It is TRUE if internal and external calls can be forwarded to different destination addresses; otherwise, FALSE.

LINEADDRCAPFLAGS_ FWDBUSYNAADDR

Specifies whether call forwarding for busy and for no answer can use different forwarding addresses. This flag is meaningful only if forwarding for busy and for no answer can be controlled separately. It is TRUE if forwarding for busy and for no answer can use different destination addresses; otherwise, FALSE.

LINEADDRCAPFLAGS_ACCEPTTOALERT

TRUE if an offering call must be accepted using lineAccept to start alerting the users at both ends of the call; otherwise, FALSE. Typically, this is only used with ISDN.

LINEADDRCAPFLAGS_CONFDROP

TRUE if invoking lineDrop on a conference call parent also has the side effect of dropping (disconnecting) the other parties involved in the conference call; FALSE if dropping a conference call still allows the other parties to talk among themselves.

LINEADDRCAPFLAGS_ PICKUPCALLWAIT

TRUE if linePickup can be used to pick up a call detected by the user as a "call waiting" call; otherwise FALSE.

dwCallFeatures

This field specifies the switching capabilities or features available for all calls on this address using the LINECALLFEATURE_ constants. This member represents the call-related features which may possibly be available on an address (static availability as opposed to dynamic availability). Invoking a supported feature requires the call to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the application has the right privileges to the call and the call is in the appropriate state for the operation to be meaningful. This field allows an application to discover which call features can be (and which can never be) supported by the address.

dwRemoveFromConfCaps

This field specifies the address's capabilities for removing calls from a conference call. It uses the following LINEREMOVEFROMCONF_ constants:

LINEREMOVEFROMCONF_NONE

Parties cannot be removed from the conference call.

LINEREMOVEFROMCONF_LAST

Only the most recently added party can be removed from the conference call.

LINEREMOVEFROMCONF_ANY

Any participating party can be removed from the conference call.

dwRemoveFromConfState

This field uses the LINECALLSTATE_ constants to specify the state of the call after it has been removed from a conference call.

dwTransferModes

This field specifies the address's capabilities for resolving transfer requests. It uses the following LINETRANSFERMODE_ constants:

LINETRANSFERMODE_TRANSFER

Resolve the initiated transfer by transferring the initial call to the consultation call.

LINETRANSFERMODE_CONFERENCE

Resolve the initiated transfer by conferencing all three parties into a three-way conference call. A conference call is created and returned to the application.

dwParkModes

This field specifies the different call park modes available at this address. It uses the LINEPARKMODE_ constants:

LINEPARKMODE_DIRECTED

Specifies directed call park. The address where the call is to be parked must be supplied to the switch.

LINEPARKMODE_NONDIRECTED

Specifies nondirected call park. The address where the call is parked is selected by the switch and provided by the switch to the application.

dwForwardModes

This field specifies the different modes of forwarding available for this address. It uses the following LINEFORWARDMODE_ constants:

LINEFORWARDMODE_UNCOND

Forward all calls unconditionally, irrespective of their origin. Use this value when unconditional forwarding for internal and external calls cannot be controlled separately. Unconditional forwarding overrides forwarding on busy and/or no answer conditions.

LINEFORWARDMODE_UNCONDINTERNAL

Forward all internal calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.

LINEFORWARDMODE_UNCONDEXTERNAL

Forward all external calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.

LINEFORWARDMODE_UNCONDSPECIFIC

Forward all calls that originated at a specified address unconditionally (selective call forwarding).

LINEFORWARDMODE_BUSY

Forward all calls on busy, irrespective of their origin. Use this value when forwarding for internal and external calls on busy and on no answer cannot be controlled separately.

LINEFORWARDMODE_BUSYINTERNAL

Forward all internal calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.

LINEFORWARDMODE_BUSYEXTERNAL

Forward all external calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.

LINEFORWARDMODE_BUSYSPECIFIC

Forward all calls that originated at a specified address on busy (selective call forwarding).

LINEFORWARDMODE_NOANSW

Forward all calls on no answer, irrespective of their origin. Use this value when call forwarding for internal and external calls on no answer cannot be controlled separately.

LINEFORWARDMODE_NOANSWINTERNAL

Forward all internal calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.

LINEFORWARDMODE_NOANSWEXTERNAL

Forward all external calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.

LINEFORWARDMODE_NOANSWSPECIFIC

Forward all calls that originated at a specified address on no answer (selective call forwarding).

LINEFORWARDMODE_BUSYNA

Forward all calls on busy/no answer, irrespective of their origin. Use this value when forwarding for internal and external calls on busy and on no answer cannot be controlled separately.

LINEFORWARDMODE_BUSYNAINTERNAL

Forward all internal calls on busy/no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.

LINEFORWARDMODE_BUSYNAEXTERNAL

Forward all external calls on busy/no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.

LINEFORWARDMODE_BUSYNASPECIFIC

Forward all calls that originated at a specified address on busy/no answer (selective call forwarding).

dwMaxForwardEntries

Specifies the maximum number of entries that can be passed to lineForward in the lpForwardList parameter.

dwMaxSpecificEntries

Specifies the maximum number of entries in the lpForwardList parameter passed to lineForward that can contain forwarding instructions based on a specific caller ID (selective call forwarding). This field is zero if selective call forwarding is not supported.

dwMinFwdNumRings

Specifies the minimum number of rings that can be set to determine when a call is officially considered "no answer."

dwMaxFwdNumRings

Specifies the maximum number of rings that can be set to determine when a call is officially considered "no answer." If this number of rings cannot be set, then dwMinFwdNumRings and dwMaxNumRings will be equal.

dwMaxCallCompletions

Specifies the maximum number of concurrent call completion requests that can be outstanding on this line device. Zero implies that call completion is not available.

dwCallCompletionCond

Specifies the different call conditions under which call completion can be requested. This field uses the following LINECALLCOMPLCOND_ constants:

LINECALLCOMPLCOND_BUSY

Complete the call under the busy condition.

LINECALLCOMPLCOND_NOANSWER

Complete the call under the ringback no answer condition.

dwCallCompletionModes

Specifies the way in which the call can be completed. This field uses the following LINECALLCOMPLCOND_ constants:

LINECALLCOMPLMODE_CAMPON

Queues the call until the call can be completed.

LINECALLCOMPLMODE_CALLBACK

Requests the called station to return the call when it returns to idle.

LINECALLCOMPLMODE_INTRUDE

Adds the application to the existing call at the called station if busy (barge in).

LINECALLCOMPLMODE_MESSAGE

Leave a short predefined message for the called station (Leave Word Calling). A specific message can be identified.

dwNumCompletionMessages

Specifies the number of call completion messages that can be selected from when using the LINECALLCOMPLMODE_MESSAGE option. Individual messages are identified by values in the range 0 through one less than dwNumCompletionMessages.

dwCompletionMsgTextEntrySize

Specifies the size in bytes of each of the call completion text descriptions pointed at by dwCompletionMsgTextSize/Offset.

dwCompletionMsgTextSize

dwCompletionMsgTextOffset

The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing descriptive text about each of the call completion messages. Each message is dwCompletionMsgTextEntrySize bytes long. The string format of these textual descriptions is indicated by dwStringFormat in the line's device capabilities.

dwAddressFeatures

This field specifies the features available for this address using the LINEADDRFEATURE_ constants. Invoking a supported feature requires the address to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the address is in the appropriate state for the operation to be meaningful. This field allows an application to discover which address features can be (and which can never be) supported by the address.

dwPredictiveAutoTransferStates

The call state or states upon which a call made by a predictive dialer can be set to automatically transfer the call to another address; one or more of the LINECALLSTATE_ constants. The value 0 indicates automatic transfer based on call state is unavailable.

dwNumCallTreatments

The number of entries in the array of LINECALLTREATMENTENTRY structures delimited by dwCallTreatmentSize and dwCallTreatmentOffset.

dwCallTreatmentListSize

dwCallTreatmentListOffset

The total size in bytes and offset from the beginning of LINEADDRESSCAPS of an array of LINECALLTREATMENTENTRY structures, indicating the call treatments supported on the address (which can be selected using lineSetCallTreatment). The value will be dwNumCallTreatments times SIZEOF (LINECALLTREATMENTENTRY).

dwDeviceClassesSize

dwDeviceClassesOffset

Length in bytes and offset from the beginning of LINEADDRESSCAPS of a string consisting of the device class identifiers supported on this address for use with lineGetID, separated by nulls; the last class indentifier is followed by two nulls.

dwMaxCallDataSize

The maximum number of bytes that an application can set in LINECALLINFO using lineSetCallData.

dwCallFeatures2

Specifies additional switching capabilities or features available for all calls on this address using the LINECALLFEATURE2_ constants. It is an extension of the dwCallFeatures member.

dwMaxNoAnswerTimeout

The maximum value in seconds that can be set in the dwNoAnswerTimeout member in LINECALLPARAMS when making a call. A value of 0 indicates that automatic abandonment of unanswered calls is not supported by the service provider, or that the timeout value is not adjustable by applications.

dwConnectedModes

Specifies the LINECONNECTEDMODE_ values that may appear in the dwCallStateMode member of LINECALLSTATUS and in LINE_CALLSTATE messages for calls on this address.

dwOfferingModes

Specifies the LINEOFFERINGMODE_ values that may appear in the dwCallStateMode member of LINECALLSTATUS and in LINE_CALLSTATE messages for calls on this address.

dwAvailableMediaModes

Indicates the media modes that can be invoked on new calls created on this address, when the dwAddressFeatures member indicates that new calls are possible. If this field is zero, it indicates that the service provider either does not know or cannot indicate which media modes are available, in which case any or all of the media modes indicated in the dwMediaModes field in LINEDEVCAPS may be available.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

Older applications will have been compiled without this field in the LINEADDRESSCAPS structure, and using a SIZEOF LINEADDRESSCAPS smaller than the new size. The application passes in a dwAPIVersion parameter with the lineGetAddressCaps function, which can be used for guidance by TAPI in handling this situation. If the application passes in a dwTotalSize less than the size of the fixed portion of the structure as defined in the dwAPIVersion specified, LINEERR_STRUCTURETOOSMALL will be returned. If sufficient memory has been allocated by the application, before calling TSPI_lineGetAddressCaps, TAPI will set the dwNeededSize and dwUsedSize fields to the fixed size of the structure as it existed in the specified API version.

New service providers (which support the new API version) must examine the API version passed in. If the API version is less than the highest version supported by the provider, the service provider must not fill in fields not supported in older API versions, as these would fall in the variable portion of the older structure.

New applications must be cognizant of the API version negotiated, and not examine the contents of fields in the fixed portion beyond the original end of the fixed portion of the structure for the negotiated API version.

The members dwPredictiveAutoTransferStates through dwAvailableMediaModes are available only to applications that request an API version of 0x00020000 or greater when calling lineGetAddressCaps.

See Also

LINE_ADDRESSSTATE, LINE_CALLINFO, LINE_CALLSTATE, LINE_LINEDEVSTATE, LINEADDRESSSTATUS, LINECALLINFO, LINECALLPARAMS, LINECALLSTATUS, LINECALLTREATMENTENTRY, LINEDEVCAPS, LINEDIALPARAMS, lineCompleteCall, lineForward, lineGenerateDigits, lineGetAddressCaps, lineGetID, lineSetCallData, lineSetCallTreatment


LINEADDRESSSTATUS

The LINEADDRESSSTATUS structure describes the current status of an address.

typedef struct lineaddressstatus_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwNumInUse;

    DWORD  dwNumActiveCalls;

    DWORD  dwNumOnHoldCalls;

    DWORD  dwNumOnHoldPendCalls;

    DWORD  dwAddressFeatures;

    DWORD  dwNumRingsNoAnswer;

    DWORD  dwForwardNumEntries;

    DWORD  dwForwardSize;

    DWORD  dwForwardOffset;

    DWORD  dwTerminalModesSize;

    DWORD  dwTerminalModesOffset;

    DWORD  dwDevSpecificSize;

    DWORD  dwDevSpecificOffset;

} LINEADDRESSSTATUS, FAR *LPLINEADDRESSSTATUS;

Members

dwTotalSize

The total size in bytes allocated to this data structure.

dwNeededSize

The size in bytes for this data structure that is needed to hold all the returned information.

dwUsedSize

The size in bytes of the portion of this data structure that contains useful information.

dwNumInUse

Specifies the number of stations that are currently using the address.

dwNumActiveCalls

The number of calls on the address that are in call states other than idle, onhold, onholdpendingtransfer, and onholdpendingconference.

dwNumOnHoldCalls

The number of calls on the address in the onhold state.

dwNumOnHoldPendCalls

The number of calls on the address in the onholdpendingtransfer or onholdpendingconference state.

dwAddressFeatures

This field specifies the address-related API functions that can be invoked on the address in its current state. It uses the following LINEADDRFEATURE_ constants:

LINEADDRFEATURE_FORWARD

The address can be forwarded.

LINEADDRFEATURE_MAKECALL

An outbound call can be placed on the address.

LINEADDRFEATURE_PICKUP

A call can be picked up at the address.

LINEADDRFEATURE_SETMEDIACONTROL

Media control can be set on this address.

LINEADDRFEATURE_SETTERMINAL

The terminal modes for this address can be set.

LINEADDRFEATURE_SETUPCONF

A conference call with a NULL initial call can be set up at this address.

LINEADDRFEATURE_UNCOMPLETECALL

Call completion requests can be canceled at this address.

LINEADDRFEATURE_UNPARK

Calls can be unparked using this address.

dwNumRingsNoAnswer

The number of rings set for this address before an unanswered call is considered as no answer.

dwForwardNumEntries

The number of entries in the array referred to by dwForwardSize and dwForwardOffset.

dwForwardSize

dwForwardOffset

The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field that describes the address's forwarding information. This information is an array of dwForwardNumEntries elements, of type LINEFORWARD. The offsets of the addresses in the array are relative to the beginning of the LINEADDRESSSTATUS structure. The offsets dwCallerAddressOffset and dwDestAddressOffset in the variably sized field of type LINEFORWARD pointed to by dwForwardSize and dwForwardOffset are relative to the beginning of the LINEADDRESSSTATUS data structure (the "root" container).

dwTerminalModesSize

dwTerminalModesOffset

The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing an array with DWORD-sized entries, that use the LINETERMMODE_ constants. This array is indexed by terminal IDs, in the range from zero to one less than dwNumTerminals. Each entry in the array specifies the current terminal modes for the corresponding terminal set with the lineSetTerminal function for this address. Values are:

LINETERMMODE_LAMPS

These are lamp events sent from the line to the terminal.

LINETERMMODE_BUTTONS

These are button-press events sent from the terminal to the line.

LINETERMMODE_DISPLAY

This is display information sent from the line to the terminal.

LINETERMMODE_RINGER

This is ringer-control information sent from the switch to the terminal.

LINETERMMODE_HOOKSWITCH

These are hookswitch events sent between the terminal and the line.

LINETERMMODE_MEDIATOLINE

This is the unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIAFROMLINE

This is the unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIABIDIRECT

This is the bidirectional media stream associated with a call on the line and the terminal. Use this value when the routing of both unidirectional channels of a call's media stream cannot be controlled independently.

dwDevSpecificSize

dwDevSpecificOffset

The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device-specific field.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

This data structure is returned by lineGetAddressStatus. When items in this data structure change as a consequence of activities on the address, a LINE_ADDRESSSTATE message is sent to the application. A parameter to this message is the address state, the constant LINEADDRESSSTATE_, which is an indication that the status item in this record changed.

See Also

LINE_ADDRESSSTATE, LINEFORWARD, lineGetAddressStatus, lineSetTerminal


LINEAGENTACTIVITYENTRY

typedef struct lineagentactivityentry_tag {

    DWORD  dwID;

    DWORD  dwNameSize;

    DWORD  dwNameOffset;

} LINEAGENTACTIVITYENTRY, FAR *LPLINEAGENTACTIVITYENTRY;

Members

dwID

A unique identifier for a activity. It is the responsibility of the agent handler to generate and maintain uniqueness of these IDs.

dwNameSize

dwNameOffset

Size in bytes and offset from the beginning of the containing structure of a null-terminated string specifying the name and other identifying information of an activity which can be selected using lineSetAgentActivity.


LINEAGENTACTIVITYLIST

typedef struct lineagentactivitylist_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwNumEntries;

    DWORD  dwListSize;

    DWORD  dwListOffset;

} LINEAGENTACTIVITYLIST, FAR *LPLINEAGENTACTIVITYLIST;

Members

dwNumEntries

The number of LINEAGENTACTIVITYENTRY structures that appear in the List array. The value is 0 if no agent activity codes are available.

dwListSize

dwListOffset

Total size in bytes and offset from the beginning of LINEAGENTACTIVITYLIST of an array of LINEAGENTACTIVITYENTRY elements indicating information about activity which could be specified for the current logged-in agent. This will be dwNumEntries times SIZEOF (LINEAGENTACTIVITYENTRY).


LINEAGENTCAPS

typedef struct lineagentcaps_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwAgentHandlerInfoSize;

    DWORD  dwAgentHandlerInfoOffset;

    DWORD  dwCapsVersion;

    DWORD  dwFeatures;

    DWORD  dwStates;

    DWORD  dwNextStates;

    DWORD  dwMaxNumGroupEntries;

    DWORD  dwAgentStatusMessages;

    DWORD  dwNumAgentExtensionIDs;

    DWORD  dwAgentExtensionIDListSize;

    DWORD  dwAgentExtensionIDListOffset;

} LINEAGENTCAPS, FAR *LPLINEAGENTCAPS;

Members

dwAgentHandlerInfoSize

dwAgentHandlerInfoOffset

The size in bytes and offset from the beginning of LINEAGENTCAPS of a null-terminated string specifying the name, version, or other identifying information of the server application that is handling agent requests.

dwCapsVersion

The TAPI version that the agent handler application used in preparing the contents of this structure. This will be no greater than the API version that the calling application passed in to lineGetAgentCaps.

dwFeatures

The agent-related features available for this line using the LINEAGENTFEATURE_ constants. Invoking a supported feature requires the line and address to be in the proper state. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the line is in the appropriate state for the operation to be meaningful. This field allows an application to discover which agent features can be (and which can never be) supported by the device.

dwStates

The LINEAGENTSTATE_ values which may be used in the dwAgentState parameter of lineSetAgentState. Setting a supported state requires the line and address to be in the proper state. A zero in a bit position indicates that the corresponding state is never available. A one indicates that the corresponding state may be available if the line is in the appropriate state for the state to be meaningful. This field allows an application to discover which agent states can be (and which can never be) supported on the device.

dwNextStates

The LINEAGENTSTATE_ values which may be used in the dwNextAgentState parameter of lineSetAgentState. Setting a supported state requires the line and address to be in the proper state. A zero in a bit position indicates that the corresponding state is never available. A one indicates that the corresponding state may be available if the line is in the appropriate state for the state to be meaningful. This field allows an application to discover which agent states can be (and which can never be) supported on the device.

dwMaxNumGroupEntries

The maximum number of agent IDs that can be logged in on the address simultaneously. Determines the highest value that can be passed in as the dwNumEntries field in the LINEAGENTGROUPLIST structure to lineSetAgentGroup.

dwAgentStatusMessages

Indicates the LINEAGENTSTATUS_ constants that can be received by the application in dwParam2 of a LINE_AGENTSTATUS message.

dwNumExtensionIDs

The number of LINEEXTENSIONID structures that appear in the ExtensionIDList array. The value is 0 if agent-handler-specific extensions are supported on the address.

dwExtensionIDListSize

dwExtensionIDListOffset

Total size in bytes and offset from the beginning of LINEAGENTCAPS of an array of LINEEXTENSIONID elements. The size will be dwNumExtensionIDs times SIZEOF (LINEEXTENSIONID). The array lists the 128-bit universally unique identifiers for all agent-handler-specific extensions supported by the agent handle for the address. The extension being used is referenced in the lineAgentSpecific function and LINE_AGENTSPECIFIC message by its position in this table, the first entry being entry 0, so it is important that the agent handler always present extension IDs in this array in the same order.

See Also

LINE_AGENTSPECIFIC, LINE_AGENTSTATUS, LINEAGENTGROUPLIST, lineAgentSpecific, LINEEXTENSIONID, lineGetAgentCaps, lineSetAgentGroup, lineSetAgentState


LINEAGENTGROUPENTRY

typedef struct lineagentgroupentry_tag {

  struct {

    DWORD  dwGroupID1;

    DWORD  dwGroupID2;

    DWORD  dwGroupID3;

    DWORD  dwGroupID4;

  } GroupID;

  DWORD  dwNameSize;

  DWORD  dwNameOffset;

} LINEAGENTGROUPENTRY, FAR *LPLINEAGENTGROUPENTRY;

Members

GroupID

This set of four DWORDs is a universally unique identifier for a group. It is the responsibility of the agent handler to generate and maintain uniqueness of these IDs.

dwNameSize

dwNameOffset

Size in bytes and offset from the beginning of the containing structure of a null-terminated string specifying the name and other identifying information of an ACD group or queue into which the agent can log in. This string can contain such information as supervisor and skill level, to assist the agent in selecting the correct group from a list displayed on their workstation screen.


LINEAGENTGROUPLIST

typedef struct lineagentgrouplist_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwNumEntries;

    DWORD  dwListSize;

    DWORD  dwListOffset;

} LINEAGENTGROUPLIST, FAR *LPLINEAGENTGROUPLIST;

Members

dwNumEntries

The number of LINEAGENTGROUPENTRY structures that appear in the List array. The value is 0 if no agent is to be logged in on the address.

dwListSize

dwListOffset

Total size in bytes and offset from the beginning of LINEAGENTGROUPLIST of an array of LINEAGENTGROUPENTRY elements specifying information about each group into which the current agent is to be logged in at the address. This will be dwNumEntries times SIZEOF (LINEAGENTGROUPENTRY).


LINEAGENTSTATUS

typedef struct lineagentstatus_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwNumEntries;

    DWORD  dwGroupListSize;

    DWORD  dwGroupListOffset;

    DWORD  dwState;

    DWORD  dwNextState;

    DWORD  dwActivityID;

    DWORD  dwActivitySize;

    DWORD  dwActivityOffset;

    DWORD  dwAgentFeatures;

    DWORD  dwValidStates;

    DWORD  dwValidNextStates;

} LINEAGENTSTATUS, FAR *LPLINEAGENTSTATUS;

Members

dwNumEntries

The number of LINEAGENTGROUPENTRY structures that appear in the GroupList array. The value is 0 if no agent is logged in on the address.

dwGroupListSize

dwGroupListOffset

Total size in bytes and offset from the beginning of LINEAGENTSTATUS of an array of LINEAGENTGROUPENTRY elements. The size will be dwNumEntries times SIZEOF (LINEAGENTGROUPENTRY). The array contains groups into which the agent is currently logged in on the address.

dwState

The current state of the agent. One of the LINEAGENTSTATE_ constants.

dwNextState

The state into which the agent will automatically be placed when the current call completes. One of the LINEAGENTSTATE_ constants.

dwActivityID

The ID of the current agent activity.

dwActivitySize

dwActivityOffset

Size in bytes and offset from the beginning of LINEAGENTSTATUS of a null-terminated string specifying the current agent activity.

dwAgentFeatures

The agent-related features available at the time the status was obtained, using the LINEAGENTFEATURE_ constants.

dwValidStates

The agent states which could be selected, at this point in time, using lineSetAgentState. Consists of one or more of the LINEAGENTSTATE_ constants.

dwValidNextStates

The next agent states which could be selected, at this point in time, using lineSetAgentState. Consists of one or more of the LINEAGENTSTATE_ constants.

See Also

LINEAGENTGROUPENTRY, lineSetAgentState


LINEAPPINFO

typedef struct lineappinfo_tag {

} LINEAPPINFO, FAR *LPLINEAPPINFO;

    DWORD  dwMachineNameSize;

    DWORD  dwMachineNameOffset;

    DWORD  dwUserNameSize;

    DWORD  dwUserNameOffset;

    DWORD  dwModuleFilenameSize;

    DWORD  dwModuleFilenameOffset;

    DWORD  dwFriendlyNameSize;

    DWORD  dwFriendlyNameOffset;

    DWORD  dwMediaModes;

    DWORD  dwAddressID;

Members

dwMachineNameSize

dwMachineNameOffset

Size in bytes and offset from the beginning of LINEDEVSTATUS of a string specifying the name of the computer on which the application is executing.

dwUserNameSize

dwUserNameOffset

Size in bytes and offset from the beginning of LINEDEVSTATUS of a string specifying the username under whose account the application is running.

dwModuleFilenameSize

dwModuleFilenameOffset

Size in bytes and offset from the beginning of LINEDEVSTATUS of a string specifying the module filename of the application. This string may be used in a call to lineHandoff to perform a directed handoff to the application.

dwFriendlyNameSize

dwFriendlyNameOffset

Size in bytes and offset from the beginning of LINEDEVSTATUS of the string provided by the application to lineInitialize or lineInitializeEx, which should be used in any display of applications to the user.

dwMediaModes

The media modes for which the application has requested ownership of new calls; 0 if when it opened the line dwPrivileges did not include LINECALLPRIVILEGE_OWNER.

dwAddressID

If the line handle was opened using LINEOPENOPTION_SINGLEADDRESS, contains the address ID specified; set to 0xFFFFFFFF if the single address option was not used.


LINECALLINFO

The LINECALLINFO structure contains information about a call. This information remains relatively fixed for the duration of the call and is obtained with lineGetCallInfo. If a part of the structure does change, then a LINE_CALLINFO message is sent to the application indicating which information item has changed. Dynamically changing information about a call, such as call progress status, is available in the LINECALLSTATUS structure, returned with the function lineGetCallStatus.

typedef struct linecallinfo_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

  HLINE  hLine;

    DWORD  dwLineDeviceID;

    DWORD  dwAddressID;

    DWORD  dwBearerMode;

    DWORD  dwRate;

    DWORD  dwMediaMode;

    DWORD  dwAppSpecific;

    DWORD  dwCallID;

    DWORD  dwRelatedCallID;

    DWORD  dwCallParamFlags;

    DWORD  dwCallStates;

    DWORD  dwMonitorDigitModes;

    DWORD  dwMonitorMediaModes;

  LINEDIALPARAMS  DialParams;

    DWORD  dwOrigin;

    DWORD  dwReason;

    DWORD  dwCompletionID;

    DWORD  dwNumOwners;

    DWORD  dwNumMonitors;

    DWORD  dwCountryCode;

    DWORD  dwTrunk;

    DWORD  dwCallerIDFlags;

    DWORD  dwCallerIDSize;

    DWORD  dwCallerIDOffset;

    DWORD  dwCallerIDNameSize;

    DWORD  dwCallerIDNameOffset;

    DWORD  dwCalledIDFlags;

    DWORD  dwCalledIDSize;

    DWORD  dwCalledIDOffset;

    DWORD  dwCalledIDNameSize;

    DWORD  dwCalledIDNameOffset;

    DWORD  dwConnectedIDFlags;

    DWORD  dwConnectedIDSize;

    DWORD  dwConnectedIDOffset;

    DWORD  dwConnectedIDNameSize;

    DWORD  dwConnectedIDNameOffset;

    DWORD  dwRedirectionIDFlags;

    DWORD  dwRedirectionIDSize;

    DWORD  dwRedirectionIDOffset;

    DWORD  dwRedirectionIDNameSize;

    DWORD  dwRedirectionIDNameOffset;

    DWORD  dwRedirectingIDFlags;

    DWORD  dwRedirectingIDSize;

    DWORD  dwRedirectingIDOffset;

    DWORD  dwRedirectingIDNameSize;

    DWORD  dwRedirectingIDNameOffset;

    DWORD  dwAppNameSize;

    DWORD  dwAppNameOffset;

    DWORD  dwDisplayableAddressSize;

    DWORD  dwDisplayableAddressOffset;

    DWORD  dwCalledPartySize;

    DWORD  dwCalledPartyOffset;

    DWORD  dwCommentSize;

    DWORD  dwCommentOffset;

    DWORD  dwDisplaySize;

    DWORD  dwDisplayOffset;

    DWORD  dwUserUserInfoSize;

    DWORD  dwUserUserInfoOffset;

    DWORD  dwHighLevelCompSize;

    DWORD  dwHighLevelCompOffset;

    DWORD  dwLowLevelCompSize;

    DWORD  dwLowLevelCompOffset;

    DWORD  dwChargingInfoSize;

    DWORD  dwChargingInfoOffset;

    DWORD  dwTerminalModesSize;

    DWORD  dwTerminalModesOffset;

    DWORD  dwDevSpecificSize;

    DWORD  dwDevSpecificOffset;

    DWORD  dwCallTreatment;

    DWORD  dwCallDataSize;

    DWORD  dwCallDataOffset;

    DWORD  dwSendingFlowspecSize;

    DWORD  dwSendingFlowspecOffset;

    DWORD  dwReceivingFlowspecSize;

    DWORD  dwReceivingFlowspecOffset;

} LINECALLINFO, FAR *LPLINECALLINFO;

Members

dwTotalSize

The total size in bytes allocated to this data structure.

dwNeededSize

The size in bytes for this data structure that is needed to hold all the returned information.

dwUsedSize

The size in bytes of the portion of this data structure that contains useful information.

hLine

The handle for the line device with which this call is associated.

dwLineDeviceID

The device ID of the line device with which this call is associated.

dwAddressID

The address ID of the address on the line on which this call exists.

dwBearerMode

The current bearer mode of the call. This field uses the following LINEBEARERMODE_ constants:

LINEBEARERMODE_VOICE

This is a regular 3.1 kHz analog voice grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.

LINEBEARERMODE_SPEECH

This corresponds to G.711 speech transmission on the call. The network may use processing techniques such as analog transmission, echo cancellation, and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.

LINEBEARERMODE_MULTIUSE

The multiuse mode defined by ISDN.

LINEBEARERMODE_DATA

The unrestricted data transfer on the call. The data rate is specified separately.

LINEBEARERMODE_ALTSPEECHDATA

The alternate transfer of speech or unrestricted data on the same call (ISDN).

LINEBEARERMODE_NONCALLSIGNALING

A non-call-associated signaling connection from the application to the service provider or switch (treated as a "media stream" by TAPI).

LINEBEARERMODE_PASSTHROUGH

When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.

dwRate

The rate of the call's data stream in bps (bits per second).

dwMediaMode

Specifies the media mode of the information stream currently on the call. This is the media mode as determined by the owner of the call, which is not necessarily the same as that of the last LINE_MONITORMEDIA message. This field is not directly affected by the LINE_MONITORMEDIA messages. It uses the following LINEMEDIAMODE_ constants:

LINEMEDIAMODE_UNKNOWN

A media stream exists but its mode is not known. This corresponds to a call with an unclassified media type. In typical analog telephony environments, an inbound call's media mode may be unknown until after the call has been answered and the media stream has been filtered to make a determination.

LINEMEDIAMODE_INTERACTIVEVOICE

The presence of voice energy is detected on the call and the call is treated as an interactive call with humans on both ends.

LINEMEDIAMODE_AUTOMATEDVOICE

The presence of voice energy is detected on the call and the voice is locally handled by an automated application.

LINEMEDIAMODE_DATAMODEM

A data modem session is detected on the call.

LINEMEDIAMODE_G3FAX

A group 3 fax is being sent or received on the call.

LINEMEDIAMODE_G4FAX

A group 4 fax is being sent or received over the call.

LINEMEDIAMODE_TDD

A TDD (Telephony Devices for the Deaf) session on the call.

LINEMEDIAMODE_DIGITALDATA

Digital data being sent or received over the call.

LINEMEDIAMODE_TELETEX

A teletex session on the call. Teletex is one of the telematic services.

LINEMEDIAMODE_VIDEOTEX

A videotex session on the call. Videotex is one the telematic services.

LINEMEDIAMODE_TELEX

A telex session on the call. Telex is one the telematic services.

LINEMEDIAMODE_MIXED

A mixed session on the call. Mixed is one the ISDN telematic services.

LINEMEDIAMODE_ADSI

An ADSI (Analog Display Services Interface) session on the call.

LINEMEDIAMODE_VOICEVIEW

The media mode of the call is VoiceView.

dwAppSpecific

This field is uninterpreted by the API implementation and service provider. It can be set by any owner application of this call with the operation lineSetAppSpecific.

dwCallID

In some telephony environments, the switch or service provider may assign a unique identifier to each call. This allows the call to be tracked across transfers, forwards, or other events. The domain of these call IDs and their scope is service-provider defined. The dwCallID field makes this unique identifier available to the applications.

dwRelatedCallID

Telephony environments that use the call ID often may find it necessary to relate one call to another. The dwRelatedCallID field may be used by the service provider for this purpose.

dwCallParamFlags

A collection of call-related parameters when the call is outbound. These are same call parameters specified in lineMakeCall, of type LINECALLPARAMFLAGS_. Values are:

LINECALLPARAMFLAGS_SECURE

The call is currently secure. This flag is also updated if the call is later secured through lineSecureCall.

LINECALLPARAMFLAGS_IDLE

The call started out using an idle call.

LINECALLPARAMFLAGS_BLOCKID

The originator identity was concealed (block caller ID presentation to the remote party).

LINECALLPARAMFLAGS_ORIGOFFHOOK

The originator's phone was automatically taken offhook.

LINECALLPARAMFLAGS_DESTOFFHOOK

The called party's phone was automatically taken offhook.

dwCallStates

The call states for which the application may be notified on this call, of type LINECALLSTATE_. The dwCallStates member is constant in LINECALLINFO and does not change depending on the call state. Values are:

LINECALLSTATE_IDLE

The call is idle—no call exists.

LINECALLSTATE_OFFERING

The call is being offered to the station signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user; alerting is done by the switch instructing the line to ring. It does not affect any call states.

LINECALLSTATE_ACCEPTED

The call was offering and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also initiates alerting to both parties.

LINECALLSTATE_DIALTONE

The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.

LINECALLSTATE_DIALING

Destination address information (a phone number) is being sent to the switch over the call. Note that the operation lineGenerateDigits does not place the line into the dialing state.

LINECALLSTATE_RINGBACK

The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.

LINECALLSTATE_BUSY

The call is receiving a busy tone. Busy tone indicates that the call cannot be completed—either a circuit (trunk) or the remote party's station are in use.

LINECALLSTATE_SPECIALINFO

Special information is sent by the network. Special information is typically sent when the destination cannot be reached.

LINECALLSTATE_CONNECTED

The call has been established, the connection is made. Information is able to flow over the call between the originating address and the destination address.

LINECALLSTATE_PROCEEDING

Dialing has completed and the call is proceeding through the switch or telephone network.

LINECALLSTATE_ONHOLD

The call is on hold by the switch.

LINECALLSTATE_CONFERENCED

The call is currently a member of a multiparty conference call.

LINECALLSTATE_ONHOLDPENDCONF

The call is currently on hold while it is being added to a conference.

LINECALLSTATE_ONHOLDPENDTRANSF

The call is currently on hold awaiting transfer to another number.

LINECALLSTATE_DISCONNECTED

The remote party has disconnected from the call.

LINECALLSTATE_UNKNOWN

The state of the call is not known. This may be due to limitations of the call progress detection implementation.

dwMonitorDigitsModes

The various digit modes for which monitoring is currently enabled, of type LINEDIGITMODE_. Values are:

LINEDIGITMODE_PULSE

Uses pulse/rotary for digit signaling.

LINEDIGITMODE_DTMF

Uses DTMF tones for digit signaling.

LINEDIGITMODE_DTMFEND

Uses DTMF tones for digit detection, and also detects the down edges.

dwMonitorMediaModes

The various media modes for which monitoring is currently enabled, of type LINEMEDIAMODE_. Values are:

LINEMEDIAMODE_INTERACTIVEVOICE

The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends.

LINEMEDIAMODE_AUTOMATEDVOICE

The presence of voice energy on the call and the voice is locally handled by an automated application.

LINEMEDIAMODE_DATAMODEM

A data modem session on the call.

LINEMEDIAMODE_G3FAX

A group 3 fax is being sent or received over the call.

LINEMEDIAMODE_G4FAX

A group 4 fax is being sent or received over the call.

LINEMEDIAMODE_TDD

A TDD (Telephony Devices for the Deaf) session on the call.

LINEMEDIAMODE_DIGITALDATA

Digital data is being sent or received over the call.

LINEMEDIAMODE_TELETEX

A teletex session on the call. Teletex is one of the telematic services.

LINEMEDIAMODE_VIDEOTEX

A videotex session on the call. Videotex is one the telematic services.

LINEMEDIAMODE_TELEX

A telex session on the call. Telex is one the telematic services.

LINEMEDIAMODE_MIXED

A mixed session on the call. Mixed is one the ISDN telematic services.

LINEMEDIAMODE_ADSI

An ADSI (Analog Display Services Interface) session on the call.

LINEMEDIAMODE_VOICEVIEW

The media mode of the call is VoiceView.

DialParams

The dialing parameters currently in effect on the call, of type LINEDIALPARAMS. Unless these parameters are set by either lineMakeCall or lineSetCallParams, their values will be the same as the defaults used in the LINEDEVCAPS.

dwOrigin

Identifies where the call originated from. This field uses the following LINECALLORIGIN_ constants:

LINECALLORIGIN_OUTBOUND

The call is an outbound call.

LINECALLORIGIN_INTERNAL

The call is inbound and originated internally (on the same PBX, for example).

LINECALLORIGIN_EXTERNAL

The call is inbound and originated externally.

LINECALLORIGIN_UNKNOWN

The call is an inbound call and its origin is currently unknown but may become known later.

LINECALLORIGIN_UNAVAIL

The call is an inbound call. Its origin is not available and will never become known for this call.

LINECALLORIGIN_CONFERENCE

The call handle is for a conference call, that is, the application's connection to the conference bridge in the switch.

dwReason

The reason why the call occurred. This field uses the following LINECALLREASON_ constants:

LINECALLREASON_DIRECT

This is a direct call.

LINECALLREASON_FWDBUSY

This call was forwarded from another extension that was busy at the time of the call.

LINECALLREASON_FWDNOANSWER

The call was forwarded from another extension that didn't answer the call after some number of rings.

LINECALLREASON_FWDUNCOND

The call was forwarded unconditionally from another number.

LINECALLREASON_PICKUP

The call was picked up from another extension.

LINECALLREASON_UNPARK

The call was retrieved as a parked call.

LINECALLREASON_REDIRECT

The call was redirected to this station.

LINECALLREASON_CALLCOMPLETION

The call was the result of a call completion request.

LINECALLREASON_TRANSFER

The call has been transferred from another number. Party ID information may indicate who the caller is and where the call was transferred from.

LINECALLREASON_REMINDER

The call is a reminder (or "recall") that the user has a call parked or on hold for potentially a long time.

LINECALLREASON_UNKNOWN

The reason for the call is currently unknown but may become known later.

LINECALLREASON_UNAVAIL

The reason for the call is unavailable and will not become known later.

dwCompletionID

The completion ID for the incoming call if it is the result of a completion request that terminates. This ID is meaningful only if dwReason is LINECALLREASON_CALLCOMPLETION.

dwNumOwners

The number of application modules with different call handles with owner privilege for the call.

dwNumMonitors

The number of application modules with different call handles with monitor privilege for the call.

dwCountryCode

The country code of the destination party. Zero if unknown.

dwTrunk

The number of the trunk over which the call is routed. This field is used for both inbound and outgoing calls. The dwTrunk field should be set to 0xFFFFFFFF if it is unknown.

dwCallerIDFlags

Determines the validity and content of the caller party ID information. The caller is the originator of the call. This field uses the following LINECALLPARTYID_ constants:

LINECALLPARTYID_BLOCKED

Caller ID information for the call has been blocked by the caller but would otherwise have been available.

LINECALLPARTYID_OUTOFAREA

Caller ID information for the call is not available because it is not propagated all the way by the network.

LINECALLPARTYID_NAME

The caller ID information for the call is the caller's name (from a table maintained inside the switch). It is provided in the caller ID name variably sized field.

LINECALLPARTYID_ADDRESS

The caller ID information for the call is the caller's number and is provided in the caller ID variably sized field.

LINECALLPARTYID_PARTIAL

Caller ID information for the call is valid but is limited to partial number information.

LINECALLPARTYID_UNKNOWN

Caller ID information is currently unknown but it may become known later.

LINECALLPARTYID_UNAVAIL

Caller ID information is unavailable and will not become known later.

dwCallerIDSize

dwCallerIDOffset

The size in bytes of the variably sized field containing the caller party ID number information, and the offset in bytes from the beginning of this data structure.

dwCallerIDNameSize

dwCallerIDNameOffset

The size in bytes of the variably sized field containing the caller party ID name information, and the offset in bytes from the beginning of this data structure.

dwCalledIDFlags

Determines the validity and content of the called-party ID information. The called party corresponds to the originally addressed party. This field uses the following LINECALLPARTYID_ constants:

LINECALLPARTYID_BLOCKED

Called ID information for the call has been blocked by the caller but would otherwise have been available.

LINECALLPARTYID_OUTOFAREA

Caller ID information for the call is not available because it is not propagated all the way by the network.

LINECALLPARTYID_NAME

The called ID information for the call is the caller's name (from a table maintained inside the switch). It is provided in the called ID name variably sized field.

LINECALLPARTYID_ADDRESS

The called ID information for the call is the caller's number and is provided in the called ID variably sized field.

LINECALLPARTYID_PARTIAL

Called ID information for the call is valid but is limited to partial number information.

LINECALLPARTYID_UNKNOWN

Called ID information is currently unknown but it may become known later.

LINECALLPARTYID_UNAVAIL

Called ID information is unavailable and will not become known later.

dwCalledIDSize

dwCalledIDOffset

The size in bytes of the variably sized field containing the called-party ID number information, and the offset in bytes from the beginning of this data structure.

dwCalledIDNameSize

dwCalledIDNameOffset

The size in bytes of the variably sized field containing the called-party ID name information, and the offset in bytes from the beginning of this data structure.

dwConnectedFlags

Determines the validity and content of the connected party ID information. The connected party is the party that was actually connected to. This may be different from the called-party ID if the call was diverted. This field uses the following LINECALLPARTYID_ constants:

LINECALLPARTYID_BLOCKED

Connected party ID information for the call has been blocked by the caller but would otherwise have been available.

LINECALLPARTYID_OUTOFAREA

Connected ID information for the call is not available as it is not propagated all the way by the network.

LINECALLPARTYID_NAME

The connected party ID information for the call is the caller's name (from a table maintained inside the switch). It is provided in the connected ID name variably sized field.

LINECALLPARTYID_ADDRESS

The connected party ID information for the call is the caller's number and is provided in the connected ID variably sized field.

LINECALLPARTYID_PARTIAL

Connected party ID information for the call is valid but is limited to partial number information.

LINECALLPARTYID_UNKNOWN

Connected party ID information is currently unknown but it may become known later.

LINECALLPARTYID_UNAVAIL

Connected party ID information is unavailable and will not become known later.

dwConnectedIDSize

dwConnectedIDOffset

The size in bytes of the variably sized field containing the connected party ID number information, and the offset in bytes from the beginning of this data structure.

dwConnectedIDNameSize

dwConnectedIDNameOffset

The size in bytes of the variably sized field containing the connected party ID name information, and the offset in bytes from the beginning of this data structure.

dwRedirectionIDFlags

Determines the validity and content of the redirection party ID information. The redirection party identifies to the calling user the number towards which diversion was invoked. This field uses the following LINECALLPARTYID_ constants:

LINECALLPARTYID_BLOCKED

Redirection party ID information for the call has been blocked by the caller but would otherwise have been available.

LINECALLPARTYID_OUTOFAREA

Redirection ID information for the call is not available because it is not propagated all the way by the network.

LINECALLPARTYID_NAME

The redirection party ID information for the call is the caller's name (from a table maintained inside the switch). It is provided in the redirection ID name variably sized field.

LINECALLPARTYID_ADDRESS

The redirection party ID information for the call is the caller's number and is provided in the redirection ID variably sized field.

LINECALLPARTYID_PARTIAL

Redirection party ID information for the call is valid but is limited to partial number information.

LINECALLPARTYID_UNKNOWN

Redirection ID information is currently unknown but it may become known later.

LINECALLPARTYID_UNAVAIL

Redirection ID information is unavailable and will not become known later.

dwRedirectionIDSize

dwRedirectionIDOffset

The size in bytes of the variably sized field containing the redirection party ID number information, and the offset in bytes from the beginning of this data structure.

dwRedirectionIDNameSize

dwRedirectionIDNameOffset

The size in bytes of the variably sized field containing the redirection party ID name information, and the offset in bytes from the beginning of this data structure.

dwRedirectingIDFlags

Determines the validity and content of the redirecting party ID information. The redirecting party identifies to the diverted-to user the party from which diversion was invoked. This field uses the following LINECALLPARTYID_ constants:

LINECALLPARTYID_BLOCKED

Redirecting party ID information for the call has been blocked by the caller but would otherwise have been available.

LINECALLPARTYID_OUTOFAREA

Redirecting ID information for the call is not available because it is not propagated all the way by the network.

LINECALLPARTYID_NAME

The redirecting party ID information for the call is the caller's name (from a table maintained inside the switch). It is provided in the redirecting ID name variably sized field.

LINECALLPARTYID_ADDRESS

The redirecting party ID information for the call is the caller's number and is provided in the redirecting ID variably sized field.

LINECALLPARTYID_PARTIAL

Redirecting party ID information for the call is valid but is limited to partial number information.

LINECALLPARTYID_UNKNOWN

Redirecting ID information is currently unknown but it may become known later.

LINECALLPARTYID_UNAVAIL

Redirecting ID information is unavailable and will not become known later.

dwRedirectingIDSize

dwRedirectingIDOffset

The size in bytes of the variably sized field containing the redirecting party ID number information, and the offset in bytes from the beginning of this data structure.

dwRedirectingIDNameSize

dwRedirectingIDNameOffset

The size in bytes of the variably sized field containing the redirecting party ID name information, and the offset in bytes from the beginning of this data structure.

dwAppNameSize

dwAppNameOffset

The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field holding the user-friendly application name of the application that first originated, accepted, or answered the call. This is the name that an application can specify in lineInitializeEx. If the application specifies no such name, then the application's module file name is used instead.

dwDisplayableAddressSize

dwDisplayableAddressOffset

The displayable string is used for logging purposes. The information is obtained from LINECALLPARAMS for functions that initiate calls. The function lineTranslateAddress returns appropriate information to be placed in this field in the dwDisplayableAddressSize and dwDisplayableAddressOffset fields of the LINETRANSLATEOUTPUT structure.

dwCalledPartySize

dwCalledPartyOffset

The size in bytes of the variably sized field holding a user-friendly description of the called party, and the offset in bytes from the beginning of this data structure. This information can be specified on lineMakeCall and can be optionally specified in the lpCallParams whenever a new call is established. It is useful for call logging purposes.

dwCommentSize

dwCommentOffset

The size in bytes of the variably sized field holding a comment about the call provided by the application that originated the call using lineMakeCall, and the offset in bytes from the beginning of this data structure. This information can be optionally specified in the lpCallParams whenever a new call is established.

dwDisplaySize

dwDisplayOffset

The size in bytes of the variably sized field holding raw display information, and the offset in bytes from the beginning of this data structure. Depending on the telephony environment, a service provider may extract functional information from this for presentation in a more functional way.

dwUserUserInfoSize

dwUserUserInfoOffset

The size in bytes of the variably sized field holding user-to-user information, and the offset in bytes from the beginning of this data structure The protocol discriminator field for the user-to-user information, if used, appears as the first byte of the data pointed to by dwUserUserInfoOffset, and is accounted for in dwUserUserInfoSize.

dwHighLevelCompSize

dwHighLevelCompOffset

The size in bytes of the variably sized field holding high-level compatibility information, and the offset in bytes from the beginning of this data structure. The format of this information is specified by other standards (ISDN Q.931).

dwLowLevelCompSize

dwLowLevelCompOffset

The size in bytes of the variably sized field holding low-level compatibility information, and the offset in bytes from the beginning of this data structure The format of this information is specified by other standards (ISDN Q.931).

dwChargingInfoSize

dwChargingInfoOffset

The size in bytes of the variably sized field holding charging information, and the offset in bytes from the beginning of this data structure The format of this information is specified by other standards (ISDN Q.931).

dwTerminalModesSize

dwTerminalModesOffset

The size in bytes of the variably sized device field containing an array with DWORD-sized entries, and the offset in bytes from the beginning of this data structure. The set of LINETERMMODE_ constants is indexed by terminal IDs, in the range from zero to one less than dwNumTerminals. Each entry in the array specifies the current terminal modes for the corresponding terminal set with the lineSetTerminal operation for this call's media stream. Values are:

LINETERMMODE_LAMPS

Lamp events sent from the line to the terminal.

LINETERMMODE_BUTTONS

Button-press events sent from the terminal to the line.

LINETERMMODE_DISPLAY

Display information sent from the line to the terminal.

LINETERMMODE_RINGER

Ringer-control information sent from the switch to the terminal.

LINETERMMODE_HOOKSWITCH

Hookswitch event sent between the terminal and the line.

LINETERMMODE_MEDIATOLINE

The unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIAFROMLINE

The unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIABIDIRECT

The bidirectional media stream associated with a call on the line and the terminal. Use this value when the routing of both the unidirectional channels of a call's media stream cannot be controlled independently.

dwDevSpecificSize

dwDevSpecificOffset

The size in bytes of the variably sized field holding device-specific information., and the offset in bytes from the beginning of this data structure.

dwCallTreatment

The call treatment currently being applied on the call or that will be applied when the call enters the next applicable state. May be 0 if call treatments are not supported.

dwCallDataSize

dwCallDataOffset

The size in bytes and offset from the beginning of LINECALLINFO of the application-settable call data.

dwSendingFlowspecSize

dwSendingFlowspecOffset

The total size in bytes and offset from the beginning of LINECALLINFO of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in SendingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service current in effect in the sending direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI will not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application.

dwReceivingFlowspecSize

dwReceivingFlowspecOffset

The total size in bytes and offset from the beginning of LINECALLINFO of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in ReceivingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service current in effect in the receiving direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI will not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The LINECALLINFO data structure contains relatively fixed information about a call. This structure is returned with lineGetCallInfo. When information items in this data structure have changed, a LINE_CALLINFO message is sent to the application. A parameter to this message is the information item or field that changed.

The dwAppSpecific field can be used by applications to tag calls by using lineSetAppSpecific. This field is uninterpreted by TAPI or service providers. It is initially set to zero.

The members dwCallTreatment through dwReceivingFlowspecOffset are available only to applications that open the line device with an API version of 0x00020000 or greater.

Note  The preferred format for specification of the contents of the callerID field and the other five similar fields is the TAPI canonical number format. For example, a ICLID of "2068828080" received from the switch should be converted to "+1 (206) 8828080" before being placed in the LINECALLINFO structure. This standardized format facilitates searching of databases and callback functions implemented in applications.

See Also

LINE_CALLINFO, LINE_MONITORMEDIA, LINECALLSTATUS, LINEDEVCAPS, LINEDIALPARAMS, lineGenerateDigits, lineGetCallInfo, lineGetCallStatus, lineInitializeEx, lineMakeCall, lineSecureCall, lineSetAppSpecific, lineSetCallParams, lineSetTerminal, lineTranslateAddress, LINETRANSLATEOUTPUT


LINECALLLIST

The LINECALLLIST structure describes a list of call handles. A structure of this type is returned by the functions lineGetNewCalls and lineGetConfRelatedCalls.

typedef struct linecalllist_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwCallsNumEntries;

    DWORD  dwCallsSize;

    DWORD  dwCallsOffset;

} LINECALLLIST, FAR *LPLINECALLLIST;

Members

dwTotalSize

The total size in bytes allocated to this data structure.

dwNeededSize

The size in bytes for this data structure that is needed to hold all the returned information.

dwUsedSize

The size in bytes of the portion of this data structure that contains useful information.

dwCallsNumEntries

The number of handles in the hCalls array.

dwCallsSize

dwCallsOffset

The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field (which is an array of HCALL-sized handles).

Remarks

No extensions.

See Also

lineGetConfRelatedCalls, lineGetNewCalls


LINECALLPARAMS

The LINECALLPARAMS structure describes parameters supplied when making calls using lineMakeCall. The LINECALLPARAMS structure is also used as a parameter in other operations. The comments on the right indicate the default values used when this structure is not provided to lineMakeCall.

typedef struct linecallparams_tag {  // Defaults:

    DWORD  dwTotalSize;          // ---------

    DWORD  dwBearerMode;              // voice

    DWORD  dwMinRate;                 // (3.1kHz)

    DWORD  dwMaxRate;                 // (3.1kHz)

    DWORD  dwMediaMode;               // interactiveVoice

    DWORD  dwCallParamFlags;          // 0

    DWORD  dwAddressMode;             // addressID

    DWORD  dwAddressID;               // (any available)

  LINEDIALPARAMS DialParams;        // (0, 0, 0, 0)

    DWORD  dwOrigAddressSize;         // 0

    DWORD  dwOrigAddressOffset;

    DWORD  dwDisplayableAddressSize;  // 0

    DWORD  dwDisplayableAddressOffset;

    DWORD  dwCalledPartySize;         // 0

    DWORD  dwCalledPartyOffset;

    DWORD  dwCommentSize;             // 0

    DWORD  dwCommentOffset;

    DWORD  dwUserUserInfoSize;        // 0

    DWORD  dwUserUserInfoOffset;

    DWORD  dwHighLevelCompSize;       // 0

    DWORD  dwHighLevelCompOffset;

    DWORD  dwLowLevelCompSize;        // 0

    DWORD  dwLowLevelCompOffset;

    DWORD  dwDevSpecificSize;         // 0

    DWORD  dwDevSpecificOffset;

    DWORD  dwPredictiveAutoTransferStates;

    DWORD  dwTargetAddressSize;

    DWORD  dwTargetAddressOffset;

    DWORD  dwSendingFlowspecSize;

    DWORD  dwSendingFlowspecOffset;

    DWORD  dwReceivingFlowspecSize;

    DWORD  dwReceivingFlowspecOffset;

    DWORD  dwDeviceClassSize;

    DWORD  dwDeviceClassOffset;

    DWORD  dwDeviceConfigSize;

    DWORD  dwDeviceConfigOffset;

    DWORD  dwCallDataSize;

    DWORD  dwCallDataOffset;

    DWORD  dwNoAnswerTimeout;

    DWORD  dwCallingPartyIDSize;

    DWORD  dwCallingPartyIDOffset;

} LINECALLPARAMS, FAR *LPLINECALLPARAMS;

Members

dwTotalSize

The total size in bytes allocated to this data structure. This size should be big enough to hold all the fixed and variably sized portions of this data structure.

dwBearerMode

The bearer mode for the call. This field uses the following LINEBEARERMODE_ constants:

LINEBEARERMODE_VOICE

This is a regular 3.1 kHz analog voice grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.

LINEBEARERMODE_SPEECH

This corresponds to G.711 speech transmission on the call. The network may use processing techniques such as analog transmission, echo cancellation, and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.

LINEBEARERMODE_MULTIUSE

The multiuse mode defined by ISDN.

LINEBEARERMODE_DATA

The unrestricted data transfer on the call. The data rate is specified separately.

LINEBEARERMODE_ALTSPEECHDATA

The alternate transfer of speech or unrestricted data on the same call (ISDN).

LINEBEARERMODE_NONCALLSIGNALING

This corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a "media stream" by the Telephony API).

LINEBEARERMODE_PASSTHROUGH

When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed via the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.

If dwBearerMode is 0, default value is LINEBEARERMODE_VOICE.

dwMinRate

dwMaxRate

The data rate range requested for the call's data stream in bps (bits per second). When making a call, the service provider attempts to provide the highest available rate in the requested range. If a specific data rate is required, both min and max should be set to that value. If an application works best with one rate but is able to degrade to lower rates, the application should specify these as the max and min rates respectively. If dwMaxRate is 0, the default value is as specified by the dwMaxRate member of the LINEDEVCAPS structure. This is the maximum rate supported by device.

dwMediaMode

The expected media mode of the call. This field uses the following LINEMEDIAMODE_ constants:

LINEMEDIAMODE_UNKNOWN

A media stream exists but its mode is not known. This would correspond to a call with an unclassified media type. In typical analog telephony environments, an inbound call's media mode may be unknown until after the call has been answered and the media stream has been filtered to make a determination.

LINEMEDIAMODE_INTERACTIVEVOICE

The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends.

LINEMEDIAMODE_AUTOMATEDVOICE

The presence of voice energy on the call and the voice is locally handled by an automated application.

LINEMEDIAMODE_DATAMODEM

A data modem session on the call.

LINEMEDIAMODE_G3FAX

A group 3 fax is being sent or received over the call.

LINEMEDIAMODE_G4FAX

A group 4 fax is being sent or received over the call.

LINEMEDIAMODE_TDD

A TDD (Telephony Devices for the Deaf) session on the call.

LINEMEDIAMODE_DIGITALDATA

Digital data is being sent or received over the call.

LINEMEDIAMODE_TELETEX

A teletex session on the call. Teletex is one of the telematic services.

LINEMEDIAMODE_VIDEOTEX

A videotex session on the call. Videotex is one the telematic services.

LINEMEDIAMODE_TELEX

A telex session on the call. Telex is one the telematic services.

LINEMEDIAMODE_MIXED

A mixed session on the call. Mixed is one the ISDN telematic services.

LINEMEDIAMODE_ADSI

An ADSI (Analog Display Services Interface) session on the call.

LINEMEDIAMODE_VOICEVIEW

The media mode of the call is VoiceView.

If dwMediaMode is 0, the default value is LINEMEDIAMODE_INTERACTIVEVOICE.

dwCallParamFlags

These flags specify a collection of Boolean call-setup parameters. This field uses the following LINECALLPARAMFLAGS_ constants:

LINECALLPARAMFLAGS_SECURE

The call should be set up as secure.

LINECALLPARAMFLAGS_IDLE

The call should get an idle call appearance.

LINECALLPARAMFLAGS_BLOCKID

The originator identity should be concealed (block caller ID).

LINECALLPARAMFLAGS_ORIGOFFHOOK

The originator's phone should be automatically taken offhook.

LINECALLPARAMFLAGS_DESTOFFHOOK

The called party's phone should be automatically taken offhook.

dwAddressMode

The mode by which the originating address is specified. The dwAddressMode field cannot be LINEADDRESSMODE_ADDRESSID for the function call lineOpen. This field uses the following LINEADDRESSMODE_ constants:

LINEADDRESSMODE_ADDRESSID

The address is specified with a small integer in the range 0 to dwNumAddresses minus one, where dwNumAddresses is the value in the line's LINEDEVCAPS structure. The selected address is specified in the dwAddressID field.

LINEADDRESSMODE_DIALABLEADDR

The address is specified with its dialable address. The address is contained in the dwOrigAddressSize  dwOrigAddressOffset variably sized field. If dwAddressMode is 0, the default value is LINEADDRESSMODE_ADDRESSID.

dwAddressID

The address ID of the originating address if dwAddressMode is set to LINEADDRESSMODE_ADDRESSID.

DialParams

Dial parameters to be used on this call, of type LINEDIALPARAMS. When a value of zero is specified for this field, the default value for the field is used as indicated in the DefaultDialParams member of the LINEDEVCAPS structure. If a non-zero value is specified for a field which is outside the range specified by the corresponding fields in MinDialParams and MaxDialParams in the LINEDEVCAPS structure, the nearest value within the valid range is used instead.

dwOrigAddressSize

dwOrigAddressOffset

The size in bytes of the variably sized field holding the originating address, and the offset in bytes from the beginning of this data structure. The format of this address is dependent on the dwAddressMode field.

dwDisplayableAddressSize

dwDisplayableAddressOffset

The displayable string is used for logging purposes. The content of these fields is recorded in the dwDisplayableAddressOffset and dwDisplayableAddressSize fields of the call's LINECALLINFO message. The lineTranslateAddress function returns appropriate information to be placed in this field in the dwDisplayableAddressSize and dwDisplayableAddressOffset fields of the LINETRANSLATEOUTPUT structure.

dwCalledPartySize

dwCalledPartyOffset

The size in bytes of the variably sized field holding called-party information, and the offset in bytes from the beginning of this data structure. This information can be specified by the application that makes the call and is made available in the call's information structure for logging purposes. The format of this field is that of dwStringFormat, as specified in LINEDEVCAPS.

dwCommentSize

dwCommentOffset

The size in bytes of the variably sized field holding comments about the call, and the offset in bytes from the beginning of this data structure. This information can be specified by the application that makes the call and is made available in the call's information structure for logging purposes. The format of this field is that of dwStringFormat, as specified in LINEDEVCAPS.

dwUserUserInfoSize

dwUserUserInfoOffset

The size in bytes of the variably sized field holding user-to-user information, and the offset in bytes from the beginning of this data structure. The protocol discriminator field for the user-user information, if required, should appear as the first byte of the data pointed to by dwUserUserInfoOffset, and must be accounted for in dwUserUserInfoSize.

dwHighLevelCompSize

dwHighLevelCompOffset

The size in bytes of the variably sized field holding high-level compatibility information, and the offset in bytes from the beginning of this data structure

dwLowLevelCompSize

dwLowLevelCompOffset

The size in bytes of the variably sized field holding low-level compatibility information, and the offset in bytes from the beginning of this data structure.

dwDevSpecificSize

dwDevSpecificOffset

The size in bytes of the variably sized field holding device-specific information, and the offset in bytes from the beginning of this data structure

dwPredictiveAutoTransferStates

The LINECALLSTATE_ values, entry into which cause the call to be blind-transferred to the specified target address. Set to 0 if automatic transfer is not desired.

dwTargetAddressSize

dwTargetAddressOffset

The size in bytes and offset from the beginning of LINECALLPARAMS of a string specifying the target dialable address (not dwAddressID); used in the case of certain automatic actions. In the case of predictive dialing, specifies the address to which the call should be automatically transferred. This is essentially the same string that would be passed to lineBlindTransfer if automatic transfer were not being used. Set to 0 if automatic transfer is not desired. In the case of a No Hold Conference, specifies the address that should be conferenced to the call. In the case of a One Step Transfer, specifies the address to dial on the consultation call.

dwSendingFlowspecSize

dwSendingFlowspecOffset

The total size in bytes and offset from the beginning of LINECALLPARAMS of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in SendingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service desired in the sending direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI will not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application.

dwReceivingFlowspecSize

dwReceivingFlowspecOffset

The total size in bytes and offset from the beginning of LINECALLPARAMS of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in ReceivingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service desired in the receiving direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI will not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application.

dwDeviceClassSize

dwDeviceClassOffset

The size in bytes and offset from the beginning of LINECALLPARAMS of a NULL-terminated ASCII string (the size includes the null) that indicates the device class of the device whose configuration is specified in DeviceConfig. Valid device class strings are the same as those specified for the lineGetID function.

dwDeviceConfigSize

dwDeviceConfigOffset

The number of bytes and offset from the beginning of LINECALLPARAMS of the opaque configuration data structure pointed to by dwDevConfigOffset. This value will have been returned in the dwStringSize member in the VARSTRING structure returned by lineGetDevConfig. If the size is 0, the default device configuration is used. This allows the application to set the device configuration before the call is initiated.

dwCallDataSize

dwCallDataOffset

The size in bytes and offset from the beginning of LINECALLPARAMS of the application-settable call data to be initially attached to the call.

dwNoAnswerTimeout

The number of seconds, after the completion of dialing, that the call should be allowed to wait in the PROCEEDING or RINGBACK states, before it is automatically abandoned by the service provider with a LINECALLSTATE_DISCONNECTED and LINEDISCONNECTMODE_NOANSWER. A value of 0 indicates that the application does not desire automatic call abandonment.

dwCallingPartyIDSize

dwCallingPartyIDOffset

The size in bytes and offset from the beginning of LINECALLPARAMS of a NULL-terminated ASCII string (the size includes the null) that specifies the identity of the party placing the call. The service provider will, if the content of the ID is acceptable and a path is available, pass the ID along to the called party to indicate the identity of the calling party.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

This structure is used as a parameter to lineMakeCall when setting up a call. Its fields allow the application to specify the quality of service requested from the network as well as a variety of ISDN call-setup parameters. If no LINECALLPARAMS structure is supplied to lineMakeCall, a default POTS voice-grade call is requested with the default values listed above.

Note  The fields DialParams through dwDevSpecificOffset are ignored when an lpCallParams parameter is specified with the function lineOpen.

The members dwPredictiveAutoTransferStates though dwCallingPartyIDOffset are available only to applications that open the line device with an API version of 0x00020000 or greater.

See Also

lineBlindTransfer, LINEDEVCAPS, LINEDIALPARAMS, lineGetDevConfig, lineMakeCall, lineOpen, lineTranslateAddress, LINETRANSLATEOUTPUT, VARSTRING


LINECALLSTATUS

The LINECALLSTATUS structure describes the current status of a call. The information in this structure, as returned with lineGetCallStatus, depends on the device capabilities of the address, the ownership of the call by the invoking application, and the current state of the call being queried.

typedef struct linecallstatus_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwCallState;

    DWORD  dwCallStateMode;

    DWORD  dwCallPrivilege;

    DWORD  dwCallFeatures;

    DWORD  dwDevSpecificSize;

    DWORD  dwDevSpecificOffset;

    DWORD  dwCallFeatures2;

    SYSTEMTIME  tStateEntryTime;

} LINECALLSTATUS, FAR *LPLINECALLSTATUS;

Members

dwTotalSize

The total size in bytes allocated to this data structure.

dwNeededSize

The size in bytes for this data structure that is needed to hold all the returned information.

dwUsedSize

The size in bytes of the portion of this data structure that contains useful information.

dwCallState

dwCallStateMode

The dwCallState field specifies the current call state of the call. The interpretation of the dwCallStateMode field is call-state-dependent. It specifies the current mode of the call while in its current state (if that state defines a mode). This field uses the following LINECALLSTATE_ constants:

LINECALLSTATE_IDLE

The call state mode is unused.

LINECALLSTATE_OFFERING

The call state mode is of type LINEOFFERINGMODE_. Values are:

LINEOFFERINGMODE_ACTIVE

Indicates that the call is alerting at the current station (will be accompanied by LINEDEVSTATE_RINGING messages), and if any application is set up to automatically answer, it may do so.

LINEOFFERINGMODE_INACTIVE

Indicates that the call is being offered at more than one station, but the current station is not alerting (for example, it may be an attendant station where the offering status is advisory, such as blinking a light).

LINECALLSTATE_ACCEPTED

The call state mode is unused.

LINECALLSTATE_DIALTONE

The call state mode, of type LINEDIALTONEMODE_. Values are:

LINEDIALTONEMODE_NORMAL

This is a "normal" dial tone, which typically is a continuous tone.

LINEDIALTONEMODE_SPECIAL

This is a special dial tone indicating a certain condition is currently in effect.

LINEDIALTONEMODE_INTERNAL

This an internal dial tone, as within a PBX.

LINEDIALTONEMODE_EXTERNAL

This is an external (public network) dial tone.

LINEDIALTONEMODE_UNKNOWN

The dial tone mode is not currently known but may become known later.

LINEDIALTONEMODE_UNAVAIL

The dial tone mode is unavailable and will not become known.

LINECALLSTATE_DIALING

Call state mode is unused.

LINECALLSTATE_RINGBACK

Call state mode is unused.

LINECALLSTATE_BUSY

The call state mode is of type LINEBUSYMODE_. Values are:

LINEBUSYMODE_STATION

The busy signal indicates that the called party's station is busy. This is usually signaled with a "normal" busy tone.

LINEBUSYMODE_TRUNK

The busy signal indicates that a trunk or circuit is busy. This is usually signaled with a "long" busy tone.

LINEBUSYMODE_UNKNOWN

The busy signal's specific mode is currently unknown but may become known later.

LINEBUSYMODE_UNAVAIL

The busy signal's specific mode is unavailable and will not become known.

LINECALLSTATE_SPECIALINFO

The call state mode is of type LINESPECIALINFO_. Values are:

LINESPECIALINFO_NOCIRCUIT

This special information tone precedes a no circuit or emergency announcement (trunk blockage category).

LINESPECIALINFO_CUSTIRREG

This special information tone precedes a vacant number, AIS, Centrex number change and nonworking station, access code not dialed or dialed in error, or manual intercept operator message (customer irregularity category).

LINESPECIALINFO_REORDER

This special information tone precedes a reorder announcement (equipment irregularity category).

LINESPECIALINFO_UNKNOWN

Specifics about the special information tone are currently unknown but may become known later.

LINESPECIALINFO_UNAVAIL

Specifics about the special information tone are unavailable and will not become known.

LINECALLSTATE_CONNECTED

Call state mode is of type LINECONNECTEDMODE_. Values are:

LINECONNECTEDMODE_ACTIVE

Indicates that the call is connected at the current station (the current station is a participant in the call).

LINECONNECTEDMODE_INACTIVE

Indicates that the call is active at one or more other stations, but the current station is not a participant in the call.

LINECALLSTATE_PROCEEDING

Call state mode is unused.

LINECALLSTATE_ONHOLD

Call state mode is unused.

LINECALLSTATE_CONFERENCED

Call state mode is unused.

LINECALLSTATE_ONHOLDPENDCONF

Call state mode is unused.

LINECALLSTATE_ONHOLDPENDTRANSF

Call state mode is unused.

LINECALLSTATE_DISCONNECTED

Call state mode is of type LINEDISCONNECTMODE_. Values are:

LINEDISCONNECTMODE_NORMAL

This is a "normal" disconnect request by the remote party. The call was terminated normally.

LINEDISCONNECTMODE_UNKNOWN

The reason for the disconnect request is unknown.

LINEDISCONNECTMODE_REJECT

The remote user has rejected the call.

LINEDISCONNECTMODE_PICKUP

The call was picked up from elsewhere.

LINEDISCONNECTMODE_FORWARDED

The call was forwarded by the switch.

LINEDISCONNECTMODE_BUSY

The remote user's station is busy.

LINEDISCONNECTMODE_NOANSWER

The remote user's station does not answer.

LINEDISCONNECTMODE_NODIALTONE

A dial tone was not detected within a service-provider defined timeout, at a point during dialing when one was expected (such as at a "W" in the dialable string). This can also occur without a service-provider-defined timeout period or without a value specified in the dwWaitForDialTone member of the LINEDIALPARAMS structure.

LINEDISCONNECTMODE_BADADDRESS

The destination address in invalid.

LINEDISCONNECTMODE_UNREACHABLE

The remote user could not be reached.

LINEDISCONNECTMODE_CONGESTION

The network is congested.

LINEDISCONNECTMODE_INCOMPATIBLE

The remote user's station equipment is incompatible with the type of call requested.

LINEDISCONNECTMODE_UNAVAIL

The reason for the disconnect is unavailable and will not become known later.

LINECALLSTATE_UNKNOWN

Call state mode is unused.

dwCallPrivilege

The application's privilege for this call. This field uses the following LINECALLPRIVILEGE_ constants. Values are:

LINECALLPRIVILEGE_MONITOR

The application has monitor privilege.

LINECALLPRIVILEGE_OWNER

The application has owner privilege.

dwCallFeatures

These flags indicate which Telephony API functions can be invoked on the call, given the availability of the feature in the device capabilities, the current call state, and call ownership of the invoking application. A zero indicates the corresponding feature cannot be invoked by the application on the call in its current state; a one indicates the feature can be invoked. This field uses LINECALLFEATURE_ constants.

dwDevSpecificSize

dwDevSpecificOffset

The size in bytes of the variably sized device-specific field, and the offset in bytes from the beginning of this data structure.

dwCallFeatures2

Indicates additional functions can be invoked on the call, given the availability of the feature in the device capabilities, the current call state, and call ownership of the invoking application. An extension of the dwCallFeatures field. This field uses LINECALLFEATURE2_ constants.

tStateEntryTime

The Coordinated Universal Time at which the current call state was entered.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The application is sent a LINE_CALLSTATE message whenever the call state of a call changes. This message only provides the new call state of the call. Additional status about a call is available with lineGetCallStatus.

The members dwCallFeatures2 and tStateEntryTime are available only to applications that open the line device with an API version of 0x00020000 or greater.

See Also

LINE_CALLSTATE, LINEDIALPARAMS, lineGetCallStatus


LINECALLTREATMENTENTRY

typedef struct linecalltreatmententry_tag {

    DWORD  dwCallTreatmentID;

    DWORD  dwCallTreatmentNameSize;

    DWORD  dwCallTreatmentNameOffset;

} LINECALLTREATMENTENTRY, FAR *LPLINECALLTREATMENTENTRY;

Members

dwCallTreatmentID

One of the LINECALLTREATMENT_ constants (if the treatment is of a predefined type) or a service provider-specific value.

dwCallTreatmentNameSize

dwCallTreatmentNameOffset

Size in bytes (including the terminating null) and offset from the beginning of LINEADDRESSCAPS of a null-terminated string identifying the treatment. This would ordinarily describe the content of the music or recorded announcement. If the treatment is of a predefined type, a meaningful name should still be specified, for example, "Silence\0", "Busy Signal\0", "Ringback\0", or "Music\0".


LINECARDENTRY

The LINECARDENTRY structure describes a calling card.

typedef struct linecardentry_tag {

    DWORD  dwPermanentCardID;

    DWORD  dwCardNameSize;

    DWORD  dwCardNameOffset;

    DWORD  dwCardNumberDigits;

    DWORD  dwSameAreaRuleSize;

    DWORD  dwSameAreaRuleOffset;

    DWORD  dwLongDistanceRuleSize;

    DWORD  dwLongDistanceRuleOffset;

    DWORD  dwInternationalRuleSize;

    DWORD  dwInternationalRuleOffset;

    DWORD  dwOptions;

} LINECARDENTRY, FAR *LPLINECARDENTRY;

Members

dwPermanentCardID

The permanent ID that identifies the card.

dwCardNameSize

dwCardNameOffset

Contains a NULL-terminated ASCII string (size includes the NULL) that describes the card in a user-friendly manner.

dwCardNumberDigits

The number of digits in the existing card number. The card number itself is not returned for security reasons (it is stored in scrambled form by TAPI). The application can use this to insert filler bytes into a text control in "password" mode to show that a number exists.

dwSameAreaRuleSize

dwSameAreaRuleOffset

The offset in bytes from the beginning of the LINETRANSLATECAPS structure and the total number of bytes in the dialing rule defined for calls to numbers in the same area code. The rule is a null-terminated ASCII string.

dwLongDistanceRuleSize

dwLongDistanceRuleOffset

The offset in bytes from the beginning of the LINETRANSLATECAPS structure and the total number of bytes in the dialing rule defined for calls to numbers in the other areas in the same country. The rule is a null-terminated ASCII string.

dwInternationalRuleSize

dwInternationalRuleOffset

The offset in bytes from the beginning of the LINETRANSLATECAPS structure and the total number of bytes in the dialing rule defined for calls to numbers in other countries. The rule is a null-terminated ASCII string.

dwOptions

Indicates other settings associated with this calling card, using the LINECARDOPTION_ set of constants.

Remarks

Older applications will have been compiled without knowledge of these new fields, and using a SIZEOF LINECARDENTRY smaller than the new size. Because this is an array in the variable portion of a LINETRANSLATECAPS structure, it is imperative that older applications receive LINECARDENTRY structures in the format they previously expected, or they will not be able to index properly through the array. The application passes in a dwAPIVersion parameter with the lineGetTranslateCaps function, which can be used for guidance by TAPI in handling this situation. lineGetTranslateCaps should use the LINECARDENTRY fields and size that match the indicated API version, when building the LINETRANSLATECAPS structure to be returned to the application.

No extensions.

See Also

lineGetTranslateCaps, LINETRANSLATECAPS


LINECOUNTRYENTRY

The LINECOUNTRYENTRY structure provides the information for a single country entry. An array of 1 or more of these structures is returned as part of the LINECOUNTRYLIST structure returned by the function lineGetCountry.

typedef struct linecountryentry_tag {

    DWORD  dwCountryID;

    DWORD  dwCountryCode;

    DWORD  dwNextCountryID;

    DWORD  dwCountryNameSize;

    DWORD  dwCountryNameOffset;

    DWORD  dwSameAreaRuleSize;

    DWORD  dwSameAreaRuleOffset;

    DWORD  dwLongDistanceRuleSize;

    DWORD  dwLongDistanceRuleOffset;

    DWORD  dwInternationalRuleSize;

    DWORD  dwInternationalRuleOffset;

} LINECOUNTRYENTRY, FAR *LPLINECOUNTRYENTRY;

Members

dwCountryID

The country ID of the entry. The country ID is an internal identifier which allows multiple entries to exist in the country list with the same country code (for example, all countries in North America and the Caribbean share country code 1, but require separate entries in the list).

dwCountryCode

The actual country code of the country represented by the entry (that is, the digits that would be dialed in an international call). Only this value should ever be displayed to users (country IDs should never be displayed, as they would be confusing).

dwNextCountryID

The country ID of the next entry in the country list. Because country codes and IDs are not assigned in any regular numeric sequence, the country list is a single linked list, with each entry pointing to the next. The last country in the list has a dwNextCountryID value of 0. When the LINECOUNTRYLIST structure is used to obtain the entire list, the entries in the list will be in sequence as linked by their dwNextCountryID fields.

dwCountryNameSize

dwCountryNameOffset

The size in bytes and the offset in bytes from the beginning of the LINECOUNTRYLIST structure of a null-terminated string giving the name of the country.

dwSameAreaRuleSize

dwSameAreaRuleOffset

The size in bytes and the offset in bytes from the beginning of the LINECOUNTRYLIST structure of a null-terminated ASCII string containing the dialing rule for direct-dialed calls to the same area code.

dwLongDistanceRuleSize

dwLongDistanceRuleOffset

The size in bytes and the offset in bytes from the beginning of the LINECOUNTRYLIST structure of a null-terminated ASCII string containing the dialing rule for direct-dialed calls to other areas in the same country.

dwInternationalRuleSize

dwInternationalRuleOffset

The size in bytes and the offset in bytes from the beginning of the LINECOUNTRYLIST structure of a null-terminated ASCII string containing the dialing rule for direct-dialed calls to other countries.

Remarks

Not extensible.

Because this structure is returned by a new function, backward compatibility is not an issue at this time.

See Also

LINECOUNTRYLIST, lineGetCountry


LINECOUNTRYLIST

The LINECOUNTRYLIST structure describes a list of countries. A structure of this type is returned by the function lineGetCountry.

typedef struct linecountrylist_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwNumCountries;

    DWORD  dwCountryListSize;

    DWORD  dwCountryListOffset;

} LINECOUNTRYLIST, FAR *LPLINECOUNTRYLIST;

Members

dwTotalSize

The total size in bytes allocated to this data structure.

dwNeededSize

The size in bytes for this data structure that is needed to hold all the returned information.

dwUsedSize

The size in bytes of the portion of this data structure that contains useful information.

dwNumCountries

The number of LINECOUNTRYENTRY structures present in the array denominated by dwCountryListSize and dwCountryListOffset.

dwCountryListSize

dwCountryListOffset

The size in bytes and the offset in bytes from the beginning of this data structure of an array of LINECOUNTRYENTRY elements which provide the information on each country.

Remarks

Not extensible.

Because this structure is returned by a new function, backward compatibility is not an issue at this time.

See Also

LINECOUNTRYENTRY, lineGetCountry


LINEDEVCAPS

The LINEDEVCAPS structure describes the capabilities of a line device.

typedef struct linedevcaps_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwProviderInfoSize;

    DWORD  dwProviderInfoOffset;

    DWORD  dwSwitchInfoSize;

    DWORD  dwSwitchInfoOffset;

    DWORD  dwPermanentLineID;

    DWORD  dwLineNameSize;

    DWORD  dwLineNameOffset;

    DWORD  dwStringFormat;

    DWORD  dwAddressModes;

    DWORD  dwNumAddresses;

    DWORD  dwBearerModes;

    DWORD  dwMaxRate;

    DWORD  dwMediaModes;

    DWORD  dwGenerateToneModes;

    DWORD  dwGenerateToneMaxNumFreq;

    DWORD  dwGenerateDigitModes;

    DWORD  dwMonitorToneMaxNumFreq;

    DWORD  dwMonitorToneMaxNumEntries;

    DWORD  dwMonitorDigitModes;

    DWORD  dwGatherDigitsMinTimeout;

    DWORD  dwGatherDigitsMaxTimeout;

    DWORD  dwMedCtlDigitMaxListSize;

    DWORD  dwMedCtlMediaMaxListSize;

    DWORD  dwMedCtlToneMaxListSize;

    DWORD  dwMedCtlCallStateMaxListSize;

    DWORD  dwDevCapFlags;

    DWORD  dwMaxNumActiveCalls;

    DWORD  dwAnswerMode;

    DWORD  dwRingModes;

    DWORD  dwLineStates;

    DWORD  dwUUIAcceptSize;

    DWORD  dwUUIAnswerSize;

    DWORD  dwUUIMakeCallSize;

    DWORD  dwUUIDropSize;

    DWORD  dwUUISendUserUserInfoSize;

    DWORD  dwUUICallInfoSize;

  LINEDIALPARAMS  MinDialParams;

  LINEDIALPARAMS  MaxDialParams;

  LINEDIALPARAMS  DefaultDialParams;

    DWORD  dwNumTerminals;

    DWORD  dwTerminalCapsSize;

    DWORD  dwTerminalCapsOffset;

    DWORD  dwTerminalTextEntrySize;

    DWORD  dwTerminalTextSize;

    DWORD  dwTerminalTextOffset;

    DWORD  dwDevSpecificSize;

    DWORD  dwDevSpecificOffset;

    DWORD  dwLineFeatures;

    DWORD  dwSettableDevStatus;

    DWORD  dwDeviceClassesSize;

    DWORD  dwDeviceClassesOffset;

} LINEDEVCAPS, FAR *LPLINEDEVCAPS;

Members

dwTotalSize

The total size in bytes allocated to this data structure.

dwNeededSize

The size in bytes for this data structure that is needed to hold all the returned information.

dwUsedSize

The size in bytes of the portion of this data structure that contains useful information.

dwProviderInfoSize

dwProviderInfoOffset

The size in bytes of the variably sized field containing service provider information, and the offset in bytes from the beginning of this data structure. The dwProviderInfoSize/Offset field is intended to provide information about the provider hardware and/or software, such as the vendor name and version numbers of hardware and software. This information can be useful when a user needs to call customer service with problems regarding the provider.

dwSwitchInfoSize

dwSwitchInfoOffset

The size in bytes of the variably sized device field containing switch information, and the offset in bytes from the beginning of this data structure. The dwSwitchInfoSize/Offset field is intended to provide information about the switch to which the line device is connected, such as the switch manufacturer, the model name, the software version, and so on. This information can be useful when a user needs to call customer service with problems regarding the switch.

dwPermanentLineID

The permanent DWORD identifier by which the line device is known in the system's configuration. It is a permanent name for the line device. This permanent name (as opposed to dwDevice ID) does not change as lines are added or removed from the system. It can therefore be used to link line-specific information in INI files (or other files) in a way that is not affected by adding or removing other lines.

dwLineNameSize

dwLineNameOffset

The size in bytes of the variably sized device field containing a user configurable name for this line device, and the offset in bytes from the beginning of this data structure. This name can be configured by the user when configuring the line device's service provider, and is provided for the user's convenience.

dwStringFormat

The string format used with this line device. This field uses the following STRINGFORMAT_ constants:

STRINGFORMAT_ASCII

The ASCII string format using one byte per character.

STRINGFORMAT_DBCS

The DBCS string format using two bytes per character.

STRINGFORMAT_UNICODE

The Unicode string format using two bytes per character.

dwAddressModes

The mode by which the originating address is specified. This field uses the LINEADDRESSMODE_ constants.

dwNumAddresses

The number of addresses associated with this line device. Individual addresses are referred to by address IDs. Address IDs range from zero to one less than the value indicated by dwNumAddresses.

dwBearerModes

This flag array indicates the different bearer modes that the address is able to support. It uses the following LINEBEARERMODE_ constants:

LINEBEARERMODE_VOICE

This is a regular 3.1 kHz analog voice-grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.

LINEBEARERMODE_SPEECH

This corresponds to G.711 speech transmission on the call. The network may use processing techniques such as analog transmission, echo cancellation and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.

LINEBEARERMODE_MULTIUSE

The multiuse mode defined by ISDN.

LINEBEARERMODE_DATA

The unrestricted data transfer on the call. The data rate is specified separately.

LINEBEARERMODE_ALTSPEECHDATA

The alternate transfer of speech or unrestricted data on the same call (ISDN).

LINEBEARERMODE_NONCALLSIGNALING

This corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a "media stream" by the Telephony API).

LINEBEARERMODE_PASSTHROUGH

When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.

dwMaxRate

This field contains the maximum data rate in bits per second for information exchange over the call.

dwMediaModes

This flag array indicates the different media modes the address is able to support. It uses the following LINEMEDIAMODE_ constants:

LINEMEDIAMODE_UNKNOWN

A media stream exists but its mode is not known. This corresponds to a call with an unclassified media type. In typical analog telephony environments, an inbound call's media mode may be unknown until after the call has been answered and the media stream filtered to make a determination.

LINEMEDIAMODE_INTERACTIVEVOICE

The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends.

LINEMEDIAMODE_AUTOMATEDVOICE

The presence of voice energy on the call and the voice is locally handled by an automated application.

LINEMEDIAMODE_DATAMODEM

A data modem session on the call.

LINEMEDIAMODE_G3FAX

A group 3 fax is being sent or received over the call.

LINEMEDIAMODE_G4FAX

A group 4 fax is being sent or received over the call.

LINEMEDIAMODE_TDD

A TDD (Telephony Devices for the Deaf) session on the call.

LINEMEDIAMODE_DIGITALDATA

Digital data being transmitted over the call.

LINEMEDIAMODE_TELETEX

A teletex session on the call. Teletex is one of the telematic services.

LINEMEDIAMODE_VIDEOTEX

A videotex session on the call. Videotex is one the telematic services.

LINEMEDIAMODE_TELEX

A telex session on the call. Telex is one the telematic services.

LINEMEDIAMODE_MIXED

A mixed session on the call. Mixed is one the ISDN telematic services.

LINEMEDIAMODE_ADSI

An ADSI (Analog Display Services Interface) session on the call.

LINEMEDIAMODE_VOICEVIEW

The media mode of the call is VoiceView.

dwGenerateToneModes

The different kinds of tones that can be generated on this line. This field uses the following LINETONEMODE_ constants:

LINETONEMODE_CUSTOM

The tone is a custom tone defined by the specified frequencies.

LINETONEMODE_RINGBACK

The tone to be generated is a ringback tone.

LINETONEMODE_BUSY

The tone is a standard (station) busy tone.

LINETONEMODE_BEEP

The tone is a beep, as used to announce the beginning of a recording.

LINETONEMODE_BILLING

The tone is billing information tone such as a credit card prompt tone.

dwGenerateToneMaxNumFreq

This field contains the maximum number of frequencies that can be specified in describing a general tone using the LINEGENERATETONE data structure when generating a tone using lineGenerateTone. A value of zero indicates that tone generation is not available.

dwGenerateDigitModes

This field specifies the digit modes than can be generated on this line. It uses the following LINEDIGITMODE_ constants:

LINEDIGITMODE_PULSE

Generate digits as pulse/rotary pulse sequences.

LINEDIGITMODE_DTMF

Generate digits as DTMF tones.

dwMonitorToneMaxNumFreq

This field contains the maximum number of frequencies that can be specified in describing a general tone using the LINEMONITORTONE data structure when monitoring a general tone using lineMonitorTones. A value of zero indicates that tone monitor is not available.

dwMonitorToneMaxNumEntries

This field contains the maximum number of entries that can be specified in a tone list to lineMonitorTones.

dwMonitorDigitModes

This field specifies the digit modes than can be detected on this line. It uses the following LINEDIGITMODE_ constants:

LINEDIGITMODE_PULSE

Detect digits as audible clicks that are the result of rotary pulse sequences.

LINEDIGITMODE_DTMF

Detect digits as DTMF tones.

LINEDIGITMODE_DTMFEND

Detect the down edges of digits detected as DTMF tones.

dwGatherDigitsMinTimeout

dwGatherDigitsMaxTimeout

These fields contain the minimum and maximum values in milliseconds that can be specified for both the first digit and inter-digit timeout values used by lineGatherDigits. If both these field are zero, timeouts are not supported.

dwMedCtlDigitMaxListSize

dwMedCtlMediaMaxListSize

dwMedCtlToneMaxListSize

dwMedCtlCallStateMaxListSize

These fields contain the maximum number of entries that can be specified in the digit list, the media list, the tone list, and the call state list parameters of lineSetMediaControl respectively.

dwDevCapFlags

This field specifies various Boolean device capabilities. It uses the following LINEDEVCAPFLAGS_ constants:

LINEDEVCAPFLAGS_CROSSADDRCONF

Specifies whether calls on different addresses on this line can be conferenced.

LINEDEVCAPFLAGS_HIGHLEVCOMP

Specifies whether high-level compatibility information elements are supported on this line.

LINEDEVCAPFLAGS_LOWLEVCOMP

Specifies whether low-level compatibility information elements are supported on this line.

LINEDEVCAPFLAGS_MEDIACONTROL

Specifies whether media-control operations are available for calls at this line.

LINEDEVCAPFLAGS_MULTIPLEADDR

Specifies whether lineMakeCall or lineDial are able to deal with multiple addresses at once (such as for inverse multiplexing).

LINEDEVCAPFLAGS_CLOSEDROP

Specifies what happens when an open line is closed while the application has calls active on the line. If TRUE, the service provider drops (clears) all active calls on the line when the last application that has opened the line closes it with lineClose. If FALSE, the service provider does not drop active calls in such cases. Instead, the calls remain active and under control of external device(s). A service provider typically sets this bit to FALSE if there is some other device that can keep the call alive. For example, if an analog line has the computer and phoneset both connect directly to them in a party-line configuration, the offhook phone will automatically keep the call active even after the computer powers down.

Applications should check this flag to determine whether to warn the user (with an OK/Cancel dialog box) that active calls will be lost.

LINEDEVCAPFLAGS_DIALBILLING

LINEDEVCAPFLAGS_DIALQUIET

LINEDEVCAPFLAGS_DIALDIALTONE

These flags indicate whether the "$", "@", or "W" dialable string modifier is supported for a given line device. It is TRUE if the modifier is supported; otherwise, FALSE. The "?" (prompt user to continue dialing) is never supported by a line device. These flags allow an application to determine "up front" which modifiers would result in the generation of a LINEERR. The application has the choice of pre-scanning dialable strings for unsupported characters, or passing the "raw" string from lineTranslateAddress directly to the provider as part of lineMakeCall (lineDial, and so on) and let the function generate an error to tell it which unsupported modifier occurs first in the string.

dwMaxNumActiveCalls

This field provides the maximum number of (minimum bandwidth) calls that can be active (connected) on the line at any one time. The actual number of active calls may be lower if higher bandwidth calls have been established on the line.

dwAnswerMode

This field specifies the effect on the active call when answering another offering call on a line device. This field uses the following LINEANSWERMODE_ constants:

LINEANSWERMODE_NONE

Answering another call on the same line has no effect on the existing active call(s) on the line.

LINEANSWERMODE_DROP

The currently active call will be automatically dropped.

LINEANSWERMODE_HOLD

The currently active call will automatically be placed on hold.

dwRingModes

This field contains the number of different ring modes that can be reported in the LINE_LINEDEVSTATE message with the ringing indication. Different ring modes range from one to dwRingModes. Zero indicates no ring.

dwLineStates

This field specifies the different line status components for which the application may be notified in a LINE_LINEDEVSTATE message on this line. It uses the following LINEDEVSTATE_ constants:

LINEDEVSTATE_OTHER

Device-status items other than those listed below have changed. The application should check the current device status to determine which items have changed.

LINEDEVSTATE_RINGING

The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending LINE_LINEDEVSTATE messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds.

LINEDEVSTATE_CONNECTED

The line was previously disconnected and is now connected to TAPI.

LINEDEVSTATE_DISCONNECTED

This line was previously connected and is now disconnected from TAPI.

LINEDEVSTATE_MSGWAITON

The "message waiting" indicator is turned on.

LINEDEVSTATE_MSGWAITOFF

The "message waiting" indicator is turned off.

LINEDEVSTATE_NUMCOMPLETIONS

The number of outstanding call completions on the line device has changed.

LINEDEVSTATE_INSERVICE

The line is connected to TAPI. This happens when TAPI is first activated or when the line wire is physically plugged in and in service at the switch while TAPI is active.

LINEDEVSTATE_OUTOFSERVICE

The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.

LINEDEVSTATE_MAINTENANCE

Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.

LINEDEVSTATE_OPEN

The line has been opened.

LINEDEVSTATE_CLOSE

The line has been closed.

LINEDEVSTATE_NUMCALLS

The number of calls on the line device has changed.

LINEDEVSTATE_TERMINALS

The terminal settings have changed.

LINEDEVSTATE_ROAMMODE

The roam mode of the line device has changed.

LINEDEVSTATE_BATTERY

The battery level has changed significantly (cellular).

LINEDEVSTATE_SIGNAL

The signal level has changed significantly (cellular).

LINEDEVSTATE_DEVSPECIFIC

The line's device-specific information has changed.

LINEDEVSTATE_REINIT

Items have changed in the configuration of line devices. To become aware of these changes (such as for the appearance of new line devices), the application should reinitialize its use of TAPI. The hDevice parameter is left NULL for this state change as it applies to any of the lines in the system.

LINEDEVSTATE_LOCK

The locked status of the line device has changed.

LINEDEVSTATE_CAPSCHANGE

Indicates that, due to configuration changes made by the user or other circumstances, one or more of the fields in the LINEDEVCAPS structure for the address have changed. The application should use lineGetDevCaps to read the updated structure. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI in order to obtain the updated information.

LINEDEVSTATE_CONFIGCHANGE

Indicates that configuration changes have been made to one or more of the media devices associated with the line device. The application, if it desires, may use lineGetDevConfig to read the updated information. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will not receive any notification.

LINEDEVSTATE_TRANSLATECHANGE

Indicates that, due to configuration changes made by the user or other circumstances, one or more of the fields in the LINETRANSLATECAPS structure have changed. The application should use lineGetTranslateCaps to read the updated structure. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI in order to obtain the updated information.

LINEDEVSTATE_COMPLCANCEL

Indicates that the call completion identified by the completion ID contained in parameter dwParam2 of the LINE_LINEDEVSTATE message has been externally canceled and is no longer considered valid (if that value were to be passed in a subsequent call to lineUncompleteCall, the function would fail with LINEERR_INVALCOMPLETIONID). If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will not receive any notification.

LINEDEVSTATE_REMOVED

Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A LINE_LINEDEVSTATE message with this value will normally be immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized will result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will not receive any notification.

dwUUIAcceptSize

This field specifies the maximum size of user-to-user information that can be sent during a call accept.

dwUUIAnswerSize

This field specifies the maximum size of user-to-user information that can be sent during a call answer.

dwUUIMakeCallSize

This field specifies the maximum size of user-to-user information that can be sent during a make call.

dwUUIDropSize

This field specifies the maximum size of user-to-user information that can be sent during a call drop.

dwUUISendUserUserInfoSize

This field specifies the maximum size of user-to-user information that can be sent separately any time during a call with lineSendUserUserInfo.

dwUUICallInfoSize

This field specifies the maximum size of user-to-user information that can be received in the LINECALLINFO structure.

MinDialParams

MaxDialParams

These fields contain the minimum and maximum values for the dial parameters in milliseconds that can be set for calls on this line. Dialing parameters can be set to values in this range. The granularity of the actual settings is service provider-specific.

DefaultDialParams

This field contains the default dial parameters used for calls on this line. These parameter values can be overridden on a per-call basis.

dwNumTerminals

The number of terminals that can be set for this line device, its addresses, or its calls. Individual terminals are referred to by terminal IDs and range from zero to one less than the value indicated by dwNumTerminals.

dwTerminalCapsSize

dwTerminalCapsOffset

The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing an array with entries of type LINETERMCAPS. This array is indexed by terminal IDs, in the range from zero to dwNumTerminals minus one. Each entry in the array specifies the terminal device capabilities of the corresponding terminal.

dwTerminalTextEntrySize

The size in bytes of each of the terminal text descriptions pointed at by dwTerminalTextSize/Offset.

dwTerminalTextSize

dwTerminalTextOffset

The size in bytes of the variably sized field containing descriptive text about each of the line's available terminals, and the offset in bytes from the beginning of this data structure. Each message is dwTerminalTextEntrySize bytes long. The string format of these textual descriptions is indicated by dwStringFormat in the line's device capabilities.

dwDevSpecificSize

dwDevSpecificOffset

The size in bytes of the variably sized device-specific field, and the offset in bytes from the beginning of this data structure

dwLineFeatures

This field specifies the features available for this line using the LINEFEATURE_ constants. Invoking a supported feature requires the line to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the line is in the appropriate state for the operation to be meaningful. This field allows an application to discover which line features can be (and which can never be) supported by the device.

dwSettableDevStatus

The LINEDEVSTATUS_ values which can be modified using lineSetLineDevStatus.

dwDeviceClassesSize

dwDeviceClassesOffset

Length in bytes and offset from the beginning of LINEDEVCAPS of a string consisting of the device class identifiers supported on one or more addresses on this line for use with lineGetID, separated by nulls; the last identifier in the list is followed by two nulls.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

Older applications will have been compiled without new fields in the LINEDEVCAPS structure, and using a SIZEOF LINEDEVCAPS smaller than the new size. The application passes in a dwAPIVersion parameter with the lineGetDevCaps function, which can be used for guidance by TAPI in handling this situation. If the application passes in a dwTotalSize less than the size of the fixed portion of the structure as defined in the dwAPIVersion specified, LINEERR_STRUCTURETOOSMALL will be returned. If sufficient memory has been allocated by the application, before calling TSPI_lineGetDevCaps, TAPI will set the dwNeededSize and dwUsedSize fields to the fixed size of the structure as it existed in the specified API version.

New applications must be cognizant of the API version negotiated, and not examine the contents of fields in the fixed portion beyond the original end of the fixed portion of the structure for the negotiated API version.

If the LINEBEARERMODE_DATA bit is set in dwBearerModes member, the dwMaxRate member indicates the maximum rate of digital transmission on the bearer channel. The dwMaxRate member of the LINEDEVCAPS structure can contain valid values even if the dwBearerModes member of the LINEDEVCAPS structure is not set to LINEBEARERMODE_DATA.

If LINEBEARERMODE_DATA is not set in dwBearerModes, but the LINEBEARERMODE_VOICE value is set and the LINEMEDIAMODE_DATAMODEM value is set in the dwMediaModes member, the dwMaxRate member indicates the maximum SYNCHRONOUS (DCE) bit rate on the phone line for the attached modem or functional equivalent. For example, if the modem's fastest modulation speed is V.32bis at 14,400bps, dwMaxRate will equal 14400. This is not the fastest DTE port rate (which would most likely be 38400, 57600, or 115200), but the fastest bit rate the modem supports on the phone line.

The application must be careful to check to see that LINEBEARERMODE_DATA is not set, to avoid misinterpreting the dwMaxRate member. It is likely to be 64000 or higher if LINEBEARERMODE_DATA is set.

It should also be noted that if the modem has not been specifically identified (for example, it is a "generic" modem), the figure indicated is a "best guess" based on examination of the modem.

The members dwSettableDevStatus through dwDeviceClassesOffset are available only to applications that open the line device with an API version of 0x00020000 or greater.

See Also

LINE_LINEDEVSTATE, LINECALLINFO, lineClose, lineDial, lineGatherDigits, LINEGENERATETONE, lineGenerateTone, lineGetDevCaps, lineGetID, lineGetTranslateCaps, lineSendUserUserInfo, lineMakeCall, LINEMONITORTONE, lineMonitorTones, lineSetMediaControl, LINETERMCAPS, lineTranslateAddress, LINETRANSLATECAPS, lineUncompleteCall


LINEDEVSTATUS

The LINEDEVSTATUS structure describes the current status of a line device.

typedef struct linedevstatus_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwNumOpens;

    DWORD  dwOpenMediaModes;

    DWORD  dwNumActiveCalls;

    DWORD  dwNumOnHoldCalls;

    DWORD  dwNumOnHoldPendCalls;

    DWORD  dwLineFeatures;

    DWORD  dwNumCallCompletions;

    DWORD  dwRingMode;

    DWORD  dwSignalLevel;

    DWORD  dwBatteryLevel;

    DWORD  dwRoamMode;

    DWORD  dwDevStatusFlags;

    DWORD  dwTerminalModesSize;

    DWORD  dwTerminalModesOffset;

    DWORD  dwDevSpecificSize;

    DWORD  dwDevSpecificOffset;

    DWORD dwAvailableMediaModes;

    DWORD dwAppInfoSize;

    DWORD dwAppInfoOffset;

} LINEDEVSTATUS, FAR *LPLINEDEVSTATUS;

Members

dwTotalSize

The total size in bytes allocated to this data structure.

dwNeededSize

The size in bytes for this data structure that is needed to hold all the returned information.

dwUsedSize

The size in bytes of the portion of this data structure that contains useful information.

dwNumOpens

The number of active opens on the line device.

dwOpenMediaModes

This bit array indicates for which media modes the line device is currently open.

dwNumActiveCalls

The number of calls on the line in call states other than idle, onhold, onholdpendingtransfer, and onholdpendingconference.

dwNumOnHoldCalls

The number of calls on the line in the onhold state.

dwNumOnHoldPendingCalls

The number of calls on the line in the onholdpendingtransfer or onholdpendingconference states.

dwLineFeatures

This field specifies the line-related API functions that are currently available on this line. It uses the following LINEFEATURE_ constants:

LINEFEATURE_DEVSPECIFIC

Device-specific operations can be used on the line.

LINEFEATURE_DEVSPECIFICFEAT

Device-specific features can be used on the line.

LINEFEATURE_FORWARD

Forwarding of all addresses can be used on the line.

LINEFEATURE_MAKECALL

An outbound call can be placed on this line using an unspecified address.

LINEFEATURE_SETMEDIACONTROL

Media control can be set on this line.

LINEFEATURE_SETTERMINAL

Terminal modes for this line can be set.

dwNumCallCompletions

The number of outstanding call completion requests on the line.

dwRingMode

The current ring mode on the line device.

dwBatteryLevel

The current battery level of the line device hardware. This is a value in the range 0x00000000 (battery empty) to 0x0000FFFF (battery full).

dwSignalLevel

The current signal level of the connection on the line. This is a value in the range 0x00000000 (weakest signal) to 0x0000FFFF (strongest signal).

dwRoamMode

The current roam mode of the line device. It uses the following LINEROAMMODE_ constants:

LINEROAMMODE_UNKNOWN

The roam mode is currently unknown but may become known later.

LINEROAMMODE_UNAVAIL

The roam mode is unavailable and will not be known.

LINEROAMMODE_HOME

The line is connected to the home network node.

LINEROAMMODE_ROAMA

The line is connected to the Roam-A carrier and calls are charged accordingly.

LINEROAMMODE_ROAMB

The line is connected to the Roam-B carrier and calls are charged accordingly.

dwDevStatusFlags

The size in bytes of this data structure that contains useful information, of type LINEDEVSTATUSFLAGS_.

LINEDEVSTATUSFLAGS_CONNECTED

Specifies whether the line is connected to TAPI. If TRUE, the line is connected and API is able to operate on the line device. If FALSE, the line is disconnected and the application is unable to control the line device using TAPI.

LINEDEVSTATUSFLAGS_LOCKED

This bit is most often used with line devices associated with cellular phones. Many cellular phones have a security mechanism that requires the entry of a password to enable the phone to place calls. This bit may be used to indicate to applications that the phone is locked and cannot place calls until the password is entered on the user interface of the phone, so that the application can present an appropriate alert to the user.

LINEDEVSTATUSFLAGS_MSGWAIT

This field indicates whether the line has a message waiting. If TRUE, a message is waiting; if FALSE, no message is waiting.

LINEDEVSTATUSFLAGS_INSERVICE

This field indicates whether the line is in service. If TRUE, the line is in service; if FALSE, the line is out of service.

dwTerminalModesSize

dwTerminalModesOffset

The size in bytes of the variably sized device field containing an array with DWORD-sized entries, and the offset in bytes from the beginning of this data structure. This array is indexed by terminal IDs, in the range from zero to dwNumTerminals minus one. Each entry in the array specifies the current terminal modes for the corresponding terminal set using the lineSetTerminal operation for this line. It uses the following LINETERMMODE_ constants:

LINETERMMODE_LAMPS

Lamp events sent from the line to the terminal.

LINETERMMODE_BUTTONS

Button-press events sent from the terminal to the line.

LINETERMMODE_DISPLAY

Display information sent from the line to the terminal.

LINETERMMODE_RINGER

Ringer-control information sent from the switch to the terminal.

LINETERMMODE_HOOKSWITCH

Hookswitch events sent between the terminal and the line.

LINETERMMODE_MEDIATOLINE

The unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIAFROMTERM

This is the unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIABIDIRECT

This is the bidirectional media stream associated with a call on the line and the terminal. Use this value when the routing of both unidirectional channels of a call's media stream cannot be controlled independently.

dwDevSpecificSize

dwDevSpecificOffset

The size in bytes of the variably sized device-specific field, and the offset in bytes from the beginning of this data structure.

dwAvailableMediaModes

Indicates the media modes that can be invoked on new calls created on this line device, when the dwLineFeatures field indicates that new calls are possible. If this field is zero, it indicates that the service provider either does not know or cannot indicate which media modes are available, in which case any or all of the media modes indicated in the dwMediaModes field in LINEDEVCAPS may be available.

dwAppInfoSize

dwAppInfoOffset

Length in bytes and offset from the beginning of LINEDEVSTATUS of an array of LINEAPPINFO structures. The dwNumOpens member indicates the number of elements in the array. Each element in the array identifies an application that has the line open.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

These members dwAvailableMediaModes through dwAppInfoOffset are available only to applications that open the line device with an API version of 0x00020000 or greater.

See Also

LINEAPPINFO, LINEDEVCAPS, lineSetTerminal


LINEDIALPARAMS

The LINEDIALPARAMS structure specifies a collection of dialing-related fields.

typedef struct linedialparams_tag {

    DWORD  dwDialPause;

    DWORD  dwDialSpeed;

    DWORD  dwDigitDuration;

    DWORD  dwWaitForDialtone;

} LINEDIALPARAMS, FAR *LPLINEDIALPARAMS;

Members

dwDialPause

The duration in milliseconds of a comma in the dialable address.

dwDialSpeed

The inter-digit time period in milliseconds between successive digits.

dwDigitDuration

The duration in milliseconds of a digit.

dwWaitForDialtone

The maximum amount of time that should be waited for dial tone when a 'W' is used in the dialable address.

Remarks

No extensions.

When a value of zero is specified for a field, the default value for that field is used. If a non-zero value is specified for a field which is outside the range specified by the corresponding fields in MinDialParams and MaxDialParams in the LINEDEVCAPS structure, the nearest value within the valid range is used instead.

The lineMakeCall function allows an application to adjust the dialing parameters to be used for the call. The lineSetCallParams function can be used to adjust the dialing parameters of an existing call. The LINECALLINFO structure lists the call's current dialing parameters.

See Also

LINECALLINFO, LINEDEVCAPS, lineMakeCall, lineSetCallParams


LINEEXTENSIONID

The LINEEXTENSIONID structure describes an extension ID. Extension IDs are used to identify service provider-specific extensions for line devices.

typedef struct lineextensionid_tag {

    DWORD  dwExtensionID0;

    DWORD  dwExtensionID1;

    DWORD  dwExtensionID2;

    DWORD  dwExtensionID3;

} LINEEXTENSIONID, FAR *LPLINEEXTENSIONID;

Members

dwExtensionID0

dwExtensionID1

dwExtensionID2

dwExtensionID3

These four DWORD-sized fields together specify a universally unique extension ID that identifies a line device class extension.

Remarks

No extensions.

Extension IDs are generated using an SDK-provided generation utility.


LINEFORWARD

The LINEFORWARD structure describes an entry of the forwarding instructions.

typedef struct lineforward_tag {

    DWORD  dwForwardMode;

    DWORD  dwCallerAddressSize;

    DWORD  dwCallerAddressOffset;

    DWORD  dwDestCountryCode;

    DWORD  dwDestAddressSize;

    DWORD  dwDestAddressOffset;

} LINEFORWARD, FAR *LPLINEFORWARD;

Members

dwForwardMode

The types of forwarding. The dwForwardMode field can have only a single bit set. This field uses the following LINEFORWARDMODE_ constants:

LINEFORWARDMODE_UNCOND

Forward all calls unconditionally, irrespective of their origin. Use this value when unconditional forwarding for internal and external calls cannot be controlled separately. Unconditional forwarding overrides forwarding on busy and/or no answer conditions.

LINEFORWARDMODE_UNCONDINTERNAL

Forward all internal calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.

LINEFORWARDMODE_UNCONDEXTERNAL

Forward all external calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.

LINEFORWARDMODE_UNCONDSPECIFIC

Unconditionally forward all calls that originated at a specified address (selective call forwarding).

LINEFORWARDMODE_BUSY

Forward all calls on busy, irrespective of their origin. Use this value when forwarding for internal and external calls both on busy and on no answer cannot be controlled separately.

LINEFORWARDMODE_BUSYINTERNAL

Forward all internal calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.

LINEFORWARDMODE_BUSYEXTERNAL

Forward all external calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.

LINEFORWARDMODE_BUSYSPECIFIC

Forward on busy all calls that originated at a specified address (selective call forwarding).

LINEFORWARDMODE_NOANSW

Forward all calls on no answer, irrespective of their origin. Use this value when call forwarding for internal and external calls on no answer cannot be controlled separately.

LINEFORWARDMODE_NOANSWINTERNAL

Forward all internal calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.

LINEFORWARDMODE_NOANSWEXTERNAL

Forward all external calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.

LINEFORWARDMODE_NOANSWSPECIFIC

Forward all calls that originated at a specified address on no answer (selective call forwarding).

LINEFORWARDMODE_BUSYNA

Forward all calls on busy/no answer, irrespective of their origin. Use this value when forwarding for internal and external calls on both busy and on no answer cannot be controlled separately.

LINEFORWARDMODE_BUSYNAINTERNAL

Forward all internal calls on busy/no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.

LINEFORWARDMODE_BUSYNAEXTERNAL

Forward all external calls on busy/no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.

LINEFORWARDMODE_BUSYNASPECIFIC

Forward on busy/no answer all calls that originated at a specified address (selective call forwarding).

LINEFORWARDMODE_UNKNOWN

Calls are forwarded, but the conditions under which forwarding will occur are not known at this time. It is possible that the conditions may become known at a future time.

LINEFORWARDMODE_UNAVAIL

Calls are forwarded, but the conditions under which forwarding will occur are not known, and will never be known by the service provider.

dwCallerAddressSize

dwCallerAddressOffset

The size in bytes of the variably sized address field containing the address of a caller to be forwarded, and the offset in bytes from the beginning of the containing data structure. The dwCallerAddressSize/Offset field is set to zero if dwForwardMode is not one of the following: LINEFORWARDMODE_BUSYNASPECIFIC, LINEFORWARDMODE_NOANSWSPECIFIC, LINEFORWARDMODE_UNCONDSPECIFIC, or LINEFORWARDMODE_BUSYSPECIFIC.

dwDestCountryCode

The country code of the destination address to which the call is to be forwarded.

dwDestAddressSize

dwDestAddressOffset

The size in bytes of the variably sized address field containing the address of the address where calls are to be forwarded, and the offset in bytes from the beginning of the containing data structure.

Remarks

No extensions.

Each entry in the LINEFORWARD structure specifies a forwarding request.


LINEFORWARDLIST

The LINEFORWARDLIST structure describes a list of forwarding instructions.

typedef struct lineforwardlist_tag {

    DWORD  dwTotalSize;

    DWORD  dwNumEntries;

    LINEFORWARD  ForwardList[1];

} LINEFORWARDLIST, FAR *LPLINEFORWARDLIST;

Members

dwTotalSize

The total size in bytes of the data structure.

dwNumEntries

Number of entries in the array specified as ForwardList[ ].

ForwardList[ ]

An array of forwarding instruction. The array's entries are of type LINEFORWARD.

Remarks

No extensions.

The LINEFORWARDLIST structure defines the forwarding parameters requested for forwarding calls on an address or on all addresses on a line.


LINEGENERATETONE

The LINEGENERATETONE structure contains information about a tone to be generated.

typedef struct linegeneratetone_tag {

    DWORD  dwFrequency;

    DWORD  dwCadenceOn;

    DWORD  dwCadenceOff;

    DWORD  dwVolume;

} LINEGENERATETONE, FAR *LPLINEGENERATETONE;

Members

dwFrequency

The frequency in Hertz of this tone component. A service provider may adjust (round up or down) the frequency specified by the application to fit its resolution.

dwCadenceOn

The "on" duration in milliseconds of the cadence of the custom tone to be generated. Zero means no tone is generated.

dwCadenceOff

The "off" duration in milliseconds of the cadence of the custom tone to be generated. Zero means no off time, that is, a constant tone.

dwVolume

The volume level at which the tone is to be generated. A value of 0x0000FFFF represents full volume, and a value of 0x00000000 is silence.

Remarks

No extensions.

This structure is only used for the generation of tones. It is not used for tone monitoring.


LINEINITIALIZEEXPARAMS

typedef struct lineinitializeexparams_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwOptions;

  union

  {

    HANDLE  hEvent;

    HANDLE  hCompletionPort;

  } Handles;

    DWORD  dwCompletionKey;

} LINEINITIALIZEEXPARAMS, FAR *LPLINEINITIALIZEEXPARAMS;

Members

dwOptions

One of the LINEINITIALIZEEXOPTION_ constants. Specifies the event notification mechanism the applications desires to use.

hEvent

If dwOptions specifies LINEINITIALIZEEXOPTION_USEEVENT, TAPI returns the event handle in this field.

hCompletionPort

If dwOptions specifies LINEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this field the handle of an existing completion port opened using CreateIoCompletionPort.

dwCompletionKey

If dwOptions specifies LINEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this field a value that will be returned through the lpCompletionKey parameter of GetQueuedCompletionStatus to identify the completion message as a telephony message.

Remarks

See lineInitializeEx for further information on these options.


LINELOCATIONENTRY

The LINELOCATIONENTRY structure describes a location used to provide an address translation context.

typedef struct linelocationentry_tag {

    DWORD  dwPermanentLocationID;

    DWORD  dwLocationNameSize;

    DWORD  dwLocationNameOffset;

    DWORD  dwCountryCode;

    DWORD  dwCityCodeSize;

    DWORD  dwCityCodeOffset;

    DWORD  dwPreferredCardID;

    DWORD  dwLocalAccessCodeSize;

    DWORD  dwLocalAccessCodeOffset;

    DWORD  dwLongDistanceAccessCodeSize;

    DWORD  dwLongDistanceAccessCodeOffset;

    DWORD  dwTollPrefixListSize;

    DWORD  dwTollPrefixListOffset;

    DWORD  dwCountryID;

    DWORD  dwOptions;

    DWORD  dwCancelCallWaitingSize;

    DWORD  dwCancelCallWaitingOffset;

} LINELOCATIONENTRY, FAR *LPLINELOCATIONENTRY;

Members

dwPermanentLocationID

The permanent ID that identifies the location.

dwLocationNameSize

dwLocationNameOffset

Contains a NULL-terminated ASCII string (size includes the NULL) that describes the location in a user-friendly manner.

dwCountryCode

The country code of the location.

dwPreferredCardID

The preferred calling card when dialing from this location.

dwCityCodeSize

dwCityCodeOffset

Contains a NULL-terminated ASCII string specifying the city/area code associated with the location (the size includes the NULL). This information, along with the country code, can be used by applications to "default" entry fields for the user when entering phone numbers, to encourage the entry of proper canonical numbers.

dwLocalAccessCodeSize

dwLocalAccessCodeOffset

The size in bytes and the offset in bytes from the beginning of the LINETRANSLATECAPS structure of a null-terminated ASCII string containing the access code to be dialed before calls to addresses in the local calling area.

dwLongDistanceAccessCodeSize

dwLongDistanceAccessCodeOffset

The size in bytes and the offset in bytes from the beginning of the LINETRANSLATECAPS structure of a null-terminated ASCII string containing the access code to be dialed before calls to addresses outside the local calling area.

dwTollPrefixListSize

dwTollPrefixListOffset

The size in bytes and the offset in bytes from the beginning of the LINETRANSLATECAPS structure of a null-terminated ASCII string containing the toll prefix list for the location. The string will contain only prefixes consisting of the digits "0" through "9", separated from each other by a single "," (comma) character.

dwCountryID

The country ID of the country selected for the location. This can be used with the lineGetCountry function to obtain additional information about the specific country, such as the country name (the dwCountryCode field cannot be used for this purpose because country codes are not unique).

dwOptions

Indicates options in effect for this location, with values taken from the LINELOCATIONOPTION_ set of constants.

dwCancelCallWaitingSize

dwCancelCallWaitingOffset

The size in bytes and the offset in bytes from the beginning of the LINETRANSLATECAPS structure of a null-terminated ASCII string containing the dial digits and modifier characters that should be prefixed to the dialable string (after the pulse/tone character) when an application sets the LINETRANSLATEOPTION_CANCELCALLWAITING bit in the dwTranslateOptions parameter of lineTranslateAddress. If no prefix is defined, this may be indicated by dwCancelCallWaitingSize being set to 0, or by it being set to 1 and dwCancelCallWaitingOffset pointing to an empty string (single null byte).

Remarks

No extensions.

Older applications will have been compiled without knowledge of these new fields, and using a SIZEOF LINELOCATIONENTRY smaller than the new size. Because this is an array in the variable portion of a LINETRANSLATECAPS structure, it is imperative that older applications receive LINELOCATIONENTRY structures in the format they previously expected, or they will not be able to index through the array properly. The application passes in a dwAPIVersion parameter with the lineGetTranslateCaps function, which can be used for guidance by TAPI in handling this situation. lineGetTranslateCaps should use the LINELOCATIONENTRY fields and size that match the indicated API version, when building the LINETRANSLATECAPS structure to be returned to the application.

See Also

lineGetCountry, lineGetTranslateCaps, lineTranslateAddress, LINETRANSLATECAPS


LINEMEDIACONTROLCALLSTATE

The LINEMEDIACONTROLCALLSTATE structure describes a media action to be executed when detecting transitions into one or more call states.

typedef struct linemediacontrolcallstate_tag {

    DWORD  dwCallStates;

    DWORD  dwMediaControl;

} LINEMEDIACONTROLCALLSTATE, FAR *LPLINEMEDIACONTROLCALLSTATE;

Members

dwCallStates

Specifies one or more call states. This field uses the following LINECALLSTATE_ constants:

LINECALLSTATE_IDLE

The call is idle—no call exists.

LINECALLSTATE_OFFERING

The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user. Alerting is done by the switch instructing the line to ring, and it does not affect any call states.

LINECALLSTATE_ACCEPTED

The call was offering and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also initiates alerting to both parties.

LINECALLSTATE_DIALTONE

The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.

LINECALLSTATE_DIALING

Destination address information (a phone number) is being sent to the switch over the call. Note that the operation lineGenerateDigits does not place the line into the dialing state.

LINECALLSTATE_RINGBACK

The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.

LINECALLSTATE_BUSY

The call is receiving a busy tone. Busy tone indicates that the call cannot be completed because either a circuit (trunk) or the remote party's station are in use.

LINECALLSTATE_SPECIALINFO

Special information is sent by the network. Special information is typically sent when the destination cannot be reached.

LINECALLSTATE_CONNECTED

The call has been established, and the connection is made. Information is able to flow over the call between the originating address and the destination address.

LINECALLSTATE_PROCEEDING

Dialing has completed and the call is proceeding through the switch or telephone network.

LINECALLSTATE_ONHOLD

The call is on hold by the switch.

LINECALLSTATE_CONFERENCED

The call is currently a member of a multiparty conference call.

LINECALLSTATE_ONHOLDPENDCONF

The call is currently on hold while it is being added to a conference.

LINECALLSTATE_ONHOLDPENDTRANSF

The call is currently on hold awaiting transfer to another number.

LINECALLSTATE_DISCONNECTED

The remote party has disconnected from the call.

LINECALLSTATE_UNKNOWN

The state of the call is not known. This may be due to limitations of the call-progress detection implementation.

dwMediaControl

The media-control action. This field uses the following LINEMEDIACONTROL_ constants:

LINEMEDIACONTROL_NONE

No change is to be made to the media stream.

LINEMEDIACONTROL_RESET

Reset the media stream. Equivalent to an end-of-input. All buffers are released.

LINEMEDIACONTROL_PAUSE

Temporarily pause the media stream.

LINEMEDIACONTROL_RESUME

Start or resume a paused media stream.

LINEMEDIACONTROL_RATEUP

The speed of the media stream is increased by some stream-defined quantity.

LINEMEDIACONTROL_RATEDOWN

The speed of the media stream is decreased by some stream-defined quantity.

LINEMEDIACONTROL_RATENORMAL

The speed of the media stream is returned to normal.

LINEMEDIACONTROL_VOLUMEUP

The amplitude of the media stream is increased by some stream-defined quantity.

LINEMEDIACONTROL_VOLUMEDOWN

The amplitude of the media stream is decreased by some stream-defined quantity.

LINEMEDIACONTROL_VOLUMENORMAL

The amplitude of the media stream is returned to normal.

Remarks

No extensions.

The LINEMEDIACONTROLCALLSTATE structure defines a triple <call state(s), media-control action>. An array of these triples is passed to the lineSetMediaControl function to set the media-control actions triggered by the transition to the call state of the given call. When a transition to a listed call state is detected, the corresponding action on the media stream is invoked.

See Also

lineGenerateDigits, lineSetMediaControl


LINEMEDIACONTROLDIGIT

The LINEMEDIACONTROLDIGIT structure describes a media action to be executed when detecting a digit. It is used as an entry in an array.

typedef struct linemediacontroldigit_tag {

    DWORD  dwDigit;

    DWORD  dwDigitModes;

    DWORD  dwMediaControl;

} LINEMEDIACONTROLDIGIT, FAR *LPLINEMEDIACONTROLDIGIT;

Members

dwDigit

The low-order byte of this DWORD specifies the digit in ASCII whose detection is to trigger a media action. Valid digits depend on the media mode.

dwDigitModes

The digit mode(s) that are to be monitored. This field uses the following LINEDIGITMODE_ constants:

LINEDIGITMODE_PULSE

Detect digits as audible clicks that are the result of rotary pulse sequences. Valid digits for pulse are '0' through '9'.

LINEDIGITMODE_DTMF

Detect digits as DTMF tones. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.

LINEDIGITMODE_DTMFEND

Detect and provide application notification of DTMF down edges. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.

dwMediaControl

The media-control action. This field uses the following LINEMEDIACONTROL_ constants:

LINEMEDIACONTROL_NONE

No change is to be made to the media stream.

LINEMEDIACONTROL_RESET

Reset the media stream. Equivalent to an end-of-input. All buffers are released.

LINEMEDIACONTROL_PAUSE

Temporarily pause the media stream.

LINEMEDIACONTROL_RESUME

Start or resume a paused media stream.

LINEMEDIACONTROL_RATEUP

The speed of the media stream is increased by some stream-defined quantity.

LINEMEDIACONTROL_RATEDOWN

The speed of the media stream is decreased by some stream-defined quantity.

LINEMEDIACONTROL_RATENORMAL

The speed of the media stream is returned to normal.

LINEMEDIACONTROL_VOLUMEUP

The amplitude of the media stream is increased by some stream-defined quantity.

LINEMEDIACONTROL_VOLUMEDOWN

The amplitude of the media stream is decreased by some stream-defined quantity.

LINEMEDIACONTROL_VOLUMENORMAL

The amplitude of the media stream is returned to normal.

Remarks

No extensions.

The LINEMEDIACONTROLMEDIA structure defines a triple <digit, digit mode(s), media-control action>. An array of these triples is passed to the lineSetMediaControl function to set the media-control actions triggered by digits detected on a given call. When a listed digit is detected, then the corresponding action on the media stream is invoked.

See Also

LINEMEDIACONTROLMEDIA, lineSetMediaControl


LINEMEDIACONTROLMEDIA

The LINEMEDIACONTROLMEDIA structure describes a media action to be executed when detecting a media-mode change. It is used as an entry in an array.

typedef struct linemediacontrolmedia_tag {

    DWORD  dwMediaModes;

    DWORD  dwDuration;

    DWORD  dwMediaControl;

} LINEMEDIACONTROLMEDIA, FAR *LPLINEMEDIACONTROLMEDIA;

Members

dwMediaModes

One or more media modes. This field uses the following LINEMEDIAMODE_ constants:

LINEMEDIAMODE_UNKNOWN

A media stream exists but its mode is not known. This would correspond to a call with an unclassified media type. In typical analog telephony environments, an inbound call's media mode may be unknown until after the call has been answered and the media stream filtered to make a determination.

LINEMEDIAMODE_INTERACTIVEVOICE

The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends.

LINEMEDIAMODE_AUTOMATEDVOICE

The presence of voice energy on the call and the voice is locally handled by an automated application.

LINEMEDIAMODE_DATAMODEM

A data modem session on the call.

LINEMEDIAMODE_G3FAX

A group 3 fax is being sent or received over the call.

LINEMEDIAMODE_G4FAX

A group 4 fax is being sent or received over the call.

LINEMEDIAMODE_TDD

A TDD (Telephony Devices for the Deaf) session on the call.

LINEMEDIAMODE_DIGITALDATA

Digital data is being sent or received over the call.

LINEMEDIAMODE_TELETEX

A teletex session on the call. Teletex is one of the telematic services.

LINEMEDIAMODE_VIDEOTEX

A videotex session on the call. Videotex is one the telematic services.

LINEMEDIAMODE_TELEX

A telex session on the call. Telex is one the telematic services.

LINEMEDIAMODE_MIXED

A mixed session on the call. Mixed is one the ISDN telematic services.

LINEMEDIAMODE_ADSI

An ADSI (Analog Display Services Interface) session on the call.

LINEMEDIAMODE_VOICEVIEW

The media mode of the call is VoiceView.

dwDuration

The duration in milliseconds during which the media mode should be present before the application should be notified or media-control action should be taken.

dwMediaControl

The media-control action. This field uses the following LINEMEDIACONTROL_ constants:

LINEMEDIACONTROL_NONE

No change is to be made to the media stream.

LINEMEDIACONTROL_RESET

Reset the media stream. Equivalent to an end-of-input. All buffers are released.

LINEMEDIACONTROL_PAUSE

Temporarily pause the media stream.

LINEMEDIACONTROL_RESUME

Start or resume a paused media stream.

LINEMEDIACONTROL_RATEUP

The speed of the media stream is increased by some stream-defined quantity.

LINEMEDIACONTROL_RATEDOWN

The speed of the media stream is decreased by some stream-defined quantity.

LINEMEDIACONTROL_RATENORMAL

The speed of the media stream is returned to normal.

LINEMEDIACONTROL_VOLUMEUP

The amplitude of the media stream is increased by some stream-defined quantity.

LINEMEDIACONTROL_VOLUMEDOWN

The amplitude of the media stream is decreased by some stream-defined quantity.

LINEMEDIACONTROL_VOLUMENORMAL

The amplitude of the media stream is returned to normal.

Remarks

No extensions.

The LINEMEDIACONTROLMEDIA structure defines a triple <media mode(s), duration, media-control action>. An array of these triples is passed to the lineSetMediaControl function to set the media-control actions triggered by media-mode changes for a given call. When a change to a listed media mode is detected, then the corresponding action on the media stream is invoked.

See Also

lineSetMediaControl


LINEMEDIACONTROLTONE

The LINEMEDIACONTROLTONE structure describes a media action to be executed when a tone has been detected. It is used as an entry in an array.

typedef struct linemediacontroltone_tag {

    DWORD  dwAppSpecific;

    DWORD  dwDuration;

    DWORD  dwFrequency1;

    DWORD  dwFrequency2;

    DWORD  dwFrequency3;

    DWORD  dwMediaControl;

} LINEMEDIACONTROLTONE, FAR *LPLINEMEDIACONTROLTONE;

Members

dwAppSpecific

This field is used by the application for tagging the tone. When this tone is detected, the value of the dwAppSpecific field is passed back to the application.

dwDuration

The duration in milliseconds during which the tone should be present before a detection is made.

dwFrequency1

dwFrequency2

dwFrequency3

The frequency in Hertz of a component of the tone. If fewer than three frequencies are needed in the tone, a value of zero should be used for the unused frequencies. A tone with all three frequencies set to zero is interpreted as silence and can be use for silence detection.

dwMediaControl

The media-control action. This field uses the following LINEMEDIACONTROL_ constants:

LINEMEDIACONTROL_NONE

No change is to be made to the media stream.

LINEMEDIACONTROL_RESET

Reset the media stream. Equivalent to an end-of-input. All buffers are released.

LINEMEDIACONTROL_PAUSE

Temporarily pause the media stream.

LINEMEDIACONTROL_RESUME

Start or resume a paused media stream.

LINEMEDIACONTROL_RATEUP

The speed of the media stream is increased by some stream-defined quantity.

LINEMEDIACONTROL_RATEDOWN

The speed of the media stream is decreased by some stream-defined quantity.

LINEMEDIACONTROL_RATENORMAL

The speed of the media stream is returned to normal.

LINEMEDIACONTROL_VOLUMEUP

The amplitude of the media stream is increased by some stream-defined quantity.

LINEMEDIACONTROL_VOLUMEDOWN

The amplitude of the media stream is decreased by some stream-defined quantity.

LINEMEDIACONTROL_VOLUMENORMAL

The amplitude of the media stream is returned to normal.

Remarks

No extensions.

The LINEMEDIACONTROLTONE structure defines a tuple <tone, media-control action>. An array of these tuples is passed to the lineSetMediaControl function to set media-control actions triggered by media-mode changes for a given call. When a change to a listed media mode is detected, the corresponding action on the media stream is invoked.

A tone with all frequencies set to zero corresponds to silence. An application can thus monitor the call's information stream for silence.

See Also

lineSetMediaControl


LINEMESSAGE

typedef struct linemessage_tag {

    DWORD  hDevice;

    DWORD  dwMessageID;

    DWORD  dwCallbackInstance;

    DWORD  dwParam1;

   DWORD  dwParam2;

    DWORD  dwParam3;

} LINEMESSAGE, FAR *LPLINEMESSAGE;

Members

hDevice

A handle to either a line device or a call. The nature of this handle (line handle or call handle) can be determined by the context provided by dwMessageID.

dwMessageID

A line or call device message.

dwCallbackInstance

Instance data passed back to the application, which was specified by the application in lineInitializeEx. This DWORD is not interpreted by TAPI.

dwParam1

A parameter for the message.

dwParam2

A parameter for the message.

dwParam3

A parameter for the message.

Remarks

For information about parameter values passed in this structure, see Line Device Messages.


LINEMONITORTONE

The LINEMONITORTONE structure describes a tone to be monitored. This is used as an entry in an array.

typedef struct linemonitortone_tag {

    DWORD  dwAppSpecific;

    DWORD  dwDuration;

    DWORD  dwFrequency1;

    DWORD  dwFrequency2;

    DWORD  dwFrequency3;

} LINEMONITORTONE, FAR *LPLINEMONITORTONE;

Members

dwAppSpecific

This field is used by the application for tagging the tone. When this tone is detected, the value of the dwAppSpecific field is passed back to the application.

dwDuration

The duration in milliseconds during which the tone should be present before a detection is made.

dwFrequency1

dwFrequency2

dwFrequency3

The frequency in Hertz of a component of the tone. If fewer than three frequencies are needed in the tone, a value of zero should be used for the unused frequencies. A tone with all three frequencies set to zero is interpreted as silence and can be used for silence detection.

Remarks

No extensions.

The LINEMONITORTONE structure defines a tone for the purpose of detection. An array of tones is passed to the lineMonitorTones function which monitors these tones and sends a LINE_MONITORTONE message to the application when a detection is made.

A tone with all frequencies set to zero corresponds to silence. An application can thus monitor the call's information stream for silence.

See Also

LINE_MONITORTONE, lineMonitorTones


LINEPROVIDERENTRY

The LINEPROVIDERENTRY structure provides the information for a single service provider entry. An array of these structures is returned as part of the LINEPROVIDERLIST structure returned by the function lineGetProviderList.

typedef struct lineproviderentry_tag {

    DWORD  dwPermanentProviderID;

    DWORD  dwProviderFilenameSize;

    DWORD  dwProviderFilenameOffset;

} LINEPROVIDERENTRY, FAR *LPLINEPROVIDERENTRY;

Members

dwPermanentProviderID

The permanent provider ID of the entry.

dwProviderFilenameSize

dwProviderFilenameOffset

The size in bytes and the offset in bytes from the beginning of the LINEPROVIDERLIST structure of a null-terminated ASCII string containing the filename (path) of the service provider DLL (.TSP) file.

Remarks

Not extensible.

See Also

lineGetProviderList, LINEPROVIDERLIST


LINEPROVIDERLIST

The LINEPROVIDERLIST structure describes a list of service providers. A structure of this type is returned by the function lineGetProviderList.

typedef struct lineproviderlist_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwNumProviders;

    DWORD  dwProviderListSize;

    DWORD  dwProviderListOffset;

} LINEPROVIDERLIST, FAR *LPLINEPROVIDERLIST;

Members

dwTotalSize

The total size in bytes allocated to this data structure.

dwNeededSize

The size in bytes for this data structure that is needed to hold all the returned information.

dwUsedSize

The size in bytes of the portion of this data structure that contains useful information.

dwNumProviders

The number of LINEPROVIDERENTRY structures present in the array denominated by dwProviderListSize and dwProviderListOffset.

dwProviderListSize

dwProviderListOffset

The size in bytes and the offset in bytes from the beginning of this data structure of an array of LINEPROVIDERENTRY elements which provide the information on each service provider.

Remarks

Not extensible.


LINEPROXYREQUEST

typedef struct lineproxyrequest_tag {

    DWORD dwSize;

    DWORD dwClientMachineNameSize;

    DWORD dwClientMachineNameOffset;

    DWORD dwClientUserNameSize;

    DWORD dwClientUserNameOffset;

    DWORD dwClientAppAPIVersion;

    DWORD dwRequestType;

  union {

   struct {

    DWORD dwAddressID;

      LINEAGENTGROUPLIST GroupList;

      } SetAgentGroup;

   struct {

    DWORD dwAddressID;

    DWORD dwAgentState;

    DWORD dwNextAgentState;

      } SetAgentState;

   struct {

    DWORD dwAddressID;

    DWORD dwActivityID;

      } SetAgentActivity;

   struct {

    DWORD dwAddressID;

      LINEAGENTCAPS AgentCaps;

      } GetAgentCaps;

   struct {

    DWORD dwAddressID;

      LINEAGENTSTATUS AgentStatus;

      } GetAgentStatus;

   struct {

    DWORD dwAddressID;

    DWORD dwAgentExtensionIDIndex;

    DWORD dwSize;

      BYTE Params[1];

      } AgentSpecific;

   struct {

    DWORD dwAddressID;

      LINEAGENTACTIVITYLIST ActivityList;

      } GetAgentActivityList;

   struct {

    DWORD dwAddressID;

      LINEAGENTGROUPLIST GroupList;

      } GetAgentGroupList;

  };

} LINEPROXYREQUEST, FAR *LPLINEPROXYREQUEST;

Members

dwSize

The total number of bytes allocated by TAPI to contain the LINEPROXYREQUEST structure. Note that the dwTotalSize field of any structure contained within LINEPROXYREQUEST (for example, LINEAGENTCAPS) reflects only the number of bytes allocated for that specific structure.

dwClientMachineNameSize

dwClientMachineNameOffset

Size in bytes (including the terminating null) and offset from the beginning of LINEPROXYREQUEST of a null-terminated string identifying the client machine that made this request.

dwClientUserNameSize

dwClientUserNameOffset

Size in bytes (including the terminating null) and offset from the beginning of LINEPROXYREQUEST of a null-terminated string identifying the user under whose account the application is running on the client machine.

dwClientAppAPIVersion

The global (highest) API version supported by the application that made the request. The proxy handler should restrict the contents of any data returned to the application to those fields and values that were defined in this, or earlier, versions of TAPI.

dwRequestType

One of the LINEPROXYREQUEST_ constants. Identifies the type of function and the union component that defines the remaining data in the structure.

SetAgentGroup

The union component used when dwRequestType is LINEPROXYREQUEST_SETAGENT.

dwAddressID

The identifier of the address for which the agent is to be set.

GroupList

A structure of type LINEAGENTGROUPLIST. Offsets within this structure are relative to the beginning of SetAgentGroup.GroupList rather than the beginning of the LINEPROXYREQUEST structure.

SetAgentState

The union component used when dwRequestType is LINEPROXYREQUEST_SETAGENTSTATE.

dwAddressID

The identifier of the address for which the agent state is to be set.

dwAgentState

The new agent state, or 0 to leave the agent state unchanged.

dwNextAgentState

The new next agent state, or 0 to use the default next state associated with the specified agent state.

SetAgentActivity

The union component used when dwRequestType is LINEPROXYREQUEST_SETAGENTACTIVITY.

dwAddressID

The identifier of the address for which the agent activity is to be set.

dwActivityID

The identifier for the activity being selected.

GetAgentCaps

The union component used when dwRequestType is LINEPROXYREQUEST_GETAGENTCAPS.

dwAddressID

The identifier of the address for which the agent capabilities are to be retrieved.

AgentCaps

A structure of type LINEAGENTCAPS. Offsets within this structure are relative to the beginning of GetAgentCaps.AgentCaps rather than the beginning of the LINEPROXYREQUEST structure. The dwTotalSize field is set by TAPI and the remaining bytes set to 0. The proxy handler must fill in dwNeededSize, dwUsedSize, and the remaining fields as appropriate, before calling lineProxyResponse.

GetAgentStatus

The union component used when dwRequestType is LINEPROXYREQUEST_SETAGENTGROUP.

dwAddressID

The identifier of the address for which the agent status is to be retrieved.

AgentStatus

A structure of type LINEAGENTSTATUS. Offsets within this structure are relative to the beginning of GetAgentStatus.AgentStatus rather than the beginning of the LINEPROXYREQUEST structure. The dwTotalSize field is set by TAPI and the remaining bytes set to 0. The proxy handler must fill in dwNeededSize, dwUsedSize, and the remaining fields as appropriate, before calling lineProxyResponse.

AgentSpecific

The union component used when dwRequestType is LINEPROXYREQUEST_AGENTSPECIFIC.

dwAddressID

The identifier of the address for which the agent status is to be retrieved.

dwAgentExtensionIDIndex

The index of the handler extension being invoked; the ID's position within the array of extension IDs returned in LINEAGENTCAPS.

dwSize

The total size in bytes of the Params parameter block.

Params

A block of memory which includes the contents passed to the handler from the application. If the handler is to return data to the application, it must be written into this parameter block before calling lineProxyResponse.

GetAgentActivityList

The union component used when dwRequestType is LINEPROXYREQUEST_GETAGENTACTIVITYLIST.

dwAddressID

The identifier of the address for which the agent activity list is to be retrieved.

ActivityList

A structure of type LINEAGENTACTIVITYLIST. Offsets within this structure are relative to the beginning of GetAgentActivityList.ActivityList rather than the beginning of the LINEPROXYREQUEST structure. The dwTotalSize field is set by TAPI and the remaining bytes set to 0. The proxy handler must fill in dwNeededSize, dwUsedSize, and the remaining fields as appropriate, before calling lineProxyResponse.

GetAgentGroupList

The union component used when dwRequestType is LINEPROXYREQUEST_GETAGENTGROUPLIST.

dwAddressID

The identifier of the address for which the agent group list is to be retrieved.

GroupList

A structure of type LINEAGENTGROUPLIST. Offsets within this structure are relative to the beginning of GetAgentGroupList.GroupList rather than the beginning of the LINEPROXYREQUEST structure. The dwTotalSize field is set by TAPI and the remaining bytes set to 0. The proxy handler must fill in dwNeededSize, dwUsedSize, and the remaining fields as appropriate, before calling lineProxyResponse.

See Also

lineProxyResponse


LINEREQMAKECALL

The LINEREQMAKECALL structure describes a tapiRequestMakeCall request.

typedef struct linereqmakecall_tag {

    char  szDestAddress[TAPIMAXDESTADDRESSSIZE];

    char  szAppName[TAPIMAXAPPNAMESIZE];

    char  szCalledParty[TAPIMAXCALLEDPARTYSIZE];

    char  szComment[TAPIMAXCOMMENTSIZE];

} LINEREQMAKECALL, FAR *LPLINEREQMAKECALL;

Members

szDestAddress[TAPIMAXADDRESSSIZE]

The NULL-terminated destination address of the make-call request. The address can use the canonical address format or the dialable address format. The maximum length of the address is TAPIMAXDESTADDRESSSIZE characters, which includes the NULL terminator. Longer strings are truncated.

szAppName[TAPIMAXAPPNAMESIZE]

The ASCII NULL-terminated user-friendly application name or filename of the application that originated the request. The maximum length of the address is TAPIMAXAPPNAMESIZE characters, which includes the NULL terminator.

szCalledParty[TAPIMAXCALLEDPARTYSIZE]

The ASCII NULL-terminated user-friendly called-party name. The maximum length of the called-party information is TAPIMAXCALLEDPARTYSIZE characters, which includes the NULL terminator.

szComment[TAPIMAXCOMMENTSIZE]

The ASCII NULL-terminated comment about the call request. The maximum length of the comment string is TAPIMAXCOMMENTSIZE characters, which includes the NULL terminator.

Remarks

No extensions.

The szDestAddress field contains the address of the remote party; the other fields are useful for logging purposes. An application must use this structure to interpret the request buffer it received from lineGetRequest with the LINEREQUESTMODE_MAKECALL request mode.

See Also

lineGetRequest, tapiRequestMakeCall


LINETERMCAPS

The LINETERMCAPS structure describes the capabilities of a line's terminal device.

typedef struct linetermcaps_tag {

    DWORD  dwTermDev;

    DWORD  dwTermModes;

    DWORD  dwTermSharing;

} LINETERMCAPS, FAR *LPLINETERMCAPS;

Members

dwTermDev

The device type of the terminal. This field uses the following LINETERMDEV_ constants:

LINETERMDEV_PHONE

The terminal is a phone set.

LINETERMDEV_HEADSET

The terminal is a headset

LINETERMDEV_SPEAKER

The terminal is an external speaker and microphone.

dwTermModes

The terminal mode(s) the terminal device is able to deal with. This field uses the following LINETERMMODE_ constants:

LINETERMMODE_BUTTONS

Button-press events sent from the terminal to the line.

LINETERMMODE_LAMPS

Lamp events sent from the line to the terminal.

LINETERMMODE_DISPLAY

Display information sent from the line to the terminal.

LINETERMMODE_RINGER

Ringer-control information sent from the switch to the terminal.

LINETERMMODE_HOOKSWITCH

Hookswitch events sent from the terminal to the line.

LINETERMMODE_MEDIATOLINE

The unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIAFROMLINE

The unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIABIDIRECT

This is the bidirectional media stream associated with a call on the line and the terminal. Use this value when the routing of both unidirectional channels of a call's media stream cannot be controlled independently.

dwTermSharing

Specifies how the terminal device is shared between line devices. This field uses the following LINETERMSHARING_ constants:

LINETERMSHARING_PRIVATE

The terminal device is private to a single line device.

LINETERMSHARING_SHAREDEXCL

The terminal device can be used by multiple lines. The last line device to do a lineSetTerminal to the terminal for a given terminal mode will have exclusive connection to the terminal for that mode.

LINETERMSHARING_SHAREDCONF

The terminal device can be used by multiple lines. The lineSetTerminal requests of the various terminals end up being "merged" at the terminal.

Remarks

No extensions.

See Also

lineSetTerminal


LINETRANSLATECAPS

The LINETRANSLATECAPS structure describes the address translation capabilities.

typedef struct linetranslatecaps_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwNumLocations;

    DWORD  dwLocationListSize;

    DWORD  dwLocationListOffset;

    DWORD  dwCurrentLocationID;

    DWORD  dwNumCards;

    DWORD  dwCardListSize;

    DWORD  dwCardListOffset;

    DWORD  dwCurrentPreferredCardID;

} LINETRANSLATECAPS, FAR *LPLINETRANSLATECAPS;

Members

dwTotalSize

The total size in bytes allocated to this data structure.

dwNeededSize

The size in bytes for this data structure that is needed to hold all the returned information.

dwUsedSize

The size in bytes of the portion of this data structure that contains useful information.

dwNumLocations

The number of entries in the LocationList. It includes all locations defined, including 0 (default).

dwLocationListSize

dwLocationListOffset

List of locations known to address translation. The list consists of a sequence of LINELOCATIONENTRY structures. The dwLocationListOffset field points to the first byte of the first LINELOCATIONENTRY structure, and the dwLocationListSize field indicates the total number of bytes in the entire list.

dwCurrentLocationID

This is the dwPermanentLocationID from the LINELOCATIONENTRY for the Current Location.

dwNumCards

The number of entries in the CardList.

dwCardListSize

dwCardListOffset

List of calling cards known to address translation. It includes only non-hidden card entries and always includes card 0 (direct dial). The list consists of a sequence of LINECARDENTRY structures. The dwCardListOffset field points to the first byte of the first LINECARDENTRY structure, and the dwCardListSize field indicates the total number of bytes in the entire list.

dwCurrentPreferredCardID

This is the dwPreferredCardID from the LINELOCATIONENTRY for the Current Location.

Remarks

No extensions.

See Also

LINECARDENTRY, LINELOCATIONENTRY


LINETRANSLATEOUTPUT

The LINETRANSLATEOUTPUT structure describes the result of an address translation.

typedef struct linetranslateoutput_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwDialableStringSize;

    DWORD  dwDialableStringOffset;

    DWORD  dwDisplayableStringSize;

    DWORD  dwDisplayableStringOffset;

    DWORD  dwCurrentCountry;

    DWORD  dwDestCountry;

    DWORD  dwTranslateResults;

} LINETRANSLATEOUTPUT, FAR *LPLINETRANSLATEOUTPUT;

Members

dwTotalSize

The total size in bytes allocated to this data structure.

dwNeededSize

The size in bytes for this data structure that is needed to hold all the returned information.

dwUsedSize

The size in bytes of the portion of this data structure that contains useful information.

dwDialableStringSize

dwDialableStringOffset

Contains the translated output which can be passed to the lineMakeCall, lineDial, or other function requiring a dialable string. The output is always a null-terminated ASCII string (null is accounted for in Size). Ancillary fields such as name and subaddress are included in this output string if they were in the input string. This string may contain private information such as calling card numbers. It should not be displayed to the user, to prevent inadvertent visibility to unauthorized persons.

dwDisplayableStringSize

dwDisplayableStringOffset

Contains the translated output which can be displayed to the user for confirmation. It will be identical to DialableString, except that calling card digits will be replaced with the "friendly name" of the card enclosed within bracket characters (for example, "[AT&T Card]"), and ancillary fields such as name and subaddress will be removed. It should normally be safe to display this string in call-status dialog boxes without exposing private information to unauthorized persons. This information is also appropriate to include in call logs.

dwCurrentCountry

Contains the country code configured in CurrentLocation. This value may be used to control the display by the application of certain user interface elements, local call progress tone detection, and for other purposes.

dwDestCountry

Contains the destination country code of the translated address. This value may be passed to the dwCountryCode parameter of lineMakeCall and other dialing functions (so that the call progress tones of the destination country such as a busy signal will be properly detected). This field is set to 0 if the destination address passed to lineTranslateAddress is not in canonical format.

dwTranslateResults

Indicates the information derived from the translation process, which may assist the application in presenting user-interface elements. This field uses the following LINETRANSLATERESULT_ constants:

LINETRANSLATERESULT_CANONICAL

Indicates that the input string was in valid canonical format.

LINETRANSLATERESULT_INTERNATIONAL

If this bit is on, the call is being treated as an international call (country code specified in the destination address is the different from the country code specified for the CurrentLocation).

LINETRANSLATERESULT_LONGDISTANCE

If this bit is on, the call is being treated as a long distance call (country code specified in the destination address is the same but area code is different from those specified for the CurrentLocation).

LINETRANSLATERESULT_LOCAL

If this bit is on, the call is being treated as a local call (country code and area code specified in the destination address are the same as those specified for the CurrentLocation).

LINETRANSLATERESULT_INTOLLLIST

If this bit is on, the local call is being dialed as long distance because the country has toll calling and the prefix appears in the TollPrefixList of the CurrentLocation.

LINETRANSLATERESULT_NOTINTOLLLIST

If this bit is on, the country supports toll calling but the prefix does not appear in the TollPrefixList, so the call is dialed as a local call. Note that if both INTOLLIST and NOTINTOLLIST are off, the current country does not support toll prefixes, and user-interface elements related to toll prefixes should not be presented to the user; if either such bit is on, the country does support toll lists, and the related user-interface elements should be enabled.

LINETRANSLATERESULT_DIALBILLING

Indicates that the returned address contains a "$".

LINETRANSLATERESULT_DIALQUIET

Indicates that the returned address contains a "@".

LINETRANSLATERESULT_DIALDIALTONE

Indicates that the returned address contains a "W".

LINETRANSLATERESULT_DIALPROMPT

Indicates that the returned address contains a "?".

Remarks

No extensions.

See Also

lineDial, lineMakeCall, lineTranslateAddress


Phone Device Structures

The following is the reference for phone device structures.


PHONEBUTTONINFO

The PHONEBUTTONINFO structure contains information about a button on a phone device.

typedef struct phonebuttoninfo_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwButtonMode;

    DWORD  dwButtonFunction;

    DWORD  dwButtonTextSize;

    DWORD  dwButtonTextOffset;

    DWORD  dwDevSpecificSize;

    DWORD  dwDevSpecificOffset;

    DWORD  dwButtonState;

} PHONEBUTTONINFO, FAR *LPPHONEBUTTONINFO;

Members

dwTotalSize

The total size in bytes allocated to this data structure.

dwNeededSize

The size in bytes for this data structure that is needed to hold all the returned information.

dwUsedSize

The size in bytes of the portion of this data structure that contains useful information.

dwButtonMode

The mode or general usage class of the button. This parameter uses the following PHONEBUTTONMODE_ constants:

PHONEBUTTONMODE_DUMMY

This value is used to describe a button/lamp position that has no corresponding button but has only a lamp.

PHONEBUTTONMODE_CALL

The button is assigned to a call appearance.

PHONEBUTTONMODE_FEATURE

The button is assigned to requesting features from the switch, such as hold, conference, and transfer.

PHONEBUTTONMODE_KEYPAD

The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.

PHONEBUTTONMODE_LOCAL

The button is a local function button, such as mute or volume control.

PHONEBUTTONMODE_DISPLAY

The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.

dwButtonFunction

The function assigned to the button. This field uses the PHONEBUTTONFUNCTION_ constants.

dwButtonTextSize

dwButtonTextOffset

The size in bytes of the variably sized field containing descriptive text for this button., and the offset in bytes from the beginning of this data structure. The format of this information is as specified in the dwStringFormat field of the phone's device capabilities.

dwDevSpecificSize

dwDevSpecificOffset

The size in bytes of the variably sized device-specific field, and the offset in bytes from the beginning of this data structure.

dwButtonState

For the phoneGetButtonInfo function, this field indicates the current state of the button, using the PHONEBUTTONSTATE_ constants. This field is ignored by the phoneSetButtonInfo function.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

Older applications will have been compiled without this field in the PHONEBUTTONINFO structure, and using a SIZEOF PHONEBUTTONINFO smaller than the new size. The application passes in a dwAPIVersion parameter with the phoneOpen function, which can be used for guidance by TAPI in handling this situation. If the application passes in a dwTotalSize less than the size of the fixed portion of the structure as defined in the dwAPIVersion specified, PHONEERR_STRUCTURETOOSMALL will be returned. If sufficient memory has been allocated by the application, before calling TSPI_phoneGetButtonInfo, TAPI will set the dwNeededSize and dwUsedSize fields to the fixed size of the structure as it existed in the specified API version.

New service providers (which support the new API version) must examine the API version passed in. If the API version is less than the highest version supported by the provider, the service provider must not fill in fields not supported in older API versions, as these would fall in the variable portion of the older structure.

New applications must be cognizant of the API version negotiated, and not examine the contents of fields in the fixed portion beyond the original end of the fixed portion of the structure for the negotiated API version.

See Also

phoneGetButtonInfo, phoneOpen


PHONECAPS

The PHONECAPS structure describes the capabilities of a phone device.

typedef struct phonecaps_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwProviderInfoSize;

    DWORD  dwProviderInfoOffset;

    DWORD  dwPhoneInfoSize;

    DWORD  dwPhoneInfoOffset;

    DWORD  dwPermanentPhoneID;

    DWORD  dwPhoneNameSize;

    DWORD  dwPhoneNameOffset;

    DWORD  dwStringFormat;

    DWORD  dwPhoneStates;

    DWORD  dwHookSwitchDevs;

    DWORD  dwHandsetHookSwitchModes;

    DWORD  dwSpeakerHookSwitchModes;

    DWORD  dwHeadsetHookSwitchModes;

    DWORD  dwVolumeFlags;

    DWORD  dwGainFlags;

    DWORD  dwDisplayNumRows;

    DWORD  dwDisplayNumColumns;

    DWORD  dwNumRingModes;

    DWORD  dwNumButtonLamps;

    DWORD  dwButtonModesSize;

    DWORD  dwButtonModesOffset;

    DWORD  dwButtonFunctionsSize;

    DWORD  dwButtonFunctionsOffset;

    DWORD  dwLampModesSize;

    DWORD  dwLampModesOffset;

    DWORD  dwNumSetData;

    DWORD  dwSetDataSize;

    DWORD  dwSetDataOffset;

    DWORD  dwNumGetData

    DWORD  dwGetDataSize;

    DWORD  dwGetDataOffset;

    DWORD  dwDevSpecificSize;

    DWORD  dwDevSpecificOffset;

    DWORD dwDeviceClassesSize;

    DWORD dwDeviceClassesOffset;

    DWORD dwPhoneFeatures;

    DWORD dwSettableHandsetHookSwitchModes;

    DWORD dwSettableSpeakerHookSwitchModes;

    DWORD dwSettableHeadsetHookSwitchModes;

    DWORD dwMonitoredHandsetHookSwitchModes;

    DWORD dwMonitoredSpeakerHookSwitchModes;

    DWORD dwMonitoredHeadsetHookSwitchModes;

} PHONECAPS, FAR *LPPHONECAPS;

Members

dwTotalSize

The total size in bytes allocated to this data structure.

dwNeededSize

The size in bytes for this data structure that is needed to hold all the returned information.

dwUsedSize

The size in bytes of the portion of this data structure that contains useful information.

dwProviderInfoSize

dwProviderInfoOffset

The size in bytes of the variably sized field containing service provider-specific information, and the offset in bytes from the beginning of this data structure.

The dwProviderInfoSize/Offset field is intended to provide information about the provider hardware and/or software, such as the vendor name and version numbers of hardware and software. This information can be useful when a user needs to call customer service with problems regarding the provider.

dwPhoneInfoSize

dwPhoneInfoOffset

The size in bytes of the variably sized device field containing phone-specific information, and the offset in bytes from the beginning of this data structure.

The dwPhoneInfoSize/Offset field is intended to provide information about the attached phone device, such as the phone device manufacturer, the model name, the software version, and so on. This information can be useful when a user needs to call customer service with problems regarding the phone.

dwPermanentPhoneID

The permanent DWORD identifier by which the phone device is known in the system's configuration.

dwPhoneNameSize

dwPhoneNameOffset

The size in bytes of the variably sized device field containing a user configurable name for this phone device, and the offset in bytes from the beginning of this data structure This name can be configured by the user when configuring the phone device's service provider and is provided for the user's convenience.

dwStringFormat

The string format to be used with this phone device. This parameter uses the following STRINGFORMAT_ constants:

STRINGFORMAT_ASCII

ASCII string format using one byte per character.

STRINGFORMAT_DBCS

DBCS string format using two bytes per character.

STRINGFORMAT_UNICODE

Unicode string format using two bytes per character.

dwPhoneStates

The state changes for this phone device for which the application can be notified in a PHONE_STATE message. This parameter uses the following PHONESTATE_ constants:

PHONESTATE_OTHER

Phone status items other than those listed below have changed. The application should check the current phone status to determine which items have changed.

PHONESTATE_CONNECTED

The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked or when the wire connecting the phone to the PC is plugged in with TAPI active.

PHONESTATE_DISCONNECTED

The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the PC is unplugged while TAPI is active.

PHONESTATE_OWNER

The number of owners for the phone device has changed.

PHONESTATE_MONITORS

The number of monitors for the phone device has changed.

PHONESTATE_DISPLAY

The display of the phone has changed.

PHONESTATE_LAMP

A lamp of the phone has changed.

PHONESTATE_RINGMODE

The ring mode of the phone has changed.

PHONESTATE_RINGVOLUME

The ring volume of the phone has changed.

PHONESTATE_HANDSETHOOKSWITCH

The handset hookswitch state has changed.

PHONESTATE_HANDSETVOLUME

The handset's speaker volume setting has changed.

PHONESTATE_HANDSETGAIN

The handset's microphone gain setting has changed.

PHONESTATE_SPEAKERHOOKSWITCH

The speakerphone's hookswitch state has changed.

PHONESTATE_SPEAKERVOLUME

The speakerphone's speaker volume setting has changed.

PHONESTATE_SPEAKERGAIN

The speakerphone's microphone gain setting state has changed.

PHONESTATE_HEADSETHOOKSWITCH

The headset's hookswitch state has changed.

PHONESTATE_HEADSETVOLUME

The headset's speaker volume setting has changed.

PHONESTATE_HEADSETGAIN

The headset's microphone gain setting has changed.

PHONESTATE_SUSPEND

The application's use of the phone is temporarily suspended.

PHONESTATE_RESUME

The application's use of the phone device is resumed after having been suspended for some time.

PHONESTATE_DEVSPECIFIC

The phone's device-specific information has changed.

PHONESTATE_REINIT

Items have changed in the configuration of phone devices. To become aware of these changes (as for the appearance of new phone devices) the application should reinitialize its use of TAPI.

PHONESTATE_CAPSCHANGE

Indicates that, due to configuration changes made by the user or other circumstances, one or more of the fields in the PHONECAPS structure have changed. The application should use phoneGetDevCaps to read the updated structure.

PHONESTATE_REMOVED

Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A PHONE_STATE message with this value will normally be immediately followed by a PHONE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized will result in PHONEERR_NODEVICE being returned to the application. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 0x00010004 or above; applications negotiating a previous API version will not receive any notification.

dwHookSwitchDevs

This field specifies the phone's hookswitch devices. This parameter uses the following PHONEHOOKSWITCHDEV_ constants:

PHONEHOOKSWITCHDEV_HANDSET

This is the ubiquitous, handheld, ear- and mouthpiece.

PHONEHOOKSWITCHDEV_SPEAKER

A built-in loudspeaker and microphone. This could also be an externally connected adjunct to the telephone set.

PHONEHOOKSWITCHDEV_HEADSET

This is a headset connected to the phone set.

dwHandsetHookSwitchModes

dwSpeakerHookSwitchModes

dwHeadsetHookSwitchModes

This field specifies the phone's hookswitch mode capabilities of the handset, speaker, or headset, respectively. The field is only meaningful if the hookswitch device is listed in dwHookSwitchDevs. This parameter uses the following PHONEHOOKSWITCHMODE_ constants:

PHONEHOOKSWITCHMODE_ONHOOK

The device's microphone and speaker are both onhook.

PHONEHOOKSWITCHMODE_MIC

The device's microphone is active, the speaker is mute.

PHONEHOOKSWITCHMODE_SPEAKER

The device's speaker is active, the microphone is mute.

PHONEHOOKSWITCHMODE_MICSPEAKER

The device's microphone and speaker are both active.

dwVolumeFlags

This field specifies the volume setting capabilities of the phone device's speaker components. If the bit in position PHONEHOOKSWITCHDEV_ is TRUE, the volume of the corresponding hookswitch device's speaker component can be adjusted with phoneSetVolume; otherwise FALSE.

dwGainFlags

This field specifies the gain setting capabilities of the phone device's microphone components. If the bit position PHONEHOOKSWITCHDEV_ is TRUE, the volume of the corresponding hookswitch device's microphone component can be adjusted with phoneSetGain; otherwise FALSE.

dwDisplayNumRows

This field specifies the display capabilities of the phone device by describing the number of rows in the phone display. The dwDisplayNumRows and dwDisplayNumColumns fields are both zero for a phone device without a display.

dwDisplayNumColumns

This field specifies the display capabilities of the phone device by describing the number of columns in the phone display. dwDisplayNumRows and dwDisplayNumColumns are both zero for a phone device without a display.

dwNumRingModes

The ring capabilities of the phone device. The phone is able to ring with dwNumRingModes different ring patterns, identified as 1, 2, through dwNumRingModes minus one. If the value of this field is zero, applications have no control over the ring mode of the phone. If the value of this field is greater than zero, it indicates the number of ring modes in addition to silence that are supported by the service provider. A value of 0 in the lpdwRingMode parameter of phoneGetRing or the dwRingMode parameter of phoneSetRing indicates silence (the phone is not ringing or should not be rung), and dwRingMode values of 1 to dwNumRingModes are valid ring modes for the phone device.

dwNumButtonLamps

This field specifies the number of button/lamps on the phone device that are detectable in TAPI. Button/lamps are identified by their ID. Valid button/lamp IDs range from zero to dwNumButtonLamps minus one. The keypad buttons '0', through '9', '*', and '#' are assigned the IDs 0 through 12.

dwButtonModesSize

dwButtonModesOffset

The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field containing the button modes of the phone's buttons. The array is indexed by button/lamp ID. This parameter uses the following PHONEBUTTONMODE_ constants:

PHONEBUTTONMODE_DUMMY

This value is used to describe a button/lamp position that has no corresponding button, but has only a lamp. If the phone provides any non-DUMMY buttons, the PHONE_BUTTON message will be sent to the application if a button is pressed at the phone device.

PHONEBUTTONMODE_CALL

The button is assigned to a call appearance.

PHONEBUTTONMODE_FEATURE

The button is assigned to requesting features from the switch, such as hold, conference, and transfer.

PHONEBUTTONMODE_KEYPAD

The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.

PHONEBUTTONMODE_LOCAL

The button is a local function button, such as mute or volume control.

PHONEBUTTONMODE_DISPLAY

The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.

dwButtonFunctionsSize

dwButtonFunctionsOffset

The size in bytes of the variably sized field containing the button modes of the phone's buttons, and the offset in bytes from the beginning of this data structure. This field uses the values specified by the PHONEBUTTONFUNCTION_ constants. The array is indexed by button/lamp ID.

dwLampModesSize

dwLampModesOffset

The size in bytes of the variably sized field containing the lamp modes of the phone's lamps, and the offset in bytes from the beginning of this data structure. The array is indexed by button/lamp ID. This parameter uses the following PHONELAMPMODE_ constants:

PHONELAMPMODE_BROKENFLUTTER

Broken flutter is the superposition of flash and flutter.

PHONELAMPMODE_FLASH

Flash means slow on and off.

PHONELAMPMODE_FLUTTER

Flutter means fast on and off.

PHONELAMPMODE_OFF

The lamp is off.

PHONELAMPMODE_STEADY

The lamp is continuously lit.

PHONELAMPMODE_WINK

The lamp is winking.

PHONELAMPMODE_DUMMY

This value is used to describe a button/lamp position that has no corresponding lamp.

dwNumSetData

The number of different download areas in the phone device. The different areas are referred to using the data IDs 0, 1, , dwNumSetData minus one. If this field is zero, the phone does not support the download capability.

dwSetDataSize

dwSetDataOffset

The size in bytes of the variably sized field containing the sizes (in bytes) of the phone's download data areas, and the offset in bytes from the beginning of this data structure. This is an array with DWORD-sized elements indexed by data ID.

dwNumGetData

The number of different upload areas in the phone device. The different areas are referred to using the data IDs 0, 1, , dwNumGetData minus one. If this field is zero, the phone does not support the upload capability.

dwGetDataSize

dwGetDataOffset

The size in bytes of the variably sized field containing the sizes (in bytes) of the phone's upload data areas, and the offset in bytes from the beginning of this data structure. This is an array with DWORD-sized elements indexed by data ID.

dwDevSpecificSize

dwDevSpecificOffset

The size in bytes of the variably sized device-specific field, and the offset in bytes from the beginning of this data structure

dwDeviceClassesSize

dwDeviceClassesOffset

Length in bytes and offset from the beginning of PHONECAPS of a string consisting of the device class identifiers supported on this device for use with phoneGetID, separated by nulls; the last identifier in the list is followed by two nulls.

dwPhoneFeatures

These flags indicate which Telephony API functions can be invoked on the phone. A zero indicates the corresponding feature is not implemented and can never be invoked by the application on the phone; a one indicates the feature may be invoked depending on the device state and other factors. This field uses PHONEFEATURE_ constants.

dwSettableHandsetHookSwitchModes

The PHONEHOOKSWITCHMODE_ values which can be set on the handset using phoneSetHookSwitch.

dwSettableSpeakerHookSwitchModes

The PHONEHOOKSWITCHMODE_ values which can be set on the speakerphone using phoneSetHookSwitch.

dwSettableHeadsetHookSwitchModes

The PHONEHOOKSWITCHMODE_ values which can be set on the headset using phoneSetHookSwitch.

dwMonitoredHandsetHookSwitchModes

The PHONEHOOKSWITCHMODE_ values which can be detected and reported for the handset in a PHONE_STATE message and by phoneGetHookSwitch.

dwMonitoredSpeakerHookSwitchModes

The PHONEHOOKSWITCHMODE_ values which can be detected and reported for the speakerphone in a PHONE_STATE message and by phoneGetHookSwitch.

dwMonitoredHeadsetHookSwitchModes

The PHONEHOOKSWITCHMODE_ values which can be detected and reported for the headset in a PHONE_STATE message and by phoneGetHookSwitch.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The members dwDeviceClassesSize through dwMonitoredHeadsetHookSwitchModes are available only to applications that open the phone device with an API version of 0x00020000 or greater.

See Also

PHONE_BUTTON, PHONE_CLOSE, PHONE_STATE, phoneGetDevCaps, phoneGetHookSwitch, phoneGetRing, phoneSetGain, phoneSetHookSwitch, phoneSetRing, phoneSetVolume


PHONEEXTENSIONID

The PHONEEXTENSIONID structure describes an extension ID. Extension IDs are used to identify service provider-specific extensions for phone device classes.

typedef struct phoneextensionid_tag {

    DWORD  dwExtensionID0;

    DWORD  dwExtensionID1;

    DWORD  dwExtensionID2;

    DWORD  dwExtensionID3;

} PHONEEXTENSIONID, FAR *LPPHONEEXTENSIONID;

Members

dwExtensionID0

dwExtensionID1

dwExtensionID2

dwExtensionID3

These four DWORD-sized fields together specify a universally unique extension ID that identifies a phone device class extension.

Remarks

No extensibility.

Extension IDs are generated using an SDK-provided generation utility.


PHONEINITIALIZEEXPARAMS

typedef struct phoneinitializeexparams_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwOptions;

  union

  {

    HANDLE hEvent;

    HANDLE hCompletionPort;

  } Handles;

    DWORD dwCompletionKey;

} PHONEINITIALIZEEXPARAMS, FAR *LPPHONEINITIALIZEEXPARAMS;

Members

dwOptions

One of the PHONEINITIALIZEEXOPTION_ constants. Specifies the event notification mechanism the application desires to use.

hEvent

If dwOptions specifies PHONEINITIALIZEEXOPTION_USEEVENT, TAPI returns the event handle in this field.

hCompletionPort

If dwOptions specifies PHONEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this field the handle of an existing completion port opened using CreateIoCompletionPort.

dwCompletionKey

If dwOptions specifies PHONEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this field a value that will be returned through the lpCompletionKey parameter of GetQueuedCompletionStatus to identify the completion message as a telephony message.

Remarks

See phoneInitializeEx for further information on these options.


PHONEMESSAGE

typedef struct phonemessage_tag {

    DWORD  hDevice;

    DWORD  dwMessageID;

    DWORD  dwCallbackInstance;

    DWORD  dwParam1;

    DWORD  dwParam2;

    DWORD  dwParam3;

} PHONEMESSAGE, FAR *LPPHONEMESSAGE;

Members

hDevice

A handle to a phone device.

dwMessageID

A phone message.

dwCallbackInstance

Instance data passed back to the application, which was specified by the application in phoneInitializeEx. This DWORD is not interpreted by TAPI.

dwParam1

A parameter for the message.

dwParam2

A parameter for the message.

dwParam3

A parameter for the message.

Remarks

For information about parameters values passed in this structure, see Phone Device Messages.

See Also

phoneInitializeEx


PHONESTATUS

The PHONESTATUS structure describes the current status of a phone device.

typedef struct phonestatus_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwStatusFlags;

    DWORD  dwNumOwners;

    DWORD  dwNumMonitors;

    DWORD  dwRingMode;

    DWORD  dwRingVolume;

    DWORD  dwHandsetHookSwitchMode;

    DWORD  dwHandsetVolume;

    DWORD  dwHandsetGain;

    DWORD  dwSpeakerHookSwitchMode;

    DWORD  dwSpeakerVolume;

    DWORD  dwSpeakerGain;

    DWORD  dwHeadsetHookSwitchMode;

    DWORD  dwHeadsetVolume;

    DWORD  dwHeadsetGain;

    DWORD  dwDisplaySize;

    DWORD  dwDisplayOffset;

    DWORD  dwLampModesSize;

    DWORD  dwLampModesOffset;

    DWORD  dwOwnerNameSize;

    DWORD  dwOwnerNameOffset;

    DWORD  dwDevSpecificSize;

    DWORD  dwDevSpecificOffset;

    DWORD dwPhoneFeatures;

} PHONESTATUS, FAR *LPPHONESTATUS;

Members

dwTotalSize

The total size in bytes allocated to this data structure.

dwNeededSize

The size in bytes for this data structure that is needed to hold all the returned information.

dwUsedSize

The size in bytes of the portion of this data structure that contains useful information.

dwStatusFlags

This field provides a set of status flags for this phone device. This parameter uses the following PHONESTATUSFLAGS_ constants:

PHONESTATUSFLAGS_CONNECTED

Specifies whether the phone is currently connected to TAPI. TRUE if connected; FALSE otherwise.

PHONESTATUSFLAGS_SUSPENDED

Specifies whether TAPI's manipulation of the phone device is suspended. TRUE if suspended; FALSE otherwise. An application's use of a phone device may be temporarily suspended when the switch wants to manipulate the phone in a way that cannot tolerate interference from the application.

dwNumOwners

The number of application modules with owner privilege for the phone.

dwNumMonitors

The number of application modules with monitor privilege for the phone.

dwRingMode

The current ring mode of a phone device.

dwRingVolume

The current ring volume of a phone device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).

dwHandsetHookSwitchMode

The current hookswitch mode of the phone's handset. This parameter uses the following PHONEHOOKSWITCHMODE_ constants:

PHONEHOOKSWITCHMODE_ONHOOK

The device's microphone and speaker are both onhook.

PHONEHOOKSWITCHMODE_MIC

The device’s microphone is active, the speaker is mute.

PHONEHOOKSWITCHMODE_SPEAKER

The device's speaker is active, the microphone is mute.

PHONEHOOKSWITCHMODE_MICSPEAKER

The device's microphone and speaker are both active.

dwHandsetVolume

The current speaker volume of the phone's handset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).

dwHandsetGain

The current microphone gain of the phone's handset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum gain).

dwSpeakerHookSwitchMode

The current hookswitch mode of the phone's speakerphone. This parameter uses the following PHONEHOOKSWITCHMODE_ constants:

PHONEHOOKSWITCHMODE_ONHOOK

The device's microphone and speaker are both onhook.

PHONEHOOKSWITCHMODE_MIC

The device's microphone is active, the speaker is mute.

PHONEHOOKSWITCHMODE_SPEAKER

The device's speaker is active, the microphone is mute.

PHONEHOOKSWITCHMODE_MICSPEAKER

The device's microphone and speaker are both active.

dwSpeakerVolume

The current speaker volume of the phone's speaker device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).

dwSpeakerGain

The current microphone gain of the phone's speaker device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum gain).

dwHeadsetHookSwitchMode

The current hookswitch mode of the phone's headset. This parameter uses the following PHONEHOOKSWITCHMODE_ constants:

PHONEHOOKSWITCHMODE_ONHOOK

The device's microphone and speaker are both onhook.

PHONEHOOKSWITCHMODE_MIC

The device's microphone is active, the speaker is mute.

PHONEHOOKSWITCHMODE_SPEAKER

The device's speaker is active, the microphone is mute.

PHONEHOOKSWITCHMODE_MICSPEAKER

The device's microphone and speaker are both active.

dwHeadsetVolume

The current speaker volume of the phone's headset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).

dwHeadsetGain

The current microphone gain of the phone's headset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum gain).

dwDisplaySize

dwDisplayOffset

The size in bytes of the variably sized field containing the phone's current display information, and the offset in bytes, from the beginning of this data structure.

dwLampModesSize

dwLampModesOffset

The size in bytes of the variably sized field containing the phone's current lamp modes, and the offset in bytes from the beginning of this data structure.

dwOwnerNameSize

dwOwnerNameOffset

The size in bytes of the variably sized field containing the name of the application that is the current owner of the phone device, and the offset in bytes from the beginning of this data structure. The name is the application name provided by the application when it invoked with phoneInitialize or phoneInitializeEx . If no application name was supplied, the application's file name is used instead. If the phone currently has no owner, dwOwnerNameSize is zero.

dwDevSpecificSize

dwDevSpecificOffset

The size in bytes of the variably sized device-specific field, and the offset in bytes from the beginning of this data structure

dwPhoneFeatures

These flags indicate which Telephony API functions can be invoked on the phone, considering the availability of the feature in the device capabilities, the current device state, and device ownership of the invoking application. A zero indicates the corresponding feature cannot be invoked by the application on the phone in its current state; a one indicates the feature can be invoked. This field uses PHONEFEATURE_ constants.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The dwPhoneFeatures member is available only to applications that open the phone device with an API version of 0x00020000 or greater.

See Also

phoneInitialize, phoneInitializeEx


VARSTRING

The VARSTRING structure is used for returning variably sized strings. It is used both by the line device class and the phone device class.

typedef struct varstring_tag {

    DWORD  dwTotalSize;

    DWORD  dwNeededSize;

    DWORD  dwUsedSize;

    DWORD  dwStringFormat;

    DWORD  dwStringSize;

    DWORD  dwStringOffset;

} VARSTRING, FAR *LPVARSTRING;

Members

dwTotalSize

The total size in bytes allocated to this data structure.

dwNeededSize

The size in bytes for this data structure that is needed to hold all the returned information.

dwUsedSize

The size in bytes of the portion of this data structure that contains useful information.

dwStringFormat

The format of the string. This parameter uses the following STRINGFORMAT_ constants:

STRINGFORMAT_ASCII

ASCII string format using one byte per character. The actual string is a NULL-terminated ASCII string with the terminating NULL accounted for in the string size.

STRINGFORMAT_DBCS

DBCS string format using one or two bytes per character.

STRINGFORMAT_UNICODE

Unicode string format using two bytes per character.

STRINGFORMAT_BINARY

An array of unsigned characters that could be used for numeric values.

dwStringSize

dwStringOffset

The size in bytes of the variably sized device field containing the string information, and the offset in bytes from the beginning of this data structure.

Remarks

No extensibility.

If a string cannot be returned in a variable structure, the dwStringSize and dwStringOffset members are set in one of these ways:

•	dwStringSize and dwStringOffset members are both set to zero.

•	dwStringOffset is nonzero and dwStringSize is zero.

•	dwStringOffset is nonzero, dwStringSize is 1, and the byte at the given offset is 0.


Unicode Support

The following section contains information about support for Unicode.


Functions with Unicode (W) Versions

The following TAPI functions are implemented in Unicode (W) and ANSI (A) versions. In general, the implementation of the ANSI version calls the Unicode version and performs necessary conversions of ANSI parameters and structure fields to and from Unicode; the following table indicates the parameters that are converted.

Applications that explicitly call the generic (neither "W" or "A" suffix) version of a function will execute the ANSI version, for backward compatibility with previous versions of TAPI.

Note  The entire Telephony Service Provider Interface (TSPI) is Unicode for version 2.0.

In the following table, references to string fields in TAPI structures consist of a portion of the field names. For example, the "Caller Address" in the LINEFORWARD structure is pointed to by a field named dwCallerAddressOffset and delimited by a field named dwCallerAddressSize; in the table, this string is identified simply as CallerAddress.

TAPI Function	Parameters and Structure Fields Converted in ANSI Version of Function
lineAddProvider	lpszProviderName
lineBlindTransfer	lpszDestAddress
lineConfigDialog	lpszDeviceClass
lineConfigDialogEdit	lpszDeviceClass  Note  Application must handle conversion of strings in lpDeviceConfigIn and lpDeviceConfigOut, if these are directly manipulated.
lineDial	lpszDestAddress
lineForward	lpForwardList (LINEFORWARDLIST)  • ForwardList (LINEFORWARD)  • CallerAddress  • DestAddress  lpCallParams (LINECALLPARAMS)  • OrigAddress  • DisplayableAddress  • CalledParty  • Comment  • TargetAddress  • DeviceClass  • CallingPartyID
lineGatherDigits	lpsDigits  lpszTerminationDigits
lineGenerateDigits	lpszDigits
lineGetAddressCaps	lpAddressCaps (LINEADDRESSCAPS)  • Address  • CompletionMsgText  • DeviceClasses  • CallTreatmentList (LINECALLTREATMENTENTRY)  • CallTreatmentName
lineGetAddressID	lpsAddress
lineGetAddressStatus	lpAddressStatus (LINEADDRESSSTATUS)  • Forward (LINEFORWARD)  • CallerAddress  • DestAddress
lineGetAgentActivityList	lpAgentActivityList (LINEAGENTACTIVITYLIST)  • List (LINEAGENTACTIVITYENTRY)  • Name
lineGetAgentCaps	lpAgentCaps (LINEAGENTCAPS)  • AgentHandlerInfo
lineGetAgentGroupList	lpAgentGroupListI(LINEAGENTGROUPLIST)  • List (LINEAGENTGROUPENTRY)  • Name
lineGetAgentStatus	lpAgentStatus (LINEAGENTSTATUS)  • Activity  • GroupList (LINEAGENTGROUPENTRY)  • Name
lineGetAppPriority	lpszAppFilename  lpExtensionName
lineGetCallInfo	lpCallInfo (LINECALLINFO)  • CallerID  • CallerIDName  • CalledID  • CalledIDName  • ConnectID  • ConnectedIDName  • RedirectionID  • RedirectionIDName  • RedirectingID  • RedirectingIDName  • AppName  • DisplayableAddress  • CalledParty  • Comment
lineGetCountry	lpLineCountryList (LINECOUNTRYLIST)  • CountryList (LINECOUNTRYENTRY)  • CountryName  • SameAreaRule  • LongDistanceRule  • InternationalRule
lineGetDevCaps	lpLineDevCaps (LINEDEVCAPS)  • ProviderInfo  • SwitchInfo  • LineName  • TerminalText  • DeviceClasses  Note  dwStringFormat is obsolete.
LineGetDevConfig	lpszDeviceClass  Note  Application must handle conversion of strings in lpDeviceConfig, if these are directly manipulated.
LineGetIcon	lpszDeviceClass
lineGetID	lpszDeviceClass  Note  Application must handle conversion of strings in lpDeviceID, if these are directly manipulated.
LineGetLineDevStatus	lpLineDevStatus (LINEDEVSTATUS)  • AppInfo (LINEAPPINFO)  • MachineName  • UserName  • ModuleFilename  • FriendlyName
lineGetProviderList	lpProviderList (LINEPROVIDERLIST)  • ProviderList (LINEPROVIDERENTRY)  • ProviderFilename
lineGetRequest	lpRequestBuffer (LINEREQMAKECALL  • szDestAddress  • szAppName  • szCalledParty  • szComment
lineGetTranslateCaps	lpTranslateCaps (LINETRANSLATECAPS)  • CardList (LINECARDENTRY)  • CardName  • SameAreaRule  • LongDistanceRule  • InternationalRule  • LocationList (LINELOCATIONENTRY  • LocationName  • CityCode  • LocalAccessCode  • LongDistanceAccessCode  • TollPrefixList  • celCallWaiting
lineHandoff	lpszFileName
lineInitializeEx	lpszFriendlyAppName
lineMakeCall	lpszDestAddress  lpCallParams (LINECALLPARAMS)  • OrigAddress  • DisplayableAddress  • CalledParty  • Comment  • TargetAddress  • DeviceClass  • CallingPartyID
lineOpen	lpCallParams (LINECALLPARAMS)  • OrigAddress  • DisplayableAddress  • CalledParty  • Comment  • TargetAddress  • DeviceClass  • CallingPartyID
linePark	lpszDirAddress  lpNonDirAddress (VARSTRING)  • String
linePickup	lpszDestAddress  lpszGroupID
linePrepareAddToConference	lpCallParams (LINECALLPARAMS)  • OrigAddress  • DisplayableAddress  • CalledParty  • Comment  • TargetAddress  • DeviceClass  • CallingPartyID
lineRedirect	lpszDestAddress
lineSetAppPriority	lpszAppFilename  lpszExtensionName
lineSetDevConfig	lpszDeviceClass  Note  Application must handle conversion of strings in lpDeviceConfig, if these are directly manipulated.
lineSetTollList	lpszAddressIn
lineSetupConference	lpCallParams (LINECALLPARAMS)  • OrigAddress  • DisplayableAddress  • CalledParty  • Comment  • TargetAddress  • DeviceClass  • CallingPartyID
lineSetupTransfer	lpCallParams (LINECALLPARAMS)  • OrigAddress  • DisplayableAddress  • CalledParty  • Comment  • TargetAddress  • DeviceClass  • CallingPartyID
lineTranslateAddress	lpszAddressIn  lpTranslateOutput (LINETRANSLATEOUTPUT)  • DialableString  • DisplayableString
lineTranslateDialog	lpszAddressIn
lineUnpark	lpszDestAddress
phoneConfigDialog	lpszDeviceClass
phoneGetButtonInfo	lpButtonInfo (PHONEBUTTONINFO)  • ButtonText
phoneGetDevCaps	lpPhoneCaps (PHONECAPS)  • ProviderInfo  • PhoneInfo  • PhoneName  • DeviceClasses  Note  dwStringFormat is obsolete.
phoneGetIcon	lpszDeviceClass
phoneGetID	lpszDeviceClass  Note  Application must handle conversion of strings in lpDeviceID, if these are directly manipulated.
phoneGetStatus	lpPhoneStatus (PHONESTATUS)  • OwnerName
phoneInitializeEx	lpszFriendlyAppName
phoneSetButtonInfo	lpButtonInfo (PHONEBUTTONINFO)  • ButtonTest
tapiGetLocationInfo	lpszCountryCode  lpszCityCode
tapiRequestMakeCall	lpszDestAddress  lpszAppName  lpszCalledParty  lpszComment


Functions without Unicode Versions

The following functions are provided only in a generic version without an "A" or "W" suffix.

TAPI Function	Comments
lineAccept	The memory pointed to by lpsUserUserInfo is presumed to contain binary data for end-to-end transfer. The application must provide data in a form ready for transmission.
lineAddToConference	—
lineAgentSpecific	The memory pointed to by lpParams is private between the application and agent handler. The application must provide data in the form specified in the agent handler extension definition.
lineAnswer	The memory pointed to by lpsUserUserInfo is presumed to contain binary data for end-to-end transfer. The application must provide data in a form ready for transmission.
lineClose	—
lineCompleteCall	—
lineCompleteTransfer	—
lineConfigProvider	—
lineDeallocateCall	—
lineDevSpecific	The memory pointed to by lpParams is private between the application and service provider. The application must provide data in the form specified in the service provider extension definition.
lineDevSpecificFeature	The memory pointed to by lpParams is private between the application and service provider. The application must provide data in the form specified in the service provider extension definition.
lineDrop	The memory pointed to by lpsUserUserInfo is presumed to contain binary data for end-to-end transfer. The application must provide data in a form ready for transmission.
lineGenerateTone	—
lineGetCallStatus	—
lineGetConfRelatedCalls	—
lineGetNewCalls	—
lineGetMessage	—
lineGetNumRings	—
lineGetStatusMessages	—
lineHold	—
lineMonitorDigits	—
lineMonitorMedia	—
lineMonitorTones	—
lineNegotiateAPIVersion	—
lineNegotiateExtVersion	—
lineProxyMessage	—
lineProxyResponse	The fields in the LINEPROXYREQUEST structure are always Unicode.
lineRegisterRequestRecipient	—
lineReleaseUserUserInfo	—
lineRemoveFromConference	—
lineRemoveProvider	—
lineSecureCall	—
lineSendUserUserInfo	The memory pointed to by lpsUserUserInfo is presumed to contain binary data for end-to-end transfer. The application must provide data in a form ready for transmission.
lineSetAgentActivity	—
lineSetAgentGroup	Note  Group names are ignored.
lineSetAgentState	—
lineSetAppSpecific	—
lineSetCallData	The memory pointed to by lpCallData is in a format specified by the application or a group of cooperating applications. The format of the data is beyond the scope of TAPI and is not converted by TAPI.
lineSetCallParams	—
lineSetCallPrivilege	—
lineSetCallQualityOfService	The format of data in the provider-specific portion of the QOS structure is beyond the scope of TAPI and is not converted by TAPI.
lineSetCallTreatment	—
lineSetCurrentLocation	—
lineSetLineDevStatus	—
lineSetMediaControl	—
lineSetMediaMode	—
lineSetNumRings	—
lineSetStatusMessages	—
lineSetTerminal	—
lineShutdown	—
lineSwapHold	—
lineUncompleteCall	—
lineUnhold	—
phoneClose	—
phoneDevSpecific	The memory pointed to by lpParams is private between the application and service provider. The application must provide data in the form specified in the service provider extension definition.
phoneGetData	The memory pointed to by lpData is private between the application and service provider. The application must process data in the form specified in the service provider definition.
phoneGetDisplay	The memory pointed to by lpDisplay is private between the application and service provider. The application must process data in the form specified in the service provider definition.
phoneGetGain	—
phoneGetHookSwitch	—
phoneGetLamp	—
phoneGetMessage	—
phoneGetRing	—
phoneGetStatusMessages	—
phoneGetVolume	—
phoneNegotiateAPIVersion	—
phoneNegotiateExtVersion	—
phoneOpen	—
phoneSetData	The memory pointed to by lpParams is private between the application and service provider. The application must provide data in the form specified in the service provider definition.
phoneSetDisplay	The memory pointed to by lpDisplay is private between the application and service provider. The application must provide data in the form specified in the service provider definition.
phoneSetGain	—
phoneSetHookSwitch	—
phoneSetLamp	—
phoneSetRing	—
phoneSetStatusMessages	—
phoneSetVolume	—
phoneShutdown	—
tapiRequestDrop	This function is obsolete and unavailable to Microsoft® Win32® API applications.
tapiRequestMediaCall	This function is obsolete and unavailable to Microsoft Win32 applications.


Creating Help Files

Microsoft Windows help provides online help for users working with a Win32-based application. Windows help provides a practical way to present information about your application in a format users can access easily.

The Help Topics dialog box contains a Contents tab, and Index tab, and a Find tab. The Contents tab contains a hierarchical view of the information that the user can use to navigate the information. The view contains books, which can contain topics or other books. The Index tab contains keywords for one or more help files. The Find tab provides full-text search capability for any help file.


About Windows Help Files

Windows help files display information by using the following elements:

•	Text in multiple fonts, sizes, and colors.

•	Secondary windows to present information.

•	Cross-reference jumps for links to additional information.

•	Pop-up windows to present text and graphics.

•	Bitmaps and metafiles.

•	Segmented-graphics bitmaps with embedded hot spots.

•	Video (.AVI) files.

To create a help file, you need to create the following files: topic, graphics, help project, and contents. A topic file contains the text for the help topic and contains the help statements and macros that define the format of the text and the position of graphics in each topic. The graphics files contain the bitmaps and metafiles you want to display in the topics. The project file contains a description of how to build the help file. The contents file specifies the information in the Contents tab.

You use the Microsoft Help Workshop (HCW.EXE) to build the final help file. The compiler combines the topic, graphics, and project files to create a single help file (with the filename extension .HLP) that you can open and view by using Windows Help. For more information, see the Help Author’s Guide (HCW.HLP) included with the Help Workshop.


Creating Topic Files

A topic file contains help text, as well as the statements and macros that define the format of the text and the position of the graphics. Every topic file consists of one or more topics. A topic is any distinct unit of information, such as a contents screen, a conceptual description, a set of instructions, a keyboard table, a glossary definition, a list of jumps, a picture, and so on.

Windows Help displays only one topic at a time, but a user can view any topic in a help file by using a link to the topic or searching for keywords associated with the topic.

You create topic files directly by using a text editor and inserting help statements. You can create them indirectly by using a word processor that generates rich-text format (RTF) files. The help statements are an extended subset of the RTF statements, which provide a wide variety of formatting capabilities.

For complete syntax of the RTF commands, see the Help Author’s Guide (HCW.HLP) included with the Help Workshop.


Declaring Character Set, Fonts, and Colors

When you create a topic file, you must ensure that the entire contents of the file are enclosed in braces ({ }). The first statement in the file must be the \rtf statement; it immediately follows the first opening brace. You should follow the \rtf statement with an \ansi statement (or a similar statement) that specifies the character set used in the file. The following example shows the general form for a topic file:

{\rtf1\ansi
    .
    .
    .
}

You must declare the names of the fonts you use in the file by using a \fonttbl statement. The \fonttbl statement, enclosed in braces, contains a list of font and family names and specifies a unique number for each font. You use these numbers with \f statements later in the file to set specific fonts. The following \fonttbl statement assigns font numbers 0, 1, and 2 to the TrueType® fonts Times New Roman, Courier New, and Arial, respectively:

{\fonttbl
\f0\froman Times New Roman;
\f1\fdecor Courier New;
\f2\fswiss Arial;}

You should also use the \deff statement to set the default font for the file. Windows Help uses this default font if no other font is specified. The following example sets the default font number to zero, corresponding to the Times New Roman font specified in the previous \fonttbl statement:

\deff0

If you use specific text colors or choose not to rely on the default text colors set by Windows, you must define your colors by using a \colortbl statement. The \colortbl statement, enclosed in braces, defines each color by specifying the amount of each primary color (red, green, and blue) used in it. The statement implicitly numbers the colors consecutively starting from zero. You use these color numbers with \cf statements later in the file to set the color. The following example creates four colors (black, red, green, and blue):

{\colortbl
\red0\green0\blue0;
\red255\green0\blue0;
\red0\green128\blue0;
\red0\green0\blue255;}

Although it is not shown here, you can put a semicolon immediately after the \colortbl statement to define the default color as 0.


Defining Individual Topics

Each topic starts with one or more \footnote statements and ends with a \page statement. All text and graphics specified between these statements belong to the topic.

Every topic must have a context string. Windows Help uses the context string to locate the topic when the user requests to view it. You assign a context string to a topic by using the \footnote statement and the number sign (#) footnote character. Context strings can consist of letters, digits, and the underscore character (_). To prevent conflicts, each context string in a help file must be unique.

You can also assign a title to the topic by using the \footnote statement and the dollar sign ($) footnote character. Windows Help uses the title to identify the topic. You must provide a title if you assign keywords to the topic.

The following example defines a small topic having the context string “topic1” and the title “My Topic”:

#{\footnote topic1}
${\footnote My Topic}
This is my first topic.
\par
\page

In general, you use the \par statement to mark the end of each paragraph. In this example, the \par statement marks the end of the only paragraph in the topic.

You can add a macro to a topic by using the \footnote statement and the exclamation point (!) as the footnote character. For example, the following \footnote statement adds the CopyTopic macro to the topic:

!{\footnote CopyTopic()}

Windows Help executes the macro each time it displays the topic.


Setting Font Size and Name

You can set the font name and size by using the \f and \fs statements. The name is set by using a font number specified in the \fonttbl statement. The size of the font is specified in half-points. The following example sets the text to 10-point Times New Roman (if the \fonttbl statement matches the example in Declaring Character Set, Fonts, and Colors):

\f0\fs20

Once you set the font name and size, the settings apply to all subsequent text up to the next \plain statement or until you change the name or size by using the \f or \fs statement again. The \plain statement resets the name and font to the defaults. The default font name is as set by the \deff statement; the default font size is 12 points.


Setting Space Before and After Paragraphs

You can set the amount of space before and after each paragraph by using the \sb and \sa statements. These statements let you control the amount of space that appears between paragraphs. You specify the space in twips. (A twip is 1/1440 inch, or 1/20 of a printer’s point). The following example sets the space before a paragraph to 360 twips:

\sb360
This paragraph has 360 twips space immediately before it.
\par
This paragraph also has 360 twips before it.
\par

Once you set the space before or after a paragraph, the spacing applies to all subsequent paragraphs up to the next \pard statement or until you change the spacing by using the \sa and \sb statements again. The \pard statement restores the default spacing.


Setting the Left and Right Indents

When Windows Help displays its window, it automatically creates left and right margins and wraps text to fit within these margins. The margins are positioned slightly within the left and right edges of the window to prevent text in the topic from being clipped by the window.

You can override these margins by setting the left and right indents for a paragraph. The \li and \ri statements set an indent to a position relative to the corresponding left and right margins. For example, the following paragraph is indented 1 inch (1440 twips) from the left margin:

\li1440
This paragraph is indented 1 inch.
\par \pard
This paragraph is not indented.

Once indents are set, they apply to all subsequent paragraphs up to the next \pard statement. Note that the \pard statement must follow the \par statement that ends the paragraph to be indented.

You can set an indent for the first line in a paragraph by using the \fi statement. This allows you to create paragraphs with hanging indents. It is also useful for creating two-column lists.


Setting Tab Stops

You can set tab stops by using the \tx statement. You can use one or more \tx statements, each setting a specific position in twips relative to the left margin. Once you have set tab stops, you can use the \tab statement to align subsequent text with the next tab. The tab settings remain active until you use the \pard statement. The following example creates a two-column list by using a tab stop and paragraph indenting:

\fi-1440\li1440\tx1440
left
\tab
right
\par
left
\tab
right
\par
\pard


Breaking Lines

Ordinarily, Windows Help wraps all lines in a paragraph, fitting as many words on a line as will fit between the current left and right indents. You can force Windows Help to break a line at a given place by using the \line statement. You can control wrapping by using the \keep and \pard statements.

The following example uses the \keep statement to turn off word wrapping for three short lines and uses the \pard statement to restore the default properties:

\keep
3 pairs black socks\line
5 pairs blue socks\line
2 pairs brown socks\line
\par
\pard

The following example uses the \keep and \pard statements to create three nonwrapping paragraphs:

\keep
3 pairs black socks
\par
5 pairs blue socks
\par
2 pairs brown socks
\par
\pard


Creating Links and Pop-up Topics

Windows Help displays only one topic at a time. To enable users to view other topics, you must create hot spots that link your topics to other topics. You create a hot spot by using the \strike, \ul, or \uldb statement and a corresponding \v statement. When you create a link, you provide the text for the hot spot and the context string for the topic that is to be jumped to or displayed. The following example creates a hot spot named Glossary and establishes a link from the hot spot to the topic having the context string “glo1”:

You can find a list of terms used in this
help file in the {\uldb Glossary}{\v glo1}.

When Windows Help displays the topic with this hot spot, it places a line under the word Glossary and colors the word green. The context string is not shown, but if the user clicks on the hot spot, Windows Help jumps to and displays the corresponding topic.

The \strike and \uldb statements are used to create jumps to other topics. The \ul statement creates a link to a pop-up topic. Windows Help displays pop-up topics in a pop-up window and leaves the current topic in the main window.

You can also associate a help macro with a hot spot in a topic. For example, the following \uldb and \v statements create a hot spot for the ExecProgram macro:

{\uldb Clock}{\v !ExecProgram("clock.exe", 1)}

Windows Help executes the macro whenever the user chooses the hot spot. Windows Help continues displaying the topic while it executes the macro, unless the macro causes a jump to another topic.


Creating a Keyword List

You can also enable users to find and view topics by assigning keywords to the topics. You assign a keyword by using the \footnote statement and the letter K as the footnote character. Windows Help collects all keywords in a help file and displays them in its Index tab. Using this tab, a user can select a keyword and view the help topics associated with it. The following example assigns the keyword “Sample Topics” to the current topic:

#{\footnote topic1}
${\footnote My Topic}
K{\footnote Sample Topics}
This is my first topic.
\par
\page

If a keyword begins with the letter K, you must place an extra space before the word. Multiple keywords for a topic are separated by semicolons.

A keyword can be assigned to any number of topics. When the user selects the keyword in the Index tab, Windows Help displays all topics associated with the keyword. The user then picks the one to view.

You can also create alternative keywords for a help file for use with the WinHelp function.


Creating Browse Sequences

You can enable users to browse through a sequence of help topics by creating a browse sequence and adding browse buttons to your help file. A browse sequence typically consists of two or more related topics that are intended to be read sequentially. You create a browse sequence by using the \footnote statement and the plus-sign (+) footnote character to assign a sequence identifier. The following example assigns a sequence identifier to the topic titled “A Topic”:

#{\footnote topic5}
${\footnote A Topic}
+{\footnote shorttopics}
This is one topic in a browse sequence.
\par
\page

Windows Help adds topics with sequence identifiers to the browse sequence and determines the order of topics in the sequence by sorting the identifiers alphabetically. If two topics have the same identifier, Windows Help assumes that the topic that was compiled first is to be displayed first.

Windows Help uses the sequence only if the browse buttons have been enabled. You can enable the buttons by placing the following statements in the help project file:

[CONFIG]
BrowseButtons()

For more information about the project file, see Creating Help Project Files.

You can create more than one browse sequence in a help file by using sequence numbers with sequence identifiers. The sequence number consists of a colon (:) followed by an integer. Windows Help combines all topics having the same sequence identifier (but different sequence numbers) into a single browse sequence and determines the order of the topics by sorting them alphabetically. To ensure that numerals are sorted correctly, they should have the same number of digits. For example, the numerals 1 through 10 should be 01 through 10.

#{\footnote topic10}
${\footnote Alpha Topic #3}
+{\footnote alpha:3}
This topic is part of the alpha browse sequence.
\par
\page


Embedding Graphics

You can add bitmaps and metafiles to your help files by using the bml, bmc, and bmr statements. These statements take the name of a graphics file and insert the corresponding bitmap or metafile into the help file at the specified position.

Windows Help requires graphics files to be in one of the following formats:

•	Windows bitmap (.BMP)

•	Windows metafile (.WMF)

•	Multiple-resolution bitmap (.MRB)

•	Segmented-graphics bitmap (.SHG)

Multiple-resolution bitmaps can be created by using the Microsoft Multiple-Resolution Bitmap Compiler (MRBC). Segmented-graphics bitmaps can be created by using Microsoft Windows Hotspot Editor.

Although the \pict statement can also be used to add bitmaps and metafiles to a help file, the bitmap or metafile data must be inserted into the topic file rather than specified as a separate file.


Inserting a Bitmap in Text

You can insert a bitmap into a paragraph as if it were a character by using the bmc statement. The statement aligns the bottom of the bitmap with the base line of the current line of text and places the left edge of the bitmap at the next character position. The following example inserts a bitmap into a line of text:

Press the \{bmc enter.bmp\} key to complete the task and return to
the main window.

Because the bitmap is treated as text, any paragraph properties assigned to the paragraph also apply to the bitmap. Windows Help places text following the bitmap on the same base line at the next available character position.

In general, bitmaps inserted as characters should be clipped to the smallest possible size. Any extra white space at the top or bottom of the bitmap image affects the alignment of the bitmap with the text and may affect the spacing between lines.

You must not specify negative line spacing for paragraphs that contain bmc statements. Doing so might cause the bitmap to appear on top of the paragraph.


Wrapping Text Around a Bitmap

You can place a bitmap at the left or right margin of the Help window and have subsequent text wrap around the bitmap by using the bml or bmr statement. The bml statement inserts a bitmap at the left margin; bmr inserts it at the right.

If you want text to wrap around a bitmap, you must place the bml or bmr statement at the beginning of a paragraph. Windows Help aligns the start of the paragraph with the top of the bitmap and wraps around the left or right edge of the bitmap. The following example places the bitmap at the left margin and subsequent text wraps around its right edge:

\{bml mybitmap.bmp\}
The text in this paragraph wraps around
the right edge of the bitmap.
\par

If you place a bml or bmr statement at the end of a paragraph, Windows Help places the bitmap under the paragraph instead of wrapping the text around the bitmap. If you do not want text to wrap around a bitmap, place \par statements immediately before and after the bml or bmr statement.


Using a Bitmap as a Hot Spot

You can use bitmaps as hot spots. This enables you to create graphics, such as icons or buttons, and use them as “jumps” to particular topics or as hot spots for macros. The following example uses the bitmap in the MYBUTTON.BMP file to create a link. When the user clicks the bitmap, Windows Help jumps to the topic identified by the context string “topic15”:

{\strike \{bml mybutton.bmp\}}{\v topic15}

You can also divide a single bitmap into several hot spots and assign a different link or macro to each hot spot. Such bitmaps, called segmented-graphics bitmaps, are created by using Hotspot Editor. For example, if you have a bitmap of a dialog box, you can assign links to each of the control windows in the dialog box, enabling the user to click a control window and view information about it. Segmented-graphics bitmaps already contain the context strings needed for the links; only a bml or bmr statement is needed to insert the bitmap. The \strike and \v statements must not be used.

\{bml mydialog.shg\}


Using a Bitmap on Different Displays

A multiple-resolution bitmap is a single bitmap file that contains one or more bitmaps that have been marked for use with specific displays, such as the CGA, EGA, VGA, or 8514 displays. You use multiple-resolution bitmaps to avoid problems associated with displaying bitmaps designed for a single type of display. Single-resolution bitmaps can have the following problems:

•	Appear too big or too small on displays having different resolutions

•	Appear stretched or compressed on displays with different aspect ratios

•	Lack colors or use unintended colors on displays with different color capabilities

You create multiple-resolution bitmaps by using MRBC. The compiler, an MS-DOS program, has the following command-line syntax:

mrbc [/s] filename

The filename parameter specifies the name of a Windows bitmap file. Typically, you specify several filenames, one for each type of display. Wildcards can be used. The compiler uses the filename of the first bitmap file as the name of the output file but gives the output file the filename extension .MRB. The following example combines the bitmap files MYBUTTON.EGA, MYBUTTON.VGA, and MYBUTTON.854 into the multiple-resolution bitmap file MYBUTTON.MRB:

mrbc mybutton.ega mybutton.vga mybutton.854

In this example, the compiler checks the biXPelsPerMeter and biYPelsPerMeter members of the BITMAPINFOHEADER structure in each bitmap file to determine the display type for the bitmap. If these members are set to zero, the compiler prompts for the display type with a message such as the following:

Please enter the monitor type for the bitmap mybutton.ega:

You must enter at least the first character of one of the following display-type names: CGA, EGA, VGA, or 8514. The compiler sets the display type you specify, but it does not check that the type is valid. For example, if you specify VGA for an EGA bitmap, the compiler marks it as a VGA bitmap. The result may be undesirable.

The /s option, specifying silent mode, speeds up compilation if the names of the bitmap files conform to the MRBC filename convention. If you use the /s option, the compiler uses the first character of the filename extension to determine the display type for the bitmap, as described in the following list:

Letter	Meaning
C	CGA bitmap
E	EGA bitmap
V	VGA bitmap
8	8514 bitmap
If the filename extension starts with any other character, MRBC assumes a VGA bitmap. The following example creates the multiple-resolution bitmap file MYBUTTON.MRB, containing bitmaps for EGA, VGA, and 8514 displays:

mrbc /s mybutton.ega mybutton.vga mybutton.854

The compiler never writes over existing multiple-resolution bitmap files. If the output file already exists, the compiler displays an error message.

You insert multiple-resolution bitmaps into your help file by using the same statements as for Windows bitmaps. For example, the following bmc statement inserts the bitmaps from the MYBUTTON.MRB file:

Click the \{bmc mybutton.mrb\} button to complete the task and
return to the main window.

Before displaying a multiple-resolution bitmap, Windows Help checks the display type for the computer and then selects the bitmap that has the closest matching resolution, aspect ratio, and color capabilities. Windows Help never displays more than one bitmap from a multiple-resolution bitmap file.


Creating Help Project Files

This section describes the format and contents of the help project file (.HPJ) used to build the help file. The project file contains all the information the Microsoft Help Workshop needs to combine topic files and other elements into a help file.

The project file is a text file divided into sections. A number of these sections should be managed through the Help Workshop, rather than through a text file as shown here. For more information, see the Help Author’s Guide (HCW.HLP) included with the Help Workshop.


Project File Sections

Every project file consists of one or more sections. Each section has a section name, enclosed in brackets ([]), that defines the purpose and format of statements and options in the section. Following are the sections used in project files:

Section	Description
[ALIAS]	Assigns one or more context strings to the same topic.
[BAGGAGE]	Lists files that are to be placed within the help file (which contains its own file system).
[BITMAPS]	Specifies bitmap files. This section is not required if the project file lists a path for bitmap files by using the BMROOT or ROOT option.
[BUILDTAGS]	Specifies valid build tags.
[CONFIG]	Specifies help macros that define nonstandard menus and buttons used in the help file. This section is required if the help file uses any of these features.
[CONFIG:x]	Contains one or more macros that Windows Help runs when opening the corresponding window, x.
[FILES]	Specifies topic files to be included in the build. This section is required.
[MAP]	Associates topic identifiers with context numbers.
[MACROS]	Associates macros with keywords.
[OPTIONS]	Specifies options that control the build process. If this section is used, it should be the first section listed in the project file, so that the options will apply during the entire build process.
[WINDOWS	Defines the characteristics of the primary Help window and the secondary-window types used in the help file. This section is required if the help file uses secondary windows.
Every project file requires a [FILES] section. This section names the topic files. Most project files also have an [OPTIONS] section that specifies how to build the help file. A very useful option in the [OPTIONS] section is the COMPRESS option, which specifies whether the help file should be compressed or uncompressed. Compressing a help file reduces its size considerably and saves valuable disk space. For more information, see the Help Author’s Guide (HCW.HLP) included with the Help Workshop.

The following example creates a compressed help file from two topic files, MAIN.RTF and MENUS.RTF:

[OPTIONS]
COMPRESS=TRUE

[FILES]
MAIN.RTF
MENUS.RTF


Using Macros in Project Files

You can add macros to the [MACROS] section of a project file. These macros are run whenever a user selects the specified keyword in the index.

You can create new menu items and buttons for Windows Help by using such macros as CreateButton and InsertMenu. These macros define other help macros and associate them with the menu items and buttons. Windows Help executes these macros when the user chooses a corresponding menu item or button. Macros that create help buttons, menus, or menu items remain in effect until the user quits Windows Help or opens a new help file.

You can extend the capabilities of Windows Help by developing your own dynamic-link libraries (DLLs) and defining help macros that call functions in the libraries. To define help macros that call DLL functions, you must register each function and its corresponding library by using the RegisterRoutine macro in the [CONFIG] section of the project file.


Sample Project File

The following example is a sample project file for the Cardfile application. Comments, marked by a beginning semicolon (;), indicate the purpose of each section in the file:

; Options used to define the Help title bar and icon
[OPTIONS]
ROOT=C:\HELP
BMROOT=C:\HELP\ART
CONTENTS=cont_idx_card
TITLE=Cardfile Help
ICON=CARDHLP.ICO
COMPRESS=OFF
WARNING=3
REPORT=ON
ERRORLOG=CARD.BUG

; Files used to build Cardfile Help
[FILES]
RTFTXT\COMMANDS.RTF
RTFTXT\HOWTO.RTF
RTFTXT\KEYS.RTF
RTFTXT\GLOSSARY.RTF

; Button macros and Using help file
[CONFIG]
CreateButton("btn_up", "&Up", "JumpContents('HOME.HLP')")
BrowseButtons()
SetHelpOnFile("APPHELP.HLP")

; Secondary-window characteristics
[WINDOWS]
picture = "Samples", (123,123,256,256), 0, (0,255,255), (255,0,0)


Windows Help Statements and Macros

This section describes the syntax and purpose of statements and macros used in topic and project files. The help statements define the format and placement of text and graphics in the help file. The help macros define actions to take while the help file is being viewed, such as creating custom buttons and carrying out menu commands.


Help Statement Syntax

Help statements are an extended subset of tokens defined by the rich-text-format (RTF) standard. The statements specify character and paragraph properties, such as font, color, spacing, and alignment for text in the help file.

Help statements are contained in topic files, which are specified in the [FILES] section of a project file. A topic file consists of statements, groups, and unformatted text. Each statement consists of a backslash (\) followed by a statement name. For example, the following line demonstrates usage of the \tab statement:

left column\tab right column

Statements must be separated from subsequent text or statement parameters by a delimiter. A delimiter can be one of the following:

•	A space.

•	A digit or minus sign, which indicates that a numeric parameter follows. The subsequent digit sequence is then delimited by a space or character other than a letter or digit.

•	Any character other than a letter or digit.

When a space is used as a delimiter, the compiler discards it. If any other character is used, the compiler processes it as text or the start of another statement. For example, if a backslash is used as a delimiter, the compiler interprets it as the beginning of the next statement.

A group consists of help statements and text enclosed in braces ({}). Formatting specified within a group affects only the text within that group. Text within a group inherits any formatting of the text preceding the group.

Unformatted text consists of any combination of 7-bit ASCII characters. Although characters whose values are greater than 127 are not permitted in topic files, the \' statement can be used to insert them in the final help file. The compiler treats spaces as part of the text, but it discards carriage return and linefeed characters.

Although the compiler supports many RTF tokens, it does not support them all. The compiler ignores any RTF statement that is not explicitly defined in the Help Author’s Guide (HCW.HLP). Furthermore, the compiler may interpret an RTF token differently than it is specified by the standard. For example, the standard specifies that the \uldb statement indicates a double underline, but the compiler uses this statement to indicate a hot spot.


Help Macro Syntax

Help macros specify actions that Windows Help takes when it loads help or displays a topic. A macro consists of a macro name and parameters enclosed in parentheses.

Macro names specify the action to take, such as creating buttons or inserting menu items. The names are not sensitive to case, so any combination of uppercase and lowercase letters may be used.

Macro parameters specify the files, buttons, menus, or topics on which to carry out the action. The parameters must be enclosed in parentheses and separated by spaces. Parameters in many macros must also be enclosed in quotation marks. This is especially true if the parameter contains space characters. The valid quotation characters are the matching double quotation marks (" ") and the opening and closing single quotation marks (' '). If a quotation character is needed as part of a parameter rather than to enclose a parameter, the parameter should be enclosed in single quotation marks. When you use single quotation marks in this case, you can omit the backslash escape character for the double quotation marks, as shown in the following:

'command "string as parameter"'

Macros can be used as parameters in other macros. In most cases, embedded macros must be enclosed in quotation marks. If the embedded macro also has quoted parameters, the quotation character that is used must be different than the quotation characters enclosing the macro. The following example shows the correct way to use nested quotation marks:

CreateButton("time_btn", "&Time", "ExecProgram('clock', 0)")

Help macros can be combined into macro strings by separating the macros with semicolons (;). The compiler processes the macro string as a unit and executes the individual macros sequentially.


Using Help in a Windows Application

Win32-based applications can offer help to their users by using the WinHelp function to start Windows Help and display topics in the application’s help file. The WinHelp function gives a Win32-based application complete access to the help file, as well as to the menus and commands of Windows Help. Many applications use WinHelp to implement context-sensitive help. Context-sensitive help enables users to view topics about specific windows, menus, menu items, and control windows by selecting the item with the keyboard or the mouse. For example, a user can learn about the Open command on the File menu by selecting the command (using the direction keys) and pressing the F1 key.


Choosing Help from the Help Menu

Every application should provide a Help menu to allow the user to open the help file with either the keyboard or the mouse. The Help menu should contain at least one Contents menu item that, when chosen, displays the Contents tab or the main topic in the help file. To support the Help menu, the application’s main window procedure should check for the Contents menu item and call the WinHelp function, as in the following example:

case WM_COMMAND:
    switch (wParam) {
    case IDM_HELP_CONTENTS:
        WinHelp(hwnd, "myhelp.hlp", HELP_CONTENTS, 0L);
        return 0L;
        .
        .
        .

    }
    break;

You can add other menu items to the Help menu for topics containing general information about the application. For example, if your help file contains a topic that describes how to use the keyboard, you can place a Keyboard menu item on the Help menu. To support additional menu items, your application must specify either the context string or the context identifier for the corresponding topic when it calls the WinHelp function. The following example uses a macro to specify the context string IDM_HELP_KEYBOARD for the Keyboard topic:

case IDM_HELP_KEYBOARD:
    WinHelp(hwnd, "myhelp.hlp", HELP_COMMAND,
            (LPSTR)"JumpID(\"myhelp.hlp\",\"IDM_HELP_KEYBOARD\")");
    return 0L;

A better way to display a topic is to use a context identifier. To do this, the help file must assign a unique number to the corresponding context string, in the [MAP] section of the project file. For example, the following section assigns the number 101 to the context string IDM_HELP_KEYBOARD:

[MAP]
IDM_HELP_KEYBOARD   101

An application can display the Keyboard topic by specifying the context identifier in the call to the WinHelp function, as in the following example:

#define IDM_HELP_KEYBOARD 101

WinHelp(hwnd, "myhelp.hlp", HELP_CONTEXT, (DWORD)IDM_HELP_KEYBOARD);

To make maintenance of an application easier, most programmers place their defined constants (such as IDM_HELP_KEYBOARD in the previous example) in a single header file. As long as the names of the defined constants in the header file are identical to the context strings in the help file, you can include the header file in the [MAP] section to assign context identifiers, as shown in the following example:

[MAP]
#include <myhelp.h>

If a help file contains two or more Contents topics, the application can assign one as the default by using the context identifier and the HELP_SETCONTENTS value in a call to the WinHelp function.


Choosing Help with the Keyboard

An application can enable the user to choose a help topic with the keyboard by intercepting the F1 key. Intercepting this key lets the user select a menu, menu item, dialog box, message box, or control window and view help for it with a single keystroke.

To intercept the F1 key, the application must install a message-filter procedure by using the SetWindowsHook function. This allows the application to examine all keystrokes for the application, regardless of which window has the input focus. If the filter procedure detects the F1 key, it posts a WM_F1DOWN message (application-defined) to the application's main window procedure. The procedure then determines which help topic to display.

The filter procedure should have the following form:

int CALLBACK FilterFunc(nCode, wParam, lParam)
int nCode;
WORD wParam;
DWORD lParam;
{
    LPMSG lpmsg = (LPMSG)lParam;

    if ((nCode == MSGF_DIALOGBOX || nCode == MSGF_MENU) &&
            lpmsg->message == WM_KEYDOWN && lpmsg->wParam == VK_F1) {
        PostMessage(hWnd, WM_F1DOWN, nCode, 0L);
    }

    DefHookProc(nCode, wParam, lParam, &lpFilterFunc);

    return 0;
}

The application should install the filter procedure after creating the main window, as shown in the following example:

lpProcInstance = MakeProcInstance(FilterFunc, hInstance);
if (lpProcInstance == NULL)
    return FALSE;

lpFilterFunc = SetWindowsHook(WH_MSGFILTER, lpProcInstance);

The filter procedure sends a WM_F1DOWN message only when the F1 key is pressed in a dialog box, message box, or menu. Many applications also display the Contents topic if no menu, dialog box, or message box is selected when the user presses the F1 key. In this case, the application should define the F1 key as an accelerator key that starts Windows Help.

To create an accelerator key, the application’s resource-definition file must define an accelerator table, as follows:

1 ACCELERATORS
BEGIN
    VK_F1, IDM_HELP_CONTENTS, VIRTKEY
END

To support the accelerator key, the application must load the accelerator table by using the LoadAccelerators function and translate the accelerator keys in the main message loop by using the TranslateAccelerator function.

In addition to installing the filter procedure, the application must keep track of which menu, menu item, dialog box, or message box is currently selected. In other words, when the user selects an item, the application must set a global variable indicating the current context. For dialog and message boxes, the application should set the global variable immediately before calling the DialogBox or MessageBox function. For menus and menu items, the application should set the variable whenever it receives a WM_MENUSELECT message. As long as identifiers for all menu items and controls in an application are unique, an application can use code similar to the following example to monitor menu selections:

case WM_MENUSELECT:
    /*
     * Set dwCurrentHelpId to the help ID of the menu item that is
     * currently selected.
     */

    if (HIWORD(lParam) == 0)             /* no menu selected    */
        dwCurrentHelpId = ID_NONE;

    else if (lParam & MF_POPUP) {        /* pop-up selected     */
        if ((HMENU)wParam == hMenuFile)
            dwCurrentHelpId = ID_FILE;
        else if ((HMENU)wParam == hMenuEdit)
            dwCurrentHelpId = ID_EDIT;
        else if ((HMENU)wParam == hMenuHelp)
            dwCurrentHelpId = ID_HELP;
        else
            dwCurrentHelpId = ID_SYSTEM;
    }

    else                                 /* menu item selected */
        dwCurrentHelpId = wParam;

    break;

In this example, the hMenuFile, hMenuEdit, and hMenuHelp parameters must previously have been set to specify the corresponding menu handles. An application can use the GetMenu and GetSubMenu functions to retrieve these handles.

When the main window procedure finally receives a WM_F1DOWN message, it should use the current value of the global variable to display a help topic. The application can also provide help for individual controls in a dialog box by determining which control has the focus at this point, as shown in the following example:

case WM_F1DOWN:
    /*
     * If there is a current help context, display it.
     */

    if (dwCurrentHelpId != ID_NONE) {
        DWORD dwHelp = dwCurrentHelpId;

        /*
         * Check for context-sensitive help for individual dialog
         * box controls.
         */

        if (wParam == MSGF_DIALOGBOX) {
            WORD wID = GetWindowWord(GetFocus(), GWW_ID);
            if (wID != IDOK && wID != IDCANCEL)
                dwHelp = (DWORD) wID;
        }

        WinHelp(hWnd, szHelpFileName, HELP_CONTEXT, dwHelp);

        /*
         * This call is used to remove the highlighting from the
         * System menu, if necessary.
         */

        DrawMenuBar(hWnd);
    }

    break;

When the application ends, it must remove the filter procedure by using the UnhookWindowsHook function and free the procedure instance for the function by using the FreeProcInstance function.


Choosing Help with the Mouse

An application can enable the user to choose a help topic with the mouse by intercepting mouse input messages and calling the WinHelp function. To distinguish requests to view help from regular mouse input, the user must press the SHIFT+F1 key combination. In such cases, the application sets a global variable when the user presses the key combination and changes the cursor shape to a question-mark pointer to indicate that the mouse can be used to choose a help topic.

To detect the SHIFT+F1 key combination, an application checks for the VK_F1 virtual-key value in each WM_KEYDOWN message sent to its main window procedure. It also checks for the VK_ESCAPE virtual-key code. The user presses the ESC key to quit Windows Help and restore the mouse to its regular function. The following example checks for these keys:

case WM_KEYDOWN:
    if (wParam == VK_F1) {

        /* If Shift-F1, turn help mode on and set help cursor. */

        if (GetKeyState(VK_SHIFT)) {
            bHelp = TRUE;
            SetCursor(hHelpCursor);
            return DefWindowProc(hwnd, message, wParam, lParam);
        }

        /* If F1 without shift, call help main index topic. */

        else {
            WinHelp(hwnd,"myhelp.hlp",HELP_CONTENTS,0L);
        }
    }

    else if (wParam == VK_ESCAPE && bHelp) {

        /* Escape during help mode: turn help mode off. */

        bHelp = FALSE;
        SetCursor((HCURSOR) GetClassWord(hWnd, GCW_HCURSOR));
    }

    break;

Until the user clicks the mouse or presses the ESC key, the application responds to WM_SETCURSOR messages by resetting the cursor to the arrow and question-mark combination.

case WM_SETCURSOR:
    /*
     * In help mode, it is necessary to reset the cursor in response
     * to every WM_SETCURSOR message. Otherwise, by default, Windows
     * will reset the cursor to that of the window class.
     */

    if (bHelp) {
        SetCursor(hHelpCursor);
        break;
    }

    return (DefWindowProc(hwnd, message, wParam, lParam));

case WM_INITMENU:
    if (bHelp) {
        SetCursor(hHelpCursor);
    }

    return (TRUE);

If the user clicks the mouse button in a nonclient area of the application window while in help mode, the application receives a WM_NCLBUTTONDOWN message. By examining the wParam value of this message, the application can determine which context identifier to pass to WinHelp.

case WM_NCLBUTTONDOWN:
    /*
     * If in help mode (Shift+F1), display context-sensitive
     * help for nonclient area.
     */

    if (bHelp) {
        dwHelpContextId =
            (wParam == HTCAPTION) ?(DWORD) HELPID_TITLE_BAR:
            (wParam == HTSIZE) ? (DWORD) HELPID_SIZE_BOX:
            (wParam == HTREDUCE) ? (DWORD) HELPID_MINIMIZE_ICON:
            (wParam == HTZOOM) ? (DWORD) HELPID_MAXIMIZE_ICON:
            (wParam == HTSYSMENU) ?(DWORD) HELPID_SYSTEM_MENU:
            (wParam == HTBOTTOM) ? (DWORD) HELPID_SIZING_BORDER:
            (wParam == HTBOTTOMLEFT) ? (DWORD) HELPID_SIZING_BORDER:
            (wParam == HTBOTTOMRIGHT) ?(DWORD) HELPID_SIZING_BORDER:
            (wParam == HTTOP) ?(DWORD) HELPID_SIZING_BORDER:
            (wParam == HTLEFT) ?(DWORD) HELPID_SIZING_BORDER:
            (wParam == HTRIGHT) ?(DWORD) HELPID_SIZING_BORDER:
            (wParam == HTTOPLEFT) ?(DWORD) HELPID_SIZING_BORDER:
            (wParam == HTTOPRIGHT) ? (DWORD) HELPID_SIZING_BORDER:
            (DWORD) 0L;

        if (!((BOOL) dwHelpContextId))
            return DefWindowProc(hwnd, message, wParam, lParam);
        bHelp = FALSE;
        WinHelp(hWnd, szHelpFileName, HELP_CONTEXT, dwHelpContextId);
        break;
    }

    return (DefWindowProc(hWnd, message, wParam, lParam));

If the user clicks a menu item while in help mode, the application intercepts the WM_COMMAND message and sends the help request:

case WM_COMMAND:

    /* In help mode (Shift-F1)? */

    if (bHelp) {
        bHelp = FALSE;
        WinHelp(hWnd, szHelpFileName, HELP_CONTEXT, (DWORD)wParam);
        return NULL;
    }


Searching for Help with Keywords

An application can enable the user to search for topics based on full or partial keywords. The following example searches for the keyword “Keyboard” and displays the corresponding topic, if found:

WinHelp(hwnd, "myhelp.hlp", HELP_KEY, "Keyboard");

If the topic is not found, Windows Help displays the Index tab. If more than one topic has the same keyword, Windows Help displays the list of topics in the Topics Found dialog.

An application can give the user more options in a search by specifying partial keywords. When a partial keyword is given, Windows Help usually displays the Index tab to allow the user to continue the search or return to the application. However, if there is an exact match and no other topic exists with the given keyword, Windows Help displays the topic. The following example opens the Find tab and selects the first keyword in the list starting with the letters Ke:

WinHelp(hwnd, "myhelp.hlp", HELP_PARTIALKEY, "Ke");

When the HELP_KEY and HELP_PARTIALKEY values are specified in the WinHelp function, Windows Help searches the K keyword table. This table contains keywords generated by using the letter K with \footnote statements in the topic file. An application can search alternative keyword tables by specifying the HELP_MULTIKEY value in the WinHelp function. In this case, the application must specify the footnote character and the full keyword in a MULTIKEYHELP structure, as follows:

HGLOBAL hglblmkh;
MULTIKEYHELP FAR* mkh;
PSTR pszKeyword = "Frame";
UINT cb;

cb = sizeof(MULTIKEYHELP) + lstrlen(pszKeyword);

hglblmkh = GlobalAlloc(GHND, (DWORD) cb);
if (hglblmkh == NULL)
    break;
mkh = (MULTIKEYHELP FAR*) GlobalLock(hglblmkh);

mkh->mkSize    = cb;
mkh->mkKeylist = 'L';
lstrcpy(mkh->szKeyphrase, pszKeyword);

WinHelp(hwnd, "myhelp.hlp", HELP_MULTIKEY, (DWORD) mkh);

GlobalUnlock(hglblmkh);
GlobalFree(hglblmkh);

If the keyword is not found, Windows Help displays an error message. If more than one topic has the keyword, Windows Help displays only the first topic.

Applications cannot use alternative keyword tables unless the MULTIKEY option is specified in the [OPTIONS] section of the project file.


Displaying Help in a Secondary Window

An application can display topics in secondary windows instead of in the Windows Help main window. Secondary windows are useful whenever the user does not need the full capabilities of Windows Help.

To display help in a secondary window, the application specifies the name of the secondary window along with the name of the help file. The following example displays the topic having the context identifier IDM_FILE_SAVE in the secondary window named “wnd_menu”:

WinHelp(hwnd, "myhelp.hlp>wnd_menu", HELP_CONTEXT, IDM_FILE_SAVE);

The name and characteristics of the secondary window must be defined in the [WINDOWS] section of the project file, as in the following example:

[WINDOWS]
wnd_menu = "Menus", (128, 128, 256, 256), 0

Windows Help displays the secondary window with the initial size and position specified in the [WINDOWS] section. However, an application can set a new size and position by specifying the HELP_SETWINPOS value in the WinHelp function. In this case, the application sets the members in a HELPWININFO structure to specify the window size and position. The following examples sets the secondary window wnd_menu to a new size and position:

HANDLE hhwi;
LPHELPWININFO lphwi;
WORD wSize;
char *szWndName = "wnd_menu";

wSize = sizeof(HELPWININFO) + lstrlen(szWndName);
hhwi = GlobalAlloc(GHND, wSize);
lphwi = (LPHELPWININFO)GlobalLock(hhwi);

lphwi->wStructSize = wSize;
lphwi->x           = 256;
lphwi->y           = 256;
lphwi->dx          = 767;
lphwi->dy          = 512;
lphwi->wMax        = 0;
lstrcpy(lphwi->rgchMember, szWndName);

WinHelp(hwnd, "myhelp.hlp", HELP_SETWINPOS, lphwi);

GlobalUnlock(hhwi);
GlobalFree(hhwi);


Canceling Help

Windows Help requires an application to explicitly cancel help so that Windows Help can free any resources it used to keep track of the application and its help files. The application can do this at any time.

An application cancels Windows Help by calling the WinHelp function and specifying the HELP_QUIT value, as shown in the following example:

WinHelp(hwnd, "myhelp.hlp", HELP_QUIT, NULL);

If the application has made any calls to the WinHelp function, it must cancel help before it closes its main window (for example, in response to the WM_DESTROY message in the main window procedure). An application needs to call WinHelp only once to cancel help, no matter how many help files it has opened. Windows Help remains running until all applications or dynamic-link libraries that have called the WinHelp function have canceled help.


Installable Drivers

This appendix describes the general format of installable drivers and defines the installable driver functions that applications and DLLs use to open and manage installable drivers.


About Installable Drivers

An installable driver is a Microsoft Windows dynamic-link library (DLL) that provides a standard interface through which Windows-based applications and DLLs communicate with and manage the driver. Installable drivers are used most commonly for as multimedia device drivers, but installable drivers can also be used for other purposes and are particularly useful in situations that require a standard interface and control of multiple instances.


Installable Driver Format

Every installable driver exports a DriverProc function. This common entry-point function receives driver messages from the system that direct the driver to carry out actions or provide information. The system sends driver messages to the DriverProc function when an application or DLL opens or closes the driver or requests that a message be sent to the driver. The DriverProc function either processes the message or passes the message to the default message handler, the DefDriverProc function. In either case, DriverProc must return a value indicating whether the requested action was successful.


Driver Messages

Each driver message consists of a message identifier and two 32-bit parameters. The message identifier is a unique value that the DriverProc function checks to determine which action to carry out. The meaning of the message parameters depends on the message. The parameters may represent values or addresses. In many cases, the parameters are not used and are set to zero.

Driver messages can be standard or custom. Windows sends standard driver messages, such as DRV_OPEN, DRV_CLOSE, and DRV_CONFIGURE, to an installable driver in response to a request to open, close, or configure the driver. The standard messages direct the installable driver to load or unload its resources, enable or disable its operation, open or close a driver instance, and display a configuration dialog box. Some standard messages, such as DRV_POWER and DRV_EXITSESSION, notify the driver of system-wide events that affect the operation of the driver or any related hardware.

Applications and DLLs send custom driver messages to direct an installable driver to carry out driver-specific actions. Installable drivers that support custom messages must include appropriate processing in the DriverProc function. To prevent conflict between custom and standard driver messages, custom message identifiers must have values ranging from DRV_RESERVED to DRV_USER. Custom messages passed to the DefDriverProc function are ignored.


Driver Instances

Windows allows for multiples instances of an installable driver. The system creates an instance of the driver each time the driver is opened and destroys the instance when the driver is closed. Driver instances are especially useful for installable drivers that support multiple devices or that are opened by multiple applications or by the same application multiple times.

To help the driver keep track of the instances, the system sends a driver instance handle with each driver message after the instance has been created. Because this handle uniquely identifies the instance, installable drivers often associate the handle with memory and other resources that they have specifically allocated for the instance.

When the first instance is opened, the system sends the DRV_LOAD, DRV_ENABLE, and DRV_OPEN messages to the driver in that order. The DRV_LOAD and DRV_ENABLE messages notify the driver that it is now in memory and is enabled for operation. The DRV_OPEN message identifies the instance handle and may include configuration information for the instance. On each subsequent opening of an instance of the same driver, the system sends only a DRV_OPEN message.

When processing a DRV_LOAD message, a driver typically reads configuration settings from the registry, configures the driver and any associated hardware, and allocates memory for use by all instances of the driver. If a driver cannot complete the configuration or allocate memory, it returns zero to direct the system to immediately remove the driver from memory and prevent any subsequent messages from being sent. When processing the DRV_ENABLE message, the driver prepares the hardware to receive and process input and output (I/O) requests. The preparation may include installing interrupt handlers.

When processing the DRV_OPEN message, the driver allocates memory or resources required by the given instance of the driver and then returns a nonzero value. The system uses this nonzero value as the driver identifier in subsequent driver messages for the instance. The driver can use this identifier for any purpose. For example, some drivers use a memory handle for the identifier to gain quick access to memory containing information about the given instance.

Many installable drivers process the second parameter of the DRV_OPEN message, giving the system and applications the means to send additional information to the driver when opening an instance. The parameter can be a single value or an address of a structure containing a set of values. When processing DRV_OPEN, the driver checks the parameter to determine whether it is a value and uses the given values, if any, to complete the creation of the instance.

The system sends a DRV_CLOSE message each time an instance is closed. The instance handle sent with the message identifies which instance to close. When the last remaining instance is closed, the system sends the DRV_CLOSE, DRV_DISABLE, and DRV_FREE messages in that order. The DRV_CLOSE message directs the driver to close the instance, and the DRV_DISABLE and DRV_FREE messages notify the driver that it is now disabled and will be immediately freed from memory.

When processing the DRV_CLOSE message, the driver typically frees any memory or resources allocated for the instance. When processing the DRV_DISABLE message, the driver places any hardware in an inactive state, which may include the removal of interrupt handlers. When processing the DRV_FREE message, the driver frees any memory or resources that are still allocated.

Installable drivers are not required to support multiple instances. A driver can prevent any instance from being created by returning zero for the DRV_OPEN message.


Configuration

An installable driver can let users choose configuration settings for the driver and associated hardware by displaying a configuration dialog box when processing the DRV_CONFIGURE message. The driver is responsible for creating and managing the dialog box, processing any user input from the dialog box, and changing the configuration of the driver or hardware as requested by the user. The driver must provide a separate dialog box procedure to process window messages for the dialog box and a dialog box template to define the appearance and content of the dialog box.

Before receiving the DRV_CONFIGURE message, a driver receives the DRV_QUERYCONFIGURE message. The driver must return a nonzero value to the query to ensure receipt of the subsequent DRV_CONFIGURE message.

When initializing the configuration dialog box, the driver typically retrieves configuration information from the registry. To help locate this information, the DRV_CONFIGURE message usually includes the address of a DRVCONFIGINFO structure that contains the names of the registry key and value associated with the driver. If the user requests changes to the configuration, the driver should update the configuration information in the registry.


Installation

An installable driver can carry out driver-specific installation tasks when processing the DRV_INSTALL and DRV_REMOVE messages. An installation application, such as a Control Panel application, sends the messages to the driver when installing or removing the driver, respectively.

When processing the DRV_INSTALL message, the driver typically verifies that the required hardware is present and then displays the configuration dialog box to let the user choose the initial configuration settings for the driver and associated hardware. The message includes the address of a DRVCONFIGINFO structure that contains the names of the registry key and value associated with the driver; the driver checks the registry value for default configuration information. Finally, the driver also creates any additional registry keys and values needed for successful operation.

When processing the DRV_REMOVE message, the driver removes any registry keys and values it may have created.


Callback Functions

Installable drivers can notify the application, window, or task that opened the given instance about events by using the DriverCallback function. This function gives the driver the means to return information to an application or DLL while continuing to process a request.

If a driver supports callback functions, the application or DLL that opens the instance must supply a value this is either the address of a callback function, a window handle, or a task handle. This value and a flag identifying the type of the value are typically passed in a structure pointed to by the second parameter of the DRV_OPEN message.


Installable Drive Module-Definition File

The module-definition (.DEF) file of an installable driver names the driver, exports the DriverProc function, and defines a driver description. The following example shows a typical module-definition file for an installable driver:

LIBRARY OSCI

DESCRIPTION 'FREQ,AMPL:Oscilloscope frequency and amplitude drivers.'
EXPORTS
    DriverProc

Some installation applications may open the driver and retrieve the description line to use when installing the driver. To remain compatible with these installation applications, the description line should have this form:

DESCRIPTION alias[,alias]...:text

The alias specifies a unique name for the driver that applications can use to open the driver. The alias also serves as the value name associated with the driver in the registry. Multiple aliases are separated by commas. The text describes the purpose of the driver.


Installable Driver Functions and Messages

You can open an installable driver from an application by using the OpenDriver function. This function creates an instance of the driver, loading the driver into memory if no other instance exists, and returns the handle of the new instance. When opening an installable driver, you must supply either the full path of the driver or the names of the registry key and value associated with the driver.

Once a driver is open, you can direct it to carry out tasks by using the SendDriverMessage function to send driver messages to the driver. For example, you can direct the driver to display its configuration dialog box by sending the DRV_CONFIGURE message. Before sending this message, you must determine whether the driver has a configuration dialog box by sending the DRV_QUERYCONFIGURE message and checking for a nonzero return value. Many drivers provide a set of custom messages that you can send to direct the operations of the driver.

If you need special access to an installable driver, such as access to its resources, you can retrieve the module handle of the driver by using the GetDriverModuleHandle function.

When you no longer need the installable driver, you can close it by using the CloseDriver function.

You can use the installable driver functions and messages to open and manage any installable driver. However, the recommended course of action for opening and managing multimedia devices is to first use standard services (such as waveOutOpen, waveOutMessage, and waveOutClose for waveform output devices), if they exist. If standard services do not exist for a multimedia driver, then open and manage the driver using the installable driver functions and messages.

Note  The SendDriverMessage and GetDriverModuleHandle functions are the preferred functions to use to send messages to a driver and to obtain a handle to a module instance. The older DrvGetModuleHandle function, however, has been included to maintain compatibility with previous versions of the Windows operating system.


Using Installable Drivers

You use installable drivers to give applications or DLLs a standard way to access a device or a set of useful routines. The following sections show how to create an installable driver by using a DriverProc function and how to open an installable driver and direct it to carry out useful tasks.


Creating a DriverProc Function

You create a DriverProc function in much the same way as you create a window procedure. The function consists of a switch statement, and each case processes a given driver message, returning a value indicating success or failure. The DriverProc function has the following form:

LONG DriverProc(DWORD dwDriverId, HDRVR hdrvr, UINT msg,
    LONG lParam1, LONG lParam2)
{
    DWORD dwRes = 0L;

    switch (msg) {
    case DRV_LOAD:
    // Sent when the driver is loaded. This is always
    // the first message received by a driver.
        dwRes = 1L;  // returns 0L to fail
        break;

    case DRV_FREE:
    // Sent when the driver is about to be discarded.
    // This is the last message a driver receives
    // before it is freed.
        dwRes = 1L;  // return value ignored
        break;

    case DRV_OPEN:
    // Sent when the driver is opened.
        dwRes = 1L;  // returns 0L to fail
        break;       // value subsequently used
                     // for dwDriverId.

    case DRV_CLOSE:
    // Sent when the driver is closed. Drivers are
    // unloaded when the open count reaches zero.
        dwRes = 1L;  // returns 0L to fail
        break;

    case DRV_ENABLE:
    // Sent when the driver is loaded or reloaded and
    // when Windows is enabled. Install interrupt
    // handlers and initialize hardware. Expect the
    // driver to be in memory only between the enable
    // and disable messages.
        dwRes = 1L;  // return value ignored
        break;

    case DRV_DISABLE:
    // Sent before the driver is freed or when Windows
    // is disabled. Remove interrupt handlers and place
    // hardware in an inactive state.
        dwRes = 1L;  // return value ignored
        break;

    case DRV_INSTALL:
    // Sent when the driver is installed.
        dwRes = DRVCNF_OK;  // Can also return
        break;              // DRVCNF_CANCEL
                            // and DRV_RESTART

    case DRV_REMOVE:
    // Sent when the driver is removed.
        dwRes = 1L;  // return value ignored
        break;

    case DRV_QUERYCONFIGURE:
    // Sent to determine if the driver can be
    // configured.
        dwRes = 0L;  // Zero indicates configuration
        break;       // NOT supported

    case DRV_CONFIGURE:
    // Sent to display the configuration
    // dialog box for the driver.
        dwRes = DRVCNF_OK;  // Can also return
        break;              // DRVCNF_CANCEL
                            // and DRVCNF_RESTART

    default:
    // Process any other messages.
        return DefDriverProc (dwDriverId, hdrvr,
            msg, lParam1, lParam2);

    }
    return dwRes;
}


Configuring an Installable Driver

To direct an installable driver to carry out useful tasks, you must open the driver by using the OpenDriver function and send it messages by using the SendDriverMessage function. The following example shows how to direct the driver to display its configuration dialog box.

LONG MyConfigureDriver()
{
    HDRVR hdrvr;
    DRVCONFIGINFO dci;
    LONG lRes;

    // Open the driver (no additional parameters needed this time).
    if ((hdrvr = OpenDriver(L"\\samples\\sample.drv", 0, 0)) == 0) {
        // Can't open the driver
        return DRVCNF_CANCEL;
    }

    // Make sure driver has a configuration dialog box.
    if (SendDriverMessage(hdrvr, DRV_QUERYCONFIGURE, 0, 0) != 0) {
        // Set the DRVCONFIGINFO structure and send the message
        dci.dwDCISize = sizeof (dci);
        dci.lpszDCISectionName = (LPWSTR)0;
        dci.lpszDCIAliasName = (LPWSTR)0;
        lRes = SendDriverMessage(hdrvr, DRV_CONFIGURE, 0, (LONG)&dci);
     }

    // Close the driver (no additional parameters needed this time).
    CloseDriver(hdrvr, 0, 0);

    return lRes;
}


Installable Driver Reference

The functions and messages associated with installable drivers are grouped as follows.

Loading and Unloading Drivers

GetDriverModuleHandle
OpenDriver
SendDriverMessage

CloseDriver

DRV_CLOSE
DRV_DISABLE
DRV_ENABLE
DRV_FREE
DRV_LOAD
DRV_OPEN

Configuring a Driver

DRV_CONFIGURE
DRV_QUERYCONFIGURE
DRVCONFIGINFO

Installing a Driver

DRV_INSTALL
DRV_REMOVE

Driver Functions

DefDriverProc
DriverCallback
DriverProc


Installable Driver Functions

The functions in this section can be used in an application to open, close, and communicate with an installable driver.

CloseDriver
DrvGetModuleHandle
GetDriverModuleHandle
OpenDriver
SendDriverMessage


CloseDriver

Closes an installable driver.

LRESULT CloseDriver(HDRVR hdrvr, LONG lParam1, LONG lParam2);

Parameters

hdrvr

Handle of an installable driver instance. The handle must have been previously created by using the OpenDriver function.

lParam1 and lParam2

32-bit driver-specific data.

Return Value

Returns nonzero if successful or zero otherwise.

Remarks

The function passes the lParam1 and lParam2 parameters to the DriverProc function of the installable driver.


DrvGetModuleHandle

Retrieves the instance handle of the module that contains the installable driver. This function is provided for compatibility with previous versions of Windows.

WINMMAPI HMODULE WINAPI DrvGetModuleHandle(HDRVR hDriver);

Parameters

hDriver

Handle of the installable driver instance. The handle must have been previously created by using the OpenDriver function.

Return Value

Returns an instance handle of the driver module if successful or NULL otherwise.


GetDriverModuleHandle

Retrieves the instance handle of the module that contains the installable driver.

HMODULE GetDriverModuleHandle(HDRVR hdrvr);

Parameters

hdrvr

Handle of the installable driver instance. The handle must have been previously created by using the OpenDriver function.

Return Value

Returns an instance handle of the driver module if successful or NULL otherwise.


OpenDriver

Opens an instance of an installable driver and initializes the instance using either the driver’s default settings or a driver-specific value.

HDRVR OpenDriver(LPCWSTR lpDriverName, LPCWSTR lpSectionName,
    LONG lParam);

Parameters

lpDriverName

Address of a null-terminated, wide-character string that specifies the filename of an installable driver or the name of a registry value associated with the installable driver. (This value must have been previously set when the driver was installed.)

lpSectionName

Address of a null-terminated, wide-character string that specifies the name of the registry key containing the registry value given by the lpDriverName parameter. If lpSectionName is NULL, the registry key is assumed to be Drivers32.

lParam

32-bit driver-specific value. This value is passed as the lParam2 parameter to the DriverProc function of the installable driver.

Return Value

Returns the handle of the installable driver instance if successful or NULL otherwise.


SendDriverMessage

Sends the specified message to the installable driver.

LRESULT SendDriverMessage(HDRVR hdrvr, UINT msg, LONG lParam1,
    LONG lParam2);

Parameters

hdrvr

Handle of the installable driver instance. The handle must been previously created by using the OpenDriver function.

msg

Driver message value. It can be a custom message value or one of these standard message values:

DRV_QUERYCONFIGURE	Queries an installable driver about whether it supports the DRV_CONFIGURE message and can display a configuration dialog box.
DRV_CONFIGURE	Notifies an installable driver that it should display a configuration dialog box. (This message should only be sent if the driver returns a nonzero value when the DRV_QUERYCONFIGURE message is processed.)
DRV_INSTALL	Notifies an installable driver that it has been successfully installed.
DRV_REMOVE	Notifies an installable driver that it is about to be removed from the system.
lParam1 and lParam2

32-bit message-dependent information.

Return Value

Returns nonzero if successful or zero otherwise.


Driver Functions

The functions in this section describe the entry point, default processing, and callback functions to use in an installable driver.

DefDriverProc
DriverProc
DriverCallback


DefDriverProc

Provides default processing for any messages not processed by an installable driver. This function is intended to be used only within the DriverProc function of an installable driver.

LONG DefDriverProc(DWORD dwDriverId, HDRVR hdrvr, UINT msg,
    LONG lParam1, LONG lParam2);

Parameters

dwDriverId

Identifier of the installable driver.

hdrvr

Handle of the installable driver instance.

msg

Driver message value.

lParam1 and lParam2

32-bit message-dependent information.

Return Value

Returns nonzero if successful or zero otherwise.


DriverProc

Processes driver messages for the installable driver. DriverProc is a driver-supplied function.

LONG DriverProc(DWORD dwDriverId, HDRVR hdrvr, UINT msg,
    LONG lParam1, LONG lParam2);

Parameters

dwDriverId

Identifier of the installable driver.

hdrvr

Handle of the installable driver instance. Each instance of the installable driver has a unique handle.

msg

Driver message value. It can be a custom value or one of these standard values:

DRV_CLOSE	Notifies the driver that it should decrement its usage count and unload the driver if the count is zero.
DRV_CONFIGURE	Notifies the driver that it should display a configuration dialog box. This message is sent only if the driver returns a nonzero value when processing the DRV_QUERYCONFIGURE message.
DRV_DISABLE	Notifies the driver that its allocated memory is about to be freed.
DRV_ENABLE	Notifies the driver that it has been loaded or reloaded or that Windows has been enabled.
DRV_FREE	Notifies the driver that it will be discarded.
DRV_INSTALL	Notifies the driver that it has been successfully installed.
DRV_LOAD	Notifies the driver that it has been successfully loaded.
DRV_OPEN	Notifies the driver that it is about to be opened.
DRV_POWER	Notifies the driver that the device’s power source is about to be turned on or off.
DRV_QUERYCONFIGURE	Directs the driver to specify whether it supports the DRV_CONFIGURE message.
DRV_REMOVE	Notifies the driver that it is about to be removed from the system.
lParam1 and lParam2

32-bit message-specific value.

Return Value

Returns nonzero if successful or zero otherwise.

Remarks

When msg is DRV_OPEN, lParam1 is the string following the driver filename from the SYSTEM.INI file and lParam2 is the value given as the lParam parameter in a call to the OpenDriver function.

When msg is DRV_CLOSE, lParam1 and lParam2 are the same values as the lParam1 and lParam2 parameters in a call to the CloseDriver function.


DriverCallback

Calls a callback function, sends a message to a window, or unblocks a thread. The action depends on the value of the notification flag. This function is intended to be used only within the DriverProc function of an installable driver.

BOOLEAN DriverCallback(DWORD dwCallBack, DWORD dwFlags, HDRVR hdrvr,
    DWORD msg, DWORD dwUser, DWORD dwParam1, DWORD dwParam2);

Parameters

dwCallBack

Address of the callback function, a window handle, or a task handle, depending on the flag specified in the dwFlags parameter.

dwFlags

Notification flags. It can be one of these values:

DCB_NOSWITCH	The system is prevented from switching stacks. This value is only used if enough stack space for the callback function is known to exist.
DCB_FUNCTION	The dwCallback parameter is the address of an application-defined callback function. The system sends the callback message to the callback function.
DCB_WINDOW	The dwCallback parameter is the handle of an application-defined window. The system sends subsequent notifications to the window.
DCB_TASK	The dwCallback parameter is the handle of an application or task. The system sends subsequent notifications to the application or task.
hdrvr

Handle of the installable driver instance.

msg

Message value.

dwUser

32-bit user-instance data supplied by the application when the device was opened.

dwParam1 and dwParam2

32-bit message-dependent parameter.

Return Value

Returns TRUE if successful or FALSE if a parameter is invalid or the task’s message queue is full.

Remarks

The client specifies how to notify it when the device is opened. The DCB_FUNCTION and DCB_WINDOW flags are equivalent to the high-order word of the corresponding flags CALLBACK_FUNCTION and CALLBACK_WINDOW specified in the lParam2 parameter of the DRV_OPEN message when the device was opened.

If notification is accomplished with a callback function, hdrvr, msg, dwUser, dwParam1, and dwParam2 are passed to the callback function. If notification is accomplished by means of a window, only msg, hdrvr, and dwParam1 are passed to the window.


Driver Messages
Installable Driver Messages

The messages in this section can be used with installable drivers.

DRV_CLOSE
DRV_CONFIGURE
DRV_DISABLE
DRV_ENABLE
DRV_EXITSESSION
DRV_FREE
DRV_INSTALL
DRV_LOAD
DRV_OPEN
DRV_POWER
DRV_QUERYCONFIGURE
DRV_REMOVE


DRV_CLOSE

Directs the driver to close the given instance. If no other instances are open, the driver should prepare for subsequent release from memory.

Parameters

dwDriverId

Identifier of the installable driver. This is the same value previously returned by the driver from the DRV_OPEN message.

hdrvr

Handle of the installable driver instance.

lParam1

32-bit value specified as the lParam1 parameter in a call to the DriverClose function.

lParam2

32-bit value specified as the lParam2 parameter in a call to the DriverClose function.

Return Value

Returns nonzero if successful or zero otherwise.


DRV_CONFIGURE

Directs the installable driver to display its configuration dialog box and let the user specify new settings for the given installable driver instance.

Parameters

dwDriverId

Identifier of the installable driver. This is the same value previously returned by the driver from the DRV_OPEN message.

hdrvr

Handle of the installable driver instance.

lParam1

Handle of the parent window. This window is used as the parent window for the configuration dialog box.

lParam2

Address of a DRVCONFIGINFO structure or NULL. If the structure is given, it contains the names of the registry key and value associated with the driver.

Return Value

Returns one of these values:

DRVCNF_OK	The configuration is successful; no further action is required.
DRVCNF_CANCEL	The user canceled the dialog box; no further action is required.
DRVCNF_RESTART	The configuration is successful, but the changes do not take effect until the system is restarted.
Remarks

Some installable drivers append configuration information to the value assigned to the registry value associated with the driver.

The DRV_CANCEL, DRV_OK, and DRV_RESTART return values are obsolete; they have been replaced by DRVCNF_CANCEL, DRVCNF_OK, and DRVCNF_RESTART, respectively.


DRV_DISABLE

Disables the driver. The driver should place the corresponding device, if any, in an inactive state and terminate any callback functions or threads.

Parameters

hdrvr

Handle of the installable driver instance.

Return Value

No return value.

Remarks

The dwDriverId, lParam1, and lParam2 parameters are not used.

After disabling the driver, the system typically sends the driver a DRV_FREE message before removing the driver from memory.


DRV_ENABLE

Enables the driver. The driver should initialize any variables and locate devices with the input and output (I/O) interface.

Parameters

hdrvr

Handle of the installable driver instance.

Return Value

No return value.

Remarks

The dwDriverId, lParam1, and lParam2 parameters are not used.

Drivers are considered enabled from the time they receive this message until they are disabled by using the DRV_DISABLE message.


DRV_EXITSESSION

Notifies the driver that Windows is preparing to exit. The driver should prepare for termination.

Parameters

dwDriverId

Identifier of the installable driver. This is the same value previously returned by the driver from the DRV_OPEN message.

hdrvr

Handle of the installable driver instance.

Return Value

No return value.

Remarks

The lParam1 and lParam2 parameters are not used.


DRV_FREE

Notifies the driver that it is being removed from memory. The driver should free any memory and other system resources that it has allocated.

Parameters

hdrvr

Handle of the installable driver instance.

Return Value

No return value.

Remarks

The dwDriverId, lParam1, and lParam2 parameters are not used.

The DRV_FREE message is always the last message that a device driver receives.


DRV_INSTALL

Notifies the driver that is it being installed. The driver should create and initialize any needed registry keys and values and verify that the supporting drivers and hardware are installed and properly configured.

Parameters

dwDriverId

Identifier of the installable driver. This is the same value previously returned by the driver from the DRV_OPEN message.

hdrvr

Handle of the installable driver instance.

lParam2

Address of a DRVCONFIGINFO structure or NULL. If a structure is given, it contains the names of the registry key and value associated with the driver.

Return Value

Returns one of these values:

DRVCNF_OK	The installation is successful; no further action is required.
DRVCNF_CANCEL	The installation failed..
DRVCNF_RESTART	The installation is successful, but it does not take effect until the system is restarted.
Remarks

The lParam1 parameter is not used.

Some installable drivers append configuration information to the value assigned to the registry value associated with the driver.


DRV_LOAD

Notifies the driver that it has been loaded. The driver should make sure that any hardware and supporting drivers it needs to function properly are present.

Parameters

The hdrvr parameter is always zero. The dwDriverId, lParam1, and lParam2 parameters are not used.

Return Value

Returns nonzero if successful or zero otherwise.

Remarks

The DRV_LOAD message is always the first message that a device driver receives.


DRV_OPEN

Directs the driver to open an new instance.

Parameters

dwDriverId

Identifier of the installable driver.

hdrvr

Handle of the installable driver instance.

lParam1

Address of a null-terminated, wide-character string that specifies configuration information used to open the instance. If no configuration information is available, either this string is empty or the parameter is NULL.

lParam2

32-bit driver-specific data.

Return Value

Returns a nonzero value if successful or zero otherwise.

Remarks

If the driver returns a nonzero value, the system uses that value as the driver identifier (the dwDriverId parameter) in messages it subsequently sends to the driver instance. The driver can return any type of value as the identifier. For example, some drivers return memory addresses that point to instance-specific information. Using this method of specifying identifiers for a driver instance gives the drivers ready access to the information while they are processing messages.


DRV_POWER

Notifies the driver that power to the device is being turned on or off.

Parameters

dwDriverId

Identifier of the installable driver. This is the same value previously returned by the driver from the DRV_OPEN message.

hdrvr

Handle of the installable driver instance.

Return Value

Returns nonzero if successful or zero otherwise.

Remarks

The lParam1 and lParam2 parameters are not used.


DRV_QUERYCONFIGURE

Directs the driver to specify whether it supports custom configuration.

Parameters

dwDriverId

Identifier of the installable driver. This is the same value previously returned by the driver from the DRV_OPEN message.

hdrvr

Handle of the installable driver instance.

Return Value

Returns a nonzero value if the driver can display a configuration dialog box or zero otherwise.

Remarks

The lParam1 and lParam2 parameters are not used.


DRV_REMOVE

Notifies the driver that it is about to be removed from the system. When a driver receives this message, it should remove any sections it created in the registry.

Parameters

dwDriverId

Identifier of the installable driver. This is the same value previously returned by the driver from the DRV_OPEN message.

hdrvr

Handle of the installable driver instance.

Return Value

No return value.

Remarks

The lParam1 and lParam2 parameters are not used.


Driver Structures
Installable Driver Structures

The following structure can be used with installable drivers.

DRVCONFIGINFO


DRVCONFIGINFO

Contains the registry key and value names associated with the installable driver.

typedef struct tagDRVCONFIGINFO {

    DWORD dwDCISize;

    LPCWSTR lpszDCISectionName;

    LPCWSTR lpszDCIAliasName;

} DRVCONFIGINFO;

Members

dwDCISize

Size of the structure, in bytes.

lpszDCISectionName

Address of a null-terminated, wide-character string specifying the name of the registry key associated with the driver.

lpszDCIAliasName

Address of a null-terminated, wide-character string specifying the name of the registry value associated with the driver.


Multimedia PC Specifications

The Multimedia PC (MPC) Marketing Council has developed two specifications to encourage the adoption of multimedia capabilities. The Level 1 specification, developed in 1990, provides a baseline definition of multimedia computing in functionality, hardware components, and software components. The Level 2 specification, issued in 1993, builds on the first specification and focuses on enhanced multimedia capabilities since the first specification was issued.

This appendix summarizes the specifications. For more information or complete specifications, contact the MPC Marketing Council at the following address:

Multimedia PC Marketing Council
1730 M Street NW, Suite 707
Washington, DC  20036


Level 1 Specification

The Level 1 specification was developed to encourage the adoption of basic multimedia capabilities at a minimum performance level. The most common multimedia components available to the marketplace when the Level 1 specification was issued included several compact disc − read-only memory (CD-ROM) drives that provided data at sustained transfer rates varying from 90 to 150 kilobytes per second, 8-bit sound cards, and 16-color and 256-color (SVGA) video adapters.


Level 1 System Resources

The minimum configuration for a PC to satisfy the Level 1 specification includes the following items:

•	A 386SX microprocessor with 2 megabytes (MB) of random-access memory (RAM)

•	A 3.5-inch high-density floppy disk drive

•	A hard disk drive with at least 30 MB of disk space

•	A color monitor with a display resolution of 640 by 480 pixels with 16 colors

•	System software that offers binary compatibility with the Microsoft Windows operating system version 3.0


Level 1 Optical Storage

The minimum performance optical storage device is a CD-ROM drive that meets the following criteria:

•	A sustained data transfer rate of 150 kilobytes per second

•	A CPU bandwidth usage of 40 percent or less when maintaining a sustained data transfer rate of 150 kilobytes per second

•	An average seek time of 1 second or less


Level 1 Audio Requirements

The audio subsystem of a PC satisfying the Level 1 specification includes the following items:

•	An 8-bit digital-to-analog converter (DAC) capable of processing waveform-audio files recorded at 22.05 and 11.025 kHz sampling rates

•	An 8-bit analog-to-digital converter (ADC) capable of recording waveform-audio files at the sample rate of 11.025 kHz through an external source, such as a microphone

•	Internal synthesizer capabilities with four or nine multivoice, multitimbral capacity, and two simultaneous percussive notes


Level 2 Specification

The Level 2 specification was developed to encourage the adoption of enhanced multimedia capabilities. This specification builds on the requirements set in the Level 1 specification and is a superset of it. The Level 2 specification defines the minimum system functionality for enhanced multimedia capabilities. It is not a recommendation for a system configuration.


Level 2 System Resources

The minimum configuration for a PC to satisfy the Level 2 specification includes the following items:

•	A 25 Mhz 486SX microprocessor with 4 MB of RAM

•	A 3.5-inch high-density floppy disk drive

•	A hard disk drive with at least 160 MB of disk space

•	A 101-key keyboard with a standard DIN connector or one that provides identical functionality by using key combinations

•	A two-button mouse with a serial or bus connector

•	A MIDI (Musical Instrument Digital Interface) port that includes MIDI Out, MIDI In, and MIDI Thru, and that has interrupt support for input and FIFO transfer

•	An IBM-style analog or digital joystick (game) port

•	A color monitor with a display resolution of 640 by 480 pixels with 65,536 colors

•	System software that offers binary compatibility with Windows 3.0 or Windows 3.1

In addition, the recommended performance goal for the video adapter (VGA+) is 1.2 million pixels per second using 40 percent or less of the CPU bandwidth. The device-independent bitmaps (DIBs) used to measure this performance goal have color depths of 1, 4, and 8 bits, and can use run-length encoding or be unencoded. A second method of measuring the video performance is to deliver 256-color, 320 by 240 pixel digital-video images at 15 frames per second.


Level 2 Optical Storage

The minimum performance optical storage device is a double-speed CD-ROM drive that meets the following criteria:

•	A sustained data transfer rate of 300 kilobytes per second

•	A CPU bandwidth usage of 40 percent or less when maintaining a sustained data transfer rate of 150 kilobytes per second, or a CPU bandwidth of 60 percent or less when maintaining a sustained data transfer rate of 300 kilobytes per second

•	An average seek time of 400 milliseconds or less

•	A 10,000 hour mean-time-between-failures rating

•	CD-ROM XA ready (mode 1 capable, mode 2 form 1 capable, mode form 2 capable)

•	Multisession capable

•	MSCDEX-2.2 driver or equivalent that implements the extended audio functions

The recommended CPU bandwidth should be reached by using a read-block size of at least 16K and a lead time of no more than the time needed to load one read-block of data into the CD-ROM buffer.


Level 2 Audio Requirements

The audio subsystem of a PC satisfying the Level 2 specification includes the following items:

•	A CD-ROM driver with CD-DA (Red Book audio) outputs and volume control

•	A 16-bit DAC with the following characteristics:

•	Linear PCM (Pulse Code Modulation) sampling

•	DMA or FIFO buffered transfer capability with interrupt on buffer empty

•	Mandatory sample rates of 44.1, 22.05, and 11.025 kHz

•	Stereo channels

•	CPU bandwidth usage of 10 percent or less when outputting audio of 22.05 or 11.025 kHz sample rate, or a CPU bandwidth of 15 percent or less when outputting audio of 44.1 kHz sample rate

•	A 16-bit ADC with the following characteristics:

•	Linear PCM sampling

•	DMA or FIFO buffered transfer capability with interrupt on buffer empty

•	Mandatory sample rates of 44.1, 22.05, and 11.025 kHz

•	Microphone input

•	Internal synthesizer capabilities with multivoice, multitimbral, six simultaneous melody notes plus two simultaneous percussive notes

•	Internal mixing with the following capabilities:

•	Can combine three audio sources and present the output as a stereo, line-level audio signal at the back panel

•	Mixing sources are CD Red Book audio, synthesizer, and DAC

•	Each mixing source has 3-bit volume control with a logarithmic taper


Manufacturer and Product Identifiers

This appendix documents the manufacturer and product identifiers defined for multimedia applications. These identifiers are used when an application issues a query about the installed devices on a computer. To use these identifiers in your application, include the MMREG.H file.

To request a product identifier for a device, send email to mmreg@microsoft.com.


Manufacturer Identifiers

Company name	Identifier
Advanced Gravis Computer Technology, Ltd.	MM_GRAVIS
Antex Electronics Corporation	MM_ANTEX
APPS Software	MM_APPS
Artisoft, Inc.	MM_ARTISOFT
AST Research, Inc.	MM_AST
ATI Technologies, Inc.	MM_ATI
Audio, Inc.	MM_AUDIOFILE
Audio Processing Technology	MM_APT
Audio Processing Technology	MM_AUDIOPT
Auravision Corporation	MM_AURAVISION
Aztech Labs, Inc.	MM_AZTECH
Canopus, Co., Ltd.	MM_CANOPUS
Compusic	MM_COMPUSIC
Computer Aided Technology, Inc.	MM_CAT
Computer Friends, Inc.	MM_COMPUTER_FRIENDS
Control Resources Corporation	MM_CONTROLRES
Creative Labs, Inc.	MM_CREATIVE
Dialogic Corporation	MM_DIALOGIC
Dolby Laboratories, Inc.	MM_DOLBY
DSP Group, Inc.	MM_DSP_GROUP
DSP Solutions, Inc.	MM_DSP_SOLUTIONS
Echo Speech Corporation	MM_ECHO
ESS Technology, Inc.	MM_ESS
Everex Systems, Inc.	MM_EVEREX
EXAN, Ltd.	MM_EXAN
Fujitsu, Ltd.	MM_FUJITSU
I/O Magic Corporation	MM_IOMAGIC
ICL Personal Systems	MM_ICL_PS
Ing. C. Olivetti & C., S.p.A.	MM_OLIVETTI
Integrated Circuit Systems, Inc.	MM_ICS
Intel Corporation	MM_INTEL
InterActive, Inc.	MM_INTERACTIVE
International Business Machines	MM_IBM
Iterated Systems, Inc.	MM_ITERATEDSYS
Logitech, Inc.	MM_LOGITECH
Lyrrus, Inc.	MM_LYRRUS
Matsushita Electric Corporation of America	MM_MATSUSHITA
Media Vision, Inc.	MM_MEDIAVISION
Metheus Corporation	MM_METHEUS
microEngineering Labs	MM_MELABS
Microsoft Corporation	MM_MICROSOFT
MOSCOM Corporation	MM_MOSCOM
Motorola, Inc.	MM_MOTOROLA
Natural MicroSystems Corporation	MM_NMS
NCR Corporation	MM_NCR
NEC Corporation	MM_NEC
New Media Corporation	MM_NEWMEDIA
OKI	MM_OKI
OPTi, Inc.	MM_OPTI
Roland Corporation	MM_ROLAND
SCALACS	MM_SCALACS
Seiko Epson Corporation, Inc.	MM_EPSON
Sierra Semiconductor Corporation	MM_SIERRA
Silicon Software, Inc.	MM_SILICONSOFT
Sonic Foundry	MM_SONICFOUNDRY
Speech Compression	MM_SPEECHCOMP
Supermac Technology, Inc.	MM_SUPERMAC
Tandy Corporation	MM_TANDY
Toshihiko Okuhura, Korg, Inc.	MM_KORG
Truevision, Inc.	MM_TRUEVISION
Turtle Beach Systems	MM_TURTLE_BEACH
Video Associates Labs, Inc.	MM_VAL
VideoLogic, Inc.	MM_VIDEOLOGIC
Visual Information Technologies, Inc.	MM_VITEC
VocalTec, Inc.	MM_VOCALTEC
Voyetra Technologies	MM_VOYETRA
Wang Laboratories	MM_WANGLABS
Willow Pond Corporation	MM_WILLOWPOND
Winnov, LP	MM_WINNOV
Xebec Multimedia Solutions Limited	MM_XEBEC
Yamaha Corporation of America	MM_YAMAHA


Microsoft Corporation Product Identifiers

Product name	Identifier
Adlib-compatible synthesizer	MM_ADLIB
G.711 codec	MM_MSFT_ACM_G711
GSM 610 codec	MM_MSFT_ACM_GSM610
IMA ADPCM codec	MM_MSFT_ACM_IMAADPCM
Joystick adapter	MM_PC_JOYSTICK
MIDI mapper	MM_MIDI_MAPPER
MPU 401-compatible MIDI input port	MM_MPU401_MIDIIN
MPU 401-compatible MIDI output port	MM_MPU401_MIDIOUT
MS ADPCM codec	MM_MSFT_ACM_MSADPCM
MS audio board stereo FM synthesizer	MM_MSFT_WSS_FMSYNTH_STEREO
MS audio board aux port	MM_MSFT_WSS_AUX
MS audio board mixer driver	MM_MSFT_WSS_MIXER
MS audio board waveform input	MM_MSFT_WSS_WAVEIN
MS audio board waveform output	MM_MSFT_WSS_WAVEOUT
MS audio compression manager	MM_MSFT_MSACM
MS filter	MM_MSFT_ACM_MSFILTER
MS OEM audio aux port	MM_MSFT_WSS_OEM_AUX
MS OEM audio board mixer driver	MM_MSFT_WSS_OEM_MIXER
MS OEM audio board stereo FM synthesizer	MM_MSFT_WSS_OEM_FMSYNTH_STEREO
MS OEM audio board waveform input	MM_MSFT_WSS_OEM_WAVEIN
MS OEM audio board waveform output	MM_MSFT_WSS_OEM_WAVEOUT
MS vanilla driver aux (CD)	MM_MSFT_GENERIC_AUX_CD
MS vanilla driver aux (line in)	MM_MSFT_GENERIC_AUX_LINE
MS vanilla driver aux (mic)	MM_MSFT_GENERIC_AUX_MIC
MS vanilla driver MIDI external out	MM_MSFT_GENERIC_MIDIOUT
MS vanilla driver MIDI in	MM_MSFT_GENERIC_MIDIIN
MS vanilla driver MIDI synthesizer	MM_MSFT_GENERIC_MIDISYNTH
MS vanilla driver waveform input	MM_MSFT_GENERIC_WAVEIN
MS vanilla driver wavefrom output	MM_MSFT_GENERIC_WAVEOUT
PC speaker waveform output	MM_PCSPEAKER_WAVEOUT
PCM converter	MM_MSFT_ACM_PCM
Sound Blaster internal synthesizer	MM_SNDBLST_SYNTH
Sound Blaster MIDI input port	MM_SNDBLST_MIDIIN
Sound Blaster MIDI output port	MM_SNDBLST_MIDIOUT
Sound Blaster waveform input	MM_SNDBLST_WAVEIN
Sound Blaster waveform output	MM_SNDBLST_WAVEOUT
Wave mapper	MM_WAVE_MAPPER


Microsoft Windows Sound System Drivers

Driver	Identifier
Sound Blaster 16 waveform output	MM_MSFT_SB16_WAVEOUT
Sound Blaster 16 aux (CD)	MM_WSS_SB16_AUX_CD
Sound Blaster 16 aux (CD)	MM_MSFT_SB16_AUX_CD
Sound Blaster 16 aux (line in)	MM_WSS_SB16_AUX_LINE
Sound Blaster 16 aux (line in)	MM_MSFT_SB16_AUX_LINE
Sound Blaster 16 FM synthesizer	MM_WSS_SB16_SYNTH
Sound Blaster 16 FM synthesizer	MM_MSFT_SB16_SYNTH
Sound Blaster 16 MIDI out	MM_WSS_SB16_MIDIOUT
Sound Blaster 16 MIDI out	MM_MSFT_SB16_MIDIOUT
Sound Blaster 16 MIDI in	MM_WSS_SB16_MIDIIN
Sound Blaster 16 MIDI in	MM_MSFT_SB16_MIDIIN
Sound Blaster 16 mixer device	MM_WSS_SB16_MIXER
Sound Blaster 16 mixer device	MM_MSFT_SB16_MIXER
Sound Blaster 16 waveform input	MM_WSS_SB16_WAVEIN
Sound Blaster 16 waveform input	MM_MSFT_SB16_WAVEIN
Sound Blaster 16 waveform output	MM_WSS_SB16_WAVEOUT
Sound Blaster Pro aux (CD)	MM_WSS_SBPRO_AUX_CD
Sound Blaster Pro aux (CD)	MM_MSFT_SBPRO_AUX_CD
Sound Blaster Pro aux (line in)	MM_WSS_SBPRO_AUX_LINE
Sound Blaster Pro aux (line in)	MM_MSFT_SBPRO_AUX_LINE
Sound Blaster Pro FM synthesizer	MM_WSS_SBPRO_SYNTH
Sound Blaster Pro FM synthesizer	MM_MSFT_SBPRO_SYNTH
Sound Blaster Pro MIDI in	MM_WSS_SBPRO_MIDIIN
Sound Blaster Pro MIDI in	MM_MSFT_SBPRO_MIDIIN
Sound Blaster Pro MIDI out	MM_WSS_SBPRO_MIDIOUT
Sound Blaster Pro MIDI out	MM_MSFT_SBPRO_MIDIOUT
Sound Blaster Pro mixer	MM_WSS_SBPRO_MIXER
Sound Blaster Pro mixer	MM_MSFT_SBPRO_MIXER
Sound Blaster Pro waveform input	MM_WSS_SBPRO_WAVEIN
Sound Blaster Pro waveform input	MM_MSFT_SBPRO_WAVEIN
Sound Blaster Pro waveform output	MM_WSS_SBPRO_WAVEOUT
Sound Blaster Pro waveform output	MM_MSFT_SBPRO_WAVEOUT
WSS NT aux	MM_MSFT_WSS_NT_AUX
WSS NT FM synthesizer	MM_MSFT_WSS_NT_FMSYNTH_STEREO
WSS NT mixer	MM_MSFT_WSS_NT_MIXER
WSS NT wave in	MM_MSFT_WSS_NT_WAVEIN
WSS NT wave out	MM_MSFT_WSS_NT_WAVEOUT


Product Identifiers

Company	Product identifiers
Artisoft, Inc.	MM_ARTISOFT_SBWAVEIN MM_ARTISOFT_SBWAVEOUT
Audio Processing Technology	MM_APT_ACE100CD
Aztech Labs, Inc.	MM_AZTECH_AUX_CD MM_AZTECH_AUX_LINE MM_AZTECH_AUX_MIC MM_AZTECH_DSP16_FMSYNTH MM_AZTECH_DSP16_WAVEIN MM_AZTECH_DSP16_WAVEOUT MM_AZTECH_DSP16_WAVESYNTH MM_AZTECH_FMSYNTH MM_AZTECH_MIDIIN MM_AZTECH_MIDIOUT MM_AZTECH_PRO16_FMSYNTH MM_AZTECH_PRO16_WAVEIN MM_AZTECH_PRO16_WAVEOUT MM_AZTECH_WAVEIN MM_AZTECH_WAVEOUT
Computer Aided Technology, Inc.	MM_CAT_WAVEOUT
Creative Labs, Inc.	MM_CREATIVE_AUX_CD MM_CREATIVE_AUX_LINE MM_CREATIVE_AUX_MASTER MM_CREATIVE_AUX_MIC MM_CREATIVE_AUX_MIDI MM_CREATIVE_AUX_PCSPK MM_CREATIVE_AUX_WAVE MM_CREATIVE_FMSYNTH_MONO MM_CREATIVE_FMSYNTH_STEREO MM_CREATIVE_MIDIIN MM_CREATIVE_MIDIOUT MM_CREATIVE_SB15_WAVEIN MM_CREATIVE_SB15_WAVEOUT MM_CREATIVE_SB16_MIXER MM_CREATIVE_SB20_WAVEIN MM_CREATIVE_SB20_WAVEOUT MM_CREATIVE_SBP16_WAVEIN MM_CREATIVE_SBP16_WAVEOUT MM_CREATIVE_SBPRO_MIXER MM_CREATIVE_SBPRO_WAVEIN MM_CREATIVE_SBPRO_WAVEOUT
DSP Group, Inc.	MM_DSP_GROUP_TRUESPEECH
DSP Solutions, Inc.	MM_DSP_SOLUTIONS_AUX MM_DSP_SOLUTIONS_SYNTH MM_DSP_SOLUTIONS_WAVEIN MM_DSP_SOLUTIONS_WAVEOUT
Echo Speech Corporation	MM_ECHO_AUX MM_ECHO_MIDIIN MM_ECHO_MIDIOUT MM_ECHO_SYNTH MM_ECHO_WAVEIN MM_ECHO_WAVEOUT
ESS Technology, Inc.	MM_ESS_AMAUX MM_ESS_AMMIDIIN MM_ESS_AMMIDIOUT MM_ESS_AMSYNTH MM_ESS_AMWAVEIN MM_ESS_AMWAVEOUT
Everex Systems, Inc.	MM_EVEREX_CARRIER
I/O Magic Corporation	MM_IOMAGIC_TEMPO_AUXOUT MM_IOMAGIC_TEMPO_MIDIOUT MM_IOMAGIC_TEMPO_MXDOUT MM_IOMAGIC_TEMPO_SYNTH MM_IOMAGIC_TEMPO_WAVEIN MM_IOMAGIC_TEMPO_WAVEOUT
Ing. C. Olivetti & C., S.p.A.	MM_OLIVETTI_ACM_ADPCM MM_OLIVETTI_ACM_CELP MM_OLIVETTI_ACM_GSM MM_OLIVETTI_ACM_OPR MM_OLIVETTI_ACM_SBC MM_OLIVETTI_AUX MM_OLIVETTI_JOYSTICK MM_OLIVETTI_MIDIIN MM_OLIVETTI_MIDIOUT MM_OLIVETTI_MIXER MM_OLIVETTI_SYNTH MM_OLIVETTI_WAVEIN MM_OLIVETTI_WAVEOUT
Integrated Circuit Systems, Inc.	MM_ICS_WAVEDECK_AUX MM_ICS_WAVEDECK_MIXER MM_ICS_WAVEDECK_SYNTH MM_ICS_WAVEDECK_WAVEIN MM_ICS_WAVEDECK_WAVEOUT
InterActive, Inc.	MM_INTERACTIVE_WAVEIN MM_INTERACTIVE_WAVEOUT
International Business Machines	MM_IBM_PCMCIA_AUX MM_IBM_PCMCIA_MIDIIN MM_IBM_PCMCIA_MIDIOUT MM_IBM_PCMCIA_SYNTH MM_IBM_PCMCIA_WAVEIN MM_IBM_PCMCIA_WAVEOUT MM_MMOTION_WAVEAUX MM_MMOTION_WAVEIN MM_MMOTION_WAVEOUT
Iterated Systems, Inc.	MM_ITERATEDSYS_FUFCODEC
Lyrrus, Inc.	MM_LYRRUS_BRIDGE_GUITAR
Matsushita Electric Corporation of America	MM_MATSUSHITA_AUX MM_MATSUSHITA_FMSYNTH_STEREO MM_MATSUSHITA_MIXER MM_MATSUSHITA_WAVEIN MM_MATSUSHITA_WAVEOUT
Media Vision, Inc.	MM_MEDIAVISION_CDPC MM_CDPC_AUX MM_CDPC_MIDIIN MM_CDPC_MIDIOUT MM_CDPC_MIXER MM_CDPC_SYNTH MM_CDPC_WAVEIN MM_CDPC_WAVEOUT
	MM_OPUS401_MIDIIN MM_OPUS401_MIDIOUT
	MM_MEDIAVISION_OPUS1208 MM_OPUS1208_AUX MM_OPUS1208_MIXER MM_OPUS1208_SYNTH MM_OPUS1208_WAVEIN MM_OPUS1208_WAVEOUT
	MM_MEDIAVISION_OPUS1216 MM_OPUS1216_AUX MM_OPUS1216_MIDIIN MM_OPUS1216_MIDIOUT MM_OPUS1216_MIXER MM_OPUS1216_SYNTH MM_OPUS1216_WAVEIN MM_OPUS1216_WAVEOUT
	MM_MEDIAVISION_PROAUDIO MM_PROAUD_AUX MM_PROAUD_MIDIIN MM_PROAUD_MIDIOUT MM_PROAUD_MIXER
	MM_MEDIAVISION_PROAUDIO_16 MM_PROAUD_16_AUX MM_PROAUD_16_MIDIIN MM_PROAUD_16_MIDIOUT MM_PROAUD_16_MIXER MM_PROAUD_16_SYNTH MM_PROAUD_16_WAVEIN MM_PROAUD_16_WAVEOUT
	MM_MEDIAVISION_PROAUDIO_PLUS MM_PROAUD_PLUS_AUX MM_PROAUD_PLUS_MIDIIN MM_PROAUD_PLUS_MIDIOUT MM_PROAUD_PLUS_MIXER MM_PROAUD_PLUS_SYNTH MM_PROAUD_PLUS_WAVEIN MM_PROAUD_PLUS_WAVEOUT MM_PROAUD_SYNTH MM_PROAUD_WAVEIN MM_PROAUD_WAVEOUT
	MM_MEDIAVISION_PROSTUDIO_16 MM_STUDIO_16_AUX MM_STUDIO_16_MIDIIN MM_STUDIO_16_MIDIOUT MM_STUDIO_16_MIXER MM_STUDIO_16_SYNTH MM_STUDIO_16_WAVEIN MM_STUDIO_16_WAVEOUT
	MM_MEDIAVISION_THUNDER MM_THUNDER_AUX MM_THUNDER_SYNTH MM_THUNDER_WAVEIN MM_THUNDER_WAVEOUT
	MM_MEDIAVISION_TPORT MM_TPORT_SYNTH MM_TPORT_WAVEIN MM_TPORT_WAVEOUT
Metheus Corporation	MM_METHEUS_ZIPPER
microEngineering Labs	MM_MELABS_MIDI2GO
MOSCOM Corporation	MM_MOSCOM_VPC2400
NCR Corporation	MM_NCR_BA_AUX MM_NCR_BA_MIXER MM_NCR_BA_SYNTH MM_NCR_BA_WAVEIN MM_NCR_BA_WAVEOUT
New Media Corporation	MM_NEWMEDIA_WAVJAMMER
OPTi, Inc.	MM_OPTI_M16_AUX MM_OPTI_M16_FMSYNTH_STEREO MM_OPTI_M16_MIDIIN MM_OPTI_M16_MIDIOUT MM_OPTI_M16_MIXER MM_OPTI_M16_WAVEIN MM_OPTI_M16_WAVEOUT MM_OPTI_M32_AUX MM_OPTI_M32_MIDIIN MM_OPTI_M32_MIDIOUT MM_OPTI_M32_MIXER MM_OPTI_M32_SYNTH_STEREO MM_OPTI_M32_WAVEIN MM_OPTI_M32_WAVEOUT MM_OPTI_P16_AUX MM_OPTI_P16_FMSYNTH_STEREO MM_OPTI_P16_MIDIIN MM_OPTI_P16_MIDIOUT MM_OPTI_P16_MIXER MM_OPTI_P16_WAVEIN MM_OPTI_P16_WAVEOUT
Roland Corporation	MM_ROLAND_MPU401_MIDIIN MM_ROLAND_MPU401_MIDIOUT MM_ROLAND_SC7_MIDIIN MM_ROLAND_SC7_MIDIOUT MM_ROLAND_SERIAL_MIDIIN MM_ROLAND_SERIAL_MIDIOUT MM_ROLAND_SMPU_MIDIINA MM_ROLAND_SMPU_MIDIINB MM_ROLAND_SMPU_MIDIOUTA MM_ROLAND_SMPU_MIDIOUTB
Sierra Semiconductor Corporation	MM_SIERRA_ARIA_AUX MM_SIERRA_ARIA_AUX2 MM_SIERRA_ARIA_MIDIIN MM_SIERRA_ARIA_MIDIOUT MM_SIERRA_ARIA_SYNTH MM_SIERRA_ARIA_WAVEIN MM_SIERRA_ARIA_WAVEOUT
Silicon Software, Inc.	MM_SILICONSOFT_SC1_WAVEIN MM_SILICONSOFT_SC1_WAVEOUT MM_SILICONSOFT_SC2_WAVEIN MM_SILICONSOFT_SC2_WAVEOUT MM_SILICONSOFT_SOUNDJR2_WAVEOUT MM_SILICONSOFT_SOUNDJR2PR_WAVEIN MM_SILICONSOFT_SOUNDJR2PR_WAVEOUT MM_SILICONSOFT_SOUNDJR3_WAVEOUT
Tandy Corporation	MM_TANDY_PSSJWAVEIN MM_TANDY_PSSJWAVEOUT MM_TANDY_SENS_MMAMIDIIN MM_TANDY_SENS_MMAMIDIOUT MM_TANDY_SENS_MMAWAVEIN MM_TANDY_SENS_MMAWAVEOUT MM_TANDY_SENS_VISWAVEOUT MM_TANDY_VISBIOSSYNTH MM_TANDY_VISWAVEIN MM_TANDY_VISWAVEOUT
Toshihiko Okuhura, Korg, Inc.	MM_KORG_PCIF_MIDIIN MM_KORG_PCIF_MIDIOUT
Truevision, Inc.	MM_TRUEVISION_WAVEIN1 MM_TRUEVISION_WAVEOUT1
VideoLogic, Inc.	MM_VIDEOLOGIC_MSWAVEIN MM_VIDEOLOGIC_MSWAVEOUT
Visual Information Technologies, Inc.	MM_VITEC_VMAKER MM_VITEC_VMPRO
VocalTec, Inc.	MM_VOCALTEC_WAVEIN MM_VOCALTEC_WAVEOUT
Wang Laboratories	MM_WANGLABS_WAVEIN1 MM_WANGLABS_WAVEOUT1
Winnov, LP	MM_WINNOV_CAVIAR_CHAMPAGNE MM_WINNOV_CAVIAR_VIDC MM_WINNOV_CAVIAR_WAVEIN MM_WINNOV_CAVIAR_WAVEOUT MM_WINNOV_CAVIAR_YUV8
Yamaha Corporation of America	MM_YAMAHA_GSS_AUX MM_YAMAHA_GSS_MIDIIN MM_YAMAHA_GSS_MIDIOUT MM_YAMAHA_GSS_SYNTH MM_YAMAHA_GSS_WAVEIN MM_YAMAHA_GSS_WAVEOUT


Audio Compression Manager

This overview describes the services available in the audio compression manager (ACM) and explains the programming techniques used to access these services.


About the Audio Compression Manager

The audio compression manager adds system-level support for the following services:

•	Transparent run-time audio compression and decompression

•	Waveform-audio data format selection

•	Waveform-audio data filter selection

•	Waveform-audio data format conversion

•	Waveform-audio data filtering


Mapping Waveform-Audio Devices

The Microsoft® Win32® application programming interface (API) provides a set of standard functions for audio devices. These functions issue calls to device drivers that manage hardware devices. The system uses a module called a “mapper” to manage installed devices. The mapper uses special hooks in the driver interface to intercept calls and to act as an intermediary between the system and the drivers installed in the system. The mapper is responsible for matching an application’s requests for access to a device with the available devices and for finding a device that meets the current application’s audio requirements. The system provides mappers for standard driver types: waveform-audio, MIDI (Musical Instrument Digital Interface), and auxiliary devices.

The ACM is an extension of the basic multimedia system and is installed as a mapper. This means the ACM uses the driver-interface mapper hooks for waveform-audio devices. Using these hooks allows the ACM to decode or encode waveform-audio data before passing it to or from a waveform-audio device driver. The difference between the ACM and the standard system mapper is that the ACM can search for a waveform-audio device that supports a specified format or find a combination of a waveform-audio device and an ACM compressor or decompressor that supports a specified format.

When an application requests that the system open a waveform-audio device for input or output, the request specifies the format and device. When the specified device is the mapper, the mapper must find a device that supports the specified format. The mapper implemented in the ACM searches for an installed waveform-audio device that supports the specified format. If the ACM cannot find such a device, it searches for a waveform-audio device and a compressor or decompressor that together support the format. Specifically, the ACM searches for a compressor or decompressor that converts the specified format into a format that is supported by an installed waveform-audio device. After the ACM finds a device that supports the converted format, it can honor requests to play or record the format originally requested, even though no installed waveform-audio device directly supports that format.

In addition to format conversion, the ACM also offers services to support compression, decompression, filtering, format selection, and filter selection. It provides a standard API that it supports by calling its own drivers.


How the Audio Compression Manager Works

The ACM uses existing driver interface hooks to override the default mapping algorithm for waveform-audio devices. This allows the ACM to intercept device-open calls. After a call has been intercepted, the ACM can perform a variety of tasks to process the audio data, such as inserting an external compressor or decompressor into the sequence.

The ACM manages the following types of drivers:

•	Compressor and decompressor (codec) drivers

•	Format converter drivers

•	Filter drivers

Compressors and decompressors change one format type to another. For example, a compressor or decompressor can change a PCM (Pulse Code Modulation) file to an ADPCM (Adaptive Differential Pulse Code Modulation) file. Format converters change the format, but not the data type. For example, a converter can change 44-kHz, 16-bit data to 44-kHz, 8-bit data. Filters do not change the data format at all, but they change the waveform-audio data in some manner. For example, a filter could combine a data stream and an echo of itself. A single ACM driver, or a filter tag or format tag within a driver, might also support combinations of the preceding types.

For waveform-audio output, the ACM passes each buffer of data to the converter as it arrives. The converter decompresses the data and returns the decompressed data to the ACM in a “shadow” buffer. The ACM then passes the decompressed shadow buffer to the waveform-audio driver. The ACM allocates the shadow buffers whenever it receives a prepare message.

For waveform-audio input, the ACM passes empty shadow buffers to the driver. It uses a background task to receive a notification after the driver has filled the shadow buffer. The ACM then passes the buffers to the driver for compression. After compression is finished, the driver passes the data to the application.


Audio Compression Manager Functions and Structures

The ACM functions fall into several categories. Naming conventions for the functions make it easy to identify these categories. Function names (with two exceptions) are of the form acmGroupFunction, where Group designates the ACM category (such as “Driver,” “Format,” “FormatTag,” “Filter,” “FilterTag,” or “Stream”), and Function describes the action performed by the function.

The functions in the filter and format groups are very similar. Almost every function that acts on filters has a parallel function that acts on formats.

In the format group, some functions use waveform-audio format tags (the wFormatTag member of a WAVEFORMATEX structure) while others require full waveform-audio formats (the full WAVEFORMATEX structure). (For reference information about the WAVEFORMATEX structure, see Error.)

In the filter group, some functions use waveform-audio filter tags (the dwFilterTag member of a WAVEFILTER structure), while others require full waveform-audio filters (the full WAVEFILTER structure).

The functions in the stream group represent the many steps involved in a conversion: opening a conversion instance, preparing for the conversion, performing the conversion, cleaning up after the conversion is complete, and closing the conversion instance.


Functions Called by the System

The system calls three different kinds of application-defined functions. Callback functions are functions in your application that the system calls in response to a request made by an application. Hook procedures help an application handle the customization of dialog boxes. A driver procedure is an application’s implementation of its own codec, converter, or filter.

The callback functions have the following names:

•	acmDriverEnumCallback

•	acmFilterEnumCallback

•	acmFilterTagEnumCallback

•	acmFormatEnumCallback

•	acmFormatTagEnumCallback

•	acmStreamConvertCallback

Most of the enumeration functions in the ACM use callback functions. For example, when you call an enumeration function, the ACM enumerates the items by repeatedly calling the application through the callback function.

Some functions cannot be called from within these callback functions. Functions that cannot be called manipulate internal ACM structures that are used by the enumeration functions. The following functions should not be called from within a callback function:

•	acmDriverAdd

•	acmDriverPriority

•	acmDriverRemove

The system calls the following functions to help an application handle the customization of dialog boxes:

•	acmFilterChooseHookProc

•	acmFormatChooseHookProc

The following function is specified as a prototype that allows an application to use a customized codec, converter, or filter. A function conforming to this prototype may be passed as an argument to the acmDriverAdd function.

•	acmDriverProc


Using the Audio Compression Manager

This section contains examples demonstrating how to perform the following tasks:

•	Retrieving a string that describes a filter

•	Producing a dialog box for selecting a filter

•	Producing a dialog box for selecting a specific type of format

•	Producing a dialog box for selecting restricted formats

•	Producing a dialog box for selecting a format for saving

•	Producing a dialog box for selecting a format for recording

•	Converting data from one format to another

•	Multistep format conversion

•	Finding a specific format

•	Finding a specific driver

•	Adding drivers within an application

•	Generating a nonstandard format


Retrieving a String That Describes a Filter

An application often needs to display a string that describes the current format. This task can be accomplished easily with the acmFilterTagDetails and acmFilterDetails functions. These functions must be called with the appropriate filter or filter tag. The following example shows how to use these functions.

BOOL GetFilterDescription

(

    LPWAVEFILTER  pwfltr,

    LPTSTR        pszFilterTag,

    LPTSTR        pszFilter

)

{

    MMRESULT      mmr;

    // Retrieve the name for the filter tag of the specified filter.

    if (NULL != pszFilterTag) {

        ACMFILTERTAGDETAILS aftd;

        // Initialize all unused members of the ACMFILTERTAGDETAILS

        // structure to zero.

        memset(&aftd, 0, sizeof(aftd));

        // Fill in the required members of the ACMFILTERTAGDETAILS

        // structure for the ACM_FILTERTAGDETAILSF_FILTERTAG query.

        aftd.cbStruct = sizeof(aftd);

        aftd.dwFilterTag = pwfltr->dwFilterTag;

        // Ask the ACM to find the first available driver that

        // supports the specified filter tag.

        mmr = acmFilterTagDetails(NULL, &aftd,

            ACM_FILTERTAGDETAILSF_FILTERTAG);

        if (MMSYSERR_NOERROR != mmr) {

            // No ACM driver is available that supports the

            // specified filter tag.

            return (FALSE);

        }

        // Copy the filter tag name into the calling application's

        // buffer.

        lstrcpy(pszFilterTag, aftd.szFilterTag);

    }

    // Retrieve the description of the attributes for the specified

    // filter.

    if (NULL != pszFilter) {

        ACMFILTERDETAILS afd;

        // Initialize all unused members of the ACMFILTERDETAILS

        // structure to zero.

        memset(&afd, 0, sizeof(afd));

        // Fill in the required members of the ACMFILTERDETAILS

        // structure for the ACM_FILTERDETAILSF_FILTER query.

        afd.cbStruct    = sizeof(afd);

        afd.dwFilterTag = pwfltr->dwFilterTag;

        afd.pwfltr      = pwfltr;

        afd.cbwfltr     = pwfltr->cbStruct;

        // Ask the ACM to find the first available driver that

        // supports the specified filter.

        mmr = acmFilterDetails(NULL, &afd, ACM_FILTERDETAILSF_FILTER);

        if (MMSYSERR_NOERROR != mmr) {

            // No ACM driver is available that supports the

            // specified filter.

            return (FALSE);

        }

        // Copy the filter attributes description into the calling

        // application's buffer.

        lstrcpy(pszFilter, afd.szFilter);

    }

    return (TRUE);

}


Producing a Dialog Box for Selecting a Filter

An application can allow users to select an arbitrary filter operation and apply it to waveform-audio data. In the following example, the application allocates a buffer to hold the filter and then uses the acmFilterChoose function to select the filter. The functions in this example must be called with the appropriate filter or filter tag.

MMRESULT        mmr;

ACMFILTERCHOOSE afc;

PWAVEFILTER     pwfltr;

DWORD           cbwfltr;

// Determine the maximum size required for any valid filter

// for which the ACM has a driver installed and enabled.

mmr = acmMetrics(NULL, ACM_METRIC_MAX_SIZE_FILTER, &cbwfltr);

if (MMSYSERR_NOERROR != mmr) {

    // The ACM probably has no drivers installed and

    // enabled for filter operations.

    return (mmr);

}

// Dynamically allocate a structure large enough to hold the

// maximum sized filter enabled in the system.

pwfltr = (PWAVEFILTER)LocalAlloc(LPTR, (UINT)cbwfltr);

if (NULL == pwfltr) {

    return (MMSYSERR_NOMEM);

}

// Initialize the ACMFILTERCHOOSE members.

memset(&afc, 0, sizeof(afc));

afc.cbStruct    = sizeof(afc);

afc.fdwStyle    = 0L;               // no special style flags

afc.hwndOwner   = hwnd;             // hwnd of parent window

afc.pwfltr      = pwfltr;           // wfltr to receive selection

afc.cbwfltr     = cbwfltr;          // size of wfltr buffer

afc.pszTitle    = TEXT("Any Filter Selection");

// Call the ACM to bring up the filter-selection dialog box.

mmr = acmFilterChoose(&afc);

if (MMSYSERR_NOERROR == mmr) {

    // The user selected a valid filter. The pwfltr buffer,

    // allocated above, contains the complete filter description.

}

// Clean up and exit.

LocalFree((HLOCAL)pwfltr);

return (mmr);


Producing a Dialog Box for Selecting a Specific Type of Format

You might want an application to allow the user to select a format from a restricted list of formats in a dialog box. Restrictions might limit the number of channels, the sampling rate, the waveform-audio format tag, or the number of bits per sample. In all of these cases, you can generate the list by using the acmFormatChoose function, setting the fdwEnum and pwfxEnum members of the ACMFORMATCHOOSE structure. The following example illustrates this process.

MMRESULT            mmr;

ACMFORMATCHOOSE     afc;

WAVEFORMATEX        wfxSelection;

WAVEFORMATEX        wfxEnum;

// Initialize the ACMFORMATCHOOSE members.

memset(&afc, 0, sizeof(afc));

afc.cbStruct    = sizeof(afc);

afc.fdwStyle    = 0L;               // no special style flags

afc.hwndOwner   = hwnd;             // hwnd of parent window

afc.pwfx        = &wfxSelection;    // wfx to receive selection

afc.cbwfx       = sizeof(wfxSelection);

afc.pszTitle    = TEXT("16 Bit PCM Selection");

//  Request that all 16-bit PCM formats be displayed for the user

//  to select from.

memset(&wfxEnum, 0, sizeof(wfxEnum));

wfxEnum.wFormatTag = WAVE_FORMAT_PCM;

wfxEnum.wBitsPerSample = 16;

afc.fdwEnum = ACM_FORMATENUMF_WFORMATTAG |

    ACM_FORMATENUMF_WBITSPERSAMPLE;

afc.pwfxEnum = &wfxEnum;

mmr = acmFormatChoose(&afc);

if ((MMSYSERR_NOERROR != mmr) && (ACMERR_CANCELED != mmr))

{

    // There was a fatal error in bringing up the list

    // dialog box (probably invalid input parameters).

}


Producing a Dialog Box for Selecting Restricted Formats

You might want to use the dialog box created by the acmFormatChoose function, but limit or control the formats in the dialog box. You can do this by using the ACMFORMATCHOOSE_STYLEF_ENABLEHOOK flag to hook the dialog procedure. The application can then filter the formats by responding to the MM_ACM_FORMATCHOOSE message in the message procedure for the dialog box.


Producing a Dialog Box for Selecting a Format for Saving

You might want an application to save existing waveform-audio data in another format. For example, a waveform-audio editor could save a waveform-audio file as a compressed file. To list only the suggested destination formats for a specified source format in the dialog box created by the acmFormatChoose function, specify the source format in the pwfxEnum member and the ACM_FORMATENUMF_SUGGEST flag in the fdwEnum member of the ACMFORMATCHOOSE structure.

Similarly, to list valid destination formats for a specified format, use the ACM_FORMATENUMF_CONVERT flag instead of the ACM_FORMATENUMF_SUGGEST flag.


Producing a Dialog Box for Selecting a Format for Recording

An application can allow the user to select a format for which an installed waveform-audio device provides native support. For example, you might want a waveform-audio editor to record new waveform-audio data without using an ACM compressor or decompressor to provide a translation layer. To do this, use the acmFormatChoose function, specifying the ACM_FORMATENUMF_HARDWARE and ACM_FORMATENUMF_INPUT flags in the fdwEnum member of the ACMFORMATCHOOSE structure.


Converting Data from One Format to Another

The ACM uses stream functions to support data format conversion. Converters in the ACM change the format, but not the data type. For example, a converter module can change 44-kHz, 16-bit data to 44-kHz, 8-bit data.

The following ACM functions support data format conversion. They are listed in the order in which you would typically use them.

•	The acmStreamOpen function opens a conversion stream.

•	The acmStreamSize function calculates the appropriate size of the source or destination buffer.

•	The acmStreamPrepareHeader function prepares source and destination buffers to be used in a conversion.

•	The acmStreamConvert function converts data in a source buffer into the destination format, writing the converted data into the destination buffer.

•	The acmStreamUnprepareHeader function cleans up the source and destination buffers prepared by acmStreamPrepareHeader. You must call this function before freeing the source and destination buffers.

•	The acmStreamClose function closes a conversion stream.

When converting data, first identify the source format, then choose the destination format. The easiest way to do this is by using the acmFormatChoose function, which displays a format-selection dialog box and returns the user’s format choice.

When you know the source and destination formats, you can use acmStreamOpen to open a conversion stream. Then you can use the acmStreamSize function to determine the appropriate buffer sizes.

The next step is to prepare the buffers to be used in the conversion by using acmStreamPrepareHeader.

To perform the conversion, use acmStreamConvert until all the buffers have been processed. When the conversion is complete, use acmStreamUnprepareHeader to clean up the buffers and then use acmStreamClose to close the conversion stream.


Multistep Format Conversion

Sometimes the ACM cannot convert data from one format to another in a single step. For example, an application might need to convert 16-bit, 44-kHz stereo data to 11-kHz mono ADPCM. If the compressor or decompressor cannot do this conversion directly, the application might attempt it in two steps. This usually means making one conversion between two PCM formats, then another conversion to the final format type.

To convert in two steps, use the acmFormatSuggest function to find a PCM format that matches the ADPCM format. Then use two conversion streams to perform the conversion. For example, perform one conversion from 16-bit, 44-kHz stereo PCM to 16-bit, 11-kHz mono, then convert from 16-bit, 11-kHz mono to 11-kHz mono ADPCM.

Multistep conversion also happens when either the source or the destination format is not PCM. If the source format is not PCM, it should be changed to a PCM format before conversion. If the destination format is not PCM, the source must be converted to an intermediate PCM format and then converted to the final destination format.

The most straightforward conversions occur when the source and destination formats are both PCM formats. When either the source or destination format is not PCM, the conversion might require an additional step. If both source and destination formats are not PCM, the conversion will usually require more than one step, and, in some instances, conversion might not be possible.


Finding a Specific Format

An application might have only a partial specification for a format when it needs the full specification. For example, the specification might stipulate an 11-kHz mono, 4-bit ADPCM format, but not the average bytes per second. The application can get the full format without user intervention by using the acmFormatEnum function and specifying flags in the fdwEnum parameter.


Finding a Specific Driver

You might want your application to send a message directly to a specific driver or to identify certain drivers from the list. For example, you might want your application to identify those drivers that support filters and then query each driver to determine which filter tags it supports. You can use the acmDriverEnum function to obtain a handle to the desired driver or drivers; this handle can then be used to communicate with that driver.

Note that when an application installs a local driver for its own use, the acmDriverAdd function returns a driver handle, which can be used to communicate with the driver. It is not necessary to use acmDriverEnum in this case.


Adding Drivers Within an Application

If you need your application to implement its own compression routines internally, the application can add drivers to the ACM by calling the acmDriverAdd function. The application implements the driver by providing a function that conforms to the acmDriverProc prototype. After the application has added the driver, the application can use the driver through the ACM as it would use any other driver.

The ACM treats drivers as either global or local. An application specifies whether a driver should be added as global or local when it calls acmDriverAdd. There are two differences between global and local drivers:

•	Drivers added as global drivers are not shared with other applications.

•	An application can directly alter the priority of a global driver (but not a local driver) by calling the acmDriverPriority function. The ACM conducts a prioritized search when seeking an appropriate driver to provide an implementation of a function call. The ACM always gives local drivers higher priority than global drivers. The most recently added local driver has highest priority.


Generating a Nonstandard Format

Sometimes an application needs a nonstandard format. For example, an application might need a 16-kHz ADPCM-format file. Because 16 kHz is nonstandard, the enumeration functions will not generate this format. In fact, short of custom coding the format algorithms into the application, there is no reliable way to generate a nonstandard format. It is sometimes possible, however, to generate an analogous format by setting up a valid PCM format with all the required information and then using the acmFormatSuggest function. Because compressors and decompressors try to suggest a format that is closest to the desired format, the number of channels and frequency are usually preserved.


Audio Compression Manager Reference

This section describes the functions, structures, and messages associated with the ACM. These elements are grouped as follows.

Drivers

acmDriverAdd
acmDriverClose
ACMDRIVERDETAILS
acmDriverEnum
acmDriverEnumCallback
acmDriverID
acmDriverMessage
acmDriverOpen
acmDriverPriority
acmDriverProc
acmDriverRemove

Filters

ACMFILTERCHOOSE
acmFilterChooseHookProc
ACMFILTERDETAILS
acmFilterEnum
acmFilterEnumCallback
ACMFILTERTAGDETAILS
acmFilterTagEnum
acmFilterTagEnumCallback

Formats

ACMFORMATCHOOSE
acmFormatChooseHookProc
ACMFORMATDETAILS
acmFormatEnum
acmFormatEnumCallback
acmFormatSuggest
ACMFORMATTAGDETAILS
acmFormatTagEnum
acmFormatTagEnumCallback

Messages

MM_ACM_FILTERCHOOSE
MM_ACM_FORMATCHOOSE

Streams

acmStreamClose
acmStreamConvert
acmStreamConvertCallback
ACMSTREAMHEADER
acmStreamMessage
acmStreamOpen
acmStreamPrepareHeader
acmStreamReset
acmStreamSize
acmStreamUnprepareHeader

Miscellaneous

acmGetVersion
acmMetrics


Audio Compression Functions

The following functions are used with audio compression.

acmDriverAdd
acmDriverClose
acmDriverDetails
acmDriverEnum
acmDriverEnumCallback
acmDriverID
acmDriverMessage
acmDriverOpen
acmDriverPriority
acmDriverProc
acmDriverRemove
acmFilterChoose
acmFilterChooseHookProc
acmFilterDetails
acmFilterEnum
acmFilterEnumCallback
acmFilterTagDetails
acmFilterTagEnum
acmFilterTagEnumCallback
acmFormatChoose
acmFormatChooseHookProc
acmFormatDetails
acmFormatEnum
acmFormatEnumCallback
acmFormatSuggest
acmFormatTagDetails
acmFormatTagEnum
acmFormatTagEnumCallback
acmGetVersion
acmMetrics
acmStreamClose
acmStreamConvert
acmStreamConvertCallback
acmStreamMessage
acmStreamOpen
acmStreamPrepareHeader
acmStreamReset
acmStreamSize
acmStreamUnprepareHeader


Audio Compression Structures

The following structures are used with audio compression.

ACMDRIVERDETAILS
ACMFILTERCHOOSE
ACMFILTERDETAILS
ACMFILTERTAGDETAILS
ACMFORMATCHOOSE
ACMFORMATDETAILS
ACMFORMATTAGDETAILS
ACMSTREAMHEADER


Audio Compression Messages

The following messages are used with audio compression.

MM_ACM_FILTERCHOOSE
MM_ACM_FORMATCHOOSE


Musical Instrument Digital Interface (MIDI)

The Musical Instrument Digital Interface (MIDI) is a protocol and set of commands for storing and transmitting information about music. MIDI output devices interpret this information and use it to synthesize music.


About MIDI

The Microsoft Win32 application programming interface (API) provides the following methods for applications to work with MIDI data:

•	The Media Control Interface (MCI). Although the simplest way to play a MIDI file is to use the MCIWnd window class, you can also use MCI commands to create a customized interface to a MIDI device. For more information about the MCIWnd window class, see MCIWnd Window Class. For more information about MCI, see MCI, or Media Control Interface (MCI).

•	Stream buffers. This format allows an application to manipulate buffers of time-stamped MIDI data for playback. Stream buffers are useful to applications that require more precise control over output than MCI offers.

•	MIDI services. Applications that need the most precise control of MIDI data typically use these low-level services.

This overview discusses each of these methods and provides an overview of the the MIDI Mapper.


The MIDI Mapper

The MIDI Mapper’s standard patch services provide device-independent MIDI file playback for applications. The MIDI Mapper can be used with the MCI MIDI sequencer or with low-level MIDI output services.


MIDI Notational Conventions

Unless stated otherwise, all references to MIDI channel numbers use the logical channel numbers 1 through 16. These logical channel numbers correspond to the physical channel numbers 0 through 15 that are actually part of the MIDI message. All references to MIDI program-change and key values use the physical values 0 through 127. All numbers are decimal unless preceded by 0x prefix, in which case they are hexadecimal.

In the discussion of the MIDI Mapper, the term source refers to the input side of the MIDI Mapper. The term destination refers to the output side of the MIDI Mapper. For example, a source channel is the MIDI channel of a message sent to the MIDI Mapper, and a destination channel is the MIDI channel of a message sent from the MIDI Mapper to an output device.


The MIDI Mapper and Windows

The MIDI Mapper is part of the system software. The following illustration shows how the MIDI Mapper relates to other elements of the audio services.

From the viewpoint of an application, the MIDI Mapper looks like another MIDI output device. The MIDI Mapper receives messages sent to it by the low-level MIDI output functions midiOutShortMsg and midiOutLongMsg. The MIDI Mapper modifies these messages and redirects them to a MIDI output device according to the current MIDI setup map. The current MIDI setup map is selected by the user by means of the MIDI Control Panel option. Only the user can select the current setup map; applications cannot change the current setup map.


The MIDI Mapper Architecture

The MIDI Mapper uses a MIDI setup map to determine how to translate and redirect the messages it receives. A MIDI setup map consists of the following types of maps.

•	Channel map

•	Patch map

•	Key map

The following illustration shows the roles of channel, patch, and key maps in a MIDI setup map.


The Channel Map

The channel map affects all MIDI channel messages. MIDI channel messages include note-on, note-off, polyphonic-key-aftertouch, control-change, program-change, channel-aftertouch, and pitch-bend-change messages. The MIDI Mapper uses a single channel map with an entry for each of the 16 MIDI channels. Each channel-map entry specifies the following:

•	A destination channel for the MIDI message

•	A destination output device for the MIDI message

•	An optional patch map specifying other possible modifications for the MIDI message

The destination channel is set to one of the 16 MIDI channels. MIDI messages are modified to reflect each new channel assignment. For example, if the destination channel entry for MIDI channel 4 is set to 6, all MIDI messages sent to channel 4 will be mapped to channel 6, as shown in the following illustration.

In this example, the MIDI status byte 0x93 is mapped to 0x95. The low-order of a MIDI status byte specifies the channel number. Source channels are set to either active or inactive. Messages sent to inactive source channels are ignored, so an inactive channel is in effect muted or turned off.

The destination output device is set to one of the available MIDI output devices. A MIDI output device can be an internal synthesizer or a physical MIDI output port.

MIDI system messages are MIDI messages (with status bytes) from 0xF0 to 0xFF. There is no channel associated with MIDI system messages, so they cannot be mapped. MIDI system messages are sent to all MIDI output devices listed in a channel map.


Patch Maps

Each channel map entry can have an associated patch map. Patch maps affect MIDI program-change and volume-controller messages. Program-change messages tell a synthesizer to change the instrument sound (patch) for a specified channel. Volume-controller messages set the volume for a channel.

A patch map has a translation table with an entry for each of the 128 program-change values. Each patch map specifies the following:

•	A destination program-change value

•	A volume scalar

•	An optional key map

When program-change messages are received by the MIDI Mapper, the destination program-change value is substituted for the program-change value in the message. For example, if the destination program-change value for program-change 16 is 18, the MIDI Mapper modifies the MIDI program-change message as shown in the following illustration.


The Volume Scalar

The purpose of the volume scalar is to allow adjustments between the relative output levels of different patches on a synthesizer. For example, if the bass patch on a synthesizer is too loud compared with its piano patch, you can change the setup map to scale the bass volume down or the piano volume up.

The volume scalar specifies a percentage value for changing all MIDI main-volume controller messages that follow an associated program-change message. For example, if the volume scalar value is 50%, the MIDI Mapper modifies MIDI main-volume controller messages as shown in the following illustration:


Key Maps

Each entry in the patch-map translation table can have an associated key map. Key maps affect note-on, note-off, and polyphonic-key-aftertouch messages. A key map has a translation table with an entry for each of the 128 MIDI key values. For example, if the entry for key value 60 is 72, the MIDI Mapper modifies MIDI note-on messages as shown in the following illustration.

Key maps are useful with synthesizers that have key-based percussion instruments with a particular percussion sound assigned to each key. Key maps are usually assigned to the first patch in the patch maps on the percussion channels (10 and 16).


Summary of Maps and MIDI Messages

Following are the status bytes for MIDI messages and the map types that affect each message.

MIDI status	Description	Map types
0x80−0x8F	Note off	Channel maps, key maps
0x90−0x9F	Note on	Channel maps, key maps
0xA0−0xAF	Polyphonic-key aftertouch	Channel maps, key maps
0xB0−0xBF	Control change	Channel maps, patch maps
0xC0−0xCF	Program change	Channel maps, patch maps
0xD0−0xDF	Channel aftertouch	Channel maps
0xE0−0xEF	Pitch-bend change	Channel maps
0xF0−0xFF	System	Not mapped
•	The high-order four bits represent the status value. The low-order four bits represent the channel information.

•	Patch maps affect only controller 7 (main volume).

•	System messages are sent to all devices listed in a channel map.


Media Control Interface (MCI)

The MCI MIDI sequencer is the MCI system component that plays MIDI files. Applications can play MIDI files easily using MCI, but MCI imposes the following restrictions on MIDI capabilities:

•	MCI supports MIDI output only.

•	MCI does not allow close synchronization between MIDI events and other real-time events (such as video).

If you need accurate MIDI synchronization, you must use the stream buffers or the MIDI services. If you need MIDI input capabilities, you must use the MIDI services.

The MCI MIDI sequencer plays standard MIDI files and resource interchange file format (RIFF) MIDI files, known as RMID files. Standard MIDI files conform to the Standard MIDI Files 1.0 specification. Because RMID files are standard MIDI files with a RIFF header, information about standard MIDI files also applies to RMID files. For more information about RIFF files, see File Input and Output.

Although there are currently three kinds of standard MIDI files, the MCI sequencer plays only two of them: Format 0 and Format 1 MIDI files.

For more information about controlling multimedia devices (including sequencers) using MCI commands, see MCI.


Stream Buffers

Applications can use stream buffers to send streams of MIDI events to a device. Each stream buffer is a block of memory pointed to by a MIDIHDR structure. This block of memory contains data for one or more MIDI events, each of which is defined by a MIDIEVENT structure. An application controls the buffer by calling the stream-manipulation functions, such as midiStreamOpen, midiStreamOut, and midiStreamClose.


Stream Buffer Format

The lpData member of the MIDIHDR structure points to a stream buffer, and the dwBufferLength member specifies the actual size of this buffer. The dwBytesRecorded member of MIDIHDR specifies the number of bytes in the buffer that are actually used by the MIDI events; this value must be less than or equal to the value specified by dwBufferLength.

Each of the MIDI events in the stream buffer is specified by a MIDIEVENT structure, which contains the time for the event, a stream identifier, an event code, and, when appropriate, parameters for the event. Each of these MIDIEVENT structures must begin on a doubleword boundary. If necessary, pad bytes must be added to the end of the structure to ensure that the next one starts on a doubleword boundary.


Timing Information

Timing information for a MIDI event is stored in the dwDeltaTime member of the MIDIEVENT structure. Time is given in ticks, as defined in the Standard MIDI Files 1.0 specification. The length of a tick is defined by the time format and possibly the tempo associated with the stream. For more information about streams, see MIDI Streams.

A tick is expressed either as microseconds per quarter note or as ticks of SMPTE (Society of Motion Picture and Television Engineers) time. Applications that send MIDI messages individually or use unprocessed MIDI messages use quarter note time and tempo information to determine the duration of a tick. Applications that preprocess MIDI messages can store the elapsed time as a count of the SMPTE units being used.

Quarter note time is indicated with a zero in the high-word bit (bit 15) of the time-division word. The remainder of the word contains the ticks per quarter note. A tempo associated with a stream of MIDI data is kept in units (microseconds per quarter note) consistent with the Standard MIDI Files 1.0 specification. For example, a quarter note in 4/4 time that uses a tempo of 500,000 microseconds per quarter note plays at the rate of 120 beats per minute.

SMPTE time division formats completely specify the length of a tick without the need for tempo information. In using SMPTE time formats, MIDI sequences can be synchronized with other SMPTE events, such as video or striped audio. SMPTE time is indicated with a 1 in the high-order bit (bit 15) of the time-division word. The rest of the most-significant byte specifies the SMPTE format in use as negative values. The supported SMPTE formats and their corresponding values (in parentheses) are 24 (-24), 25 (-25), 30 (-30), and 30 drop (-29). The low byte of the time-division word specifies the number of ticks per SMPTE frame.


Event Types

The dwEvent member of the MIDIEVENT structure describes the MIDI event that is to take place. Short events fit entirely into this member. Long events require one or more doubleword values in addition to the dwEvent member to store the event descriptions.

The high byte of the dwEvent member contains information about whether the event is long or short and about whether a callback is generated along with the event. In addition, this byte is used to describe the event type. The remaining 24 bits of the dwEvent member are used either to contain the event parameters (for short messages) or to contain the length of the event parameters (for long messages). To extract information from the dwEvent member, use the MEVT_EVENTTYPE and MEVT_EVENTPARM macros.

For a description of the predefined event types, see the reference material for the MIDIEVENT structure.


MIDI Streams

MIDI events occur in the context of a stream of MIDI data. Although an application can use several streams to define musical data, the MIDI mapper does not recognize multiple streams. Most applications that use streams use a single MIDI stream.

The following functions work with streams:

midiStreamClose	Closes a MIDI stream.
midiStreamOpen	Opens a MIDI stream and retrieves a handle.
midiStreamOut	Plays or queues a stream (buffer) of MIDI data to a MIDI output device.
midiStreamPause	Pauses playback of a specified MIDI stream.
midiStreamPosition	Retrieves the current position in a MIDI stream.
midiStreamProperty	Sets and retrieves stream properties.
midiStreamRestart	Restarts playback of a paused MIDI stream.
midiStreamStop	Turns off all notes on all MIDI channels for the specified MIDI stream.


MIDI Services

Most applications will be able to use the MCI MIDI sequencer or stream buffers (and the midiStreamOut function) to implement all the MIDI functionality they need. Serious MIDI developers — those producing MIDI authoring or sequencing tools — can use either a combination of the stream capabilities and the MIDI services or use only the MIDI services. This section presents general information about using the MIDI services.


Querying MIDI Devices

Before playing or recording MIDI data, you must determine the capabilities of the MIDI hardware present in the system. MIDI capability can vary from one multimedia computer to the next; applications should not make assumptions about the hardware present in a given system.

Windows provides the following functions to determine how many MIDI devices are available for input or output in a given system:

midiInGetNumDevs	Retrieves the number of MIDI input devices present in the system.
midiOutGetNumDevs	Retrieves the number of MIDI output devices present in the system.
Like other audio devices, MIDI devices are identified by a device identifier, which is determined implicitly from the number of devices present in a given system. Device identifiers range from zero to the number of devices present, minus one. For example, if there are two MIDI output devices in a system, valid device identifiers are 0 and 1.

After you determine how many MIDI input or output devices are present in a system, you can inquire about the capabilities of each device. Windows provides the following functions to determine the capabilities of audio devices:

midiInGetDevCaps	Retrieves the capabilities of a given MIDI input device and places this information in the MIDIINCAPS structure.
midiOutGetDevCaps	Retrieves the capabilities of a given MIDI output device and places this information in the MIDIOUTCAPS structure.
Each of these functions has a parameter specifying the address of a structure that the function fills with information about the capabilities of a specified device.


Opening and Closing Device Drivers

You must open a MIDI device before using it, and you should close the device as soon as you finish using it. Windows provides the following functions to open and close different types of MIDI devices:

midiInClose	Closes a specified MIDI input device.
midiInOpen	Opens a specified MIDI input device for recording.
midiOutClose	Closes a specified MIDI output device.
midiOutOpen	Opens a MIDI output device for playback.
Each function that opens a MIDI device takes as parameters a device identifier, an address of a memory location, and some parameters unique to MIDI devices. The memory location is filled with a device handle, which is used to identify the open audio device in calls to other audio functions.

Many MIDI functions can accept either a device handle or a device identifier. Although you can use a device handle wherever you would use a device identifier, you cannot always use a device identifier when a handle is called for.

Note  MIDI devices are not necessarily shareable, so a particular device may not be available when a user requests it. If this happens, the application should notify the user and allow the user to try to open the device again.


Allocating and Preparing MIDI Data Blocks

The midiOutLongMsg, midiInAddBuffer, and midiStreamOut functions require that applications to allocate data blocks to pass to the device drivers for playback or recording purposes. Each of these functions uses a MIDIHDR structure to describe its data block.

Before you use one of these functions to pass a data block to a device driver, you must allocate memory for the buffer and the header structure that describes the data block.

Windows provides the following functions for preparing and cleaning up MIDI data blocks:

midiInPrepareHeader	Prepares a MIDI input data block.
midiInUnprepareHeader	Cleans up the preparation of a MIDI input data block.
midiOutPrepareHeader	Prepares a MIDI output data block.
midiOutUnprepareHeader	Cleans up the preparation of a MIDI output data block.
Before you pass a MIDI data block to a device driver, you must prepare the buffer by passing it to the midiInPrepareHeader or midiOutPrepareHeader function. When the device driver is finished with the buffer and returns it, you must clean up this preparation by passing the buffer to the midiInUnprepareHeader or midiOutUnprepareHeader function before any allocated memory can be freed.


Managing MIDI Data Blocks

Applications that use data blocks for passing system-exclusive messages (using the midiOutLongMsg and midiInAddBuffer functions) and stream buffers (using the midiStreamOut function) must continually supply the device driver with data blocks until playback or recording is complete.

Even if a single data block is used, an application must be able to determine when a device driver is finished with the data block so it can free the memory associated with the data block and header structure. Three methods can be used to determine when a device driver is finished with a data block:

•	Specify a callback function to receive a message sent by the driver when it is finished with a data block. To get time-stamped MIDI input data, you must use a callback function.

•	Use an event callback (for output only).

•	Use a window or thread callback to receive a message sent by the driver when it is finished with a data block.

If an application does not get a data block to the device driver when it is needed, an audible gap in playback or a loss of incoming recorded information can occur. At a minimum, an application should use a double-buffering scheme to stay at least one data block ahead of the device driver.

Using a Callback Function to Process Driver Messages

You can write your own callback function to process messages sent by the device driver. To use a callback function, specify the CALLBACK_FUNCTION flag in the dwFlags parameter and the address of the callback function in the dwCallback parameter of the midiInOpen or midiOutOpen function.

Messages sent to a callback function are similar to messages sent to a window, except they have two doubleword parameters instead of an unsigned integer parameter and a doubleword parameter. For more information about these messages, see Sending System-Exclusive Messages and Managing MIDI Recording.

Use one of the following techniques to pass instance data from an application to a callback function:

•	Use the dwCallbackInstance parameter of the function that opens the device driver.

•	Use the dwUser member of the MIDIHDR structure that identifies a data block being sent to a MIDI device driver.

If you need more than 32 bits of instance data, pass an address of a structure containing the additional information.

Using an Event Callback to Process Driver Messages

To use an event callback, use the CreateEvent function to retrieve the handle of an event and specify CALLBACK_EVENT in the call to the midiOutOpen function.

An event callback is set by anything that might cause a function callback. Unlike callback functions and window or thread callbacks, event callbacks do not receive specific close, done, or open notifications. Therefore, an application may have to check the status of the process it is waiting for after the event occurs.

For more information about event callbacks, see Using an Event Callback to Manage Buffered Playback.

Using a Window or Thread Callback to Process Driver Messages

To use a window callback, specify the CALLBACK_WINDOW flag in the dwFlags parameter and a window handle in the low-order word of the dwCallback parameter of the midiInOpen or midiOutOpen function. Driver messages will be sent to the window procedure function for the window identified by the handle in dwCallback.

Similarly, to use a thread callback, specify the CALLBACK_THREAD flag and a thread identifier in the call to midiInOpen or midiOutOpen. In this case, messages will be posted to the specified thread instead of to a window.

Messages sent to a window or thread callback are specific to the MIDI device used. For more information about these messages, see Sending System-Exclusive Messages and Managing MIDI Recording.


Requesting Time Formats

Windows uses the MMTIME structure to represent time in one or more different formats, including milliseconds, samples, SMPTE, and MIDI song pointer formats. The wType member specifies the time format.

The midiStreamPosition function uses the MMTIME structure. Before calling this function, you must set the wType member to indicate your requested time format. To see if the requested time format is supported, check wType after the call. If the requested time format is not supported, the time is specified in an alternate time format selected by the device driver and the wType member is changed to indicate the selected time format.

For more information about the MMTIME structure, see Multimedia Timers.


Handling Errors with MIDI Functions

MIDI audio functions return a nonzero error code. For MIDI-associated errors, the midiInGetErrorText and midiOutGetErrorText functions retrieve textual descriptions for the error codes. The application must still look at the error value itself to determine how to proceed, but it can use the error descriptions in dialog boxes to inform users of the error conditions.

The only MIDI functions that do not return error codes are the midiInGetNumDevs and midiOutGetNumDevs functions. These functions return a value of zero if no devices are present in a system or if any errors are encountered by the function.


Playing MIDI Files

You should use the MCI MIDI sequencer to play MIDI files whenever you can. If the sequencer services do not meet the needs of your application, you can manage MIDI playback by using stream buffers or the MIDI services.


MIDI Output Data Types

Windows defines the following data types for MIDI output functions:

HMIDIOUT	Handle of a MIDI output device.
MIDIHDR	Header for a block of MIDI system-exclusive or stream data.
MIDIOUTCAPS	Structure used to inquire about the capabilities of a particular MIDI output device.


Querying MIDI Output Devices

Before playing a MIDI file, you should use the midiOutGetDevCaps function to determine the capabilities of the MIDI output device that is present in the system. This function takes an address of a MIDIOUTCAPS structure, which it fills with information about the capabilities of the given device. This information includes the manufacturer and product identifiers, a product name for the device, and the version number of the device driver (specified in the wMid, wPid, szPname, and vDriverVersion members, respectively).

MIDI output devices can be either internal synthesizers or external MIDI output ports. The wTechnology member of the MIDIOUTCAPS structure specifies the technology of the device.

If the device is an internal synthesizer, additional device information is available in the wVoices, wNotes, and wChannelMask members. The wVoices member specifies the number of voices that the device supports. Each voice can have a different sound or timbre. Voices are organized into MIDI channels. The wNotes member specifies the polyphony of the device — that is, the maximum number of notes that can be played simultaneously. The wChannelMask member is a bit representation of the MIDI channels that the device responds to. For example, if the device responds to the first eight MIDI channels, wChannelMask is 0x00FF. If the device is an external output port, wVoices and wNotes are unused, and wChannelMask is set to 0xFFFF.

The dwSupport member of the MIDIOUTCAPS structure indicates whether the device driver supports volume changes, patch caching, and streaming. Volume changes are supported only by internal synthesizer devices. External MIDI output ports do not support volume changes. For information about changing volume, see Changing Internal MIDI Synthesizer Volume.


Opening MIDI Output Devices

To open a MIDI output device for playback, use the midiOutOpen function. This function opens the device associated with the specified device identifier and returns a handle of the open device by writing the handle to a specified memory location.

One of the parameters of midiOutOpen is a doubleword value. This value specifies a window or thread handle, an event handle, or the address of a callback function that is used to monitor the progress of the playback of MIDI system-exclusive data and stream buffers. Monitoring enables the application to determine when to send additional data blocks and when to free data blocks that have been sent. For more information about these methods, see Managing MIDI Data Blocks.


Sending MIDI Messages with Stream Buffers

When your application works with stream buffers, it uses the midiStreamOut function to send all (short and long) MIDI messages to the device. To specify stream data blocks, use the MIDIHDR and MIDIEVENT structures. The MIDIHDR structure contains an address of a locked data block, the data-block length, and some assorted flags. The data is stored in the form of MIDIEVENT structures. The system imposes a size limit of 64K on stream buffers.

After you use midiStreamOut to send a stream buffer of data, you must wait until the device driver is finished with the data block before freeing it. If you are sending multiple data blocks, you must monitor the completion of each data block so you know when to send additional blocks. For information about different techniques for monitoring data-block completion, see Managing MIDI Data Blocks.


Sending Individual MIDI Messages

You can work with individual MIDI messages by using the following functions:

midiOutLongMsg	Sends a buffer of MIDI data to the specified MIDI output device. Use this function to send system-exclusive messages to a MIDI device.
midiOutReset	Turns off all notes on all channels for a specified MIDI output device. Any pending system-exclusive buffers and stream buffers are marked as done and returned to the application.
midiOutShortMsg	Sends a MIDI message to a specified MIDI output device.
To send any MIDI message (except for system-exclusive messages), use midiOutShortMsg.


Sending System-Exclusive Messages

MIDI system-exclusive messages are the only MIDI messages that will not fit into a single doubleword value. System-exclusive messages can be any length. Windows provides the midiOutLongMsg function for sending system-exclusive messages to MIDI output devices. To specify MIDI system-exclusive data blocks, use the MIDIHDR structure.

After you send a system-exclusive data block using midiOutLongMsg, you must wait until the device driver is finished with the data block before freeing it. If you are sending multiple data blocks, you must monitor the completion of each data block so you know when to send additional blocks. For information about different techniques for monitoring data-block completion, see Managing MIDI Data Blocks.

Note  Any MIDI status byte other than a system-real-time message will terminate a system-exclusive message. If you are using multiple data blocks to send a single system-exclusive message, do not send any MIDI messages other than system-real-time messages between data blocks.


Using a Window or Thread to Manage Buffered Playback

The following messages can be sent to a window or thread for managing playback of MIDI system-exclusive messages or stream buffers:

MM_MOM_CLOSE	Sent when the device is closed by using the midiOutClose function.
MM_MOM_DONE	Sent when the device driver is finished with a data block sent by using the midiOutLongMsg or midiStreamOut function.
MM_MOM_OPEN	Sent when the device is opened by using the midiOutOpen function.
A wParam parameter and an lParam parameter are associated with each of these messages. The wParam parameter always specifies the handle of an open MIDI device. For MM_MOM_DONE, lParam specifies an address of a MIDIHDR structure identifying the completed data block. The lParam parameter is unused for MM_MOM_CLOSE and MM_MOM_OPEN.

The most useful message is probably MM_MOM_DONE. Unless you need to allocate memory or initialize variables, you probably do not need to process MM_MOM_OPEN and MM_MOM_CLOSE. When playback of a data block is complete, you can clean up and free the data block.


Using a Callback Function to Manage Buffered Playback

You can define your own callback function to manage buffered playback of MIDI output devices. The callback function is documented as MidiOutProc.

The following messages can be sent to the wMsg parameter of the MidiOutProc callback function.

MOM_CLOSE	Sent when the device is closed by using the midiOutClose function.
MOM_DONE	Sent when the device driver is finished with a data block sent by using the midiOutLongMsg or midiStreamOut function.
MOM_OPEN	Sent when the device is opened by using the midiOutOpen function.
These messages are similar to those sent to window procedure functions, but the parameters are different. A handle of the open MIDI device is passed as a parameter to the callback function, along with the doubleword of instance data passed by using midiOutOpen.

After the driver is finished with a data block, you can clean up and free the data block. Because of the suggested restrictions on callback functions, it is better not to do this from within the callback function.


Using an Event Callback to Manage Buffered Playback

To use an event callback, use the CreateEvent function to retrieve the handle of an event. In a call to the midiOutOpen function, specify CALLBACK_EVENT for the dwFlags parameter. After using the midiOutPrepareHeader function but before sending MIDI events to the device, create a nonsignaled event by calling the ResetEvent function, specifying the event handle retrieved by CreateEvent. Then, inside a loop that checks whether the MHDR_DONE bit is set in the dwFlags member of the MIDIHDR structure, use the WaitForSingleObject function, specifying the event handle and a time-out value of INFINITE as parameters.

An event callback is set by anything that might cause a function callback.

Because event callbacks do not receive specific close, done, or open notifications, an application may need to check the status of the process it is waiting for after the event occurs. It is possible that a number of tasks could be completed by the time WaitForSingleObject returns.


Resetting MIDI Output

The midiOutReset function turns off all notes on all MIDI channels for a specified MIDI device. Then, the function marks any pending system-exclusive buffers as done and returns them to the application. This function can be useful in an application that uses MIDI output to provide the user with the ability to reset MIDI output.

Note  Terminating a system-exclusive message without sending an EOX (end-of-exclusive) byte can cause problems for the receiving device. The midiOutReset function does not send an EOX byte when it terminates a system-exclusive message, because applications are responsible for doing this.


Changing Internal MIDI Synthesizer Volume

Windows provides the following functions to retrieve and set the volume level of internal MIDI synthesizer devices:

midiOutGetVolume	Retrieves the volume level of the specified internal MIDI synthesizer device.
midiOutSetVolume	Sets the volume level of the specified internal MIDI synthesizer device.
Not all MIDI output devices support volume changes. Some devices can support individual volume changes on both the left and right channels. For information on how to determine if a particular device supports volume changes, see Querying MIDI Output Devices.

Unless your application is designed to be a master volume-control application (provides the user with volume control for all audio devices in a system), you should open an audio device before changing its volume. You should also check the volume level before changing it and restore the volume level to its previous level as soon as possible.

Volume is specified as a doubleword value. The upper 16 bits specify the relative volume of the right channel, and the lower 16 bits specify the relative volume of the left channel.

For devices that do not support individual volume changes on both the left and right channels, the lower 16 bits specify the volume level and the upper 16 bits are ignored. Values for the volume level range from 0x0 (silence) to 0xFFFF (maximum volume) and are interpreted logarithmically. The perceived volume increase is the same when increasing the volume level from 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.


Preloading Patches with Internal MIDI Synthesizers

Some internal MIDI synthesizer devices cannot keep all of their patches loaded simultaneously. These devices must preload their patch data.

Windows provides the following functions to request that a synthesizer preload and cache specified patches:

midiOutCachePatches	Requests that an internal MIDI synthesizer device preload and cache specified melodic patches.
midiOutCacheDrumPatches	Requests that an internal MIDI synthesizer device preload and cache specified key-based percussion patches.
For information on how to determine if a particular device supports preloading patches, see Querying MIDI Output Devices.


Recording MIDI Audio

To record MIDI audio data, you must use the MIDI input functions. MCI does not provide a device handler for recording MIDI audio.


MIDI Input Data Types

Windows defines the following data types for the MIDI input functions:

HMIDIIN	Handle of a MIDI input device.
MIDIHDR	Header for a stream buffer or a block of MIDI system-exclusive data. For input applications, this structure records only system-exclusive data (streaming is not supported for MIDI input).
MIDIINCAPS	Structure used to inquire about the capabilities of a MIDI input device.


Querying MIDI Input Devices

Before recording MIDI audio, you should use the midiInGetDevCaps function to determine the capabilities of the MIDI input device that is present in the system. This function takes an address of a MIDIINCAPS structure, which it fills with information about the capabilities of the given device. This information includes the manufacturer and product identifiers, a product name for the device, and the version number of the device driver.


Opening MIDI Input Devices

To open a MIDI input device for recording, use the midiInOpen function. This function opens the device associated with the specified device identifier and returns a handle of the open device by writing the handle to a specified memory location.

If you use the MIDI_IO_STATUS flag with midiInOpen, the system uses the MIM_MOREDATA message to alert your application’s callback function when it is not processing MIDI data fast enough to keep up with the input device driver. (The MM_MIM_MOREDATA message does the same job with window callbacks. However, for performance reasons, most applications will use callback functions instead of window callbacks.) If your application processes MIDI data in a separate thread, boosting the thread’s priority can have a significant impact on the application’s ability to keep up with the data flow.


Managing MIDI Recording

After you open a MIDI device, you can begin recording MIDI data. Windows provides the following functions for managing MIDI recording:

midiInAddBuffer	Sends a buffer to the device driver so it can be filled with recorded system-exclusive MIDI data.
midiInReset	Stops MIDI recording and marks all pending buffers as done.
midiInStart	Starts MIDI recording and resets the time stamp to zero.
midiInStop	Stops MIDI recording.
To send buffers to the device driver for recording system-exclusive messages, use midiInAddBuffer. The application is notified as the buffers are filled with system-exclusive recorded data. For more information about the notification techniques, see Managing MIDI Data Blocks.

The midiInStart function begins the recording process. When recording system-exclusive messages, send at least one buffer to the driver before starting recording. To stop recording, use midiInStop. Before closing the device by using the midiInClose function, mark any pending data blocks as being done by calling midiInReset.

Applications that require time-stamped data use a callback function to receive MIDI data. If your timing requirements are not strict, you can use a window or thread callback. However, you cannot use an event callback to receive MIDI data.

To record system-exclusive messages with applications that do not use stream buffers, you must supply the device driver with buffers. These buffers are specified by using a MIDIHDR structure.


Managing MIDI Thru

You can connect a MIDI input device directly to a MIDI output device so that when the input device receives an MIM_DATA message, the system sends a message with the same MIDI event data to the output device driver. To connect a MIDI output device to a MIDI input device, use the midiConnect function.

To achieve the best possible performance with multiple outputs, an application can choose to supply a special form of MIDI output driver, called a thru driver. Although the system allows only one MIDI output device to be connected to a MIDI input device, multiple MIDI output devices can be connected to a thru driver. An application on such a system could connect the MIDI input device to this thru device and connect the MIDI thru device to as many MIDI output devices as needed. For more information about thru drivers, see the Windows device-driver documentation.

Using Messages to Manage MIDI Recording

The following messages can be sent to a window or thread callback procedure for managing MIDI recording:

MM_MIM_CLOSE	Sent when a MIDI input device is closed by using the midiInClose function.
MM_MIM_DATA	Sent when a complete MIDI message is received. (This message is used for all MIDI messages except system-exclusive messages.)
MM_MIM_ERROR	Sent when an invalid MIDI message is received. (This message is used for all MIDI messages except system-exclusive messages.)
MM_MIM_LONGDATA	Sent when either a complete MIDI system-exclusive message is received or when a buffer has been filled with system-exclusive data.
MM_MIM_LONGERROR	Sent when an invalid MIDI system-exclusive message is received.
MM_MIM_MOREDATA	Sent when an application is not processing MIM_DATA messages fast enough to keep up with the input device driver.
MM_MIM_OPEN	Sent when a MIDI input device is opened by using the midiInOpen function.
A wParam parameter and an lParam parameter are associated with each of these messages. The wParam parameter always specifies the handle of an open MIDI device. The lParam parameter is unused for the MM_MIM_CLOSE and MM_MIM_OPEN messages.

For the MM_MIM_LONGDATA message, lpMidiHdr specifies an address of a MIDIHDR structure that identifies the buffer for system-exclusive messages. The buffer may not be completely filled, because the size of the system-exclusive messages is usually not known before being recorded and because buffers whose total size can contain the largest expected message must be allocated. To determine the amount of valid data present in the buffer, use the dwBytesRecorded member of the MIDIHDR structure.

Using a Callback Function to Manage MIDI Recording

You can define your own callback function to manage recording for MIDI input devices. The callback function is documented as MidiInProc.

The following messages can be sent to the wMsg parameter of the MidiInProc callback function:

MIM_CLOSE	Sent when the device is closed by using the midiInClose function.
MIM_DATA	Sent when a complete MIDI message is received (this message is used for all MIDI messages except system-exclusive messages).
MIM_ERROR	Sent when an invalid MIDI message is received (this message is used for all MIDI messages except system-exclusive messages).
MIM_LONGDATA	Sent when either a complete MIDI system-exclusive message is received or when a buffer has been filled with system-exclusive data.
MIM_LONGERROR	Sent when an invalid MIDI system-exclusive message is received.
MIM_MOREDATA	Sent when an application is not processing MIM_DATA messages fast enough to keep up with the input device driver.
MIM_OPEN	Sent when the MIDI input device is opened by using the midiInOpen function.
These messages are similar to those sent to window procedure functions, but the parameters are different. A handle of the open MIDI device is passed as a parameter to the callback function, along with the doubleword of instance data that was passed by using midiInOpen.

For the MIM_LONGDATA message, lpMidiHdr specifies an address of a MIDIHDR structure that identifies the buffer for system-exclusive messages. The buffer might not be completely filled. To determine the amount of valid data present in the buffer, use the dwBytesRecorded member of the MIDIHDR structure.

After the device driver is finished with a data block, you can clean up and free the data block.


Receiving Time-Stamped MIDI Messages

Because of the delay between when the device driver receives a MIDI message and the time the application receives the message, MIDI input device drivers time stamp the MIDI message with the time that the message was received. MIDI time stamps, which are defined as the time the first byte of the message was received, are specified in milliseconds. The midiInStart function resets the time stamps for a device to zero.

As stated previously, to receive time stamps with MIDI input, you must use a callback function. The dwParam2 parameter of the callback function specifies the time stamp for data associated with the MIM_DATA and MIM_LONGDATA messages.


Receiving Running-Status Messages

The Standard MIDI Files 1.0 specification allows the use of running status when a message has the same status byte as the previous message. When running status is used, the status byte of subsequent messages can be omitted. All MIDI input device drivers are required to expand messages using running status into complete messages, so that you always receive complete MIDI messages from a MIDI input device driver.


Processing MIDI Data from Two MIDI Sources

The MIDI subsystem can route MIDI messages from two data sources to a single MIDI output device for concurrent playback. For example, one source can be background music or a bass line that has been pre-recorded and stored in a file. The second source can be live data from a MIDI instrument, such as a keyboard or guitar.

Both data sources send MIDI data to a single MIDI device that is identified with one handle. Send one data stream by using the midiStreamOut function and one or more stream buffers. This data stream typically contains prerecorded data that is packed into the buffer.

Send the second data stream (typically from a MIDI instrument) asynchronously by using the midiOutShortMsg function. The running status of a stream buffer will not be adversely affected by the asynchronous calls made by the second data stream.

Each short message sent with midiOutShortMsg must be a complete MIDI message, with a status byte and the appropriate number of data bytes. If the status byte is omitted, midiOutShortMsg returns an error. (However, there is no running status with stream output.)


Creating MIDI Files

The Musical Instrument Digital Interface (MIDI) specifications are published by and are copyrighted material of the MIDI Manufacturers Association (MMA). The following list describes the specifications which are of the greatest general interest:

MIDI Detailed Specification

The MIDI Detailed Specification explains the MIDI hardware and software protocols. This is useful to those developing multimedia applications which implement MIDI support by using MIDI functions to record, edit, and/or play MIDI data.

Standard MIDI Files 1.0

The Standard MIDI Files specification defines a way to interchange time-stamped MIDI data between different applications on the same or different hardware platforms. This is useful to developers writing applications that read and parse disk files containing MIDI data and/or write MIDI data files to disk.

General MIDI System - Level 1

The General MIDI (GM) specification defines a minimum MIDI configuration of a "General MIDI System". This system consists of a specific class of MIDI playback devices and is of interest to multimedia developers who author MIDI files.  Most PC sound cards and MIDI synthesizers manufactured today are compatible with the GM specification. MIDI files which are authored to the GM specification should generally sound as they were intended to sound, no matter which GM-compatible device they are played on.

For current information, contact the MMA at the address or phone numbers listed here.

MIDI Manufacturers Association
PO Box 3173
La Habra, CA 90632-3173
Phone: (310) 947-8689
Fax: (310) 947-4569

To enable MIDI files to be a viable format for representing music in multimedia computing, Windows follows the General MIDI System Level 1 specification. We also provide some additional MIDI authoring guidelines:

•	Authoring Guidelines for MIDI Files

•	Standard MIDI Patch Assignments

•	Standard MIDI Key Assignments


Authoring Guidelines for MIDI Files

Follow these guidelines to author device-independent MIDI files for Windows:

•	Use the standard MIDI patch assignments and key assignments.

•	Always send a program-change message to a channel to select a patch before sending other messages to that channel. For the two percussion channels (10 and 16), select program number 0.

•	Always follow a MIDI program-change message with a MIDI main-volume controller message (controller number 7) to set the relative volume of the patch.

•	Use a value of 80 (0x50) for the main-volume controller for normal listening levels. For quieter or louder levels, you can use lower or higher values.

•	Use only the following MIDI messages: note-on with velocity, note-off, program change, pitch bend, main volume (controller 7), and damper pedal (controller 64). Internal synthesizers are required to respond to these messages and most MIDI musical instruments respond to them as well.


Standard MIDI Patch Assignments

The standard MIDI patch assignments for authoring MIDI files for use with Windows are based on the MIDI Manufacturers Association (MMA) General MIDI Mode specification. Following are the standard MIDI patch assignments.

Piano	Chromatic Percussion	Organ
0 Acoustic grand piano	8 Celesta	16 Hammond organ
1 Bright acoustic piano	9 Glockenspiel	17 Percussive organ
2 Electric grand piano	10 Music box	18 Rock organ
3 Honky-tonk piano	11 Vibraphone	19 Church organ
4 Rhodes piano	12 Marimba	20 Reed organ
5 Chorused piano	13 Xylophone	21 Accordion
6 Harpsichord	14 Tubular bells	22 Harmonica
7 Clavinet	15 Dulcimer	23 Tango accordion
Guitar	Bass	Strings
24 Acoustic guitar (nylon)	32 Acoustic bass	40 Violin
25 Acoustic guitar (steel)	33 Electric bass (finger)	41 Viola
26 Electric guitar (jazz)	34 Electric bass (pick)	42 Cello
27 Electric guitar (clean)	35 Fretless bass	43 Contrabass
28 Electric guitar (muted)	36 Slap bass 1	44 Tremolo strings
29 Overdriven guitar	37 Slap bass 2	45 Pizzicato strings
30 Distortion guitar	38 Synth bass 1	46 Orchestral harp
31 Guitar harmonics	39 Synth bass 2	47 Timpani
Ensemble	Brass	Reed
48 String ensemble 1	56 Trumpet	64 Soprano sax
49 String ensemble 2	57 Trombone	65 Alto sax
50 Synth. strings 1	58 Tuba	66 Tenor sax
51 Synth. strings 2	59 Muted trumpet	67 Baritone sax
52 Choir Aahs	60 French horn	68 Oboe
53 Voice Oohs	61 Brass section	69 English horn
54 Synth voice	62 Synth. brass 1	70 Bassoon
55 Orchestra hit	63 Synth. brass 2	71 Clarinet
Pipe	Synth Lead	Synth Pad
72 Piccolo	80 Lead 1 (square)	88 Pad 1 (new age)
73 Flute	81 Lead 2 (sawtooth)	89 Pad 2 (warm)
74 Recorder	82 Lead 3 (calliope lead)	90 Pad 3 (polysynth)
75 Pan flute	83 Lead 4 (chiff lead)	91 Pad 4 (choir)
76 Bottle blow	84 Lead 5 (charang)	92 Pad 5 (bowed)
77 Shakuhachi	85 Lead 6 (voice)	93 Pad 6 (metallic)
78 Whistle	86 Lead 7 (fifths)	94 Pad 7 (halo)
79 Ocarina	87 Lead 8 (brass + lead)	95 Pad 8 (sweep)
Sound Effects
120 Guitar fret noise
121 Breath noise
122 Seashore
123 Bird tweet
124 Telephone ring
125 Helicopter
126 Applause
127 Gunshot


Standard MIDI Key Assignments

The standard MIDI key assignments for percussion instruments are based on the MMA General MIDI Mode specification. The following illustration shows the standard key assignments for MIDI files authored for Windows.


Using MIDI

This section contains examples demonstrating how to perform the following tasks:

•	Using the MCI MIDI sequencer

•	Using midiOutShortMsg to send individual MIDI messages


Using the MCI MIDI Sequencer

Like all MCI devices, the MCI MIDI sequencer responds to standard MCI commands. This section discusses how to retrieve a sequence division type and how to retrieve and set a tempo. For more information about MCI, see MCI.


Retrieving the Sequence Division Type

The division type of a MIDI sequence determines the amount of time between MIDI events in the sequence. To determine the division type of a sequence, use the MCI_STATUS command and set the dwItem member of the MCI_STATUS_PARMS structure to MCI_SEQ_STATUS_DIVTYPE .

If the MCI_STATUS command is successful, the dwReturn member of the MCI_STATUS_PARMS structure will contain one of the following values to indicate the division type.

Value	Division type
MCI_SEQ_DIV_PPQN	PPQN (parts-per-quarter note)
MCI_SEQ_DIV_SMPTE_24	SMPTE, 24 fps (frames per second)
MCI_SEQ_DIV_SMPTE_25	SMPTE, 25 fps
MCI_SEQ_DIV_SMPTE_30	SMPTE, 30 fps
MCI_SEQ_DIV_SMPTE_30DROP	SMPTE, 30 fps drop frame
You must know the division type of a sequence to change or query its tempo. You cannot change the division type of a sequence by using the MCI sequencer.


Querying and Setting the Tempo

To retrieve the tempo of a sequence, use the MCI_STATUS command and set the dwItem member of the MCI_STATUS_PARMS structure to MCI_SEQ_STATUS_TEMPO. If the MCI_STATUS command is successful, the dwReturn member of the MCI_STATUS_PARMS structure contains the current tempo.

To change tempo, use the MCI_SET command with the MCI_SEQ_SET_PARMS structure, specifying the MCI_SEQ_SET_TEMPO flag and setting the dwTempo member of the structure to the desired tempo.

The way tempo is represented depends on the division type of the sequence. If the division type is PPQN, the tempo is represented in beats per minute. If the division type is one of the SMPTE division types, the tempo is represented in frames per second. For information about determining the division type of a sequence, see Retrieving the Sequence Division Type.


Using midiOutShortMsg to Send Individual MIDI Messages

The following example uses the midiOutShortMsg function to send a specified MIDI event to a given MIDI output device:

UINT sendMIDIEvent(HMIDIOUT hmo, BYTE bStatus, BYTE bData1,

    BYTE bData2)

{

    union {

        DWORD dwData;

        BYTE bData[4];

    } u;

    // Construct the MIDI message.

    u.bData[0] = bStatus;  // MIDI status byte

    u.bData[1] = bData1;   // first MIDI data byte

    u.bData[2] = bData2;   // second MIDI data byte

    u.bData[3] = 0;

    // Send the message.

    return midiOutShortMsg(hmo, u.dwData);

}

Note  MIDI output drivers are not required to verify data before sending it to an output port. Applications must ensure that only valid data is sent.


MIDI Reference

This section describes the functions, macros, messages, and structures associated with the Musical Instrument Digital Interface (MIDI). These elements are grouped as follows.

Allocating and Managing Buffers

MIDIHDR
midiInAddBuffer
midiInPrepareHeader
midiInUnprepareHeader
midiOutPrepareHeader
midiOutUnprepareHeader

Callback Functions

MidiInProc
MidiOutProc

Device Capabilities

MIDIINCAPS
midiInGetDevCaps
midiInGetID
midiInGetNumDevs
MIDIOUTCAPS
midiOutGetDevCaps
midiOutGetID
midiOutGetNumDevs
MIDISTRMBUFFVER

Error Processing

midiInGetErrorText
midiOutGetErrorText
MIM_ERROR
MIM_LONGERROR
MM_MIM_ERROR
MM_MIM_LONGERROR

Managing MIDI Streams

midiStreamClose
midiStreamOpen
midiStreamOut
midiStreamPause
midiStreamPosition
midiStreamProperty
midiStreamRestart
midiStreamStop

Opening and Closing Devices

midiInClose
midiInOpen
midiOutClose
midiOutOpen
MIM_CLOSE
MIM_OPEN
MM_MIM_CLOSE
MM_MIM_OPEN
MM_MOM_CLOSE
MM_MOM_OPEN
MOM_CLOSE
MOM_OPEN

Output Devices

KEYARRAY
midiOutCacheDrumPatches
midiOutCachePatches
midiOutGetVolume
midiOutSetVolume
PATCHARRAY

Playing a Message or Messages

MEVT_EVENTPARM
MEVT_EVENTTYPE
MIDIEVENT
midiOutLongMsg
midiOutReset
midiOutShortMsg
midiStreamOut
midiStreamPause
midiStreamRestart
midiStreamStop
MM_MOM_DONE
MM_MOM_POSITIONCB
MOM_DONE
MOM_POSITIONCB

Recording

midiConnect
midiDisconnect
midiInReset
midiInStart
midiInStop
MIDIPROPTEMPO
MIDIPROPTIMEDIV
MIM_DATA
MIM_LONGDATA
MIM_MOREDATA
MM_MIM_DATA
MM_MIM_MOREDATA
MM_MIM_LONGDATA

Sending Messages to Devices

midiInMessage
midiOutMessage


MIDI Functions

The following functions are used with MIDI.

midiConnect
midiDisconnect
midiInAddBuffer
midiInClose
midiInGetDevCaps
midiInGetErrorText
midiInGetID
midiInGetNumDevs
midiInMessage
midiInOpen
midiInPrepareHeader
midiInProc
midiInReset
midiInStart
midiInStop
midiInUnprepareHeader
midiOutCacheDrumPatches
midiOutCachePatches
midiOutClose
midiOutGetDevCaps
midiOutGetErrorText
midiOutGetID
midiOutGetNumDevs
midiOutGetVolume
midiOutLongMsg
midiOutMessage
midiOutOpen
midiOutPrepareHeader
MidiOutProc
midiOutReset
midiOutSetVolume
midiOutShortMsg
midiOutUnprepareHeader
midiStreamClose
midiStreamOpen
midiStreamOut
midiStreamPause
midiStreamPosition
midiStreamProperty
midiStreamRestart
midiStreamStop


MIDI Structures

The following structures are used with MIDI.

MIDIEVENT
MIDIHDR
MIDIINCAPS
MIDIOUTCAPS
MIDIPROPTEMPO
MIDIPROPTIMEDIV
MIDISTRMBUFFVER


MIDI Messages

The following messages are used with MIDI.

MIM_CLOSE
MIM_DATA
MIM_ERROR
MIM_LONGDATA
MIM_LONGERROR
MIM_MOREDATA
MIM_OPEN
MM_MIM_CLOSE
MM_MIM_DATA
MM_MIM_ERROR
MM_MIM_LONGDATA
MM_MIM_LONGERROR
MM_MIM_MOREDATA
MM_MIM_OPEN
MM_MOM_CLOSE
MM_MOM_DONE
MM_MOM_OPEN
MM_MOM_POSITIONCB
MOM_CLOSE
MOM_DONE
MOM_OPEN
MOM_POSITIONCB


MIDI Macros

The following macros are used with MIDI.

MEVT_EVENTPARM
MEVT_EVENTTYPE


MIDI Types

The following types are used with MIDI.

KEYARRAY
PATCHARRAY


Audio Mixers

This overview presents general information about using audio mixer services.


About Audio Mixers

Audio mixer services control the routing of audio lines to a destination device for playing or recording. These services can also control volume and other effects. Many of the techniques required to use these services are similar to those for audio devices discussed in other multimedia overviews.


Mixer Architecture

The basic element of the mixer architecture is an audio line. An audio line consists of one or more channels of data originating from a single source or a system resource. For example, a stereo audio line has two data channels, but it is considered a single audio line because it originates from a single source.

The mixer architecture provides routing services to manage audio lines on a computer. You can use the routing services if you have adequate hardware devices and software drivers installed. The mixer architecture allows several audio source lines to map to a single destination audio line.

Each audio line can have mixer controls associated with it. A mixer control can perform any number of functions (such as control volume), depending on the characteristics of the associated audio line.


Control Types

The mixer services include the following classes of standard controls to associate with audio lines:

•	Audio mixer custom controls

•	Faders

•	Lists

•	Meters

•	Numbers

•	Sliders

•	Switches

•	Time controls


Audio Mixer Custom Controls

Custom controls are the most generic of the mixer controls. These controls allow a mixer driver to define the control’s characteristics, and by implication, the visual representation of the control.


Faders

The fader controls are typically vertical controls that can be adjusted up or down. These controls have a linear scale and use the MIXERCONTROLDETAILS_UNSIGNED structure to retrieve and set control details. The following table describes the types of faders.

Control	Description
Fader	General fade control. The range of acceptable values is 0 through 65,535.
Volume	General volume fade control. The range of acceptable values is 0 through 65,535. For information about changing this range, see the documentation for your mixer device.
Bass	Bass volume fade control. The range of acceptable values is 0 through 65,535. The limits of the bass frequency band are hardware specific. For information about band limits, see the documentation for your mixer device.
Treble	Treble volume fade control. The range of acceptable values is 0 through 65,535. The limits of the treble frequency band are hardware specific. For information about the band limits, see the documentation for your mixer device.
Equalizer	Graphic equalizer control. The range of acceptable values for one band of the equalizer is 0 through 65,535. The number of equalizer bands and their limits are hardware specific. For information about the equalizer, see the documentation for your mixer device. You can use the MIXERCONTROLDETAILS_LISTTEXT structure to retrieve text labels for the equalizer.


Lists

The list controls provide single-select or multiple-select states for complex audio lines. These controls use the MIXERCONTROLDETAILS_BOOLEAN structure to retrieve and set control properties. The MIXERCONTROLDETAILS_LISTTEXT structure is also used to retrieve all text descriptions of a multiple-item control. The following table describes the types of list controls.

Control	Description
Single-select	Restricts the control selection to one item at a time. Unlike the multiplexer control, this control can be used to control more than audio source lines. For example, you could use this control to select a low-pass filter from a list of filters supported by a mixer device.
Multiplexer (MUX)	Restricts the line selection to one source line at a time.
Multiple-select	Allows the user to select multiple items from a list simultaneously. Unlike the mixer control, the multiple-select control can be used to control more than audio source lines.
Mixer	Allows the user to select source lines from a list simultaneously.


Meters

The meter controls measure data passing through an audio line. These controls use the MIXERCONTROLDETAILS_BOOLEAN, MIXERCONTROLDETAILS_SIGNED, and MIXERCONTROLDETAILS_UNSIGNED structures to retrieve and set control properties. The following table describes the types of meters.

Control	Description
Boolean	Measures whether an integer value is FALSE/OFF (zero) or TRUE/ON (nonzero).
Peak	Measures the deflection from 0 in both the positive and negative directions. The range of integer values for the peak meter is − 32,768 through 32,767.
Signed	Measures integer values in the range of − 231 through (231 −  1). The mixer driver defines the limits of this meter.
Unsigned	Measures integer values in the range of 0 through (232 −  1). The mixer driver defines the limits of this meter.


Numbers

The number controls allow the user to enter numerical data associated with a line. The numerical data is expressed as signed integers, unsigned integers, or integer decibel values. These controls use the MIXERCONTROLDETAILS_SIGNED and MIXERCONTROLDETAILS_UNSIGNED structures to retrieve and set control properties. The following table describes the types of number controls.

Control	Description
Signed	Allows integer values entered in the range of  − 231 through (231 −  1).
Unsigned	Allows integer values entered in the range of 0 through (232 −  1).
Decibel	Allows integer decibel values to be entered, in tenths of decibels. The range of values for this control is − 32,768 through 32,767.
Percent	Allows values to be entered as percentages.


Sliders

The slider controls are typically horizontal controls that can be adjusted to the left or right. These controls use the MIXERCONTROLDETAILS_SIGNED structure to retrieve and set control properties. The following table describes the types of sliders.

Control	Description
Slider	Has a range of  − 32,768 through 32,767. The mixer driver defines the limits of this control.
Pan	Has a range of −32,768 through 32,767. The mixer driver defines the limits of this control, with 0 as the midrange value.
QSound Pan	Provides expanded sound control through QSound. This control has a range of −15 through 15.


Switches

The switch controls are two-state switches. These controls use the MIXERCONTROLDETAILS_BOOLEAN structure to retrieve and set control properties. The following table describes the types of switches.

Control	Description
Boolean	The generic switch. It can be set to TRUE or FALSE.
Button	Set to TRUE for all buttons that the driver should handle as though they had been pressed. If the value is FALSE, no action is taken.
On/Off	An alternative switch that is represented by a graphic other than the one used for the Boolean switch. It can be set to ON or OFF.
Mute	Mutes an audio line (suppressing the data flow of the line) or allows the audio data to play. This switch is frequently used to help control the lines feeding into the mixer.
Mono	Switches between mono and stereo output for a stereo audio line. Set to OFF to play stereo data as separate channels. Set to ON to combine data from both channels into a mono audio line.
Loudness	Boosts low-volume bass for an audio line. Set to ON to boost low-volume bass. Set to OFF to set volume levels to normal. The amount of boost is hardware specific. For more information, see the documentation for your mixer device.
Stereo Enhanced	Increases stereo separation. Set to ON to increase stereo separation. Set to OFF for no enhancement.


Time Controls

The time controls allow the user to enter timing-related data, such as an echo delay or reverberation. The time data is expressed as positive integers. Types of time controls include the following:

Control	Description
Microsecond	Supports timing data expressed in microseconds. The range of acceptable values is 0 through (232 −1).
Millisecond	Supports timing data expressed in milliseconds. The range of acceptable values is 0 through (232 −1).


Mixer Device Queries

The mixer services provide functions for determining the number of mixer devices present in the system and the capabilities of the devices. You can also use a mixer services function to determine the device identifier for a mixer device.

You can use the mixerGetNumDevs function to determine how many mixer devices are present in the system. Mixer devices are identified by a device identifier. Device identifiers are determined implicitly from the number of devices present in a given system. They range from zero through one less than the number of devices present.

Before using a mixer device, you must determine its capabilities. Audio capabilities can vary from one multimedia computer to another, so applications need to work with a variety of audio hardware.

You can use the mixerGetDevCaps function to determine the capabilities of mixer devices. This function fills a MIXERCAPS structure with information about the capabilities of a specified device.

The mixerGetID function retrieves the audio mixer device identifier associated with a specified device handle. For example, you could use this function to retrieve the device identifier for an audio mixer and then use the device identifier to adjust the volume or to display another control.


Opening and Closing Mixer Devices

When you want to use a mixer device, you can either simply begin using it or you can explicitly open the device before using it. Explicitly opening a mixer device offers two main benefits:

•	It guarantees the continued existence of that mixer device.

•	It lets you receive notification of audio line and control changes.

You can use the mixerOpen function to explicitly open a mixer device. This function takes as parameters a device identifier, a pointer to a memory location, and other values unique to each type of device. The memory location is filled with a device handle. Use this device handle to identify the open mixer device when calling other audio mixer functions. As long as a handle of a mixer device exists, the device continues to exist in the system. If a configuration change occurs to the mixer device and it hasn’t been explicitly opened, your application might suddenly be unable to access it.

Note  The difference between device identifiers and device handles is important. Device handles are returned when you open a device driver by using mixerOpen. Device identifiers are determined implicitly from the number of devices present in a system; this number is obtained by using the mixerGetNumDevs function.

You can use the mixerClose function to close a mixer device. You should close the device after you finish using it.


Window Callback Services

The mixer services provide window callback services so that your application can process messages from mixer drivers. To use these services, specify the CALLBACK_WINDOW flag in the fdwOpen parameter and a window handle in the dwCallback parameter of the mixerOpen function. Driver messages are sent to the window procedure function for the window identified by the handle in dwCallback. The messages are specific to the audio device type.


Audio Line and Control Queries

The mixer services provide functions for determining information about audio lines, audio-line controls, and control details. The services also provide functions for setting control details.

You can use the mixerGetLineInfo function to retrieve information about a specified audio line. This function fills the MIXERLINE structure for a specified source audio line, destination audio line, or line identifier. The structure includes the destination line number, the number of channels in the audio line, as well as a short and a long name for the audio line.

The mixerGetLineControls function retrieves general information about one or more controls associated with an audio line. This function fills the MIXERLINECONTROLS structure with information about the specified control or controls. You can use mixerGetLineControls to retrieve control properties for one of the following:

•	All controls for a specified source line

•	A specified control for a specified source line

•	The first control of a specific class for a specified source line

The mixerGetControlDetails function retrieves properties of a single control associated with an audio line. This function fills the MIXERCONTROLDETAILS structure with the current values for a control.

The mixerSetControlDetails function uses the contents of the MIXERCONTROLDETAILS structure to set the properties of the specified control. You must ensure that all members of this structure are filled before you call mixerSetControlDetails.


Audio Mixer Reference

This section describes the functions, structures, and messages associated with audio mixers. These elements are grouped as follows.

Querying Devices

MIXERCAPS
mixerGetDevCaps
mixerGetNumDevs

Opening and Closing

mixerClose
mixerOpen

Retrieving Mixer Identifiers

mixerGetID

Retrieving Line Controls

MIXERCONTROL
mixerGetLineControls
MIXERLINECONTROLS

Changing Control Attributes

MIXERCONTROLDETAILS
MIXERCONTROLDETAILS_BOOLEAN
MIXERCONTROLDETAILS_LISTTEXT
MIXERCONTROLDETAILS_SIGNED
MIXERCONTROLDETAILS_UNSIGNED
mixerGetControlDetails
mixerSetControlDetails

Retrieving Line Information

mixerGetLineInfo
MIXERLINE
MM_MIXM_CONTROL_CHANGE
MM_MIXM_LINE_CHANGE

Sending User-Defined Messages

mixerMessage


Audio Mixer Functions

The following functions are used with audio mixers.

mixerClose
mixerGetControlDetails
mixerGetDevCaps
mixerGetID
mixerGetLineControls
mixerGetLineInfo
mixerGetNumDevs
mixerMessage
mixerOpen
mixerSetControlDetails


Audio Mixer Structures

The following structures are used with audio mixers.

MIXERCAPS
MIXERCONTROL
MIXERCONTROLDETAILS
MIXERCONTROLDETAILS_BOOLEAN
MIXERCONTROLDETAILS_LISTTEXT
MIXERCONTROLDETAILS_SIGNED
MIXERCONTROLDETAILS_UNSIGNED
MIXERLINE
MIXERLINECONTROLS


Audio Mixer Messages

The following messages are used with audio mixers.

MM_MIXM_CONTROL_CHANGE
MM_MIXM_LINE_CHANGE


Waveform Audio

This overview explains how to use the waveform and auxiliary audio services of the Microsoft Win32 application programming interface (API) to add sound to applications.


About Waveform Audio

Adding sound to your application can make it more efficient and more fun to use. You can improve your users’ efficiency by using sounds to get their attention at critical points, to help them avoid mistakes, or to let them know that a time-consuming operation has finished. You can help them have more fun by adding music or sound effects.

This overview explains how to do the following things with sound:

•	Play waveform audio.

•	Use waveform-audio services.

•	Record waveform audio.

•	Use auxiliary audio devices.

•	Use audio clipboard formats.

This overview documents several methods for adding sound to your application. The simplest method documented here is that of using the PlaySound function. Most of the other waveform-audio API elements documented in this overview are relatively low-level. However, the MCI overview documents an interface to multimedia programming that offers method of adding sound to your application that is simpler and faster than using the waveform-audio sound API.


The PlaySound Function

You can use the PlaySound function to play waveform audio, as long as the sound fits into available memory. (The sndPlaySound function offers a subset of the capabilities of PlaySound. To maximize the portability of your Win32-based application, use PlaySound, not sndPlaySound.)

The PlaySound function allows you to specify a sound in one of three ways:

•	As a system alert, using the alias stored in the WIN.INI file or the registry

•	As a filename

•	As a resource identifier

The PlaySound function allows you to play a sound in a continuous loop, ending only when you call PlaySound again, specifying either NULL or the sound identifier of another sound for the pszSound parameter.

You can use PlaySound to play the sound synchronously or asynchronously, and to control the behavior of the function in other ways when it must share system resources.

For examples of how to use PlaySound in your Win32-based applications, see Playing WAVE Resources.


Waveform-Audio Files

In the Microsoft Windows operating system, most waveform-audio files use the .WAV filename extension.

The following statement plays the C:\SOUNDS\BELLS.WAV file:

PlaySound("C:\\SOUNDS\\BELLS.WAV", NULL, SND_SYNC);

If the specified file does not exist, or if the file does not fit into the available memory, PlaySound plays the default system sound. If no default system sound has been defined, PlaySound fails without producing any sound. If you do not want the default system sound to play, specify the SND_NODEFAULT flag, as shown in the following example:

PlaySound("C:\\SOUNDS\\BELLS.WAV", NULL, SND_SYNC | SND_NODEFAULT);


Looping Sounds

If you specify the SND_LOOP and SND_ASYNC flags for the fdwSound parameter of the PlaySound function, the sound will continue to play repeatedly as shown in the following example:

PlaySound("C:\\SOUNDS\\BELLS.WAV", NULL, SND_LOOP | SND_ASYNC);

If you want to loop a sound, you must play it asynchronously; you cannot use the SND_SYNC flag with the SND_LOOP flag. A looped sound will continue to play until you call PlaySound to play another sound. To stop playing a sound (looped or asynchronous) without playing another sound, use the following statement:

PlaySound(NULL, NULL, 0);


Playing Sounds Specified in the Registry

The PlaySound function will also play sounds referred to by a keyname in the registry. This allows users to assign their own sounds to system alerts and warnings, or to user actions, such as a mouse button click. Sounds that are associated with system alerts and warnings are called sound events.

To play a sound event, call PlaySound with the pszSound parameter pointing to a string containing the name of the registry entry that identifies the sound. For example, to play the sound associated with the “MouseClick” entry and to wait for the sound to complete before returning, use the following statement:

PlaySound("MouseClick", NULL, SND_SYNC);

If the specified registry entry or the waveform-audio file it identifies does not exist, or if the file does not fit into the available memory, PlaySound plays the default system sound.

The sound events that are predefined by the system can vary with the platform. The following list gives the sound events that are defined for all implementations of the Win32 API:

SystemAsterisk

SystemExclamation

SystemExit

SystemHand

SystemQuestion

SystemStart

If an application registers its own sound events, the user can configure the sound event by using the standard Control Panel interface. The application should register the sound event by using the standard registry functions; for more information, see Registry. The entries belong at the same position in the registry hierarchy as the rest of the sound events. This position varies with the Win32 implementation. The appropriate data value also varies with the implementation.

The sndPlaySound function always searches the registry for a keyname matching lpszSound before attempting to load a file with this name. The PlaySound function accepts flags that specify the location of the sound.


Waveform-Audio Interface

This section documents the waveform-audio interface, which is used by applications that need the greatest possible control over audio devices. The functions and structures of this interface are named with the prefix “wave”.


Devices and Data Types

This section describes working with waveform-audio devices, and includes information on how to open, close and query them for their capabilities. It also describes how to keep track of the devices in a system by using device handles and device identifiers.

Opening Waveform-Audio Output Devices

Use the waveOutOpen function to open a waveform-audio output device for playback. This function opens the device associated with the specified device identifier and returns a handle of the open device by writing the handle of a specified memory location.

Some multimedia computers have multiple waveform-audio output devices. Unless you want to open a specific waveform-audio output device in a system, you should use the WAVE_MAPPER flag for the device identifier when you open a device. The waveOutOpen function chooses the device in the system that is best able to play the specified data format.

Querying Audio Devices

Windows provides the following functions to determine how many devices of a certain type are available in a system.

Function	Description
auxGetNumDevs	Retrieves the number of auxiliary output devices present in the system.
WaveInGetNumDevs	Retrieves the number of waveform-audio input devices present in the system.
WaveOutGetNumDevs	Retrieves the number of waveform-audio output devices present in the system.
Audio devices are identified by a device identifier. The device identifier is determined implicitly from the number of devices present in a system. Device identifiers range from zero to one less than the number of devices present. For example, if there are two waveform-audio output devices in a system, valid device identifiers are 0 and 1.

After you determine how many devices of a certain type are present in a system, you can use one of the following functions to query the capabilities of each device.

Function	Description
auxGetDevCaps	Retrieves the capabilities of a specified auxiliary output device.
waveInGetDevCaps	Retrieves the capabilities of a specified waveform-audio input device.
waveOutGetDevCaps	Retrieves the capabilities of a specified waveform-audio output device.
Each of these functions fills a structure with information about the capabilities of a specified device. The following table lists the structures that correspond to each of these functions.

Function	Structure
auxGetDevCaps	AUXCAPS
waveInGetDevCaps	WAVEINCAPS
waveOutGetDevCaps	WAVEOUTCAPS
Standard formats are listed in the dwFormats member of the WAVEOUTCAPS structure. Waveform-audio devices can support nonstandard formats. To determine whether a particular format (standard or nonstandard) is supported by a device, you can call the waveOutOpen function with the WAVE_FORMAT_QUERY flag. This flag does not open the device. You specify the format in question in the WAVEFORMATEX structure pointed to by the pwfx parameter passed to waveOutOpen. For information about setting up this structure, see Devices and Data Types.

Waveform-audio output devices vary in the capabilities they support. The dwSupport member of the WAVEOUTCAPS structure indicates whether a device supports such capabilities as volume and pitch changes.

Device Handles and Device Identifiers

Each function that opens an audio device specifies a device identifier, a pointer to a memory location, and some parameters that are unique to each type of device. The memory location is filled with a device handle. Use this device handle to identify the open audio device when calling other audio functions.

The difference between identifiers and handles for audio devices is subtle but important:

•	Device identifiers are determined implicitly from the number of devices present in a system. This number is obtained by using the auxGetNumDevs, waveInGetNumDevs, or waveOutGetNumDevs function.

•	Device handles are returned when device drivers are opened by using the waveInOpen or waveOutOpen function.

There are no functions that open or close auxiliary audio devices. Auxiliary audio devices need not be opened and closed like waveform-audio devices because there is no continuous data transfer associated with them. All auxiliary audio functions use device identifiers to identify devices.

Waveform-Audio Output Data Types

The following data types are defined for waveform-audio output functions.

Type	Description
HWAVEOUT	Handle to an open waveform-audio output device.
WAVEFORMATEX	Structure that specifies the data formats supported by a particular waveform-audio input device. This structure is also usedfor waveform-audio input devices.
WAVEHDR	Structure used as a header for a block of waveform-audio input data. This structure is also used for waveform-audio input devices.
WAVEOUTCAPS	Structure used to query the capabilities of a particular waveform-audio output device.
Specifying Waveform-Audio Data Formats

When you call the waveOutOpen function to open a device driver for playback or to query whether the driver supports a particular data format, use the pwfx parameter to specify a pointer to a WAVEFORMATEX structure containing the requested waveform-audio data format. The WAVEFORMATEX structure is an extended version of the WAVEFORMAT structure. It contains all the members of WAVEFORMAT, and adds two more: a wBitsPerSample member, which contains extra information required for the PCM (Pulse Code Modulation) format, and a cbSize member at the end. You can append data to the structure following cbSize as long as you fill cbSize with the size of the data. You can use the WAVEFORMATEX structure to describe PCM data, although you could also use the PCMWAVEFORMAT structure. When the waveform-audio format type is not PCM, you must use WAVEFORMATEX instead of WAVEFORMAT.

The outmoded WAVEFORMAT structure does not contain all the information required to describe the PCM format. The PCMWAVEFORMAT structure includes a WAVEFORMAT structure along with an additional member containing PCM-specific information. The PCMWAVEFORMAT structure has also been superseded by the WAVEFORMATEX structure.

There are also two clipboard formats you can use to represent audio data: CF_WAVE and CF_RIFF. Use the CF_WAVE format to represent data in one of the standard formats, such as 11 kHz or 22 kHz PCM. Use the CF_RIFF format to represent more complex data formats that cannot be represented as standard waveform-audio files.

Writing Waveform-Audio Data

After successfully opening a waveform-audio output device driver, you can begin playing a sound. Windows provides the waveOutWrite function for sending data blocks to waveform-audio output devices.

Use the WAVEHDR structure to specify the waveform-audio data block you are sending using waveOutWrite. This structure contains a pointer to a locked data block, the length of the data block, and some flags. This data block must be prepared before you use it; for information about preparing a data block, see Audio Data Blocks.

After you send a data block to an output device by using waveOutWrite, you must wait until the device driver is finished with the data block before freeing it. If you are sending multiple data blocks, you must monitor the completion of data blocks to know when to send additional blocks. For more information about data blocks, see Audio Data Blocks.

PCM Waveform-Audio Data Format

The lpData member of the WAVEHDR structure points to the waveform-audio data samples. For 8-bit PCM data, each sample is represented by a single unsigned data byte. For 16-bit PCM data, each sample is represented by a 16-bit signed value. The following table summarizes the maximum, minimum, and midpoint values for PCM waveform-audio data.

Data format	Maximum value	Minimum value	Midpoint value
8-bit PCM	255 (0xFF)	0	128 (0x80)
16-bit PCM	32,767 (0x7FFF)	− 32,768 (0x8000)	0
PCM Data Packing

The order of the data bytes varies between 8-bit and 16-bit formats and between mono and stereo formats. The following list describes data packing for the different PCM waveform-audio data formats.

PCM waveform-audio format	Description
8-bit mono	Each sample is 1 byte that corresponds to a single audio channel. Sample 1 is followed by samples 2, 3, 4, and so on.
8-bit stereo	Each sample is 2 bytes. Sample 1 is followed by samples 2, 3, 4, and so on. For each sample, the first byte is channel 0 (the left channel) and the second byte is channel 1 (the right channel).
16-bit mono	Each sample is 2 bytes. Sample 1 is followed by samples 2, 3, 4, and so on. For each sample, the first byte is the low-order byte of channel 0 and the second byte is the high-order byte of channel 0.
16-bit stereo	Each sample is 4 bytes. Sample 1 is followed by samples 2, 3, 4, and so on. For each sample, the first byte is the low-order byte of channel 0 (left channel); the second byte is the high-order byte of channel 0; the third byte is the low-order byte of channel 1 (right channel); and the fourth byte is the high-order byte of channel 1.
Closing Waveform-Audio Output Devices

After waveform-audio playback is complete, call waveOutClose to close the output device. If waveOutClose is called while a waveform-audio file is playing, the close operation fails and the function returns an error code indicating that the device was not closed. If you do not want to wait for playback to end before closing the device, call the waveOutReset function before closing. This ends playback and allows the device to be closed. Be sure to use the waveOutUnprepareHeader function to clean up the preparation on all data blocks before closing the device.


Playing Waveform-Audio Files

It’s easy to play sounds in your application by using the functions, macros, and messages discussed in this overview. The techniques and elements documented here operate only on waveform audio; that is, digitized representations of a sound’s physical shape. If you want to add music to your application, and you do not care about other kinds of sounds, you might want to use MIDI. For a discussion of a simple playback MIDI implementation, see the MCIWnd Window Class. For a discussion of the MIDI interface, see Musical Instrument Digital Interface (MIDI).

You can use the following functions to play waveform audio in your application in a single function call:

Function	Description
MessageBeep	Plays the sound that corresponds to a specified system-alert level.
sndPlaySound	Plays the sound that corresponds to the system sound entered in the registry or the contents of the specified filename.
PlaySound	Provides all the functionality of sndPlaySound and can directly access resources.
The MessageBeep function is a standard part of the Win32 API; because its capabilities are very limited and it is documented elsewhere, it is not discussed here.

The functions listed provide the following methods of playing waveform audio:

•	Playing waveform-audio files associated with system-alert levels

•	Playing waveform-audio files specified by entries in the registry

•	Playing in-memory WAVE resources

•	Playing waveform-audio files stored on a hard disk or compact disc − read-only memory (CD-ROM)

The sndPlaySound and PlaySound functions load an entire waveform-audio file into memory and, in effect, limit the size of file they can play. Use sndPlaySound and PlaySound to play waveform-audio files that are relatively small — up to about 100K. These two functions also require the sound data to be in a format that is playable by one of the installed waveform-audio drivers, including the wave mapper.

For larger sound files, use the Media Control Interface (MCI) services. For more information, see MCI.

Using Window Messages to Manage Waveform-Audio Playback

The following messages can be sent to a window procedure function for managing waveform-audio playback.

Message	Description
MM_WOM_CLOSE	Sent when the device is closed by using the waveOutClose function.
MM_WOM_DONE	Sent when the device driver is finished with a data block sent by using the waveOutWrite function.
MM_WOM_OPEN	Sent when the device is opened by using the waveOutOpen function.
A wParam and lParam parameter is associated with each of these messages. The wParam parameter always specifies a handle of the open waveform-audio device. For the MM_WOM_DONE message, lParam specifies a pointer to a WAVEHDR structure that identifies the completed data block. The lParam parameter is unused for the MM_WOM_CLOSE and MM_WOM_OPEN messages.

The most useful message is probably MM_WOM_DONE. When this message signals that playback of a data block is complete, you can clean up and free the data block. Unless you need to allocate memory or initialize variables, you probably do not need to process the MM_WOM_OPEN and MM_WOM_CLOSE messages.

The callback function for waveform-audio output devices is supplied by the application. For information about this callback function, see the waveOutProc function.

Retrieving the Current Playback Position

You can monitor the current playback position within the file while waveform audio is playing by using the waveOutGetPosition function.

For waveform-audio devices, samples are the preferred time format in which to represent the current position. Thus, the current position of a waveform-audio device is specified as the number of samples for one channel from the beginning of the waveform-audio file. To query the current position of a waveform-audio device, set the wType member of the MMTIME structure to TIME_SAMPLES and pass this structure to waveOutGetPosition.

The MMTIME structure can represent time in one or more different formats, including milliseconds, samples, SMPTE (Society of Motion Picture and Television Engineers), and MIDI song pointer formats. The wType member specifies the format used to represent time. Before calling a function that uses the MMTIME structure, you must set wType to indicate your requested time format. Be sure to check wType after the call to see whether the requested time format is supported. If the requested time format is not supported, the device driver specifies the time in an alternate time format and changes the wType member to the selected time format.

For more information about the MMTIME structure, see Multimedia Timers.

Stopping, Pausing, and Restarting Playback

You can stop or pause playback while waveform audio is playing. After playback has been paused, you can restart it. Windows provides the following functions for controlling waveform-audio playback.

Function	Description
waveOutPause	Pauses playback on a waveform-audio output device.
waveOutReset	Stops playback on a waveform-audio output device and marks all pending data blocks as done.
WaveOutRestart	Resumes playback on a paused waveform-audio output device.
Pausing a waveform-audio device by using waveOutPause might not be instantaneous; the driver may finish playing the current block before pausing playback.

Generally, as soon as the first waveform-audio data block is sent by using the waveOutWrite function, the waveform-audio device begins playing. If you do not want the sound to start playing immediately, call waveOutPause before calling waveOutWrite. Then, when you want to begin playing waveform-audio data, call waveOutRestart.

You cannot use waveOutRestart to restart a device that has been stopped with waveOutReset; you must use waveOutWrite to send the first data block to resume playback on the device.

Looping Playback

Looping a sound is controlled by the dwLoops and dwFlags members in the WAVEHDR structures passed to the device with the waveOutWrite function. Use the WHDR_BEGINLOOP and WHDR_ENDLOOP flags in the dwFlags member to specify the beginning and ending data blocks for looping.

To loop a single data block, specify both flags for the same block. To specify the number of loops, use the dwLoops member in the WAVEHDR structure for the first block in the loop.

You can call the waveOutBreakLoop function to stop a looping sound.

Changing the Volume of Waveform-Audio Playback

Windows provides the following functions to query and set the volume level of waveform-audio output devices.

Function	Description
waveOutGetVolume	Retrieves the current volume level of the specified waveform-audio output device.
waveOutSetVolume	Sets the volume level of the specified waveform-audio output device.
Not all waveform-audio devices support volume changes. Some devices support individual volume control on both the left and right channels. For information about how to determine the volume-control capabilities of waveform-audio devices, see Devices and Data Types.

Some applications allow the user to control the volume for all audio devices in a system. (Many applications of this type use the audio mixer services; for more information, see Audio Mixers.) Unless your application is capable of this kind of master volume control, you should open an audio device before changing its volume. You should also query the volume level before changing it and restore the volume level to its previous level as soon as possible.

Volume is specified in a doubleword value. When the audio format is stereo, the upper 16 bits specify the relative volume of the right channel and the lower 16 bits specify the relative volume of the left channel. For devices that do not support left- and right-channel volume control, the lower 16 bits specify the volume level, and the upper 16 bits are ignored.

Volume-level values range from 0x0 (silence) to 0xFFFF (maximum volume) and are interpreted logarithmically. The perceived volume increase is the same when increasing the volume level from 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.

Changing Pitch and Playback Rate

Some waveform-audio output devices can vary the pitch and the playback rate of waveform-audio data. Not all waveform-audio devices support pitch and playback-rate changes. For information about how to determine whether a particular waveform-audio device supports pitch and playback rate changes, see Devices and Data Types.

The differences between changing pitch and playback rate are as follows:

•	Changing the playback rate is performed by the device driver and does not require specialized hardware. The sample rate is not changed, but the driver interpolates by skipping or synthesizing samples. For example, if the playback rate is changed by a factor of two, the driver skips every other sample.

•	Changing the pitch requires specialized hardware. The playback rate and sample rate are not changed.

Windows provides the following functions to query and set waveform-audio pitch and playback rates.

Function	Description
waveOutGetPitch	Retrieves the pitch for the specified waveform-audio output device.
waveOutGetPlaybackRate	Retrieves the playback rate for the specified waveform-audio output device.
waveOutSetPitch	Sets the pitch for the specified waveform-audio output device.
waveOutSetPlaybackRate	Sets the playback rate for the specified waveform-audio output device.
The pitch and playback rates are changed by a factor specified with a fixed-point number packed into a doubleword value. The upper 16 bits specify the integer part of the number; the lower 16 bits specify the fractional part. For example, the value 1.5 is represented as 0x00018000L. The value 0.75 is represented as 0x0000C000L. A value of 1.0 (0x00010000) means the pitch or playback rate is unchanged.


Recording Waveform Audio

If the MCI waveform-audio recording services do not meet the specifications of your application, you can handle waveform-audio recording using the waveform-audio services. For more information, see MCI.

Waveform-Audio Input Data Types

The following data types are defined for waveform-audio input functions:

Type	Description
HWAVEIN	Handle of an open waveform-audio input device.
WAVEFORMATEX	Structure that specifies the data formats supported by a particular waveform-audio input device. This structure is also used for waveform-audio output devices.
WAVEHDR	Structure used as a header for a block of waveform-audio input data. This structure is also used for waveform-audio output devices.
WAVEINCAPS	Structure used to inquire about the capabilities of a particular waveform-audio input device.
Querying Waveform-Audio Input Devices

Before recording waveform audio, you should call the waveInGetDevCaps function to determine the waveform-audio input capabilities of the system. This function fills a WAVEINCAPS structure with information about the capabilities of a specified device. This information includes the manufacturer and product identifiers, a product name for the device, and the version number of the device driver. In addition, the WAVEINCAPS structure provides information about the standard waveform-audio formats that the device supports.

Opening Waveform-Audio Input Devices

Use the waveInOpen function to open a waveform-audio input device for recording. This function opens the device associated with the specified device identifier and returns a handle of the open device by writing the handle of a specified memory location.

Some multimedia computers have multiple waveform-audio input devices. Unless you know you want to open a specific waveform-audio input device in a system, you should use the WAVE_MAPPER constant for the device identifier when you open a device. The waveInOpen function will choose the device in the system best able to record in the specified data format.

Managing Waveform-Audio Recording

After you open a waveform-audio input device, you can begin recording waveform-audio data. Waveform-audio data is recorded into application-supplied buffers specified by a WAVEHDR structure. These data blocks must be prepared before they are used; for more information, see Audio Data Blocks.

Windows provides the following functions to manage waveform-audio recording.

Function	Description
waveInAddBuffer	Sends a buffer to the device driver so it can be filled with recorded waveform-audio data.
waveInReset	Stops waveform-audio recording and marks all pending buffers as done.
waveInStart	Starts waveform-audio recording.
waveInStop	Stops waveform-audio recording.
Use the waveInAddBuffer function to send buffers to the device driver. As the buffers are filled with recorded waveform-audio data, the application is notified with a window message, callback message, thread message, or event, depending on the flag specified when the device was opened.

Before you begin recording by using waveInStart, you should send at least one buffer to the driver, or incoming data could be lost.

Before closing the device using waveInClose, call waveInReset to mark any pending data blocks as being done.

Using Window Messages to Manage Waveform-Audio Recording

The following messages can be sent to a window procedure function for managing waveform-audio recording.

Message	Description
MM_WIM_CLOSE	Sent when the device is closed by using the waveInClose function.
MM_WIM_DATA	Sent when the device driver is finished with a buffer sent by using the waveInAddBuffer function.
MM_WIM_OPEN	Sent when the device is opened by using the waveInOpen function.
The lParam parameter of MM_WIM_DATA specifies a pointer to a WAVEHDR structure that identifies the buffer. This buffer might not be completely filled with waveform-audio data; recording can stop before the buffer is filled. Use the dwBytesRecorded member of the WAVEHDR structure to determine the amount of valid data present in the buffer.

The most useful message is probably MM_WIM_DATA. When your application finishes using the data block sent by the device driver, you can clean up and free the data block. Unless you need to allocate memory or initialize variables, you probably do not need to use the MM_WIM_OPEN and MM_WIM_CLOSE messages.

The callback function for waveform-audio input devices is supplied by the application. For information about this callback function, see the waveInProc function.


Auxiliary Audio Interface

Auxiliary audio devices are audio devices whose output is mixed with the MIDI and waveform-audio output devices in a multimedia computer. An example of an auxiliary audio device is the CD audio output from a CD-ROM drive.


Querying Auxiliary Audio Devices

Not all multimedia systems have auxiliary audio support. You can use the auxGetNumDevs function to determine the number of controllable auxiliary devices present in a system.

To get information about a particular auxiliary audio device, use the auxGetDevCaps function. This function fills an AUXCAPS structure with information about the capabilities of a specified device. This information includes the manufacturer and product identifiers, a product name for the device, and the device-driver version number.


Changing the Volume of Auxiliary Audio-Devices

Windows provides the following functions to query and set the volume for auxiliary audio devices.

Function	Description
auxGetVolume	Retrieves the current volume setting of the specified auxiliary output device.
auxSetVolume	Sets the volume of the specified auxiliary output device.
Not all auxiliary audio devices support volume changes. Some devices can support individual volume changes on both the left and the right channels.

Volume is specified in a doubleword value, as with the waveform-audio and MIDI volume-control functions. When the audio format is stereo, the upper 16 bits specify the relative volume of the right channel and the lower 16 bits specify the relative volume of the left channel. For devices that do not support left- and right-channel volume control, the lower 16 bits specify the volume level, and the upper 16 bits are ignored.

Volume-level values range from 0x0 (silence) to 0xFFFF (maximum volume) and are interpreted logarithmically. The perceived volume increase is the same when increasing the volume level from 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.


Audio Data Blocks

The waveInAddBuffer and waveOutWrite functions require applications to allocate data blocks to pass to the device drivers for recording or playback purposes. Both of these functions use the WAVEHDR structure to describe its data block.

Before using one of these functions to pass a data block to a device driver, you must allocate memory for the data block and the header structure that describes the data block. The headers can be prepared and unprepared by using the following functions.

Function	Description
waveInPrepareHeader	Prepares a waveform-audio input data block.
waveInUnprepareHeader	Cleans up the preparation on a waveform-audio input data block.
waveOutPrepareHeader	Prepares a waveform-audio output data block.
waveOutUnprepareHeader	Cleans up the preparation on a waveform-audio output data block.
Before you pass an audio data block to a device driver, you must prepare the data block by passing it to either waveInPrepareHeader or waveOutPrepareHeader. When the device driver is finished with the data block and returns it, you must clean up this preparation by passing the data block to either waveInUnprepareHeader or waveOutUnprepareHeader before any allocated memory can be freed.

Unless the waveform-audio input and output data is small enough to be contained in a single data block, applications must continually supply the device driver with data blocks until playback or recording is complete.

Even if a single data block is used, an application must be able to determine when a device driver is finished with the data block so the application can free the memory associated with the data block and header structure. There are several ways to determine when a device driver is finished with a data block:

•	By specifying a callback function to receive a message sent by the driver when it is finished with a data block

•	By using an event callback

•	By specifying a window or thread to receive a message sent by the driver when it is finished with a data block

•	By polling the WHDR_DONE bit in the dwFlags member of the WAVEHDR structure sent with each data block

If an application does not get a data block to the device driver when needed, there can be an audible gap in playback or a loss of incoming recorded information. This requires at least a double-buffering scheme — staying at least one data block ahead of the device driver.

The following sections describe ways to determine when a device driver is finished with a data block:

•	Using a callback function to process driver messages

•	Using an event callback to process driver messages

•	Using a window or thread to process driver messages

•	Managing data blocks by polling


Using a Callback Function to Process Driver Messages

You can write your own callback function to process messages sent by the device driver. To use a callback function, specify the CALLBACK_FUNCTION flag in the fdwOpen parameter and the address of the callback in the dwCallback parameter of the waveInOpen or waveOutOpen function.

Messages sent to a callback function are similar to messages sent to a window, except they have two DWORD parameters instead of a UINT and a DWORD parameter. For details on these messages, see Playing Waveform-Audio Files.

To pass instance data from an application to a callback function, use one of the following techniques:

•	Pass the instance data using the dwInstance parameter of the function that opens the device driver.

•	Pass the instance data using the dwUser member of the WAVEHDR structure that identifies an audio data block being sent to a device driver.

If you need more than 32 bits of instance data, pass a pointer to a structure containing the additional information.


Using an Event Callback to Process Driver Messages

To use an event callback, use the CreateEvent function to retrieve the handle of an event. In the call to the waveOutOpen function, specify CALLBACK_EVENT for the fdwOpen parameter. After calling the waveOutPrepareHeader function but before sending waveform-audio data to the device, create a nonsignaled event by calling the ResetEvent function, specifying the event handle retrieved by CreateEvent. Then, inside a loop that checks whether the WHDR_DONE bit is set in the dwFlags member of the WAVEHDR structure, call the WaitForSingleObject function, specifying as parameters the event handle and a time-out value of INFINITE.

Because event callbacks do not receive specific close, done, or open notifications, an application might have to check the status of the process it is waiting for after the event occurs. It is possible that a number of tasks could have been completed by the time WaitForSingleObject returns.


Using a Window or Thread to Process Driver Messages

To use a window callback function, specify the CALLBACK_WINDOW flag in the fdwOpen parameter and a window handle in the low-order word of the dwCallback parameter of the waveInOpen or waveOutOpen function. Driver messages will be sent to the window procedure for the window identified by the handle in dwCallback.

Similarly, to use a thread callback, specify CALLBACK_THREAD and a thread handle in the call to waveInOpen or waveOutOpen. In this case, messages are posted to the specified thread instead of to a window.

Messages sent to the window or thread callback are specific to the audio device type used. For more information about these messages, see Playing Waveform-Audio Files.


Managing Data Blocks by Polling

In addition to using a callback function, you can poll the dwFlags member of a WAVEHDR structure to determine when an audio device is finished with a data block. Sometimes it is better to poll dwFlags than to wait for another mechanism to receive messages from the drivers. For example, after you call the waveOutReset function to release pending data blocks, you can immediately poll to be sure that the data blocks have been released before calling waveOutUnprepareHeader and freeing the memory for the data block.

You can use the WHDR_DONE flag to test the dwFlags member. As soon as the WHDR_DONE flag is set in the dwFlags member of the WAVEHDR structure, the driver is finished with the data block.


Handling Errors with Audio Functions

The waveform-audio and auxiliary-audio functions return a nonzero value when an error occurs. Windows provides functions that convert these error values into textual descriptions of the errors. The application must still examine the error values to determine how to proceed, but textual descriptions of errors can be used in dialog boxes that describe errors to users.

You can use the following functions to retrieve textual descriptions of audio error values:

Function	Description
waveInGetErrorText	Retrieves a textual description of a specified waveform-audio input error.
waveOutGetErrorText	Retrieves a textual description of a specified waveform-audio output error.
The only audio functions that do not return error values are auxGetNumDevs,  waveInGetNumDevs, and waveOutGetNumDevs. These functions return zero if no devices are present in a system or if they encounter any errors.


Using Waveform and Auxiliary Audio

This section demonstrates implementing waveform and auxiliary audio in your application. The following topics are discussed:

•	Playing WAVE resources

•	Determining nonstandard format support

•	Processing the MM_WOM_DONE message


Playing WAVE Resources

You can use the PlaySound function to play a sound that is stored as a resource. Although this is also possible using the sndPlaySound function, sndPlaySound requires that you find, load, lock, unlock, and free the resource; PlaySound achieves all of this with a single line of code.

PlaySound Example

PlaySound(“SoundName”, hInst, SND_RESOURCE | SND_ASYNC);

sndPlaySound Example

The SND_MEMORY flag indicates that the lpszSoundName parameter is a pointer to an in-memory image of the WAVE file. To include a WAVE file as a resource in an application, add the following entry to the application’s resource script (.RC) file.

soundName WAVE c:\sounds\bells.wav

The name soundName is a placeholder for a name that you supply to refer to this WAVE resource. WAVE resources are loaded and accessed just like other application-defined Windows resources. The PlayResource function in the following example plays a specified WAVE resource.

BOOL PlayResource(LPSTR lpName)

{

    BOOL bRtn;

    LPSTR lpRes;

    HANDLE hResInfo, hRes;

    // Find the WAVE resource.

    hResInfo = FindResource(hInst, lpName, "WAVE");

    if (hResInfo == NULL)

        return FALSE;

    // Load the WAVE resource.

    hRes = LoadResource(hInst, hResInfo);

    if (hRes == NULL)

        return FALSE;

    // Lock the WAVE resource and play it.

    lpRes = LockResource(hRes);

    if (lpRes != NULL) {

        bRtn = sndPlaySound(lpRes, SND_MEMORY | SND_SYNC |

            SND_NODEFAULT);

        UnlockResource(hRes);

    }

    else

        bRtn = 0;

    // Free the WAVE resource and return success or failure.

    FreeResource(hRes);

    return bRtn;

}

To play a WAVE resource by using this function, pass to the function a pointer to a string containing the name of the resource, as shown in the following example.

PlayResource("soundName");


Using the PCMWAVEFORMAT Structure

For PCM audio data, use the PCMWAVEFORMAT structure to specify the data format. The following example shows how to set up a PCMWAVEFORMAT structure for 11.025 kilohertz (kHz) 8-bit mono and for 44.1 kHz 16-bit stereo. After setting up PCMWAVEFORMAT, the example calls the IsFormatSupported function to verify that the PCM waveform output device supports the format. The source code for IsFormatSupported is shown in an example in Determining Nonstandard Format Support.

UINT wReturn;

PCMWAVEFORMAT pcmWaveFormat;

// Set up PCMWAVEFORMAT for 11 kHz 8-bit mono.

pcmWaveFormat.wf.wFormatTag = WAVE_FORMAT_PCM;

pcmWaveFormat.wf.nChannels = 1;

pcmWaveFormat.wf.nSamplesPerSec = 11025L;

pcmWaveFormat.wf.nAvgBytesPerSec = 11025L;

pcmWaveFormat.wf.nBlockAlign = 1;

pcmWaveFormat.wBitsPerSample = 8;

// See if format is supported by any device in system.

wReturn = IsFormatSupported(&pcmWaveFormat, WAVE_MAPPER);

// Report results.

if (wReturn == 0)

     MessageBox(hMainWnd, "11 kHz 8-bit mono is supported.",

       "", MB_ICONINFORMATION);

else if (wReturn == WAVERR_BADFORMAT)

     MessageBox(hMainWnd, "11 kHz 8-bit mono NOT supported.",

       "", MB_ICONINFORMATION);

else

     MessageBox(hMainWnd, "Error opening waveform device.",

       "Error", MB_ICONEXCLAMATION);

// Set up PCMWAVEFORMAT for 44.1 kHz 16-bit stereo.

pcmWaveFormat.wf.wFormatTag = WAVE_FORMAT_PCM;

pcmWaveFormat.wf.nChannels = 2;

pcmWaveFormat.wf.nSamplesPerSec = 44100L;

pcmWaveFormat.wf.nAvgBytesPerSec = 176400L;

pcmWaveFormat.wf.nBlockAlign = 4;

pcmWaveFormat.wBitsPerSample = 32;

// See if format is supported by any device in the system.

wReturn = IsFormatSupported(&pcmWaveFormat, WAVE_MAPPER);

/ Report results.

if (wReturn == 0)

    MessageBox(hMainWnd, "44.1 kHz 16-bit stereo is supported.",

      "", MB_ICONINFORMATION);

else if (wReturn == WAVERR_BADFORMAT)

    MessageBox(hMainWnd, "44.1 kHz 16-bit stereo NOT supported.",

      "", MB_ICONINFORMATION);

else

    MessageBox(hMainWnd, "Error opening waveform device.",

      "Error", MB_ICONEXCLAMATION);


Determining Nonstandard Format Support

To see whether a device supports a particular format (standard or nonstandard), you can call the waveOutOpen function with the WAVE_FORMAT_QUERY flag. The following example uses this technique to determine whether a waveform-audio device supports a specified format.

// Determines whether the specified waveform-audio output device

// supports a specified waveform-audio format. Returns

// MMSYSERR_NOERROR if the format is supported, WAVEERR_BADFORMAT if

// the format is not supported, and one of the other MMSYSERR_ error

// codes if there are other errors encountered in opening the

// specified waveform-audio device.

MMRESULT IsFormatSupported(LPWAVEFORMATEX pwfx, UINT uDeviceID)

{

    return (waveOutOpen(

        NULL,                 // ptr can be NULL for query

        uDeviceID,            // the device identifier

        pwfx,                 // defines requested format

        NULL,                 // no callback

        NULL,                 // no instance data

        WAVE_FORMAT_QUERY));  // query only, do not open device

}

This technique for determining nonstandard format support also applies to waveform-audio input devices. The only difference is that the waveInOpen function is used in place of waveOutOpen to query for format support.

To determine whether a particular waveform-audio data format is supported by any of the waveform-audio devices in a system, use the technique illustrated in the previous example, but specify the WAVE_MAPPER constant for the uDeviceID parameter.


Example of Writing Waveform Data

The following example illustrates the steps required to allocate and set up a WAVEHDR structure and write a block of data to a waveform output device.

// Global variables.

HANDLE hData  = NULL;  // handle of waveform data memory

HPSTR  lpData = NULL;  // pointer to waveform data memory

void WriteWaveData(void)

{

    HWAVEOUT    hWaveOut;

    HGLOBAL     hWaveHdr;

    LPWAVEHDR   lpWaveHdr;

    HMMIO       hmmio;

    UINT        wResult;

    HANDLE      hFormat;

    WAVEFORMAT  *pFormat;

    DWORD       dwDataSize;

    // Open a waveform device for output using window callback.

    if (waveOutOpen((LPHWAVEOUT)&hWaveOut, WAVE_MAPPER,

                    (LPWAVEFORMAT)pFormat,

                    (LONG)hwndApp, 0L, CALLBACK_WINDOW))

    {

        MessageBox(hwndApp,

                   "Failed to open waveform output device.",

                   NULL, MB_OK | MB_ICONEXCLAMATION);

        LocalUnlock(hFormat);

        LocalFree(hFormat);

        mmioClose(hmmio, 0);

        return;

    }

    // Allocate and lock memory for the waveform data.

    hData = GlobalAlloc(GMEM_MOVEABLE | GMEM_SHARE, dwDataSize );

    if (!hData)

    {

        MessageBox(hwndApp, "Out of memory.",

                   NULL, MB_OK | MB_ICONEXCLAMATION);

        mmioClose(hmmio, 0);

        return;

    }

    if ((lpData = GlobalLock(hData)) == NULL)

    {

        MessageBox(hwndApp, "Failed to lock memory for data chunk.",

                   NULL, MB_OK | MB_ICONEXCLAMATION);

        GlobalFree(hData);

        mmioClose(hmmio, 0);

        return;

    }

    // Read the waveform data subchunk.

    if(mmioRead(hmmio, (HPSTR) lpData, dwDataSize) != (LRESULT)dwDataSize)

    {

        MessageBox(hwndApp, "Failed to read data chunk.",

                   NULL, MB_OK | MB_ICONEXCLAMATION);

        GlobalUnlock(hData);

        GlobalFree(hData);

        mmioClose(hmmio, 0);

        return;

    }

    // Allocate and lock memory for the header.

    hWaveHdr = GlobalAlloc(GMEM_MOVEABLE | GMEM_SHARE,

        (DWORD) sizeof(WAVEHDR));

    if (hWaveHdr == NULL)

    {

        GlobalUnlock(hData);

        GlobalFree(hData);

        MessageBox(hwndApp, "Not enough memory for header.",

            NULL, MB_OK | MB_ICONEXCLAMATION);

        return;

    }

    lpWaveHdr = (LPWAVEHDR) GlobalLock(hWaveHdr);

    if (lpWaveHdr == NULL)

    {

        GlobalUnlock(hData);

        GlobalFree(hData);

        MessageBox(hwndApp,

            "Failed to lock memory for header.",

            NULL, MB_OK | MB_ICONEXCLAMATION);

        return;

    }

    // After allocation, set up and prepare header.

    lpWaveHdr->lpData = lpData;

    lpWaveHdr->dwBufferLength = dwDataSize;

    lpWaveHdr->dwFlags = 0L;

    lpWaveHdr->dwLoops = 0L;

    waveOutPrepareHeader(hWaveOut, lpWaveHdr, sizeof(WAVEHDR));

    // Now the data block can be sent to the output device. The

    // waveOutWrite function returns immediately and waveform

    // data is sent to the output device in the background.

    wResult = waveOutWrite(hWaveOut, lpWaveHdr, sizeof(WAVEHDR));

    if (wResult != 0)

    {

        waveOutUnprepareHeader(hWaveOut, lpWaveHdr,

                               sizeof(WAVEHDR));

        GlobalUnlock( hData);

        GlobalFree(hData);

        MessageBox(hwndApp, "Failed to write block to device",

                   NULL, MB_OK | MB_ICONEXCLAMATION);

        return;

    }

}


Processing the MM_WOM_DONE Message

The following example shows how to process the MM_WOM_DONE message. This example assumes the application does not play multiple data blocks, so it can close the output device after playing a single data block.

// WndProc--Main window procedure.

LRESULT FAR PASCAL WndProc(HWND hWnd, UINT msg, WPARAM wParam,

    LPARAM lParam)

{

switch (msg)

{

    case MM_WOM_DONE:

    // A waveform-audio data block has been played and

    // can now be freed.

    waveOutUnprepareHeader((HWAVEOUT) wParam,

        (LPWAVEHDR) lParam, sizeof(WAVEHDR) );

    // Free hData memory.

    waveOutClose((HWAVEOUT) wParam);

    break;

    }

    return DefWindowProc(hWnd, msg, wParam, lParam);

}


Waveform Audio Reference

This section describes the functions, structures, and messages associated with waveform audio. These elements are grouped as follows.

Auxiliary Devices

AUXCAPS
auxGetDevCaps
auxGetNumDevs
auxGetVolume
auxOutMessage
auxSetVolume

Easy Playback

PlaySound
sndPlaySound

Errors

waveInGetErrorText
waveOutGetErrorText

Opening and Closing

PCMWAVEFORMAT
MM_WIM_CLOSE
MM_WIM_OPEN
MM_WOM_CLOSE
MM_WOM_OPEN
WAVEFORMAT
WAVEFORMATEX
waveInClose
waveInProc
waveInOpen
waveOutClose
waveOutProc
waveOutOpen
WIM_CLOSE
WIM_OPEN
WOM_CLOSE
WOM_OPEN

Pitch

waveOutGetPitch
waveOutSetPitch

Playback Rate

waveOutGetPlaybackRate
waveOutSetPlaybackRate

Playback Progress

MM_WOM_DONE
waveOutBreakLoop
waveOutPause
waveOutReset
waveOutRestart
WOM_DONE

Playing

MM_WOM_DONE
WAVEHDR
waveOutPrepareHeader
waveOutUnprepareHeader
waveOutWrite
WOM_DONE

Querying a Device

WAVEINCAPS
waveInGetDevCaps
waveInGetNumDevs
WAVEOUTCAPS
waveOutGetDevCaps
waveOutGetNumDevs

Recording

MM_WIM_DATA
waveInAddBuffer
waveInPrepareHeader
waveInReset
waveInStart
waveInStop
waveInUnprepareHeader
WIM_DATA

Retrieving Device Identifiers

waveInGetID
waveOutGetID

Retrieving the Current Position

waveInGetPosition
waveOutGetPosition

Sending Custom Messages

waveInMessage
waveOutMessage

Volume

waveOutGetVolume
waveOutSetVolume


Waveform Functions

The following functions are used with waveform audio.

auxGetDevCaps
auxGetNumDevs
auxGetVolume
auxOutMessage
auxSetVolume
PlaySound
sndPlaySound
waveInAddBuffer
waveInClose
waveInGetDevCaps
waveInGetErrorText
waveInGetID
waveInGetNumDevs
waveInGetPosition
waveInMessage
waveInOpen
waveInPrepareHeader
waveInProc
waveInReset
waveInStart
waveInStop
waveInUnprepareHeader
waveOutBreakLoop
waveOutClose
waveOutGetDevCaps
waveOutGetErrorText
waveOutGetID
waveOutGetNumDevs
waveOutGetPitch
waveOutGetPlaybackRate
waveOutGetPosition
waveOutGetVolume
waveOutMessage
waveOutOpen
waveOutPause
waveOutPrepareHeader
waveOutProc
waveOutReset
waveOutRestart
waveOutSetPitch
waveOutSetPlaybackRate
waveOutSetVolume
waveOutUnprepareHeader
waveOutWrite


Waveform Structures

PCMWAVEFORMAT
WAVEFILTER
WAVEFORMAT
WAVEFORMATEX
WAVEHDR
WAVEINCAPS
WAVEOUTCAPS


Waveform Messages

MM_WIM_CLOSE
MM_WIM_DATA
MM_WIM_OPEN
MM_WOM_CLOSE
MM_WOM_DONE
MM_WOM_OPEN
WIM_CLOSE
WIM_DATA
WIM_OPEN
WOM_CLOSE
WOM_DONE
WOM_OPEN


MCI_BREAK

The MCI_BREAK command sets a break key for an MCI device. MCI supports this command directly rather than passing it to the device. Any MCI application can use this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_BREAK,
    DWORD dwFlags, (DWORD) (LPMCI_BREAK_PARMS) lpBreak);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and video-cassette recorder (VCR) devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpBreak

Address of an MCI_BREAK_PARMS structure.

Return Values

Returns zero if successful or an error otherwise.

Remarks

You might have to press the break key multiple times to interrupt a wait operation. Pressing the break key after a device wait is canceled can send the break to an application. If an application has an action defined for the virtual-key code, then it can inadvertently respond to the break. For example, an application using VK_CANCEL for an accelerator key can respond to the default CTRL+BREAK key if it is pressed after a wait is canceled.

The following additional flags apply to all devices:

MCI_BREAK_HWND

The hwndBreak member of the structure identified by lpBreak contains a window handle that must be the current window in order to enable break detection for that MCI device. This is usually the application’s main window. If omitted, MCI does not check the window handle of the current window.

MCI_BREAK_KEY

The nVirtKey member of the structure identified by lpBreak specifies the virtual-key code used for the break key. By default, MCI assigns CTRL+BREAK as the break key. This flag is required if MCI_BREAK_OFF is not specified.

MCI_BREAK_OFF

Disables any existing break key for the indicated device.

See Also

MCI_BREAK_PARMS


MCI_CAPTURE

The MCI_CAPTURE command captures the contents of the frame buffer and stores it in a specified file. Digital-video devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_CAPTURE,
    DWORD dwFlags, (DWORD) (LPMCI_DGV_CAPTURE_PARMS) lpCapture);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpCapture

Address of an MCI_DGV_CAPTURE_PARMSstructure.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags apply to digital-video devices:

MCI_DGV_CAPTURE_AS

The lpstrFileName member of the structure identified by lpCapture contains an address of a buffer specifying the destination path and filename. (This flag is required.)

MCI_DGV_CAPTURE_AT

The rc member of the structure identified by lpCapture contains a valid rectangle. The rectangle specifies the rectangular region within the frame buffer that is cropped and saved to disk. If omitted, the cropped region defaults to the rectangle specified or defaulted on a previous MCI_PUT command that specifies the source area for this instance of the device driver.

See Also

MCI_DGV_CAPTURE_PARMS, MCI_PUT


MCI_CLOSE

The MCI_CLOSE command releases access to a device or file. All devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_CLOSE,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpClose);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY or MCI_WAIT. For information about these flags, see The Wait, Notify, and Test Flags.

lpClose

Address of an MCI_GENERIC_PARMS structure. (You can also use an MCI_CLOSE_PARMS  structure. For more information, see the comments for MCI_GENERIC_PARMS.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

Exiting an application without closing any MCI devices it has opened can leave the device inaccessible. Your application should explicitly close each device or file when it is finished with it. MCI unloads the device when all instances of the device or all associated files are closed.

See Also

MCI_GENERIC_PARMS


MCI_CONFIGURE

The MCI_CONFIGURE command displays a dialog box for setting the operating options. Digital-video devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_CONFIGURE,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpConfigure);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpConfigure

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

See Also

MCI_GENERIC_PARMS


MCI_COPY

The MCI_COPY command copies data to the clipboard. Digital-video devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_COPY,
    DWORD dwFlags, (DWORD) (LPMCI_DGV_COPY_PARMS) lpCopy);

Parameters

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpCopy

Address of an MCI_DGV_COPY_PARMS structure.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags apply to digital-video devices:

MCI_DGV_COPY_AT

A rectangle is included in the rc member of the structure identified by lpCopy. The rectangle specifies the portion of each frame to copy. If the flag is omitted, MCI_COPY copies the entire frame.

MCI_DGV_COPY_AUDIO_STREAM

An audio-stream number is included in the dwAudioStream member of the structure identified by lpCopy. If you use this flag and also want to copy video, you must also use the MCI_DGV_COPY_VIDEO_STREAM flag. (If neither flag is specified, data from all audio and video streams is copied.)

MCI_DGV_COPY_VIDEO_STREAM

A video-stream number is included in the dwVideoStream member of the structure identified by lpCopy. If you use this flag and also want to copy audio, you must also use the MCI_DGV_COPY_AUDIO_STREAM flag. (If neither flag is specified, data from all audio and video streams is copied.)

MCI_FROM

A starting location is included in the dwFrom member of the structure identified by lpCopy. The units assigned to the position values are specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command.

MCI_TO

An ending location is included in the dwTo member of the structure identified by lpCopy. The units assigned to the position values are specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command.

See Also

MCI_DGV_COPY_PARMS, MCI_SET


MCI_CUE

The MCI_CUE command cues a device so that playback or recording begins with minimum delay.Digital-video, VCR, and waveform-audio devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_CUE,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpCue);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpCue

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags are used with the digitalvideo device type:

MCI_DGV_CUE_INPUT

A digital-video instance should prepare for recording. If the application has not reserved disk space, the device reserves the disk space using its default parameters. The application can omit this flag if the current presentation source is already the external input. (This flag has no effect on selecting the presentation source.)

MCI_DGV_CUE_NOSHOW

A digital-video instance should prepare for playing the frame specified with the command without displaying it. When this flag is specified, the display continues to show the image in the frame buffer even though its corresponding frame is not the current position. For example, if the frame buffer contains the image from frame 7, the device continues to show frame 7 when this flag is used to cue the device to any other position. A subsequent cue command without this flag and without the MCI_TO flag displays the current frame.

MCI_DGV_CUE_OUTPUT

A digital-video instance should prepare for playing. If the workspace is paused, no positioning occurs. If the workspace is stopped, the position might change to a previous key-frame image. The application can omit this flag if the current presentation source is already the workspace.

MCI_TO

A workspace position is included in the dwTo member of the structure identified by lpCue. The units assigned to position values are specified using the MCI_SET_TIME_FORMAT flag of the MCI_SET command. This is equivalent to seeking to a position, except the device is paused after the command.

For digitalvideo devices, the lpCue parameter points to an MCI_DGV_CUE_PARMS structure.

The following additional flags are used with the vcr device type:

MCI_FROM

The dwFrom member of the structure pointed to by lpCue contains the starting location specified in the current time format.

MCI_TO

The dwTo member of the structure pointed to by lpCue contains the ending (pausing) location specified in the current time format.

MCI_VCR_CUE_INPUT

Prepare for recording.

MCI_VCR_CUE_OUTPUT

Prepare for playing. If neither MCI_VCR_CUE_INPUT nor MCI_VCR_CUE_OUTPUT is specified, MCI_VCR_CUE_OUTPUT is assumed.

MCI_VCR_CUE_PREROLL

Cue the device to the current position, or the dwFrom position, minus the preroll duration. This will allow the device to prepare itself before entering record or playback mode.

MCI_VCR_CUE_REVERSE

The direction of the next play or record command is reverse.

When cueing for playback by using the MCI_CUE command with the MCI_VCR_CUE_OUTPUT flag, you can cancel MCI_CUE by issuing the MCI_PLAY command with MCI_FROM, MCI_TO, or MCI_VCR_PLAY_REVERSE.

When cueing for recording by using MCI_CUE with the MCI_VCR_CUE_INPUT flag, you can cancel MCI_CUE by issuing the MCI_RECORD command with MCI_FROM, MCI_TO, or MCI_VCR_RECORD_INITIALIZE.

For vcr devices, the lpCue parameter points to an MCI_VCR_CUE_PARMS structure.

The following additional flags are used with the waveaudio device type:

MCI_WAVE_INPUT

A waveform-audio input device should be cued.

MCI_WAVE_OUTPUT

A waveform-audio output device should be cued. This is the default flag if a flag is not specified.

See Also

MCI_DGV_CUE_PARMS, MCI_GENERIC_PARMS, MCI_PLAY, I_RECORD, MCI_SET, MCI_VCR_CUE_PARMS


MCI_CUT

The MCI_CUT command removes data from the file and copies it to the clipboard. Digital-video devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_CUT,
    DWORD dwFlags, (DWORD) (LPMCI_DGV_CUT_PARMS) lpCut);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpCut

Address of an MCI_DGV_CUT_PARMS structure.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags apply to digital-video devices:

MCI_DGV_CUT_AT

A rectangle is included in the rc member of the structure identified by lpCut. The rectangle specifies the portion of each frame to cut. If the flag is omitted, MCI_CUT cuts the entire frame.

MCI_DGV_CUT_AUDIO_STREAM

An audio-stream number is included in the dwAudioStream member of the structure identified by lpCut. If you use this flag and also want to cut video, you must also use the MCI_DGV_CUT_VIDEO_STREAM flag. (If neither flag is specified, data from all audio and video streams is cut.)

MCI_DGV_CUT_VIDEO_STREAM

A video-stream number is included in the dwVideoStream member of the structure identified by lpCut. If you use this flag and also want to cut audio, you must also use the MCI_DGV_CUT_AUDIO_STREAM flag. (If neither flag is specified, data from all audio and video streams is cut.)

MCI_FROM

A starting location is included in the dwFrom member of the structure identified by lpCut. The units assigned to the position values are specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command.

MCI_TO

An ending location is included in the dwTo member of the structure identified by lpCut. The units assigned to the position values are specified with the MCI_SET_TIME_FORMAT flag of MCI_SET.

See Also

MCI_DGV_CUT_PARMS, MCI_SET


MCI_DELETE

The MCI_DELETE command removes data from the file. Digital-video and waveform-audio devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_DELETE,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpDelete);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpDelete

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following flags apply to the digitalvideo device type:

MCI_DGV_DELETE_AT

A rectangle is included in the rc member of the structure identified by lpDelete. The rectangle specifies the portion of each frame to delete. When this flag is used, the frame is retained in the workspace and the area specified by the rectangle becomes black. If the flag is omitted, MCI_DELETE defaults to the entire frame and removes the frame from the workspace.

MCI_DGV_DELETE_AUDIO_STREAM

An audio-stream number is included in the dwAudioStream member of the structure identified by lpDelete. If you use this flag and also want to delete video, you must also use the MCI_DGV_DELETE_VIDEO_STREAM flag. (If neither flag is specified, data from all audio and video streams is deleted.)

MCI_DGV_DELETE_VIDEO_STREAM

A video-stream number is included in the dwVideoStream member of the structure identified by lpDelete. If you use this flag and also want to delete audio, you must also use the MCI_DGV_DELETE_AUDIO_STREAM flag. (If neither flag is specified, data from all audio and video streams is deleted.)

MCI_FROM

A starting location is included in the dwFrom member of the structure identified by lpDelete. The units assigned to the position values are specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command.

MCI_TO

An ending location is included in the dwTo member of the structure identified by lpDelete. The units assigned to the position values are specified with the MCI_SET_TIME_FORMAT flag of MCI_SET.

For digital-video devices, the lpDelete parameter points to an MCI_DGV_DELETE_PARMS structure.

The following flags apply to the waveaudio device type:

MCI_FROM

A starting location is included in the dwFrom member of the structure identified by lpDelete. The units assigned to the position values are specified with the MCI_SET_TIME_FORMAT flag of MCI_SET.

MCI_TO

An ending location is included in the dwTo member of the structure identified by lpDelete. The units assigned to the position values are specified with the MCI_SET_TIME_FORMAT flag of MCI_SET.

For waveform-audio devices, the lpDelete parameter points to an MCI_WAVE_DELETE_PARMS structure.

See Also

MCI_DGV_DELETE_PARMS, MCI_GENERIC_PARMS, MCI_SET, MCI_WAVE_DELETE_PARMS


MCI_ESCAPE

The MCI_ESCAPE command sends a string directly to the device. Videodisc devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_ESCAPE,
    DWORD dwFlags, (DWORD) (LPMCI_VD_ESCAPE_PARMS) lpEscape);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY or MCI_WAIT. For information about these flags, see The Wait, Notify, and Test Flags.

lpEscape

Address of an MCI_VD_ESCAPE_PARMS structure.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The data sent with MCI_ESCAPE is device-dependent and is usually passed directly to the hardware associated with the device.

The following additional flag applies to videodisc devices:

MCI_VD_ESCAPE_STRING

A command string is specified in the lpstrCommand member of the structure identified by lpEscape. This flag is required.

See Also

MCI_VD_ESCAPE_PARMS


MCI_FREEZE

The MCI_FREEZE command freezes motion on the display. Digital-video, video-overlay, and VCR devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_FREEZE,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpFreeze);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpFreeze

Address of an MCI_GENERIC_PARMS structure. (Devices with additional parameters might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags are used by the digitalvideo device type:

MCI_DGV_FREEZE_AT

The rc member of the structure identified by lpFreeze contains a valid rectangle. The rectangle specifies a region within the frame buffer that will have the lock mask bit for each pixel turned on. The specified pixels will not be updated until their lock mask bit is turned off. If this flag is not specified, the rectangle defaults to the entire frame buffer. This flag is supported only if the MCI_GETDEVCAPS command returns TRUE for the MCI_DGV_GETDEVCAPS_CAN_LOCK flag.

MCI_DGV_FREEZE_OUTSIDE

The area outside the region specified for the MCI_DGV_FREEZE_AT flag is frozen.

For digital-video devices, the lpFreeze parameter points to an MCI_DGV_FREEZE_PARMS structure.

The following additional flags are used by the vcr device type:

MCI_VCR_FREEZE_FIELD

Freeze only one member of the current frame.

MCI_VCR_FREEZE_FRAME

Freeze both fields of the current frame.

MCI_VCR_FREEZE_INPUT

Freeze the current frame on the screen (used for recording).

MCI_VCR_FREEZE_OUTPUT

Freeze the current frame from the VCR (used with frame capture).

For VCR devices, the lpFreeze parameter points to an MCI_GENERIC_PARMS structure.

The following additional flag is used by the overlay device type:

MCI_OVLY_RECT

The rc member of the structure identified by lpFreeze contains a valid rectangle. If this flag is not specified, the device driver will freeze the entire frame.

For video-overlay devices, the lpFreeze parameter points to an MCI_OVLY_RECT_PARMS structure.

See Also

MCI_DGV_FREEZE_PARMS, MCI_GENERIC_PARMS, MCI_GETDEVCAPS


MCI_GETDEVCAPS

The MCI_GETDEVCAPS command retrieves static information about a device. All devices recognize this command. The parameters and flags available for this command depend on the selected device. Information is returned in the dwReturn member of the structure identified by lpCapsParms.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_GETDEVCAPS,
    DWORD dwFlags, (DWORD) (LPMCI_GETDEVCAPS_PARMS) lpCapsParms);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpCapsParms

Address of an MCI_GETDEVCAPS_PARMS structure.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional standard and command-specific flags apply to all devices supporting MCI_GETDEVCAPS:

MCI_GETDEVCAPS_COMPOUND_DEVICE

The dwReturn member is set to TRUE if the device uses data storage that must be explicitly opened and closed; it is set to FALSE otherwise.

MCI_GETDEVCAPS_DEVICE_TYPE

The dwReturn member is set to one of the values listed in Constants: Device Types.

MCI_GETDEVCAPS_HAS_AUDIO

The dwReturn member is set to TRUE if the device has audio output; it is set to FALSE otherwise.

MCI_GETDEVCAPS_HAS_VIDEO

The dwReturn member is set to TRUE if the device has video output; it is set to FALSE otherwise. For example, the member is set to TRUE for devices that support the videodisc command set.

MCI_GETDEVCAPS_ITEM

Specifies that the dwItem member of the MCI_GETDEVCAPS_PARMS structure contains one of the following constants:

MCI_GETDEVCAPS_CAN_EJECT

The dwReturn member is set to TRUE if the device can eject the media; otherwise, it is set to FALSE.

MCI_GETDEVCAPS_CAN_PLAY

The dwReturn member is set to TRUE if the device can play the media; otherwise, it is set to FALSE. If a device specifies TRUE, it implies the device supports the MCI_PAUSE and MCI_STOP commands as well as the MCI_PLAY command.

MCI_GETDEVCAPS_CAN_RECORD

The dwReturn member is set to TRUE if the device supports recording; otherwise, it is set to FALSE. If a device specifies TRUE, it implies the device supports the MCI_PAUSE and MCI_STOP commands as well as the MCI_RECORD command.

MCI_GETDEVCAPS_CAN_SAVE

The dwReturn member is set to TRUE if the device can save a file; otherwise, it is set to FALSE.

MCI_GETDEVCAPS_USES_FILES

The dwReturn member is set to TRUE if the device requires a filename; it is set to FALSE otherwise. Only compound devices use files.

The following flags can be specified in the dwItem member of MCI_GETDEVCAPS_PARMS for the digitalvideo device type:

MCI_DGV_GETDEVCAPS_CAN_FREEZE

The dwReturn member is set to TRUE if the device can freeze frames; otherwise, it is set to FALSE.

MCI_DGV_GETDEVCAPS_CAN_LOCK

The dwReturn member is set to TRUE if the device can lock; otherwise, it is set to FALSE.

MCI_DGV_GETDEVCAPS_CAN_REVERSE

The dwReturn member is set to TRUE if the device can play in reverse; otherwise, it is set to FALSE.

MCI_DGV_GETDEVCAPS_CAN_STR_IN

The dwReturn member is set to TRUE if the device can stretch input; otherwise, it is set to FALSE.

MCI_DGV_GETDEVCAPS_CAN_STRETCH

The dwReturn member is set to TRUE if the device can stretch an image; otherwise, it is set to FALSE.

MCI_DGV_GETDEVCAPS_CAN_TEST

The dwReturn member is set to TRUE if the device can perform tests; otherwise, it is set to FALSE.

MCI_DGV_GETDEVCAPS_HAS_STILL

The dwReturn member is set to TRUE if the device can display still images; otherwise, it is set to FALSE.

MCI_DGV_GETDEVCAPS_MAX_WINDOWS

The dwReturn member is set to the maximum number of windows that the device can handle simultaneously.

MCI_DGV_GETDEVCAPS_MAXIMUM_RATE

The dwReturn member is set to the maximum play rate for the device, in frames per second.

MCI_DGV_GETDEVCAPS_MINIMUM_RATE

The dwReturn member is set to the minimum play rate for the device, in frames per second.

MCI_DGV_GETDEVCAPS_PALETTES

The dwReturn member is set to TRUE if the device can return a palette handle; otherwise, it is set to FALSE.

The following flags can be specified in the dwItem member of MCI_GETDEVCAPS_PARMS for the vcr device type:

MCI_GETDEVCAPS_CLOCK_INCREMENT_RATE

The dwReturn member is set to the number of increments per second.

MCI_VCR_GETDEVCAPS_CAN_DETECT_LENGTH

The dwReturn member is set to TRUE if the device is capable of detecting the length of the media; otherwise, it is set to FALSE.

MCI_VCR_GETDEVCAPS_CAN_FREEZE

The dwReturn member is set to TRUE if the device is capable of freezing the output image; otherwise, it is set to FALSE.

MCI_VCR_GETDEVCAPS_CAN_MONITOR_SOURCES

The dwReturn member is set to TRUE if the device is capable of monitoring sources; otherwise, it is set to FALSE.

MCI_VCR_GETDEVCAPS_CAN_PREROLL

The dwReturn member is set to TRUE if the device is capable of preroll; otherwise, it is set to FALSE.

MCI_VCR_GETDEVCAPS_CAN_PREVIEW

The dwReturn member is set to TRUE if the device is capable of previews; otherwise, it is set to FALSE.

MCI_VCR_GETDEVCAPS_CAN_REVERSE

The dwReturn member is set to TRUE if the device is capable of playing in reverse; otherwise, it is set to FALSE.

MCI_VCR_GETDEVCAPS_CAN_TEST

The dwReturn member is set to TRUE if the device is capable of testing; otherwise, it is set to FALSE.

MCI_VCR_GETDEVCAPS_HAS_CLOCK

The dwReturn member is set to TRUE if the device supports an external clock; otherwise, it is set to FALSE.

MCI_VCR_GETDEVCAPS_HAS_TIMECODE

The dwReturn member is set to TRUE if device has timecode capability or if this capability is unknown; otherwise, it is set to FALSE.

MCI_VCR_GETDEVCAPS_NUMBER_OF_MARKS

The dwReturn member is set to the number of marks (99).

MCI_VCR_GETDEVCAPS_SEEK_ACCURACY

The dwReturn member is set to the seek accuracy of the device.

The following flags can be specified in the dwItem member of MCI_GETDEVCAPS_PARMS for the overlay device type:

MCI_OVLY_GETDEVCAPS_CAN_FREEZE

The dwReturn member is set to TRUE if the device can freeze the image; otherwise, it is set to FALSE.

MCI_OVLY_GETDEVCAPS_CAN_STRETCH

The dwReturn member is set to TRUE if the device can stretch the image to fill the frame; otherwise, it is set to FALSE.

MCI_OVLY_GETDEVCAPS_MAX_WINDOWS

The dwReturn member is set to the maximum number of windows that the device can handle simultaneously.

The following flags can be specified in the dwItem member of MCI_GETDEVCAPS_PARMS for the videodisc device type:

MCI_VD_GETDEVCAPS_CAN_REVERSE

The dwReturn member is set to TRUE if the videodisc player can play in reverse; otherwise, it is set to FALSE. Some players can play CLV discs in reverse as well as CAV discs.

MCI_VD_GETDEVCAPS_CAV

When combined with other items, specifies that the return information applies to CAV format videodiscs. This is the default if no videodisc is inserted.

MCI_VD_GETDEVCAPS_CLV

When combined with other items, specifies that the return information applies to CLV format videodiscs.

MCI_VD_GETDEVCAPS_FAST_RATE

The dwReturn member is set to the standard fast play rate in frames per second.

MCI_VD_GETDEVCAPS_NORMAL_RATE

The dwReturn member is set to the normal play rate in frames per second.

MCI_VD_GETDEVCAPS_SLOW_RATE

The dwReturn member is set to the standard slow play rate in frames per second.

The following flags can be specified in the dwItem member of MCI_GETDEVCAPS_PARMS for the waveaudio device type:

MCI_WAVE_GETDEVCAPS_INPUT

The dwReturn member is set to the total number of waveform input (recording) devices.

MCI_WAVE_GETDEVCAPS_OUTPUT

The dwReturn member is set to the total number of waveform output (playback) devices.

See Also

MCI_GETDEVCAPS_PARMS, MCI_PAUSE, MCI_PLAY, MCI_RECORD, MCI_STOP


MCI_INDEX

The MCI_INDEX command turns the on-screen display on or off. VCR devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_INDEX,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpIndex);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpIndex

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The information presented in the on-screen display is controlled by the MCI_VCR_SET_INDEX flag in the MCI_SET command.

The following additional flags apply to VCR devices:

MCI_SET_OFF

Turns on-screen display off.

MCI_SET_ON

Turns on-screen display on.

See Also

MCI_GENERIC_PARMS, MCI_SET


MCI_INFO

The MCI_INFO command retrieves string information from a device. All devices recognize this command. Information is returned in the lpstrReturn member of the structure identified by lpInfo. The dwRetSize member specifies the buffer length for the returned data.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_INFO,
    DWORD dwFlags, (DWORD) (LPMCI_INFO_PARMS) lpInfo);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpInfo

Address of an MCI_INFO_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional standard and command-specific flag applies to all devices supporting MCI_INFO:

MCI_INFO_PRODUCT

Obtains a description of the hardware associated with a device. Devices should supply a description that identifies both the driver and the hardware used.

The following additional flags apply to the cdaudio device type:

MCI_INFO_MEDIA_IDENTITY

Produces a unique identifier for the audio CD currently loaded in the player being queried. This flag returns a string of 16 hexadecimal digits.

MCI_INFO_MEDIA_UPC

Produces the Universal Product Code (UPC) that is encoded on an audio CD. The UPC is a string of digits. It might not be available for all CDs.

The following additional flags apply to the digitalvideo device type:

MCI_DGV_INFO_ITEM

A constant indicating the information desired is included in the dwItem member of the structure identified by lpInfo. The following constants are defined for digital-video devices:

MCI_DGV_INFO_AUDIO_ALG

Returns the name for the current audio compression algorithm.

MCI_DGV_INFO_AUDIO_QUALITY

Returns the name for the current audio quality descriptor.

MCI_DGV_INFO_STILL_ALG

Returns the name for the current still image compression algorithm.

MCI_DGV_INFO_STILL_QUALITY

Returns the name for the current still image quality descriptor.

MCI_DGV_INFO_USAGE

Returns a string describing usage restrictions that might be imposed by the owner of the visual or audible data in the workspace.

MCI_DGV_INFO_VIDEO_ALG

Returns the name for the current video compression algorithm.

MCI_DGV_INFO_VIDEO_QUALITY

Returns the name for the current video quality descriptor.

MCI_INFO_VERSION

Returns the release level of the device driver and hardware. Device driver developers must document the syntax of the returned string.

MCI_DGV_INFO_TEXT

Obtains the window caption.

MCI_INFO_FILE

Obtains the path and filename of the last file specified with the MCI_OPEN or MCI_LOAD command. If a file has not been specified, the device returns a null-terminated string. This flag is supported only by devices that return TRUE to the MCI_GETDEVCAPS_USES_FILES flag of the MCI_GETDEVCAPS command.

For digital-video devices, lpInfo points to an MCI_DGV_INFO_PARMS structure.

The following additional flags apply to the sequencer device type:

MCI_INFO_COPYRIGHT

Obtains the MIDI file copyright notice from the copyright meta event.

MCI_INFO_FILE

Obtains the filename of the current file. This flag is supported only by devices that return TRUE when you call the MCI_GETDEVCAPS command with the MCI_GETDEVCAPS_USES_FILES flag.

MCI_INFO_NAME

Obtains the sequence name from the sequence/track name meta event.

The following additional flag applies to the vcr device type:

MCI_VCR_INFO_VERSION

Sets lpstrReturn member of the MCI_INFO_PARMS structure to point to the version number. Also sets the dwRetSize member equal to the length of the string pointed to.

The following additional flags apply to the overlay device type:

MCI_INFO_FILE

Obtains the filename of the current file. This flag is supported only by devices that return TRUE to the MCI_GETDEVCAPS_USES_FILES flag of the MCI_GETDEVCAPS command.

MCI_OVLY_INFO_TEXT

Obtains the caption of the window associated with the video-overlay device.

The following additional flags apply to the waveaudio device type:

MCI_INFO_FILE

Obtains the filename of the current file. This flag is supported by devices that return TRUE when you call the MCI_GETDEVCAPS command with the MCI_GETDEVCAPS_USES_FILES flag.

MCI_WAVE_INPUT

Obtains the product name of the current input.

MCI_WAVE_OUTPUT

Obtains the product name of the current output and its value is device specific.

See Also

MCI_DGV_INFO_PARMS, MCI_GETDEVCAPS, MCI_INFO_PARMS, MCI_LOAD, I_OPEN


MCI_LIST

The MCI_LIST command obtains information about the number and types of inputs available to the device. Digital-video and VCR devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_LIST,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpList);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpList

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags apply to the digitalvideo device type:

MCI_DGV_LIST_ALG

The lpstrAlgorithm member of the structure identified by lpList contains an address of a buffer containing the name of an algorithm. The name is used to retrieve the types of quality descriptors associated with an algorithm.

MCI_DGV_LIST_COUNT

Returns the number of options of the specified type.

MCI_DGV_LIST_ITEM

A constant indicating the list type is included in the dwItem member of the structure identified by lpList. This flag is required. Use one of the following constants to indicate the list type:

MCI_DGV_LIST_AUDIO_ALG

The command should retrieve names of audio algorithms.

MCI_DGV_LIST_AUDIO_QUALITY

The command should retrieve audio quality levels. The levels returned are associated with the algorithm referenced by the lpstrAlgorithm member of the structure identified by lpList. If that member is specified using the string “current”, then the qualities associated with the current algorithm are returned.

MCI_DGV_LIST_AUDIO_STREAM

The command should retrieve names of audio streams.

MCI_DGV_LIST_STILL_AL

The command should retrieve names of still algorithms.

MCI_DGV_LIST_STILL_QUALITY

The command should retrieve quality levels. The levels returned are associated with the algorithm referenced by the lpstrAlgorithm member of the structure identified by lpList. If that member is specified using the string “current”, then the qualities associated with the current algorithm are returned.

MCI_DGV_LIST_VIDEO_ALG

The command should retrieve names of video algorithms.

MCI_DGV_LIST_VIDEO_QUALITY

The command should retrieve video quality levels. The levels returned are associated with the algorithm referenced by the lpstrAlgorithm member of the structure identified by lpList. If that member is specified using the string “current”, then the qualities associated with the current algorithm are returned.

MCI_DGV_LIST_VIDEO_SOURCE

The command should return information about the video sources. When used with MCI_DGV_LIST_COUNT, the command returns the number of video sources. When used with MCI_DGV_LIST_NUMBER, the command returns the type of a video source. MCI defines the following types:

MCI_DGV_SETVIDEO_SRC_GENERIC
MCI_DGV_SETVIDEO_SRC_NTSC
MCI_DGV_SETVIDEO_SRC_PAL
MCI_DGV_SETVIDEO_SRC_RGB
MCI_DGV_SETVIDEO_SRC_SECAM
MCI_DGV_SETVIDEO_SRC_SVIDEO

There might be more than one source of each type returned. The generic source type is used when more then one type of signal is allowed for that connector.

MCI_DGV_LIST_VIDEO_STREAM

The command should retrieve names of video streams.

MCI_DGV_LIST_NUMBER

An index is specified in the dwNumber member of the structure identified by lpList. The index must be an integer between 1 and the value returned for the MCI_DGV_LIST_COUNT flag.

For digital-video devices, lpList points to an MCI_DGV_LIST_PARMS structure.

The following additional flags apply to the vcr device type:

MCI_VCR_LIST_AUDIO_SOURCE

List audio inputs or types.

MCI_VCR_LIST_COUNT

Sets the dwReturn member of the structure identified by lpList to the total number of video or audio inputs.

MCI_VCR_LIST_NUMBER

Sets the dwReturn member of the structure identified by lpList to the type of the video or audio input specified by the dwNumber member.

MCI_VCR_LIST_VIDEO_SOURCE

List video inputs or types.

For VCR devices, lpList points to an MCI_VCR_LIST_PARMS structure.

See Also

MCI_DGV_LIST_PARMS, MCI_GENERIC_PARMS, MCI_VCR_LIST_PARMS


MCI_LOAD

The MCI_LOAD command loads a file. Digital-video and video-overlay devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_LOAD,
    DWORD dwFlags, (DWORD) (LPMCI_LOAD_PARMS) lpLoad);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpLoad

Address of an MCI_LOAD_PARMS structure. (Devices with additional parameters might replace this structure with a device-specific structure. For digital-video devices, the lpLoad parameter points to an MCI_DGV_LOAD_PARMS structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flag applies to all devices supporting MCI_LOAD:

MCI_LOAD_FILE

The lpfilename member of the structure identified by lpLoad contains an address of a buffer containing the filename.

The following additional flag is used with the overlay device type:

MCI_OVLY_RECT

The rc member of the structure identified by lpLoad contains a valid display rectangle that identifies the area of the video buffer to update.

For video-overlay devices, the lpLoad parameter points to an MCI_OVLY_LOAD_PARMS structure.

See Also

MCI_DGV_LOAD_PARMS, MCI_LOAD_PARMS, MCI_OVLY_LOAD_PARMS


MCI_MARK

The MCI_MARK command records or erases marks that can be used with the MCI_SEEK command for high-speed searches. VCR devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_MARK,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpMark);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpMark

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags apply to VCR devices:

MCI_VCR_MARK_ERASE

Erases a mark at the current position if one exists.

MCI_VCR_MARK_WRITE

Writes a mark at the current position.

See Also

MCI_GENERIC_PARMS


MCI_MONITOR

The MCI_MONITOR command specifies the presentation source. Digital-video devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_MONITOR,
    DWORD dwFlags, (DWORD) (LPMCI_DGV_MONITOR_PARMS) lpMonitor);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpMonitor

Address of an MCI_DGV_MONITOR_PARMS structure.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags apply to digital-video devices:

MCI_DGV_MONITOR_METHOD

A constant indicating the method of monitoring is included in the dwMethod member of the structure identified by lpMonitor.

When the MCI_DGV_MONITOR_INPUT flag is used in the dwSource member, this selects the method of monitoring. Typically, different monitoring methods have different implications on how the hardware is used. The default monitoring method is selected by the device.

MCI_DGV_MONITOR_SOURCE

A constant indicating the monitor source is included in the dwSource member of the structure identified by lpMonitor.

See Also

MCI_DGV_MONITOR_PARMS


MCI_OPEN

The MCI_OPEN command initializes a device or file. All devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_OPEN,
    DWORD dwFlags, (DWORD) (LPMCI_OPEN_PARMS) lpOpen);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY or MCI_WAIT. For information about these flags, see The Wait, Notify, and Test Flags.

lpOpen

Address of an MCI_OPEN_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The MCI_OPEN_TYPE flag must be used whenever a device is specified in the mciSendCommand function. If you open a device by specifying a device-type constant, you must specify the MCI_OPEN_TYPE_ID flag in addition to MCI_OPEN_TYPE. For a list of device-type constants, see Constants: Device Types.

If the MCI_OPEN_SHAREABLE flag is not specified when a device or file is initially opened, all subsequent MCI_OPEN commands to the device or file will fail. If the device or file is already open and this flag is not specified, the call will fail even if the first open command specified MCI_OPEN_SHAREABLE. Files opened for the MCISEQ.DRV and MCIWAVE.DRV devices are nonshareable.

Case is ignored in the device name, but there cannot be leading or trailing blanks.

To use automatic type selection (via the entries in the registry), assign the filename and file extension to the lpstrElementName member of the structure identified by lpOpen, set the lpstrDeviceType member to NULL, and set the MCI_OPEN_ELEMENT flag.

The following additional flags apply to all devices supporting MCI_OPEN:

MCI_OPEN_ALIAS

An alias is included in the lpstrAlias member of the structure identified by lpOpen.

MCI_OPEN_SHAREABLE

The device or file should be opened as shareable.

MCI_OPEN_TYPE

A device type name or constant is included in the lpstrDeviceType member of the structure identified by lpOpen.

MCI_OPEN_TYPE_ID

The low-order word of the lpstrDeviceType member of the structure identified by lpOpen contains a standard MCI device type identifier and the high-order word optionally contains the ordinal index for the device. Use this flag with the MCI_OPEN_TYPE flag.

The following additional flags apply to compound devices:

MCI_OPEN_ELEMENT

A filename is included in the lpstrElementName member of the structure identified by lpOpen.

MCI_OPEN_ELEMENT_ID

The lpstrElementName member of the structure identified by lpOpen is interpreted as a doubleword value and has meaning internal to the device. Use this flag with the MCI_OPEN_ELEMENT flag.

The following additional flags are used with the digitalvideo device type:

MCI_DGV_OPEN_NOSTATIC

The device should reduce the number of static (system) colors in the palette. This increases the number of colors available for rendering the video stream. This flag applies only to devices that share a palette with Windows.

MCI_DGV_OPEN_PARENT

The parent window handle is specified in the hWndParent member of the structure identified by lpOpen.

MCI_DGV_OPEN_WS

A window style is specified in the dwStyle member of the structure identified by lpOpen.

MCI_DGV_OPEN_16BIT

Indicates a preference for 16-bit MCI device support.

MCI_DGV_OPEN_32BIT

Indicates a preference for 32-bit MCI device support.

For digital-video devices, the lpOpen parameter points to an MCI_DGV_OPEN_PARMS structure.

The following additional flags are used with the overlay device type:

MCI_OVLY_OPEN_PARENT

The parent window handle is specified in the hWndParent member of the structure identified by lpOpen.

MCI_OVLY_OPEN_WS

A window style is specified in the dwStyle member of the structure identified by lpOpen. The dwStyle value specifies the style of the window that the driver will create and display if the application does not provide one. The style parameter takes an integer that defines the window style. These constants are the same as the standard window styles (such as WS_CHILD, WS_OVERLAPPEDWINDOW, or WS_POPUP).

For video-overlay devices, the lpOpen parameter points to an MCI_OVLY_OPEN_PARMS structure.

The following additional flag is used with the waveaudio device type:

MCI_WAVE_OPEN_BUFFER

A buffer length is specified in the dwBufferSeconds member of the structure identified by lpOpen.

For waveform-audio devices, the lpOpen parameter points to an MCI_WAVE_OPEN_PARMS structure. The MCIWAVE driver requires an asychronous waveform-audio device.

See Also

CreateWindow, MCI_DGV_OPEN_PARMS, MCI_OPEN_PARMS, MCI_OVLY_OPEN_PARMS, MCI_WAVE_OPEN_PARMS, mciSendCommand


MCI_PASTE

The MCI_PASTE command pastes data from the clipboard into a file. Digital-video devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_PASTE,
    DWORD dwlags, (DWORD) (LPMCI_DGV_PASTE_PARMS) lpPaste);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or  MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpPaste

Address of an MCI_DGV_PASTE_PARMS structure.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags apply to digital-video devices:

MCI_DGV_PASTE_AT

A rectangle is included in the rc member of the structure identified by lpPaste. The first two values of the rectangle specify the point within the frame to place the clipboard information. If the rectangle height and width are nonzero, the clipboard contents are scaled to those dimensions when they are pasted in the frame. If the flag is omitted, MCI_PASTE defaults to the entire frame rectangle.

MCI_DGV_PASTE_AUDIO_STREAM

An audio-stream number is included in the dwAudioStream member of the structure identified by lpPaste. If only one audio stream exists on the clipboard, the audio data is pasted into the designated stream. If more than one audio stream exists on the clipboard, the stream indicates the starting number for the stream sequences. If you use this flag and also want to paste video, you must also use the MCI_DGV_PASTE_VIDEO_STREAM flag. (If neither flag is specified, all audio and video streams are pasted starting with the first audio and video stream. Each pasted stream retains its original stream number.)

MCI_DGV_PASTE_INSERT

Clipboard data should be inserted in the existing workspace at the position specified by the MCI_TO flag. Any existing data after the insertion point is moved in the workspace to make room. This is the default.

MCI_DGV_PASTE_OVERWRITE

Clipboard data should replace data already present in the workspace. The workspace data replaced follows the insertion point.

MCI_DGV_PASTE_VIDEO_STREAM

A video-stream number is included in the dwVideoStream member of the structure identified by lpPaste. If only one video stream exists on the clipboard, the video data is pasted into the designated stream. If more than one video stream exists on the clipboard, the stream indicates the starting number for the stream sequences. If you use this flag and also want to paste audio, you must also use the MCI_DGV_PASTE_AUDIO_STREAM flag. (If neither flag is specified, all audio and video streams are pasted starting with the first audio and video stream. Each pasted stream retains its original stream number.)

MCI_TO

A position value is included in the dwTo member of the structure identified by lpPaste. The position value specifies the position to begin pasting data into the workspace. If this flag is omitted, the position defaults to the current position.

See Also

MCI_DGV_PASTE_PARMS


MCI_PAUSE

The MCI_PAUSE command pauses the current action. CD audio, digital-video, MIDI sequencer, VCR, videodisc, and waveform-audio devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_PAUSE,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpPause);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpPause

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The difference between the MCI_STOP and MCI_PAUSE commands depends on the device. If possible, MCI_PAUSE suspends device operation but leaves the device ready to resume play immediately. With the MCICDA, MCISEQ, and MCIPIONR drivers, the MCI_PAUSE command works the same as the MCI_STOP command.

For digital-video devices, the lpPause parameter points to an MCI_DGV_PAUSE_PARMS structure.

See Also

MCI_DGV_PAUSE_PARMS, MCI_GENERIC_PARMS, MCI_STOP


MCI_PLAY

The MCI_PLAY command signals the device to begin transmitting output data. CD audio, digital-video, MIDI sequencer, videodisc, VCR, and waveform-audio devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_PLAY,
    DWORD dwFlags, (DWORD) (LPMCI_PLAY_PARMS ) lpPlay);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpPlay

Address of an MCI_PLAY_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags apply to all devices supporting MCI_PLAY:

MCI_FROM

A starting location is included in the dwFrom member of the structure identified by lpPlay. The units assigned to the position values are specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. If MCI_FROM is not specified, the starting location defaults to the current position.

MCI_TO

An ending location is included in the dwTo member of the structure identified by lpPlay. The units assigned to the position values are specified with the MCI_SET_TIME_FORMAT flag of MCI_SET. If MCI_TO is not specified, the ending location defaults to the end of the media.

The following additional flags are used with the digitalvideo device type:

MCI_DGV_PLAY_REPEAT

Playback should start again at the beginning when the end of the content is reached.

MCI_DGV_PLAY_REVERSE

Playback should occur in reverse.

MCI_MCIAVI_PLAY_WINDOW

Playback should occur in the window associated with a device instance (the default). (This flag is specific to MCIAVI.DRV.)

MCI_MCIAVI_PLAY_FULLSCREEN

Playback should use a full-screen display. Use this flag only when playing compressed or 8-bit files.

For digital-video devices, lpPlay points to an MCI_DGV_PLAY_PARMS structure.

The following additional flags are used with the vcr device type:

MCI_VCR_PLAY_AT

The dwAt member of the structure identified by lpPlay contains a time when the entire command begins, or if the device is cued, when the device reaches the from position given by the MCI_CUE command.

MCI_VCR_PLAY_REVERSE

Playback should occur in reverse.

MCI_VCR_PLAY_SCAN

Playback should be as fast as possible while maintaining video output.

For VCR devices, lpPlay points to an MCI_VCR_PLAY_PARMS structure.

The following additional flags are used with the videodisc device type:

MCI_VD_PLAY_FAST

Play fast.

MCI_VD_PLAY_REVERSE

Play in reverse.

MCI_VD_PLAY_SCAN

Scan quickly.

MCI_VD_PLAY_SLOW

Play slowly.

MCI_VD_PLAY_SPEED

The play speed is included in the dwSpeed member in the structure identified by lpPlay.

See Also

MCI_CUE, MCI_DGV_PLAY_PARMS, MCI_PLAY_PARMS, MCI_SET, MCI_VCR_PLAY_PARMS, MCI_VD_PLAY_PARMS


MCI_PUT

The MCI_PUT command sets the source, destination, and frame rectangles. Digital-video and video-overlay devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_PUT,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpDest);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpDest

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags are used with the digitalvideo device type:

MCI_DGV_PUT_CLIENT

The rectangle defined for MCI_DGV_RECT applies to the position of the client window. The rectangle specified is relative to the parent window of the display window. MCI_DGV_PUT_WINDOW must be set concurrently with this flag.

MCI_DGV_PUT_DESTINATION

The rectangle defined for MCI_DGV_RECT specifies a destination rectangle. The destination rectangle specifies the portion of the client window associated with this device driver instance that shows the image or video.

MCI_DGV_PUT_FRAME

The rectangle defined for MCI_DGV_RECT applies to the frame rectangle. The frame rectangle specifies the portion of the frame buffer used as the destination of the video images obtained from the video rectangle. The video should be scaled to fit within the frame buffer rectangle.

The rectangle is specified in frame buffer coordinates. The default rectangle is the full frame buffer. Specifying this rectangle lets the device scale the image as it digitizes the data. Devices that cannot scale the image reject this command with MCIERR_UNSUPPORTED_FUNCTION. You can use the MCI_GETDEVCAPS_CAN_STRETCH flag with the MCI_GETDEVCAPS command to determine if a device scales the image. A device returns FALSE if it cannot scale the image.

MCI_DGV_PUT_SOURCE

The rectangle defined for MCI_DGV_RECT specifies a source rectangle. The source rectangle specifies which portion of the frame buffer is to be scaled to fit into the destination rectangle.

MCI_DGV_PUT_VIDEO

The rectangle defined for MCI_DGV_RECT applies to the video rectangle. The video rectangle specifies which portion of the current presentation source is stored in the frame buffer. The rectangle is specified using the natural coordinates of the presentation source. It allows the specification of cropping that occurs prior to storing images and video in the frame buffer. The default rectangle is the full active scan area or the full decompressed images and video.

MCI_DGV_PUT_WINDOW

The rectangle defined for MCI_DGV_RECT applies to the display window. This rectangle is relative to the parent window of the display window (usually the desktop). If the window is not specified, it defaults to the initial window size and position.

MCI_DGV_RECT

The rc member of the structure identified by lpDest contains a valid rectangle.

For digital-video devices, lpDest points to an MCI_DGV_PUT_PARMS structure.

The following additional flags are used with the overlay device type:

MCI_OVLY_PUT_DESTINATION

The rectangle defined for MCI_OVLY_RECT specifies the area of the client window used to display an image. The rectangle contains the offset and visible extent of the image relative to the window origin. If the frame is being stretched, the source is stretched to the destination rectangle.

MCI_OVLY_PUT_FRAME

The rectangle defined for MCI_OVLY_RECT specifies the area of the video buffer used to receive the video image. The rectangle contains the offset and extent of the buffer area relative to the video buffer origin.

MCI_OVLY_PUT_SOURCE

The rectangle defined for MCI_OVLY_RECT specifies the area of the video buffer used as the source of the digital image. The rectangle contains the offset and extent of the clipping rectangle for the video buffer relative to its origin.

MCI_OVLY_PUT_VIDEO

The rectangle defined for MCI_OVLY_RECT specifies the area of the video source capture by the video buffer. The rectangle contains the offset and extent of the clipping rectangle for the video source relative to its origin.

MCI_OVLY_RECT

The rc member of the structure identified by lpDest contains a valid display rectangle. If this flag is not specified, the default rectangle matches the coordinates of the video buffer or window being clipped.

For video-overlay devices, lpDest points to an MCI_OVLY_RECT_PARMS structure.

See Also

MCI_DGV_PUT_PARMS, MCI_GENERIC_PARMS, MCI_GETDEVCAPS, MCI_OVLY_RECT_PARMS


MCI_QUALITY

The MCI_QUALITY command defines a custom quality level for audio, video, or still image data compression. Digital-video devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_QUALITY,
    DWORD dwFlags, (DWORD) (LPMCI_DGV_QUALITY_PARMS) lpQuality);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpQuality

Address of an MCI_DGV_QUALITY_PARMS structure.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The name defined for this quality level can be used when setting the audio, video, or still quality with the MCI_SETAUDIO and MCI_SETVIDEO commands.

The following additional flags apply to digital-video devices:

MCI_QUALITY_ALG

The lpstrAlgorithm member of the structure identified by lpQuality contains an address of a buffer containing the name of the algorithm. This algorithm must be supported by the device driver, and must be compatible with the audio, still, or video descriptor that is used. If this flag is omitted, the current algorithm is used.

MCI_QUALITY_DIALOG

The device driver should display a dialog box for specifying the quality level. The dialog box has algorithm-specific fields used internally by the device driver to create a structure describing a specific quality level.

MCI_QUALITY_HANDLE

The dwHandle member of the structure identified by lpQuality contains a handle to a structure. The structure contains algorithmic-specific data describing the specific quality level. The format of the structures for the algorithms is device dependent.

MCI_QUALITY_ITEM

A constant indicating the type of algorithm is included in the dwItem member of the structure identified by lpQuality.

MCI_QUALITY_NAME

The lpstrName member of the structure identified by lpQuality contains an address of a buffer containing the quality descriptor.

See Also

MCI_DGV_QUALITY_PARMS, MCI_SETAUDIO, MCI_SETVIDEO


MCI_REALIZE

The MCI_REALIZE command causes a graphic device to realize its palette into a device context (DC). Digital-video devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_REALIZE,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpRealize);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpRealize

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

You should use this command when your application receives the WM_QUERYNEWPALETTE message.

The following additional flags are used with the digitalvideo device type:

MCI_DGV_REALIZE_BKGD

Realizes the palette as a background palette.

MCI_DGV_REALIZE_NORM

Realizes the palette normally. This is the default.

For digital-video devices, the lpRealize parameter points to an MCI_REALIZE_PARMS  structure. For more information, see comments in the MCI_GENERIC_PARMS structure.

See Also

MCI_GENERIC_PARMS


MCI_RECORD

The MCI_RECORD command starts recording from the current position or from one specified location to another specified location. VCR and waveform-audio devices recognize this command. Although digital-video devices and MIDI sequencers also recognize this command, the MCIAVI and MCISEQ drivers do not implement it.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_RECORD,

    DWORD dwFlags, (DWORD) (LPMCI_RECORD_PARMS) lpRecord);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpRecord

Address of an MCI_RECORD_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

This command is supported by devices that return TRUE when you call the MCI_GETDEVCAPS command with the MCI_GETDEVCAPS_CAN_RECORD flag. For the MCIWAVE driver, all data recorded after a file is opened is discarded if the file is closed without saving it.

The following additional flags apply to all devices supporting MCI_RECORD:

MCI_FROM

A starting location is included in the dwFrom member of the structure identified by lpRecord. The units assigned to the position values are specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. If MCI_FROM is not specified, the starting location defaults to the current position.

MCI_RECORD_INSERT

Newly recorded information should be inserted or pasted into the existing data. Some devices might not support this. If supported, this is the default.

MCI_RECORD_OVERWRITE

Data should overwrite existing data. The MCIWAVE.DRV device returns MCIERR_UNSUPPORTED_FUNCTION in response to this flag.

MCI_TO

An ending location is included in the dwTo member of the structure identified by lpRecord. The units assigned to the position values are specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. If MCI_TO is not specified, the ending location defaults to the end of the content.

The following additional flags are used with the digitalvideo device type:

MCI_DGV_RECORD_AUDIO_STREAM

An audio-stream number is included in the dwAudioStream member of the structure identified by lpRecord. If you omit this flag, audio data is recorded into the first physical stream.

MCI_DGV_RECORD_HOLD

When recording stops, the screen will hold the last image and will not resume showing the video until an MCI_MONITOR command is issued.

MCI_DGV_RECORD_VIDEO_STREAM

A video-stream number is included in the dwVideoStream member of the structure identified by lpRecord. If you omit this flag, video data is recorded into the first physical stream.

MCI_DGV_RECT

A rectangle is specified in the rc member of the structure identified by lpRecord. The rectangle specifies the region of the external input used as the source for the pixels compressed and saved. This rectangle defaults to the rectangle specified (or defaulted) by the MCI_DGV_PUT_VIDEO flag for the MCI_PUT command. When it is set differently than the video rectangle, what is displayed is not what is recorded

For digital-video devices, lpRecord points to an MCI_DGV_RECORD_PARMS structure.

The following additional flags are used with the vcr device type:

MCI_VCR_RECORD_AT

The dwAt member of the structure identified by lpRecord contains a time when the entire command begins, or if the device is cued, when the device reaches the from position given by the cue command.

MCI_VCR_RECORD_INITIALIZE

Seek the device to the start of the media, begin recording blank video and audio, and record timecode, if possible.

For VCR devices, lpRecord points to an MCI_VCR_RECORD_PARMS structure.

See Also

MCI_DGV_RECORD_PARMS, MCI_GETDEVCAPS, MCI_MONITOR, MCI_PUT, MCI_RECORD_PARMS, MCI_SET, MCI_VCR_RECORD_PARMS


MCI_RESERVE

The MCI_RESERVE command allocates contiguous disk space for the workspace of the device driver instance for use with subsequent recording. Digital-video devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_RESERVE,
    DWORD dwFlags, (DWORD) (LPMCI_DGV_RESERVE_PARMS) lpReserve);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpReserve

Address of an MCI_DGV_RESERVE_PARMS structure.

Return Values

Returns zero if successful or an error otherwise.

Remarks

If the workspace contains unsaved data, this data is lost. If disk space is not reserved prior to recording, the MCI_RECORD command performs an implied reserve with device-specific default parameters. On some implementations, reserve is not required and might be ignored by the device driver. Explicitly reserving space gives you better control over when the delay for disk allocation occurs, how much space is allocated, and where the disk space is allocated. The amount and location of disk space already reserved for this device instance can be changed by issuing MCI_RESERVE again. Any allocated and still unused disk space is not deallocated until any recorded data is saved or until the device driver instance is closed.

If video is turned off with the MCI_OFF flag of the MCI_SETVIDEO command, the space reserved does not include any video. If audio is turned off with the MCI_OFF flag of the MCI_SETAUDIO command, the space reserved does not include any audio. If both audio and video are turned off or if the requested size is zero, no space is reserved and any existing reserved space is deallocated.

The following additional flags apply to digital-video devices:

MCI_DGV_RESERVE_IN

The lpstrPath member of the structure identified by lpReserve contains an address of a buffer containing the location of a temporary file. The buffer contains only the drive and directory path of the file used to hold recorded data; the filename is specified by the device driver. This temporary file is deleted when the device instance is closed unless it is explicitly saved. If this flag is omitted, the device driver specifies where disk space is allocated.

MCI_DGV_RESERVE_SIZE

The dwSize member of the structure identified by lpReserve specifies the approximate amount of disk space to reserve in the workspace for recording. The value is specified in the current time format. The amount of disk space is estimated from the requested time and from which file format and video and audio algorithm and quality values are in effect. If this flag is omitted, the device driver might use a default value it defines.

See Also

MCI_DGV_RESERVE_PARMS, MCI_RECORD, MCI_SETAUDIO, MCI_SETVIDEO


MCI_RESTORE

The MCI_RESTORE command copies a bitmap from a file to the frame buffer. Digital-video devices recognize this command. This command performs the opposite action of the MCI_CAPTURE command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_RESTORE,
    DWORD dwFlags, (DWORD) (LPMCI_DGV_RESTORE_PARMS) lpRestore);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpRestore

Address of an MCI_DGV_RESTORE_PARMS structure.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The implementation can recognize a variety of image formats, but a Windows device-independent bitmap (DIB) is always accepted.

The following additional flags apply to digital-video devices:

MCI_DGV_RESTORE_FROM

The lpstrFileName member of the structure identified by lpRestore contains an address of a buffer containing the source filename. The filename is required.

MCI_DGV_RESTORE_AT

The rc member of the structure identified by lpRestore contains a valid rectangle. The rectangle specifies a region of the frame buffer relative to its origin. The first pair of coordinates specifies the upper left corner of the rectangle; the second pair specifies the width and height. If this flag is not specified, the image is copied to the upper left corner of the frame buffer.

See Also

MCI_CAPTURE, MCI_DGV_RESTORE_PARMS


MCI_RESUME

The MCI_RESUME command causes a paused device to resume the paused operation. Digital-video, VCR, and waveform-audio devices recognize this command. Although CD audio, MIDI sequencer, and videodisc devices also recognize this command, the MCICDA, MCISEQ, and MCIPIONR device drivers do not support it.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_RESUME,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpResume);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpResume

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

This command resumes playing and recording without changing the current track position set with MCI_PLAY or MCI_RECORD.

See Also

MCI_GENERIC_PARMS, MCI_PLAY, MCI_RECORD


MCI_SAVE

The MCI_SAVE command saves the current file. Devices that modify files should not destroy the original copy until they receive the save message. Video-overlay and waveform-audio devices recognize this command. Although digital-video devices and MIDI sequencers also recognize this command, the MCIAVI and MCISEQ drivers do not implement it.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_SAVE,
    DWORD dwFlags, (DWORD) (LPMCI_SAVE_PARMS ) lpSave);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpSave

Address of an MCI_SAVE_PARMS structure. (Devices with additional parameters might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

This command is supported by devices that return TRUE when you call the MCI_GETDEVCAPS command with the MCI_GETDEVCAPS_CAN_SAVE flag.

The following additional flag applies to all devices supporting MCI_SAVE:

MCI_SAVE_FILE

The lpfilename member of the structure identified by lpSave contains an address of a buffer containing the destination filename.

The following additional flags are used with the digitalvideo device type:

MCI_DGV_RECT

The rc member of the structure identified by lpSave contains a valid rectangle. The rectangle specifies a region of the frame buffer that will be saved to the specified file. The first pair of coordinates specifies the upper left corner of the rectangle; the second pair specifies the width and height. Digital-video devices must use the MCI_CAPTURE command to capture the contents of the frame buffer. (Video-overlay devices should also use MCI_CAPTURE.) This flag is for compatibility with the existing MCI video-overlay command set.

MCI_DGV_SAVE_ABORT

Stops a save operation in progress. This must be the only flag present.

MCI_DGV_SAVE_KEEPRESERVE

Unused disk space left over from the original MCI_RESERVE command is not deallocated.

For digital-video devices, the lpSave parameter points to an MCI_DGV_SAVE_PARMS structure.

The following additional flag is used with the overlay device type:

MCI_OVLY_RECT

The rc member of the structure identified by lpSave contains a valid display rectangle indicating the area of the video buffer to save.

For video-overlay devices, the lpSave parameter points to an MCI_OVLY_SAVE_PARMS structure.

See Also

MCI_CAPTURE, MCI_DGV_SAVE_PARMS, MCI_GETDEVCAPS, MCI_OVLY_SAVE_PARMS, MCI_RESERVE, MCI_SAVE_PARMS


MCI_SEEK

The MCI_SEEK command changes the current position in the content as quickly as possible. Video and audio output are disabled during the seek. After the seek is complete, the device is stopped. CD audio, digital-video, MIDI sequencer, VCR, videodisc, and waveform-audio devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_SEEK,
    DWORD dwFlags, (DWORD) (LPMCI_SEEK_PARMS) lpSeek);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpSeek

Address of an MCI_SEEK_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

If a data sample size for a device is larger than 1 byte (such as with waveform-audio stereo data), this command moves to the beginning of the nearest sample when a specified position does not coincide with the start of a sample.

The following additional flags apply to all devices supporting MCI_SEEK:

MCI_SEEK_TO_END

Seek to the end of the content.

MCI_SEEK_TO_START

Seek to the beginning of the content.

MCI_TO

A position is included in the dwTo member of the structure identified by lpSeek. The units assigned to the position values are specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. Do not use this flag with MCI_SEEK_TO_END or MCI_SEEK_TO_START.

The following additional flags are used with the vcr device type:

MCI_VCR_SEEK_AT

The dwAt member of the structure identified by lpSeek contains a time when the entire command begins.

MCI_VCR_SEEK_MARK

The dwMark member of the structure identified by lpSeek contains the numbered mark to search for.

MCI_VCR_SEEK_REVERSE

Seek direction is reverse; this is used only with the MCI_VCR_SEEK_MARK flag.

For VCR devices, the lpSeek parameter points to an MCI_VCR_SEEK_PARMS structure.

The following additional flag is used with the videodisc device type:

MCI_VD_SEEK_REVERSE

Seek direction is reverse.

See Also

MCI_SEEK_PARMS, MCI_SET, MCI_VCR_SEEK_PARMS


MCI_SET

The MCI_SET command sets device information. CD audio, digital-video, MIDI sequencer, VCR, videodisc, video-overlay, and waveform-audio devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_SET,
    DWORD dwFlags, (DWORD) (LPMCI_SET_PARMS) lpSet);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpSet

Address of an MCI_SET_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags apply to all devices supporting MCI_SET:

MCI_SET_AUDIO

An audio channel number is included in the dwAudio member of the structure identified by lpSet. This flag must be used with MCI_SET_ON or MCI_SET_OFF. Use one of the following constants to indicate the channel number:

MCI_SET_AUDIO_ALL

All audio channels.

MCI_SET_AUDIO_LEFT

Left channel.

MCI_SET_AUDIO_RIGHT

Right channel.

MCI_SET_DOOR_CLOSED

Closes the media cover (if any).

MCI_SET_DOOR_OPEN

Opens the media cover (if any).

MCI_SET_OFF

Disables the specified video or audio channel.

MCI_SET_ON

Enables the specified video or audio channel.

MCI_SET_TIME_FORMAT

A time format parameter is included in the dwTimeFormat member of the structure identified by lpSet. The following flags are used with this flag:

MCI_FORMAT_BYTES

Within a PCM (Pulse Code Modulation) data format, changes the time member description to bytes for input or output. Recognized by the waveaudio device type.

MCI_FORMAT_FRAMES

Subsequent commands will use frames. Recognized by the digitalvideo, vcr, and videodisc device types.

MCI_FORMAT_HMS

Changes the time format to hours, minutes, and seconds. Recognized by the vcr and videodisc device types.

MCI_FORMAT_MILLISECONDS

Changes the time format to milliseconds. Recognized by all device types.

MCI_FORMAT_MSF

Changes the time format to minutes, seconds, and frames. Recognized by the cdaudio and vcr device types.

MCI_FORMAT_SAMPLES

Changes the time format to samples for input or output. Recognized by the waveaudio device type.

MCI_FORMAT_SMPTE_24, MCI_FORMAT_SMPTE_25, and MCI_FORMAT_SMPTE_30

Sets the time format to 24, 25, and 30 frame SMPTE (Society of Motion Picture and Television Engineers), respectively. Recognized by the sequencer and vcr device types.

MCI_FORMAT_SMPTE_30DROP

Sets the time format to 30 drop-frame SMPTE. Recognized by the sequencer and vcr device types.

MCI_FORMAT_TMSF

Changes the time format to tracks, minutes, seconds, and frames. (MCI uses continuous track numbers.) Recognized by the cdaudio and vcr device types.

MCI_SET_VIDEO

Sets the video signal on or off. This flag must be used with either MCI_SET_ON or MCI_SET_OFF. Devices that do not have video return MCIERR_UNSUPPORTED_FUNCTION.

The following additional flags are used with the digitalvideo device type:

MCI_DGV_SET_FILEFORMAT

A file format parameter is included in the dwFileFormat member of the structure identified by lpSet. For digital-video devices, the file format is used for save or capture commands. If omitted, this might default to a device driver defined format. If the specified file format conflicts with the currently selected algorithm and quality, then they are changed to the defaults for the file format. The following file format constants are defined:

MCI_DGV_FF_AVI

AVI format.

MCI_DGV_FF_AVSS

AVSS format.

MCI_DGV_FF_DIB

DIB format.

MCI_DGV_FF_JFIF

JFIF format.

MCI_DGV_FF_JPEG

JPEG format.

MCI_DGV_FF_MPEG

MPEG format.

MCI_DGV_FF_RDIB

RLE DIB format.

MCI_DGV_FF_RJPEG

RJPEG format.

MCI_DGV_SET_SEEK_EXACTLY

Sets the format used for positioning. This flag must be used with MCI_SET_ON or MCI_SET_OFF. If MCI_SET_ON is specified, playing or recording precisely accesses the frame specified with the MCI_FROM flag. This might add some extra delay if the requested frame is not a key frame. If MCI_SET_OFF is specified, the device will seek to a key-frame image that precedes the requested frame. For some files and devices, this might be the first frame of the file. The default for this flag is device dependent.

MCI_DGV_SET_SPEED

A speed parameter is included in the dwSpeed member of the structure identified by lpSet. Speed is specified as a ratio between the nominal frame rate and the desired frame rate where the nominal frame rate is designated as 1000. Half speed is 500 and double speed is 2000. The allowable speed range is dependent on the device and possibly the file, too.

MCI_DGV_SET_STILL

When used with MCI_DGV_SET_FILEFORMAT, MCI_SET sets the file format used for capture commands.

For digital-video devices, the lpSet parameter points to an MCI_DGV_SET_PARMS structure.

The following additional flags are used with the sequencer device type:

MCI_SEQ_FORMAT_SONGPTR

Sets the time format to song pointer units.

MCI_SEQ_SET_MASTER

Sets the sequencer as a source of synchronization data and indicates that the type of synchronization is specified in the dwMaster member of the structure identified by lpSet. MCISEQ returns MCIERR_UNSUPPORTED_FUNCTION. The following constants are defined for the synchronization type:

MCI_SEQ_MIDI

The sequencer will send MIDI format synchronization data.

MCI_SEQ_SMPTE

The sequencer will send SMPTE format synchronization data.

MCI_SEQ_NONE

The sequencer will not send synchronization data.

MCI_SEQ_SET_OFFSET

Changes the SMPTE offset of a sequence to that specified by the dwOffset member of the structure identified by lpSet. This affects only sequences with a SMPTE division type.

MCI_SEQ_SET_PORT

Sets the output MIDI port of a sequence to that specified by the MIDI device identifier in the dwPort member of the structure identified by lpSet. The device closes the previous port (if any), and attempts to open and use the new port. If it fails, it returns an error and reopens the previously used port (if any). The following constants are defined for the ports:

MCI_SEQ_NONE

Closes the previously used port (if any). The sequencer behaves exactly the same as if a port were open, except no MIDI message is sent.

MIDI_MAPPER

Sets the port opened to the MIDI mapper.

MCI_SEQ_SET_SLAVE

Sets the sequencer to receive synchronization data and indicates that the type of synchronization is specified in the dwSlave member of the structure identified by lpSet. MCISEQ returns MCIERR_UNSUPPORTED_FUNCTION. The following constants are defined for the synchronization type:

MCI_SEQ_FILE

Sets the sequencer to receive synchronization data contained in the MIDI file.

MCI_SEQ_MIDI

Sets the sequencer to receive MIDI synchronization data.

MCI_SEQ_NONE

Sets the sequencer to ignore synchronization data in a MIDI stream.

MCI_SEQ_SMPTE

Sets the sequencer to receive SMPTE synchronization data.

MCI_SEQ_SET_TEMPO

Changes the tempo of the MIDI sequence to that specified by the dwTempo member of the structure pointed to by lpSet. For sequences with division type PPQN, tempo is specified in beats per minute; for sequences with division type SMPTE, tempo is specified in frames per second.

For sequencer devices, the lpSet parameter points to an MCI_SEQ_SET_PARMS structure.

The following additional flags are used with the vcr device type:

MCI_VCR_SET_ASSEMBLE_RECORD

Sets the device to record in assemble or insert modes (when assemble is off, insert is on, and vice-versa). Use with one of the following flag:

MCI_SET_ON

Sets assemble record on, and turns insert record off. Records all video, audio and timecode tracks.

MCI_SET_OFF

Sets assemble record off, and turns insert record on. When assemble record is off, individual tracks of video, audio, and timecode can be selected for recording.

MCI_VCR_SET_CLOCK

The dwClock member of the structure identified by lpSet contains the new clock time.

MCI_VCR_SET_COUNTER_FORMAT

The dwCounterFormat member of the structure identified by lpSet contains a constant specifying the new counter-time format to be used by the status counter. For a list of valid constants, see MCI_SET_TIME_FORMAT in the list of additional flags for this command.

MCI_VCR_SET_COUNTER_VALUE

The dwCounterValue member of the structure identified by lpSet contains the new counter value.

MCI_VCR_SET_INDEX

The dwIndex member of the structure identified by lpSet contains a constant indicating the contents of the on-screen display and must be one of the following:

MCI_VCR_INDEX_COUNTER

Displays counter.

MCI_VCR_INDEX_DATE

Displays date.

MCI_VCR_INDEX_TIME

Displays time.

MCI_VCR_INDEX_TIMECODE

Displays timecode.

For more information, see the MCI_INDEX command.

MCI_VCR_SET_PAUSE_TIMEOUT

The dwPauseTimeout member of the structure identified by lpSet contains the maximum duration, in milliseconds, of a pause command.

MCI_VCR_SET_POSTROLL_DURATION

The dwPostrollDuration member of the structure identified by lpSet contains the videotape length, in the current time format, needed to brake the VCR transport when a stop or pause command is issued.

MCI_VCR_SET_POWER

Sets the power on or off. Must be used with one of the following flags:

MCI_SET_OFF

Turns power off.

MCI_SET_ON

Turns power on.

MCI_VCR_SET_PREROLL_DURATION

The dwPrerollDuration member of the structure identified by lpSet contains the videotape length, in the current time format, needed to stabilize the VCR output.

MCI_VCR_SET_RECORD_FORMAT

The dwRecordFormat member of the structure identified by lpSet contains a constant describing the record speed, which must be one of the following:

MCI_VCR_FORMAT_EP

Records at slow speed.

MCI_VCR_FORMAT_LP

Records at medium-slow speed.

MCI_VCR_FORMAT_SP

Records at standard speed.

MCI_VCR_SET_SPEED

The dwSpeed member of the structure identified by lpSet contains the new speed setting, where 1000 is normal speed, 2000 is double speed, and 500 is half speed, and so on.

MCI_VCR_SET_TAPE_LENGTH

The dwTapeLength member of the structure identified by lpSet contains the new length of the tape, provided that the length of the tape is undetectable.

MCI_VCR_SET_TIME_MODE

The dwTimeMode member of the structure identified by lpSet contains a constant indicating the new positional time mode. The following constants are valid:

MCI_VCR_TIME_COUNTER

Forces the device to use counter exclusively.

MCI_VCR_TIME_DETECT

Each time a new videotape is inserted into the device, or the mode changes from not ready to ready, the device should attempt to determine if there is timecode available on the videotape. If timecode is available, use timecode in all subsequent commands that specify positions. Otherwise, use the counter.

MCI_VCR_TIME_TIMECODE

Forces the device to use timecode exclusively.

MCI_VCR_SET_TRACKING

Tunes the speed of the VCR tape transport with a fine adjustment, and must be used with one of the following flags:

MCI_VCR_PLUS

Increases the tape transport speed.

MCI_VCR_MINUS

Decreases the tape transport speed.

MCI_VCR_RESET

Returns the tracking adjustment to zero.

For VCR devices, the lpSet parameter points to an MCI_VCR_SET_PARMS structure.

The following additional flag is used with the videodisc device type:

MCI_VD_FORMAT_TRACK

Changes the time format to tracks. MCI uses continuous track numbers.

The following additional flags are used with the waveaudio device type:

MCI_WAVE_INPUT

Sets the input used for recording to the wInput member of the structure identified by lpSet.

MCI_WAVE_OUTPUT

Sets the output used for playing to the wOutput member of the structure identified by lpSet.

MCI_WAVE_SET_ANYINPUT

Any wave input compatible with the current format can be used for recording.

MCI_WAVE_SET_ANYOUTPUT

Any wave output compatible with the current format can be used for playing.

MCI_WAVE_SET_AVGBYTESPERSEC

Sets the bytes per second used for playing, recording, and saving to the nAvgBytesPerSec member of the structure identified by lpSet.

MCI_WAVE_SET_BITSPERSAMPLE

Sets the bits per sample used for playing, recording, and saving to the nBitsPerSample member of the PCM data format identified by lpSet.

MCI_WAVE_SET_BLOCKALIGN

Sets the block alignment used for playing, recording, and saving to the nBlockAlign member of the structure identified by lpSet.

MCI_WAVE_SET_CHANNELS

The number of channels is indicated in the nChannels member of the structure identified by lpSet.

MCI_WAVE_SET_FORMATTAG

Sets the format type used for playing, recording, and saving to the wFormatTag member of the structure identified by lpSet. Specifying WAVE_FORMAT_PCM changes the format to PCM.

MCI_WAVE_SET_SAMPLESPERSEC

Sets the samples per second used for playing, recording, and saving to the nSamplesPerSec member of the structure identified by lpSet.

For waveform-audio devices, the lpSet parameter points to an MCI_WAVE_SET_PARMS structure.

Several properties of waveform-audio data are defined when the file to store the data is created. These properties describe how the data is structured within the file and cannot be changed once recording begins. The following list of flags identifies these properties:

•	MCI_WAVE_SET_AVGBYTESPERSEC

•	MCI_WAVE_SET_BITSPERSAMPLE

•	MCI_WAVE_SET_BLOCKALIGN

•	MCI_WAVE_SET_CHANNELS

•	MCI_WAVE_SET_FORMATTAG

•	MCI_WAVE_SET_SAMPLESPERSEC

See Also

MCI_DGV_SET_PARMS, MCI_INDEX, MCI_SEQ_SET_PARMS, MCI_SET_PARMS, MCI_VCR_SET_PARMS, MCI_WAVE_SET_PARMS


MCI_SETAUDIO

The MCI_SETAUDIO command sets values associated with audio playback and capture. Digital-video and VCR devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_SETAUDIO,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpSetAudio);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpSetAudio

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following flags apply to the digitalvideo device type:

MCI_DGV_SETAUDIO_ALG

The lpstrAlgorithm member of the structure identified by lpSetAudio contains an address of a buffer containing the name of an audio compression algorithm. The compression algorithm is used by subsequent MCI_RESERVE or MCI_RECORD commands. The available algorithms are device dependent. If the algorithm is incompatible with the current file format, the file format is changed to the default format for the algorithm.

MCI_DGV_SETAUDIO_CLOCKTIME

The time specified is in milliseconds and is absolute time when used with MCI_DGV_SETAUDIO_OVER. (This time is not in step with the playing of the workspace.)

MCI_DGV_SETAUDIO_INPUT

Modifies the bass, treble, or volume flag so that it affects the input signal and modifies what is recorded. If possible, this is the default when monitoring the input.

MCI_DGV_SETAUDIO_ITEM

An audio constant is specified in the dwItem member of the structure identified by lpSetAudio. The constant identifies the value that is being set. The following constants are defined:

MCI_DGV_SETAUDIO_AVGBYTESPERSEC

The average number of bytes is specified in the dwValue member of the structure identified by lpSetAudio. This value sets the average number of bytes per second for playing or recording in the PCM (Pulse Code Modulation) and ADPCM (Adaptive Differential Pulse Code Modulation) formats. The file is saved in this format.

MCI_DGV_SETAUDIO_BASS

The audio low frequency level is specified as a factor in the dwValue member of the structure identified by lpSetAudio.

MCI_DGV_SETAUDIO_BITSPERSAMPLE

The number of bits per sample is specified in the dwValue member of the structure identified by lpSetAudio. This value sets the number of bits per sample played or recorded in the PCM format. The file is saved in this format.

MCI_DGV_SETAUDIO_BLOCKALIGN

The data block alignment is specified in the dwValue member of the structure identified by lpSetAudio. This value sets the alignment of data blocks relative to the start of input waveform data.

MCI_DGV_SETAUDIO_SAMPLESPERSEC

The sample rate is specified in the dwValue member of the structure identified by lpSetAudio. This value sets the sample rate for playing and recording with the PCM and ADPCM algorithms. The file is saved in this format.

MCI_DGV_SETAUDIO_SOURCE

A constant specifying the source of audio input is included in the dwValue member of the structure identified by lpSetAudio. The following constants are defined for the audio input sources:

MCI_DGV_SETAUDIO_SOURCE_AVERAGE

    The average of the left and right audio channels.

MCI_DGV_SETAUDIO_SOURCE_LEFT

    Left audio channel.

MCI_DGV_SETAUDIO_SOURCE_RIGHT

    Right audio channel.

MCI_DGV_SETAUDIO_SOURCE_STEREO

    Stereo.

MCI_DGV_SETAUDIO_STREAM

An audio-stream is specified in the dwValue member of the structure identified by lpSetAudio. The integer value specifies the audio stream played back from the workspace. If the stream is not specified, the first physically interleaved audio stream is played.

MCI_DGV_SETAUDIO_TREBLE

The audio high-frequency level is specified as a factor in the dwValue member of the structure identified by lpSetAudio.

MCI_DGV_SETAUDIO_VOLUME

The audio level for one or both audio channels is specified as a factor in the dwValue member of the structure identified by lpSetAudio. If the left and right volumes have been set to different values, then the ratio of left to right volume is approximately unchanged.

MCI_DGV_SETAUDIO_LEFT

Enables the left audio channel when used with MCI_SET_ON. Disables the left audio channel when used with MCI_SET_OFF. When this flag is used with the combination of MCI_DGV_SETAUDIO_VALUE and MCI_DGV_SETAUDIO_VOLUME, it sets the volume of the left audio channel. When this flag is used with MCI_DGV_SETAUDIO_SOURCE, it specifies the left audio channel as the source for the audio input digitizer.

MCI_DGV_SETAUDIO_OVER

A transition length parameter is included in the dwOver member of the structure identified by lpSetAudio. The length value specifies how long (in units of the current time format) it should take to make a change that uses a factor. If this flag is not used, changes occur immediately.

MCI_DGV_SETAUDIO_QUALITY

The lpstrQuality member of the structure identified by lpSetAudio contains an address of a buffer defining the audio quality. A text-string within the buffer specifies the characteristics of the audio compression algorithm.

The MCI_DGV_SETAUDIO_ALG flag can be used to select a quality descriptor for the specified algorithm. If this flag is omitted, then the current algorithm is used.

The algorithms and descriptor names available depend on the device. Each device supplies documentation for the available algorithms and a description of the applicable descriptor names. The MCI_QUALITY command can define additional descriptor names.

MCI_DGV_SETAUDIO_RECORD

Specifies whether recording includes or excludes audio data. When combined with MCI_SET_ON, audio data is recorded. When combined with MCI_SET_OFF, audio data is excluded. The default includes audio data.

MCI_DGV_SETAUDIO_RIGHT

Enables the right audio channel when used with MCI_SET_ON. Disables the right audio channel when used with MCI_SET_OFF. When this flag is used with the combination of MCI_DGV_SETAUDIO_VALUE and MCI_DGV_SETAUDIO_VOLUME, it sets the volume of the right audio channel.

MCI_DGV_SETAUDIO_VALUE

A value is specified in the dwValue member of the structure identified by lpSetAudio. The meaning of the value is specified by the constant defined for the MCI_DGV_SETAUDIO_ITEM flag.

MCI_SET_OFF

Disables the specified audio channel.

MCI_SET_ON

Enables the specified audio channel.

MCI_SETAUDIO_OUTPUT

Modifies the bass, treble, or volume flag so that it modifies only the played signal and not what is recorded. If possible, this is the default when monitoring the input.

For digital-video devices, the lpSetAudio parameter points to an MCI_DGV_SETAUDIO_PARMS structure.

The following additional flags are used with the vcr device type:

MCI_VCR_SETAUDIO_RECORD

Sets the audio recording to on or off, which is used in conjunction with one of following flags:

MCI_SET_ON

Audio recording on.

MCI_SET_OFF

Audio recording off. It might be necessary to first turn off the assemble recording (using the MCI_SET command with the MCI_VCR_SET_ASSEMBLE_RECORD flag set to off) before the audio recording can be turned off.

MCI_TRACK

The dwTrack member of the structure identified by lpSetAudio specifies which track is affected by the command.

MCI_VCR_SETAUDIO_SOURCE

Sets the audio source. This flag must be used with the MCI_VCR_SETAUDIO_TO flag.

MCI_VCR_SETAUDIO_MONITOR

Sets the audio source monitor. This flag must be used with the MCI_VCR_SETAUDIO_TO flag.

MCI_VCR_SETAUDIO_TO

The dwTo member of the structure identified by lpSetAudio contains a constant describing the type of input or monitored input. It must be one of the following:

MCI_VCR_SRC_TYPE_TUNER

Type is tuner.

MCI_VCR_SRC_TYPE_LINE

Type is line.

MCI_VCR_SRC_TYPE_AUX

Type is auxiliary.

MCI_VCR_SRC_TYPE_GENERIC

Type is generic.

MCI_VCR_SRC_TYPE_MUTE

Type is mute. This can be used only with the MCI_VCR_SETAUDIO_SOURCE flag.

MCI_VCR_SRC_TYPE_OUTPUT

Type is output.

MCI_VCR_SETAUDIO_NUMBER

The dwNumber member of the structure identified by lpSetAudio contains the audio input (of the type specified in the dwTo member) to use.

For VCR devices, the lpSetAudio parameter points to an MCI_VCR_SETAUDIO_PARMS structure.

See Also

MCI_DGV_SETAUDIO_PARMS, MCI_GENERIC_PARMS, MCI_QUALITY, MCI_RECORD, MCI_RESERVE, MCI_SET, MCI_VCR_SETAUDIO_PARMS


MCI_SETTIMECODE

The MCI_SETTIMECODE command enables or disables timecode recording for a VCR. VCR devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_SETTIMECODE,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpSetTimeCode);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpSetTimeCode

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flag applies to VCR devices:

MCI_VCR_SETTIMECODE_RECORD

Sets the timecode track recording to on or off. This flag is used in combination with one of the following additional flags:

MCI_SET_ON

Timecode recording on.

MCI_SET_OFF

Timecode recording off.

See Also

MCI_GENERIC_PARMS


MCI_SETTUNER

The MCI_SETTUNER command sets the current channel on the tuner. VCR devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_SETTUNER,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpSetTuner);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpSetTuner

Address of an MCI_VCR_SETTUNER_PARMS structure.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags apply to VCR devices:

MCI_VCR_SETTUNER_CHANNEL

The dwChannel member of the structure identified by lpSetTuner contains the new channel number.

MCI_VCR_SETTUNER_CHANNEL_DOWN

Decrements the tuner channel.

MCI_VCR_SETTUNER_CHANNEL_SEEK_DOWN

Searches for a valid channel in the reverse direction.

MCI_VCR_SETTUNER_CHANNEL_SEEK_UP

Searches for a valid channel in the forward direction.

MCI_VCR_SETTUNER_CHANNEL_UP

Increments the tuner channel.

MCI_VCR_SETTUNER_NUMBER

The dwNumber member of the structure identified by lpSetTuner specifies which logical tuner to affect with this command.

See Also

MCI_VCR_SETTUNER_PARMS


MCI_SETVIDEO

The MCI_SETVIDEO command sets values associated with video playback. Digital-video and VCR devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_SETVIDEO,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpSetVideo);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpSetVideo

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags are used with the digitalvideo device type:

MCI_DGV_SETVIDEO_ALG

The lpstrAlgorithm member of the structure identified by lpSetVideo contains an address of a buffer containing the name of a video compression algorithm. The compression algorithm is used by subsequent MCI_RESERVE or MCI_RECORD commands. The available algorithms are device dependent.

If the specified algorithm is incompatible with the current file format, the file format is changed to the default format for the algorithm.

MCI_DGV_SETVIDEO_CLOCKTIME

When used with MCI_DGV_SETVIDEO_OVER, indicates time is specified in milliseconds and is absolute time. (This time is not in step with the playing of the workspace.)

MCI_DGV_SETVIDEO_INPUT

Modifies the MCI_DGV_SETVIDEO_BRIGHTNESS, MCI_DGV_SETVIDEO_COLOR, MCI_DGV_SETVIDEO_CONTRAST, MCI_DGV_SETVIDEO_GAMMA, MCI_DGV_SETVIDEO_SHARPNESS, or MCI_DGV_SETVIDEO_TINT so that it affects the input signal and modifies what is recorded. If possible, this is the default when monitoring the input.

MCI_DGV_SETVIDEO_ITEM

A video constant is specified in the dwItem member of the structure identified by lpSetVideo. The constant identifies the value that is being set. You can specify the following constants with this flag:

MCI_AVI_SETVIDEO_DRAW_PROCEDURE

A new drawing procedure address is specified in the dwValue member of the structure identified by lpSetVideo. You can specify a new drawing procedure only when the device is idle. This flag is recognized only by the MCIAVI digital-video driver. There is no equivalent to this flag in the string command interface.

MCI_AVI_SETVIDEO_PALETTE_COLOR

A new palette color is specified in the dwOver and dwValue members of the structure identified by lpSetVideo. The dwOver member specifies the palette index of the color to be changed and the dwValue member specifies the new color, as an RGB value. You must also specify the MCI_DGV_SETVIDEO_OVER and MCI_DGV_SETVIDEO_VALUE flags with MCI_DGV_SETVIDEO_ITEM when you use this constant. This flag is recognized only by the MCIAVI digital-video driver.

MCI_AVI_SETVIDEO_PALETTE_HALFTONE

Indicates that the halftone palette should be used, instead of the default palette. This flag is recognized only by the MCIAVI digital-video driver.

MCI_DGV_SETVIDEO_BITSPERPEL

The number of bits per pixel is specified in the dwValue member of the structure identified by lpSetVideo. The number of bits per pixel is used for saving captured or recorded data

MCI_DGV_SETVIDEO_BRIGHTNESS

The video brightness level is specified as a factor in the dwValue member of the structure identified by lpSetVideo.

MCI_DGV_SETVIDEO_COLOR

The video color saturation level is specified as a factor in the dwValue member of the structure identified by lpSetVideo.

MCI_DGV_SETVIDEO_CONTRAST

The video contrast level is specified as a factor in the dwValue member of the structure identified by lpSetVideo.

MCI_DGV_SETVIDEO_FRAME_RATE

A frame rate is specified in the dwValue member of the structure identified by lpSetVideo. The rate is specified in units of frames per second times 1000. For example, 29.97 frames per second is specified as 29970.

MCI_DGV_SETVIDEO_GAMMA

A gamma correction exponent value is specified in the dwValue member of the structure identified by lpSetVideo. Gamma correction adjusts the mapping between the intensity encoded in the presentation source and the displayed brightness. The value is the exponent multiplied by 1000. For example, 2200 indicates an exponent of 2.2. A value of 1000 indicates an exponent of 1, which applies no gamma correction.

MCI_DGV_SETVIDEO_KEY_COLOR

A key color is specified in the dwValue member of the structure identified by lpSetVideo. The key color is a Windows RGB value.

MCI_DGV_SETVIDEO_KEY_INDEX

A key index value is specified in the dwValue member of the structure identified by lpSetVideo. The index parameter is a physical palette index.

MCI_DGV_SETVIDEO_PALHANDLE

A palette handle is specified in the dwValue member of the structure identified by lpSetVideo. The palette handle is contained in the low-order word. Digital-video devices should not free the palette passed with this command. Applications should free it after they close the device. This flag is supported only by devices that use palettes. If this specified palette handle is zero, then the default palette is used.

MCI_DGV_SETVIDEO_SHARPNESS

A video sharpness value is specified as a factor in the dwValue member of the structure identified by lpSetVideo.

MCI_DGV_SETVIDEO_SOURCE

A constant specifying the source of the video input is specified in the dwValue member of the structure identified by lpSetVideo. The following constants are defined:

MCI_DGV_SETVIDEO_SRC_NTSC

    Specifies NTSC.

MCI_DGV_SETVIDEO_SRC_PAL

    Specifies PAL.

MCI_DGV_SETVIDEO_SRC_RGB

    Specifies RGB.

MCI_DGV_SETVIDEO_SRC_SECAM

    Specifies SECAM.

MCI_DGV_SETVIDEO_SRC_SVIDEO

    Specifies SVIDEO.

MCI_DGV_SETVIDEO_STREAM

A video stream is specified in the dwValue member of the structure identified by lpSetVideo. The integer value specifies the video stream played back from the workspace. If the stream is not specified and the file format does not define a default stream, the first physically interleaved video stream is played.

MCI_DGV_SETVIDEO_TINT

A video tint value is specified as a factor in the dwValue member of the structure identified by lpSetVideo. Typically, this adjustment is modeled after the tint control of many color television sets, with 250 defined as green, 750 defined as red, and 0 (or 1000) defined as blue. The nominal value is always 500.

MCI_DGV_SETVIDEO_OUTPUT

The MCI_DGV_SETVIDEO_BRIGHTNESS, MCI_DGV_SETVIDEO_COLOR, MCI_DGV_SETVIDEO_CONTRAST, MCI_DGV_SETVIDEO_GAMMA, MCI_DGV_SETVIDEO_SHARPNESS, or MCI_DGV_SETVIDEO_TINT flag is modified so that it affects only the displayed signal and not what is recorded. If possible, this is the default when monitoring a file.

MCI_DGV_SETVIDEO_OVER

A transition length parameter is included in the dwOver member of the structure identified by lpSetVideo. The transition length specifies how long (in the current time format) it should take to make a change. If this flag is not used, the change occurs immediately.

MCI_DGV_SETVIDEO_QUALITY

The lpstrQuality member of the structure identified by lpSetVideo contains an address of a buffer describing the video quality. A text-string in the buffer specifies the characteristics of the video compression algorithm.

The MCI_DGV_SETVIDEO_ALG flag can be used to select a quality descriptor for the specified algorithm. If this flag is omitted, then the current algorithm is used.

The algorithms and descriptor names available depend on the device. Each device supplies documentation for the available algorithms and a description of the applicable descriptor names. The MCI_QUALITY command can define additional descriptor names. All devices support the descriptors “low”, “medium”, and “high”. The default is driver specific.

MCI_DGV_SETVIDEO_RECORD

Specifies whether recording includes or excludes video data. When combined with MCI_SET_ON, video data is recorded. When combined with MCI_SET_OFF, video data is excluded. The default includes video data.

MCI_DGV_SETVIDEO_SRC_NUMBER

A number for the video source is specified in the dwSourceNumber member of the structure identified by lpSetVideo. If there is more than one input of the type specified by MCI_DGV_SETVIDEO_VALUE, the value selects the input. This flag must always be used with MCI_DGV_SETVIDEO_SOURCE. If MCI_DGV_SETVIDEO_VALUE is omitted, however, the specified source number indicates the absolute source to use as specified in the MCI_LIST command.

MCI_DGV_SETVIDEO_STILL

The algorithm name or quality value specified applies to still images.

Every device driver must support an algorithm of “none”, which means no compression. This is the default. In this case, digital-video devices save still images as RGB format device-independent bitmaps (DIBs).

MCI_DGV_SETVIDEO_VALUE

A value is included in the dwValue member of the structure identified by lpSetVideo. The meaning of the value is specified by the MCI_DGV_SETVIDEO_ITEM flag.

MCI_SET_OFF

Disables video output. For digital-video devices, disabling video sets the pixels in the destination rectangle defined by the MCI_PUT command (or its default, the client region of the current window) to a solid color, but it has no effect on the frame buffer. You can hide the window with the MCI_WINDOW command if desired. The source of video, whether it’s the workspace or an external input, might continue to store new images in the frame buffer, but they are not displayed until the video is enabled. While applications should use the MCI_SETVIDEO command to control this function, digital-video devices must still support this flag. The default value after an open is on.

MCI_SET_ON

Enables video output.

For digital-video devices, the lpSetVideo parameter points to an MCI_DGV_SETVIDEO_PARMS structure.

The following additional flags are used with the vcr device type:

MCI_VCR_SETVIDEO_RECORD

Sets the video recording to on or off. Used in conjunction with one of following flags:

MCI_SET_ON

Video recording on.

MCI_SET_OFF

Video recording off. It might be necessary to first turn off the assemble recording (using the MCI_SET command with the MCI_VCR_SET_ASSEMBLE_RECORD flag set to off) before the video recording can be turned off.

MCI_TRACK

The dwTrack member of the structure identified by lpSetVideo specifies which track is affected by the command.

MCI_VCR_SETVIDEO_SOURCE

Sets the video source, and must be used with the MCI_VCR_SETVIDEO_TO flag.

MCI_VCR_SETVIDEO_MONITOR

Sets the video source monitor, and must be used with the MCI_VCR_SETVIDEO_TO flag.

MCI_VCR_SETVIDEO_TO

The dwTo member of the structure identified by lpSetVideo contains one of the following constants:

MCI_VCR_SRC_TYPE_TUNER
MCI_VCR_SRC_TYPE_LINE
MCI_VCR_SRC_TYPE_AUX
MCI_VCR_SRC_TYPE_GENERIC
MCI_VCR_SRC_TYPE_MUTE
MCI_VCR_SRC_TYPE_OUTPUT
MCI_VCR_SRC_TYPE_RGB

MCI_VCR_SETVIDEO_NUMBER

The dwNumber member of the structure identified by lpSetVideo contains the video input (of the type specified in the dwTo member) to use.

For VCR devices, the lpSetVideo parameter points to an MCI_VCR_SETVIDEO_PARMS structure.

See Also

MCI_DGV_SETVIDEO_PARMS, MCI_GENERIC_PARMS, MCI_LIST, MCI_PUT, MCI_QUALITY, MCI_RECORD, MCI_RESERVE, MCI_SET, MCI_VCR_SETVIDEO_PARMS, MCI_WINDOW, RGB


MCI_SIGNAL

The MCI_SIGNAL command sets a specified position in the workspace. Digital-video devices recognize this command. MCIAVI supports only one active signal at a time.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_SIGNAL,
    DWORD dwFlags, (DWORD) (LPMCI_DGV_SIGNAL_PARMS) lpSignal);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpSignal

Address of an MCI_DGV_SIGNAL_PARMS structure.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The window whose handle you specify in the dwCallback member of the MCI_DGV_SIGNAL_PARMS structure receives the MM_MCISIGNAL message.

The following flags apply to digital-video devices:

MCI_DGV_SIGNAL_AT

A signal position is included in the dwPosition member of the structure identified by lpSignal.

MCI_DGV_SIGNAL_CANCEL

Removes the signal position specified by the value associated with MCI_DGV_SIGNAL_USERVAL.

MCI_DGV_SIGNAL_EVERY

A signal-period value is included in the dwPeriod member of the structure identified by lpSignal.

MCI_DGV_SIGNAL_POSITION

The device will send the position value with the Windows message instead of the user-specified value.

MCI_DGV_SIGNAL_USERVAL

A data value is included in the dwUserParm member of the structure identified by lpSignal. The data value associated with this request is reported back with the Windows message.

See Also

MCI_DGV_SIGNAL_PARMS


MCI_SPIN

The MCI_SPIN command starts the device spinning up or down. Videodisc devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_SPIN,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpSpin);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY or MCI_WAIT. For information about these flags, see The Wait, Notify, and Test Flags.

lpSpin

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags apply to videodisc devices:

MCI_VD_SPIN_DOWN

Stops the disc spinning.

MCI_VD_SPIN_UP

Starts the disc spinning.

See Also

MCI_GENERIC_PARMS


MCI_STATUS

The MCI_STATUS command retrieves information about an MCI device. All devices recognize this command. Information is returned in the dwReturn member of the structure identified by the lpStatus parameter.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_STATUS,
    DWORD dwFlags, (DWORD) (LPMCI_STATUS_PARMS) lpStatus);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpStatus

Address of an MCI_STATUS_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional standard and command-specific flags apply to all devices supporting MCI_STATUS:

MCI_STATUS_ITEM

Specifies that the dwItem member of the structure identified by lpStatus contains a constant specifying which status item to obtain. The following constants define which status item to return in the dwReturn member of the structure:

MCI_STATUS_CURRENT_TRACK

The dwReturn member is set to the current track number. MCI uses continuous track numbers.

MCI_STATUS_LENGTH

The dwReturn member is set to the total media length.

MCI_STATUS_MODE

The dwReturn member is set to the current mode of the device. The modes include the following:

MCI_MODE_NOT_READY
MCI_MODE_PAUSE
MCI_MODE_PLAY
MCI_MODE_STOP
MCI_MODE_OPEN
MCI_MODE_RECORD
MCI_MODE_SEEK

MCI_STATUS_NUMBER_OF_TRACKS

The dwReturn member is set to the total number of playable tracks.

MCI_STATUS_POSITION

The dwReturn member is set to the current position.

MCI_STATUS_READY

The dwReturn member is set to TRUE if the device is ready; it is set to FALSE otherwise.

MCI_STATUS_TIME_FORMAT

The dwReturn member is set to the current time format of the device. The time formats include:

MCI_FORMAT_BYTES
MCI_FORMAT_FRAMES
MCI_FORMAT_HMS
MCI_FORMAT_MILLISECONDS
MCI_FORMAT_MSF
MCI_FORMAT_SAMPLES
MCI_FORMAT_TMSF

MCI_STATUS_START

Obtains the starting position of the media. To get the starting position, combine this flag with MCI_STATUS_ITEM and set the dwItem member of the structure identified by lpStatus to MCI_STATUS_POSITION.

MCI_TRACK

Indicates a status track parameter is included in the dwTrack member of the structure identified by lpStatus. You must use this flag with the MCI_STATUS_POSITION or MCI_STATUS_LENGTH constants. When used with MCI_STATUS_POSITION, MCI_TRACK obtains the starting position of the specified track. When used with MCI_STATUS_LENGTH, MCI_TRACK obtains the length of the specified track. MCI uses continuous track numbers.

The following additional flags are used with the cdaudio device type. These constants are used in the dwItem member of the structure pointed to by the lpStatus parameter when MCI_STATUS_ITEM is specified for the dwFlags parameter.

MCI_CDA_STATUS_TYPE_TRACK

The dwReturn member is set to one of the following values:

MCI_CDA_TRACK_AUDIO
MCI_CDA_TRACK_OTHER

To use this flag, the MCI_TRACK flag must be set, and the dwTrack member of the structure identified by lpStatus must contain a valid track number.

MCI_STATUS_MEDIA_PRESENT

The dwReturn member is set to TRUE if the media is inserted in the device; it is set to FALSE otherwise.

The following additional flags are used with the digitalvideo device type:

MCI_DGV_STATUS_DISKSPACE

The lpstrDrive member of the structure identified by lpStatus specifies a disk drive or, in some implementations, a path. The MCI_STATUS command returns the approximate amount of disk space that could be obtained by the MCI_RESERVE command in the dwReturn member of the structure identified by lpStatus. The disk space is measured in units of the current time format.

MCI_DGV_STATUS_INPUT

The constant specified by the dwItem member of the structure identified by lpStatus applies to the input.

MCI_DGV_STATUS_LEFT

The constant specified by the dwItem member of the structure identified by lpStatus applies to the left audio channel.

MCI_DGV_STATUS_NOMINAL

The constant specified by the dwItem member of the structure identified by lpStatus requests the nominal value rather than the current value.

MCI_DGV_STATUS_OUTPUT

The constant specified by the dwItem member of the structure identified by lpStatus applies to the output.

MCI_DGV_STATUS_RECORD

The frame rate returned for the MCI_DGV_STATUS_FRAME_RATE flag is the rate used for compression.

MCI_DGV_STATUS_REFERENCE

The dwReturn member of the structure identified by lpStatus returns the nearest key-frame image that precedes the frame specified in the dwReference member.

MCI_DGV_STATUS_RIGHT

The constant specified by the dwItem member of the structure identified by lpStatus applies to the right audio channel.

The following constants are used with the digitalvideo device type in the dwItem member of the structure pointed to by the lpStatus parameter when MCI_STATUS_ITEM is specified for the dwFlags parameter.

MCI_AVI_STATUS_AUDIO_BREAKS

The dwReturn member returns the number of times the audio portion of the last AVI sequence broke up. The system counts an audio break whenever it attempts to write audio data to the device driver and discovers that the driver has already played all of the available data. This flag is recognized only by the MCIAVI digital-video driver.

MCI_AVI_STATUS_FRAMES_SKIPPED

The dwReturn member returns the number of frames that were not drawn when the last AVI sequence was played. This flag is recognized only by the MCIAVI digital-video driver.

MCI_AVI_STATUS_LAST_PLAY_SPEED

The dwReturn member returns a value representing how closely the actual playing time of the last AVI sequence matched the target playing time. The value 1000 indicates that the target time and the actual time were the same. A value of 2000, for example, would indicate that the AVI sequence took twice as long to play as it should have. This flag is recognized only by the MCIAVI digital-video driver.

MCI_DGV_STATUS_AUDIO

The dwReturn member returns MCI_ON or MCI_OFF depending on the most recent MCI_SET_AUDIO option for the MCI_SET command. It returns MCI_ON if either or both speakers are enabled, and MCI_OFF otherwise.

MCI_DGV_STATUS_AUDIO_INPUT

The dwReturn member returns the approximate instantaneous audio level of the analog audio signal. A value greater than 1000 implies there is clipping distortion. Some devices can determine this value only while recording audio. This status value has no associated MCI_SET or MCI_SETAUDIO command. This value is related to, but normalized differently from, the waveform-audio command MCI_WAVE_STATUS_LEVEL.

MCI_DGV_STATUS_AUDIO_RECORD

The dwReturn member returns MCI_ON or MCI_OFF reflecting the state set by the MCI_DGV_SETAUDIO_RECORD flag of the MCI_SETAUDIO command.

MCI_DGV_STATUS_AUDIO_SOURCE

The dwReturn member returns the current audio digitizer source:

MCI_DGV_SETAUDIO_AVERAGE

Specifies the average of the left and right audio channels.

MCI_DGV_SETAUDIO_LEFT

Specifies the left audio channel.

MCI_DGV_SETAUDIO_RIGHT

Specifies the right audio channel.

MCI_DGV_SETAUDIO_STEREO

Specifies stereo.

MCI_DGV_STATUS_AUDIO_STREAM

The dwReturn member returns the current audio-stream number.

MCI_DGV_STATUS_AVGBYTESPERSEC

The dwReturn member returns the average number of bytes per second used for recording.

MCI_DGV_STATUS_BASS

The dwReturn member returns the current audio bass level. Use MCI_DGV_STATUS_NOMINAL with this flag to obtain the nominal level.

MCI_DGV_STATUS_BITSPERPEL

The dwReturn member returns the number of bits per pixel used for saving captured or recorded data.

MCI_DGV_STATUS_BITSPERSAMPLE

The dwReturn member returns the number of bits per sample the device uses for recording. This applies only to devices supporting the PCM format.

MCI_DGV_STATUS_BLOCKALIGN

The dwReturn member returns the alignment of data blocks relative to the start of the input waveform.

MCI_DGV_STATUS_BRIGHTNESS

The dwReturn member returns the current video brightness level. Use MCI_DGV_STATUS_NOMINAL with this flag to obtain the nominal level.

MCI_DGV_STATUS_COLOR

The dwReturn member returns the current color level. Use MCI_DGV_STATUS_NOMINAL with this flag to obtain the nominal level.

MCI_DGV_STATUS_CONTRAST

The dwReturn member returns the current contrast level. Use MCI_DGV_STATUS_NOMINAL with this flag to obtain the nominal level.

MCI_DGV_STATUS_FILEFORMAT

The dwReturn member returns the current file format for recording or saving.

MCI_DGV_STATUS_FILE_MODE

The dwReturn member returns the state of the file operation:

MCI_DGV_FILE_MODE_EDITING

Returned during cut, copy, delete, paste, and undo operations.

MCI_DGV_FILE_MODE_IDLE

Returned when the file is ready for the next operation.

MCI_DGV_FILE_MODE_LOADING

Returned while the file is being loaded.

MCI_DGV_FILE_MODE_SAVING

Returned while the file is being saved.

MCI_DGV_STATUS_FILE_COMPLETION

The dwReturn member returns the estimated percentage a load, save, capture, cut, copy, delete, paste, or undo operation has progressed. (Applications can use this to provide a visual indicator of progress.) This flag is not supported by all digital-video devices.

MCI_DGV_STATUS_FORWARD

The dwReturn member returns TRUE if the device direction is forward or the device is not playing.

MCI_DGV_STATUS_FRAME_RATE

The dwReturn member must be used with MCI_DGV_STATUS_NOMINAL, MCI_DGV_STATUS_RECORD, or both. When used with MCI_DGV_STATUS_RECORD, the current frame rate used for recording is returned. When used with both MCI_DGV_STATUS_RECORD and MCI_DGV_STATUS_NOMINAL, the nominal frame rate associated with the input video signal is returned. When used with MCI_DGV_STATUS_NOMINAL, the nominal frame rate associated with the file is returned. In all cases the units are in frames per second multiplied by 1000.

MCI_DGV_STATUS_GAMMA

The dwReturn member returns the current gamma value. Use MCI_DGV_STATUS_NOMINAL with this flag to obtain the nominal level.

MCI_DGV_STATUS_HPAL

The dwReturn member returns the ASCII decimal value for the current palette handle. The handle is contained in the low-order word of the returned value.

MCI_DGV_STATUS_HWND

The dwReturn member returns the ASCII decimal value for the current explicit or default window handle associated with this device driver instance. The handle is contained in the low-order word of the returned value.

MCI_DGV_STATUS_KEY_COLOR

The dwReturn member returns the current key-color value.

MCI_DGV_STATUS_KEY_INDEX

The dwReturn member returns the current key-index value.

MCI_DGV_STATUS_MONITOR

The dwReturn member returns a constant indicating the source of the current presentation. The following constants are defined:

MCI_DGV_MONITOR_FILE

A file is the source.

MCI_DGV_MONITOR_INPUT

The input is the source.

MCI_DGV_STATUS_MONITOR_METHOD

The dwReturn member returns a constant indicating the method used for input monitoring. The following constants are defined:

MCI_DGV_METHOD_DIRECT

Direct input monitoring.

MCI_DGV_METHOD_POST

Post-input monitoring.

MCI_DGV_METHOD_PRE

Pre-input monitoring.

MCI_DGV_STATUS_PAUSE_MODE

The dwReturn member returns MCI_MODE_PLAY if the device was paused while playing and returns MCI_MODE_RECORD if the device was paused while recording. The command returns MCIERR_NONAPPLICABLE_FUNCTION as an error return if the device is not paused.

MCI_DGV_STATUS_SAMPLESPERSECOND

The dwReturn member returns the number of samples per second recorded.

MCI_DGV_STATUS_SEEK_EXACTLY

The dwReturn member returns TRUE or FALSE indicating whether or not the seek exactly format is set. (Applications can set this format by using the MCI_SET command with the MCI_DGV_SET_SEEK_EXACTLY flag.)

MCI_DGV_STATUS_SHARPNESS

The dwReturn member returns the current sharpness level. Use MCI_DGV_STATUS_NOMINAL with this flag to obtain the nominal level.

MCI_DGV_STATUS_SIZE

The dwReturn member returns the approximate playback duration of compressed data that the reserved workspace will hold. The duration units are in the current time format. It returns zero if there is no reserved disk space. The size returned is approximate since the precise disk space for compressed data cannot, in general, be predicted until after the data has been compressed.

MCI_DGV_STATUS_SMPTE

The dwReturn member returns the SMPTE time code associated with the current position in the workspace.

MCI_DGV_STATUS_SPEED

The dwReturn member returns the current playback speed.

MCI_DGV_STATUS_STILL_FILEFORMAT

The dwReturn member returns the current file format for the MCI_CAPTURE command.

MCI_DGV_STATUS_TINT

The dwReturn member returns the current video tint level. Use MCI_DGV_STATUS_NOMINAL with this flag to obtain the nominal level.

MCI_DGV_STATUS_TREBLE

The dwReturn member returns the current audio treble level. Use MCI_DGV_STATUS_NOMINAL with this flag to obtain the nominal level.

MCI_DGV_STATUS_UNSAVED

The dwReturn member returns TRUE if there is recorded data in the workspace that might be lost as a result of a MCI_CLOSE, MCI_LOAD, MCI_RECORD, MCI_RESERVE, MCI_CUT, MCI_DELETE, or MCI_PASTE command. The member returns FALSE otherwise.

MCI_DGV_STATUS_VIDEO

The dwReturn member returns MCI_ON if video is enabled or MCI_OFF if it is disabled.

MCI_DGV_STATUS_VIDEO_RECORD

The dwReturn member returns MCI_ON or MCI_OFF, reflecting the state set by the MCI_DGV_SETVIDEO_RECORD flag of the MCI_SETVIDEO command.

MCI_DGV_STATUS_VIDEO_SOURCE

The dwReturn member returns a constant indicating the type of video source set by the MCI_DGV_SETVIDEO_SOURCE flag of the MCI_SETVIDEO command.

MCI_DGV_STATUS_VIDEO_SRC_NUM

The dwReturn member returns the number within its type of the video-input source currently active.

MCI_DGV_STATUS_VIDEO_STREAM

The dwReturn member returns the current video-stream number.

MCI_DGV_STATUS_VOLUME

The dwReturn member returns the average of the volume to the left and right speakers. Use MCI_DGV_STATUS_NOMINAL with this flag to obtain the nominal level.

MCI_DGV_STATUS_WINDOW_VISIBLE

The dwReturn member returns TRUE if the window is not hidden.

MCI_DGV_STATUS_WINDOW_MINIMIZED

The dwReturn member returns TRUE if the window is minimized.

MCI_DGV_STATUS_WINDOW_MAXIMIZED

The dwReturn member returns TRUE if the window is maximized.

MCI_STATUS_MEDIA_PRESENT

The dwReturn member returns TRUE.

For digital-video devices, the lpStatus parameter points to an MCI_DGV_STATUS_PARMS structure.

The following additional flags are used with the sequencer device type. These constants are used in the dwItem member of the structure pointed to by the lpStatus parameter when MCI_STATUS_ITEM is specified for the dwFlags parameter.

MCI_SEQ_STATUS_DIVTYPE

The dwReturn member is set to one of the following values indicating the current division type of a sequence:

MCI_SEQ_DIV_PPQN
MCI_SEQ_DIV_SMPTE_24
MCI_SEQ_DIV_SMPTE_25
MCI_SEQ_DIV_SMPTE_30
MCI_SEQ_DIV_SMPTE_30DROP

MCI_SEQ_STATUS_MASTER

The dwReturn member is set to the synchronization type used for master operation.

MCI_SEQ_STATUS_OFFSET

The dwReturn member is set to the current SMPTE offset of a sequence.

MCI_SEQ_STATUS_PORT

The dwReturn member is set to the MIDI device identifier for the current port used by the sequence.

MCI_SEQ_STATUS_SLAVE

The dwReturn member is set to the synchronization type used for slave operation.

MCI_SEQ_STATUS_TEMPO

The dwReturn member is set to the current tempo of a MIDI sequence in beats per minute for PPQN files, or frames per second for SMPTE files.

MCI_STATUS_MEDIA_PRESENT

The dwReturn member is set to TRUE if the media is inserted in the device; it is set to FALSE otherwise.

The following additional flags are used with the vcr device type. These constants are used in the dwItem member of the structure pointed to by the lpStatus parameter when MCI_STATUS_ITEM is specified for the dwFlags parameter.

MCI_STATUS_MEDIA_PRESENT

The dwReturn member is set to TRUE if the media is inserted in the device; it is set to FALSE otherwise.

MCI_VCR_STATUS_ASSEMBLE_RECORD

The dwReturn member is set to TRUE if assemble mode is on; it is set to FALSE otherwise.

MCI_VCR_STATUS_AUDIO_MONITOR

The dwReturn member is set to a constant, indicating the currently selected audio-monitor type.

MCI_VCR_STATUS_AUDIO_MONITOR_NUMBER

The dwReturn member is set to the number of the currently selected audio-monitor type.

MCI_VCR_STATUS_AUDIO_RECORD

The dwReturn member is set to TRUE if audio will be recorded when the next record command is given; it is set to FALSE otherwise. If you specify MCI_TRACK in the dwFlags parameter of this command, dwTrack contains the track this inquiry applies to.

MCI_VCR_STATUS_AUDIO_SOURCE

The dwReturn member is set to a constant, indicating the current audio-source type.

MCI_VCR_STATUS_AUDIO_SOURCE_NUMBER

The dwReturn member is set to the number of the currently selected audio-source type.

MCI_VCR_STATUS_CLOCK

The dwReturn member is set to the current clock value, in total clock increments.

MCI_VCR_STATUS_CLOCK_ID

The dwReturn member is set to a number which uniquely describes the clock in use.

MCI_VCR_STATUS_COUNTER_FORMAT

The dwReturn member is set to a constant describing the current counter format. For more information, see the MCI_SET_TIME_FORMAT flag of the MCI_SET command.

MCI_VCR_STATUS_COUNTER_RESOLUTION

The dwReturn member is set to a constant describing the resolution of the counter, and is one of the following values:

MCI_VCR_COUNTER_RES_FRAMES

Counter has resolution of frames.

MCI_VCR_COUNTER_RES_SECONDS

Counter has resolution of seconds.

MCI_VCR_STATUS_COUNTER_VALUE

The dwReturn member is set to the current counter reading, in the current counter-time format.

MCI_VCR_STATUS_FRAME_RATE

The dwReturn member is set to the current native frame rate of the device.

MCI_VCR_STATUS_INDEX

The dwReturn member is set to a constant, describing the current contents of the on-screen display, and is one of the following:

MCI_VCR_INDEX_COUNTER

MCI_VCR_INDEX_DATE

MCI_VCR_INDEX_TIME

MCI_VCR_INDEX_TIMECODE

MCI_VCR_STATUS_INDEX_ON

The dwReturn member is set to TRUE if the on-screen display is on; it is set to FALSE otherwise.

MCI_VCR_STATUS_MEDIA_TYPE

The dwReturn member is set to one of the following:

MCI_VCR_MEDIA_8MM
MCI_VCR_MEDIA_HI8
MCI_VCR_MEDIA_VHS
MCI_VCR_MEDIA_SVHS
MCI_VCR_MEDIA_BETA
MCI_VCR_MEDIA_EDBETA
MCI_VCR_MEDIA_OTHER

MCI_VCR_STATUS_NUMBER

The dwNumber member is set to the logical-tuner number when you use this flag with the MCI_VCR_STATUS_TUNER_CHANNEL flag.

MCI_VCR_STATUS_NUMBER_OF_AUDIO_TRACKS

The dwReturn member is set to the number of audio tracks that are independently selectable.

MCI_VCR_STATUS_NUMBER_OF_VIDEO_TRACKS

The dwReturn member is set to the number of video tracks that are independently selectable.

MCI_VCR_STATUS_PAUSE_TIMEOUT

The dwReturn member is set to the maximum duration, in milliseconds, of a pause command. The return value of zero indicates that no time-out will occur.

MCI_VCR_STATUS_PLAY_FORMAT

The dwReturn member is set to one of the following:

MCI_VCR_FORMAT_EP
MCI_VCR_FORMAT_LP
MCI_VCR_FORMAT_OTHER
MCI_VCR_FORMAT_SP

MCI_VCR_STATUS_POSTROLL_DURATION

The dwReturn member is set to the length of the videotape that will play after the spot at which it was stopped, in the current time format. This is needed to brake the VCR tape transport from a stop or pause command.

MCI_VCR_STATUS_POWER_ON

The dwReturn member is set to TRUE if the power is on; it is set to FALSE otherwise.

MCI_VCR_STATUS_PREROLL_DURATION

The dwReturn member is set to the length of the videotape that will play before the spot at which it was started, in the current time format. This is needed to stabilize the VCR output.

MCI_VCR_STATUS_RECORD_FORMAT

The dwReturn member is set to one of the following:

MCI_VCR_FORMAT_EP
MCI_VCR_FORMAT_LP
MCI_VCR_FORMAT_OTHER
MCI_VCR_FORMAT_SP

MCI_VCR_STATUS_SPEED

The dwReturn member is set to the current speed. For more information, see the MCI_VCR_SET_SPEED flag of the MCI_SET command.

MCI_VCR_STATUS_TIME_MODE

The dwReturn member is set to one of the following:

MCI_VCR_TIME_COUNTER
MCI_VCR_TIME_DETECT
MCI_VCR_TIME_TIMECODE

For more information, see the MCI_VCR_SET_TIME_MODE flag of the MCI_SET command.

MCI_VCR_STATUS_TIME_TYPE

The dwReturn member is set to a constant describing the current time type in use (used by play, record, seek, and so on), and is one of the following:

MCI_VCR_TIME_COUNTER

Counter is in use.

MCI_VCR_TIME_TIMECODE

Timecode is in use.

MCI_VCR_STATUS_TIMECODE_PRESENT

The dwReturn member is set to TRUE if timecode is present at the current position in the content; it is set to FALSE otherwise.

MCI_VCR_STATUS_TIMECODE_RECORD

The dwReturn member is set to TRUE if the timecode will be recorded when the next record command is given; it is set to FALSE otherwise.

MCI_VCR_STATUS_TIMECODE_TYPE

The dwReturn member is set to a constant, describing the type of timecode that is directly supported by the device, and is one of the following:

MCI_VCR_TIMECODE_TYPE_NONE

This device does not use a timecode.

MCI_VCR_TIMECODE_TYPE_OTHER

This device uses an unspecified timecode.

MCI_VCR_TIMECODE_TYPE_SMPTE

This device uses SMPTE timecode.

MCI_VCR_TIMECODE_TYPE_SMPTE_DROP

This device uses SMPTE drop timecode.

MCI_VCR_STATUS_TUNER_CHANNEL

The dwReturn member is set to the current channel number. If you specify MCI_VCR_STATUS_NUMBER in the dwFlags parameter of this command, dwNumber contains the logical-tuner number this command applies to.

MCI_VCR_STATUS_VIDEO_MONITOR

The dwReturn member is set to a constant, indicating the currently selected video-monitor type.

MCI_VCR_STATUS_VIDEO_MONITOR_NUMBER

The dwReturn member is set to the number of the currently selected video-monitor type.

MCI_VCR_STATUS_VIDEO_RECORD

The dwReturn member is set to TRUE if video will be recorded when the next record command is given; it is set to FALSE otherwise. If you specify MCI_TRACK in the dwFlags parameter of this command, dwTrack contains the track this inquiry applies to.

MCI_VCR_STATUS_VIDEO_SOURCE

The dwReturn member is set to a constant indicating the currently selected video-source type.

MCI_VCR_STATUS_VIDEO_SOURCE_NUMBER

The dwReturn member is set to the number of the currently selected video-source type.

MCI_VCR_STATUS_WRITE_PROTECTED

The dwReturn member is set to TRUE if the media is write-protected; it is set to FALSE otherwise.

For VCR devices, the lpStatus parameter points to an MCI_VCR_STATUS_PARMS structure.

Using the MCI_STATUS_LENGTH flag to determine the length of the media always returns 2 hours for VCR devices, unless the length has been explicitly changed using the MCI_SET command.

The following additional flags are used with the overlay device type. These constants are used in the dwItem member of the structure pointed to by the lpStatus parameter when MCI_STATUS_ITEM is specified for the dwFlags parameter.

MCI_OVLY_STATUS_HWND

The dwReturn member is set to the handle of the window associated with the video-overlay device.

MCI_OVLY_STATUS_STRETCH

The dwReturn member is set to TRUE if stretching is enabled; it is set to FALSE otherwise.

MCI_STATUS_MEDIA_PRESENT

The dwReturn member is set to TRUE if the media is inserted in the device; it is set to FALSE otherwise.

The following additional flags are used with the videodisc device type. These constants are used in the dwItem member of the structure pointed to by the lpStatus parameter when MCI_STATUS_ITEM is specified for the dwFlags parameter.

MCI_STATUS_MEDIA_PRESENT

The dwReturn member is set to TRUE if the media is inserted in the device; it is set to FALSE otherwise.

MCI_STATUS_MODE

The dwReturn member is set to the current mode of the device. Videodisc devices can return the MCI_VD_MODE_PARK constant, in addition to the constants any device can return, as documented with the dwFlags parameter.

MCI_VD_STATUS_DISC_SIZE

The dwReturn member is set to the size of the loaded disc in inches (8 or 12).

MCI_VD_STATUS_FORWARD

The dwReturn member is set to TRUE if playing forward; it is set to FALSE otherwise.

The MCI videodisc device does not support this flag.

MCI_VD_STATUS_MEDIA_TYPE

The dwReturn member is set to the media type of the inserted media. The following media types can be returned:

MCI_VD_MEDIA_CAV
MCI_VD_MEDIA_CLV
MCI_VD_MEDIA_OTHER

MCI_VD_STATUS_SIDE

The dwReturn member is set to 1 or 2 to indicate which side of the disc is loaded. Not all videodisc devices support this flag.

MCI_VD_STATUS_SPEED

The dwReturn member is set to the play speed in frames per second. The MCIPIONR.DRV device driver returns MCIERR_UNSUPPORTED_FUNCTION.

The following additional flags are used with the waveaudio device type. These constants are used in the dwItem member of the structure pointed to by the lpStatus parameter when MCI_STATUS_ITEM is specified for the dwFlags parameter.

MCI_WAVE_FORMATTAG

The dwReturn member is set to the current format tag used for playing, recording, and saving.

MCI_WAVE_INPUT

The dwReturn member is set to the wave input device used for recording. If no device is in use and no device has been explicitly set, then the error return is MCIERR_WAVE_INPUTUNSPECIFIED.

MCI_WAVE_OUTPUT

The dwReturn member is set to the wave output device used for playing. If no device is in use and no device has been explicitly set, then the error return is MCIERR_WAVE_OUTPUTUNSPECIFIED.

MCI_WAVE_STATUS_AVGBYTESPERSEC

The dwReturn member is set to the current bytes per second used for playing, recording, and saving.

MCI_WAVE_STATUS_BITSPERSAMPLE

The dwReturn member is set to the current bits per sample used for playing, recording, and saving PCM formatted data.

MCI_WAVE_STATUS_BLOCKALIGN

The dwReturn member is set to the current block alignment used for playing, recording, and saving.

MCI_WAVE_STATUS_CHANNELS

The dwReturn member is set to the current channel count used for playing, recording, and saving.

MCI_WAVE_STATUS_LEVEL

The dwReturn member is set to the current record or playback level of PCM formatted data. The value is returned as an 8- or 16-bit value, depending on the sample size used. The right or mono channel level is returned in the low-order word. The left channel level is returned in the high-order word.

MCI_WAVE_STATUS_SAMPLESPERSEC

The dwReturn member is set to the current samples per second used for playing, recording, and saving.

See Also

MCI_CAPTURE, MCI_CLOSE, MCI_CUT, MCI_DELETE, MCI_DGV_STATUS_PARMS, MCI_LOAD, MCI_PASTE, MCI_RECORD, MCI_RESERVE, or MCI_SET, MCI_SETAUDIO, MCI_SETVIDEO, MCI_STATUS_PARMS, MCI_VCR_STATUS_PARMS, play, record, seek


MCI_STEP

The MCI_STEP command steps the player one or more frames. Digital-video, VCR, and CAV-format videodisc devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_STEP,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpStep);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpStep

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

This command supports devices that return TRUE to the MCI_GETDEVCAPS_HAS_VIDEO flag of the MCI_GETDEVCAPS command.

The following additional flags are used with the digitalvideo device type:

MCI_DGV_STEP_FRAMES

The dwFrames member of the structure identified by lpStep specifies the number of frames to advance before displaying another image.

MCI_DGV_STEP_REVERSE

Steps in reverse.

For digital-video devices, the lpStep parameter points to an MCI_DGV_STEP_PARMS structure.

The following additional flags are used with the vcr device type:

MCI_VCR_STEP_FRAMES

The dwFrames member of the structure identified by lpStep specifies the number of frames to advance before displaying another image.

MCI_VCR_STEP_REVERSE

Steps in reverse.

For VCR devices, the lpStep parameter points to an MCI_VCR_STEP_PARMS structure.

The following additional flags are used with the videodisc device type:

MCI_VD_STEP_FRAMES

The dwFrames member of the structure identified by lpStep specifies the number of frames to step.

MCI_VD_STEP_REVERSE

Steps in reverse.

For videodisc devices, the lpStep parameter points to an MCI_VD_STEP_PARMS structure.

See Also

MCI_DGV_STEP_PARMS, MCI_GENERIC_PARMS, MCI_GETDEVCAPS, MCI_VCR_STEP_PARMS, MCI_VD_STEP_PARMS


MCI_STOP

The MCI_STOP command stops all play and record sequences, unloads all play buffers, and ceases display of video images. CD audio, digital-video, MIDI sequencer, videodisc, VCR, and waveform-audio devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_STOP,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpStop);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpStop

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The difference between the MCI_STOP and MCI_PAUSE commands depends on the device. If possible, MCI_PAUSE suspends device operation but leaves the device ready to resume play immediately.

For the CD audio device, MCI_STOP resets the current track position to zero; in contrast, MCI_PAUSE maintains the current track position, anticipating that the device will resume playing.

See Also

MCI_GENERIC_PARMS, MCI_PAUSE


MCI_SYSINFO

The MCI_SYSINFO command retrieves information about MCI devices. MCI supports this command directly rather than passing it to the device. Any MCI application can use this command. String information is returned in the application-supplied buffer pointed to by the lpstrReturn member of the structure identified by lpSysInfo. Numeric information is returned as a doubleword value placed in the application-supplied buffer. The dwRetSize member specifies the buffer length.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_SYSINFO,
    DWORD dwFlags, (DWORD) (LPMCI_SYSINFO_PARMS) lpSysInfo);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

One or more of the following standard and command-specific flags:

MCI_SYSINFO_INSTALLNAME

Obtains the name (listed in the registry or the SYSTEM.INI file) used to install the device.

MCI_SYSINFO_NAME

Obtains a device name corresponding to the device number specified in the dwNumber member of the structure identified by lpSysInfo. If the MCI_SYSINFO_OPEN flag is set, MCI returns the names of open devices.

MCI_SYSINFO_OPEN

Obtains the quantity or name of open devices.

MCI_SYSINFO_QUANTITY

Obtains the number of devices of the specified type that are listed in the registry or the [mci] section of the SYSTEM.INI file. If the MCI_SYSINFO_OPEN flag is set, the number of open devices is returned.

lpSysInfo

Address of an MCI_SYSINFO_PARMS structure.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The wDeviceType member of the structure identified by lpSysInfo is used to indicate the device type of the query. If the wDeviceID parameter is set to MCI_ALL_DEVICE_ID, it overrides the value of wDeviceType. For a list of device types, see Constants: Device Types.

Integer return values are doubleword values returned in the buffer pointed to by the lpstrReturn member of the structure identified by lpSysInfo.

String return values are null-terminated strings returned in the buffer pointed to by the lpstrReturn member of the structure identified by lpSysInfo.

See Also

MCI_SYSINFO_PARMS


MCI_UNDO

The MCI_UNDO command reverses the most recent successful MCI_CUT, MCI_COPY, MCI_DELETE, or MCI_PASTE command. Digital-video devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_UNDO,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpUndo);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpUndo

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

See Also

MCI_CUT, MCI_COPY, MCI_DELETE, MCI_GENERIC_PARMS, MCI_PASTE


MCI_UNFREEZE

The MCI_UNFREEZE command restores motion to an area of the video buffer frozen with the MCI_FREEZE command. Digital-video, VCR, and video-overlay devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_UNFREEZE,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpUnfreeze);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpUnfreeze

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flag is used with the digitalvideo device type:

MCI_DGV_RECT

The rc member of the structure identified by lpUnfreeze contains a valid display rectangle. The rectangle specifies a region within the frame buffer whose pixels should have their lock mask bit turned off. Rectangular regions are specified as described for the MCI_PUT command. If omitted, the rectangle defaults to the entire frame buffer. By using a sequence of freeze and unfreeze commands with different rectangles, arbitrary patterns of lock mask bits can be described.

For digital-video devices, the lpUnfreeze parameter points to an MCI_DGV_UNFREEZE_PARMS  structure. For more information, see the comments for the MCI_DGV_RECT_PARMS structure.

The following additional flags are used with the vcr device type:

MCI_VCR_UNFREEZE_INPUT

Unfreeze the input.

MCI_VCR_UNFREEZE_OUTPUT

Unfreeze the output.

The following additional flag is used with the overlay device type:

MCI_OVLY_RECT

The rc member of the structure identified by lpUnfreeze contains a valid display rectangle. This is a required parameter.

For video-overlay devices, the lpUnfreeze parameter points to an MCI_OVLY_RECT_PARMS structure.

See Also

MCI_DGV_RECT_PARMS, MCI_FREEZE, MCI_GENERIC_PARMS, MCI_OVLY_RECT_PARMS, MCI_PUT


MCI_UPDATE

The MCI_UPDATE command updates the display rectangle. Digital-video devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_UPDATE,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpDest);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpDest

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags are used with the digitalvideo device type:

MCI_DGV_UPDATE_HDC

The hDC member of the structure identified by lpDest contains a valid window of the DC to paint. This flag is required.

MCI_DGV_RECT

The rc member of the structure identified by lpUnfreeze contains a valid display rectangle. The rectangle specifies the clipping rectangle relative to the client rectangle.

MCI_DGV_UPDATE_PAINT

An application uses this flag when it receives a WM_PAINT message that is intended for a display DC. A frame-buffer device usually paints the key color. If the display device does not have a frame buffer, it might ignore the MCI_UPDATE command when the MCI_DGV_UPDATE_PAINT flag is used because the display will be repainted during the playback operation.

For digital-video devices, the lpDest parameter points to an MCI_DGV_UPDATE_PARMS structure.

See Also

MCI_DGV_UPDATE_PARMS, MCI_GENERIC_PARMS


MCI_WHERE

The MCI_WHERE command obtains the clipping rectangle for the video device. Digital-video, and video-overlay devices recognize this command. The top and left members of the returned RECT contain the origin of the clipping rectangle, and the right and bottom members contain the width and height of the clipping rectangle. (This is not the standard use of the right and bottom members.)

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_WHERE,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpQuery);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpQuery

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following additional flags are used with the digitalvideo device type:

MCI_DGV_WHERE_DESTINATION

Obtains a description of the rectangular region used to display video and images in the client area of the current window.

MCI_DGV_WHERE_FRAME

Obtains a description of the rectangular region of the frame buffer into which images from the video rectangle are scaled. The rectangle coordinates are placed in the rc member of the structure identified by lpQuery.

MCI_DGV_WHERE_MAX

When used with MCI_DGV_WHERE_DESTINATION or MCI_DGV_WHERE_SOURCE, the rectangle returned indicates the maximum width and height of the specified region. When used with MCI_DGV_WHERE_WINDOW, the rectangle returned indicates the size of the entire display.

MCI_DGV_WHERE_SOURCE

Obtains a description of the rectangular region (cropped from the frame buffer) that is stretched to fit the destination rectangle on the display.

MCI_DGV_WHERE_VIDEO

Obtains a description of the rectangular region cropped from the presentation source to fill the frame rectangle in the frame buffer. The rectangle coordinates are placed in the rc member of the structure identified by lpQuery.

MCI_DGV_WHERE_WINDOW

Obtains a description of the display-window frame.

For digital-video devices, the lpQuery parameter points to an MCI_DGV_WHERE_PARMS structure. The MCI_DGV_WHERE_PARMS structure is identical to the MCI_DGV_RECT_PARMS structure.

The following additional flags are used with the overlay device type:

MCI_OVLY_WHERE_DESTINATION

Obtains the destination display rectangle. The rectangle coordinates are placed in the rc member of the structure identified by lpQuery.

MCI_OVLY_WHERE_FRAME

Obtains the overlay frame rectangle. The rectangle coordinates are placed in the rc member of the structure identified by lpQuery.

MCI_OVLY_WHERE_SOURCE

Obtains the source rectangle. The rectangle coordinates are placed in the rc member of the structure identified by lpQuery.

MCI_OVLY_WHERE_VIDEO

Obtains the video rectangle. The rectangle coordinates are placed in the rc member of the structure identified by lpQuery.

For video-overlay devices, the lpQuery parameter points to an MCI_OVLY_RECT_PARMS structure.

See Also

MCI_DGV_RECT_PARMS, MCI_GENERIC_PARMS, MCI_OVLY_RECT_PARMS


MCI_WINDOW

The MCI_WINDOW command specifies the window and the window characteristics for graphic devices. Digital-video, and video-overlay devices recognize this command.

MCIERROR mciSendCommand(MCIDEVICEID wDeviceID, MCI_WINDOW,
    DWORD dwFlags, (DWORD) (LPMCI_GENERIC_PARMS) lpWindow);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpWindow

Address of an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Values

Returns zero if successful or an error otherwise.

Remarks

Graphic devices should create a default window when a device is opened but should not display it until they receive the MCI_PLAY command. The MCI_WINDOW command is used to supply an application-created window to the device and to change the display characteristics of an application-defined or default display window. If the application supplies the display window, it should be prepared to update an invalid rectangle on the window.

The following additional flags are used with the digitalvideo device type:

MCI_DGV_WINDOW_HWND

The handle of the window needed for use as the destination is included in the hWnd member of the structure identified by lpWindow.

MCI_DGV_WINDOW_STATE

The nCmdShow member of the structure identified by lpWindow contains parameters for setting the window state.

MCI_DGV_WINDOW_TEXT

The lpstrText member of the structure identified by lpWindow contains an address of a buffer containing the caption used in the window title bar.

For digital-video devices, the lpWindow parameter points to an MCI_DGV_WINDOW_PARMS structure.

The following additional flags are used with the overlay device type:

MCI_OVLY_WINDOW_DISABLE_STRETCH

Disables stretching of the image.

MCI_OVLY_WINDOW_ENABLE_STRETCH

Enables stretching of the image.

MCI_OVLY_WINDOW_HWND

The handle of the window used for the destination is included in the hWnd member of the structure identified by lpWindow. Set this flag to MCI_OVLY_WINDOW_DEFAULT to return to the default window.

MCI_OVLY_WINDOW_STATE

The nCmdShow member of the lpWindow structure contains parameters for setting the window state. This flag is equivalent to calling ShowWindow with the state parameter. The constants are the same as those defined in WINDOWS.H (such as SW_HIDE, SW_MINIMIZE, or SW_SHOWNORMAL).

MCI_OVLY_WINDOW_TEXT

The lpstrText member of the structure identified by lpWindow contains an address of a buffer containing the caption used for the window.

For video-overlay devices, the lpWindow parameter points to an MCI_OVLY_WINDOW_PARMS structure.

See Also

MCI_DGV_WINDOW_PARMS, MCI_GENERIC_PARMS, MCI_OVLY_WINDOW_PARMS, MCI_PLAY, ShowWindow


Constants: Device Types

The following values identify devices in MCI messages and structures:

Value	Meaning
MCI_ALL_DEVICE_ID	Any device
MCI_DEVTYPE_ANIMATION	Animation-playback device
MCI_DEVTYPE_CD_AUDIO	CD audio device
MCI_DEVTYPE_DAT	Digital-audio tape device
MCI_DEVTYPE_DIGITAL_VIDEO	Digital-video playback device
MCI_DEVTYPE_OTHER	Undefined device
MCI_DEVTYPE_OVERLAY	Video-overlay device
MCI_DEVTYPE_SCANNER	Scanner device
MCI_DEVTYPE_SEQUENCER	MIDI sequencer device
MCI_DEVTYPE_VCR	Video-cassette recorder
MCI_DEVTYPE_VIDEODISC	Videodisc player
MCI_DEVTYPE_WAVEFORM_AUDIO	Waveform-audio device


Constants: MCIERR Return Values

The mciSendCommand and mciSendString functions return zero if they are successful; otherwise, they return a doubleword value that contains one of the following error values in the low word. You can obtain a description of individual return values by passing the return values to the mciGetErrorString function.


General Error Values

The following error values can be returned by either the mciSendCommand or mciSendString function:

Value	Meaning
MCIERR_BAD_TIME_FORMAT	The specified value for the time format is invalid.
MCIERR_CANNOT_LOAD_DRIVER	The specified device driver will not load properly.
MCIERR_CANNOT_USE_ALL	The device name “all” is not allowed for this command.
MCIERR_CREATEWINDOW	Could not create or use window.
MCIERR_DEVICE_LENGTH	The device or driver name is too long. Specify a device or driver name that is less than 79 characters.
MCIERR_DEVICE_LOCKED	The device is now being closed. Wait a few seconds, then try again.
MCIERR_DEVICE_NOT_INSTALLED	The specified device is not installed on the system. Use the Drivers option from the Control Panel to install the device.
MCIERR_DEVICE_NOT_READY	The device driver is not ready.
MCIERR_DEVICE_OPEN	The device name is already used as an alias by this application. Use a unique alias.
MCIERR_DEVICE_ORD_LENGTH	The device or driver name is too long. Specify a device or driver name that is less than 79 characters.
MCIERR_DEVICE_TYPE_REQUIRED	The specified device cannot be found on the system. Check that the device is installed and the device name is spelled correctly.
MCIERR_DRIVER	The device driver exhibits a problem. Check with the device manufacturer about obtaining a new driver.
MCIERR_DRIVER_INTERNAL	The device driver exhibits a problem. Check with the device manufacturer about obtaining a new driver.
MCIERR_DUPLICATE_ALIAS	The specified alias is already used in this application. Use a unique alias.
MCIERR_EXTENSION_NOT_FOUND	The specified extension has no device type associated with it. Specify a device type.
MCIERR_EXTRA_CHARACTERS	You must enclose a string with quotation marks; characters following the closing quotation mark are not valid.
MCIERR_FILE_NOT_FOUND	The requested file was not found. Check that the path and filename are correct.
MCIERR_FILE_NOT_SAVED	The file was not saved. Make sure your system has sufficient disk space or has an intact network connection.
MCIERR_FILE_READ	A read from the file failed. Make sure the file is present on your system or that your system has an intact network connection.
MCIERR_FILE_WRITE	A write to the file failed. Make sure your system has sufficient disk space or has an intact network connection.
MCIERR_FILENAME_REQUIRED	The filename is invalid. Make sure the filename is no longer than eight characters, followed by a period and an extension.
MCIERR_FLAGS_NOT_COMPATIBLE	The specified parameters cannot be used together.
MCIERR_GET_CD	The requested file OR MCI device was not found. Try changing directories or restarting your system.
MCIERR_HARDWARE	The specified device exhibits a problem. Check that the device is working correctly or contact the device manufacturer.
MCIERR_ILLEGAL_FOR_AUTO_OPEN	MCI will not perform the specified command on an automatically opened device. Wait until the device is closed, then try to perform the command.
MCIERR_INTERNAL	A problem occurred in initializing MCI. Try restarting the Windows operating system.
MCIERR_INVALID_DEVICE_ID	Invalid device ID. Use the ID given to the device when the device was opened.
MCIERR_INVALID_DEVICE_NAME	The specified device is not open nor recognized by MCI.
MCIERR_INVALID_FILE	The specified file cannot be played on the specified MCI device. The file may be corrupt or may use an incorrect file format.
MCIERR_MISSING_PARAMETER	The specified command requires a parameter, which you must supply.
MCIERR_MULTIPLE	Errors occurred in more than one device. Specify each command and device separately to identify the devices causing the errors.
MCIERR_MUST_USE_SHAREABLE	The device driver is already in use. You must specify the “shareable” parameter with each open command to share the device.
MCIERR_NO_ELEMENT_ALLOWED	The specified device does not use a filename.
MCIERR_NO_INTEGER	The parameter for this MCI command must be an integer value.
MCIERR_NO_WINDOW	There is no display window.
MCIERR_NONAPPLICABLE_FUNCTION	The specified MCI command sequence cannot be performed in the given order. Correct the command sequence; then, try again.
MCIERR_NULL_PARAMETER_BLOCK	A null parameter block (structure) was passed to MCI.
MCIERR_OUT_OF_MEMORY	Your system does not have enough memory for this task. Quit one or more applications to increase the available memory, then, try to perform the task again.
MCIERR_OUTOFRANGE	The specified parameter value is out of range for the specified MCI command.
MCIERR_SET_CD	The specified file or MCI device is inaccessible because the application cannot change directories.
MCIERR_SET_DRIVE	The specified file or MCI device is inaccessible because the application cannot change drives.
MCIERR_UNNAMED_RESOURCE	You cannot store an unnamed file. Specify a filename.
MCIERR_UNRECOGNIZED_COMMAND	The driver cannot recognize the specified command.
MCIERR_UNSUPPORTED_FUNCTION	The MCI device driver the system is using does not support the specified command.


mciSendString Errors

The following errors are returned by the mciSendString function but not by mciSendCommand:

Value	Meaning
MCIERR_BAD_CONSTANT	The value specified for a parameter is unknown.
MCIERR_BAD_INTEGER	An integer in the command was invalid or missing.
MCIERR_DUPLICATE_FLAGS	A flag or value was specified twice.
MCIERR_MISSING_COMMAND_STRING	No command was specified.
MCIERR_MISSING_DEVICE_NAME	No device name was specified.
MCIERR_MISSING_STRING_ARGUMENT	A string value was missing from the command.
MCIERR_NEW_REQUIRES_ALIAS	An alias must be used with the “new” device name.
MCIERR_NO_CLOSING_QUOTE	A closing quotation mark is missing.
MCIERR_NOTIFY_ON_AUTO_OPEN	The “notify” flag is illegal with auto-open.
MCIERR_PARAM_OVERFLOW	The output string was not long enough.
MCIERR_PARSER_INTERNAL	An internal parser error occurred.
MCIERR_UNRECOGNIZED_KEYWORD	An unknown command parameter was specified.


Digital-Video Errors

The following additional return values are defined for digital-video devices:

Value	Meaning
MCIAVI_PRODUCTNAME	Video
MCIERR_AVI_AUDIOERROR	Unknown error while attempting to play audio.
MCIERR_AVI_BADPALETTE	Unable to switch to new palette.
MCIERR_AVI_CANTPLAYFULLSCREEN	This AVI file cannot be played in full screen mode.
MCIERR_AVI_DISPLAYERROR	Unknown error while attempting to display video.
MCIERR_AVI_NOCOMPRESSOR	Can’t locate installable compressor needed to play this file.
MCIERR_AVI_NODISPDIB	256 color VGA mode not available.
MCIERR_AVI_NOTINTERLEAVED	This AVI file is not interleaved.
MCIERR_AVI_OLDAVIFORMAT	This AVI file is of an obsolete format.
MCIERR_AVI_TOOBIGFORVGA	This AVI file is too big to be played in the selected VGA mode.


Sequencer Errors

The following additional return values are defined for MCI sequencers:

Value	Meaning
MCIERR_SEQ_DIV_INCOMPATIBLE	The time formats of the “song pointer” and SMPTE are singular. You can’t use them together.
MCIERR_SEQ_NOMIDIPRESENT	This system has no installed MIDI devices. Use the Drivers option from the Control Panel to install a MIDI driver.
MCIERR_SEQ_PORT_INUSE	The specified MIDI port is already in use. Wait until it is free; then, try again.
MCIERR_SEQ_PORT_MAPNODEVICE	The current MIDI Mapper setup refers to a MIDI device that is not installed on the system. Use the MIDI Mapper from the Control Panel to edit the setup.
MCIERR_SEQ_PORT_MISCERROR	An error occurred with specified port.
MCIERR_SEQ_PORT_NONEXISTENT	The specified MIDI device is not installed on the system. Use the Drivers option from the Control Panel to install a MIDI device.
MCIERR_SEQ_PORTUNSPECIFIED	The system does not have a current MIDI port specified.
MCIERR_SEQ_TIMER	All multimedia timers are being used by other applications. Quit one of these applications; then, try again.


Waveform-Audio Errors

The following additional return values are defined for MCI waveform-audio devices:

Value	Meaning
MCIERR_WAVE_INPUTSINUSE	All waveform devices that can record files in the current format are in use. Wait until one of these devices is free; then, try again.
MCIERR_WAVE_INPUTSUNSUITABLE	No installed waveform device can record files in the current format. Use the Drivers option from the Control Panel to install a suitable waveform recording device.
MCIERR_WAVE_INPUTUNSPECIFIED	You can specify any compatible waveform recording device.
MCIERR_WAVE_OUTPUTSINUSE	All waveform devices that can play files in the current format are in use. Wait until one of these devices is free; then, try again.
MCIERR_WAVE_OUTPUTSUNSUITABLE	No installed waveform device can play files in the current format. Use the Drivers option from the Control Panel to install a suitable waveform device.
MCIERR_WAVE_OUTPUTUNSPECIFIED	You can specify any compatible waveform playback device.
MCIERR_WAVE_SETINPUTINUSE	The current waveform device is in use. Wait until the device is free; then, try again to set the device for recording.
MCIERR_WAVE_SETINPUTUNSUITABLE	The device you are using to record a waveform cannot recognize the data format.
MCIERR_WAVE_SETOUTPUTINUSE	The current waveform device is in use. Wait until the device is free; then, try again to set the device for playback.
MCIERR_WAVE_SETOUTPUTUNSUITABLE	The device you are using to playback a waveform cannot recognize the data format.


acmDriverAdd

The acmDriverAdd function adds a driver to the list of available ACM drivers. The driver type and location are dependent on the flags used to add ACM drivers. After a driver is successfully added, the driver entry function will receive ACM driver messages.

MMRESULT acmDriverAdd(

LPHACMDRIVERID phadid,
HINSTANCE hinstModule,
LPARAM lParam,
DWORD dwPriority,
DWORD fdwAdd
);
Parameters

phadid

Address that is filled with a handle identifying the installed driver. This handle is used to identify the driver in calls to other ACM functions.

hinstModule

Handle of the instance of the module whose executable or dynamic-link library (DLL) contains the driver entry function.

lParam

Driver function address or a notification window handle, depending on the fdwAdd flags.

dwPriority

Window message to send for notification broadcasts. This parameter is used only with the ACM_DRIVERADDF_NOTIFYHWND flag. All other flags require this member to be set to zero.

fdwAdd

Flags for adding ACM drivers. The following values are defined:

ACM_DRIVERADDF_FUNCTION

The lParam parameter is a driver function address conforming to the acmDriverProc prototype. The function may reside in either an executable or DLL file.

ACM_DRIVERADDF_GLOBAL

Provided for compatibility with 16-bit applications. For the Win32 API, ACM drivers added by the acmDriverAdd function can be used only by the application that added the driver. This is true whether or not ACM_DRIVERADDF_GLOBAL is specified. For more information, see Adding Drivers Within an Application.

ACM_DRIVERADDF_LOCAL

The ACM automatically gives a local driver higher priority than a global driver when searching for a driver to satisfy a function call. For more information, see Adding Drivers Within an Application.

ACM_DRIVERADDF_NOTIFYHWND

The lParam parameter is a handle of a notification window that receives messages when changes to global driver priorities and states are made. The window message to receive is defined by the application and must be passed in dwPriority. The wParam and lParam parameters passed with the window message are reserved for future use and should be ignored. ACM_DRIVERADDF_GLOBAL cannot be specified in conjunction with this flag. For more information about driver priorities, see the description for the acmDriverPriority function.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
MMSYSERR_NOMEM	The system is unable to allocate resources.
See Also

acmDriverProc, acmDriverPriority


acmDriverClose

The acmDriverClose function closes a previously opened ACM driver instance. If the function is successful, the handle is invalidated.

MMRESULT acmDriverClose(

HACMDRIVER had,
DWORD fdwClose
);
Parameters

had

Handle of the open driver instance to be closed.

fdwClose

Reserved; must be zero.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

ACMERR_BUSY	The driver is in use and cannot be closed.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.


acmDriverDetails

The acmDriverDetails function queries a specified ACM driver to determine its capabilities.

MMRESULT acmDriverDetails(

HACMDRIVERID hadid,
LPACMDRIVERDETAILS padd,
DWORD fdwDetails
);
Parameters

hadid

Handle of the driver identifier of an installed ACM driver. Disabled drivers can be queried for details.

padd

Address of an ACMDRIVERDETAILS structure that will receive the driver details. The cbStruct member must be initialized to the size, in bytes, of the structure.

fdwDetails

Reserved; must be zero.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
See Also

ACMDRIVERDETAILS


acmDriverEnum

The acmDriverEnum function enumerates the available ACM drivers, continuing until there are no more drivers or the callback function returns FALSE.

MMRESULT acmDriverEnum(

ACMDRIVERENUMCB fnCallback,
DWORD dwInstance,
DWORD fdwEnum
);
Parameters

fnCallback

Procedure instance address of the application-defined callback function.

dwInstance

A 32-bit application-defined value that is passed to the callback function along with ACM driver information.

fdwEnum

Flags for enumerating ACM drivers. The following values are defined:

ACM_DRIVERENUMF_DISABLED

Disabled ACM drivers should be included in the enumeration. Drivers can be disabled by the user through the Control Panel or by an application using the acmDriverPriority function. If a driver is disabled, the fdwSupport parameter to the callback function will have the ACMDRIVERDETAILS_SUPPORTF_DISABLED flag set.

ACM_DRIVERENUMF_NOLOCAL

Only global drivers should be included in the enumeration.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
Remarks

The acmDriverEnum function will return MMSYSERR_NOERROR (zero) if no ACM drivers are installed. Moreover, the callback function will not be called.

See Also

acmDriverPriority


acmDriverEnumCallback

The acmDriverEnumCallback function specifies a callback function used with the acmDriverEnum function. The acmDriverEnumCallback name is a placeholder for an application-defined function name.

BOOL ACMDRIVERENUMCB acmDriverEnumCallback(

HACMDRIVERID hadid,
DWORD dwInstance,
DWORD fdwSupport
);
Parameters

hadid

Handle of an ACM driver identifier.

dwInstance

Application-defined value specified in acmDriverEnum.

fdwSupport

Driver-support flags specific to the driver specified by hadid. These flags are identical to the fdwSupport flags of the ACMDRIVERDETAILS structure. This parameter can be a combination of the following values:

ACMDRIVERDETAILS_SUPPORTF_ASYNC

Driver supports asynchronous conversions.

ACMDRIVERDETAILS_SUPPORTF_CODEC

Driver supports conversion between two different format tags. For example, if a driver supports compression from WAVE_FORMAT_PCM to WAVE_FORMAT_ADPCM, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_CONVERTER

Driver supports conversion between two different formats of the same format tag. For example, if a driver supports resampling of WAVE_FORMAT_PCM, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_DISABLED

Driver has been disabled. An application must specify the ACM_DRIVERENUMF_DISABLED flag with acmDriverEnum to include disabled drivers in the enumeration.

ACMDRIVERDETAILS_SUPPORTF_FILTER

Driver supports a filter (modification of the data without changing any of the format attributes). For example, if a driver supports volume or echo operations on WAVE_FORMAT_PCM, this flag is set.

Return Values

The callback function must return TRUE to continue enumeration or FALSE to stop enumeration.

Remarks

The acmDriverEnum function will return MMSYSERR_NOERROR (zero) if no ACM drivers are installed. Moreover, the callback function will not be called.

The following functions should not be called from within the callback function: acmDriverAdd, acmDriverRemove, and acmDriverPriority.

See Also

ACMDRIVERDETAILS, acmDriverEnum, acmDriverAdd, acmDriverRemove, and acmDriverPriority


acmDriverID

The acmDriverID function returns the handle of an ACM driver identifier associated with an open ACM driver instance or stream handle.

MMRESULT acmDriverID(

HACMOBJ hao,
LPHACMDRIVERID phadid,
DWORD fdwDriverID
);
Parameters

hao

Handle of the open driver instance or stream handle. This is the handle of an ACM object, such HACMDRIVER or HACMSTREAM.

phadid

Address that is filled with a handle identifying the installed driver that is associated with hao.

fdwDriverID

Reserved; must be zero.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.


acmDriverMessage

The acmDriverMessage function sends a user-defined message to a given ACM driver instance.

LRESULT acmDriverMessage(

HACMDRIVER had,
UINT uMsg,
LPARAM lParam1,
LPARAM lParam2
);
Parameters

had

Handle of the ACM driver instance to which the message will be sent.

uMsg

Message that the ACM driver must process. This message must be in the ACMDM_USER message range (above or equal to ACMDM_USER and less than ACMDM_RESERVED_LOW). The exceptions to this restriction are the ACMDM_DRIVER_ABOUT, DRV_QUERYCONFIGURE, and DRV_CONFIGURE messages.

lParam1 and lParam2

Message parameters.

Return Values

The return value is specific to the user-defined ACM driver message specified by the uMsg parameter. However, possible error values include the following:

MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	The uMsg parameter is not in the ACMDM_USER range.
MMSYSERR_NOTSUPPORTED	The ACM driver did not process the message.
Remarks

To display a custom About dialog box from an ACM driver, an application must send the ACMDM_DRIVER_ABOUT message to the driver. The lParam1 parameter should be the handle of the owner window for the custom About dialog box, and lParam2 must be set to zero. If the driver does not support a custom About dialog box, MMSYSERR_NOTSUPPORTED will be returned and it is the application’s responsibility to display its own dialog box. For example, the Control Panel Sound Mapper option will display a default About dialog box based on the ACMDRIVERDETAILS structure when an ACM driver returns MMSYSERR_NOTSUPPORTED. An application can query a driver for custom About dialog box support without the dialog box being displayed by setting lParam1 to − 1L. If the driver supports a custom About dialog box, MMSYSERR_NOERROR will be returned. Otherwise, the return value is MMSYSERR_NOTSUPPORTED.

User-defined messages must be sent only to an ACM driver that specifically supports the messages. The caller should verify that the ACM driver is the correct driver by retrieving the driver details and checking the wMid, wPid, and vdwDriver members of the ACMDRIVERDETAILS structure.

Never send user-defined messages to an unknown ACM driver.

See Also

DRV_QUERYCONFIGURE, DRV_CONFIGURE, ACMDRIVERDETAILS


acmDriverOpen

The acmDriverOpen function opens the specified ACM driver and returns a driver instance handle that can be used to communicate with the driver.

MMRESULT acmDriverOpen(

LPHACMDRIVER phad,
HACMDRIVERID hadid,
DWORD fdwOpen
);
Parameters

phad

Address that will receive the new driver instance handle that can be used to communicate with the driver.

hadid

Handle of the driver identifier of an installed and enabled ACM driver.

fdwOpen

Reserved; must be zero.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
MMSYSERR_NOMEM	The system is unable to allocate resources.
MMSYSERR_NOTENABLED	The driver is not enabled.


acmDriverPriority

The acmDriverPriority function modifies the priority and state of an ACM driver.

MMRESULT acmDriverPriority(

HACMDRIVERID hadid,
DWORD dwPriority,
DWORD fdwPriority
);
Parameters

hadid

Handle of the driver identifier of an installed ACM driver. If the ACM_DRIVERPRIORITYF_BEGIN and ACM_DRIVERPRIORITYF_END flags are specified, this parameter must be NULL.

dwPriority

New priority for a global ACM driver identifier. A zero value specifies that the priority of the driver identifier should remain unchanged. A value of 1 specifies that the driver should be placed as the highest search priority driver. A value of − 1 specifies that the driver should be placed as the lowest search priority driver. Priorities are used only for global drivers.

fdwPriority

Flags for setting priorities of ACM drivers. The following values are defined:

ACM_DRIVERPRIORITYF_BEGIN

Change notification broadcasts should be deferred. An application must reenable notification broadcasts as soon as possible with the ACM_DRIVERPRIORITYF_END flag. Note that hadid must be NULL, dwPriority must be zero, and only the ACM_DRIVERPRIORITYF_BEGIN flag can be set.

ACM_DRIVERPRIORITYF_DISABLE

ACM driver should be disabled if it is currently enabled. Disabling a disabled driver does nothing.

ACM_DRIVERPRIORITYF_ENABLE

ACM driver should be enabled if it is currently disabled. Enabling an enabled driver does nothing.

ACM_DRIVERPRIORITYF_END

Calling task wants to reenable change notification broadcasts. An application must call acmDriverPriority with ACM_DRIVERPRIORITYF_END for each successful call with the ACM_DRIVERPRIORITYF_BEGIN flag. Note that hadid must be NULL, dwPriority must be zero, and only the ACM_DRIVERPRIORITYF_END flag can be set.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

MMSYSERR_ALLOCATED	The deferred broadcast lock is owned by a different task.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
MMSYSERR_NOTSUPPORTED	The requested operation is not supported for the specified driver. For example, local and notify driver identifiers do not support priorities (but can be enabled and disabled). If an application specifies a nonzero value for dwPriority for local and notify driver identifiers, this error will be returned.
Remarks

All driver identifiers can be enabled and disabled, including global, local and notification driver identifiers.

If more than one global driver identifier needs to be enabled, disabled or shifted in priority, an application should defer change notification broadcasts by using the ACM_DRIVERPRIORITYF_BEGIN flag. A single change notification will be broadcast when the ACM_DRIVERPRIORITYF_END flag is specified.

An application can use the  function with the acmMetrics ACM_METRIC_DRIVER_PRIORITY metric index to retrieve the current priority of a global driver. Drivers are always enumerated from highest to lowest priority by the acmDriverEnum function.

All enabled driver identifiers will receive change notifications. An application can register a notification message by using the acmDriverAdd function in conjunction with the ACM_DRIVERADDF_NOTIFYHWND flag. Changes to nonglobal driver identifiers will not be broadcast.

Priorities are simply used for the search order when an application does not specify a driver. Boosting the priority of a driver will have no effect on the performance of a driver.

See Also

acmMetrics, acmDriverEnum, acmDriverAdd


acmDriverProc

The acmDriverProc function specifies a callback function used with the ACM driver. The acmDriverProc name is a placeholder for an application-defined function name. The actual name must be exported by including it in the module-definition file of the executable or DLL file.

LRESULT CALLBACK acmDriverProc(

DWORD dwID,
HDRIVER hdrvr,
UINT uMsg,
LPARAM lParam1,
LPARAM lParam2
);
Parameters

dwID

Identifier of the installable ACM driver.

hdrvr

Handle of the installable ACM driver. This parameter is a unique handle the ACM assigns to the driver.

uMsg

ACM driver message.

lParam1 and lParam2

Message parameters.

Return Values

Returns zero if successful or an error otherwise.

Remarks

Applications should not call any system-defined functions from inside a callback function, except for PostMessage, timeGetSystemTime, timeGetTime, timeSetEvent, timeKillEvent, midiOutShortMsg, midiOutLongMsg, and OutputDebugStr.

See Also

PostMessage, timeGetSystemTime, timeGetTime, timeSetEvent, timeKillEvent, midiOutShortMsg, midiOutLongMsg


acmDriverRemove

The acmDriverRemove function removes an ACM driver from the list of available ACM drivers. The driver will be removed for the calling application only. If the driver is globally installed, other applications will still be able to use it.

MMRESULT acmDriverRemove(

HACMDRIVERID hadid,
DWORD fdwRemove
);
Parameters

hadid

Handle of the driver identifier to be removed.

fdwRemove

Reserved; must be zero.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

ACMERR_BUSY	The driver is in use and cannot be removed.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.


acmFilterChoose

The acmFilterChoose function creates an ACM-defined dialog box that enables the user to select a waveform-audio filter.

MMRESULT acmFilterChoose(

LPACMFILTERCHOOSE pafltrc
);
Parameters

pafltrc

Address of an ACMFILTERCHOOSE structure that contains information used to initialize the dialog box. When acmFilterChoose returns, this structure contains information about the user’s filter selection.

The pwfltr member of this structure must contain a valid pointer to a memory location that will contain the returned filter header structure. The cbwfltr member must be filled in with the size, in bytes, of this memory buffer.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

ACMERR_CANCELED	The user chose the Cancel button or the Close command on the System menu to close the dialog box.
ACMERR_NOTPOSSIBLE	The buffer identified by the pwfltr member of the ACMFILTERCHOOSE structure is too small to contain the selected filter.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
MMSYSERR_NODRIVER	A suitable driver is not available to provide valid filter selections.
See Also

ACMFILTERCHOOSE


acmFilterChooseHookProc

The acmFilterChooseHookProc function specifies a user-defined function that hooks the acmFilterChoose dialog box.

UINT ACMFILTERCHOOSEHOOKPROC acmFilterChooseHookProc(

HWND hwnd,
UINT uMsg,
WPARAM wParam,
LPARAM lParam
);
Parameters

hwnd

Window handle for the dialog box.

uMsg

Window message.

wParam and lParam

Message parameters.

Remarks

To customize the dialog box selections, a hook function can optionally process the MM_ACM_FILTERCHOOSE message.

You should use this function the same way as you use the Common Dialog hook functions for customizing common dialog boxes.

See Also

acmFilterChoose, MM_ACM_FILTERCHOOSE


acmFilterDetails

The acmFilterDetails function queries the ACM for details about a filter with a specific waveform-audio filter tag.

MMRESULT acmFilterDetails(

HACMDRIVER had,
LPACMFILTERDETAILS pafd,
DWORD fdwDetails
);
Parameters

had

Handle of the ACM driver to query for waveform-audio filter details for a filter tag. If this parameter is NULL, the ACM uses the details from the first suitable ACM driver.

pafd

Address of the ACMFILTERDETAILS structure that is to receive the filter details for the given filter tag.

fdwDetails

Flags for getting the details. The following values are defined:

ACM_FILTERDETAILSF_FILTER

A WAVEFILTER structure pointed to by the pwfltr member of the ACMFILTERDETAILS structure was given and the remaining details should be returned. The dwFilterTag member of the ACMFILTERDETAILS structure must be initialized to the same filter tag pwfltr specifies. This query type can be used to get a string description of an arbitrary filter structure. If an application specifies an ACM driver handle for had, details on the filter will be returned for that driver. If an application specifies NULL for had, the ACM finds the first acceptable driver to return the details.

ACM_FILTERDETAILSF_INDEX

A filter index for the filter tag was given in the dwFilterIndex member of the ACMFILTERDETAILS structure. The filter details will be returned in the structure defined by pafd. The index ranges from zero to one less than the cStandardFilters member returned in the ACMFILTERTAGDETAILS structure for a filter tag. An application must specify a driver handle for had when retrieving filter details with this flag. For information about what members should be initialized before calling this function, see the ACMFILTERDETAILS structure.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

ACMERR_NOTPOSSIBLE	The details requested are not available.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
See Also

WAVEFILTER, ACMFILTERTAGDETAILS


acmFilterEnum

The acmFilterEnum function enumerates waveform-audio filters available for a given filter tag from an ACM driver. This function continues enumerating until there are no more suitable filters for the filter tag or the callback function returns FALSE.

MMRESULT acmFilterEnum(

HACMDRIVER had,
LPACMFILTERDETAILS pafd,
ACMFILTERENUMCB fnCallback,
DWORD dwInstance,
DWORD fdwEnum
);
Parameters

had

Handle of the ACM driver to query for waveform-audio filter details. If this parameter is NULL, the ACM uses the details from the first suitable ACM driver.

pafd

Address of the ACMFILTERDETAILS structure that contains the filter details when it is passed to the function specified by fnCallback. When your application calls acmFilterEnum, the cbStruct, pwfltr, and cbwfltr members of this structure must be initialized. The dwFilterTag member must also be initialized to either WAVE_FILTER_UNKNOWN or a valid filter tag.

fnCallback

Procedure-instance address of the application-defined callback function.

dwInstance

A 32-bit, application-defined value that is passed to the callback function along with ACM filter details.

fdwEnum

Flags for enumerating the filters for a given filter tag. The following values are defined:

ACM_FILTERENUMF_DWFILTERTAG

The dwFilterTag member of the WAVEFILTER structure pointed to by the pwfltr member of the ACMFILTERDETAILS structure is valid. The enumerator will enumerate only a filter that conforms to this attribute. The dwFilterTag member of the ACMFILTERDETAILS structure must be equal to the dwFilterTag member of the WAVEFILTER structure.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

ACMERR_NOTPOSSIBLE	The details for the filter cannot be returned.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
Remarks

The acmFilterEnum function will return MMSYSERR_NOERROR (zero) if no suitable ACM drivers are installed. Moreover, the callback function will not be called.

The following functions should not be called from within the callback function: acmDriverAdd, acmDriverRemove, and acmDriverPriority.

See Also

WAVEFILTER, ACMFILTERDETAILS, acmDriverAdd, acmDriverRemove, acmDriverPriority


acmFilterEnumCallback

The acmFilterEnumCallback function specifies a callback function used with the acmFilterEnum function. The acmFilterEnumCallback name is a placeholder for an application-defined function name.

BOOL ACMFILTERENUMCB acmFilterEnumCallback(

HACMDRIVERID hadid,
LPACMFILTERDETAILS pafd,
DWORD dwInstance,
DWORD fdwSupport
);
Parameters

hadid

Handle of the ACM driver identifier.

pafd

Address of an ACMFILTERDETAILS structure that contains the enumerated filter details for a filter tag.

dwInstance

Application-defined value specified in acmFilterEnum.

fdwSupport

Driver-support flags specific to the driver identified by hadid for the specified filter. These flags are identical to the fdwSupport flags of the ACMDRIVERDETAILS structure, but they are specific to the filter that is being enumerated. This parameter can be a combination of the following values and identifies which operations the driver supports for the filter tag:

ACMDRIVERDETAILS_SUPPORTF_ASYNC

Driver supports asynchronous conversions with the specified filter tag.

ACMDRIVERDETAILS_SUPPORTF_CODEC

Driver supports conversion between two different format tags while using the specified filter. For example, if a driver supports compression from WAVE_FORMAT_PCM to WAVE_FORMAT_ADPCM with the specified filter, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_CONVERTER

Driver supports conversion between two different formats of the same format tag while using the specified filter. For example, if a driver supports resampling of WAVE_FORMAT_PCM with the specified filter, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_FILTER

Driver supports a filter (modification of the data without changing any of the format attributes). For example, if a driver supports volume or echo operations on WAVE_FORMAT_PCM, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_HARDWARE

Driver supports hardware input, output, or both with the specified filter through a waveform-audio device. An application should use the acmMetrics function with the ACM_METRIC_HARDWARE_WAVE_INPUT and ACM_METRIC_HARDWARE_WAVE_OUTPUT metric indices to get the waveform-audio device identifiers associated with the supporting ACM driver.

Return Values

The callback function must return TRUE to continue enumeration or FALSE to stop enumeration.

Remarks

The acmFilterEnum function will return MMSYSERR_NOERROR (zero) if no filters are to be enumerated. Moreover, the callback function will not be called.

The following functions should not be called from within the callback function: acmDriverAdd, acmDriverRemove, and acmDriverPriority.

See Also

acmFilterEnum, ACMFILTERDETAILS, acmMetrics, acmDriverAdd, acmDriverRemove, acmDriverPriority


acmFilterTagDetails

The acmFilterTagDetails function queries the ACM for details about a specific waveform-audio filter tag.

MMRESULT acmFilterTagDetails(

HACMDRIVER had,
LPACMFILTERTAGDETAILS paftd,
DWORD fdwDetails
);
Parameters

had

Handle of the ACM driver to query for waveform-audio filter tag details. If this parameter is NULL, the ACM uses the details from the first suitable ACM driver. An application must specify a valid HACMDRIVER or HACMDRIVERID identifier when using the ACM_FILTERTAGDETAILSF_INDEX query type. Driver identifiers for disabled drivers are not allowed.

paftd

Address of the ACMFILTERTAGDETAILS structure that is to receive the filter tag details.

fdwDetails

Flags for getting the details. The following values are defined:

ACM_FILTERTAGDETAILSF_FILTERTAG

A filter tag was given in the dwFilterTag member of the ACMFILTERTAGDETAILS structure. The filter tag details will be returned in the structure pointed to by paftd. If an application specifies an ACM driver handle for had, details on the filter tag will be returned for that driver. If an application specifies NULL for had, the ACM finds the first acceptable driver to return the details.

ACM_FILTERTAGDETAILSF_INDEX

A filter tag index was given in the dwFilterTagIndex member of the ACMFILTERTAGDETAILS structure. The filter tag and details will be returned in the structure pointed to by paftd. The index ranges from zero to one less than the cFilterTags member returned in the ACMDRIVERDETAILS structure for an ACM driver. An application must specify a driver handle for had when retrieving filter tag details with this flag.

ACM_FILTERTAGDETAILSF_LARGESTSIZE

Details on the filter tag with the largest filter size, in bytes, are to be returned. The dwFilterTag member must either be WAVE_FILTER_UNKNOWN or the filter tag to find the largest size for. If an application specifies an ACM driver handle for had, details on the largest filter tag will be returned for that driver. If an application specifies NULL for had, the ACM finds an acceptable driver with the largest filter tag requested to return the details.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

ACMERR_NOTPOSSIBLE	The details requested are not available.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
See Also

ACMDRIVERDETAILS


acmFilterTagEnum

The acmFilterTagEnum function enumerates waveform-audio filter tags available from an ACM driver. This function continues enumerating until there are no more suitable filter tags or the callback function returns FALSE.

MMRESULT acmFilterTagEnum(

HACMDRIVER had,
LPACMFILTERTAGDETAILS paftd,
ACMFILTERTAGENUMCB fnCallback,
DWORD dwInstance,
DWORD fdwEnum
);
Parameters

had

Handle of the ACM driver to query for waveform-audio filter tag details. If this parameter is NULL, the ACM uses the details from the first suitable ACM driver.

paftd

Address of the ACMFILTERTAGDETAILS structure that contains the filter tag details when it is passed to the fnCallback function. When your application calls acmFilterTagEnum, the cbStruct member of this structure must be initialized.

fnCallback

Procedure instance address of the application-defined callback function.

dwInstance

A 32-bit application-defined value that is passed to the callback function along with ACM filter tag details.

fdwEnum

Reserved; must be zero.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
Remarks

This function will return MMSYSERR_NOERROR (zero) if no suitable ACM drivers are installed. Moreover, the callback function will not be called.

See Also

ACMFILTERTAGDETAILS


acmFilterTagEnumCallback

The acmFilterTagEnumCallback function specifies a callback function used with the acmFilterTagEnum function. The acmFilterTagEnumCallback function name is a placeholder for an application-defined function name.

BOOL ACMFILTERTAGENUMCB acmFilterTagEnumCallback(

HACMDRIVERID hadid,
LPACMFILTERTAGDETAILS paftd,
DWORD dwInstance,
DWORD fdwSupport
);
Parameters

hadid

Handle of the ACM driver identifier.

paftd

Address of an ACMFILTERTAGDETAILS structure that contains the enumerated filter tag details.

dwInstance

Application-defined value specified in acmFilterTagEnum.

fdwSupport

Driver-support flags specific to the driver identifier hadid. These flags are identical to the fdwSupport flags of the ACMDRIVERDETAILS structure. This parameter can be a combination of the following values and identifies which operations the driver supports with the filter tag:

ACMSDRIVERDETAILS_SUPPORTF_ASYNC

Driver supports asynchronous conversions with the specified filter tag.

ACMDRIVERDETAILS_SUPPORTF_CODEC

Driver supports conversion between two different format tags while using the specified filter tag. For example, if a driver supports compression from WAVE_FORMAT_PCM to WAVE_FORMAT_ADPCM with the specified filter tag, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_CONVERTER

Driver supports conversion between two different formats of the same format tag while using the specified filter tag. For example, if a driver supports resampling of WAVE_FORMAT_PCM with the specified filter tag, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_FILTER

Driver supports a filter (modification of the data without changing any of the format attributes). For example, if a driver supports volume or echo operations on WAVE_FORMAT_PCM, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_HARDWARE

Driver supports hardware input, output, or both with the specified filter tag through a waveform-audio device. An application should use the acmMetrics function with the ACM_METRIC_HARDWARE_WAVE_INPUT and ACM_METRIC_HARDWARE_WAVE_OUTPUT metric indices to get the waveform-audio device identifiers associated with the supporting ACM driver.

Return Values

The callback function must return TRUE to continue enumeration or FALSE to stop enumeration.

Remarks

The acmFilterTagEnum function will return MMSYSERR_NOERROR (zero) if no filter tags are to be enumerated. Moreover, the callback function will not be called.

The following functions should not be called from within the callback function: acmDriverAdd, acmDriverRemove, and acmDriverPriority.

See Also

acmFilterTagEnum, ACMDRIVERDETAILS, acmMetrics, acmDriverAdd, acmDriverRemove, acmDriverPriority


acmFormatChoose

The acmFormatChoose function creates an ACM-defined dialog box that enables the user to select a waveform-audio format.

MMRESULT acmFormatChoose(

LPACMFORMATCHOOSE pfmtc
);
Parameters

pfmtc

Address of an ACMFORMATCHOOSE structure that contains information used to initialize the dialog box. When this function returns, this structure contains information about the user’s format selection.

The pwfx member of this structure must contain a valid pointer to a memory location that will contain the returned format header structure. Moreover, the cbwfx member must be filled in with the size, in bytes, of this memory buffer.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible return values include the following:

ACMERR_CANCELED	The user chose the Cancel button or the Close command on the System menu to close the dialog box.
ACMERR_NOTPOSSIBLE	The buffer identified by the pwfx member of the ACMFORMATCHOOSE structure is too small to contain the selected format.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
MMSYSERR_NODRIVER	A suitable driver is not available to provide valid format selections.
See Also

ACMFORMATCHOOSE


acmFormatChooseHookProc

The acmFormatChooseHookProc function specifies a user-defined function that hooks the acmFormatChoose dialog box. The acmFormatChooseHookProc name is a placeholder for an application-defined name.

UINT ACMFORMATCHOOSEHOOKPROC acmFormatChooseHookProc(

HWND hwnd,
UINT uMsg,
WPARAM wParam,
LPARAM lParam
);
Parameters

hwnd

Window handle for the dialog box.

uMsg

Window message.

wParam and lParam

Message parameters.

Remarks

If the hook function processes one of the WM_CTLCOLOR messages, this function must return a handle of the brush that should be used to paint the control background.

A hook function can optionally process the MM_ACM_FORMATCHOOSE message.

You should use this function the same way as you use the Common Dialog hook functions for customizing common dialog boxes.

See Also

acmFormatChoose, MM_ACM_FORMATCHOOSE


acmFormatDetails

The acmFormatDetails function queries the ACM for format details for a specific waveform-audio format tag.

MMRESULT acmFormatDetails(

HACMDRIVER had,
LPACMFORMATDETAILS pafd,
DWORD fdwDetails
);
Parameters

had

Handle of the ACM driver to query for waveform-audio format details for a format tag. If this parameter is NULL, the ACM uses the details from the first suitable ACM driver.

pafd

Address of an ACMFORMATDETAILS structure to contain the format details for the given format tag.

fdwDetails

Flags for getting the waveform-audio format tag details. The following values are defined:

ACM_FORMATDETAILSF_FORMAT

A WAVEFORMATEX structure pointed to by the pwfx member of the ACMFORMATDETAILS structure was given and the remaining details should be returned. The dwFormatTag member of the ACMFORMATDETAILS structure must be initialized to the same format tag as pwfx specifies. This query type can be used to get a string description of an arbitrary format structure. If an application specifies an ACM driver handle for had, details on the format will be returned for that driver. If an application specifies NULL for had, the ACM finds the first acceptable driver to return the details.

ACM_FORMATDETAILSF_INDEX

A format index for the format tag was given in the dwFormatIndex member of the ACMFORMATDETAILS structure. The format details will be returned in the structure defined by pafd. The index ranges from zero to one less than the cStandardFormats member returned in the ACMFORMATTAGDETAILS structure for a format tag. An application must specify a driver handle for had when retrieving format details with this flag. For information about which members should be initialized before calling this function, see the ACMFORMATDETAILS structure.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

ACMERR_NOTPOSSIBLE	The details requested are not available.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
See Also

WAVEFORMATEX, ACMFORMATTAGDETAILS


acmFormatEnum

The acmFormatEnum function enumerates waveform-audio formats available for a given format tag from an ACM driver. This function continues enumerating until there are no more suitable formats for the format tag or the callback function returns FALSE.

MMRESULT acmFormatEnum(

HACMDRIVER had,
LPACMFORMATDETAILS pafd,
ACMFORMATENUMCB fnCallback,
DWORD dwInstance,
DWORD fdwEnum
);
Parameters

had

Handle of the ACM driver to query for waveform-audio format details. If this parameter is NULL, the ACM uses the details from the first suitable ACM driver.

pafd

Address of an ACMFORMATDETAILS structure to contain the format details passed to the fnCallback function. This structure must have the cbStruct, pwfx, and cbwfx members of the ACMFORMATDETAILS structure initialized. The dwFormatTag member must also be initialized to either WAVE_FORMAT_UNKNOWN or a valid format tag.

fnCallback

Procedure instance address of the application-defined callback function.

dwInstance

A 32-bit application-defined value that is passed to the callback function along with ACM format details.

fdwEnum

Flags for enumerating the formats for a given format tag. The following values are defined:

ACM_FORMATENUMF_CONVERT

The WAVEFORMATEX structure pointed to by the pwfx member of the ACMFORMATDETAILS structure is valid. The enumerator will only enumerate destination formats that can be converted from the given pwfx format.

ACM_FORMATENUMF_HARDWARE

The enumerator should only enumerate formats that are supported as native input or output formats on one or more of the installed waveform-audio devices. This flag provides a way for an application to choose only formats native to an installed waveform-audio device. This flag must be used with one or both of the ACM_FORMATENUMF_INPUT and ACM_FORMATENUMF_OUTPUT flags. Specifying both ACM_FORMATENUMF_INPUT and ACM_FORMATENUMF_OUTPUT will enumerate only formats that can be opened for input or output. This is true regardless of whether this flag is specified.

ACM_FORMATENUMF_INPUT

Enumerator should enumerate only formats that are supported for input (recording).

ACM_FORMATENUMF_NCHANNELS

The nChannels member of the WAVEFORMATEX structure pointed to by the pwfx member of the ACMFORMATDETAILS structure is valid. The enumerator will enumerate only a format that conforms to this attribute.

ACM_FORMATENUMF_NSAMPLESPERSEC

The nSamplesPerSec member of the WAVEFORMATEX structure pointed to by the pwfx member of the ACMFORMATDETAILS structure is valid. The enumerator will enumerate only a format that conforms to this attribute.

ACM_FORMATENUMF_OUTPUT

Enumerator should enumerate only formats that are supported for output (playback).

ACM_FORMATENUMF_SUGGEST

The WAVEFORMATEX structure pointed to by the pwfx member of the ACMFORMATDETAILS structure is valid. The enumerator will enumerate all suggested destination formats for the given pwfx format. This mechanism can be used instead of the acmFormatSuggest function to allow an application to choose the best suggested format for conversion. The dwFormatIndex member will always be set to zero on return.

ACM_FORMATENUMF_WBITSPERSAMPLE

The wBitsPerSample member of the WAVEFORMATEX structure pointed to by the pwfx member of the ACMFORMATDETAILS structure is valid. The enumerator will enumerate only a format that conforms to this attribute.

ACM_FORMATENUMF_WFORMATTAG

The wFormatTag member of the WAVEFORMATEX structure pointed to by the pwfx member of the ACMFORMATDETAILS structure is valid. The enumerator will enumerate only a format that conforms to this attribute. The dwFormatTag member of the ACMFORMATDETAILS structure must be equal to the wFormatTag member.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

ACMERR_NOTPOSSIBLE	The details for the format cannot be returned.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
Remarks

This function will return MMSYSERR_NOERROR (zero) if no suitable ACM drivers are installed. Moreover, the callback function will not be called.

See Also

acmFormatSuggest, WAVEFORMATEX, ACMFORMATDETAILS


acmFormatEnumCallback

The acmFormatEnumCallback function specifies a callback function used with the acmFormatEnum function. The acmFormatEnumCallback name is a placeholder for the application-defined function name.

BOOL ACMFORMATENUMCB acmFormatEnumCallback(

HACMDRIVERID hadid,
LPACMFORMATDETAILS pafd,
DWORD dwInstance,
DWORD fdwSupport
);
Parameters

hadid

Handle of the ACM driver identifier.

pafd

Address of an ACMFORMATDETAILS structure that contains the enumerated format details for a format tag.

dwInstance

Application-defined value specified in the acmFormatEnum function.

fdwSupport

Driver support flags specific to the driver identified by hadid for the specified format. These flags are identical to the fdwSupport flags of the ACMDRIVERDETAILS structure, but they are specific to the format that is being enumerated. This parameter can be a combination of the following values and indicates which operations the driver supports for the format tag:

ACMDRIVERDETAILS_SUPPORTF_ASYNC

Driver supports asynchronous conversions with the specified filter tag.

ACMDRIVERDETAILS_SUPPORTF_CODEC

Driver supports conversion between two different format tags for the specified format. For example, if a driver supports compression from WAVE_FORMAT_PCM to WAVE_FORMAT_ADPCM with the specified format, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_CONVERTER

Driver supports conversion between two different formats of the same format tag while using the specified format. For example, if a driver supports resampling of WAVE_FORMAT_PCM to the specified format, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_FILTER

Driver supports a filter (modification of the data without changing any of the format attributes) with the specified format. For example, if a driver supports volume or echo operations on WAVE_FORMAT_PCM, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_HARDWARE

Driver supports hardware input, output, or both of the specified format tags through a waveform-audio device. An application should use the acmMetrics function with the ACM_METRIC_HARDWARE_WAVE_INPUT and ACM_METRIC_HARDWARE_WAVE_OUTPUT metric indexes to get the waveform-audio device identifiers associated with the supporting ACM driver.

Return Values

The callback function must return TRUE to continue enumeration or FALSE to stop enumeration.

Remarks

The acmFormatEnum function will return MMSYSERR_NOERROR (zero) if no formats are to be enumerated. Moreover, the callback function will not be called.

The following functions should not be called from within the callback function: acmDriverAdd, acmDriverRemove, and acmDriverPriority.

See Also

acmFormatEnum, ACMFORMATDETAILS, ACMDRIVERDETAILS, acmMetrics, acmDriverAdd, acmDriverRemove, acmDriverPriority


acmFormatSuggest

The acmFormatSuggest function queries the ACM or a specified ACM driver to suggest a destination format for the supplied source format. For example, an application can use this function to determine one or more valid PCM formats to which a compressed format can be decompressed.

MMRESULT acmFormatSuggest(

HACMDRIVER had,
LPWAVEFORMATEX pwfxSrc,
LPWAVEFORMATEX pwfxDst,
DWORD cbwfxDst,
DWORD fdwSuggest
);
Parameters

had

Handle of an open instance of a driver to query for a suggested destination format. If this parameter is NULL, the ACM attempts to find the best driver to suggest a destination format.

pwfxSrc

Address of a WAVEFORMATEX structure that identifies the source format for which a destination format will be suggested by the ACM or specified driver.

pwfxDst

Address of a WAVEFORMATEX structure that will receive the suggested destination format for the pwfxSrc format. Depending on the fdwSuggest parameter, some members of the structure pointed to by pwfxDst may require initialization.

cbwfxDst

Size, in bytes, available for the destination format. The acmMetrics and acmFormatTagDetails functions can be used to determine the maximum size required for any format available for the specified driver (or for all installed ACM drivers).

fdwSuggest

Flags for matching the desired destination format. The following values are defined:

ACM_FORMATSUGGESTF_NCHANNELS

The nChannels member of the structure pointed to by pwfxDst is valid. The ACM will query acceptable installed drivers that can suggest a destination format matching nChannels or fail.

ACM_FORMATSUGGESTF_NSAMPLESPERSEC

The nSamplesPerSec member of the structure pointed to by pwfxDst is valid. The ACM will query acceptable installed drivers that can suggest a destination format matching nSamplesPerSec or fail.

ACM_FORMATSUGGESTF_WBITSPERSAMPLE

The wBitsPerSample member of the structure pointed to by pwfxDst is valid. The ACM will query acceptable installed drivers that can suggest a destination format matching wBitsPerSample or fail.

ACM_FORMATSUGGESTF_WFORMATTAG

The wFormatTag member of the structure pointed to by pwfxDst is valid. The ACM will query acceptable installed drivers that can suggest a destination format matching wFormatTag or fail.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
See Also

WAVEFORMATEX, acmMetrics, acmFormatTagDetails


acmFormatTagDetails

The acmFormatTagDetails function queries the ACM for details on a specific waveform-audio format tag.

MMRESULT acmFormatTagDetails(

HACMDRIVER had,
LPACMFORMATTAGDETAILS paftd,
DWORD fdwDetails
);
Parameters

had

Handle of the ACM driver to query for waveform-audio format tag details. If this parameter is NULL, the ACM uses the details from the first suitable ACM driver. An application must specify a valid handle or driver identifier when using the ACM_FORMATTAGDETAILSF_INDEX query type. Driver identifiers for disabled drivers are not allowed.

paftd

Address of the ACMFORMATTAGDETAILS structure that is to receive the format tag details.

fdwDetails

Flags for getting the details. The following values are defined:

ACM_FORMATTAGDETAILSF_FORMATTAG

A format tag was given in the dwFormatTag member of the ACMFORMATTAGDETAILS structure. The format tag details will be returned in the structure pointed to by paftd. If an application specifies an ACM driver handle for had, details on the format tag will be returned for that driver. If an application specifies NULL for had, the ACM finds the first acceptable driver to return the details.

ACM_FORMATTAGDETAILSF_INDEX

A format tag index was given in the dwFormatTagIndex member of the ACMFORMATTAGDETAILS structure. The format tag and details will be returned in the structure defined by paftd. The index ranges from zero to one less than the cFormatTags member returned in the ACMDRIVERDETAILS structure for an ACM driver. An application must specify a driver handle for had when retrieving format tag details with this flag.

ACM_FORMATTAGDETAILSF_LARGESTSIZE

Details on the format tag with the largest format size, in bytes, are to be returned. The dwFormatTag member of the ACMFORMATTAGDETAILS structure must either be WAVE_FORMAT_UNKNOWN or the format tag to find the largest size for. If an application specifies an ACM driver handle for had, details on the largest format tag will be returned for that driver. If an application specifies NULL for had, the ACM finds an acceptable driver with the largest format tag requested to return the details.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

ACMERR_NOTPOSSIBLE	The details requested are not available.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
See Also

ACMFORMATTAGDETAILS, ACMDRIVERDETAILS


acmFormatTagEnum

The acmFormatTagEnum function enumerates waveform-audio format tags available from an ACM driver. This function continues enumerating until there are no more suitable format tags or the callback function returns FALSE.

MMRESULT acmFormatTagEnum(

HACMDRIVER had,
LPACMFORMATTAGDETAILS paftd,
ACMFORMATTAGENUMCB fnCallback,
DWORD dwInstance,
DWORD fdwEnum
);
Parameters

had

Handle of the ACM driver to query for waveform-audio format tag details. If this parameter is NULL, the ACM uses the details from the first suitable ACM driver.

paftd

Address of the ACMFORMATTAGDETAILS structure that is to receive the format tag details passed to the function specified in fnCallback. This structure must have the cbStruct member of the ACMFORMATTAGDETAILS structure initialized.

fnCallback

Procedure instance address of the application-defined callback function.

dwInstance

A 32-bit application-defined value that is passed to the callback function along with ACM format tag details.

fdwEnum

Reserved; must be zero.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
Remarks

This function will return MMSYSERR_NOERROR (zero) if no suitable ACM drivers are installed. Moreover, the callback function will not be called.

See Also

ACMFORMATTAGDETAILS


acmFormatTagEnumCallback

The acmFormatTagEnumCallback function specifies a callback function used with the acmFormatTagEnum function. The acmFormatTagEnumCallback name is a placeholder for an application-defined function name.

BOOL ACMFORMATTAGENUMCB acmFormatTagEnumCallback(

HACMDRIVERID hadid,
LPACMFORMATTAGDETAILS paftd,
DWORD dwInstance,
DWORD fdwSupport
);
Parameters

hadid

Handle of the ACM driver identifier.

paftd

Address of an ACMFORMATTAGDETAILS structure that contains the enumerated format tag details.

dwInstance

Application-defined value specified in the acmFormatTagEnum function.

fdwSupport

Driver-support flags specific to the format tag. These flags are identical to the fdwSupport flags of the ACMDRIVERDETAILS structure. This parameter can be a combination of the following values and indicates which operations the driver supports with the format tag:

ACMDRIVERDETAILS_SUPPORTF_ASYNC

Driver supports asynchronous conversions with the specified filter tag.

ACMDRIVERDETAILS_SUPPORTF_CODEC

Driver supports conversion between two different format tags where one of the tags is the specified format tag. For example, if a driver supports compression from WAVE_FORMAT_PCM to WAVE_FORMAT_ADPCM, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_CONVERTER

Driver supports conversion between two different formats of the specified format tag. For example, if a driver supports resampling of WAVE_FORMAT_PCM, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_FILTER

Driver supports a filter (modification of the data without changing any of the format attributes). For example, if a driver supports volume or echo operations on the specified format tag, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_HARDWARE

Driver supports hardware input, output, or both of the specified format tag through a waveform-audio device. An application should use acmMetrics with the ACM_METRIC_HARDWARE_WAVE_INPUT and ACM_METRIC_HARDWARE_WAVE_OUTPUT metric indexes to get the waveform-audio device identifiers associated with the supporting ACM driver.

Return Values

The callback function must return TRUE to continue enumeration or FALSE to stop enumeration.

Remarks

The acmFormatTagEnum function will return MMSYSERR_NOERROR (zero) if no format tags are to be enumerated. Moreover, the callback function will not be called.

The following functions should not be called from within the callback function: acmDriverAdd, acmDriverRemove, and acmDriverPriority.

See Also

acmFormatTagEnum, ACMFORMATTAGDETAILS, ACMDRIVERDETAILS, acmMetrics, acmDriverAdd, acmDriverRemove, acmDriverPriority


acmGetVersion

The acmGetVersion function returns the version number of the ACM.

DWORD acmGetVersion(VOID);

Parameters

This function takes no parameters.

Return Values

The version number is returned as a hexadecimal number of the form 0xAABBCCCC, where AA is the major version number, BB is the minor version number, and CCCC is the build number.

Remarks

Win32 applications must verify that the ACM version is at least 0x03320000 (version 3.50) or greater before attempting to use any other ACM functions. The build number (CCCC) is always zero for the retail (non-debug) version of the ACM.

To display the ACM version for a user, an application should use the following format (note that the values should be printed as unsigned decimals):

{

    DWORD   dw;

    TCHAR   ach[10];

    dw = acmGetVersion();

    wsprintf(ach, "%u.%.02u", HIWORD(dw) >> 8, HIWORD(dw) & 0x00FF);

}


acmMetrics

The acmMetrics function returns various metrics for the ACM or related ACM objects.

MMRESULT acmMetrics(

HACMOBJ hao,
UINT uMetric,
LPVOID pMetric
);
Parameters

hao

Handle of the ACM object to query for the metric specified in uMetric. For some queries, this parameter can be NULL.

uMetric

Metric index to be returned in pMetric.

ACM_METRIC_COUNT_CODECS

Returned value is the number of global ACM compressor or decompressor drivers in the system. The hao parameter must be NULL for this metric index. The pMetric parameter must point to a buffer of a size equal to a doubleword value.

ACM_METRIC_COUNT_CONVERTERS

Returned value is the number of global ACM converter drivers in the system. The hao parameter must be NULL for this metric index. The pMetric parameter must point to a buffer of a size equal to a doubleword value.

ACM_METRIC_COUNT_DISABLED

Returned value is the total number of global disabled ACM drivers (of all support types) in the system. The hao parameter must be NULL for this metric index. The pMetric parameter must point to a buffer of a size equal to a doubleword value. The sum of the ACM_METRIC_COUNT_DRIVERS and ACM_METRIC_COUNT_DISABLED metric indices is the total number of globally installed ACM drivers.

ACM_METRIC_COUNT_DRIVERS

Returned value is the total number of enabled global ACM drivers (of all support types) in the system. The hao parameter must be NULL for this metric index. The pMetric parameter must point to a buffer of a size equal to a doubleword value.

ACM_METRIC_COUNT_FILTERS

Returned value is the number of global ACM filter drivers in the system. The hao parameter must be NULL for this metric index. The pMetric parameter must point to a buffer of a size equal to a doubleword value.

ACM_METRIC_COUNT_HARDWARE

Returned value is the number of global ACM hardware drivers in the system. The hao parameter must be NULL for this metric index. The pMetric parameter must point to a buffer of a size equal to a doubleword value.

ACM_METRIC_COUNT_LOCAL_CODECS

Returned value is the number of local ACM compressor drivers, ACM decompressor drivers, or both for the calling task. The hao parameter must be NULL for this metric index. The pMetric parameter must point to a buffer of a size equal to a doubleword value.

ACM_METRIC_COUNT_LOCAL_CONVERTERS

Returned value is the number of local ACM converter drivers for the calling task. The hao parameter must be NULL for this metric index. The pMetric parameter must point to a buffer of a size equal to a doubleword value.

ACM_METRIC_COUNT_LOCAL_DISABLED

Returned value is the total number of local disabled ACM drivers, of all support types, for the calling task. The hao parameter must be NULL for this metric index. The pMetric parameter must point to a buffer of a size equal to a doubleword value. The sum of the ACM_METRIC_COUNT_LOCAL_DRIVERS and ACM_METRIC_COUNT_LOCAL_DISABLED metric indices is the total number of locally installed ACM drivers.

ACM_METRIC_COUNT_LOCAL_DRIVERS

Returned value is the total number of enabled local ACM drivers (of all support types) for the calling task. The hao parameter must be NULL for this metric index. The pMetric parameter must point to a buffer of a size equal to a doubleword value.

ACM_METRIC_COUNT_LOCAL_FILTERS

Returned value is the number of local ACM filter drivers for the calling task. The hao parameter must be NULL for this metric index. The pMetric parameter must point to a buffer of a size equal to a doubleword value.

ACM_METRIC_DRIVER_PRIORITY

Returned value is the current priority for the specified driver. The hao parameter must be a valid ACM driver identifier of the HACMDRIVERID data type. The pMetric parameter must point to a buffer of a size equal to a doubleword value.

ACM_METRIC_DRIVER_SUPPORT

Returned value is the fdwSupport flags for the specified driver. The hao parameter must be a valid ACM driver identifier of the HACMDRIVERID data type. The pMetric parameter must point to a buffer of a size equal to a doubleword value.

ACM_METRIC_HARDWARE_WAVE_INPUT

Returned value is the waveform-audio input device identifier associated with the specified driver. The hao parameter must be a valid ACM driver identifier of the HACMDRIVERID data type that supports the ACMDRIVERDETAILS_SUPPORTF_HARDWARE flag. If no waveform-audio input device is associated with the driver, MMSYSERR_NOTSUPPORTED is returned. The pMetric parameter must point to a buffer of a size equal to a doubleword value.

ACM_METRIC_HARDWARE_WAVE_OUTPUT

Returned value is the waveform-audio output device identifier associated with the specified driver. The hao parameter must be a valid ACM driver identifier of the HACMDRIVERID data type that supports the ACMDRIVERDETAILS_SUPPORTF_HARDWARE flag. If no waveform-audio output device is associated with the driver, MMSYSERR_NOTSUPPORTED is returned. The pMetric parameter must point to a buffer of a size equal to a doubleword value.

ACM_METRIC_MAX_SIZE_FILTER

Returned value is the size of the largest WAVEFILTER structure. If hao is NULL, the return value is the largest WAVEFILTER structure in the system. If hao identifies an open instance of an ACM driver of the HACMDRIVER data type or an ACM driver identifier of the HACMDRIVERID data type, the largest WAVEFILTER structure for that driver is returned. The pMetric parameter must point to a buffer of a size equal to a doubleword value. This metric is not allowed for an ACM stream handle of the HACMSTREAM data type.

ACM_METRIC_MAX_SIZE_FORMAT

Returned value is the size of the largest WAVEFORMATEX structure. If hao is NULL, the return value is the largest WAVEFORMATEX structure in the system. If hao identifies an open instance of an ACM driver of the HACMDRIVER data type or an ACM driver identifier of the HACMDRIVERID data type, the largest WAVEFORMATEX structure for that driver is returned. The pMetric parameter must point to a buffer of a size equal to a doubleword value. This metric is not allowed for an ACM stream handle of the HACMSTREAM data type.

pMetric

Address of the buffer to receive the metric details. The exact definition depends on the uMetric index.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

ACMERR_NOTPOSSIBLE	The index specified in uMetric cannot be returned for the specified hao.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
MMSYSERR_NOTSUPPORTED	The index specified in uMetric is not supported.
See Also

WAVEFILTER, WAVEFORMATEX


acmStreamClose

The acmStreamClose function closes an ACM conversion stream. If the function is successful, the handle is invalidated.

MMRESULT acmStreamClose(

HACMSTREAM has,
DWORD fdwClose
);
Parameters

has

Handle of the open conversion stream to be closed.

fdwClose

Reserved; must be zero.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

ACMERR_BUSY	The conversion stream cannot be closed because an asynchronous conversion is still in progress.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.


acmStreamConvert

The acmStreamConvert function requests the ACM to perform a conversion on the specified conversion stream. A conversion may be synchronous or asynchronous, depending on how the stream was opened.

MMRESULT acmStreamConvert(

HACMSTREAM has,
LPACMSTREAMHEADER pash,
DWORD fdwConvert
);
Parameters

has

Handle of the open conversion stream.

pash

Address of a stream header that describes source and destination buffers for a conversion. This header must have been prepared previously by using the acmStreamPrepareHeader function.

fdwConvert

Flags for doing the conversion. The following values are defined:

ACM_STREAMCONVERTF_BLOCKALIGN

Only integral numbers of blocks will be converted. Converted data will end on block-aligned boundaries. An application should use this flag for all conversions on a stream until there is not enough source data to convert to a block-aligned destination. In this case, the last conversion should be specified without this flag.

ACM_STREAMCONVERTF_END

ACM conversion stream should begin returning pending instance data. For example, if a conversion stream holds instance data, such as the end of an echo filter operation, this flag will cause the stream to start returning this remaining data with optional source data. This flag can be specified with the ACM_STREAMCONVERTF_START flag.

ACM_STREAMCONVERTF_START

ACM conversion stream should reinitialize its instance data. For example, if a conversion stream holds instance data, such as delta or predictor information, this flag will restore the stream to starting defaults. This flag can be specified with the ACM_STREAMCONVERTF_END flag.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

ACMERR_BUSY	The stream header specified in pash is currently in use and cannot be reused.
ACMERR_UNPREPARED	The stream header specified in pash is currently not prepared by the acmStreamPrepareHeader function.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
Remarks

You must use the acmStreamPrepareHeader function to prepare the source and destination buffers before they are passed to acmStreamConvert.

If an asynchronous conversion request is successfully queued by the ACM or driver and the conversion is later determined to be impossible, the ACMSTREAMHEADER structure is posted back to the application’s callback function with the cbDstLengthUsed member set to zero.

See Also

acmStreamPrepareHeader, ACMSTREAMHEADER


acmStreamConvertCallback

The acmStreamConvertCallback function specifies an application-provided callback function to be used when the acmStreamOpen function specifies the CALLBACK_FUNCTION flag. The acmStreamConvertCallback name is a placeholder for an application-defined function name.

void CALLBACK acmStreamConvertCallback(

HACMSTREAM has,
UINT uMsg,
DWORD dwInstance,
LPARAM lParam1,
LPARAM lParam2
);
Parameters

has

Handle of the ACM conversion stream associated with the callback function.

uMsg

ACM conversion stream message. The following values are defined:

MM_ACM_CLOSE

ACM has successfully closed the conversion stream identified by has. The handle specified by has is no longer valid after receiving this message.

MM_ACM_DONE

ACM has successfully converted the buffer identified by lParam1 (which is a pointer to the ACMSTREAMHEADER structure) for the stream handle identified by has.

MM_ACM_OPEN

ACM has successfully opened the conversion stream identified by has.

dwInstance

User-instance data given as the dwInstance parameter of the acmStreamOpen function.

lParam1 and lParam2

Message parameters.

Return Values

This function does not return a value.

Remarks

The following functions should not be called from within the callback function: acmDriverAdd, acmDriverRemove, and acmDriverPriority.

See Also

acmStreamOpen, ACMSTREAMHEADER, acmDriverAdd, acmDriverRemove, acmDriverPriority


acmStreamMessage

The acmStreamMessage function sends a driver-specific message to an ACM driver.

MMRESULT ACMAPI acmStreamMessage(

HACMSTREAM has,
UINT uMsg,
LPARAM lParam1,
LPARAM lParam2
);
Parameters

has

Handle of an open conversion stream.

uMsg

Message to send.

lParam1 and lParam2

Message parameters.

Return Values

Returns the value returned by the ACM device driver.


acmStreamOpen

The acmStreamOpen function opens an ACM conversion stream. Conversion streams are used to convert data from one specified audio format to another.

MMRESULT acmStreamOpen(

LPHACMSTREAM phas,
HACMDRIVER had,
LPWAVEFORMATEX pwfxSrc,
LPWAVEFORMATEX pwfxDst,
LPWAVEFILTER pwfltr,
DWORD dwCallback,
DWORD dwInstance,
DWORD fdwOpen
);
Parameters

phas

Address of a handle that will receive the new stream handle that can be used to perform conversions. This handle is used to identify the stream in calls to other ACM stream conversion functions. If the ACM_STREAMOPENF_QUERY flag is specified, this parameter should be NULL.

had

Handle of an ACM driver. If this handle is specified, it identifies a specific driver to be used for a conversion stream. If this parameter is NULL, all suitable installed ACM drivers are queried until a match is found.

pwfxSrc

Address of a WAVEFORMATEX structure that identifies the desired source format for the conversion.

pwfxDst

Address of a WAVEFORMATEX structure that identifies the desired destination format for the conversion.

pwfltr

Address of a WAVEFILTER structure that identifies the desired filtering operation to perform on the conversion stream. If no filtering operation is desired, this parameter can be NULL. If a filter is specified, the source (pwfxSrc) and destination (pwfxDst) formats must be the same.

dwCallback

Address of a callback function, a handle of a window, or a handle of an event. A callback function will be called only if the conversion stream is opened with the ACM_STREAMOPENF_ASYNC flag. A callback function is notified when the conversion stream is opened or closed and after each buffer is converted. If the conversion stream is opened without the ACM_STREAMOPENF_ASYNC flag, this parameter should be set to zero.

dwInstance

User-instance data passed to the callback function specified by the dwCallback parameter. This parameter is not used with window and event callbacks. If the conversion stream is opened without the ACM_STREAMOPENF_ASYNC flag, this parameter should be set to zero.

fdwOpen

Flags for opening the conversion stream. The following values are defined:

ACM_STREAMOPENF_ASYNC

Stream conversion should be performed asynchronously. If this flag is specified, the application can use a callback function to be notified when the conversion stream is opened and closed and after each buffer is converted. In addition to using a callback function, an application can examine the fdwStatus member of the ACMSTREAMHEADER structure for the ACMSTREAMHEADER_STATUSF_DONE flag.

ACM_STREAMOPENF_NONREALTIME

ACM will not consider time constraints when converting the data. By default, the driver will attempt to convert the data in real time. For some formats, specifying this flag might improve the audio quality or other characteristics.

ACM_STREAMOPENF_QUERY

ACM will be queried to determine whether it supports the given conversion. A conversion stream will not be opened, and no handle will be returned in the phas parameter.

CALLBACK_EVENT

The dwCallback parameter is a handle of an event.

CALLBACK_FUNCTION

The dwCallback parameter is a callback procedure address. The function prototype must conform to the acmStreamConvertCallback prototype.

CALLBACK_WINDOW

The dwCallback parameter is a window handle.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

ACMERR_NOTPOSSIBLE	The requested operation cannot be performed.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
MMSYSERR_NOMEM	The system is unable to allocate resources.
Remarks

If an ACM driver cannot perform real-time conversions and the ACM_STREAMOPENF_NONREALTIME flag is not specified for the fdwOpen parameter, the open operation will fail returning an ACMERR_NOTPOSSIBLE error code. An application can use the ACM_STREAMOPENF_QUERY flag to determine if real-time conversions are supported for input.

If an application uses a window to receive callback information, the MM_ACM_OPEN, MM_ACM_CLOSE, and MM_ACM_DONE messages are sent to the window procedure function to indicate the progress of the conversion stream. In this case, the wParam parameter identifies the HACMSTREAM handle. The lParam parameter identifies the ACMSTREAMHEADER structure for MM_ACM_DONE, but it is not used for MM_ACM_OPEN and MM_ACM_CLOSE.

If an application uses a function to receive callback information, the MM_ACM_OPEN, MM_ACM_CLOSE, and MM_ACM_DONE messages are sent to the function to indicate the progress of waveform-audio output. The callback function must reside in a dynamic-link library (DLL).

If an application uses an event for callback notification, the event is signaled to indicate the progress of the conversion stream. The event will be signaled when a stream is opened, after each buffer is converted, and when the stream is closed.

See Also

WAVEFORMATEX, WAVEFILTER, ACMSTREAMHEADER, acmStreamConvertCallback


acmStreamPrepareHeader

The acmStreamPrepareHeader function prepares an ACMSTREAMHEADER structure for an ACM stream conversion. This function must be called for every stream header before it can be used in a conversion stream. An application needs to prepare a stream header only once for the life of a given stream. The stream header can be reused as long as the sizes of the source and destination buffers do not exceed the sizes used when the stream header was originally prepared.

MMRESULT acmStreamPrepareHeader(

HACMSTREAM has,
LPACMSTREAMHEADER pash,
DWORD fdwPrepare
);
Parameters

has

Handle of the conversion steam.

pash

Address of an ACMSTREAMHEADER structure that identifies the source and destination buffers to be prepared.

fdwPrepare

Reserved; must be zero.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
MMSYSERR_NOMEM	The system is unable to allocate resources.
Remarks

Preparing a stream header that has already been prepared has no effect, and the function returns zero. Nevertheless, you should ensure your application does not prepare a stream header multiple times.

See Also

ACMSTREAMHEADER


acmStreamReset

The acmStreamReset function stops conversions for a given ACM stream. All pending buffers are marked as done and returned to the application.

MMRESULT acmStreamReset(

HACMSTREAM has,
DWORD fdwReset
);
Parameters

has

Handle of the conversion stream.

fdwReset

Reserved; must be zero.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
Remarks

Resetting an ACM conversion stream is necessary only for asynchronous conversion streams. Resetting a synchronous conversion stream will succeed, but no action will be taken.


acmStreamSize

The acmStreamSize function returns a recommended size for a source or destination buffer on an ACM stream.

MMRESULT acmStreamSize(

HACMSTREAM has,
DWORD cbInput,
LPDWORD pdwOutputBytes,
DWORD fdwSize
);
Parameters

has

Handle of the conversion stream.

cbInput

Size, in bytes, of the source or destination buffer. The fdwSize flags specify what the input parameter defines. This parameter must be nonzero.

pdwOutputBytes

Address of a variable that contains the size, in bytes, of the source or destination buffer. The fdwSize flags specify what the output parameter defines. If the acmStreamSize function succeeds, this location will always be filled with a nonzero value.

fdwSize

Flags for the stream size query. The following values are defined:

ACM_STREAMSIZEF_DESTINATION

The cbInput parameter contains the size of the destination buffer. The pdwOutputBytes parameter will receive the recommended source buffer size, in bytes.

ACM_STREAMSIZEF_SOURCE

The cbInput parameter contains the size of the source buffer. The pdwOutputBytes parameter will receive the recommended destination buffer size, in bytes.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

ACMERR_NOTPOSSIBLE	The requested operation cannot be performed.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
Remarks

An application can use this function to determine suggested buffer sizes for either source or destination buffers. The buffer sizes returned might be only an estimation of the actual sizes required for conversion. Because actual conversion sizes cannot always be determined without performing the conversion, the sizes returned will usually be overestimated.

In the event of an error, the location pointed to by pdwOutputBytes will receive zero. This assumes that the pointer specified by pdwOutputBytes is valid.


acmStreamUnprepareHeader

The acmStreamUnprepareHeader function cleans up the preparation performed by the acmStreamPrepareHeader function for an ACM stream. This function must be called after the ACM is finished with the given buffers. An application must call this function before freeing the source and destination buffers.

MMRESULT acmStreamUnprepareHeader(

HACMSTREAM has,
LPACMSTREAMHEADER pash,
DWORD fdwUnprepare
);
Parameters

has

Handle of the conversion steam.

pash

Address of an ACMSTREAMHEADER structure that identifies the source and destination buffers to be unprepared.

fdwUnprepare

Reserved; must be zero.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

ACMERR_BUSY	The stream header specified in pash is currently in use and cannot be unprepared.
ACMERR_UNPREPARED	The stream header specified in pash is currently not prepared by the acmStreamPrepareHeader function.
MMSYSERR_INVALFLAG	At least one flag is invalid.
MMSYSERR_INVALHANDLE	The specified handle is invalid.
MMSYSERR_INVALPARAM	At least one parameter is invalid.
Remarks

Unpreparing a stream header that has already been unprepared is an error. An application must specify the source and destination buffer lengths (cbSrcLength and cbDstLength, respectively) that were used during a call to the corresponding acmStreamPrepareHeader. Failing to reset these member values will cause acmStreamUnprepareHeader to fail with an MMSYSERR_INVALPARAM error.

The ACM can recover from some errors. The ACM will return a nonzero error, yet the stream header will be properly unprepared. To determine whether the stream header was actually unprepared, an application can examine the ACMSTREAMHEADER_STATUSF_PREPARED flag. If acmStreamUnprepareHeader returns success, the header will always be unprepared.

See Also

acmStreamPrepareHeader, ACMSTREAMHEADER


auxGetDevCaps

The auxGetDevCaps function retrieves the capabilities of a given auxiliary output device.

MMRESULT auxGetDevCaps(

UINT uDeviceID,
LPAUXCAPS lpCaps,
UINT cbCaps
);
Parameters

uDeviceID

Identifier of the auxiliary output device to be queried. Specify a valid device identifier (see the following comments section), or use the following constant:

AUX_MAPPER

Auxiliary audio mapper. The function returns an error if no auxiliary audio mapper is installed.

lpCaps

Address of an AUXCAPS structure to be filled with information about the capabilities of the device.

cbCaps

Size, in bytes, of the AUXCAPS structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_BADDEVICEID	Specified device identifier is out of range.
Remarks

The device identifier in uDeviceID varies from zero to one less than the number of devices present. AUX_MAPPER may also be used. Use the auxGetNumDevs function to determine the number of auxiliary output devices present in the system.

See Also

AUXCAPS, auxGetNumDevs


auxGetNumDevs

The auxGetNumDevs function retrieves the number of auxiliary output devices present in the system.

UINT auxGetNumDevs(VOID);

Parameters

This function takes no parameters.

Return Values

Returns the number of device. A return value of zero means that no devices are present or that an error occurred.


auxGetVolume

The auxGetVolume function retrieves the current volume setting of the specified auxiliary output device.

MMRESULT auxGetVolume(

UINT uDeviceID,
LPDWORD lpdwVolume
);
Parameters

uDeviceID

Identifier of the auxiliary output device to be queried.

lpdwVolume

Address of a variable to be filled with the current volume setting. The low-order word of this location contains the left channel volume setting, and the high-order word contains the right channel setting. A value of 0xFFFF represents full volume, and a value of 0x0000 is silence.

If a device does not support both left and right volume control, the low-order word of the specified location contains the volume level.

The full 16-bit setting(s) set with the auxSetVolume function are returned, regardless of whether the device supports the full 16 bits of volume-level control.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_BADDEVICEID	Specified device identifier is out of range.
Remarks

Not all devices support volume control. To determine whether a device supports volume control, use the AUXCAPS_VOLUME flag to test the dwSupport member of the AUXCAPS structure (filled by the auxGetDevCaps function).

To determine whether a device supports volume control on both the left and right channels, use the AUXCAPS_LRVOLUME flag to test the dwSupport member of the AUXCAPS structure (filled by auxGetDevCaps).

See Also

auxSetVolume, AUXCAPS, auxGetDevCaps


auxOutMessage

The auxOutMessage function sends a message to the given auxiliary output device. This function also performs error checking on the device identifier passed as part of the message.

DWORD auxOutMessage(

UINT uDeviceID,
UINT uMsg,
DWORD dwParam1,
DWORD dwParam2
);
Parameters

uDeviceID

Identifier of the auxiliary output device to receive the message.

uMsg

Message to send.

dwParam1 and dwParam2

Message parameters.

Return Values

Returns the message return value.


auxSetVolume

The auxSetVolume function sets the volume of the specified auxiliary output device.

MMRESULT auxSetVolume(

UINT uDeviceID,
DWORD dwVolume
);
Parameters

uDeviceID

Identifier of the auxiliary output device to be queried. Device identifiers are determined implicitly from the number of devices present in the system. Device identifier values range from zero to one less than the number of devices present. Use the auxGetNumDevs function to determine the number of auxiliary devices in the system.

dwVolume

Specifies the new volume setting. The low-order word specifies the left-channel volume setting, and the high-order word specifies the right-channel setting. A value of 0xFFFF represents full volume, and a value of 0x0000 is silence.

If a device does not support both left and right volume control, the low-order word of dwVolume specifies the volume level, and the high-order word is ignored.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_BADDEVICEID	Specified device identifier is out of range.
Remarks

Not all devices support volume control. To determine whether the device supports volume control, use the AUXCAPS_VOLUME flag to test the dwSupport member of the AUXCAPS structure (filled by the auxGetDevCaps function).

To determine whether the device supports volume control on both the left and right channels, use the AUXCAPS_LRVOLUME flag to test the dwSupport member of the AUXCAPS structure (filled by auxGetDevCaps).

Most devices do not support the full 16 bits of volume-level control and will use only the high-order bits of the requested volume setting. For example, for a device that supports 4 bits of volume control, requested volume level values of 0x4000, 0x4FFF, and 0x43BE will produce the same physical volume setting, 0x4000. The auxGetVolume function will return the full 16-bit setting set with auxSetVolume.

Volume settings are interpreted logarithmically. This means the perceived volume increase is the same when increasing the volume level from 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.

See Also

AUXCAPS, auxGetDevCaps, auxGetVolume


AVIBuildFilter

The AVIBuildFilter function builds a filter specification that is subsequently used by the GetOpenFileName or GetSaveFileName function.

STDAPI AVIBuildFilter(

LPTSTR lpszFilter,
LONG cbFilter,
BOOL fSaving
);
Parameters

lpszFilter

Address of the buffer containing the filter string.

cbFilter

Size, in bytes, of buffer pointed to by lpszFilter.

fSaving

Flag that indicates whether the filter should include read or write formats. Specify TRUE to include write formats or FALSE to include read formats.

Return Values

Returns AVIERR_OK if successful or an error otherwise. Possible error values include the following:

AVIERR_BUFFERTOOSMALL	The buffer size cbFilter was smaller than the generated filter specification.
AVIERR_MEMORY	There was not enough memory to complete the read operation.
Remarks

This function accesses the registry for all filter types that the AVIFile library can use to open, read, or write multimedia files. It does not search the hard disk for filter DLLs and formats.

See Also

GetOpenFileName, GetSaveFileName


AVIClearClipboard

The AVIClearClipboard function removes an AVI file from the clipboard.

STDAPI AVIClearClipboard(VOID);

Parameters

This function takes no parameters.

Return Values

Returns zero if successful or an error otherwise.


AVIFileAddRef

The AVIFileAddRef function increments the reference count of an AVI file.

STDAPI_(ULONG) AVIFileAddRef(

PAVIFILE pfile
);
Parameters

pfile

Handle of an open AVI file.

Return Values

Returns the updated reference count for the file interface.


AVIFileCreateStream

The AVIFileCreateStream function creates a new stream in an existing file and creates an interface to the new stream.

STDAPI AVIFileCreateStream(

PAVIFILE pfile,
PAVISTREAM * ppavi,
AVISTREAMINFO * psi
);
Parameters

pfile

Handle of an open AVI file.

ppavi

Address of the new stream interface.

psi

Address of a structure containing information about the new stream, including the stream type and its sample rate.

Return Values

Returns zero if successful or an error otherwise. Unless the file has been opened with write permission, this function returns AVIERR_READONLY.

Remarks

This function starts a reference count for the new stream.


AVIFileEndRecord

The AVIFileEndRecord function marks the end of a record when writing an interleaved file that uses a 1:1 interleave factor of video to audio data. (Each frame of video is interspersed with an equivalent amount of audio data.)

STDAPI AVIFileEndRecord(

PAVIFILE pfile
);
Parameters

pfile

Handle of an open AVI file.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The AVISave function uses this function internally. In general, applications should not need to use this function.

See Also

AVISave


AVIFileExit

The AVIFileExit function exits the AVIFile library and decrements the reference count for the library.

This function supercedes the obsolete AVIStreamExit function.

STDAPI_(VOID) AVIFileExit(VOID);

Parameters

This function takes no parameters.

Return Values

This function does not return a value.


AVIFileGetStream

The AVIFileGetStream function returns the address of a stream interface that is associated with a specified AVI file.

STDAPI AVIFileGetStream(

PAVIFILE pfile,
PAVISTREAM * ppavi,
DWORD fccType,
LONG lParam
);
Parameters

pfile

Handle of an open AVI file.

ppavi

Address of the new stream interface.

fccType

Four-character code indicating the type of stream to open. Zero indicates any stream can be opened. The following definitions apply to the data commonly found in AVI streams:

streamtypeAUDIO	Indicates an audio stream.
streamtypeMIDI	Indicates a MIDI stream.
streamtypeTEXT	Indicates a text stream.
streamtypeVIDEO	Indicates a video stream.
lParam

Count of the stream type. Identifies which occurrence of the specified stream type to access.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

AVIERR_NODATA	The file does not contain a stream corresponding to the values of fccType and lParam.
AVIERR_MEMORY	Not enough memory.


AVIFileInfo

The AVIFileInfo function obtains information about an AVI file.

STDAPI AVIFileInfo(

PAVIFILE pfile,
AVIFILEINFO * pfi,
LONG lSize
);
Parameters

pfile

Handle of an open AVI file.

pfi

Address of the structure used to return file information. Typically, this parameter points to an AVIFILEINFO structure.

lSize

Size, in bytes, of the structure.

Return Values

Returns zero if successful or an error otherwise.

See Also

AVIFILEINFO


AVIFileInit

The AVIFileInit function initializes the AVIFile library.

The AVIFile library maintains a count of the number of times it is initialized, but not the number of times it was released. Use the AVIFileExit function to release the AVIFile library and decrement the reference count. Call AVIFileInit before using any other AVIFile functions.

This function supercedes the obsolete AVIStreamInit function.

STDAPI_(VOID) AVIFileInit(VOID);

Parameters

This function takes no parameters.

Return Values

This function does not return a value.

See Also

AVIFileExit


AVIFileOpen

The AVIFileOpen function opens an AVI file and returns the address of a file interface used to access it. The AVIFile library maintains a count of the number of times a file is opened, but not the number of times it was released. Use the AVIFileRelease function to release the file and decrement the count.

STDAPI AVIFileOpen(

PAVIFILE * ppfile,
LPCTSTR szFile,
UINT mode,
CLSID * pclsidHandler
);
Parameters

ppfile

Address to contain the new file interface pointer.

szFile

Null-terminated string containing the name of the file to open.

mode

Access mode to use when opening the file. The default access mode is OF_READ. The following access modes can be specified with AVIFileOpen:

OF_CREATE

Creates a new file. If the file already exists, it is truncated to zero length.

OF_SHARE_DENY_NONE

Opens the file nonexclusively. Other processes can open the file with read or write access. AVIFileOpen fails if another process has opened the file in compatibility mode.

OF_SHARE_DENY_READ

Opens the file nonexclusively. Other processes can open the file with write access. AVIFileOpen fails if another process has opened the file in compatibility mode or has read access to it.

OF_SHARE_DENY_WRITE

Opens the file nonexclusively. Other processes can open the file with read access. AVIFileOpen fails if another process has opened the file in compatibility mode or has write access to it.

OF_SHARE_EXCLUSIVE

Opens the file and denies other processes any access to it. AVIFileOpen fails if any other process has opened the file.

OF_READ

Opens the file for reading.

OF_READWRITE

Opens the file for reading and writing.

OF_WRITE

Opens the file for writing.

pclsidHandler

Address of a class identifier of the standard or custom handler you want to use. If the value is NULL, the system chooses a handler from the registry based on the file extension or the RIFF type specified in the file.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

AVIERR_BADFORMAT	The file couldn’t be read, indicating a corrupt file or an unrecognized format.
AVIERR_MEMORY	The file could not be opened because of insufficient memory.
AVIERR_FILEREAD	A disk error occurred while reading the file.
AVIERR_FILEOPEN	A disk error occurred while opening the file.
REGDB_E_CLASSNOTREG	According to the registry, the type of file specified in AVIFileOpen does not have a handler to process it.
See Also

AVIFileRelease


AVIFileReadData

The AVIFileReadData function reads optional header data that applies to the entire file, such as author or copyright information.

STDAPI AVIFileReadData(

PAVIFILE pfile,
DWORD ckid,
LPVOID lpData,
LONG * lpcbData
);
Parameters

pfile

Handle of an open AVI file.

ckid

RIFF chunk identifier (four-character code) of the data.

lpData

Address of the buffer used to return the data read.

lpcbData

Address of a location indicating the size of the memory block referenced by lpData. If the data is read successfully, the value is changed to indicate the amount of data read.

Return Values

Returns zero if successful or an error otherwise. The return value AVIERR_NODATA indicates that data with the requested chunk identifier does not exist.

Remarks

The optional header information is custom and does not have a set format.


AVIFileRelease

The AVIFileRelease function decrements the reference count of an AVI file interface handle and closes the file if the count reaches zero.

This function supercedes the obsolete AVIFileClose function.

STDAPI_(ULONG) AVIFileRelease(

PAVIFILE pfile
);
Parameters

pfile

Handle of an open AVI file.

Return Values

Returns the reference count of the file. This return value should be used only for debugging purposes.


AVIFileWriteData

The AVIFileWriteData function writes supplementary data (other than normal header, format, and stream data) to the file.

STDAPI AVIFileWriteData(

PAVIFILE pfile,
DWORD ckid,
LPVOID lpData,
LONG cbData
);
Parameters

pfile

Handle of an open AVI file.

ckid

RIFF chunk identifier (four-character code) of the data.

lpData

Address of the buffer used to write the data.

cbData

Size, in bytes, of the memory block referenced by lpData.

Return Values

Returns zero if successful or an error otherwise. In an application has read-only access to the file, the error code AVIERR_READONLY is returned.

Remarks

Use the AVIStreamWriteData function to write data that applies to an individual stream.

See Also

AVIStreamWriteData


AVIGetFromClipboard

The AVIGetFromClipboard function copies an AVI file from the clipboard.

STDAPI AVIGetFromClipboard(

PAVIFILE * lppf
);
Parameters

lppf

Address of the location used to return the handle created for the AVI file.

Return Values

Returns zero if successful or an error otherwise.

Remarks

If the clipboard does not contain an AVI file, AVIGetFromClipboard also can copy data with the CF_DIB or CF_WAVE clipboard flags to an AVI file. In this case, the function creates an AVI file with one DIB stream and one waveform-audio stream, and fills each stream with the data from the clipboard.


AVIMakeCompressedStream

The AVIMakeCompressedStream function creates a compressed stream from an uncompressed stream and a compression filter, and returns the address of a pointer to the compressed stream. This function supports audio and video compression.

STDAPI AVIMakeCompressedStream(

PAVISTREAM * ppsCompressed,
PAVISTREAM psSource,
AVICOMPRESSOPTIONS * lpOptions,
CLSID * pclsidHandler
);
Parameters

ppsCompressed

Address to contain the compressed stream pointer.

psSource

Address of the stream to be compressed.

lpOptions

Address of a structure that identifies the type of compression to use and the options to apply. You can specify video compression by identifying an appropriate handler in the AVICOMPRESSOPTIONS structure. For audio compression, specify the compressed data format.

pclsidHandler

Address of a class identifier used to create the stream.

Return Values

Returns AVIERR_OK if successful or an error otherwise. Possible error values include the following:

AVIERR_NOCOMPRESSOR	A suitable compressor cannot be found.
AVIERR_MEMORY	There is not enough memory to complete the operation.
AVIERR_UNSUPPORTED	Compression is not supported for this type of data. This error might be returned if you try to compress data that is not audio or video.
Remarks

Applications can read from or write to the compressed stream.

See Also

AVICOMPRESSOPTIONS


AVIMakeFileFromStreams

The AVIMakeFileFromStreams function constructs an AVIFile interface pointer from separate streams.

STDAPI AVIMakeFileFromStreams(

PAVIFILE * ppfile,
int nStreams,
PAVISTREAM * papStreams
);
Parameters

ppfile

Address to contain the new file interface pointer.

nStreams

Count of the number of streams in the array of stream interface pointers referenced by papStreams.

papStreams

Address of an array of stream interface pointers.

Return Values

Returns zero if successful or an error otherwise.

Remarks

Use the AVIFileRelease function to close the file.

Other functions can use the AVIFile interface created by this function to copy and edit the streams associated with the interface. For example, you can retrieve a specific stream by using AVIFileGetStream with the file interface pointer.

See Also

AVIFileRelease, AVIFileGetStream


AVIMakeStreamFromClipboard

The AVIMakeStreamFromClipboard function creates an editable stream from stream data on the clipboard.

SDTAPI AVIMakeStreamFromClipboard(

UINT cfFormat,
HANDLE hGlobal,
PAVISTREAM * ppstream
);
Parameters

cfFormat

Clipboard flag.

hGlobal

Handle of stream data on the clipboard.

ppstream

Handle of the created stream.

Return Values

Returns zero if successful or an error otherwise.

Remarks

When an application finishes using the editable stream, it must release the stream to free the resources associated with it.


AVIPutFileOnClipboard

The AVIPutFileOnClipboard function copies an AVI file to the clipboard.

STDAPI AVIPutFileOnClipboard(

PAVIFILE pf
);
Parameters

pf

Handle of an open AVI file.

Return Values

Returns zero if successful or an error otherwise.

Remarks

This function also copies data with the CF_DIB, CF_PALETTE, and CF_WAVE clipboard flags onto the clipboard using the first frame of the first video stream of the file as a DIB and using the audio stream as CF_WAVE.


AVISave

The AVISave function builds a file by combining data streams from other files or from memory.

HRESULT AVISave(

LPCTSTR szFile,
CLSID * pclsidHandler,
AVISAVECALLBACK lpfnCallback,
int nStreams,
PAVISTREAM pavi,
LPAVICOMPRESSOPTIONS lpOptions,
. . .
);
Parameters

szFile

Null-terminated string containing the name of the file to save.

pclsidHandler

Address of the file handler used to write the file. The file is created by calling the AVIFileOpen function using this handler. If a handler is not specified, a default is selected from the registry based on the file extension.

lpfnCallback

Address of a callback function for the save operation.

nStreams

Number of streams saved in the file.

pavi

Address of an AVI stream. This parameter is paired with lpOptions. The parameter pair can be repeated as a variable number of arguments.

lpOptions

Address of an application-defined AVICOMPRESSOPTIONS structure containing the compression options for the stream referenced by pavi. This parameter is paired with pavi. The parameter pair can be repeated as a variable number of arguments.

Return Values

Returns AVIERR_OK if successful or an error otherwise.

Remarks

This function creates a file, copies stream data into the file, closes the file, and releases the resources used by the new file. The last two parameters of this function identify a stream to save in the file and define the compression options of that stream. When saving more than one stream in an AVI file, repeat these two stream-specific parameters for each stream in the file.

A callback function (referenced by using lpfnCallback) can display status information and let the user cancel the save operation. The callback function uses the following format:

LONG PASCAL SaveCallback(int nPercent)

The nPercent parameter specifies the percentage of the file saved.

The callback function should return AVIERR_OK if the operation should continue and AVIERR_USERABORT if the user wishes to abort the save operation.

See Also

AVIFileOpen, AVICOMPRESSOPTIONS


AVISaveOptions

The AVISaveOptions function retrieves the save options for a file and returns them in a buffer.

BOOL AVISaveOptions(

HWND hwnd,
UINT uiFlags,
int nStreams,
PAVISTREAM * ppavi,
LPAVICOMPRESSOPTIONS * plpOptions
);
Parameters

hwnd

Handle of the parent window for the Compression Options dialog box.

uiFlags

Flags for displaying the Compression Options dialog box. The following flags are defined:

ICMF_CHOOSE_KEYFRAME

Displays a Key Frame Every dialog box for the video options. This is the same flag used in the ICCompressorChoose function.

ICMF_CHOOSE_DATARATE

Displays a Data Rate dialog box for the video options. This is the same flag used in ICCompressorChoose.

ICMF_CHOOSE_PREVIEW

Displays a Preview button for the video options. This button previews the compression by using a frame from the stream. This is the same flag used in ICCompressorChoose.

nStreams

Number of streams that have their options set by the dialog box.

ppavi

Address of an array of stream interface pointers. The nStreams parameter indicates the number of pointers in the array.

plpOptions

Address of an array of pointers to AVICOMPRESSOPTIONS structures. These structures hold the compression options set by the dialog box. The nStreams parameter indicates the number of pointers in the array.

Return Values

Returns TRUE if the user pressed OK, FALSE for CANCEL, or an error otherwise.

Remarks

This function presents a standard Compression Options dialog box using hwnd as the parent window handle. When the user is finished selecting the compression options for each stream, the options are returned in the AVICOMPRESSOPTIONS structure in the array referenced by plpOptions. The calling application must pass the interface pointers for the streams in the array referenced by ppavi.

An application must allocate memory for the AVICOMPRESSOPTIONS structures and the array of pointers to these structures.

See Also

ICCompressorChoose, AVICOMPRESSOPTIONS


AVISaveOptionsFree

The AVISaveOptionsFree function frees the resources allocated by the AVISaveOptions function.

LONG AVISaveOptionsFree(

int nStreams,
LPAVICOMPRESSOPTIONS *plpOptions
);
Parameters

nStreams

Count of the AVICOMPRESSOPTIONS structures referenced in plpOptions.

plpOptions

Address of an array of pointers to AVICOMPRESSOPTIONS structures. These structures hold the compression options set by the dialog box. The resources allocated by AVISaveOptions for each of these structures will be freed.

Return Values

Returns AVIERR_OK.

See Also

AVISaveOptions, AVICOMPRESSOPTIONS


AVISaveV

The AVISaveV function builds a file by combining data streams from other files or from memory.

STDAPI AVISaveV(

LPCTSTR szFile,
CLSID * pclsidHandler,
AVISAVECALLBACK lpfnCallback,
int nStreams,
PAVISTREAM * ppavi,
LPAVICOMPRESSOPTIONS * plpOptions
);
Parameters

szFile

Null-terminated string containing the name of the file to save.

pclsidHandler

Address of the file handler used to write the file. The file is created by calling the AVIFileOpen function using this handler. If a handler is not specified, a default is selected from the registry based on the file extension.

lpfnCallback

Address of a callback function used to display status information and to let the user cancel the save operation.

nStreams

Number of streams to save.

ppavi

Address of an array of pointers to the AVISTREAM function structures. The array uses one pointer for each stream.

plpOptions

Address of an array of pointers to AVICOMPRESSOPTIONS structures. The array uses one pointer for each stream.

Return Values

Returns AVIERR_OK if successful or an error otherwise.

Remarks

This function is equivalent to the AVISave function except the streams are passed in an array instead of as a variable number of arguments.

This function creates a file, copies stream data into the file, closes the file, and releases the resources used by the new file. The last two parameters of this function are arrays that identify the streams to save in the file and define the compression options of those streams.

An application must allocate memory for the AVICOMPRESSOPTIONS structures and the array of pointers to these structures.

See Also

AVIFileOpen, AVICOMPRESSOPTIONS, AVISave


AVIStreamAddRef

The AVIStreamAddRef function increments the reference count of an AVI stream.

STDAPI_(LONG) AVIStreamAddRef(

PAVISTREAM pavi
);
Parameters

pavi

Handle of an open AVI stream.

Return Values

Returns the current reference count of the stream. This value should be used only for debugging purposes.


AVIStreamBeginStreaming

The AVIStreamBeginStreaming function specifies the parameters used in streaming and lets a stream handler prepare for streaming.

STDAPI AVIStreamBeginStreaming(

PAVISTREAM pavi,
LONG lStart,
LONG lEnd,
LONG lRate
);
Parameters

pavi

Address of a stream.

lStart

Starting frame for streaming.

lEnd

Ending frame for streaming.

lRate

Speed at which the file is read relative to its natural speed.  Specify 1000 for the normal speed. Values less than 1000 indicate a slower-than-normal speed; values greater than 1000 indicate a faster-than-normal speed.

Return Values

Returns zero if successful or an error otherwise.


AVIStreamCreate

The AVIStreamCreate function creates a stream not associated with any file.

STDAPI AVIStreamCreate(

PAVISTREAM * ppavi,
LONG lParam1,
LONG lParam2,
CLSID * pclsidHandler
);
Parameters

ppavi

Address to contain the new stream interface.

lParam1

Stream-handler specific information.

lParam2

Stream-handler specific information.

pclsidHandler

Address of the class identifier used for the stream.

Return Values

Returns zero if successful or an error otherwise.

Remarks

You should not need to call this function. Some functions, such as CreateEditableStream and AVIMakeCompressedStream, use it internally.

See Also

CreateEditableStream, AVIMakeCompressedStream


AVIStreamEndStreaming

The AVIStreamEndStreaming function ends streaming.

STDAPI AVIStreamEndStreaming(

PAVISTREAM pavi
);
Parameters

pavi

Address of a stream.

Return Values

Returns zero if successful or an error otherwise.

Remarks

Many stream implementations ignore this function.


AVIStreamFindSample

The AVIStreamFindSample function returns the position of a sample (key frame, nonempty frame, or a frame containing a format change) relative to the specified position.

This function supercedes the obsolete AVIStreamFindKeyFrame function.

STDAPI_(LONG) AVIStreamFindSample(

PAVISTREAM pavi,
LONG lPos,
LONG lFlags
);
Parameters

pavi

Handle of an open stream.

lPos

Starting frame for the search.

lFlags

Flags that designate the type of frame to locate, the direction in the stream to search, and the type of return information. The following flags are defined:

FIND_ANY

Finds a nonempty frame. This flag supercedes the SEARCH_ANY flag.

FIND_KEY

Finds a key frame. This flag supercedes the SEARCH_KEY flag.

FIND_FORMAT

Finds a format change.

FIND_NEXT

Finds nearest sample, frame, or format change searching forward. The current sample is included in the search. Use this flag with the FIND_ANY, FIND_KEY, or FIND_FORMAT flag. This flag supercedes the SEARCH_FORWARD flag.

FIND_PREV

Finds nearest sample, frame, or format change searching backward. The current sample is included in the search. Use this flag with the FIND_ANY, FIND_KEY, or FIND_FORMAT flag. This flag supercedes the SEARCH_NEAREST and SEARCH_BACKWARD flags.

FIND_FROM_START

Finds first sample, frame, or format change beginning from the start of the stream. Use this flag with the FIND_ANY, FIND_KEY, or FIND_FORMAT flag.

Return Values

Returns the position of the frame found or -1 if the search is unsuccessful.

Remarks

The FIND_KEY, FIND_ANY, and FIND_FORMAT flags are mutually exclusive, as are the FIND_NEXT and FIND_PREV flags.


AVIStreamGetFrame

The AVIStreamGetFrame function returns the address of a decompressed video frame.

STDAPI_(LPVOID) AVIStreamGetFrame(

PGETFRAME pgf,
LONG lPos
);
Parameters

pgf

Address of a GetFrame object.

lPos

Position, in samples, within the stream of the desired frame.

Return Values

Returns a pointer to the frame data if successful or NULL otherwise. The frame data is returned as a packed DIB.

Remarks

The returned frame is valid only until the next call to this function or the AVIStreamGetFrameClose function.

See Also

AVIStreamGetFrameClose


AVIStreamGetFrameClose

The AVIStreamGetFrameClose function releases resources used to decompress video frames.

STDAPI AVIStreamGetFrameClose(

PGETFRAME pget
);
Parameters

pget

Handle returned from the AVIStreamGetFrameOpen function. After calling this function, the handle is invalid.

Return Values

Returns zero if successful or an error otherwise.

See Also

AVIStreamGetFrameOpen


AVIStreamGetFrameOpen

The AVIStreamGetFrameOpen function prepares to decompress video frames from the specified video stream.

STDAPI_(PGETFRAME) AVIStreamGetFrameOpen(

PAVISTREAM pavi,
LPBITMAPINFOHEADER lpbiWanted
);
Parameters

pavi

Address of the video stream used as the video source.

lpbiWanted

Address of a structure that defines the desired video format. Specify NULL to use a default format. You can also specify AVIGETFRAMEF_BESTDISPLAYFMT to decode the frames to the best format for your display.

Return Values

Returns a GetFrame object that can be used with the AVIStreamGetFrame function. If the system cannot find a decompressor that can decompress the stream to the given format, or to any RGB format, the function returns NULL.

See Also

AVIStreamGetFrame


AVIStreamInfo

The AVIStreamInfo function obtains stream header information.

STDAPI AVIStreamInfo(

PAVISTREAM pavi,
AVISTREAMINFO * psi,
LONG lSize
);
Parameters

pavi

Handle of an open stream.

psi

Address of a structure to contain the stream information.

lSize

Size, in bytes, of the structure used for psi.

Return Values

Returns zero if successful or an error otherwise.


AVIStreamLength

The AVIStreamLength function returns the length of the stream.

STDAPI_(LONG) AVIStreamLength(

PAVISTREAM pavi
);
Parameters

pavi

Handle of an open stream.

Return Values

Returns the stream’s length, in samples, if successful or -1 otherwise.


AVIStreamOpenFromFile

The AVIStreamOpenFromFile function opens a single stream from a file.

STDAPI AVIStreamOpenFromFile(

PAVISTREAM * ppavi,
LPCTSTR szFile,
DWORD fccType,
LONG lParam,
UINT mode,
CLSID * pclsidHandler
);
Parameters

ppavi

Address to contain the new stream handle.

szFile

Null-terminated string containing the name of the file to open.

fccType

Four-character code indicating the type of stream to be opened. Zero indicates that any stream can be opened. The following definitions apply to the data commonly found in AVI streams:

streamtypeAUDIO	Indicates an audio stream.
streamtypeMIDI	Indicates a MIDI stream.
streamtypeTEXT	Indicates a text stream.
streamtypeVIDEO	Indicates a video stream.
lParam

Stream of the type specified in fccType to access. This parameter is zero-based; use zero to specify the first occurrence.

mode

Access mode to use when opening the file. This function can open only existing streams, so the OF_CREATE mode flag cannot be used. For more information about the available flags for the mode parameter, see the OpenFile function.

pclsidHandler

Address of a class identifier of the handler you want to use. If the value is NULL, the system chooses one from the registry based on the file extension or the file RIFF type.

Return Values

Returns zero if successful or an error otherwise.

Remarks

This function calls the AVIFileOpen, AVIFileGetStream, and AVIFileRelease functions.

See Also

OpenFile, AVIFileOpen, AVIFileGetStream, AVIFileRelease


AVIStreamRead

The AVIStreamRead function reads audio, video or other data from a stream according to the stream type.

STDAPI AVIStreamRead(

PAVISTREAM pavi,
LONG lStart,
LONG lSamples,
LPVOID lpBuffer,
LONG cbBuffer,
LONG * plBytes,
LONG * plSamples
);
Parameters

pavi

Handle of an open stream.

lStart

First sample to read.

lSamples

Number of samples to read. You can also specify the value AVISTREAMREAD_CONVENIENT to let the stream handler determine the number of samples to read.

lpBuffer

Address of a buffer to contain the data.

cbBuffer

Size, in bytes, of the buffer pointed to by lpBuffer.

plBytes

Address to contain the number of bytes of data written in the buffer referenced by lpBuffer. This value can be NULL.

plSamples

Address to contain the number of samples written in the buffer referenced by lpBuffer. This value can be NULL.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

AVIERR_BUFFERTOOSMALL	The buffer size cbBuffer was smaller than a single sample of data.
AVIERR_MEMORY	There was not enough memory to complete the read operation.
AVIERR_FILEREAD	A disk error occurred while reading the file.
Remarks

If lpBuffer is NULL, this function does not read any data; it returns information about the size of data that would be read.


AVIStreamReadData

The AVIStreamReadData function reads optional header data from a stream.

STDAPI AVIStreamReadData(

PAVISTREAM pavi,
DWORD ckid,
LPVOID lpData,
LONG * lpcbData
);
Parameters

pavi

Handle of an open stream.

ckid

Four-character code identifying the data.

lpData

Address of the buffer to contain the optional header data.

lpcbData

Address of the location that specifies the buffer size used for lpData. If the read is successful, AVIFile changes this value to indicate the amount of data written into the buffer for lpData.

Return Values

Returns zero if successful or an error otherwise. The return value AVIERR_NODATA indicates the system could not find any data with the specified chunk identifier.

Remarks

This function retrieves only optional header information from the stream. This information is custom and does not have a set format.


AVIStreamReadFormat

The AVIStreamReadFormat function reads the stream format data.

STDAPI AVIStreamReadFormat(

PAVISTREAM pavi,
LONG lPos,
LPVOID lpFormat,
LONG * lpcbFormat
);
Parameters

pavi

Handle of an open stream.

lPos

Position in the stream used to obtain the format data.

lpFormat

Address of a buffer to contain the format data.

lpcbFormat

Address of a location indicating the size of the memory block referenced by lpFormat. On return, the value is changed to indicate the amount of data read. If lpFormat is NULL, this parameter can be used to obtain the amount of memory needed to return the format.

Return Values

Returns zero if successful or an error otherwise.


AVIStreamRelease

The AVIStreamRelease function decrements the reference count of an AVI stream interface handle, and closes the stream if the count reaches zero.

This function supercedes the obsolete AVIStreamClose function.

STDAPI_(LONG) AVIStreamRelease(

PAVISTREAM pavi
);
Parameters

pavi

Handle of an open stream.

Return Values

Returns the current reference count of the stream. This value should be used only for debugging purposes.


AVIStreamSampleToTime

The AVIStreamSampleToTime function converts a stream position from samples to milliseconds.

STDAPI_(LONG) AVIStreamSampleToTime(

PAVISTREAM pavi,
LONG lSample
);
Parameters

pavi

Handle of an open stream.

lSample

Position information. A sample can correspond to blocks of audio, a video frame, or other format, depending on the stream type.

Return Values

Returns the converted time if successful or − 1 otherwise.


AVIStreamSetFormat

The AVIStreamSetFormat function sets the format of a stream at the specified position.

STDAPI AVIStreamSetFormat(

PAVISTREAM pavi,
LONG lPos,
LPVOID lpFormat,
LONG cbFormat
);
Parameters

pavi

Handle of an open stream.

lPos

Position in the stream to receive the format.

lpFormat

Address of a structure containing the new format.

cbFormat

Size, in bytes, of the block of memory referenced by lpFormat.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The handler for writing AVI files does not accept format changes. Besides setting the initial format for a stream, only changes in the palette of a video stream are allowed in an AVI file. The palette change must occur after any frames already written to the AVI file. Other handlers might impose different restrictions.


AVIStreamStart

The AVIStreamStart function returns the starting sample number for the stream.

STDAPI_(LONG) AVIStreamStart(

PAVISTREAM pavi
);
Parameters

pavi

Handle of an open stream.

Return Values

Returns the number if successful or − 1 otherwise.


AVIStreamTimeToSample

The AVIStreamTimeToSample function converts from milliseconds to samples.

STDAPI_(LONG) AVIStreamTimeToSample(

PAVISTREAM pavi,
LONG lTime
);
Parameters

pavi

Handle of an open stream.

lTime

Time, expressed in milliseconds.

Return Values

Returns the converted time if successful or − 1 otherwise.

Remarks

Samples typically correspond to audio samples or video frames. Other stream types might support different formats than these.


AVIStreamWrite

The AVIStreamWrite function writes data to a stream.

STDAPI AVIStreamWrite(

PAVISTREAM pavi,
LONG lStart,
LONG lSamples,
LPVOID lpBuffer,
LONG cbBuffer,
DWORD dwFlags,
LONG * plSampWritten,
LONG * plBytesWritten
);
Parameters

pavi

Handle of an open stream.

lStart

First sample to write.

lSamples

Number of samples to write.

lpBuffer

Address of a buffer containing the data to write.

cbBuffer

Size of the buffer referenced by lpBuffer.

dwFlags

Flag associated with this data. The following flag is defined:

AVIIF_KEYFRAME

Indicates this data does not rely on preceding data in the file.

plSampWritten

Address to contain the number of samples written. This can be set to NULL.

plBytesWritten

Address to contain the number of bytes written. This can be set to NULL.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The default AVI file handler supports writing only at the end of a stream. The “WAVE” file handler supports writing anywhere.

This function overwrites existing data, rather than inserting new data.


AVIStreamWriteData

The AVIStreamWriteData function writes optional header information to the stream.

STDAPI AVIStreamWriteData(

PAVISTREAM pavi,
DWORD ckid,
LPVOID lpData,
LONG cbData
);
Parameters

pavi

Handle of an open stream.

ckid

Four-character code identifying the data.

lpData

Address of a buffer containing the data to write.

cbData

Number of bytes of data to write into the stream.

Return Values

Returns zero if successful or an error otherwise. The return value AVIERR_READONLY indicates the file was opened without write access.

Remarks

Use the AVIStreamWrite function to write the multimedia content of the stream. Use AVIFileWriteData to write data that applies to an entire file.

See Also

AVIStreamWrite, AVIFileWriteData


capCreateCaptureWindow

The capCreateCaptureWindow function creates a capture window.

HWND VFWAPI capCreateCaptureWindow(

LPCSTR lpszWindowName,
DWORD dwStyle,
int x,
int y,
int nWidth,
int nHeight,
HWND hWnd,
int nID
);
Parameters

lpszWindowName

Null-terminated string containing the name used for the capture window.

dwStyle

Window styles used for the capture window. Window styles are described with the CreateWindowEx function.

x and y

The x- and y-coordinates of the upper left corner of the capture window.

nWidth and nHeight

Width and height of the capture window.

hWnd

Handle of the parent window.

nID

Window identifier.

Return Values

Returns a handle of the capture window if successful or NULL otherwise.

See Also

CreateWindowEx


capControlCallback

The capControlCallback function is the callback function used for precision control to begin and end streaming capture. The capControlCallback callback function is a placeholder for the application-supplied function name.

LRESULT CALLBACK capControlCallback(

HWND hWnd,
int nState
);
Parameters

hWnd

Handle of the capture window associated with the callback function.

nState

Current state of the capture operation. The CONTROLCALLBACK_PREROLL value is sent initially to enable prerolling of the video sources and to return control to the capture application at the exact moment recording is to begin. The CONTROLCALLBACK_CAPTURING value is sent once per captured frame to indicate that streaming capture is in progress and to enable the application to end capture.

Return Values

When nState is set to CONTROLCALLBACK_PREROLL, this callback function must return TRUE to start capture or FALSE to abort it. When nState is set to CONTROLCALLBACK_CAPTURING, this callback function must return TRUE to continue capture or FALSE to end it.

Remarks

The first message sent to the callback procedure sets the nState parameter to CONTROLCALLBACK_PREROLL after allocating all buffers and all other capture preparations are complete.


capGetDriverDescription

The capGetDriverDescription function retrieves the version description of the capture driver.

BOOL VFWAPI capGetDriverDescription(

WORD wDriverIndex,
LPSTR lpszName,
INT cbName,
LPSTR lpszVer,
INT cbVer
);
Parameters

wDriverIndex

Index of the capture driver. The index can range from 0 through 9.

Plug-and-Play capture drivers are enumerated first, followed by capture drivers listed in the registry, which are then followed by capture drivers listed in SYSTEM.INI.

lpszName

Address of a buffer containing a null-terminated string corresponding to the capture driver name.

cbName

Length, in bytes, of the buffer pointed to by lpszName.

lpszVer

Address of a buffer containing a null-terminated string corresponding to the description of the capture driver.

cbVer

Length, in bytes, of the buffer pointed to by lpszVer.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

If the information description is longer than its buffer, the description is truncated. The returned string is always null-terminated. If a buffer size is zero, its corresponding description is not copied.


capErrorCallback

The capErrorCallback function is the error callback function used with video capture. The capErrorCallback error callback function is a placeholder for the application-supplied function name.

LRESULT CALLBACK capErrorCallback(

HWND hWnd,
int nID,
LPCSTR lpsz
);
Parameters

hWnd

Handle of the capture window associated with the callback function.

nID

Error identification number.

lpsz

Address of a textual description of the returned error.

Remarks

A message identifier of zero indicates a new operation is starting and the callback function should clear the current error.


capStatusCallback

The capStatusCallback function is the status callback function used with video capture. The capStatusCallback status callback function is a placeholder for the application-supplied function name.

LRESULT CALLBACK capStatusCallback(

HWND hWnd,
int nID,
LPCSTR lpsz
);
Parameters

hWnd

Handle of the capture window associated with the callback function.

nID

Message identification number.

lpsz

Address of a textual description of the returned status.

Remarks

During capture operations, the first message sent to the callback function is always IDS_CAP_BEGIN and the last is always IDS_CAP_END. A message identifier of zero indicates a new operation is starting and the callback function should clear the current status.


capVideoStreamCallback

The capVideoStreamCallback function is the callback function used with streaming capture to optionally process a frame of captured video. The capVideoStreamCallback callback function is a placeholder for the application-supplied function name.

LRESULT CALLBACK capVideoStreamCallback(

HWND hWnd,
LPVIDEOHDR lpVHdr
);
Parameters

hWnd

Handle of the capture window associated with the callback function.

lpVHdr

Address of a VIDEOHDR structure containing information about the captured frame.

Remarks

The capture window calls a videostream callback function when a video buffer is marked done by the capture driver. When capturing to disk, this will preceed the disk write operation.


capWaveStreamCallback

The capWaveStreamCallback function is the callback function used with streaming capture to optionally process buffers of audio data. The capWaveStreamCallback callback function is a placeholder for the application-supplied function name.

LRESULT CALLBACK capWaveStreamCallback(

HWND hWnd,
LPWAVEHDR lpWHdr
);
Parameters

hWnd

Handle of the capture window associated with the callback function.

lpWHdr

Address of a WAVEHDR structure containing information about the captured audio data.

Remarks

The capture window calls a wavestream callback function when an audio buffer is marked done by the waveform-audio driver. When capturing to disk, this will preceed the disk write operation.

See Also

WAVEHDR


capYieldCallback

The capYieldCallback function is the yield callback function used with video capture. The capYieldCallback yield callback function is a placeholder for the application-supplied function name.

LRESULT CALLBACK capYieldCallback(

HWND hWnd
);
Parameters

hWnd

Handle of the capture window associated with the callback function.

Remarks

The capture window calls the yield callback function at least once for every captured video frame, but the exact rate depends on the frame rate and the overhead of the capture driver and disk.


CreateEditableStream

The CreateEditableStream function creates an editable stream. Use this function before using other stream editing functions.

STDAPI CreateEditableStream(

PAVISTREAM * ppsEditable,
PAVISTREAM psSource
);
Parameters

ppsEditable

Address to contain the new stream handle.

psSource

Handle of the stream supplying data for the new stream. Specify NULL to create an empty editable string that you can copy and paste data into.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The stream pointer returned in ppsEditable must be used as the source stream in the other stream editing functions.

Internally, this function creates tables to keep track of changes to a stream. The original stream is never changed by the stream editing functions. The stream pointer created by this function can be used in any AVIFile function that accepts stream pointers. You can use this function on the same stream multiple times. A copy of a stream is not affected by changes in another copy.


DllGetClassObject

The DllGetClassObject function is the entry point used by C+ + file and stream handlers to create an instance of the handler.

STDAPI DllGetClassObject(

const CLSID & rclsid,
const IID & riid,
void ** ppv)
Parameters

rclsid

Class identifier of the file or stream handler.

riid

Interface identifier of the file or stream handler.

ppv

Address returned for the object of the interface query. If the interface specified in riid is not supported by the object, S_FALSE is returned and the ppvObj parameter used in the IUnknown interface must be set to NULL.

Return Values

Returns a handle of an instance of the file or stream handler.

Remarks

DllGetClassObject is the only export function your DLL needs. The OLE component object DLL calls this function to obtain an instance of the stream- or file-handler interface.

Your file or stream handler should ensure that the system requests the correct class identifier before creating an instance of it.

See Also

IUnknown


DrawDibBegin

The DrawDib function changes parameters of a DrawDib DC or initializes a new DrawDib DC.

BOOL DrawDibBegin(

HDRAWDIB hdd,
HDC hdc,
int dxDest,
int dyDest,
LPBITMAPINFOHEADER lpbi,
int dxSrc,
int dySrc,
UINT wFlags
);
Parameters

hdd

Handle of a DrawDib DC.

hdc

Handle of a DC for drawing. This parameter is optional.

dxDest and dyDest

Width and height, in MM_TEXT client units, of the destination rectangle.

lpbi

Address of a BITMAPINFOHEADER structure containing the image format. The color table for the DIB follows the image format and the biHeight member must be a positive value.

dxSrc and dySrc

Width and height, in pixels, of the source rectangle.

wFlags

Applicable flags for the function. The following values are defined:

DDF_ANIMATE

Allows palette animation. If this value is present, DrawDib reserves as many entries as possible by setting PC_RESERVED in the palPalEntry members of the LOGPALETTE structure, and the palette can be animated by using the DrawDibChangePalette function. If your application uses the DrawDibBegin function with the DrawDibDraw function, set this value with DrawDibBegin rather than DrawDibDraw.

DDF_BACKGROUNDPAL

Realizes the palette used for drawing as a background task, leaving the current palette used for the display unchanged. (This value is mutually exclusive of DDF_SAME_HDC.)

DDF_BUFFER

Causes DrawDib to try to use an off-screen buffer so DDF_UPDATE can be used. This disables decompression and drawing directly to the screen. If DrawDib is unable to create an off-screen buffer, it will decompress or draw directly to the screen. For more information, see the DDF_UPDATE and DDF_DONTDRAW values described for DrawDibDraw.

DDF_DONTDRAW

Current image is not drawn, but is decompressed. DDF_UPDATE can be used later to draw the image. This flag supercedes the DDF_PREROLL flag.

DDF_FULLSCREEN

Not supported.

DDF_HALFTONE

Always dithers the DIB to a standard palette regardless of the palette of the DIB. If your application uses DrawDibBegin with DrawDibDraw, set this value with DrawDibBegin rather than DrawDibDraw.

DDF_JUSTDRAWIT

Draws the image by using GDI. Prohibits DrawDib functions from decompressing, stretching, or dithering the image. This strips DrawDib of capabilities that differentiate it from the StretchDIBits function.

DDF_SAME_DRAW

Use the current drawing parameters for DrawDibDraw. Use this value only if lpbi, dxDest, dyDest, dxSrc, and dySrc have not changed since using DrawDibDraw or DrawDibBegin. This flag supercedes the DDF_SAME_DIB and DDF_SAME_SIZE flags.

DDF_SAME_HDC

Use the current DC handle and the palette currently associated with the DC.

DDF_UPDATE

Last buffered bitmap needs to be redrawn. If drawing fails with this value, a buffered image is not available and a new image needs to be specified before the display can be updated.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

This function prepares to draw a DIB specified by lpbi to the DC. The image is stretched to the size specified by dxDest and dyDest. If dxDest and dyDest are set to − 1, the DIB is drawn to a 1:1 scale without stretching.

You can update the flags of a DrawDib DC by reissuing DrawDibBegin, specifying the new flags, and changing at least one of the following settings: dxDest, dyDest, lpbi, dxSrc, or dySrc.

If the parameters of DrawDibBegin have not changed, subsequent calls to the function have no effect.

See Also

BITMAPINFOHEADER, LOGPALETTE, DrawDibChangePalette, DrawDibDraw, StretchDIBits


DrawDibChangePalette

The DrawDibChangePalette function sets the palette entries used for drawing DIBs.

BOOL DrawDibChangePalette(

HDRAWDIB hdd,
int iStart,
int iLen,
LPPALETTEENTRY lppe
);
Parameters

hdd

Handle of a DrawDib DC.

iStart

Starting palette entry number.

iLen

Number of palette entries.

lppe

Address of an array of palette entries.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

This function changes the physical palette only if the current DrawDib palette is realized by calling the DrawDibRealize function.

If the color table is not changed, the next call to the DrawDibDraw function that does not specify DDF_SAME_DRAW calls the DrawDibBegin function implicitly.

See Also

DrawDibRealize, DrawDibDraw, DrawDibBegin


DrawDibClose

The DrawDibClose function closes a DrawDib DC and frees the resources DrawDib allocated for it.

BOOL DrawDibClose(

HDRAWDIB hdd
);
Parameters

hdd

Handle of a DrawDib DC.

Return Values

Returns TRUE if successful or FALSE otherwise.


DrawDibDraw

The DrawDibDraw function draws a DIB to the screen.

BOOL DrawDibDraw(

HDRAWDIB hdd,
HDC hdc,
int xDst,
int yDst,
int dxDst,
int dyDst,
LPBITMAPINFOHEADER lpbi,
LPVOID lpBits,
int xSrc,
int ySrc,
int dxSrc,
int dySrc,
UINT wFlags
);
Parameters

hdd

Handle of a DrawDib DC.

hdc

Handle of the DC.

xDst and yDst

The x- and y-coordinates, in MM_TEXT client coordinates, of the upper left corner of the destination rectangle.

dxDst and dyDst

Width and height, in MM_TEXT client coordinates, of the destination rectangle. If dxDst is − 1, the width of the bitmap is used. If dyDst is − 1, the height of the bitmap is used.

lpbi

Address of the BITMAPINFOHEADER structure containing the image format. The color table for the DIB within BITMAPINFOHEADER follows the format and the biHeight member must be a positive value; DrawDibDraw will not draw inverted DIBs.

lpBits

Address of the buffer that contains the bitmap bits.

xSrc and ySrc

The x- and y-coordinates, in pixels, of the upper left corner of the source rectangle. The coordinates (0,0) represent the upper left corner of the bitmap.

dxSrc and dySrc

Width and height, in pixels, of the source rectangle.

wFlags

Applicable flags for drawing. The following values are defined:

DDF_BACKGROUNDPAL

Realizes the palette used for drawing in the background, leaving the actual palette used for display unchanged. This value is valid only if DDF_SAME_HDC is not set.

DDF_DONTDRAW

Current image is decompressed but not drawn. This flag supercedes the DDF_PREROLL flag.

DDF_FULLSCREEN

Not supported.

DDF_HALFTONE

Always dithers the DIB to a standard palette regardless of the palette of the DIB. If your application uses the DrawDibBegin function, set this value in DrawDibBegin rather than in DrawDibDraw.

DDF_HURRYUP

Data does not have to be drawn (that is, it can be dropped) and DDF_UPDATE will not be used to recall this information. DrawDib checks this value only if it is required to build the next frame; otherwise, the value is ignored.

This value is usually used to synchronize video and audio. When synchronizing data, applications should send the image with this value in case the driver needs to buffer the frame to decompress subsequent frames.

DDF_NOTKEYFRAME

DIB data is not a key frame.

DDF_SAME_HDC

Use the current DC handle and the palette currently associated with the DC.

DDF_SAME_DRAW

Use the current drawing parameters for DrawDibDraw. Use this value only if lpbi, dxDst, dyDst, dxSrc, and dySrc have not changed since using DrawDibDraw or DrawDibBegin. DrawDibDraw typically checks the parameters, and if they have changed, DrawDibBegin prepares the DrawDib DC for drawing. This flag supercedes the DDF_SAME_DIB and DDF_SAME_SIZE flags.

DDF_UPDATE

Last buffered bitmap is to be redrawn. If drawing fails with this value, a buffered image is not available and a new image needs to be specified before the display can be updated.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

DDF_DONTDRAW causes DrawDibDraw to decompress but not display an image. A subsequent call to DrawDibDraw specifying DDF_UPDATE displays the image.

If the DrawDib DC does not have an off-screen buffer specified, specifying DDF_DONTDRAW causes the frame to be drawn to the screen immediately. Subsequent calls to DrawDibDraw specifying DDF_UPDATE fail.

Although they are set at different times, DDF_UPDATE and DDF_DONTDRAW can be used together to create composite images off-screen. When the off-screen image is complete, you can display the image by calling DrawDibDraw.

See Also

BITMAPINFOHEADER, DrawDibBegin


DrawDibEnd

The DrawDibEnd function clears the flags and other settings of a DrawDib DC that are set by the DrawDibBegin or DrawDibDraw functions.

BOOL DrawDibEnd(

HDRAWDIB hdd
);
Parameters

hdd

Handle of the DrawDib DC to free.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

DrawDibBegin, DrawDibDraw


DrawDibGetBuffer

The DrawDibGetBuffer function retrieves the location of the buffer used by DrawDib for decompression.

LPVOID DrawDibGetBuffer(

HDRAWDIB hdd,
LPBITMAPINFOHEADER lpbi,
DWORD dwSize,
DWORD dwFlags
);
Parameters

hdd

Handle of a DrawDib DC.

lpbi

Address of a BITMAPINFO structure. This structure is made up of a BITMAPINFOHEADER structure and a 256-entry table defining the colors used by the bitmap.

dwSize

Size, in bytes, of the BITMAPINFO structure pointed to by lpbi

dwFlags

Reserved; must be zero.

Return Values

Returns the address of the buffer or NULL if no buffer is used. if lpbr is not NULL, it is filled with a copy of the BITMAPINFO structure describing the buffer.

See Also

BITMAPINFO, BITMAPINFOHEADER


DrawDibGetPalette

The DrawDibGetPalette function retrieves the palette used by a DrawDib DC.

HPALETTE DrawDibGetPalette(

HDRAWDIB hdd
);
Parameters

hdd

Handle of a DrawDib DC.

Return Values

Returns a handle to the palette if successful or NULL otherwise.

Remarks

This function assumes the DrawDib DC contains a valid palette entry, implying that a call to this function must follow calls to the DrawDibDraw or DrawDibBegin functions.

You should rarely need to call this function because you can realize the correct palette in response to a window message by using the DrawDibRealize function.

See Also

DrawDibDraw, DrawDibBegin, DrawDibRealize


DrawDibOpen

The DrawDibOpen function opens the DrawDib library for use and creates a DrawDib DC for drawing.

HDRAWDIB DrawDibOpen(VOID);

Parameters

This function takes no parameters.

Return Values

Returns a handle to a DrawDib DC if successful or NULL otherwise.

Remarks

When drawing multiple DIBs simultaneously, create a DrawDib DC for each of the images that will be simultaneously on-screen.


DrawDibProfileDisplay

The DrawDibProfileDisplay function determines settings for the display system when using DrawDib functions.

BOOL DrawDibProfileDisplay(

LPBITMAPINFOHEADER lpbi
);
Parameters

lpbi

Address of a BITMAPINFOHEADER structure that contains bitmap information. You can also specify NULL to verify that the profile information is current. If the profile information is not current, DrawDib will rerun the profile tests to obtain a current set of information. When you call DrawDibProfileDisplay with this parameter set to NULL, the return value is meaningless.

Return Values

Returns a value that indicates the fastest drawing and stretching capabilities of the display system. This value can be zero if the bitmap format is not supported or one or more of the following values:

PD_CAN_DRAW_DIB	DrawDib can draw images using this format. Stretching might or might not also be supported.
PD_CAN_STRETCHDIB	DrawDib can stretch and draw images using this format.
PD_STRETCHDIB_1_1_OK	StretchDIBits draws unstretched images using this format faster than an alternative method.
PD_STRETCHDIB_1_2_OK	StretchDIBits draws stretched images (in a 1:2 ratio) using this format faster than an alternative method.
PD_STRETCHDIB_1_N_OK	StretchDIBits draws stretched images (in a 1:N ratio) using this format faster than an alternative method.
See Also

BITMAPINFOHEADER, StretchDIBits


DrawDibRealize

The DrawDibRealize function realizes the palette of the DrawDib DC for use with the specified DC.

UINT DrawDibRealize(

HDRAWDIB hdd,
HDC hdc,
BOOL fBackground
);
Parameters

hdd

Handle of a DrawDib DC.

hdc

Handle of the DC containing the palette.

fBackground

Background palette flag. If this value is nonzero, the palette is a background palette. If this value is zero and the DC is attached to a window, the logical palette becomes the foreground palette when the window has the input focus. (A DC is attached to a window when the window class style is CS_OWNDC or when the DC is obtained by using the GetDC function.)

Return Values

Returns the number of entries in the logical palette mapped to different values in the system palette. If an error occurs or no colors were updated, it returns zero.

Remarks

To select the palette of the DrawDib DC as a background palette, use the DrawDibDraw function and specify the DDF_BACKGROUNDPAL flag.

See Also

GetDC, DrawDibDraw


DrawDibSetPalette

The DrawDibSetPalette function sets the palette used for drawing DIBs.

BOOL DrawDibSetPalette(

HDRAWDIB hdd,
HPALETTE hpal
);
Parameters

hdd

Handle of a DrawDib DC.

hpal

Handle of the palette. Specify NULL to use the default palette.

Return Values

Returns TRUE if successful or FALSE otherwise.


DrawDibStart

The DrawDibStart function prepares a DrawDib DC for streaming playback.

BOOL DrawDibStart(

HDRAWDIB hdd,
LONG rate
);
Parameters

hdd

Handle of a DrawDib DC.

rate

Playback rate, in microseconds per frame.

Return Values

Returns TRUE if successful or FALSE otherwise.


DrawDibStop

The DrawDibStop function frees the resources used by a DrawDib DC for streaming playback.

BOOL DrawDibStop(

HDRAWDIB hdd
);
Parameters

hdd

Handle of a DrawDib DC.

Return Values

Returns TRUE if successful or FALSE otherwise.


DrawDibTime

The DrawDibTime function retrieves timing information about the drawing operation and is used during debug operations.

BOOL DrawDibTime(

HDRAWDIB hdd,
LPDRAWDIBTIME lpddtime
);
Parameters

hdd

Handle of a DrawDib DC.

lpddtime

Address of a DRAWDIBTIME structure.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

This function is present only in the debug version of the Win32 Software Development Kit libraries.

See Also

DRAWDIBTIME


EditStreamClone

The EditStreamClone function creates a duplicate editable stream.

STDAPI EditStreamClone(

PAVISTREAM pavi,
PAVISTREAM * ppResult
);
Parameters

pavi

Handle of an editable stream that will be copied.

ppResult

Address to contain the new stream handle.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The editable stream that is being cloned must have been created by the CreateEditableStream function or one of the stream editing functions.

The new stream can be treated as any other AVI stream.

See Also

CreateEditableStream


EditStreamCopy

The EditStreamCopy function copies an editable stream (or a portion of it) into a temporary stream.

STDAPI EditStreamCopy(

PAVISTREAM pavi,
LONG * plStart,
LONG * plLength,
PAVISTREAM * ppResult
);
Parameters

pavi

Handle of the stream being copied.

plStart

Starting position within the stream being copied. The starting position is returned.

plLength

Amount of data to copy from the stream referenced by pavi. The length of the copied data is returned.

ppResult

Address to contain the handle created for the new stream.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The stream that is copied must be created by the CreateEditableStream function or one of the stream editing functions.

The temporary stream can be treated as any other AVI stream.

See Also

CreateEditableStream


EditStreamCut

The EditStreamCut function deletes all or part of an editable stream and creates a temporary editable stream from the deleted portion of the stream.

STDAPI EditStreamCut(

PAVISTREAM pavi,
LONG * plStart,
LONG * plLength,
PAVISTREAM * ppResult
);
Parameters

pavi

Handle of the stream being edited.

plStart

Starting position of the data to cut from the stream referenced by pavi.

plLength

Amount of data to cut from the stream referenced by pavi.

ppResult

Address of the handle created for the new stream.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The stream being edited must have been created by the CreateEditableStream function or one of the stream editing functions.

The temporary stream is an editable stream and can be treated as any other AVI stream. An application must release the temporary stream to free the resources associated with it.

See Also

CreateEditableStream


EditStreamPaste

The EditStreamPaste function copies a stream (or a portion of it) from one stream and pastes it within another stream at a specified location.

STDAPI EditStreamPaste(

PAVISTREAM pavi,
LONG * plPos,
LONG * plLength,
PAVISTREAM pstream,
LONG lStart,
LONG lLength
);
Parameters

pavi

Handle of an editable stream that will receive the copied stream data.

plPos

Starting position to paste the data within the destination stream (referenced by pavi).

plLength

Address to contain the amount of data pasted in the stream.

pstream

Handle of a stream supplying the data to paste. This stream does not need to be an editable stream.

lStart

Starting position of the data to copy within the source stream.

lLength

Amount of data to copy from the source stream. If lLength is -1, the entire stream referenced by pstream is pasted in the other stream.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The stream referenced by pavi must have been created by the CreateEditableStream function or one of the stream editing functions.

This function inserts data into the specified stream as a continuous block of data. It opens the specified data stream at the insertion point, pastes the specified stream segment at the insertion point, and appends the stream segment that trails the insertion point to the end of pasted segment.

See Also

CreateEditableStream


EditStreamSetInfo

The EditStreamSetInfo function changes characteristics of an editable stream.

SDTAPI EditStreamSetInfo(

PAVISTREAM pavi,
AVISTREAMINFO * lpInfo,
LONG cbInfo
);
Parameters

pavi

Handle of an open stream.

lpInfo

Address of an AVISTREAMINFO structure containing new information.

cbInfo

Size, in bytes, of the structure pointed to by lpInfo.

Return Values

Returns zero if successful or an error otherwise.

Remarks

You must supply information for the entire AVISTREAMINFO structure, including the members you will not use. You can use the AVIStreamInfo function to initialize the structure and then update selected members with your data.

This function does not change the following members:

dwCaps
dwEditCount
dwFlags
dwInitialFrames
dwLength
dwSampleSize
dwSuggestedBufferSize
fccHandler
fccType

The function changes the following members:

dwRate
dwQuality
dwScale
dwStart
rcFrame
szName
wLanguage
wPriority

Seee Also

AVISTREAMINFO, AVIStreamInfo


EditStreamSetName

The EditStreamSetName function assigns a descriptive string to a stream.

SDTAPI EditStreamSetName(

PAVISTREAM pavi,
LPCSTR lpszName
);
Parameters

pavi

Handle of an open stream.

lpszName

Null-terminated string containing the description of the stream.

Return Values

Returns zero if successful or an error otherwise.

Remarks

This function updates the szName member of the AVISTREAMINFO structure.

See Also

AVISTREAMINFO


GetOpenFileNamePreview

The GetOpenFileNamePreview function selects a file by using the Open dialog box. The dialog box also allows the user to preview the currently specified AVI file. This function augments the capability found in the GetOpenFileName function.

BOOL GetOpenFileNamePreview(

LPOPENFILENAME lpofn
);
Parameters

lpofn

Address of an OPENFILENAME structure used to initialize the dialog box. On return, the structure contains information about the user’s file selection.

Return Values

Returns a handle to the selected file.

See Also

GetOpenFileName, OPENFILENAME


GetSaveFileNamePreview

The GetSaveFileNamePreviewfunction selects a file by using the SaveAs dialog box. The dialog box also allows the user to preview the currently specified file. This function augments the capability found in the GetSaveFileName function.

BOOL GetSaveFileNamePreview(

LPOPENFILENAME lpofn
);
Parameters

lpofn

Address of an OPENFILENAME structure used to initialize the dialog box. On return, the structure contains information about the user’s file selection.

Return Values

Returns a handle to the selected file.

See Also

GetSaveFileName, OPENFILENAME


ICClose

The ICClose function closes a compressor or decompressor.

LRESULT ICClose(

HIC hic
);
Parameters

hic

Handle of a compressor or decompressor.

Return Values

Returns ICERR_OK if successful or an error otherwise.


ICCompress

The ICCompress function compresses a single video image.

DWORD ICCompress(

HIC hic,
DWORD dwFlags,
LPBITMAPINFOHEADER lpbiOutput,
LPVOID lpData,
LPBITMAPINFOHEADER lpbiInput,
LPVOID lpBits,
LPDWORD lpckid,
LPDWORD lpdwFlags,
LONG lFrameNum,
DWORD dwFrameSize,
DWORD dwQuality,
LPBITMAPINFOHEADER lpbiPrev,
LPVOID lpPrev
);
Parameters

hic

Handle of the compressor to use.

dwFlags

Compression flag. The following value is defined:

ICCOMPRESS_KEYFRAME

Compressor should make this frame a key frame.

lpbiOutput

Address of a BITMAPINFO structure containing the output format.

lpData

Address of an output buffer large enough to contain a compressed frame.

lpbiInput

Address of a BITMAPINFO structure containing the input format.

lpBits

Address of the input buffer.

lpckid

Reserved; do not use.

lpdwFlags

Address of the return flags used in the AVI index. The following value is defined:

AVIIF_KEYFRAME

Current frame is a key frame.

lFrameNum

Frame number.

dwFrameSize

Requested frame size, in bytes. Specify a nonzero value if the compressor supports a suggested frame size, as indicated by the presence of the VIDCF_CRUNCH flag returned by the ICGetInfo function. If this flag is not set or a data rate for the frame is not specified, specify zero for this parameter.

A compressor might have to sacrifice image quality or make some other trade-off to obtain the size goal specified in this parameter.

dwQuality

Requested quality value for the frame. Specify a nonzero value if the compressor supports a suggested quality value, as indicated by the presence of the VIDCF_QUALITY flag returned by ICGetInfo. Otherwise, specify zero for this parameter.

lpbiPrev

Address of a BITMAPINFO structure containing the format of the previous frame.

lpPrev

Address of the uncompressed image of the previous frame. This parameter is not used for fast temporal compression. Specify NULL for this parameter when compressing a key frame, if the compressor does not support temporal compression, or if the compressor does not require an external buffer to store the format and data of the previous image.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

You can obtain the required by size of the output buffer by sending the ICM_COMPRESS_GET_SIZE message (or by using the ICCompressGetSize macro).

The compressor sets the contents of lpdwFlags to AVIIF_KEYFRAME when it creates a key frame. If your application creates AVI files, it should save the information returned for lpckid and lpdwFlags in the file.

Compressors use lpbiPrev and lpPrev to perform temporal compression and require an external buffer to store the format and data of the previous frame. Specify NULL for lpbiPrev and lpPrev when compressing a key frame, when performing fast compression, or if the compressor has its own buffer to store the format and data of the previous image. Specify non-NULL values for these parameters if ICGetInfo returns the VIDCF_TEMPORAL flag, the compressor is performing normal compression, and the frame to compress is not a key frame.

See Also

ICGetInfo, BITMAPINFO, ICM_COMPRESS_GET_SIZE


ICCompressorChoose

The ICCompressorChoose function displays a dialog box in which a user can select a compressor. This function can display all registered compressors or list only the compressors that support a specific format.

BOOL ICCompressorChoose(

HWND hwnd,
UINT uiFlags,
LPVOID pvIn,
LPVOID lpData,
PCOMPVARS pc,
LPSTR lpszTitle
);
Parameters

hwnd

Handle of a parent window for the dialog box.

uiFlags

Applicable flags. The following values are defined:

ICMF_CHOOSE_ALLCOMPRESSORS

All compressors should appear in the selection list. If this flag is not specified, only the compressors that can handle the input format appear in the selection list.

ICMF_CHOOSE_DATARATE

Displays a check box and edit box to enter the data rate for the movie.

ICMF_CHOOSE_KEYFRAME

Displays a check box and edit box to enter the frequency of key frames.

ICMF_CHOOSE_PREVIEW

Displays a button to expand the dialog box to include a preview window. The preview window shows how frames of your movie will appear when compressed with the current settings.

pvIn

Uncompressed data input format. Only compressors that support the specified data input format are included in the compressor list. This parameter is optional.

lpData

Address of an AVI stream interface to use in the preview window. You must specify a video stream. This parameter is optional.

pc

Address of a COMPVARS structure. The information returned initializes the structure for use with other functions.

lpszTitle

Address of a null-terminated string containing a title for the dialog box. This parameter is optional.

Return Values

Returns TRUE if the user chooses a compressor and presses OK. Returns FALSE on error or if the user presses CANCEL.

Remarks

Before using this function, set the cbSize member of the COMPVARS structure to the size of the structure. Initialize the rest of the structure to zeros unless you want to specify some valid defaults for the dialog box. If specifying defaults, set the dwFlags member to ICMF_COMPVARS_VALID and initialize the other members of the structure. For more information about initializing the structure, see the  ICSeqCompressFrameStart function and COMPVARS.

See Also

COMPVARS, ICSeqCompressFrameStart


ICCompressorFree

The ICCompressorFree function frees the resources in the COMPVARS structure used by other VCM functions.

void ICCompressorFree(

PCOMPVARS pc
);
Parameters

pc

Address of the COMPVARS structure containing the resources to be freed.

Return Values

This function does not return a value.

Remarks

Use this function to release the resources in the COMPVARS structure after using the ICCompressorChoose, ICSeqCompressFrameStart, ICSeqCompressFrame, and ICSeqCompressFrameEnd functions.

See Also

COMPVARS, ICCompressorChoose, ICSeqCompressFrameStart, ICSeqCompressFrame,  ICSeqCompressFrameEnd


ICDecompress

The ICDecompress function decompresses a single video frame.

DWORD ICDecompress(

HIC hic,
DWORD dwFlags,
LPBITMAPINFOHEADER lpbiFormat,
LPVOID lpData,
LPBITMAPINFOHEADER lpbi,
LPVOID lpBits
);
Parameters

hic

Handle of the decompressor to use.

dwFlags

Applicable decompression flags. The following values are defined:

ICDECOMPRESS_HURRYUP

Tries to decompress at a faster rate. When an application uses this flag, the driver should buffer the decompressed data but not draw the image.

ICDECOMPRESS_NOTKEYFRAME

Current frame is not a key frame.

ICDECOMPRESS_NULLFRAME

Current frame does not contain data and the decompressed image should be left the same.

ICDECOMPRESS_PREROLL

Current frame precedes the point in the movie where playback starts and, therefore, will not be drawn.

ICDECOMPRESS_UPDATE

Screen is being updated or refreshed.

lpbiFormat

Address of a BITMAPINFO structure containing the format of the compressed data.

lpData

Address of the input data.

lpbi

Address of a BITMAPINFO structure containing the output format.

lpBits

Address of a buffer that is large enough to contain the decompressed data.

Return Values

Returns ICERR_OK if successful or an error otherwise.

See Also

BITMAPINFO


ICDecompressEx

The ICDecompressEx function decompresses a single video frame.

DWORD ICDecompressEx(

HIC hic,
DWORD dwFlags,
LPBITMAPINFOHEADER lpbiSrc,
LPVOID lpSrc,
int xSrc,
int ySrc,
int dxSrc,
int dySrc,
LPBITMAPINFOHEADER lpbiDst,
LPVOID lpDst,
int xDst,
int yDst,
int dxDst,
int dyDst
);
Parameters

hic

Handle of the decompressor.

dwFlags

Decompression flags. The following values are defined:

ICDECOMPRESS_HURRYUP

Tries to decompress at a faster rate. When an application uses this flag, the driver should buffer the decompressed data but not draw the image.

ICDECOMPRESS_NOTKEYFRAME

Current frame is not a key frame.

ICDECOMPRESS_NULLFRAME

Current frame does not contain data and the decompressed image should be left the same.

ICDECOMPRESS_PREROLL

Current frame precedes the point in the movie where playback starts and, therefore, will not be drawn.

ICDECOMPRESS_UPDATE

Screen is being updated or refreshed.

lpbiSrc

Address of a BITMAPINFOHEADER structure containing the format of the compressed data.

lpSrc

Address of the input data.

xSrc, ySrc

The x- and y- coordinates of the source rectangle for the DIB specified by lpbiSrc.

dxSrc, dySrc

Width and height of the source rectangle.

lpbiDst

Address of a BITMAPINFOHEADER structure containing the output format.

lpDst

Address of a buffer that is large enough to contain the decompressed data.

xDst, yDst

The x- and y-coordinates of the destination rectangle for the DIB specified by lpbiDst.

dxDst, dyDst

Width and height of the destination rectangle.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

Typically, applications use the ICDECOMPRESS_PREROLL flag to seek to a key frame in a compressed stream. The flag is sent with the key frame and with subsequent frames required to decompress the desired frame.

See Also

BITMAPINFOHEADER


ICDecompressExBegin

The ICDecompressExBegin function prepares a decompressor for decompressing data.

DWORD ICDecompressExBegin(

HIC hic,
DWORD dwFlags,
LPBITMAPINFOHEADER lpbiSrc,
LPVOID lpSrc,
int xSrc,
int ySrc,
int dxSrc,
int dySrc,
LPBITMAPINFOHEADER lpbiDst,
LPVOID lpDst,
int xDst,
int yDst,
int dxDst,
int dyDst
);
Parameters

hic

Handle of the decompressor to use.

dwFlags

Decompression flags. The following values are defined:

ICDECOMPRESS_HURRYUP

Tries to decompress at a faster rate. When an application uses this flag, the driver should buffer the decompressed data but not draw the image.

ICDECOMPRESS_NOTKEYFRAME

Current frame is not a key frame.

ICDECOMPRESS_NULLFRAME

Current frame does not contain data and the decompressed image should be left the same.

ICDECOMPRESS_PREROLL

Current frame precedes the point in the movie where playback starts and, therefore, will not be drawn.

ICDECOMPRESS_UPDATE

Screen is being updated or refreshed.

lpbiSrc

Address of a BITMAPINFOHEADER structure containing the format of the compressed data.

lpSrc

Address of the input data.

xSrc, ySrc

The x- and y-coordinates of the source rectangle for the DIB specified by lpbiSrc.

dxSrc, dySrc

Width and height of the source rectangle.

lpbiDst

Address of a BITMAPINFOHEADER structure containing the output format.

lpDst

Address of a buffer that is large enough to contain the decompressed data.

xDst, yDst

The x- and y-coordinates of the destination rectangle for the DIB specified by lpbiDst.

dxDst, dyDst

Width and height of the destination rectangle.

Return Values

Returns ICERR_OK if successful or an error otherwise.

See Also

BITMAPINFOHEADER


ICDecompressExQuery

The ICDecompressExQuery function determines if a decompressor can decompress data with a specific format.

DWORD ICDecompressExQuery(

HIC hic,
DWORD dwFlags,
LPBITMAPINFOHEADER lpbiSrc,
LPVOID lpSrc,
int xSrc,
int ySrc,
int dxSrc,
int dySrc,
LPBITMAPINFOHEADER lpbiDst,
LPVOID lpDst,
int xDst,
int yDst,
int dxDst,
int dyDst
);
Parameters

hic

Handle of the decompressor to use.

dwFlags

Reserved; do not use.

lpbiSrc

Address of a BITMAPINFOHEADER structure containing the format of the compressed data to decompress.

lpSrc

Reserved; must be NULL.

xSrc, ySrc

The x- and y-coordinates of the source rectangle for the DIB specified by lpbiSrc.

dxSrc, dySrc

Width and height of the source rectangle.

lpbiDst

Address of a BITMAPINFOHEADER structure containing the output format. If the value of this parameter is NULL, the function determines whether the input format is supported and this parameter is ignored.

lpDst

Address of a buffer that is large enough to contain the decompressed data.

xDst, yDst

The x- and y-coordinates of the destination rectangle for the DIB specified by lpbiDst.

dxDst, dyDst

Width and height of the destination rectangle.

Return Values

Returns ICERR_OK if successful or an error otherwise.

See Also

BITMAPINFOHEADER


ICDraw

The ICDraw function decompresses an image for drawing.

DWORD ICDraw(

HIC hic,
DWORD dwFlags,
LPVOID lpFormat,
LPVOID lpData,
DWORD cbData,
LONG lTime
);
Parameters

hic

Handle of an decompressor.

dwFlags

Decompression flags. The following values are defined:

ICDRAW_HURRYUP

Data is buffered and not drawn to the screen. Use this flag for fastest decompression.

ICDRAW_NOTKEYFRAME

Current frame is not a key frame.

ICDRAW_NULLFRAME

Current frame does not contain any data and the previous frame should be redrawn.

ICDRAW_PREROLL

Current frame of video occurs before playback should start. For example, if playback will begin on frame 10, and frame 0 is the nearest previous key frame, frames 0 through 9 are sent to the driver with the ICDRAW_PREROLL flag set. The driver needs this data to display frame 10 properly.

ICDRAW_UPDATE

Updates the screen based on previously received data. Set lpData to NULL when this flag is used.

lpFormat

Address of a BITMAPINFOHEADER structure containing the input format of the data.

lpData

Address of the input data.

cbData

Size of the input data, in bytes.

lTime

Time, in samples, to draw this frame. The units for video data are frames. For a definition of the playback rate, see the dwRate and dwScale members of the ICDRAWBEGIN structure.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

You can initiate drawing the frames by sending the ICM_DRAW_START message (or by using the ICDrawStart macro). The application should be sure to buffer the required number of frames before drawing is started. Send the KM_GETBUFFERSWANTED message (or use the ICGetBuffersWanted macro) to obtain this value.

See Also

BITMAPINFOHEADER, ICDRAWBEGIN, ICM_DRAW_START


ICDrawBegin

The ICDrawBegin function initializes the renderer and prepares the drawing destination for drawing.

DWORD ICDrawBegin(

HIC hic,
DWORD dwFlags,
HPALETTE hpal,
HWND hwnd,
HDC hdc,
int xDst,
int yDst,
int dxDst,
int dyDst,
LPBITMAPINFOHEADER lpbi,
int xSrc,
int ySrc,
int dxSrc,
int dySrc,
DWORD dwRate,
DWORD dwScale
);
Parameters

hic

Handle of the decompressor to use.

dwFlags

Decompression flags. The following values are defined:

ICDRAW_ANIMATE

Application can animate the palette.

ICDRAW_CONTINUE

Drawing is a continuation of the previous frame.

ICDRAW_FULLSCREEN

Draws the decompressed data on the full screen.

ICDRAW_HDC

Draws the decompressed data to a window or a DC.

ICDRAW_MEMORYDC

DC is off-screen.

ICDRAW_QUERY

Determines if the decompressor can decompress the data. The driver does not decompress the data.

ICDRAW_UPDATING

Current frame is being updated rather than played.

hpal

Handle of the palette used for drawing.

hwnd

Handle of the window used for drawing.

hdc

DC used for drawing.

xDst, yDst

The x- and y-coordinates of the upper right corner of the destination rectangle.

dxDst, dyDst

Width and height of the destination rectangle.

lpbi

Address of a BITMAPINFO structure containing the format of the input data to be decompressed.

xSrc, ySrc

The x- and y-coordinates of the upper right corner of the source rectangle.

dxSrc, dySrc

Width and height of the source rectangle.

dwRate

Frame rate numerator. The frame rate, in frames per second, is obtained by dividing dwRate by dwScale.

dwScale

Frame rate denominator. The frame rate, in frames per second, is obtained by dividing dwRate by dwScale.

Return Values

Returns ICERR_OK if the renderer can decompress the data or ICERR_UNSUPPORTED otherwise.

Remarks

The ICDRAW_HDC and ICDRAW_FULLSCREEN flags are mutually exclusive. If an application sets the ICDRAW_HDC flag in dwFlags, the decompressor uses hwnd, hdc, and the parameters defining the destination rectangle (xDst, yDst, dxDst, and dyDst). Your application should set these parameters to the size of the destination rectangle. Specify destination rectangle values relative to the current window or DC.

If an application sets the ICDRAW_FULLSCREEN flag in dwFlags, the hwnd and hdc parameters are not used and should be set to NULL. Also, the destination rectangle is not used and its parameters can be set to zero.

The source rectangle is relative to the full video frame. The portion of the video frame specified by the source rectangle is stretched or shrunk to fit the destination rectangle.

The dwRate and dwScale parameters specify the decompression rate. The integer value specified for dwRate divided by the integer value specified for dwScale defines the frame rate in frames per second. This value is used by the renderer when it is responsible for timing frames during playback.

See Also

BITMAPINFO


ICDrawSuggestFormat

The ICDrawSuggestFormat function notifies the drawing handler to suggest the input data format.

DWORD ICDrawSuggestFormat(

HIC hic,
LPBITMAPINFOHEADER lpbiIn,
LPBITMAPINFOHEADER lpbiOut,
int dxSrc,
int dySrc,
int dxDst,
int dyDst,
HIC hicDecompressor
);
Parameters

hic

Handle of the driver to use.

lpbiIn

Address of a structure containing the format of the compressed data. For bitmaps, this is a BITMAPINFOHEADER structure.

lpbiOut

Address of a structure to return the suggested format. The drawing handler can receive and draw data from this format. For bitmaps, this is a BITMAPINFOHEADER structure.

dxSrc, dySrc

Width and height of the source rectangle.

dxDst, dyDst

Width and height of the destination rectangle.

hicDecompressor

Decompressor that can use the format of data in lpbiIn.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

Applications can use this function to determine alternative input formats that a drawing handler can decompress and if the drawing handler can stretch data. If the drawing handler cannot stretch data as requested, the application might have to stretch the data.

If the drawing handler cannot decompress a format provided by an application, use the ICDecompress, ICDecompressEx, ICDecompressExBegin, ICDecompressExQuery, and ICDecompressOpen functions to obtain alternate formats.

See Also

BITMAPINFOHEADER, ICDecompress, ICDecompressEx, ICDecompressExBegin, ICDecompressExQuery, ICDecompressOpen


ICGetDisplayFormat

The ICGetDisplayFormat function determines the best format available for displaying a compressed image. The function also opens a compressor if a handle of an open compressor is not specified.

HIC ICGetDisplayFormat(

HIC hic,
LPBITMAPINFOHEADER lpbiIn,
LPBITMAPINFOHEADER lpbiOut,
int BitDepth,
int dx,
int dy
);
Parameters

hic

Handle of the compressor to use. Specify NULL to have VCM select and open an appropriate compressor.

lpbiIn

Address of BITMAPINFOHEADER structure containing the compressed format.

lpbiOut

Address of a buffer to return the decompressed format. The buffer should be large enough for a BITMAPINFOHEADER structure and 256 color entries.

BitDepth

Preferred bit depth, if nonzero.

dx, dy

Width and height multipliers to stretch the image. If this parameter is zero, that dimension is not stretched.

Return Values

Returns a handle to a decompressor if successful or zero otherwise.

See Also

BITMAPINFOHEADER


ICGetInfo

The ICGetInfo function obtains information about a compressor.

LRESULT ICGetInfo(

HIC hic,
ICINFO * lpicinfo,
DWORD cb
);
Parameters

hic

Handle of a compressor.

lpicinfo

Address of the ICINFO structure to return information about the compressor.

cb

Size, in bytes, of the structure pointed to by lpicinfo.

Return Values

Returns the number of bytes copied into the structure or zero if an error occurs.

See Also

ICINFO


ICImageCompress

The ICImageCompress function compresses an image to a given size. This function does not require initialization functions.

HANDLE ICImageCompress(

HIC hic,
UINT uiFlags,
LPBITMAPINFO lpbiIn,
LPVOID lpBits,
LPBITMAPINFO lpbiOut,
LONG lQuality,
LONG * plSize
);
Parameters

hic

Handle of a compressor opened with the ICOpen function. Specify NULL to have VCM select an appropriate compressor for the compression format. An application can have the user select the compressor by using the ICCompressorChoose function, which opens the selected compressor and returns a handle of the compressor in this parameter.

uiFlags

Reserved; must be zero.

lpbiIn

Address of the BITMAPINFO structure containing the input data format.

lpBits

Address of input data bits to compress. The data bits exclude header and format information.

lpbiOut

Address of the BITMAPINFO structure containing the compressed output format. Specify NULL to have the compressor use an appropriate format.

lQuality

Quality value used by the compressor. Values range from 0 to 10,000.

plSize

Maximum size desired for the compressed image. The compressor might not be able to compress the data to fit within this size. When the function returns, this parameter points to the size of the compressed image. Image sizes are specified in bytes.

Return Values

Returns a handle to a compressed DIB. The image data follows the format header.

Remarks

To obtain the format information from the LPBITMAPINFOHEADER structure, use the GlobalLock function to lock the data. Use the GlobalFree function to free the DIB when you are finished.

See Also

ICOpen, ICCompressorChoose, BITMAPINFO, GlobalLock, GlobalFree


ICImageDecompress

The ICImageDecompress function decompresses an image without using initialization functions.

HANDLE ICImageDecompress(

HIC hic,
UINT uiFlags,
LPBITMAPINFO lpbiIn,
LPVOID lpBits,
LPBITMAPINFO lpbiOut
);
Parameters

hic

Handle of a decompressor opened with the ICOpen function. Specify NULL to have VCM select an appropriate decompressor for the compressed image.

uiFlags

Reserved; must be zero.

lpbiIn

Compressed input data format.

lpBits

Address of input data bits to compress. The data bits exclude header and format information.

lpbiOut

Decompressed output format. Specify NULL to let decompressor use an appropriate format.

Return Values

Returns a handle to an uncompressed DIB in the CF_DIB format if successful or NULL otherwise. Image data follows the format header.

Remarks

To obtain the format information from the LPBITMAPINFOHEADER structure, use the GlobalLock function to lock the data. Use the GlobalFree function to free the DIB when you are finished.

See Also

ICOpen, GlobalLock, GlobalFree


ICInfo

The ICInfo function retrieves information about specific installed compressors or enumerates the installed compressors.

BOOL ICInfo(

DWORD fccType,
DWORD fccHandler,
ICINFO * lpicinfo
);
Parameters

fccType

Four-character code indicating the type of compressor. Specify zero to match all compressor types.

fccHandler

Four-character code identifying a specific compressor or a number between zero and the number of installed compressors of the type specified by fccType.

lpicinfo

Address of a ICINFO structure to return information about the compressor.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

To enumerate the compressors or decompressors, specify an integer for fccHandler. This function returns information for integers between zero and the number of installed compressors or decompressors of the type specified for fccType.

See Also

ICINFO


ICInstall

The ICInstall function installs a new compressor or decompressor.

BOOL ICInstall(

DWORD fccType,
DWORD fccHandler,
LPARAM lParam,
LPSTR szDesc,
UINT wFlags
);
Parameters

fccType

Four-character code indicating the type of data used by the compressor or decompressor. Specify “VIDC” for a video compressor or decompressor.

fccHandler

Four-character code identifying a specific compressor or decompressor.

lParam

Address of a null-terminated string containing the name of the compressor or decompressor, or the address of a function used for compression or decompression. The contents of this parameter are defined by the flags set for wFlags.

szDesc

Reserved; do not use.

wFlags

Flags defining the contents of lParam. The following values are defined:

ICINSTALL_DRIVER

The lParam parameter contains the address of a
null-terminated string that names the compressor to install.

ICINSTALL_FUNCTION

The lParam parameter contains the address of a compressor function. This function should be structured like the DriverProc entry point function used by compressors.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

Applications must open an installed compressor or decompressor before using it.

If your application installs a function as a compressor or decompressor, it should remove the function with the ICRemove function before it terminates. This prevents other applications from trying to access the function when it is not available.

See Also

DriverProc, ICRemove


ICLocate

The ICLocate function finds a compressor or decompressor that can handle images with the specified formats, or finds a driver that can decompress an image with a specified format directly to hardware.

HIC ICLocate(

DWORD fccType,
DWORD fccHandler,
LPBITMAPINFOHEADER lpbiIn,
LPBITMAPINFOHEADER lpbiOut,
WORD wFlags
);
Parameters

fccType

Four-character code indicating the type of compressor or decompressor to open. For video streams, the value of this parameter is “VIDC”.

fccHandler

Preferred handler of the specified type. Typically, the handler type is stored in the stream header in an AVI file. Specify NULL if your application can use any handler type or it does not know the handler type to use.

lpbiIn

Address of a BITMAPINFOHEADER structure defining the input format. A compressor handle is not returned unless it supports this format.

lpbiOut

Address of a BITMAPINFOHEADER structure defining an optional decompressed format. You can also specify zero to use the default output format associated with the input format.

If this parameter is nonzero, a compressor handle is not returned unless it can create this output format.

wFlags

Flags that describe the search criteria for a compressor or decompressor. The following values are defined:

ICMODE_COMPRESS

Finds a compressor that can compress an image with a format defined by lpbiIn to the format defined by lpbiOut.

ICMODE_DECOMPRESS

Finds a decompressor that can decompress an image with a format defined by lpbiIn to the format defined by lpbiOut.

ICMODE_DRAW

Finds a decompressor that can decompress an image with a format defined by lpbiIn and draw it directly to hardware.

ICMODE_FASTCOMPRESS

Has the same meaning as ICMODE_COMPRESS except the compressor is used for a real-time operation and emphasizes speed over quality.

ICMODE_FASTDECOMPRESS

Has the same meaning as ICMODE_DECOMPRESS except the decompressor is used for a real-time operation and emphasizes speed over quality.

Return Values

Returns a handle to a compressor or decompressor if successful or zero otherwise.

See Also

BITMAPINFOHEADER


ICOpen

The ICOpen function opens a compressor or decompressor.

HIC ICOpen(

DWORD fccType,
DWORD fccHandler,
UINT wMode
);
Parameters

fccType

Four-character code indicating the type of compressor or decompressor to open. For video streams, the value of this parameter is “VIDC”.

fccHandler

Preferred handler of the specified type. Typically, the handler type is stored in the stream header in an AVI file.

wMode

Flag defining the use of the compressor or decompressor. The following values are defined:

ICMODE_COMPRESS

Compressor will perform normal compression.

ICMODE_DECOMPRESS

Decompressor will perform normal decompression.

ICMODE_DRAW

Decompressor will decompress and draw the data directly to hardware.

ICMODE_FASTCOMPRESS

Compressor will perform fast (real-time) compression.

ICMODE_FASTDECOMPRESS

Decompressor will perform fast (real-time) decompression.

ICMODE_QUERY

Queries the compressor or decompressor for information.

Return Values

Returns a handle to a compressor or decompressor if successful or zero otherwise.


ICOpenFunction

The ICOpenFunction function opens a compressor or decompressor defined as a function.

HIC ICOpenFunction(

DWORD fccType,
DWORD fccHandler,
UINT wMode,
FARPROC lpfnHandler
);
Parameters

fccType

Type of compressor to open. For video, the value of this parameter is ICTYPE_VIDEO.

fccHandler

Preferred handler of the specified type. Typically, this comes from the stream header in an AVI file.

wMode

Flag to define the use of the compressor or decompressor. The following values are defined:

ICMODE_COMPRESS

Compressor will perform normal compression.

ICMODE_DECOMPRESS

Decompressor will perform normal decompression.

ICMODE_DRAW

Decompressor will decompress and draw the data directly to hardware.

ICMODE_FASTCOMPRESS

Compressor will perform fast (real-time) compression.

ICMODE_FASTDECOMPRESS

Decompressor will perform fast (real-time) decompression.

ICMODE_QUERY

Queries the compressor or decompressor for information.

lpfnHandler

Address of the function used as the compressor or decompressor.

Return Values

Returns a handle to a compressor or decompressor if successful or zero otherwise.


ICRemove

The ICRemove function removes an installed compressor.

BOOL ICRemove(

DWORD fccType,
DWORD fccHandler,
UINT wFlags
);
Parameters

fccType

Four-character code indicating the type of data used by the compressor or decompressor. Specify “VIDC” for a video compressor or decompressor.

fccHandler

Four-character code identifying a specific compressor or a number between zero and the number of installed compressors of the type specified by fccType.

wFlags

Reserved; do not use.

Return Values

Returns TRUE if successful or FALSE otherwise.


ICSendMessage

The ICSendMessage function sends a message to a compressor.

LRESULT ICSendMessage(

HIC hic,
UINT wMsg,
DWORD dw1,
DWORD dw2
);
Parameters

hic

Handle of the compressor to receive the message.

wMsg

Message to send.

dw1

Additional message-specific information.

dw2

Additional message-specific information.

Return Values

Returns a message-specific result.


ICSeqCompressFrame

The ICSeqCompressFrame function compresses one frame in a sequence of frames.

LPVOID ICSeqCompressFrame(

PCOMPVARS pc,
UINT uiFlags,
LPVOID lpBits,
BOOL * pfKey,
LONG * plSize
);
Parameters

pc

Address of a COMPVARS structure initialized with information about the compression.

uiFlags

Reserved; must be zero.

lpBits

Address of the data bits to compress. (The data bits exclude header or format information.)

pfKey

Returns whether or not the frame was compressed into a key frame.

plSize

Maximum size desired for the compressed image. The compressor might not be able to compress the data to fit within this size. When the function returns, the parameter points to the size of the compressed image. Images sizes are specified in bytes.

Return Values

Returns the address of the compressed bits if successful or NULL otherwise.

Remarks

This function uses a COMPVARS structure to provide settings for the specified compressor and intersperses key frames at the rate specified by the ICSeqCompressorFrameStart function. You can specify values for the data rate for the sequence and the key-frame frequency by using the appropriate members of COMPVARS.

Use this function instead of the ICCompress function to compress a video sequence.

You can allow the user to specify a compressor and initialize a COMPVARS structure by using the ICCompressorChoose function. Or, you can initialize a COMPVARS structure manually.

Use the ICSeqCompressFrameStart, ICSeqCompressFrame, and ICSeqCompressFrameEnd functions to compress a sequence of frames to a specified data rate and number of key frames. Use ICSeqCompressFrame once for each frame to be compressed.

When finished with compression, use the ICCompressorFree function to release the resources specified by COMPVARS.

See Also

COMPVARS, ICCompress, ICCompressorChoose, ICSeqCompressFrameStart, ICSeqCompressFrameEnd, ICCompressorFree


ICSeqCompressFrameEnd

The ICSeqCompressFrameEnd function ends sequence compression that was initiated by using the ICSeqCompressFrameStart and ICSeqCompressFrame functions.

void ICSeqCompressFrameEnd(

PCOMPVARS pc
);
Parameters

pc

Address of a COMPVARS structure used during sequence compression.

Return Values

This function does not return a value.

Remarks

When finished with compression, use the ICCompressorFree function to release the resources specified by COMPVARS.

See Also

ICSeqCompressFrameStart, ICSeqCompressFrame, COMPVARS, ICCompressorFree


ICSeqCompressFrameStart

The ICSeqCompressFrameStart function initializes resources for compressing a sequence of frames using the ICSeqCompressFrame function.

BOOL ICSeqCompressFrameStart(

PCOMPVARS pc,
LPBITMAPINFO lpbiIn
);
Parameters

pc

Address of a COMPVARS structure initialized with information for compression.

lpbiIn

Format of the data to be compressed.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

This function uses a COMPVARS structure to provide settings for the specified compressor and intersperses key frames at the rate specified by the lKey member of COMPVARS. You can specify values for the data rate for the sequence and the key-frame frequency by using the appropriate members of COMPVARS.

Use the ICSeqCompressFrameStart, ICSeqCompressFrame, and ICSeqCompressFrameEnd functions to compress a sequence of frames to a specified data rate and number of key frames.

When finished with compression, use the ICCompressorFree function to release the resources specified in COMPVARS.

COMPVARS needs to be initialized before you use this function. You can initialize the structure manually or you can allow the user to specify a compressor and initialize a COMPVARS structure by using the ICCompressorChoose function.

See Also

ICSeqCompressFrame, ICSeqCompressFrameEnd, ICCompressorFree, ICCompressorChoose, COMPVARS


ICSetStatusProc

The ICSetStatusProc function sends the address of a status callback function to a compressor. The compressor calls this function during lengthy operations.

DWORD ICSetStatusProc(

HIC hic,
DWORD dwFlags,
LONG lParam,
LONG (CALLBACK * ()) fpfnStatus
);
Parameters

hic

Handle of the compressor.

dwFlags

Applicable flags. Set to zero.

lParam

Constant specified with the status callback address.

fpfnStatus

Address of the status callback function. Specify NULL to indicate no status callbacks should be sent.

Return Values

Returns ICERR_OK if successful or FALSE otherwise.


IOProc

The IOProc function accesses a unique storage system, such as a database or file archive. You can install or remove this callback function by using the mmioInstallIOProc function.

IOProc is a placeholder for the application-defined function name. The actual name must be exported by including it in a EXPORTS statement in the application’s module-definition file.

LRESULT PASCAL IOProc(

LPSTR lpmmioinfo,
UINT wMsg,
LPARAM lParam1,
LPARAM lParam2
);
Parameters

lpmmioinfo

Address of an MMIOINFO structure containing information about the open file. The I/O procedure must maintain the lDiskOffset member in this structure to indicate the file offset to the next read or write location. The I/O procedure can use the adwInfo member to store state information. The I/O procedure should not modify any other members of the MMIOINFO structure.

wMsg

Message indicating the requested I/O operation. Messages that can be received include MMIOM_OPEN, MMIOM_CLOSE, MMIOM_READ, MMIOM_WRITE, and MMIOM_SEEK.

lParam1 and lParam2

Parameters for the message.

Return Values

Returns a value that corresponds to the message specified by wMsg. If the I/O procedure does not recognize a message, it should return zero.

Remarks

The four-character code specified by the fccIOProc member of the MMIOINFO structure associated with a file identifies a filename extension for a custom storage system. When an application calls the mmioOpen function with a filename such as EXAMPLE.XYZ! ABC, the I/O procedure associated with the four-character code “XYZ” is called to open the ABC element of the file EXAMPLE.XYZ.

The mmioInstallIOProc function maintains a separate list of installed I/O procedures for each Windows application. Therefore, different applications can use the same I/O procedure identifier for different I/O procedures without conflict.

If an application calls mmioInstallIOProc more than once to register the same I/O procedure, it must call this function to remove the procedure once for each time it installed the procedure.

The mmioInstallIOProc function does not prevent an application from installing two different I/O procedures with the same identifier, or installing an I/O procedure with one of the predefined identifiers (DOS or MEM). The most recently installed procedure takes precedence, and the most recently installed procedure is the first one to be removed.

When searching for a specified I/O procedure, local procedures are searched first, then global procedures.

See Also

mmioInstallIOProc, MMIOINFO, MMIOM_OPEN, MMIOM_CLOSE, MMIOM_READ, MMIOM_WRITE, MMIOM_SEEK, mmioOpen, ABC


joyGetDevCaps

The joyGetDevCaps function queries a joystick to determine its capabilities.

MMRESULT joyGetDevCaps(

UINT uJoyID,
LPJOYCAPS pjc,
UINT cbjc
);
Parameters

uJoyID

Identifier of the joystick (JOYSTICKID1 or JOYSTICKID2) to be queried.

pjc

Address of a JOYCAPS structure to contain the capabilities of the joystick.

cbjc

Size, in bytes, of the JOYCAPS structure.

Return Values

Returns JOYERR_NOERROR if successful or one of the following error values:

Remarks

Use the joyGetNumDevs function to determine the number of joystick devices supported by the driver.

MMSYSERR_NODRIVER	The joystick driver is not present.
MMSYSERR_INVALPARAM	An invalid parameter was passed.
See Also

JOYCAPS, joyGetNumDevs


joyGetNumDevs

The joyGetNumDevs function queries the joystick driver for the number of joysticks it supports.

UINT joyGetNumDevs(VOID);

Parameters

This function takes no parameters.

Return Values

Returns the number of joysticks supported by the joystick driver or zero if no driver is present.

Remarks

Use the joyGetPos function to determine whether a given joystick is physically attached to the system. If the specified joystick is not connected, joyGetPos returns a JOYERR_UNPLUGGED error value.

See Also

joyGetPos


joyGetPos

The joyGetPos function queries a joystick for its position and button status.

MMRESULT joyGetPos(

UINT uJoyID,
LPJOYINFO pji
);
Parameters

uJoyID

Identifier of the joystick (JOYSTICKID1 or JOYSTICKID2) to be queried.

pji

Address of a JOYINFO structure that contains the position and button status of the joystick.

Return Values

Returns JOYERR_NOERROR if successful or one of the following error values:

MMSYSERR_NODRIVER	The joystick driver is not present.
MMSYSERR_INVALPARAM	An invalid parameter was passed.
JOYERR_UNPLUGGED	The specified joystick is not connected to the system.
Remarks

For devices that have four to six axes of movement, a point-of-view control, or more than four buttons, use the joyGetPosEx function.

See Also

JOYINFO, joyGetPosEx


joyGetPosEx

The joyGetPosEx function queries a joystick for its position and button status.

MMRESULT joyGetPosEx(

UINT uJoyID,
LPJOYINFOEX pji
);
Parameters

uJoyID

Identifier of the joystick (JOYSTICKID1 or JOYSTICKID2) to be queried.

pji

Address of a JOYINFOEX structure that contains extended position information and button status of the joystick.

Return Values

Returns JOYERR_NOERROR if successful or one of the following error values:

MMSYSERR_NODRIVER	The joystick driver is not present.
MMSYSERR_INVALPARAM	An invalid parameter was passed.
MMSYSERR_BADDEVICEID	The specified joystick identifier is invalid.
JOYERR_UNPLUGGED	The specified joystick is not connected to the system.
Remarks

This function provides access to extended devices such as rudder pedals, point-of-view hats, devices with a large number of buttons, and coordinate systems using up to six axes. For joystick devices that use three axes or fewer and have fewer than four buttons, use the joyGetPos function.

See Also

JOYINFOEX, joyGetPos


joyGetThreshold

The joyGetThreshold function queries a joystick for its current movement threshold.

MMRESULT joyGetThreshold(

UINT uJoyID,
LPUINT puThreshold
);
Parameters

uJoyID

Identifier of the joystick (JOYSTICKID1 or JOYSTICKID2) to be queried.

puThreshold

Address of a variable that contains the movement threshold value.

Return Values

Returns JOYERR_NOERROR if successful or one of the following error values:

MMSYSERR_NODRIVER	The joystick driver is not present.
MMSYSERR_INVALPARAM	An invalid parameter was passed.
Remarks

The movement threshold is the distance the joystick must be moved before a WM_JOYMOVE message is sent to a window that has captured the device. The threshold is initially zero.


joyReleaseCapture

The joyReleaseCapture function releases the specified captured joystick.

MMRESULT joyReleaseCapture(

UINT uJoyID
);
Parameters

uJoyID

Identifier of the joystick (JOYSTICKID1 or JOYSTICK2) to be released.

Return Values

Returns JOYERR_NOERROR if successful or one of the following error values:

MMSYSERR_NODRIVER	The joystick driver is not present.
JOYERR_PARMS	The specified joystick device identifier uJoyID is invalid.


joySetCapture

The joySetCature function captures a joystick by causing its messages to be sent to the specified window.

MMRESULT joySetCapture(

HWND hwnd,
UINT uJoyID,
UINT uPeriod,
BOOL fChanged
);
Parameters

hwnd

Handle of the window to receive the joystick messages.

uJoyID

Identifier of the joystick (JOYSTICKID1 or JOYSTICKID2) to be captured.

uPeriod

Polling frequency, in milliseconds.

fChanged

Change position flag. Specify TRUE for this parameter to send messages only when the position changes by a value greater than the joystick movement threshold. Otherwise, messages are sent at the polling frequency specified in uPeriod.

Return Values

Returns JOYERR_NOERROR if successful or one of the following error values:

MMSYSERR_NODRIVER	The joystick driver is not present.
JOYERR_NOCANDO	Cannot capture joystick input because a required service (such as a Windows timer) is unavailable.
JOYERR_UNPLUGGED	The specified joystick is not connected to the system.
Remarks

This function fails if the specified joystick is currently captured. Call the joyReleaseCapture function to release the captured joystick, or destroy the window to release the joystick automatically.

See Also

joyReleaseCapture


joySetThreshold

The joySetThreshold function sets the movement threshold of a joystick.

MMRESULT joySetThreshold(

UINT uJoyID,
UINT uThreshold
);
Parameters

uJoyID

Identifier of the joystick (JOYSTICKID1 or JOYSTICKID2).

uThreshold

New movement threshold.

Return Values

Returns JOYERR_NOERROR if successful or one of the following error values:

MMSYSERR_NODRIVER	The joystick driver is not present.
JOYERR_PARMS	The specified joystick device identifier uJoyID is invalid.
Remarks

The movement threshold is the distance the joystick must be moved before a WM_JOYMOVE message is sent to a window that has captured the device. The threshold is initially zero.


mciGetCreatorTask

The mciGetCreatorTask function retrieves a handle to the creator task for the specified device.

HANDLE mciGetCreatorTask(

MCIDEVICEID IDDevice
);
Parameters

IDDevice

Device for which the creator task is returned.

Return Values

Returns the handle of the creator task responsible for opening the device if successful. If the device identifier is invalid, the return value is NULL.


mciGetDeviceID

The mciGetDeviceID function retrieves the device identifier corresponding to the name of an open device.

MCIDEVICEID mciGetDeviceID(

LPCTSTR lpszDevice
);
Parameters

lpszDevice

Address of a null-terminated string that specifies the device name or the alias name by which the device is known.

Return Values

Returns the device identifier assigned to the device when it was opened if successful. The identifier is used in the mciSendCommand function. If the device name is not known, if the device is not open, or if there was not enough memory to complete the operation, the return value is zero.

Remarks

Each file for a compound device has a unique device identifier. The identifier of the “all” device is MCI_ALL_DEVICE_ID.

See Also

mciSendCommand


mciGetErrorString

The mciGetErrorString function retrieves a string that describes the specified MCI error code.

BOOL mciGetErrorString(

DWORD fdwError,
LPTSTR lpszErrorText,
UINT cchErrorText
);
Parameters

fdwError

Error code returned by the mciSendCommand or mciSendString function.

lpszErrorText

Address of a buffer that receives a null-terminated string describing the specified error.

cchErrorText

Length of the buffer, in characters, pointed to by the lpszErrorText parameter.

Return Values

Returns TRUE if successful or FALSE if the error code is not known.

Remarks

Each string that MCI returns, whether data or an error description, can be a maximum of 128 characters.

See Also

mciSendCommand, mciSendString


mciGetYieldProc

The mciGetYieldProc function retrieves the address of the callback function associated with the “wait” (MCI_WAIT) flag. The callback function is called periodically while an MCI device waits for a command specified with the “wait” flag to finish.

YIELDPROC mciGetYieldProc(

MCIDEVICEID IDDevice,
LPDWORD lpdwYieldData
);
Parameters

IDDevice

MCI device being monitored (the device performing an MCI command).

lpdwYieldData

Address of a buffer containing yield data to be passed to the callback function. This parameter can be NULL if there is no yield data.

Return Values

Returns the address of the current yield callback function if successful or NULL if the device identifier is invalid.


mciSendCommand

The mciSendCommand function sends a command message to the specified MCI device.

MCIERROR mciSendCommand(

MCIDEVICEID IDDevice,
UINT uMsg,
DWORD fdwCommand,
DWORD dwParam
);
Parameters

IDDevice

Device identifier of the MCI device that is to receive the command message. This parameter is not used with the MCI_OPEN command message.

uMsg

Command message.  For information about command messages, see Command Messages.

fdwCommand

Flags for the command message.

dwParam

Address of a structure that contains parameters for the command message.

Return Values

Returns zero if successful or an error otherwise. The low-order word of the returned doubleword value contains the error return value. If the error is device-specific, the high-order word of the return value is the driver identifier; otherwise, the high-order word is zero. For a list of possible return values, see Constants: MCIERR Return Values.

To retrieve a text description of mciSendCommand return values, pass the return value to the mciGetErrorString function.

Remarks

Error values that are returned when a device is being opened are listed with the MCI_OPEN command message. In addition to the MCI_OPEN error return values, this function can return the values listed in Constants: MCIERR Return Values.

Use MCI_OPEN to obtain the device identifier specified by the IDDevice parameter.

See Also

MCI_OPEN, mciGetErrorString


mciSendString

The mciSendString function sends a command string to an MCI device. The device that the command is sent to is specified in the command string.

MCIERROR mciSendString(

LPCTSTR lpszCommand,
LPTSTR lpszReturnString,
UINT cchReturn,
HANDLE hwndCallback
);
Parameters

lpszCommand

Address of a null-terminated string that specifies an MCI command string. For more information about the command strings, see Command Strings.

lpszReturnString

Address of a buffer that receives return information. If no return information is needed, this parameter can be NULL.

cchReturn

Size, in characters, of the return buffer specified by the lpszReturnString parameter.

hwndCallback

Handle of a callback window if the “notify” flag was specified in the command string.

Return Values

Returns zero if successful or an error otherwise. The low-order word of the returned doubleword value contains the error return value. If the error is device-specific, the high-order word of the return value is the driver identifier; otherwise, the high-order word is zero. For a list of possible error values, see Constants: MCIERR Return Values.

To retrieve a text description of mciSendString return values, pass the return value to the mciGetErrorString function.

See Also

mciGetErrorString


mciSetYieldProc

The mciSetYieldProc function sets the address of a procedure to be called periodically when an MCI device is waiting for a command to finish because the “wait” (MCI_WAIT) flag was specified.

UINT mciSetYieldProc(

MCIDEVICEID IDDevice,
YIELDPROC yp,
DWORD dwYieldData
);
Parameters

IDDevice

Identifier of the device to assign a procedure to.

yp

Address of the procedure to call when yielding for the specified device. If this parameter is NULL, the function disables any existing yield procedure.

dwYieldData

Data to be sent to the yield procedure when it is called for the specified device.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

This function overrides any previous yield procedure for this device.


MCIWndCreate

The MCIWndCreate function registers the MCIWnd window class and creates an MCIWnd window for using MCI services. MCIWndCreate can also open an MCI device or file (such as an AVI file) and associate it with the MCIWnd window.

HWND MCIWndCreate(

HWND hwndParent,
HINSTANCE hInstance,
DWORD dwStyle,
LPSTR szFile
);
Parameters

hwndParent

Handle of the parent window.

hInstance

Handle of the module instance to associate with the MCIWnd window.

dwStyle

Flags defining the window style. In addition to specifying the window styles used with the CreateWindowEx function, you can specify the following styles to use with MCIWnd windows:

MCIWNDF_NOAUTOSIZEWINDOW

Will not change the dimensions of an MCIWnd window when the image size changes.

MCIWNDF_NOAUTOSIZEMOVIE

Will not change the dimensions of the destination rectangle when an MCIWnd window size changes.

MCIWNDF_NOERRORDLG

Inhibits display of MCI errors to users.

MCIWNDF_NOMENU

Hides the Menu button from view on the toolbar and prohibits users from accessing its pop-up menu.

MCIWNDF_NOOPEN

Hides the open and close commands from the MCIWnd menu and prohibits users from accessing these choices in the pop-up menu.

MCIWNDF_NOPLAYBAR

Hides the toolbar from view and prohibits users from accessing it.

MCIWNDF_NOTIFYANSI

Causes MCIWnd to use an ANSI string instead of a Unicode string when notifying the parent window of device mode changes. This flag is used in combination with MCIWNDF_NOTIFYMODE and is exclusive to Windows NT.

MCIWNDF_NOTIFYMODE

Causes MCIWnd to notify the parent window with an MCIWNDM_NOTIFYMODE message whenever the device changes operating modes. The lParam parameter of this message identifies the new mode, such as MCI_MODE_STOP.

MCIWNDF_NOTIFYPOS

Causes MCIWnd to notify the parent window with an MCIWNDM_NOTIFYPOS message whenever a change in the playback or record position within the content occurs. The lParam parameter of this message contains the new position in the content.

MCIWNDF_NOTIFYMEDIA

Causes MCIWnd to notify the parent window with an MCIWNDM_NOTIFYMEDIA message whenever a new device is used or a data file is opened or closed. The lParam parameter of this message contains a pointer to the new filename.

MCIWNDF_NOTIFYSIZE

Causes MCIWnd to notify the parent window when the MCIWnd window size changes.

MCIWNDF_NOTIFYERROR

Causes MCIWnd to notify the parent window when an MCI error occurs.

MCIWNDF_NOTIFYALL

Causes all MCIWNDF window notification styles to be used.

MCIWNDF_RECORD

Adds a Record button to the toolbar and adds a new file command to the menu if the MCI device has recording capability.

MCIWNDF_SHOWALL

Causes all MCIWNDF_SHOW styles to be used.

MCIWNDF_SHOWMODE

Displays the current mode of the MCI device in the window title bar. For a list of device modes, see the MCIWndGetMode macro.

MCIWNDF_SHOWNAME

Displays the name of the open MCI device or data file in the MCIWnd window title bar.

MCIWNDF_SHOWPOS

Displays the current position within the content of the MCI device in the window title bar.

szFile

Null-terminated string indicating the name of an MCI device or data file to open.

Return Values

Returns the handle to an MCI window if successful or zero otherwise.

Remarks

Default window styles for a child window are WS_CHILD, WS_BORDER, and WS_VISIBLE. MCIWndCreate assumes a child window when a non-NULL handle of a parent window is specified.

Default window styles for a parent window are WS_OVERLAPPEDWINDOW and WS_VISIBLE. MCIWndCreate assumes a parent window when a NULL handle of a parent window is specified.

Use the window handle returned by this function for the window handle in the MCIWnd macros. If your application uses this function, it does not need to use the MCIWndRegisterClass function.

See Also

CreateWindowEx, MCIWNDM_NOTIFYMODE, MCIWNDM_NOTIFYPOS, MCIWNDM_NOTIFYMEDIA, MCIWndGetMode, MCIWndRegisterClass


MCIWndRegisterClass

The MCIWndRegisterClass function registers the MCI window class MCIWND_WINDOW_CLASS.

BOOL MCIWndRegisterClass(

HINSTANCE hInstance
);
Parameters

hInstance

Handle of the device instance.

Return Values

Returns zero if successful.

Remarks

After registering the MCI window class, use the CreateWindow or CreateWindowEx functions to create an MCIWnd window. If your application uses this function, it does not need to use the MCIWndCreate function.

See Also

CreateWindow, CreateWindowEx, MCIWndCreate


midiConnect

The midiConnect function connects a MIDI input device to a MIDI thru or output device, or connects a MIDI thru device to a MIDI output device.

MMRESULT midiConnect(

HMIDI hMidi,
HMIDIOUT hmo,
LPVOID pReserved
);
Parameters

hMidi

Handle of a MIDI input device or a MIDI thru device. (For thru devices, this handle must have been returned by a call to the midiOutOpen function.)

hmo

Handle of the MIDI output or thru device.

pReserved

Reserved; must be NULL.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MIDIERR_NOTREADY	Specified input device is already connected to an output device.
MMSYSERR_INVALHANDLE	Specified device handle is invalid.
Remarks

After calling this function, the MIDI input device receives event data in an MIM_DATA message whenever a message with the same event data is sent to the output device driver.

A thru driver is a special form of MIDI output driver. The system will allow only one MIDI output device to be connected to a MIDI input device, but multiple MIDI output devices can be connected to a MIDI thru device. Whenever the given MIDI input device receives event data in an MIM_DATA message, a message with the same event data is sent to the given output device driver (or through the thru driver to the output drivers).

See Also

midiOutOpen, MIM_DATA


midiDisconnect

The midiDisconnect function disconnects a MIDI input device from a MIDI thru or output device, or disconnects a MIDI thru device from a MIDI output device.

MMRESULT midiDisconnect(

HMIDI hMidi,
HMIDIOUT hmo,
LPVOID pReserved
);
Parameters

hMidi

Handle of a MIDI input device or a MIDI thru device.

hmo

Handle of the MIDI output device to be disconnected.

pReserved

Reserved; must be NULL.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
Remarks

MIDI input, output, and thru devices can be connected by using the midiConnect function. Thereafter, whenever the MIDI input device receives event data in an MIM_DATA message, a message with the same event data is sent to the output device driver (or through the thru driver to the output drivers).

See Also

midiConnect, MIM_DATA


midiInAddBuffer

The midiInAddBuffer function sends an input buffer to a specified opened MIDI input device. This function is used for system-exclusive messages.

MMRESULT midiInAddBuffer(

HMIDIIN hMidiIn,
LPMIDIHDR lpMidiInHdr,
UINT cbMidiInHdr
);
Parameters

hMidiIn

Handle of the MIDI input device.

lpMidiInHdr

Address of a MIDIHDR structure that identifies the buffer.

cbMidiInHdr

Size, in bytes, of the MIDIHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MIDIERR_STILLPLAYING	The buffer pointed to by lpMidiInHdr is still in the queue.
MIDIERR_UNPREPARED	The buffer pointed to by lpMidiInHdr has not been prepared.
MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_INVALPARAM	The specified pointer or structure is invalid.
MMSYSERR_NOMEM	The system is unable to allocate or lock memory.
Remarks

When the buffer is filled, it is sent back to the application.

The buffer must be prepared by using the midiInPrepareHeader function before it is passed to the midiInAddBuffer function.

See Also

MIDIHDR, midiInPrepareHeader


midiInClose

The midiInClose function closes the specified MIDI input device.

MMRESULT midiInClose(

HMIDIIN hMidiIn
);
Parameters

hMidiIn

Handle of the MIDI input device. If the function is successful, the handle is no longer valid after the call to this function.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MIDIERR_STILLPLAYING	Buffers are still in the queue.
MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_NOMEM	The system is unable to allocate or lock memory.
Remarks

If there are input buffers that have been sent by using the midiInAddBuffer function and have not been returned to the application, the close operation will fail. To return all pending buffers through the callback function, use the midiInReset function.

See Also

midiInAddBuffer, midiInReset


midiInGetDevCaps

The midiInGetDevCaps function determines the capabilities of a specified MIDI input device.

MMRESULT midiInGetDevCaps(

UINT uDeviceID,
LPMIDIINCAPS lpMidiInCaps,
UINT cbMidiInCaps
);
Parameters

uDeviceID

Identifier of the MIDI input device. The device identifier varies from zero to one less than the number of devices present. This parameter can also be a properly cast device handle.

lpMidiInCaps

Address of a MIDIINCAPS structure that is filled with information about the capabilities of the device.

cbMidiInCaps

Size, in bytes, of the MIDIINCAPS structure. Only cbMidiInCaps bytes (or less) of information is copied to the location pointed to by lpMidiInCaps. If cbMidiInCaps is zero, nothing is copied, and the function returns MMSYSERR_NOERROR.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_BADDEVICEID	The specified device identifier is out of range.
MMSYSERR_INVALPARAM	The specified pointer or structure is invalid.
MMSYSERR_NODRIVER	The driver is not installed.
MMSYSERR_NOMEM	The system is unable to allocate or lock memory.
Remarks

To determine the number of MIDI input devices present on the system, use the midiInGetNumDevs function.

See Also

MIDIINCAPS, midiInGetNumDevs


midiInGetErrorText

The midiInGetErrorText function retrieves a textual description for an error identified by the specified error code.

MMRESULT midiInGetErrorText(

MMRESULT wError,
LPSTR lpText,
UINT cchText
);
Parameters

wError

Error code.

lpText

Address of the buffer to be filled with the textual error description.

cchText

Length, in characters, of the buffer pointed to by lpText.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_BADERRNUM	The specified error number is out of range.
MMSYSERR_INVALPARAM	The specified pointer or structure is invalid.
MMSYSERR_NOMEM	The system is unable to allocate or lock memory.
Remarks

If the textual error description is longer than the specified buffer, the description is truncated. The returned error string is always null-terminated. If cchText is zero, nothing is copied, and the function returns zero. All error descriptions are less than MAXERRORLENGTH characters long.


midiInGetID

The midiInGetID function gets the device identifier for the given MIDI input device.

This function is supported for backward compatibility. New applications can cast a handle of the device rather than retrieving the device identifier.

MMRESULT midiInGetID(

HMIDIIN hmi,
LPUINT puDeviceID
);
Parameters

hmi

Handle of the MIDI input device.

puDeviceID

Address of a variable to be filled with the device identifier.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The hwi parameter specifies an invalid handle.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.


midiInGetNumDevs

The midiInGetNumDevs function retrieves the number of MIDI input devices in the system.

UINT midiInGetNumDevs(VOID);

Parameters

This function takes no parameters.

Return Values

Returns the number of MIDI input devices present in the system. A return value of zero means that there are no devices (not that there is no error).


midiInMessage

The midiInMessage function sends a message to the MIDI device driver.

DWORD midiInMessage(

HMIDIIN hMidiIn,
UINT msg,
DWORD dw1,
DWORD dw2
);
Parameters

hMidiIn

Handle of the MIDI device.

msg

Message to send.

dw1 and dw2

Message parameters.

Return Values

Returns the value returned by the audio device driver.

Remarks

This function is used only for driver-specific messages that are not supported by the MIDI API.


midiInOpen

The midiInOpen function opens a specified MIDI input device.

MMRESULT midiInOpen(

LPHMIDIIN lphMidiIn,
UINT uDeviceID,
DWORD dwCallback,
DWORD dwCallbackInstance,
DWORD dwFlags
);
Parameters

lphMidiIn

Address of an HMIDIIN handle. This location is filled with a handle identifying the opened MIDI input device. The handle is used to identify the device in calls to other MIDI input functions.

uDeviceID

Identifier of the MIDI input device to be opened.

dwCallback

Address of a callback function, a thread identifier, or a handle of a window called with information about incoming MIDI messages. For more information on the callback function, see MidiInProc.

dwCallbackInstance

User instance data passed to the callback function. This parameter is not used with window callback functions or threads.

dwFlags

Callback flag for opening the device and, optionally, a status flag that helps regulate rapid data transfers. It can be the following values:

CALLBACK_FUNCTION

The dwCallback parameter is a callback procedure address.

CALLBACK_NULL

There is no callback mechanism. This value is the default setting.

CALLBACK_THREAD

The dwCallback parameter is a thread identifier.

CALLBACK_WINDOW

The dwCallback parameter is a window handle.

MIDI_IO_STATUS

When this parameter also specifies CALLBACK_FUNCTION, MIM_MOREDATA messages are sent to the callback function as well as MIM_DATA messages. Or, if this parameter also specifies CALLBACK_WINDOW, MM_MIM_MOREDATA messages are sent to the window as well as MM_MIM_DATA messages. This flag does not affect event or thread callbacks.

Most applications that use a callback mechanism will specify CALLBACK_FUNCTION for this parameter.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_ALLOCATED	The specified resource is already allocated.
MMSYSERR_BADDEVICEID	The specified device identifier is out of range.
MMSYSERR_INVALFLAG	The flags specified by dwFlags are invalid.
MMSYSERR_INVALPARAM	The specified pointer or structure is invalid.
MMSYSERR_NOMEM	The system is unable to allocate or lock memory.
Remarks

To determine the number of MIDI input devices present in the system, use the midiInGetNumDevs function. The device identifier specified by wDeviceID varies from zero to one less than the number of devices present.

If a window or thread is chosen to receive callback information, the following messages are sent to the window procedure or thread to indicate the progress of MIDI input: MM_MIM_OPEN, MM_MIM_CLOSE, MM_MIM_DATA, MM_MIM_LONGDATA, MM_MIM_ERROR, MM_MIM_LONGERROR, and MM_MIM_MOREDATA.

If a function is chosen to receive callback information, the following messages are sent to the function to indicate the progress of MIDI input: MIM_OPEN, MIM_CLOSE, MIM_DATA, MIM_LONGDATA, MIM_ERROR, MIM_LONGERROR, and MIM_MOREDATA.

See Also

MIM_MOREDATA, MIM_DATA, MM_MIM_MOREDATA, MM_MIM_DATA, midiInGetNumDevs, MidiInProc, MM_MIM_OPEN, MM_MIM_CLOSE, MM_MIM_LONGDATA, MM_MIM_ERROR, MM_MIM_LONGERROR, MIM_OPEN, MIM_CLOSE, MIM_DATA, MIM_LONGDATA, MIM_ERROR, MIM_LONGERROR, MIM_MOREDATA


midiInPrepareHeader

The midiInPrepareHeader function prepares a buffer for MIDI input.

MMRESULT midiInPrepareHeader(

HMIDIIN hMidiIn,
LPMIDIHDR lpMidiInHdr,
UINT cbMidiInHdr
);
Parameters

hMidiIn

Handle of the MIDI input device.

lpMidiInHdr

Address of a MIDIHDR structure that identifies the buffer to be prepared.

cbMidiInHdr

Size, in bytes, of the MIDIHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_INVALPARAM	The specified address is invalid.
MMSYSERR_NOMEM	The system is unable to allocate or lock memory.
Remarks

Preparing a header that has already been prepared has no effect, and the function returns zero.

Before using this function, you must set the lpData, dwBufferLength, and dwFlags members of the MIDIHDR structure. The dwFlags member must be set to zero.

See Also

MIDIHDR


MidiInProc

The MidiInProc function is the callback function for handling incoming MIDI messages. MidiInProc is a placeholder for the application-supplied function name. The address of this function can be specified in the callback-address parameter of the midiInOpen function.

void CALLBACK MidiInProc(

HMIDIIN hMidiIn,
UINT wMsg,
DWORD dwInstance,
DWORD dwParam1,
DWORD dwParam2
);
Parameters

hMidiIn

Handle of the MIDI input device.

wMsg

MIDI input message.

dwInstance

Instance data supplied with the midiInOpen function.

dwParam1

Message parameters.

dwParam2

Message parameters.

Return Values

This function does not return a value.

Remarks

Applications should not call any system-defined functions from inside a callback function, except for EnterCriticalSection, LeaveCriticalSection, midiOutLongMsg, midiOutShortMsg, OutputDebugString, PostMessage, PostThreadMessage, SetEvent, timeGetSystemTime, timeGetTime, timeKillEvent, and timeSetEvent.

See Also

EnterCriticalSection, LeaveCriticalSection, midiInOpen, midiOutLongMsg, midiOutShortMsg, OutputDebugString, PostMessage, PostThreadMessage, SetEvent, timeGetSystemTime, timeGetTime, timeKillEvent, timeSetEvent,


midiInReset

The midiInReset function stops input on a given MIDI input device.

MMRESULT midiInReset(

HMIDIIN hMidiIn
);
Parameters

hMidiIn

Handle of the MIDI input device.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The specified device handle is invalid.
Remarks

This function returns all pending input buffers to the callback function and sets the MHDR_DONE flag in the dwFlags member of the MIDIHDR structure.

See Also

MIDIHDR


midiInStart

The midiInStart function starts MIDI input on the specified MIDI input device.

MMRESULT midiInStart(

HMIDIIN hMidiIn
);
Parameters

hMidiIn

Handle of the MIDI input device.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The specified device handle is invalid.
Remarks

This function resets the time stamp to zero; time stamp values for subsequently received messages are relative to the time that this function was called.

All messages except system-exclusive messages are sent directly to the client when they are received. System-exclusive messages are placed in the buffers supplied by the midiInAddBuffer function. If there are no buffers in the queue, the system-exclusive data is thrown away without notification to the client and input continues. Buffers are returned to the client when they are full, when a complete system-exclusive message has been received, or when the midiInReset function is used. The dwBytesRecorded member of the MIDIHDR structure will contain the actual length of data received.

Calling this function when input is already started has no effect, and the function returns zero.

See Also

midiInAddBuffer, midiInReset, MIDIHDR


midiInStop

The midiInStop function stops MIDI input on the specified MIDI input device.

MMRESULT midiInStop(

HMIDIIN hMidiIn
);
Parameters

hMidiIn

Handle of the MIDI input device.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The specified device handle is invalid.
Remarks

If there are any system-exclusive messages or stream buffers in the queue, the current buffer is marked as done (the dwBytesRecorded member of the MIDIHDR structure will contain the actual length of data), but any empty buffers in the queue remain there and are not marked as done.

Calling this function when input is not started has no effect, and the function returns zero.

See Also

MIDIHDR


midiInUnprepareHeader

The midiInUnprepareHeader function cleans up the preparation performed by the midiInPrepareHeader function.

MMRESULT midiInUnprepareHeader(

HMIDIIN hMidiIn,
LPMIDIHDR lpMidiInHdr,
UINT cbMidiInHdr
);
Parameters

hMidiIn

Handle of the MIDI input device.

lpMidiInHdr

Address of a MIDIHDR structure identifying the buffer to be cleaned up.

cbMidiInHdr

Size of the MIDIHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MIDIERR_STILLPLAYING	The buffer pointed to by lpMidiInHdr is still in the queue.
MMSYSERR_INVALPARAM	The specified pointer or structure is invalid.
MMSYSERR_INVALHANDLE	The specified device handle is invalid.
Remarks

This function is complementary to midiInPrepareHeader. You must use this function before freeing the buffer. After passing a buffer to the device driver by using the midiInAddBuffer function, you must wait until the driver is finished with the buffer before using midiInUnprepareHeader. Unpreparing a buffer that has not been prepared has no effect, and the function returns MMSYSERR_NOERROR.

See Also

midiInPrepareHeader, MIDIHDR, midiInAddBuffer


midiOutCacheDrumPatches

The midiOutCacheDrumPatches function requests that an internal MIDI synthesizer device preload and cache a specified set of key-based percussion patches.

MMRESULT midiOutCacheDrumPatches(

HMIDIOUT hmo,
UINT wPatch,
WORD * lpKeyArray,
UINT wFlags
);
Parameters

hmo

Handle of the opened MIDI output device. This device should be an internal MIDI synthesizer. This parameter can also be the handle of a MIDI stream, cast to HMIDIOUT.

wPatch

Drum patch number that should be used. This parameter should be set to zero to cache the default drum patch.

lpKeyArray

Address of a KEYARRAY array indicating the key numbers of the specified percussion patches to be cached or uncached.

wFlags

Options for the cache operation. It can be one of the following flags:

MIDI_CACHE_ALL

Caches all of the specified patches. If they cannot all be cached, it caches none, clears the KEYARRAY array, and returns MMSYSERR_NOMEM.

MIDI_CACHE_BESTFIT

Caches all of the specified patches. If they cannot all be cached, it caches as many patches as possible, changes the KEYARRAY array to reflect which patches were cached, and returns MMSYSERR_NOMEM.

MIDI_CACHE_QUERY

Changes the KEYARRAY array to indicate which patches are currently cached.

MIDI_UNCACHE

Uncaches the specified patches and clears the KEYARRAY array.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALFLAG	The flag specified by wFlags is invalid.
MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_INVALPARAM	The array pointed to by the lpKeyArray array is invalid.
MMSYSERR_NOMEM	The device does not have enough memory to cache all of the requested patches.
MMSYSERR_NOTSUPPORTED	The specified device does not support patch caching.
Remarks

Some synthesizers are not capable of keeping all percussion patches loaded simultaneously. Caching patches ensures that the specified patches are available.

Each element of the KEYARRAY array represents one of the 128 key-based percussion patches and has bits set for each of the 16 MIDI channels that use the particular patch. The least-significant bit represents physical channel 0, and the most-significant bit represents physical channel 15. For example, if the patch on key number 60 is used by physical channels 9 and 15, element 60 would be set to 0x8200.

This function applies only to internal MIDI synthesizer devices. Not all internal synthesizers support patch caching. To see if a device supports patch caching, use the MIDICAPS_CACHE flag to test the dwSupport member of the MIDIOUTCAPS structure filled by the midiOutGetDevCaps function.

See Also

KEYARRAY, MIDIOUTCAPS, midiOutGetDevCaps


midiOutCachePatches

The midiOutCachePatches function requests that an internal MIDI synthesizer device preload and cache a specified set of patches.

MMRESULT midiOutCachePatches(

HMIDIOUT hmo,
UINT wBank,
WORD * lpPatchArray,
UINT wFlags
);
Parameters

hmo

Handle of the opened MIDI output device. This device must be an internal MIDI synthesizer. This parameter can also be the handle of a MIDI stream, cast to HMIDIOUT.

wBank

Bank of patches that should be used. This parameter should be set to zero to cache the default patch bank.

lpPatchArray

Address of a PATCHARRAY array indicating the patches to be cached or uncached.

wFlags

Options for the cache operation. It can be one of the following flags:

MIDI_CACHE_ALL

Caches all of the specified patches. If they cannot all be cached, it caches none, clears the PATCHARRAY array, and returns MMSYSERR_NOMEM.

MIDI_CACHE_BESTFIT

Caches all of the specified patches. If they cannot all be cached, it caches as many patches as possible, changes the PATCHARRAY array to reflect which patches were cached, and returns MMSYSERR_NOMEM.

MIDI_CACHE_QUERY

Changes the PATCHARRAY array to indicate which patches are currently cached.

MIDI_UNCACHE

Uncaches the specified patches and clears the PATCHARRAY array.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALFLAG	The flag specified by wFlags is invalid.
MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_INVALPARAM	The array pointed to by lpPatchArray is invalid.
MMSYSERR_NOMEM	The device does not have enough memory to cache all of the requested patches.
MMSYSERR_NOTSUPPORTED	The specified device does not support patch caching.
Remarks

Some synthesizers are not capable of keeping all patches loaded simultaneously and must load data from disk when they receive MIDI program change messages. Caching patches ensures that the specified patches are immediately available.

Each element of the PATCHARRAY array represents one of the 128 patches and has bits set for each of the 16 MIDI channels that use the particular patch. The least-significant bit represents physical channel 0, and the most-significant bit represents physical channel 15 (0x0F). For example, if patch 0 is used by physical channels 0 and 8, element 0 would be set to 0x0101.

This function applies only to internal MIDI synthesizer devices. Not all internal synthesizers support patch caching. To see if a device supports patch caching, use the MIDICAPS_CACHE flag to test the dwSupport member of the MIDIOUTCAPS structure filled by the midiOutGetDevCaps function.

See Also

PATCHARRAY, MIDIOUTCAPS, midiOutGetDevCaps


midiOutClose

The midiOutClose function closes the specified MIDI output device.

MMRESULT midiOutClose(

HMIDIOUT hmo
);
Parameters

hmo

Handle of the MIDI output device. If the function is successful, the handle is no longer valid after the call to this function.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MIDIERR_STILLPLAYING	Buffers are still in the queue.
MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_NOMEM	The system is unable to load mapper string description.
Remarks

If there are output buffers that have been sent by using the midiOutLongMsg function and have not been returned to the application, the close operation will fail. To mark all pending buffers as being done, use the midiOutReset function.

See Also

midiOutLongMsg, midiOutReset


midiOutGetDevCaps

The midiOutGetDevCaps function queries a specified MIDI output device to determine its capabilities.

MMRESULT midiOutGetDevCaps(

UINT uDeviceID,
LPMIDIOUTCAPS lpMidiOutCaps,
UINT cbMidiOutCaps
);
Parameters

uDeviceID

Identifier of the MIDI output device. The device identifier specified by this parameter varies from zero to one less than the number of devices present. The MIDI_MAPPER constant is also a valid device identifier.

This parameter can also be a properly cast device handle.

lpMidiOutCaps

Address of a MIDIOUTCAPS structure. This structure is filled with information about the capabilities of the device.

cbMidiOutCaps

Size, in bytes, of the MIDIOUTCAPS structure. Only cbMidiOutCaps bytes (or less) of information is copied to the location pointed to by lpMidiOutCaps. If cbMidiOutCaps is zero, nothing is copied, and the function returns MMSYSERR_NOERROR.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_BADDEVICEID	The specified device identifier is out of range.
MMSYSERR_INVALPARAM	The specified pointer or structure is invalid.
MMSYSERR_NODRIVER	The driver is not installed.
MMSYSERR_NOMEM	The system is unable to load mapper string description.
Remarks

To determine the number of MIDI output devices present in the system, use the midiOutGetNumDevs function.

See Also

MIDIOUTCAPS, midiOutGetNumDevs


midiOutGetErrorText

The midiOutGetErrorText function retrieves a textual description for an error identified by the specified error code.

UINT midiOutGetErrorText(

MMRESULT mmrError,
LPSTR lpText,
UINT cchText
);
Parameters

mmrError

Error code.

lpText

Address of a buffer to be filled with the textual error description.

cchText

Length, in characters, of the buffer pointed to by lpText.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_BADERRNUM	The specified error number is out of range.
MMSYSERR_INVALPARAM	The specified pointer or structure is invalid.
Remarks

If the textual error description is longer than the specified buffer, the description is truncated. The returned error string is always null-terminated. If cchText is zero, nothing is copied, and the function returns MMSYSERR_NOERROR. All error descriptions are less than MAXERRORLENGTH characters long.


midiOutGetID

The midiOutGetID function retrieves the device identifier for the given MIDI output device.

This function is supported for backward compatibility. New applications can cast a handle of the device rather than retrieving the device identifier.

MMRESULT midiOutGetID(

HMIDIOUT hmo,
LPUINT puDeviceID
);
Parameters

hmo

Handle of the MIDI output device.

puDeviceID

Address of a variable to be filled with the device identifier.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The hwo parameter specifies an invalid handle.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.


midiOutGetNumDevs

The midiOutGetNumDevs function retrieves the number of MIDI output devices present in the system.

UINT midiOutGetNumDevs(VOID);

Parameters

This function takes no parameters.

Return Values

Returns the number of MIDI output devices. A return value of zero means that there are no devices (not that there is no error).


midiOutGetVolume

The midiOutGetVolume function retrieves the current volume setting of a MIDI output device.

MMRESULT midiOutGetVolume(

HMIDIOUT hmo,
LPDWORD lpdwVolume
);
Parameters

hmo

Handle of an open MIDI output device. This parameter can also contain the handle of a MIDI stream, as long as it is cast to HMIDIOUT. This parameter can also be a device identifier.

lpdwVolume

Address of the location to contain the current volume setting. The low-order word of this location contains the left-channel volume setting, and the high-order word contains the right-channel setting. A value of 0xFFFF represents full volume, and a value of 0x0000 is silence.

If a device does not support both left and right volume control, the low-order word of the specified location contains the mono volume level.

Any value set by using the midiOutSetVolume function is returned, regardless of whether the device supports that value.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_INVALPARAM	The specified pointer or structure is invalid.
MMSYSERR_NOMEM	The system is unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED	The function is not supported.
Remarks

If a device identifier is used, then the result of the midiOutGetVolume call and the information returned in lpdwVolume applies to all instances of the device. If a device handle is used, then the result and information returned applies only to the instance of the device referenced by the device handle.

Not all devices support volume control. You can determine whether a device supports volume control by querying the device by using the midiOutGetDevCaps function and specifying the MIDICAPS_VOLUME flag.

You can also determine whether the device supports volume control on both the left and right channels by querying the device by using the midiOutGetDevCaps function and specifying the MIDICAPS_LRVOLUME flag.

See Also

midiOutSetVolume, midiOutGetDevCaps


midiOutLongMsg

The midiOutLongMsg function sends a system-exclusive MIDI message to the specified MIDI output device.

MMRESULT midiOutLongMsg(

HMIDIOUT hmo,
LPMIDIHDR lpMidiOutHdr,
UINT cbMidiOutHdr
);
Parameters

hmo

Handle of the MIDI output device. This parameter can also be the handle of a MIDI stream cast to HMIDIOUT.

lpMidiOutHdr

Address of a MIDIHDR structure that identifies the MIDI buffer.

cbMidiOutHdr

Size, in bytes, of the MIDIHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MIDIERR_NOTREADY	The hardware is busy with other data.
MIDIERR_UNPREPARED	The buffer pointed to by lpMidiOutHdr has not been prepared.
MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_INVALPARAM	The specified pointer or structure is invalid.
Remarks

Before the buffer is passed to midiOutLongMsg, it must be prepared by using the midiOutPrepareHeader function. The MIDI output device driver determines whether the data is sent synchronously or asynchronously.

See Also

MIDIHDR, midiOutPrepareHeader


midiOutMessage

The midiOutMessage function sends a message to the MIDI device drivers. This function is used only for driver-specific messages that are not supported by the MIDI API.

DWORD midiOutMessage(

HMIDIOUT hmo,
UINT msg,
DWORD dw1,
DWORD dw2
);
Parameters

hmo

Handle of the MIDI device.  This parameter can also be the handle of a MIDI stream cast to HMIDIOUT.

msg

Message to send.

dw1 and dw2

Message parameters.

Return Values

Returns the value returned by the audio device driver.


midiOutOpen

The midiOutOpen function opens a MIDI output device for playback.

UINT midiOutOpen(

LPHMIDIOUT lphmo,
UINT uDeviceID,
DWORD dwCallback,
DWORD dwCallbackInstance,
DWORD dwFlags
);
Parameters

lphmo

Address of an HMIDIOUT handle. This location is filled with a handle identifying the opened MIDI output device. The handle is used to identify the device in calls to other MIDI output functions.

uDeviceID

Identifier of the MIDI output device that is to be opened.

dwCallback

Address of a callback function, an event handle, a thread identifier, or a handle of a window or thread called during MIDI playback to process messages related to the progress of the playback. If no callback is desired, specify NULL for this parameter. For more information on the callback function, see MidiOutProc.

dwCallbackInstance

User instance data passed to the callback. This parameter is not used with window callbacks or threads.

dwFlags

Callback flag for opening the device. It can be the following values:

CALLBACK_EVENT

The dwCallback parameter is an event handle. This callback mechanism is for output only.

CALLBACK_FUNCTION

The dwCallback parameter is a callback function address.

CALLBACK_NULL

There is no callback mechanism. This value is the default setting.

CALLBACK_THREAD

The dwCallback parameter is a thread identifier.

CALLBACK_WINDOW

The dwCallback parameter is a window handle.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MIDIERR_NODEVICE	No MIDI port was found. This error occurs only when the mapper is opened.
MMSYSERR_ALLOCATED	The specified resource is already allocated.
MMSYSERR_BADDEVICEID	The specified device identifier is out of range.
MMSYSERR_INVALPARAM	The specified pointer or structure is invalid.
MMSYSERR_NOMEM	The system is unable to allocate or lock memory.
Remarks

To determine the number of MIDI output devices present in the system, use the midiOutGetNumDevs function. The device identifier specified by wDeviceID varies from zero to one less than the number of devices present. MIDI_MAPPER can also be used as the device identifier.

If a window or thread is chosen to receive callback information, the following messages are sent to the window procedure or thread to indicate the progress of MIDI output: MM_MOM_OPEN, MM_MOM_CLOSE, and MM_MOM_DONE.

If a function is chosen to receive callback information, the following messages are sent to the function to indicate the progress of MIDI output: MOM_OPEN, MOM_CLOSE, and MOM_DONE.

See Also

midiOutGetNumDevs, MidiOutProc, MM_MOM_OPEN, MM_MOM_CLOSE, MM_MOM_DONE


midiOutPrepareHeader

The midiOutPrepareHeader function prepares a MIDI system-exclusive or stream buffer for output.

MMRESULT midiOutPrepareHeader(

HMIDIOUT hmo,
LPMIDIHDR lpMidiOutHdr,
UINT cbMidiOutHdr
);
Parameters

hmo

Handle of the MIDI output device. This parameter can also be the handle of a MIDI stream cast to HMIDIOUT.

lpMidiOutHdr

Address of a MIDIHDR structure that identifies the buffer to be prepared.

cbMidiOutHdr

Size, in bytes, of the MIDIHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_INVALPARAM	The specified address is invalid or the given stream buffer is greater than 64K.
MMSYSERR_NOMEM	The system is unable to allocate or lock memory.
Remarks

A stream buffer cannot be larger than 64K.

Preparing a header that has already been prepared has no effect, and the function returns MMSYSERR_NOERROR.

Before using this function, you must set the lpData, dwBufferLength, and dwFlags members of the MIDIHDR structure. The dwFlags member must be set to zero.

See Also

MIDIHDR


MidiOutProc

The MidiOutProc function is the callback function for handling outgoing MIDI messages. MidiOutProc is a placeholder for the application-supplied function name. The address of the function can be specified in the callback-address parameter of the midiOutOpen function.

void CALLBACK MidiOutProc(

HMIDIOUT hmo,
UINT wMsg,
DWORD dwInstance,
DWORD dwParam1,
DWORD dwParam2
);
Parameters

hmo

Handle of the MIDI device associated with the callback function.

wMsg

MIDI output message.

dwInstance

Instance data supplied by using the midiOutOpen function.

dwParam1

Message parameters.

dwParam2

Message parameters.

Return Values

This function does not return a value.

Remarks

Applications should not call any system-defined functions from inside a callback function, except for EnterCriticalSection, LeaveCriticalSection, midiOutLongMsg, midiOutShortMsg, OutputDebugString, PostMessage, PostThreadMessage, SetEvent, timeGetSystemTime, timeGetTime, timeKillEvent, and timeSetEvent. Calling other wave functions will cause deadlock.

See Also

EnterCriticalSection, LeaveCriticalSection, midiOutLongMsg, midiOutOpen, midiOutShortMsg, OutputDebugString, PostMessage, PostThreadMessage, SetEvent, timeGetSystemTime, timeGetTime, timeKillEvent, timeSetEvent,


midiOutReset

The midiOutReset function turns off all notes on all MIDI channels for the specified MIDI output device.

MMRESULT midiOutReset(

HMIDIOUT hmo
);
Parameters

hmo

Handle of the MIDI output device. This parameter can also be the handle of a MIDI stream cast to HMIDIOUT.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The specified device handle is invalid.
Remarks

Any pending system-exclusive or stream output buffers are returned to the callback function and the MHDR_DONE flag is set in the dwFlags member of the MIDIHDR structure.

Terminating a system-exclusive message without sending an EOX (end-of-exclusive) byte might cause problems for the receiving device. The midiOutReset function does not send an EOX byte when it terminates a system-exclusive message — applications are responsible for doing this.

To turn off all notes, a note-off message for each note in each channel is sent. In addition, the sustain controller is turned off for each channel.

See Also

MIDIHDR


midiOutSetVolume

The midiOutSetVolume function sets the volume of a MIDI output device.

MMRESULT midiOutSetVolume(

HMIDIOUT hmo,
DWORD dwVolume
);
Parameters

hmo

Handle of an open MIDI output device. This parameter can also contain the handle of a MIDI stream, as long as it is cast to HMIDIOUT. This parameter can also be a device identifier.

dwVolume

New volume setting. The low-order word contains the left-channel volume setting, and the high-order word contains the right-channel setting. A value of 0xFFFF represents full volume, and a value of 0x0000 is silence.

If a device does not support both left and right volume control, the low-order word of dwVolume specifies the mono volume level, and the high-order word is ignored.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_NOMEM	The system is unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED	The function is not supported.
Remarks

If a device identifier is used, then the result of the midiOutSetVolume call applies to all instances of the device. If a device handle is used, then the result applies only to the instance of the device referenced by the device handle.

Not all devices support volume changes. You can determine whether a device supports it by querying the device using the midiOutGetDevCaps function and the MIDICAPS_VOLUME flag.

You can also determine whether the device supports volume control on both the left and right channels by querying the device using the midiOutGetDevCaps function and the MIDICAPS_LRVOLUME flag.

Devices that do not support a full 16 bits of volume-level control use the high-order bits of the requested volume setting. For example, a device that supports 4 bits of volume control produces the same volume setting for the following volume-level values: 0x4000, 0x43be, and 0x4fff. The midiOutGetVolume function returns the full 16-bit value, as set by midiOutSetVolume, irrespective of the device’s capabilities.

Volume settings are interpreted logarithmically. This means that the perceived increase in volume is the same when increasing the volume level from 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.

See Also

midiOutGetDevCaps, midiOutGetVolume


midiOutShortMsg

The midiOutShortMsg function sends a short MIDI message to the specified MIDI output device.

MMRESULT midiOutShortMsg(

HMIDIOUT hmo,
DWORD dwMsg
);
Parameters

hmo

Handle of the MIDI output device. This parameter can also be the handle of a MIDI stream cast to HMIDIOUT.

dwMsg

MIDI message. The message is packed into a doubleword value with the first byte of the message in the low-order byte. The message is packed into this parameter as follows:

High word	High-order byte	Not used.
	Low-order byte	Contains a second byte of MIDI data (when needed).
Low word	High-order byte	Contains the first byte of MIDI data (when needed).
	Low-order byte	Contains the MIDI status.
The two MIDI data bytes are optional, depending on the MIDI status byte. When a series of messages have the same status byte, the status byte can be omitted from messages after the first one in the series, creating a running status. Pack a message for running status as follows:

High word	High-order byte	Not used.
	Low-order byte	Not used.
Low word	High-order byte	Contains a second byte of MIDI data (when needed).
	Low-order byte	Contains the first byte of MIDI data.
Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MIDIERR_BADOPENMODE	The application sent a message without a status byte to a stream handle.
MIDIERR_NOTREADY	The hardware is busy with other data.
MMSYSERR_INVALHANDLE	The specified device handle is invalid.
Remarks

This function is used to send any MIDI message except for system-exclusive or stream messages.

This function might not return until the message has been sent to the output device. You can send short messages while streams are playing on the same device (although you cannot use a running status in this case).


midiOutUnprepareHeader

The midiOutUnprepareHeader function cleans up the preparation performed by the midiOutPrepareHeader function.

MMRESULT midiOutUnprepareHeader(

HMIDIOUT hmo,
LPMIDIHDR lpMidiOutHdr,
UINT cbMidiOutHdr
);
Parameters

hmo

Handle of the MIDI output device. This parameter can also be the handle of a MIDI stream cast to HMIDIOUT.

lpMidiOutHdr

Address of a MIDIHDR structure identifying the buffer to be cleaned up.

cbMidiOutHdr

Size, in bytes, of the MIDIHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MIDIERR_STILLPLAYING	The buffer pointed to by lpMidiOutHdr is still in the queue.
MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_INVALPARAM	The specified pointer or structure is invalid.
Remarks

This function is complementary to the midiOutPrepareHeader function. You must call midiOutUnprepareHeader before freeing the buffer. After passing a buffer to the device driver with the midiOutLongMsg function, you must wait until the device driver is finished with the buffer before calling midiOutUnprepareHeader.

Unpreparing a buffer that has not been prepared has no effect, and the function returns MMSYSERR_NOERROR.

See Also

midiOutPrepareHeader, MIDIHDR, midiOutLongMsg


midiStreamClose

The midiStreamClose function closes an open MIDI stream.

MMRESULT midiStreamClose(

HMIDISTRM hStream
);
Parameters

hStream

Handle of a MIDI stream, as retrieved by using the midiStreamOpen function.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The specified device handle is invalid.
See Also

midiStreamOpen


midiStreamOpen

The midiStreamOpen function opens a MIDI stream for output. By default, the device is opened in paused mode. The stream handle retrieved by this function must be used in all subsequent references to the stream.

MMRESULT midiStreamOpen(

LPHMIDISTRM lphStream,
LPUINT puDeviceID,
DWORD cMidi,
DWORD dwCallback,
DWORD dwInstance,
DWORD fdwOpen
);
Parameters

lphStream

Address of a variable to contain the stream handle when the function returns.

puDeviceID

Address of a device identifier. The device is opened on behalf of the stream and closed again when the stream is closed.

cMidi

Reserved; must be 1.

dwCallback

Address of a callback function, an event handle, a thread identifier, or a handle of a window or thread called during MIDI playback to process messages related to the progress of the playback. If no callback mechanism is desired, specify NULL for this parameter.

dwInstance

Application-specific instance data that is returned to the application with every callback function.

fdwOpen

Callback flag for opening the device. One of the following callback flags must be specified:

CALLBACK_EVENT

The dwCallback parameter is an event handle. This callback mechanism is for output only.

CALLBACK_FUNCTION

The dwCallback parameter is a callback procedure address.

CALLBACK_NULL

There is no callback mechanism. This is the default setting.

CALLBACK_THREAD

The dwCallback parameter is a thread identifier.

CALLBACK_WINDOW

The dwCallback parameter is a window handle.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_BADDEVICEID	The specified device identifier is out of range.
MMSYSERR_INVALPARAM	The given handle or flags parameter is invalid.
MMSYSERR_NOMEM	The system is unable to allocate or lock memory.


midiStreamOut

The midiStreamOut function plays or queues a stream (buffer) of MIDI data to a MIDI output device.

MMRESULT midiStreamOut(

HMIDISTRM hMidiStream,
LPMIDIHDR lpMidiHdr,
UINT cbMidiHdr
);
Parameters

hMidiStream

Handle of a MIDI stream. This handle must have been returned by a call to the midiStreamOpen function. This handle identifies the output device.

lpMidiHdr

Address of a MIDIHDR structure that identifies the MIDI buffer.

cbMidiHdr

Size, in bytes, of the MIDIHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_NOMEM	The system is unable to allocate or lock memory.
MIDIERR_STILLPLAYING	The output buffer pointed to by lpMidiHdr is still playing or is queued from a previous call to midiStreamOut.
MIDIERR_UNPREPARED	The header pointed to by lpMidiHdr has not been prepared.
MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_INVALPARAM	The pointer specified by lpMidiHdr is invalid.
Remarks

Because the midiStreamOpen function opens the output device in paused mode, you must call the midiStreamRestart function before you can use midiStreamOut to start the playback.

For the current implementation of this function, the buffer must be smaller than 64K.

The buffer pointed to by the MIDIHDR structure contains one or more MIDI events, each of which is defined by a MIDIEVENT structure.

See Also

midiStreamOpen, MIDIHDR, MIDIEVENT


midiStreamPause

The midiStreamPause function pauses playback of a specified MIDI stream.

MMRESULT midiStreamPause(

HMIDISTRM hms
);
Parameters

hms

Handle of a MIDI stream. This handle must have been returned by a call to the MIDIEVENTfunction. This handle identifies the output device.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The specified device handle is invalid.
Remarks

The current playback position is saved when playback is paused. To resume playback from the current position, use the midiStreamRestart function.

Calling this function when the output is already paused has no effect, and the function returns MMSYSERR_NOERROR.

See Also

MIDIEVENT, midiStreamRestart


midiStreamPosition

The midiStreamPosition function retrieves the current position in a MIDI stream.

MMRESULT midiStreamPosition(

HMIDISTRM hms,
LPMMTIME pmmt,
UINT cbmmt
);
Parameters

hms

Handle of a MIDI stream. This handle must have been returned by a call to the midiStreamOpen function. This handle identifies the output device.

pmmt

Address of an MMTIME structure.

cbmmt

Size, in bytes, of the MMTIME structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_INVALPARAM	Specified pointer or structure is invalid.
Remarks

Before calling midiStreamPosition, set the wType member of the MMTIME structure to indicate the time format you desire. After calling midiStreamPosition, check the wType member to determine if the desired time format is supported. If the desired format is not supported, wType will specify an alternative format.

The position is set to zero when the device is opened or reset.

See Also

midiStreamOpen, MMTIME


midiStreamProperty

The midiStreamProperty function sets or retrieves properties of a MIDI data stream associated with a MIDI output device.

MMRESULT midiStreamProperty(

HMIDISTRM hm,
LPBYTE lppropdata,
DWORD dwProperty
);
Parameters

hm

Handle of the MIDI device that the property is associated with.

lppropdata

Address of the property data.

dwProperty

Flags that specify the action to perform and identify the appropriate property of the MIDI data stream. The midiStreamProperty function requires setting two flags in each use. One flag (either MIDIPROP_GET or MIDIPROP_SET) specifies an action, and the other identifies a specific property to examine or edit:

MIDIPROP_GET

Retrieves the current setting of the given property.

MIDIPROP_SET

Sets the given property.

MIDIPROP_TEMPO

Retrieves the tempo property. The lppropdata parameter points to a MIDIPROPTEMPO structure. The current tempo value can be retrieved at any time. Output devices set the tempo by inserting MEVT_TEMPO events into the MIDI data.

MIDIPROP_TIMEDIV

Specifies the time division property. You can get or set this property. The lppropdata parameter points to a MIDIPROPTIMEDIV structure. This property can be set only when the device is stopped.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The specified handle is not a stream handle.
MMSYSERR_INVALPARAM	The given handle or flags parameter is invalid.
Remarks

These properties are the default properties defined by the system. Driver writers can implement and document their own properties.

See Also

MIDIPROPTEMPO, MIDIPROPTIMEDIV


midiStreamRestart

The midiStreamRestart function restarts a paused MIDI stream.

MMRESULT midiStreamRestart(

HMIDISTRM hms
);
Parameters

hms

Handle of a MIDI stream. This handle must have been returned by a call to the midiStreamOpen function. This handle identifies the output device.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The specified device handle is invalid.
Remarks

Calling this function when the output is not paused has no effect, and the function returns MMSYSERR_NOERROR.

See Also

midiStreamOpen


midiStreamStop

The midiStreamStop function turns off all notes on all MIDI channels for the specified MIDI output device.

MMRESULT midiStreamStop(

HMIDISTRM hms
);
Parameters

hms

Handle of a MIDI stream. This handle must have been returned by a call to the midiStreamOpen function. This handle identifies the output device.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The specified device handle is invalid.
Remarks

When you call this function, any pending system-exclusive or stream output buffers are returned to the callback mechanism and the MHDR_DONE bit is set in the dwFlags member of the MIDIHDR structure.

While the midiOutReset function turns off all notes, midiStreamStop turns off only those notes that have been turned on by a MIDI note-on message.

See Also

midiStreamOpen, MIDIHDR, midiOutReset


mixerClose

The mixerClose function closes the specified mixer device.

MMRESULT mixerClose(

HMIXER hmx
);
Parameters

hmx

Handle of the mixer device. This handle must have been returned successfully by the mixerOpen function. If mixerClose is successful, hmx is no longer valid.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
See Also

mixerOpen


mixerGetControlDetails

The mixerGetControlDetails function retrieves details about a single control associated with an audio line.

MMRESULT mixerGetControlDetails(

HMIXEROBJ hmxobj,
LPMIXERCONTROLDETAILS pmxcd,
DWORD fdwDetails
);
Parameters

hmxobj

Handle of the mixer device object being queried.

pmxcd

Address of a MIXERCONTROLDETAILS structure, which is filled with state information about the control.

fdwDetails

Flags for retrieving control details. The following values are defined:

MIXER_GETCONTROLDETAILSF_LISTTEXT

The paDetails member of the MIXERCONTROLDETAILS structure points to one or more MIXERCONTROLDETAILS_LISTTEXT structures to receive text labels for multiple-item controls. An application must get all list text items for a multiple-item control at once. This flag cannot be used with MIXERCONTROL_CONTROLTYPE_CUSTOM controls.

MIXER_GETCONTROLDETAILSF_VALUE

Current values for a control are retrieved. The paDetails member of the MIXERCONTROLDETAILS structure points to one or more details structures appropriate for the control class.

MIXER_OBJECTF_AUX

The hmxobj parameter is an auxiliary device identifier in the range of zero to one less than the number of devices returned by the auxGetNumDevs function.

MIXER_OBJECTF_HMIDIIN

The hmxobj parameter is the handle of a MIDI (Musical Instrument Digital Interface) input device. This handle must have been returned by the midiInOpen function.

MIXER_OBJECTF_HMIDIOUT

The hmxobj parameter is the handle of a MIDI output device. This handle must have been returned by the midiOutOpen function.

MIXER_OBJECTF_HMIXER

The hmxobj parameter is a mixer device handle returned by the mixerOpen function. This flag is optional.

MIXER_OBJECTF_HWAVEIN

The hmxobj parameter is a waveform-audio input handle returned by the waveInOpen function.

MIXER_OBJECTF_HWAVEOUT

The hmxobj parameter is a waveform-audio output handle returned by the waveOutOpen function.

MIXER_OBJECTF_MIDIIN

The hmxobj parameter is the identifier of a MIDI input device. This identifier must be in the range of zero to one less than the number of devices returned by the midiInGetNumDevs function.

MIXER_OBJECTF_MIDIOUT

The hmxobj parameter is the identifier of a MIDI output device. This identifier must be in the range of zero to one less than the number of devices returned by the midiOutGetNumDevs function.

MIXER_OBJECTF_MIXER

The hmxobj parameter is the identifier of a mixer device in the range of zero to one less than the number of devices returned by the mixerGetNumDevs function. This flag is optional.

MIXER_OBJECTF_WAVEIN

The hmxobj parameter is the identifier of a waveform-audio input device in the range of zero to one less than the number of devices returned by the waveInGetNumDevs function.

MIXER_OBJECTF_WAVEOUT

The hmxobj parameter is the identifier of a waveform-audio output device in the range of zero to one less than the number of devices returned by the waveOutGetNumDevs function.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MIXERR_INVALCONTROL	The control reference is invalid.
MMSYSERR_BADDEVICEID	The hmxobj parameter specifies an invalid device identifier.
MMSYSERR_INVALFLAG	One or more flags are invalid.
MMSYSERR_INVALHANDLE	The hmxobj parameter specifies an invalid handle.
MMSYSERR_INVALPARAM	One or more parameters are invalid.
MMSYSERR_NODRIVER	No mixer device is available for the object specified by hmxobj.
Remarks

All members of the MIXERCONTROLDETAILS structure must be initialized before calling this function.

See Also

MIXERCONTROLDETAILS, MIXERCONTROLDETAILS_LISTTEXT, auxGetNumDevs, midiInOpen, midiOutOpen, mixerOpen, waveInOpen, waveOutOpen, midiInGetNumDevs, midiOutGetNumDevs, mixerGetNumDevs, waveInGetNumDevs, waveOutGetNumDevs


mixerGetDevCaps

The mixerGetDevCaps function queries a specified mixer device to determine its capabilities.

MMRESULT mixerGetDevCaps(

UINT uMxId,
LPMIXERCAPS pmxcaps,
UINT cbmxcaps
);
Parameters

uMxId

Identifier or handle of an open mixer device.

pmxcaps

Address of a MIXERCAPS structure that receives information about the capabilities of the device.

cbmxcaps

Size, in bytes, of the MIXERCAPS structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_BADDEVICEID	The specified device identifier is out of range.
MMSYSERR_INVALHANDLE	The mixer device handle is invalid.
MMSYSERR_INVALPARAM	One or more parameters are invalid.
Remarks

Use the mixerGetNumDevs function to determine the number of mixer devices present in the system. The device identifier specified by uMxId varies from zero to one less than the number of mixer devices present.

Only the number of bytes (or less) of information specified in cbmxcaps is copied to the location pointed to by pmxcaps. If cbmxcaps is zero, nothing is copied, and the function returns successfully.

This function also accepts a mixer device handle returned by the mixerOpen function as the uMxId parameter. The application should cast the HMIXER handle to a UINT.

See Also

MIXERCAPS, mixerGetNumDevs, mixerOpen


mixerGetID

The mixerGetID function retrieves the device identifier for a mixer device associated with a specified device handle.

MMRESULT mixerGetID(

HMIXEROBJ hmxobj,
UINT * puMxId,
DWORD fdwId
);
Parameters

hmxobj

Handle of the audio mixer object to map to a mixer device identifier.

puMxId

Address of a variable that receives the mixer device identifier. If no mixer device is available for the hmxobj object, the value − 1 is placed in this location and the MMSYSERR_NODRIVER error value is returned.

fdwId

Flags for mapping the mixer object hmxobj. The following values are defined:

MIXER_OBJECTF_AUX

The hmxobj parameter is an auxiliary device identifier in the range of zero to one less than the number of devices returned by the auxGetNumDevs function.

MIXER_OBJECTF_HMIDIIN

The hmxobj parameter is the handle of a MIDI input device. This handle must have been returned by the midiInOpen function.

MIXER_OBJECTF_HMIDIOUT

The hmxobj parameter is the handle of a MIDI output device. This handle must have been returned by the midiOutOpen function.

MIXER_OBJECTF_HMIXER

The hmxobj parameter is a mixer device handle returned by the mixerOpen function. This flag is optional.

MIXER_OBJECTF_HWAVEIN

The hmxobj parameter is a waveform-audio input handle returned by the waveInOpen function.

MIXER_OBJECTF_HWAVEOUT

The hmxobj parameter is a waveform-audio output handle returned by the waveOutOpen function.

MIXER_OBJECTF_MIDIIN

The hmxobj parameter is the identifier of a MIDI input device. This identifier must be in the range of zero to one less than the number of devices returned by the midiInGetNumDevs function.

MIXER_OBJECTF_MIDIOUT

The hmxobj parameter is the identifier of a MIDI output device. This identifier must be in the range of zero to one less than the number of devices returned by the midiOutGetNumDevs function.

MIXER_OBJECTF_MIXER

The hmxobj parameter is the identifier of a mixer device in the range of zero to one less than the number of devices returned by the mixerGetNumDevs function. This flag is optional.

MIXER_OBJECTF_WAVEIN

The hmxobj parameter is the identifier of a waveform-audio input device in the range of zero to one less than the number of devices returned by the waveInGetNumDevs function.

MIXER_OBJECTF_WAVEOUT

The hmxobj parameter is the identifier of a waveform-audio output device in the range of zero to one less than the number of devices returned by the waveOutGetNumDevs function.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_BADDEVICEID	The hmxobj parameter specifies an invalid device identifier.
MMSYSERR_INVALFLAG	One or more flags are invalid.
MMSYSERR_INVALHANDLE	The hmxobj parameter specifies an invalid handle.
MMSYSERR_INVALPARAM	One or more parameters are invalid.
MMSYSERR_NODRIVER	No audio mixer device is available for the object specified by hmxobj. The location referenced by puMxId also contains the value −1.
See Also

auxGetNumDevs, midiInOpen, midiOutOpen, mixerOpen, waveInOpen, waveOutOpen, midiInGetNumDevs, midiOutGetNumDevs, mixerGetNumDevs,  waveInGetNumDevs, waveOutGetNumDevs


mixerGetLineControls

The mixerGetLineControls function retrieves one or more controls associated with an audio line.

MMRESULT mixerGetLineControls(

HMIXEROBJ hmxobj,
LPMIXERLINECONTROLS pmxlc,
DWORD fdwControls
);
Parameters

hmxobj

Handle of the mixer device object that is being queried.

pmxlc

Address of a MIXERLINECONTROLS structure. This structure is used to reference one or more MIXERCONTROL structures to be filled with information about the controls associated with an audio line. The cbStruct member of the MIXERLINECONTROLS structure must always be initialized to be the size, in bytes, of the MIXERLINECONTROLS structure.

fdwControls

Flags for retrieving information about one or more controls associated with an audio line. The following values are defined:

MIXER_GETLINECONTROLSF_ALL

The pmxlc parameter references a list of MIXERCONTROL structures that will receive information on all controls associated with the audio line identified by the dwLineID member of the MIXERLINECONTROLS structure. The cControls member must be initialized to the number of controls associated with the line. This number is retrieved from the cControls member of the MIXERLINE structure returned by the mixerGetLineInfo function. The cbmxctrl member must be initialized to the size, in bytes, of a single MIXERCONTROL structure. The pamxctrl member must point to the first MIXERCONTROL structure to be filled. The dwControlID and dwControlType members are ignored for this query.

MIXER_GETLINECONTROLSF_ONEBYID

The pmxlc parameter references a single MIXERCONTROL structure that will receive information on the control identified by the dwControlID member of the MIXERLINECONTROLS structure. The cControls member must be initialized to 1. The cbmxctrl member must be initialized to the size, in bytes, of a single MIXERCONTROL structure. The pamxctrl member must point to a MIXERCONTROL structure to be filled. The dwLineID and dwControlType members are ignored for this query. This query is usually used to refresh a control after receiving a MM_MIXM_CONTROL_CHANGE control change notification message by the user-defined callback (see mixerOpen).

MIXER_GETLINECONTROLSF_ONEBYTYPE

The mixerGetLineControls function retrieves information about the first control of a specific class for the audio line that is being queried. The pmxlc parameter references a single MIXERCONTROL structure that will receive information about the specific control. The audio line is identified by the dwLineID member. The control class is specified in the dwControlType member of the MIXERLINECONTROLS structure.

The dwControlID member is ignored for this query. This query can be used by an application to get information on a single control associated with a line. For example, you might want your application to use a peak meter only from a waveform-audio output line.

MIXER_OBJECTF_AUX

The hmxobj parameter is an auxiliary device identifier in the range of zero to one less than the number of devices returned by the auxGetNumDevs function.

MIXER_OBJECTF_HMIDIIN

The hmxobj parameter is the handle of a MIDI input device. This handle must have been returned by the midiInOpen function.

MIXER_OBJECTF_HMIDIOUT

The hmxobj parameter is the handle of a MIDI output device. This handle must have been returned by the midiOutOpen function.

MIXER_OBJECTF_HMIXER

The hmxobj parameter is a mixer device handle returned by the mixerOpen function. This flag is optional.

MIXER_OBJECTF_HWAVEIN

The hmxobj parameter is a waveform-audio input handle returned by the waveInOpen function.

MIXER_OBJECTF_HWAVEOUT

The hmxobj parameter is a waveform-audio output handle returned by the waveOutOpen function.

MIXER_OBJECTF_MIDIIN

The hmxobj parameter is the identifier of a MIDI input device. This identifier must be in the range of zero to one less than the number of devices returned by the midiInGetNumDevs function.

MIXER_OBJECTF_MIDIOUT

The hmxobj parameter is the identifier of a MIDI output device. This identifier must be in the range of zero to one less than the number of devices returned by the midiOutGetNumDevs function.

MIXER_OBJECTF_MIXER

The hmxobj parameter is the identifier of a mixer device in the range of zero to one less than the number of devices returned by the mixerGetNumDevs function. This flag is optional.

MIXER_OBJECTF_WAVEIN

The hmxobj parameter is the identifier of a waveform-audio input device in the range of zero to one less than the number of devices returned by the waveInGetNumDevs function.

MIXER_OBJECTF_WAVEOUT

The hmxobj parameter is the identifier of a waveform-audio output device in the range of zero to one less than the number of devices returned by the waveOutGetNumDevs function.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MIXERR_INVALCONTROL	The control reference is invalid.
MIXERR_INVALLINE	The audio line reference is invalid.
MMSYSERR_BADDEVICEID	The hmxobj parameter specifies an invalid device identifier.
MMSYSERR_INVALFLAG	One or more flags are invalid.
MMSYSERR_INVALHANDLE	The hmxobj parameter specifies an invalid handle.
MMSYSERR_INVALPARAM	One or more parameters are invalid.
MMSYSERR_NODRIVER	No mixer device is available for the object specified by hmxobj.
See Also

MIXERLINECONTROLS, MIXERCONTROL, MIXERLINE, mixerGetLineInfo, MM_MIXM_CONTROL_CHANGE, mixerOpen, auxGetNumDevs, midiInOpen, midiOutOpen, waveInOpen, waveOutOpen, midiInGetNumDevs, midiOutGetNumDevs, mixerGetNumDevs, waveInGetNumDevs, waveOutGetNumDevs


mixerGetLineInfo

The mixerGetLineInfo function retrieves information about a specific line of a mixer device.

MMRESULT mixerGetLineInfo(

HMIXEROBJ hmxobj,
LPMIXERLINE pmxl,
DWORD fdwInfo
);
Parameters

hmxobj

Handle of the mixer device object that controls the specific audio line.

pmxl

Address of a MIXERLINE structure. This structure is filled with information about the audio line for the mixer device. The cbStruct member must always be initialized to be the size, in bytes, of the MIXERLINE structure.

fdwInfo

Flags for retrieving information about an audio line. The following values are defined:

MIXER_GETLINEINFOF_COMPONENTTYPE

The pmxl parameter will receive information about the first audio line of the type specified in the dwComponentType member of the MIXERLINE structure. This flag is used to retrieve information about an audio line of a specific component type. Remaining structure members except cbStruct require no further initialization.

MIXER_GETLINEINFOF_DESTINATION

The pmxl parameter will receive information about the destination audio line specified by the dwDestination member of the MIXERLINE structure. This index ranges from zero to one less than the value in the cDestinations member of the MIXERCAPS structure. All remaining structure members except cbStruct require no further initialization.

MIXER_GETLINEINFOF_LINEID

The pmxl parameter will receive information about the audio line specified by the dwLineID member of the MIXERLINE structure. This is usually used to retrieve updated information about the state of an audio line. All remaining structure members except cbStruct require no further initialization.

MIXER_GETLINEINFOF_SOURCE

The pmxl parameter will receive information about the source audio line specified by the dwDestination and dwSource members of the MIXERLINE structure. The index specified by dwDestination ranges from zero to one less than the value in the cDestinations member of the MIXERCAPS structure. The index specified by dwSource ranges from zero to one less than the value in the cConnections member of the MIXERLINE structure returned for the audio line stored in the dwDestination member. All remaining structure members except cbStruct require no further initialization.

MIXER_GETLINEINFOF_TARGETTYPE

The pmxl parameter will receive information about the audio line that is for the dwType member of the Target structure, which is a member of the MIXERLINE structure. This flag is used to retrieve information about an audio line that handles the target type (for example, MIXERLINE_TARGETTYPE_WAVEOUT). An application must initialize the dwType, wMid, wPid, vDriverVersion and szPname members of the MIXERLINE structure before calling mixerGetLineInfo. All of these values can be retrieved from the device capabilities structures for all media devices. Remaining structure members except cbStruct require no further initialization.

MIXER_OBJECTF_AUX

The hmxobj parameter is an auxiliary device identifier in the range of zero to one less than the number of devices returned by the auxGetNumDevs function.

MIXER_OBJECTF_HMIDIIN

The hmxobj parameter is the handle of a MIDI input device. This handle must have been returned by the midiInOpen function.

MIXER_OBJECTF_HMIDIOUT

The hmxobj parameter is the handle of a MIDI output device. This handle must have been returned by the midiOutOpen function.

MIXER_OBJECTF_HMIXER

The hmxobj parameter is a mixer device handle returned by the mixerOpen function. This flag is optional.

MIXER_OBJECTF_HWAVEIN

The hmxobj parameter is a waveform-audio input handle returned by the waveInOpen function.

MIXER_OBJECTF_HWAVEOUT

The hmxobj parameter is a waveform-audio output handle returned by the waveOutOpen function.

MIXER_OBJECTF_MIDIIN

The hmxobj parameter is the identifier of a MIDI input device. This identifier must be in the range of zero to one less than the number of devices returned by the midiInGetNumDevs function.

MIXER_OBJECTF_MIDIOUT

The hmxobj parameter is the identifier of a MIDI output device. This identifier must be in the range of zero to one less than the number of devices returned by the midiOutGetNumDevs function.

MIXER_OBJECTF_MIXER

The hmxobj parameter is a mixer device identifier in the range of zero to one less than the number of devices returned by the mixerGetNumDevs function. This flag is optional.

MIXER_OBJECTF_WAVEIN

The hmxobj parameter is the identifier of a waveform-audio input device in the range of zero to one less than the number of devices returned by the waveInGetNumDevs function.

MIXER_OBJECTF_WAVEOUT

The hmxobj parameter is the identifier of a waveform-audio output device in the range of zero to one less than the number of devices returned by the waveOutGetNumDevs function.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MIXERR_INVALLINE	The audio line reference is invalid.
MMSYSERR_BADDEVICEID	The hmxobj parameter specifies an invalid device identifier.
MMSYSERR_INVALFLAG	One or more flags are invalid.
MMSYSERR_INVALHANDLE	The hmxobj parameter specifies an invalid handle.
MMSYSERR_INVALPARAM	One or more parameters are invalid.
MMSYSERR_NODRIVER	No mixer device is available for the object specified by hmxobj.
See Also

MIXERLINE, MIXERCAPS, auxGetNumDevs, midiInOpen, midiOutOpen, mixerOpen, waveInOpen, waveOutOpen, midiInGetNumDevs, midiOutGetNumDevs, mixerGetNumDevs, waveInGetNumDevs, waveOutGetNumDevs


mixerGetNumDevs

The mixerGetNumDevs function retrieves the number of mixer devices present in the system.

UINT mixerGetNumDevs(VOID);

Parameters

This function takes no parameters.

Return Values

Returns the number of mixer devices or zero if no mixer devices are available.


mixerMessage

The mixerMessage function sends a custom mixer driver message directly to a mixer driver.

DWORD mixerMessage(

HMIXER hmx,
UINT uMsg,
DWORD dwParam1,
DWORD dwParam2
);
Parameters

hmx

Handle of an open instance of a mixer device. This handle is returned by the mixerOpen function.

uMsg

Custom mixer driver message to send to the mixer driver. This message must be above or equal to the MXDM_USER constant.

dwParam1 and dwParam2

Arguments associated with the message being sent.

Return Values

Returns a value that is specific to the custom mixer driver message. Possible error values include the following:

MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_INVALPARAM	The uMsg parameter specified in the MXDM_USER message is invalid.
MMSYSERR_NOTSUPPORTED	The mixer device did not process the message.
Remarks

User-defined messages must be sent only to a mixer driver that supports the messages. The application should verify that the mixer driver is the driver that supports the message by retrieving the mixer capabilities and checking the wMid, wPid, vDriverVersion, and szPname members of the MIXERCAPS structure.

See Also

mixerOpen, MIXERCAPS


mixerOpen

The mixerOpen function opens a specified mixer device and ensures that the device will not be removed until the application closes the handle.

MMRESULT mixerOpen(

LPHMIXER phmx,
UINT uMxId,
DWORD dwCallback,
DWORD dwInstance,
DWORD fdwOpen
);
Parameters

phmx

Address of a variable that will receive a handle identifying the opened mixer device. Use this handle to identify the device when calling other audio mixer functions. This parameter cannot be NULL.

uMxId

Identifier of the mixer device to open. Use a valid device identifier or any HMIXEROBJ (see the mixerGetID function for a description of mixer object handles). A “mapper” for audio mixer devices does not currently exist, so a mixer device identifier of − 1 is not valid.

dwCallback

Handle of a window called when the state of an audio line and/or control associated with the device being opened is changed. Specify zero for this parameter if no callback mechanism is to be used.

dwInstance

User instance data passed to the callback function. This parameter is not used with window callback functions.

fdwOpen

Flags for opening the device. The following values are defined:

CALLBACK_WINDOW

The dwCallback parameter is assumed to be a window handle.

MIXER_OBJECTF_AUX

The uMxId parameter is an auxiliary device identifier in the range of zero to one less than the number of devices returned by the auxGetNumDevs function.

MIXER_OBJECTF_HMIDIIN

The uMxId parameter is the handle of a MIDI input device. This handle must have been returned by the midiInOpen function.

MIXER_OBJECTF_HMIDIOUT

The uMxId parameter is the handle of a MIDI output device. This handle must have been returned by the midiOutOpen function.

MIXER_OBJECTF_HMIXER

The uMxId parameter is a mixer device handle returned by the mixerOpen function. This flag is optional.

MIXER_OBJECTF_HWAVEIN

The uMxId parameter is a waveform-audio input handle returned by the waveInOpen function.

MIXER_OBJECTF_HWAVEOUT

The uMxId parameter is a waveform-audio output handle returned by the waveOutOpen function.

MIXER_OBJECTF_MIDIIN

The uMxId parameter is the identifier of a MIDI input device. This identifier must be in the range of zero to one less than the number of devices returned by the midiInGetNumDevs function.

MIXER_OBJECTF_MIDIOUT

The uMxId parameter is the identifier of a MIDI output device. This identifier must be in the range of zero to one less than the number of devices returned by the midiOutGetNumDevs function.

MIXER_OBJECTF_MIXER

The uMxId parameter is a mixer device identifier in the range of zero to one less than the number of devices returned by the mixerGetNumDevs function. This flag is optional.

MIXER_OBJECTF_WAVEIN

The uMxId parameter is the identifier of a waveform-audio input device in the range of zero to one less than the number of devices returned by the waveInGetNumDevs function.

MIXER_OBJECTF_WAVEOUT

The uMxId parameter is the identifier of a waveform-audio output device in the range of zero to one less than the number of devices returned by the waveOutGetNumDevs function.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_ALLOCATED	The specified resource is already allocated by the maximum number of clients possible.
MMSYSERR_BADDEVICEID	The uMxId parameter specifies an invalid device identifier.
MMSYSERR_INVALFLAG	One or more flags are invalid.
MMSYSERR_INVALHANDLE	The uMxId parameter specifies an invalid handle.
MMSYSERR_INVALPARAM	One or more parameters are invalid.
MMSYSERR_NODRIVER	No mixer device is available for the object specified by uMxId. Note that the location referenced by uMxId will also contain the value  − 1.
MMSYSERR_NOMEM	Unable to allocate resources.
Remarks

Use the mixerGetNumDevs function to determine the number of audio mixer devices present in the system. The device identifier specified by uMxId varies from zero to one less than the number of devices present.

If a window is chosen to receive callback information, the MM_MIXM_LINE_CHANGE and MM_MIXM_CONTROL_CHANGE messages are sent to the window procedure function to indicate when an audio line or control state changes. For both messages, the wParam parameter is the handle of the mixer device. The lParam parameter is the line identifier for MM_MIXM_LINE_CHANGE or the control identifier for MM_MIXM_CONTROL_CHANGE that changed state.

To query for audio mixer support or a media device, use the mixerGetID function.

See Also

mixerGetID, auxGetNumDevs, midiInOpen, midiOutOpen, waveInOpen, waveOutOpen, midiInGetNumDevs, midiOutGetNumDevs, mixerGetNumDevs, waveInGetNumDevs, waveOutGetNumDevs, MM_MIXM_LINE_CHANGE, MM_MIXM_CONTROL_CHANGE


mixerSetControlDetails

The mixerSetControlDetails function sets properties of a single control associated with an audio line.

MMRESULT mixerSetControlDetails(

HMIXEROBJ hmxobj,
LPMIXERCONTROLDETAILS pmxcd,
DWORD fdwDetails
);
Parameters

hmxobj

Handle of the mixer device object for which properties are being set.

pmxcd

Address of a MIXERCONTROLDETAILS structure. This structure is used to reference control detail structures that contain the desired state for the control.

fdwDetails

Flags for setting properties for a control. The following values are defined:

MIXER_OBJECTF_AUX

The hmxobj parameter is an auxiliary device identifier in the range of zero to one less than the number of devices returned by the auxGetNumDevs function.

MIXER_OBJECTF_HMIDIIN

The hmxobj parameter is the handle of a MIDI input device. This handle must have been returned by the midiInOpen function.

MIXER_OBJECTF_HMIDIOUT

The hmxobj parameter is the handle of a MIDI output device. This handle must have been returned by the midiOutOpen function.

MIXER_OBJECTF_HMIXER

The hmxobj parameter is a mixer device handle returned by the mixerOpen function. This flag is optional.

MIXER_OBJECTF_HWAVEIN

The hmxobj parameter is a waveform-audio input handle returned by the waveInOpen function.

MIXER_OBJECTF_HWAVEOUT

The hmxobj parameter is a waveform-audio output handle returned by the waveOutOpen function.

MIXER_OBJECTF_MIDIIN

The hmxobj parameter is the identifier of a MIDI input device. This identifier must be in the range of zero to one less than the number of devices returned by the midiInGetNumDevs function.

MIXER_OBJECTF_MIDIOUT

The hmxobj parameter is the identifier of a MIDI output device. This identifier must be in the range of zero to one less than the number of devices returned by the midiOutGetNumDevs function.

MIXER_OBJECTF_MIXER

The hmxobj parameter is a mixer device identifier in the range of zero to one less than the number of devices returned by the mixerGetNumDevs function. This flag is optional.

MIXER_OBJECTF_WAVEIN

The hmxobj parameter is the identifier of a waveform-audio input device in the range of zero to one less than the number of devices returned by the waveInGetNumDevs function.

MIXER_OBJECTF_WAVEOUT

The hmxobj parameter is the identifier of a waveform-audio output device in the range of zero to one less than the number of devices returned by the waveOutGetNumDevs function.

MIXER_SETCONTROLDETAILSF_CUSTOM

A custom dialog box for the specified custom mixer control is displayed. The mixer device gathers the required information from the user and returns the data in the specified buffer. The handle for the owning window is specified in the hwndOwner member of the MIXERCONTROLDETAILS structure. (This handle can be set to NULL.) The application can then save the data from the dialog box and use it later to reset the control to the same state by using the MIXER_SETCONTROLDETAILSF_VALUE flag.

MIXER_SETCONTROLDETAILSF_VALUE

The current value(s) for a control are set. The paDetails member of the MIXERCONTROLDETAILS structure points to one or more mixer-control details structures of the appropriate class for the control.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MIXERR_INVALCONTROL	The control reference is invalid.
MMSYSERR_BADDEVICEID	The hmxobj parameter specifies an invalid device identifier.
MMSYSERR_INVALFLAG	One or more flags are invalid.
MMSYSERR_INVALHANDLE	The hmxobj parameter specifies an invalid handle.
MMSYSERR_INVALPARAM	One or more parameters are invalid.
MMSYSERR_NODRIVER	No mixer device is available for the object specified by hmxobj.
Remarks

All members of the MIXERCONTROLDETAILS structure must be initialized before calling mixerSetControlDetails.

If an application needs to retrieve only the current state of a custom mixer control and not display a dialog box, then mixerGetControlDetails can be used with the MIXER_GETCONTROLDETAILSF_VALUE flag.

See Also

MIXERCONTROLDETAILS, auxGetNumDevs, midiInOpen, midiOutOpen, mixerOpen, waveInOpen, waveOutOpen, midiInGetNumDevs, midiOutGetNumDevs, mixerGetNumDevs, waveInGetNumDevs, waveOutGetNumDevs, mixerGetControlDetails


mmioAdvance

The mmioAdvance function advances the I/O buffer of a file set up for direct I/O buffer access with the mmioGetInfo function.

MMRESULT mmioAdvance(

HMMIO hmmio,
LPMMIOINFO lpmmioinfo,
UINT wFlags
);
Parameters

hmmio

File handle of a file opened by using the mmioOpen function.

lpmmioinfo

Address of the MMIOINFO structure obtained by using the mmioGetInfo function. This structure is used to set the current file information, and then it is updated after the buffer is advanced. This parameter is optional.

wFlags

Flags for the operation. It can be one of the following:

MMIO_READ

Buffer is filled from the file.

MMIO_WRITE

Buffer is written to the file.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMIOERR_CANNOTEXPAND	The specified memory file cannot be expanded, probably because the adwInfo member of the MMIOINFO structure was set to zero in the initial call to the mmioOpen function.
MMIOERR_CANNOTREAD	An error occurred while refilling the buffer.
MMIOERR_CANNOTWRITE	The contents of the buffer could not be written to disk.
MMIOERR_OUTOFMEMORY	There was not enough memory to expand a memory file for further writing.
MMIOERR_UNBUFFERED	The specified file is not opened for buffered I/O.
Remarks

If the file is opened for reading, the I/O buffer is filled from the disk. If the file is opened for writing and the MMIO_DIRTY flag is set in the dwFlags member of the MMIOINFO structure, the buffer is written to disk. The pchNext, pchEndRead, and pchEndWrite members of the MMIOINFO structure are updated to reflect the new state of the I/O buffer.

If the specified file is opened for writing or for both reading and writing, the I/O buffer is flushed to disk before the next buffer is read. If the I/O buffer cannot be written to disk because the disk is full, mmioAdvance returns MMIOERR_CANNOTWRITE.

If the specified file is open only for writing, the MMIO_WRITE flag must be specified.

If you have written to the I/O buffer, you must set the MMIO_DIRTY flag in the dwFlags member of the MMIOINFO structure before calling mmioAdvance. Otherwise, the buffer will not be written to disk.

If the end of file is reached, mmioAdvance still returns successfully even though no more data can be read. To check for the end of the file, check if the pchNext and pchEndRead members of the MMIOINFO structure are equal after calling mmioAdvance.

See Also

mmioGetInfo, mmioOpen, MMIOINFO


mmioAscend

The mmioAscend function ascends out of a chunk in a RIFF file descended into with the mmioDescend function or created with the mmioCreateChunk function.

MMRESULT mmioAscend(

HMMIO hmmio,
LPMMCKINFO lpck,
UINT wFlags
);
Parameters

hmmio

File handle of an open RIFF file.

lpck

Address of an application-defined MMCKINFO structure previously filled by the mmioDescend or mmioCreateChunk function.

wFlags

Reserved; must be zero.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMIOERR_CANNOTSEEK	There was an error while seeking to the end of the chunk.
MMIOERR_CANNOTWRITE	The contents of the buffer could not be written to disk.
Remarks

If the chunk was descended into by using mmioDescend, mmioAscend seeks to the location following the end of the chunk (past the extra pad byte, if any).

If the chunk was created and descended into by using mmioCreateChunk, or if the MMIO_DIRTY flag is set in the dwFlags member of the MMCKINFO structure referenced by lpck, the current file position is assumed to be the end of the data portion of the chunk. If the chunk size is not the same as the value stored in the cksize member of the MMCKINFO structure when mmioCreateChunk was called, mmioAscend corrects the chunk size in the file before ascending from the chunk. If the chunk size is odd, mmioAscend writes a null pad byte at the end of the chunk. After ascending from the chunk, the current file position is the location following the end of the chunk (past the extra pad byte, if any).

See Also

mmioDescend, mmioCreateChunk, MMCKINFO


mmioClose

The mmioClose function closes a file that was opened by using the mmioOpen function.

MMRESULT mmioClose(

HMMIO hmmio,
UINT wFlags
);
Parameters

hmmio

File handle of the file to close.

wFlags

Flags for the close operation. The following value is defined:

MMIO_FHOPEN

If the file was opened by passing a file handle whose type is not HMMIO, using this flag tells the mmioClose function to close the multimedia file handle, but not the standard file handle.

Return Values

Returns zero if successful or an error otherwise. The error value can originate from the mmioFlush function or from the I/O procedure. Possible error values include the following:

MMIOERR_CANNOTWRITE	The contents of the buffer could not be written to disk.
See Also

mmioOpen, mmioFlush


mmioCreateChunk

The mmioCreateChunk function creates a chunk in a RIFF file that was opened by using the mmioOpen function. The new chunk is created at the current file position. After the new chunk is created, the current file position is the beginning of the data portion of the new chunk.

MMRESULT mmioCreateChunk(

HMMIO hmmio,
LPMMCKINFO lpck,
UINT wFlags
);
Parameters

hmmio

File handle of an open RIFF file.

lpck

Address an application-defined MMCKINFO structure containing information about the chunk to be created.

wFlags

Flags identifying what type of chunk to create. The following values are defined:

MMIO_CREATELIST

“LIST” chunk.

MMIO_CREATERIFF

“RIFF” chunk.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMIOERR_CANNOTSEEK	Unable to determine offset of the data portion of the chunk.
MMIOERR_CANNOTWRITE	Unable to write the chunk header.
Remarks

This function cannot insert a chunk into the middle of a file. If an application attempts to create a chunk somewhere other than at the end of a file, mmioCreateChunk overwrites existing information in the file.

The MMCKINFO structure pointed to by the lpck parameter should be set up as follows:

•	The ckid member specifies the chunk identifier. If wFlags includes MMIO_CREATERIFF or MMIO_CREATELIST, this member will be filled by mmioCreateChunk.

•	The cksize member specifies the size of the data portion of the chunk, including the form type or list type (if any). If this value is not correct when the mmioAscend function is called to mark the end of the chunk, mmioAscend corrects the chunk size.

•	The fccType member specifies the form type or list type if the chunk is a “RIFF” or “LIST” chunk. If the chunk is not a “RIFF” or “LIST” chunk, this member does not need to be filled in.

•	The dwDataOffset member does not need to be filled in. The mmioCreateChunk function fills this member with the file offset of the data portion of the chunk.

•	The dwFlags member does not need to be filled in. The mmioCreateChunk function sets the MMIO_DIRTY flag in dwFlags.

See Also

mmioOpen, MMCKINFO, mmioAscend


mmioDescend

The mmioDescend function descends into a chunk of a RIFF file that was opened by using the mmioOpen function. It can also search for a given chunk.

MMRESULT mmioDescend(

HMMIO hmmio,
LPMMCKINFO lpck,
LPMMCKINFO lpckParent,
UINT wFlags
);
Parameters

hmmio

File handle of an open RIFF file.

lpck

Address an application-defined MMCKINFO structure.

lpckParent

Address of an optional application-defined MMCKINFO structure identifying the parent of the chunk being searched for. If this parameter is not NULL, mmioDescend assumes the MMCKINFO structure it refers to was filled when mmioDescend was called to descend into the parent chunk, and mmioDescend searches for a chunk within the parent chunk. Set this parameter to NULL if no parent chunk is being specified.

wFlags

Search flags. If no flags are specified, mmioDescend descends into the chunk beginning at the current file position. The following values are defined:

MMIO_FINDCHUNK

Searches for a chunk with the specified chunk identifier.

MMIO_FINDLIST

Searches for a chunk with the chunk identifier “LIST” and with the specified form type.

MMIO_FINDRIFF

Searches for a chunk with the chunk identifier “RIFF” and with the specified form type.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMIOERR_CHUNKNOTFOUND	The end of the file (or the end of the parent chunk, if given) was reached before the desired chunk was found.
Remarks

A “RIFF” chunk consists of a four-byte chunk identifier (type FOURCC), followed by a four-byte chunk size (type DWORD), followed by the data portion of the chunk, followed by a null pad byte if the size of the data portion is odd. If the chunk identifier is “RIFF” or “LIST”, the first four bytes of the data portion of the chunk are a form type or list type (type FOURCC).

If you use mmioDescend to search for a chunk, make sure the file position is at the beginning of a chunk before calling the function. The search begins at the current file position and continues to the end of the file. If a parent chunk is specified, the file position should be somewhere within the parent chunk before calling mmioDescend. In this case, the search begins at the current file position and continues to the end of the parent chunk.

If mmioDescend is unsuccessful in searching for a chunk, the current file position is undefined. If mmioDescend is successful, the current file position is changed. If the chunk is a “RIFF” or “LIST” chunk, the new file position will be just after the form type or list type (12 bytes from the beginning of the chunk). For other chunks, the new file position will be the start of the data portion of the chunk (8 bytes from the beginning of the chunk).

The mmioDescend function fills the MMCKINFO structure pointed to by the lpck parameter with the following information:

•	The ckid member is the chunk. If the MMIO_FINDCHUNK, MMIO_FINDRIFF, or MMIO_FINDLIST flag is specified for wFlags, the MMCKINFO structure is also used to pass parameters to mmioDescend. In this case, the ckid member specifies the four-character code of the chunk identifier, form type, or list type to search for.

•	The cksize member is the size, in bytes, of the data portion of the chunk. The size includes the form type or list type (if any), but does not include the 8-byte chunk header or the pad byte at the end of the data (if any).

•	The fccType member is the form type if ckid is “RIFF”, or the list type if ckid is “LIST”. Otherwise, it is NULL.

•	The dwDataOffset member is the file offset of the beginning of the data portion of the chunk. If the chunk is a “RIFF” chunk or a “LIST” chunk, this member is the offset of the form type or list type.

•	The dwFlags member contains other information about the chunk. Currently, this information is not used and is set to zero.

See Also

mmioOpen, MMCKINFO


mmioFlush

The mmioFlush function writes the I/O buffer of a file to disk if the buffer has been written to.

MMRESULT mmioFlush(

HMMIO hmmio,
UINT fuFlush
);
Parameters

hmmio

File handle of a file opened by using the mmioOpen function.

fuFlush

Flag determining how the flush is carried out. It can be zero or the following:

MMIO_EMPTYBUF	Empties the buffer after writing it to the disk.
Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

MMIOERR_CANNOTWRITE	The contents of the buffer could not be written to disk.
Remarks

Closing a file with the mmioClose function automatically flushes its buffer.

If there is insufficient disk space to write the buffer, mmioFlush fails, even if the preceding calls of the mmioWrite function were successful.

See Also

mmioOpen, mmioClose, mmioWrite


mmioGetInfo

The mmioGetinfo function retrieves information about a file opened by using the mmioOpen function. This information allows the application to directly access the I/O buffer, if the file is opened for buffered I/O.

MMRESULT mmioGetInfo(

HMMIO hmmio,
LPMMIOINFO lpmmioinfo,
UINT wFlags
);
Parameters

hmmio

File handle of the file.

lpmmioinfo

Address an MMIOINFO structure that mmioGetInfo fills with information about the file.

wFlags

Reserved; must be zero.

Return Values

Returns zero if successful or an error otherwise.

Remarks

To directly access the I/O buffer of a file opened for buffered I/O, use the following members of the MMIOINFO structure filled by mmioGetInfo:

•	The pchNext member points to the next byte in the buffer that can be read or written. When you read or write, increment pchNext by the number of bytes read or written.

•	The pchEndRead member points to 1 byte past the last valid byte in the buffer that can be read.

•	The pchEndWrite member points to 1 byte past the last location in the buffer that can be written.

After you read or write to the buffer and modify pchNext, do not call any multimedia file I/O functions except mmioAdvance until you call the mmioSetInfo function. Call mmioSetInfo when you are finished directly accessing the buffer.

When you reach the end of the buffer specified by the pchEndRead or pchEndWrite member, call mmioAdvance to fill the buffer from the disk or write the buffer to the disk. The mmioAdvance function updates the pchNext, pchEndRead, and pchEndWrite members in the MMIOINFO structure for the file.

Before calling mmioAdvance or mmioSetInfo to flush a buffer to disk, set the MMIO_DIRTY flag in the dwFlags member of the MMIOINFO structure for the file. Otherwise, the buffer will not be written to disk.

Do not decrement pchNext or modify any members in the MMIOINFO structure other than pchNext and dwFlags. Do not set any flags in dwFlags except MMIO_DIRTY.

See Also

mmioOpen, MMIOINFO, mmioAdvance, mmioSetInfo


mmioInstallIOProc

The mmioInstallIOProc function installs or removes a custom I/O procedure. This function also locates an installed I/O procedure, using its corresponding four-character code.

LPMMIOPROC mmioInstallIOProc(

FOURCC fccIOProc,
LPMMIOPROC pIOProc,
DWORD dwFlags
);
Parameters

fccIOProc

Four-character code identifying the I/O procedure to install, remove, or locate. All characters in this code should be uppercase.

pIOProc

Address of the I/O procedure to install. To remove or locate an I/O procedure, set this parameter to NULL. For more information about the I/O procedure, see MMIOProc.

dwFlags

Flag indicating whether the I/O procedure is being installed, removed, or located. The following values are defined:

MMIO_FINDPROC

Searches for the specified I/O procedure.

MMIO_GLOBALPROC

This flag is a modifier to the MMIO_INSTALLPROC flag and indicates the I/O procedure should be installed for global use. This flag is ignored if MMIO_FINDPROC or MMIO_REMOVEPROC is specified.

MMIO_INSTALLPROC

Installs the specified I/O procedure.

MMIO_REMOVEPROC

Removes the specified I/O procedure.

Return Values

Returns the address of the I/O procedure installed, removed, or located. Returns NULL if there is an error.

See Also

MMIOProc


mmioOpen

The mmioOpen function opens a file for unbuffered or buffered I/O. The file can be a standard file, a memory file, or an element of a custom storage system. The handle returned by mmioOpen is not a standard file handle; do not use it with any file I/O functions other than multimedia file I/O functions.

HMMIO mmioOpen(

LPSTR szFilename,
LPMMIOINFO lpmmioinfo,
DWORD dwOpenFlags
);
Parameters

szFilename

Address of a string containing the filename of the file to open. If no I/O procedure is specified to open the file, the filename determines how the file is opened, as follows:

•	If the filename does not contain a plus sign (+), it is assumed to be the name of a standard  file (that is, a file whose type is not HMMIO).

•	If the filename is of the form EXAMPLE.EXT+ABC, the extension EXT is assumed to identify an installed I/O procedure which is called to perform I/O on the file. For more information, see mmioInstallIOProc.

•	If the filename is NULL and no I/O procedure is given, the adwInfo member of the MMIOINFO structure is assumed to be the standard (non-HMMIO) file handle of a currently open file.

The filename should not be longer than 128 bytes, including the terminating NULL character.

When opening a memory file, set szFilename to NULL.

lpmmioinfo

Address of an MMIOINFO structure containing extra parameters used by mmioOpen. Unless you are opening a memory file, specifying the size of a buffer for buffered I/O, or specifying an uninstalled I/O procedure to open a file, this parameter should be NULL. If this parameter is not NULL, all unused members of the MMIOINFO structure it references must be set to zero, including the reserved members.

dwOpenFlags

Flags for the open operation. The MMIO_READ, MMIO_WRITE, and MMIO_READWRITE flags are mutually exclusive — only one should be specified. The MMIO_COMPAT, MMIO_EXCLUSIVE, MMIO_DENYWRITE, MMIO_DENYREAD, and MMIO_DENYNONE flags are file-sharing flags. The following values are defined:

MMIO_ALLOCBUF

Opens a file for buffered I/O. To allocate a buffer larger or smaller than the default buffer size (8K, defined as MMIO_DEFAULTBUFFER), set the cchBuffer member of the MMIOINFO structure to the desired buffer size. If cchBuffer is zero, the default buffer size is used. If you are providing your own I/O buffer, this flag should not be used.

MMIO_COMPAT

Opens the file with compatibility mode, allowing any process on a given machine to open the file any number of times. If the file has been opened with any of the other sharing modes, mmioOpen fails.

MMIO_CREATE

Creates a new file. If the file already exists, it is truncated to zero length. For memory files, this flag indicates the end of the file is initially at the start of the buffer.

MMIO_DELETE

Deletes a file. If this flag is specified, szFilename should not be NULL. The return value is TRUE (cast to HMMIO) if the file was deleted successfully or FALSE otherwise. Do not call the mmioClose function for a file that has been deleted. If this flag is specified, all other flags that open files are ignored.

MMIO_DENYNONE

Opens the file without denying other processes read or write access to the file. If the file has been opened in compatibility mode by any other process, mmioOpen fails.

MMIO_DENYREAD

Opens the file and denies other processes read access to the file. If the file has been opened in compatibility mode or for read access by any other process, mmioOpen fails.

MMIO_DENYWRITE

Opens the file and denies other processes write access to the file. If the file has been opened in compatibility mode or for write access by any other process, mmioOpen fails.

MMIO_EXCLUSIVE

Opens the file and denies other processes read and write access to the file. If the file has been opened in any other mode for read or write access, even by the current process, mmioOpen fails.

MMIO_EXIST

Determines whether the specified file exists and creates a fully qualified filename from the path specified in szFilename. The filename is placed back into szFilename. The return value is TRUE (cast to HMMIO) if the qualification was successful and the file exists or FALSE otherwise. The file is not opened, and the function does not return a valid multimedia file I/O file handle, so do not attempt to close the file.

MMIO_GETTEMP

Creates a temporary filename, optionally using the parameters passed in szFilename. For example, you can specify “C:F” to create a temporary file residing on drive C, starting with letter “F”. The resulting filename is placed in the buffer pointed to by szFilename. The return value is MMSYSERR_NOERROR (cast to HMMIO) if the temporary filename was created successfully or MMIOERR_FILENOTFOUND otherwise. The file is not opened, and the function does not return a valid multimedia file I/O file handle, so do not attempt to close the file. This flag overrides all other flags.

MMIO_PARSE

Creates a fully qualified filename from the path specified in szFilename. The filename is placed back into szFilename. The return value is TRUE (cast to HMMIO) if the qualification was successful or FALSE otherwise. The file is not opened, and the function does not return a valid multimedia file I/O file handle, so do not attempt to close the file. If this flag is specified, all flags that open files are ignored.

MMIO_READ

Opens the file for reading only. This is the default if MMIO_WRITE and MMIO_READWRITE are not specified.

MMIO_READWRITE

Opens the file for reading and writing.

MMIO_WRITE

Opens the file for writing only.

Return Values

Returns a handle of the opened file. If the file cannot be opened, the return value is NULL. If lpmmioinfo is not NULL, the wErrorRet member of the MMIOINFO structure will contain one of the following error values:

MMIOERR_ACCESSDENIED	The file is protected and cannot be opened.
MMIOERR_INVALIDFILE	Another failure condition occurred. This is the default error for an open-file failure.
MMIOERR_NETWORKERROR	The network is not responding to the request to open a remote file.
MMIOERR_PATHNOTFOUND	The directory specification is incorrect.
MMIOERR_SHARINGVIOLATION	The file is being used by another application and is unavailable.
MMIOERR_TOOMANYOPENFILES	The number of files simultaneously open is at a maximum level. The system has run out of available file handles.
Remarks

If lpmmioinfo references an MMIOINFO structure, set up the members of that structure as described below. All unused members must be set to zero, including reserved members.

•	To request that a file be opened with an installed I/O procedure, set fccIOProc to the four-character code of the I/O procedure, and set pIOProc to NULL.

•	To request that a file be opened with an uninstalled I/O procedure, set IOProc to point to the I/O procedure, and set fccIOProc to NULL.

•	To request that mmioOpen determine which I/O procedure to use to open the file based on the filename contained in szFilename, set fccIOProc and pIOProc to NULL. This is the default behavior if no MMIOINFO structure is specified.

•	To open a memory file using an internally allocated and managed buffer, set pchBuffer to NULL, fccIOProc to FOURCC_MEM, cchBuffer to the initial size of the buffer, and adwInfo to the incremental expansion size of the buffer. This memory file will automatically be expanded in increments of the number of bytes specified in adwInfo when necessary. Specify the MMIO_CREATE flag for the dwOpenFlags parameter to initially set the end of the file to be the beginning of the buffer.

•	To open a memory file using an application-supplied buffer, set pchBuffer to point to the memory buffer, fccIOProc to FOURCC_MEM, cchBuffer to the size of the buffer, and adwInfo to the incremental expansion size of the buffer. The expansion size in adwInfo should be nonzero only if pchBuffer is a pointer obtained by calling the GlobalAlloc and GlobalLock functions; in this case, the GlobalReAlloc function will be called to expand the buffer. In other words, if pchBuffer points to a local or global array or a block of memory in the local heap, adwInfo must be zero. Specify the MMIO_CREATE flag for the dwOpenFlags parameter to initially set the end of the file to be the beginning of the buffer. Otherwise, the entire block of memory is considered readable.

•	To use a currently open standard file handle (that is, a file handle that does not have the HMMIO type) with multimedia file I/O services, set fccIOProc to FOURCC_DOS, pchBuffer to NULL, and adwInfo to the standard file handle. Offsets within the file will be relative to the beginning of the file and are not related to the position in the standard file at the time mmioOpen is called; the initial multimedia file I/O offset will be the same as the offset in the standard file when mmioOpen is called. To close the multimedia file I/O file handle without closing the standard file handle, pass the MMIO_FHOPEN flag to mmioClose.

You must call mmioClose to close a file opened by using mmioOpen. Open files are not automatically closed when an application exits.

See Also

ABC, mmioInstallIOProc, MMIOINFO, mmioClose, IOProc, GlobalAlloc, GlobalLock, GlobalReAlloc


MMIOProc

The MMIOProc function is a custom input/output (I/O) procedure installed by the mmioInstallIOProc function. MMIOProc is a placeholder for the application-defined function name. The address of this function can be specified in the callback-address parameter of mmioInstallIOProc.

LRESULT MMIOProc(

LPSTR lpmmioinfo,
UINT uMsg,
LONG lParam1,
LONG lParam2
);
Parameters

lpmmioinfo

Points to an MMIOINFO structure containing information about the open file.

The I/O procedure must maintain the lDiskOffset member in this structure to indicate the file offset to the next read or write location. The I/O procedure can use the adwInfo[] member to store state information. The I/O procedure should not modify any other members of the MMIOINFO structure.

uMsg

Specifies a message indicating the requested I/O operation. Messages that can be received include MMIOM_OPEN, MMIOM_CLOSE, MMIOM_READ, MMIOM_SEEK, MMIOM_WRITE, and MMIOM_WRITEFLUSH.

lParam1

Specifies an application-defined parameter for the message.

lParam2

Specifies an application-defined parameter for the message.

Return Values

The return value depends on the message specified by uMsg. If the I/O procedure does not recognize a message, it should return zero.

Remarks

The four-character code specified by the fccMMIOProc member in the MMIOINFO structure associated with a file identifies a filename extension for a custom storage system. When an application calls mmioOpen with a filename such as “one.xyz+two”, the I/O procedure associated with the four-character code “XYZ” is called to open the “two” element of the file “one.xyz”.

The mmioInstallIOProc function maintains a separate list of installed I/O procedures for each Windows-based application. Therefore, different applications can use the same I/O procedure identifier for different I/O procedures without conflict. However, installing an I/O procedure globally enables any process to use the procedure.

If an application calls mmioInstallIOProc more than once to register the same I/O procedure, then it must call mmioInstallIOProc to remove the procedure once for each time it installed the procedure.

mmioInstallIOProc will not prevent an application from installing two different I/O procedures with the same identifier, or installing an I/O procedure with one of the predefined identifiers (“DOS “, “MEM “). The most recently installed procedure takes precedence, and the most recently installed procedure is the first one to be removed.

When searching for a specified I/O procedure, local procedures are searched first, then global procedures.

See Also

MMIOINFO, mmioInstallIOProc, MMIOM_OPEN, MMIOM_CLOSE, MMIOM_READ, MMIOM_SEEK, MMIOM_WRITE, MMIOM_WRITEFLUSH, mmioOpen


mmioRead

The mmioRead function reads a specified number of bytes from a file opened by using the mmioOpen function.

LONG mmioRead(

HMMIO hmmio,
HPSTR pch,
LONG cch
);
Parameters

hmmio

File handle of the file to be read.

pch

Address of a buffer to contain the data read from the file.

cch

Number of bytes to read from the file.

Return Values

Returns the number of bytes actually read. If the end of the file has been reached and no more bytes can be read, the return value is 0. If there is an error reading from the file, the return value is − 1.

See Also

mmioOpen


mmioRename

The mmioRename function renames the specified file.

MMRESULT mmioRename(

LPCSTR szFilename,
LPCSTR szNewFilename,
const LPMMIOINFO lpmmioinfo,
DWORD dwRenameFlags
);
Parameters

szFilename

Address of a string containing the filename of the file to rename.

szNewFileName

Address of a string containing the new filename.

lpmmioinfo

Address of an MMIOINFO structure containing extra parameters used by mmioRename. If this parameter is not NULL, all unused members of the MMIOINFO structure it references must be set to zero, including the reserved members.

dwRenameFlags

Flags for the rename operation. This parameter should be set to zero.

Return Values

Returns zero if the file was renamed. Otherwise, returns an error code returned from mmioRename or from the I/O procedure.

See Also

MMIOINFO


mmioSeek

The mmioSeek function changes the current file position in a file opened by using the mmioOpen function.

LONG mmioSeek(

HMMIO hmmio,
LONG lOffset,
int iOrigin
);
Parameters

hmmio

File handle of the file to seek in.

lOffset

Offset to change the file position.

iOrigin

Flags indicating how the offset specified by lOffset is interpreted. The following values are defined:

SEEK_CUR

Seeks to lOffset bytes from the current file position.

SEEK_END

Seeks to lOffset bytes from the end of the file.

SEEK_SET

Seeks to lOffset bytes from the beginning of the file.

Return Values

Returns the new file position, in bytes, relative to the beginning of the file. If there is an error, the return value is − 1.

Remarks

Seeking to an invalid location in the file, such as past the end of the file, might not cause mmioSeek to return an error, but it might cause subsequent I/O operations on the file to fail.

To locate the end of a file, call mmioSeek with lOffset set to zero and iOrigin set to SEEK_END.

See Also

mmioOpen


mmioSendMessage

The mmioSendMessage function sends a message to the I/O procedure associated with the specified file.

LRESULT mmioSendMessage(

HMMIO hmmio,
UINT wMsg,
LPARAM lParam1,
LPARAM lParam2
);
Parameters

hmmio

File handle for a file opened by using the mmioOpen function.

wMsg

Message to send to the I/O procedure.

lParam1 and lParam2

Parameters for the message.

Return Values

Returns a value that corresponds to the message. If the I/O procedure does not recognize the message, the return value should be zero.

Remarks

Use this function to send custom user-defined messages. Do not use it to send the MMIOM_OPEN, MMIOM_CLOSE, MMIOM_READ, MMIOM_WRITE, MMIOM_WRITEFLUSH, or MMIOM_SEEK messages. Define custom messages to be greater than or equal to the MMIOM_USER constant.

See Also

mmioOpen, MMIOM_OPEN, MMIOM_CLOSE, MMIOM_READ, MMIOM_WRITE, MMIOM_WRITEFLUSH, MMIOM_SEEK


mmioSetBuffer

The mmioSetBuffer function enables or disables buffered I/O, or changes the buffer or buffer size for a file opened by using the mmioOpen function.

MMRESULT mmioSetBuffer(

HMMIO hmmio,
LPSTR pchBuffer,
LONG cchBuffer,
UINT wFlags
);
Parameters

hmmio

File handle of the file.

pchBuffer

Address of an application-defined buffer to use for buffered I/O. If this parameter is NULL, mmioSetBuffer allocates an internal buffer for buffered I/O.

cchBuffer

Size, in characters, of the application-defined buffer, or the size of the buffer for mmioSetBuffer to allocate.

wFlags

Reserved; must be zero.

Return Values

Returns zero if successful or an error otherwise. If an error occurs, the file handle remains valid. The following values are defined:

MMIOERR_CANNOTWRITE	The contents of the old buffer could not be written to disk, so the operation was aborted.
MMIOERR_OUTOFMEMORY	The new buffer could not be allocated, probably due to a lack of available memory.
Remarks

To enable buffering using an internal buffer, set pchBuffer to NULL and cchBuffer to the desired buffer size.

To supply your own buffer, set pchBuffer to point to the buffer, and set cchBuffer to the size of the buffer.

To disable buffered I/O, set pchBuffer to NULL and cchBuffer to zero.

If buffered I/O is already enabled using an internal buffer, you can reallocate the buffer to a different size by setting pchBuffer to NULL and cchBuffer to the new buffer size. The contents of the buffer can be changed after resizing.

See Also

mmioOpen


mmioSetInfo

The mmioSetInfo function updates the information retrieved by the mmioGetInfo function about a file opened by using the mmioOpen function. Use this function to terminate direct buffer access of a file opened for buffered I/O.

MMRESULT mmioSetInfo(

HMMIO hmmio,
LPMMIOINFO lpmmioinfo,
UINT wFlags
);
Parameters

hmmio

File handle of the file.

lpmmioinfo

Address of an MMIOINFO structure filled with information by the mmioGetInfo function.

wFlags

Reserved; must be zero.

Return Values

Returns zero if successful or an error otherwise.

Remarks

If you have written to the file I/O buffer, set the MMIO_DIRTY flag in the dwFlags member of the MMIOINFO structure before calling mmioSetInfo to terminate direct buffer access. Otherwise, the buffer will not get flushed to disk.

See Also

mmioGetInfo, mmioOpen, MMIOINFO


mmioStringToFOURCC

The mmioStringToFOURCC function converts a null-terminated string to a four-character code.

FOURCC mmioStringToFOURCC(

LPCSTR sz,
UINT wFlags
);
Parameters

sz

Address of a null-terminated string to convert to a four-character code.

wFlags

Flags for the conversion. The following value is defined:

MMIO_TOUPPER

Converts all characters to uppercase.

Return Values

Returns the four-character code created from the given string.

Remarks

This function copies the string to a four-character code and pads it with space characters or truncates it if necessary. It does not check whether the code it returns is valid.


mmioWrite

The mmioWrite function writes a specified number of bytes to a file opened by using the mmioOpen function.

LONG mmioWrite(

HMMIO hmmio,
char _huge* pch,
LONG cch
);
Parameters

hmmio

File handle of the file.

pch

Address of the buffer to be written to the file.

cch

Number of bytes to write to the file.

Return Values

Returns the number of bytes actually written. If there is an error writing to the file, the return value is -1.

Remarks

The current file position is incremented by the number of bytes written.

See Also

mmioOpen


MyStatusProc

The MyStatusProc function describes an application-defined status callback function used by the ICM_SET_STATUS_PROC message and the ICSetStatusProc function.

LONG MyStatusProc(

LPARAM lParam,
UINT Message
);
Parameters

lParam

Constant specified with the status callback address.

Message

Status flag. It can be one of the following values:

ICSTATUS_END

A lengthy operation is finishing.

ICSTATUS_START

A lengthy operation is starting.

ICSTATUS_STATUS

Operation is proceeding, and is lParam percent done.

ICSTATUS_YIELD

A lengthy operation is proceeding. This value has the same meaning as ICSTATUS_STATUS but does not indicate a value for percentage done.

Return Values

Returns zero if processing should continue or a nonzero value if it should end.

See Also

ICM_SET_STATUS_PROC, ICSetStatusProc


PlaySound

The PlaySound function plays a sound specified by the given filename, resource, or system event. (A system event may be associated with a sound in the registry or in the WIN.INI file.)

BOOL PlaySound(

LPCSTR pszSound,
HMODULE hmod,
DWORD fdwSound
);
Parameters

pszSound

A string that specifies the sound to play. If this parameter is NULL, any currently playing waveform sound is stopped. To stop a non-waveform sound, specify SND_PURGE in the fdwSound parameter.

Three flags in fdwSound (SND_ALIAS, SND_FILENAME, and SND_RESOURCE) determine whether the name is interpreted as an alias for a system event, a filename, or a resource identifier. If none of these flags are specified, PlaySound searches the registry or the WIN.INI file for an association with the specified sound name. If an association is found, the sound event is played. If no association is found in the registry, the name is interpreted as a filename.

hmod

Handle of the executable file that contains the resource to be loaded. This parameter must be NULL unless SND_RESOURCE is specified in fdwSound.

fdwSound

Flags for playing the sound. The following values are defined:

SND_APPLICATION

The sound is played using an application-specific association.

SND_ALIAS

The pszSound parameter is a system-event alias in the registry or the WIN.INI file. Do not use with either SND_FILENAME or SND_RESOURCE.

SND_ALIAS_ID

The pszSound parameter is a predefined sound identifier.

SND_ASYNC

The sound is played asynchronously and PlaySound returns immediately after beginning the sound. To terminate an asynchronously played waveform sound, call PlaySound with pszSound set to NULL.

SND_FILENAME

The pszSound parameter is a filename.

SND_LOOP

The sound plays repeatedly until PlaySound is called again with the pszSound parameter set to NULL. You must also specify the SND_ASYNC flag to indicate an asynchronous sound event.

SND_MEMORY

A sound event’s file is loaded in RAM. The parameter specified by pszSound must point to an image of a sound in memory.

SND_NODEFAULT

No default sound event is used. If the sound cannot be found, PlaySound returns silently without playing the default sound.

SND_NOSTOP

The specified sound event will yield to another sound event that is already playing. If a sound cannot be played because the resource needed to generate that sound is busy playing another sound, the function immediately returns FALSE without playing the requested sound.

If this flag is not specified, PlaySound attempts to stop the currently playing sound so that the device can be used to play the new sound.

SND_NOWAIT

If the driver is busy, return immediately without playing the sound.

SND_PURGE

Sounds are to be stopped for the calling task. If pszSound is not NULL, all instances of the specified sound are stopped. If pszSound is NULL, all sounds that are playing on behalf of the calling task are stopped.

You must also specify the instance handle to stop SND_RESOURCE events.

SND_RESOURCE

The pszSound parameter is a resource identifier; hmod must identify the instance that contains the resource.

SND_SYNC

Synchronous playback of a sound event. PlaySound returns after the sound event completes.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The sound specified by pszSound must fit into available physical memory and be playable by an installed waveform-audio device driver. PlaySound searches the following directories for sound files: the current directory; the Windows directory; the Windows system directory; directories listed in the PATH environment variable; and the list of directories mapped in a network. For more information about the directory search order, see the documentation for the OpenFile function.

If it cannot find the specified sound, PlaySound uses the default system event sound entry instead. If the function can find neither the system default entry nor the default sound, it makes no sound and returns FALSE.


sndPlaySound

The sndPlaySound function plays a waveform sound specified either by a filename or by an entry in the registry or the WIN.INI file. This function offers a subset of the functionality of the PlaySound function; sndPlaySound is being maintained for backward compatibility.

BOOL sndPlaySound(

LPCSTR lpszSound,
UINT fuSound
);
Parameters

lpszSound

A string that specifies the sound to play. This parameter can be either an entry in the registry or in WIN.INI that identifies a system sound, or it can be the name of a waveform-audio file. (If the function does not find the entry, the parameter is treated as a filename.) If this parameter is NULL, any currently playing sound is stopped.

fuSound

Flags for playing the sound. The following values are defined:

SND_ASYNC

The sound is played asynchronously and the function returns immediately after beginning the sound. To terminate an asynchronously played sound, call sndPlaySound with lpszSoundName set to NULL.

SND_LOOP

The sound plays repeatedly until sndPlaySound is called again with the lpszSoundName parameter set to NULL. You must also specify the SND_ASYNC flag to loop sounds.

SND_MEMORY

The parameter specified by lpszSoundName points to an image of a waveform sound in memory.

SND_NODEFAULT

If the sound cannot be found, the function returns silently without playing the default sound.

SND_NOSTOP

If a sound is currently playing, the function immediately returns FALSE, without playing the requested sound.

SND_SYNC

The sound is played synchronously and the function does not return until the sound ends.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

If the specified sound cannot be found, sndPlaySound plays the system default sound. If there is no system default entry in the registry or WIN.INI file, or if the default sound cannot be found, the function makes no sound and returns FALSE.

The specified sound must fit in available physical memory and be playable by an installed waveform-audio device driver. If sndPlaySound does not find the sound in the current directory, the function searches for it using the standard directory-search order.

See Also

PlaySound


timeBeginPeriod

The timeBeginPeriod function sets the minimum timer resolution for an application or device driver.

MMRESULT timeBeginPeriod(

UINT uPeriod
);
Parameters

uPeriod

Minimum timer resolution, in milliseconds, for the application or device driver.

Return Values

Returns TIMERR_NOERROR if successful or TIMERR_NOCANDO if the resolution specified in uPeriod is out of range.

Remarks

Call this function immediately before using timer services, and call the timeEndPeriod function immediately after you are finished using the timer services.

You must match each call to timeBeginPeriod with a call to timeEndPeriod, specifying the same minimum resolution in both calls. An application can make multiple timeBeginPeriod calls as long as each call is matched with a call to timeEndPeriod.

See Also

timeEndPeriod


timeEndPeriod

The timeEndPeriod function clears a previously set minimum timer resolution.

MMRESULT timeEndPeriod(

UINT uPeriod
);
Parameters

uPeriod

Minimum timer resolution specified in the previous call to the timeBeginPeriod function.

Return Values

Returns TIMERR_NOERROR if successful or TIMERR_NOCANDO if the resolution specified in uPeriod is out of range.

Remarks

Call this function immediately after you are finished using timer services.

You must match each call to timeBeginPeriod with a call to timeEndPeriod, specifying the same minimum resolution in both calls. An application can make multiple timeBeginPeriod calls as long as each call is matched with a call to timeEndPeriod.

See Also

timeBeginPeriod


timeGetDevCaps

The timeGetDevCaps function queries the timer device to determine its resolution.

MMRESULT timeGetDevCaps(

LPTIMECAPS ptc,
UINT cbtc
);
Parameters

ptc

Address of a TIMECAPS structure. This structure is filled with information about the resolution of the timer device.

cbtc

Size, in bytes, of the TIMECAPS structure.

Return Values

Returns TIMERR_NOERROR if successful or TIMERR_STRUCT if it fails to return the timer device capabilities.

See Also

TIMECAPS


timeGetSystemTime

The timeGetSystemTime function retrieves the system time, in milliseconds. The system time is the time elapsed since Windows was started. This function works very much like the timeGetTime function. See timeGetTime for details of these functions’ operation.

MMRESULT timeGetSystemTime(

LPMMTIME pmmt,
UINT cbmmt
);
Parameters

pmmt

Address of an MMTIME structure.

cbmmt

Size, in bytes, of the MMTIME structure.

Return Values

Returns TIMERR_NOERROR. The system time is returned in the ms member of the MMTIME structure.

See Also

timeGetTime, MMTIME


timeGetTime

The timeGetTime function retrieves the system time, in milliseconds. The system time is the time elapsed since Windows was started.

DWORD timeGetTime(VOID);

Parameters

This function does not take parameters.

Return Values

Returns the system time, in milliseconds.

Remarks

The only difference between this function and the timeGetSystemTime function is that timeGetSystemTime uses the MMTIME structure to return the system time. The timeGetTime function has less overhead than timeGetSystemTime.

Note that the value returned by the timeGetTime function is a DWORD value. The return value wraps around to 0 every 2^32 milliseconds, which is about 49.71 days.This can cause problems in code that directly uses the timeGetTime return value in computations, particularly where the value is used to control code execution. You should always use the difference between two timeGetTime return values in computations.

Windows NT: The default precision of the timeGetTime function can be five milliseconds or more, depending on the machine. You can use the timeBeginPeriod and timeEndPeriod functions to increase the precision of timeGetTime. If you do so, the minimum difference between successive values returned by timeGetTime can be as large as the minimum period value set using timeBeginPeriod and timeEndPeriod. Use the QueryPerformanceCounter and QueryPerformanceFrequency functions to measure short time intervals at a high resolution,

Windows 95: The default precision of the timeGetTime function is 1 millisecond. In other words, the timeGetTime function can return successive values that differ by just 1 millisecond. This is true no matter what calls have been made to the timeBeginPeriod and timeEndPeriod functions.

See Also

timeGetSystemTime, MMTIME, timeGetTime, timeBeginPeriod, timeEndPeriod, QueryPerformanceCounter, QueryPerformanceFrequency


timeKillEvent

The timeKillEvent function cancels a specified timer event.

MMRESULT timeKillEvent(

UINT uTimerID
);
Parameters

uTimerID

Identifier of the timer event to cancel. This identifier was returned by the timeSetEvent function when the timer event was set up.

Return Values

Returns TIMERR_NOERROR if successful or MMSYSERR_INVALPARAM if the specified timer event does not exist.

See Also

timeSetEvent


TimeProc

The TimeProc function callback function that is called once upon the expiration of a single event or periodically upon the expiration of periodic events.

void CALLBACK TimeProc(

UINT uID,
UINT uMsg,
DWORD dwUser,
DWORD dw1,
DWORD dw2
);
TimeProc is a placeholder for the application-defined function name.

Parameters

uID

Identifier of the timer event. This identifier was returned by the timeSetEvent function when the timer event was set up.

uMsg

Reserved; do not use.

dwUser

User instance data supplied to the dwUser parameter of timeSetEvent.

dw1 and dw2

Reserved; do not use.

Return Values

This function does not return a value.

Remarks

Applications should not call any system-defined functions from inside a callback function, except for PostMessage, timeGetSystemTime, timeGetTime, timeSetEvent, timeKillEvent, midiOutShortMsg, midiOutLongMsg, and OutputDebugString.

See Also

timeSetEvent, PostMessage, timeGetSystemTime, timeGetTime, timeKillEvent, midiOutShortMsg, midiOutLongMsg, OutputDebugString


timeSetEvent

The timeSetEvent function starts a specified timer event. The multimedia timer runs in its own thread. After the event is activated, it calls the specified callback function.

MMRESULT timeSetEvent(

UINT uDelay,
UINT uResolution,
LPTIMECALLBACK lpTimeProc,
DWORD dwUser,
UINT fuEvent
);
Parameters

uDelay

Event delay, in milliseconds. If this value is not in the range of the minimum and maximum event delays supported by the timer, the function returns an error.

uResolution

Resolution of the timer event, in milliseconds. The resolution increases with smaller values; a resolution of 0 indicates periodic events should occur with the greatest possible accuracy. To reduce system overhead, however, you should use the maximum value appropriate for your application.

lpTimeProc

Address of a callback function that is called once upon expiration of a single event or periodically upon expiration of periodic events.

dwUser

User-supplied callback data.

fuEvent

Timer event type. The following values are defined:

TIME_ONESHOT

Event occurs once, after uDelay milliseconds.

TIME_PERIODIC

Event occurs every uDelay milliseconds.

Return Values

Returns an identifier for the timer event if successful or an error otherwise. This function returns NULL if it fails and the timer event was not created. (This identifier is also passed to the callback function.)

Remarks

Each call to timeSetEvent for periodic timer events must be matched with a call to the timeKillEvent function.

See Also

timeKillEvent


waveInAddBuffer

The waveInAddBuffer function sends an input buffer to the given waveform-audio input device. When the buffer is filled, the application is notified.

MMRESULT waveInAddBuffer(

HWAVEIN hwi,
LPWAVEHDR pwh,
UINT cbwh
);
Parameters

hwi

Handle of the waveform-audio input device.

pwh

Address of a WAVEHDR structure that identifies the buffer.

cbwh

Size, in bytes, of the WAVEHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
WAVERR_UNPREPARED	The buffer pointed to by the pwh parameter hasn’t been prepared.
Remarks

When the buffer is filled, the WHDR_DONE bit is set in the dwFlags member of the WAVEHDR structure.

The buffer must be prepared with the waveInPrepareHeader function before it is passed to this function.

See Also

WAVEHDR, waveInPrepareHeader


waveInClose

The waveInClose function closes the given waveform-audio input device.

MMRESULT waveInClose(

HWAVEIN hwi
);
Parameters

hwi

Handle of the waveform-audio input device. If the function succeeds, the handle is no longer valid after this call.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
WAVERR_STILLPLAYING	There are still buffers in the queue.
Remarks

If there are input buffers that have been sent with the waveInAddBuffer function and that haven’t been returned to the application, the close operation will fail. Call the waveInReset function to mark all pending buffers as done.

See Also

waveInAddBuffer, waveInReset


waveInGetDevCaps

The waveInGetDevCaps function retrieves the capabilities of a given waveform-audio input device.

MMRESULT waveInGetDevCaps(

UINT uDeviceID,
LPWAVEINCAPS pwic,
UINT cbwic
);
Parameters

uDeviceID

Identifier of the waveform-audio output device. It can be either a device identifier or a handle of an open waveform-audio input device.

pwic

Address of a WAVEINCAPS structure to be filled with information about the capabilities of the device.

cbwic

Size, in bytes, of the WAVEINCAPS structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_BADDEVICEID	Specified device identifier is out of range.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
Remarks

Use this function to determine the number of waveform-audio input devices present in the system. If the value specified by the uDeviceID parameter is a device identifier, it can vary from zero to one less than the number of devices present. The WAVE_MAPPER constant can also be used as a device identifier. Only cbwic bytes (or less) of information is copied to the location pointed to by pwic. If cbwic is zero, nothing is copied and the function returns zero.

See Also

WAVEINCAPS


waveInGetErrorText

The waveInGetErrorText function retrieves a textual description of the error identified by the given error number.

MMRESULT waveInGetErrorText(

MMRESULT mmrError,
LPSTR pszText,
UINT cchText
);
Parameters

mmrError

Error number.

pszText

Address of the buffer to be filled with the textual error description.

cchText

Size, in characters, of the buffer pointed to by pszText.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_BADERRNUM	Specified error number is out of range.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
Remarks

If the textual error description is longer than the specified buffer, the description is truncated. The returned error string is always null-terminated. If cchText is zero, nothing is copied and the function returns zero. All error descriptions are less than MAXERRORLENGTH characters long.


waveInGetID

The waveInGetID function gets the device identifier for the given waveform-audio input device.

This function is supported for backward compatibility. New applications can cast a handle of the device rather than retrieving the device identifier.

MMRESULT waveInGetID(

HWAVEIN hwi,
LPUINT puDeviceID
);
Parameters

hwi

Handle of the waveform-audio input device.

puDeviceID

Address of a variable to be filled with the device identifier.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The hwi parameter specifies an invalid handle.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.


waveInGetNumDevs

The waveInGetNumDevs function returns the number of waveform-audio input devices present in the system.

UINT waveInGetNumDevs(VOID);

Parameters

This function takes no parameters.

Return Values

Returns the number of devices. A return value of zero means that no devices are present or that an error occurred.


waveInGetPosition

The waveInGetPosition function retrieves the current input position of the given waveform-audio input device.

MMRESULT waveInGetPosition(

HWAVEIN hwi,
LPMMTIME pmmt,
UINT cbmmt
);
Parameters

hwi

Handle of the waveform-audio input device.

pmmt

Address of an MMTIME structure.

cbmmt

Size, in bytes, of the MMTIME structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
Remarks

Before calling this function, set the wType member of the MMTIME structure to indicate the time format you want. After calling this function, check wType to determine whether the desired time format is supported. If the format is not supported, the member will specify an alternative format.

The position is set to zero when the device is opened or reset.

See Also

MMTIME


waveInMessage

The waveInMessage function sends messages to the waveform-audio input device drivers.

DWORD waveInMessage(

HWAVEIN hwi,
UINT uMsg,
DWORD dwParam1,
DWORD dwParam2
);
Parameters

hwi

Handle of the waveform-audio input device.

uMsg

Message to send.

dwParam1 and dwParam2

Message parameters.

Return Values

Returns the value returned from the driver.


waveInOpen

The waveInOpen function opens the given waveform-audio input device for recording.

MMRESULT waveInOpen(

LPHWAVEIN phwi,
UINT uDeviceID,
LPWAVEFORMATEX pwfx,
DWORD dwCallback,
DWORD dwCallbackInstance,
DWORD fdwOpen
);
Parameters

phwi

Address filled with a handle identifying the open waveform-audio input device. Use this handle to identify the device when calling other waveform-audio input functions. This parameter can be NULL if WAVE_FORMAT_QUERY is specified for fdwOpen.

uDeviceID

Identifier of the waveform-audio input device to open. It can be either a device identifier or a handle of an open waveform-audio input device.You can use the following flag instead of a device identifier:

WAVE_MAPPER

The function selects a waveform-audio input device capable of recording in the specified format.

pwfx

Address of a WAVEFORMATEX structure that identifies the desired format for recording waveform-audio data. You can free this structure immediately after waveInOpen returns.

dwCallback

Address of a fixed callback function, an event handle, a handle to a window, or the identifier of a thread to be called during waveform-audio recording to process messages related to the progress of recording. If no callback function is required, this value can be zero. For more information on the callback function, see waveInProc.

dwCallbackInstance

User-instance data passed to the callback mechanism. This parameter is not used with the window callback mechanism.

fdwOpen

Flags for opening the device. The following values are defined:

CALLBACK_EVENT

The dwCallback parameter is an event handle.

CALLBACK_FUNCTION

The dwCallback parameter is a callback procedure address.

CALLBACK_NULL

No callback mechanism. This is the default setting.

CALLBACK_THREAD

The dwCallback parameter is a thread identifier.

CALLBACK_WINDOW

The dwCallback parameter is a window handle.

WAVE_FORMAT_DIRECT

If this flag is specified, the ACM driver does not perform conversions on the audio data.

WAVE_FORMAT_QUERY

The function queries the device to determine whether it supports the given format, but it does not open the device.

WAVE_MAPPED

The uDeviceID parameter specifies a waveform-audio device to be mapped to by the wave mapper.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_ALLOCATED	Specified resource is already allocated.
MMSYSERR_BADDEVICEID	Specified device identifier is out of range.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
WAVERR_BADFORMAT	Attempted to open with an unsupported waveform-audio format.
Remarks

Use the waveInGetNumDevs function to determine the number of waveform-audio input devices present on the system. The device identifier specified by uDeviceID varies from zero to one less than the number of devices present. The WAVE_MAPPER constant can also be used as a device identifier.

If you choose to have a window or thread receive callback information, the following messages are sent to the window procedure or thread to indicate the progress of waveform-audio input: MM_WIM_OPEN, MM_WIM_CLOSE, and MM_WIM_DATA.

If you choose to have a function receive callback information, the following messages are sent to the function to indicate the progress of waveform-audio input: WIM_OPEN, WIM_CLOSE, and WIM_DATA.

See Also

WAVEFORMATEX, waveInGetNumDevs, waveInProc, MM_WIM_OPEN, MM_WIM_CLOSE, MM_WIM_DATA


waveInPrepareHeader

The waveInPrepareHeader function prepares a buffer for waveform-audio input.

MMRESULT waveInPrepareHeader(

HWAVEIN hwi,
LPWAVEHDR pwh,
UINT cbwh
);
Parameters

hwi

Handle of the waveform-audio input device.

pwh

Address of a WAVEHDR structure that identifies the buffer to be prepared.

cbwh

Size, in bytes, of the WAVEHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
Remarks

The lpData, dwBufferLength, and dwFlags members of the WAVEHDR structure must be set before calling this function (dwFlags must be zero).

See Also

 WAVEHDR


waveInProc

The waveInProc function is the callback function used with the waveform-audio input device. This function is a placeholder for the application-defined function name. The address of this function can be specified in the callback-address parameter of the waveInOpen function.

void CALLBACK waveInProc(

HWAVEIN hwi,
UINT uMsg,
DWORD dwInstance,
DWORD dwParam1,
DWORD dwParam2
);
Parameters

hwi

Handle of the waveform-audio device associated with the callback function.

uMsg

Waveform-audio input message. It can be one of the following messages:

WIM_CLOSE

Sent when the device is closed using the waveInClose function.

WIM_DATA

Sent when the device driver is finished with a data block sent using the waveInAddBuffer function.

WIM_OPEN

Sent when the device is opened using the waveInOpen function.

dwInstance

User instance data specified with waveInOpen.

dwParam1

Message parameters.

dwParam2

Message parameters.

Return Values

This function does not return a value.

Remarks

Applications should not call any system-defined functions from inside a callback function, except for EnterCriticalSection, LeaveCriticalSection, midiOutLongMsg, midiOutShortMsg, OutputDebugString, PostMessage, PostThreadMessage, SetEvent, timeGetSystemTime, timeGetTime, timeKillEvent, and timeSetEvent. Calling other wave functions will cause deadlock.

See Also

EnterCriticalSection, LeaveCriticalSection, midiOutLongMsg, midiOutShortMsg, OutputDebugString, PostMessage, PostThreadMessage, SetEvent, timeGetSystemTime, timeGetTime, timeKillEvent, timeSetEvent, waveInAddBuffer, waveInClose, waveInOpen, WIM_DATA, WIM_CLOSE, WIM_OPEN


waveInReset

The waveInReset function stops input on the given waveform-audio input device and resets the current position to zero. All pending buffers are marked as done and returned to the application.

MMRESULT waveInReset(

HWAVEIN hwi
);
Parameters

hwi

Handle of the waveform-audio input device.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.


waveInStart

The waveInStart function starts input on the given waveform-audio input device.

MMRESULT waveInStart(

HWAVEIN hwi
);
Parameters

hwi

Handle of the waveform-audio input device.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
Remarks

Buffers are returned to the application when full or when the waveInReset function is called (the dwBytesRecorded member in the header will contain the length of data). If there are no buffers in the queue, the data is thrown away without notifying the application, and input continues.

Calling this function when input is already started has no effect, and the function returns zero.

See Also

waveInReset


waveInStop

The waveInStop function stops waveform-audio input.

MMRESULT waveInStop(

HWAVEIN hwi
);
Parameters

hwi

Handle of the waveform-audio input device.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
Remarks

If there are any buffers in the queue, the current buffer will be marked as done (the dwBytesRecorded member in the header will contain the length of data), but any empty buffers in the queue will remain there.

Calling this function when input is not started has no effect, and the function returns zero.


waveInUnprepareHeader

The waveInUnprepareHeader function cleans up the preparation performed by the waveInPrepareHeader function. This function must be called after the device driver fills a buffer and returns it to the application. You must call this function before freeing the buffer.

MMRESULT waveInUnprepareHeader(

HWAVEIN hwi,
LPWAVEHDR pwh,
UINT cbwh
);
Parameters

hwi

Handle of the waveform-audio input device.

pwh

Address of a WAVEHDR structure identifying the buffer to be cleaned up.

cbwh

Size, in bytes, of the WAVEHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
WAVERR_STILLPLAYING	The buffer pointed to by the pwh parameter is still in the queue.
Remarks

This function complements the waveInPrepareHeader function.

You must call this function before freeing the buffer. After passing a buffer to the device driver with the waveInAddBuffer function, you must wait until the driver is finished with the buffer before calling waveInUnprepareHeader. Unpreparing a buffer that has not been prepared has no effect, and the function returns zero.

See Also

waveInPrepareHeader, WAVEHDR, waveInAddBuffer


waveOutBreakLoop

The waveOutBreakLoop function breaks a loop on the given waveform-audio output device and allows playback to continue with the next block in the driver list.

MMRESULT waveOutBreakLoop(

HWAVEOUT hwo
);
Parameters

hwo

Handle of the waveform-audio output device.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
Remarks

The blocks making up the loop are played to the end before the loop is terminated.

Calling this function when nothing is playing or looping has no effect, and the function returns zero.


waveOutClose

The waveOutClose function closes the given waveform-audio output device.

MMRESULT waveOutClose(

HWAVEOUT hwo
);
Parameters

hwo

Handle of the waveform-audio output device. If the function succeeds, the handle is no longer valid after this call.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
WAVERR_STILLPLAYING	There are still buffers in the queue.
Remarks

If the device is still playing a waveform-audio file, the close operation fails. Use the waveOutReset function to terminate playback before calling waveOutClose.

See Also

waveOutReset


waveOutGetDevCaps

The waveOutGetDevCaps function retrieves the capabilities of a given waveform-audio output device.

MMRESULT waveOutGetDevCaps(

UINT uDeviceID,
LPWAVEOUTCAPS pwoc,
UINT cbwoc
);
Parameters

uDeviceID

Identifier of the waveform-audio output device. It can be either a device identifier or a handle of an open waveform-audio output device.

pwoc

Address of a WAVEOUTCAPS structure to be filled with information about the capabilities of the device.

cbwoc

Size, in bytes, of the WAVEOUTCAPS structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_BADDEVICEID	Specified device identifier is out of range.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
Remarks

Use the waveOutGetNumDevs function to determine the number of waveform-audio output devices present in the system. If the value specified by the uDeviceID parameter is a device identifier, it can vary from zero to one less than the number of devices present. The WAVE_MAPPER constant can also be used as a device identifier. Only cbwoc bytes (or less) of information is copied to the location pointed to by pwoc. If cbwoc is zero, nothing is copied and the function returns zero.

See Also

WAVEOUTCAPS, waveOutGetNumDevs


waveOutGetErrorText

The waveOutGetErrorText function retrieves a textual description of the error identified by the given error number.

MMRESULT waveOutGetErrorText(

MMRESULT mmrError,
LPSTR pszText,
UINT cchText
);
Parameters

mmrError

Error number.

pszText

Address of a buffer to be filled with the textual error description.

cchText

Size, in characters, of the buffer pointed to by pszText.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_BADERRNUM	Specified error number is out of range.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
Remarks

If the textual error description is longer than the specified buffer, the description is truncated. The returned error string is always null-terminated. If cchText is zero, nothing is copied and the function returns zero. All error descriptions are less than MAXERRORLENGTH characters long.


waveOutGetID

The waveOutGetID function retrieves the device identifier for the given waveform-audio output device.

This function is supported for backward compatibility. New applications can cast a handle of the device rather than retrieving the device identifier.

MMRESULT waveOutGetID(

HWAVEOUT hwo,
LPUINT puDeviceID
);
Parameters

hwo

Handle of the waveform-audio output device.

puDeviceID

Address of a variable to be filled with the device identifier.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	The hwo parameter specifies an invalid handle.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.


waveOutGetNumDevs

The waveOutGetNumDevs function retrieves the number of waveform-audio output devices present in the system.

UINT waveOutGetNumDevs(VOID);

Parameters

This function takes no parameters.

Return Values

Returns the number of devices. A return value of zero means that no devices are present or that an error occurred.


waveOutGetPitch

The waveOutGetPitch function retrieves the current pitch setting for the specified waveform-audio output device.

MMRESULT waveOutGetPitch(

HWAVEOUT hwo,
LPDWORD pdwPitch
);
Parameters

hwo

Handle of the waveform-audio output device.

pdwPitch

Address of a variable to be filled with the current pitch multiplier setting. The pitch multiplier indicates the current change in pitch from the original authored setting. The pitch multiplier must be a positive value.

The pitch multiplier is specified as a fixed-point value. The high-order word of the variable contains the signed integer part of the number, and the low-order word contains the fractional part. A value of 0x8000 in the low-order word represents one-half, and 0x4000 represents one-quarter. For example, the value 0x00010000 specifies a multiplier of 1.0 (no pitch change), and a value of 0x000F8000 specifies a multiplier of 15.5.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED	Function isn’t supported.
Remarks

Changing the pitch does not change the playback rate, sample rate, or playback time. Not all devices support pitch changes. To determine whether the device supports pitch control, use the WAVECAPS_PITCH flag to test the dwSupport member of the WAVEOUTCAPS structure (filled by the waveOutGetDevCaps function).

See Also

WAVEOUTCAPS, waveOutGetDevCaps


waveOutGetPlaybackRate

The waveOutGetPlaybackRate function retrieves the current playback rate for the specified waveform-audio output device.

MMRESULT waveOutGetPlaybackRate(

HWAVEOUT hwo,
LPDWORD pdwRate
);
Parameters

hwo

Handle of the waveform-audio output device.

pdwRate

Address of a variable to be filled with the current playback rate. The playback rate setting is a multiplier indicating the current change in playback rate from the original authored setting. The playback rate multiplier must be a positive value.

The rate is specified as a fixed-point value. The high-order word of the variable contains the signed integer part of the number, and the low-order word contains the fractional part. A value of 0x8000 in the low-order word represents one-half, and 0x4000 represents one-quarter. For example, the value 0x00010000 specifies a multiplier of 1.0 (no playback rate change), and a value of 0x000F8000 specifies a multiplier of 15.5.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED	Function isn’t supported.
Remarks

Changing the playback rate does not change the sample rate but does change the playback time. Not all devices support playback rate changes. To determine whether a device supports playback rate changes, use the WAVECAPS_PLAYBACKRATE flag to test the dwSupport member of the WAVEOUTCAPS structure (filled by the waveOutGetDevCaps function).

See Also

WAVEOUTCAPS, waveOutGetDevCaps


waveOutGetPosition

The waveOutGetPosition function retrieves the current playback position of the given waveform-audio output device.

MMRESULT waveOutGetPosition(

HWAVEOUT hwo,
LPMMTIME pmmt,
UINT cbmmt
);
Parameters

hwo

Handle of the waveform-audio output device.

pmmt

Address of an MMTIME structure.

cbmmt

Size, in bytes, of the MMTIME structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
Remarks

Before calling this function, set the wType member of the MMTIME structure to indicate the time format you want. After calling this function, check wType to determine whether the time format is supported. If the format is not supported, wType will specify an alternative format.

The position is set to zero when the device is opened or reset.

See Also

MMTIME


waveOutGetVolume

The waveOutGetVolume function retrieves the current volume level of the specified waveform-audio output device.

MMRESULT waveOutGetVolume(

HWAVEOUT hwo,
LPDWORD pdwVolume
);
Parameters

hwo

Handle of an open waveform-audio output device. This parameter can also be a device identifier.

pdwVolume

Address of a variable to be filled with the current volume setting. The low-order word of this location contains the left-channel volume setting, and the high-order word contains the right-channel setting. A value of 0xFFFF represents full volume, and a value of 0x0000 is silence.

If a device does not support both left and right volume control, the low-order word of the specified location contains the mono volume level.

The full 16-bit setting(s) set with the waveOutSetVolume function is returned, regardless of whether the device supports the full 16 bits of volume-level control.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED	Function isn’t supported.
Remarks

If a device identifier is used, then the result of the waveOutGetVolume call and the information returned in pdwVolume applies to all instances of the device. If a device handle is used, then the result and information returned applies only to the instance of the device referenced by the device handle.

Not all devices support volume changes. To determine whether the device supports volume control, use the WAVECAPS_VOLUME flag to test the dwSupport member of the WAVEOUTCAPS structure (filled by the waveOutGetDevCaps function).

To determine whether the device supports left- and right-channel volume control, use the WAVECAPS_LRVOLUME flag to test the dwSupport member of the WAVEOUTCAPS structure (filled by waveOutGetDevCaps).

Volume settings are interpreted logarithmically. This means the perceived increase in volume is the same when increasing the volume level from 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.

See Also

waveOutSetVolume, WAVEOUTCAPS, waveOutGetDevCaps


waveOutMessage

The waveOutMessage function sends messages to the waveform-audio output device drivers.

DWORD waveOutMessage(

HWAVEOUT hwo,
UINT uMsg,
DWORD dwParam1,
DWORD dwParam2
);
Parameters

hwo

Handle of the waveform-audio output device.

uMsg

Message to send.

dwParam1 and dwParam2

Message parameters.

Return Values

Returns the value returned from the driver.


waveOutOpen

The waveOutOpen function opens the given waveform-audio output device for playback.

MMRESULT waveOutOpen(

LPHWAVEOUT phwo,
UINT uDeviceID,
LPWAVEFORMATEX pwfx,
DWORD dwCallback,
DWORD dwCallbackInstance,
DWORD fdwOpen
);
Parameters

phwo

Address filled with a handle identifying the open waveform-audio output device. Use the handle to identify the device when calling other waveform-audio output functions. This parameter might be NULL if the WAVE_FORMAT_QUERY flag is specified for fdwOpen.

uDeviceID

Identifier of the waveform-audio output device to open. It can be either a device identifier or a handle of an open waveform-audio input device.You can use the following flag instead of a device identifier:

WAVE_MAPPER

The function selects a waveform-audio output device capable of playing the given format.

pwfx

Address of a WAVEFORMATEX structure that identifies the format of the waveform-audio data to be sent to the device. You can free this structure immediately after passing it to waveOutOpen.

dwCallback

Address of a fixed callback function, an event handle, a handle to a window, or the identifier of a thread to be called during waveform-audio playback to process messages related to the progress of the playback. If no callback function is required, this value can be zero. For more information on the callback function, see waveOutProc.

dwCallbackInstance

User-instance data passed to the callback mechanism. This parameter is not used with the window callback mechanism.

fdwOpen

Flags for opening the device. The following values are defined:

CALLBACK_EVENT

The dwCallback parameter is an event handle.

CALLBACK_FUNCTION

The dwCallback parameter is a callback procedure address.

CALLBACK_NULL

No callback mechanism. This is the default setting.

CALLBACK_THREAD

The dwCallback parameter is a thread identifier.

CALLBACK_WINDOW

The dwCallback parameter is a window handle.

WAVE_ALLOWSYNC

If this flag is specified, a synchronous waveform-audio device can be opened. If this flag is not specified while opening a synchronous driver, the device will fail to open.

WAVE_FORMAT_DIRECT

If this flag is specified, the ACM driver does not perform conversions on the audio data.

WAVE_FORMAT_QUERY

If this flag is specified, waveOutOpen queries the device to determine if it supports the given format, but the device is not actually opened.

WAVE_MAPPED

If this flag is specified, the uDeviceID parameter specifies a waveform-audio device to be mapped to by the wave mapper.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_ALLOCATED	Specified resource is already allocated.
MMSYSERR_BADDEVICEID	Specified device identifier is out of range.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
WAVERR_BADFORMAT	Attempted to open with an unsupported waveform-audio format.
WAVERR_SYNC	The device is synchronous but waveOutOpen was called without using the WAVE_ALLOWSYNC flag.
Remarks

Use the waveOutGetNumDevs function to determine the number of waveform-audio output devices present in the system. If the value specified by the uDeviceID parameter is a device identifier, it can vary from zero to one less than the number of devices present. The WAVE_MAPPER constant can also be used as a device identifier.

The structure pointed to by pwfx can be extended to include type-specific information for certain data formats. For example, for PCM data, an extra UINT is added to specify the number of bits per sample. Use the PCMWAVEFORMAT structure in this case. For all other waveform-audio formats, use the WAVEFORMATEX structure to specify the length of the additional data.

If you choose to have a window or thread receive callback information, the following messages are sent to the window procedure function to indicate the progress of waveform-audio output: MM_WOM_OPEN, MM_WOM_CLOSE, and MM_WOM_DONE.

If you choose to have a function receive callback information, the following messages are sent to the function to indicate the progress of waveform-audio output: WOM_OPEN, WOM_CLOSE, and WOM_DONE.

See Also

WAVEFORMATEX, waveOutGetNumDevs, waveOutProc, PCMWAVEFORMAT, MM_WOM_OPEN, MM_WOM_CLOSE, MM_WOM_DONE


waveOutPause

The waveOutPause function pauses playback on the given waveform-audio output device. The current position is saved. Use the waveOutRestart function to resume playback from the current position.

MMRESULT waveOutPause(

HWAVEOUT hwo
);
Parameters

hwo

Handle of the waveform-audio output device.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED	Specified device is synchronous and does not support pausing.
Remarks

Calling this function when the output is already paused has no effect, and the function returns zero.

See Also

waveOutRestart


waveOutPrepareHeader

The waveOutPrepareHeader function prepares a waveform-audio data block for playback.

MMRESULT waveOutPrepareHeader(

HWAVEOUT hwo,
LPWAVEHDR pwh,
UINT cbwh
);
Parameters

hwo

Handle of the waveform-audio output device.

pwh

Address of a WAVEHDR structure that identifies the data block to be prepared.

cbwh

Size, in bytes, of the WAVEHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
Remarks

The lpData, dwBufferLength, and dwFlags members of the WAVEHDR structure must be set before calling this function (dwFlags must be zero).

The dwFlags, dwBufferLength, and dwLoops members of the WAVEHDR structure can change between calls to this function and the waveOutWrite function. (The only flags that can change in this interval for the dwFlags member are WHDR_BEGINLOOP and WHDR_ENDLOOP.) If you change the size specified by dwBufferLength before the call to waveOutWrite, the new value must be less than the prepared value.

Preparing a header that has already been prepared has no effect, and the function returns zero.

See Also

WAVEHDR, waveOutWrite


waveOutProc

The waveOutProc function is the callback function used with the waveform-audio output device. The waveOutProc function is a placeholder for the application-defined function name. The address of this function can be specified in the callback-address parameter of the waveOutOpen function.

void CALLBACK waveOutProc(

HWAVEOUT hwo,
UINT uMsg,
DWORD dwInstance,
DWORD dwParam1,
DWORD dwParam2
);
Parameters

hwo

Handle of the waveform-audio device associated with the callback.

uMsg

Waveform-audio output message. It can be one of the following values:

WOM_CLOSE

Sent when the device is closed using the waveOutClose function.

WOM_DONE

Sent when the device driver is finished with a data block sent using the waveOutWrite function.

WOM_OPEN

Sent when the device is opened using the waveOutOpen function.

dwInstance

User-instance data specified with waveOutOpen.

dwParam1

Message parameters.

dwParam2

Message parameters.

Return Values

This function does not return a value.

Remarks

Applications should not call any system-defined functions from inside a callback function, except for EnterCriticalSection, LeaveCriticalSection, midiOutLongMsg, midiOutShortMsg, OutputDebugString, PostMessage, PostThreadMessage, SetEvent, timeGetSystemTime, timeGetTime, timeKillEvent, and timeSetEvent. Calling other wave functions will cause deadlock.

See Also

EnterCriticalSection, LeaveCriticalSection, midiOutLongMsg, midiOutShortMsg, OutputDebugString, PostMessage, PostThreadMessage, SetEvent, timeGetSystemTime, timeGetTime, timeKillEvent, timeSetEvent, waveOutClose, waveOutOpen, waveOutWrite, WOM_CLOSE, WOM_DONE, WOM_OPEN


waveOutReset

The waveOutReset function stops playback on the given waveform-audio output device and resets the current position to zero. All pending playback buffers are marked as done and returned to the application.

MMRESULT waveOutReset(

HWAVEOUT hwo
);
Parameters

hwo

Handle of the waveform-audio output device.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED	Specified device is synchronous and does not support pausing.


waveOutRestart

The waveOutRestart function resumes playback on a paused waveform-audio output device.

MMRESULT waveOutRestart(

HWAVEOUT hwo
);
Parameters

hwo

Handle of the waveform-audio output device.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED	Specified device is synchronous and does not support pausing.
Remarks

Calling this function when the output is not paused has no effect, and the function returns zero.


waveOutSetPitch

The waveOutSetPitch function sets the pitch for the specified waveform-audio output device.

MMRESULT waveOutSetPitch(

HWAVEOUT hwo,
DWORD dwPitch
);
Parameters

hwo

Handle of the waveform-audio output device.

dwPitch

New pitch multiplier setting. This setting indicates the current change in pitch from the original authored setting. The pitch multiplier must be a positive value.

The pitch multiplier is specified as a fixed-point value. The high-order word contains the signed integer part of the number, and the low-order word contains the fractional part. A value of 0x8000 in the low-order word represents one-half, and 0x4000 represents one-quarter. For example, the value 0x00010000 specifies a multiplier of 1.0 (no pitch change), and a value of 0x000F8000 specifies a multiplier of 15.5.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED	Function isn’t supported.
Remarks

Changing the pitch does not change the playback rate or the sample rate, nor does it change the playback time. Not all devices support pitch changes. To determine whether the device supports pitch control, use the WAVECAPS_PITCH flag to test the dwSupport member of the WAVEOUTCAPS structure (filled by the waveOutGetDevCaps function).

See Also

WAVEOUTCAPS, waveOutGetDevCaps


waveOutSetPlaybackRate

The waveOutSetPlaybackRate function sets the playback rate for the specified waveform-audio output device.

MMRESULT waveOutSetPlaybackRate(

HWAVEOUT hwo,
DWORD dwRate
);
Parameters

hwo

Handle of the waveform-audio output device.

dwRate

New playback rate setting. This setting is a multiplier indicating the current change in playback rate from the original authored setting. The playback rate multiplier must be a positive value.

The rate is specified as a fixed-point value. The high-order word contains the signed integer part of the number, and the low-order word contains the fractional part. A value of 0x8000 in the low-order word represents one-half, and 0x4000 represents one-quarter. For example, the value 0x00010000 specifies a multiplier of 1.0 (no playback rate change), and a value of 0x000F8000 specifies a multiplier of 15.5.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED	Function isn’t supported.
Remarks

Changing the playback rate does not change the sample rate but does change the playback time. Not all devices support playback rate changes. To determine whether a device supports playback rate changes, use the WAVECAPS_PLAYBACKRATE flag to test the dwSupport member of the WAVEOUTCAPS structure (filled by the waveOutGetDevCaps function).

See Also

WAVEOUTCAPS, waveOutGetDevCaps


waveOutSetVolume

The waveOutSetVolume function sets the volume level of the specified waveform-audio  output device.

MMRESULT waveOutSetVolume(

HWAVEOUT hwo,
DWORD dwVolume
);
Parameters

hwo

Handle of an open waveform-audio output device. This parameter can also be a device identifier.

dwVolume

New volume setting. The low-order word contains the left-channel volume setting, and the high-order word contains the right-channel setting. A value of 0xFFFF represents full volume, and a value of 0x0000 is silence.

If a device does not support both left and right volume control, the low-order word of dwVolume specifies the volume level, and the high-order word is ignored.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED	Function is not supported.
Remarks

If a device identifier is used, then the result of the waveOutSetVolume call applies to all instances of the device. If a device handle is used, then the result applies only to the instance of the device referenced by the device handle.

Not all devices support volume changes. To determine whether the device supports volume control, use the WAVECAPS_VOLUME flag to test the dwSupport member of the WAVEOUTCAPS structure (filled by the waveOutGetDevCaps function). To determine whether the device supports volume control on both the left and right channels, use the WAVECAPS_LRVOLUME flag.

Most devices do not support the full 16 bits of volume-level control and will not use the high-order bits of the requested volume setting. For example, for a device that supports 4 bits of volume control, requested volume level values of 0x4000, 0x4FFF, and 0x43BE all produce the same physical volume setting: 0x4000. The waveOutGetVolume function returns the full 16-bit setting set with waveOutSetVolume.

Volume settings are interpreted logarithmically. This means the perceived increase in volume is the same when increasing the volume level from 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.

See Also

WAVEOUTCAPS, waveOutGetDevCaps, waveOutGetVolume


waveOutUnprepareHeader

The waveOutUnprepareHeader function cleans up the preparation performed by the waveOutPrepareHeader function. This function must be called after the device driver is finished with a data block. You must call this function before freeing the buffer.

MMRESULT waveOutUnprepareHeader(

HWAVEOUT hwo,
LPWAVEHDR pwh,
UINT cbwh
);
Parameters

hwo

Handle of the waveform-audio output device.

pwh

Address of a WAVEHDR structure identifying the data block to be cleaned up.

cbwh

Size, in bytes, of the WAVEHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
WAVERR_STILLPLAYING	The data block pointed to by the pwh parameter is still in the queue.
Remarks

This function complements waveOutPrepareHeader. You must call this function before freeing the buffer. After passing a buffer to the device driver with the waveOutWrite function, you must wait until the driver is finished with the buffer before calling waveOutUnprepareHeader.

Unpreparing a buffer that has not been prepared has no effect, and the function returns zero.

See Also

waveOutPrepareHeader, WAVEHDR, waveOutWrite


waveOutWrite

The waveOutWrite function sends a data block to the given waveform-audio output device.

MMRESULT waveOutWrite(

HWAVEOUT hwo,
LPWAVEHDR pwh,
UINT cbwh
);
Parameters

hwo

Handle of the waveform-audio output device.

pwh

Address of a WAVEHDR structure containing information about the data block.

cbwh

Size, in bytes, of the WAVEHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMSYSERR_INVALHANDLE	Specified device handle is invalid.
MMSYSERR_NODRIVER	No device driver is present.
MMSYSERR_NOMEM	Unable to allocate or lock memory.
WAVERR_UNPREPARED	The data block pointed to by the pwh parameter hasn’t been prepared.
Remarks

When the buffer is finished, the WHDR_DONE bit is set in the dwFlags member of the WAVEHDR structure.

The buffer must be prepared with the waveOutPrepareHeader function before it is passed to waveOutWrite. Unless the device is paused by calling the waveOutPause function, playback begins when the first data block is sent to the device.

See Also

WAVEHDR, waveOutPrepareHeader, waveOutPause


AVIStreamDataSize

The AVIStreamDataSize macro determines the buffer size, in bytes, needed to retrieve optional header data for a specified stream.

AVIStreamDataSize(

pavi,
fcc,
plSize
);
Parameters

pavi

Handle of an open stream.

fcc

Four-character code specifying the stream type.

plSize

Address to contain the buffer size for the optional header data.

Return Values

Returns zero if successful or an error otherwise. The return value AVIERR_NODATA indicates the system could not find any data with the specified four-character code.

Remarks

The AVIStreamDataSize macro is defined as follows:

#define AVIStreamDataSize(pavi, fcc, plSize) \

    AVIStreamReadData(pavi, fcc, NULL, plSize)


AVIStreamEnd

The AVIStreamEnd macro calculates the sample associated with the end of a stream.

AVIStreamEnd(

pavi
);
Parameters

pavi

Handle of an open stream.

Return Values

Returns the sample number associated with the end of a stream, or, if an error occurs, one less than the first sample or one less than the stream length.

Remarks

The sample number returned is not a valid sample number for reading data. It represents the end of the file. (The end of the file is equal to the start of the file plus its length.)

The AVIStreamEnd macro is defined as follows:

#define AVIStreamEnd(pavi) \

    (AVIStreamStart(pavi) + AVIStreamLength(pavi))


AVIStreamEndTime

The AVIStreamEndTime macro returns the time representing the end of the stream.

AVIStreamEndTime(

pavi
);
Parameters

pavi

Handle of an open stream.

Return Value

Returns the time if successful or  − 1 otherwise.

Remarks

The AVIStreamEndTime macro is defined as follows:

#define AVIStreamEndTime(pavi) \

    AVIStreamSampleToTime(pavi, AVIStreamEnd(pavi))


AVIStreamFormatSize

The AVIStreamFormatSize macro determines the buffer size, in bytes, needed to store format information for a sample in a stream.

AVIStreamFormatSize(

pavi,
lPos,
plSize
);
Parameters

pavi

Handle of an open stream.

lPos

Position of a sample in the stream.

plSize

Address to contain the buffer size.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The AVIStreamFormatSize macro is defined as follows:

#define AVIStreamFormatSize(pavi, lPos, plSize) \

    AVIStreamReadFormat(pavi, lPos, NULL, plSize)


AVIStreamIsKeyFrame

The AVIStreamIsKeyFrame macro indicates whether a sample in a specified stream is a key frame.

AVIStreamIsKeyFrame(

pavi,
lPos
);
Parameters

pavi

Handle of an open stream.

lPos

Position to search in the stream.

Return Values

Returns TRUE if the sample is a key frame or FALSE otherwise.

Remarks

The AVIStreamIsKeyFrame macro is defined as follows:

#define AVIStreamIsKeyFrame(pavi, lPos) \

    (AVIStreamNearestKeyFrame(pavi, lPos) == 1)


AVIStreamLengthTime

The AVIStreamLengthTime macro returns the length of a stream in time.

AVIStreamLengthTime(

pavi
);
Parameters

pavi

Handle of an open stream.

Return Values

Returns the time if successful or   − 1 otherwise.

Remarks

The AVIStreamLengthTime macro is defined as follows:

#define AVIStreamLengthTime(pavi) \

    AVIStreamSampleToTime(pavi, AVIStreamLength(pavi))


AVIStreamNearestKeyFrame

The AVIStreamNearestKeyFrame macro locates the key frame at or preceding a specified position in a stream.

AVIStreamNearestKeyFrame(

pavi,
lPos
);
Parameters

pavi

Handle of an open stream.

lPos

Starting position to search in the stream.

Return Values

Returns the position of the key frame if successful or  − 1 otherwise.

Remarks

The AVIStreamNearestKeyFrame macro is defined as follows:

#define AVIStreamNearestKeyFrame(pavi, lPos) \

    AVIStreamFindSample(pavi, lPos , FIND_PREV | FIND_KEY)


AVIStreamNearestKeyFrameTime

The AVIStreamNearestKeyFrameTime macro determines the time corresponding to the beginning of the key frame nearest (at or preceding) a specified time in a stream.

AVIStreamNearestKeyFrameTime(

pavi,
lTime
);
Parameters

pavi

Handle of an open stream.

lTime

Starting time, in milliseconds, to search in the stream.

Return Values

Returns the time of the nearest key frame if successful or  − 1 otherwise.

Remarks

The AVIStreamNearestKeyFrameTime macro is defined as follows:

#define AVIStreamNearestKeyFrameTime(pavi, lTime) \

    AVIStreamSampleToTime(pavi, AVIStreamNearestKeyFrame(pavi,

    AVIStreamTimeToSample(pavi, lTime)))


AVIStreamNearestSample

The AVIStreamNearestSample macro locates the nearest nonempty sample at or preceding a specified position in a stream.

AVIStreamNearestSample(

pavi,
lPos
);
Parameters

pavi

Handle of an open stream.

lPos

Starting position to search in the stream.

Return Values

Returns the sample position if successful or -1 otherwise.

Remarks

The AVIStreamNearestSample macro is defined as follows:

#define AVIStreamNearestSample(pavi, lPos) \

    AVIStreamFindSample(pavi, lPos, FIND_PREV | FIND_ANY)


AVIStreamNearestSampleTime

The AVIStreamNearestSampleTime macro determines the time corresponding to the beginning of a sample that is nearest to a specified time in a stream.

AVIStreamNearestSampleTime(

pavi,
lTime
);
Parameters

pavi

Handle of an open stream.

lTime

Starting time, in milliseconds, to search in the stream.

Return Values

Returns the time of the nearest sample if successful or − 1 otherwise.

Remarks

The AVIStreamNearestSampleTime macro is defined as follows:

#define AVIStreamNearestSampleTime(pavi, lTime) \

    AVIStreamSampleToTime(pavi, AVIStreamNearestSample(pavi,

    AVIStreamTimeToSample(pavi, lTime)))


AVIStreamNextKeyFrame

The AVIStreamNextKeyFrame macro locates the next key frame following a specified position in a stream.

AVIStreamNextKeyFrame(

pavi,
lPos
);
Parameters

pavi

Handle of an open stream.

lPos

Starting position to search in the stream.

Return Values

Returns the position of the key frame if successful or  − 1 otherwise.

Remarks

The search performed by this macro does not include the frame at the specified position.

The AVIStreamNextKeyFrame macro is defined as follows:

#define AVIStreamNextKeyFrame(pavi, lPos) \

    AVIStreamFindSample(pavi, lPos + 1, FIND_NEXT | FIND_KEY)


AVIStreamNextKeyFrameTime

The AVIStreamNextKeyFrameTime macro returns the time of the next key frame in the stream, starting at a given time.

AVIStreamNextKeyFrameTime(

pavi,
time
);
Parameters

pavi

Handle of an open stream.

time

Position in the stream to begin searching.

Return Values

Returns the time if successful or  − 1 otherwise.

Remarks

The search performed by this macro includes the frame that corresponds to the specified time.

The AVIStreamNextKeyFrameTime macro is defined as follows:

#define AVIStreamNextKeyFrameTime(pavi, time) \

    AVIStreamSampleToTime(pavi, \

    AVIStreamNextKeyFrame(pavi, \

    AVIStreamTimeToSample(pavi, time)))


AVIStreamNextSample

The AVIStreamNextSample macro locates the next nonempty sample from a specified position in a stream.

AVIStreamNextSample(

pavi,
lPos
);
Parameters

pavi

Handle of an open stream.

lPos

Starting position to search in the stream.

Return Values

Returns the sample position if successful or  − 1 otherwise.

Remarks

The sample position returned does not include the sample specified by lPos.

The AVIStreamNextSample macro is defined as follows:

#define AVIStreamNextSample(pavi, lPos) \

    AVIStreamFindSample(pavi, lPos + 1, FIND_NEXT | FIND_ANY)


AVIStreamNextSampleTime

The AVIStreamNextSampleTime macro returns the time that a sample changes to the next sample in the stream. This macro finds the the next interesting time in a stream.

AVIStreamNextSampleTime(

pavi,
time
);
Parameters

pavi

Handle of an open stream.

time

Position information of the sample in the stream.

Return Values

Returns the time if successful or − 1 otherwise.

Remarks

The AVIStreamNextSampleTime macro is defined as follows:

#define AVIStreamNextSampleTime(pavi, time) \

    AVIStreamSampleToTime(pavi, \

    AVIStreamNextSample(pavi, \

    AVIStreamTimeToSample(pavi, t)))


AVIStreamPrevKeyFrame

The AVIStreamPrevKeyFrame macro locates the key frame that precedes a specified position in a stream.

AVIStreamPrevKeyFrame(

pavi,
lPos
);
Parameters

pavi

Handle of an open stream.

lPos

Starting position to search in the stream.

Return Values

Returns the position of the key frame if successful or − 1 otherwise.

Remarks

The search performed by this macro does not include the frame at the specified position.

The AVIStreamPrevKeyFrame macro is defined as follows:

#define AVIStreamPrevKeyFrame(pavi, lPos) \

    AVIStreamFindSample(pavi, lPos - 1, FIND_PREV | FIND_KEY)


AVIStreamPrevKeyFrameTime

The AVIStreamPrevKeyFrameTime macro returns the time of the previous key frame in the stream, starting at a given time.

AVIStreamPrevKeyFrameTime(

pavi,
time
);
Parameters

pavi

Handle of an open stream.

time

Position in the stream to begin searching.

Return Values

Returns the time if successful or − 1 otherwise.

Remarks

The search performed by this macro includes the frame that corresponds to the specified time.

The AVIStreamPrevKeyFrameTime macro is defined as follows:

#define AVIStreamPrevKeyFrameTime(pavi, time) \

    AVIStreamSampleToTime(pavi, AVIStreamPrevKeyFrame(pavi,
    AVIStreamTimeToSample(pavi, time)))


AVIStreamPrevSample

The AVIStreamPrevSample macro locates the nearest nonempty sample that precedes a specified position in a stream.

AVIStreamPrevSample(

pavi,
lPos
);
Parameters

pavi

Handle of an open stream.

lPos

Starting position to search in the stream.

Return Values

Returns the sample position if successful or − 1 otherwise.

Remarks

The sample position returned does not include the sample specified by lPos.

The AVIStreamPrevSample macro is defined as follows:

#define AVIStreamPrevSample(pavi, lPos) \

    AVIStreamFindSample(pavi, lPos - 1, FIND_PREV | FIND_ANY)


AVIStreamPrevSampleTime

The AVIStreamPrevSampleTime macro determines the time of the nearest nonempty sample that precedes a specified time in a stream.

AVIStreamPrevSampleTime(

pavi,
time
);
Parameters

pavi

Handle of an open stream.

time

Position information of the sample in the stream.

Return Values

Returns the time if successful or − 1 otherwise.

Remarks

The AVIStreamPrevSampleTime macro is defined as follows:

#define AVIStreamPrevSampleTime(pavi, time) \

    AVIStreamSampleToTime(pavi, \

    AVIStreamPrevSample(pavi, \

    AVIStreamTimeToSample(pavi, t)))


AVIStreamSampleSize

The AVIStreamRelease macro determines the size of the buffer needed to store one sample of information from a stream. The size corresponds to the sample at the position specified by lPos.

AVIStreamSampleSize(

pavi,
lPos,
plSize
);
Parameters

pavi

Handle of an open stream.

lPos

Position of a sample in the stream.

plSize

Address to contain the buffer size.

Return Values

Returns zero if successful or an error otherwise. Possible error values include the following:

AVIERR_BUFFERTOOSMALL	The buffer size was smaller than a single sample of data.
AVIERR_MEMORY	There was not enough memory to complete the read operation.
AVIERR_FILEREAD	A disk error occurred while reading the file.
Remarks

The AVIStreamSampleSize macro is defined as follows:

#define AVIStreamSampleSize(pavi, lPos, plSize) \

    AVIStreamRead(pavi, lPos, 1, NULL, 0, plSize, NULL)


AVIStreamSampleToSample

The AVIStreamSampleToSample macro returns the sample in a stream that occurs at the same time as a sample that occurs in a second stream.

AVIStreamSampleToSample(

pavi1,
pavi2,
lSample
);
Parameters

pavi1

Handle of an open stream that contains the sample that is returned.

pavi2

Handle of a second stream that contains the reference sample.

lSample

Position information of the sample in the stream referenced by pavi2.

Return Values

Returns the sample if successful or − 1 otherwise.

Remarks

The AVIStreamSampleToSample macro is defined as follows:

#define AVIStreamSampleToSample(pavi1, pavi2, lsample) \

    AVIStreamTimeToSample(pavi1, AVIStreamSampleToTime \

    (pavi2, lsample))


AVIStreamStartTime

The AVIStreamStartTime macro returns the starting time of a stream’s first sample.

AVIStreamStartTime(

pavi
);
Parameters

pavi

Handle of an open stream.

Return Values

Returns the time if successful or − 1 otherwise.

Remarks

The AVIStreamStartTime macro is defined as follows:

#define AVIStreamStartTime(pavi) \

    AVIStreamSampleToTime(pavi, AVIStreamStart(pavi))


capCaptureAbort

The capCaptureAbort macro stops the capture operation. You can use this macro or explictly send the WM_CAP_ABORT message.

BOOL capCaptureAbort(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The capture operation must yield to use this macro.

In the case of step capture, the image data collected up to the point of the capCaptureAbort macro will be retained in the capture file, but audio will not be captured.

Use the capCaptureStop macro to halt step capture at the current position, and then capture audio.

See Also

capCaptureStop, WM_CAP_ABORT


capCaptureGetSetup

The capCaptureGetSetup macro retrieves the current settings of the streaming capture parameters. You can use this macro or explictly send the WM_CAP_GET_SEQUENCE_SETUP message.

BOOL capCaptureGetSetup(

hwnd,
s,
wSize
);
Parameters

hwnd

Handle of a capture window.

wSize

Size, in bytes, of the structure referenced by s.

s

Address of a CAPTUREPARMS structure.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

For information about the parameters used to control streaming capture, see the CAPTUREPARMS structure.

See Also

CAPTUREPARMS, WM_CAP_GET_SEQUENCE_SETUP


capCaptureSequence

The capCaptureSequence macro initiates streaming video and audio capture to a file. You can use this macro or explicitly send the WM_CAP_SEQUENCE message.

BOOL capCaptureSequence(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the capSetCallbackOnError macro, the error callback function is called.

Remarks

If you want to alter the parameters controlling streaming capture, use the capCaptureSetSetup macro prior to starting the capture.

By default, the capture window does not allow other applications to continue running during capture. To override this, either set the fYield member of the CAPTUREPARMS structure to TRUE, or install a yield callback function.

During streaming capture, the capture window can optionally issue notifications to your application of specific types of conditions. To install callback procedures for these notifications, use the following macros:

capSetCallbackOnError
capSetCallbackOnStatus
capSetCallbackOnVideoStream
capSetCallbackOnWaveStream
capSetCallbackOnYield

See Also

capCaptureSetSetup, capSetCallbackOnError, capSetCallbackOnStatus, capSetCallbackOnVideoStream, capSetCallbackOnWaveStream, capSetCallbackOnYield, CAPTUREPARMS, WM_CAP_SEQUENCE


capCaptureSequenceNoFile

The capCaptureSequenceNoFile macro initiates streaming video capture without writing data to a file. You can use this macro or explicitly send the WM_CAP_SEQUENCE_NOFILE message.

BOOL capCaptureSequenceNoFile(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

This message is useful in conjunction with video stream or waveform-audio stream callback functions that let your application use the video and audio data directly.

If you want to alter the parameters controlling streaming capture, use the capCaptureSetSetup macro prior to starting the capture.

By default, the capture window does not allow other applications to continue running during capture. To override this, either set the fYield member of the CAPTUREPARMS structure to TRUE, or install a yield callback function.

During streaming capture, the capture window can optionally issue notifications to your application of specific types of conditions. To install callback procedures for these notifications, use the following macros:

capSetCallbackOnError
capSetCallbackOnStatus
capSetCallbackOnVideoStream
capSetCallbackOnWaveStream
capSetCallbackOnYield

See Also

capCaptureSetSetup, capSetCallbackOnError, capSetCallbackOnStatus, capSetCallbackOnVideoStream, capSetCallbackOnWaveStream, capSetCallbackOnYield, CAPTUREPARMS, WM_CAP_SEQUENCE_NOFILE


capCaptureSetSetup

The capCaptureSetSetup macro sets the configuration parameters used with streaming capture. You can use this macro or explicitly send the WM_CAP_SET_SEQUENCE_SETUP message.

BOOL capCaptureSetSetup(

hwnd,
psCapParms,
wSize
);
Parameters

hwnd

Handle of a capture window.

psCapParms

Address of a CAPTUREPARMS structure.

wSize

Size, in bytes, of the structure referenced by s.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

For information about the parameters used to control streaming capture, see the CAPTUREPARMS structure.

See Also

CAPTUREPARMS, WM_CAP_SET_SEQUENCE_SETUP


capCaptureSingleFrame

The capCaptureSingleFrame macro appends a single frame to a capture file that was opened using the capCaptureSingleFrameOpen macro. You can use this macro or explicitly send the WM_CAP_SINGLE_FRAME message.

BOOL capCaptureSingleFrame(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

capCaptureSingleFrameOpen WM_CAP_SINGLE_FRAME


capCaptureSingleFrameClose

The capCaptureSingleFrameClose macro closes the capture file opened by the capCaptureSingleFrameOpen macro. You can use this macro or explicitly send the WM_CAP_SINGLE_FRAME_CLOSE message.

BOOL capCaptureSingleFrameClose(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

For information about installing callback functions, see the capSetCallbackOnErrror and capSetCallbackOnFrame macros.

See Also

capCaptureSingleFrameOpen, capSetCallbackOnError, capSetCallbackOnFrame, WM_CAP_SINGLE_FRAME_CLOSE


capCaptureSingleFrameOpen

The capCaptureSingleFrameOpen macro opens the capture file for single-frame capturing. Any previous information in the capture file is overwritten. You can use this macro or explicitly send the WM_CAP_SINGLE_FRAME_OPEN message.

BOOL capCaptureSingleFrameOpen(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

For information about installing callback functions, see the capSetCallbackOnError and capSetCallbackOnFrame macros.

See Also

capSetCallbackOnError, capSetCallbackOnFrame, WM_CAP_SINGLE_FRAME_OPEN


capCaptureStop

The capCaptureStop macro stops the capture operation. You can use this macro or explicitly send the WM_CAP_STOP message.

In step frame capture, the image data that was collected before this message was sent is retained in the capture file. An equivalent duration of audio data is also retained in the capture file if audio capture was enabled.

BOOL capCaptureStop(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The capture operation must yield to use this message. Use the capCaptureAbort macro to abandon the current capture operation.

See Also

capCaptureAbort, WM_CAP_STOP


capDlgVideoCompression

The capDlgVideoCompresion macro displays a dialog box in which the user can select a compressor to use during the capture process. The list of available compressors can vary with the video format selected in the capture driver's Video Format dialog box. You can use this macro or explicitly send the WM_CAP_DLG_VIDEOCOMPRESSION message.

BOOL capDlgVideoCompression(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

Use this message with capture drivers that provide frames only in the BI_RGB format. This message is most useful in the step capture operation to combine capture and compression in a single operation. Compressing frames with a software compressor as part of a real-time capture operation is most likely too time-consuming to perform.

Compression does not affect the frames copied to the clipboard.

See Also

WM_CAP_DLG_VIDEOCOMPRESSION


capDlgVideoDisplay

The capDlgVideoDisplay macro displays a dialog box in which the user can set or adjust the video output. This dialog box might contain controls that affect the hue, contrast, and brightness of the displayed image, as well as key color alignment. You can use this macro or explicitly send the WM_CAP_DLG_VIDEODISPLAY message.

BOOL capDlgVideoDisplay(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The controls in this dialog box do not affect digitized video data; they affect only the output or redisplay of the video signal.

The Video Display dialog box is unique for each capture driver. Some capture drivers might not support a Video Display dialog box. Applications can determine if the capture driver supports this message by checking the fHasDlgVideoDisplay member of the CAPDRIVERCAPS structure.

See Also

CAPDRIVERCAPS, WM_CAP_DLG_VIDEODISPLAY


capDlgVideoFormat

The capDlgVideoFormat macro displays a dialog box in which the user can select the video format. The Video Format dialog box might be used to select image dimensions, bit depth, and hardware compression options. You can use this macro or explicitly send the WM_CAP_DLG_VIDEOFORMAT message.

BOOL capDlgVideoFormat(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

After this message returns, applications might need to update the CAPSTATUS structure because the user might have changed the image dimensions.

The Video Format dialog box is unique for each capture driver. Some capture drivers might not support a Video Format dialog box. Applications can determine if the capture driver supports this message by checking the fHasDlgVideoFormat member of CAPDRIVERCAPS.

See Also

CAPDRIVERCAPS, CAPSTATUS, WM_CAP_DLG_VIDEOFORMAT


capDlgVideoSource

The capDlgVideoSource macro displays a dialog box in which the user can control the video source. The Video Source dialog box might contain controls that select input sources; alter the hue, contrast, brightness of the image; and modify the video quality before digitizing the images into the frame buffer. You can use this macro or explicitly send the WM_CAP_DLG_VIDEOSOURCE message.

BOOL capDlgVideoSource(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The Video Source dialog box is unique for each capture driver. Some capture drivers might not support a Video Source dialog box. Applications can determine if the capture driver supports this message by checking the fHasDlgVideoSource member of the CAPDRIVERCAPS structure.

See Also

CAPDRIVERCAPS, WM_CAP_DLG_VIDEOSOURCE


capDriverConnect

The capDriverConnect macro connects a capture window to a capture driver. You can use this macro or explicitly send the WM_CAP_DRIVER_CONNECT message.

BOOL capDriverConnect(

hwnd,
iIndex
);
Parameters

iIndex

Index of the capture driver. The index can range from 0 through 9.

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE if the specified capture driver cannot be connected to the capture window.

Remarks

Connecting a capture driver to a capture window automatically disconnects any previously connected capture driver.

See Also

WM_CAP_DRIVER_CONNECT


capDriverDisconnect

The capDriverDisconnect macro disconnects a capture driver from a capture window. You can use this macro or explicitly send the WM_CAP_DRIVER_DISCONNECT message.

BOOL capDriverDisconnect(

hwnd
);
Parameters

Return Values

Returns TRUE if successful or FALSE if the capture window is not connected to a capture driver.

See Also

WM_CAP_DRIVER_DISCONNECT


capDriverGetCaps

The capDriverGetCaps macro returns the hardware capabilities of the capture driver currently connected to a  capture window. You can use this macro or explicitly send the WM_CAP_DRIVER_GET_CAPS message.

capDriverGetCaps(

hwnd,
psCaps,
wSize
);
Parameters

hwnd

Handle of a capture window.

wSize

Size, in bytes, of the structure referenced by s.

psCaps

Address of the CAPDRIVERCAPS structure to contain the hardware capabilities.

Return Values

Returns TRUE if successful or FALSE if the capture window is not connected to a capture driver.

Remarks

The capabilities returned in CAPDRIVERCAPS are constant for a given capture driver. Applications need to retrieve this information once when the capture driver is first connected to a capture window.

See Also

CAPDRIVERCAPS, WM_CAP_DRIVER_GET_CAPS


capDriverGetName

The capDriverGetName macro returns the name of the capture driver connected to the capture window. You can use this macro or explicitly call the WM_CAP_DRIVER_GET_NAME message.

BOOL capDriverGetName(

hwnd,
szName,
wSize
);
Parameters

hwnd

Handle of a capture window.

wSize

Size, in bytes, of the buffer referenced by szName.

szName

Address of an application-defined buffer used to return the device name as a null-terminated string.

Return Values

Returns TRUE if successful or FALSE if the capture window is not connected to a capture driver.

Remarks

The name is a text string retrieved from the driver’s resource area. Applications should allocate approximately 80 bytes for this string. If the driver does not contain a name resource, the full path name of the driver listed in the registry or in the SYSTEM.INI file is returned.

See Also

WM_CAP_DRIVER_GET_NAME


capDriverGetVersion

The capDriverGetVersion macro returns the version information of the capture driver connected to a capture window. You can use this macro or explicitly send the WM_CAP_DRIVER_GET_VERSION message.

BOOL capDriverGetVersion(

hwnd,
szVer,
wSize
);
Parameters

wSize

Size, in bytes, of the application-defined buffer referenced by szVer.

szVer

Address of an application-defined buffer used to return the version information as a null-terminated string.

Return Values

Returns TRUE if successful or FALSE if the capture window is not connected to a capture driver.

Remarks

The version information is a text string retrieved from the driver’s resource area. Applications should allocate approximately 40 bytes for this string. If version information is not available, a NULL string is returned.

See Also

WM_CAP_DRIVER_GET_VERSION


capEditCopy

The capEditCopy macro copies the contents of the video frame buffer and associated palette to the clipboard. You can use this macro or explicitly send the WM_CAP_EDIT_COPY message.

BOOL capEditCopy(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

WM_CAP_EDIT_COPY


capFileAlloc

The capFileAlloc macro creates (preallocates) a capture file of a specified size. You can use this macro or explicitly send the WM_CAP_FILE_ALLOCATE message.

BOOL capFileAlloc(

hwnd,
dwSize
);
Parameters

hwnd

Handle of a capture window.

dwSize

Size, in bytes, to create the capture file.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the capSetCallbackOnError macro, the error callback function is called.

Remarks

You can improve streaming capture performance significantly by preallocating a capture file large enough to store an entire video clip and by defragmenting the capture file before capturing the clip.

See Also

capSetCallbackOnError, WM_CAP_FILE_ALLOCATE


capFileGetCaptureFile

The capFileGetCaptureFile macro returns the name of the current capture file. You can use this macro or explicitly call the WM_CAP_FILE_GET_CAPTURE_FILE message.

BOOL capFileGetCaptureFile(

hwnd,
szName,
wSize
);
Parameters

wSize

Size, in bytes, of the application-defined buffer referenced by szName.

szName

Address of an application-defined buffer used to return the name of the capture file as a null-terminated string.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The default capture filename is C:\CAPTURE.AVI.

See Also

WM_CAP_FILE_GET_CAPTURE_FILE


capFileSaveAs

The capFileSaveAs macro copies the contents of the capture file to another file. You can use this macro or explicitly call the WM_CAP_FILE_SAVEAS message.

BOOL capFileSaveAs(

hwnd,
szName
);
Parameters

hwnd

Handle of a capture window.

szName

Address of the null-terminated string that contains the name of the destination file used to copy the file.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the capSetCallbackOnError macro, the error callback function is called.

Remarks

This message does not change the name or contents of the current capture file.

If the copy operation is unsuccessful due to a disk full error, the destination file is automatically deleted.

Typically, a capture file is preallocated for the largest capture segment anticipated and only a portion of it might be used to capture data. This message copies only the portion of the file containing the capture data.

See Also

capSetCallbackOnError, WM_CAP_FILE_SAVEAS


capFileSaveDIB

The capFileSaveDIB macro copies the current frame to a DIB file. You can use this macro or explicitly call the WM_CAP_FILE_SAVEDIB message.

BOOL capFileSaveDIB(

hwnd,
szName
);
Parameters

hwnd

Handle of a capture window.

szName

Address of the null-terminated string that contains the name of the destination DIB file.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the capSetCallbackOnError macro, the error callback function is called.

Remarks

If the capture driver supplies frames in a compressed format, this call attempts to decompress the frame before writing the file.

See Also

capSetCallbackOnError, WM_CAP_FILE_SAVEDIB


capFileSetCaptureFile

The capFileSetCaptureFile macro names the file used for video capture. You can use this macro or explicitly call the WM_CAP_FILE_SET_CAPTURE_FILE message.

BOOL capFileSetCaptureFile(

hwnd,
szName
);
Parameters

hwnd

Handle of a capture window.

szName

Address of the null-terminated string that contains the name of the capture file to use.

Return Values

Returns TRUE if successful or FALSE if the filename is invalid or if streaming or single-frame capture is in progress.

Remarks

This message stores the filename in an internal structure. It does not create, allocate, or open the specified file. The default capture filename is C:\CAPTURE.AVI.

See Also

WM_CAP_FILE_SET_CAPTURE_FILE


capFileSetInfoChunk

The capFileSetInfoChunk macro sets and clears information chunks. Information chunks can be inserted in an AVI file during capture to embed text strings or custom data. You can use this macro or explicitly call the WM_CAP_FILE_SET_INFOCHUNK message.

BOOL capFileSetInfoChunk(

hwnd,
lpInfoChunk
);
Parameters

hwnd

Handle of a capture window.

lpInfoChunk

Address of a CAPINFOCHUNK structure defining the information chunk to be created or deleted.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the capSetCallbackOnError macro, the error callback function is called.

Remarks

Multiple registered information chunks can be added to an AVI file. After an information chunk is set, it continues to be added to subsequent capture files until either the entry is cleared or all information chunk entries are cleared. To clear a single entry, specify the information chunk in the fccInfoID member and NULL in the lpData member of the CAPINFOCHUNK structure. To clear all entries, specify NULL in fccInfoID.

See Also

CAPINFOCHUNK, capSetCallbackOnError, WM_CAP_FILE_SET_INFOCHUNK


capGetAudioFormat

The capGetAudioFormat macro obtains the audio format. You can use this macro or explicitly call the WM_CAP_GET_AUDIOFORMAT message.

DWORD capGetAudioFormat(

hwnd,
psAudioFormat,
wSize
);
Parameters

hwnd

Handle of a capture window.

psAudioFormat

Address of a WAVEFORMATEX structure, or NULL. If the value is NULL, the size, in bytes, required to hold the WAVEFORMATEX structure is returned.

wSize

Size, in bytes, of the structure referenced by s.

Return Values

Returns the size, in bytes, of the audio format.

Remarks

Because compressed audio formats vary in size requirements applications must first retrieve the size, then allocate memory, and finally request the audio format data.

See Also

WAVEFORMATEX, WM_CAP_GET_AUDIOFORMAT


capGetAudioFormatSize

The capGetAudioFormatSize macro obtains the size of the audio format. You can use this macro or explicitly call the WM_CAP_GET_AUDIOFORMAT message.

DWORD capGetAudioFormatSize(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns the size, in bytes, of the audio format.

Remarks

Because compressed audio formats vary in size requirements applications must first retrieve the size, then allocate memory, and finally request the audio format data.

See Also

WM_CAP_GET_AUDIOFORMAT


capGetMCIDeviceName

The capGetMCIDeviceName macro retrieves the name of an MCI device previously set with the capSetMCIDeviceName macro. You can use this macro or explicitly call the WM_CAP_GET_MCI_DEVICE message.

BOOL capGetMCIDeviceName(

hwnd,
szName,
wSize
);
Parameters

hwnd

Handle of a capture window.

wSize

Length, in bytes, of the buffer referenced by szName .

szName

Address of a null-terminated string that contains the MCI device name.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

capSetMCIDeviceName, WM_CAP_GET_MCI_DEVICE


capGetStatus

The capGetStatus macro retrieves the status of the capture window. You can use this macro or explicitly call the WM_CAP_GET_STATUS message.

BOOL capGetStatus(

hwnd,
s,
wSize
);
Parameters

hwnd

Handle of a capture window.

wSize

Size, in bytes, of the structure referenced by s.

s

Address of a CAPSTATUS structure.

Return Values

Returns TRUE if successful or FALSE if the capture window is not connected to a capture driver.

Remarks

The CAPSTATUS structure contains the current state of the capture window. Since this state is dynamic and changes in response to various messages, the application should initialize this structure after sending the capDlgVideoFormat macro and whenever it needs to enable menu items or determine the actual state of the window.

See Also

capDlgVideoFormat, CAPSTATUS, WM_CAP_GET_STATUS


capGetUserData

The capGetUserData macro retrieves a LONG data value associated with a capture window. You can use this macro or explicitly call the WM_CAP_GET_USER_DATA message.

BOOL capGetUserData(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns the value previously saved by using the capSetUserData macro.

See Also

WM_CAP_GET_USER_DATA


capGetVideoFormat

The capGetVideoFormat macro retrieves a copy of the video format in use. You can use this macro or explicitly call the WM_CAP_GET_VIDEOFORMAT message.

DWORD capGetVideoFormat(

hwnd,
psVideoFormat,
wSize
);
hwnd

Handle of a capture window.

psVideoFormat

Address of a BITMAPINFO structure. You can also specify NULL to retrieve the number of bytes needed by BITMAPINFO.

wSize

Size, in bytes, of the structure referenced by s.

Return Values

Returns the size, in bytes, of the video format or zero if the capture window is not connected to a capture driver. For video formats that require a palette, the current palette is also returned.

Remarks

Because compressed video formats vary in size requirements applications must first retrieve the size, then allocate memory, and finally request the video format data.

See Also

BITMAPINFO, WM_CAP_GET_VIDEOFORMAT


capGetVideoFormatSize

The capGetVideoFormatSize macro retrieves the size required for the video format. You can use this macro or explicitly call the WM_CAP_GET_VIDEOFORMAT message.

DWORD capGetVideoFormatSize(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns the size, in bytes, of the video format or zero if the capture window is not connected to a capture driver. For video formats that require a palette, the current palette is also returned.

Remarks

Because compressed video formats vary in size requirements applications must first retrieve the size, then allocate memory, and finally request the video format data.

See Also

WM_CAP_GET_VIDEOFORMAT


capGrabFrame

The capGrabFrame macro retrieves and displays a single frame from the capture driver. After capture, overlay and preview are disabled. You can use this macro or explicitly call the WM_CAP_GRAB_FRAME message.

BOOL capGrabFrame(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

For information about installing callback functions, see the capSetCallbackOnError and capSetCallbackOnFrame macros.

See Also

capSetCallbackOnError, capSetCallbackOnFrame, WM_CAP_GRAB_FRAME


capGrabFrameNoStop

The capGrabFrameNoStop macro fills the frame buffer with a single uncompressed frame from the capture device and displays it. Unlike with the capGrabFrame macro, the state of overlay or preview is not altered by this message. You can use this macro or explicitly call the WM_CAP_GRAB_FRAME_NOSTOP message.

BOOL capGrabFrameNoStop(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

For information about installing callback functions, see the capSetCallbackOnError and capSetCallbackOnFrame macros.

See Also

capSetCallbackOnError, capSetCallbackOnFrame, WM_CAP_GRAB_FRAME_NOSTOP


capOverlay

The capOverlay macro enables or disables overlay mode. In overlay mode, video is displayed using hardware overlay. You can use this macro or explicitly call the WM_CAP_SET_OVERLAY message.

BOOL capOverlay(

hwnd,
f
);
Parameters

hwnd

Handle of a capture window.

f

Overlay flag. Specify TRUE for this parameter to enable overlay mode or FALSE to disable it.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

Using an overlay does not require CPU resources.

The fHasOverlay member of the CAPDRIVERCAPS structure indicates whether the device is capable of overlay. The fOverlayWindow member of the CAPSTATUS structure indicates whether overlay mode is currently enabled.

Enabling overlay mode automatically disables preview mode.

See Also

CAPDRIVERCAPS, CAPSTATUS, WM_CAP_SET_OVERLAY


capPaletteAuto

The capPaletteAuto macro requests that the capture driver sample video frames and automatically create a new palette. You can use this macro or explicitly call the WM_CAP_PAL_AUTOCREATE message.

BOOL capPaletteAuto(

hwnd,
iFrames,
iColors
);
Parameters

hwnd

Handle of a capture window.

iFrames

Number of frames to sample.

iColors

Number of colors in the palette. The maximum value for this parameter is 256.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the capSetCallbackOnError macro, the error callback function is called.

Remarks

The sampled video sequence should include all the colors you want in the palette. To obtain the best palette, you might have to sample the whole sequence rather than a portion of it.

See Also

capSetCallbackOnError, WM_CAP_PAL_AUTOCREATE


capPaletteManual

The capPaletteManual macro requests that the capture driver manually sample video frames and create a new palette. You can use this macro or explicitly call the WM_CAP_PAL_MANUALCREATE message.

BOOL capPaletteManual(

hwnd,
fGrab,
iColors
);
Parameters

hwnd

Handle of a capture window.

fGrab

Palette histogram flag. Set this parameter to TRUE for each frame included in creating the optimal palette. After the last frame has been collected, set this parameter to FALSE to calculate the optimal palette and send it to the capture driver.

iColors

Number of colors in the palette. The maximum value for this parameter is 256. This value is used only during collection of the first frame in a sequence.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the capSetCallbackOnError macro, the error callback function is called.

See Also

capSetCallbackOnError, WM_CAP_PAL_MANUALCREATE


capPaletteOpen

The capPaletteOpen macro loads a new palette from a palette file and passes it to a capture driver. Palette files typically use the filename extension .PAL. A capture driver uses a palette when required by the specified digitized image format. You can use this macro or explicitly call the WM_CAP_PAL_OPEN message.

BOOL capPaletteOpen(

hwnd,
szName
);
Parameters

hwnd

Handle of a capture window.

szName

Address of a null-terminated string containing the palette filename.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the capSetCallbackOnError macro, the error callback function is called.

See Also

capSetCallbackOnError, WM_CAP_PAL_OPEN


capPalettePaste

The capPalettePaste macro copies the palette from the clipboard and passes it to a capture driver. You can use this macro or explicitly call the WM_CAP_PAL_PASTE message.

BOOL capPalettePaste(

hwnd
);
Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the capSetCallbackOnError macro, the error callback function is called.

Remarks

A capture driver uses a palette when required by the specified digitized video format.

See Also

capSetCallbackOnError, WM_CAP_PAL_PASTE


capPaletteSave

The capPaletteSave macro saves the current palette to a palette file. Palette files typically use the filename extension .PAL. You can use this macro or explicitly send the WM_CAP_PAL_SAVE message.

BOOL capPaletteSave(

hwnd,
szName
);
Parameters

hwnd

Handle of a capture window.

szName

Address of a null-terminated string containing the palette filename.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the capSetCallbackOnError macro, the error callback function is called.

See Also

capSetCallbackOnError, WM_CAP_PAL_SAVE


capPreview

The capPreview macro enables or disables preview mode. In preview mode, frames are transferred from the capture hardware to system memory and then displayed in the capture window using GDI functions. You can use this macro or explicitly call the WM_CAP_SET_PREVIEW message.

BOOL capPreview(

hwnd,
f
);
Parameters

hwnd

Handle of a capture window.

f

Preview flag. Specify TRUE for this parameter to enable preview mode or FALSE to disable it.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The preview mode uses substantial CPU resources. Applications can disable preview or lower the preview rate when another application has the focus. The fLiveWindow member of the CAPSTATUS structure indicates if preview mode is currently enabled.

Enabling preview mode automatically disables overlay mode.

See Also

CAPSTATUS, WM_CAP_SET_PREVIEW


capPreviewRate

The capPreviewRate macro sets the frame display rate in preview mode. You can use this macro or explicitly call the WM_CAP_SET_PREVIEWRATE message.

BOOL capPreviewRate(

hwnd,
wMS
);
Parameters

hwnd

Handle of a capture window.

wMS

Rate, in milliseconds, at which new frames are captured and displayed.

Return Values

Returns TRUE if successful or FALSE if the capture window is not connected to a capture driver.

Remarks

The preview mode uses substantial CPU resources. Applications can disable preview or lower the preview rate when another application has the focus. During streaming video capture, the previewing task is lower priority than writing frames to disk, and preview frames are displayed only if no other buffers are available for writing.

See Also

WM_CAP_SET_PREVIEWRATE


capPreviewScale

The capPreviewScale macro enables or disables scaling of the preview video images. If scaling is enabled, the captured video frame is stretched to the dimensions of the capture window. You can use this macro or explicitly call the WM_CAP_SET_SCALE message.

BOOL capPreviewScale(

hwnd,
f
);
Parameters

hwnd

Handle of a capture window.

f

Preview scaling flag. Specify TRUE for this parameter to stretch preview frames to the size of the capture window or FALSE to display them at their natural size.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

Scaling preview images controls the immediate presentation of captured frames within the capture window. It has no effect on the size of the frames saved to file.

Scaling has no effect when using overlay to display video in the frame buffer.

See Also

WM_CAP_SET_SCALE


capSetAudioFormat

The capSetAudioFormat macro sets the audio format to use when performing streaming or step capture. You can use this macro or explicitly call the WM_CAP_SET_AUDIOFORMAT message.

BOOL capSetAudioFormat(

hwnd,
psAudioFormat,
wSize
);
Parameters

hwnd

Handle of a capture window.

wSize

Size, in bytes, of the structure referenced by s.

psAudioFormat

Address of a WAVEFORMATEX or PCMWAVEFORMAT structure that defines the audio format.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

PCMWAVEFORMAT, WAVEFORMATEX, WM_CAP_SET_AUDIOFORMAT


capSetCallbackOnCapControl

The capSetCallbackOnCapControl macro sets a callback function in the application giving it precise recording control. You can use this macro or explicitly call the WM_CAP_SET_CALLBACK_CAPCONTROL message.

BOOL capSetCallbackOnCapControl(

hwnd,
fpProc
);
Parameters

hwnd

Handle of a capture window.

fpProc

Address of the callback function. Specify NULL for this parameter to disable a previously installed callback function.

Return Values

Returns TRUE if successful or FALSE if streaming capture or a single-frame capture session is in progress.

Remarks

A single callback function is used to give the application precise control over the moments that streaming capture begins and completes. The capture window first calls the procedure with nState set to CONTROLCALLBACK_PREROLL after all buffers have been allocated and all other capture preparations have finished. This gives the application the ability to preroll video sources, returning from the callback function at the exact moment recording is to begin. A return value of TRUE from the callback function continues capture, and a return value of FALSE aborts capture. After capture begins, this callback function will be called frequently with nState set to CONTROLCALLBACK_CAPTURING to allow the application to end capture by returning FALSE.

See Also

WM_CAP_SET_CALLBACK_CAPCONTROL


capSetCallbackOnError

The capSetCallbackOnError macro sets an error callback function in the client application. AVICap calls this procedure when errors occur. You can use this macro or explicitly call the WM_CAP_SET_CALLBACK_ERROR message.

BOOL capSetCallbackOnError(

hwnd,
fpProc
);
Parameters

hwnd

Handle of a capture window.

fpProc

Address of the error callback function. Specify NULL for this parameter to disable a previously installed error callback function.

Return Values

Returns TRUE if successful or FALSE if streaming capture or a single-frame capture session is in progress.

Remarks

Applications can optionally set an error callback function. If set, AVICap calls the error procedure in the following situations:

•	The disk is full.

•	A capture window cannot be connected with a capture driver.

•	A waveform-audio device cannot be opened.

•	The number of frames dropped during capture exceeds the specified percentage.

•	The frames cannot be captured due to vertical synchronization interrupt problems.

See Also

WM_CAP_SET_CALLBACK_ERROR


capSetCallbackOnFrame

The capSetCallbackOnFrame macro sets a preview callback function in the application. AVICap calls this procedure when the capture window captures preview frames. You can use this macro or explicitly call the WM_CAP_SET_CALLBACK_FRAME message.

BOOL capSetCallbackOnFrame(

hwnd,
fpProc
);
Parameters

hwnd

Handle of a capture window.

fpProc

Address of the preview callback function. Specify NULL for this parameter to disable a previously installed callback function.

Return Values

Returns TRUE if successful or FALSE if streaming capture or a single-frame capture session is in progress.

Remarks

The capture window calls the callback function before displaying preview frames. This allows an application to modify the frame if desired. This callback function is not used during streaming video capture.

See Also

WM_CAP_SET_CALLBACK_FRAME


capSetCallbackOnStatus

The capSetCallbackOnStatus macro sets a status callback function in the application. AVICap calls this procedure whenever the capture window status changes. You can use this macro or explicitly call the WM_CAP_SET_CALLBACK_STATUS message.

BOOL capSetCallbackOnStatus(

hwnd,
fpProc
);
Parameters

hwnd

Handle of a capture window.

fpProc

Address of the status callback function. Specify NULL for this parameter to disable a previously installed status callback function.

Return Values

Returns TRUE if successful or FALSE if streaming capture or a single-frame capture session is in progress.

Remarks

Applications can optionally set a status callback function. If set, AVICap calls this procedure in the following situations:

•	A capture session is completed.

•	A capture driver successfully connected to a capture window.

•	An optimal palette is created.

•	The number of captured frames is reported.

See Also

WM_CAP_SET_CALLBACK_STATUS


capSetCallbackOnVideoStream

The capSetCallbackOnVideoStream macro sets a callback function in the application. AVICap calls this procedure during streaming capture when a video buffer is filled. You can use this macro or explicitly call the WM_CAP_SET_CALLBACK_VIDEOSTREAM message.

BOOL capSetCallbackOnVideoStream(

hwnd,
fpProc
);
Parameters

hwnd

Handle of a capture window.

fpProc

Address of the video-stream callback function. Specify NULL for this parameter to disable a previously installed video-stream callback function.

Return Values

Returns TRUE if successful or FALSE if streaming capture or a single-frame capture session is in progress.

Remarks

The capture window calls the callback function before writing the captured frame to disk. This allows applications to modify the frame if desired.

If a video stream callback function is used for streaming capture, the procedure must be installed before starting the capture session and it must remain enabled for the duration of the session. It can be disabled after streaming capture ends.

See Also

WM_CAP_SET_CALLBACK_VIDEOSTREAM


capSetCallbackOnWaveStream

The capSetCallbackOnWaveStream macro sets a callback function in the application. AVICap calls this procedure during streaming capture when a new audio buffer becomes available. You can use this macro or explicitly call the WM_CAP_SET_CALLBACK_WAVESTREAM message.

BOOL capSetCallbackOnWaveStream(

hwnd,
fpProc
);
Parameters

hwnd

Handle of a capture window.

fpProc

Address of the wave stream callback function. Specify NULL for this parameter to disable a previously installed wave stream callback function.

Return Values

Returns TRUE if successful or FALSE if streaming capture or a single-frame capture session is in progress.

Remarks

The capture window calls the procedure before writing the audio buffer to disk. This allows applications to modify the audio buffer if desired.

If a wave stream callback function is used, it must be installed before starting the capture session and it must remain enabled for the duration of the session. It can be disabled after streaming capture ends.

See Also

WM_CAP_SET_CALLBACK_WAVESTREAM


capSetCallbackOnYield

The capSetCallbackOnYield macro sets a callback function in the application. AVICap calls this procedure when the capture window yields during streaming capture. You can use this macro or explicitly call the WM_CAP_SET_CALLBACK_YIELD message.

BOOL capSetCallbackOnYield(

hwnd,
fpProc
);
Parameters

hwnd

Handle of a capture window.

fpProc

Address of the yield callback function. Specify NULL for this parameter to disable a previously installed yield callback function.

Return Values

Returns TRUE if successful or FALSE if streaming capture or a single-frame capture session is in progress.

Remarks

Applications can optionally set a yield callback function. The yield callback function is called at least once for each video frame captured during streaming capture. If a yield callback function is installed, it will be called regardless of the state of the fYield member of the CAPTUREPARMS structure.

If the yield callback function is used, it must be installed before starting the capture session and it must remain enabled for the duration of the session. It can be disabled after streaming capture ends.

Applications typically perform some type of message processing in the callback function consisting of a PeekMessage, TranslateMessage, DispatchMessage loop, as in the message loop of a WinMain function. The yield callback function must also filter and remove messages that can cause reentrancy problems.

An application typically returns TRUE in the yield procedure to continue streaming capture. If a yield callback function returns FALSE, the capture window stops the capture process.

See Also

CAPTUREPARMS, DispatchMessage, PeekMessage, TranslateMessage, WM_CAP_SET_CALLBACK_YIELD, WinMain


capSetMCIDeviceName

The capSetMCIDeviceName macro specifies the name of the MCI video device to be used to capture data. You can use this macro or explicitly call the WM_CAP_SET_MCI_DEVICE message.

BOOL capSetMCIDeviceName(

hwnd,
szName
);
Parameters

hwnd

Handle of a capture window.

szName

Address of a null-terminated string containing the name of the device.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

This message stores the MCI device name in an internal structure. It does not open or access the device. The default device name is NULL.

See Also

WM_CAP_SET_MCI_DEVICE


capSetScrollPos

The capSetScrollPos macro defines the portion of the video frame to display in the capture window. This message sets the upper left corner of the client area of the capture window to the coordinates of a specified pixel within the video frame. You can use this macro or explicitly call the WM_CAP_SET_SCROLL message.

BOOL capSetScrollPos(

hwnd,
lpP
);
Parameters

hwnd

Handle of a capture window.

lpP

Address to contain the desired scroll position.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The scroll position affects the image in both preview and overlay modes.

See Also

WM_CAP_SET_SCROLL


capSetUserData

The capSetUserData macro associates a LONG data value with a capture window. You can use this macro or explicitly call the WM_CAP_SET_USER_DATA message.

BOOL capSetUserData(

hwnd,
lUser
);
Parameters

hwnd

Handle of a capture window.

lUser

Data value to associate with a capture window.

Return Values

Returns TRUE if successful or FALSE if streaming capture is in progress.

Remarks

Typically this message is used to point to a block of data associated with a capture window.

See Also

WM_CAP_SET_USER_DATA


capSetVideoFormat

The capSetVideoFormat macro sets the format of captured video data. You can use this macro or explicitly call the WM_CAP_SET_VIDEOFORMAT message.

BOOL capSetVideoFormat(

hwnd,
psVideoFormat,
wSize
);
Parameters

hwnd

Handle of a capture window.

psVideoFormat

Address of a BITMAPINFO structure.

wSize

Size, in bytes, of the structure referenced by s.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

Because video formats are device-specific, applications should check the return value from this function to determine if the format is accepted by the driver.

See Also

BITMAPINFO, WM_CAP_SET_VIDEOFORMAT


DrawDibUpdate

The DrawDibUpdate macro draws the last frame in the DrawDib off-screen buffer.

BOOL DrawDibUpdate(

HDRAWDIB hdd,
HDC hdc,
int xDst,
int yDst
);
Parameters

hdd

Handle of a DrawDib DC.

hdc

Handle of the DC.

xDst and yDst

The x- and y-coordinates, in MM_TEXT client coordinates, of the upper left corner of the destination rectangle.

Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

The DrawDibUpdate macro is defined as follows:

#define DrawDibUpdate( hdd, hdc, x, y) \

    DrawDibDraw( hdd, hdc, x, y, 0, 0, NULL, NULL, 0, 0, \

    0, 0, DDF_UPDATE)

This macro can be used to refresh an image or a portion of an image displayed by your application.


ICAbout

The ICAbout macro notifies a video compression driver to display its About dialog box. You can use this macro or explicitly call the ICM_ABOUT message.

DWORD ICAbout(

hic,
hwnd
);
hic

Handle of the compressor.

hwnd

Handle of the parent window of the displayed dialog box.

You can also determine if a driver has an About dialog box by specifying -1 in this parameter, as in the ICQueryAbout macro. The driver returns ICERR_OK if it has an About dialog box or ICERR_UNSUPPORTED otherwise.

Return Values

Returns ICERR_OK if the driver supports this message or ICERR_UNSUPPORTED otherwise.

See Also

ICM_ABOUT, ICQueryAbout


ICCompressBegin

The ICCompressBegin macro notifies a video compression driver to prepare to compress data. You can use this macro or explicitly call the ICM_COMPRESS_BEGIN message.

DWORD ICCompressBegin(

hic,
lpbiInput,
lpbiOutput
);
Parameters

hic

Handle of a compressor.

lpbiInput

Address of a BITMAPINFO structure containing the input format.

lpbiOutput

Address of a BITMAPINFO structure containing the output format.

Return Values

Returns ICERR_OK if the specified compression is supported or ICERR_BADFORMAT if the input or output format is not supported.

Remarks

The driver should allocate and initialize any tables or memory that it needs for compressing the data formats when it receives the ICM_COMPRESS message.

VCM saves the settings of the most recent ICCompressBegin macro. The ICCompressBegin and ICCompressEnd messages do not nest. If your driver receives ICM_COMPRESS_BEGIN before compression is stopped with ICM_COMPRESS_END, it should restart compression with new parameters.

See Also

BITMAPINFO, ICCompressEnd, ICM_COMPRESS_BEGIN


ICCompressEnd

The ICCompressEnd macro notifies a video compression driver to end compression and free resources allocated for compression. You can use this macro or explicitly call the ICM_COMPRESS_END message.

DWORD ICCompressEnd(

hic
);
Parameters

hic

Handle of the compressor.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

VCM saves the settings of the most recent ICCompressBegin macro. ICCompressBegin and ICCompressEnd do not nest. If your driver receives the ICM_COMPRESS_BEGIN message before compression is stopped with the ICM_COMPRESS_END message, it should restart compression with new parameters.

See Also

ICCompressBegin, ICM_COMPRESS_END


ICCompressGetFormat

The ICCompressGetFormat macro requests the output format of the compressed data from a video compression driver. You can use this macro or explicitly call the ICM_COMPRESS_GET_FORMAT message.

DWORD ICCompressGetFormat(

hic,
lpbiInput,
lpbiOutput
);
hic

Handle of the compressor.

lpbiInput

Address of a BITMAPINFO structure containing the input format.

lpbiOutput

Address of a BITMAPINFO structure to contain the output format. You can specify zero for this parameter to request only the size of the output format, as in the ICCompressGetFormatSize macro.

Return Values

If lpbiOutput is zero, returns the size of the structure.

If lpbiOutput is nonzero, returns ICERR_OK if successful or an error otherwise.

Remarks

If lpbiOutput is nonzero, the driver should fill the BITMAPINFO structure with the default output format corresponding to the input format specified for lpbiInput. If the compressor can produce several formats, the default format should be the one that preserves the greatest amount of information.

See Also

BITMAPINFO, ICCompressGetFormatSize, ICM_COMPRESS_GET_FORMAT


ICCompressGetFormatSize

The ICCompressGetFormatSize macro requests the size of the output format of the compressed data from a video compression driver. You can use this macro or explicitly call the ICM_COMPRESS_GET_FORMAT message.

DWORD ICCompressGetFormatSize(

hic,
lpbiInput
);
Parameters

hic

Handle of the compressor.

lpbiInput

Address of a BITMAPINFO structure containing the input format.

Return Values

Returns the size of the structure.

See Also

BITMAPINFO, ICM_COMPRESS_GET_FORMAT


ICCompressGetSize

The ICCompressGetSize macro requests that the video compression driver supply the maximum size of one frame of data when compressed into the specified output format. You can use this macro or explicitly call the ICM_COMPRESS_GET_SIZE message.

DWORD ICCompressGetSize(

hic,
lpbiInput,
lpbiOutput
);
Parameters

hic

Handle of a compressor.

lpbiInput

Address of a BITMAPINFO structure containing the input format.

lpbiOutput

Address of a BITMAPINFO structure containing the output format.

Return Values

Returns the maximum number of bytes a single compressed frame can occupy.

Remarks

Typically, applications send this message to determine how large a buffer to allocate for the compressed frame.

The driver should calculate the size of the largest possible frame based on the input and output formats.

See Also

BITMAPINFO, ICM_COMPRESS_GET_SIZE


ICCompressQuery

The ICCompressQuery macro queries a video compression driver to determine if it supports a specific input format or if it can compress a specific input format to a specific output format. You can use this macro or explicitly call the ICM_COMPRESS_QUERY message.

DWORD ICCompressQuery(

hic,
lpbiInput,
lpbiOutput
);
Parameters

hic

Handle of a compressor.

lpbiInput

Address of a BITMAPINFO structure containing the input format.

lpbiOutput

Address of a BITMAPINFO structure containing the output format. You can specify zero for this parameter to indicate any output format is acceptable.

Return Values

Returns ICERR_OK if the specified compression is supported or ICERR_BADFORMAT otherwise.

Remarks

When a driver receives this message, it should examine the BITMAPINFO structure associated with lpbiInput to determine if it can compress the input format.

See Also

BITMAPINFO, ICM_COMPRESS_QUERY


ICConfigure

The ICConfigure macro notifies a video compression driver to display its configuration dialog box. You can use this macro or explicitly send the ICM_CONFIGURE message.

DWORD ICConfigure(

hic,
hwnd
);
Parameters

hic

Handle of the compressor.

hwnd

Handle of the parent window of the displayed dialog box.

You can determine if a driver has a configuration dialog box by specifying  − 1 in this parameter, as in the ICQueryConfigure macro.

Return Values

Returns ICERR_OK if the driver supports this macro or ICERR_UNSUPPORTED otherwise.

Remarks

The ICM_CONFIGURE message is different from the DRV_CONFIGURE message used for hardware configuration. The dialog box for this message should let the user set and edit the internal state referenced by the ICGetState and ICSetState macros. For example, this dialog box can let the user change parameters affecting the quality level and other similar compression options.

See Also

DRV_CONFIGURE ICM_CONFIGURE, ICGetState, ICQueryConfigure, ICSetState


ICDecompressBegin

The ICDecompressBegin macro notifies a video decompression driver to prepare to decompress data. You can use this macro or explicitly call the ICM_DECOMPRESS_BEGIN message.

DWORD ICDecompressBegin(

hic,
lpbiInput,
lpbiOutput
);
Parameters

hic

Handle of a decompressor.

lpbiInput

Address of a BITMAPINFO structure containing the input format.

lpbiOutput

Address of a BITMAPINFO structure containing the output format.

Return Values

Returns ICERR_OK if the specified decompression is supported or ICERR_BADFORMAT otherwise.

Remarks

When the driver receives this message, it should allocate buffers and do any time-consuming operations so that it can process ICM_DECOMPRESS messages efficiently.

The ICDecompressBegin and ICDecompressEnd macros do not nest. If your driver receives ICM_DECOMPRESS_BEGIN before decompression is stopped with ICM_DECOMPRESS_END, it should restart decompression with new parameters.

See Also

BITMAPINFO, ICDecompressEnd, ICM_DECOMPRESS, ICM_DECOMPRESS_BEGIN, ICM_DECOMPRESS_END


ICDecompressEnd

The ICDecompressEnd macro notifies a video decompression driver to end decompression and free resources allocated for decompression. You can use this macro or explicitly call the ICM_DECOMPRESS_END message.

DWORD ICDecompressEnd(

hic
);
Parameters

hic

Handle of a decompressor.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

The driver should free any resources allocated for the ICM_DECOMPRESS_BEGIN message.

The ICDecompressBegin and ICDecompressEnd macros do not nest. If your driver receives ICM_DECOMPRESS_BEGIN before decompression is stopped with ICM_DECOMPRESS_END, it should restart decompression with new parameters.

See Also

ICDecompressBegin, ICM_DECOMPRESS, ICM_DECOMPRESS_BEGIN, ICM_DECOMPRESS_END


ICDecompressExEnd

The ICDecompressExEnd macro notifies a video decompression driver to end decompression and free resources allocated for decompression. You can use this macro or explicitly call the ICM_DECOMPRESSEX_END message.

DWORD ICDecompressExEnd(

hic
);
Parameters

hic

Handle of a decompressor.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

The driver frees any resources allocated for the ICM_DECOMPRESSEX_BEGIN message.

ICM_DECOMPRESSEX_BEGIN and ICM_DECOMPRESSEX_END do not nest. If your driver receives ICM_DECOMPRESSEX_BEGIN before decompression is stopped with ICM_DECOMPRESSEX_END, it should restart decompression with new parameters.

See Also

ICM_DECOMPRESSEX_END


ICDecompressGetFormat

The ICDecompressGetFormat macro requests the output format of the decompressed data from a video decompression driver. You can use this macro or explicitly call the ICM_DECOMPRESS_GET_FORMAT message.

DWORD ICDecompressGetFormat(

hic,
lpbiInput,
lpbiOutput
);
hic

Handle of a decompressor.

lpbiInput

Address of a BITMAPINFO structure containing the input format.

lpbiOutput

Address of a BITMAPINFO structure to contain the output format. You can specify zero to request only the size of the output format, as in the ICDecompressGetFormatSize macro.

Return Values

If lpbiOutput is zero, returns the size of the structure.

If lpbiOutput is nonzero, returns ICERR_OK if successful or an error otherwise.

Remarks

If lpbiOutput is nonzero, the driver should fill the BITMAPINFO structure with the default output format corresponding to the input format specified for lpbiInput. If the compressor can produce several formats, the default format should be the one that preserves the greatest amount of information.

See Also

BITMAPINFO, ICDecompressGetFormatSize, ICM_DECOMPRESS_GET_FORMAT


ICDecompressGetFormatSize

The ICDecompressGetFormatSize macro requests the size of the output format of the decompressed data from a video decompression driver. You can use this macro or explicitly call the ICM_DECOMPRESS_GET_FORMAT message.

DWORD ICDecompressGetFormatSize(

hic,
lpbiInput
);
Parameters

hic

Handle of a decompressor.

lpbiInput

Address of a BITMAPINFO structure containing the input format.

Return Values

Returns the size of the structure.

See Also

BITMAPINFO, ICM_DECOMPRESS_GET_FORMAT


ICDecompressGetPalette

The ICDecompressGetPalette macro requests that the video decompression driver supply the color table of the output BITMAPINFOHEADER structure. You can use this macro or explicitly call the ICM_DECOMPRESS_GET_PALETTE message.

DWORD ICDecompressGetPalette(

hic,
lpbiInput,
lpbiOutput
);
Parameters

hic

Handle of a decompressor.

lpbiInput

Address of a BITMAPINFOHEADER structure containing the input format.

lpbiOutput

Address of a BITMAPINFOHEADER structure to contain the color table. The space reserved for the color table is always at least 256 colors. You can specify zero for this parameter to return only the size of the color table.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

If lpbiOutput is nonzero, the driver sets the biClrUsed member of BITMAPINFOHEADER to the number of colors in the color table. The driver fills the bmiColors members of BITMAPINFO with the actual colors.

The driver should support this message only if it uses a palette other than the one specified in the input format.

See Also

BITMAPINFO, BITMAPINFOHEADER, ICM_DECOMPRESS_GET_PALETTE


ICDecompressOpen

The ICDecompressOpen macro opens a decompressor that is compatible with the specified formats.

HIC ICDecompressOpen(

DWORD fccType,
DWORD fccHandler,
LPBITMAPINFOHEADER lpbiIn,
LPBITMAPINFOHEADER lpbiOut
);
Parameters

fccType

Four-character code indicating the type of compressor to open. For video streams, the value of this parameter is “VIDC” or ICTYPE_VIDEO.

fccHandler

Four-character code indicating the preferred stream handler to use. Typically, this information is stored in the stream header in an AVI file.

lpbiIn

Address of a structure defining the input format. A decompressor handle is not returned unless it can decompress this format. For bitmaps, this parameter refers to a BITMAPINFOHEADER structure.

lpbiOut

Address of a structure defining an optional decompression format. You can also specify zero to use the default output format associated with the input format.

If this parameter is nonzero, a compressor handle is not returned unless it can create this output format. For bitmaps, this parameter refers to a BITMAPINFOHEADER structure.

Return Values

Returns a handle of a decompressor if successful or zero otherwise.

Remarks

The ICDecompressOpen macro is defined as follows:

#define ICDecompressOpen(fccType, fccHandler, lpbiIn, lpbiOut) \

    ICLocate(fccType, fccHandler, lpbiIn, lpbiOut, ICMODE_DECOMPRESS);

See Also

BITMAPINFOHEADER


ICDecompressQuery

The ICDecompressQuery macro queries a video decompression driver to determine if it supports a specific input format or if it can decompress a specific input format to a specific output format. You can use this macro or explicitly call the ICM_DECOMPRESS_QUERY message.

DWORD ICDecompressQuery(

hic,
lpbiInput,
lpbiOutput
);
Parameters

hic

Handle of a decompressor.

lpbiInput

Address of a BITMAPINFO structure containing the input format.

lpbiOutput

Address of a BITMAPINFO structure containing the output format. You can specify zero for this parameter to indicate any output format is acceptable.

Return Values

Returns ICERR_OK if the specified decompression is supported or ICERR_BADFORMAT otherwise.

See Also

ICM_DECOMPRESS_QUERY


ICDecompressSetPalette

The ICDecompressSetPalette macro specifies a palette for a video decompression driver to use if it is decompressing to a format that uses a palette. You can use this macro or explicitly call the ICM_DECOMPRESS_SET_PALETTE message.

ICDecompressSetPalette(

hic,
lpbiPalette
);
Parameters

lpbiPalette

Address of a BITMAPINFOHEADER structure whose color table contains the colors that should be used if possible. You can specify zero to use the default set of output colors.

Return Values

Returns ICERR_OK if the decompression driver can precisely decompress images to the suggested palette using the set of colors as they are arranged in the palette. Returns ICERR_UNSUPPORTED otherwise.

Remarks

This macro should not affect decompression already in progress; rather, colors passed using this message should be returned in response to future ICDecompressGetFormat and ICDecompressGetPalette macros. Colors are sent back to the decompression driver in a future ICDecompressBegin macro.

This macro is used primarily when a driver decompresses images to the screen and another application that uses a palette is in the foreground, forcing the decompression driver to adapt to a foreign set of colors.

See Also

BITMAPINFOHEADER, ICDecompressGetFormat, ICDecompressGetPalette, ICM_DECOMPRESS_SET_PALETTE


ICDrawChangePalette

The ICDrawChangePalette macro notifies a rendering driver that the movie palette is changing. You can use this macro or explicitly call the ICM_DRAW_CHANGEPALETTE message.

DWORD ICDrawChangePalette(

hic,
lpbiInput
);
Parameters

hic

Handle of a rendering driver.

lpbiInput

Address of a BITMAPINFO structure containing the new format and optional color table.

Return Values

Returns ICERR_OK if successful or FALSE otherwise.

Remarks

This message should be supported by installable rendering handlers that draw DIBs with an internal structure that includes a palette.

See Also

BITMAPINFO, ICM_DRAW_CHANGEPALETTE


ICDrawEnd

The ICDrawEnd macro notifies a rendering driver to decompress the current image to the screen and to release resources allocated for decompression and drawing. You can use this macro or explicitly call the ICM_DRAW_END message.

DWORD ICDrawEnd(

hic
);
Parameters

hic

Handle of a driver.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

The ICM_DRAW_BEGIN and ICM_DRAW_END messages do not nest. If your driver receives ICM_DRAW_BEGIN before decompression is stopped with ICM_DRAW_END, it should restart decompression with new parameters.

See Also

ICM_DRAW_BEGIN, ICM_DRAW_END


ICDrawFlush

The ICDrawFlush macro notifies a rendering driver to render the contents of any image buffers that are waiting to be drawn. You can use this macro or explicitly call the ICM_DRAW_FLUSH message.

DWORD ICDrawFlush(

hic
);
Parameters

hic

Handle of a driver.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

This message is used only by hardware that performs its own asynchronous decompression, timing, and drawing.

See Also

ICM_DRAW_FLUSH


ICDrawGetTime

The ICDrawGetTime macro requests a rendering driver that controls the timing of drawing frames to return the current value of its internal clock. You can use this macro or explicitly call the ICM_DRAW_GETTIME message.

DWORD ICDrawGetTime(

hic,
lplTime
);
Parameters

hic

Handle of a driver.

lplTime

Address to contain the current time. The return value should be specified in samples.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

This message is generally supported by hardware that performs its own asynchronous decompression, timing, and drawing. The message can also be sent if the hardware is being used as the synchronization master.

See Also

ICM_DRAW_GETTIME


ICDrawOpen

The ICDrawOpen macro opens a driver that can draw images with the specified format.

HIC ICDrawOpen(

DWORD fccType,
DWORD fccHandler,
LPBITMAPINFOHEADER lpbiIn
);
Parameters

fccType

Four-character code indicating the type of driver to open. For video streams, the value of this parameter is “VIDC” or ICTYPE_VIDEO.

fccHandler

Four-character code indicating the preferred stream handler to use. Typically, this information is stored in the stream header in an AVI file.

lpbiIn

Address of the structure defining the input format. A driver handle will not be returned unless it can decompress this format. For images, this parameter refers to a BITMAPINFOHEADER structure.

Return Values

Returns a handle of a driver if successful or zero otherwise.

Remarks

The ICDrawOpen macro is defined as follows:

#define ICDrawOpen(fccType, fccHandler, lpbiIn) \
    ICLocate(fccType, fccHandler, lpbiIn, NULL, ICMODE_DRAW);

See Also

BITMAPINFOHEADER


ICDrawQuery

The ICDrawQuery macro queries a rendering driver to determine if it can render data in a specific format. You can use this macro or explicitly call the ICM_DRAW_QUERY message.

DWORD ICDrawQuery(

hic,
lpbiInput
);
Parameters

hic

Handle of a driver.

lpbiInput

Address of a BITMAPINFO structure containing the input format.

Return Values

Returns ICERR_OK if the driver can render data in the specified format or ICERR_BADFORMAT otherwise.

Remarks

This macro differs from the ICDrawBegin macro in that it queries the driver in a general sense. ICDrawBegin determines if the driver can draw the data using the specified format under specific conditions, such as stretching the image.

See Also

BITMAPINFO, ICDrawBegin, ICM_DRAW_QUERY


ICDrawRealize

The ICDrawRealize macro notifies a rendering driver to realize its drawing palette while drawing. You can use this macro or explicitly call the ICM_DRAW_REALIZE message.

DWORD ICDrawRealize(

hic,
hdc,
fBackground
);
Parameters

hic

Handle of a driver.

hdc

Handle of the DC used to realize the palette.

fBackground

Background flag. Specify TRUE to realize the palette as a background task or FALSE to realize the palette in the foreground.

Return Values

Returns ICERR_OK if the drawing palette is realized or ICERR_UNSUPPORTED if the palette associated with the decompressed data is realized.

Remarks

Drivers need to respond to this message only if the drawing palette is different from the decompressed palette.

See Also

ICM_DRAW_REALIZE


ICDrawRenderBuffer

The ICDrawRenderBuffer macro notifies a rendering driver to draw the frames that have been passed to it. You can use this macro or explicitly call the ICM_DRAW_RENDERBUFFER message.

DWORD ICDrawRenderBuffer(

hic
);
Parameters

hic

Handle of a driver.

Return Values

This macro does not return a value.

Remarks

Use this message with hardware that performs its own asynchronous decompression, timing, and drawing.

This message is typically used to perform a seek operation when the driver must be specifically instructed to display each video frame passed to it rather than playing a sequence of video frames.

See Also

ICM_DRAW_RENDERBUFFER


ICDrawSetTime

The ICDrawSetTime macro provides synchronization information to a rendering driver that handles the timing of drawing frames. The synchronization information is the sample number of the frame to draw. You can use this macro or explicitly call the ICM_DRAW_SETTIME message.

DWORD ICDrawSetTime(

hic,
lpTime
);
Parameters

hic

Handle of a driver.

lpTime

Sample number of the frame to render.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

Typically, the driver compares the specified value with the frame number associated with the time of its internal clock and attempts to synchronize the two if the difference is significant.

Use this message when the hardware performs its own asynchronous decompression, timing, and drawing, and the hardware relies on an external synchronization signal (the hardware is not being used as the synchronization master).

See Also

ICM_DRAW_SETTIME


ICDrawStart

The ICDrawStart macro notifies a rendering driver to start its internal clock for the timing of drawing frames. You can use this macro or explicitly call the ICM_DRAW_START message.

DWORD ICDrawStart(

hic
);
Parameters

hic

Handle of a driver.

Return Values

This macro does not return a value.

Remarks

This message is used by hardware that performs its own asynchronous decompression, timing, and drawing.

When the driver receives this message, it should start rendering data at the rate specified with the ICM_DRAW_BEGIN message.

The ICDrawStart and ICDrawStop macros do not nest. If your driver receives ICDrawStart before rendering is stopped with ICDrawStop, it should restart rendering with new parameters.

See Also

ICDrawStop, ICM_DRAW_START


ICDrawStartPlay

The ICDrawStartPlay macro provides the start and end times of a play operation to a rendering driver. You can use this macro or explicitly call the ICM_DRAW_START_PLAY message.

ICDrawStartPlay(

hic,
lFrom,
lTo
);
Parameters

lFrom

Start time.

lTo

End time.

Return Values

This macro does not return a value.

Remarks

This message precedes any frame data sent to the rendering driver.

Units for lFrom and lTo are specified with the ICM_DRAW_BEGIN message. For video data this is normally a frame number. For more information about the playback rate, see the dwRate and dwScale members of the ICDRAWBEGIN structure.

If the end time is less than the start time, the playback direction is reversed.

See Also

ICDRAWBEGIN, ICM_DRAW_START_PLAY


ICDrawStop

The ICDrawStop macro notifies a rendering driver to stop its internal clock for the timing of drawing frames. You can use this macro or explicitly call the ICM_DRAW_STOP message.

DWORD ICDrawStop(

hic
);
Parameters

hic

Handle of a driver.

Return Values

This macro does not return a value.

Remarks

This macro is used by hardware that performs its own asynchronous decompression, timing, and drawing.

See Also

ICM_DRAW_STOP


ICDrawStopPlay

The ICDrawStopPlay macro notifies a rendering driver when a play operation is complete. You can use this macro or explicitly call the ICM_DRAW_STOP_PLAY message.

ICDrawStopPlay(

hic
);
Parameters

hic

Handle of a driver.

Return Values

This macro does not return a value.

Remarks

Use this message when the play operation is complete. Use the ICDrawStop macro to end timing.

See Also

ICM_DRAW_STOP_PLAY


ICDrawWindow

The ICDrawWindow macro notifies a rendering driver that the window specified for the ICM_DRAW_BEGIN message needs to be redrawn. The window has moved or become temporarily obscured. You can use this macro or explicitly call the ICM_DRAW_WINDOW message.

DWORD ICDrawWindow(

hic,
prc
);
Parameters

hic

Handle of a driver.

prc

Address of the destination rectangle in screen coordinates. If this parameter points to an empty rectangle, drawing should be turned off.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

This message is supported by hardware that performs its own asynchronous decompression, timing, and drawing.

Video-overlay drivers use this message to draw when the window is obscured or moved. When a window specified for ICM_DRAW_BEGIN is completely hidden by other windows, the destination rectangle is empty. Drivers should turn off video-overlay hardware when this condition occurs.

See Also

ICM_DRAW_BEGIN, ICM_DRAW_WINDOW


ICGetBuffersWanted

The ICGetBuffersWanted macro queries a driver for the number of buffers to allocate. You can use this macro or explicitly call the ICM_GETBUFFERSWANTED message.

DWORD ICGetBuffersWanted(

hic,
lpdwBuffers
);
Parameters

hic

Handle of a driver.

lpdwBuffers

Address to contain the number of samples the driver needs to efficiently render the data.

Return Values

Returns ICERR_OK if successful or ICERR_UNSUPPORTED otherwise.

Remarks

This message is used by drivers that use hardware to render data and want to ensure a minimal time lag caused by waiting for buffers to arrive. For example, if a driver controls a video decompression board that can hold 10 frames of video, it could return 10 for this message. This instructs applications to try to stay 10 frames ahead of the frame it currently needs.

See Also

ICM_GETBUFFERSWANTED


ICGetDefaultKeyFrameRate

The ICGetDefaultKeyFrameRate macro queries a video compression driver for its default (or preferred) key-frame spacing. You can use this macro or explicitly call the ICM_GETDEFAULTKEYFRAMERATE message.

DWORD ICGetDefaultKeyFrameRate(

hic
);
Parameters

hic

Handle of a compressor.

wParam

Address to contain the preferred key-frame spacing.

Return Values

Returns ICERR_OK if the driver supports this message or ICERR_UNSUPPORTED otherwise.

Remarks

The ICGetDefaultKeyFrameRate macro returns the default key frame rate.

See Also

ICM_GETDEFAULTKEYFRAMERATE


ICGetDefaultQuality

The ICGetDefaultQuality macro queries a video compression driver to provide its default quality setting. You can use this macro or explicitly call the ICM_GETDEFAULTQUALITY message.

DWORD ICGetDefaultQuality(

hic
);
Parameters

hic

Handle of a compressor.

wParam

Address to contain the default quality value. Quality values range from 0 to 10,000.

Return Values

Returns ICERR_OK if the driver supports this message or ICERR_UNSUPPORTED otherwise.

Remarks

The ICGetDefaultQuality macro returns the default quality value.

See Also

ICM_GETDEFAULTQUALITY


ICGetState

The ICGetState macro queries a video compression driver to return its current configuration in a block of memory. You can use this macro or explicitly call the ICM_GETSTATE message.

DWORD ICGetState(

hic,
pv,
cb
);
hic

Handle of the compressor.

pv

Address of a block of memory to contain the current configuration information. You can specify NULL for this parameter to determine the amount of memory required for the configuration information, as in ICGetStateSize.

cb

Size, in bytes, of the block of memory.

Return Values

If pv is NULL, returns the amount of memory, in bytes, required for configuration information.

If pv is not NULL, returns ICERR_OK if successful or an error otherwise.

Remarks

The ICGetStateSize macro returns the number of bytes used by the state data.

The structure used to represent configuration information is driver specific and is defined by the driver.

Use ICGetStateSize before calling the ICGetState macro to determine the size of buffer to allocate for the call.

See Also

ICGetStateSize, ICM_GETSTATE


ICGetStateSize

The ICGetStateSize macro queries a video compression driver to determine the amount of memory required to retrieve the configuration information. You can use this macro or explicitly call the ICM_GETSTATE message.

DWORD ICGetStateSize(

hic
);
Parameters

hic

Handle of the compressor.

Return Values

Returns the amount of memory, in bytes, required by the state information.

Remarks

The structure used to represent configuration information is driver specific and is defined by the driver.

Use ICGetStateSize before calling the ICGetState macro to determine the size of buffer to allocate for the call.

See Also

ICGetState, ICM_GETSTATE


ICQueryAbout

The ICQueryAbout macro queries a video compression driver to determine if it has an About dialog box. You can use this macro or explicitly call the ICM_ABOUT message.

DWORD ICQueryAbout(

hic
);
Parameters

hic

Handle of the compressor.

Return Values

Returns ICERR_OK if the driver supports this message or ICERR_UNSUPPORTED otherwise.

See Also

ICM_ABOUT


ICQueryConfigure

The ICQueryConfigure macro queries a video compression driver to determine if it has a configuration dialog box. You can use this macro or explicitly send the ICM_CONFIGURE message.

DWORD ICQueryConfigure(

hic
);
hic

Handle of the compressor.

Return Values

Returns ICERR_OK if the driver supports this macro or ICERR_UNSUPPORTED otherwise.

Remarks

This message is different from the DRV_CONFIGURE message used for hardware configuration. The dialog box for this message should let the user set and edit the internal state referenced by the ICM_GETSTATE and ICM_SETSTATE messages. For example, this dialog box can let the user change parameters affecting the quality level and other similar compression options.

See Also

ICM_CONFIGURE, ICM_GETSTATE, ICM_SETSTATE, DRV_CONFIGURE


ICSetState

The ICSetState macro notifies a video compression driver to set the state of the compressor. You can use this macro or explicitly call the ICM_SETSTATE message.

DWORD ICSetState(

hic,
pv,
cb
);
Parameters

hic

Handle of the compressor.

pv

Address of a block of memory containing configuration data. You can specify NULL for this parameter to reset the compressor to its default state.

cb

Size, in bytes, of the block of memory.

Return Values

Returns the number of bytes used by the compressor if successful or zero otherwise.

Remarks

The information used by this message is private and specific to a given compressor. Client applications should use this message only to restore information previously obtained with the ICGetState and ICConfigure macros and should use the ICConfigure macro to adjust the configuration of a video compression driver.

See Also

ICConfigure, ICGetState, ICM_SETSTATE


MCI_HMS_HOUR

The MCI_HMS_HOUR macro retrieves the hours component from a parameter containing packed hours/minutes/seconds (HMS) information.

BYTE MCI_HMS_HOUR(

DWORD dwHMS
);
Parameters

dwHMS

Time in HMS format.

Return Values

Returns the hours component of the specified HMS information.

Remarks

Time in HMS format is expressed as a doubleword value with the least significant byte containing hours, the next least significant byte containing minutes, and the next least significant byte containing seconds. The most significant byte is unused.

The MCI_HMS_HOUR macro is defined as follows:

#define MCI_HMS_HOUR(hms) ((BYTE)(hms))


MCI_HMS_MINUTE

The MCI_HMS_MINUTE macro retrieves the minutes component from a parameter containing packed hours/minutes/seconds (HMS) information.

BYTE MCI_HMS_MINUTE(

DWORD dwHMS
);
Parameters

dwHMS

Time in HMS format.

Return Values

Returns the minutes component of the specified HMS information.

Remarks

Time in HMS format is expressed as a doubleword value with the least significant byte containing hours, the next least significant byte containing minutes, and the next least significant byte containing seconds. The most significant byte is unused.

The MCI_HMS_MINUTE macro is defined as follows:

#define MCI_HMS_MINUTE(hms) ((BYTE)(((WORD)(hms)) >> 8))


MCI_HMS_SECOND

The MCI_HMS_SECOND macro retrieves the seconds component from a parameter containing packed hours/minutes/seconds (HMS) information.

BYTE MCI_HMS_SECOND(

DWORD dwHMS
);
Parameters

dwHMS

Time in HMS format.

Return Values

Returns the seconds component of the specified HMS information.

Remarks

Time in HMS format is expressed as a doubleword value with the least significant byte containing hours, the next least significant byte containing minutes, and the next least significant byte containing seconds. The most significant byte is unused.

The MCI_HMS_SECOND macro is defined as follows:

#define MCI_HMS_SECOND(hms) ((BYTE)((hms) >> 16))


MCI_MAKE_HMS

The MCI_MAKE_HMS macro creates a time value in packed hours/minutes/seconds (HMS) format from the given hours, minutes, and seconds values.

DWORD MCI_MAKE_HMS(

BYTE hours,
BYTE minutes,
BYTE seconds
);
Parameters

hours, minutes, and seconds

Number of hours, minutes, and seconds.

Return Values

Returns the time in packed HMS format.

Remarks

Time in HMS format is expressed as a doubleword value with the least significant byte containing hours, the next least significant byte containing minutes, and the next least significant byte containing seconds. The most significant byte is unused.

The MCI_MAKE_HMS macro is defined as follows:

#define MCI_MAKE_HMS(h, m, s) ((DWORD)(((BYTE)(h) | \

                              ((WORD)(m) << 8)) | \

                              (((DWORD)(BYTE)(s)) << 16)))


MCI_MAKE_MSF

The MCI_MAKE_MSF macro creates a time value in packed minutes/seconds/frames (MSF) format from the given minutes, seconds, and frame values.

DWORD MCI_MAKE_MSF(

BYTE minutes,
BYTE seconds,
BYTE frames
);
Parameters

minutes, seconds, and frames

Number of minutes, seconds, and frames.

Return Values

Returns the time in packed MSF format.

Remarks

Time in MSF format is expressed as a doubleword value with the least significant byte containing minutes, the next least significant byte containing seconds, and the next least significant byte containing frames. The most significant byte is unused.

The MCI_MAKE_MSF macro is defined as follows:

#define MCI_MAKE_MSF(m, s, f) ((DWORD)(((BYTE)(m) | \

                              ((WORD)(s) << 8)) | \

                              (((DWORD)(BYTE)(f)) << 16)))


MCI_MAKE_TMSF

The MCI_MAKE_TMSF macro creates a time value in packed tracks/minutes/seconds/frames (TMSF) format from the given tracks, minutes, seconds, and frames values.

DWORD MCI_MAKE_TMSF(

BYTE tracks,
BYTE minutes,
BYTE seconds,
BYTE frames
);
Parameters

tracks, minutes, seconds, and frames

Number of tracks, minutes, seconds, and frames.

Return Values

Returns the time in packed TMSF format.

Remarks

Time in TMSF format is expressed as a doubleword value with the least significant byte containing tracks, the next least significant byte containing minutes, the next least significant byte containing seconds, and the most significant byte containing frames.

The MCI_MAKE_TMSF macro is defined as follows:

#define MCI_MAKE_TMSF(t, m, s, f) ((DWORD)(((BYTE)(t) | \

                                  ((WORD)(m) << 8)) | \

                                  (((DWORD)(BYTE)(s) | \

                                  ((WORD)(f) << 8)) << 16)))


MCI_MSF_FRAME

The MCI_MSF_FRAME macro creates the frames component from a parameter containing packed minutes/seconds/frames (MSF) information.

BYTE MCI_MSF_FRAME(

DWORD dwMSF
);
Parameters

dwMSF

Time in MSF format.

Return Values

Returns the frames component of the specified MSF information.

Remarks

Time in MSF format is expressed as a doubleword value with the least significant byte containing minutes, the next least significant byte containing seconds, and the next least significant byte containing frames. The most significant byte is unused.

The MCI_MSF_FRAME macro is defined as follows:

#define MCI_MSF_FRAME(msf) ((BYTE)((msf) >> 16))


MCI_MSF_MINUTE

The MCI_MSF_MINUTE macro retrieves the minutes component from a parameter containing packed minutes/seconds/frames (MSF) information.

BYTE MCI_MSF_MINUTE(

DWORD dwMSF
);
Parameters

dwMSF

Time in MSF format.

Return Values

Returns the minutes component of the specified MSF information.

Remarks

Time in MSF format is expressed as a doubleword value with the least significant byte containing minutes, the next least significant byte containing seconds, and the next least significant byte containing frames. The most significant byte is unused.

The MCI_MSF_MINUTE macro is defined as follows:

#define MCI_MSF_MINUTE(msf) ((BYTE)(msf))


MCI_MSF_SECOND

The MCI_MSF_SECOND macro retrieves the seconds component from a parameter containing packed minutes/seconds/frames (MSF) information.

BYTE MCI_MSF_SECOND(

DWORD dwMSF
);
Parameters

dwMSF

Time in MSF format.

Return Values

Returns the seconds component of the specified MSF information.

Remarks

Time in MSF format is expressed as a doubleword value with the least significant byte containing minutes, the next least significant byte containing seconds, and the next least significant byte containing frames. The most significant byte is unused.

The MCI_MSF_SECOND macro is defined as follows:

#define MCI_MSF_SECOND(msf) ((BYTE)(((WORD)(msf)) >> 8))


MCI_TMSF_FRAME

The MCI_TMSF_FRAME macro retrieves the frames component from a parameter containing packed tracks/minutes/seconds/frames (TMSF) information.

BYTE MCI_TMSF_FRAME(

DWORD dwTMSF
);
Parameters

dwTMSF

Time in TMSF format.

Return Values

Returns the frames component of the specified TMSF information.

Remarks

Time in TMSF format is expressed as a doubleword value with the least significant byte containing tracks, the next least significant byte containing minutes, the next least significant byte containing seconds, and the most significant byte containing frames.

The MCI_TMSF_FRAME macro is defined as follows:

#define MCI_TMSF_FRAME(tmsf) ((BYTE)((tmsf) >> 24))


MCI_TMSF_MINUTE

The MCI_TMSF_MINUTE macro retrieves the minutes component from a parameter containing packed tracks/minutes/seconds/frames (TMSF) information.

BYTE MCI_TMSF_MINUTE(

DWORD dwTMSF
);
Parameters

dwTMSF

Time in TMSF format.

Return Values

Returns the minutes component of the specified TMSF information.

Remarks

Time in TMSF format is expressed as a doubleword value with the least significant byte containing tracks, the next least significant byte containing minutes, the next least significant byte containing seconds, and the most significant byte containing frames.

The MCI_TMSF_MINUTE macro is defined as follows:

#define MCI_TMSF_MINUTE(tmsf) ((BYTE)(((WORD)(tmsf)) >> 8))


MCI_TMSF_SECOND

The MCI_TMSF_SECOND macro retrieves the seconds component from a parameter containing packed tracks/minutes/seconds/frames (TMSF) information.

BYTE MCI_TMSF_SECOND(

DWORD dwTMSF
);
Parameters

dwTMSF

Time in TMSF format.

Return Values

Returns the seconds component of the specified TMSF information.

Remarks

Time in TMSF format is expressed as a doubleword value with the least significant byte containing tracks, the next least significant byte containing minutes, the next least significant byte containing seconds, and the most significant byte containing frames.

The MCI_TMSF_SECOND macro is defined as follows:

#define MCI_TMSF_SECOND(tmsf) ((BYTE)((tmsf) >> 16))


MCI_TMSF_TRACK

The MCI_TMSF_TRACK macro retrieves the tracks component from a parameter containing packed tracks/minutes/seconds/frames (TMSF) information.

BYTE MCI_TMSF_TRACK(

DWORD dwTMSF
);
Parameters

dwTMSF

Time in TMSF format.

Return Values

Returns the tracks component of the specified TMSF information.

Remarks

Time in TMSF format is expressed as a doubleword value with the least significant byte containing tracks, the next least significant byte containing minutes, the next least significant byte containing seconds, and the most significant byte containing frames.

The MCI_TMSF_TRACK macro is defined as follows:

#define MCI_TMSF_TRACK(tmsf) ((BYTE)(tmsf))


MCIWndCanConfig

The MCIWndCanConfig macro determines if an MCI device can display a configuration dialog box. You can use this macro or explicitly send the MCIWNDM_CAN_CONFIG message.

BOOL MCIWndCanConfig(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns TRUE if the device supports configuration or FALSE otherwise.

See Also

MCIWNDM_CAN_CONFIG


MCIWndCanEject

The MCIWndCanEject macro determines if an MCI device can eject its media. You can use this macro or explicitly send the MCIWNDM_CAN_EJECT message.

BOOL MCIWndCanEject(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns TRUE if the device can eject its media or FALSE otherwise.

See Also

MCIWNDM_CAN_EJECT


MCIWndCanPlay

The MCIWndCanPlay macro determines if an MCI device can play a data file or content of some other kind. You can use this macro or explicitly send the MCIWNDM_CAN_PLAY message.

BOOL MCIWndCanPlay(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns TRUE if the device supports playing the data or FALSE otherwise.

See Also

MCIWNDM_CAN_PLAY


MCIWndCanRecord

The MCIWndCanRecord macro determines if an MCI device supports recording. You can use this macro or explicitly send the MCIWNDM_CAN_RECORD message.

BOOL MCIWndCanRecord(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns TRUE if the device supports recording or FALSE otherwise.

See Also

MCIWNDM_CAN_RECORD


MCIWndCanSave

The MCIWndCanSave macro determines if an MCI device can save data. You can use this macro or explicitly send the MCIWNDM_CAN_SAVE message.

BOOL MCIWndCanSave(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns TRUE if the device supports saving data or FALSE otherwise.

See Also

MCIWNDM_CAN_SAVE


MCIWndCanWindow

The MCIWndCanWindow macro determines if an MCI device supports window-oriented MCI commands. You can use this macro or explicitly send the MCIWNDM_CAN_WINDOW message.

BOOL MCIWndCanWindow(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns TRUE if the device supports window-oriented MCI commands or FALSE otherwise.

See Also

MCIWNDM_CAN_WINDOW


MCIWndChangeStyles

The MCIWndChangeStyles macro changes the styles used by the MCIWnd window. You can use this macro or explicitly send the MCIWNDM_CHANGESTYLES message.

LONG MCIWndChangeStyles(

hwnd,
mask,
value
);
Parameters

hwnd

Handle of the MCIWnd window.

mask

Mask that identifies the styles that can change. This mask is the bitwise OR operator of all styles that will be permitted to change.

value

New style settings for the window. Specify zero for this parameter to turn off all styles identified in the mask. For a list of the available styles, see the MCIWndCreate function.

Return Values

Returns zero.

Remarks

For an example of using MCIWndChangeStyles, see Pausing and Resuming Playback.

See Also

MCIWNDM_CHANGESTYLES


MCIWndClose

The MCIWndClose macro closes an MCI device or file associated with an MCIWnd window. Although the MCI device closes, the MCIWnd window is still open and can be associated with another MCI device. You can use this macro or explicitly send the MCI_CLOSE command.

LONG MCIWndClose(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns zero.

See Also

MCI_CLOSE


MCIWndDestroy

The MCIWndDestroy macro closes an MCI device or file associated with an MCIWnd window and destroys the window. You can use this macro or explicitly send the WM_CLOSE message.

VOID MCIWndDestroy(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

This macro does not return a value.

See Also

WM_CLOSE


MCIWndEject

The MCIWndEject macro sends a command to an MCI device to eject its media. You can use this macro or explicitly send the MCIWNDM_EJECT message.

LONG MCIWndEject(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWNDM_EJECT


MCIWndEnd

The MCIWndEnd macro moves the current position to the end of the content. You can use this macro or explicitly send the MCI_SEEK message.

LONG MCIWndEnd(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCI_SEEK


MCIWndGetActiveTimer

The MCIWndGetActiveTimer macro retrieves the update period used when the MCIWnd window is the active window. You can use this macro or explicitly send the MCIWNDM_GETACTIVETIMER message.

UINT MCIWndGetActiveTimer(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns the update period in milliseconds. The default is 500 milliseconds..

See Also

MCIWNDM_GETACTIVETIMER


MCIWndGetAlias

The MCIWndGetAlias macro retrieves the alias used to open an MCI device or file with the mciSendString function. You can use this macro or explicitly send the MCIWNDM_GETALIAS message.

UINT MCIWndGetAlias(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns the device alias.

See Also

mciSendString, MCIWNDM_GETALIAS


MCIWndGetDest

The MCIWndGetDest macro retrieves the coordinates of the destination rectangle used for zooming or stretching the images of an AVI file during playback. You can use this macro or explicitly send the MCIWNDM_GET_DEST message.

LONG MCIWndGetDest(

hwnd,
prc
);
Parameters

hwnd

Handle of the MCIWnd window.

prc

Address of a RECT structure to return the coordinates of the destination rectangle.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWNDM_GET_DEST


MCIWndGetDevice

The MCIWndGetDevice macro retrieves the name of the current MCI device. You can use this macro or explicitly send the MCIWNDM_GETDEVICE message.

LONG MCIWndGetDevice(

hwnd,
lp,
len
);
Parameters

hwnd

Handle of the MCIWnd window.

lp

Address of an application-defined buffer to return the device name.

len

Size, in bytes, of the buffer.

Return Values

Returns zero if successful or a nonzero value otherwise.

Remarks

If the null-terminated string containing the device name is longer than the buffer, MCIWnd truncates it.

See Also

MCIWNDM_GETDEVICE


MCIWndGetDeviceID

The MCIWndGetDeviceID macro retrieves the identifier of the current MCI device to use with the mciSendCommand function. You can use this macro or explicitly send the MCIWNDM_GETDEVICEID message.

UINT MCIWndGetDeviceID(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns the device identifier.

See Also

mciSendCommand, MCIWNDM_GETDEVICEID


MCIWndGetEnd

The MCIWndGetEnd macro retrieves the location of the end of the content of an MCI device or file. You can use this macro or explicitly send the MCIWNDM_GETEND message.

LONG MCIWndGetEnd(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns the location in the current time format.

See Also

MCIWNDM_GETEND


MCIWndGetError

The MCIWndGetError macro retrieves the last MCI error encountered. You can use this macro or explicitly send the MCIWNDM_GETERROR message.

LONG MCIWndGetError(

hwnd,
lp,
len
);
Parameters

hwnd

Handle of the MCIWnd window.

lp

Address of an application-defined buffer used to return the error string.

len

Size, in bytes, of the error buffer.

Return Values

Returns the integer error value if successful.

Remarks

If lp is a valid pointer, a null-terminated string corresponding to the error is returned in its buffer. If the error string is longer than the buffer, MCIWnd truncates it.

See Also

MCIWNDM_GETERROR


MCIWndGetFileName

The MCIWndGetFileName macro retrieves the filename used by an MCI device. You can use this macro or explicitly send the MCIWNDM_GETFILENAME message.

LONG MCIWndGetFileName(

hwnd,
lp,
len
);
Parameters

hwnd

Handle of the MCIWnd window.

lp

Address of an application-defined buffer to return the filename.

len

Size, in bytes, of the buffer.

Return Values

Returns zero if successful or 1 otherwise.

Remarks

If the null-terminated string containing the filename is longer than the buffer, MCIWnd truncates the filename.

See Also

MCIWNDM_GETFILENAME


MCIWndGetInactiveTimer

The MCIWndGetInactiveTimer macro retrieves the update period used when the MCIWnd window is the inactive window. You can use this macro or explicitly send the MCIWNDM_GETINACTIVETIMER message.

UINT MCIWndGetInactiveTimer(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns the update period, in milliseconds. The default value is 2000 milliseconds.

See Also

MCIWNDM_GETINACTIVETIMER


MCIWndGetLength

The MCIWndGetLength macro retrieves the length of the content or file currently used by an MCI device. You can use this macro or explicitly send the MCIWNDM_GETLENGTH message.

LONG MCIWndGetLength(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns the length. The units for the length depend on the current time format.

Remarks

This value added to the value returned for the MCIWndGetStart macro equals the end of the content.

See Also

MCIWndGetStart, MCIWNDM_GETLENGTH


MCIWndGetMode

The MCIWndGetMode macro retrieves the current operating mode of an MCI device. MCI devices have several operating modes, which are designated by constants. You can use this macro or explicitly send the MCIWNDM_GETMODE message.

LONG MCIWndGetMode(

hwnd,
lp,
len
);
Parameters

hwnd

Handle of the MCIWnd window.

lp

Address of the application-defined buffer used to return the mode.

len

Size, in bytes, of the buffer.

Return Values

Returns an integer corresponding to the MCI constant defining the mode.

Remarks

If the null-terminated string describing the mode is longer than the buffer, it is truncated.

Not all devices can operate in every mode. For example, the MCIAVI device is a playback device; it doesn't support the recording mode. The following modes can be retrieved by using MCIWNDM_GETMODE:

Operating mode	MCI constant
not ready	MCI_MODE_NOT_READY
open	MCI_MODE_OPEN
paused	MCI_MODE_PAUSE
playing	MCI_MODE_PLAY
recording	MCI_MODE_RECORD
seeking	MCI_MODE_SEEK
stopped	MCI_MODE_STOP
See Also

MCIWNDM_GETMODE


MCIWndGetPalette

The MCIWndGetPalette macro retrieves a handle of the palette used by an MCI device. You can use this macro or explicitly send the MCIWNDM_GETPALETTE message.

HPALETTE MCIWndGetPalette(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns the handle of the palette if successful.

See Also

MCIWNDM_GETPALETTE


MCIWndGetPosition

The MCIWndGetPosition macro retrieves the numerical value of the current position within the content of the MCI device. You can use this macro or explicitly send the MCIWNDM_GETPOSITION message.

LONG MCIWndGetPosition(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns an integer corresponding to the current position. The units for the position value depend on the current time format.

See Also

MCIWNDM_GETPOSITION


MCIWndGetPositionString

The MCIWndGetPositionString macro retrieves the numerical value of the current position within the content of the MCI device. This macro also provides the current position in string form in an application-defined buffer. You can use this macro or explicitly send the MCIWNDM_GETPOSITION message.

LONG MCIWndGetPositionString(

hwnd,
lp,
len
);
Parameters

hwnd

Handle of the MCIWnd window.

lp

Address of an application-defined buffer used to return the position. Use zero to inhibit retrieval of the position as a string.

If the device supports tracks, the string position information is returned in the form TT:MM:SS:FF where TT corresponds to tracks, MM and SS correspond to minutes and seconds, and FF corresponds to frames.

len

Size, in bytes, of the buffer. If the null-terminated string is longer than the buffer, it is truncated. Use zero to inhibit retrieval of the position as a string.

Return Values

Returns an integer corresponding to the current position. The units for the position value depend on the current time format.

See Also

MCIWNDM_GETPOSITION


MCIWndGetRepeat

The MCIWndGetRepeat macro determines if continuous playback has been activated. You can use this macro or explicitly send the MCIWNDM_GETREPEAT message.

BOOL MCIWndGetRepeat(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns TRUE if continuous playback is activated or FALSE otherwise.

See Also

MCIWNDM_GETREPEAT


MCIWndGetSource

The MCIWndGetSource macro retrieves the coordinates of the source rectangle used for cropping the images of an AVI file during playback. You can use this macro or explicitly send the MCIWNDM_GET_SOURCE message.

LONG MCIWndGetSource(

hwnd,
prc
);
Parameters

hwnd

Handle of the MCIWnd window.

prc

Address of a RECT structure to contain the coordinates of the source rectangle.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWNDM_GET_SOURCE, RECT


MCIWndGetSpeed

The MCIWndGetSpeed macro retrieves the playback speed of an MCI device. You can use this macro or explicitly send the MCIWNDM_GETSPEED message.

LONG MCIWndGetSpeed(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns the playback speed if successful. The value for normal speed is 1000. Larger values indicate faster speeds; smaller values indicate slower speeds.

See Also

MCIWNDM_GETSPEED


MCIWndGetStart

The MCIWndGetStart macro retrieves the location of the beginning of the content of an MCI device or file. You can use this macro or explicitly send the MCIWNDM_GETSTART message.

LONG MCIWndGetStart(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns the location in the current time format.

Typically, the return value is zero; but some devices use a nonzero starting location. Seeking to this location sets the device to the start of the media.

See Also

MCIWNDM_GETSTART


MCIWndGetStyles

The MCIWndGetStyles macro retrieves the flags specifying the current MCIWnd window styles used by a window. You can use this macro or explicitly send the MCIWNDM_GETSTYLES message.

UINT MCIWndGetStyles(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns a value representing the current styles of the MCIWnd window. The return value is the bitwise OR operator of the MCIWnd window styles (MCIWNDF flags).

See Also

MCIWNDM_GETSTYLES


MCIWndGetTimeFormat

The MCIWndGetTimeFormat macro retrieves the current time format of an MCI device in two forms: as a numerical value and as a string. You can use this macro or explicitly send the MCIWNDM_GETTIMEFORMAT message.

LONG MCIWndGetTimeFormat(

hwnd,
lp,
len
);
Parameters

hwnd

Handle of the MCIWnd window.

lp

Address of a buffer to contain the null-terminated string form of the time format.

len

Size, in bytes, of the buffer.

Return Values

Returns an integer corresponding to the MCI constant defining the time format.

Remarks

If the time format string is longer than the return buffer, MCIWnd truncates the string.

An MCI device can support one or more of the following time formats:

Time format	MCI constant
Bytes	MCI_FORMAT_BYTES
Frames	MCI_FORMAT_FRAMES
Hours, minutes, seconds	MCI_FORMAT_HMS
Milliseconds	MCI_FORMAT_MILLISECONDS
Minutes, seconds, frames	MCI_FORMAT_MSF
Samples	MCI_FORMAT_SAMPLES
SMPTE 24	MCI_FORMAT_SMPTE_24
SMPTE 25	MCI_FORMAT_SMPTE_25
SMPTE 30 drop	MCI_FORMAT_SMPTE_30DROP
SMPTE 30 (non-drop)	MCI_FORMAT_SMPTE_30
Tracks, minutes, seconds, frames	MCI_FORMAT_TMSF
See Also

MCIWNDM_GETTIMEFORMAT


MCIWndGetVolume

The MCIWndGetVolume macro retrieves the current volume setting of an MCI device. You can use this macro or explicitly send the MCIWNDM_GETVOLUME message.

LONG MCIWndGetVolume(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns the current volume setting. The default value is 1000. Higher values indicate louder volumes; lower values indicate quieter volumes.

See Also

MCIWNDM_GETVOLUME


MCIWndGetZoom

The MCIWndGetZoom macro retrieves the current zoom value used by an MCI device. You can use this macro or explicitly send the MCIWNDM_GETZOOM message.

UINT MCIWndGetZoom(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns the most recent values used with MCIWndSetZoom.

A return value of 100 indicates the image is not zoomed. A value of 200 indicates the image is enlarged to twice its original size. A value of 50 indicates the image is reduced to half its original size.

See Also

MCIWNDM_GETZOOM, MCIWndSetZoom


MCIWndHome

The MCIWndHome macro moves the current position to the beginning of the content. You can use this macro or explicitly send the MCI_SEEK command.

LONG MCIWndHome(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCI_SEEK


MCIWndNew

The MCIWndNew macro creates a new file for the current MCI device. You can use this macro or explicitly send the MCIWNDM_NEW message.

LONG MCIWndNew(

hwnd,
lp
);
Parameters

hwnd

Handle of the MCIWnd window.

lp

Address of a buffer containing the name of the MCI device that will use the file.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWNDM_NEW


MCIWndOpen

The MCIWndOpen macro opens an MCI device and associates it with an MCIWnd window. For MCI devices that use data files, this macro can also open a specified data file, name a new file to be created, or display a dialog box to let the user select a file to open. You can use this macro or explicitly send the MCIWNDM_OPEN message.

LONG MCIWndOpen(

hwnd,
szFile,
wFlags
);
Parameters

hwnd

Handle of the MCIWnd window.

szFile

Address of a null-terminated string identifying the filename or MCI device name to open. Specify −1 for this parameter to display the Open dialog box.

wFlags

Flags associated with the device or file to open. The MCIWNDOPENF_NEW flag specifies a new file is to be created with the name specified in szFile.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWNDM_OPEN


MCIWndOpenDialog

The MCIWndOpenDialog macro opens a user-specified data file and corresponding type of MCI device, and associates them with an MCIWnd window. This macro displays the Open dialog box for the user to select the data file to associate with an MCI window. You can use this macro or explicitly send the MCIWNDM_OPEN message.

LONG MCIWndOpenDialog(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWNDM_OPEN


MCIWndOpenInterface

The MCIWndOpenInterface macro attaches the data stream or file associated with the specified interface to an MCIWnd window. You can use this macro or explicitly send the MCIWNDM_OPENINTERFACE message.

MCIWndOpenInterface(

hwnd,
pUnk
);
Parameters

hwnd

Handle of the MCIWnd window.

pUnk

Address of an IAVI interface that points to a file or a data stream in a file.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWNDM_OPENINTERFACE


MCIWndPause

The MCIWndPause macro sends a command to an MCI device to pause playing or recording.

LONG MCIWndPause(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns zero if successful or an error otherwise.


MCIWndPlay

The MCIWndPlay macro sends a command to an MCI device to start playing from the current position in the content. You can use this macro or explicitly send the MCI_PLAY command.

LONG MCIWndPlay(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCI_PLAY


MCIWndPlayFrom

The MCIWndPlayFrom macro plays the content of an MCI device from the specified location to the end of the content or until another command stops playback. You can use this macro or explicitly send the MCIWNDM_PLAYFROM message.

LONG MCIWndPlayFrom(

hwnd,
lPos
);
Parameters

hwnd

Handle of the MCIWnd window.

lPos

Starting location. The units for the starting location depend on the current time format.

Return Values

Returns zero if successful or an error otherwise.

Remarks

You can also specify both a starting and ending location for playback by using the MCIWndPlayFromTo macro.

See Also

MCIWNDM_PLAYFROM, MCIWndPlayFromTo


MCIWndPlayFromTo

The MCIWndPlayFromTo macro plays a portion of content between specified starting and ending locations. This macro seeks to the specified point to begin playback, then plays the content to the specified ending location. This macro is defined using the MCIWndSeek and MCIWndPlayTo macros, which in turn use the MCI_SEEK command and the MCIWNDM_PLAYTO message.

LONG MCIWndPlayFromTo(

hwnd,
lStart,
lEnd
);
Parameters

hwnd

Handle of the MCIWnd window.

lStart

Position to seek; it is also the starting location.

lEnd

Ending location.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The units for the seek position depend on the current time format.

See Also

MCI_SEEK, MCIWNDM_PLAYTO, MCIWndPlayTo, MCIWndSeek


MCIWndPlayReverse

The MCIWndPlayReverse macro plays the current content in the reverse direction, beginning at the current position and ending at the beginning of the content or until another command stops playback. You can use this macro or explicitly send the MCIWNDM_PLAYREVERSE message.

LONG MCIWndPlayReverse(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWNDM_PLAYREVERSE


MCIWndPlayTo

The MCIWndPlayTo macro plays the content of an MCI device from the current position to the specified ending location or until another command stops playback. If the specified ending location is beyond the end of the content, playback stops at the end of the content. You can use this macro or explicitly send the MCIWNDM_PLAYTO message.

LONG MCIWndPlayTo(

hwnd,
lPos
);
Parameters

hwnd

Handle of the MCIWnd window.

lPos

Ending location. The units for the ending location depend on the current time format.

Return Values

Returns zero if successful or an error otherwise.

Remarks

You can also specify both a starting and ending location for playback by using the MCIWndPlayFromTo macro.

See Also

MCIWNDM_PLAYTO, MCIWndPlayFromTo


MCIWndPutDest

The MCIWndPutDest macro redefines the coordinates of the destination rectangle used for zooming or stretching the images of an AVI file during playback. You can use this macro or explicitly send the MCIWNDM_PUT_DEST message.

LONG MCIWndPutDest(

hwnd,
prc
);
Parameters

hwnd

Handle of the MCIWnd window.

prc

Address of a RECT structure containing the coordinates of the destination rectangle.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWNDM_PUT_DEST


MCIWndPutSource

The MCIWndPutSource macro redefines the coordinates of the source rectangle used for cropping the images of an AVI file during playback. You can use this macro or explicitly send the MCIWNDM_PUT_SOURCE message.

LONG MCIWndPutSource(

hwnd,
prc
);
Parameters

hwnd

Handle of the MCIWnd window.

prc

Address of a RECT structure containing the coordinates of the source rectangle.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWNDM_PUT_SOURCE


MCIWndRealize

The MCIWndRealize macro controls how an MCI window realized in the foreground or background. This macro also causes the palette for the MCI window to be realized in the process. You can use this macro or explicitly send the MCIWNDM_REALIZE message.

LONG MCIWndRealize(

hwnd,
fBkgnd
);
Parameters

hwnd

Handle of the MCIWnd window.

fBkgnd

Background flag. Specify TRUE for this parameter for the window to be realized in the background or FALSE if the window can be realized in the foreground.

Return Values

Returns zero if successful or an error otherwise.

Remarks

A common use for MCIWndRealize is to coordinate palette ownership between an MCI control and the application that contains it. The application can have the MCI window realize in the background and realize its own palette in the foreground.

If your application contains an MCI control, but does not need to realize its palette, you can use this macro to handle the WM_PALETTECHANGED and WM_QUERYNEWPALETTE messages, instead of using RealizePalette. However, it is usually easier to call the SendMessage function to forward the message to the MCIWnd window, which will automatically realize the palette.

See Also

MCIWNDM_REALIZE, RealizePalette, SendMessage, WM_PALETTECHANGED, WM_QUERYNEWPALETTE


MCIWndRecord

The MCIWndRecord macro begins recording content using the MCI device. The recording process begins at the current position in the content and will overwrite existing data for the duration of the recording.

LONG MCIWndRecord(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The function that an MCI device performs during recording depends on the characteristics of the device. An MCI device that uses files, such as a waveform-audio device, sends data to the file during recording. An MCI device that does not use files, such as a video-cassette recorder, receives and externally records data on another medium.


MCIWndResume

The MCIWndResume macro resumes playback or recording content from the paused mode. This macro restarts playback or recording from the current position in the content. You can use this macro or explicitly send the MCI_RESUME command.

LONG MCIWndResume(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCI_RESUME


MCIWndReturnString

The MCIWndReturnString macro retrieves the reply to the most recent MCI string command sent to an MCI device. Information in the reply is supplied as a null-terminated string. You can use this macro or explicitly send the MCIWNDM_RETURNSTRING message.

LONG MCIWndReturnString(

hwnd,
lp,
len
);
Parameters

hwnd

Handle of the MCIWnd window.

lp

Address of an application-defined buffer to contain the null-terminated string.

len

Size, in bytes, of the buffer.

Return Values

Returns an integer corresponding to the MCI string.

Remarks

If the null-terminated string is longer than the buffer, the string is truncated.

See Also

MCIWNDM_RETURNSTRING


MCIWndSave

The MCIWndSave macro saves the content currently used by an MCI device. This macro can save the content to a specified data file or display the Save dialog box to let the user select a filename to store the content. You can use this macro or explicitly send the MCI_SAVE command.

LONG MCIWndSave(

hwnd,
szFile
);
Parameters

hwnd

Handle of the MCIWnd window.

szFile

Null-terminated string containing the name and path of the destination file. Specify  − 1 for this parameter to display the Save dialog box.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCI_SAVE


MCIWndSaveDialog

The MCIWndSaveDialog macro saves the content currently used by an MCI device. This macro displays the Save dialog box to let the user select a filename to store the content. You can use this macro or explicitly send the MCI_SAVE command.

LONG MCIWndSaveDialog(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCI_SAVE


MCIWndSeek

The MCIWndSeek macro moves the playback position to the specified location in the content. You can use this macro or explicitly use the MCI_SEEK command.

LONG MCIWndSeek(

hwnd,
lPos
);
Parameters

hwnd

Handle of the MCIWnd window.

lPos

Position to seek. You can specify a position using the current time format, the MCIWND_START constant to designate the beginning of the content, or the MCIWND_END constant to designate the end of the content.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCI_SEEK


MCIWndSendString

The MCIWndSendString macro sends an MCI command in string form to the device associated with the MCIWnd window. You can use this macro or explicitly send the MCIWNDM_SENDSTRING message.

LONG MCIWndSendString(

hwnd,
sz
);
Parameters

hwnd

Handle of the MCIWnd window.

sz

String command to send to the MCI device.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The message handler for MCIWndSendString (and MCIWNDM_SENDSTRING) appends a device alias to the MCI command you send to the device. Therefore, you should not use any alias in an MCI command that you issue with MCIWndSendString.

See Also

MCIWNDM_SENDSTRING


MCIWndSetActiveTimer

The MCIWndSetActiveTimer macro sets the update period used by MCIWnd to update the trackbar in the MCIWnd window, update position information displayed in the window title bar, and send notification messages to the parent window when the MCIWnd window is active. You can use this macro or explicitly send the MCIWNDM_SETACTIVETIMER message.

VOID MCIWndSetActiveTimer(

hwnd,
active
);
Parameters

hwnd

Handle of the MCIWnd window.

active

Update period, in milliseconds. The default is 500 milliseconds.

Return Values

This macro does not return a value.

See Also

MCIWNDM_SETACTIVETIMER


MCIWndSetInactiveTimer

The MCIWndSetInactiveTimer macro sets the update period used by MCIWnd to update the trackbar in the MCIWnd window, update position information displayed in the window title bar, and send notification messages to the parent window when the MCIWnd window is inactive. You can use this macro or explicitly send the MCIWNDM_SETINACTIVETIMER message.

VOID MCIWndSetInactiveTimer(

hwnd,
inactive
);
Parameters

hwnd

Handle of the MCIWnd window.

inactive

Update period, in milliseconds. The default is 2000 milliseconds.

Return Values

This macro does not return a value.

See Also

MCIWNDM_SETINACTIVETIMER


MCIWndSetOwner

The MCIWndSetOwner macro sets the window to receive notification messages associated with the MCIWnd window. You can use this macro or explicitly send the MCIWNDM_SETOWNER message.

LONG MCIWndSetOwner(

hwnd,
hwndP
);
Parameters

hwnd

Handle of the MCIWnd window.

hwndP

Handle of the window to receive the notification messages.

Return Values

Returns zero.

See Also

MCIWNDM_SETOWNER


MCIWndSetPalette

The MCIWndSetPalette macro sends a palette handle to the MCI device associated with the MCIWnd window. You can use this macro or explicitly send the MCIWNDM_SETPALETTE message.

MCIWndSetPalette(

hwnd,
hpal
);
Parameters

hwnd

Handle of the MCIWnd window.

hpal

Palette handle.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWNDM_SETPALETTE


MCIWndSetRepeat

The MCIWndSetRepeat macro sets the repeat flag associated with continuous playback. You can use this macro or explicitly send the MCIWNDM_SETREPEAT message.

VOID MCIWndSetRepeat(

hwnd,
f
);
Parameters

hwnd

Handle of the MCIWnd window.

f

New state of the repeat flag. Specify TRUE to turn on continuous playback.

Return Values

Returns zero.

Remarks

The MCIWndSetRepeat macro only affects playback that the user initiates by hitting the play button on the toolbar. It will not affect playback started with the MCIWndPlay macro.

Currently, MCIAVI is the only device that supports continuous playback.

See Also

MCIWNDM_SETREPEAT, MCIWndPlay


MCIWndSetSpeed

The MCIWndSetSpeed macro sets the playback speed of an MCI device. You can use this macro or explicitly send the MCIWNDM_SETSPEED message.

LONG MCIWndSetSpeed(

hwnd,
iSpeed
);
Parameters

hwnd

Handle of the MCIWnd window.

iSpeed

Playback speed. Specify 1000 for normal speed, larger values for faster speeds, and smaller values for slower speeds.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWNDM_SETSPEED


MCIWndSetTimeFormat

The MCIWndSetTimeFormat macro sets the time format of an MCI device. You can use this macro or explicitly send the MCIWNDM_SETTIMEFORMAT message.

LONG MCIWndSetTimeFormat(

hwnd,
lp
);
Parameters

hwnd

Handle of the MCIWnd window.

lp

Address of a buffer containing the null-terminated string indicating the time format. Specify “frames” to set the time format to frames, or “ms” to set the time format to milliseconds.

Return Values

Returns zero if successful or an error otherwise.

Remarks

An application can specify time formats other than frames or milliseconds as long as the formats are supported by the MCI device. Noncontinuous formats, such as tracks and SMPTE, can cause the trackbar to behave erratically. For these time formats, you might want to turn off the toolbar by using the MCIWndChangeStyles macro and specifying the MCIWNDF_NOPLAYBAR window style.

If you want to set the time format to frames or milliseconds, you can also use the MCIWndUseFrames or MCIWndUseTime macro. For a list of time formats, see the MCIWndGetTimeFormat macro.

See Also

MCIWndChangeStyles, MCIWndGetTimeFormat, MCIWNDM_SETTIMEFORMAT, MCIWndUseFrames, MCIWndUseTime


MCIWndSetTimers

The MCIWndSetTimers macro sets the update periods used by MCIWnd to update the trackbar in the MCIWnd window, update the position information displayed in the window title bar, and send notification messages to the parent window. You can use this macro or explicitly send the MCIWNDM_SETTIMERS message.

VOID MCIWndSetTimers(

hwnd,
active,
inactive
);
Parameters

hwnd

Handle of the MCIWnd window.

active

Update period used by MCIWnd when it is the active window. The default value is 500 milliseconds. Storage for this value is limited to 16 bits.

inactive

Update period used by MCIWnd when it is the inactive window. The default value is 2000 milliseconds. Storage for this value is limited to 16 bits.

Return Values

This macro does not return a value.

See Also

MCIWNDM_SETTIMERS


MCIWndSetVolume

The MCIWndSetVolume macro sets the volume level of an MCI device. You can use this macro or explicitly send the MCIWNDM_SETVOLUME message.

LONG MCIWndSetVolume(

hwnd,
iVol
);
Parameters

hwnd

Handle of the MCIWnd window.

iVol

New volume level. Specify 1000 for normal volume level. Specify a higher value for a louder volume or a lower value for a quieter volume.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWNDM_SETVOLUME


MCIWndSetZoom

The MCIWndSetZoom macro resizes a video image according to a zoom factor. This marco adjusts the size of an MCIWnd window while maintaining a constant aspect ratio. You can use this macro or explicitly send the MCIWNDM_SETZOOM message.

VOID MCIWndSetZoom(

hwnd,
iZoom
);
Parameters

hwnd

Handle of the MCIWnd window.

iZoom

Zoom factor expressed as a percentage of the original image. Specify 100 to display the image at its authored size, 200 to display the image at twice its normal size, or 50 to display the image at half its normal size.

Return Values

This macro does not return a value.

See Also

MCIWNDM_SETZOOM


MCIWndStep

The MCIWndStep macro moves the current position in the content forward or backward by a specified increment. You can use this macro or explicitly send the MCI_STEP command.

LONG MCIWndStep(

hwnd,
n
);
Parameters

hwnd

Handle of the MCIWnd window.

n

Step value. Negative values step the device through the content in reverse. The units for the step value depend on the current time format.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCI_STEP


MCIWndStop

The MCIWndStop macro stops playing or recording the content of the MCI device associated with the MCIWnd window. You can use this macro or explicitly send the MCI_STOP command.

LONG MCIWndStop(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCI_STOP


MCIWndUseFrames

The MCIWndUseFrames macro sets the time format of an MCI device to frames. You can use this macro or explicitly send the MCIWNDM_SETTIMEFORMAT message.

LONG MCIWndUseFrames(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWNDM_SETTIMEFORMAT


MCIWndUseTime

The MCIWndUseTime macro sets the time format of an MCI device to milliseconds. You can use this macro or explicitly send the MCIWNDM_SETTIMEFORMAT message.

LONG MCIWndUseTime(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWNDM_SETTIMEFORMAT


MCIWndValidateMedia

The MCIWndValidateMedia macro updates the starting and ending locations of the content, the current position in the content, and the trackbar according to the current time format. You can use this macro or explicitly send the MCIWNDM_VALIDATEMEDIA message.

VOID MCIWndValidateMedia(

hwnd
);
Parameters

hwnd

Handle of the MCIWnd window.

Return Values

This macro does not return a value.

Remarks

Typically, you should not need to use this macro; however, if your application changes the time format of a device without using MCIWnd; the starting and ending locations of the content, as well as the trackbar, continue to use the old format. You can use this macro to update these values.

See Also

MCIWNDM_VALIDATEMEDIA


MEVT_EVENTPARM

The MEVT_EVENTPARM macro retrieves the event parameters or length from the value specified in the dwEvent member of a MIDIEVENT structure.

DWORD MEVT_EVENTPARM(

DWORD dwEvent
);
Parameters

dwEvent

Code for the MIDI event and the event parameters or length, as specified in the dwEvent member of the MIDIEVENT structure.

Remarks

The MEVT_EVENTPARM macro is defined as follows:

#define MEVT_EVENTPARM(x) ((DWORD) ((x)&0x00FFFFFFL))

See Also

MIDIEVENT


MEVT_EVENTTYPE

The MEVT_EVENTTYPE macro retrieves the event type from the value specified in the dwEvent member of a MIDIEVENT structure.

BYTE MEVT_EVENTTYPE(

DWORD dwEvent
);
Parameters

dwEvent

Code for the MIDI event and the event parameters or length, as specified in the dwEvent member of the MIDIEVENT structure.

Remarks

The MEVT_EVENTTYPE macro is defined as follows:

#define MEVT_EVENTTYPE(x) ((BYTE) (((x)>>24)&0xFF))

See Also

MIDIEVENT


mmioFOURCC

The mmioFOURCC macro converts four characters into a four-character code.

FOURCC mmioFOURCC(

CHAR ch0,
CHAR ch1,
CHAR ch2,
CHAR ch3
);
Parameters

ch0, ch1, ch2, and ch3

First, second, third, and fourth characters of the four-character code.

Return Values

Returns the four-character code created from the given characters.

Remarks

This macro does not check whether the four-character code it returns is valid.

The mmioFOURCC macro is defined as follows:

#define mmioFOURCC(ch0, ch1, ch2, ch3) \

    MAKEFOURCC(ch0, ch1, ch2, ch3);

The MAKEFOURCC macro, in turn, is defined as follows:

#define MAKEFOURCC(ch0, ch1, ch2, ch3)  \

    ((DWORD)(BYTE)(ch0) | ((DWORD)(BYTE)(ch1) << 8) |  \

    ((DWORD)(BYTE)(ch2) << 16) | ((DWORD)(BYTE)(ch3) << 24 ));


sndAlias

The sndAlias macro creates an alias identifier from two characters, for use with the PlaySound function.

DWORD sndAlias(

ch0,
ch1
);
Parameters

ch0 and ch1

Characters describing the sound alias.

Return Values

Returns an alias identifier corresponding to the two supplied characters.

Remarks

This macro is defined as follows:

sndAlias(ch0, ch1)    (SND_ALIAS_START + (DWORD)(BYTE)(ch0) |

    ((DWORD)(BYTE)(ch1) << 8))

See Also

PlaySound


MCI

The Media Control Interface (MCI) provides standard commands for playing multimedia devices and recording multimedia resource files. These commands are a generic interface to nearly every kind of multimedia device.


About MCI

MCI provides applications with device-independent capabilities for controlling audio and visual peripherals. Your application can use MCI to control any supported multimedia device, including waveform-audio devices, MIDI sequencers, CD audio devices, and digital-video (video playback) devices.


MCI Command Strings and Messages

MCI supports command strings and command messages. You can use either strings or messages, or both, in your MCI application.

•	The command-message interface consists of constants and structures. You use the mciSendCommand function to send a message to an MCI device.

•	The command-string interface provides a textual version of the command messages. You use the mciSendString function to send a string to an MCI device. Command strings duplicate the functionality of the command messages. The Microsoft Windows operating system converts the command strings to command messages before sending them to the MCI driver for processing.

The command messages that retrieve information do so in the form of structures, which are easy to interpret in a C application. These structures can contain information on many different aspects of a device. The command strings that retrieve information do so in the form of strings, and can only retrieve one string at a time. Your application must parse or test each string to interpret it. You might find that the command messages are easier to use than the command strings in some cases, but the command strings are easy to remember and implement. Some MCI applications use command strings when the return value will not be used (other than to verify success) and command messages when retrieving information from the device.

When commands are discussed, this overview uses the string form of the command followed by the message form in parentheses.


Command Strings

MCI supports command strings and command messages. This section discusses how to use MCI command strings. For information about the command-message interface, see Command Messages.

You can send a string command by using the mciSendString function, which includes parameters for the string command and a buffer for any returned information.


Sending Command Strings

Windows provides two functions to send command strings to devices and to query devices for error information:

•	The mciSendString function sends a command string to an MCI device.

•	The mciGetErrorString function returns the error string corresponding to an error number.

The mciSendString function returns zero if successful. If the function fails, the low-order word of the return value contains an error code. You can pass this error code to mciGetErrorString to get a text description of it.


Syntax of Command Strings

MCI command strings use a consistent verb-object-modifier syntax. Each command string includes a command, a device identifier, and command arguments. Arguments are optional for some commands and required for others.

A command string has the following form:

command device_id arguments

These components contain the following information:

•	The command specifies an MCI command, such as open, close, or play.

•	The device_id identifies an instance of an MCI driver. The device_id is created when the device is opened.

•	The arguments specify the flags and variables used by the command. Flags are keywords recognized with the MCI command. Variables are numbers or strings that apply to the MCI command or flag.

For example, the play command uses the arguments “from position” and “to position” to indicate the positions at which to start and end play. You can list the flags used with a command in any order. When you use a flag that has a variable associated with it, you must supply a value for the variable.

Unspecified (and optional) command arguments assume a default value.

The following example function sends the play command with the “from” and “to” flags.

DWORD PlayFromTo(LPSTR lpstrAlias, DWORD dwFrom, DWORD dwTo)

{

    char achCommandBuff[128];

    // Form the command string.

    wsprintf(achCommandBuff, "play %s from %u to %u",

        lpstrAlias, dwFrom, dwTo);

    // Send the command string.

    return mciSendString(achCommandBuff, NULL, 0, NULL);

}


Data Types for Command Variables

You can use the following data types for the variables in a command string:

Data type	Description
Strings	String data types are delimited by leading and trailing white spaces and quotation marks. MCI removes single quotation marks from a string. To put a quotation mark in a string, use a set of two quotation marks where you want to embed your quotation mark. To use an empty string, use two quotation marks delimited by leading and trailing white spaces.
Signed long integers	Signed long integer data types are delimited by leading and trailing white spaces. Unless otherwise specified, integers can be positive or negative. If you use negative integers, you should not separate the minus sign and the first digit with a space.
Rectangles	Rectangle data types are an ordered list of four signed short values. White space delimits this data type and separates each integer in the list.


Command Messages

MCI supports command strings and command messages. This section discusses  how to use MCI command messages. For information about the command-string interface, see Command Strings.

The command-message interface is designed to be used by applications requiring a C-language interface to control multimedia devices. It uses a message-passing paradigm to communicate with MCI devices. You can send a command by using the mciSendCommand function.


Sending Command Messages

The Microsoft Windows operating system provides two functions for sending command messages to devices and to query devices for error information: mciSendCommand and mciGetErrorString. The mciSendCommand function sends a command message to an MCI device. The mciGetErrorString function returns the error string corresponding to an error number.

The mciSendCommand function returns zero if successful. If the function fails, the low-order word of the return value contains an error code. You can pass this error code to mciGetErrorString to get a text description of it.


Syntax of Command Messages

MCI command messages consist of the following three elements:

•	A constant message value

•	A structure containing parameters for the command

•	A set of flags specifying options for the command and validating fields in the parameter block

The following example sends the MCI_PLAY command to the device identified by a device identifier.

mciSendCommand(wDeviceID,            // device identifier

    MCI_PLAY,                        // command message

    0,                               // flags

    (DWORD)(LPVOID) &mciPlayParms);  // parameter block

The device identifier given in the first parameter is retrieved when the device is opened using the MCI_OPEN command. The last parameter is the address of an MCI_PLAY_PARMS structure, which might contain information about where to begin and end playback. Many MCI command messages use a structure to contain parameters of this kind. The first member of each of these structures identifies the window that receives an MM_MCINOTIFY message when the operation finishes.


Classifications of MCI Commands

MCI defines four command classifications: system, required, basic, and extended. The following list describes these command classifications:

•	System commands are handled by MCI directly, rather than by the driver.

•	Required commands are handled by the driver. All MCI drivers must support the required commands and flags.

•	Basic commands (or optional commands) are used by some devices. If a device supports a basic command, it must support a defined set of flags for that command.

•	Extended commands are specific to a device type or driver. Extended commands include commands, like the put (MCI_PUT) and where (MCI_WHERE) commands for the digitalvideo and overlay device types, and extensions to existing commands (like the “stretch” flag of the status (MCI_STATUS) command for the overlay device type).

While system and required commands are the minimum command set for any MCI driver, basic and extended commands are not supported by all drivers. Your application can always use system and required commands and their flags, but if it needs to use a basic or extended command or flag, it should first query the driver by using the capability (MCI_GETDEVCAPS) command. The following sections summarize the specific commands in each category.

System Commands

MCI processes the following system commands directly, rather than passing them to MCI devices.

String	Message	Description
break	MCI_BREAK	Sets a break key for an MCI device.
sysinfo	MCI_SYSINFO	Returns information about MCI devices.
Required Commands

All MCI devices support the following required commands.

String	Message	Description
capability	MCI_GETDEVCAPS	Obtains the capabilities of a device.
close	MCI_CLOSE	Closes the device.
info	MCI_INFO	Obtains textual information from a device.
open	MCI_OPEN	Initializes the device.
status	MCI_STATUS	Obtains status information from the device. Some of this command’s flags are not required, so it is also a basic command.
Devices must also support a standard set of command flags for the required commands.

Basic Commands

The following list summarizes the basic commands. The use of these commands by an MCI device is optional.

String	Message	Description
load	MCI_LOAD	Loads data from a file.
pause	MCI_PAUSE	Stops playing. Playback or recording can be resumed at the current position.
play	MCI_PLAY	Starts transmitting output data.
record	MCI_RECORD	Starts recording input data.
resume	MCI_RESUME	Resumes playing or recording on a paused device.
save	MCI_SAVE	Saves data to a disk file.
seek	MCI_SEEK	Seeks forward or backward.
set	MCI_SET	Sets the operating state of the device.
status	MCI_STATUS	Obtains status information about the device. This is also a required command; since some of its flags are not required, it is also listed here. (The optional items support devices that use linear media with identifiable positions.)
stop	MCI_STOP	Stops playing.
If a driver supports a basic command, it must also support a standard set of flags for the command.

Extended Commands

Some MCI devices have additional commands, or they add flags to existing commands. While some extended commands apply only to a specific device driver, most of them apply to all drivers of a particular device type. For example, the command set for the sequencer device type extends the set (MCI_SET) command to add time formats that are needed by MIDI sequencers.

You should not assume that the device supports the extended commands or flags. You can use the capability (MCI_GETDEVCAPS) command to determine whether a specific feature is supported, and your application should be ready to deal with “unsupported command” or “unsupported function” return values.

The following extended commands are available with the listed device types.

String	Message	Device types	Description
configure	MCI_CONFIGURE	digitalvideo	Displays a configuration dialog box.
cue	MCI_CUE	digitalvideo, waveaudio	Prepares for playing or recording.
delete	MCI_DELETE	waveaudio	Deletes a data segment from the media file.
escape	MCI_ESCAPE	videodisc	Sends custom information to a device.
freeze	MCI_FREEZE	overlay	Disables video acquisition to the frame buffer.
put	MCI_PUT	digitalvideo, overlay	Defines the source, destination, and frame windows.
realize	MCI_REALIZE	digitalvideo	Tells the device to select and realize its palette into a device context of the displayed window.
setaudio	MCI_SETAUDIO	digitalvideo	Sets audio parameters for video.
setvideo	MCI_SETVIDEO	digitalvideo	Sets video parameters.
signal	MCI_SIGNAL	digitalvideo	Identifies a specified position with a signal.
spin	MCI_SPIN	videodisc	Starts the disc spinning or stops the disc from spinning.
step	MCI_STEP	digitalvideo, videodisc	Steps the play one or more frames forward or reverse.
unfreeze	MCI_UNFREEZE	overlay	Enables the frame buffer to acquire video data.
update	MCI_UPDATE	digitalvideo	Repaints the current frame into the device context.
where	MCI_WHERE	digitalvideo, overlay	Obtains the rectangle specifying the source, destination, or frame area.
window	MCI_WINDOW	digitalvideo, overlay	Controls the display window.


MCI Functions, Macros, and Messages

Most MCI applications use the mciSendString and mciSendCommand functions dozens of times. MCI provides some other useful functions that your application will use less frequently.

The device identifier required by most MCI commands is typically retrieved in a call to the open (MCI_OPEN) command. If you need a device identifier but do not want to open the device — for example, if you want to query the capabilities of the device before taking any other action — you can call the mciGetDeviceID function.

The mciGetCreatorTask function allows your application to use a device identifier to retrieve a handle to the task that created that identifier.

You can use the mciGetYieldProc and mciSetYieldProc functions to assign and retrieve the address of the callback function associated with the “wait” (MCI_WAIT) flag.

The mciGetErrorString function retrieves a string that describes an MCI error value. Each string that MCI returns, whether data or an error description, is a maximum of 128 characters. Dialog box fields that are smaller than 128 characters will truncate the longer strings returned by MCI. For more information about these strings, see Constants: MCIERR Return Values.

The MCI macros are tools you can use to create and disassemble values that specify time formats. These time formats are used in many MCI commands. The formats acted on by the macros are hours/minutes/seconds (HMS), minutes/seconds/frames (MSF), and tracks/minutes/seconds/frames (TMSF). The following table lists the macros and their descriptions.

Macro	Description
MCI_HMS_HOUR	Retrieves the hours component from an HMS value.
MCI_HMS_MINUTE	Retrieves the minutes component from an HMS value.
MCI_HMS_SECOND	Retrieves the seconds component from an HMS value.
MCI_MAKE_HMS	Creates an HMS value.
MCI_MAKE_MSF	Creates an MSF value.
MCI_MAKE_TMSF	Creates a TMSF value.
MCI_MSF_FRAME	Retrieves the frames component from an MSF value.
MCI_MSF_MINUTE	Retrieves the minutes component from an MSF value.
MCI_MSF_SECOND	Retrieves the seconds component from an MSF value.
MCI_TMSF_FRAME	Retrieves the frames component from a TMSF value.
MCI_TMSF_MINUTE	Retrieves the minutes component from a TMSF value.
MCI_TMSF_SECOND	Retrieves the seconds component from a TMSF value.
MCI_TMSF_TRACK	Retrieves the tracks component from a TMSF value.
MCI also provides two messages: MM_MCINOTIFY and MM_MCISIGNAL. The MM_MCINOTIFY message notifies an application of the outcome of an MCI command whenever that command specifies the “notify” (MCI_NOTIFY) flag. The MM_MCISIGNAL message is specific to digital-video devices; it notifies the application when a specified position is reached.


The Wait, Notify, and Test Flags

Most MCI commands include flags that modify the command. The “wait” (MCI_WAIT) and “notify” (MCI_NOTIFY) flags are common to every command. The “test” (MCI_TEST) flag is available to digital-video and VCR devices. This section describes the use of these flags.


The Wait Flag

MCI commands usually return to the user immediately, even if it takes several minutes to complete the action initiated by the command. You can use the “wait” (MCI_WAIT) flag to direct the device to wait until the requested action is completed before returning control to the application.

For example, the following play command will not return control to the application until the playback completes:

mciSendString("play mydevice from 0 to 100 wait",
    lpszReturnString, lstrlen(lpszReturnString), NULL);

Note  The user can cancel a wait operation by pressing a break key. By default, this key is CTRL+BREAK. Applications can redefine this key by using the break (MCI_BREAK) command. (MCI_BREAK uses the MCI_BREAK_PARMS structure.) When a wait operation is canceled, MCI attempts to return control to the application without interrupting the command associated with the “wait” flag.


The Notify Flag

The “notify” (MCI_NOTIFY) flag directs the device to post an MM_MCINOTIFY message when the device completes an action. Your application must have a window procedure to process the MM_MCINOTIFY message for notification to have any effect. An MM_MCINOTIFY message indicates that the processing of a command has completed, but it does not indicate whether the command was completed successfully, failed, or was superseded or aborted.

The application specifies the handle to the destination window for the message when it issues a command. In the command-string interface, this handle is the last parameter of the mciSendString function. In the command-message interface, the handle is specified in the low-order word of the dwCallBack member of the structure sent with the command message. (Every structure associated with a command message contains this member.)


The Test Flag

The “test” (MCI_TEST) flag queries the device to determine if it can execute the command. The device returns an error if it cannot execute the command. It returns no error if it can handle the command. When you specify this flag, MCI returns control to the application without executing the command.

This flag is supported by digital-video and VCR devices for all commands except open (MCI_OPEN) and close (MCI_CLOSE).


Command Shortcuts and Variations

You can use several shortcuts when working with MCI commands. These shortcuts enable you to use a single identifier to refer to all the devices your application has opened, or to open a device without explicitly issuing an open (MCI_OPEN) command.


Using All as a Device Identifier

You can specify “all” (MCI_ALL_DEVICE_ID) as a device identifier for any command that does not return information. When you specify “all”, MCI sends the command sequentially to all devices opened by the current application.

For example, the close “all” command closes all open devices and the play “all” command starts playing all devices opened by the application. Because MCI sequentially sends the commands to the MCI devices, there is an interval between when the first and last devices receive the command.

Using “all” is a convenient way to broadcast a command to all your devices, but you should not rely on it to synchronize devices; the timing between messages can vary.


Automatically Opening a Device

When you issue a command and specify a device that is not open, MCI tries to open the device before implementing the command. The following rules apply to automatically opening devices:

•	The automatic open feature works only with the command-string interface.

•	The automatic open feature fails for commands that are specific to custom device drivers.

•	Automatically opened devices do not respond to commands that use “all” as a device name.

•	The automatic open feature does not let your application specify the “type” flag. Without the device name, MCI determines the device name from the entries in the registry. To use a specific device, you can combine the device name with the filename by using the exclamation point, as described in the reference material for the open command.

If an application uses the automatic open feature to open a device, the application should check the return value of every subsequent open command to verify that the device is still open. MCI also automatically closes any device that it automatically opens. MCI typically closes a device in the following situations:

•	The command is completed.

•	You abort the command.

•	You request notification in a subsequent command.

•	MCI detects a failure.


MCI Devices

Every MCI multimedia device supports a core set of MCI commands in a way that makes sense for that device. For example, the play (MCI_PLAY) command causes the open device to play a file or track, no matter what kind of data the device works with. This section discusses MCI devices and how they respond to standard MCI commands.


Device Control

To control an MCI device, you open the device, send the necessary commands to it, and then close the device. The commands can be very similar, even for completely different MCI devices. For example, the following series of MCI commands plays the sixth track of an audio CD by using the command-string interface:

mciSendString("open cdaudio", lpszReturnString,
    lstrlen(lpszReturnString), NULL);
mciSendString("set cdaudio time format tmsf", lpszReturnString,
    lstrlen(lpszReturnString), NULL);
mciSendString("play cdaudio from 6 to 7", lpszReturnString,
    lstrlen(lpszReturnString), NULL);
mciSendString("close cdaudio", lpszReturnString,
    lstrlen(lpszReturnString), NULL);

The next example shows a similar series of MCI commands that plays the first 10,000 samples of a waveform-audio file:

mciSendString(
    "open c:\mmdata\purplefi.wav type waveaudio alias finch",
    lpszReturnString, lstrlen(lpszReturnString), NULL);
mciSendString("set finch time format samples", lpszReturnString,
    lstrlen(lpszReturnString), NULL);
mciSendString("play finch from 1 to 10000", lpszReturnString,
    lstrlen(lpszReturnString), NULL);
mciSendString("close finch", lpszReturnString,
    lstrlen(lpszReturnString), NULL);

These examples illustrate some interesting facts about MCI commands:

•	The same basic commands (open, set, play, and close) are used with CD audio and waveform-audio devices. The same MCI commands are used with all MCI devices.

•	The open command for the waveform-audio device includes a filename specification. The waveform-audio device is a compound device (one associated with a data file), while the CD audio device is a simple device (one without an associated data file).

•	The set command specifies time formats in each case, but the time-format flag for the CD audio device specifies tracks/minutes/seconds/frames (TMSF) format, while the time format used with the waveform-audio device specifies “samples”.

•	The variables used with the “from” and “to” flags are appropriate to the respective time format. For example, for the CD audio device, the variables specify a range of tracks, but for the waveform-audio device, the variables specify a range of samples.


Playback and Positioning

A number of MCI commands, such as play (MCI_PLAY), stop (MCI_STOP), pause (MCI_PAUSE), resume (MCI_RESUME), and seek (MCI_SEEK), affect the playback or positioning of a multimedia file. If an MCI device receives a playback command while another playback command is in progress, it accepts the command and either stops or supersedes the previous command.

Many MCI commands, such as set (MCI_SET), do not affect playback. A notification from one of these commands does not interfere with pending playback or position commands as long as the notifications are not performed from the same instance of the driver. For example, you can issue a set or status (MCI_STATUS) command while a device is performing a seek command without stopping or superseding the seek command.

However, there can be only one pending notification. For example, if an application requests a notification for play and follows that request with status “start position notify,” the play notification will return “superseded” and the notification for the status command will return when it is finished. In this case, however, the play command will still succeed, even though the application did not receive the notification.


Device Types

MCI recognizes a basic set of device types. A device type is a set of MCI drivers that share a common command set and are used to control similar multimedia devices or data files. Many MCI commands, such as open (MCI_OPEN), require you to specify a device type.

The following table lists the defined device types. The current implementation of MCI includes command sets for a subset of these devices.

Device type	Constant	Description
cdaudio	MCI_DEVTYPE_CD_AUDIO	CD audio player
dat	MCI_DEVTYPE_DAT	Digital-audio tape player
digitalvideo	MCI_DEVTYPE_DIGITAL_VIDEO	Digital video in a window (not GDI-based)
other	MCI_DEVTYPE_OTHER	Undefined MCI device
overlay	MCI_DEVTYPE_OVERLAY	Overlay device (analog video in a window)
scanner	MCI_DEVTYPE_SCANNER	Image scanner
sequencer	MCI_DEVTYPE_SEQUENCER	MIDI sequencer
vcr	MCI_DEVTYPE_VCR	Video-cassette recorder or player
videodisc	MCI_DEVTYPE_VIDEODISC	Videodisc player
waveaudio	MCI_DEVTYPE_WAVEFORM_AUDIO	Audio device that plays digitized waveform files
In this document, the names of device types are bold. Device-type names are used with the command-string interface. Device-type constants are used with the command-message interface.


Device Names

For each device type, there might be several MCI drivers that share the command set but operate on different data formats. To uniquely identify an MCI driver, MCI uses device names.

Device names are identified either in the [mci] section of the SYSTEM.INI file or in the appropriate part of the registry. This information identifies all MCI drivers to Windows. The entries in the [mci] section use the following form:

device_name = driver_filename.extension

The following example shows a typical [mci] section from SYSTEM.INI:

[mci]
cdaudio=mcicda.drv

sequencer=mciseq.drv

waveaudio=mciwave.drv

avivideo=mciavi.drv

If an MCI driver is installed using a device name that already exists in SYSTEM.INI or the registry, the system appends an integer to the device name of the new driver, creating a unique device name. In the preceding example, an additional driver installed using the “cdaudio” device name would be assigned the device name “cdaudio1”.


Driver Support for MCI Commands

MCI drivers provide the functionality for MCI commands. The system software performs some basic data-management tasks, but all the multimedia playback, presentation, and recording is handled by the individual MCI drivers.

Drivers vary in their support for MCI commands and command flags. Because multimedia devices can have widely different capabilities, MCI is designed to let individual drivers extend or reduce the command sets to match the capabilities of the device. For example, the record (MCI_RECORD) command is part of the command set for MIDI sequencers, but the MCISEQ driver included with Windows does not support this command. The reference topic for the record command explains that devices of the sequencer device type recognize the command; this does not mean that all devices of this type support the command. Applications should use the capability (MCI_GETDEVCAPS) command to determine the capabilities of a particular device.


Default Behavior of Drivers

In many situations, the MCI command specifications define the default values and behavior for drivers of a particular device type. Since multimedia devices can have a wide range of features (and limitations), there can be undefined areas of behavior. Also, drivers might handle exceptions differently, based on the capabilities of the device.

For example, consider the following commands sent to a waveform-audio driver:

mciSendString("open sound.wav alias sound", lpszReturnString,
    lstrlen(lpszReturnString), NULL);
mciSendString("play sound notify", lpszReturnString,
    lstrlen(lpszReturnString), NULL);
mciSendString("record sound from 0 notify", lpszReturnString,
    lstrlen(lpszReturnString), NULL);

The record command returns a “Parameter out of range” value and stops the playback started by the previous play command. One might expect the driver to validate the record command before stopping playback, but the driver stops the playback first.


Working with MCI Devices

This section describes how to perform the following tasks:

•	Opening a device

•	Retrieving information about a device

•	Obtaining MCI system information

•	Playing a device

•	Recording

•	Stopping, pausing, and resuming a device

•	Closing a device

In addition, this section provides you with shortcuts you can use with MCI commands.


Opening a Device

Before using a device, you must initialize it by using the open (MCI_OPEN) command. This command loads the driver into memory (if it isn’t already loaded) and retrieves the device identifier you will use to identify the device in subsequent MCI commands. You should check the return value of the mciSendString or mciSendCommand function before using a new device identifier to ensure that the identifier is valid. (You can also retrieve a device identifier by using the mciGetDeviceID function.)

Like all MCI command messages, MCI_OPEN has an associated structure. These structures are sometimes called parameter blocks. The default structure for MCI_OPEN is MCI_OPEN_PARMS. Certain devices (such as waveform and overlay) have extended structures (such as MCI_WAVE_OPEN_PARMS and MCI_OVLY_OPEN_PARMS) to accommodate additional optional parameters. Unless you need to use these additional parameters, you can use the MCI_OPEN_PARMS structure with any MCI device.

The number of devices you can have open is limited only by the amount of available memory.

Using an Alias

When you open a device, you can use the “alias” flag  to specify a device identifier for the device. This flag lets you assign a short device identifier for compound devices with lengthy filenames, and it lets you open multiple instances of the same file or device.

For example, the following command assigns the device identifier “birdcall” to the lengthy filename C:\NABIRDS\SOUNDS\MOCKMTNG.WAV:

mciSendString(
    "open c:\nabirds\sounds\mockmtng.wav type waveaudio alias birdcall",
    lpszReturnString, lstrlen(lpszReturnString), NULL);

In the command-message interface, you specify an alias by using the lpstrAlias member of the MCI_OPEN_PARMS structure.

Specifying a Device Type

When you open a device, you can use the “type” flag to refer to a device type, rather than to a specific device driver. The following example opens the waveform-audio file C:\WINDOWS\CHIMES.WAV (using the “type” flag to specify the waveaudio device type) and assigns the alias “chimes”:

mciSendString(
    "open c:\windows\chimes.wav type waveaudio alias chimes",
    lpszReturnString, lstrlen(lpszReturnString), NULL);

In the command-message interface, the functionality of the “type” flag is supplied by the lpstrDeviceType member of the MCI_OPEN_PARMS structure.

Simple and Compound Devices

MCI classifies device drivers as compound or simple. Drivers for compound devices require the name of a data file for playback; drivers for simple devices do not.

Simple devices include cdaudio and videodisc devices. There are two ways to open simple devices:

•	Specify a pointer to a null-terminated string containing the device name from the registry or the SYSTEM.INI file.

For example, you can open a videodisc device by using the following command:

mciSendString("open videodisc", lpszReturnString,
    lstrlen(lpszReturnString), NULL);

In this case, “videodisc” is the device name from the registry or the [mci] section of SYSTEM.INI.

•	Specify the actual name of the device driver. Opening a device using the device-driver filename, however, makes the application device-specific and can prevent the application from running if the system configuration changes. If you use a filename, you do not need to specify the complete path or the filename extension; MCI assumes drivers are located in a system directory and have the .DRV filename extension.

Compound devices include waveaudio and sequencer devices. The data for a compound device is sometimes called a device element. This document, however, generally refers to this data as a file, even though in some cases the data might not be stored as a file.

There are three ways to open a compound device:

•	Specify only the device name. This lets you open a compound device without associating a filename. Most compound devices process only the capability (MCI_GETDEVCAPS) and close (MCI_CLOSE) commands when they are opened this way.

•	Specify only the filename. The device name is determined from the associations in the registry.

•	Specify the filename and the device name. MCI ignores the entries in the registry and opens the specified device name.

To associate a data file with a particular device, you can specify the filename and device name. For example, the following command opens the waveaudio device with the filename MYVOICE.SND:

mciSendString("open myvoice.snd type waveaudio", lpszReturnString,
    lstrlen(lpszReturnString), NULL);

In the command-string interface, you can also abbreviate the device name specification by using the alternative exclamation-point format, as documented with the open command.

Opening a Device Using the Filename Extension

If the open (MCI_OPEN) command specifies only the filename, MCI uses the filename extension to select the appropriate device from the list in the registry or the [mci extensions] section of the SYSTEM.INI file. The entries in the [mci extensions] section use the following form:

filename_extension=device_name

MCI implicitly uses device_name if the extension is found and if a device name has not been specified in the open command.

The following example shows a typical [mci extensions] section:

[mci extensions]
wav=waveaudio
mid=sequencer
rmi=sequencer

Using these definitions, MCI opens the waveaudio device if the following command is issued:

mciSendString("open train.wav", lpszReturnString,
    lstrlen(lpszReturnString), NULL);

New Data Files

To create a new data file, simply specify a blank filename. MCI does not save a new file until you save it by using the save (MCI_SAVE) command. When creating a new file, you must include a device alias with the open (MCI_OPEN) command.

The following example opens a new waveaudio file, starts and stops recording, then saves and closes the file:

mciSendString("open new type waveaudio alias capture", lpszReturnString,
    lstrlen(lpszReturnString), NULL);
mciSendString("record capture", lpszReturnString,
    lstrlen(lpszReturnString), NULL);
mciSendString("stop capture", lpszReturnString,
    lstrlen(lpszReturnString), NULL);
mciSendString("save capture orca.wav", lpszReturnString,
    lstrlen(lpszReturnString), NULL);
mciSendString("close capture", lpszReturnString,
    lstrlen(lpszReturnString), NULL);

Shareable Devices

The “shareable” (MCI_OPEN_SHAREABLE) flag of the open (MCI_OPEN) command lets multiple applications access the same device (or file) and device instance simultaneously. If your application opens a device or file as shareable, other applications can also access it by opening it as shareable. The shared device or file gives each application the ability to change the parameters governing its operating state. Each time a device or file is opened as shareable, MCI returns a unique device identifier, even though the identifiers refer to the same instance.

If your application opens a device or file without specifying that it is shareable, no other application can access it until your application closes it. Also, if a device supports only one open instance, the open command will fail if you specify the shareable flag.

If your application opens a device and specifies that it is shareable, your application should not make any assumptions about the state of this device. Your application might need to compensate for changes made by other applications accessing the device.

Most compound files are not shareable; however, you can open multiple files, or you can open a single file multiple times. If you open a single file multiple times, MCI creates an independent instance for each, with each instance having a unique operating status.

If you open multiple instances of a file, you must assign a unique device identifier to each. You can use an alias, as described in the following section, to assign a unique name for each file.


Retrieving Information About a Device

Every device responds to the capability (MCI_GETDEVCAPS), status (MCI_STATUS), and info (MCI_INFO) commands. These commands obtain information about the device. For example, the following command returns “true” if a cdaudio device can eject the disc:

mciSendString(
    "capability cdaudio can eject",
    lpszReturnString, lstrlen(lpszReturnString), NULL);

The flags listed for the required and basic commands provide a minimum amount of information about a device. Many devices supplement the required and basic commands with extended flags to provide additional information about the device.


Obtaining MCI System Information

The sysinfo (MCI_SYSINFO) command obtains system information about MCI devices. MCI handles this command without relaying it to any MCI device. For the command-message interface, MCI returns the system information in the MCI_SYSINFO_PARMS structure.

You can use the sysinfo (MCI_SYSINFO) command to retrieve information such as the number of MCI devices on a system, the number of MCI devices of a particular type, the number of open MCI devices, and the names of the devices. This command is often called more than once to retrieve a particular piece of information. For example, you might retrieve the number of devices of a particular type in the first call and then enumerate the names of the devices in the next.


Playing a Device

The play (MCI_PLAY) command starts playing a device. Without any flags, this command starts playing from the current position and plays until the command is interrupted or until the end of the media or file is reached. After playback, the current position is at the end of the media. You can also use the seek (MCI_SEEK) command to change the current position.

Most devices that support the play command also support the “from” (MCI_FROM) and “to” (MCI_TO) flags. These flags indicate the position at which the device should start and stop playing. For example, the following command plays a CD audio disc from the beginning of the first track:

mciSendString("play cdaudio from 0", lpszReturnString,
    lstrlen(lpszReturnString), NULL);

Some device types extend this command to exploit the capabilities of a particular device. For example, the play command for the videodisc device type includes the “fast” (MCI_VD_PLAY_FAST) , “slow” (MCI_VD_PLAY_SLOW), and “scan” (MCI_VD_PLAY_SCAN) flags.

Note  The units assigned to the position value depend on the time format used by the device. Each device has a default time format, but you should specify the time format by using the set (MCI_SET) command before issuing any commands that use position values.

Playing an AVI File

Video files in Windows are made up of at least two interleaved data streams: a video (pictorial) stream and an audio stream. You can easily play these audio-video interleaved (AVI) files by using MCI commands. The following sections discuss playing AVI files.

Setting Up an MCIAVI Playback Window

Your application can specify the following options to define the playback window for playing an AVI file:

•	Use the MCIAVI driver’s default pop-up window.

•	Specify a parent window and window style that the MCIAVI driver can use to create the playback window.

•	Specify a playback window for the MCIAVI driver to use for playback.

•	Play the AVI file on a full-screen display.

If your application does not specify any window options, the MCIAVI driver creates a default window for playing the sequence. The driver creates this playback window for the open (MCI_OPEN) command, but it does not display the window until your application sends a command to either display the window or play the file. This default playback window is a pop-up window with a sizing border, title bar, a thick frame, a window menu, and a Minimize button.

Your application can also specify a parent window handle and a window style when it issues the open command. In this case, the MCIAVI driver creates a window based on these specifications instead of the default pop-up window. Your application can specify any window style available for the CreateWindow function. Styles that require a parent window, such as WS_CHILD, should include a parent window handle.

Your application can also create its own window and supply the handle to the MCIAVI driver by using the window (MCI_WINDOW) command. The MCIAVI driver uses this window instead of creating one of its own.

When the MCIAVI driver creates the playback window or obtains a window handle from your application, it does not display the window until your application either plays the sequence or sends a command to display the window. Your application can use the window command to display the window without playing the sequence. For example, the following command displays the window using the command-string interface:

mciSendString("window movie state show", lpszReturnString,
    lstrlen(lpszReturnString), NULL);

In this example, “movie” is an alias for the digital-video device.

Your application can also play an AVI file full-screen. To play full-screen, modify the play (MCI_PLAY) command with the “fullscreen” (MCI_MCIAVI_PLAY_FULLSCREEN) flag. When your application uses this flag, the MCIAVI driver uses a 320- by 240-pixel full-screen format for playing the sequence. For example, the following command plays the opened file full-screen (using “movie” as an alias):

mciSendString("play movie fullscreen", lpszReturnString,
    lstrlen(lpszReturnString), NULL);

Changing the Playback State for an AVI file

Your application can use the seek (MCI_SEEK) command to move the current position to the beginning, the end, or an arbitrary position in an AVI file. There are two seek modes for the MCIAVI driver: exact and inexact. Your application can change the seek mode by using the set (MCI_SET) command. When you use set “seek exactly on”, the MCIAVI driver seeks exactly to the frame your application specifies. This might cause a delay if the file is temporally compressed and your application does not specify a key frame. When you use set “seek exactly off”, the MCIAVI driver seeks to the nearest key frame in a temporally compressed file.

Some MCI commands let your application alter the playback of an AVI file in other ways. For example, an AVI file, by default, plays at its normal speed, but your application can increase or decrease this speed by using the “speed” flag with the set command. For AVI files, a speed value of 1000 is typical. Thus, to play a movie at half its typical speed, your application can use the command set “movie speed 500”; alternatively, it can use set “movie speed 2000” to play the sequence at twice its normal speed.

The setaudio (MCI_SETAUDIO) command lets your application control the audio portion of an AVI file. Your application can mute audio during playback or, in the case of multiple audio stream files, select the audio stream that is played.

The MCIAVI driver has a dialog box to control some of its playback options. Some of the options available to the user include selecting window-oriented or full-screen playback, selecting the seek mode, and zooming the image. Your application can have MCIAVI display this dialog box by using the configure (MCI_CONFIGURE) command.

Stream Handlers

The data in an AVI file is treated as a series of streams. An AVI file typically contains an audio and video stream, and there might also be a custom stream that contains text or some other custom data. The MCIAVI driver can use different handlers for these data streams. For more information about custom AVI files, see Custom File and Stream Handlers.


Recording

The general MCI specification supports recording with digital-video, MIDI sequencer, video-cassette recorder (VCR), and waveform-audio devices; however, only waveform-audio and VCR devices currently implement recording capabilities. You can insert or overwrite recorded information into an existing file or record into a new file. To record to an existing file, open a waveform-audio device and file as you would normally. To record into a new file, when you open the device specify “new” as the device name if you are using the command-string interface. If you are using the command-message interface, specify a zero-length filename.

When MCI creates a new file for recording, the data format is set to a default format specified by the device driver. To use a format other than the default format, you can use the set (MCI_SET) command.

To begin recording, use the record command (or MCI_RECORD and the MCI_RECORD_PARMS structure).

If you record in insert mode to an existing file, you can use the “from” (MCI_FROM) and “to” (MCI_TO) flags of the record command to specify starting and ending positions for recording. For example, if you record to a file that is 20 seconds long, and you begin recording at 5 seconds and end recording at 10 seconds, the resulting file will be 25 seconds long. The file will have a 5-second segment inserted 5 seconds into the original recording.

If you record with overwrite mode to an existing file, you can use the “from” and “to” flags to specify starting and ending locations of the section that is overwritten. For example, if you record to a file that is 20 seconds long, and you begin recording at 5 seconds and end recording at 10 seconds, you still have a recording 20 seconds long, but the section beginning at 5 seconds and ending at 10 seconds will have been replaced.

If you do not specify an ending location, recording continues until you send a stop (MCI_STOP) command, or until the driver runs out of free disk space. If you record to a new file, you can omit the “from” flag or set it to zero to start recording at the beginning of a new file. You can specify an ending location to terminate recording when recording to a new file.

The record command is sometimes accurate to within only 1 second of the starting location, such as with VCR devices. To record more accurately, you should use the cue (MCI_CUE) command. This command is recognized by digital-video, VCR, and waveform-audio devices. For more information about recording with VCR devices, see VCR Services.

Saving a Recorded File

When recording is complete, use the save command (or MCI_SAVE and the MCI_SAVE_PARMS structure) to save the recording before closing the device.

Note  If you close the device without saving, the recorded data is lost.

Checking Input Levels (PCM Only)

To get the level of the input signal before recording on a PCM (Pulse Code Modulation) waveform-audio input device, use the status (MCI_STATUS) command. Specify the “level” flag (or the MCI_STATUS_ITEM flag and set the dwItem member of the MCI_STATUS_PARMS structure to MCI_WAVE_STATUS_LEVEL). The average input signal level is returned. The left-channel value is in the high-order word and the right- or mono-channel value is in the low-order word.

The input level is represented as an unsigned value. For 8-bit samples, this value is in the range 0 through 127 (0x7F). For 16-bit samples, it is in the range 0 through 32,767 (0x7FFF).


Stopping, Pausing, and Resuming a Device

The stop (MCI_STOP) command suspends the playing or recording of a device. Many devices also support the pause (MCI_PAUSE) command. The difference between stop and pause depends on the device. Usually pause suspends operation but leaves the device ready to resume playing or recording immediately.

Using the play (MCI_PLAY) or record (MCI_RECORD) command to restart a device resets the locations specified with the “to” (MCI_TO) and “from” (MCI_FROM) flags before the device was paused or stopped. Without the “from” flag, these commands reset the starting location to the current position. Without the “to” flag, they reset the ending location to the end of the media. To continue playing or recording without resetting a previously specified stop position, use the play or record command’s “to” flag to specify an ending position.

Some devices support the resume (MCI_RESUME) command to restart a paused device. This command does not change the “to” and “from” locations specified with the play or record command that preceded the pause command.


Closing a Device

The close (MCI_CLOSE) command releases access to a device or file. MCI frees a device when all tasks using a device have closed it. To help MCI manage the devices, your application must close each device or file when it is finished using it.

When you close an external MCI device that uses its own media instead of files (such as CD audio), the driver leaves the device in its current mode of operation. Thus, if you close a CD audio device that is playing, even though the device driver is released from memory, the CD audio device will continue to play until it reaches the end of its content.

Note  Closing an application with open MCI devices can prevent other applications from using those devices until Windows is restarted.


MCI Implementations for Specific Devices

The following sections discuss using MCI commands with specific MCI devices:

•	MCIAVI

•	VCR services


MCIAVI

An AVI file can contain more than two streams — for example, a video sequence, an English soundtrack, and a French soundtrack. Your application can use a stream independently of the other streams in the file.

The digitalvideo device type controls video files. For a list of the MCI commands recognized by digital-video devices, see Digital-Video Command Set.

The MCIAVI driver plays video sequences and other data streams under the control of MCI commands. Data streams can contain images, audio, and palettes. The image data can consist of images with either color palettes or true-color information.

Audio is synchronized with the video within one-thirtieth of a second. If audio hardware is not available, however, the driver plays only the video stream. The MCIAVI driver can drop video frames, if necessary, to play a stream without audio interruption.

Your application can use the MCIWnd window class services instead of the MCI command interface to control any MCI driver. This window class handles many of the details of managing the window supporting the MCI device and simplifies the programming required to send the MCI commands. Your application can use the MCIWnd library services directly to control the MCI device, or it can have MCIWnd display a toolbar, scroll bar, and menus that let the user control the device. For more information about the MCIWnd window class, see MCIWnd Window Class.


VCR Services

Windows provides VCR services through a device driver that is based on the MCI command set for VCRs. This section describes the MCI Video System Control Architecture (VISCA) driver and explains how to use it to control a VCR.

The vcr device type controls VCRs. For a list of the MCI commands recognized by VCR devices, see VCR Command Set.

The MCI VISCA Driver

The MCI VISCA driver controls Sony VISCA-compatible VCRs, such as the CVD-1000 VDeck. The VISCA driver controls the tape transport, channel tuners, and VCR input and output channels.

Searching and Positioning with a VCR

The VISCA driver uses two methods to track videotape movement within the VCR tape transport: timecode information and tape counters. Timecode information is timing information that has been recorded on the videotape. Most VCRs allow timecodes to be recorded without destroying audio and video tracks. Tape counters estimate the amount of videotape that travels past the videotape head to obtain a position.

Both timecode information and tape counters increase as the videotape moves from beginning to end. Because of its accuracy, using timecode information to position a videotape is almost always preferable to using tape counters.

The MCI command flags for specifying positioning information are expressed as time dependencies: “time format”, “duration”, “from”, “to”, and “seek”. (Also, the status “position” command returns its time value in the current time format.)

The VISCA driver uses the set “time mode” command to select the type of positioning to use with a videotape. When the time mode is set to “timecode”, the status “position” and set “time format” commands use the timecode on the videotape. When the time mode is set to “counter”, the status “position” and set “time format” commands use counters.

An application can set the time mode to “detect” if it doesn’t matter that there might be two sources of position information. When in detect mode, the VISCA driver uses timecode information for positioning when any of the following conditions occur:

•	The timecode information is present when the driver is opened.

•	You change a videotape with the set “door open” command and timecode information is present on the videotape.

•	The set “time mode” command is reissued.

If timecode information cannot be found, the driver uses the tape counters.

To determine the current positioning method, issue the status “time type” command, which returns either “timecode” or “counter”. You can also identify the current positioning mode by using the status “time mode” command, which returns “timecode”, “counter”, or “detect”.

The status “counter” command retrieves the current tape counter value, regardless of the current positioning method; however, you can use this counter reading only with the set “counter” command.

The VISCA driver can retrieve the native timecode format recorded on a videotape by using the status “timecode type” and status “frame rate” commands together. For example, if timecode type is “smpte” and frame rate is 25, the native timecode format recorded on the videotape is SMPTE 25.

The VISCA driver can also retrieve the counter resolution by using the status “counter resolution” command, which returns “seconds” or “frames”. The counter format might still be set to SMPTE 30, but the return value returns only a frame of 0. If the current time type is counter, then this resolution applies also to the value returned by status “position”.

Capturing Frames

Frame-capturing commands provide still images for a frame-capture device. A frame-capture device is a separate piece of hardware capable of reading and storing the video image. The VISCA driver supports the freeze (MCI_FREEZE) command to stabilize a still image for capturing. Also, the unfreeze (MCI_UNFREEZE) command can be used to restart the tape transport following a freeze command.

The freeze command provides a high-quality, stabilized, time-base − corrected image for a frame-capture device. This command exists because a device might not always deliver its maximum-quality output image during playback or while paused; such a video image is not suitable for capturing.

The unfreeze command unlocks the tape transport and resumes the transport mode in effect before the freeze command.

When your application needs to record a video image on the VCR, use the freeze “input” command or the cue (MCI_CUE) command to record the image.

Selecting Inputs

The VISCA driver supports three input types: video, audio, and timecode. The video inputs include two standard channels (lines 1 and 2), an SVideo channel, an auxiliary channel, and a channel from an internal tuner. The audio inputs include two standard channels (lines 1 and 2) and a channel from an internal tuner. The timecode input is internal to the VCR.

The normal outputs carry the currently selected inputs when the VCR is recording or when the tape transport is stopped, and they carry the contents of the videotape when the tape transport is playing or paused. The monitored outputs carry the same information as the normal outputs plus current timecode and channel information.

Assuming the appropriate external inputs are connected to your VCR and you have decided what you want to record, you can select the inputs to be recorded. For example, to record or view from the “svideo” video and the “line 1” audio inputs, you would use the setvideo (MCI_SETVIDEO) and setaudio (MCI_SETAUDIO) commands to select these input sources. You can verify these selections by using the status (MCI_STATUS) command.

By default, the monitor shows exactly what appears as the output. Sometimes, however, you might want to view one source while recording from another. This is a common practice using the tuner. For example, you might want to watch channel 4 while you record channel 7. In this case, you have two logical tuner inputs. You could set up the VCR by using the following commands:

To review one source while recording from another

1.	Use the settuner (MCI_SETTUNER) command to select the channels to watch and record.

2.	Use the setvideo command to select the video-recording source.

3.	Use the setaudio command to select the audio-recording source.

4.	Use the setvideo command to route the channel 4 video input to the monitored output to display it on-screen.

5.	Use the setaudio command to route the channel 4 audio input to the monitored output to play the audio.

6.	Verify your selections by using the status command.

The VISCA driver also supports a special input type for audio and video called mute. Mute allows the selection of “no input,” which is useful when recording a blank signal.

Selecting Recording Tracks

Three types of recording tracks exist on a videotape: video, audio, and timecode. You have only one video or timecode track, but you can use more than one audio track. When you do so, make track 1 the main audio track.

The VISCA driver supports two operating modes: assemble and insert. In assemble mode, all tracks are selected to be recorded. In insert mode, tracks can be independently selected for recording. Most VCRs are in assemble mode by default. Use the set (MCI_SET) command to change these modes.

Recording and Editing

The record (MCI_RECORD) command provides simple recording and is accurate to approximately 1 second of the starting position. To record more accurately, or if you expect to edit the video content while simultaneously operating multiple decks, you should use the cue (MCI_CUE) command.

The cue command prepares the device for recording or playing. Use the cue “input” command to prepare the device for recording. The cue command is required because an application must know when the device is ready to perform the command (and because it can take several minutes to prepare for a play (MCI_PLAY) or record command).

The VCR prepares itself for recording or playing by seeking to the in-point, which is the current position or the position specified by using the cue “from” command. If the “preroll” flag is specified with the cue command, however, the VCR positions itself the preroll distance from the in-point. The “preroll” flag also indicates that the VCR uses any applicable editing mode, so it’s important that you use “preroll”, especially when you want the most accurate recording. (Use the capability (MCI_GETDEVCAPS) command with the “can preroll” flag to check whether the preroll mode is supported.)

Note  When you record using “from” and “to” positions, the “from” position is included in the edit, and the “to” position is not.

For more information about recording, see Recording.

Using the Clock While Editing

When editing, you might want to record segments from one VCR to another. You can begin recording at a specific time and position on one VCR while another begins playing at the same time and position by specifying an action (play or record), a position, and a time for each VCR.

Both VCRs must use the same clock for this type of editing; the clock helps synchronize both devices. You can determine if two VCRs share the same clock by using the status (MCI_STATUS) command with the “clock id” flag to query each VCR. If the identification numbers returned by the status command are the same, the devices use the same clock. As a shared resource, the clock can be connected to multiple VCRs. The VISCA driver supports only one shared clock.

You can also determine clock resolution by using the status “clock increment rate” command. This command returns the number of increments the clock supports per second. For example, if the clock is updated every millisecond, the command returns 1000 as the clock increment rate. The advantage of using the increment rate is that the rate is expressed as an integer; otherwise, the increment would be a (single- or double-precision) floating-point value. As an integer, manipulating the increment rate is a simple operation and is not susceptible to rounding errors. You can reset the clock by using the set (MCI_SET) command with the “clock 0” (zero) flag.

When issuing a play (MCI_PLAY), record (MCI_RECORD), or seek (MCI_SEEK) command, you can specify when the command is to be executed. The characteristics of the VCRs being used determine when to start each VCR. The timing must account for the amount of preroll each device requires and the amount of time needed to complete the MCI commands used to set up the edit session. To do this, retrieve the clock time and add a waiting interval of 5 to 10 seconds. (The waiting interval must be long enough to let the preroll and any outstanding MCI commands finish executing.)

To ensure that the waiting period is long enough, place the record command last in your application and check the time immediately before it. If the interval is too short, restart the play command. Alternatively, you could check the time immediately after the last command of the script to verify that there is enough time to send and complete all the commands.


Device-Specific Command Sets

The following sections list the commands supported by each device type:

•	CD audio command set

•	Digital-video command set

•	MIDI Sequencer command Set

•	VCR command set

•	Videodisc command set

•	Video-overlay command set

•	Waveform-audio command set


CD Audio Command Set

CD audio devices support the following set of commands:

String form	Message form
break	MCI_BREAK
capability	MCI_GETDEVCAPS
close	MCI_CLOSE
info	MCI_INFO
open	MCI_OPEN
pause	MCI_PAUSE
play	MCI_PLAY
resume	MCI_RESUME
seek	MCI_SEEK
set	MCI_SET
status	MCI_STATUS
stop	MCI_STOP
sysinfo	MCI_SYSINFO


Digital-Video Command Set

Digital-video devices (for example, the MCIAVI driver) support the following set of commands:

String form	Message form
break	MCI_BREAK
capability	MCI_GETDEVCAPS
capture	MCI_CAPTURE
close	MCI_CLOSE
configure	MCI_CONFIGURE
copy	MCI_COPY
cue	MCI_CUE
cut	MCI_CUT
delete	MCI_DELETE
freeze	MCI_FREEZE
info	MCI_INFO
list	MCI_LIST
load	MCI_LOAD
monitor	MCI_MONITOR
open	MCI_OPEN
paste	MCI_PASTE
pause	MCI_PAUSE
play	MCI_PLAY
put	MCI_PUT
quality	MCI_QUALITY
realize	MCI_REALIZE
record	MCI_RECORD
reserve	MCI_RESERVE
restore	MCI_RESTORE
resume	MCI_RESUME
save	MCI_SAVE
seek	MCI_SEEK
set	MCI_SET
setaudio	MCI_SETAUDIO
setvideo	MCI_SETVIDEO
signal	MCI_SIGNAL
status	MCI_STATUS
step	MCI_STEP
stop	MCI_STOP
sysinfo	MCI_SYSINFO
undo	MCI_UNDO
unfreeze	MCI_UNFREEZE
update	MCI_UPDATE
where	MCI_WHERE
window	MCI_WINDOW


MIDI Sequencer Command Set

The MIDI sequencer supports the following set of commands:

String form	Message form
break	MCI_BREAK
capability	MCI_GETDEVCAPS
close	MCI_CLOSE
info	MCI_INFO
open	MCI_OPEN
pause	MCI_PAUSE
play	MCI_PLAY
record	MCI_RECORD
resume	MCI_RESUME
save	MCI_SAVE
seek	MCI_SEEK
set	MCI_SET
status	MCI_STATUS
stop	MCI_STOP
sysinfo	MCI_SYSINFO


VCR Command Set

VCRs support the following set of commands:

String form	Message form
break	MCI_BREAK
capability	MCI_GETDEVCAPS
cue	MCI_CUE
freeze	MCI_FREEZE
index	MCI_INDEX
info	MCI_INFO
list	MCI_LIST
mark	MCI_MARK
pause	MCI_PAUSE
play	MCI_PLAY
record	MCI_RECORD
resume	MCI_RESUME
seek	MCI_SEEK
set	MCI_SET
setaudio	MCI_SETAUDIO
settimecode	MCI_SETTIMECODE
settuner	MCI_SETTUNER
setvideo	MCI_SETVIDEO
status	MCI_STATUS
step	MCI_STEP
stop	MCI_STOP
sysinfo	MCI_SYSINFO
unfreeze	MCI_UNFREEZE


Videodisc Command Set

Videodisc devices support the following set of commands:

String form	Message form
break	MCI_BREAK
capability	MCI_GETDEVCAPS
close	MCI_CLOSE
escape	MCI_ESCAPE
info	MCI_INFO
open	MCI_OPEN
pause	MCI_PAUSE
play	MCI_PLAY
resume	MCI_RESUME
seek	MCI_SEEK
set	MCI_SET
spin	MCI_SPIN
status	MCI_STATUS
step	MCI_STEP
stop	MCI_STOP
sysinfo	MCI_SYSINFO


Video-Overlay Command Set

Video-overlay devices support the following set of commands:

String form	Message form
break	MCI_BREAK
capability	MCI_GETDEVCAPS
close	MCI_CLOSE
freeze	MCI_FREEZE
info	MCI_INFO
load	MCI_LOAD
open	MCI_OPEN
put	MCI_PUT
save	MCI_SAVE
set	MCI_SET
status	MCI_STATUS
sysinfo	MCI_SYSINFO
unfreeze	MCI_UNFREEZE
where	MCI_WHERE
window	MCI_WINDOW


Waveform-Audio Command Set

Waveform-audio devices support the following set of commands:

String form	Message form
break	MCI_BREAK
capability	MCI_GETDEVCAPS
close	MCI_CLOSE
cue	MCI_CUE
delete	MCI_DELETE
info	MCI_INFO
open	MCI_OPEN
pause	MCI_PAUSE
play	MCI_PLAY
record	MCI_RECORD
resume	MCI_RESUME
save	MCI_SAVE
seek	MCI_SEEK
set	MCI_SET
status	MCI_STATUS
stop	MCI_STOP
sysinfo	MCI_SYSINFO


Using MCI Command Strings

This section contains examples demonstrating how to use the MCI command-string interface to perform the following tasks:

•	Sending a command

•	Opening multiple AVI files

•	Changing the playback state

•	Converting strings


Sending a Command

The following example function sends the play command with the “from” and “to” flags.

DWORD PlayFromTo(LPSTR lpstrAlias, DWORD dwFrom, DWORD dwTo)

{

    char    achCommandBuff[128];

    wsprintf(achCommandBuff, "play %s from %u to %u",

        lpstrAlias, dwFrom, dwTo);

    return mciSendString(achCommandBuff, NULL, 0, NULL);

}


Opening Multiple AVI Files

If your application opens multiple files, it should include routines such as the following simple functions. The application would use the “initAVI” function during its initialization and the “termAVI” function during its termination.

// Initialize the MCIAVI driver. This returns TRUE if OK,

// FALSE on error.

BOOL initAVI(VOID)

{

    // Perform additional initialization before loading first file.

    return mciSendString("open digitalvideo", NULL, 0, NULL) == 0;

}

// Close the MCIAVI driver.

void termAVI(VOID)

{

    mciSendString("close digitalvideo", NULL, 0, NULL);

}


Changing the Playback State

The following examples show how to use the pause, resume, stop, and seek commands.

// Assume the file was opened with the alias 'movie'.

// Pause play.

mciSendString("pause movie", NULL, 0, NULL);

// Resume play.

mciSendString("resume movie", NULL, 0, NULL);

// Stop play.

mciSendString("stop movie", NULL, 0, NULL);

// Seek to the beginning.

mciSendString("seek movie to start", NULL, 0, NULL);

The following example shows how to change the seek mode:

// Set seek mode with the string interface.

// Assume the file was opened with the alias 'movie'.

void SetSeekMode(BOOL fExact)

{

    if (fExact)

        mciSendString("set movie seek exactly on", NULL, 0, NULL);

    else

        mciSendString("set movie seek exactly off", NULL, 0, NULL);

}


Converting Strings

When you use the string interface, all values passed with the command and all return values are text strings, so your application needs conversion routines to translate from variables to strings or back again. The following example retrieves the source rectangle and converts the returned string into rectangle coordinates.

void GetSourceRect(LPSTR lpstrAlias, LPRECT lprc)

{

    char achRetBuff[128];

    char achCommandBuff[128];

    // Build the command string.

    wsprintf(achCommandBuff, "where %s source", lpstrAlias);

    SetRectEmpty(lprc);    // clears the RECT

    // Send the command.

    if (mciSendString(achCommandBuff, achRetBuff,

        sizeof(achRetBuff), NULL) == 0){

        // The rectangle is returned as "x y dx dy".

        // Both x and y are 0 because this is the source

        // rectangle. Translate the string into the RECT

        // structure.

        char *p;

        p = achRetBuff;           // point to the return string

        while (*p != ' ') p++;    // go past the x (0)

        while (*p == ' ') p++;    // go past spaces

        while (*p != ' ') p++;    // go past the y (0)

        while (*p == ' ') p++;    // go past spaces

        // Retrieve the width.

        for ( ; *p != ' '; p++)

            lprc->right = (10 * lprc->right) + (*p - '0');

        while (*p == ' ') p++;    // go past spaces

        // Retrieve the height.

        for ( ; *p != ' '; p++)

            lprc->bottom = (10 * lprc->bottom) + (*p - '0');

    }

}

Note  RECT structures are handled differently in MCI than in other parts of Windows; in MCI, the right member contains the width of the rectangle and the bottom member contains its height. In the string interface, a rectangle is specified as X1, Y1, X2, and Y2. The coordinates X1 and Y1 specify the upper-left corner of the rectangle, and the coordinates X2 and Y2 specify the width and height.


Using MCI Command Messages

This section contains examples demonstrating how to perform the following tasks:

•	Closing all MCI devices used by an application

•	Opening a simple device by using the device name

•	Opening a simple device by using the device-type constant

•	Opening a compound device by using the filename

•	Verifying the output device

•	Handling MCI errors

•	Playing a waveform-audio file

•	Playing a MIDI file

•	Playing a compact disc track

•	Playing a movie

•	Using the MCI_NOTIFY flag

•	Retrieving information about a movie

•	Retrieving compact disc track-specific information

•	Recording with a waveform-audio device


Closing All MCI Devices Used by an Application

The following example closes all of the MCI devices that are opened by an application.

UINT wDeviceID;

DWORD dwReturn;

// Closes all MCI devices opened by this application.

// Waits until devices are closed before returning.

if(dwReturn = mciSendCommand(MCI_ALL_DEVICE_ID, MCI_CLOSE, MCI_WAIT,

    NULL))

    // Error, unable to close all devices.


Opening a Simple Device by Using the Device Name

The following example opens a CD audio device by specifying the device name.

UINT wDeviceID;

DWORD dwReturn;

MCI_OPEN_PARMS mciOpenParms;

// Opens a CD audio device by specifying the device name.

mciOpenParms.lpstrDeviceType = "cdaudio";

if (dwReturn = mciSendCommand(NULL, MCI_OPEN, MCI_OPEN_TYPE,

    (DWORD)(LPVOID) &mciOpenParms))

    // Error, unable to open device.

// The device opened successfully; get the device ID.

wDeviceID = mciOpenParms.wDeviceID;


Opening a Simple Device by Using the Device-Type Constant

The following example opens a CD audio device by specifying a device-type constant.

UINT wDeviceID;

DWORD dwReturn;

MCI_OPEN_PARMS mciOpenParms;

// Opens a CD audio device by specifying a device-type constant.

mciOpenParms.lpstrDeviceType = (LPCSTR) MCI_DEVTYPE_CD_AUDIO;

if (dwReturn = mciSendCommand(NULL, MCI_OPEN,

    MCI_OPEN_TYPE | MCI_OPEN_TYPE_ID, (DWORD)(LPVOID) &mciOpenParms))

    // Error, unable to open device.

// The device opened successfully; get the device ID.

wDeviceID = mciOpenParms.wDeviceID;


Opening a Compound Device by Using the Filename

The following example opens the waveform-audio device by specifying a waveform-audio file named “TIMPANI.WAV”.

UINT wDeviceID;

DWORD dwReturn;

MCI_OPEN_PARMS mciOpenParms;

// Opens a waveform-audio device by specifying the device and filename.

mciOpenParms.lpstrDeviceType = "waveaudio";

mciOpenParms.lpstrElementName = "timpani.wav";

if (dwReturn = mciSendCommand(NULL, MCI_OPEN,

    MCI_OPEN_TYPE | MCI_OPEN_ELEMENT, (DWORD)(LPVOID) &mciOpenParms))

    // Error, unable to open device.

// The device opened successfully; get the device ID.

wDeviceID = mciOpenParms.wDeviceID;


Verifying the Output Device

After opening the sequencer, you should check whether the MIDI mapper was available and selected as the output device. The following example uses the MCI_STATUS command to verify that the MIDI mapper is the output device for the MCI sequencer.

UINT wDeviceID;      // valid MCI sequencer ID

DWORD dwReturn;

MCI_STATUS_PARMS mciStatusParms;

// Make sure the opened device is the MIDI mapper.

mciStatusParms.dwItem = MCI_SEQ_STATUS_PORT;

if (dwReturn = mciSendCommand(wDeviceID, MCI_STATUS, MCI_STATUS_ITEM,

    (DWORD)(LPVOID) &mciStatusParms))

{

    // Error sending MCI_STATUS command.

    return;

}

if (LOWORD(mciStatusParms.dwReturn) == MIDI_MAPPER)

    // The MIDI mapper is the output device.

Else

    // The MIDI mapper is not the output device.


Handling MCI Errors

You should always check the return value of the mciSendCommand function. If it indicates an error, you can use mciGetErrorString to get a textual description of the error.

The following example passes the MCI error code specified by dwError to mciGetErrorString, and then displays the resulting textual error description using the MessageBox function.

// Uses mciGetErrorString to get a textual description of an MCI error.

// Displays the error description using MessageBox.

void showError(DWORD dwError)

{

    char szErrorBuf[MAXERRORLENGTH];

    MessageBeep(MB_ICONEXCLAMATION);

    if(mciGetErrorString(dwError, (LPSTR) szErrorBuf, MAXERRORLENGTH))

        MessageBox(hMainWnd, szErrorBuf, "MCI Error",

        MB_ICONEXCLAMATION);

    else

        MessageBox(hMainWnd, "Unknown Error", "MCI Error",

            MB_ICONEXCLAMATION);

}

Note  To interpret an mciSendCommand error return value yourself, mask the high-order word (the low-order word contains the error code). If you pass the error return value to mciGetErrorString, however, you must pass the entire doubleword value.


Playing a Waveform-Audio File

The following example opens a waveform-audio device and plays the waveform-audio file specified by the lpszWAVEFileName parameter.

// Plays a specified waveform-audio file using MCI_OPEN and MCI_PLAY.

// Returns when playback begins. Returns 0L on success, otherwise

// returns an MCI error code.

DWORD playWAVEFile(HWND hWndNotify, LPSTR lpszWAVEFileName)

{

    UINT wDeviceID;

    DWORD dwReturn;

    MCI_OPEN_PARMS mciOpenParms;

    MCI_PLAY_PARMS mciPlayParms;

    // Open the device by specifying the device and filename.

    // MCI will choose a device capable of playing the specified file.

    mciOpenParms.lpstrDeviceType = "waveaudio";

    mciOpenParms.lpstrElementName = lpszWAVEFileName;

    if (dwReturn = mciSendCommand(0, MCI_OPEN,
       MCI_OPEN_TYPE | MCI_OPEN_ELEMENT, (DWORD)(LPVOID) &mciOpenParms))

    {

        // Failed to open device. Don't close it; just return error.

        return (dwReturn);

    }

    // The device opened successfully; get the device ID.

    wDeviceID = mciOpenParms.wDeviceID;

    // Begin playback. The window procedure function for the parent

    // window will be notified with an MM_MCINOTIFY message when

    // playback is complete. At this time, the window procedure closes

    // the device.

    mciPlayParms.dwCallback = (DWORD) hWndNotify;

    if (dwReturn = mciSendCommand(wDeviceID, MCI_PLAY, MCI_NOTIFY,

        (DWORD)(LPVOID) &mciPlayParms))

    {

        mciSendCommand(wDeviceID, MCI_CLOSE, 0, NULL);

        return (dwReturn);

    }

    return (0L);

}


Playing a MIDI File

The following example opens a MIDI sequencer device, verifies that the MIDI mapper was selected as the output port, plays the MIDI file specified by the lpszMIDIFileName parameter, and closes the device after playback is complete.

// Plays a specified MIDI file by using MCI_OPEN and MCI_PLAY. Returns

// as soon as playback begins. The window procedure function for the

// specified window will be notified when playback is complete.

// Returns 0L on success; otherwise, it returns an MCI error code.

DWORD playMIDIFile(HWND hWndNotify, LPSTR lpszMIDIFileName)

{

    UINT wDeviceID;

    DWORD dwReturn;

    MCI_OPEN_PARMS mciOpenParms;

    MCI_PLAY_PARMS mciPlayParms;

    MCI_STATUS_PARMS mciStatusParms;

    MCI_SEQ_SET_PARMS mciSeqSetParms;

    // Open the device by specifying the device and filename.

    // MCI will attempt to choose the MIDI mapper as the output port.

    mciOpenParms.lpstrDeviceType = "sequencer";

    mciOpenParms.lpstrElementName = lpszMIDIFileName;

    if (dwReturn = mciSendCommand(NULL, MCI_OPEN,

        MCI_OPEN_TYPE | MCI_OPEN_ELEMENT,

        (DWORD)(LPVOID) &mciOpenParms))

    {

        // Failed to open device. Don't close it; just return error.

        return (dwReturn);

    }

    // The device opened successfully; get the device ID.

    wDeviceID = mciOpenParms.wDeviceID;

    // Check if the output port is the MIDI mapper.

    mciStatusParms.dwItem = MCI_SEQ_STATUS_PORT;

    if (dwReturn = mciSendCommand(wDeviceID, MCI_STATUS,

        MCI_STATUS_ITEM, (DWORD)(LPVOID) &mciStatusParms))

    {

        mciSendCommand(wDeviceID, MCI_CLOSE, 0, NULL);

        return (dwReturn);

    }

    // The output port is not the MIDI mapper.

    // Ask if the user wants to continue.

    if (LOWORD(mciStatusParms.dwReturn) != MIDI_MAPPER)

    {

        if (MessageBox(hMainWnd,

            "The MIDI mapper is not available. Continue?",

            "", MB_YESNO) == IDNO)

        {

            // User does not want to continue. Not an error;

            // just close the device and return.

            mciSendCommand(wDeviceID, MCI_CLOSE, 0, NULL);

            return (0L);

        }

    }

    // Begin playback. The window procedure function for the parent

    // window will be notified with an MM_MCINOTIFY message when

    // playback is complete. At this time, the window procedure closes

    // the device.

    mciPlayParms.dwCallback = (DWORD) hWndNotify;

    if (dwReturn = mciSendCommand(wDeviceID, MCI_PLAY, MCI_NOTIFY,

        (DWORD)(LPVOID) &mciPlayParms))

    {

        mciSendCommand(wDeviceID, MCI_CLOSE, 0, NULL);

        return (dwReturn);

    }

    return (0L);

}


Playing a Compact Disc Track

The following example opens a CD audio device, plays the track specified by the bTrack parameter, and closes the device after playback is complete.

// Plays a specified audio track using MCI_OPEN, MCI_PLAY. Returns as

// soon as playback begins. The window procedure function for the

// specified window will be notified when playback is complete.

// Returns 0L on success; otherwise, returns an MCI error code.

DWORD playCDTrack(HWND hWndNotify, BYTE bTrack)

{

    UINT wDeviceID;

    DWORD dwReturn;

    MCI_OPEN_PARMS mciOpenParms;

    MCI_SET_PARMS mciSetParms;

    MCI_PLAY_PARMS mciPlayParms;

    // Open the CD audio device by specifying the device name.

    mciOpenParms.lpstrDeviceType = "cdaudio";

    if (dwReturn = mciSendCommand(NULL, MCI_OPEN,

        MCI_OPEN_TYPE, (DWORD)(LPVOID) &mciOpenParms))

    {

        // Failed to open device. Don't close it; just return error.

        return (dwReturn);

    }

    // The device opened successfully; get the device ID.

    wDeviceID = mciOpenParms.wDeviceID;

    // Set the time format to track/minute/second/frame (TMSF).

    mciSetParms.dwTimeFormat = MCI_FORMAT_TMSF;

    if (dwReturn = mciSendCommand(wDeviceID, MCI_SET,

        MCI_SET_TIME_FORMAT, (DWORD)(LPVOID) &mciSetParms))

    {

        mciSendCommand(wDeviceID, MCI_CLOSE, 0, NULL);

        return (dwReturn);

    }

    // Begin playback from the given track and play until the beginning

    // of the next track. The window procedure function for the parent

    // window will be notified with an MM_MCINOTIFY message when

    // playback is complete. Unless the play command fails, the window

    // procedure closes the device.

    mciPlayParms.dwFrom = 0L;

    mciPlayParms.dwTo = 0L;

    mciPlayParms.dwFrom = MCI_MAKE_TMSF(bTrack, 0, 0, 0);

    mciPlayParms.dwTo = MCI_MAKE_TMSF(bTrack + 1, 0, 0, 0);

    mciPlayParms.dwCallback = (DWORD) hWndNotify;

    if (dwReturn = mciSendCommand(wDeviceID, MCI_PLAY,

        MCI_FROM | MCI_TO | MCI_NOTIFY, (DWORD)(LPVOID) &mciPlayParms))

    {

        mciSendCommand(wDeviceID, MCI_CLOSE, 0, NULL);

        return (dwReturn);

    }

    return (0L);

}

To specify a position relative to a track on a compact disc, you must use the track/minute/second/frame (TMSF) time format.


Playing a Movie

The following examples show how to set up and play an audio-video interleaved (AVI) file.


Opening the Playback Window

The following example shows how to use the MCI_OPEN command to set a parent window and create a child of that window.

MCI_DGV_OPEN_PARMS    mciOpen;

mciOpen.lpstrElementName = lpstrFile;  // Set the filename.

mciOpen.dwStyle = WS_CHILD;            // Set the style.

mciOpen.hWndParent = hWnd;             // Give a window handle.

if (mciSendCommand(0, MCI_OPEN,

   (DWORD)(MCI_OPEN_ELEMENT|MCI_DGV_OPEN_PARENT|MCI_DGV_OPEN),

   (DWORD)(LPSTR)&mciOpen) == 0)

{

    // Open operation is successful. Continue.

}


Setting Up the Playback Window

The following example finds the dimensions needed to play an AVI file, creates a window corresponding to that size, and plays the file in the window by using the MCIAVI driver.

HWND hwnd;

MCI_DGV_RECT_PARMS mciRect;

// Get the movie dimensions with MCI_WHERE.

mciSendCommand(wDeviceID, MCI_WHERE, MCI_DGV_WHERE_SOURCE,

    (DWORD)(LPSTR)&mciRect);

// Create the playback window. Make it bigger for the border.

// Note that the right and bottom members of RECT structures in MCI

// are unusual; rc.right is set to the rectangle's width, and

// rc.bottom is set to the rectangle's height.

hwndMovie = CreateWindow("mywindow", "Playback",

    WS_CHILD|WS_BORDER, 0,0,

    mciRect.rc.right+(2*GetSystemMetric(SM_CXBORDER)),

    mciRect.rc.bottom+(2*GetSystemMetric(SM_CYBORDER)),

    hwndParent, hInstApp, NULL);

if (hwndMovie){

    // Window created OK; make it the playback window.

    MCI_DGV_WINDOW_PARMS mciWindow;

    mciWindow.hWnd = hwndMovie;

    mciSendCommand(wDeviceID, MCI_WINDOW, MCI_DGV_WINDOW_HWND,

        (DWORD)(LPSTR)&mciWindow);

}


Playing the AVI File

Before using the mciSendCommand function to send the MCI_PLAY command, your application allocates the memory for the structure, initializes the members it will use, and sets the flags corresponding to the members used in the structure. (If your application does not set a flag for a structure member, MCI drivers ignore the member.) For example, the following example plays a movie from the starting position specified by dwFrom to the ending position specified by dwTo. (If either position is zero, the example is written so that the position is not used.)

DWORD PlayMovie(WORD wDevID, DWORD dwFrom, DWORD dwTo)

{

    MCI_DGV_PLAY_PARMS mciPlay;    // play parameters

    DWORD dwFlags = 0;

    // Check dwFrom. If it is != 0 then set parameters and flags.

    if (dwFrom){

        mciPlay.dwFrom = dwFrom; // set parameter

        dwFlags |= MCI_FROM;     // set flag to validate member

    }

    // Check dwTo. If it is != 0 then set parameters and flags.

    if (dwTo){

        mciPlay.dwTo = dwTo;    // set parameter

        dwFlags |= MCI_TO;      // set flag to validate member

    }

    // Send the MCI_PLAY command and return the result.

    return mciSendCommand(wDevID, MCI_PLAY, dwFlags,

       (DWORD)(LPVOID)&mciPlay);

}


Changing the Current Position

To change the current position in a device element, use the MCI_SEEK command message along with the MCI_TO flag and the MCI_SEEK_PARMS structure. If you use the dwTo member to specify a seek position with MCI_SEEK, you should query the time format and set it, if necessary.

In addition to specifying a position with the dwTo member, you can specify the MCI_SEEK_TO_START or MCI_SEEK_TO_END flags for the dwParam1 parameter of the mciSendCommand function to find the starting and ending positions of the device element. If you use one of these flags, don’t specify the MCI_TO flag.


Setting the Time Format

Use the MCI_SET command message along with the MCI_SET_PARMS structure to set the time format for an open device. Set the dwTimeFormat member to one of the following constants.

Constant	Time format
MCI_FORMAT_BYTES	Bytes (in pulse code modulated [PCM] format files)
MCI_FORMAT_MILLISECONDS	Milliseconds
MCI_FORMAT_MSF	Minute/second/frame
MCI_FORMAT_SAMPLES	Samples
MCI_FORMAT_SMPTE_24	SMPTE, 24 frame
MCI_FORMAT_SMPTE_25	SMPTE, 25 frame
MCI_FORMAT_SMPTE_30	SMPTE, 30 frame
MCI_FORMAT_SMPTE_30DROP	SMPTE, 30 frame drop
MCI_FORMAT_TMSF	Track/minute/second/frame
MCI_SEQ_FORMAT_SONGPTR	MIDI song pointer
The following example sets the time format to milliseconds on the device specified by the wDeviceID variable:

UINT wDeviceID;

MCI_SET_PARMS mciSetParms;

// Set time format to milliseconds.

mciSetParms.dwTimeFormat = MCI_FORMAT_MILLISECONDS;

if (mciSendCommand(wDeviceID, MCI_SET, MCI_SET_TIME_FORMAT,

                   (DWORD) &mciSetParms))

    // Error, unable to set time format.

    return FALSE;

else

    // Time format set successfully.

    return TRUE;


Changing Sequencer Synchronization

To change the synchronization mode of a sequencer device, use the MCI_SET command message with the MCI_SEQ_SET_MASTER and MCI_SEQ_SET_SLAVE flags. Two members in the MCI_SEQ_SET_PARMS structure, dwMaster and dwSlave, are used to specify the master and slave synchronization modes.

The master synchronization mode controls synchronization information sent by the sequencer to an output port. The slave synchronization mode controls where the sequencer gets its timing information to play a MIDI file. Following are the constants for the dwMaster member and their corresponding master synchronization modes.

Constant	Synchronization mode
MCI_SEQ_MIDI	MIDI Synchronization. Send timing information to output port using MIDI timing clock messages.
MCI_SEQ_SMPTE	SMPTE Synchronization. Send timing information to output port using MIDI quarter-frame messages.
MCI_SEQ_NONE	No Synchronization. Send no timing information.
Following are the constants for the dwSlave member and their corresponding slave synchronization modes.

Constant	Synchronization mode
MCI_SEQ_FILE	File Synchronization. Get timing information from MIDI file.
MCI_SEQ_MIDI	MIDI Synchronization. Get timing information from input port using MIDI timing clock messages.
MCI_SEQ_SMPTE	SMPTE Synchronization. Get timing information from input port using MIDI quarter-frame messages.
MCI_SEQ_NONE	No Synchronization. Get timing information from MCI commands only and ignore timing information (such as tempo changes) that are in the MIDI file.
Note  Currently, for master synchronization, the MCI MIDI sequencer supports only the No Synchronization mode (MCI_SEQ_NONE). For slave synchronization, it supports only the File Synchronization mode (MCI_SEQ_FILE) and the No Synchronization mode (MCI_SEQ_NONE).


Using the MCI_NOTIFY Flag

The following example shows how the MCI_NOTIFY flag is used with the MCI_PLAY command. The handle to the window procedure that will process the MM_MCINOTIFY message is specified in hwnd.

MCI_DGV_PLAY_PARMS mciPlay;

DWORD dwFlags;

mciPlay.dwCallback = MAKELONG(hwnd, 0);

dwFlags = MCI_NOTIFY;

mciSendCommand(wMCIDeviceID, MCI_PLAY, dwFlags, (DWORD)(LPSTR)&mciPlay);


Retrieving Information About a Movie

The following example sets the time format to frames and obtains the current position if the device is playing.

MCI_DGV_SET_PARMS mciSet;

MCI_DGV_STATUS_PARMS mciStatus;

// Put in frame mode.

mciSet.dwTimeFormat = MCI_FORMAT_FRAMES;

mciSendCommand(wDeviceID, MCI_SET,

    MCI_SET_TIME_FORMAT,

    (DWORD)(LPSTR)&mciSet);

mciStatus.dwItem = MCI_STATUS_MODE;

mciSendCommand(wDeviceID, MCI_STATUS,

    MCI_STATUS_ITEM,

    (DWORD)(LPSTR)&mciStatus);

// If device is playing, get the position.

if (mciStatus.dwReturn == MCI_MODE_PLAY){

    mciStatus.dwItem = MCI_STATUS_POSITION;

    mciSendCommand(wDeviceID, MCI_STATUS, MCI_STATUS_ITEM,

        (DWORD)(LPSTR)&mciStatus);

// Update the position from mciStatus.dwReturn.

}


Retrieving Compact Disc Track-Specific Information

For CD audio devices, you can get the starting location and length of a track by specifying the MCI_TRACK flag and setting the dwTrack member of MCI_STATUS_PARMS to the desired track number. To get the starting location of a track, set the dwItem member to MCI_STATUS_POSITION. To get the length of a track, set dwItem to MCI_STATUS_LENGTH. For example, the following example retrieves the total number of tracks on the compact disc and the starting location of each track. Then, it uses the MessageBox function to report the starting locations of the tracks.

// Uses the MCI_STATUS command to get and display the

// starting times for the tracks on a compact disc.

// Returns 0L if successful; otherwise, it returns an

// MCI error code.

DWORD getCDTrackStartTimes(VOID)

{

    UINT wDeviceID;

    int i, iNumTracks;

    DWORD dwReturn;

    DWORD dwPosition;

    DWORD *pMem;

    char szTempString[64];

    char szTimeString[512] = "\0";  // room for 20 tracks

    MCI_OPEN_PARMS mciOpenParms;

    MCI_SET_PARMS mciSetParms;

    MCI_STATUS_PARMS mciStatusParms;

    // Open the device by specifying the device name.

    mciOpenParms.lpstrDeviceType = "cdaudio";

    if (dwReturn = mciSendCommand(NULL, MCI_OPEN,

        MCI_OPEN_TYPE, (DWORD)(LPVOID) &mciOpenParms))

    {

        // Failed to open device.

        // Don't close device; just return error.

        return (dwReturn);

    }

    // The device opened successfully; get the device ID.

    wDeviceID = mciOpenParms.wDeviceID;

// Set the time format to minute/second/frame (MSF) format.

    mciSetParms.dwTimeFormat = MCI_FORMAT_MSF;

    if (dwReturn = mciSendCommand(wDeviceID, MCI_SET,

        MCI_SET_TIME_FORMAT,

        (DWORD)(LPVOID) &mciSetParms))

    {

        mciSendCommand(wDeviceID, MCI_CLOSE, 0, NULL);

        return (dwReturn);

    }

    // Get the number of tracks;

    // limit to number that can be displayed (20).

    mciStatusParms.dwItem = MCI_STATUS_NUMBER_OF_TRACKS;

    if (dwReturn = mciSendCommand(wDeviceID, MCI_STATUS,

        MCI_STATUS_ITEM, (DWORD)(LPVOID) &mciStatusParms))

    {

        mciSendCommand(wDeviceID, MCI_CLOSE, 0, NULL);

        return (dwReturn);

    }

    iNumTracks = mciStatusParms.dwReturn;

    iNumTracks = min(iNumTracks, 20);

    // Allocate memory to hold starting positions.

    pMem = (DWORD *)LocalAlloc(LPTR,

        iNumTracks * sizeof(DWORD));

    if (pMem == NULL)

    {

        mciSendCommand(wDeviceID, MCI_CLOSE, 0, NULL);

        return (-1);

    }

// For each track, get and save the starting location and

// build a string containing starting locations.

    for(i=1; i<=iNumTracks; i++)

    {

        mciStatusParms.dwItem = MCI_STATUS_POSITION;

        mciStatusParms.dwTrack = i;

        if (dwReturn = mciSendCommand(wDeviceID,

            MCI_STATUS, MCI_STATUS_ITEM | MCI_TRACK,

            (DWORD)(LPVOID) &mciStatusParms)) {

            mciSendCommand(wDeviceID, MCI_CLOSE, 0, NULL);

            return (dwReturn);

        }

        pMem[i-1] = mciStatusParms.dwReturn;

        wsprintf(szTempString,

            "Track %2d - %02d:%02d:%02d\n", i,

            MCI_MSF_MINUTE(pMem[i-1]),

            MCI_MSF_SECOND(pMem[i-1]),

            MCI_MSF_FRAME(pMem[i-1]));

        lstrcat(szTimeString, szTempString);

    }

    // Use MessageBox to display starting times.

    MessageBox(hMainWnd, szTimeString,

        "Track Starting Position", MB_ICONINFORMATION);

    // Free memory and close the device.

    LocalFree((HANDLE) pMem);

    if (dwReturn = mciSendCommand(wDeviceID,

        MCI_CLOSE, 0, NULL)) {

        return (dwReturn);

    }

    return (0L);

}


Recording with a Waveform-Audio Device

The following example opens a waveform-audio device with a new file, records for the specified time, plays the recording, and prompts the user to save the recording if desired.

// Uses the MCI_OPEN, MCI_RECORD, and MCI_SAVE commands to record and

// save a waveform-audio file. Returns 0L if successful; otherwise,

// it returns an MCI error code.

DWORD recordWAVEFile(DWORD dwMilliSeconds)

{

    UINT wDeviceID;

    DWORD dwReturn;

    MCI_OPEN_PARMS mciOpenParms;

    MCI_RECORD_PARMS mciRecordParms;

    MCI_SAVE_PARMS mciSaveParms;

    MCI_PLAY_PARMS mciPlayParms;

    // Open a waveform-audio device with a new file for recording.

    mciOpenParms.lpstrDeviceType = "waveaudio";

    mciOpenParms.lpstrElementName = "";

    if (dwReturn = mciSendCommand(0, MCI_OPEN,

        MCI_OPEN_ELEMENT | MCI_OPEN_TYPE,
        (DWORD)(LPVOID) &mciOpenParms))
    {

        // Failed to open device; don't close it, just return error.

        return (dwReturn);

    }

    // The device opened successfully; get the device ID.

    wDeviceID = mciOpenParms.wDeviceID;

    // Begin recording and record for the specified number of

    // milliseconds. Wait for recording to complete before continuing.

    // Assume the default time format for the waveform-audio device

    // (milliseconds).

    mciRecordParms.dwTo = dwMilliSeconds;

    if (dwReturn = mciSendCommand(wDeviceID, MCI_RECORD,

        MCI_TO | MCI_WAIT, (DWORD)(LPVOID) &mciRecordParms))

    {

        mciSendCommand(wDeviceID, MCI_CLOSE, 0, NULL);

        return (dwReturn);

    }

    // Play the recording and query user to save the file.

    mciPlayParms.dwFrom = 0L;

    if (dwReturn = mciSendCommand(wDeviceID, MCI_PLAY,

        MCI_FROM | MCI_WAIT, (DWORD)(LPVOID) &mciPlayParms))

    {

        mciSendCommand(wDeviceID, MCI_CLOSE, 0, NULL);

        return (dwReturn);

    }

    if (MessageBox(hMainWnd, "Do you want to save this recording?",

        "", MB_YESNO) == IDNO)

    {

        mciSendCommand(wDeviceID, MCI_CLOSE, 0, NULL);

        return (0L);

    }

    // Save the recording to a file named TEMPFILE.WAV. Wait for

    // the operation to complete before continuing.

    mciSaveParms.lpfilename = "tempfile.wav";

    if (dwReturn = mciSendCommand(wDeviceID, MCI_SAVE,

        MCI_SAVE_FILE | MCI_WAIT, (DWORD)(LPVOID) &mciSaveParms))

    {

        mciSendCommand(wDeviceID, MCI_CLOSE, 0, NULL);

        return (dwReturn);

    }

    return (0L);

}


MCI Reference

This section describes the MCI functions, structures, messages, macros, commands, and command strings. These elements are grouped as follows.

Notifications

MM_MCINOTIFY
MM_MCISIGNAL

Retrieving Information

mciGetCreatorTask
mciGetDeviceID
mciGetErrorString

Sending Commands

mciSendCommand
mciSendString

Time Formats

MCI_HMS_HOUR
MCI_HMS_MINUTE
MCI_HMS_SECOND
MCI_MAKE_HMS
MCI_MAKE_MSF
MCI_MAKE_TMSF
MCI_MSF_FRAME
MCI_MSF_MINUTE
MCI_MSF_SECOND
MCI_TMSF_FRAME
MCI_TMSF_MINUTE
MCI_TMSF_SECOND
MCI_TMSF_TRACK

Yield Procedures

mciGetYieldProc
mciSetYieldProc

Configuring a Device

break
configure
escape
index
MCI_BREAK
MCI_BREAK_PARMS
MCI_CONFIGURE
MCI_DGV_SET_PARMS
MCI_DGV_SETAUDIO_PARMS
MCI_DGV_SETVIDEO_PARMS
MCI_ESCAPE
MCI_INDEX
MCI_SEQ_SET_PARMS
MCI_SET
MCI_SET_PARMS
MCI_SETAUDIO
MCI_SETTIMECODE
MCI_SETTUNER
MCI_SETVIDEO
MCI_SPIN
MCI_VCR_SET_PARMS
MCI_VCR_SETAUDIO_PARMS
MCI_VCR_SETTUNER_PARMS
MCI_VCR_SETVIDEO_PARMS
MCI_VD_ESCAPE_PARMS
MCI_WAVE_SET_PARMS
set
setaudio
settimecode
settuner
setvideo
spin

Controlling Playback

freeze
load
MCI_DGV_FREEZE_PARMS
MCI_DGV_LOAD_PARMS
MCI_DGV_PAUSE_PARMS
MCI_DGV_PLAY_PARMS
MCI_DGV_RESUME_PARMS
MCI_DGV_STOP_PARMS
MCI_FREEZE
MCI_LOAD
MCI_LOAD_PARMS
MCI_OVLY_LOAD_PARMS
MCI_PAUSE
MCI_PLAY
MCI_PLAY_PARMS
MCI_RESUME
MCI_STOP
MCI_UNFREEZE
MCI_VCR_PLAY_PARMS
MCI_VD_PLAY_PARMS
pause
play
resume
stop
unfreeze

Controlling the Position

cue
mark
MCI_CUE
MCI_DGV_CUE_PARMS
MCI_DGV_SIGNAL_PARMS
MCI_DGV_STEP_PARMS
MCI_MARK
MCI_SEEK
MCI_SEEK_PARMS
MCI_SIGNAL
MCI_STEP
MCI_VCR_CUE_PARMS
MCI_VCR_SEEK_PARMS
MCI_VCR_STEP_PARMS
MCI_VD_STEP_PARMS
seek
signal
step

Editing

copy
cut
delete
MCI_COPY
MCI_CUT
MCI_DELETE
MCI_DGV_COPY_PARMS
MCI_DGV_CUT_PARMS
MCI_DGV_DELETE_PARMS
MCI_DGV_PASTE_PARMS
MCI_PASTE
MCI_UNDO
MCI_WAVE_DELETE_PARMS
paste
undo

Miscellaneous

MCI_GENERIC_PARMS

Opening and Closing

close
MCI_CLOSE
MCI_DGV_OPEN_PARMS
MCI_OPEN
MCI_OPEN_PARMS
MCI_OVLY_OPEN_PARMS
MCI_WAVE_OPEN_PARMS
open

Realizing a Palette

MCI_REALIZE
realize

Repainting a Frame

MCI_DGV_UPDATE_PARMS
MCI_UPDATE
update

Retrieving Information

capability
info
list
MCI_DGV_INFO_PARMS
MCI_DGV_LIST_PARMS
MCI_DGV_STATUS_PARMS
MCI_GETDEVCAPS
MCI_GETDEVCAPS_PARMS
MCI_INFO
MCI_INFO_PARMS
MCI_LIST
MCI_STATUS
MCI_STATUS_PARMS
MCI_SYSINFO
MCI_SYSINFO_PARMS
MCI_VCR_LIST_PARMS
MCI_VCR_STATUS_PARMS
status
sysinfo

Saving

MCI_DGV_RECORD_PARMS
MCI_DGV_SAVE_PARMS
MCI_OVLY_SAVE_PARMS
MCI_RECORD
MCI_RECORD_PARMS
MCI_SAVE
MCI_SAVE_PARMS
MCI_VCR_RECORD_PARMS
record
save

Video Control

capture
MCI_CAPTURE
MCI_DGV_MONITOR_PARMS
MCI_DGV_QUALITY_PARMS
MCI_DGV_RESERVE_PARMS
MCI_DGV_RESTORE_PARMS
MCI_MONITOR
MCI_QUALITY
MCI_RESERVE
MCI_RESTORE
monitor
quality
reserve
restore

Window or Display Rectangles

MCI_DGV_PUT_PARMS
MCI_DGV_RECT_PARMS
MCI_DGV_WINDOW_PARMS
MCI_OVLY_RECT_PARMS
MCI_OVLY_WINDOW_PARMS
MCI_PUT
MCI_WHERE
MCI_WINDOW
put
where
window


MCI Functions

The following functions are used with MCI.

mciGetCreatorTask
mciGetDeviceID
mciGetErrorString
mciGetYieldProc
mciSendCommand
mciSendString
mciSetYieldProc


MCI Structures

The following structures are used with MCI.

MCI_BREAK_PARMS
MCI_DGV_CAPTURE_PARMS
MCI_DGV_COPY_PARMS
MCI_DGV_CUE_PARMS
MCI_DGV_CUT_PARMS
MCI_DGV_DELETE_PARMS
MCI_DGV_FREEZE_PARMS
MCI_DGV_INFO_PARMS
MCI_DGV_LIST_PARMS
MCI_DGV_LOAD_PARMS
MCI_DGV_MONITOR_PARMS
MCI_DGV_OPEN_PARMS
MCI_DGV_PASTE_PARMS
MCI_DGV_PAUSE_PARMS
MCI_DGV_PLAY_PARMS
MCI_DGV_PUT_PARMS
MCI_DGV_QUALITY_PARMS
MCI_DGV_RECORD_PARMS
MCI_DGV_RECT_PARMS
MCI_DGV_RESERVE_PARMS
MCI_DGV_RESTORE_PARMS
MCI_DGV_RESUME_PARMS
MCI_DGV_SAVE_PARMS
MCI_DGV_SET_PARMS
MCI_DGV_SETAUDIO_PARMS
MCI_DGV_SETVIDEO_PARMS
MCI_DGV_SIGNAL_PARMS
MCI_DGV_STATUS_PARMS
MCI_DGV_STEP_PARMS
MCI_DGV_STOP_PARMS
MCI_DGV_UPDATE_PARMS
MCI_DGV_WINDOW_PARMS
MCI_GENERIC_PARMS
MCI_GETDEVCAPS_PARMS
MCI_INFO_PARMS
MCI_LOAD_PARMS
MCI_OPEN_PARMS
MCI_OVLY_LOAD_PARMS
MCI_OVLY_OPEN_PARMS
MCI_OVLY_RECT_PARMS
MCI_OVLY_SAVE_PARMS
MCI_OVLY_WINDOW_PARMS
MCI_PLAY_PARMS
MCI_RECORD_PARMS
MCI_SAVE_PARMS
MCI_SEEK_PARMS
MCI_SEQ_SET_PARMS
MCI_SET_PARMS
MCI_STATUS_PARMS
MCI_SYSINFO_PARMS
MCI_VCR_CUE_PARMS
MCI_VCR_LIST_PARMS
MCI_VCR_PLAY_PARMS
MCI_VCR_RECORD_PARMS
MCI_VCR_SEEK_PARMS
MCI_VCR_SET_PARMS
MCI_VCR_SETAUDIO_PARMS
MCI_VCR_SETTUNER_PARMS
MCI_VCR_SETVIDEO_PARMS
MCI_VCR_STATUS_PARMS
MCI_VCR_STEP_PARMS
MCI_VD_ESCAPE_PARMS
MCI_VD_PLAY_PARMS
MCI_VD_STEP_PARMS
MCI_WAVE_DELETE_PARMS
MCI_WAVE_OPEN_PARMS
MCI_WAVE_SET_PARMS


MCI Messages

The following messages are used with MCI.

MM_MCINOTIFY
MM_MCISIGNAL


MCI Macros

The following macros are used with MCI.

MCI_HMS_HOUR
MCI_HMS_MINUTE
MCI_HMS_SECOND
MCI_MAKE_HMS
MCI_MAKE_MSF
MCI_MAKE_TMSF
MCI_MSF_FRAME
MCI_MSF_MINUTE
MCI_MSF_SECOND
MCI_TMSF_FRAME
MCI_TMSF_MINUTE
MCI_TMSF_SECOND
MCI_TMSF_TRACK


MCI Commands

The following commands are used with MCI.

MCI_BREAK
MCI_CAPTURE
MCI_CLOSE
MCI_CONFIGURE
MCI_COPY
MCI_CUE
MCI_CUT
MCI_DELETE
MCI_ESCAPE
MCI_FREEZE
MCI_GETDEVCAPS
MCI_INDEX
MCI_INFO
MCI_LIST
MCI_LOAD
MCI_MARK
MCI_MONITOR
MCI_OPEN
MCI_PASTE
MCI_PAUSE
MCI_PLAY
MCI_PUT
MCI_QUALITY
MCI_REALIZE
MCI_RECORD
MCI_RESERVE
MCI_RESTORE
MCI_RESUME
MCI_SAVE
MCI_SEEK
MCI_SET
MCI_SETAUDIO
MCI_SETTIMECODE
MCI_SETTUNER
MCI_SETVIDEO
MCI_SIGNAL
MCI_SPIN
MCI_STATUS
MCI_STEP
MCI_STOP
MCI_SYSINFO
MCI_UNDO
MCI_UNFREEZE
MCI_UPDATE
MCI_WHERE
MCI_WINDOW


MCI Command Strings

The following command strings are used with MCI.

break
capability
capture
close
configure
copy
cue
cut
delete
escape
freeze
index
info
list
load
mark
monitor
open
paste
pause
play
put
quality
realize
record
reserve
restore
resume
save
seek
set
setaudio
settimecode
settuner
setvideo
signal
spin
status
step
stop
sysinfo
undo
unfreeze
update
where
window


MCIWnd Window Class

MCIWnd is a window class for controlling multimedia devices. A library of functions, messages, and macros associated with MCIWnd provides a simple method to add multimedia playback or recording capabilities to your applications.


About the MCIWnd Window Class

The MCIWnd Window class is easy to use. By using a single function, MCIWndCreate your application can create a control that plays any device that uses the media control interface (MCI). These devices include CD audio, waveform-audio, MIDI, and video devices.

Automating playback is also quick and easy. Using only one function and two macros, an application can create an MCIWnd window with the appropriate media device, play the device, and close both the device and the window when the content has finished playing.

Note  Some devices play content that is stored in files. Other devices, such as CD audio devices, play content that is stored in another medium. For purposes of clarity, this overview refers to both circumstances as “playing the device.”


MCIWnd Window User Interface

MCIWnd provides additional features to adjust the look of the MCIWnd window, customize the behavior of your application, and tune playback performance. The following features are included in the MCIWnd window:

•	A toolbar with Play, Stop, Record and Menu buttons

•	A trackbar that controls positioning within the playback content

•	A pop-up menu containing common commands

•	A playback area for video and other devices that display images

The following illustration shows the initial state of user-controlled video playback. The sample file used is CLOCK.AVI.

The MCIWnd window includes a playback area for video and other devices that display images during playback. MCIWnd omits the playback area from waveform-audio devices, MIDI sequencers, and other devices that do not write to the display. The following illustration shows the waveform-audio playback area.

The Play button is located in the lower-left corner of the MCIWnd window. It appears when the content is stopped. The user can play the content in the following ways:

•	To play the content from the current playback position, select the Play button.

•	To play the content full-screen from the current playback position, select the Play button while holding down the CTRL key.

•	To play the content backward from the current playback position, select the Play button while holding down the SHIFT key.

The Menu button, located next to the Play button, activates a menu that allows the user to open and close audio-video interleaved (AVI) files, and to adjust the image size, playback speed, and volume. (The user can also activate the menu by clicking the right mouse button whenever the cursor is in the client area of the window.) The menu also includes commands to change the configuration of the current device, to copy the playback content to the clipboard, and to issue MCI commands.

The trackbar to the right of the Menu button represents the duration of the playback (or recorded) content. The slider on the trackbar represents the current playback position within the content. When the slider is positioned at the left end of the trackbar, the current playback position is the beginning of the content. The user can move to different locations in the content by dragging the slider along the trackbar. The Stop button is located in the lower-left corner of the MCIWnd window. It appears when the content is played. The following illustration shows video playback in progress.

The MCIWnd controls can also include a Record button for devices that can record. The Record button is marked with a red circle and appears only when the device is capable of recording.

Note  The playback window must be aligned on a four-pixel boundary for the best video playback performance. Typically, the Microsoft® Windows® operating system aligns the window automatically when it is created. If a user moves or stretches the window from its initial position, video playback speed might be reduced by half.


Multimedia Playback

The MCIWndCreate function provides the means for controlling an MCIWnd window and the device associated with it. In general, this function registers the MCIWnd window class and creates an MCIWnd window for using MCI services. This section describes how to use MCIWndCreate to perform the following tasks:

•	Adding user-controlled playback.

•	Automating playback.

•	Using window styles to change the MCIWnd window.

•	Allowing the user to specify devices and files.


Adding User-Controlled Playback

You can add user-controlled playback to an existing application by calling the MCIWndCreate function as follows:

MCIWndCreate(hwndParent, hInstModule, NULL, "filename.typ");

The MCIWndCreate parameters identify handles to the parent window and to the module instance associated with the MCIWnd window. They also specify window styles and the filename (or device name) to associate with the MCIWnd window.

MCIWndCreate automatically performs the following steps that, for other window classes, you would implement in your code yourself:

1.	Register the MCIWnd window class.

2.	Create the MCIWnd window.

3.	Load the specified content.

4.	Establish the current playback position at the beginning of the content.

5.	Display the device control.

6.	Display the playback area of the window, if needed.


Automating Playback

You can automate playback in your application by using MCIWndCreate and the MCIWndPlay macro, along with either the MCIWndDestroy or the MCIWndClose macro. To automate playback, specify the MCIWNDF_NOPLAYBAR and MCIWNDF_NOTIFYMODE styles in the MCIWndCreate dwStyle parameter. Specify the MCIWNDF_NOPLAYBAR style to hide the toolbar, and the MCIWNDF_NOTIFYMODE style to issue an appropriate notification message when the device stops playing.

You can play the device or file specified in MCIWndCreate by using MCIWndPlay. The MCIWndPlay macro starts playing the content from its current playback position and continues to its end.

You can destroy or close an MCIWnd window by using the MCIWndDestroy or MCIWndClose macro. The MCIWndDestroy macro closes the device or file and destroys the MCIWnd window by invalidating its handle. If your application can reuse the MCIWnd window, use MCIWndClose to close the device without destroying the window.

Your application can detect when the device stops playing and automatically close the window. To do this, specify the MCIWNDF_NOTIFYMODE style for the dwStyle parameter of MCIWndCreate. This causes the device to send a MCIWNDM_NOTIFYMODE message whenever it changes modes. Your application can trap this message to determine whether the device has stopped playing. When the device stops playing, the application closes the window.


Using Window Styles to Change the MCIWnd Window

As with any window, you can change the appearance and behavior of an MCIWnd window by choosing from the standard window styles specified with the CreateWindow function. In addition, you can choose from several other window styles that are specific to MCIWnd windows. With these styles, your application can change these MCIWnd windows in the following ways:

•	Change window size.

•	Hide or display controls.

•	Issue notification messages.

•	Display information in the title bar.

You can set window styles by specifying them in the MCIWndCreate function, or you can use the MCIWndChangeStyles macro to change the style of an existing MCIWnd window. You can also query an MCIWnd window for its current styles by using the MCIWndGetStyles macro.

For a list of the MCIWnd-specific window styles, see MCIWndCreate.


Allowing the User to Specify Devices and Files

You can associate a device or file with an existing MCIWnd window by using the MCIWndOpenDialog, MCIWndOpen, and MCIWndOpenInterface macros, and the GetOpenFileNamePreview function.

To let a user of your application select a file to play, use MCIWndOpenDialog. This macro displays the Open dialog box (shown following) for choosing a file and associates the selected file with the current MCIWnd window.

You can let a user of your application select a file to associate with an MCIWnd window and preview that file by using GetOpenFileNamePreview and MCIWndOpen. The GetOpenFileNamePreview function displays the Open dialog box for choosing a file and lets the user preview (play) its contents. When the name of an existing file is specified in the dialog box, GetOpenFileNamePreview provides a small control to let the user preview the contents of the file. You can associate a specified file, selected with GetOpenFileNamePreview or specified in another manner, with an MCIWnd window by using MCIWndOpen.

You can also use MCIWndOpen to specify a device to associate with an MCIWnd window. For example, you can use a device name, such as “CDAudio”.

To associate an MCIWnd window with a file interface or data-stream interface to multimedia data, use the MCIWndOpenInterface macro. For more information about file and data-stream interfaces, see AVIFile Functions and Macros.

Note  Before associating a new file or device with an MCIWnd window, MCIWndOpenDialog and MCIWndOpen close any device currently associated with the window. Your application does not need to close any open devices before using these macros.


Playback Controls

MCIWnd includes several macros for controlling playback. This section describes how to use these macros to perform the following tasks:

•	Determining and changing the current position.

•	Starting, pausing, and resuming playback.

•	Defining playback scope.

•	Reversing playback.

•	Looping playback.


Determining and Changing the Current Position

When a file or device is associated with an MCIWnd window, the playback position is initially set at the start of the content, regardless of the media type. During playback, the playback position moves linearly through the content and, if playback is uninterrupted, eventually reaches the end of the content. If an interruption occurs, the current playback position is the location at which playback was stopped or paused.

You can retrieve the locations for the beginning and end of the content by using the MCIWndGetStart and MCIWndGetEnd macros. You can determine the length of the content by subtracting the value returned by MCIWndGetStart from the value returned by MCIWndGetEnd, or by using the MCIWndGetLength macro. You can retrieve the current playback position by using the MCIWndGetPosition macro, or you can retrieve the playback position as a null-terminated string by using the MCIWndGetPositionString macro.

To change the current playback position, use the MCIWndHome, MCIWndEnd, and MCIWndSeek macros. You can move the playback position to the start of the content by using MCIWndHome or to the end of the content by using MCIWndEnd. Use MCIWndSeek to move the playback position to any location in the content.

You can also step through the content by using the MCIWndStep macro. Beginning from the current playback position, this macro moves the playback position forward or backward by a specified increment.

Note  The units used to specify position vary among the different media types and devices. For example, the playback position for AVI files used by the MCIAVI device is measured in frames; the playback position for CD audio, waveform-audio, and MIDI files is measured in milliseconds.

Devices for other media types and third-party devices might use other units. For information about determining these units, see Playback Enhancements.


Starting, Pausing, and Resuming Playback

MCIWndPlay is the most general playback macro. This macro lets you play a file or device from the current playback position. Playback continues through the end of the content unless it is interrupted.

You can temporarily interrupt a device that is playing by using the MCIWndPause macro. To resume playback from the paused position, use the MCIWndResume macro. Some devices do not support the pause and resume commands. These devices usually map MCIWndPause to the MCIWndStop macro, which stops playback or recording. You can restart a device that does not support pause or resume by using MCIWndPlay, which starts playback from the current playback position.


Defining Playback Scope

MCIWnd provides macros that allow you to define the playback scope. The scope is the portion of the playback you want to play. For example, you can play the content from a position other than the beginning position by using the MCIWndPlayFrom macro. This macro moves to the specified position, begins playback, and continues to the end of the content. Similarly, you can play the content to a specified end point by using the MCIWndPlayTo macro. This macro starts at the current playback position and plays until it reaches the specified position or the end of the content is reached, whichever comes first.

Also, you can define both the beginning and ending positions by using the MCIWndPlayFromTo macro. This macro moves to the specified starting position and plays until the specified ending position or the end of the content is reached.


Reversing Playback

Some devices support playback in the reverse direction. You can play the content of such a device in the reverse direction by using the MCIWndPlayReverse macro. This macro defines the playback scope from the current playback position to the beginning of the content. The digital-video device, MCIAVI.DRV, can play backward. Devices that cannot play backward, such as CD audio, can issue an error message when MCIWndPlayReverse is invoked.


Looping Playback

MCIWnd supports playback as a continuous loop. You can play the content of a file or device repeatedly as a loop by using the MCIWndSetRepeat macro in combination with the Play button on the toolbar. The video playback device, MCIAVI, supports playback loops. To determine if continuous playback has been activated, use the MCIWndGetRepeat macro.


Multimedia Recording

You can implement recording capabilities in your application by using the user interface built into MCIWnd. You can use the MCIWndCreate function and the MCIWndNew macro to provide controls for starting and stopping recording and for saving the recorded information. Using MCIWndCreate, you can specify window styles to display an MCIWnd window and to include the Record button on the toolbar. Using MCIWndNew, you can specify the device type that is being recorded and specify that the information is to be captured in a new file.

If your application requires more sophistication, you can automate and customize the recording by using the MCIWndRecord macro. For more information, see Customizing the Recording Process.

Note  Some devices, such as CD audio and MCIAVI, are used for playback only. Other devices, such as waveform-audio devices, can be used for recording. If you specify a device that cannot record, MCIWnd omits the Record button from the toolbar.


Saving Recorded Content

After completing the recording, you can save the content by using the MCIWndSave or MCIWndSaveDialog macro, or by using the GetSaveFileNamePreview function with MCIWndSave. The MCIWndSave macro saves data in the file associated with the MCIWnd window. The MCIWndSaveDialog macro lets the user specify a filename and save the recorded data in the specified file. The GetSaveFileNamePreview function displays the SaveAs dialog box for choosing a file and lets the user preview (play) the file. When the name of an existing file is specified in the SaveAs dialog box, GetSaveFileNamePreview provides a small control in the dialog box to let the user preview the contents of the file. You can save the recorded data in a file selected with GetSaveFileNamePreview by using MCIWndSave.


Playback Enhancements

After you have configured your application to play multimedia data using an MCIWnd window, you can enhance and adjust the window’s appearance and behavior. This section describes how to perform the following tasks:

•	Specifying time formats

•	Adjusting speed, volume, and zoom

•	Providing controls for cropping and stretching images

•	Using MCIWnd palettes

•	Providing status updates

•	Using a multiple document interface


Specifying Time Formats

Multimedia data types typically can use time to identify significant positions within their content. Common time formats are milliseconds, tracks, and frames; other less common time formats, such as SMPTE (Society of Motion Picture and Television Engineers) 24, also exist. Time is the format and reference system for waveform-audio, MIDI, and CD audio data. Video supports time even though it is recorded as a sequence of frames (stream) that is typically played at a specific speed. Several macros are available for designating time format.

You can retrieve the current time format for a file or device by using the MCIWndGetTimeFormat macro. You can change the current time format to any other time format supported by a device by using the MCIWndSetTimeFormat macro. Or you can the set the time format to milliseconds or frames by using the MCIWndUseTime or MCIWndUseFrames macros.

Note  Noncontinuous formats, such as tracks and SMPTE, can cause the toolbar to behave erratically. For these time formats, you might want to turn off the toolbar by specifying the MCIWNDF_NOPLAYBAR window style when creating an MCIWnd window.


Adjusting Speed, Volume, and Zoom

The speed, volume, and zoom macros provide the functionality of the View, Volume, and Speed commands on the MCIWnd menu. The macros described in this section are generally used with video and other devices that display images during playback.

Some devices support multiple playback speed changes. You can set the playback speed for these devices by using the MCIWndSetSpeed macro. This macro defines the playback speed as 1000. Higher values indicate faster speeds. Lower values indicate slower speeds.

You can retrieve the current playback speed by using the MCIWndGetSpeed macro. This macro uses the same values and range as those used by MCIWndSetSpeed.

Some devices support volume changes. You can adjust or set the volume by using the MCIWndSetVolume macro. This macro defines the normal volume level as 1000. Higher values indicate louder volumes. Lower values indicate quieter volumes.

You can retrieve the current volume level by using the MCIWndGetVolume macro. This macro uses the same numerical values and range as those used by MCIWndSetVolume.

For devices that use a playback window, MCIWnd supports a zoom feature that sets the size of the playback image. You can set the playback image size by using the MCIWndSetZoom macro. The macro redefines the playback image size while maintaining a constant aspect ratio for the image. The zoom value is defined as a percentage of the original image size. Thus, 100 represents the original image size, 50 indicates the image shown is half its original size, and 200 indicates that the image shown is twice its original size.

You can retrieve the current zoom value by using the MCIWndGetZoom macro. This macro uses the same values and range as those used by MCIWndSetZoom.

Note  The standard MCI CD audio and waveform-audio drivers do not support volume or speed changes.


Providing Controls for Cropping and Stretching Images

MCIWnd allows you to crop and stretch images of a video clip. To understand these features, you need to understand the relationships between frame size, source rectangle, destination rectangle, and playback area.

A video clip consists of several frames, each containing one image. The frame size of a video clip is the size of the image in the current frame. Typically, a video clip has one frame size because all the images in the clip are the same size.

The source rectangle is a rectangular area that overlays the frames of a video clip. The source rectangle defines the portion of each frame that is displayed during playback. When a video clip is loaded with MCIWnd, the source rectangle is initialized with the same dimensions and position as the initial frame of the video clip.

The destination rectangle is a rectangular area that defines a virtual playback window. The destination rectangle receives the image data from the source rectangle for each frame of the video clip. When the source and destination rectangle dimensions are different, MCIWnd adjusts the image data horizontally and vertically as needed to fill the destination rectangle. When a video clip is loaded with MCIWnd, the destination rectangle is initialized with the same dimensions and position as the initial frame of the video clip.

The playback area is the portion of an MCIWnd window an application uses to display the video clip. The playback area is the client area of an MCIWnd window or the portion of the client area that excludes the MCIWnd toolbar. When a video clip is loaded with MCIWnd, the playback area is initialized with the same dimensions and position as the initial frame of the video clip.

You can crop a video clip by using the MCIWndGetSource and MCIWndPutSource macros to alter the source rectangle. Cropping an image determines only which portion of the frames are displayed during playback; it does not alter the content of the file being played. Before you crop an image, you can retrieve the current size of the source rectangle by using MCIWndGetSource. After the new size and location of the source rectangle are calculated, you can set the cropping boundaries of the source rectangle by using MCIWndPutSource.

You can stretch a video clip by using the MCIWndGetDest and MCIWndPutDest macros to alter the destination rectangle. When you stretch a video clip, you lengthen or shorten the frame size of a video clip vertically, horizontally, or in both directions. Before you stretch an image, you can retrieve the current size and location of the destination rectangle by using MCIWndGetDest. The MCIWndPutDest macro allows you to redefine the destination rectangle. Stretching can distort the image during playback, but it does not alter the content of the file being played.

If the size of the destination rectangle becomes larger than the playback area, you can specify which portion of the playback area will display the video clip by using MCIWndPutDest.

Note  The MCIWndPutDest macro does not change the size of the playback area. To stretch the MCIWnd window along with the destination rectangle, you need to know the current size of the MCIWnd window and issue new window dimensions based on the destination rectangle. You can retrieve the MCIWnd window dimensions by using the GetWindowRect function and resize the MCIWnd window by using the SetWindowPos function.


Using MCIWnd Palettes

Playing video clips with 8-bit color depth (256-color capacity) requires a palette to define the colors being used. Sometimes, the palette included with a video clip is not the most appropriate palette to use during playback. In this case, MCIWnd provides three ways to manage palettes for playback:

•	Retrieve a handle to the palette associated with an MCIWnd window by using the MCIWndGetPalette macro. The palette is not necessarily associated exclusively with the MCIWnd window. Other applications can access, and even invalidate, the palette handle. Consequently, your application should anticipate the global use of the palette and, when finished with the palette, should not free it.

•	Specify a new palette to use with the video clip associated with an MCIWnd window by using the MCIWndSetPalette macro.

•	Realize the palette associated with an MCIWnd window to the system palette by using the MCIWndRealize macro. This macro calls the RealizePalette function with the palette associated with the MCIWnd window. If your application message handlers for WM_PALETTECHANGED and WM_QUERYNEWPALETTE call only RealizePalette or MCIWndRealize, you must forward these messages to MCIWnd if you do not handle them yourself.

Note  When a video clip with 8-bit color depth is loaded into the MCIWnd window, the palette included with that clip replaces the palette associated with the MCIWnd window.


Providing Status Updates

MCIWnd uses timers to periodically update information in the window title bar and scroll bar, and to send notification messages to the parent window. One timer controls the update period of the active MCIWnd window, and a second timer controls the update period for MCIWnd windows that are inactive. Your application can use the MCIWnd timer macros to retrieve the current timer settings and to adjust the update periods.

You can set the update period used by the active window timer by using the MCIWndSetActiveTimer macro. This macro sets the period used by MCIWnd to update the trackbar, to update the playback position reported in the window title bar, and to notify the parent window that the media has changed. You can retrieve the current update period used by the active window timer by using the MCIWndGetActiveTimer macro. The default update period for the active window timer is 500 milliseconds.

You can set the update period used by the inactive window timer by using the MCIWndSetInactiveTimer macro. This macro sets the period used by MCIWnd to update the trackbar, to update the playback position reported in the window caption, and to notify the parent window that the media has changed. You can retrieve the current update period used by the inactive window timer by using the MCIWndGetInactiveTimer macro. The default update period for the inactive window timer is 2000 milliseconds.

Your application can simultaneously set the update period for both timers by using the MCIWndSetTimers macro. The storage for the value of the update period is limited to 16 bits. If a larger quantity for either update period is needed, set the timers individually.


Using a Multiple Document Interface

Applications that use a multiple document interface (MDI) might need to specify window styles that are not available through the MCIWndCreate function. For these applications, you can register and create an MCIWnd window by using the MCIWndRegisterClass function with the CreateWindowEx function. The MCIWndRegisterClass function registers the MCIWND_WINDOW_CLASS window class and then CreateWindowEx creates an instance of an MCIWnd window.


Error Messages and Notifications

MCIWnd uses MCI to control the devices that play and record multimedia data. In general, MCIWnd displays MCI errors in an error dialog box. An MCI error is generated whenever an MCI command fails. For example, if your application tries to resume paused playback by using the MCIWndResume macro and the current device does not support resume, an error is reported to the user.

MCIWnd allows you two choices for handling error messages:

•	You can prevent error messages from reaching the user. To prevent the display of MCI error messages, specify the MCIWNDF_NOERRORDLG window style when you create an instance of an MCIWnd window by using the MCIWndCreate or CreateWindowEx function.

•	You can redirect them to your application for display. To redirect MCI error messages to your application, specify the MCIWNDF_NOTIFYERROR window style when you create an instance of an MCIWnd window by using MCIWndCreate or CreateWindowEx.

When error notification is enabled, MCIWnd sends each notification message (MCIWNDM_NOTIFYERROR) to the main message handler of the parent of the MCIWnd window. Your application must have a message handler to process the notification messages it receives.

You can obtain a textual description of the most recent MCI error message by using the MCIWndGetError macro. This macro returns the text in an application-defined buffer. If the error string is longer than the buffer, MCIWnd truncates the string.

You can route all notifications to another window by using the MCIWndSetOwner macro.


Communicating with MCI Devices

The driver of each MCI device maintains a list of its current settings and capabilities, so it can issue an accurate response when it is queried for information.

When you want to communicate with an MCI device, you can use MCIWnd macros and functions. Many of the most common MCI commands and queries are defined as macros. However, if the task you want to perform is unavailable as a function or macro, you can send MCI commands directly to the device driver by using the MCIWndSendString macro or by using either the message form or string form of the MCI commands. Using the MCIWndSendString macro is equivalent to using the mciSendString function as follows:

mciSendString(sz, Null, 0, Null)

The parameters of MCIWndSendString include only the window handle and the string form of the command. To retrieve the information returned by a string command, use the MCIWndReturnString macro.

For more information about MCI, see MCI.

Note  You must exclude the device alias from the MCI command when you use MCIWndSendString. The MCIWnd library adds this alias when it sends the command to the MCI device.


Communication with MCI Devices

It is possible for each MCI device to use one of more of the following as identifiers:

•	a device identifier

•	a device name

•	an alias

•	the filename of the currently loaded content.

MCIWnd provides macros you can use to retrieve this information. You can then use this information to communicate through MCI directly with MCI devices associated with MCIWnd windows.

You can retrieve the identifier of the current MCI device by using the MCIWndGetDeviceID macro. The MCI device identifier is a numerical value that identifies the instance of the MCI device your application is using. Your application can use this identifier when communicating with an MCI device by using the mciSendCommand function.

To retrieve the name of the current MCI device, use the MCIWndGetDevice macro. The MCI device name is a null-terminated string that identifies the device type associated with an MCIWnd window. Your application can use this name when communicating with an MCI device by using mciSendCommand.

You can retrieve the alias of the current MCI device by using the MCIWndGetAlias macro. Your application can use this alias when communicating with an MCI device by using the mciSendString function.

Finally, you can retrieve the filename used by an MCI device by using the MCIWndGetFileName macro. The filename identifies the content currently associated with an MCIWnd window. Your application can use this filename when communicating with a MCI device by using mciSendCommand or mciSendString.


MCI Device Capabilities

MCIWnd includes the following macros to let you query MCI devices for their capabilities.

Macro	Description
MCIWndCanConfig	Determines whether a device has a configuration dialog box to support multiple configurations, such as the MCIAVI device.
MCIWndCanEject	Determines whether a device has a software-controlled eject function.
MCIWndCanPlay	Determines whether a device can play the existing content.
MCIWndCanRecord	Determines whether a device can record.
MCIWndCanSave	Determines whether a device can store data.
MCIWndCanWindow	Determines whether a device supports MCI window commands (such as window, put and where).
These macros return TRUE if the device supports the specific capability, or FALSE otherwise.


Using the MCIWnd Window Class

This section contains examples demonstrating how to perform the following tasks:

•	Creating an MCIWnd window

•	Automating playback for MCIWnd

•	Pausing and resuming playback

•	Limiting the playback scope

•	Recording with MCIWnd controls

•	Customizing the recording process

•	Cropping an image

•	Stretching an image

•	Stretching an image and window


Creating an MCIWnd Window

The MCIWndCreate function registers and creates an MCIWnd window. The window can be a parent, child, or pop-up window. The following example creates an MCIWnd window as a child window and lets the user control playback by providing access to the trackbar and the Play, Stop, and Menu buttons. The example specifies a handle of a parent window and specifies NULL for the window styles, so the default window styles of WS_CHILD, WS_BORDER, and WS_VISIBLE are used to create the MCIWnd window.

// Global variable and constants

// extern HINSTANCE g_hinst;       instance handle

// extern HWND g_hwndMCIWnd;       MCIWnd window handle

case WM_COMMAND:

    switch (wParam) {

    case IDM_CREATEMCIWND:

        g_hwndMCIWnd = MCIWndCreate(hwnd, g_hinst, NULL,
            "sample.avi");

        break;

    }

    break;

Note  You could also specify NULL for both the parent window handle and the window styles, in which case the default window styles would be WS_OVERLAPPED and WS_VISIBLE.


Automating Playback for MCIWnd

You can automate playback for MCIWnd by specifying certain window styles in the MCIWndCreate function. To play the device, the window needs a parent window to process notification messages, a playback area to play AVI files, and notification of device mode changes to identify when playback stops. The window does not need a toolbar. You can set these characteristics by specifying the appropriate styles in MCIWndCreate.

The following example uses menu commands to create an MCIWnd window to play content from several different types of devices. The MCIWndCreate function creates the MCIWnd window, and devices and files are loaded by using the MCIWndOpen macro in the device-specific commands. When a device finishes playing, you close the device by trapping the MCIWNDM_NOTIFYMODE message and issuing the MCIWndClose macro.

case WM_COMMAND:

    switch (wParam)

    {

        case IDM_CREATEMCIWND:

            dwMCIWndStyle = WS_CHILD |     // child window

                WS_VISIBLE |               // visible

                MCIWNDF_NOTIFYMODE |       // notifies of mode changes

                MCIWNDF_NOPLAYBAR;	         // hides toolbar

            g_hwndMCIWnd = MCIWndCreate(hwnd,

                g_hinst, dwMCIWndStyle, NULL);

            break;

        case IDM_PLAYCDA:

            LoadNGoMCIWnd(hwnd, "CDAudio");

            break;

        case IDM_PLAYWAVE:

            LoadNGoMCIWnd(hwnd, "SoundWave.WAV");

            break;

        case IDM_PLAYMIDI:

            LoadNGoMCIWnd(hwnd, "MIDIFile.MID");

            break;

        case IDM_PLAYAVI:

            LoadNGoMCIWnd(hwnd, "AVIFile.AVI");

            break;

        case IDM_EXIT:

            MCIWndDestroy(g_hwndMCIWnd);

            DestroyWindow(hwnd);

            break;

    }

    break;

case MCIWNDM_NOTIFYMODE:

    if (lParam == MCI_MODE_STOP)  // device stopped

    {

        MessageBox(hwnd,"","Closing Device",MB_OK);

        MCIWndClose(g_hwndMCIWnd);

    }

    break;

// Handle other messages here.

// LoadNGoMCIWnd - automatically loads and plays a multimedia device

//

// hwnd -  handle to the parent window

// lpstr - pointer to device or filename played by device

//

// Global variable

// extern HINSTANCE g_hwndMCIWnd;  instance handle to MCIWnd window

VOID LoadNGoMCIWnd(HWND hwnd, LPSTR lpstr)

{

    MessageBox(hwnd, lpstr, "Loading Device", MB_OK);

    MCIWndOpen(g_hwndMCIWnd, lpstr, NULL);   // new device in window

    MCIWndPlay(g_hwndMCIWnd);                // plays device

}


Pausing and Resuming Playback

You can interrupt playback of a device or file associated with an MCIWnd window by using the MCIWndPause macro. You can then restart playback by using the MCIWndResume macro. If the device does not support resume or if an error occurs, you can use the MCIWndPlay macro to restart playback.

The following example creates an MCIWnd window and plays an AVI file. Pause and resume menu commands are available to the user to interrupt and restart playback.

MCIWnd window styles are changed temporarily by using the MCIWndChangeStyles macro to inhibit an MCI error dialog box from being displayed if MCIWndResume fails.

case WM_COMMAND:

    switch (wParam)

    {

        case IDM_CREATEMCIWND:             // creates and plays clip

            g_hwndMCIWnd = MCIWndCreate(hwnd,

                g_hinst,

                WS_CHILD | WS_VISIBLE |    // standard styles

                MCIWNDF_NOPLAYBAR |        // hides toolbar

                MCIWNDF_NOTIFYMODE,        // notifies of mode changes

                "sample.avi");

            MCIWndPlay(g_hwndMCIWnd);

            break;

        case IDM_PAUSEMCIWND:              // pauses playback

            MCIWndPause(g_hwndMCIWnd);

            MessageBox(hwnd, "MCIWnd", "Pausing Playback", MB_OK);

            break;

        case IDM_RESUMEMCIWND:	       // resumes playback

            MCIWndChangeStyles(      // hides error dialog messages

                g_hwndMCIWnd,        // MCIWnd window

                MCIWNDF_NOERRORDLG,  // mask of style to change

                MCIWNDF_NOERRORDLG); // suppresses MCI error dialogs

            lResult = MCIWndResume(g_hwndMCIWnd);

            if(lResult){                   // device doesn't resume

                MessageBox(hwnd, "MCIWnd",

                    "Resume with Stop and Play", MB_OK);

                MCIWndStop(g_hwndMCIWnd);

                MCIWndPlay(g_hwndMCIWnd);

                MCIWndChangeStyles(        // resumes original styles

                    g_hwndMCIWnd,

                    MCIWNDF_NOERRORDLG,

                    NULL);

        }

        break;

    }

    break;

// Handle other messages here.


Limiting the Playback Scope

Controlling playback begins with the MCIWndPlay macro, which plays the content or file associated with an MCIWnd window from the current playback position to the end of the content. If you want to limit playback to a specific portion of the content or file, you can choose from the other playback MCIWnd macros: MCIWndPlayFrom, MCIWndPlayTo, and MCIWndPlayFromTo.

You also need to set an appropriate time format. The time format determines whether the content is measured in frames, milliseconds, tracks, or some other units.

The following example creates an MCIWnd window and provides menu commands to play the last third, first third, or middle third of the content. These menu commands use MCIWndPlayFrom, MCIWndPlayTo, and MCIWndPlayFromTo to play the content segments. The example also uses the MCIWndGetStart and MCIWndGetEnd macros to identify the beginning and end of the content, and it uses the MCIWndHome macro to move the playback position to the beginning of the content.

The MCIWndCreate function uses the WS_CAPTION and MCIWNDF_SHOWALL styles in addition to the standard window styles to display the filename, mode, and current playback position in the title bar of the MCIWnd window.

case WM_COMMAND:

    switch (wParam)

    {

        case IDM_CREATEMCIWND:

            g_hwndMCIWnd = MCIWndCreate(hwnd,

                g_hinst,

                WS_CHILD | WS_VISIBLE | WS_CAPTION |

                MCIWNDF_SHOWALL,

                "sample.avi");

            break;

        case IDM_PLAYFROM:                // plays last third of clip

            MCIWndUseTime(g_hwndMCIWnd);  // millisecond format

        // Get media start and end positions.

            lStart = MCIWndGetStart(g_hwndMCIWnd);

            lEnd = MCIWndGetEnd(g_hwndMCIWnd);

        // Determine playback end position.

            lPlayStart = 2 * (lEnd - lStart) / 3 + lStart;

            MCIWndPlayFrom(g_hwndMCIWnd, lPlayStart);

            break;

        case IDM_PLAYTO:                  // plays first third of clip

            MCIWndUseTime(g_hwndMCIWnd);  // millisecond format

        // Get media start and end positions.

            lStart = MCIWndGetStart(g_hwndMCIWnd);

            lEnd = MCIWndGetEnd(g_hwndMCIWnd);

        // Determine playback start position.

            lPlayEnd = (lEnd - lStart) / 3 + lStart;

            MCIWndHome(g_hwndMCIWnd);

            MCIWndPlayTo(g_hwndMCIWnd, lPlayEnd);

            break;

        case IDM_PLAYSOME:               // plays middle third of clip

            MCIWndUseTime(g_hwndMCIWnd); // millisecond format

        // Get media start and end positions.

            lStart = MCIWndGetStart(g_hwndMCIWnd);

            lEnd = MCIWndGetEnd(g_hwndMCIWnd);

        // Determine playback start and end positions.

            lPlayStart = (lEnd - lStart) / 3 + lStart;
            lPlayEnd = 2 * (lEnd - lStart) / 3 + lStart;

            MCIWndPlayFromTo(g_hwndMCIWnd, lPlayStart, lPlayEnd);

            break;

    // Handle other commands here.

    }


Recording with MCIWnd Controls

The following example records waveform audio using the built-in controls of the MCIWnd window. The example creates an MCIWnd window by using the MCIWNDF_RECORD window style with the MCIWndCreate function to add a Record button to the toolbar. The MCIWndNew macro indicates a new file is associated with the MCIWnd window and that a waveform-audio device will provide its content. A second menu command, IDM_SAVEMCIWND, lets the user save the recording and select a filename by using the MCIWndSaveDialog macro.

case WM_COMMAND:

    switch (wParam) {

    case IDM_CREATEMCIWND:

        g_hwndMCIWnd = MCIWndCreate(hwnd, g_hinst,

            WS_VISIBLE | MCIWNDF_RECORD, NULL);

        MCIWndNew(g_hwndMCIWnd, "waveaudio");

        break;

    case IDM_SAVEMCIWND:

        MCIWndSaveDialog(g_hwndMCIWnd);

        break;

    }


Customizing the Recording Process

You can customize the recording process, taking complete control of most everything — from creating the MCIWnd window to saving the recorded information in a file. The following example queries the MCI device for recording and saving capabilities, and includes menu commands to record at the beginning or end of the content.

The following example uses the MCIWndCreate function to create a new window and allows you to specify an existing file to store the recorded data and the MCIWndNew macro to associate a new file with the window. Alternatively, you can use the MCIWndOpen or MCIWndOpenDialog macro to specify a file.

The example uses the MCIWndCanRecord macro to verify that the device can record and the MCIWndCanSave macro to verify that the device save information. The example sets the current playback position by using the MCIWndHome and MCIWndEnd macros. The example starts recording by using the MCIWndRecord macro. After the information is recorded, the example saves it by using the MCIWndSaveDialog macro.

case WM_COMMAND:

    switch (wParam)

    {

        case IDM_CREATEMCIWND:

            g_hwndMCIWnd = MCIWndCreate( hwnd, g_hinst,

                WS_VISIBLE | WS_CHILD |

                MCIWNDF_RECORD,                   // add Record button

                NULL );

            MCIWndNew(g_hwndMCIWnd, "waveaudio"); // new file

            if( MCIWndCanRecord(g_hwndMCIWnd) )

            {

                MessageBox( hwnd,

                "Press the red button on the toolbar to record.",

                "MCIWnd Record",

                MB_OK );

            }

            else

            {

                MessageBox( hwnd,

                    "This device doesn't record.",

                    "MCIWnd Record",

                    MB_OK );

            }

            break;

        case IDM_RECORDATSTART:

            if( MCIWndCanRecord(g_hwndMCIWnd) )

            {

                MCIWndHome(g_hwndMCIWnd);

                MCIWndRecord(g_hwndMCIWnd);

            }

            else

            {

                MessageBox( hwnd,

                    "This device doesn't record.",

                    "MCIWnd Record",

                    MB_OK);

            }

            break;

        case IDM_RECORDATEND:

            if( MCIWndCanRecord(g_hwndMCIWnd) )

            {

                MCIWndEnd(g_hwndMCIWnd);

                MCIWndRecord(g_hwndMCIWnd);

            }

            else

            {

                MessageBox( hwnd,

                    "This device doesn't record.",

                    "MCIWnd Record",

                    MB_OK);

            }

            break;

        case IDM_SAVEMCIWND:

            if( MCIWndCanSave(g_hwndMCIWnd) )

                MCIWndSaveDialog(g_hwndMCIWnd);

    }

    break;

    // Handle other messages here.


Cropping an Image

The following example creates an MCIWnd window and loads an AVI file. The window includes a crop command in the menu, which crops one-quarter of the height or width from each of the four sides of the frame. The example retrieves the current (initial) dimensions of the source rectangle by using the MCIWndGetSource macro. The modified source rectangle is half the original height and width and is centered in the original frame. The call to the MCIWndPutSource macro redefines the coordinates of the source rectangle.

// extern RECT rSource, rDest;

case WM_COMMAND:

    switch (wParam)

    {

        case IDM_CREATEMCIWND:

            g_hwndMCIWnd = MCIWndCreate( hwnd,

                g_hinst,

                WS_CHILD | WS_VISIBLE,

                "sample.avi" );

            break;

        case IDM_CROPIMAGE:                          // crops image

            MCIWndGetSource(g_hwndMCIWnd, &rSource); // source rectangle

            rDest.left = rSource.left +              // new boundaries

                ((rSource.right - rSource.left) / 4);

            rDest.right = rSource.right -

                ((rSource.right - rSource.left) / 4);

            rDest.top = rSource.top +

                ((rSource.bottom - rSource.top) / 4);

            rDest.bottom = rSource.bottom -

                ((rSource.bottom - rSource.top) / 4);

            MCIWndPutSource(g_hwndMCIWnd, &rDest);   // new source rectangle

    }

    break;

    // Handle other messages here.


Stretching an Image

The following example stretches the images of a video clip. It increases the dimensions of the destination rectangle by using the MCIWndPutDest macro. The size of the playback area remains unchanged, so the result is a distorted, magnified image. The examples uses the MCIWndPutDest function to reposition the destination rectangle with respect to the playback area, providing a way to view different portions of the stretched image.

extern RECT rCurrent, rDest;

case WM_COMMAND:

   switch (wParam)

   {

       case IDM_CREATEMCIWND:

           g_hwndMCIWnd = MCIWndCreate(hwnd,

               g_hinst,

               WS_CHILD | WS_VISIBLE,

               "sample.avi");

           break;

       case  IDM_STRETCHIMAGE:      // stretch destination RECT 3:2,

           MCIWndGetDest(g_hwndMCIWnd, &rCurrent); // destination RECT

           rDest.top = rCurrent.top;               // new boundaries

           rDest.right = rCurrent.right;

           rDest.left = rCurrent.left +

               ((rCurrent.left - rCurrent.right) * 3);

           rDest.bottom = rCurrent.top +

               ((rCurrent.bottom - rCurrent.top) * 2);

           MCIWndPutDest(g_hwndMCIWnd, &rDest); // new destination

           break;

       case IDM_MOVEDOWN:           // move toward bottom of image

           MCIWndGetDest(g_hwndMCIWnd, &rCurrent); // destination RECT

           rCurrent.top -= 100;                    // new boundaries

           rCurrent.bottom -= 100;

           MCIWndPutDest(g_hwndMCIWnd, &rCurrent); // new destination

           break;

       case IDM_MOVEUP:             // move toward top of image

           MCIWndGetDest(g_hwndMCIWnd, &rCurrent); // destination RECT

           rCurrent.top += 100;                    // new boundaries

           rCurrent.bottom += 100;

           MCIWndPutDest(g_hwndMCIWnd, &rCurrent); // new destination

           break;

       case IDM_MOVELEFT:           // move toward left edge of image

           MCIWndGetDest(g_hwndMCIWnd, &rCurrent); // destination RECT

           rCurrent.right += 100;                  // new boundaries

           rCurrent.left += 100;

           MCIWndPutDest(g_hwndMCIWnd, &rCurrent); // new destination

           break;

       case  IDM_MOVERIGHT:         // move toward right edge of image

           MCIWndGetDest(g_hwndMCIWnd, &rCurrent); // destination RECT

           rCurrent.right -= 100;                  // new boundaries

           rCurrent.left -= 100;

           MCIWndPutDest(g_hwndMCIWnd, &rCurrent); // new destination

           break;

   }

   break;

   // Handle other messages here.


Stretching an Image and Window

The following example stretches the images of a video clip and changes the aspect ratio of the displayed frames. The frames displayed in the MCIWnd window are twice the height and three times the width of the original frame. The MCIWndGetDest and MCIWndPutDest macros retrieve and redefine the destination rectangle coordinates. The GetWindowRect and SetWindowPos functions manage changes to the MCIWnd window dimensions.

// extern RECT rCurrent, rDest;

case WM_COMMAND:

   switch (wParam)

   {

       case IDM_CREATEMCIWND:

           g_hwndMCIWnd = MCIWndCreate(hwnd,

           g_hinst,

           WS_CHILD | WS_VISIBLE,

          "sample.avi");

           break;

       case IDM_RESIZEWINDOW: // destination RECT and playback area

           GetWindowRect(g_hwndMCIWnd, &rWin);     // window size

           MCIWndGetDest(g_hwndMCIWnd, &rCurrent); // destination RECT

           rDest.top = rCurrent.top;               // new boundaries

           rDest.right = rCurrent.right;

           rDest.left = rCurrent.left +

               ((rCurrent.left - rCurrent.right) * 3);

           rDest.bottom = rCurrent.top +

               ((rCurrent.bottom - rCurrent.top) * 2);

           MCIWndPutDest(g_hwndMCIWnd, &rDest); // new RECT

           SetWindowPos(g_hwndMCIWnd,           // window to resize

               NULL,                          // z-order: don't care

               0, 0,                          // position: don't care

               rDest.right - rDest.left,      // width

               (rWin.bottom - rWin.top +           // height (window -

               (rCurrent.bottom - rCurrent.top) +  //  original RECT +

               (rDest.bottom - rDest.top)),        //  new RECT

               SWP_NOMOVE | SWP_NOZORDER | SWP_NOACTIVATE);

           break;

   }

   break;

   // Handle other messages here.


MCIWnd Reference

This section describes the functions, messages, and macros associated with the MCIWnd window class. These elements are grouped as follows.

Window Management

MCIWndChangeStyles
MCIWndCreate
MCIWndGetStyles
MCIWndRegisterClass

File and Device Management

MCIWndClose
MCIWndDestroy
MCIWndEject
MCIWndNew
MCIWndOpen
MCIWndOpenDialog
MCIWndSave
MCIWndSaveDialog

Playback Options

MCIWndGetRepeat
MCIWndPlay
MCIWndPlayFrom
MCIWndPlayFromTo
MCIWndPlayReverse
MCIWndPlayTo
MCIWndSetRepeat

Recording

MCIWndRecord

Positioning

MCIWndEnd
MCIWndGetEnd
MCIWndGetLength
MCIWndGetPosition
MCIWndGetPositionString
MCIWndGetStart
MCIWndHome
MCIWndSeek
MCIWndStep

Pause and Resume Playback

MCIWndGetRepeat
MCIWndPlay
MCIWndPlayFrom
MCIWndPlayFromTo
MCIWndPlayReverse
MCIWndPlayTo
MCIWndSetRepeat

Performance Tuning

MCIWndGetSpeed
MCIWndGetVolume
MCIWndGetZoom
MCIWndSetSpeed
MCIWndSetVolume
MCIWndSetZoom

Image and Palette Adjustments

MCIWndGetDest
MCIWndGetPalette
MCIWndGetSource
MCIWndPutDest
MCIWndPutSource
MCIWndRealize
MCIWndSetPalette

Event and Error Notification

MCIWndGetError
MCIWNDM_NOTIFYERROR
MCIWNDM_NOTIFYMEDIA
MCIWNDM_NOTIFYMODE
MCIWNDM_NOTIFYPOS
MCIWNDM_NOTIFYSIZE

Time Formats

MCIWndGetTimeFormat
MCIWndSetTimeFormat
MCIWndUseFrames
MCIWndUseTime
MCIWndValidateMedia

Status Updates

MCIWndGetActiveTimer
MCIWndGetInactiveTimer
MCIWndSetActiveTimer
MCIWndSetInactiveTimer
MCIWndSetTimers

Device Capabilities

MCIWndCanConfig
MCIWndCanEject
MCIWndCanPlay
MCIWndCanRecord
MCIWndCanSave
MCIWndCanWindow

MCI Device Settings

MCIWndGetAlias
MCIWndGetDevice
MCIWndGetDeviceID
MCIWndGetFileName
MCIWndGetMode

MCI Command-String Interface

MCIWndReturnString
MCIWndSendString


MCIWnd Functions

The following functions are used with MCIWnd.

GetOpenFileNamePreview
GetSaveFileNamePreview
MCIWndCreate
MCIWndRegisterClass


MCIWnd Messages

The following messages are used with MCIWnd.

MCIWNDM_CAN_CONFIG
MCIWNDM_CAN_EJECT
MCIWNDM_CAN_PLAY
MCIWNDM_CAN_RECORD
MCIWNDM_CAN_SAVE
MCIWNDM_CAN_WINDOW
MCIWNDM_CHANGESTYLES
MCIWNDM_EJECT
MCIWNDM_GETACTIVETIMER
MCIWNDM_GETALIAS
MCIWNDM_GET_DEST
MCIWNDM_GETDEVICE
MCIWNDM_GETDEVICEID
MCIWNDM_GETEND
MCIWNDM_GETERROR
MCIWNDM_GETFILENAME
MCIWNDM_GETINACTIVETIMER
MCIWNDM_GETLENGTH
MCIWNDM_GETMODE
MCIWNDM_GETPALETTE
MCIWNDM_GETPOSITION
MCIWNDM_GETREPEAT
MCIWNDM_GET_SOURCE
MCIWNDM_GETSPEED
MCIWNDM_GETSTART
MCIWNDM_GETSTYLES
MCIWNDM_GETTIMEFORMAT
MCIWNDM_GETVOLUME
MCIWNDM_GETZOOM
MCIWNDM_NEW
MCIWNDM_NOTIFYERROR
MCIWNDM_NOTIFYMEDIA
MCIWNDM_NOTIFYMODE
MCIWNDM_NOTIFYPOS
MCIWNDM_NOTIFYSIZE
MCIWNDM_OPEN
MCIWNDM_OPENINTERFACE
MCIWNDM_PLAYFROM
MCIWNDM_PLAYREVERSE
MCIWNDM_PLAYTO
MCIWNDM_PUT_DEST
MCIWNDM_PUT_SOURCE
MCIWNDM_REALIZE
MCIWNDM_RETURNSTRING
MCIWNDM_SENDSTRING
MCIWNDM_SETACTIVETIMER
MCIWNDM_SETINACTIVETIMER
MCIWNDM_SETOWNER
MCIWNDM_SETPALETTE
MCIWNDM_SETREPEAT
MCIWNDM_SETSPEED
MCIWNDM_SETTIMEFORMAT
MCIWNDM_SETTIMERS
MCIWNDM_SETVOLUME
MCIWNDM_SETZOOM
MCIWNDM_VALIDATEMEDIA


MCIWnd Macros

The following macros are used with MCIWnd.

MCIWndCanConfig
MCIWndCanEject
MCIWndCanPlay
MCIWndCanRecord
MCIWndCanSave
MCIWndCanWindow
MCIWndChangeStyles
MCIWndClose
MCIWndDestroy
MCIWndEject
MCIWndEnd
MCIWndGetActiveTimer
MCIWndGetAlias
MCIWndGetDest
MCIWndGetDevice
MCIWndGetDeviceID
MCIWndGetEnd
MCIWndGetError
MCIWndGetFileName
MCIWndGetInactiveTimer
MCIWndGetLength
MCIWndGetMode
MCIWndGetPalette
MCIWndGetPosition
MCIWndGetPositionString
MCIWndGetRepeat
MCIWndGetSource
MCIWndGetSpeed
MCIWndGetStart
MCIWndGetStyles
MCIWndGetTimeFormat
MCIWndGetVolume
MCIWndGetZoom
MCIWndHome
MCIWndNew
MCIWndOpen
MCIWndOpenDialog
MCIWndOpenInterface
MCIWndPause
MCIWndPlay
MCIWndPlayFrom
MCIWndPlayFromTo
MCIWndPlayReverse
MCIWndPlayTo
MCIWndPutDest
MCIWndPutSource
MCIWndRealize
MCIWndRecord
MCIWndResume
MCIWndReturnString
MCIWndSave
MCIWndSaveDialog
MCIWndSeek
MCIWndSendString
MCIWndSetActiveTimer
MCIWndSetInactiveTimer
MCIWndSetOwner
MCIWndSetPalette
MCIWndSetRepeat
MCIWndSetSpeed
MCIWndSetTimeFormat
MCIWndSetTimers
MCIWndSetVolume
MCIWndSetZoom
MCIWndStep
MCIWndStop
MCIWndUseFrames
MCIWndUseTime
MCIWndValidateMedia


break

The break command specifies a key to abort a command that was invoked using the “wait” flag. This command is an MCI system command; it is interpreted directly by MCI.

wsprintf(lpstrCommand, "break %s %s %s", lpszDeviceID, lpszVirtKey,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszVirtKey

One of the following flags:

on virtual key code	Specifies the key that aborts a command that was started using the “wait” flag.
off	Disables the current break key.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

When the break key is enabled and the user presses the key identified by the virtual-key code specified in the lpsVirtKey parameter, the device returns control to the application. If possible, the command continues execution.

The following command sets F2 as the break key for the “mysound” device:

break mysound on 113


capability

The capability command requests information about a particular capability of a device. All MCI devices recognize this command.

wsprintf(lpstrCommand, "capability %s %s %s", lpszDeviceID, lpszRequest,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszRequest

Flag that identifies a device capability. The following table lists device types that recognize the capability command and the flags used by each type:

cdaudio	can eject can play can record can save compound device	device type has audio has video uses files
digitalvideo	can eject can freeze can lock can play can record can reverse can save can stretch can stretch input can test	compound device device type has audio has still has video maximum play rate minimum play rate uses files uses palettes windows
overlay	can eject can freeze can play can record can save can stretch	compound device device type has audio has video uses files windows
sequencer	can eject can play can record can save compound device	device type has audio has video uses files
vcr	can detect length can eject can freeze can monitor sources can play can preroll can preview can record can reverse can save can test	clock increment rate compound device device type has audio has clock has timecode has video number of marks seek accuracy uses files
videodisc	can eject can play can record can reverse can save CAV CLV compound device	device type fast play rate has audio has video normal play rate slow play rate uses files
waveaudio	can eject can play can record can save compound device device type	has audio has video inputs outputs uses files
The following table lists the flags that can be specified in the lpszRequest parameter and their meanings:

can detect length	Returns TRUE if the device can detect the length of the media.
can eject	Returns TRUE if the device can eject the media.
can freeze	Returns TRUE if the device can freeze data in the frame buffer.
can lock	Returns TRUE if the device can lock data.
can monitor sources	Returns TRUE if the device can pass an input (source) to the monitored output, independent of the current input selection.
can play	Returns TRUE if the device can play.
can preroll	Returns TRUE if the device supports the “preroll” flag with the cue command.
can preview	Returns TRUE if the device supports previews.
can record	Returns TRUE if the device supports recording.
can reverse	Returns TRUE if the device can play in reverse.
can save	Returns TRUE if the device can save data.
can stretch	Returns TRUE if the device can stretch frames to fill a given display rectangle.
can stretch input	Returns TRUE if the device can resize an image in the process of digitizing it into the frame buffer.
can test	Returns TRUE if the device recognizes the test keyword.
cav	When combined with other items, this flag specifies that the return information applies to CAV format videodiscs. This is the default if no videodisc is inserted.
clock increment rate	Returns the number of subdivisions the external clock supports per second. If the external clock is a millisecond clock, the return value is 1000. If the return value is 0, no clock is supported.
clv	When combined with other items, this flag specifies that the return information applies to CLV format videodiscs.
compound device	Returns TRUE if the device supports an element name (filename).
device type	Returns a device type name, which can be one of the following: cdaudio dat digitalvideo other overlay scanner sequencer vcr videodisc waveaudio
fast play rate	Returns the fast play rate in frames per second, or zero if the device cannot play fast.
has audio	Returns TRUE if the device supports audio playback.
has clock	Returns TRUE if the device has a clock.
has still	Returns TRUE if the device treats files with a single image more efficiently than motion video files.
has timecode	Returns TRUE if the device is capable of supporting timecode, or if it is unknown.
has video	Returns TRUE if the device supports video.
inputs	Returns the total number of input devices.
maximum play rate	Returns the maximum play rate, in frames per second, for the device.
minimum play rate	Returns the minimum play rate, in frames per second, for the device.
normal play rate	Returns the normal play rate, in frames per second, for the device.
number of marks	Returns the maximum number of marks that can be used; zero indicates that marks are unsupported.
outputs	Returns the total number of output devices.
seek accuracy	Returns the expected accuracy of a search in frames; 0 indicates that the device is frame accurate, 1 indicates that the device expects to be within one frame of the indicated seek position, and so on.
slow play rate	Returns the slow play rate in frames per second, or zero if the device cannot play slowly.
uses files	Returns TRUE if the data storage used by a compound device is a file.
uses palettes	Returns TRUE if the device uses palettes.
windows	Returns the number of simultaneous display windows the device can support.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns information in the lpstrReturnString parameter of the mciSendString function. The information is dependent on the request type.

Remarks

The following command returns the device type of the “mysound” device:

capability mysound device type

See Also

cue, mciSendString


capture

The capture command copies the contents of the frame buffer and stores it in the specified file. Digital-video devices recognize this command.

wsprintf(lpstrCommand, "capture %s %s %s", lpszDeviceID, lpszCapture,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszCapture

One or more of the following flags:

as pathname	Specifies the destination path and filename for the captured image. This flag is required.
at rectangle	Specifies the rectangular region within the frame buffer that the device crops and saves to disk. If omitted, the cropped region defaults to the rectangle specified or defaulted on a previous put “source” command for this device instance.
lpszFlags

Can be “wait”, “notify”, “test”, or a combination of these. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

This command might fail if the device is currently playing motion video or executing some other resource-intensive operation. If the frame buffer is being updated in real time, the updating momentarily pauses so that a complete image is captured. If the device pauses the updating, there might be a visual or audible effect. If the file format, compression algorithm, and quality levels have not been set, their defaults are used.

See Also

put


close

The close command closes the device or file and any associated resources. MCI unloads a device when all instances of the device or all files are closed. All MCI devices recognize this command.

wsprintf(lpstrCommand, "close %s %s", lpszDeviceID, lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszFlags

Can be “wait”, “notify”, or both. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

To close all devices opened by your application, specify the “all” device identifier for the lpszDeviceID parameter.

The following command closes the “mysound” device:

close mysound


configure

The configure command displays a dialog box used to configure the device. Digital-video devices recognize this command.

wsprintf(lpstrCommand, "configure %s %s", lpszDeviceID, lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszFlags

Can be “wait”, “notify”, or  “test”. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.


copy

The copy command copies data to the clipboard. Digital-video devices recognize this command.

wsprintf(lpstrCommand, "copy %s %s %s", lpszDeviceID, lpszItem,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszItem

One of the following flags identifying the item to copy:

at rectangle	Specifies the portion of each frame that will be copied. If omitted, the default setting is the entire frame.
audio stream stream	Specifies the audio stream in the workspace affected by the command. If you use this flag and also want to copy video, you must also use the “video stream” flag. (If neither flag is specified, all audio and video streams are copied.)
from position	Specifies the start of the range copied. If omitted, the default setting is the current position.
to position	Specifies the end of the range copied. The audio and video data copied are exclusive of this position. If omitted, the default setting is the end of the workspace.
video stream stream	Specifies the video stream in the workspace affected by the command. If you use this flag and also want to copy audio, you must also use the “audio stream” flag. (If neither flag is specified, all audio and video streams are copied.)
lpszFlags

Can be “wait”, “notify”, “test”, or a combination of these. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.


cue

The cue command prepares for playing or recording. Digital-video, VCR, and waveform-audio devices recognize this command.

wsprintf(lpstrCommand, "cue %s %s %s", lpszDeviceID, lpszInOutTo,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszInOutTo

Flag that prepares a device for playing or recording. The following table lists device types that recognize the cue command and the flags used by each type:

digitalvideo	input noshow	output to position
vcr	from position input output	preroll reverse to position
waveaudio	input	output
The following table lists the flags that can be specified in the lpszInOutTo parameter and their meanings:

from position	Indicates where to start.
input	Prepares for recording. For digital-video devices, this flag can be omitted if the current presentation source is already the external input.
noshow	Prepares for playing a frame without displaying it. When this flag is specified, the display continues to show the image in the frame buffer even though its corresponding frame is not the current position. A subsequent cue command without this flag and without the “to” flag displays the current frame.
output	Prepares for playing. If neither “input” nor “output” is specified, the default setting is “output”.
preroll	Moves the preroll distance from the in-point. The in-point is the current position, or the position specified by the “from” flag.
reverse	Indicates play direction is in reverse (backward).
to position	Moves the workspace to the specified position. For VCR devices, this flag indicates where to stop.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

Although it is not necessary, issuing the cue command before playing or recording on some devices might reduce the delay before the device starts the action.

This command fails if playing or recording is in progress or if the device is paused.

When cueing for playback (using cue “output”), issuing the play command with the “from”, “to”, or “reverse” flag cancels the cue command.

When cueing for recording (using cue “input”), issuing the record command with the “from”, “to”, or “initialize” flag cancels the cue command.

The following command prepares the “mysound” device for recording:

cue mysound input

See Also

play, record


cut

The cut command removes data from the workspace and copies it to the clipboard. Digital-video devices recognize this command.

wsprintf(lpstrCommand, "cut %s %s %s", lpszDeviceID, lpszItem,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszItem

One of the following flags identifying the item to cut:

at rectangle	Specifies the portion of each frame cut. If omitted, it defaults to the entire frame. When this item is specified, frames are not deleted. Instead the area inside the rectangle becomes black.
audio stream stream	Specifies the audio stream in the workspace affected by the command. If you use this flag and also want to cut video, you must also use the “video stream” flag. (If neither flag is specified, all audio and video streams are cut.)
from position	Specifies the start of the range cut. If omitted, it defaults to the current position.
to position	Specifies the end of the range cut. The audio and video data cut are exclusive of this position. If omitted it defaults to the end of the workspace.
video stream stream	Specifies the video stream in the workspace affected by the command. If you use this flag and also want to cut audio, you must also use the “audio stream” flag. (If neither flag is specified, all audio and video streams are cut.)
lpszFlags

Can be “wait”, “notify”, “test”, or a combination of these. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The change becomes permanent only when the data is explicitly saved; however, playback acts as if the data has been removed.


delete

The delete command deletes a data segment from a file. Digital-video and waveform-audio devices recognize this command.

wsprintf(lpstrCommand, "delete %s %s %s", lpszDeviceID, lpszPosition,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszPosition

Flag that identifies a data segment to delete. The following table lists device types that recognize the delete command and the flags used by each type:

digitalvideo	at rectangle audio stream stream from position	to position video stream stream
waveaudio	from position	to position
The following table lists the flags that can be specified in the lpszPosition parameter and their meanings:

at rectangle	Specifies the portion of each frame deleted. If omitted, it defaults to the entire frame. When this item is specified, frames are not deleted. Instead the area inside the rectangle becomes black.
audio stream stream	Specifies the audio stream in the workspace affected by the command. If you use this flag and also want to delete video, you must also use the “video stream” flag. (If neither flag is specified, all audio and video streams are deleted.)
from position	Specifies the position at which deletion begins. If this flag is omitted, the deletion begins at the current position.
to position	Specifies the position at which deletion ends. If this flag is omitted, the deletion continues to the end of the content or workspace.
video stream stream	Specifies the video stream in the workspace affected by the command. If you use this flag and also want to delete audio, you must also use “audio stream” flag. (If neither flag is specified, all audio and video streams are deleted.)
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

Before issuing any commands that use position values, you should set the desired time format by using the set command.

The following command deletes the waveform-audio data from 1 millisecond through 900 milliseconds (assuming the time format is set to milliseconds):

delete mysound from 1 to 900

See Also

set


escape

The escape command sends device-specific information to a device. Videodisc devices recognize this command.

wsprintf(lpstrCommand, "escape %s %s %s", lpszDeviceID, lpszEscape,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszEscape

Custom information to send to the device.

lpszFlags

Can be “wait”, “notify”, or both. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following command sends the escape string “SA” to the videodisc device:

escape videodisc SA


freeze

The freeze command freezes video input or video output on a VCR or disables video acquisition to the frame buffer. Digital-video, video-overlay, and VCR devices recognize this command.

wsprintf(lpstrCommand, "freeze %s %s %s", lpszDeviceID, lpszFreezeFlags,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszFreezeFlags

Flag that identifies what to freeze. The following table lists device types that recognize the freeze command and the flags used by each type:

digitalvideo	at rectangle	outside
overlay	at rectangle
vcr	field frame	input output
The following table lists the flags that can be specified in the lpszFreezeFlags parameter and their meanings:

at rectangle	Specifies the region that will be frozen. For video-overlay devices, this region will have video acquisition disabled. For digital-video devices, the pixels within the rectangle will have their lock mask bit turned on (unless the “outside” flag is specified). The rectangle is relative to the video buffer origin and is specified as X1 Y1 X2 Y2. The coordinates X1 Y1 specify the upper left corner of the rectangle, and the coordinates X2 Y2 specify the width and height.
field	Freezes the first field. Field is assumed by default (if neither frame nor field is specified).
frame	Freezes the entire frame, displaying both fields.
input	Freezes the current frame of the input image, whether it is paused or running.
output	Freezes the current frame of the output from the VCR. If the VCR is playing when freeze is issued, the current frame is frozen and the VCR is paused. If the VCR is paused when this command is issued, the current frame is frozen. The frozen image remains on the output device until an unfreeze command is issued. If neither “input” nor “output” is specified, “output” is assumed.
outside	Indicates that the area outside the region specified using the “at” flag is frozen.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

When used with VCR devices, this command is intended for frame-grabbing cards.

To specify irregular acquisition regions with the “at” flag, use a series of freeze and unfreeze commands. Some video-overlay devices limit the complexity of the acquisition region.

This command is supported only if a call to the capability command with the “can freeze” flag returns TRUE.

The following command disables video acquisition in a 100-pixel square at the upper left corner of the video buffer:

freeze vboard at 0 0 100 100

See Also

capability, unfreeze


index

The index command controls a VCR’s on-screen display. VCR devices recognize this command.

wsprintf(lpstrCommand, "index %s %s %s", lpszDeviceID, lpszIndex,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszIndex

One of the following flags:

off	Turns off the on-screen display.
on	Turns on the on-screen display. The item to be displayed is specified by the “index” flag of the set command.
lpszFlags

Can be “wait”, “notify”, or “test”. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

See Also

set


info

The info command retrieves a hardware description from a device. All MCI devices recognize this command.

wsprintf(lpstrCommand, "info %s %s %s", lpszDeviceID, lpszInfoType,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszInfoType

Flag that identifies the type of information required. The following table lists device types that recognize the info command and the flags used by each type:

cdaudio	info identity info upc	product
digitalvideo	audio algorithm audio quality file product still algorithm still quality	usage version video algorithm video quality window text
overlay	file product	window text
sequencer	copyright file	name product
vcr	product	version
videodisc	product
waveaudio	file input	output product
The following table lists the flags that can be specified in the lpszInfoType parameter and their meanings:

audio algorithm	Returns the name of the current audio compression algorithm.
audio quality	Returns the name for the current audio quality descriptor. This might return “unknown” if the application has set parameters to specific values that do not correspond to defined qualities.
copyright	Retrieves the MIDI file copyright notice from the copyright meta event.
file	Retrieves the name of the file used by the compound device. If the device is opened without a file and the load command has not been used, a null string is returned.
info identity	Produces a unique identifier for the audio CD currently loaded in the player being queried.
info upc	Produces the Universal Product Code (UPC) that is encoded on an audio CD. The UPC is a string of digits. It might not be available for all CDs.
input	Retrieves the description of the current input device. Returns “none” if an input device is not set.
name	Retrieves the sequence name from the sequence/track name meta event.
output	Retrieves the description of the current output device. Returns “none” if an output device is not set.
product	Retrieves a description of the device. This information often includes the product name and model. The string length will be 31 characters or fewer.
still algorithm	Returns the name of the current still image compression algorithm.
still quality	Returns the name for the current still image quality descriptor. This might return “unknown” if the application has set parameters to specific values that do not correspond to defined qualities.
usage	Returns a string describing usage restrictions that might be imposed by the owner of the visual or audio data in the workspace.
version	Returns the release level of the device driver and hardware.
video algorithm	Returns the name of the current video compression algorithm.
video quality	Returns the name for the current video quality descriptor. This might return “unknown” if the application has set parameters to specific values that do not correspond to defined qualities.
window text	Retrieves the caption of the window used by the device.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following command retrieves a description of the hardware associated with the “mysound” device:

info mysound product

See Also

load


list

The list command determines the number and types of video and audio inputs. Digital-video and VCR devices recognize this command.

wsprintf(lpstrCommand, "list %s %s %s", lpszDeviceID, lpszList,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszList

Flag that identifies the number and types of video and audio inputs. The following table lists device types that recognize the list command and the flags used by each type:

digitalvideo	audio algorithm audio quality algorithm algorithm audio stream count number index	still algorithm still quality algorithm algorithm video algorithm video quality algorithm algorithm video source video stream
vcr	audio source count audio source number index	video source count video source number index
The following table lists the flags that can be specified in the lpszList parameter and their meanings:

audio algorithm	Specifies the command should retrieve audio algorithm names.
audio quality algorithm algorithm	Specifies the command should retrieve quality levels associated with the specified algorithm. If algorithm is “current”, the quality level of the current algorithm is returned.
audio source count	Returns the total number of audio inputs.
audio source number index	Returns the type of audio input of source index.
audio stream	Specifies the command should retrieve the names of the audio streams associated with the workspace. These strings (such as “English” or “German”) are embedded in the file and identify the stream.
count	Returns the number of options of the specified type.
number index	Returns a string describing a specific option (as identified by index) of the specified option type. Index must be an integer between 1 and the value returned by “count”.
still algorithm	Specifies the command should retrieve still algorithm names.
still quality algorithm algorithm	Specifies the command should retrieve quality levels associated with the specified still algorithm. If algorithm is “current”, the quality level of the current algorithm is returned.
video algorithm	Specifies the command should retrieve video algorithm names.
video quality algorithm algorithm	Specifies the command should retrieve quality levels associated with the specified video algorithm. If algorithm is “current”, the quality level of the current algorithm is returned.
video source	Specifies the command should return information about the video sources. When used with the “count” flag, it returns the number of video sources. When used with the “number” flag, it returns the type of a video source. MCI defines the following constants for type: “ntsc”, “rgb”, “pal”, “secam”, “svideo”, and “generic”. There might be more than one source of each type returned. The “generic” source type is used when more than one signal is allowed for that connector.
video source count	Returns total number of video inputs.
video source number index	Returns the type of video input of source index.
video stream	Specifies the command should retrieve the names of video streams associated with the workspace. These strings (such as “funny ending” or “sad ending”) are embedded in the file and identify the stream.
lpszFlags

Can be “wait”, “notify”, or “test”. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

For VCR devices, either “video source” or “audio source” must be specified with either the “count” or “number” flags. If “count” is specified, the total number of inputs of video or audio is returned. If “number” is specified, the driver returns a type corresponding to the input. The type can be any one of the following: “tuner”, “line”, “svideo”, “aux”, or “generic”. Typically, you should first query the VCR for the “count” and then use the count as the range for the “number” flag. The “source” numbers start from 1.


load

The load command loads a file in a device-specific format. Digital-video and video-overlay devices recognize this command.

wsprintf(lpstrCommand, "load %s %s %s", lpszDeviceID, lpszFilePos,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszFilePos

Path and filename to load. For video-overlay devices, this can also include a target rectangle for the data. To specify a target rectangle, specify “at” followed by X1 Y1 X2 Y2, where X1 Y1 specify the upper left corner of the rectangle, and X2 Y2 specify the width and height. The rectangle is relative to the video buffer origin.

lpszFlags

Can be “wait”, “notify”, or both. For digital-video devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following command loads a file into the “vidboard” device:

load vidboard c:\vid\fish.vid notify

The “vidboard” device sends a notification message when the loading is completed.


mark

The mark command controls recording and erasing of marks on the videotape. VCR devices recognize this command.

wsprintf(lpstrCommand, "mark %s %s %s", lpszDeviceID, lpszMark,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszMark

One of the following flags:

erase	Erases a mark at the current position, if one exists. To erase a mark, first seek to the mark and then issue the mark “erase” command.
write	Writes a mark at the current position. The VCR might need to be in play or record mode for this command to succeed.
lpszFlags

Can be “wait”, “notify”, or “test”. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

Marks are special signals written to the content that can be detected by the VCR during high-speed searches. Marks are VCR specific.


monitor

The monitor command specifies the presentation source. (The default presentation source is the workspace.) Switching the presentation source switches all audio and video streams in the source. Digital-video devices recognize this command.

wsprintf(lpstrCommand, "monitor %s %s %s", lpszDeviceID, lpszMonitor,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszMonitor

One or more of the following flags:

file	Specifies that the workspace is the presentation source. This is the default source.
input	Specifies that the external input is the presentation source. If a play command is in progress, it is first paused. If setvideo is “on”, this flag displays a default hidden window. Devices might limit what other device instances can do while monitoring input.
method method	When used with monitor “input”, this flag selects the method of monitoring. The method is either “pre”, “post”, or “direct”. Direct monitoring requests that the device be configured for optimum display quality during monitoring. The direct monitoring method might be incompatible with motion video recording.  Pre- and post-monitoring allow motion video recording. Pre-monitoring shows the external input prior to compression, while post-monitoring shows the external input after compression. Typically, different monitoring methods have different hardware implications. The default monitoring method is selected by the device.
lpszFlags

Can be “wait”, “notify”, “test”, or a combination of these. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The presentation source automatically switches to the workspace after a play, step, pause, cue “output”, or seek command. The record command does not automatically switch presentation sources, which gives your application the option of not showing video while it is being recorded.

See Also

cue, pause, play, record, seek, step


open

The open command initializes a device. All MCI devices recognize this command.

wsprintf(lpstrCommand, "open %s %s %s", lpszDevice, lpszOpenFlags,
    lpszFlags);

Parameters

lpszDevice

Identifier of an MCI device or device driver. This can be either a device name (as given in the registry or the SYSTEM.INI file) or the filename of the device driver. If you specify the filename of the device driver, you can optionally include the .DRV extension, but you should not include the path to the file.

lpszOpenFlags

Flag that identifies what to initialize. The following table lists device types that recognize the open command and the flags used by each type:

cdaudio	alias device_alias shareable	type device_type
digitalvideo	alias device_alias elementname nostatic parent hwnd shareable	style child style overlapped style popup style style_type type device_type
overlay	alias device_alias parent hwnd shareable style child	style overlapped style popup style style_type type device_type
sequencer	alias device_alias shareable	type device_type
vcr	alias device_alias shareable	type device_type
videodisc	alias device_alias shareable	type device_type
waveaudio	alias device_alias buffer buffer_size	shareable type device_type
The following table lists the flags that can be specified in the lpszOpenFlags parameter and their meanings:

alias device_alias	Specifies an alternate name for the given device. If specified, it must be used as the device_id in subsequent commands.
elementname	Specifies the name of the device element (file) loaded when the device opens.
buffer buffer_size	Sets the size, in seconds, of the buffer used by the waveform-audio device. The default size of the buffer is set when the waveform-audio device is installed or configured. Typically the buffer size is set to 4 seconds. With the MCIWAVE device, the minimum size is 2 seconds and the maximum size is 9 seconds.
parent hwnd	Specifies the window handle of the parent window.
shareable	Initializes the device or file as shareable. Subsequent attempts to open the device or file fail unless you specify “shareable” in both the original and subsequent open commands.  MCI returns an invalid device error if the device is already open and not shareable. The MCISEQ sequencer and MCIWAVE devices do not support shared files.
style child	Opens a window with a child window style.
style overlapped	Opens a window with an overlapped window style.
style popup	Opens a window with a pop-up window style.
style style_type	Indicates a window style.
type device_type	Specifies the device type of a file.
lpszFlags

Can be “wait”, “notify”, or both. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

MCI reserves “cdaudio” for the CD audio device type, “videodisc” for the videodisc device type, “sequencer” for the MIDI sequencer device type, “AVIVideo” for the digital-video device type, and “waveaudio” for the waveform-audio device type.

As an alternative to the “type” flag, MCI can select the device based on the extension used by the file, as recorded in the registry or the [mci extension] section of the SYSTEM.INI file.

MCI can open AVI files by using a file-interface pointer or a stream-interface pointer. To open a file by using either type of interface pointer, specify an at sign (@) followed by the interface pointer in place of the file or device name for the lpszDevice parameter. For more information about the file and stream interfaces, see “AVIFile Functions and Macros .”

The following command opens the “mysound” device:

open new type waveaudio alias mysound buffer 6

With device name “new”, the waveform driver prepares a new waveform resource. The command assigns the device alias “mysound” and specifies a 6-second buffer.

You can eliminate the “type” flag if you combine the device name with the filename. MCI recognizes this combination when you use the following syntax:

device_name!element_name

The exclamation point separates the device name from the filename. The exclamation point should not be delimited by white spaces.

The following example opens the RIGHT.WAV file using the “waveaudio” device:

open waveaudio!right.wav

The MCIWAVE driver requires an asynchronous waveform-audio device.


paste

The paste command copies the contents of the clipboard into the workspace. Digital-video devices recognize this command.

wsprintf(lpstrCommand, "paste %s %s %s", lpszDeviceID, lpszItem,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszItem

One or more of the following flags:

at rectangle	Specifies the location within the frame where the data is pasted. The upper left corner of the rectangle corresponds to the upper left corner of the added data. If the rectangle has a nonzero size in X or Y, the contents of the clipboard are scaled in those dimensions when they are pasted into the frame. If omitted, the rectangle defaults to the entire frame. If this flag is specified in “insert” mode (the default), any region outside the rectangle is painted a solid color.
audio stream stream	Specifies the audio stream in the workspace affected by the command. If only one audio stream exists on the clipboard, the audio data is pasted into the designated stream. If more than one audio stream exists on the clipboard, the stream indicates the starting number for the stream sequences. If you use this flag and also want to paste video, you must also use the “video stream” flag. (If neither flag is specified, all audio and video streams are pasted and retain their original stream numbers.)
insert	Specifies that the data is inserted into the workspace. Any data after the insertion point is moved forward in the workspace to make room. This is the default value.
overwrite	Specifies that the data is copied into the workspace by writing over any existing data after the insertion point. The “insert” and “overwrite” flags affect whether frames are destroyed or moved during the paste operation, not how the data is pasted within each frame.
to position	Specifies the position in the workspace at which the data is pasted. If omitted, it defaults to the current position.
video stream stream	Specifies the video stream in the workspace affected by the command. If only one video stream exists on the clipboard, the video data is pasted into the designated stream. If more than one video stream exists on the clipboard, the stream indicates the starting number for the stream sequences. If you use this flag and also want to paste audio, you must also use the “audio stream” flag. (If neither flag is specified, all audio and video streams are pasted and retain their original stream numbers.)
lpszFlags

Can be “wait”, “notify”, “test”, or a combination of these. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

No signals are present in the data copied from the clipboard. The change becomes permanent only when the data is explicitly saved; however, playback acts as if the data has been added.


pause

The pause command pauses playing or recording. Most drivers retain the current position and eventually resume playback or recording at this position. CD audio, digital-video, MIDI sequencer, VCR, videodisc, and waveform-audio devices recognize this command.

wsprintf(lpstrCommand, "pause %s %s", lpszDeviceID, lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

With the MCICDA, MCISEQ, and MCIPIONR drivers, the pause command works the same as the stop command.

The following command pauses the “mysound” device:

pause mysound

See Also

stop


play

The play command starts playing a device. CD audio, digital-video, MIDI sequencer, videodisc, VCR, and waveform-audio devices recognize this command.

wsprintf(lpstrCommand, "play %s %s %s", lpszDeviceID, lpszPlayFlags,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszPlayFlags

Flag for playing a device. The following table lists device types that recognize the play command and the flags used by each type:

cdaudio	from position	to position
digitalvideo	from position  fullscreen repeat	reverse to position window
sequencer	from position	to position
vcr	at time from position  reverse	scan to position
videodisc	fast from position  reverse scan	slow speed integer to position
waveaudio	from position	to position
The following table lists the flags that can be specified in the lpszPlayFlags parameter and their meanings:

at time	Indicates when the device should begin performing this command, or, if the device has been cued, when the cued command begins. For more information, see the cue command.
fast	Indicates that the device should play faster than normal. To determine the exact speed on a videodisc player, use the “speed” flag of the status command. To specify the speed more precisely, use the “speed” flag of this command.
from position	Specifies a starting position for the playback. If the “from” flag is not specified, playback begins at the current position. For cdaudio devices, if the “from” position is greater than the end position of the disc, or if the “from” position is greater than the “to” position, the driver returns an error. For videodisc devices, the default positions are in frames for CAV discs and in hours, minutes, and seconds for CLV discs.
fullscreen	Specifies that a full-screen display should be used. Use this flag only when playing compressed files. (Uncompressed files won’t play full-screen.)
repeat	Specifies that playback should restart when the end of the content is reached.
reverse	Specifies that the play direction is backward. You cannot specify an ending location with the “reverse” flag. For videodiscs, “scan” applies only to CAV format.
scan	Plays as fast as possible without disabling video (although audio might be disabled). For videodiscs, “scan” applies only to CAV format.
slow	Plays slowly. To determine the exact speed on a videodisc player, use the “speed” flag of the status command. To specify the speed more precisely, use the “speed” flag of this command. For videodiscs, “slow” applies only to CAV format.
speed integer	Plays a videodisc at the specified speed, in frames per second. This flag applies only to CAV discs.
to position	Specifies an ending position for the playback. If the “to” flag is not specified, playback stops at the end of the content. For cdaudio devices, if the “to” position is greater than the end position of the disc, the driver returns an error. For videodisc devices, the default positions are in frames for CAV discs and in hours, minutes, and seconds for CLV discs.
window	Specifies that playing should use the window associated with the device instance. This is the default setting.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

Before issuing commands that use position values, you should set the desired time format by using the set command. This command begins playing at the current speed, as set with the set “speed” command. The direction is reverse if the “reverse” flag is specified, or if the “to” flag is specified as a value less than the “from” flag. If the “from” flag is not specified, playback begins at the current position. The “to” and “reverse” flags cannot be used together.

The following command plays the “mysound” device from position 1000 through position 2000, sending a notification message when the playback completes:

play mysound from 1000 to 2000 notify

See Also

cue, set, status


put

The put command defines the area of the source image and destination window used for display. Digital-video and video-overlay devices recognize this command.

wsprintf(lpstrCommand, "put %s %s %s", lpszDeviceID, lpszRegions,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszRegions

Flag for defining the area. The following table lists device types that recognize the put command and the flags used by each type:

digitalvideo	destination destination at rectangle frame frame at rectangle source source at rectangle	video video at rectangle window window at rectangle window client window client at rectangle
overlay	destination destination at rectangle frame frame at rectangle	source source at rectangle video video at rectangle
The following table lists the flags that can be specified in the lpszRegions parameter and their meanings:

destination	Selects the entire client area of the destination window to display the data.
destination at rectangle	Selects a portion of the client area of the destination window used to display the image. When an area of the display window is specified and the device supports stretching, the source image is stretched to the destination offset and extent.
frame	Selects the entire frame buffer to receive the incoming video images.
frame at rectangle	Selects a portion of the frame buffer to receive the incoming video images.
source	Selects the entire image for display in the destination window.
source at rectangle	Selects a portion of the image to display in the destination window. When an area of the source image is specified, and the device supports stretching, the source image is stretched to the destination offset and extent.
video	Selects the entire incoming video image to capture in the frame buffer.
video at rectangle	Selects a portion of the incoming video image to capture in the frame buffer.
window	Restores the initial window size on the display. This command also displays the window.
window at rectangle	Changes the size and location of the display window. The specified rectangle is relative to the parent window of the display window (usually the desktop) if the “style child” flag has been used for the open command. To change the location of the window without changing its height or width, specify zero for the height and width.
window client	Restores the client area of the window.
window client at rectangle	Changes the size and location of the client area of the window. The specified rectangle is relative to the parent window of the client window. To change the location of the window without changing its height or width, specify zero for the height and width.
When a flag includes a rectangle, the rectangle coordinates are relative to the window origin or the image origin, as appropriate, and are specified as X1 Y1 X2 Y2. The coordinates X1 Y1 specify the upper left corner, and the coordinates X2 Y2 specify the width and height of the rectangle.

lpszFlags

Can be “wait”, “notify”, or both. For digital-video devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The put command defines one or more of the following rectangles when working with video-overlay devices:

•	The video rectangle defines the region of the incoming video image to capture.

•	The frame rectangle defines the region of the frame buffer that receives the incoming video image.

•	The source rectangle defines which region of the frame buffer is copied to the destination rectangle.

•	The destination rectangle defines the region of the display window client area that receives the video image.

The video rectangle is related to the frame rectangle in the same way the source rectangle is related to the destination rectangle. Stretching can occur from the video rectangle to the frame rectangle and from the source rectangle to the destination rectangle. Not all devices support stretching, and stretching must be enabled (by using the set command).

The following command defines three regions for the video, frame, and source:

put vboard video 120 120 200 200 frame 0 0 200 200 source 0 0 200 200

The regions in this example are defined as follows:

•	A 200- by 200-pixel region of the incoming video data, starting at an origin 120 pixels from the upper left corner, will be captured to the frame buffer.

•	The video data will be placed in a 200- by 200-pixel region at the upper left corner of the frame buffer.

•	Transfers are made from the 200- by 200-pixel region at the upper left corner of the frame buffer to the destination window.

See Also

open, set


quality

The quality command defines a custom quality level for either audio, video or still image data compression. Digital-video devices recognize this command.

wsprintf(lpstrCommand, "quality %s %s %s", lpszDeviceID, lpszQuality,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszQuality

One or more of the following flags. (One of the three flags “audio”, “still”, and “video” must be present.)

algorithm algorithm	Associates the quality level with the specified algorithm. This algorithm must be supported by the device and be compatible with the “audio”, “still”, or “video” flag that is used. If omitted, the current algorithm is used.
audio name	Indicates this command specifies an “audio” quality level identified with name.
dialog	Requests that the device display a dialog box. This dialog box has algorithm-specific fields that are used internally by the device to create the structure describing a specific quality level.
handle handle	Specifies a handle to a structure that contains algorithmic-specific data describing a specific quality level. The structures for the data referenced by this handle are device specific.
still name	Indicates the command specifies a “still” quality level identified with name.
video name	Indicates the command specifies a “video” quality level identified with name.
lpszFlags

Can be “wait”, “notify”, “test”, or a combination of these. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

This command defines a string name for the quality level, which can then be used in a setvideo “quality”, setvideo “still quality”, or setaudio “quality” command to establish it as the current video, still, or audio-compression quality level.

See Also

setaudio, setvideo


realize

The realize command instructs a device to select and realize its palette into the display context of the displayed window. Digital-video devices recognize this command.

wsprintf(lpstrCommand, "realize %s %s %s", lpszDeviceID, lpszPalette,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszPalette

One of the following flags:

background	Realizes the palette as a background palette.
normal	Realizes the palette for a top-level window. This is the default setting.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

Use this command only if your application uses a window handle and receives a WM_QUERYNEWPALLETTE or WM_PALETTECHANGED message.

The following command tells the “myvideo” device to realize its palette:

realize myvideo normal

See Also

WM_PALETTECHANGED


record

The record command starts recording data. VCR and waveform-audio devices recognize this command. Although digital-video devices and MIDI sequencers also recognize this command, the MCIAVI and MCISEQ drivers do not implement it.

wsprintf(lpstrCommand, "record %s %s %s", lpszDeviceID, lpszRecordFlags,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszRecordFlags

Flag for recording data. The following table lists device types that recognize the record command and the flags used by each type:

digitalvideo	at rectangle audio stream stream from position hold	insert overwrite to position video stream stream
sequencer	from position insert	overwrite to position
vcr	at time from position initialize	insert overwrite to position
waveaudio	from position insert	overwrite to position
The following table lists the flags that can be specified in the lpszRecordFlags parameter and their meanings:

at rectangle	Specifies a rectangular region of the external input used as the source for the pixels compressed and saved. If not specified, the rectangle defaults to the rectangle specified for put “video”. When it is set differently from the “video” rectangle, the displayed image is not what is recorded.
at time	Indicates when the device should begin performing this command, or, if the device has been cued, when the cued command begins. For more information, see the cue command.
audio stream stream	Specifies the audio stream used for recording. If this flag is not specified and the file format does not define a default, it is recorded into the stream that is physically first.
from position	Specifies a starting position for the recording. If the “from” flag is not specified, the device starts recording at the current position.
hold	Freezes the image when recording has finished instead of showing live video. When recording stops, an automatic monitor “file” command is performed. To return to live video, issue the monitor “input” command.
initialize	Initialize the tape (media), which involves recording timecode (if possible) for blank video and audio. This command might take several hours if the entire tape must be initialized.
insert	Specifies that new data is added to the file at the current position.
overwrite	Specifies that new data will replace data in the file.
to position	Specifies an ending position for the recording. If the “to” flag is not specified, the device records until it receives a stop or pause command.
video stream stream	Specifies the video stream used for recording. If this is not specified and the file format does not define a default, then it is recorded into the stream that is physically first.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The recording stops when a stop or pause command is issued. For the MCIWAVE driver, all data recorded after a file is opened is discarded if the file is closed without saving it.

Before issuing any commands that use position values, you should set the desired time format by using the set command. The tracks to be recorded are specified by the settimecode “record”, set “assemble record”, setvideo “record”, and setaudio “record” commands.

The following command starts recording at the current position:

record mysound

See Also

cue, monitor, pause, put, set, setaudio, settimecode, setvideo, stop


reserve

The reserve command allocates contiguous disk space for the device instance’s workspace. Digital-video devices recognize this command.

wsprintf(lpstrCommand, "reserve %s %s %s", lpszDeviceID, lpszReserve,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszReserve

One or more of the following flags:

in path	Specifies the drive and directory path (but not the name) of a temporary file used to hold recorded data. The name of this file is specified by the device. The temporary file is deleted when the device is closed. If this flag is omitted, the device specifies the location of the disk space.
size duration	Specifies the approximate amount of disk space to reserve in the workspace. The duration value is specified in the current time format. The device bases its estimate of the required disk space on the following parameters: the requested time, the file format, the video and audio compression algorithm, and the compression quality values in effect. If setvideo “record” is “off”, then space is reserved only for audio. If setaudio “record” is “off”, then space is reserved only for video. If both are “off”, or if duration is zero, then no space is reserved and any existing reserved space is deallocated. If this flag is omitted, the device will use a device-defined default.
lpszFlags

Can be “wait”, “notify”, “test”, or a combination of these. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

If needed, subsequent record or save commands use the space reserved by this command. If the workspace contains unsaved data, the data is lost. Some devices do not require reserve and ignore it. If disk space is not reserved prior to recording, the record command performs an implied reserve with device-specific default flags. Use an explicit reserve command if you want better control of when the delay for disk allocation occurs, control of how much space is allocated, and control of where the disk space is allocated. Your application can change the amount and location of previously reserved disk space with subsequent reserve commands. Any allocated and still unused disk space is not deallocated until any recorded data is saved, or until the device instance is closed.

See Also

record, save, setaudio, setvideo


restore

The restore command copies a still image from a file to the frame buffer. This is the reverse of the capture command. Digital-video devices recognize this command.

wsprintf(lpstrCommand, "restore %s %s %s", lpszDeviceID, lpszRestore,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszRestore

One or more of the following flags:

at rectangle	Specifies a rectangle relative to the frame buffer origin. The rectangle is specified as X1 Y1 X2 Y2. The coordinates X1 Y1 specify the upper left corner and the coordinates X2 Y2 specify the width and height.  If this flag is not used, the image is copied to the upper left corner of the frame buffer.
from filename	Specifies the image filename to recall. This flag is required.
lpszFlags

Can be “wait”, “notify”, “test”, or a combination of these. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

Devices can recognize a variety of image formats; a Windows device-independent bitmap is always recognized.

See Also

capture


resume

The resume command continues playing or recording on a device that has been paused using the pause command. Digital-video, VCR, and waveform-audio devices recognize this command. Although CD audio, MIDI sequencer, and videodisc devices also recognize this command, the MCICDA, MCISEQ, and MCIPIONR device drivers do not support it.

wsprintf(lpstrCommand, "resume %s %s", lpszDeviceID, lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following command continues playing or recording the “newsound” device:

resume newsound

See Also

pause


save

The save command saves an MCI file. Video-overlay and waveform-audio devices recognize this command. Although digital-video devices and MIDI sequencers also recognize this command, the MCIAVI and MCISEQ drivers do not support it.

wsprintf(lpstrCommand, "save %s %s %s", lpszDeviceID, lpszFilename,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszFilename

Flag specifying the name of the file being saved and, optionally, additional flags modifying the save operation. The following table lists device types that recognize the save command and the flags used by each type:

digitalvideo	abort at rectangle	filename keepreserve
overlay	at rectangle	filename
sequencer	filename
waveaudio	filename
The following table lists the flags that can be specified in the lpszFilename parameter and their meanings:

abort	Stops a save operation in progress. If used, this must be the only item present.
at rectangle	Specifies a rectangle relative to the frame buffer origin. The rectangle is specified as X1 Y1 X2 Y2. The coordinates X1 Y1 specify the upper left corner and the coordinates X2 Y2 specify the width and height. For digital-video devices, the capture command is used to capture the contents of the frame buffer.
filename	Specifies the filename to assign to the data file. If a path is not specified, the file will be placed on the disk and in the directory previously specified on the explicit or implicit reserve command. If reserve has not been issued, the default drive and directory are those associated with the application’s task. If a path is specified, the device might require it to be on the disk drive specified by the explicit or implicit reserve. This flag is required.
keepreserve	Specifies that unused disk space left over from the original reserve command is not deallocated.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The filename variable is required if the device was opened using the “new” device identifier.

The following command saves the entire video buffer to a file named VCAPFILE.TGA:

save vboard c:\vcap\vcapfile.tga

See Also

capture, reserve


seek

The seek command moves to the specified position and stops. CD audio, digital-video, MIDI sequencer, VCR, videodisc, and waveform-audio devices recognize this command.

wsprintf(lpstrCommand, "seek %s %s %s", lpszDeviceID, lpszSeekFlags,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszSeekFlags

Flag for moving to a specified position. The following table lists device types that recognize the seek command and the flags used by each type:

cdaudio	to end to position	to start
digitalvideo	to end to position	to start
sequencer	to end to position	to start
vcr	at time mark mark_num reverse	to end to position to start
videodisc	reverse to end	to position to start
waveaudio	to end to position	to start
The following table lists the flags that can be specified in the lpszSeekFlags parameter and their meanings:

at time	Indicates when the device should begin performing this command, or, if the device has been cued, when the cued command begins. For more information, see the cue command.
mark mark_num	Seeks to the relative mark indicated by mark_num, which must be a positive integer value. Marks are signals written to the VCR tape using the mark command and are used for high-speed searching.
reverse	Indicates that the seek direction on VCRs and CAV videodiscs is backward. This flag is invalid if the “to” flag is specified. For VCRs, this flag must be used with the “mark” flag.
to end	Seeks to the end of the content.
to position	Specifies the position to stop the seek. For cdaudio devices, MCI returns an out-of-range error if the specified position is greater than the length of the disc.
to start	Seeks to the start of the content.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

Before issuing any commands that use position values, you should set the desired time format by using the set command.

Digital-video devices support two seek modes, which you can change by using the set command. The “seek exactly on” mode causes the seek command to move to the specified frame. The “seek exactly off” mode causes the seek command to move to the closest key frame prior to the specified frame.

If a CD audio device is playing when the seek command is issued, playback is stopped. When the seek command is issued with a videodisc device, the device searches using fast forward or fast reverse with video and audio off.

When the seek command is issued with a waveform-audio device, the behavior depends on the sample size. If the sample size is 16 bits or greater, seek moves to the beginning of the nearest sample when a specified position does not coincide with the start of a sample.

The following command seeks to the start of the media file associated with the “mysound” device:

seek mysound to start

See Also

cue, mark, set


set

The set command establishes control settings for the device. CD audio, digital-video, MIDI sequencer, VCR, videodisc, video-overlay, and waveform-audio devices recognize this command.

wsprintf(lpstrCommand, "set %s %s %s", lpszDeviceID, lpszSetting,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszSetting

Flag for establishing control settings. The following table lists device types that recognize the set command and the flags used by each type:

cdaudio	audio all off audio all on audio left off audio left on audio right off audio right on	door closed door open time format milliseconds time format msf time format tmsf
digitalvideo	audio all off audio all on audio left off audio left on audio right off audio right on door closed door open	file format format seek exactly on seek exactly off speed factor still file format format time format frames time format milliseconds video off video on
overlay	audio all off audio all on audio left off audio left on audio right off	audio right on door closed door open video off video on
sequencer	audio all off audio all on audio left off audio left on audio right off audio right on door closed door open master MIDI master none master SMPTE offset time	port mapper port none port port_number slave file slave MIDI slave none slave SMPTE tempo tempo_value time format milliseconds time format SMPTE fps time format SMPTE 30 drop time format song pointer
vcr	assemble record on assemble record off audio all off audio all on audio left off audio left on audio right off audio right on clock time counter format counter value door closed door open index counter index date index time index timecode length duration pause timeout postroll duration -     duration	power on power off preroll duration duration record format SP record format LP record format EP speed factor time format frames time format hms time format milliseconds time format msf time format SMPTE fps time format SMPTE 30 drop time format tmsf time mode counter time mode detect time mode timecode tracking plus tracking minus tracking reset
videodisc	audio all off audio all on audio left off audio left on audio right off audio right on door closed	door open time format frames time format hms time format milliseconds time format track video off video on
waveaudio	alignment integer any input any output audio all off audio all on audio left off audio left on audio right off audio right on bitspersample bit_count bytespersec byte_rate	channels channel_count door closed door open format tag pcm format tag tag input integer output integer samplespersec integer time format bytes time format milliseconds time format samples
The following table lists the flags that can be specified in the lpszSetting parameter and their meanings:

alignment integer	Sets the alignment of data blocks relative to the start of data passed to the waveform-audio device. The file is saved in this format.
any input	Use any input that supports the current format when recording. This is the default setting.
any output	Use any output that supports the current format when playing. This is the default.
assemble record on assemble record off	In assemble mode, all tracks are recorded as defined by the device. Most VCRs are in assemble mode by default.
audio all off audio all on	Disables or enables audio output. Video-overlay devices, the MCISEQ sequencer, and the MCIWAVE waveform-audio device do not support this flag.
audio left off audio left on audio right off audio right on	Disables or enables output to either the left or the right audio channel. Video-overlay devices, the MCISEQ sequencer, and the MCIWAVE waveform-audio device do not support this flag.
bitspersample bit_count	Sets the number of bits per PCM (Pulse Code Modulation) sample played or recorded. The file is saved in this format.
bytespersec byte_rate	Sets the average number of bytes per second played or recorded. The file is saved in this format.
channels channel_count	Sets the channels for playing and recording. The file is saved in this format.
clock time	Sets time on the external clock to time. The format is specified as a long unsigned integer.
counter format	Set the time format for the counter, as returned by status “counter”. For information about applicable types, see the set “time format” command.
counter value	Sets the VCR counter to the specified value. The value must be specified in the current counter format. For more information, see the set “counter format” command.
door closed	Retracts the tray and closes the door, if possible. For VCRs, loads the tape automatically.
door open	Opens the door and ejects the tray or tape, if possible.
file format format	Specifies a file format that is used for save or capture commands. If omitted, this might default to a device driver defined format. If the specified file format conflicts with the currently selected algorithm and quality, then they are changed to the defaults for the file format. The following file formats are defined: avi Specifies AVI format.  avss Specifies AVSS format.  dib Specifies DIB format.  jfif Specifies JFIF format.  jpeg Specifies JPEG format.  mpeg Specifies MPEG format.  rdib Specifies RLE DIB format.  rjpeg Specifies RJPEG format.
format tag pcm	Sets the format type to PCM for playing and recording. The file is saved in this format.
format tag tag	Sets the format type for playing and recording. The file is saved in this format.
index timecode index counter index date index time	Sets the current display screen on the VCR.
input integer	Sets the audio channel used as the input.
length duration	Sets the user-specified length of the tape in the VCR. This length is returned by the status “length” command and is provided for compatibility with applications that require this command to return a valid length.
master midi	Sets the MIDI sequencer as the synchronization source. Synchronization data is sent in MIDI format. The MCISEQ sequencer does not support this flag.
master none	Inhibits the MIDI sequencer from sending synchronization data. The MCISEQ sequencer does not support this flag.
master smpte	Sets the MIDI sequencer as the synchronization source. Synchronization data is sent in SMPTE (Society of Motion Picture and Television Engineers) format. The MCISEQ sequencer does not support this flag.
offset time	Sets the SMPTE offset time. The offset is the beginning time of a SMPTE based sequence. The time is expressed as hh:mm:ss:ff, where hh is hours, mm is minutes, ss is seconds, and ff is frames.
output integer	Sets the audio channel used as the output.
pause timeout	Sets the maximum duration, in milliseconds, of a pause command. A timeout value of zero indicates that no time-out will occur.
postroll duration duration	Sets the length, in the current time format, needed to brake the VCR transport when a stop or pause command is issued.
port mapper	Sets the MIDI mapper as the port receiving the MIDI messages. This command fails if the MIDI mapper or a port it needs is being used by another application.
port none	Disables the sending of MIDI messages. This command also closes a MIDI port.
port port_number	Sets the MIDI port receiving the MIDI messages. This command fails if the port you are trying to open is being used by another application.
power on power off	Sets the device power to on or off.
preroll duration duration	Sets the length, in the current time format, needed to stabilize the VCR output.
record format SP record format LP record format EP	Sets the recording mode for the VCR to SP for standard play, EP for extended play, or LP for long play. These values are not intended to be VHS specific. They map to any three appropriate modes with other tape formats. For example, SP maps to the fastest, highest quality recording.
samplespersec integer	Sets the sample rate for playing and recording. The file is saved in this format.
seek exactly on seek exactly off	Selects one of two seek modes. With “seek exactly on”, seek will always move to the frame specified. With “seek exactly off”, seek will move to the closest key frame prior to the frame specified.
slave file	Sets the MIDI sequencer to use file data as the synchronization source. This is the default setting.
slave midi	Sets the MIDI sequencer to use incoming MIDI data for the synchronization source. The sequencer recognizes synchronization data with the MIDI format. The MCISEQ sequencer does not support this flag.
slave none	Sets the MIDI sequencer to ignore synchronization data.
slave smpte	Sets the MIDI sequencer to use incoming MIDI data for the synchronization source. The sequencer recognizes synchronization data with the SMPTE format. The MCISEQ sequencer does not support this flag.
speed factor	Sets the relative speed of video and audio playback from the workspace. Factor is the ratio between the nominal frame rate and the desired frame rate, where the nominal frame rate is designated as 1000. (A rate of 500 is half normal speed, 2000 is twice normal speed, and so on.) Setting the speed to zero plays the video as fast as possible without dropping frames and without audio.
still file format format	Specifies the file format used for capture commands.
tempo tempo_value	Sets the tempo of the sequence according to the current time format. For a PPQN-based file, the tempo_value is interpreted as beats per minute. For a SMPTE-based file, the tempo_value is interpreted as frames per second.
time format bytes	In a PCM file format, sets the time format to bytes. All position information is specified as bytes following this command.
time format frames	Sets the time format to frames. All commands that use position values will assume frames. When the device is opened, frames is the default mode. Supported by videodiscs using CAV format.
time format hms	Sets the time format to hours, minutes, and seconds. All commands that use position values will assume HMS. HMS is the default format for CLV videodiscs.  Specify an HMS value as hh:mm:ss, where hh is hours, mm is minutes, and ss is seconds. You can omit a field if it and all following fields are zero. For example,  3, 3:0, and 3:0:0 are all valid ways to express 3 hours.
time format milliseconds	Sets the time format to milliseconds. All commands that use position values will assume milliseconds. You can abbreviate milliseconds as “ms”. For sequencer devices, the sequence file sets the default format to PPQN or SMPTE. Video-overlay devices do not support this flag.
time format msf	Sets the time format to minutes, seconds, and frames. All commands that use position values will assume MSF (the default format for CD audio). Specify an MSF value as mm:ss:ff, where mm is minutes, ss is seconds, and ff is frames. You can omit a field if it and all following fields are zero. For example, 3, 3:0, and 3:0:0 are valid ways to express 3 minutes.  The MSF fields have the following maximum values: Minutes 99 Seconds 59 Frames  74
time format samples	Sets the time format to samples. All position information is specified as samples following this command.
time format smpte 24 time format smpte 25 time format smpte 30	Sets the time format to an SMPTE frame rate.  For VCRs, sets the time format to hh:mm:ss:ff, where the legal values are 00:00:00:00 through 23:59:59:xx, and xx is one less than the frames per second as specified by the number 24, 25, or 30 as specified in the flag. On input, colons (:) are required to separate the components. The least significant units can be  omitted if they are 00; for example, 02:00 is the same  as 02:00:00:00.  All commands that use position values will assume SMPTE format.  The sequence file sets the default format to PPQN or SMPTE.
time format smpte 30 drop	Sets the time format to SMPTE 30 drop frame rate.  For VCRs, same as SMPTE 30, except that certain timecode positions are dropped from the format to have the recorded timecode positions for each frame (at the NTSC frame rate of 29.97 fps) correspond to real time (at 30 fps). Timecode positions that are dropped are as follows: two every minute, on the minute, for the first nine of every ten minutes of recorded content. For example, at 01:04:59:29, the next timecode position would be 01:05:00:02, not 01:05:00:00.  All commands that use position values will assume SMPTE format.  The sequence file sets the default format to PPQN or SMPTE.
time format song pointer	Sets the time format to song pointer (sixteenth notes). All commands that use position values will assume song pointer units. This flag is valid only for a sequence of division type PPQN.
time format tmsf	Sets the time format to tracks, minutes, seconds, and frames. All commands that use position values will assume TMSF. Specify a TMSF value as tt:mm:ss:ff, where tt is tracks, mm is minutes, ss is seconds, and ff is frames. You can omit a field if it and all following fields are zero. For example, 3, 3:0, 3:0:0, and 3:0:0:0 are all valid ways to express track 3.  The TMSF fields have the following maximum values: Tracks 99 Minutes 99 Seconds 59 Frames  74
time format track	Sets the position format to tracks. All commands that use position values will assume tracks.
time mode counter	Sets the position-information mode to use the VCR counters.
time mode detect	Sets the position information mode based on detection of timecode information on the tape. If timecode information is detected, the time type is set to “timecode”; otherwise, the time type is set to “counter”. “Detect” is a special mode. Whenever the driver is opened, a new tape is inserted, or the “time mode” command is issued, the driver checks the current time mode available on the tape and sets “time type” to either “timecode” or “counter”. Once “time type” is set, the driver doesn’t change it until one of the above conditions occurs again.
time mode timecode	Sets the position information mode to use “timecode” information on the tape.
tracking plus tracking minus tracking reset	Adjusts the speed of the videotape transport in fine increments. Use the “tracking” flags when a noisy picture is obtained from a VCR. “Tracking plus” increases the transport speed. “Tracking minus” decreases the transport speed. “Tracking reset” returns the tracking adjustment to zero.
video off	Disables video output.
video on	Enables video output.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

Several properties of waveform-audio data are defined when the file to store the data is created. These properties describe how the data is structured within the file and cannot be changed once recording begins. The following list identifies these properties:

•	alignment

•	bitspersample

•	bytespersec

•	channels

•	format tag

•	samplespersec

The following command sets the time format to milliseconds and sets the waveform-audio format to 8 bit, mono, 11 kHz:

set mysound time format ms bitspersample 8 channels 1 samplespersec 11025

See Also

capture, pause, save, status, stop


setaudio

The setaudio command sets values associated with audio playback and capture. Digital-video and VCR devices recognize this command.

wsprintf(lpstrCommand, "setaudio %s %s %s", lpszDeviceID, lpszAudio,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszAudio

Flag for audio playback and capture. The following table lists device types that recognize the setaudio command and the flags used by each type:

digitalvideo	algorithm algorithm alignment to integer bass to factor bitspersample to bit_count bytespersec to integer clocktime input left off left on left volume to factor off on output	over duration quality descriptor record off record on right off right on right volume to factor samplespersec to integer source to sourcename stream to number treble to factor volume to factor
vcr	off on monitor to type number number record off record track track_number off	record on  record track track_number on  source to type number number track track_number off track track_number on
The following table lists the flags that can be specified in the lpszAudio parameter and their meanings:

algorithm algorithm	Selects a specific audio compression algorithm for use by a subsequent reserve or record command. The algorithms supported are device specific. MCI defines the values “g711”, “g721”, “g722”, “g728”, “pcm”, “cdxa”, “adpcm”, and “adpcm4e” for algorithm. If a device supports the algorithm names “pcm”, “cdxa”, and “adpcm4e”, they adhere to standard definitions. The “cdxa” algorithm has been defined by Sony Corporation. The “adpcm4e” algorithm has been defined by Intel Corporation. The “g711”, “g721”, “g722”, and “g728” values represent audio algorithms recommended by the International Telegraph and Telephone Consultative Committee (CCITT). If the specified algorithm conflicts with the current file format, the file format is changed to the default format for the algorithm.
alignment to integer	Sets the alignment of data blocks relative to the start of input waveform-audio data.
bass to factor	Sets the audio low frequency level.
bitspersample to bit_count	Sets the number of bits per sample recorded. The file is saved in this format. This flag applies only to devices supporting the “pcm” algorithm.
bytespersec to integer	Sets the average number of bytes per second for recording in the “pcm” and “adpcm” algorithms. The file is saved in this format.
clocktime	Indicates the time specified in the “over” flag is in milliseconds. This time is absolute and not in step with the playing of the workspace.
input	Modifies the “bass”, “treble”, or “volume” flag so that it affects the input signal and modifies what is recorded. If possible, this is the default when monitoring the input.
left off left on	Enables or disables audio output on the left channel. The audio presentation source can be the external input or the workspace. The default is “left on”. If there is only one channel, that channel is set on or off.
left volume to factor	Sets the audio volume of the left audio channel. If there is only one channel it sets its volume.
monitor to type number number	Controls which source input will be passed to the VCR output without changing the recording source input selection. Type can be “output,” or one of the valid input sources. If number is not specified, then the first input of that type will be chosen.
off on	Enables or disables audio. The audio presentation source can either be the external input or the workspace. This command affects the left and right audio channels simultaneously. The default is setaudio “on”.
output	Modifies the “bass”, “treble”, or “volume” flag so that it modifies only the played signal and not what is recorded. If possible, this is the default when monitoring a file.
over duration	Specifies how long it should take to make a change that uses a factor variable. The units for duration are in the current time format. Changes occur in step with the playing of the workspace. When playing is suspended, the change is also suspended until the play continues. If “over” is not specified or not supported, the change occurs immediately.
quality descriptor	Specifies the characteristics of the audio compression performed when audio is recorded to a file. All devices support the three descriptors “low”, “medium”, and “high”. The default is device specific. If the “algorithm” flag is not specified, the “quality” adjustment applies to the current algorithm. The quality command can be used to define additional descriptor names.
record off	Clears the audio-source selection so that no audio will be recorded with the next record command.
record on	Enables recording of audio data. The default is to record audio data.
record track track_number off	Clears the audio-source selection so that no audio will be recorded with the next record command. “Track” allows independent track selection. Track 2 corresponds to the PCM track in Hi8. If “track” is not specified, a default value of 1 is assumed.
record track track_number on	Selects the audio source to be recorded with the next record command. “Track” allows independent track selection. Track 2 corresponds to the PCM track in Hi8. If “track” is not specified, a default value of 1 is assumed.
right off right on	Enables or disables audio output on the right channel. The audio presentation source can be the external input or the workspace. The default is “right on”. If there is only one channel, this flag has no effect.
right volume to factor	Sets the audio volume to the right audio channel. If there is only one channel, it has no effect.
samplespersec to integer	Sets the sample rate for recording with the “pcm” and “adpcm” algorithms. The file is saved in this format.
source to sourcename	Specifies the source for the audio input digitizer. The constants defined for sourcename include: “left”, “right”, “average”, and “stereo”. The first three specify monophonic recording using the left input only, the right input only, and the average of the two inputs.
source to type number number	Selects the audio source to be recorded on the tape. Type must be “tuner”, “line”, “svideo”, “aux”, “generic”, or “mute”.
stream to number	Specifies the audio stream played back from the workspace. If the stream is not specified and the file format does not define a default, then the interleaved audio stream that is physically first will be played.
track track_number off	Disables an individual track.
track track_number on	Enables an individual track.
treble to factor	Sets the audio high-frequency level.
volume to factor	Sets the average audio volume for both audio channels. If the left and right volumes have been set to different values, then the ratio of left-to-right volume is approximately unchanged.
lpszFlags

Can be “wait”, “notify”, “test”, or a combination of these. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

For VCR devices, using setaudio with a flag that turns off an individual track (“track track_number off”) might cause your application to receive a status message indicating that the command could not be carried out. Some VCRs can turn off only combinations of tracks, not individual tracks; for example, the first audio track and a video track of a video cassette. In this case, simply use setaudio and setvideo to continue to turn off the other tracks that make up the combination. The driver will turn off the tracks when it receives the command to turn off the last track in the combination.

See Also

quality, record, reserve, setvideo


settimecode

The settimecode command enables or disables timecode recording for a VCR. VCR devices recognize this command.

wsprintf(lpstrCommand, "settimecode %s %s %s", lpszDeviceID,
    lpszTimecode, lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszTimecode

One of the following flags:

record on	Sets the VCR to record timecode.
record off	Disables timecode recording.
lpszFlags

Can be “wait”, “notify”, “test”, or a combination of these. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.


settuner

The settuner command changes the current tuner or the channel setting of the current tuner. VCR devices recognize this command.

wsprintf(lpstrCommand, "settuner %s %s %s", lpszDeviceID, lpszTuner,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszTuner

One of the following flags:

channel channel	Sets the tuner to channel. You might not be able to change the channel while recording, depending on the VCR. A channel larger than the maximum sets the tuner to the maximum channel.
channel seek up channel seek down	Seeks the next channel with a valid signal. “Seek up” increments the channel number in its search. “Seek down” decrements the channel number in its search. The tuner wraps to channel 1 when the maximum channel number is exceeded. Similarly, when seeking down, the tuner wraps to the maximum channel.
channel up  channel down	Increments or decrements the tuner channel. You might not be able to change the channel while recording, depending on the VCR. The tuner wraps to channel 1 when the maximum channel number is exceeded. Similarly, when seeking down, the tuner wraps to the maximum channel.
number number	Specifies the tuner to be affected by the settuner command. If number is not given, the default value of 1 is assumed.
lpszFlags

Can be “wait”, “notify”, “test”, or a combination of these. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.


setvideo

The setvideo command sets values associated with video playback and capture. Digital-video and VCR devices recognize this command.

wsprintf(lpstrCommand, "setvideo %s %s %s", lpszDeviceID, lpszVideo,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszVideo

Flag for video playback and capture. The following table lists device types that recognize the setvideo command and the flags used by each type:

digitalvideo	algorithm algorithm bitsperpel to count brightness to factor clocktime color to factor contrast to factor gamma to value halftone input key color to r:g:b key index to index off on output	over duration palette color color over index      to newrgb palette handle to handle quality descriptor record frame rate to rate  record on record off sharpness to factor source to source number value still algorithm algorithm still quality descriptor stream to number tint to factor
vcr	off on monitor to type number number record off record track track_number off	record on  record track track_number on  source to type number number track track_number off track track_number on
The following table lists the flags that can be specified in the lpszVideo parameter and their meanings:

algorithm algorithm	Specifies a video compression algorithm for use by a subsequent reserve or record command. Algorithms supported by a device are device specific. MCI defines the constants “mpeg” and “h261” for algorithm. If the specified algorithm conflicts with the current file format, the file format is changed to the default format for the algorithm.
bitsperpel to count	Sets the number of bits per pixel for saving data with the capture or record command.
brightness to factor	Sets the video brightness level.
clocktime	Indicates that the time specified in the “over” flag is in milliseconds. The time is absolute and not in step with the playing of the workspace.
color to factor	Sets the color-saturation level.
contrast to factor	Sets the video-contrast level.
gamma to value	Specifies the gamma correction exponent multiplied by 1000. For example, to specify an exponent of 2.2, use 2200 for value. A gamma value of 1.0 (1000) indicates no gamma correction is applied. Gamma correction adjusts the mapping between the intensity encoded in the presentation source and the displayed brightness.
halftone	Causes the halftone palette to be used instead of the default palette. This flag is recognized only by the MCIAVI digital-video driver.
input	Modifies the “brightness”, “color”, “contrast”, “gamma”, “sharpness”, or “tint” flag so that it affects the input signal and modifies what is recorded. If possible, this is the default when monitoring the input.
key color to r:g:b	Sets the key color. The r:g:b variable is a Windows RGB value. Colons (:) separate the individual red, green, and blue values.
key index to index	Sets the key index. The index variable is a physical palette index.
monitor to type number number	Controls which source input will be passed to the VCR output, without changing the recording source input selection. Type can be “output”, or one of the valid input sources. If “number” is not specified, then the first input of that type is chosen.
off on	Enables or disables display of video. Disabling video sets the pixels in the put “destination” rectangle (or its default, the client region of the current window) to a solid color. It has no effect on the frame buffer. The video source, whether the workspace or an external input, might continue to store new images in the frame buffer. They are not displayed until video is enabled. You can use the window “state” command to hide the window. The default is setvideo “on”.
output	Modifies the “brightness”, “color”, “contrast”, “gamma”, “sharpness”, or “tint” flag so that it modifies only the displayed signal and not what is recorded. If possible, this is the default when monitoring a file.
over duration	Specifies how long it should take to make a change that uses a factor variable. The units for duration are in the current time format. Changes occur in step with the playing of the workspace. When playing is suspended, the change is also suspended until the play continues. If “over” is not used or not supported, the change occurs immediately.
palette color color over index to newrgb	Sets a new palette color. The color and palette index to be changed are specified by the color and index parameters; the new color is specified by newrgb. This flag is recognized only by the MCIAVI digital-video driver.
palette handle to handle	Specifies the handle to a palette the device must use for rendering. This item is supported only by devices that use palettes. If handle is zero, the default palette is used. Digital-video devices should not free the palette passed with this command. Applications should free it after they close the device.
quality descriptor	Specifies the characteristics of the video compression performed when video is recorded to a file. All devices support the three descriptors: “low”, “medium”, and “high”. The default is device specific. The significance of these names depends on the algorithm and the device. Devices might define additional descriptor names. The quality command can be used to define additional descriptor names. If the “algorithm” flag is not used, the descriptor applies to the current algorithm.
record frame rate to rate	Sets the recording for motion video. The recording rate is specified in units of frames per second multiplied by 1000. For example, the NTSC frame rate of 29.97 frames per second is represented as 29970.
record on record off	Enables or disables recording of video data. Recording video data is the default.
record track track_number off	Clears the video-source selection so that no video will be recorded with the next record command. “Track” allows independent track selection. If “track” is not specified, a default value of 1 is assumed. It might be necessary to first issue a set “assemble record off” command before the video recording can be turned off.
record track track_number on	Selects the video source to be recorded with the next record command. “Track” allows independent track selection. Track 2 corresponds to the PCM track in Hi8. If “track” is not specified, a default of 1 is assumed.
sharpness to factor	Sets the video sharpness level.
source to source number value	Sets the source of the video input. This usually corresponds to external connectors. The constants defined for source include “rgb”, “pal”, “ntsc”, “svideo”, and “secam”. If more than one input of the specified type exists, the optional “number” value indicates the desired input. For example, setvideo “source to ntsc number 2” specifies the second NTSC input. If “to” source is omitted, then the absolute source is used as defined by the list “video source” command.
source to type number number	Selects the video source to be recorded on the tape. Type must be “tuner”, “line”, “svideo”, “aux”, “generic”, “mute”, or “rgb”.
still algorithm algorithm	Specifies the still image compression algorithm used by the capture command. Every device must support an algorithm of “none”, which means no compression. This is the default. In this case, digital-video devices save still images as RGB format device-independent bitmaps. Devices might also support a device-specific list of additional algorithms.
still quality descriptor	Specifies the characteristics of the still-image compression performed while capturing a still image. All devices support the descriptors “low”, “medium”, and “high”. The default is device specific.  If the “algorithm” flag is not used, the descriptor applies to the current algorithm. The quality command can be used to define other descriptor names.
stream to number	Specifies the video stream played back from the workspace. If the stream is not specified and a default stream is not defined by the file format, then the physically first interleaved video stream is played.
tint to factor	Sets the image tint. Typically, this adjustment is modeled after the tint control of many color television sets, with 250 meaning green, 750 meaning red, and 0 (or 1000) meaning blue. The nominal value is always 500.
track track_number off	Disables an individual video track.
track track_number on	Enables an individual video track.
lpszFlags

Can be “wait”, “notify”, “test”, or a combination of these. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

For VCR devices, using setvideo with a flag that turns off an individual track (“track track_number off”) might cause your application to receive a status message indicating that the command could not be carried out. Some VCRs can turn off only combinations of tracks, not individual tracks; for example, the first audio track and a video track of a video cassette. In this case, simply use setaudio and setvideo to continue to turn off the other tracks that make up the combination. The driver will turn off the tracks when it receives the command to turn off the last track in the combination.

See Also

capture, list, put, quality, record, reserve, RGB, set, setaudio, window


signal

The signal command identifies a specified position in the workspace by sending the application an MM_MCISIGNAL message. Digital-video devices recognize this command. MCIAVI supports only one active signal at a time.

wsprintf(lpstrCommand, "signal %s %s %s", lpszDeviceID, lpszSignalFlags,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszSignalFlags

One of the following flags:

at position	Specifies the frame to invoke a signal.
cancel	Removes signals from the workspace. An individual signal is specified by using the “uservalue” flag. If the “uservalue” flag is not specified by using “cancel”, the device cancels all signals. The “cancel” flag is incompatible with the “at”, “every”, and “return position” flags.
every interval	Specifies the period of the signals. The interval value is specified in the current time format.  If used with “at” position, signals are placed throughout the workspace with one signal mark placed at position.  Without the “at” flag, signals are placed throughout the workspace with one signal at the current position.  If this flag is omitted, only the position indicated by the “at” flag is marked.  If the interval value is less than the minimum frequency supported by a device, it will use its minimum value.
return position	Indicates the device should send the position value instead of the “uservalue” identifier in the signaling message. The “uservalue” identifier can still be used to cancel or to redefine the signal marks.
uservalue id	Specifies an identifier that is reported back with the signaling message. This identifier acts as an identifier that can be used with other signal commands to reference this signal setting. If omitted, the default value is zero.
lpszFlags

Can be “wait”, “notify”, “test”, or a combination of these. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The window handle used for notification of command completion messages is also used for signaling.

See Also

MM_MCISIGNAL


spin

The spin command starts spinning a disc or stops the disc from spinning. Videodisc devices recognize this command.

wsprintf(lpstrCommand, "spin %s %s %s", lpszDeviceID, lpszUpDown,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszUpDown

One of the following flags:

down	Stops the disc from spinning.
up	Starts spinning the disc.
lpszFlags

Can be “wait”, “notify”, or both. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following command starts spinning a videodisc device:

spin videodisc up


status

The status command requests status information from a device. All devices recognize this command.

wsprintf(lpstrCommand, "status %s %s %s", lpszDeviceID, lpszRequest,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszRequest

Flag for requesting status information. The following table lists device types that recognize the status command and the flags used by each type:

cdaudio	cdaudio type track number current track length length track number media present mode	number of tracks position position track number ready start position time format
digitalvideo	audio audio alignment audio bitspersample audio breaks audio bytespersec audio input audio record audio source audio samplespersec audio stream bass bitsperpel brightness color contrast current track disk space drive file completion file format  file mode forward frames skipped gamma input left volume length length track number media present mode monitor monitor method nominal nominal frame rate nominal record frame rate number of tracks	output palette handle pause mode play speed position position track number ready record frame rate reference frame reserved size right volume seek exactly sharpness smpte speed start position still file format time format tint treble unsaved video video key index video key color video record video source video source number video stream volume window handle window visible window minimized window maximized
overlay	media present mode number of tracks	ready stretch window handle
sequencer	current track division type length length track number master media present mode number of tracks offset	port position position track number ready slave start position tempo time format
vcr	assemble record audio monitor audio monitor number audio record  audio record track number audio source audio source number channel channel tuner number clock clock id counter counter format counter resolution current track frame rate index index on length length track number media present media type mode number of audio tracks number of tracks number of video tracks	pause timeout play format position position start position track number postroll duration power on preroll duration ready record format speed time format time mode time type timecode present timecode record timecode type tuner number video monitor video monitor number video record video record track number video source video source number write protected
videodisc	current track disc size forward length length track number media present media type mode	number of tracks position position track number ready side speed start position time format
waveaudio	alignment bitspersample bytespersec channels current track format tag input length length track number level	media present mode number of tracks output position position track number ready samplespersec start position time format
The following table lists the flags that can be specified in the lpszRequest parameter and their meanings:

alignment	Returns the block alignment of data, in bytes.
assemble record	Returns TRUE if the device is set to assemble mode recording.
audio	Returns “on” or “off” depending on the most recent setaudio “on” or “off” command. It returns “on” if either or both speakers are enabled, and “off” otherwise.
audio alignment	Returns the alignment of data blocks relative to the start of input waveform-audio data.
audio bitspersample	Returns the number of bits per sample the device uses for recording. This flag applies only to devices supporting the “pcm” algorithm.
audio breaks	Returns the number of times the audio portion of the last AVI sequence broke up. The system counts an audio break whenever it attempts to write audio data to the device driver and discovers that the driver has already played all of the available data. This flag is recognized only by the MCIAVI digital-video driver. It is meant for performance evaluation only; the return value is difficult to interpret.
audio bytespersec	Returns the average number of bytes per second used for recording.
audio input	Returns the approximate instantaneous audio level of the analog input audio signal. A value greater than 1000 implies clipping distortion. Some devices can return this value only while recording audio. The value has no associated set or setaudio command.
audio monitor	Returns “output”, or one of the valid source-input types. For more information, see the setaudio “monitor” command.
audio monitor number	Returns the monitored-video number of the type specified by status “audio monitor”. For more information, see the setaudio command.
audio record	Returns “on” or “off”, reflecting the state set by setaudio “record”.
audio record track number	Returns TRUE if the VCR is set to record audio. If no track number is given, the default value of 1 is assumed.
audio samplespersec	Returns the number of samples per second recorded.
audio source	Returns the current audio digitizer source: “left”, “right”, “average”, or “stereo”.
audio source number	Returns the audio-source number of the type returned by status “audio source”. For more information, see the setaudio command.
audio stream	Returns the current audio-stream number.
bass	Returns the current audio-bass level.
bitsperpel	Returns the number of bits per pixel for saving captured or recorded data.
bitspersample	Returns the bits per sample.
brightness	Returns the current video-brightness level.
bytespersec	Returns the average number of bytes per second played or recorded.
cdaudio type track number	Returns the type of the specified track number. This can be “audio” or “other.”
channel	Returns the integer value of the channel set on the tuner.
channel tuner number	If “tuner” number is given, then the currently selected channel on the logical tuner number will be returned. Note that there can be several logical tuners.
channels	Returns the number of channels set (1 for mono, 2 for stereo).
clock	Returns the external time. The time must be an unsigned long integer expressing total increments. For more information, see the capability “clock increment rate” command.
clock id	Returns a unique integer identifying the clock.
color	Returns the current color level.
contrast	Returns the current contrast level.
counter	Returns the counter position, in the current counter format.
counter format	Returns the current counter format. For more information, see the set “counter format” command.
counter resolution	Returns “frames” or “seconds”, indicating the counter’s resolution. This is not the same as accuracy.
current track	Returns the current track. The MCISEQ sequencer returns 1.
disc size	Returns either 8 or 12, indicating the size of the loaded disc in inches.
disk space drive	Returns the approximate disk space, in the current time format, that can be obtained by a reserve command for the specified disk drive. The drive is usually specified as a single letter or a single letter followed by a colon (:). Some devices, however, might use a path.
division type	Returns one of the following file division types: PPQN  SMPTE 24 frame SMPTE 25 frame SMPTE 30 drop frame  SMPTE 30 frame Use this information to determine the format of the MIDI file and the meaning of tempo and position information.
file completion	Returns the estimated percentage a load, save, capture, cut, copy, delete, paste, or undo operation has progressed. (Applications can use this to provide a visual indicator of progress.)
file format	Returns the current file format for record or save commands.
file mode	Returns “loading”, “saving”, “editing”, or “idle”. During a load operation, it returns “loading”. During save and capture operations, it returns “saving”. During cut, copy, delete, paste, or undo operations, it returns “editing”.
format tag	Returns the format tag.
forward	Returns TRUE if the play direction is forward or if the device is not playing.
frame rate	Returns the number of frames per second that the device will use by default. NTSC devices return 30, PAL 25, and so on.
frames skipped	Returns the number of frames that were not drawn when the last AVI sequence was played. This flag is recognized only by the MCIAVI digital-video driver. It is meant for performance evaluation only; the return value is difficult to interpret.
gamma	Returns the value set with setvideo “gamma to” value.
index	Returns the current index display. For more information, see the set “index” command.
index on	Returns TRUE if the index is on.
input	Returns the input set. If one is not set, the error returned indicates that any device can be used.  For digital-video devices, modifies the “bass”, “treble”, “volume”, “brightness”, “color”, “contrast”, “gamma”, “sharpness”, or “tint” flag so that it applies only to the input. This is the default when monitoring the input.
left volume	Returns the volume set for the left audio channel.
length	Returns the total length of the media, in the current time format.  For PPQN files, the length is returned in song pointer units. For SMPTE files, it is returned as hh:mm:ss:ff, where hh is hours, mm is minutes, ss is seconds, and ff is frames. For VCR devices, the length is 2 hours (unless the length has been explicitly changed using the set command).
length track number	Returns the length of the track, in time or frames, specified by number.  For PPQN files, the length is returned in song pointer units. For SMPTE files, it is returned as hh:mm:ss:ff, where hh is hours, mm is minutes, ss is seconds, and ff is frames.
level	Returns the current PCM audio sample value.
master	Returns “midi”, “none”, or “smpte” depending on the type of synchronization set.
media present	Returns TRUE if the media is inserted in the device or FALSE otherwise. Sequencer, video-overlay, digital-video, and waveform-audio devices return TRUE.
media type	Returns the type of the media. For VCRS, this is “8mm”, “vhs”, “svhs”, “beta”, “Hi8”, “edbeta”, or “other”. For videodiscs, this is “CAV”, “CLV”, or “other”, depending on the type of videodisc.
mode	Returns the current mode of the device. All devices can return the “not ready”, “paused”, “playing”, and “stopped” values. Some devices can return the additional “open”, “parked”, “recording”, and “seeking” values.
monitor	Returns “file” or “input”. The returned value indicates the current presentation source.
monitor method	Returns “pre”, “post”, or “direct”. The returned value indicates the method used for input monitoring.
nominal	The item modifies the “bass”, “brightness”, “color”, “contrast”, “gamma”, “sharpness”, “tint”, “treble,” and “volume” flags to return the nominal value instead of the current setting.
nominal frame rate	Returns the nominal frame rate associated with the file. The units are in frames per second multiplied by 1000.
nominal record frame rate	Returns the nominal frame rate associated with the input video signal. The units are in frames per second multiplied by 1000.
number of audio tracks	Returns the number of audio tracks on the media.
number of tracks	Returns the number of tracks on the media. The MCISEQ and MCIWAVE devices return 1, as do most VCR devices. The MCIPIONR device does not support this flag.
number of video tracks	Returns the number of video tracks on the media.
offset	Returns the offset of a SMPTE-based file. The offset is the start time of a SMPTE-based sequence. The time is returned as hh:mm:ss:ff, where hh is hours, mm is minutes, ss is seconds, and ff is frames.
output	Returns the currently set output. If no output is set, the error returned indicates that any device can be used.  For digital-video devices, modifies the “bass”, “treble”, “volume”, “brightness”, “color”, “contrast”, “gamma”, “sharpness”, or “tint” flag so that it applies only to the output. This is the default when monitoring a file.
pause mode	Returns “recording” if the device is paused while recording. It returns “playing” if the device is paused while playing. It returns the error “Action not applicable in current mode” if the device is not paused.
pause timeout	Returns the maximum duration, in milliseconds, of a pause command.
play format	Returns a code indicating the format that the videotape will be played back in, if detectable: “lp”, “ep”, “sp”, or “other”. For more information, see the “record format” flag.
play speed	Returns a value representing how closely the actual playing time of the last AVI sequence matched the target playing time. The value 1000 indicates that the target time and the actual time were the same. A value of 2000, for example, would indicate that the AVI sequence took twice as long to play as it should have. This flag is recognized only by the MCIAVI digital-video driver. It is meant for performance evaluation only; the return value is difficult to interpret.
port	Returns the MIDI port number assigned to the sequence.
position	Returns the current position. For PPQN files, the position is returned in song pointer units. For SMPTE files, it is returned as hh:mm:ss:ff, where hh is hours, mm is minutes, ss is seconds, and ff is frames.
position start	Returns the position of the start of the usable media.
position track number	Returns the position of the start of the track specified by number. For PPQN files, the time format is returned in song pointer units. For SMPTE files, it is returned as hh:mm:ss:ff, where hh is hours, mm is minutes, ss is seconds, and ff is frames. The MCISEQ sequencer returns zero. The MCIPIONR device does not support this flag. The MCIWAVE device returns zero.
postroll duration	Returns the length of videotape, in the current time format, needed to brake the VCR transport when a stop or pause command is issued.
power on	Returns TRUE if the VCR’s power is on.
preroll duration	Returns the length of videotape, in the current time format, needed to stabilize the VCR output.
ready	Returns TRUE if the device is ready to accept another command.
record format	Returns a code indicating the format that the videotape will be recorded in. The current return types are “lp”, “ep”, “sp”, or “other”. These formats are not VHS specific and can be applied to any VCR that has multiple selectable recording formats. The “sp” type is the fastest, highest quality recording format and is used as default on single format VCRs.
record frame rate	Returns the frame rate, in frames per second multiplied by 1000, used for compression.
reference frame	Returns the frame number for the nearest key frame image that precedes the specified frame.
reserved size	Returns the size, in the current time format, of the reserved workspace. The size corresponds to the approximate time it would take to play the compressed data from a full workspace. It returns zero if there is no reserved disk space. This flag returns the approximate size because the precise disk space for compressed data cannot, in general, be predicted until after the data has been compressed.
right volume	Returns the volume set for the right audio channel.
samplespersec	Returns the number of samples per second played or recorded.
seek exactly	Returns “on” or “off”, indicating whether or not the “seek exactly” flag is set.
sharpness	Returns the current sharpness level of the device.
side	Returns 1 or 2 to indicate which side of the videodisc is loaded.
slave	Returns “file”, “midi”, “none”, or “smpte” depending on the type of synchronization set.
smpte	Returns the SMPTE timecode associated with the current position in the workspace. This is a string with the form dd:dd:dd:dd, where each d denotes a digit from 0 to 9. If the workspace data does not include timecode data, then this flag returns 00:00:00:00.
speed	Returns the current speed of the device in frames per second (or in the same format used by the set “speed” command). The MCIPIONR videodisc player does not support this flag.
start position	Returns the starting position of the media.
still file format	Returns the current file format for the capture command.
stretch	Returns TRUE if stretching is enabled.
tempo	Returns the current tempo of a MIDI sequence in the current time format. For files with PPQN format, the tempo is in beats per minute. For files with SMPTE format, the tempo is in frames per second.
time format	Returns the current time format. For more information, see the time formats in the set command.
time mode	Returns the current position time mode. It can be “detect”, “timecode”, or “counter”.
time type	Returns the current position time in use: “timecode” or “counter”.
timecode present	Returns TRUE if timecode has been recorded at the current position on the tape. The timecode must advance from the current position. A VCR might need to be played to check this condition.
timecode record	Returns TRUE if the VCR is set to record timecode.
timecode type	Returns “smpte”, “smpte drop”, “other”, or “none”. Note the frames per second can be obtained from the status “frame rate” command, and the accuracy of the device can be returned by the capability “seek accuracy” command.
tint	Returns the current video-tint level.
treble	Returns the current audio-treble level.
tuner number	Returns the current logical-tuner number.
unsaved	Returns TRUE if there is recorded data in the workspace that might be lost as a result of a close, load, record, reserve, cut, delete, or paste command. Returns FALSE otherwise.
video	Returns “on” or “off”, reflecting the state set by the setvideo command.
video key color	Returns the value for the key color.
video key index	Returns the value for the key index.
video monitor	Returns “output” or one of the valid source-input types. For more information, see the setvideo “monitor” command.
video monitor number	Returns the monitored-video number of the type returned by status “video monitor”. For more information, see the setvideo command.
video record	Returns “on” or “off”, reflecting the current state set by setvideo “record”.
video record track number	Return TRUE if the VCR is set to record video. If no track number is given, the default value of 1 is assumed.
video source	Returns the video-source type. For more information, see the setvideo command.
video source number	Returns a number corresponding to the video source of the type in use. For example, it returns 2 if the second NTSC video source input is being used.
video stream	Returns the current video-stream number.
volume	Returns the average volume to the left and right speaker. This returns an error if the device has not been played or volume has not been set.
window handle	Returns ASCII decimal value for the window handle in the low-order word of the return value.
window maximized	Returns TRUE if the window is maximized.
window minimized	Returns TRUE if the window is minimized.
window visible	Returns TRUE if the window is not hidden.
write protected	Returns TRUE if the device detects that it cannot record (that is, if the write protect is on). If it can record, or if it is unable to determine whether or not it can record (without actually writing), the driver returns FALSE.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns information in the lpstrReturnString parameter of mciSendString. The information is dependent on the request type.

Remarks

Before issuing any commands that use position values, you should set the desired time format by using the set command.

The following command returns the current mode of the “mysound” device:

status mysound mode

See Also

capability, capture, close, cut, delete, load, mciSendString, pause, paste, record, reserve, save, set, setaudio, setvideo, stop, undo


step

The step command steps the play one or more frames forward or reverse. The default action is to step forward one frame. Digital-video, VCR, and CAV-format videodisc devices recognize this command.

wsprintf(lpstrCommand, "step %s %s %s", lpszDeviceID, lpszStepFlags,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszStepFlags

One or both of the following flags:

by frames	Indicates the number of frames to step. If you specify a negative frames value, you cannot specify the “reverse” flag.
reverse	Step the frames in reverse.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.


stop

The stop command stops playback or recording. CD audio, digital-video, MIDI sequencer, videodisc, VCR, and waveform-audio devices recognize this command.

wsprintf(lpstrCommand, "stop %s %s %s", lpszDeviceID, lpszStopFlags,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszStopFlags

For digital-video devices, it can be the following flag:

hold	Prevents the release of resources required to redraw a still image on the screen. The frame buffer remains available for use in updating the display when, for example, the window is moved.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

For CD audio devices, the stop command stops playback and resets the current track position to zero.

The following command stops playback or recording on the “mysound” device:

stop mysound


sysinfo

The sysinfo command retrieves MCI system information. The sysinfo command is an MCI system command; it is interpreted directly by MCI.

wsprintf(lpstrCommand, "sysinfo %s %s %s", lpszDeviceID, lpszRequest,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device or device type. If a device type is specified, it must be a standard MCI device-type name, as listed in the reference material for the capability command. You can specify “all” when the flag specified in lpszRequest allows that possibility.

lpszRequest

One of the following flags:

installname	Returns the name listed in the registry or the SYSTEM.INI file used to install the open device with the specified device identifier.
quantity	Returns the number of MCI devices listed in the registry or the SYSTEM.INI file of the type specified in the lpszDeviceID parameter. This device identifier must be a standard MCI device-type name. Any digits after the device type are ignored. Specifying “all” for lpszDeviceID returns the total number of MCI devices in the system.
quantity open	Returns the number of open MCI devices of the type specified in lpszDeviceID. This device identifier must be a standard MCI device-type name. Specifying “all” for lpszDeviceID returns the total number of open MCI devices in the system.
name index	Returns the name of an MCI device. The device identifier must be a standard MCI device-type name. The index ranges from 1 to the number of devices of that type. If “all” is specified for lpszDeviceID, index ranges from 1 to the total number of devices in the system.
name index open	Returns the name of an open MCI device. The device identifier must be a standard MCI device-type name. The index ranges from 1 to the number of open devices of that device type. If “all” is specified for lpszDeviceID, index ranges from 1 to the total number of open devices in the system.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following command returns the number of open waveform-audio devices:

sysinfo waveaudio quantity open

The following command returns the name (device alias) of the first open waveform-audio device:

sysinfo waveaudio name 1 open

See Also

capability


undo

The undo command reverses the action taken by the most recent successful copy, cut, delete, undo, or paste command. Digital-video devices recognize this command.

wsprintf(lpstrCommand, "undo %s %s", lpszDeviceID, lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszFlags

Can be “wait”, “notify”, “test”, or a combination of these. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

See Also

copy, cut, delete, paste


unfreeze

The unfreeze command reenables video acquisition to the frame buffer after it has been disabled by the freeze command. Digital-video, VCR, and video-overlay devices recognize this command.

wsprintf(lpstrCommand, "unfreeze %s %s %s", lpszDeviceID, lpszUnfreeze,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszUnfreeze

Flag for reenabling video acquisition to the frame buffer. The following table lists device types that recognize the unfreeze command and the flags used by each type:

digitalvideo	at rectangle
overlay	at rectangle
vcr	input output
The following table lists the flags that can be specified in the lpszUnfreeze parameter and their meanings:

at rectangle	Specifies the region that will have video acquisition reenabled. The rectangle is relative to the video buffer origin and is specified as X1 Y1 X2 Y2. The coordinates X1 Y1 specify the upper left corner of the rectangle, and the coordinates X2 Y2 specify the width and height.
input	Unfreeze the input image.
output	Unfreeze the output image. If neither “input” nor “output” is given, “output” is assumed.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video and VCR devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following command unfreezes a region of the video buffer:

unfreeze vboard at 10 20 90 165

See Also

freeze


update

The update command repaints the current frame into the specified device context (DC). Digital-video devices recognize this command.

wsprintf(lpstrCommand, "update %s %s %s", lpszDeviceID, lpszHDC,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszHDC

Handle of a DC. The following table lists device types that recognize the update command and the flags used by each type:

digitalvideo	hdc hdc hdc hdc at rect	paint hdc hdc
The following table lists the flags that can be specified in the lpszHDC parameter and their meanings:

hdc hdc	Specifies the handle of the DC to paint.
hdc hdc at rect	Specifies the clipping rectangle relative to the client rectangle.
paint hdc hdc	Paints the DC when the application receives a WM_PAINT message intended for a DC.
To specify the handle of the DC, use the string “hdc” followed by an ASCII representation of the handle. The rectangle is specified as X1 Y1 X2 Y2. The coordinates X1 Y1 specify the upper left corner of the rectangle, and the coordinates X2 Y2 specify the width and height.

lpszFlags

Can be “wait”, “notify”, or both. For digital-video devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The following command updates the entire display window used by the “movie” device. The number 203 is a handle to a DC obtained from the BeginPaint function:

update movie hdc 203

See Also

BeginPaint, WM_PAINT


where

The where command retrieves the rectangle specifying the source or destination area. This rectangle was specified using the put command. Digital-video, and video-overlay devices recognize this command.

wsprintf(lpstrCommand, "where %s %s %s", lpszDeviceID, lpszRequestRect,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszRequestRect

Flag that identifies the rectangle whose dimensions are retrieved. The following table lists device types that recognize the where command and the flags used by each type:

digitalvideo	destination destination max frame frame max source	source max video video max window window max
overlay	destination frame	source video
The following table lists the flags that can be specified in the lpszRequestRect parameter and their meanings:

destination	Retrieves the destination offset and extent. For video-overlay devices, the destination rectangle defines the area of the display window client area that displays the image data from the frame buffer.
destination max	Retrieves the current size of the client rectangle.
frame	Retrieves the offset and extent of the frame buffer rectangle. The frame buffer rectangle defines the area of the frame buffer that receives incoming video data. Images from the “video” rectangle are scaled into this region.
frame max	Returns the maximum size of the frame buffer.
source	Retrieves the source offset and extent. For video-overlay devices, the source rectangle defines the region of the frame buffer that is displayed in the destination window. The device uses this rectangle to crop the image before it is stretched to fit the destination rectangle on the display.
source max	Retrieves the maximum size of the frame buffer.
video	Retrieves the offset and extent of the video rectangle. The video rectangle defines the region of the incoming video data that is transferred to the frame buffer.
video max	Returns the maximum size of the input.
window	Retrieves the current size and position of the display-window frame.
window max	Retrieves the size of the entire display.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns a rectangle in the lpstrReturnString parameter of the mciSendString function. The rectangle describes the area specified in the lpszRequestRect parameter of this command. The rectangle is specified as X1 Y1 X2 Y2. The coordinates X1 Y1 specify the upper left corner of the rectangle, and the coordinates X2 Y2 specify the width and height.

Remarks

The following command returns the display rectangle of the “movie” device:

where movie destination

See Also

mciSendString, put


window

The window command controls the display window. You can use this command to change the display characteristics of the window or provide a destination window for the driver to use in place of the default display window. Digital-video, and video-overlay devices recognize this command.

wsprintf(lpstrCommand, "window %s %s %s", lpszDeviceID, lpszWindowFlags,
    lpszFlags);

Parameters

lpszDeviceID

Identifier of an MCI device. This identifier or alias is assigned when the device is opened.

lpszWindowFlags

Flag for controlling the display window. The following table lists device types that recognize the window command and the flags used by each type:

digitalvideo	handle hwnd state hide state minimize state restore state show show maximized	show minimized show min noactive show na show noactivate show normal text caption
overlay	fixed handle default handle hwnd state hide state iconic state maximized state minimize state minimized state no action state no activate state normal	state restore state show show maximized show minimized show min noactive show na show noactivate show normal stretch text caption
The following table lists the flags that can be specified in the lpszWindowFlags parameter and their meanings:

fixed	Disables stretching of the image.
handle default	Specifies that the device should set the display window back to the default window created during the open operation. For  video-overlay devices, specifies that the device should create and manage its own destination window.
handle hwnd	Specifies the handle of the destination window to use instead of the default window. The hwnd parameter contains the ASCII numeric equivalent of the window handle returned by the CreateWindow function. Two device instances can use the same window handle provided that each instance updates the video and image pixels in the window as if the other instance did not exist. When video output is disabled with setvideo “off”, an update command will make the destination rectangle a solid color.
show maximized	Maximizes the destination window.
show min noactive	Displays the destination window as an icon.
show minimized	Minimizes the destination window.
show na	Displays the destination window in its current state; the window that is currently active remains active.
show noactivate	Displays the destination window in its most recent size and position; the window that is currently active remains active.
show normal	Activates and displays the destination window in its original size and position. (This is the same as the “state restore” flag.)
state hide	Hides the destination window.
state iconic	Displays the destination window as an icon.
state maximized	Maximizes the destination window.
state minimize	Minimizes the destination window and activates the top-level window in the window-manager’s list.
state minimized	Minimizes the destination window.
state no action	Displays the destination window in its current state. The window that is currently active remains active.
state no activate	Displays the destination window in its most recent size and state. The currently active window remains active.
state normal	Activates and displays the destination window in its original size and position.
state restore	Activates and displays the destination window in its original size and position.
state show	Shows the destination window.
stretch	Enables stretching of the image.
text caption	Specifies the caption for the destination window. If this text contains embedded blanks, the entire caption must be enclosed in quotation marks. The default caption for the default window is blank.
lpszFlags

Can be “wait”, “notify”, or both. For digital-video devices, “test” can also be specified. For more information about these flags, see The Wait, Notify, and Test Flags.

Return Values

Returns zero if successful or an error otherwise.

Remarks

Video-overlay devices typically create and display a window when opened. If your application provides a window to the driver, your application is responsible for managing the messages sent to the window.

Since you can use the status command to retrieve the handle to the driver display window, you can also use the standard window manager functions (such as ShowWindow) to manipulate the window.

The following command displays and sets the caption for the “movie” playback window:

window movie text "Welcome to the Movies" state show

See Also

CreateWindow, open, play, setvideo, ShowWindow, status, update


ICM_ABOUT

The ICM_ABOUT message notifies a video compression driver to display its About dialog box or queries a video compression driver to determine if it has an About dialog box. You can send this message explicitly or by using the ICAbout macro.

ICM_ABOUT

wParam = (DWORD) (UINT) hwnd;

lParam = 0;

Parameters

hwnd

Handle of the parent window of the displayed dialog box.

You can also determine if a driver has an About dialog box by specifying -1 in this parameter, as in the ICQueryAbout macro. The driver returns ICERR_OK if it has an About dialog box or ICERR_UNSUPPORTED otherwise.

Return Values

Returns ICERR_OK if the driver supports this message or ICERR_UNSUPPORTED otherwise.

See Also

ICAbout, ICQueryAbout


ICM_COMPRESS

The ICM_COMPRESS message notifies a video compression driver to compress a frame of data into an application-defined buffer.

ICM_COMPRESS

wParam = (DWORD) (LPVOID) &icc;

lParam = sizeof(ICCOMPRESS);

Parameters

icc

Address of an ICCOMPRESS structure. The following members of this structure specify the compression parameters: lpbiInput, lpInput, lpbiOutput, lpOutput, lpbiPrev, lpPrev, lpckid, lpdwFlags, dwFrameSize, and dwQuality.

The driver should also use the biSizeImage member of the BITMAPINFOHEADER structure associated with lpbiOutput of ICCOMPRESS to return the size of the compressed frame.

lParam

Size, in bytes, of ICCOMPRESS.

Return Values

Returns ICERR_OK if successful or an error otherwise.

See Also

BITMAPINFOHEADER, ICCOMPRESS


ICM_COMPRESS_BEGIN

The ICM_COMPRESS_BEGIN message notifies a video compression driver to prepare to compress data. You can send this message explicitly or by using the ICCompressBegin macro.

ICM_COMPRESS_BEGIN

wParam = (DWORD) (LPVOID) lpbiInput;

lParam = (DWORD) (LPVOID) lpbiOutput;

Parameters

lpbiInput

Address of a BITMAPINFO structure containing the input format.

lpbiOutput

Address of a BITMAPINFO structure containing the output format.

Return Values

Returns ICERR_OK if the driver supports the specified compression or ICERR_BADFORMAT if the input or output format is not supported.

Remarks

The driver should allocate and initialize any tables or memory that it needs for compressing the data formats when it receives the ICM_COMPRESS message.

VCM saves the settings of the most recent ICM_COMPRESS_BEGIN message. The ICM_COMPRESS_BEGIN and ICM_COMPRESS_END messages do not nest. If your driver receives ICM_COMPRESS_BEGIN before compression is stopped with ICM_COMPRESS_END, it should restart compression with new parameters.

See Also

BITMAPINFO, ICM_COMPRESS, ICM_COMPRESS_END, ICCompressBegin


ICM_COMPRESS_END

The ICM_COMPRESS_END message notifies a video compression driver to end compression and free resources allocated for compression. You can send this message explicitly or by using the ICCompressEnd macro.

ICM_COMPRESS_END

wParam = 0;

lParam = 0;

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

VCM saves the settings of the most recent ICM_COMPRESS_BEGIN message. ICM_COMPRESS_BEGIN and ICM_COMPRESS_END do not nest. If your driver receives ICM_COMPRESS_BEGIN before compression is stopped with ICM_COMPRESS_END, it should restart compression with new parameters.

See Also

ICCompressEnd, ICM_COMPRESS_BEGIN


ICM_COMPRESS_FRAMES_INFO

The ICM_COMPRESS_FRAMES_INFO message notifies a compression driver to set the parameters for the pending compression.

ICM_COMPRESS_FRAMES_INFO

wParam = (DWORD) (LPVOID) &icf;

lParam = sizeof(ICCOMPRESSFRAMES);

Parameters

icf

Address of an ICCOMPRESSFRAMES structure. The GetData and PutData members of this structure are not used with this message.

lParam

Size, in bytes, of ICCOMPRESSFRAMES.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

A compressor can use this message to determine how much space to allocate for each frame while compressing.

See Also

ICCOMPRESSFRAMES


ICM_COMPRESS_GET_FORMAT

The ICM_COMPRESS_GET_FORMAT message requests the output format of the compressed data from a video compression driver. You can send this message explicitly or by using the ICCompressGetFormat macro.

ICM_COMPRESS_GET_FORMAT

wParam = (DWORD) (LPVOID) lpbiInput;

lParam = (DWORD) (LPVOID) lpbiOutput;

Parameters

lpbiInput

Address of a BITMAPINFO structure containing the input format.

lpbiOutput

Address of a BITMAPINFO structure to contain the output format. You can specify zero for this parameter to request only the size of the output format, as in the ICCompressGetFormatSize macro.

Return Values

If lpbiOutput is zero, returns the size of the structure.

If lpbiOutput is nonzero, returns ICERR_OK if successful or an error otherwise.

Remarks

If lpbiOutput is nonzero, the driver should fill the BITMAPINFO structure with the default output format corresponding to the input format specified for lpbiInput. If the compressor can produce several formats, the default format should be the one that preserves the greatest amount of information.

See Also

BITMAPINFO, ICCompressGetFormat, ICCompressGetFormatSize


ICM_COMPRESS_GET_SIZE

The ICM_COMPRESS_GET_SIZE message requests that the video compression driver supply the maximum size of one frame of data when compressed into the specified output format. You can send this message explicitly or by using the ICCompressGetSize macro.

ICM_COMPRESS_GET_SIZE

wParam = (DWORD) (LPVOID) lpbiInput;

lParam = (DWORD) (LPVOID) lpbiOutput;

Parameters

lpbiInput

Address of a BITMAPINFO structure containing the input format.

lpbiOutput

Address of a BITMAPINFO structure containing the output format.

Return Values

Returns the maximum number of bytes a single compressed frame can occupy.

Remarks

Typically, applications send this message to determine how large a buffer to allocate for the compressed frame.

The driver should calculate the size of the largest possible frame based on the input and output formats.

See Also

BITMAPINFO, ICCompressGetSize


ICM_COMPRESS_QUERY

The ICM_COMPRESS_QUERY message queries a video compression driver to determine if it supports a specific input format or if it can compress a specific input format to a specific output format. You can send this message explicitly or by using the ICCompressQuery macro.

ICM_COMPRESS_QUERY

wParam = (DWORD) (LPVOID) lpbiInput;

lParam = (DWORD) (LPVOID) lpbiOutput;

Parameters

lpbiInput

Address of a BITMAPINFO structure containing the input format.

lpbiOutput

Address of a BITMAPINFO structure containing the output format. You can specify zero for this parameter to indicate any output format is acceptable.

Return Values

Returns ICERR_OK if the specified compression is supported or ICERR_BADFORMAT otherwise.

Remarks

When a driver receives this message, it should examine the BITMAPINFO structure associated with lpbiInput to determine if it can compress the input format.

See Also

BITMAPINFO, ICCompressQuery


ICM_CONFIGURE

The ICM_CONFIGURE message notifies a video compression driver to display its configuration dialog box or queries a video compression driver to determine if it has a configuration dialog box. You can send this message explicitly or by using the ICConfigure macro.

ICM_CONFIGURE

wParam = (DWORD) (UINT) hwnd;

lParam = 0;

Parameters

hwnd

Handle of the parent window of the displayed dialog box.

You can determine if a driver has a configuration dialog box by specifying
 − 1 in this parameter, as in the ICQueryConfigure macro.

Return Values

Returns ICERR_OK if the driver supports this message or ICERR_UNSUPPORTED otherwise.

Remarks

This message is different from the DRV_CONFIGURE message used for hardware configuration. The dialog box for this message should let the user set and edit the internal state referenced by the ICM_GETSTATE and ICM_SETSTATE messages. For example, this dialog box can let the user change parameters affecting the quality level and other similar compression options.

See Also

DRV_CONFIGURE, ICConfigure, ICM_GETSTATE, ICM_SETSTATE, ICQueryConfigure


ICM_DECOMPRESS

The ICM_DECOMPRESS message notifies a video decompression driver to decompress a frame of data into an application-defined buffer.

ICM_DECOMPRESS

wParam = (DWORD) (LPVOID) &icd;

lParam = sizeof(ICDECOMPRESS);

Parameters

icd

Address of an ICDECOMPRESS structure.

lParam

Size, in bytes, of ICDECOMPRESS.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

If you want the driver to decompress data directly to the screen, send the ICM_DRAW message.

The driver returns an error if this message is received before the ICM_DECOMPRESS_BEGIN message.

See Also

ICDECOMPRESS, ICM_DECOMPRESS_BEGIN, ICM_DRAW


ICM_DECOMPRESS_BEGIN

The ICM_DECOMPRESS_BEGIN message notifies a video decompression driver to prepare to decompress data. You can send this message explicitly or by using the ICDecompressBegin macro.

ICM_DECOMPRESS_BEGIN

wParam = (DWORD) (LPVOID) lpbiInput;

lParam = (DWORD) (LPVOID) lpbiOutput;

Parameters

lpbiInput

Address of a BITMAPINFO structure containing the input format.

lpbiOutput

Address of a BITMAPINFO structure containing the output format.

Return Values

Returns ICERR_OK if the specified decompression is supported or ICERR_BADFORMAT otherwise.

Remarks

When the driver receives this message, it should allocate buffers and do any time-consuming operations so that it can process ICM_DECOMPRESS messages efficiently.

If you want the driver to decompress data directly to the screen, send the ICM_DRAW message.

The ICM_DECOMPRESS_BEGIN and ICM_DECOMPRESS_END messages do not nest. If your driver receives ICM_DECOMPRESSd_BEGIN before decompression is stopped with ICM_DECOMPRESS_END, it should restart decompression with new parameters.

See Also

BITMAPINFO, ICM_DECOMPRESS, ICDecompressBegin, ICM_DECOMPRESS_END, ICM_DRAW


ICM_DECOMPRESS_END

The ICM_DECOMPRESS_END message notifies a video decompression driver to end decompression and free resources allocated for decompression. You can send this message explicitly or by using the ICDecompressEnd macro.

ICM_DECOMPRESS_END

wParam = 0;

lParam = 0;

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

The driver should free any resources allocated for the ICM_DECOMPRESS_BEGIN message.

ICM_DECOMPRESS_BEGIN and ICM_DECOMPRESS_END do not nest. If your driver receives ICM_DECOMPRESS_BEGIN before decompression is stopped with ICM_DECOMPRESS_END, it should restart decompression with new parameters.

See Also

ICDecompressEnd, ICM_DECOMPRESS_BEGIN


ICM_DECOMPRESS_GET_FORMAT

The ICM_DECOMPRESS_GET_FORMAT message requests the output format of the decompressed data from a video decompression driver. You can send this message explicitly or by using the ICDecompressGetFormat macro.

ICM_DECOMPRESS_GET_FORMAT

wParam = (DWORD) (LPVOID) lpbiInput;

lParam = (DWORD) (LPVOID) lpbiOutput;

Parameters

lpbiInput

Address of a BITMAPINFO structure containing the input format.

lpbiOutput

Address of a BITMAPINFO structure to contain the output format. You can specify zero to request only the size of the output format, as in the ICDecompressGetFormatSize macro.

Return Values

If lpbiOutput is zero, returns the size of the structure.

If lpbiOutput is nonzero, returns ICERR_OK if successful or an error otherwise.

Remarks

If lpbiOutput is nonzero, the driver should fill the BITMAPINFO structure with the default output format corresponding to the input format specified for lpbiInput. If the compressor can produce several formats, the default format should be the one that preserves the greatest amount of information.

See Also

BITMAPINFO, ICDecompressGetFormat, ICDecompressGetFormatSize


ICM_DECOMPRESS_GET_PALETTE

The ICM_DECOMPRESS_GET_PALETTE message requests that the video decompression driver supply the color table of the output BITMAPINFOHEADER structure. You can send this message explicitly or by using the ICDecompressGetPalette macro.

ICM_DECOMPRESS_GET_PALETTE

wParam = (DWORD) (LPVOID) lpbiInput;

lParam = (DWORD) (LPVOID) lpbiOutput;

Parameters

lpbiInput

Address of a BITMAPINFOHEADER structure containing the input format.

lpbiOutput

Address of a BITMAPINFOHEADER structure to contain the color table. The space reserved for the color table is always at least 256 colors. You can specify zero for this parameter to return only the size of the color table.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

If lpbiOutput is nonzero, the driver sets the biClrUsed member of BITMAPINFOHEADER to the number of colors in the color table. The driver fills the bmiColors members of BITMAPINFO with the actual colors.

The driver should support this message only if it uses a palette other than the one specified in the input format.

See Also

BITMAPINFO, BITMAPINFOHEADER, ICDecompressGetPalette


ICM_DECOMPRESS_QUERY

The ICM_DECOMPRESS_QUERY message queries a video decompression driver to determine if it supports a specific input format or if it can decompress a specific input format to a specific output format. You can send this message explicitly or by using the ICDecompressQuery macro.

ICM_DECOMPRESS_QUERY

wParam = (DWORD) (LPVOID) lpbiInput;

lParam = (DWORD) (LPVOID) lpbiOutput;

Parameters

lpbiInput

Address of a BITMAPINFO structure containing the input format.

lpbiOutput

Address of a BITMAPINFO structure containing the output format. You can specify zero for this parameter to indicate any output format is acceptable.

Return Values

Returns ICERR_OK if the specified decompression is supported or ICERR_BADFORMAT otherwise.

See Also

BITMAPINFO, ICDecompressQuery


ICM_DECOMPRESS_SET_PALETTE

The ICM_DECOMPRESS_SET_PALETTE message specifies a palette for a video decompression driver to use if it is decompressing to a format that uses a palette. You can send this message explicitly or by using the ICDecompressSetPalette macro.

ICM_DECOMPRESS_SET_PALETTE

wParam = (DWORD) (LPVOID) lpbiPalette;

lParam = 0;

Parameters

lpbiPalette

Address of a BITMAPINFOHEADER structure whose color table contains the colors that should be used if possible. You can specify zero to use the default set of output colors.

Return Values

Returns ICERR_OK if the decompression driver can precisely decompress images to the suggested palette using the set of colors as they are arranged in the palette. Returns ICERR_UNSUPPORTED otherwise.

Remarks

This message should not affect decompression already in progress; rather, colors passed using this message should be returned in response to future ICM_DECOMPRESS_GET_FORMAT and ICM_DECOMPRESS_GET_PALETTE messages. Colors are sent back to the decompression driver in a future ICM_DECOMPRESS_BEGIN message.

This message is used primarily when a driver decompresses images to the screen and another application that uses a palette is in the foreground, forcing the decompression driver to adapt to a foreign set of colors.

See Also

BITMAPINFOHEADER, ICDecompressSetPalette, ICM_DECOMPRESS_BEGIN, ICM_DECOMPRESS_GET_FORMAT, ICM_DECOMPRESS_GET_PALETTE


ICM_DECOMPRESSEX

The ICM_DECOMPRESSEX message notifies a video compression driver to decompress a frame of data directly to the screen, decompress to an upside-down DIB, or decompress images described with source and destination rectangles.

ICM_DECOMPRESSEX

wParam = (DWORD) (LPVOID) &icdex;

lParam = sizeof(ICDECOMPRESSEX);

Parameters

icdex

Address of an ICDECOMPRESSEX structure.

lParam

Size, in bytes, of ICDECOMPRESSEX.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

This message is similar to ICM_DECOMPRESS except that it uses the ICDECOMPRESSEX structure to define its decompression information.

If you want the driver to decompress data directly to the screen, send the ICM_DRAW message.

The driver returns an error if this message is received before the ICM_DECOMPRESSEX_BEGIN message.

See Also

ICDECOMPRESSEX, ICM_DECOMPRESS, ICM_DECOMPRESSEX_BEGIN, ICM_DRAW


ICM_DECOMPRESSEX_BEGIN

The ICM_DECOMPRESSEX_BEGIN message notifies a video compression driver to prepare to decompress data.

ICM_DECOMPRESSEX_BEGIN

wParam = (DWORD) (LPVOID) &icdex;

lParam = sizeof(ICDECOMPRESSEX);

Parameters

icdex

Address of a ICDECOMPRESSEX structure containing the input and output formats.

lParam

Size, in bytes, of ICDECOMPRESSEX.

Return Values

Returns ICERR_OK if the specified decompression is supported or ICERR_BADFORMAT otherwise.

Remarks

When the driver receives this message, it should allocate buffers and do any time-consuming operations so that it can process ICM_DECOMPRESSEX messages efficiently.

If you want the driver to decompress data directly to the screen, send the ICM_DRAW_BEGIN message.

The ICM_DECOMPRESSEX_BEGIN and ICM_DECOMPRESSEX_END messages do not nest. If your driver receives ICM_DECOMPRESSEX_BEGIN before decompression is stopped with ICM_DECOMPRESSEX_END, it should restart decompression with new parameters.

See Also

ICDECOMPRESSEX, ICM_DECOMPRESSEX, ICM_DECOMPRESSEX_END, ICM_DRAW_BEGIN


ICM_DECOMPRESSEX_END

The ICM_DECOMPRESSEX_END message notifies a video decompression driver to end decompression and free resources allocated for decompression. You can send this message explicitly or by using the ICDecompressExEnd macro.

ICM_DECOMPRESSEX_END

wParam = 0;

lParam = 0;

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

The driver frees any resources allocated for the ICM_DECOMPRESSEX_BEGIN message.

ICM_DECOMPRESSEX_BEGIN and ICM_DECOMPRESSEX_END do not nest. If your driver receives ICM_DECOMPRESSEX_BEGIN before decompression is stopped with ICM_DECOMPRESSEX_END, it should restart decompression with new parameters.

See Also

ICDecompressExEnd, ICM_DECOMPRESSEX_BEGIN


ICM_DECOMPRESSEX_QUERY

The ICM_DECOMPRESSEX_QUERY message queries a video compression driver to determine if it supports a specific input format or if it can decompress a specific input format to a specific output format.

ICM_DECOMPRESSEX_QUERY

wParam = (DWORD) (LPVOID) &icdex;

lParam = sizeof(ICDECOMPRESSEX);

Parameters

icdex

Address of a ICDECOMPRESSEX structure containing the input format.

lParam

Size, in bytes, of ICDECOMPRESSEX.

Return Values

Returns ICERR_OK if the specified decompression is supported or ICERR_BADFORMAT otherwise.

See Also

ICDECOMPRESSEX


ICM_DRAW

The ICM_DRAW message notifies a rendering driver to decompress a frame of data and draw it to the screen.

ICM_DRAW

wParam = (DWORD) (LPVOID) &icdraw;

lParam = sizeof(ICDRAW);

Parameters

wParam

Address of an ICDRAW structure.

lParam

Size, in bytes, of ICDRAW.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

If the ICDRAW_UPDATE flag is set in the dwFlags member of ICDRAW, the area of the screen used for drawing is invalid and needs to be updated. The extent of updating depends on the contents of the lpData member.

If lpData is NULL, the driver should update the entire destination rectangle with the current image. If the driver maintains a copy of the image in an off-screen buffer, it can fail this message. If lpData is not NULL, the driver should draw the data and make sure the entire destination is updated.

If the ICDRAW_HURRYUP flag is set in dwFlags, the calling application wants the driver to proceed as quickly as possible, possibly not even updating the screen.

If the ICDRAW_PREROLL flag is set in dwFlags, this video frame is preliminary information and should not be displayed if possible. For example, if play is to start from frame 10, and frame 0 is the nearest previous key frame, frames 0 through 9 will have ICDRAW_PREROLL set.

If you want the driver to decompress data into a buffer, send the ICM_DECOMPRESS message.

See Also

ICDRAW, ICM_DECOMPRESS


ICM_DRAW_BEGIN

The ICM_DRAW_BEGIN message notifies a rendering driver to prepare to draw data.

ICM_DRAW_BEGIN

wParam = (DWORD) (LPVOID) &icdrwBgn;

lParam = sizeof(ICDRAW);

Parameters

icdrwBgn

Address of an ICDRAWBEGIN structure containing the input format.

lParam

Size, in bytes, of ICDRAWBEGIN.

Return Values

Returns ICERR_OK if the driver supports drawing the data to the screen in the specified manner and format, or an error code otherwise. Possible error values include the following:

ICERR_BADFORMAT	Input or output format is not supported.
ICERR_NOTSUPPORTED	Driver does not draw directly to the screen or does not support this message.
Remarks

If you want the driver to decompress data into a buffer, send the ICM_DECOMPRESS_BEGIN message.

The ICM_DRAW_BEGIN and ICM_DRAW_END messages do not nest. If your driver receives ICM_DRAW_BEGIN before decompression is stopped with ICM_DRAW_END, it should restart decompression with new parameters.

See Also

ICDRAWBEGIN, ICM_DECOMPRESS_BEGIN, ICM_DRAW_END


ICM_DRAW_CHANGEPALETTE

The ICM_DRAW_CHANGEPALETTE message notifies a rendering driver that the movie palette is changing. You can send this message explicitly or by using the ICDrawChangePalette macro.

ICM_DRAW_CHANGEPALETTE

wParam = (DWORD) (LPVOID) lpbiInput;

lParam = 0;

Parameters

lpbiInput

Address of a BITMAPINFO structure containing the new format and optional color table.

Return Values

Returns ICERR_OK if successful or FALSE otherwise.

Remarks

This message should be supported by installable rendering handlers that draw DIBs with an internal structure that includes a palette.

See Also

BITMAPINFO, ICDrawChangePalette


ICM_DRAW_END

The ICM_DRAW_END message notifies a rendering driver to decompress the current image to the screen and to release resources allocated for decompression and drawing. You can send this message explicitly or by using the ICDrawEnd macro.

ICM_DRAW_END

wParam = 0;

lParam = 0;

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

The ICM_DRAW_BEGIN and ICM_DRAW_END messages do not nest. If your driver receives ICM_DRAW_BEGIN before decompression is stopped with ICM_DRAW_END, it should restart decompression with new parameters.

See Also

ICDrawEnd, ICM_DRAW_BEGIN


ICM_DRAW_FLUSH

The ICM_DRAW_FLUSH message notifies a rendering driver to render the contents of any image buffers that are waiting to be drawn. You can send this message explicitly or by using the ICDrawFlush macro.

ICM_DRAW_FLUSH

wParam = 0;

lParam = 0;

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

This message is used only by hardware that performs its own asynchronous decompression, timing, and drawing.

See Also

ICDrawFlush


ICM_DRAW_GET_PALETTE

The ICM_DRAW_GET_PALETTE message requests a rendering driver to return a palette.

ICM_DRAW_GET_PALETTE

wParam = 0;

lParam = 0;

Return Values

The driver should return one of the following: a handle of the palette being used, NULL if it doesn't have a handle to return, or ICERR_UNSUPPORTED if it doesn’t support palettes.


ICM_DRAW_GETTIME

The ICM_DRAW_GETTIME message requests a rendering driver that controls the timing of drawing frames to return the current value of its internal clock. You can send this message explicitly or by using the ICDrawGetTime macro.

ICM_DRAW_GETTIME

wParam = (DWORD) (LPVOID) lplTime;

lParam = 0;

Parameters

lplTime

Address to contain the current time. The return value should be specified in samples.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

This message is generally supported by hardware that performs its own asynchronous decompression, timing, and drawing. The message can also be sent if the hardware is being used as the synchronization master.

See Also

ICDrawGetTime


ICM_DRAW_QUERY

The ICM_DRAW_QUERY message queries a rendering driver to determine if it can render data in a specific format. You can send this message explicitly or by using the ICDrawQuery macro.

ICM_DRAW_QUERY

wParam = (DWORD) (LPVOID) lpbiInput;

lParam = 0;

Parameters

lpbiInput

Address of a BITMAPINFO structure containing the input format.

Return Values

Returns ICERR_OK if the driver can render data in the specified format or ICERR_BADFORMAT otherwise.

Remarks

This message differs from the ICM_DRAW_BEGIN message in that it queries the driver in a general sense. ICM_DRAW_BEGIN determines if the driver can draw the data using the specified format under specific conditions, such as stretching the image.

See Also

BITMAPINFO, ICDrawQuery, ICM_DRAW_BEGIN


ICM_DRAW_REALIZE

The ICM_DRAW_REALIZE message notifies a rendering driver to realize its drawing palette while drawing. You can send this message explicitly or by using the ICDrawRealize macro.

ICM_DRAW_REALIZE

wParam = (DWORD) (UINT) (HDC) hdc;

lParam = (DWORD) (BOOL) fBackground;

Parameters

hdc

Handle of the DC used to realize the palette.

fBackground

Background flag. Specify TRUE to realize the palette as a background task or FALSE to realize the palette in the foreground.

Return Values

Returns ICERR_OK if the drawing palette is realized or ICERR_UNSUPPORTED if the palette associated with the decompressed data is realized.

Remarks

Drivers need to respond to this message only if the drawing palette is different from the decompressed palette.

See Also

ICDrawRealize


ICM_DRAW_RENDERBUFFER

The ICM_DRAW_RENDERBUFFER message notifies a rendering driver to draw the frames that have been passed to it. You can send this message explicitly or by using the ICDrawRenderBuffer macro.

ICM_DRAW_RENDERBUFFER

wParam = 0;

lParam = 0;

Return Values

This message does not return a value.

Remarks

Use this message with hardware that performs its own asynchronous decompression, timing, and drawing.

This message is typically used to perform a seek operation when the driver must be specifically instructed to display each video frame passed to it rather than playing a sequence of video frames.

See Also

ICDrawRenderBuffer


ICM_DRAW_SETTIME

The ICM_DRAW_SETTIME provides synchronization information to a rendering driver that handles the timing of drawing frames. The synchronization information is the sample number of the frame to draw. You can send this message explicitly or by using the ICDrawSetTime macro.

ICM_DRAW_SETTIME

wParam = (DWORD) lpTime;

lParam = 0;

Parameters

lpTime

Sample number of the frame to render.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

Typically, the driver compares the specified value with the frame number associated with the time of its internal clock and attempts to synchronize the two if the difference is significant.

Use this message when the hardware performs its own asynchronous decompression, timing, and drawing, and the hardware relies on an external synchronization signal (the hardware is not being used as the synchronization master).

See Also

ICDrawSetTime


ICM_DRAW_START

The ICM_DRAW_START message notifies a rendering driver to start its internal clock for the timing of drawing frames. You can send this message explicitly or by using the ICDrawStart macro.

ICM_DRAW_START

wParam = 0;

lParam = 0;

Return Values

This message does not return a value.

Remarks

This message is used by hardware that performs its own asynchronous decompression, timing, and drawing.

When the driver receives this message, it should start rendering data at the rate specified with the ICM_DRAW_BEGIN message.

The ICM_DRAW_START and ICM_DRAW_STOP messages do not nest. If your driver receives ICM_DRAW_START before rendering is stopped with ICM_DRAW_STOP, it should restart rendering with new parameters.

See Also

ICDrawStart, ICM_DRAW_BEGIN, ICM_DRAW_STOP


ICM_DRAW_START_PLAY

The ICM_DRAW_START_PLAY message provides the start and end times of a play operation to a rendering driver. You can send this message explicitly or by using the ICDrawStartPlay macro.

ICM_DRAW_START_PLAY

wParam = (DWORD) lFrom;

lParam = (DWORD) lTo;

Parameters

lFrom

Start time.

lTo

End time.

Return Values

This message does not return a value.

Remarks

This message precedes any frame data sent to the rendering driver.

Units for lFrom and lTo are specified with the ICM_DRAW_BEGIN message. For video data this is normally a frame number. For more information about the playback rate, see the dwRate and dwScale members of the ICDRAWBEGIN structure.

If the end time is less than the start time, the playback direction is reversed.

See Also

ICDRAWBEGIN, ICDrawStartPlay, ICM_DRAW_BEGIN


ICM_DRAW_STOP

The ICM_DRAW_STOP message notifies a rendering driver to stop its internal clock for the timing of drawing frames. You can send this message explicitly or by using the ICDrawStop macro.

ICM_DRAW_STOP

wParam = 0;

lParam = 0;

Return Values

This message does not return a value.

Remarks

This message is used by hardware that performs its own asynchronous decompression, timing, and drawing.

See Also

ICDrawStop


ICM_DRAW_STOP_PLAY

The ICM_DRAW_STOP_PLAY message notifies a rendering driver when a play operation is complete. You can send this message explicitly or by using the ICDrawStopPlay macro.

ICM_DRAW_STOP_PLAY

wParam = 0;

lParam = 0;

Return Values

This message does not return a value.

Remarks

Use this message when the play operation is complete. Use the ICM_DRAW_STOP message to end timing.

See Also

ICDrawStopPlay, ICM_DRAW_STOP


ICM_DRAW_SUGGESTFORMAT

The ICM_DRAW_SUGGESTFORMAT message queries a rendering driver to suggest a decompressed format that it can draw.

ICM_DRAW_SUGGESTFORMAT

wParam = (DWORD) (LPVOID) &icdrwSuggest;

lParam = sizeof(ICDRAWSUGGEST);

Parameters

icdrwSuggest

Address of an ICDRAWSUGGEST structure.

lParam

Size, in bytes, of ICDRAWSUGGEST.

Return Values

Returns ICERR_OK if successful. If the lpbiSuggest member of the ICDRAWSUGGEST structure is NULL, this message returns the amount of memory required to contain the suggested format.

Remarks

The driver should examine the format specified in the lpbiIn member of the ICDRAWSUGGEST structure and use the lpbiSuggest member to return a format it can draw. The output format should preserve as much data as possible from the input format.

Optionally, the driver can use the installable compressor handle passed in the hicDecompressor member of ICDRAWSUGGEST to make more complex selections. For example, if the input format is 24-bit JPEG data, a renderer could query the decompressor to find out if it can decompress to a YUV format (which might be drawn more efficiently) before selecting the format to suggest.

See Also

ICDRAWSUGGEST


ICM_DRAW_WINDOW

The ICM_DRAW_WINDOW message notifies a rendering driver that the window specified for the ICM_DRAW_BEGIN message needs to be redrawn. The window has moved or become temporarily obscured. You can send this message explicitly or by using the ICDrawWindow macro.

ICM_DRAW_WINDOW

wParam = (DWORD) (LPVOID) prc;

lParam = 0;

Parameters

prc

Address of the destination rectangle in screen coordinates. If this parameter points to an empty rectangle, drawing should be turned off.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

This message is supported by hardware that performs its own asynchronous decompression, timing, and drawing.

Video-overlay drivers use this message to draw when the window is obscured or moved. When a window specified for ICM_DRAW_BEGIN is completely hidden by other windows, the destination rectangle is empty. Drivers should turn off video-overlay hardware when this condition occurs.

See Also

ICDrawWindow, ICM_DRAW_BEGIN


ICM_GET

The ICM_GET message retrieves an application-defined doubleword from a video compression driver.

ICM_GET

wParam = (DWORD) (LPVOID) pv;

lParam = (DWORD) cb;

Parameters

pv

Address of a block of memory to be filled with the current state. You can also specify NULL to determine the amount of memory required by the state information.

cb

Size, in bytes, of the block of memory.

Return Values

Returns the amount of memory, in bytes, required to store the status information.

Remarks

The structure used to represent state information is driver specific and is defined by the driver.


ICM_GETBUFFERSWANTED

The ICM_GETBUFFERSWANTED message queries a driver for the number of buffers to allocate. You can send this message explicitly or by using the ICGetBuffersWanted macro.

ICM_GETBUFFERSWANTED

wParam = (DWORD) (LPVOID) lpdwBuffers;

lParam = 0;

Parameters

lpdwBuffers

Address to contain the number of samples the driver needs to efficiently render the data.

Return Values

Returns ICERR_OK if successful or ICERR_UNSUPPORTED otherwise.

Remarks

This message is used by drivers that use hardware to render data and want to ensure a minimal time lag caused by waiting for buffers to arrive. For example, if a driver controls a video decompression board that can hold 10 frames of video, it could return 10 for this message. This instructs applications to try to stay 10 frames ahead of the frame it currently needs.

See Also

ICGetBuffersWanted


ICM_GETDEFAULTKEYFRAMERATE

The ICM_GETDEFAULTKEYFRAMERATE message queries a video compression driver for its default (or preferred) key-frame spacing. You can send this message explicitly or by using the ICGetDefaultKeyFrameRate macro.

ICM_GETDEFAULTKEYFRAMERATE

wParam = (DWORD) (LPVOID) &dwICValue;

lParam = 0;

Parameters

dwICValue

Address to contain the preferred key-frame spacing.

Return Values

Returns ICERR_OK if the driver supports this message or ICERR_UNSUPPORTED otherwise.

See Also

ICGetDefaultKeyFrameRate


ICM_GETDEFAULTQUALITY

The ICM_GETDEFAULTQUALITY message queries a video compression driver to provide its default quality setting. You can send this message explicitly or by using the ICGetDefaultQuality macro.

ICM_GETDEFAULTQUALITY

wParam = (DWORD) (LPVOID) &dwICValue;

lParam = 0;

Parameters

dwICValue

Address to contain the default quality value. Quality values range from 0 to 10,000.

Return Values

Returns ICERR_OK if the driver supports this message or ICERR_UNSUPPORTED otherwise.

See Also

ICGetDefaultQuality


ICM_GETINFO

The ICM_GETINFO message queries a video compression driver to return a description of itself in an ICINFO structure.

ICM_GETINFO

wParam = (DWORD) (LPVOID) lpicinfo;

lParam = sizeof(icinfo);

Parameters

lpicinfo

Address of an ICINFO structure to contain information.

lParam

Size, in bytes, of ICINFO.

Return Values

Returns the size, in bytes, of ICINFO or zero if an error occurs..

Remarks

Typically, applications send this message to display a list of the installed compressors.

The driver should fill all members of the ICINFO structure except szDriver.

See Also

ICINFO


ICM_GETQUALITY

The ICM_GETQUALITY message queries a video compression driver to return its current quality setting.

ICM_GETQUALITY

wParam = (DWORD) (LPVOID) &dwICValue;

lParam = 0;

Parameters

dwICValue

Address to contain the current quality value. Quality values range from 0 to 10,000.

Return Values

Returns ICERR_OK if the driver supports this message or ICERR_UNSUPPORTED otherwise.


ICM_GETSTATE

The ICM_GETSTATE message queries a video compression driver to return its current configuration in a block of memory or to determine the amount of memory required to retrieve the configuration information. You can send this message explicitly or by using the ICGetState macro.

ICM_GETSTATE

wParam = (DWORD) (LPVOID) pv;

lParam = (DWORD) cb;

Parameters

pv

Address of a block of memory to contain the current configuration information. You can specify NULL for this parameter to determine the amount of memory required for the configuration information, as in ICGetStateSize.

cb

Size, in bytes, of the block of memory.

Return Values

If pv is NULL, returns the amount of memory, in bytes, required for configuration information.

If pv is not NULL, returns ICERR_OK if successful or an error otherwise.

Remarks

The structure used to represent configuration information is driver specific and is defined by the driver.

See Also

ICGetState, ICGetStateSize


ICM_SET_STATUS_PROC

The ICM_SET_STATUS_PROC message provides a status callback function with the status of a lengthy operation.

ICM_SET_STATUS_PROC

wParam = (DWORD) (LPVOID) icsetstatusProc;

lParam = sizeof(icsetstatusProc);

Parameters

icsetstatusProc

Address of an ICSETSTATUSPROC structure.

lParam

Size, in bytes, of ICSETSTATUSPROC.

Return Values

Returns ICERR_OK if successful or an error otherwise.

Remarks

Support of this message is optional but strongly recommended if compression or decompression takes longer than approximately one-tenth of a second.

An application can send this message periodically to a status callback function during lengthy operations.

See Also

ICSETSTATUSPROC


ICM_SETQUALITY

The ICM_SETQUALITY message provides a video compression driver with a quality level to use during compression.

ICM_SETQUALITY

wParam = (DWORD) (LPVOID) &dwICValue;

lParam = 0;

Parameters

dwICValue

New quality value. Quality values range from 0 to 10,000.

Return Values

Returns ICERR_OK if the driver supports this message or ICERR_UNSUPPORTED otherwise.


ICM_SETSTATE

The ICM_SETSTATE message notifies a video compression driver to set the state of the compressor. You can send this message explicitly or by using the ICSetState macro.

ICM_SETSTATE

wParam = (DWORD) (LPVOID) pv;

lParam = (DWORD) cb;

Parameters

pv

Address of a block of memory containing configuration data. You can specify NULL for this parameter to reset the compressor to its default state.

cb

Size, in bytes, of the block of memory.

Return Values

Returns the number of bytes used by the compressor if successful or zero otherwise.

Remarks

The information used by this message is private and specific to a given compressor. Client applications should use this message only to restore information previously obtained with the ICM_GETSTATE message and should use the ICM_CONFIGURE message to adjust the configuration of a video compression driver.

See Also

ICM_CONFIGURE, ICM_GETSTATE, ICSetState


MCIWNDM_CAN_CONFIG

The MCIWNDM_CAN_CONFIG message determines if an MCI device can display a configuration dialog box. You can send this message explicitly or by using the MCIWndCanConfig macro.

MCIWNDM_CAN_CONFIG

wParam = 0;

lParam = 0;

Return Values

Returns TRUE if the device supports configuration or FALSE otherwise.

See Also

MCIWndCanConfig


MCIWNDM_CAN_EJECT

The MCIWNDM_CAN_EJECT message determines if an MCI device can eject its media. You can send this message explicitly or by using the MCIWndCanEject macro.

MCIWNDM_CAN_EJECT

wParam = 0;

lParam = 0;

Return Values

Returns TRUE if the device can eject its media or FALSE otherwise.

See Also

MCIWndCanEject


MCIWNDM_CAN_PLAY

The MCIWNDM_CAN_PLAY message determines if an MCI device can play a data file or content of some other kind. You can send this message explicitly or by using the MCIWndCanPlay macro.

MCIWNDM_CAN_PLAY

wParam = 0;

lParam = 0;

Return Values

Returns TRUE if the device supports playing the data or FALSE otherwise.

See Also

MCIWndCanPlay


MCIWNDM_CAN_RECORD

The MCIWNDM_CAN_RECORD message determines if an MCI device supports recording. You can send this message explicitly or by using the MCIWndCanRecord macro.

MCIWNDM_CAN_RECORD

wParam = 0;

lParam = 0;

Return Values

Returns TRUE if the device supports recording or FALSE otherwise.

See Also

MCIWndCanRecord


MCIWNDM_CAN_SAVE

The MCIWNDM_CAN_SAVE message determines if an MCI device can save data. You can send this message explicitly or by using the MCIWndCanSave macro.

MCIWNDM_CAN_SAVE

wParam = 0;

lParam = 0;

Return Values

Returns TRUE if the device supports saving or FALSE otherwise.

See Also

MCIWndCanSave


MCIWNDM_CAN_WINDOW

The MCIWNDM_CAN_WINDOW message determines if an MCI device supports window-oriented MCI commands. You can send this message explicitly or by using the MCIWndCanWindow macro.

MCIWNDM_CAN_WINDOW

wParam = 0;

lParam = 0;

Return Values

Returns TRUE if the device supports window-oriented MCI commands or FALSE otherwise.

See Also

MCIWndCanWindow


MCIWNDM_CHANGESTYLES

The MCIWNDM_CHANGESTYLES message changes the styles used by the MCIWnd window. You can send this message explicitly or by using the MCIWndChangeStyles macro.

MCIWNDM_CHANGESTYLES

wParam = (WPARAM) (UINT) mask;

lParam = (LPARAM) (LONG) value;

Parameters

mask

Mask that identifies the styles that can change. This mask is the bitwise OR operator of all styles that will be permitted to change.

value

New style settings for the window. Specify zero for this parameter to turn off all styles identified in the mask. For a list of the available styles, see the MCIWndCreate function.

Return Values

Returns zero.

See Also

MCIWndCreate, MCIWndChangeStyles


MCIWNDM_EJECT

The MCIWNDM_EJECT message sends a command to an MCI device to eject its media. You can send this message explicitly or by using the MCIWndEject macro.

MCIWNDM_EJECT

wParam = 0;

lParam = 0;

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWndEject


MCIWNDM_GETACTIVETIMER

The MCIWNDM_GET_ACTIVETIMER message retrieves the update period used when the MCIWnd window is the active window. You can send this message explicitly or by using the MCIWndGetActiveTimer macro.

MCIWNDM_GETACTIVETIMER

wParam = 0;

lParam = 0L;

Return Values

Returns the update period in milliseconds. The default is 500 milliseconds.

See Also

MCIWndGetActiveTimer


MCIWNDM_GETALIAS

The MCIWNDM_GETALIAS message retrieves the alias used to open an MCI device or file with the mciSendString function. You can send this message explicitly or by using the MCIWndGetAlias macro.

MCIWNDM_GETALIAS

wParam = 0;

lParam = 0;

Return Values

Returns the device alias.

See Also

mciSendString, MCIWndGetAlias


MCIWNDM_GET_DEST

The MCIWNDM_GET_DEST message retrieves the coordinates of the destination rectangle used for zooming or stretching the images of an AVI file during playback. You can send this message explicitly or by using the MCIWndGetDest macro.

MCIWNDM_GET_DEST

wParam = 0;

lParam = (LPARAM) (LPRECT) prc;

Parameters

prc

Address of a RECT structure to return the coordinates of the destination rectangle.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWndGetDest, RECT


MCIWNDM_GETDEVICE

The MCIWNDM_GETDEVICE message retrieves the name of the currently open MCI device. You can send this message explicitly or by using the MCIWndGetDevice macro.

MCIWNDM_GETDEVICE

wParam = (WPARAM) (UINT) len;

lParam = (LPARAM) (LPVOID) lp;

Parameters

len

Size, in bytes, of the buffer.

lp

Address of an application-defined buffer to return the device name.

Return Values

Returns zero if successful or a nonzero value otherwise.

Remarks

If the null-terminated string containing the device name is longer than the buffer, MCIWnd truncates it.

See Also

MCIWndGetDevice


MCIWNDM_GETDEVICEID

The MCIWNDM_GETDEVICEID message retrieves the identifier of the currently open MCI device to use with the mciSendCommand function. You can send this message explicitly or by using the MCIWndGetDeviceID macro.

MCIWNDM_GETDEVICEID

wParam = 0;

lParam = 0;

Return Values

Returns the device identifier.

See Also

mciSendCommand, MCIWndGetDeviceID


MCIWNDM_GETEND

The MCIWNDM_GETEND message retrieves the location of the end of the content of an MCI device or file. You can send this message explicitly or by using the MCIWndGetEnd macro.

MCIWNDM_GETEND

wParam = 0;

lParam = 0;

Return Values

Returns the location in the current time format.

See Also

MCIWndGetEnd


MCIWNDM_GETERROR

The MCIWNDM_GETERROR message retrieves the last MCI error encountered. You can send this message explicitly or by using the MCIWndGetError macro.

MCIWNDM_GETERROR

wParam = (WPARAM) (UINT) len;

lParam = (LPARAM) (LPVOID) lp;

Parameters

len

Size, in bytes, of the error buffer.

lp

Address of an application-defined buffer used to return the error string.

Return Values

Returns the integer error value if successful.

Remarks

If lp is a valid pointer, a null-terminated string corresponding to the error is returned in its buffer. If the error string is longer than the buffer, MCIWnd truncates it.

See Also

MCIWndGetError


MCIWNDM_GETFILENAME

The MCIWNDM_GETFILENAME message retrieves the filename currently used by an MCI device. You can send this message explicitly or by using the MCIWndGetFileName macro.

MCIWNDM_GETFILENAME

wParam = (WPARAM) (UINT) len;

lParam = (LPARAM) (LPVOID) lp;

Parameters

len

Size, in bytes, of the buffer.

lp

Address of an application-defined buffer to return the filename.

Return Values

Returns zero if successful or 1 otherwise.

Remarks

If the null-terminated string containing the filename is longer than the buffer, MCIWnd truncates the filename.

See Also

MCIWndGetFileName


MCIWNDM_GETINACTIVETIMER

The MCIWNDM_GETINACTIVETIMER message retrieves the update period used when the MCIWnd window is the inactive window. You can send this message explicitly or by using the MCIWndGetInactiveTimer macro.

MCIWNDM_GETINACTIVETIMER

wParam = 0;

lParam = 0L;

Return Values

Returns the update period, in milliseconds. The default value is 2000 milliseconds.

See Also

MCIWndGetInactiveTimer


MCIWNDM_GETLENGTH

The MCIWNDM_GETLENGTH message retrieves the length of the content or file currently used by an MCI device. You can send this message explicitly or by using the MCIWndGetLength macro.

MCIWNDM_GETLENGTH

wParam = 0;

lParam = 0;

Return Values

Returns the length. The units for the length depend on the current time format.

See Also

MCIWndGetLength


MCIWNDM_GETMODE

The MCIWNDM_GETMODE message retrieves the current operating mode of an MCI device. MCI devices have several operating modes, which are designated by constants. You can send this message explicitly or by using the MCIWndGetMode macro.

MCIWNDM_GETMODE

wParam = (WPARAM) (UINT) len;

lParam = (LPARAM) (LPSTR) lp;

Parameters

len

Size, in bytes, of the buffer.

lp

Address of the application-defined buffer used to return the mode.

Return Values

Returns an integer corresponding to the MCI constant defining the mode.

Remarks

If the null-terminated string describing the mode is longer than the buffer, it is truncated.

Not all devices can operate in every mode. For example, the MCIAVI device is a playback device; it doesn't support the recording mode. The following modes can be retrieved by using MCIWNDM_GETMODE:

Operating mode	MCI constant
not ready	MCI_MODE_NOT_READY
open	MCI_MODE_OPEN
paused	MCI_MODE_PAUSE
playing	MCI_MODE_PLAY
recording	MCI_MODE_RECORD
seeking	MCI_MODE_SEEK
stopped	MCI_MODE_STOP
See Also

MCIWndGetMode


MCIWNDM_GETPALETTE

The MCIWNDM_GETPALETTE message retrieves a handle of the palette used by an MCI device. You can send this message explicitly or by using the MCIWndGetPalette macro.

MCIWNDM_GETPALETTE

wParam = 0;

lParam = 0;

Return Values

Returns the handle of the palette if successful.

See Also

MCIWndGetPalette


MCIWNDM_GETPOSITION

The MCIWNDM_GETPOSITION message retrieves the numerical value of the current position within the content of the MCI device. This macro also provides the current position in string form in an application-defined buffer. You can send this message explicitly or by using the MCIWndGetPosition or MCIWndGetPositionString macro.

MCIWNDM_GETPOSITION

wParam = (WPARAM) (UINT) len;

lParam = (LPARAM) (LPTSTR) lp;

Parameters

len

Size, in bytes, of the buffer. If the null-terminated string is longer than the buffer, it is truncated. Use zero to inhibit retrieval of the position as a string.

lp

Address of an application-defined buffer used to return the position. Use zero to inhibit retrieval of the position as a string.

If the device supports tracks, the string position information is returned in the form TT:MM:SS:FF where TT corresponds to tracks, MM and SS correspond to minutes and seconds, and FF corresponds to frames.

Return Values

Returns an integer corresponding to the current position. The units for the position value depend on the current time format.

See Also

MCIWndGetPosition, MCIWndGetPositionString


MCIWNDM_GETREPEAT

The MCIWNDM_GETREPEAT message determines if continuous playback has been activated. You can send this message explicitly or by using the MCIWndGetRepeat macro.

MCIWNDM_GETREPEAT

wParam = 0;

lParam = 0;

Return Values

Returns TRUE if continuous playback is activated or FALSE otherwise.

See Also

MCIWndGetRepeat


MCIWNDM_GET_SOURCE

The MCIWNDM_GET_SOURCE message retrieves the coordinates of the source rectangle used for cropping the images of an AVI file during playback. You can send this message explicitly or by using the MCIWndGetSource macro.

MCIWNDM_GET_SOURCE

wParam = 0;

lParam = (LPARAM) (LPRECT) prc;

Parameters

prc

Address of a RECT structure to contain the coordinates of the source rectangle.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWndGetSource, RECT


MCIWNDM_GETSPEED

The MCIWNDM_GETSPEED message retrieves the playback speed of an MCI device. You can send this message explicitly or by using the MCIWndGetSpeed macro.

MCIWNDM_GETSPEED

wParam = 0;

lParam = 0;

Return Values

Returns the playback speed if successful. The value for normal speed is 1000. Larger values indicate faster speeds, smaller values indicate slower speeds.

See Also

MCIWndGetSpeed


MCIWNDM_GETSTART

The MCIWNDM_GETSTART message retrieves the location of the beginning of the content of an MCI device or file. You can send this message explicitly or by using the MCIWndGetStart macro.

MCIWNDM_GETSTART

wParam = 0;

lParam = 0;

Remarks

Typically, the return value is zero; but some devices use a nonzero starting location. Seeking to this location sets the device to the start of the media.

Return Values

Returns the location in the current time format.

See Also

MCIWndGetStart


MCIWNDM_GETSTYLES

The MCIWNDM_GETSTYLES message retrieves the flags specifying the current MCIWnd window styles used by a window. You can send this message explicitly or by using the MCIWndGetStyles macro.

MCIWNDM_GETSTYLES

wParam = 0;

lParam = 0;

Return Values

Returns a value representing the current styles of the MCIWnd window. The return value is the bitwise OR operator of the MCIWnd window styles (MCIWNDF flags).

See Also

MCIWndGetStyles


MCIWNDM_GETTIMEFORMAT

The MCIWNDM_GETTIMEFORMAT message retrieves the current time format of an MCI device in two forms: as a numerical value and as a string. You can send this message explicitly or by using the MCIWndGetTimeFormat macro.

MCIWNDM_GETTIMEFORMAT

wParam = (WPARAM) (UINT) len;

lParam = (LPARAM) (LPSTR) lp;

Parameters

len

Size, in bytes, of the buffer.

lp

Address of a buffer to contain the null-terminated string form of the time format.

Return Values

Returns an integer corresponding to the MCI constant defining the time format.

Remarks

If the time format string is longer than the return buffer, MCIWnd truncates the string.

An MCI device can support one or more of the following time formats:

Time format	MCI constant
Bytes	MCI_FORMAT_BYTES
Frames	MCI_FORMAT_FRAMES
Hours, minutes, seconds	MCI_FORMAT_HMS
Milliseconds	MCI_FORMAT_MILLISECONDS
Minutes, seconds, frames	MCI_FORMAT_MSF
Samples	MCI_FORMAT_SAMPLES
SMPTE 24	MCI_FORMAT_SMPTE_24
SMPTE 25	MCI_FORMAT_SMPTE_25
SMPTE 30 drop	MCI_FORMAT_SMPTE_30DROP
SMPTE 30 (non-drop)	MCI_FORMAT_SMPTE_30
Tracks, minutes, seconds, frames	MCI_FORMAT_TMSF
See Also

MCIWndGetTimeFormat


MCIWNDM_GETVOLUME

The MCIWNDM_GETVOLUME message retrieves the current volume setting of an MCI device. You can send this message explicitly or by using the MCIWndGetVolume macro.

MCIWNDM_GETVOLUME

wParam = 0;

lParam = 0;

Return Values

Returns the current volume setting. The default value is 1000. Higher values indicate louder volumes, lower values indicate quieter volumes.

See Also

MCIWndGetVolume


MCIWNDM_GETZOOM

The MCIWNDM_GETZOOM message retrieves the current zoom value used by an MCI device. You can send this message explicitly or by using the MCIWndGetZoom macro.

MCIWNDM_GETZOOM

wParam = 0;

lParam = 0;

Return Values

Returns the most recent values used with MCIWNDM_SETZOOM.

Remarks

A return value of 100 indicates the image is not zoomed. A value of 200 indicates the image is enlarged to twice its original size. A value of 50 indicates the image is reduced to half its original size.

See Also

MCIWndGetZoom, MCIWNDM_SETZOOM


MCIWNDM_NEW

The MCIWNDM_NEW message creates a new file for the current MCI device. You can send this message explicitly or by using the MCIWndNew macro.

MCIWNDM_NEW

wParam = 0;

lParam = (LPARAM) (LPVOID) lp;

Parameters

lp

Address of a buffer containing the name of the MCI device that will use the file.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWndNew


MCIWNDM_NOTIFYERROR

The MCIWNDM_NOTIFYERROR message notifies the parent window of an application that an MCI error occurred.

MCIWNDM_NOTIFYERROR

wParam = (WPARAM) (HWND) hwnd;

lParam = (LPARAM) (LONG) errorCode;

Parameters

hwnd

Handle of the MCIWnd window.

errorCode

Numerical code for the MCI error.

Remarks

You can enable MCI error notification by specifying the MCIWNDF_NOTIFYERROR window style.


MCIWNDM_NOTIFYMEDIA

The MCIWNDM_NOTIFYMEDIA message notifies the parent window of an application that the media has changed.

MCIWNDM_NOTIFYMEDIA

wParam = (WPARAM) (HWND) hwnd;

lParam = (LPARAM) (LPSTR) lp;

Parameters

hwnd

Handle of the MCIWnd window.

lp

Address of a null-terminated string containing the new filename. If the media is closing, it specifies a null string.

Remarks

You can enable notification of media changes by specifying the MCIWNDF_NOTIFYMEDIA window style.


MCIWNDM_NOTIFYMODE

The MCIWNDM_NOTIFYMODE message notifies the parent window of an application that the operating mode of the MCI device has changed.

MCIWNDM_NOTIFYMODE

wParam = (WPARAM) (HWND) hwnd;

lParam = (LPARAM) (LONG) mode;

Parameters

hwnd

Handle of the MCIWnd window.

mode

Integer corresponding to the MCI mode.

Remarks

You can enable notification of mode changes of an MCI device by specifying the MCIWNDF_NOTIFYMODE window style.


MCIWNDM_NOTIFYPOS

The MCIWNDM_NOTIFYPOS message notifies the parent window of an application that the window position has changed.

MCIWNDM_NOTIFYPOS

wParam = (WPARAM) (HWND) hwnd;

lParam = (LPARAM) (LONG) pos;

Parameters

hwnd

Handle of the MCIWnd window.

pos

Describes the new position.

Remarks

You can enable notification of changes in the position of an MCIWnd window by specifying the MCIWNDF_NOTIFYPOS window style.


MCIWNDM_NOTIFYSIZE

The MCIWNDM_NOTIFYSIZE message notifies the parent window of an application that the window size has changed.

MCIWNDM_NOTIFYSIZE

wParam = (WPARAM) (HWND) hwnd;

lParam = 0;

Parameters

hwnd

Handle of the MCIWnd window.

Remarks

You can enable notification of changes in the size of an MCIWnd window by specifying the MCIWNDF_NOTIFYSIZE window style.


MCIWNDM_OPEN

The MCIWNDM_OPEN message opens an MCI device and associates it with an MCIWnd window. For MCI devices that use data files, this macro can also open a specified data file, name a new file to be created, or display a dialog box to let the user select a file to open. You can send this message explicitly or by using the MCIWndOpen macro.

MCIWNDM_OPEN

wParam = (WPARAM) (UINT) wFlags;

lParam = (LPARAM) (LPVOID) szFile;

Parameters

wFlags

Flags associated with the device or file to open. The MCIWNDOPENF_NEW flag specifies a new file is to be created with the name specified in szFile.

szFile

Address of a null-terminated string identifying the filename or MCI device name to open. Specify −1 for this parameter to display the Open dialog box.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWndOpen


MCIWNDM_OPENINTERFACE

The MCIWNDM_OPENINTERFACE message attaches the data stream or file associated with the specified interface to an MCIWnd window. You can send this message explicitly or by using the MCIWndOpenInterface macro.

MCIWNDM_OPENINTERFACE

wParam = 0;

lParam = (LPARAM) (LPUNKNOWN) pUnk;

Parameters

pUnk

Address of an IAVI interface that points to a file or a data stream in a file.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWndOpenInterface


MCIWNDM_PLAYFROM

The MCIWNDM_PLAYFROM message plays the content of an MCI device from the specified location to the end of the content or until another command stops playback. You can send this message explicitly or by using the MCIWndPlayFrom macro.

MCIWNDM_PLAYFROM

wParam = 0;

lParam = (LPARAM) (LONG) lPos;

Parameters

lPos

Starting location. The units for the starting location depend on the current time format.

Return Values

Returns zero if successful or an error otherwise.

Remarks

You can also specify both a starting and ending location for playback by using the MCIWndPlayFromTo macro.

See Also

MCIWndPlayFrom, MCIWndPlayFromTo


MCIWNDM_PLAYTO

The MCIWNDM_PLAYTO message plays the content of an MCI device from the current position to the specified ending location or until another command stops playback. If the specified ending location is beyond the end of the content, playback stops at the end of the content. You can send this message explicitly or by using the MCIWndPlayTo macro.

MCIWNDM_PLAYTO

wParam = 0;

lParam = (LPARAM) (LONG) lEnd;

Parameters

lEnd

Ending location. The units for the ending location depend on the current time format.

Return Values

Returns zero if successful or an error otherwise.

Remarks

This macro is defined using the MCIWndSeek and MCIWndPlayTo macros, which in turn use the MCI_SEEK command and the MCIWNDM_PLAYTO message.

You can also specify both a starting and ending location for playback by using the MCIWndPlayFromTo macro.

See Also

MCI_SEEK, MCIWndPlayFromTo, MCIWndPlayTo, MCIWndSeek


MCIWNDM_PLAYREVERSE

The MCIWNDM_PLAYREVERSE message plays the current content in the reverse direction, beginning at the current position and ending at the beginning of the content or until another command stops playback. You can send this message explicitly or by using the MCIWndPlayReverse macro.

MCIWNDM_PLAYREVERSE

wParam = 0;

lParam = 0;

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWndPlayReverse


MCIWNDM_PUT_DEST

The MCIWNDM_PUT_DEST message redefines the coordinates of the destination rectangle used for zooming or stretching the images of an AVI file during playback. You can send this message explicitly or by using the MCIWndPutDest macro.

MCIWNDM_PUT_DEST

wParam = 0;

lParam = (LPARAM) (LPRECT) prc;

Parameters

prc

Address of a RECT structure containing the coordinates of the destination rectangle.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWndPutDest, RECT


MCIWNDM_PUT_SOURCE

The MCIWNDM_PUT_SOURCE message redefines the coordinates of the source rectangle used for cropping the images of an AVI file during playback. You can send this message explicitly or by using the MCIWndPutSource macro.

MCIWNDM_PUT_SOURCE

wParam = 0;

lParam = (LPARAM) (LPRECT) prc;

Parameters

prc

Address of a RECT structure containing the coordinates of the source rectangle.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWndPutSource, RECT


MCIWNDM_REALIZE

The MCIWNDM_REALIZE message realizes the palette currently used by the MCI device in an MCIWnd window. This macro is defined with the MCIWNDM_REALIZE message. You can send this message explicitly or by using the MCIWndRealize macro.

MCIWNDM_REALIZE

wParam = (WPARAM) (BOOL) fBkgnd;

lParam = 0;

Parameters

fBkgnd

Background flag. Specify TRUE for this parameter if the window is a background application.

Return Values

Returns zero if successful or an error otherwise.

Remarks

MCIWNDM_REALIZE uses the palette of the MCI device and calls the RealizePalette function. If your application explicitly handles the WM_PALETTECHANGED and WM_QUERYNEWPALETTE messages, you should use this message in your application instead of using RealizePalette. If the body of one of these message handlers contains only RealizePalette, forward the message to the MCIWnd window, which will automatically realize the palette.

See Also

MCIWndRealize, RealizePalette, WM_PALETTECHANGED, WM_QUERYNEWPALETTE


MCIWNDM_RETURNSTRING

The MCIWNDM_RETURNSTRING message retrieves the reply to the most recent MCI string command sent to an MCI device. Information in the reply is supplied as a null-terminated string. You can send this message explicitly or by using the MCIWndReturnString macro.

MCIWNDM_RETURNSTRING

wParam = (WPARAM) (UINT) len;

lParam = (LPARAM) (LPVOID) lp;

Parameters

len

Size, in bytes, of the buffer.

lp

Address of an application-defined buffer to contain the null-terminated string.

Return Values

Returns an integer corresponding to the MCI string.

Remarks

If the null-terminated string is longer than the buffer, the string is truncated.

See Also

MCIWndReturnString


MCIWNDM_SENDSTRING

The MCIWNDM_SENDSTRING message sends an MCI command in string form to the device associated with the MCIWnd window. You can send this message explicitly or by using the MCIWndSendString macro.

MCIWNDM_SENDSTRING

wParam = 0;

lParam = (LPARAM) (LPSTR) sz;

Parameters

sz

String command to send to the MCI device.

Return Values

Returns zero if successful or an error otherwise.

Remarks

The message handler for MCIWNDM_SENDSTRING appends a device alias to the MCI command you send to the device. Therefore, you should not use any alias in an MCI command that you issue with MCIWNDM_SENDSTRING.

See Also

MCIWndSendString


MCIWNDM_SETACTIVETIMER

The MCIWNDM_SETACTIVETIMER message sets the update period used by MCIWnd to update the trackbar in the MCIWnd window, update position information displayed in the window title bar, and send notification messages to the parent window when the MCIWnd window is active. You can send this message explicitly or by using the MCIWndSetActiveTimer macro.

MCIWNDM_SETACTIVETIMER

wParam = (WPARAM) (UINT) active;

lParam = 0L;

Parameters

active

Update period, in milliseconds. The default is 500 milliseconds.

Return Values

This message does not return a value.

See Also

MCIWndSetActiveTimer


MCIWNDM_SETINACTIVETIMER

The MCIWNDM_SETINACTIVETIMER message sets the update period used by MCIWnd to update the trackbar in the MCIWnd window, update position information displayed in the window title bar, and send notification messages to the parent window when the MCIWnd window is inactive. You can send this message explicitly or by using the MCIWndSetInactiveTimer macro.

MCIWNDM_SETINACTIVETIMER

wParam = (WPARAM) (UINT) inactive;

lParam = 0;

Parameters

inactive

Update period, in milliseconds. The default is 2000 milliseconds.

Return Values

This message does not return a value.

See Also

MCIWndSetInactiveTimer


MCIWNDM_SETOWNER

The MCIWNDM_SETOWNER message sets the window to receive notification messages associated with the MCIWnd window. You can send this message explicitly or by using the MCIWndSetOwner macro.

MCIWNDM_SETOWNER

wParam = (WPARAM) hwndP;

lParam = 0;

Parameters

hwndP

Handle of the window to receive the notification messages.

Return Values

Returns zero.

See Also

MCIWndSetOwner


MCIWNDM_SETPALETTE

The MCIWNDM_SETPALETTE message sends a palette handle to the MCI device associated with the MCIWnd window. You can send this message explicitly or by using the MCIWndSetPalette macro.

MCIWNDM_SETPALETTE

wParam = (WPARAM) (HPALETTE) hpal;

lParam = 0;

Parameters

hpal

Palette handle.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWndSetPalette


MCIWNDM_SETREPEAT

The MCIWNDM_SETREPEAT message sets the repeat flag associated with continuous playback. The MCIWNDM_SETREPEAT message works in conjunction with the MCI_PLAY command to provide a continuous playback loop. You can send this message explicitly or by using the MCIWndSetRepeat macro.

MCIWNDM_SETREPEAT

wParam = 0;

lParam = (LPARAM) (BOOL) f;

Parameters

f

New state of the repeat flag. Specify TRUE to turn on continuous playback.

Return Values

Returns zero.

Remarks

Currently, MCIAVI is the only device that supports continuous playback.

See Also

MCI_PLAY, MCIWndSetRepeat


MCIWNDM_SETSPEED

The MCIWNDM_SETSPEED message sets the playback speed of an MCI device. You can send this message explicitly or by using the MCIWndSetSpeed macro.

MCIWNDM_SETSPEED

wParam = 0;

lParam = (LPARAM) (UINT) iSpeed;

Parameters

iSpeed

Playback speed. Specify 1000 for normal speed, larger values for faster speeds, and smaller values for slower speeds.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWndSetSpeed


MCIWNDM_SETTIMEFORMAT

The MCIWNDM_SETTIMEFORMAT message sets the time format of an MCI device. You can send this message explicitly or by using the MCIWndSetTimeFormat macro.

MCIWNDM_SETTIMEFORMAT

wParam = 0;

lParam = (LPARAM) (LPSTR) lp;

Parameters

lp

Address of a buffer containing the null-terminated string indicating the time format. Specify “frames” to set the time format to frames, or “ms” to set the time format to milliseconds.

Return Values

Returns zero if successful or an error otherwise.

Remarks

An application can specify time formats other than frames or milliseconds as long as the formats are supported by the MCI device. Noncontinuous formats, such as tracks and SMPTE, can cause the trackbar to behave erratically. For these time formats, you might want to turn off the toolbar by using the MCIWndChangeStyles macro and specifying the MCIWNDF_NOPLAYBAR window style.

If you want to set the time format to frames or milliseconds, you can also use the MCIWndUseFrames or MCIWndUseTime macro. For a list of time formats, see the MCIWndGetTimeFormat macro.

See Also

MCIWndChangeStyles, MCIWndGetTimeFormat, MCIWndSetTimeFormat, MCIWndUseFrames, MCIWndUseTime


MCIWNDM_SETTIMERS

The MCIWNDM_SETTIMERS message sets the update periods used by MCIWnd to update the trackbar in the MCIWnd window, update the position information displayed in the window title bar, and send notification messages to the parent window. You can send this message explicitly or by using the MCIWndSetTimers macro.

MCIWNDM_SETTIMERS

wParam = (WPARAM) (UINT) active;

lParam = (LPARAM) (UINT) inactive;

Parameters

active

Update period used by MCIWnd when it is the active window. The default value is 500 milliseconds. Storage for this value is limited to 16 bits.

inactive

Update period used by MCIWnd when it is the inactive window. The default value is 2000 milliseconds. Storage for this value is limited to 16 bits.

Return Values

This message does not return a value.

See Also

MCIWndSetTimers


MCIWNDM_SETVOLUME

The MCIWNDM_SETVOLUME message sets the volume level of an MCI device. You can send this message explicitly or by using the MCIWndSetVolume macro.

MCIWNDM_SETVOLUME

wParam = 0;

lParam = (LPARAM) (UINT) iVol;

Parameters

iVol

New volume level. Specify 1000 for normal volume level. Specify a higher value for a louder volume or a lower value for a quieter volume.

Return Values

Returns zero if successful or an error otherwise.

See Also

MCIWndSetVolume


MCIWNDM_SETZOOM

The MCIWNDM_SETZOOM message resizes a video image according to a zoom factor. This marco adjusts the size of an MCIWnd window while maintaining a constant aspect ratio. You can send this message explicitly or by using the MCIWndSetZoom macro.

MCIWNDM_SETZOOM

wParam = 0;

lParam = (LPARAM) (UINT) iZoom;

Parameters

iZoom

Zoom factor expressed as a percentage of the original image. Specify 100 to display the image at its authored size, 200 to display the image at twice its normal size, or 50 to display the image at half its normal size.

Return Values

This message does not return a value.

See Also

MCIWndSetZoom


MCIWNDM_VALIDATEMEDIA

The MCIWNDM_VALIDATEMEDIA message updates the starting and ending locations of the content, the current position in the content, and the trackbar according to the current time format. You can send this message explicitly or by using the MCIWndValidateMedia macro.

MCIWNDM_VALIDATEMEDIA

wParam = 0;

lParam = 0;

Return Values

This message does not return a value.

Remarks

Typically, you should not need to use this macro; however, if your application changes the time format of a device without using MCIWnd; the starting and ending locations of the content, as well as the trackbar, continue to use the old format. You can use this macro to update these values.

See Also

MCIWndValidateMedia


MIM_CLOSE

The MIM_CLOSE message is sent to a MIDI input callback function when a MIDI input device is closed.

MIM_CLOSE

dwParam1 = reserved

dwParam2 = reserved

Parameters

dwParam1

Reserved; do not use.

dwParam2

Reserved; do not use.

Return Values

This message does not return a value.

Remarks

The device handle is no longer valid after this message has been sent.


MIM_DATA

The MIM_DATA message is sent to a MIDI input callback function when a MIDI message is received by a MIDI input device.

MIM_DATA

dwParam1 = dwMidiMessage

dwParam2 = dwTimestamp

Parameters

dwMidiMessage

MIDI message that was received. The message is packed into a doubleword value as follows:

High word	High-order byte	Not used.
	Low-order byte	Contains a second byte of MIDI data (when needed).
Low word	High-order byte	Contains the first byte of MIDI data (when needed).
	Low-order byte	Contains the MIDI status.
The two MIDI data bytes are optional, depending on the MIDI status byte.

dwTimestamp

Time that the message was received by the input device driver. The time stamp is specified in milliseconds, beginning at zero when the midiInStart function was called.

Return Values

This message does not return a value.

Remarks

MIDI messages received from a MIDI input port have running status disabled; each message is expanded to include the MIDI status byte.

This message is not sent when a MIDI system-exclusive message is received.

See Also

midiInStart


MIM_ERROR

The MIM_ERROR message is sent to a MIDI input callback function when an invalid MIDI message is received.

MIM_ERROR

dwParam1 = dwMidiMessage

dwParam2 = dwTimestamp

Parameters

dwMidiMessage

Invalid MIDI message that was received. The message is packed into a doubleword value with the first byte of the message in the low-order byte.

dwTimestamp

Time that the message was received by the input device driver. The time stamp is specified in milliseconds, beginning at zero when the midiInStart function was called.

Return Values

This message does not return a value.

See Also

midiInStart


MIM_LONGDATA

The MIM_LONGDATA message is sent to a MIDI input callback function when a system-exclusive buffer has been filled with data and is being returned to the application.

MIM_LONGDATA

dwParam1 = (DWORD) lpMidiHdr

dwParam2 = dwTimestamp

Parameters

lpMidiHdr

Address of a MIDIHDR structure identifying the input buffer.

dwTimestamp

Time that the data was received by the input device driver. The time stamp is specified in milliseconds, beginning at zero when the midiInStart function was called.

Return Values

This message does not return a value.

Remarks

The returned buffer might not be full. To determine the number of bytes recorded into the returned buffer, use the dwBytesRecorded member of the MIDIHDR structure specified by lpMidiHdr.

See Also

midiInStart, MIDIHDR


MIM_LONGERROR

The MIM_LONGERROR message is sent to a MIDI input callback function when an invalid or incomplete MIDI system-exclusive message is received.

MIM_LONGERROR

dwParam1 = (DWORD) lpMidiHdr

dwParam2 = dwTimestamp

Parameters

lpMidiHdr

Address of a MIDIHDR structure identifying the buffer containing the invalid message.

dwTimestamp

Time that the data was received by the input device driver. The time stamp is specified in milliseconds, beginning at zero when the midiInStart function was called.

Return Values

This message does not return a value.

Remarks

The returned buffer might not be full. To determine the number of bytes recorded into the returned buffer, use the dwBytesRecorded member of the MIDIHDR structure specified by lpMidiHdr.

See Also

midiInStart, MIDIHDR


MIM_MOREDATA

The MIM_MOREDATA message is sent to a MIDI input callback function when a MIDI message is received by a MIDI input device but the application is not processing MIM_DATA messages fast enough to keep up with the input device driver. The callback function receives this message only when the application specifies MIDI_IO_STATUS in the call to the midiInOpen function.

MIM_MOREDATA

dwParam1 = dwMidiMessage

dwParam2 = dwTimestamp

Parameters

dwMidiMessage

Specifies the MIDI message that was received. The message is packed into a doubleword value as follows:

High word	High-order byte	Not used.
	Low-order byte	Contains a second byte of MIDI data (when needed).
Low word	High-order byte	Contains the first byte of MIDI data (when needed).
	Low-order byte	Contains the MIDI status.
The two MIDI data bytes are optional, depending on the MIDI status byte.

dwTimestamp

Specifies the time that the message was received by the input device driver. The time stamp is specified in milliseconds, beginning at 0 when the midiInStart function was called.

Return Values

This message does not return a value.

Remarks

An application should do only a minimal amount of processing of MIM_MOREDATA messages. (In particular, applications should not call the PostMessage function while processing MIM_MOREDATA.) Instead, the application should place the event data into a buffer and then return.

When an application receives an MIM_DATA message after a series of MIM_MOREDATA messages, it has caught up with incoming MIDI events and can safely call time-intensive functions.

MIDI messages received from a MIDI input port have running status disabled; each message is expanded to include the MIDI status byte.

This message is not sent when a MIDI system-exclusive message is received.

See Also

midiInOpen, MIM_DATA, PostMessage


MIM_OPEN

The MIM_OPEN message is sent to a MIDI input callback function when a MIDI input device is opened.

MIM_OPEN

dwParam1 = reserved

dwParam2 = reserved

Parameters

dwParam1

Reserved; do not use.

dwParam2

Reserved; do not use.

Return Values

This message does not return a value.


MM_ACM_FILTERCHOOSE

The MM_ACM_FILTERCHOOSE message notifies an acmFilterChoose dialog box hook function before adding an element to one of the three drop-down list boxes. This message allows an application to further customize the selections available through the user interface.

MM_ACM_FILTERCHOOSE

wParam = (WPARAM) wDropDown

lParam = (LONG) lCustom

Parameters

wDropDown

Drop-down list box being initialized and a verify or add operation.

FILTERCHOOSE_CUSTOM_VERIFY

The lParam parameter is a pointer to a WAVEFILTER structure to be added to the custom Name drop-down list box.

FILTERCHOOSE_FILTER_ADD

The lParam parameter is a pointer to a buffer that will accept a WAVEFILTER structure to be added to the Filter drop-down list box. The application must copy the filter structure to be added into this buffer.

FILTERCHOOSE_FILTER_VERIFY

The lParam parameter is a pointer to a WAVEFILTER structure to be added to the Filter drop-down list box.

FILTERCHOOSE_FILTERTAG_ADD

The lParam parameter is a pointer to a DWORD that will accept a waveform-audio filter tag to be added to the Filter Tag drop-down list box.

FILTERCHOOSE_FILTERTAG_VERIFY

The lParam parameter is a waveform-audio filter tag to be listed in the Filter Tag drop-down list box.

lCustom

Value defined by the listbox specified in the wParam parameter.

Return Values

Returns TRUE if an application handles this message or FALSE otherwise.

Remarks

If the application processes the FILTERCHOOSE_FILTER_ADD operation, the size of the memory buffer supplied in lParam will be determined from the acmMetrics function.

If the application processes a verify operation, the application must precede the return value with SetWindowLong(hwnd, DWL_MSGRESULT, (LONG) FALSE) to prevent the dialog box from listing this selection or with SetWindowLong(hwnd, DWL_MSGRESULT, (LONG)TRUE) to allow the dialog box to list this selection. If processing an add operation, the application must precede the return with SetWindowLong(hwnd, DWL_MSGRESULT, (LONG)FALSE) to indicate that no more additions are required or with SetWindowLong(hwnd, DWL_MSGRESULT, (LONG)TRUE) if more additions are required.

See Also

acmFilterChoose, acmMetrics, SetWindowLong, WAVEFILTER


MM_ACM_FORMATCHOOSE

The MM_ACM_FORMATCHOOSE message notifies an acmFormatChoose dialog hook function before adding an element to one of the three drop-down list boxes. This message allows an application to further customize the selections available through the user interface.

MM_ACM_FORMATCHOOSE

wParam = (WPARAM) wDropDown

lParam = (LONG) lCustom

Parameters

wDropDown

Drop-down listbox being initialized and a verify or add operation.

FORMATCHOOSE_CUSTOM_VERIFY

The lParam parameter is a pointer to a WAVEFORMATEX structure to be added to the custom Name drop-down list box.

FORMATCHOOSE_FORMAT_ADD

The lParam parameter is a pointer to a buffer that will accept a WAVEFORMATEX structure to be added to the Format drop-down list box. The application must copy the format structure to be added into this buffer.

FORMATCHOOSE_FORMAT_VERIFY

The lParam parameter is a pointer to a WAVEFORMATEX structure to be added to the Format drop-down list box.

FORMATCHOOSE_FORMATTAG_ADD

The lParam parameter is a pointer to a variable that will accept a waveform-audio format tag to be added to the Format Tag drop-down list box.

FORMATCHOOSE_FORMATTAG_VERIFY

The lParam parameter is a waveform-audio format tag to be listed in the Format Tag drop-down list box.

lCustom

Value defined by the listbox specified in the wParam parameter.

Return Values

Returns TRUE if an application handles this message or FALSE otherwise.

Remarks

If the application processes the FILTERCHOOSE_FORMAT_ADD operation, the size of the memory buffer supplied in lParam will be determined from the acmMetrics function.

If your application is processing a verify operation, it can prevent the dialog box from listing this selection by calling the SetWindowLong function with nIndex set to DWL_MSGRESULT and lNewLong set to FALSE (cast to a LONG data type). To allow the dialog box to list this selection, call this function with lNewLong set to TRUE.

If your application is processing an add operation, it can indicate that no more additions are required by calling the SetWindowLong function with nIndex set to DWL_MSGRESULT and lNewLong set to FALSE (cast to a LONG data type). To indicate more additions are required, call this function with lNewLong set to TRUE.

See Also

acmFormatChoose, acmMetrics, SetWindowLong, WAVEFORMATEX


MM_JOY1BUTTONDOWN

The MM_JOY1BUTTONDOWN message notifies the window that has captured joystick JOYSTICKID1 that a button has been pressed.

MM_JOY1BUTTONDOWN

fwButtons = wParam;

xPos = LOWORD(lParam);

yPos = HIWORD(lParam);

Parameters

fwButtons

Identifies the button that has changed state and the buttons that are pressed. It can be one of the following:

JOY_BUTTON1CHG	First joystick button has changed state.
JOY_BUTTON2CHG	Second joystick button has changed state.
JOY_BUTTON3CHG	Third joystick button has changed state.
JOY_BUTTON4CHG	Fourth joystick button has changed state.
and one or more of the following:

JOY_BUTTON1	First joystick button is pressed.
JOY_BUTTON2	Second joystick button is pressed.
JOY_BUTTON3	Third joystick button is pressed.
JOY_BUTTON4	Fourth joystick button is pressed.
xPos

The x-coordinate of the joystick relative to the upper left corner of the client area.

yPos

The y-coordinate of the joystick relative to the upper left corner of the client area.


MM_JOY1BUTTONUP

The MM_JOY1BUTTONUP message notifies the window that has captured joystick JOYSTICKID1 that a button has been released.

MM_JOY1BUTTONUP

fwButton = wParam;

xPos = LOWORD(lParam);

yPos = HIWORD(lParam);

Parameters

fwButtons

Identifies the button that has changed state and the buttons that are pressed. It can be one of the following:

JOY_BUTTON1CHG	First joystick button has changed state.
JOY_BUTTON2CHG	Second joystick button has changed state.
JOY_BUTTON3CHG	Third joystick button has changed state.
JOY_BUTTON4CHG	Fourth joystick button has changed state.
and one or more of the following:

JOY_BUTTON1	First joystick button is pressed.
JOY_BUTTON2	Second joystick button is pressed.
JOY_BUTTON3	Third joystick button is pressed.
JOY_BUTTON4	Fourth joystick button is pressed.
xPos

The x-coordinates of the joystick relative to the upper left corner of the client area.

yPos

The y-coordinate of the joystick relative to the upper left corner of the client area.


MM_JOY1MOVE

The MM_JOY1MOVE message notifies the window that has captured joystick JOYSTICKID1 that the joystick position has changed.

MM_JOY1MOVE

fwButtons = wParam;

xPos = LOWORD(lParam);

yPos = HIWORD(lParam);

Parameters

fwButtons

Identifies the buttons that are pressed. It can be one or more of the following values:

JOY_BUTTON1	First joystick button is pressed.
JOY_BUTTON2	Second joystick button is pressed.
JOY_BUTTON3	Third joystick button is pressed.
JOY_BUTTON4	Fourth joystick button is pressed.
xPos

The x-coordinates of the joystick relative to the upper left corner of the client area.

yPos

The y-coordinate of the joystick relative to the upper left corner of the client area.


MM_JOY1ZMOVE

The MM_JOY1ZMOVE message notifies the window that has captured joystick JOYSTICKID1 that the joystick position on the z-axis has changed.

MM_JOY1ZMOVE

fwButtons = wParam;

zPos = LOWORD(lParam);

Parameters

fwButtons

Identifies the buttons that are pressed. It can be one or more of the following values:

JOY_BUTTON1	First joystick button is pressed.
JOY_BUTTON2	Second joystick button is pressed.
JOY_BUTTON3	Third joystick button is pressed.
JOY_BUTTON4	Fourth joystick button is pressed.
zPos

The z-coordinate of the joystick.


MM_JOY2BUTTONDOWN

The MM_JOY2BUTTONDOWN message notifies the window that has captured joystick JOYSTICKID2 that a button has been pressed.

MM_JOY2BUTTONDOWN

fwButtons = wParam;

xPos = LOWORD(lParam);

yPos = HIWORD(lParam);

Parameters

fwButtons

Identifies the button that has changed state and the buttons that are pressed. It can be one of the following:

JOY_BUTTON1CHG	First joystick button has changed state.
JOY_BUTTON2CHG	Second joystick button has changed state.
JOY_BUTTON3CHG	Third joystick button has changed state.
JOY_BUTTON4CHG	Fourth joystick button has changed state.
and one or more of the following:

JOY_BUTTON1	First joystick button is pressed.
JOY_BUTTON2	Second joystick button is pressed.
JOY_BUTTON3	Third joystick button is pressed.
JOY_BUTTON4	Fourth joystick button is pressed.
xPos

The x-coordinates of the joystick relative to the upper left corner of the client area.

yPos

The y-coordinate of the joystick relative to the upper left corner of the client area.


MM_JOY2BUTTONUP

The MM_JOY2BUTTONUP message notifies the window that has captured joystick JOYSTICKID2 that a button has been released.

MM_JOY2BUTTONUP

fwButton = wParam;

xPos = LOWORD(lParam);

yPos = HIWORD(lParam);

Parameters

fwButtons

Identifies the button that has changed state and the buttons that are pressed. It can be one of the following:

JOY_BUTTON1CHG	First joystick button has changed state.
JOY_BUTTON2CHG	Second joystick button has changed state.
JOY_BUTTON3CHG	Third joystick button has changed state.
JOY_BUTTON4CHG	Fourth joystick button has changed state.
and one or more of the following:

JOY_BUTTON1	First joystick button is pressed.
JOY_BUTTON2	Second joystick button is pressed.
JOY_BUTTON3	Third joystick button is pressed.
JOY_BUTTON4	Fourth joystick button is pressed.
xPos

The x-coordinates of the joystick relative to the upper left corner of the client area.

yPos

The y-coordinate of the joystick relative to the upper left corner of the client area.


MM_JOY2MOVE

The MM_JOY2MOVE message notifies the window that has captured joystick JOYSTICKID2 that the joystick position has changed.

MM_JOY2MOVE

fwButtons = wParam;

xPos = LOWORD(lParam);

yPos = HIWORD(lParam);

Parameters

fwButtons

Identifies the buttons that are pressed. It can be one or more of the following values:

JOY_BUTTON1	First joystick button is pressed.
JOY_BUTTON2	Second joystick button is pressed.
JOY_BUTTON3	Third joystick button is pressed.
JOY_BUTTON4	Fourth joystick button is pressed.
xPos

The x-coordinates of the joystick relative to the upper left corner of the client area.

yPos

The y-coordinate of the joystick relative to the upper left corner of the client area.


MM_JOY2ZMOVE

The MM_JOY2ZMOVE message notifies the window that has captured joystick JOYSTICKID2 that the joystick position on the z-axis has changed.

MM_JOY2ZMOVE

fwButtons = wParam;

zPos = LOWORD(lParam);

Parameters

fwButtons

Identifies the buttons that are pressed. It can be one or more of the following values:

JOY_BUTTON1	First joystick button is pressed.
JOY_BUTTON2	Second joystick button is pressed.
JOY_BUTTON3	Third joystick button is pressed.
JOY_BUTTON4	Fourth joystick button is pressed.
zPos

The z-coordinate of the joystick.


MM_MCINOTIFY

The MM_MCINOTIFY message notifies an application that an MCI device has completed an operation. MCI devices send this message only when the MCI_NOTIFY flag is used.

MM_MCINOTIFY

wParam = (WPARAM) wFlags

lParam = (LONG) lDevID

Parameters

wFlags

Reason for the notification. The following values are defined:

MCI_NOTIFY_ABORTED

The device received a command that prevented the current conditions for initiating the callback function from being met. If a new command interrupts the current command and it also requests notification, the device sends this message only and not MCI_NOTIFY_SUPERCEDED.

MCI_NOTIFY_FAILURE

A device error occurred while the device was executing the command.

MCI_NOTIFY_SUCCESSFUL

The conditions initiating the callback function have been met.

MCI_NOTIFY_SUPERSEDED

The device received another command with the “notify” flag set and the current conditions for initiating the callback function have been superseded.

lDevID

Identifier of the device initiating the callback function.

Return Values

Returns zero if successful or an error otherwise.

Remarks

For more information about the MCI_NOTIFY flag, see The Notify Flag.

A device returns the MCI_NOTIFY_SUCCESSFUL flag with MM_MCINOTIFY when the action for a command finishes. For example, a CD audio device uses this flag for notification for the play (MCI_PLAY) command when the device finishes playing. The play command is successful only when it reaches the specified end position or reaches the end of the media. Similarly, the seek (MCI_SEEK) and record (MCI_RECORD) commands do not return MCI_NOTIFY_SUCCESSFUL until they reach the specified end position or reach the end of the media.

A device returns the MCI_NOTIFY_ABORTED flag with MM_MCINOTIFY only when it receives a command that prevents it from meeting the notification conditions. For example, the play command would not abort notification for a previous play command provided that the new command does not change the play direction or change the ending position. The seek and record commands behave similarly. MCI also does not send MCI_NOTIFY_ABORTED when playback or recording is paused with the pause (MCI_PAUSE) command. Sending the resume (MCI_RESUME) command allows them to continue to meet the callback conditions.

When your application requests notification for a command, check the error return of the mciSendString or mciSendCommand functions. If these functions encounter an error and return a nonzero value, MCI will not set notification for the command.

See Also

MCI_PAUSE, MCI_PLAY, MCI_RECORD, MCI_RESUME, MCI_SEEK, mciSendString, mciSendCommand, pause, play, record, resume, seek


MM_MCISIGNAL

The MM_MCISIGNAL message is sent to a window to notify an application that an MCI device has reached a position defined in a previous signal (MCI_SIGNAL) command.

MM_MCISIGNAL

wParam = (WPARAM) wID
lParam = (LONG) lUserParm

Parameters

wID

Identifier of the device initiating the signal message.

lUserParm

Value passed in the dwUserParm member of the MCI_DGV_SIGNAL_PARAMS structure when the signal command has defined this callback function. Alternatively, it might contain the position value.

See Also

signal, MCI_SIGNAL


MM_MIM_CLOSE

The MM_MIM_CLOSE message is sent to a window when a MIDI input device is closed.

MM_MIM_CLOSE

wParam = (WPARAM) hInput

lParam = reserved

Parameters

hInput

Handle of the MIDI input device that was closed.

lParam

Reserved; do not use.

Return Values

This message does not return a value.

Remarks

The device handle is no longer valid after this message has been sent.


MM_MIM_DATA

The MM_MIM_DATA message is sent to a window when a complete MIDI message is received by a MIDI input device.

MM_MIM_DATA

wParam = (WPARAM) hInput

lParam = (LPARAM) (DWORD) lMidiMessage

Parameters

hInput

Handle of the MIDI input device that received the MIDI message.

lMidiMessage

MIDI message that was received. The message is packed into a doubleword value as follows:

High word	High-order byte	Not used.
	Low-order byte	Contains a second byte of MIDI data (when needed).
Low word	High-order byte	Contains the first byte of MIDI data (when needed).
	Low-order byte	Contains the MIDI status.
The two MIDI data bytes are optional, depending on the MIDI status byte.

Return Values

This message does not return a value.

Remarks

MIDI messages received from a MIDI input port have running status disabled; each message is expanded to include the MIDI status byte.

This message is not sent when a MIDI system-exclusive message is received. No time stamp is available with this message. For time-stamped input data, you must use the messages that are sent to callback functions.


MM_MIM_ERROR

The MM_MIM_ERROR message is sent to a window when an invalid MIDI message is received.

MM_MIM_ERROR

wParam = (WPARAM) hInput

lParam = (LPARAM) (DWORD) lMidiMessage

Parameters

hInput

Handle of the MIDI input device that received the invalid message.

lMidiMessage

Invalid MIDI message. The message is packed into a doubleword value with the first byte of the message in the low-order byte.

Return Values

This message does not return a value.


MM_MIM_LONGDATA

The MM_MIM_LONGDATA message is sent to a window when either a complete MIDI system-exclusive message is received or when a buffer has been filled with system-exclusive data.

MM_MIM_LONGDATA

wParam = (WPARAM) hInput

lParam = (LPARAM) lpMidiHdr

Parameters

hInput

Handle of the MIDI input device that received the data.

lpMidiHdr

Address of a MIDIHDR structure identifying the buffer.

Return Values

This message does not return a value.

Remarks

The returned buffer might not be full. To determine the number of bytes recorded into the returned buffer, use the dwBytesRecorded member of the MIDIHDR structure pointed to by lpMidiHdr.

No time stamp is available with this message. For time-stamped input data, you must use the messages that are sent to callback functions.

See Also

MIDIHDR


MM_MIM_LONGERROR

The MM_MIM_LONGERROR message is sent to a window when an invalid or incomplete MIDI system-exclusive message is received.

MM_MIM_LONGERROR

wParam = (WPARAM) hInput

lParam = (LPARAM) lpMidiHdr

Parameters

hInput

Handle of the MIDI input device that received the invalid message.

lpMidiHdr

Address of a MIDIHDR structure identifying the buffer containing the invalid message.

Return Values

This message does not return a value.

Remarks

The returned buffer might not be full. To determine the number of bytes recorded into the returned buffer, use the dwBytesRecorded member of the MIDIHDR structure specified by lpMidiHdr.

See Also

MIDIHDR


MM_MIM_MOREDATA

The MM_MIM_MOREDATA message is sent to a callback window when a MIDI message is received by a MIDI input device but the application is not processing MIM_DATA messages fast enough to keep up with the input device driver. The window receives this message only when the application specifies MIDI_IO_STATUS in the call to the midiInOpen function.

MM_MIM_MOREDATA

wParam = (WPARAM) hInput

lParam = (LPARAM) (DWORD) lMidiMessage

Parameters

hInput

Handle of the MIDI input device that received the MIDI message.

lMidiMessage

Specifies the MIDI message that was received. The message is packed into a doubleword value as follows:

High word	High-order byte	Not used.
	Low-order byte	Contains a second byte of MIDI data (when needed).
Low word	High-order byte	Contains the first byte of MIDI data (when needed).
	Low-order byte	Contains the MIDI status.
The two MIDI data bytes are optional, depending on the MIDI status byte.

Return Values

This message does not return a value.

Remarks

If your application will receive MIDI data faster than it can process it, you should not use a window callback mechanism. To maximize speed, use a callback function, and use the MIM_MOREDATA message instead of MM_MIM_MOREDATA.

An application should do only a minimal amount of processing of MM_MIM_MOREDATA messages. (In particular, applications should not call the PostMessage function while processing MM_MIM_MOREDATA.) Instead, the application should place the event data into a buffer and then return.

When an application receives an MM_MIM_DATA message after a series of MM_MIM_MOREDATA messages, it has caught up with incoming MIDI events and can safely call time-intensive functions.

MIDI messages received from a MIDI input port have running status disabled; each message is expanded to include the MIDI status byte.

This message is not sent when a MIDI system-exclusive message is received. No time stamp is available with this message. For time-stamped input data, you must use the messages that are sent to callback functions.

See Also

midiInOpen, MIM_DATA, MIM_MOREDATA, MM_MIM_DATA, PostMessage


MM_MIM_OPEN

The MM_MIM_OPEN message is sent to a window when a MIDI input device is opened.

MM_MIM_OPEN

wParam = (WPARAM) hInput

lParam = reserved

Parameters

hInput

Handle of the MIDI input device that was opened.

lParam

Reserved; do not use.

Return Values

This message does not return a value.


MM_MIXM_CONTROL_CHANGE

The MM_MIXM_CONTROL_CHANGE message is sent by a mixer device to notify an application that the state of a control associated with an audio line has changed. The application should refresh its display and cached values for the specified control.

MM_MIXM_CONTROL_CHANGE

wParam = (WPARAM) hMixer

lParam = (LPARAM) dwControlID

Parameters

hMixer

Handle of the mixer device (HMIXER) that sent the notification message.

dwControlID

Control identifier for the mixer control that has changed state. This identifier is the same as the dwControlID member of the MIXERCONTROL structure returned by the mixerGetLineControls function.

Remarks

An application must open a mixer device and specify a callback window to receive the MM_MIXM_CONTROL_CHANGE message.

See Also

mixerGetLineControls, MIXERCONTROL


MM_MIXM_LINE_CHANGE

The MM_MIXM_LINE_CHANGE message is sent by a mixer device to notify an application that the state of an audio line on the specified device has changed. The application should refresh its display and cached values for the specified audio line.

MM_MIXM_LINE_CHANGE

wParam = (WPARAM) hMixer

lParam = (LPARAM) dwLineID

Parameters

hMixer

Handle of the mixer device that sent the notification message.

dwLineID

Line identifier for the audio line that has changed state. This identifier is the same as the dwLineID member of the MIXERLINE structure returned by the mixerGetLineInfo function.

Remarks

An application must open a mixer device and specify a callback window to receive the MM_MIXM_LINE_CHANGE message.

See Also

mixerGetLineInfo, MIXERLINE


MM_MOM_CLOSE

The MM_MOM_CLOSE message is sent to a window when a MIDI output device is closed.

MM_MOM_CLOSE

wParam = (WPARAM) hOutput

lParam = reserved

Parameters

hOutput

Handle of the MIDI output device.

lParam

Reserved; do not use.

Return Values

This message does not return a value.

Remarks

The device handle is no longer valid after this message has been sent.


MM_MOM_DONE

The MM_MOM_DONE message is sent to a window when the specified MIDI system-exclusive or stream buffer has been played and is being returned to the application.

MM_MOM_DONE

wParam = (WPARAM) hOutput

lParam = (LPARAM) lpMidiHdr

Parameters

hOutput

Handle of the MIDI output device that played the buffer.

lpMidiHdr

Address of a MIDIHDR structure identifying the buffer.

Return Values

This message does not return a value.

See Also

MIDIHDR


MM_MOM_OPEN

The MM_MOM_OPEN message is sent to a window when a MIDI output device is opened.

MM_MOM_OPEN

wParam = (WPARAM) hOutput

lParam = reserved

Parameters

hOutput

Handle of the MIDI output device.

lParam

Reserved; do not use.

Return Values

This message does not return a value.


MM_MOM_POSITIONCB

The MM_MOM_POSITIONCB message is sent to a window when an MEVT_F_CALLBACK event is reached in the MIDI output stream.

MM_MOM_POSITIONCB

wParam = (WPARAM) lpMidiHdr

lParam = reserved

Parameters

lpMidiHdr

Address of a MIDIHDR structure that identifies the event that caused the callback. The dwOffset member gives the offset of the event.

lParam

Reserved; do not use.

Return Values

This message does not return a value.

Remarks

Playback of the stream buffer continues even while the callback function is executing. Any events after the MEVT_F_CALLBACK event in the buffer will be scheduled and sent on time regardless of how much time is spent in the callback function.

If position callbacks are being generated more quickly than your application can process them, the dwOffset member of the MIDIHDR structure might refer to an event your application has not yet processed.

See Also

MIDIHDR


MMIOM_CLOSE

The MMIOM_CLOSE message is sent to an I/O procedure by the mmioClose function to request that a file be closed.

MMIOM_CLOSE

lParam1 = (LPARAM) lCloseFlags

lParam2 = reserved

Parameters

lCloseFlags

Flags contained in the wFlags parameter of mmioClose.

Return Values

Returns zero if the file is successfully closed or an error otherwise.

See Also

mmioClose


MMIOM_OPEN

The MMIOM_OPEN message is sent to an I/O procedure by the mmioOpen function to request that a file be opened or deleted.

MMIOM_OPEN

lParam1 = (LPARAM) lpszFileName

lParam2 = reserved

Parameters

lpszFileName

Null-terminated string containing the name of the file to open.

lParam2

Reserved.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

MMIOM_CANNOTOPEN	The file could not be opened.
MMIOM_OUTOFMEMORY	Not enough memory to perform the operation.
Remarks

The dwFlags member of the MMIOINFO structure contains flags passed to the mmioOpen function.

The lDiskOffset member of the MMIOINFO structure is initialized to zero. If this value is incorrect, the I/O procedure must correct it.

If the application passed an MMIOINFO structure to mmioOpen, the return value is returned in the wErrorRet member.

See Also

MMIOINFO, mmioOpen


MMIOM_READ

The MMIOM_READ message is sent to an I/O procedure by the mmioRead function to request that a specified number of bytes be read from an open file.

MMIOM_READ

lParam1 = (LPARAM) lBuffer

lParam2 = (LPARAM) cbRead

Parameters

lBuffer

Address of the buffer to be filled with data read from the file.

cbRead

Number of bytes to read from file.

Return Values

Returns the number of bytes actually read from the file. If no more bytes can be read, the return value is 0. If there is an error, the return value is − 1.

Remarks

The I/O procedure is responsible for updating the lDiskOffset member of the MMIOINFO structure to reflect the new file position after the read operation.

See Also

mmioRead, MMIOINFO


MMIOM_RENAME

The MMIOM_RENAME message is sent to an I/O procedure by the mmioRename function to request that the specified file be renamed.

MMIOM_RENAME

lParam1 = (LPARAM) lpszOldFilename

lParam2 = (LPARAM) lpszNewFilename

Parameters

lpszOldFilename

Address of a string containing the filename of the file to rename.

lpszNewFilename

Address of a string containing the new filename.

Return Values

If the file is renamed successfully, the return value is zero. If the specified file was not found, the return value is MMIOERR_FILENOTFOUND.

See Also

mmioRename


MMIOM_SEEK

The MMIOM_SEEK message is sent to an I/O procedure by the mmioSeek function to request that the current file position be moved.

MMIOM_SEEK

lParam1 = (LPARAM) lNewFilePos

lParam2 = (LPARAM) lChangeFlag

Parameters

lNewFilePos

New file position. The meaning of this value is dependent on the flag specified in lChangeFlag.

lChangeFlag

Flag specifying how the file position is changed. The following values are defined:

SEEK_CUR

Move the file position to be lNewFilePos bytes from the current position. NewFilePos can be positive or negative.

SEEK_END

Move the file position to be lNewFilePos bytes from the end of the file.

SEEK_SET

Move the file position to be lNewFilePos bytes from the beginning of the file.

Return Values

Returns the new file position. If there is an error, the return value is − 1.

Remarks

The I/O procedure is responsible for maintaining the current file position in the lDiskOffset member of the MMIOINFO structure.

See Also

mmioSeek, MMIOINFO


MMIOM_WRITE

The MMIOM_WRITE message is sent to an I/O procedure by the mmioWrite function to request that data be written to an open file.

MMIOM_WRITE

lParam1 = (LPARAM) lpBuffer

lParam2 = (LPARAM) cbWrite

Parameters

lpBuffer

Address of a buffer containing the data to write to the file.

cbWrite

Number of bytes to write to file.

Return Values

Returns the number of bytes actually written to the file. If there is an error, the return value is − 1.

Remarks

The I/O procedure is responsible for updating the lDiskOffset member of the MMIOINFO structure to reflect the new file position after the write operation.

See Also

mmioWrite, MMIOINFO


MMIOM_WRITEFLUSH

The MMIOM_WRITEFLUSH message is sent to an I/O procedure by the mmioWrite function to request that data be written to an open file and that any internal buffers used by the I/O procedure be flushed to disk.

MMIOM_WRITEFLUSH

lParam1 = (LPARAM) lpBuffer

lParam2 = (LPARAM) cbWrite

Parameters

lpBuffer

Address of a buffer containing the data to write to the file.

cbWrite

Number of bytes to write to file.l

Return Values

Returns the number of bytes actually written to the file. If there is an error, the return value is − 1.

Remarks

The I/O procedure is responsible for updating the lDiskOffset member of the MMIOINFO structure to reflect the new file position after the write operation.

This message is equivalent to the MMIOM_WRITE message except that it requests that the I/O procedure flush its internal buffers, if any. Unless an I/O procedure performs internal buffering, this message can be handled exactly like the MMIOM_WRITE message.

See Also

mmioWrite, MMIOINFO, MMIOM_WRITE


MM_WIM_CLOSE

The MM_WIM_CLOSE message is sent to a window when a waveform-audio input device is closed. The device handle is no longer valid after this message has been sent.

MM_WIM_CLOSE

wParam = (WPARAM) hInputDev

lParam = reserved

Parameters

hInputDev

Handle of the waveform-audio input device that was closed.

lParam

Reserved; must be zero.

Return Values

This message does not return a value.


MM_WIM_DATA

The MM_WIM_DATA message is sent to a window when waveform-audio data is present in the input buffer and the buffer is being returned to the application. The message can be sent either when the buffer is full or after the waveInReset function is called.

MM_WIM_DATA

wParam = (WPARAM) hInputDev

lParam = (LONG) lpwvhdr

Parameters

hInputDev

Handle of the waveform-audio input device that received the data.

lpwvhdr

Address of a WAVEHDR structure that identifies the buffer containing the data.

Return Values

This message does not return a value.

Remarks

The returned buffer might not be full. Use the dwBytesRecorded member of the WAVEHDR structure specified by lParam to determine the number of bytes recorded into the returned buffer.

See Also

waveInReset, WAVEHDR


MM_WIM_OPEN

The MM_WIM_OPEN message is sent to a window when a waveform-audio input device is opened.

MM_WIM_OPEN

wParam = (WPARAM) hInputDev

lParam = reserved

Parameters

hInputDev

Handle of the device that was opened.

lParam

Reserved; must be zero.

Return Values

This message does not return a value.


MM_WOM_CLOSE

The MM_WOM_CLOSE message is sent to a window when a waveform-audio output device is closed. The device handle is no longer valid after this message has been sent.

MM_WOM_CLOSE

wParam = (WPARAM) hOutputDev

lParam = reserved

Parameters

hOutputDev

Handle of the device that was closed.

lParam

Reserved; must be zero.

Return Values

This message does not return a value.


MM_WOM_DONE

The MM_WOM_DONE message is sent to a window when the given output buffer is being returned to the application. Buffers are returned to the application when they have been played, or as the result of a call to the waveOutReset function.

MM_WOM_DONE

wParam = (WPARAM) hOutputDev

lParam = (LONG) lpwvhdr

Parameters

hOutputDev

Handle of the waveform-audio output device that played the buffer.

lpwvhdr

Address of a WAVEHDR structure identifying the buffer.

Return Values

This message does not return a value.

See Also

waveOutReset, WAVEHDR


MM_WOM_OPEN

The MM_WOM_OPEN message is sent to a window when the given waveform-audio output device is opened.

MM_WOM_OPEN

wParam = (WPARAM) hOutputDev

lParam = reserved

Parameters

hOutputDev

Handle of the device that was opened.

lParam

Reserved; must be zero.

Return Values

This message does not return a value.


MOM_CLOSE

The MOM_CLOSE message is sent to a MIDI output callback function when a MIDI output device is closed.

MOM_CLOSE

dwParam1 = reserved

dwParam2 = reserved

Parameters

dwParam1

Reserved; do not use.

dwParam2

Reserved; do not use.

Return Values

This message does not return a value.

Remarks

The device handle is no longer valid after this message has been sent.


MOM_DONE

The MOM_DONE message is sent to a MIDI output callback function when the specified system-exclusive or stream buffer has been played and is being returned to the application.

MOM_DONE

dwParam1 = (DWORD) lpMidiHdr

dwParam2 = reserved

Parameters

lpMidiHdr

Address of a MIDIHDR structure identifying the buffer.

dwParam2

Reserved; do not use.

Return Values

This message does not return a value.

See Also

MIDIHDR


MOM_OPEN

The MOM_OPEN message is sent to a MIDI output callback function when a MIDI output device is opened.

MOM_OPEN

dwParam1 = reserved

dwParam2 = reserved

Parameters

dwParam1

Reserved; do not use.

dwParam2

Reserved; do not use.

Return Values

This message does not return a value.


MOM_POSITIONCB

The MOM_POSITION message is sent to a window when a MEVT_F_CALLBACK event is reached in the MIDI output stream.

MOM_POSITIONCB

dwParam1 = (DWORD) hOutput

dwParam2 = (DWORD) lpMidiHdr

Parameters

hOutput

Handle of the MIDI output device.

lpMidiHdr

Address of a MIDIHDR structure that identifies the event that caused the callback function. The dwOffset member gives the offset of the event.

Return Values

This message does not return a value.

Remarks

Playback of the stream buffer continues even while the callback function is executing. Any events after the MEVT_F_CALLBACK event in the buffer will be scheduled and sent on time regardless of how much time is spent in the callback function.

If position callbacks are being generated more quickly than your application can process them, the dwOffset member of the MIDIHDR structure might refer to an event your application has not yet processed.

See Also

MIDIHDR


WIM_CLOSE

The WIM_CLOSE message is sent to the given waveform-audio input callback function when a waveform-audio input device is closed. The device handle is no longer valid after this message has been sent.

WIM_CLOSE

dwParam1 = reserved

dwParam2 = reserved

Parameters

dwParam1

Reserved; must be zero.

dwParam2

Reserved; must be zero.

Return Values

This message does not return a value.


WIM_DATA

The WIM_DATA message is sent to the given waveform-audio input callback function when waveform-audio data is present in the input buffer and the buffer is being returned to the application. The message can be sent when the buffer is full or after the waveInReset function is called.

WIM_DATA

dwParam1 = (DWORD) lpwvhdr

dwParam2 = reserved

Parameters

dwParam1

Address of a WAVEHDR structure that identifies the buffer containing the data.

dwParam2

Reserved; must be zero.

Return Values

This message does not return a value.

Remarks

The returned buffer might not be full. Use the dwBytesRecorded member of the WAVEHDR structure specified by lpwvhdr to determine the number of bytes recorded into the returned buffer.

See Also

WAVEHDR, waveInReset


WIM_OPEN

The WIM_OPEN message is sent to a waveform-audio input callback function when a waveform-audio input device is opened.

WIM_OPEN

dwParam1 = reserved

dwParam2 = reserved

Parameters

dwParam1

Reserved; must be zero.

dwParam2

Reserved; must be zero.

Return Values

This message does not return a value.


WM_CAP_ABORT

The WM_CAP_ABORT message stops the capture operation. In the case of step capture, the image data collected up to the point of the WM_CAP_ABORT message will be retained in the capture file, but audio will not be captured. You can send this message explicitly or by using the capCaptureAbort macro.

WM_CAP_ABORT

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The capture operation must yield to use this message.

Use the WM_CAP_STOP message to halt step capture at the current position, and then capture audio.

See Also

capCaptureAbort, WM_CAP_STOP


WM_CAP_DLG_VIDEOCOMPRESSION

The WM_CAP_DLG_VIDEOCOMPRESSION message displays a dialog box in which the user can select a compressor to use during the capture process. The list of available compressors can vary with the video format selected in the capture driver's Video Format dialog box. You can send this message explicitly or by using the capDlgVideoCompression macro.

WM_CAP_DLG_VIDEOCOMPRESSION

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

Use this message with capture drivers that provide frames only in the BI_RGB format. This message is most useful in the step capture operation to combine capture and compression in a single operation. Compressing frames with a software compressor as part of a real-time capture operation is most likely too time-consuming to perform.

Compression does not affect the frames copied to the clipboard.

See Also

capDlgVideoCompression


WM_CAP_DLG_VIDEODISPLAY

The WM_CAP_DLG_VIDEODISPLAY message displays a dialog box in which the user can set or adjust the video output. This dialog box might contain controls that affect the hue, contrast, and brightness of the displayed image, as well as key color alignment. You can send this message explicitly or by using the capDlgVideoDisplay macro.

WM_CAP_DLG_VIDEODISPLAY

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The controls in this dialog box do not affect digitized video data; they affect only the output or redisplay of the video signal.

The Video Display dialog box is unique for each capture driver. Some capture drivers might not support a Video Display dialog box. Applications can determine if the capture driver supports this message by checking the fHasDlgVideoDisplay member of the CAPDRIVERCAPS structure.

See Also

capDlgVideoDisplay, CAPDRIVERCAPS


WM_CAP_DLG_VIDEOFORMAT

The WM_CAP_DLG_VIDEOFORMAT message displays a dialog box in which the user can select the video format. The Video Format dialog box might be used to select image dimensions, bit depth, and hardware compression options. You can send this message explicitly or by using the capDlgVideoFormat macro.

WM_CAP_DLG_VIDEOFORMAT

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

After this message returns, applications might need to update the CAPSTATUS structure because the user might have changed the image dimensions.

The Video Format dialog box is unique for each capture driver. Some capture drivers might not support a Video Format dialog box. Applications can determine if the capture driver supports this message by checking the fHasDlgVideoFormat member of CAPDRIVERCAPS.

See Also

capDlgVideoFormat, CAPDRIVERCAPS, CAPSTATUS


WM_CAP_DLG_VIDEOSOURCE

The WM_CAP_DLG_VIDEOSOURCE message displays a dialog box in which the user can control the video source. The Video Source dialog box might contain controls that select input sources; alter the hue, contrast, brightness of the image; and modify the video quality before digitizing the images into the frame buffer. You can send this message explicitly or by using the capDlgVideoSource macro.

WM_CAP_DLG_VIDEOSOURCE

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The Video Source dialog box is unique for each capture driver. Some capture drivers might not support a Video Source dialog box. Applications can determine if the capture driver supports this message by checking the fHasDlgVideoSource member of the CAPDRIVERCAPS structure.

See Also

capDlgVideoSource, CAPDRIVERCAPS


WM_CAP_DRIVER_CONNECT

The WM_CAP_DRIVER_CONNECT message connects a capture window to a capture driver. You can send this message explicitly or by using the capDriverConnect macro.

WM_CAP_DRIVER_CONNECT

wParam = (WPARAM) (iIndex);

lParam = 0L;

Parameters

iIndex

Index of the capture driver. The index can range from 0 through 9.

Return Values

Returns TRUE if successful or FALSE if the specified capture driver cannot be connected to the capture window.

Remarks

Connecting a capture driver to a capture window automatically disconnects any previously connected capture driver.

See Also

capDriverConnect


WM_CAP_DRIVER_DISCONNECT

The WM_CAP_DRIVER_DISCONNECT message disconnects a capture driver from a capture window. You can send this message explicitly or by using the capDriverDisconnect macro.

WM_CAP_DRIVER_DISCONNECT

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns TRUE if successful or FALSE if the capture window is not connected to a capture driver.

See Also

capDriverDisconnect


WM_CAP_DRIVER_GET_CAPS

The WM_CAP_DRIVER_GET_CAPS message returns the hardware capabilities of the capture driver currently connected to a  capture window. You can send this message explicitly or by using the capDriverGetCaps macro.

WM_CAP_DRIVER_GET_CAPS

wParam = (WPARAM) (wSize);

lParam = (LPARAM) (LPVOID) (LPCAPDRIVERCAPS) (psCaps);

Parameters

wSize

Size, in bytes, of the structure referenced by s.

psCaps

Address of the CAPDRIVERCAPS structure to contain the hardware capabilities.

Return Values

Returns TRUE if successful or FALSE if the capture window is not connected to a capture driver.

Remarks

The capabilities returned in CAPDRIVERCAPS are constant for a given capture driver. Applications need to retrieve this information once when the capture driver is first connected to a capture window.

See Also

CAPDRIVERCAPS, capDriverGetCaps


WM_CAP_DRIVER_GET_NAME

The WM_CAP_DRIVER_GET_NAME message returns the name of the capture driver connected to the capture window. You can send this message explicitly or by using the capDriverGetName macro.

WM_CAP_DRIVER_GET_NAME

wParam = (WPARAM) (wSize);

lParam = (LPARAM) (LPVOID) (LPSTR) (szName);

Parameters

wSize

Size, in bytes, of the buffer referenced by szName.

szName

Address of an application-defined buffer used to return the device name as a null-terminated string.

Return Values

Returns TRUE if successful or FALSE if the capture window is not connected to a capture driver.

Remarks

The name is a text string retrieved from the driver’s resource area. Applications should allocate approximately 80 bytes for this string. If the driver does not contain a name resource, the full path name of the driver listed in the registry or in the SYSTEM.INI file is returned.

See Also

capDriverGetName


WM_CAP_DRIVER_GET_VERSION

The WM_CAP_DRIVER_GET_VERSION message returns the version information of the capture driver connected to a capture window. You can send this message explicitly or by using the capDriverGetVersion macro.

WM_CAP_DRIVER_GET_VERSION

wParam = (WPARAM) (wSize);

lParam = (LPARAM) (LPVOID) (LPSTR) (szVer);

Parameters

wSize

Size, in bytes, of the application-defined buffer referenced by szVer.

szVer

Address of an application-defined buffer used to return the version information as a null-terminated string.

Return Values

Returns TRUE if successful or FALSE if the capture window is not connected to a capture driver.

Remarks

The version information is a text string retrieved from the driver’s resource area. Applications should allocate approximately 40 bytes for this string. If version information is not available, a NULL string is returned.

See Also

capDriverGetVersion


WM_CAP_EDIT_COPY

The WM_CAP_EDIT_COPY message copies the contents of the video frame buffer and associated palette to the clipboard. You can send this message explicitly or by using the capEditCopy macro.

WM_CAP_EDIT_COPY

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

capEditCopy


WM_CAP_FILE_ALLOCATE

The WM_CAP_FILE_ALLOCATE message creates (preallocates) a capture file of a specified size. You can send this message explicitly or by using the capFileAlloc macro.

WM_CAP_FILE_ALLOCATE

wParam = (WPARAM) 0;

lParam = (LPARAM) (DWORD) (dwSize);

Parameters

dwSize

Size, in bytes, to create the capture file.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the WM_CAP_SET_CALLBACK_ERROR message, the error callback function is called.

Remarks

You can improve streaming capture performance significantly by preallocating a capture file large enough to store an entire video clip and by defragmenting the capture file before capturing the clip.

See Also

capFileAlloc, WM_CAP_SET_CALLBACK_ERROR


WM_CAP_FILE_GET_CAPTURE_FILE

The WM_CAP_FILE_GET_CAPTURE_FILE message returns the name of the current capture file. You can send this message explicitly or by using the capFileGetCaptureFile macro.

WM_CAP_FILE_GET_CAPTURE_FILE

wParam = (WPARAM) (wSize);

lParam = (LPARAM) (LPVOID) (LPSTR) (szName);

Parameters

wSize

Size, in bytes, of the application-defined buffer referenced by szName.

szName

Address of an application-defined buffer used to return the name of the capture file as a null-terminated string.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The default capture filename is C:\CAPTURE.AVI.

See Also

capFileGetCaptureFile


WM_CAP_FILE_SAVEAS

The WM_CAP_FILE_SAVEAS message copies the contents of the capture file to another file. You can send this message explicitly or by using the capFileSaveAs macro.

WM_CAP_FILE_SAVEAS

wParam = (WPARAM) 0;

lParam = (LPARAM) (LPVOID) (LPSTR) (szName);

Parameters

szName

Address of the null-terminated string that contains the name of the destination file used to copy the file.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the WM_CAP_SET_CALLBACK_ERROR message, the error callback function is called.

Remarks

This message does not change the name or contents of the current capture file.

If the copy operation is unsuccessful due to a disk full error, the destination file is automatically deleted.

Typically, a capture file is preallocated for the largest capture segment anticipated and only a portion of it might be used to capture data. This message copies only the portion of the file containing the capture data.

See Also

capFileSaveAs, WM_CAP_SET_CALLBACK_ERROR


WM_CAP_FILE_SAVEDIB

The WM_CAP_FILE_SAVEDIB message copies the current frame to a DIB file. You can send this message explicitly or by using the capFileSaveDIB macro.

WM_CAP_FILE_SAVEDIB

wParam = (WPARAM) 0;

lParam = (LPARAM) (LPVOID) (LPSTR) (szName);

Parameters

szName

Address of the null-terminated string that contains the name of the destination DIB file.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the WM_CAP_SET_CALLBACK_ERROR message, the error callback function is called.

Remarks

If the capture driver supplies frames in a compressed format, this call attempts to decompress the frame before writing the file.

See Also

capFileSaveDIB, WM_CAP_SET_CALLBACK_ERROR


WM_CAP_FILE_SET_CAPTURE_FILE

The WM_CAP_FILE_SET_CAPTURE_FILE message names the file used for video capture. You can send this message explicitly or by using the capFileSetCaptureFile macro.

WM_CAP_FILE_SET_CAPTURE_FILE

wParam = (WPARAM) 0;

lParam = (LPARAM) (LPVOID) (LPSTR) (szName);

Parameters

szName

Address of the null-terminated string that contains the name of the capture file to use.

Return Values

Returns TRUE if successful or FALSE if the filename is invalid, or if streaming or single-frame capture is in progress.

Remarks

This message stores the filename in an internal structure. It does not create, allocate, or open the specified file. The default capture filename is C:\CAPTURE.AVI.

See Also

capFileSetCaptureFile


WM_CAP_FILE_SET_INFOCHUNK

The WM_CAP_FILE_SET_INFOCHUNK message sets and clears information chunks. Information chunks can be inserted in an AVI file during capture to embed text strings or custom data. You can send this message explicitly or by using the capFileSetInfoChunk macro.

WM_CAP_FILE_SET_INFOCHUNK

wParam = (WPARAM)0;

lParam = (LPARAM) (LPCAPINFOCHUNK) (lpInfoChunk);

Parameters

lpInfoChunk

Address of a CAPINFOCHUNK structure defining the information chunk to be created or deleted.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the WM_CAP_SET_CALLBACK_ERROR message, the error callback function is called.

Remarks

Multiple registered information chunks can be added to an AVI file. After an information chunk is set, it continues to be added to subsequent capture files until either the entry is cleared or all information chunk entries are cleared. To clear a single entry, specify the information chunk in the fccInfoID member and NULL in the lpData member of the CAPINFOCHUNK structure. To clear all entries, specify NULL in fccInfoID.

See Also

capFileSetInfoChunk, CAPINFOCHUNK, WM_CAP_SET_CALLBACK_ERROR


WM_CAP_GET_AUDIOFORMAT

The WM_CAP_GET_AUDIOFORMAT message obtains the audio format or the size of the audio format. You can send this message explicitly or by using the capGetAudioFormat and capGetAudioFormatSize macros.

WM_CAP_GET_AUDIOFORMAT

wParam = (WPARAM) (wSize);

lParam = (LPARAM) (LPVOID) (LPWAVEFORMATEX) (psAudioFormat);

Parameters

wSize

Size, in bytes, of the structure referenced by s.

psAudioFormat

Address of a WAVEFORMATEX structure, or NULL. If the value is NULL, the size, in bytes, required to hold the WAVEFORMATEX structure is returned.

Return Values

Returns the size, in bytes, of the audio format.

Remarks

Because compressed audio formats vary in size requirements applications must first retrieve the size, then allocate memory, and finally request the audio format data.

See Also

capGetAudioFormat, capGetAudioFormatSize, WAVEFORMATEX


WM_CAP_GET_MCI_DEVICE

The WM_CAP_GET_MCI_DEVICE message retrieves the name of an MCI device previously set with the WM_CAP_SET_MCI_DEVICE message. You can send this message explicitly or by using the capGetMCIDeviceName macro.

WM_CAP_GET_MCI_DEVICE

wParam = (WPARAM) (wSize);

lParam = (LPARAM) (LPVOID) (LPSTR) (szName);

Parameters

wSize

Length, in bytes, of the buffer referenced by szName .

szName

Address of a null-terminated string that contains the MCI device name.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

capGetMCIDeviceName, WM_CAP_SET_MCI_DEVICE


WM_CAP_GET_SEQUENCE_SETUP

The WM_CAP_GET_SEQUENCE_SETUP message retrieves the current settings of the streaming capture parameters. You can send this message explicitly or by using the capCaptureGetSetup macro.

WM_CAP_GET_SEQUENCE_SETUP

wParam = (WPARAM) (wSize);

lParam = (LPARAM) (LPVOID) (LPCAPTUREPARMS) (s);

Parameters

wSize

Size, in bytes, of the structure referenced by s.

s

Address of a CAPTUREPARMS structure.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

For information about the parameters used to control streaming capture, see the CAPTUREPARMS structure.

See Also

capCaptureGetSetup, CAPTUREPARMS


WM_CAP_GET_STATUS

The WM_CAP_GET_STATUS message retrieves the status of the capture window. You can send this message explicitly or by using the capGetStatus macro.

WM_CAP_GET_STATUS

wParam = (WPARAM) (wSize);

lParam = (LPARAM) (LPVOID) (LPCAPSTATUS) (s);

Parameters

wSize

Size, in bytes, of the structure referenced by s.

s

Address of a CAPSTATUS structure.

Return Values

Returns TRUE if successful or FALSE if the capture window is not connected to a capture driver.

Remarks

The CAPSTATUS structure contains the current state of the capture window. Since this state is dynamic and changes in response to various messages, the application should initialize this structure after sending the WM_CAP_DLG_VIDEOFORMAT message (or using the capDlgVideoFormat macro) and whenever it needs to enable menu items or determine the actual state of the window.

See Also

capGetStatus, CAPSTATUS, WM_CAP_DLG_VIDEOFORMAT


WM_CAP_GET_USER_DATA

The WM_CAP_GET_USER_DATA message retrieves a LONG data value associated with a capture window. You can send this message explicitly or by using the capGetUserData macro.

WM_CAP_GET_USER_DATA

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns a value previously saved by using the WM_CAP_SET_USER_DATAmessage.

See Also

capGetUserData, WM_CAP_SET_USER_DATA


WM_CAP_GET_VIDEOFORMAT

The WM_CAP_GET_VIDEOFORMAT message retrieves a copy of the video format in use or the size required for the video format. You can send this message explicitly or by using the capGetVideoFormat and capGetVideoFormatSize macros.

WM_CAP_GET_VIDEOFORMAT

wParam = (WPARAM) (wSize);

lParam = (LPARAM) (LPVOID) (psVideoFormat);

Parameters

wSize

Size, in bytes, of the structure referenced by s.

psVideoFormat

Address of a BITMAPINFO structure. You can also specify NULL to retrieve the number of bytes needed by BITMAPINFO.

Return Values

Returns the size, in bytes, of the video format or zero if the capture window is not connected to a capture driver. For video formats that require a palette, the current palette is also returned.

Remarks

Because compressed video formats vary in size requirements applications must first retrieve the size, then allocate memory, and finally request the video format data.

See Also

BITMAPINFO, capGetVideoFormat, capGetVideoFormatSize


WM_CAP_GRAB_FRAME

The WM_CAP_GRAB_FRAME message retrieves and displays a single frame from the capture driver. After capture, overlay and preview are disabled. You can send this message explicitly or by using the capGrabFrame macro.

WM_CAP_GRAB_FRAME

wParam = (WPARAM)0;

lParam = (LPARAM)0L;

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

For information about installing callback functions, see the WM_CAP_SET_CALLBACK_ERROR and WM_CAP_SET_CALLBACK_FRAME messages.

See Also

capGrabFrame, WM_CAP_SET_CALLBACK_ERROR, WM_CAP_SET_CALLBACK_FRAME


WM_CAP_GRAB_FRAME_NOSTOP

The WM_CAP_GRAB_FRAME_NOSTOP message fills the frame buffer with a single uncompressed frame from the capture device and displays it. Unlike with the WM_CAP_GRAB_FRAME message, the state of overlay or preview is not altered by this message. You can send this message explicitly or by using the capGrabFrameNoStop macro.

WM_CAP_GRAB_FRAME_NOSTOP

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

For information about installing callback functions, see the WM_CAP_SET_CALLBACK_ERROR and WM_CAP_SET_CALLBACK_FRAME messages.

See Also

capGrabFrameNoStop, WM_CAP_GRAB_FRAME, WM_CAP_SET_CALLBACK_ERROR, WM_CAP_SET_CALLBACK_FRAME


WM_CAP_PAL_AUTOCREATE

The WM_CAP_PAL_AUTOCREATE message requests that the capture driver sample video frames and automatically create a new palette. You can send this message explicitly or by using the capPaletteAuto macro.

WM_CAP_PAL_AUTOCREATE

wParam = (WPARAM) (iFrames);

lParam = (LPARAM) (DWORD) (iColors);

Parameters

iFrames

Number of frames to sample.

iColors

Number of colors in the palette. The maximum value for this parameter is 256.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the WM_CAP_SET_CALLBACK_ERROR message, the error callback function is called.

Remarks

The sampled video sequence should include all the colors you want in the palette. To obtain the best palette, you might have to sample the whole sequence rather than a portion of it.

See Also

capPaletteAuto, WM_CAP_SET_CALLBACK_ERROR


WM_CAP_PAL_MANUALCREATE

The WM_CAP_PAL_MANUALCREATE message requests that the capture driver manually sample video frames and create a new palette. You can send this message explicitly or by using the capPaletteManual macro.

WM_CAP_PAL_MANUALCREATE

wParam = (WPARAM) (fGrab);

lParam = (LPARAM) (DWORD) (iColors);

Parameters

fGrab

Palette histogram flag. Set this parameter to TRUE for each frame included in creating the optimal palette. After the last frame has been collected, set this parameter to FALSE to calculate the optimal palette and send it to the capture driver.

iColors

Number of colors in the palette. The maximum value for this parameter is 256. This value is used only during collection of the first frame in a sequence.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the WM_CAP_SET_CALLBACK_ERROR message, the error callback function is called.

See Also

capPaletteManual, WM_CAP_SET_CALLBACK_ERROR


WM_CAP_PAL_OPEN

The WM_CAP_PAL_OPEN message loads a new palette from a palette file and passes it to a capture driver. Palette files typically use the filename extension .PAL. A capture driver uses a palette when required by the specified digitized image format. You can send this message explicitly or by using the capPaletteOpen macro.

WM_CAP_PAL_OPEN

wParam = (WPARAM) 0;

lParam = (LPARAM) (LPVOID) (LPSTR) (szName);

Parameters

szName

Address of a null-terminated string containing the palette filename.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the WM_CAP_SET_CALLBACK_ERROR message, the error callback function is called.

See Also

capPaletteOpen, WM_CAP_SET_CALLBACK_ERROR


WM_CAP_PAL_PASTE

The WM_CAP_ message copies the palette from the clipboard and passes it to a capture driver. You can send this message explicitly or by using the capPalettePaste macro.

WM_CAP_PAL_PASTE

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the WM_CAP_SET_CALLBACK_ERROR message, the error callback function is called.

Remarks

A capture driver uses a palette when required by the specified digitized video format.

See Also

capPalettePaste, WM_CAP_SET_CALLBACK_ERROR


WM_CAP_PAL_SAVE

The WM_CAP_PAL_SAVE message saves the current palette to a palette file. Palette files typically use the filename extension .PAL. You can send this message explicitly or by using the capPaletteSave macro.

WM_CAP_PAL_SAVE

wParam = (WPARAM) 0;

lParam = (LPARAM) (LPVOID) (LPSTR) (szName);

Parameters

szName

Address of a null-terminated string containing the palette filename.

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the WM_CAP_SET_CALLBACK_ERROR message, the error callback function is called.

See Also

capPaletteSave, WM_CAP_SET_CALLBACK_ERROR


WM_CAP_SEQUENCE

The WM_CAP_SEQUENCE message initiates streaming video and audio capture to a file. You can send this message explicitly or by using the capCaptureSequence macro.

WM_CAP_SEQUENCE

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns TRUE if successful or FALSE otherwise.

If an error occurs and an error callback function is set using the WM_CAP_SET_CALLBACK_ERROR message, the error callback function is called.

Remarks

If you want to alter the parameters controlling streaming capture, use the WM_CAP_SET_SEQUENCE_SETUP message prior to starting the capture.

By default, the capture window does not allow other applications to continue running during capture. To override this, either set the fYield member of the CAPTUREPARMS structure to TRUE, or install a yield callback function.

During streaming capture, the capture window can optionally issue notifications to your application of specific types of conditions. To install callback procedures for these notifications, use the following messages:

WM_CAP_SET_CALLBACK_ERROR
WM_CAP_SET_CALLBACK_STATUS
WM_CAP_SET_CALLBACK_YIELD
WM_CAP_SET_CALLBACK_VIDEOSTREAM
WM_CAP_SET_CALLBACK_WAVESTREAM

See Also

capCaptureSequence, CAPTUREPARMS, WM_CAP_SET_CALLBACK_ERROR, WM_CAP_SET_CALLBACK_STATUS, WM_CAP_SET_CALLBACK_YIELD, WM_CAP_SET_CALLBACK_VIDEOSTREAM, WM_CAP_SET_CALLBACK_WAVESTREAM, WM_CAP_SET_SEQUENCE_SETUP


WM_CAP_SEQUENCE_NOFILE

The WM_CAP_SEQUENCE_NOFILE message initiates streaming video capture without writing data to a file. You can send this message explicitly or by using the capCaptureSequenceNoFile macro.

WM_CAP_SEQUENCE_NOFILE

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

This message is useful in conjunction with video stream or waveform-audio stream callback functions that let your application use the video and audio data directly.

If you want to alter the parameters controlling streaming capture, use the WM_CAP_SET_SEQUENCE_SETUP message prior to starting the capture.

By default, the capture window does not allow other applications to continue running during capture. To override this, either set the fYield member of the CAPTUREPARMS structure to TRUE, or install a yield callback function.

During streaming capture, the capture window can optionally issue notifications to your application of specific types of conditions. To install callback procedures for these notifications, use the following messages:

WM_CAP_SET_CALLBACK_ERROR
WM_CAP_SET_CALLBACK_STATUS
WM_CAP_SET_CALLBACK_YIELD
WM_CAP_SET_CALLBACK_VIDEOSTREAM
WM_CAP_SET_CALLBACK_WAVESTREAM

See Also

capCaptureSequenceNoFile, CAPTUREPARMS, WM_CAP_SET_CALLBACK_ERROR, WM_CAP_SET_CALLBACK_STATUS, WM_CAP_SET_CALLBACK_YIELD, WM_CAP_SET_CALLBACK_VIDEOSTREAM, WM_CAP_SET_CALLBACK_WAVESTREAM, WM_CAP_SET_SEQUENCE_SETUP


WM_CAP_SET_AUDIOFORMAT

The WM_CAP_SET_AUDIOFORMAT message sets the audio format to use when performing streaming or step capture. You can send this message explicitly or by using the capSetAudioFormat macro.

WM_CAP_SET_AUDIOFORMAT

wParam = (WPARAM) (wSize);

lParam = (LPARAM) (LPVOID) (LPWAVEFORMATEX) (psAudioFormat);

Parameters

wSize

Size, in bytes, of the structure referenced by s.

psAudioFormat

Address of a WAVEFORMATEX or PCMWAVEFORMAT structure that defines the audio format.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

capSetAudioFormat, PCMWAVEFORMAT, WAVEFORMATEX


WM_CAP_SET_CALLBACK_CAPCONTROL

The WM_CAP_SET_CALLBACK_CAPCONTROL message sets a callback function in the application giving it precise recording control. You can send this message explicitly or by using the capSetCallbackOnCapControl macro.

WM_CAP_SET_CALLBACK_CAPCONTROL

wParam = (WPARAM) 0;

lParam = (LPARAM) (LPVOID) (fpProc);

Parameters

fpProc

Address of the callback function. Specify NULL for this parameter to disable a previously installed callback function.

Return Values

Returns TRUE if successful or FALSE if a streaming capture or a single-frame capture session is in progress.

Remarks

A single callback function is used to give the application precise control over the moments that streaming capture begins and completes. The capture window first calls the procedure with nState set to CONTROLCALLBACK_PREROLL after all buffers have been allocated and all other capture preparations have finished. This gives the application the ability to preroll video sources, returning from the callback function at the exact moment recording is to begin. A return value of TRUE from the callback function continues capture, and a return value of FALSE aborts capture. After capture begins, this callback function will be called frequently with nState set to CONTROLCALLBACK_CAPTURING to allow the application to end capture by returning FALSE.

See Also

capSetCallbackOnCapControl


WM_CAP_SET_CALLBACK_ERROR

The WM_CAP_SET_CALLBACK_ERROR message sets an error callback function in the client application. AVICap calls this procedure when errors occur. You can send this message explicitly or by using the capSetCallbackOnError macro.

WM_CAP_SET_CALLBACK_ERROR

wParam = (WPARAM) 0;

lParam = (LPARAM) (LPVOID) (fpProc);

Parameters

fpProc

Address of the error callback function. Specify NULL for this parameter to disable a previously installed error callback function.

Return Values

Returns TRUE if successful or FALSE if streaming capture or a single-frame capture session is in progress.

Remarks

Applications can optionally set an error callback function. If set, AVICap calls the error procedure in the following situations:

•	The disk is full.

•	A capture window cannot be connected with a capture driver.

•	A waveform-audio device cannot be opened.

•	The number of frames dropped during capture exceeds the specified percentage.

•	The frames cannot be captured due to vertical synchronization interrupt problems.

See Also

capSetCallbackOnError


WM_CAP_SET_CALLBACK_FRAME

The WM_CAP_SET_CALLBACK_FRAME message sets a preview callback function in the application. AVICap calls this procedure when the capture window captures preview frames. You can send this message explicitly or by using the capSetCallbackOnFrame macro.

WM_CAP_SET_CALLBACK_FRAME

wParam = (WPARAM) 0;

lParam = (LPARAM) (LPVOID) (fpProc);

Parameters

fpProc

Address of the preview callback function. Specify NULL for this parameter to disable a previously installed callback function.

Return Values

Returns TRUE if successful or FALSE if streaming capture or a single-frame capture session is in progress.

Remarks

The capture window calls the callback function before displaying preview frames. This allows an application to modify the frame if desired. This callback function is not used during streaming video capture.

See Also

capSetCallbackOnFrame


WM_CAP_SET_CALLBACK_STATUS

The WM_CAP_SET_CALLBACK_STATUS message sets a status callback function in the application. AVICap calls this procedure whenever the capture window status changes. You can send this message explicitly or by using the capSetCallbackOnStatus macro.

WM_CAP_SET_CALLBACK_STATUS

wParam = (WPARAM) 0;

lParam = (LPARAM) (LPVOID) (fpProc);

Parameters

fpProc

Address of the status callback function. Specify NULL for this parameter to disable a previously installed status callback function.

Return Values

Returns TRUE if successful or FALSE if streaming capture or a single-frame capture sesion is in progress.

Remarks

Applications can optionally set a status callback function. If set, AVICap calls this procedure in the following situations:

•	A capture session is completed.

•	A capture driver successfully connected to a capture window.

•	An optimal palette is created.

•	The number of captured frames is reported.

See Also

capSetCallbackOnStatus


WM_CAP_SET_CALLBACK_VIDEOSTREAM

The WM_CAP_SET_CALLBACK_VIDEOSTREAM message sets a callback function in the application. AVICap calls this procedure during streaming capture when a video buffer is filled. You can send this message explicitly or by using the capSetCallbackOnVideoStream macro.

WM_CAP_SET_CALLBACK_VIDEOSTREAM

wParam = (WPARAM) 0;

lParam = (LPARAM) (LPVOID) (fpProc);

Parameters

fpProc

Address of the video-stream callback function. Specify NULL for this parameter to disable a previously installed video-stream callback function.

Return Values

Returns TRUE if successful or FALSE if streaming capture or a single-frame capture session is in progress.

Remarks

The capture window calls the callback function before writing the captured frame to disk. This allows applications to modify the frame if desired.

If a video stream callback function is used for streaming capture, the procedure must be installed before starting the capture session and it must remain enabled for the duration of the session. It can be disabled after streaming capture ends.

See Also

capSetCallbackOnVideoStream


WM_CAP_SET_CALLBACK_WAVESTREAM

The WM_CAP_SET_CALLBACK_WAVESTREAM message sets a callback function in the application. AVICap calls this procedure during streaming capture when a new audio buffer becomes available. You can send this message explicitly or by using the capSetCallbackOnWaveStream macro.

WM_CAP_SET_CALLBACK_WAVESTREAM

wParam = (WPARAM) 0;

lParam = (LPARAM) (LPVOID) (fpProc);

Parameters

fpProc

Address of the wave stream callback function. Specify NULL for this parameter to disable a previously installed wave stream callback function.

Return Values

Returns TRUE if successful or FALSE if streaming capture or a single-frame capture session is in progress.

Remarks

The capture window calls the procedure before writing the audio buffer to disk. This allows applications to modify the audio buffer if desired.

If a wave stream callback function is used, it must be installed before starting the capture session and it must remain enabled for the duration of the session. It can be disabled after streaming capture ends.

See Also

capSetCallbackOnWaveStream


WM_CAP_SET_CALLBACK_YIELD

The WM_CAP_SET_CALLBACK_YIELD message sets a callback function in the application. AVICap calls this procedure when the capture window yields during streaming capture. You can send this message explicitly or by using the capSetCallbackOnYield macro.

WM_CAP_SET_CALLBACK_YIELD

wParam = (WPARAM) 0;

lParam = (LPARAM) (LPVOID) (fpProc);

Parameters

fpProc

Address of the yield callback function. Specify NULL for this parameter to disable a previously installed yield callback function.

Return Values

Returns TRUE if successful or FALSE if streaming capture or a single-frame capture session is in progress.

Remarks

Applications can optionally set a yield callback function. The yield callback function is called at least once for each video frame captured during streaming capture. If a yield callback function is installed, it will be called regardless of the state of the fYield member of the CAPTUREPARMS structure.

If the yield callback function is used, it must be installed before starting the capture session and it must remain enabled for the duration of the session. It can be disabled after streaming capture ends.

Applications typically perform some type of message processing in the callback function consisting of a PeekMessage, TranslateMessage, DispatchMessage loop, as in the message loop of a WinMain function. The yield callback function must also filter and remove messages that can cause reentrancy problems.

An application typically returns TRUE in the yield procedure to continue streaming capture. If a yield callback function returns FALSE, the capture window stops the capture process.

See Also

capSetCallbackOnYield, CAPTUREPARMS, DispatchMessage PeekMessage, TranslateMessage


WM_CAP_SET_MCI_DEVICE

The WM_CAP_SET_MCI_DEVICE message specifies the name of the MCI video device to be used to capture data. You can send this message explicitly or by using the capSetMCIDeviceName macro.

WM_CAP_SET_MCI_DEVICE

wParam = (WPARAM) 0;

lParam = (LPARAM) (LPVOID) (LPSTR) (szName);

Parameters

szName

Address of a null-terminated string containing the name of the device.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

This message stores the MCI device name in an internal structure. It does not open or access the device. The default device name is NULL.

See Also

capSetMCIDeviceName


WM_CAP_SET_OVERLAY

The WM_CAP_SET_OVERLAY message enables or disables overlay mode. In overlay mode, video is displayed using hardware overlay. You can send this message explicitly or by using the capOverlay macro.

WM_CAP_SET_OVERLAY

wParam = (WPARAM) (BOOL) (f);

lParam = 0L;

Parameters

f

Overlay flag. Specify TRUE for this parameter to enable overlay mode or FALSE to disable it.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

Using an overlay does not require CPU resources.

The fHasOverlay member of the CAPDRIVERCAPS structure indicates whether the device is capable of overlay. The fOverlayWindow member of the CAPSTATUS structure indicates whether overlay mode is currently enabled.

Enabling overlay mode automatically disables preview mode.

See Also

CAPDRIVERCAPS, capOverlay, CAPSTATUS


WM_CAP_SET_PREVIEW

The WM_CAP_SET_PREVIEW message enables or disables preview mode. In preview mode, frames are transferred from the capture hardware to system memory and then displayed in the capture window using GDI functions. You can send this message explicitly or by using the capPreview macro.

WM_CAP_SET_PREVIEW

wParam = (WPARAM) (BOOL) (f);

lParam = 0L;

Parameters

f

Preview flag. Specify TRUE for this parameter to enable preview mode or FALSE to disable it.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The preview mode uses substantial CPU resources. Applications can disable preview or lower the preview rate when another application has the focus. The fLiveWindow member of the CAPSTATUS structure indicates if preview mode is currently enabled.

Enabling preview mode automatically disables overlay mode.

See Also

capPreview, CAPSTATUS


WM_CAP_SET_PREVIEWRATE

The WM_CAP_SET_PREVIEWRATE message sets the frame display rate in preview mode. You can send this message explicitly or by using the capPreviewRate macro.

WM_CAP_SET_PREVIEWRATE

wParam = (WPARAM) (wMS);

lParam = 0L;

Parameters

wMS

Rate, in milliseconds, at which new frames are captured and displayed.

Return Values

Returns TRUE if successful or FALSE if the capture window is not connected to a capture driver.

Remarks

The preview mode uses substantial CPU resources. Applications can disable preview or lower the preview rate when another application has the focus. During streaming video capture, the previewing task is lower priority than writing frames to disk, and preview frames are displayed only if no other buffers are available for writing.

See Also

capPreviewRate


WM_CAP_SET_SCALE

The WM_CAP_SET_SCALE message enables or disables scaling of the preview video images. If scaling is enabled, the captured video frame is stretched to the dimensions of the capture window. You can send this message explicitly or by using the capPreviewScale macro.

WM_CAP_SET_SCALE

wParam = (WPARAM) (BOOL)f;

lParam = 0L;

Parameters

f

Preview scaling flag. Specify TRUE for this parameter to stretch preview frames to the size of the capture window or FALSE to display them at their natural size.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

Scaling preview images controls the immediate presentation of captured frames within the capture window. It has no effect on the size of the frames saved to file.

Scaling has no effect when using overlay to display video in the frame buffer.

See Also

capPreviewScale


WM_CAP_SET_SCROLL

The WM_CAP_SET_SCROLL message defines the portion of the video frame to display in the capture window. This message sets the upper left corner of the client area of the capture window to the coordinates of a specified pixel within the video frame. You can send this message explicitly or by using the capSetScrollPos macro.

WM_CAP_SET_SCROLL

wParam = (WPARAM) 0;

lParam = (LPARAM) (LPPOINT) (lpP);

Parameters

lpP

Address to contain the desired scroll position.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The scroll position affects the image in both preview and overlay modes.

See Also

capSetScrollPos


WM_CAP_SET_SEQUENCE_SETUP

The WM_CAP_SET_SEQUENCE_SETUP message sets the configuration parameters used with streaming capture. You can send this message explicitly or by using the capCaptureSetSetup macro.

WM_CAP_SET_SEQUENCE_SETUP

wParam = (WPARAM) (wSize);

lParam = (LPARAM) (LPVOID) (LPCAPTUREPARMS) (psCapParms);

Parameters

wSize

Size, in bytes, of the structure referenced by s.

psCapParms

Address of a CAPTUREPARMS structure.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

For information about the parameters used to control streaming capture, see the CAPTUREPARMS structure.

See Also

capCaptureSetSetup, CAPTUREPARMS


WM_CAP_SET_USER_DATA

The WM_CAP_SET_USER_DATA message associates a LONG data value with a capture window. You can send this message explicitly or by using the capSetUserData macro.

WM_CAP_SET_USER_DATA

wParam = (WPARAM) 0;

lParam = (LPARAM)lUser;

Parameters

lUser

Data value to associate with a capture window.

Return Values

Returns TRUE if successful or FALSE if streaming capture is in progress.

Remarks

Typically this message is used to point to a block of data associated with a capture window.

See Also

capSetUserData


WM_CAP_SET_VIDEOFORMAT

The WM_CAP_SET_VIDEOFORMAT message sets the format of captured video data. You can send this message explicitly or by using the capSetVideoFormat macro.

WM_CAP_SET_VIDEOFORMAT

wParam = (WPARAM) (wSize);

lParam = (LPARAM) (LPVOID) (psVideoFormat);

Parameters

wSize

Size, in bytes, of the structure referenced by s.

psVideoFormat

Address of a BITMAPINFO structure.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

Because video formats are device-specific, applications should check the return value from this function to determine if the format is accepted by the driver.

See Also

BITMAPINFO, capSetVideoFormat


WM_CAP_SINGLE_FRAME

The WM_CAP_SINGLE_FRAME message appends a single frame to a capture file that was opened using the WM_CAP_SINGLE_FRAME_OPEN message. You can send this message explicitly or by using the capCaptureSingleFrame macro.

WM_CAP_SINGLE_FRAME

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

capCaptureSingleFrame, WM_CAP_SINGLE_FRAME_OPEN


WM_CAP_SINGLE_FRAME_CLOSE

The WM_CAP_SINGLE_FRAME_CLOSE message closes the capture file opened by the WM_CAP_SINGLE_FRAME_OPEN message. You can send this message explicitly or by using the capCaptureSingleFrameClose macro.

WM_CAP_SINGLE_FRAME_CLOSE

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

For information about installing callback functions, see the WM_CAP_SET_CALLBACK_ERROR and WM_CAP_SET_CALLBACK_FRAME messages.

See Also

capCaptureSingleFrameClose, WM_CAP_SET_CALLBACK_ERROR, WM_CAP_SET_CALLBACK_FRAME, WM_CAP_SINGLE_FRAME_OPEN


WM_CAP_SINGLE_FRAME_OPEN

The WM_CAP_SINGLE_FRAME_OPEN message opens the capture file for single-frame capturing. Any previous information in the capture file is overwritten. You can send this message explicitly or by using the capCaptureSingleFrameOpen macro.

WM_CAP_SINGLE_FRAME_OPEN

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

For information about installing callback functions, see the WM_CAP_SET_CALLBACK_ERROR and WM_CAP_SET_CALLBACK_FRAME messages.

See Also

capCaptureSingleFrameOpen, WM_CAP_SET_CALLBACK_ERROR, WM_CAP_SET_CALLBACK_FRAME


WM_CAP_STOP

The WM_CAP_STOP message stops the capture operation. You can send this message explicitly or by using the capCaptureStop macro.

In step frame capture, the image data that was collected before this message was sent is retained in the capture file. An equivalent duration of audio data is also retained in the capture file if audio capture was enabled.

WM_CAP_STOP

wParam = (WPARAM) 0;

lParam = 0L;

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The capture operation must yield to use this message. Use the WM_CAP_ABORT message to abandon the current capture operation.

See Also

capCaptureStop, WM_CAP_ABORT


WOM_CLOSE

The WOM_CLOSE message is sent to a waveform-audio output callback function when a waveform-audio output device is closed. The device handle is no longer valid after this message has been sent.

WOM_CLOSE

dwParam1 = reserved

dwParam2 = reserved

Parameters

dwParam1

Reserved; must be zero.

dwParam2

Reserved; must be zero.

Return Values

This message does not return a value.


WOM_DONE

The WOM_DONE message is sent to a waveform-audio output callback function when the given output buffer is being returned to the application. Buffers are returned to the application when they have been played, or as the result of a call to the waveOutReset function.

WOM_DONE

dwParam1 = (DWORD) lpwvhdr

dwParam2 = reserved

Parameters

dwParam1

Address of a WAVEHDR structure identifying the buffer.

dwParam2

Reserved; must be zero.

Return Values

This message does not return a value.

See Also

WAVEHDR, waveOutReset


WOM_OPEN

The WOM_OPEN message is sent to a waveform-audio output callback function when a waveform-audio output device is opened.

WOM_OPEN

dwParam1 = reserved

dwParam2 = reserved

Parameters

dwParam1

Reserved; must be zero.

dwParam2

Reserved; must be zero.

Return Values

This message does not return a value.


Joysticks

This overview describes the functions and messages that support joysticks, as well as other ancillary input devices that track positions within an absolute coordinate system, such as a touch screen, digitizing tablet, and light pen. Extended capabilities also provide support for rudder pedals, flight yokes, and other devices that use up to six axes of movement, a point-of-view hat, and 32 buttons.


About Joysticks

The joystick is an ancillary input device for applications that provide alternatives to using the keyboard and mouse. The joystick provides positional information within a coordinate system that has absolute maximum and minimum values in each axis of movement.

Joystick services are loaded when the operating system is started. The joystick services can simultaneously monitor two joysticks, each with two- or three-axis movement. Each joystick can have up to four buttons. You can use the joystick functions to determine the capabilities of the joysticks and joystick driver. Also, you can process a joystick’s positional and button information by querying the joystick directly or by capturing the joystick and processing messages from it. The latter method is simpler because your application does not have to manually query the joystick or track the time to generate queries at regular intervals.


Joystick Capabilities

Joysticks can support two- or three-axis movement and up to four buttons. Joysticks also support different ranges of motion and polling frequencies. The range of motion is the distance a joystick handle can move from its resting position to the position farthest from its resting position. The polling frequency is the time interval between joystick queries.

Joystick drivers can support either one or two joysticks. You can determine the number of joysticks supported by a joystick driver by using the joyGetNumDevs function. This function returns an unsigned integer that contains the number of supported joysticks or zero if there is no joystick support. The return value does not indicate the number of joysticks attached to the system.

You can determine if a joystick is attached to the system by using the joyGetPos function. This function returns JOYERR_NOERROR if the specified device is attached. Otherwise , it returns JOYERR_UNPLUGGED.

Each joystick has several capabilities that are available to your application. You can retrieve the capabilities of a joystick by using the joyGetDevCaps function. This function fills a JOYCAPS structure with joystick capabilities such as the minimum and maximum values for its coordinate system, the number of buttons on the joystick, and the minimum and maximum polling frequencies.


Joystick Position

You can query a joystick for position and button information by using the joyGetPos function. For example, an application can query the joystick for baseline position values. The Joystick Control Panel property sheet uses this technique when calibrating the joystick.

You can also query a joystick or other device that has extended capabilities by using the joyGetPosEx function.


Joystick Notifications

You can capture direct joystick messages to be sent to a function by using the joySetCapture function. Only one application at a time can capture messages from a joystick, but you can query the joystick from another application by using the joyGetPos or joyGetPosEx function.

Note  A joystick message can fail to reach the application that captured the joystick if a second application uses joyGetPos or joyGetPosEx to query the joystick at approximately the same time that the message is sent. In this case, the second application could intercept the message.

If you want to capture messages from two joysticks attached to the system, use joySetCapture twice, once for each joystick. Your window receives separate and distinct messages for each device.

You can release a captured joystick by using the joyReleaseCapture function. If an application does not release the joystick before ending, the joystick is automatically released shortly after the capture window is destroyed.

You cannot capture an unplugged joystick. The joySetCapture function returns JOYERR_UNPLUGGED if the specified device is unplugged.


Time-Based Notifications

You can notify the operating system to send joystick messages to an application at regular time intervals by setting the fChanged parameter of joySetCapture to FALSE and by specifying the interval length between successive messages. To do this, assign the uPeriod parameter a value between the minimum and maximum polling frequencies for the joystick. You can determine this range by using the joyGetDevCaps function, which fills the wPeriodMin and wPeriodMax members in the JOYCAPS structure. If the uPeriod value is outside the range of valid polling frequencies for the joystick, the joystick driver uses the minimum or maximum polling frequency, whichever is closer to the uPeriod value.

Note  Windows sets up a timer event with each call to joySetCapture.


Event-Based Notifications

You can notify Windows to send joystick messages to an application whenever the position of a joystick axis changes by a value greater than the movement threshold of the device. The movement threshold is the distance the joystick must be moved before a WM_JOYMOVE message is sent to a window that has captured the device. The threshold is initially zero. You can set the movement threshold by using the joySetThreshold function. You can retrieve the minimum polling frequency of the joystick by using the joyGetDevCaps function.


Joystick Notification Messages

Joystick messages notify your application that a joystick has changed position or that one of its buttons has changed states. Messages beginning with MM_JOY1 are sent to the function if your application requests input from the joystick using the identifier JOYSTICKID1, and MM_JOY2 messages are sent if your application requests input from the joystick using the identifier JOYSTICKID2.

The messages in the following table identify the status of the joystick buttons:

Message	Description
MM_JOY1BUTTONDOWN	A button on joystick JOYSTICKID1 has been pressed.
MM_JOY1BUTTONUP	A button on joystick JOYSTICKID1 has been released.
MM_JOY1MOVE	Joystick JOYSTICKID1 changed position in the x- or y-direction.
MM_JOY1ZMOVE	Joystick JOYSTICKID1 changed position in the z-direction.
MM_JOY2BUTTONDOWN	A button on joystick JOYSTICKID2 has been pressed.
MM_JOY2BUTTONUP	A button on joystick JOYSTICKID2 has been released.
MM_JOY2MOVE	Joystick JOYSTICKID2 changed position in the x- or y-direction
MM_JOY2ZMOVE	Joystick JOYSTICKID2 changed position in the z-direction.
All messages report nonexistent buttons as released.


Using Joysticks

This section contains examples demonstrating how to perform the following tasks:

•	Getting the driver capabilities

•	Capturing joystick input

•	Processing joystick messages

The examples are taken from a simple joystick application that retrieves position and button-state information from the joystick services, plays waveform-audio resources, and paints bullet holes on the screen when a user presses the joystick buttons.


Getting the Driver Capabilities

The following example uses joyGetNumDevs and joyGetPos to determine whether the joystick services are available and if a joystick is attached to one of the ports.

JOYINFO joyinfo;

UINT wNumDevs, wDeviceID;

BOOL bDev1Attached, bDev2Attached;

    if((wNumDevs = joyGetNumDevs()) == 0)

        return ERR_NODRIVER;

    bDev1Attached = joyGetPos(JOYSTICKID1,&joyinfo) != JOYERR_UNPLUGGED;

    bDev2Attached = wNumDevs == 2 && joyGetPos(JOYSTICKID2,&joyinfo) !=

        JOYERR_UNPLUGGED;

    if(bDev1Attached || bDev2Attached)   // decide which joystick to use

        wDeviceID = bDev1Attached ? JOYSTICKID1 : JOYSTICKID2;

    else

        return ERR_NODEVICE;


Capturing Joystick Input

Most of the code controlling the joystick is in the main window function. In the following portion of the message handler, the application calls joySetCapture to capture input from the joystick JOYSTICKID1.

case WM_CREATE:

    if(joySetCapture(hWnd, JOYSTICKID1, NULL, FALSE))

    {

        MessageBeep(MB_ICONEXCLAMATION);

        MessageBox(hWnd, "Couldn't capture the joystick.", NULL,

            MB_OK | MB_ICONEXCLAMATION);

        PostMessage(hWnd,WM_CLOSE,0,0L);

    }

    break;


Processing Joystick Messages

The following example illustrates how an application could respond to joystick movements and changes in the button states. When the joystick changes position, the application moves the cursor and, if either button is pressed, draws a bullet hole on the desktop. When a joystick button is pressed, the application draws a hole on the desktop and plays a sound continuously until a button is released. The messages to watch are MM_JOY1MOVE, MM_JOY1BUTTONDOWN, and MM_JOY1BUTTONUP.

case MM_JOY1MOVE :                     // changed position

    if((UINT) wParam & (JOY_BUTTON1 | JOY_BUTTON2))

        DrawFire(hWnd);

    DrawSight(lParam);                 // calculates new cursor position

    break;

case MM_JOY1BUTTONDOWN :               // button is down

    if((UINT) wParam & JOY_BUTTON1)

    {

        PlaySound(lpButton1, SND_LOOP | SND_ASYNC | SND_MEMORY);

        DrawFire(hWnd);

    }

    else if((UINT) wParam & JOY_BUTTON2)

    {

        PlaySound(lpButton2, SND_ASYNC | SND_MEMORY |  SND_LOOP);

        DrawFire(hWnd);

    }

    break;

case MM_JOY1BUTTONUP :                 // button is up

    sndPlaySound(NULL, 0);             // stops the sound

    break;


Joystick Reference

This section describes the functions, structures, and messages associated with joysticks. The elements are grouped as follows:

Device Capabilities

joyGetDevCaps
joyGetNumDevs
JOYCAPS

Querying a Joystick

joyGetPos
joyGetPosEx
JOYINFO
JOYINFOEX

Capturing a Joystick

joyGetThreshold
joyReleaseCapture
joySetCapture
joySetThreshold
MM_JOY1BUTTONDOWN
MM_JOY1BUTTONUP
MM_JOY1MOVE
MM_JOY1ZMOVE
MM_JOY2BUTTONDOWN
MM_JOY2BUTTONUP
MM_JOY2MOVE
MM_JOY2ZMOVE


Multimedia Joystick Functions

An application uses the joystick functions to query a joystick driver and to prepare an application to receive notification messages from a joystick driver.

The following functions are used with multimedia joysticks.

joyGetDevCaps
joyGetNumDevs
joyGetPos
joyGetPosEx
joyGetThreshold
joyReleaseCapture
joySetCapture
joySetThreshold


Multimedia Joystick Structures

The following structures are used with multimedia joysticks.

JOYCAPS
JOYINFO
JOYINFOEX


Multimedia Joystick Messages

The following messages are used with multimedia joysticks.

MM_JOY1BUTTONDOWN
MM_JOY1BUTTONUP
MM_JOY1MOVE
MM_JOY1ZMOVE
MM_JOY2BUTTONDOWN
MM_JOY2BUTTONUP
MM_JOY2MOVE
MM_JOY2ZMOVE


File Input and Output

The multimedia file I/O services provide more functionality than the standard operating system services, including support for buffered I/O, resource interchange file format (RIFF) files, memory files, and custom storage systems. In addition, the multimedia file I/O services are optimized for applications sensitive to performance.


About File Input and Output

Most multimedia applications require file input and output (I/O) — that is, the ability to create, read, and write disk files. Multimedia file I/O services provide buffered and unbuffered file I/O and support for RIFF files. The services are extensible with custom I/O procedures that can be shared among applications.

Most applications need only the basic file I/O services and the RIFF file I/O services. Applications sensitive to file I/O performance, such as applications that stream data from compact disc  in real time, can optimize performance by using services to directly access the file I/O buffer. Applications that access custom storage systems, such as file archives and databases, can provide their own I/O procedure that reads and writes elements of the storage system.


File Input and Output Services

This section describes procedures for using the following multimedia file I/O services:

•	Basic services

•	Buffered services

•	Resource interchange file format services

•	Custom services


Basic Services

Using the basic I/O services is similar to using the run-time file I/O services of the C run-time library. Files must be opened before they can be read or written. After reading or writing, the file must be closed. You can also change the current read or write location within an open file.

Before you begin any I/O operations to a file, you must open the file by using the mmioOpen function. This function returns a file handle of type HMMIO. You can use this file handle to identify the open file when calling other file I/O functions.

Note  An HMMIO file handle is not a standard file handle. Do not use HMMIO file handles with Win32 or C run-time file I/O functions.

When you use mmioOpen to open a file, you use a flag to specify whether you are opening it for reading, writing, or both. You can also specify flags that enable you to create or delete a file. Use the mmioClose function to close a file when you are finished reading or writing to it.

You can read and write files by using the mmioRead and mmioWrite functions respectively. The next read or write operation occurs at the current file position or file pointer in a file. The current file position is advanced each time a file is read or written.

You can also change the current file position by using the mmioSeek function. You should ensure that you specify a valid location in a file. If you specify an invalid location, such as past the end of the file, mmioSeek may not return an error, but subsequent I/O operations could fail.

There are flags you can use with the mmioOpen function for operations beyond basic file I/O. By specifying an MMIOINFO structure, for example, you can open memory files, specify a custom I/O procedure, or supply a buffer for buffered I/O.


Buffered Services

Most of the overhead in file I/O occurs when accessing the media device. If you are reading or writing many small blocks of information, the device can spend a lot of time moving to the physical location on the media for each read or write operation. In this case, you can achieve better performance by using buffered file I/O services. With buffered I/O, the file I/O manager maintains an intermediate buffer larger than the blocks of information you are reading or writing. It accesses the device only when the buffer must be filled from or written to the disk.

Before you set up and use buffered file I/O, you must decide whether you want the file I/O manager or the application to allocate the buffer. It is simpler to let the file I/O manager allocate the buffer. However, you can let the application allocate the buffer if you want to directly access the buffer or open a memory file. For more information about using memory files, see Performing Memory File I/O. For an example of directly accessing an I/O buffer, see Accessing a File I/O Buffer

A buffer allocated by the file I/O manager is called an internal I/O buffer. To open a file for buffered I/O using an internal buffer, specify the MMIO_ALLOCBUF flag when you open the file with the mmioOpen function. The following illustration shows the initial state of the file I/O buffer after a file is opened for a buffered read operation. The buffering is transparent — you read and seek as if you were using unbuffered I/O. The mmioOpen function has set pchNext and pchEndRead to point to the beginning of the file I/O buffer.

The following illustration shows the initial state of the file I/O buffer after a file is opened for a buffered write operation. The mmioOpen function has set pchNext to point to the beginning of the file I/O buffer and pchEndWrite to point to the end of the buffer.

The default size of the internal I/O buffer is 8K. If this size is not adequate, you can use the mmioSetBuffer function to change the buffer size. You can also use this function to enable buffering on a file opened for unbuffered I/O, or to supply your own buffer for use as a memory file.

You can force the contents of an I/O buffer to be written to disk by using the mmioFlush function. However, when you close a file by using the mmioClose function, you do not have to call mmioFlush to flush an I/O buffer — the mmioClose function automatically flushes it. If you run out of disk space, mmioFlush could fail, even if the preceding calls to the mmioWrite function were successful. Similarly, mmioClose could fail when it is flushing its I/O buffer.

Applications that are performance-sensitive,  such as those that stream data in real time from a CD-ROM, can optimize file I/O performance by directly accessing the I/O buffer. You should be careful if you choose to do this, because you bypass some of the safeguards and error checking provided by the file I/O manager.

The multimedia file I/O manager uses the MMIOINFO structure to maintain state information about an open file. You use three members in this structure to read and write the I/O buffer: pchNext, pchEndRead, and pchEndWrite. The pchNext member points to the next location in the buffer to read or write. You must increment this member as you read and write the buffer. The pchEndRead member identifies the last valid character you can read from the buffer. Likewise, this member identifies the last location in the buffer you can write. More precisely, both pchEndRead and pchEndWrite point to the memory location that follows the last valid data in the buffer. Use the mmioGetInfo and mmioSetInfo functions to retrieve and set state information about the file I/O buffer. The following illustration shows the state of the I/O buffer after the application calls mmioAdvance during a read operation. The mmioAdvance function fills the buffer and sets the pchEndRead pointer to the end of the buffer.

In the following illustration, the application reads from the I/O buffer at the location specified by pchNext, and advances the pointer.

Similarly, for a write operation, the application writes to the I/O buffer and advances the pchNext pointer.

After the application fills the buffer, it calls mmioAdvance to flush the buffer to disk. The mmioAdvance function resets pchNext to point to the beginning of the buffer, as shown following.

When you reach the end of the I/O buffer, you must advance the buffer to fill it from the disk, if you are reading, or flush it to the disk, if you are writing. Use the mmioAdvance function to advance an I/O buffer. To fill an I/O buffer from disk, use mmioAdvance with the MMIO_READ flag. If there is not enough data remaining in the file to fill the buffer, the pchEndRead member of the MMIOINFO structure points to the location following the last valid byte in the buffer. To flush a buffer to disk, set the MMIO_DIRTY flag in the dwFlags member of the MMIOINFO structure and then call mmioAdvance with the MMIO_WRITE flag.

For example, during a read operation, the mmioAdvance function sets pchEndRead to point to the end of valid data in the buffer, as shown following.

Similarly, during a write operation, the application calls mmioAdvance to flush the buffer and advance pchNext to the end of valid data in the buffer, as shown following.


Resource Interchange File Format Services

The preferred format for multimedia files is resource interchange file format (RIFF). The RIFF file I/O functions work with the basic buffered and unbuffered file I/O services. You can open, read, and write RIFF files in the same way as other file types. For detailed information about RIFF, see AVIFile Functions and Macros.

RIFF files use four-character codes to identify file elements. These codes are 32-bit quantities representing a sequence of one to four ASCII alphanumeric characters, padded on the right with space characters. The data type for four-character codes is FOURCC. Use the mmioFOURCC macro to convert four characters into a four-character code. To convert a null-terminated string into a four-character code, use the mmioStringToFOURCC function.

The basic building block of a RIFF file is a chunk. A chunk is a logical unit of multimedia data, such as a single frame in a video clip. Each chunk contains the following fields:

•	A four-character code specifying the chunk identifier

•	A doubleword value specifying the size of the data member in the chunk

•	A data field

The following illustration shows a “RIFF” chunk that contains two subchunks.

A chunk contained in another chunk is a subchunk. The only chunks allowed to contain subchunks are those with a chunk identifier of “RIFF” or “LIST”. A chunk that contains another chunk is called a parent chunk. The first chunk in a RIFF file must be a “RIFF” chunk. All other chunks in the file are subchunks of the “RIFF” chunk.

“RIFF” chunks include an additional field in the first four bytes of the data field. This additional field provides the form type of the field. The form type is a four-character code identifying the format of the data stored in the file. For example, Microsoft waveform-audio files have a form type of “WAVE”.

“LIST” chunks also include an additional field in the first four bytes of the data field. This additional field contains the list type of the field. The list type is a four-character code identifying the contents of the list. For example, a “LIST” chunk with a list type of “INFO” can contain “ICOP” and “ICRD” chunks providing copyright and creation date information. The following illustration shows a “RIFF” chunk that contains a “LIST” chunk and one other subchunk (the “LIST” chunk contains two subchunks).

Multimedia file I/O services include two functions you can use to navigate among chunks in a RIFF file: mmioAscend and mmioDescend. You can use these functions as high-level seek functions. When you descend into a chunk, the file position is set to the data field of the chunk (8 bytes from the beginning of the chunk). For “RIFF” and “LIST” chunks, the file position is set to the location following the form type or list type (12 bytes from the beginning of the chunk). When you ascend out of a chunk, the file position is set to the location following the end of the chunk.

To create a new chunk, use the mmioCreateChunk function to write a chunk header at the current position in an open file. The mmioAscend, mmioDescend, and mmioCreateChunk functions use the MMCKINFO structure to specify and retrieve information about “RIFF” chunks.


Custom Services

Multimedia file I/O services use I/O procedures to handle the physical input and output associated with reading and writing to different types of storage systems, such as file-archival systems and database-storage systems. Predefined I/O procedures exist for the standard file systems and for memory files, but you can supply a custom I/O procedure for accessing a unique storage system by using the mmioInstallIOProc function.

To open a file by using a custom I/O procedure, use the mmioOpen function. Include a plus sign (+) or the CFSEPCHAR constant in the filename to separate the name of the physical file from the name of the element of the file you want to open. The following example opens a file element named “element” from a file named FILENAME.ARC:

mmioOpen("filename.arc+element", NULL, MMIO_READ);

When the file I/O manager encounters a plus sign in a filename, it examines the filename extension to determine which I/O procedure to associate with the file. In the previous example, the file I/O manager would attempt to use the I/O procedure associated with the .ARC filename extension; this I/O procedure would have been installed by using mmioInstallIOProc. If no I/O procedure is installed, mmioOpen returns an error.

I/O procedures must respond to the following messages:

MMIOM_CLOSE
MMIOM_OPEN
MMIOM_READ
MMIOM_WRITE
MMIOM_SEEK
MMIOM_RENAME
MMIOM_WRITEFLUSH

You can also create custom messages and send them to your I/O procedure by using the mmioSendMessage function. If you define your own messages, make sure they are defined at or above the value defined by the MMIOM_USER constant.

In addition to processing messages, an I/O procedure must maintain the lDiskOffset member of the MMIOINFO structure (pointed to by the lpmmioinfo parameter of the mmioOpen function). The lDiskOffset member must always contain the file offset to the location that the next MMIOM_READ or MMIOM_WRITE message will access. The offset is specified in bytes and is relative to the beginning of the file. The I/O procedure can use the adwInfo member to maintain any required state information. The I/O procedure should not modify any other members in the MMIOINFO structure.


Using File Input and Output

This section contains examples demonstrating how to perform the following tasks:

•	Opening a file with mmioOpen

•	Creating and deleting a file.

•	Seeking to a new position in a file.

•	Changing the I/O buffer size.

•	Accessing a file I/O buffer.

•	Generating four-character codes.

•	Creating a RIFF chunk.

•	Searching for a RIFF chunk.

•	Searching for a subchunk.

•	Performing file I/O on RIFF files.

•	Performing memory file I/O.

•	Installing custom I/O procedures.

•	Sharing an I/O procedure with other applications.


Opening a File with mmioOpen

To open a file for basic I/O operations, set the lpmmioinfo parameter of the mmioOpen function to NULL. The following example opens a file named “C:\SAMPLES\SAMPLE1.TXT” for reading, and checks the return value for error.

HMMIO hFile;

if ((hFile = mmioOpen("C:\\SAMPLES\\SAMPLE1.TXT", NULL,

    MMIO_READ)) != NULL)

    // File opened successfully.

else

    // File cannot be opened.

Use the dwFlags parameter of mmioOpen to specify flags for opening a file.


Creating and Deleting a File

To create a file, set the dwOpenFlags parameter of the mmioOpen function to MMIO_CREATE. The following example creates a file and opens it for reading and writing.

HMMIO hFile;

hFile = mmioOpen("NEWFILE.TXT", NULL, MMIO_CREATE | MMIO_READWRITE);

if (hFile != NULL)

    // File created successfully.

else

    // File cannot be created.

If the file you are creating already exists, it will be truncated to zero length.

To delete a file, set the dwOpenFlags parameter of the mmioOpen function to MMIO_DELETE. After you delete a file, it cannot be recovered by any standard means. If your application is deleting a file at the request of a user, query the user before deleting the file to make sure the user wants to delete it.


Seeking to a New Position in a File

The following example moves to the beginning of an open file using the mmioSeek function.

mmioSeek(hFile, 0L, SEEK_SET);

The following example moves to the end of an open file.

mmioSeek(hFile, 0L, SEEK_END);

The following example moves to a position 10 bytes from the end of an open file.

mmioSeek(hFile, -10L, SEEK_END);


Changing the I/O Buffer Size

The following example opens a file named SAMPLE.TXT for unbuffered I/O, and then enables buffered I/O with an internal 16K buffer using the mmioSetBuffer function.

HMMIO hFile;

if ((hFile = mmioOpen("SAMPLE.TXT", NULL, MMIO_READ)) != NULL)

{

    // File opened successfully; request an I/O buffer.

    if (mmioSetBuffer(hFile, NULL, 16384L, 0))

        // Buffer cannot be allocated.

    else

        // Buffer allocated successfully.

}

else

    // File cannot be opened.


Accessing a File I/O Buffer

The following example accesses an I/O buffer directly to read data from a waveform-audio file.

HMMIO    hmmio;

MMIOINFO mmioinfo;

DWORD    dwDataSize;

DWORD    dwCount;

HPSTR    hptr;

// Get information about the file I/O buffer.

if (mmioGetInfo(hmmio, &mmioinfo, 0))

{

    Error("Failed to get I/O buffer info.");

    .

    .

    .

    mmioClose(hmmio, 0);

    return;

}

// Read the entire file by directly reading the file I/O buffer.

// When the end of the I/O buffer is reached, advance the buffer.

for (dwCount = dwDataSize, hptr = lpData; dwCount  0; dwCount--)

{

    // Check to see if the I/O buffer must be advanced.

    if (mmioinfo.pchNext == mmioinfo.pchEndRead)

    {

        if(mmioAdvance(hmmio, &mmioinfo, MMIO_READ))

        {

            Error("Failed to advance buffer.");

            .

            .

            .

            mmioClose(hmmio, 0);

            return;

        }

    }

    // Get a character from the buffer.

    *hptr++ = *mmioinfo.pchNext++;

}

// End direct buffer access and close the file.

mmioSetInfo(hmmio, &mmioinfo, 0);

mmioClose(hmmio, 0);

When you finish accessing a file I/O buffer, call the mmioSetInfo function, passing an address of the MMIOINFO structure filled by the mmioGetInfo function. If you wrote to the buffer, set the MMIO_DIRTY flag in the dwFlags member of the MMIOINFO structure before calling mmioSetInfo. Otherwise, the buffer will not be flushed to disk.


Generating Four-Character Codes

You can use the mmioFOURCC macro or the mmioStringToFOURCC function to generate four-character codes. The following example uses mmioFOURCC to generate a four-character code for “WAVE”.

FOURCC fourccID;

.

.

.

fourccID = mmioFOURCC('W', 'A', 'V', 'E');

The following example uses mmioStringToFOURCC to generate a four-character code for “WAVE”.

FOURCC fourccID;

.

.

.

fourccID = mmioStringToFOURCC("WAVE", 0);

The second parameter in mmioStringToFOURCC specifies flags for converting the string to a four-character code. If you specify the MMIO_TOUPPER flag, mmioStringToFOURCC converts all alphabetic characters in the string to uppercase. This is useful when you need to specify a four-character code to identify a custom I/O procedure because four-character codes identifying file-extension names must be all uppercase.


Creating a RIFF Chunk

The following example uses the mmioCreateChunk function to create a chunk with a chunk identifier of “RIFF” and a form type of “RDIB”.

HMMIO    hmmio;

MMCKINFO mmckinfo;

.

.

.

mmckinfo.fccType = mmioFOURCC('R', 'D', 'I', 'B');

mmioCreateChunk(hmmio, &mmckinfo, MMIO_CREATERIFF);

If you are creating a “RIFF” or “LIST” chunk, you must specify the form type or list type in the fccType member of the MMCKINFO structure. In the previous example, “RDIB” is the form type.

If you know the size of the data field in a new chunk, you can set the cksize member of the MMCKINFO structure when you create the chunk. This value will be written to the data size field in the new chunk. If this value is not correct when you call mmioAscend to mark the end of the chunk, it will be automatically rewritten to reflect the correct size of the data field.

After you create a chunk by using the mmioCreateChunk function, the file position is set to the data field of the chunk (8 bytes from the beginning of the chunk). If the chunk is a “RIFF” or “LIST” chunk, the file position is set to the location following the form type or list type (12 bytes from the beginning of the chunk).


Searching for a RIFF Chunk

The following example uses the mmioDescend function to search for a “RIFF” chunk with a form type of “WAVE” to verify that the file that has just been opened is a waveform-audio file.

HMMIO    hmmio;

MMCKINFO mmckinfoParent;

MMCKINFO mmckinfoSubchunk;

.

.

.

// Locate a "RIFF" chunk with a "WAVE" form type to make

// sure the file is a waveform-audio file.

mmckinfoParent.fccType = mmioFOURCC('W', 'A', 'V', 'E');

if (mmioDescend(hmmio, (LPMMCKINFO) &mmckinfoParent, NULL,

    MMIO_FINDRIFF))

    // The file is not a waveform-audio file.

else

    // The file is a waveform-audio file


Searching for a Subchunk

The following example uses the mmioDescend function to search for the “FMT” chunk in the “RIFF” chunk of the previous example.

// Find the format chunk (form type "FMT"); it should be

// a subchunk of the "RIFF" parent chunk.

mmckinfoSubchunk.ckid = mmioFOURCC('f', 'm', 't', ' ');

if (mmioDescend(hmmio, &mmckinfoSubchunk, &mmckinfoParent,

    MMIO_FINDCHUNK))

    // Error, cannot find the "FMT" chunk.

else

    // "FMT" chunk found.

To search for a subchunk (that is, any chunk other than a “RIFF” or “LIST” chunk), identify its parent chunk in the lpckParent parameter of the mmioDescend function.

If you do not specify a parent chunk, the current file position should be at the beginning of a chunk before you call the mmioDescend function. If you do specify a parent chunk, the current file position can be anywhere in that chunk.

If the search for a subchunk fails, the current file position is undefined. You can use the mmioSeek function and the dwDataOffset member of the MMCKINFO structure describing the parent chunk to seek back to the beginning of the parent chunk, as in the following example:

mmioSeek(hmmio, mmckinfoParent.dwDataOffset + 4, SEEK_SET);

Because dwDataOffset specifies the offset to the beginning of the data portion of the chunk, you must seek 4 bytes past dwDataOffset to set the file position after the form type.


Performing File I/O on RIFF Files

The following example shows how to open a RIFF file for buffered I/O, as well as how to descend, ascend, and read “RIFF” chunks.

// ReversePlay--Plays a waveform-audio file backward.

void ReversePlay()

{

    char        szFileName[128];    // filename of file to open

    HMMIO       hmmio;              // file handle for open file

    MMCKINFO    mmckinfoParent;     // parent chunk information

    MMCKINFO    mmckinfoSubchunk;   // subchunk information structure

    DWORD       dwFmtSize;          // size of "FMT" chunk

    DWORD       dwDataSize;         // size of "DATA" chunk

    WAVEFORMAT  *pFormat;           // address of "FMT" chunk

    HPSTR       lpData;             // address of "DATA" chunk

    // Get the filename from the edit control.

    .

    .

    .

    // Open the file for reading with buffered I/O

    // by using the default internal buffer

    if(!(hmmio = mmioOpen(szFileName, NULL,

        MMIO_READ | MMIO_ALLOCBUF)))

    {

        Error("Failed to open file.");

        return;

    }

    // Locate a "RIFF" chunk with a "WAVE" form type to make

    // sure the file is a waveform-audio file.

    mmckinfoParent.fccType = mmioFOURCC('W', 'A', 'V', 'E');

    if (mmioDescend(hmmio, (LPMMCKINFO) &mmckinfoParent, NULL,

        MMIO_FINDRIFF))

    {

        Error("This is not a waveform-audio file.");

        mmioClose(hmmio, 0);

        return;

    }

    // Find the "FMT" chunk (form type "FMT"); it must be

    // a subchunk of the "RIFF" chunk.

    mmckinfoSubchunk.ckid = mmioFOURCC('f', 'm', 't', ' ');

    if (mmioDescend(hmmio, &mmckinfoSubchunk, &mmckinfoParent,

        MMIO_FINDCHUNK))

    {

        Error("Waveform-audio file has no "FMT" chunk.");

        mmioClose(hmmio, 0);

        return;

    }

    // Get the size of the "FMT" chunk. Allocate

    // and lock memory for it.

    dwFmtSize = mmckinfoSubchunk.cksize;

    .

    .

    .

    // Read the "FMT" chunk.

    if (mmioRead(hmmio, (HPSTR) pFormat, dwFmtSize) != dwFmtSize){

        Error("Failed to read format chunk.");

        .

        .

        .

        mmioClose(hmmio, 0);

        return;

    }

    // Ascend out of the "FMT" subchunk.

    mmioAscend(hmmio, &mmckinfoSubchunk 0);

    // Find the data subchunk. The current file position should be at

    // the beginning of the data chunk; however, you should not make

    // this assumption. Use mmioDescend to locate the data chunk.

    mmckinfoSubchunk.ckid = mmioFOURCC('d', 'a', 't', 'a');

    if (mmioDescend(hmmio, &mmckinfoSubchunk, &mmckinfoParent,

        MMIO_FINDCHUNK))

    {

        Error("Waveform-audio file has no data chunk.");

        .

        .

        .

        mmioClose(hmmio, 0);

        return;

    }

    // Get the size of the data subchunk.

    dwDataSize = mmckinfoSubchunk.cksize;

    if (dwDataSize == 0L){

        Error("The data chunk contains no data.");

        .

        .

        .

        mmioClose(hmmio, 0);

        return;

    }

    // Open a waveform-audio output device.

    .

    .

    .

    // Allocate and lock memory for the waveform-audio data.

    .

    .

    .

    // Read the waveform-audio data subchunk.

    if(mmioRead(hmmio, (HPSTR) lpData, dwDataSize) != dwDataSize){

        Error("Failed to read data chunk.");

        .

        .

        .

        mmioClose(hmmio, 0);

        return;

    }

    // Close the file.

    mmioClose(hmmio, 0);

    // Reverse the sound and play it.

    .

    .

    .

}


Performing Memory File I/O

The multimedia file I/O services let you treat a block of memory as a file. This can be useful if you already have a file image in memory. Memory files let you reduce the number of special-case conditions in your code because, for I/O purposes, you can treat memory files as if they were disk-based files. You can also use memory files with the clipboard.

As with I/O buffers, memory files can use memory allocated by the application or by the file I/O manager. In addition, memory files can be either expandable or nonexpandable. When the file I/O manager reaches the end of an expandable memory file, it expands the memory file by a predefined increment.

To open a memory file, use the mmioOpen function with the szFilename parameter set to NULL and the MMIO_READWRITE flag set in the dwOpenFlags parameter. Set the lpmmioinfo parameter to point to an MMIOINFO structure that has been set up as follows:

1.	Set the pIOProc member to NULL.

2.	Set the fccIOProc member to FOURCC_MEM.

3.	Set the pchBuffer member to point to the memory block. To request that the file I/O manager allocate the memory block, set pchBuffer to NULL.

4.	Set the cchBuffer member to the initial size of the memory block.

5.	Set the adwInfo member to the minimum expansion size of the memory block. For a nonexpandable memory file, set adwInfo to NULL.

6.	Set all other members to zero.

There are no restrictions on allocating memory for use as a nonexpandable memory file.


Installing Custom I/O Procedures

To install an I/O procedure associated with the .ARC filename extension, use the mmioInstallIOProc function as follows:

mmioInstallIOProc (mmioFOURCC('A', 'R', 'C', ' '),

    (LPMMIOPROC)lpmmioproc, MMIO_INSTALLPROC);

When you install an I/O procedure using mmioInstallIOProc, the procedure remains installed until you remove it. The I/O procedure is used for any file you open as long as the file has the appropriate filename extension.

You can also temporarily install an I/O procedure by using the mmioOpen function. In this case, the I/O procedure is used only with a file opened by using mmioOpen and is removed when the file is closed by using the mmioClose function. To specify an I/O procedure when you open a file by using mmioOpen, use the lpmmioinfo parameter to reference an MMIOINFO structure as follows:

1.	Set the fccIOProc member to NULL.

2.	Set the pIOProc member to the procedure-instance address of the I/O procedure.

3.	Set all other members to zero (unless you are opening a memory file, or directly reading or writing to the file I/O buffer).

Be sure to remove any I/O procedures you have installed before you exit your application.


Sharing an I/O Procedure with Other Applications

If you want to share an I/O procedure with other applications, you need to write a dynamic-link library (DLL) for your application. You can share the I/O procedure by doing one of the following:

•	Include the code for the I/O procedure in the DLL.

•	Create a function in the DLL that calls the mmioInstallIOProc function to install the I/O procedure.

•	Export this function in the module-definitions file of the DLL.

To use the shared I/O procedure, an application must first call the function in the DLL to install the I/O procedure.


File Input and Output Reference

This section describes the functions, macros, messages, and structures associated with multimedia file input and output. These elements are grouped as follows.

Basic I/O

mmioClose
mmioOpen
mmioRead
mmioRename
mmioSeek
mmioWrite

Buffered I/O

mmioAdvance
mmioFlush
mmioGetInfo
MMIOINFO
mmioSetBuffer
mmioSetInfo

RIFF I/O

mmioAscend
MMCKINFO
mmioCreateChunk
mmioDescend
mmioFOURCC
mmioStringToFOURCC

Custom I/O Procedures

IOProc
mmioInstallIOProc
MMIOM_CLOSE
MMIOM_OPEN
MMIOM_READ
MMIOM_RENAME
MMIOM_SEEK
MMIOM_WRITE
MMIOM_WRITEFLUSH
mmioSendMessage


Multimedia File I/O Functions

The following functions are used with multimedia file I/O.

IOProc
mmioAdvance
mmioAscend
mmioClose
mmioCreateChunk
mmioDescend
mmioFlush
mmioGetInfo
mmioInstallIOProc
mmioOpen
mmioRead
mmioRename
mmioSeek
mmioSendMessage
mmioSetBuffer
mmioSetInfo
mmioStringToFOURCC
mmioWrite


Multimedia File I/O Structures

The following structures are used with multimedia file I/O.

MMCKINFO
MMIOINFO


Multimedia File I/O Messages

The following messages are used with multimedia file I/O.

MMIOM_CLOSE
MMIOM_OPEN
MMIOM_READ
MMIOM_RENAME
MMIOM_SEEK
MMIOM_WRITE
MMIOM_WRITEFLUSH


Multimedia Timers

The multimedia timer services allow an application to schedule periodic timer events — that is, the application can request and receive timer messages at application-specified intervals.


About Multimedia Timers

Multimedia timer services allow applications to schedule timer events with the greatest resolution (or accuracy) possible for the hardware platform. These multimedia timer services allow you to schedule timer events at a higher resolution than other timer services.

These timer services are useful for applications that demand high-resolution timing. For example, a MIDI sequencer requires a high-resolution timer because it must maintain the pace of MIDI events within a resolution of 1 millisecond.

Applications that do not use high-resolution timing should use the SetTimer function instead of multimedia timer services. The timer services provided by SetTimer post WM_TIMER messages to a message queue, while the multimedia timer services call a callback function. Applications that want a waitable timer should use the CreateWaitableTimer function.


Obtaining the System Time

Typically, before an application begins using the multimedia timer services, it retrieves the current system time. The system time is the time, in milliseconds, since the Microsoft Windows operating system was started. You can use the timeGetTime or timeGetSystemTime function to retrieve the system time. These two functions are very similar: timeGetTime returns the system time, and timeGetSystemTime fills an MMTIME structure with the system time.


Timer Resolution

To determine the minimum and maximum timer resolutions supported by the timer services, use the timeGetDevCaps function. This function fills the wPeriodMin and wPeriodMax members of the TIMECAPS structure with the minimum and maximum resolutions. This range can vary across computers and Windows platforms.

After you determine the minimum and maximum available timer resolutions, you must establish the minimum resolution you want your application to use. Use the timeBeginPeriod and timeEndPeriod functions to set and clear this resolution. You must match each call to timeBeginPeriod with a call to timeEndPeriod, specifying the same minimum resolution in both calls. An application can make multiple timeBeginPeriod calls, as long as each call is matched with a call to timeEndPeriod.

In both timeBeginPeriod and timeEndPeriod, the uPeriod parameter indicates the minimum timer resolution, in milliseconds. You can specify any timer resolution value within the range supported by the timer.


Timer Event Operations

After you have established your application’s timer resolution, you can start timer events by using the timeSetEvent function. This function returns a timer identifier that can be used to stop or identify timer events. One of the function’s parameters is the address of a TimeProc callback function that is called when the timer event takes place.

There are two types of timer events: single and periodic. A single timer event occurs once, after a specified number of milliseconds. A periodic timer event occurs every time a specified number of milliseconds elapses. The interval between periodic events is called an event delay. Periodic timer events with an event delay of 10 milliseconds or less consume a significant portion of CPU resources.

The relationship between the resolution of a timer event and the length of the event delay is important in timer events. For example, if you specify a resolution of 5 and an event delay of 100, the timer services notify the callback function after an interval ranging from 95 to 105 milliseconds.

You can cancel an active timer event at any time by using the timeKillEvent function. Be sure to cancel any outstanding timers before freeing the memory containing the callback function.

Note  The multimedia timer runs in its own thread.


Using Multimedia Timers

This section contains examples demonstrating how to perform the following tasks:

•	Obtaining and setting timer resolution

•	Starting a single timer event

•	Writing a timer callback function

•	Canceling a timer event


Obtaining and Setting Timer Resolution

The following example calls the timeGetDevCaps function to determine the minimum and maximum timer resolutions supported by the timer services. Before it sets up any timer events, the example establishes the minimum timer resolution by using the timeBeginPeriod function.

#define TARGET_RESOLUTION 1         // 1-millisecond target resolution

TIMECAPS tc;

UINT     wTimerRes;

if (timeGetDevCaps(&tc, sizeof(TIMECAPS)) != TIMERR_NOERROR)

{

    // Error; application can't continue.

}

wTimerRes = min(max(tc.wPeriodMin, TARGET_RESOLUTION), tc.wPeriodMax);

timeBeginPeriod(wTimerRes);


Starting a Single Timer Event

To start a single timer event, an application must call the timeSetEvent function, specifying the amount of time before the callback occurs, the resolution, the address of the callback function (see TimeProc), and the user data to supply with the callback function. An application can use a function like the following to start a single timer event.

UINT SetTimerCallback(NPSEQ npSeq,  // sequencer data

    UINT msInterval)                // event interval

{

    npSeq->wTimerID = timeSetEvent(

        msInterval,                    // delay

        wTimerRes,                     // resolution (global variable)

        OneShotCallback,               // callback function

        (DWORD)npSeq,                  // user data

        TIME_ONESHOT );                // single timer event

    if(! npSeq->wTimerID)

        return ERR_TIMER;

    else

        return ERR_NOERROR;

}

For an example of the callback function OneShotCallback, see Writing a Timer Callback Function.


Writing a Timer Callback Function

The following callback function, OneShotTimer, invalidates the identifier for the single timer event and calls a timer routine to handle the application-specific tasks. For more information, see TimeProc.

void CALLBACK OneShotTimer(UINT wTimerID, UINT msg,

    DWORD dwUser, DWORD dw1, DWORD dw2)

{

    NPSEQ npSeq;             // pointer to sequencer data

    npSeq = (NPSEQ)dwUser;
    npSeq->wTimerID = 0;     // invalidate timer ID (no longer in use)

    TimerRoutine(npSeq);     // handle tasks

}


Canceling a Timer Event

The application must cancel any outstanding timers by calling the timeKillEvent function before it frees the memory that contains the callback function. To cancel a timer event, it might call the following function.

void DestroyTimer(NPSEQ npSeq)

{

    if(npSeq->wTimerID) {                // is timer event pending?

        timeKillEvent(npSeq->wTimerID);  // cancel the event

        npSeq->wTimerID = 0;

    }

}


Multimedia Timer Reference

This section describes the functions and structures associated with multimedia timer services. These elements are grouped as follows.

Retrieving the System Time

MMTIME
timeGetSystemTime
timeGetTime

Retrieving Timer Information

TIMECAPS
timeGetDevCaps

Time Events

timeKillEvent
TimeProc
timeSetEvent

Time Periods

timeBeginPeriod
timeEndPeriod


Multimedia Timer Functions

The following functions are used with multimedia timers.

timeBeginPeriod
timeEndPeriod
timeGetDevCaps
timeGetSystemTime
timeGetTime
timeKillEvent
TimeProc
timeSetEvent


Multimedia Timer Structures

The following structures are used with multimedia timers.

MMTIME
TIMECAPS


ACMDRIVERDETAILS

The ACMDRIVERDETAILS structure describes the features of an ACM driver.

typedef struct {

    DWORD  cbStruct;

    FOURCC fccType;

    FOURCC fccComp;

    WORD   wMid;

    WORD   wPid;

    DWORD  vdwACM;

    DWORD  vdwDriver;

    DWORD  fdwSupport;

    DWORD  cFormatTags;

    DWORD  cFilterTags;

    HICON  hicon;

    char  szShortName[ACMDRIVERDETAILS_SHORTNAME_CHARS];

    char  szLongName[ACMDRIVERDETAILS_LONGNAME_CHARS];

    char  szCopyright[ACMDRIVERDETAILS_COPYRIGHT_CHARS];

    char  szLicensing[ACMDRIVERDETAILS_LICENSING_CHARS];

    char  szFeatures[ACMDRIVERDETAILS_FEATURES_CHARS];

} ACMDRIVERDETAILS;

Members

cbStruct

Size, in bytes, of the valid information contained in the ACMDRIVERDETAILS structure. An application should initialize this member to the size, in bytes, of the desired information. The size specified in this member must be large enough to contain the cbStruct member of the ACMDRIVERDETAILS structure. When the acmDriverDetails function returns, this member contains the actual size of the information returned. The returned information will never exceed the requested size.

fccType

Type of the driver. For ACM drivers, set this member to ACMDRIVERDETAILS_FCCTYPE_AUDIOCODEC.

fccComp

Subtype of the driver. This member is currently set to ACMDRIVERDETAILS_FCCCOMP_UNDEFINED (zero).

wMid

Manufacturer identifier. Manufacturer identifiers are defined in Manufacturer and Product Identifiers.

wPid

Product identifier. Product identifiers are defined in Manufacturer and Product Identifiers.

vdwACM

Version of the ACM for which this driver was compiled. The version number is a hexadecimal number in the format 0xAABBCCCC, where AA is the major version number, BB is the minor version number, and CCCC is the build number. The version parts (major, minor, and build) should be displayed as decimal numbers.

vdwDriver

Version of the driver. The version number is a hexadecimal number in the format 0xAABBCCCC, where AA is the major version number, BB is the minor version number, and CCCC is the build number. The version parts (major, minor, and build) should be displayed as decimal numbers.

fdwSupport

Support flags for the driver. The following values are defined:

ACMDRIVERDETAILS_SUPPORTF_ASYNC

Driver supports asynchronous conversions.

ACMDRIVERDETAILS_SUPPORTF_CODEC

Driver supports conversion between two different format tags. For example, if a driver supports compression from WAVE_FORMAT_PCM to WAVE_FORMAT_ADPCM, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_CONVERTER

Driver supports conversion between two different formats of the same format tag. For example, if a driver supports resampling of WAVE_FORMAT_PCM, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_DISABLED

Driver has been disabled. This flag is set by the ACM for a driver when it has been disabled for any of a number of reasons. Disabled drivers cannot be opened and can be used only under very limited circumstances.

ACMDRIVERDETAILS_SUPPORTF_FILTER

Driver supports a filter (modification of the data without changing any of the format attributes). For example, if a driver supports volume or echo operations on WAVE_FORMAT_PCM, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_HARDWARE

Driver supports hardware input, output, or both through a waveform-audio device. An application should use the acmMetrics function with the ACM_METRIC_HARDWARE_WAVE_INPUT and ACM_METRIC_HARDWARE_WAVE_OUTPUT metric indexes to get the waveform-audio device identifiers associated with the supporting ACM driver.

ACMDRIVERDETAILS_SUPPORTF_LOCAL

The driver has been installed locally with respect to the current task.

cFormatTags

Number of unique format tags supported by this driver.

cFilterTags

Number of unique filter tags supported by this driver.

hicon

Handle of a custom icon for this driver. An application can use this icon for referencing the driver visually. This member can be NULL.

szShortName

Null-terminated string that describes the name of the driver. This string is intended to be displayed in small spaces.

szLongName

Null-terminated string that describes the full name of the driver. This string is intended to be displayed in large (descriptive) spaces.

szCopyright

Null-terminated string that provides copyright information for the driver.

szLicensing

Null-terminated string that provides special licensing information for the driver.

szFeatures

Null-terminated string that provides special feature information for the driver.

See Also

acmDriverDetails, acmMetrics


ACMFILTERCHOOSE

The ACMFILTERCHOOSE structure contains information the ACM uses to initialize the system-defined waveform-audio filter selection dialog box. After the user closes the dialog box, the system returns information about the user’s selection in this structure.

typedef struct {

    DWORD                   cbStruct;

    DWORD                   fdwStyle;

    HWND                    hwndOwner;

    LPWAVEFILTER            pwfltr;

    DWORD                   cbwfltr;

    LPCSTR                  pszTitle;

    char szFilterTag[ACMFILTERTAGDETAILS_FILTERTAG_CHARS];

    char szFilter[ACMFILTERDETAILS_FILTER_CHARS];

    LPSTR                   pszName;

    DWORD                   cchName;

    DWORD                   fdwEnum;

    LPWAVEFILTER            pwfltrEnum;

    HINSTANCE               hInstance;

    LPCSTR                  pszTemplateName;

    LPARAM                  lCustData;

    ACMFILTERCHOOSEHOOKPROC pfnHook;

} ACMFILTERCHOOSE;

Members

cbStruct

Size, in bytes, of the ACMFILTERCHOOSE structure. This member must be initialized before an application calls the acmFilterChoose function. The size specified in this member must be large enough to contain the base ACMFILTERCHOOSE structure.

fdwStyle

Optional style flags for the acmFilterChoose function. This member must be initialized to a valid combination of the following flags before an application calls the acmFilterChoose function. The following values are defined:

ACMFILTERCHOOSE_STYLEF_CONTEXTHELP

Context-sensitive help will be available in the dialog box. To use this feature, an application must register the ACMHELPMSGCONTEXTMENU and ACMHELPMSGCONTEXTHELP constants, using the RegisterWindowMessage function. When the user invokes help, the registered message will be posted to the owning window. The message will contain the wParam and lParam parameters from the original WM_CONTEXTMENU or WM_CONTEXTHELP message.

ACMFILTERCHOOSE_STYLEF_ENABLEHOOK

Enables the hook function specified in the pfnHook member. An application can use hook functions for a variety of customizations, including answering the MM_ACM_FILTERCHOOSE message.

ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATE

Causes the ACM to create the dialog box template identified by the hInstance and pszTemplateName members.

ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATEHANDLE

The hInstance member identifies a data block that contains a preloaded dialog box template. If this flag is specified, the ACM ignores the pszTemplateName member.

ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT

The buffer pointed to by pwfltr contains a valid WAVEFILTER structure that the dialog box will use as the initial selection.

ACMFILTERCHOOSE_STYLEF_SHOWHELP

A help button will appear in the dialog box. To use a custom Help file, an application must register the ACMHELPMSGSTRING value with the RegisterWindowMessage function. When the user presses the help button, the registered message is posted to the owner.

hwndOwner

Handle of the window that owns the dialog box. This member can be any valid window handle or NULL if the dialog box has no owner. This member must be initialized before calling the acmFilterChoose function.

pwfltr

Address of a WAVEFILTER structure. If the ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT flag is specified in the fdwStyle member, this structure must be initialized to a valid filter. When the acmFilterChoose function returns, this buffer contains the selected filter. If the user cancels the dialog box, no changes will be made to this buffer.

cbwfltr

Size, in bytes, of the buffer pointed to by the pwfltr member. The acmFilterChoose function returns ACMERR_NOTPOSSIBLE if the buffer is too small to contain the filter information; the ACM also copies the required size into this member. An application can use the acmMetrics and acmFilterTagDetails functions to determine the largest size required for this buffer.

pszTitle

Address of a string to be placed in the title bar of the dialog box. If this member is NULL, the ACM uses the default title (that is, “Filter Selection”).

szFilterTag

Buffer containing a null-terminated string describing the filter tag of the filter selection when the acmFilterChoose function returns. This string is equivalent to the szFilterTag member of the ACMFILTERTAGDETAILS structure returned by acmFilterTagDetails. If the user cancels the dialog box, this member will contain a null-terminated string.

szFilter

Buffer containing a null-terminated string describing the filter attributes of the filter selection when the acmFilterChoose function returns. This string is equivalent to the szFilter member of the ACMFILTERDETAILS structure returned by acmFilterDetails. If the user cancels the dialog box, this member will contain a null-terminated string.

pszName

Address of a string for a user-defined filter name. If this is a non-null-terminated string, the ACM attempts to match the name with a previously saved user-defined filter name. If a match is found, the dialog box is initialized to that filter. If a match is not found or this member is a null-terminated string, this member is ignored for input. When the acmFilterChoose function returns, this buffer contains a null-terminated string describing the user-defined filter. If the filter name is untitled (that is, the user has not given a name for the filter), this member will be a null-terminated string on return. If the user cancels the dialog box, no changes will be made to this buffer.

If the ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT flag is specified by the fdwStyle member, the pszName member is ignored as an input member.

cchName

Size, in characters, of the buffer identified by the pszName member. This buffer should be at least 128 characters long. If pszName is NULL, this member is ignored.

fdwEnum

Optional flags for restricting the type of filters listed in the dialog box. These flags are identical to the fdwEnum flags for the acmFilterEnum function. If pwfltrEnum is NULL, this member should be zero.

ACM_FILTERENUMF_DWFILTERTAG

The dwFilterTag member of the WAVEFILTER structure pointed to by the pwfltrEnum member is valid. The enumerator will only enumerate a filter that conforms to this attribute.

pwfltrEnum

Address of a WAVEFILTER structure that will be used to restrict the filters listed in the dialog box. The fdwEnum member defines which members of this structure should be used for the enumeration restrictions. The cbStruct member of this WAVEFILTER structure must be initialized to the size of the WAVEFILTER structure. If no special restrictions are desired, this member can be NULL.

hInstance

Handle of a data block that contains a dialog box template specified by the pszTemplateName member. This member is used only if the fdwStyle member specifies the ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATE or ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATEHANDLE flag; otherwise, this member should be NULL on input.

pszTemplateName

Address of a null-terminated string that specifies the name of the resource file for the dialog box template that is to be substituted for the dialog box template in the ACM. An application can use the MAKEINTRESOURCE macro for numbered dialog box resources. This member is used only if the fdwStyle member specifies the ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATE flag; otherwise, this member should be NULL on input.

lCustData

Application-defined data that the ACM passes to the hook function identified by the pfnHook member. The system passes the data in the lParam parameter of the WM_INITDIALOG message.

pfnHook

Address of a hook function that processes messages intended for the dialog box. An application must specify the ACMFILTERCHOOSE_STYLEF_ENABLEHOOK flag in the fdwStyle member to enable the hook; otherwise, this member should be NULL. The hook function should return FALSE to pass a message to the standard dialog box procedure or TRUE to discard the message.

See Also

acmFilterChoose, acmFilterDetails, acmFilterEnum, ACMFILTERDETAILS, acmFilterTagDetails, ACMFILTERTAGDETAILS, acmMetrics, MAKEINTRESOURCE, MM_ACM_FILTERCHOOSE, RegisterWindowMessage, WAVEFILTER, WM_INITDIALOG


ACMFILTERDETAILS

The ACMFILTERDETAILS structure details a waveform-audio filter for a specific filter tag for an ACM driver.

typedef struct {

    DWORD        cbStruct;

    DWORD        dwFilterIndex;

    DWORD        dwFilterTag;

    DWORD        fdwSupport;

    LPWAVEFILTER pwfltr;

    DWORD        cbwfltr;

    char        szFilter[ACMFILTERDETAILS_FILTER_CHARS];

} ACMFILTERDETAILS;

Members

cbStruct

Size, in bytes, of the ACMFILTERDETAILS structure. This member must be initialized before calling the acmFilterDetails or acmFilterEnum functions. The size specified in this member must be large enough to contain the base ACMFILTERDETAILS structure. When the acmFilterDetails function returns, this member contains the actual size of the information returned. The returned information will never exceed the requested size.

dwFilterIndex

Index of the filter about which details will be retrieved. The index ranges from zero to one less than the number of standard filters supported by an ACM driver for a filter tag. The number of standard filters supported by a driver for a filter tag is contained in the cStandardFilters member of the ACMFILTERTAGDETAILS structure. The dwFilterIndex member is used only when querying standard filter details about a driver by index; otherwise, this member should be zero. Also, this member will be set to zero by the ACM when an application queries for details on a filter; in other words, this member is used only for input and is never returned by the ACM or an ACM driver.

dwFilterTag

Waveform-audio filter tag that the ACMFILTERDETAILS structure describes. This member is used as an input for the ACM_FILTERDETAILSF_INDEX query flag. For the ACM_FILTERDETAILSF_FORMAT query flag, this member must be initialized to the same filter tag as the pwfltr member specifies. If the acmFilterDetails function is successful, this member is always returned. This member should be set to WAVE_FILTER_UNKNOWN for all other query flags.

fdwSupport

Driver-support flags specific to the specified filter. These flags are identical to the fdwSupport flags of the ACMDRIVERDETAILS structure, but they are specific to the filter that is being queried. This member can be a combination of the following values and identifies which operations the driver supports for the filter tag:

ACMDRIVERDETAILS_SUPPORTF_ASYNC

Driver supports asynchronous conversions.

ACMDRIVERDETAILS_SUPPORTF_CODEC

Driver supports conversion between two different format tags while using the specified filter. For example, if a driver supports compression from WAVE_FORMAT_PCM to WAVE_FORMAT_ADPCM with the specified filter, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_CONVERTER

Driver supports conversion between two different formats of the same format tag while using the specified filter. For example, if a driver supports resampling of WAVE_FORMAT_PCM with the specified filter, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_FILTER

Driver supports a filter (modification of the data without changing any of the format attributes). For example, if a driver supports volume or echo operations on WAVE_FORMAT_PCM, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_HARDWARE

Driver supports hardware input, output, or both with the specified filter through a waveform-audio device. An application should use the acmMetrics function with the ACM_METRIC_HARDWARE_WAVE_INPUT and ACM_METRIC_HARDWARE_WAVE_OUTPUT metric indexes to retrieve the waveform-audio device identifiers associated with the supporting ACM driver.

pwfltr

Address of a WAVEFILTER structure that will receive the filter details. This structure requires no initialization by the application unless the ACM_FILTERDETAILSF_FILTER flag is specified with the acmFilterDetails function. In this case, the dwFilterTag member of the WAVEFILTER structure must be equal to the dwFilterTag member of the ACMFILTERDETAILS structure.

cbwfltr

Size, in bytes, available for pwfltr to receive the filter details. The acmMetrics and acmFilterTagDetails functions can be used to determine the maximum size required for any filter available for the specified driver (or for all installed ACM drivers).

szFilter

String that describes the filter for the dwFilterTag type. If the acmFilterDetails function is successful, this string is always returned.

See Also

acmFilterDetails, ACMDRIVERDETAILS, acmFilterEnum, acmFilterTagDetails, ACMFILTERTAGDETAILS, acmMetrics, WAVEFILTER


ACMFILTERTAGDETAILS

The ACMFILTERTAGDETAILS structure details a waveform-audio filter tag for an ACM filter driver.

typedef struct {

    DWORD cbStruct;

    DWORD dwFilterTagIndex;

    DWORD dwFilterTag;

    DWORD cbFilterSize;

    DWORD fdwSupport;

    DWORD cStandardFilters;

    char szFilterTag[ACMFILTERTAGDETAILS_FILTERTAG_CHARS];

} ACMFILTERTAGDETAILS;

Members

cbStruct

Size, in bytes, of the ACMFILTERTAGDETAILS structure. This member must be initialized before an application calls the acmFilterTagDetails or acmFilterTagEnum function. The size specified in this member must be large enough to contain the base ACMFILTERTAGDETAILS structure. When the acmFilterTagDetails function returns, this member contains the actual size of the information returned. The returned information will never exceed the requested size.

dwFilterTagIndex

Index of the filter tag to retrieve details for. The index ranges from zero to one less than the number of filter tags supported by an ACM driver. The number of filter tags supported by a driver is contained in the cFilterTags member of the ACMDRIVERDETAILS structure. The dwFilterTagIndex member is used only when querying filter tag details about a driver by index; otherwise, this member should be zero.

dwFilterTag

Waveform-audio filter tag that the ACMFILTERTAGDETAILS structure describes. This member is used as an input for the ACM_FILTERTAGDETAILSF_FILTERTAG and ACM_FILTERTAGDETAILSF_LARGESTSIZE query flags. This member is always returned if the acmFilterTagDetails function is successful. This member should be set to WAVE_FILTER_UNKNOWN for all other query flags.

cbFilterSize

Largest total size, in bytes, of a waveform-audio filter of the dwFilterTag type. For example, this member will be 40 for WAVE_FILTER_ECHO and 36 for WAVE_FILTER_VOLUME.

fdwSupport

Driver-support flags specific to the filter tag. These flags are identical to the fdwSupport flags of the ACMDRIVERDETAILS structure. This member can be a combination of the following values and identifies which operations the driver supports with the filter tag:

ACMDRIVERDETAILS_SUPPORTF_ASYNC

Driver supports asynchronous conversions.

ACMDRIVERDETAILS_SUPPORTF_CODEC

Driver supports conversion between two different format tags while using the specified filter tag. For example, if a driver supports compression from WAVE_FORMAT_PCM to WAVE_FORMAT_ADPCM with the specified filter tag, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_CONVERTER

Driver supports conversion between two different formats of the same format tag while using the specified filter tag. For example, if a driver supports resampling of WAVE_FORMAT_PCM with the specified filter tag, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_FILTER

Driver supports a filter (modification of the data without changing any of the format attributes). For example, if a driver supports volume or echo operations on WAVE_FORMAT_PCM, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_HARDWARE

Driver supports hardware input, output, or both with the specified filter tag through a waveform-audio device. An application should use the acmMetrics function with the ACM_METRIC_HARDWARE_WAVE_INPUT and ACM_METRIC_HARDWARE_WAVE_OUTPUT metric indexes to get the waveform-audio device identifiers associated with the supporting ACM driver.

cStandardFilters

Number of standard filters of the dwFilterTag type (that is, the combination of all filter characteristics). This value cannot specify all filters supported by the driver.

szFilterTag

String that describes the dwFilterTag type. This string is always returned if the acmFilterTagDetails function is successful.

See Also

ACMDRIVERDETAILS, acmFilterTagDetails, acmFilterTagEnum


ACMFORMATCHOOSE

The ACMFORMATCHOOSE structure contains information the ACM uses to initialize the system-defined waveform-audio format selection dialog box. After the user closes the dialog box, the system returns information about the user’s selection in this structure.

typedef struct {

    DWORD                   cbStruct;

    DWORD                   fdwStyle;

    HWND                    hwndOwner;

    LPWAVEFORMATEX          pwfx;

    DWORD                   cbwfx;

    LPCSTR                  pszTitle;

    char szFormatTag[ACMFORMATTAGDETAILS_FORMATTAG_CHARS];

    char szFormat[ACMFORMATDETAILS_FORMAT_CHARS];

    LPSTR                   pszName;

    DWORD                   cchName;

    DWORD                   fdwEnum;

    LPWAVEFORMATEX          pwfxEnum;

    HINSTANCE               hInstance;

    LPCSTR                  pszTemplateName;

    LPARAM                  lCustData;

    ACMFORMATCHOOSEHOOKPROC pfnHook;

} ACMFORMATCHOOSE;

Members

cbStruct

Size, in bytes, of the ACMFORMATCHOOSE structure. This member must be initialized before an application calls the acmFormatChoose function. The size specified in this member must be large enough to contain the base ACMFORMATCHOOSE structure.

fdwStyle

Optional style flags for the acmFormatChoose function. This member must be initialized to a valid combination of the following flags before an application calls the acmFormatChoose function:

ACMFORMATCHOOSE_STYLEF_CONTEXTHELP

Context-sensitive help will be available in the dialog box. To use this feature, an application must register the ACMHELPMSGCONTEXTMENU and ACMHELPMSGCONTEXTHELP constants, using the RegisterWindowMessage function. When the user invokes help, the registered message will be posted to the owning window. The message will contain the wParam and lParam parameters from the original WM_CONTEXTMENU or WM_CONTEXTHELP message.

ACMFORMATCHOOSE_STYLEF_ENABLEHOOK

Enables the hook function pointed to by the pfnHook member. An application can use hook functions for a variety of customizations, including answering the MM_ACM_FORMATCHOOSE message.

ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATE

Causes the ACM to create the dialog box template identified by hInstance and pszTemplateName.

ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATEHANDLE

The hInstance member identifies a data block that contains a preloaded dialog box template. If this flag is specified, the ACM ignores the pszTemplateName member.

ACMFORMATCHOOSE_STYLEF_INITTOWFXSTRUCT

The buffer pointed to by pwfx contains a valid WAVEFORMATEX structure that the dialog box will use as the initial selection.

ACMFORMATCHOOSE_STYLEF_SHOWHELP

A help button will appear in the dialog box. To use a custom Help file, an application must register the ACMHELPMSGSTRING constant with the RegisterWindowMessage function. When the user presses the help button, the registered message will be posted to the owner.

hwndOwner

Handle of the window that owns the dialog box. This member can be any valid window handle, or NULL if the dialog box has no owner. This member must be initialized before calling the acmFormatChoose function.

pwfx

Address of a WAVEFORMATEX structure. If the ACMFORMATCHOOSE_STYLEF_INITTOWFXSTRUCT flag is specified in the fdwStyle member, this structure must be initialized to a valid format. When the acmFormatChoose function returns, this buffer contains the selected format. If the user cancels the dialog box, no changes will be made to this buffer.

cbwfx

Size, in bytes, of the buffer pointed to by pwfx. If the buffer is too small to contain the format information, the acmFormatChoose function returns ACMERR_NOTPOSSIBLE. Also, the ACM copies the required size into this member. An application can use the acmMetrics and acmFormatTagDetails functions to determine the largest size required for this buffer.

pszTitle

Address of a string to be placed in the title bar of the dialog box. If this member is NULL, the ACM uses the default title (that is, “Sound Selection”).

szFormatTag

Buffer containing a null-terminated string describing the format tag of the format selection when the acmFormatChoose function returns. This string is equivalent to the szFormatTag member of the ACMFORMATTAGDETAILS structure returned by the acmFormatTagDetails function. If the user cancels the dialog box, this member will contain a null-terminated string.

szFormat

Buffer containing a null-terminated string describing the format attributes of the format selection when the acmFormatChoose function returns. This string is equivalent to the szFormat member of the ACMFORMATDETAILS structure returned by the acmFormatDetails function. If the user cancels the dialog box, this member will contain a null-terminated string.

pszName

Address of a string for a user-defined format name. If this is a non-null-terminated string, the ACM will attempt to match the name with a previously saved user-defined format name. If a match is found, the dialog box is initialized to that format. If a match is not found or this member is a null-terminated string, this member is ignored on input. When the acmFormatChoose function returns, this buffer contains a null-terminated string describing the user-defined format. If the format name is untitled (that is, the user has not given a name for the format), this member will be a null-terminated string on return. If the user cancels the dialog box, no changes will be made to this buffer.

If the ACMFORMATCHOOSE_STYLEF_INITTOWFXSTRUCT flag is specified in the fdwStyle member, the pszName member is ignored for input.

cchName

Size, in characters, of the buffer identified by the pszName member. This buffer should be at least 128 characters long. If the pszName member is NULL, this member is ignored.

fdwEnum

Optional flags for restricting the type of formats listed in the dialog box. These flags are identical to the fdwEnum flags for the acmFormatEnum function. If pwfxEnum is NULL, this member should be zero. The following values are defined:

ACM_FORMATENUMF_CONVERT

The WAVEFORMATEX structure pointed to by the pwfxEnum member is valid. The enumerator will enumerate only destination formats that can be converted from the given pwfxEnum format.

ACM_FORMATENUMF_HARDWARE

The enumerator should enumerate only formats that are supported in hardware by one or more of the installed waveform-audio devices. This flag provides a way for an application to choose only formats native to an installed waveform-audio device.

ACM_FORMATENUMF_INPUT

The enumerator should enumerate only formats that are supported for input (recording).

ACM_FORMATENUMF_NCHANNELS

The nChannels member of the WAVEFORMATEX structure pointed to by the pwfxEnum member is valid. The enumerator will enumerate only a format that conforms to this attribute.

ACM_FORMATENUMF_NSAMPLESPERSEC

The nSamplesPerSec member of the WAVEFORMATEX structure pointed to by the pwfxEnum member is valid. The enumerator will enumerate only a format that conforms to this attribute.

ACM_FORMATENUMF_OUTPUT

The enumerator should enumerate only formats that are supported for output (playback).

ACM_FORMATENUMF_SUGGEST

The WAVEFORMATEX structure pointed to by the pwfxEnum member is valid. The enumerator will enumerate all suggested destination formats for the given pwfxEnum format.

ACM_FORMATENUMF_WBITSPERSAMPLE

The wBitsPerSample member of the WAVEFORMATEX structure pointed to by the pwfxEnum member is valid. The enumerator will enumerate only a format that conforms to this attribute.

ACM_FORMATENUMF_WFORMATTAG

The wFormatTag member of the WAVEFORMATEX structure pointed to by the pwfxEnum member is valid. The enumerator will enumerate only a format that conforms to this attribute.

pwfxEnum

Address of a WAVEFORMATEX structure that will be used to restrict the formats listed in the dialog box. The fdwEnum member defines the members of the structure pointed to by pwfxEnum that should be used for the enumeration restrictions. If no special restrictions are desired, this member can be NULL. For other requirements associated with the pwfxEnum member, see the description for the acmFormatEnum function.

hInstance

Handle of a data block that contains a dialog box template specified by the pszTemplateName member. This member is used only if the fdwStyle member specifies the ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATE or ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATEHANDLE flag; otherwise, this member should be NULL on input.

pszTemplateName

Address of a null-terminated string that specifies the name of the resource file for the dialog box template that is to be substituted for the dialog box template in the ACM. An application can use the MAKEINTRESOURCE macro for numbered dialog box resources. This member is used only if the fdwStyle member specifies the ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATE flag; otherwise, this member should be NULL on input.

lCustData

Application-defined data that the ACM passes to the hook function identified by the pfnHook member. The system passes the data in the lParam parameter of the WM_INITDIALOG message.

pfnHook

Address of a hook function that processes messages intended for the dialog box. An application must specify the ACMFORMATCHOOSE_STYLEF_ENABLEHOOK flag in the fdwStyle member to enable the hook; otherwise, this member should be NULL. The hook function should return FALSE to pass a message to the standard dialog box procedure or TRUE to discard the message.

See Also

acmFormatChoose, acmFormatDetails, ACMFORMATDETAILS, acmFormatEnum, acmFormatTagDetails, ACMFORMATTAGDETAILS, acmMetrics, MAKEINTRESOURCE, MM_ACM_FORMATCHOOSE, RegisterWindowMessage, WAVEFORMATEX, WM_INITDIALOG


ACMFORMATDETAILS

The ACMFORMATDETAILS structure details a waveform-audio format for a specific format tag for an ACM driver.

typedef struct {

    DWORD          cbStruct;

    DWORD          dwFormatIndex;

    DWORD          dwFormatTag;

    DWORD          fdwSupport;

    LPWAVEFORMATEX pwfx;

    DWORD          cbwfx;

    char szFormat[ACMFORMATDETAILS_FORMAT_CHARS];

} ACMFORMATDETAILS;

Members

cbStruct

Size, in bytes, of the ACMFORMATDETAILS structure. This member must be initialized before an application calls the acmFormatDetails or acmFormatEnum function. The size specified by this member must be large enough to contain the base ACMFORMATDETAILS structure. When the acmFormatDetails function returns, this member contains the actual size of the information returned. The returned information will never exceed the requested size.

dwFormatIndex

Index of the format to retrieve details for. The index ranges from zero to one less than the number of standard formats supported by an ACM driver for a format tag. The number of standard formats supported by a driver for a format tag is contained in the cStandardFormats member of the ACMFORMATTAGDETAILS structure. The dwFormatIndex member is used only when an application queries standard format details about a driver by index; otherwise, this member should be zero. Also, this member will be set to zero by the ACM when an application queries for details on a format; in other words, this member is used only for input and is never returned by the ACM or an ACM driver.

dwFormatTag

Waveform-audio format tag that the ACMFORMATDETAILS structure describes. This member is used for input for the ACM_FORMATDETAILSF_INDEX query flag. For the ACM_FORMATDETAILSF_FORMAT query flag, this member must be initialized to the same format tag as the pwfx member specifies. If a call to the acmFormatDetails function is successful, this member is always returned. This member should be set to WAVE_FORMAT_UNKNOWN for all other query flags.

fdwSupport

Driver-support flags specific to the specified format. These flags are identical to the fdwSupport flags of the ACMDRIVERDETAILS structure. This member can be a combination of the following values and indicates which operations the driver supports for the format tag:

ACMDRIVERDETAILS_SUPPORTF_ASYNC

Driver supports asynchronous conversions with the specified format tag.

ACMDRIVERDETAILS_SUPPORTF_CODEC

Driver supports conversion between two different format tags for the specified format. For example, if a driver supports compression from WAVE_FORMAT_PCM to WAVE_FORMAT_ADPCM with the specified format, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_CONVERTER

Driver supports conversion between two different formats of the same format tag while using the specified format. For example, if a driver supports resampling of WAVE_FORMAT_PCM to the specified format, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_FILTER

Driver supports a filter (which modifies data without changing any format attributes) with the specified format. For example, if a driver supports volume or echo operations on WAVE_FORMAT_PCM, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_HARDWARE

Driver supports hardware input and/or output of the specified format through a waveform-audio device. An application should use acmMetrics with the ACM_METRIC_HARDWARE_WAVE_INPUT and ACM_METRIC_HARDWARE_WAVE_OUTPUT metric indexes to get the waveform-audio device identifiers associated with the supporting ACM driver.

pwfx

Address of a WAVEFORMATEX structure that will receive the format details. This structure requires no initialization by the application unless the ACM_FORMATDETAILSF_FORMAT flag is specified in the acmFormatDetails function. In this case, the wFormatTag member of the WAVEFORMATEX structure must be equal to the dwFormatTag of the ACMFORMATDETAILS structure.

cbwfx

Size, in bytes, available for pwfx to receive the format details. The acmMetrics and acmFormatTagDetails functions can be used to determine the maximum size required for any format available for the specified driver (or for all installed ACM drivers).

szFormat

String that describes the format for the dwFormatTag type. If the acmFormatDetails function is successful, this string is always returned.

See Also

ACMDRIVERDETAILS, acmFormatDetails, acmFormatEnum, acmFormatTagDetails, ACMFORMATTAGDETAILS, acmMetrics, WAVEFORMATEX


ACMFORMATTAGDETAILS

The ACMFORMATTAGDETAILS structure details a waveform-audio format tag for an ACM driver.

typedef struct {

    DWORD cbStruct;

    DWORD dwFormatTagIndex;

    DWORD dwFormatTag;

    DWORD cbFormatSize;

    DWORD fdwSupport;

    DWORD cStandardFormats;

    char szFormatTag[ACMFORMATTAGDETAILS_FORMATTAG_CHARS];

} ACMFORMATTAGDETAILS;

Members

cbStruct

Size, in bytes, of the ACMFORMATTAGDETAILS structure. This member must be initialized before an application calls the acmFormatTagDetails or acmFormatTagEnum function. The size specified by this member must be large enough to contain the base ACMFORMATTAGDETAILS structure. When the acmFormatTagDetails function returns, this member contains the actual size of the information returned. The returned information will never exceed the requested size.

dwFormatTagIndex

Index of the format tag for which details will be retrieved. The index ranges from zero to one less than the number of format tags supported by an ACM driver. The number of format tags supported by a driver is contained in the cFormatTags member of the ACMDRIVERDETAILS structure. The dwFormatTagIndex member is used only when querying format tag details on a driver by index; otherwise, this member should be zero.

dwFormatTag

Waveform-audio format tag that the ACMFORMATTAGDETAILS structure describes. This member is used for input for the ACM_FORMATTAGDETAILSF_FORMATTAG and ACM_FORMATTAGDETAILSF_LARGESTSIZE query flags. If the acmFormatTagDetails function is successful, this member is always returned. This member should be set to WAVE_FORMAT_UNKNOWN for all other query flags.

cbFormatSize

Largest total size, in bytes, of a waveform-audio format of the dwFormatTag type. For example, this member will be 16 for WAVE_FORMAT_PCM and 50 for WAVE_FORMAT_ADPCM.

fdwSupport

Driver-support flags specific to the format tag. These flags are identical to the fdwSupport flags of the ACMDRIVERDETAILS structure. This member may be some combination of the following values and refer to what operations the driver supports with the format tag:

ACMDRIVERDETAILS_SUPPORTF_ASYNC

Driver supports asynchronous conversions with the specified format tag.

ACMDRIVERDETAILS_SUPPORTF_CODEC

Driver supports conversion between two different format tags where one of the tags is the specified format tag. For example, if a driver supports compression from WAVE_FORMAT_PCM to WAVE_FORMAT_ADPCM, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_CONVERTER

Driver supports conversion between two different formats of the specified format tag. For example, if a driver supports resampling of WAVE_FORMAT_PCM, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_FILTER

Driver supports a filter (modification of the data without changing any of the format attributes). For example, if a driver supports volume or echo operations on the specified format tag, this flag is set.

ACMDRIVERDETAILS_SUPPORTF_HARDWARE

Driver supports hardware input, output, or both of the specified format tag through a waveform-audio device. An application should use the acmMetrics function with the ACM_METRIC_HARDWARE_WAVE_INPUT and ACM_METRIC_HARDWARE_WAVE_OUTPUT metric indexes to get the waveform-audio device identifiers associated with the supporting ACM driver.

cStandardFormats

Number of standard formats of the dwFormatTag type; that is, the combination of all sample rates, bits per sample, channels, and so on. This value can specify all formats supported by the driver, but not necessarily.

szFormatTag

String that describes the dwFormatTag type. If the acmFormatTagDetails function is successful, this string is always returned.

See Also

ACMDRIVERDETAILS, acmFormatTagDetails, acmFormatTagEnum, acmMetrics


ACMSTREAMHEADER

The ACMSTREAMHEADER structure defines the header used to identify an ACM conversion source and destination buffer pair for a conversion stream.

typedef struct {

    DWORD  cbStruct;

    DWORD  fdwStatus;

    DWORD  dwUser;

    LPBYTE pbSrc;

    DWORD  cbSrcLength;

    DWORD  cbSrcLengthUsed;

    DWORD  dwSrcUser;

    LPBYTE pbDst;

    DWORD  cbDstLength;

    DWORD  cbDstLengthUsed;

    DWORD  dwDstUser;

    DWORD  dwReservedDriver[10];

} ACMSTREAMHEADER;

Members

cbStruct

Size, in bytes, of the ACMSTREAMHEADER structure. This member must be initialized before the application calls any ACM stream functions using this structure. The size specified in this member must be large enough to contain the base ACMSTREAMHEADER structure.

fdwStatus

Flags giving information about the conversion buffers. This member must be initialized to zero before the application calls the acmStreamPrepareHeader function and should not be modified by the application while the stream header remains prepared.

ACMSTREAMHEADER_STATUSF_DONE

Set by the ACM or driver to indicate that it is finished with the conversion and is returning the buffers to the application.

ACMSTREAMHEADER_STATUSF_INQUEUE

Set by the ACM or driver to indicate that the buffers are queued for conversion.

ACMSTREAMHEADER_STATUSF_PREPARED

Set by the ACM to indicate that the buffers have been prepared by using the acmStreamPrepareHeader function.

dwUser

User data. This can be any instance data specified by the application.

pbSrc

Address of the source buffer. This pointer must always refer to the same location while the stream header remains prepared. If an application needs to change the source location, it must unprepare the header and reprepare it with the alternate location.

cbSrcLength

Length, in bytes, of the source buffer pointed to by pbSrc. When the header is prepared, this member must specify the maximum size that will be used in the source buffer. Conversions can be performed on source lengths less than or equal to the original prepared size. However, this member must be reset to the original size when an application unprepares the header.

cbSrcLengthUsed

Amount of data, in bytes, used for the conversion. This member is not valid until the conversion is complete. This value can be less than or equal to cbSrcLength. An application must use the cbSrcLengthUsed member when advancing to the next piece of source data for the conversion stream.

dwSrcUser

User data. This can be any instance data specified by the application.

pbDst

Address of the destination buffer. This pointer must always refer to the same location while the stream header remains prepared. If an application needs to change the destination location, it must unprepare the header and reprepare it with the alternate location.

cbDstLength

Length, in bytes, of the destination buffer pointed to by pbDst. When the header is prepared, this member must specify the maximum size that will be used in the destination buffer.

cbDstLengthUsed

Amount of data, in bytes, returned by a conversion. This member is not valid until the conversion is complete. This value can be less than or equal to cbDstLength. An application must use the cbDstLengthUsed member when advancing to the next destination location for the conversion stream.

dwDstUser

User data. This can be any instance data specified by the application.

dwReservedDriver

Reserved; do not use. This member requires no initialization by the application and should never be modified while the header remains prepared.

Remarks

Before an ACMSTREAMHEADER structure can be used for a conversion, it must be prepared by using the acmStreamPrepareHeader function. When an application is finished with an ACMSTREAMHEADER structure, it must call the acmStreamUnprepareHeader function before freeing the source and destination buffers.

See Also

acmStreamPrepareHeader, acmStreamUnprepareHeader


AUXCAPS

The AUXCAPS structure describes the capabilities of an auxiliary output device.

typedef struct {

    WORD      wMid;

    WORD      wPid;

    MMVERSION vDriverVersion;

    CHAR      szPname[MAXPNAMELEN];

    WORD      wTechnology;

    WORD      wReserved1;

    DWORD     dwSupport;

} AUXCAPS;

Members

wMid

Manufacturer identifier for the device driver for the auxiliary audio device. Manufacturer identifiers are defined in Manufacturer and Product Identifiers.

wPid

Product identifier for the auxiliary audio device. Currently, no product identifiers are defined for auxiliary audio devices.

vDriverVersion

Version number of the device driver for the auxiliary audio device.  The high-order byte is the major version number, and the low-order byte is the minor version number.

szPname

Product name in a null-terminated string.

wTechnology

Type of the auxiliary audio output:

AUXCAPS_AUXIN

Audio output from auxiliary input jacks.

AUXCAPS_CDAUDIO

Audio output from an internal CD-ROM drive.

wReserved1

Padding.

dwSupport

Describes optional functionality supported by the auxiliary audio device.

AUXCAPS_LRVOLUME

Supports separate left and right volume control.

AUXCAPS_VOLUME

Supports volume control.

If a device supports volume changes, the AUXCAPS_VOLUME flag will be set. If a device supports separate volume changes on the left and right channels, both AUXCAPS_VOLUME and the AUXCAPS_LRVOLUME will be set.


AVICOMPRESSOPTIONS

The AVICOMPRESSOPTIONS structure contains information about a stream and how it is compressed and saved. This structure passes data to the AVIMakeCompressedStream function (or the AVISave function, which uses AVIMakeCompressedStream).

typedef struct {

    DWORD  fccType;

    DWORD  fccHandler;

    DWORD  dwKeyFrameEvery;

    DWORD  dwQuality;

    DWORD  dwBytesPerSecond;

    DWORD  dwFlags;

    LPVOID lpFormat;

    DWORD  cbFormat;

    LPVOID lpParms;

    DWORD  cbParms;

    DWORD  dwInterleaveEvery;

} AVICOMPRESSOPTIONS;

Members

fccType

Four-character code indicating the stream type. The following constants have been defined for the data commonly found in AVI streams:

streamtypeAUDIO	Indicates an audio stream.
streamtypeMIDI	Indicates a MIDI stream.
streamtypeTEXT	Indicates a text stream.
streamtypeVIDEO	Indicates a video stream.
fccHandler

Four-character code for the compressor handler that will compress this video stream when it is saved (for example, mmioFOURCC('M','S','V','C')). This member is not used for audio streams.

dwKeyFrameEvery

Maximum period between video key frames. This member is used only if the AVICOMPRESSF_KEYFRAMES flag is set; otherwise every video frame is a key frame.

dwQuality

Quality value passed to a video compressor. This member is not used for an audio compressor.

dwBytesPerSecond

Video compressor data rate. This member is used only if the AVICOMPRESSF_DATARATE flag is set.

dwFlags

Flags used for compression. The following values are defined:

AVICOMPRESSF_DATARATE

Compresses this video stream using the data rate specified in dwBytesPerSecond.

AVICOMPRESSF_INTERLEAVE

Interleaves this stream every dwInterleaveEvery frames with respect to the first stream.

AVICOMPRESSF_KEYFRAMES

Saves this video stream with key frames at least every dwKeyFrameEvery frames. By default, every frame will be a key frame.

AVICOMPRESSF_VALID

Uses the data in this structure to set the default compression values for AVISaveOptions. If an empty structure is passed and this flag is not set, some defaults will be chosen.

lpFormat

Address of a structure defining the data format. For an audio stream, this is an LPWAVEFORMAT structure.

cbFormat

Size, in bytes, of the data referenced by lpFormat.

lpParms

Video-compressor-specific data; used internally.

cbParms

Size, in bytes, of the data referenced by lpParms

dwInterleaveEvery

Interleave factor for interspersing stream data with data from the first stream. Used only if the AVICOMPRESSF_INTERLEAVE flag is set.

See Also

AVIMakeCompressedStream, AVISave, AVISaveOptions, mmioFOURCC


AVIFILEINFO

The AVIFILEINFO structure contains global information for an entire AVI file.

typedef struct {

    DWORD dwMaxBytesPerSec;

    DWORD dwFlags;

    DWORD dwCaps;

    DWORD dwStreams;

    DWORD dwSuggestedBufferSize;

    DWORD dwWidth;

    DWORD dwHeight;

    DWORD dwScale;

    DWORD dwRate;

    DWORD dwLength;

    DWORD dwEditCount;

    char  szFileType[64];

} AVIFILEINFO;

Members

dwMaxBytesPerSec

Approximate maximum data rate of the AVI file.

dwFlags

Applicable flags. The following flags are defined:

AVIFILEINFO_HASINDEX

The AVI file has an index at the end of the file. For good performance, all AVI files should contain an index.

AVIFILEINFO_MUSTUSEINDEX

The file index contains the playback order for the chunks in the file. Use the index rather than the physical ordering of the chunks when playing back the data. This could be used for creating a list of frames for editing.

AVIFILEINFO_ISINTERLEAVED

The AVI file is interleaved.

AVIFILEINFO_WASCAPTUREFILE

The AVI file is a specially allocated file used for capturing real-time video. Applications should warn the user before writing over a file with this flag set because the user probably defragmented this file.

AVIFILEINFO_COPYRIGHTED

The AVI file contains copyrighted data and software. When this flag is used, software should not permit the data to be duplicated.

dwCaps

Capability flags. The following flags are defined:

AVIFILECAPS_CANREAD

An application can open the AVI file with with the read privilege.

AVIFILECAPS_CANWRITE

An application can open the AVI file with the write privilege.

AVIFILECAPS_ALLKEYFRAMES

Every frame in the AVI file is a key frame.

AVIFILECAPS_NOCOMPRESSION

The AVI file does not use a compression method.

dwStreams

Number of streams in the file. For example, a file with audio and video has at least two streams.

dwSuggestedBufferSize

Suggested buffer size, in bytes, for reading the file. Generally, this size should be large enough to contain the largest chunk in the file. For an interleaved file, this size should be large enough to read an entire record, not just a chunk.

If the buffer size is too small or is set to zero, the playback software will have to reallocate memory during playback, reducing performance.

dwWidth

Width, in pixels, of the AVI file.

dwHeight

Height, in pixels, of the AVI file.

dwScale

Time scale applicable for the entire file. Dividing dwRate by dwScale gives the number of samples per second.

Any stream can define its own time scale to supersede the file time scale.

dwLength

Length of the AVI file. The units are defined by dwRate and dwScale.

dwEditCount

Number of streams that have been added to or deleted from the AVI file.

szFileType

Null-terminated string containing descriptive information for the file type.


AVISTREAMINFO

The AVISTREAMINFO structure contains information for a single stream.

typedef struct {

    DWORD fccType;

    DWORD fccHandler;

    DWORD dwFlags;

    DWORD dwCaps;

    WORD  wPriority;

    WORD  wLanguage;

    DWORD dwScale;

    DWORD dwRate;

    DWORD dwStart;

    DWORD dwLength;

    DWORD dwInitialFrames;

    DWORD dwSuggestedBufferSize;

    DWORD dwQuality;

    DWORD dwSampleSize;

    RECT  rcFrame;

    DWORD dwEditCount;

    DWORD dwFormatChangeCount;

    char  szName[64];

} AVISTREAMINFO;

Members

fccType

Four-character code indicating the stream type. The following constants have been defined for the data commonly found in AVI streams:

streamtypeAUDIO	Indicates an audio stream.
streamtypeMIDI	Indicates a MIDI stream.
streamtypeTEXT	Indicates a text stream.
streamtypeVIDEO	Indicates a video stream.
fccHandler

Four-character code of the compressor handler that will compress this video stream when it is saved (for example, mmioFOURCC('M','S','V','C')). This member is not used for audio streams.

dwFlags

Applicable flags for the stream. The bits in the high-order word of these flags are specific to the type of data contained in the stream. The following flags are defined:

AVISTREAMINFO_DISABLED

Indicates this stream should be rendered when explicitly enabled by the user.

AVISTREAMINFO_FORMATCHANGES

Indicates this video stream contains palette changes. This flag warns the playback software that it will need to animate the palette.

dwCaps

Capability flags; currently unused.

wPriority

Priority of the stream.

wLanguage

Language of the stream.

dwScale

Time scale applicable for the stream. Dividing dwRate by dwScale gives the playback rate in number of samples per second.

For video streams, this rate should be the frame rate. For audio streams, this rate should correspond to the audio block size (the nBlockAlign member of the WAVEFORMAT or PCMWAVEFORMAT structure), which for PCM (Pulse Code Modulation) audio reduces to the sample rate.

dwRate

See dwScale.

dwStart

Sample number of the first frame of the AVI file. The units are defined by dwRate and dwScale. Normally, this is zero, but it can specify a delay time for a stream that does not start concurrently with the file.

The 1.0 release of the AVI tools does not support a nonzero starting time.

dwLength

Length of this stream. The units are defined by dwRate and dwScale.

dwInitialFrames

Audio skew. This member specifies how much to skew the audio data ahead of the video frames in interleaved files. Typically, this is about 0.75 seconds.

dwSuggestedBufferSize

Recommended buffer size, in bytes, for the stream. Typically, this member contains a value corresponding to the largest chunk in the stream. Using the correct buffer size makes playback more efficient. Use zero if you do not know the correct buffer size.

dwQuality

Quality indicator of the video data in the stream. Quality is represented as a number between 0 and 10,000. For compressed data, this typically represents the value of the quality parameter passed to the compression software. If set to  − 1, drivers use the default quality value.

dwSampleSize

Size, in bytes, of a single data sample. If the value of this member is zero, the samples can vary in size and each data sample (such as a video frame) must be in a separate chunk. A nonzero value indicates that multiple samples of data can be grouped into a single chunk within the file.

For video streams, this number is typically zero, although it can be nonzero if all video frames are the same size. For audio streams, this number should be the same as the nBlockAlign member of the WAVEFORMAT or WAVEFORMATEX structure describing the audio.

rcFrame

Dimensions of the video destination rectangle. The values represent the coordinates of upper left corner, the height, and the width of the rectangle.

dwEditCount

Number of times the stream has been edited. The stream handler maintains this count.

dwFormatChangeCount

Number of times the stream format has changed. The stream handler maintains this count.

szName

Null-terminated string containing a description of the stream.

See Also

mmioFOURCC, PCMWAVEFORMAT, WAVEFORMAT, WAVEFORMATEX


CAPDRIVERCAPS

The CAPDRIVERCAPS structure defines the capabilities of the capture driver.

An application should use the WM_CAP_DRIVER_GET_CAPS message or capDriverGetCaps macro to place a copy of the driver capabilities in a CAPDRIVERCAPS structure whenever the application connects a capture window to a capture driver.

typedef struct {

    UINT   wDeviceIndex;

    BOOL   fHasOverlay;

    BOOL   fHasDlgVideoSource;

    BOOL   fHasDlgVideoFormat;

    BOOL   fHasDlgVideoDisplay;

    BOOL   fCaptureInitialized;

    BOOL   fDriverSuppliesPalettes;

    HANDLE hVideoIn;

    HANDLE hVideoOut;

    HANDLE hVideoExtIn;

    HANDLE hVideoExtOut;

} CAPDRIVERCAPS;

Members

wDeviceIndex

Index of the capture driver. An index value can range from 0 to 9.

fHasOverlay

Video-overlay flag. The value of this member is TRUE if the device supports video overlay.

fHasDlgVideoSource

Video source dialog flag. The value of this member is TRUE if the device supports a dialog box for selecting and controlling the video source.

fHasDlgVideoFormat

Video format dialog flag. The value of this member is TRUE if the device supports a dialog box for selecting the video format.

fHasDlgVideoDisplay

Video display dialog flag. The value of this member is TRUE if the device supports a dialog box for controlling the redisplay of video from the capture frame buffer.

fCaptureInitialized

Capture initialization flag. The value of this member is TRUE if a capture device has been successfully connected.

fDriverSuppliesPalettes

Driver palette flag. The value of this member is TRUE if the driver can create palettes.

hVideoIn

Not used in Win32 applications.

hVideoOut

Not used in Win32 applications.

hVideoExtIn

Not used in Win32 applications.

hVideoExtOut

Not used in Win32 applications.


CAPINFOCHUNK

The CAPINFOCHUNK structure contains parameters that can be used to define an information chunk within an AVI capture file. The WM_CAP_FILE_SET_INFOCHUNK message or capSetInfoChunk macro is used to send a CAPINFOCHUNK structure to a capture window.

typedef struct {

    FOURCC fccInfoID;

    LPVOID lpData;

    LONG   cbData;

} CAPINFOCHUNK;

Members

fccInfoID

Four-character code that identifies the representation of the chunk data. If this value is NULL and lpData is NULL, all accumulated information chunks are deleted.

lpData

Address of the data. If this value is NULL, all fccInfoID information chunks are deleted.

cbData

Size, in bytes, of the data pointed to by lpData. If lpData specifies a
null-terminated string, use the string length incremented by one to save the NULL with the string.

See Also

WM_CAP_FILE_SET_INFOCHUNK


CAPSTATUS

The CAPSTATUS structure defines the current state of the capture window.

typedef struct {

    UINT     uiImageWidth;

    UINT     uiImageHeight;

    BOOL     fLiveWindow;

    BOOL     fOverlayWindow;

    BOOL     fScale;

    POINT    ptScroll;

    BOOL     fUsingDefaultPalette;

    BOOL     fAudioHardware;

    BOOL     fCapFileExists;

    DWORD    dwCurrentVideoFrame;

    DWORD    dwCurrentVideoFramesDropped;

    DWORD    dwCurrentWaveSamples;

    DWORD    dwCurrentTimeElapsedMS;

    HPALETTE hPalCurrent;

    BOOL     fCapturingNow;

    DWORD    dwReturn;

    UINT     wNumVideoAllocated;

    UINT     wNumAudioAllocated;

} CAPSTATUS;

Members

uiImageWidth

Image width, in pixels.

uiImageHeight

Image height, in pixels

fLiveWindow

Live window flag. The value of this member is TRUE if the window is displaying video using the preview method.

fOverlayWindow

Overlay window flag. The value of this member is TRUE if the window is displaying video using hardware overlay.

fScale

Input scaling flag. The value of this member is TRUE if the window is scaling the input video to the client area when displaying video using preview. This parameter has no effect when displaying video using overlay.

ptScroll

The x- and y-offset of the pixel displayed in the upper left corner of the client area of the window.

fUsingDefaultPalette

Default palette flag. The value of this member is TRUE if the capture driver is using its default palette.

fAudioHardware

Audio hardware flag. The value of this member is TRUE if the system has waveform-audio hardware installed.

fCapFileExists

Capture file flag. The value of this member is TRUE if a valid capture file has been generated.

dwCurrentVideoFrame

Number of frames processed during the current (or most recent) streaming capture. This count includes dropped frames.

dwCurrentVideoFramesDropped

Number of frames dropped during the current (or most recent) streaming capture. Dropped frames occur when the capture rate exceeds the rate at which frames can be saved to file. In this case, the capture driver has no buffers available for storing data. Dropping frames does not affect synchronization because the previous frame is displayed in place of the dropped frame.

dwCurrentWaveSamples

Number of waveform-audio samples processed during the current (or most recent) streaming capture.

dwCurrentTimeElapsedMS

Time, in milliseconds, since the start of the current (or most recent) streaming capture.

hPalCurrent

Handle of current palette.

fCapturingNow

Capturing flag. The value of this member is TRUE when capturing is in progress.

dwReturn

Error return values. Use this member if your application does not support an error callback function.

wNumVideoAllocated

Number of video buffers allocated. This value might be less than the number specified in the wNumVideoRequested member of the CAPTUREPARMS structure.

wNumAudioAllocated

Number of audio buffers allocated. This value might be less than the number specified in the wNumAudioRequested member of the CAPTUREPARMS structure.

Remarks

Because the state of a capture window changes in response to various messages, an application should update the information in this structure whenever it needs to enable menu items, determine the actual state of the capture window, or call the video format dialog box. If the application yields during streaming capture, this structure returns the progress of the capture in the dwCurrentVideoFrame, dwCurrentVideoFramesDropped, dwCurrentWaveSamples, and dwCurrentTimeElapsedMS members. Use the WM_CAP_GET_STATUS message or capGetStatus macro to update the contents of this structure.

See Also

CAPTUREPARMS, WM_CAP_GET_STATUS


CAPTUREPARMS

The CAPTUREPARMS structure contains parameters that control the streaming video capture process. This structure is used to get and set parameters that affect the capture rate, the number of buffers to use while capturing, and how capture is terminated.

typedef struct {

    DWORD dwRequestMicroSecPerFrame;

    BOOL  fMakeUserHitOKToCapture;

    UINT  wPercentDropForError;

    BOOL  fYield;

    DWORD dwIndexSize;

    UINT  wChunkGranularity;

    BOOL  fUsingDOSMemory;

    UINT  wNumVideoRequested;

    BOOL  fCaptureAudio;

    UINT  wNumAudioRequested;

    UINT  vKeyAbort;

    BOOL  fAbortLeftMouse;

    BOOL  fAbortRightMouse;

    BOOL  fLimitEnabled;

    UINT  wTimeLimit;

    BOOL  fMCIControl;

    BOOL  fStepMCIDevice;

    DWORD dwMCIStartTime;

    DWORD dwMCIStopTime;

    BOOL  fStepCaptureAt2x;

    UINT  wStepCaptureAverageFrames;

    DWORD dwAudioBufferSize;

    BOOL  fDisableWriteCache;

    UINT  AVStreamMaster;

} CAPTUREPARMS;

Members

dwRequestMicroSecPerFrame

Requested frame rate, in microseconds. The default value is 66667, which corresponds to 15 frames per second.

fMakeUserHitOKToCapture

User-initiated capture flag. If this member is TRUE, AVICap displays a dialog box prompting the user to initiate capture. The default value is FALSE.

wPercentDropForError

Maximum allowable percentage of dropped frames during capture. Values range from 0 to 100. The default value is 10.

fYield

Yield flag. If this member is TRUE, the capture window spawns a separate background thread to perform step and streaming capture. The default value is FALSE.

Applications that set this flag must handle potential reentry issues because the controls in the application are not disabled while capture is in progress.

dwIndexSize

Maximum number of index entries in an AVI file. Values range from 1800 to 324,000. If set to 0, a default value of 34,952 (32K frames plus a proportional number of audio buffers) is used.

Each video frame or buffer of waveform-audio data uses one index entry. The value of this entry establishes a limit for the number of frames or audio buffers that can be captured.

wChunkGranularity

Logical block size, in bytes, of an AVI file. The value 0 indicates the current sector size is used as the granularity.

fUsingDOSMemory

Not used in Win32 applications.

wNumVideoRequested

Maximum number of video buffers to allocate. The memory area to place the buffers is specified with fUsingDOSMemory. The actual number of buffers allocated might be lower if memory is unavailable.

fCaptureAudio

Capture audio flag. If this member is TRUE, audio is captured during streaming capture. This is the default value if audio hardware is installed.

wNumAudioRequested

Maximum number of audio buffers to allocate. The maximum number of buffers is 10.

vKeyAbort

Virtual keycode used to terminate streaming capture. The default value is VK_ESCAPE. You must call the RegisterHotKey function before specifying a keystroke that can abort a capture session.

You can combine keycodes that include CTRL and SHIFT keystrokes by using the logical OR operator with the keycodes for CTRL (0x8000) and SHIFT (0x4000).

fAbortLeftMouse

Abort flag for left mouse button. If this member is TRUE, streaming capture stops if the left mouse button is pressed. The default value is TRUE.

fAbortRightMouse

Abort flag for right mouse button. If this member is TRUE, streaming capture stops if the right mouse button is pressed. The default value is TRUE.

fLimitEnabled

Time limit enabled flag. If this member is TRUE, streaming capture stops after the number of seconds in wTimeLimit has elapsed. The default value is FALSE.

wTimeLimit

Time limit for capture, in seconds. This parameter is used only if fLimitEnabled is TRUE.

fMCIControl

MCI device capture flag. If this member is TRUE, AVICap controls an
MCI-compatible video source during streaming capture. MCI-compatible video sources include VCRs and laserdiscs.

fStepMCIDevice

MCI device step capture flag. If this member is TRUE, step capture using an MCI device as a video source is enabled. If it is FALSE, real-time capture using an MCI device is enabled. (If fMCIControl is FALSE, this member is ignored.)

dwMCIStartTime

Starting position, in milliseconds, of the MCI device for the capture sequence. (If fMCIControl is FALSE, this member is ignored.)

dwMCIStopTime

Stopping position, in milliseconds, of the MCI device for the capture sequence. When this position in the content is reached, capture ends and the MCI device stops. (If fMCIControl is FALSE, this member is ignored.)

fStepCaptureAt2x

Double-resolution step capture flag. If this member is TRUE, the capture hardware captures at twice the specified resolution. (The resolution for the height and width is doubled.)

Enable this option if the hardware does not support hardware-based decimation and you are capturing in the RGB format.

wStepCaptureAverageFrames

Number of times a frame is sampled when creating a frame based on the average sample. A typical value for the number of averages is 5.

dwAudioBufferSize

Audio buffer size. If the default value of zero is used, the size of each buffer will be the maximum of 0.5 seconds of audio or 10K bytes.

fDisableWriteCache

Not used in Win32 applications.

AVStreamMaster

Indicates whether the audio stream controls the clock when writing an AVI file. If this member is set to AVSTREAMMASTER_AUDIO, the audio stream is considered the master stream and the video stream duration is forced to match the audio duration. If this member is set to AVSTREAMMASTER_NONE, the durations of audio and video streams can differ.

Remarks

The WM_CAP_GET_SEQUENCE_SETUP message or capCaptureGetSetup macro is used to retrieve the current capture parameters. The WM_CAP_SET_SEQUENCE_SETUP message or capCaptureSetSetup macro is used to set the capture parameters.

The WM_CAP_GET_SEQUENCE_SETUP message or capCaptureGetSetup macro is used to retrieve the current capture parameters. The WM_CAP_SET_SEQUENCE_SETUP message or capCaptureSetSetup macro is used to set the capture parameters.

See Also

capCaptureGetSetup, capCaptureSetSetup, RegisterHotKey, WM_CAP_GET_SEQUENCE_SETUP, WM_CAP_SET_SEQUENCE_SETUP


COMPVARS

The COMPVARS structure describes compressor settings for functions such as ICCompressorChoose, ICSeqCompressFrame, and ICCompressorFree.

typedef struct {

    LONG         cbSize;

    DWORD        dwFlags;

    HIC          hic;

    DWORD        fccType;

    DWORD        fccHandler;

    LPBITMAPINFO lpbiIn;

    LPBITMAPINFO lpbiOut;

    LPVOID       lpBitsOut;

    LPVOID       lpBitsPrev;

    LONG         lFrame;

    LONG         lKey;

    LONG         lDataRate;

    LONG         lQ;

    LONG         lKeyCount;

    LPVOID       lpState;

    LONG         cbState;

} COMPVARS;

Members

cbSize

Size, in bytes, of this structure. This member must be set to validate the structure before calling any function using this structure.

dwFlags

Applicable flags. The following value is defined:

ICMF_COMPVARS_VALID

Data in this structure is valid and has been manually entered. Set this flag before you call any function if you fill this structure manually. Do not set this flag if you let ICCompressorChoose initialize this structure.

hic

Handle of the compressor to use. You can open a compressor and obtain a handle of it by using the ICOpen function. You can also choose a compressor by using ICCompressorChoose. ICCompressorChoose opens the chosen compressor and returns the handle of the compressor in this member. You can close the compressor by using ICCompressorFree.

fccType

Type of compressor used. Currently only ICTYPE_VIDEO (VIDC) is supported. This member can be set to zero.

fccHandler

Four-character code of the compressor. Specify NULL to indicate the data is not to be recompressed. Specify “DIB” to indicate the data is an uncompressed, full frame. You can use this member to specify which compressor is selected by default when the dialog box is displayed.

lpbiIn

Reserved; do not use.

lpbiOut

Address of a BITMAPINFO structure containing the image output format. You can specify a specific format to use or you can specify NULL to use the default compressor associated with the input format. You can also set the image output format by using ICCompressorChoose.

lpBitsOut

Reserved; do not use.

lpBitsPrev

Reserved; do not use.

lFrame

Reserved; do not use.

lKey

Key-frame rate. Specify an integer to indicate the frequency that key frames are to occur in the compressed sequence or zero to not use key frames. You can also let ICCompressorChoose set the key-frame rate selected in the dialog box. The ICSeqCompressFrameStart function uses the value of this member for making key frames.

lDataRate

Data rate, in kilobytes per second. ICCompressorChoose copies the selected data rate from the dialog box to this member.

lQ

Quality setting. Specify a quality setting of 1 to 10,000 or specify ICQUALITY_DEFAULT to use the default quality setting. You can also let ICCompressorChoose set the quality value selected in the dialog box. ICSeqCompressFrameStart uses the value of this member as its quality setting.

lKeyCount

Reserved; do not use.

lpState

Reserved; do not use.

cbState

Reserved; do not use.

Remarks

You can let ICCompressorChoose fill the contents of this structure or you can do it manually. If you manually fill the structure, you must provide information for the following members: cbSize, hic, lpbiOut, lKey, and lQ. Also, you must set the ICMF_COMPVARS_VALID flag in the dwFlags member.

See Also

BITMAPINFO, ICCompressorChoose, ICCompressorFree, ICSeqCompressFrame, ICSeqCompressFrameStart


DRAWDIBTIME

The DRAWDIBTIME structure contains elapsed timing information for performing a set of DrawDib operations. The DrawDibTime function resets the count and the elapsed time value for each operation each time it is called.

typedef struct {

    LONG timeCount;

    LONG timeDraw;

    LONG timeDecompress;

    LONG timeDither;

    LONG timeStretch;

    LONG timeBlt;

    LONG timeSetDIBits;

}   DRAWDIBTIME, *LPDRAWDIBTIME;

Members

timeCount

Number of times the following operations have been performed since DrawDibTime was last called:

•	Draw a bitmap on the screen.

•	Decompress a bitmap.

•	Dither a bitmap.

•	Stretch a bitmap.

•	Transfer bitmap data by using the BitBlt function.

•	Transfer bitmap data by using the SetDIBits function.

timeDraw

Time to draw bitmaps.

timeDecompress

Time to decompress bitmaps.

timeDither

Time to dither bitmaps.

timeStretch

Time to stretch bitmaps.

timeBlt

Time to transfer bitmaps by using the BitBlt function.

timeSetDIBits

Time to transfer bitmaps by using the SetDIBits function.

See Also

BitBlt, DrawDibTime, SetDIBits


ICCOMPRESS

The ICCOMPRESS structure contains compression parameters used with the ICM_COMPRESS message.

typedef struct {

    DWORD              dwFlags;

    LPBITMAPINFOHEADER lpbiOutput;

    LPVOID             lpOutput;

    LPBITMAPINFOHEADER lpbiInput;

    LPVOID             lpInput;

    LPDWORD            lpckid;

    LPDWORD            lpdwFlags;

    LONG               lFrameNum;

    DWORD              dwFrameSize;

    DWORD              dwQuality;

    LPBITMAPINFOHEADER lpbiPrev;

    LPVOID             lpPrev;

} ICCOMPRESS;

Members

dwFlags

Flags used for compression. The following value is defined:

ICCOMPRESS_KEYFRAME

Input data should be treated as a key frame.

lpbiOutput

Address of a BITMAPINFOHEADER structure containing the output (compressed) format. The biSizeImage member must contain the size of the compressed data.

lpOutput

Address of the buffer where the driver should write the compressed data.

lpbiInput

Address of a BITMAPINFOHEADER structure containing the input (uncompressed) format.

lpInput

Address of the buffer containing input data.

lpckid

Address to contain the chunk identifier for data in the AVI file. If the value of this member is not NULL, the driver should specify a two-character code for the chunk identifier corresponding to the chunk identifier used in the AVI file.

lpdwFlags

Address to contain flags for the AVI index. If the returned frame is a key frame, the driver should set the AVIIF_KEYFRAME flag.

lFrameNum

Number of the frame to compress.

dwFrameSize

Desired maximum size, in bytes, for compressing this frame. The size value is used for compression methods that can make tradeoffs between compressed image size and image quality. Specify zero for this member to use the default setting.

dwQuality

Quality setting.

lpbiPrev

Address of a BITMAPINFOHEADER structure containing the format of the previous frame, which is typically the same as the input format.

lpPrev

Address of the buffer containing input data of the previous frame.

Remarks

Drivers that perform temporal compression use data from the previous frame (found in the lpbiPrev and lpPrev members) to prune redundant data from the current frame.

See Also

BITMAPINFOHEADER, ICM_COMPRESS


ICCOMPRESSFRAMES

The ICCOMPRESSFRAMES structure contains compression parameters used with the ICM_COMPRESS_FRAMES_INFO message.

typedef struct {

    DWORD              dwFlags;

    LPBITMAPINFOHEADER lpbiOutput;

    LPARAM             lOutput;

    LPBITMAPINFOHEADER lpbiInput;

    LPARAM             lInput;

    LONG               lStartFrame;

    LONG               lFrameCount;

    LONG               lQuality;

    LONG               lDataRate;

    LONG               lKeyRate;

    DWORD              dwRate;

    DWORD              dwScale;

    DWORD              dwOverheadPerFrame;

    DWORD              dwReserved2;

    LONG (CALLBACK* GetData) (LPARAM lInput, LONG lFrame,
        LPVOID lpBits, LONG len);

    LONG (CALLBACK* PutData) (LPARAM lInput, LONG lFrame,
        LPVOID lpBits, LONG len);

} ICCOMPRESSFRAMES;

Members

dwFlags

Applicable flags. The following value is defined:

ICDECOMPRESSFRAMES_PADDING

Padding is used with the frame.

lpbiOutput

Address of a BITMAPINFOHEADER structure containing the output format.

lOutput

Reserved; do not use.

lpbiInput

Address of a BITMAPINFOHEADER structure containing the input format.

lInput

Reserved; do not use.

lStartFrame

Number of the first frame to compress.

lFrameCount

Number of frames to compress.

lQuality

Quality setting.

lDataRate

Maximum data rate, in bytes per second.

lKeyRate

Maximum number of frames between consecutive key frames.

dwRate

Compression rate in an integer format. To obtain the rate in frames per second, divide this value by the value in dwScale.

dwScale

Value used to scale dwRate to frames per second.

dwOverheadPerFrame

Reserved; do not use.

dwReserved2

Reserved; do not use.

GetData

Reserved; do not use.

PutData

Reserved; do not use.

See Also

BITMAPINFOHEADER, ICM_COMPRESS_FRAMES_INFO


ICDECOMPRESS

The ICDECOMPRESS structure contains decompression parameters used with the ICM_DECOMPRESS message.

typedef struct {

    DWORD              dwFlags;

    LPBITMAPINFOHEADER lpbiInput;

    LPVOID             lpInput;

    LPBITMAPINFOHEADER lpbiOutput;

    LPVOID             lpOutput;

    DWORD              ckid;

} ICDECOMPRESS;

Members

dwFlags

Applicable flags. The following values are defined:

ICDECOMPRESS_HURRYUP

Tries to decompress at a faster rate. When an application uses this flag, the driver should buffer the decompressed data but not draw the image.

ICDECOMPRESS_NOTKEYFRAME

Current frame is not a key frame.

ICDECOMPRESS_NULLFRAME

Current frame does not contain data and the decompressed image should be left the same.

ICDECOMPRESS_PREROLL

Current frame precedes the point in the movie where playback starts and, therefore, will not be drawn.

ICDECOMPRESS_UPDATE

Screen is being updated or refreshed.

lpbiInput

Address of a BITMAPINFOHEADER structure containing the input format.

lpInput

Address of a buffer containing the input data.

lpbiOutput

Address of a BITMAPINFOHEADER structure containing the output format.

lpOutput

Address of a buffer where the driver should write the decompressed image.

ckid

Chunk identifier from the AVI file.

See Also

BITMAPINFOHEADER, ICM_DECOMPRESS


ICDECOMPRESSEX

The ICDECOMPRESSEX structure contains decompression parameters used with the ICM_DECOMPRESSEX message

typedef struct {

    DWORD              dwFlags;

    LPBITMAPINFOHEADER lpbiSrc;

    LPVOID             lpSrc;

    LPBITMAPINFOHEADER lpbiDst;

    LPVOID             lpDst;

    int                xDst;

    int                yDst;

    int                dxDst;

    int                dyDst;

    int                xSrc;

    int                ySrc;

    int                dxSrc;

    int                dySrc;

} ICDECOMPRESSEX;

Members

dwFlags

Applicable flags. The following values are defined:

ICDECOMPRESS_HURRYUP

Tries to decompress at a faster rate. When an application uses this flag, the driver should buffer the decompressed data but not draw the image.

ICDECOMPRESS_NOTKEYFRAME

Current frame is not a key frame.

ICDECOMPRESS_NULLFRAME

Current frame does not contain data and the decompressed image should be left the same.

ICDECOMPRESS_PREROLL

Current frame precedes the point in the movie where playback starts and, therefore, will not be drawn.

ICDECOMPRESS_UPDATE

Screen is being updated or refreshed.

lpbiSrc

Address of a BITMAPINFOHEADER structure containing the input format.

lpSrc

Address of a buffer containing the input data.

lpbiDst

Address of a BITMAPINFOHEADER structure containing the output format.

lpDst

Address of a buffer where the driver should write the decompressed image.

xDst, yDst

The x- and y-coordinates of the destination rectangle within the DIB specified by lpbiDst.

dxDst, dyDst

Width and height of the destination rectangle.

xSrc, ySrc

The x- and y-coordinates of the source rectangle within the DIB specified by lpbiSrc.

dxSrc, dySrc

Width and height of the source rectangle.

See Also

BITMAPINFOHEADER, ICM_DECOMPRESSEX


ICDRAW

The ICDRAW structure contains parameters for drawing video data to the screen. This structure is used with the ICM_DRAW message.

typedef struct {

    DWORD  dwFlags;

    LPVOID lpFormat;

    LPVOID lpData;

    DWORD  cbData;

    LONG   lTime;

} ICDRAW;

Members

dwFlags

Flags from the AVI file index. The following values are defined:

ICDRAW_HURRYUP

Data is buffered and not drawn to the screen. Use this flag for fastest decompression.

ICDRAW_NOTKEYFRAME

Current frame is not a key frame.

ICDRAW_NULLFRAME

Current frame does not contain any data, and the previous frame should be redrawn.

ICDRAW_PREROLL

Current frame of video occurs before playback should start. For example, if playback will begin on frame 10, and frame 0 is the nearest previous key frame, frames 0 through 9 are sent to the driver with this flag set. The driver needs this data to display frame 10 properly.

ICDRAW_UPDATE

Updates the screen based on data previously received. In this case, lpData should be ignored.

lpFormat

Address of a structure containing the data format. For video streams, this is a BITMAPINFOHEADER structure.

lpData

Address of the data to render.

cbData

Number of data bytes to render.

lTime

Time, in samples, when this data should be drawn. For video data this is normally a frame number.

See Also

BITMAPINFOHEADER, ICM_DRAW


ICDRAWBEGIN

The ICDRAWBEGIN structure contains decompression parameters used with the ICM_DRAW_BEGIN message.

typedef struct {

    DWORD              dwFlags;

    HPALETTE           hpal;

    HWND               hwnd;

    HDC                hdc;

    int                xDst;

    int                yDst;

    int                dxDst;

    int                dyDst;

    LPBITMAPINFOHEADER lpbi;

    int                xSrc;

    int                ySrc;

    int                dxSrc;

    int                dySrc;

    DWORD              dwRate;

    DWORD              dwScale;

} ICDRAWBEGIN;

Members

dwFlags

Applicable flags. The following values are defined:

ICDRAW_ANIMATE

Application can animate the palette.

ICDRAW_BUFFER

Buffers this data off-screen; it will need to be updated.

ICDRAW_CONTINUE

Drawing is a continuation of the previous frame.

ICDRAW_FULLSCREEN

Draws the decompressed data on the full screen.

ICDRAW_HDC

Draws the decompressed data to a window or a DC.

ICDRAW_MEMORYDC

DC is off-screen.

ICDRAW_QUERY

Determines if the decompressor can handle the decompression. The driver does not actually decompress the data.

ICDRAW_RENDER

Renders but does not draw the data.

ICDRAW_UPDATING

Current frame is being updated rather than played.

hpal

Handle of the palette used for drawing.

hwnd

Handle of the window used for drawing.

hdc

Handle of the DC used for drawing. Specify NULL to use a DC associated with the specified window.

xDst, yDst

The x- and y-coordinates of the destination rectangle.

dxDst, dyDst

Width and height of the destination rectangle.

lpbi

Address of a BITMAPINFOHEADER structure containing the input format.

xSrc, ySrc

The x- and y-coordinates of the source rectangle.

dxSrc, dySrc

Width and height of the source rectangle.

dwRate

Decompression rate in an integer format. To obtain the rate in frames per second, divide this value by the value in dwScale.

dwScale

Value used to scale dwRate to frames per second.

See Also

BITMAPINFOHEADER, ICM_DRAW_BEGIN


ICDRAWSUGGEST

The ICDRAWSUGGEST structure contains compression parameters used with the ICM_DRAW_SUGGESTFORMAT message to suggest an appropriate input format.

typedef struct {

    LPBITMAPINFOHEADER lpbiIn;

    LPBITMAPINFOHEADER lpbiSuggest;

    int                dxSrc;

    int                dySrc;

    int                dxDst;

    int                dyDst;

    HIC                hicDecompressor;

} ICDRAWSUGGEST;

Members

lpbiIn

Address of the structure containing the compressed input format.

lpbiSuggest

Address of a buffer to return a compatible input format for the renderer.

dxSrc, dySrc

Width and height of the source rectangle.

dxDst, dyDst

Width and height of the destination rectangle.

hicDecompressor

Handle of a decompressor that supports the format of data described in lpbiIn.

See Also

ICM_DRAW_SUGGESTFORMAT


ICINFO

The ICINFO structure contains compression parameters supplied by a video compression driver. The driver fills or updates the structure when it receives the ICM_GETINFO message.

typedef struct {

    DWORD dwSize;

    DWORD fccType;

    DWORD fccHandler;

    DWORD dwFlags;

    DWORD dwVersion;

    DWORD dwVersionICM;

    WCHAR szName[16];

    WCHAR szDescription[128];

    WCHAR szDriver[128];

} ICINFO;

Members

dwSize

Size, in bytes, of the ICINFO structure.

fccType

Four-character code indicating the type of stream being compressed or decompressed. Specify “VIDC” for video streams.

fccHandler

A four-character code identifying a specific compressor.

dwFlags

Applicable flags. Zero or more of the following flags can be set:

VIDCF_COMPRESSFRAMES

Driver is requesting to compress all frames. For information about compressing all frames, see the ICM_COMPRESS_FRAMES_INFO message.

VIDCF_CRUNCH

Driver supports compressing to a frame size.

VIDCF_DRAW

Driver supports drawing.

VIDCF_FASTTEMPORALC

Driver can perform temporal compression and maintains its own copy of the current frame. When compressing a stream of frame data, the driver doesn’t need image data from the previous frame.

VIDCF_FASTTEMPORALD

Driver can perform temporal decompression and maintains its own copy of the current frame. When decompressing a stream of frame data, the driver doesn’t need image data from the previous frame.

VIDCF_QUALITY

Driver supports quality values.

VIDCF_TEMPORAL

Driver supports inter-frame compression.

dwVersion

Version number of the driver.

dwVersionICM

Version of VCM supported by the driver. This member should be set to ICVERSION.

szName

Short version of the compressor name. The name in the null-terminated string should be suitable for use in list boxes.

szDescription

Long version of the compressor name.

szDriver

Name of the module containing VCM compression driver. Normally, a driver does not need to fill this out.

See Also

ICM_COMPRESS_FRAMES_INFO, ICM_GETINFO


ICOPEN

The ICOPEN structure contains information about the data stream being compressed or decompressed, the version number of the driver, and how the driver is used.

typedef struct {

    DWORD    dwSize;

    DWORD    fccType;

    DWORD    fccHandler;

    DWORD    dwVersion;

    DWORD    dwFlags;

    LPRESULT dwError;

    LPVOID   pV1Reserved;

    LPVOID   pV2Reserved;

    DWORD    dnDevNode;

} ICOPEN;

Members

dwSize

Size, in bytes, of the structure.

fccType

Four-character code indicating the type of stream being compressed or decompressed. Specify “VIDC” for video streams.

fccHandler

Four-character code identifying a specific compressor.

dwVersion

Version of the installable driver interface used to open the driver.

dwFlags

Applicable flags indicating why the driver is opened. The following values are defined:

ICMODE_COMPRESS

Driver is opened to compress data.

ICMODE_DECOMPRESS

Driver is opened to decompress data.

ICMODE_DRAW

Device driver is opened to decompress data directly to hardware.

ICMODE_QUERY

Driver is opened for informational purposes, rather than for compression.

dwFlags

Error return values.

pV1Reserved

Reserved; do not use.

pV2Reserved

Reserved; do not use.

dnDevNode

Device node for plug and play devices.

Remarks

This structure is passed to video capture drivers when they are opened. This allows a single installable driver to function as either an installable compressor or a video capture device. By examining the fccType member of the ICOPEN structure, the driver can determine its function. For example, a fccType value of “VIDC” indicates that it is opened as an installable video compressor.


ICSETSTATUSPROC

The ICSETSTATUSPROC structure contains status information used with the ICM_SET_STATUS_PROC message.

typedef struct {

    DWORD  dwFlags;

    LPARAM lParam;

    LONG   (CALLBACK * ()) fpfnStatus;

} ICSETSTATUSPROC;

Members

dwFlags

Reserved; set to zero.

lParam

Parameter that contains a constant to pass to the status procedure.

fpfnStatus

Address of the status function. Specify NULL if status messages should not be sent. For more information about the callback function, see the MyStatusProc function.

See Also

ICM_SET_STATUS_PROC, MyStatusProc


JOYCAPS

The JOYCAPS structure contains information about the joystick capabilities.

typedef struct {

    WORD wMid;

    WORD wPid;

    CHAR szPname[MAXPNAMELEN];

    UINT wXmin;

    UINT wXmax;

    UINT wYmin;

    UINT wYmax;

    UINT wZmin;

    UINT wZmax;

    UINT wNumButtons;

    UINT wPeriodMin;

    UINT wPeriodMax;

    UINT wRmin;

    UINT wRmax;

    UINT wUmin;

    UINT wUmax;

    UINT wVmin;

    UINT wVmax;

    UINT wCaps;

    UINT wMaxAxes;

    UINT wNumAxes;

    UINT wMaxButtons;

    CHAR szRegKey[MAXPNAMELEN];

    CHAR szOEMVxD[MAX_JOYSTICKOEMVXDNAME];

} JOYCAPS;

Members

wMid

Manufacturer identifier. Manufacturer identifiers are defined in Manufacturer and Product Identifiers.

wPid

Product identifier. Product identifiers are defined in Manufacturer and Product Identifiers.

szPname

Null-terminated string containing the joystick product name.

wXMin

Minimum X-coordinate.

wXMax

Maximum X-coordinate.

wYMin

Minimum Y-coordinate.

wYMax

Maximum Y-coordinate.

wZMin

Minimum Z-coordinate.

wZMax

Maximum Z-coordinate.

wNumButtons

Number of joystick buttons.

wPeriodMin

Smallest polling frequency supported when captured by the joySetCapture function.

wPeriodMax

Largest polling frequency supported when captured by joySetCapture.

wRmin and wRmax

Minimum rudder value. The rudder is a fourth axis of movement.

wRmax

Maximum rudder value. The rudder is a fourth axis of movement.

wUmin

Minimum u-coordinate (fifth axis) values.

wUmax

Maximum u-coordinate (fifth axis) values.

wVmin and wVmax

Minimum v-coordinate (sixth axis) values.

wVmax

Maximum v-coordinate (sixth axis) values.

wCaps

Joystick capabilities The following flags define individual capabilities that a joystick might have:

JOYCAPS_HASZ	Joystick has z-coordinate information.
JOYCAPS_HASR	Joystick has rudder (fourth axis) information.
JOYCAPS_HASU	Joystick has u-coordinate (fifth axis) information.
JOYCAPS_HASV	Joystick has v-coordinate (sixth axis) information.
JOYCAPS_HASPOV	Joystick has point-of-view information.
JOYCAPS_POV4DIR	Joystick point-of-view supports discrete values (centered, forward, backward, left, and right).
JOYCAPS_POVCTS	Joystick point-of-view supports continuous degree bearings.
wMaxAxes

Maximum number of axes supported by the joystick.

wNumAxes

Number of axes currently in use by the joystick.

wMaxButtons

Maximum number of buttons supported by the joystick.

szRegKey

Null-terminated string containing the registry key for the joystick.

szOEMVxD

Null-terminated string identifying the joystick driver OEM.

See Also

joySetCapture


JOYINFO

The JOYINFO structure contains information about the joystick position and button state.

typedef struct {

    UINT wXpos;

    UINT wYpos;

    UINT wZpos;

    UINT wButtons;

} JOYINFO;

Members

wXpos

Current X-coordinate.

wYpos

Current Y-coordinate.

wZpos

Current Z-coordinate.

wButtons

Current state of joystick buttons described by one or more of the following values:

JOY_BUTTON1	First joystick button is pressed.
JOY_BUTTON2	Second joystick button is pressed.
JOY_BUTTON3	Third joystick button is pressed.
JOY_BUTTON4	Fourth joystick button is pressed.


JOYINFOEX

The JOYINFOEX structure contains extended information about the joystick position, point-of-view position, and button state.

typedef struct joyinfoex_tag {

    DWORD dwSize;

    DWORD dwFlags;

    DWORD dwXpos;

    DWORD dwYpos;

    DWORD dwZpos;

    DWORD dwRpos;

    DWORD dwUpos;

    DWORD dwVpos;

    DWORD dwButtons;

    DWORD dwButtonNumber;

    DWORD dwPOV;

    DWORD dwReserved1;

    DWORD dwReserved2;

} JOYINFOEX;

Members

dwSize

Size, in bytes, of this structure.

dwFlags

Flags indicating the valid information returned in this structure. Members that do not contain valid information are set to zero. The following flags are defined:

JOY_RETURNALL	Equivalent to setting all of the JOY_RETURN bits except JOY_RETURNRAWDATA.
JOY_RETURNBUTTONS	The dwButtons member contains valid information about the state of each joystick button.
JOY_RETURNCENTERED	Centers the joystick neutral position to the middle value of each axis of movement.
JOY_RETURNPOV	The dwPOV member contains valid information about the point-of-view control, expressed in discrete units.
JOY_RETURNPOVCTS	The dwPOV member contains valid information about the point-of-view control expressed in continuous, one-hundredth degree units.
JOY_RETURNR	The dwRpos member contains valid rudder pedal data. This information represents another (fourth) axis.
JOY_RETURNRAWDATA	Data stored in this structure is uncalibrated joystick readings.
JOY_RETURNU	The dwUpos member contains valid data for a fifth axis of the joystick, if such an axis is available, or returns zero otherwise.
JOY_RETURNV	The dwVpos member contains valid data for a sixth axis of the joystick, if such an axis is available, or returns zero otherwise.
JOY_RETURNX	The dwXpos member contains valid data for the x-coordinate of the joystick.
JOY_RETURNY	The dwYpos member contains valid data for the y-coordinate of the joystick.
JOY_RETURNZ	The dwZpos member contains valid data for the z-coordinate of the joystick.
JOY_USEDEADZONE	Expands the range for the neutral position of the joystick and calls this range the dead zone. The joystick driver returns a constant value for all positions in the dead zone.
The following flags provide data to calibrate a joystick and are intended for custom calibration applications.

JOY_CAL_READ3	Read the x-, y-, and z-coordinates and store the raw values in dwXpos, dwYpos, and dwZpos.
JOY_CAL_READ4	Read the rudder information and the x-, y-, and z-coordinates and store the raw values in dwXpos, dwYpos, dwZpos, and dwRpos.
JOY_CAL_READ5	Read the rudder information and the x-, y-, z-, and u-coordinates and store the raw values in dwXpos, dwYpos, dwZpos, dwRpos, and dwUpos.
JOY_CAL_READ6	Read the raw v-axis data if a joystick mini driver is present that will provide the data. Returns zero otherwise.
JOY_CAL_READALWAYS	Read the joystick port even if the driver does not detect a device.
JOY_CAL_READRONLY	Read the rudder information if a joystick mini-driver is present that will provide the data and store the raw value in dwRpos. Return zero otherwise.
JOY_CAL_READXONLY	Read the x-coordinate and store the raw (uncalibrated) value in dwXpos.
JOY_CAL_READXYONLY	Reads the x- and y-coordinates and place the raw values in dwXpos and dwYpos.
JOY_CAL_READYONLY	Reads the y-coordinate and store the raw value in dwYpos.
JOY_CAL_READZONLY	Read the z-coordinate and store the raw value in dwZpos.
JOY_CAL_READUONLY	Read the u-coordinate if a joystick mini-driver is present that will provide the data and store the raw value in dwUpos. Return zero otherwise.
JOY_CAL_READVONLY	Read the v-coordinate if a joystick mini-driver is present that will provide the data and store the raw value in dwVpos. Return zero otherwise.
dwXpos

Current X-coordinate.

dwYpos

Current Y-coordinate.

dwZpos

Current Z-coordinate.

dwRpos

Current position of the rudder or fourth joystick axis.

dwUpos

Current fifth axis position.

dwVpos

Current sixth axis position.

dwButtons

Current state of the 32 joystick buttons. The value of this member can be set to any combination of JOY_BUTTONn flags, where n is a value in the range of 1 through 32 corresponding to the button that is pressed.

dwButtonNumber

Current button number that is pressed.

dwPOV

Current position of the point-of-view control. Values for this member are in the range 0 through 35,900. These values represent the angle, in degrees, of each view multiplied by 100.

dwReserved1

Reserved; do not use.

dwReserved2

Reserved; do not use.

Remarks

The value of the dwSize member is also used to identify the version number for the structure when it’s passed to the joyGetPosEx function.

Most devices with a point-of-view control have only five positions. When the JOY_RETURNPOV flag is set, these positions are reported by using the following constants:

Point-of-view flags	Description
JOY_POVBACKWARD	Point-of-view hat is pressed backward. The value 18,000 represents an orientation of 180.00 degrees (to the rear).
JOY_POVCENTERED	Point-of-view hat is in the neutral position. The value -1 means the point-of-view hat has no angle to report.
JOY_POVFORWARD	Point-of-view hat is pressed forward. The value 0 represents an orientation of 0.00 degrees (straight ahead).
JOY_POVLEFT	Point-of-view hat is being pressed to the left. The value 27,000 represents an orientation of 270.00 degrees (90.00 degrees to the left).
JOY_POVRIGHT	Point-of-view hat is pressed to the right. The value 9,000 represents an orientation of 90.00 degrees (to the right).
The default Windows 95 joystick driver currently supports these five discrete directions. If an application can accept only the defined point-of-view values, it must use the JOY_RETURNPOV flag. If an application can accept other degree readings, it should use the JOY_RETURNPOVCTS flag to obtain continuous data if it is available. The JOY_RETURNPOVCTS flag also supports the JOY_POV constants used with the JOY_RETURNPOV flag.

See Also

joyGetPosEx


MCI_BREAK_PARMS

The MCI_BREAK_PARMS structure contains virtual-key code and window information for the MCI_BREAK command.

typedef struct {

    DWORD dwCallback;

    int   nVirtKey;

    HWND  hwndBreak;

} MCI_BREAK_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

nVirtKey

Virtual-key code for break key.

hwndBreak

Handle of the window that must be the current window for break detection.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members. The following flags are defined:

MCI_BREAK_HWND

Validates the hwndBreak member specifying the window that must have focus to enable break detection.

MCI_BREAK_KEY

Validates the nVirtKey member specifying the virtual-key code to be used for the break key.

MCI_BREAK_OFF

Disables any existing break key.

See Also

MCI_BREAK, mciSendCommand


MCI_DGV_CAPTURE_PARMS

The MCI_DGV_CAPTURE_PARMS structure contains parameters for the MCI_CAPTURE command for digital-video devices.

typedef struct  {

    DWORD dwCallback;

    LPSTR lpstrFileName;

    RECT  rc;

} MCI_DGV_CAPTURE_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

lpstrFileName

Address of a null-terminated string specifying the destination path and filename for the file that receives the captured data.

rc

Rectangle containing positioning information. RECT structures are handled differently in MCI than in other parts of Windows; in MCI, rc.right contains the width of the rectangle and rc.bottom contains its height.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

mciSendCommand, RECT


MCI_DGV_CUE_PARMS

The MCI_DGV_CUE_PARMS structure contains parameters for the MCI_CUE command for digital-video devices.

typedef struct {

    DWORD dwCallback;

    DWORD dwTo;

} MCI_DGV_CUE_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwTo

Cue position.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_CUE, mciSendCommand


MCI_DGV_COPY_PARMS

The MCI_DGV_COPY_PARMS structure contains parameters for the MCI_COPY command for digital-video devices.

typedef struct  {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

    RECT  rc;

    DWORD dwAudioStream;

    DWORD dwVideoStream;

} MCI_DGV_COPY_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwFrom

Starting position for copy.

dwTo

Ending position for copy.

rc

Rectangle describing area to be copied. RECT structures are handled differently in MCI than in other parts of Windows; in MCI, rc.right contains the width of the rectangle and rc.bottom contains its height.

dwAudioStream

Audio stream.

dwVideoStream

Video stream.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_COPY, mciSendCommand, RECT


MCI_DGV_CUT_PARMS

The MCI_DGV_CUT_PARMS structure contains parameters for the MCI_CUT command for digital-video devices.

typedef struct  {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

    RECT  rc;

    DWORD dwAudioStream;

    DWORD dwVideoStream;

} MCI_DGV_CUT_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwFrom

Starting position for cut.

dwTo

Ending position for cut.

rc

Rectangle describing area to be cut. RECT structures are handled differently in MCI than in other parts of Windows; in MCI, rc.right contains the width of the rectangle and rc.bottom contains its height.

dwAudioStream

Audio stream.

dwVideoStream

Video stream.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_CUT, mciSendCommand, RECT


MCI_DGV_DELETE_PARMS

The MCI_DGV_DELETE_PARMS structure contains parameters for the MCI_DELETE command for digital-video devices.

typedef struct  {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

    RECT  rc;

    DWORD dwAudioStream;

} MCI_DGV_DELETE_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwFrom

Starting position for delete.

dwTo

Ending position for delete.

rc

Rectangle describing area to delete. RECT structures are handled differently in MCI than in other parts of Windows; in MCI, rc.right contains the width of the rectangle and rc.bottom contains its height.

dwAudioStream

Audio stream.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_DELETE, mciSendCommand, RECT


MCI_DGV_FREEZE_PARMS

The MCI_DGV_FREEZE_PARMS structure contains parameters for the MCI_FREEZE and MCI_UNFREEZE commands for digital-video devices.

typedef struct  {

    DWORD dwCallback;

    RECT  rc;

} MCI_DGV_FREEZE_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

rc

Rectangle containing positioning information. RECT structures are handled differently in MCI than in other parts of Windows; in MCI, rc.right contains the width of the rectangle and rc.bottom contains its height.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_FREEZE, MCI_UNFREEZE, mciSendCommand, RECT


MCI_DGV_INFO_PARMS

The MCI_DGV_INFO_PARMS structure contains parameters for the MCI_INFO command for digital-video devices.

typedef struct {

    DWORD  dwCallback;

    LPSTR  lpstrReturn;

    DWORD  dwRetSize;

    DWORD  dwItem;

} MCI_DGV_INFO_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

lpstrReturn

Address of buffer for return string.

dwRetSize

Size, in bytes, of return buffer.

dwItem

Constant describing information to return.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_INFO, mciSendCommand


MCI_DGV_LIST_PARMS

The MCI_DGV_LIST_PARMS structure contains the information for the MCI_LIST command for digital-video devices.

typedef struct  {

    DWORD dwCallback;

    LPSTR lpstrReturn;

    DWORD dwLength;

    DWORD dwNumber;

    DWORD dwItem;

    LPSTR lpstrAlgorithm;

} MCI_DGV_LIST_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

lpstrReturn

Buffer for return string.

dwLength

Length, in bytes, of buffer.

dwNumber

Index of item in list.

dwItem

Type of list item.

lpstrAlgorithm

String containing algorithm name.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_LIST, mciSendCommand


MCI_DGV_LOAD_PARMS

The MCI_DGV_LOAD_PARMS structure contains the information for the MCI_LOAD command for digital-video devices.

typedef struct  {

    DWORD dwCallback;

    LPSTR lpfilename;

} MCI_DGV_LOAD_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

lpfilename

String naming file to load.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_LOAD, mciSendCommand


MCI_DGV_MONITOR_PARMS

The MCI_DGV_MONITOR_PARMS structure contains parameters for the MCI_MONITOR command.

typedef struct  {
    DWORD dwCallback;
    DWORD dwSource;
    DWORD dwMethod;
} MCI_DGV_MONITOR_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwSource

One of the following flags for the monitor source:

MCI_DGV_MONITOR_FILE

The workspace is the presentation source. (This is the default source.) If this flag is used during recording, the recording pauses. If the MCI_MONITOR command changes the presentation source, recording or playing stops and the current position is the value returned by the MCI_STATUS command for the start position.

MCI_DGV_MONITOR_INPUT

The external input is the presentation source. Playback is paused before the input is selected. If the MCI_SETVIDEO command has been enabled using the MCI_SET_ON flag, this flag displays a default hidden window. Device drivers might limit what other device instances can do while monitoring input.

dwMethod

One of the following constants for the type of monitoring:

MCI_DGV_METHOD_DIRECT

The device should be configured for optimum display quality during monitoring. Direct monitoring might be incompatible with motion-video recording.

MCI_DGV_METHOD_POST

The device should show the external input after compression. Post monitoring supports motion-video recording.

MCI_DGV_METHOD_PRE

The device should show the external input prior to compression.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_MONITOR, MCI_SETVIDEO, MCI_STATUS, mciSendCommand


MCI_DGV_OPEN_PARMS

The MCI_DGV_OPEN_PARMS structure contains information for the MCI_OPEN command for digital-video devices.

typedef struct {

    DWORD dwCallback;

    UINT  wDeviceID;

    LPSTR lpstrDeviceType;

    LPSTR lpstrElementName;

    LPSTR lpstrAlias;

    DWORD dwStyle;

    HWND  hWndParent;

} MCI_DGV_OPEN_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

wDevice ID

Device ID returned to user.

lpstrDeviceType

Name or constant ID of device type.

lpstrElementName

Optional device alias.

lpstrAlias

Optional device alias.

dwStyle

Window style.

hWndParent

Handle of parent window.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

mciSendCommand, MCI_OPEN


MCI_DGV_PASTE_PARMS

The MCI_DGV_PASTE_PARMS structure contains parameters for the MCI_PASTE command for digital-video devices.

typedef struct  {

    DWORD dwCallback;

    DWORD dwTo;

    RECT  rc;

    DWORD dwAudioStream;

    DWORD dwVideoStream;

} MCI_DGV_PASTE_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwTo

Starting position for paste.

rc

Rectangle containing positioning information. RECT structures are handled differently in MCI than in other parts of Windows; in MCI, rc.right contains the width of the rectangle and rc.bottom contains its height.

dwAudioStream

Audio stream.

dwVideoStream

Video stream.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

mciSendCommand, MCI_PASTE, RECT


MCI_DGV_PAUSE_PARMS

The MCI_DGV_PAUSE_PARMS structure contains information for the MCI_PAUSE command.

typedef struct {

    DWORD dwCallback;

} MCI_DGV_PAUSE_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

mciSendCommand, MCI_PAUSE


MCI_DGV_PLAY_PARMS

The MCI_DGV_PLAY_PARMS structure contains parameters for the MCI_PLAY command for digital-video devices.

typedef struct {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

} MCI_DGV_PLAY_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwFrom

Position to play from.

dwTo

Position to play to.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

mciSendCommand


MCI_DGV_PUT_PARMS

The MCI_DGV_PUT_PARMS structure contains parameters for the MCI_PUT command for digital-video devices.

typedef struct {

    DWORD dwCallback;

    RECT  rc;

} MCI_DGV_PUT_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

rc

Rectangle containing positioning information. RECT structures are handled differently in MCI than in other parts of Windows; in MCI, rc.right contains the width of the rectangle and rc.bottom contains its height.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_PUT, mciSendCommand, RECT


MCI_DGV_QUALITY_PARMS

The MCI_DGV_QUALITY_PARMS structure contains parameters for the MCI_QUALITY command for digital-video devices.

typedef struct  {

    DWORD dwCallback;

    DWORD dwItem;

    LPSTR lpstrName;

    DWORD lpstrAlgorithm;

    DWORD dwHandle;

} MCI_DGV_QUALITY_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwItem

One of the following constants indicating the type of algorithm:

MCI_QUALITY_ITEM_AUDIO

Definitions are for an audio compression algorithm.

MCI_QUALITY_ITEM_STILL

Definitions are for a still video compression algorithm.

MCI_QUALITY_ITEM_VIDEO

Definitions are for a video compression algorithm.

lpstrName

String naming description.

lpstrAlgorithm

String naming algorithm.

dwHandle

Handle of a structure containing information describing the quality attributes.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_QUALITY, mciSendCommand


MCI_DGV_RECORD_PARMS

The MCI_DGV_RECORD_PARMS structure contains parameters for the MCI_RECORD command for digital-video devices.

typedef struct  {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

    RECT  rc;

    DWORD dwAudioStream;

    DWORD dwVideoStream;

} MCI_DGV_RECORD_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwFrom

Position to record from.

dwTo

Position to record to.

rc

The region of the frame buffer used as the source for the pixels compressed and saved. RECT structures are handled differently in MCI than in other parts of Windows; in MCI, rc.right contains the width of the rectangle and rc.bottom contains its height.

dwAudioStream

Audio stream.

dwVideoStream

Video stream.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_RECORD, RECT, mciSendCommand


MCI_DGV_RECT_PARMS

The MCI_DGV_RECT_PARMS structure contains parameters for the MCI_FREEZE, MCI_PUT, MCI_UNFREEZE, and MCI_WHERE commands for digital-video devices.

typedef struct {

    DWORD dwCallback;

    RECT  rc;

} MCI_DGV_RECT_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

rc

Rectangle containing positioning information. RECT structures are handled differently in MCI than in other parts of Windows; in MCI, rc.right contains the width of the rectangle and rc.bottom contains its height.

Remarks

The MCI_DGV_UNFREEZE_PARMS and MCI_DGV_WHERE_PARMS structures are identical to the MCI_DGV_RECT_PARMS structure.

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_FREEZE, MCI_PUT, MCI_UNFREEZE, MCI_WHERE, mciSendCommand, RECT


MCI_DGV_RESERVE_PARMS

The MCI_DGV_RESERVE_PARMS structure contains information for the MCI_RESERVE command for digital-video devices.

typedef struct  {

    DWORD dwCallback;

    LPSTR lpstrPath;

    DWORD dwSize;

} MCI_DGV_RESERVE_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

lpstrPath

Address of a null-terminated string containing the location of a temporary file. The buffer contains only the drive and directory path of the file used to hold recorded data; the filename is specified by the device driver.

dwSize

Size of reserved disk space.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_RESERVE, mciSendCommand


MCI_DGV_RESTORE_PARMS

The MCI_DGV_RESTORE_PARMS structure contains information for the MCI_RESTORE command for digital-video devices.

typedef struct  {

    DWORD dwCallback;

    DWORD lpstrFileName;

    RECT  rc;

} MCI_DGV_RESTORE_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

lpstrFileName

Address of a null-terminated string containing the filename from which the frame buffer information will be restored.

rc

Rectangle containing positioning information. RECT structures are handled differently in MCI than in other parts of Windows; in MCI, rc.right contains the width of the rectangle and rc.bottom contains its height.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_RESTORE, mciSendCommand, RECT


MCI_DGV_RESUME_PARMS

The MCI_DGV_RESUME_PARMS structure contains information for the MCI_RESUME command.

typedef struct  {

    DWORD dwCallback;

} MCI_DGV_RESUME_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_RESUME, mciSendCommand


MCI_DGV_SAVE_PARMS

The MCI_DGV_SAVE_PARMS structure contains information for the MCI_SAVE command for digital-video devices.

typedef struct  {

    DWORD dwCallback;

    DWORD lpstrFileName;

    RECT  rc;

} MCI_DGV_SAVE_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

lpstrFileName

String for filename to save.

rc

Rectangle containing positioning information. RECT structures are handled differently in MCI than in other parts of Windows; in MCI, rc.right contains the width of the rectangle and rc.bottom contains its height.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SAVE, mciSendCommand, RECT


MCI_DGV_SET_PARMS

The MCI_DGV_SET_PARMS structure contains parameters for the MCI_SET command for digital-video devices.

typedef struct {

    DWORD dwCallback;

    DWORD dwTimeFormat;

    DWORD dwAudio;

    DWORD dwFileFormat;

    DWORD dwSpeed;

} MCI_DGV_SET_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwTimeFormat

Time format of device.

dwAudio

Channel for audio output.

dwFileFormat

File format.

dwSpeed

Playback speed.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SET, mciSendCommand


MCI_DGV_SETAUDIO_PARMS

The MCI_DGV_SETAUDIO_PARMS structure contains parameters for the MCI_SETAUDIO command for digital-video devices.

typedef struct {

    DWORD dwCallback;

    DWORD dwItem;

    DWORD dwValue;

    DWORD dwOver;

    LPSTR lpstrAlgorithm;

    LPSTR lpstrQuality;

} MCI_DGV_SETAUDIO_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwItem

Constant indicating the target adjustment. For a list of possible values, see the MCI_SETAUDIO command.

dwValue

Adjustment level.

dwOver

Transmission length.

lpstrAlgorithm

Address of a null-terminated string containing the name of the audio-compression algorithm.

lpstrQuality

Address of a null-terminated string containing a descriptor of the audio-compression algorithm.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SETAUDIO, mciSendCommand


MCI_DGV_SETVIDEO_PARMS

The MCI_DGV_SETVIDEO_PARMS structure contains parameters for the MCI_SETVIDEO command for digital-video devices.

typedef struct {

    DWORD  dwCallback;

    DWORD  dwItem;

    DWORD  dwValue;

    DWORD  dwOver;

    LPSTR  lpstrQuality;

    LPSTR  lpstrAlgorithm;

    DWORD  dwSourceNumber;

} MCI_DGV_SETVIDEO_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwItem

Constant indicating the target adjustment.

dwValue

Adjustment level.

dwOver

Transmission length.

lpstrQuality

Address of a null-terminated string containing a descriptor of the video-compression algorithm.

lpstrAlgorithm

Address of a null-terminated string containing the name of the video-compression algorithm.

dwSourceNumber

Index of input source.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SETVIDEO, mciSendCommand


MCI_DGV_SIGNAL_PARMS

The MCI_DGV_SIGNAL_PARMS structure contains parameters for the MCI_SIGNAL command for digital-video devices.

typedef struct {

    DWORD dwCallback;

    DWORD dwPosition;

    DWORD dwPeriod;

    DWORD dwUserParm;

} MCI_DGV_SIGNAL_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwPosition

Position to be marked.

dwPeriod

Interval of the position marks.

dwUseParm

User value associated with signals.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SIGNAL, mciSendCommand


MCI_DGV_STATUS_PARMS

The MCI_DGV_STATUS_PARMS structure contains parameters for the MCI_STATUS command for digital-video devices.

typedef struct {

    DWORD dwCallback;

    DWORD dwReturn;

    DWORD dwItem;

    DWORD dwTrack;

    LPSTR lpstrDrive;

    DWORD dwReference;

} MCI_DGV_STATUS_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwReturn

Buffer for return information.

dwItem

Identifies capability being queried.

dwTrack

Length or number of tracks.

lpstrDrive

Specifies the approximate amount of disk space that can be obtained by the MCI_RESERVE command.

dwReference

Specifies the approximate location of the nearest previous intraframe-encoded image.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_RESERVE, MCI_STATUS, mciSendCommand


MCI_DGV_STEP_PARMS

The MCI_DGV_STEP_PARMS structure contains parameters for the MCI_STEP command for digital-video devices.

typedef struct {

    DWORD dwCallback;

    DWORD dwFrames;

} MCI_DGV_STEP_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwFrames

Number of frames to step.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_STEP, mciSendCommand


MCI_DGV_STOP_PARMS

The MCI_DGV_STOP_PARMS structure contains information for the MCI_STOP command for digital-video devices.

typedef struct {

    DWORD dwCallback;

} MCI_DGV_STOP_PARMS;

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_STOP, mciSendCommand


MCI_DGV_UPDATE_PARMS

The MCI_DGV_UPDATE_PARMS structure contains parameters for the MCI_UPDATE command.

typedef struct {

    DWORD dwCallback;

    RECT  rc;

    HDC   hDC;

} MCI_DGV_UPDATE_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

rc

Rectangle containing positioning information. RECT structures are handled differently in MCI than in other parts of Windows; in MCI, rc.right contains the width of the rectangle and rc.bottom contains its height.

hDC

Handle to display context.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_UPDATE, mciSendCommand, RECT


MCI_DGV_WINDOW_PARMS

The MCI_DGV_WINDOW_PARMS structure contains parameters for MCI_WINDOW command for digital-video devices.

typedef struct {

    DWORD dwCallback;

    WORD  hWnd;

    WORD  nCmdShow;

    LPSTR lpstrText;

} MCI_DGV_WINDOW_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

hWnd

Handle to the display window. If this member is MCI_DGV_WINDOW_HWND, the system uses a default window.

nCmdShow

Window-display command.

lpstrText

Window caption.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members

See Also

MCI_WINDOW, mciSendCommand


MCI_GENERIC_PARMS

The MCI_GENERIC_PARMS structure contains the handle of the window that receives notification messages. This structure is used for MCI command messages that have empty parameter lists.

typedef struct {

    DWORD dwCallback;

} MCI_GENERIC_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

Remarks

The MCI_CLOSE_PARMS and MCI_REALIZE_PARMS structures are identical to the MCI_GENERIC_PARMS structure.

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

mciSendCommand


MCI_GETDEVCAPS_PARMS

The MCI_GETDEVCAPS_PARMS structure contains device-capability information for the MCI_GETDEVCAPS command.

typedef struct {

    DWORD dwCallback;

    DWORD dwReturn;

    DWORD dwItem;

} MCI_GETDEVCAPS_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwReturn

Contains information on exit.

dwItem

Capability being queried. This member can be one of the constants listed in the reference material for the MCI_GETDEVCAPS command.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_GETDEVCAPS, mciSendCommand


MCI_INFO_PARMS

The MCI_INFO_PARMS structure contains information for the MCI_INFO command.

typedef struct {

    DWORD dwCallback;

    LPSTR lpstrReturn;

    DWORD dwRetSize;

} MCI_INFO_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

lpstrReturn

Buffer for return string.

dwRetSize

Size, in bytes, of return string.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_INFO, mciSendCommand


MCI_LOAD_PARMS

The MCI_LOAD_PARMS structure contains the filename to load for the MCI_LOAD command.

typedef struct {

    DWORD   dwCallback;

    LPCSTR  lpfilename;

} MCI_LOAD_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

lpfilename

Name of file to load.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_LOAD, mciSendCommand


MCI_OPEN_PARMS

The MCI_OPEN_PARMS structure contains information for the MCI_OPEN command.

typedef struct {

    DWORD        dwCallback;

    MCIDEVICEID  wDeviceID;

    LPCSTR       lpstrDeviceType;

    LPCSTR       lpstrElementName;

    LPCSTR       lpstrAlias;

} MCI_OPEN_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

wDeviceID

Identifier returned to application.

lpstrDeviceType

Name or constant identifier of the device type. (The name of the device is typically obtained from the registry or SYSTEM.INI file.) If this member is a constant, it can be one of the values listed in Constants: Device Types.

lpstrElementName

Device element (often a path).

lpstrAlias

Optional device alias.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_OPEN, mciSendCommand


MCI_OVLY_LOAD_PARMS

The MCI_OVLY_LOAD_PARMS structure contains information for the MCI_LOAD command for video-overlay devices.

typedef struct {

    DWORD  dwCallback;

    LPCSTR lpfilename;

    RECT   rc;

} MCI_OVLY_LOAD_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

lpfilename

Name of file to load.

rc

Identifies the area of the video buffer to update. RECT structures are handled differently in MCI than in other parts of Windows; in MCI, rc.right contains the width of the rectangle and rc.bottom contains its height.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_LOAD, mciSendCommand, RECT


MCI_OVLY_OPEN_PARMS

The MCI_OVLY_OPEN_PARMS structure contains information for the MCI_OPEN command for video-overlay devices.

typedef struct {

    DWORD  dwCallback;

    MCIDEVICEID wDeviceID;

    LPCSTR lpstrDeviceType;

    LPCSTR lpstrElementName;

    LPCSTR lpstrAlias;

    DWORD  dwStyle;

    DWORD  hWndParent;

} MCI_OVLY_OPEN_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

wDeviceID

Identifier returned to application.

lpstrDeviceType

Name or constant identifier of the device type. (The name of the device is typically obtained from the registry or SYSTEM.INI file.) If this member is a constant, it can be one of the values listed in Constants: Device Types.

lpstrElementName

Device element name (usually a path).

lpstrAlias

Optional device alias.

dwStyle

Window style.

hWndParent

Handle of parent window.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

You can use the MCI_OPEN_PARMS structure in place of MCI_OVLY_OPEN_PARMS if you are not using the extended data members.

See Also

MCI_OPEN, MCI_OPEN_PARMS, mciSendCommand


MCI_OVLY_RECT_PARMS

The MCI_OVLY_RECT_PARMS structure contains positioning information for the MCI_PUT and MCI_WHERE commands for video-overlay devices.

typedef struct {

    DWORD dwCallback;

    RECT  rc;

} MCI_OVLY_RECT_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

rc

Rectangle containing positioning information. RECT structures are handled differently in MCI than in other parts of Windows; in MCI, rc.right contains the width of the rectangle and rc.bottom contains its height.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_PUT, MCI_WHERE, mciSendCommand, RECT


MCI_OVLY_SAVE_PARMS

The MCI_OVLY_SAVE_PARMS structure contains information for the MCI_SAVE command for video-overlay devices.

typedef struct {

    DWORD  dwCallback;

    LPCSTR lpfilename;

    RECT   rc;

} MCI_OVLY_SAVE_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

lpfilename

Name of file to save.

rc

Rectangle indicating the area of the video buffer to save. RECT structures are handled differently in MCI than in other parts of Windows; in MCI, rc.right contains the width of the rectangle and rc.bottom contains its height.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SAVE, mciSendCommand, RECT


MCI_OVLY_WINDOW_PARMS

The MCI_OVLY_WINDOW_PARMS structure contains window-display information for the MCI_WINDOW command for video-overlay devices.

typedef struct {

    DWORD  dwCallback;

    HWND   hWnd;

    UINT   nCmdShow;

    LPCSTR lpstrText;

} MCI_OVLY_WINDOW_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

hWnd

Handle of display window.

nCmdShow

Window-display command.

lpstrText

Window caption.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_WINDOW, mciSendCommand


MCI_PLAY_PARMS

The MCI_PLAY_PARMS structure contains positioning information for the MCI_PLAY command.

typedef struct {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

} MCI_PLAY_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwFrom

Position to play from.

dwTo

Position to play to.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_PLAY, mciSendCommand


MCI_RECORD_PARMS

The MCI_RECORD_PARMS structure contains positioning information for the MCI_RECORD command.

typedef struct {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

} MCI_RECORD_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwFrom

Position to play from.

dwTo

Position to play to.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_RECORD, mciSendCommand


MCI_SAVE_PARMS

The MCI_SAVE_PARMS structure contains the filename information for the MCI_SAVE command.

typedef struct {

    DWORD  dwCallback;

    LPCSTR lpfilename;

} MCI_SAVE_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

lpfilename

Name of file to save.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SAVE, mciSendCommand


MCI_SEEK_PARMS

The MCI_SEEK_PARMS structure contains positioning information for the MCI_SEEK command.

typedef struct {

    DWORD dwCallback;

    DWORD dwTo;

} MCI_SEEK_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwTo

Position to seek to.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SEEK, mciSendCommand


MCI_SEQ_SET_PARMS

The MCI_SEQ_SET_PARMS structure contains information for the MCI_SET command for MIDI sequencer devices.

typedef struct {

    DWORD dwCallback;

    DWORD dwTimeFormat;

    DWORD dwAudio;

    DWORD dwTempo;

    DWORD dwPort;

    DWORD dwSlave;

    DWORD dwMaster;

    DWORD dwOffset;

} MCI_SEQ_SET_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwTimeFormat

Sequencer’s time format.

dwAudio

Audio output channel.

dwTempo

Tempo.

dwSlave

Type of synchronization used by the sequencer for slave operation.

dwMaster

Type of synchronization used by the sequencer for master operation.

dwOffset

Data offset.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SET, mciSendCommand


MCI_SET_PARMS

The MCI_SET_PARMS structure contains information for the MCI_SET command.

typedef struct {

    DWORD dwCallback;

    DWORD dwTimeFormat;

    DWORD dwAudio;

} MCI_SET_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwTimeFormat

Time format for device.

dwAudio

Audio output channel.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SET, mciSendCommand


MCI_STATUS_PARMS

The MCI_STATUS_PARMS structure contains information for the MCI_STATUS command.

typedef struct {

    DWORD dwCallback;

    DWORD dwReturn;

    DWORD dwItem;

    DWORD dwTrack;

} MCI_STATUS_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwReturn

Contains information on return.

dwItem

Capability being queried.

dwTrack

Length or number of tracks.

Remarks

The MCI_STATUS_ITEM flag must be set in the fdwCommand parameter of the mciSendCommand function to validate the dwItem member, which should contain one of the constants indicating what status information is being requested.

See Also

MCI_STATUS, mciSendCommand


MCI_SYSINFO_PARMS

The MCI_SYSINFO_PARMS structure contains information for the MCI_SYSINFO command.

typedef struct {

    DWORD dwCallback;

    LPSTR lpstrReturn;

    DWORD dwRetSize;

    DWORD dwNumber;

    UINT  wDeviceType;

} MCI_SYSINFO_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

lpstrReturn

Address of a user-supplied buffer for the return string. It is also used to return a doubleword value when the MCI_SYSINFO_QUANTITY flag is used.

dwRetSize

Size, in bytes, of return buffer.

dwNumber

Number indicating the device position in the MCI device table or in the list of open devices if the MCI_SYSINFO_OPEN flag is set.

wDeviceType

Type of device. This member can be one of the values listed in Constants: Device Types.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SYSINFO, mciSendCommand


MCI_VCR_CUE_PARMS

The MCI_VCR_CUE_PARMS structure contains parameters for the MCI_CUE command for video-cassette recorders.

typedef struct tagMCI_VCR_CUE_PARMS {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

} MCI_VCR_CUE_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwFrom

Position to cue from.

dwTo

Position to cue to.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_CUE, mciSendCommand


MCI_VCR_LIST_PARMS

The MCI_VCR_LIST_PARMS structure contains parameters for the MCI_LIST command for video-cassette recorders.

typedef struct tagMCI_VCR_LIST_PARMS {

    DWORD dwCallback;

    DWORD dwReturn;

    DWORD dwNumber;

} MCI_VCR_LIST_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwReturn

Buffer for returned information.

dwNumber

Number of VCR’s video or audio inputs.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_LIST, mciSendCommand


MCI_VCR_PLAY_PARMS

The MCI_VCR_PLAY_PARMS structure contains parameters for the MCI_PLAY command for video-cassette recorders.

typedef struct tagMCI_VCR_PLAY_PARMS {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

    DWORD dwAt;

} MCI_VCR_PLAY_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwFrom

Position to play from.

dwTo

Position to play to.

dwAt

Time value that affects the MCI_PLAY or MCI_CUE command. For MCI_PLAY, this is the time when playback begins. For MCI_CUE, this is the time when the cued device reaches the position given in dwFrom.

Remarks

Positions are specified in the current time format.

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_CUE, MCI_PLAY, mciSendCommand


MCI_VCR_RECORD_PARMS

The MCI_VCR_RECORD_PARMS structure contains parameters for the MCI_RECORD command for video-cassette recorders.

typedef struct tagMCI_VCR_RECORD_PARMS {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

    DWORD dwAt;

} MCI_VCR_RECORD_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwFrom

Position to play from.

dwTo

Position to play to.

dwAt

Time value that affects the MCI_RECORD or MCI_CUE command. For MCI_RECORD, this is the time when recording begins. For MCI_CUE, this is the time when the cued device reaches the position given in dwFrom.

Remarks

Positions are specified in the current time format.

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_CUE, MCI_RECORD, mciSendCommand


MCI_VCR_SEEK_PARMS

The MCI_VCR_SEEK_PARMS structure contains parameters for the MCI_SEEK command for video-cassette recorders.

typedef struct tagMCI_VCR_SEEK_PARMS {

    DWORD dwCallback;

    DWORD dwTo;

    DWORD dwMark;

    DWORD dwAt;

} MCI_VCR_SEEK_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwTo

Position to seek to.

dwMark

Numbered mark to seek for.

dwAt

Time when seek begins.

Remarks

Positions are specified in the current time format.

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SEEK, mciSendCommand


MCI_VCR_SET_PARMS

The MCI_VCR_SET_PARMS structure contains parameters for the MCI_SET command for video-cassette recorders.

typedef struct tagMCI_VCR_SET_PARMS {

    DWORD dwCallback;

    DWORD dwTimeFormat;

    DWORD dwAudio;

    DWORD dwTimeMode;

    DWORD dwRecordFormat;

    DWORD dwCounterFormat;

    DWORD dwIndex;

    DWORD dwTracking;

    DWORD dwSpeed;

    DWORD dwLength;

    DWORD dwCounter;

    DWORD dwClock;

    DWORD dwPauseTimeout;

    DWORD dwPrerollDuration;

    DWORD dwPostrollDuration;

} MCI_VCR_SET_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwTimeFormat

Current time format.

dwAudio

Not used.

dwTimeMode

Constant that specifies the timing source used by the device. The timing source is either a timecode recorded on videotape, or the counters in the device that sense videotape movement.

dwRecordFormat

Recording rate.

dwCounterFormat

Format of a new counter time value.

dwIndex

Contents of on-screen display.

dwTracking

Speed adjustment used when tracking the VCR playback rate.

dwSpeed

Playback speed used by the device as an integer. Normal playback speed is 1000, double speed is 2000, and half speed is 500.

dwLength

Videotape length when the length is undetectable by the device.

dwCounter

New counter value.

dwClock

New clock time.

dwPauseTimeout

New timeout value for pause command.

dwPrerollDuration

Videotape length needed to stabilize the VCR output.

dwPostrollDuration

Videotape length needed to brake the VCR transport when a MCI_STOP or MCI_PAUSE command is issued.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_PAUSE, MCI_SET, MCI_STOP, mciSendCommand


MCI_VCR_SETAUDIO_PARMS

The MCI_VCR_SETAUDIO_PARMS structure contains parameters for the MCI_SETAUDIO command for video-cassette recorders.

typedef struct tagMCI_VCR_SETAUDIO_PARMS {

    DWORD dwCallback;

    DWORD dwTrack;

    DWORD dwTo;

    DWORD dwNumber;

} MCI_VCR_SETAUDIO_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwTrack

Audio track.

dwTo

Type of input or monitored input.

dwNumber

Audio input (of the type specified in the dwTo member) to use.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SETAUDIO, mciSendCommand


MCI_VCR_SETTUNER_PARMS

The MCI_VCR_SETTUNER_PARMS structure contains parameters for the MCI_SETTUNER command for video-cassette recorders.

typedef struct tagMCI_VCR_SETTUNER_PARMS {

    DWORD dwCallback;

    DWORD dwChannel;

    DWORD dwNumber;

} MCI_VCR_SETTUNER_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwChannel

New channel number.

dwNumber

Logical tuner that the MCI_SETTUNER command affects.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SETTUNER, mciSendCommand


MCI_VCR_SETVIDEO_PARMS

The MCI_VCR_SETVIDEO_PARMS structure contains parameters for the MCI_SETVIDEO command for video-cassette recorders.

typedef struct tagMCI_VCR_SETVIDEO_PARMS {

    DWORD dwCallback;

    DWORD dwTrack;

    DWORD dwTo;

    DWORD dwNumber;

} MCI_VCR_SETVIDEO_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwTrack

Affected track.

dwTo

Type of input or monitored input.

dwNumber

Video input (of the type specified in the dwTo member) to use.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SETVIDEO, mciSendCommand


MCI_VCR_STATUS_PARMS

The MCI_VCR_STATUS_PARMS structure contains parameters for the MCI_STATUS command for video-cassette recorders.

typedef struct tagMCI_VCR_STATUS_PARMS {

    DWORD dwCallback;

    DWORD dwReturn;

    DWORD dwItem;

    DWORD dwTrack;

    DWORD dwNumber;

} MCI_VCR_STATUS_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwReturn

Value returned by the MCI_STATUS command. The return value varies according to the inquiry of the command. For more information, see the description of the MCI_STATUS command.

dwItem

Type of information requested.

dwTrack

Audio or video track that will store information during the next recording. This member is used to return information when the MCI_STATUS command inquires about the video or audio recording status.

dwNumber

Logical tuner that the current channel is associated with. This member is used to return information when the MCI_STATUS command inquires about the current channel number.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_STATUS, mciSendCommand


MCI_VCR_STEP_PARMS

The MCI_VCR_STEP_PARMS structure contains parameters for the MCI_STEP command for video-cassette recorders.

typedef struct tagMCI_VCR_STEP_PARMS {

    DWORD dwCallback;

    DWORD dwFrames;

} MCI_VCR_STEP_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwFrames

Number of frames to jump (the length of a single step) as the MCI_STEP command steps forward or backward through the content.

Remarks

When assigning data to the members in this structure, set the corresponding flags in the fdwCommand parameter of mciSendCommand to validate the members.

See Also

MCI_STEP, mciSendCommand


MCI_VD_ESCAPE_PARMS

The MCI_VD_ESCAPE_PARMS structure contains the command sent to a device for the MCI_ESCAPE command for videodisc devices.

typedef struct {

    DWORD  dwCallback;

    LPCSTR lpstrCommand;

} MCI_VD_ESCAPE_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

lpstrCommand

Command to send to device.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_ESCAPE, mciSendCommand


MCI_VD_PLAY_PARMS

The MCI_VD_PLAY_PARMS structure contains position and speed information for the MCI_PLAY command for videodisc devices.

typedef struct {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

    DWORD dwSpeed;

} MCI_VD_PLAY_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwFrom

Position to play from.

dwTo

Position to play to.

dwSpeed

Playback speed in frames per second.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

You can use the MCI_PLAY_PARMS structure instead of MCI_VD_PLAY_PARMS if you are not using the extended data members.

See Also

MCI_PLAY, MCI_PLAY_PARMS, mciSendCommand


MCI_VD_STEP_PARMS

The MCI_VD_STEP_PARMS structure contains information for the MCI_STEP command for videodisc devices.

typedef struct {

    DWORD dwCallback;

    DWORD dwFrames;

} MCI_VD_STEP_PARMS;

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwFrames

Number of frames to step.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_STEP, mciSendCommand


MCI_WAVE_DELETE_PARMS

The MCI_WAVE_DELETE_PARMS structure contains position information for the MCI_DELETE command for waveform-audio devices.

typedef struct {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

} MCI_WAVE_DELETE_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwFrom

Position to delete from.

dwTo

Position to delete to.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_DELETE, mciSendCommand


MCI_WAVE_OPEN_PARMS

The MCI_WAVE_OPEN_PARMS structure contains information for MCI_OPEN command for waveform-audio devices.

typedef struct {

    DWORD  dwCallback;

    MCIDEVICEID   wDeviceID;

    LPCSTR lpstrDeviceType;

    LPCSTR lpstrElementName;

    LPCSTR lpstrAlias;

    DWORD  dwBufferSeconds;

} MCI_WAVE_OPEN_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

wDeviceID

Indentifier returned to application.

lpstrDeviceType

Name or constant identifier of the device type. (The name of the device is typically obtained from the registry or SYSTEM.INI file.) This member can be one of the values listed in Constants: Device Types.

lpstrElementName

Device element name (usually a path).

lpstrAlias

Optional device alias.

dwBufferSeconds

Buffer length, in seconds.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

You can use the MCI_OPEN_PARMS structure instead of MCI_WAVE_OPEN_PARMS if you are not using the extended data members.

See Also

MCI_OPEN, mciSendCommand, MCI_OPEN_PARMS


MCI_WAVE_SET_PARMS

The MCI_WAVE_SET_PARMS structure contains information for the MCI_SET command for waveform-audio devices.

typedef struct {

    DWORD dwCallback;

    DWORD dwTimeFormat;

    DWORD dwAudio;

    UINT  wInput;

    UINT  wOutput;

    WORD  wFormatTag;

    WORD  wReserved2;

    WORD  nChannels;

    WORD  wReserved3;

    DWORD nSamplesPerSec;

    DWORD nAvgBytesPerSec;

    WORD  nBlockAlign;

    WORD  wReserved4;

    WORD  wBitsPerSample;

    WORD  wReserved5;

} MCI_WAVE_SET_PARMS;

Members

dwCallback

The low-order word specifies a window handle used for the MCI_NOTIFY flag.

dwTimeFormat

Device’s time format.

dwAudio

Channel number for audio output. Typically used when turning a channel on or off.

wInput

Audio input channel.

wOutput

Output device to use. For example, this value could be 2 if a system had two installed sound cards.

wFormatTag

Format of the waveform-audio data. This member can be one of the following:

WAVE_FORMAT_ADPCM

Microsoft Corporation

WAVE_FORMAT_ALAW

Microsoft Corporation

WAVE_FORMAT_ANTEX_ADPCME

Antex Electronics Corporation

WAVE_FORMAT_APTX

Audio Processing Technology

WAVE_FORMAT_AUDIOFILE_AF10

Audiofile

WAVE_FORMAT_AUDIOFILE_AF36

Audiofile

WAVE_FORMAT_CONTROL_RES_CR10

Control Resources Corporation

WAVE_FORMAT_CONTROL_RES_VQLPC

Control Resources Corporation

WAVE_FORMAT_CREATIVE_ADPCM

Creative Labs, Inc.

WAVE_FORMAT_CREATIVE_FASTSPEECH10

Creative Labs, Inc.

WAVE_FORMAT__CREATIVE__FASTSPEECH8

Creative Labs, Inc.

WAVE_FORMAT_DIALOGIC_OKI_ADPCM

Dialogic Corporation

WAVE_FORMAT_DIGIADPCM

DSP Solutions, Inc.

WAVE_FORMAT_DIGIFIX

DSP Solutions, Inc.

WAVE_FORMAT_DIGIREAL

DSP Solutions, Inc.

WAVE_FORMAT_DIGISTD

DSP Solutions, Inc.

WAVE_FORMAT_DOLBY_AC2

Dolby Laboratories, Inc.

WAVE_FORMAT_DSPGROUP_TRUESPEECH

DSP Group, Inc.

WAVE_FORMAT_DVI_ADPCM

Intel Corporation

WAVE_FORMAT_ECHOSC1

Echo Speech Corporation

WAVE_FORMAT_FM_TOWNS_SND

Fujitsu, Ltd.

WAVE_FORMAT_G721_ADPCM

Antex Electronics Corporation

WAVE_FORMAT_G723_ADPCM

Antex Electronics Corporation

WAVE_FORMAT_GSM610

Microsoft Corporation

WAVE_FORMAT_IBM_CVSD

International Business Machines

WAVE_FORMAT_IMA_ADPCM

Intel Corporation

WAVE_FORMAT_MEDIASPACE_ADPCM

VideoLogic, Inc.

WAVE_FORMAT_MPEG

Microsoft Corporation

WAVE_FORMAT_MULAW

Microsoft Corporation

WAVE_FORMAT_NMS_VBXADPCM

Natural MicroSystems Corporation

WAVE_FORMAT_OKI_ADPCM

OKI

WAVE_FORMAT_OLIADPCM

Ing C. Olivetti & C., S.p.A.

WAVE_FORMAT_OLICELP

Ing C. Olivetti & C., S.p.A.

WAVE_FORMAT_OLIGSM

Ing C. Olivetti & C., S.p.A.

WAVE_FORMAT_OLIOPR

Ing C. Olivetti & C., S.p.A.

WAVE_FORMAT_OLISBC

Ing C. Olivetti & C., S.p.A.

WAVE_FORMAT_SIERRA_ADPCM

Sierra Semiconductor Corporation

WAVE_FORMAT_SONARC

Speech Compression

WAVE_FORMAT_UNKNOWN

Microsoft Corporation

WAVE_FORMAT_YAMAHA_ADPCM

Yamaha Corporation of America

wReserved2

Reserved.

nChannels

Mono (1) or stereo (2).

wReserved3

Reserved.

nSamplesPerSec

Samples per second.

nAvgBytesPerSec

Sample rate in bytes per second.

nBlockAlign

Block alignment of the data.

wReserved4

Reserved.

wBitsPerSample

Bits per sample.

wReserved5

Reserved.

Remarks

When assigning data to the members of this structure, set the corresponding flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

See Also

MCI_SET, mciSendCommand


MIDIEVENT

The MIDIEVENT structure describes a MIDI event in a stream buffer.

typedef struct {

    DWORD dwDeltaTime;

    DWORD dwStreamID;

    DWORD dwEvent;

    DWORD dwParms[];

} MIDIEVENT;

Members

dwDeltaTime

Time, in MIDI ticks, between the previous event and the current event. The length of a tick is defined by the time format and possibly the tempo associated with the stream. (The definition is identical to the specification for a tick in a standard MIDI file.)

dwStreamID

Reserved; must be zero.

dwEvent

Event code and event parameters or length. To parse this information, use the MEVT_EVENTTYPE and MEVT_EVENTPARM macros.

The high byte of this member contains one or more of the following flags and an event code:

MEVT_F_CALLBACK

The system generates a callback when the event is about to be executed.

MEVT_F_LONG

The event is a long event. The low 24 bits of dwEvent contain the length of the event parameters.

MEVT_F_SHORT

The event is a short event. The event parameters are contained in the low 24 bits of dwEvent.

Either MEVT_F_LONG or MEVT_F_SHORT must be specified, but MEVT_F_CALLBACK is optional.

The remainder of the high byte contains one of the following event codes:

MEVT_COMMENT

Long event. The event data will be ignored. This event is intended to store commentary information about the stream that might be useful to authoring programs or sequencers if the stream data were to be stored in a file in stream format. In a buffer of this data, the zero byte identifies the comment class and subsequent bytes contain the comment data.

MEVT_LONGMSG

Long event. The event data is transmitted verbatim. The event data is assumed to be system-exclusive data; that is, running status will be cleared when the event is executed and running status from any previous events will not be applied to any channel events in the event data. Using this event to send a group of channel messages at the same time is not recommended; a set of MEVT_SHORTMSG events with zero delta times should be used instead.

MEVT_NOP

Short event. This event is a placeholder; it does nothing. The low 24 bits are ignored. This event will still generate a callback if MEVT_F_CALLBACK is set in dwEvent.

MEVT_SHORTMSG

Short event. The data in the low 24 bits of dwEvent is a MIDI short message. (For a description of how a short message is packed into a doubleword value, see the midiOutShortMsg function.)

MEVT_TEMPO

Short event. The data in the low 24 bits of dwEvent contain the new tempo for following events. The tempo is specified in the same format as it is for the tempo change meta-event in a MIDI file — that is, in microseconds per quarter note. (This event will have no affect if the time format specified for the stream is SMPTE time.)

MEVT_VERSION

Long event. The event data must contain a MIDISTRMBUFFVER structure.

dwParms

Parameters for the event, if dwEvent specifies MEVT_F_LONG and the length of the buffer. This parameter data must be padded with zeros so that an integral number of doubleword values are stored. For example, if the event data is five bytes long, three pad bytes must follow the data for a total of eight bytes. In this case, the low 24 bits of dwEvent would contain the value 5.

See Also

MEVT_EVENTTYPE, MEVT_EVENTPARM, midiOutShortMsg, MIDISTRMBUFFVER


MIDIHDR

The MIDIHDR structure defines the header used to identify a MIDI system-exclusive or stream buffer.

typedef struct {

    LPSTR  lpData;

    DWORD  dwBufferLength;

    DWORD  dwBytesRecorded;

    DWORD  dwUser;

    DWORD  dwFlags;

    struct midihdr_tag far * lpNext;

    DWORD  reserved;

    DWORD  dwOffset;

    DWORD  dwReserved[4];

} MIDIHDR;

Members

lpData

Address of MIDI data.

dwBufferLength

Size of the buffer.

dwBytesRecorded

Actual amount of data in the buffer. This value should be less than or equal to the value given in the dwBufferLength member.

dwUser

Custom user data.

dwFlags

Flags giving information about the buffer.

MHDR_DONE

Set by the device driver to indicate that it is finished with the buffer and is returning it to the application.

MHDR_INQUEUE

Set by Windows to indicate that the buffer is queued for playback.

MHDR_ISSTRM

Set to indicate that the buffer is a stream buffer.

MHDR_PREPARED

Set by Windows to indicate that the buffer has been prepared by using the midiInPrepareHeader or midiOutPrepareHeader function.

midihdr_tag

Reserved; do not use.

reserved

Reserved; do not use.

dwOffset

Offset into the buffer when a callback is performed. (This callback is generated because the MEVT_F_CALLBACK flag is set in the dwEvent member of the MIDIEVENT structure.) This offset enables an application to determine which event caused the callback.

dwReserved

Reserved; do not use.

See Also

MIDIEVENT, midiInPrepareHeader, midiOutPrepareHeader


MIDIINCAPS

The MIDIINCAPS structure describes the capabilities of a MIDI input device.

typedef struct {

    WORD      wMid;

    WORD      wPid;

    MMVERSION vDriverVersion;

    CHAR      szPname[MAXPNAMELEN];

    DWORD     dwSupport;

} MIDIINCAPS;

Members

wMid

Manufacturer identifier of the device driver for the MIDI input device. Manufacturer identifiers are defined in Manufacturer and Product Identifiers.

wPid

Product identifier of the MIDI input device. Product identifiers are defined in Manufacturer and Product Identifiers.

vDriverVersion

Version number of the device driver for the MIDI input device. The high-order byte is the major version number, and the low-order byte is the minor version number.

szPname

Product name in a null-terminated string.

dwSupport

Reserved; must be zero.


MIDIOUTCAPS

The MIDIOUTCAPS structure describes the capabilities of a MIDI output device.

typedef struct {

    WORD      wMid;

    WORD      wPid;

    MMVERSION vDriverVersion;

    CHAR      szPname[MAXPNAMELEN];

    WORD      wTechnology;

    WORD      wVoices;

    WORD      wNotes;

    WORD      wChannelMask;

    DWORD     dwSupport;

} MIDIOUTCAPS;

Members

wMid

Manufacturer identifier of the device driver for the MIDI output device. Manufacturer identifiers are defined in Manufacturer and Product Identifiers.

wPid

Product identifier of the MIDI output device. Product identifiers are defined in Manufacturer and Product Identifiers.

vDriverVersion

Version number of the device driver for the MIDI output device. The high-order byte is the major version number, and the low-order byte is the minor version number.

szPname

Product name in a null-terminated string.

wTechnology

Flags describing the type of the MIDI output device. It can be one of the following:

MOD_FMSYNTH

The device is an FM synthesizer.

MOD_MAPPER

The device is the Microsoft MIDI mapper.

MOD_MIDIPORT

The device is a MIDI hardware port.

MOD_SQSYNTH

The device is a square wave synthesizer.

MOD_SYNTH

The device is a synthesizer.

wVoices

Number of voices supported by an internal synthesizer device. If the device is a port, this member is not meaningful and is set to 0.

wNotes

Maximum number of simultaneous notes that can be played by an internal synthesizer device. If the device is a port, this member is not meaningful and is set to 0.

wChannelMask

Channels that an internal synthesizer device responds to, where the least significant bit refers to channel 0 and the most significant bit to channel 15. Port devices that transmit on all channels set this member to 0xFFFF.

dwSupport

Optional functionality supported by the device. It can be one or more of the following:

MIDICAPS_CACHE

Supports patch caching.

MIDICAPS_LRVOLUME

Supports separate left and right volume control.

MIDICAPS_STREAM

Provides direct support for the midiStreamOut function.

MIDICAPS_VOLUME

Supports volume control.

If a device supports volume changes, the MIDICAPS_VOLUME flag will be set for the dwSupport member. If a device supports separate volume changes on the left and right channels, both the MIDICAPS_VOLUME and the MIDICAPS_LRVOLUME flags will be set for this member.

See Also

midiStreamOut


MIDIPROPTEMPO

The MIDIPROPTEMPO structure contains the tempo property for a stream.

typedef struct {

    DWORD cbStruct;

    DWORD dwTempo;

} MIDIPROPTEMPO;

Members

cbStruct

Length, in bytes, of this structure. This member must be filled in for both the MIDIPROP_SET and MIDIPROP_GET operations of the midiStreamProperty function.

dwTempo

Tempo of the stream, in microseconds per quarter note. The tempo is honored only if the time division for the stream is specified in quarter note format. This member is set in a MIDIPROP_SET operation and is filled on return from a MIDIPROP_GET operation.

Remarks

The tempo property is read or written by the midiStreamProperty function.

See Also

midiStreamProperty


MIDIPROPTIMEDIV

The MIDIPROPTIMEDIV structure contains the time division property for a stream.

typedef struct {

    DWORD cbStruct;

    DWORD dwTimeDiv;

} MIDIPROPTIMEDIV;

Members

cbStruct

Length, in bytes, of this structure. This member must be filled in for both the MIDIPROP_SET and MIDIPROP_GET operations of the midiStreamProperty function.

dwTimeDiv

Time division for this stream, in the format specified in the Standard MIDI Files 1.0 specification. The low 16 bits of this doubleword value contain the time division. This member is set in a MIDIPROP_SET operation and is filled on return from a MIDIPROP_GET operation.

Remarks

The time division property is read or written by the midiStreamProperty function.

See Also

midiStreamProperty


MIDISTRMBUFFVER

The MIDISTRMBUFFVER structure contains version information for a long MIDI event of the MEVT_VERSION type.

typedef struct {

    DWORD dwVersion;

    DWORD dwMid;

    DWORD dwOEMVersion;

} MIDISTRMBUFFVER;

Members

dwVersion

Version of the stream. The high 16 bits contain the major version, and the low 16 bits contain the minor version. The version number for the first implementation of MIDI streams should be 1.0.

dwMid

Manufacturer identifier. Manufacturer identifiers are defined in Manufacturer and Product Identifiers.

dwOEMVersion

OEM version of the stream. Original equipment manufacturers can use this field to version-stamp any custom events they have specified. If a custom event is specified, it must be the first event sent after the stream is opened.


MIXERCAPS

The MIXERCAPS structure describes the capabilities of a mixer device.

typedef struct {

    WORD    wMid;

    WORD    wPid;

    MMVERSION vDriverVersion;

    CHAR    szPname[MAXPNAMELEN];

    DWORD   fdwSupport;

    DWORD   cDestinations;

} MIXERCAPS;

Members

wMid

A manufacturer identifier for the mixer device driver. Manufacturer identifiers are defined in Manufacturer and Product Identifiers.

wPid

A product identifier for the mixer device driver. Product identifiers are defined in Manufacturer and Product Identifiers.

vDriverVersion

Version number of the mixer device driver. The high-order byte is the major version number, and the low-order byte is the minor version number.

szPname

Name of the product. If the mixer device driver supports multiple cards, this string must uniquely and easily identify (potentially to a user) the specific card.

fdwSupport

Various support information for the mixer device driver. No extended support bits are currently defined.

cDestinations

The number of audio line destinations available through the mixer device. All mixer devices must support at least one destination line, so this member cannot be zero. Destination indexes used in the dwDestination member of the MIXERLINE structure range from zero to the value specified in the cDestinations member minus one.

See Also

MIXERLINE


MIXERCONTROL

The MIXERCONTROL structure describes the state and metrics of a single control for an audio line.

typedef struct {

    DWORD cbStruct;

    DWORD dwControlID;

    DWORD dwControlType;

    DWORD fdwControl;

    DWORD cMultipleItems;

    CHAR  szShortName[MIXER_SHORT_NAME_CHARS];

    CHAR  szName[MIXER_LONG_NAME_CHARS];

    union {

        struct {

            LONG lMinimum;

            LONG lMaximum;

        };

        struct {

            DWORD dwMinimum;

            DWORD dwMaximum;

        };

        DWORD dwReserved[6];

    } Bounds;

    union {

        DWORD cSteps;

        DWORD cbCustomData;

        DWORD dwReserved[6];

    } Metrics;

} MIXERCONTROL, *PMIXERCONTROL, FAR *LPMIXERCONTROL;

Members

cbStruct

Size, in bytes, of the MIXERCONTROL structure.

dwControlID

Audio mixer-defined identifier that uniquely refers to the control described by the MIXERCONTROL structure. This identifier can be in any format supported by the mixer device. An application should use this identifier only as an abstract handle. No two controls for a single mixer device can ever have the same control identifier.

dwControlType

Class of the control for which the identifier is specified in dwControlID. An application must use this information to display the appropriate control for input from the user. An application can also display tailored graphics based on the control class or search for a particular control class on a specific line. If an application does not know about a control class, this control must be ignored. There are eight control class classifications, each with one or more standard control types:

MIXERCONTROL_CT_CLASS_CUSTOM

MIXERCONTROL_CONTROLTYPE_CUSTOM

MIXERCONTROL_CT_CLASS_FADER

MIXERCONTROL_CONTROLTYPE_BASS
MIXERCONTROL_CONTROLTYPE_EQUALIZER
MIXERCONTROL_CONTROLTYPE_FADER
MIXERCONTROL_CONTROLTYPE_TREBLE
MIXERCONTROL_CONTROLTYPE_VOLUME

MIXERCONTROL_CT_CLASS_LIST

MIXERCONTROL_CONTROLTYPE_MIXER
MIXERCONTROL_CONTROLTYPE_MULTIPLESELECT
MIXERCONTROL_CONTROLTYPE_MUX
MIXERCONTROL_CONTROLTYPE_SINGLESELECT

MIXERCONTROL_CT_CLASS_METER

MIXERCONTROL_CONTROLTYPE_BOOLEANMETER
MIXERCONTROL_CONTROLTYPE_PEAKMETER
MIXERCONTROL_CONTROLTYPE_SIGNEDMETER
MIXERCONTROL_CONTROLTYPE_UNSIGNEDMETER

MIXERCONTROL_CT_CLASS_NUMBER

MIXERCONTROL_CONTROLTYPE_DECIBELS
MIXERCONTROL_CONTROLTYPE_PERCENT
MIXERCONTROL_CONTROLTYPE_SIGNED
MIXERCONTROL_CONTROLTYPE_UNSIGNED

MIXERCONTROL_CT_CLASS_SLIDER

MIXERCONTROL_CONTROLTYPE_PAN
MIXERCONTROL_CONTROLTYPE_QSOUNDPAN
MIXERCONTROL_CONTROLTYPE_SLIDER

MIXERCONTROL_CT_CLASS_SWITCH

MIXERCONTROL_CONTROLTYPE_BOOLEAN
MIXERCONTROL_CONTROLTYPE_BUTTON
MIXERCONTROL_CONTROLTYPE_LOUDNESS
MIXERCONTROL_CONTROLTYPE_MONO
MIXERCONTROL_CONTROLTYPE_MUTE
MIXERCONTROL_CONTROLTYPE_ONOFF
MIXERCONTROL_CONTROLTYPE_STEREOENH

MIXERCONTROL_CT_CLASS_TIME

MIXERCONTROL_CONTROLTYPE_MICROTIME
MIXERCONTROL_CONTROLTYPE_MILLITIME

fdwControl

Status and support flags for the audio line control. The following values are defined:

MIXERCONTROL_CONTROLF_DISABLED

The control is disabled, perhaps due to other settings for the mixer hardware, and cannot be used. An application can read current settings from a disabled control, but it cannot apply settings.

MIXERCONTROL_CONTROLF_MULTIPLE

The control has two or more settings per channel. An equalizer, for example, requires this flag because each frequency band can be set to a different value. An equalizer that affects both channels of a stereo line in a uniform fashion will also specify the MIXERCONTROL_CONTROLF_UNIFORM flag.

MIXERCONTROL_CONTROLF_UNIFORM

The control acts on all channels of a multichannel line in a uniform fashion. For example, a control that mutes both channels of a stereo line would set this flag. Most MIXERCONTROL_CONTROLTYPE_MUX and MIXERCONTROL_CONTROLTYPE_MIXER controls also specify the MIXERCONTROL_CONTROLF_UNIFORM flag.

cMultipleItems

Number of items per channel that make up a MIXERCONTROL_CONTROLF_MULTIPLE control. This number is always two or greater for multiple-item controls. If the control is not a multiple-item control, do not use this member; it will be zero.

szShortName

Short string that describes the audio line control specified by dwControlID. This description should be appropriate to use as a concise label for the control.

szName

String that describes the audio line control specified by dwControlID. This description should be appropriate to use as a complete description for the control.

Bounds

Union of boundary types.

lMinimum

Minimum signed value for a control that has a signed boundary nature. This member cannot be used in conjunction with dwMinimun.

lMaximum

Maximum signed value for a control that has a signed boundary nature. This member cannot be used in conjunction with dwMaximun.

dwMinimum

Minimum unsigned value for a control that has an unsigned boundary nature. This member cannot be used in conjunction with lMinimun.

dwMaximum

Maximum unsigned value for a control that has an unsigned boundary nature. This member cannot be used in conjunction with lMaximum.

Metrics

Union of boundary metrics.

cSteps

Number of discrete ranges within the union specified for a control specified by the Bounds member. This member overlaps with the other members of the Metrics structure member and cannot be used in conjunction with those members.

cbCustomData

Size, in bytes, required to contain the state of a custom control class. This member is appropriate only for the MIXERCONTROL_CONTROLTYPE_CUSTOM control class.

To determine if the dwMinimum, dwMaximum, lMinimum, lMaximum, cSteps, and cbCustomData members are appropriate for a control class, see Control Types.

The calling application does not need to initialize any members of this structure because the MIXERCONTROL structure is passed to the mixerGetLineControls function as a receiving buffer that is referenced and described by the MIXERLINECONTROLS structure. When mixerGetLineControls returns, the cbStruct member contains the actual size of the information returned by the mixer device. The returned information will not exceed the requested size, nor will it be smaller than the MIXERCONTROL structure.

dwReserved

Reserved; do not use.

See Also

mixerGetLineControls, MIXERLINECONTROLS


MIXERCONTROLDETAILS

The MIXERCONTROLDETAILS structure refers to control-detail structures, retrieving or setting state information of an audio mixer control. All members of this structure must be initialized before calling the mixerGetControlDetails and mixerSetControlDetails functions.

typedef struct {

    DWORD cbStruct;

    DWORD dwControlID;

    DWORD cChannels;

    union {

        HWND  hwndOwner;

        DWORD cMultipleItems;

    };

    DWORD  cbDetails;

    LPVOID paDetails;

} MIXERCONTROLDETAILS;

Members

cbStruct

Size, in bytes, of the MIXERCONTROLDETAILS structure. The size must be large enough to contain the base MIXERCONTROLDETAILS structure. When mixerGetControlDetails returns, this member contains the actual size of the information returned. The returned information will not exceed the requested size, nor will it be smaller than the base MIXERCONTROLDETAILS structure.

dwControlID

Control identifier on which to get or set properties.

cChannels

Number of channels on which to get or set control properties. The following values are defined:

0

Use this value when the control is a MIXERCONTROL_CONTROLTYPE_CUSTOM control.

1

Use this value when the control is a MIXERCONTROL_CONTROLF_UNIFORM control or when an application needs to get and set all channels as if they were uniform.

MIXERLINE.cChannels

Use this value when the properties for the control are expected on all channels for a line.

An application cannot specify a value that falls between 1 and the number of channels for the audio line. For example, specifying 2 or 3 for a four-channel line is not valid. This member cannot be 0 for noncustom control types.

hwndOwner

Handle of the window that owns a custom dialog box for a mixer control. This member is used when the MIXER_SETCONTROLDETAILSF_CUSTOM flag is specified in the mixerSetControlDetails function.

cMultipleItems

Number of multiple items per channel on which to get or set properties. The following values are defined:

0

Use this value for all controls except for a MIXERCONTROL_CONTROLF_MULTIPLE or a MIXERCONTROL_CONTROLTYPE_CUSTOM control.

MIXERCONTROL cMultipleItems member.

Use this value when the control class is MIXERCONTROL_CONTROLF_MULTIPLE.

MIXERCONTROLDETAILS hwndOwner member.

Use this value when the control is a MIXERCONTROL_CONTROLTYPE_CUSTOM control and the MIXER_SETCONTROLDETAILSF_CUSTOM flag is specified for the mixerSetControlDetails function. In this case, the hwndOwner member overlaps with cMultipleItems, providing the value of the window handle.

When using a MIXERCONTROL_CONTROLTYPE_CUSTOM control without the MIXERCONTROL_CONTROLTYPE_CUSTOM flag, specify zero for this member.

An application cannot specify any value other than the value specified in the cMultipleItems member of the MIXERCONTROL structure for a MIXERCONTROL_CONTROLF_MULTIPLE control.

cbDetails

Size, in bytes, of one of the following details structures being used:

MIXERCONTROLDETAILS_BOOLEAN

Boolean value for an audio line control.

MIXERCONTROLDETAILS_LISTTEXT

List text buffer for an audio line control. For information about the appropriate details structure for a specific control, see Control Types.

MIXERCONTROLDETAILS_SIGNED

Signed value for an audio line control.

MIXERCONTROLDETAILS_UNSIGNED

Unsigned value for an audio line control.

If the control is a MIXERCONTROL_CONTROLTYPE_CUSTOM control, this member must be equal to the cbCustomData member of the MIXERCONTROL structure.

paDetails

Address of an array of one or more structures in which properties for the specified control are retrieved or set. For MIXERCONTROL_CONTROLF_MULTIPLE controls, the size of this buffer should be the product of the cChannels, cMultipleItems and cbDetails members of the MIXERCONTROLDETAILS structure. For controls other than MIXERCONTROL_CONTROLF_MULTIPLE types, the size of this buffer is the product of the cChannels and cbDetails members of the MIXERCONTROLDETAILS structure.

For controls that are MIXERCONTROL_CONTROLF_MULTIPLE types, the array can be treated as a two-dimensional array that is channel major. That is, all multiple items for the left channel are given, then all multiple items for the right channel, and so on.

For controls other than MIXERCONTROL_CONTROLF_MULTIPLE types, each element index is equivalent to the zero-based channel that it affects. That is, paDetails[0] is for the left channel and paDetails[1] is for the right channel.

If the control is a MIXERCONTROL_CONTROLTYPE_CUSTOM control, this member must point to a buffer that is at least large enough to contain the size, in bytes, specified by the cbCustomData member of the MIXERCONTROL structure.

See Also

MIXERCONTROL, mixerGetControlDetails, mixerSetControlDetails


MIXERCONTROLDETAILS_BOOLEAN

The MIXERCONTROLDETAILS_BOOLEAN structure retrieves and sets Boolean control properties for an audio mixer control.

typedef struct {

    LONG fValue;

} MIXERCONTROLDETAILS_BOOLEAN;

Members

fValue

Boolean value for a single item or channel. This value is assumed to be zero for a FALSE state (such as off or disabled), and nonzero for a TRUE state (such as on or enabled).

Remarks

The following standard control types use this structure for retrieving and setting properties.

Meter controls:

MIXERCONTROL_CONTROLTYPE_BOOLEANMETER

Switch controls:

MIXERCONTROL_CONTROLTYPE_BOOLEAN
MIXERCONTROL_CONTROLTYPE_BUTTON
MIXERCONTROL_CONTROLTYPE_LOUDNESS
MIXERCONTROL_CONTROLTYPE_MONO
MIXERCONTROL_CONTROLTYPE_MUTE
MIXERCONTROL_CONTROLTYPE_ONOFF
MIXERCONTROL_CONTROLTYPE_STEREOENH

List controls:

MIXERCONTROL_CONTROLTYPE_MIXER
MIXERCONTROL_CONTROLTYPE_MULTIPLESELECT
MIXERCONTROL_CONTROLTYPE_MUX
MIXERCONTROL_CONTROLTYPE_SINGLESELECT


MIXERCONTROLDETAILS_LISTTEXT

The MIXERCONTROLDETAILS_LISTTEXT structure retrieves list text, label text, and/or band-range information for multiple-item controls. This structure is used when the MIXER_GETCONTROLDETAILSF_LISTTEXT flag is specified in the mixerGetControlDetails function.

typedef struct {

    DWORD dwParam1;

    DWORD dwParam2;

    CHAR  szName[MIXER_LONG_NAME_CHARS];

} MIXERCONTROLDETAILS_LISTTEXT;

Members

dwParam1 and dwParam2

Control class-specific values. The following control types are listed with their corresponding values:

EQUALIZER

MIXERCONTROL.Bounds dwMinimum member.

MIXER and MUX

MIXERLINE dwLineID member.

MULTIPLESELECT and SINGLESELECT

Undefined; must be zero

szName

Name describing a single item in a multiple-item control. This text can be used as a label or item text, depending on the control class.

Remarks

The following standard control types use this structure for retrieving the item text descriptions on multiple-item controls:

Fader control:

MIXERCONTROL_CONTROLTYPE_EQUALIZER

List controls:

MIXERCONTROL_CONTROLTYPE_MIXER
MIXERCONTROL_CONTROLTYPE_MULTIPLESELECT
MIXERCONTROL_CONTROLTYPE_MUX
MIXERCONTROL_CONTROLTYPE_SINGLESELECT

See Also

mixerGetControlDetails


MIXERCONTROLDETAILS_SIGNED

The MIXERCONTROLDETAILS_SIGNED structure retrieves and sets signed type control properties for an audio mixer control.

typedef struct {

    LONG lValue;

} MIXERCONTROLDETAILS_SIGNED;

Members

lValue

Signed integer value for a single item or channel. This value must be inclusively within the bounds given in the Bounds member of this structure for signed integer controls.

Remarks

The following standard control types use this structure for retrieving and setting properties:

Meter controls:

MIXERCONTROL_CONTROLTYPE_PEAKMETER
MIXERCONTROL_CONTROLTYPE_SIGNEDMETER

Member controls:

MIXERCONTROL_CONTROLTYPE_SIGNED

Number controls:

MIXERCONTROL_CONTROLTYPE_DECIBELS

Slider controls:

MIXERCONTROL_CONTROLTYPE_PAN
MIXERCONTROL_CONTROLTYPE_QSOUNDPAN
MIXERCONTROL_CONTROLTYPE_SLIDER


MIXERCONTROLDETAILS_UNSIGNED

The MIXERCONTROLDETAILS_UNSIGNED structure retrieves and sets unsigned type control properties for an audio mixer control.

typedef struct {

    DWORD dwValue;

} MIXERCONTROLDETAILS_UNSIGNED;

Members

dwValue

Unsigned integer value for a single item or channel. This value must be inclusively within the bounds given in the Bounds structure member of the MIXERCONTROL structure for unsigned integer controls.

Remarks

The following standard control types use this structure for retrieving and setting properties:

Meter control:

MIXERCONTROL_CONTROLTYPE_UNSIGNEDMETER

Number control:

MIXERCONTROL_CONTROLTYPE_UNSIGNED

Fader controls:

MIXERCONTROL_CONTROLTYPE_BASS
MIXERCONTROL_CONTROLTYPE_EQUALIZER
MIXERCONTROL_CONTROLTYPE_FADER
MIXERCONTROL_CONTROLTYPE_TREBLE
MIXERCONTROL_CONTROLTYPE_VOLUME

Time controls:

MIXERCONTROL_CONTROLTYPE_MICROTIME
MIXERCONTROL_CONTROLTYPE_MILLITIME
MIXERCONTROL_CONTROLTYPE_PERCENT

See Also

MIXERCONTROL


MIXERLINE

The MIXERLINE structure describes the state and metrics of an audio line.

typedef struct {

    DWORD cbStruct;

    DWORD dwDestination;

    DWORD dwSource;

    DWORD dwLineID;

    DWORD fdwLine;

    DWORD dwUser;

    DWORD dwComponentType;

    DWORD cChannels;

    DWORD cConnections;

    DWORD cControls;

    CHAR  szShortName[MIXER_SHORT_NAME_CHARS];

    CHAR  szName[MIXER_LONG_NAME_CHARS];

    struct {

        DWORD     dwType;

        DWORD     dwDeviceID;

        WORD      wMid;

        WORD      wPid;

        MMVERSION vDriverVersion;

        CHAR      szPname[MAXPNAMELEN];

    } Target;

} MIXERLINE;

Members

cbStruct

Size, in bytes, of the MIXERLINE structure. This member must be initialized before calling the mixerGetLineInfo function. The size specified in this member must be large enough to contain the MIXERLINE structure. When mixerGetLineInfo returns, this member contains the actual size of the information returned. The returned information will not exceed the requested size.

dwDestination

Destination line index. This member ranges from zero to one less than the value specified in the cDestinations member of the MIXERCAPS structure retrieved by the mixerGetDevCaps function. When the mixerGetLineInfo function is called with the MIXER_GETLINEINFOF_DESTINATION flag, properties for the destination line are returned. (The dwSource member must be set to zero in this case.) When called with the MIXER_GETLINEINFOF_SOURCE flag, the properties for the source given by the dwSource member that is associated with the dwDestination member are returned.

dwSource

Index for the audio source line associated with the dwDestination member. That is, this member specifies the nth audio source line associated with the specified audio destination line. This member is not used for destination lines and must be set to zero when MIXER_GETLINEINFOF_DESTINATION is specified in the mixerGetLineInfo function. When the MIXER_GETLINEINFOF_SOURCE flag is specified, this member ranges from zero to one less than the value specified in the cConnections member for the audio destination line given in the dwDestination member.

dwLineID

An identifier defined by the mixer device that uniquely refers to the audio line described by the MIXERLINE structure. This identifier is unique for each mixer device and can be in any format. An application should use this identifier only as an abstract handle.

fdwLine

Status and support flags for the audio line. This member is always returned to the application and requires no initialization.

MIXERLINE_LINEF_ACTIVE

Audio line is active. An active line indicates that a signal is probably passing through the line.

MIXERLINE_LINEF_DISCONNECTED

Audio line is disconnected. A disconnected line’s associated controls can still be modified, but the changes have no effect until the line is connected.

MIXERLINE_LINEF_SOURCE

Audio line is an audio source line associated with a single audio destination line. If this flag is not set, this line is an audio destination line associated with zero or more audio source lines.

If an application is not using a waveform-audio output device, the audio line associated with that device would not be active (that is, the MIXERLINE_LINEF_ACTIVE flag would not be set). If the waveform-audio output device is opened, then the audio line is considered active and the MIXERLINE_LINEF_ACTIVE flag will be set. A paused or starved waveform-audio output device is still considered active. In other words, if the waveform-audio output device is opened by an application regardless of whether data is being played, the associated audio line is considered active. If a line cannot be strictly defined as active, the mixer device will always set the MIXERLINE_LINEF_ACTIVE flag.

dwUser

Instance data defined by the audio device for the line. This member is intended for custom mixer applications designed specifically for the mixer device returning this information. Other applications should ignore this data.

dwComponentType

Component type for this audio line. An application can use this information to display tailored graphics or to search for a particular component. If an application does not use component types, this member should be ignored. This member can be one of the following values:

MIXERLINE_COMPONENTTYPE_DST_DIGITAL

Audio line is a digital destination (for example, digital input to a DAT or CD audio device).

MIXERLINE_COMPONENTTYPE_DST_HEADPHONES

Audio line is an adjustable (gain and/or attenuation) destination intended to drive headphones. Most audio cards use the same audio destination line for speakers and headphones, in which case the mixer device simply uses the MIXERLINE_COMPONENTTYPE_DST_SPEAKERS type.

MIXERLINE_COMPONENTTYPE_DST_LINE

Audio line is a line level destination (for example, line level input from a CD audio device) that will be the final recording source for the analog-to-digital converter (ADC). Because most audio cards for personal computers provide some sort of gain for the recording audio source line, the mixer device will use the MIXERLINE_COMPONENTTYPE_DST_WAVEIN type.

MIXERLINE_COMPONENTTYPE_DST_MONITOR

Audio line is a destination used for a monitor.

MIXERLINE_COMPONENTTYPE_DST_SPEAKERS

Audio line is an adjustable (gain and/or attenuation) destination intended to drive speakers. This is the typical component type for the audio output of audio cards for personal computers.

MIXERLINE_COMPONENTTYPE_DST_TELEPHONE

Audio line is a destination that will be routed to a telephone line.

MIXERLINE_COMPONENTTYPE_DST_UNDEFINED

Audio line is a destination that cannot be defined by one of the standard component types. A mixer device is required to use this component type for line component types that have not been defined by Microsoft Corporation.

MIXERLINE_COMPONENTTYPE_DST_VOICEIN

Audio line is a destination that will be the final recording source for voice input. This component type is exactly like MIXERLINE_COMPONENTTYPE_DST_WAVEIN but is intended specifically for settings used during voice recording/recognition. Support for this line is optional for a mixer device. Many mixer devices provide only MIXERLINE_COMPONENTTYPE_DST_WAVEIN.

MIXERLINE_COMPONENTTYPE_DST_WAVEIN

Audio line is a destination that will be the final recording source for the waveform-audio input (ADC). This line typically provides some sort of gain or attenuation. This is the typical component type for the recording line of most audio cards for personal computers.

MIXERLINE_COMPONENTTYPE_SRC_ANALOG

Audio line is an analog source (for example, analog output from a video-cassette tape).

MIXERLINE_COMPONENTTYPE_SRC_AUXILIARY

Audio line is a source originating from the auxiliary audio line. This line type is intended as a source with gain or attenuation that can be routed to the MIXERLINE_COMPONENTTYPE_DST_SPEAKERS destination and/or recorded from the MIXERLINE_COMPONENTTYPE_DST_WAVEIN destination.

MIXERLINE_COMPONENTTYPE_SRC_COMPACTDISC

Audio line is a source originating from the output of an internal audio CD. This component type is provided for audio cards that provide an audio source line intended to be connected to an audio CD (or CD-ROM playing an audio CD).

MIXERLINE_COMPONENTTYPE_SRC_DIGITAL

Audio line is a digital source (for example, digital output from a DAT or audio CD).

MIXERLINE_COMPONENTTYPE_SRC_LINE

Audio line is a line-level source (for example, line-level input from an external stereo) that can be used as an optional recording source. Because most audio cards for personal computers provide some sort of gain for the recording source line, the mixer device will use the MIXERLINE_COMPONENTTYPE_SRC_AUXILIARY type.

MIXERLINE_COMPONENTTYPE_SRC_MICROPHONE

Audio line is a microphone recording source. Most audio cards for personal computers provide at least two types of recording sources: an auxiliary audio line and microphone input. A microphone audio line typically provides some sort of gain. Audio cards that use a single input for use with a microphone or auxiliary audio line should use the MIXERLINE_COMPONENTTYPE_SRC_MICROPHONE component type.

MIXERLINE_COMPONENTTYPE_SRC_PCSPEAKER

Audio line is a source originating from personal computer speaker. Several audio cards for personal computers provide the ability to mix what would typically be played on the internal speaker with the output of an audio card. Some audio cards support the ability to use this output as a recording source.

MIXERLINE_COMPONENTTYPE_SRC_SYNTHESIZER

Audio line is a source originating from the output of an internal synthesizer. Most audio cards for personal computers provide some sort of MIDI synthesizer (for example, an Adlib®-compatible or OPL/3 FM synthesizer).

MIXERLINE_COMPONENTTYPE_SRC_TELEPHONE

Audio line is a source originating from an incoming telephone line.

MIXERLINE_COMPONENTTYPE_SRC_UNDEFINED

Audio line is a source that cannot be defined by one of the standard component types. A mixer device is required to use this component type for line component types that have not been defined by Microsoft Corporation.

MIXERLINE_COMPONENTTYPE_SRC_WAVEOUT

Audio line is a source originating from the waveform-audio output digital-to-analog converter (DAC). Most audio cards for personal computers provide this component type as a source to the MIXERLINE_COMPONENTTYPE_DST_SPEAKERS destination. Some cards also allow this source to be routed to the MIXERLINE_COMPONENTTYPE_DST_WAVEIN destination.

cChannels

Maximum number of separate channels that can be manipulated independently for the audio line. The minimum value for this field is 1 because a line must have at least one channel. Most modern audio cards for personal computers are stereo devices; for them, the value of this member is 2.

Channel 1 is assumed to be the left channel; channel 2 is assumed to be the right channel. A multichannel line might have one or more uniform controls (controls that affect all channels of a line uniformly) associated with it.

cConnections

Number of connections that are associated with the audio line. This member is used only for audio destination lines and specifies the number of audio source lines that are associated with it. This member is always zero for source lines and for destination lines that do not have any audio source lines associated with them.

cControls

Number of controls associated with the audio line. This value can be zero. If no controls are associated with the line, the line is likely to be a source that might be selected in a MIXERCONTROL_CONTROLTYPE_MUX or MIXERCONTROL_CONTROLTYPE_MIXER but allows no manipulation of the signal.

szShortName

Short string that describes the audio mixer line specified in the dwLineID member. This description should be appropriate as a concise label for the line.

szName

String that describes the audio mixer line specified in the dwLineID member. This description should be appropriate as a complete description for the line.

Target

Target media information.

dwType

Target media device type associated with the audio line described in the MIXERLINE structure. An application must ignore target information for media device types it does not use. The following values are defined:

MIXERLINE_TARGETTYPE_AUX

The audio line described by the MIXERLINE structure is strictly bound to the auxiliary device detailed in the remaining members of the Target structure member of the MIXERLINE structure.

MIXERLINE_TARGETTYPE_MIDIIN

The audio line described by the MIXERLINE structure is strictly bound to the MIDI input device detailed in the remaining members of the Target structure member of the MIXERLINE structure.

MIXERLINE_TARGETTYPE_MIDIOUT

The audio line described by the MIXERLINE structure is strictly bound to the MIDI output device detailed in the remaining members of the Target structure member of the MIXERLINE structure.

MIXERLINE_TARGETTYPE_UNDEFINED

The audio line described by the MIXERLINE structure is not strictly bound to a defined media type. All remaining Target structure members of the MIXERLINE structure should be ignored. An application cannot use the MIXERLINE_TARGETTYPE_UNDEFINED target type when calling the mixerGetLineInfo function with the MIXER_GETLINEINFOF_TARGETTYPE flag.

MIXERLINE_TARGETTYPE_WAVEIN

The audio line described by the MIXERLINE structure is strictly bound to the waveform-audio input device detailed in the remaining members of the Target structure member of the MIXERLINE structure.

MIXERLINE_TARGETTYPE_WAVEOUT

The audio line described by the MIXERLINE structure is strictly bound to the waveform-audio output device detailed in the remaining members of the Target structure member of the MIXERLINE structure.

dwDeviceID

Current device identifier of the target media device when the dwType member is a target type other than MIXERLINE_TARGETTYPE_UNDEFINED. This identifier is identical to the current media device index of the associated media device. When calling the mixerGetLineInfo function with the MIXER_GETLINEINFOF_TARGETTYPE flag, this member is ignored on input and will be returned to the caller by the audio mixer manager.

wMid

Manufacturer identifier of the target media device when the dwType member is a target type other than MIXERLINE_TARGETTYPE_UNDEFINED. This identifier is identical to the wMid member of the device-capabilities structure for the associated media. Manufacturer identifiers are defined in Manufacturer and Product Identifiers.

wPid

Product identifier of the target media device when the dwType member is a target type other than MIXERLINE_TARGETTYPE_UNDEFINED. This identifier is identical to the wPid member of the device-capabilities structure for the associated media. Product identifiers are defined in Manufacturer and Product Identifiers.

vDriverVersion

Driver version of the target media device when the dwType member is a target type other than MIXERLINE_TARGETTYPE_UNDEFINED. This version is identical to the vDriverVersion member of the device-capabilities structure for the associated media.

szPname

Product name of the target media device when the dwType member is a target type other than MIXERLINE_TARGETTYPE_UNDEFINED. This name is identical to the szPname member of the device-capabilities structure for the associated media.

See Also

MIXERCAPS, mixerGetDevCaps, mixerGetLineInfo


MIXERLINECONTROLS

The MIXERLINECONTROLS structure contains information about the controls of an audio line.

typedef struct {

    DWORD cbStruct;

    DWORD dwLineID;

    union {

        DWORD dwControlID;

        DWORD dwControlType;

    };

    DWORD          cControls;

    DWORD          cbmxctrl;

    LPMIXERCONTROL pamxctrl;

} MIXERLINECONTROLS;

Members

cbStruct

Size, in bytes, of the MIXERLINECONTROLS structure. This member must be initialized before calling the mixerGetLineControls function. The size specified in this member must be large enough to contain the MIXERLINECONTROLS structure. When mixerGetLineControls returns, this member contains the actual size of the information returned. The returned information will not exceed the requested size, nor will it be smaller than the MIXERLINECONTROLS structure.

dwLineID

Line identifier for which controls are being queried. This member is not used if the MIXER_GETLINECONTROLSF_ONEBYID flag is specified for the mixerGetLineControls function, but the mixer device still returns this member in this case. The dwControlID and dwControlType members are not used when MIXER_GETLINECONTROLSF_ALL is specified.

dwControlID

Control identifier of the desired control. This member is used with the MIXER_GETLINECONTROLSF_ONEBYID flag for the mixerGetLineControls function to retrieve the control information of the specified control. Note that the dwLineID member of the MIXERLINECONTROLS structure will be returned by the mixer device and is not required as an input parameter. This member overlaps with the dwControlType member and cannot be used in conjunction with the MIXER_GETLINECONTROLSF_ONEBYTYPE query type.

dwControlType

Class of the desired control. This member is used with the MIXER_GETLINECONTROLSF_ONEBYTYPE flag for the mixerGetLineControls function to retrieve the first control of the specified class on the line specified by the dwLineID member of the MIXERLINECONTROLS structure. This member overlaps with the dwControlID member and cannot be used in conjunction with the MIXER_GETLINECONTROLSF_ONEBYID query type.

cControls

Number of MIXERCONTROL structure elements to retrieve. This member must be initialized by the application before calling the mixerGetLineControls function. This member can be 1 only if MIXER_GETLINECONTROLSF_ONEBYID or MIXER_GETLINECONTROLSF_ONEBYTYPE is specified or the value returned in the cControls member of the MIXERLINE structure returned for an audio line. This member cannot be zero. If an audio line specifies that it has no controls, mixerGetLineControls should not be called.

cbmxctrl

Size, in bytes, of a single MIXERCONTROL structure. The size specified in this member must be at least large enough to contain the base MIXERCONTROL structure. The total size, in bytes, required for the buffer pointed to by the pamxctrl member is the product of the cbmxctrl and cControls members of the MIXERLINECONTROLS structure.

pamxctrl

Address of one or more MIXERCONTROL structures to receive the properties of the requested audio line controls. This member cannot be NULL and must be initialized before calling the mixerGetLineControls function. Each element of the array of controls must be at least large enough to contain a base MIXERCONTROL structure. The cbmxctrl member must specify the size, in bytes, of each element in this array. No initialization of the buffer pointed to by this member is required by the application. All members are filled in by the mixer device (including the cbStruct member of each MIXERCONTROL structure) upon returning successfully.

See Also

MIXERCONTROL, MIXERLINE, mixerGetLineControls


MMCKINFO

The MMCKINFO structure contains information about a chunk in a RIFF file.

typedef struct {

    FOURCC ckid;

    DWORD  cksize;

    FOURCC fccType;

    DWORD  dwDataOffset;

    DWORD  dwFlags;

} MMCKINFO;

Members

ckid

Chunk identifier.

cksize

Size, in bytes, of the data member of the chunk. The size of the data member does not include the 4-byte chunk identifier, the 4-byte chunk size, or the optional pad byte at the end of the data member.

fccType

Form type for “RIFF” chunks or the list type for “LIST” chunks.

dwDataOffset

File offset of the beginning of the chunk’s data member, relative to the beginning of the file.

dwFlags

Flags specifying additional information about the chunk. It can be zero or the following flag:

MMIO_DIRTY

The length of the chunk might have changed and should be updated by the mmioAscend function. This flag is set when a chunk is created by using the mmioCreateChunk function.

See Also

mmioAscend, mmioCreateChunk


MMIOINFO

The MMIOINFO structure contains the current state of a file opened by using the mmioOpen function.

typedef struct {

    DWORD      dwFlags;

    FOURCC     fccIOProc;

    LPMMIOPROC pIOProc;

    UINT       wErrorRet;

    HTASK      hTask;

    LONG       cchBuffer;

    HPSTR      pchBuffer;

    HPSTR      pchNext;

    HPSTR      pchEndRead;

    HPSTR      pchEndWrite;

    LONG       lBufOffset;

    LONG       lDiskOffset;

    DWORD      adwInfo[4];

    DWORD      dwReserved1;

    DWORD      dwReserved2;

    HMMIO      hmmio;

} MMIOINFO;

Members

dwFlags

Flags specifying how a file was opened. The following values are defined:

MMIO_ALLOCBUF

File’s I/O buffer was allocated by the mmioOpen or mmioSetBuffer function.

MMIO_CREATE

The mmioOpen function was directed to create the file (or truncate it to zero length if it already existed).

MMIO_DIRTY

The I/O buffer has been modified.

MMIO_EXIST

Checks for the existence of the file.

MMIO_GETTEMP

A temporary name was retrieved by the mmioOpen function.

MMIO_PARSE

The new file’s path is returned.

The following values may be set when the file is opened in share mode (identified by using the MMIO_SHAREMODE bit mask):

MMIO_COMPAT

File was opened with compatibility mode, allowing any process on a given machine to open the file any number of times.

MMIO_DENYNONE

Other processes are not denied read or write access to the file.

MMIO_DENYREAD

Other processes are denied read access to the file.

MMIO_DENYWRITE

Other processes are denied write access to the file.

MMIO_EXCLUSIVE

Other processes are denied read and write access to the file.

The following values may be set when the file is opened in read/write mode (identified by using the MMIO_RWMODE bit mask):

MMIO_READ

File was opened only for reading.

MMIO_READWRITE

File was opened for reading and writing.

MMIO_WRITE

File was opened only for writing.

fccIOProc

Four-character code identifying the file’s I/O procedure. If the I/O procedure is not an installed I/O procedure, this member is NULL.

pIOProc

Address of file’s IO procedure.

wErrorRet

Extended error value from the mmioOpen function if it returns NULL. This member is not used to return extended error information from any other functions.

hTask

Handle of a local I/O procedure. Media Control Interface (MCI) devices that perform file I/O in the background and need an I/O procedure can locate a local I/O procedure with this handle.

cchBuffer

Size, in bytes, of the file’s I/O buffer. If the file does not have an I/O buffer, this member is zero.

pchBuffer

Address of the file’s I/O buffer. If the file is unbuffered, this member is NULL.

pchNext

Address of the next location in the I/O buffer to be read or written. If no more bytes can be read without calling the mmioAdvance or mmioRead function, this member points to the pchEndRead member. If no more bytes can be written without calling the mmioAdvance or mmioWrite function, this member points to the pchEndWrite member.

pchEndRead

Address of the location that is 1 byte past the last location in the buffer that can be read.

pchEndWrite

Address of the location that is 1 byte past the last location in the buffer that can be written.

lBufOffset

Reserved.

lDiskOffset

Current file position, which is an offset, in bytes, from the beginning of the file. I/O procedures are responsible for maintaining this member.

adwInfo

State information maintained by the I/O procedure. I/O procedures can also use these members to transfer information from the application to the I/O procedure when the application opens a file.

dwReserved1

Reserved.

dwReserved2

Reserved.

hmmio

Handle of the open file, as returned by the mmioOpen function. I/O procedures can use this handle when calling other multimedia file I/O functions.

See Also

mmioAdvance, mmioOpen, mmioRead, mmioSetBuffer, mmioWrite


MMTIME

The MMTIME structure contains timing information for different types of multimedia data.

typedef struct mmtime_tag {

    UINT wType;

    union {

        DWORD ms;

        DWORD sample;

        DWORD cb;

        DWORD ticks;

        struct {

            BYTE hour;

            BYTE min;

            BYTE sec;

            BYTE frame;

            BYTE fps;

            BYTE dummy;

            BYTE pad[2]

        } smpte;

        struct {

            DWORD songptrpos;

        } midi;

    } u;

} MMTIME;

Members

wType

Time format. It can be one of the following values:

TIME_BYTES	Current byte offset from beginning of the file.
TIME_MIDI	MIDI time.
TIME_MS	Time in milliseconds.
TIME_SAMPLES	Number of waveform-audio samples.
TIME_SMPTE	SMPTE (Society of Motion Picture and Television Engineers) time.
TIME_TICKS	Ticks within a MIDI stream.
ms

Number of milliseconds. Used when wType is TIME_MS.

sample

Number of samples. Used when wType is TIME_SAMPLES.

cb

Byte count. Used when wType is TIME_BYTES.

ticks

Ticks in MIDI stream. Used when wType is TIME_TICKS.

smpte

SMPTE time structure. Used when wType is TIME_SMPTE.

songptrpos

Song pointer position.

midi

MIDI time structure. Used when wType is TIME_MIDI.

hour

Hours.

min

Minutes.

sec

Seconds.

frame

Frames.

fps

Frames per second (24, 25, 29 (30 drop), or 30).

dummy

Dummy byte for alignment.

pad

Padding.


PCMWAVEFORMAT

The PCMWAVEFORMAT structure describes the data format for PCM waveform-audio data. This structure has been superseded by the WAVEFORMATEX structure.

typedef struct {

    WAVEFORMAT wf;

    WORD       wBitsPerSample;

} PCMWAVEFORMAT;

Members

wf

A WAVEFORMAT structure containing general information about the format of the data.

wBitsPerSample

Number of bits per sample.

See Also

WAVEFORMAT, WAVEFORMATEX


TIMECAPS

The TIMERCAPS structure contains information about the resolution of the timer.

typedef struct {

    UINT wPeriodMin;

    UINT wPeriodMax;

} TIMECAPS;

Members

wPeriodMin

Minimum supported resolution.

wPeriodMax

Maximum supported resolution.


WAVEFILTER

The WAVEFILTER structure defines a filter for waveform-audio data. Only filter information common to all waveform-audio data filters is included in this structure. For filters that require additional information, this structure is included as the first member in another structure along with the additional information.

typedef struct {

    DWORD cbStruct;

    DWORD dwFilterTag;

    DWORD fdwFilter;

    DWORD dwReserved[5];

} WAVEFILTER;

Members

cbStruct

Size, in bytes, of the WAVEFILTER structure. The size specified in this member must be large enough to contain the base WAVEFILTER structure.

dwFilterTag

Waveform-audio filter type. Filter tags are registered with Microsoft Corporation for various filter algorithms.

fdwFilter

Flags for the dwFilterTag member. The flags defined for this member are universal to all filters. Currently, no flags are defined.

dwReserved

Reserved for system use; should not be examined or modified by an application.


WAVEFORMAT

The WAVEFORMAT structure describes the format of waveform-audio data. Only format information common to all waveform-audio data formats is included in this structure. This structure has been superseded by the WAVEFORMATEX structure.

typedef struct {

    WORD  wFormatTag;

    WORD  nChannels;

    DWORD nSamplesPerSec;

    DWORD nAvgBytesPerSec;

    WORD  nBlockAlign;

} WAVEFORMAT;

Members

wFormatTag

Format type. The following type is defined:

WAVE_FORMAT_PCM

Waveform-audio data is PCM.

nChannels

Number of channels in the waveform-audio data. Mono data uses one channel and stereo data uses two channels.

nSamplesPerSec

Sample rate, in samples per second.

nAvgBytesPerSec

Required average data transfer rate, in bytes per second. For example, 16-bit stereo at 44.1 kHz has an average data rate of 176,400 bytes per second (2 channels  —  2 bytes per sample per channel  —  44,100 samples per second).

nBlockAlign

Block alignment, in bytes. The block alignment is the minimum atomic unit of data. For PCM data, the block alignment is the number of bytes used by a single sample, including data for both channels if the data is stereo. For example, the block alignment for 16-bit stereo PCM is 4 bytes (2 channels  —  2 bytes per sample).

Remarks

For formats that require additional information, this structure is included as a member in another structure along with the additional information.

See Also

WAVEFORMATEX


WAVEFORMATEX

The WAVEFORMATEX structure defines the format of waveform-audio data. Only format information common to all waveform-audio data formats is included in this structure. For formats that require additional information, this structure is included as the first member in another structure, along with the additional information.

typedef struct {

    WORD  wFormatTag;

    WORD  nChannels;

    DWORD nSamplesPerSec;

    DWORD nAvgBytesPerSec;

    WORD  nBlockAlign;

    WORD  wBitsPerSample;

    WORD  cbSize;

} WAVEFORMATEX;

Members

wFormatTag

Waveform-audio format type. Format tags are registered with Microsoft Corporation for many compression algorithms. A complete list of format tags can be found in the MMREG.H header file.

nChannels

Number of channels in the waveform-audio data. Monaural data uses one channel and stereo data uses two channels.

nSamplesPerSec

Sample rate, in samples per second (hertz), that each channel should be played or recorded. If wFormatTag is WAVE_FORMAT_PCM, then common values for nSamplesPerSec are 8.0 kHz, 11.025 kHz, 22.05 kHz, and 44.1 kHz. For non-PCM formats, this member must be computed according to the manufacturer’s specification of the format tag.

nAvgBytesPerSec

Required average data-transfer rate, in bytes per second, for the format tag. If wFormatTag is WAVE_FORMAT_PCM, nAvgBytesPerSec should be equal to the product of nSamplesPerSec and nBlockAlign. For non-PCM formats, this member must be computed according to the manufacturer’s specification of the format tag.

Playback and record software can estimate buffer sizes by using the nAvgBytesPerSec member.

nBlockAlign

Block alignment, in bytes. The block alignment is the minimum atomic unit of data for the wFormatTag format type. If wFormatTag is WAVE_FORMAT_PCM, nBlockAlign should be equal to the product of nChannels and wBitsPerSample divided by 8 (bits per byte). For non-PCM formats, this member must be computed according to the manufacturer’s specification of the format tag.

Playback and record software must process a multiple of nBlockAlign bytes of data at a time. Data written and read from a device must always start at the beginning of a block. For example, it is illegal to start playback of PCM data in the middle of a sample (that is, on a non-block-aligned boundary).

wBitsPerSample

Bits per sample for the wFormatTag format type. If wFormatTag is WAVE_FORMAT_PCM, then wBitsPerSample should be equal to 8 or 16. For non-PCM formats, this member must be set according to the manufacturer’s specification of the format tag. Note that some compression schemes cannot define a value for wBitsPerSample, so this member can be zero.

cbSize

Size, in bytes, of extra format information appended to the end of the WAVEFORMATEX structure. This information can be used by non-PCM formats to store extra attributes for the wFormatTag. If no extra information is required by the wFormatTag, this member must be set to zero. Note that for WAVE_FORMAT_PCM formats (and only WAVE_FORMAT_PCM formats), this member is ignored.

Remarks

An example of a format that uses extra information is the Microsoft Adaptive Delta Pulse Code Modulation (MS-ADPCM) format. The wFormatTag for MS-ADPCM is WAVE_FORMAT_ADPCM. The cbSize member will typically be set to 32. The extra information stored for WAVE_FORMAT_ADPCM is coefficient pairs required for encoding and decoding the waveform-audio data.


WAVEHDR

The WAVEHDR structure defines the header used to identify a waveform-audio buffer.

typedef struct {

    LPSTR  lpData;

    DWORD  dwBufferLength;

    DWORD  dwBytesRecorded;

    DWORD  dwUser;

    DWORD  dwFlags;

    DWORD  dwLoops;

    struct wavehdr_tag * lpNext;

    DWORD  reserved;

} WAVEHDR;

Members

lpData

Address of the waveform buffer.

dwBufferLength

Length, in bytes, of the buffer.

dwBytesRecorded

When the header is used in input, this member specifies how much data is in the buffer.

dwUser

User data.

dwFlags

Flags supplying information about the buffer. The following values are defined:

WHDR_BEGINLOOP

This buffer is the first buffer in a loop.  This flag is used only with output buffers.

WHDR_DONE

Set by the device driver to indicate that it is finished with the buffer and is returning it to the application.

WHDR_ENDLOOP

This buffer is the last buffer in a loop.  This flag is used only with output buffers.

WHDR_INQUEUE

Set by Windows to indicate that the buffer is queued for playback.

WHDR_PREPARED

Set by Windows to indicate that the buffer has been prepared with the waveInPrepareHeader or waveOutPrepareHeader function.

dwLoops

Number of times to play the loop. This member is used only with output buffers.

wavehdr_tag

Reserved.

reserved

Reserved.

Remarks

Use the WHDR_BEGINLOOP and WHDR_ENDLOOP flags in the dwFlags member to specify the beginning and ending data blocks for looping. To loop on a single block, specify both flags for the same block. Use the dwLoops member in the WAVEHDR structure for the first block in the loop to specify the number of times to play the loop.

The lpData, dwBufferLength, and dwFlags members must be set before calling the waveInPrepareHeader or waveOutPrepareHeader function. (For either function, the dwFlags member must be set to zero.)

See Also

waveInPrepareHeader, waveOutPrepareHeader


WAVEINCAPS

The WAVEINCAPS structure describes the capabilities of a waveform-audio input device.

typedef struct {

    WORD      wMid;

    WORD      wPid;

    MMVERSION vDriverVersion;

    CHAR      szPname[MAXPNAMELEN];

    DWORD     dwFormats;

    WORD      wChannels;

    WORD      wReserved1;

} WAVEINCAPS;

Members

wMid

Manufacturer identifier for the device driver for the waveform-audio input device. Manufacturer identifiers are defined in Manufacturer and Product Identifiers.

wPid

Product identifier for the waveform-audio input device. Product identifiers are defined in Manufacturer and Product Identifiers.

vDriverVersion

Version number of the device driver for the waveform-audio input device. The high-order byte is the major version number, and the low-order byte is the minor version number.

szPname

Product name in a null-terminated string.

dwFormats

Standard formats that are supported. Can be a combination of the following:

WAVE_FORMAT_1M08	11.025 kHz, mono, 8-bit
WAVE_FORMAT_1M16	11.025 kHz, mono, 16-bit
WAVE_FORMAT_1S08	11.025 kHz, stereo, 8-bit
WAVE_FORMAT_1S16	11.025 kHz, stereo, 16-bit
WAVE_FORMAT_2M08	22.05 kHz, mono, 8-bit
WAVE_FORMAT_2M16	22.05 kHz, mono, 16-bit
WAVE_FORMAT_2S08	22.05 kHz, stereo, 8-bit
WAVE_FORMAT_2S16	22.05 kHz, stereo, 16-bit
WAVE_FORMAT_4M08	44.1 kHz, mono, 8-bit
WAVE_FORMAT_4M16	44.1 kHz, mono, 16-bit
WAVE_FORMAT_4S08	44.1 kHz, stereo, 8-bit
WAVE_FORMAT_4S16	44.1 kHz, stereo, 16-bit
wChannels

Number specifying whether the device supports mono (1) or stereo (2) input.

wReserved1

Padding.


WAVEOUTCAPS

The WAVEOUTCAPS structure describes the capabilities of a waveform-audio output device.

typedef struct {

    WORD      wMid;

    WORD      wPid;

    MMVERSION vDriverVersion;

    CHAR      szPname[MAXPNAMELEN];

    DWORD     dwFormats;

    WORD      wChannels;

    WORD      wReserved1;

    DWORD     dwSupport;

} WAVEOUTCAPS;

Members

wMid

Manufacturer identifier for the device driver for the device. Manufacturer identifiers are defined in Manufacturer and Product Identifiers.

wPid

Product identifier for the device. Product identifiers are defined in Manufacturer and Product Identifiers.

vDriverVersion

Version number of the device driver for the device. The high-order byte is the major version number, and the low-order byte is the minor version number.

szPname

Product name in a null-terminated string.

dwFormats

Standard formats that are supported. Can be a combination of the following:

WAVE_FORMAT_1M08	11.025 kHz, mono, 8-bit
WAVE_FORMAT_1M16	11.025 kHz, mono, 16-bit
WAVE_FORMAT_1S08	11.025 kHz, stereo, 8-bit
WAVE_FORMAT_1S16	11.025 kHz, stereo, 16-bit
WAVE_FORMAT_2M08	22.05 kHz, mono, 8-bit
WAVE_FORMAT_2M16	22.05 kHz, mono, 16-bit
WAVE_FORMAT_2S08	22.05 kHz, stereo, 8-bit
WAVE_FORMAT_2S16	22.05 kHz, stereo, 16-bit
WAVE_FORMAT_4M08	44.1 kHz, mono, 8-bit
WAVE_FORMAT_4M16	44.1 kHz, mono, 16-bit
WAVE_FORMAT_4S08	44.1 kHz, stereo, 8-bit
WAVE_FORMAT_4S16	44.1 kHz, stereo, 16-bit
wChannels

Number specifying whether the device supports mono (1) or stereo (2) output.

wReserved1

Packing.

dwSupport

Optional functionality supported by the device. The following values are defined:

WAVECAPS_LRVOLUME	Supports separate left and right volume control.
WAVECAPS_PITCH	Supports pitch control.
WAVECAPS_PLAYBACKRATE	Supports playback rate control.
WAVECAPS_SYNC	The driver is synchronous and will block while playing a buffer.
WAVECAPS_VOLUME	Supports volume control.
WAVECAPS_SAMPLEACCURATE	Returns sample-accurate position information.
Remarks

If a device supports volume changes, the WAVECAPS_VOLUME flag will be set for the dwSupport member. If a device supports separate volume changes on the left and right channels, both the WAVECAPS_VOLUME and the WAVECAPS_LRVOLUME flags will be set for this member.


KEYARRAY

KEYARRAY specifies a type used to define an array of keys. Each element in the array corresponds to a key-based percussion patch with each of the 16 bits representing one of the 16 MIDI channels. Bits are set for each of the channels that use that particular patch. For example, if the percussion patch for key number 60 is used by physical MIDI channels 9 and 15, element 60 of the array should be set to 0x8200.

typedef WORD KEYARRAY[MIDIPATCHSIZE];


PATCHARRAY

PATCHARRAY is a type used to define an array of MIDI patches. Each element in the array corresponds to a patch with each of the 16 bits representing one of the 16 MIDI channels. Bits are set for each of the channels that use that particular patch. For example, if patch number 0 is used by physical MIDI channels 0 and 8, element 0 of the array should be set to 0x0101.

typedef WORD PATCHARRAY[MIDIPATCHSIZE];


Video Capture

You can easily incorporate video capture capabilities into your application by using the AVICap window class. AVICap provides applications with a simple, message-based interface to access video and waveform-audio acquisition hardware and to control the process of streaming video capture to disk.


About Video Capture

AVICap supports streaming video capture and single-frame capture in real-time. In addition, AVICap provides control of video sources that are Media Control Interface (MCI) devices so the user can control (through an application) the start and stop positions of a video source, and augment the capture operation to include step frame capture.

The windows you create by using the AVICap window class can perform the following tasks:

•	Capture audio and video streams to an audo-video interleaved (AVI) file.

•	Connect and disconnect video and audio input devices dynamically.

•	View a live incoming video signal by using the overlay or preview methods.

•	Specify a file to use when capturing and copy the contents of the capture file to another file.

•	Set the capture rate.

•	Display dialog boxes that control the video source and format.

•	Create, save, and load palettes.

•	Copy images and palettes to the clipboard.

•	Capture and save a single image as a device-independent bitmap (DIB).


Video Capture: A Minimal Approach

Video capture digitizes a stream of video and audio data, and stores it on a hard disk or some other type of persistent storage device. This section describes how to add a simple form of video capture to an application using three statements of code. It also describes how to end or abort a capture session by sending messages to the capture window.

An AVICap capture window handles the details of streaming audio and video capture to AVI files. This frees your application from involvement in the AVI file format, video and audio buffer management, and the low-level access of video and audio device drivers. AVICap provides a flexible interface for applications. You can add video capture to your application, using only the following lines of code:

hWndC = capCreateCaptureWindow ( "My Own Capture Window",

    WS_CHILD | WS_VISIBLE , 0, 0, 160, 120, hwndParent, nID);

SendMessage (hWndC, WM_CAP_DRIVER_CONNECT, 0 /* wIndex */, 0L);

SendMessage (hWndC, WM_CAP_SEQUENCE, 0, 0L);

A macro interface is also available that provides an alternative to using the SendMessage function and improves the readability of an application. The following example uses the macro interface to add video capture to an application.

hWndC = capCreateCaptureWindow (	"My Own Capture Window",

    WS_CHILD | WS_VISIBLE ,	0, 0, 160, 120, hwndParent, nID);

capDriverConnect (hWndC, 0);

capCaptureSequence (hWndC);

After your application creates a capture window of the AVICap window class and connects it to a video driver, the capture window is ready to capture data. At this point, your application can simply send the WM_CAP_SEQUENCE message (or the capCaptureSequence macro) to begin capturing.

Using default settings, WM_CAP_SEQUENCE initiates the capture of video and audio input to a file named CAPTURE.AVI. Capture continues until one of the following events occurs:

•	The user presses the ESC key or a mouse button.

•	Your application stops or aborts capture operation.

•	The disk becomes full.

In an application, you can stop streaming captured data to a file by sending the WM_CAP_STOP (or the capCaptureStop macro) message to a capture window. You can also abort the capture operation by sending the WM_CAP_ABORT message (or the capCaptureAbort macro) to a capture window.


Basic Capture Options

By modifying one or more of the capture parameters defined in the CAPTUREPARMS structure, you can perform the following tasks:

•	Change the frame capture rate.

•	Specify keyboard or mouse control for ending a capture session.

•	Specify a duration for a capture session.


Capture Rate

The capture rate is the number of frames that are captured each second of a capture session. You can retrieve the current capture rate by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). The current capture rate is stored in the dwRequestMicroSecPerFrame member of the CAPTUREPARMS structure. You can set the capture rate by specifying the number of microseconds between successive frames as the value of this member, then sending the updated CAPTUREPARMS structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro). The default value of dwRequestMicroSecPerFrame is 66667, which corresponds to 15 frames per second.


Keys Ending Capture

You can allow the user to abort a capture session by pressing a key or keystroke combination from the keyboard, or by pressing the right or left mouse button. If the user aborts a real-time capture session, the contents of the capture file are discarded. If the user aborts a step-frame capture session, the contents of the capture file up to the point of aborting the capture are saved.

You can retrieve the settings for aborting a capture session by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). The current keystroke setting is stored in the vKeyAbort member of the CAPTUREPARMS structure; the current mouse settings are stored in the fAbortLeftMouse and fAbortRightMouse members. You can set a new key or keystroke combination by specifying the keycode or keycode combination (as in a CTRL or SHIFT key combination) as the value of vKeyAbort, or set the left or right mouse button as the abort key by specifying the fAbortLeftMouse or fAbortRightMouse member. After you set these members, send the updated CAPTUREPARMS structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro). The default value of vKeyAbort is VK_ESCAPE. You must call the RegisterHotKey function before specifying a keystroke that can abort a capture session. The default values of fAbortLeftMouse and fAbortRightMouse are TRUE.


Time Limit

You can limit the duration of a capture operation by using the fLimitEnabled and wTimeLimit members of the CAPTUREPARMS structure. The fLimitEnabled member indicates whether the capture operation is to be timed, while wTimeLimit specifies the maximum duration of the capture operation.

You can retrieve the values for fLimitEnabled and wTimeLimit by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). You can enable a timer for the capture operation by specifying TRUE as the value of fLimitEnabled, or you can set the duration of the capture operation by specifying a value, in seconds, for wTimeLimit. After you set these members, send the updated CAPTUREPARMS structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro). The default value of fLimitEnabled is FALSE.


Capture Windows

Capture windows are conceptually similar to standard controls (such as buttons, list boxes, or scroll bars). Typically, capture windows use the WS_CHILD and WS_VISIBLE window styles.


Creating an AVICap Capture Window

You can create a capture window of the AVICap window class by using the capCreateCaptureWindow function. This function returns a window handle that identifies the capture window and is used by an application to send subsequent messages to the window.

You can create one or more capture windows in an application and connect each capture window to a different capture device.


Connecting a Capture Window to a Capture Driver

You can dynamically connect or disconnect a capture window to a capture driver. You can connect or associate a capture window with a capture driver by using the WM_CAP_DRIVER_CONNECT message (or the capDriverConnect macro). After a capture window and capture driver are connected, you can send device-specific messages to the capture driver associated with a capture window.

If you have more than one capture device installed on a system, you can connect a capture window to a particular video capture device driver by specifying an integer for the wParam parameter of the WM_CAP_DRIVER_CONNECT message. The integer is an index that identifies a video capture driver listed in the registry or in the [drivers] section of the SYSTEM.INI file. Use zero for the first index entry.

You can retrieve the name and version of an installed capture driver by using the the capGetDriverDescription function. Your application can use this function to enumerate the installed capture devices and drivers, so the user can select a capture device to connect to a capture window.

You can retrieve the name of the capture device driver connected to a capture window by using the WM_CAP_DRIVER_GET_NAME message (or the capDriverGetName macro). To retrieve the version of an installed capture driver, use the WM_CAP_DRIVER_GET_VERSION message (or the capDriverGetVersion macro).

You can disconnect a capture window from a capture driver by using the WM_CAP_DRIVER_DISCONNECT message (or the capDriverDisconnect macro).

When an capture window is destroyed, any connected video capture device drivers are automatically disconnected.


Parent-Child Window Interaction

Some system-level messages, such as WM_PALETTECHANGED and WM_QUERYNEWPALETTE, are sent only to top-level and overlapped windows. If a capture window is a child window, its parent must forward these messages.

Similarly, if the parent window changes size, it might need to send notification messages to the capture window. Conversely, if the dimensions of the captured video change, the capture window might need to send notification messages to the parent window. The simplest way to manage this is to always keep the capture window dimensions equal to the size of the captured video stream, notifying the parent whenever these dimensions change.


Capture Window Status

You can retrieve the current status of a capture window by using the WM_CAP_GET_STATUS message (or the capGetStatus macro). This message retrieves a copy of the CAPSTATUS structure with the current values of its members. The CAPSTATUS structure contains information regarding the dimensions of the image, scroll position, and whether overlay or preview of the image is enabled. Because the information represented in CAPSTATUS is dynamic, your application should refresh the contents of the structure whenever the size or format of the captured video stream might have changed (such as after displaying the video format of the capture driver).

Changing the dimensions of the capture window has no effect on the dimensions of the actual captured video stream. The format dialog box displayed by the video capture device driver controls the dimensions of the captured video stream.


Capture and Audio Drivers

A capture driver and the underlying hardware can dictate several aspects of video capture, including acceptable video sources, display options, formats, and compression options. An audio driver specifies the audio format and an optional compression option used with captured audio data.


Capture Driver Capabilities

You can retrieve the hardware capabilities of the currently connected capture driver by using the WM_CAP_DRIVER_GET_CAPS message (or the capDriverGetCaps macro). This message returns the capabilities of the capture driver and underlying hardware in the CAPDRIVERCAPS structure.


Video Dialog Boxes

Each capture driver can provide up to four dialog boxes to control aspects of the video digitization and capture process, and to define compression attributes used in reducing the size of the video data. The contents of these dialog boxes are defined by the video capture driver.

The Video Source dialog box controls the selection of video input channels and parameters affecting the video image being digitized in the frame buffer. This dialog box enumerates the types of signals that connect the video source to the capture card (typically SVHS and composite inputs), and provides controls to change hue, contrast, or saturation. If the dialog box is supported by a video capture driver, you can display and update it by using the WM_CAP_DLG_VIDEOSOURCE message (or the capDlgVideoSource macro).

The Video Format dialog box controls selection of the digitized video frame dimensions and image-depth, and compression options of the captured video. If the dialog box is supported by a video capture driver, you can display and update it by using the WM_CAP_DLG_VIDEOFORMAT message (or the capDlgVideoFormat macro).

The Video Display dialog box controls the appearance of the video on the monitor during capture. The controls in this dialog box have no effect on the digitized video data, but they might affect the presentation of the digitized signal. For example, capture devices that support overlay might allow altering hue and saturation, key color, or alignment of the overlay. If the dialog box is supported by a video capture driver, you can display and update it by using the WM_CAP_DLG_VIDEODISPLAY message (or the capDlgVideoDisplay macro).

The Video Compression dialog box controls the post-capture video compression attributes. If the dialog box is supported by a video capture driver, you can display and update it by using the WM_CAP_DLG_VIDEOCOMPRESSION message (or the capDlgVideoCompression macro).


Preview and Overlay Modes

A capture driver can implement two methods for viewing an incoming video stream: preview mode and overlay mode. If a capture driver implements both methods, the user can choose which method to use.

Preview mode transfers digitized frames from the capture hardware to system memory and then displays the digitized frames in the capture window by using graphics device interface (GDI) functions. Applications might decrease the preview rate when the parent window loses focus, and increase the preview rate when the parent window gains focus. This action improves general system responsiveness because the preview operation is processor intensive.

There are three messages to control the preview operation.

•	Use the WM_CAP_SET_PREVIEW message to enable or disable preview mode by sending the (or the capPreview macro) to a capture window.

•	Use the WM_CAP_SET_PREVIEWRATE message (or the capPreviewRate macro) to set the rate at which frames are displayed in preview mode

•	Use the WM_CAP_SET_SCALE message (or the capPreviewScale macro) to enable or disable scaling of the preview video.

When preview and scaling are both enabled, the captured video frame is stretched to the dimensions of the capture window. Enabling preview mode automatically disables overlay mode.

Overlay mode is a hardware function that displays the contents of the capture buffer on the monitor without using CPU resources. You can enable and disable overlay mode by sending the WM_CAP_SET_OVERLAY message (or the capOverlay macro) to a capture window. Enabling overlay mode automatically disables preview mode.

You can also set the scroll position of the video frame within the client area of the capture window for preview mode or overlay mode by sending the WM_CAP_SET_SCROLL message (or the capSetScrollPos macro) to a capture window.


Video Format

You can retrieve the structure that specifies the video format or the size of that structure by sending the WM_CAP_GET_VIDEOFORMAT message (or the capGetVideoFormat and capGetVideoFormatSize macros) to a capture window. You can set the format of captured video data by sending the WM_CAP_SET_VIDEOFORMAT message (or the capSetVideoFormat macro) to a capture window.


Video Capture Settings

The CAPTUREPARMS structure contains the control parameters for streaming video capture. This structure controls several aspects of the capture process, and allows you to perform the following tasks:

•	Specify the frame rate.

•	Specify the number of allocated video buffers.

•	Disable and enable audio capture.

•	Specify the time interval for the capture.

•	Specify whether an MCI device (VCR or videodisc) is used during capture.

•	Specify keyboard or mouse control for ending streaming.

•	Specify the type of video averaging applied during capture.

You can retrieve the current capture settings within the CAPTUREPARMS structure by sending the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro) to a capture window. You can set one or more current capture settings by updating the appropriate members of the CAPTUREPARMS structure and then sending the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro) and CAPTUREPARMS to a capture window.


Audio Format

You can retrieve the current capture format for audio data or the size of the audio format structure by sending the WM_CAP_GET_AUDIOFORMAT message (or the capGetAudioFormat and capGetAudioFormatSize macros) to a capture window. The default audio capture format is mono, 8-bit, 11 kHz PCM (Pulse Code Modulation). When you retrieve the format by using WM_CAP_GET_AUDIOFORMAT, always use the WAVEFORMATEX structure.

You can set the capture format for audio data by sending the WM_CAP_SET_AUDIOFORMAT message (or the capSetAudioFormat macro) to a capture window. When setting the audio format, you can pass a pointer to a WAVEFORMAT, WAVEFORMATEX, or PCMWAVEFORMAT structure, depending on the specified audio format.


Capture File and Buffers

This section describes tips and options for using the capture file and for specifying buffers for the capture operation.

•	Capture Filename

•	Saving Captured Data to a New File

•	Disk Space Preallocation for the Capture File

•	Index Size

•	Video and Audio Chunk Granularity

•	Video Buffers

•	Audio Buffers


Capture Filename

AVICap, by default, routes video and audio stream data from a capture window to a file named CAPTURE.AVI in the root directory of the current drive. You can specify an alternate filename by sending the WM_CAP_FILE_SET_CAPTURE_FILE message (or the capFileSetCaptureFile macro) to a capture window. This message specifies the filename; it does not create, allocate, or open the file. You can retrieve the current capture filename by sending the WM_CAP_FILE_GET_CAPTURE_FILE message (or the capFileGetCaptureFile macro) to a capture window.


Saving Captured Data to a New File

If the user wants to save captured data, the application should save the contents of the capture file to another file by using the WM_CAP_FILE_SAVEAS message (or the capFileSaveAs macro). This message does not change the name or contents of the capture file. Your application must specify a name for the new file because the capture file retains its original filename.

Typically, a capture file is preallocated for the largest capture segment anticipated, and only a portion of it might be used to capture data. This message copies only the portion of the capture file containing the capture data.


Disk Space Preallocation for the Capture File

Preallocating disk space for the capture file builds a file of a specified size on the disk before the start of a capture operation. Preallocating a capture file reduces the processing required while capture is in progress and results in fewer dropped frames. You can preallocate a capture file by using the WM_CAP_FILE_ALLOCATE message (or the capFileAlloc macro).

Typically, your application should preallocate enough disk space to contain the largest capture file anticipated. Preallocating disk space does not restrict the size of the captured file. The file size is automatically enlarged if the captured data exceeds the allocated space. Subsequent write operations to the capture file reuse the portions of disk space allocated for the file, preserving the size and fragmentation of the file.

You can also improve capture performance by defragmenting the capture file. To defragment the file, use a defragmentation utility such as Disk Defragmenter. If you use a defragmented capture file and later enlarge it, you should defragment the enlarged file. Enlarging a defragmented capture file can fragment the expanded portion of the file and reduce performance in the capture operation.

You might also improve performance by using an uncompressed disk for video capture. Compressing data during capture can limit capture throughput to the disk.

An application can reserve a permanent capture file to eliminate the time required to preallocate and defragment a file each time it is started. Because a capture file can require considerable disk space, and preallocating a capture file removes all data from an existing capture file, an application should let the user decide if the file is permanent or temporary.


Index Size

Each AVI file uses an index of a specified size to locate video and audio data chunks within the file. An entry in the index locates one video frame or waveform-audio buffer. Consequently, the value of the index size indirectly sets the upper limit on the number of frames that can be captured in a file.

You can retrieve the current index size by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). The current index size is stored in the dwIndexSize member of the CAPTUREPARMS structure. You can specify a new index size as the value of dwIndexSize and then send the updated CAPTUREPARMS structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro). The default index size is 34,952 entries (allowing 32K frames and a proportional number of audio buffers).


Video and Audio Chunk Granularity

The chunk granularity is a logical block size for an AVI file that is used for writing and retrieving audio and video data chunks. When writing audio and video chunks to disk, AVICap adds filler chunks (RIFF “JUNK” chunks) as necessary to fill each logical block of data.

You can retrieve the current chunk granularity setting by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). The current chunk granularity is stored in the wChunkGranularity member of the CAPTUREPARMS structure. You can specify a new chunk granularity as the value of wChunkGranularity and then send the updated CAPTUREPARMS structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro). You can also specify zero for this member to set the chunk granularity to the sector size of the disk.


Video Buffers

The buffers used with video capture reside in the memory heap. The number of buffers used in a capture operation can vary and depend on the value of the wNumVideoRequested member of the CAPTUREPARMS structure and available system memory.

You can retrieve the current value of requested video buffers by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). The current requested number of video buffers is stored in the wNumVideoRequested member of the CAPTUREPARMS structure. You can request the placement and number of buffers by updating this member, and then sending the updated CAPTUREPARMS structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro).


Audio Buffers

You can control the audio portion of a capture operation in three ways:

•	Include or exclude audio from the capture operation.

•	Request a specific number of audio buffers.

•	Request that audio buffers be a specific size.

You can retrieve the settings for audio buffers by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). The fCaptureAudio member of the CAPTUREPARMS structure specifies whether audio is included or excluded from the capture operation. The current requested number of audio buffers is stored in the wNumAudioRequested member, and the current audio buffer size is stored in the dwAudioBufferSize member. You can specify whether to include audio capture, specify the size and number of audio buffers by updating these members, and send the updated CAPTUREPARMS structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro).

By default, audio is included in the capture operation, and four audio buffers are allocated. The default value of fCaptureAudio is TRUE. The default buffer size (the value of dwAudioBufferSize) can contain 0.5 seconds of audio data or 10K, whichever is greater.


Capture Variations

In addition to streaming capture based on a constant time interval, AVICap supports the following types of capture:

•	Manual frame capture (programmable control frames that are captured)

•	Still-image capture

•	Capture without using disk storage

•	Streaming capture from an MCI device (real-time and step-frame)


Manual Frame Capture

If you want to individually specify the frames to capture in a video stream, you can control the sequence by using the WM_CAP_SINGLE_FRAME_OPEN, WM_CAP_SINGLE_FRAME, and WM_CAP_SINGLE_FRAME_CLOSE messages (or the capCaptureSingleFrameOpen, capCaptureSingleFrame, and capCaptureSingleFrameClose macros). Typically, these messages are used to create animation by appending individual frames to the capture file. WM_CAP_SINGLE_FRAME_OPEN opens a file for a manually driven capture operation. WM_CAP_SINGLE_FRAME captures an individual frame and appends it to the capture file. WM_CAP_SINGLE_FRAME_CLOSE closes the file used for manual frame capture.

Note  This capture method does not support simultaneous audio capture with video capture.


Still-Image Capture

If you want to capture a single frame as a still image, you can use the WM_CAP_GRAB_FRAME_NOSTOP or WM_CAP_GRAB_FRAME message (or the capGrabFrameNoStop or capGrabFrame macro) to capture the digitized image in an internal frame buffer. You can freeze the display on the captured image by using WM_CAP_GRAB_FRAME. Otherwise, use WM_CAP_GRAB_FRAME_NOSTOP.

Once captured, you can copy the image for use by other applications. You can copy an image from the frame buffer to the clipboard by using the WM_CAP_EDIT_COPY message (or the capEditCopy macro). You can also copy the image from the frame buffer to a device-independent bitmap (DIB) by using the WM_CAP_FILE_SAVEDIB message (or the capFileSaveDIB macro).

Your application can also use the two single-frame capture messages to edit a sequence frame by frame, or to create a time-lapse photography sequence.


Capture Without Using Disk Storage

You can use capture services without writing the data to a disk file by using the WM_CAP_SEQUENCE_NOFILE message (or the capCaptureSequenceNoFile macro). This message is useful only in conjunction with callback functions that allow your application to use the video and audio data directly. For example, videoconferencing applications might use this message to obtain streaming video frames. The callback functions would transfer the captured images to the remote computer.


Streaming Capture from an MCI Device

MCI devices augment the capture operation in real-time capture and step-frame capture. You can specify the MCI device, such as a videodisc or video-cassette recorder (VCR), acting as the video source for your capture operation by using the WM_CAP_SET_MCI_DEVICE message (or the capSetMCIDeviceName macro) and specifying the name of the device. You can also retrieve the device name currently set by using the WM_CAP_GET_MCI_DEVICE message (or the capGetMCIDeviceName macro).

In real-time capture, the capture window synchronizes the capture operation and compensates for delays associated with positioning the MCI video source and initializing the resources (such as capture buffers) required for capturing data. The capture window expects a valid MCI video device to be installed in the system for capturing data this way.

Specifications for controlling an MCI device are stored in the members of the CAPTUREPARMS structure. MCI-compatible video sources include VCRs and laserdiscs. If the fMCIControl member of this structure is set to TRUE, the capture window coordinates MCI operation. The capture window uses the parameters specified in the dwMCIStartTime and dwMCIStopTime members to obtain the starting and stopping positions, in milliseconds, of the sequence. If the value of fMCIControl is FALSE, the video source is not treated as an MCI device and the contents of dwMCIStartTime and dwMCIStopTime are ignored.

You can use Media Player to quickly verify that an MCI video device is properly connected to the system. Playing a device with Media Player verifies that the MCI configuration for the device is correct. If an image appears on the video display, the video source is connected properly to the capture hardware.

In step-frame capture, the capture window synchronizes the capture operation and compensates for the delays associated with positioning the MCI video source and initializing the resources required for capturing data. In addition, the capture window ensures that no frames are dropped; it steps through the video frames individually, ensuring that the frame is captured and stored before capturing the next frame in the video stream.

Specifications for controlling step-frame capture are stored in the members of the CAPTUREPARMS structure. Step-frame capture uses the following members in addition to the members used for real-time capture: fStepMCIDevice, fStepCaptureAt2x, and wStepCaptureAverageFrames. If the fStepMCIDevice member is set to TRUE, the capture window coordinates step-frame capture. The capture window uses the parameters specified in the dwMCIStartTime and dwMCIStopTime members for the starting and stopping positions, in milliseconds, of the sequence. The capture window uses fStepCaptureAt2x to determine if the capture hardware should capture video frames at twice the normal resolution and uses wStepCaptureAverageFrames to specify the number of times each frame in the capture operation is sampled.

If fStepMCIDevice is FALSE, real-time capture is used instead of step-frame capture and the contents of fStepCaptureAt2x, and wStepCaptureAverageFrames are ignored.

If a step-frame capture is specified and fStepCaptureAt2x is set to TRUE, the capture hardware captures at twice the specified resolution. (The resolutions of both the height and width are doubled.) The software interpolates the pixels in the higher resolution image to produce the image at the specified resolution. This form of averaging can improve the edge definition of images in a frame. You can enable this option if the hardware does not support hardware-based decimation and you are capturing in the RGB format.

Note  If your hardware supports hardware-based decimation, it can capture samples at a higher rate than specified and use these additional samples to obtain color definitions that are more consistent with the original image. The additional samples are discarded after they are used, and the hardware passes samples to the capture driver at the specified rate.

If a step-frame capture is specified, the wStepCaptureAverageFrames member specifies the number of times a frame is sampled when creating a frame based on the average sample. This averaging technique reduces the random digitization noise appearing in a frame. A typical value for the number of averages is 5.

For more information about MCI, see MCI.


Advanced Capture Options

This section describes other options you can include in a capture operation.

•	Measuring Video Quality

•	User-Initiated Capture

•	Working with Palettes

•	Embedding Information Chunks in an AVI File

•	User Data Messages


Measuring Video Quality

One way to measure video quality is to limit the number of captured frames dropped during the capture operation. When streaming capture has finished, the quality value is compared with the ratio of dropped frames to total frames. If the percentage of dropped frames is greater than the value of the wPercentDropForError member of the CAPTUREPARMS structure, AVICap sends an error message to the error callback function if it is installed.

You can retrieve the current limit of dropped frames (expressed as a percentage) by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). You can set a new limit by specifying a percentage as the value of the wPercentDropForError member of the CAPTUREPARMS structure, and then sending the updated structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro). The default value of wPercentDropForError is 10 percent.


User-Initiated Capture

You can retrieve the current value of the user-initiated capture flag by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). The value of the flag is stored in the fMakeUserHitOKToCapture member of the CAPTUREPARMS structure. You can provide the user with precise control over when to start a capture session by setting this member to TRUE. AVICap displays a dialog box after allocating all video and audio buffers for a capture session. This lets the user eliminate capture delays because of software initialization. If your application uses a small number of video buffers, this dialog box is probably unnecessary. The default value is FALSE.


Working with Palettes

Initially, if the video capture format requires a palette, the capture window uses the palette supplied by the capture driver. This palette might consist of gray-scale values for black-and-white reproduction, or a broad selection of color values. You can retrieve an existing palette to replace the default palette by using the WM_CAP_PAL_PASTE or WM_CAP_PAL_OPEN message (or the capPalettePaste or capPaletteOpen macro). Alternatively, you can create a custom palette to replace the default palette by using the WM_CAP_PAL_AUTOCREATE or WM_CAP_PAL_MANUALCREATE message (or the capPaletteAuto or capPaletteManual macro). After you replace the default palette, the capture window and driver use the replacement palette until you create or open another palette.

The WM_CAP_PAL_AUTOCREATE or WM_CAP_PAL_MANUALCREATE message creates an optimized palette based on the current video input. This custom palette gives a video sequence the best color fidelity because it is based on colors that exist in the sequence. The capture window creates a three-dimensional histogram of the colors it samples. It reduces the number of colors by examining the absolute error between adjacent colors and consolidating those with the smallest error value.

When sending WM_CAP_PAL_AUTOCREATE, you must specify the number of frames for AVICap to sample, and specify the size of the color palette. When specifying the number of frames, include enough frames to ensure that all colors in the sequence are sampled.

You can sample the current frame by using WM_CAP_PAL_MANUALCREATE. By using this message with several manually selected frames, you can create a palette that contains the colors you want to appear in the palette.

A palette can contain up to 256 colors. If you merge palettes or if the video sequence is to be displayed simultaneously with other video or images, you should use a smaller color selection so that colors from each image or video clip can coexist.

You save a new palette by using the WM_CAP_PAL_SAVE message (or the capPaletteSave macro) and later retrieve it by using the WM_CAP_PAL_OPEN message. You can save a palette for post-processing of the palette or for use in another application.

You can paste a palette from the clipboard into the capture window by using the WM_CAP_PAL_PASTE message. The capture window passes the palette to the capture driver. Other applications can copy palettes to the clipboard. You can also copy a palette to the clipboard by using the WM_CAP_EDIT_COPY message (or the capEditCopy macro). This message copies the video frame buffer, including the palette, onto the clipboard.


Embedding Information Chunks in an AVI File

You can insert information chunks, such as text or custom data, in an AVI file by using the WM_CAP_FILE_SET_INFOCHUNK message (or the capFileSetInfoChunk macro). You can also use this message to clear information chunks from an AVI file.


User Data Messages

You can associate data with a capture window by using the WM_CAP_GET_USER_DATA and WM_CAP_SET_USER_DATA messages (or the capGetUserData and capSetUserData macros). You can retrieve a LONG data value by using the WM_CAP_GET_USER_DATA message and set a LONG data value by using the WM_CAP_SET_USER_DATA message.


AVICap Callback Functions

Your application can register callback functions with a capture window to have it notify your application when the status changes, when errors occur, when video frame and audio buffers become available, and to yield during streaming capture. The following messages set the callback function.

Message	Description
WM_CAP_SET_CALLBACK_CAPCONTROL	Specifies the callback function in the application called to give precise control over capture start and end. You can also use the capSetCallbackOnCapControl macro to send this message.
WM_CAP_SET_CALLBACK_ERROR	Specifies the callback function in the application called when an error occurs. You can also use the capSetCallbackOnError macro to send this message.
WM_CAP_SET_CALLBACK_FRAME	Specifies the callback function in the application called when preview frames are captured. You can also use the capSetCallbackOnFrame macro to send this message.
WM_CAP_SET_CALLBACK_STATUS	Specifies the callback function in the application called when the status changes. You can also use the capSetCallbackOnStatus macro to send this message.
WM_CAP_SET_CALLBACK_VIDEOSTREAM	Specifies the callback function in the application called during streaming capture when a new video buffer becomes available. You can also use the capSetCallbackOnVideoStream macro to send this message.
WM_CAP_SET_CALLBACK_WAVESTREAM	Specifies the callback function in the application called during streaming capture when a new audio buffer becomes available. You can also use the capSetCallbackOnWaveStream macro to send this message.
WM_CAP_SET_CALLBACK_YIELD	Specifies the callback function in the application called when yielding during streaming capture. You can also use the capSetCallbackOnYield macro to send this message.
The following topics describe the different callback functions, the notifications sent to the functions, and their uses.


Precise Capture Control

A capture window can provide the capture-control callback function with precise control over the moments that streaming capture begin and end. The first message sent from the capture driver to the callback procedure sets the nState parameter to CONTROLCALLBACK_PREROLL after allocating all buffers and all other capture preparations are complete. This message gives the application the ability to preroll the video sources. (The callback function specifies nState as its second parameter.) The callback function then returns at the exact moment recording is to begin. A return value of TRUE from the callback function continues capture. A return value of FALSE aborts capture. Once capture begins, the callback function is called frequently with nState set to CONTROLCALLBACK_CAPTURING to allow the application to end capture by returning false.


Error

A capture window uses error notification messages to notify your application of AVICap errors, such as running out of disk space, attempting to write to a read-only file, failing to access hardware, or dropping too many frames. The content of an error notification includes a message identifier and a formatted text string ready for display. Your application can use the message identifier to filter the notifications and limit the messages to present to the user. A message identifier of zero indicates a new operation is starting and the callback function should clear any displayed error message.


Frame

A capture window uses frame callback notification messages to notify your application when a new video frame is available. The capture window enables these callback notifications only if the preview rate is nonzero and streaming capture is not in progress.


Status Callback Functions

A capture window can send messages to the status callback function while capturing video to disk or during other lengthy operations to notify your application of the progress of an operation. The status information includes a message identifier and a formatted text string ready for display. Your application can use the message identifier to filter the notifications and limit the messages to present to the user. During capture operations, the first message sent to the callback function is always IDS_CAP_BEGIN and the last is always IDS_CAP_END. A message identifier of zero indicates a new operation is starting and the callback function should clear the current status.


Videostream

Applications can use videostream callback functions during streaming capture to process a captured video frame. The capture window calls a videostream callback function just before writing each captured frame to the disk.


Wavestream

Applications use the wavestream callback functions during streaming capture to process audio buffers. The capture window calls a wavestream callback function just before writing each audio buffer to the disk.


Yield Callback Functions

Applications can use yield callback functions during streaming capture. (A yield callback function typically consists of a message loop that calls PeekMessage, TranslateMessage, and DispatchMessage.) The capture window calls the yield callback function at least once for every captured video frame, but the exact rate depends on the frame rate and the overhead of the capture driver and disk.


Disabling Callback Functions

You can permanently or temporarily disable any of the callback functions by specifying NULL in place of the callback function when sending the appropriate message to set a callback function.


Using Video Capture

This section contains examples demonstrating how to perform the following tasks:

•	Creating a capture window

•	Connecting to a capture driver

•	Enumerating installed capture drivers

•	Obtaining the capabilities of a capture driver

•	Obtaining the status of a capture window

•	Displaying dialog boxes to set video characteristics

•	Obtaining and setting the video format

•	Previewing video

•	Enabling video overlay

•	Naming the capture file

•	Formatting audio capture

•	Changing a video capture setting

•	Capturing data

•	Adding an information chunk

•	Adding callback functions to an application

•	Creating a status callback function

•	Creating an error callback function

•	Creating a frame callback function


Creating a Capture Window

The following example creates a capture window by using the capCreateCaptureWindow function.

hWndC = capCreateCaptureWindow (

    (LPSTR) "My Capture Window", // window name if pop-up

    WS_CHILD | WS_VISIBLE,       // window style

    0, 0, 160, 120,              // window position and dimensions

    (HWND) hwndParent,

    (int) nID /* child ID */);


Connecting to a Capture Driver

The following example connects the capture window with the handle hWndC to the MSVIDEO driver and then disconnects them using the capDriverDisconnect macro:

fOK = SendMessage (hWndC, WM_CAP_DRIVER_CONNECT, 0, 0L);

//

// Or, use the macro to connect to the MSVIDEO driver:

// fOK = capDriverConnect(hWndC, 0);

//

// Place code to set up and capture video here.

//

capDriverDisconnect (hWndC);


Enumerating Installed Capture Drivers

The following example uses the capGetDriverDescription function to obtain the names and versions of the installed capture drivers.

char szDeviceName[80];

char szDeviceVersion[80];

for (wIndex = 0; wIndex < 10; wIndex++)

{

    if (capGetDriverDescription (wIndex, szDeviceName,

        sizeof (szDeviceName), szDeviceVersion,

        sizeof (szDeviceVersion))

    {

        // Append name to list of installed capture drivers

        // and then let the user select a driver to use.

    }

}


Obtaining the Capabilities of a Capture Driver

The WM_CAP_DRIVER_GET_CAPS message returns the capabilities of the capture driver and underlying hardware in the CAPDRIVERCAPS structure. Each time an application connects a new capture driver to the capture window, it should update the CAPDRIVERCAPS structure. The following example uses the capDriverGetCaps macro to obtain the capture driver capabilities.

CAPDRIVERCAPS CapDrvCaps;

SendMessage (hWndC, WM_CAP_DRIVER_GET_CAPS,

    sizeof (CAPDRIVERCAPS), (LONG) (LPVOID) &CapDrvCaps);

// Or, use the macro to retrieve the driver capabilities.

// capDriverGetCaps(hWndC, &CapDrvCaps, sizeof (CAPDRIVERCAPS));


Obtaining the Status of a Capture Window

The following example uses the SetWindowPos function to set the size of the capture window to the overall dimensions of the incoming video stream based on information returned by the capGetStatus macro in the CAPSTATUS structure.

CAPSTATUS CapStatus;

capGetStatus(hWndC, &CapStatus, sizeof (CAPSTATUS));

SetWindowPos(hWndC, NULL, 0, 0, CapStatus.uiImageWidth,

    CapStatus.uiImageHeight, SWP_NOZORDER | SWP_NOMOVE);


Displaying Dialog Boxes to Set Video Characteristics

Each capture driver can provide up to three different dialog boxes used to control aspects of the video digitization and capture process. The following example demonstrates how to display these dialog boxes. Before displaying each dialog box, the example calls the capDriverGetCaps macro and checks the CAPDRIVERCAPS structure returned to see if the capture driver can display it.

CAPDRIVERCAPS CapDrvCaps;

capDriverGetCaps(hWndC, &CapDrvCaps, sizeof (CAPDRIVERCAPS));

// Video source dialog box.

if (CapDriverCaps.fHasDlgVideoSource)

    capDlgVideoSource(hWndC);

// Video format dialog box.

if (CapDriverCaps.fHasDlgVideoFormat)

{

    capDlgVideoFormat(hWndC);

    // Are there new image dimensions?

    capGetStatus(hWndC, &CapStatus, sizeof (CAPSTATUS));

    // If so, notify the parent of a size change.

}

// Video display dialog box.

if (CapDriverCaps.fHasDlgVideoDisplay)

    capDlgVideoDisplay(hWndC);


Obtaining and Setting the Video Format

The BITMAPINFO structure is of variable length to accommodate standard and compressed data formats. Because this structure is of variable length, applications must always query the size of the structure and allocate memory before retrieving the current video format. The following example uses the capGetVideoFormatSize macro to retrieve the buffer size and then calls the capGetVideoFormat macro to retrieve the current video format.

LPBITMAPINFO lpbi;

DWORD dwSize;

dwSize = capGetVideoFormatSize(hWndC);

lpbi = GlobalAllocPtr (GHND, dwSize);

capGetVideoFormat(hWndC, lpbi, dwSize);

// Access the video format and then free the allocated memory.

Applications can use the capSetVideoFormat macro (or the WM_CAP_SET_VIDEOFORMAT message) to send a BITMAPINFO header structure to the capture window. Because video formats are device specific, your application should check the return value to determine if the format was accepted.


Previewing Video

The following example uses the capPreviewRate macro to set the frame display rate for preview mode to 66 milliseconds per frame and then uses the capPreview macro to place the capture window in preview mode.

capPreviewRate(hWndC, 66);     // rate, in milliseconds

capPreview(hWndC, TRUE);       // starts preview

// Preview

capPreview(hWnd, FALSE);        // disables preview


Enabling Video Overlay

The following example uses the capDriverGetCaps macro to determine whether a capture driver has overlay capabilities; if it does, the macro enables the overlay.

CAPDRIVERCAPS CapDrvCaps;

capDriverGetCaps(hWndC, &CapDrvCaps, sizeof (CAPDRIVERCAPS));

if (CapDrvCaps.fHasOverlay)

    capOverlay(hWndC, TRUE);


Naming the Capture File

The following example uses the capFileSetCaptureFile macro to specify an alternate filename (MYCAP.AVI) for the capture file and the capFileAlloc macro to preallocate a file of 5 MB.

char szCaptureFile[] = “MYCAP.AVI”;

capFileSetCaptureFile( hWndC, szCaptureFile);

capFileAlloc( hWndC, (1024L * 1024L * 5));


Formatting Audio Capture

The following example uses capSetAudioFormat to set the audio format to 11-kHz PCM 8-bit, stereo.

WAVEFORMATEX wfex;

wfex.wFormatTag = WAVE_FORMAT_PCM;

wfex.nChannels = 2;                // Use stereo

wfex.nSamplesPerSec = 11025;

wfex.nAvgBytesPerSec = 22050;

wfex.nBlockAlign = 2;

wfex.wBitsPerSample = 8;

wfex.cbSize = 0;

capSetAudioFormat(hWndC, &wfex, sizeof(WAVEFORMATEX));


Changing a Video Capture Setting

The following example uses the capCaptureGetSetup and capCaptureSetSetup macros to change the capture rate from the default value (15 frames per second) to 10 frames per second.

CAPTUREPARMS CaptureParms;

float FramesPerSec = 10.0;

capCaptureGetSetup(hWndC, &CaptureParms, sizeof(CAPTUREPARMS));

CaptureParms.dwRequestMicroSecPerFrame = (DWORD) (1.0e6 /

    FramesPerSec);

capCaptureSetSetup(hWndC, &CaptureParms, sizeof (CAPTUREPARMS));


Capturing Data

The following example uses the capCaptureSequence macro to start video capture and the capFileSaveAs macro to copy the captured data from the capture file to the file NEWFILE.AVI.

char szNewName[] = "NEWFILE.AVI";

// Set up the capture operation.

capCaptureSequence(hWndC);

// Capture.

capFileSaveAs(hWndC, szNewName);


Adding an Information Chunk

If you need to include other information in your application in addition to audio and video, you can create information chunks and insert them into a capture file. Information chunks can contain several types of information, including the details of a copyright notice, identification of the video source, or external timing information. The following example stores external timing information — a SMPTE (Society of Motion Picture and Television Engineers) timecode — in an information chunk and adds the chunk to a capture file using the capFileSetInfoChunk macro.

//  This example assumes the application controls

//  the video source for preroll and postroll.

CAPINFOCHUNK cic;
// .

// .

// .

cic.fccInfoID = infotypeSMPTE_TIME;
cic.lpData = “00:20:30:12”;
cic.cbData = strlen (cic.lpData) + 1;
capFileSetInfoChunk (hwndC, &cic);


Adding Callback Functions to an Application

An application can register callback functions with the capture window so that it notifies the application in the following circumstances:

•	The status changes

•	Errors occur

•	Video frame and audio buffers become available

•	The application should yield during streaming capture

The following example creates a capture window and registers status, error, video stream, and frame callback functions in the message-processing loop of an application. It also includes a sample statement for disabling a callback function. Subsequent examples show simple status, error, and frame callback functions.

case WM_CREATE:

{

    char    achDeviceName[80] ;

    char    achDeviceVersion[100] ;

    char    achBuffer[100] ;

    WORD    wDriverCount = 0 ;

    WORD    wIndex ;

    WORD    wError ;

    HMENU   hMenu ;

    // Create a capture window using the capCreateCaptureWindow macro.

    ghWndCap = capCreateCaptureWindow((LPSTR)"Capture Window",

        WS_CHILD | WS_VISIBLE, 0, 0, 160, 120, (HWND) hWnd, (int) 0);

    // Register the error callback function using the

    // capSetCallbackOnError macro.

    capSetCallbackOnError(ghWndCap, fpErrorCallback);

    // Register the status callback function using the

    // capSetCallbackOnStatus macro.

    capSetCallbackOnStatus(ghWndCap, fpStatusCallback);

    // Register the video-stream callback function using the

    // capSetCallbackOnVideoStream macro.

    capSetCallbackOnVideoStream(ghWndCap, fpVideoCallback);

    // Register the frame callback function using the

    // capSetCallbackOnFrame macro.

    capSetCallbackOnFrame(ghWndCap, fpFrameCallback);

    // Connect to a capture driver

    break;

}

case WM_CLOSE:

{

// Use the capSetCallbackOnFrame macro to

// disable the frame callback. Similar calls exist for the other

// callback functions.

    capSetCallbackOnFrame(hWndC, NULL);

    break;

}


Creating a Status Callback Function

The following example is a simple status callback function. Register this callback by using the capSetCallbackOnStatus macro.

// StatusCallbackProc: status callback function

// hWnd:               capture window handle

// nID:                status code for the current status

// lpStatusText:       status text string for the current status

//

LRESULT PASCAL StatusCallbackProc(HWND hWnd, int nID,

    LPSTR lpStatusText)

{

    if (!ghWndMain)

        return FALSE;

    if (nID == 0) {           // Clear old status messages.

        SetWindowText(ghWndMain, (LPSTR) gachAppName);

        return (LRESULT) TRUE;

    }

    // Show the status ID and status text...

    wsprintf(gachBuffer, "Status# %d: %s", nID, lpStatusText);

    SetWindowText(ghWndMain, (LPSTR)gachBuffer);

    return (LRESULT) TRUE;

}


Creating an Error Callback Function

The following example is a simple error callback function. Register this callback by using the capSetCallbackOnError macro.

// ErrorCallbackProc: error callback function

// hWnd:              capture window handle

// nErrID:            error code for the encountered error

// lpErrorText:       error text string for the encountered error

//

LRESULT PASCAL ErrorCallbackProc(HWND hWnd, int nErrID,

    LPSTR lpErrorText)

{

    if (!ghWndMain)

        return FALSE;

    if (nErrID == 0)            // Starting a new major function.

        return TRUE;            // Clear out old errors.

    // Show the error identifier and text.

    wsprintf(gachBuffer, "Error# %d", nErrID);

    MessageBox(hWnd, lpErrorText, gachBuffer,

        MB_OK | MB_ICONEXCLAMATION);

    return (LRESULT) TRUE;

}


Creating a Frame Callback Function

The following example is a simple frame callback function. Register this callback by using the capSetCallbackOnFrame macro.

// FrameCallbackProc: frame callback function

// hWnd:              capture window handle

// lpVHdr:            pointer to struct containing captured

//                    frame information

//

LRESULT PASCAL FrameCallbackProc(HWND hWnd, LPVIDEOHDR lpVHdr)

{

    if (!ghWndMain)

        return FALSE;

    wsprintf(gachBuffer, "Preview frame# %ld ", gdwFrameNum++);

    SetWindowText(ghWndMain, (LPSTR)gachBuffer);

    return (LRESULT) TRUE ;

}


Video Capture Reference

This section describes the functions, structures, messages, and macros associated with the AVICap window class. These elements are grouped as follows.

Basic Capture Operations

capCreateCaptureWindow
WM_CAP_ABORT
WM_CAP_DRIVER_CONNECT
WM_CAP_SEQUENCE
WM_CAP_STOP

Capture Windows

CAPSTATUS
capGetDriverDescription
WM_CAP_DRIVER_CONNECT
WM_CAP_DRIVER_DISCONNECT
WM_CAP_GET_STATUS

Capture Drivers

CAPDRIVERCAPS
WM_CAP_DRIVER_GET_CAPS
WM_CAP_DRIVER_GET_NAME
WM_CAP_DRIVER_GET_VERSION
WM_CAP_GET_AUDIOFORMAT
WM_CAP_GET_VIDEOFORMAT
WM_CAP_SET_AUDIOFORMAT
WM_CAP_SET_VIDEOFORMAT

Capture Driver Preview and Overlay Modes

WM_CAP_SET_OVERLAY
WM_CAP_SET_PREVIEW
WM_CAP_SET_PREVIEWRATE
WM_CAP_SET_SCALE
WM_CAP_SET_SCROLL

Capture Driver Video Dialog Boxes

WM_CAP_DLG_VIDEOCOMPRESSION
WM_CAP_DLG_VIDEODISPLAY
WM_CAP_DLG_VIDEOFORMAT
WM_CAP_DLG_VIDEOSOURCE

Audio Format

WM_CAP_GET_AUDIOFORMAT
WM_CAP_SET_AUDIOFORMAT

Video Capture Settings

CAPTUREPARMS
WM_CAP_GET_SEQUENCE_SETUP
WM_CAP_SET_SEQUENCE_SETUP

Capture File and Buffers

CAPTUREPARMS
WM_CAP_FILE_ALLOCATE
WM_CAP_FILE_GET_CAPTURE_FILE
WM_CAP_FILE_SAVEAS
WM_CAP_FILE_SET_CAPTURE_FILE

Directly Using Capture Data

WM_CAP_SEQUENCE_NOFILE

Capture from MCI Device

WM_CAP_SET_MCI_DEVICE

Manual Frame Capture

WM_CAP_SINGLE_FRAME
WM_CAP_SINGLE_FRAME_CLOSE
WM_CAP_SINGLE_FRAME_OPEN

Still-Image Capture

WM_CAP_EDIT_COPY
WM_CAP_FILE_SAVEDIB
WM_CAP_GRAB_FRAME
WM_CAP_GRAB_FRAME_NOSTOP

Advanced Capture Options

WM_CAP_FILE_SET_INFOCHUNK
WM_CAP_GET_USER_DATA
WM_CAP_SET_USER_DATA

Working with Palettes

WM_CAP_EDIT_COPY
WM_CAP_PAL_AUTOCREATE
WM_CAP_PAL_MANUALCREATE
WM_CAP_PAL_OPEN
WM_CAP_PAL_PASTE
WM_CAP_PAL_SAVE

Yielding to Other Applications

WM_CAP_GET_SEQUENCE_SETUP
WM_CAP_SET_CALLBACK_YIELD
WM_CAP_SET_SEQUENCE_SETUP

AVICap Callback Functions

capControlCallback
capErrorCallback
capStatusCallback
capVideoStreamCallback
capWaveStreamCallback
capYieldCallback
WM_CAP_SET_CALLBACK_CAPCONTROL
WM_CAP_SET_CALLBACK_ERROR
WM_CAP_SET_CALLBACK_FRAME
WM_CAP_SET_CALLBACK_STATUS
WM_CAP_SET_CALLBACK_VIDEOSTREAM
WM_CAP_SET_CALLBACK_WAVESTREAM
WM_CAP_SET_CALLBACK_YIELD


Video Capture Functions

The following functions are used with video capture.

capControlCallback
capCreateCaptureWindow
capErrorCallback
capGetDriverDescription
capStatusCallback
capVideoStreamCallback
capWaveStreamCallback
capYieldCallback


Video Capture Structures

The following structures are used with video capture.

CAPDRIVERCAPS
CAPINFOCHUNK
CAPSTATUS
CAPTUREPARMS


Video Capture Messages

The following messages are used with video capture.

WM_CAP_ABORT
WM_CAP_DLG_VIDEOCOMPRESSION
WM_CAP_DLG_VIDEODISPLAY
WM_CAP_DLG_VIDEOFORMAT
WM_CAP_DLG_VIDEOSOURCE
WM_CAP_DRIVER_CONNECT
WM_CAP_DRIVER_DISCONNECT
WM_CAP_DRIVER_GET_CAPS
WM_CAP_DRIVER_GET_NAME
WM_CAP_DRIVER_GET_VERSION
WM_CAP_EDIT_COPY
WM_CAP_FILE_ALLOCATE
WM_CAP_FILE_GET_CAPTURE_FILE
WM_CAP_FILE_SAVEAS
WM_CAP_FILE_SAVEDIB
WM_CAP_FILE_SET_CAPTURE_FILE
WM_CAP_FILE_SET_INFOCHUNK
WM_CAP_GET_AUDIOFORMAT
WM_CAP_GET_MCI_DEVICE
WM_CAP_GET_SEQUENCE_SETUP
WM_CAP_GET_STATUS
WM_CAP_GET_USER_DATA
WM_CAP_GET_VIDEOFORMAT
WM_CAP_GRAB_FRAME
WM_CAP_GRAB_FRAME_NOSTOP
WM_CAP_PAL_AUTOCREATE
WM_CAP_PAL_MANUALCREATE
WM_CAP_PAL_OPEN
WM_CAP_PAL_PASTE
WM_CAP_PAL_SAVE
WM_CAP_SEQUENCE
WM_CAP_SEQUENCE_NOFILE
WM_CAP_SET_AUDIOFORMAT
WM_CAP_SET_CALLBACK_CAPCONTROL
WM_CAP_SET_CALLBACK_ERROR
WM_CAP_SET_CALLBACK_FRAME
WM_CAP_SET_CALLBACK_STATUS
WM_CAP_SET_CALLBACK_VIDEOSTREAM
WM_CAP_SET_CALLBACK_WAVESTREAM
WM_CAP_SET_CALLBACK_YIELD
WM_CAP_SET_MCI_DEVICE
WM_CAP_SET_OVERLAY
WM_CAP_SET_PREVIEW
WM_CAP_SET_PREVIEWRATE
WM_CAP_SET_SCALE
WM_CAP_SET_SCROLL
WM_CAP_SET_SEQUENCE_SETUP
WM_CAP_SET_USER_DATA
WM_CAP_SET_VIDEOFORMAT
WM_CAP_SINGLE_FRAME
WM_CAP_SINGLE_FRAME_CLOSE
WM_CAP_SINGLE_FRAME_OPEN
WM_CAP_STOP


Video Capture Macros

The following macros are used with video capture.

capCaptureAbort
capCaptureGetSetup
capCaptureSequence
capCaptureSequenceNoFile
capCaptureSetSetup
capCaptureSingleFrame
capCaptureSingleFrameClose
capCaptureSingleFrameOpen
capCaptureStop
capDlgVideoCompression
capDlgVideoDisplay
capDlgVideoFormat
capDlgVideoSource
capDriverConnect
capDriverDisconnect
capDriverGetCaps
capDriverGetName
capDriverGetVersion
capEditCopy
capFileAlloc
capFileGetCaptureFile
capFileSaveAs
capFileSaveDIB
capFileSetCaptureFile
capFileSetInfoChunk
capGetAudioFormat
capGetAudioFormatSize
capGetMCIDeviceName
capGetStatus
capGetUserData
capGetVideoFormat
capGetVideoFormatSize
capGrabFrame
capGrabFrameNoStop
capOverlay
capPaletteAuto
capPaletteManual
capPaletteOpen
capPalettePaste
capPaletteSave
capPreview
capPreviewRate
capPreviewScale
capSetAudioFormat
capSetCallbackOnCapControl
capSetCallbackOnError
capSetCallbackOnFrame
capSetCallbackOnStatus
capSetCallbackOnVideoStream
capSetCallbackOnWaveStream
capSetCallbackOnYield
capSetMCIDeviceName
capSetScrollPos
capSetUserData
capSetVideoFormat


Video Compression Manager

The video compression manager (VCM) provides access to the interface used by installable compressors to handle real-time data. Applications can use installable compressors to perform the following tasks:

•	Compress and decompress video data.

•	Send a renderer compressed video data and have it draw it to the display.

•	Compress, decompress, or draw data with application-defined renderers.

•	Use renderers to handle text and custom data.


About the Video Compression Manager

Typically, installable compressors operate with video-image data stored in audio-video interleaved (AVI) files. This overview explains the programming techniques used to access installable compressors through VCM and covers the following topics:

•	VCM and the Video for Windows architecture

•	Compressing and decompressing image data from your application

•	Using VCM renderers to draw data from your application

•	VCM functions and structures

Before you read this overview, you should be familiar with the Microsoft Win32 graphic services. In particular, bitmaps and bitmap-related structures, such as BITMAPINFO and BITMAPINFOHEADER, are used extensively by VCM. For additional information about the BITMAPINFO and BITMAPINFOHEADER structures, see Bitmaps.

Note  The audio compression manager (ACM) provides system-level support for audio compression and decompression drivers. For a description of the audio compression services, see Audio Compression Manager.


VCM Architecture

VCM is an intermediary between an application and compression and decompression drivers. The compression and decompression drivers compress and decompress individual frames of data.

When an application makes a call to VCM, VCM translates the call into a message. The message is sent by using the ICSendMessage function to the appropriate compressor or decompressor, which compresses or decompresses the data. VCM receives the return value from the compression or decompression driver and then returns control to the application.

If a macro is defined for a message, the macro expands to an ICSendMessage function call supplying appropriate parameters for that message. If a macro is defined for a message, your application should use it rather than the message. In this overview, these macros follow messages in parentheses.


System Entries for Compressors, Decompressors, and Renderers

The system uses entries in the registry to find VCM drivers. These entries are in the form of two four-character codes separated by a period. The first four-character code is defined by the system and can be one of the following:

Four-character code	Description
“VIDC”	Identifies compressors and decompressors.
“VIDS”	Identifies video-stream renderers.
“TXTS”	Identifies text-stream renderers.
“AUDS”	Identifies audio-stream handlers.
Custom renderers can define their own four-character codes.

The second four-character code is defined by the driver. Typically, the second four-character code corresponds to the type of data the driver can handle.

When opening a VCM driver, an application specifies the type of driver and the type of data handler it needs. Typically, this information comes from the stream header. The system tries to open the specified data handler, but if it fails, the system searches the registry for a driver that has the required handler.

When searching for the driver, the system tries to match the four-character codes specified for the driver type and data handler with those specified in the driver entry. For example, if an application specifies the compressor MSSQ, the system searches the registry for the driver entry VIDC.MSSQ. If it cannot find a match, it opens each driver corresponding to the driver type and locates one that can handle the type of data your application specifies. In the previous example, if the system could not find VIDC.MSSQ, it would open all drivers with the “VIDC” four-character code and locate one that can handle the data.


VCM Services

In general, an application uses VCM to perform the following tasks:

•	Locate, open, or install a compressor or decompressor.

•	Configure or obtain configuration information about the compressor or decompressor.

•	Use a series of functions to compress, decompress, or draw the data.

The functions and macros of the DrawDib library perform these tasks implicitly and might provide the most convenient way to use VCM. For more information about the DrawDib library, see DrawDib.

The following sections describe tasks you can perform by using VCM:

•	Compressor and decompressor basics

•	User-selected compressors

•	Compressor and decompressor installation and removal

•	Compressor and decompressor configuration

•	Getting information about compressors and decompressors

•	Single-image compression

•	Sequence compression

•	Image-data compression

•	Single-image decompression

•	Image-data decompression

•	Monitoring the progress of compressors and decompressors

•	Hardware drawing capabilities


Compressor and Decompressor Basics

To open and locate a compressor, you can use the ICLocate and ICOpen functions. You can use ICLocate to find a compressor of a specific type and to obtain a handle of it for use in other VCM functions. To open a compressor, you can use ICOpen. Your application uses the handle returned by this function to identify the opened compressor when it uses other VCM functions.

To open and locate a decompressor, applications can use the ICDecompressOpen and ICDrawOpen macros. These macros use ICLocate for operation.

When your application hass finished using a compressor or decompressor, it must close it to free any resources used for compression or decompression. Your application can use the ICClose function to close the compressor or decompressor.

Also, your application can enumerate the compressors or decompressors on a system by using the ICInfo function.

Note  The stream header in an AVI file contains information about the stream type and the specific handler for that stream. Within the stream header, the fccType and fccHandler members identify the stream type and the stream handler specified for the stream.


User-Selected Compressors

When compressing data, your application can use the ICCompressorChoose function to create a dialog box in which the user can select the compressor. You can specify flags for this function to allow the user to specify the key-frame frequency and the movie-data rate, or to display a preview window.

The compressor selected by the user is automatically opened and its handle is returned in the hic member of the COMPVARS structure specified in ICCompressorChoose.

If you use ICCompressorChoose, use the ICCompressorFree function to close the compressor and free any resources associated with the COMPVARS structure.


Compressor and Decompressor Installation and Removal

An application can use compressors and decompressors that are already installed on a system running the Microsoft Windows operating system. An application can also install compressors and decompressors for general or special uses. Most applications will not need to install or remove compressors or decompressors because they are usually installed by a setup program. An application might, however, install a compressor directly or install a function as a compressor.

An application can install a compressor or decompressor (or a function used as a compressor or decompressor) by using the ICInstall function. This function creates an entry in the registry identifying the compressor or decompressor. Your application or another application can search the registry to determine if the system contains a compressor or decompressor suitable for its data. Use ICInstall to install all compression and decompression drivers.

An application can locate and open an installed compressor or decompressor by using the ICLocate and ICOpen functions. When an application finishes using a compressor or decompressor, it closes it by using the ICClose function.

An application can remove the registry entry for an installed compressor or decompressor by using the ICRemove function. This function removes the registry entry of a compressor or decompressor that is not currently loaded in memory.

An application can restrict the use of a compressor or decompressor by installing, opening, closing, and removing it.

Alternatively, to use a function internally as a compressor or decompressor without installing it in the registry, an application can use the ICOpenFunction function. This function requires the calling application to have the address of the function to be used as a compressor or decompressor. When the application finishes using the function, it must close it by using ICClose. Because the function was not installed, the application does not need to remove the function from the registry.

The internal structure of a function used as a compressor or decompressor should be the same as the DriverProc entry-point function used by installable drivers. For more information about the DriverProc entry-point function, see Installable Drivers.

Note  An application installing a function as a compressor or decompressor must remove the function before the application is closed so other applications do not try to use the function. When removing a function, the application must identify it with the four-character code used to install it.


Compressor and Decompressor Configuration

Your application can configure the compressor or decompressor automatically, or it can allow the user to configure them. If it is practical, allow the user to configure the compressor or decompressor; this frees you from considering all the options for the compressor or decompressor.

The user can configure the compressor or decompressor by using a configuration dialog box. You can send the ICM_CONFIGURE message to VCM (or use the ICQueryConfigure macro) to determine if a compressor or decompressor can display a configuration dialog box. If so, send the ICM_CONFIGURE message (or use the ICConfigure macro) to display it.

Your application can send the ICM_GETSTATE and ICM_SETSTATE messages (or use the ICGetStateSize, ICGetState, and ICSetState macros) to get and set the status for a compressor or decompressor. If your application creates or modifies the status, it must obtain the layout of the compressor or decompressor data before restoring its status. Alternatively, if your application obtains the status from a compressor or decompressor and uses it to restore the status in a subsequent session, it must ensure that it restores only status information obtained from the compressor or decompressor it is currently using.


Getting Information About Compressors and Decompressors

To get general information about a compressor or decompressor, your application can use the ICGetInfo function. This function fills an ICINFO structure with information about the compressor or decompressor. Your application must allocate the memory for the ICINFO structure and pass a pointer to it in ICGetInfo. Unless your application searches for a particular compressor or decompressor, the flags in the ICINFO structure provide the most useful information about the capabilities of a compressor or decompressor.

To get the default key-frame rate and default quality value of a compressor or decompressor, your application can send the ICM_GETDEFAULTKEYFRAMERATE and ICM_GETDEFAULTQUALITY messages (or use the ICGetDefaultKeyFrameRate and ICGetDefaultQuality macros).

To determine the best display format of a compressor or decompressor, your application can use the ICGetDisplayFormat function.

To determine if a compressor or decompressor can display an About dialog box, send the ICM_ABOUT message (or use the ICQueryAbout macro). You can also display the About dialog box of a compressor or decompressor by sending the ICM_ABOUT message and changing the value of the wParam parameter (or by using the ICAbout macro).


Single-Image Compression

You can use the ICImageCompress function to compress a single image. This function returns a handle of the compressed device-independent bitmap (DIB). The compressed DIB is packed using the CF_DIB format.


Sequence Compression

Your application can use the ICSeqCompressFrame, ICSeqCompressFrameStart, and ICSeqCompressFrameEnd functions to compress a sequence of frames. These functions use the data stored in the COMPVARS structure. Applications use the ICCompressorChoose function to allow the user to select a compressor, open it, and set the compression parameters in the COMPVARS structure; however, applications can set the parameters in the structure manually.

Before an application can begin compressing a sequence of frames, it must use ICSeqCompressFrameStart to allocate the necessary resources. After the resources are allocated, the application can use ICSeqCompressFrame to compress each frame individually. The frame rate and key-frame frequency used in compressing the sequence are specified in members of the COMPVARS structure. The return value for ICSeqCompressFrame points to the compressed data.

When an application finishes compressing a sequence, it can use ICSeqCompressFrameEnd to free system resources allocated for ICSeqCompressFrameStart. To free the resources allocated for the COMPVARS structure, the application can use the ICCompressorFree function.


Image-Data Compression

Your application can use a series of ICCompress functions and macros to compress data. The functions and macros can help you perform the following tasks:

•	Determine the compression format to use for a specified input format.

•	Prepare the compressor.

•	Compress the data.

•	End compression.

Your application can increase control over the compression process by using the ICCompress functions and macros. This group of functions and macros handles individual frames, rather than the sequence as a whole. For example, your application can identify the frames to compress as key frames by using the ICCompress function.

A compressor receives data in one format, compresses the data, and returns a compressed version of the data using a specified format. The typical input format specifies DIBs using the BITMAPINFO structure. The typical output format specifies compressed DIBs, also using the BITMAPINFO structure.

Note  To minimize image and audio degradation during playback, avoid compressing an AVI file more than once. Combine uncompressed pieces of video in your editing system and then compress the final product.

Compressor and Compression Format Selection

If you want to compress data and your application requires a specific output format, send the ICM_COMPRESS_QUERY message (or use the ICCompressQuery macro) to query the compressor to determine if it supports the input and output formats.

If the output format is not important to your application, you need only find a compressor that can handle the input format. To determine if a compressor can handle the input format, you can send ICM_COMPRESS_QUERY, specifying NULL for the lParam parameter. This message does not return the output format to your application. Your application can determine the buffer size needed for the data specifying the compression format by sending the ICM_COMPRESS_GET_FORMAT message (or use the ICCompressGetFormatSize macro). You can also retrieve the format data by sending ICM_COMPRESS_GET_FORMAT (or the ICCompressGetFormat macro).

If you want to determine the largest buffer that the compressor could require for compression, send the ICM_COMPRESS_GET_SIZE message (or use the ICCompressGetSize macro). You can use the number of bytes returned by the ICSendMessage function to allocate a buffer for subsequent image compressions.

Compressor Initialization

After your application selects a compressor that can handle the input and output formats it needs, you can initialize the compressor by using the ICM_COMPRESS_BEGIN message (or use the ICCompressBegin macro). This message requires the compressor handle and the input and output formats.

Data Compression

You can use the ICCompress function to compress a frame. Your application must use this function repeatedly until all the frames in a sequence are compressed. Your application must also track and increment the number of each frame compressed with ICCompress. The compressor uses this value to check if frames are sent out of order during fast temporal compression (storing differences between successive frames). If your application recompresses a frame, it should use the same frame number as when the frame was first compressed. If your application compresses a still-frame image, it can specify a frame number of zero.

Your application can use the ICCOMPRESS_KEYFRAME flag to make the frame compressed by ICCompress a key frame.

When VCM returns control to your application after compressing a frame, VCM stores the compressed data in the structures referenced by the lpbiOutput and lpData parameters. If your application needs to move the compressed data, it can find its size in the biSizeImage member of the BITMAPINFO structure specified in lpbiOutput.

Note  Your application must allocate the structures and buffers that store the uncompressed and compressed data. If the compressor supports temporal compression, your application must also allocate a structure and buffer to hold the format and data for the previous frame of information.

Ending Compression

After your application has compressed the data, it can use the ICCompressEnd macro to notify the compressor that it has finished. If you want to restart compression after using this function, your application must reinitialize the compressor by sending the ICM_COMPRESS_BEGIN message (or use the ICCompressBegin macro).


Single-Image Decompression

You can use the ICImageDecompress function to decompress a single image. This function returns a handle of the decompressed DIB. The decompressed DIB is stored in the CF_DIB format.


Image-Data Decompression

Your application uses a series of ICDecompressEx functions to control the decompressor. The functions can help you perform the following tasks:

•	Select a decompressor.

•	Prepare the decompressor.

•	Decompress the data.

•	End decompression.

Your application handles decompression similarly to the way it handles compression, except that the input format is a compressed format and the output format is a displayable format. The input format for decompression is usually obtained from the stream header. After determining the input format, your application can use the ICLocate or ICOpen functions to find a decompressor that can handle it.

The ICDecompressEx functions and macros are a superset of the ICDecompress function group and provide more capabilities. The functionality of ICDecompressEx, ICDecompressExBegin, ICDecompressExEnd, and ICDecompressExQuery replaces that of the ICDecompress, ICDecompressBegin, ICDecompressEnd, and ICDecompressQuery functions. Use the ICDecompressEx functions and macros in place of the ICDecompress equivalents.

Decompressor and Decompression Format Selection

If you want to decompress data and your application requires a specific output format, you can use the ICDecompressExQuery function to query the decompressor to determine if it supports the input and output formats.

If the output format is not important in your application, you need only find a decompressor that can handle the input format. To determine if a decompressor can handle the input format, use ICDecompressExQuery and specify NULL for the lpbiDst parameter. Your application can determine the buffer size needed for the data specifying the decompression format by sending the ICM_DECOMPRESS_GET_FORMAT message (or use the ICDecompressGetFormatSize macro). You can also send ICM_DECOMPRESS_GET_FORMAT (or the ICDecompressGetFormat macro) to retrieve the format data. The decompressor returns its suggested format in a BITMAPINFO structure. This format typically preserves the most information during decompression. Your application should ensure that the decompressor returns successfully before it decompresses the information.

Because your application allocates the memory required for decompression, it needs to determine the maximum memory the decompressor can require for the output format. The ICM_DECOMPRESS_GET_FORMAT message obtains the number of bytes the decompressor uses for the default format.

If your application defines its own format by using ICDecompressExQuery, it must also obtain a palette for the bitmap; ICDecompressExQuery does not provide palette definitions. (Most applications use standard formats and do not need to obtain a palette.) Your application can obtain the palette by sending the ICM_DECOMPRESS_GET_PALETTE message (or use the ICDecompressGetPalette macro).

Decompressor Initialization

After your application selects a decompressor that can handle the input and output formats it needs, you can initialize the decompressor by using the ICDecompressExBegin function. This function requires the decompressor handle and the input and output formats.

Data Decompression

You can use the ICDecompressEx function to decompress a frame. Your application must use this function repeatedly until all the frames in a sequence are decompressed.

If your video stream lags behind other components (such as audio) during playback, your application can specify the ICDECOMPRESS_HURRYUP flag to speed decompression. To do this, a decompressor might extract only the information it needs to decompress the next frame and not fully decompress the current frame. Therefore, your application should not try to draw the decompressed data when it uses this flag.

After your application has decompressed the data, it can send the ICM_DECOMPRESSEX_END message (or use the ICDecompressExEnd macro) to notify the decompressor that it has finished. If you want to restart decompression after using this function, your application must reinitialize the decompressor by using ICDecompressExBegin.


Monitoring the Progress of Compressors and Decompressors

Your application can monitor the progress of a lengthy operation performed by a compressor or decompressor by sending it the address of a callback function. You can use the ICSetStatusProc function to send the address to the compressor or decompressor. When the compressor or decompressor receives this address, it sends status messages to the function. These messages indicate whether the operation is starting, stopping, yielding, or proceeding.


Hardware Drawing Capabilities

Some renderers can draw directly to video hardware as they decompress video frames. These renderers return the VIDCF_DRAW flag in response to the ICGetInfo function. When using this type of renderer, your application does not have to handle the decompressed data. It lets the renderer retain the decompressed data for drawing.

If your application uses a renderer with drawing capabilities, it must handle the following tasks:

•	Select a renderer.

•	Specify image formats.

•	Initialize the renderer.

•	Draw the data.

•	Control drawing parameters.

Renderer Selection

The ICDrawOpen macro opens a renderer that can draw images with the specified format. It returns a handle of a renderer if it is successful, or zero otherwise. This macro uses the ICLocate function to open the renderer.

Specifying Image Formats

Because your application does not need to draw the decompressed data, it does not require a specific output format. It must, however, ensure that the renderer can draw using the input format by using the ICM_DRAW_QUERY message (or use the ICDrawQuery macro). This message cannot determine if a renderer can draw a bitmap. If your application must determine if the renderer can draw the bitmap, use this message with the ICDrawBegin function.

Your application can have a renderer suggest an input format by using the ICDrawSuggestFormat function. This function is used when a renderer separates the drawing capabilities from the decompressing capabilities. Most applications using the drawing functions will not need to determine the output format.

Renderer Initialization

The ICDrawBegin function initializes a renderer and tells it the drawing destination. This function can also perform the following tasks:

•	Determine whether the renderer supports a specific input format.

•	Specify whether the drawing operation occupies a window or the entire screen.

•	Specify the part of the image to display using the source rectangle.

•	Define the playback rate of the image sequence.

Some renderers buffer the compressed data to operate more efficiently. Your application can send the ICM_GETBUFFERSWANTED message (or use the ICGetBuffersWanted macro) to determine the number of buffers the renderer requests. Your application should preload these buffers and send them to the renderer before drawing.

Drawing the Data

You can use the ICDraw function to decompress the data for drawing. The renderer, however, does not start drawing data until your application sends the ICM_DRAW_START message (or uses the ICDrawStart macro). When your application calls this function, the renderer begins to draw the frames at the rate specified by the dwRate parameter divided by the dwScale parameter; these parameters were supplied when the application initialized the renderer by using the ICDrawBegin function. Drawing continues until your application sends the ICM_DRAW_STOP message (or uses the ICDrawStop macro).

Note  If a renderer buffers the data before drawing, your application should not use the ICDrawStart macro until it has sent the number of frames the renderer returned for the ICGetBuffersWanted macro.

The lTime parameter of ICDraw specifies the time to draw a frame. The renderer divides this integer by the time scale specified with ICDrawBegin to obtain the actual time. Times for ICDraw functions are relative to ICDrawStart. ICDrawStart sets the clock to zero. For example, if your application specifies 1000 for the time scale and 75 for lTime, the renderer draws the frame 75 milliseconds into the sequence.

Controlling Drawing Parameters

You can monitor the clock of a renderer by sending the ICM_DRAW_GETTIME message (or use the ICDrawGetTime macro), and you can set the clock of a renderer that can draw data by sending the ICM_DRAW_SETTIME message (or use the ICDrawSetTime macro).

To change the current position while a renderer is drawing, your application can send the ICM_DRAW_WINDOW message (or use the ICDrawWindow macro) for repositioning the window. Applications typically use this message whenever the window changes.

If the playback window gets a realize-palette message, your application must send the ICM_DRAW_REALIZE message (or use the ICDrawRealize macro) to have the renderer realize the palette again for playback. Applications can change the palette by sending the ICM_DRAW_CHANGEPALETTE message (or use the ICDrawChangePalette macro) and obtain the current palette by sending the ICM_DRAW_GET_PALETTE message.

Some renderers must be specifically instructed to display frames passed to them. Sending the ICM_DRAW_RENDERBUFFER message (or use the ICDrawRenderBuffer macro) causes these renderers to draw the frame.


Using the Video Compression Manager

This section contains examples demonstrating how to perform the following tasks:

•	Locating and opening compressors and decompressors

•	Installing compressors and decompressors

•	Configuring compressors and decompressors

•	Obtaining information about compressors and decompressors

•	Determining a compressor’s output format

•	Compressing data

•	Determining a decompressor’s output format

•	Decompressing data

•	Determining if a driver can handle the input format

•	Preparing to draw data

•	Drawing data

•	Monitoring compressor and decompressor progress


Locating and Opening Compressors and Decompressors

The following example uses the ICLocate function to find a compressor that can compress an 8-bits-per-pixel bitmap.

BITMAPINFOHEADER bih;

HIC              hIC

// Initialize the bitmap structure.

bih.biSize = sizeof(BITMAPINFOHEADER);

bih.biWidth = bih.biHeight = 0;

bih.biPlanes = 1;

bih.biCompression = BI_RGB;      // standard RGB bitmap

bih.biBitcount = 8;              // 8 bits-per-pixel format

bih.biSizeImage = 0;

bih.biXPelsPerMeter = bih.biYPelsPerMeter = 0;

bih.biClrUsed = bih.biClrImportant = 256;

hIC = ICLocate (ICTYPE_VIDEO, 0L, (LPBITMAPINFOHEADER) &bih,

    NULL, ICMODE_COMPRESS);

The following example enumerates the decompressors in the system to find one that can handle the format of its images. This example uses ICTYPE_VIDEO (which is equivalent to the “VIDC” four-character code) and the ICDecompressQuery macro to determine if a compressor or decompressor supports the image format.

for (i=0; ICInfo(fccType, i, &icinfo); i++)

{

    hic = ICOpen(icinfo.fccType, icinfo.fccHandler, ICMODE_QUERY);

    if (hic)

    {

        // Skip this compressor if it can't handle the format.

        if (fccType == ICTYPE_VIDEO && pvIn != NULL &&

            ICDecompressQuery(hic, pvIn, NULL) != ICERR_OK)

        {

            ICClose(hic);

            continue;

        }

        // Find out the compressor name.

        ICGetInfo(hic, &icinfo, sizeof(icinfo));

        // Add it to the combo box.

        n = ComboBox_AddString(hwndC,icinfo.szDescription);

        ComboBox_SetItemData(hwndC, n, hic);

    }

}

The following example attempts to locate a specific compressor to compress the 8-bit RGB format to an 8-bit RLE format.

BITMAPINFOHEADER    bihIn, bihOut;

HIC                 hIC

// Initialize the bitmap structure.

biSize = bihOut.biSize = sizeof(BITMAPINFOHEADER);

bihIn.biWidth = bihIn.biHeight = bihOut.biWidth = bihOut.biHeight = 0;

bihIn.biPlanes = bihOut.biPlanes= 1;

bihIn.biCompression = BI_RGB;        // standard RGB bitmap for input

bihOut.biCompression = BI_RLE8;      // 8-bit RLE for output format

bihIn.biBitcount = bihOut.biBitCount = 8;  // 8 bits-per-pixel format

bihIn.biSizeImage = bihOut.biSizeImage = 0;

bihIn.biXPelsPerMeter = bih.biYPelsPerMeter =

    bihOut.biXPelsPerMeter = bihOut.biYPelsPerMeter = 0;

bihIn.biClrUsed = bih.biClrImportant =

    bihOut.biClrUsed = bihOut.biClrImportant = 256;

hIC = ICLocate (ICTYPE_VIDEO, 0L,

    (LPBITMAPINFOHEADER)&bihIn,

    (LPBITMAPINFOHEADER)&bihOut, ICMODE_COMPRESS);


Installing Compressors and Decompressors

The following example shows how an application can install a function as a compressor or decompressor using the ICInstall function.

// This function looks like a DriverProc entry point.

LRESULT MyCodecFunction(DWORD dwID, HDRVR hDriver,

    UINT uiMessage, LPARAM lParam1, LPARAM lParam2);

// This function installs the MyCodecFunction as a compressor.

result = ICInstall ( ICTYPE_VIDEO, mmioFOURCC('s','a','m','p'),

    (LPARAM)(FARPROC)&MyCodecFunction, NULL, ICINSTALL_FUNCTION);


Configuring Compressors and Decompressors

The following example uses the ICQueryConfigure macro to demonstrate how to test whether a compressor supports the configuration dialog box and to display it if it does.

// If the compressor handles a configuration dialog box, display it

// using our application window as the parent window.

if (ICQueryConfigure(hIC)) ICConfigure(hIC, hwndApp);

The following example shows how to obtain the state data using the ICGetState macro.

dwStateSize = ICGetStateSize(hIC);    // gets size of buffer required

h = GlobalAlloc(GHND, dwStateSize);   // allocates buffer

ICGetState(hIC, (LPVOID)lpData, dwStateSize);  // gets the state data

// Store the state data as required.

The following example shows how to restore state data using the ICSetState macro. State data restored by applications should not contain any changes to the state data obtained from a driver.

ICSetState(hIC, (LPVOID)lpData, dwStateSize); // sets new state data


Obtaining Information About Compressors and Decompressors

The following example uses the ICGetInfo function to obtain information about a compressor or decompressor.

ICINFO ICInfo;

ICGetInfo(hIC, &ICInfo, sizeof(ICInfo));

The following example uses the ICGetDefaultKeyFrameRate and ICGetDefaultQuality macros to obtain the default values.

DWORD dwKeyFrameRate, dwQuality;

dwKeyFrameRate = ICGetDefaultKeyFrameRate(hIC);

dwQuality = ICGetDefaultQuality(hIC);

The following example uses the ICQueryAbout and ICAbout macros to display an About dialog box for the compressor or decompressor, if the dialog box exists.

// If the compressor has an About dialog box, display it.

if ( ICQueryAbout(hIC)) ICAbout(hIC, hwndApp);


Determining a Compressor's Output Format
Determining a Compressor’s Output Format

The following example uses the ICCompressGetFormat size macro to determine the buffer size needed for the data specifying the compression format, allocates a buffer of the appropriate size using the GlobalAlloc function, and retrieves the compression format information using the ICCompressGetFormat macro.

LPBITMAPINFOHEADER	lpbiIn, lpbiOut;

// *lpbiIn must be initialized to the input format.

dwFormatSize = ICCompressGetFormatSize(hIC, lpbiIn);

h = GlobalAlloc(GHND, dwFormatSize);

lpbiOut = (LPBITMAPINFOHEADER)GlobalLock(h);

ICCompressGetFormat(hIC, lpbiIn, lpbiOut);

The following example uses the ICCompressQuery macro to determine whether a compressor can handle the input and output formats.

LPBITMAPINFOHEADER	lpbiIn, lpbiOut;

// Both *lpbiIn and *lpbiOut must be initialized to the respective
// formats.

if (ICCompressQuery(hIC, lpbiIn, lpbiOut) == ICERR_OK)

{

    // Format is supported; use the compressor.

}

The following example uses the ICCompressGetSize macro to determine the buffer size, and it allocates a buffer of that size using GlobalAlloc.

// Find the worst-case buffer size.

dwCompressBufferSize = ICCompressGetSize(hIC, lpbiIn, lpbiOut);

// Allocate a buffer and get lpOutput to point to it.

h = GlobalAlloc(GHND, dwCompressBufferSize);

lpOutput = (LPVOID)GlobalLock(h);


Compressing Data

The following example compresses image data for use in an AVI file. It assumes the compressor does not support the VIDCF_CRUNCH or VIDCF_TEMPORAL flags, but it does support VIDCF_QUALITY. The example uses the ICCompressBegin macro, the ICCompress function, and the ICCompressEnd macro.

DWORD dwCkID;

DWORD dwCompFlags;

DWORD dwQuality;

LONG  lNumFrames, lFrameNum;

// Assume dwNumFrames is initialized to the total number of frames.

// Assume dwQuality holds the proper quality value (0-10000).

// Assume lpbiOut, lpOut, lpbiIn, and lpIn are initialized properly.

// If OK to start, compress each frame.

if (ICCompressBegin(hIC, lpbiIn, lpbiOut) == ICERR_OK)

{

    for ( lFrameNum = 0; lFrameNum < lNumFrames; lFrameNum++)

    {

        if (ICCompress(hIC, 0, lpbiOut, lpOut, lpbiIn, lpIn,

            &dwCkID, &dwCompFlags, lFrameNum,

            0, dwQuality, NULL, NULL) == ICERR_OK)

        {

            // Write compressed data to the AVI file.

            // Set lpIn to the next frame in the sequence.

        }

        else

        {

            // Handle compressor error.

        }

    }

    ICCompressEnd(hIC);    // terminate compression

}

else

{

    // Handle the error identifying the unsupported format.

}


Determining a Decompressor's Output Format
Determining a Decompressor’s Output Format

The following example determines the buffer size needed for the data specifying the decompression format using the ICDecompressGetFormatSize macro, allocates a buffer of the appropriate size using the GlobalAlloc function, and retrieves the decompression format information using the ICDecompressGetFormat macro.

LPBITMAPINFOHEADER lpbiIn, lpbiOut;

// Assume *lpbiIn points to the input (compressed) format.

dwFormatSize = ICDecompressGetFormatSize(hIC, lpbiIn);

h = GlobalAlloc(GHND, dwFormatSize);

lpbiOut = (LPBITMAPINFOHEADER)GlobalLock(h);

ICDecompressGetFormat(hIC, lpbiIn, lpbiOut);

The following example shows how an application can use the ICDecompressQuery macro to determine if a decompressor can handle the input and output formats.

LPBITMAPINFOHEADER lpbiIn, lpbiOut;

// Assume *lpbiIn & *lpbiOut are initialized to the respective
// formats.

if (ICDecompressQuery(hIC, lpbiIn, lpbiOut) == ICERR_OK)

{

    // Format is supported - use the decompressor.

}

The following code fragment shows how to get the palette information using the ICDecompressGetPalette macro.

ICDecompressGetPalette(hIC, lpbiIn, lpbiOut);

// Move up to the palette.

lpPalette = (LPBYTE)lpbiOut + lpbi->biSize;


Decompressing Data

The following example shows how an application can initialize a decompressor using the ICDecompressBegin macro, decompress a frame sequence using the ICDecompress function, and terminate decompression using the ICDecompressEnd macro.

LPBITMAPINFOHEADER lbpiIn, lpbiOut;

LPVOID             lpIn, lpOut;

LONG               lNumFrames, lFrameNum;

// Assume lpbiIn and lpbiOut are initialized to the input and output

// format and lpIn and lpOut are pointing to the buffers.

if (ICDecompressBegin(hIC, lpbiIn, lpbiOut) == ICERR_OK)

{

    for (lFrameNum = 0; lFrameNum < lNumFrames, lFrameNum++)

    {

        if (ICDecompress(hIC, 0, lpbiIn, lpIn, lpbiOut,

            lpOut) == ICERR_OK)

        {

            // Frame decompressed OK so we can process it as required.

        }

        else

        {

            // Handle the decompression error that occurred.

        }

    }

    ICDecompressEnd(hIC);

}

else

{

    // Handle the error identifying an unsupported format.

}


Determining If a Driver Can Handle the Input Format

The following example shows how to check the input format with the ICDrawQuery macro.

// lpbiIn points to BITMAPINFOHEADER structure indicating the input

// format.

if (ICDrawQuery(hIC, lpbiIn) == ICERR_OK)

{

    // Driver recognizes the input format.

}

else

{

    // Need a different decompressor.

}


Preparing to Draw Data

The following example shows the initialization sequence that instructs the decompressor to draw full-screen. It uses the ICDrawBegin and ICDrawEnd macros.

// Assume lpbiIn has the input format, dwRate has the data rate.

if (ICDrawBegin(hIC, ICDRAW_QUERY | ICDRAW_FULLSCREEN, NULL, NULL,

    NULL, 0, 0, 0, 0, lpbiIn, 0, 0, 0, 0, dwRate,

    dwScale) == ICERR_OK)

{

    // Decompressor supports this drawing so set up to draw.

    ICDrawBegin(hIC, ICDRAW_FULLSCREEN, hPal, NULL, NULL, 0, 0, 0,

        0, lpbiIn, 0, 0, lbpi->biWidth, lpbi->biHeight, dwRate,

        dwScale);

    .

    . // Start decompressing and drawing frames.

    .

    // Drawing done. Terminate procedure.

    ICDrawEnd(hIC);

}

else

{

    // Use another renderer to draw data on the screen;

    // ICDraw does not support the format.

}


Drawing Data

The following example uses the ICDraw function and the ICDrawStart, ICDrawStop, ICDrawFlush, and ICDrawEnd macros to draw data on the screen.

DWORD    dwNumBuffers;

// Find out how many buffers need filling before drawing starts.

ICGetBuffersWanted(hIC, &dwNumBuffers);

for (dw = 0; dw < dwNumBuffers; dw++)

{

    ICDraw(hIC, 0, lpFormat, lpData, cbData, dw); // fill the pipeline

    // Point lpFormat and lpData to next format and buffer.

}

ICDrawStart(hIC);  // starts the clock

dw = 0;

while (fPlaying)

{

    ICDraw(hIC, 0, lpFormat, lpData, chData, dw); // fill more buffers

    // Point lpFormat and lpData to next format and buffer,

    // update dw.

}

ICDrawStop(hIC);   // stops drawing and decompressing when done

ICDrawFlush(hIC);  // flushes any existing buffers

ICDrawEnd(hIC);    // ends decompression


Monitoring Compressor and Decompressor Progress

The following example shows how the ICSetStatusProc function is used to inform the compressor or decompressor of the callback function address:

ICSetStatusProc(compvars.hic, 0, (LPARAM) (UINT) hwndApp,

    &PreviewStatusProc);

The following example shows the callback function installed by the previous fragment:

LONG CALLBACK export PreviewStatusProc(LPARAM lParam,

    UINT message, LONG l)

{

    switch (message)

    {

        MSG msg;

        case ICSTATUS_START:

        // Create and display status dialog box.

            break;

        case ICSTATUS_STATUS:

            ProSetBarPos((int) l); // sets status bar positions

        // Watch for abort message

            while(PeekMessage(&msg, NULL, 0, 0, PM_REMOVE))

            {

                if (msg.message == WM_KEYDOWN && msg.wParam ==

                    VK_ESCAPE)

                    return 1;

                if (msg.message == WM_SYSCOMMAND &&

                    (msg.wParam & 0xFFF0) == SC_CLOSE)

                    return 1;

                TranslateMessage(&msg);

                DispatchMessage(&msg);

            }

            break;

        case ICSTATUS_END:

        // Close and destroy status dialog box.

            break;

        case ICSTATUS_YIELD:

            break;

    }

    return 0;

}


Video Compression Manager Reference

This section describes the functions, structures, messages, and macros, associated with VCM. These elements are grouped as follows.

Compressor Installation and Removal

ICInstall
ICLocate
ICOPEN
ICClose
ICRemove
ICOpenFunction

Locating and Opening a Compressor

ICLocate
ICOPEN
ICDecompressOpen
ICDrawOpen
ICINFO
ICClose

Selecting Compressors

ICCompressorChoose
ICCompressorFree
COMPVARS

Configuring Compressors

ICM_CONFIGURE
ICM_GETSTATE
ICM_SETSTATE
ICSendMessage

Compressor Information

ICGetInfo
ICINFO
ICM_GETDEFAULTKEYFRAMERATE
ICGetDisplayFormat
ICM_GETDEFAULTQUALITY
ICM_ABOUT

Single Image Compression

ICImageCompress

Sequence Compression

ICSeqCompressFrame
ICSeqCompressFrameStart
ICSeqCompressFrameEnd

COMPVARS

ICCompressorChoose

Image Data Compression

ICCOMPRESS
ICM_COMPRESS_GET_FORMAT
ICM_COMPRESS_QUERY
ICM_COMPRESS_GET_SIZE
ICM_COMPRESS_BEGIN
ICM_COMPRESS_END

Compressor Monitoring

ICSETSTATUSPROC

Decompressing Single Images

ICImageDecompress

Decompressing Image Data

ICDECOMPRESSEX
ICDecompressExBegin
ICM_DECOMPRESSEX_END
ICM_DECOMPRESS_GET_FORMAT
ICM_DECOMPRESS_GET_PALETTE
ICDecompressExQuery
ICDECOMPRESS
ICM_DECOMPRESS_BEGIN
ICM_DECOMPRESS_END
ICM_DECOMPRESS_QUERY

Using Hardware-Drawing Capabilities

ICGetInfo
ICDRAWBEGIN
ICM_DRAW_END
ICM_DRAW_FLUSH
ICM_DRAW_QUERY
ICDrawSuggestFormat
ICM_DRAW_START
ICM_DRAW_STOP
ICM_GETBUFFERSWANTED
ICM_DRAW_REALIZE
ICDrawOpen
ICDRAW
ICM_DRAW_GETTIME
ICM_DRAW_SETTIME
ICM_DRAW_WINDOW
ICM_DRAW_REALIZE
ICM_DRAW_CHANGEPALETTE
ICM_DRAW_RENDERBUFFER


Video Compression Functions

The following functions are used with video compression.

ICClose
ICCompress
ICCompressorChoose
ICCompressorFree
ICDecompress
ICDecompressEx
ICDecompressExBegin
ICDecompressExQuery
ICDraw
ICDrawBegin
ICDrawSuggestFormat
ICGetDisplayFormat
ICGetInfo
ICImageCompress
ICImageDecompress
ICInfo
ICInstall
ICLocate
ICOpen
ICOpenFunction
ICRemove
ICSendMessage
ICSeqCompressFrame
ICSeqCompressFrameEnd
ICSeqCompressFrameStart
ICSetStatusProc
MyStatusProc


Video Compression Structures

The following structures are used with video compression.

COMPVARS
ICCOMPRESS
ICCOMPRESSFRAMES
ICDECOMPRESS
ICDECOMPRESSEX
ICDRAW
ICDRAWBEGIN
ICDRAWSUGGEST
ICINFO
ICOPEN
ICSETSTATUSPROC


Video Compression Messages

The following messages are used with video compression.

ICM_ABOUT
ICM_COMPRESS
ICM_COMPRESS_BEGIN
ICM_COMPRESS_END
ICM_COMPRESS_FRAMES_INFO
ICM_COMPRESS_GET_FORMAT
ICM_COMPRESS_GET_SIZE
ICM_COMPRESS_QUERY
ICM_CONFIGURE
ICM_DECOMPRESS
ICM_DECOMPRESS_BEGIN
ICM_DECOMPRESS_END
ICM_DECOMPRESS_GET_FORMAT
ICM_DECOMPRESS_GET_PALETTE
ICM_DECOMPRESS_QUERY
ICM_DECOMPRESS_SET_PALETTE
ICM_DECOMPRESSEX
ICM_DECOMPRESSEX_BEGIN
ICM_DECOMPRESSEX_END
ICM_DECOMPRESSEX_QUERY
ICM_DRAW
ICM_DRAW_BEGIN
ICM_DRAW_CHANGEPALETTE
ICM_DRAW_END
ICM_DRAW_FLUSH
ICM_DRAW_GET_PALETTE
ICM_DRAW_GETTIME
ICM_DRAW_QUERY
ICM_DRAW_REALIZE
ICM_DRAW_RENDERBUFFER
ICM_DRAW_SETTIME
ICM_DRAW_START
ICM_DRAW_START_PLAY
ICM_DRAW_STOP
ICM_DRAW_STOP_PLAY
ICM_DRAW_SUGGESTFORMAT
ICM_DRAW_WINDOW
ICM_GET
ICM_GETBUFFERSWANTED
ICM_GETDEFAULTKEYFRAMERATE
ICM_GETDEFAULTQUALITY
ICM_GETINFO
ICM_GETQUALITY
ICM_GETSTATE
ICM_SET_STATUS_PROC
ICM_SETQUALITY
ICM_SETSTATE


Video Compression Macros

The following macros are used with video compression.

ICAbout
ICCompressBegin
ICCompressEnd
ICCompressGetFormat
ICCompressGetFormatSize
ICCompressGetSize
ICCompressQuery
ICConfigure
ICDecompressBegin
ICDecompressEnd
ICDecompressExEnd
ICDecompressGetFormat
ICDecompressGetFormatSize
ICDecompressGetPalette
ICDecompressOpen
ICDecompressQuery
ICDecompressSetPalette
ICDrawChangePalette
ICDrawEnd
ICDrawFlush
ICDrawGetTime
ICDrawOpen
ICDrawQuery
ICDrawRealize
ICDrawRenderBuffer
ICDrawSetTime
ICDrawStart
ICDrawStartPlay
ICDrawStop
ICDrawStopPlay
ICDrawWindow
ICGetBuffersWanted
ICGetDefaultKeyFrameRate
ICGetDefaultQuality
ICGetState
ICGetStateSize
ICQueryAbout
ICQueryConfigure
ICSetState


Custom File and Stream Handlers

File and stream handlers are drivers that provide consistent interfaces to an application that controls multimedia data. The file and stream handlers included in the operating system use video and waveform-audio data stored in audio-video interleaved (AVI) and waveform-audio files.

You can write handlers to allow your application to write or access multimedia data from another source, such as a file using a proprietary format, an AVI file that has been expanded to contain additional data streams, or a handler that generates its own multimedia data. If you have a custom file format for AVI data that you would like to use with the AVIFile functions and macros, you need to write a custom handler.


About Custom File and Stream Handlers

Your application can use a custom file handler to read from a file or write to a file that is in a nonstandard format. To do this, your application simply uses the name of your file handler when opening the file or allocating the file interface. The AVIFile library then uses the functions from your file handler instead of those from another file handler. The nonstandard format appears as standard AVI data to your application or to any other application using your custom file handler.

Similarly, your application can use a custom stream handler to read a stream that is in a nonstandard format. A stream — whether it constitutes audio, video, MIDI, text, or custom data — is a component of an AVI file. For example, an AVI file that contains a video sequence, an English soundtrack, and a French soundtrack consists of three streams. Your application can specify the streams in an AVI file to process and direct each of those streams to a handler that can optimally process the appropriate type of multimedia data.

Note  You must place custom stream and file handlers in one or more DLLs, separated from main application files.


Handler Architecture

The internal function of a file or stream handler is defined by the handler itself. To an application, a file handler typically appears as a module to read and write AVI files. Similarly, a stream handler appears as a module to read and write a specific type of data stream. The consistent stream interface makes the source and destination of the stream unimportant to the application that uses the handler.

A file handler provides access to a data source consisting of one or more data streams. File handlers typically provide access to disk files containing one or more data streams, and the internal functions of the file handler read and write the multimedia data. However, file handlers can work with any data source, such as a digital transmission channel containing several intermingled data streams.

In contrast, a stream handler processes one type of data and appears as a data stream to an application. A stream handler can provide data that it manufactures, or it can retrieve data from a file or an external source. It supplies its data in a format that your application can use.


C++ main:0000
C++ and OLE Programming Concepts

The file and stream handlers included with Windows use an object-oriented design to promote a standard interface and to share functionality. These handlers are written in C++ and use the OLE Component Object Model.

You can develop custom handlers using the C or C++ development systems; however, using C++ is strongly recommended, because it provides an easier and more straightforward approach to implement a handler. Using C++, you can explicitly define data as objects, and you can associate the functions that manipulate the data with the member functions of an object.

This section identifies and briefly summarizes the important concepts of C++ and the OLE Component Object Model that apply to designing and implementing file and stream handlers. There are many books written about C++ programming that you can reference for more information. For more information on OLE, please see the OLE Programmer’s Reference.


Classes, Objects, and Interfaces

In the C++ programming language, a class consists of properties (or member data) and methods (or member functions). The properties are data elements, such as those contained in a structure. The methods are used for a variety of purposes, such as initialization, assignment, operations, and data access. You use a class declaration in the same way that you use a structure declaration. Memory is allocated for a class when you define a class object. Each class object has a data area for its properties and a table of pointers to the methods it supports.

In OLE, an object consists of data and methods, as it does in C++. However, an OLE object adheres to stricter rules. The data is strictly internal. An object only exposes interfaces. An interface is a set of related methods for an object. Each object can support multiple interfaces. All OLE interfaces support the IUnknown interface.


The Scope Resolution Operator in C++

Two colons (::) are used in C+ + as a scope resolution operator. This operator gives you more freedom in naming your variables by letting you distinguish between variables with the same name. For example, MyFile::Read refers to the Read method of the MyFile class of objects, as opposed to YourFile::Read, which refers to a Read method in the YourFile class.


Virtual Function Tables

A virtual function table is an array of pointers to the methods an object supports. If you’re using C, an object appears as a structure whose first member is a pointer to the virtual function table (lpVtbl); that is, the first member points to an array containing function pointers. The methods all take a pointer to the function table as the first parameter. Thus, the following example calls the Read method of a pStream object:

pStream->lpVtbl->Read(pStream, parameters)

In C+ +, the pointer to the virtual function table, the this pointer, is implicit. The following is equivalent to the previous example when using C+ +:

pStream->Read(parameters)


The OLE Component Object Model

The objects used by the AVIFile library are all part of the OLE Component Object Model. Primarily, this means they share certain methods that make them easier to work with, and the values they return are common to most OLE interface methods.

The OLE Component Object Model of the file and stream handlers uses the OLE IClassFactory interface to create instances of their object class. As component objects, they implement the the IUnknown interface, which consists of the QueryInterface, Release, and AddRef methods. The IUnknown interface lets an application obtain pointers to other interfaces supported by the same object.

You can determine if an object supports a specific interface by using the QueryInterface method. If an object supports a specified interface, QueryInterface returns a pointer to that interface.

You can increment and decrement the reference count associated with an object by using the AddRef and Release methods. The reference count lets multiple clients access an object. When an object is used by the first application, its reference count is set to 1. Applications subsequently use the AddRef method to increment the count to let the object keep track of the number of times it is accessed.

When an application is done using an object, it calls the Release method to decrement the reference count. When the reference count is zero, the object is no longer needed and Release frees any resources it uses and destroys the object. Because an object uses internal resources transparent to the application, the object is responsible for freeing them. For example, a file handler might need to close open disk files and free buffer memory when released.

Most OLE interface methods return result handles that are defined by using the HRESULT data type. This data type is made of a severity code, contextual information, a facility code, and a status code. A return result handle that indicates success has the value zero. A nonzero value indicates failure and the status code member of the return result handle provides a basis for additional interpretation. For additional information about OLE return result handles, see the OLE Programmer’s Reference.


IAVIStream and IAVIFile Interfaces

The IAVIStream and IAVIFile interfaces contain the methods used by file and stream handlers. The PAVISTREAM data type is a pointer to an AVI stream object (through the IAVIStream interface) and the PAVIFILE data type is a pointer to an AVI file object (through the IAVIFile interface).

To create an object pointer in C, first allocate space for a structure that is large enough to contain the pointer to the virtual function table and the other data members. Create a virtual function table for the methods for your type of stream, then set the pointer to the virtual function table to the address of the virtual function table.


File and Stream Handler Installation

The AVIFile library uses installed stream and file handlers for reading and writing AVI files and streams. A handler is installed when it resides in the Windows SYSTEM directory and the registry contains the following information needed to describe and identify a handler:

•	The 16-byte class identifier for the handler

•	A brief description of the handler

•	The name of the file containing the handler

•	The file extension that a file handler can process

•	File-access and other properties associated with a file handler

•	Four-character codes identifying stream types that a stream handler can process

The AVIFile library queries the registry for handlers that are external to an application when opening files and accessing streams. The result of a successful query returns the filename of a handler that can process the file or stream type specified in the query. The registry lists each handler by creating three entries that have the following form:

[HKEY_CLASSES_ROOT\Clsid\{00010023-0000-0000-C000-000000000046}]

@="Wave File reader/writer"

[HKEY_CLASSES_ROOT\Clsid\{00010023-0000-0000-C000-

000000000046}\InprocServer32]

@="wavefile.dll"

"ThreadingModel"="Apartment"

[HKEY_CLASSES_ROOT\Clsid\{00010023-0000-0000-C000-

000000000046}\AVIFile]

@="3"

These entries consist of the following parts.

Part	Description
HKEY_CLASSES_ROOT	Identifies the root entry of the registry.
Clsid	Identifies this entry as a class identifier.
{00010023-0000-0000-C000-000000000046}	Specifies an interface identifier (IID) or class identifier. This value is a unique 16-byte identifier. (The identifier might also be referred to as a GUID or a UUID in other manuals.)
Wave File reader/writer	Specifies a string to describe the handler. This string can be displayed in dialog boxes for selecting stream and file handlers.
InProcServer32	Specifies the file (in this example, WAVEFILE.DLL) that can be loaded to handle this class.
AVIFile	Specifies the properties of a file handler. In this example, the handler can read and write to an AVI file.
A file handler can have one or more of its properties stored in the registry. The following constants identify the properties currently associated with a file.

Constant	Description
AVIFILEHANDLER_CANACCEPTNONRGB	Indicates that a file handler can process image data other than RGB.
AVIFILEHANDLER_CANREAD	Indicates that a file handler can open a file with read access.
AVIFILEHANDLER_CANWRITE	Indicates that a file handler can open a file with write access.
When creating a file or stream handler, you can obtain a new identifier by running UUIDGEN.EXE. Always use UUIDGEN.EXE to create a new identifier. The 16-byte hexadecimal number created by this executable will uniquely identify your handler.

The AVIFile library uses additional entries in the registry to identify a class identifier based on the file extension that a file handler can process or a four-character code that a file or stream handler can process. For example, the following entries associate a class identifier with the file extension .WAV and the four-character code “WAVE”:

[HKEY_CLASSES_ROOT\AVIFile\Extensions\WAV]

@="{00010023-0000-0000-C000-000000000046}"

[HKEY_CLASSES_ROOT\AVIFile\RIFFHandlers\WAVE]

@="{00010023-0000-0000-C000-000000000046}"

These entries consist of the following parts.

Part	Description
HKEY_CLASSES_ROOT	Identifies the root entry of the registry.
AVIFile	Identifies this entry as an entry used by AVIFile.
Extensions	Specifies the file extension (in this example, .WAV) that a file handler can process.
RIFFHandlers	Specifies the four-character code (in this example, “WAVE”) a file or stream handler can process.
{00010023-0000-0000-C000-000000000046}	Specifies an interface identifier (IID) or class identifier.
If you distribute your stream or file handler without a setup application to install it in the user’s system, you must include a .REG file so the user can install the handler. The user will use the registry editor to create registry entries for your stream or file handler.

The following example shows the contents of a typical .REG file. The first entry in the following example is the descriptive string for the handler. The second entry identifies the file containing the handler. The third entry identifies the properties of the file handler (in this case, read-only access to files). The fourth entry associates the type of file the handler processes (in this case, files with a .JPG filename extension) with the class identifier.

[HKEY_CLASSES_ROOT\Clsid\{5C2B8200-E2C8-1068-B1CA-6066188C6002}]

@="JFIF (JPEG) Files"

[HKEY_CLASSES_ROOT\Clsid\{5C2B8200-E2C8-1068-B1CA-6066188C6002}]\InprocServer32]

@="jfiffile.dll"

[HKEY_CLASSES_ROOT\AVIFile\Extensions\JPG]

@="{5C2B8200-E2C8-1068-B1CA-6066188C6002}"

When creating this file, save it with a .REG extension to identify it as an update file for the registry. Also, substitute a unique IID for the 16-byte code used in the example.

Users can update the registry on their system by using the following procedure:

1.	Click the Start menu (or run Program Manager and click the File menu), then click Run.

2.	In the Run dialog box, type the following command and press ENTER:

regedit -s filename.reg


Using Custom File and Stream Handlers

•	Creating a file or stream handler

•	Creating a virtual function table for a stream handler

•	Creating an object pointer

•	Obtaining the address of a virtual function table

•	Creating a file-handler instance in a DLL

•	Determining which interface an object supports

•	Incrementing the handler reference count

•	Deleting an object


Creating a File or Stream Handler

In an application written in the C programming language, a file or stream handler usually creates a function for each method. Your application accesses these functions through an array of function pointers the stream handler creates. An IAVIStreamVtbl structure contains the array of function pointers. A stream handler can assign any name it wants to functions it creates for the methods. The position of the function pointer in the structure implies the correspondence of the function to the method. For example, the first function pointer in the structure corresponds to the QueryInterface method. Your stream handler must provide all the functions of an interface.


Creating a Virtual Function Table for a Stream Handler

The following example (written in C) shows how an application (AVIBall) creates the virtual function table  used to reference its services.

HRESULT STDMETHODCALLTYPE AVIBallQueryInterface (PAVISTREAM ps,

    REFIID riid, LPVOID FAR* ppvObj);

HRESULT STDMETHODCALLTYPE AVIBallCreate (PAVISTREAM ps,

    LONG lParam1, LONG lParam2);

ULONG STDMETHODCALLTYPE AVIBallAddRef (PAVISTREAM ps);

ULONG STDMETHODCALLTYPE AVIBallRelease (PAVISTREAM ps);

HRESULT STDMETHODCALLTYPE AVIBallInfo (PAVISTREAM ps,

    AVIStreamHeader FAR * psi, LONG lSize);

LONG STDMETHODCALLTYPE AVIBallFindSample (PAVISTREAM ps,

    LONG lPos, LONG lFlags);

HRESULT STDMETHODCALLTYPE AVIBallReadFormat (PAVISTREAM ps,

    LONG lPos, LPVOID lpFormat, LONG FAR *lpcbFormat);

HRESULT STDMETHODCALLTYPE AVIBallSetFormat (PAVISTREAM ps,

    LONG lPos, LPVOID lpFormat, LONG cbFormat);

HRESULT STDMETHODCALLTYPE AVIBallRead (PAVISTREAM ps,

    LONG lStart, LONG lSamples, LPVOID lpBuffer, LONG cbBuffer,

    LONG FAR * plBytes,LONG FAR * plSamples);

HRESULT STDMETHODCALLTYPE AVIBallWrite (PAVISTREAM ps, LONG lStart,

    LONG lSamples, LPVOID lpBuffer, LONG cbBuffer, DWORD dwFlags);

HRESULT STDMETHODCALLTYPE AVIBallDelete (PAVISTREAM ps,

    LONG lStart, LONG lSamples);

HRESULT STDMETHODCALLTYPE AVIBallReadData (PAVISTREAM ps,

    DWORD fcc, LPVOID lp,LONG FAR *lpcb);

HRESULT STDMETHODCALLTYPE AVIBallWriteData (PAVISTREAM ps,

    DWORD fcc, LPVOID lp,LONG cb);

IAVIStreamVtbl AVIBallHandler = {

    AVIBallQueryInterface,  // Function pointer for ::QueryInterface

    AVIBallAddRef,          // Function pointer for ::AddRef

    AVIBallRelease,         // Function pointer for ::Release

    AVIBallCreate,          // Function pointer for ::Create

    AVIBallInfo,            // Function pointer for ::Info

    AVIBallFindSample,      // Function pointer for ::FindSample

    AVIBallReadFormat,      // Function pointer for ::ReadFormat

    AVIBallSetFormat,       // Function pointer for ::SetFormat

    AVIBallRead,            // Function pointer for ::Read

    AVIBallWrite,           // Function pointer for ::Write

    AVIBallDelete,          // Function pointer for ::Delete

    AVIBallReadData,        // Function pointer for ::ReadData

    AVIBallWriteData        // Function pointer for ::WriteData

};

File handlers use a similar procedure, except they use a different definition for the virtual function table.


Creating an Object Pointer

AVIBall uses the following structure as its object pointer. The first member of this structure points to the virtual function table that AVIBall uses to access its functions. Applications can cast this structure to the PAVISTREAM data type. Methods that use the PAVISTREAM data type use only the pointer to the virtual function table. The members following the pointer to the virtual function table are used internally by AVIBall.

typedef struct

{

    IAVIStreamVtbl FAR * lpvtbl;

    // Ball instance data.

    ULONG	  ulRefCount;

    DWORD	  fccType;  // is this audio/video?

    int	  width;    // size, in pixels, of each frame

    int	  height;

    int	  length;   // length, in frames

    int	  size;

    COLORREF	 color;    // ball color

} AVIBALL, FAR * PAVIBALL;


Obtaining the Address of a Virtual Function Table

In an application written in the C programming language, you can retrieve the address of the IAVIStreamVtbl structure by using the NewBall function. This function returns the address of a structure containing a pointer to IAVIStreamVtbl. Information following the IAVIStreamVtbl pointer specifies data used internally by AVIBall. Your stream handler can append its own information after the IAVIStreamVtbl pointer. This information is returned in subsequent calls to your stream handler.

PAVISTREAM WINAPI NewBall(VOID)

{

    PAVIBALL pball;

    pball = (PAVIBALL) GlobalAllocPtr(GHND, sizeof(AVIBALL));

    if (!pball)

        return 0;

    pball->lpvtbl = &AVIBallHandler;

    pball->lpvtbl->Create((PAVISTREAM) pball, 0, 0);

    return (PAVISTREAM) pball;

}


Creating a File-Handler Instance in a DLL

When an application specifies your file-handler DLL or stream handler, the system looks it up in the registry by its class identifier and loaded. The system then calls the DllGetClassObject function of the DLL to create an instance of the file or stream handler. The following example (written in C++) shows how a file handler creates an instance.

// Main DLL entry point.

STDAPI DllGetClassObject(const CLSID FAR& rclsid,

    const IID FAR& riid, void FAR* FAR* ppv)

{

    HRESULT hresult;

    hresult = CAVIFileCF::Create(rclsid, riid, ppv);

    return hresult;

}

HRESULT CAVIFileCF::Create(const CLSID FAR&	rclsid,

    const IID FAR& riid, void FAR* FAR*	ppv)

{

// The following is the class factory creation and not an

// actual PAVIFile.

    CAVIFileCF FAR*	pAVIFileCF;

    IUnknown FAR*	pUnknown;

    HRESULT hresult;

// Create the instance.

    pAVIFileCF = new FAR CAVIFileCF(rclsid, &pUnknown);

    if (pAVIFileCF == NULL)

        return ResultFromScode(E_OUTOFMEMORY);

// Set the interface pointer.

    hresult = pUnknown->QueryInterface(riid, ppv);

    if (FAILED(GetScode(hresult)))

        delete pAVIFileCF;

    return hresult;

}


Determining Which Interface an Object Supports

The QueryInterface method lets an application query an object to determine which interfaces it supports. The sample application sets the ppv pointer to the current interface.

STDMETHODIMP CAVIFileCF::QueryInterface(

    const IID FAR& iid,

    void FAR* FAR* ppv)

{

    if (iid == IID_IUnknown)

        *ppv = this;                     // set the interface pointer

                                         // to this instance

    else if (iid == IID_IClassFactory)

        *ppv = this;                     // second chance to set the

                                         // interface pointer to this

                                         // instance

    else

        return ResultFromScode(E_NOINTERFACE);

    AddRef();  //Increment the reference count

    return NULL;

}


Incrementing the Handler Reference Count

The AddRef method increments the stream-hander or file-handler reference count.

STDMETHODIMP_(ULONG) CAVIFileCF::AddRef()

{

    return ++m_refs;

}


Deleting an Object

The Release method deletes the object when its reference count is zero.

STDMETHODIMP_(ULONG) CAVIFileCF::Release()

{

    if (!--m_refs)

    {

        delete this;   // If O, delete this instance.

        return 0;

    }

    return m_refs;

}


Custom File and Stream Handler Reference

The following functions and interfaces are used with custom file and stream handlers.


Custom File and Stream Handler Functions

The following function is used with custom file and stream handlers.

DllGetClassObject


Custom File and Stream Handler Interfaces

The following interfaces and member functions are used with custom file and stream handlers.

IAVIEditStream
IAVIEditStream::Clone
IAVIEditStream::Copy
IAVIEditStream::Cut
IAVIEditStream::Paste
IAVIEditStream::SetInfo
IAVIFile
IAVIFile::CreateStream
IAVIFile::EndRecord
IAVIFile::GetStream
IAVIFile::Info
IAVIFile::Open
IAVIFile::ReadData
IAVIFile::WriteData
IAVIStream
IAVIStream::Create
IAVIStream::Delete
IAVIStream::FindSample
IAVIStream::Info
IAVIStream::Read
IAVIStream::ReadData
IAVIStream::ReadFormat
IAVIStream::SetFormat
IAVIStream::Write
IAVIStream::WriteData
IAVIStreaming
IAVIStreaming::Begin
IAVIStreaming::End
IGetFrame
IGetFrame::Begin
IGetFrame::End
IGetFrame::GetFrame
IGetFrame::SetFormat
IUnknown
IUnknown::QueryInterface
IUnknown::AddRef
IUnknown::Release


AVIFile Functions and Macros

AVIFile functions and macros provide access to time-based files that use the resource information file format (RIFF), such as waveform-audio and audio-video interleaved (AVI) files. These functions and macros manage RIFF files, making it unnecessary for you to manage and navigate through the RIFF architecture.


About AVIFile Functions and Macros

The AVIFile functions and macros handle the information in time-based files as one or more data streams instead of tagged blocks of data called chunks. Data streams refer to the components of a time-based file. An AVI file can contain several different types of data, such as a video sequence, an English soundtrack, and a French soundtrack. Using AVIFile, an application can access each of these components separately.

Note  Although the AVIFile functions and macros work with any RIFF file, this overview demonstrates their use with AVI files only. AVI files are typically the time-based files used with the AVIFile macros and functions.

AVIFile functions and macros are contained in a dynamic-link library. To initialize the library, use the AVIFileInit function. After you initialize the library, you can use any of the AVIFile functions or macros. To release the library, use the AVIFileExit function. AVIFile maintains a reference count of the applications that are using the library, but not those that have released it. Your applications should balance each use of AVIFileInit with a call to AVIFileExit to completely release the library after each application finishes using it.


Function Data Types and Return Values

The AVIFile functions and macros use file and stream handlers implemented with OLE technology. The standard data type of an OLE function is STDAPI, and the function returns an HRESULT value (zero for success or an error otherwise). If a function returns a value other than an HRESULT, the type of the function’s prototype has a slightly different syntax that embeds the return value type in parentheses following STDAPI_. For example, a function that returns a LONG data value uses STDAPI_(LONG) in the prototype statement.


AVIFile Operations

This section describes the AVIFile file input and output (I/O) operations.

•	Opening and Closing Files

•	Reading from a File

•	Writing to a File

•	Using the Clipboard with AVI Files


Opening and Closing Files

An application must open an AVI file before reading or writing. To open an AVI file, use the AVIFileOpen function. AVIFileOpen returns the address of an AVI file interface that contains the handle of the open file and increments the reference count of the file.

The AVIFileOpen function supports the OF flags used with the OpenFile function. If an application writes to an existing file, it must include the OF_WRITE flag in AVIFileOpen. Similarly, if your application creates and writes to a new file, you must include the OF_CREATE and OF_WRITE flags in AVIFileOpen.

When you open a file using AVIFileOpen, you can use a default file handler or you can specify a custom file handler to read and write to the file and its data streams. In either case, AVIFile searches the registry for the correct file handler to use. You must ensure custom file handlers are in the registry before an application can access them.

You can increment the reference count of a file by using the AVIFileAddRef function. For example, you might want to do this when passing a handle of the file interface to another application, or when you want to keep a file open while using a function that would normally close the file.

You can close a file by using the AVIFileRelease function. The AVIFileRelease function decrements the reference count of an AVI file, saves changes made to the file, and when the reference count reaches zero, closes the file. Your applications should balance the reference count by including a call to AVIFileRelease for each use of AVIFileOpen and AVIFileAddRef.

Note  An application can open a file with one or more program threads. However, for the best possible performance, only one thread should access the file at any one time.


Reading from a File

You can retrieve information about an open file by using the AVIFileInfo function. This function fills the AVIFILEINFO structure with such information as the maximum data rate, the number of streams in the file, whether the file uses an index, and whether the file is copyrighted.

To retrieve supplementary information in an AVI file, use the AVIFileReadData function. Supplementary information is applicable to the entire file and is not included in the normal file headers. For example, the name of the company or person who holds the copyrights of a file could be supplementary information. Supplementary information does not adhere to a specific format; it can be file specific. AVIFileReadData returns the supplementary information in an application-supplied buffer.


Writing to a File

You can write supplementary information to a file that has been opened with write privileges by using the AVIFileWriteData function. This function copies the information from an application-supplied buffer and places it in one or more chunks in the file. The “INFO” chunk is a common RIFF chunk type in which the function stores supplementary information. For a description of RIFF files and their data chunks, see File Input and Output.


Using the Clipboard with AVI Files

The clipboard provides convenient, temporary storage that an application can use to copy or transfer AVI files. AVIFile includes clipboard functions that you can use with disk or memory files.

You can copy a file to the clipboard by using the AVIPutFileOnClipboard function. To write a file that is on the clipboard to memory or disk, use the AVIGetFromClipboard function.

You can clear a file from the clipboard by using the AVIClearClipboard function. This function does not clear other types of information, such as text, from the clipboard. If you use clipboard functions in your application, clear the clipboard with AVIClearClipboard before closing the application or closing the file on the clipboard. You can call AVIClearClipboard in your application whether or not AVIPutFileOnClipboard has been used.

Note  If your application copies a file to the clipboard and the file contains stream data that might change, you can create a memory file of cloned streams by using the AVIMakeFileFromStreams function. You can then place the file on the clipboard and then release the original file without invalidating it.


Stream Operations

Most of the features of AVIFile focus on data streams. This section describes the functions and macros that deal with streams and stream data.

•	Opening and Closing Streams

•	Reading from a Stream

•	Working with Compressed Video Data in a Stream

•	Creating a File from Existing Streams

•	Writing Streams to a File

•	Positioning in Streams

•	Creating Temporary Streams

•	Editing Streams


Opening and Closing Streams

Opening data streams is similar to opening files. You can open a stream by using the AVIFileGetStream function. This function creates a stream interface, places a handle of the stream in the interface, and returns a pointer to the interface. AVIFileGetStream also maintains a reference count of the applications that have opened a stream, but not of those that have closed it.

If you want to access a single stream in a file, you can open the file and the stream by using the AVIStreamOpenFromFile function. This function combines the operations and function arguments of the AVIFileOpen and AVIFileGetStream functions.

To access more than one stream in a file, use AVIFileOpen once followed by multiple calls to AVIFileGetStream.

You can increment the reference count of a stream by using the AVIStreamAddRef function to keep a stream open when using a function that would normally close the stream.

You can close a stream by using the AVIStreamRelease function. This function decrements the reference count of the stream and closes it when the reference count reaches zero. Your applications should balance the reference count by including a call to AVIStreamRelease for each use of the AVIFileGetStream, AVIFileCreateStream, AVIStreamAddRef, or AVIStreamOpenFromFile function. When you release a stream that has been opened by using AVIStreamOpenFromFile, AVIFile closes the file containing the stream. If your application releases a file that has open data streams, AVIFile will not close the streams until all of the streams are released.


Reading from a Stream

You can retrieve information about an open stream by using the AVIStreamInfo function. This function fills the AVISTREAMINFO structure with information such as the type of data in the stream, the compression method used when writing stream data, the suggested buffer size, the playback rate, and a text description of the stream.

Some members of the AVISTREAMINFO structure are also present in the AVIFILEINFO structure. The information in the AVIFILEINFO structure applies to the entire file. The information in the AVISTREAMINFO structure is specific to the accessed stream and has precedence over the information in the AVIFILEINFO structure.

If a stream has supplementary information associated with it, you can retrieve this information by using the AVIStreamReadData function. This function returns the information in an application-supplied buffer. Supplementary stream information might include configuration settings for the compression and decompression methods used on a stream. You can obtain the required buffer size by using the AVIStreamDataSize macro.

You can retrieve formatting information about a stream by using the AVIStreamReadFormat function. This function returns a stream-specific structure in an application-supplied buffer. For a video stream, the buffer contains formatting information in a BITMAPINFO structure. For an audio stream, the buffer contains formatting information in a WAVEFORMATEX or PCMWAVEFORMAT structure. For other stream types, the stream handler returns information specific to the stream. You can determine the required buffer size by using AVIStreamReadFormat and specifying a NULL buffer address or by using the AVIStreamFormatSize macro.

You can retrieve the multimedia content in a stream by using the AVIStreamRead function. This function copies raw data from the stream into an application-supplied buffer. For video streams, this function retrieves the bitmapped images that make up the frame content. For audio streams, this function retrieves waveform-audio samples that make up the sound content. You can determine the required buffer size by using AVIStreamRead and specifying a NULL buffer address or by using the AVIStreamSampleSize macro.

Some AVI stream handlers introduce delays associated with software and hardware initialization or coordination. You can inform these handlers to prepare for data streaming by using the AVIStreamBeginStreaming function. This function lets the stream handler allocate and initialize the resources it needs. To inform these handlers when streaming has ended, use the AVIStreamEndStreaming function. This function lets the stream handler deallocate the resources it allocated for AVIStreamBeginStreaming.

The AVIStreamRead function does not provide decompression services. For information about compressing and decompressing audio streams, see Audio Compression Manager. For information about compressing and decompressing video streams, see Video Compression Manager. For information about compressing and decompressing individual frames in a video stream, see Working with Compressed Video Data in a Stream.


Working with Compressed Video Data in a Stream

AVIFile provides several ways for you to access compressed video streams.

If you want to display one or more frames of a compressed video stream, you can retrieve the frames by using the AVIStreamRead function and forwarding the compressed frame data to DrawDib functions to display them. DrawDib functions can display images of several image depths and automatically dither images for displays that cannot handle certain types of device-independent bitmaps (DIBs). These functions work with uncompressed and compressed images. For more information about DrawDib functions, see DrawDib Functions.

AVIFile provides functions for decompressing a single video frame. To allocate resources, use the AVIStreamGetFrameOpen function. This function creates a buffer for the decompressed data.

You can decompress a single video frame by using the AVIStreamGetFrame function. This function decompresses the frame and retrieves a complete frame of image data, returning the address of the DIB in the BITMAPINFOHEADER structure. Your application can display the DIB by using standard drawing functions or by using the DrawDib functions.

If your application makes successive calls to AVIStreamGetFrame, the function overwrites its buffer with each retrieved frame.

When you finish using AVIStreamGetFrame and the decompressed DIB is in its buffer, you can release the allocated resources by using the AVIStreamGetFrameClose function.

For more information about decompressing images, see Video Compression Manager.


Creating a File from Existing Streams

One way to create a file that contains data streams is to combine existing streams into a new file. The streams that provide data for the new file can reside in memory or in one or more files.

You can build a file from several streams by using the AVISave function. This function creates a file and writes the data streams specified in its calling sequence to the file. The calling sequence for AVISave uses a variable number of arguments that include interfaces for the streams combined in the new file.

You can also combine data streams in a new file by using the AVISaveV function. This function provides the same functionality as AVISave, but when you use AVISaveV, your application specifies the data streams as an array, not as a variable number of arguments.

You can create a dialog box in which the user can select compression settings for the new file by using the AVISaveOptions function. The dialog box displays the current compression settings and lets the user edit them. Compression setting changes are stored in an AVICOMPRESSOPTIONS structure.

You can also include a callback function with AVISave and AVISaveV that your application can use to display the progress of writing the file and, if needed, let the user cancel the save operation. You can include the address of the callback function in the calling sequence of AVISave or AVISaveV.

You can let the user select a filename for the new file by using the GetSaveFileNamePreview function. This function displays the Save As dialog box in which the user can preview the first stream (normally the video stream) of an AVI file.

You can create a file interface pointer (and a virtual file) for a group of streams by using the AVIMakeFileFromStreams function. Other AVIFile functions can use the file interface pointer returned by this function to access the streams in the virtual file. After you finish using the virtual file, delete the file interface pointer by using the AVIFileRelease function.

Note  To minimize image and audio degradation, avoid compressing an AVI file more than once. Combine uncompressed pieces of video in your editing system and then compress the final product. For information about compression options, see Video Compression Manager.


Writing Streams to a File

You can also create a file containing data streams by writing a new data stream to a file.

You can create a new stream in a new or existing file by using the AVIFileCreateStream function. This function defines a new stream according to the characteristics described in an AVISTREAMINFO structure, creates a stream interface for the new stream, increments the reference count of the stream, and returns the address of the stream-interface pointer.

Before you write the content of the stream, you must specify the stream format. You can set the stream format by using the AVIStreamSetFormat function. When setting the format of a video stream, you must supply this function with a BITMAPINFO structure containing the appropriate information. When setting the format of an audio stream, you must supply a WAVEFORMAT or WAVEFORMATEX structure containing the appropriate information. The information you need to supply to the function for other stream types depends on the stream type and the stream handler.

You can write the multimedia content in a stream by using the AVIStreamWrite function. This function copies raw data from an application-supplied buffer into the specified stream. The default AVI file handler appends information to the end of a stream. The default WAVE handler can write waveform-audio data within a stream as well as at the end of a stream.

You can write supplementary information about the file or stream that is not included in the AVIFileCreateStream or AVIStreamSetFormat function by using the AVIFileWriteData and AVIStreamWriteData functions. You can record data that is applicable to the entire file, such as copyright information and modification history, by using AVIFileWriteData. You can record stream-specific information, such as compression and decompression settings, by using AVIStreamWriteData. The supplementary information is stored in separate chunks within the file.

You can close the stream after you finish writing to the new stream by using the AVIStreamRelease function. This function clears buffers used in recording the stream data, and it completes and closes any incomplete data chunks in the file.


Positioning in Streams

AVIFile provides several ways to locate and move to a position in a data stream. The functions and macros in this section let your application find the starting position, length, and key frames (containing a complete image in the sample) within a stream. The functions and macros also associate time with positions in a stream by calculating the elapsed time needed to play a stream from its beginning to any point in a stream.

Finding the Starting Position

You can retrieve the sample number of the first frame in a video stream by using the AVIStreamStart function. (The frames of a movie might start at sample 0 or 1, depending on the preference of the author.) You can also obtain this information by using the AVIStreamInfo function. This function stores the sample number in the dwStart member of the AVISTREAMINFO structure. You can retrieve the starting time of a stream’s first sample by using the AVIStreamStartTime macro.

You can retrieve the stream length by using the AVIStreamLength function. This function returns the number of samples in the stream. You can also obtain this information by using the AVIStreamInfo function. This function stores the stream length in the dwLength member of the AVISTREAMINFO structure. To retrieve the length of a stream in milliseconds, use the AVIStreamLengthTime macro.

In a video stream, each sample generally corresponds to a frame of video. There might, however, be samples for which no video data is present. If you call the AVIStreamRead function specifying one of those positions, it returns a data length of 0 bytes. You can find samples that contain data by using the AVIStreamFindSample function and specifying the FIND_ANY flag.

In an audio stream, each sample corresponds to one data block of audio data. For example, if the audio data has a 22 kHz ADPCM (Adaptive Differential Pulse Code Modulation) format, each sample for AVIStreamLength corresponds to a block of 256 bytes of compressed audio data. This block of audio data contains approximately 500 audio samples when uncompressed. The functions and macros of AVIFile, however, treat each 256-byte block as a single sample.

Note  Valid positions within a stream range from the beginning to the end of the stream, which is the sum of the stream starting point and its length. The position represented by the sum of the starting position and the length corresponds to a time after the last data has been rendered; it does not contain any data. You can retrieve the sample number that represents the end of the stream by using the AVIStreamEnd macro. You can retrieve the time value in milliseconds that represents the end of the stream by using the AVIStreamEndTime macro.

Finding Sample and Key Frames

You can search for different types of samples in a stream by using the AVIStreamFindSample function. This function searches backward or forward through a stream for a sample of the appropriate type, beginning with the sample number you specify. You can search for different types of samples in a stream by specifying a flag in the AVIStreamFindSample calling sequence. Specify the FIND_ANY flag to locate nonempty samples or to skip samples that lack data. Specify the FIND_KEY flag to search for key frames that contain the data to render a complete image without needing to reference previous frames. Specify the FIND_FORMAT flag to search for changes to the format. AVIStreamFindSample is used mainly with video streams.

Several macros that use AVIFile functions supplement the stream search features. The following list provides a brief description of each macro. The macros that search for a specific position or type of data require a starting location to be specified in the stream.

Macro	Description
AVIStreamIsKeyFrame	Indicates whether a sample in a specified stream is a key frame.
AVIStreamNearestKeyFrame	Locates the key frame at or preceding a specified position in a stream.
AVIStreamNearestKeyFrameTime	Determines the time corresponding to the beginning of the key frame nearest (at or preceding) a specified time in a stream.
AVIStreamNearestSample	Locates the nearest nonempty sample at or preceding a specified position in a stream.
AVIStreamNearestSampleTime	Determines the time corresponding to the beginning of a sample that is nearest to a specified time in a stream.
AVIStreamNextKeyFrame	Locates the next key frame following a specified position in a stream.
AVIStreamNextKeyFrameTime	Returns the time of the next key frame in a stream, starting at a given time.
AVIStreamNextSample	Locates the next nonempty sample from a specified position in a stream.
AVIStreamNextSampleTime	Returns the time that a sample changes to the next sample in the stream.
AVIStreamPrevKeyFrame	Locates the key frame that precedes a specified position in a stream.
AVIStreamPrevKeyFrameTime	Returns the time of the previous key frame in the stream, starting at a given time.
AVIStreamPrevSample	Locates the nonempty sample that precedes a specified position in a stream.
AVIStreamPrevSampleTime	Determines the time at which the previous sample replaces its predecessor in the stream.
AVIStreamSampleToSample	Returns the sample in a stream that occurs at the same time as a sample that occurs in a second stream.
Switching Between Samples and Time

You can determine the elapsed time from the beginning of a stream to a sample using the AVIStreamSampleToTime function. This function converts the sample number to a time value expressed in milliseconds. For a video frame (which spans several milliseconds), this value represents the time the sample begins to play since playback began and assumes the video clip plays at normal speed. For an audio sample (which has several samples in a millisecond), the time value corresponds to the time at which the sample begins to play and assumes the audio stream plays at normal speed.

Conversely, you can find the sample number associated with a time value by using the AVIStreamTimeToSample function. This function converts the millisecond value to a sample number and assumes the video clip plays at normal speed.

Because AVIStreamSampleToTime returns the time at which a frame begins to play, the relationship between AVIStreamSampleToTime and AVIStreamTimeToSample is not truly inverse. They determine the position in a file more acurately than they determine time. For example, two consecutive audio samples might both play in the same millisecond. Using AVIStreamSampleToTime to convert the sample numbers would result in identical time values. If you convert the time value back to a sample number by using AVIStreamTimeToSample, a single sample would be referenced.


Creating Temporary Streams

Temporary streams can be beneficial in several ways. You can use a temporary stream as a work stream, for example, when changing the stream format. Or you can create a temporary stream to hold portions of other streams that have been copied.

You can create a stream in memory that is not associated with any file by using the AVIStreamCreate function. This function returns the address of the interface to the new stream in a specified location and is used internally by other functions that create temporary streams.

You can create a compressed stream from an uncompressed stream by using the AVIMakeCompressedStream function. You identify the stream to compress, the compression method and compression options, and the handler for the new stream.

When you finish using a stream created with AVIStreamCreate or AVIMakeCompressedStream, close the stream by using the AVIStreamRelease function. AVIStreamRelease frees the resources the temporary stream used.


Editing Streams

You can create a stream that you can edit by using the CreateEditableStream function. This function initializes the environment for editing a stream. This includes creating an interface to the new stream, and internal edit tables that track changes made to the stream. CreateEditableStream returns a stream pointer to an editable stream that is required by other stream-editing functions. The editable stream pointer can also be used by other AVIFile functions that accept stream pointers.

You can cut one or more samples from an editable stream by using the EditStreamCut function. To remove samples from the editable stream, this function adds an entry to the edit table. The function then places a copy of the cut samples in a new temporary stream whose interface pointer is returned in a variable.

You can copy one or more samples from an editable stream into a temporary stream by using the EditStreamCopy function. EditStreamCopy places copies of the samples in a new temporary stream whose interface pointer is returned in a variable.

You can copy one or more samples from a stream and paste them into an editable stream by using the EditStreamPaste function. To insert the samples at the specified position, this function adds an entry in the edit table of the target editable stream.

You can duplicate an editable stream by using the EditStreamClone function. This function returns a pointer to the stream interface of the new stream. You can copy these streams to the clipboard or use them to maintain a trail of edits made to a stream.

You can change several of the characteristics of an editable stream by using the EditStreamSetInfo function. This function updates the priority setting, language, scale and rate, starting time, quality setting, destination rectangle dimensions and coordinates, and the textual description of the stream. These items are stored in the AVISTREAMINFO structure associated with the editable stream.

You can also change the textual description of an editable stream by using the EditStreamSetName function. This function updates the szName member of the AVISTREAMINFO structure associated with the editable stream.

The editing functions work on streams. You need to cut and paste each stream individually, and then use the AVIMakeFileFromStreams function to create a new file pointer.

Note  The edit tables in an editable stream maintain all the changes for a stream. The source stream is never changed.


Using AVIFile Functions and Macros

This section contains examples demonstrating how to perform the following tasks:

•	Opening an AVI file

•	Opening streams in an AVI file and closing the file

•	Reading streams from an AVI file

•	Reading from one stream and writing to another

•	Using the editing functions and putting a file on the clipboard


Opening an AVI File

The following example initializes the AVIFile library using the AVIFileInit function and opens an AVI file using the AVIFileOpen function. The function uses a default file handler.

// LoadAVIFile - loads AVIFile and opens an AVI file.

//

// szfile - filename

// hwnd - window handle

//

VOID LoadAVIFile(LPCSTR szFile, HWND hwnd)

{

    LONG hr;

    PAVIFILE pfile;

    AVIFileInit();          // opens AVIFile library

    hr = AVIFileOpen(&pfile, szFile, OF_SHARE_DENY_WRITE, 0L);

    if (hr != 0){

        ErrMsg("Unable to open %s", szFile);

        return;

    }

//

// Place functions here that interact with the open file.

//

    AVIFileRelease(pfile);  // closes the file

    AVIFileExit();          // releases AVIFile library

}


Opening Streams in an AVI File and Closing the File

The following example opens all the streams in an AVI file using the AVIFileGetStream function. If an error is encountered, the file is closed.

// InsertAVIFile - opens the streams in an AVI file.

//

// pfile - file-interface pointer from AVIFileOpen

//

// Global variables

// gcpavi - count of the number of streams in an AVI file

// gapavi[] = array of stream-interface pointers

void InsertAVIFile(PAVIFILE pfile, HWND hwnd, LPSTR lpszFile)

{

    int    i;

    gcpavi = 0;

    // Open the streams until a stream is not available.

    for (i = gcpavi; i < MAXNUMSTREAMS; i++) {

        gapavi[i] = NULL;

        if (AVIFileGetStream(pfile, &gapavi[i], 0L, i - gcpavi)
            != AVIERR_OK)

        break;

    if (gapavi[i] == NULL)

        break;

    }

    // Display error message-stream not found.

    if (gcpavi == i)

    {

        ErrMsg("Unable to open %s", lpszFile);

        if (pfile) // If file is open, close it

        AVIFileRelease(pfile);

        return;

    }

    else {

        gcpavi = i - 1;

    }

//  .

//  . Place functions to process data here.

//  .

}


Reading Streams from an AVI File

The following subroutine obtains stream information from an AVI file and determines the stream type from the AVISTREAMINFO structure returned by the AVIStreamInfo function.

// StreamTypes - opens the streams in an AVI file and determines

// stream types.

//

// Global variables

// gcpavi - count of streams in an AVI file

// gapavi[] = array of stream-interface pointers

void StreamTypes(HWND hwnd)

{

    AVISTREAMINFO     avis;

    LONG    r, lHeight = 0;

    WORD    w;

    int     i;

    RECT    rc;

// Walk through all streams.

    for (i = 0; i < gcpavi; i++) {

        AVIStreamInfo(gapavi[i], &avis, sizeof(avis));

        if (avis.fccType == streamtypeVIDEO) {

        // Place video-processing functions here.

        }

        else if (avis.fccType == streamtypeAUDIO) {

        // Place audio-processing functions here.

        }

        else if (avis.fccType == streamtypeTEXT) {

        // Place text-processing functions here.

        }

    }

}


Reading from One Stream and Writing to Another

The following example reads data from a stream, compresses it into a new stream, and writes the compressed data into a stream of a new file.

// SaveSmall - copies a stream of data from one file, compresses

// the stream, and writes the compressed stream to a new file.

//

// ps stream interface pointer

// lpFilename - new AVI file to build

//

void SaveSmall(PAVISTREAM ps, LPSTR lpFilename)

{

    PAVIFILE         pf;

    PAVISTREAM       psSmall;

    HRESULT          hr;

    AVISTREAMINFO    strhdr;

    BITMAPINFOHEADER bi;

    BITMAPINFOHEADER biNew;

    LONG             lStreamSize;

    LPVOID           lpOld;

    LPVOID           lpNew;

    // Determine the size of the format data using

    // AVIStreamFormatSize.

    AVIStreamFormatSize(ps, 0, &lStreamSize);

    if (lStreamSize > sizeof(bi)) // Format too large?

        return;

    lStreamSize = sizeof(bi);

    hr = AVIStreamReadFormat(ps, 0, &bi, &lStreamSize); // Read format

    if (bi.biCompression != BI_RGB) // Wrong compression format?

        return;

    hr = AVIStreamInfo(ps, &strhdr, sizeof(strhdr));

    // Create new AVI file using AVIFileOpen.

    hr = AVIFileOpen(&pf, lpFilename, OF_WRITE | OF_CREATE, NULL);

    if (hr != 0)

        return;

    // Set parameters for the new stream.

    biNew = bi;

    biNew.biWidth /= 2;

    biNew.biHeight /= 2;

    biNew.biSizeImage = ((((UINT)biNew.biBitCount * biNew.biWidth
                        + 31)&~31) / 8) * biNew.biHeight;

    SetRect(&strhdr.rcFrame, 0, 0, (int) biNew.biWidth,
            (int) biNew.biHeight);

    // Create a stream using AVIFileCreateStream.

    hr = AVIFileCreateStream(pf, &psSmall, &strhdr);

    if (hr != 0) {            //Stream created OK? If not, close file.

        AVIFileRelease(pf);

        return;

    }

    // Set format of new stream using AVIStreamSetFormat.

    hr = AVIStreamSetFormat(psSmall, 0, &biNew, sizeof(biNew));

    if (hr != 0) {

        AVIStreamRelease(psSmall);

        AVIFileRelease(pf);

        return;

    }

    // Allocate memory for the bitmaps.

    lpOld = GlobalAllocPtr(GMEM_MOVEABLE, bi.biSizeImage);

    lpNew = GlobalAllocPtr(GMEM_MOVEABLE, biNew.biSizeImage);

    // Read the stream data using AVIStreamRead.

    for (lStreamSize = AVIStreamStart(ps); lStreamSize <
        AVIStreamEnd(ps); lStreamSize++) {

        hr = AVIStreamRead(ps, lStreamSize, 1, lpOld, bi.biSizeImage,
            NULL, NULL);

        //

        // Place error check here.

        //

        // Compress the data.

        CompressDIB(&bi, lpOld, &biNew, lpNew);

        // Save the compressed data using AVIStreamWrite.

        hr = AVIStreamWrite(psSmall, lStreamSize, 1, lpNew,
            biNew.biSizeImage, AVIIF_KEYFRAME, NULL, NULL);

    }

     // Close the stream and file.

    AVIStreamRelease(psSmall);

    AVIFileRelease(pf);

}


Using the Editing Functions and Putting a File on the Clipboard

The following example cuts, copies, or deletes segments from an array of streams. The cut and copied streams are merged into a new file and placed on the clipboard. The functions used include EditStreamClone, EditStreamCopy, and EditStreamCut.

// Global variables

// gcpavi - count of streams in an AVI file

// gapavi[] - array of stream-interface pointers, used as data source

// gapaviSel[] - stream-interface pointers of edited streams

// galSelStart[] - edit starting point in each stream

// galSelLen[] - length of edit to make in each stream

// gapaviTemp[] - array of stream-interface pointers put on clipboard

//

// Comment:

//     The editable streams in gapaviSel have been

//     initialized with CreateEditableStream.

//

case MENU_CUT:

case MENU_COPY:

case MENU_DELETE:

{

    PAVIFILE pf;

    int      i;

    // Walk list of selections and make streams out of each section.

    gcpaviSel = 0;  // index counter for destination streams

    for (i = 0; i < gcpavi; i++) {

        if (galSelStart[i] != -1) {

            if (wParam == MENU_COPY)

                EditStreamCopy(gapavi[i], &galSelStart[i],

                &galSelLen[i], &gapaviSel[gcpaviSel++]);

            else {

                EditStreamCut(gapavi[i], &galSelStart[i],

                &galSelLen[i], &gapaviSel[gcpaviSel++]);

            }

        }

    }

.

.

.

    // Put on the clipboard if segment is not deleted.

    if (gcpaviSel && wParam != MENU_DELETE) {

        PAVISTREAM   gapaviTemp[MAXNUMSTREAMS];

        int i;

        // Clone the edited streams, so that if the user does

        // more editing, the clipboard won't change.

        for (i = 0; i < gcpaviSel; i++) {

            gapaviTemp[i] = NULL;

            EditStreamClone(gapaviSel[i], &gapaviTemp[i]);

            //

            // Place error check here.

            //

        }

        // Create a file from the streams and put on clipboard.

        AVIMakeFileFromStreams(&pf, gcpaviSel, gapaviTemp);

        AVIPutFileOnClipboard(pf);

        // Release clone streams.

        for (i = 0; i < gcpaviSel; i++) {

            AVIStreamRelease(gapaviTemp[i]);

        }

        // Release file put on clipboard.

        AVIFileRelease(pf);

    }

    // Release streams created.

    for (i = 0; i < gcpaviSel; i++)

        AVIStreamRelease(gapaviSel[i]);

}


AVIFile Reference

This section describes the functions, structures, and macros for applications using the AVIFile services. These elements are grouped as follows:

AVIFile Library Operations

AVIFileInit
AVIFileExit

Opening and Closing AVI Files

AVIFileOpen
AVIFileAddRef
AVIFileRelease
GetOpenFileNamePreview

Reading from a File

AVIFileInfo
AVIFILEINFO
AVIFileReadData

Writing to a File

AVIFileWriteData

Using the Clipboard

AVIPutFileOnClipboard
AVIGetFromClipboard
AVIClearClipboard

Opening and Closing Streams

AVIFileGetStream
AVIStreamOpenFromFile
AVIStreamAddRef
AVIStreamRelease

Reading Stream Information

AVISTREAMINFO
AVIStreamReadData
AVIStreamDataSize
AVIStreamReadFormat
AVIStreamFormatSize
AVIStreamRead
AVIStreamSampleSize
AVIStreamBeginStreaming
AVIStreamEndStreaming

Decompressing Video Data in a Stream

AVIStreamGetFrameOpen
AVIStreamGetFrame
AVIStreamGetFrameClose

Creating a File from Existing Streams

AVISave
AVISaveV
AVISaveOptions
GetSaveFileNamePreview
AVIMakeFileFromStreams

Writing Individual Streams

AVIFileCreateStream
AVIStreamSetFormat
AVIStreamWrite
AVIFileWriteData
AVIStreamWriteData
AVIStreamRelease

Finding the Starting Position in a Stream

AVIStreamStart
AVIStreamStartTime
AVIStreamLength
AVIStreamLengthTime
AVIStreamFindSample
AVIStreamEnd
AVIStreamEndTime

Finding Sample and Key Frames

AVIStreamFindSample
AVIStreamIsKeyFrame
AVIStreamNearestKeyFrame
AVIStreamNearestKeyFrameTime
AVIStreamNearestSample
AVIStreamNearestSampleTime
AVIStreamNextKeyFrame
AVIStreamNextKeyFrameTime
AVIStreamNextSample
AVIStreamNextSampleTime
AVIStreamPrevKeyFrame
AVIStreamPrevKeyFrameTime
AVIStreamPrevSample
AVIStreamPrevSampleTime
AVIStreamSampleToSample

Switching Between Samples and Time

AVIStreamSampleToTime
AVIStreamTimeToSample

Creating Temporary Streams

AVIStreamCreate
AVIMakeCompressedStream
AVIStreamRelease

Editing AVI Streams

CreateEditableStream
EditStreamCut
EditStreamCopy
EditStreamPaste
EditStreamClone
EditStreamSetInfo
EditStreamSetName


AVIFile Functions

The following functions are used with AVIFile.

AVIBuildFilter
AVIClearClipboard
AVIFileAddRef
AVIFileCreateStream
AVIFileEndRecord
AVIFileExit
AVIFileGetStream
AVIFileInfo
AVIFileInit
AVIFileOpen
AVIFileReadData
AVIFileRelease
AVIFileWriteData
AVIGetFromClipboard
AVIMakeCompressedStream
AVIMakeFileFromStreams
AVIMakeStreamFromClipboard
AVIPutFileOnClipboard
AVISave
AVISaveOptions
AVISaveOptionsFree
AVISaveV
AVIStreamAddRef
AVIStreamBeginStreaming
AVIStreamCreate
AVIStreamEndStreaming
AVIStreamFindSample
AVIStreamGetFrame
AVIStreamGetFrameClose
AVIStreamGetFrameOpen
AVIStreamInfo
AVIStreamLength
AVIStreamOpenFromFile
AVIStreamRead
AVIStreamReadData
AVIStreamReadFormat
AVIStreamRelease
AVIStreamSampleToTime
AVIStreamSetFormat
AVIStreamStart
AVIStreamTimeToSample
AVIStreamWrite
AVIStreamWriteData
CreateEditableStream
EditStreamClone
EditStreamCopy
EditStreamCut
EditStreamPaste
EditStreamSetInfo
EditStreamSetName


AVIFile Structures

The following structures are used with AVIFile.

AVICOMPRESSOPTIONS
AVIFILEINFO
AVISTREAMINFO


AVIFile Macros

The following macros are used with AVIFile.

AVIStreamDataSize
AVIStreamEnd
AVIStreamEndTime
AVIStreamFormatSize
AVIStreamIsKeyFrame
AVIStreamLengthTime
AVIStreamNearestKeyFrame
AVIStreamNearestKeyFrameTime
AVIStreamNearestSample
AVIStreamNearestSampleTime
AVIStreamNextKeyFrame
AVIStreamNextKeyFrameTime
AVIStreamNextSample
AVIStreamNextSampleTime
AVIStreamPrevKeyFrame
AVIStreamPrevKeyFrameTime
AVIStreamPrevSample
AVIStreamPrevSampleTime
AVIStreamSampleSize
AVIStreamSampleToSample
AVIStreamStartTime


DrawDib

The DrawDib functions provide high performance image-drawing capabilities for device-independent bitmaps (DIBs). DrawDib functions support DIBs of 8-bit, 16-bit, 24-bit, and 32-bit image depths.

DrawDib functions write directly to video memory. They do not rely on functions of the graphics device interface (GDI).


About the DrawDib Functions

Collectively, the DrawDib functions are similar to the StretchDIBits function in that they provide image-stretching and dithering capabilities. However, the DrawDib functions support image decompression, data-streaming, and a greater number of display adapters.

You will find it beneficial to use the DrawDib functions in some circumstances. Still, StretchDIBits is more diverse than the DrawDib functions and should be used when the DrawDib functions cannot provide the desired functionality. The following list describes factors to consider when deciding whether to use the DrawDib functions or StretchDIBits.

•	Color table information format. DrawDib functions display images that use the DIB_RGB_COLORS format for their color table. If images in your application store color table information with the DIB_PAL_COLORS or DIB_PAL_INDICES format, you must use StretchDIBits to display them.

•	Transfer mode. DrawDib functions require that your application use the SRCCOPY transfer mode. If your application uses StretchDIBits with a transfer mode other than SRCCOPY, you should continue to use StretchDIBits. Similarly, if you need to use other raster operations in your application, such as an XOR, use StretchDIBits.

•	Quality of video and animation playback. You can use the DrawDib functions for data-streaming applications, such as those that play video clips and animated sequences. The DrawDib functions outperform StretchDIBits in that they provide higher-quality images and improve motion during playback.

•	Display adapters. DrawDib functions support a greater number of display adapters than StretchDIBits supports. The DrawDib functions support VGA color adapters that provide 16-color palettes using 4-bit image depth, SVGA adapters that provide 256-color palettes using 8-bit image depth, and true-color display adapters that provide thousands of colors using 16-bit, 24-bit, and 32-bit image depths.

The DrawDib functions also improve the speed and quality of displaying images on display adapters with more limited capabilities. For example, when using an 8-bit display adapter, the DrawDib functions efficiently dither true-color images to 256 colors. They also dither 8-bit images when using 4-bit display adapters.

•	Image-stretching. Like StretchDIBits, the DrawDib functions use source and destination rectangles to control the portion of an image that is displayed. You can crop unwanted portions of an image or stretch an image by varying the position and size of the source and destination rectangles. If a display driver does not support image-stretching, the DrawDib functions provide more efficient stretching capabilities than StretchDIBits.

•	Compressed images. The DrawDib functions support several compression and decompression methods, including run-length encoding, JPEG, Cinepak, 411 YUV, and Indeo.


DrawDib Operations

You can access the entire group of DrawDib functions by using the DrawDibOpen function. This function loads the dynamic-link library (DLL), allocates memory resources, creates a DrawDib device context (DC), and maintains a reference count of the number of DCs that are initialized. DrawDibOpen also returns a handle of the new DC that you use with the other DrawDib functions.

You can release a DrawDib DC when you finish using it by using the DrawDibClose function. DrawDibClose also decrements the reference count of the applications accessing the DLL. The call to DrawDibClose should be the last DrawDib function in your application.

You can create as many DrawDib DCs as you want. You can use multiple DrawDib DCs to draw several bitmaps simultaneously. You can also create multiple DrawDib DCs, each with unique characteristics, so your application can choose and then use the DC with the most appropriate settings. For example, you can create two DrawDib DCs in an application: one that displays an image at its normal resolution, and the other that displays an enlarged portion of the image.

To run efficiently, DrawDib functions require information about the display adapter and its driver. The display profile is obtained by running a series of tests on the display adapter the first time the DLL containing the DrawDib functions is accessed. The DrawDib functions use this information for all applications. You can repeat these tests when necessary by using the DrawDibProfileDisplay function.

Note  Retrieving and storing the display profile is typically a one-time occurrence. If, however, the profile information is deleted or another display driver is installed in the system, DrawDib reruns the tests.


Image Rendering

After you create a DrawDib DC, you can draw a DIB to the screen by using the DrawDibDraw function. DrawDibDraw dithers true-color bitmaps when displaying them with 8-bit display adapters.

DrawDibDraw also supports video compressors transparently when displaying compressed bitmaps. You can access the buffer that contains the decompressed image by using the DrawDibGetBuffer function. DrawDibGetBuffer returns NULL when drawing an uncompressed bitmap. You should prepare your application to handle compressed and uncompressed bitmaps.

You can refresh an image or a portion of an image displayed by your application by using the DrawDibUpdate macro.


Sequences of Images

You can display a sequence of bitmaps with the same dimensions and formats by using the DrawDibDraw function with the DrawDibBegin function. DrawDibBegin improves the efficiency of DrawDibDraw by preparing the DrawDib DC for drawing.

Note  If your application does not use DrawDibBegin, DrawDibDraw implicitly executes it prior to drawing. If your application uses DrawDibBegin prior to DrawDibDraw, DrawDibDraw does not have to process the function and wait for it to complete.

The DrawDibBegin function provides DrawDibDraw with the DrawDib DC, the DC handle, the address of the BITMAPINFOHEADER structure, and the source and destination rectangle dimensions. When you display a sequence of bitmaps, DrawDibDraw checks the values of these items for each image in the sequence. If DrawDibDraw detects changes to any of these items, it implicitly calls DrawDibBegin again to adjust the DrawDib DC settings.

After using DrawDibBegin, you can draw the image sequence by using DrawDibDraw and specifying one or more flags as appropriate. Specify the DDF_SAME_HDC flag as long as the DC handle has not changed. Specify the DDF_SAME_DRAW flag when the following parameters for DrawDibDraw have not changed: the address of the BITMAPINFOHEADER structure and the source and destination rectangle dimensions.

You can update the flags set with DrawDibBegin by using the DrawDibEnd function followed by another call to DrawDibBegin. Then use DrawDibEnd to clear the DrawDib DC of its current flags and settings. The subsequent call to DrawDibBegin reinitializes the DrawDib DC with the appropriate flags and settings. Alternatively, you can update the flags for a DrawDib DC by using DrawDibBegin without DrawDibEnd. To do this, you must change at least one of the following settings concurrently with the flags: the address of the BITMAPINFOHEADER structure, or the source or destination rectangle dimensions.

You can increase the efficiency of DrawDibDraw for data-streaming operations that use compressed images, such as playing a video clip, by using the DrawDibStart and DrawDibStop functions. The DrawDibStart function prepares the DrawDib DC to receive a stream of images by sending a message to the video compression manager (VCM). When streaming has ended, DrawDibStop sends a message to VCM indicating that it can release resources it allocated for the data-streaming operation. For more information about VCM, see Video Compression Manager.

Note  You must specify the width and height of the source and destination rectangles in your application. However, you do not need to specify the origins of the rectangles. Your application can redefine the origins in DrawDibDraw to use different portions of the image or to update different portions of the display.


Palettes

The DrawDib functions require that an application respond to two palette-oriented messages: WM_QUERYNEWPALETTE and WM_PALETTECHANGED. If your application is not palette-aware, you will need to add a handler for each of these messages. For more information about processing the WM_QUERYNEWPALETTE and WM_PALETTECHANGED messages, see Adding Palette Message Handlers.

You can realize the current DrawDib palette to the DC by using the DrawDibRealize function. You should realize the palette in response to the WM_QUERYNEWPALETTE or WM_PALETTECHANGED message, or when you prepare to display an image sequence by using the DrawDibDraw function.

You can draw an image mapped to another palette by using the DrawDibSetPalette function. This function forces the DrawDib DC to use the specified palette, which can affect the image quality. For example, an application that is palette-aware might have realized a palette and needs to prevent DrawDib from realizing its own palette. The application can use DrawDibSetPalette to notify DrawDib of the palette to use.

You can obtain a handle of the current foreground palette by using the DrawDibGetPalette function. If your application uses the current foreground palette, it does not have exclusive use of the palette and another application can invalidate the palette handle. Your application should not free the palette when you finish using it. Freeing the palette could invalidate the palette handle for another application.

You can prepare DrawDib to receive new color values for its palette by using the DrawDibChangePalette function. In the code following DrawDibChangePalette, you assign new values for the palette color table. If the DDF_ANIMATE flag is not set in the DrawDib DC when you call DrawDibChangePalette, you can enact the palette changes by using DrawDibRealize to realize the palette. You can then use DrawDibDraw to redraw the image. If the DDF_ANIMATE flag is set in the DrawDib DC, you can animate the palette and the colors of the displayed bitmap by using DrawDibDraw or DrawDibRealize. You can update the DDF_ANIMATE flag by using the DrawDibEnd and DrawDibBegin functions.

Note  If you free the DrawDib palette while it is selected by a DC, a graphics device interface (GDI) error can result when the DC uses the palette. Instead, your application should use DrawDibSetPalette to change the DrawDib DC to use the default palette or another palette.

The DrawDibEnd, DrawDibClose, and DrawDibBegin functions can free the DrawDib palette. However, these functions should be used only when the palette has not been selected by the DC. The DrawDibDraw function can also free the palette when it uses the same DrawDib DC, but specifies different drawing parameters (lpbi, dxDst, dyDst, dxSrc, or dySrc) or a different format.


Timing

As part of debugging an application, you can obtain information about the amount of time required to complete repetitive DrawDib operations. The DrawDibTime function returns timing information for the following operations:

•	Drawing a bitmap

•	Decompressing a bitmap

•	Dithering a bitmap

•	Stretching a bitmap

•	Transferring a bitmap by using the BitBlt function

•	Transferring a bitmap by using the StretchDIBits function

After retrieving a set of values, DrawDibTime resets the count and value for each operation.

The DrawDibTime function is available only in the debug version of the DrawDib functions.


Using DrawDib

This section contains examples demonstrating how to perform the following tasks:

•	Adding palette message handlers

•	Drawing a display context

•	Animating a palette


Adding Palette Message Handlers

The following example illustrates simple message handlers for the WM_PALETTECHANGED and WM_QUERYNEWPALETTE messages. The example uses the DrawDibRealize function to process the WM_QUERYNEWPALETTE message.

Your application should respond to the WM_QUERYNEWPALETTE message by invalidating the destination window to let the DrawDibDraw function redraw an image. You should respond to the WM_PALETTECHANGED message by using the DrawDibRealize function to realize the palette.

case WM_PALETTECHANGED:

if ((HWND)wParam == hwnd)

break;

case WM_QUERYNEWPALETTE:

hdc = GetDC(hwnd);

f = DrawDibRealize(hdd, hdc, FALSE) > 0;

ReleaseDC(hwnd, hdc);

if (f)

InvalidateRect(hwnd, NULL, TRUE);

break;


Drawing a Display Context

The following example prepares a DrawDib DC by using the DrawDibRealize function prior to displaying several images in a bitmap sequence.

hdc = GetDC(hwnd);

DrawDibBegin(hdd, hdc, dxDest, dyDest, lpbi, dxSrc, dySrc, NULL);

DrawDibRealize(hdd, hdc, fBackground);

DrawDibDraw(hdd, hdc, xDst, yDst, dxDst, dyDst, lpbi, lpBits,

    xSrc, ySrc, dxSrc, dySrc, DDF_SAME_DRAW|DDF_SAME_HDC);

DrawDibDraw(hdd, hdc, xDst, yDst, dxDst, dyDst, lpbi, lpBits,

    xSrc, ySrc, dxSrc, dySrc, DDF_SAME_DRAW|DDF_SAME_HDC);

DrawDibDraw(hdd, hdc, xDst, yDst, dxDst, dyDst, lpbi, lpBits,

    xSrc, ySrc, dxSrc, dySrc, DDF_SAME_DRAW|DDF_SAME_HDC);

ReleaseDC(hwnd, hdc);


Animating a Palette

The following example animates a palette by using the DrawDibRealize, DrawDibChangePalette, and DrawDibDraw functions.

You can change the colors of a bitmap by using the DrawDibBegin function in combination with DrawDibChangePalette. First, to allow palette changes, specify the DDF_ANIMATE flag in the call to DrawDibBegin. Second, set the color table values from the palette entries by using DrawDibChangePalette.

For example, if lppe is an address of the PALETTEENTRY array containing the new colors, and lpbi is the LPBITMAPINFOHEADER structure used in DrawDibBegin or DrawDibDraw, the following fragment updates the DIB color table.

hdc = GetDC(hwnd);

DrawDibBegin(hdd, ....., DDF_ANIMATE);

DrawDibRealize(hdd, hdc, fBackground);

DrawDibDraw(hdd, hdc, ...., DDF_SAME_DRAW|DDF_SAME_HDC);

// Call to change color.

DrawDibChangePalette(hDD, iStart, iLen, lppe);

.

.

.

ReleaseDC(hwnd, hdc);


DrawDib Reference

This section describes the DrawDib functions and associated structures. These elements are grouped as follows:

DrawDib Library Operations

DrawDibOpen
DrawDibClose
DrawDibProfileDisplay

Image Rendering

DrawDibDraw
DrawDibGetBuffer
DrawDibUpdate

Sequences of Images

DrawDibBegin
DrawDibEnd
DrawDibStart
DrawDibStop

Palettes

DrawDibRealize
DrawDibSetPalette
DrawDibGetPalette
DrawDibChangePalette

Timing DrawDib

DRAWDIBTIME


DrawDib Functions

An application uses DrawDib functions to create and manage a DrawDib DC, display and update images on-screen, manipulate palettes, and to close the DrawDib DC when it’s no longer needed. The DrawDib functions also include a timing function and a test function to determine display characteristics.

The following functions are used with DrawDib.

DrawDibBegin
DrawDibChangePalette
DrawDibClose
DrawDibDraw
DrawDibEnd
DrawDibGetBuffer
DrawDibGetPalette
DrawDibOpen
DrawDibProfileDisplay
DrawDibRealize
DrawDibSetPalette
DrawDibStart
DrawDibStop
DrawDibTime


DrawDib Structures

The following structure is used with DrawDib.

DRAWDIBTIME


DrawDib Macros

The following macro is used with DrawDib.

DrawDibUpdate


Windows NT Performance Counters

This appendix describes the Windows NT performance objects and their associated performance counters. The following objects are covered.

•	AppleTalk Object

•	Browser Object

•	Cache Object

•	Client Service for Netware Object

•	ICMP Object

•	Image Object

•	IP Object

•	Logical Disk Object

•	Memory Object

•	NBT Connection Object

•	NetBEUI Object

•	NetBEUI Resource Object

•	Network Interface Object

•	Network Segment Object

•	NWLink IPX Object

•	NWLink NetBIOS Object

•	NWLink SPX Object

•	Objects Object

•	Paging File Object

•	Physical Disk Object

•	Process Object

•	Process Address Space Object

•	Processor Object

•	RAS Port Object

•	RAS Total Object

•	Redirector Object

•	Server Object

•	Server Work Queues Object

•	System Object

•	TCP Object

•	Thread Object

•	Thread Details Object

•	UDP Object


AppleTalk Object

The AppleTalk performance object.

Packets In/sec

Number of packets received per second by Appletalk on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Packets Out/sec

Number of packets sent per second by Appletalk on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Bytes In/sec

Number of bytes received per second by Appletalk on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_BULK_COUNT

Bytes Out/sec

Number of bytes sent per second by Appletalk on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_BULK_COUNT

Average Time/DDP Packet

Average time in milliseconds to process a DDP packet on this port.

Detail Level: Novice
Counter Type: PERF_AVERAGE_BULK

DDP Packets/sec

Number of DDP packets per second received by Appletalk on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Average Time/AARP Packet

Average time in milliseconds to process an AARP packet on this port.

Detail Level: Novice
Counter Type: PERF_AVERAGE_BULK

AARP Packets/sec

Number of AARP packets per second received by Appletalk on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Average Time/ATP Packet

Average time in milliseconds to process an ATP packet on this port.

Detail Level: Novice
Counter Type: PERF_AVERAGE_BULK

ATP Packets/sec

Number of ATP packets per second received by Appletalk on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Average Time/NBP Packet

Average time in milliseconds to process an NBP packet on this port.

Detail Level: Novice
Counter Type: PERF_AVERAGE_BULK

NBP Packets/sec

Number of NBP packets per second received by Appletalk on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Average Time/ZIP Packet

Average time in milliseconds to process a ZIP packet on this port.

Detail Level: Novice
Counter Type: PERF_AVERAGE_BULK

ZIP Packets/sec

Number of ZIP packets per second received by Appletalk on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Average Time/RTMP Packet

Average time in milliseconds to process an RTMP packet on this port.

Detail Level: Novice
Counter Type: PERF_AVERAGE_BULK

RTMP Packets/sec

Number of RTMP packets per second received by Appletalk on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

ATP Retries Local

Number of ATP requests retransmitted on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

ATP Retries Remote

Number of ATP requests retransmitted to this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

ATP Response Timouts

Number of ATP release timers that have expired on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

ATP XO Response/Sec

Number of ATP Exactly-once transaction responses per second on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

ATP ALO Response/Sec

Number of ATP At-least-once transaction responses per second on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

ATP Recvd Release/Sec

Number of ATP transaction release packets per second received on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Current NonPaged Pool

The current amount of nonpaged memory resources used by AppleTalk.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Packets Routed In/Sec

Number of packets routed in on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Packets Routed Out/Sec

Number of packets routed out on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Packets dropped

Number of packets dropped due to resource limitations on this port.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT


Browser Object

The Browser performance object consists of counters that measure the rates of announcements, enumerations, and other Browser transmissions.

Announcements Server/sec

Announcements Server/sec is the rate at which the servers in this domain have announced themselves to this server.

Detail Level: Novice
Counter Type: PERF_COUNTER_BULK_COUNT

Announcements Domain/sec

Announcements Domain/sec is the rate at which a Domain has announced itself to the network.

Detail Level: Novice
Counter Type: PERF_COUNTER_BULK_COUNT

Announcements Total/sec

Announcements Total/sec is the sum of Announcements Server/sec and Announcements Domain/sec.

Detail Level: Novice
Counter Type: PERF_COUNTER_BULK_COUNT

Election Packets/sec

Election Packets/sec is the rate of Browser election packets that have been received by this workstation.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Mailslot Writes/sec

Mailslot Writes/sec is the rate of mailslot messages that have been successfully received.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Server List Requests/sec

Server List Requests/sec is the rate of requests to retrieve a list of browser servers that have been processed by this workstation.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Enumerations Server/sec

Enumerations Server/sec is the rate of Server browse requests that have been processed by this workstation.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Enumerations Domain/sec

Enumerations Domain/sec is the rate of Domain browse requests that have been processed by this workstation.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Enumerations Other/sec

Enumerations Other/sec is the rate of browse requests processed by this workstation that were not domain or server browse requests.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Enumerations Total/sec

Enumerations Total/sec is the rate of browse requests that have been processed by this workstation. This is the sum of Enumerations Server, Enumerations Domain, and Enumerations Other.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Missed Server Announcements

Missed Server Announcements is the number of server announcements that have been missed due to configuration or allocation limits.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Missed Mailslot Datagrams

Missed Mailslot Datagrams is the number of Mailslot Datagrams that have been discarded due to configuration or allocation limits.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Missed Server List Requests

Missed Server List Requests is the number of requests to retrieve a list of browser servers that were received by this workstation, but could not be processed.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Server Announce Allocations Failed/sec

Server Announce Allocations Failed/sec is the rate of server (or domain) announcements that have failed due to lack of memory.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Mailslot Allocations Failed

Mailslot Allocations Failed is the number of times the datagram receiver has failed to allocate a buffer to hold a user mailslot write.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Mailslot Receives Failed

Mailslot Receives Failed indicates the number of mailslot messages that couldn't be received due to transport failures.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Mailslot Writes Failed

Mailslot Writes Failed is the total number of mailslot messages that have been successfully received, but that were unable to be written to the mailslot.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Mailslot Opens Failed/sec

Mailslot Opens Failed/sec indicates the rate of mailslot messages received by this workstation that were to be delivered to mailslots that are not present on this workstation.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Duplicate Master Announcements

Duplicate Master Announcements indicates the number of times that the master browser has detected another master browser on the same domain.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Illegal Datagrams/sec

Illegal Datagrams/sec is the rate of incorrectly formatted datagrams that have been received by the workstation.

Detail Level: Novice
Counter Type: PERF_COUNTER_BULK_COUNT


Cache Object

The Cache performance object consists of counters that monitor the file system cache, an area of physical memory that stores recently used data as long as possible to permit access to the data without having to read from the disk. Because applications typically use the cache, the cache is monitored as an indicator of application I/O operations. When memory is plentiful, the cache can grow, but when memory is scarce, the cache can become too small to be effective.

Data Maps/sec

Data Maps/sec is the frequency that a file system such as NTFS, maps a page of a file into the file system cache to read the page.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Sync Data Maps/sec

Sync Data Maps/sec counts the frequency that a file system, such as NTFS, maps a page of a file into the file system cache to read the page, and wishes to wait for the page to be retrieved if it is not in main memory.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Async Data Maps/sec

Async Data Maps/sec is the frequency that an application using a file system, such as NTFS, to map a page of a file into the file system cache to read the page, and does not wait for the page to be retrieved if it is not in main memory.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Data Map Hits %

Data Map Hits is the percentage of data maps in the file system cache that could be resolved without having to retrieve a page from the disk, because the page was already in physical memory.

Detail Level: Wizard
Counter Type: PERF_SAMPLE_FRACTION

Data Map Hits %

Data Map Hits is the percentage of data maps in the file system cache that could be resolved without having to retrieve a page from the disk, because the page was already in physical memory.

Detail Level: Wizard
Counter Type: PERF_SAMPLE_BASE

Data Map Pins/sec

Data Map Pins/sec is the frequency of data maps in the file system cache that resulted in pinning a page in main memory, an action usually preparatory to writing to the file on disk.  While pinned, a page's physical address in main memory and virtual address in the file system cache will not be altered.

Detail Level: Wizard
Counter Type: PERF_SAMPLE_FRACTION

Data Map Pins/sec

Data Map Pins/sec is the frequency of data maps in the file system cache that resulted in pinning a page in main memory, an action usually preparatory to writing to the file on disk.  While pinned, a page's physical address in main memory and virtual address in the file system cache will not be altered.

Detail Level: Wizard
Counter Type: PERF_SAMPLE_BASE

Pin Reads/sec

Pin Reads/sec is the frequency of reading data into the file system cache preparatory to writing the data back to disk. Pages read in this fashion are pinned in memory at the completion of the read. While pinned, a page's physical address in the file system cache will not be altered.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Sync Pin Reads/sec

Sync Pin Reads/sec is the frequency of reading data into the file system cache preparatory to writing the data back to disk. Pages read in this fashion are pinned in memory at the completion of the read. The file system will not regain control until the page is pinned in the file system cache, in particular if the disk must be accessed to retrieve the page. While pinned, a page's physical address in the file system cache will not be altered.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Async Pin Reads/sec

Async Pin Reads/sec is the frequency of reading data into the file system cache preparatory to writing the data back to disk. Pages read in this fashion are pinned in memory at the completion of the read. The file system will regain control immediately even if the disk must be accessed to retrieve the page. While pinned, a page's physical address will not be altered.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Pin Read Hits %

Pin Read Hits is the percentage of pin read requests that hit the file system cache, i.e., did not require a disk read in order to provide access to the page in the file system cache. While pinned, a page's physical address in the file system cache will not be altered. The LAN Redirector uses this method for retrieving data from the cache, as does the LAN Server for small transfers. This is usually the method used by the disk file systems as well.

Detail Level: Expert
Counter Type: PERF_SAMPLE_FRACTION

Pin Read Hits %

Pin Read Hits is the percentage of pin read requests that hit the file system cache, i.e., did not require a disk read in order to provide access to the page in the file system cache. While pinned, a page's physical address in the file system cache will not be altered. The LAN Redirector uses this method for retrieving data from the cache, as does the LAN Server for small transfers. This is usually the method used by the disk file systems as well.

Detail Level: Expert
Counter Type: PERF_SAMPLE_BASE

Copy Reads/sec

Copy Reads/sec is the frequency of reads from pages of the file system cache that involve a memory copy of the data from the cache to the application's buffer. The LAN Redirector uses this method for retrieving information from the file system cache, as does the LAN Server for small transfers. This is a method used by the disk file systems as well.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Sync Copy Reads/sec

Sync Copy Reads/sec is the frequency of reads from pages of the file system cache that involve a memory copy of the data from the cache to the application's buffer. The file system will not regain control until the copy operation is complete, even if the disk must be accessed to retrieve the page.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Async Copy Reads/sec

Async Copy Reads/sec is the frequency of reads from pages of the file system cache that involve a memory copy of the data from the cache to the application's buffer. The application will regain control immediately even if the disk must be accessed to retrieve the page.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Copy Read Hits %

Copy Read Hits is the percentage of cache copy read requests that hit the cache, that is, they did not require a disk read in order to provide access to the page in the cache. A copy read is a file read operation that is satisfied by a memory copy from a page in the cache to the application's buffer. The LAN Redirector uses this method for retrieving information from the cache, as does the LAN Server for small transfers. This is a method used by the disk file systems as well.

Detail Level: Expert
Counter Type: PERF_SAMPLE_FRACTION

Copy Read Hits %

Copy Read Hits is the percentage of cache copy read requests that hit the cache, that is, they did not require a disk read in order to provide access to the page in the cache. A copy read is a file read operation that is satisfied by a memory copy from a page in the cache to the application's buffer. The LAN Redirector uses this method for retrieving information from the cache, as does the LAN Server for small transfers. This is a method used by the disk file systems as well.

Detail Level: Expert
Counter Type: PERF_SAMPLE_BASE

MDL Reads/sec

MDL Reads/sec is the frequency of reads from the file system cache that use a Memory Descriptor List (MDL) to access the data. The MDL contains the physical address of each page involved in the transfer, and thus can employ a hardware Direct Memory Access (DMA) device to effect the copy. The LAN Server uses this method for large transfers out of the server.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Sync MDL Reads/sec

Sync MDL Reads/sec is the frequency of reads from the file system cache that use a Memory Descriptor List (MDL) to access the pages. The MDL contains the physical address of each page in the transfer, thus permitting Direct Memory Access (DMA) of the pages. If the accessed page(s) are not in main memory, the caller will wait for the pages to fault in from the disk.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Async MDL Reads/sec

Async MDL Reads/sec is the frequency of reads from the file system cache that use a Memory Descriptor List (MDL) to access the pages. The MDL contains the physical address of each page in the transfer, thus permitting Direct Memory Access (DMA) of the pages. If the accessed page(s) are not in main memory, the calling application program will not wait for the pages to fault in from disk.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

MDL Read Hits %

MDL Read Hits is the percentage of Memory Descriptor List (MDL) read requests to the file system cache that hit the cache, i.e., did not require disk accesses in order to provide memory access to the page(s) in the cache.

Detail Level: Expert
Counter Type: PERF_SAMPLE_FRACTION

MDL Read Hits %

MDL Read Hits is the percentage of Memory Descriptor List (MDL) read requests to the file system cache that hit the cache, i.e., did not require disk accesses in order to provide memory access to the page(s) in the cache.

Detail Level: Expert
Counter Type: PERF_SAMPLE_BASE

Read Aheads/sec

Read Aheads/sec is the frequency of reads from the file system cache in which the cache detects sequential access to a file. The read aheads permit the data to be transferred in larger blocks than those being requested by the application, reducing the overhead per access.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Fast Reads/sec

Fast Reads/sec is the frequency of reads from the file system cache that bypass the installed file system and retrieve the data directly from the cache. Normally, file I/O requests invoke the appropriate file system to retrieve data from a file, but this path permits direct retrieval of data from the cache without file system involvement if the data is in the cache. Even if the data is not in the cache, one invocation of the file system is avoided.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Sync Fast Reads/sec

Sync Fast Reads/sec is the frequency of reads from the file system cache that bypass the installed file system and retrieve the data directly from the cache. Normally, file I/O requests invoke the appropriate file system to retrieve data from a file, but this path permits direct retrieval of data from the cache without file system involvement if the data is in the cache. Even if the data is not in the cache, one invocation of the file system is avoided. If the data is not in the cache, the request (application program call) will wait until the data has been retrieved from disk.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Async Fast Reads/sec

Async Fast Reads/sec is the frequency of reads from the file system cache that bypass the installed file system and retrieve the data directly from the cache. Normally, file I/O requests will invoke the appropriate file system to retrieve data from a file, but this path permits data to be retrieved from the cache directly (without file system involvement) if the data is in the cache. Even if the data is not in the cache, one invocation of the file system is avoided. If the data is not in the cache, the request (application program call) will not wait until the data has been retrieved from disk, but will get control immediately.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Fast Read Resource Misses/sec

Fast Read Resource Misses/sec is the frequency of cache misses necessitated by the lack of available resources to satisfy the request.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Fast Read Not Possibles/sec

Fast Read Not Possibles/sec is the frequency of attempts by an Application Program Interface (API) function call to bypass the file system to get to data in the file system cache that could not be honored without invoking the file system.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Lazy Write Flushes/sec

Lazy Write Flushes/sec is the rate at which the Lazy Writer thread has written to disk. Lazy Writing is the process of updating the disk after the page has been changed in memory, so that the application that changed the file does not have to wait for the disk write to be complete before proceeding. More than one page can be transferred by each write operation.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Lazy Write Pages/sec

Lazy Write Pages/sec is the rate at which the Lazy Writer thread has written to disk. Lazy Writing is the process of updating the disk after the page has been changed in memory, so that the application that changed the file does not have to wait for the disk write to be complete before proceeding. More than one page can be transferred on a single disk write operation.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Data Flushes/sec

Data Flushes/sec is the rate at which the file system cache has flushed its contents to disk as the result of a request to flush or to satisfy a write-through file write request. More than one page can be transferred on each flush operation.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Data Flush Pages/sec

Data Flush Pages/sec is the number of pages the file system cache has flushed to disk as a result of a request to flush or to satisfy a write-through file write request. More than one page can be transferred on each flush operation.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER


Client Service For NetWare Object

The Client Service For NetWare performance object consists of counters that measure packet transmission rates, logons, and connections.

Bytes Total/sec

Bytes Total/sec is the rate the Redirector is processing data bytes. This includes all application and file data in addition to protocol information such as packet headers.

Detail Level: Novice
Counter Type: PERF_COUNTER_BULK_COUNT

File Data Operations/sec

File Data Operations/sec is the rate the Redirector is processing data operations. One operation includes (hopefully) many bytes. We say hopefully here because each operation has overhead. You can determine the efficiency of this path by dividing the Bytes/sec by this counter to determine the average number of bytes transferred/operation.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Packets/sec

Packets/sec is the rate the Redirector is processing data packets. One packet includes (hopefully) many bytes. We say hopefully here because each packet has protocol overhead. You can determine the efficiency of this path by dividing the Bytes/sec by this counter to determine the average number of bytes transferred/packet. You can also divide this counter by Operations/sec to determine the average number of packets per operation, another measure of efficiency.

Detail Level: Novice
Counter Type: PERF_COUNTER_BULK_COUNT

Bytes Received/sec

Bytes Received/sec is the rate of bytes coming in to the Redirector from the network. It includes all application data as well as network protocol information (such as packet headers.)

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Packets Received/sec

Packets Received/sec is the rate at which the Redirector is receiving packets (also called SMBs or Server Message Blocks). Network transmissions are divided into packets. The average number of bytes received in a packet can be obtained by dividing Bytes Received/sec by this counter. Some packets received might not contain incoming data, for example an acknowledgment to a write made by the Redirector would count as an incoming packet.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Bytes Transmitted/sec

Bytes Transmitted/sec is the rate at which bytes are leaving the Redirector to the network. It includes all application data as well as network protocol information (such as packet headers and the like.)

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Packets Transmitted/sec

Packets Transmitted/sec is the rate at which the Redirector is sending packets (also called SMBs or Server Message Blocks). Network transmissions are divided into packets. The average number of bytes transmitted in a packet can be obtained by dividing Bytes Transmitted/sec by this counter.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

File Read Operations/sec

File Read Operations/sec is the rate at which applications are asking the Redirector for data. Each call to a file system or similar Application Program Interface (API) call counts as one operation.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Read Operations Random/sec

Read Operations Random/sec counts the rate at which, on a file-by-file basis, reads are made that are not sequential. If a read is made using a particular file handle, and then is followed by another read that is not immediately the contiguous next byte, this counter is incremented by one.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Read Packets/sec

Read Packets/sec is the rate at which read packets are being placed on the network. Each time a single packet is sent with a request to read data remotely, this counter is incremented by one.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

File Write Operations/sec

File Write Operations/sec is the rate at which applications are sending data to the Redirector. Each call to a file system or similar Application Program Interface (API) call counts as one operation.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Write Operations Random/sec

Write Operations Random/sec is the rate at which, on a file-by-file basis, writes are made that are not sequential. If a write is made using a particular file handle, and then is followed by another write that is not immediately the next contiguous byte, this counter is incremented by one.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Write Packets/sec

Write Packets/sec is the rate at which writes are being sent to the network. Each time a single packet is sent with a request to write remote data, this counter is incremented by one.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Server Sessions

Server Sessions counts the total number of security objects the Redirector has managed. For example, a logon to a server followed by a network access to the same server will establish one connection, but two sessions.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Server Reconnects

Server Reconnects counts the number of times your Redirector has had to reconnect to a server in order to complete a new active request. You can be disconnected by the Server if you remain inactive for too long. Locally even if all your remote files are closed, the Redirector will keep your connections intact for (nominally) ten minutes. Such inactive connections are called Dormant Connections. Reconnecting is expensive in time.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connect NetWare 2.x

Connect NetWare 2.x counts connections to NetWare 2.x servers.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connect NetWare 3.x

Connect NetWare 3.x counts connections to NetWare 3.x servers.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connect NetWare 4.x]

Connect NetWare 4.x counts connections to NetWare 4.x servers.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Server Disconnects

Server Disconnects counts the number of times a Server has disconnected your Redirector. See also Server Reconnects.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Packet Burst Read NCP Count/sec

Packet Burst Read NCP Count/sec is the rate of NetWare Core Protocol requests for Packet Burst Read. Packet Burst is a windowing protocol that improves performance.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Packet Burst Read Timeouts/sec

Packet Burst Read Timeouts/sec is the rate the NetWare Service needs to retransmit a Burst Read Request because the NetWare server took too long to respond.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Packet Burst Write NCP Count/sec

Packet Burst Write NCP Count/sec is the rate of NetWare Core Protocol requests for Packet Burst Write. Packet Burst is a windowing protocol that improves performance.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Packet Burst Write Timeouts/sec

Packet Burst Write Timeouts/sec is the rate the NetWare Service needs to retransmit a Burst Write Request because the NetWare server took too long to respond.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Packet Burst IO/sec

Packet Burst IO/sec is the sum of Packet Burst Read NCPs/sec and Packet Burst Write NCPs/sec.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER


ICMP Object

The ICMP performance object consists of counters that measure the rates at which ICMP messages are sent and received by using the ICMP protocols. It also includes counters that monitor ICMP protocol errors.

Messages/sec

Messages/sec is the total rate at which ICMP messages are sent and received by the entity. The rate includes those messages received or sent in error.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Messages Received/sec

Messages Received/sec is the rate at which ICMP messages are received by the entity. The rate includes those messages received in error.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Messages Received Errors

Messages Received Errors is the number of ICMP messages that the entity received but determined as having errors (bad ICMP checksums, bad length, etc.).

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Received Dest. Unreachable

Received Destination Unreachable is the number of ICMP Destination Unreachable messages received.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Received Time Exceeded

Received Time Exceeded is the number of ICMP Time Exceeded messages received.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Received Parameter Problem

Received Parameter Problem is the number of ICMP Parameter Problem messages received.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Received Source Quench

Received Source Quench is the number of ICMP Source Quench messages received.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Received Redirect/sec

Received Redirect/sec is the rate of ICMP Redirect messages received.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Received Echo/sec

Received Echo/sec is the rate of ICMP Echo messages received.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Received Echo Reply/sec

Received Echo Reply/sec is the rate of ICMP Echo Reply messages received.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Received Timestamp/sec

Received Timestamp/sec is the rate of ICMP Timestamp (request) messages received.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Received Timestamp Reply/sec

Received Timestamp Reply/sec is the rate of ICMP Timestamp Reply messages received.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Received Address Mask

Received Address Mask is the number of ICMP Address Mask Request messages received.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Received Address Mask Reply

Received Address Mask Reply is the number of ICMP Address Mask Reply messages received.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Messages Sent/sec

Messages Sent/sec is the rate at which ICMP messages are attempted to be sent by the entity. The rate includes those messages sent in error.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Messages Outbound Errors

Messages Outbound Errors is the number of ICMP messages that this entity did not send due to problems discovered within ICMP such as lack of buffers. This value does not include errors discovered outside the ICMP layer, such as those recording the failure of IP to route the resultant datagram. In some implementations, none of the error types are included in the value of this counter.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Sent Destination Unreachable

Sent Destination Unreachable is the number of ICMP Destination Unreachable messages sent.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Sent Time Exceeded

Sent Time Exceeded is the number of ICMP Time Exceeded messages sent.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Sent Parameter Problem

Sent Parameter Problem is the number of ICMP Parameter Problem messages sent.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Sent Source Quench

Sent Source Quench is the number of ICMP Source Quench messages sent.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Sent Redirect/sec

Sent Redirect/sec is the rate of ICMP Redirect messages sent.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Sent Echo/sec

Sent Echo/sec is the rate of ICMP Echo messages sent.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Sent Echo Reply/sec

Sent Echo Reply/sec is the rate of ICMP Echo Reply messages sent.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Sent Timestamp/sec

Sent Timestamp/sec is the rate of ICMP Timestamp (request) messages sent.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Sent Timestamp Reply/sec

Sent Timestamp Reply/sec is the rate of ICMP Timestamp Reply messages sent.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Sent Address Mask

Sent Address Mask is the number of ICMP Address Mask Request messages sent.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Sent Address Mask Reply

Sent Address Mask Reply is the number of ICMP Address Mask Reply messages sent.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT


Image Object

The Image performance object consists of counters that monitor virtual address usage of images executed by processes on the computer.

No Access

Image Space is the virtual address space in use by the selected image with this protection. No Access protection prevents a process from writing or reading these pages and will generate an access violation if either is attempted.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Read Only

Image Space is the virtual address space in use by the selected image with this protection. Read Only protection prevents the contents of these pages from being modified. Any attempts to write or modify these pages will generate an access violation.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Read/Write

Image Space is the virtual address space in use by the selected image with this protection. Read/Write protection allows a process to read, modify and write to these pages.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Write Copy

Image Space is the virtual address space in use by the selected image with this protection. Write Copy protection is used when memory is shared for reading but not for writing. When processes are reading this memory, they can share the same memory, however, when a sharing process wants to have read/write access to this shared memory, a copy of that memory is made for writing to.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Executable

Image Space is the virtual address space in use by the selected image with this protection. Executable memory is memory that can be executed by programs, but cannot be read or written. This type of protection is not supported by all processor types.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Exec Read Only

Image Space is the virtual address space in use by the selected image with this protection. Execute/Read Only memory is memory that can be executed as well as read.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Exec Read/Write

Image Space is the virtual address space in use by the selected image with this protection. Execute/Read/Write memory is memory that can be executed by programs as well as read and written.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Exec Write Copy

Image Space is the virtual address space in use by the selected image with this protection. Execute Write Copy is memory that can be executed by programs as well as read and written. This type of protection is used when memory needs to be shared between processes. If the sharing processes only read the memory, then they will all use the same memory. If a sharing process desires write access, then a copy of this memory will be made for that process.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT


IP Object

The IP performance object includes those counters that describe the rates at which IP datagrams are sent and received by a certain computer using the IP protocol. It also describes various error counts for the IP protocol.

Datagrams/sec

Datagrams/sec is the rate at which IP datagrams are received from or sent to the interfaces, including those in error. Any forwarded datagrams are not included in this rate.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagrams Received/sec

Datagrams Received/sec is the rate at which IP datagrams are received from the interfaces, including those in error.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagrams Received Header Errors

Datagrams Received Header Errors is the number of input datagrams discarded due to errors in their IP headers, including bad checksums, version number mismatch, other format errors, time-to-live exceeded, errors discovered in processing their IP options, etc.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Datagrams Received Address Errors

Datagrams Received Address Errors is the number of input datagrams discarded because the IP address in their IP header's destination field was not a valid address to be received at this entity. This count includes invalid addresses (e.g., 0.0. 0.0) and addresses of unsupported Classes (e.g., Class E). For entities that are not IP Gateways and therefore do not forward datagrams, this counter includes datagrams discarded because the destination address was not a local address.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Datagrams Forwarded/sec

Datagrams Forwarded/sec is the rate of input datagrams for that this entity was not their final IP destination, as a result of which an attempt was made to find a route to forward them to that final destination. In entities that do not act as IP Gateways, this rate will include only those packets that were Source-Routed via this entity, and the Source-Route option processing was successful.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagrams Received Unknown Protocol

Datagrams Received Unknown Protocol is the number of locally-addressed datagrams received successfully but discarded because of an unknown or unsupported protocol.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Datagrams Received Discarded

Datagrams Received Discarded is the number of input IP datagrams for which no problems were encountered to prevent their continued processing, but which were discarded (e.g., for lack of buffer space). This counter does not include any datagrams discarded while awaiting re-assembly.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Datagrams Received Delivered/sec

Datagrams Received Delivered/sec is the rate at which input datagrams are successfully delivered to IP user-protocols (including ICMP).

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagrams Sent/sec

Datagrams Sent/sec is the rate at which IP datagrams are supplied to IP for transmission by local IP user-protocols (including ICMP). That this counter does not include any datagrams counted in Datagrams Forwarded.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagrams Outbound Discarded

Datagrams Outbound Discarded is the number of output IP datagrams for which no problems were encountered to prevent their transmission to their destination, but which were discarded (e.g., for lack of buffer space.) This counter would include datagrams counted in Datagrams Forwarded if any such packets met this (discretionary) discard criterion.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Datagrams Outbound No Route

Datagrams Outbound No Route is the number of IP datagrams discarded because no route could be found to transmit them to their destination. This counter includes any packets counted in Datagrams Forwarded that meet this `no route' criterion.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Fragments Received/sec

Fragments Received/sec is the rate at which IP fragments that need to be re-assembled at this entity are received.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Fragments Re-assembled/sec

Fragments Re-assembled/sec is the rate at which IP fragments are successfully re-assembled.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Fragment Re-assembly Failures

Fragment Re-assembly Failures is the number of failures detected by the IP re-assembly algorithm (for whatever reason: timed out, errors, etc.) This is not necessarily a count of discarded IP fragments since some algorithms (notably RFC 815) can lose track of the number of fragments by combining them as they are received.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Fragmented Datagrams/sec

Fragmented Datagrams/sec is the rate at which datagrams are successfully fragmented at this entity.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Fragmentation Failures

Fragmentation Failures is the number of IP datagrams that have been discarded because they needed to be fragmented at this entity but could not be, e.g., because their `Don't Fragment' flag was set.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Fragments Created/sec

Fragments Created/sec is the rate at which IP datagram fragments have been generated as a result of fragmentation at this entity.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER


Logical Disk Object

The Logical Disk performance object consists of counters that monitor logical partitions of a hard or fixed disk drives. Performance Monitor identifies logical disks by their a drive letter, such as C.

Free Space

Percent Free Space is the ratio of the free space available on the logical disk unit to the total usable space provided by the selected logical disk drive

Detail Level: Novice
Counter Type: PERF_RAW_FRACTION

% Free Space

Percent Free Space is the ratio of the free space available on the logical disk unit to the total usable space provided by the selected logical disk drive

Detail Level: Novice
Counter Type: PERF_RAW_BASE

Free Megabytes

Free Megabytes displays the unallocated space on the disk drive in megabytes. One megabyte = 1,048,576 bytes.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Current Disk Queue Length

Current Disk Queue Length is the number of requests outstanding on the disk at the time the performance data is collected. It includes requests in service at the time of the snapshot. This is an instantaneous length, not an average over the time interval. Multi-spindle disk devices can have multiple requests active at one time, but other concurrent requests are awaiting service. This counter might reflect a transitory high or low queue length, but if there is a sustained load on the disk drive, it is likely that this will be consistently high. Requests are experiencing delays proportional to the length of this queue minus the number of spindles on the disks. This difference should average less than 2 for good performance.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

% Disk Time

Disk Time is the percentage of elapsed time that the selected disk drive is busy servicing read or write requests.

Detail Level: Novice
Counter Type: PERF_COUNTER_TIMER

Avg. Disk Queue Length

Avg. Disk Queue Length is the average number of both read and write requests that were queued for the selected disk during the sample interval.

Detail Level: Novice
Counter Type: 0x450500,

% Disk Read Time

Disk Read Time is the percentage of elapsed time that the selected disk drive is busy servicing read requests.

Detail Level: Novice
Counter Type: PERF_COUNTER_TIMER

Avg. Disk Read Queue Length

Avg. Disk Read Queue Length is the average number of read requests that were queued for the selected disk during the sample interval.

Detail Level: Novice
Counter Type: 0x450500,

% Disk Write Time

Avg. Disk Read Queue Length is the average number of read requests that were queued for the selected disk during the sample interval.

Detail Level: Novice
Counter Type: PERF_COUNTER_TIMER

Avg. Disk Write Queue Length

Avg. Disk Write Queue Length is the average number of write requests that were queued for the selected disk during the sample interval.

Detail Level: Novice
Counter Type: 0x450500,

Avg. Disk sec/Transfer

Avg. Disk sec/Transfer is the time in seconds of the average disk transfer.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_TIMER

Avg. Disk sec/Transfer

Avg. Disk sec/Transfer is the time in seconds of the average disk transfer.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_BASE

Avg. Disk sec/Read

Avg. Disk sec/Read is the average time in seconds of a read of data from the disk.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_TIMER

Avg. Disk sec/Read

Avg. Disk sec/Read is the average time in seconds of a read of data from the disk.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_BASE

Avg. Disk sec/Write

Avg. Disk sec/Write is the average time in seconds of a write of data to the disk.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_TIMER

Avg. Disk sec/Write

Avg. Disk sec/Write is the average time in seconds of a write of data to the disk.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_BASE

Disk Transfers/sec

Disk Transfers/sec is the rate of read and write operations on the disk.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Disk Reads/sec

Disk Reads/sec is the rate of read operations on the disk.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Disk Writes/sec

Disk Writes/sec is the rate of write operations on the disk.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Disk Bytes/sec

Disk Bytes/sec is the rate bytes are transferred to or from the disk during write or read operations.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Disk Read Bytes/sec

Disk Read Bytes/sec is the rate bytes are transferred from the disk during read operations.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Disk Write Bytes/sec

Disk Write Bytes is rate bytes are transferred to the disk during write operations.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Avg. Disk Bytes/Transfer

Avg. Disk Bytes/Transfer is the average number of bytes transferred to or from the disk during write or read operations.

Detail Level: Expert
Counter Type: PERF_AVERAGE_BULK

Avg. Disk Bytes/Transfer

Avg. Disk Bytes/Transfer is the average number of bytes transferred to or from the disk during write or read operations.

Detail Level: Expert
Counter Type: PERF_AVERAGE_BASE

Avg. Disk Bytes/Read

Avg. Disk Bytes/Read is the average number of bytes transferred from the disk during read operations.

Detail Level: Expert
Counter Type: PERF_AVERAGE_BULK

Avg. Disk Bytes/Read

Avg. Disk Bytes/Read is the average number of bytes transferred from the disk during read operations.

Detail Level: Expert
Counter Type: PERF_AVERAGE_BASE

Avg. Disk Bytes/Write

Avg. Disk Bytes/Write is the average number of bytes transferred to the disk during write operations.

Detail Level: Expert
Counter Type: PERF_AVERAGE_BULK

Avg. Disk Bytes/Write

Avg. Disk Bytes/Write is the average number of bytes transferred to the disk during write operations.

Detail Level: Expert
Counter Type: PERF_AVERAGE_BASE


Memory Object

The Memory performance object consists of counters that describe the behavior of physical and virtual memory on the computer. Physical memory is the amount of random access memory on the computer. Virtual memory consists of space in physical memory and on disk. Many of the memory counters monitor paging, which is the movement of pages of code and data between disk and physical memory. Excessive paging, a symptom of a memory shortage, can cause delays which interfere will all system processes.

Available Bytes

Available Bytes is the amount of physical memory available to processes running on the computer, in bytes. It is calculated by summing space on the Zeroed, Free, and Standby memory lists. Free memory is ready for use; Zeroed memory is pages of memory filled with zeros to prevent later processes from seeing data used by a previous process. Standby memory is memory removed from a process's working set (its physical memory) on route to disk, but is still available to be recalled.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Committed Bytes

Committed Bytes is the amount of committed virtual memory, in bytes. (Committed memory is physical memory for which space has been reserved on the disk paging file in case it needs to be written back to disk.)

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Commit Limit

Commit Limit is the amount of virtual memory that can be committed without having to extend the paging file(s). It is measured in bytes. (Committed memory is physical memory for which space has been reserved on the disk paging files. There can be one paging file on each physical drive.)If the paging file(s) are be expanded, this limit increases accordingly.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Page Faults/sec

Page Faults/sec is overall rate at which of faulted pages are handled by the processor. It is measured in numbers of pages faulted. A page fault occurs when a process requires code or data that is not in its working set (its space in physical memory) in main memory. This counter includes both hard faults (those that require disk access) and soft faults (where the faulted page is found elsewhere in physical memory.) Most processors can handle large numbers of soft faults without consequence. However, hard faults can cause significant delays.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Write Copies/sec

Write Copies/sec is the number of page faults caused by attempts to write that have been satisfied by coping of the page from elsewhere in physical memory. This is an economical way of sharing data since pages are only copied when they are written to; otherwise, the page is shared. This counter counts the number of copies, without regard for the number of pages copied in each operation.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Transition Faults/sec

Transition Faults/sec is the number of page faults resolved by recovering pages that were on the modified page list, on the standby list, or being written to disk at the time of the page fault. The pages were recovered without additional disk activity. Transition faults are counted in numbers of faults, without regard for the number of pages faulted in each operation.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Cache Faults/sec

Cache Faults/sec is the number of faults which occur when a page sought in the file system cache is not found there and must be retrieved from elsewhere in memory (a soft fault) or from disk (a hard fault). The file system cache is an area of physical memory that stores recently used pages of data for applications. Cache activity is a reliable indicator of most application I/O operations. This counter counts the number of faults, without regard for the number of pages faulted in each operation.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Demand Zero Faults/sec

Demand Zero Faults/sec is the number of page faults that require a zeroed page to satisfy the fault. Zeroed pages, pages emptied of previously stored data and filled with zeros, are a security feature of Windows NT. They prevent processes from seeing data stored by earlier processes that used the memory space. Windows NT maintains a list of zeroed pages to accelerate this process. This counter counts numbers of faults, without regard to the numbers of pages retrieved to satisfy the fault.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Pages/sec

Pages/sec is the number of pages read from or written to disk to resolve hard page faults. (Hard page faults occur when a process requires code or data that is not in its working set or elsewhere in physical memory, and must be retrieved from disk.) This counter was designed as a primary indicator of the kinds of faults that cause system-wide delays. It is the sum of Memory: Pages Input/sec and Memory: Pages Output/sec. It is counted in numbers of pages, so it can be compared to other counts of pages, such as Memory: Page Faults/sec, without conversion. It includes pages retrieved to satisfy faults in the file system cache (usually requested by applications) non-cached mapped memory files.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Pages Input/sec

Pages Input/sec is the number of pages read from disk to resolve hard page faults. (Hard page faults occur when a process requires code or data that is not in its working set or elsewhere in physical memory, and must be retrieved from disk.) This counter was designed as a primary indicator of the kinds of faults that cause system-wide delays. It includes pages retrieved to satisfy faults in the file system cache (usually requested by applications) and in non-cached mapped memory files. This counter counts numbers of pages, and can be compared to other counts of pages, such as Memory: Page Faults/sec, without conversion.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Page Reads/sec

Page Reads/sec is the number of times the disk was read to resolve hard page faults. (Hard page faults occur when a process requires code or data that is not in its working set or elsewhere in physical memory, and must be retrieved from disk.) This counter was designed as a primary indicator of the kinds of faults that cause system-wide delays. It includes reads to satisfy faults in the file system cache (usually requested by applications) and in non-cached mapped memory files. This counter counts numbers of read operations, without regard to the numbers of pages retrieved by each operation.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Pages Output/sec

Pages Output/sec is the number of pages written to disk to free up space in physical memory. Pages are written back to disk only if they are changed in physical memory, so they are likely to hold data, not code. A high rate of pages output might indicate a memory shortage. Windows NT writes more pages back to disk to free up space when physical memory is in short supply. This counter counts numbers of pages, and can be compared to other counts of pages, without conversion.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Page Writes/sec

Page Writes/sec is the number of times pages were written to disk to free up space in physical memory. Pages are written to disk only if they are changed while in physical memory, so they are likely to hold data, not code. This counter counts write operations, without regard to the number of pages written in each operation.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Pool Paged Bytes

Pool Paged Bytes is the number of bytes in the paged pool, an area of system memory (physical memory used by the operating system) for objects that can be written to disk when they are not being used. Memory: Pool Paged Bytes is calculated differently than Process: Pool Paged Bytes, so it might not equal Process: Pool Paged Bytes: _Total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Pool Nonpaged Bytes

Pool Nonpaged Bytes is the number of bytes in the nonpaged pool, an area of  system memory (physical memory used by the operating system) for objects that cannot be written to disk, but must remain in physical memory as long as they are allocated. Memory: Pool Nonpaged Bytes is calculated differently than Process: Pool Nonpaged Bytes, so it might not equal Process: Pool Nonpaged Bytes: _Total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Pool Paged Allocs

Pool Paged Allocs is the number of calls to allocate space in the paged pool. The paged pool is an area of system memory (physical memory used by the operating system) for objects that can be written to disk when they are not being used. It is measured in numbers of calls to allocate space, regardless of the amount of space allocated in each call.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Pool Nonpaged Allocs

Pool Nonpaged Allocs is the number of calls to allocate space in the nonpaged pool.  The nonpaged pool is an area of system memory area for objects that cannot be written to disk, and must remain in physical memory as long as they are allocated. It is measured in numbers of calls to allocate space, regardless of the amount of space allocated in each call.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Free System Page Table Entries

The number of Page Table Entries not currently in use by the system.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Cache Bytes

Cache Bytes is the number of bytes currently being used by the file system cache. The file system cache is an area of physical memory that stores recently used pages of data for applications. Windows NT continually adjusts the size of the cache, making it as large as it can while still preserving the minimum required number of available bytes for processes.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Cache Bytes Peak

Cache Bytes Peak is the maximum number of bytes used by the file system cache since the system was last restarted. This might be larger than the current size of the cache. Cache. The file system cache is an area of physical memory that stores recently used pages of data for applications. Windows NT continually adjusts the size of the cache, making it as large as it can while still preserving the minimum required number of available bytes for processes.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Pool Paged Resident Bytes

Pool Paged Resident Bytes is the current size of paged pool in bytes. The paged pool is an area of system memory (physical memory used by the operating system) for objects that can be written to disk when they are not being used. Space used by the paged and nonpaged pools are taken from physical memory, so a pool that is too large denies memory space to processes.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

System Code Total Bytes

System Code Total Bytes is the number of bytes of pageable operating system code currently in virtual memory. It is a measure of the amount of physical memory being used by the operating system that can be written to disk when not in use. This value is calculated by summing the bytes in Ntoskrnl.exe, Hal.dll, the boot drivers, and file systems loaded by Ntldr/osloader. This counter does not include code that must remain in physical memory and cannot be written to disk.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

System Code Resident Bytes

System Code Resident Bytes is the number of bytes of operating system code currently in physical memory that can be written to disk when not in use. This value is a component of System Code Total Bytes, which also includes operating system code on disk. System Code Resident Bytes (and System Code Total Bytes) does not include code that must remain in physical memory and cannot be written to disk.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

System Driver Total Bytes

System Driver Total Bytes is the number of bytes of pageable virtual memory currently being used by device drivers. (Pageable memory can be written to disk when it is not being used.) It includes physical memory (Memory: System Driver Resident Bytes) and code and data written to disk. It is a component of Memory: System Code Total Bytes.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

System Driver Resident Bytes

System Driver Resident Bytes is the number of bytes of pageable physical memory being used by device drivers. It is the working set (physical memory area) of the drivers. This value is a component of Memory: System Driver Total Bytes, which also includes driver memory that has been written to disk. Neither System Driver Resident Bytes nor System Driver Total Bytes includes memory that cannot be written to disk.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

System Cache Resident Bytes

System Cache Resident Bytes is the number of bytes of pageable operating system code in the file system cache. This value is a component of Memory: System Code Resident Bytes which represents all pageable operating system code that is currently in physical memory.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

% Committed Bytes In Use

% Committed Bytes In Use is the ratio of Memory: Committed Bytes to the Memory: Commit Limit. (Committed memory is physical memory in use for which space has been reserved in the paging file should it need to be written to disk. The commit limit is determined by the size of the paging file. If the paging file is enlarged, the commit limit increases, and the ratio is reduced.)

Detail Level: Expert
Counter Type: PERF_RAW_FRACTION

% Committed Bytes In Use

% Committed Bytes In Use is the ratio of the Committed Bytes to the Commit Limit. This represents the amount of available virtual memory in use. Note that the Commit Limit might change if the paging file is extended. This is an instantaneous value, not an average.

Detail Level: Expert
Counter Type: PERF_RAW_BASE


NBT Connection Object

The NBT Connection performance object consists of counters that measure the rates at which bytes are sent and received over the NBT connection between the local computer and a remote computer. The connection is identified by the name of the remote computer.

Bytes Received/sec

Bytes Received/sec is the rate at which bytes are received by the local computer over an NBT connection to some remote computer. All the bytes received by the local computer over the particular NBT connection are counted.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Bytes Sent/sec

Bytes Sent/sec is the rate at which bytes are sent by the local computer over an NBT connection to some remote computer. All the bytes sent by the local computer over the particular NBT connection are counted.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Bytes Total/sec

Total Bytes/sec is the rate at which bytes are sent or received by the local computer over an NBT connection to some remote computer. All the bytes sent or received by the local computer over the particular NBT connection are counted.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT


NetBEUI Object

The NetBEUI performance object consists of counters that measure data transmission for network activity which conforms to the NetBIOS End User Interface standard.

Datagrams/sec

Datagrams/sec is the rate at which datagrams are processed by the computer. This counter displays the sum of datagrams sent and datagrams received. A datagram is a connectionless packet whose delivery to a remote is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagram Bytes/sec

Datagram Bytes/sec is the rate at which datagram bytes are processed by the computer. This counter is the sum of datagram bytes that are sent as well as received. A datagram is a connectionless packet whose delivery to a remote is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Packets/sec

Packets/sec is the rate at which packets are processed by the computer. This count is the sum of Packets Sent and Packets Received per second. This counter includes all packets processed: control as well as data packets.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frames/sec

Frames/sec is the rate at which data frames (or packets) are processed by the computer. This counter is the sum of data frames sent and data frames received. This counter only counts those frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes/sec

Frame Bytes/sec is the rate at which data bytes are processed by the computer. This counter is the sum of data frame bytes sent and received. This counter only counts the byte in frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Bytes Total/sec

Bytes Total/sec is the sum of Frame Bytes/sec and Datagram Bytes/sec. This is the total rate of bytes sent to or received from the network by the protocol, but only counts the bytes in frames (i.e., packets) which carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Connections Open

Connections Open is the number of connections currently open for this protocol. This counter shows the current count only and does not accumulate over time.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connections No Retries

Connections No Retries is the total count of connections that were successfully made on the first try. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connections With Retries

Connections With Retries is the total count of connections that were made after retrying the attempt. A retry occurs when the first connection attempt failed. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Disconnects Local

Disconnects Local is the number of session disconnections that were initiated by the local computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Disconnects Remote

Disconnects Remote is the number of session disconnections that were initiated by the remote computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Link

Failures Link is the number of connections that were dropped due to a link failure. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Adapter

Failures Adapter is the number of connections that were dropped due to an adapter failure. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connection Session Timeouts

Connection Session Timeouts is the number of connections that were dropped due to a session time out. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connections Canceled

Connections Canceled is the number of connections that were canceled. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Resource Remote

Failures Resource Remote is the number of connections that failed because of resource problems or shortages on the remote computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Resource Local

Failures Resource Local is the number of connections that failed because of resource problems or shortages on the local computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Not Found

Failures Not Found is the number of connection attempts that failed because the remote computer could not be found. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures No Listen

Failures No Listen is the number of connections that were rejected because the remote computer was not listening for connection requests.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Datagrams Sent/sec

Datagrams Sent/sec is the rate at which datagrams are sent from the computer. A datagram is a connectionless packet whose delivery to a remote computer is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagram Bytes Sent/sec]

Datagram Bytes Sent/sec is the rate at which datagram bytes are sent from the computer. A datagram is a connectionless packet whose delivery to a remote computer is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Datagrams Received/sec

Datagrams Received/sec is the rate at which datagrams are received by the computer. A datagram is a connectionless packet whose delivery to a remote computer is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagram Bytes Received/sec

Datagram Bytes Received/sec is the rate at which datagram bytes are received by the computer. A datagram is a connectionless packet whose delivery to a remote computer is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Packets Sent/sec

Packets Sent/sec is the rate at which packets are sent by the computer. This counter counts all packets sent by the computer, i.e. control as well as data packets.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Packets Received/sec

Packets Received/sec is the rate at which packets are received by the computer. This counter counts all packets processed, control as well as data packets.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Frames Sent/sec

Frames Sent/sec is the rate at which data frames are sent by the computer. This counter only counts the frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Sent/sec

Frame Bytes Sent/sec is the rate at which data bytes are sent by the computer. This counter only counts the bytes in frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Frames Received/sec

Frames Received/sec is the rate at which data frames are received by the computer. This counter only counts the frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Received/sec

Frame Bytes Received/sec is the rate at which data bytes are received by the computer. This counter only counts the frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Frames Re-Sent/sec

Frames Re-Sent/sec is the rate at which data frames (packets) are re-sent by the computer. This counter only counts the frames or packets that carry data.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Re-Sent/sec

Frame Bytes Re-Sent/sec is the rate at which data bytes are re-sent by the computer. This counter only counts the bytes in frames that carry data.

Detail Level: Wizard
Counter Type: PERF_COUNTER_BULK_COUNT

Frames Rejected/sec

Frames Rejected/sec is the rate at which data frames are rejected. This counter only counts the frames (packets) that carry data.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Rejected/sec

Frame Bytes Rejected/sec is the rate at which data bytes are rejected. This counter only counts the bytes in data frames (packets) that carry data.

Detail Level: Expert
Counter Type: PERF_COUNTER_BULK_COUNT

Expirations Response

Expirations Response is the count of T1 timer expirations.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Expirations Ack

Expirations Ack is the count of T2 timer expirations.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Window Send Maximum

Window Send Maximum is the maximum number of bytes of data that will be sent before waiting for an acknowledgment from the remote computer.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Window Send Average

Window Send Average is the running average number of data bytes that were sent before waiting for an acknowledgment from the remote computer.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Piggyback Ack Queued/sec

Piggyback Ack Queued/sec is the rate at which piggybacked acknowledgments are queued. Piggyback acknowledgments are acknowledgments to received packets that are to be included in the next outgoing packet to the remote computer.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Piggyback Ack Timeouts

Piggyback Ack Timeouts is the number of times that a piggyback acknowledgment could not be sent because there was no outgoing packet to the remote on which to piggyback. A piggyback ack is an acknowledgment to a received packet that is sent along in an outgoing data packet to the remote computer. If no outgoing packet is sent within the time-out period, then an ack packet is sent and this counter is incremented.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT


NetBEUI Resource Object

The NetBEUI Resource performance object consists of counters that track the use of buffers by the NetBEUI protocol.

Used Maximum

Used Maximum is the maximum number of NetBEUI resources (buffers) in use at any point in time. This value is useful in sizing the maximum resources provided. The number in parentheses following the resource name is used to identify the resource in Event Log messages.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Used Average

Used Average is the current number of resources (buffers) in use at this time. The number in parentheses following the resource name is used to identify the resource in Event Log messages.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Times Exhausted

Times Exhausted is the number of times all the resources (buffers) were in use. The number in parentheses following the resource name is used to identify the resource in Event Log messages.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT


Network Interface Object

The Network Interface performance object consists of counters that measure the rates at which bytes and packets are sent and received over a TCP/IP connection. It includes counters that monitor connection errors.

Bytes Total/sec

Bytes Total/sec is the rate at which bytes are sent and received on the interface, including framing characters.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Packets/sec

Packets/sec is the rate at which packets are sent and received on the network interface.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Packets Received/sec

Packets Received/sec is the rate at which packets are received on the network interface.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Packets Sent/sec

Packets Sent/sec is the rate at which packets are sent on the network interface.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Current Bandwidth

Current Bandwidth is an estimate of the interface's current bandwidth in bits per second (BPS). For interfaces that do not vary in bandwidth or for those where no accurate estimation can be made, this value is the nominal bandwidth.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Bytes Received/sec

Bytes Received/sec is the rate at which bytes are received on the interface, including framing characters.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Packets Received Unicast/sec

Packets Received Unicast/sec is the rate at which (subnet) unicast packets are delivered to a higher-layer protocol.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Packets Received Non-Unicast/sec

Packets Received Non-Unicast/sec is the rate at which non-unicast (i.e., subnet broadcast or subnet multicast) packets are delivered to a higher-layer protocol.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Packets Received Discarded

Packets Received Discarded is the number of inbound packets that were chosen to be discarded even though no errors had been detected to prevent their being deliverable to a higher-layer protocol. One possible reason for discarding such a packet could be to free up buffer space.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Packets Received Errors

Packets Received Errors is the number of inbound packets that contained errors preventing them from being deliverable to a higher-layer protocol.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Packets Received Unknown

Packets Received Unknown is the number of packets received via the interface that were discarded because of an unknown or unsupported protocol.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Bytes Sent/sec

Bytes Sent/sec is the rate at which bytes are sent on the interface, including framing characters.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Packets Sent Unicast/sec

Packets Sent Unicast/sec is the rate at which packets are requested to be transmitted to subnet-unicast addresses by higher-level protocols. The rate includes the packets that were discarded or not sent.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Packets Sent Non-Unicast/sec

Packets Sent Non-Unicast/sec is the rate at which packets are requested to be transmitted to non-unicast (i.e., subnet broadcast or subnet multicast) addresses by higher-level protocols. The rate includes the packets that were discarded or not sent.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Packets Outbound Discarded

Packets Outbound Discarded is the number of outbound packets that were chosen to be discarded even though no errors had been detected to prevent their being transmitted. One possible reason for discarding such a packet could be to free up buffer space.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Packets Outbound Errors

Packets Outbound Errors is the number of outbound packets that could not be transmitted because of errors.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Output Queue Length

Output Queue Length is the length of the output packet queue (in packets.) If this is longer than 2, delays are being experienced and the bottleneck should be found and eliminated if possible. Since the requests are queued by NDIS in this implementations, this will always be 0.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT


Network Segment Object

The network segment performance object provides network statistics for the local network segment via the Network Monitor service.

Total frames received/second

The total number of frames received per second on this network segment.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Total bytes received/second

The number of bytes received per second on this network segment.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Broadcast frames received/second

The number of Broadcast frames received per second on this network segment.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Multicast frames received/second

The number of Multicast frames received per second on this network segment.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

% Network utilization

Percentage of network bandwidth in use on this network segment.

Detail Level: Advanced
Counter Type: PERF_COUNTER_MULTI_TIMER

(null)

Detail Level: Advanced
Counter Type: PERF_COUNTER_MULTI_BASE

% Broadcast Frames

Percentage of network bandwidth which is made up of broadcast traffic on this network segment.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_BULK

% Broadcast Frames

Percentage of network bandwidth which is made up of broadcast traffic on this network segment.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_BASE

% Multicast Frames

Percentage of network bandwidth which is made up of multicast traffic on this network segment.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_BULK

% Multicast Frames

Percentage of network bandwidth which is made up of multicast traffic on this network segment.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_BASE


NWLink IPX Object

The NWLink IPX performance object consists of counter that measure datagram transmission to and from computers using the IPX protocol.

Datagrams/sec

Datagrams/sec is the rate at which datagrams are processed by the computer. This counter displays the sum of datagrams sent and datagrams received. A datagram is a connectionless packet whose delivery to a remote is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagram Bytes/sec

Datagram Bytes/sec is the rate at which datagram bytes are processed by the computer. This counter is the sum of datagram bytes that are sent as well as received. A datagram is a connectionless packet whose delivery to a remote is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Packets/sec

Packets/sec is the rate at which packets are processed by the computer. This count is the sum of Packets Sent and Packets Received per second. This counter includes all packets processed: control as well as data packets.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frames/sec

Frames/sec is the rate at which data frames (or packets) are processed by the computer. This counter is the sum of data frames sent and data frames received. This counter only counts those frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes/sec

Frame Bytes/sec is the rate at which data bytes are processed by the computer. This counter is the sum of data frame bytes sent and received. This counter only counts the byte in frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Bytes Total/sec

Bytes Total/sec is the sum of Frame Bytes/sec and Datagram Bytes/sec. This is the total rate of bytes sent to or received from the network by the protocol, but only counts the bytes in frames (i.e., packets) which carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Connections Open

Connections Open is the number of connections currently open for this protocol. This counter shows the current count only and does not accumulate over time.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connections No Retries

Connections No Retries is the total count of connections that were successfully made on the first try. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connections With Retries

Connections With Retries is the total count of connections that were made after retrying the attempt. A retry occurs when the first connection attempt failed. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Disconnects Local

Disconnects Local is the number of session disconnections that were initiated by the local computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Disconnects Remote

Disconnects Remote is the number of session disconnections that were initiated by the remote computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Link

Failures Link is the number of connections that were dropped due to a link failure. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Adapter

Failures Adapter is the number of connections that were dropped due to an adapter failure. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connection Session Timeouts

Connection Session Timeouts is the number of connections that were dropped due to a session time out. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connections Canceled

Connections Canceled is the number of connections that were canceled. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Resource Remote

Failures Resource Remote is the number of connections that failed because of resource problems or shortages on the remote computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Resource Local

Failures Resource Local is the number of connections that failed because of resource problems or shortages on the local computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Not Found

Failures Not Found is the number of connection attempts that failed because the remote computer could not be found. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures No Listen

Failures No Listen is the number of connections that were rejected because the remote computer was not listening for connection requests.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Datagrams Sent/sec

Datagrams Sent/sec is the rate at which datagrams are sent from the computer. A datagram is a connectionless packet whose delivery to a remote computer is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagram Bytes Sent/sec

Datagram Bytes Sent/sec is the rate at which datagram bytes are sent from the computer. A datagram is a connectionless packet whose delivery to a remote computer is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Datagrams Received/sec

Datagrams Received/sec is the rate at which datagrams are received by the computer. A datagram is a connectionless packet whose delivery to a remote computer is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagram Bytes Received/sec

Datagram Bytes Received/sec is the rate at which datagram bytes are received by the computer. A datagram is a connectionless packet whose delivery to a remote computer is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Packets Sent/sec

Packets Sent/sec is the rate at which packets are sent by the computer. This counter counts all packets sent by the computer, i.e. control as well as data packets.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Packets Received/sec

Packets Received/sec is the rate at which packets are received by the computer. This counter counts all packets processed: control as well as data packets.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Frames Sent/sec

Frames Sent/sec is the rate at which data frames are sent by the computer. This counter only counts the frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Sent/sec

Frame Bytes Sent/sec is the rate at which data bytes are sent by the computer. This counter only counts the bytes in frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Frames Received/sec

Frames Received/sec is the rate at which data frames are received by the computer. This counter only counts the frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Received/sec

Frame Bytes Received/sec is the rate at which data bytes are received by the computer. This counter only counts the frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Frames Re-Sent/sec

Frames Re-Sent/sec is the rate at which data frames (packets) are re-sent by the computer. This counter only counts the frames or packets that carry data.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Re-Sent/sec

Frame Bytes Re-Sent/sec is the rate at which data bytes are re-sent by the computer. This counter only counts the bytes in frames that carry data.

Detail Level: Wizard
Counter Type: PERF_COUNTER_BULK_COUNT

Frames Rejected/sec

Frames Rejected/sec is the rate at which data frames are rejected. This counter only counts the frames (packets) that carry data.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Rejected/sec

Frame Bytes Rejected/sec is the rate at which data bytes are rejected. This counter only counts the bytes in data frames (packets) that carry data.

Detail Level: Expert
Counter Type: PERF_COUNTER_BULK_COUNT

Expirations Response

Expirations Response is the count of T1 timer expirations.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Expirations Ack

Expirations Ack is the count of T2 timer expirations

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Window Send Maximum

Window Send Maximum is the maximum number of bytes of data that will be sent before waiting for an acknowledgment from the remote computer.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Window Send Average

Window Send Average is the running average number of data bytes that were sent before waiting for an acknowledgment from the remote computer.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Piggyback Ack Queued/sec

Piggyback Ack Queued/sec is the rate at which piggybacked acknowledgments are queued. Piggyback acknowledgments are acknowledgments to received packets that are to be included in the next outgoing packet to the remote computer.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Piggyback Ack Timeouts

Piggyback Ack Timeouts is the number of times that a piggyback acknowledgment could not be sent because there was no outgoing packet to the remote on which to piggyback. A piggyback ack is an acknowledgment to a received packet that is sent along in an outgoing data packet to the remote computer. If no outgoing packet is sent within the time-out period, then an ack packet is sent and this counter is incremented.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT


NWLink NetBIOS Object

The NWLink NetBIOS performance object consists of counters that monitor IPX transport rates and connections.

Datagrams/sec

Datagrams/sec is the rate at which datagrams are processed by the computer. This counter displays the sum of datagrams sent and datagrams received. A datagram is a connectionless packet whose delivery to a remote is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagram Bytes/sec

Datagram Bytes/sec is the rate at which datagram bytes are processed by the computer. This counter is the sum of datagram bytes that are sent as well as received. A datagram is a connectionless packet whose delivery to a remote is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Packets/sec

Packets/sec is the rate at which packets are processed by the computer. This count is the sum of Packets Sent and Packets Received per second. This counter includes all packets processed: control as well as data packets.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frames/sec

Frames/sec is the rate at which data frames (or packets) are processed by the computer. This counter is the sum of data frames sent and data frames received. This counter only counts those frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes/sec

Frame Bytes/sec is the rate at which data bytes are processed by the computer. This counter is the sum of data frame bytes sent and received. This counter only counts the byte in frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Bytes Total/sec

Bytes Total/sec is the sum of Frame Bytes/sec and Datagram Bytes/sec. This is the total rate of bytes sent to or received from the network by the protocol, but only counts the bytes in frames (i.e., packets) which carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Connections Open

Connections Open is the number of connections currently open for this protocol. This counter shows the current count only and does not accumulate over time.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connections No Retries

Connections No Retries is the total count of connections that were successfully made on the first try. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connections With Retries

Connections With Retries is the total count of connections that were made after retrying the attempt. A retry occurs when the first connection attempt failed. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Disconnects Local

Disconnects Local is the number of session disconnections that were initiated by the local computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Disconnects Remote

Disconnects Remote is the number of session disconnections that were initiated by the remote computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Link

Failures Link is the number of connections that were dropped due to a link failure. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Adapter

Failures Adapter is the number of connections that were dropped due to an adapter failure. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connection Session Timeouts

Connection Session Timeouts is the number of connections that were dropped due to a session time out. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connections Canceled

Connections Canceled is the number of connections that were canceled. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Resource Remote

Failures Resource Remote is the number of connections that failed because of resource problems or shortages on the remote computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Resource Local

Failures Resource Local is the number of connections that failed because of resource problems or shortages on the local computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Not Found

Failures Not Found is the number of connection attempts that failed because the remote computer could not be found. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures No Listen

Failures No Listen is the number of connections that were rejected because the remote computer was not listening for connection requests.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Datagrams Sent/sec

Datagrams Sent/sec is the rate at which datagrams are sent from the computer. A datagram is a connectionless packet whose delivery to a remote computer is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagram Bytes Sent/sec

Datagram Bytes Sent/sec is the rate at which datagram bytes are sent from the computer. A datagram is a connectionless packet whose delivery to a remote computer is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Datagrams Received/sec

Datagrams Received/sec is the rate at which datagrams are received by the computer. A datagram is a connectionless packet whose delivery to a remote computer is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagram Bytes Received/sec

Datagram Bytes Received/sec is the rate at which datagram bytes are received by the computer. A datagram is a connectionless packet whose delivery to a remote computer is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Packets Sent/sec

Packets Sent/sec is the rate at which packets are sent by the computer. This counter counts all packets sent by the computer, i.e. control as well as data packets.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Packets Received/sec

Packets Received/sec is the rate at which packets are received by the computer. This counter counts all packets processed: control as well as data packets.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Frames Sent/sec

Frames Sent/sec is the rate at which data frames are sent by the computer. This counter only counts the frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Sent/sec

Frame Bytes Sent/sec is the rate at which data bytes are sent by the computer. This counter only counts the bytes in frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Frames Received/sec

Frames Received/sec is the rate at which data frames are received by the computer. This counter only counts the frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Received/sec

Frame Bytes Received/sec is the rate at which data bytes are received by the computer. This counter only counts the frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Frames Re-Sent/sec

Frames Re-Sent/sec is the rate at which data frames (packets) are re-sent by the computer. This counter only counts the frames or packets that carry data.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Re-Sent/sec

Frame Bytes Re-Sent/sec is the rate at which data bytes are re-sent by the computer. This counter only counts the bytes in frames that carry data.

Detail Level: Wizard
Counter Type: PERF_COUNTER_BULK_COUNT

Frames Rejected/sec

Frames Rejected/sec is the rate at which data frames are rejected. This counter only counts the frames (packets) that carry data.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Rejected/sec

Frame Bytes Rejected/sec is the rate at which data bytes are rejected. This counter only counts the bytes in data frames (packets) that carry data.

Detail Level: Expert
Counter Type: PERF_COUNTER_BULK_COUNT

Expirations Response

Expirations Response is the count of T1 timer expirations.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Expirations Ack

Expirations Ack is the count of T2 timer expirations.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Window Send Maximum

Window Send Maximum is the maximum number of bytes of data that will be sent before waiting for an acknowledgment from the remote computer.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Window Send Average

Window Send Average is the running average number of data bytes that were sent before waiting for an acknowledgment from the remote computer.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Piggyback Ack Queued/sec

Piggyback Ack Queued/sec is the rate at which piggybacked acknowledgments are queued. Piggyback acknowledgments are acknowledgments to received packets that are to be included in the next outgoing packet to the remote computer.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Piggyback Ack Timeouts

Piggyback Ack Timeouts is the number of times that a piggyback acknowledgment could not be sent because there was no outgoing packet to the remote on which to piggyback. A piggyback ack is an acknowledgment to a received packet that is sent along in an outgoing data packet to the remote computer. If no outgoing packet is sent within the time-out period, then an ack packet is sent and this counter is incremented.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT


NWLink SPX Object

The NWLink SPX performance object consists of counters that measure data transmission and session connections for computers using the SPX protocol.

Datagrams/sec

Datagrams/sec is the rate at which datagrams are processed by the computer. This counter displays the sum of datagrams sent and datagrams received. A datagram is a connectionless packet whose delivery to a remote is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagram Bytes/sec

Datagram Bytes/sec is the rate at which datagram bytes are processed by the computer. This counter is the sum of datagram bytes that are sent as well as received. A datagram is a connectionless packet whose delivery to a remote is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Packets/sec

Packets/sec is the rate at which packets are processed by the computer. This count is the sum of Packets Sent and Packets Received per second. This counter includes all packets processed: control as well as data packets.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frames/sec

Frames/sec is the rate at which data frames (or packets) are processed by the computer. This counter is the sum of data frames sent and data frames received. This counter only counts those frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes/sec

Frame Bytes/sec is the rate at which data bytes are processed by the computer. This counter is the sum of data frame bytes sent and received. This counter only counts the byte in frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Bytes Total/sec

Bytes Total/sec is the sum of Frame Bytes/sec and Datagram Bytes/sec. This is the total rate of bytes sent to or received from the network by the protocol, but only counts the bytes in frames (i.e., packets) which carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Connections Open

Connections Open is the number of connections currently open for this protocol. This counter shows the current count only and does not accumulate over time.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connections No Retries

Connections No Retries is the total count of connections that were successfully made on the first try. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connections With Retries

Connections With Retries is the total count of connections that were made after retrying the attempt. A retry occurs when the first connection attempt failed. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Disconnects Local

Disconnects Local is the number of session disconnections that were initiated by the local computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Disconnects Remote

Disconnects Remote is the number of session disconnections that were initiated by the remote computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Link

Failures Link is the number of connections that were dropped due to a link failure. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Adapter

Failures Adapter is the number of connections that were dropped due to an adapter failure. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connection Session Timeouts

Connection Session Timeouts is the number of connections that were dropped due to a session time out. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connections Canceled

Connections Canceled is the number of connections that were canceled. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Resource Remote

Failures Resource Remote is the number of connections that failed because of resource problems or shortages on the remote computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Resource Local

Failures Resource Local is the number of connections that failed because of resource problems or shortages on the local computer. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures Not Found

Failures Not Found is the number of connection attempts that failed because the remote computer could not be found. This number is an accumulator and shows a running total.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Failures No Listen

Failures No Listen is the number of connections that were rejected because the remote computer was not listening for connection requests.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Datagrams Sent/sec

Datagrams Sent/sec is the rate at which datagrams are sent from the computer. A datagram is a connectionless packet whose delivery to a remote computer is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagram Bytes Sent/sec

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Datagrams Received/sec

Datagrams Received/sec is the rate at which datagrams are received by the computer. A datagram is a connectionless packet whose delivery to a remote computer is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagram Bytes Received/sec

Datagram Bytes Received/sec is the rate at which datagram bytes are received by the computer. A datagram is a connectionless packet whose delivery to a remote computer is not guaranteed.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Packets Sent/sec

Packets Sent/sec is the rate at which packets are sent by the computer. This counter counts all packets sent by the computer, i.e. control as well as data packets.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Packets Received/sec

Packets Received/sec is the rate at which packets are received by the computer. This counter counts all packets processed: control as well as data packets.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Frames Sent/sec

Frames Sent/sec is the rate at which data frames are sent by the computer. This counter only counts the frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Sent/sec

Frame Bytes Sent/sec is the rate at which data bytes are sent by the computer. This counter only counts the bytes in frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Frames Received/sec

Frames Received/sec is the rate at which data frames are received by the computer. This counter only counts the frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Received/sec

Frame Bytes Received/sec is the rate at which data bytes are received by the computer. This counter only counts the frames (packets) that carry data.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Frames Re-Sent/sec

Frames Re-Sent/sec is the rate at which data frames (packets) are re-sent by the computer. This counter only counts the frames or packets that carry data.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Re-Sent/sec

Frame Bytes Re-Sent/sec is the rate at which data bytes are re-sent by the computer. This counter only counts the bytes in frames that carry data.

Detail Level: Wizard
Counter Type: PERF_COUNTER_BULK_COUNT

Frames Rejected/sec

Frames Rejected/sec is the rate at which data frames are rejected. This counter only counts the frames (packets) that carry data.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Frame Bytes Rejected/sec

Frame Bytes Rejected/sec is the rate at which data bytes are rejected. This counter only counts the bytes in data frames (packets) that carry data.

Detail Level: Expert
Counter Type: PERF_COUNTER_BULK_COUNT

Expirations Response

Expirations Response is the count of T1 timer expirations.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Expirations Ack

Expirations Ack is the count of T2 timer expirations

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Window Send Maximum

Window Send Maximum is the maximum number of bytes of data that will be sent before waiting for an acknowledgment from the remote computer.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Window Send Average

Window Send Average is the running average number of data bytes that were sent before waiting for an acknowledgment from the remote computer.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Piggyback Ack Queued/sec

Piggyback Ack Queued/sec is the rate at which piggybacked acknowledgments are queued. Piggyback acknowledgments are acknowledgments to received packets that are to be included in the next outgoing packet to the remote computer.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Piggyback Ack Timeouts

Piggyback Ack Timeouts is the number of times that a piggyback acknowledgment could not be sent because there was no outgoing packet to the remote on which to piggyback. A piggyback ack is an acknowledgment to a received packet that is sent along in an outgoing data packet to the remote computer. If no outgoing packet is sent within the time-out period, then an ack packet is sent and this counter is incremented.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT


Objects Object

The Objects performance object consists of counters that monitor logical objects in the system, such as processes, threads, mutexes, and semaphores. This information can be used to detect the unnecessary consumption of computer resources. Each object requires memory to store basic information about the object.

Processes

Processes is the number of processes in the computer at the time of data collection. Notice that this is an instantaneous count, not an average over the time interval. Each process represents the running of a program.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Threads

Threads is the number of threads in the computer at the time of data collection. Notice that this is an instantaneous count, not an average over the time interval. A thread is the basic executable entity that can execute instructions in a processor.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Events

Events is the number of events in the computer at the time of data collection. Notice that this is an instantaneous count, not an average over the time interval. An event is used when two or more threads wish to synchronize execution.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Semaphores

Semaphores is the number of semaphores in the computer at the time of data collection. Notice that this is an instantaneous count, not an average over the time interval. Threads use semaphores to obtain exclusive access to data structures that they share with other threads.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Mutexes

Mutexes counts the number of mutexes in the computer at the time of data collection. This is an instantaneous count, not an average over the time interval. Mutexes are used by threads to assure only one thread is executing some section of code.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Sections

Sections is the number of sections in the computer at the time of data collection. Notice that this is an instantaneous count, not an average over the time interval. A section is a portion of virtual memory created by a process for a storing data. A process might share sections with other processes.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT


Paging File Object

The Paging File performance object consists of counters that monitor the paging file(s) on the computer. The paging file is a reserved space on disk that backs up committed physical memory on the computer.

Usage

The amount of the Page File instance in use in percent. See also Process:Page File Bytes.

Detail Level: Advanced
Counter Type: PERF_RAW_FRACTION

% Usage

The amount of the Page File instance in use in percent. See also Process:Page File Bytes.

Detail Level: Advanced
Counter Type: PERF_RAW_BASE

% Usage Peak

The peak usage of the Page File instance in percent. See also Process:Page File Bytes Peak.

Detail Level: Advanced
Counter Type: PERF_RAW_FRACTION

% Usage Peak

The peak usage of the Page File instance in percent. See also Process:Page File Bytes Peak.

Detail Level: Advanced
Counter Type: PERF_RAW_BASE


Physical Disk Object

The Physical Disk performance object consists of counters that monitor hard or fixed disk drive on a computer. Disks are used to store file, program, and paging data and are read to retrieve these items, and written to record changes to them. The values of physical disk counters are sums of the values of the logical disks (or partitions) into which they are divided.

Current Disk Queue Length

Current Disk Queue Length is the number of requests outstanding on the disk at the time the performance data is collected. It includes requests in service at the time of the snapshot. This is an instantaneous length, not an average over the time interval. Multi-spindle disk devices can have multiple requests active at one time, but other concurrent requests are awaiting service. This counter might reflect a transitory high or low queue length, but if there is a sustained load on the disk drive, it is likely that this will be consistently high. Requests are experiencing delays proportional to the length of this queue minus the number of spindles on the disks. This difference should average less than 2 for good performance.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

% Disk Time

Disk Time is the percentage of elapsed time that the selected disk drive is busy servicing read or write requests.

Detail Level: Novice
Counter Type: PERF_COUNTER_TIMER

Avg. Disk Queue Length

Avg. Disk Queue Length is the average number of both read and write requests that were queued for the selected disk during the sample interval.

Detail Level: Novice
Counter Type: 0x450500,

% Disk Read Time

Disk Read Time is the percentage of elapsed time that the selected disk drive is busy servicing read requests.

Detail Level: Novice
Counter Type: PERF_COUNTER_TIMER

Avg. Disk Read Queue Length

Avg. Disk Read Queue Length is the average number of read requests that were queued for the selected disk during the sample interval.

Detail Level: Novice
Counter Type: 0x450500,

% Disk Write Time

Disk Write Time is the percentage of elapsed time that the selected disk drive is busy servicing write requests.

Detail Level: Novice
Counter Type: PERF_COUNTER_TIMER

Avg. Disk Write Queue Length

Avg. Disk Write Queue Length is the average number of write requests that were queued for the selected disk during the sample interval.

Detail Level: Novice
Counter Type: 0x450500,

Avg. Disk sec/Transfer

Avg. Disk sec/Transfer is the time in seconds of the average disk transfer.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_TIMER

Avg. Disk sec/Transfer

Avg. Disk sec/Transfer is the time in seconds of the average disk transfer.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_BASE

Avg. Disk sec/Read

Avg. Disk sec/Read is the average time in seconds of a read of data from the disk.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_TIMER

Avg. Disk sec/Read

Avg. Disk sec/Read is the average time in seconds of a read of data from the disk.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_BASE

Avg. Disk sec/Write

Avg. Disk sec/Write is the average time in seconds of a write of data to the disk.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_TIMER

Avg. Disk sec/Write

Avg. Disk sec/Write is the average time in seconds of a write of data to the disk.

Detail Level: Advanced
Counter Type: PERF_AVERAGE_BASE

Disk Transfers/sec

Disk Transfers/sec is the rate of read and write operations on the disk.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Disk Reads/sec

Disk Reads/sec is the rate of read operations on the disk.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Disk Writes/sec

Disk Writes/sec is the rate of write operations on the disk.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Disk Bytes/sec

Disk Bytes/sec is the rate bytes are transferred to or from the disk during write or read operations.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Disk Read Bytes/sec

Disk Read Bytes/sec is the rate bytes are transferred from the disk during read operations.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Disk Write Bytes/sec

Disk Write Bytes is rate bytes are transferred to the disk during write operations.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Avg. Disk Bytes/Transfer

Avg. Disk Bytes/Transfer is the average number of bytes transferred to or from the disk during write or read operations.

Detail Level: Expert
Counter Type: PERF_AVERAGE_BULK

Avg. Disk Bytes/Transfer

Avg. Disk Bytes/Transfer is the average number of bytes transferred to or from the disk during write or read operations.

Detail Level: Expert
Counter Type: PERF_AVERAGE_BASE

Avg. Disk Bytes/Read

Avg. Disk Bytes/Read is the average number of bytes transferred from the disk during read operations.

Detail Level: Expert
Counter Type: PERF_AVERAGE_BULK

Avg. Disk Bytes/Read

Avg. Disk Bytes/Read is the average number of bytes transferred from the disk during read operations.

Detail Level: Expert
Counter Type: PERF_AVERAGE_BASE

Avg. Disk Bytes/Write

Avg. Disk Bytes/Write is the average number of bytes transferred to the disk during write operations.

Detail Level: Expert
Counter Type: PERF_AVERAGE_BULK

Avg. Disk Bytes/Write

Avg. Disk Bytes/Write is the average number of bytes transferred to the disk during write operations.

Detail Level: Expert
Counter Type: PERF_AVERAGE_BASE


Process Object

The Process performance object consists of counters that monitor running application program and system processes. All the threads in a process share the same address space and have access to the same data.

Processor Time

Processor Time is the percentage of elapsed time that all of the threads of this process used the processor to execute instructions. An instruction is the basic unit of execution in a computer, a thread is the object that executes instructions, and a process is the object created when a program is run. Code executed to handle some hardware interrupts and trap conditions are included in this count.

Detail Level: Novice
Counter Type: PERF_100NSEC_TIMER

% User Time

User Time is the percentage of elapsed time that this process's threads have spent executing code in user mode. Applications, environment subsystems, and integral subsystems execute in user mode. Code executing in User Mode cannot damage the integrity of the Windows NT Executive, Kernel, and device drivers. Unlike some early operating systems, Windows NT uses process boundaries for subsystem protection in addition to the traditional protection of user and privileged modes. These subsystem processes provide additional protection. Therefore, some work done by Windows NT on behalf of your application might appear in other subsystem processes in addition to the privileged time in your process.

Detail Level: Advanced
Counter Type: PERF_100NSEC_TIMER

% Privileged Time

Privileged Time is the percentage of elapsed time that the threads of the process have spent executing code in privileged mode. When a Windows NT system service is called, the service will often run in Privileged Mode to gain access to system-private data. Such data is protected from access by threads executing in user mode. Calls to the system can be explicit or implicit, such as page faults or interrupts. Unlike some early operating systems, Windows NT uses process boundaries for subsystem protection in addition to the traditional protection of user and privileged modes. These subsystem processes provide additional protection. Therefore, some work done by Windows NT on behalf of your application might appear in other subsystem processes in addition to the privileged time in your process.

Detail Level: Advanced
Counter Type: PERF_100NSEC_TIMER

Virtual Bytes Peak

Virtual Bytes Peak is the maximum number of bytes of virtual address space the process has used at any one time. Use of virtual address space does not necessarily imply corresponding use of either disk or main memory pages. Virtual space is however finite, and by using too much, the process might limit its ability to load libraries.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Virtual Bytes

Virtual Bytes is the current size in bytes of the virtual address space the process is using. Use of virtual address space does not necessarily imply corresponding use of either disk or main memory pages. Virtual space is finite, and by using too much, the process can limit its ability to load libraries.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Page Faults/sec

Page Faults/sec is the rate of Page Faults by the threads executing in this process. A page fault occurs when a thread refers to a virtual memory page that is not in its working set in main memory. This will not cause the page to be fetched from disk if it is on the standby list and hence already in main memory, or if it is in use by another process with whom the page is shared.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Working Set Peak

Working Set Peak is the maximum number of bytes in the Working Set of this process at any point in time. The Working Set is the set of memory pages touched recently by the threads in the process. If free memory in the computer is above a threshold, pages are left in the Working Set of a process even if they are not in use. When free memory falls below a threshold, pages are trimmed from Working Sets. If they are needed they will then be soft-faulted back into the Working Set before they leave main memory.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Working Set

Working Set is the current number of bytes in the Working Set of this process. The Working Set is the set of memory pages touched recently by the threads in the process. If free memory in the computer is above a threshold, pages are left in the Working Set of a process even if they are not in use. When free memory falls below a threshold, pages are trimmed from Working Sets. If they are needed they will then be soft-faulted back into the Working Set before they leave main memory.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Page File Bytes Peak

Page File Bytes Peak is the maximum number of bytes this process has used in the paging file(s). Paging files are used to store pages of memory used by the process that are not contained in other files. Paging files are shared by all processes, and lack of space in paging files can prevent other processes from allocating memory.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Page File Bytes

Page File Bytes is the current number of bytes this process has used in the paging file(s). Paging files are used to store pages of memory used by the process that are not contained in other files. Paging files are shared by all processes, and lack of space in paging files can prevent other processes from allocating memory.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Private Bytes

Private Bytes is the current number of bytes this process has allocated that cannot be shared with other processes.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Thread Count

The number of threads currently active in this process. An instruction is the basic unit of execution in a processor, and a thread is the object that executes instructions. Every running process has at least one thread.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Priority Base

The current base priority of this process. Threads within a process can raise and lower their own base priority relative to the process's base priority.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Elapsed Time

The total elapsed time (in seconds) this process has been running.

Detail Level: Advanced
Counter Type: PERF_ELAPSED_TIME

ID Process

ID Process is the unique identifier of this process. ID Process numbers are reused, so they only identify a process for the lifetime of that process.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Pool Paged Bytes

Pool Paged Bytes is the number of bytes in the Paged Pool, a system memory area where space is acquired by operating system components as they accomplish their appointed tasks. Paged Pool pages can be paged out to the paging file when not accessed by the system for sustained periods of time.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Pool Nonpaged Bytes

Pool Nonpaged Bytes is the number of bytes in the nonpaged pool, a system memory area where space is acquired by operating system components as they accomplish their appointed tasks. Nonpaged pool pages cannot be paged out to the paging file, but instead remain in main memory as long as they are allocated.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Handle Count

The total number of handles currently open by this process. This number is the sum of the handles currently open by each thread in this process.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT


Process Address Space Object

The Process Address Space performance object consists of counters that monitor memory allocation and use for a selected process.

Bytes Image Reserved

Bytes Image Reserved is the sum of all virtual memory reserved by images run within this process.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

ID Process

ID Process is the unique identifier of this process. ID Process numbers are reused, so they only identify a process for the lifetime of that process.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Bytes Image Free

Bytes Image Free is the amount of virtual address space that is not in use or reserved by images within this process.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Bytes Reserved

Bytes Reserved is the total amount of virtual memory reserved for future use by this process.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Bytes Free

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Bytes Free is the total unused virtual address space of this process.

Mapped Space No Access

Mapped Space is virtual memory that has been mapped  to a specific virtual address (or range of virtual addresses) in the process's virtual address space. No Access protection prevents a process from writing to or reading from these pages and will generate an access violation if either is attempted.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Mapped Space Read Only

Mapped Space is virtual memory that has been mapped  to a specific virtual address (or range of virtual addresses) in the process's virtual address space. Read Only protection prevents the contents of these pages from being modified. Any attempts to write or modify these pages will generate an access violation.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Mapped Space Read/Write

Mapped Space is virtual memory that has been mapped  to a specific virtual address (or range of virtual addresses) in the process's virtual address space. Read/Write protection allows a process to read, modify and write to these pages.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Mapped Space Write Copy

Mapped Space is virtual memory that has been mapped  to a specific virtual address (or range of virtual addresses) in the process's virtual address space. Write Copy protection is used when memory is shared for reading but not for writing. When processes are reading this memory, they can share the same memory, however, when a sharing process wants to have write access to this shared memory, a copy of that memory is made.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Mapped Space Executable

Mapped Space is virtual memory that has been mapped  to a specific virtual address (or range of virtual addresses) in the process's virtual address space. Executable memory is memory that can be executed by programs, but cannot be read or written. This type of protection is not supported by all processor types.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Mapped Space Exec Read Only

Mapped Space is virtual memory that has been mapped  to a specific virtual address (or range of virtual addresses) in the process's virtual address space. Execute/Read Only memory is memory that can be executed as well as read.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Mapped Space Exec Read/Write

Mapped Space is virtual memory that has been mapped  to a specific virtual address (or range of virtual addresses) in the process's virtual address space. Execute/Read/Write memory is memory that can be executed by programs as well as read and modified.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Mapped Space Exec Write Copy

Mapped Space is virtual memory that has been mapped  to a specific virtual address (or range of virtual addresses) in the process's virtual address space. Execute Write Copy is memory that can be executed by programs as well as read and written. This type of protection is used when memory needs to be shared between processes. If the sharing processes only read the memory, then they will all use the same memory. If a sharing process desires write access, then a copy of this memory will be made for that process.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Reserved Space No Access

Reserved Space is virtual memory that has been reserved for future use by a process, but has not been mapped or committed. No Access protection prevents a process from writing to or reading from these pages and will generate an access violation if either is attempted.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Reserved Space Read Only

Reserved Space is virtual memory that has been reserved for future use by a process, but has not been mapped or committed. Read Only protection prevents the contents of these pages from being modified. Any attempts to write or modify these pages will generate an access violation.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Reserved Space Read/Write

Reserved Space is virtual memory that has been reserved for future use by a process, but has not been mapped or committed. Read/Write protection allows a process to read, modify and write to these pages.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Reserved Space Write Copy

Reserved Space is virtual memory that has been reserved for future use by a process, but has not been mapped or committed. Write Copy protection is used when memory is shared for reading but not for writing. When processes are reading this memory, they can share the same memory, however, when a sharing process wants to have read/write access to this shared memory, a copy of that memory is made.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Reserved Space Executable

Reserved Space is virtual memory that has been reserved for future use by a process, but has not been mapped or committed. Executable memory is memory that can be executed by programs, but cannot be read or written. This type of protection is not supported by all processor types.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Reserved Space Exec Read Only

Reserved Space is virtual memory that has been reserved for future use by a process, but has not been mapped or committed. Execute/Read Only memory is memory that can be executed as well as read.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Reserved Space Exec Read/Write

Reserved Space is virtual memory that has been reserved for future use by a process, but has not been mapped or committed. Execute/Read/Write memory is memory that can be executed by programs as well as read and modified.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Reserved Space Exec Write Copy

Reserved Space is virtual memory that has been reserved for future use by a process, but has not been mapped or committed. Execute Write Copy is memory that can be executed by programs as well as read and written. This type of protection is used when memory needs to be shared between processes. If the sharing processes only read the memory, then they will all use the same memory. If a sharing process desires write access, then a copy of this memory will be made for that process.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Unassigned Space No Access

Unassigned Space is mapped and committed virtual memory in use by the process that is not attributable to any particular image being executed by that process. No Access protection prevents a process from writing to or reading from these pages and will generate an access violation if either is attempted.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Unassigned Space Read Only

Unassigned Space is mapped and committed virtual memory in use by the process that is not attributable to any particular image being executed by that process. Read Only protection prevents the contents of these pages from being modified. Any attempts to write or modify these pages will generate an access violation.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Unassigned Space Read/Write

Unassigned Space is mapped and committed virtual memory in use by the process that is not attributable to any particular image being executed by that process. Read/Write protection allows a process to read, modify and write to these pages.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Unassigned Space Write Copy

Unassigned Space is mapped and committed virtual memory in use by the process that is not attributable to any particular image being executed by that process. Write Copy protection is used when memory is shared for reading but not for writing. When processes are reading this memory, they can share the same memory, however, when a sharing process wants to have read/write access to this shared memory, a copy of that memory is made for writing to.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Unassigned Space Executable

Unassigned Space is mapped and committed virtual memory in use by the process that is not attributable to any particular image being executed by that process. Executable memory is memory that can be executed by programs, but cannot be read or written. This type of protection is not supported by all processor types.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Unassigned Space Exec Read Only

Unassigned Space is mapped and committed virtual memory in use by the process that is not attributable to any particular image being executed by that process. Execute/Read Only memory is memory that can be executed as well as read.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Unassigned Space Exec Read/Write

Unassigned Space is mapped and committed virtual memory in use by the process that is not attributable to any particular image being executed by that process. Execute/Read/Write memory is memory that can be executed by programs as well as read and written.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Unassigned Space Exec Write Copy

Unassigned Space is mapped and committed virtual memory in use by the process that is not attributable to any particular image being executed by that process. Execute Write Copy is memory that can be executed by programs as well as read and written. This type of protection is used when memory needs to be shared between processes. If the sharing processes only read the memory, then they will all use the same memory. If a sharing process desires write access, then a copy of this memory will be made for that process.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Image Space No Access

Image Space is the virtual address space in use by the images being executed by the process. This is the sum of all the address space with this protection allocated by images run by the selected process No Access protection prevents a process from writing to or reading from these pages and will generate an access violation if either is attempted.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Image Space Read Only

Image Space is the virtual address space in use by the images being executed by the process. This is the sum of all the address space with this protection allocated by images run by the selected process Read Only protection prevents the contents of these pages from being modified. Any attempts to write or modify these pages will generate an access violation.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Image Space Read/Write

Image Space is the virtual address space in use by the images being executed by the process. This is the sum of all the address space with this protection allocated by images run by the selected process Read/Write protection allows a process to read, modify and write to these pages.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Image Space Write Copy

Image Space is the virtual address space in use by the images being executed by the process. This is the sum of all the address space with this protection allocated by images run by the selected process Write Copy protection is used when memory is shared for reading but not for writing. When processes are reading this memory, they can share the same memory, however, when a sharing process wants to have read/write access to this shared memory, a copy of that memory is made for writing to.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Image Space Executable

Image Space is the virtual address space in use by the images being executed by the process. This is the sum of all the address space with this protection allocated by images run by the selected process Executable memory is memory that can be executed by programs, but cannot be read or written. This type of protection is not supported by all processor types.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Image Space Exec Read Only

Image Space is the virtual address space in use by the images being executed by the process. This is the sum of all the address space with this protection allocated by images run by the selected process Execute/Read Only memory is memory that can be executed as well as read.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Image Space Exec Read/Write

Image Space is the virtual address space in use by the images being executed by the process. This is the sum of all the address space with this protection allocated by images run by the selected process Execute/Read/Write memory is memory that can be executed by programs as well as read and written and modified.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Image Space Exec Write Copy

Image Space is the virtual address space in use by the images being executed by the process. This is the sum of all the address space with this protection allocated by images run by the selected process Execute Write Copy is memory that can be executed by programs as well as read and written. This type of protection is used when memory needs to be shared between processes. If the sharing processes only read the memory, then they will all use the same memory. If a sharing process desires write access, then a copy of this memory will be made for that process.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT


Processor Object

The Processor performance object consists of counters that measure aspects of processor activity The processor is the part of the computer that performs arithmetic and logical computations, initiates operations on peripherals, and runs the threads of processes. A computer can have multiple processors. The processor object represents each processor as an instance of the object.

%Processor Time

%Processor Time is the percentage of time that the processor is executing a non-Idle thread. This counter was designed as a primary indicator of processor activity. It is calculated by measuring the time that the processor spends executing the thread of the Idle process in each sample interval, and subtracting that value from 100%. (Each processor has an Idle thread which consumes cycles when no other threads are ready to run.) It can be viewed as the fraction of the time spent doing useful work.

Detail Level: Novice
Counter Type: PERF_100NSEC_TIMER_INV

%User Time

%User Time is the percentage of non-idle processor time spent in user mode. (User mode is a restricted processing mode designed for applications, environment subsystems, and integral subsystems. The alternative, privileged mode, is designed for operating system components and allows direct access to hardware and all memory. The operating system switches application threads to privileged mode to obtain operating system services.)

Detail Level: Advanced
Counter Type: PERF_100NSEC_TIMER

% Privileged Time

Privileged Time is the percentage of non-idle processor time spent in privileged mode. (Privileged mode is a processing mode designed for operating system components and hardware-manipulating drivers. It allows direct access to hardware and all memory. The alternative, user mode, is a restricted processing mode designed for applications, environment subsystems, and integral subsystems. The operating system switches application threads to privileged mode to obtain operating system services.) % Privileged Time includes time servicing interrupts and DPCs. A high rate of privileged time might be attributable to a large number of interrupts generated by a failing device.

Detail Level: Advanced
Counter Type: PERF_100NSEC_TIMER

Interrupts/sec

Interrupts/sec is the average number of hardware interrupts the processor is receiving and servicing in each second. It does not include DPCs, which are counted separately. This value is an indirect indicator of the activity of devices that generate interrupts, such as the system clock, the mouse, disk drivers, data communication lines, network interface cards and other peripheral devices. These devices normally interrupt the processor when they have completed a task or require attention. Normal thread execution is suspended during interrupts. Most system clocks interrupt the processor every 10 milliseconds, creating a background of interrupt activity.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

% DPC Time

% DPC Time is the percentage of time that the processor spent receiving and servicing deferred procedure calls (DPCs) during the sample interval.(DPCs are interrupts that run at a lower priority than standard interrupts.) % DPC Time is a component of % Privileged Time because DPCs are executed in privileged mode. They are counted separately and are not a component of the interrupt counters.

Detail Level: Advanced
Counter Type: PERF_100NSEC_TIMER

% Interrupt Time

% Interrupt Time is the percentage of time the processor spent receiving and servicing hardware interrupts during the sample interval. This value is an indirect indicator of the activity of devices that generate interrupts, such as the system clock, the mouse, disk drivers, data communication lines, network interface cards and other peripheral devices. These devices normally interrupt the processor when they have completed a task or require attention. Normal thread execution is suspended during interrupts. Most system clocks interrupt the processor every 10 milliseconds, creating a background of interrupt activity.

Detail Level: Advanced
Counter Type: PERF_100NSEC_TIMER

DPCs Queued/sec

DPCs Queued/sec is the overall rate at which deferred procedure calls (DPC) are added to the processor's DPC queue. (DPCs are interrupts that run at a lower priority than standard interrupts. Each processor has its own DPC queue.) This counter measures the rate at which DPCs are added to the queue, not the number of DPCs in the queue.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

DPC Rate

DPC Rate is the rate at which deferred procedure calls (DPC) are added to the processor’s DPC queue between the timer tics of the processor clock. DPC objects are queued to this processor's DPC queue per clock tick. (DPCs are interrupts that run at a lower priority than standard interrupts. Each processor has its own DPC queue.) This counter measures the rates at which DPCs are added to the queue, not the number of DPCs in the queue.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

DPC Bypasses/sec

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

DPC Bypasses/sec is the rate at which deferred procedure calls (DPC) on all processors were avoided. (DPCs are interrupts that run at a lower priority than standard interrupts.

APC Bypasses/sec

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

APC Bypasses/sec is the rate at which kernel APC interrupts were avoided. APC Bypasses/sec is the rate at which kernel APC interrupts were short-circuited. .


RAS Port Object

The RAS Port performance object consists of counters that monitor individual Remote Access Service (RAS) ports of the RAS device on the system.

Bytes Transmitted

The number of bytes transmitted total for this connection.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Bytes Received

The number of bytes received total for this connection.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Frames Transmitted

The number of data frames transmitted total for this connection.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Frames Received

The number of data frames received total for this connection.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Percent Compression Out

The compression ratio for bytes being transmitted.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Percent Compression In

The compression ratio for bytes being received.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

CRC Errors

The total number of CRC Errors for this connection. CRC Errors occur when the frame received contains erroneous data.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Timeout Errors

The total number of Timeout Errors for this connection. Timeout Errors occur when an expected is not received in time.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Serial Overrun Errors

The total number of Serial Overrun Errors for this connection. Serial Overrun Errors occur when the hardware cannot handle the rate at which data is received.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Alignment Errors

The total number of Alignment Errors for this connection. Alignment Errors occur when a byte received is different from the byte expected.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Buffer Overrun Errors

The total number of Buffer Overrun Errors for this connection. Buffer Overrun Errors when the software cannot handle the rate at which data is received.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Total Errors

The total number of CRC, Timeout, Serial Overrun, Alignment, and Buffer Overrun Errors for this connection.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Bytes Transmitted/Sec

The number of bytes transmitted per second.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Bytes Received/Sec

The number of bytes received per second.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Frames Transmitted/Sec

The number of frames transmitted per second.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Frames Received/Sec

The number of frames received per second.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Total Errors/Sec

The total number of CRC, Timeout, Serial Overrun, Alignment, and Buffer Overrun Errors per second.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER


RAS Total Object

The RAS Total performance object consists of counters that combine values for all ports of the Remote Access Service (RAS) device on the computer.

Bytes Transmitted

The number of bytes transmitted total for this connection.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Bytes Received

The number of bytes received total for this connection.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Frames Transmitted

The number of data frames transmitted total for this connection.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Frames Received

The number of data frames received total for this connection.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Percent Compression Out

The compression ratio for bytes being transmitted.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Percent Compression In

The compression ratio for bytes being received.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

CRC Errors

The total number of CRC Errors for this connection. CRC Errors occur when the frame received contains erroneous data.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Timeout Errors

The total number of Timeout Errors for this connection. Timeout Errors occur when an expected is not received in time.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Serial Overrun Errors

The total number of Serial Overrun Errors for this connection. Serial Overrun Errors occur when the hardware cannot handle the rate at which data is received.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Alignment Errors

The total number of Alignment Errors for this connection. Alignment Errors occur when a byte received is different from the byte expected.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Buffer Overrun Errors

The total number of Buffer Overrun Errors for this connection. Buffer Overrun Errors when the software cannot handle the rate at which data is received.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Total Errors

The total number of CRC, Timeout, Serial Overrun, Alignment, and Buffer Overrun Errors for this connection.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Bytes Transmitted/Sec

The number of bytes transmitted per second.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Bytes Received/Sec

The number of bytes received per second.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Frames Transmitted/Sec

The number of frames transmitted per second.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Frames Received/Sec

The number of frames received per second.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Total Errors/Sec

The total number of CRC, Timeout, Serial Overrun, Alignment, and Buffer Overrun Errors per second.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Total Connections

The total number of Remote Access connections.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT


Redirector Object

The Redirector performance object consists of counter that monitor network connections originating at the local computer.

Bytes Total/sec

Bytes Total/sec is the rate the Redirector is processing data bytes. This includes all application and file data in addition to protocol information such as packet headers.

Detail Level: Novice
Counter Type: PERF_COUNTER_BULK_COUNT

File Data Operations/sec

File Data Operations/sec is the rate the Redirector is processing data operations. One operation includes (hopefully) many bytes. We say hopefully here because each operation has overhead. You can determine the efficiency of this path by dividing the Bytes/sec by this counter to determine the average number of bytes transferred/operation.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Packets/sec

Packets/sec is the rate the Redirector is processing data packets. One packet includes (hopefully) many bytes. We say hopefully here because each packet has protocol overhead. You can determine the efficiency of this path by dividing the Bytes/sec by this counter to determine the average number of bytes transferred/packet. You can also divide this counter by Operations/sec to determine the average number of packets per operation, another measure of efficiency.

Detail Level: Novice
Counter Type: PERF_COUNTER_BULK_COUNT

Bytes Received/sec

Bytes Received/sec is the rate of bytes coming in to the Redirector from the network. It includes all application data as well as network protocol information (such as packet headers.)

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Packets Received/sec

Packets Received/sec is the rate at which the Redirector is receiving packets (also called SMBs or Server Message Blocks). Network transmissions are divided into packets. The average number of bytes received in a packet can be obtained by dividing Bytes Received/sec by this counter. Some packets received might not contain incoming data, for example an acknowledgment to a write made by the Redirector would count as an incoming packet.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Read Bytes Paging/sec

Read Bytes Paging/sec is the rate at which the Redirector is attempting to read bytes in response to page faults. Page faults are caused by loading of modules (such as programs and libraries), by a miss in the Cache (see Read Bytes Cache/sec), or by files directly mapped into the address space of applications (a high-performance feature of Windows NT.)

Detail Level: Expert
Counter Type: PERF_COUNTER_BULK_COUNT

Read Bytes Non-Paging/sec

Read Bytes Non-Paging/sec are those bytes read by the Redirector in response to normal file requests by an application when they are redirected to come from another computer. In addition to file requests, this counter includes other methods of reading across the network such as Named Pipes and Transactions. This counter does not count network protocol information, just application data.

Detail Level: Expert
Counter Type: PERF_COUNTER_BULK_COUNT

Read Bytes Cache/sec

Read Bytes Cache/sec is the rate at which applications are accessing the file system cache by using the Redirector. Some of these data requests are satisfied by retrieving the data from the cache. Requests that miss the cache cause a page fault (see Read Bytes Paging/sec).

Detail Level: Expert
Counter Type: PERF_COUNTER_BULK_COUNT

Read Bytes Network/sec

Read Bytes Network/sec is the rate at which applications are reading data across the network. This occurs when data sought in the file system cache is not found there and must be retrieved from the network. Dividing this value by Bytes Received/sec indicates the proportion of application data traveling across the network (see Bytes Received/sec.)

Detail Level: Novice
Counter Type: PERF_COUNTER_BULK_COUNT

Bytes Transmitted/sec

Bytes Transmitted/sec is the rate at which bytes are leaving the Redirector to the network. It includes all application data as well as network protocol information (such as packet headers and the like.)

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Packets Transmitted/sec

Packets Transmitted/sec is the rate at which the Redirector is sending packets (also called SMBs or Server Message Blocks). Network transmissions are divided into packets. The average number of bytes transmitted in a packet can be obtained by dividing Bytes Transmitted/sec by this counter.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Write Bytes Paging/sec

Write Bytes Paging/sec is the rate at which the Redirector is attempting to write bytes changed in the pages being used by applications. The program data changed by modules (such as programs and libraries) that were loaded over the network are 'paged out' when no longer needed. Other output pages come from the cache (see Write Bytes Cache/sec).

Detail Level: Expert
Counter Type: PERF_COUNTER_BULK_COUNT

Write Bytes Non-Paging/sec

Write Bytes Non-Paging/sec is the rate at which bytes are written by the Redirector in response to normal file outputs by an application when they are redirected to another computer. In addition to file requests this counter includes other methods of writing across the network such as Named Pipes and Transactions. This counter does not count network protocol information, just application data.

Detail Level: Expert
Counter Type: PERF_COUNTER_BULK_COUNT

Write Bytes Cache/sec

Write Bytes Cache/sec is the rate at which applications on your computer are writing to the file system cache using the Redirector. The data might not leave your computer immediately; it can be retained in the cache for further modification before being written to the network. This saves network traffic. Each write of a byte into the cache is counted here.

Detail Level: Expert
Counter Type: PERF_COUNTER_BULK_COUNT

Write Bytes Network/sec

Write Bytes Network/sec is the rate at which applications are writing data across the network. This occurs when the file system cache is, such as for named pipes or transactions, or else the cache writes the bytes to disk to make room for other data. Dividing this counter by Bytes Transmitted/sec will indicate the proportion of application data being written to the network (see Transmitted Bytes/sec.)

Detail Level: Novice
Counter Type: PERF_COUNTER_BULK_COUNT

File Read Operations/sec

File Read Operations/sec is the rate at which applications are asking the Redirector for data. Each call to a file system or similar Application Program Interface (API) call counts as one operation.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Read Operations Random/sec

Read Operations Random/sec counts the rate at which, on a file-by-file basis, reads are made that are not sequential. If a read is made using a particular file handle, and then is followed by another read that is not immediately the contiguous next byte, this counter is incremented by one.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Read Packets/sec

Read Packets/sec is the rate at which read packets are being placed on the network. Each time a single packet is sent with a request to read data remotely, this counter is incremented by one.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Reads Large/sec

Reads Large/sec is the rate at which reads over 2 times the server's negotiated buffer size are made by applications. Too many of these could place a strain on server resources. This counter is incremented once for each read. It does not count packets.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Read Packets Small/sec

Read Packets Small/sec is the rate at which reads less than one-fourth of the server's negotiated buffer size are made by applications. Too many of these could indicate a waste of buffers on the server. This counter is incremented once for each read. It does not count packets.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

File Write Operations/sec

File Write Operations/sec is the rate at which applications are sending data to the Redirector. Each call to a file system or similar Application Program Interface (API) call counts as one operation.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Write Operations Random/sec

Write Operations Random/sec is the rate at which, on a file-by-file basis, writes are made that are not sequential. If a write is made using a particular file handle, and then is followed by another write that is not immediately the next contiguous byte, this counter is incremented by one.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Write Packets/sec

Write Packets/sec is the rate at which writes are being sent to the network. Each time a single packet is sent with a request to write remote data, this counter is incremented by one.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Writes Large/sec

Writes Large/sec is the rate at which writes are made by applications that are over 2 times the server's negotiated buffer size. Too many of these could place a strain on server resources. This counter is incremented once for each write: it counts writes, not packets.

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Write Packets Small/sec

Write Packets Small/sec is the rate at which writes are made by applications that are less than one-fourth of the server's negotiated buffer size. Too many of these could indicate a waste of buffers on the server. This counter is incremented once for each write: it counts writes, not packets!

Detail Level: Expert
Counter Type: PERF_COUNTER_COUNTER

Reads Denied/sec

Reads Denied/sec is the rate at which the server is unable to accommodate requests for Raw Reads. When a read is much larger than the server's negotiated buffer size, the Redirector requests a Raw Read which, if granted, would permit the transfer of the data without lots of protocol overhead on each packet. To accomplish this the server must lock out other requests, so the request is denied if the server is really busy.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Writes Denied/sec

Writes Denied/sec is the rate at which the server is unable to accommodate requests for Raw Writes. When a write is much larger than the server's negotiated buffer size, the Redirector requests a Raw Write which, if granted, would permit the transfer of the data without lots of protocol overhead on each packet. To accomplish this the server must lock out other requests, so the request is denied if the server is really busy.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Network Errors/sec

Network Errors/sec counts serious unexpected errors that generally indicate the Redirector and one or more Servers are having serious communication difficulties. For example an SMB (Server Manager Block) protocol error will generate a Network Error. These result in an entry in the system Event Log, so look there for details.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Server Sessions

Server Sessions counts the total number of security objects the Redirector has managed. For example, a logon to a server followed by a network access to the same server will establish one connection, but two sessions.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Server Reconnects

Server Reconnects counts the number of times your Redirector has had to reconnect to a server in order to complete a new active request. You can be disconnected by the Server if you remain inactive for too long. Locally even if all your remote files are closed, the Redirector will keep your connections intact for (nominally) ten minutes. Such inactive connections are called Dormant Connections. Reconnecting is expensive in time.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connects Core

Connects Core counts the number of connections you have to servers running the original MS-Net SMB protocol, including MS-Net itself and Xenix and VAXs.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connects LAN Manager 2.0

Connects LAN Manager 2.0 counts connections to LAN Manager 2.0 servers, including LMX servers.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connects LAN Manager 2.1

Connects LAN Manager 2.1 counts connections to LAN Manager 2.1 servers, including LMX servers.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connects Windows NT

Connects Windows NT counts the connections to Windows NT computers.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Server Disconnects

Server Disconnects counts the number of times a Server has disconnected your Redirector. See also Server Reconnects.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Server Sessions Hung

Server Sessions Hung counts the number of active sessions that are timed out and unable to proceed due to a lack of response from the remote server.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Current Commands

Current Commands counts the number of requests to the Redirector that are currently queued for service. If this number is much larger than the number of network adapter cards installed in the computer, then the network(s) and/or the server(s) being accessed are seriously bottlenecked.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT


Server Object

The Server performance object consists of counters that measure communication between the  local computer and the network.

Bytes Total/sec

The number of bytes the server has sent to and received from the network. This value provides an overall indication of how busy the server is.

Detail Level: Novice
Counter Type: PERF_COUNTER_BULK_COUNT

Bytes Received/sec

The number of bytes the server has received from the network. Indicates how busy the server is.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Bytes Transmitted/sec

The number of bytes the server has sent on the network. Indicates how busy the server is.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Sessions Timed Out

The number of sessions that have been closed due to their idle time exceeding the AutoDisconnect parameter for the server. Shows whether the AutoDisconnect setting is helping to conserve resources.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Sessions Errored Out

The number of sessions that have been closed due to unexpected error conditions. Indicates how frequently network problems are causing dropped sessions on the server.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Sessions Logged Off

The number of sessions that have terminated normally. Useful in interpreting the Sessions Times Out and Sessions Errored Out statistics--allows percentage calculations.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Sessions Forced Off

The number of sessions that have been forced to logoff. Can indicate how many sessions were forced to logoff due to logon time constraints.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Errors Logon

The number of failed logon attempts to the server. Can indicate whether password guessing programs are being used to crack the security on the server.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Errors Access Permissions

The number of times opens on behalf of clients have failed with STATUS_ACCESS_DENIED. Can indicate whether somebody is randomly attempting to access files in hopes of getting at something that was not properly protected.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Errors Granted Access

The number of times accesses to files opened successfully were denied. Can indicate attempts to access files without proper access authorization.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Errors System

The number of times an internal Server Error was detected. Unexpected errors usually indicate a problem with the Server.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Blocking Requests Rejected

The number of times the server has rejected blocking SMBs due to insufficient count of free work items. Indicates whether the MaxWorkItem or MinFreeWorkItems server parameters might need tuning.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Work Item Shortages

The number of times STATUS_DATA_NOT_ACCEPTED was returned at receive indication time. This occurs when no work item is available or can be allocated to service the incoming request. Indicates whether the InitWorkItems or MaxWorkItems parameters might need to be adjusted.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Files Opened Total

The number of successful open attempts performed by the server of behalf of clients. Useful in determining the amount of file I/O, determining overhead for path-based operations, and for determining the effectiveness of open locks.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Files Open

The number of files currently opened in the server. Indicates current server activity.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

Server Sessions

The number of sessions currently active in the server. Indicates current server activity.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT

File Directory Searches

The number of searches for files currently active in the server. Indicates current server activity.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Pool Nonpaged Bytes

The number of bytes of non-pageable computer memory the server is currently using. This value is useful for determining good values for the MaxNonpagedMemoryUsage parameter.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Pool Nonpaged Failures

The number of times allocations from nonpaged pool have failed. Indicates that the computer's physical memory is too small.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Pool Nonpaged Peak

The maximum number of bytes of nonpaged pool the server has had in use at any one point. Indicates how much physical memory the computer should have.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Pool Paged Bytes

The number of bytes of pageable computer memory the server is currently using. Can help in determining good values for the MaxPagedMemoryUsage parameter.

Detail Level: Expert
Counter Type: PERF_COUNTER_RAWCOUNT

Pool Paged Failures

The number of times allocations from paged pool have failed. Indicates that the computer's physical memory or page file are too small.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Pool Paged Peak

The maximum number of bytes of paged pool the server has had allocated. Indicates the proper sizes of the Page File(s) and physical memory.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Context Blocks Queued/sec

Context Blocks Queued per second is the rate at which work context blocks had to be placed on the server's FSP queue to await server action.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Logon/sec

Logon/sec includes the rate of all interactive logons, network logons, service logons, successful logon, and failed logons.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

Logon Total

Logon Total includes all interactive logons, network logons, service logons, successful logon, and failed logons since the machine is last rebooted.

Detail Level: Novice
Counter Type: PERF_COUNTER_RAWCOUNT


Server Work Queues Object

The Server Work Queues performance object consists of counters that monitor the length of the queues and objects in the queues.

Queue Length

Queue Length is the current length of the server work queue for this CPU. A sustained queue length greater than four might indicate processor congestion. This is an instantaneous count, not an average over time.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Active Threads

Active Threads is the number of threads currently working on a request from the server client for this CPU. The system keeps this number as low as possible to minimize unnecessary context switching. This is an instantaneous count for the CPU, not an average over time.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Available Threads

Available Threads is the number of server threads on this CPU not currently working on requests from a client. The server dynamically adjusts the number of threads to maximize server performance.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Available Work Items

Every request from a client is represented in the server as a 'work item,' and the server maintains a pool of available work items per CPU to speed processing. This is the instantaneous number of available work items for this CPU. A sustained near-zero value indicates the need to increase the MinFreeWorkItems registry value for the Server service. This value will always be 0 in the Blocking Queue instance.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Borrowed Work Items

Every request from a client is represented in the server as a 'work item,' and the server maintains a pool of available work items per CPU to speed processing. When a CPU runs out of work items, it borrows a free work item from another CPU. An increasing value of this running counter might indicate the need to increase the 'MaxWorkItems' or 'MinFreeWorkItems' registry values for the Server service. This value will always be 0 in the Blocking Queue instance.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Work Item Shortages

Every request from a client is represented in the server as a 'work item,' and the server maintains a pool of available work items per CPU to speed processing. A sustained value greater than zero indicates the need to increase the 'MaxWorkItems' registry value for the Server service. This value will always be 0 in the Blocking Queue instance.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Current Clients

Current Clients is the instantaneous count of the clients being serviced by this CPU. The server actively balances the client load across all of the CPU's in the system. This value will always be 0 in the Blocking Queue instance.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Bytes Received/sec

The rate at which the Server is receiving bytes from the network clients on this CPU. This value is a measure of how busy the Server is.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Bytes Sent/sec

The rate at which the Server is sending bytes to the network clients on this CPU. This value is a measure of how busy the Server is.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Bytes Transferred/sec

The rate at which the Server is sending and receiving bytes with the network clients on this CPU. This value is a measure of how busy the Server is.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Read Operations/sec

Read Operations/sec is the rate the server is performing file read operations for the clients on this CPU. This value is a measure of how busy the Server is. This value will always be 0 in the Blocking Queue instance.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Read Bytes/sec

Read Bytes/sec is the rate the server is reading data from files for the clients on this CPU. This value is a measure of how busy the Server is.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Write Operations/sec

Write Operations/sec is the rate the server is performing file write operations for the clients on this CPU. This value is a measure of how busy the Server is. This value will always be 0 in the Blocking Queue instance.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Write Bytes/sec

Write Bytes/sec is the rate the server is writing data to files for the clients on this CPU. This value is a measure of how busy the Server is.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Total Bytes/sec

Total Bytes/sec is the rate the Server is reading and writing data to and from the files for the clients on this CPU. This value is a measure of how busy the Server is.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Total Operations/sec

Total Operations/sec is the rate the Server is performing file read and file write operations for the clients on this CPU. This value is a measure of how busy the Server is. This value will always be 0 in the Blocking Queue instance.

Detail Level: Advanced
Counter Type: PERF_COUNTER_BULK_COUNT

Context Blocks Queued/sec

Context Blocks Queued per second is the rate at which work context blocks had to be placed on the server's FSP queue to await server action.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER


System Object

The System performance object consists of those counters that apply to more than one component on the computer

File Read Operations/sec

File Read Operations/sec is the combined rate of file system read requests to all devices on the computer, including requests to read from the file system cache. It is measured in numbers of reads.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

File Write Operations/sec

File Write Operations/sec is the combined rate of the file system write requests to all devices on the computer, including requests to write to data in the file system cache. It is measured in numbers of writes.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

File Control Operations/sec

File Control Operations/sec is the combined rate of file system operations that are neither reads nor writes, such as file system control requests and requests for information about device characteristics or status. This is the inverse of System: File Data Operations/sec and is measured in numbers of operations.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

File Read Bytes/sec

File Read Bytes/sec is the overall rate at which bytes are read to satisfy  file system read requests to all devices on the computer, including reads from the file system cache. It is measured in numbers of bytes.

Detail Level: Expert
Counter Type: PERF_COUNTER_BULK_COUNT

File Write Bytes/sec

File Write Bytes/sec is the overall rate at which bytes are written to satisfy file system write requests to all devices on the computer, including writes to the file system cache. It is measured in numbers of bytes.

Detail Level: Expert
Counter Type: PERF_COUNTER_BULK_COUNT

File Control Bytes/sec

File Control Bytes/sec is the overall rate at which  bytes are transferred for all file system operations that are neither reads nor writes, including file system control requests and requests for information about device characteristics or status. It is measured in numbers of bytes.

Detail Level: Wizard
Counter Type: PERF_COUNTER_BULK_COUNT

Context Switches/sec

Context Switches/sec is the combined rate at which all processors on the computer are switched from one thread to another. Context switches occur when a running thread voluntarily relinquishes the processor, is preempted by a higher priority ready thread, or switches between user-mode and privileged (kernel) mode to use an Executive or subsystem service. It is the sum of Thread: Context Switches/sec for all threads running on all processors in the computer and is measured in numbers of switches. There are context switch counters on the System and Thread objects.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

System Calls/sec

Systems Calls/sec is the combined rate of calls to Windows NT system service routines by all processes running on the computer. These routines perform all of the basic scheduling and synchronization of activities on the computer, and provide access to non-graphic devices, memory management, and name space management.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Total Processor Time

% Total Processor Time is the average percentage of time that all processors on the computer are executing non-idle threads. This counter was designed as the primary indicator of processor activity on multiprocessor computers. It is equal to the sum of Process: % Processor Time for all processors, divided by the number of processors. It is calculated by summing the time that all processors spend executing the thread of the Idle process in each sample interval, subtracting that value from 100%, and dividing the difference by the number of processors on the computer. (Each processor has an Idle thread which consumes cycles when no other threads are ready to run.) For example, on a multiprocessor computer, a value of 50% means that all processors are busy for half of the sample interval, or that half of the processors are busy for all of the sample interval.

Detail Level: Novice
Counter Type: PERF_100NSEC_TIMER_INV

Total User Time

% Total User Time is the average percentage of non-idle time all processors spent in User mode. It is the sum of Processor: % User Time for all processors on the computer, divided by the number of processors. System: % Total User Time and System: % Total Privileged Time sum to % Total Processor Time, but not always to 100%. (User mode is a restricted processing mode designed for applications, environment subsystems, and integral subsystems. The alternative, privileged mode, is designed for operating system components and allows direct access to hardware and all memory. The operating system switches application threads to privileged mode to obtain operating system services.)

Detail Level: Advanced
Counter Type: PERF_100NSEC_TIMER

Total Privileged Time

% Total Privileged Time is the average percentage of non-idle time all processors spent in privileged (kernel) mode. It is the sum of Processor: % Privileged Time for all processors on the computer, divided by the number of processors. System: % Total User Time and System: % Total Privileged Time sum to % Total Processor Time, but not always to 100%. (Privileged mode is an processing mode designed for operating system components which allows direct access to hardware and all memory. The operating system switches application threads to privileged mode to obtain operating system services. The alternative, user mode, is a restricted processing mode designed for applications and environment subsystems.)

Detail Level: Advanced
Counter Type: PERF_100NSEC_TIMER

Total Interrupts/sec

Total Interrupts/sec is the combined rate of hardware interrupts received and serviced by all processors on the computer It is the sum of Processor: Interrupts/sec for all processors, and divided by the number of processors, and is measured in numbers of interrupts. It does not include DPCs, which are counted separately. This value is an indirect indicator of the activity of devices that generate interrupts, such as the system timer, the mouse, disk drivers, data communication lines, network interface cards and other peripheral devices. These devices normally interrupt the processor when they have completed a task or require attention. Normal thread execution is suspended during interrupts. Most system clocks interrupt the processor every 10 milliseconds, creating a background of interrupt activity.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

File Data Operations/sec

File Data Operations/sec is the combined rate of read and write operations on all logical disks on the computer. This is the inverse of System: File Control Operations/sec.

Detail Level: Novice
Counter Type: PERF_COUNTER_COUNTER

System Up Time

Total Time (in seconds) that the computer has been operational since it was last started.

Detail Level: Novice
Counter Type: PERF_ELAPSED_TIME

Processor Queue Length

Processor Queue Length is the number of threads in the processor queue. There is a single queue for processor time even on computers with multiple processors. Unlike the disk counters, this counter counts ready threads only, not threads that are running. A sustained processor queue of greater than two threads generally indicates processor congestion.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Alignment Fixups/sec

Alignment Fixups/sec is the rate of alignment faults fixed by the system.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Exception Dispatches/sec

Exception Dispatches/sec is the rate of exceptions dispatched by the system.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

Floating Emulations/sec

Floating Emulations/sec is the rate of floating emulations performed by the system.

Detail Level: Wizard
Counter Type: PERF_COUNTER_COUNTER

% Total DPC Time

% Total DPC Time is the average percentage of time that all processors spent receiving and servicing deferred procedure calls (DPC). (DPCs are interrupts that run at a lower priority than the standard interrupts.) it is the sum of Processor: %DPC Time for all processors on the computer, divided by the number of processors. System: %Total DPC Time is a component of System: %Total Privileged Time because DPCs are executed in privileged mode. DPCs are counter separately and are not a component of the interrupt count.

Detail Level: Advanced
Counter Type: PERF_100NSEC_TIMER

% Total Interrupt Time

% Total Interrupt Time is the average percentage of time that all processors spent servicing interrupts.  It is the sum of Processor: % Interrupt Time for of all processors on the computer, divided by the number of processors. DPCs are counted separately and are not a component of the interrupt count. This value is an indirect indicator of the activity of devices that generate interrupts, such as the system timer, the mouse, disk drivers, data communication lines, network interface cards and other peripheral devices.

Detail Level: Advanced
Counter Type: PERF_100NSEC_TIMER

Total DPCs Queued/sec

Total DPCs Queued/sec is the combined rate at which deferred procedure calls (DPC) are added to the DPC queue of all processors on the computer. (DPCs are interrupts that run at a lower priority than standard interrupts.) Each processor has its own DPC queue. This counter measures the rates at which DPCs are added to the queue, not the number of DPCs in the queue. It is the sum of Processor: DPCs Queued/sec for all processors on the computer, divided by the number of processors.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Total DPC Rate

Total DPC Rate is the combined rate at which deferred procedure calls (DPCs) are added to the DPC queues of all processors between timer tics of each processor’s system clock. (DPCs are interrupts that run at a lower priority than standard interrupts.) Each processor has its own DPC queue. clock on the processor. This counter measures the rate at which DPCs are added to the queue, not the number of DPCs in the queue. It is the sum of Processor: DPC Rate for all processors on the computer, divided by the number of processors.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Total DPC Bypasses/sec

Total DPC Bypasses/sec is the combined rate at which deferred procedure calls (DPCs)  on all processors were avoided. (DPCs are interrupts that run at a lower priority than standard interrupts.) . This value is the sum of Processor: DPC Bypasses/sec for all processors, divided by the number of processors.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Total APC Bypasses/sec

Total APC Bypasses/sec is the combined rate at which kernel asynchronous procedure call (APC) interrupts on all processors were avoided. This value is the sum of Processor: APC Bypasses/sec for all processors, divided by the number of processors.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

%Registry Quota In Use

% Registry Quota In Use is the percentage of the Total Registry Quota Allowed that is currently being used by the system.

Detail Level: Advanced
Counter Type: PERF_RAW_FRACTION

Registry Quota In Use

% Registry Quota In Use indicates the percentage of the Total Registry Quota Allowed currently in use by the system.

Detail Level: Advanced
Counter Type: PERF_RAW_BASE


TCP Object

The TCP performance object consists of counters that measure the rates at which TCP Segments are sent and received by using the TCP protocol. It includes counters that monitor the number of TCP connections in each TCP connection state.

Segments/sec

Segments/sec is the rate at which TCP segments are sent or received using the TCP protocol.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Connections Established

Connections Established is the number of TCP connections for which the current state is either ESTABLISHED or CLOSE-WAIT.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connections Active

Connections Active is the number of times TCP connections have made a direct transition to the SYN-SENT state from the CLOSED state.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connections Passive

Connections Passive is the number of times TCP connections have made a direct transition to the SYN-RCVD state from the LISTEN state.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connection Failures

Connection Failures is the number of times TCP connections have made a direct transition to the CLOSED state from the SYN-SENT state or the SYN-RCVD state, plus the number of times TCP connections have made a direct transition to the LISTEN state from the SYN-RCVD state.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Connections Reset

Connections Reset is the number of times TCP connections have made a direct transition to the CLOSED state from either the ESTABLISHED state or the CLOSE-WAIT state.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Segments Received/sec

Segments Received/sec is the rate at which segments are received, including those received in error. This count includes segments received on currently established connections.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Segments Sent/sec

Segments Sent/sec is the rate at which segments are sent, including those on current connections, but excluding those containing only retransmitted bytes.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Segments Retransmitted/sec

Segments Retransmitted/sec is the rate at which segments are retransmitted, that is, segments transmitted containing one or more previously transmitted bytes.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER


Thread Object

The Thread performance object consists of counters that measure aspects of thread behavior. A thread is the basic object that executes instructions on a processor. All running processes have at least one thread.

Processor Time

Processor Time is the percentage of elapsed time that this thread used the processor to execute instructions. An instruction is the basic unit of execution in a processor, and a thread is the object that executes instructions. Code executed to handle some hardware interrupts and trap conditions are included in this count.

Detail Level: Novice
Counter Type: PERF_100NSEC_TIMER

% User Time

User Time is the percentage of elapsed time that this thread has spent executing code in user mode. Applications, environment subsystems, and integral subsystems execute in user mode. Code executing in user mode cannot damage the integrity of the Windows NT Executive, Kernel, and device drivers. Unlike some early operating systems, Windows NT uses process boundaries for subsystem protection in addition to the traditional protection of user and privileged modes. These subsystem processes provide additional protection. Therefore, some work done by Windows NT on behalf of your application might appear in other subsystem processes in addition to the privileged time in your process.

Detail Level: Advanced
Counter Type: PERF_100NSEC_TIMER

% Privileged Time

Privileged Time is the percentage of elapsed time that this thread has spent executing code in privileged mode. When a Windows NT system service is called, the service will often run in privileged mode in order to gain access to system-private data. Such data is protected from access by threads executing in user mode. Calls to the system can be explicit or implicit, such as page faults or interrupts. Unlike some early operating systems, Windows NT uses process boundaries for subsystem protection in addition to the traditional protection of user and privileged modes. These subsystem processes provide additional protection. Therefore, some work done by Windows NT on behalf of your application might appear in other subsystem processes in addition to the privileged time in your process.

Detail Level: Advanced
Counter Type: PERF_100NSEC_TIMER

Context Switches/sec

Context Switches/sec is the rate of switches from one thread to another. Thread switches can occur either inside of a single process or across processes. A thread switch can be caused either by one thread asking another for information, or by a thread being preempted by another, higher priority thread becoming ready to run. Unlike some early operating systems, Windows NT uses process boundaries for subsystem protection in addition to the traditional protection of user and privileged modes. These subsystem processes provide additional protection. Therefore, some work done by Windows NT on behalf of an application might appear in other subsystem processes in addition to the privileged time in the application. Switching to the subsystem process causes one context switch in the application thread. Switching back causes another context switch in the subsystem thread.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Elapsed Time

The total elapsed time (in seconds) this thread has been running.

Detail Level: Advanced
Counter Type: PERF_ELAPSED_TIME

Priority Current

The current dynamic priority of this thread. The system can raise the thread's dynamic priority above the base priority if the thread is handling user input, or lower it towards the base priority if the thread becomes compute bound.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Priority Base

The current base priority of this thread. The system can raise the thread's dynamic priority above the base priority if the thread is handling user input, or lower it towards the base priority if the thread becomes compute bound.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Start Address

Starting virtual address for this thread.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Thread State

Thread State is the current state of the thread. It is 0 for Initialized, 1 for Ready, 2 for Running, 3 for Standby, 4 for Terminated, 5 for Wait, 6 for Transition, 7 for Unknown. A Running thread is using a processor; a Standby thread is about to use one. A Ready thread wants to use a processor, but is waiting for a processor because none are free. A thread in Transition is waiting for a resource in order to execute, such as waiting for its execution stack to be paged in from disk. A Waiting thread has no use for the processor because it is waiting for a peripheral operation to complete or a resource to become free.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

Thread Wait Reason

Thread Wait Reason is only applicable when the thread is in the Wait state (see Thread State.) It is 0 or 7 when the thread is waiting for the Executive, 1 or 8 for a Free Page, 2 or 9 for a Page In, 3 or 10 for a Pool Allocation, 4 or 11 for an Execution Delay, 5 or 12 for a Suspended condition, 6 or 13 for a User Request, 14 for an Event Pair High, 15 for an Event Pair Low, 16 for an LPC Receive, 17 for an LPC Reply, 18 for Virtual Memory, 19 for a Page Out; 20 and higher are not assigned at the time of this writing. Event Pairs are used to communicate with protected subsystems (see Context Switches.)

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

ID Process

ID Process is the unique identifier of this process. ID Process numbers are reused, so they only identify a process for the lifetime of that process.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT

ID Thread

ID Thread is the unique identifier of this thread. ID Thread numbers are reused, so they only identify a thread for the lifetime of that thread.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT


Thread Details Object

Thread Details performance object consists of counters that measure aspects of thread behavior that are difficult or time-consuming to collect. These counters are distinguished from those in the Thread performance object by their high overhead.

User PC

Current User Program Counter for this thread.

Detail Level: Wizard
Counter Type: PERF_COUNTER_RAWCOUNT


UDP Object

The UDP performance object consists of counters that measure the rates at which UDP datagrams are sent and received by using the UDP protocol. It includes counters that monitor UDP protocol errors.

Datagrams/sec

Datagrams/sec is the rate at which UDP datagrams are sent or received by the entity.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagrams Received/sec

Datagrams Received/sec is the rate at which UDP datagrams are delivered to UDP users.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagrams No Port/sec

Datagrams No Port/sec is the rate of received UDP datagrams for which there was no application at the destination port.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER

Datagrams Received Errors

Datagrams Received Errors is the number of received UDP datagrams that could not be delivered for reasons other than the lack of an application at the destination port.

Detail Level: Advanced
Counter Type: PERF_COUNTER_RAWCOUNT

Datagrams Sent/sec

Datagrams Sent/sec is the rate at which UDP datagrams are sent from the entity.

Detail Level: Advanced
Counter Type: PERF_COUNTER_COUNTER


Locale Identifiers

This appendix contains detailed information about national language support in Microsoft® Windows®. The information presented here pertains to locale identifiers, LCTYPE constants, country codes, and language identifiers.

A locale identifier (LCID) is a DWORD value containing the language identifier in the lower word and a reserved value in the upper word. The identifier supplied in an LCID is a standard international numeric abbreviation. This LCID has the components necessary to uniquely identify one of the installed system-defined locales.

Applications can use the MAKELCID macro to create LCID values.

There are two predefined LCID values: LOCALE_SYSTEM_DEFAULT is the system default locale, and LOCALE_USER_DEFAULT is the current user’s locale.


LCTYPE Constants

An LCTYPE constant is a constant that specifies a particular piece of locale information.

The values in the following list correspond to the names of these values in the configuration registry, under both the user’s preferences (as values in the registry key HKEY_CURRENT_USER\Control Panel\International) and the system’s installed languages (as files pointed to by registry keys, one key per language installed, under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\NLS). All values are null-terminated Unicode™ strings. If no maximum length is indicated, the strings may vary in length.

Constant	Description
LOCALE_ILANGUAGE	Language identifier indicating the language. The maximum number of characters allowed for this string is 5.
LOCALE_SLANGUAGE	Full localized name of the language.
LOCALE_SENGLANGUAGE	Full English name of the language from the International Organization for Standardization (ISO) Standard 639. This is always restricted to characters mappable into the ASCII 127-character subset.
LOCALE_SABBREVLANGNAME	Abbreviated name of the language, created by taking the 2-letter language abbreviation from the ISO Standard 639 and adding a third letter, as appropriate, to indicate the sublanguage.
LOCALE_SNATIVELANGNAME	Native name of the language.
LOCALE_ICOUNTRY	Country code, based on international phone codes, also referred to as IBM country codes. The maximum number of characters allowed for this string is 6.
LOCALE_SCOUNTRY	Full localized name of the country.
LOCALE_SENGCOUNTRY	Full English name of the country. This is always restricted to characters mappable into the ASCII 127-character subset.
LOCALE_SABBREVCTRYNAME	Abbreviated name of the country from the ISO Standard 3166.
LOCALE_SNATIVECTRYNAME	Native name of the country.
LOCALE_IDEFAULTLANGUAGE	Language identifier for the principal language spoken in this locale. This is provided so that partially specified locales can be completed with default values. The maximum number of characters allowed for this string is 5.
LOCALE_IDEFAULTCOUNTRY	Country code for the principal country in this locale. This is provided so that partially specified locales can be completed with default values. The maximum number of characters allowed for this string is 6.
LOCALE_IDEFAULTCODEPAGE	Original equipment manufacturer (OEM) code page associated with the country. The maximum number of characters allowed for this string is 6.
LOCALE_SLIST	Character(s) used to separate list items. For example, a comma is used in many locales.
LOCALE_IMEASURE	System of measurement. This value is 0 if the metric system (Systéme International d’Unités, or S.I.) is used and 1 if the U.S. system is used. The maximum number of characters allowed for this string is 2.
LOCALE_SDECIMAL	Character(s) used as the decimal separator.
LOCALE_STHOUSAND	Character(s) used to separate groups of digits to the left of the decimal.
LOCALE_SGROUPING	Sizes for each group of digits to the left of the decimal. An explicit size is needed for each group; sizes are separated by semicolons. If the last value is zero, the preceding value is repeated. To group thousands, specify 3;0, for example.
LOCALE_IDIGITS	Number of fractional digits. The maximum number of characters allowed for this string is 3.
LOCALE_ILZERO	Specifier for leading zeros in decimal fields. The maximum number of characters allowed for this string is 2. The specifier can be one of the following values:
Value	Meaning
0	No leading zeros
1	Leading zeros
LOCALE_SNATIVEDIGITS	Native equivalents to ASCII 0 through 9.
LOCALE_SCURRENCY	String used as the local monetary symbol.
LOCALE_SINTLSYMBOL	Three characters of the international monetary symbol specified in ISO 4217, “Codes for the Representation of Currencies and Funds,” followed by the character separating this string from the amount.
LOCALE_SMONDECIMALSEP	Character(s) used as the monetary decimal separator.
LOCALE_SMONTHOUSANDSEP	Character(s) used as the monetary separator between groups of digits to the left of the decimal.
LOCALE_SMONGROUPING	Sizes for each group of monetary digits to the left of the decimal. An explicit size is needed for each group; sizes are separated by semicolons. If the last value is zero, the preceding value is repeated. To group thousands, specify 3;0, for example.
LOCALE_ICURRDIGITS	Number of fractional digits for the local monetary format. The maximum number of characters allowed for this string is 3.
LOCALE_IINTLCURRDIGITS	Number of fractional digits for the international monetary format. The maximum number of characters allowed for this string is 3.
LOCALE_ICURRENCY	Positive currency mode. The maximum number of characters allowed for this string is 2. The mode can be one of the following values:
Value	Meaning
0	Prefix, no separation
1	Suffix, no separation
2	Prefix, 1-char. separation
3	Suffix, 1-char. separation
LOCALE_INEGCURR	Negative currency mode. The maximum number of characters allowed for this string is 3. The mode can be one of the following values:
Value	Example
0	($1.1)
1	−$1.1
2	$−1.1
3	$1.1−
4	(1.1$)
5	−1.1$
6	1.1−$
7	1.1$−
8	−1.1 $ (space before $)
9	−$ 1.1 (space after $)
10	1.1 $− (space before $)
11	$ 1.1− (space after $)
12	$ −1.1 (space after $)
13	1.1− $ (space before $)
14	($ 1.1) (space after $)
15	(1.1 $) (space before $)
LOCALE_SDATE	Character(s) for the date separator.
LOCALE_STIME	Character(s) for the time separator.
LOCALE_STIMEFORMAT	Time formatting strings for this locale.
LOCALE_SSHORTDATE	Short date formatting string for this locale.
LOCALE_SLONGDATE	Long date formatting string for this locale.
LOCALE_IDATE	Short date format-ordering specifier. The maximum number of characters allowed for this string is 2. The specifier can be one of the following values:
Value	Meaning
0	Month-Day-Year
1	Day-Month-Year
2	Year-Month-Day
LOCALE_ILDATE	Long date format-ordering specifier. The maximum number of characters allowed for this string is 2. The specifier can be one of the following values:
Value	Meaning
0	Month-Day-Year
1	Day-Month-Year
2	Year-Month-Day
LOCALE_ITIME	Time format specifier. The maximum number of characters allowed for this string is 2. The specifier can be one of the following values:
Value	Meaning
0	AM / PM 12-hour format
1	24-hour format
LOCALE_ICENTURY	Specifier for full 4-digit century. The maximum number of characters allowed for this string is 2. The specifier can be one of the following values:
Value	Meaning
0	Abbreviated 2-digit century
1	Full 4-digit century
LOCALE_ITLZERO	Specifier for leading zeros in time fields. The maximum number of characters allowed for this string is 2. The specifier can be one of the following values:
Value	Meaning
0	No leading zeros for hours
1	Leading zeros for hours
LOCALE_IDAYLZERO	Specifier for leading zeros in day fields. The maximum number of characters allowed for this string is 2. The specifier can be one of the following values:
Value	Meaning
0	No leading zeros for days
1	Leading zeros for days
LOCALE_IMONLZERO	Specifier for leading zeros in month fields. The maximum number of characters allowed for this string is 2. The specifier can be one of the following values:
Value	Meaning
0	No leading zeros for months
1	Leading zeros for months
LOCALE_S1159	String for the AM designator.
LOCALE_S2359	String for the PM designator.
LOCALE_SDAYNAME1	Native long name for Monday.
LOCALE_SDAYNAME2	Native long name for Tuesday.
LOCALE_SDAYNAME3	Native long name for Wednesday.
LOCALE_SDAYNAME4	Native long name for Thursday.
LOCALE_SDAYNAME5	Native long name for Friday.
LOCALE_SDAYNAME6	Native long name for Saturday.
LOCALE_SDAYNAME7	Native long name for Sunday.
LOCALE_SABBREVDAYNAME1	Native abbreviated name for Monday.
LOCALE_SABBREVDAYNAME2	Native abbreviated name for Tuesday.
LOCALE_SABBREVDAYNAME3	Native abbreviated name for Wednesday.
LOCALE_SABBREVDAYNAME4	Native abbreviated name for Thursday.
LOCALE_SABBREVDAYNAME5	Native abbreviated name for Friday.
LOCALE_SABBREVDAYNAME6	Native abbreviated name for Saturday.
LOCALE_SABBREVDAYNAME7	Native abbreviated name for Sunday.
LOCALE_SMONTHNAME1	Native long name for January.
LOCALE_SMONTHNAME2	Native long name for February.
LOCALE_SMONTHNAME3	Native long name for March.
LOCALE_SMONTHNAME4	Native long name for April.
LOCALE_SMONTHNAME5	Native long name for May.
LOCALE_SMONTHNAME6	Native long name for June.
LOCALE_SMONTHNAME7	Native long name for July.
LOCALE_SMONTHNAME8	Native long name for August.
LOCALE_SMONTHNAME9	Native long name for September.
LOCALE_SMONTHNAME10	Native long name for October.
LOCALE_SMONTHNAME11	Native long name for November.
LOCALE_SMONTHNAME12	Native long name for December.
LOCALE_SABBREVMONTHNAME1	Native abbreviated name for January.
LOCALE_SABBREVMONTHNAME2	Native abbreviated name for February.
LOCALE_SABBREVMONTHNAME3	Native abbreviated name for March.
LOCALE_SABBREVMONTHNAME4	Native abbreviated name for April.
LOCALE_SABBREVMONTHNAME5	Native abbreviated name for May.
LOCALE_SABBREVMONTHNAME6	Native abbreviated name for June.
LOCALE_SABBREVMONTHNAME7	Native abbreviated name for July.
LOCALE_SABBREVMONTHNAME8	Native abbreviated name for August.
LOCALE_SABBREVMONTHNAME9	Native abbreviated name for September.
LOCALE_SABBREVMONTHNAME10	Native abbreviated name for October.
LOCALE_SABBREVMONTHNAME11	Native abbreviated name for November.
LOCALE_SABBREVMONTHNAME12	Native abbreviated name for December.
LOCALE_SPOSITIVESIGN	String value for the positive sign.
LOCALE_SNEGATIVESIGN	String value for the negative sign.
LOCALE_IPOSSIGNPOSN	Formatting index for positive values. The maximum number of characters allowed for this string is 2. The index can be one of the following values:
Value	Meaning
0	Parentheses surround the amount and the monetary symbol.
1	The sign string precedes the amount and the monetary symbol.
2	The sign string succeeds the amount and the monetary symbol.
3	The sign string immediately precedes the monetary symbol.
4	The sign string immediately succeeds the monetary symbol.
LOCALE_INEGSIGNPOSN	Formatting index for negative values. This index uses the same values as LOCALE_IPOSSIGNPOSN. The maximum number of characters allowed for this string is 2.
LOCALE_IPOSSYMPRECEDES	Position of monetary symbol in a positive monetary value. This value is 1 if the monetary symbol precedes the positive amount, 0 if it follows it. The maximum number of characters allowed for this string is 2.
LOCALE_IPOSSEPBYSPACE	Separation of monetary symbol in a positive monetary value. This value is 1 if the monetary symbol is separated by a space from a positive amount, 0 if it is not. The maximum number of characters allowed for this string is 2.
LOCALE_INEGSYMPRECEDES	Position of monetary symbol in a negative monetary value. This value is 1 if the monetary symbol precedes the negative amount, 0 if it follows it. The maximum number of characters allowed for this string is 2.
LOCALE_INEGSEPBYSPACE	Separation of monetary symbol in a negative monetary value. This value is 1 if the monetary symbol is separated by a space from the negative amount, 0 if it is not. The maximum number of characters allowed for this string is 2.
LOCALE_NOUSEROVERRIDE	This constant may be OR’ed with any other LCTYPE constant in a call to the GetLocaleInfo function. This always causes the function to bypass any user overrides, and return the system default value for the other LCTYPE specified in the function call, based on the given LCID.


Language Identifiers and Locales

Applications can use the MAKELANGID macro to create a language identifier.

The first release of Windows NT supports 35 sublanguages/locales.

The following 28 sublanguages/locales use the Latin 1 script:

Latin 1 Script

Identifier	Language	Sublanguage/Locale	Language Code
0x0406	Danish	Danish	DAN
0x0413	Dutch	Dutch (Standard)	NLD
0x0813	Dutch	Belgian (Flemish)	NLB
0x0409	English	American	ENU
0x0809	English	British	ENG
0x0c09	English	Australian	ENA
0x1009	English	Canadian	ENC
0x1409	English	New Zealand	ENZ
0x1809	English	Ireland	ENI
0x040b	Finnish	Finnish	FIN
0x040c	French	French (Standard)	FRA
0x080c	French	Belgian	FRB
0x0c0c	French	Canadian	FRC
0x100c	French	Swiss	FRS
0x0407	German	German (Standard)	DEU
0x0807	German	Swiss	DES
0x0c07	German	Austrian	DEA
0x040f	Icelandic	Icelandic	ISL
0x0410	Italian	Italian (Standard)	ITA
0x0810	Italian	Swiss	ITS
0x0414	Norwegian	Norwegian (Bokmal)	NOR
0x0814	Norwegian	Norwegian (Nynorsk)	NON
0x0416	Portuguese	Portuguese (Brazilian)	PTB
0x0816	Portuguese	Portuguese (Standard)	PTG
0x041D	Swedish	Swedish	SVE
0x040a	Spanish	Spanish (Standard/Traditional)	ESP
0x080a	Spanish	Mexican	ESM
0x0c0a	Spanish	Spanish (Modern)	ESN
The following 5 sublanguages/locales use the Latin 2 script:

Latin 2 Script

Identifier	Sublanguage/Locale	Language Code
0x041f	Turkish	TRK
0x0415	Polish	PLK
0x0405	Czech	CSY
0x041b	Slovak	SKY
0x040e	Hungarian	HUN
The following sublanguage/locale uses the Cyrillic script:

Cyrillic Script

Identifier	Sublanguage/Locale	Language Code
0x0419	Russian	RUS
The following sublanguage/locale uses an other script:

Other Script

Identifier	Sublanguage/Locale	Language Code
0x0408	Greek	ELL
The following special identifiers are also defined:

Special Identifiers

Identifier	Sublanguage/Locale
0x0000	Language-Neutral
0x0400	Process Default Language


Raster Operation Codes

Raster-operation codes define how the graphics device interface (GDI) combines the bits from the selected pen with the bits in the destination bitmap. This appendix lists and describes the binary and ternary raster operations used by GDI.


About Raster Operation Codes

This appendix lists and describes the binary and ternary raster operations used by graphics device interface (GDI). A binary raster operation involves two operands: a pen and a destination bitmap. A ternary raster operation involves three operands: a source bitmap, a brush, and a destination bitmap. Both binary and ternary raster operations use Boolean operators.


Binary Raster Operations

This section lists the binary raster-operation codes used by the GetROP2 and SetROP2 functions. Raster-operation codes define how GDI combines the bits from the selected pen with the bits in the destination bitmap.

Each raster-operation code represents a Boolean operation in which the values of the pixels in the selected pen and the destination bitmap are combined. Following are the two operands used in these operations:

Operand	Meaning
P	Selected pen
D	Destination bitmap
The Boolean operators used in these operations follow:

Operator	Meaning
a	Bitwise AND
n	Bitwise NOT (inverse)
o	Bitwise OR
x	Bitwise exclusive OR (XOR)
All Boolean operations are presented in reverse Polish notation. For example, the following operation replaces the values of the pixels in the destination bitmap with a combination of the pixel values of the pen and the selected brush:

DPo

Each raster-operation code is a 32-bit integer whose high-order word is a Boolean operation index and whose low-order word is the operation code. The 16-bit operation index is a zero-extended 8-bit value that represents all possible outcomes resulting from the Boolean operation on two parameters (in this case, the pen and destination values). For example, the operation indexes for the DPo and DPan operations are shown in the following list:

P	D	DPo	DPan
0	0	0	1
0	1	1	1
1	0	1	1
1	1	1	0
The following list outlines the drawing modes and the Boolean operations that they represent:

Raster operation	Boolean operation
R2_BLACK	0
R2_COPYPEN	P
R2_MASKNOTPEN	DPna
R2_MASKPEN	DPa
R2_MASKPENNOT	PDna
R2_MERGENOTPEN	DPno
R2_MERGEPEN	DPo
R2_MERGEPENNOT	PDno
R2_NOP	D
R2_NOT	Dn
R2_NOTCOPYPEN	Pn
R2_NOTMASKPEN	DPan
R2_NOTMERGEPEN	DPon
R2_NOTXORPEN	DPxn
R2_WHITE	1
R2_XORPEN	DPx
For a monochrome device, GDI maps the value zero to black and the value 1 to white. If an application attempts to draw with a black pen on a white destination by using the available binary raster operations, the following results occur:

Raster operation	Result
R2_BLACK	Visible black line
R2_COPYPEN	Visible black line
R2_MASKNOTPEN	No visible line
R2_MASKPEN	Visible black line
R2_MASKPENNOT	Visible black line
R2_MERGENOTPEN	No visible line
R2_MERGEPEN	Visible black line
R2_MERGEPENNOT	Visible black line
R2_NOP	No visible line
R2_NOT	Visible black line
R2_NOTCOPYPEN	No visible line
R2_NOTMASKPEN	No visible line
R2_NOTMERGEPEN	Visible black line
R2_NOTXORPEN	Visible black line
R2_WHITE	No visible line
R2_XORPEN	No visible line
For a color device, GDI uses RGB values to represent the colors of the pen and the destination. An RGB color value is a long integer that contains a red, a green, and a blue color field, each specifying the intensity of the given color. Intensities range from 0 through 255. The values are packed in the three low-order bytes of the long integer. The color of a pen is always a solid color, but the color of the destination may be a mixture of any two or three colors. If an application attempts to draw with a white pen on a blue destination by using the available binary raster operations, the following results occur:

Raster operation	Result
R2_BLACK	Visible black line
R2_COPYPEN	Visible white line
R2_MASKNOTPEN	Visible black line
R2_MASKPEN	Invisible blue line
R2_MASKPENNOT	Visible red/green line
R2_MERGENOTPEN	Invisible blue line
R2_MERGEPEN	Visible white line
R2_MERGEPENNOT	Visible white line
R2_NOP	Invisible blue line
R2_NOT	Visible red/green line
R2_NOTCOPYPEN	Visible black line
R2_NOTMASKPEN	Visible red/green line
R2_NOTMERGEPEN	Visible black line
R2_NOTXORPEN	Invisible blue line
R2_WHITE	Visible white line
R2_XORPEN	Visible red/green line


Ternary Raster Operations

This section lists the ternary raster-operation codes used by the BitBlt, PatBlt, and StretchBlt functions. Ternary raster-operation codes define how GDI combines the bits in a source bitmap with the bits in the destination bitmap.

Each raster-operation code represents a Boolean operation in which the values of the pixels in the source, the selected brush, and the destination are combined. Following are the three operands used in these operations:

Operand	Meaning
D	Destination bitmap
P	Selected brush (also called pattern)
S	Source bitmap
Boolean operators used in these operations follow:

Operator	Meaning
a	Bitwise AND
n	Bitwise NOT (inverse)
o	Bitwise OR
x	Bitwise exclusive OR (XOR)
All Boolean operations are presented in reverse Polish notation. For example, the following operation replaces the values of the pixels in the destination bitmap with a combination of the pixel values of the source and brush:

PSo

The following operation combines the values of the pixels in the source and brush with the pixel values of the destination bitmap (there are alternative spellings of the same function, so although a particular spelling may not be in the list, an equivalent form would be):

DPSoo

Each raster-operation code is a 32-bit integer whose high-order word is a Boolean operation index and whose low-order word is the operation code. The 16-bit operation index is a zero-extended, 8-bit value that represents the result of the Boolean operation on predefined brush, source, and destination values. For example, the operation indexes for the PSo and DPSoo operations are shown in the following list:

P	S	D	PSo	DPSoo
0	0	0	0	0
0	0	1	0	1
0	1	0	1	1
0	1	1	1	1
1	0	0	1	1
1	0	1	1	1
1	1	0	1	1
1	1	1	1	1
Operation index:			00FCh	00FEh
In this case, PSo has the operation index 00FC (read from the bottom up); DPSoo has the operation index 00FE. These values define the location of the corresponding raster-operation codes, as shown in Table A.1, “Raster-Operation Codes.” The PSo operation is in line 252 (00FCh) of the table; DPSoo is in line 254 (00FEh).

The most commonly used raster operations have been given special names in the Windows include file, WINDOWS.H. You should use these names whenever possible in your applications.

When the source and destination bitmaps are monochrome, a bit value of zero represents a black pixel and a bit value of 1 represents a white pixel. When the source and the destination bitmaps are color, those colors are represented with RGB values. For more information about RGB values, see RGB

Raster-Operation Codes

Boolean function (hexadecimal)	Raster operation (hexadecimal)	Boolean function in reverse Polish	Common name
00	00000042	0	BLACKNESS
01	00010289	DPSoon	−
02	00020C89	DPSona	−
03	000300AA	PSon	−
04	00040C88	SDPona	−
05	000500A9	DPon	−
06	00060865	PDSxnon	−
07	000702C5	PDSaon	−
08	00080F08	SDPnaa	−
09	00090245	PDSxon	−
0A	000A0329	DPna	−
0B	000B0B2A	PSDnaon	−
0C	000C0324	SPna	−
0D	000D0B25	PDSnaon	−
0E	000E08A5	PDSonon	−
0F	000F0001	Pn	−
10	00100C85	PDSona	−
11	001100A6	DSon	NOTSRCERASE
12	00120868	SDPxnon	−
13	001302C8	SDPaon	−
14	00140869	DPSxnon	−
15	001502C9	DPSaon	−
16	00165CCA	PSDPSanaxx	−
17	00171D54	SSPxDSxaxn	−
18	00180D59	SPxPDxa	−
19	00191CC8	SDPSanaxn	−
1A	001A06C5	PDSPaox	−
1B	001B0768	SDPSxaxn	−
1C	001C06CA	PSDPaox	−
1D	001D0766	DSPDxaxn	−
1E	001E01A5	PDSox	−
1F	001F0385	PDSoan	−
20	00200F09	DPSnaa	−
21	00210248	SDPxon	−
22	00220326	DSna	−
23	00230B24	SPDnaon	−
24	00240D55	SPxDSxa	−
25	00251CC5	PDSPanaxn	−
26	002606C8	SDPSaox	−
27	00271868	SDPSxnox	−
28	00280369	DPSxa	−
29	002916CA	PSDPSaoxxn	−
2A	002A0CC9	DPSana	−
2B	002B1D58	SSPxPDxaxn	−
2C	002C0784	SPDSoax	−
2D	002D060A	PSDnox	−
2E	002E064A	PSDPxox	−
2F	002F0E2A	PSDnoan	−
30	0030032A	PSna	−
31	00310B28	SDPnaon	−
32	00320688	SDPSoox	−
33	00330008	Sn	NOTSRCCOPY
34	003406C4	SPDSaox	−
35	00351864	SPDSxnox	−
36	003601A8	SDPox	−
37	00370388	SDPoan	−
38	0038078A	PSDPoax	−
39	00390604	SPDnox	−
3A	003A0644	SPDSxox	−
3B	003B0E24	SPDnoan	−
3C	003C004A	PSx	−
3D	003D18A4	SPDSonox	−
3E	003E1B24	SPDSnaox	−
3F	003F00EA	PSan	−
40	00400F0A	PSDnaa	−
41	00410249	DPSxon	−
42	00420D5D	SDxPDxa	−
43	00431CC4	SPDSanaxn	−
44	00440328	SDna	SRCERASE
45	00450B29	DPSnaon	−
46	004606C6	DSPDaox	−
47	0047076A	PSDPxaxn	−
48	00480368	SDPxa	−
49	004916C5	PDSPDaoxxn	−
4A	004A0789	DPSDoax	−
4B	004B0605	PDSnox	−
4C	004C0CC8	SDPana	−
4D	004D1954	SSPxDSxoxn	−
4E	004E0645	PDSPxox	−
4F	004F0E25	PDSnoan	−
50	00500325	PDna	−
51	00510B26	DSPnaon	−
52	005206C9	DPSDaox	−
53	00530764	SPDSxaxn	−
54	005408A9	DPSonon	−
55	00550009	Dn	DSTINVERT
56	005601A9	DPSox	−
57	00570389	DPSoan	−
58	00580785	PDSPoax	−
59	00590609	DPSnox	−
5A	005A0049	DPx	PATINVERT
5B	005B18A9	DPSDonox	−
5C	005C0649	DPSDxox	−
5D	005D0E29	DPSnoan	−
5E	005E1B29	DPSDnaox	−
5F	005F00E9	DPan	−
60	00600365	PDSxa	−
61	006116C6	DSPDSaoxxn	−
62	00620786	DSPDoax	−
63	00630608	SDPnox	−
64	00640788	SDPSoax	−
65	00650606	DSPnox	−
66	00660046	DSx	SRCINVERT
67	006718A8	SDPSonox	−
68	006858A6	DSPDSonoxxn	−
69	00690145	PDSxxn	−
6A	006A01E9	DPSax	−
6B	006B178A	PSDPSoaxxn	−
6C	006C01E8	SDPax	−
6D	006D1785	PDSPDoaxxn	−
6E	006E1E28	SDPSnoax	−
6F	006F0C65	PDSxnan	−
70	00700CC5	PDSana	−
71	00711D5C	SSDxPDxaxn	−
72	00720648	SDPSxox	−
73	00730E28	SDPnoan	−
74	00740646	DSPDxox	−
75	00750E26	DSPnoan	−
76	00761B28	SDPSnaox	−
77	007700E6	DSan	−
78	007801E5	PDSax	−
79	00791786	DSPDSoaxxn	−
7A	007A1E29	DPSDnoax	−
7B	007B0C68	SDPxnan	−
7C	007C1E24	SPDSnoax	−
7D	007D0C69	DPSxnan	−
7E	007E0955	SPxDSxo	−
7F	007F03C9	DPSaan	−
80	008003E9	DPSaa	−
81	00810975	SPxDSxon	−
82	00820C49	DPSxna	−
83	00831E04	SPDSnoaxn	−
84	00840C48	SDPxna	−
85	00851E05	PDSPnoaxn	−
86	008617A6	DSPDSoaxx	−
87	008701C5	PDSaxn	−
88	008800C6	DSa	SRCAND
89	00891B08	SDPSnaoxn	−
8A	008A0E06	DSPnoa	−
8B	008B0666	DSPDxoxn	−
8C	008C0E08	SDPnoa	−
8D	008D0668	SDPSxoxn	−
8E	008E1D7C	SSDxPDxax	−
8F	008F0CE5	PDSanan	−
90	00900C45	PDSxna	−
91	00911E08	SDPSnoaxn	−
92	009217A9	DPSDPoaxx	−
93	009301C4	SPDaxn	−
94	009417AA	PSDPSoaxx	−
95	009501C9	DPSaxn	−
96	00960169	DPSxx	−
97	0097588A	PSDPSonoxx	−
98	00981888	SDPSonoxn	−
99	00990066	DSxn	−
9A	009A0709	DPSnax	−
9B	009B07A8	SDPSoaxn	−
9C	009C0704	SPDnax	−
9D	009D07A6	DSPDoaxn	−
9E	009E16E6	DSPDSaoxx	−
9F	009F0345	PDSxan	−
A0	00A000C9	DPa	−
A1	00A11B05	PDSPnaoxn	−
A2	00A20E09	DPSnoa	−
A3	00A30669	DPSDxoxn	−
A4	00A41885	PDSPonoxn	−
A5	00A50065	PDxn	−
A6	00A60706	DSPnax	−
A7	00A707A5	PDSPoaxn	−
A8	00A803A9	DPSoa	−
A9	00A90189	DPSoxn	−
AA	00AA0029	D	−
AB	00AB0889	DPSono	−
AC	00AC0744	SPDSxax	−
AD	00AD06E9	DPSDaoxn	−
AE	00AE0B06	DSPnao	−
AF	00AF0229	DPno	−
B0	00B00E05	PDSnoa	−
B1	00B10665	PDSPxoxn	−
B2	00B21974	SSPxDSxox	−
B3	00B30CE8	SDPanan	−
B4	00B4070A	PSDnax	−
B5	00B507A9	DPSDoaxn	−
B6	00B616E9	DPSDPaoxx	−
B7	00B70348	SDPxan	−
B8	00B8074A	PSDPxax	−
B9	00B906E6	DSPDaoxn	−
BA	00BA0B09	DPSnao	−
BB	00BB0226	DSno	MERGEPAINT
BC	00BC1CE4	SPDSanax	−
BD	00BD0D7D	SDxPDxan	−
BE	00BE0269	DPSxo	−
BF	00BF08C9	DPSano	−
C0	00C000CA	PSa	MERGECOPY
C1	00C11B04	SPDSnaoxn	−
C2	00C21884	SPDSonoxn	−
C3	00C3006A	PSxn	−
C4	00C40E04	SPDnoa	−
C5	00C50664	SPDSxoxn	−
C6	00C60708	SDPnax	−
C7	00C707AA	PSDPoaxn	−
C8	00C803A8	SDPoa	−
C9	00C90184	SPDoxn	−
CA	00CA0749	DPSDxax	−
CB	00CB06E4	SPDSaoxn	−
CC	00CC0020	S	SRCCOPY
CD	00CD0888	SDPono	−
CE	00CE0B08	SDPnao	−
CF	00CF0224	SPno	−
D0	00D00E0A	PSDnoa	−
D1	00D1066A	PSDPxoxn	−
D2	00D20705	PDSnax	−
D3	00D307A4	SPDSoaxn	−
D4	00D41D78	SSPxPDxax	−
D5	00D50CE9	DPSanan	−
D6	00D616EA	PSDPSaoxx	−
D7	00D70349	DPSxan	−
D8	00D80745	PDSPxax	−
D9	00D906E8	SDPSaoxn	−
DA	00DA1CE9	DPSDanax	−
DB	00DB0D75	SPxDSxan	−
DC	00DC0B04	SPDnao	−
DD	00DD0228	SDno	−
DE	00DE0268	SDPxo	−
DF	00DF08C8	SDPano	−
E0	00E003A5	PDSoa	−
E1	00E10185	PDSoxn	−
E2	00E20746	DSPDxax	−
E3	00E306EA	PSDPaoxn	−
E4	00E40748	SDPSxax	−
E5	00E506E5	PDSPaoxn	−
E6	00E61CE8	SDPSanax	−
E7	00E70D79	SPxPDxan	−
E8	00E81D74	SSPxDSxax	−
E9	00E95CE6	DSPDSanaxxn	−
EA	00EA02E9	DPSao	−
EB	00EB0849	DPSxno	−
EC	00EC02E8	SDPao	−
ED	00ED0848	SDPxno	−
EE	00EE0086	DSo	SRCPAINT
EF	00EF0A08	SDPnoo	−
F0	00F00021	P	PATCOPY
F1	00F10885	PDSono	−
F2	00F20B05	PDSnao	−
F3	00F3022A	PSno	−
F4	00F40B0A	PSDnao	−
F5	00F50225	PDno	−
F6	00F60265	PDSxo	−
F7	00F708C5	PDSano	−
F8	00F802E5	PDSao	−
F9	00F90845	PDSxno	−
FA	00FA0089	DPo	−
FB	00FB0A09	DPSnoo	PATPAINT
FC	00FC008A	PSo	−
FD	00FD0A0A	PSDnoo	−
FE	00FE02A9	DPSoo	−
FF	00FF0062	1	WHITENESS


Virtual-Key Codes

The following table shows the symbolic constant names, hexadecimal values, and keyboard equivalents for the virtual-key codes used by the Microsoft Windows operating system. The codes are listed in numeric order.

Symbolic constant name	Value (hexadecimal)	Mouse or keyboard equivalent
VK_LBUTTON	01	Left mouse button
VK_RBUTTON	02	Right mouse button
VK_CANCEL	03	Control-break processing
VK_MBUTTON	04	Middle mouse button (three-button mouse)
—	05−07	Undefined
VK_BACK	08	BACKSPACE key
VK_TAB	09	TAB key
—	0A−0B	Undefined
VK_CLEAR	0C	CLEAR key
VK_RETURN	0D	ENTER key
—	0E−0F	Undefined
VK_SHIFT	10	SHIFT key
VK_CONTROL	11	CTRL key
VK_MENU	12	ALT key
VK_PAUSE	13	PAUSE key
VK_CAPITAL	14	CAPS LOCK key
—	15−19	Reserved for Kanji systems
—	1A	Undefined
VK_ESCAPE	1B	ESC key
—	1C−1F	Reserved for Kanji systems
VK_SPACE	20	SPACEBAR
VK_PRIOR	21	PAGE UP key
VK_NEXT	22	PAGE DOWN key
VK_END	23	END key
VK_HOME	24	HOME key
VK_LEFT	25	LEFT ARROW key
VK_UP	26	UP ARROW key
VK_RIGHT	27	RIGHT ARROW key
VK_DOWN	28	DOWN ARROW key
VK_SELECT	29	SELECT key
—	2A	Original equipment manufacturer (OEM) specific
VK_EXECUTE	2B	EXECUTE key
VK_SNAPSHOT	2C	PRINT SCREEN key for Windows 3.0 and later
VK_INSERT	2D	INS key
VK_DELETE	2E	DEL key
VK_HELP	2F	HELP key
VK_0	30	0 key
VK_1	31	1 key
VK_2	32	2 key
VK_3	33	3 key
VK_4	34	4 key
VK_5	35	5 key
VK_6	36	6 key
VK_7	37	7 key
VK_8	38	8 key
VK_9	39	9 key
—	3A−40	Undefined
VK_A	41	A key
VK_B	42	B key
VK_C	43	C key
VK_D	44	D key
VK_E	45	E key
VK_F	46	F key
VK_G	47	G key
VK_H	48	H key
VK_I	49	I key
VK_J	4A	J key
VK_K	4B	K key
VK_L	4C	L key
VK_M	4D	M key
VK_N	4E	N key
VK_O	4F	O key
VK_P	50	P key
VK_Q	51	Q key
VK_R	52	R key
VK_S	53	S key
VK_T	54	T key
VK_U	55	U key
VK_V	56	V key
VK_W	57	W key
VK_X	58	X key
VK_Y	59	Y key
VK_Z	5A	Z key
VK_LWIN	5B	Left Windows key (Microsoft Natural Keyboard)
VK_RWIN	5C	Right Windows key (Microsoft Natural Keyboard)
VK_APPS	5D	Applications key (Microsoft Natural Keyboard)
—	5E−5F	Undefined
VK_NUMPAD0	60	Numeric keypad 0 key
VK_NUMPAD1	61	Numeric keypad 1 key
VK_NUMPAD2	62	Numeric keypad 2 key
VK_NUMPAD3	63	Numeric keypad 3 key
VK_NUMPAD4	64	Numeric keypad 4 key
VK_NUMPAD5	65	Numeric keypad 5 key
VK_NUMPAD6	66	Numeric keypad 6 key
VK_NUMPAD7	67	Numeric keypad 7 key
VK_NUMPAD8	68	Numeric keypad 8 key
VK_NUMPAD9	69	Numeric keypad 9 key
VK_MULTIPLY	6A	Multiply key
VK_ADD	6B	Add key
VK_SEPARATOR	6C	Separator key
VK_SUBTRACT	6D	Subtract key
VK_DECIMAL	6E	Decimal key
VK_DIVIDE	6F	Divide key
VK_F1	70	F1 key
VK_F2	71	F2 key
VK_F3	72	F3 key
VK_F4	73	F4 key
VK_F5	74	F5 key
VK_F6	75	F6 key
VK_F7	76	F7 key
VK_F8	77	F8 key
VK_F9	78	F9 key
VK_F10	79	F10 key
VK_F11	7A	F11 key
VK_F12	7B	F12 key
VK_F13	7C	F13 key
VK_F14	7D	F14 key
VK_F15	7E	F15 key
VK_F16	7F	F16 key
VK_F17	80H	F17 key
VK_F18	81H	F18 key
VK_F19	82H	F19 key
VK_F20	83H	F20 key
VK_F21	84H	F21 key
VK_F22	85H	F22 key
VK_F23	86H	F23 key
VK_F24	87H	F24 key
—	88−8F	Unassigned
VK_NUMLOCK	90	NUM LOCK key
VK_SCROLL	91	SCROLL LOCK key
—	92−B9	Unassigned
—	BA−C0	OEM specific
—	C1−DA	Unassigned
—	DB−E4	OEM specific
—	E5	Unassigned
—	E6	OEM specific
—	E7−E8	Unassigned
—	E9−F5	OEM specific
VK_ATTN	F6	Attn key
VK_CRSEL	F7	CrSel key
VK_EXSEL	F8	ExSel key
VK_EREOF	F9	Erase EOF key
VK_PLAY	FA	Play key
VK_ZOOM	FB	Zoom key
VK_NONAME	FC	Reserved for future use.
VK_PA1	FD	PA1 key
VK_OEM_CLEAR	FE	Clear key


XTYP_ADVDATA

XTYP_ADVDATA

A dynamic data exchange (DDE) client callback function receives the XTYP_ADVDATA transaction after establishing an advise loop with a server. This transaction informs the client that the value of the data item has changed.

Parameters

uFmt

Specifies the format atom of the data sent from the server.

hconv

Identifies the conversation.

hsz1

Identifies the topic name.

hsz2

Identifies the item name.

hdata

Identifies the data associated with the topic name and item name pair. This parameter is NULL if the client specified the XTYPF_NODATA flag when it requested the advise loop.

dwData1

Not used.

dwData2

Not used.

Return Values

A DDE callback function should return DDE_FACK if it processes this transaction, DDE_FBUSY if it is too busy to process this transaction, or DDE_FNOTPROCESSED if it rejects this transaction.

Remarks

An application must not free the data handle obtained during this transaction. An application must, however, copy the data associated with the data handle if the application must process the data after the callback function returns. An application can use the DdeGetData function to copy the data.

See Also

DdeClientTransaction, DdeGetData, DdePostAdvise


XTYP_ADVREQ

XTYP_ADVREQ

The system sends the XTYP_ADVREQ transaction to a server after the server calls the DdePostAdvise function. This transaction informs the server that an advise transaction is outstanding on the specified topic name and item name pair and that data corresponding to the topic name and item name pair has changed.

Parameters

uFmt

Specifies the format in which the data should be submitted to the client.

hconv

Identifies the conversation.

hsz1

Identifies the topic name.

hsz2

Identifies the item name that has changed.

hdata

Not used.

dwData1

Specifies the count, in the low-order word, of XTYP_ADVREQ transactions that remain to be processed on the same topic, item, and format name set within the context of the current call to the DdePostAdvise function. The count is zero if the current XTYP_ADVREQ transaction is the last one. A server can use this count to determine whether to create an HDATA_APPOWNED data handle for the advise data.

The low-order word is set to CADV_LATEACK if the Dynamic Data Exchange Management Library (DDEML) issued the XTYP_ADVREQ transaction because of a late-arriving DDE_ACK message from a client being outrun by the server.

The high-order word is not used.

dwData2

Not used.

Return Values

The server should first call the DdeCreateDataHandle function to create a data handle that identifies the changed data and then return the handle. The server should return NULL if it is unable to complete the transaction.

Remarks

A server cannot block this transaction type; the CBR_BLOCK return code is ignored.

See Also

DdeCreateDataHandle, DdeInitialize, DdePostAdvise


XTYP_ADVSTART

XTYP_ADVSTART

A dynamic data exchange (DDE) server callback function receives the XTYP_ADVSTART transaction when a client specifies XTYP_ADVSTART as the uType parameter of the DdeClientTransaction function. A client uses this transaction to establish an advise loop with a server.

Parameters

uFmt

Specifies the data format requested by the client.

hconv

Identifies the conversation.

hsz1

Identifies the topic name.

hsz2

Identifies the item name.

hdata

Not used.

dwData1

Not used.

dwData2

Not used.

Return Values

A server callback function should return TRUE to allow an advise loop on the specified topic name and item name pair, or FALSE to deny the advise loop. If the callback function returns TRUE, any subsequent calls to the DdePostAdvise function by the server on the same topic name and item name pair causes the system to send XTYP_ADVREQ transactions to the server.

Remarks

If a client requests an advise loop on a topic name, item name, and data format for an advise loop that is already established, the Dynamic Data Exchange Management Library (DDEML) does not create a duplicate advise loop but instead alters the advise loop flags (XTYPF_ACKREQ and XTYPF_NODATA) to match the latest request.

This transaction is filtered if the server application specified the CBF_FAIL_ADVISES flag in the DdeInitialize function.

See Also

DdeClientTransaction, DdeInitialize, DdePostAdvise


XTYP_ADVSTOP

XTYP_ADVSTOP

A dynamic data exchange (DDE) server callback function receives the XTYP_ADVSTOP transaction when a client specifies XTYP_ADVSTOP in the DdeClientTransaction function. A client uses this transaction to end an advise loop with a server.

Parameters

uFmt

Specifies the data format associated with the advise loop being ended.

hconv

Identifies the conversation.

hsz1

Identifies the topic name.

hsz2

Identifies the item name.

hdata

Not used.

dwData1

Not used.

dwData2

Not used.

Remarks

This transaction is filtered if the server application specified the CBF_FAIL_ADVISES flag in the DdeInitialize function.

See Also

DdeClientTransaction, DdeInitialize, DdePostAdvise


XTYP_CONNECT

XTYP_CONNECT

A dynamic data exchange (DDE) server callback function receives the XTYP_CONNECT transaction when a client specifies a service name that the server supports and a topic name that is not NULL in a call to the DdeConnect function.

Parameters

uFmt

Not used.

hconv

Not used.

hsz1

Identifies the topic name.

hsz2

Identifies the service name.

hdata

Not used.

dwData1

Points to a CONVCONTEXT structure that contains context information for the conversation. If the client is not a Dynamic Data Exchange Management Library (DDEML) application, this parameter is 0.

dwData2

Specifies whether the client is the same application instance as the server. If the parameter is 1, the client is the same instance. If the parameter is 0, the client is a different instance.

Return Values

A server callback function should return TRUE to allow the client to establish a conversation on the specified service name and topic name pair, or the function should return FALSE to deny the conversation. If the callback function returns TRUE and a conversation is successfully established, the system passes the conversation handle to the server by issuing an XTYP_CONNECT_CONFIRM transaction to the server’s callback function (unless the server specified the CBF_SKIP_CONNECT_CONFIRMS flag in the DdeInitialize function).

Remarks

This transaction is filtered if the server application specified the CBF_FAIL_CONNECTIONS flag in the DdeInitialize function.

A server cannot block this transaction type; the CBR_BLOCK return code is ignored.

See Also

CONVCONTEXT, DdeConnect, DdeInitialize


XTYP_CONNECT_CONFIRM

XTYP_CONNECT_CONFIRM

A dynamic data exchange (DDE) server callback function receives the XTYP_CONNECT_CONFIRM transaction to confirm that a conversation has been established with a client and to provide the server with the conversation handle. The system sends this transaction as a result of a previous XTYP_CONNECT or XTYP_WILDCONNECT transaction.

Parameters

uFmt

Not used.

hconv

Identifies the new conversation.

hsz1

Identifies the topic name on which the conversation has been established.

hsz2

Identifies the service name on which the conversation has been established.

hdata

Not used.

dwData1

Not used.

dwData2

Specifies whether the client is the same application instance as the server. If the parameter is 1, the client is the same instance. If the parameter is 0, the client is a different instance.

Remarks

This transaction is filtered if the server application specified the CBF_SKIP_CONNECT_CONFIRMS flag in the DdeInitialize function.

A server cannot block this transaction type; the CBR_BLOCK return code is ignored.

See Also

DdeConnect, DdeConnectList, DdeInitialize


XTYP_DISCONNECT

XTYP_DISCONNECT

An application’s dynamic data exchange (DDE) callback function receives the XTYP_DISCONNECT transaction when the application’s partner in a conversation uses the DdeDisconnect function to terminate the conversation.

Parameters

uFmt

Not used.

hconv

Identifies that the conversation was terminated.

hsz1

Not used.

hsz2

Not used.

hdata

Not used.

dwData1

Not used.

dwData2

Specifies whether the partners in the conversation are the same application instance. If this parameter is 1, the partners are the same instance. If this parameter is 0, the partners are different instances.

Remarks

This transaction is filtered if the application specified the CBF_SKIP_DISCONNECTS flag in the DdeInitialize function.

The application can obtain the status of the terminated conversation by calling the DdeQueryConvInfo function while processing this transaction. The conversation handle becomes invalid after the callback function returns.

An application cannot block this transaction type; the CBR_BLOCK return code is ignored.

See Also

DdeDisconnect, DdeInitialize, DdeQueryConvInfo


XTYP_ERROR

XTYP_ERROR

A dynamic data exchange (DDE) callback function receives the XTYP_ERROR transaction when a critical error occurs.

Parameters

uFmt

Not used.

hconv

Identifies the conversation associated with the error. This parameter is NULL if the error is not associated with a conversation.

hsz1

Not used.

hsz2

Not used.

hdata

Not used.

dwData1

Specifies the error code in the low-order word. Currently, only the following error code is supported:

Error Code	Description
DMLERR_LOW_MEMORY	Memory is low; advise, poke, or execute data may be lost, or the system may fail.
dwData2

Not used.

Remarks

An application cannot block this transaction type; the CBR_BLOCK return code is ignored. The DDEML attempts to free memory by removing noncritical resources. An application that has blocked conversations should unblock them.


XTYP_EXECUTE

XTYP_EXECUTE

A dynamic data exchange (DDE) server callback function receives the XTYP_EXECUTE transaction when a client specifies XTYP_EXECUTE in the DdeClientTransaction function. A client uses this transaction to send a command string to the server.

Parameters

uFmt

Not used.

hconv

Identifies the conversation.

hsz1

Identifies the topic name.

hsz2

Not used.

hdata

Identifies the command string.

dwData1

Not used.

dwData2

Not used.

Return Values

A server callback function should return DDE_FACK if it processes this transaction, DDE_FBUSY if it is too busy to process this transaction, or DDE_FNOTPROCESSED if it rejects this transaction.

Remarks

This transaction is filtered if the server application specified the CBF_FAIL_EXECUTES flag in the DdeInitialize function.

An application must free the data handle obtained during this transaction. An application must, however, copy the command string associated with the data handle if the application must process the string after the callback function returns. An application can use the DdeGetData function to copy the data.

Because most client applications expect a server application to perform an XTYP_EXECUTE transaction synchonrously, a server should attempt to perform all processing of the XTYP_EXECUTE transaction either from within the DDE callback function or by returning the CBR_BLOCK return code. If the hdata parameter is a command that instructs the server to terminate, the server should do so after processing the XTYP_EXECUTE transaction.

See Also

DdeClientTransaction, DdeGetData, DdeInitialize


XTYP_MONITOR

XTYP_MONITOR

The dynamic data exchange (DDE) callback function of a DDE debugging application receives the XTYP_MONITOR transaction whenever a DDE event occurs in the system. To receive this transaction, an application must specify the APPCLASS_MONITOR flag when it calls the DdeInitialize function.

Parameters

uFmt

Not used.

hconv

Not used.

hsz1

Not used.

hsz2

Not used.

hdata

Identifies a DDE object that contains information about the DDE event. The application should use the DdeAccessData function to obtain a pointer to the object.

dwData1

Not used.

dwData2

Identifies the DDE event. This parameter may be one of the following values:

Value	Meaning
MF_CALLBACKS	The system sent a transaction to a DDE callback function. The DDE object contains a MONCBSTRUCT structure that provides information about the transaction.
MF_CONV	A DDE conversation was established or terminated. The DDE object contains a MONCONVSTRUCT structure that provides information about the conversation.
MF_ERRORS	A DDE error occurred. The DDE object contains a MONERRSTRUCT structure that provides information about the error.
MF_HSZ_INFO	A DDE application created, freed, or incremented the usage count of a string handle, or a string handle was freed as a result of a call to the DdeUninitialize function. The DDE object contains a MONHSZSTRUCT structure that provides information about the string handle.
MF_LINKS	A DDE application started or stopped an advise loop. The DDE object contains a MONLINKSTRUCT structure that provides information about the advise loop.
MF_POSTMSGS	The system or an application posted a DDE message. The DDE object contains a MONMSGSTRUCT structure that provides information about the message.
MF_SENDMSGS	The system or an application sent a DDE message. The DDE object contains a MONMSGSTRUCT structure that provides information about the message.
Return Value

If the callback function processes this transaction, it should return 0.

See Also

DdeAccessData, DdeInitialize, DdeUninitialize, MONCBSTRUCT, MONCONVSTRUCT, MONERRSTRUCT, MONHSZSTRUCT, MONLINKSTRUCT, MONMSGSTRUCT


XTYP_POKE

XTYP_POKE

A dynamic data exchange (DDE) server callback function receives the XTYP_POKE transaction when a client specifies XTYP_POKE in DdeClientTransaction function. A client uses this transaction to send unsolicited data to the server.

Parameters

uFmt

Specifies the format of the data sent from the server.

hconv

Identifies the conversation.

hsz1

Identifies the topic name.

hsz2

Identifies the item name.

hdata

Identifies the data that the client is sending to the server.

dwData1

Not used.

dwData2

Not used.

Return Value

A server callback function should return the DDE_FACK flag if it processes this transaction, the DDE_FBUSY flag if it is too busy to process this transaction, or the DDE_FNOTPROCESSED flag if it rejects this transaction.

Remarks

This transaction is filtered if the server application specified the CBF_FAIL_POKES flag in the DdeInitialize function.

See Also

DdeClientTransaction, DdeInitialize


XTYP_REGISTER

XTYP_REGISTER

A dynamic data exchange (DDE) callback function receives the XTYP_REGISTER transaction type whenever a Dynamic Data Exchange Library (DDEML) server application uses the DdeNameService function to register a service name, or whenever a non-DDEML application that supports the System topic is started.

Parameters

uFmt

Not used.

hconv

Not used.

hsz1

Identifies the base service name being registered.

hsz2

Identifies the instance-specific service name being registered.

hdata

Not used.

dwData1

Not used.

dwData2

Not used.

Remarks

This transaction is filtered if the application specified the CBF_SKIP_REGISTRATIONS flag in the DdeInitialize function.

A application cannot block this transaction type; the CBR_BLOCK return code is ignored.

An application should use the hsz1 parameter to add the service name to the list of servers available to the user. An application should use the hsz2 parameter to identify which application instance has started.

See Also

DdeInitialize, DdeNameService


XTYP_REQUEST

XTYP_REQUEST

A dynamic data exchange (DDE) server callback function receives the XTYP_REQUEST transaction when a client specifies XTYP_REQUEST in the DdeClientTransaction function. A client uses this transaction to request data from a server.

Parameters

uFmt

Specifies the format in which the server should submit data to the client.

hconv

Identifies the conversation.

hsz1

Identifies the topic name.

hsz2

Identifies the item name.

hdata

Not used.

dwData1

Not used.

dwData2

Not used.

Return Value

The server should call the DdeCreateDataHandle function to create a data handle that identifies the data and then return the handle. The server should return NULL if it is unable to complete the transaction. If the server returns NULL, the client will receive a DDE_FNOTPROCESSED flag.

Remarks

This transaction is filtered if the server application specified the CBF_FAIL_REQUESTS flag in the DdeInitialize function.

If responding to this transaction requires lengthy processing, the server can return the CBR_BLOCK return code to suspend future transactions on the current conversation and then process the transaction asynchronously. When the server has finished and the data is ready to pass to the client, the server can call the DdeEnableCallback function to resume the conversation.

See Also

DdeClientTransaction, DdeCreateDataHandle, DdeEnableCallback, DdeInitialize


XTYP_UNREGISTER

XTYP_UNREGISTER

A dynamic data exchange (DDE) callback function receives the XTYP_UNREGISTER transaction whenever a Dynamic Data Exchange Management Library (DDEML) server application uses the DdeNameService function to unregister a service name, or whenever a non-DDEML application that supports the System topic is terminated.

Parameters

uFmt

Not used.

hconv

Not used.

hsz1

Identifies the base service name being unregistered.

hsz2

Identifies the instance-specific service name being unregistered.

hdata

Not used.

dwData1

Not used.

dwData2

Not used.

Remarks

This transaction is filtered if the application specified the CBF_SKIP_REGISTRATIONS flag in the DdeInitialize function.

A application cannot block this transaction type; the CBR_BLOCK return code is ignored.

An application should use the hsz1 parameter to remove the service name from the list of servers available to the user. An application should use the hsz2 parameter to identify which application instance has terminated.

See Also

DdeInitialize, DdeNameService


XTYP_WILDCONNECT

XTYP_WILDCONNECT

A dynamic data exchange (DDE) server callback function receives the XTYP_WILDCONNECT transaction when a client specifies a NULL service name, a NULL topic name, or both in a call to the DdeConnect or DdeConnectList function. This transaction allows a client to establish a conversation on each of the server’s service name and topic name pairs that match the specified service name and topic name.

Parameters

uFmt

Not used.

hconv

Not used.

hsz1

Identifies the topic name. If this parameter is NULL, the client is requesting a conversation on all topic names that the server supports.

hsz2

Identifies the service name. If this parameter is NULL, the client is requesting a conversation on all service names that the server supports.

hdata

Not used.

dwData1

Points to a CONVCONTEXT structure that contains context information for the conversation. If the client is not a Dynamic Data Exchange Management Library (DDEML) application, this parameter is set to 0.

dwData2

Specifies whether the client is the same application instance as the server. If the parameter is 1, the client is same instance. If the parameter is 0, the client is a different instance.

Return Value

The server should return a data handle that identifies an array of HSZPAIR structures. The array should contain one structure for each service-name and topic-name pair that matches the service-name and topic-name pair requested by the client. The array must be terminated by a NULL string handle. The system sends the XTYP_CONNECT_CONFIRM transaction to the server to confirm each conversation and to pass the conversation handles to the server. The server will not receive these confirmations if it specified the CBF_SKIP_CONNECT_CONFIRMS flag in the DdeInitialize function.

The server should return NULL to refuse the XTYP_WILDCONNECT transaction.

Remarks

This transaction is filtered if the server application specified the CBF_FAIL_CONNECTIONS flag in the DdeInitialize function.

A server cannot block this transaction type; the CBR_BLOCK return code is ignored.

See Also

CONVCONTEXT, DdeConnect, DdeInitialize, HSZPAIR


XTYP_XACT_COMPLETE

XTYP_XACT_COMPLETE

A dynamic data exchange (DDE) client callback function receives the XTYP_XACT_COMPLETE transaction when an asynchronous transaction, initiated by a call to the DdeClientTransaction function, has completed.

Parameters

uFmt

Specifies the format of the data associated with the completed transaction (if applicable) or NULL if no data was exchanged during the transaction.

hconv

Identifies the conversation.

hsz1

Identifies the topic name involved in the completed transaction.

hsz2

Identifies the item name involved in the completed transaction.

hdata

Identifies the data involved in the completed transaction, if applicable. If the transaction was successful but involved no data, this parameter is TRUE. This parameter is NULL if the transaction was unsuccessful.

dwData1

Specifies the transaction identifier of the completed transaction.

dwData2

Specifies any applicable DDE_ status flags in the low word. This parameter provides support for applications dependent on DDE_APPSTATUS bits. It is recommended that applications no longer use these bits — future versions of the Dynamic Data Exchange Management Library (DDEML) may not support them.

Remarks

An application must not free the data handle obtained during this transaction. An application must, however, copy the data associated with the data handle if the application must process the data after the callback function returns. An application can use the DdeGetData function to copy the data.

See Also

DdeClientTransaction, DdeGetData


ACCESS_MODE [New - Windows NT]
ACCESS_MODE

[New - Windows NT]

The ACCESS_MODE enumeration type contains values that indicate how the access rights in an EXPLICIT_ACCESS structure apply to the trustee. Functions such as SetEntriesInAcl and GetExplicitEntriesFromAcl use these values to set or retrieve information in an access-control entry (ACE).

typedef enum _ACCESS_MODE

{

    NOT_USED_ACCESS = 0,

    GRANT_ACCESS,

    SET_ACCESS,

    DENY_ACCESS,

    REVOKE_ACCESS,

    SET_AUDIT_SUCCESS,

    SET_AUDIT_FAILURE

} ACCESS_MODE;

Enumerator	Meaning
GRANT_ACCESS	An input flag that creates an ACCESS_ALLOWED_ACE. The new ACE combines the specified rights with any existing allowed or denied rights of the trustee.
SET_ACCESS	Indicates an ACCESS_ALLOWED_ACE that allows the specified rights.  On input, this flag discards any existing access-control information for the trustee.
DENY_ACCESS	Indicates an ACCESS_DENIED_ACE that denies the specified rights.  On input, this flag denies the specified rights in addition to any currently denied rights of the trustee. It also modifies or deletes any existing ACCESS_ALLOWED_ACE for the trustee that allows the specified rights.
REVOKE_ACCESS	An input flag that removes all existing ACCESS_DENIED_ACE, ACCESS_ALLOWED_ACE, or SYSTEM_AUDIT_ACEs for the specified trustee.
SET_AUDIT_SUCCESS	Indicates a SYSTEM_AUDIT_ACE that generates audit messages for successful attempts to use the specified access rights. You can combine this value with SET_AUDIT_FAILURE. On input, this flag combines the specified rights with any existing audited access rights for the trustee.
SET_AUDIT_FAILURE	Indicates a SYSTEM_AUDIT_ACE that generates audit messages for failed attempts to use the specified access rights. You can combine this value with SET_AUDIT_SUCCESS. On input, this flag combines the specified rights with any existing audited access rights for the trustee.
See Also

ACCESS_DENIED_ACE, ACCESS_ALLOWED_ACE, ACE, EXPLICIT_ACCESS, GetExplicitEntriesFromAcl, SetEntriesInAcl, SYSTEM_AUDIT_ACE


ACL_INFORMATION_CLASS

The ACL_INFORMATION_CLASS enumeration type contains values that specify the type of information being assigned to or retrieved from an access-control list (ACL).

typedef enum _ACL_INFORMATION_CLASS { // aclic

    AclRevisionInformation = 1,    // ACL revision information

    AclSizeInformation             // ACL size information

} ACL_INFORMATION_CLASS;

See Also

ACL, ACL_REVISION_INFORMATION, ACL_SIZE_INFORMATION, GetAclInformation, SetAclInformation


FD_FLAGS

The FD_FLAGS enumeration type defines the flags used with the dwFlags member of the FILEDESCRIPTOR structure.

typedef enum {

    FD_CLSID = 0x0001,

    FD_SIZEPOINT = 0x0002,

    FD_ATTRIBUTES = 0x0004,

    FD_CREATETIME = 0x0008,

    FD_ACCESSTIME = 0x0010,

    FD_WRITESTIME = 0x0020,

    FD_FILESIZE = 0x0040,

    FD_LINKUI = 0x8000,

} FD_FLAGS;


GET_FILEEX_INFO_LEVELS [New - Windows NT]
GET_FILEEX_INFO_LEVELS

[New - Windows NT]

The GET_FILEEX_INFO_LEVELS enumeration type contains values that are used with the GetFileAttributesEx function to specify the type of attribute information to obtain.

typedef enum _GET_FILEEX_INFO_LEVELS {

    GetFileExInfoStandard

} GET_FILEEX_INFO_LEVELS ;

Currently, one enumerator value is defined:

Enumerator	Meaning
GetFileExInfoStandard	The GetFileAttributesEx function obtains a standard set of attribute information. The data is returned in a WIN32_FILE_ATTRIBUTE_DATA structure.
See Also

GetFileAttributesEx, WIN32_FILE_ATTRIBUTE_DATA


MEDIA_TYPE

The MEDIA_TYPE enumeration type contains values that specify various forms of device media. The comments explain the enumerators.

typedef enum _MEDIA_TYPE {

    Unknown,                // Format is unknown

    F5_1Pt2_512,            // 5.25", 1.2MB,  512 bytes/sector

    F3_1Pt44_512,           // 3.5",  1.44MB, 512 bytes/sector

    F3_2Pt88_512,           // 3.5",  2.88MB, 512 bytes/sector

    F3_20Pt8_512,           // 3.5",  20.8MB, 512 bytes/sector

    F3_720_512,             // 3.5",  720KB,  512 bytes/sector

    F5_360_512,             // 5.25", 360KB,  512 bytes/sector

    F5_320_512,             // 5.25", 320KB,  512 bytes/sector

    F5_320_1024,            // 5.25", 320KB,  1024 bytes/sector

    F5_180_512,             // 5.25", 180KB,  512 bytes/sector

    F5_160_512,             // 5.25", 160KB,  512 bytes/sector

    RemovableMedia,         // Removable media other than floppy

    FixedMedia              // Fixed hard disk media

} MEDIA_TYPE;

Remarks

The MediaType member of the DISK_GEOMETRY data structure is of type MEDIA_TYPE. The DeviceIoControl function receives a DISK_GEOMETRY structure in response to an IOCTL_DISK_GET_DRIVE_GEOMETRY device I/O operation. The DeviceIoControl function receives an array of DISK_GEOMETRY structures in response to an IOCTL_DISK_GET_MEDIA_TYPES device I/O operation.

See Also

DeviceIoControl, DISK_GEOMETRY, IOCTL_DISK_GET_DRIVE_GEOMETRY, IOCTL_DISK_GET_MEDIA_TYPES


MULTIPLE_TRUSTEE_OPERATION [New - Windows NT]
MULTIPLE_TRUSTEE_OPERATION

[New - Windows NT]

The MULTIPLE_TRUSTEE_OPERATION enumeration type contains values that indicate whether a TRUSTEE structure is an impersonate trustee.

typedef enum _MULTIPLE_TRUSTEE_OPERATION

{

    NO_MULTIPLE_TRUSTEE,

    TRUSTEE_IS_IMPERSONATE,

} MULTIPLE_TRUSTEE_OPERATION;

Enumerator	Meaning
NO_MULTIPLE_TRUSTEE	The trustee is not an impersonate trustee.
TRUSTEE_IS_IMPERSONATE	The trustee is an impersonate trustee. The pMultipleTrustee member of the TRUSTEE structure points to a trustee for a server that can impersonate the client trustee.
See Also

TRUSTEE


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	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);

See Also

RasDial, RasGetConnectStatus, RasGetProjectionInfo, RASCONNSTATUS


RAS_PARAMS_FORMAT [New - Windows NT]
RAS_PARAMS_FORMAT

[New - Windows NT]

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

} ;

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

RAS_PARAMETERS


RASPROJECTION

The RASPROJECTION enumeration type defines values that specify a particular authentication protocol or Point-to-Point Protocol control protocol (PPP). 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.

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

RasGetProjectionInfo, RASAMB, RASPPPIP, RASPPPIPX, RASPPPNBF


SE_OBJECT_TYPE [New - Windows NT]
SE_OBJECT_TYPE

[New - Windows NT]

The SE_OBJECT_TYPE enumeration type contains values that correspond to the types of Win32 objects that support security. The GetSecurityInfo, SetSecurityInfo, GetNamedSecurityInfo, and SetNamedSecurityInfo functions use these values to indicate the type of object.

typedef enum _SE_OBJECT_TYPE

{

    SE_UNKNOWN_OBJECT_TYPE = 0,

    SE_FILE_OBJECT,

    SE_SERVICE,

    SE_PRINTER,

    SE_REGISTRY_KEY,

    SE_LMSHARE,

    SE_KERNEL_OBJECT,

    SE_WINDOW_OBJECT

} SE_OBJECT_TYPE;

Enumerator	Meaning
SE_FILE_OBJECT	Indicates a file or directory. The name string that identifies a file or directory object can be  • A relative path, such as “abc.dat” or “..\abc.dat” • An absolute path, such as “\abc.dat”, “c:\dir1\abc.dat”, or “g:\remotedir\abc.dat” • A UNC name, such as “\\machinename\sharename\abc.dat”. • A local file system root, such as “\\\\.\\c:”. Security set on a file system root does not persist when the system is restarted.
SE_SERVICE	Indicates a Windows NT service. A service object can be a local service, such as “servicename”; or a remote service, such as “\\machinename\servicename”.
SE_PRINTER	Indicates a printer. A printer object can be a local printer, such as “printername”; or a remote printer, such as “\\machinename\printername”.
SE_REGISTRY_KEY	Indicates a registry key. A registry key object can be in the local registry, such as “CLASSES_ROOT\somepath”; or in a remote registry, such as “\\machinename\CLASSES_ROOT\somepath”.  The names of registry keys must use the following literal strings to identify the predefined registry keys: “CLASSES_ROOT”, “CURRENT_USER”, “MACHINE”, and “USERS”.
SE_LMSHARE	Indicates a Windows NT network share. A share object can be local, such as “sharename”; or remote, such as “\\machinename\sharename”.
SE_KERNEL_OBJECT	Indicates a local kernel object, which can be any of the following: a process, thread, semaphore, event, mutex, file mapping, or waitable timer. Only some kernel objects can be identified by name.  Note that the GetSecurityInfo, SetSecurityInfo, GetNamedSecurityInfo, and SetNamedSecurityInfo functions do not work with the following types of kernel objects: access token, console screen buffer, mailslot, named pipe, and anonymous pipe.
SE_WINDOW_OBJECT	Indicates a window station or desktop object on the local computer.
See Also

GetSecurityInfo, SetSecurityInfo, GetNamedSecurityInfo, SetNamedSecurityInfo


SECURITY_IMPERSONATION_LEVEL

The SECURITY_IMPERSONATION_LEVEL enumeration type contains values that specify security impersonation levels. Security impersonation levels govern the degree to which a server process can act on behalf of a client process.

typedef enum _SECURITY_IMPERSONATION_LEVEL { // sil

    SecurityAnonymous,

    SecurityIdentification,

    SecurityImpersonation,

    SecurityDelegation

} SECURITY_IMPERSONATION_LEVEL;

Value	Meaning
SecurityAnonymous	The server process cannot obtain identification information about the client and it cannot impersonate the client. It is defined with no value given, and thus, by ANSI C rules, defaults to a value of 0.
SecurityIdentification	The server process can obtain information about the client, such as security identifiers and privileges, but it cannot impersonate the client. This is useful for servers that export their own objects — for example, database products that export tables and views. Using the retrieved client-security information, the server can make access-validation decisions without being able to utilize other services using the client’s security context.
SecurityImpersonation	The server process can impersonate the client’s security context on its local system. The server cannot impersonate the client on remote systems.
SecurityDelegation	Windows NT security does not support this impersonation level.
Remarks

Impersonation is the ability of a process to take on the security attributes of another process.

See Also

CreatePrivateObjectSecurity, DuplicateToken, DuplicateTokenEx, GetTokenInformation, ImpersonateSelf, OpenThreadToken


SHCONTF

The SHCONTF enumeration type defines flags used with the IShellFolder::EnumObjects and IShellFolder::SetNameOf methods.

typedef enum tagSHCONTF {

    SHCONTF_FOLDERS = 32,         // for shell browser

    SHCONTF_NONFOLDERS = 64,      // for default view

    SHCONTF_INCLUDEHIDDEN = 128,  // for hidden or system objects

} SHCONTF;

See Also

IShellFolder::EnumObjects, IShellFolder::SetNameOf


SHGNO

The SHGNO enumeration type defines flags used with the IShellFolder::GetDisplayNameOf and IShellFolder::SetNameOf methods.

typedef enum tagSHGDN {

    SHGDN_NORMAL = 0,

    SHGDN_INFOLDER = 1,

    SHGDN_FORPARSING = 0x8000,

} SHGNO;

Members

SHGDN_NORMAL

Default display name that is suitable for a file object displayed by itself, as shown in the following examples.

File system path	Corresponding display name
C:\WINDOWS\FILE.TXT	file
\\COMPUTER\SHARE	share on computer
C:\ (where drive C has the volume name My Drive)	My Drive (C)
SHGDN_INFOLDER

Display name that is suitable for a file object displayed within its respective folder, as shown in the following examples.

File system path	Corresponding display name
C:\WINDOWS\FILE.TXT	file
\\COMP\SHARE	user
C:\ (where drive C has the volume name My Drive)	My Drive (C)
SHGDN_FORPARSING

Display name that can be passed to the ParseDisplayName method of the parent folder’s IShellFolder object.

File system path	Corresponding display name
C:\WINDOWS\FILE.TXT	C:\WINDOWS\FILE.TXT
\\COMP\SHARE	\\COMP\SHARE
C:\ (where drive C has the volume name My Drive)	C:\
See Also

IShellFolder::GetDisplayNameOf, IShellFolder::SetNameOf, ParseDisplayName


SID_NAME_USE

The SID_NAME_USE enumeration type contains values that specify the type of a security identifier (SID).

typedef enum _SID_NAME_USE {

    SidTypeUser = 1,

    SidTypeGroup,

    SidTypeDomain,

    SidTypeAlias,

    SidTypeWellKnownGroup,

    SidTypeDeletedAccount,

    SidTypeInvalid,

    SidTypeUnknown

} SID_NAME_USE;

Value	Meaning
SidTypeUser	Indicates a user SID.
SidTypeGroup	Indicates a group SID.
SidTypeDomain	Indicates a domain SID.
SidTypeAlias	Indicates an alias SID.
SidTypeWellKnownGroup	Indicates an SID for a well-known group.
SidTypeDeletedAccount	Indicates an SID for a deleted account.
SidTypeInvalid	Indicates an invalid SID.
SidTypeUnknown	Indicates an unknown SID type.
See Also

LookupAccountName, LookupAccountSid


TOKEN_INFORMATION_CLASS

The TOKEN_INFORMATION_CLASS enumeration type contains values that specify the type of information being assigned to or retrieved from an access token.

typedef enum _TOKEN_INFORMATION_CLASS { // tic

    TokenUser = 1,

    TokenGroups,

    TokenPrivileges,

    TokenOwner,

    TokenPrimaryGroup,

    TokenDefaultDacl,

    TokenSource,

    TokenType,

    TokenImpersonationLevel,

    TokenStatistics

} TOKEN_INFORMATION_CLASS;

See Also

GetTokenInformation, SetTokenInformation, TOKEN_CONTROL, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


TOKEN_TYPE

The TOKEN_TYPE enumeration type contains values that differentiate between a primary token and an impersonation token.

typedef enum tagTOKEN_TYPE { // tt

    TokenPrimary = 1,

    TokenImpersonation

} TOKEN_TYPE;

See Also

GetTokenInformation, TOKEN_CONTROL, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_USER


TRUSTEE_FORM [New - Windows NT]
TRUSTEE_FORM

[New - Windows NT]

The TRUSTEE_FORM enumeration type contains values that indicate how a TRUSTEE structure identifies the trustee.

typedef enum _TRUSTEE_FORM

{

    TRUSTEE_IS_SID,

    TRUSTEE_IS_NAME,

} TRUSTEE_FORM;

Enumerator	Meaning
TRUSTEE_IS_SID	The trustee is identified by a security identifier (SID).
TRUSTEE_IS_NAME	The trustee is identified by a name.
See Also

TRUSTEE


TRUSTEE_TYPE [New - Windows NT]
TRUSTEE_TYPE

[New - Windows NT]

The TRUSTEE_TYPE enumeration type contains values that indicate the type of trustee identified by a TRUSTEE structure.

typedef enum _TRUSTEE_TYPE

{

    TRUSTEE_IS_UNKNOWN,

    TRUSTEE_IS_USER,

    TRUSTEE_IS_GROUP,

} TRUSTEE_TYPE;

Enumerator	Meaning
TRUSTEE_IS_UNKNOWN	The trustee type is unknown, but not necessarily invalid. The functions that use TRUSTEE structures do not validate the trustee type information.
TRUSTEE_IS_USER	The trustee account is a user account.
TRUSTEE_IS_GROUP	The trustee account is a group account.
See Also

TRUSTEE


Error Codes

Alphabetic listing

Numerical listing


Alphabetical List of Error Codes

EPT_S_CANT_CREATE

The endpoint mapper database could not be created.

EPT_S_CANT_PERFORM_OP

The operation cannot be performed.

EPT_S_INVALID_ENTRY

The entry is invalid.

EPT_S_NOT_REGISTERED

There are no more endpoints available from the endpoint mapper.

ERROR_ACCESS_DENIED

Access is denied.

ERROR_ACCOUNT_DISABLED

The referenced account is currently disabled and cannot be logged on to.

ERROR_ACCOUNT_EXPIRED

The user’s account has expired.

ERROR_ACCOUNT_LOCKED_OUT

The referenced account is currently locked out and may not be logged on to.

ERROR_ACCOUNT_RESTRICTION

Indicates a referenced user name and authentication information are valid, but some user account restriction has prevented successful authentication (such as time-of-day restrictions).

ERROR_ACTIVE_CONNECTIONS

Active connections still exist.

ERROR_ADAP_HDW_ERR

A network adapter hardware error occurred.

ERROR_ADDRESS_ALREADY_ASSOCIATED

The network transport endpoint already has an address associated with it.

ERROR_ADDRESS_NOT_ASSOCIATED

An address has not yet been associated with the network endpoint.

ERROR_ALIAS_EXISTS

The specified alias already exists.

ERROR_ALLOTTED_SPACE_EXCEEDED

When a block of memory is allotted for future updates, such as the memory allocated to hold discretionary access control and primary group information, successive updates may exceed the amount of memory originally allotted. Since quota may already have been charged to several processes that have handles of the object, it is not reasonable to alter the size of the allocated memory. Instead, a request that requires more memory than has been allotted must fail and the ERROR_ALLOTTED_SPACE_EXCEEDED error returned.

ERROR_ALREADY_ASSIGNED

The local device name is already in use.

ERROR_ALREADY_EXISTS

Attempt to create file that already exists.

ERROR_ALREADY_INITIALIZED

An attempt was made to perform an initialization operation when initialization has already been completed.

ERROR_ALREADY_REGISTERED

The service is already registered.

ERROR_ALREADY_RUNNING_LKG

The system is currently running with the last-known-good configuration.

ERROR_ALREADY_WAITING

The specified Printer handle is already being waited on

ERROR_APP_WRONG_OS

The specified program is not a Windows or MS-DOS program.

ERROR_ARENA_TRASHED

The storage control blocks were destroyed.

ERROR_ARITHMETIC_OVERFLOW

Arithmetic result exceeded 32-bits.

ERROR_ATOMIC_LOCKS_NOT_SUPPORTED

The file system does not support atomic changing of the lock type.

ERROR_AUTODATASEG_EXCEEDS_64k

The operating system cannot run this application program.

ERROR_BAD_ARGUMENTS

The argument string passed to DosExecPgm is incorrect.

ERROR_BAD_COMMAND

The device does not recognize the command.

ERROR_BAD_DESCRIPTOR_FORMAT

Indicates a security descriptor is not in the required format (absolute or self-relative).

ERROR_BAD_DEV_TYPE

The network resource type is incorrect.

ERROR_BAD_DEVICE

The specified device name is invalid.

ERROR_BAD_DRIVER

The specified driver is invalid.

ERROR_BAD_DRIVER_LEVEL

The system does not support the requested command.

ERROR_BAD_ENVIRONMENT

The environment is incorrect.

ERROR_BAD_EXE_FORMAT

%1 is not a valid Windows-based application.

ERROR_BAD_FORMAT

An attempt was made to load a program with an incorrect format.

ERROR_BAD_IMPERSONATION_LEVEL

A specified impersonation level is invalid. Also used to indicate a required impersonation level was not provided.

ERROR_BAD_INHERITANCE_ACL

Indicates that an attempt to build either an inherited ACL or ACE did not succeed. One of the more probable causes is the replacement of a CreatorId with an SID that didn’t fit into the ACE or ACL.

ERROR_BAD_LENGTH

The program issued a command but the command length is incorrect.

ERROR_BAD_LOGON_SESSION_STATE

The logon session is not in a state consistent with the requested operation.

ERROR_BAD_NET_NAME

The network name cannot be found.

ERROR_BAD_NET_RESP

The specified server cannot perform the requested operation.

ERROR_BAD_NETPATH

The network path was not found.

ERROR_BAD_PATHNAME

The specified path name is invalid.

ERROR_BAD_PIPE

The pipe state is invalid.

ERROR_BAD_PROFILE

The network connection profile is damaged.

ERROR_BAD_PROVIDER

The specified network provider name is invalid.

ERROR_BAD_REM_ADAP

The remote adapter is not compatible.

ERROR_BAD_THREADID_ADDR

The address for the thread ID is incorrect.

ERROR_BAD_TOKEN_TYPE

The type of token object is inappropriate for its attempted use.

ERROR_BAD_UNIT

The system cannot find the specified device.

ERROR_BAD_USERNAME

The specified user name is invalid.

ERROR_BAD_VALIDATION_CLASS

The requested validation information class is invalid.

ERROR_BADDB

The configuration registry database is damaged.

ERROR_BADKEY

The configuration registry key is invalid.

ERROR_BEGINNING_OF_MEDIA

The beginning of the tape or partition was encountered.

ERROR_BOOT_ALREADY_ACCEPTED

The current boot has already been accepted for use as the last-known-good control set.

ERROR_BROKEN_PIPE

The pipe was ended.

ERROR_BUFFER_OVERFLOW

The file name is too long.

ERROR_BUS_RESET

The I/O bus was reset.

ERROR_BUSY

The requested resource is in use.

ERROR_BUSY_DRIVE

The system cannot perform a JOIN or SUBST at this time.

ERROR_CALL_NOT_IMPLEMENTED

The Application Program Interface (API) entered will only work in Windows/NT mode.

ERROR_CAN_NOT_COMPLETE

Cannot complete function for some reason.

ERROR_CAN_NOT_DEL_LOCAL_WINS

The local WINS can not be deleted.

ERROR_CANCEL_VIOLATION

A lock request was not outstanding for the supplied cancel region.

ERROR_CANCELLED

The operation was cancelled by the user.

ERROR_CANNOT_COPY

The Copy API cannot be used.

ERROR_CANNOT_FIND_WND_CLASS

Cannot find window class.

ERROR_CANNOT_IMPERSONATE

Indicates that an attempt was made to impersonate via a named pipe was not yet read from.

ERROR_CANNOT_MAKE

The directory or file cannot be created.

ERROR_CANNOT_OPEN_PROFILE

Unable to open the network connection profile.

ERROR_CANT_ACCESS_DOMAIN_INFO

Indicates a domain controller could not be contacted or that objects within the domain are protected and necessary information could not be retrieved.

ERROR_CANT_DISABLE_MANDATORY

A mandatory group cannot be disabled.

ERROR_CANT_OPEN_ANONYMOUS

An attempt was made to open an anonymous level token. Anonymous tokens cannot be opened.

ERROR_CANTOPEN

The configuration registry key cannot be opened.

ERROR_CANTREAD

The configuration registry key cannot be read.

ERROR_CANTWRITE

The configuration registry key cannot be written.

ERROR_CHILD_MUST_BE_VOLATILE

An attempt was made to create a stable subkey under a volatile parent key.

ERROR_CHILD_NOT_COMPLETE

The %1 application cannot be run in Windows mode.

ERROR_CHILD_WINDOW_MENU

Child windows can’t have menus.

ERROR_CIRCULAR_DEPENDENCY

Circular service dependency was specified.

ERROR_CLASS_ALREADY_EXISTS

Class already exists.

ERROR_CLASS_DOES_NOT_EXIST

Class does not exist.

ERROR_CLASS_HAS_WINDOWS

Class still has open windows.

ERROR_CLIPBOARD_NOT_OPEN

Thread doesn’t have clipboard open.

ERROR_CLIPPING_NOT_SUPPORTED

The requested clipping operation is not supported.

ERROR_COMMITMENT_LIMIT

The paging file is too small for this operation to complete.

ERROR_CONNECTION_ABORTED

The network connection was aborted by the local system.

ERROR_CONNECTION_ACTIVE

An invalid operation was attempted on an active network connection.

ERROR_CONNECTION_COUNT_LIMIT

A connection to the server could not be made because the limit on the number of concurrent connections for this account has been reached.

ERROR_CONNECTION_INVALID

An operation was attempted on a non-existent network connection.

ERROR_CONNECTION_REFUSED

The remote system refused the network connection.

ERROR_CONNECTION_UNAVAIL

The device is not currently connected but is a remembered connection.

ERROR_CONTINUE

Return that wants caller to continue with work in progress.

ERROR_CONTROL_ID_NOT_FOUND

Control ID not found.

ERROR_COUNTER_TIMEOUT

A serial I/O operation completed because the time-out period expired. (The IOCTL_SERIAL_XOFF_COUNTER did not reach zero.)

ERROR_CRC

Data error (cyclic redundancy check).

ERROR_CURRENT_DIRECTORY

The directory cannot be removed.

ERROR_DATABASE_DOES_NOT_EXIST

The database specified does not exist.

ERROR_DC_NOT_FOUND

Invalid HDC passed to ReleaseDC.

ERROR_DDE_FAIL

An error occurred in sending the command to the application.

ERROR_DEPENDENT_SERVICES_RUNNING

A stop control has been sent to a service which other running services are dependent on.

ERROR_DESTROY_OBJECT_OF_OTHER_THREAD

Cannot destroy object created by another thread.

ERROR_DEV_NOT_EXIST

The specified network resource is no longer available.

ERROR_DEVICE_ALREADY_REMEMBERED

An attempt was made to remember a device that was previously remembered.

ERROR_DEVICE_IN_USE

The device is in use by an active process and cannot be disconnected.

ERROR_DEVICE_NOT_PARTITIONED

Tape partition information could not be found when loading a tape.

ERROR_DIFFERENT_SERVICE_ACCOUNT

The account specified for this service is different from the account specified for other services running in the same process.

ERROR_DIR_NOT_EMPTY

The directory is not empty.

ERROR_DIR_NOT_ROOT

The directory is not a subdirectory of the root directory.

ERROR_DIRECT_ACCESS_HANDLE

Attempt to use a file handle to an open disk partition for an operation other than raw disk I/O.

ERROR_DIRECTORY

The directory name is invalid.

ERROR_DISCARDED

The segment is already discarded and cannot be locked.

ERROR_DISK_CHANGE

Program stopped because alternate disk was not inserted.

ERROR_DISK_CORRUPT

The disk structure is damaged and nonreadable.

ERROR_DISK_FULL

There is not enough space on the disk.

ERROR_DISK_OPERATION_FAILED

While accessing the hard disk, a disk operation failed even after retries.

ERROR_DISK_RECALIBRATE_FAILED

While accessing the hard disk, a recalibrate operation failed, even after retries.

ERROR_DISK_RESET_FAILED

While accessing the hard disk, a disk controller reset was needed, but even that failed.

ERROR_DLL_INIT_FAILED

A DLL initialization routine failed.

ERROR_DLL_NOT_FOUND

One of the library files needed to run this application cannot be found.

ERROR_DOMAIN_CONTROLLER_NOT_FOUND

Could not find the domain controller for this domain.

ERROR_DOMAIN_EXISTS

The specified domain already exists.

ERROR_DOMAIN_LIMIT_EXCEEDED

An attempt to exceed the limit on the number of domains per server for this release.

ERROR_DOMAIN_TRUST_INCONSISTENT

The name or security ID (SID) of the domain specified is inconsistent with the trust information for that domain.

ERROR_DRIVE_LOCKED

The disk is in use or locked by another process.

ERROR_DUP_DOMAINNAME

The workgroup or domain name is already in use by another computer on the network.

ERROR_DUP_NAME

A duplicate name exists on the network.

ERROR_DUPLICATE_SERVICE_NAME

The name is already in use as either a service name or a service display name.

ERROR_DYNLINK_FROM_INVALID_RING

The operating system cannot run this application program.

ERROR_EA_ACCESS_DENIED

Access to the EA is denied.

ERROR_EA_FILE_CORRUPT

The EA file on the mounted file system is damaged.

ERROR_EA_LIST_INCONSISTENT

The EAs are inconsistent.

ERROR_EA_TABLE_FULL

The EA table in the EA file on the mounted file system is full.

ERROR_EAS_DIDNT_FIT

The EAs did not fit in the buffer.

ERROR_EAS_NOT_SUPPORTED

The mounted file system does not support extended attributes.

ERROR_END_OF_MEDIA

The physical end of the tape has been reached.

ERROR_ENVVAR_NOT_FOUND

The system could not find the environment option entered.

ERROR_EOM_OVERFLOW

Physical end of tape encountered.

ERROR_EVENTLOG_CANT_START

No event log file could be opened, so the event logging service did not start.

ERROR_EVENTLOG_FILE_CHANGED

The event log file has changed between reads.

ERROR_EVENTLOG_FILE_CORRUPT

One of the Eventlog logfiles is damaged.

ERROR_EXCEPTION_IN_SERVICE

An exception occurred in the service when handling the control request.

ERROR_EXCL_SEM_ALREADY_OWNED

The exclusive semaphore is owned by another process.

ERROR_EXE_MARKED_INVALID

The operating system cannot run %1.

ERROR_EXTENDED_ERROR

An extended error has occurred.

ERROR_FAIL_I24

Fail on INT 24.

ERROR_FAILED_SERVICE_CONTROLLER_CONNECT

The service process could not connect to the service controller.

ERROR_FILE_CORRUPT

The file or directory is damaged and nonreadable.

ERROR_FILE_EXISTS

The file exists.

ERROR_FILE_INVALID

The volume for a file was externally altered and the opened file is no longer valid.

ERROR_FILE_NOT_FOUND

The system cannot find the file specified.

ERROR_FILEMARK_DETECTED

A tape access reached a filemark.

ERROR_FILENAME_EXCED_RANGE

The file name or extension is too long.

ERROR_FLOPPY_BAD_REGISTERS

The floppy disk controller returned inconsistent results in its registers.

ERROR_FLOPPY_ID_MARK_NOT_FOUND

No ID address mark was found on the floppy disk.

ERROR_FLOPPY_WRONG_CYLINDER

Mismatch between the floppy disk sector ID field and the floppy disk controller track address.

ERROR_FLOPPY_UNKNOWN_ERROR

The floppy disk controller reported an error that is not recognized by the floppy disk driver.

ERROR_FULL_BACKUP

The backup failed. Check the directory that you are backing the database to.

ERROR_FULLSCREEN_MODE

The requested operation cannot be performed in full-screen mode.

ERROR_GEN_FAILURE

A device attached to the system is not functioning.

ERROR_GENERIC_NOT_MAPPED

Indicates generic access types were contained in an access mask that should already be mapped to non-generic access types.

ERROR_GLOBAL_ONLY_HOOK

This hook can only be set globally.

ERROR_GRACEFUL_DISCONNECT

The network connection was gracefully closed.

ERROR_GROUP_EXISTS

The specified group already exists.

ERROR_HANDLE_DISK_FULL

The disk is full.

ERROR_HANDLE_EOF

Reached End Of File.

ERROR_HOOK_NEEDS_HMOD

Cannot set non-local hook without an module handle.

ERROR_HOOK_NOT_INSTALLED

Hook is not installed.

ERROR_HOOK_TYPE_NOT_ALLOWED

Hook type not allowed.

ERROR_HOST_UNREACHABLE

The remote system is not reachable by the transport.

ERROR_HOTKEY_ALREADY_REGISTERED

Hotkey is already registered.

ERROR_HOTKEY_NOT_REGISTERED

Hotkey is not registered.

ERROR_HWNDS_HAVE_DIFFERENT_PARENT

All DeferWindowPos HWNDs must have same parent.

ERROR_ILL_FORMED_PASSWORD

When trying to update a password, this return status indicates the value provided for the new password contains values not allowed in passwords.

ERROR_INC_BACKUP

The backup failed. Was a full backup done before ?

ERROR_INCORRECT_ADDRESS

The network address could not be used for the operation requested.

ERROR_INFLOOP_IN_RELOC_CHAIN

The operating system cannot run %1.

ERROR_INSUFFICIENT_BUFFER

The data area passed to a system call is too small.

ERROR_INTERNAL_DB_CORRUPTION

This error indicates the requested operation cannot be completed due to a catastrophic media failure or on-disk data structure corruption.

ERROR_INTERNAL_DB_ERROR

The Local Security Authority (LSA) database contains in internal inconsistency.

ERROR_INTERNAL_ERROR

This error indicates the SAM server has encounterred an internal consistency error in its database. This catastrophic failure prevents further operation of SAM.

ERROR_INVALID_ACCEL_HANDLE

Invalid accelerator-table handle.

ERROR_INVALID_ACCESS

The access code is invalid.

ERROR_INVALID_ACCOUNT_NAME

The name provided is not a properly formed account name.

ERROR_INVALID_ACL

Indicates the ACL structure is not valid.

ERROR_INVALID_ADDRESS

Attempt to access invalid address.

ERROR_INVALID_AT_INTERRUPT_TIME

Cannot request exclusive semaphores at interrupt time.

ERROR_INVALID_BLOCK

The storage control block address is invalid.

ERROR_INVALID_BLOCK_LENGTH

When accessing a new tape of a multivolume partition, the current block size is incorrect.

ERROR_INVALID_CATEGORY

The IOCTL call made by the application program is incorrect.

ERROR_INVALID_COMBOBOX_MESSAGE

Invalid Message, combo box doesn’t have an edit control.

ERROR_INVALID_COMPUTERNAME

The format of the specified computer name is invalid.

ERROR_INVALID_CURSOR_HANDLE

The cursor handle is invalid.

ERROR_INVALID_DATA

The data is invalid.

ERROR_INVALID_DATATYPE

The specified datatype is invalid.

ERROR_INVALID_DLL

One of the library files needed to run this application is damaged.

ERROR_INVALID_DOMAINNAME

The format of the specified domain name is invalid.

ERROR_INVALID_DOMAIN_ROLE

Indicates the requested operation cannot be completed with the domain in its present role.

ERROR_INVALID_DOMAIN_STATE

Indicates the domain is in the wrong state to perform the desired operation.

ERROR_INVALID_DRIVE

The system cannot find the specified drive.

ERROR_INVALID_DWP_HANDLE

The DeferWindowPos handle is invalid.

ERROR_INVALID_EA_HANDLE

The specified EA handle is invalid.

ERROR_INVALID_EA_NAME

The specified EA name is invalid.

ERROR_INVALID_EDIT_HEIGHT

Height must be less than 256.

ERROR_INVALID_ENVIRONMENT

The Environment specified is invalid.

ERROR_INVALID_EVENT_COUNT

The number of specified semaphore events is incorrect.

ERROR_INVALID_EVENTNAME

The format of the specified event name is invalid.

ERROR_INVALID_EXE_SIGNATURE

%1 cannot be run in Windows/NT mode.

ERROR_INVALID_FILTER_PROC

The filter proc is invalid.

ERROR_INVALID_FLAG_NUMBER

The flag passed is incorrect.

ERROR_INVALID_FLAGS

The flags are invalid.

ERROR_INVALID_FUNCTION

The function is incorrect.

ERROR_INVALID_GROUP_ATTRIBUTES

The specified attributes are invalid, or incompatible with the attributes for the group as a whole.

ERROR_INVALID_GROUPNAME

The format of the specified group name is invalid.

ERROR_INVALID_GW_COMMAND

The GW_* command is invalid.

ERROR_INVALID_FORM_NAME

The specified Form name is invalid.

ERROR_INVALID_FORM_SIZE

The specified Form size is invalid

ERROR_INVALID_HANDLE

The internal file identifier is incorrect.

ERROR_INVALID_HOOK_FILTER

The hook filter type is invalid.

ERROR_INVALID_HOOK_HANDLE

The hook handle is invalid.

ERROR_INVALID_ICON_HANDLE

The icon handle is invalid.

ERROR_INVALID_ID_AUTHORITY

The value provided is an invalid value for an identifier authority.

ERROR_INVALID_INDEX

The index is invalid.

ERROR_INVALID_KEYBOARD_HANDLE

Invalid keyboard layout handle.

ERROR_INVALID_LB_MESSAGE

The message for single-selection list box is invalid.

ERROR_INVALID_LEVEL

The system call level is incorrect.

ERROR_INVALID_LIST_FORMAT

The list is not correct.

ERROR_INVALID_LOGON_HOURS

The user account has time restrictions and cannot be logged onto at this time.

ERROR_INVALID_LOGON_TYPE

Indicates an invalid value has been provided for LogonType has been requested.

ERROR_INVALID_MEMBER

A new member could not be added to an alias because the member has the wrong account type.

ERROR_INVALID_MENU_HANDLE

The menu handle is invalid.

ERROR_INVALID_MESSAGE

Window can’t handle sent message.

ERROR_INVALID_MESSAGEDEST

The format of the specified message destination is invalid.

ERROR_INVALID_MESSAGENAME

The format of the specified message name is invalid.

ERROR_INVALID_MINALLOCSIZE

The operating system cannot run %1.

ERROR_INVALID_MODULETYPE

The operating system cannot run %1.

ERROR_INVALID_MSGBOX_STYLE

The message box style is invalid.

ERROR_INVALID_NAME

The file name, directory name, or volume label is syntactically incorrect.

ERROR_INVALID_NETNAME

The format of the specified network name is invalid.

ERROR_INVALID_ORDINAL

The operating system cannot run %1.

ERROR_INVALID_OWNER

Indicates a particular Security ID cannot be assigned as the owner of an object.

ERROR_INVALID_PARAMETER

The parameter is incorrect.

ERROR_INVALID_PASSWORD

The specified network password is incorrect.

ERROR_INVALID_PASSWORDNAME

The format of the specified password is invalid.

ERROR_INVALID_PIXEL_FORMAT

The pixel format is invalid.

ERROR_INVALID_PRIMARY_GROUP

Indicates a particular Security ID cannot be assigned as the primary group of an object.

ERROR_INVALID_PRINT_MONITOR

The specified print monitor does not have the required functions.

ERROR_INVALID_PRINTER_COMMAND

The printer command is invalid.

ERROR_INVALID_PRINTER_NAME

The printer name is invalid.

ERROR_INVALID_PRINTER_STATE

The state of the Printer is invalid

ERROR_INVALID_PRIORITY

The specified priority is invalid.

ERROR_INVALID_SCROLLBAR_RANGE

Scrollbar range greater than 0x7FFF.

ERROR_INVALID_SECURITY_DESCR

Indicates the SECURITY_DESCRIPTOR structure is invalid.

ERROR_INVALID_SEGDPL

The operating system cannot run %1.

ERROR_INVALID_SEGMENT_NUMBER

The system detected a segment number that is incorrect.

ERROR_INVALID_SEPARATOR_FILE

The specified separator file is invalid.

ERROR_INVALID_SERVER_STATE

Indicates the Sam Server was in the wrong state to perform the desired operation.

ERROR_INVALID_SERVICE_ACCOUNT

The account name is invalid or does not exist.

ERROR_INVALID_SERVICE_CONTROL

The requested control is not valid for this service

ERROR_INVALID_SERVICE_LOCK

The specified service database lock is invalid.

ERROR_INVALID_SERVICENAME

The format of the specified service name is invalid.

ERROR_INVALID_SHARENAME

The format of the specified share name is invalid.

ERROR_INVALID_SHOWWIN_COMMAND

The ShowWindow command is invalid.

ERROR_INVALID_SID

Indicates the SID structure is invalid.

ERROR_INVALID_SIGNAL_NUMBER

The signal being posted is incorrect.

ERROR_INVALID_SPI_VALUE

The SPI_* parameter is invalid.

ERROR_INVALID_STACKSEG

The operating system cannot run %1.

ERROR_INVALID_STARTING_CODESEG

The operating system cannot run %1.

ERROR_INVALID_SUB_AUTHORITY

Indicates the sub-authority value is invalid for the particular use.

ERROR_INVALID_TARGET_HANDLE

The target internal file identifier is incorrect.

ERROR_INVALID_THREAD_ID

The thread ID is invalid.

ERROR_INVALID_TIME

The specified time is invalid.

ERROR_INVALID_USER_BUFFER

The supplied user buffer is invalid for the requested operation.

ERROR_INVALID_VERIFY_SWITCH

The verify-on-write switch parameter value is incorrect.

ERROR_INVALID_WINDOW_HANDLE

The window handle invalid.

ERROR_INVALID_WINDOW_STYLE

The window style or class attribute is invalid for this operation.

ERROR_INVALID_WORKSTATION

The user account is restricted and cannot be used to log on from the source workstation.

ERROR_IO_DEVICE

The request could not be performed because of an I/O device error.

ERROR_IO_INCOMPLETE

Overlapped IO event not in signaled state.

ERROR_IO_PENDING

Overlapped IO operation in progress.

ERROR_IOPL_NOT_ENABLED

The operating system is not presently configured to run this application.

ERROR_IRQ_BUSY

Unable to open a device that was sharing an interrupt request (IRQ) with other devices. At least one other device that uses that IRQ was already opened.

ERROR_IS_JOIN_PATH

Not enough resources are available to process this command.

ERROR_IS_JOIN_TARGET

A JOIN or SUBST command cannot be used for a drive that contains previously joined drives.

ERROR_IS_JOINED

An attempt was made to use a JOIN or SUBST command on a drive that is already joined.

ERROR_IS_SUBST_PATH

The path specified is being used in a substitute.

ERROR_IS_SUBST_TARGET

An attempt was made to join or substitute a drive for which a directory on the drive is the target of a previous substitute.

ERROR_IS_SUBSTED

An attempt was made to use a JOIN or SUBST command on a drive already substituted.

ERROR_ITERATED_DATA_EXCEEDS_64k

The operating system cannot run %1.

ERROR_JOIN_TO_JOIN

The system tried to join a drive to a directory on a joined drive.

ERROR_JOIN_TO_SUBST

The system tried to join a drive to a directory on a substituted drive.

ERROR_JOURNAL_HOOK_SET

The journal hook is already installed.

ERROR_KEY_DELETED

Illegal operation attempted on a registry key that has been marked for deletion.

ERROR_KEY_HAS_CHILDREN

An attempt was made to create a symbolic link in a registry key that already has subkeys or values.

ERROR_LABEL_TOO_LONG

The volume label entered exceeds the 11 character limit. The first 11 characters were written to disk. Any characters that exceeded the 11 character limit were automatically deleted.

ERROR_LAST_ADMIN

Indicates the requested operation would disable or delete the last remaining administration account. This is not allowed to prevent creating a situation where the system will not be administrable.

ERROR_LB_WITHOUT_TABSTOPS

This list box doesn’t support tab stops.

ERROR_LICENSE_QUOTA_EXCEEDED

The service being accessed is licensed for a particular number of connections. No more connections can be made to the service at this time because there are already as many connections as the service can accept.

ERROR_LISTBOX_ID_NOT_FOUND

List box ID not found.

ERROR_LM_CROSS_ENCRYPTION_REQUIRED

An attempt was made to change a user password in the security account manager without providing the required LM cross-encrypted password.

ERROR_LOCAL_USER_SESSION_KEY

A user session key was requested for a local RPC connection. The session key returned is a constant value and not unique to this connection.

ERROR_LOCK_FAILED

Attempt to lock a region of a file failed.

ERROR_LOCK_VIOLATION

The process cannot access the file because another process has locked a portion of the file.

ERROR_LOCKED

The segment is locked and cannot be reallocated.

ERROR_LOG_FILE_FULL

The event log file is full.

ERROR_LOGIN_TIME_RESTRICTION

Attempting to login during an unauthorized time of day for this account.

ERROR_LOGIN_WKSTA_RESTRICTION

The account is not authorized to login from this station.

ERROR_LOGON_FAILURE

The attempted logon is invalid. This is due to either a bad user name or authentication information.

ERROR_LOGON_NOT_GRANTED

A requested type of logon, such as Interactive, Network, or Service, is not granted by the target system’s local security policy. The system administrator can grant the required form of logon.

ERROR_LOGON_SESSION_COLLISION

The logon session ID is already in use.

ERROR_LOGON_SESSION_EXISTS

An attempt was made to start a new session manager or LSA logon session with an ID already in use.

ERROR_LOGON_TYPE_NOT_GRANTED

A user has requested a type of logon, such as interactive or network, that was not granted. An administrator has control over who may logon interactively and through the network.

ERROR_LUIDS_EXHAUSTED

Indicates there are no more LUID to allocate.

ERROR_MAPPED_ALIGNMENT

The base address or the file offset specified does not have the proper alignment.

ERROR_MAX_THRDS_REACHED

No more threads can be created in the system.

ERROR_MEDIA_CHANGED

Media in drive may have changed.

ERROR_MEMBER_IN_ALIAS

The specified account name is not a member of the alias.

ERROR_MEMBER_IN_GROUP

The specified user account is already in the specified group account. Also used to indicate a group can not be deleted because it contains a member.

ERROR_MEMBER_NOT_IN_ALIAS

The specified account name is not a member of the alias.

ERROR_MEMBER_NOT_IN_GROUP

The specified user account is not a member of the specified group account.

ERROR_MEMBERS_PRIMARY_GROUP

Indicates a member cannot be removed from a group because the group is currently the member’s primary group.

ERROR_MENU_ITEM_NOT_FOUND

A menu item was not found.

ERROR_META_EXPANSION_TOO_LONG

The global filename characters * or ? are entered incorrectly, or too many global filename characters are specified.

ERROR_METAFILE_NOT_SUPPORTED

The requested metafile operation is not supported.

ERROR_MOD_NOT_FOUND

The specified module cannot be found.

ERROR_MORE_DATA

More data is available.

ERROR_MORE_WRITES

A serial I/O operation was completed by another write to the serial port. (The IOCTL_SERIAL_XOFF_COUNTER reached zero.)

ERROR_MR_MID_NOT_FOUND

The system cannot find message for message number 0x%1 in message file for %2.

ERROR_NEGATIVE_SEEK

An attempt was made to move the file pointer before the beginning of the file.

ERROR_NESTING_NOT_ALLOWED

Can’t nest calls to LoadModule.

ERROR_NETLOGON_NOT_STARTED

An attempt was made to logon, but the network logon service was not started.

ERROR_NET_WRITE_FAULT

A write fault occurred on the network.

ERROR_NETNAME_DELETED

The specified network name is no longer available.

ERROR_NETWORK_ACCESS_DENIED

Network access is denied.

ERROR_NETWORK_BUSY

The network is busy.

ERROR_NETWORK_UNREACHABLE

The remote network is not reachable by the transport.

ERROR_NO_ASSOCIATION

No application is associated with the specified file for this operation.

ERROR_NO_BROWSER_SERVERS_FOUND

The list of servers for this workgroup is not currently available

ERROR_NO_DATA

Pipe close in progress.

ERROR_NO_DATA_DETECTED

During a tape access, the end of the data marker was reached.

ERROR_NO_IMPERSONATION_TOKEN

An attempt was made to operate on an impersonation token by a thread was not currently impersonating a client.

ERROR_NO_INHERITANCE

Indicates an ACL contains no inheritable components.

ERROR_NO_LOG_SPACE

System could not allocate required space in a registry log.

ERROR_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT

The account used is an interdomain trust account. Use your normal user account or remote user account to access this server.

ERROR_NOLOGON_SERVER_TRUST_ACCOUNT

The account used is an server trust account. Use your normal user account or remote user account to access this server.

ERROR_NO_LOGON_SERVERS

There are currently no logon servers available to service the logon request.

ERROR_NOLOGON_WORKSTATION_TRUST_ACCOUNT

The account used is a workstation trust account. Use your normal user account or remote user account to access this server.

ERROR_NO_MEDIA_IN_DRIVE

Tape query failed because of no media in drive.

ERROR_NO_MORE_DEVICES

No more local devices.

ERROR_NO_MORE_FILES

There are no more files.

ERROR_NO_MORE_ITEMS

No more data is available.

ERROR_NO_MORE_SEARCH_HANDLES

No more internal file identifiers available.

ERROR_NO_NET_OR_BAD_PATH

No network provider accepted the given network path.

ERROR_NO_NETWORK

The network is not present or not started.

ERROR_NO_PROC_SLOTS

The system cannot start another process at this time.

ERROR_NO_QUOTAS_FOR_ACCOUNT

No system quota limits are specifically set for this account.

ERROR_NO_SCROLLBARS

Window does not have scroll bars.

ERROR_NO_SECURITY_ON_OBJECT

Indicates an attempt was made to operate on the security of an object that does not have security associated with it.

ERROR_NO_SHUTDOWN_IN_PROGRESS

An attempt to abort the shutdown of the system failed because no shutdown was in progress.

ERROR_NO_SIGNAL_SENT

No process in the command subtree has a signal handler.

ERROR_NO_SPOOL_SPACE

Space to store the file waiting to be printed is not available on the server.

ERROR_NO_SUCH_ALIAS

The specified alias does not exist.

ERROR_NO_SUCH_DOMAIN

The specified domain does not exist.

ERROR_NO_SUCH_GROUP

The specified group does not exist.

ERROR_NO_SUCH_LOGON_SESSION

A specified logon session does not exist. It may already have been terminated.

ERROR_NO_SUCH_MEMBER

A new member cannot be added to an alias because the member does not exist.

ERROR_NO_SUCH_PACKAGE

A specified authentication package is unknown.

ERROR_NO_SUCH_PRIVILEGE

A specified privilege does not exist.

ERROR_NO_SUCH_USER

The specified user does not exist.

ERROR_NO_SYSTEM_MENU

Window does not have system menu.

ERROR_NO_SYSTEM_RESOURCES

Insufficient system resources exist to complete the requested service.

ERROR_NO_TOKEN

An attempt was made to reference a token that does not exist.

ERROR_NO_TRUST_LSA_SECRET

The workstation does not have a trust secret.

ERROR_NO_TRUST_SAM_ACCOUNT

The domain controller does not have an account for this workstation.

ERROR_NO_UNICODE_TRANSLATION

No mapping for the Unicode character exists in the target multi-byte code page.

ERROR_NO_USER_SESSION_KEY

There is no user session key for the specified logon session.

ERROR_NO_VOLUME_LABEL

The disk has no volume label.

ERROR_NO_WILDCARD_CHARACTERS

No wildcard characters found.

ERROR_NOACCESS

Invalid access to memory location.

ERROR_NON_MDICHILD_WINDOW

DefMDIChildProc called with a non-MDI child window.

ERROR_NONE_MAPPED

None of the information to be mapped has been translated.

ERROR_NONPAGED_SYSTEM_RESOURCES

Insufficient system resources exist to complete the requested service.

ERROR_NOT_ALL_ASSIGNED

Indicates not all privileges referenced are assigned to the caller. This allows, for example, all privileges to be disabled without having to know exactly which privileges are assigned.

ERROR_NOT_AUTHENTICATED

The operation being requested was not performed because the user has not been authenticated.

ERROR_NOT_CHILD_WINDOW

Window is not a child window.

ERROR_NOT_CONNECTED

This network connection does not exist.

ERROR_NOT_CONTAINER

Cannot enumerate a non-container.

ERROR_NOT_DOS_DISK

The specified disk cannot be accessed.

ERROR_NOT_ENOUGH_MEMORY

Not enough storage is available to process this command.

ERROR_NOT_ENOUGH_QUOTA

Not enough quota is available to process this command.

ERROR_NOT_ENOUGH_SERVER_MEMORY

Not enough server storage is available to process this command.

ERROR_NOT_JOINED

The system attempted to delete the JOIN of a drive not previously joined.

ERROR_NOT_LOCKED

The segment is already unlocked.

ERROR_NOT_LOGGED_ON

The operation being requested was not performed because the user has not logged on to the network.

ERROR_NOT_LOGON_PROCESS

The requested action is restricted for use by logon processes only. The calling process has not registered as a logon process.

ERROR_NOT_OWNER

Attempt to release mutex not owned by caller.

ERROR_NOT_READY

The drive is not ready.

ERROR_NOT_REGISTRY_FILE

The system attempted to load or restore a file into the registry, and the specified file is not in the format of a registry file.

ERROR_NOT_SAME_DEVICE

The system cannot move the file to a different disk drive.

ERROR_NOT_SUBSTED

The system attempted to delete the substitution of a drive not previously substituted.

ERROR_NOT_SUPPORTED

The network request is not supported.

ERROR_NOTIFY_ENUM_DIR

This indicates that a notify change request is being completed and the information is not being returned in the caller’s buffer. The caller now needs to enumerate the files to find the changes.

ERROR_NT_CROSS_ENCRYPTION_REQUIRED

An attempt was made to change a user password in the security account manager without providing the necessary NT cross-encrypted password.

ERROR_NULL_LM_PASSWORD

The Windows NT password is too complex to be converted to a Windows-networking password. The Windows-networking password returned is a NULL string.

ERROR_OLD_WIN_VERSION

The specified program requires a newer version of Windows.

ERROR_OPEN_FAILED

The system cannot open the specified device or file.

ERROR_OPEN_FILES

There are open files or requests pending on this connection.

ERROR_OPERATION_ABORTED

The I/O operation was aborted due to either thread exit or application request.

ERROR_OUT_OF_PAPER

The printer is out of paper.

ERROR_OUT_OF_STRUCTURES

Storage to process this request is not available.

ERROR_OUTOFMEMORY

Not enough storage is available to complete this operation.

ERROR_PAGED_SYSTEM_RESOURCES

Insufficient system resources exist to complete the requested service.

ERROR_PAGEFILE_QUOTA

Insufficient quota to complete the requested service.

ERROR_PARTIAL_COPY

Only part of a Read/WriteProcessMemory request was completed.

ERROR_PARTITION_FAILURE

Tape could not be partitioned.

ERROR_PASSWORD_EXPIRED

The user account’s password has expired.

ERROR_PASSWORD_MUST_CHANGE

The user must change his password before he logs on the first time.

ERROR_PASSWORD_RESTRICTION

When trying to update a password, this status indicates that some password update rule was violated. For example, the password may not meet length criteria.

ERROR_PATH_BUSY

The specified path cannot be used at this time.

ERROR_PATH_NOT_FOUND

The system cannot find the specified path.

ERROR_PIPE_BUSY

All pipe instances busy.

ERROR_PIPE_CONNECTED

There is a process on other end of the pipe.

ERROR_PIPE_LISTENING

Waiting for a process to open the other end of the pipe.

ERROR_PIPE_NOT_CONNECTED

No process on other end of pipe.

ERROR_POPUP_ALREADY_ACTIVE

Pop-up menu already active.

ERROR_PORT_UNREACHABLE

No service is operating at the destination network endpoint on the remote system.

ERROR_POSSIBLE_DEADLOCK

A potential deadlock condition has been detected.

ERROR_PRINT_CANCELLED

File waiting to be printed was deleted.

ERROR_PRINT_MONITOR_ALREADY_INSTALLED

The specified print monitor has already been installed.

ERROR_PRINT_MONITOR_IN_USE

The specified print monitor is currently in use.

ERROR_PRINT_PROCESSOR_ALREADY_INSTALLED

The specified print processor has already been installed.

ERROR_PRINTER_ALREADY_EXISTS

The printer already exists.

ERROR_PRINTER_DELETED

The specified Printer has been deleted

ERROR_PRINTER_DRIVER_ALREADY_INSTALLED

The specified printer driver is already installed.

ERROR_PRINTER_DRIVER_IN_USE

The specified printer driver is currently in use.

ERROR_PRINTER_HAS_JOBS_QUEUED

The requested operation is not allowed when there are jobs queued to the printer.

ERROR_PRINTQ_FULL

The printer queue is full.

ERROR_PRIVATE_DIALOG_INDEX

Using private DIALOG window words.

ERROR_PRIVILEGE_NOT_HELD

A required privilege is not held by the client.

ERROR_PROC_NOT_FOUND

The specified procedure could not be found.

ERROR_PROCESS_ABORTED

The process terminated unexpectedly.

ERROR_PROTOCOL_UNREACHABLE

The remote system does not support the transport protocol.

ERROR_READ_FAULT

The system cannot read from the specified device.

ERROR_REC_NON_EXISTENT

The name does not exist in the WINS database.

ERROR_REDIR_PAUSED

The specified printer or disk device has been paused.

ERROR_REDIRECTOR_HAS_OPEN_HANDLES

The redirector is in use and cannot be unloaded.

ERROR_REGISTRY_CORRUPT

The registry is damaged. The structure of one of the files that contains registry data is damaged, or the system’s in memory image of the file is damaged, or the file could not be recovered because its alternate copy or log was absent or damaged.

ERROR_REGISTRY_IO_FAILED

The registry initiated an I/O operation that had an unrecoverable failure. The registry could not read in, or write out, or flush, one of the files that contain the system’s image of the registry.

ERROR_REGISTRY_RECOVERED

One of the files containing the system’s registry data had to be recovered by use of a log or alternate copy. The recovery succeeded.

ERROR_RELOC_CHAIN_XEEDS_SEGLIM

The operating system cannot run %1.

ERROR_REM_NOT_LIST

The remote computer is not available.

ERROR_REMOTE_SESSION_LIMIT_EXCEEDED

An attempt was made to establish a session to a LAN Manager server, but there are already too many sessions established to that server.

ERROR_REQ_NOT_ACCEP

The network request was not accepted.

ERROR_REQUEST_ABORTED

The request was aborted.

ERROR_RESOURCE_DATA_NOT_FOUND

The specified image file did not contain a resource section.

ERROR_RESOURCE_LANG_NOT_FOUND

The specified resource language ID cannot be found in the image file.

ERROR_RESOURCE_NAME_NOT_FOUND

The specified resource name can not be found in the image file.

ERROR_RESOURCE_TYPE_NOT_FOUND

The specified resource type can not be found in the image file.

ERROR_RETRY

The operation could not be completed.  A retry should be performed.

ERROR_REVISION_MISMATCH

Indicates two revision levels are incompatible.

ERROR_RING2_STACK_IN_USE

The ring 2 stack is in use.

ERROR_RING2SEG_MUST_BE_MOVABLE

The code segment cannot be greater than or equal to 64KB.

ERROR_RMODE_APP

The specified program was written for an older version of Windows.

ERROR_RPL_NOT_ALLOWED

Replication with a non-configured partner is not allowed.

ERROR_RXACT_COMMIT_FAILURE

Indicates an error occurred during a registry transaction commit. The database has been left in an unknown state. The state of the registry transaction is left as COMMITTING. This status value is returned by the runtime library (RTL) registry transaction package (RXact).

ERROR_RXACT_INVALID_STATE

Indicates that the transaction state of a registry sub-tree is incompatible with the requested operation. For example, a request has been made to start a new transaction with one already in progress, or a request to apply a transaction when one is not currently in progress. This status value is returned by the runtime library (RTL) registry transaction package (RXact).

ERROR_SAME_DRIVE

The system cannot join or substitute a drive to or for a directory on the same drive.

ERROR_SCREEN_ALREADY_LOCKED

Screen already locked.

ERROR_SECRET_TOO_LONG

The length of a secret exceeds the maximum length allowed. The length and number of secrets is limited to satisfy the United States State Department export restrictions.

ERROR_SECTOR_NOT_FOUND

The drive cannot find the requested sector.

ERROR_SEEK

The drive cannot locate a specific area or track on the disk.

ERROR_SEEK_ON_DEVICE

The file pointer cannot be set on the specified device or file.

ERROR_SEM_IS_SET

The semaphore is set and cannot be closed.

ERROR_SEM_NOT_FOUND

The specified system semaphore name was not found.

ERROR_SEM_OWNER_DIED

The previous ownership of this semaphore has ended.

ERROR_SEM_TIMEOUT

The semaphore timeout period has expired.

ERROR_SEM_USER_LIMIT

Insert the disk for drive 1.

ERROR_SERIAL_NO_DEVICE

No serial device was successfully initialized. The serial driver will unload.

ERROR_SERVER_DISABLED

The GUID allocation server is already disabled at the moment.

ERROR_SERVER_HAS_OPEN_HANDLES

The server is in use and cannot be unloaded.

ERROR_SERVER_NOT_DISABLED

The GUID allocation server is already enabled at the moment.

ERROR_SERVICE_ALREADY_RUNNING

An instance of the service is already running.

ERROR_SERVICE_CANNOT_ACCEPT_CTRL

The service cannot accept control messages at this time.

ERROR_SERVICE_DATABASE_LOCKED

The service database is locked.

ERROR_SERVICE_DEPENDENCY_DELETED

The dependency service does not exist or has been marked for deletion.

ERROR_SERVICE_DEPENDENCY_FAIL

The dependency service or group failed to start.

ERROR_SERVICE_DISABLED

The specified service is disabled and cannot be started.

ERROR_SERVICE_DOES_NOT_EXIST

The specified service does not exist as an installed service.

ERROR_SERVICE_EXISTS

The specified service already exists.

ERROR_SERVICE_LOGON_FAILED

The service did not start due to a logon failure.

ERROR_SERVICE_MARKED_FOR_DELETE

The specified service has been marked for deletion.

ERROR_SERVICE_NEVER_STARTED

No attempts to start the service have been made since the last boot.

ERROR_SERVICE_NO_THREAD

A thread could not be created for the service.

ERROR_SERVICE_NOT_ACTIVE

The service has not been started.

ERROR_SERVICE_NOT_FOUND

The specified service does not exist.

ERROR_SERVICE_REQUEST_TIMEOUT

The service did not respond to the start or control request in a timely fashion.

ERROR_SERVICE_SPECIFIC_ERROR

The service has returned a service-specific error code.

ERROR_SERVICE_START_HANG

After starting, the service hung in a start-pending state.

ERROR_SESSION_CREDENTIAL_CONFLICT

The credentials supplied conflict with an existing set of credentials.

ERROR_SET_POWER_STATE_FAILED

The system BIOS failed an attempt to change the system power state.

ERROR_SET_POWER_STATE_VETOED

An attempt to change the system power state was vetoed by another application or driver.

ERROR_SETCOUNT_ON_BAD_LB

LB_SETCOUNT sent to non-lazy list box.

ERROR_SETMARK_DETECTED

A tape access reached a setmark.

ERROR_SHARING_BUFFER_EXCEEDED

Too many files opened for sharing.

ERROR_SHARING_PAUSED

The remote server is paused or is in the process of being started.

ERROR_SHARING_VIOLATION

The process cannot access the file because it is being used by another process.

ERROR_SHUTDOWN_IN_PROGRESS

A system shutdown is in progress.

ERROR_SIGNAL_PENDING

A signal is already pending.

ERROR_SIGNAL_REFUSED

The recipient process has refused the signal.

ERROR_SINGLE_INSTANCE_APP

Cannot start more than one instance of the specified program.

ERROR_SOME_NOT_MAPPED

Some of the information to be mapped has not been translated.

ERROR_SPECIAL_ACCOUNT

Indicates an operation was attempted on a built-in (special) SAM account that is incompatible with built-in accounts. For example, built-in accounts cannot be renamed or deleted.

ERROR_SPECIAL_GROUP

The requested operation cannot be performed on the specified group because it is a built-in special group.

ERROR_SPECIAL_USER

The requested operation cannot be performed on the specified user because it is a built-in special user.

ERROR_SPL_NO_ADDJOB

An AddJob call was not issued.

ERROR_SPL_NO_STARTDOC

A StartDocPrinter call was not issued.

ERROR_SPOOL_FILE_NOT_FOUND

The spool file was not found.

ERROR_STACK_OVERFLOW

Recursion too deep, stack overflowed.

ERROR_STATIC_INIT

The importation from the file failed.

ERROR_SUBST_TO_JOIN

The system attempted to SUBST a drive to a directory on a joined drive.

ERROR_SUBST_TO_SUBST

The system attempted to substitute a drive to a directory on a substituted drive.

ERROR_SUCCESS

The operation was successfully completed.

ERROR_SUCCESS_REBOOT_REQUIRED

The requested operation is successful. Changes will not be effective until the system is rebooted.

ERROR_SUCCESS_RESTART_REQUIRED

The requested operation is successful. Changes will not be effective until the service is restarted.

ERROR_SWAPERROR

Error accessing paging file.

ERROR_SYSTEM_TRACE

System trace information not specified in your CONFIG.SYS file, or tracing is not allowed.

ERROR_TRANSFORM_NOT_SUPPORTED

The requested transformation operation is not supported.

ERROR_THREAD_1_INACTIVE

The signal handler cannot be set.

ERROR_TLW_WITH_WSCHILD

CreateWindow failed, creating top-level window with WS_CHILD style.

ERROR_TOKEN_ALREADY_IN_USE

An attempt was made to establish a token for use as a primary token but the token is already in use. A token can only be the primary token of one process at a time.

ERROR_TOO_MANY_CMDS

The network BIOS command limit has been reached.

ERROR_TOO_MANY_CONTEXT_IDS

During a logon attempt, the user’s security context accumulated too many security IDs. Remove the user from some groups or aliases to reduce the number of security ids to incorporate into the security context.

ERROR_TOO_MANY_LINKS

An attempt was made to create more links on a file than the file system supports.

ERROR_TOO_MANY_LUIDS_REQUESTED

The number of LUID requested cannot be allocated with a single allocation.

ERROR_TOO_MANY_MODULES

Too many dynamic link modules are attached to this program or dynamic link module.

ERROR_TOO_MANY_MUXWAITERS

Too many semaphores are already set.

ERROR_TOO_MANY_NAMES

The name limit for the local computer network adapter card exceeded.

ERROR_TOO_MANY_OPEN_FILES

The system cannot open the file.

ERROR_TOO_MANY_POSTS

Too many posts made to a semaphore.

ERROR_TOO_MANY_SECRETS

The maximum number of secrets that can be stored in a single system was exceeded. The length and number of secrets is limited to satisfy the United States State Department export restrictions.

ERROR_TOO_MANY_SEM_REQUESTS

The semaphore cannot be set again.

ERROR_TOO_MANY_SEMAPHORES

Cannot create another system semaphore.

ERROR_TOO_MANY_SESS

The network BIOS session limit exceeded.

ERROR_TOO_MANY_SIDS

Too many SIDs specified.

ERROR_TOO_MANY_TCBS

Cannot create another thread.

ERROR_TRUST_FAILURE

The network logon failed.

ERROR_TRUSTED_DOMAIN_FAILURE

The trust relationship between the primary domain and the trusted domain failed.

ERROR_TRUSTED_RELATIONSHIP_FAILURE

The trust relationship between this workstation and the primary domain failed.

ERROR_UNABLE_TO_LOCK_MEDIA

Attempt to lock the eject media mechanism failed.

ERROR_UNABLE_TO_UNLOAD_MEDIA

Unload media failed.

ERROR_UNEXP_NET_ERR

An unexpected network error occurred.

ERROR_UNKNOWN_PORT

The specified port is unknown.

ERROR_UNKNOWN_PRINT_MONITOR

The specified print monitor is unknown.

ERROR_UNKNOWN_PRINTPROCESSOR

The print processor is unknown.

ERROR_UNKNOWN_PRINTER_DRIVER

The printer driver is unknown.

ERROR_UNKNOWN_REVISION

Indicates an encountered or specified revision number is not one known by the service. The service may not be aware of a more recent revision.

ERROR_UNRECOGNIZED_MEDIA

The disk media is not recognized. It may not be formatted.

ERROR_UNRECOGNIZED_VOLUME

The volume does not contain a recognized file system. Make sure that all required file system drivers are loaded and the volume is not damaged.

ERROR_USER_EXISTS

The specified user already exists.

ERROR_USER_MAPPED_FILE

The requested operation cannot be performed on a file with a user mapped section open.

ERROR_VC_DISCONNECTED

The session was canceled.

ERROR_WAIT_NO_CHILDREN

There are no child processes to wait for.

ERROR_WINDOW_NOT_COMBOBOX

The window is not a combo box.

ERROR_WINDOW_NOT_DIALOG

The window is not a valid dialog window.

ERROR_WINDOW_OF_OTHER_THREAD

Invalid window, belongs to other thread.

ERROR_WINS_INTERNAL

WINS encountered an error while processing the command.

ERROR_WORKING_SET_QUOTA

Insufficient quota to complete the requested service.

ERROR_WRITE_FAULT

The system cannot write to the specified device.

ERROR_WRITE_PROTECT

The media is write protected.

ERROR_WRONG_DISK

The wrong disk is in the drive. Insert %2 (Volume Serial Number: %3) into drive %1.

ERROR_WRONG_PASSWORD

When trying to update a password, this return status indicates the value provided as the current password is incorrect.

LZERROR_BADINHANDLE

Invalid input handle.

LZERROR_BADOUTHANDLE

Invalid output handle.

LZERROR_BADVALUE

Input parameter out of acceptable range.

LZERROR_GLOBALLOC

Insufficient memory for LZFile structure.

LZERROR_GLOBLOCK

Bad global handle.

LZERROR_READ

Corrupt compressed file format.

LZERROR_WRITE

Out of space for output file.

LZERROR_UNKNOWNALG

Compression algorithm not recognized.

NO_ERROR

No error.

OR_INVALID_OID

The object specified was not found.

OR_INVALID_OXID

The object exporter specified was not found.

OR_INVALID_SET

The object resolver set specified was not found.

RPC_S_ADDRESS_ERROR

An addressing error occurred in the server.

RPC_S_ALREADY_LISTENING

The server is already listening.

RPC_S_ALREADY_REGISTERED

The object UUID already registered.

RPC_S_BINDING_HAS_NO_AUTH

The binding does not contain any authentication information.

RPC_S_BINDING_INCOMPLETE

The binding handle does not contain all required information.

RPC_S_CALL_CANCELLED

The server was altered while processing this call.

RPC_S_CALL_FAILED

The remote procedure call failed.

RPC_S_CALL_FAILED_DNE

The remote procedure call failed and did not execute.

RPC_S_CALL_IN_PROGRESS

A remote procedure call is already in progress for this thread.

RPC_S_CANNOT_SUPPORT

The requested operation is not supported.

RPC_S_CANT_CREATE_ENDPOINT

The endpoint cannot be created.

RPC_S_COMM_FAILURE

Communications failure.

RPC_S_DUPLICATE_ENDPOINT

The endpoint is a duplicate.

RPC_S_ENTRY_ALREADY_EXISTS

The entry already exists.

RPC_S_ENTRY_NOT_FOUND

The entry is not found.

RPC_S_FP_DIV_ZERO

A floating point operation at the server caused a divide by zero.

RPC_S_FP_OVERFLOW

A floating point overflow occurred at the server.

RPC_S_FP_UNDERFLOW

A floating point underflow occurred at the server.

RPC_S_GROUP_MEMBER_NOT_FOUND

The group member was not found.

RPC_S_INCOMPLETE_NAME

The entry name is incomplete.

RPC_S_INTERFACE_NOT_FOUND

The interface was not found.

RPC_S_INTERNAL_ERROR

An internal error occurred in RPC.

RPC_S_INVALID_AUTH_IDENTITY

The security context is invalid.

RPC_S_INVALID_BINDING

The binding handle is invalid.

RPC_S_INVALID_BOUND

The array bounds are invalid.

RPC_S_INVALID_ENDPOINT_FORMAT

The endpoint format is invalid.

RPC_S_INVALID_NAME_SYNTAX

The name syntax is invalid.

RPC_S_INVALID_NET_ADDR

The network address is invalid.

RPC_S_INVALID_NETWORK_OPTIONS

The network options are invalid.

RPC_S_INVALID_OBJECT

The object universal unique identifier (UUID) is the nil UUID.

RPC_S_INVALID_RPC_PROTSEQ

The RPC protocol sequence is invalid.

RPC_S_INVALID_STRING_BINDING

The string binding is invalid.

RPC_S_INVALID_STRING_UUID

The string UUID is invalid.

RPC_S_INVALID_TAG

The tag is invalid.

RPC_S_INVALID_TIMEOUT

The timeout value is invalid.

RPC_S_INVALID_VERS_OPTION

The version option is invalid.

RPC_S_MAX_CALLS_TOO_SMALL

The maximum number of calls is too small.

RPC_S_NAME_SERVICE_UNAVAILABLE

The name service is unavailable.

RPC_S_NO_BINDINGS

There are no bindings.

RPC_S_NO_CALL_ACTIVE

There is not a remote procedure call active in this thread.

RPC_S_NO_CONTEXT_AVAILABLE

No security context is available to allow impersonation.

RPC_S_NO_ENDPOINT_FOUND

No endpoint was found.

RPC_S_NO_ENTRY_NAME

The binding does not contain an entry name.

RPC_S_NO_MORE_BINDINGS

There are no more bindings.

RPC_S_NO_MORE_MEMBERS

There are no more members.

RPC_S_NO_PRINC_NAME

No principal name registered.

RPC_S_NO_PROTSEQS

There are no protocol sequences.

RPC_S_NO_PROTSEQS_REGISTERED

No protocol sequences were registered.

RPC_S_NOT_LISTENING

The server is not listening.

RPC_S_NOT_ALL_OBJS_UNEXPORTED

There is nothing to unexport.

RPC_S_NOT_CANCELLED

Thread is not cancelled.

RPC_S_NOT_RPC_ERROR

The error specified is not a valid Windows RPC error code.

RPC_S_OBJECT_NOT_FOUND

The object UUID was not found.

RPC_S_OUT_OF_RESOURCES

Not enough resources are available to complete this operation.

RPC_S_PROCNUM_OUT_OF_RANGE

The procedure number is out of range.

RPC_S_PROTOCOL_ERROR

An RPC protocol error occurred.

RPC_S_PROTSEQ_NOT_FOUND

The RPC protocol sequence was not found.

RPC_S_PROTSEQ_NOT_SUPPORTED

The RPC protocol sequence is not supported.

RPC_S_SEC_PKG_ERROR

A security package specific error occurred.

RPC_S_SEND_INCOMPLETE

Some data remains to be sent in the request buffer.

RPC_S_SERVER_OUT_OF_MEMORY

The server has insufficient memory to complete this operation.

RPC_S_SERVER_TOO_BUSY

The server is too busy to complete this operation.

RPC_S_SERVER_UNAVAILABLE

The server is unavailable.

RPC_S_STRING_TOO_LONG

The string is too long.

RPC_S_TYPE_ALREADY_REGISTERED

The type UUID is already registered.

RPC_S_UNKNOWN_AUTHN_LEVEL

The authentication level is unknown.

RPC_S_UNKNOWN_AUTHN_SERVICE

The authentication service is unknown.

RPC_S_UNKNOWN_AUTHN_TYPE

The authentication type is unknown.

RPC_S_UNKNOWN_AUTHZ_SERVICE

The authorization service is unknown.

RPC_S_UNKNOWN_IF

The interface is unknown.

RPC_S_UNKNOWN_MGR_TYPE

The manager type is unknown.

RPC_S_UNSUPPORTED_AUTHN_LEVEL

The requested authentication level is not supported.

RPC_S_UNSUPPORTED_NAME_SYNTAX

The name syntax is not supported.

RPC_S_UNSUPPORTED_TRANS_SYN

The transfer syntax is not supported by the server.

RPC_S_UNSUPPORTED_TYPE

The type UUID is not supported.

RPC_S_UUID_LOCAL_ONLY

A UUID that is valid only on this computer has been allocated.

RPC_S_UUID_NO_ADDRESS

No network address is available to use to construct a UUID.

RPC_S_WRONG_KIND_OF_BINDING

The binding handle is the incorrect type.

RPC_S_ZERO_DIVIDE

The server attempted an integer divide by zero.

RPC_X_BAD_STUB_DATA

The stub received bad data.

RPC_X_BYTE_COUNT_TOO_SMALL

The byte count is too small.

RPC_X_ENUM_VALUE_OUT_OF_RANGE

The enumeration value is out of range.

RPC_X_INVALID_ES_ACTION

Invalid operation on the encoding/decoding handle.

RPC_X_INVALID_PIPE_OBJECT

The idl pipe object is invalid or corrupted.

RPC_X_INVALID_PIPE_OPERATION

The operation is invalid for a given idl pipe object.

RPC_X_NO_MORE_ENTRIES

The list of servers available for auto_handle binding was exhausted.

RPC_X_NULL_REF_POINTER

A null reference pointer was passed to the stub.

RPC_X_SS_CANNOT_GET_CALL_HANDLE

The stub is unable to get the call handle.

RPC_X_SS_CHAR_TRANS_OPEN_FAIL

The file designated by DCERPCCHARTRANS cannot be opened.

RPC_X_SS_CHAR_TRANS_SHORT_FILE

The file containing the character translation table has fewer than 512 bytes.

RPC_X_SS_CONTEXT_DAMAGED

The context handle changed during a call.

RPC_X_SS_CONTEXT_MISMATCH

The context handle does not match any known context handles.

RPC_X_SS_HANDLES_MISMATCH

The binding handles passed to a remote procedure call do not match.

RPC_X_SS_IN_NULL_CONTEXT

A null context handle is passed as an [in] parameter.

RPC_X_WRONG_ES_VERSION

Incompatible version of the serializing package.

RPC_X_WRONG_PIPE_VERSION

The idl pipe version is not supported.

RPC_X_WRONG_STUB_VERSION

Incompatible version of the RPC stub.


Numerical List of Error Codes

-8        LZERROR_UNKNOWNALG

-7        LZERROR_BADVALUE

-6        LZERROR_GLOBLOCK

-5        LZERROR_GLOBALLOC

-4        LZERROR_WRITE

-3        LZERROR_READ

-2        LZERROR_BADOUTHANDLE

-1        LZERROR_BADINHANDLE

0L        NO_ERROR

0L        ERROR_SUCCESS

1L        ERROR_INVALID_FUNCTION

2L        ERROR_FILE_NOT_FOUND

3L        ERROR_PATH_NOT_FOUND

4L        ERROR_TOO_MANY_OPEN_FILES

5L        ERROR_ACCESS_DENIED

6L        ERROR_INVALID_HANDLE

7L        ERROR_ARENA_TRASHED

8L        ERROR_NOT_ENOUGH_MEMORY

9L        ERROR_INVALID_BLOCK

10L       ERROR_BAD_ENVIRONMENT

11L       ERROR_BAD_FORMAT

12L       ERROR_INVALID_ACCESS

13L       ERROR_INVALID_DATA

14L       ERROR_OUTOFMEMORY

15L       ERROR_INVALID_DRIVE

16L       ERROR_CURRENT_DIRECTORY

17L       ERROR_NOT_SAME_DEVICE

18L       ERROR_NO_MORE_FILES

19L       ERROR_WRITE_PROTECT

20L       ERROR_BAD_UNIT

21L       ERROR_NOT_READY

22L       ERROR_BAD_COMMAND

23L       ERROR_CRC

24L       ERROR_BAD_LENGTH

25L       ERROR_SEEK

26L       ERROR_NOT_DOS_DISK

27L       ERROR_SECTOR_NOT_FOUND

28L       ERROR_OUT_OF_PAPER

29L       ERROR_WRITE_FAULT

30L       ERROR_READ_FAULT

31L       ERROR_GEN_FAILURE

32L       ERROR_SHARING_VIOLATION

33L       ERROR_LOCK_VIOLATION

34L       ERROR_WRONG_DISK

36L       ERROR_SHARING_BUFFER_EXCEEDED

38L       ERROR_HANDLE_EOF

39L       ERROR_HANDLE_DISK_FULL

50L       ERROR_NOT_SUPPORTED

51L       ERROR_REM_NOT_LIST

52L       ERROR_DUP_NAME

53L       ERROR_BAD_NETPATH

54L       ERROR_NETWORK_BUSY

55L       ERROR_DEV_NOT_EXIST

56L       ERROR_TOO_MANY_CMDS

57L       ERROR_ADAP_HDW_ERR

58L       ERROR_BAD_NET_RESP

59L       ERROR_UNEXP_NET_ERR

60L       ERROR_BAD_REM_ADAP

61L       ERROR_PRINTQ_FULL

62L       ERROR_NO_SPOOL_SPACE

63L       ERROR_PRINT_CANCELLED

64L       ERROR_NETNAME_DELETED

65L       ERROR_NETWORK_ACCESS_DENIED

66L       ERROR_BAD_DEV_TYPE

67L       ERROR_BAD_NET_NAME

68L       ERROR_TOO_MANY_NAMES

69L       ERROR_TOO_MANY_SESS

70L       ERROR_SHARING_PAUSED

71L       ERROR_REQ_NOT_ACCEP

72L       ERROR_REDIR_PAUSED

80L       ERROR_FILE_EXISTS

82L       ERROR_CANNOT_MAKE

83L       ERROR_FAIL_I24

84L       ERROR_OUT_OF_STRUCTURES

85L       ERROR_ALREADY_ASSIGNED

86L       ERROR_INVALID_PASSWORD

87L       ERROR_INVALID_PARAMETER

88L       ERROR_NET_WRITE_FAULT

89L       ERROR_NO_PROC_SLOTS

100L      ERROR_TOO_MANY_SEMAPHORES

101L      ERROR_EXCL_SEM_ALREADY_OWNED

102L      ERROR_SEM_IS_SET

103L      ERROR_TOO_MANY_SEM_REQUESTS

104L      ERROR_INVALID_AT_INTERRUPT_TIME

105L      ERROR_SEM_OWNER_DIED

106L      ERROR_SEM_USER_LIMIT

107L      ERROR_DISK_CHANGE

108L      ERROR_DRIVE_LOCKED

109L      ERROR_BROKEN_PIPE

110L      ERROR_OPEN_FAILED

111L      ERROR_BUFFER_OVERFLOW

112L      ERROR_DISK_FULL

113L      ERROR_NO_MORE_SEARCH_HANDLES

114L      ERROR_INVALID_TARGET_HANDLE

117L      ERROR_INVALID_CATEGORY

118L      ERROR_INVALID_VERIFY_SWITCH

119L      ERROR_BAD_DRIVER_LEVEL

120L      ERROR_CALL_NOT_IMPLEMENTED

121L      ERROR_SEM_TIMEOUT

122L      ERROR_INSUFFICIENT_BUFFER

123L      ERROR_INVALID_NAME

124L      ERROR_INVALID_LEVEL

125L      ERROR_NO_VOLUME_LABEL

126L      ERROR_MOD_NOT_FOUND

127L      ERROR_PROC_NOT_FOUND

128L      ERROR_WAIT_NO_CHILDREN

129L      ERROR_CHILD_NOT_COMPLETE

130L      ERROR_DIRECT_ACCESS_HANDLE

131L      ERROR_NEGATIVE_SEEK

132L      ERROR_SEEK_ON_DEVICE

133L      ERROR_IS_JOIN_TARGET

134L      ERROR_IS_JOINED

135L      ERROR_IS_SUBSTED

136L      ERROR_NOT_JOINED

137L      ERROR_NOT_SUBSTED

138L      ERROR_JOIN_TO_JOIN

139L      ERROR_SUBST_TO_SUBST

140L      ERROR_JOIN_TO_SUBST

141L      ERROR_SUBST_TO_JOIN

142L      ERROR_BUSY_DRIVE

143L      ERROR_SAME_DRIVE

144L      ERROR_DIR_NOT_ROOT

145L      ERROR_DIR_NOT_EMPTY

146L      ERROR_IS_SUBST_PATH

147L      ERROR_IS_JOIN_PATH

148L      ERROR_PATH_BUSY

149L      ERROR_IS_SUBST_TARGET

150L      ERROR_SYSTEM_TRACE

151L      ERROR_INVALID_EVENT_COUNT

152L      ERROR_TOO_MANY_MUXWAITERS

153L      ERROR_INVALID_LIST_FORMAT

154L      ERROR_LABEL_TOO_LONG

155L      ERROR_TOO_MANY_TCBS

156L      ERROR_SIGNAL_REFUSED

157L      ERROR_DISCARDED

158L      ERROR_NOT_LOCKED

159L      ERROR_BAD_THREADID_ADDR

160L      ERROR_BAD_ARGUMENTS

161L      ERROR_BAD_PATHNAME

162L      ERROR_SIGNAL_PENDING

164L      ERROR_MAX_THRDS_REACHED

167L      ERROR_LOCK_FAILED

170L      ERROR_BUSY

173L      ERROR_CANCEL_VIOLATION

174L      ERROR_ATOMIC_LOCKS_NOT_SUPPORTED

180L      ERROR_INVALID_SEGMENT_NUMBER

182L      ERROR_INVALID_ORDINAL

183L      ERROR_ALREADY_EXISTS

186L      ERROR_INVALID_FLAG_NUMBER

187L      ERROR_SEM_NOT_FOUND

188L      ERROR_INVALID_STARTING_CODESEG

189L      ERROR_INVALID_STACKSEG

190L      ERROR_INVALID_MODULETYPE

191L      ERROR_INVALID_EXE_SIGNATURE

192L      ERROR_EXE_MARKED_INVALID

193L      ERROR_BAD_EXE_FORMAT

194L      ERROR_ITERATED_DATA_EXCEEDS_64k

195L      ERROR_INVALID_MINALLOCSIZE

196L      ERROR_DYNLINK_FROM_INVALID_RING

197L      ERROR_IOPL_NOT_ENABLED

198L      ERROR_INVALID_SEGDPL

199L      ERROR_AUTODATASEG_EXCEEDS_64k

200L      ERROR_RING2SEG_MUST_BE_MOVABLE

201L      ERROR_RELOC_CHAIN_XEEDS_SEGLIM

202L      ERROR_INFLOOP_IN_RELOC_CHAIN

203L      ERROR_ENVVAR_NOT_FOUND

205L      ERROR_NO_SIGNAL_SENT

206L      ERROR_FILENAME_EXCED_RANGE

207L      ERROR_RING2_STACK_IN_USE

208L      ERROR_META_EXPANSION_TOO_LONG

209L      ERROR_INVALID_SIGNAL_NUMBER

210L      ERROR_THREAD_1_INACTIVE

212L      ERROR_LOCKED

214L      ERROR_TOO_MANY_MODULES

215L      ERROR_NESTING_NOT_ALLOWED

230L      ERROR_BAD_PIPE

231L      ERROR_PIPE_BUSY

232L      ERROR_NO_DATA

233L      ERROR_PIPE_NOT_CONNECTED

234L      ERROR_MORE_DATA

240L      ERROR_VC_DISCONNECTED

254L      ERROR_INVALID_EA_NAME

255L      ERROR_EA_LIST_INCONSISTENT

259L      ERROR_NO_MORE_ITEMS

266L      ERROR_CANNOT_COPY

267L      ERROR_DIRECTORY

275L      ERROR_EAS_DIDNT_FIT

276L      ERROR_EA_FILE_CORRUPT

277L      ERROR_EA_TABLE_FULL

278L      ERROR_INVALID_EA_HANDLE

282L      ERROR_EAS_NOT_SUPPORTED

288L      ERROR_NOT_OWNER

298L      ERROR_TOO_MANY_POSTS

299L      ERROR_PARTIAL_COPY

317L      ERROR_MR_MID_NOT_FOUND

487L      ERROR_INVALID_ADDRESS

534L      ERROR_ARITHMETIC_OVERFLOW

535L      ERROR_PIPE_CONNECTED

536L      ERROR_PIPE_LISTENING

994L      ERROR_EA_ACCESS_DENIED

995L      ERROR_OPERATION_ABORTED

996L      ERROR_IO_INCOMPLETE

997L      ERROR_IO_PENDING

998L      ERROR_NOACCESS

999L      ERROR_SWAPERROR

1001L     ERROR_STACK_OVERFLOW

1002L     ERROR_INVALID_MESSAGE

1003L     ERROR_CAN_NOT_COMPLETE

1004L     ERROR_INVALID_FLAGS

1005L     ERROR_UNRECOGNIZED_VOLUME

1006L     ERROR_FILE_INVALID

1007L     ERROR_FULLSCREEN_MODE

1008L     ERROR_NO_TOKEN

1009L     ERROR_BADDB

1010L     ERROR_BADKEY

1011L     ERROR_CANTOPEN

1012L     ERROR_CANTREAD

1013L     ERROR_CANTWRITE

1014L     ERROR_REGISTRY_RECOVERED

1015L     ERROR_REGISTRY_CORRUPT

1016L     ERROR_REGISTRY_IO_FAILED

1017L     ERROR_NOT_REGISTRY_FILE

1018L     ERROR_KEY_DELETED

1019L     ERROR_NO_LOG_SPACE

1020L     ERROR_KEY_HAS_CHILDREN

1021L     ERROR_CHILD_MUST_BE_VOLATILE

1022L     ERROR_NOTIFY_ENUM_DIR

1051L     ERROR_DEPENDENT_SERVICES_RUNNING

1052L     ERROR_INVALID_SERVICE_CONTROL

1053L     ERROR_SERVICE_REQUEST_TIMEOUT

1054L     ERROR_SERVICE_NO_THREAD

1055L     ERROR_SERVICE_DATABASE_LOCKED

1056L     ERROR_SERVICE_ALREADY_RUNNING

1057L     ERROR_INVALID_SERVICE_ACCOUNT

1058L     ERROR_SERVICE_DISABLED

1059L     ERROR_CIRCULAR_DEPENDENCY

1060L     ERROR_SERVICE_DOES_NOT_EXIST

1061L     ERROR_SERVICE_CANNOT_ACCEPT_CTRL

1062L     ERROR_SERVICE_NOT_ACTIVE

1063L     ERROR_FAILED_SERVICE_CONTROLLER_CONNECT

1064L     ERROR_EXCEPTION_IN_SERVICE

1065L     ERROR_DATABASE_DOES_NOT_EXIST

1066L     ERROR_SERVICE_SPECIFIC_ERROR

1067L     ERROR_PROCESS_ABORTED

1068L     ERROR_SERVICE_DEPENDENCY_FAIL

1069L     ERROR_SERVICE_LOGON_FAILED

1070L     ERROR_SERVICE_START_HANG

1071L     ERROR_INVALID_SERVICE_LOCK

1072L     ERROR_SERVICE_MARKED_FOR_DELETE

1073L     ERROR_SERVICE_EXISTS

1074L     ERROR_ALREADY_RUNNING_LKG

1075L     ERROR_SERVICE_DEPENDENCY_DELETED

1076L     ERROR_BOOT_ALREADY_ACCEPTED

1077L     ERROR_SERVICE_NEVER_STARTED

1078L     ERROR_DUPLICATE_SERVICE_NAME

1079L     ERROR_DIFFERENT_SERVICE_ACCOUNT

1100L     ERROR_END_OF_MEDIA

1101L     ERROR_FILEMARK_DETECTED

1102L     ERROR_BEGINNING_OF_MEDIA

1103L     ERROR_SETMARK_DETECTED

1104L     ERROR_NO_DATA_DETECTED

1105L     ERROR_PARTITION_FAILURE

1106L     ERROR_INVALID_BLOCK_LENGTH

1107L     ERROR_DEVICE_NOT_PARTITIONED

1108L     ERROR_UNABLE_TO_LOCK_MEDIA

1109L     ERROR_UNABLE_TO_UNLOAD_MEDIA

1110L     ERROR_MEDIA_CHANGED

1111L     ERROR_BUS_RESET

1112L     ERROR_NO_MEDIA_IN_DRIVE

1113L     ERROR_NO_UNICODE_TRANSLATION

1114L     ERROR_DLL_INIT_FAILED

1115L     ERROR_SHUTDOWN_IN_PROGRESS

1116L     ERROR_NO_SHUTDOWN_IN_PROGRESS

1117L     ERROR_IO_DEVICE

1118L     ERROR_SERIAL_NO_DEVICE

1119L     ERROR_IRQ_BUSY

1120L     ERROR_MORE_WRITES

1121L     ERROR_COUNTER_TIMEOUT

1122L     ERROR_FLOPPY_ID_MARK_NOT_FOUND

1123L     ERROR_FLOPPY_WRONG_CYLINDER

1124L     ERROR_FLOPPY_UNKNOWN_ERROR

1125L     ERROR_FLOPPY_BAD_REGISTERS

1126L     ERROR_DISK_RECALIBRATE_FAILED

1127L     ERROR_DISK_OPERATION_FAILED

1128L     ERROR_DISK_RESET_FAILED

1129L     ERROR_EOM_OVERFLOW

1130L     ERROR_NOT_ENOUGH_SERVER_MEMORY

1131L     ERROR_POSSIBLE_DEADLOCK

1132L     ERROR_MAPPED_ALIGNMENT

1140L     ERROR_SET_POWER_STATE_VETOED

1141L     ERROR_SET_POWER_STATE_FAILED

1142L     ERROR_TOO_MANY_LINKS

1150L     ERROR_OLD_WIN_VERSION

1151L     ERROR_APP_WRONG_OS

1152L     ERROR_SINGLE_INSTANCE_APP

1153L     ERROR_RMODE_APP

1154L     ERROR_INVALID_DLL

1155L     ERROR_NO_ASSOCIATION

1156L     ERROR_DDE_FAIL

1157L     ERROR_DLL_NOT_FOUND

1200L     ERROR_BAD_DEVICE

1201L     ERROR_CONNECTION_UNAVAIL

1202L     ERROR_DEVICE_ALREADY_REMEMBERED

1203L     ERROR_NO_NET_OR_BAD_PATH

1204L     ERROR_BAD_PROVIDER

1205L     ERROR_CANNOT_OPEN_PROFILE

1206L     ERROR_BAD_PROFILE

1207L     ERROR_NOT_CONTAINER

1208L     ERROR_EXTENDED_ERROR

1209L     ERROR_INVALID_GROUPNAME

1210L     ERROR_INVALID_COMPUTERNAME

1211L     ERROR_INVALID_EVENTNAME

1212L     ERROR_INVALID_DOMAINNAME

1213L     ERROR_INVALID_SERVICENAME

1214L     ERROR_INVALID_NETNAME

1215L     ERROR_INVALID_SHARENAME

1216L     ERROR_INVALID_PASSWORDNAME

1217L     ERROR_INVALID_MESSAGENAME

1218L     ERROR_INVALID_MESSAGEDEST

1219L     ERROR_SESSION_CREDENTIAL_CONFLICT

1220L     ERROR_REMOTE_SESSION_LIMIT_EXCEEDED

1221L     ERROR_DUP_DOMAINNAME

1222L     ERROR_NO_NETWORK

1223L     ERROR_CANCELLED

1224L     ERROR_USER_MAPPED_FILE

1225L     ERROR_CONNECTION_REFUSED

1226L     ERROR_GRACEFUL_DISCONNECT

1227L     ERROR_ADDRESS_ALREADY_ASSOCIATED

1228L     ERROR_ADDRESS_NOT_ASSOCIATED

1229L     ERROR_CONNECTION_INVALID

1230L     ERROR_CONNECTION_ACTIVE

1231L     ERROR_NETWORK_UNREACHABLE

1232L     ERROR_HOST_UNREACHABLE

1233L     ERROR_PROTOCOL_UNREACHABLE

1234L     ERROR_PORT_UNREACHABLE

1235L     ERROR_REQUEST_ABORTED

1236L     ERROR_CONNECTION_ABORTED

1237L     ERROR_RETRY

1238L     ERROR_CONNECTION_COUNT_LIMIT

1239L     ERROR_LOGIN_TIME_RESTRICTION

1240L     ERROR_LOGIN_WKSTA_RESTRICTION

1241L     ERROR_INCORRECT_ADDRESS

1242L     ERROR_ALREADY_REGISTERED

1243L     ERROR_SERVICE_NOT_FOUND

1244L     ERROR_NOT_AUTHENTICATED

1245L     ERROR_NOT_LOGGED_ON

1246L     ERROR_CONTINUE

1247L     ERROR_ALREADY_INITIALIZED

1248L     ERROR_NO_MORE_DEVICES

1300L     ERROR_NOT_ALL_ASSIGNED

1301L     ERROR_SOME_NOT_MAPPED

1302L     ERROR_NO_QUOTAS_FOR_ACCOUNT

1303L     ERROR_LOCAL_USER_SESSION_KEY

1304L     ERROR_NULL_LM_PASSWORD

1305L     ERROR_UNKNOWN_REVISION

1306L     ERROR_REVISION_MISMATCH

1307L     ERROR_INVALID_OWNER

1308L     ERROR_INVALID_PRIMARY_GROUP

1309L     ERROR_NO_IMPERSONATION_TOKEN

1310L     ERROR_CANT_DISABLE_MANDATORY

1311L     ERROR_NO_LOGON_SERVERS

1312L     ERROR_NO_SUCH_LOGON_SESSION

1313L     ERROR_NO_SUCH_PRIVILEGE

1314L     ERROR_PRIVILEGE_NOT_HELD

1315L     ERROR_INVALID_ACCOUNT_NAME

1316L     ERROR_USER_EXISTS

1317L     ERROR_NO_SUCH_USER

1318L     ERROR_GROUP_EXISTS

1319L     ERROR_NO_SUCH_GROUP

1320L     ERROR_MEMBER_IN_GROUP

1321L     ERROR_MEMBER_NOT_IN_GROUP

1322L     ERROR_LAST_ADMIN

1323L     ERROR_WRONG_PASSWORD

1324L     ERROR_ILL_FORMED_PASSWORD

1325L     ERROR_PASSWORD_RESTRICTION

1326L     ERROR_LOGON_FAILURE

1327L     ERROR_ACCOUNT_RESTRICTION

1328L     ERROR_INVALID_LOGON_HOURS

1329L     ERROR_INVALID_WORKSTATION

1330L     ERROR_PASSWORD_EXPIRED

1331L     ERROR_ACCOUNT_DISABLED

1332L     ERROR_NONE_MAPPED

1333L     ERROR_TOO_MANY_LUIDS_REQUESTED

1334L     ERROR_LUIDS_EXHAUSTED

1335L     ERROR_INVALID_SUB_AUTHORITY

1336L     ERROR_INVALID_ACL

1337L     ERROR_INVALID_SID

1338L     ERROR_INVALID_SECURITY_DESCR

1340L     ERROR_BAD_INHERITANCE_ACL

1341L     ERROR_SERVER_DISABLED

1342L     ERROR_SERVER_NOT_DISABLED

1343L     ERROR_INVALID_ID_AUTHORITY

1344L     ERROR_ALLOTTED_SPACE_EXCEEDED

1345L     ERROR_INVALID_GROUP_ATTRIBUTES

1346L     ERROR_BAD_IMPERSONATION_LEVEL

1347L     ERROR_CANT_OPEN_ANONYMOUS

1348L     ERROR_BAD_VALIDATION_CLASS

1349L     ERROR_BAD_TOKEN_TYPE

1350L     ERROR_NO_SECURITY_ON_OBJECT

1351L     ERROR_CANT_ACCESS_DOMAIN_INFO

1352L     ERROR_INVALID_SERVER_STATE

1353L     ERROR_INVALID_DOMAIN_STATE

1354L     ERROR_INVALID_DOMAIN_ROLE

1355L     ERROR_NO_SUCH_DOMAIN

1356L     ERROR_DOMAIN_EXISTS

1357L     ERROR_DOMAIN_LIMIT_EXCEEDED

1358L     ERROR_INTERNAL_DB_CORRUPTION

1359L     ERROR_INTERNAL_ERROR

1360L     ERROR_GENERIC_NOT_MAPPED

1361L     ERROR_BAD_DESCRIPTOR_FORMAT

1362L     ERROR_NOT_LOGON_PROCESS

1363L     ERROR_LOGON_SESSION_EXISTS

1364L     ERROR_NO_SUCH_PACKAGE

1365L     ERROR_BAD_LOGON_SESSION_STATE

1366L     ERROR_LOGON_SESSION_COLLISION

1367L     ERROR_INVALID_LOGON_TYPE

1368L     ERROR_CANNOT_IMPERSONATE

1369L     ERROR_RXACT_INVALID_STATE

1370L     ERROR_RXACT_COMMIT_FAILURE

1371L     ERROR_SPECIAL_ACCOUNT

1372L     ERROR_SPECIAL_GROUP

1373L     ERROR_SPECIAL_USER

1374L     ERROR_MEMBERS_PRIMARY_GROUP

1375L     ERROR_TOKEN_ALREADY_IN_USE

1376L     ERROR_NO_SUCH_ALIAS

1377L     ERROR_MEMBER_NOT_IN_ALIAS

1378L     ERROR_MEMBER_IN_ALIAS

1379L     ERROR_ALIAS_EXISTS

1380L     ERROR_LOGON_NOT_GRANTED

1381L     ERROR_TOO_MANY_SECRETS

1382L     ERROR_SECRET_TOO_LONG

1383L     ERROR_INTERNAL_DB_ERROR

1384L     ERROR_TOO_MANY_CONTEXT_IDS

1385L     ERROR_LOGON_TYPE_NOT_GRANTED

1386L     ERROR_NT_CROSS_ENCRYPTION_REQUIRED

1387L     ERROR_NO_SUCH_MEMBER

1388L     ERROR_INVALID_MEMBER

1389L     ERROR_TOO_MANY_SIDS

1390L     ERROR_LM_CROSS_ENCRYPTION_REQUIRED

1391L     ERROR_NO_INHERITANCE

1392L     ERROR_FILE_CORRUPT

1393L     ERROR_DISK_CORRUPT

1394L     ERROR_NO_USER_SESSION_KEY

1395L     ERROR_LICENSE_QUOTA_EXCEEDED

1400L     ERROR_INVALID_WINDOW_HANDLE

1401L     ERROR_INVALID_MENU_HANDLE

1402L     ERROR_INVALID_CURSOR_HANDLE

1403L     ERROR_INVALID_ACCEL_HANDLE

1404L     ERROR_INVALID_HOOK_HANDLE

1405L     ERROR_INVALID_DWP_HANDLE

1406L     ERROR_TLW_WITH_WSCHILD

1407L     ERROR_CANNOT_FIND_WND_CLASS

1408L     ERROR_WINDOW_OF_OTHER_THREAD

1409L     ERROR_HOTKEY_ALREADY_REGISTERED

1410L     ERROR_CLASS_ALREADY_EXISTS

1411L     ERROR_CLASS_DOES_NOT_EXIST

1412L     ERROR_CLASS_HAS_WINDOWS

1413L     ERROR_INVALID_INDEX

1414L     ERROR_INVALID_ICON_HANDLE

1415L     ERROR_PRIVATE_DIALOG_INDEX

1416L     ERROR_LISTBOX_ID_NOT_FOUND

1417L     ERROR_NO_WILDCARD_CHARACTERS

1418L     ERROR_CLIPBOARD_NOT_OPEN

1419L     ERROR_HOTKEY_NOT_REGISTERED

1420L     ERROR_WINDOW_NOT_DIALOG

1421L     ERROR_CONTROL_ID_NOT_FOUND

1422L     ERROR_INVALID_COMBOBOX_MESSAGE

1423L     ERROR_WINDOW_NOT_COMBOBOX

1424L     ERROR_INVALID_EDIT_HEIGHT

1425L     ERROR_DC_NOT_FOUND

1426L     ERROR_INVALID_HOOK_FILTER

1427L     ERROR_INVALID_FILTER_PROC

1428L     ERROR_HOOK_NEEDS_HMOD

1429L     ERROR_GLOBAL_ONLY_HOOK

1430L     ERROR_JOURNAL_HOOK_SET

1431L     ERROR_HOOK_NOT_INSTALLED

1432L     ERROR_INVALID_LB_MESSAGE

1433L     ERROR_SETCOUNT_ON_BAD_LB

1434L     ERROR_LB_WITHOUT_TABSTOPS

1435L     ERROR_DESTROY_OBJECT_OF_OTHER_THREAD

1436L     ERROR_CHILD_WINDOW_MENU

1437L     ERROR_NO_SYSTEM_MENU

1438L     ERROR_INVALID_MSGBOX_STYLE

1439L     ERROR_INVALID_SPI_VALUE

1440L     ERROR_SCREEN_ALREADY_LOCKED

1441L     ERROR_HWNDS_HAVE_DIFFERENT_PARENT

1442L     ERROR_NOT_CHILD_WINDOW

1443L     ERROR_INVALID_GW_COMMAND

1444L     ERROR_INVALID_THREAD_ID

1445L     ERROR_NON_MDICHILD_WINDOW

1446L     ERROR_POPUP_ALREADY_ACTIVE

1447L     ERROR_NO_SCROLLBARS

1448L     ERROR_INVALID_SCROLLBAR_RANGE

1449L     ERROR_INVALID_SHOWWIN_COMMAND

1450L     ERROR_NO_SYSTEM_RESOURCES

1451L     ERROR_NONPAGED_SYSTEM_RESOURCES

1452L     ERROR_PAGED_SYSTEM_RESOURCES

1453L     ERROR_WORKING_SET_QUOTA

1454L     ERROR_PAGEFILE_QUOTA

1455L     ERROR_COMMITMENT_LIMIT

1456L     ERROR_MENU_ITEM_NOT_FOUND

1457L     ERROR_INVALID_KEYBOARD_HANDLE

1458L     ERROR_HOOK_TYPE_NOT_ALLOWED

1500L     ERROR_EVENTLOG_FILE_CORRUPT

1501L     ERROR_EVENTLOG_CANT_START

1502L     ERROR_LOG_FILE_FULL

1503L     ERROR_EVENTLOG_FILE_CHANGED

1700L     RPC_S_INVALID_STRING_BINDING

1701L     RPC_S_WRONG_KIND_OF_BINDING

1702L     RPC_S_INVALID_BINDING

1703L     RPC_S_PROTSEQ_NOT_SUPPORTED

1704L     RPC_S_INVALID_RPC_PROTSEQ

1705L     RPC_S_INVALID_STRING_UUID

1706L     RPC_S_INVALID_ENDPOINT_FORMAT

1707L     RPC_S_INVALID_NET_ADDR

1708L     RPC_S_NO_ENDPOINT_FOUND

1709L     RPC_S_INVALID_TIMEOUT

1710L     RPC_S_OBJECT_NOT_FOUND

1711L     RPC_S_ALREADY_REGISTERED

1712L     RPC_S_TYPE_ALREADY_REGISTERED

1713L     RPC_S_ALREADY_LISTENING

1714L     RPC_S_NO_PROTSEQS_REGISTERED

1715L     RPC_S_NOT_LISTENING

1716L     RPC_S_UNKNOWN_MGR_TYPE

1717L     RPC_S_UNKNOWN_IF

1718L     RPC_S_NO_BINDINGS

1719L     RPC_S_NO_PROTSEQS

1720L     RPC_S_CANT_CREATE_ENDPOINT

1721L     RPC_S_OUT_OF_RESOURCES

1722L     RPC_S_SERVER_UNAVAILABLE

1723L     RPC_S_SERVER_TOO_BUSY

1724L     RPC_S_INVALID_NETWORK_OPTIONS

1725L     RPC_S_NO_CALL_ACTIVE

1726L     RPC_S_CALL_FAILED

1727L     RPC_S_CALL_FAILED_DNE

1728L     RPC_S_PROTOCOL_ERROR

1730L     RPC_S_UNSUPPORTED_TRANS_SYN

1731L     RPC_S_SERVER_OUT_OF_MEMORY

1732L     RPC_S_UNSUPPORTED_TYPE

1733L     RPC_S_INVALID_TAG

1734L     RPC_S_INVALID_BOUND

1735L     RPC_S_NO_ENTRY_NAME

1736L     RPC_S_INVALID_NAME_SYNTAX

1737L     RPC_S_UNSUPPORTED_NAME_SYNTAX

1739L     RPC_S_UUID_NO_ADDRESS

1740L     RPC_S_DUPLICATE_ENDPOINT

1741L     RPC_S_UNKNOWN_AUTHN_TYPE

1742L     RPC_S_MAX_CALLS_TOO_SMALL

1743L     RPC_S_STRING_TOO_LONG

1744L     RPC_S_PROTSEQ_NOT_FOUND

1745L     RPC_S_PROCNUM_OUT_OF_RANGE

1746L     RPC_S_BINDING_HAS_NO_AUTH

1747L     RPC_S_UNKNOWN_AUTHN_SERVICE

1748L     RPC_S_UNKNOWN_AUTHN_LEVEL

1749L     RPC_S_INVALID_AUTH_IDENTITY

1750L     RPC_S_UNKNOWN_AUTHZ_SERVICE

1751L     EPT_S_INVALID_ENTRY

1752L     EPT_S_CANT_PERFORM_OP

1753L     EPT_S_NOT_REGISTERED

1755L     RPC_S_INCOMPLETE_NAME

1756L     RPC_S_INVALID_VERS_OPTION

1757L     RPC_S_NO_MORE_MEMBERS

1758L     RPC_S_NOT_ALL_OBJS_UNEXPORTED

1759L     RPC_S_INTERFACE_NOT_FOUND

1760L     RPC_S_ENTRY_ALREADY_EXISTS

1761L     RPC_S_ENTRY_NOT_FOUND

1762L     RPC_S_NAME_SERVICE_UNAVAILABLE

1764L     RPC_S_CANNOT_SUPPORT

1765L     RPC_S_NO_CONTEXT_AVAILABLE

1766L     RPC_S_INTERNAL_ERROR

1767L     RPC_S_ZERO_DIVIDE

1768L     RPC_S_ADDRESS_ERROR

1769L     RPC_S_FP_DIV_ZERO

1770L     RPC_S_FP_UNDERFLOW

1771L     RPC_S_FP_OVERFLOW

1772L     RPC_X_NO_MORE_ENTRIES

1773L     RPC_X_SS_CHAR_TRANS_OPEN_FAIL

1774L     RPC_X_SS_CHAR_TRANS_SHORT_FILE

1775L     RPC_X_SS_IN_NULL_CONTEXT

1776L     RPC_X_SS_CONTEXT_MISMATCH

1777L     RPC_X_SS_CONTEXT_DAMAGED

1778L     RPC_X_SS_HANDLES_MISMATCH

1779L     RPC_X_SS_CANNOT_GET_CALL_HANDLE

1780L     RPC_X_NULL_REF_POINTER

1781L     RPC_X_ENUM_VALUE_OUT_OF_RANGE

1782L     RPC_X_BYTE_COUNT_TOO_SMALL

1783L     RPC_X_BAD_STUB_DATA

1784L     ERROR_INVALID_USER_BUFFER

1785L     ERROR_UNRECOGNIZED_MEDIA

1786L     ERROR_NO_TRUST_LSA_SECRET

1787L     ERROR_NO_TRUST_SAM_ACCOUNT

1788L     ERROR_TRUSTED_DOMAIN_FAILURE

1789L     ERROR_TRUSTED_RELATIONSHIP_FAILURE

1790L     ERROR_TRUST_FAILURE

1791L     RPC_S_CALL_IN_PROGRESS

1792L     ERROR_NETLOGON_NOT_STARTED

1793L     ERROR_ACCOUNT_EXPIRED

1794L     ERROR_REDIRECTOR_HAS_OPEN_HANDLES

1795L     ERROR_PRINTER_DRIVER_ALREADY_INSTALLED

1796L     ERROR_UNKNOWN_PORT

1797L     ERROR_UNKNOWN_PRINTER_DRIVER

1798L     ERROR_UNKNOWN_PRINTPROCESSOR

1799L     ERROR_INVALID_SEPARATOR_FILE

1800L     ERROR_INVALID_PRIORITY

1801L     ERROR_INVALID_PRINTER_NAME

1802L     ERROR_PRINTER_ALREADY_EXISTS

1803L     ERROR_INVALID_PRINTER_COMMAND

1804L     ERROR_INVALID_DATATYPE

1805L     ERROR_INVALID_ENVIRONMENT

1806L     RPC_S_NO_MORE_BINDINGS

1807L     ERROR_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT

1808L     ERROR_NOLOGON_WORKSTATION_TRUST_ACCOUNT

1809L     ERROR_NOLOGON_SERVER_TRUST_ACCOUNT

1810L     ERROR_DOMAIN_TRUST_INCONSISTENT

1811L     ERROR_SERVER_HAS_OPEN_HANDLES

1812L     ERROR_RESOURCE_DATA_NOT_FOUND

1813L     ERROR_RESOURCE_TYPE_NOT_FOUND

1814L     ERROR_RESOURCE_NAME_NOT_FOUND

1815L     ERROR_RESOURCE_LANG_NOT_FOUND

1816L     ERROR_NOT_ENOUGH_QUOTA

1817L     RPC_S_NO_INTERFACES

1818L     RPC_S_CALL_CANCELLED

1819L     RPC_S_BINDING_INCOMPLETE

1820L     RPC_S_COMM_FAILURE

1821L     RPC_S_UNSUPPORTED_AUTHN_LEVEL

1822L     RPC_S_NO_PRINC_NAME

1823L     RPC_S_NOT_RPC_ERROR

1824L     RPC_S_UUID_LOCAL_ONLY

1825L     RPC_S_SEC_PKG_ERROR

1826L     RPC_S_NOT_CANCELLED

1827L     RPC_X_INVALID_ES_ACTION

1828L     RPC_X_WRONG_ES_VERSION

1829L     RPC_X_WRONG_STUB_VERSION

1830L     RPC_X_INVALID_PIPE_OBJECT

1831L     RPC_X_INVALID_PIPE_OPERATION

1832L     RPC_X_WRONG_PIPE_VERSION

1898L     RPC_S_GROUP_MEMBER_NOT_FOUND

1899L     EPT_S_CANT_CREATE

1900L     RPC_S_INVALID_OBJECT

1901L     ERROR_INVALID_TIME

1902L     ERROR_INVALID_FORM_NAME

1903L     ERROR_INVALID_FORM_SIZE

1904L     ERROR_ALREADY_WAITING

1905L     ERROR_PRINTER_DELETED

1906L     ERROR_INVALID_PRINTER_STATE

1907L     ERROR_PASSWORD_MUST_CHANGE

1908L     ERROR_DOMAIN_CONTROLLER_NOT_FOUND

1909L     ERROR_ACCOUNT_LOCKED_OUT

1910L     OR_INVALID_OXID

1911L     OR_INVALID_OID

1912L     OR_INVALID_SET

1913L     RPC_S_SEND_INCOMPLETE

2000L     ERROR_INVALID_PIXEL_FORMAT

2001L     ERROR_BAD_DRIVER

2002L     ERROR_INVALID_WINDOW_STYLE

2003L     ERROR_METAFILE_NOT_SUPPORTED

2004L     ERROR_TRANSFORM_NOT_SUPPORTED

2005L     ERROR_CLIPPING_NOT_SUPPORTED

2138L     ERROR_NO_NETWORK

2202L     ERROR_BAD_USERNAME

2250L     ERROR_NOT_CONNECTED

2401L     ERROR_OPEN_FILES

2402L     ERROR_ACTIVE_CONNECTIONS

2404L     ERROR_DEVICE_IN_USE

3000L     ERROR_UNKNOWN_PRINT_MONITOR

3001L     ERROR_PRINTER_DRIVER_IN_USE

3002L     ERROR_SPOOL_FILE_NOT_FOUND

3003L     ERROR_SPL_NO_STARTDOC

3004L     ERROR_SPL_NO_ADDJOB

3005L     ERROR_PRINT_PROCESSOR_ALREADY_INSTALLED

3006L     ERROR_PRINT_MONITOR_ALREADY_INSTALLED

3007L     ERROR_INVALID_PRINT_MONITOR

3008L     ERROR_PRINT_MONITOR_IN_USE

3009L     ERROR_PRINTER_HAS_JOBS_QUEUED

3010L     ERROR_SUCCESS_REBOOT_REQUIRED

3011L     ERROR_SUCCESS_RESTART_REQUIRED

4000L     ERROR_WINS_INTERNAL

4001L     ERROR_CAN_NOT_DEL_LOCAL_WINS

4002L     ERROR_STATIC_INIT

4003L     ERROR_INC_BACKUP

4004L     ERROR_FULL_BACKUP

4005L     ERROR_REC_NON_EXISTENT

4006L     ERROR_RPL_NOT_ALLOWED

6118L     ERROR_NO_BROWSER_SERVERS_FOUND


_hread

The _hread function reads data from the specified file. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the ReadFile function.

long _hread(

HFILE hFile,	// handle to file
LPVOID lpBuffer,	// pointer to buffer for read data
long lBytes	// length, in bytes, of data buffer
);
Parameters

hFile

Identifies the specified file.

lpBuffer

Pointer to a buffer that contains the data read from the file.

lBytes

Specifies the number of bytes to be read from the file.

Return Values

The return value indicates the number of bytes actually read from the file. If the number of bytes read is less than lBytes, the function has reached the end of file (EOF) before reading the specified number of bytes.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

See Also

_hwrite, ReadFile


_hwrite

The _hwrite function writes data to the specified file. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the WriteFile function.

long _hwrite(

HFILE hFile,	// handle to file
LPCSTR lpBuffer,	// pointer to buffer for data to be written
long lBytes	// number of bytes to write
);
Parameters

hFile

Identifies the specified file.

lpBuffer

Pointer to a buffer that contains the data to be written to the file.

lBytes

Specifies the number of bytes to be written to the file.

Return Values

If the function succeeds, the return value indicates the number of bytes actually written to the file.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

See Also

_hread, WriteFile


_lclose

The _lclose function closes the specified file so that it is no longer available for reading or writing. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the CloseHandle function.

HFILE _lclose(

HFILE hFile	// handle to file to close
);
Parameters

hFile

Identifies the file to be closed. This handle is returned by the function that created or last opened the file.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

See Also

CloseHandle, CreateFile, _lopen


_lcreat

The _lcreat function creates or opens a specified file. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the CreateFile function.

HFILE _lcreat(

LPCSTR lpPathName,	// pointer to name of file to open
int iAttribute	// file attribute
);
Parameters

lpPathName

Pointer to a null-terminated string that names the file to be opened. The string must consist of characters from the Windows ANSI character set.

iAttribute

Specifies the file attributes. This parameter must be one of the following values:

Value	Meaning
0	Normal (can be read from or written to without restriction).
1	Read only (cannot be opened for write)
2	Hidden (not found by directory search)
4	System (not found by directory search)
Return Values

If the function succeeds, the return value is a file handle.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

Remarks

If the file does not exist, the _lcreat function creates a new file and opens it for writing. If the file exists, _lcreat truncates the file size to zero and opens it for reading and writing. When the function opens the file, the pointer is set to the beginning of the file.

The _lcreat function should be used carefully. It can open any file, even one already opened by another function.

See Also

CreateFile, _lopen


_llseek

The _llseek function repositions the file pointer in a previously opened file. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the SetFilePointer function.

LONG _llseek(

HFILE hFile,	// handle to file
LONG lOffset,	// number of bytes to move
int iOrigin	// position to move from
);
Parameters

hFile

Identifies the file.

lOffset

Specifies the number of bytes the file pointer is to be moved.

iOrigin

Specifies the starting position and direction of the file pointer. This parameter must be one of the following values:

Value	Meaning
FILE_BEGIN	Moves the file pointer lOffset bytes from the beginning of the file.
FILE_CURRENT	Moves the file pointer lOffset bytes from its current position.
FILE_END	Moves the file pointer lOffset bytes from the end of the file.
Return Values

If the function succeeds, the return value specifies the new offset of the pointer, in bytes, from the beginning of the file.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

Remarks

When a file is initially opened, the file pointer is set to the beginning of the file. The _llseek function moves the pointer an arbitrary amount without reading data, which facilitates random access to the file’s contents.

See Also

_lopen, SetFilePointer


_lopen

The _lopen function opens an existing file and sets the file pointer to the beginning of the file. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the CreateFile function.

HFILE _lopen(

LPCSTR lpPathName,	// pointer to name of file to open
int iReadWrite	// file access mode
);
Parameters

lpPathName

Pointer to a null-terminated string that names the file to open. The string must consist of characters from the Windows ANSI character set.

iReadWrite

Specifies the modes in which to open the file. This parameter consists of one access mode and an optional share mode. The access mode must be one of the following values:

Value	Meaning
OF_READ	Opens the file for reading only.
OF_READWRITE	Opens the file for reading and writing.
OF_WRITE	Opens the file for writing only.
The share mode can be one of the following values:

Value	Meaning
OF_SHARE_COMPAT	Opens the file in compatibility mode, enabling any process on a given computer to open the file any number of times. If the file has been opened by using any of the other share modes, _lopen fails.
OF_SHARE_DENY_NONE	Opens the file without denying other processes read or write access to the file. If the file has been opened in compatibility mode by any other process, _lopen fails.
OF_SHARE_DENY_READ	Opens the file and denies other processes read access to the file. If the file has been opened in compatibility mode or for read access by any other process, _lopen fails.
OF_SHARE_DENY_WRITE	Opens the file and denies other processes write access to the file. If the file has been opened in compatibility mode or for write access by any other process, _lopen fails.
OF_SHARE_EXCLUSIVE	Opens the file in exclusive mode, denying other processes both read and write access to the file. If the file has been opened in any other mode for read or write access, even by the current process, _lopen fails.
Return Values

If the function succeeds, the return value is a file handle.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

See Also

CreateFile


_lread

The _lread function reads data from the specified file. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the ReadFile function.

UINT _lread(

HFILE hFile,	// handle to file
LPVOID lpBuffer,	// pointer to buffer for read data
UINT uBytes	// length, in bytes, of data buffer
);
Parameters

hFile

Identifies the specified file.

lpBuffer

Pointer to a buffer that contains the data read from the file.

uBytes

Specifies the number of bytes to be read from the file.

Return Values

The return value indicates the number of bytes actually read from the file. If the number of bytes read is less than uBytes, the function has reached the end of file (EOF) before reading the specified number of bytes.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

See Also

_lwrite, ReadFile


_lwrite

The _lwrite function writes data to the specified file. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the WriteFile function.

UINT _lwrite(

HFILE hFile,	// handle to file
LPCSTR lpBuffer,	// pointer to buffer for data to be written
UINT uBytes	// number of bytes to write
);
Parameters

hFile

Identifies the specified file.

lpBuffer

Pointer to a buffer that contains the data to write to the file.

uBytes

Specifies the number of bytes to be written to the file.

Return Values

If the function succeeds, the return value indicates the number of bytes actually written to the file.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

See Also

_lread, WriteFile


AbnormalTermination

The AbnormalTermination function indicates whether the try block of a try-finally statement terminated normally. The function can be called only from within the finally block of a try-finally statement.

BOOL AbnormalTermination(VOID)

Parameters

This function has no parameters.

Return Values

If the try block of the try-finally statement terminated abnormally, the return value is nonzero.

If the try block of the try-finally statement terminated normally, the return value is zero.

Remarks

The try block terminates normally only if execution leaves the block sequentially after executing the last statement in the block. Statements (such as return, goto, continue, or break) that cause execution to leave the try block result in abnormal termination of the block. This is the case even if such a statement is the last statement in the try block.

Abnormal termination of a try block causes the system to search backward through all stack frames to determine whether any termination handlers must be called. This can result in the execution of hundreds of instructions, so it is important to avoid abnormal termination of a try block due to a return, goto, continue, or break statement. Note that these statements do not generate an exception, even though the termination is abnormal.


AbortDoc

The AbortDoc function stops the current print job and erases everything drawn since the last call to the StartDoc function. This function replaces the ABORTDOC printer escape.

int AbortDoc(

HDC hdc	// handle to device context
);
Parameters

hdc

Identifies the device context for the print job.

Return Values

If the function succeeds, the return value is greater than zero.

If the function fails, the return value is SP_ERROR. To get extended error information, call GetLastError.

Remarks

Applications should call the AbortDoc function to stop a print job if an error occurs, or to stop a print job after the user cancels that job. To end a successful print job, an application should call the EndDoc function.

If Windows Print Manager was used to start the print job, calling AbortDoc erases the entire spool job, so that the printer receives nothing. If Print Manager was not used to start the print job, the data may already have been sent to the printer. In this case, the printer driver resets the printer (when possible) and ends the print job.

See Also

EndDoc, SetAbortProc, StartDoc


AbortPath

The AbortPath function closes and discards any paths in the specified device context.

BOOL AbortPath(

HDC hdc	// handle to device context
);
Parameters

hdc

Identifies the device context from which a path will be discarded.

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.

Remarks

If there is an open path bracket in the given device context, the path bracket is closed and the path is discarded. If there is a closed path in the device context, the path is discarded.

See Also

BeginPath, EndPath


AbortPrinter

The AbortPrinter function deletes a printer’s spool file if the printer is configured for spooling.

BOOL AbortPrinter(

HANDLE hPrinter	// handle to printer object
);
Parameters

hPrinter

Identifies the printer from which the spool file is deleted.

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.

Remarks

If the printer is not configured for spooling, the AbortPrinter function has no effect.

The printer handle identified by the hPrinter parameter is returned by the OpenPrinter function.

See Also

OpenPrinter


AbortProc

The AbortProc function is an application-defined callback function that is called when a print job is to be canceled during spooling.

BOOL CALLBACK AbortProc(

HDC hdc,	// handle to device context
int iError	// error value
);
Parameters

hdc

Identifies the device context for the print job.

iError

Specifies whether an error has occurred. This parameter is zero if no error has occurred; it is SP_OUTOFDISK if Windows Print Manager is currently out of disk space and more disk space will become available if the application waits.

Return Values

The callback function should return TRUE to continue the print job or FALSE to cancel the print job.

Remarks

An application installs this callback function by calling the SetAbortProc function. The AbortProc function is a placeholder for the application-defined function name.

If the iError parameter is SP_OUTOFDISK, the application need not cancel the print job. If it does not cancel the job, it must yield to Print Manager by calling the PeekMessage or GetMessage function.

See Also

GetMessage, PeekMessage, SetAbortProc


AbortSystemShutdown

The AbortSystemShutdown function stops a system shutdown started by using the InitiateSystemShutdown function.

BOOL AbortSystemShutdown(

LPTSTR lpMachineName	// pointer to name of computer to stop shutting down
);
Parameters

lpMachineName

Pointer to the null-terminated string that specifies the network name of the computer where the shutdown is to be stopped. If lpMachineName is NULL or points to an empty string, the function stops the shutdown on the local computer.

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.

Remarks

The InitiateSystemShutdown function displays a dialog box that notifies the user that the system is shutting down. During the InitiateSystemShutdown time-out period, the AbortSystemShutdown function can prevent the system from shutting down.

To stop the local computer from shutting down, the calling process must have the SE_SHUTDOWN_NAME privilege. To stop a remote computer from shutting down, the calling process must have the SE_REMOTE_SHUTDOWN_NAME privilege on the remote computer. By default, users can enable the SE_SHUTDOWN_NAME privilege on the computer they are logged onto, and administrators can enable the SE_REMOTE_SHUTDOWN_NAME privilege on remote computers.

Failures of the AbortSystemShutdown function are typically due to an invalid computer name, an inaccessible computer, or insufficient privilege.

See Also

InitiateSystemShutdown


AccessCheck

The AccessCheck function is used by a server application to check a client’s access to an object against the access control associated with the object.

BOOL AccessCheck(

PSECURITY_DESCRIPTOR pSecurityDescriptor,	// pointer to security descriptor
HANDLE ClientToken,	// handle to client access token
DWORD DesiredAccess,	// access mask to request
PGENERIC_MAPPING GenericMapping,	// address of generic-mapping structure
PPRIVILEGE_SET PrivilegeSet,	// address of privilege-set structure
LPDWORD PrivilegeSetLength,	// size of privilege-set structure
LPDWORD GrantedAccess,	// address of granted access mask
LPBOOL AccessStatus	// address of flag indicating whether access granted
);
Parameters

pSecurityDescriptor

Pointer to a SECURITY_DESCRIPTOR structure against which access is checked.

ClientToken

Identifies an access token representing a client attempting to gain access.

This handle must be obtained from a communications session layer — for instance, a named pipe — to prevent possible security policy violations.

DesiredAccess

Specifies the access mask to be requested. This mask must have been mapped by the MapGenericMask function to contain no generic access rights.

GenericMapping

Pointer to the GENERIC_MAPPING structure associated with the object for which access is being checked.

PrivilegeSet

Pointer to a PRIVILEGE_SET structure that the function fills with any privileges used to perform the access validation. If no privileges were used, the buffer contains a privilege set consisting of zero privileges.

PrivilegeSetLength

Specifies the size, in bytes, of the buffer pointed to by the PrivilegeSet parameter.

GrantedAccess

Pointer to a variable the function fills with an access mask indicating which access rights were granted. If the function fails, this access mask is not supplied.

AccessStatus

Pointer to a flag indicating the success or failure of the access check. If AccessStatus is TRUE, the access token has the requested access to the object. If AccessStatus is FALSE, the access token does not have the requested access. When this parameter is FALSE, the application can use the GetLastError function to get extended error information.

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.

Remarks

The AccessCheck function compares the specified security descriptor with the specified access token and indicates, in the AccessStatus parameter, whether access is granted or denied. If access is granted, the requested access mask becomes the object’s granted access mask.

Only the discretionary access-control list is examined during an access check.

See Also

AccessCheckAndAuditAlarm, AreAllAccessesGranted, AreAnyAccessesGranted, GENERIC_MAPPING, MapGenericMask, PrivilegeCheck, PRIVILEGE_SET, SECURITY_DESCRIPTOR


AccessCheckAndAuditAlarm

The AccessCheckAndAuditAlarm function performs an access validation and generates corresponding audit messages. An application can also use this function to determine whether necessary privileges are held by a client process. This function is generally used by a server application impersonating a client process. Alarms are not supported in the current version of Windows NT.

BOOL AccessCheckAndAuditAlarm(

LPCTSTR SubsystemName,	// address of string for subsystem name
LPVOID HandleId,	// address of handle identifier
LPTSTR ObjectTypeName,	// address of string for object type
LPTSTR ObjectName,	// address of string for object name
PSECURITY_DESCRIPTOR SecurityDescriptor,	// address of security descriptor
DWORD DesiredAccess,	// mask for requested access rights
PGENERIC_MAPPING GenericMapping,	// address of GENERIC_MAPPING
BOOL ObjectCreation,	// object-creation flag
LPDWORD GrantedAccess,	// address of mask for granted rights
LPBOOL AccessStatus,	// address of flag for results
LPBOOL pfGenerateOnClose	// pointer to flag for audit generation
);
Parameters

SubsystemName

Pointer to a null-terminated string specifying the name of the subsystem calling the function — for example, “DEBUG” or “WIN32.”

HandleId

Points to a unique 32-bit value representing the client’s handle to the object. If the access is denied, this value is ignored and may be reused.

ObjectTypeName

Points to a null-terminated string specifying the type of object being created or accessed. This string appears in the audit log for the object.

ObjectName

Points to a null-terminated string specifying the name of the object being created or accessed. This string appears in the audit log for the object.

SecurityDescriptor

Points to the SECURITY_DESCRIPTOR structure against which access is checked.

DesiredAccess

Specifies an access mask giving the requested access rights. This mask must have been mapped to contain no generic access rights by the MapGenericMask function.

GenericMapping

Points to the GENERIC_MAPPING structure associated with the type of object being examined.

ObjectCreation

Specifies a flag that determines whether the calling application will create a new object when access is granted. If this flag is TRUE, the application creates a new object; if it is FALSE, the application opens an existing object.

GrantedAccess

Points to a buffer that receives an access mask indicating which access rights were granted, if the function succeeds.

AccessStatus

Points to a flag that the function sets to indicate the success or failure of the access check. If access is granted, this flag is TRUE; otherwise, it is FALSE.

pfGenerateOnClose

Pointer to a flag set by the audit-generation routine when the function returns. This flag must be passed to the ObjectCloseAuditAlarm function when the object handle is closed.

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.

Remarks

The AccessCheckAndAuditAlarm function compares the specified security descriptor with the impersonation access token of the calling process and indicates whether access is granted or denied. If access is granted, the requested access mask becomes the granted access mask for the object. This function also generates any necessary audit messages as a result of the access attempt.

This function requires the calling process to have the SE_AUDIT_NAME privilege. The test for this privilege is performed against the primary token of the calling process, not the impersonation token of the thread.

See Also

AccessCheck, AreAllAccessesGranted, AreAnyAccessesGranted, GENERIC_MAPPING, MapGenericMask, ObjectCloseAuditAlarm, ObjectOpenAuditAlarm, ObjectPrivilegeAuditAlarm, PrivilegeCheck, PrivilegedServiceAuditAlarm, SECURITY_DESCRIPTOR


AcsLan

The AcsLan function is used to communicate with other computers or network peripheral devices, such as printers, using the data link control (DLC) protocol. The caller submits requests by filling in a command control block (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. This is unlike the Netbios function, for example, which has commands complete synchronously or asynchronously as requested by the caller.

There are some differences between NT DLC and the CCB2 interface. The most notable difference is that the buffer pool must be specified on an open adapter instance basis and not specified per-SAP (service-access point). After an adapter has been opened using the DIR.OPEN.ADAPTER command, a buffer pool must be given to the DLC driver using BUFFER.CREATE.

ACSLAN_STATUS AcsLan(

PLLC_CCB pCcb,	// pointer to command control block
PLLC_CCB *ppBadCcb	// pointer to pointer for invalid CCB
);
Parameters

pCcb

Pointer to an LLC_CCB structure describing the function being performed. For information about this structure, see documentation for IBM LAN.

ppBadCcb

Pointer to a pointer to an LLC_CCB structure. This parameter is used when a chain of LLC_CCB structures is submitted. If the parameter is not NULL on input, this pointer will contain a pointer to the first invalid LLC_CCB structure discovered 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 request has been processed and passed to the DLC driver. The command may or may not have already completed, depending on whether it is a synchronous or asynchronous command and depending on other timing considerations. This value does not mean that the command completed successfully. The caller must check the uchDlcStatus member in the LLC_CCB structure to determine whether the request succeeded or failed.
ACSLAN_STATUS_INVALID_CCB_POINTER	A pointer in the the LLC_CCB structure, or the parameter table is invalid.
ACSLAN_STATUS_CCB_IN_ERROR	A problem was detected with the LLC_CCB structure. The caller should 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.
See Also

Netbios


ActivateKeyboardLayout

The implementations of ActivateKeyboardLayout in Windows 95 and Windows NT are substantially different. To accommodate these differences, this reference page first presents the Windows 95 implementation in its entirety, followed by the Windows NT version.

Windows 95:

The ActivateKeyboardLayout function sets the input language for the current thread. This function accepts a keyboard layout handle that identifies a locale as well as the physical layout of the keyboard.

HKL ActivateKeyboardLayout(

HKL hkl,	// handle to keyboard layout
UINT Flags	// keyboard layout flags
);
Parameters

hkl

Handle to a keyboard layout or a zero-extended locale identifier. This parameter can be any valid keyboard layout handle obtained using the LoadKeyboardLayout or GetKeyboardLayoutList function or one of the following values:

Value	Meaning
HKL_NEXT	Selects the next layout in the keyboard layouts list maintained by the system.
HKL_PREV	Selects the previous layout in the keyboards layout list maintained by the system.
Flags

Specifies the keyboard layout flags. The value of this parameter can be:

Value	Meaning
KLF_REORDER	Reorders the keyboard layouts list by moving the given keyboard layout handle to the head of the list. If this value is not given, the list is rotated without a change of order. For example, if a user had an English layout active, as well as having French, German and Spanish layouts loaded (in that order), then activating the German layout with the KLF_REORDER bit set would produce the following order: German, English, French, Spanish. Activating the German layout without the KLF_REORDER value set would produce the following order: German, Spanish, English, French.
Return Values

If the function succeeds, the return value is the previous keyboard layout handle. Otherwise, it is zero. To get extended error information, use the GetLastError function.

Remarks

Several keyboard layouts can be loaded at any one time, but only one is active at a time. Loading multiple keyboard layouts makes it possible to rapidly switch between layouts.

An application can create a valid keyboard layout handle by setting the high word to zero and the low word to a locale identifier. Using such keyboard layout handles changes the input language without affecting the physical layout.

When multiple input method editors (IMEs) are allowed for each locale, passing in a keyboard layout handle in which the high word (the device handle) is zero activates the first IME in the list “belonging” to the locale.

See Also

LoadKeyboardLayout, GetKeyboardLayoutName, UnloadKeyboardLayout

Windows NT:

The ActivateKeyboardLayout function activates a different keyboard layout and sets the active keyboard layout for the entire system rather than the calling thread.

BOOL ActivateKeyboardLayout(

HKL hkl,	// handle to keyboard layout
UINT Flags	// keyboard layout flags
);
Parameters

hkl

Identifies the keyboard layout to be activated. The layout must have been loaded by a previous call to the LoadKeyboardLayout function. This parameter must be either the handle to a keyboard layout or one of the following values:

Value	Meaning
HKL_NEXT	Selects the next layout in the circular list of loaded layouts maintained by the system.
HKL_PREV	Selects the previous layout in the circular list of loaded layouts maintained by the system.
Flags

Specifies how the keyboard layout is to be activated. This parameter can be one of the following values:

Value	Meaning
KLF_REORDER	If this bit is set, the system’s circular list of loaded keyboard layouts is reordered. If this bit is not set, the list is rotated without a change of order. For example, if a user had an English layout active, as well as having French, German and Spanish layouts loaded (in that order), then activating the German layout with the KLF_REORDER bit set would produce the following order: German, English, French, Spanish. Activating the German layout without the KLF_REORDER bit set would produce the following order: German, Spanish, English, French. If less than three keyboard layouts are loaded, the value of this flag is irrelevant.
KLF_UNLOADPREVIOUS	The previously active layout is unloaded.
Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

Several keyboard layouts can be loaded at any one time, but only one is active at a time. Loading multiple keyboard layouts makes it possible to rapidly switch between layouts.

See Also

LoadKeyboardLayout, GetKeyboardLayoutName, UnloadKeyboardLayout


AddAccessAllowedAce

The AddAccessAllowedAce function adds an access-allowed ACE to an ACL. The access is granted to a specified SID.

An ACE is an access-control entry. An ACL is an access-control list. A SID is a security identifier.

BOOL AddAccessAllowedAce(

PACL pAcl,	// pointer to access-control list
DWORD dwAceRevision,	// ACL revision level
DWORD AccessMask,	// access mask
PSID pSid	// pointer to security identifier
);
Parameters

pAcl

Pointer to an ACL structure. This function adds an access-allowed ACE to this ACL. The ACE is in the form of an ACCESS_ALLOWED_ACE structure.

dwAceRevision

Specifies the revision level of the ACL being modified. Currently, this value must be ACL_REVISION.

AccessMask

Specifies the mask of access rights to be granted to the specified SID.

pSid

Pointer to the SID structure representing a process being granted access.

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.

Remarks

The addition of an access-allowed ACE to an ACL is the most common form of ACL modification.

The ACE_HEADER structure placed in the ACE by the AddAccessAllowedAce function specifies a type and size, but provides no inheritance and no ACE flags.

See Also

ACCESS_ALLOWED_ACE, ACE_HEADER, ACL, AddAccessDeniedAce, AddAce, AddAuditAccessAce, DeleteAce, GetAce


AddAccessDeniedAce

The AddAccessDeniedAce function adds an access-denied ACE to an ACL. The access is denied to a specified SID.

An ACE is an access-control entry. An ACL is an access-control list. A SID is a security identifier.

BOOL AddAccessDeniedAce(

PACL pAcl,	// pointer to access-control list
DWORD dwAceRevision,	// ACL revision level
DWORD AccessMask,	// access mask
PSID pSid	// pointer to security identifier
);
Parameters

pAcl

Pointer to an ACL structure. This function adds an access-denied ACE to this ACL. The ACE is in the form of an ACCESS_DENIED_ACE structure.

dwAceRevision

Specifies the revision level of the ACL being modified. Currently, this value must be ACL_REVISION.

AccessMask

Specifies the mask of access rights being denied to the specified SID.

pSid

Pointer to the SID structure representing the process being denied access.

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.

Remarks

The ACE_HEADER structure placed in the ACE by the AddAccessDeniedAce function specifies a type and size, but provides no ACE flags.

See Also

ACCESS_DENIED_ACE, ACE_HEADER, ACL, AddAccessAllowedAce, AddAce, AddAuditAccessAce, DeleteAce, GetAce


AddAce

The AddAce function adds one or more ACEs to a specified ACL.

An ACE is an access-control entry. An ACL is an access-control list.

BOOL AddAce(

PACL pAcl,	// pointer to access-control list
DWORD dwAceRevision,	// ACL revision level
DWORD dwStartingAceIndex,	// index of ACE position in ACL
LPVOID pAceList,	// pointer to one or more ACEs
DWORD nAceListLength	// size of buffer for ACEs
);
Parameters

pAcl

Pointer to an ACL structure. This function adds an ACE to this ACL.

dwAceRevision

Specifies the revision level of the ACL being modified. Currently, this value must be ACL_REVISION.

dwStartingAceIndex

Specifies the position in the ACL’s list of ACEs at which to add new ACEs. A value of zero inserts the ACEs at the beginning of the list. A value of MAXDWORD appends the ACEs to the end of the list.

pAceList

Pointer to a list of one or more ACEs to be added to the specified ACL. The ACEs in the list must be stored contiguously.

nAceListLength

Specifies the size, in bytes, of the input buffer pointed to by the pAceList parameter.

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.

Remarks

Applications frequently use the FindFirstFreeAce and GetAce functions when using the AddAce function to manipulate an ACL. In addition, the ACL_SIZE_INFORMATION structure retrieved by the GetAclInformation function contains the size of the ACL and the number of ACEs it contains.

See Also

ACL, ACL_SIZE_INFORMATION, AddAccessAllowedAce, AddAccessDeniedAce, AddAuditAccessAce, DeleteAce, FindFirstFreeAce, GetAce, GetAclInformation


AddAtom

The AddAtom function adds a character string to the local atom table and returns a unique value (an atom) identifying the string.

ATOM AddAtom(

LPCTSTR lpString	// pointer to string to add
);
Parameters

lpString

Pointer to the null-terminated string to be added. The string can have a maximum size of 255 bytes. Strings differing only in case are considered identical. The case of the first string added is preserved and returned by the GetAtomName function.

Return Values

If the function succeeds, the return value is the newly created atom.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The AddAtom function stores no more than one copy of a given string in the atom table. If the string is already in the table, the function returns the existing atom and, in the case of a string atom, increments the string’s reference count.

The MAKEINTATOM macro can be used to convert a WORD value into a string that can be added to the atom table by using the AddAtom function.

AddAtom returns a string atom whose value is in the range 0xC000 through 0xFFFF.

If lpString has the form “#1234”, AddAtom returns an integer atom whose value is the 16-bit representation of the decimal number specified in the string (0x04D2, in this example). If the decimal value specified is 0x0000 or a value in the range 0xC000 through 0xFFFF, the return value is zero, indicating an error. If lpString is in the range 0x0001 through 0xBFFF, the return value is the low-order word of lpString.

See Also

DeleteAtom, FindAtom, GetAtomName, GlobalAddAtom, GlobalDeleteAtom, GlobalFindAtom, GlobalGetAtomName, MAKEINTATOM


AddAuditAccessAce

The AddAuditAccessAce function adds a system-audit ACE to a system ACL. The access of a specified SID is audited.

An ACE is an access-control entry. An ACL is an access-control list. A SID is a security identifier.

BOOL AddAuditAccessAce(

PACL pAcl,	// pointer to access-control list
DWORD dwAceRevision,	// ACL revision level
DWORD dwAccessMask,	// access mask
PSID pSid,	// pointer to security identifier
BOOL bAuditSuccess,	// flag for auditing successful access
BOOL bAuditFailure	// flag for auditing unsuccessful access attempts
);
Parameters

pAcl

Pointer to an ACL structure. This function adds a system-audit ACE to this ACL. The ACE is in the form of an SYSTEM_AUDIT_ACE structure.

dwAceRevision

Specifies the revision level of the ACL being modified. Currently, this value must be ACL_REVISION.

dwAccessMask

Specifies the mask of access rights to be audited for the specified SID.

pSid

Pointer to the SID structure representing the process whose access is being audited.

bAuditSuccess

Specifies whether successful access attempts are to be audited. Set this flag to TRUE to enable auditing; otherwise, set it to FALSE.

bAuditFailure

Specifies whether unsuccessful access attempts are to be audited. Set this flag to TRUE to enable auditing; otherwise, set it to FALSE.

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.

Remarks

The ACE_HEADER structure placed in the ACE by the AddAuditAccessAce function specifies a type and size, but provides no ACE flags.

See Also

ACE_HEADER, ACL, AddAccessAllowedAce, AddAccessDeniedAce, AddAce, DeleteAce, GetAce, SID, SYSTEM_AUDIT_ACE


AddFontResource

The AddFontResource function adds the font resource from the specified file to the Windows font table. The font can subsequently be used for text output by any Windows-based application.

int AddFontResource(

LPCTSTR lpszFilename	// pointer to font-resource filename
);
Parameters

lpszFilename

Pointer to a null-terminated character string that contains a valid font file filename. The filename may specify either a .FON font resource file, a .FNT raw bitmap font file, a .TTF raw TrueType file, or a .FOT TrueType resource file.

Return Values

If the function succeeds, the return value specifies the number of fonts added.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Any application that adds or removes fonts from the Windows font table should notify other windows of the change by sending a WM_FONTCHANGE message to all top-level windows in the operating system. The application should send this message by calling the SendMessage function and setting the hwnd parameter to HWND_BROADCAST.

When an application no longer needs a font resource that it loaded by calling the AddFontResource function, it must remove the resource by calling the RemoveFontResource function.

See Also

RemoveFontResource, SendMessage


AddForm

The AddForm function adds a form to the list of available forms that can be selected for the specified printer.

BOOL AddForm(

HANDLE hPrinter,	// handle to printer object
DWORD Level,	// data-structure level
LPBYTE pForm	// pointer to form info. data structure
);
Parameters

hPrinter

Identifies the printer that supports printing with the specified form.

Level

Specifies the level of the structure to which pForm points. This value must be 1.

pForm

Pointer to a FORM_INFO_1 structure.

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.

Remarks

The printer handle identified by the hPrinter parameter is returned by the OpenPrinter function.

An application can determine which forms are available for a printer by calling the EnumForms function.

See Also

EnumForms, FORM_INFO_1, OpenPrinter


AddJob

The AddJob function obtains a path string that specifies a file that you can use to store a spooled print job.

BOOL AddJob(

HANDLE hPrinter,	// specifies printer for the print job
DWORD Level,	// specifies version of print job information data structure
LPBYTE pData,	// pointer to buffer to receive print job information data
DWORD cbBuf,	// specifies size of buffer pointed to by pData
LPDWORD pcbNeeded	// pointer to variable to receive size of print job information data
);
Parameters

hPrinter

Handle that specifies the printer for the print job. This must be a local printer that is configured as a spooled printer. If hPrinter is a handle to a remote printer connection, or if the printer is configured for direct printing, the AddJob function fails.

Level

Specifies the version of the print job information data structure that the function stores into the buffer pointed to by pData. Set this parameter to one.

pData

Pointer to a buffer to receive an ADDJOB_INFO_1 data structure and a path string.

cbBuf

Specifies the size, in bytes, of the buffer pointed to by pData. The buffer needs to be large enough to contain an ADDJOB_INFO_1 structure and a path string.

pcbNeeded

Pointer to a variable to receive the total size, in bytes, of the ADDJOB_INFO_1 data structure plus the path string. If this value is less than or equal to cbBuf and the function succeeds, this is the actual number of bytes written to the buffer pointed to by pData. If this number is greater than cbBuf, the buffer is too small, and you must call the function again with a buffer size at least as large as *pcbNeeded.

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.

Remarks

You can call the CreateFile function to open the spool file specified by the Path member of the ADDJOB_INFO_1 structure, and then call the WriteFile function to write print job data to it. Once that is done, call ScheduleJob to notify the print spooler that the print job can now be scheduled by the spooler for printing.

See Also

ADDJOB_INFO_1, CreateFile, OpenPrinter, ScheduleJob, WriteFile


AddMonitor

The AddMonitor function installs a local printer monitor and links the configuration, data, and monitor files. Future releases of Windows NT may allow remote installation of printer monitors.

BOOL AddMonitor (

LPTSTR pName,	// pointer to server name
DWORD Level,	// monitor info. structure level
LPBYTE pMonitors	// pointer to monitor info. structure
);
Parameters

pName

Pointer to a null-terminated string that specifies the name of the server on which the monitor should be installed. For this release of Windows NT, monitors may only be installed locally, so this string should be NULL.

Level

Specifies the version of the structure to which pMonitors points. This value must be 2.

pMonitors

Pointer to a MONITOR_INFO_2 structure.

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.

Remarks

Before an application calls the AddMonitor function, all files required by the monitor must be copied to the SYSTEM32 directory.

An application can determine which printer monitors are currently installed by calling the EnumMonitors function.

A monitor added by AddMonitor may be removed by calling DeleteMonitor.

See Also

DeleteMonitor, EnumMonitors, MONITOR_INFO_2


AddPort

The AddPort function adds the name of a port to the list of supported ports. The AddPort function is exported by the print monitor.

BOOL AddPort(

LPTSTR pName,	// pointer to a server name
HWND hWnd,	// handle to parent window
LPTSTR pMonitorName	// pointer to a monitor name
);
Parameters

pName

Pointer to a zero-terminated string that specifies the name of the server to which the port is connected. If this parameter is NULL, the port is local.

hWnd

Handle to the parent window of the AddPort dialog box.

pMonitorName

Pointer to a zero-terminated string that specifies the monitor associated with the port.

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.

Remarks

The AddPort function browses the network to find existing ports, and displays a dialog box for the user. The AddPort function should validate the port name entered by the user by calling EnumPorts to ensure that no duplicate names exist.

The caller of the AddPort function must have SERVER_ACCESS_ADMINISTER access to the server to which the port is connected.

See Also

DeletePort EnumPorts SetPort


AddPrinter

The AddPrinter function adds a printer to the list of supported printers for a specified server.

HANDLE AddPrinter(

LPTSTR pName,	// pointer to server name
DWORD Level,	// printer info. structure level
LPBYTE pPrinter	// pointer to structure
);
Parameters

pName

Pointer to a null-terminated string that specifies the name of the server on which the printer’s print processor should be installed. If this string is NULL, the print processor is installed locally.

Level

Specifies the version of the structure to which pPrinter points. This value must be 2.

pPrinter

Pointer to a PRINTER_INFO_2 structure that contains information about the printer. You must specify non-NULL values for the pPrinterName, pPortName, pDriverName, and pPrintProcessor members of this structure before calling AddPrinter.

Return Values

If the function succeeds, the return value is the handle to a new printer object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The following list identifies the members of the PRINTER_INFO_2 structure that can be set before the AddPrinter function is called.

Attributes	pPrintProcessor
DefaultPriority	Priority
pComment	pSecurityDescriptor
pDatatype	pSepFile
pDevMode	pShareName
pLocation	StartTime
pParameters	UntilTime
The Status, cJobs, and AveragePPM members of the PRINTER_INFO_2 structure are reserved for use by the GetPrinter function. They must not be set before calling AddPrinter.

If pSecurityDescriptor is NULL, the system assigns a default security descriptor to the printer.

After an application creates a printer object with the AddPrinter function, it must use the PrinterProperties function to specify the correct settings for the printer driver associated with the printer object.

The AddPrinter function returns an error if a printer object with the same name already exists, unless that object is marked as pending deletion. In that case, the existing printer will not be deleted, and the AddPrinter creation parameters will be used to change the existing printer settings (as if the application had used the SetPrinter function).

Windows NT:The caller of the AddPrinter function must have SERVER_ACCESS_ADMINISTER access to the server on which the printer is to be created. The handle returned by the function will have PRINTER_ALL_ACCESS permission, and can be used to perform administrative operations on the printer.

Windows 95: This access validation is not supported in Windows 95.

Use the EnumPrintProcessors function to enumerate the set of print processors installed on a server. Use the EnumPrintProcessorDatatypes function to enumerate the set of datatypes that a print processor supports.

See Also

ClosePrinter, DeletePrinter, EnumPrintProcessors, EnumPrintProcessorDatatypes, GetPrinter, PRINTER_INFO_2, PrinterProperties, SetPrinter


AddPrinterConnection

The AddPrinterConnection function adds a connection to the specified printer for the current user.

BOOL AddPrinterConnection (

LPTSTR pName	// pointer to printer name
);
Parameters

pName

Pointer to a null-terminated string that specifies the name of a printer that the current user wishes to establish a connection to.

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.

Remarks

When Windows NT makes a connection to a printer, it may need to copy printer driver files to the workstation. If the user does not have permission to copy files to the appropriate location, the AddPrinterConnection function fails, and GetLastError returns ERROR_ACCESS_DENIED.

A printer connection established by calling AddPrinterConnection will be enumerated when EnumPrinters is called with dwType set to PRINTER_ENUM_CONNECTION.

See Also

ConnectToPrinterDlg, DeletePrinterConnection, EnumPrinters


AddPrinterDriver

The AddPrinterDriver function installs a local or remote printer driver and links the configuration, data, and driver files.

BOOL AddPrinterDriver(

LPTSTR pName,	// pointer to server name
DWORD Level,	// printer info. structure level
LPBYTE pDriverInfo	// pointer to printer info. structure
);
Parameters

pName

Pointer to a null-terminated string that specifies the name of the server on which the driver should be installed.

If pName is NULL, the driver will be installed locally.

Level

Specifies the version of the structure to which pDriverInfo points.

This value can be either 2 or 3.

pDriverInfo

Pointer to either a DRIVER_INFO_2 structure or a DRIVER_INFO_3 structure. If Level is 2, this parameter receives a DRIVER_INFO_2 structure. If Level is 3, this parameter receives a DRIVER_INFO_3 structure.

If the pEnvironment member of the structure pointed to by pDriverInfo is NULL, the current environment of the caller/client (not of the destination/server) is used.

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.

Remarks

Before an application calls the AddPrinterDriver function, all files required by the driver must be copied to the system’s printer-driver directory. An application can retrieve the name of this directory by calling the GetPrinterDriverDirectory function.

An application can determine which printer drivers are currently installed by calling the EnumPrinterDrivers function.

See Also

DRIVER_INFO_2, DRIVER_INFO_3, EnumPrinterDrivers, GetPrinterDriverDirectory


AddPrintProcessor

The AddPrintProcessor function installs a print processor on the specified server and adds the print-processor name to an internal list of supported print processors.

BOOL AddPrintProcessor(

LPTSTR pName,	// pointer to server name
LPTSTR pEnvironment,	// pointer to environment name
LPTSTR pPathName,	// pointer to path
LPTSTR pPrintProcessorName	// pointer to print-processor name
);
Parameters

pName

Pointer to a null-terminated string that specifies the name of the server on which the print processor should be installed. If this parameter is NULL, the print processor is installed locally.

pEnvironment

Pointer to a null-terminated string that specifies the environment. For example, “Windows x86” specifies Windows running on an Intel 80386 or 80486 processor. If this parameter is NULL, the current environment of the caller/client (not of the destination/server) is used.

pPathName

Pointer to a null-terminated string that specifies the name of the file that contains the print processor. This file must be in the system print-processor directory.

pPrintProcessorName

Pointer to a null-terminated string that specifies the name of the print processor.

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.

Remarks

Before calling the AddPrintProcessor function, an application should verify that the file containing the print processor is stored in the system print-processor directory. An application can retrieve the name of the system print-processor directory by calling the GetPrintProcessorDirectory function.

An application can determine the name of existing print processors by calling the EnumPrintProcessors function.

See Also

EnumPrintProcessors, GetPrintProcessorDirectory


AddPrintProvidor

The AddPrintProvidor function installs a local printer provider and links the configuration, data, and provider files. Future releases of Windows may allow remote installation of printer providers.

BOOL AddPrintProvidor (

LPTSTR pName,	// pointer to server name
DWORD Level,	// provider information structure level
LPBYTE pProvidorInfo	// pointer to provider information structure
);
Parameters

pName

Pointer to a null-terminated string that specifies the name of the server on which the provider should be installed. For this release of Windows 95 and Windows NT, providers may only be installed locally, so this parameter should be NULL.

Level

Specifies the level of the structure to which pProvidorInfo points. This value must be 1.

pProvidorInfo

Pointer to a PROVIDOR_INFO_1 structure.

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.

Remarks

Before an application calls the AddPrintProvidor function, all files required by the provider must be copied to the SYSTEM32 directory.

A provider added by AddPrintProvidor may be removed by calling DeletePrintProvidor.

See Also

DeletePrintProvidor, PROVIDOR_INFO_1


AddPropSheetPageProc

The AddPropSheetPageProc function specifies an application-defined callback function that a property sheet extension uses to add a page to a property sheet.

BOOL CALLBACK AddPropSheetPageProc(

HPROPSHEETPAGE hpage,
LPARAM lParam
);
Parameters

hpage

Handle to a property sheet page.

lParam

Application-defined 32-bit value.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


AdjustTokenGroups

The AdjustTokenGroups function adjusts groups in the specified access token. TOKEN_ADJUST_GROUPS access is required to enable or disable groups in an access token.

BOOL AdjustTokenGroups(

HANDLE TokenHandle,	// handle to token that contains groups
BOOL ResetToDefault,	// flag for default settings
PTOKEN_GROUPS NewState,	// address of address of new group information
DWORD BufferLength,	// size of buffer for previous information
PTOKEN_GROUPS PreviousState,	// address of previous group information
PDWORD ReturnLength	// address of required buffer size
);
Parameters

TokenHandle

Identifies the access token containing the groups to be modified.

ResetToDefault

Specifies whether the groups are to be set to their default enabled and disabled states. If this value is TRUE, the groups are set to their default states and the NewState parameter is ignored. If this value is FALSE, the groups are set according to the information pointed to by the NewState parameter.

NewState

Points to a TOKEN_GROUPS structure containing the groups whose states are to be set. If the ResetToDefault parameter is FALSE, the function sets each of the groups to the value of that group’s SE_GROUP_ENABLED flag in the TOKEN_GROUPS structure. If ResetToDefault is TRUE, this parameter is ignored.

BufferLength

Specifies the size, in bytes, of the buffer pointed to by the PreviousState parameter. This parameter can be NULL if the PreviousState parameter is NULL.

PreviousState

Points to a buffer receiving a TOKEN_GROUPS structure containing the previous state of any groups the function modifies. The token must be open for TOKEN_QUERY access to use this parameter. This parameter can be NULL.

If a buffer is specified but it does not contain enough space to receive the complete list of modified groups, no group states are changed and the function fails. In this case, the function sets the variable pointed to by the ReturnLength parameter to the number of bytes required to hold the complete list of modified groups.

ReturnLength

Points to a variable set by the function that contains the actual number of bytes needed for the buffer pointed to by the PreviousState parameter. This parameter can be NULL and is ignored if PreviousState is NULL.

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.

Remarks

The information retrieved in the PreviousState parameter is formatted as a TOKEN_GROUPS structure. This means a pointer to the buffer can be passed as the NewState parameter in a subsequent call to the AdjustTokenGroups function, restoring the original state of the groups.

The NewState parameter can list groups to be changed that are not present in the access token. This does not affect the successful modification of the groups in the token.

Mandatory groups cannot be disabled. They are identified by the SE_GROUP_MANDATORY flag in the TOKEN_GROUPS structure. If an attempt is made to disable any mandatory groups, AdjustTokenGroups fails and leaves the state of all groups unchanged.

See Also

AdjustTokenPrivileges, GetTokenInformation, OpenProcessToken, OpenThreadToken, SetTokenInformation, TOKEN_GROUPS


AdjustTokenPrivileges

The AdjustTokenPrivileges function enables or disables privileges in the specified access token. Enabling or disabling privileges in an access token requires TOKEN_ADJUST_PRIVILEGES access.

BOOL AdjustTokenPrivileges(

HANDLE TokenHandle,	// handle to token that contains privileges
BOOL DisableAllPrivileges,	// flag for disabling all privileges
PTOKEN_PRIVILEGES NewState,	// pointer to new privilege information
DWORD BufferLength,	// size, in bytes, of the PreviousState buffer
PTOKEN_PRIVILEGES PreviousState,	// receives original state of changed privileges
PDWORD ReturnLength	// receives required size of the PreviousState buffer
);
Parameters

TokenHandle

Identifies the access token that contains the privileges to be modified.

DisableAllPrivileges

Specifies whether the function disables all of the token’s privileges. If this value is TRUE, the function disables all privileges and ignores the NewState parameter. If it is FALSE, the function modifies privileges based on the information pointed to by the NewState parameter.

NewState

Pointer to a TOKEN_PRIVILEGES structure that specifies an array of privileges and their attributes. If the DisableAllPrivileges parameter is FALSE, AdjustTokenPrivileges enables or disables these privileges for the token. If you set the SE_PRIVILEGE_ENABLED attribute for a privilege, the function enables that privilege; otherwise, it disables the privilege.

If DisableAllPrivileges is TRUE, the function ignores this parameter.

BufferLength

Specifies the size, in bytes, of the buffer pointed to by the PreviousState parameter. This parameter can be NULL if the PreviousState parameter is NULL.

PreviousState

Pointer to a buffer that the function fills with a TOKEN_PRIVILEGES structure containing the previous state of any privileges the function modifies. The token must be open for TOKEN_QUERY access to use this parameter. This parameter can be NULL.

If you specify a buffer that is too small to receive the complete list of modified privileges, the function fails and does not adjust any privileges. In this case, the function sets the variable pointed to by the ReturnLength parameter to the number of bytes required to hold the complete list of modified privileges.

ReturnLength

Pointer to a variable that receives the required size, in bytes, of the buffer pointed to by the PreviousState parameter. This parameter can be NULL if PreviousState is NULL.

Return Values

If the function succeeds, the return value is nonzero. To determine whether the function adjusted all of the specified privileges, call GetLastError, which returns one of the following values when the function succeeds:

Value	Description
ERROR_SUCCESS	The function adjusted all specified privileges.
ERROR_NOT_ALL_ASSIGNED	The token does not have one or more of the privileges specified in the NewState parameter. The function may succeed with this error value even if no privileges were adjusted. The PreviousState parameter indicates the privileges that were adjusted.
If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The AdjustTokenPrivileges function cannot add new privileges to the access token. It can only enable or disable the token’s existing privileges. To determine the token’s privileges, call the GetTokenInformation function.

Note that the NewState parameter can specify privileges that the token does not have, without causing the function to fail. In this case, the function adjusts the privileges that the token does have, ignores the other privileges, and returns success. Call the GetLastError function to determine whether the function adjusted all of the specified privileges. The PreviousState parameter indicates the privileges that were adjusted.

The PreviousState parameter retrieves a TOKEN_PRIVILEGES structure containing the the original state of the adjusted privileges. To restore the original state, pass the PreviousState pointer as the NewState parameter in a subsequent call to the AdjustTokenPrivileges function

See Also

AdjustTokenGroups, GetTokenInformation, OpenProcessToken, OpenThreadToken, SetTokenInformation, TOKEN_PRIVILEGES


AdjustWindowRect

The AdjustWindowRect function calculates the required size of the window rectangle based on the desired client-rectangle size. The window rectangle can then be passed to the CreateWindowEx function to create a window whose client area is the desired size.

BOOL AdjustWindowRect(

LPRECT lpRect,	// pointer to client-rectangle structure
DWORD dwStyle,	// window styles
BOOL bMenu	// menu-present flag
);
Parameters

lpRect

Pointer to a RECT structure that contains the coordinates of the top-left and bottom-right corners of the desired client area. When the function returns, the structure contains the coordinates of the top-left and bottom-right corners of the window to accommodate the desired client area.

dwStyle

Specifies the window styles of the window whose required size is to be calculated.

bMenu

Specifies whether the window has a menu.

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.

Remarks

A client rectangle is the smallest rectangle that completely encloses a client area. A window rectangle is the smallest rectangle that completely encloses a window.

The AdjustWindowRect function does not add extra space when a menu bar wraps to two or more rows.

See Also

AdjustWindowRectEx, CreateWindowEx, RECT


AdjustWindowRectEx

The AdjustWindowRectEx function calculates the required size of the rectangle of a window with extended style based on the desired client-rectangle size. The window rectangle can then be passed to the CreateWindowEx function to create a window whose client area is the desired size.

BOOL AdjustWindowRectEx(

LPRECT lpRect,	// pointer to client-rectangle structure
DWORD dwStyle,	// window styles
BOOL bMenu,	// menu-present flag
DWORD dwExStyle	// extended style
);
Parameters

lpRect

Pointer to a RECT structure that contains the coordinates of the top-left and bottom-right corners of the desired client area. When the function returns, the structure contains the coordinates of the top-left and bottom-right corners of the window to accommodate the desired client area.

dwStyle

Specifies the window styles of the window whose required size is to be calculated.

bMenu

Specifies whether the window has a menu.

dwExStyle

Specifies the extended style of the window whose required size is to be calculated.

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.

Remarks

A client rectangle is the smallest rectangle that completely encloses a client area. A window rectangle is the smallest rectangle that completely encloses a window.

The AdjustWindowRectEx function does not add extra space when a menu bar wraps to two or more rows.

See Also

AdjustWindowRect, CreateWindowEx, RECT


AdvancedDocumentProperties

The AdvancedDocumentProperties function displays a printer-configuration dialog box for the specified printer, allowing the user to configure that printer.

LONG AdvancedDocumentProperties(

HWND hWnd,	// handle to dialog box’s parent window
HANDLE hPrinter,	// handle to printer object
LPTSTR pDeviceName,	// pointer to driver name
PDEVMODE pDevModeOutput,	// pointer to modified device mode structure
PDEVMODE pDevModeInput	// pointer to original device mode structure
);
Parameters

hWnd

Identifies the parent window of the printer-configuration dialog box.

hPrinter

Identifies a printer object.

pDeviceName

Pointer to a null-terminated string specifying the name of the device for which a printer-configuration dialog box should be displayed.

pDevModeOutput

Pointer to a DEVMODE structure that will contain the configuration data specified by the user. An application can retrieve the number of bytes required for this structure by calling the AdvancedDocumentProperties function and setting pDevModeOutput to NULL.

pDevModeInput

Pointer to a DEVMODE structure that contains the configuration data used to initialize the controls of the printer-configuration dialog box.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

An application can obtain the printer handle identified by the hPrinter parameter by calling the OpenPrinter or AddPrinter function.

An application can obtain the name pointed to by the pDeviceName parameter by calling the GetPrinter function and then examining the pPrinterName member of the PRINTER_INFO_2 structure.

See Also

AddPrinter, DEVMODE, GetPrinter, OpenPrinter, PRINTER_INFO_2


AllocateAndInitializeSid

The AllocateAndInitializeSid function allocates and initializes a security identifier (SID) with up to eight subauthorities.

BOOL AllocateAndInitializeSid(

PSID_IDENTIFIER_AUTHORITY  pIdentifierAuthority,	// pointer to identifier authority
BYTE nSubAuthorityCount,	// count of subauthorities
DWORD dwSubAuthority0,	// subauthority 0
DWORD dwSubAuthority1,	// subauthority 1
DWORD dwSubAuthority2,	// subauthority 2
DWORD dwSubAuthority3,	// subauthority 3
DWORD dwSubAuthority4,	// subauthority 4
DWORD dwSubAuthority5,	// subauthority 5
DWORD dwSubAuthority6,	// subauthority 6
DWORD dwSubAuthority7,	// subauthority 7
PSID *pSid	// pointer to pointer to SID
);
Parameters

pIdentifierAuthority

Pointer to an SID_IDENTIFIER_AUTHORITY structure, giving the top-level identifier authority value to set in the SID.

nSubAuthorityCount

Specifies the number of subauthorities to place in the SID. This parameter also identifies how many of the subauthority parameters have meaningful values. This parameter must contain a value from 1 through 8.

For example, a value of 3 indicates that the subauthority values specified by the dwSubAuthority0, dwSubAuthority1, and dwSubAuthority2 parameters have meaningful values and to ignore the remainder.

dwSubAuthority0 through dwSubAuthority7

Specify subauthority values to place in the SID.

pSid

Pointer to a variable that receives the pointer to the allocated and initialized SID structure.

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.

Remarks

An SID allocated with the AllocateAndInitializeSid function must be freed by using the FreeSid function.

See Also

FreeSid, GetSidIdentifierAuthority, InitializeSid, SID_IDENTIFIER_AUTHORITY


AllocateLocallyUniqueId

The AllocateLocallyUniqueId function allocates a locally unique identifier (LUID).

BOOL AllocateLocallyUniqueId(

PLUID Luid	// address of locally unique identifier
);
Parameters

Luid

Points to a buffer that receives the allocated LUID.

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.

Remarks

An LUID is unique only within a single session. The same LUID value can be used on different computers or on the same computer after it has been restarted.

See Also

LookupPrivilegeValue


AllocConsole

The AllocConsole function allocates a new console for the calling process.

BOOL AllocConsole(VOID)

Parameters

This function has no parameters.

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.

Remarks

A process can be associated with only one console, so the AllocConsole function fails if the calling process already has a console. A process can use the FreeConsole function to detach itself from its current console, and then it can call AllocConsole to create a new console. If the calling process creates a child process, the child inherits the new console.

AllocConsole also sets up standard input, standard output, and standard error handles for the new console. The standard input handle is a handle to the console’s input buffer, and the standard output and standard error handles are handles to the console’s screen buffer. To retrieve these handles, use the GetStdHandle function.

This function is primarily used by graphics applications to create a console window. Graphics applications are initialized without a console. Console applications are normally initialized with a console, unless they are created as detached processes (by calling the CreateProcess function with the DETACHED_PROCESS flag).

See Also

CreateProcess, FreeConsole, GetStdHandle


AngleArc

The AngleArc function draws a line segment and an arc. The line segment is drawn from the current position to the beginning of the arc. The arc is drawn along the perimeter of a circle with the given radius and center. The length of the arc is defined by the given start and sweep angles.

BOOL AngleArc(

HDC hdc,	// handle to device context
int X,	// x-coordinate of circle’s center
int Y,	// y-coordinate of circle’s center
DWORD dwRadius,	// circle’s radius
FLOAT eStartAngle,	// arc’s start angle
FLOAT eSweepAngle	// arc’s sweep angle
);
Parameters

hdc

Identifies a device context.

X

Specifies the logical x-coordinate of the center of the circle.

Y

Specifies the logical y-coordinate of the center of the circle.

dwRadius

Specifies the radius, in logical units, of the circle. This value must be positive.

eStartAngle

Specifies the start angle, in degrees, relative to the x-axis.

eSweepAngle

Specifies the sweep angle, in degrees, relative to the starting angle.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The AngleArc function moves the current position to the ending point of the arc.

The arc drawn by this function may appear to be elliptical, depending on the current transformation and mapping mode. Before drawing the arc, AngleArc draws the line segment from the current position to the beginning of the arc.

The arc is drawn by constructing an imaginary circle around the specified center point with the specified radius. The starting point of the arc is determined by measuring counterclockwise from the x-axis of the circle by the number of degrees in the start angle. The ending point is similarly located by measuring counterclockwise from the starting point by the number of degrees in the sweep angle.

If the sweep angle is greater than 360 degrees, the arc is swept multiple times.

This function draws lines by using the current pen. The figure is not filled.

See Also

Arc, ArcTo, MoveToEx


AnimatePalette

The AnimatePalette function replaces entries in the specified logical palette.

BOOL AnimatePalette(

HPALETTE hpal,	// handle to logical color palette
UINT iStartIndex,	// first entry in logical palette
UINT cEntries,	// count of entries in logical palette
CONST PALETTEENTRY *ppe	// pointer to first replacement
);
Parameters

hpal

Identifies the logical palette.

iStartIndex

Specifies the first logical palette entry to be replaced.

cEntries

Specifies the number of entries to be replaced.

ppe

Pointer to the first member of an array of PALETTEENTRY structures used to replace the current entries.

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.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

The AnimatePalette function only changes entries with the PC_RESERVED flag set in the corresponding palPalEntry member of the LOGPALETTE structure.

If the given palette is associated with the active window, the colors in the palette are replaced immediately.

See Also

CreatePalette, GetDeviceCaps, LOGPALETTE, PALETTEENTRY


AnsiLower

The AnsiLower function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharLower function, which should be used for new Win32-based applications.


AnsiLowerBuff

The AnsiLowerBuff function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharLowerBuff function, which should be used for new Win32-based applications.


AnsiNext

The AnsiNext function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharNext function, which should be used for new Win32-based applications.


AnsiPrev

The AnsiPrev function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharPrev function, which should be used for new Win32-based applications.


AnsiToOem

The AnsiToOem function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharToOem function, which should be used for new Win32-based applications.


AnsiToOemBuff

The AnsiToOemBuff function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharToOemBuff function, which should be used for new Win32-based applications.


AnsiUpper

The AnsiUpper function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharUpper function, which should be used for new Win32-based applications.


AnsiUpperBuff

The AnsiUpperBuff function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharUpperBuff function, which should be used for new Win32-based applications.


AnyPopup

The AnyPopup function indicates whether an owned, visible, top-level pop-up, or overlapped window exists on the screen. The function searches the entire Windows screen, not just the calling application’s client area.

BOOL AnyPopup(VOID)

Parameters

This function has no parameters.

Return Values

If a pop-up window exists, the return value is nonzero, even if the pop-up window is completely covered by other windows.

If a pop-up window does not exist, the return value is zero.

Remarks

AnyPopup is a Windows version 1.x function and is retained for compatibility purposes. It is generally not useful.

This function does not detect unowned pop-up windows or windows that do not have the WS_VISIBLE style bit set.

See Also

GetLastActivePopup, ShowOwnedPopups


AppendMenu

The AppendMenu function appends a new item to the end of the specified menu bar, drop-down menu, submenu, or shortcut menu. You can use this function to specify the content, appearance, and behavior of the menu item.

The AppendMenu function has been superseded by the InsertMenuItem function. You can still use AppendMenu, however, if you do not need any of the extended features of InsertMenuItem.

BOOL AppendMenu(

HMENU hMenu,	// handle to menu to be changed
UINT uFlags,	// menu-item flags
UINT uIDNewItem,	// menu-item identifier or handle of drop-down menu or submenu
LPCTSTR lpNewItem	// menu-item content
);
Parameters

hMenu

Identifies the menu bar, drop-down menu, submenu, or shortcut menu to be changed.

uFlags

Specifies flags to control the appearance and behavior of the new menu item. This parameter can be a combination of the values listed in the following Remarks section.

uIDNewItem

Specifies either the identifier of the new menu item or, if the uFlags parameter is set to MF_POPUP, the handle to the drop-down menu or submenu.

lpNewItem

Specifies the content of the new menu item. The interpretation of lpNewItem depends on whether the uFlags parameter includes the MF_BITMAP, MF_OWNERDRAW, or MF_STRING flag, as follows:

Value	Description
MF_BITMAP	Contains a bitmap handle.
MF_OWNERDRAW	Contains a 32-bit value supplied by the application that can be used to maintain additional data related to the menu item. The value is in the itemData member of the structure pointed to by the lparam parameter of the WM_MEASURE or WM_DRAWITEM message sent when the menu is created or its appearance is updated.
MF_STRING	Contains a pointer to a null-terminated string.
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.

Remarks

The application must call the DrawMenuBar function whenever a menu changes, whether or not the menu is in a displayed window.

The following flags can be set in the uFlags parameter:

Value	Description
MF_BITMAP	Uses a bitmap as the menu item. The lpNewItem parameter contains the handle to the bitmap.
MF_CHECKED	Places a check mark next to the menu item. If the application provides check-mark bitmaps (see SetMenuItemBitmaps), this flag displays the check mark bitmap next to the menu item.
MF_DISABLED	Disables the menu item so it cannot be selected, but the flag does not gray it.
MF_ENABLED	Enables the menu item so it can be selected, and restores it from its grayed state.
MF_GRAYED	Disables the menu item and grays it so it cannot be selected.
MF_MENUBARBREAK	Functions the same as the MF_MENUBREAK flag for a menu bar. For a drop-down menu, submenu, or shortcut menu, the new column is separated from the old column by a vertical line.
MF_MENUBREAK	Places the item on a new line (for a menu bar) or in a new column (for a drop-down menu, submenu, or shortcut menu) without separating columns.
MF_OWNERDRAW	Specifies that the item is an owner-drawn item. Before the menu is displayed for the first time, the window that owns the menu receives a WM_MEASUREITEM message to retrieve the width and height of the menu item. The WM_DRAWITEM message is then sent to the window procedure of the owner window whenever the appearance of the menu item must be updated.
MF_POPUP	Specifies that the menu item opens a drop-down menu or submenu. The uIDNewItem parameter specifies the handle to the drop-down menu or submenu. This flag is used to add a menu name to a menu bar, or a menu item that opens a submenu to a drop-down menu, submenu, or shortcut menu.
MF_SEPARATOR	Draws a horizontal dividing line. This flag is used only in a drop-down menu, submenu, or shortcut menu. The line cannot be grayed, disabled, or highlighted. The lpNewItem and uIDNewItem parameters are ignored.
MF_STRING	Specifies that the menu item is a text string; the lpNewItem parameter points to the string.
MF_UNCHECKED	Does not place a check mark next to the item (default). If the application supplies check-mark bitmaps (see SetMenuItemBitmaps), this flag displays the unchecked bitmap next to the menu item.
The following groups of flags cannot be used together:

•	MF_DISABLED, MF_ENABLED, and MF_GRAYED

•	MF_BITMAP, MF_STRING, and MF_OWNERDRAW

•	MF_MENUBARBREAK and MF_MENUBREAK

•	MF_CHECKED and MF_UNCHECKED

See Also

CreateMenu, DeleteMenu, DestroyMenu, DrawMenuBar, InsertMenu, InsertMenuItem, ModifyMenu, RemoveMenu, SetMenuItemBitmaps


Arc

The Arc function draws an elliptical arc.

BOOL Arc(

HDC hdc,	// handle to device context
int nLeftRect,	// x-coordinate of bounding rectangle’s upper-left corner
int nTopRect,	// y-coordinate of bounding rectangle’s upper-left corner
int nRightRect,	// x-coordinate of bounding rectangle’s lower-right corner
int nBottomRect,	// y-coordinate of bounding rectangle’s lower-right corner
int nXStartArc,	// first radial ending point
int nYStartArc,	// first radial ending point
int nXEndArc,	// second radial ending point
int nYEndArc	// second radial ending point
);
Parameters

hdc

Identifies the device context where drawing takes place.

nLeftRect

Specifies the logical x-coordinate of the upper-left corner of the bounding rectangle.

Windows 95: The sum of nLeftRect plus nRightRect must be less than 32768.

nTopRect

Specifies the logical y-coordinate of the upper-left corner of the bounding rectangle.

Windows 95: The sum of nTopRect plus nBottomRect must be less than 32768.

nRightRect

Specifies the logical x-coordinate of the lower-right corner of the bounding rectangle.

Windows 95: The sum of nLeftRect plus nRightRect must be less than 32768.

nBottomRect

Specifies the logical y-coordinate of the lower-right corner of the bounding rectangle.

Windows 95: The sum of nTopRect plus nBottomRect must be less than 32768.

nXStartArc

Specifies the logical x-coordinate of the ending point of the radial line defining the starting point of the arc.

nYStartArc

Specifies the logical y-coordinate of the ending point of the radial line defining the starting point of the arc.

nXEndArc

Specifies the logical x-coordinate of the ending point of the radial line defining the ending point of the arc.

nYEndArc

Specifies the logical y-coordinate of the ending point of the radial line defining the ending point of the arc.

Return Values

If the arc is drawn, the return value is nonzero.

If the arc is not drawn, the return value is zero.

Remarks

The points (nLeftRect, nTopRect) and (nRightRect, nBottomRect) specify the bounding rectangle. An ellipse formed by the specified bounding rectangle defines the curve of the arc. The arc extends in the current drawing direction from the point where it intersects the radial from the center of the bounding rectangle to the (nXStartArc, nYStartArc) point. The arc ends where it intersects the radial from the center of the bounding rectangle to the (nXEndArc, nYEndArc) point. If the starting point and ending point are the same, a complete ellipse is drawn.

The arc is drawn using the current pen; it is not filled.

The current position is neither used nor updated by Arc.

Windows 95: The drawing direction is always counterclockwise.

Windows NT: Use the GetArcDirection and SetArcDirection functions to get and set the current drawing direction for a device context. The default drawing direction is counterclockwise.

Windows 95: The sum of the coordinates of the bounding rectangle cannot exceed 32,767. The sum of nLeftRect and nRightRect or nTopRect and nBottomRect parameters cannot exceed 32,767.

See Also

AngleArc, ArcTo, Chord, Ellipse, GetArcDirection, Pie, SetArcDirection


ArcTo

The ArcTo function draws an elliptical arc.

BOOL ArcTo(

HDC hdc,	// handle to device context
int nLeftRect,	// x-coordinate of bounding rectangle’s upper-left corner
int nTopRect,	// y-coordinate of bounding rectangle’s upper-left corner
int nRightRect,	// x-coordinate of bounding rectangle’s lower-right corner
int nBottomRect,	// y-coordinate of bounding rectangle’s lower-right corner
int nXRadial1,	// x-coordinate of the first radial ending point
int nYRadial1,	// y-coordinate of the first radial ending point
int nXRadial2,	// x-coordinate of the second radial ending point
int nYRadial2	// y-coordinate of the second radial ending point
);
Parameters

hdc

Identifies the device context where drawing takes place.

nLeftRect

Specifies the logical x-coordinate of the upper-left corner of the bounding rectangle.

nTopRect

Specifies the logical y-coordinate of the upper-left corner of the bounding rectangle.

nRightRect

Specifies the logical x-coordinate of the lower-right corner of the bounding rectangle.

nBottomRect

Specifies the logical y-coordinate of the lower-right corner of the bounding rectangle.

nXRadial1

Specifies the logical x-coordinate of the endpoint of the radial defining the starting point of the arc.

nYRadial1

Specifies the logical y-coordinate of the endpoint of the radial defining the starting point of the arc.

nXRadial2

Specifies the logical x-coordinate of the endpoint of the radial defining the ending point of the arc.

nYRadial2

Specifies the logical y-coordinate of the endpoint of the radial defining the ending point of the arc.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

ArcTo is similar to the Arc function, except that the current position is updated.

The points (nLeftRect, nTopRect) and (nRightRect, nBottomRect) specify the bounding rectangle. An ellipse formed by the specified bounding rectangle defines the curve of the arc. The arc extends counterclockwise from the point where it intersects the radial line from the center of the bounding rectangle to the (nXRadial1, nYRadial1) point. The arc ends where it intersects the radial line from the center of the bounding rectangle to the (nXRadial2, nYRadial2) point. If the starting point and ending point are the same, a complete ellipse is drawn.

A line is drawn from the current position to the starting point of the arc. If no error occurs, the current position is set to the ending point of the arc.

The arc is drawn using the current pen; it is not filled.

See Also

AngleArc, Arc, SetArcDirection


AreAllAccessesGranted

The AreAllAccessesGranted function checks whether a set of requested access rights has been granted. The access rights are represented as bit flags in a 32-bit access mask.

BOOL AreAllAccessesGranted(

DWORD GrantedAccess,	// access mask for granted access rights
DWORD DesiredAccess	// access mask for requested access rights
);
Parameters

GrantedAccess

An access mask that specifies the access rights that have been granted.

DesiredAccess

An access mask that specifies the access rights that have been requested. This mask must have been mapped from generic to specific and standard access rights, usually by calling the MapGenericMask function.

Return Values

If all requested access rights have been granted, the return value is nonzero.

If not all requested access rights have been granted, the return value is zero.

Remarks

The AreAllAccessesGranted function is commonly used by a server application to check the access rights of a client attempting to gain access to an object. When the bits set in the DesiredAccess parameter match the bits set in the GrantedAccess parameter, all requested rights have been granted.

See Also

AccessCheck, AreAnyAccessesGranted, MapGenericMask


AreAnyAccessesGranted

The AreAnyAccessesGranted function tests whether any of a set of requested access rights has been granted. The access rights are represented as bit flags in a 32-bit access mask.

BOOL AreAnyAccessesGranted(

DWORD GrantedAccess,	// access mask for granted access rights
DWORD DesiredAccess	// access mask for access rights requested
);
Parameters

GrantedAccess

Specifies the granted access mask.

DesiredAccess

Specifies the access mask to be requested. This mask must have been mapped from generic to specific and standard access rights, usually by calling the MapGenericMask function.

Return Values

If any of the requested access rights have been granted, the return value is nonzero.

If none of the requested access rights have been granted, the return value is zero.

Remarks

The AreAnyAccessesGranted function is often used by a server application to check the access rights of a client attempting to gain access to an object. When any of the bits set in the DesiredAccess parameter match the bits set in the GrantedAccess parameter, at least one of the requested access rights has been granted.

See Also

AccessCheck, AreAllAccessesGranted, MapGenericMask


AreFileApisANSI

The AreFileApisANSI function determines whether a set of Win32 file functions is using the ANSI or OEM character set code page. This function is useful for 8-bit console input and output operations.

BOOL AreFileApisANSI (VOID)

Parameters

This function has no parameters.

Return Values

If the set of Win32 file functions is using the ANSI code page, the return value is nonzero.

If the set of Win32 file functions is using the OEM code page, the return value is zero.

Remarks

The SetFileApisToOEM function causes a set of Win32 file functions to use the OEM code page. The SetFileApisToANSI function causes the same set of Win32 file functions to use the ANSI code page. Use the AreFileApisANSI function to determine which code page the set of file functions is currently using. For a discussion of their usage, please refer to the Remarks sections of SetFileApisToOEM and SetFileApisToANSI.

The following is the set of Win32 file functions whose code page is ascertained by the AreFileApisANSI function:

_lopen	GetDriveType	LoadLibrary
CopyFile	GetFileAttributes	LoadLibraryEx
CreateDirectory	GetFullPathName	MoveFile
CreateFile	GetModuleFileName	MoveFileEx
CreateProcess	GetModuleHandle	OpenFile
DeleteFile	GetSystemDirectory	RemoveDirectory
FindFirstFile	GetTempFileName	SearchPath
FindNextFile	GetTempPath	SetCurrentDirectory
GetCurrentDirectory	GetVolumeInformation	SetFileAttributes
GetDiskFreeSpace	GetWindowsDirectory
See Also

SetFileApisToANSI, SetFileApisToOEM


ArrangeIconicWindows

The ArrangeIconicWindows function arranges all the minimized (iconic) child windows of the specified parent window.

UINT ArrangeIconicWindows(

HWND hWnd	// handle to parent window
);
Parameters

hWnd

Identifies the parent window.

Return Values

If the function succeeds, the return value is the height of one row of icons.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

An application that maintains its own minimized child windows can use the ArrangeIconicWindows function to arrange icons in a parent window. This function can also arrange icons on the desktop. To retrieve the window handle to the desktop window, use the GetDesktopWindow function.

An application sends the WM_MDIICONARRANGE message to the multiple document interface (MDI) client window to prompt the client window to arrange its minimized MDI child windows.

See Also

CloseWindow, GetDesktopWindow


AttachThreadInput

The AttachThreadInput function attaches the input processing mechanism of one thread to that of another thread.

BOOL AttachThreadInput(

DWORD idAttach,	// thread to attach
DWORD idAttachTo,	// thread to attach to
BOOL fAttach	// attach or detach
);
Parameters

idAttach

Specifies the identifier of the thread to be attached to another thread. The thread to be attached cannot be a system thread.

idAttachTo

Specifies the identifier of the thread to be attached to. This thread cannot be a system thread.

A thread cannot attach to itself. Therefore, idAttachTo cannot equal idAttach.

fAttach

Specifies whether to attach or detach the threads. If this parameter is TRUE, the two threads are attached. If the parameter is FALSE, the threads are detached.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. There is no extended error information available.

Remarks

Windows created in different threads typically process input independently of each other. That is, they have their own input states (focus, active, capture windows, key state, queue status, and so on), and they are not synchronized with the input processing of other threads. By using the AttachThreadInput function, a thread can attach its input processing to another thread. This also allows threads to share their input states, so they can call the SetFocus function to set the keyboard focus to a window of a different thread. This also allows threads to get key-state information. These capabilities are not generally possible.

The AttachThreadInput function fails if either of the specified threads does not have a message queue. The system creates a thread's message queue when the thread makes its first call to one of the Win32 USER or GDI functions. The AttachThreadInput function also fails if a journal record hook is installed. Journal record hooks attach all input queues together.

Note that key state, which can be ascertained by calls to the GetKeyState or GetKeyboardState function, is reset after a call to AttachThreadInput.

Windows NT: You cannot attach a thread to a thread in another desktop.

See Also

GetCurrentThreadId, GetKeyState, GetKeyboardState, GetWindowThreadProcessId, SetFocus


BackupEventLog

The BackupEventLog function saves the specified event log to a backup file. The function does not clear the event log.

BOOL BackupEventLog(

HANDLE hEventLog,	// handle to event log
LPCTSTR lpBackupFileName	// name of backup file
);
Parameters

hEventLog

Identifies the open event log. This handle is returned by the OpenEventLog or OpenBackupEventLog function.

lpBackupFileName

Pointer to a null-terminated string that names the backup file. The backup filename may contain a server name to save the backup file on a remote server.

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.

Remarks

If the backup filename specifies a remote server, the event log handle must identify a log on the local computer. You cannot back up an event logfile from a remote server to a file on a remote server (even if the backup file and the original log are on the same server).

See Also

OpenBackupEventLog, OpenEventLog


BackupRead

The BackupRead function reads data associated with a specified file or directory into a buffer. You use this function to back up a file or directory.

BOOL BackupRead(

HANDLE hFile,	// handle to file or directory
LPBYTE lpBuffer,	// pointer to buffer to read to
DWORD nNumberOfBytesToRead,	// number of bytes to read
LPDWORD lpNumberOfBytesRead,	// pointer to variable to receive number of bytes read
BOOL bAbort,	// termination type
BOOL bProcessSecurity,	// process security flag
LPVOID *lpContext	// pointer to pointer to internal context information
);
Parameters

hFile

Handle to the file or directory being backed up. The function reads data associated with this file. You obtain this handle by calling the CreateFile function.

The BackupRead function fails if CreateFile was called with the flag FILE_FLAG_NO_BUFFERING. In this case, the GetLastError function returns the value ERROR_INVALID_PARAMETER.

lpBuffer

Pointer to a buffer that the function writes data to.

nNumberOfBytesToRead

Specifies the length of the buffer.  The buffer size must be greater than the size of a WIN32_STREAM_ID structure.

lpNumberOfBytesRead

Pointer to a variable that, when the function returns, contains the number of bytes read.

If the function return value is TRUE, and the variable pointed to by lpNumberOfBytesRead is zero, then all the data associated with the file handle has been read.

bAbort

Indicates whether BackupRead terminated abnormally. If this value is TRUE, the operation terminates abnormally and all buffers are deallocated.

bProcessSecurity

Indicates whether the function will restore the access-control list (ACL) data for the file or directory.

If bProcessSecurity is TRUE, the ACL data will be backed up.

lpContext

Pointer to a variable that receives and holds a pointer to an internal data structure used by BackupRead to maintain context information during a backup operation.

You must set the variable pointed to by lpContext to NULL before the first call to BackupRead for the specified file or directory. The function allocates memory for the data structure, and then sets the variable to point to that structure. You must not change lpContext  or the variable that it points to between calls to BackupRead.

To release the memory used by the data structure, call BackupRead with the bAbort parameter set to TRUE when the backup operation is complete.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero, indicating that an I/O error occurred. To get extended error information, call GetLastError.

Remarks

BackupRead processes all of the data pertaining to an opened object as a series of discrete byte streams. Each stream is preceded by a 32-bit aligned WIN32_STREAM_ID structure.

Streams must be processed in the same order in which they were written to the tape. This ordering enables applications to compare the data backed up against the data on the source device. The data returned by BackupRead is to be used only as input to the BackupWrite function. This data is returned as one large data stream divided into substreams. The substreams are separated by WIN32_STREAM_ID headers.

If an error occurs while BackupRead is reading, the calling process can skip the bad data by calling the BackupSeek function.

See Also

BackupWrite, BackupSeek, WIN32_STREAM_ID


BackupSeek

The BackupSeek function seeks forward in a data stream initially accessed by using the BackupRead or BackupWrite function.

BOOL BackupSeek(

HANDLE hFile,	// handle to open file
DWORD dwLowBytesToSeek,	// low-order 32 bits of number of bytes
DWORD dwHighBytesToSeek,	// high-order 32 bits of number of bytes
LPDWORD lpdwLowByteSeeked,	// pointer to number of bytes function seeks
LPDWORD lpdwHighByteSeeked,	// pointer to number of bytes function seeks
LPVOID *lpContext	//pointer to internal context information
);
Parameters

hFile

Identifies the file or directory being backed up. This handle is created by using the CreateFile function.

dwLowBytesToSeek

Specifies the low-order 32 bits of the number of bytes to seek.

dwHighBytesToSeek

Specifies the high-order 32 bits of the number of bytes to seek.

lpdwLowByteSeeked

Pointer to a doubleword that, when the function returns, contains the low-order 32 bits of the number of bytes the function actually seeks.

lpdwHighByteSeeked

Pointer to a doubleword that, when the function returns, contains the high-order 32 bits of the number of bytes the function actually seeks.

lpContext

Pointer to an internal data structure used by the function. This structure must be the same structure that was initialized by the BackupRead function. An application must not touch the contents of this structure.

Return Values

If the function could seek the requested amount, the function returns nonzero.

If the function could not seek the requested amount, the function returns zero.

Remarks

Applications use the BackUpSeek function to skip portions of a data stream that cause errors. This function does not seek across stream headers. If an application attempts to seek past the end of a substream, the function fails, the lpdwLowByteSeeked and lpdwHighByteSeeked parameters indicate the actual number of bytes the function seeks, and the file position is placed at the start of the next stream header.

See Also

BackupRead, BackupWrite, CreateFile


BackupWrite

The BackupWrite function writes a stream of data from a buffer to a specified file or directory. The data must be divided into substreams separated by WIN32_STREAM_ID structures. You use this function to restore a file or directory that has been backed up.

BOOL BackupWrite(

HANDLE hFile,	// handle to file or directory
LPBYTE lpBuffer,	// pointer to buffer containing data to write
DWORD nNumberOfBytesToWrite,	// number of bytes to write
LPDWORD lpNumberOfBytesWritten,	// pointer to variable to receive number of bytes written
BOOL bAbort,	// termination type
BOOL bProcessSecurity,	// process security
LPVOID *lpContext	// pointer to pointer to internal context information
);
Parameters

hFile

Handle to the file or directory being restored. The function writes data to this file. You obtain this handle by calling the CreateFile function.

The BackupWrite function fails if CreateFile was called with the flag FILE_FLAG_NO_BUFFERING. In this case, the GetLastError function returns the value ERROR_INVALID_PARAMETER.

lpBuffer

Pointer to a buffer that the function writes data from.

nNumberOfBytesToWrite

Specifies the length of the buffer.  The buffer size must be greater than the size of a WIN32_STREAM_ID structure.

lpNumberOfBytesWritten

Pointer to a variable that, when the function returns, contains the number of bytes written.

bAbort

Specifies whether BackupWrite terminated abnormally. If this value is TRUE, the operation terminated abnormally and all buffers were deallocated.

bProcessSecurity

Specifies whether the function will restore the access-control list (ACL) data for the file or directory.

If bProcessSecurity is TRUE, you need to have specified  WRITE_OWNER and WRITE_DAC access when opening the file or directory handle. If the handle does not have those access rights, the operating system denies access to the ACL data, and ACL data restoration will not occur.

lpContext

Pointer to a variable that receives and holds a pointer to an internal data structure used by BackupWrite to maintain context information during a restore operation.

You must set the variable pointed to by lpContext to NULL before the first call to BackupWrite for the specified file or directory. The function allocates memory for the data structure, and then sets the variable to point to that structure. You must not change lpContext or the variable that it points to between calls to BackupWrite.

To release the memory used by the data structure, call BackupWrite with the bAbort parameter set to TRUE when the restore operation is complete.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero, indicating that an I/O error occurred. To get extended error information, call GetLastError.

Remarks

The BACKUP_LINK stream type lets you restore files with hard links.

Data obtained by the BackupRead function should only be used as input to the BackupWrite function.

See Also

BackupRead, BackupSeek, CreateFile, WIN32_STREAM_ID


Beep

The Beep function generates simple tones on the speaker. The function is synchronous; it does not return control to its caller until the sound finishes.

BOOL Beep(

DWORD dwFreq,	// sound frequency, in hertz
DWORD dwDuration	// sound duration, in milliseconds
);
Parameters

dwFreq

Windows NT:

Specifies the frequency, in hertz, of the sound. This parameter must be in the range 37 through 32,767 (0x25 through 0x7FFF).

Windows 95:

The parameter is ignored.

dwDuration

Windows NT:

Specifies the duration, in milliseconds, of the sound.

Windows 95:

The parameter is ignored.

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.

Remarks

Windows 95:

The Beep function ignores the dwFreq and dwDuration parameters. On computers with a sound card, the function plays the default sound event. On computers without a sound card, the function plays the standard system beep.

See Also

MessageBeep


BeginDeferWindowPos

The BeginDeferWindowPos function allocates memory for a multiple-window − position structure and returns the handle to the structure.

HDWP BeginDeferWindowPos(

int nNumWindows	// number of windows
);
Parameters

nNumWindows

Specifies the initial number of windows for which to store position information. The DeferWindowPos function increases the size of the structure, if necessary.

Return Values

If the function succeeds, the return value identifies the multiple-window − position structure. If insufficient system resources are available to allocate the structure, the return value is NULL.

Remarks

The multiple-window − position structure is an internal structure; an application cannot access it directly.

DeferWindowPos fills the multiple-window − position structure with information about the target position for one or more windows about to be moved. The EndDeferWindowPos function accepts the handle to this structure and repositions the windows by using the information stored in the structure.

If any of the windows in the multiple-window − position structure have the SWP_HIDEWINDOW or SWP_SHOWWINDOW flag set, none of the windows are repositioned.

If Windows must increase the size of the multiple-window − position structure beyond the initial size specified by the nNumWindows parameter but cannot allocate enough memory to do so, Windows fails the entire window positioning sequence (BeginDeferWindowPos, DeferWindowPos, and EndDeferWindowPos). By specifying the maximum size needed, an application can detect and process failure early in the process.

See Also

DeferWindowPos, EndDeferWindowPos, SetWindowPos


BeginPaint

The BeginPaint function prepares the specified window for painting and fills a PAINTSTRUCT structure with information about the painting.

HDC BeginPaint(

HWND hwnd,	// handle to window
LPPAINTSTRUCT lpPaint	// pointer to structure for paint information
);
Parameters

hwnd

Identifies the window to be repainted.

lpPaint

Pointer to the PAINTSTRUCT structure that will receive painting information.

Return Values

If the function succeeds, the return value is the handle to a display device context for the specified window.

If the function fails, the return value is NULL, indicating that no display device context is available.

Remarks

The BeginPaint function automatically sets the clipping region of the device context to exclude any area outside the update region. The update region is set by the InvalidateRect or InvalidateRgn function and by the system after sizing, moving, creating, scrolling, or any other operation that affects the client area. If the update region is marked for erasing, BeginPaint sends a WM_ERASEBKGND message to the window.

An application should not call BeginPaint except in response to a WM_PAINT message. Each call to BeginPaint must have a corresponding call to the EndPaint function.

If the caret is in the area to be painted, BeginPaint automatically hides the caret to prevent it from being erased.

If the window’s class has a background brush, BeginPaint uses that brush to erase the background of the update region before returning.

See Also

EndPaint, InvalidateRect, InvalidateRgn, PAINTSTRUCT, ValidateRect, ValidateRgn


BeginPath

The BeginPath function opens a path bracket in the specified device context.

BOOL BeginPath(

HDC hdc	// handle to device context
);
Parameters

hdc

Identifies the device context.

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.

Remarks

After a path bracket is open, an application can begin calling GDI drawing functions to define the points that lie in the path. An application can close an open path bracket by calling the EndPath function.

When an application calls BeginPath for a device context, any previous paths are discarded from that device context.

Windows NT:

The following drawing functions define points in a path:

AngleArc	LineTo	Polyline
Arc	MoveToEx	PolylineTo
ArcTo	Pie	PolyPolygon
Chord	PolyBezier	PolyPolyline
CloseFigure	PolyBezierTo	Rectangle
Ellipse	PolyDraw	RoundRect
ExtTextOut	Polygon	TextOut
Windows 95:

When constructing a path, only the CloseFigure, ExtTextOut, LineTo, MoveToEx, PolyBezier, PolyBezierTo, Polygon, Polyline, PolylineTo, PolyPolygon, PolyPolyline, and TextOut functions are recorded.

See Also

EndPath, FillPath, PathToRegion, SelectClipPath, StrokeAndFillPath, StrokePath, WidenPath


BeginUpdateResource

The BeginUpdateResource function returns a handle that can be used by the UpdateResource function to add, delete, or replace resources in an executable file.

HANDLE BeginUpdateResource(

LPCTSTR pFileName,	// pointer to file in which to update resources
BOOL bDeleteExistingResources	// deletion option
);
Parameters

pFileName

Pointer to a null-terminated string that specifies a Windows executable file in which to update resources. An application must be able to obtain write access to this file; it cannot be currently executing. If pFileName does not specify a full path, Windows searches for the file in the current directory.

bDeleteExistingResources

Specifies whether to delete the pFileName parameter’s existing resources. If this parameter is TRUE, existing resources are deleted and the updated executable file includes only resources added with the UpdateResource function. If this parameter is FALSE, the updated executable file includes existing resources unless they are explicitly deleted or replaced by using UpdateResource.

Return Values

If the function succeeds, the return value is a handle that can be used by the UpdateResource and EndUpdateResource functions. The return value is NULL if the specified file is not an executable file, the executable file is already loaded, the file does not exist, or the file cannot be opened for writing. To get extended error information, call GetLastError.

See Also

EndUpdateResource, UpdateResource


BitBlt

The BitBlt function performs a bit-block transfer of the color data corresponding to a rectangle of pixels from the specified source device context into a destination device context.

BOOL BitBlt(

HDC hdcDest,	// handle to destination device context
int nXDest,	// x-coordinate of destination rectangle’s upper-left corner
int nYDest,	// y-coordinate of destination rectangle’s upper-left corner
int nWidth,	// width of destination rectangle
int nHeight,	// height of destination rectangle
HDC hdcSrc,	// handle to source device context
int nXSrc,	// x-coordinate of source rectangle’s upper-left corner
int nYSrc,	// y-coordinate of source rectangle’s upper-left corner
DWORD dwRop	// raster operation code
);
Parameters

hdcDest

Identifies the destination device context.

nXDest

Specifies the logical x-coordinate of the upper-left corner of the destination rectangle.

nYDest

Specifies the logical y-coordinate of the upper-left corner of the destination rectangle.

nWidth

Specifies the logical width of the source and destination rectangles.

nHeight

Specifies the logical height of the source and the destination rectangles.

hdcSrc

Identifies the source device context.

nXSrc

Specifies the logical x-coordinate of the upper-left corner of the source rectangle.

nYSrc

Specifies the logical y-coordinate of the upper-left corner of the source rectangle.

dwRop

Specifies a raster-operation code. These codes define how the color data for the source rectangle is to be combined with the color data for the destination rectangle to achieve the final color.

The following list shows some common raster operation codes:

Value	Description
BLACKNESS	Fills the destination rectangle using the color associated with index 0 in the physical palette. (This color is black for the default physical palette.)
DSTINVERT	Inverts the destination rectangle.
MERGECOPY	Merges the colors of the source rectangle with the specified pattern by using the Boolean AND operator.
MERGEPAINT	Merges the colors of the inverted source rectangle with the colors of the destination rectangle by using the Boolean OR operator.
NOTSRCCOPY	Copies the inverted source rectangle to the destination.
NOTSRCERASE	Combines the colors of the source and destination rectangles by using the Boolean OR operator and then inverts the resultant color.
PATCOPY	Copies the specified pattern into the destination bitmap.
PATINVERT	Combines the colors of the specified pattern with the colors of the destination rectangle by using the Boolean XOR operator.
PATPAINT	Combines the colors of the pattern with the colors of the inverted source rectangle by using the Boolean OR operator. The result of this operation is combined with the colors of the destination rectangle by using the Boolean OR operator.
SRCAND	Combines the colors of the source and destination rectangles by using the Boolean AND operator.
SRCCOPY	Copies the source rectangle directly to the destination rectangle.
SRCERASE	Combines the inverted colors of the destination rectangle with the colors of the source rectangle by using the Boolean AND operator.
SRCINVERT	Combines the colors of the source and destination rectangles by using the Boolean XOR operator.
SRCPAINT	Combines the colors of the source and destination rectangles by using the Boolean OR operator.
WHITENESS	Fills the destination rectangle using the color associated with index 1 in the physical palette. (This color is white for the default physical palette.)
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.

Remarks

If a rotation or shear transformation is in effect in the source device context, BitBlt returns an error. If other transformations exist in the source device context (and a matching transformation is not in effect in the destination device context), the rectangle in the destination device context is stretched, compressed, or rotated as necessary.

If the color formats of the source and destination device contexts do not match, the BitBlt function converts the source color format to match the destination format.

When an enhanced metafile is being recorded, an error occurs if the source device context identifies an enhanced-metafile device context.

Not all devices support the BitBlt function. For more information, see the RC_BITBLT raster capability entry in GetDeviceCaps.

BitBlt returns an error if the source and destination device contexts represent different devices.

See Also

GetDeviceCaps, MaskBlt, PlgBlt, StretchBlt


BringWindowToTop

The BringWindowToTop function brings the specified window to the top of the Z order. If the window is a top-level window, it is activated. If the window is a child window, the top-level parent window associated with the child window is activated.

BOOL BringWindowToTop(

HWND hWnd	// handle to window
);
Parameters

hWnd

Identifies the window to bring to the top of the Z order.

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.

Remarks

Use the BringWindowToTop function to uncover any window that is partially or completely obscured by other windows.

Calling this function is similar to calling the SetWindowPos function to change a window’s position in the Z order. BringWindowToTop does not make a window a top-level window.

If an application is not in the foreground and wants to be in the foreground, it should call the SetForegroundWindow function.

See Also

SetWindowPos, SetActiveWindow, SetForegroundWindow


BroadcastSystemMessage [Now Supported on Windows NT]
BroadcastSystemMessage

[Now Supported on Windows NT]

The BroadcastSystemMessage function sends a message to the specified recipients. The recipients can be applications, installable drivers, Windows-based network drivers, system-level device drivers, or any combination of these system components.

long BroadcastSystemMessage(

DWORD dwFlags,
LPDWORD lpdwRecipients,
UINT uiMessage,
WPARAM wParam,
LPARAM lParam
);
Parameters

dwFlags

Option flags. Can be a combination of the following values:

Value	Meaning
BSF_FLUSHDISK	Flush the disk after each recipient processes the message.
BSF_FORCEIFHUNG	Continue to broadcast the message, even if the time-out period elapses or one of the recipients is hung..
BSF_IGNORECURRENTTASK	Do not send the message to windows that belong to the current task. This prevents an application from receiving its own message.
BSF_NOHANG	Force a hung application to time out. If one of the recipients times out, do not continue broadcasting the message.
BSF_NOTIMEOUTIFNOTHUNG	Wait for a response to the message, as long as the recipient is not hung. Do not time out.
BSF_POSTMESSAGE	Post the message. Do not use in combination with BSF_QUERY.
BSF_QUERY	Send the message to one recipient at a time, sending to a subsequent recipient only if the current recipient returns TRUE.
lpdwRecipients

Pointer to a variable that contains and receives information about the recipients of the message. The variable can be a combination of the following values:

Value	Meaning
BSM_ALLCOMPONENTS	Broadcast to all system components.
BSM_ALLDESKTOPS	Windows NT only: Broadcast to all desktops. Requires the SE_TCB_NAME privilege.
BSM_APPLICATIONS	Broadcast to applications.
BSM_INSTALLABLEDRIVERS	Windows 95: Broadcast to installable drivers. Windows NT: This value is not meaningful.
BSM_NETDRIVER	Windows 95: Broadcast to Windows-based network drivers. Windows NT: This value is not meaningful.
BSM_VXDS	Windows 95: Broadcast to all system-level device drivers. Windows NT: This value is not meaningful.
When the function returns, this variable receives a combination of these values identifying which recipients actually received the message.

If this parameter is NULL, the function broadcasts to all components.

uiMessage

Identifier of the system message.

wParam

32-bit message-specific value.

lParam

32-bit message-specific value.

Return Values

If the function succeeds, the return value is a positive value.

If the function is unable to broadcast the message, the return value is −1.

If the dwFlags parameter is BSF_QUERY and at least one recipient returned BROADCAST_QUERY_DENY to the corresponding message, the return value is zero.

Remarks

If BSF_QUERY is not specified, the function sends the specified message to all requested recipients, ignoring values returned by those recipients.


BrowseCallbackProc [Now Supported on Windows NT]
BrowseCallbackProc

[Now Supported on Windows NT]

Specifies an application-defined callback function used with the SHBrowseForFolder function. The browse dialog box calls this function to notify it about events. The BFFCALLBACK type defines a pointer to this callback function.

int BrowseCallbackProc(

HWND hwnd,
UINT uMsg,
LPARAM lParam,
LPARAM lpData
);
Parameters

hwnd

Handle to the browse dialog box. The callback function can send the following messages to this window:

BFFM_ENABLEOK	Enables the OK button if the wParam parameter is nonzero or disables it if wParam is zero.
BFFM_SETSELECTION	Selects the specified folder. The lParam parameter is the PIDL of the folder to select if wParam is FALSE, or it is the path of the folder otherwise.
BFFM_SETSTATUSTEXT	Sets the status text to the null-terminated string specified by the lParam parameter.
uMsg

Value identifying the event. This parameter can be one of the following values:

BFFM_INITIALIZED	The browse dialog box has finished initializing. lpData is NULL.
BFFM_SELCHANGED	The selection has changed. lpData is a pointer to the item identifier list for the newly selected folder.
lParam

Message-specific value. For more information, see the description of uMsg.

lpData

Application-defined value that was specified in the lParam member of the BROWSEINFO structure.

Return Values

Returns zero.

See Also

BROWSEINFO


BuildCommDCB

The BuildCommDCB function fills a specified DCB structure with values specified in a device-control string. The device-control string uses the syntax of the mode command.

BOOL BuildCommDCB(

LPCTSTR lpDef,	// pointer to device-control string
LPDCB lpDCB	// pointer to device-control block
);
Parameters

lpDef

Pointer to a null-terminated string that specifies device-control information. The string must have the same form as the mode command’s command-line arguments. For example, the following string specifies a baud rate of 1200, no parity, 8 data bits, and 1 stop bit:

baud=1200 parity=N data=8 stop=1

The device name is ignored if it is included in the string, but it must specify a valid device, as follows:

COM1: baud=1200 parity=N data=8 stop=1

For further information on mode command syntax, refer to the end-user documentation for your operating system.

lpDCB

Pointer to a DCB structure to be filled in.

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.

Remarks

The BuildCommDCB function adjusts only those members of the DCB structure that are specifically affected by the lpDef parameter, with the following exceptions:

•	If the specified baud rate is 110, the function sets the stop bits to 2 to remain compatible with the Windows NT or MS-DOS mode command.

•	By default, BuildCommDCB disables XON/XOFF and hardware flow control. To enable flow control, you must explicitly set the appropriate members of the DCB structure.

The BuildCommDCB function only fills in the members of the DCB structure. To apply these settings to a serial port, use the SetCommState function.

There are older and newer forms of the mode command syntax. The BuildCommDCB function supports both forms. However, you cannot mix the two forms together.

The newer form of the mode command syntax lets you explicitly set the values of the flow control members of the DCB structure. If you use an older form of the mode syntax, the BuildCommDCB function sets the flow control members of the DCB structure, as follows:

•	For a string such as 96,n,8,1 or any other older-form mode string that doesn't end with an x or a p:

fInX, fOutX,fOutXDsrFlow,and fOutXCtsFlow are all set to FALSE

fDtrControl is set to DTR_CONTROL_ENABLE

fRtsControl is set to RTS_CONTROL_ENABLE

•	For a string such as 96,n,8,1,x or any other older-form mode string that finishes with an x:

fInX, fOutX are both set to TRUE

fOutXDsrFlow,fOutXCtsFlow are both set to FALSE.

fDtrControl is set to DTR_CONTROL_ENABLE

fRtsControl is set to RTS_CONTROL_ENABLE

•	For a string such as 96,n,8,1,p or any other older-form mode string that finishes with a p:

fInX, fOutX are both set to FALSE

fOutXDsrFlow,fOutXCtsFlow are both set to TRUE.

fDtrControl is set to DTR_CONTROL_HANDSHAKE

fRtsControl is set to RTS_CONTROL_HANDSHAKE

See Also

DCB, SetCommState


BuildCommDCBAndTimeouts

The BuildCommDCBAndTimeouts function translates a device-definition string into appropriate device-control block codes and then places these codes into a device control block. The function can also set up time-out values, including the possibility of no time-outs, for a device; the function’s behavior in this regard varies based on the contents of the device-definition string.

BOOL BuildCommDCBAndTimeouts(

LPCTSTR lpDef,	// pointer to the device-control string
LPDCB lpDCB,	// pointer to the device-control block
LPCOMMTIMEOUTS  lpCommTimeouts	// pointer to comm. time-out structure
);
Parameters

lpDef

Pointer to a null-terminated string that specifies device-control information for the device. The function takes this string, parses it, and then sets appropriate values in the DCB structure pointed to by lpDCB.

lpDCB

Pointer to a DCB structure that the function fills with information from the device-control information string pointed to by lpDef. This DCB structure defines the control settings for a communications device.

lpCommTimeouts

Pointer to a COMMTIMEOUTS structure that the function can use to set device time-out values.

The BuildCommDcbAndTimeouts function modifies its time-out setting behavior based on the presence or absence of a “TO=xxx” substring in the string specified by lpDef:

•	If that string contains the substring “TO=ON”, the function sets up total read and write time-out values for the device based on the time-out structure pointed to by lpCommTimeouts.

•	If that string contains the substring “TO=OFF”, the function sets up the device with no time-outs.

•	If that string contains neither of the aforementioned “TO=xxx” substrings, the function ignores the time-out structure pointed to by lpCommTimeouts. The time-out structure will not be accessed.

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.

See Also

BuildCommDCB, COMMTIMEOUTS, DCB, GetCommTimeouts, SetCommTimeouts


BuildExplicitAccessWithName [New - Windows NT]
BuildExplicitAccessWithName

[New - Windows NT]

The BuildExplicitAccessWithName function initializes an EXPLICIT_ACCESS structure with data specified by the caller. The trustee is identified by a name string.

VOID BuildExplicitAccessWithName(

PEXPLICIT_ACCESS pExplicitAccess,	// pointer to the structure to initialize
LPTSTR pTrusteeName,	// name of the trustee to put in the structure
DWORD AccessPermissions,	// access mask to put in the structure
ACCESS_MODE AccessMode,	// access mode to put in the structure
DWORD Inheritance	// inheritance type to put in the structure
);
Parameters

pExplicitAccess

Pointer to an EXPLICIT_ACCESS structure to initialize. BuildExplicitAccessWithName does not allocate any memory. If this parameter is NULL, the function does nothing.

pTrusteeName

Pointer to a null-terminated string that contains the name of the trustee for the ptstrName member of the TRUSTEE structure. The BuildExplicitAccessWithName function sets the other members of the TRUSTEE structure as follows:

Member	Value
pMultipleTrustee	NULL
MultipleTrusteeOperation	NO_MULTIPLE_TRUSTEE
TrusteeForm	TRUSTEE_IS_NAME
TrusteeType	TRUSTEE_IS_UNKNOWN
AccessPermissions

Specifies an access mask for the grfAccessPermissions member of the EXPLICIT_ACCESS structure. The mask is a set of bit flags that use the ACCESS_MASK format to specify the access rights that an ACE allows, denies, or audits for the trustee. The functions that use the EXPLICIT_ACCESS structure do not convert, interpret, or validate the bits in this mask.

AccessMode

Specifies an access mode for the grfAccessMode member of the EXPLICIT_ACCESS structure. The access mode indicates whether the ACE allows, denies, or audits the specified rights. This parameter contains values from the ACCESS_MODE enumeration.

Inheritance

Specifies an inheritance type for the grfInheritance member of the EXPLICIT_ACCESS structure. This value is a set of bit flags that determines whether other containers or objects can inherit the ACE from the primary object to which the ACL is attached. The value of this member corresponds to the inheritance portion (low-order byte) of the AceFlags member of the ACE_HEADER structure. This parameter can be NO_INHERITANCE to indicate that the ACE is not inheritable,or it can be a combination of the following values.

Value	Meaning
CONTAINER_INHERIT_ACE
	Other containers that are contained by the primary object inherit the ACE.
INHERIT_ONLY_ACE
	The ACE does not apply to the primary object to which the ACL is attached, but objects contained by the primary object inherit the ACE.
NO_PROPAGATE_INHERIT_ACE
	The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE flags are not propagated to an inherited ACE.
OBJECT_INHERIT_ACE
	Noncontainer objects contained by the primary object inherit the ACE.
SUB_CONTAINERS_ONLY_INHERIT
	Other containers that are contained by the primary object inherit the ACE. This flag corresponds to the CONTAINER_INHERIT_ACE flag.
SUB_OBJECTS_ONLY_INHERIT
	Noncontainer objects contained by the primary object inherit the ACE. This flag corresponds to the OBJECT_INHERIT_ACE flag.
SUB_CONTAINERS_AND_OBJECTS_INHERIT
	Both containers and noncontainer objects that are contained by the primary object inherit the ACE. This flag corresponds to the combination of the CONTAINER_INHERIT_ACE and OBJECT_INHERIT_ACE flags.
Return Values

None.

See Also

ACE, ACL, EXPLICIT_ACCESS, GetExplicitEntriesFromAcl, SetEntriesInAcl, TRUSTEE


BuildImpersonateExplicitAccessWithName [New - Windows NT]
BuildImpersonateExplicitAccessWithName

[New - Windows NT]

The BuildImpersonateExplicitAccessWithName function is provided for future use. Do not call it on Windows NT version 4.0.


BuildImpersonateTrustee [New - Windows NT]
BuildImpersonateTrustee

[New - Windows NT]

The BuildImpersonateTrustee function is provided for future use. Do not call it on Windows NT version 4.0.


BuildSecurityDescriptor [New - Windows NT]
BuildSecurityDescriptor

[New - Windows NT]

The BuildSecurityDescriptor function allocates and initializes a new security descriptor. A security descriptor is an opaque structure that contains the security information associated with an object. The function can initialize the new security descriptor by merging specified security information with the information in an existing security descriptor. If you don’t specify an existing security descriptor, the function initializes a new security descriptor based on the specified security information.

BuildSecurityDescriptor creates a self-relative security descriptor, which means that the security descriptor stores a SECURITY_DESCRIPTOR structure and associated security information in a contiguous block of memory. The self-relative format makes the security descriptor suitable for storing in a stream.

DWORD BuildSecurityDescriptor(

PTRUSTEE pOwner,	// identifies owner for new security descriptor
PTRUSTEE pGroup,	// identifies group for new security descriptor
ULONG cCountOfAccessEntries,	// number of access-control entries in the list
PEXPLICIT_ACCESS pListOfAccessEntries,	// pointer to list of access-control entries for DACL
ULONG cCountOfAuditEntries,	// number of audit-control entries in the list
PEXPLICIT_ACCESS pListOfAuditEntries,	// pointer to list of audit-control entries for SACL
PSECURITY_DESCRIPTOR pOldSD,	// pointer to an existing security descriptor
PULONG pSizeNewSD,	// pointer to the size of the new security descriptor
PSECURITY_DESCRIPTOR * pNewSD	// pointer that receives the new security descriptor
);
Parameters

pOwner

Pointer to a TRUSTEE structure that identifies the owner for the new security descriptor. If the structure uses the TRUSTEE_IS_NAME form, BuildSecurityDescriptor looks up the SID associated with the specified trustee name.

If this parameter is NULL, the function uses the owner SID from the original security descriptor pointed to by pOldSD. If pOldSD is NULL, or if the owner SID in pOldSD is NULL, the owner SID is NULL in the new security descriptor.

pGroup

Pointer to a TRUSTEE structure that identifies the primary group SID for the new security descriptor. If the structure uses the TRUSTEE_IS_NAME form, BuildSecurityDescriptor looks up the SID associated with the specified trustee name.

If this parameter is NULL, the function uses the group SID from the original security descriptor pointed to by pOldSD. If pOldSD is NULL, or if the group SID in pOldSD is NULL, the group SID is NULL in the new security descriptor.

cCountOfAccessEntries

Specifies the number of EXPLICIT_ACCESS structures in the pListOfAccessEntries array.

pListOfAccessEntries

Pointer to an array of EXPLICIT_ACCESS structures that describe access control information for the DACL of the new security descriptor. The function creates the new DACL by merging the information in the array with the DACL in pOldSD, if any. If pOldSD is NULL, or if the DACL in pOldSD is NULL, the function creates a new DACL based solely on the information in the array. For a description of the rules for creating an ACL from an array of EXPLICIT_ACCESS structures, see the SetEntriesInAcl function.

If pListOfAccessEntries is NULL, the new security descriptor gets the DACL from pOldSD. In this case, if pOldSD is NULL, or if the DACL in pOldSD is NULL, the new DACL is NULL.

cCountOfAuditEntries

Specifies the number of EXPLICIT_ACCESS structures in the pListOfAuditEntries array.

pListOfAuditEntries

Pointer to an array of EXPLICIT_ACCESS structures that describe audit control information for the SACL of the new security descriptor. The function creates the new SACL by merging the information in the array with the SACL in pOldSD, if any. If pOldSD is NULL, or the SACL in pOldSD is NULL, the function creates a new SACL based solely on the information in the array.

If pListOfAuditEntries is NULL, the new security descriptor gets the SACL from pOldSD. In this case, if pOldSD is NULL, or the SACL in pOldSD is NULL, the new SACL is NULL.

pOldSD

Pointer to an existing self-relative SECURITY_DESCRIPTOR structure and its associated security information. The function builds the new security descriptor by merging the specified owner, group, access-control, and audit-control information with the information in this security descriptor. This parameter can be NULL.

pSizeNewSD

Pointer to a ULONG variable that receives the size, in bytes, of the returned security descriptor.

pNewSD

Pointer to a variable that receives a pointer to the new security descriptor. The function allocates memory for the new security descriptor. You must call the LocalFree function to free the returned buffer.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

The BuildSecurityDescriptor function is intended for trusted servers that implement or expose security on their own objects. The function uses self-relative security descriptors suitable for serializing into a stream and storing to disk, as a trusted server might require.

See Also

ACL, EXPLICIT_ACCESS, LocalFree, SECURITY_DESCRIPTOR, SetEntriesInAcl, SID, TRUSTEE


BuildTrusteeWithName [New - Windows NT]
BuildTrusteeWithName

[New - Windows NT]

The BuildTrusteeWithName function initializes a TRUSTEE structure. The caller specifies the trustee name. The function sets other members of the structure to default values.

VOID BuildTrusteeWithName(

PTRUSTEE pTrustee,	// pointer to the structure to initialize
LPTSTR pName	// name of the trustee to put in the structure
);
Parameters

pTrustee

Pointer to a TRUSTEE structure to initialize. The BuildTrusteeWithName function does not allocate any memory. If this parameter is NULL, the function does nothing.

pName

Pointer to a null-terminated string that contains the name of the trustee for the ptstrName member of the TRUSTEE structure. The BuildTrusteeWithName function sets the other members of the TRUSTEE structure as follows:

Member	Value
pMultipleTrustee	NULL
MultipleTrusteeOperation	NO_MULTIPLE_TRUSTEE
TrusteeForm	TRUSTEE_IS_NAME
TrusteeType	TRUSTEE_IS_UNKNOWN
Return Values

None.

See Also

BuildTrusteeWithSid, TRUSTEE


BuildTrusteeWithSid [New - Windows NT]
BuildTrusteeWithSid

[New - Windows NT]

The BuildTrusteeWithSid function initializes a TRUSTEE structure. The caller specifies the security identifier (SID) of the trustee. The function sets other members of the structure to default values. The function does not look up the name associated with the SID.

VOID BuildTrusteeWithName(

PTRUSTEE pTrustee,	// pointer to the structure to initialize
PSID pSid	// name of the trustee to put in the structure
);
Parameters

pTrustee

Pointer to a TRUSTEE structure to initialize. The BuildTrusteeWithSid function does not allocate any memory. If this parameter is NULL, the function does nothing.

pSid

Pointer to a SID that identifies the trustee. The BuildTrusteeWithSid function assigns this pointer to the ptstrName member of the TRUSTEE structure. The function sets the other members of the TRUSTEE structure as follows:

Member	Value
pMultipleTrustee	NULL
MultipleTrusteeOperation	NO_MULTIPLE_TRUSTEE
TrusteeForm	TRUSTEE_IS_SID
TrusteeType	TRUSTEE_IS_UNKNOWN
Return Values

None.

See Also

BuildTrusteeWithName, TRUSTEE


CallMsgFilter

The CallMsgFilter function passes the specified message and hook code to the hook procedures associated with the WH_SYSMSGFILTER and WH_MSGFILTER hooks. A WH_SYSMSGFILTER or WH_MSGFILTER hook procedure is an application-defined callback function that examines and, optionally, modifies messages for a dialog box, message box, menu, or scroll bar.

BOOL CallMsgFilter(

LPMSG lpMsg,	// pointer to structure with message data
int nCode	// hook code
);
Parameters

lpMsg

Pointer to an MSG structure that contains the message to be passed to the hook procedures.

nCode

Specifies an application-defined code used by the hook procedure to determine how to process the message. The code must not have the same value as system-defined hook codes (MSGF_ and HC_) associated with the WH_SYSMSGFILTER and WH_MSGFILTER hooks.

Return Values

If the application should process the message further, the return value is zero.

If the application should not process the message further, the return value is nonzero.

Remarks

Windows calls CallMsgFilter to enable applications to examine and control the flow of messages during internal processing of dialog boxes, message boxes, menus, and scroll bars, or when the user activates a different window by pressing the ALT+TAB key combination.

An application installs a hook procedure by using the SetWindowsHookEx function.

See Also

MessageProc, MSG, SetWindowsHookEx, SysMsgProc


CallNamedPipe

The CallNamedPipe function connects to a message-type pipe (and waits if an instance of the pipe is not available), writes to and reads from the pipe, and then closes the pipe.

BOOL CallNamedPipe(

LPCTSTR lpNamedPipeName,	// pointer to pipe name
LPVOID lpInBuffer,	// pointer to write buffer
DWORD nInBufferSize,	// size, in bytes, of write buffer
LPVOID lpOutBuffer,	// pointer to read buffer
DWORD nOutBufferSize,	// size, in bytes, of read buffer
LPDWORD lpBytesRead,	// pointer to number of bytes read
DWORD nTimeOut	// time-out time, in milliseconds
);
Parameters

lpNamedPipeName

Pointer to a null-terminated string specifying the pipe name.

lpInBuffer

Pointer to the buffer containing the data written to the pipe.

nInBufferSize

Specifies the size, in bytes, of the write buffer.

lpOutBuffer

Pointer to the buffer that receives the data read from the pipe.

nOutBufferSize

Specifies the size, in bytes, of the read buffer.

lpBytesRead

Pointer to a 32-bit variable that receives the number of bytes read from the pipe.

nTimeOut

Specifies the number of milliseconds to wait for the named pipe to be available. In addition to numeric values, the following special values can be specified:

Value	Meaning
NMPWAIT_NOWAIT	Does not wait for the named pipe. If the named pipe is not available, the function returns an error.
NMPWAIT_WAIT_FOREVER	Waits indefinitely.
NMPWAIT_USE_DEFAULT_WAIT	Uses the default time-out specified in a call to the CreateNamedPipe 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.

Remarks

Calling CallNamedPipe is equivalent to calling the CreateFile (or WaitNamedPipe, if CreateFile cannot open the pipe immediately), TransactNamedPipe, and CloseHandle functions. CreateFile is called with an access flag of GENERIC_READ | GENERIC_WRITE, an inherit handle flag of FALSE, and a share mode of zero (indicating no sharing of this pipe instance).

If the message written to the pipe by the server process is longer than nOutBufferSize, CallNamedPipe returns FALSE, and GetLastError returns ERROR_MORE_DATA. The remainder of the message is discarded, because CallNamedPipe closes the handle to the pipe before returning.

CallNamedPipe fails if the pipe is a byte-type pipe.

See Also

CloseHandle, CreateFile, CreateNamedPipe, TransactNamedPipe, WaitNamedPipe


CallNextHookEx

The CallNextHookEx function passes the hook information to the next hook procedure in the current hook chain. This function supersedes the DefHookProc function.

LRESULT CallNextHookEx(

HHOOK hhk,	// handle to current hook
int nCode,	// hook code passed to hook procedure
WPARAM wParam,	// value passed to hook procedure
LPARAM lParam	// value passed to hook procedure
);
Parameters

hhk

Identifies the current hook. An application receives this handle as a result of a previous call to the SetWindowsHookEx function.

nCode

Specifies the hook code passed to the current hook procedure. The next hook procedure uses this code to determine how to process the hook information.

wParam

Specifies the wParam value passed to the current hook procedure. The meaning of this parameter depends on the type of hook associated with the current hook chain.

lParam

Specifies the lParam value passed to the current hook procedure. The meaning of this parameter depends on the type of hook associated with the current hook chain.

Return Values

If the function succeeds, the return value is the value returned by the next hook procedure in the chain. The current hook procedure must also return this value. The meaning of the return value depends on the hook type. For more information, see the descriptions of the individual hook procedures.

Remarks

Hook procedures are installed in chains for particular hook types. CallNextHookEx calls the next hook in the chain.

Calling CallNextHookEx is optional. A hook procedure can call this function either before or after processing the hook information. If a hook procedure does not call CallNextHookEx, Windows does not call the hook procedures installed before the current hook procedure was installed.

See Also

SetWindowsHook, SetWindowsHookEx, UnhookWindowsHook, UnhookWindowsHookEx


CallWindowProc

The CallWindowProc function passes message information to the specified window procedure.

LRESULT CallWindowProc(

WNDPROC lpPrevWndFunc,	// pointer to previous procedure
HWND hWnd,	// handle to window
UINT Msg,	// message
WPARAM wParam,	// first message parameter
LPARAM lParam	// second message parameter
);
Parameters

lpPrevWndFunc

Pointer to the previous window procedure.

If this value is obtained by calling the GetWindowLong function with the nIndex parameter set to GWL_WNDPROC or DWL_DLGPROC, it is actually either the address of a window or dialog box procedure, or a handle representing that address.

hWnd

Identifies the window procedure to receive the message.

Msg

Specifies the message.

wParam

Specifies additional message-specific information. The contents of this parameter depend on the value of the Msg parameter.

lParam

Specifies additional message-specific information. The contents of this parameter depend on the value of the Msg parameter.

Return Values

The return value specifies the result of the message processing and depends on the message sent.

Remarks

Use the CallWindowProc function for window subclassing. Usually, all windows with the same class share one window procedure. A subclass is a window or set of windows with the same class whose messages are intercepted and processed by another window procedure (or procedures) before being passed to the window procedure of the class.

The SetWindowLong function creates the subclass by changing the window procedure associated with a particular window, causing Windows to call the new window procedure instead of the previous one. An application must pass any messages not processed by the new window procedure to the previous window procedure by calling CallWindowProc. This allows the application to create a chain of window procedures.

If STRICT is defined, the lpPrevWndFunc parameter has the data type WNDPROC. The WNDPROC type is declared as follows:

LRESULT (CALLBACK* WNDPROC) (HWND, UINT, WPARAM, LPARAM);

If STRICT is not defined, the lpPrevWndFunc parameter has the data type FARPROC. The FARPROC type is declared as follows:

int (FAR WINAPI * FARPROC) ()

In C, the FARPROC declaration indicates a callback function that has an unspecified parameter list. In C++, however, the empty parameter list in the declaration indicates that a function has no parameters. This subtle distinction can break careless code. Following is one way to handle this situation:

#ifdef STRICT

  WNDPROC MyWindowProcedure

#else

  FARPROC MyWindowProcedure

#endif

...

    lResult = CallWindowProc(MyWindowProcedure, ...) ;

For further information about functions declared with empty argument lists, refer to The C++ Programming Language, Second Edition, by Bjarne Stroustrup.

Windows NT: The CallWindowProc function handles Unicode-to-ANSI conversion. You don’t get the conversion if you call the window procedure directly.

See Also

FARPROC, GetWindowLong, SetClassLong, SetWindowLong, WNDPROC


CallWndProc

The CallWndProc hook procedure is an application-defined or library-defined callback function that the system calls whenever the SendMessage function is called. Before passing the message to the destination window procedure, the system passes the message to the hook procedure. The hook procedure can examine the message; it cannot modify it.

CallWndProc is a placeholder for the application-defined or library-defined function name.

LRESULT CALLBACK CallWndProc(

int nCode,	// hook code
WPARAM wParam,	// current-process flag
LPARAM lParam	// address of structure with message data
);
Parameters

nCode

Specifies whether the hook procedure must process the message. If nCode is HC_ACTION, the hook procedure must process the message. If nCode is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies whether the message is sent by the current process. If the message is sent by the current process, it is nonzero; otherwise, it is NULL.

lParam

Pointer to a CWPSTRUCT structure that contains details about the message.

Return Values

The return value should be zero.

Remarks

The CallWndProc hook procedure can examine the message, but it cannot modify it. After the hook procedure returns control to the system, the message is passed to the window procedure.

An application installs the hook procedure by specifying the WH_CALLWNDPROC hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

The WM_CALLWNDPROC hook is called in the context of the thread that calls SendMessage, not the thread that receives the message.

See Also

CallNextHookEx, CWPSTRUCT, SendMessage, SetWindowsHookEx


CallWndRetProc [Now Supported on Windows NT]
CallWndRetProc

[Now Supported on Windows NT]

The CallWndRetProc hook procedure is an application-defined or library-defined callback function the system calls after the SendMessage function is called. After passing the message to the destination window procedure, the system passes the message to the hook procedure. The hook procedure can examine the message; it cannot modify it.

LRESULT CALLBACK CallWndRetProc(

int nCode,	// hook code
WPARAM wParam,	// current-process flag
LPARAM lParam	// address of structure with message data
);
Parameters

nCode

Specifies whether the hook procedure must process the message. If nCode is HC_ACTION, the hook procedure must process the message. If nCode is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies whether the message is sent by the current process. If the message is sent by the current process, it is nonzero; otherwise, it is NULL.

lParam

Points to a CWPRETSTRUCT structure that contains details about the message.

Return Values

The return value should be zero.

Remarks

An application installs the hook procedure by specifying the WH_CALLWNDPROCRET hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

CallWndRetProc is a placeholder for the application-defined or library-defined function name.

See Also

CallNextHookEx, CallWndProc, CWPRETSTRUCT, SendMessage, SetWindowsHookEx


CancelDC

The CancelDC function cancels any pending operation on the specified device context (DC).

BOOL CancelDC(

HDC hdc	// handle to device context
);
Parameters

hdc

Identifies the DC.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The CancelDC function is used by multithreaded applications to cancel lengthy drawing operations. If thread A initiates a lengthy drawing operation, thread B may cancel that operation by calling this function.

If an operation is canceled, the affected thread returns an error and the result of its drawing operation is undefined. The results are also undefined if no drawing operation was in progress when the function was called.

See Also

CreateThread, GetCurrentThread


CancelIO [New - Windows NT]
CancelIO

[New - Windows NT]

The CancelIO function cancels all pending input and output (I/O) operations that were issued by the calling thread for the specified file handle. The function does not cancel I/O operations issued for the file handle by other threads.

BOOL CancelIO(

HANDLE hFile	// file handle for which to cancel I/O
);
Parameters

hFile

Handle to a file. The function cancels all pending I/O operations for this file handle.

Return Values

If the function succeeds, the return value is nonzero All pending I/O operations issued by the calling thread for the file handle were successfully canceled.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If there are any I/O operations in progress for the specified file handle, and they were issued by the calling thread, the CancelIO function cancels them.

Note that the I/O operations must have been issued as overlapped I/O. If they were not, the I/O operations would not have returned to allow the thread to call the CancelIO function. Calling the CancelIO function with a file handle that was not opened with FILE_FLAG_OVERLAPPED does nothing.

All I/O operations that are canceled will complete with the error ERROR_OPERATION_ABORTED. All completion notifications for the I/O operations will occur normally.

See Also

CreateFile, DeviceIoControl, LockFileEx, ReadDirectoryChangesW, ReadFile, ReadFileEx, WriteFile, WriteFileEx


CancelWaitableTimer [New - Windows NT]
CancelWaitableTimer

[New - Windows NT]

The CancelWaitableTimer function sets the specified “waitable” timer to the inactive state.

BOOL CancelWaitableTimer(

HANDLE hTimer	// handle to a timer object
);
Parameters

hTimer

Identifies the timer object. The CreateWaitableTimer or OpenWaitableTimer function returns this handle.

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.

Remarks

The CancelWaitableTimer function does not change the signaled state of the timer. It stops the timer before it can be set to the signaled state. Therefore, threads performing a wait operation on the timer remain waiting until they time out or the timer is reactivated and its state is set to signaled.

To reactivate the timer, call the SetWaitableTimer function.

See Also

CreateWaitableTimer, OpenWaitableTimer, SetWaitableTimer


CascadeWindows [Now Supported on Windows NT]
CascadeWindows

[Now Supported on Windows NT]

The CascadeWindows function cascades the specified windows or the child windows of the specified parent window.

WORD WINAPI CascadeWindows(

HWND hwndParent,	// handle to parent window
UINT wHow,	// types of windows not to arrange
CONST RECT *lpRect,	// rectangle to arrange windows in
UINT cKids,	// number of windows to arrange
const HWND FAR *lpKids	// array of window handles
);
Parameters

hwndParent

Identifies the parent window. If this parameter is NULL, the desktop window is assumed.

wHow

Specifies a cascade flag. The only flag currently available, MDITILE_SKIPDISABLED, prevents disabled MDI child windows from being cascaded.

lpRect

Pointer to a SMALL_RECT structure that specifies the rectangular area, in screen coordinates, within which the windows are arranged. This parameter can be NULL, in which case the client area of the parent window is used.

cKids

Specifies the number of elements in the array specified by the lpKids parameter. This parameter is ignored if lpKids is NULL.

lpKids

Pointer to an array of window handles identifying the windows to arrange. If this parameter is NULL, the child windows of the specified parent window (or of the desktop window) are arranged.

Return Values

If the function succeeds, the return value is the number of windows arranged.

If the function fails, the return value is zero.

See Also

SMALL_RECT


CBTProc

The CBTProc hook procedure is an application-defined or library-defined callback function that the system calls before activating, creating, destroying, minimizing, maximizing, moving, or sizing a window; before completing a system command; before removing a mouse or keyboard event from the system message queue; before setting the keyboard focus; or before synchronizing with the system message queue. The value returned by the hook procedure determines whether Windows allows or prevents one of these operations. A computer-based training (CBT) application uses this hook procedure to receive useful notifications from the system.

LRESULT CALLBACK CBTProc(

int nCode,	// hook code
WPARAM wParam,	// depends on hook code
LPARAM lParam	// depends on hook code
);
Parameters

nCode

Specifies a code that the hook procedure uses to determine how to process the message. This parameter can be one of the following values:

Value	Meaning
HCBT_ACTIVATE	The system is about to activate a window.
HCBT_CLICKSKIPPED	The system has removed a mouse message from the system message queue. Upon receiving this hook code, a CBT application must install a WH_JOURNALPLAYBACK hook procedure in response to the mouse message.
HCBT_CREATEWND	A window is about to be created. The system calls the hook procedure before sending the WM_CREATE or WM_NCCREATE message to the window. If the hook procedure returns a nonzero value, the system destroys the window; the CreateWindow function returns NULL, but the WM_DESTROY message is not sent to the window. If the hook procedure returns zero, the window is created normally.
	At the time of the HCBT_CREATEWND notification, the window has been created, but its final size and position may not have been determined and its parent window may not have been established. It is possible to send messages to the newly created window, although it has not yet received WM_NCCREATE or WM_CREATE messages. It is also possible to change the position in the Z order of the newly created window by modifying the hwndInsertAfter member of the CBT_CREATEWND structure.
HCBT_DESTROYWND	A window is about to be destroyed.
HCBT_KEYSKIPPED	The system has removed a keyboard message from the system message queue. Upon receiving this hook code, a CBT application must install a WH_JOURNALPLAYBACK_hook hook procedure in response to the keyboard message.
HCBT_MINMAX	A window is about to be minimized or maximized.
HCBT_MOVESIZE	A window is about to be moved or sized.
HCBT_QS	The system has retrieved a WM_QUEUESYNC message from the system message queue.
HCBT_SETFOCUS	A window is about to receive the keyboard focus.
HCBT_SYSCOMMAND	A system command is about to be carried out. This allows a CBT application to prevent task switching by means of hot keys.
If nCode is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Depends on the nCode parameter. For details, see the following Remarks section.

lParam

Depends on the nCode parameter. For details, see the following Remarks section.

Return Values

For operations corresponding to the following CBT hook codes, the return value must be 0 to allow the operation, or 1 to prevent it:

HCBT_ACTIVATE
HCBT_CREATEWND
HCBT_DESTROYWND
HCBT_MINMAX
HCBT_MOVESIZE
HCBT_SETFOCUS
HCBT_SYSCOMMAND

For operations corresponding to the following CBT hook codes, the return value is ignored:

HCBT_CLICKSKIPPED
HCBT_KEYSKIPPED
HCBT_QS

Remarks

The hook procedure should not install a WH_JOURNALPLAYBACK_hook hook procedure except in the situations described in the preceding list of hook codes.

This hook procedure must be in a dynamic-link library (DLL). An application installs the hook procedure by specifying the WH_CBT hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

The following table describes the wParam and lParam parameters for each HCBT_ hook code:

Value	wParam	lParam
HCBT_ACTIVATE	Specifies the handle to the window about to be activated.	Specifies a long pointer to a CBTACTIVATESTRUCT structure containing the handle to the active window and specifies whether the activation is changing because of a mouse click.
HCBT_CLICKSKIPPED	Identifies the mouse message removed from the system message queue.	Specifies a long pointer to a MOUSEHOOKSTRUCT structure containing the hit-test code and the handle to the window for which the mouse message is intended.  The HCBT_CLICKSKIPPED value is sent to a CBTProc hook procedure only if a WH_MOUSE hook is installed. For a list of hit-test codes, see WM_NCHITTEST .
HCBT_CREATEWND	Specifies the handle to the new window.	Specifies a long pointer to a CBT_CREATEWND structure containing initialization parameters for the window. The parameters include the coordinates and dimensions of the window. By changing these parameters, a CBTProc hook procedure can set the initial size and position of the window.
HCBT_DESTROYWND	Specifies the handle to the window about to be destroyed.	Is undefined and must be set to zero.
HCBT_KEYSKIPPED	Identifies the virtual-key code.	Specifies the repeat count, scan code, key-transition code, previous key state, and context code. The HCBT_KEYSKIPPED value is sent to a CBTProc hook procedure only if a WH_KEYBOARD hook is installed. For more information, see the WM_KEYUP or WM_KEYDOWN message.
HCBT_MINMAX	Specifies the handle to the window being minimized or maximized.	Specifies, in the low-order word, a show-window value (SW_) specifying the operation. For a list of show-window values, see the ShowWindow. The high-order word is undefined.
HCBT_MOVESIZE	Specifies the handle to the window to be moved or sized.	Specifies a long pointer to a RECT structure containing the coordinates of the window. By changing the values in the structure, a CBTProc hook procedure can set the final coordinates of the window.
HCBT_QS	Is undefined and must be zero.	Is undefined and must be zero.
HCBT_SETFOCUS	Specifies the handle to the window gaining the keyboard focus.	Specifies the handle to the window losing the keyboard focus.
HCBT_SYSCOMMAND	Specifies a system-command value (SC_) specifying the system command. For more information about system-command values, see WM_SYSCOMMAND.	Contains the same data as the lParam value of a WM_SYSCOMMAND message: If a system menu command is chosen with the mouse, the low-order word contains the x-coordinate of the cursor, in screen coordinates, and the high-order word contains the y-coordinate; otherwise, the parameter is not used.
CBTProc is a placeholder for the application-defined or library-defined function name.

See Also

CallNextHookEx, CreateWindow, SetWindowsHookEx, WM_SYSCOMMAND


CCHookProc

A CCHookProc hook procedure is an application-defined or library-defined callback procedure that is used with the Color common dialog box. The hook procedure receives messages or notifications intended for the default dialog box procedure.

UINT APIENTRY CCHookProc(

HWND hdlg,	// handle to the dialog box window
UINT uiMsg,	// message identifier
WPARAM wParam,	// message parameter
LPARAM lParam	// message parameter
);
Parameters

hdlg

Handle to the Color dialog box window for which the message is intended.

uiMsg

Identifies the message being received.

wParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

lParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

If the uiMsg parameter indicates the WM_INITDIALOG message, lParam is a pointer to a CHOOSECOLOR structure containing the values specified when the dialog was created.

Return Values

If the hook procedure returns zero, the default dialog box procedure processes the message.

If the hook procedure returns a nonzero value, the default dialog box procedure ignores the message.

Remarks

When you use the ChooseColor function to create a Color dialog box, you can provide a CCHookProc hook procedure to process messages or notifications intended for the dialog box procedure. To enable the hook procedure, use the CHOOSECOLOR structure that you passed to the dialog creation function. Specify the address of the hook procedure in the lpfnHook member and specify the CC_ENABLEHOOK flag in the Flags member.

The default dialog box procedure processes the WM_INITDIALOG message before passing it to the hook procedure. For all other messages, the hook procedure receives the message first. Then, the return value of the hook procedure determines whether the default dialog procedure processes the message or ignores it.

If the hook procedure processes the WM_CTLCOLORDLG message, it must return a valid brush handle for painting the background of the dialog box. In general, if the hook procedure processes any WM_CTLCOLOR* message, it must return a valid brush handle for painting the background of the specified control.

Do not call the EndDialog function from the hook procedure. Instead, the hook procedure can call the PostMessage function to post a WM_COMMAND message with the IDABORT value to the dialog box procedure. Posting IDABORT closes the dialog box and causes the dialog box function to return FALSE. If you need to know why the hook procedure closed the dialog box, you must provide your own communication mechanism between the hook procedure and your application.

You can subclass the standard controls of the common dialog box. However, the common dialog box procedure may also subclass the controls. Because of this, you should subclass controls when your hook procedure processes the WM_INITDIALOG message. This ensures that your subclass procedure receives the control-specific messages before the subclass procedure set by the dialog box procedure.

CCHookProc is a placeholder for the application-defined or library-defined function name. The LPCCHOOKPROC type is a pointer to a CCHookProc hook procedure.

See Also

ChooseColor, CHOOSECOLOR, EndDialog, PostMessage, WM_INITDIALOG, WM_CTLCOLORDLG


CFHookProc

A CFHookProc hook procedure is an application-defined or library-defined callback procedure that is used with the Font common dialog box. The hook procedure receives messages or notifications intended for the default dialog box procedure.

UINT APIENTRY CFHookProc(

HWND hdlg,	// handle to the dialog box window
UINT uiMsg,	// message identifier
WPARAM wParam,	// message parameter
LPARAM lParam	// message parameter
);
Parameters

hdlg

Handle to the Font dialog box window for which the message is intended.

uiMsg

Identifies the message being received.

wParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

lParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

If the uiMsg parameter indicates the WM_INITDIALOG message, lParam is a pointer to a CHOOSEFONT structure containing the values specified when the common dialog box was created.

Return Values

If the hook procedure returns zero, the default dialog box procedure processes the message.

If the hook procedure returns a nonzero value, the default dialog box procedure ignores the message.

Remarks

When you use the ChooseFont function to create a Font dialog box, you can provide a CFHookProc hook procedure to process messages or notifications intended for the dialog box procedure. To enable the hook procedure, use the CHOOSEFONT structure that you passed to the dialog creation function. Specify the address of the hook procedure in the lpfnHook member and specify the CF_ENABLEHOOK flag in the Flags member.

The default dialog box procedure processes the WM_INITDIALOG message before passing it to the hook procedure. For all other messages, the hook procedure receives the message first. Then, the return value of the hook procedure determines whether the default dialog procedure processes the message or ignores it.

If the hook procedure processes the WM_CTLCOLORDLG message, it must return a valid brush handle for painting the background of the dialog box. In general, if the hook procedure processes any WM_CTLCOLOR* message, it must return a valid brush handle for painting the background of the specified control.

Do not call the EndDialog function from the hook procedure. Instead, the hook procedure can call the PostMessage function to post a WM_COMMAND message with the IDABORT value to the dialog box procedure. Posting IDABORT closes the dialog box and causes the dialog box function to return FALSE. If you need to know why the hook procedure closed the dialog box, you must provide your own communication mechanism between the hook procedure and your application.

You can subclass the standard controls of the common dialog box. However, the common dialog box procedure may also subclass the controls. Because of this, you should subclass controls when your hook procedure processes the WM_INITDIALOG message. This ensures that your subclass procedure receives the control-specific messages before the subclass procedure set by the dialog box procedure.

CFHookProc is a placeholder for the application-defined or library-defined function name. The LPCFHOOKPROC type is a pointer to an CFHookProc hook procedure.

See Also

ChooseFont, CHOOSEFONT, EndDialog, PostMessage, WM_INITDIALOG, WM_CTLCOLORDLG


ChangeClipboardChain

The ChangeClipboardChain function removes a specified window from the chain of clipboard viewers.

BOOL ChangeClipboardChain(

HWND hWndRemove,	// handle to window to remove
HWND hWndNewNext	// handle to next window
);
Parameters

hWndRemove

Identifies the window to be removed from the chain. The handle must have been passed to the SetClipboardViewer function.

hWndNewNext

Identifies the window that follows the hWndRemove window in the clipboard viewer chain. (This is the handle returned by SetClipboardViewer, unless the sequence was changed in response to a WM_CHANGECBCHAIN message.)

Return Values

The return value indicates the result of passing the WM_CHANGECBCHAIN message to the windows in the clipboard viewer chain. Because a window in the chain typically returns FALSE when it processes WM_CHANGECBCHAIN, the return value from ChangeClipboardChain is typically FALSE. If there is only one window in the chain, the return value is typically TRUE.

Remarks

The window identified by hWndNewNext replaces the hWndRemove window in the chain. The SetClipboardViewer function sends a WM_CHANGECBCHAIN message to the first window in the clipboard viewer chain.

See Also

SetClipboardViewer, WM_CHANGECBCHAIN


ChangeDisplaySettings

The ChangeDisplaySettings function changes the display settings to the specified graphics mode.

LONG ChangeDisplaySettings(

LPDEVMODE lpDevMode,
DWORD dwflags
);
Parameters

lpDevMode

Pointer to a DEVMODE structure that describes the graphics mode to switch to. The dmSize member must be initialized to the size, in bytes, of the DEVMODE structure. The following fields in the DEVMODE structure are used:

Member	Meaning
dmBitsPerPel	Bits per pixel
dmPelsWidth	Pixel width
dmPelsHeight	Pixel height
dmDisplayFlags	Mode flags
dmDisplayFrequency	Mode frequency
In addition to setting a value in one or more of the preceding DEVMODE members, you must also set the appropriate flags in the dmFields member. The flags indicate which members of the DEVMODE structure are used for the display settings change. If the appropriate bit is not set in dmFields, the display setting will not be changed. Set one or more of the following flags:

Flag	Meaning
DM_BITSPERPEL	Use the dmBitsPerPel value.
DM_PELSWIDTH	Use the dmPelsWidth value.
DM_PELSHEIGHT	Use the dmPelsHeight value.
DM_DISPLAYFLAGS	Use the dmDisplayFlags value.
DM_DISPLAYFREQENCY	Use the dmDisplayFrequency value.
If lpDevMode is NULL, all the values currently in the registry will be used for the display setting. Passing NULL for the lpDevMode parameter is the easiest way to return to the default mode after a dynamic mode change.

dwflags

Indicates how the graphics mode should be changed. May be one of the following:

Flag	Meaning
0	The graphics mode for the current screen will be changed dynamically.
CDS_UPDATEREGISTRY	The graphics mode for the current screen will be changed dynamically and the graphics mode will be updated in the registry. The mode information is stored in the USER profile.
CDS_TEST	The system tests if the requested graphics mode could be set.
If CDS_UPDATEREGISTRY is specified and it is possible to change the graphics mode dynamically, the information is stored in the registry and DISP_CHANGE_SUCCESSFUL is returned. If it is not possible to change the graphics mode dynamically, the information is stored in the registry and DISP_CHANGE_RESTART is returned.

Windows NT: If the information could not be stored in the registry, the graphics mode is not changed and DISP_CHANGE_NOTUPDATED is returned.

Specifying CDS_TEST allows an application to determine which graphics modes are actually valid, without causing the system to change to that graphics mode.

Return Values

Returns one of the following values:

Value	Meaning
DISP_CHANGE_SUCCESSFUL	The settings change was successful.
DISP_CHANGE_RESTART	The computer must be restarted in order for the graphics mode to work.
DISP_CHANGE_BADFLAGS	An invalid set of flags was passed in.
DISP_CHANGE_FAILED	The display driver failed the specified graphics mode.
DISP_CHANGE_BADMODE	The graphics mode is not supported.
DISP_CHANGE_NOTUPDATED	Windows NT only: Unable to write settings to the registry.
Remarks

Using the DEVMODE returned by the EnumDisplaySettings function ensures that the DEVMODE passed to ChangeDisplaySettings is valid and contains only values supported by the display driver.

When the display mode is changed dynamically, the WM_DISPLAYCHANGE message is sent to all running applications with the following message parameters:

Parameters	Meaning
wParam	New bits per pixel
LOWORD(lParam)	New pixel width
HIWORD(lParam)	New pixel height
See Also

CreateDC, DEVMODE, EnumDisplaySettings, WM_DISPLAYCHANGE


ChangeMenu

The ChangeMenu function has been replaced by the following specialized functions, which are available on both Windows NT and Windows 95:

Function	Description
AppendMenu	Appends a menu item to the end of a menu.
InsertMenu	Inserts a menu item into a menu.
ModifyMenu	Modifies a menu item in a menu.
RemoveMenu	Removes a menu item from a menu; if it is a pop-up item, the corresponding pop-up menu is not destroyed.
Windows 95:

Instead of using AppendMenu, InsertMenu, and ModifyMenu, applications written exclusively for Window 95 should use the following new functions, which are available only on Windows 95.

Function	Description
GetMenuItemInfo	Gets information about a menu item.
InsertMenuItem	Inserts a new menu item at the specified position in a menu bar or pop-up menu.
SetMenuItemInfo	Changes information about a menu item.
Applications written for versions earlier than Windows 3.0 can continue to call ChangeMenu. Applications written for Windows versions 3.0 and later should call these new functions.


ChangeServiceConfig

The ChangeServiceConfig function changes the configuration parameters of a service.

BOOL ChangeServiceConfig(

SC_HANDLE hService,	// handle to service
DWORD dwServiceType,	// type of service
DWORD dwStartType,	// when to start service
DWORD dwErrorControl,	// severity if service fails to start
LPCTSTR lpBinaryPathName,	// pointer to service binary file name
LPCTSTR lpLoadOrderGroup,	// pointer to load ordering group name
LPDWORD lpdwTagId,	// pointer to variable to get tag identifier
LPCTSTR lpDependencies,	// pointer to array of dependency names
LPCTSTR lpServiceStartName,	// pointer to account name of service
LPCTSTR lpPassword,	// pointer to password for service account
LPCTSTR lpDisplayName	// pointer to display name
);
Parameters

hService

Identifies the service. This handle is returned by the OpenService or CreateService function and must have SERVICE_CHANGE_CONFIG access.

dwServiceType

A set of bit flags that specify the type of service. Specify SERVICE_NO_CHANGE if you are not changing the existing service type; otherwise, specify one of the following service type flags to indicate the service type. In addition, if you specify either of the SERVICE_WIN32 flags, you can also specify the SERVICE_INTERACTIVE_PROCESS flag to enable the service process to interact with the desktop.

Value	Meaning
SERVICE_WIN32_OWN_PROCESS	A service type flag that specifies a Win32 service that runs in its own process.
SERVICE_WIN32_SHARE_PROCESS	A service type flag that specifies a Win32 service that shares a process with other services.
SERVICE_KERNEL_DRIVER	A service type flag that specifies a Windows NT device driver.
SERVICE_FILE_SYSTEM_DRIVER	A service type flag that specifies a Windows NT file system driver.
SERVICE_INTERACTIVE_PROCESS	A flag that enables a Win32 service process to interact with the desktop.
dwStartType

Specifies when to start the service. This value can be the service type SERVICE_NO_CHANGE if the existing start type is not modified, or one of the following values can be specified:

Value	Meaning
SERVICE_BOOT_START	Specifies a device driver started by the operating system loader. This value is valid only if the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_SYSTEM_START	Specifies a device driver started by the IoInitSystem function. This value is valid only if the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_AUTO_START	Specifies a device driver or Win32 service started by the service control manager automatically during system startup.
SERVICE_DEMAND_START	Specifies a device driver or Win32 service started by the service control manager when a process calls the StartService function.
SERVICE_DISABLED	Specifies a device driver or Win32 service that can no longer be started.
dwErrorControl

Specifies the severity of the error if this service fails to start during startup, and determines the action taken by the startup program if failure occurs. One of the following values can be specified:

Value	Meaning
SERVICE_ERROR_IGNORE	The startup (boot) program logs the error but continues the startup operation.
SERVICE_ERROR_NORMAL	The startup program logs the error and puts up a message box pop-up but continues the startup operation.
SERVICE_ERROR_SEVERE	The startup program logs the error. If the last-known-good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known-good configuration.
SERVICE_ERROR_CRITICAL	The startup program logs the error, if possible. If the last-known-good configuration is being started, the startup operation fails. Otherwise, the system is restarted with the last-known good configuration.
SERVICE_NO_CHANGE	The existing StartType value is not to be changed.
lpBinaryPathName

Pointer to a null-terminated string that contains the fully qualified path to the service binary file. If the pointer is NULL, the path is not modified.

lpLoadOrderGroup

Pointer to a null-terminated string that names the load ordering group of which this service is a member. If the pointer is NULL, the group is not modified. If it points to an empty string, the service does not belong to a group.

The registry has a list of load ordering groups located at

HKEY_LOCAL_MACHINES\System\CurrentControlSet
\Control\ServiceGroupOrder.

The startup program uses this list to load groups of services in a specified order with respect to the other groups in the list. You can place a service in a group so that another service can depend on the group.

The order in which a service starts is determined by the following criteria:

1.	The order of groups in the registry’s load-ordering group list. Services in groups in the load-ordering group list are started first, followed by services in groups not in the load-ordering group list, and then services that do not belong to a group.

2.	The service’s dependencies listed in the lpDependencies parameter and the dependencies of other services dependent on the service.

lpdwTagId

Pointer to a 32-bit variable that receives a unique tag value for this service in the group specified in the lpLoadOrderGroup parameter. If no tag is requested, this parameter can be NULL.

You can use a tag for ordering service startup within a load ordering group by specifying a tag order vector in the registry located at

HKEY_LOCAL_MACHINE\System\CurrentControlSet
\Control\GroupOrderList.

Tags are only evaluated for SERVICE_KERNEL_DRIVER and SERVICE_FILE_SYSTEM_DRIVER type services that have SERVICE_BOOT_START or SERVICE_SYSTEM_START start types.

lpDependencies

Pointer to an array of null-separated names of services or load ordering groups that must start before this service. The array is double null-terminated. If the pointer is NULL, the dependencies are not modified. If it points to an empty string, the service has no dependencies. If a group name is specified, it must be prefixed by the SC_GROUP_IDENTIFIER character (defined in the WINSVC.H files) to differentiate it from a service name, because services and service groups share the same name space. Dependency on a service means that this service can only run if the service it depends on is running. Dependency on a group means that this service can run if at least one member of the group is running after an attempt to start all members of the group.

lpServiceStartName

Pointer to a null-terminated string. If NULL is specified, the name is not modified. If the service type is SERVICE_WIN32_OWN_PROCESS, this name is the account name in the form of “DomainName\Username”, which the service process will be logged on as when it runs. If the account belongs to the built-in domain, “.\Username” can be specified. Services of type SERVICE_WIN32_SHARE_PROCESS are not allowed to specify an account other than LocalSystem.

If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, this name is the Windows NT driver object name (that is, \FileSystem\Rdr or \Driver\Xns), which the input and output (I/O) system uses to load the device driver. If NULL is specified, the driver is run with a default object name created by the I/O system, based on the service name.

lpPassword

Pointer to a null-terminated string that contains the password to the account name specified by the lpServiceStartName parameter if the service type is SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS. If the pointer is NULL, the password is not modified. If it points to an empty string, the service has no password. If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, this parameter is ignored.

lpDisplayName

Pointer to a null-terminated string that is to be used by user interface programs to identify the service. This string has a maximum length of 256 characters. The name is case-preserved in the Service Control Manager. Display name comparisons are always case-insensitive.

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.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED
	The specified handle was not opened with SERVICE_CHANGE_CONFIG access.
ERROR_CIRCULAR_DEPENDENCY
	A circular service dependency was specified.
ERROR_DUP_NAME
	The display name already exists in the service controller’s database, either as a service name or as another display name.
ERROR_INVALID_HANDLE
	The specified handle is invalid.
ERROR_INVALID_PARAMETER
	A parameter that was specified is invalid.
ERROR_INVALID_SERVICE_ACCOUNT
	The account name does not exist, or a service is specified to share the same binary file as an already installed service but with an account name that is not the same as the installed service.
ERROR_SERVICE_MARKED_FOR_DELETE
	The service has been marked for deletion.
Remarks

The ChangeServiceConfig function changes the configuration information for the specified service in the service control manager database. This configuration information is initially specified by the CreateService function and can be queried (except for the password parameter) by using the QueryServiceConfig function.

Any of the configuration parameters specified for this function can be left unchanged by specifying NULL for a string parameter or SERVICE_NO_CHANGE for a doubleword parameter.

If the configuration is changed for a service that is running, with the exception of lpDisplayName, the changes do not take effect until the service is stopped.

See Also

CreateService, OpenService, QueryServiceConfig, StartService


CharLower

The CharLower function converts a character string or a single character to lowercase. If the operand is a character string, the function converts the characters in place. This function supersedes the AnsiLower function.

LPTSTR CharLower(

LPTSTR lpsz	// single character or pointer to string
);
Parameters

lpsz

Pointer to a null-terminated string or specifies a single character. If the high-order word of this parameter is zero, the low-order word must contain a single character to be converted.

Return Values

If the operand is a character string, the function returns a pointer to the converted string. Since the string is converted in place, the return value is equal to lpsz.

If the operand is a single character, the return value is a 32-bit value whose high-order word is zero, and low-order word contains the converted character.

There is no indication of success or failure. Failure is rare.

Remarks

Windows NT: To make the conversion, the function uses the language driver for the current language selected by the user at setup or by using the Control Panel. If no language has been selected, Windows completes the conversion by using internal default mapping. The conversion is made based on the code page associated with the process locale.

Windows 95: The function makes the conversion based on the information associated with the user's default locale, which is the locale selected by the user at setup or by using the Control Panel. Windows 95 does not have language drivers.

See Also

CharLowerBuff, CharUpper, CharUpperBuff


CharLowerBuff

The CharLowerBuff function converts uppercase characters in a buffer to lowercase characters. The function converts the characters in place. The function supersedes the AnsiLowerBuff function.

DWORD CharLowerBuff(

LPTSTR lpsz,	// pointer to buffer containing characters to process
DWORD cchLength	// number of bytes or characters to process
);
Parameters

lpsz

Pointer to a buffer containing one or more characters to process.

cchLength

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the buffer pointed to by lpsz.

The function examines each character, and converts uppercase characters to lowercase characters. The function examines the number of bytes or characters indicated by cchLength, even if one or more characters are null characters.

Return Values

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) processed.

For example, if CharLowerBuff("Acme of Operating Systems", 10) succeeds, the return value is 10.

Remarks

Windows NT: To make the conversion, the function uses the language driver for the current language selected by the user at setup or by using the Control Panel. If no language has been selected, Windows completes the conversion by using internal default mapping. The conversion is made based on the code page associated with the process locale.

Windows 95: The function makes the conversion based on the information associated with the user's default locale, which is the locale selected by the user at setup or by using the Control Panel. Windows 95 does not have language drivers.

See Also

CharLower, CharUpper, CharUpperBuff


CharNext

The CharNext function returns a pointer to the next character in a string. This function supersedes the AnsiNext function.

LPTSTR CharNext(

LPCTSTR lpsz	// pointer to current character
);
Parameters

lpsz

Pointer to a character in a null-terminated string.

Return Values

If the function succeeds, the return value is a pointer to the next character in the string, or to the terminating null character if at the end of the string.

If lpsz points to the terminating null character, the return value is equal to lpsz.

See Also

CharNextExA, CharPrev


CharNextExA [Now Supported on Windows NT]
CharNextExA

[Now Supported on Windows NT]

The CharNextExA function retrieves the pointer to the next character in a string. This function can handle strings consisting of either single- or multi-byte characters.

LPSTR CharNextExA(

WORD CodePage,	// identifier of the code page
LPCSTR lpCurrentChar,	// pointer to current character
DWORD dwFlags	// reserved; must be zero
);
Parameters

CodePage

Identifier of the code page to use to check lead-byte ranges. Can be one of the code-page values provided in the “Code-Page Identifiers” table in Unicode and Character Set Constants or one of the following predefined values:

Value	Meaning
0	Use system default ANSI code page.
CP_ACP	Use system default ANSI code page.
CP_OEMCP	Use system default OEM code page.
lpCurrentChar

Pointer to a character in a null-terminated string.

dwFlags

Reserved; must be zero.

Return Values

If the function succeeds, the return value is a pointer to the next character in the string, or to the terminating null character if at the end of the string.

If lpCurrentChar points to the terminating null character, the return value is equal to lpCurrentChar.

See Also

CharNext, CharPrevExA


CharPrev

The CharPrev function returns a pointer to the preceding character in a string. This function supersedes the AnsiPrev function.

LPTSTR CharPrev(

LPCTSTR lpszStart,	// pointer to first character
LPCTSTR lpszCurrent	// pointer to current character
);
Parameters

lpszStart

Pointer to the beginning of the string.

lpszCurrent

Pointer to a character in a null-terminated string.

Return Values

If the function succeeds, the return value is a pointer to the preceding character in the string, or to the first character in the string if the lpszCurrent parameter equals the lpszStart parameter.

See Also

CharNext, CharPrevExA


CharPrevExA [Now Supported on Windows NT]
CharPrevExA

[Now Supported on Windows NT]

The CharPrevExA function retrieves the pointer to the preceding character in a string. This function can handle strings consisting of either single- or multi-byte characters.

LPSTR CharPrevExA(

WORD CodePage,	// identifier of code page
LPCSTR lpStart,	// pointer to first character
LPCSTR lpCurrentChar,	// pointer to current character
DWORD dwFlags	// reserved; must be zero
);
Parameters

CodePage

Identifier of the code page to use to check lead-byte ranges. Can be one of the code-page values provided in the “Code-Page Identifiers” table in Unicode and Character Set Constants or one of the following predefined values:

Value	Meaning
0	Use system default ANSI code page.
CP_ACP	Use system default ANSI code page.
CP_OEMCP	Use system default OEM code page.
lpStart

Pointer to the beginning of the string.

lpCurrentChar

Pointer to a character in a null-terminated string.

dwFlags

Reserved; must be zero.

Return Values

If the function succeeds, the return value is a pointer to the preceding character in the string, or to the first character in the string if the lpCurrentChar parameter equals the lpStart parameter.

See Also

CharNextExA, CharPrev


CharToOem

The CharToOem function translates a string into the OEM-defined character set. (OEM stands for original equipment manufacturer.) This function supersedes the AnsiToOem function.

BOOL CharToOem(

LPCTSTR lpszSrc,	// pointer to string to translate
LPSTR lpszDst	// pointer to translated string
);
Parameters

lpszSrc

Pointer to the null-terminated string to translate.

lpszDst

Pointer to the buffer for the translated string. If the CharToOem function is being used as an ANSI function, the string can be translated in place by setting the lpszDst parameter to the same address as the lpszSrc parameter. This cannot be done if CharToOem is being used as a wide-character function.

Return Values

The return value is always nonzero.

See Also

CharToOemBuff, OemToChar, OemToCharBuff


CharToOemBuff

The CharToOemBuff function translates a specified number of characters in a string into the OEM-defined character set. (OEM stands for original equipment manufacturer.) This function supersedes the AnsiToOemBuff function.

BOOL CharToOemBuff(

LPCTSTR lpszSrc,	// pointer to string to translate
LPSTR lpszDst,	// pointer to translated string
DWORD cchDstLength	// length of string to translate, in characters
);
Parameters

lpszSrc

Pointer to the null-terminated string to translate.

lpszDst

Pointer to the buffer for the translated string. If the CharToOemBuff function is being used as an ANSI function, the string can be translated in place by setting the lpszDst parameter to the same address as the lpszSrc parameter. This cannot be done if CharToOemBuff is being used as a wide-character function.

cchDstLength

Specifies the number of characters to translate in the string identified by the lpszSrc parameter.

Return Values

The return value is always nonzero.

See Also

CharToOem, OemToChar, OemToCharBuff


CharUpper

The CharUpper function converts a character string or a single character to uppercase. If the operand is a character string, the function converts the characters in place. This function supersedes the AnsiUpper function.

LPTSTR CharUpper(

LPTSTR lpsz	// single character or pointer to string
);
Parameters

lpsz

Pointer to a null-terminated string or specifies a single character. If the high-order word of this parameter is zero, the low-order word must contain a single character to be converted.

Return Values

If the operand is a character string, the function returns a pointer to the converted string. Since the string is converted in place, the return value is equal to lpsz.

If the operand is a single character, the return value is a 32-bit value whose high-order word is zero, and low-order word contains the converted character.

There is no indication of success or failure. Failure is rare.

Remarks

Windows NT: To make the conversion, the function uses the language driver for the current language selected by the user at setup or by using the Control Panel. If no language has been selected, Windows completes the conversion by using internal default mapping. The conversion is made based on the code page associated with the process locale.

Windows 95: The function makes the conversion based on the information associated with the user's default locale, which is the locale selected by the user at setup or by using the Control Panel. Windows 95 does not have language drivers.

See Also

CharLower, CharLowerBuff, CharUpperBuff


CharUpperBuff

The CharUpperBuff function converts lowercase characters in a buffer to uppercase characters. The function converts the characters in place. The function supersedes the AnsiUpperBuff function.

DWORD CharUpperBuff(

LPTSTR lpsz,	// pointer to buffer containing characters to process
DWORD cchLength	// number of characters to process
);
Parameters

lpsz

Pointer to a buffer containing one or more characters to process.

cchLength

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the buffer pointed to by lpsz.

The function examines each character, and converts lowercase characters to uppercase characters. The function examines the number of bytes or characters indicated by cchLength, even if one or more characters are null characters.

Return Values

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) processed.

For example, if CharUpperBuff("Zenith of API Sets", 10) succeeds, the return value is 10.

Remarks

Windows NT: To make the conversion, the function uses the language driver for the current language selected by the user at setup or by using the Control Panel. If no language has been selected, Windows completes the conversion by using internal default mapping. The conversion is made based on the code page associated with the process locale.

Windows 95: The function makes the conversion based on the information associated with the user's default locale, which is the locale selected by the user at setup or by using the Control Panel. Windows 95 does not have language drivers.

See Also

CharLower, CharLowerBuff, CharUpper


CheckColorsInGamut

The CheckColorsInGamut function indicates whether the specified color values are within the gamut of the specified device.

BOOL CheckColorsInGamut(

HDC hdc,
LPVOID lpaRGBQuad,
LPVOID lpResult,
DWORD nCount
);
Parameters

hdc

Handle to a device context.

lpaRGBQuad

Pointer to an array of RGBQUAD structures that contains the color values to check.

lpResult

Pointer to an array of bytes that receives the results of the color checking.

nCount

Count of elements in the array.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

For each specified color value, CheckColorsInGamut sets the corresponding byte in the results buffer to either CM_IN_GAMUT or CM_OUT_OF_GAMUT.

See Also

RGBQUAD


CheckDlgButton

The CheckDlgButton function changes the check state of a button control.

BOOL CheckDlgButton(

HWND hDlg,	// handle to dialog box
int nIDButton,	// button-control identifier
UINT uCheck	// check state
);
Parameters

hDlg

Identifies the dialog box that contains the button.

nIDButton

Identifies the button to modify.

uCheck

Specifies the check state of the button. This parameter can be one of the following values:

Value	Meaning
BST_CHECKED	Sets the button state to checked.
BST_INDETERMINATE	Sets the button state to grayed, indicating an indeterminate state. Use this value only if the button has the BS_3STATE or BS_AUTO3STATE style.
BST_UNCHECKED	Sets the button state to unchecked
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.

Remarks

The CheckDlgButton function sends a BM_SETCHECK message to the specified button control in the specified dialog box.

See Also

CheckRadioButton, IsDlgButtonChecked


CheckMenuItem

The CheckMenuItem function sets the state of the specified menu item's check mark attribute to either checked or unchecked.

The CheckMenuItem function has been superseded by the SetMenuItemInfo function. You can still use CheckMenuItem, however, if you do not need any of the extended features of SetMenuItemInfo.

DWORD CheckMenuItem(

HMENU hmenu,	// handle to menu
UINT uIDCheckItem,	// menu item to check or uncheck
UINT uCheck	// menu item flags
);
Parameters

hmenu

Identifies the menu of interest.

uIDCheckItem

Specifies the menu item whose check-mark attribute is to be set, as determined by the uCheck parameter.

uCheck

Specifies flags that control the interpretation of the uIDCheckItem parameter and the state of the menu item’s check-mark attribute. This parameter can be a combination of either MF_BYCOMMAND, or MF_BYPOSITION and MF_CHECKED or MF_UNCHECKED.

Value	Meaning
MF_BYCOMMAND	Indicates that the uIDCheckItem parameter gives the identifier of the menu item. The MF_BYCOMMAND flag is the default, if neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified.
MF_BYPOSITION	Indicates that the uIDCheckItem parameter gives the zero-based relative position of the menu item.
MF_CHECKED	Sets the check-mark attribute to the checked state.
MF_UNCHECKED	Sets the check-mark attribute to the unchecked state.
Return Values

The return value specifies the previous state of the menu item (either MF_CHECKED or MF_UNCHECKED). If the menu item does not exist, the return value is 0xFFFFFFFF.

Remarks

An item in a menu bar cannot have a check mark.

The uIDCheckItem parameter identifies a item that opens a submenu or a command item. For a item that opens a submenu, the uIDCheckItem parameter must specify the position of the item. For a command item, the uIDCheckItem parameter can specify either the item’s position or its identifier.

See Also

EnableMenuItem, GetMenuCheckMarkDimensions, GetMenuItemID, SetMenuItemBitmaps, SetMenuItemInfo


CheckMenuRadioItem [Now Supported on Windows NT]
CheckMenuRadioItem

[Now Supported on Windows NT]

The CheckMenuRadioItem function checks a specified menu item and makes it a radio item. At the same time, the function unchecks all other menu items in the associated group and clears the radio-item type flag for those items.

BOOL CheckMenuRadioItem(

HMENU hmenu,
UINT idFirst,
UINT idLast,
UINT idCheck,
UINT uFlags
);
Parameters

hmenu

Handle to the menu that contains the group of menu items.

idFirst

Identifier or position of the first menu item in the group.

idLast

Identifier or position of the last menu item in the group.

idCheck

Identifier or position of the menu item to check.

uFlags

Value specifying the meaning of idFirst, idLast, and idCheck. If this parameter is MF_BYCOMMAND, the other parameters specify menu item identifiers. If it is MF_BYPOSITION, the other parameters specify the menu item positions.

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, use the GetLastError function.

Remarks

The CheckMenuRadioItem function sets the MFT_RADIOCHECK type flag and the MFS_CHECKED state for the item specified by idCheck and, at the same time, clears both flags for all other items in the group. The checked item is displayed using a bullet bitmap instead of a check-mark bitmap.

For more information about menu item type and state flags, see the MENUITEMINFO structure.

See Also

MENUITEMINFO


CheckRadioButton

The CheckRadioButton function adds a check mark to (checks) a specified radio button in a group and removes a check mark from (clears) all other radio buttons in the group.

BOOL CheckRadioButton(

HWND hDlg,	// handle to dialog box
int nIDFirstButton,	// identifier of first radio button in group
int nIDLastButton,	// identifier of last radio button in group
int nIDCheckButton	// identifier of radio button to select
);
Parameters

hDlg

Identifies the dialog box that contains the radio button.

nIDFirstButton

Specifies the identifier of the first radio button in the group.

nIDLastButton

Specifies the identifier of the last radio button in the group.

nIDCheckButton

Specifies the identifier of the radio button to select.

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.

Remarks

The CheckRadioButton function sends a BM_SETCHECK message to each of the radio buttons in the indicated group.

See Also

BM_SETCHECK, CheckDlgButton, IsDlgButtonChecked


ChildWindowFromPoint

The ChildWindowFromPoint function determines which, if any, of the child windows belonging to a parent window contains the specified point.

HWND ChildWindowFromPoint(

HWND hWndParent,	// handle to parent window
POINT Point	// structure with point coordinates
);
Parameters

hWndParent

Identifies the parent window.

Point

Specifies a POINT structure that defines the client coordinates of the point to be checked.

Return Values

If the function succeeds, the return value is the handle of the child window that contains the point, even if the child window is hidden or disabled. If the point lies outside the parent window, the return value is NULL. If the point is within the parent window but not within any child window, the return value is the handle to the parent window.

Remarks

Windows maintains an internal list, containing the handles of the child windows associated with a parent window. The order of the handles in the list depends on the Z order of the child windows. If more than one child window contains the specified point, Windows returns the handle of the first window in the list that contains the point.

See Also

ChildWindowFromPointEx, POINT, WindowFromPoint


ChildWindowFromPointEx [Now Supported on Windows NT]
ChildWindowFromPointEx

[Now Supported on Windows NT]

The ChildWindowFromPointEx function determines which, if any, of the child windows belonging to the specified parent window contains the specified point. The function can ignore invisible, disabled, and transparent child windows.

HWND ChildWindowFromPointEx(

HWND hwndParent,	// handle to parent window
POINT pt,	// structure with point coordinates
UINT uFlags	// skipping flags
);
Parameters

hwndParent

Identifies the parent window.

pt

Specifies a POINT structure that defines the client coordinates of the point to be checked.

uFlags

Specifies which child windows to skip. This parameter can be a combination of the following values:

Value	Meaning
CWP_ALL	Do not skip any child windows
CWP_SKIPINVISIBLE	Skip invisible child windows
CWP_SKIPDISABLED	Skip disabled child windows
CWP_SKIPTRANSPARENT	Skip transparent child windows
Return Values

If the function succeeds, the return value is the handle to the first child window that contains the point and meets the criteria specified by uFlags. If the point is within the parent window but not within any child window that meets the criteria, the return value is the handle to the parent window. If the point lies outside the parent window or if the function fails, the return value is NULL.

Remarks

Windows maintains an internal list that contains the handles of the child windows associated with a parent window. The order of the handles in the list depends on the Z order of the child windows. If more than one child window contains the specified point, Windows returns the handle of the first window in the list that contains the point and meets the criteria specified by uFlags.

See Also

ChildWindowFromPoint, POINT, WindowFromPoint


ChooseColor

The ChooseColor function creates a Color common dialog box that enables the user to select a color.

BOOL ChooseColor(

LPCHOOSECOLOR lpcc	// pointer to structure with initialization data
);
Parameters

lpcc

Pointer to a CHOOSECOLOR structure that contains information used to initialize the dialog box. When ChooseColor returns, this structure contains information about the user’s color selection.

Return Values

If the user clicks the OK button of the dialog box, the return value is nonzero. The rgbResult member of the CHOOSECOLOR structure contains the RGB color value of the color selected by the user.

If the user cancels or closes the Color dialog box or an error occurs, the return value is zero. To get extended error information, call the CommDlgExtendedError function, which can return one of the following values:

CDERR_FINDRESFAILURE	CDERR_MEMLOCKFAILURE
CDERR_INITIALIZATION	CDERR_NOHINSTANCE
CDERR_LOCKRESFAILURE	CDERR_NOHOOK
CDERR_LOADRESFAILURE	CDERR_NOTEMPLATE
CDERR_LOADSTRFAILURE	CDERR_STRUCTSIZE
CDERR_MEMALLOCFAILURE
Remarks

The Color dialog box does not support palettes. The color choices offered by the dialog box are limited to the system colors and dithered versions of those colors.

You can provide a CCHookProc hook procedure for a Color dialog box. The hook procedure can process messages sent to the dialog box. To enable a hook procedure, set the CC_ENABLEHOOK flag in the Flags member of the CHOOSECOLOR structure and specify the address of the hook procedure in the lpfnHook member.

See Also

CCHookProc, CHOOSECOLOR, CommDlgExtendedError


ChooseFont

The ChooseFont function creates a Font common dialog box that enables the user to choose attributes for a logical font. These attributes include a typeface name, style (bold, italic, or regular), point size, effects (underline, strikeout, and text color), and a script (or character set).

BOOL ChooseFont(

LPCHOOSEFONT lpcf	// pointer to structure with initialization data
);
Parameters

lpcf

Pointer to a CHOOSEFONT structure that contains information used to initialize the dialog box. When ChooseFont returns, this structure contains information about the user’s font selection.

Return Values

If the user clicks the OK button of the dialog box, the return value is nonzero. The members of the CHOOSEFONT structure indicate the user’s selections.

If the user cancels or closes the Font dialog box or an error occurs, the return value is zero. To get extended error information, call the CommDlgExtendedError function, which can return one of the following values:

CDERR_FINDRESFAILURE	CDERR_NOHINSTANCE
CDERR_INITIALIZATION	CDERR_NOHOOK
CDERR_LOCKRESFAILURE	CDERR_NOTEMPLATE
CDERR_LOADRESFAILURE	CDERR_STRUCTSIZE
CDERR_LOADSTRFAILURE	CFERR_MAXLESSTHANMIN
CDERR_MEMALLOCFAILURE	CFERR_NOFONTS
CDERR_MEMLOCKFAILURE
Remarks

You can provide a CFHookProc hook procedure for a Font dialog box. The hook procedure can process messages sent to the dialog box. To enable a hook procedure, set the CF_ENABLEHOOK flag in the Flags member of the CHOOSEFONT structure and specify the address of the hook procedure in the lpfnHook member.

The hook procedure can send the WM_CHOOSEFONT_GETLOGFONT, WM_CHOOSEFONT_SETFLAGS, and WM_CHOOSEFONT_SETLOGFONT messages to the dialog box to get and set the current values and flags of the dialog box.

See Also

CFHookProc, CHOOSEFONT, CommDlgExtendedError, LOGFONT, WM_CHOOSEFONT_GETLOGFONT, WM_CHOOSEFONT_SETFLAGS, WM_CHOOSEFONT_SETLOGFONT


Chord

The Chord function draws a chord (a region bounded by the intersection of an ellipse and a line segment, called a “secant”). The chord is outlined by using the current pen and filled by using the current brush.

BOOL Chord(

HDC hdc,	// handle to device context
int nLeftRect,	// x-coordinate of the upper-left corner of the bounding rectangle
int nTopRect,	// y-coordinate of the upper-left corner of the bounding rectangle
int nRightRect,	// x-coordinate of the lower-right corner of the bounding rectangle
int nBottomRect,	// y-coordinate of the lower-right corner of the bounding rectangle
int nXRadial1,	// x-coordinate of the first radial’s endpoint
int nYRadial1,	// y-coordinate of the first radial’s endpoint
int nXRadial2,	// x-coordinate of the second radial’s endpoint
int nYRadial2	// y-coordinate of the second radial’s endpoint
);
Parameters

hdc

Identifies the device context in which the chord appears.

nLeftRect

Specifies the x-coordinate of the upper-left corner of the bounding rectangle.

nTopRect

Specifies the y-coordinate of the upper-left corner of the bounding rectangle.

nRightRect

Specifies the x-coordinate of the lower-right corner of the bounding rectangle.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the bounding rectangle.

nXRadial1

Specifies the x-coordinate of the endpoint of the radial defining the beginning of the chord.

nYRadial1

Specifies the y-coordinate of the endpoint of the radial defining the beginning of the chord.

nXRadial2

Specifies the x-coordinate of the endpoint of the radial defining the end of the chord.

nYRadial2

Specifies the y-coordinate of the endpoint of the radial defining the end of the chord.

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.

Remarks

The curve of the chord is defined by an ellipse that fits the specified bounding rectangle. The curve begins at the point where the ellipse intersects the first radial and extends counterclockwise to the point where the ellipse intersects the second radial. (A radial is a line segment drawn from the center of the ellipse to a specified endpoint on the ellipse.) The chord is closed by drawing a line from the intersection of the first radial and the curve to the intersection of the second radial and the curve.

If the starting point and ending point of the curve are the same, a complete ellipse is drawn.

The current position is neither used nor updated by Chord.

Windows 95: The sum of the coordinates of the bounding rectangle cannot exceed 32,767. The sum of nLeftRect and nRightRect or nTopRect and nBottomRect parameters cannot exceed 32,767.

See Also

AngleArc, Arc, ArcTo, Pie


ClearCommBreak

The ClearCommBreak function restores character transmission for a specified communications device and places the transmission line in a nonbreak state.

BOOL ClearCommBreak(

HANDLE hFile	// handle to communications device
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

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.

Remarks

A communications device is placed in a break state by the SetCommBreak or EscapeCommFunction function. Character transmission is then suspended until the break state is cleared by calling ClearCommBreak.

See Also

ClearCommError, CreateFile, EscapeCommFunction, SetCommBreak


ClearCommError

The ClearCommError function retrieves information about a communications error and reports the current status of a communications device. The function is called when a communications error occurs, and it clears the device’s error flag to enable additional input and output (I/O) operations.

BOOL ClearCommError(

HANDLE hFile,	// handle to communications device
LPDWORD lpErrors,	// pointer to variable to receive error codes
LPCOMSTAT lpStat	// pointer to buffer for communications status
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

lpErrors

Points to a 32-bit variable to be filled with a mask indicating the type of error. This parameter can be one or more of the following error codes:

Value	Meaning
CE_BREAK	The hardware detected a break condition.
CE_DNS	Windows 95 only: A parallel device is not selected.
CE_FRAME	The hardware detected a framing error.
CE_IOE	An I/O error occurred during communications with the device.
CE_MODE	The requested mode is not supported, or the hFile parameter is invalid. If this value is specified, it is the only valid error.
CE_OOP	Windows 95 only: A parallel device signaled that it is out of paper.
CE_OVERRUN	A character-buffer overrun has occurred. The next character is lost.
CE_PTO	Windows 95 only: A time-out occurred on a parallel device.
CE_RXOVER	An input buffer overflow has occurred. There is either no room in the input buffer, or a character was received after the end-of-file (EOF) character.
CE_RXPARITY	The hardware detected a parity error.
CE_TXFULL	The application tried to transmit a character, but the output buffer was full.
lpStat

Points to a COMSTAT structure in which the device’s status information is returned. If lpStat is NULL, no status information is returned.

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.

Remarks

If a communications port has been set up with a TRUE value for the fAbortOnError member of the setup DCB structure, the communications software will terminate all read and write operations on the communications port when a communications error occurs. No new read or write operations will be accepted until the application acknowledges the communications error by calling the ClearCommError function.

The ClearCommError function fills the status buffer pointed to by the lpStat parameter with the current status of the communications device specified by the hFile parameter.

See Also

ClearCommBreak, COMSTAT, CreateFile, DCB


ClearEventLog

The ClearEventLog function clears the specified event log, and optionally saves the current copy of the logfile to a backup file.

BOOL ClearEventLog(

HANDLE hEventLog,	// handle to event log
LPCTSTR lpBackupFileName	// name of backup file
);
Parameters

hEventLog

Identifies the event log to be cleared. This handle is returned by the OpenEventLog function.

lpBackupFileName

Points to the null-terminated string specifying the name of a file in which a current copy of the event logfile will be placed. If this file already exists, the function fails.

The backup filename may contain a server name to save the backup file on a remote server.

If the lpBackupFileName parameter is NULL, the current event logfile is not backed up.

Return Values

If the function succeeds, the return value is nonzero. The specified event log has been backed up (if lpBackupFileName is not NULL) and then cleared.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The ClearEventLog function fails if the event log is empty.

After this function returns, any handles that reference the cleared event log cannot be used to read the log.

If the backup filename specifies a remote server, the event log handle must identify a log on the local computer. You cannot back up an event logfile from a remote server to a file on a remote server (even if the backup file and the original log are on the same server).

The ClearEventLog function is used to optionally back up an existing logfile of the module represented by hEventLog. The function backs up the logfile to another file, and then clears the existing logfile. The caller must have write permission for the path specified, and must also have permission to move the current logfile. If a file already exists with the same name as lpBackupFileName, ClearEventLog fails.

See Also

OpenEventLog


ClientToScreen

The ClientToScreen function converts the client coordinates of a specified point to screen coordinates.

BOOL ClientToScreen(

HWND hWnd,	// window handle for source coordinates
LPPOINT lpPoint	// pointer to structure containing screen coordinates
);
Parameters

hWnd

Identifies the window whose client area is used for the conversion.

lpPoint

Points to a POINT structure that contains the client coordinates to be converted. The new screen coordinates are copied into this structure if the function succeeds.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The ClientToScreen function replaces the client coordinates in the POINT structure with the screen coordinates. The screen coordinates are relative to the upper-left corner of the screen.

See Also

MapWindowPoints, POINT, ScreenToClient


ClipCursor

The ClipCursor function confines the cursor to a rectangular area on the screen. If a subsequent cursor position (set by the SetCursorPos function or the mouse) lies outside the rectangle, Windows automatically adjusts the position to keep the cursor inside the rectangular area.

BOOL ClipCursor(

CONST RECT *lpRect	// pointer to structure with rectangle
);
Parameters

lprc

Points to the RECT structure that contains the screen coordinates of the upper-left and lower-right corners of the confining rectangle. If this parameter is NULL, the cursor is free to move anywhere on the screen.

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.

Remarks

The cursor is a shared resource. If an application confines the cursor, it must release the cursor by using ClipCursor before relinquishing control to another application.

The calling process must have WINSTA_WRITEATTRIBUTES access to the window station.

See Also

GetClipCursor, GetCursorPos, RECT, SetCursorPos


CloseClipboard

The CloseClipboard function closes the clipboard.

BOOL CloseClipboard(VOID)

Parameters

This function has no parameters.

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.

Remarks

When the window has finished examining or changing the clipboard, close the clipboard by calling CloseClipboard. This enables other windows to access the clipboard.

Do not place an object on the clipboard after calling CloseClipboard.

See Also

GetOpenClipboardWindow, OpenClipboard


CloseDesktop

The CloseDesktop function closes an open handle to a desktop object. A desktop is a secure object contained within a window station object. A desktop has a logical display surface and contains windows, menus and hooks.

BOOL CloseDesktop(

HDESK hDesktop	// handle to desktop to close
);
Parameters

hDesktop

Identifies the desktop to be closed. This handle is returned by the CreateDesktop and OpenDesktop functions.

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.

Remarks

The CloseDesktop function will fail if any thread in the calling process is using the specified desktop handle or if the handle refers to the initial desktop of the calling process.

See Also

CreateDesktop, OpenDesktop


CloseEnhMetaFile

The CloseEnhMetaFile function closes an enhanced-metafile device context and returns a handle that identifies an enhanced-format metafile.

HENHMETAFILE CloseEnhMetaFile(

HDC hdc	// handle to an enhanced-metafile device context
);
Parameters

hdc

Identifies an enhanced-metafile device context.

Return Values

If the function succeeds, the return value is a handle to an enhanced metafile.

If the function fails, the return value is NULL.

Remarks

An application can use the enhanced-metafile handle returned by the CloseEnhMetaFile function to perform the following tasks:

•	Display a picture stored in an enhanced metafile

•	Create copies of the enhanced metafile

•	Enumerate, edit, or copy individual records in the enhanced metafile

•	Retrieve an optional description of the metafile contents from the enhanced-metafile header

•	Retrieve a copy of the enhanced-metafile header

•	Retrieve a binary copy of the enhanced metafile

•	Enumerate the colors in the optional palette

•	Convert an enhanced-format metafile into a Windows-format metafile

When the application no longer needs the enhanced metafile handle, it should release the handle by calling the DeleteEnhMetaFile function.

See Also

CopyEnhMetaFile, CreateEnhMetaFile, DeleteEnhMetaFile, EnumEnhMetaFile, GetEnhMetaFileBits, GetWinMetaFileBits, PlayEnhMetaFile


CloseEventLog

The CloseEventLog function closes the specified event log.

BOOL CloseEventLog(

HANDLE hEventLog	// handle to event log
);
Parameters

hEventLog

Identifies the event log to be closed. This handle is returned by the OpenEventLog 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.

See Also

OpenEventLog


CloseFigure

The CloseFigure function closes an open figure in a path.

BOOL CloseFigure(

HDC hdc	// handle to device context
);
Parameters

hdc

Identifies the device context in which the figure will be closed.

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.

Remarks

The CloseFigure function closes the figure by drawing a line from the current position to the first point of the figure (usually, the point specified by the most recent call to the MoveToEx function) and then connects the lines by using the line join style. If a figure is closed by using the LineTo function instead of CloseFigure, end caps are used to create the corner instead of a join.

The CloseFigure function should only be called if there is an open path bracket in the specified device context.

A figure in a path is open unless it is explicitly closed by using this function. (A figure can be open even if the current point and the starting point of the figure are the same.)

After a call to CloseFigure, adding a line or curve to the path starts a new figure.

See Also

BeginPath, EndPath, ExtCreatePen, LineTo, MoveToEx


CloseHandle

The CloseHandle function closes an open object handle.

BOOL CloseHandle(

HANDLE hObject	// handle to object to close
);
Parameters

hObject

Identifies an open object handle.

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.

Remarks

The CloseHandle function closes handles to the following objects:

•	Console input or output

•	Event file

•	File mapping

•	Mutex

•	Named pipe

•	Process

•	Semaphore

•	Thread

•	Token (Windows NT only)

CloseHandle invalidates the specified object handle, decrements the object’s handle count, and performs object retention checks. Once the last handle to an object is closed, the object is removed from the operating system.

This function does not close module objects.

Use CloseHandle to close handles returned by calls to the CreateFile function. Use FindClose to close handles returned by calls to the FindFirstFile function.

Closing an invalid handle raises an exception. This includes closing a handle twice, not checking the return value and closing an invalid handle, and using CloseHandle on a handle returned by FindFirstFile.

See Also

CreateFile, DeleteFile, FindClose, FindFirstFile


CloseMetaFile

The CloseMetaFile function closes a metafile device context and returns a handle that identifies a Windows-format metafile.

This function is provided for compatibility with earlier versions of Microsoft Windows. Win32-based applications should use the CloseEnhMetaFile function.

HMETAFILE CloseMetaFile(

HDC hdc	// handle to metafile device context
);
Parameters

hdc

Identifies a metafile device context used to create a Windows-format metafile.

Return Values

If the function succeeds, the return value is a handle to a Windows-format metafile.

If the function fails, the return value is NULL.

Remarks

A Windows-format metafile does not support the new curve, path, and transformation functions, such as PolyBezier, BeginPath, and SetWorldTransform. Applications that use these new functions and use metafiles to store pictures created by these functions should call the enhanced-format metafile functions.

To convert a Windows-format metafile into a new enhanced-format metafile, use the SetWinMetaFileBits function.

When an application no longer needs the Windows-format metafile handle, it should delete the handle by calling the DeleteMetaFile function.

See Also

BeginPath, CloseEnhMetaFile, CopyMetaFile, CreateMetaFile, DeleteMetaFile, EnumMetaFile, GetMetaFileBitsEx, PlayMetaFile, PolyBezier, SetWinMetaFileBits, SetWorldTransform


ClosePrinter

The ClosePrinter function closes the specified printer object.

BOOL ClosePrinter(

HANDLE hPrinter	// handle to printer object
);
Parameters

hPrinter

Handle to the printer object to be closed.

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.

Remarks

When the ClosePrinter function returns, the handle hPrinter is invalid, regardless of whether the function has succeeded or failed.

See Also

AddPrinter, OpenPrinter


CloseServiceHandle

The CloseServiceHandle function closes a handle to a service control manager database as returned by the OpenSCManager function, or it closes a handle to a service object as returned by either the OpenService or CreateService function.

BOOL CloseServiceHandle(

SC_HANDLE hSCObject	// handle to service or service control manager database
);
Parameters

hSCObject

Identifies the service control manager database or the service object to close.

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.

Errors

The following error code may be set by the service control manager. Other error codes may be set by registry functions that are called by the service control manager.

Value	Meaning
ERROR_INVALID_HANDLE	The specified handle is invalid.
Remarks

The CloseServiceHandle function does not destroy the service control manager object referred to by the handle. A service control manager object cannot be destroyed. A service object can be destroyed by calling the DeleteService function.

See Also

CreateService, DeleteService, OpenSCManager, OpenService


CloseWindow

The CloseWindow function minimizes (but does not destroy) the specified window.

BOOL CloseWindow(

HWND hWnd	// handle to window to minimize
);
Parameters

hWnd

Identifies the window to be minimized.

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.

Remarks

The window is minimized by reducing it to the size of an icon and moving the window to the icon area of the screen. Windows displays the window’s icon instead of the window and draws the window’s title below the icon.

To destroy a window, an application must use the DestroyWindow function.

See Also

ArrangeIconicWindows, DestroyWindow, IsIconic, OpenIcon


CloseWindowStation

The CloseWindowStation function closes an open window station handle.

BOOL CloseWindowStation(

HWINSTA hWinSta	// handle to window station to close
);
Parameters

hWinSta

Identifies the window station to be closed. This handle is returned by the CreateWindowStation and OpenWindowStation functions.

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.

Remarks

The CloseWindowStation function will fail if the handle being closed is for the window station assigned to the calling process.

See Also

SetProcessWindowStation


ColorMatchToTarget

The ColorMatchToTarget function enables or disables preview for the specified device context. When preview is enabled, colors in subsequent output to the specified device context are displayed as they would appear on the target device. This is useful for checking how well the target maps the specified colors in an image. To enable preview, image color matching must be enabled for both the target and the preview device context.

BOOL ColorMatchToTarget(

HDC hdc,
HDC hdcTarget,
DWORD uiAction
);
Parameters

hdc

Handle to the device context to use for preview, typically the display.

hdcTarget

Handle to the target device context, typically a printer.

uiAction

This parameter can have one of the following values:

Value	Meaning
CS_ENABLE	Enable preview; start matching colors through the target before displaying.
CS_DISABLE	Disable preview; stop matching colors through the target and restore the previous method for the preview device.
CS_DELETE_TRANSFORM	Disable preview and delete the color transformation used for previewing.
Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

If you use the ColorMatchToTarget function to enable preview, your next call to this function must be to disable preview; you must not nest calls to enable preview. While preview is enabled, any changes you make to the color space or gamut matching method are temporarily ignored, but take effect when preview is disabled.

This function creates a color transformation that translates colors for the target device first, then translates colors for the preview device. You need not delete the color transformation using CS_DELETE_TRANSFORM because the system deletes the transformation when either of the devices is removed from the system, or when the color space is deleted. However, if the transform is not going to be used again, an application can free up the space taken by it.


CombineRgn

The CombineRgn function combines two regions and stores the result in a third region. The two regions are combined according to the specified mode.

int CombineRgn(

HRGN hrgnDest,	// handle to destination region
HRGN hrgnSrc1,	// handle to source region
HRGN hrgnSrc2,	// handle to source region
int fnCombineMode	// region combining mode
);
Parameters

hrgnDest

Identifies a new region with dimensions defined by combining two other regions. (This region must exist before CombineRgn is called.)

hrgnSrc1

Identifies the first of two regions to be combined.

hrgnSrc2

Identifies the second of two regions to be combined.

fnCombineMode

Specifies a mode indicating how the two regions will be combined. This parameter can be one of the following values:

Value	Description
RGN_AND	Creates the intersection of the two combined regions.
RGN_COPY	Creates a copy of the region identified by hrgnSrc1.
RGN_DIFF	Combines the parts of hrgnSrc1 that are not part of hrgnSrc2.
RGN_OR	Creates the union of two combined regions.
RGN_XOR	Creates the union of two combined regions except for any overlapping areas.
Return Values

The return value specifies the type of the resulting region. It can be one of the following values:

Value	Meaning
NULLREGION	The region is empty.
SIMPLEREGION	The region is a single rectangle.
COMPLEXREGION	The region is more than a single rectangle.
ERROR	No region is created.
Remarks

The three regions need not be distinct. For example, the hrgnSrc1 parameter can equal the hrgnDest parameter.

See Also

CreateEllipticRgn, CreateEllipticRgnIndirect, CreatePolygonRgn, CreatePolyPolygonRgn, CreateRectRgn, CreateRectRgnIndirect, CreateRoundRectRgn


CombineTransform

The CombineTransform function concatenates two world-space to page-space transformations.

BOOL CombineTransform(

LPXFORM lpxformResult,	// pointer to combined transformation
CONST XFORM *lpxform1,	// pointer to first transformation
CONST XFORM *lpxform2	// pointer to second transformation
);
Parameters

lpxformResult

Points to an XFORM structure that receives the combined transformation.

lpxform1

Points to an XFORM structure that identifies the first transformation.

lpxform2

Points to an XFORM structure that identifies the second transformation.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Applying the combined transformation has the same effect as applying the first transformation and then applying the second transformation.

The three transformations need not be distinct. For example, lpxform1 can point to the same XFORM structure as lpxformResult.

See Also

GetWorldTransform, ModifyWorldTransform, SetWorldTransform, XFORM


CommandLineToArgvW

The CommandLineToArgvW function parses a wide-character Unicode command-line string. It returns a pointer to a set of wide-character Unicode argument strings and a count of arguments, similar to the standard C run-time argv and argc values. The function provides a way to obtain a Unicode set of argv and argc values from a Unicode command-line string.

LPWSTR *  CommandLineToArgvW(

LPCWSTR lpCmdLine,	// pointer to a command-line string
int *pNumArgs	// pointer to a variable that receives the argument count
);
Parameters

lpCmdLine

Pointer to a null-terminated Unicode command-line string. An application will usually directly pass on the value returned by a call to GetCommandLineW.

*pNumArgs

Pointer to an integer variable that the function sets to the count of arguments parsed.

Return Values

If the function succeeds, the return value is a non-NULL pointer to the constructed argument list, which is a set of Unicode wide-character argument strings.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

It is the caller’s responsibility to free the memory used by the argument list when it is no longer needed. To free the memory, use a single call to either the GlobalFree or LocalFree function.

See Also

GetCommandLine, GlobalFree, LocalFree


CommConfigDialog

The CommConfigDialog function displays a driver-supplied configuration dialog box.

BOOL CommConfigDialog(

LPTSTR lpszName,	// pointer to device name string
HWND hWnd,	// handle to window
LPCOMMCONFIG lpCC	// pointer to comm. configuration structure
);
Parameters

lpszName

Points to a null-terminated string specifying the name of the device for which a dialog box should be displayed.

hWnd

Identifies the window that owns the dialog box. This parameter can be any valid window handle, or it should be NULL if the dialog box is to have no owner.

lpCC

Points to a COMMCONFIG structure. This structure contains initial settings for the dialog box before the call, and changed values after the call.

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.

Remarks

The CommConfigDialog function requires a dynamic-link library (DLL) provided by the communications hardware vendor.

See Also

COMMCONFIG


CommDlgExtendedError

The CommDlgExtendedError function returns a common dialog box error code. This code indicates the most recent error to occur during the execution of one of the following common dialog box functions:

ChooseColor	GetOpenFileName
ChooseFont	GetSaveFileName
FindText	PrintDlg
ReplaceText	PageSetupDlg
DWORD CommDlgExtendedError(VOID)

Parameters

This function has no parameters.

Return Values

If the most recent call to a common dialog box function succeeded, the return value is undefined.

If the common dialog box function returned FALSE because the user closed or canceled the dialog box, the return value is zero. Otherwise, the return value is a nonzero error code. For more information, see the following Remarks section.

Remarks

The CommDlgExtendedError function can return general error codes for any of the common dialog box functions. In addition, there are error codes that are returned only for a specific common dialog box. The error codes returned by CommDlgExtendedError are defined in the CDERR.H file.

The following general error codes can be returned for any of the common dialog box functions:

Value	Meaning
CDERR_DIALOGFAILURE	The dialog box could not be created. The common dialog box function’s call to the DialogBox function failed. For example, this error occurs if the common dialog box call specifies an invalid window handle.
CDERR_FINDRESFAILURE	The common dialog box function failed to find a specified resource.
CDERR_INITIALIZATION	The common dialog box function failed during initialization. This error often occurs when sufficient memory is not available.
CDERR_LOADRESFAILURE	The common dialog box function failed to load a specified resource.
CDERR_LOADSTRFAILURE	The common dialog box function failed to load a specified string.
CDERR_LOCKRESFAILURE	The common dialog box function failed to lock a specified resource.
CDERR_MEMALLOCFAILURE	The common dialog box function was unable to allocate memory for internal structures.
CDERR_MEMLOCKFAILURE	The common dialog box function was unable to lock the memory associated with a handle.
CDERR_NOHINSTANCE	The ENABLETEMPLATE flag was set in the Flags member of the initialization structure for the corresponding common dialog box, but you failed to provide a corresponding instance handle.
CDERR_NOHOOK	The ENABLEHOOK flag was set in the Flags member of the initialization structure for the corresponding common dialog box, but you failed to provide a pointer to a corresponding hook procedure.
CDERR_NOTEMPLATE	The ENABLETEMPLATE flag was set in the Flags member of the initialization structure for the corresponding common dialog box, but you failed to provide a corresponding template.
CDERR_REGISTERMSGFAIL	The RegisterWindowMessage function returned an error code when it was called by the common dialog box function.
CDERR_STRUCTSIZE	The lStructSize member of the initialization structure for the corresponding common dialog box is invalid.
The following error codes can be returned for the PrintDlg function:

Value	Meaning
PDERR_CREATEICFAILURE	The PrintDlg function failed when it attempted to create an information context.
PDERR_DEFAULTDIFFERENT	You called the PrintDlg function with the DN_DEFAULTPRN flag specified in the wDefault member of the DEVNAMES structure, but the printer described by the other structure members did not match the current default printer. (This error occurs when you store the DEVNAMES structure and the user changes the default printer by using the Control Panel.)
	To use the printer described by the DEVNAMES structure, clear the DN_DEFAULTPRN flag and call PrintDlg again.  To use the default printer, replace the DEVNAMES structure (and the DEVMODE structure, if one exists) with NULL; and call PrintDlg again.
PDERR_DNDMMISMATCH	The data in the DEVMODE and DEVNAMES structures describes two different printers.
PDERR_GETDEVMODEFAIL	The printer driver failed to initialize a DEVMODE structure. (This error code applies only to printer drivers written for Windows versions 3.0 and later.)
PDERR_INITFAILURE	The PrintDlg function failed during initialization, and there is no more specific extended error code to describe the failure. This is the generic default error code for the function.
PDERR_LOADDRVFAILURE	The PrintDlg function failed to load the device driver for the specified printer.
PDERR_NODEFAULTPRN	A default printer does not exist.
PDERR_NODEVICES	No printer drivers were found.
PDERR_PARSEFAILURE	The PrintDlg function failed to parse the strings in the [devices] section of the WIN.INI file.
PDERR_PRINTERNOTFOUND	The [devices] section of the WIN.INI file did not contain an entry for the requested printer.
PDERR_RETDEFFAILURE	The PD_RETURNDEFAULT flag was specified in the Flags member of the PRINTDLG structure, but the hDevMode or hDevNames member was not NULL.
PDERR_SETUPFAILURE	The PrintDlg function failed to load the required resources.
The following error codes can be returned for the ChooseFont function:

Value	Meaning
CFERR_MAXLESSTHANMIN	The size specified in the nSizeMax member of the CHOOSEFONT structure is less than the size specified in the nSizeMin member.
CFERR_NOFONTS	No fonts exist.
The following error codes can be returned for the GetOpenFileName and GetSaveFileName functions:

Value	Meaning
FNERR_BUFFERTOOSMALL	The buffer pointed to by the lpstrFile member of the OPENFILENAME structure is too small for the filename specified by the user. The first two bytes of the lpstrFile buffer contain an integer value specifying the size, in bytes (ANSI version) or characters (Unicode version), required to receive the full name.
FNERR_INVALIDFILENAME	A filename is invalid.
FNERR_SUBCLASSFAILURE	An attempt to subclass a list box failed because sufficient memory was not available.
The following error code can be returned for the FindText and ReplaceText functions:

Value	Meaning
FRERR_BUFFERLENGTHZERO	A member of the FINDREPLACE structure points to an invalid buffer.
See Also

ChooseColor, CHOOSECOLOR, ChooseFont, CHOOSEFONT, DEVMODE, DEVNAMES, DialogBox, FINDREPLACE, FindText, GetOpenFileName, GetSaveFileName, OPENFILENAME, PageSetupDlg, PAGESETUPDLG, PrintDlg, PRINTDLG, RegisterWindowMessage, ReplaceText


CompareFileTime

The CompareFileTime function compares two 64-bit file times.

LONG CompareFileTime(

CONST FILETIME *lpFileTime1,	// pointer to first file time
CONST FILETIME *lpFileTime2	// pointer to second file time
);
Parameters

lpFileTime1

Points to a FILETIME structure that specifies the first 64-bit file time.

lpFileTime2

Points to a FILETIME structure that specifies the second 64-bit file time.

Return Values

If the function succeeds, the return value is one of the following values:

Value	Meaning
−1	First file time is less than second file time.
0	First file time is equal to second file time.
+1	First file time is greater than second file time.
See Also

GetFileTime, FILETIME


CompareString

The CompareString function compares two character strings, using the locale specified by the given identifier as the basis for the comparison.

int CompareString(

LCID Locale,	// locale identifier
DWORD dwCmpFlags,	// comparison-style options
LPCTSTR lpString1,	// pointer to first string
int cchCount1,	// size, in bytes or characters, of first string
LPCTSTR lpString2,	// pointer to second string
int cchCount2	// size, in bytes or characters, of second string
);
Parameters

Locale

Specifies the locale used for the comparison. This parameter can be one of the following predefined locale identifiers:

Value	Meaning
LOCALE_SYSTEM_DEFAULT	The system’s default locale.
LOCALE_USER_DEFAULT	The current user’s default locale.
This parameter can also be a locale identifier created by the MAKELCID macro.

dwCmpFlags

A set of flags that indicate how the function compares the two strings. By default, these flags are not set. This parameter can specify zero to get the default behavior, or it can be any combination of the following values:

Value	Meaning
NORM_IGNORECASE	Ignore case.
NORM_IGNOREKANATYPE	Do not differentiate between Hiragana and Katakana characters. Corresponding Hiragana and Katakana characters compare as equal.
NORM_IGNORENONSPACE	Ignore nonspacing characters.
NORM_IGNORESYMBOLS	Ignore symbols.
NORM_IGNOREWIDTH	Do not differentiate between a single-byte character and the same character as a double-byte character.
SORT_STRINGSORT	Treat punctuation the same as symbols.
lpString1

Points to the first string to be compared.

cchCount1

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the string pointed to by the lpString1 parameter. If this parameter is  − 1, the string is assumed to be null terminated and the length is calculated automatically.

lpString2

Points to the second string to be compared.

cchCount2

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the string pointed to by the lpString2 parameter. If this parameter is  − 1, the string is assumed to be null terminated and the length is calculated automatically.

Return Values

If the function succeeds, the return value is one of the following values:

Value	Meaning
1	The string pointed to by the lpString1 parameter is less in lexical value than the string pointed to by the lpString2 parameter.
2	The string pointed to by lpString1 is equal in lexical value to the string pointed to by lpString2.
3	The string pointed to by lpString1 is greater in lexical value than the string pointed to by lpString2.
If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

Remarks

Notice that if the return value is 2, the two strings are “equal” in the collation sense, though not necessarily identical.

To maintain the C run-time convention of comparing strings, the value 2 can be subtracted from a nonzero return value. The meaning of < 0, ==0 and > 0 is then consistent with the C run times.

If the two strings are of different lengths, they are compared up to the length of the shortest one. If they are equal to that point, then the return value will indicate that the longer string is greater. For more information about locale identifiers, see Locale Identifiers.

Typically, strings are compared using what is called a “word sort” technique. In a word sort, all punctuation marks and other nonalphanumeric characters, except for the hyphen and the apostrophe, come before any alphanumeric character. The hyphen and the apostrophe are treated differently than the other nonalphanumeric symbols, in order to ensure that words such as “coop” and “co-op” stay together within a sorted list.

If the SORT_STRINGSORT flag is specified, strings are compared using what is called a “string sort” technique. In a string sort, the hyphen and apostrophe are treated just like any other nonalphanumeric symbols: they come before the alphanumeric symbols.

The following table shows a list of words sorted both ways:

Word Sort	String Sort		Word Sort	String Sort
billet	bill’s		t-ant	t-ant
bills	billet		tanya	t-aria
bill’s	bills		t-aria	tanya
cannot	can’t		sued	sue’s
cant	cannot		sues	sued
can’t	cant		sue’s	sues
con	co-op		went	we’re
coop	con		were	went
co-op	coop		we’re	were
The lstrcmp and lstrcmpi functions use a word sort. The CompareString and LCMapString functions default to using a word sort, but use a string sort if their caller sets the SORT_STRINGSORT flag.

The CompareString function is optimized to run at the highest speed when dwCmpFlags is set to 0 or NORM_IGNORECASE, and cchCount1 and cchCount2 have the value -1.

The CompareString function ignores Arabic Kashidas during the comparison. Thus, if two strings are identical save for the presence of Kashidas, CompareString returns a value of 2; the strings are considered "equal" in the collation sense, though they are not necessarily identical.

See Also

FoldString, GetSystemDefaultLCID, GetUserDefaultLCID, LCMapString, lstrcmp, lstrcmpi, MAKELCID


ConfigurePort

The ConfigurePort function displays the port-configuration dialog box for a port on the specified server.

BOOL ConfigurePort(

LPTSTR pName,	// pointer to server name
HWND hWnd,	// handle to parent window of the dialog box
LPTSTR pPortName	// pointer to port name
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server on which the specified port exists. If this parameter is NULL, the port is local.

hWnd

Identifies the parent window of the port-configuration dialog box.

pPortName

Points to a null-terminated string that specifies the name of the port to be configured.

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.

Remarks

Before calling the ConfigurePort function, an application should call the EnumPorts function to determine valid port names.

See Also

EnumPorts


ConnectNamedPipe

The ConnectNamedPipe function enables a named pipe server process to wait for a client process to connect to an instance of a named pipe. A client process connects by calling either the CreateFile or CallNamedPipe function.

BOOL ConnectNamedPipe(

HANDLE hNamedPipe,	// handle to named pipe to connect
LPOVERLAPPED lpOverlapped	// pointer to overlapped structure
);
Parameters

hNamedPipe

Identifies the server end of a named pipe instance. This handle is returned by the CreateNamedPipe function.

lpOverlapped

Points to an OVERLAPPED structure.

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.

Remarks

A named pipe server process can use ConnectNamedPipe with a newly created pipe instance. It can also be used with an instance that was previously connected to another client process; in this case, the server process must first call the DisconnectNamedPipe function to disconnect the handle from the previous client before the handle can be reconnected to a new client. Otherwise, ConnectNamedPipe returns FALSE, and GetLastError returns ERROR_NO_DATA if the previous client has closed its handle or ERROR_PIPE_CONNECTED if it has not closed its handle.

The behavior of ConnectNamedPipe depends on two conditions: whether the pipe handle’s wait mode is set to blocking or nonblocking and whether the function is set to execute synchronously or in overlapped mode. A server initially specifies a pipe handle’s wait mode in the CreateNamedPipe function, and it can be changed by using the SetNamedPipeHandleState function.

If hNamedPipe was opened with FILE_FLAG_OVERLAPPED, the lpOverlapped parameter must not be NULL. It must point to a valid OVERLAPPED structure. If hNamedPipe was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function can incorrectly report that the connect operation is complete.

If hNamedPipe was created with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the OVERLAPPED structure pointed to by lpOverlapped must contain a handle to a manual-reset event object (which the server can create by using the CreateEvent function).

If hNamedPipe was not opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function does not return until a client is connected or an error occurs. Successful synchronous operations result in the function returning TRUE if a client connects after the function is called. If a client connects before the function is called, the function returns FALSE and GetLastError returns ERROR_PIPE_CONNECTED. This can happen if a client connects in the interval between the call to CreateNamedPipe and the call to ConnectNamedPipe. In this situation, there is a good connection between client and server, even though the function returns FALSE.

If hNamedPipe was not opened with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the operation executes asynchronously. The function returns immediately with a return value of FALSE. If a client process connects before the function is called, GetLastError returns ERROR_PIPE_CONNECTED. Otherwise, GetLastError returns ERROR_IO_PENDING, which indicates that the operation is executing in the background. When this happens, the event object in the OVERLAPPED structure is set to the nonsignaled state before ConnectNamedPipe returns, and it is set to the signaled state when a client connects to this instance of the pipe.

The server process can use any of the wait functions  or SleepEx — to determine when the state of the event object is signaled, and it can then use the GetOverlappedResult function to determine the results of the ConnectNamedPipe operation.

If the specified pipe handle is in nonblocking mode, ConnectNamedPipe always returns immediately. In nonblocking mode, ConnectNamedPipe returns TRUE the first time it is called for a pipe instance that is disconnected from a previous client. This indicates that the pipe is now available to be connected to a new client process. In all other situations when the pipe handle is in nonblocking mode, ConnectNamedPipe returns FALSE. In these situations, GetLastError returns ERROR_PIPE_LISTENING if no client is connected, ERROR_PIPE_CONNECTED if a client is connected, and ERROR_NO_DATA if a previous client has closed its pipe handle but the server has not disconnected. Note that a good connection between client and server exists only after the ERROR_PIPE_CONNECTED error is received.

Note that nonblocking mode is supported for compatibility with Microsoft LAN Manager version 2.0, and it should not be used to achieve asynchronous input and output (I/O) with named pipes.

See Also

CallNamedPipe, CreateEvent, CreateFile, CreateNamedPipe, DisconnectNamedPipe, GetOverlappedResult, SetNamedPipeHandleState, SleepEx, OVERLAPPED


ConnectToPrinterDlg

The ConnectToPrinterDlg function displays a dialog box that lets users browse and connect to printers on a network. If the user selects a printer, the function attempts to create a connection to it; if a suitable driver is not installed on the server, the user is given the option of creating a printer locally.

HANDLE ConnectToPrinterDlg (

HWND hwnd,	// handle to parent window of dialog box
DWORD Flags	// reserved for future use, must be zero
);
Parameters

hwnd

Specifies the parent window of the dialog box.

Flags

This parameter is reserved for future use. Set it to zero.

Return Values

If the function succeeds and the user selects a printer, the return value is a handle to the selected printer.

If the function fails, or the user cancels the dialog box without selecting a printer, the return value is NULL.

Remarks

The ConnectToPrinterDlg function attempts to create a connection to the selected printer. However, if the server on which the printer resides does not have a suitable driver installed, the function offers the user the option of creating a printer locally. A calling application can determine whether the function has created a printer locally by calling GetPrinter with a PRINTER_INFO_2 structure, then examining that structure’s Attributes member.

An application should call DeletePrinter to delete a local printer. An application should call DeletePrinterConnection to delete a connection to a printer.

See Also

AddPrinterConnection, ClosePrinter, DeletePrinter, DeletePrinterConnection, GetPrinter, PRINTER_INFO_2


ContinueDebugEvent

The ContinueDebugEvent function enables a debugger to continue a thread that previously reported a debugging event.

BOOL ContinueDebugEvent(

DWORD dwProcessId,	// process to continue
DWORD dwThreadId,	// thread to continue
DWORD dwContinueStatus	// continuation status
);
Parameters

dwProcessId

Identifies the process to continue.

dwThreadId

Identifies the thread to continue. The combination of process identifier and thread identifier must identify a thread that has previously reported a debugging event.

dwContinueStatus

Specifies how to continue the thread that reported the debugging event.

If the DBG_CONTINUE flag is specified for this parameter and the thread specified by the dwThreadId parameter previously reported an EXCEPTION_DEBUG_EVENT debugging event, the function stops all exception processing and continues the thread. For any other debugging event, this flag simply continues the thread.

If the DBG_EXCEPTION_NOT_HANDLED flag is specified for this parameter and the thread specified by dwThreadId previously reported an EXCEPTION_DEBUG_EVENT debugging event, the function continues exception processing. If this is a first-chance exception event, the search and dispatch logic of the structured exception handler is used; otherwise, the process is terminated. For any other debugging event, this flag simply continues the thread.

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.

Remarks

Only the thread that created dwProcessId with the CreateProcess function can call ContinueDebugEvent.

After the ContinueDebugEvent function succeeds, the specified thread continues. Depending on the debugging event previously reported by the thread, different actions occur. If the continued thread previously reported an EXIT_THREAD_DEBUG_EVENT debugging event, ContinueDebugEvent closes the handle the debugger has to the thread. If the continued thread previously reported an EXIT_PROCESS_DEBUG_EVENT debugging event, ContinueDebugEvent closes the handles the debugger has to the process and to the thread.

See Also

CreateProcess


ControlService

The ControlService function sends a control code to a Win32 service.

BOOL ControlService(

SC_HANDLE hService,	// handle to service
DWORD dwControl,	// control code
LPSERVICE_STATUS lpServiceStatus	// pointer to service status structure
);
Parameters

hService

Identifies the service. This handle is returned by the OpenService or CreateService function. The access required for this handle depends on the dwControl code requested.

dwControl

Specifies the requested control code. This value can be one of the standard control codes in the table, or it can be a user-defined control code in the range of 128 to 255, inclusive. For user-defined control codes, the hService handle must have SERVICE_USER_DEFINED_CONTROL access, and the service defines the action associated with the control code.

Value	Meaning
SERVICE_CONTROL_STOP
	Requests the service to stop. The hService handle must have SERVICE_STOP access.
SERVICE_CONTROL_PAUSE
	Requests the service to pause. The hService handle must have SERVICE_PAUSE_CONTINUE access.
SERVICE_CONTROL_CONTINUE
	Requests the paused service to resume. The hService handle must have SERVICE_PAUSE_CONTINUE access.
SERVICE_CONTROL_INTERROGATE
	Requests the service to update immediately its current status information to the service control manager. The hService handle must have SERVICE_INTERROGATE access.
SERVICE_CONTROL_SHUTDOWN
	The ControlService function fails if this control code is specified.
lpServiceStatus

Points to a SERVICE_STATUS structure where the latest status information of the service is returned. The information returned reflects the most recent status reported by the service to the service control manager.

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.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED
	The specified handle was not opened with the necessary access.
ERROR_DEPENDENT_SERVICES_RUNNING
	The service cannot be stopped because other running services are dependent on it.
ERROR_INVALID_SERVICE_CONTROL
	The requested control code is not valid, or it is unacceptable to the service.
ERROR_SERVICE_CANNOT_ACCEPT_CTRL
	The requested control code cannot be sent to the service because the state of the service is SERVICE_STOPPED, SERVICE_START_PENDING, or SERVICE_STOP_PENDING.
ERROR_SERVICE_NOT_ACTIVE
	The service has not been started.
ERROR_SERVICE_REQUEST_TIMEOUT
	The service did not respond to the start request in a timely fashion.
Remarks

The ControlService function asks the service control manager to send the requested control code to the service. The service control manager sends the code if the service accepts the control and if the service is in a controllable state. The QueryServiceStatus or ControlService function returns a SERVICE_STATUS structure whose dwCurrentState and dwControlsAccepted members indicate the current state and controls accepted by a running Win32 service.

All running services accept the SERVICE_CONTROL_INTERROGATE control code by default. Each service specifies the other control codes that it accepts when it calls the SetServiceStatus function to report its status.

The following table shows the action of the service control manager in each of the possible service states:

Service state	Stop	Other controls
STOPPED	(c)	(c)
STOP_PENDING	(b)	(b)
START_PENDING	(a)	(b)
RUNNING	(a)	(a)
CONTINUE_PENDING	(a)	(a)
PAUSE_PENDING	(a)	(a)
PAUSED	(a)	(a)
(a) If the service accepts this control code, send the request to the service; otherwise, ControlService returns FALSE and GetLastError returns ERROR_INVALID_SERVICE_CONTROL.
(b) The service is not in a controllable state, so ControlService returns FALSE and GetLastError returns ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
(c) The service is not in a controllable state, so ControlService returns FALSE and GetLastError returns ERROR_SERVICE_NOT_ACTIVE.
See Also

CreateService, OpenService, QueryServiceStatus, SetServiceStatus, SERVICE_STATUS


ConvertDefaultLocale

The ConvertDefaultLocale function converts a special default locale value to an actual locale identifier.

LCID ConvertDefaultLocale(

LCID Locale	// special default locale value to be converted
);
Parameters

Locale

A special default locale value that the function converts to an actual locale identifier.

The following list shows the special default locale values:

Value	Description
LOCALE_SYSTEM_DEFAULT	The system’s default locale.
LOCALE_USER_DEFAULT	The current user’s default locale.
zero	The language-neutral default locale. This is equivalent to the locale identifier created by calling the MAKELCID macro with a language identifier consisting of the LANG_NEUTRAL and SUBLANG_NEUTRAL values.
Any sublanguage neutral default locale	A locale identifier constructed by calling MAKELCID with a language identifier consisting of a primary language value, such as LANG_ENGLISH, and the SUBLANG_NEUTRAL value.
Return Values

If the function succeeds, the return value is the appropriate actual locale identifier.

If the function fails, the return value is the Locale parameter. The function fails when Locale is not one of the special default locale values listed above.

Remarks

A call to ConvertDefaultLocale(LOCALE_SYSTEM_DEFAULT) is equivalent to a call to GetSystemDefaultLCID. A call to ConvertDefaultLocale(LOCALE_USER_DEFAULT) is equivalent to a call to GetUserDefaultLCID.

For more information about locale identifiers, see Locales and Language Identifiers.

See Also

GetSystemDefaultLCID, GetUserDefaultLCID


ConvertThreadToFiber

The ConvertTheadToFiber function converts the current thread into a fiber. You must convert a thread into a fiber before you can schedule other fibers.

LPVOID ConvertThreadToFiber(

LPVOID lpParameter	// fiber data for new fiber
);
Parameters

lpParameter

Specifies a single variable that is passed to the fiber. The fiber can retrieve this value by using the GetFiberData function.

Return Values

If the function succeeds, the return value is the address of the fiber.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Only fibers can execute other fibers. If a thread needs to execute a fiber, it must call ConvertThreadToFiber to create an area in which to save fiber state information. The thread is now the current fiber. The state information for this fiber includes the fiber data specified by lpParameter.

See Also

GetFiberData


CopyAcceleratorTable

The CopyAcceleratorTable function copies the specified accelerator table. This function is used to obtain the accelerator-table data that corresponds to an accelerator-table handle, or to determine the size of the accelerator-table data.

int CopyAcceleratorTable(

HACCEL hAccelSrc,	// handle to accelerator table to copy
LPACCEL lpAccelDst,	// pointer to structure receiving copy
int cAccelEntries	// number of entries in table being copied
);
Parameters

hAccelSrc

Identifies the accelerator table to copy.

lpAccelDst

Points to an array of ACCEL structures where the accelerator-table information is to be copied.

cAccelEntries

Specifies the number of ACCEL structures to copy to the buffer pointed to by the lpAccelDst parameter.

Return Values

If lpAccelDst is NULL, the return value specifies the number of accelerator-table entries in the original table. Otherwise, it specifies the number of accelerator-table entries that were copied.

See Also

ACCEL, CreateAcceleratorTable, DestroyAcceleratorTable, LoadAccelerators, TranslateAccelerator


CopyCursor

The CopyCursor function copies a cursor.

HCURSOR CopyCursor(

HCURSOR pcur	// handle to cursor to copy
);
Parameters

pcur

Identifies the cursor to be copied.

Return Values

If the function succeeds, the return value is the handle to the duplicate cursor.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

CopyCursor enables an application or dynamic-link library (DLL) to obtain the handle to a cursor shape owned by another module. Then if the other module is freed, the application is still able to use the cursor shape.

See Also

CopyIcon, GetCursor, SetCursor, ShowCursor


CopyEnhMetaFile

The CopyEnhMetaFile function copies the contents of an enhanced-format metafile to a specified file.

HENHMETAFILE CopyEnhMetaFile(

HENHMETAFILE hemfSrc,	// handle to an enhanced metafile
LPCTSTR lpszFile	// pointer to a filename string
);
Parameters

hemfSrc

Identifies the source-enhanced metafile.

lpszFile

Points to the name of the destination file. If this parameter is NULL, the source metafile is copied to memory.

Return Values

If the function succeeds, the return value is a handle to the copy of the enhanced metafile.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Where text arguments must use Unicode characters, use the CopyEnhMetaFile function as a wide-character function. Where text arguments must use characters from the Windows 3.x character set, use this function as an ANSI function.

Applications can use metafiles stored in memory for temporary operations.

When the application no longer needs the enhanced-metafile handle, it should delete the handle by calling the DeleteEnhMetaFile function.

See Also

DeleteEnhMetaFile


CopyFile

The CopyFile function copies an existing file to a new file.

BOOL CopyFile(

LPCTSTR lpExistingFileName,	// pointer to name of an existing file
LPCTSTR lpNewFileName,	// pointer to filename to copy to
BOOL bFailIfExists	// flag for operation if file exists
);
Parameters

lpExistingFileName

Points to a null-terminated string that specifies the name of an existing file.

lpNewFileName

Points to a null-terminated string that specifies the name of the new file.

bFailIfExists

Specifies how this operation is to proceed if a file of the same name as that specified by lpNewFileName already exists. If this parameter is TRUE and the new file already exists, the function fails. If this parameter is FALSE and the new file already exists, the function overwrites the existing file and succeeds.

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.

Remarks

Security attributes for the existing file are not copied to the new file.

File attributes (FILE_ATTRIBUTE_*) for the existing file are copied to the new file. For example, if an existing file has the FILE_ATTRIBUTE_READONLY file attribute, a copy created through a call to CopyFile will also have the FILE_ATTRIBUTE_READONLY file attribute. For further information on file attributes, see CreateFile.

See Also

CreateFile, MoveFile


CopyFileEx [New - Windows NT]
CopyFileEx

[New - Windows NT]

The CopyFileEx function copies an existing file to a new file. This function preserves extended attributes, OLE structured storage, NTFS alternate data streams, and file attributes. Security attributes for the existing file are not copied to the new file.

BOOL CopyFileEx(

LPCWSTR lpExistingFileName,	// pointer to name of an existing file
LPCWSTR lpNewFileName,	// pointer to filename to copy to
LPPROGRESS_ROUTINE lpProgressRoutine,	// pointer to the callback function
LPVOID lpData,	// to be passed to the callback function
LPBOOL pbCancel,	// flag that can be used to cancel the operation
DWORD dwCopyFlags	// flags that specify how the file is copied
);
Parameters

lpExistingFileName

Points to a null-terminated string that specifies the name of an existing file.

lpNewFileName

Points to a null-terminated string that specifies the name of the new file.

lpProgressRoutine

Specifies the address of a callback function of type LPPROGRESS_ROUTINE that is called each time another portion of the file has been copied. This parameter can be NULL. For more information on the progress callback function, see CopyProgressRoutine.

lpData

Specifies an argument to be passed to the callback function. This parameter can be NULL.

pbCancel

Points to a Boolean variable that can be used to cancel the operation. If this flag is set to TRUE during the copy operation, the operation is canceled.

dwCopyFlags

Specifies how the file is to be copied. This parameter can be a combination of the following values:

Value	Meaning
COPY_FILE_FAIL_IF_EXISTS	The copy operation fails immediately if the target file already exists.
COPY_FILE_RESTARTABLE	Progress of the copy is tracked in the target file in case the copy fails. The failed copy can be restarted at a later time by specifying the same values for lpExistingFileName and lpNewFileName as those used in the call that failed.
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.

Remarks

For information on file attributes, see CreateFile.

See Also

CreateFile, CopyFile, CopyProgressRoutine, MoveFile


CopyIcon

The CopyIcon function copies the specified icon from another module to the current module.

HICON CopyIcon(

HICON hIcon	// handle to icon to copy
);
Parameters

hIcon

Identifies the icon to be copied.

Return Values

If the function succeeds, the return value is the handle to the duplicate icon.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The CopyIcon function enables an application or dynamic-link library (DLL) to get its own handle to an icon owned by another module. If the other module is freed, the application icon will still be able to use the icon.

See Also

CopyCursor, DrawIcon, DrawIconEx


CopyImage

The CopyImage function creates a new image (icon, cursor, or bitmap) and copies the attributes of the specified image to the new one. If necessary, the function stretches the bits to fit the desired size of the new image.

HANDLE CopyImage(

HANDLE hImage,	// handle to the image to copy
UINT uType,	// type of image to copy
int cxDesired,	// desired width of new image
int cyDesired,	// desired height of new image
UINT fuFlags	// copy flags
);
Parameters

hinst

Identifies an instance of the module that contains the image to be copied.

uType

Specifies the type of image to be copied. This parameter can be one of the following values:

Value	Meaning
IMAGE_BITMAP	Copies a bitmap.
IMAGE_CURSOR	Copies a cursor.
IMAGE_ICON	Copies an icon.
cxDesired

Specifies the desired width, in pixels, of the image.

cyDesired

Specifies the desired height, in pixels, of the image.

fuFlags

Specifies a combination of the following values:

Value	Meaning
LR_COPYDELETEORG	Deletes the original image after creating the copy.
LR_COPYRETURNORG	Creates an exact copy of the image, ignoring the cxDesired and cyDesired parameters.
LR_MONOCHROME	Creates a new monochrome image.
LR_COPYFROMRESOURCE	Tries to reload an icon or cursor resource from the original resource file rather than simply copying the current image. This is useful for creating a different-sized copy when the resource file contains multiple sizes of the resource. Without this flag, CopyImage stretches the original image to the new size. If this flag is set, CopyImage uses the size in the resource file closest to the desired size. This will succeed only if hImage was loaded by LoadIcon or LoadCursor, or by LoadImage with the LR_SHARED flag.
Return Values

If the function succeeds, the return value is the handle to the newly created image.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

LoadImage


CopyLZFile

The CopyLZFile function is obsolete. It is provided only for compatibility with 16-bit versions of Windows. For Win32-based applications, use the LZCopy function.


CopyMemory

The CopyMemory function copies a block of memory from one location to another.

VOID CopyMemory (

PVOID Destination,	// address of copy destination
CONST VOID *Source,	// address of block to copy
DWORD Length	// size, in bytes, of block to copy
);
Parameters

Destination

Points to the starting address of the copied block’s destination.

Source

Points to the starting address of the block of memory to copy.

Length

Specifies the size, in bytes, of the block of memory to copy.

Return Values

This function has no return value.

Remarks

If the source and destination blocks overlap, the results are undefined. For overlapped blocks, use the MoveMemory function.

See Also

FillMemory, MoveMemory, ZeroMemory


CopyMetaFile

The CopyMetaFile function copies the content of a Windows-format metafile to the specified file.

This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the CopyEnhMetaFile function.

HMETAFILE CopyMetaFile(

HMETAFILE hmfSrc,	// handle to a Windows-format metafile
LPCTSTR lpszFile	// pointer to a filename string
);
Parameters

hmfSrc

Identifies the source Windows-format metafile.

lpszFile

Points to the name of the destination file. If this parameter is NULL, the source metafile is copied to memory.

Return Values

If the function succeeds, the return value is a handle to the copy of the Windows-format metafile.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The CopyMetaFile function supports only applications designed for Windows version 3.x. It does not record or play back the new graphics device interface functions, such as PolyBezier.

Where text arguments must use Unicode characters, use this function as a wide-character function. Where text arguments must use characters from the Windows 3.x character set, use this function as an ANSI function.

When the application no longer needs the Windows-format metafile handle, it should delete the handle by calling the DeleteMetaFile function.

See Also

DeleteMetaFile


CopyProgressRoutine [New - Windows NT]
CopyProgressRoutine

[New - Windows NT]

The CopyProgressRoutine function is called when a portion of a copy operation started by CopyFileEx is completed. This function is an application-defined callback routine.

DWORD WINAPI CopyProgressRoutine(

LARGE_INTEGER TotalFileSize,	// total file size, in bytes
LARGE_INTEGER TotalBytesTransferred,	// total number of bytes transferred
LARGE_INTEGER StreamSize,	// total number of bytes for this stream
LARGE_INTEGER StreamBytesTransferred,	// total number of bytes transferred for this stream
DWORD dwStreamNumber,	// the current stream
DWORD dwCallbackReason,	// reason for callback
HANDLE hSourceFile,	// handle to the source file
HANDLE hDestinationFile,	// handle to the destination file
LPVOID lpData	// passed by CopyFileEx
);
Parameters

TotalFileSize

The total size of the file, in bytes.

TotalBytesTransferred

The total number of bytes transferred from the source file to the destination file since the copy operation began.

StreamSize

The total size of the current file stream, in bytes.

StreamBytesTransferred

The total number of bytes in the current stream that have been transferred from the source file to the destination file since the copy operation began.

dwStreamNumber

Identifies the current stream. The stream number is 1 the first time CopyProgressRoutine is called.

dwCallbackReason

Specifies the reason that CopyProgressRoutine was called. This parameter can be one of the following values:

Value	Meaning
CALLBACK_CHUNK_FINISHED	Another part of the data file was copied.
CALLBACK_STREAM_SWITCH	Another stream was created and is about to be copied. This is the callback reason given when the callback routine is first invoked.
hSourceFile

Identifies the source file.

hDestinationFile

Identifies the destination file

lpData

The argument passed to CopyProgressRoutine by the CopyFileEx function.

Return values

The CopyProgressRoutine function should return one of the following values:

Value	Meaning
PROGRESS_CONTINUE	Continue the copy operation.
PROGRESS_CANCEL	Cancel the copy operation and delete the destination file.
PROGRESS_STOP	Stop the copy operation. It can be restarted at a later time.
PROGRESS_QUIET	Continue the copy operation, but stop invoking CopyProgressRoutine to report progress.
Remarks

An application can use this information to display a progress bar that shows the total number of bytes copied as a percent of the total file size.

See Also

CopyFileEx


CopyRect

The CopyRect function copies the coordinates of one rectangle to another.

BOOL CopyRect(

LPRECT lprcDst,	// pointer to structure for destination rectangle
CONST RECT *lprcSrc	// pointer to structure with source rectangle
);
Parameters

lprcDst

Points to the RECT structure that will receive the logical coordinates of the source rectangle.

lprcSrc

Points to the RECT structure whose coordinates are to be copied.

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.

See Also

RECT, SetRect, SetRectEmpty


CopySid

The CopySid function copies a security identifier (SID) to a buffer.

BOOL CopySid(

DWORD nDestinationSidLength,	// size of buffer for copied SID
PSID pDestinationSid,	// pointer to buffer for copied SID
PSID pSourceSid	// pointer to source SID
);
Parameters

nDestinationSidLength

Specifies the length, in bytes, of the buffer receiving the copy of the SID.

pDestinationSid

Points to a buffer receiving a copy of the source SID structure.

pSourceSid

Points to a SID structure the function copies to the buffer pointed to by the pDestinationSid parameter.

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.

Remarks

An application can use the CopySid function to make a copy of a SID in an access token (in a TOKEN_GROUPS structure, for instance) to use in an access-control entry.

See Also

AllocateAndInitializeSid, EqualSid, GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthority, GetSidSubAuthorityCount, InitializeSid, IsValidSid, SID


CountClipboardFormats

The CountClipboardFormats function retrieves the number of different data formats currently on the clipboard.

int CountClipboardFormats(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the number of different data formats currently on the clipboard.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

EnumClipboardFormats, RegisterClipboardFormat


CPlApplet

The CPlApplet function is a library-defined callback function that serves as the entry point for a Control Panel application.

LONG APIENTRY CPlApplet(

HWND hwndCPl,	// handle to Control Panel window
UINT uMsg,	// message
LONG lParam1,	// first message parameter
LONG lParam2	// second message parameter
);
Parameters

hwndCPl

Identifies the main window of the controlling application.

uMsg

Specifies the message being sent to the Control Panel application.

lParam1

Specifies additional message-specific information.

lParam2

Specifies additional message-specific information.

Return Values

The return value depends on the message. For more information, see the descriptions of the individual Control Panel messages.

Remarks

Use the hwndCPl parameter for dialog boxes or other windows that require a handle to a parent window.


CreateAcceleratorTable

The CreateAcceleratorTable function creates an accelerator table.

HACCEL CreateAcceleratorTable(

LPACCEL lpaccl,	// pointer to structure array with accelerator data
int cEntries	// number of structures in the array
);
Parameters

lpaccl

Points to an array of ACCEL structures that describes the accelerator table.

cEntries

Specifies the number of ACCEL structures in the array.

Return Values

If the function succeeds, the return value is the handle to the created accelerator table; otherwise, it is NULL.

Remarks

Before an application closes, it must use the DestroyAcceleratorTable function to destroy each accelerator table that it created by using the CreateAcceleratorTable function.

See Also

ACCEL, CopyAcceleratorTable, DestroyAcceleratorTable, LoadAccelerators, TranslateAccelerator


CreateBitmap

The CreateBitmap function creates a bitmap with the specified width, height, and color format (color planes and bits per pixel).

HBITMAP CreateBitmap(

int nWidth,	// bitmap width, in pixels
int nHeight,	// bitmap height, in pixels
UINT cPlanes,	// number of color planes used by device
UINT cBitsPerPel,	// number of bits required to identify a color
CONST VOID *lpvBits	// pointer to array containing color data
);
Parameters

nWidth

Specifies the bitmap width, in pixels.

nHeight

Specifies the bitmap height, in pixels.

cPlanes

Specifies the number of color planes used by the device.

cBitsPerPel

Specifies the number of bits required to identify the color of a single pixel.

lpvBits

Points to an array of color data used to set the colors in a rectangle of pixels. Each scan line in the rectangle must be word aligned (scan lines that are not word aligned must be padded with zeros). If this parameter is NULL, the new bitmap is undefined.

Return Values

If the function succeeds, the return value is a handle to a bitmap.

If the function fails, the return value is NULL.

Remarks

After a bitmap is created, it can be selected into a device context by calling the SelectObject function.

While the CreateBitmap function can be used to create color bitmaps, for performance reasons applications should use CreateBitmap to create monochrome bitmaps and CreateCompatibleBitmap to create color bitmaps. When a color bitmap returned from CreateBitmap is selected into a device context, Windows must ensure that the bitmap matches the format of the device context it is being selected into. Since CreateCompatibleBitmap takes a device context, it returns a bitmap that has the same format as the specified device context. Because of this, subsequent calls to SelectObject are faster than with a color bitmap returned from CreateBitmap.

If the bitmap is monochrome, zeros represent the foreground color and ones represent the background color for the destination device context.

If an application sets the nWidth or nHeight parameters to zero, CreateBitmap returns the handle of a 1- by 1-pixel, monochrome bitmap.

When you no longer need the bitmap, call the DeleteObject function to delete it.

See Also

CreateBitmapIndirect, CreateCompatibleBitmap, CreateDIBitmap, DeleteObject, GetBitmapBits, SelectObject, SetBitmapBits


CreateBitmapIndirect

The CreateBitmapIndirect function creates a bitmap with the specified width, height, and color format (color planes and bits per pixel).

HBITMAP CreateBitmapIndirect(

CONST BITMAP *lpbm	// pointer to the bitmap data
);
Parameters

lpbm

Points to a BITMAP structure that contains information about the bitmap. If an application sets the bmWidth or bmHeight members to zero, CreateBitmapIndirect returns the handle of a 1- by 1-pixel, monochrome bitmap.

Return Values

If the function succeeds, the return value is a handle to the bitmap.

If the function fails, the return value is NULL.

Remarks

After a bitmap is created, it can be selected into a device context by calling the SelectObject function.

While the CreateBitmapIndirect function can be used to create color bitmaps, for performance reasons applications should use CreateBitmapIndirect to create monochrome bitmaps and CreateCompatibleBitmap to create color bitmaps. When a color bitmap returned from CreateBitmapIndirect is selected into a device context, Windows must ensure that the bitmap matches the format of the device context it is being selected into. Since CreateCompatibleBitmap takes a device context, it returns a bitmap that has the same format as the specified device context. Because of this, subsequent calls to SelectObject are faster than with a color bitmap returned from CreateBitmapIndirect.

If the bitmap is monochrome, zeros represent the foreground color and ones represent the background color for the destination device context.

When you no longer need the bitmap, call the DeleteObject function to delete it.

See Also

BitBlt, BITMAP, CreateBitmap, CreateCompatibleBitmap, CreateDIBitmap, DeleteObject, SelectObject


CreateBrushIndirect

The CreateBrushIndirect function creates a logical brush that has the specified style, color, and pattern.

HBRUSH CreateBrushIndirect(

CONST LOGBRUSH *lplb	// pointer to structure describing brush
);
Parameters

lplb

Points to a LOGBRUSH structure that contains information about the brush.

Return Values

If the function succeeds, the return value identifies a logical brush.

If the function fails, the return value is NULL.

Remarks

A brush is a bitmap that Windows uses to paint the interiors of filled shapes.

After an application creates a brush by calling CreateBrushIndirect, it can select it into any device context by calling the SelectObject function.

A brush created by using a monochrome bitmap (one color plane, one bit per pixel) is drawn using the current text and background colors. Pixels represented by a bit set to 0 are drawn with the current text color; pixels represented by a bit set to 1 are drawn with the current background color.

If the lbStyle member of the LOGBRUSH structure pointed to by lplb is BS_PATTERN, the bitmap pointed to by the lbHatch member of that structure cannot be a DIB section. A DIB section is a bitmap created by CreateDibSection. If that bitmap is a DIB section, the CreateBrushIndirect function fails.

When you no longer need the brush, call the DeleteObject function to delete it.

See Also

CreateDibSection, DeleteObject, GetBrushOrgEx, LOGBRUSH, SelectObject, SetBrushOrgEx


CreateCaret

The CreateCaret function creates a new shape for the system caret and assigns ownership of the caret to the specified window. The caret shape can be a line, a block, or a bitmap.

BOOL CreateCaret(

HWND hWnd,	// handle to owner window
HBITMAP hBitmap,	// handle to bitmap for caret shape
int nWidth,	// caret width
int nHeight	// caret height
);
Parameters

hWnd

Identifies the window that owns the caret.

hBitmap

Identifies the bitmap that defines the caret shape. If this parameter is NULL, the caret is solid. If this parameter is (HBITMAP) 1, the caret is gray. If this parameter is a bitmap handle, the caret is the specified bitmap. The bitmap handle must have been created by the CreateBitmap, CreateDIBitmap, or LoadBitmap function.

If hBitmap is a bitmap handle, CreateCaret ignores the nWidth and nHeight parameters; the bitmap defines its own width and height.

nWidth

Specifies the width of the caret in logical units. If this parameter is zero, the width is set to the system-defined window border width. If hBitmap is a bitmap handle, CreateCaret ignores this parameter.

nHeight

Specifies the height, in logical units, of the caret. If this parameter is zero, the height is set to the system-defined window border height. If hBitmap is a bitmap handle, CreateCaret ignores this parameter.

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.

Remarks

The nWidth and nHeight parameters specify the caret’s width and height, in logical units; the exact width and height, in pixels, depend on the window’s mapping mode.

CreateCaret automatically destroys the previous caret shape, if any, regardless of the window that owns the caret. The caret is hidden until the application calls the ShowCaret function to make the caret visible.

The caret is a shared resource; there is only one caret in the system. A window should create a caret only when it has the keyboard focus or is active. The window should destroy the caret before losing the keyboard focus or becoming inactive.

You can retrieve the width or height of the system’s window border by using the GetSystemMetrics function, specifying the SM_CXBORDER and SM_CYBORDER values. Using the window border width or height guarantees that the caret will be visible on a high-resolution screen.

See Also

CreateBitmap, CreateDIBitmap, DestroyCaret, GetSystemMetrics, HideCaret, LoadBitmap, ShowCaret


CreateColorSpace

The CreateColorSpace function creates a logical color space.

HCOLORSPACE CreateColorSpace(

LPLOGCOLORSPACE lpLogColorSpace
);
Parameters

lpLogColorSpace

Pointer to the LOGCOLORSPACE structure.

Return Values

If the function succeeds, the return value is a handle that identifies a logical color space.

If the function fails, the return value is NULL.

Remarks

When you no longer need the color space, call the DeleteObject function to delete it.

See Also

DeleteObject, LOGCOLORSPACE


CreateCompatibleBitmap

The CreateCompatibleBitmap function creates a bitmap compatible with the device that is associated with the specified device context.

HBITMAP CreateCompatibleBitmap(

HDC hdc,	// handle to device context
int nWidth,	// width of bitmap, in pixels
int nHeight	// height of bitmap, in pixels
);
Parameters

hdc

Identifies a device context.

nWidth

Specifies the bitmap width, in pixels.

nHeight

Specifies the bitmap height, in pixels.

Return Values

If the function succeeds, the return value is a handle to the bitmap.

If the function fails, the return value is NULL.

Remarks

The color format of the bitmap created by the CreateCompatibleBitmap function matches the color format of the device identified by the hdc parameter. This bitmap can be selected into any memory device context that is compatible with the original device.

Because memory device contexts allow both color and monochrome bitmaps, the format of the bitmap returned by the CreateCompatibleBitmap function differs when the specified device context is a memory device context. However, a compatible bitmap that was created for a nonmemory device context always possesses the same color format and uses the same color palette as the specified device context.

If an application sets the nWidth or nHeight parameters to zero, CreateCompatibleBitmap returns the handle of a 1- by 1-pixel, monochrome bitmap.

If a DIB section, which is a bitmap created by the CreateDIBSection function, is selected into the device context identified by the hdc parameter, CreateCompatibleBitmap creates a DIB section.

When you no longer need the bitmap, call the DeleteObject function to delete it.

See Also

CreateDIBSection, DeleteObject, SelectObject


CreateCompatibleDC

The CreateCompatibleDC function creates a memory device context (DC) compatible with the specified device.

HDC CreateCompatibleDC(

HDC hdc	// handle to memory device context
);
Parameters

hdc

Identifies the device context. If this handle is NULL, the function creates a memory device context compatible with the application’s current screen.

Return Values

If the function succeeds, the return value is the handle to a memory device context.

If the function fails, the return value is NULL.

Remarks

Before an application can use a memory device context for drawing operations, it must select a bitmap of the correct width and height into the device context. Once a bitmap has been selected, the device context can be used to prepare images that will be copied to the screen or printed.

The CreateCompatibleDC function can only be used with devices that support raster operations. An application can determine whether a device supports these operations by calling the GetDeviceCaps function.

When you no longer need the memory device context, call the DeleteDC function to delete it.

See Also

CreateCompatibleBitmap, DeleteDC, GetDeviceCaps


CreateConsoleScreenBuffer

The CreateConsoleScreenBuffer function creates a console screen buffer and returns a handle of it.

HANDLE CreateConsoleScreenBuffer(

DWORD dwDesiredAccess,	// access flag
DWORD dwShareMode,	// buffer share mode
LPSECURITY_ATTRIBUTES *lpSecurityAttributes,	// pointer to security attributes
DWORD dwFlags,	// type of buffer to create
LPVOID lpScreenBufferData	// reserved
);
Parameters

dwDesiredAccess

Specifies the desired access to the console screen buffer. This parameter can be one or both of the following values:

Value	Meaning
GENERIC_READ	Requests read access to the console screen buffer, enabling the process to read data from the buffer.
GENERIC_WRITE	Requests write access to the console screen buffer, enabling the process to write data to the buffer.
dwShareMode

Specifies how this console screen buffer can be shared. This parameter can be zero, indicating that the buffer cannot be shared, or it can be one or both of the following two values:

Value	Meaning
FILE_SHARE_READ	Other open operations can be performed on the console screen buffer for read access.
FILE_SHARE_WRITE	Other open operations can be performed on the console screen buffer for write access.
lpSecurityAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new console screen buffer. If lpSecurityAttributes is NULL, the console screen buffer gets a default security descriptor.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

dwFlags

Specifies the type of console screen buffer to create. The only currently supported screen buffer type is CONSOLE_TEXTMODE_BUFFER.

lpScreenBufferData

Reserved for possible future use; should be NULL.

Return Values

If the function succeeds, the return value is a handle to the new console screen buffer.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

A console can have multiple screen buffers but only one active screen buffer. Inactive screen buffers can be accessed for reading and writing, but only the active screen buffer is displayed. To make the new screen buffer the active screen buffer, use the SetConsoleActiveScreenBuffer function.

The calling process can use the returned handle in any function that requires a handle of a console screen buffer, subject to the limitations of access specified by the dwDesiredAccess parameter.

The calling process can use the DuplicateHandle function to create a duplicate screen buffer handle that has different access or inheritability from the original handle. However, DuplicateHandle cannot be used to create a duplicate that is valid for a different process (except through inheritance).

To close the screen buffer handle, use the CloseHandle function.

See Also

CloseHandle, DuplicateHandle, GetConsoleScreenBufferInfo, SECURITY_ATTRIBUTES, SetConsoleActiveScreenBuffer, SetConsoleScreenBufferSize


CreateCursor

The CreateCursor function creates a cursor having the specified size, bit patterns, and hot spot.

HCURSOR CreateCursor(

HINSTANCE hInst,	// handle to application instance
int xHotSpot,	// horizontal position of hot spot
int yHotSpot,	// vertical position of hot spot
int nWidth,	// cursor width
int nHeight,	// cursor height
CONST VOID *pvANDPlane,	// pointer to AND bitmask array
CONST VOID *pvXORPlane	// pointer to XOR bitmask array
);
Parameters

hInst

Identifies the current instance of the application creating the cursor.

xHotSpot

Specifies the horizontal position of the cursor’s hot spot.

yHotSpot

Specifies the vertical position of the cursor’s hot spot.

nWidth

Specifies the width, in pixels, of the cursor.

nHeight

Specifies the height, in pixels, of the cursor.

pvANDplane

Points to an array of bytes that contains the bit values for the AND bitmask of the cursor, as in a device-dependent monochrome bitmap.

pvXORplane

Points to an array of bytes that contains the bit values for the XOR bitmask of the cursor, as in a device-dependent monochrome bitmap.

Return Values

If the function succeeds, the return value identifies the cursor.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The nWidth and nHeight parameters must specify a width and height that are supported by the current display driver, because the system cannot create cursors of other sizes. To determine the width and height supported by the display driver, use the GetSystemMetrics function, specifying the SM_CXCURSOR or SM_CYCURSOR value.

Before closing, an application must call the DestroyCursor function to free any system resources associated with the cursor.

See Also

CreateIcon, DestroyCursor, GetModuleHandle, GetSystemMetrics, SetCursor


CreateDC

The CreateDC function creates a device context (DC) for a device by using the specified name.

HDC CreateDC(

LPCTSTR lpszDriver,	// pointer to string specifying driver name
LPCTSTR lpszDevice,	// pointer to string specifying device name
LPCTSTR lpszOutput,	// do not use; set to NULL
CONST DEVMODE *lpInitData	// pointer to optional printer data
);
Parameters

lpszDriver

Applications written for earlier versions of Windows used this parameter to specify the filename (without extension) of the device driver.

Windows 95: In Win32-based applications, this parameter is ignored and should be NULL, with one exception: You may obtain a display device context by specifying the null-terminated string “DISPLAY”. If this parameter is “DISPLAY”, all other parameters must be NULL.

Windows NT: Points to a null-terminated character string that specifies either “DISPLAY” for a display driver, or the name of a printer driver, which is usually “WINSPOOL”.

lpszDevice

Points to a null-terminated character string that specifies the name of the specific output device being used, as shown by the Print Manager (for example, “Epson FX-80”). It is not the printer model name. The lpszDevice parameter must be used.

lpszOutput

This parameter is ignored. Do not use it in a Win32 application. Win32-based applications should set this parameter to NULL. It exists to provide compatibility for applications written for earlier versions of Windows. For more information, see the following Remarks section.

lpInitData

Points to a DEVMODE structure containing device-specific initialization data for the device driver. The DocumentProperties function retrieves this structure filled in for a specified device. The lpInitData parameter must be NULL if the device driver is to use the default initialization (if any) specified by the user.

Return Values

If the function succeeds, the return value is the handle to a device context for the specified device.

If the function fails, the return value is NULL.

Remarks

Applications written for earlier versions of Windows used the lpszOutput parameter to specify a port name or to print to a file. Win32-based applications do not need to specify a port name. Win32-based applications can print to a file by calling the StartDoc function with a DOCINFO structure whose lpszOutput member specifies the path of the output filename.

When you no longer need the device context, call the DeleteDC function to delete it.

See Also

DeleteDC, DEVMODE, DOCINFO, DocumentProperties, StartDoc


CreateDesktop

The CreateDesktop function creates a new desktop on the window station associated with the calling process. It returns a handle that can be used to access the new desktop. The calling process must have an associated window station, either assigned by the system at process creation time or set by SetProcessWindowStation. A desktop is a secure object contained within a window station object. A desktop has a logical display surface and contains windows, menus, and hooks.

HDESK CreateDesktop(

LPCTSTR lpszDesktop,	// name of the new desktop
LPCTSTR lpszDevice,	// reserved; must be NULL.
LPDEVMODE pDevMode,	// reserved; must be NULL
DWORD dwFlags,	// flags to control interaction with other applications
DWORD dwDesiredAccess,	// specifies access of returned handle
LPSECURITY_ATTRIBUTES lpsa	// specifies security attributes of the desktop
);
Parameters

lpszDesktop

Points to a null-terminated string specifying the name of the desktop to be created. Desktop names are case-insensitive and may not contain backslash characters (\).

lpszDevice

Reserved; must be NULL. The desktop uses the default display driver loaded at boot time.

pDevMode

Reserved; must be NULL.

dwFlags

A bit flag parameter that controls how the calling application will cooperate with other applications on the desktop. This parameter can specify zero or the following value:

Value	Description
DF_ALLOWOTHERACCOUNTHOOK	Allows processes running in other accounts on the desktop to set hooks in this process.
dwDesiredAccess

Specifies the type of access to the desktop. This parameter can be one or more of the following values:

Value	Description
DESKTOP_CREATEMENU	Required to create a menu on the desktop.
DESKTOP_CREATEWINDOW	Required to create a window on the desktop.
DESKTOP_ENUMERATE	Required for the desktop to be enumerated.
DESKTOP_HOOKCONTROL	Required to establish any of the window hooks.
DESKTOP_JOURNALPLAYBACK	Required to perform journal playback on the desktop.
DESKTOP_JOURNALRECORD	Required to perform journal recording on the desktop.
DESKTOP_READOBJECTS	Required to read objects on the desktop.
DESKTOP_SWITCHDESKTOP	Required to activate the desktop using the SwitchDesktop function.
DESKTOP_WRITEOBJECTS	Required to write objects on the desktop.
lpsa

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpsa is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new desktop. If lpsa is NULL, the desktop inherits its security descriptor from the parent window station.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

Return Values

If the function succeeds, the return value is a handle to the newly created desktop.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The CreateDesktop function returns a handle that can be used to access the desktop.

See Also

SECURITY_ATTRIBUTES, SetProcessWindowStation, SwitchDesktop


CreateDialog

The CreateDialog macro creates a modeless dialog box from a dialog box template resource. The CreateDialog macro uses the CreateDialogParam function.

HWND CreateDialog(

HINSTANCE hInstance,	// handle to application instance
LPCTSTR lpTemplate,	// identifies dialog box template name
HWND hWndParent,	// handle to owner window
DLGPROC lpDialogFunc	// pointer to dialog box procedure
);
Parameters

hInstance

Identifies an instance of the module whose executable file contains the dialog box template.

lpTemplate

Identifies the dialog box template. This parameter is either the pointer to a null-terminated character string that specifies the name of the dialog box template or an integer value that specifies the resource identifier of the dialog box template. If the parameter specifies a resource identifier, its high-order word must be zero and its low-order word must contain the identifier. You can use the MAKEINTRESOURCE macro to create this value.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Points to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.

Return Values

If the function succeeds, the return value is the handle to the dialog box.

If the function fails, the return value is NULL.

Remarks

The CreateDialog function uses the CreateWindowEx function to create the dialog box. CreateDialog then sends a WM_INITDIALOG message (and a WM_SETFONT message if the template specifies the DS_SETFONT style) to the dialog box procedure. The function displays the dialog box if the template specifies the WS_VISIBLE style. Finally, CreateDialog returns the window handle to the dialog box.

After CreateDialog returns, the application displays the dialog box (if it is not already displayed) by using the ShowWindow function. The application destroys the dialog box by using the DestroyWindow function.

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

CreateDialogIndirect, CreateDialogIndirectParam, CreateDialogParam, CreateWindowEx, DestroyWindow, DialogBox, DialogProc, ShowWindow, WM_INITDIALOG, WM_SETFONT


CreateDialogIndirect

The CreateDialogIndirect macro creates a modeless dialog box from a dialog box template in memory. The CreateDialogIndirect macro uses the CreateDialogIndirectParam function.

HWND CreateDialogIndirect(

HINSTANCE hInstance,	// handle to application instance
LPCDLGTEMPLATE lpTemplate,	// pointer to dialog box template
HWND hWndParent,	// handle to owner window
DLGPROC lpDialogFunc	// pointer to dialog box procedure
);
Parameters

hInstance

Identifies the instance of the module that creates the dialog box.

lpTemplate

Pointer to a global memory object containing a template that CreateDialogIndirect uses to create the dialog box. A dialog box template consists of a header that describes the dialog box, followed by one or more additional blocks of data that describe each of the controls in the dialog box. The template can use either the standard format or the extended format.

In a standard template, the header is a DLGTEMPLATE structure followed by additional variable-length arrays. The data for each control consists of a DLGITEMTEMPLATE structure followed by additional variable-length arrays.

In an extended dialog box template, the header uses the DLGTEMPLATEEX format and the control definitions use the DLGITEMTEMPLATEEX format.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Points to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.

Return Values

If the function succeeds, the return value is the window handle to the dialog box.

If the function fails, the return value is NULL.

Remarks

The CreateDialogIndirect macro uses the CreateWindowEx function to create the dialog box. CreateDialogIndirect then sends a WM_INITDIALOG message to the dialog box procedure. If the template specifies the DS_SETFONT style, the function also sends a WM_SETFONT message to the dialog box procedure. The function displays the dialog box if the template specifies the WS_VISIBLE style. Finally, CreateDialogIndirect returns the window handle to the dialog box.

After CreateDialogIndirect returns, you can use the ShowWindow function to display the dialog box (if it is not already visible). To destroy the dialog box, use the DestroyWindow function.

In a standard dialog box template, the DLGTEMPLATE structure and each of the DLGITEMTEMPLATE structures must be aligned on DWORD boundaries. The creation data array that follows a DLGITEMTEMPLATE structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must must be aligned on WORD boundaries.

In an extended dialog box template, the DLGTEMPLATEEX header and each of the DLGITEMTEMPLATEEX control definitions must be aligned on DWORD boundaries. The creation data array, if any, that follows a DLGITEMTEMPLATEEX structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must be aligned on WORD boundaries.

All character strings in the dialog box template, such as titles for the dialog box and buttons, must be Unicode strings. To create code that works on both Windows NT and Windows 95, use the MultiByteToWideChar function to generate these Unicode strings.

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

CreateDialog, CreateDialogIndirectParam, CreateDialogParam, CreateWindowEx, DestroyWindow, DialogProc, DLGITEMTEMPLATE, DLGITEMTEMPLATEEX, DLGTEMPLATE, DLGTEMPLATEEX, MultiByteToWideChar, ShowWindow, WM_INITDIALOG, WM_SETFONT


CreateDialogIndirectParam

The CreateDialogIndirectParam function creates a modeless dialog box from a dialog box template in memory. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.

HWND CreateDialogIndirectParam(

HINSTANCE hInstance,	// handle to application instance
LPCDLGTEMPLATE lpTemplate,	// pointer to dialog box template
HWND hWndParent,	// handle to owner window
DLGPROC lpDialogFunc,	// pointer to dialog box procedure
LPARAM lParamInit	// initialization value
);
Parameters

hInstance

Identifies the instance of the module that will create the dialog box.

lpTemplate

Pointer to a global memory object containing a template that CreateDialogIndirectParam uses to create the dialog box. A dialog box template consists of a header that describes the dialog box, followed by one or more additional blocks of data that describe each of the controls in the dialog box. The template can use either the standard format or the extended format.

In a standard template, the header is a DLGTEMPLATE structure followed by additional variable-length arrays. The data for each control consists of a DLGITEMTEMPLATE structure followed by additional variable-length arrays.

In an extended dialog box template, the header uses the DLGTEMPLATEEX format and the control definitions use the DLGITEMTEMPLATEEX format.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Points to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.

lParamInit

Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.

Return Values

If the function succeeds, the return value is the window handle to the dialog box.

If the function fails, the return value is NULL.

Remarks

The CreateDialogIndirectParam function uses the CreateWindowEx function to create the dialog box. CreateDialogIndirectParam then sends a WM_INITDIALOG message to the dialog box procedure. If the template specifies the DS_SETFONT style, the function also sends a WM_SETFONT message to the dialog box procedure. The function displays the dialog box if the template specifies the WS_VISIBLE style. Finally, CreateDialogIndirectParam returns the window handle to the dialog box.

After CreateDialogIndirectParam returns, you can use the ShowWindow function to display the dialog box (if it is not already visible). To destroy the dialog box, use the DestroyWindow function.

In a standard dialog box template, the DLGTEMPLATE structure and each of the DLGITEMTEMPLATE structures must be aligned on DWORD boundaries. The creation data array that follows a DLGITEMTEMPLATE structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must must be aligned on WORD boundaries.

In an extended dialog box template, the DLGTEMPLATEEX header and each of the DLGITEMTEMPLATEEX control definitions must be aligned on DWORD boundaries. The creation data array, if any, that follows a DLGITEMTEMPLATEEX structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must be aligned on WORD boundaries.

All character strings in the dialog box template, such as titles for the dialog box and buttons, must be Unicode strings. To create code that works on both Windows NT and Windows 95, use the MultiByteToWideChar function to generate these Unicode strings.

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

CreateDialog, CreateDialogIndirect, CreateDialogParam, CreateWindowEx, DestroyWindow, DialogProc, DLGITEMTEMPLATE, DLGITEMTEMPLATEEX, DLGTEMPLATE, DLGTEMPLATEEX, MultiByteToWideChar, ShowWindow, WM_INITDIALOG, WM_SETFONT


CreateDialogParam

The CreateDialogParam function creates a modeless dialog box from a dialog box template resource. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.

HWND CreateDialogParam(

HINSTANCE hInstance,	// handle to application instance
LPCTSTR lpTemplateName,	// identifies dialog box template
HWND hWndParent,	// handle to owner window
DLGPROC lpDialogFunc,	// pointer to dialog box procedure
LPARAM dwInitParam	// initialization value
);
Parameters

hInstance

Identifies an instance of the module whose executable file contains the dialog box template.

lpTemplateName

Identifies the dialog box template. This parameter is either the pointer to a null-terminated character string that specifies the name of the dialog box template or an integer value that specifies the resource identifier of the dialog box template. If the parameter specifies a resource identifier, its high-order word must be zero and low-order word must contain the identifier. You can use the MAKEINTRESOURCE macro to create this value.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Points to the dialog box procedure. For more information about the dialog box procedure, see DialogProc .

dwInitParam

Specifies the value to pass to the dialog box procedure in the lParam parameter in the WM_INITDIALOG message.

Return Values

If the function succeeds, the return value is the window handle to the dialog box.

If the function fails, the return value is NULL.

Remarks

The CreateDialogParam function uses the CreateWindowEx function to create the dialog box. CreateDialogParam then sends a WM_INITDIALOG message (and a WM_SETFONT message if the template specifies the DS_SETFONT style) to the dialog box procedure. The function displays the dialog box if the template specifies the WS_VISIBLE style. Finally, CreateDialogParam returns the window handle of the dialog box.

After CreateDialogParam returns, the application displays the dialog box (if it is not already displayed) by using the ShowWindow function. The application destroys the dialog box by using the DestroyWindow function.

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

CreateDialog, CreateDialogIndirect, CreateDialogIndirectParam, CreateWindowEx, DestroyWindow, DialogProc, MAKEINTRESOURCE, ShowWindow, WM_INITDIALOG, WM_SETFONT


CreateDIBitmap

The CreateDIBitmap function creates a device-dependent bitmap (DDB) from a device-independent bitmap (DIB) and, optionally, sets the bitmap bits.

HBITMAP CreateDIBitmap(

HDC hdc,	// handle to device context
CONST BITMAPINFOHEADER *lpbmih,	// pointer to bitmap size and format data
DWORD fdwInit,	// initialization flag
CONST VOID *lpbInit,	// pointer to initialization data
CONST BITMAPINFO *lpbmi,	// pointer to bitmap color-format data
UINT fuUsage	// color-data usage
);
Parameters

hdc

Identifies a device context.

lpbmih

Points to a BITMAPINFOHEADER structure.

If fdwInit is CBM_INIT, the function uses the BITMAPINFOHEADER structure to obtain the desired width and height of the bitmap as well as other information. Note that a positive value for the height indicates a bottom-up DIB while a negative value for the height indicates a top-down DIB. This scenario is compatible with the CreateDIBitmap function.

fdwInit

A set of bit flags that specify how the operating system initializes the bitmap’s bits.

The following bit flag constant is defined:

Value	Meaning
CBM_INIT	If this flag is set, the operating system uses the data pointed to by the lpbInit and lpbmi parameters to initialize the bitmap’s bits. If this flag is clear, the data pointed to by those parameters is not used.
If fdwInit is zero, the operating system does not initialize the bitmap’s bits.

lpbInit

Points to an array of bytes containing the initial bitmap data. The format of the data depends on the biBitCount member of the BITMAPINFO structure to which the lpbmi parameter points.

lpbmi

Points to a BITMAPINFO structure that describes the dimensions and color format of the array pointed to by the lpbInit parameter.

fuUsage

Specifies whether the bmiColors member of the BITMAPINFO structure was initialized and, if so, whether bmiColors contains explicit red, green, blue (RGB) values or palette indices. The fuUsage parameter must be one of the following values:

Value	Meaning
DIB_PAL_COLORS	A color table is provided and consists of an array of 16-bit indices into the logical palette of the device context into which the bitmap is to be selected.
DIB_RGB_COLORS	A color table is provided and contains literal RGB values.
Return Values

If the function succeeds, the return value is a handle to the bitmap.

If the function fails, the return value is NULL.

Remarks

The CBM_CREATDIB flag for the fdwInit parameter is no longer supported.

When you no longer need the bitmap, call the DeleteObject function to delete it.

See Also

BITMAPINFOHEADER, BITMAPINFO, DeleteObject, GetDeviceCaps, GetSystemPaletteEntries, SelectObject


CreateDIBPatternBrush

The CreateDIBPatternBrush function creates a logical brush that has the pattern specified by the specified device-independent bitmap (DIB). The brush can subsequently be selected into any device context that is associated with a device that supports raster operations.

This function is provided only for compatibility with applications written for versions of Windows earlier than 3.0. For Win32-based applications, use the CreateDIBPatternBrushPt function.

HBRUSH CreateDIBPatternBrush(

HGLOBAL hglbDIBPacked,	// handle to device-independent bitmap
UINT fuColorSpec	// color table data
);
Parameters

hglbDIBPacked

Identifies a global memory object containing a packed DIB, which consists of a BITMAPINFO structure immediately followed by an array of bytes defining the pixels of the bitmap.

Windows 95: Creating brushes from bitmaps or DIBs larger than 8x8 pixels is not supported. If a larger bitmap is specified, only a portion of the bitmap is used.

fuColorSpec

Specifies whether the bmiColors member of the BITMAPINFO structure is initialized and, if so, whether this member contains explicit red, green, blue (RGB) values or indices into a logical palette. The fuColorSpec parameter must be one of the following values:

Value	Meaning
DIB_PAL_COLORS	A color table is provided and consists of an array of 16-bit indices into the logical palette of the device context into which the brush is to be selected.
DIB_RGB_COLORS	A color table is provided and contains literal RGB values.
Return Values

If the function succeeds, the return value identifies a logical brush.

If the function fails, the return value is NULL.

Remarks

When an application selects a two-color DIB pattern brush into a monochrome device context, Windows does not acknowledge the colors specified in the DIB; instead, it displays the pattern brush using the current background and foreground colors of the device context. Pixels mapped to the first color of the DIB (offset 0 in the DIB color table) are displayed using the foreground color; pixels mapped to the second color (offset 1 in the color table) are displayed using the background color.

When you no longer need the brush, call the DeleteObject function to delete it.

See Also

BITMAPINFO, CreateDIBPatternBrushPt, CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, DeleteObject, SetBkColor, SetTextColor


CreateDIBPatternBrushPt

The CreateDIBPatternBrushPt function creates a logical brush that has the pattern specified by the device-independent bitmap (DIB).

HBRUSH CreateDIBPatternBrushPt(

CONST VOID *lpPackedDIB,	// pointer to structure and bitmap bits
UINT iUsage	// usage flags
);
Parameters

lpPackedDIB

Points to a packed DIB consisting of a BITMAPINFO structure immediately followed by an array of bytes defining the pixels of the bitmap.

Windows 95: Creating brushes from bitmaps or DIBs larger than 8x8 pixels is not supported. If a larger bitmap is specified, only a portion of the bitmap is used.

iUsage

Specifies whether the bmiColors member of the BITMAPINFO structure contains a valid color table and, if so, whether the entries in this color table contain explicit red, green, blue (RGB) values or palette indices. The iUsage parameter must be one of the following values:

Value	Meaning
DIB_PAL_COLORS	A color table is provided and consists of an array of 16-bit indices into the logical palette of the device context into which the brush is to be selected.
DIB_RGB_COLORS	A color table is provided and contains literal RGB values.
Return Values

If the function succeeds, the return value identifies a logical brush.

If the function fails, the return value is NULL.

Remarks

A brush is a bitmap that Windows uses to paint the interiors of filled shapes.

After an application creates a brush by calling CreateDIBPatternBrushPt, it can select that brush into any device context by calling the SelectObject function.

When you no longer need the brush, call the DeleteObject function to delete it.

See Also

BITMAPINFO, CreateDIBPatternBrush, CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, DeleteObject, GetBrushOrgEx, SelectObject, SetBrushOrgEx


CreateDIBSection

The CreateDIBSection function creates a device-independent bitmap (DIB) that applications can write to directly. The function gives you a pointer to the location of the bitmap’s bit values. You can supply a handle to a file mapping object that the function will use to create the bitmap, or you can let the operating system allocate the memory for the bitmap.

HBITMAP CreateDIBSection(

HDC hdc,	// handle to device context
CONST BITMAPINFO *pbmi,	// pointer to structure containing bitmap size, format, and color data
UINT iUsage,	// color data type indicator: RGB values or palette indices
VOID *ppvBits,	// pointer to variable to receive a pointer to the bitmap’s bit values
HANDLE hSection,	// optional handle to a file mapping object
DWORD dwOffset	// offset to the bitmap bit values within the file mapping object
);
Parameters

hdc

Handle to a device context. If the value of iUsage is DIB_PAL_COLORS, the function uses this device context’s logical palette to initialize the device-independent bitmap’s colors.

pbmi

Points to a BITMAPINFO structure that specifies various attributes of the device-independent bitmap, including the bitmap’s dimensions and colors.

iUsage

Specifies the type of data contained in the bmiColors array member of the BITMAPINFO structure pointed to by pbmi: logical palette indices or literal RGB values. The following values are defined:

Value	Meaning
DIB_PAL_COLORS	The bmiColors member is an array of 16-bit indices into the logical palette of the device context specified by hdc.
DIB_RGB_COLORS	The BITMAPINFO structure contains an array of literal RGB values.
ppvBits

Points to a variable that receives a pointer to the location of the device-independent bitmap’s bit values.

hSection

Handle to a file mapping object that the function will use to create the device-independent bitmap. This parameter can be NULL.

If hSection is not NULL, it must be a handle to a file mapping object created by calling the CreateFileMapping function. Handles created by other means will cause CreateDIBSection to fail.

If hSection is not NULL, the CreateDIBSection function locates the bitmap’s bit values at offset dwOffset in the file mapping object referred to by hSection. An application can later retrieve the hSection handle by calling the GetObject function with the HBITMAP returned by CreateDIBSection.

If hSection is NULL, the operating system allocates memory for the device-independent bitmap. In this case, the CreateDIBSection function ignores the dwOffset parameter. An application cannot later obtain a handle to this memory: the dshSection member of the DIBSECTION structure filled in by calling the GetObject function will be NULL.

dwOffset

Specifies the offset from the beginning of the file mapping object referenced by hSection where storage for the bitmap’s bit values is to begin. This value is ignored if hSection is NULL. The bitmap’s bit values are aligned on doubleword boundaries, so dwOffset must be a multiple of the size of a DWORD.

Return Values

If the function succeeds, the return value is a handle to the newly created device-independent bitmap, and *ppvBits points to the bitmap’s bit values.

If the function fails, the return value is NULL, and *ppvBits is NULL. To get extended error information, call GetLastError.

Remarks

As noted above, if hSection is NULL, the operating system allocates memory for the device-independent bitmap. The operating system closes the handle to that memory when you later delete the device-independent bitmap by calling the DeleteObject function. If hSection is not NULL, you must close the hSection memory handle yourself after calling DeleteObject to delete the bitmap.

Windows NT: You need to guarantee that the GDI subsystem has completed any drawing to a bitmap created by CreateDIBSection before you draw to the bitmap yourself. Access to the bitmap must be synchronized. Do this by calling the GdiFlush function. This applies to any use of the pointer to the bitmap’s bit values, including passing the pointer in calls to functions such as SetDIBits.

See Also

BITMAPINFO, CreateFileMapping, DeleteObject, DIBSECTION, GetDIBColorTable, GetObject, GdiFlush, HBITMAP, SetDIBits, SetDIBColorTable


CreateDirectory

The CreateDirectory function creates a new directory. If the underlying file system supports security on files and directories, the function applies a specified security descriptor to the new directory. Note that CreateDirectory does not have a template parameter, while CreateDirectoryEx does.

BOOL CreateDirectory(

LPCTSTR lpPathName,	// pointer to a directory path string
LPSECURITY_ATTRIBUTES lpSecurityAttributes	// pointer to a security descriptor
);
Parameters

lpPathName

Points to a null-terminated string that specifies the path of the directory to be created.

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the CreateDirectory function parses paths.

Windows NT: An application can transcend this limit and send in paths longer than MAX_PATH characters by calling the wide (W) version of CreateDirectory and prepending “\\?\” to the path. The “\\?\” tells the function to turn off path parsing; it lets paths longer than MAX_PATH be used with CreateDirectoryW. This also works with UNC names. The “\\?\” is ignored as part of the path. For example, “\\?\C:\myworld\private” is seen as “C:\myworld\private”, and “\\?\UNC\bill_g_1\hotstuff\coolapps” is seen as “\\bill_g_1\hotstuff\coolapps”.

lpSecurityAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new directory. If lpSecurityAttributes is NULL, the directory gets a default security descriptor. The target file system must support security on files and directories for this parameter to have an effect.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

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.

Remarks

Windows NT: Some file systems, such as NTFS, support compression for individual files and directories. On volumes formatted for such a file system, a new directory inherits the compression attribute of its parent directory.

Windows NT: An application can obtain a handle to a directory by calling CreateFile with the FILE_FLAG_BACKUP_SEMANTICS flag set. For a code example, see CreateFile.

See Also

CreateDirectoryEx, CreateFile, RemoveDirectory, SECURITY_ATTRIBUTES


CreateDirectoryEx

The CreateDirectoryEx function creates a new directory with a specified path that retains the attributes of a specified template directory. If the underlying file system supports security on files and directories, the function applies a specified security descriptor to the new directory. The new directory retains the other attributes of the specified template directory. Note that CreateDirectoryEx has a template parameter, while CreateDirectory does not.

BOOL CreateDirectoryEx(

LPCTSTR lpTemplateDirectory,	// pointer to path string of template directory
LPCTSTR lpNewDirectory,	// pointer to path string of directory to create
LPSECURITY_ATTRIBUTES lpSecurityAttributes	// pointer to security descriptor
);
Parameters

lpTemplateDirectory

Points to a null-terminated string that specifies the path of the directory to use as a template when creating the new directory.

lpNewDirectory

Points to a null-terminated string that specifies the path of the directory to be created.

lpSecurityAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new directory. If lpSecurityAttributes is NULL, the directory gets a default security descriptor. The target file system must support security on files and directories for this parameter to have an effect.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

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.

Remarks

The CreateDirectoryEx function allows you to create directories that inherit stream information from other directories. This function is useful, for example, when dealing with Macintosh directories, which have a resource stream that is needed to properly identify directory contents as an attribute.

Windows NT:

Some file systems, such as NTFS, support compression for individual files and directories. On volumes formatted for such a file system, a new directory inherits the compression attribute of its parent directory.

You can obtain a handle to a directory by calling the CreateFile function with the FILE_FLAG_BACKUP_SEMANTICS flag set. See CreateFile for a code example.

See Also

CreateDirectory, CreateFile, RemoveDirectory, SECURITY_ATTRIBUTES


CreateDiscardableBitmap

The CreateDiscardableBitmap function creates a discardable bitmap that is compatible with the specified device. The bitmap has the same bits-per-pixel format and the same color palette as the device. An application can select this bitmap as the current bitmap for a memory device that is compatible with the specified device.

The CreateDiscardableBitmap function is included only for compatibility with earlier versions of Windows. For Win32-based applications, use the CreateCompatibleBitmap function.

HBITMAP CreateDiscardableBitmap(

HDC hdc,	// handle to device context
int nWidth,	// bitmap width
int nHeight	// bitmap height
);
Parameters

hdc

Identifies a device context.

nWidth

Specifies the width, in bits, of the bitmap.

nHeight

Specifies the height, in bits, of the bitmap.

Return Values

If the function succeeds, the return value is a handle to the bitmap.

If the function fails, the return value is NULL.

Remarks

When you no longer need the bitmap, call the DeleteObject function to delete it.

See Also

CreateCompatibleBitmap, DeleteObject


CreateEllipticRgn

The CreateEllipticRgn function creates an elliptical region.

HRGN CreateEllipticRgn(

int nLeftRect,	// x-coordinate of the upper-left corner of the bounding rectangle
int nTopRect,	// y-coordinate of the upper-left corner of the bounding rectangle
int nRightRect,	// x-coordinate of the lower-right corner of the bounding rectangle
int nBottomRect	// y-coordinate of the lower-right corner of the bounding rectangle
);
Parameters

nLeftRect

Specifies the x-coordinate of the upper-left corner of the bounding rectangle of the ellipse.

nTopRect

Specifies the y-coordinate of the upper-left corner of the bounding rectangle of the ellipse.

nRightRect

Specifies the x-coordinate of the lower-right corner of the bounding rectangle of the ellipse.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the bounding rectangle of the ellipse.

Return Values

If the function succeeds, the return value is the handle to the region.

If the function fails, the return value is NULL.

Remarks

A bounding rectangle defines the size, shape, and orientation of the region: The long sides of the rectangle define the length of the ellipse’s major axis; the short sides define the length of the ellipse’s minor axis; and the center of the rectangle defines the intersection of the major and minor axes.

The coordinates of the bounding rectangle are specified in logical units.

See Also

CreateEllipticRgnIndirect, DeleteObject, SelectObject


CreateEllipticRgnIndirect

The CreateEllipticRgnIndirect function creates an elliptical region.

HRGN CreateEllipticRgnIndirect(

CONST RECT *lprc	// pointer to structure defining bounding rectangle
);
Parameters

lprc

Points to a RECT structure that contains the coordinates of the upper-left and lower-right corners of the bounding rectangle of the ellipse.

Return Values

If the function succeeds, the return value is the handle to the region.

If the function fails, the return value is NULL.

Remarks

A bounding rectangle defines the size, shape, and orientation of the region: The long sides of the rectangle define the length of the ellipse’s major axis; the short sides define the length of the ellipse’s minor axis; and the center of the rectangle defines the intersection of the major and minor axes.

The coordinates of the bounding rectangle are specified in logical units.

See Also

CreateEllipticRgn, DeleteObject, RECT, SelectObject


CreateEnhMetaFile

The CreateEnhMetaFile function creates a device context for an enhanced-format metafile. This device context can be used to store a device-independent picture.

HDC CreateEnhMetaFile(

HDC hdcRef,	// handle to a reference device context
LPCTSTR lpFilename,	// pointer to a filename string
CONST RECT *lpRect,	// pointer to a bounding rectangle
LPCTSTR lpDescription	// pointer to an optional description string
);
Parameters

hdcRef

Identifies a reference device for the enhanced metafile.

lpFilename

Points to the filename for the enhanced metafile to be created. If this parameter is NULL, the enhanced metafile is memory based and its contents are lost when it is deleted by using the DeleteEnhMetaFile function.

lpRect

Points to a RECT structure that specifies the dimensions (in .01-millimeter units) of the picture to be stored in the enhanced metafile.

lpDescription

Points to a string that specifies the name of the application that created the picture, as well as the picture’s title.

Return Values

If the function succeeds, the return value is a handle to the device context for the enhanced metafile.

If the function fails, the return value is NULL.

Remarks

Where text arguments must use Unicode characters, use the CreateEnhMetaFile function as a wide-character function. Where text arguments must use characters from the Windows 3.x character set, use this function as an ANSI function.

Windows uses the reference device identified by the hdcRef parameter to record the resolution and units of the device on which a picture originally appeared. If the hdcRef parameter is NULL, it uses the current display device for reference.

The left and top members of the RECT structure pointed to by the lpRect parameter must be less than the right and bottom members, respectively. Points along the edges of the rectangle are included in the picture. If lpRect is NULL, the graphics device interface (GDI) computes the dimensions of the smallest rectangle that surrounds the picture drawn by the application. The lpRect parameter should be provided where possible.

The string pointed to by the lpDescription parameter must contain a null character between the application name and the picture name and must terminate with two null characters — for example, “XYZ Graphics Editor\0Bald Eagle\0\0”, where \0 represents the null character. If lpDescription is NULL, there is no corresponding entry in the enhanced-metafile header.

Applications use the device context created by this function to store a graphics picture in an enhanced metafile. The handle identifying this device context can be passed to any GDI function.

After an application stores a picture in an enhanced metafile, it can display the picture on any output device by calling the PlayEnhMetaFile function. When displaying the picture, Windows uses the rectangle pointed to by the lpRect parameter and the resolution data from the reference device to position and scale the picture.

The device context returned by this function contains the same default attributes associated with any new device context.

Applications must use the GetWinMetaFileBits function to convert an enhanced metafile to the older Windows metafile format.

The filename for the enhanced metafile should use the .EMF extension.

See Also

CloseEnhMetaFile, DeleteEnhMetaFile, GetEnhMetaFileDescription, GetEnhMetaFileHeader, GetWinMetaFileBits, PlayEnhMetaFile, RECT


CreateEvent

The CreateEvent function creates a named or unnamed event object.

HANDLE CreateEvent(

LPSECURITY_ATTRIBUTES lpEventAttributes,	// pointer to security attributes
BOOL bManualReset,	// flag for manual-reset event
BOOL bInitialState,	// flag for initial state
LPCTSTR lpName	// pointer to event-object name
);
Parameters

lpEventAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpEventAttributes is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new event. If lpEventAttributes is NULL, the event gets a default security descriptor.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

bManualReset

Specifies whether a manual-reset or auto-reset event object is created. If TRUE, then you must use the ResetEvent function to manually reset the state to nonsignaled. If FALSE, Windows automatically resets the state to nonsignaled after a single waiting thread has been released.

bInitialState

Specifies the initial state of the event object. If TRUE, the initial state is signaled; otherwise, it is nonsignaled.

lpName

Points to a null-terminated string specifying the name of the event object. The name is limited to MAX_PATH characters and can contain any character except the backslash path-separator character (\). Name comparison is case sensitive.

If lpName matches the name of an existing named event object, this function requests EVENT_ALL_ACCESS access to the existing object. In this case, the bManualReset and bInitialState parameters are ignored because they have already been set by the creating process. If the lpEventAttributes parameter is not NULL, it determines whether the handle can be inherited, but its security-descriptor member is ignored.

If lpName is NULL, the event object is created without a name.

If lpName matches the name of an existing semaphore, mutex, or file-mapping object, the function fails and the GetLastError function returns ERROR_INVALID_HANDLE. This occurs because event, mutex, semaphore, and file-mapping objects share the same name space.

Return Values

If the function succeeds, the return value is a handle to the event object. If the named event object existed before the function call, the GetLastError function returns ERROR_ALREADY_EXISTS. Otherwise, GetLastError returns zero.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The handle returned by CreateEvent has EVENT_ALL_ACCESS access to the new event object and can be used in any function that requires a handle to an event object.

Any thread of the calling process can specify the event-object handle in a call to one of the wait functions. The single-object wait functions return when the state of the specified object is signaled. The multiple-object wait functions can be instructed to return either when any one or when all of the specified objects are signaled. When a wait function returns, the waiting thread is released to continue its execution.

The initial state of the event object is specified by the bInitialState parameter. Use the SetEvent function to set the state of an event object to signaled. Use the ResetEvent function to reset the state of an event object to nonsignaled.

When the state of a manual-reset event object is signaled, it remains signaled until it is explicitly reset to nonsignaled by the ResetEvent function. Any number of waiting threads, or threads that subsequently begin wait operations for the specified event object, can be released while the object’s state is signaled.

When the state of an auto-reset event object is signaled, it remains signaled until a single waiting thread is released; the system then automatically resets the state to nonsignaled. If no threads are waiting, the event object’s state remains signaled.

Multiple processes can have handles of the same event object, enabling use of the object for interprocess synchronization. The following object-sharing mechanisms are available:

•	A child process created by the CreateProcess function can inherit a handle to an event object if the lpEventAttributes parameter of CreateEvent enabled inheritance.

•	A process can specify the event-object handle in a call to the DuplicateHandle function to create a duplicate handle that can be used by another process.

•	A process can specify the name of an event object in a call to the OpenEvent or CreateEvent function.

Use the CloseHandle function to close the handle. The system closes the handle automatically when the process terminates. The event object is destroyed when its last handle has been closed.

See Also

CloseHandle, CreateProcess, DuplicateHandle, OpenEvent, ResetEvent, SECURITY_ATTRIBUTES, SetEvent


CreateFiber

The CreateFiber function allocates a fiber object, assigns it a stack, and sets up execution to begin at the specified start address, typically the fiber function. This function does not schedule the fiber.

LPVOID CreateFiber(

DWORD dwStackSize,	// initial thread stack size, in bytes
LPFIBER_START_ROUTINE lpStartAddress,	// pointer to fiber function
LPVOID lpParameter	// argument for new fiber
);
Parameters

dwStackSize

Specifies the size, in bytes, of the stack for the new fiber. If zero is specified, the stack size defaults to the same size as that of the main thread. The function fails if it cannot commit dwStackSize bytes. Note that the system increases the stack size dynamically, if necessary. The stack is freed when the thread terminates.

lpStartAddress

Points to the application-supplied function to be executed by the fiber and represents the starting address of the fiber. The function accepts a single argument and does not return a value. Execution of the newly created fiber does not begin until another fiber calls the SwitchToFiber function with this address.

lpParameter

Specifies a single argument that is passed to the fiber. This value can be retrieved by the fiber using the GetFiberData function.

Return Values

If the function succeeds, the return value is the address of the fiber.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Before a thread can schedule a fiber using the SwitchToFiber function, it must call the ConvertThreadToFiber function so there is a fiber associated with the thread.

The fiber function is of type FIBER_START_ROUTINE. It accepts a single value of type PVOID (fiber data) and does not return a value. The prototype for this function is as follows:

VOID WINAPI FiberFunc( PVOID lpParameter );

See Also

ConvertThreadToFiber, GetFiberData, SwitchToFiber


CreateFile

The CreateFile function creates or opens the following objects and returns a handle that can be used to access the object:

•	files

•	pipes

•	mailslots

•	communications resources

•	disk devices (Windows NT only)

•	consoles

•	directories (open only)

HANDLE CreateFile(

LPCTSTR lpFileName,	// pointer to name of the file
DWORD dwDesiredAccess,	// access (read-write) mode
DWORD dwShareMode,	// share mode
LPSECURITY_ATTRIBUTES lpSecurityAttributes,	// pointer to security attributes
DWORD dwCreationDistribution,	// how to create
DWORD dwFlagsAndAttributes,	// file attributes
HANDLE hTemplateFile	// handle to file with attributes to copy
);
Parameters

lpFileName

Points to a null-terminated string that specifies the name of the object (file, pipe, mailslot, communications resource, disk device, console, or directory) to create or open.

If *lpFileName is a path, there is a default string size limit of MAX_PATH characters. This limit is related to how the CreateFile function parses paths.

Windows NT: You can use paths longer than MAX_PATH characters by calling the wide (W) version of CreateFile and prepending “\\?\” to the path. The “\\?\” tells the function to turn off path parsing. This lets you use paths that are nearly 32,000 Unicode characters long. You must use fully-qualified paths with this technique. This also works with UNC names. The “\\?\” is ignored as part of the path. For example, “\\?\C:\myworld\private” is seen as “C:\myworld\private”, and “\\?\UNC\tom_1\hotstuff\coolapps” is seen as “\\tom_1\hotstuff\coolapps”.

dwDesiredAccess

Specifies the type of access to the object. An application can obtain read access, write access, read-write access, or device query access. This parameter can be any combination of the following values.

Value	Meaning
0	Specifies device query access to the object. An application can query device attributes without accessing the device.
GENERIC_READ	Specifies read access to the object. Data can be read from the file and the file pointer can be moved. Combine with GENERIC_WRITE for read-write access.
GENERIC_WRITE	Specifies write access to the object. Data can be written to the file and the file pointer can be moved. Combine with GENERIC_READ for read-write access.
dwShareMode

Set of bit flags that specifies how the object can be shared. If dwShareMode is 0, the object cannot be shared. Subsequent open operations on the object will fail, until the handle is closed.

To share the object, use a combination of one or more of the following values:

Value	Meaning
FILE_SHARE_DELETE	Windows NT only: Subsequent open operations on the object will succeed only if delete access is requested.
FILE_SHARE_READ	Subsequent open operations on the object will succeed only if read access is requested.
FILE_SHARE_WRITE	Subsequent open operations on the object will succeed only if write access is requested.
lpSecurityAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the object. If lpSecurityAttributes is NULL, the object gets a default security descriptor. The target file system must support security on files and directories for this parameter to have an effect on files.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

dwCreationDistribution

Specifies which action to take on files that exist, and which action to take when files do not exist. For more information about this parameter, see the Remarks section. This parameter must be one of the following values:

Value	Meaning
CREATE_NEW	Creates a new file. The function fails if the specified file already exists.
CREATE_ALWAYS	Creates a new file. The function overwrites the file if it exists.
OPEN_EXISTING	Opens the file. The function fails if the file does not exist.
	See the Remarks section for a discussion of why you should use the OPEN_EXISTING flag if you are using the CreateFile function for devices, including the console.
OPEN_ALWAYS	Opens the file, if it exists. If the file does not exist, the function creates the file as if dwCreationDistribution were CREATE_NEW.
TRUNCATE_EXISTING	Opens the file. Once opened, the file is truncated so that its size is zero bytes. The calling process must open the file with at least GENERIC_WRITE access. The function fails if the file does not exist.
dwFlagsAndAttributes

Specifies the file attributes and flags for the file.

Any combination of the following attributes is acceptable, except all other file attributes override FILE_ATTRIBUTE_NORMAL.

Attribute	Meaning
FILE_ATTRIBUTE_ARCHIVE	The file should be archived. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED	The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_HIDDEN	The file is hidden. It is not to be included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL	The file has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_OFFLINE	The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage.
FILE_ATTRIBUTE_READONLY	The file is read only. Applications can read the file but cannot write to it or delete it.
FILE_ATTRIBUTE_SYSTEM	The file is part of or is used exclusively by the operating system.
FILE_ATTRIBUTE_TEMPORARY	The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed.
Any combination of the following flags is acceptable.

Flag	Meaning
FILE_FLAG_WRITE_THROUGH
	Instructs the operating system to write through any intermediate cache and go directly to disk. The operating system can still cache write operations, but cannot lazily flush them.
FILE_FLAG_OVERLAPPED
	Instructs the operating system to initialize the object, so ReadFile, WriteFile, ConnectNamedPipe, and TransactNamedPipe operations that take a significant amount of time to process return ERROR_IO_PENDING. When the operation is finished, an event is set to the signaled state.
	When you specify FILE_FLAG_OVERLAPPED, the ReadFile and WriteFile functions must specify an OVERLAPPED structure. That is, when FILE_FLAG_OVERLAPPED is specified, an application must perform overlapped reading and writing.
	When FILE_FLAG_OVERLAPPED is specified, the operating system does not maintain the file pointer. The file position must be passed as part of the lpOverlapped parameter (pointing to an OVERLAPPED structure) to the ReadFile and WriteFile functions.
	This flag also enables more than one operation to be performed simultaneously with the handle (a simultaneous read and write operation, for example).
FILE_FLAG_NO_BUFFERING
	Instructs the operating system to open the file with no intermediate buffering or caching. This can provide performance gains in some situations.  An application must meet certain requirements when working with files opened with FILE_FLAG_NO_BUFFERING: • File access must begin at byte offsets within the file that are integer multiples of the volume’s sector size.  • File access must be for numbers of bytes that are integer multiples of the volume’s sector size. For example, if the sector size is 512 bytes, an application can request reads and writes of 512, 1024, or 2048 bytes, but not of 335, 981, or 7171 bytes.  • Buffer addresses for read and write operations must be aligned on addresses in memory that are integer multiples of the volume’s sector size.  One way to align buffers on integer multiples of the volume sector size is to use VirtualAlloc to allocate the buffers. It allocates memory that is aligned on addresses that are integer multiples of the operating system’s memory page size. Since both memory page and volume sector sizes are powers of 2, this memory is also aligned on addresses that are integer multiples of a volume’s sector size.  An application can determine a volume’s sector size by calling the GetDiskFreeSpace function.
FILE_FLAG_RANDOM_ACCESS
	Indicates that the file is accessed randomly. Windows can use this as a hint to optimize file caching.
FILE_FLAG_SEQUENTIAL_SCAN
	Indicates that the file is to be accessed sequentially from beginning to end. Windows can use this as a hint to optimize file caching. If an application moves the file pointer for random access, optimum caching may not occur; however, correct operation is still guaranteed.
	Specifying this flag can increase performance for applications that read large files using sequential access. Performance gains can be even more noticeable for applications that read large files mostly sequentially, but occasionally skip over small ranges of bytes.
FILE_FLAG_DELETE_ON_CLOSE
	Indicates that the operating system is to delete the file immediately after all of its handles have been closed, not just the handle for which you specified FILE_FLAG_DELETE_ON_CLOSE.  Subsequent open requests for the file will fail, unless FILE_SHARE_DELETE is used.
FILE_FLAG_BACKUP_SEMANTICS
	Windows NT only: Indicates that the file is being opened or created for a backup or restore operation. The operating system ensures that the calling process overrides file security checks, provided it has the necessary permission to do so. The relevant permissions are SE_BACKUP_NAME and SE_RESTORE_NAME. You can also set this flag to obtain a handle to a directory. A directory handle can be passed to some Win32 functions in place of a file handle.
FILE_FLAG_POSIX_SEMANTICS
	Indicates that the file is to be accessed according to POSIX rules. This includes allowing multiple files with names, differing only in case, for file systems that support such naming. Use care when using this option because files created with this flag may not be accessible by applications written for MS-DOS, Windows, or Windows NT.
If the CreateFile function opens the client side of a named pipe, the dwFlagsAndAttributes parameter can also contain Security Quality of Service information. When the calling application specifies the SECURITY_SQOS_PRESENT flag, the dwFlagsAndAttributes parameter can contain one or more of the following values:

Value	Meaning
SECURITY_ANONYMOUS	Specifies to impersonate the client at the Anonymous impersonation level.
SECURITY_IDENTIFICATION	Specifies to impersonate the client at the Identification impersonation level.
SECURITY_IMPERSONATION	Specifies to impersonate the client at the Impersonation impersonation level.
SECURITY_DELEGATION	Specifies to impersonate the client at the Delegation impersonation level.
SECURITY_CONTEXT_TRACKING	Specifies that the security tracking mode is dynamic. If this flag is not specified, Security Tracking Mode is static.
SECURITY_EFFECTIVE_ONLY	Specifies that only the enabled aspects of the client’s security context are available to the server. If you do not specify this flag, all aspects of the client’s security context are available. This flag allows the client to limit the groups and privileges that a server can use while impersonating the client.
For more information, see Security.

hTemplateFile

Specifies a handle with GENERIC_READ access to a template file. The template file supplies file attributes and extended attributes for the file being created.

Windows 95: This value must be NULL. If you supply a handle under Windows 95, the call fails and GetLastError returns ERROR_NOT_SUPPORTED.

Return Values

If the function succeeds, the return value is an open handle to the specified file. If the specified file exists before the function call and dwCreationDistribution is CREATE_ALWAYS or OPEN_ALWAYS, a call to GetLastError returns ERROR_ALREADY_EXISTS (even though the function has succeeded). If the file does not exist before the call, GetLastError returns zero.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

Use the CloseHandle function to close an object handle returned by CreateFile.

As noted above, specifying zero for dwDesiredAccess allows an application to query device attributes without actually accessing the device. This type of querying is useful, for example, if an application wants to determine the size of a floppy disk drive and the formats it supports without having a floppy in the drive.

Files

When creating a new file, the CreateFile function performs the following actions:

•	Combines the file attributes and flags specified by dwFlagsAndAttributes with FILE_ATTRIBUTE_ARCHIVE.

•	Sets the file length to zero.

•	Copies the extended attributes supplied by the template file to the new file if the hTemplateFile parameter is specified.

When opening an existing file, CreateFile performs the following actions:

•	Combines the file flags specified by dwFlagsAndAttributes with existing file attributes. CreateFile ignores the file attributes specified by dwFlagsAndAttributes.

•	Sets the file length according to the value of dwCreationDistribution.

•	Ignores the hTemplateFile parameter.

•	Ignores the lpSecurityDescriptor member of the SECURITY_ATTRIBUTES structure if the lpSecurityAttributes parameter is not NULL. The other structure members are used. The bInheritHandle member is the only way to indicate whether the file handle can be inherited.

If you are attempting to create a file on a floppy drive that does not have a floppy disk or a CD-ROM drive that does not have a CD, the system displays a message box asking the user to insert a disk or a CD, respectively. To prevent the system from displaying this message box, call the SetErrorMode function with SEM_FAILCRITICALERRORS.

Pipes

If CreateFile opens the client end of a named pipe, the function uses any instance of the named pipe that is in the listening state. The opening process can duplicate the handle as many times as required but, once opened, the named pipe instance cannot be opened by another client. The access specified when a pipe is opened must be compatible with the access specified in the dwOpenMode parameter of the CreateNamedPipe function. For more information about pipes, see Pipes.

Mailslots

If CreateFile opens the client end of a mailslot, the function returns INVALID_HANDLE_VALUE if the mailslot client attempts to open a local mailslot before the mailslot server has created it with the CreateMailSlot function. For more information about mailslots, see Mailslots.

Communications Resources

The CreateFile function can create a handle to a communications resource, such as the serial port COM1. For communications resources, the dwCreationDistribution parameter must be OPEN_EXISTING, and the hTemplate parameter must be NULL. Read, write, or read-write access can be specified, and the handle can be opened for overlapped I/O. For more information about communications, see Communications.

Disk Devices

Windows NT: You can use the CreateFile function to open a disk drive or a partition on a disk drive. The function returns a handle to the disk device; that handle can be used with the DeviceIOControl function. The following requirements must be met in order for such a call to succeed:

•	The caller must have administrative privileges for the operation to succeed on a hard disk drive.

•	The lpFileName string should be of the form \\.\PHYSICALDRIVEx to open the hard disk x. Hard disk numbers start at zero. For example:

String	Meaning
\\.\PHYSICALDRIVE2	Obtains a handle to the third physical drive on the user’s computer.
•	The lpFileName string should be \\.\x: to open a floppy drive x or a partition x on a hard disk. For example:

String	Meaning
\\.\A:	Obtains a handle to drive A on the user’s computer.
\\.\C:	Obtains a handle to drive C on the user’s computer.
Windows 95: This technique does not work for opening a logical drive. In Windows 95, specifying a string in this form causes CreateFile to return an error.

•	The dwCreationDistribution parameter must have the OPEN_EXISTING value.

•	When opening a floppy disk or a partition on a hard disk, you must set the FILE_SHARE_WRITE flag in the dwShareMode parameter.

Consoles

The CreateFile function can create a handle to console input (CONIN$). If the process has an open handle to it as a result of inheritance or duplication, it can also create a handle to the active screen buffer (CONOUT$). The calling process must be attached to an inherited console or one allocated by the AllocConsole function. For console handles, set the CreateFile parameters as follows:

Parameters	Value
lpFileName	Use the CONIN$ value to specify console input and the CONOUT$ value to specify console output.
	CONIN$ gets a handle to the console’s input buffer, even if the SetStdHandle function redirected the standard input handle. To get the standard input handle, use the GetStdHandle function.
	CONOUT$ gets a handle to the active screen buffer, even if SetStdHandle redirected the standard output handle. To get the standard output handle, use GetStdHandle.
dwDesiredAccess	GENERIC_READ | GENERIC_WRITE is preferred, but either one can limit access.
dwShareMode	If the calling process inherited the console or if a child process should be able to access the console, this parameter must be FILE_SHARE_READ | FILE_SHARE_WRITE.
lpSecurityAttributes	If you want the console to be inherited, the bInheritHandle member of the SECURITY_ATTRIBUTES structure must be TRUE.
dwCreationDistribution	You should specify OPEN_EXISTING when using CreateFile to open the console.
dwFlagsAndAttributes	Ignored.
hTemplateFile	Ignored.
The following list shows the effects of various settings of fwdAccess and lpFileName.

lpFileName	fwdAccess	Result
CON	GENERIC_READ	Opens console for input.
CON	GENERIC_WRITE	Opens console for output.
CON	GENERIC_READ\ GENERIC_WRITE	Windows 95: Causes CreateFile to fail; GetLastError returns ERROR_PATH_NOT_FOUND. Windows NT:  Causes CreateFile to fail; GetLastError returns ERROR_FILE_NOT_FOUND.
Directories

An application cannot create a directory with CreateFile; it must call CreateDirectory or CreateDirectoryEx to create a directory.

Windows NT:

You can obtain a handle to a directory by setting the FILE_FLAG_BACKUP_SEMANTICS flag. A directory handle can be passed to some Win32 functions in place of a file handle.

Some file systems, such as NTFS, support compression for individual files and directories. On volumes formatted for such a file system, a new directory inherits the compression attribute of its parent directory.

See Also

AllocConsole, CloseHandle, ConnectNamedPipe, CreateDirectory, CreateDirectoryEx, CreateNamedPipe, DeviceIOControl, GetDiskFreeSpace, GetOverlappedResult, GetStdHandle, OpenFile, OVERLAPPED, ReadFile, SECURITY_ATTRIBUTES, SetErrorMode, SetStdHandle TransactNamedPipe, VirtualAlloc, WriteFile


CreateFileMapping

The CreateFileMapping function creates a named or unnamed file-mapping object for the specified file.

HANDLE CreateFileMapping(

HANDLE hFile,	// handle to file to map
LPSECURITY_ATTRIBUTES lpFileMappingAttributes,	// optional security attributes
DWORD flProtect,	// protection for mapping object
DWORD dwMaximumSizeHigh,	// high-order 32 bits of object size
DWORD dwMaximumSizeLow,	// low-order 32 bits of object size
LPCTSTR lpName	// name of file-mapping object
);
Parameters

hFile

Identifies the file from which to create a mapping object. The file must be opened with an access mode compatible with the protection flags specified by the flProtect parameter. It is recommended, though not required, that files you intend to map be opened for exclusive access.

If hFile is (HANDLE)0xFFFFFFFF, the calling process must also specify a mapping object size in the dwMaximumSizeHigh and dwMaximumSizeLow parameters. The function creates a file-mapping object of the specified size backed by the operating-system paging file rather than by a named file in the file system. The file-mapping object can be shared through duplication, through inheritance, or by name.

lpFileMappingAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpFileMappingAttributes is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new file-mapping object. If lpFileMappingAttributes is NULL, the file-mapping object gets a default security descriptor.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

flProtect

Specifies the protection desired for the file view, when the file is mapped. This parameter can be one of the following values:

Value	Description
PAGE_READONLY	Gives read-only access to the committed region of pages. An attempt to write to or execute the committed region results in an access violation. The file specified by the hFile parameter must have been created with GENERIC_READ access.
PAGE_READWRITE	Gives read-write access to the committed region of pages. The file specified by hFile must have been created with GENERIC_READ and GENERIC_WRITE access.
PAGE_WRITECOPY	Gives copy on write access to the committed region of pages. The files specified by the hFile parameter must have been created with GENERIC_READ and GENERIC_WRITE access.
In addition, an application can specify certain section attributes by combining (using the bitwise OR operator) one or more of the following section attribute values with one of the preceding page protection values:

Value	Description
SEC_COMMIT	Allocates physical storage in memory or in the paging file on disk for all pages of a section. This is the default setting.
SEC_IMAGE	The file specified for a section’s file mapping is an executable image file. Because the mapping information and file protection are taken from the image file, no other attributes are valid with SEC_IMAGE.
SEC_NOCACHE	All pages of a section are to be set as non-cacheable. This attribute is intended for architectures requiring various locking structures to be in memory that is never fetched into the processor’s. On 80x86 and MIPS machines, using the cache for these structures only slows down the performance as the hardware keeps the caches coherent. Some device drivers require noncached data so that programs can write through to the physical memory. SEC_NOCACHE requires either the SEC_RESERVE or SEC_COMMIT to also be set.
SEC_RESERVE	Reserves all pages of a section without allocating physical storage. The reserved range of pages cannot be used by any other allocation operations until it is released. Reserved pages can be committed in subsequent calls to the VirtualAlloc function. This attribute is valid only if the hFile parameter is (HANDLE)0xFFFFFFFF; that is, a file mapping object backed by the operating sytem paging file.
dwMaximumSizeHigh

Specifies the high-order 32 bits of the maximum size of the file-mapping object.

dwMaximumSizeLow

Specifies the low-order 32 bits of the maximum size of the file-mapping object. If this parameter and dwMaximumSizeHig are zero, the maximum size of the file-mapping object is equal to the current size of the file identified by hFile.

lpName

Points to a null-terminated string specifying the name of the mapping object. The name can contain any character except the backslash character (\).

If this parameter matches the name of an existing named mapping object, the function requests access to the mapping object with the protection specified by flProtect.

If this parameter is NULL, the mapping object is created without a name.

Return Values

If the function succeeds, the return value is a handle to the file-mapping object. If the object existed before the function call, the GetLastError function returns ERROR_ALREADY_EXISTS, and the return value is a valid handle to the existing file-mapping object (with its current size, not the new specified size. If the mapping object did not exist, GetLastError returns zero.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

After a file-mapping object has been created, the size of the file must not exceed the size of the file-mapping object; if it does, not all of the file’s contents will be available for sharing.

If an application specifies a size for the file-mapping object that is larger than the size of the actual named file on disk, the file on disk is grown to match the specified size of the file-mapping object.

The handle that CreateFileMapping returns has full access to the new file-mapping object. It can be used with any function that requires a handle to a file-mapping object. File-mapping objects can be shared either through process creation, through handle duplication, or by name. For information on duplicating handles, see DuplicateHandle. For information on opening a file-mapping object by name, see OpenFileMapping.

Windows 95: File handles that have been used to create file-mapping objects must not be used in subsequent calls to file I/O functions, such as ReadFile and WriteFile. In general, if a file handle has been used in a successful call to the CreateFileMapping function, do not use that handle unless you first close the corresponding file-mapping object.

Creating a file-mapping object creates the potential for mapping a view of the file but does not map the view. The MapViewOfFile and MapViewOfFileEx functions map a view of a file into a process’s address space.

With one important exception, file views derived from a single file-mapping object are coherent, or identical, at a given time. If multiple processes have handles of the same file-mapping object, they see a coherent view of the data when they map a view of the file.

The exception has to do with remote files. Although CreateFileMapping works with remote files, it does not keep them coherent. For example, if two computers both map a file as writable, and both change the same page, each computer will only see its own writes to the page. When the data gets updated on the disk, it is not merged.

A mapped file and a file accessed by means of the input and output (I/O) functions (ReadFile and WriteFile) are not necessarily coherent.

To fully close a file mapping object, an application must unmap all mapped views of the file mapping object by calling UnmapViewOfFile, and close the file mapping object handle by calling CloseHandle. The order in which these functions are called does not matter. The call to UnmapViewOfFile is necessary because mapped views of a file mapping object maintain internal open handles to the object, and a file mapping object will not close until all open handles to it are closed.

Example

To implement a mapping-object creation function that fails if the object already exists, an application can use the following code.

hMap = CreateFileMapping(...);

if (hMap != NULL && GetLastError() == ERROR_ALREADY_EXISTS) {

    CloseHandle(hMap);

    hMap = NULL;

}

return hMap;

See Also

CloseHandle, DuplicateHandle, MapViewOfFile, MapViewOfFileEx, OpenFileMapping, ReadFile, SECURITY_ATTRIBUTES, UnmapViewOfFile, VirtualAlloc, WriteFile


CreateFont

The CreateFont function creates a logical font that has specific characteristics. The logical font can subsequently be selected as the font for any device.

HFONT CreateFont(

int nHeight,	// logical height of font
int nWidth,	// logical average character width
int nEscapement,	// angle of escapement
int nOrientation,	// base-line orientation angle
int fnWeight,	// font weight
DWORD fdwItalic,	// italic attribute flag
DWORD fdwUnderline,	// underline attribute flag
DWORD fdwStrikeOut,	// strikeout attribute flag
DWORD fdwCharSet,	// character set identifier
DWORD fdwOutputPrecision,	// output precision
DWORD fdwClipPrecision,	// clipping precision
DWORD fdwQuality,	// output quality
DWORD fdwPitchAndFamily,	// pitch and family
LPCTSTR lpszFace	// pointer to typeface name string
);
Parameters

nHeight

Specifies the height, in logical units, of the font’s character cell or character. The character height value (also known as the em height) is the character cell height value minus the internal-leading value. The font mapper interprets the value specified in nHeight in the following manner:

Value	Meaning
> 0	The font mapper transforms this value into device units and matches it against the cell height of the available fonts.
0	The font mapper uses a default height value when it searches for a match.
< 0	The font mapper transforms this value into device units and matches its absolute value against the character height of the available fonts.
For all height comparisons, the font mapper looks for the largest font that does not exceed the requested size.

This mapping occurs when the font is used for the first time.

For the MM_TEXT mapping mode, you can use the following formula to specify a height for a font with a specified point size:

nHeight = -MulDiv(PointSize, GetDeviceCaps(hDC, LOGPIXELSY), 72);

nWidth

Specifies the average width, in logical units, of characters in the requested font. If this value is zero, the font mapper chooses a “closest match” value. The “closest match” value is determined by comparing the absolute values of the difference between the current device’s aspect ratio and the digitized aspect ratio of available fonts.

nEscapement

Specifies the angle, in tenths of degrees, between the escapement vector and the x-axis of the device. The escapement vector is parallel to the base line of a row of text.

Windows NT:

When the graphics mode is set to GM_ADVANCED, you can specify the escapement angle of the string independently of the orientation angle of the string’s characters.

When the graphics mode is set to GM_COMPATIBLE, nEscapement specifies both the escapement and orientation. You should set nEscapement and nOrientation to the same value.

Windows 95:

The nEscapement parameter specifies both the escapement and orientation. You should set nEscapement and nOrientation to the same value.

nOrientation

Specifies the angle, in tenths of degrees, between each character’s base line and the x-axis of the device.

fnWeight

Specifies the weight of the font in the range 0 through 1000. For example, 400 is normal and 700 is bold. If this value is zero, a default weight is used.

The following values are defined for convenience:

Value	Weight
FW_DONTCARE	0
FW_THIN	100
FW_EXTRALIGHT	200
FW_ULTRALIGHT	200
FW_LIGHT	300
FW_NORMAL	400
FW_REGULAR	400
FW_MEDIUM	500
FW_SEMIBOLD	600
FW_DEMIBOLD	600
FW_BOLD	700
FW_EXTRABOLD	800
FW_ULTRABOLD	800
FW_HEAVY	900
FW_BLACK	900
fdwItalic

Specifies an italic font if set to TRUE.

fdwUnderline

Specifies an underlined font if set to TRUE.

fdwStrikeOut

Specifies a strikeout font if set to TRUE.

fdwCharSet

Specifies the character set. The following values are predefined:

ANSI_CHARSET
DEFAULT_CHARSET
SYMBOL_CHARSET
SHIFTJIS_CHARSET
GB2312_CHARSET
HANGEUL_CHARSET
CHINESEBIG5_CHARSET
OEM_CHARSET

Windows 95 only:

JOHAB_CHARSET
HEBREW_CHARSET
ARABIC_CHARSET
GREEK_CHARSET
TURKISH_CHARSET
THAI_CHARSET
EASTEUROPE_CHARSET
RUSSIAN_CHARSET
MAC_CHARSET
BALTIC_CHARSET

The OEM_CHARSET value specifies a character set that is operating-system dependent.

You can use the DEFAULT_CHARSET value to allow the name and size of a font to fully describe the logical font. If the specified font name does not exist, a font from any character set can be substituted for the specified font, so you should use DEFAULT_CHARSET sparingly to avoid unexpected results.

Fonts with other character sets may exist in the operating system. If an application uses a font with an unknown character set, it should not attempt to translate or interpret strings that are rendered with that font.

This parameter is important in the font mapping process. To ensure consistent results, specify a specific character set. If you specify a typeface name in the lpszFace parameter, make sure that the fdwCharSet value matches the character set of the typeface specified in lpszFace.

fdwOutputPrecision

Specifies the output precision. The output precision defines how closely the output must match the requested font’s height, width, character orientation, escapement, pitch, and font type. It can be one of the following values:

Value	Meaning
OUT_CHARACTER_PRECIS	Not used.
OUT_DEFAULT_PRECIS	Specifies the default font mapper behavior.
OUT_DEVICE_PRECIS	Instructs the font mapper to choose a Device font when the system contains multiple fonts with the same name.
OUT_OUTLINE_PRECIS	Windows NT: This value instructs the font mapper to choose from TrueType and other outline-based fonts. Windows 95: This value is not used.
OUT_RASTER_PRECIS	Instructs the font mapper to choose a raster font when the system contains multiple fonts with the same name.
OUT_STRING_PRECIS	This value is not used by the font mapper, but it is returned when raster fonts are enumerated.
OUT_STROKE_PRECIS	Windows NT: This value is not used by the font mapper, but it is returned when TrueType, other outline-based fonts, and vector fonts are enumerated.  Windows 95: This value is used to map vector fonts, and is returned when TrueType or vector fonts are enumerated.
OUT_TT_ONLY_PRECIS	Instructs the font mapper to choose from only TrueType fonts. If there are no TrueType fonts installed in the system, the font mapper returns to default behavior.
OUT_TT_PRECIS	Instructs the font mapper to choose a TrueType font when the system contains multiple fonts with the same name.
Applications can use the OUT_DEVICE_PRECIS, OUT_RASTER_PRECIS, and OUT_TT_PRECIS values to control how the font mapper chooses a font when the operating system contains more than one font with a specified name. For example, if an operating system contains a font named Symbol in raster and TrueType form, specifying OUT_TT_PRECIS forces the font mapper to choose the TrueType version. Specifying OUT_TT_ONLY_PRECIS forces the font mapper to choose a TrueType font, even if it must substitute a TrueType font of another name.

fdwClipPrecision

Specifies the clipping precision. The clipping precision defines how to clip characters that are partially outside the clipping region. It can be one or more of the following values:

Value	Meaning
CLIP_DEFAULT_PRECIS	Specifies default clipping behavior.
CLIP_CHARACTER_PRECIS	Not used.
CLIP_STROKE_PRECIS	Not used by the font mapper, but is returned when raster, vector, or TrueType fonts are enumerated. Windows NT: For compatibility, this value is always returned when enumerating fonts.
CLIP_MASK	Not used.
CLIP_EMBEDDED	You must specify this flag to use an embedded read-only font.
CLIP_LH_ANGLES	When this value is used, the rotation for all fonts depends on whether the orientation of the coordinate system is left-handed or right-handed.  If not used, device fonts always rotate counterclockwise, but the rotation of other fonts is dependent on the orientation of the coordinate system. For more information about the orientation of coordinate systems, see the description of the nOrientation parameter
CLIP_TT_ALWAYS	Not used.
fdwQuality

Specifies the output quality. The output quality defines how carefully GDI must attempt to match the logical-font attributes to those of an actual physical font. It can be one of the following values:

Value	Meaning
DEFAULT_QUALITY	Appearance of the font does not matter.
DRAFT_QUALITY	Appearance of the font is less important than when the PROOF_QUALITY value is used. For GDI raster fonts, scaling is enabled, which means that more font sizes are available, but the quality may be lower. Bold, italic, underline, and strikeout fonts are synthesized if necessary.
PROOF_QUALITY	Character quality of the font is more important than exact matching of the logical-font attributes. For GDI raster fonts, scaling is disabled and the font closest in size is chosen. Although the chosen font size may not be mapped exactly when PROOF_QUALITY is used, the quality of the font is high and there is no distortion of appearance. Bold, italic, underline, and strikeout fonts are synthesized if necessary.
fdwPitchAndFamily

Specifies the pitch and family of the font. The two low-order bits specify the pitch of the font and can be one of the following values:

DEFAULT_PITCH
FIXED_PITCH
VARIABLE_PITCH

The four high-order bits specify the font family and can be one of the following values:

Value	Description
FF_DECORATIVE	Novelty fonts. Old English is an example.
FF_DONTCARE	Don’t care or don’t know.
FF_MODERN	Fonts with constant stroke width, with or without serifs. Pica, Elite, and Courier New® are examples.
FF_ROMAN	Fonts with variable stroke width and with serifs. MS® Serif is an example.
FF_SCRIPT	Fonts designed to look like handwriting. Script and Cursive are examples.
FF_SWISS	Fonts with variable stroke width and without serifs. MS Sans Serif is an example.
An application can specify a value for the fdwPitchAndFamily parameter by using the Boolean OR operator to join a pitch constant with a family constant.

Font families describe the look of a font in a general way. They are intended for specifying fonts when the exact typeface requested is not available.

lpszFace

Points to a null-terminated string that specifies the typeface name of the font. The length of this string must not exceed 32 characters, including the null terminator. The EnumFontFamilies function can be used to enumerate the typeface names of all currently available fonts.

If lpszFace is NULL or points to an empty string, GDI uses the first font that matches the other specified attributes.

Return Values

If the function succeeds, the return value is a handle to a logical font.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

When you no longer need the font, call the DeleteObject function to delete it.

To help protect the copyrights of vendors who provide fonts for Windows operating systems, applications should always report the exact name of a selected font. Because available fonts can vary from system to system, do not assume that the selected font is always the same as the requested font. For example, if you request a font named “Palatino,” but no such font is available on the system, the font mapper will substitute a font that has similar attributes but a different name. Always report the name of the selected font to the user.

See Also

DeleteObject, SelectObject, EnumFontFamilies


CreateFontIndirect

The CreateFontIndirect function creates a logical font that has the characteristics specified in the specified structure. The font can subsequently be selected as the current font for any device context.

HFONT CreateFontIndirect(

CONST LOGFONT *lplf	// pointer to logical font structure
);
Parameters

lplf

Points to a LOGFONT structure that defines the characteristics of the logical font.

Return Values

If the function succeeds, the return value is a handle to a logical font.

If the function fails, the return value is NULL.

Remarks

The CreateFontIndirect function creates a logical font with the characteristics specified in the LOGFONT structure. When this font is selected by using the SelectObject function, GDI’s font mapper attempts to match the logical font with an existing physical font. If it fails to find an exact match, it provides an alternative whose characteristics match as many of the requested characteristics as possible.

When you no longer need the font, call the DeleteObject function to delete it.

See Also

DeleteObject, LOGFONT, SelectObject


CreateHalftonePalette

The CreateHalftonePalette function creates a halftone palette for the specified device context.

HPALETTE CreateHalftonePalette(

HDC hdc	// handle to device context
);
Parameters

hdc

Identifies the device context.

Return Values

If the function succeeds, the return value identifies a logical halftone palette.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

An application should create a halftone palette when the stretching mode of a device context is set to HALFTONE. The logical halftone palette returned by CreateHalftonePalette should then be selected and realized into the device context before the StretchBlt or StretchDIBits function is called.

When you no longer need the palette, call the DeleteObject function to delete it.

See Also

DeleteObject, RealizePalette, SelectPalette, SetStretchBltMode, StretchDIBits, StretchBlt


CreateHatchBrush

The CreateHatchBrush function creates a logical brush that has the specified hatch pattern and color.

HBRUSH CreateHatchBrush(

int fnStyle,	// hatch style
COLORREF clrref	// color value
);
Parameters

fnStyle

Specifies the hatch style of the brush. This parameter can be any one of the following values:

Value	Meaning
HS_BDIAGONAL	45-degree downward left-to-right hatch
HS_CROSS	Horizontal and vertical crosshatch
HS_DIAGCROSS	45-degree crosshatch
HS_FDIAGONAL	45-degree upward left-to-right hatch
HS_HORIZONTAL	Horizontal hatch
HS_VERTICAL	Vertical hatch
clrref

Specifies the foreground color of the brush that is used for the hatches.

Return Values

If the function succeeds, the return value identifies a logical brush.

If the function fails, the return value is NULL.

Remarks

A brush is a bitmap that Windows uses to paint the interiors of filled shapes.

After an application creates a brush by calling CreateHatchBrush, it can select that brush into any device context by calling the SelectObject function.

If an application uses a hatch brush to fill the backgrounds of both a parent and a child window with matching color, it may be necessary to set the brush origin before painting the background of the child window. You can do this by having your application call the SetBrushOrgEx function. Your application can retrieve the current brush origin by calling the GetBrushOrgEx function.

When you no longer need the brush, call the DeleteObject function to delete it.

See Also

CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreatePatternBrush, CreateSolidBrush, DeleteObject, GetBrushOrgEx, SelectObject, SetBrushOrgEx


CreateIC

The CreateIC function creates an information context for the specified device. The information context provides a fast way to get information about the device without creating a device context.

HDC CreateIC(

LPCTSTR lpszDriver,	// pointer to string specifying driver name
LPCTSTR lpszDevice,	// pointer to string specifying device name
LPCTSTR lpszOutput,	// pointer to string specifying port or file name
CONST DEVMODE *lpdvmInit	// pointer to optional initialization data
);
Parameters

lpszDriver

Points to a null-terminated character string that specifies the name of the device driver (for example, “Epson”).

lpszDevice

Points to a null-terminated character string that specifies the name of the specific output device being used, as shown by the Print Manager (for example, “Epson FX-80”). It is not the printer model name. The lpszDevice parameter must be used.

lpszOutput

Points to a null-terminated character string that specifies the file or device name for the physical output medium (file or output port). This parameter is ignored; it is present only to keep the function prototype identical with Windows version 3.1.

lpdvmInit

Points to a DEVMODE structure containing device-specific initialization data for the device driver. The DocumentProperties function retrieves this structure filled in for a specified device. The lpdvmInit parameter must be NULL if the device driver is to use the default initialization (if any) specified by the user.

Return Values

If the function succeeds, the return value is the handle to an information context.

If the function fails, the return value is NULL.

Remarks

An error occurs if an application calls a GDI drawing function and supplies a handle identifying an information context.

When you no longer need the information device context, call the DeleteDC function to delete it.

See Also

DeleteDC, DocumentProperties, DEVMODE, GetDeviceCaps


CreateIcon

The CreateIcon function creates an icon that has the specified size, colors, and bit patterns.

HICON CreateIcon(

HINSTANCE hInstance,	// handle to application instance
int nWidth,	// icon width
int nHeight,	// icon height
BYTE cPlanes,	// number of planes in XOR bitmask
BYTE cBitsPixel,	// number of bits per pixel in XOR bitmask
CONST BYTE *lpbANDbits,	// pointer to AND bitmask array
CONST BYTE *lpbXORbits	// pointer to XOR bitmask array
);
Parameters

hInstance

Identifies the instance of the module creating the icon.

nWidth

Specifies the width, in pixels, of the icon.

nHeight

Specifies the height, in pixels, of the icon.

cPlanes

Specifies the number of planes in the XOR bitmask of the icon.

cBitsPixel

Specifies the number of bits per pixel in the XOR bitmask of the icon.

lpbANDbits

Points to an array of bytes that contains the bit values for the AND bitmask of the icon. This bitmask describes a monochrome bitmap.

lpbXORbits

Points to an array of bytes that contains the bit values for the XOR bitmask of the icon. This bitmask describes a monochrome or device-dependent color bitmap.

Return Values

If the function succeeds, the return value is the handle to an icon.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The nWidth and nHeight parameters must specify a width and height supported by the current display driver, because the system cannot create icons of other sizes. To determine the width and height supported by the display driver, use the GetSystemMetrics function, specifying the SM_CXICON or SM_CYICON value.

CreateIcon applies the following truth table to the AND and XOR bitmasks:

AND bitmask	XOR bitmask	Display
0	0	Black
0	1	White
1	0	Screen
1	1	Reverse screen
See Also

GetSystemMetrics


CreateIconFromResource

The CreateIconFromResource function creates an icon or cursor from resource bits describing the icon.

HICON CreateIconFromResource(

PBYTE presbits,	// pointer to icon or cursor bits
DWORD dwResSize,	// number of bytes in bit buffer
BOOL fIcon,	// icon or cursor flag
DWORD dwVer	// Windows format version
);
Parameters

presbits

Points to a buffer containing the icon or cursor resource bits. These bits are typically loaded by calls to the LookupIconIdFromDirectory (in Windows 95 you can also call LookupIconIdFromDirectoryEx) and LoadResource functions.

dwResSize

Specifies the size, in bytes, of the set of bits pointed to by the presbits parameter.

fIcon

Specifies whether an icon or a cursor is to be created. If this parameter is TRUE, an icon is to be created. If it is FALSE, a cursor is to be created.

dwVer

Specifies the version number of the icon or cursor format for the resource bits pointed to by the presbits parameter. This parameter can be one of the following values:

Format	dwVer
Windows 2.x	0x00020000
Windows 3.x	0x00030000
All Microsoft Win32-based applications use the Windows 3.x format for icons and cursors.

Return Values

If the function succeeds, the return value is the handle to the icon or cursor.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The CreateIconFromResource, CreateIconIndirect, GetIconInfo, and LookupIconIdFromDirectory functions (and in Windows 95 the CreateIconFromResourceEx and LookupIconIdFromDirectoryEx functions) allow shell applications and icon browsers to examine and use resources from throughout the system.

See Also

CreateIconFromResource, CreateIconFromResourceEx, CreateIconIndirect, GetIconInfo, LoadResource, LookupIconIdFromDirectory, LookupIconIdFromDirectoryEx


CreateIconFromResourceEx [Now Supported on Windows NT]
CreateIconFromResourceEx

[Now Supported on Windows NT]

The CreateIconFromResourceEx function creates an icon or cursor from resource bits describing the icon.

HICON CreateIconFromResourceEx(

PBYTE pbIconBits,	// pointer to icon or cursor bits
DWORD cbIconBits,	// number of bytes in bit buffer
BOOL fIcon,	// icon or cursor flag
DWORD dwVersion,	// Windows format version
int cxDesired,	// desired width of icon or cursor
int cyDesired,	// desired height of icon or cursor
UINT uFlags	// load resource flags
);
Parameters

pbIconBits

Points to a buffer containing the icon or cursor resource bits. These bits are typically loaded by calls to the LookupIconIdFromDirectoryEx and LoadResource functions.

cbIconBits

Specifies the size, in bytes, of the set of bits pointed to by the pbIconBits parameter.

fIcon

Specifies whether an icon or a cursor is to be created. If this parameter is TRUE, an icon is to be created. If it is FALSE, a cursor is to be created.

dwVersion

Specifies the version number of the icon or cursor format for the resource bits pointed to by the pbIconBits parameter. This parameter can be one of the following values:

Format	dwVersion
Windows 2.x	0x00020000
Windows 3.x	0x00030000
All Win32-based applications use the Windows 3.x format for icons and cursors.

cxDesired

Specifies the desired width, in pixels, of the icon or cursor. If this parameter is zero, the function uses the SM_CXICON or SM_CXCURSOR system metric value to set the width.

cyDesired

Specifies the desired height, in pixels, of the icon or cursor. If this parameter is zero, the function uses the SM_CYICON or SM_CYCURSOR system metric value to set the height.

uFlags

Specifies a combination of the following values:

Value	Meaning
LR_DEFAULTCOLOR	Uses the default color format.
LR_MONOCHROME	Creates a monochrome icon or cursor.
Return Values

If the function succeeds, the return value is the handle to the icon or cursor.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The CreateIconFromResourceEx, CreateIconFromResource, CreateIconIndirect, GetIconInfo, and LookupIconIdFromDirectoryEx functions allow shell applications and icon browsers to examine and use resources from throughout the system.

See Also

BITMAPINFOHEADER, CreateIconFromResource, CreateIconIndirect, GetIconInfo, LoadResource, LookupIconIdFromDirectoryEx


CreateIconIndirect

The CreateIconIndirect function creates an icon or cursor from an ICONINFO structure.

HICON CreateIconIndirect(

PICONINFO piconinfo	// pointer to icon information structure
);
Parameters

piconinfo

Points to an ICONINFO structure the function uses to create the icon or cursor.

Return Values

If the function succeeds, the return value is the handle to the icon or cursor that is created.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The system copies the bitmaps in the ICONINFO structure before creating the icon or cursor. The application must continue to manage the original bitmaps and delete them when they are no longer necessary.

When you are finished using the icon, destroy it using the DestroyIcon function.

See Also

DestroyIcon, ICONINFO


CreateIoCompletionPort

The CreateIoCompletionPort function can associate an instance of an opened file with a newly created or an existing input/output completion port; or it can create an input/output completion port without associating it with a file.

Associating an instance of an opened file with an input/output completion port lets an application receive notification of the completion of asynchronous input/output operations involving that file.

HANDLE CreateIoCompletionPort (

HANDLE FileHandle,	// file handle to associate with I/O completion port
HANDLE ExistingCompletionPort,	// optional handle to existing I/O completion port
DWORD CompletionKey,	// per-file completion key for I/O completion packets
DWORD NumberOfConcurrentThreads	// number of threads allowed to execute concurrently
);
Parameters

FileHandle

Handle to a file opened for overlapped input/output completion. You must specify the FILE_FLAG_OVERLAPPED flag when using the CreateFile function to obtain such a handle.

Once an instance of an open file is associated with an I/O completion port, it cannot be used in ReadFileEx or WriteFileEx operations.

It is best not to share such an associated file through either handle inheritance or a call to the DuplicateHandle function. Input/output operations done with such duplicate handles will generate completion notifications.

If FileHandle specifies INVALID_HANDLE_VALUE, CreateIoCompletionPort creates an input/output completion port without associating it with a file. In this case, the ExistingCompletionPort parameter must be NULL, and the CompletionKey parameter is ignored.

ExistingCompletionPort

Handle to an existing I/O completion port. This parameter can be NULL.

If this parameter is not NULL, it specifies an existing completion port that the function is to associate with the file specified by FileHandle.

If this parameter is NULL, the function creates a new input/output completion port that it associates with the specified file.

CompletionKey

Specifies a per-file completion key that will be included in every input/output completion packet for the specified file.

NumberOfConcurrentThreads

Specifies the number of threads that are allowed to execute concurrently.

If one of the threads enters a wait state, then another thread is allowed to proceed. There may be brief periods when the number of active threads exceeds the specified value, but the operating system quickly brings the number back down.

A value of 0 for this parameter tells the operating system to allow as many threads as there are processors in the system.

Return Values

If the function succeeds, the return value is the handle to the I/O completion port that is associated with the specified file. This return value is not NULL.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The Win32 I/O system can be instructed to send I/O completion notification packets to input/output completion ports, where they are queued up. The CreateIoCompletionPort function provides a mechanism for this.

When you perform an input/output operation with a file handle that has an associated input/output completion port, the I/O system sends a completion notification packet to the completion port when the I/O operation completes. The I/O completion port places the completion packet in a first-in-first-out queue. Use the GetQueuedCompletionStatus function to retrieve these queued I/O completion packets.

Threads in the same process can use the PostQueuedCompletionStatus function to place I/O completion notification packets in a completion port’s queue. This allows you to use the port to receive communications from other threads of the process, in addition to receiving I/O completion notification packets from the Win32 I/O system.

See Also

GetQueuedCompletionStatus, PostQueuedCompletionStatus


CreateMailslot

The CreateMailslot function creates a mailslot with the specified name and returns a handle that a mailslot server can use to perform operations on the mailslot. The mailslot is local to the computer that creates it. An error occurs if a mailslot with the specified name already exists.

HANDLE CreateMailslot(

LPCTSTR lpName,	// pointer to string for mailslot name
DWORD nMaxMessageSize,	// maximum message size
DWORD lReadTimeout,	// milliseconds before read time-out
LPSECURITY_ATTRIBUTES lpSecurityAttributes	// pointer to security structure
);
Parameters

lpName

Points to a null-terminated string specifying the name of the mailslot. This name must have the following form:

\\.\mailslot\[path]name

The name field must be unique. The name may include multiple levels of pseudodirectories separated by backslashes. For example, both \\.\mailslot\example_mailslot_name and \\.\mailslot\abc\def\ghi are valid names.

nMaxMessageSize

Specifies the maximum size, in bytes, of a single message that can be written to the mailslots. To specify that the message can be of any size, set this value to zero.

lReadTimeout

Specifies the amount of time, in milliseconds, a read operation can wait for a message to be written to the mailslot before a time-out occurs. The following values have special meanings:

Value	Meaning
0	Returns immediately if no message is present. (The system does not treat an immediate return as an error.)
MAILSLOT_WAIT_FOREVER	Waits forever for a message.
This time-out value applies to all subsequent read operations and all inherited mailslot handles.

lpSecurityAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new mailslot. If lpSecurityAttributes is NULL, the mailslot gets a default security descriptor.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

Return Values

If the function succeeds, the return value is a handle to the mailslot, for use in server mailslot operations.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

The mailslot exists until one of the following conditions is true:

•	The last (possibly inherited or duplicated) handle to it is closed using the CloseHandle function.

•	The process owning the last (possibly inherited or duplicated) handle exits.

Both Windows NT and Windows 95 use the second method to destroy mailslots.

To write a message to a mailslot, a process uses the CreateFile function, specifying the mailslot name by using one of the following formats:

Format	Usage
\\.\mailslot\name	Retrieves a client handle to a local mailslot.
\\computername\mailslot\name	Retrieves a client handle to a remote mailslot.
\\domainname\mailslot\name	Retrieves a client handle to all mailslots with the specified name in the specified domain.
\\*\mailslot\name	Retrieves a client handle to all mailslots with the specified name in the system’s primary domain.
If CreateFile specifies a domain or uses the asterisk format to specify the system’s primary domain, the application cannot write more than 400 bytes at a time to the mailslot. If the application attempts to do so, the WriteFile function fails and GetLastError returns ERROR_BAD_NETPATH.

An application must specify the FILE_SHARE_READ flag when using CreateFile to retrieve a client handle to a mailslot.

See Also

CloseHandle, CreateFile, GetMailslotInfo, SECURITY_ATTRIBUTES, SetMailslotInfo, WriteFile


CreateMappedBitmap

The CreateMappedBitmap function creates a bitmap for use in a toolbar.

HBITMAP CreateMappedBitmap(

HINSTANCE hInstance,
int idBitmap,
UINT wFlags,
LPCOLORMAP lpColorMap,
int iNumMaps
);
Parameters

hInstance

Handle to the module instance with the executable file that contains the bitmap resource.

idBitmap

Resource identifier of the bitmap resource.

wFlags

Bitmap flag. This parameter can be zero or the following value:

Value	Meaning
CMB_MASKED	Uses a bitmap as a mask.
lpColorMap

Pointer to a COLORMAP structure that contains the color information needed to map the bitmaps. If this parameter is NULL, the function uses the default color map.

iNumMaps

Number of color maps pointed to by lpColorMap.

Return Values

If the function succeeds, the return value is the handle to the bitmap.

If the function fails, the return value is NULL.

Remarks

The function creates a new bitmap using the bitmap data and colors specified by the specified bitmap resource and the color mapping information.

See Also

COLORMAP


CreateMDIWindow

The CreateMDIWindow function creates a multiple document interface (MDI) child window.

HWND CreateMDIWindow(

LPTSTR lpClassName,	// pointer to registered child class name
LPTSTR lpWindowName,	// pointer to window name
DWORD dwStyle,	// window style
int X,	// horizontal position of window
int Y,	// vertical position of window
int nWidth,	// width of window
int nHeight,	// height of window
HWND hWndParent,	// handle to parent window (MDI client)
HINSTANCE hInstance,	// handle to application instance
LPARAM lParam	// application-defined value
);
Parameters

lpClassName

Points to a null-terminated string specifying the window class of the MDI child window. The class name must have been registered by a call to the RegisterClass function.

lpWindowName

Points to a null-terminated string that represents the window name. Windows displays the name in the title bar of the child window.

dwStyle

Specifies the style of the MDI child window. If the MDI client window is created with the MDIS_ALLCHILDSTYLES window style, this parameter can be any combination of the window styles listed in the description of the CreateWindow function. Otherwise, this parameter can be one or more of the following values:

Value	Meaning
WS_MINIMIZE	Creates an MDI child window that is initially minimized.
WS_MAXIMIZE	Creates an MDI child window that is initially maximized.
WS_HSCROLL	Creates an MDI child window that has a horizontal scroll bar.
WS_VSCROLL	Creates an MDI child window that has a vertical scroll bar.
X

Specifies the initial horizontal position, in client coordinates, of the MDI child window. If this parameter is CW_USEDEFAULT, the MDI child window is assigned the default horizontal position.

Y

Specifies the initial vertical position, in client coordinates, of the MDI child window. If this parameter is CW_USEDEFAULT, the MDI child window is assigned the default vertical position.

nWidth

Specifies the initial width, in device units, of the MDI child window. If this parameter is CW_USEDEFAULT, the MDI child window is assigned the default width.

nHeight

Specifies the initial height, in device units, of the MDI child window. If this parameter is set to CW_USEDEFAULT, the MDI child window is assigned the default height.

hWndParent

Identifies the MDI client window that will be the parent of the new MDI child window.

hInstance

Identifies the instance of the application creating the MDI child window.

lParam

Specifies an application-defined value.

Return Values

If the function succeeds, the return value is the handle to the created window.

If the function fails, the return value is NULL.

Remarks

Using the CreateMDIWindow function is similar to sending the WM_MDICREATE message to an MDI client window, except that the function can create an MDI child window in a different thread, while the message cannot.

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

CreateWindow, RegisterClass, WM_MDICREATE


CreateMenu

The CreateMenu function creates a menu. The menu is initially empty, but it can be filled with menu items by using the InsertMenuItem, AppendMenu, and InsertMenu functions.

HMENU CreateMenu(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the handle to the newly created menu.

If the function fails, the return value is NULL.

Remarks

Resources associated with a menu that is assigned to a window are freed automatically. If the menu is not assigned to a window, an application must free system resources associated with the menu before closing. An application frees menu resources by calling the DestroyMenu function.

Windows 95: The system can support a maximum of 16,364 menu handles.

See Also

AppendMenu, CreatePopupMenu, DestroyMenu, InsertMenu, SetMenu, InsertMenuItem


CreateMetaFile

The CreateMetaFile function creates a device context for a Windows-format metafile.

This function is provided for compatibility with earlier 16-bit versions of Microsoft Windows. Win32-based applications should use the CreateEnhMetaFile function.

HDC CreateMetaFile(

LPCTSTR lpszFile	// pointer to filename string
);
Parameters

lpszFile

Points to the filename for the Windows-format metafile to be created. If this parameter is NULL, the Windows-format metafile is memory based and its contents are lost when it is deleted by using the DeleteMetaFile function.

Return Values

If the function succeeds, the return value is a handle to the device context for the Windows-format metafile.

If the function fails, the return value is NULL.

Remarks

Where text arguments must use Unicode characters, use the CreateMetaFile function as a wide-character function. Where text arguments must use characters from the Windows 3.x character set, use this function as an ANSI function.

CreateMetaFile is a Windows-format metafile function. This function supports only applications designed for Microsoft Windows version 3.x. It does not record or play back the new Win32 graphics device interface (GDI) functions such as PolyBezier.

The device context created by this function can be used to record GDI output functions in a Windows-format metafile. It cannot be used with GDI query functions such as GetTextColor. When the device context is used with a GDI output function, the return value of that function becomes TRUE if the function is recorded and FALSE otherwise. When an object is selected by using the SelectObject function, only a copy of the object is recorded. The object still belongs to the application.

To create a scalable Windows-format metafile, record the graphics output in the MM_ANISOTROPIC mapping mode. The file cannot contain functions that modify the viewport origin and extents, nor can it contain device-dependent functions such as the SelectClipRgn function. Once created, the Windows metafile can be scaled and rendered to any output device-format by defining the viewport origin and extents of the picture before playing it.

See Also

CloseMetaFile, CreateEnhMetaFile, DeleteMetaFile, GetTextColor, PolyBezier, SelectClipRgn, SelectObject


CreateMutex

The CreateMutex function creates a named or unnamed mutex object.

HANDLE CreateMutex(

LPSECURITY_ATTRIBUTES lpMutexAttributes,	// pointer to security attributes
BOOL bInitialOwner,	// flag for initial ownership
LPCTSTR lpName	// pointer to mutex-object name
);
Parameters

lpMutexAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpMutexAttributes is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new mutex. If lpMutexAttributes is NULL, the mutex gets a default security descriptor.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

bInitialOwner

Specifies the initial owner of the mutex object. If TRUE, the calling thread requests immediate ownership of the mutex object. Otherwise, the mutex is not owned.

lpName

Points to a null-terminated string specifying the name of the mutex object. The name is limited to MAX_PATH characters and can contain any character except the backslash path-separator character (\). Name comparison is case sensitive.

If lpName matches the name of an existing named mutex object, this function requests MUTEX_ALL_ACCESS access to the existing object. In this case, the bInitialOwner parameter is ignored because it has already been set by the creating process. If the lpMutexAttributes parameter is not NULL, it determines whether the handle can be inherited, but its security-descriptor member is ignored.

If lpName is NULL, the mutex object is created without a name.

If lpName matches the name of an existing event, semaphore, or file-mapping object, the function fails and the GetLastError function returns ERROR_INVALID_HANDLE. This occurs because event, mutex, semaphore, and file-mapping objects share the same name space.

Return Values

If the function succeeds, the return value is a handle to the mutex object. If the named mutex object existed before the function call, the GetLastError function returns ERROR_ALREADY_EXISTS. Otherwise, GetLastError returns zero.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The handle returned by CreateMutex has MUTEX_ALL_ACCESS access to the new mutex object and can be used in any function that requires a handle to a mutex object.

Any thread of the calling process can specify the mutex-object handle in a call to one of the wait functions. The single-object wait functions return when the state of the specified object is signaled. The multiple-object wait functions can be instructed to return either when any one or when all of the specified objects are signaled. When a wait function returns, the waiting thread is released to continue its execution.

The state of a mutex object is signaled when it is not owned by any thread. The creating thread can use the bInitialOwner flag to request immediate ownership of the mutex. Otherwise, a thread must use one of the wait functions to request ownership. When the mutex’s state is signaled, one waiting thread is granted ownership, the mutex’s state changes to nonsignaled, and the wait function returns. Only one thread can own a mutex at any given time. The owning thread uses the ReleaseMutex function to release its ownership.

The thread that owns a mutex can specify the same mutex in repeated wait function calls without blocking its execution. Typically, you would not wait repeatedly for the same mutex, but this mechanism prevents a thread from deadlocking itself while waiting for a mutex that it already owns. However, to release its ownership, the thread must call ReleaseMutex once for each time that the mutex satisfied a wait.

Two or more processes can call CreateMutex to create the same named mutex. The first process actually creates the mutex, and subsequent processes open a handle to the existing mutex. This enables multiple processes to get handles of the same mutex, while relieving the user of the responsibility of ensuring that the creating process is started first. When using this technique, you should set the bInitialOwner flag to FALSE; otherwise, it can be difficult to be certain which process has initial ownership.

Multiple processes can have handles of the same mutex object, enabling use of the object for interprocess synchronization. The following object-sharing mechanisms are available:

•	A child process created by the CreateProcess function can inherit a handle to a mutex object if the lpMutexAttributes parameter of CreateMutex enabled inheritance.

•	A process can specify the mutex-object handle in a call to the DuplicateHandle function to create a duplicate handle that can be used by another process.

•	A process can specify the name of a mutex object in a call to the OpenMutex or CreateMutex function.

Use the CloseHandle function to close the handle. The system closes the handle automatically when the process terminates. The mutex object is destroyed when its last handle has been closed.

See Also

CloseHandle, CreateProcess, DuplicateHandle, OpenMutex, ReleaseMutex, SECURITY_ATTRIBUTES


CreateNamedPipe

The CreateNamedPipe function creates an instance of a named pipe and returns a handle for subsequent pipe operations. A named pipe server process uses this function either to create the first instance of a specific named pipe and establish its basic attributes or to create a new instance of an existing named pipe.

HANDLE CreateNamedPipe(

LPCTSTR lpName,	// pointer to pipe name
DWORD dwOpenMode,	// pipe open mode
DWORD dwPipeMode,	// pipe-specific modes
DWORD nMaxInstances,	// maximum number of instances
DWORD nOutBufferSize,	// output buffer size, in bytes
DWORD nInBufferSize,	// input buffer size, in bytes
DWORD nDefaultTimeOut,	// time-out time, in milliseconds
LPSECURITY_ATTRIBUTES lpSecurityAttributes	// pointer to security attributes structure
);
Parameters

lpName

Points to the null-terminated string that uniquely identifies the pipe. The string must have the following form:

\\.\pipe\pipename

The pipename part of the name can include any character other than a backslash, including numbers and special characters. The entire pipe name string can be up to 256 characters long. Pipe names are not case sensitive.

dwOpenMode

Specifies the pipe access mode, the overlapped mode, the write-through mode, and the security access mode of the pipe handle.

This parameter must specify one of the following pipe access mode flags. The same mode must be specified for each instance of the pipe:

Mode	Description
PIPE_ACCESS_DUPLEX	The pipe is bidirectional; both server and client processes can read from and write to the pipe. This mode gives the server the equivalent of GENERIC_READ | GENERIC_WRITE access to the pipe. The client can specify GENERIC_READ or GENERIC_WRITE, or both, when it connects to the pipe using the CreateFile function.
PIPE_ACCESS_INBOUND	The flow of data in the pipe goes from client to server only. This mode gives the server the equivalent of GENERIC_READ access to the pipe. The client must specify GENERIC_WRITE access when connecting to the pipe.
PIPE_ACCESS_OUTBOUND	The flow of data in the pipe goes from server to client only. This mode gives the server the equivalent of GENERIC_WRITE access to the pipe. The client must specify GENERIC_READ access when connecting to the pipe.
This parameter can also include either or both of the following flags, which enable write-through mode and overlapped mode. These modes can be different for different instances of the same pipe.

Mode	Description
FILE_FLAG_WRITE_THROUGH
	Write-through mode is enabled. This mode affects only write operations on byte-type pipes and, then, only when the client and server processes are on different computers. If this mode is enabled, functions writing to a named pipe do not return until the data written is transmitted across the network and is in the pipe’s buffer on the remote computer. If this mode is not enabled, the system enhances the efficiency of network operations by buffering data until a minimum number of bytes accumulate or until a maximum time elapses.
FILE_FLAG_OVERLAPPED
	Overlapped mode is enabled. If this mode is enabled, functions performing read, write, and connect operations that may take a significant time to be completed can return immediately. This mode enables the thread that started the operation to perform other operations while the time-consuming operation executes in the background. For example, in overlapped mode, a thread can handle simultaneous input and output (I/O) operations on multiple instances of a pipe or perform simultaneous read and write operations on the same pipe handle. If overlapped mode is not enabled, functions performing read, write, and connect operations on the pipe handle do not return until the operation is finished. The ReadFileEx and WriteFileEx functions can only be used with a pipe handle in overlapped mode. The ReadFile, WriteFile, ConnectNamedPipe, and TransactNamedPipe functions can execute either synchronously or as overlapped operations.
This parameter can include any combination of the following security access mode flags. These modes can be different for different instances of the same pipe. They can be specified without concern for what other dwOpenMode modes have been specified.

Mode	Description
WRITE_DAC	The caller will have write access to the named pipe’s discretionary access control list (ACL).
WRITE_OWNER	The caller will have write access to the named pipe’s owner.
ACCESS_SYSTEM_SECURITY	The caller will have write access to the named pipe’s system ACL.
dwPipeMode

Specifies the type, read, and wait modes of the pipe handle.

One of the following type mode flags can be specified. The same type mode must be specified for each instance of the pipe. If you specify zero, the parameter defaults to byte-type mode.

Mode	Description
PIPE_TYPE_BYTE	Data is written to the pipe as a stream of bytes. This mode cannot be used with PIPE_READMODE_MESSAGE.
PIPE_TYPE_MESSAGE	Data is written to the pipe as a stream of messages. This mode can be used with either PIPE_READMODE_MESSAGE or PIPE_READMODE_BYTE.
One of the following read mode flags can be specified. Different instances of the same pipe can specify different read modes. If you specify zero, the parameter defaults to byte-read mode.

Mode	Description
PIPE_READMODE_BYTE	Data is read from the pipe as a stream of bytes. This mode can be used with either PIPE_TYPE_MESSAGE or PIPE_TYPE_BYTE.
PIPE_READMODE_MESSAGE	Data is read from the pipe as a stream of messages. This mode can be only used if PIPE_TYPE_MESSAGE is also specified.
One of the following wait mode flags can be specified. Different instances of the same pipe can specify different wait modes. If you specify zero, the parameter defaults to blocking mode.

Mode	Description
PIPE_WAIT	Blocking mode is enabled. When the pipe handle is specified in the ReadFile, WriteFile, or ConnectNamedPipe function, the operations are not completed until there is data to read, all data is written, or a client is connected. Use of this mode can mean waiting indefinitely in some situations for a client process to perform an action.
PIPE_NOWAIT	Nonblocking mode is enabled. In this mode, ReadFile, WriteFile, and ConnectNamedPipe always return immediately. Note that nonblocking mode is supported for compatibility with Microsoft LAN Manager version 2.0 and should not be used to achieve asynchronous I/O with named pipes.
nMaxInstances

Specifies the maximum number of instances that can be created for this pipe. The same number must be specified for all instances. Acceptable values are in the range 1 through PIPE_UNLIMITED_INSTANCES. If this parameter is PIPE_UNLIMITED_INSTANCES, the number of pipe instances that can be created is limited only by the availability of system resources.

nOutBufferSize

Specifies the number of bytes to reserve for the output buffer. For a discussion on sizing named pipe buffers, see the following Remarks section.

nInBufferSize

Specifies the number of bytes to reserve for the input buffer. For a discussion on sizing named pipe buffers, see the following Remarks section.

nDefaultTimeOut

Specifies the default time-out value, in milliseconds, if the WaitNamedPipe function specifies NMPWAIT_USE_DEFAULT_WAIT. Each instance of a named pipe must specify the same value.

lpSecurityAttributes

Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new named pipe and determines whether child processes can inherit the returned handle. If lpSecurityAttributes is NULL, the named pipe gets a default security descriptor and the handle cannot be inherited.

Return Values

If the function succeeds, the return value is a handle to the server end of a named pipe instance.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError. The return value is ERROR_INVALID_PARAMETER if nMaxInstances is greater than PIPE_UNLIMITED_INSTANCES.

Remarks

To create an instance of a named pipe by using CreateNamedPipe, the user must have FILE_CREATE_PIPE_INSTANCE access to the named pipe object. If a new named pipe is being created, the access control list (ACL) from the security attributes parameter defines the discretionary access control for the named pipe.

All instances of a named pipe must specify the same pipe type (byte-type or message-type), pipe access (duplex, inbound, or outbound), instance count, and time-out value. If different values are used, this function fails and GetLastError returns ERROR_ACCESS_DENIED.

The input and output buffer sizes are advisory. The actual buffer size reserved for each end of the named pipe is either the system default, the system minimum or maximum, or the specified size rounded up to the next allocation boundary.

An instance of a named pipe is always deleted when the last handle to the instance of the named pipe is closed.

See Also

ConnectNamedPipe, CreateFile, ReadFile, ReadFileEx, SECURITY_ATTRIBUTES, TransactNamedPipe, WaitNamedPipe, WriteFile, WriteFileEx


CreatePalette

The CreatePalette function creates a logical color palette.

HPALETTE CreatePalette(

CONST LOGPALETTE *lplgpl	// pointer to logical color palette
);
Parameters

lplgpl

Points to a LOGPALETTE structure that contains information about the colors in the logical palette.

Return Values

If the function succeeds, the return value is a handle that identifies a logical palette.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

Once an application creates a logical palette, it can select that palette into a device context by calling the SelectPalette function. A palette selected into a device context can be realized by calling the RealizePalette function.

When you no longer need the palette, call the DeleteObject function to delete it.

See Also

DeleteObject, GetDeviceCaps, LOGPALETTE, RealizePalette, SelectPalette


CreatePatternBrush

The CreatePatternBrush function creates a logical brush with the specified bitmap pattern. The bitmap cannot be a DIB section bitmap, which is created by the CreateDIBSection function.

HBRUSH CreatePatternBrush(

HBITMAP hbmp	// handle to bitmap
);
Parameters

hbmp

Identifies the bitmap to be used to create the logical brush.

Windows 95: Creating brushes from bitmaps or DIBs larger than 8x8 pixels is not supported. If a larger bitmap is specified, only a portion of the bitmap is used.

Return Values

If the function succeeds, the return value identifies a logical brush.

If the function fails, the return value is NULL.

Remarks

A pattern brush is a bitmap that Windows uses to paint the interiors of filled shapes.

After an application creates a brush by calling CreatePatternBrush, it can select that brush into any device context by calling the SelectObject function.

You can delete a pattern brush without affecting the associated bitmap by using the DeleteObject function. Therefore, you can then use this bitmap to create any number of pattern brushes.

A brush created by using a monochrome (1 bit per pixel) bitmap has the text and background colors of the device context to which it is drawn. Pixels represented by a 0 bit are drawn with the current text color; pixels represented by a 1 bit are drawn with the current background color.

The bitmap identified by hbmp cannot be a DIB section, which is a bitmap created by the CreateDIBSection function. If the bitmap is a DIB section, the CreatePatternBrush function fails.

See Also

CreateBitmap, CreateBitmapIndirect, CreateCompatibleBitmap, CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreateDIBSection, CreateHatchBrush, DeleteObject, GetBrushOrgEx, LoadBitmap, SelectObject, SetBrushOrgEx


CreatePen

The CreatePen function creates a logical pen that has the specified style, width, and color. The pen can subsequently be selected into a device context and used to draw lines and curves.

HPEN CreatePen(

int fnPenStyle,	// pen style
int nWidth,	// pen width
COLORREF crColor	// pen color
);
Parameters

fnPenStyle

Specifies the pen style. It can be any one of the following values:

Style	Description
PS_SOLID	Pen is solid.
PS_DASH	Pen is dashed. This style is valid only when the pen width is one or less in device units.
PS_DOT	Pen is dotted. This style is valid only when the pen width is one or less in device units.
PS_DASHDOT	Pen has alternating dashes and dots. This style is valid only when the pen width is one or less in device units.
PS_DASHDOTDOT	Pen has alternating dashes and double dots. This style is valid only when the pen width is one or less in device units.
PS_NULL	Pen is invisible.
PS_INSIDEFRAME	Pen is solid. When this pen is used in any graphics device interface (GDI) drawing function that takes a bounding rectangle, the dimensions of the figure are shrunk so that it fits entirely in the bounding rectangle, taking into account the width of the pen. This applies only to geometric pens.
nWidth

Specifies the width of the pen, in logical units. If nWidth is zero, the pen is a single pixel wide, regardless of the current transformation.

crColor

Specifies a color reference for the pen color.

Return Values

If the function succeeds, the return value is a handle that identifies a logical pen.

If the function fails, the return value is NULL.

Remarks

After an application creates a logical pen, it can select that pen into a device context by calling the SelectObject function. After a pen is selected into a device context, it can be used to draw lines and curves.

If the value specified by the nWidth parameter is zero, a line drawn with the created pen will always be a single pixel wide regardless of the current transformation.

If the value specified by nWidth is greater than 1, the fnPenStyle parameter must be PS_NULL, PS_SOLID, or PS_INSIDEFRAME.

If the value specified by nWidth is greater than 1 and fnPenStyle is PS_INSIDEFRAME, the line associated with the pen is drawn inside the frame of all primitives except polygons and polylines.

If the value specified by nWidth is greater than 1, fnPenStyle is PS_INSIDEFRAME, and the color specified by the crColor parameter does not match one of the entries in the logical palette, Windows draws lines by using a dithered color. Dithered colors are not available with solid pens.

When you no longer need the pen, call the DeleteObject function to delete it.

See Also

CreatePenIndirect, DeleteObject, ExtCreatePen, GetObject, RGB, SelectObject


CreatePenIndirect

The CreatePenIndirect function creates a logical cosmetic pen that has the style, width, and color specified in a structure.

HPEN CreatePenIndirect(

CONST LOGPEN *lplgpn	// pointer to LOGPEN structure
);
Parameters

lplgpn

Points to the LOGPEN structure that specifies the pen’s style, width, and color.

Return Values

If the function succeeds, the return value is a handle that identifies a logical cosmetic pen.

If the function fails, the return value is NULL.

Remarks

After an application creates a logical pen, it can select that pen into a device context by calling the SelectObject function. After a pen is selected into a device context, it can be used to draw lines and curves.

When you no longer need the pen, call the DeleteObject function to delete it.

See Also

CreatePen, DeleteObject, ExtCreatePen, GetObject, LOGPEN, RGB, SelectObject


CreatePipe

The CreatePipe function creates an anonymous pipe, and returns handles to the read and write ends of the pipe.

BOOL CreatePipe(

PHANDLE hReadPipe,	// address of variable for read handle
PHANDLE hWritePipe,	// address of variable for write handle
LPSECURITY_ATTRIBUTES lpPipeAttributes,	// pointer to security attributes
DWORD nSize	// number of bytes reserved for pipe
);
Parameters

hReadPipe

Points to the variable that receives the read handle for the pipe.

hWritePipe

Points to the variable that receives the write handle for the pipe.

lpPipeAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpPipeAttributes is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new pipe. If lpPipeAttributes is NULL, the pipe gets a default security descriptor.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

nSize

Specifies the buffer size for the pipe. The size is only a suggestion; the system uses the value to calculate an appropriate buffering mechanism. If this parameter is zero, the system uses the default buffer size.

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.

Remarks

CreatePipe creates the pipe, assigning the specified pipe size to the storage buffer. CreatePipe also creates handles that the process uses to read from and write to the buffer in subsequent calls to the ReadFile and WriteFile functions.

To read from the pipe, a process uses the read handle in a call to the ReadFile function. ReadFile returns when one of the following is true: a write operation completes on the write end of the pipe, the number of bytes requested has been read, or an error occurs.

When a process uses WriteFile to write to an anonymous pipe, the write operation is not completed until all bytes are written. If the pipe buffer is full before all bytes are written, WriteFile does not return until another process or thread uses ReadFile to make more buffer space available.

See Also

ReadFile, SECURITY_ATTRIBUTES, WriteFile


CreatePolygonRgn

The CreatePolygonRgn function creates a polygonal region.

HRGN CreatePolygonRgn(

CONST POINT *lppt,	// pointer to array of points
int cPoints,	// number of points in array
int fnPolyFillMode	// polygon-filling mode
);
Parameters

lppt

Points to an array of POINT structures that define the vertices of the polygon. The polygon is presumed closed. Each vertex can be specified only once.

cPoints

Specifies the number of points in the array.

fnPolyFillMode

Specifies the fill mode used to determine which pixels are in the region. This parameter can be one of the following values:

Value	Meaning
ALTERNATE	Selects alternate mode (fills area between odd-numbered and even-numbered polygon sides on each scan line).
WINDING	Selects winding mode (fills any region with a nonzero winding value).
For more information about these modes, see the SetPolyFillMode function.

Return Values

If the function succeeds, the return value is the handle to the region.

If the function fails, the return value is NULL.

See Also

CreatePolyPolygonRgn, DeleteObject, POINT, SelectObject, SetPolyFillMode


CreatePolyPolygonRgn

The CreatePolyPolygonRgn function creates a region consisting of a series of polygons. The polygons can overlap.

HRGN CreatePolyPolygonRgn(

CONST POINT *lppt,	// pointer to array of points
CONST INT *lpPolyCounts,	// pointer to array that contains vertex counts
int nCount,	// number of integers in array of vertex counts
int fnPolyFillMode	// polygon fill mode
);
Parameters

lppt

Points to an array of POINT structures that define the vertices of the polygons. The polygons are specified consecutively. Each polygon is presumed closed and each vertex is specified only once.

lpPolyCounts

Points to an array of integers, each of which specifies the number of points in one of the polygons in the array pointed to by lppt.

nCount

Specifies the total number of integers in the array pointed to by lpPolyCounts.

fnPolyFillMode

Specifies the fill mode used to determine which pixels are in the region. This parameter can be one of the following values:

Value	Meaning
ALTERNATE	Selects alternate mode (fills area between odd-numbered and even-numbered polygon sides on each scan line).
WINDING	Selects winding mode (fills any region with a nonzero winding value).
For more information about these modes, see the SetPolyFillMode function.

Return Values

If the function succeeds, the return value is the handle to the region.

If the function fails, the return value is zero.

See Also

CreatePolygonRgn, DeleteObject, POINT, SelectObject, SetPolyFillMode


CreatePopupMenu

The CreatePopupMenu function creates a drop-down menu, submenu, or shortcut menu. The menu is initially empty. You can insert or append menu items by using the InsertMenuItem function. You can also use the InsertMenu function to insert menu items and the AppendMenu function to append menu items.

HMENU CreatePopupMenu(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the handle to the newly created menu.

If the function fails, the return value is NULL.

Remarks

The application can add the new menu to an existing menu, or it can display a shortcut menu by calling the TrackPopupMenuEx or TrackPopupMenu functions.

Resources associated with a menu that is assigned to a window are freed automatically. If the menu is not assigned to a window, an application must free system resources associated with the menu before closing. An application frees menu resources by calling the DestroyMenu function.

Windows 95: The system can support a maximum of 16,364 menu handles.

See Also

AppendMenu, CreateMenu, DestroyMenu, InsertMenu, SetMenu, TrackPopupMenu, TrackPopupMenuEx, InsertMenuItem


CreatePrivateObjectSecurity

The CreatePrivateObjectSecurity function allocates and initializes a self-relative security descriptor for a new protected server’s object. This function is called when a new protected server object is being created.

BOOL CreatePrivateObjectSecurity(

PSECURITY_DESCRIPTOR ParentDescriptor,	// pointer to parent directory SD
PSECURITY_DESCRIPTOR CreatorDescriptor,	// pointer to creator SD
PSECURITY_DESCRIPTOR *NewDescriptor,	// pointer to pointer to new SD
BOOL IsDirectoryObject,	// container flag for new SD
HANDLE Token,	// handle to client’s access token
PGENERIC_MAPPING GenericMapping	// pointer to access-rights structure
);
Parameters

ParentDescriptor

Points to the security descriptor for the parent directory in which a new object is being created. If there is no parent directory, this parameter can be NULL.

CreatorDescriptor

Points to a security descriptor provided by the creator of the object. If the object’s creator does not explicitly pass security information for the new object, this parameter is intended to be NULL.

lppsdNew

Points to a pointer to the newly allocated security descriptor created when the function returns.

IsDirectoryObject

Specifies whether the new object is a container. A value of TRUE indicates the object contains other objects, such as a directory.

Token

Identifies the access token for the client process on whose behalf the object is being created. If this is an impersonation token, it must be at SecurityIdentification level or higher. For a full description of the SecurityIdentification impersonation level, see the SECURITY_IMPERSONATION_LEVEL enumerated type

A client token is used to retrieve default security information for the new object, such as its default owner, primary group, and discretionary access-control list. The token must be open for TOKEN_QUERY access.

GenericMapping

Points to a GENERIC_MAPPING structure that specifies the mapping from each generic right to specific rights for the object.

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.

Remarks

If a system access-control list, or SACL, is specified in the SECURITY_DESCRIPTOR specified by CreatorDescriptor, Token must have the SE_SECURITY_NAME privilege enabled, and the caller’s token must have the SE_AUDIT_NAME privilege enabled. The CreatePrivateObjectSecurity function performs access/privilege checks to ensure this, and may generate audits during the process.

See Also

DestroyPrivateObjectSecurity, GENERIC_MAPPING, GetPrivateObjectSecurity, GetTokenInformation, OpenProcessToken, SECURITY_DESCRIPTOR, SECURITY_IMPERSONATION_LEVEL, SetPrivateObjectSecurity


CreateProcess

The CreateProcess function creates a new process and its primary thread. The new process executes the specified executable file.

BOOL CreateProcess(

LPCTSTR lpApplicationName,	// pointer to name of executable module
LPTSTR lpCommandLine,	// pointer to command line string
LPSECURITY_ATTRIBUTES lpProcessAttributes,	// pointer to process security attributes
LPSECURITY_ATTRIBUTES lpThreadAttributes,	// pointer to thread security attributes
BOOL bInheritHandles,	// handle inheritance flag
DWORD dwCreationFlags,	// creation flags
LPVOID lpEnvironment,	// pointer to new environment block
LPCTSTR lpCurrentDirectory,	// pointer to current directory name
LPSTARTUPINFO lpStartupInfo,	// pointer to STARTUPINFO
LPPROCESS_INFORMATION lpProcessInformation	// pointer to PROCESS_INFORMATION
);
Parameters

lpApplicationName

Pointer to a null-terminated string that specifies the module to execute.

The string can specify the full path and filename of the module to execute.

The string can specify a partial name. In that case, the function uses the current drive and current directory to complete the specification.

The lpApplicationName parameter can be NULL. In that case, the module name must be the first white space-delimited token in the lpCommandLine string.

The specified module can be a Win32-based application. It can be some other type of module (for example, MS-DOS or OS/2) if the appropriate subsystem is available on the local computer.

Windows NT: If the executable module is a 16-bit application, lpApplicationName should be NULL, and the string pointed to by lpCommandLine should specify the executable module. A 16-bit application is one that executes as a VDM or WOW process.

lpCommandLine

Pointer to a null-terminated string that specifies the command line to execute.

The lpCommandLine parameter can be NULL. In that case, the function uses the string pointed to by lpApplicationName as the command line.

If both lpApplicationName and lpCommandLine are non-NULL, *lpApplicationName specifies the module to execute, and *lpCommandLine specifies the command line. The new process can use GetCommandLine to retrieve the entire command line. C runtime processes can use the argc and argv arguments.

If lpApplicationName is NULL, the first white space-delimited token of the command line specifies the module name. If the filename does not contain an extension, .EXE is assumed. If the filename ends in a period (.) with no extension, or the filename contains a path, .EXE is not appended. If the filename does not contain a directory path, Windows searches for the executable file in the following sequence:

1.	The directory from which the application loaded.

2.	The current directory for the parent process.

3.	Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path of this directory.

Windows NT: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	Windows NT: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

If the process to be created is an MS-DOS - based or Windows-based application, lpCommandLine should be a full command line in which the first element is the application name. Because this also works well for Win32-based applications, it is the most robust way to set lpCommandLine.

lpProcessAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpProcessAttributes is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new process. If lpProcessAttributes is NULL, the process gets a default security descriptor.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

lpThreadAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpThreadAttributes is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the main thread. If lpThreadAttributes is NULL, the thread gets a default security descriptor.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

bInheritHandles

Indicates whether the new process inherits handles from the calling process. If TRUE, each inheritable open handle in the calling process is inherited by the new process. Inherited handles have the same value and access privileges as the original handles.

dwCreationFlags

Specifies additional flags that control the priority class and the creation of the process. The following creation flags can be specified in any combination, except as noted:

Value	Meaning
CREATE_DEFAULT_ERROR_MODE
	The new process does not inherit the error mode of the calling process. Instead, CreateProcess gives the new process the current default error mode. An application sets the current default error mode by calling SetErrorMode. This flag is particularly useful for multi-threaded shell applications that run with hard errors disabled.  The default behavior for CreateProcess is for the new process to inherit the error mode of the caller. Setting this flag changes that default behavior.
CREATE_NEW_CONSOLE
	The new process has a new console, instead of inheriting the parent’s console. This flag cannot be used with the DETACHED_PROCESS flag.
CREATE_NEW_PROCESS_GROUP
	The new process is the root process of a new process group. The process group includes all processes that are descendants of this root process. The process identifier of the new process group is the same as the process identifier, which is returned in the lpProcessInformation parameter. Process groups are used by the GenerateConsoleCtrlEvent function to enable sending a CTRL+C or CTRL+BREAK signal to a group of console processes.
CREATE_SEPARATE_WOW_VDM
	Windows NT only: This flag is valid only when starting a 16-bit Windows-based application. If set, the new process is run in a private Virtual DOS Machine (VDM). By default, all 16-bit Windows-based applications are run as threads in a single, shared VDM. The advantage of running separately is that a crash only kills the single VDM; any other programs running in distinct VDMs continue to function normally. Also, 16-bit Windows-based applications that are run in separate VDMs have separate input queues. That means that if one application hangs momentarily, applications in separate VDMs continue to receive input.
CREATE_SHARED_WOW_VDM
	Windows NT only: The flag is valid only when starting a 16-bit Windows-based application. If the DefaultSeparateVDM switch in the Windows section of WIN.INI is TRUE, this flag causes the CreateProcess function to override the switch and run the new process in the shared Virtual DOS Machine.
CREATE_SUSPENDED
	The primary thread of the new process is created in a suspended state, and does not run until the ResumeThread function is called.
CREATE_UNICODE_ENVIRONMENT
	If set, the environment block pointed to by lpEnvironment uses Unicode characters. If clear, the environment block uses ANSI characters.
DEBUG_PROCESS
	If this flag is set, the calling process is treated as a debugger, and the new process is a process being debugged. The system notifies the debugger of all debug events that occur in the process being debugged. If you create a process with this flag set, only the calling thread (the thread that called CreateProcess) can call the WaitForDebugEvent function.
DEBUG_ONLY_THIS_PROCESS
	If not set and the calling process is being debugged, the new process becomes another process being debugged by the calling process’s debugger. If the calling process is not a process being debugged, no debugging-related actions occur.
DETACHED_PROCESS
	For console processes, the new process does not have access to the console of the parent process. The new process can call the AllocConsole function at a later time to create a new console. This flag cannot be used with the CREATE_NEW_CONSOLE flag.
The dwCreationFlags parameter also controls the new process’s priority class, which is used in determining the scheduling priorities of the process’s threads. If none of the following priority class flags is specified, the priority class defaults to NORMAL_PRIORITY_CLASS unless the priority class of the creating process is IDLE_PRIORITY_CLASS. In this case the default priority class of the child process is IDLE_PRIORITY_CLASS. One of the following flags can be specified:

Priority	Meaning
HIGH_PRIORITY_CLASS	Indicates a process that performs time-critical tasks that must be executed immediately for it to run correctly. The threads of a high-priority class process preempt the threads of normal-priority or idle-priority class processes. An example is Windows Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class CPU-bound application can use nearly all available cycles.
IDLE_PRIORITY_CLASS	Indicates a process whose threads run only when the system is idle and are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle priority class is inherited by child processes.
NORMAL_PRIORITY_CLASS	Indicates a normal process with no special scheduling needs.
REALTIME_PRIORITY_CLASS	Indicates a process that has the highest possible priority. The threads of a real-time priority class process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.
lpEnvironment

Points to an environment block for the new process. If this parameter is NULL, the new process uses the environment of the calling process.

An environment block consists of a null-terminated block of null-terminated strings. Each string is in the form:

name=value

Because the equal sign is used as a separator, it must not be used in the name of an environment variable.

If an application provides an environment block, rather than passing NULL for this parameter, the current directory information of the system drives is not automatically propagated to the new process. For a discussion of this situation and how to handle it, see the following Remarks section.

An environment block can contain Unicode or ANSI characters. If the environment block pointed to by lpEnvironment contains Unicode characters, the dwCreationFlags field’s CREATE_UNICODE_ENVIRONMENT flag will be set. If the block contains ANSI characters, that flag will be clear.

Note that an ANSI environment block is terminated by two zero bytes: one for the last string, one more to terminate the block. A Unicode environment block is terminated by four zero bytes: two for the last string, two more to terminate the block.

lpCurrentDirectory

Points to a null-terminated string that specifies the current drive and directory for the child process. The string must be a full path and filename that includes a drive letter. If this parameter is NULL, the new process is created with the same current drive and directory as the calling process. This option is provided primarily for shells that need to start an application and specify its initial drive and working directory.

lpStartupInfo

Points to a STARTUPINFO structure that specifies how the main window for the new process should appear.

lpProcessInformation

Points to a PROCESS_INFORMATION structure that receives identification information about the new process.

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.

Remarks

The CreateProcess function is used to run a new program. The WinExec and LoadModule functions are still available, but they are implemented as calls to CreateProcess.

In addition to creating a process, CreateProcess also creates a thread object. The thread is created with an initial stack whose size is described in the image header of the specified program’s executable file. The thread begins execution at the image’s entry point.

The new process and the new thread handles are created with full access rights. For either handle, if a security descriptor is not provided, the handle can be used in any function that requires an object handle of that type. When a security descriptor is provided, an access check is performed on all subsequent uses of the handle before access is granted. If the access check denies access, the requesting process is not able to use the handle to gain access to the thread.

The process is assigned a 32-bit process identifier. The identifier is valid until the process terminates. It can be used to identify the process, or specified in the OpenProcess function to open a handle to the process. The initial thread in the process is also assigned a 32-bit thread identifier. The identifier is valid until the thread terminates and can be used to uniquely identify the thread within the system. These identifiers are returned in the PROCESS_INFORMATION structure.

When specifying an application name in the lpApplicationName or lpCommandLine strings, it doesn’t matter whether the application name includes the filename extension, with one exception: an MS-DOS − based or Windows-based application whose filename extension is .COM must include the .COM extension.

The calling thread can use the WaitForInputIdle function to wait until the new process has finished its initialization and is waiting for user input with no input pending. This can be useful for synchronization between parent and child processes, because CreateProcess returns without waiting for the new process to finish its initialization. For example, the creating process would use WaitForInputIdle before trying to find a window associated with the new process.

The preferred way to shut down a process is by using the ExitProcess function, because this function notifies all dynamic-link libraries (DLLs) attached to the process of the approaching termination. Other means of shutting down a process do not notify the attached DLLs. Note that when a thread calls ExitProcess, other threads of the process are terminated without an opportunity to execute any additional code (including the thread termination code of attached DLLs).

ExitProcess, ExitThread, CreateThread, CreateRemoteThread, and a process that is starting (as the result of a call by CreateProcess) are serialized between each other within a process. Only one of these events can happen in an address space at a time. This means the following restrictions hold:

•	During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.

•	Only one thread in a process can be in a DLL initialization or detach routine at a time.

•	The ExitProcess function does not return until no threads are in their DLL initialization or detach routines.

The created process remains in the system until all threads within the process have terminated and all handles to the process and any of its threads have been closed through calls to CloseHandle. The handles for both the process and the main thread must be closed through calls to CloseHandle. If these handles are not needed, it is best to close them immediately after the process is created.

When the last thread in a process terminates, the following events occur:

•	All objects opened by the process are implicitly closed.

•	The process’s termination status (which is returned by GetExitCodeProcess) changes from its initial value of STILL_ACTIVE to the termination status of the last thread to terminate.

•	The thread object of the main thread is set to the signaled state, satisfying any threads that were waiting on the object.

•	The process object is set to the signaled state, satisfying any threads that were waiting on the object.

If the current directory on drive C is \MSVC\MFC, there is an environment variable called =C: whose value is C:\MSVC\MFC. As noted in the previous description of lpEnvironment, such current directory information for a system’s drives does not automatically propagate to a new process when the CreateProcess function’s lpEnvironment parameter is non-NULL. An application must manually pass the current directory information to the new process. To do so, the application must explicitly create the =X environment variable strings, get them into alphabetical order (because Windows NT and Windows 95 use a sorted environment), and then put them into the environment block specified by lpEnvironment. Typically, they will go at the front of the environment block, due to the previously mentioned environment block sorting.

One way to obtain the current directory variable for a drive X is to call GetFullPathName(“X:”,. .). That avoids an application having to scan the environment block. If the full path returned is X:\, there is no need to pass that value on as environment data, since the root directory is the default current directory for drive X of a new process.

The handle returned by the CreateProcess function has PROCESS_ALL_ACCESS access to the process object.

The current directory specified by the lpcurrentDirectory parameter is the current directory for the child process. The current directory specified in item 2 under the lpCommandLine parameter is the current directory for the parent process.

Windows NT: When a process is created with CREATE_NEW_PROCESS_GROUP specified, an implicit call to SetConsoleCtrlHandler(NULL,TRUE) is made on behalf of the new process; this means that the new process has CTRL+C disabled. This lets good shells handle CTRL+C themselves, and selectively pass that signal on to sub-processes. CTRL+BREAK is not disabled, and may be used to interrupt the process/process group.

See Also

AllocConsole, CloseHandle, CreateRemoteThread, CreateThread, ExitProcess, ExitThread, GenerateConsoleCtrlEvent, GetCommandLine, GetEnvironmentStrings, GetExitCodeProcess, GetFullPathName, GetStartupInfo, GetSystemDirectory, GetWindowsDirectory, LoadModule, OpenProcess, PROCESS_INFORMATION, ResumeThread, SECURITY_ATTRIBUTES, SetConsoleCtrlHandler, SetErrorMode, STARTUPINFO, TerminateProcess, WaitForInputIdle, WaitForDebugEvent, WinExec


CreateProcessAsUser

The CreateProcessAsUser function creates a new process and its primary thread. The new process then executes a specified executable file. The CreateProcessAsUser function is similar to the CreateProcess function, except that the new process runs in the security context of the user represented by the hToken parameter. By default, the new process is non-interactive, that is, it runs on a desktop that is not visible and cannot receive user input. Also, by default, the new process inherits the environment of the calling process, rather than the environment associated with the specified user.

BOOL CreateProcessAsUser(

HANDLE hToken,	// handle to a token that represents a logged-on user
LPCTSTR lpApplicationName,	// pointer to name of executable module
LPTSTR lpCommandLine,	// pointer to command line string
LPSECURITY_ATTRIBUTES lpProcessAttributes,	// pointer to process security attributes
LPSECURITY_ATTRIBUTES lpThreadAttributes,	// pointer to thread security attributes
BOOL bInheritHandles,	// new process inherits handles
DWORD dwCreationFlags,	// creation flags
LPVOID lpEnvironment,	// pointer to new environment block
LPCTSTR lpCurrentDirectory,	// pointer to current directory name
LPSTARTUPINFO lpStartupInfo,	// pointer to STARTUPINFO
LPPROCESS_INFORMATION lpProcessInformation	// pointer to PROCESS_INFORMATION
);
Parameters

hToken

Handle to a primary token that represents a user. The user represented by the token must have read and execute access to the application specified by the lpApplicationName or the lpCommandLine parameter.

If your process has the SE_TCB_NAME privilege, it can call the LogonUser function to get a primary token that represents a specified user.

Alternatively, you can call the DuplicateTokenEx function to convert an impersonation token into a primary token. This allows a server application that is impersonating a client to create a process that has the security context of the client.

The other parameters of the CreateProcessAsUser function behave just like the analogous parameters of the CreateProcess function.

lpApplicationName

Points to a null-terminated string specifying the full path and filename of the module to execute. If a partial name is specified, the current drive and current directory are used by default. If this parameter is NULL, the module name must be the first white space-delimited token in the lpCommandLine string. The specified module can be a Win32-based application, or it can be some other type of module (for example, MS-DOS or OS/2) if the appropriate subsystem is available on the local computer.

lpCommandLine

Points to a null-terminated string specifying the command line for the application to be executed. If this parameter is NULL, the lpApplicationName string is used as the command line. If both lpApplicationName and lpCommandLine are non-NULL, lpApplicationName specifies the module to execute and lpCommandLine is used as the command line. The new process can use GetCommandLine to retrieve the entire command line; or C runtime processes can use the argc/argv mechanism.

If lpApplicationName is NULL, the first white space-delimited token of the command line specifies the module name. If the filename does not contain an extension, .EXE is assumed. If the filename ends in a period (.) with no extension, or the filename contains a path, .EXE is not appended. If the filename does not contain a directory path, Windows searches for the executable file in the following sequence:

1.	The directory from which the application loaded.

2.	The current directory.

3.	The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

If the process to be created is an MS-DOS − based or 16-bit Windows-based application, lpCommandLine should be a full command line in which the first element is the application name. Because this also works well for Win32-based applications, it is the most robust way to set lpCommandLine.

lpProcessAttributes

Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new process and determines whether child processes can inherit the returned handle. If lpProcessAttributes is NULL, the process gets a default security descriptor and the handle cannot be inherited.

lpThreadAttributes

Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new process and determines whether child processes can inherit the returned handle. If lpThreadAttributes is NULL, the thread gets a default security descriptor and the handle cannot be inherited.

bInheritHandles

Indicates whether the new process inherits handles from the calling process. If TRUE, each inheritable open handle in the calling process is inherited by the new process. Inherited handles have the same value and access privileges as the original handles.

dwCreationFlags

Specifies additional flags that control the priority class and the creation of the process. The following creation flags can be specified in any combination, except as noted:

Value	Meaning
CREATE_DEFAULT_ERROR_MODE
	The new process does not inherit the error mode of the calling process. Instead, CreateProcessAsUser gives the new process the current default error mode. An application sets the current default error mode by calling SetErrorMode. This flag is particularly useful for multi-threaded shell applications that run with hard errors disabled.  The default behavior for CreateProcessAsUser is for the new process to inherit the error mode of the caller. Setting this flag changes that default behavior.
CREATE_NEW_CONSOLE
	The new process has a new console, instead of inheriting the parent’s console. This flag cannot be used with the DETACHED_PROCESS flag.
CREATE_NEW_PROCESS_GROUP
	The new process is the root process of a new process group. The process group includes all processes that are descendants of this root process. The process identifier of the new process group is the same as the process identifier, which is returned in the lpProcessInformation parameter. Process groups are used by the GenerateConsoleCtrlEvent function to enable sending a CTRL+C or CTRL+BREAK signal to a group of console processes.
CREATE_SEPARATE_WOW_VDM
	This flag is only valid only starting a 16-bit Windows program. If set, the new process is run in a private Virtual DOS Machine (VDM).  By default, all 16-bit Windows programs are run in a single, shared VDM.  The advantage of running separately is that a crash only kills the single VDM; any other programs running in distinct VDMs continue to function normally. Also, 16-bit Windows applications that are run in separate VDMs have separate input queues. That means that if one application hangs momentarily, applications in separate VDMs continue to receive input.
CREATE_SUSPENDED
	The primary thread of the new process is created in a suspended state, and does not run until the ResumeThread function is called.
CREATE_UNICODE_ENVIRONMENT
	If set, the environment block pointed to by lpEnvironment uses Unicode characters. If clear, the environment block uses ANSI characters.
DEBUG_PROCESS
	If set, the calling process is treated as a debugger, and the new process is a process being debugged. The system notifies the debugger of all debug events that occur in the process being debugged.
DEBUG_ONLY_THIS_PROCESS
	If not set and the calling process is being debugged, the new process becomes another process being debugged by the calling process’s debugger. If the calling process is not a process being debugged, no debugging-related actions occur.
DETACHED_PROCESS
	For console processes, the new process does not have access to the console of the parent process. The new process can call the AllocConsole function at a later time to create a new console. This flag cannot be used with the CREATE_NEW_CONSOLE flag.
The dwCreationFlags parameter also controls the new process’s priority class, which is used in determining the scheduling priorities of the process’s threads. If none of the following priority class flags is specified, the priority class defaults to NORMAL_PRIORITY_CLASS unless the priority class of the creating process is IDLE_PRIORITY_CLASS. In this case the default priority class of the child process is IDLE_PRIORITY_CLASS. One of the following flags can be specified:

Priority	Meaning
HIGH_PRIORITY_CLASS	Indicates a process that performs time-critical tasks that must be executed immediately for it to run correctly. The threads of a high-priority class process preempt the threads of normal-priority or idle-priority class processes. An example is Windows Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class CPU-bound application can use nearly all available cycles.
IDLE_PRIORITY_CLASS	Indicates a process whose threads run only when the system is idle and are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle priority class is inherited by child processes.
NORMAL_PRIORITY_CLASS	Indicates a normal process with no special scheduling needs.
REALTIME_PRIORITY_CLASS	Indicates a process that has the highest possible priority. The threads of a real-time priority class process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.
lpEnvironment

Points to an environment block for the new process. If this parameter is NULL, the new process uses the environment of the calling process.

An environment block consists of a null-terminated block of null-terminated strings. Each string is in the form:

name=value

Because the equal sign is used as a separator, it must not be used in the name of an environment variable.

If an application provides an environment block, rather than passing NULL for this parameter, the current directory information of the system drives is not automatically propagated to the new process. For a discussion of this situation and how to handle it, see the following Remarks section.

An environment block can contain Unicode or ANSI characters. If the environment block pointed to by lpEnvironment contains Unicode characters, the dwCreationFlags field’s CREATE_UNICODE_ENVIRONMENT flag will be set. If the block contains ANSI characters, that flag will be clear.

Note that an ANSI environment block is terminated by two zero bytes: one for the last string, one more to terminate the block. A Unicode environment block is terminated by four zero bytes: two for the last string, two more to terminate the block.

lpCurrentDirectory

Points to a null-terminated string that specifies the current drive and directory for the new process. The string must be a full path and filename that includes a drive letter. If this parameter is NULL, the new process is created with the same current drive and directory as the calling process. This option is provided primarily for shells that need to start an application and specify its initial drive and working directory.

lpStartupInfo

Points to a STARTUPINFO structure that specifies how the main window for the new process should appear.

lpProcessInformation

Points to a PROCESS_INFORMATION structure that receives identification information about the new process.

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.

Remarks

The CreateProcessAsUser function requires the SE_ASSIGNPRIMARYTOKEN_NAME and SE_INCREASE_QUOTA_NAME privileges. If they are not already enabled, CreateProcessAsUser enables them for the duration of the call.

By default, CreateProcessAsUser creates the new process on a noninteractive window station with a desktop that is not visible and cannot receive user input. To enable user interaction with the new process, you must specify the name of the default interactive window station and desktop, “winsta0\default”, in the lpDesktop member of the STARTUPINFO structure. In addition, before calling CreateProcessAsUser, you must change the discretionary access control list (DACL) of both the default interactive window station and the default desktop. The DACLs for the window station and desktop must grant access to the user represented by the hToken parameter.

CreateProcessAsUser does not load the specified user’s profile into the HKEY_USERS registry key. This means that access to information in the HKEY_CURRENT_USER registry key may not produce results consistent with a normal interactive logon. It is your responsibility to load the user’s registry hive into HKEY_USERS before calling CreateProcessAsUser.

If the lpEnvironment parameter is NULL, the new process inherits the environment of the calling process. CreateProcessAsUser does not automatically modify the environment block to include environment variables specific to the user represented by hToken. For example, the USERNAME and USERDOMAIN variables are inherited from the calling process if lpEnvironment is NULL. It is your responsibility to prepare the environment block for the new process and specify it in lpEnvironment.

CreateProcessAsUser allows you to access the specified directory and executable image in the security context of the caller or the target user. By default, CreateProcessAsUser accesses the directory and executable image in the security context of the caller. In this case, if the caller does not have access to the directory and executable image, the function fails. To access the directory and executable image using the security context of the target user, specify hToken in a call to the ImpersonateLoggedOnUser function before calling CreateProcessAsUser.

The new process and the new thread handles are created with full access rights (PROCESS_ALL_ACCESS and THREAD_ALL_ACCESS). For either handle, if a security descriptor is not provided, the handle can be used in any function that requires an object handle of that type. When a security descriptor is provided, an access check is performed on all subsequent uses of the handle before access is granted. If the access check denies access, the requesting process is not able to use the handle to gain access to the process or thread.

If the lpProcessAttributes parameter is NULL, the default security descriptor for the user referenced in the hToken parameter will be used. This security descriptor may not allow access for the caller, in which case the process may not be opened again once it is run. The handle returned in the PROCESS_INFORMATION structure is valid and will continue to have all access. This is also true for thread attributes.

Handles in PROCESS_INFORMATION must be closed with CloseHandle when they are no longer needed.

The process is assigned a process identifier. The identifier is valid until the process terminates. It can be used to identify the process, or specified in the OpenProcess function to open a handle to the process. The initial thread in the process is also assigned a thread identifier. The identifier is valid until the thread terminates and can be used to uniquely identify the thread within the system. These identifiers are returned in the PROCESS_INFORMATION structure.

When specifying an application name in the lpApplicationName or lpCommandLine strings, it doesn’t matter whether the application name includes the filename extension, with one exception: an MS-DOS − based or Windows-based application whose filename extension is .COM must include the .COM extension.

The calling thread can use the WaitForInputIdle function to wait until the new process has finished its initialization and is waiting for user input with no input pending. This can be useful for synchronization between parent and child processes, because CreateProcessAsUser returns without waiting for the new process to finish its initialization. For example, the creating process would use WaitForInputIdle before trying to find a window associated with the new process.

The preferred way to shut down a process is by using the ExitProcess function, because this function notifies all dynamic-link libraries (DLLs) attached to the process of the approaching termination. Other means of shutting down a process do not notify the attached DLLs. Note that when a thread calls ExitProcess, other threads of the process are terminated without an opportunity to execute any additional code (including the thread termination code of attached DLLs).

ExitProcess, ExitThread, CreateThread, CreateRemoteThread, and a process that is starting (as the result of a call by CreateProcessAsUser) are serialized between each other within a process. Only one of these events can happen at a time. This means the following restrictions hold:

•	During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.

•	Only one thread in a process can be in a DLL initialization or detach routine at a time.

•	The ExitProcess function does not return until no threads are executing DLL initialization or detach routines.

See Also

AllocConsole, CloseHandle, CreateProcess, CreateRemoteThread, CreateThread, DuplicateTokenEx, ExitProcess, ExitThread, GenerateConsoleCtrlEvent, GetCommandLine, GetEnvironmentStrings, GetExitCodeProcess, GetFullPathName, GetStartupInfo, GetSystemDirectory, GetWindowsDirectory, ImpersonateLoggedOnUser, LoadModule, LogonUser, OpenProcess, PROCESS_INFORMATION, ResumeThread, SECURITY_ATTRIBUTES, SetConsoleCtrlHandler, SetErrorMode, STARTUPINFO, TerminateProcess, WaitForInputIdle, WinExec


CreatePropertySheetPage

The CreatePropertySheetPage function creates a new page for a property sheet.

HPROPSHEETPAGE CreatePropertySheetPage(

LPCPROPSHEETPAGE lppsp
);
Parameters

lppsp

Pointer to a PROPSHEETPAGE structure that defines a page to be included in a property sheet.

Return Values

If the function succeeds, the return value is the handle to the new property sheet.

If the function fails, the return value is NULL.

Remarks

An application uses the PropertySheet function to create a property sheet that includes the new page or uses the PSM_ADDPAGE message to add the new page to an existing property sheet.

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

PropertySheet, PROPSHEETPAGE, PSM_ADDPAGE


CreateRectRgn

The CreateRectRgn function creates a rectangular region.

HRGN CreateRectRgn(

int nLeftRect,	// x-coordinate of region’s upper-left corner
int nTopRect,	// y-coordinate of region’s upper-left corner
int nRightRect,	// x-coordinate of region’s lower-right corner
int nBottomRect	// y-coordinate of region’s lower-right corner
);
Parameters

nLeftRect

Specifies the x-coordinate of the upper-left corner of the region.

nTopRect

Specifies the y-coordinate of the upper-left corner of the region.

nRightRect

Specifies the x-coordinate of the lower-right corner of the region.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the region.

Return Values

If the function succeeds, the return value is the handle to the region.

If the function fails, the return value is NULL.

Remarks

The region will be exclusive of the bottom and right edges.

See Also

CreateRectRgnIndirect, CreateRoundRectRgn, DeleteObject, SelectObject


CreateRectRgnIndirect

The CreateRectRgnIndirect function creates a rectangular region.

HRGN CreateRectRgnIndirect(

CONST RECT *lprc	// pointer to the rectangle
);
Parameters

lprc

Points to a RECT structure that contains the coordinates of the upper-left and lower-right corners of the rectangle that defines the region.

Return Values

If the function succeeds, the return value is the handle to the region.

If the function fails, the return value is NULL.

Remarks

The region will be exclusive of the bottom and right edges.

See Also

CreateRectRgn, CreateRoundRectRgn, DeleteObject, RECT, SelectObject


CreateRemoteThread

The CreateRemoteThread function creates a thread that runs in the address space of another process.

HANDLE CreateRemoteThread(

HANDLE hProcess,	// handle to process to create thread in
LPSECURITY_ATTRIBUTES lpThreadAttributes,	// pointer to thread security attributes
DWORD dwStackSize,	// initial thread stack size, in bytes
LPTHREAD_START_ROUTINE lpStartAddress,	// pointer to thread function
LPVOID lpParameter,	// pointer to argument for new thread
DWORD dwCreationFlags,	// creation flags
LPDWORD lpThreadId	// pointer to returned thread identifier
);
Parameters

hProcess

Identifies the process in which the thread is to be created.

Windows NT: The handle must have PROCESS_CREATE_THREAD access. For more information, see Process Objects.

lpThreadAttributes

Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new thread and determines whether child processes can inherit the returned handle. If lpThreadAttributes is NULL, the thread gets a default security descriptor and the handle cannot be inherited.

dwStackSize

Specifies the size, in bytes, of the stack for the new thread. If this value is zero, the stack size defaults to the same size as that of the primary thread of the process. The stack is allocated automatically in the memory space of the process and is freed when the thread terminates. Note that the stack size grows as necessary.

lpStartAddress

Points to the starting address of the new thread. This is typically the address of a function declared with the WINAPI calling convention that never returns and that accepts a single 32-bit pointer as an argument.

lpParameter

Points to a single 32-bit value passed to the thread.

dwCreationFlags

Specifies additional flags that control the creation of the thread. If the CREATE_SUSPENDED flag is specified, the thread is created in a suspended state and will not run until the ResumeThread function is called. If this value is zero, the thread runs immediately after creation.

lpThreadId

Points to a 32-bit variable that receives the thread identifier.

Return Values

If the function succeeds, the return value is a handle to the new thread.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The CreateRemoteThread function causes a new thread of execution to begin in the address space of the specified process. The thread has access to all objects opened by the process.

The new thread handle is created with full access to the new thread. If a security descriptor is not provided, the handle may be used in any function that requires a thread object handle. When a security descriptor is provided, an access check is performed on all subsequent uses of the handle before access is granted. If the access check denies access, the requesting process cannot use the handle to gain access to the thread.

The thread execution begins at the function specified by the lpStartAddress parameter. If this function returns, the results are unspecified.

CreateRemoteThread may succeed even if lpStartAddress points to data, code, or is not accessible. If the start address is invalid when the thread runs, an exception occurs, and the thread terminates. Thread termination due to a invalid start address is handled as an error exit for the thread’s process. This behavior is similar to the asynchronous nature of CreateProcess, where the process is created even if it refers to invalid or missing dynamic-link libraries (DLLs).

The thread is created with a thread priority of THREAD_PRIORITY_NORMAL. Use the GetThreadPriority and SetThreadPriority functions to get and set the priority value of a thread.

When a thread terminates, the thread object attains a signaled state, satisfying any threads that were waiting for the object.

The thread object remains in the system until the thread has terminated and all handles to it have been closed through a call to CloseHandle.

The ExitProcess, ExitThread, CreateThread, CreateRemoteThread functions, and a process that is starting (as the result of a CreateProcess call) are serialized between each other within a process. Only one of these events can happen in an address space at a time. This means the following restrictions hold:

•	During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.

•	Only one thread in a process can be in a DLL initialization or detach routine at a time.

•	ExitProcess does not return until no threads are in their DLL initialization or detach routines.

See Also

CloseHandle, CreateProcess, CreateThread, ExitProcess, ExitThread, GetThreadPriority, ResumeThread, SECURITY_ATTRIBUTES, SetThreadPriority


CreateRoundRectRgn

The CreateRoundRectRgn function creates a rectangular region with rounded corners.

HRGN CreateRoundRectRgn(

int nLeftRect,	// x-coordinate of the region’s  upper-left corner
int nTopRect,	// y-coordinate of the region’s upper-left corner
int nRightRect,	// x-coordinate of the region’s lower-right corner
int nBottomRect,	// y-coordinate of the region’s lower-right corner
int nWidthEllipse,	// height of ellipse for rounded corners
int nHeightEllipse	// width of ellipse for rounded corners
);
Parameters

nLeftRect

Specifies the x-coordinate of the upper-left corner of the region.

nTopRect

Specifies the y-coordinate of the upper-left corner of the region.

nRightRect

Specifies the x-coordinate of the lower-right corner of the region.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the region.

nWidthEllipse

Specifies the width of the ellipse used to create the rounded corners.

nHeightEllipse

Specifies the height of the ellipse used to create the rounded corners.

Return Values

If the function succeeds, the return value is the handle to the region.

If the function fails, the return value is NULL.

See Also

CreateRectRgn, CreateRectRgnIndirect, DeleteObject, SelectObject


CreateScalableFontResource

The CreateScalableFontResource function creates a font resource file for a scalable font.

BOOL CreateScalableFontResource(

DWORD fdwHidden,	// flag for read-only embedded font
LPCTSTR lpszFontRes,	// pointer to filename for font resource
LPCTSTR lpszFontFile,	// pointer to filename for scalable font
LPCTSTR lpszCurrentPath	// pointer to path to font file
);
Parameters

fdwHidden

Specifies whether the font is a read-only embedded font. This parameter can be one of the following values:

Value	Meaning
0	The font has read-write permission.
1	The font has read-only permission and should be hidden from other applications in the system. When this flag is set, the font is not enumerated by the EnumFonts or EnumFontFamilies function.
lpszFontRes

Points to a null-terminated string specifying the name of the font resource file that this function creates.

lpszFontFile

Points to a null-terminated string specifying the name of the scalable font file that this function uses to create the font resource file.

lpszCurrentPath

Points to a null-terminated string specifying the path to the scalable font file.

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.

Remarks

The CreateScalableFontResource function is used by applications that install TrueType fonts. An application uses the CreateScalableFontResource function to create a font resource file (typically with a .FOT filename extension) and then uses the AddFontResource function to install the font. The TrueType font file (typically with a .TTF filename extension) must be in the SYSTEM subdirectory of the WINDOWS directory to be used by the AddFontResource function.

The CreateScalableFontResource function currently supports only TrueType-technology scalable fonts.

When the lpszFontFile parameter specifies only a filename and extension, the lpszCurrentPath parameter must specify a path. When the lpszFontFile parameter specifies a full path, the lpszCurrentPath parameter must be NULL or a pointer to NULL.

When only a filename and extension are specified in the lpszFontFile parameter and a path is specified in the lpszCurrentPath parameter, the string in lpszFontFile is copied into the .FOT file as the .TTF file that belongs to this resource. When the AddFontResource function is called, the operating system assumes that the .TTF file has been copied into the SYSTEM directory (or into the main Windows directory in the case of a network installation). The .TTF file need not be in this directory when the CreateScalableFontResource function is called, because the lpszCurrentPath parameter contains the directory information. A resource created in this manner does not contain absolute path information and can be used in any Windows installation.

When a path is specified in the lpszFontFile parameter and NULL is specified in the lpszCurrentPath parameter, the string in lpszFontFile is copied into the .FOT file. In this case, when the AddFontResource function is called, the .TTF file must be at the location specified in the lpszFontFile parameter when the CreateScalableFontResource function was called; the lpszCurrentPath parameter is not needed. A resource created in this manner contains absolute references to paths and drives and does not work if the .TTF file is moved to a different location.

See Also

AddFontResource, EnumFonts, EnumFontFamilies


CreateSemaphore

The CreateSemaphore function creates a named or unnamed semaphore object.

HANDLE CreateSemaphore(

LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,	// pointer to security attributes
LONG lInitialCount,	// initial count
LONG lMaximumCount,	// maximum count
LPCTSTR lpName	// pointer to semaphore-object name
);
Parameters

lpSemaphoreAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSemaphoreAttributes is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new semaphore. If lpSemaphoreAttributes is NULL, the semaphore gets a default security descriptor.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

lInitialCount

Specifies an initial count for the semaphore object. This value must be greater than or equal to zero and less than or equal to lMaximumCount. The state of a semaphore is signaled when its count is greater than zero and nonsignaled when it is zero. The count is decreased by one whenever a wait function releases a thread that was waiting for the semaphore. The count is increased by a specified amount by calling the ReleaseSemaphore function.

lMaximumCount

Specifies the maximum count for the semaphore object. This value must be greater than zero.

lpName

Points to a null-terminated string specifying the name of the semaphore object. The name is limited to MAX_PATH characters, and can contain any character except the backslash path-separator character (\). Name comparison is case sensitive.

If lpName matches the name of an existing named semaphore object, this function requests SEMAPHORE_ALL_ACCESS access to the existing object. In this case, the lInitialCount and lMaximumCount parameters are ignored because they have already been set by the creating process. If the lpSemaphoreAttributes parameter is not NULL, it determines whether the handle can be inherited, but its security-descriptor member is ignored.

If lpName is NULL, the semaphore object is created without a name.

If lpName matches the name of an existing event, mutex, or file-mapping object, the function fails and the GetLastError function returns ERROR_INVALID_HANDLE. This occurs because event, mutex, semaphore, and file-mapping objects share the same name space.

Return Values

If the function succeeds, the return value is a handle to the semaphore object. If the named semaphore object existed before the function call, the GetLastError function returns ERROR_ALREADY_EXISTS. Otherwise, GetLastError returns zero.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The handle returned by CreateSemaphore has SEMAPHORE_ALL_ACCESS access to the new semaphore object and can be used in any function that requires a handle to a semaphore object.

Any thread of the calling process can specify the semaphore-object handle in a call to one of the wait functions. The single-object wait functions return when the state of the specified object is signaled. The multiple-object wait functions can be instructed to return either when any one or when all of the specified objects are signaled. When a wait function returns, the waiting thread is released to continue its execution.

The state of a semaphore object is signaled when its count is greater than zero, and nonsignaled when its count is equal to zero. The lInitialCount parameter specifies the initial count. Each time a waiting thread is released because of the semaphore’s signaled state, the count of the semaphore is decreased by one. Use the ReleaseSemaphore function to increment a semaphore’s count by a specified amount. The count can never be less than zero or greater than the value specified in the lMaximumCount parameter.

Multiple processes can have handles of the same semaphore object, enabling use of the object for interprocess synchronization. The following object-sharing mechanisms are available:

•	A child process created by the CreateProcess function can inherit a handle to a semaphore object if the lpSemaphoreAttributes parameter of CreateSemaphore enabled inheritance.

•	A process can specify the semaphore-object handle in a call to the DuplicateHandle function to create a duplicate handle that can be used by another process.

•	A process can specify the name of a semaphore object in a call to the OpenSemaphore or CreateSemaphore function.

Use the CloseHandle function to close the handle. The system closes the handle automatically when the process terminates. The semaphore object is destroyed when its last handle has been closed.

See Also

CloseHandle, CreateProcess, DuplicateHandle, OpenSemaphore, ReleaseSemaphore, SECURITY_ATTRIBUTES


CreateService

The CreateService function creates a service object and adds it to the specified service control manager database.

SC_HANDLE CreateService(

SC_HANDLE hSCManager,	// handle to service control manager database
LPCTSTR lpServiceName,	// pointer to name of service to start
LPCTSTR lpDisplayName,	// pointer to display name
DWORD dwDesiredAccess,	// type of access to service
DWORD dwServiceType,	// type of service
DWORD dwStartType,	// when to start service
DWORD dwErrorControl,	// severity if service fails to start
LPCTSTR lpBinaryPathName,	// pointer to name of binary file
LPCTSTR lpLoadOrderGroup,	// pointer to name of load ordering group
LPDWORD lpdwTagId,	// pointer to variable to get tag identifier
LPCTSTR lpDependencies,	// pointer to array of dependency names
LPCTSTR lpServiceStartName,	// pointer to account name of service
LPCTSTR lpPassword	// pointer to password for service account
);
Parameters

hSCManager

Identifies the service control manager database. This handle must have be opened using the OpenSCManager with SC_MANAGER_CREATE_SERVICE access.

lpServiceName

Points to a null-terminated string that names the service to install. The maximum string length is 256 characters. The service control manager database preserves the case of the characters, but service name comparisons are always case insensitive. Forward-slash (/) and back-slash (\) are invalid service name characters.

lpDisplayName

Points to a null-terminated string that is to be used by user interface programs to identify the service. This string has a maximum length of 256 characters. The name is case-preserved in the service control manager. Display name comparisons are always case-insensitive.

dwDesiredAccess

Specifies the access to the service. Before granting the requested access, the system checks the access token of the calling process. Any or all of the following service object access types can be specified:

Access	Description
SERVICE_ALL_ACCESS	Includes STANDARD_RIGHTS_REQUIRED in addition to all of the access types listed in this table.
SERVICE_CHANGE_CONFIG	Enables calling of the ChangeServiceConfig function to change the service configuration.
SERVICE_ENUMERATE_DEPENDENTS	Enables calling of the EnumDependentServices function to enumerate all the services dependent on the service.
SERVICE_INTERROGATE	Enables calling of the ControlService function to ask the service to report its status immediately.
SERVICE_PAUSE_CONTINUE	Enables calling of the ControlService function to pause or continue the service.
SERVICE_QUERY_CONFIG	Enables calling of the QueryServiceConfig function to query the service configuration.
SERVICE_QUERY_STATUS	Enables calling of the QueryServiceStatus function to ask the service control manager about the status of the service.
SERVICE_START	Enables calling of the StartService function to start the service.
SERVICE_STOP	Enables calling of the ControlService function to stop the service.
SERVICE_USER_DEFINED_CONTROL	Enables calling of the ControlService function to specify a user-defined control code.
The STANDARD_RIGHTS_REQUIRED constant (defined in the WINNT.H file) enables the following service object access types:

Standard rights	Description
DELETE	Enables calling of the DeleteService function to delete the service.
READ_CONTROL	Enables calling of the QueryServiceObjectSecurity function to query the security descriptor of the service object.
WRITE_DAC|WRITE_OWNER	Enables calling of the SetServiceObjectSecurity function to modify the security descriptor of the service object.
The dwDesiredAccess parameter can specify any or all of the following generic access types:

Generic access	Service access
GENERIC_READ	Combines the following accesses: STANDARD_RIGHTS_READ, SERVICE_QUERY_CONFIG, SERVICE_QUERY_STATUS, and SERVICE_ENUMERATE_DEPENDENTS.
GENERIC_WRITE	Combines the following accesses: STANDARD_RIGHTS_WRITE and SERVICE_CHANGE_CONFIG.
GENERIC_EXECUTE	Combines the following accesses: STANDARD_RIGHTS_EXECUTE, SERVICE_START, SERVICE_STOP, SERVICE_PAUSE_CONTINUE, SERVICE_INTERROGATE, and SERVICE_USER_DEFINED_CONTROL.
dwServiceType

A set of bit flags that specify the type of service. You must specify one of the following service type flags to indicate the service type. In addition, if you specify either of the SERVICE_WIN32 flags, you can also specify the SERVICE_INTERACTIVE_PROCESS flag to enable the service process to interact with the desktop.

Value	Meaning
SERVICE_WIN32_OWN_PROCESS	A service-type flag that specifies a Win32 service that runs in its own process.
SERVICE_WIN32_SHARE_PROCESS	A service-type flag that specifies a Win32 service that shares a process with other services.
SERVICE_KERNEL_DRIVER	A service-type flag that specifies a Windows NT device driver.
SERVICE_FILE_SYSTEM_DRIVER	A service-type flag that specifies a Windows NT file system driver.
SERVICE_INTERACTIVE_PROCESS	A flag that enables a Win32 service process to interact with the desktop.
dwStartType

Specifies when to start the service. This member can be one of the following values:

Value	Meaning
SERVICE_BOOT_START	Specifies a device driver started by the operating system loader. This value is valid only if the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_SYSTEM_START	Specifies a device driver started by the I/O system after boot devices such as the boot file system and disk driver have been initialized. The device driver started using this flag is not critical to the system boot. This value is valid only if the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_AUTO_START	Specifies a device driver or service started by the service control manager automatically during system startup.
SERVICE_DEMAND_START	Specifies a device driver or service started by the service control manager when a process calls the StartService function.
SERVICE_DISABLED	Specifies a device driver or Win32 service that can no longer be started.
dwErrorControl

Specifies the severity of the error if this service fails to start during startup, and determines the action taken by the startup program if failure occurs. One of the following values can be specified:

Value	Meaning
SERVICE_ERROR_IGNORE	The startup (boot) program logs the error but continues the startup operation.
SERVICE_ERROR_NORMAL	The startup program logs the error and displays a message but continues the startup operation.
SERVICE_ERROR_SEVERE	The startup program logs the error. If the last-known-good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known-good configuration.
SERVICE_ERROR_CRITICAL	The startup program logs the error, if possible. If the last-known-good configuration is being started, the startup operation fails. Otherwise, the system is restarted with the last-known-good configuration.
lpBinaryPathName

Points to a null-terminated string that contains the fully qualified path to the service binary file.

lpLoadOrderGroup

Points to a null-terminated string that names the load ordering group of which this service is a member. If the pointer is NULL or if it points to an empty string, the service does not belong to a group. The registry has a list of load ordering groups located at:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control
\ServiceGroupOrder.

The startup program uses this list to load groups of services in a specified order with respect to the other groups in the list. You can place a service in a group so that another service can depend on the group.

The order in which a service starts is determined by the following criteria:

1.	The order of groups in the registry’s load-ordering group list. Services in groups in the load-ordering group list are started first, followed by services in groups not in the load-ordering group list and then services that do not belong to a group.

2.	The service’s dependencies listed in the lpDependencies parameter and the dependencies of other services dependent on the service.

lpdwTagId

Points to a 32-bit variable that receives a unique tag value for this service in the group specified in the lpLoadOrderGroup parameter. If no tag is requested, this parameter can be NULL.

You can use a tag for ordering service startup in a load ordering group by specifying a tag order vector in the registry located at:

HKEY_LOCAL_MACHINE\System\ CurrentControlSet
\Control\GroupOrderList.

Tags are only evaluated for SERVICE_KERNEL_DRIVER and SERVICE_FILE_SYSTEM_DRIVER type services that have SERVICE_BOOT_START or SERVICE_SYSTEM_START start types.

lpDependencies

Points to an array of null-separated names of services or load ordering groups that must start before this service. The array is double null-terminated. If the pointer is NULL or if it points to an empty string, the service has no dependencies. If a group name is specified, it must be prefixed by the SC_GROUP_IDENTIFIER character (defined in the WINSVC.H file) to differentiate it from a service name, because services and service groups share the same name space. Dependency on a service means that this service can only run if the service it depends on is running. Dependency on a group means that this service can run if at least one member of the group is running after an attempt to start all members of the group.

lpServiceStartName

Points to a null-terminated string. If the service type is SERVICE_WIN32_OWN_PROCESS, this name is the account name in the form of “DomainName\Username”, which the service process will be logged on as when it runs. If the account belongs to the built-in domain, “.\Username” can be specified. Services of type SERVICE_WIN32_SHARE_PROCESS are not allowed to specify an account other than LocalSystem. If NULL is specified, the service will be logged on as the “LocalSystem” account, in which case, the lpPassword parameter must be NULL.

If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, this name is the Windows NT driver object name (that is, \FileSystem\Rdr or \Driver\Xns), which the input and output (I/O) system uses to load the device driver. If NULL is specified, the driver is run with a default object name created by the I/O system, based on the service name.

lpPassword

Points to a null-terminated string that contains the password to the account name specified by the lpServiceStartName parameter, if the service type is SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS. If the pointer is NULL or if it points to an empty string, the service has no password. If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, this parameter is ignored.

Return Values

If the function succeeds, the return value is a handle to the service.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Errors

The following error codes can be set by the service control manager. Other error codes can be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED	The handle to the specified service control manager database does not have SC_MANAGER_CREATE_SERVICE access.
ERROR_CIRCULAR_DEPENDENCY	A circular service dependency was specified.
ERROR_DUP_NAME	The display name already exists in the service control manager database either as a service name or as another display name.
ERROR_INVALID_HANDLE	The handle to the specified service control manager database is invalid.
ERROR_INVALID_NAME	The specified service name is invalid.
ERROR_INVALID_PARAMETER	A parameter that was specified is invalid.
ERROR_INVALID_SERVICE_ACCOUNT	The user account name specified in the lpServiceStartName parameter does not exist.
ERROR_SERVICE_EXISTS	The specified service already exists in this database.
Remarks

The CreateService function creates a service object and installs it in the service control manager database by creating a service name key in the registry with the following form:

HKEY_LOCAL_MACHINE\System\CurrentControlSet
\Services\lpServiceName

where lpServiceName is the service name specified for this function. Information specified for this function is saved as values under this key. Setup programs and the service itself can create any subkey under this service name key for any service specific information.

If the appropriate access rights are enabled, the calling process can use the returned handle to identify the newly created service in the following functions:

ChangeServiceConfig, ControlService, DeleteService, QueryServiceConfig, QueryServiceObjectSecurity, QueryServiceStatus, SetServiceObjectSecurity, StartService

The returned handle is only valid for the process that called CreateService. It can be closed by calling the CloseServiceHandle function.

See Also

ChangeServiceConfig, CloseServiceHandle, ControlService, DeleteService, EnumDependentServices, OpenSCManager, QueryServiceConfig, QueryServiceObjectSecurity, QueryServiceStatus, SetServiceObjectSecurity, StartService


CreateSolidBrush

The CreateSolidBrush function creates a logical brush that has the specified solid color.

HBRUSH CreateSolidBrush(

COLORREF crColor	// brush color value
);
Parameters

crColor

Specifies the color of the brush.

Return Values

If the function succeeds, the return value identifies a logical brush.

If the function fails, the return value is NULL.

Remarks

A solid brush is a bitmap that Windows uses to paint the interiors of filled shapes.

After an application creates a brush by calling CreateSolidBrush, it can select that brush into any device context by calling the SelectObject function.

See Also

CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreateHatchBrush, CreatePatternBrush, DeleteObject, SelectObject


CreateStatusWindow

The CreateStatusWindow function creates a status window, which is typically used to display the status of an application. The window generally appears at the bottom of the parent window, and it contains the specified text.

HWND CreateStatusWindow(

LONG style,
LPCTSTR lpszText,
HWND hwndParent,
UINT wID
);
Parameters

style

Window styles for the status window. This parameter must include the WS_CHILD style and should also include the WS_VISIBLE style.

lpszText

Pointer to a null-terminated string that specifies the status text for the first part.

hwndParent

Handle to the parent window.

wID

Control identifier for the status window. The window procedure uses this value to identify messages it sends to the parent window.

Return Values

If the function succeeds, the return value is the handle for the status window.

If the function fails, the return value is NULL.

Remarks

The CreateStatusWindow function calls the CreateWindow function to create the window. It passes the parameters to CreateWindow without modification and sets the position, width, and height parameters to default values.

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

CreateWindow


CreateTapePartition

The CreateTapePartition function reformats a tape.

DWORD CreateTapePartition(

HANDLE hDevice,	// handle to open device
DWORD dwPartitionMethod,	// type of new partition
DWORD dwCount,	// number of new partitions to create
DWORD dwSize	// size of new partition, in megabytes
);
Parameters

hDevice

Identifies the device where the new partition is to be created. This handle is created by using the CreateFile function.

dwPartitionMethod

Specifies the type of partition to create. To determine what type of partitions your device supports, see the documentation for your hardware. This parameter can have one of the following values:

Value	Description
TAPE_FIXED_PARTITIONS	Partitions the tape based on the device’s default definition of partitions. The dwCount and dwSize parameters are ignored.
TAPE_INITIATOR_PARTITIONS	Partitions the tape into the number and size of partitions specified by dwCount and dwSize, respectively, except for the last partition. The size of the last partition is the remainder of the tape.
TAPE_SELECT_PARTITIONS	Partitions the tape into the number of partitions specified by dwCount. The dwSize parameter is ignored. The size of the partitions is determined by the device’s default partition size. For more specific information, refer to the documentation for your tape device.
dwCount

Specifies the number of partitions to create. The GetTapeParameters function provides the maximum number of partitions a tape can support.

dwSize

Specifies the size, in megabytes, of each partition. This value is ignored if the dwPartitionMethod parameter is TAPE_SELECT_PARTITIONS.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, it may return one of the following error codes:

Error	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
Remarks

Creating partitions reformats the tape. All previous information recorded on the tape is destroyed.

See Also

CreateFile, GetTapeParameters


CreateToolbarEx

The CreateToolbarEx function creates a toolbar window and adds the specified buttons to the toolbar.

HWND CreateToolbarEx(

HWND hwnd,
DWORD ws,
UINT wID,
int nBitmaps,
HINSTANCE hBMInst,
UINT wBMID,
LPCTBBUTTON lpButtons,
int iNumButtons,
int dxButton,
int dyButton,
int dxBitmap,
int dyBitmap,
UINT uStructSize
);
Parameters

hwnd

Handle to the parent window for the toolbar.

ws

Window styles for the toolbar. This parameter must specify at least the WS_CHILD style. It can also include a combination of styles as discussed in Toolbars and related topics.

wID

Control identifier for the toolbar.

nBitmaps

Number of button images contained in the bitmap specified by hBMInst and wBMID.

hBMInst

Module instance with the executable file that contains the bitmap resource.

wBMID

Resource identifier for the bitmap resource. If hBMInst is NULL, this parameter must be a valid bitmap handle.

lpButtons

Pointer to an array of TBBUTTON structures that contains information about the buttons to add to the toolbar.

iNumButtons

Number of buttons to add to the toolbar.

dxButton

Width, in pixels, of the buttons to add to the toolbar.

dyButton

Height, in pixels, of the buttons to add to the toolbar.

dxBitmap

Width, in pixels, of the button images to add to the buttons in the toolbar.

dyBitmap

Height, in pixels, of the button images to add to the buttons in the toolbar.

uStructSize

Size of a TBBUTTON structure.

Return Values

If the function succeeds, the return value is the window handle to the toolbarl

If the function fails, the return value is NULL.

Remarks

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

TBBUTTON


CreateThread

The CreateThread function creates a thread to execute within the address space of the calling process.

HANDLE CreateThread(

LPSECURITY_ATTRIBUTES lpThreadAttributes,	// pointer to thread security attributes
DWORD dwStackSize,	// initial thread stack size, in bytes
LPTHREAD_START_ROUTINE lpStartAddress,	// pointer to thread function
LPVOID lpParameter,	// argument for new thread
DWORD dwCreationFlags,	// creation flags
LPDWORD lpThreadId	// pointer to returned thread identifier
);
Parameters

lpThreadAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpThreadAttributes is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new thread. If lpThreadAttributes is NULL, the thread gets a default security descriptor.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

dwStackSize

Specifies the size, in bytes, of the stack for the new thread. If 0 is specified, the stack size defaults to the same size as that of the primary thread of the process. The stack is allocated automatically in the memory space of the process and it is freed when the thread terminates. Note that the stack size grows, if necessary.

CreateThread tries to commit the number of bytes specified by dwStackSize, and fails if the size exceeds available memory.

lpStartAddress

The starting address of the new thread. This is typically the address of a function declared with the WINAPI calling convention that accepts a single 32-bit pointer as an argument and returns a 32-bit exit code. Its prototype is:

DWORD WINAPI ThreadFunc( LPVOID );

lpParameter

Specifies a single 32-bit parameter value passed to the thread.

dwCreationFlags

Specifies additional flags that control the creation of the thread. If the CREATE_SUSPENDED flag is specified, the thread is created in a suspended state, and will not run until the ResumeThread function is called. If this value is zero, the thread runs immediately after creation. At this time, no other values are supported.

lpThreadId

Points to a 32-bit variable that receives the thread identifier.

Return Values

If the function succeeds, the return value is a handle to the new thread.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Windows 95: CreateThread succeeds only when it is called in the context of a 32-bit program. A 32-bit DLL cannot create an additional thread when that DLL is being called by a 16-bit program.

Remarks

The new thread handle is created with full access to the new thread. If a security descriptor is not provided, the handle can be used in any function that requires a thread object handle. When a security descriptor is provided, an access check is performed on all subsequent uses of the handle before access is granted. If the access check denies access, the requesting process cannot use the handle to gain access to the thread.

The thread execution begins at the function specified by the lpStartAddress parameter. If this function returns, the DWORD return value is used to terminate the thread in an implicit call to the ExitThread function. Use the GetExitCodeThread function to get the thread’s return value.

The CreateThread function may succeed even if lpStartAddress points to data, code, or is not accessible. If the start address is invalid when the thread runs, an exception occurs, and the thread terminates. Thread termination due to a invalid start address is handled as an error exit for the thread’s process. This behavior is similar to the asynchronous nature of CreateProcess, where the process is created even if it refers to invalid or missing dynamic-link libraries (DLLs).

The thread is created with a thread priority of THREAD_PRIORITY_NORMAL. Use the GetThreadPriority and SetThreadPriority functions to get and set the priority value of a thread.

When a thread terminates, the thread object attains a signaled state, satisfying any threads that were waiting on the object.

The thread object remains in the system until the thread has terminated and all handles to it have been closed through a call to CloseHandle.

The ExitProcess, ExitThread, CreateThread, CreateRemoteThread functions, and a process that is starting (as the result of a call by CreateProcess) are serialized between each other within a process. Only one of these events can happen in an address space at a time. This means that the following restrictions hold:

•	During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.

•	Only one thread in a process can be in a DLL initialization or detach routine at a time.

•	ExitProcess does not return until no threads are in their DLL initialization or detach routines.

A thread that uses functions from the C run-time libraries should use the beginthread and endthread C run-time functions for thread management rather than CreateThread and ExitThread. Failure to do so results in small memory leaks when ExitThread is called.

See Also

CloseHandle, CreateProcess, CreateRemoteThread, ExitProcess, ExitThread, GetExitCodeThread, GetThreadPriority, ResumeThread, SetThreadPriority, SECURITY_ATTRIBUTES


CreateUpDownControl

The CreateUpDownControl function creates an up-down control.

HWND CreateUpDownControl(

DWORD dwStyle,
int x,
int y,
int cx,
int cy,
HWND hParent,
int nID,
HINSTANCE hInst
HWND hBuddy,
int nUpper,
int nLower,
int nPos
);
Parameters

dwStyle

Window styles for the control. This parameter should include the WS_CHILD, WS_BORDER, and WS_VISIBLE styles, and it may include any of the window styles specific to the up-down control.

x

Horizontal coordinate, in client coordinates, of the upper-left corner of the control.

y

Vertical coordinate, in client coordinates, of the upper-left corner of the control.

cx

Width, in pixels, of the up-down control.

cy

Height, in pixels, of the up-down control.

hParent

Handle to the parent window of the up-down control

nID

Identifier for the up-down control.

hInst

Handle to the module instance of the application creating the up-down control.

hBuddy

Handle to the window associated with the up-down control. If this parameter is NULL, the control has no buddy window.

nUpper

Upper limit (range) of the up-down control.

nLower

Lower limit (range) of the up-down control.

nPos

Position of the control.

Return Values

If the function succeeds, the return value is the window handle to the up-down control.

If the function fails, the return value is NULL.

Remarks

Windows 95: The system can support a maximum of 16,364 window handles.


CreateWaitableTimer [New - Windows NT]
CreateWaitableTimer

[New - Windows NT]

The CreateWaitableTimer function creates a “waitable” timer object.

HANDLE CreateWaitableTimer(

LPSECURITY_ATTRIBUTES lpTimerAttributes,	// pointer to security attributes
BOOL bManualReset,	// flag for manual reset state
LPCTSTR lpTimerName	// pointer to timer object name
);
Parameters

lpTimerAttributes

Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new timer object and determines whether child processes can inherit the returned handle. If lpTimerAttributes is NULL, the timer object gets a default security descriptor and the handle cannot be inherited.

bManualReset

Specifies the timer type. If bManualReset is TRUE, the timer is a manual-reset notification timer. Otherwise, the timer is a synchronization timer.

lpTimerName

Points to a null-terminated string specifying the name of the timer object. The name is limited to MAX_PATH characters and can contain any character except the backslash path-separator character (\). Name comparison is case sensitive.

If the string specified in the lpTimerName parameter matches the name of an existing named timer object, the call returns successfully and the GetLastError function returns ERROR_ALREADY_EXISTS.

If lpTimerName is NULL, the timer object is created without a name.

If lpTimerName matches the name of an existing event, semaphore, mutex, or file-mapping object, the function fails and GetLastError returns ERROR_INVALID_HANDLE. This occurs because event, semaphore, mutex, file-mapping, and waitable-timer objects share the same name space.

Return Values

If the function succeeds, the return value is a handle to the timer object. If the named timer object exists before the function call, GetLastError returns ERROR_ALREADY_EXISTS. Otherwise, GetLastError returns zero.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The handle returned by CreateWaitableTimer is created with the TIMER_ALL_ACCESS access right. This handle can be used in any function that requires a handle to a timer object.

Any thread of the calling process can specify the timer object handle in a call to one of the wait functions.

Multiple processes can have handles to the same timer object, enabling use of the object for interprocess synchronization.

•	A process created by the CreateProcess function can inherit a handle to a timer object if the lpTimerAttributes parameter of CreateWaitableTimer enables inheritance.

•	A process can specify the timer object handle in a call to the DuplicateHandle function. The resulting handle can be used by another process.

•	A process can specify the name of a timer object in a call to the OpenWaitableTimer or CreateWaitableTimer function.

Use the CloseHandle function to close the handle. The system closes the handle automatically when the process terminates. The timer object is destroyed when its last handle has been closed.

See Also

CancelWaitableTimer, CloseHandle, CreateProcess, DuplicateHandle, FILETIME, OpenWaitableTimer, SECURITY_ATTRIBUTES, SetWaitableTimer


CreateWindow

The CreateWindow function creates an overlapped, pop-up, or child window. It specifies the window class, window title, window style, and (optionally) the initial position and size of the window. The function also specifies the window’s parent or owner, if any, and the window’s menu.

HWND CreateWindow(

LPCTSTR lpClassName,	// pointer to registered class name
LPCTSTR lpWindowName,	// pointer to window name
DWORD dwStyle,	// window style
int x,	// horizontal position of window
int y,	// vertical position of window
int nWidth,	// window width
int nHeight,	// window height
HWND hWndParent,	// handle to parent or owner window
HMENU hMenu,	// handle to menu or child-window identifier
HANDLE hInstance,	// handle to application instance
LPVOID lpParam	// pointer to window-creation data
);
Parameters

lpClassName

Points to a null-terminated string or is an integer atom. If this parameter is an atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value less than 0xC000, must be in the low-order word of lpClassName; the high-order word must be zero.

If lpClassName is a string, it specifies the window class name. The class name can be any name registered with the RegisterClass function or any of the predefined control-class names. For a complete list, see the following Remarks section.

lpWindowName

Points to a null-terminated string that specifies the window name.

dwStyle

Specifies the style of the window being created. This parameter can be a combination of the window styles and control styles listed in the following Remarks section.

x

Specifies the initial horizontal position of the window. For an overlapped or pop-up window, the x parameter is the initial x-coordinate of the window’s upper-left corner, in screen coordinates. For a child window, x is the x-coordinate of the upper-left corner of the window relative to the upper-left corner of the parent window’s client area.

If this parameter is set to CW_USEDEFAULT, Windows selects the default position for the window’s upper-left corner and ignores the y parameter. CW_USEDEFAULT is valid only for overlapped windows; if it is specified for a pop-up or child window, the x and y parameters are set to zero.

y

Specifies the initial vertical position of the window. For an overlapped or pop-up window, the y parameter is the initial y-coordinate of the window’s upper-left corner, in screen coordinates. For a child window, y is the initial y-coordinate of the upper-left corner of the child window relative to the upper-left corner of the parent window’s client area. For a list box, y is the initial y-coordinate of the upper-left corner of the list box’s client area relative to the upper-left corner of the parent window’s client area.

If an overlapped window is created with the WS_VISIBLE style bit set and the x parameter is set to CW_USEDEFAULT, Windows ignores the y parameter.

nWidth

Specifies the width, in device units, of the window. For overlapped windows, nWidth is either the window’s width, in screen coordinates, or CW_USEDEFAULT. If nWidth is CW_USEDEFAULT, Windows selects a default width and height for the window; the default width extends from the initial x-coordinate to the right edge of the screen, and the default height extends from the initial y-coordinate to the top of the icon area. CW_USEDEFAULT is valid only for overlapped windows; if CW_USEDEFAULT is specified for a pop-up or child window, nWidth and nHeight are set to zero.

nHeight

Specifies the height, in device units, of the window. For overlapped windows, nHeight is the window’s height, in screen coordinates. If nWidth is set to CW_USEDEFAULT, Windows ignores nHeight.

hWndParent

Identifies the parent or owner window of the window being created. A valid window handle must be supplied when a child window or an owned window is created. A child window is confined to the client area of its parent window. An owned window is an overlapped window that is destroyed when its owner window is destroyed or hidden when its owner is minimized; it is always displayed on top of its owner window. Although this parameter must specify a valid handle if the dwStyle parameter includes the WS_CHILD style, it is optional if dwStyle includes the WS_POPUP style.

hMenu

Identifies a menu, or specifies a child-window identifier depending on the window style. For an overlapped or pop-up window, hMenu identifies the menu to be used with the window; it can be NULL if the class menu is to be used. For a child window, hMenu specifies the child-window identifier, an integer value used by a dialog box control to notify its parent about events. The application determines the child-window identifier; it must be unique for all child windows with the same parent window.

hInstance

Identifies the instance of the module to be associated with the window.

lpParam

Points to a value passed to the window through the CREATESTRUCT structure referenced by the lParam parameter of the WM_CREATE message. If an application calls CreateWindow to create a multiple document interface (MDI) client window, lpParam must point to a CLIENTCREATESTRUCT structure.

Return Values

If the function succeeds, the return value is the handle to the new window.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Before returning, CreateWindow sends a WM_CREATE message to the window procedure.

For overlapped, pop-up, and child windows, CreateWindow sends WM_CREATE, WM_GETMINMAXINFO, and WM_NCCREATE messages to the window. The lParam parameter of the WM_CREATE message contains a pointer to a CREATESTRUCT structure. If the WS_VISIBLE style is specified, CreateWindow sends the window all the messages required to activate and show the window.

If the window style specifies a title bar, the window title pointed to by lpWindowName is displayed in the title bar. When using CreateWindow to create controls, such as buttons, check boxes, and static controls, use lpWindowName to specify the text of the control.

If you specify Windows version 4.x when linking your application, its windows cannot have caption buttons unless they also have window menus. This is not a requirement for applications that you linked specifying Windows version 3.x.

The following predefined control classes can be specified in the lpClassName parameter:

Class	Meaning
BUTTON	Designates a small rectangular child window that represents a button the user can click to turn it on or off. Button controls can be used alone or in groups, and they can either be labeled or appear without text. Button controls typically change appearance when the user clicks them.
COMBOBOX	Designates a control consisting of a list box and a selection field similar to an edit control. When using this style, an application should either display the list box at all times or enable a drop-down list box.
	Depending on the style of the combo box, the user can or cannot edit the contents of the selection field. If the list box is visible, typing characters into the selection field highlights the first list box entry that matches the characters typed. Conversely, selecting an item in the list box displays the selected text in the selection field.
EDIT	Designates a rectangular child window into which the user can type text from the keyboard. The user selects the control and gives it the keyboard focus by clicking it or moving to it by pressing the TAB key. The user can type text when the edit control displays a flashing caret; use the mouse to move the cursor, select characters to be replaced, or position the cursor for inserting characters; or use the BACKSPACE key to delete characters.
	Edit controls use the variable-pitch system font and display characters from the ANSI character set. The WM_SETFONT message can also be sent to the edit control to change the default font.
	Edit controls expand tab characters into as many space characters as are required to move the caret to the next tab stop. Tab stops are assumed to be at every eighth character position.
LISTBOX	Designates a list of character strings. Specify this control whenever an application must present a list of names, such as filenames, from which the user can choose. The user can select a string by clicking it. A selected string is highlighted, and a notification message is passed to the parent window. Use a vertical or horizontal scroll bar with a list box to scroll lists that are too long for the control window. The list box automatically hides or shows the scroll bar, as needed.
MDICLIENT	Designates an MDI client window. This window receives messages that control the MDI application’s child windows. The recommended style bits are WS_CLIPCHILDREN and WS_CHILD. Specify the WS_HSCROLL and WS_VSCROLL styles to create an MDI client window that allows the user to scroll MDI child windows into view.
SCROLLBAR	Designates a rectangle that contains a scroll box and has direction arrows at both ends. The scroll bar sends a notification message to its parent window whenever the user clicks the control. The parent window is responsible for updating the position of the scroll box, if necessary. Scroll bar controls have the same appearance and function as scroll bars used in ordinary windows. Unlike scroll bars, however, scroll bar controls can be positioned anywhere in a window for use whenever scrolling input is needed for a window.
	The scroll bar class also includes size box controls. A size box is a small rectangle the user can expand to change the size of the window.
STATIC	Designates a simple text field, box, or rectangle used to label, box, or separate other controls. Static controls take no input and provide no output.
The following window styles can be specified in the dwStyle parameter:

Style	Meaning
WS_BORDER	Creates a window that has a thin-line border.
WS_CAPTION	Creates a window that has a title bar (includes the WS_BORDER style).
WS_CHILD	Creates a child window. This style cannot be used with the WS_POPUP style.
WS_CHILDWINDOW	Same as the WS_CHILD style.
WS_CLIPCHILDREN	Excludes the area occupied by child windows when drawing occurs within the parent window. This style is used when creating the parent window.
WS_CLIPSIBLINGS	Clips child windows relative to each other; that is, when a particular child window receives a WM_PAINT message, the WS_CLIPSIBLINGS style clips all other overlapping child windows out of the region of the child window to be updated. If WS_CLIPSIBLINGS is not specified and child windows overlap, it is possible, when drawing within the client area of a child window, to draw within the client area of a neighboring child window.
WS_DISABLED	Creates a window that is initially disabled. A disabled window cannot receive input from the user.
WS_DLGFRAME	Creates a window that has a border of a style typically used with dialog boxes. A window with this style cannot have a title bar.
WS_GROUP	Specifies the first control of a group of controls. The group consists of this first control and all  controls defined after it, up to the next control with the WS_GROUP style. The first control in each group usually has the WS_TABSTOP style so that the user can move from group to group. The user can subsequently change the keyboard focus from one control in the group to the next control in the group by using the direction keys.
WS_HSCROLL	Creates a window that has a horizontal scroll bar.
WS_ICONIC	Creates a window that is initially minimized. Same as the WS_MINIMIZE style.
WS_MAXIMIZE	Creates a window that is initially maximized.
WS_MAXIMIZEBOX	Creates a window that has a Maximize button. Cannot be combined with the WS_EX_CONTEXTHELP style. The WS_SYSMENU style must also be specified.
WS_MINIMIZE	Creates a window that is initially minimized. Same as the WS_ICONIC style.
WS_MINIMIZEBOX	Creates a window that has a Minimize button. Cannot be combined with the WS_EX_CONTEXTHELP style. The WS_SYSMENU style must also be specified.
WS_OVERLAPPED	Creates an overlapped window. An overlapped window has a title bar and a border. Same as the WS_TILED style.
WS_OVERLAPPEDWINDOW	Creates an overlapped window with the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles. Same as the WS_TILEDWINDOW style.
WS_POPUP	Creates a pop-up window. This style cannot be used with the WS_CHILD style.
WS_POPUPWINDOW	Creates a pop-up window with WS_BORDER, WS_POPUP, and WS_SYSMENU styles. The WS_CAPTION and WS_POPUPWINDOW styles must be combined to make the window menu visible.
WS_SIZEBOX	Creates a window that has a sizing border. Same as the WS_THICKFRAME style.
WS_SYSMENU	Creates a window that has a window-menu on its title bar. The WS_CAPTION style must also be specified.
WS_TABSTOP	Specifies a control that can receive the keyboard focus when the user presses the TAB key. Pressing the TAB key changes the keyboard focus to the next control with the WS_TABSTOP style.
WS_THICKFRAME	Creates a window that has a sizing border. Same as the WS_SIZEBOX style.
WS_TILED	Creates an overlapped window. An overlapped window has a title bar and a border. Same as the WS_OVERLAPPED style.
WS_TILEDWINDOW	Creates an overlapped window with the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles. Same as the WS_OVERLAPPEDWINDOW style.
WS_VISIBLE	Creates a window that is initially visible.
WS_VSCROLL	Creates a window that has a vertical scroll bar.
The following button styles (in the BUTTON class) can be specified in the dwStyle parameter:

Style	Meaning
BS_3STATE	Creates a button that is the same as a check box, except that the box can be grayed as well as checked or unchecked. Use the grayed state to show that the state of the check box is not determined.
BS_AUTO3STATE	Creates a button that is the same as a three-state check box, except that the box changes its state when the user selects it. The state cycles through checked, grayed, and unchecked.
BS_AUTOCHECKBOX	Creates a button that is the same as a check box, except that the check state automatically toggles between checked and unchecked each time the user selects the check box.
BS_AUTORADIOBUTTON	Creates a button that is the same as a radio button, except that when the user selects it, Windows automatically sets the button’s check state to checked and automatically sets the check state for all other buttons in the same group to unchecked.
BS_CHECKBOX	Creates a small, empty check box with text. By default, the text is displayed to the right of the check box. To display the text to the left of the check box, combine this flag with the BS_LEFTTEXT style (or with the equivalent BS_RIGHTBUTTON style).
BS_DEFPUSHBUTTON	Creates a push button that behaves like a BS_PUSHBUTTON style button, but also has a heavy black border. If the button is in a dialog box, the user can select the button by pressing the ENTER key, even when the button does not have the input focus. This style is useful for enabling the user to quickly select the most likely (default) option.
BS_GROUPBOX	Creates a rectangle in which other controls can be grouped. Any text associated with this style is displayed in the rectangle’s upper left corner.
BS_LEFTTEXT	Places text on the left side of the radio button or check box when combined with a radio button or check box style. Same as the BS_RIGHTBUTTON style.
BS_OWNERDRAW	Creates an owner-drawn button. The owner window receives a WM_MEASUREITEM message when the button is created and a WM_DRAWITEM message when a visual aspect of the button has changed. Do not combine the BS_OWNERDRAW style with any other button styles.
BS_PUSHBUTTON	Creates a push button that posts a WM_COMMAND message to the owner window when the user selects the button.
BS_RADIOBUTTON	Creates a small circle with text. By default, the text is displayed to the right of the circle. To display the text to the left of the circle, combine this flag with the BS_LEFTTEXT style (or with the equivalent BS_RIGHTBUTTON style). Use radio buttons for groups of related, but mutually exclusive choices.
BS_USERBUTTON	Obsolete, but provided for compatibility with 16-bit versions of Windows. Win32-based applications should use BS_OWNERDRAW instead.
BS_BITMAP	Specifies that the button displays a bitmap.
BS_BOTTOM	Places text at the bottom of the button rectangle.
BS_CENTER	Centers text horizontally in the button rectangle.
BS_ICON	Specifies that the button displays an icon.
BS_LEFT	Left-justifies the text in the button rectangle. However, if the button is a check box or radio button that does not have the BS_RIGHTBUTTON style, the text is left justified on the right side of the check box or radio button.
BS_MULTILINE	Wraps the button text to multiple lines if the text string is too long to fit on a single line in the button rectangle.
BS_NOTIFY	Enables a button to send BN_DBLCLK, BN_KILLFOCUS, and BN_SETFOCUS notification messages to its parent window. Note that buttons send the BN_CLICKED notification message regardless of whether it has this style.
BS_PUSHLIKE	Makes a button (such as a check box, three-state check box, or radio button) look and act like a push button. The button looks raised when it isn’t pushed or checked, and sunken when it is pushed or checked.
BS_RIGHT	Right-justifies text in the button rectangle. However, if the button is a check box or radio button that does not have the BS_RIGHTBUTTON style, the text is right justified on the right side of the check box or radio button.
BS_RIGHTBUTTON	Positions a radio button’s circle or a check box’s square on the right side of the button rectangle. Same as the BS_LEFTTEXT style.
BS_TEXT	Specifies that the button displays text.
BS_TOP	Places text at the top of the button rectangle.
BS_VCENTER	Places text in the middle (vertically) of the button rectangle.
The following combo box styles (in the COMBOBOX class) can be specified in the dwStyle parameter:

Style	Meaning
CBS_AUTOHSCROLL	Automatically scrolls the text in an edit control to the right when the user types a character at the end of the line. If this style is not set, only text that fits within the rectangular boundary is allowed.
CBS_DISABLENOSCROLL	Shows a disabled vertical scroll bar in the list box when the box does not contain enough items to scroll. Without this style, the scroll bar is hidden when the list box does not contain enough items.
CBS_DROPDOWN	Similar to CBS_SIMPLE, except that the list box is not displayed unless the user selects an icon next to the edit control.
CBS_DROPDOWNLIST	Similar to CBS_DROPDOWN, except that the edit control is replaced by a static text item that displays the current selection in the list box.
CBS_HASSTRINGS	Specifies that an owner-drawn combo box contains items consisting of strings. The combo box maintains the memory and address for the strings, so the application can use the CB_GETLBTEXT message to retrieve the text for a particular item.
CBS_LOWERCASE	Converts to lowercase any uppercase characters entered into the edit control of a combo box.
CBS_NOINTEGRALHEIGHT	Specifies that the size of the combo box is exactly the size specified by the application when it created the combo box. Normally, Windows sizes a combo box so that it does not display partial items.
CBS_OEMCONVERT	Converts text entered in the combo box edit control. The text is converted from the Windows character set to the OEM character set and then back to the Windows set. This ensures proper character conversion when the application calls the CharToOem function to convert a Windows string in the combo box to OEM characters. This style is most useful for combo boxes that contain filenames and applies only to combo boxes created with the CBS_SIMPLE or CBS_DROPDOWN style.
CBS_OWNERDRAWFIXED	Specifies that the owner of the list box is responsible for drawing its contents and that the items in the list box are all the same height. The owner window receives a WM_MEASUREITEM message when the combo box is created and a WM_DRAWITEM message when a visual aspect of the combo box has changed.
CBS_OWNERDRAWVARIABLE	Specifies that the owner of the list box is responsible for drawing its contents and that the items in the list box are variable in height. The owner window receives a WM_MEASUREITEM message for each item in the combo box when you create the combo box; the owner window receives a WM_DRAWITEM message when a visual aspect of the combo box has changed.
CBS_SIMPLE	Displays the list box at all times. The current selection in the list box is displayed in the edit control.
CBS_SORT	Automatically sorts strings entered into the list box.
CBS_UPPERCASE	Converts to uppercase any lowercase characters entered into the edit control of a combo box.
The following edit control styles (in the EDIT class) can be specified in the dwStyle parameter:

Style	Meaning
ES_AUTOHSCROLL	Automatically scrolls text to the right by 10 characters when the user types a character at the end of the line. When the user presses the ENTER key, the control scrolls all text back to position zero.
ES_AUTOVSCROLL	Automatically scrolls text up one page when the user presses the ENTER key on the last line.
ES_CENTER	Centers text in a multiline edit control.
ES_LEFT	Left-aligns text.
ES_LOWERCASE	Converts all characters to lowercase as they are typed into the edit control.
ES_MULTILINE	Designates a multiline edit control. The default is single-line edit control.
	When the multiline edit control is in a dialog box, the default response to pressing the ENTER key is to activate the default button. To use the ENTER key as a carriage return, use the ES_WANTRETURN style.
	When the multiline edit control is not in a dialog box and the ES_AUTOVSCROLL style is specified, the edit control shows as many lines as possible and scrolls vertically when the user presses the ENTER key. If you do not specify ES_AUTOVSCROLL, the edit control shows as many lines as possible and beeps if the user presses the ENTER key when no more lines can be displayed.
	If you specify the ES_AUTOHSCROLL style, the multiline edit control automatically scrolls horizontally when the caret goes past the right edge of the control. To start a new line, the user must press the ENTER key. If you do not specify ES_AUTOHSCROLL, the control automatically wraps words to the beginning of the next line when necessary. A new line is also started if the user presses the ENTER key. The window size determines the position of the word wrap. If the window size changes, the word wrapping position changes and the text is redisplayed.
	Multiline edit controls can have scroll bars. An edit control with scroll bars processes its own scroll bar messages. Note that edit controls without scroll bars scroll as described in the previous paragraphs and process any scroll messages sent by the parent window.
ES_NOHIDESEL	Negates the default behavior for an edit control. The default behavior hides the selection when the control loses the input focus and inverts the selection when the control receives the input focus. If you specify ES_NOHIDESEL, the selected text is inverted, even if the control does not have the focus.
ES_NUMBER	Allows only digits to be entered into the edit control.
ES_OEMCONVERT	Converts text entered in the edit control. The text is converted from the Windows character set to the OEM character set and then back to the Windows set. This ensures proper character conversion when the application calls the CharToOem function to convert a Windows string in the edit control to OEM characters. This style is most useful for edit controls that contain filenames.
ES_PASSWORD	Displays an asterisk (*) for each character typed into the edit control. You can use the EM_SETPASSWORDCHAR message to change the character that is displayed.
ES_READONLY	Prevents the user from typing or editing text in the edit control.
ES_RIGHT	Right-aligns text in a multiline edit control.
ES_UPPERCASE	Converts all characters to uppercase as they are typed into the edit control.
ES_WANTRETURN	Specifies that a carriage return be inserted when the user presses the ENTER key while entering text into a multiline edit control in a dialog box. If you do not specify this style, pressing the ENTER key has the same effect as pressing the dialog box’s default push button. This style has no effect on a single-line edit control.
The following list box control styles (in the LISTBOX class) can be specified in the dwStyle parameter:

Style	Meaning
LBS_DISABLENOSCROLL	Shows a disabled vertical scroll bar for the list box when the box does not contain enough items to scroll. If you do not specify this style, the scroll bar is hidden when the list box does not contain enough items.
LBS_EXTENDEDSEL	Allows multiple items to be selected by using the SHIFT key and the mouse or special key combinations.
LBS_HASSTRINGS	Specifies that a list box contains items consisting of strings. The list box maintains the memory and addresses for the strings so the application can use the LB_GETTEXT message to retrieve the text for a particular item. By default, all list boxes except owner-drawn list boxes have this style. You can create an owner-drawn list box either with or without this style.
LBS_MULTICOLUMN	Specifies a multicolumn list box that is scrolled horizontally. The LB_SETCOLUMNWIDTH message sets the width of the columns.
LBS_MULTIPLESEL	Turns string selection on or off each time the user clicks or double-clicks a string in the list box. The user can select any number of strings.
LBS_NODATA	Specifies a no-data list box. Specify this style when the count of items in the list box will exceed one thousand. A no-data list box must also have the LBS_OWNERDRAWFIXED style, but must not have the LBS_SORT or LBS_HASSTRINGS style.
	A no-data list box resembles an owner-drawn list box except that it contains no string or bitmap data for an item. Commands to add, insert, or delete an item always ignore any given item data; requests to find a string within the list box always fail. Windows sends the WM_DRAWITEM message to the owner window when an item must be drawn. The itemID member of the DRAWITEMSTRUCT structure passed with the WM_DRAWITEM message specifies the line number of the item to be drawn. A no-data list box does not send a WM_DELETEITEM message.
LBS_NOINTEGRALHEIGHT	Specifies that the size of the list box is exactly the size specified by the application when it created the list box. Normally, Windows sizes a list box so that the list box does not display partial items.
LBS_NOREDRAW	Specifies that the list box’s appearance is not updated when changes are made. You can change this style at any time by sending a WM_SETREDRAW message.
LBS_NOSEL	Specifies that the list box contains items that can be viewed but not selected.
LBS_NOTIFY	Notifies the parent window with an input message whenever the user clicks or double-clicks a string in the list box.
LBS_OWNERDRAWFIXED	Specifies that the owner of the list box is responsible for drawing its contents and that the items in the list box are the same height. The owner window receives a WM_MEASUREITEM message when the list box is created and a WM_DRAWITEM message when a visual aspect of the list box has changed.
LBS_OWNERDRAWVARIABLE	Specifies that the owner of the list box is responsible for drawing its contents and that the items in the list box are variable in height. The owner window receives a WM_MEASUREITEM message for each item in the combo box when the combo box is created and a WM_DRAWITEM message when a visual aspect of the combo box has changed.
LBS_SORT	Sorts strings in the list box alphabetically.
LBS_STANDARD	Sorts strings in the list box alphabetically. The parent window receives an input message whenever the user clicks or double-clicks a string. The list box has borders on all sides.
LBS_USETABSTOPS	Enables a list box to recognize and expand tab characters when drawing its strings. The default tab positions are 32 dialog box units. A dialog box unit is a horizontal or vertical distance. One horizontal dialog box unit is equal to one-fourth of the current dialog box base-width unit. Windows calculates these units based on the height and width of the current system font. The GetDialogBaseUnits function returns the current dialog box base units in pixels.
LBS_WANTKEYBOARDINPUT	Specifies that the owner of the list box receives WM_VKEYTOITEM messages whenever the user presses a key and the list box has the input focus. This enables an application to perform special processing on the keyboard input.
The following scroll bar styles (in the SCROLLBAR class) can be specified in the dwStyle parameter:

Style	Meaning
SBS_BOTTOMALIGN	Aligns the bottom edge of the scroll bar with the bottom edge of the rectangle defined by the parameters x, y, nWidth, and nHeight. The scroll bar has the default height for system scroll bars. Use this style with the SBS_HORZ style.
SBS_HORZ	Designates a horizontal scroll bar. If neither the SBS_BOTTOMALIGN nor SBS_TOPALIGN style is specified, the scroll bar has the height, width, and position defined by x, y, nWidth, and nHeight.
SBS_LEFTALIGN	Aligns the left edge of the scroll bar with the left edge of the rectangle defined by the parameters x, y, nWidth, and nHeight. The scroll bar has the default width for system scroll bars. Use this style with the SBS_VERT style.
SBS_RIGHTALIGN	Aligns the right edge of the scroll bar with the right edge of the rectangle defined by the parameters x, y, nWidth, and nHeight. The scroll bar has the default width for system scroll bars. Use this style with the SBS_VERT style.
SBS_SIZEBOX	Designates a size box. If you specify neither the SBS_SIZEBOXBOTTOMRIGHTALIGN nor the SBS_SIZEBOXTOPLEFTALIGN style, the size box has the height, width, and position specified by the parameters x, y, nWidth, and nHeight.
SBS_SIZEBOXBOTTOMRIGHTALIGN	Aligns the lower-right corner of the size box with the lower-right corner of the rectangle specified by the parameters x, y, nWidth, and nHeight. The size box has the default size for system size boxes. Use this style with the SBS_SIZEBOX style.
SBS_SIZEBOXTOPLEFTALIGN	Aligns the upper-left corner of the size box with the upper-left corner of the rectangle specified by the parameters x, y, nWidth, and nHeight. The size box has the default size for system size boxes. Use this style with the SBS_SIZEBOX style.
SBS_SIZEGRIP	Same as SBS_SIZEBOX, but with a raised edge.
SBS_TOPALIGN	Aligns the top edge of the scroll bar with the top edge of the rectangle defined by the parameters x, y, nWidth, and nHeight. The scroll bar has the default height for system scroll bars. Use this style with the SBS_HORZ style.
SBS_VERT	Designates a vertical scroll bar. If you specify neither the SBS_RIGHTALIGN nor the SBS_LEFTALIGN style, the scroll bar has the height, width, and position specified by the parameters x, y, nWidth, and nHeight.
The following static control styles (in the STATIC class) can be specified in the dwStyle parameter. A static control can have only one of these styles:

Style	Description
SS_BITMAP	Specifies a bitmap is to be displayed in the static control. The error code text is the name of a bitmap (not a filename) defined elsewhere in the resource file. The style ignores the nWidth and nHeight parameters; the control automatically sizes itself to accommodate the bitmap.
SS_BLACKFRAME	Specifies a box with a frame drawn in the same color as the window frames. This color is black in the default Windows color scheme.
SS_BLACKRECT	Specifies a rectangle filled with the current window frame color. This color is black in the default Windows color scheme.
SS_CENTER	Specifies a simple rectangle and centers the error code text in the rectangle. The text is formatted before it is displayed. Words that extend past the end of a line are automatically wrapped to the beginning of the next centered line.
SS_CENTERIMAGE	Specifies that the midpoint of a static control with the SS_BITMAP or SS_ICON style is to remain fixed when the control is resized. The four sides are adjusted to accommodate a new bitmap or icon. If a static control has the SS_BITMAP style and the bitmap is smaller than the control’s client area, the client area is filled with the color of the pixel in the upper-left corner of the bitmap. If a static control has the SS_ICON style, the icon does not appear to paint the client area.
SS_GRAYFRAME	Specifies a box with a frame drawn with the same color as the screen background (desktop). This color is gray in the default Windows color scheme.
SS_GRAYRECT	Specifies a rectangle filled with the current screen background color. This color is gray in the default Windows color scheme.
SS_ICON	Specifies an icon displayed in the dialog box. The given text is the name of an icon (not a filename) defined elsewhere in the resource file. The style ignores the nWidth and nHeight parameters; the icon automatically sizes itself.
SS_LEFT	Specifies a simple rectangle and left-aligns the given text in the rectangle. The text is formatted before it is displayed. Words that extend past the end of a line are automatically wrapped to the beginning of the next left-aligned line.
SS_LEFTNOWORDWRAP	Specifies a simple rectangle and left-aligns the given text in the rectangle. Tabs are expanded but words are not wrapped. Text that extends past the end of a line is clipped.
SS_METAPICT	Specifies a metafile picture is to be displayed in the static control. The given text is the name of a metafile picture (not a filename) defined elsewhere in the resource file. A metafile static control has a fixed size; the metafile picture is scaled to fit the static control’s client area.
SS_NOPREFIX	Prevents interpretation of any ampersand (&) characters in the control’s text as accelerator prefix characters. These are displayed with the ampersand removed and the next character in the string underlined. This static control style may be included with any of the defined static controls.
	An application can combine SS_NOPREFIX with other styles by using the bitwise OR (|) operator. This can be useful when filenames or other strings that may contain an ampersand (&) must be displayed in a static control in a dialog box.
SS_NOTIFY	Sends the parent window STN_CLICKED and STN_DBLCLK notification messages when the user clicks or double clicks the control.
SS_RIGHT	Specifies a simple rectangle and right-aligns the given text in the rectangle. The text is formatted before it is displayed. Words that extend past the end of a line are automatically wrapped to the beginning of the next right-aligned line.
SS_RIGHTIMAGE	Specifies that the bottom-right corner of a static control with the SS_BITMAP or SS_ICON style is to remain fixed when the control is resized. Only the top and left sides are adjusted to accommodate a new bitmap or icon.
SS_SIMPLE	Specifies a simple rectangle and displays a single line of left-aligned text in the rectangle. The text line cannot be shortened or altered in any way. The control’s parent window or dialog box must not process the WM_CTLCOLORSTATIC message.
SS_WHITEFRAME	Specifies a box with a frame drawn with the same color as the window backgrounds. This color is white in the default Windows color scheme.
SS_WHITERECT	Specifies a rectangle filled with the current window background color. This color is white in the default Windows color scheme.
The following dialog box styles can be specified in the dwStyle parameter:

Style	Meaning
DS_3DLOOK	Gives the dialog box a nonbold font and draws three-dimensional borders around control windows in the dialog box. The DS_3DLOOK style is required only by Win32-based applications compiled for versions of Windows earlier than Windows 95 or Windows NT 4.0. The system automatically applies the three-dimensional look to dialog boxes created by applications compiled for current versions of Windows.
DS_ABSALIGN	Indicates that the coordinates of the dialog box are screen coordinates; otherwise, Windows assumes they are client coordinates.
DS_CENTER	Centers the dialog box in the working area; that is, the area not obscured by the tray.
DS_CENTERMOUSE	Centers the mouse cursor in the dialog box.
DS_CONTEXTHELP	Includes a question mark in the title bar of the dialog box. When the user clicks the question mark, the cursor changes to a question mark with a pointer. If the user then clicks a control in the dialog box, the control receives a WM_HELP message. The control should pass the message to the dialog procedure, which should call the WinHelp function using the HELP_WM_HELP command. The Help application displays a pop-up window that typically contains help for the control. Note that DS_CONTEXTHELP is just a placeholder. When the dialog box is created, the system checks for DS_CONTEXTHELP and, if it is there, adds WS_EX_CONTEXTHELP to the extended style of the dialog box. WS_EX_CONTEXTHELP cannot be used with the WS_MAXIMIZEBOX or WS_MINIMIZEBOX styles.
DS_CONTROL	Creates a dialog box that works well as a child window of another dialog box, much like a page in a property sheet. This style allows the user to tab among the control windows of a child dialog box, use its accelerator keys, and so on.
DS_FIXEDSYS	Use SYSTEM_FIXED_FONT instead of SYSTEM_FONT.
DS_LOCALEDIT	Applies to 16-bit applications only. This style directs edit controls in the dialog box to allocate memory from the application’s data segment. Otherwise, edit controls allocate storage from a global memory object.
DS_MODALFRAME	Creates a dialog box with a modal dialog-box frame that can be combined with a title bar and window menu by specifying the WS_CAPTION and WS_SYSMENU styles.
DS_NOFAILCREATE	Creates the dialog box even if errors occur — for example, if a child window cannot be created or if the system cannot create a special data segment for an edit control.
DS_NOIDLEMSG	Suppresses WM_ENTERIDLE messages that Windows would otherwise send to the owner of the dialog box while the dialog box is displayed.
DS_RECURSE	Dialog box style for control-like dialog boxes.
DS_SETFONT	Indicates that the dialog box template (the DLGTEMPLATE structure) contains two additional members specifying a font name and point size. The corresponding font is used to display text within the dialog box client area and within the dialog box controls. Windows passes the handle of the font to the dialog box and to each control by sending them the WM_SETFONT message.
DS_SETFOREGROUND	Does not apply to 16-bit versions of Microsoft Windows. This style brings the dialog box to the foreground. Internally, Windows calls the SetForegroundWindow function for the dialog box.
DS_SYSMODAL	Creates a system-modal dialog box. This style causes the dialog box to have the WS_EX_TOPMOST style, but otherwise has no effect on the dialog box or the behavior of other windows in the system when the dialog box is displayed.
Windows 95: The system can support a maximum of 16,364 window handles.

See Also

CharToOem, CLIENTCREATESTRUCT, CreateDialog, CREATESTRUCT, CreateWindowEx, DialogBox, DLGTEMPLATE, DRAWITEMSTRUCT, GetDialogBaseUnits, GlobalAddAtom, LB_GETTEXT, LB_SETCOLUMNWIDTH, MessageBox, RegisterClass, SetForegroundWindow, WM_COMMAND, WM_CREATE, WM_DELETEITEM, WM_DRAWITEM, WM_ENTERIDLE, WM_GETMINMAXINFO, WM_MEASUREITEM, WM_NCCREATE, WM_PAINT, WM_SETFONT, WM_SETREDRAW, WM_VKEYTOITEM


CreateWindowEx

The CreateWindowEx function creates an overlapped, pop-up, or child window with an extended style; otherwise, this function is identical to the CreateWindow function. For more information about creating a window and for full descriptions of the other parameters of CreateWindowEx, see CreateWindow.

HWND CreateWindowEx(

DWORD dwExStyle,	// extended window style
LPCTSTR lpClassName,	// pointer to registered class name
LPCTSTR lpWindowName,	// pointer to window name
DWORD dwStyle,	// window style
int x,	// horizontal position of window
int y,	// vertical position of window
int nWidth,	// window width
int nHeight,	// window height
HWND hWndParent,	// handle to parent or owner window
HMENU hMenu,	// handle to menu, or child-window identifier
HINSTANCE hInstance,	// handle to application instance
LPVOID lpParam	// pointer to window-creation data
);
Parameters

dwExStyle

Specifies the extended style of the window. This parameter can be one of the following values:

Style	Meaning
WS_EX_ACCEPTFILES	Specifies that a window created with this style accepts drag-drop files.
WS_EX_APPWINDOW	Forces a top-level window onto the taskbar when the window is minimized.
WS_EX_CLIENTEDGE	Specifies that a window has a border with a sunken edge.
WS_EX_CONTEXTHELP	Includes a question mark in the title bar of the window. When the user clicks the question mark, the cursor changes to a question mark with a pointer. If the user then clicks a child window, the child receives a WM_HELP message. The child window should pass the message to the parent window procedure, which should call the WinHelp function using the HELP_WM_HELP command. The Help application displays a pop-up window that typically contains help for the child window. WS_EX_CONTEXTHELP cannot be used with the WS_MAXIMIZEBOX or WS_MINIMIZEBOX styles.
WS_EX_CONTROLPARENT	Allows the user to navigate among the child windows of the window by using the TAB key.
WS_EX_DLGMODALFRAME	Creates a window that has a double border; the window can, optionally, be created with a title bar by specifying the WS_CAPTION style in the dwStyle parameter.
WS_EX_LEFT	Window has generic “left-aligned” properties. This is the default.
WS_EX_LEFTSCROLLBAR	If the shell language is Hebrew, Arabic, or another language that supports reading order alignment, the vertical scroll bar (if present) is to the left of the client area. For other languages, the style is ignored and not treated as an error.
WS_EX_LTRREADING	The window text is displayed using Left to Right reading-order properties. This is the default.
WS_EX_MDICHILD	Creates an MDI child window.
WS_EX_NOPARENTNOTIFY	Specifies that a child window created with this style does not send the WM_PARENTNOTIFY message to its parent window when it is created or destroyed.
WS_EX_OVERLAPPEDWINDOW	Combines the WS_EX_CLIENTEDGE and WS_EX_WINDOWEDGE styles.
WS_EX_PALETTEWINDOW	Combines the WS_EX_WINDOWEDGE, WS_EX_TOOLWINDOW, and WS_EX_TOPMOST styles.
WS_EX_RIGHT	Window has generic “right-aligned” properties. This depends on the window class. This style has an effect only if the shell language is Hebrew, Arabic, or another language that supports reading order alignment; otherwise, the style is ignored and not treated as an error.
WS_EX_RIGHTSCROLLBAR	Vertical scroll bar (if present) is to the right of the client area. This is the default.
WS_EX_RTLREADING	If the shell language is Hebrew, Arabic, or another language that supports reading order alignment, the window text is displayed using Right to Left reading-order properties. For other languages, the style is ignored and not treated as an error.
WS_EX_STATICEDGE	Creates a window with a three-dimensional border style intended to be used for items that do not accept user input.
WS_EX_TOOLWINDOW	Creates a tool window; that is, a window intended to be used as a floating toolbar. A tool window has a title bar that is shorter than a normal title bar, and the window title is drawn using a smaller font. A tool window does not appear in the taskbar or in the dialog that appears when the user presses ALT+TAB.
WS_EX_TOPMOST	Specifies that a window created with this style should be placed above all non-topmost windows and should stay above them, even when the window is deactivated. To add or remove this style, use the SetWindowPos function.
WS_EX_TRANSPARENT	Specifies that a window created with this style is to be transparent. That is, any windows that are beneath the window are not obscured by the window. A window created with this style receives WM_PAINT messages only after all sibling windows beneath it have been updated.
WS_EX_WINDOWEDGE	Specifies that a window has a border with a raised edge.
Using the WS_EX_RIGHT style for static or edit controls has the same effect as using the SS_RIGHT or ES_RIGHT style, respectively. Using this style with button controls has the same effect as using BS_RIGHT and BS_RIGHTBUTTON styles.

lpClassName

Points to a null-terminated string or is an integer atom. If lpClassName is an atom, it must be a global atom created by a previous call to GlobalAddAtom. The atom, a 16-bit value less than 0xC000, must be in the low-order word of lpClassName; the high-order word must be zero.

If lpClassName is a string, it specifies the window class name. The class name can be any name registered with the RegisterClass function or any of the predefined control-class names.

lpWindowName

Points to a null-terminated string that specifies the window name.

dwStyle

Specifies the style of the window being created. For a list of the window styles that can be specified in dwStyle, see CreateWindow.

x

Specifies the initial horizontal position of the window. For an overlapped or pop-up window, the x parameter is the initial x-coordinate of the window’s upper-left corner, in screen coordinates. For a child window, x is the x-coordinate of the upper-left corner of the window relative to the upper-left corner of the parent window’s client area.

If x is set to CW_USEDEFAULT, Windows selects the default position for the window’s upper-left corner and ignores the y parameter. CW_USEDEFAULT is valid only for overlapped windows; if it is specified for a pop-up or child window, the x and y parameters are set to zero.

y

Specifies the initial vertical position of the window. For an overlapped or pop-up window, the y parameter is the initial y-coordinate of the window’s upper-left corner, in screen coordinates. For a child window, y is the initial y-coordinate of the upper-left corner of the child window relative to the upper-left corner of the parent window’s client area. For a list box, y is the initial y-coordinate of the upper-left corner of the list box’s client area relative to the upper-left corner of the parent window’s client area.

If an overlapped window is created with the WS_VISIBLE style bit set and the x parameter is set to CW_USEDEFAULT, Windows ignores the y parameter.

nWidth

Specifies the width, in device units, of the window. For overlapped windows, nWidth is the window’s width, in screen coordinates, or CW_USEDEFAULT. If nWidth is CW_USEDEFAULT, Windows selects a default width and height for the window; the default width extends from the initial x-coordinates to the right edge of the screen; the default height extends from the initial y-coordinate to the top of the icon area. CW_USEDEFAULT is valid only for overlapped windows; if CW_USEDEFAULT is specified for a pop-up or child window, the nWidth and nHeight parameter are set to zero.

nHeight

Specifies the height, in device units, of the window. For overlapped windows, nHeight is the window’s height, in screen coordinates. If the nWidth parameter is set to CW_USEDEFAULT, Windows ignores nHeight.

hWndParent

Identifies the parent or owner window of the window being created. A valid window handle must be supplied when a child window or an owned window is created. A child window is confined to the client area of its parent window. An owned window is an overlapped window that is destroyed when its owner window is destroyed or hidden when its owner is minimized; it is always displayed on top of its owner window. Although this parameter must specify a valid handle if the dwStyle parameter includes the WS_CHILD style, it is optional if dwStyle includes the WS_POPUP style.

hMenu

Identifies a menu, or specifies a child-window identifier, depending on the window style. For an overlapped or pop-up window, hMenu identifies the menu to be used with the window; it can be NULL if the class menu is to be used. For a child window, hMenu specifies the child-window identifier, an integer value used by a dialog box control to notify its parent about events. The application determines the child-window identifier; it must be unique for all child windows with the same parent window.

hInstance

Identifies the instance of the module to be associated with the window.

lpParam

Points to a value passed to the window through the CREATESTRUCT structure referenced by the lParam parameter of the WM_CREATE message. If an application calls CreateWindow to create a multiple document interface client window, lpParam must point to a CLIENTCREATESTRUCT structure.

Return Values

If the function succeeds, the return value is the handle to the new window.

If the function fails, the return value is NULL.

Remarks

The CreateWindowEx function sends WM_NCCREATE, WM_NCCALCSIZE, and WM_CREATE messages to the window being created.

For information about the window control classes, window styles, and control styles used with this function, see the description of the CreateWindow function.

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

CLIENTCREATESTRUCT, CREATESTRUCT, CreateWindow, GlobalAddAtom, RegisterClass, SetWindowPos, WM_CREATE, WM_NCCALCSIZE, WM_NCCREATE, WM_PAINT, WM_PARENTNOTIFY


CreateWindowStation

The CreateWindowStation function creates a window station object. It returns a handle that can be used to access the window station. A window station is a secure object that contains a set of global atoms, a clipboard, and a set of desktop objects.

HWINSTA CreateWindowStation(

LPTSTR lpwinsta,	// name of the new window station
DWORD dwReserved,	// reserved; must be NULL
DWORD dwDesiredAccess,	// specifies access of returned handle
LPSECURITY_ATTRIBUTES lpsa	// specifies security attributes of the window station
);
Parameters

lpwinsta

Optionally points to a null-terminated string specifying the name of the window station to be created. Window station names are case-insensitive and cannot contain backslash characters (\). Only members of the Administrators group are allowed to specify a name. If lpwinsta is NULL, the system forms a window station name using the logon session identifier for the calling process. To get this name, call the GetUserObjectInformation function.

dwReserved

Reserved; must be NULL.

dwDesiredAccess

Specifies the type of access to the window station. This parameter can be one or more of the following values:

Value	Description
WINSTA_ACCESSCLIPBOARD	Required to use the clipboard.
WINSTA_ACCESSGLOBALATOMS	Required to manipulate global atoms.
WINSTA_CREATEDESKTOP	Required to create new desktop objects on the window station.
WINSTA_ENUMDESKTOPS	Required to enumerate existing desktop objects.
WINSTA_ENUMERATE	Required for the window station to be enumerated.
WINSTA_EXITWINDOWS	Required to successfully call the ExitWindows or ExitWindowsEx functions.
WINSTA_READATTRIBUTES	Required to read the attributes of a window station object.
WINSTA_READSCREEN	Required to access screen contents.
WINSTA_WRITEATTRIBUTES	Required to modify the attributes of a window station object.
lpsa

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpsa is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new window station. If lpsa is NULL, the window station (and any desktops created within the window) gets a security descriptor that grants GENERIC_ALL access to all users.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

Return Values

If the function succeeds, the return value is the handle to the newly created window station.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

GetUserObjectInformation, OpenWindowStation


CryptAcquireContext [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptAcquireContext

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptAcquireContext function is used to acquire a handle to a particular key container within a particular CSP. This returned handle can then be used to make calls to the selected CSP.

This function performs two operations. It first attempts to find a CSP with the characteristics described in the dwProvType and pszProvider parameters. If the CSP is found, then the function attempts to find a key container within the CSP matching the name specified by the pszContainer parameter.

This function can also be used to create and destroy key containers, depending on the value of the dwFlags parameter.

BOOL CRYPTFUNC CryptAcquireContext(

HCRYPTPROV *phProv,
LPCTSTR pszContainer,
LPCTSTR pszProvider,
DWORD dwProvType,
DWORD dwFlags
);
Parameters

phProv

[out] The address to which the function copies a handle to the CSP.

pszContainer

[in] The key container name. This is a zero-terminated string that identifies the key container to the CSP. This name is independent of the method used to store the keys. Some CSPs will store their key containers internally (in hardware), some will use the system Registry, and others will use the file system.

If this parameter is NULL, then a default key container name will be used. For example, if the Microsoft RSA Base Provider is being used, then the current user’s logon name will be used as the name of the key container. Other CSPs may also have default key containers that can be acquired in this way.

An application can obtain the name of the acquired key container at a later time by reading the PP_CONTAINER parameter from the CryptGetProvParam function.

pszProvider

[in] The provider name. This is a zero-terminated string that specifies the CSP to be used.

If this parameter is NULL then the user default provider is used. This situation is discussed in detail in the section Interfacing with a Cryptographic Service Provider (CSP).

An application can obtain the name of the acquired CSP at a later time by reading the PP_NAME parameter from the CryptGetProvParam function.

dwProvType

[in] The type of provider to acquire. The following provider types are predefined. These are discussed in detail in the section Interfacing with a Cryptographic Service Provider (CSP).

•	PROV_RSA_FULL

•	PROV_RSA_SIG

•	PROV_DSS

•	PROV_FORTEZZA

•	PROV_MS_MAIL

dwFlags

[in] The flag values. This parameter is normally set to zero, but some applications will set one (and only one) of the following flags:

CRYPT_VERIFYCONTEXT

If this flag is set, then the application will have no access to the key container’s private keys. In fact, if pszContainer is NULL and no default key container is present, the application will have no access to a key container at all.

This option is intended to be used by applications whose only cryptographic need is to verify digital signatures. The only operations normally needed in this case are public key import, hashing, and signature verification.

When CryptAcquireContext is called, many CSPs will require input from the owning user before granting access to the private keys in the key container. For example, the private keys may be encrypted, requiring a password from the user before they can be used. However, if the CRYPT_VERIFYCONTEXT flag is specified, access to the private keys is not required and the user interface can be bypassed.

CRYPT_NEWKEYSET

If this flag is set, then a new key container will be created with the name specified by pszContainer. If pszContainer is NULL, then a key container with the default name will be created.

Note That when key containers are created, most CSPs will not automatically create any public/private key pairs. These keys must be created as a separate step with the CryptGenKey function.

Important This flag should only be set by administrative applications. Normal applications should not create key containers.

CRYPT_DELETEKEYSET

If this flag is set, then the key container specified by pszContainer is deleted. If pszContainer is NULL, then the key container with the default name is deleted. All key pairs in the key container are also destroyed.

When the CRYPT_DELETEKEYSET flag is set, the value returned in phProv is undefined and, thus, the CryptReleaseContext function need not be called afterwards.

Important This flag should only be set by administrative applications. Normal applications should not destroy key containers.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function.

Error	Description
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_NOT_ENOUGH_MEMORY	The operating system ran out of memory during the operation.
NTE_BAD_FLAGS	The dwFlags parameter has an illegal value.
NTE_BAD_KEYSET	The Registry entry for the key container could not be opened and may not exist.
NTE_BAD_KEYSET_PARAM	The pszContainer or pszProvider parameter is set to an illegal value.
NTE_BAD_PROV_TYPE	The value of the dwProvType parameter is out of range. All provider types must be from 1 to 999, inclusive.
NTE_BAD_SIGNATURE	The provider DLL signature did not verify correctly. Either the DLL or the digital signature has been tampered with.
NTE_EXISTS	The dwFlags parameter is CRYPT_NEWKEYSET, but the key container already exists.
NTE_KEYSET_ENTRY_BAD	The Registry entry for the pszContainer key container was found (in the HKEY_CURRENT_USER window), but is corrupt. See the section System Administration for details about CryptoAPI’s Registry usage.
NTE_KEYSET_NOT_DEF	No Registry entry exists in the HKEY_CURRENT_USER window for the key container specified by pszContainer.
NTE_NO_MEMORY	The CSP ran out of memory during the operation.
NTE_PROV_DLL_NOT_FOUND	The provider DLL file does not exist or is not on the current path.
NTE_PROV_TYPE_ENTRY_BAD	The Registry entry for the provider type specified by dwProvType is corrupt. This error may relate to either the user default CSP list or the machine default CSP list. See the section System Administration for details about CryptoAPI’s Registry usage.
NTE_PROV_TYPE_NO_MATCH	The provider type specified by dwProvType does not match the provider type found in the Registry. Note that this error can only occur when pszProvider specifies an actual CSP name.
NTE_PROV_TYPE_NOT_DEF	No Registry entry exists for the provider type specified by dwProvType.
NTE_PROVIDER_DLL_FAIL	The provider DLL file could not be loaded, and may not exist. If it exists, then the file is not a valid DLL.
NTE_SIGNATURE_FILE_BAD	An error occurred while loading the DLL file image, prior to verifying its signature.
Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;

BYTE pbData[1000];

DWORD dwDataLen;

// Get handle to the default PROV_RSA_FULL provider.

if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {

    printf("Error %x during CryptAcquireContext!\n", GetLastError());

    return;

}

// Read the name of the default CSP.

dwDataLen = 1000;

if(!CryptGetProvParam(hProv, PP_NAME, pbData, &dwDataLen, 0)) {

    printf("Error %x reading CSP name!\n", GetLastError());

    return;

}

printf(“Provider name:%s\n”, pbData);

// Read the name of the default key container.

dwDataLen = 1000;

if(!CryptGetProvParam(hProv, PP_CONTAINER, pbData, &dwDataLen, 0)) {

    printf("Error %x reading key container name!\n", GetLastError());

    return;

}

printf(“Key Container name:%s\n”, pbData);

// Perform cryptographic operations.

...

// Release provider handle.

if(!CryptReleaseContext(hProv, 0)) {

    printf("Error %x during CryptReleaseContext!\n", GetLastError());

    return;

}

// ****************************************************************

// Get handle to the Microsoft RSA Base Provider and the

// "Foo" key container.

if(!CryptAcquireContext(&hProv, TEXT("Foo"), MS_DEF_PROV,

                        PROV_RSA_FULL, 0)) {

    printf("Error %x during CryptAcquireContext!\n", GetLastError());

    return;

}

// Perform cryptographic operations.

...

// Release provider handle.

if(!CryptReleaseContext(hProv, 0)) {

    printf("Error %x during CryptReleaseContext!\n", GetLastError());

    return;

}

// ****************************************************************

// Get handle to the default provider. Create a new key container

// named "Bar". Note that this key container will be empty until keys

// are explicitly created with the CryptGenKey function.

lstrcpy(szProv, );

lstrcpy(szContainer, );

if(!CryptAcquireContext(&hProv, TEXT("Bar"), NULL, PROV_RSA_FULL,

                        CRYPT_NEWKEYSET)) {

    printf("Error %x during CryptAcquireContext!\n", GetLastError());

    return;

}

// Perform cryptographic operations.

...

// Release provider handle.

if(!CryptReleaseContext(hProv, 0)) {

    printf("Error %x during CryptReleaseContext!\n", GetLastError());

    return;

}

See Also

CryptGenKey, CryptGetProvParam, CryptReleaseContext


CryptCreateHash [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptCreateHash

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptCreateHash function is used to initiate the hashing of a stream of data. It returns to the caller a handle to a CSP hash object. This handle can also be used in subsequent calls to CryptHashData and CryptHashSessionKey in order to hash streams of data and session keys.

BOOL CRYPTFUNC CryptCreateHash(

HCRYPTPROV hProv,
ALG_ID Algid,
HCRYPTKEY hKey,
DWORD dwFlags,
HCRYPTHASH *phHash
);
Parameters

hProv

[in] A handle to the CSP to use. An application obtains this handle using the CryptAcquireContext function.

Algid

[in] An algorithm identifier of the hash algorithm to use.

The valid values for this parameter will vary, depending on the CSP that is used. See the “Remarks” section for the list of default algorithms.

hKey

[in] If the type of hash algorithm is a keyed hash, such as a MAC algorithm, the key for the hash should be passed in this parameter. For nonkeyed algorithms, this parameter should be set to zero.

The key must be to a block cipher, such as RC2, with a cipher mode of CBC.

dwFlags

[in] The flag values. This parameter is reserved for future use and should always be zero.

phHash

[out] The address to which the function copies a handle to the new hash object.

Remarks

The Microsoft RSA Base Provider defines the following hashing algorithms:

Constant	Description
CALG_MAC	Message Authentication Code
CALG_MD2	MD2
CALG_MD5	MD5
CALG_SHA	US DSA Secure Hash Algorithm
The computation of the actual hash is done with the CryptHashData and CryptHashSessionKey functions. These require a handle to the hash object. Once all the data has been added to the hash object, exactly one of the following operations can be performed:

•	The hash value can be retrieved using CryptGetHashParam.

•	A session key can be derived using CryptDeriveKey.

•	The hash can be signed using CryptSignHash.

•	A signature can be verified using CryptVerifySignature.

Once one of the functions from this list has been called, the only hashing function that can be used with the same hash handle is CryptDestroyHash.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_NOT_ENOUGH_MEMORY	The operating system ran out of memory during the operation.
NTE_BAD_ALGID	The Algid parameter specifies an algorithm that this CSP does not support.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
NTE_BAD_KEY	A keyed hash algorithm (such as CALG_MAC) is specified by Algid and the hKey parameter is either zero or it specifies an invalid key handle. This error code will also be returned if the key is to a stream cipher, or if the cipher mode is anything other than CBC.
NTE_NO_MEMORY	The CSP ran out of memory during the operation.
Example

See the “Example” section in the CryptSignHash function.

See Also

CryptAcquireContext, CryptDeriveKey, CryptDestroyHash, CryptGetHashParam, CryptHashData, CryptHashSessionKey, CryptSignHash, CryptVerifySignature


CryptDecrypt [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptDecrypt

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptDecrypt function is used to decrypt data that was previously encrypted via the CryptEncrypt function.

BOOL CRYPTFUNC CryptDecrypt(

HCRYPTKEY hKey,
HCRYPTHASH hHash,
BOOL Final,
DWORD dwFlags,
BYTE *pbData,
DWORD *pdwDataLen
);
Parameters

hKey

[in] A handle to the key to use for the decryption. An application obtains this handle by using either the CryptGenKey or CryptImportKey function.

This key specifies the decryption algorithm that is used.

hHash

[in] A handle to a hash object. This parameter is only used if a hash of the data is to be computed. See the “Remarks” section for more information.

If no hash is to be done, this parameter must be zero.

Final

[in] The Boolean value that specifies whether this is the last section in a series being decrypted. This will be TRUE if this is the last or only block. If it is not, then it will be FALSE. See the “Remarks” section for more information.

dwFlags

[in] The flag values. This parameter is reserved for future use and should always be zero.

pbData

[in/out] The buffer holding the data to be decrypted. Once that decryption has been performed, the plaintext is placed back in this same buffer.

The number of encrypted bytes in this buffer is specified by pdwDataLen.

pdwDataLen

[in/out] The address of the data length. Before calling this function, the caller should set this parameter to the number of bytes to be decrypted. Upon return, this address will contain the number of bytes of plaintext generated.

When a block cipher is used, this data length must be a multiple of the block size, unless this is the final section of data to be decrypted and the Final flag is TRUE.

Remarks

If data is to be decrypted and hashed simultaneously, a handle to a hash object can be passed in the hHash parameter. The hash value will be updated with the decrypted plaintext. This option is useful when simultaneously decrypting and verifying a signature.

Prior to calling CryptDecrypt, the application should obtain a handle to the hash object by calling the CryptCreateHash function. Once the decryption is complete, the hash value can be obtained (through CryptGetHashParam) or it can be signed (through CryptSignHash), or it can be used to verify a digital signature (through CryptVerifySignature).

When a large amount of data needs to be decrypted, it can be done in sections. This is done by calling CryptDecrypt repeatedly. The Final parameter should be set to TRUE only on the last invocation of CryptDecrypt, so the decryption engine can properly finish the decryption process. The following extra actions are performed when Final is TRUE:

•	If the key is a block cipher key, the data will be padded to a multiple of the block size of the cipher. To find the block size of a cipher, use CryptGetKeyParam to get the KP_BLOCKLEN parameter of the key.

•	If the cipher is operating in a chaining mode, the next CryptDecrypt operation will reset the cipher’s feedback register to the KP_IV value of the key.

•	If the cipher is a stream cipher, the next CryptDecrypt call will reset the cipher to its initial state.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID	The hKey session key specifies an algorithm that this CSP does not support.
NTE_BAD_DATA	The data to be decrypted is invalid. For example, when a block cipher is used and the Final flag FALSE, the value specified by pdwDataLen must be a multiple of the block size. This error can also be returned when the padding is found to be invalid.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
NTE_BAD_HASH	The hHash parameter contains an invalid handle.
NTE_BAD_KEY	The hKey parameter does not contain a valid handle to a key.
NTE_BAD_LEN	The size of the output buffer is too small to hold the generated plaintext.
NTE_BAD_UID	The CSP context that was specified when the key was created cannot be found.
NTE_DOUBLE_ENCRYPT	The application attempted to decrypt the same data twice.
NTE_FAIL	The function failed in some unexpected way.
Example

See “Decryption Example” in the section Encrypting and Decrypting Data.

See Also

CryptCreateHash, CryptEncrypt, CryptGenKey, CryptGetKeyParam, CryptGetHashParam, CryptImportKey, CryptSignHash, CryptVerifySignature


CryptDeriveKey [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptDeriveKey

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptDeriveKey function generates cryptographic keys derived from base data. This function guarantees that all keys generated from the same base data will be identical, provided the same CSP and algorithms are used. The base data can be a password or any other user data.

This function is the same as CryptGenKey, except that the generated session keys are derived from base data instead of being random. Another difference is that the CryptDeriveKey function cannot be used to generate public/private key pairs.

A handle to the session key is returned in phKey. This handle can then be used as needed with any of the other CryptoAPI functions that require key handles.

BOOL CRYPTFUNC CryptDeriveKey(

HCRYPTPROV hProv,
ALG_ID Algid,
HCRYPTHASH hBaseData,
DWORD dwFlags,
HCRYPTKEY *phKey
);
Parameters

hProv

[in] A handle to the application’s CSP. An application obtains this handle using the CryptAcquireContext function.

Algid

[in] The identifier for the algorithm for which the key is to be generated.

The valid values for this parameter will vary, depending on the CSP that is used. See the “Remarks” section for a list of possible algorithm identifiers.

hBaseData

[in] A handle to a hash object that has been fed exactly the base data.

To obtain this handle, an application must first create a hash object with CryptCreateHash and then add the base data to the hash object with CryptHashData. This process is described in detail in the section Hashes and Digital Signatures.

dwFlags

[in] The flags specifying the type of key generated. This parameter can be zero, or you can specify one or more of the following flags, using the binary OR operator to combine them.

CRYPT_EXPORTABLE

If this flag is set, then the session key can be transferred out of the CSP into a key blob through the CryptExportKey function. Because keys generally must  be exportable, this flag should usually be set.

If this flag is not set, then the session key will not be exportable. This means the key will only be available within the current session and only the application that created it will be able to use it.

This flag does not apply to public/private key pairs.

CRYPT_CREATE_SALT

Typically, when a session key is made from a hash value, there are a number of leftover bits. For example, if the hash value is 128 bits and the session key is 40 bits, there will be 88 bits leftover.

If this flag is set, then the key will be assigned a salt value based on the unused hash value bits. You can retrieve this salt value using the CryptGetKeyParam function with the dwParam parameter set to KP_SALT.

If this flag is not set, then the key will be given a salt value of zero.

When keys with nonzero salt values are exported (using CryptExportKey), the salt value must also be obtained  and kept with the key blob.

CRYPT_USER_PROTECTED

If this flag is set, then the user will be notified through a dialog box or another method when certain actions are attempted using this key. The precise behavior is specified by the CSP being used.

The Microsoft RSA Base Provider ignores this flag.

CRYPT_UPDATE_KEY

Some CSPs use session keys that are derived from multiple hash values. When this is the case, CryptDeriveKey must be called multiple times.

If this flag is set, a new session key is not generated. Instead, the key specified by phKey is modified. The precise behavior of this flag is dependent on the type of key being generated and on the particular CSP being used.

The Microsoft RSA Base Provider ignores this flag.

phKey

[in/out] The address to which the function copies the handle of the newly generated key.

Remarks

To generate a key for a symmetric encryption algorithm, use the Algid parameter to specify the algorithm. The algorithms available will most likely be different for each CSP. If you are using the Microsoft RSA Base Provider, use one of the following values to specify the algorithm:

•	CALG_RC2 — RC2 block cipher

•	CALG_RC4 — RC4 stream cipher

When keys are generated for symmetric block ciphers, the key by default will be set up in cipher block chaining (CBC) mode with an initialization vector of zero. This cipher mode provides a good default method for bulk encrypting data. To change these parameters, use the CryptSetKeyParam function.

Once the CryptDeriveKey function has been called, no more data can be added to the hash object. The CryptDestroyHash function should be called at this point to destroy the hash object.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID	The Algid parameter specifies an algorithm that this CSP does not support.
NTE_BAD_FLAGS	The dwFlags parameter contains an invalid value.
NTE_BAD_HASH	The hBaseData parameter does not contain a valid handle to a hash object.
NTE_BAD_UID	The hProv parameter does not contain a valid context handle.
NTE_FAIL	The function failed in some unexpected way.
Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;

HCRYPTKEY hKey = 0;

HCRYPTHASH hHash = 0;

CHAR szPassword[ ] = "apple-camshaft";

DWORD dwLength;

// Get handle to user default provider.

if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {

    printf("Error %x during CryptAcquireContext!\n", GetLastError());

    goto done;

}

// Create hash object.

if(!CryptCreateHash(hProv, CALG_MD5, 0, 0, &hHash)) {

    printf("Error %x during CryptCreateHash!\n", GetLastError());

    goto done;

}

// Hash password string.

dwLength = strlen(szPassword);

if(!CryptHashData(hHash, (BYTE *)szPassword, dwLength, 0)) {

    printf("Error %x during CryptHashData!\n", GetLastError());

    goto done;

}

// Create block cipher session key based on hash of the password.

if(!CryptDeriveKey(hProv, CALG_RC2, hHash, CRYPT_EXPORTABLE, &hKey)) {

    printf("Error %x during CryptDeriveKey!\n", GetLastError());

    goto done;

}

// Use ‘hKey’ to do something.

...

done:

// Destroy hash object.

if(hHash != 0) CryptDestroyHash(hHash);

// Destroy session key.

if(hKey != 0) CryptDestroyKey(hKey);

// Release provider handle.

if(hProv != 0) CryptReleaseContext(hProv, 0);

See Also

CryptAcquireContext, CryptCreateHash, CryptDestroyHash, CryptDestroyKey, CryptExportKey, CryptGenKey, CryptGetKeyParam, CryptHashData, CryptSetKeyParam


CryptDestroyHash [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptDestroyHash

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptDestroyHash function destroys the hash object referenced by the hHash parameter. Once a hash object has been destroyed, it can no longer be used and its handle is useless from then on.

All hash objects should be destroyed with the CryptDestroyHash function when the application is finished with them.

BOOL CRYPTFUNC CryptDestroyHash(

HCRYPTHASH hHash
);
Parameters

hHash

[in] A handle to the hash object to be destroyed.

Remarks

When a hash object is destroyed, the many CSPs will scrub the memory in the CSP where the hash object was held. The CSP memory is then freed.

There should be a one-to-one correspondence between calls to CryptCreateHash and CryptDestroyHash.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_BUSY	The hash object specified by hHash is currently being used by another process.
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID	The hHash handle specifies an algorithm that this CSP does not support.
NTE_BAD_HASH	The hash object specified by the hHash parameter is invalid.
NTE_BAD_UID	The CSP context that was specified when the hash object was created cannot be found.
Example

See the “Example” section in the CryptSignHash function.

See Also

CryptCreateHash, CryptHashData, CryptSignHash


CryptDestroyKey [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptDestroyKey

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptDestroyKey function releases the handle referenced by the hKey parameter. Once a key handle has been released, it becomes invalid and cannot be used again.

If the handle refers to a session key, or to a public key that has been imported into the CSP through CryptImportKey, this function destroys the key and frees the memory that the key occupied. Many CSPs will scrub the memory where the key was held before freeing it.

On the other hand, if the handle refers to a public/private key pair (obtained from CryptGetUserKey), the underlying key pair is not destroyed by this function. Only the handle is destroyed.

BOOL CRYPTFUNC CryptDestroyKey(

HCRYPTKEY hKey
);
Parameters

hKey

[in] A handle to the key to be destroyed.

Remarks

Keys take up memory in both the operating system’s memory space and the CSP’s memory space. Some CSPs will be implemented in hardware with very limited memory resources. For this reason, it is important that applications destroy all keys with the CryptDestroyKey function when they are finished with them.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_KEY	The hKey parameter does not contain a valid handle to a key.
NTE_BAD_UID	The CSP context that was specified when the key was created cannot be found.
Example

See the “Example” section in the CryptGenKey function.

See Also

CryptDeriveKey, CryptGenKey, CryptGetUserKey, CryptImportKey


CryptEncrypt [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptEncrypt

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptEncrypt function is used to encrypt data. The algorithm used to encrypt the data is designated by the key held by the CSP module, which is referenced by the hKey parameter.

BOOL CRYPTFUNC CryptEncrypt(

HCRYPTKEY hKey,
HCRYPTHASH hHash,
BOOL Final,
DWORD dwFlags,
BYTE *pbData,
DWORD *pdwDataLen,
DWORD dwBufLen
);
Parameters

hKey

[in] A handle to the key to use for the encryption. An application obtains this handle by using either the CryptGenKey or the CryptImportKey function.

This key specifies the encryption algorithm that is used.

hHash

[in] A handle to a hash object. This parameter is used only if a hash of the data is to be computed at the same time the encryption is being performed. See the “Remarks” section for more information.

If no hash is to be done, this parameter must be zero.

Final

[in] The Boolean value that specifies whether this is the last section in a series being encrypted. This should be TRUE if this is the last or only block, and FALSE if it is not. See the “Remarks” section for more information.

dwFlags

[in] The flag values. This parameter is reserved for future use and should always be zero.

pbData

[in/out] The buffer holding the data to be encrypted. Once the encryption has been performed, the encrypted data is placed back in this same buffer.

The size of this buffer is specified by dwBufLen. The number of bytes of data to be encrypted is specified by pdwDataLen.

This parameter can be NULL if all you are doing is determining the number of bytes required for the returned data.

pdwDataLen

[in/out] The address of the data length. Before calling this function, the caller should set this parameter to the number of bytes to be encrypted. Upon return, this address will contain the number of bytes of encrypted data.

If the buffer specified by pbData is not large enough to hold the data, the function returns the ERROR_MORE_DATA error code (through GetLastError) and stores the required buffer size, in bytes, into the variable pointed to by pdwDataLen.

If pbData is NULL, then no error is returned, and the function stores the size of the data, in bytes, in the variable pointed to be pdwDataLen. This lets an application determine the correct buffer size unambiguously.

When a block cipher is used, this data length must be a multiple of the block size, unless this is the final section of data to be encrypted and the Final flag is TRUE.

dwBufLen

[in] The number of bytes in the pbData buffer.

Note that, depending on the algorithm used, the encrypted text can be slightly larger than the original plaintext. In this case, the pbData buffer needs to be sized accordingly.

As a rule, if a stream cipher is used the ciphertext will be the same size as the plaintext. If a block cipher is used, the ciphertext will be up to a “block length” larger than the plaintext.

Remarks

If data is to be hashed and encrypted simultaneously, a handle to a hash object can be passed in the hHash parameter. The hash value will be updated with the plaintext passed in. This option is useful when generating signed and encrypted text.

Prior to calling CryptEncrypt, the application should obtain a handle to the hash object by calling the CryptCreateHash function. Once the encryption is complete, the hash value can be obtained through the CryptGetHashParam function or the hash can be signed using the CryptSignHash function.

When a large amount of data needs to be encrypted, it can be done in sections. This is done by calling CryptEncrypt repeatedly. The Final parameter should be set to TRUE only on the last invocation of CryptEncrypt, so the encryption engine can properly finish the encryption process. The following extra actions are performed when Final is TRUE:

•	If the key is a block cipher key, the data will be padded to a multiple of the block size of the cipher. To find the block size of a cipher, use CryptGetKeyParam to get the KP_BLOCKLEN parameter of the key.

•	If the cipher is operating in a chaining mode, the next CryptEncrypt operation will reset the cipher’s feedback register to the KP_IV value of the key.

•	If the cipher is a stream cipher, the next CryptEncrypt will reset the cipher to its initial state.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID	The hKey session key specifies an algorithm that this CSP does not support.
NTE_BAD_DATA	The data to be encrypted is invalid. For example, when a block cipher is used and the Final flag is FALSE, the value specified by pdwDataLen must be a multiple of the block size.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
NTE_BAD_HASH	The hHash parameter contains an invalid handle.
NTE_BAD_KEY	The hKey parameter does not contain a valid handle to a key.
NTE_BAD_LEN	The size of the output buffer is too small to hold the generated ciphertext.
NTE_BAD_UID	The CSP context that was specified when the key was created cannot be found.
NTE_DOUBLE_ENCRYPT	The application attempted to encrypt the same data twice.
NTE_FAIL	The function failed in some unexpected way.
NTE_NO_MEMORY	The CSP ran out of memory during the operation.
Example

See “Encryption Example” in the section Encrypting and Decrypting Data.

See Also

CryptCreateHash, CryptDecrypt, CryptGenKey, CryptGetHashParam, CryptImportKey, CryptSignHash


CryptExportKey [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptExportKey

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptExportKey function is used to export cryptographic keys out of a cryptographic service provider in a secure manner.

A handle to the key to be exported is passed into the function and the function returns a key blob to the caller. This key blob can be sent over a nonsecure transport or stored in a nonsecure storage location. The key blob is useless until the intended recipient uses the CryptImportKey function on it, which will then import the key into the recipient’s CSP.

BOOL CRYPTFUNC CryptExportKey(

HCRYPTKEY hKey,
HCRYPTKEY hExpKey,
DWORD dwBlobType,
DWORD dwFlags,
BYTE *pbData,
DWORD *pdwDataLen
);
Parameters

hKey

[in] A handle to the key to be exported.

hExpKey

[in] A handle to a cryptographic key belonging to the destination user. The key data within the key blob created is encrypted using this key. This ensures that only the destination user will be able to make use of the key blob.

Most often, this will be the key exchange public key of the destination user. However, certain protocols require that a session key belonging to the destination user be used for this purpose.

If the key blob type specified by dwBlobType is PUBLICKEYBLOB, then this parameter is unused and should be set to zero.

If the key blob specified by dwBlobType is PRIVATEKEYBLOB, then this is typically a handle to a session key that is to be used to encrypt the key blob. Some CSPs allow this parameter to be zero, in which case the application should encrypt the private key blob manually so as to protect it.

dwBlobType

[in] The type of key blob to be exported. This must currently be one of the following constants. These constants are discussed in the section Exchanging Cryptographic Keys.

•	SIMPLEBLOB

•	PUBLICKEYBLOB

•	PRIVATEKEYBLOB

dwFlags

[in] The flag values. This parameter is reserved for future use and should always be zero.

pbData

[out] The buffer that the function places the key blob in. The required size for this buffer can be determined by calling CryptExportKey with NULL for this parameter.

As a rule, SIMPLEBLOBs will be 256 bytes or less, PUBLICKEYBLOBs will be 1000 bytes or less, and PRIVATEKEYBLOBS will be 5000 bytes or less.

pdwDataLen

[in/out] The address of the key blob data length. Before calling this function, the caller should set this parameter to the length, in bytes, of the pbData buffer. Upon return, this address will contain the number of bytes taken up by the key blob.

If the buffer specified by pbData is not large enough to hold the data, the function returns the ERROR_MORE_DATA error code (through GetLastError) and stores the required buffer size, in bytes, into the variable pointed to by pdwDataLen.

If pbData is NULL, then no error is returned and the function stores the size of the data, in bytes, in the variable pointed to by pdwDataLen.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
NTE_BAD_KEY	One or both of the keys specified by hKey and hExpKey are invalid.
NTE_BAD_KEY_STATE	You do not have permission to export the key. That is, when the hKey key was created, the CRYPT_EXPORTABLE flag was not specified.
NTE_BAD_PUBLIC_KEY	The key blob type specified by dwBlobType is PUBLICKEYBLOB, but hExpKey does not contain a public key handle.
NTE_BAD_TYPE	The dwBlobType parameter specifies an unknown blob type.
NTE_BAD_UID	The CSP context that was specified when the hKey key was created cannot be found.
NTE_NO_KEY	A session key is being exported and the hExpKey parameter does not specify a public key.
Example

#include <wincrypt.h>

HCRYPTPROV hProv;      // Handle to CSP

HCRYPTKEY hKey;        // Handle to session key

HCRYPTKEY hXchgKey;    // Handle to receiver’s exchange public key

BYTE *pbKeyBlob = NULL;

DWORD dwBlobLen;

...

// Determine size of key blob and allocate memory.

if(!CryptExportKey(hKey, hXchgKey, SIMPLEBLOB, 0, NULL, &dwBlobLen)) {

    printf("Error %x computing blob length!\n", GetLastError());

    ...

}

if((pbKeyBlob = malloc(dwBlobLen)) == NULL) {

    printf("Out of memory!\n");

    ...

}

// Export key into a simple key blob.

if(!CryptExportKey(hKey, hXchgKey, SIMPLEBLOB, 0, pbKeyBlob, &dwBlobLen)) {

    printf("Error %x during CryptExportKey!\n", GetLastError());

    ...

}

See Also

CryptImportKey


CryptGenKey [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptGenKey

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptGenKey function generates random cryptographic keys for use with the CSP module. A handle to the key is returned in phKey. This handle can then be used as needed with any of the other CryptoAPI functions requiring key handles.

The calling application is required to specify the algorithm when calling this function. Because this algorithm type is kept bundled with the key, the application does not need to specify the algorithm later when the actual cryptographic operations are performed.

BOOL CRYPTFUNC CryptGenKey(

HCRYPTPROV hProv,
ALG_ID Algid,
DWORD dwFlags,
HCRYPTKEY *phKey
);
Parameters

hProv

[in] A handle to the application’s CSP. An application obtains this handle using the CryptAcquireContext function.

Algid

[in] The identifier for the algorithm for which the key is to be generated.

The valid values for this parameter will vary, depending on the CSP that is used. See the “Remarks” section for a list of possible algorithm identifiers.

dwFlags

[in] The flags specifying the type of key generated. This parameter can be zero, or you can specify one or more of the following flags, using the binary OR operator to combine them.

CRYPT_EXPORTABLE

If this flag is set, then the key can be transferred out of the CSP into a key blob using the CryptExportKey function. Because session keys generally must be exportable, this flag should usually be set when they are created.

If this flag is not set, then the key will not be exportable. For a session key, this means that the key will only be available within the current session and only the application that created it will be able to use it. For a public/private key pair, this means that the private key cannot be transported or backed up.

This flag only applies to session key and private key blobs. It does not apply to public keys, which are always exportable.

CRYPT_CREATE_SALT

If this flag is set, then the key will be assigned a random salt value automatically. You can retrieve this salt value using the CryptGetKeyParam function with the dwParam parameter set to KP_SALT.

If this flag is not set, then the key will be given a salt value of zero.

When keys with non-zero salt values are exported (through CryptExportKey), then the salt value must also be obtained  and kept with the key blob.

CRYPT_USER_PROTECTED

If this flag is set, then the user will be notified through a dialog box or another method when certain actions are attempted using this key. The precise behavior is specified by the CSP being used.

The Microsoft RSA Base Provider ignores this flag.

phKey

[out] The address that the function copies the handle of the newly generated key to.

Remarks

To generate a key to be used with a symmetric encryption algorithm (that is, a session key), use the Algid parameter to specify the algorithm. The algorithms available will most likely be different for each CSP. If you are using the Microsoft RSA Base Provider, one of the following values can be used to specify the algorithm:

•	CALG_RC2 — RC2 block cipher

•	CALG_RC4 — RC4 stream cipher

When keys are generated for symmetric block ciphers, the key by default will be set up in cipher block chaining (CBC) mode with an initialization vector of zero. This cipher mode provides a good default method for bulk encrypting data. To change these parameters, use the CryptSetKeyParam function.

In addition to generating keys for symmetric algorithms, the CryptGenKey function can also generate keys for public-key algorithms. The use of public-key algorithms is restricted to key exchange and digital signatures. Each CryptoAPI client generally possesses one key pair for each of these operations. To generate one of these key pairs, set the Algid parameter to one of the following values:

•	AT_KEYEXCHANGE — Key exchange

•	AT_SIGNATURE — Digital signature

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID	The Algid parameter specifies an algorithm that this CSP does not support.
NTE_BAD_FLAGS	The dwFlags parameter contains an invalid value.
NTE_BAD_UID	The hProv parameter does not contain a valid context handle.
NTE_FAIL	The function failed in some unexpected way.
Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;

HCRYPTKEY hKey = 0;

// Get handle to user default provider.

if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {

    printf("Error %x during CryptAcquireContext!\n", GetLastError());

    goto done;

}

// Create block cipher session key.

if(!CryptGenKey(hProv, CALG_RC2, CRYPT_EXPORTABLE, &hKey)) {

    printf("Error %x during CryptGenKey!\n", GetLastError());

    goto done;

}

// Use ‘hKey’ to do something.

...

done:

// Destroy session key.

if(hKey != 0) CryptDestroyKey(hKey);

// Release provider handle.

if(hProv != 0) CryptReleaseContext(hProv, 0);

See Also

CryptAcquireContext, CryptDestroyKey, CryptExportKey, CryptGetKeyParam, CryptImportKey, CryptSetKeyParam


CryptGenRandom [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptGenRandom

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptGenRandom function fills a buffer with random bytes.

BOOL CRYPTFUNC CryptGenRandom(

HCRYPTPROV hProv,
DWORD dwLen,
BYTE *pbBuffer
);
Parameters

hProv

[in] A handle to the application’s CSP. An application obtains this handle using the CryptAcquireContext function.

dwLen

[in] The number of bytes of random data to be generated.

pbBuffer

[in/out] The buffer the function is to copy the random data to. This buffer must be at least dwLen bytes in length.

Optionally, the application can fill this buffer with data to use as an auxiliary random seed. This is explained further in the “Remarks” section.

Remarks

The data produced by this function is “cryptographically random.” It is far more random than the data generated by the typical random number generator such as the one shipped with your “C” compiler.

This function is often used to generate random initialization vectors and salt values.

Seeding the Random Number Generator

All software random number generators work in fundamentally the same way. They start with one truly random number, known as the “seed,” and then use an algorithm to generate a pseudo-random sequence of bits based on it. The most difficult part of this process is to get a seed that is truly random. This is usually based on user input latency, or the jitter from one or more hardware components.

If your application has access to a good random source, then it can fill the pbBuffer buffer with some amount of random data before calling CryptGenRandom. The CSP will then use this data to further randomize its internal seed. Failing to initialize the pbBuffer buffer before calling CryptGenRandom is acceptable.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_UID	The hProv parameter does not contain a valid context handle.
NTE_FAIL	The function failed in some unexpected way.
Example

See the “Example” section in the CryptSetKeyParam function.

See Also

CryptAcquireContext, CryptGenRandom, CryptSetKeyParam


CryptGetHashParam [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptGetHashParam

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptGetHashParam function lets applications retrieve data that governs of the operations of a hash object. The actual hash value can also be retrieved using this function.

BOOL CRYPTFUNC CryptGetHashParam(

HCRYPTHASH hHash,
DWORD dwParam,
BYTE *pbData,
DWORD *pdwDataLen,
DWORD dwFlags
);
Parameters

hHash

[in] A handle to the hash object on which to query parameters.

dwParam

[in] The parameter number. See the “Remarks” section for a list of valid parameters.

pbData

[out] The parameter data buffer. The function copies the specified parameter data to this buffer. The form of this data will vary, depending on the parameter number.

This parameter can be NULL if all you are doing is determining the number of bytes required for the returned parameter data.

pdwDataLen

[in/out] The address of the parameter data length. Before calling this function, the caller should set this parameter to the length, in bytes, of the pbData buffer. Upon return, this address will contain the number of bytes of parameter data copied to the buffer.

If the buffer specified by pbData is not large enough to hold the data, the function returns the ERROR_MORE_DATA error code (through GetLastError), and stores the required buffer size, in bytes, in the variable pointed to by pdwDataLen.

If pbData is NULL, then no error is returned and the function stores the size of the data, in bytes, in the variable pointed to by pdwDataLen.

dwFlags

[in] The flag values. This parameter is reserved for future use and should always be zero.

Remarks

The dwParam value can be set to one of the following hash parameter types:

HP_ALGID

The hash algorithm. The pbData buffer will contain a ALG_ID value indicating the algorithm that was specified when the hash object was created. See the CryptCreateHash function for a list of hash algorithms.

HP_HASHSIZE

The hash value size. The pbData buffer will contain a DWORD value indicating the number of bytes in the hash value. This value will usually be 16 or 20, depending on the hash algorithm.

Applications should retrieve this parameter just before the HP_HASHVAL parameter so the correct amount of memory can be allocated.

HP_HASHVAL

The hash value. The pbData buffer will contain the hash value or message digest for the hash object specified by hHash. This value is generated based on the data supplied earlier to the hash object through the CryptHashData and CryptHashSessionKey functions.

Once this parameter has been retrieved, the hash object is marked “finished” and no more data can be added to it.

Note that some CSPs may add additional parameters that can be queried through this function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes tat prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
NTE_BAD_HASH	The hash object specified by the hHash parameter is invalid.
NTE_BAD_TYPE	The dwParam parameter specifies an unknown parameter number.
NTE_BAD_UID	The CSP context that was specified when the hash was created cannot be found.
Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;

HCRYPTHASH hHash = 0;

BYTE *pbHash = NULL;

DWORD dwHashLen;

#define BUFFER_SIZE 256

BYTE pbBuffer[BUFFER_SIZE];

DWORD dwCount;

DWORD i;

// Get handle to the default provider.

if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {

    printf("Error %x during CryptAcquireContext!\n", GetLastError());

    goto done;

}

// Create hash object.

if(!CryptCreateHash(hProv, CALG_MD5, 0, 0, &hHash)) {

    printf("Error %x during CryptBeginHash!\n", GetLastError());

    goto done;

}

// Fill buffer with test data.

for(i = 0 ; i < BUFFER_SIZE ; i++) {

    pbBuffer[i] = (BYTE)i;

}

// Hash in buffer.

if(!CryptHashData(hHash, pbBuffer, BUFFER_SIZE, 0)) {

    printf("Error %x during CryptHashData!\n", GetLastError());

    goto done;

}

// Read hash value size and allocate memory.

dwCount = sizeof(DWORD);

if(!CryptGetHashParam(hHash, HP_HASHSIZE, (BYTE *)&dwHashLen,

                      &dwCount, 0)) {

    printf("Error %x during reading hash size!\n", GetLastError());

    goto done;

}

if((pbHash = malloc(dwHashLen)) == NULL) {

    printf("Out of memory!\n");

    goto done;

}

// Read hash value.

if(!CryptGetHashParam(hHash, HP_HASHVAL, pbHash, &dwHashLen, 0)) {

    printf("Error %x during reading hash value!\n", GetLastError());

    goto done;

}

// Print hash value.

for(i = 0 ; i < dwHashLen ; i++) {

    printf("%2.2x ",pbHash[i]);

}

printf("\n");

done:

// Free memory.

if(pbHash !=NULL) free(pbHash);

// Destroy hash object.

if(hHash) CryptDestroyHash(hHash);

// Release CSP handle.

if(hProv) CryptReleaseContext(hProv,0);

See Also

CryptCreateHash, CryptGetKeyParam, CryptHashData, CryptHashSessionKey, CryptSetHashParam


CryptGetKeyParam [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptGetKeyParam

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptGetKeyParam function lets applications retrieve data that governs of the operations of a key. Note that the base keying material is not obtainable by this function or any other function.

BOOL CRYPTFUNC CryptGetKeyParam(

HCRYPTKEY hKey,
DWORD dwParam,
BYTE *pbData,
DWORD *pdwDataLen,
DWORD dwFlags
);
Parameters

hKey

[in] A handle to the key on which to query parameters.

dwParam

[in] The parameter number. See the “Remarks” section for a list of valid parameters.

pbData

[out] The parameter data buffer. The function will copy the specified parameter data to this buffer. The form of this data will vary, depending on the parameter number.

This parameter can be NULL if all you are doing is determining the number of bytes required for the returned parameter data.

pdwDataLen

[in/out] The address of the parameter data length. Before calling this function, the caller should set this parameter to the length, in bytes, of the pbData buffer. Upon return, this address will contain the number of bytes of parameter data copied to the buffer.

If the buffer specified by pbData is not large enough to hold the data, the function returns the ERROR_MORE_DATA error code (through GetLastError) and stores the required buffer size, in bytes, into the variable pointed to by pdwDataLen.

If pbData is NULL, then no error is returned and the function stores the size of the data, in bytes, in the variable pointed to by pdwDataLen.

dwFlags

[in] The flag values. This parameter is reserved for future use and should always be zero.

Remarks

For all key types, the dwParam value can be set to one of the following key parameter types:

Parameter	Description
KP_ALGID	Key algorithm. The pbData buffer will contain an ALG_ID value indicating that the algorithm was specified when the key was created.
KP_BLOCKLEN	If a session key is specified by hKey, this parameter returns the block length, in bits, of the cipher. The pbData buffer will contain a DWORD value indicating the block length. For stream ciphers, this value will always be zero. If a public/private key pair is specified by hKey, this parameter returns the key pair’s encryption granularity in bits. For example, the Microsoft RSA Base Provider generates 512-bit RSA key pairs, so a value of 512 is returned for these keys. If the public-key algorithm does not support encryption, the value returned by this parameter is undefined.
KP_SALT	The salt value. The pbData buffer will contain a BYTE array indicating the current salt value. The size of the salt value will vary depending on the CSP and algorithm being used. Before setting this parameter, it should be read using CryptGetKeyParam in order to determine the size. Salt values do not apply to public/private key pairs.
KP_PERMISSIONS	Key permissions. The pbData buffer will contain a DWORD value with zero or more permission flags set. Refer to the table at the end of this section for a description of each of these flags.
If a block cipher session key is specified by hKey, the dwParam value can also be set to one of the following parameter types.

Parameter	Description
KP_IV	The initialization vector. The pbData buffer will contain a BYTE array indicating the current initialization vector. This array contains <block length>/8 elements. For example, if the block length is 64 bits, the initialization vector will consist of 8 bytes.
KP_PADDING	The padding mode. The pbData buffer will contain a DWORD value indicating the padding method used by the cipher. Following are the padding modes currently defined: PKCS5_PADDING — PKCS 5 (sec 6.2) padding method.
KP_MODE	The cipher mode. The pbData buffer will contain a DWORD value indicating the mode of the cipher. Refer to the following table for a list of valid cipher modes.
KP_MODE_BITS	The number of bits to feed back. The pbData buffer will contain a DWORD value indicating the number of bits that are processed per cycle when the OFB or CFB cipher modes are used.
The following table lists the possible values for the KP_MODE parameter. These cipher modes are discussed in the section Encrypting and Decrypting Data.

Cipher Mode	Description
CRYPT_MODE_ECB	Electronic codebook.
CRYPT_MODE_CBC	Cipher block chaining.
CRYPT_MODE_OFB	Output feedback mode.
CRYPT_MODE_CFB	Cipher feedback mode.
The following table lists the flags in the bit field that are obtained when the KP_PERMISSIONS parameter is read. These permission flags are ignored by the Microsoft RSA Base Provider. However, custom CSPs can use these flags to restrict operations on keys.

Permission Flag	Description
CRYPT_ENCRYPT	Allow encryption.
CRYPT_DECRYPT	Allow decryption.
CRYPT_EXPORT	Allow key to be exported.
CRYPT_READ	Allow parameters to be read.
CRYPT_WRITE	Allow parameters to be set.
CRYPT_MAC	Allow MACs to be used with key.
Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
NTE_BAD_KEY or NTE_NO_KEY	The key specified by the hKey parameter is invalid.
NTE_BAD_TYPE	The dwParam parameter specifies an unknown parameter number.
NTE_BAD_UID	The CSP context that was specified when the key was created cannot be found.
Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;

HCRYPTKEY hKey = 0;

DWORD dwMode;

BYTE pbData[16];

DWORD dwCount;

DWORD i;

// Get handle to user default provider.

if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {

    printf("Error %x during CryptAcquireContext!\n", GetLastError());

    goto done;

}

// Create random block cipher session key.

if(!CryptGenKey(hProv, CALG_RC2, CRYPT_EXPORTABLE, &hKey)) {

    printf("Error %x during CryptGenKey!\n", GetLastError());

    goto done;

}

// Read the cipher mode.

dwCount = sizeof(DWORD);

if(!CryptGetKeyParam(hKey, KP_MODE, &dwMode, &dwCount, 0)) {

    printf("Error %x during CryptGetKeyParam!\n", GetLastError());

    goto done;

}

assert(dwCount==sizeof(BYTE));

// Print out cipher mode.

printf("Default cipher mode:%d\n", dwMode);

// Read initialization vector.

dwCount = 16;

if(!CryptGetKeyParam(hKey, KP_IV, pbData, &dwCount, 0)) {

    printf("Error %x during CryptGetKeyParam!\n", GetLastError());

    goto done;

}

// Print out initialization vector.

printf("Default IV:");

for(i=0;i<dwCount;i++) printf("%2.2x ",pbData[i]);

printf("\n");

done:

// Destroy session key.

if(hKey != 0) CryptDestroyKey(hKey);

// Release provider handle.

if(hProv != 0) CryptReleaseContext(hProv, 0);

See Also

CryptSetKeyParam


CryptGetProvParam [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptGetProvParam

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptGetProvParam function lets applications retrieve parameters that govern the operations of a CSP.

BOOL CRYPTFUNC CryptGetProvParam(

HCRYPTPROV hProv,
DWORD dwParam,
BYTE *pbData,
DWORD *pdwDataLen,
DWORD dwFlags
);
Parameters

hProv

[in] A handle to the CSP on which to query parameters.

dwParam

[in] The parameter number. See the “Remarks” section for a list of valid parameters.

pbData

[out] The parameter data buffer. The function will copy the specified parameter data to this buffer. The form of this data will vary, depending on the parameter number.

This parameter can be NULL if all you are doing is determining the number of bytes required for the returned parameter data.

pdwDataLen

[in/out] The address of the parameter data length. Before calling this function, the caller should set this parameter to the length, in bytes, of the pbData buffer. Upon return, this address will contain the number of bytes of parameter data copied to the buffer.

If the buffer specified by pbData is not large enough to hold the data, the function returns the ERROR_MORE_DATA error code through the GetLastError function, and stores the required buffer size in bytes into the variable pointed to by pdwDataLen.

If pbData is NULL, then no error is returned and the function stores the size of the data in bytes in the variable pointed to by pdwDataLen.

Note  When one of the enumeration parameters (PP_ENUMALGS or PP_ENUMCONTAINERS) is being read, the pdwDataLen parameter works somewhat differently. If pbData is NULL or the value pointed to pdwDataLen is too small, the value returned in this parameter is the size of the largest item in the enumeration list instead of the size of the item currently being read.

When one of the enumeration parameters is read and the pbData parameter is NULL, the CRYPT_FIRST flag must be specified in order for the size information to be correctly retrieved.

dwFlags

[in] The flag values. This parameter is normally set to zero.

When one of the enumeration parameters (PP_ENUMALGS or PP_ENUMCONTAINERS) is being read, then the CRYPT_FIRST flag can be specified. When this flag is set, the first item in the enumeration list is returned. If this flag is not set, then the next item in the list is returned.

Remarks

Parameter Numbers

The dwParam parameter can be set to one of the following values:

PP_CONTAINER

The key container name. When this parameter is specified, the function fills the pbData buffer with the name of the current key container. This name is in the form of a zero-terminated CHAR string.

This string is exactly the same as the one passed in the pszContainer parameter of the CryptAcquireContext function in order to specify that the current key container be used. This parameter is often read in order to determine the name of the default key container.

PP_ENUMALGS

The algorithm information. When this parameter is specified, the function fills the pbData buffer with information about one of the algorithms supported by the CSP. The PP_ENUMALGS parameter must be read repeatedly to enumerate all the supported algorithms. The algorithms are not enumerated in any particular order.

The first time that the PP_ENUMALGS parameter is read, the CRYPT_FIRST flag should be specified. This will ensure that information about the “first” algorithm in the enumeration list is returned. The PP_ENUMALGS parameter can then be repeatedly read in order to retrieve the information about the rest of the algorithms. When the CryptGetProvParam function fails with the ERROR_NO_MORE_ITEMS, then the end of the enumeration list has been reached. A code sample illustrating this is located in the “Example” section.

The following code fragment indicates the format of the data that the function returns in the pbData buffer.

ALG_ID aiAlgid;

DWORD dwBits;

DWORD dwNameLen;

CHAR szName[dwNameLen];

The following table defines each of these fields.

Field	Description
aiAlgid	The algorithm identifier. This is the value that is passed to the CryptGenKey, CryptDeriveKey, or CryptCreateHash functions in order to specify that a particular algorithm be used.
dwBits	The number of bits in the keys used by the algorithm.  If this is a hash algorithm, this value indicates the number of bits in the hash values generated by this algorithm.
dwNameLen	The number of characters in the algorithm name, including the terminating zero.
szName	The zero-terminated name of the algorithm.
PP_ENUMCONTAINERS

The key container names. When this parameter is specified, the function fills the pbData buffer with the name of one of the key containers maintained by the CSP. This name is in the form of a zero-terminated CHAR string. The PP_ENUMCONTAINERS parameter must be read repeatedly to enumerate all the container names.

These container names are enumerated in the same way as are the CSP’s supported algorithms. Refer to the PP_ENUMALGS for more information.

PP_IMPTYPE

The CSP implementation type. The pbData buffer will contain a DWORD value that indicates how the CSP is implemented. Possible values are:

•	CRYPT_IMPL_HARDWARE

•	CRYPT_IMPL_SOFTWARE

•	CRYPT_IMPL_MIXED

•	CRYPT_IMPL_UNKNOWN (the CSP isn’t telling)

PP_NAME

The CSP name. When this parameter is specified, the function fills the pbData buffer with the name of the CSP. This name is in the form of a zero-terminated CHAR string.

This string is identical to the one passed in the pszProvider parameter of the CryptAcquireContext function in order to specify that the current CSP be used. For example, the Microsoft RSA Base Provider will return “Microsoft Base Cryptographic Provider v1.0” when this parameter is read.

PP_VERSION

The CSP version number. The pbData buffer will contain a DWORD value that indicates the version number of the CSP. The least significant byte contains the minor version number and the next most significant byte the major version number. For example, version 1.0 would be represented here as 0x00000100.

Algorithm Identifiers

When enumerating algorithms, your application may need to determine the class of a particular algorithm. For example, you may want to display a list of encryption algorithms to the user and disregard the rest. This can be done with the GET_ALG_CLASS(x) macro. This macro takes an algorithm identifier as an argument and returns a code indicating the general class of algorithm that the identifier belongs to. Possible return values include:

•	ALG_CLASS_DATA_ENCRYPT

•	ALG_CLASS_HASH

•	ALG_CLASS_KEY_EXCHANGE

•	ALG_CLASS_SIGNATURE

The following table lists the algorithms supported by the Microsoft RSA Base Provider along with the class of each algorithm.

Name	Identifier	Class
“MD2”	CALG_MD2	ALG_CLASS_HASH
“MD5”	CALG_MD5	ALG_CLASS_HASH
“SHA”	CALG_SHA	ALG_CLASS_HASH
“MAC”	CALG_MAC	ALG_CLASS_HASH
“RSA_SIGN”	CALG_RSA_SIGN	ALG_CLASS_SIGNATURE
“RSA_KEYX”	CALG_RSA_KEYX	ALG_CLASS_KEY_EXCHANGE
“RC2”	CALG_RC2	ALG_CLASS_DATA_ENCRYPT
“RC4”	CALG_RC4	ALG_CLASS_DATA_ENCRYPT
If your application does not recognize an algorithm identifier, it is not recommended that it use the algorithm. Making use of an unknown cryptographic algorithm can sometimes produce unpredictable results.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes  prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_NO_MORE_ITEMS	The end of the enumeration list has been reached. No valid data has been placed in the pbData buffer. This error is only returned when dwParam equals PP_ENUMALGS or PP_ENUMCONTAINERS.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
NTE_BAD_TYPE	The dwParam parameter specifies an unknown parameter number.
NTE_BAD_UID	The CSP context specified by hProv is invalid.
Example

This example shows how the list of algorithms supported by a particular CSP is accessed by an application.

HCRYPTPROV hProv;         // Handle to CSP

DWORD dwAlgCount;

BYTE *ptr = NULL;

DWORD i;

ALG_ID aiAlgid;

DWORD dwBits;

DWORD dwNameLen;

CHAR szName[100];         // Often allocated dynamically.

BYTE pbData[1000];        // Often allocated dynamically.

DWORD dwDataLen;

DWORD dwFlags;

CHAR *pszAlgType = NULL;

// Enumerate the supported algorithms.

for(i=0 ; ; i++) {

    // Set the CRYPT_FIRST flag the first time through the loop.

    if(i == 0) {

        dwFlags = CRYPT_FIRST;

    } else {

        dwFlags = 0;

    }

    // Retrieve information about an algorithm.

    dwDataLen = 1000;

    if(!CryptGetProvParam(hProv, PP_ENUMALGS, pbData, &dwDataLen, 0)) {

        if(GetLastError() == ERROR_NO_MORE_ITEMS) {

            // Exit the loop.

            break;

        } else {

            printf("Error %x reading algorithm!\n", GetLastError());

            return;

        }

    }

    // Extract algorithm information from ‘pbData’ buffer.

    ptr = pbData;

    aiAlgid = *(ALG_ID *)ptr;

    ptr += sizeof(ALG_ID);

    dwBits = *(DWORD *)ptr;

    ptr += sizeof(DWORD);

    dwNameLen = *(DWORD *)ptr;

    ptr += sizeof(DWORD);

    strncpy(szName, ptr,dwNameLen);

    // Determine algorithm type.

    switch(GET_ALG_CLASS(aiAlgid)) {

        case ALG_CLASS_DATA_ENCRYPT: pszAlgType = “Encrypt  “;

                                     break;

        case ALG_CLASS_HASH:         pszAlgType = “Hash     “;

                                     break;

        case ALG_CLASS_KEY_EXCHANGE: pszAlgType = “Exchange “;

                                     break;

        case ALG_CLASS_SIGNATURE:    pszAlgType = “Signature”;

                                     break;

        default:                     pszAlgType = “Unknown  “;

    }

    // Print information about algorithm.

    printf(“Algid:%8.8xh, Bits:%-4d, Type:%s, NameLen:%-2d, Name:%s\n”,

        aiAlgid, dwBits, pszAlgType, dwNameLen, szName

    );

}

See Also

CryptAcquireContext, CryptCreateHash, CryptDeriveKey, CryptGenKey, CryptGetKeyParam, CryptSetProvParam


CryptGetUserKey [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptGetUserKey

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptGetUserKey function retrieves a handle to a permanent user key pair, such as the user’s signature key pair.

BOOL CRYPTFUNC CryptGetUserKey(

HCRYPTPROV hProv,
DWORD dwKeySpec,
HCRYPTKEY *phUserKey
);
Parameters

hProv

[in] A handle to the application’s CSP. An application obtains this handle using the CryptAcquireContext function.

dwKeySpec

[in] The specification of the key to retrieve. The following keys are retrievable from almost all providers:

•	AT_KEYEXCHANGE — Exchange public key

•	AT_SIGNATURE — Signature public key

Additionally, some providers allow access to other user specific keys through this function. See the documentation on the specific provider for details.

phUserKey

[out] The address that the function copies the handle of the retrieved key to.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_KEY	The dwKeySpec parameter contains an invalid value.
NTE_BAD_UID	The hProv parameter does not contain a valid context handle.
NTE_NO_KEY	The key requested by the dwKeySpec parameter does not exist.
Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;

HCRYPTKEY hSignKey = 0;

HCRYPTKEY hXchgKey = 0;

// Get handle to user default provider.

if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {

    printf("Error %x during CryptAcquireContext!\n", GetLastError());

    goto done;

}

// Get handle to signature key.

if(!CryptGetUserKey(hProv, AT_SIGNATURE, &hSignKey)) {

    printf("Error %x during CryptGetUserKey!\n", GetLastError());

    goto done;

}

// Get handle to key exchange key.

if(!CryptGetUserKey(hProv, AT_KEYEXCHANGE, &hXchgKey)) {

    printf("Error %x during CryptGetUserKey!\n", GetLastError());

    goto done;

}

// Do something with 'hSignKey' and 'hXchgKey'.

...

done:

// Destroy signature key handle.

if(hSignKey != 0) CryptDestroyKey(hSignKey);

// Destroy key exchange key handle.

if(hXchgKey != 0) CryptDestroyKey(hXchgKey);

// Release provider handle.

if(hProv != 0) CryptReleaseContext(hProv, 0);

See Also

CryptAcquireContext, CryptDestroyKey, CryptGenKey


CryptHashData [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptHashData

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptHashData function is used to compute the cryptographic hash on a stream of data. This function and CryptHashSessionKey can be called multiple times to compute the hash on long streams or on discontinuous streams.

Before calling this function, the CryptCreateHash function must be called to get a handle to a hash object.

BOOL CRYPTFUNC CryptHashData(

HCRYPTHASH hHash,
BYTE *pbData,
DWORD dwDataLen,
DWORD dwFlags
);
Parameters

hHash

[in] A handle to the hash object. An application obtains this handle using the CryptCreateHash function.

pbData

[in] The address of the data to be hashed.

dwDataLen

[in] The number of bytes of data to be hashed. This must be zero if the CRYPT_USERDATA flag is set.

dwFlags

[in] The flag values. The following values are currently defined:

•	CRYPT_USERDATA

When this flag is set, the CSP will prompt the user to input some data directly. This is then added to the hash. The application is not allowed access to the data. For example, this flag can be used to allow the user to enter a PIN into the system.

The Microsoft RSA Base Provider ignores this parameter.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID	The hHash handle specifies an algorithm that this CSP does not support.
NTE_BAD_FLAGS	The dwFlags parameter contains an invalid value.
NTE_BAD_HASH	The hash object specified by the hHash parameter is invalid.
NTE_BAD_HASH_STATE	An attempt was made to add data to a hash object that is already marked “finished.”
NTE_BAD_KEY	A keyed hash algorithm is being used, but the session key is no longer valid. This error will be generated if the session key is destroyed before the hashing operating is complete.
NTE_BAD_LEN	The CRYPT_USERDATA flag is set and the dwDataLen parameter has a nonzero value.
NTE_BAD_UID	The CSP context that was specified when the hash object was created cannot be found.
NTE_FAIL	The function failed in some unexpected way.
NTE_NO_MEMORY	The CSP ran out of memory during the operation.
Example

See the “Example” section in the CryptSignHash function.

See Also

CryptCreateHash, CryptHashSessionKey, CryptSignHash


CryptHashSessionKey [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptHashSessionKey

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptHashSessionKey function is used to compute the cryptographic hash on a key object. This function can be called multiple times with the same hash handle to compute the hash on multiple keys. Calls to CryptHashSessionKey can be interspersed with calls to CryptHashData.

Before calling this function the CryptCreateHash function must be called to get a handle to a hash object.

BOOL CRYPTFUNC CryptHashSessionKey(

HCRYPTHASH hHash,
HCRYPTKEY hKey,
DWORD dwFlags
);
Parameters

hHash

[in] A handle to the hash object. An application obtains this handle using the CryptCreateHash function.

hKey

[in] A handle to the key object to be hashed.

dwFlags

[in] The flag values. This parameter is reserved for future use and should always be zero.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID	The hHash handle specifies an algorithm that this CSP does not support.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
NTE_BAD_HASH	The hash object specified by the hHash parameter is invalid.
NTE_BAD_HASH_STATE	An attempt was made to add data to a hash object that is already marked “finished.”
NTE_BAD_KEY	A keyed hash algorithm is being used, but the session key is no longer valid. This error will be generated if the session key is destroyed before the hashing operating is complete.
NTE_BAD_UID	The CSP context that was specified when the hash object was created cannot be found.
NTE_FAIL	The function failed in some unexpected way.
Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;

HCRYPTHASH hHash = 0;

HCRYPTKEY hKey   = 0;

// Get handle to the default provider.

if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {

    printf("Error %x during CryptAcquireContext!\n", GetLastError());

    goto done;

}

// Create hash object.

if(!CryptCreateHash(hProv, CALG_MD5, 0, 0, &hHash)) {

    printf("Error %x during CryptBeginHash!\n", GetLastError());

    goto done;

}

// Create random session key.

if(!CryptGenKey(hProv, CALG_RC2, CRYPT_EXPORTABLE, &hKey)) {

    printf("Error %x during CryptGenKey!\n", GetLastError());

    goto done;

}

// Hash session key.

if(!CryptHashSessionKey(hHash, hKey, 0)) {

    printf("Error %x during CryptHashSessionKey!\n", GetLastError());

    goto done;

}

// Use the hash object for something.

...

done:

// Destroy hash object.

if(hHash) CryptDestroyHash(hHash);

// Destroy session key.

if(hKey) CryptDestroyKey(hKey);

// Release CSP handle.

if(hProv) CryptReleaseContext(hProv,0);

See Also

CryptCreateHash, CryptGenKey, CryptHashData


CryptImportKey [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptImportKey

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptImportKey function is used to transfer a cryptographic key from a key blob to the CSP.

BOOL CRYPTFUNC CryptImportKey(

HCRYPTPROV hProv,
BYTE *pbData,
DWORD dwDataLen,
HCRYPTKEY hImpKey,
DWORD dwFlags,
HCRYPTKEY *phKey
);
Parameters

hProv

[in] A handle to the application’s CSP. An application obtains this handle using the CryptAcquireContext function.

pbData

[in] The buffer containing the key blob. This key blob was generated by the CryptExportKey function, either by this same application or by another application running on a distant computer.

This key blob consists of a standard header followed by the encrypted key.

dwDataLen

[in] The length, in bytes, of the key blob.

hImpKey

[in] The meaning of this parameter differs, depending on the CSP type and the type of key blob being imported.

If the key blob is not encrypted (for example, a PUBLICKEYBLOB) or if the key blob is encrypted with the key exchange key pair (for example, a SIMPLEBLOB), then this parameter is not used, and should be zero.

If a signed key blob is being imported, this key is used to validate the signature of the key blob. In this case, this parameter should contain a handle to the key exchange public key of the party that created the key blob.

If the key blob is encrypted with a session key (for example, an encrypted PRIVATEKEYBLOB), then this parameter should contain a handle to this session key.

dwFlags

[in] The flag values. This parameter is currently only used when a public/private key pair is being imported into the CSP (in the form of a PRIVATEKEYBLOB). In this case, if the CRYPT_EXPORTABLE flag is set then subsequent applications will be permitted to export the private key back out of the CSP.

phKey

[out] The address to which the function copies a handle to the key that was imported.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID	The simple key blob you are trying to import is not encrypted with the expected key exchange algorithm.
NTE_BAD_DATA	The algorithm that works with the public key you are trying to import is not supported by this CSP.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
NTE_BAD_TYPE	The key blob type is not supported by this CSP and is possibly invalid.
NTE_BAD_UID	The hProv parameter does not contain a valid context handle.
NTE_BAD_VER	The key blob’s version number does not match the CSP version. This usually indicates that the CSP needs to be upgraded.
Example

#include <wincrypt.h>

FILE *hSourceFile = NULL;

HCRYPTPROV hProv = 0;

HCRYPTKEY hKey = 0;

BYTE *pbKeyBlob = NULL;

DWORD dwBlobLen;

// Open file, getting file handle ‘hSourceFile’.

...

// Get handle to the default provider.

if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {

    printf("Error %x during CryptAcquireContext!\n", GetLastError());

    goto done;

}

// Read key blob length from file and allocate memory.

fread(&dwBlobLen, sizeof(DWORD), 1, hSourceFile);

pbKeyBlob = malloc(dwBlobLen);

// Read key blob from file.

fread(pbKeyBlob, 1, dwBlobLen, hSourceFile);

// Import key blob into CSP.

if(!CryptImportKey(hProv, pbKeyBlob, dwBlobLen, 0, 0, &hKey)) {

    printf("Error %x during CryptImportKey!\n", GetLastError());

    free(pbKeyBlob);

    goto done;

}

// Free memory.

free(pbKeyBlob);

// Use ‘hKey’ to perform cryptographic operations.

...

done:

// Destroy session key.

if(hKey) CryptDestroyKey(hKey);

// Release provider handle.

if(hProv) CryptReleaseContext(hProv, 0);

See Also

CryptAcquireContext, CryptDestroyKey, CryptExportKey


CryptReleaseContext [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptReleaseContext

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptReleaseContext function is used to release a handle to a CSP and a key container.

This should be performed when the application is finished using the CSP. Once this function is called, the CSP handle specified by the hProv parameter will no longer be valid. Neither the key container nor any key pairs are destroyed by this function.

BOOL CRYPTFUNC CryptReleaseContext(

HCRYPTPROV hProv,
DWORD dwFlags
);
Parameters

hProv

[in] A handle to the application’s CSP. This is the handle the application obtained using the CryptAcquireContext function.

dwFlags

[in] The flag values. This parameter is reserved for future use and should always be zero.

Remarks

Once this function has been called, the “session” is over, and all existing session keys and hash objects that were created using the hProv handle become invalid. In practice, all of these objects should be destroyed (with the CryptDestroyKey and CryptDestroyHash functions) before the CryptReleaseContext function is called.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_BUSY	The CSP context specified by hProv is currently being used by another process.
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
NTE_BAD_UID	The hProv parameter does not contain a valid context handle.
Example

See the “Example” section in the CryptAcquireContext function.

See Also

CryptAcquireContext, CryptDestroyKey and CryptDestroyHash


CryptSetHashParam [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptSetHashParam

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptSetHashParam function, in theory, allows applications to customize the operations of a hash object. Currently, only a single parameter is defined for this function.

BOOL CRYPTFUNC CryptSetHashParam(

HCRYPTHASH hHash,
DWORD dwParam,
BYTE *pbData,
DWORD dwFlags
);
Parameters

hHash

[in] A handle to the hash object on which to set parameters.

dwParam

[in] The parameter number. See the “Remarks” section for a list of valid parameters.

pbData

[in] The parameter data buffer. Place the parameter data in this buffer before calling CryptSetHashParam. The form of this data will vary, depending on the parameter number.

dwFlags

[in] The flag values. This parameter is reserved for future use and should always be zero.

Remarks

The dwParam parameter can be set to one of the following values:

HP_HASHVAL

Hash value. The pbData buffer should contain a byte array containing a hash value to place directly into the hash object. Before setting this parameter, the size of the hash value should be determined by reading the HP_HASHSIZE parameter with the CryptGetHashParam function.

Normal applications should never set this parameter. In fact, some CSPs may not even support this capability. Occasionally though, it is convenient to sign a hash value that has been generated elsewhere. This is the usual sequence of operations:

1.	The application creates a hash object with CryptCreateHash.

2.	It specifies a hash value by setting the HP_HASHVAL parameter.

3.	It signs the hash value using CryptSignHash, obtaining a digital signature block.

Because the binding between the hashed data and the signature is fairly tenuous, no description string can be passed into CryptSignHash in this situation.

4.	It destroys the hash object using CryptDestroyHash.

Note that some CSP types may add additional parameters that can be set with this function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_BUSY	The CSP context is currently being used by another process.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero or the pbData buffer contains an invalid value.
NTE_BAD_HASH	The hash object specified by the hHash parameter is invalid.
NTE_BAD_TYPE	The dwParam parameter specifies an unknown parameter.
NTE_BAD_UID	The CSP context that was specified when the hKey key was created cannot be found.
NTE_FAIL	The function failed in some unexpected way.
Example

This function is used in a way similar to the CryptSetKeyParam function.

See Also

CryptCreateHash, CryptDestroyHash, CryptGetHashParam, CryptSetKeyParam, CryptSignHash


CryptSetKeyParam [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptSetKeyParam

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptSetKeyParam function lets applications customize various aspects of a key’s operations.

Generally, this function is used to set session-specific parameters on symmetric keys. Note that the base keying material is not accessible by this function.

The Microsoft RSA Base Provider has no settable parameters on key exchange or signature keys. However, custom providers may define parameters that can be set on these keys.

BOOL CRYPTFUNC CryptSetKeyParam(

HCRYPTKEY hKey,
DWORD dwParam,
BYTE *pbData,
DWORD dwFlags
);
Parameters

hKey

[in] A handle to the key on which to set parameters.

dwParam

[in] The parameter number. See the “Remarks” section for a list of valid parameters.

pbData

[in] The parameter data buffer. Place the parameter data in this buffer before calling CryptSetKeyParam. The form of this data will vary, depending on the parameter number.

dwFlags

[in] The flag values. This parameter is reserved for future use and should always be zero.

Remarks

For all session key types, the dwParam value can be set to one of the following key parameter types;

Parameter	Description
KP_SALT	The salt value. The pbData buffer should contain a BYTE array specifying a new salt value. This value is made part of the session key. The size of the salt value will vary depending on the CSP being used so, before setting this parameter, it should be read using CryptGetKeyParam in order to determine its size. When it is suspected that the base data used for derived keys is less than ideal, salt values are often used to make the session keys more unique. This makes dictionary attacks more difficult. When using the Microsoft RSA Base Provider, this parameter defaults to zero.
KP_PERMISSIONS	The key permissions flags. The pbData buffer should contain a DWORD value specifying zero or more permission flags. Refer to the CryptGetKeyParam function for a description of these flags. When using the Microsoft RSA Base Provider, this parameter defaults to 0xFFFFFFFF.
If a block cipher session key is specified by hKey, the dwParam value can also be set to one of the following parameter types.

Parameter	Description
KP_IV	The initialization vector. The pbData buffer should contain a BYTE array specifying the initialization vector. This array should contain <block length>/8 elements. For example, if the block length is 64 bits, the initialization vector will consist of 8 bytes. When using the Microsoft RSA Base Provider, this parameter defaults to zero.
KP_PADDING	The padding mode. The pbData buffer should contain a DWORD value specifying the padding method to be used by the cipher. Following are the padding modes currently defined: PKCS5_PADDING — PKCS 5 (sec 6.2) padding method. When using the Microsoft RSA Base Provider, this parameter defaults to PKCS5_PADDING.
KP_MODE	The cipher mode. The pbData buffer should contain a DWORD value specifying the cipher mode to be used. Refer to the CryptGetKeyParam function for a list  of the defined cipher modes. When using the Microsoft RSA Base Provider, this parameter defaults to CRYPT_MODE_CBC.
KP_MODE_BITS	The number of bits to feed back. The pbData buffer contains a DWORD value indicating the number of bits that are processed per cycle when the OFB or CFB cipher modes are used. When using the Microsoft RSA Base Provider, this parameter defaults to 8.
Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_BUSY	The CSP context is currently being used by another process.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero or the pbData buffer contains an invalid value.
NTE_BAD_TYPE	The dwParam parameter specifies an unknown parameter.
NTE_BAD_UID	The CSP context that was specified when the hKey key was created cannot be found.
NTE_FAIL	The function failed in some unexpected way.
Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;

HCRYPTKEY hKey = 0;

DWORD dwMode;

BYTE pbData[16];

DWORD dwCount;

DWORD i;

// Get handle to user default provider.

if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {

    printf("Error %x during CryptAcquireContext!\n", GetLastError());

    goto done;

}

// Create random block cipher session key.

if(!CryptGenKey(hProv, CALG_RC2, CRYPT_EXPORTABLE, &hKey)) {

    printf("Error %x during CryptGenKey!\n", GetLastError());

    goto done;

}

// Set the cipher mode.

dwMode = CRYPT_MODE_ECB;

if(!CryptSetKeyParam(hKey, KP_MODE, &dwMode, 0)) {

    printf("Error %x during CryptSetKeyParam!\n", GetLastError());

    goto done;

}

// Generate random initialization vector.

if(!CryptGenRandom(hProv, 8, pbData)) {

    printf("Error %x during CryptGenRandom!\n", GetLastError());

    goto done;

}

// Set initialization vector.

if(!CryptSetKeyParam(hKey, KP_IV, pbData, 0)) {

    printf("Error %x during CryptGetKeyParam!\n", GetLastError());

    goto done;

}

// Do something with 'hKey'.

...

done:

// Destroy session key.

if(hKey != 0) CryptDestroyKey(hKey);

// Release provider handle.

if(hProv != 0) CryptReleaseContext(hProv, 0);

See Also

CryptGenKey, CryptGetKeyParam


CryptSetProvider [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptSetProvider

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptSetProvider function is used to specify the current user default CSP.

After this function has been called, any calls this user subsequently makes to CryptAcquireContext specifying the dwProvType provider type but not a provider name, will result in the pszProvName provider being used.

Note  Typical applications will not use this function. It is intended for sole use by administrative applications.

BOOL CRYPTFUNC CryptSetProvider(

LPCTSTR pszProvName,
DWORD dwProvType
);
Parameters

pszProvName

[in] The name of the new default CSP. This CSP should have already been installed on the computer.

dwProvType

[in] The provider type of the CSP specified by the pszProvName parameter.

Remarks

Well-behaved applications do not usually specify a CSP name when calling the CryptAcquireContext function. This gives the users a certain amount of freedom in that they can select a CSP that has an appropriate level of security.

This means that a call to CryptSetProvider will often determine the CSP of a given type used by all applications that run from that point on. With this being the case, the CryptSetProvider function should never be called without the user’s consent.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_NOT_ENOUGH_MEMORY	The operating system ran out of memory during the operation.
Error codes returned from the RegCreateKeyEx function.	See RegCreateKeyEx.
Error codes returned from the RegSetValueEx function.	See RegSetValueEx.
Example

HCRYPTPROV hProv = 0;

// Specify the default PROV_RSA_SIG provider. Note that this assumes

// that a CSP with a type of PROV_RSA_SIG and named "Joe's Provider"

// has already been installed.

if(!CryptSetProvider(TEXT("Joe's Provider"), PROV_RSA_SIG)) {

    printf("Error %x during CryptSetProvider!\n", GetLastError());

    return;

}

// Get handle to the provider that we just made default.

if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_SIG, 0)) {

    printf("Error %x during CryptAcquireContext!\n", GetLastError());

    return;

}

...

// Release provider handle.

if(!CryptReleaseContext(hProv, 0)) {

    printf("Error %x during CryptReleaseContext!\n", GetLastError());

    return;

}

See Also

CryptAcquireContext


CryptSetProvParam [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptSetProvParam

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptSetProvParam function lets applications customize the operations of a CSP.

BOOL CRYPTFUNC CryptSetProvParam(

HCRYPTPROV hProv,
DWORD dwParam,
BYTE *pbData,
DWORD dwFlags
);
Parameters

hProv

[in] A handle to the CSP on which to set parameters.

dwParam

[in] The parameter number to set.

When this parameter is set to PP_CLIENT_HWND, the pbData buffer should contain a DWORD value specifiying the window handle that the provider is to use when interacting directly with the user. When setting this parameter, applications should call the CryptSetProvParam function before calling CryptAcquireContext. This is necessary because many CSPs will display a user interface during the CryptAcquireContext function. Note that CSPs that do not ever display a user interface will ignore the value of this parameter.

pbData

[in] The parameter data buffer. Place the parameter data in this buffer before calling CryptSetProvParam. The form of this data will vary, depending on the parameter number.

dwFlags

[in] The flag values. This parameter is reserved for future use and should always be zero.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_BUSY	The CSP context is currently being used by another process.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero or the pbData buffer contains an invalid value.
NTE_BAD_TYPE	The dwParam parameter specifies an unknown parameter.
NTE_BAD_UID	The CSP context that was specified when the hKey key was created cannot be found.
NTE_FAIL	The function failed in some unexpected way.
See Also

CryptAcquireContext, CryptGetProvParam, CryptSetKeyParam


CryptSignHash [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptSignHash

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptSignHash function is used to sign a piece of data. Because all signature algorithms are asymmetric and thus incredibly slow, CryptoAPI will not let data be signed directly. Instead, you must first hash the data and then use CryptSignHash to sign the hash value.

BOOL CRYPTFUNC CryptSignHash(

HCRYPTHASH hHash,
DWORD dwKeySpec,
LPCTSTR sDescription,
DWORD dwFlags,
BYTE *pbSignature,
DWORD *pdwSigLen
);
Parameters

hHash

[in] A handle to the hash object to be signed.

dwKeySpec

[in] The key pair to use to sign the hash. The following keys can be specified:

•	AT_KEYEXCHANGE — Exchange private key

•	AT_SIGNATURE — Signature private key

The signature algorithm used is specified when the key pair was originally created.

The only signature algorithm that the Microsoft RSA Base Provider supports is the RSA Public-Key algorithm.

sDescription

[in] The string describing the data to sign. This description text is added to the hash object before the signature is generated. Whenever the signature is authenticated (with CryptVerifySignature), the exact same description string must be supplied. This ensures that both the signer and the authenticator agree on what is being signed or authenticated.

Some CSPs (not the Microsoft RSA Base Provider) will display this description string to the user. This lets the user confirm what he or she is signing. This protects the user from unscrupulous applications and also reduces misunderstandings.

This parameter can be NULL if no description string is to included in the signature. Usually, this is only the case when the signature is performed using a signature key that is not legally bound to the user. For example, when a signature operation is performed with the key exchange private key as part of a key exchange protocol, no description string is typically specified.

dwFlags

[in] The flag values. This parameter is reserved for future use and should always be zero.

pbSignature

[out] The buffer in which the function places the signature data.

This parameter can be NULL if all you are doing is determining the number of bytes required for the returned signature data.

pdwSigLen

[in/out] The address of the signature data length. Before calling this function, the caller should set this parameter to the length, in bytes, of the pbSignature buffer. Upon return, this address will contain the number of bytes in the signature data.

If the buffer specified by pbSignature is not large enough to hold the data, the function returns the ERROR_MORE_DATA error code (through GetLastError) and stores the required buffer size, in bytes, into the variable pointed to by pdwSigLen.

If pbSignature is NULL, then no error is returned and the function stores the size of the data, in bytes, in the variable pointed to by pdwSigLen.

Remarks

Before calling this function, the CryptCreateHash function must be called to get a handle to a hash object. The CryptHashData or CryptHashSessionKey function is then used to add the data or session keys to the hash object.

Once this function has been completed, the only hash function that can be called using the hHash handle is the CryptDestroyHash function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

Error	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID	The hHash handle specifies an algorithm that this CSP does not support.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
NTE_BAD_HASH	The hash object specified by the hHash parameter is invalid.
NTE_BAD_UID	The CSP context that was specified when the hash object was created cannot be found.
NTE_NO_KEY	The private key specified by dwKeySpec does not exist.
NTE_NO_MEMORY	The CSP ran out of memory during the operation.
Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;

#define BUFFER_SIZE 256

BYTE pbBuffer[BUFFER_SIZE];

HCRYPTHASH hHash = 0;

BYTE *pbSignature = NULL;

DWORD dwSigLen;

LPTSTR szDescription = TEXT(“Test Data”);

DWORD i;

// Get handle to the default provider.

if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {

    printf("Error %x during CryptAcquireContext!\n", GetLastError());

    goto done;

}

// Fill buffer with test data.

for(i = 0 ; i < BUFFER_SIZE ; i++) {

    pbBuffer[i] = (BYTE)i;

}

// Create hash object.

if(!CryptCreateHash(hProv, CALG_MD5, 0, 0, &hHash)) {

    printf("Error %x during CryptCreateHash!\n", GetLastError());

    goto done;

}

// Hash buffer.

if(!CryptHashData(hHash, pbBuffer, BUFFER_SIZE, 0)) {

    printf("Error %x during CryptHashData!\n", GetLastError());

    goto done;

}

// Determine size of signature and allocate memory.

dwSigLen = 0;

if(!CryptSignHash(hHash, AT_SIGNATURE, TEXT(""), 0, NULL, &dwSigLen)) {

    printf("Error %x during CryptSignHash!\n", GetLastError());

    if(GetLastError()!=NTE_BAD_LEN) goto done;

}

if((pbSignature = malloc(dwSigLen)) == NULL) {

    printf("Out of memory!\n");

    goto done;

}

// Sign hash object.

if(!CryptSignHash(hHash, AT_SIGNATURE, szDescription, 0, pbSignature, &dwSigLen)) {

    printf("Error %x during CryptSignHash!\n", GetLastError());

    goto done;

}

// Store or transmit the signature, test buffer, and description string.

...

done:

// Free memory used to store signature.

if(pbSignature != NULL) free(pbSignature);

// Destroy hash object.

if(hHash != 0) CryptDestroyHash(hHash);

// Release provider handle.

if(hProv != 0) CryptReleaseContext(hProv, 0);

See Also

CryptCreateHash, CryptDestroyHash, CryptHashData, CryptHashSessionKey, CryptVerifySignature


CryptVerifySignature [New - Windows NT] [New - Windows 95, OEM Service Release 2]
CryptVerifySignature

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The CryptVerifySignature function is used to verify a signature against a hash object.

Before calling this function, the CryptCreateHash function must be called to get a handle to a hash object. The CryptHashData and/or CryptHashSessionKey functions are then used to add the data and/or session keys to the hash object.

Once this function has been completed, the only hash function that can be called using the hHash handle is the CryptDestroyHash function.

BOOL CRYPTFUNC CryptVerifySignature(

HCRYPTHASH hHash,
BYTE *pbSignature,
DWORD dwSigLen,
HCRYPTKEY hPubKey,
LPCTSTR sDescription,
DWORD dwFlags
);
Parameters

hHash

[in] A handle to the hash object to verify against.

pbSignature

[in] The address of the signature data to be verified.

dwSigLen

[in] The number of bytes in the pbSignature signature data.

hPubKey

[in] A handle to the public key to use to authenticate the signature. This public key must belong to the key pair that was originally used to create the digital signature.

sDescription

[in] String describing the signed data. This must be exactly the same string that was passed in to the CryptSignHash function when the signature was created. If this string does not match, the signature verification will fail.

When this function is called, some CSPs (not the Microsoft RSA Base Provider) will display this description string to the user, together with an indication of whether the signature verified correctly. This provides the user with the verification results in a way that is completely independent of the application.

dwFlags

[in] The flag values. This parameter is reserved for future use and should always be zero.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.

	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
NTE_BAD_HASH	The hash object specified by the hHash parameter is invalid.
NTE_BAD_KEY	The hPubKey parameter does not contain a handle to a valid public key.
NTE_BAD_SIGNATURE	The signature failed to verify. This could be because the data itself has changed, the description string did not match, or the wrong public key was specified by hPubKey. This error can also be returned if the hashing or signature algorithms do not match the ones used to create the signature.
NTE_BAD_UID	The CSP context that was specified when the hash object was created cannot be found.
NTE_NO_MEMORY	The CSP ran out of memory during the operation.
Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;

#define BUFFER_SIZE 256

BYTE pbBuffer[BUFFER_SIZE];

HCRYPTHASH hHash = 0;

HCRYPTKEY hPubKey = 0;

BYTE *pbSignature = NULL;

DWORD dwSigLen;

LPTSTR szDescription = NULL;

// Get handle to the default provider.

if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {

    printf("Error %x during CryptAcquireContext!\n", GetLastError());

    goto done;

}

// Load ‘pbBuffer’ with ‘BUFFER_SIZE’ bytes of test data. This must

// be the same data that was originally signed.

...

// Point ‘pbSignature’ at the signature created by a previous call

// to CryptSignHash. Set ‘dwSigLen’ to the number of bytes in the

// signature.

...

// Point ‘szDescription’ at some text describing the data being

// signed. This must be the same description text that was originally

// passed to CryptSignHash.

...

// Get public key of the user that created the digital signature

// and import it into the CSP using CryptImportKey. This will return

// a handle to the public key in ‘hPubKey’.

...

// Create hash object.

if(!CryptCreateHash(hProv, CALG_MD5, 0, 0, &hHash)) {

    printf("Error %x during CryptCreateHash!\n", GetLastError());

    goto done;

}

// Hash buffer.

if(!CryptHashData(hHash, pbBuffer, BUFFER_SIZE, 0)) {

    printf("Error %x during CryptHashData!\n", GetLastError());

    goto done;

}

// Validate digital signature.

if(!CryptVerifySignature(hHash, pbSignature, dwSigLen, hPubKey, szDescription, 0)) {

    if(GetLastError() == NTE_BAD_SIGNATURE) {

        printf("Signature failed to validate!\n");

    } else {

        printf("Error %x during CryptSignHash!\n", GetLastError());

    }

} else {

    printf(“Signature validated OK\n”);

}

done:

...

// Release public key.

if(hPubKey != 0) CryptDestroyKey(hPubKey);

// Destroy hash object.

if(hHash != 0) CryptDestroyHash(hHash);

// Release provider handle.

if(hProv != 0) CryptReleaseContext(hProv, 0);

See Also

CryptCreateHash, CryptDestroyHash, CryptHashData, CryptHashSessionKey, CryptSignHash


DdeAbandonTransaction

The DdeAbandonTransaction function abandons the specified asynchronous transaction and releases all resources associated with the transaction.

BOOL DdeAbandonTransaction(

DWORD idInst,	// instance identifier
HCONV hConv,	// handle to conversation
DWORD idTransaction	// transaction identifier
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hConv

Identifies the conversation in which the transaction was initiated. If this parameter is 0L, all transactions are abandoned (that is, the idTransaction parameter is ignored).

idTransaction

Specifies the identifier of the transaction to abandon. If this parameter is 0L, all active transactions in the specified conversation are abandoned.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR
DMLERR_UNFOUND_QUEUE_ID

Remarks

Only a dynamic data exchange (DDE) client application should call DdeAbandonTransaction. If the server application responds to the transaction after the client has called DdeAbandonTransaction, the system discards the transaction results. This function has no effect on synchronous transactions.

See Also

DdeClientTransaction, DdeInitialize, DdeQueryConvInfo


DdeAccessData

The DdeAccessData function provides access to the data in the specified dynamic data exchange (DDE) object. An application must call the DdeUnaccessData function when it has finished accessing the data in the object.

LPBYTE DdeAccessData(

HDDEDATA hData,	// handle to DDE object
LPDWORD pcbDataSize	// pointer to variable that receives data length
);
Parameters

hData

Identifies the DDE object to access.

pcbDataSize

Points to a variable that receives the size, in bytes, of the DDE object identified by the hData parameter. If this parameter is NULL, no size information is returned.

Return Values

If the function succeeds, the return value is a pointer to the first byte of data in the DDE object.

If the function fails, the return value is NULL.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR

Remarks

If the hData parameter has not been passed to a Dynamic Data Exchange Management Library (DDEML) function, an application can use the pointer returned by DdeAccessData for read-write access to the DDE object. If hData has already been passed to a DDEML function, the pointer should be used only for read access to the memory object.

See Also

DdeAddData, DdeCreateDataHandle, DdeFreeDataHandle, DdeUnaccessData


DdeAddData

The DdeAddData function adds data to the specified dynamic data exchange (DDE) object. An application can add data starting at any offset from the beginning of the object. If new data overlaps data already in the object, the new data overwrites the old data in the bytes where the overlap occurs. The contents of locations in the object that have not been written to are undefined.

HDDEDATA DdeAddData(

HDDEDATA hData,	// handle to DDE data object
LPBYTE pSrc,	// pointer to source buffer
DWORD cb,	// length of data
DWORD cbOff	// offset within DDE data object
);
Parameters

hData

Identifies the DDE object that receives additional data.

pSrc

Points to a buffer containing the data to add to the DDE object.

cb

Specifies the length, in bytes, of the data to be added to the DDE object.

cbOff

Specifies an offset, in bytes, from the beginning of the DDE object. The additional data is copied to the object beginning at this offset.

Return Values

If the function succeeds, the return value is a new handle to the DDE object. The new handle is used in all references to the object.

If the function fails, the return value is zero.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_MEMORY_ERROR
DMLERR_NO_ERROR

Remarks

After a data handle has been used as a parameter in another Dynamic Data Exchange Management Library function or has been returned by a DDE callback function, the handle may be used only for read access to the DDE object identified by the handle.

If the amount of memory originally allocated is less than is needed to hold the added data, DdeAddData reallocates a global memory object of the appropriate size.

See Also

DdeAccessData, DdeCreateDataHandle, DdeUnaccessData


DdeCallback

The DdeCallback function is an application-defined callback function that processes dynamic data exchange (DDE) transactions sent to the function in response to Dynamic Data Exchange Management Library (DDEML) calls by other applications.

HDDEDATA CALLBACK DdeCallback(

UINT uType,	// transaction type
UINT uFmt,	// clipboard data format
HCONV hconv,	// handle to the conversation
HSZ hsz1,	// handle to a string
HSZ hsz2,	// handle to a string
HDDEDATA hdata,	// handle to a global memory object
DWORD dwData1,	// transaction-specific data
DWORD dwData2	// transaction-specific data
);
Parameters

uType

Specifies the type of the current transaction. This parameter consists of a combination of transaction class flags and transaction type flags. The following table describes each of the transaction classes and provides a list of the transaction types in each class. For information about a specific transaction type, see the individual description of that type.

Class	Meaning
XCLASS_BOOL	A DDE callback function should return TRUE or FALSE when it finishes processing a transaction that belongs to this class. The XCLASS_BOOL transaction class consists of the following types:
	XTYP_ADVSTART XTYP_CONNECT
XCLASS_DATA	A DDE callback function should return a DDE handle, the CBR_BLOCK return code, or NULL when it finishes processing a transaction that belongs to this class. The XCLASS_DATA transaction class consists of the following types:
	XTYP_ADVREQ XTYP_REQUEST XTYP_WILDCONNECT
XCLASS_FLAGS	A DDE callback function should return DDE_FACK, DDE_FBUSY, or DDE_FNOTPROCESSED when it finishes processing a transaction that belongs to this class. The XCLASS_FLAGS transaction class consists of the following types:
	XTYP_ADVDATA XTYP_EXECUTE XTYP_POKE
XCLASS_NOTIFICATION	The transaction types that belong to this class are for notification purposes only. The return value from the callback function is ignored. The XCLASS_NOTIFICATION transaction class consists of the following types: XTYP_ADVSTOP XTYP_CONNECT_CONFIRM XTYP_DISCONNECT XTYP_ERROR XTYP_MONITOR XTYP_REGISTER XTYP_XACT_COMPLETE XTYP_UNREGISTER
uFmt

Specifies the format in which data is sent or received.

hconv

Identifies the conversation associated with the current transaction.

hsz1

Identifies a string. The meaning of this parameter depends on the type of the current transaction. For the meaning of this parameter, see the description of the transaction type.

hsz2

Identifies a string. The meaning of this parameter depends on the type of the current transaction. For the meaning of this parameter, see the description of the transaction type.

hdata

Identifies DDE data. The meaning of this parameter depends on the type of the current transaction. For the meaning of this parameter, see the description of the transaction type.

dwData1

Specifies transaction-specific data. For the meaning of this parameter, see the description of the transaction type.

dwData2

Specifies transaction-specific data. For the meaning of this parameter, see the description of the transaction type.

Return Values

The return value depends on the transaction class. For more information about the return values, see descriptions of the individual transaction types.

Remarks

The callback function is called asynchronously for transactions that do not involve the creation or termination of conversations. An application that does not frequently accept incoming messages will have reduced DDE performance because the DDEML uses messages to initiate transactions.

An application must register the callback function by specifying a pointer to the function in a call to the DdeInitialize function.

DdeCallback is a placeholder for the application-defined or library-defined function name.

See Also

DdeEnableCallback, DdeInitialize


DdeClientTransaction

The DdeClientTransaction function begins a data transaction between a client and a server. Only a dynamic data exchange (DDE) client application can call this function, and the application can use it only after establishing a conversation with the server.

HDDEDATA DdeClientTransaction(

LPBYTE pData,	// pointer to data to pass to server
DWORD cbData,	// length of data
HCONV hConv,	// handle to conversation
HSZ hszItem,	// handle to item name string
UINT wFmt,	// clipboard data format
UINT wType,	// transaction type
DWORD dwTimeout,	// time-out duration
LPDWORD pdwResult	// pointer to transaction result
);
Parameters

pData

Points to the beginning of the data the client must pass to the server.

Optionally, an application can specify the data handle (HDDEDATA) to pass to the server and in that case the cbData parameter should be set to 0xFFFFFFFF. This parameter is required only if the wType parameter is XTYP_EXECUTE or XTYP_POKE. Otherwise, this parameter should be NULL.

For the optional usage of this parameter, XTYP_POKE transactions where pData is a data handle, the handle must have been created by a previous call to the DdeCreateDataHandle function, employing the same data format specified in the wFmt parameter.

cbData

Specifies the length, in bytes, of the data pointed to by the pData parameter. A value of 0xFFFFFFFF indicates that pData is a data handle that identifies the data being sent.

hConv

Identifies the conversation in which the transaction is to take place.

hszItem

Identifies the data item for which data is being exchanged during the transaction. This handle must have been created by a previous call to the DdeCreateStringHandle function. This parameter is ignored (and should be set to 0L) if the wType parameter is XTYP_EXECUTE.

wFmt

Specifies the standard clipboard format in which the data item is being submitted or requested.

If the transaction specified by the wType parameter does not pass data or is XTYP_EXECUTE, this parameter should be zero.

If the transaction specified by the wType parameter references non-execute DDE data (XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP, XTYP_REQUEST), the wFmt value must be either a valid predefined (CF_) DDE format or a valid registered clipboard format.

wType

Specifies the transaction type. This parameter can be one of the following types:

Type	Meaning
XTYP_ADVSTART	Begins an advise loop. Any number of distinct advise loops can exist within a conversation. An application can alter the advise loop type by combining the XTYP_ADVSTART transaction type with one or more of the following flags:
Flag	Meaning
XTYPF_NODATA	Instructs the server to notify the client of any data changes without actually sending the data. This flag gives the client the option of ignoring the notification or requesting the changed data from the server.
XTYPF_ACKREQ	Instructs the server to wait until the client acknowledges that it received the previous data item before sending the next data item. This flag prevents a fast server from sending data faster than the client can process it.
XTYP_ADVSTOP	Ends an advise loop.
XTYP_EXECUTE	Begins an execute transaction.
XTYP_POKE	Begins a poke transaction.
XTYP_REQUEST	Begins a request transaction.
dwTimeout

Specifies the maximum length of time, in milliseconds, that the client will wait for a response from the server application in a synchronous transaction. This parameter should be TIMEOUT_ASYNC for asynchronous transactions.

pdwResult

Points to a variable that receives the result of the transaction. An application that does not check the result can use NULL for this value. For synchronous transactions, the low-order word of this variable contains any applicable DDE_ flags resulting from the transaction. This provides support for applications dependent on DDE_APPSTATUS bits. It is, however, recommended that applications no longer use these bits because they may not be supported in future versions of the Dynamic Data Exchange Management Library (DDEML). For asynchronous transactions, this variable is filled with a unique transaction identifier for use with the DdeAbandonTransaction function and the XTYP_XACT_COMPLETE transaction.

Return Values

If the function succeeds, the return value is a data handle that identifies the data for successful synchronous transactions in which the client expects data from the server. The return value is nonzero for successful asynchronous transactions and for synchronous transactions in which the client does not expect data. The return value is zero for all unsuccessful transactions.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_ADVACKTIMEOUT
DMLERR_BUSY
DMLERR_DATAACKTIMEOUT
DMLERR_DLL_NOT_INITIALIZED
DMLERR_EXECACKTIMEOUT
DMLERR_INVALIDPARAMETER
DMLERR_MEMORY_ERROR
DMLERR_NO_CONV_ESTABLISHED
DMLERR_NO_ERROR
DMLERR_NOTPROCESSED
DMLERR_POKEACKTIMEOUT
DMLERR_POSTMSG_FAILED
DMLERR_REENTRANCY
DMLERR_SERVER_DIED
DMLERR_UNADVACKTIMEOUT

Remarks

When an application has finished using the data handle returned by DdeClientTransaction, the application should free the handle by calling the DdeFreeDataHandle function.

Transactions can be synchronous or asynchronous. During a synchronous transaction, DdeClientTransaction does not return until the transaction either completes successfully or fails. Synchronous transactions cause a client to enter a modal loop while waiting for various asynchronous events. Because of this, a client application can still respond to user input while waiting on a synchronous transaction, but the application cannot begin a second synchronous transaction because of the activity associated with the first. DdeClientTransaction fails if any instance of the same task has a synchronous transaction already in progress.

During an asynchronous transaction, DdeClientTransaction returns after the transaction has begun, passing a transaction identifier for reference. When the server’s DDE callback function finishes processing an asynchronous transaction, the system sends an XTYP_XACT_COMPLETE transaction to the client. This transaction provides the client with the results of the asynchronous transaction that it initiated by calling DdeClientTransaction. A client application can choose to abandon an asynchronous transaction by calling the DdeAbandonTransaction function.

See Also

DdeAbandonTransaction, DdeAccessData, DdeConnect, DdeConnectList, DdeCreateDataHandle, DdeCreateStringHandle, DdeFreeDataHandle, XTYP_ADVSTART, XTYP_ADVSTOP, XTYP_EXECUTE, XTYP_POKE, XTYP_REQUEST


DdeCmpStringHandles

The DdeCmpStringHandles function compares the values of two string handles. The value of a string handle is not related to the case of the associated string.

int DdeCmpStringHandles(

HSZ hsz1,	// handle to first string
HSZ hsz2	// handle to second string
);
Parameters

hsz1

Identifies the first string.

hsz2

Identifies the second string.

Return Values

The return value can be one of the following values:

Value	Meaning
−1	The value of hsz1 is either 0 or less than the value of hsz2.
0	The values of hsz1 and hsz2 are equal (both can be 0).
1	The value of hsz2 is either 0 or less than the value of hsz1.
Remarks

An application that must do a case-sensitive comparison of two string handles should compare the string handles directly. An application should use DdeCmpStringHandles for all other comparisons to preserve the case-insensitive nature of dynamic data exchange (DDE).

DdeCmpStringHandles cannot be used to sort string handles alphabetically.

See Also

DdeAccessData, DdeCreateStringHandle, DdeFreeStringHandle


DdeConnect

The DdeConnect function establishes a conversation with a server application that supports the specified service name and topic name pair. If more than one such server exists, the system selects only one.

HCONV DdeConnect(

DWORD idInst,	// instance identifier
HSZ hszService,	// handle to service name string
HSZ hszTopic,	// handle to topic name string
PCONVCONTEXT pCC	// pointer to structure with context data
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hszService

Identifies the string that specifies the service name of the server application with which a conversation is to be established. This handle must have been created by a previous call to the DdeCreateStringHandle function. If this parameter is 0L, a conversation is established with any available server.

hszTopic

Identifies the string that specifies the name of the topic on which a conversation is to be established. This handle must have been created by a previous call to DdeCreateStringHandle. If this parameter is 0L, a conversation on any topic supported by the selected server is established.

pCC

Points to the CONVCONTEXT structure that contains conversation context information. If this parameter is NULL, the server receives the default CONVCONTEXT structure during the XTYP_CONNECT or XTYP_WILDCONNECT transaction.

Return Values

If the function succeeds, the return value is the handle to the established conversation.

If the function fails, the return value is 0L.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_CONV_ESTABLISHED
DMLERR_NO_ERROR

Remarks

The client application cannot make assumptions regarding the server selected. If an instance-specific name is specified in the hszService parameter, a conversation is established with only the specified instance. Instance-specific service names are passed to an application’s dynamic data exchange (DDE) callback function during the XTYP_REGISTER and XTYP_UNREGISTER transactions.

All members of the default CONVCONTEXT structure are set to zero except cb, which specifies the size of the structure, and iCodePage, which specifies CP_WINANSI (the default code page) or CP_WINUNICODE, depending on whether the ANSI or Unicode version of the DdeInitialize function was called by the client application.

See Also

CONVCONTEXT, DdeConnectList, DdeCreateStringHandle, DdeDisconnect, DdeDisconnectList, DdeInitialize, XTYP_REGISTER, XTYP_UNREGISTER


DdeConnectList

The DdeConnectList function establishes a conversation with all server applications that support the specified service name and topic name pair. An application can also use this function to obtain a list of conversation handles by passing the function an existing conversation handle. The Dynamic Data Exchange Management Library removes the handles of any terminated conversations from the conversation list. The resulting conversation list contains the handles of all currently established conversations that support the specified service name and topic name.

HCONVLIST DdeConnectList(

DWORD idInst,	// instance identifier
HSZ hszService,	// handle to service name string
HSZ hszTopic,	// handle to topic name string
HCONVLIST hConvList,	// handle to conversation list
PCONVCONTEXT pCC	// pointer to structure with context data
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hszService

Identifies the string that specifies the service name of the server application with which a conversation is to be established. If this parameter is 0L, the system attempts to establish conversations with all available servers that support the specified topic name.

hszTopic

Identifies the string that specifies the name of the topic on which a conversation is to be established. This handle must have been created by a previous call to the DdeCreateStringHandle function. If this parameter is 0L, the system will attempt to establish conversations on all topics supported by the selected server (or servers).

hConvList

Identifies the conversation list to be enumerated. This parameter should be 0L if a new conversation list is to be established.

pCC

Points to the CONVCONTEXT structure that contains conversation-context information. If this parameter is NULL, the server receives the default CONVCONTEXT structure during the XTYP_CONNECT or XTYP_WILDCONNECT transaction.

Return Values

If the function succeeds, the return value is the handle to a new conversation list.

If the function fails, the return value is 0L. The handle to the old conversation list is no longer valid.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALID_PARAMETER
DMLERR_NO_CONV_ESTABLISHED
DMLERR_NO_ERROR
DMLERR_SYS_ERROR

Remarks

An application must free the conversation list handle returned by the DdeConnectList function, regardless of whether any conversation handles within the list are active. To free the handle, an application can call DdeDisconnectList.

All members of the default CONVCONTEXT structure are set to zero except cb, specifying the size of the structure, and iCodePage, specifying CP_WINANSI (the default code page) or CP_WINUNICODE, depending on whether the ANSI or Unicode version of the DdeInitialize function was called by the client application.

See Also

CONVCONTEXT, DdeConnect, DdeCreateStringHandle, DdeDisconnect, DdeDisconnectList, DdeInitialize, DdeQueryNextServer


DdeCreateDataHandle

The DdeCreateDataHandle function creates a dynamic data exchange (DDE) object and fills the object with data from the specified buffer. A DDE application uses this function during transactions that involve passing data to the partner application.

HDDEDATA DdeCreateDataHandle(

DWORD idInst,	// instance identifier
LPBYTE pSrc,	// pointer to source buffer
DWORD cb,	// length of DDE object
DWORD cbOff,	// offset from beginning of source buffer
HSZ hszItem,	// handle to item name string
UINT wFmt,	// clipboard data format
UINT afCmd	// creation flags
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

pSrc

Points to a buffer that contains data to be copied to the DDE object. If this parameter is NULL, no data is copied to the object.

cb

Specifies the amount of memory, in bytes, to copy from the buffer pointed to by pSrc. If this parameter is zero, the pSrc parameter is ignored.

cbOff

Specifies an offset, in bytes, from the beginning of the buffer pointed to by the pSrc parameter. The data beginning at this offset is copied from the buffer to the DDE object.

hszItem

Identifies the string that specifies the data item corresponding to the DDE object. This handle must have been created by a previous call to the DdeCreateStringHandle function. If the data handle is to be used in an XTYP_EXECUTE transaction, this parameter must be 0L.

wFmt

Specifies the standard clipboard format of the data.

afCmd

Specifies the creation flags. This parameter can be HDATA_APPOWNED, which specifies that the server application calling the DdeCreateDataHandle function owns the data handle this function creates. This flag enables the application to share the data handle with other Dynamic Data Exchange Management Library (DDEML) applications rather than creating a separate handle to pass to each application. If this flag is specified, the application must eventually free the shared memory object associated with the handle by using the DdeFreeDataHandle function. If this flag is not specified, the handle becomes invalid in the application that created the handle after the data handle is returned by the application’s DDE callback function or is used as a parameter in another DDEML function.

Return Values

If the function succeeds, the return value is a data handle.

If the function fails, the return value is 0L.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_MEMORY_ERROR
DMLERR_NO_ERROR

Remarks

Any unfilled locations in the DDE object are undefined.

After a data handle has been used as a parameter in another DDEML function or has been returned by a DDE callback function, the handle may be used only for read access to the DDE object identified by the handle.

See Also

DdeAccessData, DdeCreateStringHandle, DdeFreeDataHandle, DdeGetData, DdeInitialize


DdeCreateStringHandle

The DdeCreateStringHandle function creates a handle that identifies the string pointed to by the psz parameter. A dynamic data exchange (DDE) client or server application can pass the string handle as a parameter to other Dynamic Data Exchange Management Library (DDEML) functions.

HSZ DdeCreateStringHandle(

DWORD idInst,	// instance identifier
LPTSTR psz,	// pointer to null-terminated string
int iCodePage	// code page identifier
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

psz

Points to a buffer that contains the null-terminated string for which a handle is to be created. This string may be up to 255 characters. The reason for this limit is that DDEML string management functions are implemented using global atoms.

iCodePage

Specifies the code page used to render the string. This value should be either CP_WINANSI (the default code page) or CP_WINUNICODE, depending on whether the ANSI or Unicode version of DdeInitialize was called by the client application.

Return Values

If the function succeeds, the return value is a string handle.

If the function fails, the return value is 0L.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR
DMLERR_SYS_ERROR

Remarks

The value of a string handle is not related to the case of the string it identifies.

When an application either creates a string handle or receives one in the callback function and then uses the DdeKeepStringHandle function to keep it, the application must free that string handle when it is no longer needed.

An instance-specific string handle cannot be mapped from string handle to string and back to string handle. This is shown in the following example, in which the DdeQueryString function creates a string from a string handle and DdeCreateStringHandle creates a string handle from that string, but the two handles are not the same:

DWORD idInst;

DWORD cb;

HSZ hszInst, hszNew;

PSZ pszInst;

DdeQueryString(idInst, hszInst, pszInst, cb, CP_WINANSI);

hszNew = DdeCreateStringHandle(idInst, pszInst, CP_WINANSI);

// hszNew != hszInst !

See Also

DdeAccessData, DdeCmpStringHandles, DdeFreeStringHandle, DdeInitialize, DdeKeepStringHandle, DdeQueryString


DdeDisconnect

The DdeDisconnect function terminates a conversation started by either the DdeConnect or DdeConnectList function and invalidates the specified conversation handle.

BOOL DdeDisconnect(

HCONV hConv	// handle to conversation
);
Parameters

hConv

Identifies the active conversation to be terminated.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_NO_CONV_ESTABLISHED
DMLERR_NO_ERROR

Remarks

Any incomplete transactions started before calling DdeDisconnect are immediately abandoned. The XTYP_DISCONNECT transaction is sent to the dynamic data exchange (DDE) callback function of the partner in the conversation. Generally, only client applications must terminate conversations.

See Also

DdeConnect, DdeConnectList, DdeDisconnectList, XTYP_DISCONNECT


DdeDisconnectList

The DdeDisconnectList function destroys the specified conversation list and terminates all conversations associated with the list.

BOOL DdeDisconnectList(

HCONVLIST hConvList	// handle to conversation list
);
Parameters

hConvList

Identifies the conversation list. This handle must have been created by a previous call to the DdeConnectList function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR

Remarks

An application can use the DdeDisconnect function to terminate individual conversations in the list.

See Also

DdeConnect, DdeConnectList, DdeDisconnect


DdeEnableCallback

The DdeEnableCallback function enables or disables transactions for a specific conversation or for all conversations currently established by the calling application.

After disabling transactions for a conversation, the operating system places the transactions for that conversation in a transaction queue associated with the application. The application should reenable the conversation as soon as possible to avoid losing queued transactions.

BOOL DdeEnableCallback(

DWORD idInst,	// instance identifier
HCONV hConv,	// handle to conversation
UINT wCmd	// enable or disable function code
);
Parameters

idInst

Specifies the application-instance identifier obtained by a previous call to the DdeInitialize function.

hConv

Identifies the conversation to enable or disable. If this parameter is NULL, the function affects all conversations.

wCmd

Specifies the function code. This parameter can be one of the following values:

Value	Meaning
EC_ENABLEALL	Enables all transactions for the specified conversation.
EC_ENABLEONE	Enables one transaction for the specified conversation.
EC_DISABLE	Disables all blockable transactions for the specified conversation. A server application can disable the following transactions: XTYP_ADVSTART XTYP_ADVSTOP XTYP_EXECUTE XTYP_POKE XTYP_REQUEST A client application can disable the following transactions: XTYP_ADVDATA XTYP_XACT_COMPLETE
EC_QUERYWAITING	Determines whether any transactions are in the queue for the specified conversation.
Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

If the wCmd parameter is EC_QUERYWAITING, and the application transaction queue contains one or more unprocessed transactions that are not being processed, the return value is TRUE; otherwise, it is FALSE.

Errors

Use the DdeGetLastError function to retrieve the error code, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_NO_ERROR
DMLERR_INVALIDPARAMETER

Remarks

An application can disable transactions for a specific conversation by returning the CBR_BLOCK return code from its dynamic data exchange (DDE) callback function. When you reenable the conversation by using the DdeEnableCallback function, the operating system generates the same transaction that was in process when the conversation was disabled.

Using the EC_QUERYWAITING flag does not change the enable state of the conversation and does not cause transactions to be issued within the context of the call to DdeEnableCallback.

If DdeEnableCallback is called with EC_QUERYWAITING and the return value is TRUE, an application should try to quickly allow message processing, return from its callback, or enable callbacks. Such a result does not guarantee that subsequent callbacks will be made. Calling DdeEnableCallback with EC_QUERYWAITING lets an application with blocked callbacks determine whether there are any transactions pending on the blocked conversation. Of course, even if such a call returns false, an application should always process messages in a timely manner.

See Also

DdeConnect, DdeConnectList, DdeDisconnect, DdeInitialize


DdeFreeDataHandle

The DdeFreeDataHandle function frees a dynamic data exchange (DDE) object and deletes the data handle associated with the object.

BOOL DdeFreeDataHandle(

HDDEDATA hData	// handle to DDE object
);
Parameters

hData

Identifies the DDE object to be freed. This handle must have been created by a previous call to the DdeCreateDataHandle function or returned by the DdeClientTransaction function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR

Remarks

An application must call DdeFreeDataHandle under the following circumstances:

•	To free a DDE object that the application allocated by calling the DdeCreateDataHandle function if the object’s data handle was never passed by the application to another Dynamic Data Exchange Management Library (DDEML) function

•	To free a DDE object that the application allocated by specifying the HDATA_APPOWNED flag in a call to DdeCreateDataHandle

•	To free a DDE object whose handle the application received from the DdeClientTransaction function

The system automatically frees an unowned object when its handle is returned by a DDE callback function or is used as a parameter in a DDEML function.

See Also

DdeAccessData, DdeCreateDataHandle, DdeClientTransaction


DdeFreeStringHandle

The DdeFreeStringHandle function frees a string handle in the calling application.

BOOL DdeFreeStringHandle(

DWORD idInst,	// instance identifier
HSZ hsz	// handle to string
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hsz

Identifies the string handle to be freed. This handle must have been created by a previous call to the DdeCreateStringHandle function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

An application can free string handles it creates with DdeCreateStringHandle but should not free those that the system passed to the application’s dynamic data exchange (DDE) callback function or those returned in the CONVINFO structure by the DdeQueryConvInfo function.

See Also

CONVINFO, DdeCmpStringHandles, DdeCreateStringHandle, DdeInitialize, DdeKeepStringHandle, DdeQueryConvInfo, DdeQueryString


DdeGetData

The DdeGetData function copies data from the specified dynamic data exchange (DDE) object to the specified local buffer.

DWORD DdeGetData(

HDDEDATA hData,	// handle to DDE  object
LPBYTE pDst,	// pointer to destination buffer
DWORD cbMax,	// amount of data to copy
DWORD cbOff	// offset to beginning of data
);
Parameters

hData

Identifies the DDE object that contains the data to copy.

pDst

Points to the buffer that receives the data. If this parameter is NULL, the DdeGetData function returns the amount of data, in bytes, that would be copied to the buffer.

cbMax

Specifies the maximum amount of data, in bytes, to copy to the buffer pointed to by the pDst parameter. Typically, this parameter specifies the length of the buffer pointed to by pDst.

cbOff

Specifies an offset within the DDE object. Data is copied from the object beginning at this offset.

Return Values

If the pDst parameter points to a buffer, the return value is the size, in bytes, of the memory object associated with the data handle or the size specified in the cbMax parameter, whichever is lower.

If the pDst parameter is NULL, the return value is the size, in bytes, of the memory object associated with the data handle.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR

See Also

DdeAccessData, DdeCreateDataHandle, DdeFreeDataHandle


DdeGetLastError

The DdeGetLastError function returns the most recent error code set by the failure of a Dynamic Data Exchange Management Library (DDEML) function and resets the error code to DMLERR_NO_ERROR.

UINT DdeGetLastError(

DWORD idInst	// instance identifier
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

Return Values

If the function succeeds, the return value is the last error code. Following are the possible DDEML error codes:

Value	Meaning
DMLERR_ADVACKTIMEOUT	A request for a synchronous advise transaction has timed out.
DMLERR_BUSY	The response to the transaction caused the DDE_FBUSY flag to be set.
DMLERR_DATAACKTIMEOUT	A request for a synchronous data transaction has timed out.
DMLERR_DLL_NOT_INITIALIZED	A DDEML function was called without first calling the DdeInitialize function, or an invalid instance identifier was passed to a DDEML function.
DMLERR_DLL_USAGE	An application initialized as APPCLASS_MONITOR has attempted to perform a dynamic data exchange (DDE) transaction, or an application initialized as APPCMD_CLIENTONLY has attempted to perform server transactions.
DMLERR_EXECACKTIMEOUT	A request for a synchronous execute transaction has timed out.
DMLERR_INVALIDPARAMETER	A parameter failed to be validated by the DDEML. Some of the possible causes follow:
	The application used a data handle initialized with a different item name handle than was required by the transaction. The application used a data handle that was initialized with a different clipboard data format than was required by the transaction. The application used a client-side conversation handle with a server-side function or vice versa. The application used a freed data handle or string handle. More than one instance of the application used the same object.
DMLERR_LOW_MEMORY	A DDEML application has created a prolonged race condition (in which the server application outruns the client), causing large amounts of memory to be consumed.
DMLERR_MEMORY_ERROR	A memory allocation has failed.
DMLERR_NO_CONV_ESTABLISHED	A client’s attempt to establish a conversation has failed.
DMLERR_NOTPROCESSED	A transaction has failed.
DMLERR_POKEACKTIMEOUT	A request for a synchronous poke transaction has timed out.
DMLERR_POSTMSG_FAILED	An internal call to the PostMessage function has failed.
DMLERR_REENTRANCY	An application instance with a synchronous transaction already in progress attempted to initiate another synchronous transaction, or the DdeEnableCallback function was called from within a DDEML callback function.
DMLERR_SERVER_DIED	A server-side transaction was attempted on a conversation terminated by the client, or the server terminated before completing a transaction.
DMLERR_SYS_ERROR	An internal error has occurred in the DDEML.
DMLERR_UNADVACKTIMEOUT	A request to end an advise transaction has timed out.
DMLERR_UNFOUND_QUEUE_ID	An invalid transaction identifier was passed to a DDEML function. Once the application has returned from an XTYP_XACT_COMPLETE callback, the transaction identifier for that callback function  is no longer valid.
See Also

DdeEnableCallback, DdeInitialize, PostMessage


DdeImpersonateClient

The DdeImpersonateClient function impersonates a dynamic data exchange (DDE) client application in a DDE client conversation.

BOOL DdeImpersonateClient(

HCONV hConv	// handle to DDE conversation
);
Parameters

hConv

Identifies the DDE client conversation to be impersonated.

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.

Remarks

Impersonation is the ability of a process to take on the security attributes of another process. When a client in a DDE conversation requests information from a DDE server, the server impersonates the client. When the server requests access to an object, the system verifies the access against the client’s security attributes.

When the impersonation is complete, the server normally calls the RevertToSelf function.

See Also

ImpersonateNamedPipeClient, RevertToSelf


DdeInitialize

The DdeInitialize function registers an application with the Dynamic Data Exchange Management Library (DDEML). An application must call this function before calling any other DDEML function.

UINT DdeInitialize(

LPDWORD pidInst,	// pointer to instance identifier
PFNCALLBACK pfnCallback,	// pointer to callback function
DWORD afCmd,	// set of command and filter flags
DWORD ulRes	// reserved
);
Parameters

pidInst

Points to the application instance identifier. At initialization, this parameter should point to 0. If the function succeeds, this parameter points to the instance identifier for the application. This value should be passed as the idInst parameter in all other DDEML functions that require it. If an application uses multiple instances of the DDEML dynamic-link library (DLL), the application should provide a different callback function for each instance.

If pidInst points to a nonzero value, reinitialization of the DDEML is implied. In this case, pidInst must point to a valid application-instance identifier.

pfnCallback

Points to the application-defined dynamic data exchange (DDE) callback function. This function processes DDE transactions sent by the system. For more information, see the DdeCallback callback function.

afCmd

Specifies a set of APPCMD_, CBF_, and MF_ flags. The APPCMD_ flags provide special instructions to DdeInitialize. The CBF_ flags specify filters that prevent specific types of transactions from reaching the callback function. The MF_ flags specify the types of DDE activity that a DDE monitoring application monitors. Using these flags enhances the performance of a DDE application by eliminating unnecessary calls to the callback function.

This parameter can be a combination of the following filter flags:

Flag	Meaning
APPCLASS_MONITOR	Makes it possible for the application to monitor DDE activity in the system. This flag is for use by DDE monitoring applications. The application specifies the types of DDE activity to monitor by combining one or more monitor flags with the APPCLASS_MONITOR flag. For details, see the following Remarks section.
APPCLASS_STANDARD	Registers the application as a standard (nonmonitoring) DDEML application.
APPCMD_CLIENTONLY	Prevents the application from becoming a server in a DDE conversation. The application can only be a client. This flag reduces consumption of resources by the DDEML. It includes the functionality of the CBF_FAIL_ALLSVRXACTIONS flag.
APPCMD_FILTERINITS	Prevents the DDEML from sending XTYP_CONNECT and XTYP_WILDCONNECT transactions to the application until the application has created its string handles and registered its service names or has turned off filtering by a subsequent call to the DdeNameService or DdeInitialize function. This flag is always in effect when an application calls DdeInitialize for the first time, regardless of whether the application specifies the flag. On subsequent calls to DdeInitialize, not specifying this flag turns off the application’s service-name filters, but specifying it turns on the application’s service name filters.
CBF_FAIL_ALLSVRXACTIONS	Prevents the callback function from receiving server transactions. The system returns DDE_FNOTPROCESSED to each client that sends a transaction to this application. This flag is equivalent to combining all CBF_FAIL_ flags.
CBF_FAIL_ADVISES	Prevents the callback function from receiving XTYP_ADVSTART and XTYP_ADVSTOP transactions. The system returns DDE_FNOTPROCESSED to each client that sends an XTYP_ADVSTART or XTYP_ADVSTOP transaction to the server.
CBF_FAIL_CONNECTIONS	Prevents the callback function from receiving XTYP_CONNECT and XTYP_WILDCONNECT transactions.
CBF_FAIL_EXECUTES	Prevents the callback function from receiving XTYP_EXECUTE transactions. The system returns DDE_FNOTPROCESSED to a client that sends an XTYP_EXECUTE transaction to the server.
CBF_FAIL_POKES	Prevents the callback function from receiving XTYP_POKE transactions. The system returns DDE_FNOTPROCESSED to a client that sends an XTYP_POKE transaction to the server.
CBF_FAIL_REQUESTS	Prevents the callback function from receiving XTYP_REQUEST transactions. The system returns DDE_FNOTPROCESSED to a client that sends an XTYP_REQUEST transaction to the server.
CBF_FAIL_SELFCONNECTIONS	Prevents the callback function from receiving XTYP_CONNECT transactions from the application’s own instance. This flag prevents an application from establishing a DDE conversation with its own instance. An application should use this flag if it needs to communicate with other instances of itself but not with itself.
CBF_SKIP_ALLNOTIFICATIONS	Prevents the callback function from receiving any notifications. This flag is equivalent to combining all CBF_SKIP_ flags.
CBF_SKIP_CONNECT_CONFIRMS	Prevents the callback function from receiving XTYP_CONNECT_CONFIRM notifications.
CBF_SKIP_DISCONNECTS	Prevents the callback function from receiving XTYP_DISCONNECT notifications.
CBF_SKIP_REGISTRATIONS	Prevents the callback function from receiving XTYP_REGISTER notifications.
CBF_SKIP_UNREGISTRATIONS	Prevents the callback function from receiving XTYP_UNREGISTER notifications.
MF_CALLBACKS	Notifies the callback function whenever a transaction is sent to any DDE callback function in the system.
MF_CONV	Notifies the callback function whenever a conversation is established or terminated.
MF_ERRORS	Notifies the callback function whenever a DDE error occurs.
MF_HSZ_INFO	Notifies the callback function whenever a DDE application creates, frees, or increments the usage count of a string handle or whenever a string handle is freed as a result of a call to the DdeUninitialize function.
MF_LINKS	Notifies the callback function whenever an advise loop is started or ended.
MF_POSTMSGS	Notifies the callback function whenever the system or an application posts a DDE message.
MF_SENDMSGS	Notifies the callback function whenever the system or an application sends a DDE message.
ulRes

Reserved; must be set to zero.

Return Values

If the function succeeds, the return value is DMLERR_NO_ERROR.

If the function fails, the return value is one of the following values:

DMLERR_DLL_USAGE
DMLERR_INVALIDPARAMETER
DMLERR_SYS_ERROR

Remarks

An application that uses multiple instances of the DDEML must not pass DDEML objects between instances.

A DDE monitoring application should not attempt to perform DDE operations (establish conversations, issue transactions, and so on) within the context of the same application instance.

A synchronous transaction fails with a DMLERR_REENTRANCY error if any instance of the same task has a synchronous transaction already in progress.

The CBF_FAIL_ALLSVRACTIONS flag causes the DDEML to filter all server transactions and can be changed by a subsequent call to DdeInitialize. The APPCMD_CLIENTONLY flag prevents the DDEML from creating key resources for the server and cannot be changed by a subsequent call to DdeInitialize.

There is an ANSI version and a Unicode version of DdeInitialize. The version called determines the type of the window procedures used to control DDE conversations (ANSI or Unicode), and the default value for the iCodePage member of the CONVCONTXT structure (CP_WINANSI or CP_WINUNICODE).

See Also

DdeClientTransaction, DdeConnect, DdeCreateDataHandle, DdeEnableCallback, DdeNameService, DdePostAdvise, DdeUninitialize XTYP_ADVSTART, XTYP_ADVSTOP, XTYP_CONNECT, XTYP_CONNECT_CONFIRM, XTYP_DISCONNECT, XTYP_EXECUTE, XTYP_POKE, XTYP_REGISTER, XTYP_REQUEST, XTYP_WILDCONNECT


DdeKeepStringHandle

The DdeKeepStringHandle function increments the usage count associated with the specified handle. This function enables an application to save a string handle passed to the application’s dynamic data exchange (DDE) callback function. Otherwise, a string handle passed to the callback function is deleted when the callback function returns. This function should also be used to keep a copy of a string handle referenced by the CONVINFO structure returned by the DdeQueryConvInfo function.

BOOL DdeKeepStringHandle(

DWORD idInst,	// instance identifier
HSZ hsz	// handle to string
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hsz

Identifies the string handle to be saved.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

CONVINFO, DdeCreateStringHandle, DdeFreeStringHandle, DdeInitialize, DdeQueryConvInfo, DdeQueryString


DdeNameService

The DdeNameService function registers or unregisters the service names a dynamic data exchange (DDE) server supports. This function causes the system to send XTYP_REGISTER or XTYP_UNREGISTER transactions to other running Dynamic Data Exchange Management Library (DDEML) client applications.

A server application should call this function to register each service name that it supports and to unregister names it previously registered but no longer supports. A server should also call this function to unregister its service names just before terminating.

HDDEDATA DdeNameService(

DWORD idInst,	// instance identifier
HSZ hsz1,	// handle to service name string
HSZ hsz2,	// reserved
UINT afCmd	// service name flags
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hsz1

Identifies the string that specifies the service name the server is registering or unregistering. An application that is unregistering all of its service names should set this parameter to 0L.

hsz2

Reserved; should be set to 0L.

afCmd

Specifies the service name flags. This parameter can be one of the following flags:

Flag	Meaning
DNS_REGISTER	Registers the error code service name.
DNS_UNREGISTER	Unregisters the error code service name. If the hsz1 parameter is 0L, all service names registered by the server will be unregistered.
DNS_FILTERON	Turns on service name initiation filtering. The filter prevents a server from receiving XTYP_CONNECT transactions for service names it has not registered. This is the default setting for this filter.
	If a server application does not register any service names, the application cannot receive XTYP_WILDCONNECT transactions.
DNS_FILTEROFF	Turns off service name initiation filtering. If this flag is specified, the server receives an XTYP_CONNECT transaction whenever another DDE application calls the DdeConnect function, regardless of the service name.
Return Values

If the funcion succeeds, it returns a nonzero value. That value is not a true HDDEDATA value, merely a Boolean indicator of success. The function is typed HDDEDATA to allow for possible future expansion of the function and a more sophisticated return value.

If the function fails, the return value is 0L.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_DLL_USAGE
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR

Remarks

The service name identified by the hsz1 parameter should be a base name (that is, the name should contain no instance-specific information). The system generates an instance-specific name and sends it along with the base name during the XTYP_REGISTER and XTYP_UNREGISTER transactions. The receiving applications can then connect to the specific application instance.

See Also

DdeConnect, DdeConnectList, DdeInitialize, XTYP_REGISTER, XTYP_UNREGISTER


DdePostAdvise

The DdePostAdvise function causes the system to send an XTYP_ADVREQ transaction to the calling (server) application’s dynamic data exchange (DDE) callback function for each client with an active advise loop on the specified topic and item. A server application should call this function whenever the data associated with the topic name or item name pair changes.

BOOL DdePostAdvise(

DWORD idInst,	// instance identifier
HSZ hszTopic,	// handle to topic name string
HSZ hszItem	// handle to item name string
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hszTopic

Identifies a string that specifies the topic name. To send notifications for all topics with active advise loops, an application can set this parameter to 0L.

hszItem

Identifies a string that specifies the item name. To send notifications for all items with active advise loops, an application can set this parameter to 0L.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_DLL_USAGE
DMLERR_NO_ERROR

Remarks

A server that has nonenumerable topics or items should set the hszTopic and hszItem parameters to NULL so that the system generates transactions for all active advise loops. The server’s DDE callback function returns NULL for any advise loops that must not be updated.

If a server calls DdePostAdvise with a topic, item, and format name set that includes the set currently being handled in an XTYP_ADVREQ callback, a stack overflow may result.

See Also

DdeInitialize, XTYP_ADVREQ


DdeQueryConvInfo

The DdeQueryConvInfo function obtains information about a dynamic data exchange (DDE) transaction and about the conversation in which the transaction takes place.

UINT DdeQueryConvInfo(

HCONV hConv,	// handle to conversation
DWORD idTransaction,	// transaction identifier
PCONVINFO pConvInfo	// pointer to structure with conversation data
);
Parameters

hConv

Identifies the conversation.

idTransaction

Specifies the transaction. For asynchronous transactions, this parameter should be a transaction identifier returned by the DdeClientTransaction function. For synchronous transactions, this parameter should be QID_SYNC.

pConvInfo

Points to the CONVINFO structure that receives information about the transaction and conversation. The cb member of the CONVINFO structure must specify the length of the buffer allocated for the structure.

Return Values

If the function succeeds, the return value is the number of bytes copied into the CONVINFO structure.

If the function fails, the return value is FALSE.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_NO_CONV_ESTABLISHED
DMLERR_NO_ERROR
DMLERR_UNFOUND_QUEUE_ID

Remarks

An application should not free a string handle referenced by the CONVINFO structure. If an application must use one of these string handles, it should call the DdeKeepStringHandle function to create a copy of the handle.

If the idTransaction parameter is set to QID_SYNC, the hUser member of the CONVINFO structure is associated with the conversation and can be used to hold data associated with the conversation. If idTransaction is the identifier of an asynchronous transaction, the hUser member is associated only with the current transaction and is valid only for the duration of the transaction.

See Also

CONVINFO, DdeClientTransaction, DdeConnect, DdeConnectList, DdeKeepStringHandle, DdeQueryNextServer


DdeQueryNextServer

The DdeQueryNextServer function obtains the next conversation handle in the specified conversation list.

HCONV DdeQueryNextServer(

HCONVLIST hConvList,	// handle to conversation list
HCONV hConvPrev	// previous conversation handle
);
Parameters

hConvList

Identifies the conversation list. This handle must have been created by a previous call to the DdeConnectList function.

hConvPrev

Identifies the conversation handle previously returned by this function. If this parameter is 0L, the function returns the first conversation handle in the list.

Return Values

If the list contains any more conversation handles, the return value is the next conversation handle in the list; otherwise, it is 0L.

See Also

DdeConnectList, DdeDisconnectList


DdeQueryString

The DdeQueryString function copies text associated with a string handle into a buffer.

DWORD DdeQueryString(

DWORD idInst,	// instance identifier
HSZ hsz,	// handle to string
LPTSTR psz,	// pointer to destination buffer
DWORD cchMax,	// length of buffer
int iCodePage	// code page identifier
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hsz

Identifies the string to copy. This handle must have been created by a previous call to the DdeCreateStringHandle function.

psz

Points to a buffer that receives the string. To obtain the length of the string, this parameter should be set to NULL.

cchMax

Specifies the length, in characters, of the buffer pointed to by the psz parameter. If the string is longer than (cchMax − 1), it will be truncated. If the psz parameter is set to NULL, this parameter is ignored.

iCodePage

Specifies the code page used to render the string. This value should be either CP_WINANSI or CP_WINUNICODE.

Return Values

If the psz parameter specified a valid pointer, the return value is the length, in characters, of the returned text (not including the terminating null character). If the psz parameter specified a NULL pointer, the return value is the length of the text associated with the hsz parameter (not including the terminating null character). If an error occurs, the return value is 0L.

Remarks

The string returned in the buffer is always null-terminated. If the string is longer than (cchMax − 1), only the first (cchMax − 1) characters of the string are copied.

If the psz parameter is NULL, the DdeQueryString function obtains the length, in bytes, of the string associated with the string handle. The length does not include the terminating null character.

See Also

DdeCmpStringHandles, DdeCreateStringHandle, DdeFreeStringHandle, DdeInitialize


DdeReconnect

The DdeReconnect function allows a client Dynamic Data Exchange Management Library (DDEML) application to attempt to reestablish a conversation with a service that has terminated a conversation with the client. When the conversation is reestablished, the DDEML attempts to reestablish any preexisting advise loops.

HCONV DdeReconnect(

HCONV hConv	// handle to conversation to reestablish
);
Parameters

hConv

Identifies the conversation to be reestablished. A client must have obtained the conversation handle by a previous call to the DdeConnect function or from an XTYP_DISCONNECT transaction.

Return Values

If the function succeeds, the return value is the handle to the reestablished conversation.

If the function fails, the return value is 0L.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_CONV_ESTABLISHED
DMLERR_NO_ERROR

See Also

DdeConnect, DdeDisconnect


DdeSetQualityOfService

The DdeSetQualityOfService function specifies the quality of service a raw DDE application desires for future DDE conversations it initiates. The specified quality of service applies to any conversations started while those settings are in place. A DDE conversation’s quality of service lasts for the duration of the conversation; calls to the DdeSetQualityOfService function during a given conversation do not affect that conversation’s quality of service.

BOOL DdeSetQualityOfService(

HWND hwndClient,	// handle to DDE client window that will start DDE conversations
CONST SECURITY_QUALITY_OF_SERVICE *pqosNew,	// desired quality of service
PSECURITY_QUALITY_OF_SERVICE pqosPrev	// prior quality of service
);
Parameters

hwndClient

Identifies the DDE client window that specifies the source of WM_DDE_INITIATE messages a client will send to start DDE conversations.

pqosNew

Points to a SECURITY_QUALITY_OF_SERVICE structure for the desired quality of service values.

pqosPrev

Points to a SECURITY_QUALITY_OF_SERVICE structure that the function will fill with the previous quality of service values associated with the window identified by hwndClient.

This parameter is optional. If an application has no interest in hwndClient’s previous qos values, it should set pqosPrev to NULL.

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.

Remarks

If a quality of service has not been specified for a given client window, hwndClient, prior to sending a WM_DDE_INITIATE with the wParam set to hwndClient, the system uses the following default quality of service values for the client window:

{

   Length = sizeof(SECURITY_QUALITY_OF_SERVICE);

   ImpersonationLevel = SecurityImpersonation;

   ContextTrackingMode = SECURITY_STATIC_TRACKING;

   EffectiveOnly = TRUE;

}

Use the DdeSetQualityOfService function to associate a different quality of service with the client window. Once you change the quality of service, the new settings affect any subsequent conversations that are started. Once an application starts a DDE conversation using a particular quality of service value, it must terminate the conversation and restart the conversation in order to have a different value take effect.

See Also

SECURITY_QUALITY_OF_SERVICE, WM_DDE_INITIATE


DdeSetUserHandle

The DdeSetUserHandle function associates an application-defined 32-bit value with a conversation handle or a transaction identifier. This is useful for simplifying the processing of asynchronous transactions. An application can use the DdeQueryConvInfo function to retrieve this value.

BOOL DdeSetUserHandle(

HCONV hConv,	// handle to conversation
DWORD id,	// transaction identifier
DWORD hUser	// handle to application-defined value
);
Parameters

hConv

Identifies the conversation.

id

Specifies the transaction identifier to associate with the value specified by the hUser parameter. An application should set this parameter to QID_SYNC to associate hUser with the conversation identified by the hConv parameter.

hUser

Identifies the value to associate with the conversation handle.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR
DMLERR_UNFOUND_QUEUE_ID

See Also

DdeQueryConvInfo


DdeUnaccessData

The DdeUnaccessData function unaccesses a dynamic data exchange (DDE) object. An application must call this function after it has finished accessing the object.

BOOL DdeUnaccessData(

HDDEDATA hData	// handle to DDE object
);
Parameters

hData

Identifies the DDE object.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Errors

The DdeGetLastError function can be used to get the error code, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR

See Also

DdeAccessData, DdeAddData, DdeCreateDataHandle, DdeFreeDataHandle


DdeUninitialize

The DdeUninitialize function frees all Dynamic Data Exchange Management Library (DDEML) resources associated with the calling application.

BOOL DdeUninitialize(

DWORD idInst	// instance identifier
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

DdeUninitialize terminates any conversations currently open for the application.

See Also

DdeDisconnect, DdeDisconnectList, DdeInitialize


DebugActiveProcess

The DebugActiveProcess function allows a debugger to attach to an active process and then debug it.

BOOL DebugActiveProcess(

DWORD dwProcessId	// process to be debugged
);
Parameters

dwProcessId

Specifies the identifier for the process to be debugged. The debugger gets debugging access to the process as if it created the process with the DEBUG_ONLY_THIS_PROCESS flag.

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.

Remarks

The debugger must have appropriate access to the target process; it must be able to open the process for PROCESS_ALL_ACCESS access. In the Win32 application programming interface (API) for Windows 95, this is always true if the process identifier is valid. However, in the Win32 API for Windows NT, DebugActiveProcess can fail if the target process was created with a security descriptor that denies the debugger appropriate access.

After the system checks the process identifier and determines that a valid debugging attachment is being made, the function returns TRUE. The debugger is then expected to wait for debugging events by using the WaitForDebugEvent function. The system suspends all threads in the process and sends the debugger events representing the current state of the process.

The system sends the debugger a single CREATE_PROCESS_DEBUG_EVENT debugging event representing the process specified by the dwProcessId parameter. The lpStartAddress member of the CREATE_PROCESS_DEBUG_INFO structure is NULL.

For each thread currently part of the process, the system sends a CREATE_THREAD_DEBUG_EVENT debugging event. The lpStartAddress member of the CREATE_THREAD_DEBUG_INFO structure is NULL.

For each dynamic-link library (DLL) currently loaded into the address space of the target process, the system sends a LOAD_DLL_DEBUG_EVENT debugging event. The system arranges for the first thread in the process to execute a breakpoint instruction after it resumes. Continuing this thread causes it to return to whatever it was doing before the debugger was attached.

After all of this has been done, the system resumes all threads in the process. When the first thread in the process resumes, it executes a breakpoint instruction that causes an EXCEPTION_DEBUG_EVENT debugging event to be sent to the debugger. All future debugging events are sent to the debugger by using the normal mechanism and rules.

See Also

CreateProcess, CREATE_PROCESS_DEBUG_INFO, CREATE_THREAD_DEBUG_INFO, WaitForDebugEvent


DebugBreak

The DebugBreak function causes a breakpoint exception to occur in the current process so that the calling thread can signal the debugger and force it to take some action. If the process is not being debugged, the search logic of a standard exception handler is used. In most cases, this causes the calling process to terminate because of an unhandled breakpoint exception.

VOID DebugBreak(VOID)

Parameters

This function has no parameters.

Return Values

This function does not return a value.

See Also

DebugActiveProcess


DebugProc

The DebugProc hook procedure is an application-defined or library-defined callback function that Windows calls before calling the hook procedures associated with any other type of hook. The system passes information about the hook to be called to the DebugProc hook procedure, which examines the information and determines whether to allow the hook to be called.

LRESULT CALLBACK DebugProc(

int nCode,	// hook code
WPARAM wParam,	// type of hook about to be called
LPARAM lParam	// address of structure with debugging information
);
Parameters

nCode

Specifies whether the hook procedure must process the message. If nCode is HC_ACTION, the hook procedure must process the message. If nCode is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies the type of hook about to be called. This parameter can be one of the following values:

Value	Description
WH_CALLWNDPROC	Installs a hook procedure that monitors messages sent to a window procedure. For more information, see the description of the CallWndProc hook procedure.
WH_CALLWNDPROCRET	Installs a hook procedure that monitors messages that have just been processed by a window procedure. For more information, see the description of the CallWndRetProc hook procedure.
WH_CBT	Installs a hook procedure that receives notifications useful to a computer-based training (CBT) application. For more information, see the description of the CBTProc hook procedure.
WH_DEBUG	Installs a hook procedure useful for debugging other hook procedures. For more information, see the description of the DebugProc hook procedure.
WH_GETMESSAGE	Installs a hook procedure that monitors messages posted to a message queue. For more information, see the description of the GetMsgProc hook procedure.
WH_JOURNALPLAYBACK	Installs a hook procedure that posts messages previously recorded by a WH_JOURNALRECORD hook procedure. For more information, see the description of the JournalPlaybackProc hook procedure.
WH_JOURNALRECORD	Installs a hook procedure that records input messages posted to the system message queue. This hook is useful for recording macros. For more information, see the description of the JournalRecordProc hook procedure.
WH_KEYBOARD	Installs a hook procedure that monitors keystroke messages. For more information, see the description of the KeyboardProc hook procedure.
WH_MOUSE	Installs a hook procedure that monitors mouse messages. For more information, see the description of the MouseProc hook procedure.
WH_MSGFILTER	Installs a hook procedure that monitors messages generated as a result of an input event in a dialog box, message box, menu, or scroll bar. The hook procedure monitors these messages only for the application that installed the hook procedure. For more information, see the description of the MessageProc hook procedure.
WH_SHELL	Installs a hook procedure that receives notifications useful to a shell application. For more information, see the description of the ShellProc hook procedure.
WH_SYSMSGFILTER	Installs a hook procedure that monitors messages generated as a result of an input event in a dialog box, message box, menu, or scroll bar. The hook procedure monitors these messages for all applications in the system. For more information, see the description of the SysMsgProc hook procedure.
lParam

Points to a DEBUGHOOKINFO structure that contains the parameters to be passed to the destination hook procedure.

Return Values

To prevent the system from calling the hook, the return value must be a nonzero value. Otherwise, the hook procedure must pass the hook information to the CallNextHookEx function.

Remarks

An application installs this hook procedure by specifying the WH_DEBUG hook type and the pointer to the hook procedure in a call to the SetWindowsHookEx function.

CallWndProc and CallWndRetProc are placeholders for the application-defined or library-defined function names.

See Also

CallNextHookEx, CallWndProc, CallWndRetProc, CBTProc, DEBUGHOOKINFO, GetMsgProc, JournalPlaybackProc, JournalRecordProc, KeyboardProc, MessageProc, MouseProc, SetWindowsHookEx, ShellProc, SysMsgProc


DefDlgProc

The DefDlgProc function carries out default message processing for a window procedure belonging to an application-defined dialog box class.

LRESULT DefDlgProc(

HWND hDlg,	// handle to dialog box
UINT Msg,	// message
WPARAM wParam,	// first message parameter
LPARAM lParam	// second message parameter
);
Parameters

hDlg

Identifies the dialog box.

Msg

Specifies the message number.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Values

The return value specifies the result of the message processing and depends on the message sent.

Remarks

The DefDlgProc function is the window procedure for the predefined class of dialog box. This procedure provides internal processing for the dialog box by forwarding messages to the dialog box procedure and carrying out default processing for any messages that the dialog box procedure returns as FALSE. Applications that create custom window procedures for their custom dialog boxes often use DefDlgProc instead of the DefWindowProc function to carry out default message processing.

Applications create custom dialog box classes by filling a WNDCLASS structure with appropriate information and registering the class with the RegisterClass function. Some applications fill the structure by using the GetClassInfo function, specifying the name of the predefined dialog box. In such cases, the applications modify at least the lpszClassName member before registering. In all cases, the cbWndExtra member of WNDCLASS for a custom dialog box class must be set to at least DLGWINDOWEXTRA.

The DefDlgProc function must not be called by a dialog box procedure; doing so results in recursive execution.

See Also

DefWindowProc, GetClassInfo, RegisterClass, WNDCLASS


DeferWindowPos

The DeferWindowPos function updates the specified multiple-window − position structure for the specified window. The function then returns the handle to the updated structure. The EndDeferWindowPos function uses the information in this structure to change the position and size of a number of windows simultaneously. The BeginDeferWindowPos function creates the structure.

HDWP DeferWindowPos(

HDWP hWinPosInfo,	// handle to internal structure
HWND hWnd,	// handle to window to position
HWND hWndInsertAfter,	// placement-order handle
int x,	// horizontal position
int y,	// vertical position
int cx,	// width
int cy,	// height
UINT uFlags	// window-positioning flags
);
Parameters

hWinPosInfo

Identifies a multiple-window − position structure that contains size and position information for one or more windows. This structure is returned by BeginDeferWindowPos or by the most recent call to DeferWindowPos.

hWnd

Identifies the window for which update information is stored in the structure.

hWndInsertAfter

Identifies the window that precedes the positioned window in the Z order. This parameter must be a window handle or one of the following values:

Value	Meaning
HWND_BOTTOM	Places the window at the bottom of the Z order. If the hWnd parameter identifies a topmost window, the window loses its topmost status and is placed at the bottom of all other windows.
HWND_NOTOPMOST	Places the window above all non-topmost windows (that is, behind all topmost windows). This flag has no effect if the window is already a non-topmost window.
HWND_TOP	Places the window at the top of the Z order.
HWND_TOPMOST	Places the window above all non-topmost windows. The window maintains its topmost position even when it is deactivated.
This parameter is ignored if the SWP_NOZORDER flag is set in the uFlags parameter.

x

Specifies the x-coordinate of the window’s upper-left corner.

y

Specifies the y-coordinate of the window’s upper-left corner.

cx

Specifies the window’s new width, in pixels.

cy

Specifies the window’s new height, in pixels.

uFlags

Specifies a combination of the following values that affect the size and position of the window:

Value	Meaning
SWP_DRAWFRAME	Draws a frame (defined in the window’s class description) around the window.
SWP_FRAMECHANGED	Sends a WM_NCCALCSIZE message to the window, even if the window’s size is not being changed. If this flag is not specified, WM_NCCALCSIZE is sent only when the window’s size is being changed.
SWP_HIDEWINDOW	Hides the window.
SWP_NOACTIVATE	Does not activate the window. If this flag is not set, the window is activated and moved to the top of either the topmost or non-topmost group (depending on the setting of the hWndInsertAfter parameter).
SWP_NOCOPYBITS	Discards the entire contents of the client area. If this flag is not specified, the valid contents of the client area are saved and copied back into the client area after the window is sized or repositioned.
SWP_NOMOVE	Retains the current position (ignores the X and Y parameters).
SWP_NOOWNERZORDER	Does not change the owner window’s position in the Z order.
SWP_NOREDRAW	Does not redraw changes. If this flag is set, no repainting of any kind occurs. This applies to the client area, the nonclient area (including the title bar and scroll bars), and any part of the parent window uncovered as a result of the window being moved. When this flag is set, the application must explicitly invalidate or redraw any parts of the window and parent window that need redrawing.
SWP_NOREPOSITION	Same as the SWP_NOOWNERZORDER flag.
SWP_NOSENDCHANGING	Prevents the window from receiving the WM_WINDOWPOSCHANGING message.
SWP_NOSIZE	Retains the current size (ignores the cx and cy parameters).
SWP_NOZORDER	Retains the current Z order (ignores the hWndInsertAfter parameter).
SWP_SHOWWINDOW	Displays the window.
Return Values

The return value identifies the updated multiple-window − position structure. The handle returned by this function may differ from the handle passed to the function. The new handle that this function returns should be passed during the next call to the DeferWindowPos or EndDeferWindowPos function.

If insufficient system resources are available for the function to succeed, the return value is NULL.

Remarks

If a call to DeferWindowPos fails, the application should abandon the window-positioning operation and not call EndDeferWindowPos.

If SWP_NOZORDER is not specified, Windows places the window identified by the hWnd parameter in the position following the window identified by the hWndInsertAfter parameter. If hWndInsertAfter is NULL or HWND_TOP, Windows places the hWnd window at the top of the Z order. If hWndInsertAfter is set to HWND_BOTTOM, Windows places the hWnd window at the bottom of the Z order.

All coordinates for child windows are relative to the upper-left corner of the parent window’s client area.

A window can be made a topmost window either by setting hWndInsertAfter to the HWND_TOPMOST flag and ensuring that the SWP_NOZORDER flag is not set, or by setting the window’s position in the Z order so that it is above any existing topmost windows. When a non-topmost window is made topmost, its owned windows are also made topmost. Its owners, however, are not changed.

If neither the SWP_NOACTIVATE nor SWP_NOZORDER flag is specified (that is, when the application requests that a window be simultaneously activated and its position in the Z order changed), the value specified in hWndInsertAfter is used only in the following circumstances:

•	Neither the HWND_TOPMOST nor HWND_NOTOPMOST flag is specified in hWndInsertAfter.

•	The window identified by hWnd is not the active window.

An application cannot activate an inactive window without also bringing it to the top of the Z order. An application can change an activated window’s position in the Z order without restrictions, or it can activate a window and then move it to the top of the topmost or non-topmost windows.

A topmost window is no longer topmost if it is repositioned to the bottom (HWND_BOTTOM) of the Z order or after any non-topmost window. When a topmost window is made non-topmost, its owners and its owned windows are also made non-topmost windows.

A non-topmost window may own a topmost window, but not vice versa. Any window (for example, a dialog box) owned by a topmost window is itself made a topmost window to ensure that all owned windows stay above their owner.

See Also

BeginDeferWindowPos, EndDeferWindowPos, ShowWindow


DefFrameProc

The DefFrameProc function provides default processing for any window messages that the window procedure of a multiple document interface (MDI) frame window does not process. All window messages that are not explicitly processed by the window procedure must be passed to the DefFrameProc function, not the DefWindowProc function.

LRESULT DefFrameProc(

HWND hWnd,	// handle to MDI frame window
HWND hWndMDIClient,	// handle to MDI client window
UINT uMsg,	// message
WPARAM wParam,	// first message parameter
LPARAM lParam	// second message parameter
);
Parameters

hWnd

Identifies the MDI frame window.

hWndMDIClient

Identifies the MDI client window.

uMsg

Specifies the message to be processed.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Values

The return value specifies the result of the message processing and depends on the message. If the hWndMDIClient parameter is NULL, the return value is the same as for the DefWindowProc function.

Remarks

When an application’s window procedure does not handle a message, it typically passes the message to the DefWindowProc function to process the message. MDI applications use the DefFrameProc and DefMDIChildProc functions instead of DefWindowProc to provide default message processing. All messages that an application would usually pass to DefWindowProc (such as nonclient messages and the WM_SETTEXT message) should be passed to DefFrameProc instead. The DefFrameProc function also handles the following messages:

Message	Response
WM_COMMAND	Activates the MDI child window that the user chooses. This message is sent when the user chooses an MDI child window from the Window menu of the MDI frame window. The window identifier accompanying this message identifies the MDI child window to be activated.
WM_MENUCHAR	Opens the window menu of the active MDI child window when the user presses the ALT+ − (minus) key combination.
WM_SETFOCUS	Passes the keyboard focus to the MDI client window, which in turn passes it to the active MDI child window.
WM_SIZE	Resizes the MDI client window to fit in the new frame window’s client area. If the frame window procedure sizes the MDI client window to a different size, it should not pass the message to the DefWindowProc function.
See Also

DefMDIChildProc, DefWindowProc, WM_SETTEXT


DefHookProc

The DefHookProc function is obsolete. It is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the CallNextHookEx function.


DefineDosDevice

The DefineDosDevice function lets an application define, redefine, or delete MS-DOS device names.

MS-DOS device names are stored as symbolic links in the object name space in 32-bit versions of Windows. The code that converts an MS-DOS path into a corresponding path in 32-bit versions of Windows uses these symbolic links to map MS-DOS devices and drive letters. The DefineDosDevice function provides a mechanism whereby a Win32-based application can modify the symbolic links used to implement the MS-DOS device name space.

BOOL DefineDosDevice(

DWORD dwFlags,	// flags specifying aspects of device definition
LPCTSTR lpDeviceName,	// pointer to MS-DOS device name string
LPCTSTR lpTargetPath	// pointer to MS-DOS or path string for 32-bit Windows
);
Parameters

dwFlags

Specifies several controllable aspects of the DefineDosDevice function. One or more of the following values can be used:

Value	Meaning
DDD_RAW_TARGET_PATH	If this value is specified, the function does not convert the lpTargetPath string from an MS-DOS path to a path for a 32-bit version of Windows, but takes it as is.
DDD_REMOVE_DEFINITION	If this value is specified, the function removes the specified definition for the specified device. To determine which definition to remove, the function walks the list of mappings for the device, looking for a match of lpTargetPath against a prefix of each mapping associated with this device. The first mapping that matches is the one removed, and then the function returns. If lpTargetPath is NULL or a pointer to a NULL string, the function will remove the first mapping associated with the device and pop the most recent one pushed. If there is nothing left to pop, the device name will be removed. If this value is NOT specified, the string pointed to by the lpTargetPath parameter will become the new mapping for this device.
DDD_EXACT_MATCH_ON_REMOVE	If this value is specified along with DDD_REMOVE_DEFINITION, the function will use an exact match to determine which mapping to remove. Use this value to insure that you do not delete something that you did not define.
lpDeviceName

Points to an MS-DOS device name string specifying the device the function is defining, redefining, or deleting. The device name string must not have a trailing colon, unless a drive letter (C or D, for example) is being defined, redefined, or deleted.

lpTargetPath

Points to a path string that will implement this device. Points to an MS-DOS path string unless the DDD_RAW_TARGET_PATH flag is specified, in which case this parameter points to a path string for a 32-bit version of Windows.

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.

Remarks

As stated in this function’s introductory summary, the DefineDosDevice function provides a means whereby a Win32-based application can create and modify the symbolic links used to implement the MS-DOS device namespace. To retrieve the current mapping for a particular MS-DOS device name or to obtain a list of all MS-DOS devices known to the system, use the QueryDosDevice function.

MS-DOS Device names are global. Once defined, an MS-DOS device name remains visible to all processes until either it is explicitly removed or the system reboots.

Note that drive letters and device names defined at system boot time are protected from redefinition and deletion unless a user is running in administrative mode (ADMIN).

See Also

QueryDosDevice


DefineHandleTable

The DefineHandleTable function is obsolete. It is provided as a macro to simplify porting of 16-bit Windows-based applications. It expands to TRUE after evaluating its argument. It has no other effect.


DefMDIChildProc

The DefMDIChildProc function provides default processing for any window message that the window procedure of a multiple document interface (MDI) child window does not process. A window message not processed by the window procedure must be passed to the DefMDIChildProc function, not to the DefWindowProc function.

LRESULT DefMDIChildProc(

HWND hWnd,	// handle to MDI child window
UINT uMsg,	// message
WPARAM wParam,	// first message parameter
LPARAM lParam	// second message parameter
);
Parameters

hWnd

Identifies the MDI child window.

uMsg

Specifies the message to be processed.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Values

The return value specifies the result of the message processing and depends on the message.

Remarks

The DefMDIChildProc function assumes that the parent window of the MDI child window identified by the hWnd parameter was created with the MDICLIENT class.

When an application’s window procedure does not handle a message, it typically passes the message to the DefWindowProc function to process the message. MDI applications use the DefFrameProc and DefMDIChildProc functions instead of DefWindowProc to provide default message processing. All messages that an application would usually pass to DefWindowProc (such as nonclient messages and the WM_SETTEXT message) should be passed to DefMDIChildProc instead. In addition, DefMDIChildProc also handles the following messages:

Message	Response
WM_CHILDACTIVATE	Performs activation processing when MDI child windows are sized, moved, or displayed. This message must be passed.
WM_GETMINMAXINFO	Calculates the size of a maximized MDI child window, based on the current size of the MDI client window.
WM_MENUCHAR	Passes the message to the MDI frame window.
WM_MOVE	Recalculates MDI client scroll bars if they are present.
WM_SETFOCUS	Activates the child window if it is not the active MDI child window.
WM_SIZE	Performs operations necessary for changing the size of a window, especially for maximizing or restoring an MDI child window. Failing to pass this message to the DefMDIChildProc function produces highly undesirable results.
WM_SYSCOMMAND	Handles window menu commands: SC_NEXTWINDOW, SC_PREVWINDOW, SC_MOVE, SC_SIZE, and SC_MAXIMIZE.
See Also

DefFrameProc, DefWindowProc, WM_CHILDACTIVATE, WM_GETMINMAXINFO, WM_MENUCHAR, WM_MOVE, WM_SETFOCUS, WM_SETTEXT, WM_SIZE, WM_SYSCOMMAND


DefScreenSaverProc

The DefScreenSaverProc function provides default processing for any messages that a screen saver application does not process.

LONG DefScreenSaverProc(

HWND hWnd,	// handle to screen saver window
UINT msg,	// message
WPARAM wParam,	// first message parameter
LPARAM lParam	// second message parameter
);
Parameters

hWnd

Identifies the screen saver window.

msg

Specifies the message to be processed. The DefScreenSaverProc function responds to messages that affect the screen saver’s operation, as detailed in the Remarks section.

If a screen saver application must perform a different action in response to any of these messages, the application’s ScreenSaverProc window procedure should process the message.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Values

The return value specifies the result of the message processing and depends on the message sent.

Remarks

A screen saver application’s ScreenSaverProc window procedure should use DefScreenSaverProc instead of the DefWindowProc function to provide default message processing. The DefScreenSaverProc function passes any messages that do not affect screen saver operation to DefWindowProc.

The following table describes how the DefScreenSaverProc processes a variety of window messages:

Message	Action
WM_ACTIVATE, WM_ACTIVATEAPP, WM_NCACTIVATE	Closes the screen saver if the wParam parameter is FALSE. A wParam value of FALSE indicates that the screen saver is losing the input focus. The screen saver is closed by sending a WM_CLOSE message.
WM_SETCURSOR	Removes the cursor from the screen by setting the cursor to NULL.
WM_LBUTTONDOWN, WM_RBUTTONDOWN, WM_MBUTTONDOWN, WM_KEYDOWN, WM_KEYUP, WM_MOUSEMOVE	Calls the PostQuitMessage function to close the screen saver.
WM_DESTROY	Posts a WM_CLOSE message to close the screen saver window.
WM_SYSCOMMAND	Returns FALSE if the wParam parameter of WM_SYSCOMMAND is either SC_CLOSE or SC_SCREENSAVE.
See Also

DefWindowProc, PostQuitMessage, ScreenSaverProc, WM_ACTIVATE, WM_ACTIVATEAPP, WM_CLOSE, WM_DESTROY, WM_KEYDOWN, WM_KEYUP, WM_LBUTTONDOWN, WM_MBUTTONDOWN, WM_MOUSEMOVE, WM_NCACTIVATE, WM_RBUTTONDOWN, WM_SETCURSOR, WM_SYSCOMMAND


DefWindowProc

The DefWindowProc function calls the default window procedure to provide default processing for any window messages that an application does not process. This function ensures that every message is processed. DefWindowProc is called with the same parameters received by the window procedure.

LRESULT DefWindowProc(

HWND hWnd,	// handle to window
UINT Msg,	// message identifier
WPARAM wParam,	// first message parameter
LPARAM lParam	// second message parameter
);
Parameters

hWnd

Identifies the window procedure that received the message.

Msg

Specifies the message.

wParam

Specifies additional message information. The content of this parameter depends on the value of the Msg parameter.

lParam

Specifies additional message information. The content of this parameter depends on the value of the Msg parameter.

Return Values

The return value is the result of the message processing and depends on the message.

See Also

CallWindowProc, DefDlgProc, WindowProc


DeleteAce

The DeleteAce function deletes an ACE from an ACL.

An ACE is an access-control entry. An ACL is an access-control list.

BOOL DeleteAce(

PACL pAcl,	// pointer to access-control list
DWORD dwAceIndex	// index of ACE position in ACL
);
Parameters

pAcl

Points to an ACL structure. The ACE specified by the dwAceIndex parameter is removed from this ACL.

dwAceIndex

Specifies the ACE to delete. A value of 0 corresponds to the first ACE in the ACL, 1 to the second ACE, and so on.

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.

Remarks

An application can use the ACL_SIZE_INFORMATION structure retrieved by the GetAclInformation function to discover the size of the ACL and the number of ACEs it contains. The GetAce function retrieves information about an individual ACE.

See Also

ACL, ACL_SIZE_INFORMATION, AddAccessAllowedAce, AddAccessDeniedAce, AddAce, AddAuditAccessAce, GetAce, GetAclInformation


DeleteAtom

The DeleteAtom function decrements the reference count of a local string atom. If the atom’s reference count is reduced to zero, DeleteAtom removes the string associated with the atom from the local atom table.

ATOM DeleteAtom(

ATOM nAtom	// atom to delete
);
Parameters

nAtom

Identifies the atom and character string to be deleted.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is the nAtom parameter. To get extended error information, call GetLastError.

Remarks

A string atom’s reference count specifies the number of times the atom has been added to or removed from the atom table. The AddAtom function increments the count on each call. The DeleteAtom function decrements the count on each call but removes the string only if the atom’s reference count is zero.

The only way to ensure that an atom has been deleted from the atom table is to call this function repeatedly until it fails. When the reference count is reduced to zero, the next call to the FindAtom or DeleteAtom function fails.

The DeleteAtom function has no effect on an integer atom (an atom created by using the MAKEINTATOM macro). The function always returns zero for an integer atom.

See Also

AddAtom, FindAtom, GlobalAddAtom, GlobalDeleteAtom, GlobalFindAtom, MAKEINTATOM


DeleteColorSpace

The DeleteColorSpace function deletes the specified color space, freeing all internal resources associated with it.

BOOL DeleteColorSpace(

HCOLORSPACE hColorSpace
);
Parameters

hColorSpace

Handle to the color space to delete.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.


DeleteCriticalSection

The DeleteCriticalSection function releases all resources used by an unowned critical section object.

VOID DeleteCriticalSection(

LPCRITICAL_SECTION lpCriticalSection	// pointer to critical section object
);
Parameters

lpCriticalSection

Points to the critical section object.

Return Values

This function does not return a value.

Remarks

Deleting a critical section object releases all system resources used by the object. Once deleted, the critical section object cannot be specified in the EnterCriticalSection, TryEnterCriticalSection, or LeaveCriticalSection function.

See Also

EnterCriticalSection, InitializeCriticalSection, LeaveCriticalSection TryEnterCriticalSection


DeleteDC

The DeleteDC function deletes the specified device context (DC).

BOOL DeleteDC(

HDC hdc	// handle to device context
);
Parameters

hdc

Identifies the device context.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

An application must not delete a device context whose handle was obtained by calling the GetDC function. Instead, it must call the ReleaseDC function to free the device context.

See Also

CreateDC, GetDC, ReleaseDC


DeleteEnhMetaFile

The DeleteEnhMetaFile function deletes an enhanced-format metafile or an enhanced-format metafile handle.

BOOL DeleteEnhMetaFile(

HENHMETAFILE hemf	// handle to an enhanced metafile
);
Parameters

hemf

Identifies an enhanced metafile.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

If the hemf parameter identifies an enhanced metafile stored in memory, the DeleteEnhMetaFile function deletes the metafile. If hemf identifies a metafile stored on a disk, the function deletes the metafile handle but does not destroy the actual metafile. An application can retrieve the file by calling the GetEnhMetaFile function.

See Also

CopyEnhMetaFile, CreateEnhMetaFile, GetEnhMetaFile


DeleteFiber

The DeleteFiber function deletes an existing fiber.

VOID DeleteFiber(

LPVOID lpFiber	// pointer to the fiber to delete
);
Parameters

lpFiber

Specifies the address of the fiber to delete.

Return Values

This function does not return a value.

Remarks

The DeleteFiber function deletes all data associated with the fiber. This data includes the stack, a subset of the registers, and the fiber data. If the currently running fiber calls DeleteFiber, the ExitThread function is called and the thread terminates. If the currently running fiber is deleted by another thread, the thread associated with the fiber is likely to terminate abnormally because the fiber stack has been freed.

See Also

ExitThread


DeleteFile

The DeleteFile function deletes an existing file.

BOOL DeleteFile(

LPCTSTR lpFileName	// pointer to name of file to delete
);
Parameters

lpFileName

Points to a null-terminated string that specifies the file to be deleted.

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.

Remarks

If an application attempts to delete a file that does not exist, the DeleteFile function fails.

Windows 95: The DeleteFile function deletes a file even if it is open for normal I/O or as a memory-mapped file. To prevent loss of data, close files before attempting to delete them.

Windows NT: The DeleteFile function fails if an application attempts to delete a file that is open for normal I/O or as a memory-mapped file.

To close an open file, use the CloseHandle function.

See Also

CloseHandle, CreateFile


DeleteForm

The DeleteForm function removes a form name from the list of supported forms.

BOOL DeleteForm(

HANDLE hPrinter,	// handle to printer object
LPTSTR pFormName	// pointer to form name
);
Parameters

hPrinter

Indicates the open printer handle that this function is to be performed upon.

pFormName

Points to the form name to be removed.

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.

Remarks

The printer handle is obtained by calling the OpenPrinter function. DeleteForm can only delete form names that were added by using the AddForm function.

See Also

AddForm, OpenPrinter


DeleteMenu

The DeleteMenu function deletes an item from the specified menu. If the menu item opens a menu or submenu, this function destroys the handle to the menu or submenu and frees the memory used by the menu or submenu.

BOOL DeleteMenu(

HMENU hMenu,	// handle to menu
UINT uPosition,	// menu item identifier or position
UINT uFlags	// menu item flag
);
Parameters

hMenu

Identifies the menu to be changed.

uPosition

Specifies the menu item to be deleted, as determined by the uFlags parameter.

uFlags

Specifies how the uPosition parameter is interpreted. This parameter must be one of the following values:

Value	Meaning
MF_BYCOMMAND	Indicates that uPosition gives the identifier of the menu item. The MF_BYCOMMAND flag is the default flag if neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified.
MF_BYPOSITION	Indicates that uPosition gives the zero-based relative position of the menu item.
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.

Remarks

The application must call the DrawMenuBar function whenever a menu changes, whether or not the menu is in a displayed window.

See Also

DrawMenuBar, RemoveMenu


DeleteMetaFile

The DeleteMetaFile function deletes a Windows-format metafile or Windows-format metafile handle.

This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the DeleteEnhMetaFile function.

BOOL DeleteMetaFile(

HMETAFILE hmf	// handle to Windows-format metafile
);
Parameters

hmf

Identifies a Windows-format metafile.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

A Windows-format metafile does not support the new curve, path, and transformation functions, such as PolyBezier, BeginPath, and SetWorldTransform. Applications that use these new functions and use metafiles to store pictures created by these functions should use the enhanced format metafile functions.

If the metafile identified by the hmf parameter is stored in memory (rather than on a disk), its content is lost when it is deleted by using the DeleteMetaFile function.

See Also

BeginPath, CopyMetaFile, CreateMetaFile, DeleteEnhMetaFile, GetMetaFile, PolyBezier, SetWorldTransform


DeleteMonitor

The DeleteMonitor function removes a printer monitor added by the AddMonitor function.

BOOL DeleteMonitor(

LPTSTR pName,	// pointer to server name
LPTSTR pEnvironment,	// pointer to environment string
LPTSTR pMonitorName	// pointer to monitor name
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server from which the monitor is to be removed. If this parameter is NULL, the printer monitor is removed locally.

pEnvironment

Points to a null-terminated string that specifies the environment from which the monitor is to be removed (for example, “Windows NT x86”, “Windows NT R4000”, “Windows NT Alpha_AXP”, or “Windows 4.0”). If this parameter is NULL, the monitor is removed from the current environment of the calling application and client machine (not of the destination application and print server).

pMonitorName

Points to a null-terminated string that specifies the name of the monitor to be removed.

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.

See Also

AddMonitor


DeleteObject

The DeleteObject function deletes a logical pen, brush, font, bitmap, region, or palette, freeing all system resources associated with the object. After the object is deleted, the specified handle is no longer valid.

BOOL DeleteObject(

HGDIOBJ hObject	// handle to graphic object
);
Parameters

hObject

Identifies a logical pen, brush, font, bitmap, region, or palette.

Return Values

If the function succeeds, the return value is nonzero.

If the specified handle is not valid or is currently selected into a device context, the return value is zero.

Remarks

Do not delete a drawing object (pen or brush) while it is still selected into a device context.

When a pattern brush is deleted, the bitmap associated with the brush is not deleted. The bitmap must be deleted independently.

See Also

SelectObject


DeletePort

The DeletePort function displays a dialog box that allows the user to delete a port name.

BOOL DeletePort(

LPTSTR pName,	// pointer to server name
HWND hWnd,	// handle to window that displays dialog box
LPTSTR pPortName	// pointer to port name
);
Parameters

pName

Pointer to a zero-terminated string that specifies the name of the server for which the port should be deleted. If this parameter is NULL, a local port is deleted.

hWnd

Handle to the parent window of the port-deletion dialog box.

pPortName

Pointer to a zero-terminated string that specifies the name of the port that should be deleted.

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.

Remarks

An application can retrieve the names of valid ports by calling the EnumPorts function.

The DeletePort function returns an error if a printer is currently connected to the specified port.

The caller of the AddPort function must have SERVER_ACCESS_ADMINISTER access to the server to which the port is connected.

See Also

AddPort, EnumPorts


DeletePrinter

The DeletePrinter function deletes the specified printer object.

BOOL DeletePrinter(

HANDLE hPrinter	// handle to printer object
);
Parameters

hPrinter

Identifies a printer object that will be deleted.

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.

Remarks

The printer handle hPrinter is obtained by calling the OpenPrinter or AddPrinter function. Most users will use OpenPrinter.

If there are print jobs remaining to be processed for the specified printer, DeletePrinter marks the printer for pending deletion, and then deletes it when all the print jobs have been printed. No print jobs can be added to a printer that is marked for pending deletion.

A printer marked for pending deletion cannot be held, but its print jobs can be held, resumed, and restarted. If the printer is held and there are jobs for the printer, DeletePrinter fails with an InvalidState error.

See Also

AddPrinter, EnumPrinters, OpenPrinter


DeletePrinterConnection

The DeletePrinterConnection function deletes a connection to a printer that was established by a call to AddPrinterConnection or ConnectToPrinterDlg.

BOOL DeletePrinterConnection (

LPTSTR pName	// pointer to printer name
);
Parameters

pName

Points to a null-terminated string that specifies the name of the printer connection to delete.

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.

Remarks

The DeletePrinterConnection function does not delete any printer drivers copied to the server on which the printer resides when the printer connection was established.

See Also

AddPrinterConnection, ConnectToPrinterDlg


DeletePrinterData [New - Windows NT]
DeletePrinterData

[New - Windows NT]

The DeletePrinterData function deletes specified configuration data for a printer.

A printer’s configuration data consists of a set of named and typed values. The DeletePrinterData function deletes one of these values, specified by its value name.

DWORD DeletePrinterData(

HANDLE hPrinter,	// handle to printer of interest
LPTSTR pValueName,	// pointer to null-terminated value name string
);
Parameters

hPrinter

Handle to the printer whose configuration data is to be deleted.

You obtain this printer handle by calling the OpenPrinter function.

pValueName

Pointer to the null-terminated name of the configuration data value to be deleted.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a Win32 error value.

See Also

EnumPrinterData, GetPrinterData, OpenPrinter, SetPrinter, SetPrinterData


DeletePrinterDriver

The DeletePrinterDriver function removes the specified printer-driver name from the list of names of supported drivers for a server.

BOOL DeletePrinterDriver(

LPTSTR pName,	// pointer to server name
LPTSTR pEnvironment,	// pointer to environment
LPTSTR pDriverName	// pointer to driver name
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server from which the driver is to be deleted. If this parameter is NULL, the printer-driver name will be removed locally.

pEnvironment

Points to a null-terminated string that specifies the environment from which the driver is to be deleted (for example, “Windows NT x86”, “Windows NT R4000”, “Windows NT Alpha_AXP”, or “Windows 4.0”). If this parameter is NULL, the driver name is deleted from the current environment of the calling application and client machine (not of the destination application and print server).

pDriverName

Points to a null-terminated string specifying the name of the driver that should be deleted.

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.

Remarks

The DeletePrinterDriver function does not delete the associated files, it merely removes the driver name from the list returned by the EnumPrinterDrivers function.

See Also

EnumPrinterDrivers


DeletePrintProcessor

The DeletePrintProcessor function removes a printer processor added by the AddPrintProcessor function.

BOOL DeletePrintProcessor(

LPTSTR pName,	// pointer to server name
LPTSTR pEnvironment,	// pointer to environment string
LPTSTR pPrintProcessorName	// pointer to processor name
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server from which the processor is to be removed. If this parameter is NULL, the printer processor is removed locally.

pEnvironment

Points to a null-terminated string that specifies the environment from which the processor is to be removed (for example, “Windows NT x86”, “Windows NT R4000”, “Windows NT Alpha_AXP”, or “Windows 4.0”). If this parameter is NULL, the processor is removed from the current environment of the calling application and client machine (not of the destination application and print server). NULL is the recommended value, as it provides maximum portability.

pPrintProcessorName

Points to a null-terminated string that specifies the name of the processor to be removed.

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.

See Also

AddPrintProcessor


DeletePrintProvidor

The DeletePrintProvidor function removes a printer provider added by the AddPrintProvidor function.

BOOL DeletePrintProvidor(

LPTSTR pName,	// pointer to server name
LPTSTR pEnvironment,	// pointer to environment string
LPTSTR pPrintProvidorName	// pointer to provider name
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server from which the provider is to be removed. If this parameter is NULL, the printer provider is removed locally.

pEnvironment

Points to a null-terminated string that specifies the environment from which the provider is to be removed (for example, “Windows NT x86”, “Windows NT R4000”, “Windows NT Alpha_AXP”, or “Windows 4.0”). If this parameter is NULL, the provider is removed from the current environment of the calling application and client machine (not of the destination application and print server). NULL is the recommended value because it provides maximum portability.

pPrintProvidorName

Points to a null-terminated string that specifies the name of the provider to be removed.

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.

See Also

AddPrintProvidor


DeleteService

The DeleteService function marks the specified service for deletion from the service control manager database.

BOOL DeleteService(

SC_HANDLE hService	// handle to service
);
Parameters

hService

Identifies the service. This handle is returned by the OpenService or CreateService function, and it must have DELETE access.

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.

Errors

The following error codes may be set by the service control manager. Others may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED	The specified handle was not opened with DELETE access.
ERROR_INVALID_HANDLE	The specified handle is invalid.
ERROR_SERVICE_MARKED_FOR_DELETE	The specified service has already been marked for deletion.
Remarks

The DeleteService function marks a service for deletion from the service control manager database. The database entry is not removed until all open handles to the service have been closed by calls to the CloseServiceHandle function, and the service is not running. A running service is stopped by a call to the ControlService function with the SERVICE_CONTROL_STOP control code. If the service cannot be stopped, the database entry is removed when the system is restarted.

The service control manager deletes the service by deleting the service key and its subkeys from the registry.

See Also

CloseServiceHandle, ControlService, CreateService, OpenService


DeregisterEventSource

The DeregisterEventSource function closes a handle returned by the RegisterEventSource function.

BOOL DeregisterEventSource(

HANDLE hEventLog	// handle to event log
);
Parameters

hEventLog

Identifies the event log whose handle was returned by RegisterEventSource.

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.

See Also

RegisterEventSource


DestroyAcceleratorTable

The DestroyAcceleratorTable function destroys an accelerator table. Before an application closes, it must use this function to destroy each accelerator table that it created by using the CreateAcceleratorTable function.

BOOL DestroyAcceleratorTable(

HACCEL hAccel	// handle to accelerator table
);
Parameters

hAccel

Identifies the accelerator table to destroy. This handle must have been created by a call to the CreateAcceleratorTable 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.

See Also

CopyAcceleratorTable, CreateAcceleratorTable, LoadAccelerators, TranslateAccelerator


DestroyCaret

The DestroyCaret function destroys the caret’s current shape, frees the caret from the window, and removes the caret from the screen.

If the caret shape is based on a bitmap, DestroyCaret does not free the bitmap.

BOOL DestroyCaret(VOID)

Parameters

This function has no parameters.

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.

Remarks

DestroyCaret destroys the caret only if a window in the current task owns the caret. If a window that is not in the current task owns the caret, DestroyCaret does nothing and returns FALSE.

The caret is a shared resource; there is only one caret in the system. A window should create a caret only when it has the keyboard focus or is active. The window should destroy the caret before losing the keyboard focus or becoming inactive.

See Also

CreateCaret, HideCaret, ShowCaret


DestroyCursor

The DestroyCursor function destroys a cursor created by the CreateCursor function and frees any memory the cursor occupied. Do not use this function to destroy a cursor that was not created with the CreateCursor function.

BOOL DestroyCursor(

HCURSOR hCursor	// handle to cursor to destroy
);
Parameters

hCursor

Identifies the cursor to be destroyed. The cursor must not be in use.

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.

See Also

CreateCursor


DestroyIcon

The DestroyIcon function destroys an icon and frees any memory the icon occupied.

BOOL DestroyIcon(

HICON hIcon	// handle to icon to destroy
);
Parameters

hIcon

Identifies the icon to be destroyed. The icon must not be in use.

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.

Remarks

It is only necessary to call DestroyIcon for icons created with the CreateIconIndirect function.

See Also

CreateIconIndirect


DestroyMenu

The DestroyMenu function destroys the specified menu and frees any memory that the menu occupies.

BOOL DestroyMenu(

HMENU hMenu	// handle to menu to destroy
);
Parameters

hMenu

Identifies the menu to be destroyed.

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.

Remarks

Before closing, an application must use the DestroyMenu function to destroy a menu not assigned to a window. A menu that is assigned to a window is automatically destroyed when the application closes.

See Also

CreateMenu, DeleteMenu, RemoveMenu


DestroyPrivateObjectSecurity

The DestroyPrivateObjectSecurity function deletes a protected server object’s security descriptor. This security descriptor must have been created by a call to the CreatePrivateObjectSecurity function.

BOOL DestroyPrivateObjectSecurity(

PSECURITY_DESCRIPTOR *ObjectDescriptor	// address of pointer to SECURITY_DESCRIPTOR
);
Parameters

ObjectDescriptor

Points to a pointer to the SECURITY_DESCRIPTOR structure to be deleted.

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.

See Also

CreatePrivateObjectSecurity, GetPrivateObjectSecurity, SECURITY_DESCRIPTOR, SetPrivateObjectSecurity


DestroyPropertySheetPage

The DestroyPropertySheetPage function destroys a property sheet page. An application must call this function for pages that have not been passed to the PropertySheet function.

BOOL DestroyPropertySheetPage(

HPROPSHEETPAGE hPSPage
);
Parameters

hPSPage

Handle to the property sheet page to delete.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

PropertySheet


DestroyWindow

The DestroyWindow function destroys the specified window. The function sends WM_DESTROY and WM_NCDESTROY messages to the window to deactivate it and remove the keyboard focus from it. The function also destroys the window’s menu, flushes the thread message queue, destroys timers, removes clipboard ownership, and breaks the clipboard viewer chain (if the window is at the top of the viewer chain).

If the specified window is a parent or owner window, DestroyWindow automatically destroys the associated child or owned windows when it destroys the parent or owner window. The function first destroys child or owned windows, and then it destroys the parent or owner window.

DestroyWindow also destroys modeless dialog boxes created by the CreateDialog function.

BOOL DestroyWindow(

HWND hWnd	// handle to window to destroy
);
Parameters

hWnd

Identifies the window to be destroyed.

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.

Remarks

A thread cannot use DestroyWindow to destroy a window created by a different thread.

If the window being destroyed is a child window that does not have the WS_EX_NOPARENTNOTIFY style, a WM_PARENTNOTIFY message is sent to the parent.

See Also

CreateDialog, CreateWindow, CreateWindowEx, WM_DESTROY, WM_NCDESTROY, WM_PARENTNOTIFY


DeviceCapabilities

The DeviceCapabilities function retrieves the capabilities of a printer device driver.

DWORD DeviceCapabilities(

LPCTSTR pDevice,	// pointer to a printer-name string
LPCTSTR pPort,	// pointer to a port-name string
WORD fwCapability,	// device capability to query
LPTSTR pOutput,	// pointer to the output
CONST DEVMODE *pDevMode	// pointer to structure with device data
);
Parameters

pDevice

Pointer to a null-terminated string that contains the name of the printer. Note that this is the name of the printer, not of the printer driver.

pPort

Pointer to a null-terminated string that contains the name of the port to which the device is connected, such as “LPT1”.

fwCapability

Specifies the capabilities to query. This parameter can be one of the following values:

Value	Meaning
DC_BINADJUST	Windows 95 only: Retrieves the page positioning for the paper source specified in the DEVMODE structure pointed to by pdevMode. The return value can be one of the following:
	DCBA_FACEUPNONE
	DCBA_FACEUPCENTER
	DCBA_FACEUPLEFT
	DCBA_FACEUPRIGHT
	DCBA_FACEDOWNNONE
	DCBA_FACEDOWNCENTER
	DCBA_FACEDOWNLEFT
	DCBA_FACEDOWNRIGHT
DC_BINNAMES	Copies an array containing a list of the names of the paper bins. This array is in the form char PaperNames[cBinMax][cchBinName] where cchBinName is 24. If the pOutput parameter is NULL, the return value is the number of bin entries required. Otherwise, the return value is the number of bins copied.
DC_BINS	Retrieves a list of available bins. The function copies the list to the pOutput parameter as a WORD array. If pOutput is NULL, the function returns the number of supported bins to allow the application the opportunity to allocate a buffer with the correct size. For more information about these bins, see the description of the dmDefaultSource member of the DEVMODE structure.
DC_COPIES	Returns the number of copies the device can print.
DC_DRIVER	Returns the version number of the printer driver.
DC_DATATYPE_PRODUCED	Windows 95 only: The return value is the number of datatypes supported by the printer driver. If the function returns -1, the driver understands the “RAW” datatype only. The names of the supported datatypes are copied to an array. Use the names in the DOCINFO structure when calling the StartDoc function to specify the datatype.
DC_DUPLEX	Returns the level of duplex support. The function returns 1 if the printer is capable of duplex printing. Otherwise, the return value is zero.
DC_EMF_COMPLIANT	Windows 95 only: Determines if a printer driver supports enhanced metafile (EMF). A return value of 1 means the driver supports EMF. A return value of -1 means that the driver does not support EMF
DC_ENUMRESOLUTIONS	Returns a list of available resolutions. If pOutput is NULL, the function returns the number of available resolution configurations. Resolutions are represented by pairs of LONG integers representing the horizontal and vertical resolutions (specified in dots per inch).
DC_EXTRA	Returns the number of bytes required for the device-specific portion of the DEVMODE structure for the printer driver.
DC_FIELDS	Returns the dmFields member of the printer driver’s DEVMODE structure. The dmFields member indicates which members in the device-independent portion of the structure are supported by the printer driver.
DC_FILEDEPENDENCIES	Returns a list of files that also need to be loaded when a driver is installed. If the pOutput parameter is NULL, the function returns the number of files. Otherwise, pOutput points to an array of filenames in the form char[chFileName, 64]. Each filename is a null-terminated string.
DC_MAXEXTENT	Returns a POINTS structure that contains the maximum paper size that the dmPaperLength and dmPaperWidth members of the printer driver’s DEVMODE structure can specify. The x member of the POINTS structure contains the maximum dmPaperWidth value, and the y member contains the maximum dmPaperLength value.
DC_MINEXTENT	Returns a POINTS structure that contains the minimum paper size that the dmPaperLength and dmPaperWidth members of the printer driver’s DEVMODE structure can specify. The x member of the POINTS structure contains the minimum dmPaperWidth value, and the y member contains the minimum dmPaperLength value.
DC_ORIENTATION	Returns the relationship between portrait and landscape orientations for a device, in terms of the number of degrees that portrait orientation is rotated counterclockwise to produce landscape orientation. The return value can be one of the following:
Value	Meaning
0	No landscape orientation.
90	Portrait is rotated 90 degrees to produce landscape. (For example, Hewlett-Packard PCL printers.)
270	Portrait is rotated 270 degrees to produce landscape. (For example, dot-matrix printers.)
DC_PAPERNAMES	Retrieves a list of supported paper names (for example, Letter or Legal). If the pOutput parameter is NULL, the function returns the number of paper sizes available. Otherwise, pOutput points to an array for the paper names in the form char[cPaperNames, 64]. Each paper name is a null-terminated string.
DC_PAPERS	Retrieves a list of supported paper sizes. The function copies the list to pOutput as a WORD array and returns the number of entries in the array. If pOutput is NULL, the function returns the number of supported paper sizes to allow the application the opportunity to allocate a buffer with the correct size. For more information on paper sizes, see the description of the dmPaperSize member of the DEVMODE structure.
DC_PAPERSIZE	Copies the dimensions of all supported paper sizes, in tenths of a millimeter, to an array of POINT structures pointed to by the pOutput parameter. The width (x-dimension) and length (y-dimension) of a paper size are returned as if the paper were in the DMORIENT_PORTRAIT orientation.
DC_SIZE	Returns the dmSize member of the printer driver’s DEVMODE structure.
DC_TRUETYPE	Retrieves the abilities of the driver to use TrueType fonts. For DC_TRUETYPE, the pOutput parameter should be NULL. The return value can be one or more of the following:
Value	Meaning
DCTT_BITMAP	Device can print TrueType fonts as graphics. (For example, dot-matrix and PCL printers.)
DCTT_DOWNLOAD	Device can download TrueType fonts. (For example, PCL and PostScript printers.)
DCTT_DOWNLOAD_ OUTLINE	Windows 95 only: Device can download outline TrueType fonts.
DCTT_SUBDEV	Device can substitute device fonts for TrueType fonts. (For example, PostScript printers.)
DC_VERSION	Returns the specification version to which the printer driver conforms.
pOutput

Pointer to an array of bytes. The format of the array depends on the setting of the fwCapability parameter. If pOutput is zero, DeviceCapabilities returns the number of bytes required for the output data.

pDevMode

Pointer to a DEVMODE structure. If this parameter is NULL, DeviceCapabilities retrieves the current default initialization values for the specified printer driver. Otherwise, the function retrieves the values contained in the structure to which pDevMode points.

Return Values

If the function succeeds, the return value depends on the setting of the fwCapability parameter.

If the function fails, the return value is −1.

Remarks

In previous versions of Windows, the DeviceCapabilities function was implemented in the printer driver and you needed to call the LoadLibrary and GetProcAddress functions to get a pointer to the function. This is no longer necessary since DeviceCapabilities is part of the Win32 API and you can call it directly. You should not call LoadLibrary on the printer driver.

The DEVMODE structure pointed to by the pDevMode parameter may be obtained by calling the DocumentProperties function.

See Also

DEVMODE, DocumentProperties, GetDeviceCaps, GetProcAddress, LoadLibrary, POINT


DeviceIoControl

The DeviceIoControl function sends a control code directly to a specified device driver, causing the corresponding device to perform the specified operation.

BOOL DeviceIoControl(

HANDLE hDevice,	// handle to device of interest
DWORD dwIoControlCode,	// control code of operation to perform
LPVOID lpInBuffer,	// pointer to buffer to supply input data
DWORD nInBufferSize,	// size of input buffer
LPVOID lpOutBuffer,	// pointer to buffer to receive output data
DWORD nOutBufferSize,	// size of output buffer
LPDWORD lpBytesReturned,	// pointer to variable to receive output byte count
LPOVERLAPPED lpOverlapped	// pointer to overlapped structure for asynchronous operation
);
Parameters

hDevice

Handle to the device that is to perform the operation. Call the CreateFile function to obtain a device handle.

dwIoControlCode

Specifies the control code for the operation. This value identifies the specific operation to be performed and the type of device on which the operation is to be performed. The following values are defined:

Value	Meaning
FSCTL_DISMOUNT_VOLUME	Dismounts a volume.
FSCTL_GET_COMPRESSION	Obtains the compression state of a file or directory
FSCTL_LOCK_VOLUME	Locks a volume.
FSCTL_READ_COMPRESSION	Reserved for future use.
FSCTL_SET_COMPRESSION	Sets the compression state of a file or directory.
FSCTL_UNLOCK_VOLUME	Unlocks a volume.
FSCTL_WRITE_COMPRESSION	Reserved for future use.
IOCTL_DISK_CHECK_VERIFY	Obsolete. Use IOCTL_STORAGE_CHECK_VERIFY
IOCTL_DISK_EJECT_MEDIA	Obsolete. Use IOCTL_STORAGE_EJECT_MEDIA
IOCTL_DISK_FORMAT_TRACKS	Formats a contiguous set of disk tracks.
IOCTL_DISK_GET_DRIVE_GEOMETRY	Obtains information on the physical disk’s geometry.
IOCTL_DISK_GET_DRIVE_LAYOUT	Provides information about each partition on a disk.
IOCTL_DISK_GET_MEDIA_TYPES	Obsolete. Use IOCTL_STORAGE_GET_MEDIA_TYPES
IOCTL_DISK_GET_PARTITION_INFO	Obtains disk partition information.
IOCTL_DISK_LOAD_MEDIA	Obsolete. Use IOCTL_STORAGE_LOAD_MEDIA
IOCTL_DISK_MEDIA_REMOVAL	Obsolete. Use IOCTL_STORAGE_MEDIA_REMOVAL
IOCTL_DISK_PERFORMANCE	Provides disk performance information.
IOCTL_DISK_REASSIGN_BLOCKS	Maps disk blocks to spare-block pool.
IOCTL_DISK_SET_DRIVE_LAYOUT	Partitions a disk.
IOCTL_DISK_SET_PARTITION_INFO	Sets the disk partition type.
IOCTL_DISK_VERIFY	Performs logical format of a disk extent.
IOCTL_SERIAL_LSRMST_INSERT	Enables or disables placement of a line and modem status data into the data stream.
IOCTL_STORAGE_CHECK_VERIFY	Checks for change in a removable-media device.
IOCTL_STORAGE_EJECT_MEDIA	Ejects media from a SCSI device.
IOCTL_STORAGE_GET_MEDIA_TYPES	Obtains information about media support.
IOCTL_STORAGE_LOAD_MEDIA	Loads media into a device.
IOCTL_STORAGE_MEDIA_REMOVAL	Enables or disables the media eject mechanism.
For more detailed information on each control code, see its topic. In particular, each topic provides details on the usage of the lpInBuffer, nInBufferSize, lpOutBuffer, nOutBufferSize, and lpBytesReturned parameters.

lpInBuffer

Pointer to a buffer that contains the data required to perform the operation.

This parameter can be NULL if the dwIoControlCode parameter specifies an operation that does not require input data.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer.

lpOutBuffer

Pointer to a buffer that receives the operation’s output data.

This parameter can be NULL if the dwIoControlCode parameter specifies an operation that does not produce output data.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer.

lpBytesReturned

Pointer to a variable that receives the size, in bytes, of the data stored into the buffer pointed to by lpOutBuffer.

If lpOverlapped is NULL, lpBytesReturned cannot be NULL. Even when an operation produces no output data, and lpOutBuffer can be NULL, the DeviceIoControl function makes use of the variable pointed to by lpBytesReturned. After such an operation, the value of the variable is without meaning.

If lpOverlapped is not NULL, lpBytesReturned can be NULL. If this is an overlapped operation, you can get the number of bytes returned by calling GetOverlappedResult. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling GetQueuedCompletionStatus.

lpOverlapped

Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, this parameter must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, this parameter is ignored and the DeviceIoControl function does not return until the operation has been completed, or an error occurs.

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.

Remarks

If hDevice was opened with FILE_FLAG_OVERLAPPED and the lpOverlapped parameter points to an OVERLAPPED structure, DeviceIoControl is performed as an overlapped (asynchronous) operation. In this case, the OVERLAPPED structure must contain a handle to a manual-reset event object created by a call to the CreateEvent function. For more information on manual-reset event objects, see Synchronization.

If the overlapped operation cannot be completed immediately, the function returns FALSE, and GetLastError returns ERROR_IO_PENDING, indicating that the operation is executing in the background. When this happens, the operating system sets the event object in the OVERLAPPED structure to the nonsignaled state before DeviceIoControl returns. The system then sets the event object to the signaled state when the operation has been completed. The calling thread can use any of the wait functions to wait for the event object to be signaled, and then use the GetOverlappedResult function to determine the results of the operation. The GetOverlappedResult function reports the success or failure of the operation and the number of bytes returned in the lpOutBuffer buffer.

See Also

CreateEvent, CreateFile, GetOverlappedResult, GetQueuedCompletionStatus, OVERLAPPED


DialogBox

The DialogBox macro creates a modal dialog box from a dialog box template resource. DialogBox does not return control until the specified callback function terminates the modal dialog box by calling the EndDialog function. The DialogBox macro uses the DialogBoxParam function.

int DialogBox(

HINSTANCE hInstance,	// handle to application instance
LPCTSTR lpTemplate,	// identifies dialog box template
HWND hWndParent,	// handle to owner window
DLGPROC lpDialogFunc	// pointer to dialog box procedure
);
Parameters

hInstance

Identifies an instance of the module whose executable file contains the dialog box template.

lpTemplate

Identifies the dialog box template. This parameter is either the pointer to a null-terminated character string that specifies the name of the dialog box template or an integer value that specifies the resource identifier of the dialog box template. If the parameter specifies a resource identifier, its high-order word must be zero and its low-order word must contain the identifier. You can use the MAKEINTRESOURCE macro to create this value.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Points to the dialog box procedure. For more information about the dialog box procedure, see the DialogProc callback function.

Return Values

If the function succeeds, the return value is the nResult parameter in the call to the EndDialog function used to terminate the dialog box.

If the function fails, the return value is −1.

Remarks

The DialogBox macro uses the CreateWindowEx function to create the dialog box. DialogBox then sends a WM_INITDIALOG message (and a WM_SETFONT message if the template specifies the DS_SETFONT style) to the dialog box procedure. The function displays the dialog box (regardless of whether the template specifies the WS_VISIBLE style), disables the owner window, and starts its own message loop to retrieve and dispatch messages for the dialog box.

When the dialog box procedure calls the EndDialog function, DialogBox destroys the dialog box, ends the message loop, enables the owner window (if previously enabled), and returns the nResult parameter specified by the dialog box procedure when it called EndDialog.

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

CreateDialog, CreateWindowEx, DialogBoxIndirect, DialogBoxIndirectParam, DialogBoxParam, DialogProc, EndDialog, MAKEINTRESOURCE, WM_INITDIALOG, WM_SETFONT


DialogBoxIndirect

The DialogBoxIndirect macro creates a modal dialog box from a dialog box template in memory. DialogBoxIndirect does not return control until the specified callback function terminates the modal dialog box by calling the EndDialog function. The DialogBoxIndirect macro uses the DialogBoxIndirectParam function.

int DialogBoxIndirect(

HINSTANCE hInstance,	// handle to application instance
LPDLGTEMPLATE lpTemplate,	// identifies dialog box template
HWND hWndParent,	// handle to owner window
DLGPROC lpDialogFunc	// pointer to dialog box procedure
);
Parameters

hInstance

Identifies the instance of the module that creates the dialog box.

lpTemplate

Pointer to a global memory object containing a template that DialogBoxIndirect uses to create the dialog box. A dialog box template consists of a header that describes the dialog box, followed by one or more additional blocks of data that describe each of the controls in the dialog box. The template can use either the standard format or the extended format.

In a standard template for a dialog box, the header is a DLGTEMPLATE structure followed by additional variable-length arrays. The data for each control consists of a DLGITEMTEMPLATE structure followed by additional variable-length arrays.

In an extended template for a dialog box, the header uses the DLGTEMPLATEEX format and the control definitions use the DLGITEMTEMPLATEEX format.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Pointer to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.

Return Values

If the function succeeds, the return value is the nResult parameter specified in the call to the EndDialog function that was used to terminate the dialog box.

If the function fails, the return value is −1.

Remarks

The DialogBoxIndirect macro uses the CreateWindowEx function to create the dialog box. DialogBoxIndirect then sends a WM_INITDIALOG message to the dialog box procedure. If the template specifies the DS_SETFONT style, the function also sends a WM_SETFONT message to the dialog box procedure. The function displays the dialog box (regardless of whether the template specifies the WS_VISIBLE style), disables the owner window, and starts its own message loop to retrieve and dispatch messages for the dialog box.

When the dialog box procedure calls the EndDialog function, DialogBoxIndirect destroys the dialog box, ends the message loop, enables the owner window (if previously enabled), and returns the nResult parameter specified by the dialog box procedure when it called EndDialog.

In a standard dialog box template, the DLGTEMPLATE structure and each of the DLGITEMTEMPLATE structures must be aligned on DWORD boundaries. The creation data array that follows a DLGITEMTEMPLATE structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must must be aligned on WORD boundaries.

In an extended dialog box template, the DLGTEMPLATEEX header and each of the DLGITEMTEMPLATEEX control definitions must be aligned on DWORD boundaries. The creation data array, if any, that follows a DLGITEMTEMPLATEEX structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must be aligned on WORD boundaries.

All character strings in the dialog box template, such as titles for the dialog box and buttons, must be Unicode strings. To create code that works on both Windows NT and Windows 95, use the MultiByteToWideChar function to generate these Unicode strings.

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

CreateWindowEx, DialogBox, DialogBoxIndirectParam, DialogBoxParam, DialogProc, DLGITEMTEMPLATE, DLGITEMTEMPLATEEX, DLGTEMPLATE, DLGTEMPLATEEX, EndDialog, MultiByteToWideChar, WM_INITDIALOG, WM_SETFONT


DialogBoxIndirectParam

The DialogBoxIndirectParam function creates a modal dialog box from a dialog box template in memory. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.

int DialogBoxIndirectParam(

HINSTANCE hInstance,	// handle to application instance
LPCDLGTEMPLATE hDialogTemplate,	// identifies dialog box template
HWND hWndParent,	// handle to owner window
DLGPROC lpDialogFunc,	// pointer to dialog box procedure
LPARAM dwInitParam	// initialization value
);
Parameters

hInstance

Identifies the instance of the module that creates the dialog box.

hDialogTemplate

Pointer to a global memory object containing a template that DialogBoxIndirectParam uses to create the dialog box. A dialog box template consists of a header that describes the dialog box, followed by one or more additional blocks of data that describe each of the controls in the dialog box. The template can use either the standard format or the extended format.

In a standard template for a dialog box, the header is a DLGTEMPLATE structure followed by additional variable-length arrays. The data for each control consists of a DLGITEMTEMPLATE structure followed by additional variable-length arrays.

In an extended template for a dialog box, the header uses the DLGTEMPLATEEX format and the control definitions use the DLGITEMTEMPLATEEX format.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Pointer to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.

dwInitParam

Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.

Return Values

If the function succeeds, the return value is the nResult parameter specified in the call to the EndDialog function that was used to terminate the dialog box.

If the function fails, the return value is −1.

Remarks

The DialogBoxIndirectParam function uses the CreateWindowEx function to create the dialog box. DialogBoxIndirectParam then sends a WM_INITDIALOG message to the dialog box procedure. If the template specifies the DS_SETFONT style, the function also sends a WM_SETFONT message to the dialog box procedure. The function displays the dialog box (regardless of whether the template specifies the WS_VISIBLE style), disables the owner window, and starts its own message loop to retrieve and dispatch messages for the dialog box.


When the dialog box procedure calls the EndDialog function, DialogBoxIndirectParam destroys the dialog box, ends the message loop, enables the owner window (if previously enabled), and returns the nResult parameter specified by the dialog box procedure when it called EndDialog.

In a standard dialog box template, the DLGTEMPLATE structure and each of the DLGITEMTEMPLATE structures must be aligned on DWORD boundaries. The creation data array that follows a DLGITEMTEMPLATE structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must must be aligned on WORD boundaries.

In an extended dialog box template, the DLGTEMPLATEEX header and each of the DLGITEMTEMPLATEEX control definitions must be aligned on DWORD boundaries. The creation data array, if any, that follows a DLGITEMTEMPLATEEX structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must be aligned on WORD boundaries.

All character strings in the dialog box template, such as titles for the dialog box and buttons, must be Unicode strings. To create code that works on both Windows NT and Windows 95, use the MultiByteToWideChar function to generate these Unicode strings.

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

CreateWindowEx, DialogBox, DialogBoxIndirect, DialogBoxParam, DialogProc, DLGITEMTEMPLATE, DLGITEMTEMPLATEEX, DLGTEMPLATE, DLGTEMPLATEEX, EndDialog, MultiByteToWideChar, WM_INITDIALOG, WM_SETFONT


DialogBoxParam

The DialogBoxParam function creates a modal dialog box from a dialog box template resource. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.

int DialogBoxParam(

HINSTANCE hInstance,	// handle to application instance
LPCTSTR lpTemplateName,	// identifies dialog box template
HWND hWndParent,	// handle to owner window
DLGPROC lpDialogFunc,	// pointer to dialog box procedure
LPARAM dwInitParam	// initialization value
);
Parameters

hInstance

Identifies an instance of the module whose executable file contains the dialog box template.

lpTemplateName

Identifies the dialog box template. This parameter is either the pointer to a null-terminated character string that specifies the name of the dialog box template or an integer value that specifies the resource identifier of the dialog box template. If the parameter specifies a resource identifier, its high-order word must be zero and its low-order word must contain the identifier. You can use the MAKEINTRESOURCE macro to create this value.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Points to the dialog box procedure. For more information about the dialog box procedure, see the DialogProc callback function.

dwInitParam

Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.

Return Values

If the function succeeds, the return value is the value of the nResult parameter specified in the call to the EndDialog function used to terminate the dialog box.

If the function fails, the return value is −1.

Remarks

The DialogBoxParam function uses the CreateWindowEx function to create the dialog box. DialogBoxParam then sends a WM_INITDIALOG message (and a WM_SETFONT message if the template specifies the DS_SETFONT style) to the dialog box procedure. The function displays the dialog box (regardless of whether the template specifies the WS_VISIBLE style), disables the owner window, and starts its own message loop to retrieve and dispatch messages for the dialog box.

When the dialog box procedure calls the EndDialog function, DialogBoxParam destroys the dialog box, ends the message loop, enables the owner window (if previously enabled), and returns the nResult parameter specified by the dialog box procedure when it called EndDialog.

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

CreateWindowEx, DialogBox, DialogBoxIndirect, DialogBoxIndirectParam, DialogProc, EndDialog, MAKEINTRESOURCE, WM_INITDIALOG, WM_SETFONT


DialogProc

The DialogProc function is an application-defined callback function that processes messages sent to a modal or modeless dialog box.

BOOL CALLBACK DialogProc(

HWND hwndDlg,	// handle to dialog box
UINT uMsg,	// message
WPARAM wParam,	// first message parameter
LPARAM lParam	// second message parameter
);
Parameters

hwndDlg

Identifies the dialog box.

uMsg

Specifies the message.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Values

Except in response to the WM_INITDIALOG message, the dialog box procedure should return nonzero if it processes the message, and zero if it does not. In response to a WM_INITDIALOG message, the dialog box procedure should return zero if it calls the SetFocus function to set the focus to one of the controls in the dialog box. Otherwise, it should return nonzero, in which case the system sets the focus to the first control in the dialog box that can be given the focus.

Remarks

You should use the dialog box procedure only if you use the dialog box class for the dialog box. This is the default class and is used when no explicit class is specified in the dialog box template. Although the dialog box procedure is similar to a window procedure, it must not call the DefWindowProc function to process unwanted messages. Unwanted messages are processed internally by the dialog box window procedure.

DialogProc is a placeholder for the application-defined function name.

See Also

CreateDialog, CreateDialogIndirect, CreateDialogIndirectParam, CreateDialogParam, DefWindowProc, DialogBox, DialogBoxIndirect, DialogBoxIndirectParam, DialogBoxParam, SetFocus, WM_INITDIALOG


DisableThreadLibraryCalls

The DisableThreadLibraryCalls function disables the DLL_THREAD_ATTACH and DLL_THREAD_DETACH notifications for the dynamic-link library (DLL) specified by hLibModule. This can reduce the size of the working code set for some applications.

BOOL DisableThreadLibraryCalls(

HMODULE hLibModule	// dynamic-link library for which calls are to be disabled
);
Parameters

hLibModule

Specifies the dynamic-link library module for which the DLL_THREAD_ATTACH and DLL_THREAD_DETACH notifications are to be disabled.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. The DisableThreadLibraryCalls function fails if the DLL specified by hLibModule has active static thread local storage, or if hLibModule is an invalid module handle. To get extended error information, call GetLastError.

Remarks

The DisableThreadLibraryCalls function lets a DLL disable the DLL_THREAD_ATTACH and DLL_THREAD_DETACH notification calls. This can be a useful optimization for multithreaded applications that have many DLLs, frequently create and delete threads, and whose DLLs do not need these thread-level notifications of attachment/detachment. A remote procedure call (RPC) server application is an example of such an application. In these sorts of applications, DLL initialization routines often remain in memory to service DLL_THREAD_ATTACH and DLL_THREAD_DETACH notifications. By disabling the notifications, the DLL initialization code is not paged in because a thread is created or deleted, thus reducing the size of the application’s working code set. To implement the optimization, modify a DLL’s DLL_PROCESS_ATTACH code to call DisableThreadLibraryCalls.

See Also

FreeLibraryAndExitThread


DisconnectNamedPipe

The DisconnectNamedPipe function disconnects the server end of a named pipe instance from a client process.

BOOL DisconnectNamedPipe(

HANDLE hNamedPipe	// handle to named pipe
);
Parameters

hNamedPipe

Identifies an instance of a named pipe. This handle must be created by the CreateNamedPipe 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.

Remarks

If the client end of the named pipe is open, the DisconnectNamedPipe function forces that end of the named pipe closed. The client receives an error the next time it attempts to access the pipe. A client that is forced off a pipe by DisconnectNamedPipe must still use the CloseHandle function to close its end of the pipe.

When the server process disconnects a pipe instance, any unread data in the pipe is discarded. Before disconnecting, the server can make sure data is not lost by calling the FlushFileBuffers function, which does not return until the client process has read all the data.

The server process must call DisconnectNamedPipe to disconnect a pipe handle from its previous client before the handle can be connected to another client by using the ConnectNamedPipe function.

See Also

CloseHandle, ConnectNamedPipe, CreateNamedPipe, FlushFileBuffers


DispatchMessage

The DispatchMessage function dispatches a message to a window procedure. It is typically used to dispatch a message retrieved by the GetMessage function.

LONG DispatchMessage(

CONST MSG *lpmsg	// pointer to structure with message
);
Parameters

lpmsg

Points to an MSG structure that contains the message.

Return Values

The return value specifies the value returned by the window procedure. Although its meaning depends on the message being dispatched, the return value generally is ignored.

Remarks

The MSG structure must contain valid message values. If the lpmsg parameter points to a WM_TIMER message and the lParam parameter of the WM_TIMER message is not NULL, lParam points to a function that is called instead of the window procedure.

See Also

GetMessage, MSG, PeekMessage, PostAppMessage, PostMessage, TranslateMessage, WM_TIMER


DlgDirList

The DlgDirList function fills the specified list box with the names of all files matching the specified path or filename.

int DlgDirList(

HWND hDlg,	// handle to dialog box with list box
LPTSTR lpPathSpec,	// pointer to path or filename string
int nIDListBox,	// identifier of list box
int nIDStaticPath,	// identifier of static control
UINT uFileType	// file attributes to display
);
Parameters

hDlg

Identifies the dialog box that contains the list box.

lpPathSpec

Points to a null-terminated string that contains the path or filename. DlgDirList modifies this string, which should be long enough to contain the modifications. For more information about this parameter, see the Remarks section.

nIDListBox

Specifies the identifier of a list box. If this parameter is zero, DlgDirList assumes that no list box exists and does not attempt to fill one.

nIDStaticPath

Specifies the identifier of the static control used for displaying the current drive and directory. If this parameter is zero, DlgDirList assumes that no such control is present.

uFileType

Specifies attributes of the filenames to be displayed. This parameter must be one or more of the following values:

Value	Description
DDL_ARCHIVE	Includes archived files.
DDL_DIRECTORY	Includes subdirectories. Subdirectory names are enclosed in square brackets ([ ]).
DDL_DRIVES	Includes drives. Drives are listed in the form [-x-], where x is the drive letter.
DDL_EXCLUSIVE	Includes only files with the specified attributes. By default, read-write files are listed even if DDL_READWRITE is not specified.
DDL_HIDDEN	Includes hidden files.
DDL_READONLY	Includes read-only files.
DDL_READWRITE	Includes read-write files with no additional attributes.
DDL_SYSTEM	Includes system files.
DDL_POSTMSGS	Posts messages to the application’s message queue. By default, DlgDirList sends messages directly to the dialog box procedure.
Return Values

If a listing is made — even an empty listing — the return value is nonzero. If the input string does not contain a valid search path, the return value is zero.

Remarks

If you specify a zero-length string for the lpPathSpec parameter or if you specify only a directory name with no filename, the string will be changed to *.*

The lpPathSpec parameter has the following form:

[drive:] [[\u]directory[\idirectory]\u] [filename]

In this example, drive is a drive letter, directory is a valid directory name, and filename is a valid filename that must contain at least one wildcard (? or *).

If lpPathSpec includes a drive or directory name, or both, the current drive and directory are changed to the specified drive and directory before the list box is filled. The static control identified by the nIDStaticPath parameter is also updated with the new drive or directory name, or both.

After the list box is filled, DlgDirList updates lpPathSpec by removing the drive or directory portion, or both, of the path and filename.

DlgDirList sends the LB_RESETCONTENT and LB_DIR messages to the list box.

See Also

DlgDirListComboBox, DlgDirSelectComboBoxEx, DlgDirSelectEx


DlgDirListComboBox

The DlgDirListComboBox function fills the specified combo box with a directory listing. It fills the list with the names of all files, drives, and subdirectories that match the specified attributes and path string.

int DlgDirListComboBox(

HWND hDlg,	// handle to dialog box with combo box
LPTSTR lpPathSpec,	// pointer to path or filename string
int nIDComboBox,	// identifier of combo box
int nIDStaticPath,	// identifier of static control
UINT uFiletype	// file attributes to display
);
Parameters

hDlg

Identifies the dialog box that contains the combo box.

lpPathSpec

Points to a null-terminated string of the following form:

[drive:][\]][directory\[...]][filename]

If the specified string includes a drive or directory path, the DlgDirListComboBox function changes the current drive and directory before filling the list. After the list is filled, the drive and directory path are removed from the string specified by the lpPathSpec parameter.

nIDComboBox

Specifies the identifier of a combo box control in a dialog box. If nIDComboBox is zero, the DlgDirListComboBox function assumes no combo box exists and does not attempt to fill it.

nIDStaticPath

Specifies the identifier of the static text control in which the DlgDirListComboBox function is to display the current directory. If nIDStaticPath is zero, DlgDirListComboBox assumes no such control is present.

uFiletype

Specifies the attributes of the files to be displayed. It can be any combination of the following values:

Value	Meaning
DDL_ARCHIVE	Includes archived files.
DDL_DIRECTORY	Includes subdirectories. Subdirectory names are enclosed in square brackets ([ ]).
DDL_DRIVES	Includes drives. Drives are listed in the form [-x-], where x is the drive letter.
DDL_EXCLUSIVE	Includes only files with the specified attributes. By default, read-write files are listed even if DDL_READWRITE is not specified.
DDL_HIDDEN	Includes hidden files.
DDL_READONLY	Includes read-only files.
DDL_READWRITE	Includes read-write files with no additional attributes.
DDL_SYSTEM	Includes system files.
DDL_POSTMSGS	Posts messages to the application’s message queue. By default, the DlgDirList function sends messages directly to the dialog box procedure.
Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. For example, if the string specified by lpPathSpec is not a valid path, the function fails. To get extended error information, call GetLastError.

Remarks

If the lpszPathSpec parameter points to a zero-length string or to a string specifying a drive, directory, or both — but no filename — the filename *.* (wildcards) is assumed.

Windows NT:

The directory listing displays long filenames, if any.

Windows 95:

The directory listing displays short filenames (the 8.3 form). You can use the SHGetFileInfo or GetFullPathName functions to get the corresponding long filename.

See Also

DlgDirList, DlgDirSelectComboBoxEx, GetFullPathName, SHGetFileInfo


DlgDirSelectComboBoxEx

The DlgDirSelectComboBoxEx function retrieves the current selection from a combo box filled by using the DlgDirListComboBox function. The selection is interpreted as a drive letter, a file, or a directory name.

BOOL DlgDirSelectComboBoxEx(

HWND hDlg,	// handle to dialog box with list box
LPTSTR lpString,	// pointer to buffer for path string
int nCount,	// number of characters in path string
int nIDComboBox	// identifier of combo box
);
Parameters

hDlg

Identifies the dialog box that contains the combo box.

lpString

Points to the buffer that is to receive the selected path.

nCount

Specifies the length, in characters, of the buffer pointed to by the lpString parameter.

nIDComboBox

Specifies the integer identifier of the combo box control in the dialog box.

Return Values

If the current selection is a directory name, the return value is nonzero.

If the current selection is not a directory name, the return value is zero. To get extended error information, call GetLastError.

Remarks

If the current selection specifies a directory name or drive letter, the DlgDirSelectComboBoxEx function removes the enclosing square brackets (and hyphens for drive letters) so the name or letter is ready to be inserted into a new path or filename. If there is no selection, the contents of the buffer pointed to by lpString do not change.

The DlgDirSelectComboBox function does not allow more than one filename to be returned from a combo box.

DlgDirSelectComboBoxEx sends CB_GETCURSEL and CB_GETLBTEXT messages to the combo box.

In the Win32 API, you can use this function with all three types of combo boxes (CBS_SIMPLE, CBS_DROPDOWN, and CBS_DROPDOWNLIST).

See Also

CB_GETCURSEL, CB_GETLBTEXT, DlgDirListComboBox, DlgDirSelectEx


DlgDirSelectEx

The DlgDirSelectEx function retrieves the current selection from a single-selection list box. It assumes that the list box has been filled by the DlgDirList function and that the selection is a drive letter, filename, or directory name.

BOOL DlgDirSelectEx(

HWND hDlg,	// handle to dialog box with list box
LPTSTR lpString,	// pointer to buffer for path string
int nCount,	// number of characters in path string
int nIDListBox	// identifier of list box
);
Parameters

hDlg

Identifies the dialog box that contains the list box.

lpString

Points to a buffer that is to receive the selected path.

nCount

Specifies the length, in characters, of the buffer pointed to by lpString.

nIDListBox

Specifies the integer identifier of a list box in the dialog box.

Return Values

If the current selection is a directory name, the return value is nonzero.

If the current selection is not a directory name, the return value is zero. To get extended error information, call GetLastError.

Remarks

The DlgDirSelectEx function copies the selection to the buffer pointed to by the lpString parameter. If the current selection is a directory name or drive letter, DlgDirSelectEx removes the enclosing square brackets (and hyphens, for drive letters), so that the name or letter is ready to be inserted into a new path. If there is no selection, lpString does not change.

DlgDirSelectEx sends LB_GETCURSEL and LB_GETTEXT messages to the list box. The function does not allow more than one filename to be returned from a list box. The list box must not be a multiple-selection list box. If it is, this function does not return a zero value and lpString remains unchanged.

See Also

DlgDirList, DlgDirListComboBox, DlgDirSelectComboBoxEx, LB_GETCURSEL, LB_GETTEXT


DllEntryPoint

The DllEntryPoint function is an optional method of entry into a dynamic-link library (DLL). If the function is used, it is called by the system when processes and threads are initialized and terminated, or upon calls to the LoadLibrary and FreeLibrary functions. DllEntryPoint is a placeholder for the library-defined function name. The actual name must be specified at build time. For more information, see the documentation included with your development tools.

BOOL WINAPI DllEntryPoint(

HINSTANCE hinstDLL,	// handle to DLL module
DWORD fdwReason,	// reason for calling function
LPVOID lpvReserved	// reserved
);
Parameters

hinstDLL

A handle to the DLL. The value is the base address of the DLL. The HINSTANCE of a DLL is the same as the HMODULE of the DLL, so hinstDLL can be used in subsequent calls to the GetModuleFileName function and other functions that require a module handle.

fdwReason

Specifies a flag indicating why the DLL entry-point function is being called. This parameter can be one of the following values:

Value	Meaning
DLL_PROCESS_ATTACH
	Indicates that the DLL is attaching to the address space of the current process as a result of the process starting up or as a result of a call to LoadLibrary. DLLs can use this opportunity to initialize any instance data or to use the TlsAlloc function to allocate a thread local storage (TLS) index.
	During initial process startup or after a call to LoadLibrary, the operating system scans the list of loaded DLLs for the process. For each DLL that has not already been called with the DLL_PROCESS_ATTACH value, the system calls the DLL’s entry-point function. This call is made in the context of the thread that caused the process address space to change, such as the primary thread of the process or the thread that called LoadLibrary.
DLL_THREAD_ATTACH
	Indicates that the current process is creating a new thread. When this occurs, the system calls the entry-point function of all DLLs currently attached to the process. The call is made in the context of the new thread. DLLs can use this opportunity to initialize a TLS slot for the thread. A thread calling the DLL entry-point function with the DLL_PROCESS_ATTACH value does not call the DLL entry-point function with the DLL_THREAD_ATTACH value.
	Note that a DLL’s entry-point function is called with this value only by threads created after the DLL is attached to the process. When a DLL is attached by LoadLibrary, existing threads do not call the entry-point function of the newly loaded DLL.
DLL_THREAD_DETACH
	Indicates that a thread is exiting cleanly. If the DLL has stored a pointer to allocated memory in a TLS slot, it uses this opportunity to free the memory. The operating system calls the entry-point function of all currently loaded DLLs with this value. The call is made in the context of the exiting thread. There are cases in which the entry-point function is called for a terminating thread even if the DLL never attached to the thread — for example, the entry-point function was never called with the DLL_THREAD_ATTACH value in the context of the thread in either of these two situations: • The thread was the initial thread in the process, so the system called the entry-point function with the DLL_PROCESS_ATTACH value.  • The thread was already running when a call to the LoadLibrary function was made, so the system never called the entry-point function for it.
DLL_PROCESS_DETACH
	Indicates that the DLL is detaching from the address space of the calling process as a result of either a clean process exit or of a call to FreeLibrary. The DLL can use this opportunity to call the TlsFree function to free any TLS indices allocated by using TlsAlloc and to free any thread local data. When a DLL detaches from a process as a result of process termination or as a result of a call to FreeLibrary, the operating system does not call the DLL’s entry-point function with the DLL_THREAD_DETACH value for the individual threads of the process. The DLL is only given DLL_PROCESS_DETACH notification. DLLs can take this opportunity to clean up all resources for all threads attached and known to the DLL.
lpvReserved

Specifies further aspects of DLL initialization and cleanup.

If fdwReason is DLL_PROCESS_ATTACH, lpvReserved is NULL for dynamic loads and non-NULL for static loads.

If fdwReason is DLL_PROCESS_DETACH, lpvReserved is NULL if DllEntryPoint has been called by using FreeLibrary and non-NULL if DllEntryPoint has been called during process termination.

Return Values

When the system calls the DllEntryPoint function with the DLL_PROCESS_ATTACH value, the function returns TRUE if it succeeds or FALSE if initialization fails. If the return value is FALSE when DllEntryPoint is called because the process uses the LoadLibrary function, LoadLibrary returns NULL. If the return value is FALSE when DllEntryPoint is called during process initialization, the process terminates with an error. To get extended error information, call GetLastError.

When the system calls the DllEntryPoint function with any value other than DLL_PROCESS_ATTACH, the return value is ignored.

See Also

FreeLibrary, GetModuleFileName, LoadLibrary, TlsAlloc, TlsFree


DocumentProperties

The DocumentProperties function retrieves or modifies printer initialization information or displays a printer-configuration dialog box for the specified printer.

LONG DocumentProperties(

HWND hWnd,	// handle to window that displays dialog box
HANDLE hPrinter,	// handle to printer object
LPTSTR pDeviceName,	// pointer to device name
PDEVMODE pDevModeOutput,	// pointer to modified device mode structure
PDEVMODE pDevModeInput,	// pointer to original device mode structure
DWORD fMode	// mode flag
);
Parameters

hWnd

Identifies the parent window of the printer-configuration dialog box.

hPrinter

Identifies a printer object.

pDeviceName

Points to a null-terminated string that specifies the name of the device for which the printer-configuration dialog box should be displayed.

pDevModeOutput

Points to a DEVMODE structure that receives the printer configuration data specified by the user.

pDevModeInput

Pointer to a DEVMODE structure that the operating system uses to initialize the dialog box controls.

This parameter is only used if the DM_IN_BUFFER flag is set in the fMode parameter. If DM_IN_BUFFER is not set, the operating system uses the printer’s default DEVMODE.

fMode

Specifies a mask of values that determines the operations the function performs. If this parameter is zero, the DocumentProperties function returns the number of bytes required by the printer driver’s DEVMODE data structure. Otherwise, use one or more of the following constants to construct a value for this parameter; note, however, that in order to change the print settings, an application must specify at least one input value and one output value:

Value	Meaning
DM_IN_BUFFER	Input value. Before prompting, copying, or updating, the function merges the printer driver’s current print settings with the settings in the DEVMODE structure specified by the pDevModeInput parameter. The function updates the structure only for those members specified by the DEVMODE structure’s dmFields member. This value is also defined as DM_MODIFY. In cases of conflict during the merge, the settings in the DEVMODE structure specified by pDevModeInput override the printer driver’s current print settings.
DM_IN_PROMPT	Input value. The function presents the printer driver’s Print Setup dialog box and then changes the settings in the printer’s DEVMODE data structure to those values specified by the user. This value is also defined as DM_PROMPT.
DM_OUT_BUFFER	Output value. The function writes the printer driver’s current print settings, including private data, to the DEVMODE data structure specified by the pDevModeOutput parameter. The caller must allocate a buffer sufficiently large to contain the information. If the bit DM_OUT_BUFFER sets is clear, the pDevModeOutput parameter can be NULL. This value is also defined as DM_COPY.
Return Values

If the fMode parameter is zero, the return value is the size of the buffer required to contain the printer driver initialization data. Note that this buffer can be larger than a DEVMODE structure if the printer driver appends private data to the structure.

If the function displays the initialization dialog box, the return value is either IDOK or IDCANCEL, depending on which button the user selects.

If the function does not display the dialog box and is successful, the return value is IDOK.

If the function fails, the return value is less than zero.

Remarks

The printer object handle identified by the hPrinter parameter can be obtained by calling the OpenPrinter function.

The string pointed to by the pDeviceName parameter can be obtained by calling the GetPrinter function.

Note that the DEVMODE structure actually used by a printer driver contains the device-independent part (as defined above) followed by a driver-specific part that varies in size and content with each driver and driver version. Because of this driver dependence, it is very important for applications to query the driver for the correct size of the DEVMODE structure before allocating a buffer for it.

To make changes to print settings that are local to an application, an application should follow these steps:

1.	Get the number of bytes required for the full DEVMODE structure by calling DocumentProperties and specifying zero in the fMode parameter.

2.	Allocate memory for the full DEVMODE structure.

3.	Get the current printer settings by calling DocumentProperties. Pass a pointer to the DEVMODE structure allocated in Step 2 as the pDevModeOutput parameter and specify the DM_OUT_BUFFER value.

4.	Modify the appropriate members of the returned DEVMODE structure and indicate which members were changed by setting the corresponding bits in the dmFields member of the DEVMODE.

5.	Call DocumentProperties and pass the modified DEVMODE structure back as both the pDevModeInput and pDevModeOutput parameters and specify both the DM_IN_BUFFER and DM_OUT_BUFFER values (which are combined using the OR operator).

The DEVMODE structure returned by the third call to DocumentProperties can be used as an argument in a call to the CreateDC function.

To create a handle to a printer-device context using the current printer settings, you only need to call DocumentProperties twice, as described above. The first call gets the size of the full DEVMODE and the second call initializes the DEVMODE with the current printer settings. Pass the initialized DEVMODE to CreateDC to obtain the handle to the printer device context.

See Also

AdvancedDocumentProperties, CreateDC, DEVMODE, GetPrinter, OpenPrinter


DosDateTimeToFileTime

The DosDateTimeToFileTime function converts MS-DOS date and time values to a 64-bit file time.

BOOL DosDateTimeToFileTime(

WORD wFatDate,	// 16-bit MS-DOS date
WORD wFatTime,	// 16-bit MS-DOS time
LPFILETIME lpFileTime	// pointer to buffer for 64-bit file time
);
Parameters

wFatDate

Specifies the MS-DOS date. The date is a packed 16-bit value with the following format:

Bits	Contents
0−4	Day of the month (1−31)
5−8	Month (1 = January, 2 = February, and so on)
9−15	Year offset from 1980 (add 1980 to get actual year)
wFatTime

Specifies the MS-DOS time. The time is a packed 16-bit value with the following format:

Bits	Contents
0−4	Second divided by 2
5−10	Minute (0−59)
11−15	Hour (0−23 on a 24-hour clock)
lpFileTime

Points to a FILETIME structure to receive the converted 64-bit file time.

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.

See Also

FILETIME, FileTimeToDosDateTime, FileTimeToSystemTime, SystemTimeToFileTime


DPtoLP

The DPtoLP function converts device coordinates into logical coordinates. The conversion depends on the mapping mode of the device context, the settings of the origins and extents for the window and viewport, and the world transformation.

BOOL DPtoLP(

HDC hdc,	// handle to device context
LPPOINT lpPoints,	// pointer to array of points
int nCount	// count of points
);
Parameters

hdc

Identifies the device context.

lpPoints

Points to an array of POINT structures. The x- and y-coordinates contained in each POINT structure will be transformed.

nCount

Specifies the number of points in the array.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The DPtoLP function fails if the device coordinates exceed 27 bits, or if the converted logical coordinates exceed 32 bits. In the case of such an overflow, the results for all the points are undefined.

See Also

LPtoDP, POINT


DragAcceptFiles

The DragAcceptFiles function registers whether a window accepts dropped files.

VOID DragAcceptFiles(

HWND hWnd,	// handle to the registering window
BOOL fAccept	// acceptance option
);
Parameters

hWnd

Identifies the window registering whether it accepts dropped files.

fAccept

Specifies whether the window identified by the hWnd parameter accepts dropped files. This value is TRUE to accept dropped files; it is FALSE to discontinue accepting dropped files.

Return Values

This function does not return a value.

Remarks

An application that calls DragAcceptFiles with the fAccept parameter set to TRUE has identified itself as able to process the WM_DROPFILES message from File Manager.

See Also

WM_DROPFILES


DragDetect [Now Supported on Windows NT]
DragDetect

[Now Supported on Windows NT]

The DragDetect function captures the mouse and tracks its movement until the user releases the left button, presses the ESC key, or moves the mouse outside the “drag rectangle” around the specified point. The width and height of the drag rectangle are specified by the SM_CXDRAG and SM_CYDRAG values returned by the GetSystemMetrics function.

BOOL DragDetect(

HWND hwnd,
POINT pt
);
Parameters

hwnd

Handle to the window receiving mouse input.

pt

Initial position of the mouse, in screen coordinates. The function determines the coordinates of the drag rectangle by using this point.

Return Values

If the user moved the mouse outside of the drag rectangle while holding the left button down, the return value is nonzero.

If the user did not move the mouse outside of the drag rectangle while holding the left button down, the return value is zero.

Remarks

The system metrics for the drag rectangle are configurable, allowing for larger or smaller drag rectangles.

See Also

GetSystemMetrics


DragFinish

The DragFinish function releases memory that Windows allocated for use in transferring filenames to the application.

VOID DragFinish(

HDROP hDrop	// handle to memory to free
);
Parameters

hDrop

Identifies the structure describing dropped files. This handle is retrieved from the wParam parameter of the WM_DROPFILES message.

Return Values

This function does not return a value.

See Also

WM_DROPFILES


DragQueryFile

The DragQueryFile function retrieves the filenames of dropped files.

UINT DragQueryFile(

HDROP hDrop,	// handle to structure for dropped files
UINT iFile,	// index of file to query
LPTSTR lpszFile,	// buffer for returned filename
UINT cch	// size of buffer for filename
);
Parameters

hDrop

Identifies the structure containing the filenames of the dropped files.

iFile

Specifies the index of the file to query. If the value of the iFile parameter is 0xFFFFFFFF, DragQueryFile returns a count of the files dropped. If the value of the iFile parameter is between zero and the total number of files dropped, DragQueryFile copies the filename with the corresponding value to the buffer pointed to by the lpszFile parameter.

lpszFile

Points to a buffer to receive the filename of a dropped file when the function returns. This filename is a null-terminated string. If this parameter is NULL, DragQueryFile returns the required size, in characters, of the buffer.

cch

Specifies the size, in characters, of the lpszFile buffer.

Return Values

When the function copies a filename to the buffer, the return value is a count of the characters copied, not including the terminating null character.

If the index value is 0xFFFFFFFF, the return value is a count of the dropped files.

If the index value is between zero and the total number of dropped files and the lpszFile buffer address is NULL, the return value is the required size, in characters, of the buffer, not including the terminating null character.

See Also

DragQueryPoint


DragQueryPoint

The DragQueryPoint function retrieves the position of the mouse pointer at the time a file was dropped.

BOOL DragQueryPoint(

HDROP hDrop,	// handle to structure for dropped file
LPPOINT lppt	// pointer to structure for mouse coordinates
);
Parameters

hDrop

Identifies the structure describing the dropped file.

lppt

Points to a POINT structure that the function fills with the coordinates of the mouse pointer at the time the file was dropped.

Return Values

If the drop occurred in the client area of the window, the return value is nonzero.

If the drop did not occur in the client area of the window, the return value is zero.

Remarks

The DragQueryPoint function fills the POINT structure with the coordinates of the mouse pointer at the time the user released the left mouse button. The window for which coordinates are returned is the window that received the WM_DROPFILES message.

See Also

DragQueryFile, POINT, WM_DROPFILES


DrawAnimatedRects [Now Supported on Windows NT]
DrawAnimatedRects

[Now Supported on Windows NT]

The DrawAnimatedRects function draws a wire-frame rectangle and animates it to indicate the opening of an icon or the minimizing or maximizing of a window.

BOOL WINAPI DrawAnimatedRects(

HWND hwnd,	// handle to clipping window
int idAni,	// type of animation
CONST RECT *lprcFrom,	// pointer to rectangle coordinates (minimized)
CONST RECT *lprcTo	// pointer to rectangle coordinates (restored)
);
Parameters

hwnd

Handle to the window to which the rectangle is clipped. If this parameter is NULL, the working area of the screen is used.

idAni

This parameter is reserved and must be zero.

lprcFrom

Points to a SMALL_RECT structure specifying the location and size of the icon or minimized window. Coordinates are relative to the rectangle specified by the lprcClip parameter.

lprcTo

Points to a SMALL_RECT structure specifying the location and size of the restored window. Coordinates are relative to the rectangle specified by the lprcClip parameter.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

SMALL_RECT


DrawCaption [Now Supported on Windows NT]
DrawCaption

[Now Supported on Windows NT]

The DrawCaption function draws a window caption.

BOOL WINAPI DrawCaption(

HWND hwnd,	// handle to window to get text and icon from
HDC hdc,	// handle to device context to draw into
LPCRECT lprc,	// pointer to rectangle to draw into
UINT uFlags,	// set of drawing option flags
);
Parameters

hwnd

Handle to a window that supplies text and an icon for the window caption.

hdc

Handle to a device context. The function draws the window caption into this device context.

lprc

Pointer to a RECT structure that specifies the bounding rectangle for the window caption.

uFlags

A set of bit flags that specify drawing options. You can set zero or more of the following flags:

Value	Meaning
DC_ACTIVE	The function uses the colors that denote an active caption.
DC_ICON	The function draws the icon when drawing the caption text.
DC_INBUTTON	The function draws the caption as a button.
DC_SMALLCAP	The function draws a small caption, using the current small caption font.
DC_TEXT	The function draws the caption text when drawing the caption.
If DC_SMALLCAP is specified, the function draws a normal window caption.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

RECT


DrawEdge

The DrawEdge function draws one or more edges of rectangle.

BOOL DrawEdge(

HDC hdc,	// handle to device context
LPRECT qrc,	// pointer to rectangle coordinates
UINT edge,	// type of inner and outer edge to draw
UINT grfFlags	// type of border
);
Parameters

hdc

Identifies the device context.

qrc

Points to a RECT structure that contains the logical coordinates of the rectangle.edge

Specifies the type of inner and outer edge to draw. This parameter must be a combination of one inner-border flag and one outer-border flag. The inner-border flags are as follows:

Value	Meaning
BDR_RAISEDINNER	Raised inner edge.
BDR_SUNKENINNER	Sunken inner edge.
The outer-border flags are as follows:

Value	Meaning
BDR_RAISEDOUTER	Raised outer edge.
BDR_SUNKENOUTER	Sunken outer edge.
Alternatively, the edge parameter can specify one of the following flags:

Value	Meaning
EDGE_BUMP	Combination of BDR_RAISEDOUTER and BDR_SUNKENINNER.
EDGE_ETCHED	Combination of BDR_SUNKENOUTER and BDR_RAISEDINNER.
EDGE_RAISED	Combination of BDR_RAISEDOUTER and BDR_RAISEDINNER.
EDGE_SUNKEN	Combination of BDR_SUNKENOUTER and BDR_SUNKENINNER.
grfFlags

Specifies the type of border. This parameter can be a combination of these values:

Value	Meaning
BF_ADJUST	Rectangle to be adjusted to leave space for client area.
BF_BOTTOM	Bottom of border rectangle.
BF_BOTTOMLEFT	Bottom and left side of border rectangle.
BF_BOTTOMRIGHT	Bottom and right side of border rectangle.
BF_DIAGONAL	Diagonal border.
BF_DIAGONAL_ENDBOTTOMLEFT	Diagonal border. The end point is the bottom-left corner of the rectangle; the origin is top-right corner.
BF_DIAGONAL_ENDBOTTOMRIGHT	Diagonal border. The end point is the bottom-right corner of the rectangle; the origin is top-left corner.
BF_DIAGONAL_ENDTOPLEFT	Diagonal border. The end point is the top-left corner of the rectangle; the origin is bottom-right corner.
BF_DIAGONAL_ENDTOPRIGHT	Diagonal border. The end point is the top-right corner of the rectangle; the origin is bottom-left corner.
BF_FLAT	Flat border.
BF_LEFT	Left side of border rectangle.
BF_MIDDLE	Interior of rectangle to be filled.
BF_MONO	One-dimensional border.
BF_RECT	Entire border rectangle.
BF_RIGHT	Right side of border rectangle.
BF_SOFT	Soft buttons instead of tiles.
BF_TOP	Top of border rectangle.
BF_TOPLEFT	Top and left side of border rectangle.
BF_TOPRIGHT	Top and right side of border rectangle.
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.

See Also

RECT


DrawEscape

The DrawEscape function accesses drawing capabilities of a video display that are not directly available through the graphics device interface (GDI).

int DrawEscape(

HDC hdc,	// handle to device context
int nEscape,	// specifies escape function
int cbInput,	// size of structure for input
LPCSTR lpszInData	// pointer to structure for input
);
Parameters

hdc

Identifies the device context for the specified video display.

nEscape

Specifies the escape function to be performed.

cbInput

Specifies the number of bytes of data pointed to by the lpszInData parameter.

lpszInData

Points to the input structure required for the specified escape.

Return Values

The return value specifies the outcome of the function. It is greater than zero if the function is successful, except for the QUERYESCSUPPORT draw escape, which checks for implementation only. The return value is zero if the escape is not implemented. The return value is less than zero if an error occurred. To get extended error information, call GetLastError.

Remarks

When an application calls the DrawEscape function, the data identified by cbInput and lpszInData is passed directly to the specified display driver.


DrawFocusRect

The DrawFocusRect function draws a rectangle in the style used to indicate that the rectangle has the focus.

BOOL DrawFocusRect(

HDC hDC,	// handle to device context
CONST RECT *lprc	// pointer to structure for rectangle
);
Parameters

hDC

Identifies the device context.

lprc

Points to a RECT structure that specifies the logical coordinates of the rectangle.

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.

Remarks

Because DrawFocusRect is an XOR function, calling it a second time with the same rectangle removes the rectangle from the screen.

This function draws a rectangle that cannot be scrolled. To scroll an area containing a rectangle drawn by this function, call DrawFocusRect to remove the rectangle from the screen, scroll the area, and then call DrawFocusRect again to draw the rectangle in the new position.

See Also

FrameRect, RECT


DrawFrameControl

The DrawFrameControl function draws a frame control of the specified type and style.

BOOL DrawFrameControl(

HDC hdc,	// handle to device context
LPRECT lprc,	// pointer to bounding rectangle
UINT uType,	// frame-control type
UINT uState	// frame-control state
);
Parameters

hdc

Identifies the device context of the window in which to draw the control.

lprc

Points to a RECT structure that contains the logical coordinates of the bounding rectangle for frame control.

uType

Specifies the type of frame control to draw. This parameter can be one of the following values:

Value	Meaning
DFC_BUTTON	Standard button
DFC_CAPTION	Title bar
DCF_MENU	Menu
DFC_SCROLL	Scroll bar
uState

Specifies the initial state of the frame control. If uType is DFC_BUTTON, uState can be one of the following values:

Value	Meaning
DFCS_BUTTON3STATE	Three-state button
DFCS_BUTTONCHECK	Check box
DFCS_BUTTONPUSH	Push button
DFCS_BUTTONRADIO	Radio button
DFCS_BUTTONRADIOIMAGE	Image for radio button (nonsquare needs image)
DFCS_BUTTONRADIOMASK	Mask for radio button (nonsquare needs mask)
If uType is DFC_CAPTION, uState can be one of the following values:

Value	Meaning
DFCS_CAPTIONCLOSE	Close button
DFCS_CAPTIONHELP	Windows 95 only: Help button
DFCS_CAPTIONMAX	Maximize button
DFCS_CAPTIONMIN	Minimize button
DFCS_CAPTIONRESTORE	Restore button
If uType is DFC_MENU, uState can be one of the following values:

Value	Meaning
DFCS_MENUARROW	Submenu arrow
DFCS_MENUBULLET	Bullet
DFCS_MENUCHECK	Check mark
If uType is DFC_SCROLL, uState can be one of the following values:

Value	Meaning
DFCS_SCROLLCOMBOBOX	Combo box scroll bar
DFCS_SCROLLDOWN	Down arrow of scroll bar
DFCS_SCROLLLEFT	Left arrow of scroll bar
DFCS_SCROLLRIGHT	Right arrow of scroll bar
DFCS_SCROLLSIZEGRIP	Size grip in bottom-right corner of window
DFCS_SCROLLUP	Up arrow of scroll bar
The following style can be used to adjust the bounding rectangle of the push button:

Value	Meaning
DFCS_ADJUSTRECT	Bounding rectangle is adjusted to exclude the surrounding edge of the push button.
One or more of the following values can be used to set the state of the control to be drawn:

Value	Meaning
DFCS_CHECKED	Button is checked.
DFCS_FLAT	Button has a flat border.
DFCS_INACTIVE	Button is inactive (grayed).
DFCS_MONO	Button has a monochrome border.
DFCS_PUSHED	Button is pushed.
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.

See Also

RECT


DrawIcon

The DrawIcon function draws an icon in the client area of the window of the specified device context.

BOOL DrawIcon(

HDC hDC,	// handle to device context
int X,	// x-coordinate of upper-left corner
int Y,	// y-coordinate of upper-left corner
HICON hIcon	// handle to icon to draw
);
Parameters

hDC

Identifies the device context for a window.

X

Specifies the logical x-coordinate of the upper-left corner of the icon.

Y

Specifies the logical y-coordinate of the upper-left corner of the icon.

hIcon

Identifies the icon to be drawn.

Windows NT: The icon resource must have been previously loaded by using the LoadIcon function.

Windows 95: The icon resource must have been previously loaded by using the LoadIcon or LoadImage functions.

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.

Remarks

DrawIcon places the icon’s upper-left corner at the location specified by the X and Y parameters. The location is subject to the current mapping mode of the device context.

See Also

CreateIcon, DrawIconEx, LoadIcon


DrawIconEx

The DrawIconEx function draws an icon or cursor in the client area of the window of the specified device context, performing the specified raster operations, and stretching or compressing the icon or cursor as specified.

BOOL DrawIconEx(

HDC hdc,	// handle to device context
int xLeft,	// x-coordinate of upper left corner
int yTop,	// y-coordinate of upper left corner
HICON hIcon,	// handle to icon to draw
int cxWidth,	// width of the icon
int cyWidth,	// height of the icon
UINT istepIfAniCur,	// index of frame in animated cursor
HBRUSH hbrFlickerFreeDraw,	// handle to background brush
UINT diFlags	// icon-drawing flags
);
Parameters

hdc

Identifies the device context for a window.

xLeft

Specifies the logical x-coordinate of the upper-left corner of the icon or cursor.

yTop

Specifies the logical y-coordinate of the upper-left corner of the icon or cursor.

hIcon

Identifies the icon or cursor to be drawn. This parameter can identify an animated cursor. The icon or cursor resource must have been previously loaded by using the LoadImage function.

cxWidth

Specifies the logical width of the icon or cursor. If this parameter is zero and the diFlags parameter is DI_DEFAULTSIZE, the function uses the SM_CXICON or SM_CXCURSOR system metric value to set the width. If this parameter is zero and DI_DEFAULTSIZE is not used, the function uses the actual resource width.

cyWidth

Specifies the logical height of the icon or cursor. If this parameter is zero and the diFlags parameter is DI_DEFAULTSIZE, the function uses the SM_CYICON or SM_CYCURSOR system metric value to set the width. If this parameter is zero and DI_DEFAULTSIZE is not used, the function uses the actual resource height.

istepIfAniCur

Specifies the index of the frame to draw, if hIcon identifies an animated cursor. This parameter is ignored if hIcon does not identify an animated cursor.

hbrFlickerFreeDraw

Identifies a brush that the system uses for flicker-free drawing. If hbrBkgnd is a valid brush handle, the system creates an offscreen bitmap using the specified brush for the background color, draws the icon or cursor into the bitmap, and then copies the bitmap into the device context identified by hdc. If hbrBkgnd is NULL, the system draws the icon or cursor directly into the device context.

diFlags

Specifies the drawing flags. This parameter can be one of the following values:

Value	Meaning
DI_COMPAT	Draws the icon or cursor using the system default image rather than the user-specified image.
DI_DEFAULTSIZE	Draws the icon or cursor using the width and height specified by the system metric values for cursors or icons, if the cxWidth and cyWidth parameters are set to zero. If this flag is not specified and cxWidth and cyWidth are set to zero, the function uses the actual resource size.
DI_IMAGE	Performs the raster operation specified by ropImage.
DI_MASK	Performs the raster operation specified by ropMask.
DI_NORMAL	Combination of DI_IMAGE and DI_MASK.
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.

Remarks

The DrawIconEx function places the icon’s upper-left corner at the location specified by the xLeft and yTop parameters. The location is subject to the current mapping mode of the device context.

See Also

CopyImage, DrawIcon, LoadImage


DrawInsert

The DrawInsert function draws the insert icon in the parent window of the specified drag list box.

void DrawInsert(

HWND handParent,
HWND hLB,
int nItem
);
Parameters

handParent

Handle to the parent window of the drag list box.

hLB

Handle to the drag list box.

nItem

Identifier of the icon item to be drawn.

Return Values

This function does not return a value.


DrawMenuBar

The DrawMenuBar function redraws the menu bar of the specified window. If the menu bar changes after Windows has created the window, this function must be called to draw the changed menu bar.

BOOL DrawMenuBar(

HWND hWnd	// handle to window with menu bar to redraw
);
Parameters

hWnd

Identifies the window whose menu bar needs redrawing.

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.

See Also

DeleteMenu, InsertMenuItem, RemoveMenu, SetMenuItemInfo


DrawState [Now Supported on Windows NT]
DrawState

[Now Supported on Windows NT]

The DrawState function displays an image and applies a visual effect to indicate a state, such as a disabled or default state.

BOOL WINAPI DrawState(

HDC hdc,	// handle to device context
HBRUSH hbr,	// handle to brush
DRAWSTATEPROC lpOutputFunc,	// pointer to callback function
LPARAM lData,	// image information
WPARAM wData,	// more image information
int x,	// horizontal location of image
int y,	// vertical location of image
int cx,	// width of image
int cy,	// height of image
UINT fuFlags	// image type and state
);
Parameters

hdc

Identifies the device context to draw in.

hbr

Identifies the brush used to draw the image, if the state specified by the fuFlags parameter is DSS_MONO. This parameter is ignored for other states.

lpOutputFunc

Points to an application-defined callback function used to render the image. This parameter is required if the image type in fuFlags is DST_COMPLEX. It is optional and can be NULL if the image type is DST_TEXT. For all other image types, this parameter is ignored. For more information about the callback function, see the DrawStateProc function.

lData

Specifies information about the image. The meaning of this parameter depends on the image type.

wData

Specifies information about the image. The meaning of this parameter depends on the image type. It is, however, zero extended for use with the DrawStateProc function.

x

Specifies the horizontal location at which to draw the image.

y

Specifies the vertical location at which to draw the image.

cx

Specifies the width of the image, in device units. This parameter is required if the image type is DST_COMPLEX. Otherwise, it can be zero to calculate the width of the image.

cy

Specifies the height of the image, in device units. This parameter is required if the image type is DST_COMPLEX. Otherwise, it can be zero to calculate the height of the image.

fuFlags

Specifies the image type and state. The type can be one of these values:

Value (type)	Meaning
DST_BITMAP	The image is a bitmap. The low-order word of the lData parameter is the bitmap handle.
DST_COMPLEX	The image is application defined. To render the image, DrawState calls the callback function specified by the lpOutputFunc parameter.
DST_ICON	The image is an icon. The low-order word of lData is the icon handle.
DST_PREFIXTEXT	The image is text that may contain an accelerator mnemonic. DrawState interprets the ampersand (&) prefix character as a directive to underscore the character that follows. The lData parameter specifies the address of the string, and the wData parameter specifies the length. If wData is zero, the string must be null-terminated.
DST_TEXT	The image is text. The lData parameter specifies the address of the string, and the wData parameter specifies the length. If wData is zero, the string must be null-terminated.
The state can be one of these values:

Value (state)	Meaning
DSS_NORMAL	Draws the image without any modification.
DSS_UNION	Dithers the image.
DSS_DISABLED	Embosses the image.
DSS_MONO	Draws the image using the brush specified by the hbr parameter.
For all states except DSS_NORMAL, the image is converted to monochrome before the visual effect is applied.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

DrawStateProc


DrawStateProc [Now Supported on Windows NT]
DrawStateProc

[Now Supported on Windows NT]

The DrawStateProc function is an application-defined callback function that renders a complex image for the DrawState function.

BOOL CALLBACK DrawStateProc(

HDC hdc,	// handle to device context
LPARAM lData,	// image information
WPARAM wData,	// more image information
int cx,	// width of image
int cy	// height of image
);
Parameters

hdc

Identifies the device context to draw in. The device context is a memory device context with a bitmap selected, the dimensions of which are at least as great as those specified by the cx and cy parameters.

lData

Specifies information about the image, which the application passed to DrawState.

wData

Specifies information about the image, which the application passed to DrawState.

cx

Specifies the image width, in device units, as specified by the call to DrawState.

cy

Specifies the image height, in device units, as specified by the call to DrawState.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

DrawState


DrawStatusText

The DrawStatusText function draws the specified text in the style of a status window with borders.

void DrawStatusText(

HDC hdc,
LPRECT lprc,
LPCTSTR pszText,
UINT uFlags
);
Parameters

hdc

Handle to the display context for the window.

lprc

Pointer to a RECT structure that contains the position, in client coordinates, of the rectangle in which the text is drawn. The function draws the borders just inside of the edges of the specified rectangle.

pszText

Pointer to a null-terminated string that specifies the text to display. Tab characters in the string determine whether the string is left-aligned, right-aligned, or centered.

uFlags

Text drawing flags. This parameter can be a combination of these values:

Value	Meaning
SBT_NOBORDERS	Prevents borders from being drawn around the specified text.
SBT_POPOUT	Draws highlighted borders that make the text stand out.
SBT_RTLREADING	Windows 95 only: Displays text using right-to-left reading order on Hebrew or Arabic systems.
Return Values

This function does not return a value.

See Also

RECT


DrawText

The DrawText function draws formatted text in the specified rectangle. It formats the text according to the specified method (expanding tabs, justifying characters, breaking lines, and so forth).

int DrawText(

HDC hDC,	// handle to device context
LPCTSTR lpString,	// pointer to string to draw
int nCount,	// string length, in characters
LPRECT lpRect,	// pointer to structure with formatting dimensions
UINT uFormat	// text-drawing flags
);
Parameters

hDC

Identifies the device context.

lpString

Points to the string to be drawn. If the nCount parameter is −1, the string must be null-terminated.

nCount

Specifies the number of characters in the string. If nCount is −1, then the lpString parameter is assumed to be a pointer to a null-terminated string and DrawText computes the character count automatically.

lpRect

Points to a RECT structure that contains the rectangle (in logical coordinates) in which the text is to be formatted.

uFormat

Specifies the method of formatting the text. It can be any combination of the following values:

Value	Description
DT_BOTTOM	Justifies the text to the bottom of the rectangle. This value must be combined with DT_SINGLELINE.
DT_CALCRECT	Determines the width and height of the rectangle. If there are multiple lines of text, DrawText uses the width of the rectangle pointed to by the lpRect parameter and extends the base of the rectangle to bound the last line of text. If there is only one line of text, DrawText modifies the right side of the rectangle so that it bounds the last character in the line. In either case, DrawText returns the height of the formatted text but does not draw the text.
DT_CENTER	Centers text horizontally in the rectangle.
DT_EDITCONTROL	Duplicates the text-displaying characteristics of a multiline edit control. Specifically, the average character width is calculated in the same manner as for an edit control, and the function does not display a partially visible last line.
DT_END_ELLIPSIS or DT_PATH_ELLIPSIS	Replaces part of the given string with ellipses, if necessary, so that the result fits in the specified  rectangle. The given string is not modified unless the DT_MODIFYSTRING flag is specified. You can specify DT_END_ELLIPSIS to replace characters at the end of the string, or DT_PATH_ELLIPSIS to replace characters in the middle of the string. If the string contains backslash (\) characters, DT_PATH_ELLIPSIS preserves as much as possible of the text after the last backslash.
DT_EXPANDTABS	Expands tab characters. The default number of characters per tab is eight.
DT_EXTERNALLEADING	Includes the font external leading in line height. Normally, external leading is not included in the height of a line of text.
DT_LEFT	Aligns text to the left.
DT_MODIFYSTRING	Modifies the given string to match the displayed text. This flag has no effect unless the DT_END_ELLIPSIS or DT_PATH_ELLIPSIS flag is specified.
DT_NOCLIP	Draws without clipping. DrawText is somewhat faster when DT_NOCLIP is used.
DT_NOPREFIX	Turns off processing of prefix characters. Normally, DrawText interprets the mnemonic-prefix character & as a directive to underscore the character that follows, and the mnemonic-prefix characters && as a directive to print a single &. By specifying DT_NOPREFIX, this processing is turned off.
DT_RIGHT	Aligns text to the right.
DT_RTLREADING	Layout in right to left reading order for bi-directional text when the font selected into the hdc is a Hebrew or Arabic font. The default reading order for all text is left to right.
DT_SINGLELINE	Displays text on a single line only. Carriage returns and linefeeds do not break the line.
DT_TABSTOP	Sets tab stops. Bits 15−8 (high-order byte of the low-order word) of the uFormat parameter specify the number of characters for each tab. The default number of characters per tab is eight.
DT_TOP	Top-justifies text (single line only).
DT_VCENTER	Centers text vertically (single line only).
DT_WORDBREAK	Breaks words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the lpRect parameter. A carriage return-linefeed sequence also breaks the line.
Note that the DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP, and DT_NOPREFIX values cannot be used with the DT_TABSTOP value.

Return Values

If the function succeeds, the return value is the height of the text.

Remarks

The DrawText function uses the device context’s selected font, text color, and background color to draw the text. Unless the DT_NOCLIP format is used, DrawText clips the text so that it does not appear outside the specified rectangle. All formatting is assumed to have multiple lines unless the DT_SINGLELINE format is specified.

If the selected font is too large for the specified rectangle, the DrawText function does not attempt to substitute a smaller font.

See Also

GrayString, TabbedTextOut, TextOut, RECT


DrawTextEx [Now Supported on Windows NT]
DrawTextEx

[Now Supported on Windows NT]

The DrawTextEx function draws formatted text in the specified rectangle.

int DrawTextEx(

HDC hdc,	// handle to device context
LPTSTR lpchText,	// pointer to string to draw
int cchText,	// length of string to draw
LPRECT lprc,	// pointer to rectangle coordinates
UINT dwDTFormat,	// formatting options
LPDRAWTEXTPARAMS lpDTParams	// pointer to structure for more options
);
Parameters

hdc

Identifies the device context to draw in.

lpchText

Points to the string to draw. The string must be null-terminated if the cchText parameter is  −1.

cchText

Specifies the length, in characters, of the string specified by the lpchText parameter. If the string is null-terminated, this parameter can be  −1 to calculate the length.

lprc

Points to a RECT structure that contains the rectangle, in logical coordinates, in which the text is to be formatted.

dwDTFormat

Specifies formatting options. This parameter can be one or more of these values:

Value	Meaning
DT_BOTTOM	Justifies the text to the bottom of the rectangle. This value must be combined with DT_SINGLELINE.
DT_CALCRECT	Determines the width and height of the rectangle. If there are multiple lines of text, DrawTextEx uses the width of the rectangle pointed to by the lprc parameter and extends the base of the rectangle to bound the last line of text. If there is only one line of text, DrawTextEx modifies the right side of the rectangle so that it bounds the last character in the line. In either case, DrawTextEx returns the height of the formatted text, but does not draw the text.
DT_CENTER	Centers text horizontally in the rectangle.
DT_EDITCONTROL	Duplicates the text-displaying characteristics of a multiline edit control. Specifically, the average character width is calculated in the same manner as for an edit control, and the function does not display a partially visible last line.
DT_END_ELLIPSIS or DT_PATH_ELLIPSIS	Replaces part of the given string with ellipses, if necessary, so that the result fits in the specified  rectangle. The given string is not modified unless the DT_MODIFYSTRING flag is specified. You can specify DT_END_ELLIPSIS to replace characters at the end of the string, or DT_PATH_ELLIPSIS to replace characters in the middle of the string. If the string contains backslash (\) characters, DT_PATH_ELLIPSIS preserves as much as possible of the text after the last backslash.
DT_EXPANDTABS	Expands tab characters. The default number of characters per tab is eight.
DT_EXTERNALLEADING	Includes the font external leading in line height. Normally, external leading is not included in the height of a line of text.
DT_LEFT	Aligns text to the left.
DT_MODIFYSTRING	Modifies the given string to match the displayed text. This flag has no effect unless the DT_END_ELLIPSIS or DT_PATH_ELLIPSIS flag is specified.
DT_NOCLIP	Draws without clipping. DrawTextEx is somewhat faster when DT_NOCLIP is used.
DT_NOPREFIX	Turns off processing of prefix characters. Normally, DrawTextEx interprets the ampersand (&) mnemonic-prefix character as a directive to underscore the character that follows, and the double ampersand (&&) mnemonic-prefix characters as a directive to print a single ampersand. By specifying DT_NOPREFIX, this processing is turned off.
DT_RIGHT	Aligns text to the right.
DT_RTLREADING	Layout in right to left reading order for bi-directional text when the font selected into the hdc is a Hebrew or Arabic font. The default reading order for all text is left to right.
DT_SINGLELINE	Displays text on a single line only. Carriage returns and linefeeds do not break the line.
DT_TABSTOP	Sets tab stops. The DRAWTEXTPARAMS structure pointed to by the lpDTParams parameter specifies the number of average character widths per tab stop.
DT_TOP	Top justifies text (single line only).
DT_VCENTER	Centers text vertically (single line only).
DT_WORDBREAK	Breaks words. Lines are automatically broken between words if a word extends past the edge of the rectangle specified by the lprc parameter. A carriage return-linefeed sequence also breaks the line.
dwDTParams

Points to a DRAWTEXTPARAMS structure that specifies additional formatting options. This parameter can be NULL.

Return Values

If the function succeeds, the return value is the text height.

If the function fails, the return value is zero.

See Also

DrawText, DRAWTEXTPARAMS


DuplicateHandle

The DuplicateHandle function duplicates an object handle.

BOOL DuplicateHandle(

HANDLE hSourceProcessHandle,	// handle to process with handle to duplicate
HANDLE hSourceHandle,	// handle to duplicate
HANDLE hTargetProcessHandle,	// handle to process to duplicate to
LPHANDLE lpTargetHandle,	// pointer to duplicate handle
DWORD dwDesiredAccess,	// access for duplicate handle
BOOL bInheritHandle,	// handle inheritance flag
DWORD dwOptions	// optional actions
);
Parameters

hSourceProcessHandle

Identifies the process containing the handle to duplicate. The handle must have PROCESS_DUP_HANDLE access. For more information, see Process Objects.

hSourceHandle

Identifies the handle to duplicate. This is an open object handle that is valid in the context of the source process. For a list of objects whose handles can be duplicated, see the following Remarks section.

hTargetProcessHandle

Identifies the process that is to receive the duplicated handle. The handle must have PROCESS_DUP_HANDLE access.

lpTargetHandle

Points to a variable receiving the value of the duplicate handle. This handle value is valid in the context of the target process. If lpTargetHandle is NULL, the function duplicates the handle, but does not return the duplicate handle value to the caller.

dwDesiredAccess

Specifies the access requested for the new handle. This parameter is ignored if the dwOptions parameter specifies the DUPLICATE_SAME_ACCESS flag. Otherwise, the flags that can be specified depend on the type of object whose handle is being duplicated. For the flags that can be specified for each object type, see the following Remarks section. Note that the new handle can have more access than the original handle.

bInheritHandle

Indicates whether the handle is inheritable. If TRUE, the duplicate handle can be inherited by new processes created by the target process. If FALSE, the new handle cannot be inherited.

dwOptions

Specifies optional actions. This parameter can be zero, or any combination of the following flags:

Value	Meaning
DUPLICATE_CLOSE_SOURCE	Closes the source handle. This occurs regardless of any error status returned.
DUPLICATE_SAME_ACCESS	Ignores the dwDesiredAccess parameter. The duplicate handle has the same access as the source handle.
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.

Remarks

DuplicateHandle can be called by either the source process or the target process. It can also be invoked where the source and target process are the same. For example, a process can use DuplicateHandle to create a noninheritable duplicate of an inheritable handle, or a handle with different access than the original handle.

The duplicating process uses the GetCurrentProcess function to get a handle of itself. To get the other process handle, it may be necessary to use some form of interprocess communication (for example, named pipe or shared memory) to communicate the process identifier to the duplicating process. This identifier is then used in the OpenProcess function to open a handle.

If the process that calls DuplicateHandle is not the target process, the duplicating process must use interprocess communication to pass the value of the duplicate handle to the target process.

The duplicate handle is the same object handle as the source handle. This means that the state of the object is the same for both handles. For example, the current file mark for a file handle is always the same for both handles.

DuplicateHandle can duplicate handles to the following types of objects:

Object	Description
Console input	The handle is returned by the CreateFile function when CONIN$ is specified, or by the GetStdHandle function when STD_INPUT_HANDLE is specified. Console handles can be duplicated for use only in the same process.
Console screen buffer	The handle is returned by the CreateFile function when CONOUT$ is specified, or by the GetStdHandle function when STD_OUTPUT_HANDLE is specified. Console handles can be duplicated for use only in the same process.
Event	The handle is returned by the CreateEvent or OpenEvent function.
File or communications device	The handle is returned by the CreateFile function.
File mapping	The handle is returned by the CreateFileMapping function.
Mutex	The handle is returned by the CreateMutex or OpenMutex function.
Pipe	A named pipe handle is returned by the CreateNamedPipe or CreateFile function. An anonymous pipe handle is returned by the CreatePipe function.
Process	The handle is returned by the CreateProcess, GetCurrentProcess, or OpenProcess function.
Registry key	The handle is returned by the RegCreateKey, RegCreateKeyEx, RegOpenKey, or RegOpenKeyEx function. Note that registry key handles returned by the RegConnectRegistry function cannot be used in a call to DuplicateHandle.
Semaphore	The handle is returned by the CreateSemaphore or OpenSemaphore function.
Thread	The handle is returned by the CreateProcess, CreateThread, CreateRemoteThread, or GetCurrentThread function
In addition to STANDARD_RIGHTS_REQUIRED, the following access flags can be specified in the dwDesiredAccess parameter for the different object types. Note that the new handle can have more access than the original handle. However, in some cases DuplicateHandle cannot create a duplicate handle with more access permission than the original handle. For example, a file handle created with GENERIC_READ access cannot be duplicated so that it has both GENERIC_READ and GENERIC_WRITE access.

Any combination of the following access flags is valid for handles to communications devices, console input, console screen buffers, files, and pipes:

Access	Description
GENERIC_READ	Enables read access.
GENERIC_WRITE	Enables write access.
Any combination of the following access flags is valid for file-mapping objects:

Access	Description
FILE_MAP_ALL_ACCESS	Specifies all possible access flags for the file-mapping object.
FILE_MAP_READ	Enables mapping the object into memory that permits read access.
FILE_MAP_WRITE	Enables mapping the object into memory that permits write access. For write access, PAGE_READWRITE protection must have been specified when the file-mapping object was created by the CreateFileMapping function.
Any combination of the following access flags is valid for mutex objects:

Access	Description
MUTEX_ALL_ACCESS	Specifies all possible access flags for the mutex object.
SYNCHRONIZE	Windows NT only: Enables use of the mutex handle in any of the wait functions to acquire ownership of the mutex, or in the ReleaseMutex function to release ownership.
Any combination of the following access flags is valid for semaphore objects:

Access	Description
SEMAPHORE_ALL_ACCESS	Specifies all possible access flags for the semaphore object.
SEMAPHORE_MODIFY_STATE	Enables use of the semaphore handle in the ReleaseSemaphore function to modify the semaphore’s count.
SYNCHRONIZE	Windows NT only: Enables use of the semaphore handle in any of the wait functions to wait for the semaphore’s state to be signaled.
Any combination of the following access flags is valid for event objects:

Access	Description
EVENT_ALL_ACCESS	Specifies all possible access flags for the event object.
EVENT_MODIFY_STATE	Enables use of the event handle in the SetEvent and ResetEvent functions to modify the event’s state.
SYNCHRONIZE	Windows NT only: Enables use of the event handle in any of the wait functions to wait for the event’s state to be signaled.
Any combination of the following access flags is valid for handles to registry keys:

Value	Meaning
KEY_ALL_ACCESS	Specifies all possible flags for the registry key.
KEY_CREATE_LINK	Enables using the handle to create a link to a registry-key object.
KEY_CREATE_SUB_KEY	Enables using the handle to create a subkey of a registry-key object.
KEY_ENUMERATE_SUB_KEYS	Enables using the handle to enumerate the subkeys of a registry-key object.
KEY_EXECUTE	Equivalent to KEY_READ.
KEY_NOTIFY	Enables using the handle to request change notifications for a registry key or for subkeys of a registry key.
KEY_QUERY_VALUE	Enables using the handle to query a value of a registry-key object.
KEY_READ	Combines the STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY values.
KEY_SET_VALUE	Enables using the handle to create or set a value of a registry-key object.
KEY_WRITE	Combines the STANDARD_RIGHTS_WRITE, KEY_SET_VALUE, and KEY_CREATE_SUB_KEY values.
Any combination of the following access flags is valid for process objects:

Access	Description
PROCESS_ALL_ACCESS	Specifies all possible access flags for the process object.
PROCESS_CREATE_PROCESS	Used internally.
PROCESS_CREATE_THREAD	Enables using the process handle in the CreateRemoteThread function to create a thread in the process.
PROCESS_DUP_HANDLE	Enables using the process handle as either the source or target process in the DuplicateHandle function to duplicate a handle.
PROCESS_QUERY_INFORMATION	Enables using the process handle in the GetExitCodeProcess and GetPriorityClass functions to read information from the process object.
PROCESS_SET_INFORMATION	Enables using the process handle in the SetPriorityClass function to set the process’s priority class.
PROCESS_TERMINATE	Enables using the process handle in the TerminateProcess function to terminate the process.
PROCESS_VM_OPERATION	Enables using the process handle in the VirtualProtectEx and WriteProcessMemory functions to modify the virtual memory of the process.
PROCESS_VM_READ	Enables using the process handle in the ReadProcessMemory function to read from the virtual memory of the process.
PROCESS_VM_WRITE	Enables using the process handle in the WriteProcessMemory function to write to the virtual memory of the process.
SYNCHRONIZE	Windows NT only: Enables using the process handle in any of the wait functions to wait for the process to terminate.
Any combination of the following access flags is valid for thread objects:

Access	Description
SYNCHRONIZE	Windows NT only: Enables using the thread handle in any of the wait functions to wait for the thread to terminate.
THREAD_ALL_ACCESS	Specifies all possible access flags for the thread object.
THREAD_DIRECT_IMPERSONATION	Used internally.
THREAD_GET_CONTEXT	Enables using the thread handle in the GetThreadContext function to read the thread’s context.
THREAD_IMPERSONATE	Used internally.
THREAD_QUERY_INFORMATION	Enables using the thread handle in the GetExitCodeThread, GetThreadPriority, and GetThreadSelectorEntry functions to read information from the thread object.
THREAD_SET_CONTEXT	Enables using the thread handle in the SetThreadContext function to set the thread’s context.
THREAD_SET_INFORMATION	Enables using the thread handle in the SetThreadPriority function to set the thread’s priority.
THREAD_SET_THREAD_TOKEN	Used internally.
THREAD_SUSPEND_RESUME	Enables using the thread handle in the SuspendThread or ResumeThread functions to suspend or resume a thread.
THREAD_TERMINATE	Enables using the thread handle in the TerminateThread function to terminate the thread.
See Also

CloseHandle, CreateEvent, CreateFile, CreateFileMapping, CreateMutex, CreateNamedPipe, CreatePipe, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, GetCurrentProcess, GetExitCodeProcess, GetExitCodeThread, GetPriorityClass, GetStdHandle, GetThreadContext, GetThreadPriority, GetThreadSelectorEntry, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, ReadProcessMemory, RegConnectRegistry, RegCreateKey, RegCreateKeyEx, RegOpenKey, RegOpenKeyEx, ReleaseMutex, ReleaseSemaphore, ResetEvent, ResumeThread, SetEvent, SetPriorityClass, SetThreadContext, SetThreadPriority, SuspendThread, TerminateProcess, TerminateThread, VirtualProtectEx, WriteProcessMemory


DuplicateToken

The DuplicateToken function creates a new access token that duplicates one already in existence.

BOOL DuplicateToken(

HANDLE ExistingTokenHandle,	// handle to token to duplicate
SECURITY_IMPERSONATION_LEVEL ImpersonationLevel,	// impersonation level
PHANDLE DuplicateTokenHandle	// handle to duplicated token
);
Parameters

ExistingTokenHandle

Identifies an access token opened with TOKEN_DUPLICATE access.

ImpersonationLevel

Specifies a SECURITY_IMPERSONATION_LEVEL enumerated type that supplies the impersonation level of the new token.

DuplicateTokenHandle

Pointer to a variable that receives the handle of the duplicate token. This handle has TOKEN_IMPERSONATE and TOKEN_QUERY access to the new token.

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.

Remarks

The DuplicateToken function creates an impersonation token, which you can use in functions such as SetThreadToken and ImpersonateLoggedOnUser. The token created by DuplicateToken cannot be used in the CreateProcessAsUser function, which requires a primary token. To create a token that you can pass to CreateProcessAsUser, use the DuplicateTokenEx function.

See Also

CreateProcessAsUser, DuplicateTokenEx, ImpersonateLoggedOnUser, SECURITY_IMPERSONATION_LEVEL, SetThreadToken


DuplicateTokenEx [New - Windows NT]
DuplicateTokenEx

[New - Windows NT]

The DuplicateTokenEx function creates a new access token that duplicates an existing token. This function can create either a primary token or an impersonation token.

BOOL DuplicateTokenEx(

HANDLE hExistingToken,	// handle to token to duplicate
DWORD dwDesiredAccess,	// access rights of new token
LPSECURITY_ATTRIBUTES lpTokenAttributes,	// security attributes of the new token
SECURITY_IMPERSONATION_LEVEL ImpersonationLevel,	// impersonation level of new token
TOKEN_TYPE TokenType,	// primary or impersonation token
PHANDLE phNewToken	// handle to duplicated token
);
Parameters

hExistingToken

Identifies an access token opened with TOKEN_DUPLICATE access.

dwDesiredAccess

Specifies the requested access rights for the new token. The DuplicateTokenEx function compares the requested access rights with the existing token’s discretionary access-control list (ACL) to determine which rights are granted or denied. To request the same access rights as the existing token, specify zero. To request all access rights that are valid for the caller, specify MAXIMUM_ALLOWED. Otherwise, specify a combination of the following access rights.

Value	Meaning
TOKEN_ADJUST_DEFAULT	Required to change the default ACL, primary group, or owner of an access token.
TOKEN_ADJUST_GROUPS	Required to change the groups specified in an access token.
TOKEN_ADJUST_PRIVILEGES	Required to change the privileges specified in an access token.
TOKEN_ALL_ACCESS	Combines the STANDARD_RIGHTS_REQUIRED standard access rights and all individual access rights for tokens.
TOKEN_ASSIGN_PRIMARY	Required to attach a primary token to a process in addition to the SE_CREATE_TOKEN_NAME privilege.
TOKEN_DUPLICATE	Required to duplicate an access token.
TOKEN_EXECUTE	Combines the STANDARD_RIGHTS_EXECUTE standard access rights and the TOKEN_IMPERSONATE access right.
TOKEN_IMPERSONATE	Required to attach an impersonation access token to a process.
TOKEN_QUERY	Required to query the contents of an access token.
TOKEN_QUERY_SOURCE	Required to query the source of an access token.
TOKEN_READ	Combines the STANDARD_RIGHTS_READ standard access rights and the TOKEN_QUERY access right.
TOKEN_WRITE	Combines the STANDARD_RIGHTS_WRITE standard access rights and the TOKEN_ADJUST_PRIVILEGES, TOKEN_ADJUST_GROUPS, and TOKEN_ADJUST_DEFAULT access rights.
lpTokenAttributes

Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new token and determines whether child processes can inherit the token. If lpTokenAttributes is NULL, the token gets a default security descriptor and the handle cannot be inherited.

ImpersonationLevel

Specifies a value from the SECURITY_IMPERSONATION_LEVEL enumeration that indicates the impersonation level of the new token.

TokenType

Specifies one of the following values from the TOKEN_TYPE enumeration.

Value	Meaning
TokenPrimary	The new token is a primary token that you can use in the CreateProcessAsUser function.
TokenImpersonation	The new token is an impersonation token.
phNewToken

Pointer to a HANDLE variable that receives the new token.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The DuplicateTokenEx function allows you to create a primary token that you can use in the CreateProcessAsUser function. This allows a server application that is impersonating a client to create a process that has the security context of the client. Note that the DuplicateToken function can create only impersonation tokens, which are not valid for CreateProcessAsUser.

The following is a typical scenario for using DuplicateTokenEx to create a primary token. A server application creates a thread that calls one of the impersonation functions, such as ImpersonateNamedPipeClient, to impersonate a client. The impersonating thread then calls the OpenThreadToken function to get its own token, which is an impersonation token that has the security context of the client. The thread specifies this impersonation token in a call to DuplicateTokenEx, specifying the TokenPrimary flag. DuplicateTokenEx creates a primary token that has the security context of the client.

When you have finished using the new token, call the CloseHandle function to close the token handle.

See Also

CloseHandle, CreateProcessAsUser, DdeImpersonateClient, DuplicateToken, ImpersonateNamedPipeClient, OpenThreadToken, RevertToSelf, RpcImpersonateClient, SECURITY_ATTRIBUTES, SECURITY_IMPERSONATION_LEVEL


EditWordBreakProc

An EditWordBreakProc function is an application-defined callback function. A value of type EDITWORDBREAKPROC is a pointer to such a function.

Windows NT: A multiline edit control calls an EditWordBreakProc function whenever the control must break a line of text.

Windows 95: A multiline edit control or a rich edit control calls an EditWordBreakProc function whenever the control must break a line of text.

int CALLBACK EditWordBreakProc(

LPTSTR lpch,	// pointer to edit text
int ichCurrent,	// index of starting point
int cch,	// length in characters of edit text
int code	// action to take
);
Parameters

lpch

Points to the text of the edit control.

ichCurrent

Specifies an index to a character position in the buffer of text that identifies the point at which the function should begin checking for a word break.

cch

Specifies the number of characters in the edit control text.

code

Specifies the action to be taken by the callback function. This parameter can be one of the following values:

Value	Action
WB_ISDELIMITER	Checks whether the character at the current position is a delimiter.
WB_LEFT	Looks for the beginning of a word to the left of the current position.
WB_RIGHT	Looks for the beginning of a word to the right of the current position. (This is useful in right-aligned edit controls.)
Windows 95: Additional values for the code parameter are defined for rich edit controls. For a list of these values, see the description of the EM_FINDWORDBREAK message.

Return Values

If the code parameter specifies WB_ISDELIMITER, the return value is nonzero (TRUE) if the character at the current position is a delimiter, or zero if it is not. Otherwise, the return value is an index to the beginning of a word in the buffer of text.

Remarks

A carriage return followed by a linefeed must be treated as a single word by the callback function. Two carriage returns followed by a linefeed also must be treated as a single word.

An application must install the callback function by specifying the address of the callback function in an EM_SETWORDBREAKPROC message.

EditWordBreakProc is a placeholder for an application-defined function name.

See Also

SendMessage, EM_FINDWORDBREAK, EM_SETWORDBREAKPROC


EditWordBreakProcEx [Now Supported on Windows NT]
EditWordBreakProcEx

[Now Supported on Windows NT]

An application-supplied callback function that determines the character index of the word break, or the character class and word break flags of the characters in the specified text.

LONG EditWordBreakProcEx(

char *pchText,
LONG cchText,
BYTE bCharSet,
INT code
);
Parameters

pchText

Pointer to the text at the current position. If code specifies movement to the left, the text is in the elements pchText[-1] through pchText[-cchText] and pchText[0] is undefined. For all other actions, the text is in the elements pchText[0] through pchText[cchText - 1].

cchText

Number of characters in the buffer in the direction specified by code.

bCharSet

Character set of the text.

code

Wordbreak action to take. Can be one of the values described for the code parameter in the EM_FINDWORDBREAK message.

Return Values

Returns the character index of the word break, unless the code parameter is the WB_CLASSIFY or WB_ISDELIMITER value.

See Also

EM_FINDWORDBREAK


Ellipse

The Ellipse function draws an ellipse. The center of the ellipse is the center of the specified bounding rectangle. The ellipse is outlined by using the current pen and is filled by using the current brush.

BOOL Ellipse(

HDC hdc,	// handle to device context
int nLeftRect,	// x-coord. of bounding rectangle’s upper-left corner
int nTopRect,	// y-coord. of bounding rectangle’s upper-left corner
int nRightRect,	// x-coord. of bounding rectangle’s lower-right corner
int nBottomRect	// y-coord. bounding rectangle’s f lower-right corner
);
Parameters

hdc

Identifies the device context.

nLeftRect

Specifies the x-coordinate of the upper-left corner of the bounding rectangle.

nTopRect

Specifies the y-coordinate of the upper-left corner of the bounding rectangle.

nRightRect

Specifies the x-coordinate of the lower-right corner of the bounding rectangle.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the bounding rectangle.

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.

Remarks

The current position is neither used nor updated by Ellipse.

Windows 95: The sum of the coordinates of the bounding rectangle cannot exceed 32,767. The sum of nLeftRect and nRightRect or nTopRect and nBottomRect parameters cannot exceed 32,767.

See Also

Arc, ArcTo


EmptyClipboard

The EmptyClipboard function empties the clipboard and frees handles to data in the clipboard. The function then assigns ownership of the clipboard to the window that currently has the clipboard open.

BOOL EmptyClipboard(VOID)

Parameters

This function has no parameters.

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.

Remarks

Before calling EmptyClipboard, an application must open the clipboard by using the OpenClipboard function. If the application specifies a NULL window handle when opening the clipboard, EmptyClipboard succeeds but sets the clipboard owner to NULL.

See Also

OpenClipboard, SetClipboardData, WM_DESTROYCLIPBOARD


EnableEUDC [Now Supported on Windows NT]
EnableEUDC

[Now Supported on Windows NT]

The EnableEUDC function enables or disables end-user-defined characters (EUDC). Enabling EUDC allows text output functions to retrieve information about end-user-defined characters from EUDC fonts. Disabling EUDC prevents output functions from accessing these fonts.

BOOL EnableEUDC(

BOOL fEnableEUDC
);
Parameters

fEnableEUDC

Action flag. Can be TRUE to enable EUDC or FALSE to disable it.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Applications call the EnableEUDC function before and after adding, modifying, or deleting EUDC fonts. An application must disable EUDC before modifying a EUDC font or before adding or deleting a font from the registry. Application must enable EUDC after these changes to allow functions access to them.

See Also

ImmRegisterWord, ImmUnregisterWord


EnableMenuItem

The EnableMenuItem function enables, disables, or grays the specified menu item.

BOOL EnableMenuItem(

HMENU hMenu,	// handle to menu
UINT uIDEnableItem,	// menu item to enable, disable, or gray
UINT uEnable	// menu item flags
);
Parameters

hMenu

Identifies the menu.

uIDEnableItem

Specifies the menu item to be enabled, disabled, or grayed, as determined by the uEnable parameter. This parameter specifies an item in a menu bar, menu, or submenu.

uEnable

Specifies flags that control the interpretation of the uIDEnableItem parameter and indicate whether the menu item is enabled, disabled, or grayed. This parameter must be a combination of either MF_BYCOMMAND or MF_BYPOSITION and MF_ENABLED, MF_DISABLED, or MF_GRAYED.

Value	Meaning
MF_BYCOMMAND	Indicates that uIDEnableItem gives the identifier of the menu item. If neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified, the MF_BYCOMMAND flag is the default flag.
MF_BYPOSITION	Indicates that uIDEnableItem gives the zero-based relative position of the menu item.
MF_DISABLED	Indicates that the menu item is disabled, but not grayed, so it cannot be selected.
MF_ENABLED	Indicates that the menu item is enabled and restored from a grayed state so that it can be selected.
MF_GRAYED	Indicates that the menu item is disabled and grayed so that it cannot be selected.
Return Values

The return value specifies the previous state of the menu item (it is either MF_DISABLED, MF_ENABLED, or MF_GRAYED). If the menu item does not exist, the return value is 0xFFFFFFFF.

Remarks

An application must use the MF_BYPOSITION flag to specify the correct menu handle. If the menu handle to the menu bar is specified, the top-level menu item (an item in the menu bar) is affected. To set the state of an item in a drop-down menu or submenu by position, an application must specify the handle to the drop-down menu or submenu.

When an application specifies the MF_BYCOMMAND flag, Windows checks all items that open submenus in the menu identified by the specified menu handle. Therefore, unless duplicate menu items are present, specifying the menu handle to the menu bar is sufficient.

The CreateMenu, InsertMenu, InsertMenuItem, LoadMenuIndirect, ModifyMenu, and SetMenuItemInfo functions can also set the state (enabled, disabled, or grayed) of a menu item.

See Also

CreateMenu, GetMenuItemID, InsertMenu, InsertMenuItem, LoadMenuIndirect, ModifyMenu, SetMenuItemInfo, WM_SYSCOMMAND


EnableScrollBar

The EnableScrollBar function enables or disables one or both scroll bar arrows.

BOOL EnableScrollBar(

HWND hWnd,	// handle to window or scroll bar
UINT wSBflags,	// scroll bar type flag
UINT wArrows	// scroll bar arrow flag
);
Parameters

hWnd

Identifies a window or a scroll bar control, depending on the value of the wSBflags parameter.

wSBflags

Specifies the scroll bar type. This parameter can be one of the following values:

Value	Meaning
SB_BOTH	Enables or disables the arrows on the horizontal and vertical scroll bars associated with the specified window. The hWnd parameter must be the handle to the window.
SB_CTL	Identifies the scroll bar as a scroll bar control. The hWnd parameter must be the handle to the scroll bar control.
SB_HORZ	Enables or disables the arrows on the horizontal scroll bar associated with the specified window. The hWnd parameter must be the handle to the window.
SB_VERT	Enables or disables the arrows on the vertical scroll bar associated with the specified window. The hWnd parameter must be the handle to the window.
wArrows

Specifies whether the scroll bar arrows are enabled or disabled and indicates which arrows are enabled or disabled. This parameter can be one of the following values:

Value	Meaning
ESB_DISABLE_BOTH	Disables both arrows on a scroll bar.
ESB_DISABLE_DOWN	Disables the down arrow on a vertical scroll bar.
ESB_DISABLE_LEFT	Disables the left arrow on a horizontal scroll bar.
ESB_DISABLE_LTUP	Disables the left arrow on a horizontal scroll bar or the up arrow of a vertical scroll bar.
ESB_DISABLE_RIGHT	Disables the right arrow on a horizontal scroll bar.
ESB_DISABLE_RTDN	Disables the right arrow on a horizontal scroll bar or the down arrow of a vertical scroll bar.
ESB_DISABLE_UP	Disables the up arrow on a vertical scroll bar.
ESB_ENABLE_BOTH	Enables both arrows on a scroll bar.
Return Values

If the arrows are enabled or disabled as specified, the return value is nonzero.

If the arrows are already in the requested state or an error occurs, the return value is zero.

See Also

ShowScrollBar


EnableWindow

The EnableWindow function enables or disables mouse and keyboard input to the specified window or control. When input is disabled, the window does not receive input such as mouse clicks and key presses. When input is enabled, the window receives all input.

BOOL EnableWindow(

HWND hWnd,	// handle to window
BOOL bEnable	// flag for enabling or disabling input
);
Parameters

hWnd

Identifies the window to be enabled or disabled.

bEnable

Specifies whether to enable or disable the window. If this parameter is TRUE, the window is enabled. If the parameter is FALSE, the window is disabled.

Return Values

If the window was previously disabled, the return value is nonzero.

If the window was not previously disabled, the return value is zero. To get extended error information, call GetLastError.

Remarks

If the enabled state of a window is changing, a WM_ENABLE message is sent before the EnableWindow function returns. If a window is already disabled, all its child windows are implicitly disabled, although they are not sent a WM_ENABLE message.

A window must be enabled before it can be activated. For example, if an application is displaying a modeless dialog box and has disabled its main window, the application must enable the main window before destroying the dialog box. Otherwise, another window will receive the keyboard focus and be activated. If a child window is disabled, it is ignored when Windows tries to determine which window should receive mouse messages.

By default, a window is enabled when it is created. To create a window that is initially disabled, an application can specify the WS_DISABLED style in the CreateWindow or CreateWindowEx function. After a window has been created, an application can use EnableWindow to enable or disable the window.

An application can use this function to enable or disable a control in a dialog box. A disabled control cannot receive the keyboard focus, nor can a user gain access to it.

See Also

CreateWindow, CreateWindowEx, IsWindowEnabled, WM_ENABLE


EndDeferWindowPos

The EndDeferWindowPos function simultaneously updates the position and size of one or more windows in a single screen-refreshing cycle.

BOOL EndDeferWindowPos(

HDWP hWinPosInfo	// handle to internal structure
);
Parameters

hWinPosInfo

Identifies a multiple-window − position structure that contains size and position information for one or more windows. This internal structure is returned by the BeginDeferWindowPos function or by the most recent call to the DeferWindowPos 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.

Remarks

The EndDeferWindowPos function sends the WM_WINDOWPOSCHANGING and WM_WINDOWPOSCHANGED messages to each window identified in the internal structure.

See Also

BeginDeferWindowPos, DeferWindowPos, WM_WINDOWPOSCHANGED, WM_WINDOWPOSCHANGING


EndDialog

The EndDialog function destroys a modal dialog box, causing the system to end any processing for the dialog box.

BOOL EndDialog(

HWND hDlg,	// handle to dialog box
int nResult	// value to return
);
Parameters

hDlg

Identifies the dialog box to be destroyed.

nResult

Specifies the value to be returned to the application from the function that created the dialog box.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Dialog boxes created by the DialogBox, DialogBoxParam, DialogBoxIndirect, and DialogBoxIndirectParam functions must be destroyed using the EndDialog function. An application calls EndDialog from within the dialog box procedure; the function must not be used for any other purpose.

A dialog box procedure can call EndDialog at any time, even during the processing of the WM_INITDIALOG message. If your application calls the function while WM_INITDIALOG is being processed, the dialog box is destroyed before it is shown and before the input focus is set.

EndDialog does not destroy the dialog box immediately. Instead, it sets a flag and allows the dialog box procedure to return control to the system. The system checks the flag before attempting to retrieve the next message from the application queue. If the flag is set, the system ends the message loop, destroys the dialog box, and uses the value in nResult as the return value from the function that created the dialog box.

See Also

DialogBox, DialogBoxIndirect, DialogBoxIndirectParam, DialogBoxParam, WM_INITDIALOG


EndDoc

The EndDoc function ends a print job. This function replaces the ENDDOC printer escape.

int EndDoc(

HDC hdc	// handle to device context
);
Parameters

hdc

Identifies the device context for the print job.

Return Values

If the function succeeds, the return value is greater than zero.

If the function fails, the return value is less than or equal to zero. To get extended error information, call GetLastError.

Remarks

Applications should call EndDoc immediately after finishing a print job.

See Also

StartDoc


EndDocPrinter

The EndDocPrinter function ends a print job for the specified printer.

BOOL EndDocPrinter(

HANDLE hPrinter	// handle to printer object
);
Parameters

hPrinter

Identifies a printer for which the print job should be ended.

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.

Remarks

The EndDocPrinter function returns an error if the print job was not started by calling the StartDocPrinter function.

See Also

StartDocPrinter


EndPage

The EndPage function informs the device that the application has finished writing to a page. This function is typically used to direct the device driver to advance to a new page. This function replaces the NEWFRAME printer escape.

int EndPage(

HDC hdc	// handle to device context
);
Parameters

hdc

Identifies the device context for the print job.

Return Values

If the function succeeds, the return value is greater than zero.

If the function fails, the return value is less than or equal to zero. To get extended error information, call GetLastError.

Remarks

Use the ResetDC function to change the device mode, if necessary, after calling the EndPage function. Note that a call to ResetDC resets all device context attributes back to default values.

Windows 3.x: EndPage resets the device context attributes back to default values. You must re-select objects and set up the mapping mode again before printing the next page.

Windows 95: EndPage does not reset the device context attributes. However, the next StartPage call does reset the device context attributes to default values. At that time, you must re-select objects and set up the mapping mode again before printing the next page.

Windows NT: Beginning with Windows NT Version 3.5, neither EndPage or StartPage resets the device context attributes. Device context attributes remain constant across subsequent pages. You do not need to re-select objects and set up the mapping mode again before printing the next page; however, doing so will produce the same results and reduce code differences between Windows 95 and Windows NT.

See Also

ResetDC, StartPage


EndPagePrinter

The EndPagePrinter function indicates the end of one page and the beginning of the next page for the specified printer.

BOOL EndPagePrinter(

HANDLE hPrinter	// handle to printer object
);
Parameters

hPrinter

Identifies the printer for which the page will be concluded.

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.

Remarks

The printer-object handle hPrinter is obtained by calling the OpenPrinter function.

Each page in a print job begins with a StartPagePrinter function call and ends with an EndPagePrinter function call. The data for each page is written to the print file by using the WritePrinter function.

See Also

OpenPrinter, StartPagePrinter, WritePrinter


EndPaint

The EndPaint function marks the end of painting in the specified window. This function is required for each call to the BeginPaint function, but only after painting is complete.

BOOL EndPaint(

HWND hWnd,	// handle to window
CONST PAINTSTRUCT *lpPaint	// pointer to structure for paint data
);
Parameters

hWnd

Identifies the window that has been repainted.

lpPaint

Points to a PAINTSTRUCT structure that contains the painting information retrieved by BeginPaint.

Return Values

The return value is always nonzero.

Remarks

If the caret was hidden by BeginPaint, EndPaint restores the caret to the screen.

See Also

BeginPaint, PAINTSTRUCT


EndPath

The EndPath function closes a path bracket and selects the path defined by the bracket into the specified device context.

BOOL EndPath(

HDC hdc	// handle to device context
);
Parameters

hdc

Identifies the device context into which the new path is selected.

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 one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER

See Also

BeginPath


EndUpdateResource

The EndUpdateResource function ends a resource update in an executable file.

BOOL EndUpdateResource(

HANDLE hUpdate,	// update-file handle
BOOL fDiscard	// write flag
);
Parameters

hUpdate

Specifies an update handle. This handle is returned by the BeginUpdateResource function.

fDiscard

Specifies whether to write resource updates to an executable file. If this parameter is TRUE, no changes are made to the executable file. If it is FALSE, the changes are made.

Return Values

If the function succeeds and the accumulated resource modifications specified by calls to the UpdateResource function are written to the specified executable file, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

BeginUpdateResource, UpdateResource


EnhMetaFileProc

The EnhMetaFileProc function is an application-defined callback function that processes enhanced-format metafile records. This function is called by the EnumEnhMetaFile function.

int CALLBACK EnhMetaFileProc(

HDC hDC,	// handle to device context
HANDLETABLE FAR *lpHTable,	// pointer to metafile handle table
ENHMETARECORD FAR *lpEMFR,	// pointer to metafile record
int nObj,	// count of objects
LPARAM lpData	// pointer to optional data
);
Parameters

hDC

Identifies the device context passed to EnumEnhMetaFile.

lpHTable

Points to a table of handles associated with the graphics objects (pens, brushes, and so on) in the metafile. The first entry contains the enhanced-metafile handle.

lpEMFR

Points to one of the records in the metafile. This record should not be modified. (If modification is necessary, it should be performed on a copy of the record.)

nObj

Specifies the number of objects with associated handles in the handle table.

lpData

Points to any application-supplied data.

Return Values

This function must return a nonzero value to continue enumeration; to stop enumeration, it must return zero.

Remarks

An application must register the callback function by passing its address to the EnumEnhMetaFile function.

EnhMetaFileProc is a placeholder for the application-supplied function name.

See Also

EnumEnhMetaFile


EnterCriticalSection

The EnterCriticalSection function waits for ownership of the specified critical section object. The function returns when the calling thread is granted ownership.

VOID EnterCriticalSection(

LPCRITICAL_SECTION lpCriticalSection	// pointer to critical section object
);
Parameters

lpCriticalSection

Points to the critical section object.

Return Values

This function does not return a value.

Remarks

The threads of a single process can use a critical section object for mutual-exclusion synchronization. The process is responsible for allocating the memory used by a critical section object, which it can do by declaring a variable of type CRITICAL_SECTION. Before using a critical section, some thread of the process must call the InitializeCriticalSection function to initialize the object.

To enable mutually exclusive access to a shared resource, each thread calls the EnterCriticalSection or TryEnterCriticalSection function to request ownership of the critical section before executing any section of code that accesses the protected resource. The difference is that TryEnterCriticalSection returns immediately, regardless of whether it obtained ownership of the critical section, while EnterCriticalSection blocks until the thread can take ownership of the critical section. When it has finished executing the protected code, the thread uses the LeaveCriticalSection function to relinquish ownership, enabling another thread to become owner and access the protected resource. The thread must call LeaveCriticalSection once for each time that it entered the critical section. The thread enters the critical section each time EnterCriticalSection and TryEnterCriticalSection succeed.

Once a thread has ownership of a critical section, it can make additional calls to EnterCriticalSection or TryEnterCriticalSection without blocking its execution. This prevents a thread from deadlocking itself while waiting for a critical section that it already owns.

Any thread of the process can use the DeleteCriticalSection function to release the system resources that were allocated when the critical section object was initialized. After this function has been called, the critical section object can no longer be used for synchronization.

See Also

DeleteCriticalSection, InitializeCriticalSection, LeaveCriticalSection TryEnterCriticalSection


EnumCalendarInfo

The EnumCalendarInfo function enumerates calendar information for a specified locale. The CalType parameter specifies the type of calendar information to enumerate. The function returns the specified calendar information for all applicable calendars for the locale, or for a single requested calendar, depending on the value of the Calendar parameter.

The EnumCalendarInfo function enumerates the calendar information by calling an application-defined callback function. It passes the callback function a pointer to a string buffer containing the requested calendar information. This continues until either the last applicable calendar is found or the callback function returns FALSE.

BOOL EnumCalendarInfo(

CALINFO_ENUMPROC lpCalInfoEnumProc,	// pointer to enumeration callback function
LCID Locale,	// locale whose calendar information is of interest
CALID Calendar,	// calendar whose information is of interest
CALTYPE CalType	// type of calendar information of interest
);
Parameters

lpCalInfoEnumProc

Points to an application-defined callback function. For more information, see the EnumCalendarInfoProc callback function.

Locale

Specifies the locale to retrieve calendar information for. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
Calendar

Specifies the calendar for which information is requested. The following values are defined:

Value	Meaning
ENUM_ALL_CALENDARS	Enumerate all applicable calendars for the locale specified by Locale.
1	Gregorian (localized)
2	Gregorian (English strings always)
3	Japanese era
4	Year of the Republic of China
5	Tangun Era (Korea)
CalType

Indicates the type of calendar information to be returned.  Note that only one CALTYPE value can be specified per call of this 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 one of the following error codes:

ERROR_BADDB
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER

See Also

EnumCalendarInfoProc, EnumDateFormats


EnumCalendarInfoProc

An EnumCalendarInfoProc function is an application-defined callback function. It is called as a result of a call to the EnumCalendarInfo function, and receives a pointer to a string buffer containing a calendar information string.

BOOL CALLBACK EnumCalendarInfoProc(

LPTSTR lpCalendarInfoString	// pointer to calendar information string
);
Parameters

lpCalendarInfoString

Pointer to a string buffer containing a null-terminated calendar information string. This string is formatted according to the CALTYPE value passed to EnumCalendarInfo. Note that lpCalendarInfoString should be an LPWSTR for the Unicode (W) version of EnumCalendarInfo, and an LPSTR for the ANSI (A) version of EnumCalendarInfo.

Return Values

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

EnumCalendarInfoProc is a placeholder for an application-defined function name.

An EnumCalendarInfoProc function can carry out any desired task.

An application registers an EnumCalendarInfoProc function by passing its address to the EnumCalendarInfo function.

A value of type CALINFO_ENUMPROC is a pointer to an EnumCalendarInfoProc function.

See Also

EnumCalendarInfo


EnumChildProc

The EnumChildProc function is an application-defined callback function that receives child window handles as a result of a call to the EnumChildWindows function.

BOOL CALLBACK EnumChildProc(

HWND hwnd,	// handle to child window
LPARAM lParam	// application-defined value
);
Parameters

hwnd

Identifies a child window of the parent window specified in EnumChildWindows.

lParam

Specifies the application-defined value given in EnumChildWindows.

Return Values

To continue enumeration, the callback function must return TRUE; to stop enumeration, it must return FALSE.

Remarks

The callback function can carry out any desired task.

An application must register this callback function by passing its address to EnumChildWindows. EnumChildProc is a placeholder for the application-defined function name.

See Also

EnumChildWindows


EnumChildWindows

The EnumChildWindows function enumerates the child windows that belong to the specified parent window by passing the handle of each child window, in turn, to an application-defined callback function. EnumChildWindows continues until the last child window is enumerated or the callback function returns FALSE.

BOOL EnumChildWindows(

HWND hWndParent,	// handle to parent window
WNDENUMPROC lpEnumFunc,	// pointer to callback function
LPARAM lParam	// application-defined value
);
Parameters

hWndParent

Identifies the parent window whose child windows are to be enumerated.

lpEnumFunc

Points to an application-defined callback function. For more information about the callback function, see the EnumChildProc callback function.

lParam

Specifies a 32-bit, application-defined value to be passed to the callback function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The EnumChildWindows function does not enumerate top-level windows owned by the specified window, nor does it enumerate any other owned windows.

If a child window has created child windows of its own, this function enumerates those windows as well.

A child window that is moved or repositioned in the Z order during the enumeration process will be properly enumerated. The function does not enumerate a child window that is destroyed before being enumerated or that is created during the enumeration process.

This function is more reliable than calling the GetWindow function in a loop. An application that calls GetWindow to perform this task risks being caught in an infinite loop or referencing a handle to a window that has been destroyed.

See Also

EnumChildProc, EnumThreadWindows, EnumWindows, GetWindow


EnumClipboardFormats

The EnumClipboardFormats function lets you enumerate the data formats that are currently available on the clipboard.

Clipboard data formats are stored in an ordered list. To perform an enumeration of clipboard data formats, you make a series of calls to the EnumClipboardFormats function. For each call, the format parameter specifies an available clipboard format, and the function returns the next available clipboard format.

UINT EnumClipboardFormats(

UINT format	// specifies a known available clipboard format
);
Parameters

format

Specifies a clipboard format that is known to be available.

To start an enumeration of clipboard formats, set format to zero. When format is zero, the function retrieves the first available clipboard format. For subsequent calls during an enumeration, set format to the result of the previous EnumClipboardFormat call.

Return Values

If the function succeeds, the return value is the clipboard format that follows the specified format. In other words, the next available clipboard format.

If the function fails, the return value is zero. To get extended error information, call GetLastError. If the clipboard is not open, the function fails.

If there are no more clipboard formats to enumerate, the return value is zero. In this case, the GetLastError function returns the value NO_ERROR. This lets you distinguish between function failure and the end of enumeration.

Remarks

You must open the clipboard before enumerating its formats. Use the OpenClipboard function to open the clipboard. The EnumClipboardFormats function fails if the clipboard is not open.

The EnumClipboardFormats function enumerates formats in the order that they were placed on the clipboard. If you are copying information to the clipboard, add clipboard objects in order from the most descriptive clipboard format to the least descriptive clipboard format. If you are pasting information from the clipboard, retrieve the first clipboard format that you can handle. That will be the most descriptive clipboard format that you can handle.

The operating system provides automatic type conversions for certain clipboard formats. In the case of such a format, this function enumerates the specified format, then enumerates the formats to which it can be converted. For more information about clipboard formats and automatic clipboard format type conversions, see the GetClipboardData and SetClipboardData functions.

See Also

CountClipboardFormats, GetClipboardData, OpenClipboard, RegisterClipboardFormat, SetClipboardData


EnumCodePagesProc

An EnumCodePagesProc function is an application-defined callback function. It is called as a result of a call to the EnumSystemCodePages function, and receives a pointer to a string buffer containing a code page identifier.

BOOL CALLBACK EnumCodePagesProc(

LPTSTR lpCodePageString	// pointer to code page identifier string
);
Parameters

lpCodePageString

Pointer to a string buffer containing a null-terminated code page identifier string.

Return Values

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

EnumCodePagesProc is a placeholder for an application-defined function name.

An EnumCodePagesProc function can carry out any desired task.

An application registers an EnumCodePagesProc function by passing its address to the EnumSystemCodePages function.

A value of type CODEPAGE_ENUMPROC is a pointer to an EnumCodePagesProc function.

See Also

EnumSystemCodePages


EnumDateFormats

The EnumDateFormats function enumerates the long or short date formats that are available for a specified locale, including date formats for any alternate calendars. The value of the dwFlags parameter determines whether the long or short date formats are enumerated. The function enumerates the date formats by passing date format string pointers, one at a time, to the specified application-defined callback function. This continues until the last date format is found or the callback function returns FALSE.

BOOL EnumDateFormats(

DATEFMT_ENUMPROC lpDateFmtEnumProc,	// pointer to enumeration callback function
LCID Locale,	// locale whose date formats are of interest
DWORD dwFlags	// date formats to enumerate
);
Parameters

lpDateFmtEnumProc

Points to an application-defined callback function. The EnumDateFormats function enumerates date formats by making repeated calls to this callback function. For more information, see the EnumDateFormatsProc callback function.

Locale

Specifies the locale to retrieve date format information for. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
dwFlags

Specifies the date formats that are of interest. Use one of the following values:

Value	Meaning
DATE_SHORTDATE	Return short date formats.
DATE_LONGDATE	Return long date formats.
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 one of the following error codes:

ERROR_INVALID_PARAMETER
ERROR_BADDB
ERROR_INVALID FLAGS

Remarks

The DATE_SHORTDATE and DATE_LONGDATE flags are mutually exclusive. Use one or the other, but not both.

See Also

EnumDateFormatsProc, EnumCalendarInfo, EnumTimeFormats


EnumDateFormatsProc

An EnumDateFormatsProc function is an application-defined callback function. It is called as a result of a call to the EnumDateFormats function, and receives a pointer to a string buffer containing a date format string.

BOOL CALLBACK EnumDateFormatsProc(

LPTSTR lpDateFormatString	// pointer to date format string
);
Parameters

lpDateFormatString

Pointer to a string buffer containing a null-terminated date format string. This string is a long or short date format, depending on the value of the dwFlags parameter passed to EnumDateFormats. Note that lpDateFormatString should be an LPWSTR for the Unicode (W) version of EnumDateFormats, and an LPSTR for the ANSI (A) version of EnumDateFormats.

Return Values

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

EnumDateFormatsProc is a placeholder for an application-defined function name.

An EnumDateFormatsProc function can carry out any desired task.

An application registers an EnumDateFormatsProc function by passing its address to the EnumDateFormats function.

A value of type DATEFMT_ENUMPROC is a pointer to an EnumDateFormatsProc function.

See Also

EnumDateFormats


EnumDependentServices

The EnumDependentServices function enumerates services that depend on another specified service; that is, the specified service must be running before the enumerated services can run. The name and status of each dependent service are provided.

BOOL EnumDependentServices(

SC_HANDLE hService,	// handle to service
DWORD dwServiceState,	// state of services to enumerate
LPENUM_SERVICE_STATUS lpServices,	// pointer to service status buffer
DWORD cbBufSize,	// size of service status buffer
LPDWORD pcbBytesNeeded,	// pointer to variable for bytes needed
LPDWORD lpServicesReturned	// pointer to variable for number returned
);
Parameters

hService

Handle that identifies the service. This handle is returned by the OpenService or CreateService function, and it must have SERVICE_ENUMERATE_DEPENDENTS access.

dwServiceState

Specifies the services to enumerate based on their running state. It must be one or both of the following values:

Value	Meaning
SERVICE_ACTIVE	Enumerates services that are in the following states: SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_RUNNING, SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING, and SERVICE_PAUSED.
SERVICE_INACTIVE	Enumerates services that are in the SERVICE_STOPPED state.
lpServices

Pointer to an array of ENUM_SERVICE_STATUS structures. Each structure receives name and service status information for a dependent service. The order of the services in this array is the reverse of the start order of the services. In other words, the first dependent service in the array is the one that would be started last, and the last service in the array is the one that would be started first.

cbBufSize

Specifies the size, in bytes, of the buffer pointed to by the lpServices parameter.

pcbBytesNeeded

Pointer to a variable that receives the number of bytes needed to store the array of service entries. The variable only receives this value if the buffer pointed to by lpServices is too small, indicated by function failure and the ERROR_MORE_DATA error; otherwise, the contents of *pcbBytesNeeded are undefined.

lpServicesReturned

Pointer to a variable that receives the number of service entries returned.

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.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED
	The specified handle was not opened with SERVICE_ENUMERATE_DEPENDENTS access.
ERROR_INVALID_HANDLE
	The specified handle is invalid.
ERROR_INVALID_PARAMETER
	A parameter that was specified is invalid.
ERROR_MORE_DATA
	The buffer pointed to by lpServices is not large enough. The function sets the variable pointed to by lpServicesReturned to the actual number of service entries stored into the buffer. The function sets the variable pointed to by pcbBytesNeeded to the number of bytes required to store all of the service entries.
Remarks

The returned services entries are ordered in the reverse order of the start order, with group order taken into account. If you need to stop the dependent services, you can use the order of entries written to the lpServices buffer to stop the dependent services in the proper order.

See Also

CreateService, ENUM_SERVICE_STATUS, EnumServicesStatus, OpenService


EnumDesktopProc

The EnumDesktopProc function is an application-defined callback function that receives a desktop name as a result of a call to the EnumDesktops function.

BOOL CALLBACK EnumDesktopProc(

LPTSTR lpszDesktop,	// name of a desktop
LPARAM lParam	// value specified in EnumDesktops call
);
Parameters

lpszDesktop

Points to the null-terminated name of a desktop.

lParam

Specifies the application-defined value given in the EnumDesktops function.

Return Values

To continue enumeration, the callback function must return TRUE. To stop enumeration, it must return FALSE.

Remarks

The EnumDesktopProc function is a placeholder for the application-defined function name. The DESKTOPENUMPROC type is a pointer to an EnumDesktopProc function.

See Also

EnumDesktops


EnumDesktops

The EnumDesktops function enumerates all desktops in the window station assigned to the calling process. The function does so by passing the name of each desktop, in turn, to an application-defined callback function.

BOOL EnumDesktops(

HWINSTA hwinsta,	// handle to window station to enumerate
DESKTOPENUMPROC lpEnumFunc,	// points to application’s callback function
LPARAM lParam	// 32-bit value to pass to the callback function
);
Parameters

hwinsta

Specifies the handle to the window station whose desktops are to be enumerated. The CreateWindowStation, GetProcessWindowStation, and OpenWindowStation functions return a window station handle.

lpEnumFunc

Points to an application-defined EnumDesktopProc callback function.

dwDesiredAccess

Specifies a 32-bit application-defined value to be passed to the callback 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.

Remarks

The calling process must have WINSTA_ENUMDESKTOPS access to the window station. The EnumDesktops function enumerates only those desktops for which the calling process has DESKTOP_ENUMERATE access.

The EnumDesktops function repeatedly invokes the lpEnumFunc callback function until the last desktop is enumerated or the callback function returns FALSE.

See Also

CreateWindowStation, EnumDesktopProc, GetProcessWindowStation, OpenWindowStation


EnumDesktopWindows

The EnumDesktopWindows function enumerates all windows in a desktop by passing the handle of each window, in turn, to an application-defined callback function.

BOOL EnumDesktopWindows(

HDESK hDesktop,	// handle to desktop to enumerate
WNDENUMPROC lpfn,	// points to application’s callback function
LPARAM lParam	// 32-bit value to pass to the callback function
);
Parameters

hDesktop

Specifies the handle to the desktop whose windows are to be enumerated. The CreateDesktop, OpenDesktop, and GetThreadDesktop functions return a desktop handle.

lpfn

Points to an application-defined EnumWindowsProc callback function.

lParam

Specifies a 32-bit application-defined value to be passed to the callback 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.

Remarks

The EnumDesktopWindows function repeatedly invokes the lpfn callback function until the last window is enumerated or the callback function returns FALSE.

See Also

CreateDesktop, EnumWindowsProc, GetThreadDesktop, OpenDesktop


EnumDisplaySettings

The EnumDisplaySettings function obtains information about one of a display device’s graphics modes. You can obtain information for all of a display device’s graphics modes by making a series of calls to this function.

BOOL EnumDisplaySettings(

LPCTSTR lpszDeviceName,	// specifies the display device
DWORD iModeNum,	// specifies the graphics mode
LPDEVMODE lpDevMode	// points to structure to receive settings
);
Parameters

lpszDeviceName

Pointer to a null-terminated string that specifies the display device whose graphics mode the function will obtain information about.

This parameter can be NULL. A NULL value specifies the current display device on the computer that the calling thread is running on.

If lpszDeviceName is not NULL, the string must be of the form \\.\DisplayX, where X can have the values 1, 2, or 3.

Windows 95: lpszDeviceName must be NULL.

iModeNum

Index value that specifies the graphics mode for which information is to be obtained.

Graphics mode indexes start at zero. To obtain information for all of a display device’s graphics modes, make a series of calls to EnumDisplaySettings, as follows: Set iModeNum to zero for the first call, and increment iModeNum by one for each subsequent call. Continue calling the function until the return value is FALSE.

When you call EnumDisplaySettings with iModeNum set to zero, the operating system initializes and caches information about the display device. When you call EnumDisplaySettings with iModeNum set to a non-zero value, the function returns the information that was cached the last time the function was called with iModeNum set to zero.

lpDevMode

Pointer to a DEVMODE structure into which the function stores information about the specified graphics mode.

The EnumDisplaySettings function sets values for the following five DEVMODE members:

dmBitsPerPel
dmPelsWidth
dmPelsHeight
dmDisplayFlags
dmDisplayFrequency

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

The function fails if iModeNum is greater than the index of the display device’s last graphics mode. As noted in the description of the iModeNum parameter, you can use this behavior to enumerate all of a display device’s graphics modes.

See Also

ChangeDisplaySettings, CreateDC, CreateDesktop, DEVMODE


EnumEnhMetaFile

The EnumEnhMetaFile function enumerates the records within an enhanced-format metafile by retrieving each record and passing it to the specified callback function. The application-supplied callback function processes each record as required. The enumeration continues until the last record is processed or when the callback function returns zero.

BOOL EnumEnhMetaFile(

HDC hdc,	// handle to device context
HENHMETAFILE hemf,	// handle to enhanced metafile
ENHMFENUMPROC lpEnhMetaFunc,	// pointer to callback function
LPVOID lpData,	// pointer to callback-function data
CONST RECT *lpRect	// pointer to bounding rectangle
);
Parameters

hdc

Identifies a device context. This handle is passed to the callback function.

hemf

Identifies an enhanced metafile.

lpEnhMetaFunc

Points to the application-supplied callback function. For more information, see the EnhMetaFileProc function.

lpData

Points to optional callback-function data.

lpRect

Points to a RECT structure that specifies the coordinates of the picture’s upper-left and lower-right corners. The dimensions of this rectangle are specified in logical units.

Return Values

If the callback function successfully enumerates all the records in the enhanced metafile, the return value is nonzero.

If the callback function does not successfully enumerate all the records in the enhanced metafile, the return value is zero.

Remarks

Points along the edge of the rectangle pointed to by the lpRect parameter are included in the picture. If the hdc parameter is NULL, Windows ignores lpRect.

If the callback function calls the PlayEnhMetaFileRecord function, hdc must identify a valid device context. Windows uses the device context’s transformation and mapping mode to transform the picture displayed by the PlayEnhMetaFileRecord function.

You can use the EnumEnhMetaFile function to embed one enhanced-metafile within another.

See Also

EnhMetaFileProc, PlayEnhMetaFile, PlayEnhMetaFileRecord, RECT


EnumFontFamExProc [Now Supported on Windows NT]
EnumFontFamExProc

[Now Supported on Windows NT]

The EnumFontFamExProc function is an application-supplied callback function that processes the fonts enumerated by the EnumFontFamiliesEx function. The system calls this callback function once for each enumerated font.

int CALLBACK EnumFontFamExProc(

ENUMLOGFONTEX *lpelfe,	// pointer to logical-font data
NEWTEXTMETRICEX *lpntme,	// pointer to physical-font data
int FontType,	// type of font
LPARAM lParam	// application-defined data
);
Parameters

lpelfe

Points to an ENUMLOGFONTEX structure that contains information about the logical attributes of the font.

lpntme

Points to a structure that contains information about the physical attributes of a font. The function uses the NEWTEXTMETRICEX structure for TrueType fonts; and the TEXTMETRIC structure for other fonts.

Windows 95: The NEWTEXTMETRICEX structure is not implemented. Use NEWTEXTMETRIC instead.

FontType

Specifies the type of the font. This parameter can be a combination of these values:

DEVICE_FONTTYPE
RASTER_FONTTYPE
TRUETYPE_FONTTYPE

lParam

Specifies the application-defined data passed by the EnumFontFamiliesEx function.

Return Values

The return value must be a nonzero value to continue enumeration; to stop enumeration, the return value must be zero.

Remarks

Unlike the EnumFontFamProc callback function, EnumFontFamExProc receives extended information about a font. The ENUMLOGFONTEX structure includes the localized name of the script (character set) and the NEWTEXTMETRICEX structure includes a font-coverage signature.

See Also

EnumFontFamiliesEx, EnumFontFamProc, ENUMLOGFONTEX, NEWTEXTMETRICEX, TEXTMETRIC


EnumFontFamilies

The EnumFontFamilies function enumerates the fonts in a specified font family that are available on a specified device. This function supersedes the EnumFonts function.

int EnumFontFamilies(

HDC hdc,	// handle to device control
LPCTSTR lpszFamily,	// pointer to family-name string
FONTENUMPROC lpEnumFontFamProc,	// pointer to callback function
LPARAM lParam	// address of application-supplied data
);
Parameters

hdc

Identifies the device context.

lpszFamily

Points to a null-terminated string that specifies the family name of the desired fonts. If lpszFamily is NULL, EnumFontFamilies randomly selects and enumerates one font of each available type family.

lpEnumFontFamProc

Specifies the procedure-instance address of the application-defined callback function. For information about the callback function, see the EnumFontFamProc function.

lParam

Points to application-supplied data. The data is passed to the callback function along with the font information.

Return Values

If the function succeeds, the return value is the last value returned by the callback function. Its meaning is implementation specific.

Remarks

The EnumFontFamilies function differs from the EnumFonts function in that it retrieves the style names associated with a TrueType font. With EnumFontFamilies, information can be retrieved about unusual font styles (for example, Outline) that could not be enumerated by using the EnumFonts function. Win32-based applications should use EnumFontFamilies instead of EnumFonts.

For each font having the typeface name specified by the lpszFamily parameter, the EnumFontFamilies function retrieves information about that font and passes it to the function pointed to by the lpEnumFontFamProc parameter. The application-defined callback function can process the font information as desired. Enumeration continues until there are no more fonts or the callback function returns zero.

See Also

EnumFontFamProc, EnumFonts


EnumFontFamiliesEx [Now Supported on Windows NT]
EnumFontFamiliesEx

[Now Supported on Windows NT]

The EnumFontFamiliesEx function enumerates all fonts in the system that match the font characteristics specified by the LOGFONT structure. EnumFontFamiliesEx enumerates fonts based on typeface name, character set, or both. It is recommended that Win32-based applications use this function rather than EnumFontFamilies to enumerate fonts.

int EnumFontFamiliesEx(

HDC hdc,	// handle to device context
LPLOGFONT lpLogfont,	// pointer to logical font information
FONTENUMPROC lpEnumFontFamExProc,	// pointer to callback function
LPARAM lParam,	// application-supplied data
DWORD dwFlags	// reserved; must be zero
);
Parameters

hdc

Identifies the device context.

lpLogfont

Points to a LOGFONT structure that contains information about the fonts to enumerate. The function examines these members:

Member	Description
lfCharset	If set to DEFAULT_CHARSET, the function enumerates all fonts in all character sets. If set to a valid character set value, the function enumerates only fonts in the specified character set.
lfFaceName	If set to an empty string, the function enumerates one font in each available typeface name. If set to a valid typeface name, the function enumerates all fonts with the specified name.
lfPitchAndFamily	Must be set to zero for all language versions of the operating system except Hebrew and Arabic. For these languages, set IfPitchAndFamily to MONO_FONT to enumerate only fonts that provide all codepage characters within the font.
lpEnumFontFamExProc

Points to the application-defined callback function. For more information about the callback function, see the EnumFontFamExProc function.

lParam

Specifies a 32-bit application-defined value. The function passes this value to the callback function along with font information.

dwFlags

Reserved; must be zero.

Return Values

If the function succeeds, the return value is the last value returned by the callback function. This value depends on which font families are available for the specified device.

Remarks

EnumFontFamiliesEx does not use “tagged” typeface names to identify character sets. Instead, it always passes the correct typeface name and a separate character set value to the callback function. The function enumerates fonts based on the the values of the lfCharset and lfFacename members in the LOGFONT structure.

If lfCharset is DEFAULT_CHARSET and lfFaceName is an empty string, the function enumerates one font in every face in every character set. If lfFaceName is not empty, the function enumerates every font in the specified typeface regardless of character set.

If lfCharset is a valid character set value and lfFaceName is an empty string, the function enumerates every font in the specified character set. If lfFaceName is not empty, the function enumerates every font having the specified typeface and character set.

See Also

EnumFontFamilies, EnumFontFamExProc, LOGFONT


EnumFontFamProc

The EnumFontFamProc function is an application-defined callback function that retrieves data describing available fonts.

int CALLBACK EnumFontFamProc(

ENUMLOGFONT FAR *lpelf,	// pointer to logical-font data
NEWTEXTMETRIC FAR *lpntm,	// pointer to physical-font data
int FontType,	// type of font
LPARAM lParam	// address of application-defined data
);
Parameters

lpelf

Points to an ENUMLOGFONT structure that contains information about the logical attributes of the font. This structure is locally defined.

lpntm

Points to a NEWTEXTMETRIC structure that contains information about the physical attributes of the font, if the font is a TrueType font. If the font is not a TrueType font, this parameter points to a TEXTMETRIC structure.

FontType

Specifies the type of the font. This parameter can be a combination of the following values:

DEVICE_FONTTYPE
RASTER_FONTTYPE
TRUETYPE_FONTTYPE

lParam

Points to the application-defined data passed by the EnumFontFamilies function.

Return Values

The return value must be a nonzero value to continue enumeration; to stop enumeration, it must return zero.

Remarks

An application must register this callback function by passing its address to the EnumFontFamilies function.

The EnumFontFamProc function is a placeholder for the application-defined function name.

The AND (&) operator can be used with the RASTER_FONTTYPE, DEVICE_FONTTYPE, and TRUETYPE_FONTTYPE constants to determine the font type. If the RASTER_FONTTYPE bit is set, the font is a raster font. If the TRUETYPE_FONTTYPE bit is set, the font is a TrueType font. If neither bit is set, the font is a vector font. DEVICE_FONTTYPE is set when a device (for example, a laser printer) supports downloading TrueType fonts or when the font is a device-resident font; it is zero if the device is a display adapter, dot-matrix printer, or other raster device. An application can also use DEVICE_FONTTYPE to distinguish graphics device interface (GDI)-supplied raster fonts from device-supplied fonts. GDI can simulate bold, italic, underline, and strikeout attributes for GDI-supplied raster fonts, but not for device-supplied fonts.

See Also

EnumFontFamilies, EnumFontFamProc, EnumFonts, ENUMLOGFONT, NEWTEXTMETRIC, TEXTMETRIC


EnumFonts

The EnumFonts function enumerates the fonts available on a specified device. For each font with the specified typeface name, the EnumFonts function retrieves information about that font and passes it to the application-defined callback function. This callback function can process the font information as desired. Enumeration continues until there are no more fonts or the callback function returns zero.

This function is provided for compatibility with earlier versions of Microsoft Windows. Win32-based applications should use the EnumFontFamilies function.

int EnumFonts(

HDC hdc,	// handle to device context
LPCTSTR lpFaceName,	// pointer to font typeface name string
FONTENUMPROC lpFontFunc,	// pointer to callback function
LPARAM lParam	// address of application-supplied data
);
Parameters

hdc

Identifies the device context.

lpFaceName

Points to a null-terminated character string that specifies the typeface name of the desired fonts. If lpFaceName is NULL, EnumFonts randomly selects and enumerates one font of each available typeface.

lpFontFunc

Points to the application-defined callback function. For more information about the callback function, see the EnumFontsProc function.

lParam

Points to any application-defined data. The data is passed to the callback function along with the font information.

Return Values

If the function succeeds, the return value is the last value returned by the callback function. Its meaning is defined by the application.

Remarks

Use EnumFontFamilies instead of EnumFonts. The EnumFontFamilies function differs from the EnumFonts function in that it retrieves the style names associated with a TrueType font. With EnumFontFamilies, you can retrieve information about unusual font styles (for example, Outline) that cannot be enumerated using the EnumFonts function.

See Also

EnumFontFamilies, EnumFontsProc, GetDeviceCaps


EnumFontsProc

The EnumFontsProc function is an application-defined callback function that processes font data from the EnumFonts function.

int CALLBACK EnumFontsProc(

lplf lplf,	// pointer to logical-font data
lptm lptm,	// pointer to physical-font data
DWORD dwType,	// font type
LPARAM lpData	// pointer to application-defined data
);
Parameters

lplf

Points to a LOGFONT structure that contains information about the logical attributes of the font.

lptm

Points to a TEXTMETRIC structure that contains information about the physical attributes of the font.

dwType

Specifies the type of the font. This parameter can be a combination of the following values:

DEVICE_FONTTYPE
RASTER_FONTTYPE
TRUETYPE_FONTTYPE

lpData

Points to the application-defined data passed by EnumFonts.

Return Values

The return value must be a nonzero value to continue enumeration; to stop enumeration, it must be zero.

Remarks

The AND (&) operator can be used with the RASTER_FONTTYPE and DEVICE_FONTTYPE constants to determine the font type. The RASTER_FONTTYPE bit of the FontType parameter specifies whether the font is a raster or vector font. If the bit is one, the font is a raster font; if zero, it is a vector font. The DEVICE_FONTTYPE bit of FontType specifies whether the font is a device-based or graphics device interface (GDI)-based font. If the bit is one, the font is a device-based font; if zero, it is a GDI-based font.

If the device is capable of text transformations (scaling, italicizing, and so on) only the base font is enumerated. The user must inquire into the device’s text-transformation abilities to determine which additional fonts are available directly from the device.

An application must register the EnumFontsProc function by passing its address to the EnumFonts function.

EnumFontsProc is a placeholder for the application-defined function name.

See Also

EnumFonts, LOGFONT, TEXTMETRIC


EnumForms

The EnumForms function enumerates the forms supported by the specified printer.

BOOL EnumForms(

HANDLE hPrinter,	// handle to printer object
DWORD Level,	// data-structure level
LPBYTE pForm,	// points to buffer that receives form info. structure array
DWORD cbBuf,	// count of bytes in buffer
LPDWORD pcbNeeded,	// points to variable to receive count of bytes copied or required
LPDWORD pcReturned	// points to variable to receive count of structures copied
);
Parameters

hPrinter

Identifies the printer for which the forms should be enumerated.

Level

Specifies the version of the structure to which pForm points. This value must be 1.

pForm

Points to a FORM_INFO_1 structure.

cbBuf

Specifies the size, in bytes, of the buffer to which pForm points.

pcbNeeded

Points to a variable that receives the number of bytes copied to or the number of bytes required for the array to which pForm points. If cbBuf is too small, this value specifies the number of bytes required; otherwise, this value specifies the number of bytes copied.

pcReturned

Points to a variable that receives the number of FORM_INFO_1 structures copied into the array to which pForm points.

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.

Remarks

The printer-object handle hPrinter is normally obtained by calling the OpenPrinter function. The AddPrinter function can also be used.

See Also

AddPrinter, FORM_INFO_1, OpenPrinter


EnumICMProfiles

The EnumICMProfiles function enumerates the different color profiles that the system supports for the specified device context.

int EnumICMProfiles(

HDC hdc,
ICMENUMPROC lpICMEnumFunc,
LPARAM lParam
);
Parameters

hdc

Handle to the device context.

lpICMEnumFunc

Pointer to the application-defined callback function. For more information, see the EnumICMProfilesProc function.

lParam

Application-supplied data. The data is passed to the callback function along with the color profile information.

Return Values

Returns −1 if there are no color profiles to enumerate or image color matching is not enabled. Otherwise, it returns the last value returned by the callback function, which may be zero if the callback interrupted the enumeration.

See Also

EnumICMProfilesProc


EnumICMProfilesProc

The EnumICMProfilesProc function is an application-defined callback function that processes color profile data from the EnumICMProfiles function.

int CALLBACK EnumICMProfilesProc(

LPTSTR lpszFilename,
LPARAM lParam
);
Parameters

lpszFilename

Pointer to a null-terminated string specifying the name of the color profile file.

lParam

Application-supplied data passed by the EnumICMProfiles function.

Return Values

Returns a positive value to continue enumeration, or 0 to stop enumeration. The function must not return a negative value.

See Also

EnumICMProfiles


EnumJobs

The EnumJobs function initializes an array of either JOB_INFO_1 or JOB_INFO_2 structures with data describing the specified print jobs for the specified printer.

BOOL EnumJobs(

HANDLE hPrinter,	// handle to printer object
DWORD FirstJob,	// location of first job in print queue to enumerate
DWORD NoJobs,	// number of jobs to enumerate
DWORD Level,	// structure level
LPBYTE pJob,	// pointer to structure array
DWORD cbBuf,	// size of array, in bytes
LPDWORD pcbNeeded,	// addr. of variable with no. of bytes copied (or required)
LPDWORD pcReturned	// addr. of variable with no. of job info. structures copied
);
Parameters

hPrinter

Handle to the printer object whose print jobs the function will enumerate.

FirstJob

Specifies the zero-based position within the print queue of the first print job to enumerate. For example, a value of 0 specifies that enumeration should begin at the first print job in the print queue; a value of 9 specifies that enumeration should begin at the tenth print job in the print queue.

NoJobs

Specifies the total number of print jobs to enumerate.

Level

Specifies whether the function should use JOB_INFO_1 or JOB_INFO_2 structures to store data for the enumerated jobs. A value of 1 specifies that the JOB_INFO_1 structure should be used; a value of 2 specifies that the JOB_INFO_2 structure should be used.

pJob

Points to an array of either JOB_INFO_1 or JOB_INFO_2 structures.

cbBuf

Specifies the size, in bytes, of the array pJob.

pcbNeeded

Points to a variable that receives the number of bytes copied if the function succeeds. If the function fails, the variable receives the number of bytes required.

pcReturned

Points to a variable that receives the number of JOB_INFO_1 or JOB_INFO_2 structures that were initialized.

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.

Remarks

The handle hPrinter is obtained by calling the OpenPrinter function.

The JOB_INFO_1 structure contains general print-job information; the JOB_INFO_2 structure has much more detailed information.

See Also

GetJob, JOB_INFO_1, JOB_INFO_2, OpenPrinter, SetJob


EnumLocalesProc

An EnumLocalesProc function is an application-defined callback function. It is called as a result of a call to the EnumSystemLocales function, and receives a pointer to a string buffer containing a locale identifier.

BOOL CALLBACK EnumLocalesProc(

LPTSTR lpLocaleString	// pointer to locale identifier string
);
Parameters

lpLocaleString

Pointer to a string buffer containing a null-terminated locale identifier string. Note that lpLocaleString should be an LPWSTR for the Unicode (W) version of EnumLocalesProc, and an LPSTR for the ANSI (A) version of EnumLocalesProc.

Return Values

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

EnumLocalesProc is a placeholder for an application-defined function name.

An application registers an EnumLocalesProc function by passing its address to the EnumSystemLocales function.

A value of type LOCALE_ENUMPROC is a pointer to an EnumLocalesProc function.

See Also

EnumSystemLocales


EnumMetaFile

The EnumMetaFile function enumerates the records within a Windows-format metafile by retrieving each record and passing it to the specified callback function. The application-supplied callback function processes each record as required. The enumeration continues until the last record is processed or when the callback function returns zero.

This function is provided for compatibility with earlier versions of Microsoft Windows. Win32-based applications should use the EnumEnhMetaFile function.

BOOL EnumMetaFile(

HDC hdc,	// handle to device context
HMETAFILE hmf,	// handle to Windows-format metafile
MFENUMPROC lpMetaFunc,	// pointer to callback function
LPARAM lParam	// address of callback function data
);
Parameters

hdc

Identifies a device context. This handle is passed to the callback function.

hmf

Identifies a Windows-format metafile.

lpMetaFunc

Points to an application-supplied callback function. For more information, see the EnumMetaFileProc callback function.

lParam

Points to optional callback-function data.

Return Values

If the callback function successfully enumerates all the records in the Windows-format metafile, the return value is nonzero.

If the callback function does not successfully enumerate all the records in the Windows-format metafile, the return value is zero.

Remarks

A Windows-format metafile does not support the new curve, path, and transformation functions, such as PolyBezier, BeginPath, and SetWorldTransform. Applications that use these new functions and use metafiles to store pictures created by these functions should use the enhanced-format metafile functions.

To convert a Windows-format metafile into an enhanced-format metafile, use the SetWinMetaFileBits function.

You can use the EnumMetaFile function to embed one Windows-format metafile within another.

See Also

BeginPath, EnumEnhMetaFile, EnumMetaFileProc, PlayMetaFile, PlayMetaFileRecord, PolyBezier, SetWinMetaFileBits, SetWorldTransform


EnumMetaFileProc

The EnumMetaFileProc function is an application-defined callback function that processes Windows-format metafile records. This function is called by the EnumMetaFile function.

This function is provided for compatibility with earlier versions of Microsoft Windows. Win32-based applications should use the EnhMetaFileProc and EnumEnhMetaFile functions.

int CALLBACK EnumMetaFileProc(

HDC hDC,	// handle to device context
HANDLETABLE FAR *lpHTable,	// pointer to metafile handle table
METARECORD FAR *lpMFR,	// pointer to metafile record
int nObj,	// count of objects
LPARAM lpClientData	// pointer to optional data
);
Parameters

hDC

Identifies the device context passed to EnumMetaFile.

lpHTable

Points to a table of handles associated with the graphics objects (pens, brushes, and so on) in the metafile.

lpMFR

Points to one of the records in the metafile. This record should not be modified. (If modification is necessary, it should be performed on a copy of the record.)

nObj

Specifies the number of objects with associated handles in the handle table.

lpClientData

Points to any application-supplied data.

Return Values

This function must return a nonzero value to continue enumeration; to stop enumeration, it must return zero.

Remarks

An application must register the callback function by passing its address to the EnumMetaFile function.

EnumMetaFileProc is a placeholder for the application-supplied function name.

See Also

EnhMetaFileProc, EnumEnhMetaFile, EnumMetaFile


EnumMonitors

The EnumMonitors function initializes an array of structures with data describing the monitors for the specified server.

BOOL EnumMonitors(

LPTSTR pName,	// pointer to server name
DWORD Level,	// structure level
LPBYTE pMonitors,	// pointer to structure array
DWORD cbBuf,	// size, in bytes, of buffer
LPDWORD pcbNeeded,	// addr. of variable with no. of bytes copied (or required)
LPDWORD pcReturned	// addr. of variable with no. of job info. structures copied
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server on which the monitors reside. If this parameter is NULL, the local monitors are enumerated.

Level

Specifies the version of the structure pointed to by pMonitors.

pMonitors

Points to an array of MONITOR_INFO_1 or MONITOR_INFO_2 structures.

cbBuf

Specifies the size, in bytes, of the buffer pointed to by pMonitors.

pcbNeeded

Points to a variable that receives the number of bytes copied if the function succeeds or the number of bytes required if cbBuf is too small.

pcReturned

Points to a variable that receives the number of structures that were returned in the buffer pointed to by pMonitors.

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.

See Also

MONITOR_INFO_1, MONITOR_INFO_2


EnumObjects

The EnumObjects function enumerates the pens or brushes available for the specified device context. This function calls the application-defined callback function once for each available object, supplying data describing that object. EnumObjects continues calling the callback function until the callback function returns zero or until all of the objects have been enumerated.

int EnumObjects(

HDC hdc,	// handle to device context
int nObjectType,	// object-type identifier
GOBJENUMPROC lpObjectFunc,	// pointer to callback function
LPARAM lParam	// pointer to application-supplied data
);
Parameters

hdc

Identifies the device context.

nObjectType

Specifies the object type. This parameter can be OBJ_BRUSH or OBJ_PEN.

lpObjectFunc

The pointer to the application-defined callback function. For more information about the callback function, see the EnumObjectsProc function.

lParam

Points to the application-defined data. The data is passed to the callback function along with the object information.

Return Values

The return value specifies the last value returned by the callback function. Its meaning is user-defined. The return value is -1 if there are too many objects to enumerate. In this case, the callback function is not called.

See Also

EnumObjectsProc, GetObject


EnumObjectsProc

The EnumObjectsProc function is an application-defined callback function that processes object data supplied by the EnumObjects function.

VOID CALLBACK EnumObjectsProc(

LPVOID lpLogObject,	// pointer to graphic-object structure
LPARAM lpData	// pointer to application-defined data
);
Parameters

lpLogObject

Points to a LOGPEN or LOGBRUSH structure describing the attributes of the object.

lpData

Points to the application-defined data passed by the EnumObjects function.

Return Values

This function does not return a value.

Remarks

An application must register this function by passing its address to the EnumObjects function. EnumObjectsProc is a placeholder for the application-defined function name.

See Also

EnumObjects, GlobalAlloc, GlobalLock, LOGPEN, LOGBRUSH


EnumPorts

The EnumPorts function enumerates the ports that are available for printing on a specified server.

BOOL EnumPorts(

LPTSTR pName,	// pointer to server name
DWORD Level,	// specifies type of port info structure
LPBYTE pPorts,	// pointer to buffer to receive array of port info. structures
DWORD cbBuf,	// specifies size, in bytes, of buffer
LPDWORD pcbNeeded,	// pointer to number of bytes stored into buffer (or required  // buffer size)
LPDWORD pcReturned	// pointer to number of PORT_INFO_*. structures stored into buffer
);
Parameters

pName

Pointer to a null-terminated string that specifies the name of the server whose printer ports you wish to enumerate.

If pName is NULL, the function enumerates the local machine’s printer ports.

Level

Specifies the type of data structures pointed to by pPorts.

This value can be 1 or 2.

pPorts

Pointer to a buffer that receives an array of PORT_INFO_1 or PORT_INFO_2 structures. Each structure contains data that describes an available printer port. The value of Level specifies the type of structure. A Level value of 1 specifies PORT_INFO_1 structures. A Level value of 2 specifies PORT_INFO_2 structures.

cbBuf

Specifies the size, in bytes, of the buffer pointed to by pPorts.

pcbNeeded

Pointer to a variable that the function sets to the size, in bytes, of the data that enumerates the printer ports. If cbBuf is smaller than this value, EnumPorts fails, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and the variable pointed to by pcbNeeded represents the required buffer size. If cbBuf is equal to or greater than this value, the variable pointed to by pcbNeeded represents the number of bytes stored into the buffer.

pcReturned

Pointer to a variable that the function sets to the number of PORT_INFO_* structures that it stores into the buffer pointed to by pPorts. This is the number of printer ports that are available on the specified server.

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.

Remarks

The EnumPorts function can succeed even if the server specified by pName does not have a printer defined.

See Also

AddPort, DeletePort, PORT_INFO_1, PORT_INFO_2


EnumPrinterData [New - Windows NT]
EnumPrinterData

[New - Windows NT]

The EnumPrinterData function enumerates configuration data for a specified printer.

A printer’s configuration data consists of a set of named and typed values. The EnumPrinterData function obtains one of these values, and its name and a type code, each time you call it. Call the EnumPrinterData function several times in succession to obtain all of a printer’s configuration data values.

Printer configuration data is stored in the registry. While enumerating printer configuration data, you should avoid calling registry functions that might change that data.

DWORD EnumPrinterData(

HANDLE hPrinter,	// handle to printer of interest
DWORD dwIndex,	// index of value to retrieve
LPTSTR pValueName,	// pointer to buffer to receive value name
DWORD cbValueName,	// size in bytes of value name buffer
LPDWORD pcbValueName,	// pointer to variable to receive number of bytes stored into value name buffer
LPDWORD pType,	// pointer to variable to receive value type code
LPBYTE pData,	// pointer to buffer to receive value data
DWORD cbData,	// size in bytes of value data buffer
LPDWORD pcbData	// pointer to variable to receive number of bytes stored into value data buffer
);
Parameters

hPrinter

Handle to the printer whose configuration data is to be obtained.

You obtain this printer handle by calling the OpenPrinter function.

dwIndex

An index value that specifies the configuration data value to retrieve.

Set this parameter to zero for the first call to EnumPrinterData for a given printer handle. Then increment the parameter by one for subsequent calls involving the same printer, until the function returns ERROR_NO_MORE_ITEMS. See the following Remarks section for further information.

Note: If you use the technique mentioned in the descriptions of the cbValueName and cbData parameters to obtain adequate buffer size values, setting both those parameters to zero in a first call to EnumPrinterData for a given printer handle, the value of dwIndex does not matter for that call. Set dwIndex to zero in the next call to EnumPrinterData to start the actual enumeration process.

Configuration data values are not ordered. New values will have an arbitrary index. This means that the EnumPrinterData function may return values in any order.

pValueName

Pointer to a buffer that receives the name of the configuration data value, including a terminating null character.

cbValueName

Specifies the size, in bytes, of the buffer pointed to by pValueName.

If you want to have the operating system supply an adequate buffer size, set both this parameter and the cbData parameter to zero for the first call to EnumPrinterData for a given printer handle. When the function returns, the variable pointed to by pcbValueName will contain a buffer size that is large enough to successfully enumerate all of the printer’s configuration data value names.

pcbValueName

Pointer to a variable that receives the number of bytes stored into the buffer pointed to by pValueName.

pType

Pointer to a variable that receives a type code for the value specified by dwIndex. The type code can be one of the following values:

Value	Meaning
REG_BINARY	Binary data in any form.
REG_DWORD	A 32-bit number.
REG_DWORD_LITTLE_ENDIAN	A 32-bit number in little-endian format. This is equivalent to REG_DWORD. In little-endian format, a multi-byte value is stored in memory from the lowest byte (the “little end”) to the highest byte. For example, the value 0x12345678 is stored as (0x78 0x56 0x34 0x12) in little-endian format. Windows NT and Windows 95 are designed to run on little-endian computer architectures. A user may connect to computers that have big-endian architectures, such as some UNIX systems.
REG_DWORD_BIG_ENDIAN	A 32-bit number in big-endian format.  In big-endian format, a multi-byte value is stored in memory from the highest byte (the “big end”) to the lowest byte. For example, the value 0x12345678 is stored as (0x12 0x34 0x56 0x78) in big-endian format. Windows NT and Windows 95 are designed to run on little-endian computer architectures. A user may connect to computers that have big-endian architectures, such as some UNIX systems.
REG_EXPAND_SZ	A null-terminated string that contains unexpanded references to environment variables (for example, “%PATH%”). It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
REG_LINK	A Unicode symbolic link.
REG_MULTI_SZ	An array of null-terminated strings, terminated by two null characters.
REG_NONE	No defined value type.
REG_RESOURCE_LIST	A device-driver resource list.
REG_SZ	A null-terminated string. It will be a Unicode or ANSI string, depending on whether you use the Unicode or ANSI functions.
The pType parameter can be NULL if the type code is not required.

pData

Pointer to a buffer that receives the configuration data value.

This parameter can be NULL if the configuration data value is not required.

cbData

Specifies the size, in bytes, of the buffer pointed to by pData.

If you want to have the operating system supply an adequate buffer size, set both this parameter and the cbValueName parameter to zero for the first call to EnumPrinterData for a given printer handle. When the function returns, the variable pointed to by pcbData will contain a buffer size that is large enough to successfully enumerate all of the printer’s configuration data value names.

pcbData

Pointer to a variable that receives the number of bytes stored into the buffer pointed to by pData.

This parameter can be NULL if pData is NULL.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a Win32 error value.

The function returns ERROR_NO_MORE_ITEMS when there are no more configuration data values to retrieve for a given printer handle.

Remarks

EnumPrinterData retrieves printer configuration data set by the SetPrinterData function.

If you want to have the operating system supply an adequate buffer size, first call EnumPrinterData with both the cbValueName and cbData parameters set to zero, as noted earlier in the Parameters section. The value of dwIndex does not matter for this call. When the function returns, *pcbValueName and *pcbData will contain buffer sizes that are large enough to enumerate all of the printer’s configuration data value names and values. On the next call, allocate value name and data buffers, set cbValueName and cbData to the sizes in bytes of the allocated buffers, and set dwIndex to zero. Thereafter, continue to call the EnumPrinterData function, incrementing dwIndex by one each time, until the function returns ERROR_NO_MORE_ITEMS.

See Also

DeletePrinterData, GetPrinterData, OpenPrinter, SetPrinter, SetPrinterData


EnumPrinterDrivers

The EnumPrinterDrivers function enumerates all of the printer drivers installed on the specified printer server.

BOOL EnumPrinterDrivers(

LPTSTR pName,	// pointer to server name
LPTSTR pEnvironment,	// pointer to environment name
DWORD Level,	// structure level
LPBYTE pDriverInfo,	// pointer to an array of structures
DWORD cbBuf,	// size, in bytes, of array
LPDWORD pcbNeeded,	// pointer to number of bytes copied (or required)
LPDWORD pcReturned	// pointer to number of DRIVER_INFO. structures
);
Parameters

pName

Pointer to a null-terminated string that specifies the name of the server on which the printer drivers should be enumerated.

If pName is NULL, the function enumerates the local machine’s printer drivers.

pEnvironment

Pointer to a null-terminated string that specifies the environment. For example, “Windows NT x86” specifies Windows NT running on an Intel 80386 or 80486 processor. If this parameter is NULL, the function uses the current environment of the caller/client (not of the destination/server).

Level

Specifies the type of structures pointed to by pDriverInfo. This value must be 1, 2, or 3.

pDriverInfo

Pointer to a buffer that receives an array of DRIVER_INFO_1, DRIVER_INFO_2, or DRIVER_INFO_3 structures. Each structure contains data that describes an available printer driver.

cbBuf

Specifies the size, in bytes, of the buffer pointed to by pDriverInfo.

pcbNeeded

Pointer to a value that the function sets to the size in bytes of the data that enumerates the printer drivers. If cbBuf is smaller than this value, EnumPrinterDrivers fails, and the variable pointed to by pcbNeeded represents the required buffer size. If cbBuf is equal to or greater than this value, the variable pointed to by pcbNeeded represents the number of bytes stored into the buffer.

pcReturned

Pointer to a value that specifies the number of structures that it stores into the buffer pointed to by pDriverInfo. This is the number of printer drivers installed on the specified print server.

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.

See Also

AddPrinterDriver, DRIVER_INFO_1, DRIVER_INFO_2, DRIVER_INFO_3, GetPrinterDriver


EnumPrinters

The EnumPrinters function enumerates available printers, print servers, domains, or print providers.

BOOL EnumPrinters(

DWORD Flags,	// types of printer objects to enumerate
LPTSTR Name,	// name of printer object
DWORD Level,	// specifies type of printer info structure
LPBYTE pPrinterEnum,	// pointer to buffer to receive printer info structures
DWORD cbBuf,	// size, in bytes, of array
LPDWORD pcbNeeded,	// pointer to variable with no. of bytes copied (or required)
LPDWORD pcReturned	// pointer to variable with no. of printer info. structures copied
);
Parameters

Flags

Specifies the types of print objects that the function should enumerate. This value can be a combination of the following constants:

Value	Meaning
PRINTER_ENUM_LOCAL	The function ignores the Name parameter, and enumerates the locally installed printers. Windows 95: The function will also enumerate network printers because they are handled by the local print provider.
PRINTER_ENUM_NAME	The function enumerates the printer identified by Name. This can be a server, a domain, or a print provider. If Name is NULL, the function enumerates available print providers.
PRINTER_ENUM_SHARED	The function enumerates printers that have the shared attribute. Cannot be used in isolation; use an OR operation to combine with another PRINTER_ENUM type.
PRINTER_ENUM_DEFAULT	Windows 95 only: The function returns information about the default printer.
PRINTER_ENUM_CONNECTIONS	Windows NT only: The function enumerates the list of printers to which the user has made previous connections.
PRINTER_ENUM_NETWORK	Windows NT only: The function enumerates network printers in the computer’s domain. This value is valid only if Level is 1.
PRINTER_ENUM_REMOTE	Windows NT only: The function enumerates network printers and print servers in the computer’s domain. This value is valid only if Level is 1.
If Level is 4, you can only use the PRINTER_ENUM_CONNECTIONS and PRINTER_ENUM_LOCAL constants.

Name

If Level is 1, Flags contains PRINTER_ENUM_NAME, and Name is non-NULL, Name points to a null-terminated string that specifies the name of the object to enumerate. This string can be the name of a server, a domain, or a print provider.

If Level is 1, Flags contains PRINTER_ENUM_NAME, and Name is NULL, the function enumerates the available print providers.

If Level is 1, Flags contains PRINTER_ENUM_REMOTE, and Name is NULL, the function enumerates the printers in the user’s domain.

If Level is 2 or 5, Name points to a null-terminated string that specifies the name of a server whose printers are to be enumerated. If this string is NULL, the function enumerates the printers installed on the local machine.

If Level is 4, Name should be NULL. The function always queries on the local machine.

When Name is NULL, it enumerates printers that are installed on the local machine. These printers include those that are physically attached to the local machine as well as remote printers to which it has a network connection.

Level

Specifies the type of data structures pointed to by pPrinterEnum. Valid values are 1, 2, 4, and 5, which correspond to the PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4, and PRINTER_INFO_5 data structures.

Windows 95: The value can be 1, 2, or 5.

Windows NT: This value can be 1, 2, 4, or 5.

pPrinterEnum

Pointer to a buffer that receives an array of PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4, or PRINTER_INFO_5 structures. Each structure contains data that describes an available print object. If Level is 1, the array contains PRINTER_INFO_1 structures. If Level is 2, the array contains PRINTER_INFO_2 structures. If Level is 4, the array contains PRINTER_INFO_4 structures. If Level is 5, the array contains PRINTER_INFO_5 structures.

Windows 95: The buffer cannot receive PRINTER_INFO_4 structures. It can receive any of the other types.

cbBuf

Specifies the size, in bytes, of the array pointed to by pPrinterEnum.

pcbNeeded

Pointer to a value that receives the number of bytes copied if the function succeeds or the number of bytes required if cbBuf is too small.

pcReturned

Pointer to a value that receives the number of PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4, or PRINTER_INFO_5 structures that the function returns in the array to which pPrinterEnum points.

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.

Remarks

If EnumPrinters returns a PRINTER_INFO_1 structure in which PRINTER_ENUM_CONTAINER is specified, this indicates that there is a hierarchy of printer objects. An application can enumerate the hierarchy by calling EnumPrinters again, setting Name to the value of the PRINTER_INFO_1 structure’s pName member.

The EnumPrinters function does not retrieve security information. If PRINTER_INFO_2 structures are returned in the array pointed to by pPrinterEnum, their pSecurityDescriptor members will be set to NULL.

To get information about the default printer, call the GetProfileString function with the section name string set to "windows" and the key name string set to "device". The returned string contains the name of the default printer, the name of the printer DRV file, and the port to which the printer is attached.

Windows NT:

The PRINTER_INFO_4 structure provides an easy and extremely fast way to retrieve the names of the printers installed on a local machine, as well as the remote connections that a user has established. When EnumPrinters is called with a PRINTER_INFO_4 data structure, that function queries the registry for the specified information, then returns immediately. This differs from the behavior of EnumPrinters when called with other levels of PRINTER_INFO_* data structures. In particular, when EnumPrinters is called with a level 2 (PRINTER_INFO_2) data structure, it performs an OpenPrinter call on each remote connection. If a remote connection is down, or the remote server no longer exists, or the remote printer no longer exists, the function must wait for RPC to time out and consequently fail the OpenPrinter call. This can take a while. Passing a PRINTER_INFO_4 structure lets an application retrieve a bare minimium of required information; if more detailed information is desired, a subsequent EnumPrinter level 2 call can be made.

Windows 95:

To quickly enumerate local and network printers, use the PRINTER_INFO_5 structure. This causes EnumPrinters to query the registry rather than make remote calls, and is similar to using the PRINTER_INFO_4 structure on Windows NT as described in the preceding paragraph.

Examples

The following table shows the EnumPrinters output for various Flags values when the Level parameter is set to 1.

In the Name parameter column of the table, you should substitute an appropriate name for Print Provider, Domain, and Machine. For example, for Print Provider, you could use the name of the Windows NT network print provider: “Windows NT Remote Printers”, or the name of the Windows 95 local print provider: “Windows 95 Local Print Provider”. To get print provider names, call EnumPrinters with Name set to NULL.

Flags parameter	Name parameter	Result
PRINTER_ENUM_LOCAL	The Name parameter is ignored.	All local printers. Windows 95: Also enumerates network printers because they are installed locally.
PRINTER_ENUM_NAME	“Print Provider”	All domain names
PRINTER_ENUM_NAME	Windows NT only:  “Print Provider!Domain”	All printers and print servers in the computer’s domain
PRINTER_ENUM_NAME	Windows NT only:  “Print Provider!!\\Machine”	All printers shared at \\Machine
PRINTER_ENUM_NAME	Windows NT: An empty string, ““ Windows 95: The name of the local machine or the local print provider.	All local printers. Windows 95: Also enumerates network printers because they are installed locally.
PRINTER_ENUM_NAME	NULL	All print providers in the computer’s domain
Windows NT only:  PRINTER_ENUM_CONNECTIONS	The Name parameter is ignored.	All connected remote printers
Windows NT only:  PRINTER_ENUM_NETWORK	The Name parameter is ignored.	All printers in the computer’s domain
Windows NT only:  PRINTER_ENUM_REMOTE	An empty string, ““	All printers and print servers in the computer’s domain
Windows NT only:  PRINTER_ENUM_REMOTE	“Print Provider”	Same as PRINTER_ENUM_NAME
Windows NT only:  PRINTER_ENUM_REMOTE	“Print Provider!Domain”	All printers and print servers in computer’s domain, regardless of Domain specified.
See Also

AddPrinter, DeletePrinter, GetPrinter, GetProfileString, PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4, PRINTER_INFO_5, SetPrinter


EnumPrintProcessorDatatypes

The EnumPrintProcessorDatatypes function enumerates the data types that a specifed print processor supports.

BOOL EnumPrintProcessorDatatypes(

LPTSTR pName,	// points to server name string
LPTSTR pPrintProcessorName,	// points to print processor name string
DWORD Level,	// specifies version of print processor data type structures
LPBYTE pDatatypes,	// points to buffer to receive print processor data type structures
DWORD cbBuf,	// specifies size, in bytes, of buffer
LPDWORD pcbNeeded,	// points to number of bytes copied (or required)
LPDWORD pcReturned	// points to number of data structures obtained
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server on which the print processor resides. If this parameter is NULL, the data types for the local print processor are enumerated.

pPrintProcessorName

Points to a null-terminated string that specifies the name of the print processor whose data types are to be enumerated.

Level

Specifies the version of the print-processor data type structures to be stored in the buffer pointed to by pDatatypes. This parameter must be 1.

pDatatypes

Points to an array of DATATYPES_INFO_1 structures. One structure is created for each available data type.

cbBuf

Specifies the size, in bytes, of the buffer pointed to by pDatatypes.

pcbNeeded

Points to a variable to receive the total size, in bytes, of the array of DATATYPES_INFO_1 structures.

If this value is less than or equal to cbBuf and the function succeeds, this is the number of bytes stored in the buffer pointed to by pDatatypes. If this number is greater than cbBuf, the buffer is too small, and you must call the function again with a buffer size at least as large as *pcbNeeded.

pcReturned

Points to a variable that the function sets to the number of data structures stored in the buffer pointed to by pDatatypes.

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.

See Also

DATATYPES_INFO_1, EnumPrintProcessors


EnumPrintProcessors

The EnumPrintProcessors function enumerates the print processors installed on the specified server.

BOOL EnumPrintProcessors(

LPTSTR pName,	// points to server name
LPTSTR pEnvironment,	// points to environment name
DWORD Level,	// structure level
LPBYTE pPrintProcessorInfo,	// points to structure array
DWORD cbBuf,	// array length in bytes
LPDWORD pcbNeeded,	// points to number of bytes copied (or required)
LPDWORD pcReturned	// points to number of job info. structures copied
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server on which the print processors reside. If this parameter is NULL, the local print processors are enumerated.

pEnvironment

Points to a null-terminated string that specifies the environment. For example, “Windows NT x86” specifies Windows NT running on an Intel 80386 or 80486 processor. If this parameter is NULL, the current environment of the calling application and client machine (not of the destination application and print server) is used.

Level

Specifies the version of the structure to which pPrintProcessorInfo points. This value must be 1.

pPrintProcessorInfo

Points to an array of PRINTPROCESSOR_INFO_1 structures. One structure is created for each available print processor.

cbBuf

Specifies the size, in bytes, of the buffer pointed to by pPrintProcessorInfo.

pcbNeeded

Points to a value that specifies the number of bytes copied if the function succeeds or the number of bytes required if cbBuf is too small.

pcReturned

Points to a value that specifies the number of PRINTPROCESSOR_INFO_1 structures that returned in the array to which pPrintProcessorInfo points.

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.

See Also

AddPrintProcessor, EnumPrintProcessorDatatypes, PRINTPROCESSOR_INFO_1


EnumProps

The EnumProps function enumerates all entries in the property list of a window by passing them, one by one, to the specified callback function. EnumProps continues until the last entry is enumerated or the callback function returns FALSE.

int EnumProps(

HWND hWnd,	// handle to window
PROPENUMPROC lpEnumFunc	// pointer to callback function
);
Parameters

hWnd

Identifies the window whose property list is to be enumerated.

lpEnumFunc

Points to the callback function. For more information about the callback function, see the PropEnumProc function.

Return Values

The return value specifies the last value returned by the callback function. It is -1 if the function did not find a property for enumeration.

Remarks

An application can remove only those properties it has added. It must not remove properties added by other applications or by Windows itself.

See Also

EnumPropsEx, GetProp, PropEnumProc, RemoveProp, SetProp


EnumPropsEx

The EnumPropsEx function enumerates all entries in the property list of a window by passing them, one by one, to the specified callback function. EnumPropsEx continues until the last entry is enumerated or the callback function returns FALSE.

int EnumPropsEx(

HWND hWnd,	// handle to window
PROPENUMPROCEX lpEnumFunc,	// pointer to callback function
LPARAM lParam	// application-defined data
);
Parameters

hWnd

Identifies the window whose property list is to be enumerated.

lpEnumFunc

Points to the callback function. For more information about the callback function, see the PropEnumProcEx function.

lParam

Contains application-defined data to be passed to the callback function.

Return Values

The return value specifies the last value returned by the callback function. It is -1 if the function did not find a property for enumeration.

Remarks

An application can remove only those properties it has added. It must not remove properties added by other applications or by Windows itself.

See Also

EnumProps, GetProp, PropEnumProcEx, RemoveProp, SetProp


EnumRegisterWordProc

The EnumRegisterWordProc function is an application-defined callback function that process data of register string from the ImmEnumRegisterWord function.

UINT CALLBACK EnumRegisterWordProc(

LPCTSTR lpReading,
DWORD dwStyle,
LPCTSTR lpszString,
LPVOID lpData
);
Parameters

lpszReading

Pointer to a null-terminated string specifying the matched reading string.

dwStyle

Style of register string.

lpszString

Pointer to a null-terminated string specifying the matched register string.

lpData

Application-supplied data.

Return Values

Returns a nonzero value to continue enumeration; zero to stop enumeration.

See Also

ImmEnumRegisterWord


EnumResLangProc

The EnumResLangProc function is an application-defined callback function that receives resource languages as a result of a call to the EnumResourceLanguages function.

BOOL CALLBACK EnumResLangProc(

HANDLE hModule,	// resource-module handle
LPCTSTR lpszType,	// pointer to resource type
LPCTSTR lpszName,	// pointer to resource name
WORD wIDLanguage,	// resource language identifier
LONG lParam	// application-defined parameter
);
Parameters

hModule

Identifies the module whose executable file contains the resources for which the languages are being enumerated. If this parameter is NULL, the function enumerates the resource languages in the module used to create the current process.

lpszType

Points to a null-terminated string specifying the type name of the resource for which the language is being enumerated. For standard resource types, this parameter should be one of the following values:

Value	Meaning
RT_ACCELERATOR	Accelerator table
RT_ANICURSOR	Animated cursor
RT_ANIICON	Animated icon
RT_BITMAP	Bitmap resource
RT_CURSOR	Hardware-dependent cursor resource
RT_DIALOG	Dialog box
RT_FONT	Font resource
RT_FONTDIR	Font directory resource
RT_GROUP_CURSOR	Hardware-independent cursor resource
RT_GROUP_ICON	Hardware-independent icon resource
RT_ICON	Hardware-dependent icon resource
RT_MENU	Menu resource
RT_MESSAGETABLE	Message-table entry
RT_RCDATA	Application-defined resource (raw data)
RT_STRING	String-table entry
RT_VERSION	Version resource
lpszName

Points to a null-terminated string specifying the name of the resource for which the language is being enumerated.

wIDLanguage

Specifies the language identifier for the resource for which the language is being enumerated. The EnumResourceLanguages function provides this value. For a list of the primary language identifiers and sublanguage identifiers that constitute a language identifier, see the MAKELANGID macro.

lParam

Specifies the application-defined parameter passed to the EnumResourceLanguages function. This parameter can be used in error checking.

Return Values

This callback function should return TRUE to continue enumeration; otherwise, it should return FALSE to stop enumeration.

Remarks

The EnumResLangProc function is a placeholder for the application-defined or library-defined function name.

See Also

EnumResourceLanguages, MAKELANGID


EnumResNameProc

The EnumResNameProc function is an application-defined callback function that receives resource names as a result of a call to the EnumResourceNames function.

BOOL CALLBACK EnumResNameProc(

HANDLE hModule,	// resource-module handle
LPCTSTR lpszType,	// pointer to resource type
LPTSTR lpszName,	// pointer to resource name
LONG lParam	// application-defined parameter
);
Parameters

hModule

Identifies the module whose executable file contains the resources for which the names are being enumerated. If this parameter is NULL, the function enumerates the resource names in the module used to create the current process.

lpszType

Points to a null-terminated string specifying the type name of the resource for which the name is being enumerated. For standard resource types, this parameter should be one of the following values:

Value	Meaning
RT_ACCELERATOR	Accelerator table
RT_ANICURSOR	Animated cursor
RT_ANIICON	Animated icon
RT_BITMAP	Bitmap resource
RT_CURSOR	Hardware-dependent cursor resource
RT_DIALOG	Dialog box
RT_FONT	Font resource
RT_FONTDIR	Font directory resource
RT_GROUP_CURSOR	Hardware-independent cursor resource
RT_GROUP_ICON	Hardware-independent icon resource
RT_ICON	Hardware-dependent icon resource
RT_MENU	Menu resource
RT_MESSAGETABLE	Message-table entry
RT_RCDATA	Application-defined resource (raw data)
RT_STRING	String-table entry
RT_VERSION	Version resource
lpszName

Points to a null-terminated string specifying the name of the resource for which the name is being enumerated.

lParam

Specifies the application-defined parameter passed to the EnumResourceNames function. This parameter can be used in error checking.

Return Values

This callback function should return TRUE to continue enumeration; otherwise, it should return FALSE to stop enumeration.

Remarks

The EnumResNameProc function is a placeholder for the application-defined or library-defined function name.

See Also

EnumResourceNames


EnumResourceLanguages

The EnumResourceLanguages function searches a module for each resource of the specified type and name and passes the language of each resource it locates to a defined callback function.

BOOL EnumResourceLanguages(

HMODULE hModule,	// resource-module handle
LPCTSTR lpType,	// pointer to resource type
LPCTSTR lpName,	// pointer to resource name
ENUMRESLANGPROC lpEnumFunc,	// pointer to callback function
LONG lParam	// application-defined parameter
);
Parameters

hModule

Identifies the module whose executable file contains the resources for which the languages are to be enumerated. If this parameter is NULL, the function enumerates the resource languages in the module used to create the current process.

lpType

Points to a null-terminated string specifying the type of the resource for which the language is being enumerated. For standard resource types, this parameter can be one of the following values:

Value	Meaning
RT_ACCELERATOR	Accelerator table
RT_ANICURSOR	Animated cursor
RT_ANIICON	Animated icon
RT_BITMAP	Bitmap resource
RT_CURSOR	Hardware-dependent cursor resource
RT_DIALOG	Dialog box
RT_FONT	Font resource
RT_FONTDIR	Font directory resource
RT_GROUP_CURSOR	Hardware-independent cursor resource
RT_GROUP_ICON	Hardware-independent icon resource
RT_ICON	Hardware-dependent icon resource
RT_MENU	Menu resource
RT_MESSAGETABLE	Message-table entry
RT_RCDATA	Application-defined resource (raw data)
RT_STRING	String-table entry
RT_VERSION	Version resource
lpName

Points to a null-terminated string specifying the name of the resource for which the language is being enumerated.

lpEnumFunc

Points to the callback function to be called for each enumerated resource language. For more information, see the EnumResLangProc function.

lParam

Specifies an application-defined value passed to the callback function. This parameter may be used in error checking.

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.

Remarks

The EnumResourceLanguages function continues to enumerate resource languages until the callback function returns FALSE or all resource languages have been enumerated.

See Also

EnumResLangProc, EnumResourceNames, EnumResourceTypes


EnumResourceNames

The EnumResourceNames function searches a module for each resource of the specified type and passes the name of each resource it locates to an application-defined callback function.

BOOL EnumResourceNames(

HINSTANCE hModule,	// resource-module handling
LPCTSTR lpszType,	// pointer to resource type
ENUMRESNAMEPROC lpEnumFunc,	// pointer to callback function
LONG lParam	// application-defined parameter
);
Parameters

hModule

Identifies the module whose executable file contains the resources for which the names are to be enumerated. If this parameter is NULL, the function enumerates the resource names in the module used to create the current process.

lpszType

Points to a null-terminated string specifying the type name of the resource for which the name is being enumerated. For standard resource types, this parameter can be one of the following values:

Value	Meaning
RT_ACCELERATOR	Accelerator table
RT_ANICURSOR	Animated cursor
RT_ANIICON	Animated icon
RT_BITMAP	Bitmap resource
RT_CURSOR	Hardware-dependent cursor resource
RT_DIALOG	Dialog box
RT_FONT	Font resource
RT_FONTDIR	Font directory resource
RT_GROUP_CURSOR	Hardware-independent cursor resource
RT_GROUP_ICON	Hardware-independent icon resource
RT_ICON	Hardware-dependent icon resource
RT_MENU	Menu resource
RT_MESSAGETABLE	Message-table entry
RT_RCDATA	Application-defined resource (raw data)
RT_STRING	String-table entry
RT_VERSION	Version resource
lpEnumFunc

Points to the callback function to be called for each enumerated resource name. For more information, see the EnumResNameProc function.

lParam

Specifies an application-defined value passed to the callback function. This parameter can be used in error checking.

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.

Remarks

The EnumResourceNames function continues to enumerate resource names until the callback function returns FALSE or all resource names have been enumerated.

See Also

EnumResNameProc, EnumResourceLanguages, EnumResourceTypes


EnumResourceTypes

The EnumResourceTypes function searches a module for resources and passes each resource type it finds to an application-defined callback function.

BOOL EnumResourceTypes(

HMODULE hModule,	// resource-module handle
ENUMRESTYPEPROC lpEnumFunc,	// pointer to callback function
LONG lParam	// application-defined parameter
);
Parameters

hModule

Identifies the module whose executable file contains the resources for which the types are to be enumerated. If this parameter is NULL, the function enumerates the resource types in the module used to create the current process.

lpEnumFunc

Points to the callback function to be called for each enumerated resource type. For more information, see the EnumResTypeProc function.

lParam

Specifies an application-defined value passed to the callback 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.

Remarks

The EnumResourceTypes function continues to enumerate resource types until the callback function returns FALSE or all resource types have been enumerated.

See Also

EnumResourceLanguages, EnumResourceNames, EnumResTypeProc


EnumResTypeProc

The EnumResTypeProc function is an application-defined callback function that receives resource types as a result of a call to the EnumResourceTypes function.

BOOL CALLBACK EnumResTypeProc(

HANDLE hModule,	// resource-module handle
LPTSTR lpszType,	// pointer to resource type
LONG lParam	// application-defined parameter
);
Parameters

hModule

Identifies the module whose executable file contains the resources for which the types are to be enumerated. If this parameter is NULL, the function enumerates the resource types in the module used to create the current process.

lpszType

Points to a null-terminated string specifying the type name of the resource for which the type is being enumerated. For standard resource types, this parameter can be one of the following values:

Value	Meaning
RT_ACCELERATOR	Accelerator table
RT_ANICURSOR	Animated cursor
RT_ANIICON	Animated icon
RT_BITMAP	Bitmap resource
RT_CURSOR	Hardware-dependent cursor resource
RT_DIALOG	Dialog box
RT_FONT	Font resource
RT_FONTDIR	Font directory resource
RT_GROUP_CURSOR	Hardware-independent cursor resource
RT_GROUP_ICON	Hardware-independent icon resource
RT_ICON	Hardware-dependent icon resource
RT_MENU	Menu resource
RT_MESSAGETABLE	Message-table entry
RT_RCDATA	Application-defined resource (raw data)
RT_STRING	String-table entry
RT_VERSION	Version resource
lParam

Specifies the application-defined parameter passed to the EnumResourceTypes function. This parameter can be used in error checking.

Return Values

The callback function should return TRUE to continue enumeration; otherwise, it should return FALSE to stop enumeration.

Remarks

The EnumResTypeProc function is a placeholder for the application-defined or library-defined function name.

See Also

EnumResourceTypes


EnumServicesStatus

The EnumServicesStatus function enumerates services in the specified service control manager database. The name and status of each service are provided.

BOOL EnumServicesStatus(

SC_HANDLE hSCManager,	// handle to service control manager database
DWORD dwServiceType,	// type of services to enumerate
DWORD dwServiceState,	// state of services to enumerate
LPENUM_SERVICE_STATUS lpServices,	// pointer to service status buffer
DWORD cbBufSize,	// size of service status buffer
LPDWORD pcbBytesNeeded,	// pointer to variable for bytes needed
LPDWORD lpServicesReturned,	// pointer to variable for number returned
LPDWORD lpResumeHandle	// pointer to variable for next entry
);
Parameters

hSCManager

Identifies the service control manager database. The OpenSCManager function returns this handle which must have SC_MANAGER_ENUMERATE_SERVICE access.

dwServiceType

Specifies the type of services to enumerate. It must be one or both of the following values:

Value	Meaning
SERVICE_WIN32	Enumerates services of type SERVICE_WIN32_OWN_PROCESS and SERVICE_WIN32_SHARE_PROCESS.
SERVICE_DRIVER	Enumerates services of type SERVICE_KERNEL_DRIVER and SERVICE_FILE_SYSTEM_DRIVER.
dwServiceState

Specifies the services to enumerate based on their running state. It must be one or both of the following values:

Value	Meaning
SERVICE_ACTIVE	Enumerates services that are in the following states: SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_RUNNING, SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING, and SERVICE_PAUSED.
SERVICE_INACTIVE	Enumerates services that are in the SERVICE_STOPPED state.
lpServices

Points to an array of ENUM_SERVICE_STATUS structures in which the name and service status information for each service in the database is returned.

cbBufSize

Specifies the size, in bytes, of the buffer pointed to by the lpServices parameter.

pcbBytesNeeded

Points to a variable that receives the number of bytes needed to return the remaining service entries.

lpServicesReturned

Points to a variable that receives the number of service entries returned.

lpResumeHandle

Points to a 32-bit variable that, on input, specifies the starting point of enumeration. The first time this function is called, the variable’s value is set to zero. On output, the variable’s value is zero if the function succeeds. If the function returns FALSE and the GetLastError function returns ERROR_MORE_DATA, the variable’s value is used to indicate the next unread service entry when the function is called again to retrieve the additional data.

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.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED
	The specified handle was not opened with SC_MANAGER_ENUMERATE_SERVICE access.
ERROR_INVALID_HANDLE
	The specified handle is invalid.
ERROR_INVALID_PARAMETER
	A parameter that was specified is invalid.
ERROR_MORE_DATA
	There are more service entries than would fit into the lpServices buffer. The actual number of service entries written to lpServices is returned in the lpServicesReturned parameter. The number of bytes required to get the remaining entries is returned in the pcbBytesNeeded parameter. The remaining services can be enumerated by additional calls to EnumServicesStatus with the lpResumeHandle parameter indicating the next service to read.
See Also

EnumDependentServices, ENUM_SERVICE_STATUS, OpenSCManager


EnumSystemCodePages

The EnumSystemCodePages function enumerates the code pages that are either installed on or supported by a system. The dwFlags parameter determines whether the function enumerates installed or supported code pages. The function enumerates the code pages by passing code page identifiers, one at a time, to the specified application-defined callback function. This continues until all of the installed or supported code page identifiers have been passed to the callback function, or the callback function returns FALSE.

BOOL EnumSystemCodePages(

CODEPAGE_ENUMPROC lpCodePageEnumProc,	// pointer to enumeration callback function
DWORD dwFlags	// indicates which code pages to enumerate
);
Parameters

lpCodePageEnumProc

Points to an application-defined callback function. The EnumSystemCodePages function enumerates code pages by making repeated calls to this callback function. For more information, see the EnumCodePagesProc callback function.

dwFlags

Specifies the code pages to enumerate. This parameter can be one of the following values:

Value	Meaning
CP_INSTALLED	Enumerate only installed code pages.
CP_SUPPORTED	Enumerate all supported code pages.
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 one of the following error codes:

ERROR_INVALID_PARAMETER
ERROR_BADDB
ERROR_INVALID FLAGS

Remarks

The CP_INSTALLED and CP_SUPPORTED flags are mutually exclusive.

See Also

EnumCodePagesProc


EnumSystemLocales

The EnumSystemLocales function enumerates the locales that are either installed on or supported by a system. The dwFlags parameter determines whether the function enumerates installed or supported system locales. The function enumerates locales by passing locale identifiers, one at a time, to the specified application-defined callback function. This continues until all of the installed or supported locale identifiers have been passed to the callback function or the callback function returns FALSE.

BOOL EnumSystemLocales(

LOCALE_ENUMPROC lpLocaleEnumProc,	// pointer to enumeration callback function
DWORD dwFlags	// indicates which locales to enumerate
);
Parameters

lpLocaleEnumProc

Points to an application-defined callback function. The EnumSystemLocales function enumerates locales by making repeated calls to this callback function. For more information, see the EnumLocalesProc callback function.

dwFlags

Specifies the locale identifiers to enumerate. This parameter can be one of the following values:

Value	Meaning
LCID_INSTALLED	Enumerate only installed locale identifiers.
LCID_SUPPORTED	Enumerate all supported locale identifiers.
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 one of the following error codes:

ERROR_INVALID_PARAMETER
ERROR_BADDB
ERROR_INVALID FLAGS

Remarks

The LCID_INSTALLED and LCID_SUPPORTED flags are mutually exclusive.

See Also

EnumLocalesProc


EnumTaskWindows

The EnumTaskWindows function is obsolete. It has been superseded by the EnumThreadWindows function.

To maintain compatibility for 16-bit applications, EnumTaskWindows has been replaced with a macro that calls EnumThreadWindows. Earlier applications can continue to call EnumTaskWindows as previously documented, but new applications should use EnumThreadWindows.


EnumThreadWindows

The EnumThreadWindows function enumerates all nonchild windows associated with a thread by passing the handle of each window, in turn, to an application-defined callback function. EnumThreadWindows continues until the last window is enumerated or the callback function returns FALSE. To enumerate child windows of a particular window, use the EnumChildWindows function. This function supersedes the EnumTaskWindows function.

BOOL EnumThreadWindows(

DWORD dwThreadId,	// thread identifier
WNDENUMPROC lpfn,	// pointer to callback function
LPARAM lParam	// application-defined value
);
Parameters

dwThreadId

Identifies the thread whose windows are to be enumerated.

lpfn

Points to an application-defined callback function. For more information about the callback function, see the EnumThreadWndProc callback function.

lParam

Specifies a 32-bit, application-defined value to be passed to the callback function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

EnumChildWindows, EnumThreadWndProc, EnumWindows


EnumThreadWndProc

The EnumThreadWndProc function is an application-defined callback function that receives the window handles associated with a thread as a result of a call to the EnumThreadWindows function.

BOOL CALLBACK EnumThreadWndProc(

HWND hwnd,	// handle to window
LPARAM lParam	// application-defined value
);
Parameters

hwnd

Identifies a window associated with the thread specified in the EnumThreadWindows function.

lParam

Specifies the application-defined value given in the EnumThreadWindows function.

Return Values

To continue enumeration, the callback function must return TRUE; to stop enumeration, it must return FALSE.

Remarks

The callback function can perform any desired task.

An application must register this callback function by passing its address to the EnumThreadWindows function. EnumThreadWndProc is a placeholder for the application-defined function name.

See Also

EnumThreadWindows


EnumTimeFormats

The EnumTimeFormats function enumerates the time formats that are available for a specified locale. The function enumerates the time formats by passing a pointer to a string buffer containing a time format to an application-defined callback function. It continues to do so until the last time format is found or the callback function returns FALSE.

BOOL EnumTimeFormats(

TIMEFMT_ENUMPROC lpTimeFmtEnumProc,	// pointer to enumeration callback function
LCID Locale,	// locale whose time formats are of interest
DWORD dwFlags	// currently unused
);
Parameters

lpTimeFmtEnumProc

Points to an application-defined callback function. See the EnumTimeFormatsProc callback function for further details.

Locale

Specifies the locale to retrieve time format information for. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
dwFlags

Currently unused. Must be zero.

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 one of the following error codes:

ERROR_INVALID_PARAMETER
ERROR_BADDB
ERROR_INVALID FLAGS

See Also

EnumTimeFormatsProc, EnumCalendarInfo, EnumDateFormats


EnumTimeFormatsProc

An EnumTimeFormatsProc function is an application-defined callback function. It is called as a result of a call to the EnumTimeFormats function, and receives a pointer to a string buffer containing a time format string.

BOOL CALLBACK EnumTimeFormatsProc(

LPTSTR lpTimeFormatString	// pointer to time format string
);
Parameters

lpTimeFormatString

Pointer to a string buffer containing a null-terminated time format string. Note that lpTimeFormatString should be an LPWSTR for the Unicode (W) version of EnumTimeFormatsProc, and an LPSTR for the ANSI (A) version of EnumTimeFormatsProc.

Return Values

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

EnumTimeFormatsProc is a placeholder for an application-defined function name.

An EnumTimeFormatsProc function can carry out any task

An application registers an EnumTimeFormatsProc function by passing its address to the EnumTimeFormats function.

A value of type TIMEFMT_ENUMPROC is a pointer to an EnumTimeFormatsProc function.

See Also

EnumTimeFormats


EnumWindows

The EnumWindows function enumerates all top-level windows on the screen by passing the handle of each window, in turn, to an application-defined callback function. EnumWindows continues until the last top-level window is enumerated or the callback function returns FALSE.

BOOL EnumWindows(

WNDENUMPROC lpEnumFunc,	// pointer to callback function
LPARAM lParam	// application-defined value
);
Parameters

lpEnumFunc

Points to an application-defined callback function. For more information, see the EnumWindowsProc callback function.

lParam

Specifies a 32-bit, application-defined value to be passed to the callback function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The EnumWindows function does not enumerate child windows.

This function is more reliable than calling the GetWindow function in a loop. An application that calls GetWindow to perform this task risks being caught in an infinite loop or referencing a handle to a window that has been destroyed.

See Also

EnumChildWindows, EnumWindowsProc, GetWindow


EnumWindowsProc

The EnumWindowsProc function is an application-defined callback function that receives top-level window handles as a result of a call to the EnumWindows or EnumDesktopWindows function.

BOOL CALLBACK EnumWindowsProc(

HWND hwnd,	// handle to parent window
LPARAM lParam	// application-defined value
);
Parameters

hwnd

Identifies a top-level window.

lParam

Specifies the application-defined value given in EnumWindows or EnumDesktopWindows.

Return Values

To continue enumeration, the callback function must return TRUE; to stop enumeration, it must return FALSE.

Remarks

The callback function can perform any desired task.

An application must register this callback function by passing its address to EnumWindows or EnumDesktopWindows. EnumWindowsProc is a placeholder for the application-defined function name. The WNDENUMPROC type is a pointer to an EnumWindowsProc function.

See Also

EnumWindows, EnumDesktopWindows


EnumWindowStationProc

The EnumWindowStationProc function is an application-defined callback function that receives a window station name as a result of a call to the EnumWindowStations function.

BOOL EnumWindowStationProc(

LPTSTR lpszWindowStation	// name of a window station
LPARAM lParam	// value specified in EnumWindowStations call
);
Parameters

lpszWindowStation

Points to the null-terminated name of a window station.

lParam

Specifies the application-defined value given in the EnumWindowStations function.

Return Values

To continue enumeration, the callback function must return TRUE. To stop enumeration, it must return FALSE.

Remarks

EnumWindowStationProc is a placeholder for the application-defined function name. The WINSTAENUMPROC type is a pointer to an EnumWindowStationProc function.

See Also

EnumWindowStations


EnumWindowStations

The EnumWindowStations function enumerates all windowstations in the system by passing the name of each window station, in turn, to an application-defined callback function.

BOOL EnumWindowStations(

WINSTAENUMPROC lpEnumFunc,	// points to application’s callback function
LPARAM lParam	// 32-bit value to pass to the callback function
);
Parameters

lpEnumFunc

Points to an application-defined EnumWindowStationProc callback function.

lParam

Specifies a 32-bit application-defined value to be passed to the callback 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.

Remarks

The EnumWindowStations function enumerates only those window stations for which the calling process has WINSTA_ENUMERATE access.

EnumWindowStations repeatedly invokes the lpEnumFunc callback function until the last window station is enumerated or the callback function returns FALSE.

See Also

EnumWindowStationProc


EqualPrefixSid

The EqualPrefixSid function tests two security-identifier (SID) prefix values for equality. A SID prefix is the entire SID except for the last subauthority value.

BOOL EqualPrefixSid(

PSID pSid1,	// pointer to first SID to compare
PSID pSid2	// pointer to second SID to compare
);
Parameters

pSid1

Points to the first SID structure to compare. This structure is assumed to be valid.

pSid2

Points to the second SID structure to compare. It also is assumed to be valid.

Return Values

If the SID prefixes are equal, the return value is nonzero.

If the SID prefixes are not equal, the return value is zero. To get extended error information, call GetLastError.

Remarks

The EqualPrefixSid function enables a server application in one domain to verify an attempt by a user to log on to another domain. For example, if a user attempts to log on to RemoteDomain from a workstation in LocalDomain, the server for LocalDomain can request the SIDs for the user and the user’s groups from RemoteDomain. The domain controller for RemoteDomain responds with the relevant SIDs.

All SIDs for a specified domain necessarily have the same prefix. When the server receives the user’s SIDs, it can call the EqualPrefixSid function for each SID, comparing the user or group SID against the SID for RemoteDomain. If any of the SID prefixes are not equal, the server refuses the logon attempt.

It is advisable to modify the SID for a domain before comparing it with a group or user SID. If the SID for RemoteDomain is S-1−1234−8, each group or user SID for that domain will have S-1−1234−8 as its prefix. To compare the SIDs by using the EqualPrefixSid function, an application copies the domain SID and adds any subauthority (RID) value to the copy, thereby creating a SID in the form S-1−1234−8−0. The application then uses the modified domain SID as a template against which the group and user SIDs are compared.

See Also

CopySid, EqualSid, IsValidSid, SID


EqualRect

The EqualRect function determines whether the two specified rectangles are equal by comparing the coordinates of their upper-left and lower-right corners.

BOOL EqualRect(

CONST RECT *lprc1,	// pointer to structure with first rectangle
CONST RECT *lprc2	// pointer to structure with second rectangle
);
Parameters

lprc1

Points to a RECT structure that contains the logical coordinates of the first rectangle.

lprc2

Points to a RECT structure that contains the logical coordinates of the second rectangle.

Return Values

If the two rectangles are identical, the return value is nonzero.

If the two rectangles are not identical, the return value is zero. To get extended error information, call GetLastError.

See Also

IsRectEmpty, PtInRect, RECT


EqualRgn

The EqualRgn function checks the two specified regions to determine whether they are identical. The function considers two regions identical if they are equal in size and shape.

BOOL EqualRgn(

HRGN hSrcRgn1,	// handle to first region
HRGN hSrcRgn2	// handle to second region
);
Parameters

hSrcRgn1

Identifies a region.

hSrcRgn2

Identifies a region.

Return Values

If the two regions are equal, the return value is nonzero.

If the two regions are not equal, the return value is zero. A return value of ERROR means at least one of the region handles is invalid.

See Also

CreateRectRgn, CreateRectRgnIndirect


EqualSid

The EqualSid function tests two security identifier (SID) values for equality. Two SIDs must match exactly to be considered equal.

BOOL EqualSid(

PSID pSid1,	// pointer to first SID to compare
PSID pSid2	// pointer to second SID to compare
);
Parameters

pSid1

Points to the first SID structure to compare. This structure is assumed to be valid.

pSid2

Points to the second SID structure to compare. It also is assumed to be valid.

Return Values

If the SID structures are equal, the return value is nonzero.

If the SID structures are not equal, the return value is zero. To get extended error information, call GetLastError.

If either SID structure is invalid, the return value is undefined.

See Also

EqualPrefixSid, IsValidSid, SID


EraseTape

The EraseTape function erases all or part of a tape.

DWORD EraseTape(

HANDLE hDevice,	// handle to open device
DWORD dwEraseType,	// type of erasure to perform
BOOL bImmediate	// return after erase operation begins
);
Parameters

hDevice

Identifies the device where the tape is to be erased. This handle is created by using the CreateFile function.

dwEraseType

Specifies the erasing technique. This parameter can be one of the following values:

Value	Description
TAPE_ERASE_LONG	Erases the tape from the current position to the end of the current partition.
TAPE_ERASE_SHORT	Writes an erase gap or end-of-data marker at the current position.
bImmediate

Specifies whether to return as soon as the erase operation begins. If this parameter is TRUE, the function returns immediately; if it is FALSE, the function does not return until the erase operation has been completed.

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:

Error code	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
Remarks

Some tape devices do not support certain tape operations. To determine your tape device’s capabilities, see your tape device documentation and use the GetTapeParameters function.

See Also

CreateFile, GetTapeParameters


Escape

The Escape function allows applications to access capabilities of a particular device not directly available through GDI. Escape calls made by an application are translated and sent to the driver.

int Escape(

HDC hdc,	// handle to device context
int nEscape,	// escape function
int cbInput,	// number of bytes in input structure
LPCSTR lpvInData,	// pointer to input structure
LPVOID lpvOutData	// pointer to output structure
);
Parameters

hdc

Identifies the device context.

nEscape

Specifies the escape function to be performed. This parameter must be one of the predefined escape values. Use the ExtEscape function if your application defines a private escape value.

cbInput

Specifies the number of bytes of data pointed to by the lpvInData parameter.

lpvInData

Points to the input structure required for the specified escape.

lpvOutData

Points to the structure that receives output from this escape. This parameter should be NULL if no data is returned.

Return Values

If the function succeeds, the return value is greater than zero, except with the QUERYESCSUPPORT printer escape, which checks for implementation only. If the escape is not implemented, the return value is zero.

If the function fails, the return value is an error. To get extended error information, call GetLastError.

Errors

If the function fails, the return value is one of the following values.

Value	Meaning
SP_ERROR	General error. If SP_ERROR is returned, Escape may set the last error code to: ERROR_INVALID_PARAMETER ERROR_DISK_FULL ERROR_NOT_ENOUGH_MEMORY ERROR_PRINT_CANCELLED
SP_OUTOFDISK	Not enough disk space is currently available for spooling, and no more space will become available.
SP_OUTOFMEMORY	Not enough memory is available for spooling.
SP_USERABORT	The user terminated the job through Windows Print Manager.
Remarks

The Win32 API provides six new functions that supersede some printer escapes:

Function	Description
AbortDoc	Terminates a print job. Supersedes the ABORTDOC escape.
EndDoc	Ends a print job. Supersedes the ENDDOC escape.
EndPage	Ends a page. Supersedes the NEWFRAME escape. Unlike NEWFRAME, this function is always called after printing a page.
SetAbortProc	Sets the abort function for a print job. Supersedes the SETABORTPROC escape.
StartDoc	Starts a print job. Supersedes the STARTDOC escape.
StartPage	Prepares printer driver to receive data.
The Win32 API provides six new indexes for the GetDeviceCaps function that supersede some printer escapes:

Index	Description
PHYSICALWIDTH	For printing devices: the width of the physical page, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper has a physical width value of 5100 device units. Note that the physical page is almost always greater than the printable area of the page, and never smaller.
PHYSICALHEIGHT	For printing devices: the height of the physical page, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper has a physical height value of 6600 device units. Note that the physical page is almost always greater than the printable area of the page, and never smaller.
PHYSICALOFFSETX	For printing devices: the distance  from the left edge of the physical page to the left edge of the printable area, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper, that cannot print on the leftmost 0.25" of paper, has a horizontal physical offset of 150 device  units.
PHYSICALOFFSETY	For printing devices: the distance from the top edge of the physical page to the top edge of the printable area, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper, that cannot print on the topmost 0.5" of paper, has a vertical physical offset of 300 device units.
Of the original printer escapes, only the following can be used by Win32-based application:

Escape	Description
QUERYYESCSUPPORT	Determines whether a particular escape is implemented by the device driver.
Following is a list of the obsolete printer escapes that are supported only for compatibility with 16-bit versions of Windows:

Escape	Description
ABORTDOC	Stops the current print job and erases everything the application has written to the device since the last ENDDOC escape.
ENDDOC	Ends a print job started by the STARTDOC escape.
GETPHYSPAGESIZE	Retrieves the physical page size and copies it to the specified location.
GETPRINTINGOFFSET	Retrieves the offset from the upper-left corner of the physical page where the actual printing or drawing begins.
GETSCALINGFACTOR	Retrieves the scaling factors for the x-axis and the y-axis of a printer.
NEWFRAME	Informs the printer that the application has finished writing to a page.
NEXTBAND	Informs the printer that the application has finished writing to a band.
PASSTHROUGH	Allows the application to send data directly to a printer.
SETABORTPROC	Sets the Abort function for a print job.
STARTDOC	Informs a printer driver that a new print job is starting.
See Also

AbortDoc, EndDoc, EndPage, ExtEscape, SetAbortProc, StartDoc, StartPage, ResetDC


EscapeCommFunction

The EscapeCommFunction function directs a specified communications device to perform an extended function.

BOOL EscapeCommFunction(

HANDLE hFile,	// handle to communications device
DWORD dwFunc	// extended function to perform
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

dwFunc

Specifies the code of the extended function to perform. This parameter can be one of the following values:

Value	Meaning
CLRDTR	Clears the DTR (data-terminal-ready) signal.
CLRRTS	Clears the RTS (request-to-send) signal.
SETDTR	Sends the DTR (data-terminal-ready) signal.
SETRTS	Sends the RTS (request-to-send) signal.
SETXOFF	Causes transmission to act as if an XOFF character has been received.
SETXON	Causes transmission to act as if an XON character has been received.
SETBREAK	Suspends character transmission and places the transmission line in a break state until the ClearCommBreak function is called (or EscapeCommFunction is called with the CLRBREAK extended function code). The SETBREAK extended function code is identical to the SetCommBreak function. Note that this extended function does not flush data that has not been transmitted.
CLRBREAK	Restores character transmission and places the transmission line in a nonbreak state. The CLRBREAK extended function code is identical to the ClearCommBreak 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.

See Also

ClearCommBreak, CreateFile, SetCommBreak


ExcludeClipRect

The ExcludeClipRect function creates a new clipping region that consists of the existing clipping region minus the specified rectangle.

int ExcludeClipRect(

HDC hdc,	// handle to device context
int nLeftRect,	// x-coordinate of upper-left corner of rectangle
int nTopRect,	// y-coordinate of upper-left corner of rectangle
int nRightRect,	// x-coordinate of lower-right corner of rectangle
int nBottomRect	// y-coordinate of lower-right corner of rectangle
);
Parameters

hdc

Identifies the device context.

nLeftRect

Specifies the logical x-coordinate of the upper-left corner of the rectangle.

nTopRect

Specifies the logical y-coordinate of the upper-left corner of the rectangle.

nRightRect

Specifies the logical x-coordinate of the lower-right corner of the rectangle.

nBottomRect

Specifies the logical y-coordinate of the lower-right corner of the rectangle.

Return Values

If the function succeeds, the return value specifies the new clipping region’s complexity and can be any one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
ERROR	No region was created.
Remarks

The lower and right edges of the specified rectangle are not excluded from the clipping region.

See Also

IntersectClipRect


ExcludeUpdateRgn

The ExcludeUpdateRgn function prevents drawing within invalid areas of a window by excluding an updated region in the window from a clipping region.

int ExcludeUpdateRgn(

HDC hDC,	// handle to device context
HWND hWnd	// handle to window
);
Parameters

hDC

Identifies the device context associated with the clipping region.

hWnd

Identifies the window to update.

Return Values

The return value specifies the complexity of the excluded region; it can be any one of the following values:

Value	Meaning
COMPLEXREGION	Region consists of more than one rectangle.
ERROR	An error occurred.
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
See Also

BeginPaint, GetUpdateRect, GetUpdateRgn, UpdateWindow


ExitProcess

The ExitProcess function ends a process and all its threads.

VOID ExitProcess(

UINT uExitCode	// exit code for all threads
);
Parameters

uExitCode

Specifies the exit code for the process, and for all threads that are terminated as a result of this call. Use the GetExitCodeProcess function to retrieve the process’s exit value. Use the GetExitCodeThread function to retrieve a thread’s exit value.

Return Values

This function does not return a value.

Remarks

ExitProcess is the preferred method of ending a process. This function provides a clean process shutdown. This includes calling the entry-point function of all attached dynamic-link libraries (DLLs) with a value indicating that the process is detaching from the DLL. If a process terminates by calling TerminateProcess, the DLLs that the process is attached to are not notified of the process termination.

After all attached DLLs have executed any process termination value, this function terminates the current process.

Terminating a process causes the following:

1.	All of the object handles opened by the process are closed.

2.	All of the threads in the process terminate their execution.

3.	The state of the process object becomes signaled, satisfying any threads that had been waiting for the process to terminate.

4.	The states of all threads of the process become signaled, satisfying any threads that had been waiting for the threads to terminate.

5.	The termination status of the process changes from STILL_ACTIVE to the exit value of the process.

Terminating a process does not cause child processes to be terminated.

Terminating a process does not necessarily remove the process object from the operating system. A process object is deleted when the last handle to the process is closed.

The ExitProcess, ExitThread, CreateThread, CreateRemoteThread functions, and a process that is starting (as the result of a call by CreateProcess) are serialized between each other within a process. Only one of these events can happen in an address space at a time. This means the following restrictions hold:

•	During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.

•	Only one thread in a process can be in a DLL initialization or detach routine at a time.

•	ExitProcess does not return until no threads are in their DLL initialization or detach routines.

See Also

CreateProcess, CreateRemoteThread, CreateThread, ExitThread, GetExitCodeProcess, GetExitCodeThread, OpenProcess, TerminateProcess


ExitThread

The ExitThread function ends a thread.

VOID ExitThread(

DWORD dwExitCode	// exit code for this thread
);
Parameters

dwExitCode

Specifies the exit code for the calling thread. Use the GetExitCodeThread function to retrieve a thread’s exit code.

Return Values

This function does not return a value.

Remarks

ExitThread is the preferred method of exiting a thread. When this function is called (either explicitly or by returning from a thread procedure), the current thread’s stack is deallocated and the thread terminates. The entry-point function of all attached dynamic-link libraries (DLLs) is invoked with a value indicating that the thread is detaching from the DLL.

If the thread is the last thread in the process when this function is called, the thread’s process is also terminated.

The state of the thread object becomes signaled, releasing any other threads that had been waiting for the thread to terminate. The thread’s termination status changes from STILL_ACTIVE to the value of the dwExitCode parameter.

Terminating a thread does not necessarily remove the thread object from the operating system. A thread object is deleted when the last handle to the thread is closed.

The ExitProcess, ExitThread, CreateThread, CreateRemoteThread functions, and a process that is starting (as the result of a CreateProcess call) are serialized between each other within a process. Only one of these events can happen in an address space at a time. This means the following restrictions hold:

•	During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.

•	Only one thread in a process can be in a DLL initialization or detach routine at a time.

•	ExitProcess does not return until no threads are in their DLL initialization or detach routines.

A thread that uses functions from the C run-time libraries should use the _beginthread and _endthread C run-time functions for thread management rather than CreateThread and ExitThread. Failure to do so results in small memory leaks when ExitThread is called.

See Also

CreateProcess, CreateRemoteThread, CreateThread, ExitProcess, FreeLibraryAndExitThread, GetExitCodeThread, TerminateThread


ExitWindows

The ExitWindows function logs the current user off.

BOOL ExitWindows(

DWORD dwReserved,	// reserved
UINT uReserved	// reserved
);
Parameters

dwReserved

Reserved; must be zero.

uReserved

Reserved; must be zero.

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.

Remarks

Windows NT: The ExitWindows function asks applications if they want to terminate by sending the WM_QUERYENDSESSION message to the main window of all running applications.

Windows 95: The ExitWindows function sends the WM_QUERYENDSESSION message to all applications except the one that called ExitWindows.

An application agrees to terminate by returning TRUE when it receives this message (or by allowing the DefWindowProc function to process the message). If any application returns FALSE when it receives the WM_QUERYENDSESSION message, the shutdown is canceled.

After Windows processes the results of the WM_QUERYENDSESSION message, it sends the WM_ENDSESSION message with the wParam parameter set to TRUE if the system is shutting down and to FALSE if it is not.

Windows does not allow new applications to start up during the shutdown process.

See Also

DefWindowProc, ExitWindowsEx


ExitWindowsEx

The ExitWindowsEx function either logs off, shuts down, or shuts down and restarts the system.

BOOL ExitWindowsEx(

UINT uFlags,	// shutdown operation
DWORD dwReserved	// reserved
);
Parameters

uFlags

Specifies the type of shutdown. This parameter must be some combination of the following values:

Value	Meaning
EWX_FORCE	Forces processes to terminate. When this flag is set, Windows does not send the messages WM_QUERYENDSESSION and WM_ENDSESSION to the applications currently running in the system. This can cause the applications to lose data. Therefore, you should only use this flag in an emergency.
EWX_LOGOFF	Shuts down all processes running in the security context of the process that called the ExitWindowsEx function. Then it logs the user off.
EWX_POWEROFF	Shuts down the system and turns off the power. The system must support the power-off feature. Windows NT: The calling process must have the SE_SHUTDOWN_NAME privilege. For more information, see the following Remarks section.  Windows 95: Security privileges are not supported or required.
EWX_REBOOT	Shuts down the system and then restarts the system.  Windows NT: The calling process must have the SE_SHUTDOWN_NAME privilege. For more information, see the following Remarks section.  Windows 95: Security privileges are not supported or required.
EWX_SHUTDOWN	Shuts down the system to a point at which it is safe to turn off the power. All file buffers have been flushed to disk, and all running processes have stopped.  Windows NT: The calling process must have the SE_SHUTDOWN_NAME privilege. For more information, see the following Remarks section.  Windows 95: Security privileges are not supported or required.
dwReserved

Reserved; this parameter is ignored.

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.

Remarks

The ExitWindowsEx function returns as soon as it has initiated the shutdown. The shutdown or logoff then proceeds asynchronously.

During a shutdown or log-off operation, applications that are shut down are allowed a specific amount of time to respond to the shutdown request. If the time expires, Windows displays a dialog box that allows the user to forcibly shut down the application, to retry the shutdown, or to cancel the shutdown request. If the EWX_FORCE value is specified, Windows always forces applications to close and does not display the dialog box.

The ExitWindowsEx function sends a separate notification message, CTRL_SHUTDOWN_EVENT or CTRL_LOGOFF_EVENT as the situation warrants, to console processes. A console process routes these messages to its HandlerRoutine functions, which are added and removed by calls to the SetConsoleCtrlHandler function. ExitWindowsEx sends these notification messages asynchronously; thus, an application cannot assume that the console notification messages have been handled when a call to ExitWindowsEx returns.

Windows NT: To shut down or restart the system, the calling process must use the AdjustTokenPrivileges function to enable the SE_SHUTDOWN_NAME privilege. For more information about security privileges, see Privileges.

Windows 95: Security privileges are not supported or required.

See Also

AdjustTokenPrivileges, ExitWindows, HandlerRoutine, SetConsoleCtrlHandler


ExpandEnvironmentStrings

The ExpandEnvironmentStrings function expands environment-variable strings and replaces them with their defined values.

DWORD ExpandEnvironmentStrings(

LPCTSTR lpSrc,	// pointer to string with environment variables
LPTSTR lpDst,	// pointer to string with expanded environment variables
DWORD nSize	// maximum characters in expanded string
);
Parameters

lpSrc

Points to a null-terminated string that might contain references to environment-variable strings of the form:

%variableName%

For each such reference, the %variableName% portion is replaced with the current value of that environment variable.

The replacement rules are the same as those used by the command interpreter. Case is ignored when looking up the environment-variable name. If the name is not found, the %variableName% portion is left undisturbed.

lpDst

Points to a buffer to receive a copy of the source buffer, after all environment-variable name substitutions have been performed.

nSize

Specifies the maximum number of characters that can be stored in the buffer pointed to by the lpDst parameter, including the terminating null character.

Return Values

If the function succeeds, the return value is the number of characters stored in the destination buffer. If the number of characters is greater than the size of the destination buffer, the return value is the size of the buffer required to hold the expanded strings.

If the function fails, the return value is zero. To get extended error information, call GetLastError.


ExtCreatePen

The ExtCreatePen function creates a logical cosmetic or geometric pen that has the specified style, width, and brush attributes.

HPEN ExtCreatePen(

DWORD dwPenStyle,	// pen style
DWORD dwWidth,	// pen width
CONST LOGBRUSH *lplb,	// pointer to structure for brush attributes
DWORD dwStyleCount,	// length of array containing custom style bits
CONST DWORD *lpStyle	// optional array of custom style bits
);
Parameters

dwPenStyle

Specifies a combination of type, style, end cap, and join attributes. The values from each category are combined by using the bitwise OR operator (|).

The pen type can be one of the following values:

Type	Description
PS_GEOMETRIC	Pen is geometric.
PS_COSMETIC	Pen is cosmetic.
The pen style can be any one of the following values:

Style	Description
PS_ALTERNATE	Windows NT: Pen sets every other pixel. (This style is applicable only for cosmetic pens.) Windows 95: Not supported.
PS_SOLID	Pen is solid.
PS_DASH	Pen is dashed. Windows 95: This style is not supported for geometric lines.
PS_DOT	Pen is dotted. Windows 95: This style is not supported for geometric lines.
PS_DASHDOT	Pen has alternating dashes and dots. Windows 95: This style is not supported for geometric lines.
PS_DASHDOTDOT	Pen has alternating dashes and double dots. Windows 95: This style is not supported for geometric lines.
PS_NULL	Pen is invisible.
PS_USERSTYLE	Windows NT: Pen uses a styling array supplied by the user. Windows 95: Not supported.
PS_INSIDEFRAME	Pen is solid. When this pen is used in any graphics device interface (GDI) drawing function that takes a bounding rectangle, the dimensions of the figure are shrunk so that it fits entirely in the bounding rectangle, taking into account the width of the pen. This applies only to geometric pens.
The end cap is only specified for geometric pens. The end cap can be one of the following values:

End cap	Description
PS_ENDCAP_ROUND	End caps are round.
PS_ENDCAP_SQUARE	End caps are square.
PS_ENDCAP_FLAT	End caps are flat.
The join is only specified for geometric pens. The join can be one of the following values:

Line join	Description
PS_JOIN_BEVEL	Joins are beveled.
PS_JOIN_MITER	Joins are mitered when they are within the current limit set by the SetMiterLimit function. If it exceeds this limit, the join is beveled.
PS_JOIN_ROUND	Joins are round.
Windows 95: The PS_ENDCAP_ROUND, PS_ENDCAP_SQUARE, PS_ENDCAP_FLAT, PS_JOIN_BEVEL, PS_JOIN_MITER, and PS_JOIN_ROUND styles are supported only for geometric pens when used to draw paths.

dwWidth

Specifies the width of the pen. If the dwPenStyle parameter is PS_GEOMETRIC, the width is given in logical units. If dwPenStyle is PS_COSMETIC, the width must be set to 1.

lplb

Points to a LOGBRUSH structure. If dwPenStyle is PS_COSMETIC, the lbColor member specifies the color of the pen and the lbStyle member must be set to BS_SOLID. If dwPenStyle is PS_GEOMETRIC, all members must be used to specify the brush attributes of the pen.

dwStyleCount

Specifies the length, in doubleword units, of the lpStyle array. This value must be zero if dwPenStyle is not PS_USERSTYLE.

lpStyle

Points to an array of doubleword values. The first value specifies the length of the first dash in a user-defined style, the second value specifies the length of the first space, and so on. This pointer must be NULL if dwPenStyle is not PS_USERSTYLE.

Return Values

If the function succeeds, the return value is a handle that identifies a logical pen.

If the function fails, the return value is zero.

Remarks

A geometric pen can have any width and can have any of the attributes of a brush, such as dithers and patterns. A cosmetic pen can only be a single pixel wide and must be a solid color, but cosmetic pens are generally faster than geometric pens.

The width of a geometric pen is always specified in world units. The width of a cosmetic pen is always 1.

End cap and join are only specified for geometric pens.

After an application creates a logical pen, it can select that pen into a device context by calling the SelectObject function. After a pen is selected into a device context, it can be used to draw lines and curves.

If dwPenStyle is PS_COSMETIC and PS_USERSTYLE, the entries in the lpStyle array specify lengths of dashes and spaces in style units. A style unit is defined by the device where the pen is used to draw a line.

If dwPenStyle is PS_GEOMETRIC and PS_USERSTYLE, the entries in the lpStyle array specify lengths of dashes and spaces in logical units.

If dwPenStyle is PS_ALTERNATE, the style unit is ignored and every other pixel is set.

If the lbStyle member of the LOGBRUSH structure pointed to by lplb is BS_PATTERN, the bitmap pointed to by the lbHatch member of that structure cannot be a dib section. A dib section is a bitmap created by CreateDibSection. If that bitmap is a dib section, the ExtCreatePen function fails.

When an application no longer requires a specified pen, it should call the DeleteObject function to delete the pen.

See Also

CreatePen, CreateDibSection, CreatePenIndirect, DeleteObject, GetObject, LOGBRUSH, SelectObject, SetMiterLimit


ExtCreateRegion

The ExtCreateRegion function creates a region from the specified region and transformation data.

HRGN ExtCreateRegion(

CONST XFORM *lpXform,	// pointer to transformation data
DWORD nCount,	// size of structure containing region data
CONST RGNDATA *lpRgnData	// pointer to region data
);
Parameters

lpXform

Points to an XFORM structure that defines the transformation to be performed on the region. If this pointer is NULL, the identity transformation is used.

nCount

Specifies the number of bytes pointed to by lpRgnData.

lpRgnData

Points to a RGNDATA structure that contains the region data.

Return Values

If the function succeeds, the return value is the value of the region.

If the function fails, the return value is NULL.

Remarks

An application can retrieve data for a region by calling the GetRegionData function.

Windows 95: Regions are no longer limited to the 64K heap.

Windows 95: World transforms that involve either shearing or rotations are not supported. ExtCreateRegion fails if the transformation matrix is anything other than a scaling or translation of the region.

See Also

GetRegionData, RGNDATA, XFORM


ExtensionPropSheetPageProc

The ExtensionPropSheetPageProc function specifies an application-defined callback function that receives the address of the AddPropSheetPageProc function, which resides in the module that creates a property sheet. A property sheet extension must export the ExtensionPropSheetPageProc function.

BOOL CALLBACK ExtensionPropSheetPageProc(

LPVOID lpv,
LPFNADDPROPSHEETPAGE lpfnAddPropSheetPageProc,
LPARAM lParam
);
Parameters

lpv

Pointer to an application-defined value that describes an item for which a property sheet page is to be created. This parameter can be NULL.

lpfnAddPropSheetPageProc

Pointer to the AddPropSheetPageProc function. The extension dynamic-link library (DLL) calls this function to add a page to the property sheet.

lParam

Application-defined 32-bit value.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

AddPropSheetPageProc


ExtEscape

The ExtEscape function allows applications to access capabilities of a particular device that are not available through GDI.

int ExtEscape(

HDC hdc,	// handle to device context
int nEscape,	// escape function
int cbInput,	// number of bytes in input structure
LPCSTR lpszInData,	// pointer to input structure
int cbOutput,	// number of bytes in output structure
LPSTR lpszOutData	// pointer to output structure
);
Parameters

hdc

Identifies the device context.

nEscape

Specifies the escape function to be performed.

cbInput

Specifies the number of bytes of data pointed to by the lpszInData parameter.

lpszInData

Points to the input structure required for the specified escape.

cbOutput

Specifies the number of bytes of data pointed to by the lpszOutData parameter.

lpszOutData

Points to the structure that receives output from this escape. This parameter must not be NULL if ExtEscape is called as a query function. If no data is to be returned in this structure, set cbOutput to 0.

Return Values

The return value specifies the outcome of the function. It is greater than zero if the function is successful, except for the QUERYESCSUPPORT printer escape, which checks for implementation only. The return value is zero if the escape is not implemented. A return value less than zero indicates an error. To get extended error information, call GetLastError.

Remarks

Use this function to pass a driver-defined escape value to a device.

Use the Escape function to pass one of the escape values defined by Windows to a device. ExtEscape might not work properly with the escapes defined by Windows. In particular, escapes in which lpszInData points to a structure that contains a member that is a pointer will fail.

See Also

Escape, GetDeviceCaps


ExtFloodFill

The ExtFloodFill function fills an area of the display surface with the current brush.

BOOL ExtFloodFill(

HDC hdc,	// handle to device context
int nXStart,	// x-coordinate where filling begins
int nYStart,	// y-coordinate where filling begins
COLORREF crColor,	// fill color
UINT fuFillType	// fill type
);
Parameters

hdc

Identifies a device context.

nXStart

Specifies the logical x-coordinate of the point where filling is to begin.

nYStart

Specifies the logical y-coordinate of the point where filling is to begin.

crColor

Specifies the color of the boundary or of the area to be filled. The interpretation of crColor depends on the value of the fuFillType parameter.

fuFillType

Specifies the type of fill operation to be performed. It must be one of the following values:

Value	Meaning
FLOODFILLBORDER	The fill area is bounded by the color specified by the crColor parameter. This style is identical to the filling performed by the FloodFill function.
FLOODFILLSURFACE	The fill area is defined by the color that is specified by crColor. Filling continues outward in all directions as long as the color is encountered. This style is useful for filling areas with multicolored boundaries.
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.

Remarks

Following are some of the reasons this function might fail:

•	The filling could not be completed.

•	The specified point has the boundary color specified by the crColor parameter (if FLOODFILLBORDER was requested).

•	The specified point does not have the color specified by crColor (if FLOODFILLSURFACE was requested).

•	The point is outside the clipping region — that is, it is not visible on the device.

If the fuFillType parameter is FLOODFILLBORDER, Windows assumes that the area to be filled is completely bounded by the color specified by the crColor parameter. The function begins filling at the point specified by the nXStart and nYStart parameters and continues in all directions until it reaches the boundary.

If fuFillType is FLOODFILLSURFACE, Windows assumes that the area to be filled is a single color. The function begins to fill the area at the point specified by nXStart and nYStart and continues in all directions, filling all adjacent regions containing the color specified by crColor.

Only memory device contexts and devices that support raster-display operations support the ExtFloodFill function. To determine whether a device supports this technology, use the GetDeviceCaps function.

See Also

FloodFill, GetDeviceCaps


ExtractAssociatedIcon

The ExtractAssociatedIcon function returns the handle of an indexed icon found in a file or an icon found in an associated executable file.

HICON ExtractAssociatedIcon(

HINSTANCE hInst,	// application instance handle
LPTSTR lpIconPath,	// path and filename of file for which icon is wanted
LPWORD lpiIcon	// pointer to icon index
);
Parameters

hInst

Specifies the instance of the application calling the function.

lpIconPath

Points to a string that specifies the full path and filename of the file for which an icon is desired. The function extracts the icon handle from that file, or from an executable file associated with that file.

If the icon handle is obtained from an executable file, the function stores the full path and filename of that executable in the string pointed to by lpIconPath.

lpiIcon

Points to a WORD that specifies the index of the icon whose handle is to be obtained.

If the icon handle is obtained from an executable file, the function stores the icon’s identifier in the WORD pointed to by lpiIcon.

Return Values

If the function succeeds, the return value is an icon handle. If the icon is extracted from an associated executable file, the function stores the full path and filename of the executable file in the string pointed to by lpIconPath, and stores the icon’s identifier in the WORD pointed to by lpiIcon.

If the function fails, the return value is NULL.

Remarks

The ExtractAssociatedIcon function first looks for the indexed icon in the file specified by lpIconPath. If the function cannot obtain the icon handle from that file, and the file has an associated executable file, it looks in that executable file for an icon. Associations with executable files are based on filename extensions, are stored in the per-user part of the registry, and can be defined using File Manager’s Associate command.

See Also

ExtractIcon


ExtractIcon

The ExtractIcon function retrieves the handle of an icon from the specified executable file, dynamic-link library (DLL), or icon file.

HICON ExtractIcon(

HINSTANCE hInst,	// instance handle
LPCTSTR lpszExeFileName,	// filename of file with icon
UINT nIconIndex	// index of icon to extract
);
Parameters

hInst

Identifies the instance of the application calling the function.

lpszExeFileName

Points to a null-terminated string specifying the name of an executable file, DLL, or icon file.

nIconIndex

Specifies the index of the icon to retrieve. If this value is 0, the function returns the handle of the first icon in the specified file. If this value is −1, the function returns the total number of icons in the specified file.

Return Values

If the function succeeds, the return value is the handle to an icon. If the file specified was not an executable file, DLL, or icon file, the return is 1. If no icons were found in the file, the return value is NULL.


ExtractIconEx

The ExtractIconEx function retrieves the handle of an icon from the specified executable file, dynamic-link library (DLL), or icon file.

HICON ExtractIconEx(

LPCSTR lpszFile,
int nIconIndex,
HICON FAR * phiconLarge,
HICON FAR * phiconSmall,
UINT nIcons
);
Parameters

lpszFile

Pointer to a null-terminated string specifying the name of an executable file, DLL, or icon file.

nIconIndex

Specifies the index of the icon to retrieve. If this value is 0, the function returns the handle of the first icon in the specified file. If this value is −1 and phIconLargeand phiconSmall are both NULL, the function returns the total number of icons in the specified file.

phiconLarge

Pointer to an array of handles of large icons returned. This parameter can be NULL.

phiconSmall

Pointer to an array of handles of small icons returned. This parameter can be NULL.

nIcons

Specifies the count of the number of icons to extract.

Return Values

If the function succeeds, the return value is the handle to an icon. If the file specified was not an executable file, DLL, or icon file, the return value is 1. If no icons were found in the file, the return value is NULL.

See Also

ExtractIcon


ExtSelectClipRgn

The ExtSelectClipRgn function combines the specified region with the current clipping region by using the specified mode.

int ExtSelectClipRgn(

HDC hdc,	// handle to device context
HRGN hrgn,	// handle to region
int fnMode	// region-selection mode
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies the region to be selected. This handle can only be NULL when the RGN_COPY mode is specified.

fnMode

Specifies the operation to be performed. It must be one of the following values:

Value	Meaning
RGN_AND	The new clipping region combines the overlapping areas of the current clipping region and the region identified by hrgn.
RGN_COPY	The new clipping region is a copy of the region identified by hrgn. This is identical to SelectClipRgn. If the region identified by hrgn is NULL, the new clipping region is the default clipping region (the default clipping region is a null region).
RGN_DIFF	The new clipping region combines the areas of the current clipping region with those areas excluded from the region identified by hrgn.
RGN_OR	The new clipping region combines the current clipping region and the region identified by hrgn.
RGN_XOR	The new clipping region combines the current clipping region and the region identified by hrgn but excludes any overlapping areas.
Return Values

If the function succeeds, the return value specifies the new clipping region’s complexity and can be any one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
ERROR	An error occurred.
Remarks

If an error occurs when this function is called, the previous clipping region for the specified device context is not affected.

The ExtSelectClipRgn function assumes that the coordinates for the specified region are specified in device units.

Only a copy of the region identified by the hrgn parameter is used. The region itself can be reused after this call or it can be deleted.

See Also

SelectClipRgn


ExtTextOut

The ExtTextOut function draws a character string by using the currently selected font. An optional rectangle may be provided, to be used for clipping, opaquing, or both.

BOOL ExtTextOut(

HDC hdc,	// handle to device context
int X,	// x-coordinate of reference point
int Y,	// y-coordinate of reference point
UINT fuOptions,	// text-output options
CONST RECT *lprc,	// optional clipping and/or opaquing rectangle
LPCTSTR lpString,	// points to string
UINT cbCount,	// number of characters in string
CONST INT *lpDx	// pointer to array of intercharacter spacing values
);
Parameters

hdc

Identifies the device context.

X

Specifies the logical x-coordinate of the reference point used to position the string.

Y

Specifies the logical y-coordinate of the reference point used to position the string.

fuOptions

Specifies how to use the application-defined rectangle. This parameter can be a combination of the following values:

Value	Meaning
ETO_CLIPPED	The text will be clipped to the rectangle.
ETO_GLYPH_INDEX	Windows 95 only: The lpString array refers to an array returned from GetCharacterPlacement and should be parsed directly by GDI as no further language-specific processing is required. Glyph indexing only applies to TrueType fonts, but the flag can be used for Windows bitmap and vector fonts to indicate no further language processing is necessary and GDI should process the string directly. Note that all glyph indices are 16-bit values even though the string is assumed to be an array of 8-bit values for raster fonts.
ETO_OPAQUE	The current background color should be used to fill the rectangle.
ETO_RTLREADING	Windows 95 only: If this value is specified and a Hebrew or Arabic font is selected into the device context, the string is output using right-to-left reading order. If this value is not specified, the string is output in left- to-right order. The same effect can be achieved by setting the TA_RTLREADING value in SetTextAlign. This value is preserved for backward compatability.
The ETO_GLYPH_INDEX and ETO_RTLREADING values cannot be used together. Because ETO_GLYPH_INDEX implies that all language processing has been completed, the function ignores the ETO_RTLREADING flag if also specified.

lprc

Points to an optional RECT structure that specifies the dimensions of a rectangle that is used for clipping, opaquing, or both.

lpString

Points to the character string to be drawn. The string does not need to be zero-terminated, since cbCount specifies the length of the string.

cbCount

Specifies the number of characters in the string.

lpDx

Points to an optional array of values that indicate the distance between origins of adjacent character cells. For example, lpDx[i] logical units separate the origins of character cell i and character cell i + 1.

Return Values

If the string is drawn, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The current text-alignment settings for the specified device context determine how the reference point is used to position the text. The text-alignment settings are retrieved by calling the GetTextAlign function. The text-alignment settings are altered by calling the SetTextAlign function.

If the lpDx parameter is NULL, the ExtTextOut function uses the default spacing between characters. The character-cell origins and the contents of the array pointed to by the lpDx parameter are given in logical units. A character-cell origin is defined as the upper-left corner of the character cell.

By default, the current position is not used or updated by this function. However, an application can call the SetTextAlign function with the fMode parameter set to TA_UPDATECP to permit Windows to use and update the current position each time the application calls ExtTextOut for a specified device context. When this flag is set, Windows ignores the X and Y parameters on subsequent ExtTextOut calls.

See Also

GetTextAlign, RECT, SetTextAlign


FatalAppExit

The FatalAppExit function displays a message box and terminates the application when the message box is closed. If Windows is running with a kernel debugger, the message box gives the user the opportunity to terminate the application or to cancel the message box and return to the application that called FatalAppExit.

VOID FatalAppExit(

UINT uAction,	// reserved
LPCTSTR lpMessageText	// pointer to string to display in message box
);
Parameters

uAction

Reserved; must be zero.

lpMessageText

Points to a null-terminated string that is displayed in the message box. The message is displayed on a single line. To accommodate low-resolution screens, the string should be no more than 35 characters in length.

Return Values

This function does not return a value.

Remarks

An application calls FatalAppExit only when it is not capable of terminating any other way. FatalAppExit may not always free an application’s memory or close its files, and it may cause a general failure of Windows. An application that encounters an unexpected error should terminate by freeing all its memory and returning from its main message loop.

See Also

FatalExit


FatalExit

The FatalExit function transfers execution control to the debugger. The behavior of the debugger thereafter is specific to the type of debugger used.

VOID FatalExit(

int ExitCode	// error code
);
Parameters

ExitCode

Specifies the error code associated with the exit.

Return Values

This function does not return a value.

Remarks

An application should only use FatalExit for debugging purposes. It should not call the function in a retail version of the application because doing so will terminate the application.

See Also

FatalAppExit


FileIOCompletionRoutine

The FileIOCompletionRoutine function is called when an asynchronous input and output (I/O) function (ReadFileEx or WriteFileEx) is completed and the calling thread is in an alertable wait (using the SleepEx, WaitForSingleObjectEx, or WaitForMultipleObjectsEx function with the fAlertable flag set to TRUE).

VOID WINAPI FileIOCompletionRoutine(

DWORD dwErrorCode,	// completion code
DWORD dwNumberOfBytesTransfered,	// number of bytes transferred
LPOVERLAPPED lpOverlapped	// pointer to structure with I/O information
);
Parameters

dwErrorCode

Specifies the I/O completion status. This parameter may be one of the following values:

Value	Meaning
0	The I/O was successful.
ERROR_HANDLE_EOF	The ReadFileEx function tried to read past the end of the file.
dwNumberOfBytesTransfered

Specifies the number of bytes transferred. If an error occurs, this parameter is zero.

lpOverlapped

Points to the OVERLAPPED structure specified by the asynchronous I/O function.

Windows does not use the hEvent member of the OVERLAPPED structure; the calling application may use this member to pass information to the completion routine. Windows does not use the OVERLAPPED structure after the completion routine is called, so the completion routine can deallocate the memory used by the overlapped structure.

Return Values

This function does not return a value.

Remarks

The FileIOCompletionRoutine function is a placeholder for an application-defined or library-defined function name.

Returning from this function allows another pending I/O completion routine to be called. All waiting completion routines are called before the alertable thread’s wait is satisfied with a return code of WAIT_IO_COMPLETION. Windows may call the waiting completion routines in any order. They may or may not be called in the order the I/O functions are completed.

Each time Windows calls a completion routine, it uses some of the application’s stack. If the completion routine does additional asynchronous I/O and alertable waits, the stack may grow.

See Also

OVERLAPPED, ReadFileEx, SleepEx, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFileEx


FileTimeToDosDateTime

The FileTimeToDosDateTime function converts a 64-bit file time to MS-DOS date and time values.

BOOL FileTimeToDosDateTime(

CONST FILETIME *lpFileTime,	// pointer to 64-bit file time
LPWORD lpFatDate,	// pointer to variable for MS-DOS date
LPWORD lpFatTime	// pointer to variable for MS-DOS time
);
Parameters

lpFileTime

Points to a FILETIME structure containing the 64-bit file time to convert to MS-DOS date and time format. The FILETIME structure has the following form:

typedef struct _FILETIME { // ft

    DWORD dwLowDateTime;

    DWORD dwHighDateTime;

} FILETIME;

lpFatDate

Points to a variable to receive the MS-DOS date. The date is a packed 16-bit value with the following format:

Bits	Contents
0−4	Day of the month (1−31)
5−8	Month (1 = January, 2 = February, etc.)
9−15	Year offset from 1980 (add 1980 to get actual year)
lpFatTime

Points to a variable to receive the MS-DOS time. The time is a packed 16-bit value with the following format:

Bits	Contents
0−4	Second divided by 2
5−10	Minute (0−59)
11−15	Hour (0−23 on a 24-hour clock)
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.

Remarks

The MS-DOS date format can represent only dates between 1/1/1980 and 12/31/2107; this conversion fails if the input file time is outside this range.

See Also

DosDateTimeToFileTime, FileTimeToSystemTime, SystemTimeToFileTime


FileTimeToLocalFileTime

The FileTimeToLocalFileTime function converts a file time based on the Coordinated Universal Time (UTC) to a local file time.

BOOL FileTimeToLocalFileTime(

CONST FILETIME *lpFileTime,	// pointer to UTC file time to convert
LPFILETIME lpLocalFileTime	// pointer to converted file time
);
Parameters

lpFileTime

Points to a FILETIME structure containing the UTC-based file time to be converted into a local file time.

lpLocalFileTime

Points to a FILETIME structure to receive the converted local file time. This parameter cannot be the same as the lpFileTime parameter.

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.

See Also

FILETIME, LocalFileTimeToFileTime


FileTimeToSystemTime

The FileTimeToSystemTime function converts a 64-bit file time to system time format.

BOOL FileTimeToSystemTime(

CONST FILETIME *lpFileTime,	// pointer to file time to convert
LPSYSTEMTIME lpSystemTime	// pointer to structure to receive system time
);
Parameters

lpFileTime

Pointer to a FILETIME structure containing the file time to convert to system date and time format.

The FileTimeToSystemTime function only works with FILETIME values that are less than 0x8000000000000000. The function fails with values equal to or greater than that.

lpSystemTime

Pointer to a SYSTEMTIME structure to receive the converted file time.

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.

Remarks

As noted above, the function fails for FILETIME values that are equal to or greater than 0x8000000000000000.

See Also

DosDateTimeToFileTime, FILETIME, FileTimeToDosDateTime, SYSTEMTIME, SystemTimeToFileTime


FillConsoleOutputAttribute

The FillConsoleOutputAttribute function sets the text and background color attributes for a specified number of character cells, beginning at the specified coordinates in a screen buffer.

BOOL FillConsoleOutputAttribute(

HANDLE hConsoleOutput,	// handle to screen buffer
WORD wAttribute,	// color attribute to write
DWORD nLength,	// number of character cells to write to
COORD dwWriteCoord,	// x- and y-coordinates of first cell
LPDWORD lpNumberOfAttrsWritten	// pointer to number of cells written to
);
Parameters

hConsoleOutput

Identifies a screen buffer. The handle must have GENERIC_WRITE access.

wAttribute

Specifies the foreground and background color attributes to write to the screen buffer. Any combination of the following values can be specified: FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_RED, FOREGROUND_INTENSITY, BACKGROUND_BLUE, BACKGROUND_GREEN, BACKGROUND_RED, and BACKGROUND_INTENSITY. For example, the following combination of values produces white text on a black background:

FOREGROUND_RED | FOREGROUND_GREEN | FOREGROUND_BLUE

nLength

Specifies the number of character cells to be set to the specified color attributes.

dwWriteCoord

Specifies a COORD structure containing the screen buffer coordinates of the first cell whose attributes are to be set.

lpNumberOfAttrsWritten

Points to the variable that receives the number of character cells whose attributes were actually set.

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.

Remarks

If the number of character cells whose attributes are to be set extends beyond the end of the specified row in the screen buffer, the cells of the next row are set. If the number of cells to write to extends beyond the end of the screen buffer, the cells are written up to the end of the screen buffer.

The character values at the positions written to are not changed.

See Also

COORD, FillConsoleOutputCharacter, SetConsoleTextAttribute, WriteConsoleOutputAttribute


FillConsoleOutputCharacter

The FillConsoleOutputCharacter function writes a character to the screen buffer a specified number of times, beginning at the specified coordinates.

BOOL FillConsoleOutputCharacter(

HANDLE hConsoleOutput,	// handle to screen buffer
TCHAR cCharacter,	// character to write
DWORD nLength,	// number of character cells to write to
COORD dwWriteCoord,	// x- and y-coordinates of first cell
LPDWORD lpNumberOfCharsWritten	// pointer to number of cells written to
);
Parameters

hConsoleOutput

Identifies a screen buffer. The handle must have GENERIC_WRITE access.

cCharacter

Specifies the character to write to the screen buffer.

nLength

Specifies the number of character cells to write the character to.

dwWriteCoord

Specifies a COORD structure containing the screen buffer coordinates of the first cell to write the character to.

lpNumberOfCharsWritten

Points to the variable that receives the number of characters actually written to the screen buffer.

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.

Remarks

If the number of characters to write to extends beyond the end of the specified row in the screen buffer, characters are written to the next row. If the number of characters to write to extends beyond the end of the screen buffer, the characters are written up to the end of the screen buffer.

The attribute values at the positions written are not changed.

Windows NT: This function uses either Unicode characters or 8-bit characters from the console's current codepage. The console's codepage defaults initially to the system's OEM codepage. To change the console's codepage, use the SetConsoleCP or SetConsoleOutputCP functions, or use the chcp or mode con cp select= commands.

See Also

COORD, FillConsoleOutputAttribute, SetConsoleCP, SetConsoleOutputCP, WriteConsoleOutputCharacter


FillMemory

The FillMemory function fills a block of memory with a specified value.

VOID FillMemory (

PVOID Destination,	// pointer to block to fill
DWORD Length,	// size, in bytes, of block to fill
BYTE Fill	// the byte value with which to fill
);
Parameters

Destination

Points to the starting address of the block of memory to fill.

Length

Specifies the size, in bytes, of the block of memory to fill.

Fill

Specifies the byte value with which to fill the memory block.

Return Values

This function has no return value.

See Also

CopyMemory, MoveMemory, ZeroMemory


FillPath

The FillPath function closes any open figures in the current path and fills the path’s interior by using the current brush and polygon-filling mode.

BOOL FillPath(

HDC hdc	// handle to device context
);
Parameters

hdc

Identifies a device context (DC) that contains a valid path.

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 one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY

Remarks

After its interior is filled, the path is discarded from the DC identified by the hdc parameter.

See Also

BeginPath, SetPolyFillMode, StrokeAndFillPath, StrokePath


FillRect

The FillRect function fills a rectangle by using the specified brush. This function includes the left and top borders, but excludes the right and bottom borders of the rectangle.

int FillRect(

HDC hDC,	// handle to device context
CONST RECT *lprc,	// pointer to structure with rectangle
HBRUSH hbr	// handle to brush
);
Parameters

hDC

Identifies the device context.

lprc

Points to a RECT structure that contains the logical coordinates of the rectangle to be filled.

hbr

Identifies the brush used to fill the rectangle.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The brush identified by the hbr parameter may be either a handle to a logical brush or a color value. If specifying a handle to a logical brush, call one of the following functions to obtain the handle: CreateHatchBrush, CreatePatternBrush, or CreateSolidBrush. Additionally, you may retrieve a handle to one of the stock brushes by using the GetStockObject function. If specifying a color value for the hbr parameter, it must be one of the standard system colors (the value 1 must be added to the chosen color). For example:

FillRect(hdc, &rect, (HBRUSH) (COLOR_ENDCOLORS+1));

For a list of all the standard system colors, see GetSysColor.

When filling the specified rectangle, FillRect does not include the rectangle’s right and bottom sides. GDI fills a rectangle up to, but not including, the right column and bottom row, regardless of the current mapping mode.

See Also

CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, GetStockObject, RECT


FillRgn

The FillRgn function fills a region by using the specified brush.

BOOL FillRgn(

HDC hdc,	// handle to device context
HRGN hrgn,	// handle to region to be filled
HBRUSH hbr	// handle to brush used to fill the region
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies the region to be filled. The region’s coordinates are presumed to be in logical units.

hbr

Identifies the brush to be used to fill the region.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

CreateBrushIndirect, CreateDIBPatternBrush, CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, PaintRgn


FindAtom

The FindAtom function searches the local atom table for the specified character string and retrieves the atom associated with that string.

ATOM FindAtom(

LPCTSTR lpString	// pointer to string to find
);
Parameters

lpString

Points to the null-terminated character string to search for.

Return Values

If the function succeeds, the return value is the atom associated with the given string.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Even though Windows preserves the case of a string in an atom table, the search performed by the FindAtom function is not case sensitive.

See Also

AddAtom, DeleteAtom, GlobalAddAtom, GlobalDeleteAtom, GlobalFindAtom


FindClose

The FindClose function closes the specified search handle. The FindFirstFile and FindNextFile functions use the search handle to locate files with names that match a given name.

BOOL FindClose(

HANDLE hFindFile	// file search handle
);
Parameters

hFindFile

Identifies the search handle. This handle must have been previously opened by the FindFirstFile 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.

Remarks

After the FindClose function is called, the handle specified by the hFindFile parameter cannot be used in subsequent calls to either the FindNextFile or FindClose function.

See Also

FindFirstFile, FindNextFile


FindCloseChangeNotification

The FindCloseChangeNotification function stops change notification handle monitoring.

BOOL FindCloseChangeNotification(

HANDLE hChangeHandle	// handle to change notification to close
);
Parameters

hChangeHandle

Identifies a change notification handle created by the FindFirstChangeNotification 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.

Remarks

After the FindCloseChangeNotification function is called, the handle specified by the hChangeHandle parameter cannot be used in subsequent calls to either the FindNextChangeNotification or FindCloseChangeNotification function.

Change notifications can also be used in the wait functions.

See Also

FindFirstChangeNotification, FindNextChangeNotification


FindClosePrinterChangeNotification

The FindClosePrinterChangeNotification function closes a change notification object created by calling the FindFirstPrinterChangeNotification function. The printer or print server associated with the change notification object will no longer be monitored by that object.

BOOL FindClosePrinterChangeNotification(

HANDLE hChange	// handle to change notification object to close
);
Parameters

hChange

Handle to the change notification object to be closed. This is a handle created by calling the FindFirstPrinterChangeNotification 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.

Remarks

After calling the FindClosePrinterChangeNotification function, you cannot use the hChange handle in subsequent calls to either FindFirstPrinterChangeNotification or FindNextPrinterChangeNotification.

The three Find*PrinterChangeNotification functions, in combination with the wait functions, provide an asynchronous, more resource-efficient alternative to the WaitForPrinterChange function.

See Also

FindFirstPrinterChangeNotification, FindNextPrinterChangeNotification, WaitForPrinterChange


FindExecutable

The FindExecutable function retrieves the name and handle to the executable (.EXE) file associated with the specified filename.

HINSTANCE FindExecutable(

LPCTSTR lpFile,	// pointer to string for filename
LPCTSTR lpDirectory,	// pointer to string for default directory
LPTSTR lpResult	// pointer to buffer for string for executable file on return
);
Parameters

lpFile

Pointer to a null-terminated string specifying a filename. This can be a document or executable file.

lpDirectory

Pointer to a null-terminated string specifying the default directory.

lpResult

Pointer to a buffer to receive the filename when the function returns. This filename is a null-terminated string specifying the executable file started when an “open” association is run on the file specified in the lpFile parameter.

Return Values

If the function succeeds, the return value is greater than 32.

If the function fails, the return value is less than or equal to 32. The following table lists the possible error values:

Value	Meaning
0	The system is out of memory or resources.
31	There is no association for the specified file type.
ERROR_FILE_NOT_FOUND	The specified file was not found.
ERROR_PATH_NOT_FOUND	The specified path was not found.
ERROR_BAD_FORMAT	The .EXE file is invalid (non-Win32 .EXE or error in .EXE image).
Remarks

When FindExecutable returns, the lpResult parameter may contain the path to the DDE server started if no server responds to a request to initiate a DDE conversation.

See Also

ShellExecute


FindFirstChangeNotification

The FindFirstChangeNotification function creates a change notification handle and sets up initial change notification filter conditions. A wait on a notification handle succeeds when a change matching the filter conditions occurs in the specified directory or subtree.

HANDLE FindFirstChangeNotification(

LPCTSTR lpPathName,	// pointer to name of directory to watch
BOOL bWatchSubtree,	// flag for monitoring directory or directory tree
DWORD dwNotifyFilter	// filter conditions to watch for
);
Parameters

lpPathName

Points to a null-terminated string that specifies the path of the directory to watch.

bWatchSubtree

Specifies whether the function will monitor the directory or the directory tree. If this parameter is TRUE, the function monitors the directory tree rooted at the specified directory; if it is FALSE, it monitors only the specified directory.

dwNotifyFilter

Specifies the filter conditions that satisfy a change notification wait. This parameter can be one or more of the following values:

Value	Meaning
FILE_NOTIFY_CHANGE_FILE_NAME
	Any filename change in the watched directory or subtree causes a change notification wait operation to return. Changes include renaming, creating, or deleting a filename.
FILE_NOTIFY_CHANGE_DIR_NAME
	Any directory-name change in the watched directory or subtree causes a change notification wait operation to return. Changes include creating or deleting a directory.
FILE_NOTIFY_CHANGE_ATTRIBUTES
	Any attribute change in the watched directory or subtree causes a change notification wait operation to return.
FILE_NOTIFY_CHANGE_SIZE
	Any file-size change in the watched directory or subtree causes a change notification wait operation to return. The operating system detects a change in file size only when the file is written to the disk. For operating systems that use extensive caching, detection occurs only when the cache is sufficiently flushed.
FILE_NOTIFY_CHANGE_LAST_WRITE
	Any change to the last write-time of files in the watched directory or subtree causes a change notification wait operation to return. The operating system detects a change to the last write-time only when the file is written to the disk. For operating systems that use extensive caching, detection occurs only when the cache is sufficiently flushed.
FILE_NOTIFY_CHANGE_SECURITY
	Any security-descriptor change in the watched directory or subtree causes a change notification wait operation to return.
Return Values

If the function succeeds, the return value is a handle to a find change notification object.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

The wait functions can monitor the specified directory or subtree by using the handle returned by the FindFirstChangeNotification function. A wait is satisfied when one of the filter conditions occurs in the monitored directory or subtree.

After the wait has been satisfied, the application can respond to this condition and continue monitoring the directory by calling the FindNextChangeNotification function and the appropriate wait function. When the handle is no longer needed, it can be closed by using the FindCloseChangeNotification function.

See Also

FindCloseChangeNotification, FindNextChangeNotification


FindFirstFile

The FindFirstFile function searches a directory for a file whose name matches the specified filename. FindFirstFile examines subdirectory names as well as filenames.

HANDLE FindFirstFile(

LPCTSTR lpFileName,	// pointer to name of file to search for
LPWIN32_FIND_DATA lpFindFileData	// pointer to returned information
);
Parameters

lpFileName

Windows 95: Points to a null-terminated string that specifies a valid directory or path and filename, which can contain wildcard characters (* and ?). This string must not exceed MAX_PATH characters.

Windows NT: Points to a null-terminated string that specifies a valid directory or path and filename, which can contain wildcard characters (* and ?).

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the FindFirstFile function parses paths. An application can transcend this limit and send in paths longer than MAX_PATH characters by calling the wide (W) version of FindFirstFile and prepending “\\?\” to the path. The “\\?\” tells the function to turn off path parsing; it lets paths longer than MAX_PATH be used with FindFirstFileW. This also works with UNC names. The “\\?\” is ignored as part of the path. For example, “\\?\C:\myworld\private” is seen as “C:\myworld\private”, and “\\?\UNC\bill_g_1\hotstuff\coolapps” is seen as “\\bill_g_1\hotstuff\coolapps”.

lpFindFileData

Points to the WIN32_FIND_DATA structure that receives information about the found file or subdirectory. The structure can be used in subsequent calls to the FindNextFile or FindClose function to refer to the file or subdirectory.

Return Values

If the function succeeds, the return value is a search handle used in a subsequent call to FindNextFile or FindClose.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

The FindFirstFile function opens a search handle and returns information about the first file whose name matches the specified pattern. Once the search handle is established, you can use the FindNextFile function to search for other files that match the same pattern. When the search handle is no longer needed, close it by using the FindClose function.

This function searches for files by name only; it cannot be used for attribute-based searches.

See Also

FindClose, FindNextFile, GetFileAttributes, SetFileAttributes, WIN32_FIND_DATA


FindFirstFileEx [New - Windows NT]
FindFirstFileEx

[New - Windows NT]

The FindFirstFileEx function searches a directory for a file whose name and attributes match those specified in the function call.

HANDLE FindFirstFileEx(

LPCTSTR lpFileName,	// pointer to the name of the file to search for
FINDEX_INFO_LEVELS fInfoLevelId,	// information level of the returned data
LPVOID lpFindFileData,	// pointer to the returned information
FINDEX_SEARCH_OPS fSearchOp,	// type of filtering to perform
LPVOID lpSearchFilter,	// pointer to search criteria
DWORD dwAdditionalFlags	// additional search control flags
);
Parameters

lpFileName

Points to a null-terminated string that specifies a valid directory or path and filename, which can contain wildcard characters (* and ?).

fInfoLevelId

Specifies the information level of the returned data. If the FindExInfoStandard constant is used, the lpFindFileData pointer is the standard WIN32_FIND_DATA structure used with FindFirstFile. At this time, no other information levels are supported.

lpFindFileData

Pointer to the file data. The pointer type is determined by the level of information specified in the fInfoLevelId parameter.

fSearchOp

Specifies the type of filtering to perform beyond wildcard matching. For more details, see the Remarks section later in this topic.

lpSearchFilter

If the specified fSearchOp needs structured search information, lpSearchFilter points to the search criteria. At this time, none of the supported fSearchOp values require extended search information. Therefore, this pointer must be NULL.

dwAdditionalFlags

Specifies additional flags for controlling the search. You can use the FIND_FIRST_EX_CASE_SENSITIVE flag for case-sensitive searches. The default search is case insensitive. At this time, no other flags are defined.

Return Value

If the function succeeds, the return value is a search handle that can be used in a subsequent call to the FindNextFile or FindClose functions.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

The FindFirstFileEx function is provided to open a search handle and return information about the first file whose name matches the specified pattern and attributes.

The way additional filtering is done depends on the value of fSearchOp. The fSearchOp parameter can be one of the following values:

Value	Meaning
FindExSearchNameMatch	Search for a file that matches the specified filename. Note that lpSearchFilter must be NULL when this search operation is used.
FindExSearchLimitToDevices	Only device names are returned. Device names are generally accessible through the \\.\<name> convention. The dwAdditionalFlags parameter cannot be FIND_FIRST_EX_CASE_SENSITIVE when this search operation is used.
FindExSearchLimitToDirectories	This is an advisory flag.  If the file system supports directory filtering, the function searches for a “file” that matches the specified filename and that is a directory.  If the file system does not support directory filtering, this flag is silently ignored. The lpSearchFilter parameter must be NULL when this search operation is used. If you want directory filtering, use this flag on all file systems, but be sure to examine the file attribute data stored into *lpFindFileData to determine whether the function has indeed returned a handle to a directory.
If the underlying file system does not support a particular type of filtering, other than directory filtering, FindFirstFileEx fails with the error ERROR_NOT_SUPPORTED. The application has to use type FileExSearchNameMatch and perform its own filtering.

Once established, the search handle can be used in the FindNextFile function to search for other files that match the same pattern with the same filtering being performed. When the search handle is no longer needed, it should be closed using the FindClose function.

The call

FindFirstFileEx( lpFileName,

                 FindExInfoStandard,

                 lpFindData,

                 FindExSearchNameMatch,

                 NULL,

                 0 );

is equivalent to the call

FindFirstFile( lpFileName, lpFindData);

See Also

FindFirstFile, FindNextFile, FindClose, WIN32_FIND_DATA


FindFirstFreeAce

The FindFirstFreeAce function retrieves a pointer to the first free byte in an access-control list (ACL).

BOOL FindFirstFreeAce(

PACL pAcl,	// pointer to access-control list
LPVOID *pAce	// pointer to pointer to first free byte
);
Parameters

pAcl

Points to an ACL structure.

pAce

Points to a pointer to the first free position in the ACL created when the function returns. If the ACL is invalid, this parameter is NULL. If the ACL is full, this parameter points to the byte immediately following the ACL.

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.

See Also

ACL, GetAce, GetAclInformation


FindFirstPrinterChangeNotification

The FindFirstPrinterChangeNotification function creates a change notification object and returns a handle to the object. You can then use this handle in a call to one of the wait functions to monitor changes to the printer or print server.

The FindFirstPrinterChangeNotification call specifies the type of changes to be monitored. You can specify a set of conditions to monitor for changes, a set of printer information fields to monitor, or both.

A wait operation on the change notification handle succeeds when one of the specified changes occurs in the specified printer or print server. You then call the FindNextPrinterChangeNotification function to retrieve information about the change, and to reset the change notification object for use in the next wait operation.

HANDLE FindFirstPrinterChangeNotification(

HANDLE hPrinter,	// handle to printer or print server to monitor for changes
DWORD fdwFlags,	// flags that specify the conditions to monitor
DWORD fdwOptions,	// reserved, must be zero
LPVOID pPrinterNotifyOptions	// pointer to structure specifying printer information to monitor
);
Parameters

hPrinter

Handle to the printer or print server that you want to monitor. This handle is obtained by calling the OpenPrinter function.

fdwFlags

A set of bit flags that specify the conditions that will cause the change notification object to enter a signaled state. A change notification occurs when one or more of the specified conditions are met. The fdwFlags parameter can be zero if pPrinterNotifyOptions is non-NULL.

You can set one or more of the following change notification constants:

Value	Meaning
PRINTER_CHANGE_FORM
	Notify of any changes to a form. You can set this general flag or one or more of the following specific flags: PRINTER_CHANGE_ADD_FORM PRINTER_CHANGE_SET_FORM PRINTER_CHANGE_DELETE_FORM
PRINTER_CHANGE_JOB
	Notify of any changes to a job. You can set this general flag or one or more of the following specific flags: PRINTER_CHANGE_ADD_JOB PRINTER_CHANGE_SET_JOB PRINTER_CHANGE_DELETE_JOB PRINTER_CHANGE_WRITE_JOB
PRINTER_CHANGE_PORT
	Notify of any changes to a port. You can set this general flag or one or more of the following specific flags: PRINTER_CHANGE_ADD_PORT PRINTER_CHANGE_CONFIGURE_PORT PRINTER_CHANGE_DELETE_PORT
PRINTER_CHANGE_PRINT_PROCESSOR
	Notify of any changes to a print processor. You can set this general flag or one or more of the following specific flags: PRINTER_CHANGE_ADD_PRINT_PROCESSOR PRINTER_CHANGE_DELETE_PRINT_PROCESSOR
PRINTER_CHANGE_PRINTER
	Notify of any changes to a printer. You can set this general flag or one or more of the following specific flags:  PRINTER_CHANGE_ADD_PRINTER PRINTER_CHANGE_SET_PRINTER PRINTER_CHANGE_DELETE_PRINTER PRINTER_CHANGE_FAILED_CONNECTION_PRINTER
PRINTER_CHANGE_PRINTER_DRIVER
	Notify of any changes to a printer driver. You can set this general flag or one or more of the following specific flags: PRINTER_CHANGE_ADD_PRINTER_DRIVER PRINTER_CHANGE_SET_PRINTER_DRIVER PRINTER_CHANGE_DELETE_PRINTER_DRIVER
PRINTER_CHANGE_ALL
	Notify if any of the preceding changes occur.
For descriptions of the more specific flags in the preceding table, see the FindNextPrinterChangeNotification function.

fdwOptions

Reserved; must be zero.

pPrinterNotifyOptions

Pointer to a PRINTER_NOTIFY_OPTIONS structure. The pTypes member of this structure points to an array of one or more PRINTER_NOTIFY_OPTIONS_TYPE structures, each of which specifies a printer information field to monitor. A change notification occurs when one or more of the specified fields changes. When a change occurs, the FindNextPrinterChangeNotification function can retrieve the new printer information. This parameter can be NULL if fdwFlags is nonzero.

For a list of fields that can be monitored, see PRINTER_NOTIFY_OPTIONS_TYPE.

Return Values

If the function succeeds, the return value is a handle to a change notification object associated with the specified printer or print server.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

To monitor a printer or print server, call the FindFirstPrinterChangeNotification function, then use the returned change notification object handle in a call to one of the wait functions. A wait operation on a change notification object is satisfied when the change notification object enters the signaled state. The system signals the object when one or more of the changes specified by fdwFlags or pPrinterNotifyOptions occurs in the monitored printer or print server.

When you call FindFirstPrinterChangeNotification, either fdwFlags must be nonzero or pPrinterNotifyOptions must be non-NULL. If both are specified, notifications will occur for both.

When a wait operation on a printer change notification object is satisfied, call the FindNextPrinterChangeNotification function to determine the cause of the notification. For a condition specified by fdwFlags, FindNextPrinterChangeNotification reports the condition or conditions that changed. For a printer information field specified by pPrinterNotifyOptions , FindNextPrinterChangeNotification reports the field or fields that changed as well as the new information for these fields. FindNextPrinterChangeNotification also resets the change notification object to the nonsignaled state so you can use it in another wait operation to continue monitoring the printer or print server.

Do not call the FindNextPrinterChangeNotification function if the change notification object is not in the signaled state. If the wait function returns the value WAIT_TIMEOUT, the change object is not in the signaled state. Call the FindNextPrinterChangeNotification function only if the wait function succeeds without timing out.

When you no longer need the change notification object, close it by calling the FindClosePrinterChangeNotification function.

The three Find*PrinterChangeNotification functions, in combination with the wait functions, provide an asynchronous and resource-efficient alternative to the WaitForPrinterChange function.

See Also

FindClosePrinterChangeNotification, FindNextPrinterChangeNotification, OpenPrinter, PRINTER_NOTIFY_OPTIONS, PRINTER_NOTIFY_OPTIONS_TYPE, WaitForPrinterChange


FindNextChangeNotification

The FindNextChangeNotification function requests that the operating system signal a change notification handle the next time it detects an appropriate change.

BOOL FindNextChangeNotification(

HANDLE hChangeHandle	// handle to change notification to signal
);
Parameters

hChangeHandle

Identifies a change notification handle created by the FindFirstChangeNotification 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.

Remarks

After the FindNextChangeNotification function returns successfully, the application can wait for notification that a change has occurred by using the wait functions.

If a change occurs after a call to FindFirstChangeNotification but before a call to FindNextChangeNotification, the operating system records the change. When FindNextChangeNotification is executed, the recorded change immediately satisfies a wait for the change notification.

FindNextChangeNotification should not be used more than once on the same handle without using one of the wait functions. An application may miss a change notification if it uses FindNextChangeNotification when there is a change request outstanding.

When hChangeHandle is no longer needed, close it by using the FindCloseChangeNotification function.

See Also

FindCloseChangeNotification, FindFirstChangeNotification


FindNextFile

The FindNextFile function continues a file search from a previous call to the FindFirstFile function.

BOOL FindNextFile(

HANDLE hFindFile,	// handle to search
LPWIN32_FIND_DATA lpFindFileData	// pointer to structure for data on found file
);
Parameters

hFindFile

Identifies a search handle returned by a previous call to the FindFirstFile function.

lpFindFileData

Points to the WIN32_FIND_DATA structure that receives information about the found file or subdirectory. The structure can be used in subsequent calls to FindNextFile to refer to the found file or directory.

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. If no matching files can be found, the GetLastError function returns ERROR_NO_MORE_FILES.

Remarks

The FindNextFile function searches for files by name only; it cannot be used for attribute-based searches.

See Also

FindClose, FindFirstFile, GetFileAttributes, SetFileAttributes, WIN32_FIND_DATA


FindNextPrinterChangeNotification

The FindNextPrinterChangeNotification function retrieves information about the most recent change notification for a change notification object associated with a printer or print server. Call this function when a wait operation on the change notification object is satisfied.

The function also resets the change notification object to the not-signaled state. You can then use the object in another wait operation to continue monitoring the printer or print server. The operating system will set the object to the signaled state the next time one of a specified set of changes occurs to the printer or print server. The FindFirstPrinterChangeNotification function creates the change notification object and specifies the set of changes to be monitored.

BOOL FindNextPrinterChangeNotification(

HANDLE hChange,	// handle to change notification object of interest
PDWORD pdwChange,	// pointer to a value that indicates the condition that changed
LPVOID pPrinterNotifyOptions,	// pointer to a structure that specifies a refresh flag
LPVOID *ppPrinterNotifyInfo	// pointer to a pointer that receives printer information buffer
);
Parameters

hChange

Handle to a change notification object associated with a printer or print server. You obtain such a handle by calling the FindFirstPrinterChangeNotification function. The operating system sets this change notification object to the signaled state when it detects one of the changes specified in the object’s change notification filter.

pdwChange

Pointer to a doubleword variable whose bits are set to indicate the changes that occurred to cause the most recent notification. The bit flags that might be set correspond to those specified in the fdwFlags parameter of the FindFirstPrinterChangeNotification call. The system sets one or more of the following bit flags:

Value	Meaning
PRINTER_CHANGE_ADD_FORM
	A form was added to the server.
PRINTER_CHANGE_ADD_JOB
	A print job was sent to the printer.
PRINTER_CHANGE_ADD_PORT
	A port or monitor was added to the server.
PRINTER_CHANGE_ADD_PRINT_PROCESSOR
	A print processor was added to the server.
PRINTER_CHANGE_ADD_PRINTER
	A printer was added to the server.
PRINTER_CHANGE_ADD_PRINTER_DRIVER
	A printer driver was added to the server.
PRINTER_CHANGE_CONFIGURE_PORT
	A port was configured on the server.
PRINTER_CHANGE_DELETE_FORM
	A form was deleted from the server.
PRINTER_CHANGE_DELETE_JOB
	A job was deleted.
PRINTER_CHANGE_DELETE_PORT
	A port or monitor was deleted from the server.
PRINTER_CHANGE_DELETE_PRINT_PROCESSOR
	A print processor was deleted from the server.
PRINTER_CHANGE_DELETE_PRINTER
	A printer was deleted.
PRINTER_CHANGE_DELETE_PRINTER_DRIVER
	A printer driver was deleted from the server.
PRINTER_CHANGE_FAILED_CONNECTION_PRINTER
	A printer connection has failed.
PRINTER_CHANGE_SET_FORM
	A form was set on the server.
PRINTER_CHANGE_SET_JOB
	A job was set.
PRINTER_CHANGE_SET_PRINTER
	A printer was set.
PRINTER_CHANGE_SET_PRINTER_DRIVER
	A printer driver was set.
PRINTER_CHANGE_WRITE_JOB
	Job data was written.
pPrinterNotifyOptions

Pointer to a PRINTER_NOTIFY_OPTIONS structure. Set the Flags member of this structure to PRINTER_NOTIFY_OPTIONS_REFRESH, to cause the function to return the current data for all monitored printer information fields. The function ignores all other members of the structure. This parameter can be NULL.

ppPrinterNotifyInfo

Pointer to a pointer variable that receives the address of a system-allocated, read-only buffer. Call the FreePrinterNotifyInfo function to free the buffer when you are finished with it. This parameter can be NULL if no information is required.

The buffer contains a PRINTER_NOTIFY_INFO structure, which contains an array of PRINTER_NOTIFY_INFO_DATA structures. Each element of the array contains information about one of the fields specified in the pPrinterNotifyOptions parameter of the FindFirstPrinterChangeNotification call. Typically, the function provides data only for the fields that changed to cause the most recent notification. However, if the structure pointed to by the pPrinterNotifyOptions parameter specifies PRINTER_NOTIFY_OPTIONS_REFRESH, the function provides data for all monitored fields.

If the PRINTER_NOTIFY_INFO_DISCARDED bit is set in the Flags member of the PRINTER_NOTIFY_INFO structure, an overflow or error occurred, and notifications may have been lost. In this case, no additional notifications will be sent until you make a second FindNextPrinterChangeNotification call that specifies PRINTER_NOTIFY_OPTIONS_REFRESH.

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.

Remarks

Call the FindNextPrinterChangeNotification function after a wait operation on a notification object created by FindFirstPrinterChangeNotification has been satisfied. Calling FindNextPrinterChangeNotification lets you obtain information about the change that satisfied the wait operation, and resets the notification object so it can be signaled when the next change occurs.

Do not call the FindNextPrinterChangeNotification function if the change notification object is not in the signaled state. If a wait function returns the value WAIT_TIMEOUT, the change object is not in the signaled state. Call the FindNextPrinterChangeNotification function only if the wait function succeeds without timing out.

To continue monitoring the printer or print server for changes, repeat the cycle of calling one of the wait functions, and then calling the FindNextPrinterChangeNotification function to examine the change and reset the notification object.

FindNextPrinterChangeNotification may combine multiple changes to the same printer information field into a single notification. When this occurs, the function typically collapses all changes for the field into a single entry in the array of PRINTER_NOTIFY_INFO_DATA structures in ppPrinterNotifyInfo; the single entry reports only the most current information. However, for some job and printer information fields, the function can return multiple array entries for the same field. In this case, the last array entry for the field reports the current data, and the earlier entries contain the data for the intermediate stages.

When you no longer need the change notification object, close it by calling the FindClosePrinterChangeNotification function.

The three Find*PrinterChangeNotification functions, in combination with the wait functions, provide an asynchronous, more resource-efficient alternative to the WaitForPrinterChange function.

See Also

FindClosePrinterChangeNotification, FindFirstPrinterChangeNotification, PRINTER_NOTIFY_INFO, PRINTER_NOTIFY_INFO_DATA, PRINTER_NOTIFY_OPTIONS, WaitForPrinterChange


FindResource

The FindResource function determines the location of a resource with the specified type and name in the specified module.

HRSRC FindResource(

HMODULE hModule,	// resource-module handle
LPCTSTR lpName,	// pointer to resource name
LPCTSTR lpType	// pointer to resource type
);
Parameters

hModule

A handle to the module whose executable file contains the resource.

A value of NULL specifies the module handle associated with the image file that the operating system used to create the current process.

lpName

Specifies the name of the resource. For more information, see the Remarks section.

lpType

Specifies the resource type. For more information, see the Remarks section. For standard resource types, this parameter can be one of the following values:

Value	Meaning
RT_ACCELERATOR	Accelerator table
RT_ANICURSOR	Animated cursor
RT_ANIICON	Animated icon
RT_BITMAP	Bitmap resource
RT_CURSOR	Hardware-dependent cursor resource
RT_DIALOG	Dialog box
RT_FONT	Font resource
RT_FONTDIR	Font directory resource
RT_GROUP_CURSOR	Hardware-independent cursor resource
RT_GROUP_ICON	Hardware-independent icon resource
RT_ICON	Hardware-dependent icon resource
RT_MENU	Menu resource
RT_MESSAGETABLE	Message-table entry
RT_RCDATA	Application-defined resource (raw data)
RT_STRING	String-table entry
RT_VERSION	Version resource
Return Values

If the function succeeds, the return value is a handle to the specified resource’s info block. To obtain a handle to the resource, pass this handle to the LoadResource function.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If the high-order word of the lpName or lpType parameter is zero, the low-order word specifies the integer identifier of the name or type of the given resource. Otherwise, those parameters are long pointers to null-terminated strings. If the first character of the string is a pound sign (#), the remaining characters represent a decimal number that specifies the integer identifier of the resource’s name or type. For example, the string “#258” represents the integer identifier 258.

An application should reduce the amount of memory required for the resources by referring to them by integer identifier instead of by name.

An application can use FindResource to find any type of resource, but this function should be used only if the application must access the binary resource data when making subsequent calls to LoadLibrary and LockResource.

To use a resource immediately, an application should use one of the following resource-specific functions to find and load the resources in one call:

Function	Action
FormatMessage	Loads and formats a message-table entry.
LoadAccelerators	Loads an accelerator table.
LoadBitmap	Loads a bitmap resource.
LoadCursor	Loads a cursor resource.
LoadIcon	Loads an icon resource.
LoadMenu	Loads a menu resource.
LoadString	Loads a string-table entry.
For example, an application can use the LoadIcon function to load an icon for display on the screen. However, the application should use FindResource and LoadResource if it is loading the icon to copy its data to another application.

See Also

FindResourceEx, FormatMessage, LoadAccelerators, LoadBitmap, LoadCursor, LoadIcon, LoadMenu, LoadResource, LoadString, LockResource, SizeofResource


FindResourceEx

The FindResourceEx function determines the location of the resource with the specified type, name, and language in the specified module.

HRSRC FindResourceEx(

HMODULE hModule,	// resource-module handle
LPCTSTR lpType,	// pointer to resource type
LPCTSTR lpName,	// pointer to resource name
WORD wLanguage	// resource language
);
Parameters

hModule

Identifies the module whose executable file contains the resource. If this parameter is NULL, the function searches the module used to create the current process.

lpType

Points to a null-terminated string specifying the type name of the resource. For more information, see the Remarks section. For standard resource types, this parameter can be one of the following values:

Value	Meaning
RT_ACCELERATOR	Accelerator table
RT_ANICURSOR	Animated cursor
RT_ANIICON	Animated icon
RT_BITMAP	Bitmap resource
RT_CURSOR	Hardware-dependent cursor resource
RT_DIALOG	Dialog box
RT_FONT	Font resource
RT_FONTDIR	Font directory resource
RT_GROUP_CURSOR	Hardware-independent cursor resource
RT_GROUP_ICON	Hardware-independent icon resource
RT_ICON	Hardware-dependent icon resource
RT_MENU	Menu resource
RT_MESSAGETABLE	Message-table entry
RT_RCDATA	Application-defined resource (raw data)
RT_STRING	String-table entry
RT_VERSION	Version resource
lpName

Points to a null-terminated string specifying the name of the resource. For more information, see the Remarks section.

wLanguage

Specifies the language of the resource. If this parameter is MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL), the current language associated with the calling thread is used.

To specify a language other than the current language, use the MAKELANGID macro to create this parameter. For more information, see the MAKELANGID macro.

Return Values

If the function succeeds, the return value is a handle to the specified resource’s info block. To obtain a handle to the resource, pass this handle to the LoadResource function.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If the high-word of the lpType or lpName parameter is zero, the low-word specifies the integer identifier of the type or name of the given resource. Otherwise, those parameters are pointers to null-terminated strings. If the first character of the string is a pound sign (#), the remaining characters represent a decimal number that specifies the integer identifier of the resource’s name or type. For example, the string “#258” represents the integer identifier 258.

Applications should reduce the amount of memory required for the resources by referring to them by integer identifier instead of by name.

An application can use FindResource to find any type of resource, but this function should be used only if the application must access the binary resource data when making subsequent calls to the LoadLibrary and LockResource functions.

To use a resource immediately, an application should use the following resource-specific functions to find and load the resources in one call:

Function	Action
FormatMessage	Loads and formats a message-table entry.
LoadAccelerators	Loads an accelerator table.
LoadBitmap	Loads a bitmap resource.
LoadCursor	Loads a cursor resource.
LoadIcon	Loads an icon resource.
LoadMenu	Loads a menu resource.
LoadString	Loads a string-table entry.
For example, an application can use the LoadIcon function to load an icon for display on the screen. However, the application should use FindResource and LoadResource if it is loading the icon to copy its data to another application.

See Also

FindResource, FormatMessage, LoadAccelerators, LoadBitmap, LoadCursor, LoadIcon, LoadMenu, LoadString, LoadResource, MAKELANGID


FindText

The FindText function creates a system-defined modeless dialog box that lets the user specify a string to search for and options to use when searching for text in a document.

HWND FindText(

LPFINDREPLACE lpfr	// pointer to structure with initialization data
);
Parameters

lpfr

Pointer to a FINDREPLACE structure that contains information used to initialize the dialog box. The dialog box uses this structure to send information about the user’s input to your application. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is the window handle to the dialog box. You can use the window handle to communicate with or to close the dialog box.

If the function fails, the return value is NULL. To get extended error information, call the CommDlgExtendedError function. CommDlgExtendedError may return one of the following error codes:

CDERR_FINDRESFAILURE	CDERR_MEMLOCKFAILURE
CDERR_INITIALIZATION	CDERR_NOHINSTANCE
CDERR_LOCKRESFAILURE	CDERR_NOHOOK
CDERR_LOADRESFAILURE	CDERR_NOTEMPLATE
CDERR_LOADSTRFAILURE	CDERR_STRUCTSIZE
CDERR_MEMALLOCFAILURE	FRERR_BUFFERLENGTHZERO
Remarks

The FindText function does not perform a search operation. Instead, the dialog box sends FINDMSGSTRING registered messages to the window procedure of the owner window of the dialog box. When you create the dialog box, the hwndOwner member of the FINDREPLACE structure identifies the owner window.

Before calling FindText, you must call the RegisterWindowMessage function to get the identifier for the FINDMSGSTRING message. The dialog box procedure uses this identifier to send messages when the user clicks the Find Next button, or when the dialog box is closing. The lParam parameter of the FINDMSGSTRING message contains a pointer to a FINDREPLACE structure. The Flags member of this structure indicates the event that caused the message. Other members of the structure indicate the user’s input.

If you create a Find dialog box, you must also use the IsDialogMessage function in the main message loop of your application to ensure that the dialog box correctly processes keyboard input, such as the TAB and ESC keys. IsDialogMessage returns a value that indicates whether the Find dialog box processed the message.

You can provide an FRHookProc hook procedure for a Find dialog box. The hook procedure can process messages sent to the dialog box. To enable a hook procedure, set the FR_ENABLEHOOK flag in the Flags member of the FINDREPLACE structure and specify the address of the hook procedure in the lpfnHook member.

See Also

CommDlgExtendedError, FINDMSGSTRING, FINDREPLACE, FRHookProc, IsDialogMessage, RegisterWindowMessage, ReplaceText


FindWindow

The FindWindow function retrieves the handle to the top-level window whose class name and window name match the specified strings. This function does not search child windows.

HWND FindWindow(

LPCTSTR lpClassName,	// pointer to class name
LPCTSTR lpWindowName	// pointer to window name
);
Parameters

lpClassName

Points to a null-terminated string that specifies the class name or is an atom that identifies the class-name string. If this parameter is an atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value, must be placed in the low-order word of lpClassName; the high-order word must be zero.

lpWindowName

Points to a null-terminated string that specifies the window name (the window’s title). If this parameter is NULL, all window names match.

Return Values

If the function succeeds, the return value is the handle to the window that has the specified class name and window name.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

EnumWindows, FindWindowEx, GetClassName, GlobalAddAtom


FindWindowEx [Now Supported on Windows NT]
FindWindowEx

[Now Supported on Windows NT]

The FindWindowEx function retrieves the handle to a window whose class name and window name match the specified strings. The function searches child windows, beginning with the one following the given child window.

HWND FindWindowEx(

HWND hwndParent,	// handle to parent window
HWND hwndChildAfter,	// handle to a child window
LPCTSTR lpszClass,	// pointer to class name
LPCTSTR lpszWindow	// pointer to window name
);
Parameters

hwndParent

Identifies the parent window whose child windows are to be searched.

If hwndParent is NULL, the function uses the desktop window as the parent window. The function searches among windows that are child windows of the desktop.

hwndChildAfter

Identifies a child window. The search begins with the next child window in the Z order. hwndChildAfter must be a direct child window of hwndParent, not just a descendant window.

If hwndChildAfter is NULL, the search begins with the first child window of hwndParent.

Note that if both hwndParent and hwndChildAfter are NULL, the function searches all top-level windows.

lpszClass

Points to a null-terminated string that specifies the class name or is an atom that identifies the class-name string. If this parameter is an atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value, must be placed in the low-order word of lpszClass; the high-order word must be zero.

lpszWindow

Points to a null-terminated string that specifies the window name (the window’s title). If this parameter is NULL, all window names match.

Return Values

If the function succeeds, the return value is the handle to the window that has the specified class and window names.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

EnumWindows, FindWindow, GetClassName, GlobalAddAtom


FixBrushOrgEx

The FixBrushOrgEx function is not implemented in the Win32 API. It is provided for compatibility with Win32s. If called, the function does nothing, and returns FALSE.

See Also

GetBrushOrgEx, SetBrushOrgEx


FlashWindow

The FlashWindow function flashes the specified window once.

BOOL FlashWindow(

HWND hWnd,	// handle to window to flash
BOOL bInvert	// flash status
);
Parameters

hWnd

Identifies the window to be flashed. The window can be either open or minimized (iconic).

bInvert

Specifies whether the window is to be flashed or returned to its original state. The window is flashed from one state to the other if this parameter is TRUE. If it is FALSE, the window is returned to its original state (either active or inactive). When an application is iconic, if this parameter is TRUE, the taskbar window button flashes active/inactive. If it is FALSE, the taskbar window button flashes inactive, meaning that it does not change colors. It flashes, as if it were being redraw, but it does not provide the visual invert clue to the user.

Return Values

The return value specifies the window’s state before the call to the FlashWindow function. If the window was active before the call, the return value is nonzero.

If the window was not active before the call, the return value is zero.

Remarks

Flashing a window means changing the appearance of its caption bar as if the window were changing from inactive to active status, or vice versa. (An inactive caption bar changes to an active caption bar; an active caption bar changes to an inactive caption bar.)

Typically, a window is flashed to inform the user that the window requires attention but that it does not currently have the keyboard focus.

The FlashWindow function flashes the window only once; for repeated flashing, the application should create a system timer.


FlattenPath

The FlattenPath function transforms any curves in the path that is selected into the current device context (DC), turning each curve into a sequence of lines.

BOOL FlattenPath(

HDC hdc	// handle to device context
);
Parameters

hdc

Identifies a DC that contains a valid path.

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 one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY

See Also

WidenPath


FloodFill

The FloodFill function fills an area of the display surface with the current brush. The area is assumed to be bounded as specified by the crFill parameter.

The FloodFill function is included only for compatibility with earlier versions of Windows. For Win32-based applications, use the ExtFloodFill function with FLOODFILLBORDER specified.

BOOL FloodFill(

HDC hdc,	// handle to device context
int nXStart,	// x-coordinate, where fill begins
int nYStart,	// y-coordinate, where fill begins
COLORREF crFill	// fill color
);
Parameters

hdc

Identifies a device context.

nXStart

Specifies the logical x-coordinate of the point where filling is to begin.

nYStart

Specifies the logical y-coordinate of the point where filling is to begin.

crFill

Specifies the color of the boundary or of the area to be filled.

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.

Remarks

Following are reasons this function might fail:

•	The fill could not be completed.

•	The given point has the boundary color specified by the crFill parameter.

•	The given point lies outside the current clipping region — that is, it is not visible on the device.

See Also

ExtFloodFill


FlushConsoleInputBuffer

The FlushConsoleInputBuffer function flushes the console input buffer. All input records currently in the input buffer are discarded.

BOOL FlushConsoleInputBuffer(

HANDLE hConsoleInput	// handle to console input buffer
);
Parameters

hConsoleInput

Identifies the console input buffer. The handle must have GENERIC_WRITE access.

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.

See Also

GetNumberOfConsoleInputEvents, PeekConsoleInput, ReadConsoleInput, WriteConsoleInput


FlushFileBuffers

The FlushFileBuffers function clears the buffers for the specified file and causes all buffered data to be written to the file.

BOOL FlushFileBuffers(

HANDLE hFile	// open handle to file whose buffers are to be flushed
);
Parameters

hFile

An open file handle. The function flushes this file’s buffers. The file handle must have GENERIC_WRITE access to the file.

If hFile is a handle to a communications device, the function only flushes the transmit buffer.

If hFile is a handle to the server end of a named pipe, the function does not return until the client has read all buffered data from the pipe.

Windows NT: The function fails if hFile is a handle to console output. That is because console output is not buffered. The function returns FALSE, and GetLastError returns ERROR_INVALID_HANDLE.

Windows 95: The function does nothing if hFile is a handle to console output. That is because console output is not buffered. The function returns TRUE, but it does nothing.

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.

Remarks

The WriteFile and WriteFileEx functions typically write data to an internal buffer that the operating system writes to disk on a regular basis. The FlushFileBuffers function writes all of the buffered information for the specified file to disk.

You can pass the same file handle used with the _lread, _lwrite, _lcreat, and related functions to FlushFileBuffers.

See Also

_lread, _lwrite, _lcreat, WriteFile, WriteFileEx


FlushInstructionCache

The FlushInstructionCache function flushes the instruction cache for the specified process.

BOOL FlushInstructionCache(

HANDLE hProcess,	// handle to process with cache to flush
LPCVOID lpBaseAddress,	// pointer to region to flush
DWORD dwSize	// length of region to flush
);
Parameters

hProcess

Identifies the process that has an instruction cache to flush.

lpBaseAddress

Points to the base of the region to be flushed. This parameter can be NULL.

dwSize

Specifies the length of the region to be flushed if the lpBaseAddress parameter is not NULL.

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.

Windows 95: The FlushInstructionCache function always returns TRUE. windows 95 supports single-processor machines only.


FlushViewOfFile

The FlushViewOfFile function writes to the disk a byte range within a mapped view of a file.

BOOL FlushViewOfFile(

LPCVOID lpBaseAddress,	// start address of byte range to flush
DWORD dwNumberOfBytesToFlush	// number of bytes in range
);
Parameters

lpBaseAddress

Points to the base address of the byte range to be flushed to the disk representation of the mapped file.

dwNumberOfBytesToFlush

Specifies the number of bytes to flush.

If dwNumberOfBytesToFlush is zero, the file is flushed from the base address to the end of the mapping.

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.

Remarks

Flushing a range of a mapped view causes any dirty pages within that range to be written to the disk. Dirty pages are those whose contents have changed since the file view was mapped.

See Also

MapViewOfFile, UnmapViewOfFile


FMExtensionProc

The FMExtensionProc function is an application-defined callback function that processes menu commands and messages sent to a File Manager extension dynamic-link library (DLL).

LONG WINAPI FMExtensionProc(

HWND hwnd,	// handle to extension window
WORD wEvent,	// menu-item identifier, or message
LONG lParam	// additional message information
);
Parameters

hwnd

Identifies the File Manager window. An extension DLL should use this handle to specify the owner for any dialog box or message box that the DLL may display and to send request messages to File Manager.

wEvent

Specifies the message. This parameter can be one of the following values:

Value	Meaning
1−99	The user selected the menu item identified by this number.
FMEVENT_INITMENU	User selected the extension’s menu.
FMEVENT_LOAD	File Manager is loading the extension DLL.
FMEVENT_SELCHANGE	Selection changed in File Manager’s directory window or in Search Results window.
FMEVENT_UNLOAD	File Manager is unloading the extension DLL.
FMEVENT_USER_REFRESH	User chose the Refresh command from the Window menu.
lParam

Specifies 32 bits of additional message-specific information.

Return Values

The callback function should return the result of the message processing. The actual return value depends on the message processed.

Remarks

Whenever File Manager calls the FMExtensionProc function, it waits to refresh its directory windows (for changes in the file system) until after the function returns. This allows the extension to perform large numbers of file operations without excessive repainting by File Manager. It is not necessary for the extension to send the FM_REFRESH_WINDOWS message to notify File Manager to repaint its windows.


FoldString

The FoldString function maps one string to another, performing a specified transformation option.

int FoldString(

DWORD dwMapFlags,	// mapping transformation options
LPCTSTR lpSrcStr,	// pointer to source string
int cchSrc,	// size of source string, in bytes or characters
LPTSTR lpDestStr,	// pointer to destination buffer
int cchDest	// size of destination buffer, in bytes or characters
);
Parameters

dwMapFlags

A set of bit flags that indicate the type of transformation to be used during mapping. This value can be a combination of the following bit-flag constants:

Option	Meaning
MAP_FOLDCZONE	Fold compatibility zone characters into standard Unicode equivalents. For information about compatibility zone characters, see the following Remarks section.
MAP_FOLDDIGITS	Map all digits to Unicode characters 0 through 9.
MAP_PRECOMPOSED	Map accented characters to precomposed characters, in which the accent and base character are combined into a single character value. This value cannot be combined with MAP_COMPOSITE.
MAP_COMPOSITE	Map accented characters to composite characters, in which the accent and base character are represented by two character values. This value cannot be combined with MAP_PRECOMPOSED.
lpSrcStr

Points to the string to be mapped.

cchSrc

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the lpSrcStr buffer. If cchSrc is −1, lpSrcStr is assumed to be null-terminated, and the length is calculated automatically.

lpDestStr

Points to the buffer to store the mapped string.

cchDest

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the lpDestStr buffer. If cchDest is zero, the function returns the number of bytes or characters required to hold the mapped string, and the buffer pointed to by lpDestStr is not used.

Return Values

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) written to the destination buffer, or if the cchDest parameter is zero, the number of bytes or characters required to hold the mapped string.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER

Remarks

The mapped string is null-terminated if the source string is null-terminated.

The lpSrcStr and lpDestStr pointers must not be the same. If they are the same, the function fails and GetLastError returns ERROR_INVALID_PARAMETER.

The compatibility zone in Unicode consists of characters in the range 0xF900 through 0xFFEF that are assigned to characters from other character-encoding standards but are actually variants of characters that are already in Unicode. The compatibility zone is used to support round-trip mapping to these standards. Applications can use the MAP_FOLDCZONE flag to avoid supporting the duplication of characters in the compatibility zone.

See Also

LCMapString, CompareString


ForegroundIdleProc

The ForegroundIdleProc hook procedure is an application-defined callback function the system calls whenever the 32-bit foreground thread is about to become idle.

DWORD ForegroundIdleProc(

int code,	// hook code
DWORD wParam,	// not used
LONG lParam	// not used
);
Parameters

code

Specifies whether the hook procedure must process the message. If code is HC_ACTION, the hook procedure must process the message. If code is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Not used.

lParam

Not used.

Remarks

An application installs this hook procedure by specifying the WH_FOREGROUNDIDLE hook type and the pointer to the hook procedure in a call to the SetWindowsHookEx function.

ForegroundIdleProc is a placeholder for the application-defined function name.

This is a thread-specific hook.

See Also

CallNextHookEx, SetWindowsHookEx


FormatMessage

The FormatMessage function formats a message string. The function requires a message definition as input. The message definition can come from a buffer passed into the function. It can come from a message table resource in an already-loaded module. Or the caller can ask the function to search the system’s message table resource(s) for the message definition. The function finds the message definition in a message table resource based on a message identifier and a language identifier. The function copies the formatted message text to an output buffer, processing any embedded insert sequences if requested.

DWORD FormatMessage(

DWORD dwFlags,	// source and processing options
LPCVOID lpSource,	// pointer to  message source
DWORD dwMessageId,	// requested message identifier
DWORD dwLanguageId,	// language identifier for requested message
LPTSTR lpBuffer,	// pointer to message buffer
DWORD nSize,	// maximum size of message buffer
va_list *Arguments	// address of array of message inserts
);
Parameters

dwFlags

Contains a set of bit flags that specify aspects of the formatting process and how to interpret the lpSource parameter. The low-order byte of dwFlags specifies how the function handles line breaks in the output buffer. The low-order byte can also specify the maximum width of a formatted output line.

You can specify a combination of the following bit flags:

Value	Meaning
FORMAT_MESSAGE_ALLOCATE_BUFFER
	Specifies that the lpBuffer parameter is a pointer to a PVOID pointer, and that the nSize parameter specifies the minimum number of bytes (ANSI version) or characters (Unicode version) to allocate for an output message buffer. The function allocates a buffer large enough to hold the formatted message, and places a pointer to the allocated buffer at the address specified by lpBuffer. The caller should use the LocalFree function to free the buffer when it is no longer needed.
FORMAT_MESSAGE_IGNORE_INSERTS
	Specifies that insert sequences in the message definition are to be ignored and passed through to the output buffer unchanged. This flag is useful for fetching a message for later formatting. If this flag is set, the Arguments parameter is ignored.
FORMAT_MESSAGE_FROM_STRING
	Specifies that lpSource is a pointer to a null-terminated message definition. The message definition may contain insert sequences, just as the message text in a message table resource may. Cannot be used with FORMAT_MESSAGE_FROM_HMODULE or FORMAT_MESSAGE_FROM_SYSTEM.
FORMAT_MESSAGE_FROM_HMODULE
	Specifies that lpSource is a module handle containing the message-table resource(s) to search. If this lpSource handle is NULL, the current process’s application image file will be searched. Cannot be used with FORMAT_MESSAGE_FROM_STRING.
FORMAT_MESSAGE_FROM_SYSTEM
	Specifies that the function should search the system message-table resource(s) for the requested message. If this flag is specified with FORMAT_MESSAGE_FROM_HMODULE, the function searches the system message table if the message is not found in the module specified by lpSource. Cannot be used with FORMAT_MESSAGE_FROM_STRING. If this flag is specified, an application can pass the result of the GetLastError function to retrieve the message text for a system-defined error.
FORMAT_MESSAGE_ARGUMENT_ARRAY
	Specifies that the Arguments parameter is not a va_list structure, but instead is just a pointer to an array of 32-bit values that represent the arguments.
The low-order byte of dwFlags can specify the maximum width of a formatted output line. Use the FORMAT_MESSAGE_MAX_WIDTH_MASK constant and bitwise Boolean operations to set and retrieve this maximum width value.

The following table shows how FormatMessage interprets the value of the low-order byte.

Value	Meaning
0	There are no output line width restrictions. The function stores line breaks that are in the message definition text into the output buffer.
A nonzero value other than FORMAT_MESSAGE_MAX_WIDTH_MASK	The nonzero value is the maximum number of characters in an output line. The function ignores regular line breaks in the message definition text. The function never splits a string delimited by white space across a line break. The function stores hard-coded line breaks in the message definition text into the output buffer. Hard-coded line breaks are coded with the %n escape sequence.
FORMAT_MESSAGE_MAX_WIDTH_MASK	The function ignores regular line breaks in the message definition text. The function stores hard-coded line breaks in the message definition text into the output buffer. The function generates no new line breaks.
lpSource

Specifies the location of the message definition. The type of this parameter depends upon the settings in the dwFlags parameter.

dwFlags Setting	Parameter Type
FORMAT_MESSAGE_FROM_HMODULE	lpSource is an hModule of the module that contains the message table to search.
FORMAT_MESSAGE_FROM_STRING	lpSource is an LPTSTR that points to unformatted message text. It will be scanned for inserts and formatted accordingly.
If neither of these flags is set in dwFlags, then lpSource is ignored.

dwMessageId

Specifies the 32-bit message identifier for the requested message. This parameter is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING.

dwLanguageId

Specifies the 32-bit language identifier for the requested message. This parameter is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING.

If you pass a specific LANGID in this parameter, FormatMessage will return a message for that LANGID only. If the function cannot find a message for that LANGID, it returns ERROR_RESOURCE_LANG_NOT_FOUND. If you pass in zero, FormatMessage looks for a message for LANGIDs in the following order:

1.	Language neutral

2.	Thread LANGID, based on the thread's locale value

3.	User default LANGID, based on the user's default locale value

4.	System default LANGID, based on the system default locale value

5.	US English

If FormatMessage doesn't find a message for any of the above LANGIDs, it returns any language message string that is present. If even that fails, it returns ERROR_RESOURCE_LANG_NOT_FOUND.

lpBuffer

Points to a buffer for the formatted (and null-terminated) message. If dwFlags includes FORMAT_MESSAGE_ALLOCATE_BUFFER, the function allocates a buffer using the LocalAlloc function, and places the address of the buffer at the address specified in lpBuffer.

nSize

If the FORMAT_MESSAGE_ALLOCATE_BUFFER flag is not set, this parameter specifies the maximum number of bytes (ANSI version) or characters (Unicode version) that can be stored in the output buffer. If FORMAT_MESSAGE_ALLOCATE_BUFFER is set, this parameter specifies the minimum number of bytes or characters to allocate for an output buffer.

Arguments

Points to an array of 32-bit values that are used as insert values in the formatted message. %1 in the format string indicates the first value in the Arguments array; %2 indicates the second argument; and so on.

The interpretation of each 32-bit value depends on the formatting information associated with the insert in the message definition. The default is to treat each value as a pointer to a null-terminated string.

By default, the Arguments parameter is of type va_list*, which is a language- and implementation-specific data type for describing a variable number of arguments. If you do not have a pointer of type va_list*, then specify the FORMAT_MESSAGE_ARGUMENT_ARRAY flag and pass a pointer to an array of 32-bit values; those values are input to the message formatted as the insert values. Each insert must have a corresponding element in the array.

Return Values

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) stored in the output buffer, excluding the terminating null character.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The FormatMessage function can be used to obtain error message strings for the system error codes returned by GetLastError, as shown in the following sample code.

LPVOID lpMsgBuf;

FormatMessage(

    FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM,

    NULL,

    GetLastError(),

    MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // Default language

    (LPTSTR) &lpMsgBuf,

    0,

    NULL

);

// Display the string.

MessageBox( NULL, lpMsgBuf, "GetLastError", MB_OK|MB_ICONINFORMATION );

// Free the buffer.

LocalFree( lpMsgBuf );

Within the message text, several escape sequences are supported for dynamically formatting the message. These escape sequences and their meanings are shown in the following table. All escape sequences start with the percent character (%).

Escape Sequence	Meaning
%0	Terminates a message text line without a trailing newline character. This escape sequence can be used to build up long lines or to terminate the message itself without a trailing newline character. It is useful for prompt messages.
%n!printf format string!	Identifies an insert. The value of n can be in the range 1 through 99. The printf format string (which must be bracketed by exclamation marks) is optional and defaults to !s! if not specified.
	The printf format string can contain the * specifier for either the precision or the width component. If * is specified for one component, the FormatMessage function uses insert %n+1; it uses %n+2 if * is specified for both components.
	Floating-point printf format specifiers  —  e, E, f, and g  —  are not supported. The workaround is to to use the sprintf function to format the floating-point number into a temporary buffer, then use that buffer as the insert string.
Any other nondigit character following a percent character is formatted in the output message without the percent character. Following are some examples:

Format string	Resulting output
%%	A single percent sign in the formatted message text.
%n	A hard line break when the format string occurs at the end of a line. This format string is useful when FormatMessage is supplying regular line breaks so the message fits in a certain width.
%space	A space in the formatted message text. This format string can be used to ensure the appropriate number of trailing spaces in a message text line.
%.	A single period in the formatted message text. This format string can be used to include a single period at the beginning of a line without terminating the message text definition.
%!	A single exclamation point in the formatted message text. This format string can be used to include an exclamation point immediately after an insert without its being mistaken for the beginning of a printf format string.
See Also

LoadString, LocalFree


FrameRect

The FrameRect function draws a border around the specified rectangle by using the specified brush. The width and height of the border are always one logical unit.

int FrameRect(

HDC hDC,	// handle to device context
CONST RECT *lprc,	// pointer to rectangle coordinates
HBRUSH hbr	// handle to brush
);
Parameters

hDC

Identifies the device context in which the border is drawn.

lprc

Points to a RECT structure that contains the logical coordinates of the upper-left and lower-right corners of the rectangle.

hbr

Identifies the brush used to draw the border.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The brush identified by the hbr parameter must have been created by using the CreateHatchBrush, CreatePatternBrush, or CreateSolidBrush function, or retrieved by using the GetStockObject function.

If the bottom member of the RECT structure is less than or equal to the top member, or if the right member is less than or equal to the left member, the function does not draw the rectangle.

See Also

CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, GetStockObject, RECT


FrameRgn

The FrameRgn function draws a border around the specified region by using the specified brush.

BOOL FrameRgn(

HDC hdc,	// handle to device context
HRGN hrgn,	// handle to region to be framed
HBRUSH hbr,	// handle to brush used to draw border
int nWidth,	// width of region frame
int nHeight	// height of region frame
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies the region to be enclosed in a border. The region’s coordinates are presumed to be in logical units.

hbr

Identifies the brush to be used to draw the border.

nWidth

Specifies the width, in logical units, of vertical brush strokes.

nHeight

Specifies the height, in logical units, of horizontal brush strokes.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

FillRgn, PaintRgn


FreeConsole

The FreeConsole function detaches the calling process from its console.

BOOL FreeConsole(VOID)

Parameters

This function has no parameters.

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.

Remarks

If other processes share the console, the console is not destroyed, but the calling process cannot refer to it.

A process can use FreeConsole to detach itself from its current console, and then it can call the AllocConsole function to create a new console.

See Also

AllocConsole


FreeDDElParam

The FreeDDElParam function frees the memory specified by the lParam parameter of a posted DDE message. An application receiving a posted DDE message should call this function after it has used the UnpackDDElParam function to unpack the lParam value.

BOOL FreeDDElParam(

UINT msg,	// posted DDE message
LONG lParam	// lParam of message
);
Parameters

msg

Specifies the posted DDE message.

lParam

Specifies the lParam parameter of the posted DDE message.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

An application should call this function only for posted DDE messages.

This function frees the memory specified by the lParam parameter. It does not free the contents of lParam.

See Also

PackDDElParam, ReuseDDElParam, UnpackDDElParam


FreeEnvironmentStrings

The FreeEnvironmentStrings function frees a block of environment strings.

BOOL FreeEnvironmentStrings(

LPTSTR lpszEnvironmentBlock	// pointer to a block of environment strings
);
Parameters

lpszEnvironmentBlock

Pointer to a block of environment strings. The pointer to the block must be obtained by calling the GetEnvironmentStrings 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.

Remarks

When GetEnvironmentStrings is called, it allocates memory for a block of environment strings. When the block is no longer needed, it should be freed by calling FreeEnvironmentStrings.

See Also

GetEnvironmentStrings


FreeLibrary

The FreeLibrary function decrements the reference count of the loaded dynamic-link library (DLL) module. When the reference count reaches zero, the module is unmapped from the address space of the calling process and the handle is no longer valid. This function supersedes the FreeModule function.

BOOL FreeLibrary(

HMODULE hLibModule	// handle to loaded library module
);
Parameters

hLibModule

Identifies the loaded library module. The LoadLibrary or GetModuleHandle function returns this handle.

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.

Remarks

Each process maintains a reference count for each loaded library module. This reference count is incremented each time LoadLibrary is called and is decremented each time FreeLibrary is called. A DLL module loaded at process initialization due to load-time dynamic linking has a reference count of one. This count is incremented if the same module is loaded by a call to LoadLibrary.

Before unmapping a library module, the system enables the DLL to detach from the process by calling the DLL’s DllEntryPoint function, if it has one, with the DLL_PROCESS_DETACH value. Doing so gives the DLL an opportunity to clean up resources allocated on behalf of the current process. After the entry-point function returns, the library module is removed from the address space of the current process.

Calling FreeLibrary does not affect other processes using the same library module.

See Also

DllEntryPoint, FreeLibraryAndExitThread, FreeModule, GetModuleHandle, LoadLibrary


FreeLibraryAndExitThread

The FreeLibraryAndExitThread function decrements the reference count of a loaded dynamic-link library (DLL) by one, and then calls ExitThread to terminate the calling thread. The function does not return.

The FreeLibraryAndExitThread function gives threads that are created and executed within a dynamic-link library an opportunity to safely unload the DLL and terminate themselves.

VOID FreeLibraryAndExitThread(

HMODULE hLibModule,	// dynamic-link library whose reference count is to decrement
DWORD dwExitCode	// exit code for thread
);
Parameters

hLibModule

Specifies the dynamic-link library module whose reference count the function decrements.

dwExitCode

Specifies the exit code for the calling thread.

Return Values

The function has no return value. The function does not return. Invalid hLibModule handles are ignored.

Remarks

The FreeLibraryAndExitThread function is implemented as:

    FreeLibrary(hLibModule);

    ExitThread(dwExitCode);

Refer to the reference pages for FreeLibrary and ExitThread for further information on those functions.

See Also

FreeLibrary, ExitThread, DisableThreadLibraryCalls


FreeModule

The FreeModule function is obsolete.

This function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the FreeLibrary function.


FreePrinterNotifyInfo

The FreePrinterNotifyInfo function frees a system-allocated buffer that was returned by the FindNextPrinterChangeNotification function.

BOOL FreePrinterNotifyInfo(

PPRINTER_NOTIFY_INFO pPrinterNotifyInfo	// pointer to a PRINTER_NOTIFY_INFO buffer
);
Parameters

pPrinterNotifyInfo

Pointer to a PRINTER_NOTIFY_INFO buffer returned from a call to the FindNextPrinterChangeNotification function. FreePrinterNotifyInfo deallocates this buffer.

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.

See Also

FindNextPrinterChangeNotification, PRINTER_NOTIFY_INFO


FreeProcInstance

The FreeProcInstance function is obsolete.

This function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should not use this function; it has no meaning in the 32-bit environment.


FreeResource

The FreeResource function is obsolete. It is provided to simplify porting of 16-bit Windows-based applications. It is not necessary for Win32-based applications to free resources loaded by using the LoadResource function.

See Also

LoadResource, LockResource


FreeSid

The FreeSid function frees a security identifier (SID) previously allocated by using the AllocateAndInitializeSid function.

PVOID FreeSid(

PSID pSid	// pointer to SID to free
);
Parameters

pSid

Points to the SID structure to free.

Return Values

This function does not return a value.

See Also

AllocateAndInitializeSid, SID


FRHookProc

An FRHookProc hook procedure is an application-defined or library-defined callback procedure that is used with the Find and Replace common dialog boxes. The hook procedure receives messages or notifications intended for the default dialog box procedure.

UINT APIENTRY FRHookProc(

HWND hdlg,	// handle to the dialog box window
UINT uiMsg	// message identifier
WPARAM wParam,	// message parameter
LPARAM lParam	// message parameter
);
Parameters

hdlg

Handle to the Find or Replace common dialog box window for which the message is intended.

uiMsg

Identifies the message being received.

wParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

lParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

If the uiMsg parameter indicates the WM_INITDIALOG message, lParam is a pointer to a FINDREPLACE structure containing the values specified when the common dialog box was created.

Return Values

If the hook procedure returns zero, the default dialog box procedure processes the message.

If the hook procedure returns a nonzero value, the default dialog box procedure ignores the message.

Remarks

When you use the FindText or ReplaceText functions to create a Find or Replace common dialog box, you can provide an FRHookProc hook procedure to process messages or notifications intended for the dialog box procedure. To enable the hook procedure, use the FINDREPLACE structure that you passed to the dialog creation function. Specify the address of the hook procedure in the lpfnHook member and specify the FR_ENABLEHOOK flag in the Flags member.

The default dialog box procedure processes the WM_INITDIALOG message before passing it to the hook procedure. For all other messages, the hook procedure receives the message first. Then, the return value of the hook procedure determines whether the default dialog procedure processes the message or ignores it.

If the hook procedure processes the WM_CTLCOLORDLG message, it must return a valid brush handle for painting the background of the dialog box. In general, if the hook procedure processes any WM_CTLCOLOR* message, it must return a valid brush handle for painting the background of the specified control.

Do not call the EndDialog function from the hook procedure. Instead, the hook procedure can call the PostMessage function to post a WM_COMMAND message with the IDABORT value to the dialog box procedure. Posting IDABORT closes the dialog box and causes the dialog box function to return FALSE. If you need to know why the hook procedure closed the dialog box, you must provide your own communication mechanism between the hook procedure and your application.

You can subclass the standard controls of the common dialog box. However, the common dialog box procedure may also subclass the controls. Because of this, you should subclass controls when your hook procedure processes the WM_INITDIALOG message. This ensures that your subclass procedure receives the control-specific messages before the subclass procedure set by the dialog box procedure.

FRHookProc is a placeholder for the application-defined or library-defined function name. The LPFRHOOKPROC type is a pointer to an FRHookProc hook procedure.

See Also

EndDialog, FINDREPLACE, FindText, PostMessage, ReplaceText, WM_INITDIALOG, WM_CTLCOLORDLG


FSCTL_DISMOUNT_VOLUME

The FSCTL_DISMOUNT_VOLUME DeviceIoControl operation dismounts a volume.

dwIoControlCode = FSCTL_DISMOUNT_VOLUME;   // operation code

lpInBuffer = NULL; // pointer to input buffer; not used; must be NULL

nInBufferSize = 0; // size of input buffer; not used; must be zero

lpOutBuffer ;      // pointer to output buffer; not used; must be NULL

nOutBufferSize ;   // size of output buffer; not used; must be zero

lpBytesReturned ;  // pointer to DWORD used by DeviceIoControl function

Parameters

lpInBuffer

Points to an input buffer. Not used with this operation. Set to NULL.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer. Not used with this operation. Set to zero.

lpOutBuffer

Points to an output buffer. Not used with this operation. Set to NULL.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer. Not used with this operation. Set to zero.

lpBytesReturned

Pointer to a DWORD. This value cannot be NULL. Although the FSCTL_DISMOUNT_VOLUME operation produces no output data and lpOutBuffer should be NULL, the DeviceIoControl function uses the variable pointed to by lpBytesReturned. After the operation, the value of this variable is without meaning.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

The hDevice handle passed to DeviceIoControl must be a handle to a volume, opened for direct access. An application can obtain such a handle by calling CreateFile with lpFileName set to a string that looks like this:

\\.\X:

where X is a hard-drive partition letter, floppy disk drive, or CD-ROM drive. The application must also specify the FILE_SHARE_READ and FILE_SHARE_WRITE flags in the dwShareMode parameter of CreateFile.

If the specified volume is locked, the operation fails.

A dismounted volume has the following properties:

•	There are no open files.

•	The operating system does not “know” about the volume.

The operating system tries to mount an unmounted volume as soon as any attempt is made to access it. For example, a call to GetLogicalDrives triggers the operating system to mount any unmounted volumes.

Dismounting a volume is useful whenever a volume needs to disappear for a while. For example, an application that changes a volume’s file system from FAT to NTFS might follow these steps:

1.	Open the volume

2.	Lock the volume

3.	Format the volume

4.	Unlock the volume

5.	Dismount the volume

6.	Close the volume handle

A dismounting operation removes the volume from the FAT file system’s “awareness.” When the operating system mounts the volume, it appears as an NTFS volume.

See Also

CreateFile, DeviceIoControl, ExitThread, GetLogicalDrives


FSCTL_GET_COMPRESSION

The FSCTL_GET_COMPRESSION DeviceIoControl operation obtains the current compression state of a file or directory on a volume whose file system supports per-stream compression.

dwIoControlCode = FSCTL_GET_COMPRESSION;   // operation code

lpInBuffer = NULL; // pointer to input buffer; not used; must be NULL

nInBufferSize = 0; // size of input buffer; not used; must be zero

lpOutBuffer ;      // pointer to output buffer

nOutBufferSize ;   // size of output buffer

lpBytesReturned ;  // pointer to actual bytes of output

Parameters

lpInBuffer

Points to an input buffer. Not used with this operation. Set to NULL.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer. Not used with this operation. Set to zero.

lpOutBuffer

Points to a buffer that receives a USHORT indicating the current compression state of the file or directory.

The following values are defined:

Value	Meaning
COMPRESSION_FORMAT_NONE	The file or directory is not compressed.
COMPRESSION_FORMAT_LZNT1	The file or directory is compressed, using the LZNT1 compression format.
all other values	Reserved for future use.
nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer. The buffer  must be large enough to contain one USHORT value.

lpBytesReturned

Points to a DWORD value that receives the actual size, in bytes, of the data stored into the buffer pointed to by lpOutBuffer.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

On this release, LZNT1 is the only compression algorithm implemented. Future releases may have additional compression methods.

COMPRESSION_FORMAT_DEFAULT is not a compression state so it is not included in the table under the lpOutBuffer parameter. This value is only used with the FSCTL_SET_COMPRESSION operation

If the file system of the volume containing the specified file or directory does not support per-file or per-directory compression, the FSCTL_GET_COMPRESSION operation fails.

Windows NT version 3.51 supports file compression on volumes formatted with NTFS.

You can set the compression state of a file or directory by using the FSCTL_SET_COMPRESSION DeviceIoControl operation. You can also compress or uncompress a file with that operation.

You can obtain the compression attribute of a file or directory by calling the GetFileAttributes function. The compression attribute indicates whether a file or directory is compressed. The compression state indicates whether a file or directory is compressed, and, if it is, the format of the compressed data.

See Also

DeviceIoControl, FSCTL_SET_COMPRESSION, GetFileAttributes


FSCTL_LOCK_VOLUME

The FSCTL_LOCK_VOLUME DeviceIoControl operation locks a volume. A locked volume can be accessed only through handles to the file object (*hDevice) that locks the volume.

dwIoControlCode = FSCTL_LOCK_VOLUME;   // operation code

lpInBuffer = NULL; // pointer to input buffer; not used; must be NULL

nInBufferSize = 0; // size of input buffer; not used; must be zero

lpOutBuffer ;      // pointer to output buffer; not used; must be NULL

nOutBufferSize ;   // size of output buffer; not used; must be zero

lpBytesReturned ;  // pointer to DWORD used by DeviceIoControl function

Parameters

lpInBuffer

Points to an input buffer. Not used with this operation. Set to NULL.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer. Not used with this operation. Set to zero.

lpOutBuffer

Points to an output buffer. Not used with this operation. Set to NULL.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer. Not used with this operation. Set to zero.

lpBytesReturned

Pointer to a DWORD. This value cannot be NULL. Although the FSCTL_LOCK_VOLUME operation produces no output data and lpOutBuffer should be NULL, the DeviceIoControl function uses the variable pointed to by lpBytesReturned. After the operation, the value of this variable is without meaning.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

The hDevice handle passed to DeviceIoControl must be a handle to a volume, opened for direct access. An application can obtain such a handle by calling CreateFile with lpFileName set to a string that looks like this:

\\.\X:

where X is a hard-drive partition letter, floppy disk drive, or CD-ROM drive. The application must also specify the FILE_SHARE_READ and FILE_SHARE_WRITE flags in the dwShareMode parameter of CreateFile.

The FSCTL_LOCK_VOLUME operation fails if there are any open files on the volume. Conversely, success of this operation indicates there are no open files.

The operation is useful for applications that need exclusive access to a volume for a period of time—for example, disk utility programs.

A locked volume remains locked until one of the following occurs:

•	The application invokes the FSCTL_UNLOCK_VOLUME DeviceIoControl operation to unlock the volume.

•	The handle closes, either directly through CloseHandle, or indirectly when a process terminates.

The system flushes all cached data to the volume before locking it. For example, any data held in a lazy-write cache is written to the volume.

See Also

CloseHandle, CreateFile, DeviceIoControl, FSCTL_UNLOCK_VOLUME


FSCTL_SET_COMPRESSION

The FSCTL_SET_COMPRESSION DeviceIoControl operation sets the compression state of a file or directory on a volume whose file system supports per-file and per-directory compression. You can use this operation to compress or uncompress a file or directory on such a volume.

dwIoControlCode = FSCTL_SET_COMPRESSION;   // operation code

lpInBuffer ;        // pointer to input buffer

nInBufferSize ;     // size of input buffer

lpOutBuffer = NULL; // pointer to output buffer; not used; must be NULL

nOutBufferSize = 0; // size of output buffer; not used; must be zero

lpBytesReturned ;   // pointer to DWORD used by DeviceIoControl function

Parameters

lpInBuffer

Points to a buffer that contains a USHORT that specifies a new compression state for the file or directory.

The following values are defined:

Value	Meaning
COMPRESSION_FORMAT_NONE	Uncompress the file or directory.
COMPRESSION_FORMAT_DEFAULT	Compress the file or directory, using the default compression format.
COMPRESSION_FORMAT_LZNT1	Compress the file or directory, using the LZNT1 compression format.
all other values	Reserved for future use.
nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer. The buffer must be large enough to contain one USHORT value.

lpOutBuffer

Points to an output buffer. Not used with this operation. Set to NULL.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer. Not used with this operation. Set to zero.

lpBytesReturned

Pointer to a DWORD. This value cannot be NULL. Although the FSCTL_SET_COMPRESSION operation produces no output data and lpOutBuffer should be NULL, the DeviceIoControl function uses the variable pointed to by lpBytesReturned. After the operation, the value of this variable is without meaning.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

On this release, LZNT1 is the only compression algorithm implemented. As a result, LZNT1 will be used as the DEFAULT compression method. Future releases may have additional compression methods which may be used as the DEFAULT.

If the file system of the volume containing the specified file or directory does not support per-file or per-directory compression, the FSCTL_SET_COMPRESSION operation fails.

Windows NT release 3.51 supports file compression on volumes formatted with NTFS.

The compression state change of the file or directory occurs synchronously with the call to DeviceIoControl.

You can obtain the compression state of a file or directory by using the FSCTL_GET_COMPRESSION DeviceIoControl operation.

You can obtain the compression attribute of a file or directory by calling the GetFileAttributes function. The compression attribute indicates whether a file or directory is compressed. The compression state indicates whether a file or directory is compressed and, if it is, the format of the compressed data.

See Also

DeviceIoControl, FSCTL_GET_COMPRESSION, GetFileAttributes


FSCTL_UNLOCK_VOLUME

The FSCTL_UNLOCK_VOLUME DeviceIoControl operation unlocks a volume.

dwIoControlCode = FSCTL_UNLOCK_VOLUME;   // operation code

lpInBuffer = NULL; // pointer to input buffer; not used; must be NULL

nInBufferSize = 0; // size of input buffer; not used; must be zero

lpOutBuffer ;      // pointer to output buffer; not used; must be NULL

nOutBufferSize ;   // size of output buffer; not used; must be zero

lpBytesReturned ;  // pointer to DWORD used by DeviceIoControl function

Parameters

lpInBuffer

Points to an input buffer. Not used with this operation. Set to NULL.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer. Not used with this operation. Set to zero.

lpOutBuffer

Points to an output buffer. Not used with this operation. Set to NULL.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer. Not used with this operation. Set to zero.

lpBytesReturned

Pointer to a DWORD. This value cannot be NULL. Although the FSCTL_UNLOCK_VOLUME operation produces no output data and lpOutBuffer should be NULL, the DeviceIoControl function uses the variable pointed to by lpBytesReturned. After the operation, the value of this variable is without meaning.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

An application can call the FSCTL_LOCK_VOLUME DeviceIoControl operation to lock a volume.

The hDevice handle passed to DeviceIoControl must be a handle to a volume, opened for direct access. An application can obtain such a handle by calling CreateFile with lpFileName set to a string that looks like this:

\\.\X:

where X is a hard-drive partition letter, floppy disk drive, or CD-ROM drive. The application must also specify the FILE_SHARE_READ and FILE_SHARE_WRITE flags in the dwShareMode parameter of CreateFile.

See Also

CreateFile, DeviceIoControl, FSCTL_LOCK_VOLUME


GdiComment

The GdiComment function copies a comment from a buffer into a specified enhanced-format metafile.

BOOL GdiComment(

HDC hdc,	// handle to a device context
UINT cbSize,	// size of text buffer
CONST BYTE *lpData	// pointer to text buffer
);
Parameters

hdc

Identifies an enhanced-metafile device context.

cbSize

Specifies the length of the comment buffer, in bytes.

lpData

Points to the buffer that contains the comment.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

A comment can include any kind of private information — for example, the source of a picture and the date it was created. A comment should begin with an application signature, followed by the data.

Comments should not contain application-specific or position-specific data. Position-specific data specifies the location of a record, and it should not be included because one metafile may be embedded within another metafile.

A public comment is a comment that begins with the comment signature identifier GDICOMMENT_IDENTIFIER. The following public comments are defined:

Comment	Description
GDICOMMENT_WINDOWS_METAFILE
	The GDICOMMENT_WINDOWS_METAFILE public comment contains a Windows-format metafile that is equivalent to an enhanced-format metafile. This comment is written only by the SetWinMetaFileBits function. The comment record, if given, follows the ENHMETAHEADER metafile record. The comment has the following form:
DWORD ident;         // This contains GDICOMMENT_IDENTIFIER.

DWORD iComment;      // This contains GDICOMMENT_WINDOWS_METAFILE.

DWORD nVersion;      // This contains the version number of the

                     // Windows-format metafile.

DWORD nChecksum;     // This is the additive DWORD checksum for

                     // the enhanced metafile.  The checksum

                     // for the enhanced metafile data including

                     // this comment record must be zero.

                     // Otherwise, the enhanced metafile has been

                     //  modified and the Windows-format

                     // metafile is no longer valid.

DWORD fFlags;        // This must be zero.

DWORD cbWinMetaFile; // This is the size, in bytes. of the

                     // Windows-format metafile data that follows.

GDICOMMENT_BEGINGROUP
	The GDICOMMENT_BEGINGROUP public comment identifies the beginning of a group of drawing records. It identifies an object within an enhanced metafile. The comment has the following form:
DWORD   ident;         // This contains GDICOMMENT_IDENTIFIER.

DWORD   iComment;      // This contains GDICOMMENT_BEGINGROUP.

RECTL   rclOutput;     // This is the bounding rectangle for the

                       // object in logical coordinates.

DWORD   nDescription;  // This is the number of characters in the

                       // optional Unicode description string that

                       // follows. This is zero if there is no

                       // description string.

GDICOMMENT_ENDGROUP
	The GDICOMMENT_ENDGROUP public comment identifies the end of a group of drawing records. The GDICOMMENT_BEGINGROUP comment and the GDICOMMENT_ENDGROUP comment must be included in a pair and may be nested. The comment has the following form:
DWORD   ident;       // This contains GDICOMMENT_IDENTIFIER.

DWORD   iComment;    // This contains GDICOMMENT_ENDGROUP.

GDICOMMENT_MULTIFORMATS
	The GDICOMMENT_MULTIFORMATS public comment allows multiple definitions of a picture to be included in an enhanced metafile. Using this comment, for example, an application can include an encapsulated PostScript definition as well as an enhanced metafile definition of a picture. When the record is played back, GDI selects and renders the first format recognized by the device. The comment has the following form:
DWORD   ident;          // This contains GDICOMMENT_IDENTIFIER.

DWORD   iComment;       // This contains GDICOMMENT_MULTIFORMATS.

RECTL   rclOutput;      // This is the bounding rectangle for the

                        // picture in logical coordinates.

DWORD   nFormats;       // This contains the number of formats in

                        // the comment.

EMRFORMAT aemrformat[1];// This is an array of EMRFORMAT structures

                        // in the order of preference.  The data

                        // for each format follows the last

                        // EMRFORMAT structure.

The EMRFORMAT structure has the following form:

typedef struct tagEMRFORMAT   {

    DWORD   dSignature;

    DWORD   nVersion;

    DWORD   cbData;

    DWORD   offData;

} EMRFORMAT;

See Also

CreateEnhMetaFile, EMRFORMAT, SetWinMetaFileBits


GdiFlush

The GdiFlush function flushes the calling thread’s current batch.

BOOL GdiFlush(VOID)

Parameters

This function has no parameters.

Return Values

If all functions in the current batch succeed, the return value is nonzero.

If not all functions in the current batch succeed, the return value is zero, indicating that at least one function returned an error.

Remarks

Batching enhances drawing performance by minimizing the amount of time needed to call GDI drawing functions that return Boolean values. The system accumulates the parameters for calls to these functions in the current batch and then calls the functions when the batch is flushed by any of the following means:

•	Calling the GdiFlush function

•	Reaching or exceeding the batch limit set by the GdiSetBatchLimit function

•	Filling the batching buffers

•	Calling any GDI function that does not return a Boolean value

The return value for GdiFlush applies only to the functions in the batch at the time GdiFlush is called. Errors that occur when the batch is flushed by any other means are never reported.

The GdiGetBatchLimit function returns the batch limit.

Note that the batch limit is maintained for each thread separately. In order to completely disable batching, call GdiSetBatchLimit(1) during the initialization of each thread.

An application should call GdiFlush before a thread goes away if there is a possibility that there are pending function calls in the graphics batch queue. The operating system does not execute such batched functions when a thread goes away.

A multithreaded application that serializes access to GDI objects with a mutex must ensure flushing the GDI batch queue by calling GdiFlush as each thread releases ownership of the GDI object. This prevents collisions of the GDI objects (device contexts, metafiles, and so on).

See Also

GdiGetBatchLimit, GdiSetBatchLimit


GdiGetBatchLimit

The GdiGetBatchLimit function returns the maximum number of function calls that can be accumulated in the calling thread’s current batch. The system flushes the current batch whenever this limit is exceeded.

DWORD GdiGetBatchLimit(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the batch limit.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The batch limit is set by using the GdiSetBatchLimit function. Setting the limit to 1 effectively disables batching.

Only GDI drawing functions that return Boolean values can be batched; calls to any other GDI functions immediately flush the current batch. Exceeding the batch limit or calling the GdiFlush function also flushes the current batch.

When the system batches a function call, the function returns TRUE. The actual return value for the function is reported only if GdiFlush is used to flush the batch.

Note that the batch limit is maintained for each thread separately. In order to completely disable batching, call GdiSetBatchLimit(1) during the initialization of each thread.

See Also

GdiFlush, GdiSetBatchLimit


GdiSetBatchLimit

The GdiSetBatchLimit function sets the maximum number of functions that can be accumulated in the calling thread’s current batch. The system flushes the current batch whenever this limit is exceeded.

DWORD GdiSetBatchLimit(

DWORD dwLimit	// batch limit
);
Parameters

dwLimit

Specifies the batch limit to be set. A value of 0 sets the default limit. A value of 1 disables batching.

Return Values

If the function succeeds, the return value is the previous batch limit.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Only GDI drawing functions that return Boolean values can be accumulated in the current batch; calls to any other GDI functions immediately flush the current batch. Exceeding the batch limit or calling the GdiFlush function also flushes the current batch.

When the system accumulates a function, the function returns TRUE to indicate it is in the batch. When the system flushes the current batch and executes the function for the second time, the return value is either TRUE or FALSE, depending on whether the function succeeds. This second return value is reported only if GdiFlush is used to flush the batch.

Note that the batch limit is maintained for each thread separately. In order to completely disable batching, call GdiSetBatchLimit(1) during the initialization of each thread.

See Also

GdiFlush, GdiGetBatchLimit


GenerateConsoleCtrlEvent

The GenerateConsoleCtrlEvent function sends a specified signal to a console process group that shares the console associated with the calling process.

BOOL GenerateConsoleCtrlEvent(

DWORD dwCtrlEvent,	// signal to generate
DWORD dwProcessGroupId	// process group to get signal
);
Parameters

dwCtrlEvent

Specifies the type of signal to generate. One of the following values is specified:

Value	Meaning
CTRL_C_EVENT	Generates a CTRL+C signal.
CTRL_BREAK_EVENT	Generates a CTRL+BREAK signal.
dwProcessGroupId

Specifies the identifier of the process group that receives the signal. A process group is created when the CREATE_NEW_PROCESS_GROUP flag is specified in a call to the CreateProcess function. The process identifier of the new process is also the process group identifier of a new process group. The process group includes all processes that are descendants of the root process. Only those processes in the group that share the same console as the calling process receive the signal. In other words, if a process in the group creates a new console, that process does not receive the signal, nor do its descendants.

If this parameter is zero, the signal is generated in all processes that share the console of the calling process.

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.

Remarks

GenerateConsoleCtrlEvent causes the control handler functions of processes in the target group to be called. All console processes have a default handler function that calls the ExitProcess function. A console process can use the SetConsoleCtrlHandler function to install or remove other handler functions.

SetConsoleCtrlHandler can also enable an inheritable attribute that causes the calling process to ignore CTRL+C signals. If GenerateConsoleCtrlEvent sends a CTRL+C signal to a process for which this attribute is enabled, the handler functions for that process are not called. CTRL+BREAK signals always cause the handler functions to be called.

See Also

CreateProcess, ExitProcess, SetConsoleCtrlHandler


GetAce

The GetAce function obtains a pointer to an ACE in an ACL.

An ACE is an access control entry. An ACL is an access control list.

BOOL GetAce(

PACL pAcl,	// pointer to access-control list
DWORD dwAceIndex,	// index of ACE to retrieve
LPVOID *pAce	// pointer to pointer to ACE
);
Parameters

pAcl

Points to an ACL structure containing the ACE to be retrieved.

dwAceIndex

Specifies the ACE to which a pointer is retrieved. A value of 0 corresponds to the first ACE in the ACL, 1 to the second ACE, and so on.

pAce

Points to a pointer the function sets to the address of the ACE.

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.

See Also

ACL, AddAccessAllowedAce, AddAccessDeniedAce, AddAce, AddAuditAccessAce, GetAclInformation, InitializeAcl


GetAclInformation

The GetAclInformation function retrieves information about an access-control list (ACL).

BOOL GetAclInformation(

PACL pAcl,	// pointer to access-control list
LPVOID pAclInformation,	// pointer to ACL information
DWORD nAclInformationLength,	// size of ACL information
ACL_INFORMATION_CLASS dwAclInformationClass	// class of requested information
);
Parameters

pAcl

Points to an ACL structure. The function retrieves information about this ACL.

pAclInformation

Points to a buffer receiving the requested information. The structure put into the buffer depends on the information class requested in the dwAclInformationClass parameter.

nAclInformationLength

Specifies the size, in bytes, of the buffer pointed to by the pAclInformation parameter.

dwAclInformationClass

Specifies an ACL_INFORMATION_CLASS enumerated type that gives the class of information requested. This parameter can be one of two values from this enumerated type. If the value is AclRevisionInformation, the function fills the buffer pointed to by the pAclInformation parameter with an ACL_REVISION_INFORMATION structure.

If the value is AclSizeInformation, the function fills the buffer pointed to by the pAclInformation parameter with an ACL_SIZE_INFORMATION structure.

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.

See Also

ACL, ACL_REVISION_INFORMATION, ACL_SIZE_INFORMATION, GetAce, InitializeAcl, IsValidAcl, SetAclInformation


GetACP

The GetACP function retrieves the current ANSI code-page identifier for the system.

UINT GetACP(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the current ANSI code-page identifier for the system, or a default identifier if no code page is current.

Remarks

Following are the ANSI code-page identifiers:

Identifier	Meaning
874	Thai
932	Japan
936	Chinese (PRC, Singapore)
949	Korean
950	Chinese (Taiwan, Hong Kong)
1200	Unicode (BMP of ISO 10646)
1250	Windows 3.1 Eastern European
1251	Windows 3.1 Cyrillic
1252	Windows 3.1 Latin 1 (US, Western Europe)
1253	Windows 3.1 Greek
1254	Windows 3.1 Turkish
1255	Hebrew
1256	Arabic
1257	Baltic
See Also

GetCPInfo, GetOEMCP


GetActiveWindow

The GetActiveWindow function retrieves the window handle to the active window associated with the thread that calls the function.

HWND GetActiveWindow(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the handle to the active window associated with the thread that calls the function. If the calling thread does not have an active window, the return value is NULL.

See Also

SetActiveWindow


GetArcDirection

The GetArcDirection function returns the current arc direction for the specified device context. Arc and rectangle functions use the arc direction.

int GetArcDirection(

HDC hdc	// handle to device context
);
Parameters

hdc

Identifies the device context.

Return Values

If the function succeeds, the return value specifies the current arc direction. Following are the valid return values:

Value	Meaning
AD_COUNTERCLOCKWISE	Arcs and rectangles are drawn counterclockwise.
AD_CLOCKWISE	Arcs and rectangles are drawn clockwise.
If an error occurs, the return value is zero.

See Also

SetArcDirection


GetAspectRatioFilterEx

The GetAspectRatioFilterEx function retrieves the setting for the current aspect-ratio filter.

BOOL GetAspectRatioFilterEx(

HDC hdc,	// handle to device context
LPSIZE lpAspectRatio	// pointer to aspect-ratio filter
);
Parameters

hdc

Identifies a device context.

lpAspectRatio

Points to a SIZE structure that receives the current aspect-ratio filter.

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.

Remarks

The aspect ratio is the ratio formed by the width and height of a pixel on a given device.

Windows provides a special filter, the aspect-ratio filter, to select fonts that were designed for a particular device. An application can specify that Windows should only retrieve fonts matching the specified aspect ratio by calling the SetMapperFlags function.

See Also

SetMapperFlags, SIZE


GetAsyncKeyState

The GetAsyncKeyState function determines whether a key is up or down at the time the function is called, and whether the key was pressed after a previous call to GetAsyncKeyState.

SHORT GetAsyncKeyState(

int vKey	// virtual-key code
);
Parameters

vKey

Specifies one of 256 possible virtual-key codes.

Windows NT: You can use left- and right-distinguishing constants to specify certain keys. See the Remarks section for further information.

Windows 95: Windows 95 does not support the left- and right-distinguishing constants available on Windows NT.

Return Values

If the function succeeds, the return value specifies whether the key was pressed since the last call to GetAsyncKeyState, and whether the key is currently up or down. If the most significant bit is set, the key is down, and if the least significant bit is set, the key was pressed after the previous call to GetAsyncKeyState. The return value is zero if a window in another thread or process currently has the keyboard focus.

Windows 95: Windows 95 does not support the left- and right-distinguishing constants. If you call GetAsyncKeyState on the Windows 95 platform with these constants, the return value is zero.

Remarks

You can use the virtual-key code constants VK_SHIFT, VK_CONTROL, and VK_MENU as values for the vKey parameter. This gives the state of the SHIFT, CTRL, or ALT keys without distinguishing between left and right.

Windows NT: You can use the following virtual-key code constants as values for vKey to distinguish between the left and right instances of those keys:

VK_LSHIFT	VK_RSHIFT
VK_LCONTROL	VK_RCONTROL
VK_LMENU	VK_RMENU
These left- and right-distinguishing constants are only available when you call the GetKeyboardState, SetKeyboardState, GetAsyncKeyState, GetKeyState, and MapVirtualKey functions.

Windows 95: Windows 95 does not support the left- and right-distinguishing constants, and returns 0 when you use these constants.

The GetAsyncKeyState function works with mouse buttons. However, it checks on the state of the physical mouse buttons, not on the logical mouse buttons that the physical buttons are mapped to. For example, the call GetAsyncKeyState(VK_LBUTTON) always returns the state of the left physical mouse button, which may mapped to the left or right logical mouse button. You can determine the system’s current mapping of physical mouse buttons to logical mouse buttons by calling

GetSystemMetrics(SM_SWAPBUTTON)

which returns TRUE if the mouse buttons have been swapped.

See Also

GetKeyboardState, GetKeyState, GetSystemMetrics, MapVirtualKey, SetKeyboardState


GetAtomName

The GetAtomName function retrieves a copy of the character string associated with the specified local atom. This function replaces the GetAtomHandle function.

UINT GetAtomName(

ATOM nAtom,	// atom identifying character string
LPTSTR lpBuffer,	// address of buffer for atom string
int nSize	// size of buffer
);
Parameters

nAtom

Specifies the local atom that identifies the character string to be retrieved.

lpBuffer

Points to the buffer for the character string.

nSize

Specifies the size, in characters, of the buffer.

Return Values

If the function succeeds, the return value is the length of the string copied to the buffer, in characters, not including the terminating null character.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The string returned for an integer atom (an atom created by the MAKEINTATOM macro) is a null-terminated string in which the first character is a pound sign (#) and the remaining characters represent the unsigned integer originally passed to MAKEINTATOM.

See Also

AddAtom, DeleteAtom, FindAtom, GlobalAddAtom, GlobalDeleteAtom, GlobalFindAtom, GlobalGetAtomName, MAKEINTATOM


GetAuditedPermissionsFromAcl [New - Windows NT]
GetAuditedPermissionsFromAcl

[New - Windows NT]

The GetAuditedPermissionsFromAcl function returns the audited access rights for a specified trustee. The audited rights are based on the access-control entries (ACEs) of a specified access-control list (ACL). The audited access rights indicate the types of access attempts that cause the system to generate an audit record in the system event log. The audited rights include those that the ACL specifies for the trustee or for any groups of which the trustee is a member. In determining the audited rights, the function does not consider the security privileges held by the trustee.

DWORD GetAuditedPermissionsFromAcl(

PACL pacl,	// ACL to get trustee’s audited rights from
PTRUSTEE pTrustee,	// trustee to get rights for
PACCESS_MASK pSuccessfulAuditedRights,	// receives rights audited for successful access
PACCESS_MASK pFailedAuditRights	// receives rights audited for failed access
);
Parameters

pacl

Pointer to an ACL from which to get the trustee’s audited access rights.

pTrustee

Pointer to a TRUSTEE structure that identifies the trustee. A trustee can be a user, group, or program (such as a Windows NT service). You can use a name or a security identifier (SID) to identify a trustee.

pSuccessfulAuditedRights

Pointer to an ACCESS_MASK variable that receives a set of access rights. The system generates an audit record when the trustee successfully uses any of these access rights.

pFailedAuditRights

Pointer to an ACCESS_MASK variable that receives a set of access rights based on the access-control entries in the specified ACL. The system generates an audit record when the trustee fails in an attempt to use any of these rights.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

The GetAuditedPermissionsFromAcl function checks all system-audit ACEs in the ACL to determine the audited rights for the trustee. For all ACEs that specify audited rights for a group, GetAuditedPermissionsFromAcl enumerates the members of the group to determine whether the trustee is a member. The function returns an error if it cannot enumerate the members of a group.

See Also

ACCESS_MASK, ACE, ACL, GetEffectiveRightsFromAcl, SID, SYSTEM_AUDIT_ACE, TRUSTEE


GetBinaryType

The GetBinaryType function determines whether a file is executable, and if so, what type of executable file it is. That last property determines which subsystem an executable file runs under.

BOOL GetBinaryType (

LPCTSTR lpApplicationName,	// points to fully qualified path of file to test
LPDWORD lpBinaryType	// points to variable to receive binary type information
);
Parameters

lpApplicationName

Points to a null-terminated string that contains the fully qualified path of the file whose binary type the function shall determine.

lpBinaryType

Points to a variable to receive information about the executable type of the file specified by lpApplicationName. The function adjusts a set of bit flags in this variable. The following bit flag constants are defined:

Value	Description
SCS_32BIT_BINARY	A Win32-based application
SCS_DOS_BINARY	An MS-DOS − based application
SCS_OS216_BINARY	A 16-bit OS/2-based application
SCS_PIF_BINARY	A PIF file that executes an MS-DOS − based application
SCS_POSIX_BINARY	A POSIX − based application
SCS_WOW_BINARY	A 16-bit Windows-based application
Return Values

If the file is executable, the return value is nonzero. The function sets the variable pointed to by lpBinaryType to indicate the file’s executable type.

If the function is not executable, or if the function fails, the return value is zero.


GetBitmapBits

The GetBitmapBits function copies the bitmap bits of a specified bitmap into a buffer.

The GetBitmapBits function is not implemented in the Win32 API. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the GetDIBits function.


GetBitmapDimensionEx

The GetBitmapDimensionEx function retrieves the dimensions of a bitmap. The retrieved dimensions must have been set by the SetBitmapDimensionEx function. The GetMapDimensionEx function replaces the GetMapDimension function.

BOOL GetBitmapDimensionEx(

HBITMAP hBitmap,	// handle of bitmap
LPSIZE lpDimension	// address of structure receiving dimensions
);
Parameters

hBitmap

Identifies the bitmap.

lpDimension

Points to a SIZE structure to receive the bitmap dimensions.

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.

Remarks

The function returns a data structure that contains fields for the height and width of the bitmap. If those dimensions have not yet been set, the structure that is returned will have zeroes in those fields.

See Also

SetBitmapDimensionEx, SIZE


GetBkColor

The GetBkColor function returns the current background color for the specified device context.

COLORREF GetBkColor(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies the device context whose background color is to be returned.

Return Values

If the function succeeds, the return value is a COLORREF value for the current background color.

If the function fails, the return value is CLR_INVALID.

See Also

GetBkMode, SetBkColor


GetBkMode

The GetBkMode function returns the current background mix mode for a specified device context. The background mix mode of a device context affects text, hatched brushes, and pen styles that are not solid lines.

int GetBkMode(

HDC hdc	// handle to device context of interest
);
Parameters

hdc

Identifies the device context whose background mode is to be returned.

Return Values

If the function succeeds, the return value specifies the current background mix mode, either OPAQUE or TRANSPARENT.

If the function fails, the return value is zero.

See Also

GetBkColor, SetBkMode


GetBoundsRect

The GetBoundsRect function obtains the current accumulated bounding rectangle for a specified device context.

Windows maintains an accumulated bounding rectangle for each application. An application can retrieve and set this rectangle.

UINT GetBoundsRect(

HDC hdc,	// handle to device context of interest
LPRECT lprcBounds,	// points to structure to receive bounding rectangle
UINT flags	// specifies function options
);
Parameters

hdc

Identifies the device context whose bounding rectangle the function will return.

lprcBounds

Points to the RECT structure that will receive the current bounding rectangle. The application’s rectangle is returned in logical coordinates, and the Windows rectangle is returned in screen coordinates.

flags

Specifies aspects of how the GetBoundsRect function will operate on a given call. This parameter can be the following value:

Value	Meaning
DCB_RESET	Clears the bounding rectangle after returning it. If this flag is not set, the bounding rectangle will not be cleared.
Return Values

The return value specifies the state of the accumulated bounding rectangle; it can be one of the following values:

Value	Meaning
0	An error occurred. The given device context handle is invalid.
DCB_DISABLE	Boundary accumulation is off.
DCB_ENABLE	Boundary accumulation is on.
DCB_RESET	The bounding rectangle is empty.
DCB_SET	The bounding rectangle is not empty.
Remarks

The DCB_SET value is a combination of the bit values DCB_ACCUMULATE and DCB_RESET. Applications that check the DCB_RESET bit to determine whether the bounding rectangle is empty must also check the DCB_ACCUMULATE bit. The bounding rectangle is empty only if the DCB_RESET bit is 1 and the DCB_ACCUMULATE bit is 0.

See Also

SetBoundsRect


GetBrushOrgEx

The GetBrushOrgEx function retrieves the current brush origin for the specified device context. This function replaces the GetBrushOrg function.

BOOL GetBrushOrgEx(

HDC hdc,	// handle of device context
LPPOINT lppt	// address of structure of coordinates
);
Parameters

hdc

Identifies the device context.

lppt

Points to a POINT structure that receives the brush origin, in device coordinates.

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.

Remarks

A brush is a bitmap that Windows uses to paint the interiors of filled shapes.

The brush origin is a set of coordinates with values between 0 and 7, specifying the location of one pixel in the bitmap. The default brush origin coordinates are (0,0). For horizontal coordinates, the value 0 corresponds to the leftmost column of pixels; the value 7 corresponds to the rightmost column. For vertical coordinates, the value 0 corresponds to the uppermost row of pixels; value 7 corresponds to the lowermost row. When Windows positions the brush at the start of any painting operation, it maps the origin of the brush to the location in the window’s client area specified by the brush origin. For example, if the origin is set to (2,3), Windows maps the origin of the brush (0,0) to the location (2,3) on the window’s client area.

If an application uses a brush to fill the backgrounds of both a parent and a child window with matching colors, it may be necessary to set the brush origin after painting the parent window but before painting the child window.

Windows NT: The operating system automatically tracks the origin of all window-managed device contexts and adjusts their brushes as necessary to maintain an alignment of patterns on the surface.

Windows 95: Automatic tracking of the brush origin is not supported. Applications must use the UnrealizeObject, SetBrushOrgEx, and SelectObject functions to align the brush before using it.

See Also

POINT, SelectObject, SetBrushOrgEx, UnrealizeObject


GetCapture

The GetCapture function retrieves the handle of the window (if any) that has captured the mouse. Only one window at a time can capture the mouse; this window receives mouse input whether or not the cursor is within its borders.

HWND GetCapture(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the handle of the capture window associated with the current thread. If no window in the thread has captured the mouse, the return value is NULL.

Remarks

A NULL return value does not mean no other thread or process in the system has captured the mouse; it just means the current thread has not captured the mouse.

See Also

ReleaseCapture, SetCapture


GetCaretBlinkTime

The GetCaretBlinkTime function returns the elapsed time, in milliseconds, required to invert the caret’s pixels. The user can set this value using the Control Panel.

UINT GetCaretBlinkTime(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the blink time, in milliseconds.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

SetCaretBlinkTime


GetCaretPos

The GetCaretPos function copies the caret’s position, in client coordinates, to the specified POINT structure.

BOOL GetCaretPos(

LPPOINT lpPoint	// address of structure to receive coordinates
);
Parameters

lpPoint

Points to the POINT structure that is to receive the client coordinates of the caret.

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.

Remarks

The caret position is always given in the client coordinates of the window that contains the caret.

See Also

SetCaretPos, POINT


GetCharABCWidths

The GetCharABCWidths function retrieves the widths, in logical units, of consecutive characters in a given range from the current TrueType font. This function succeeds only with TrueType fonts.

BOOL GetCharABCWidths(

HDC hdc,	// handle of device context
UINT uFirstChar,	// first character in range to query
UINT uLastChar,	// last character in range to query
LPABC lpabc	// address of character-width structure
);
Parameters

hdc

Identifies the device context.

uFirstChar

Specifies the first character in the group of consecutive characters from the current font.

uLastChar

Specifies the last character in the group of consecutive characters from the current font.

lpabc

Points to an array of ABC structures that receive the character widths when the function returns. This array must contain at least as many ABC structures as there are characters in the range specified by the uFirstChar and uLastChar parameters.

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.

Remarks

The TrueType rasterizer provides ABC character spacing after a specific point size has been selected. “A” spacing is the distance added to the current position before placing the glyph. “B” spacing is the width of the black part of the glyph. “C” spacing is the distance added to the current position to provide white space to the right of the glyph. The total advanced width is given by A+B+C.

When the GetCharABCWidths function retrieves negative “A” or “C” widths for a character, that character includes underhangs or overhangs.

To convert the ABC widths to font design units, an application should use the value stored in the otmEMSquare member of a OUTLINETEXTMETRIC structure. This value can be retrieved by calling the GetOutlineTextMetrics function.

The ABC widths of the default character are used for characters outside the range of the currently selected font.

To retrieve the widths of characters in non-TrueType fonts, applications should use the GetCharWidth function.

See Also

GetCharWidth, GetOutlineTextMetrics, OUTLINETEXTMETRIC, ABC


GetCharABCWidthsFloat

The GetCharABCWidthsFloat function retrieves the widths, in logical units, of consecutive characters in a specified range from the current font.

BOOL GetCharABCWidthsFloat(

HDC hdc,	// handle of device context
UINT iFirstChar,	// first character in range to query
UINT iLastChar,	// last character in range to query
LPABCFLOAT lpABCF	// address of character-width structure
);
Parameters

hdc

Identifies the device context.

iFirstChar

Specifies the code point of the first character in the group of consecutive characters where the ABC widths are sought.

iLastChar

Specifies the code point of the last character in the group of consecutive characters where the ABC widths are sought. This range is inclusive. An error is returned if the specified last character precedes the specified first character.

lpABCF

Points to an application-defined buffer with an array of ABCFLOAT structures to receive the character widths when the function returns.

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.

Remarks

Unlike the GetCharABCWidths function that returns widths only for TrueType fonts, the GetCharABCWidthsFloat function retrieves widths for any font. The widths returned by this function are in the IEEE floating-point format.

If the current world-to-device transformation is not identified, the returned widths may be noninteger values, even if the corresponding values in the device space are integers.

“A” spacing is the distance added to the current position before placing the glyph. “B” spacing is the width of the black part of the glyph. “C” spacing is the distance added to the current position to provide white space to the right of the glyph. The total advanced width is given by A+B+C.

The ABC spaces are measured along the character base line of the selected font.

The ABC widths of the default character are used for characters outside the range of the currently selected font.

See Also

ABCFLOAT, GetCharABCWidths, GetCharWidth, GetCharWidthFloat


GetCharacterPlacement [Now Supported on Windows NT]
GetCharacterPlacement

[Now Supported on Windows NT]

The GetCharacterPlacement function retrieves information about a character string, such as character widths, caret positioning, ordering within the string, and glyph rendering. The type of information returned depends on the dwFlags parameter and is based on the currently selected font in the given display context. The function copies the information to the specified GCP_RESULTS structure or to one or more arrays specified by the structure.

DWORD GetCharacterPlacement(

HDC hdc,	// handle to device context
LPCTSTR lpString,	// pointer to string
int nCount,	// number of characters in string
int nMaxExtent,	// maximum extent for displayed string
LPGCP_RESULTS *lpResults,	// pointer to buffer for placement result
DWORD dwFlags	// placement flags
);
Parameters

hdc

Identifies the device context.

lpString

Points to the character string to process.

nCount

Specifies the number of characters in the string.

nMaxExtent

Specifies the maximum extent (in logical units) to which the string is processed. Characters that, if processed, would exceed this extent are ignored. Computations for any required ordering or glyph arrays apply only to the included characters. This parameter is used only if the GCP_MAXEXTENT value is given in the dwFlags parameter. As the function processes the input string, each character and its extent is added to the output, extent, and other arrays only if the total extent has not yet exceeded the maximum. Once the limit is reached, processing will stop.

lpResults

Points to a GCP_RESULTS structure that receives the results of the function.

dwFlags

Specifies how to process the string into the required arrays. This parameter can be one or more of the following values:

Value	Meaning
GCP_CLASSIN	Specifies that the lpClass array contains preset classifications for characters. The classifications may be the same as on output. If the particular classification for a character is not known, the corresponding location in the array must be set to zero. for more information about the classifications, see GCP_RESULTS. This is useful only if GetFontLanguageInfo returned the GCP_REORDER flag.
GCP_DIACRITIC	Determines how diacritics in the string are handled. If this value is not set, diacritics are treated as zero-width characters. For example, a Hebrew string may contain diacritics, but you may not want to display them.  Use GetFontLanguageInfo to determine whether a font supports diacritics. If it does, you can use or not use the GCP_DIACRITIC flag in the call to GetCharacterPlacement, depending on the needs of your application.
GCP_DISPLAYZWG	For languages that need reordering or different glyph shapes depending on the positions of the characters within a word, nondisplayable characters often appear in the codepage. For example, in the Hebrew codepage, there are Left-To-Right and Right-To-Left markers, to help determine the final positioning of characters within the output strings. Normally these are not displayed and are removed from the lpGlyphs and lpDx arrays. You can use the GCP_DISPLAYZWG flag to display these characters.
GCP_GLYPHSHAPE	Specifies that some or all characters in the string are to be displayed using shapes other than the standard shapes defined in the currently selected font for the current code page. Some languages, such as Arabic, cannot support glyph creation unless this value is given. As a general rule, if GetFontLanguageInfo returns this value for a string, this value must be used with GetCharacterPlacement.
GCP_JUSTIFY	Adjusts the extents in the lpDx array so that the string length is the same as nMaxExtent. GCP_JUSTIFY may only be used in conjunction with GCP_MAXEXTENT.
GCP_JUSTIFYIN	Specifies that the lpDx array contains justification weights on input. Normally, a justification weight can be either 0 or 1, where 1 indicates that the width of the given character can be adjusted for justification. For languages in which GetFontLanguageInfo returns the GCP_KASHIDA flag, the justification weight can be one of the GCP_ARAJUST_* values.
GCP_KASHIDA	Use Kashidas as well as, or instead of, adjusted extents to modify the length of the string so that it is equal to the value given by nMaxExtent. In the lpDx array, a Kashida is indicated by a negative justification index. GCP_KASHIDA may be used only in conjunction with GCP_JUSTIFY and only if the font (and language) support Kashidas. Use GetFontLanguageInfo to determine whether the current font supports Kashidas. Using Kashidas to justifiy the string can result in the number of glyphs required being greater than the number of characters in the input string. Because of this, when Kashidas are used, the application cannot assume that setting the arrays to be the size of the input string will be sufficient. (The maximum possible will be approximately dxPageWidth/dxAveCharWidth, where dxPageWidth is the width of the document and dxAveCharWidth is the average character width as returned from a GetTextMetrics call). Note that just because GetFontLanguageInfo returns the GCP_KASHIDA flag does not mean that it has to be used in the call to GetCharacterPlacement, just that the option is available.
GCP_LIGATE	Use ligations wherever characters ligate. A ligation occurs where one glyph is used for two or more characters. For example, the letters “a” and “e” can ligate to “æ”. For this to be used, however , both the language support and the font must support the required glyphs (the example given will NOT be processed by default in English).  Use GetFontLanguageInfo to determine whether the current font supports ligation. If it does and a specific maximum is required for the number of characters that will ligate, set the number in the first element of the lpGlyphs array. If normal ligation is required, set this value to zero. If GCP_LIGATE is not given, no ligation will take place. See GCP_RESULTS for more information. If the GCP_REORDER value is usually required for the character set but is not given, the output will be meaningless unless the string being passed in is already in visual ordering (that is, the result that gets put into lpGcpResults->lpOutString in one call to GetCharacterPlacement is the input string of a second call).  Note that just because GetFontLanguageInfo returns the GCP_LIGATE flag does not mean that it has to be used in the call to GetCharacterPlacement, just that the option is available.
GCP_MAXEXTENT	Compute extents of the string only as long as the resulting extent, in logical units, does not exceed the values given by the nMaxExtent parameter.
GCP_NEUTRALOVERRIDE	Certain languages only. Override the normal handling of neutrals and treat them as strong characters that match the strings reading order. Useful only with the GCP_REORDER flag.
GCP_NUMERICOVERRIDE	Certain languages only. Override the normal handling of numerics and treat them as strong characters that match the strings reading order. Useful only with the GCP_REORDER flag.
GCP_NUMERICSLATIN	Arabic/Thai only. Use standard Latin glyphs for numbers and override the system default. To determine if this option is available in the language of the font, use GetStringTypeEx to see if the language supports more than one number format.
GCP_NUMERICSLOCAL	Arabic/Thai only. Use local glyphs for numeric characters and override the system default. To determine if this option is available in the language of the font, use GetStringTypeEx to see if the language supports more than one number format.
GCP_REORDER	Reorder the string. Use for languages that are not SBCS and left-to-right reading order. If this value is not given, the string is assumed to be in display order already.  If this flag is set for Semitic languages and the lpClass array is used, the first two elements of the array are used to specify the reading order beyond the bounds of the string. GCP_CLASS_PREBOUNDRTL and GCP_CLASS_PREBOUNDLTR can be used to set the order. If no preset order is required, set the values to zero. These values can be combined with other values if theGCPCLASSIN flag is set. If the GCP_REORDER value is not given, the lpString parameter is taken to be visual ordered for languages where this is used, and the lpOutString and lpOrder fields are ignored. Use GetFontLanguageInfo to determine whether the current font supports reordering.
GCP_SYMSWAPOFF	Semitic languages only. Specifies that swappable characters are not reset. For example, in a right-to-left string, the ‘(‘ and ‘)’ are not reversed.
GCP_USEKERNING	Use kerning pairs in the font (if any) when creating the widths arrays. Use GetFontLanguageInfo to determine whether the current font supports kerning pairs. Note that just because GetFontLanguageInfo returns the GCP_USEKERNING flag does not mean that it has to be used in the call to GetCharacterPlacement, just that the option is available. Most TrueType fonts have a kerning table, but you do not have to use it.
It is recommended that an application use the GetFontLanguageInfo function to determine whether the GCP_DIACRITIC, GCP_DBCS, GCP_USEKERNING, GCP_LIGATE, GCP_REORDER, GCP_GLYPHSHAPE, and GCP_KASHIDA values are valid for the currently selected font. If not valid, GetCharacterPlacement ignores the value.

The GCP_NODIACRITICS value is no longer defined and should not be used.

Return Values

If the function succeeds, the return value is the same as the return value from GetTextExtentPoint32, the width and height of the string.

If the function fails, the return value is zero.

Remarks

GetCharacterPlacement ensures that an application can correctly process text regardless of the international setting and type of fonts available. Applications use this function before using the ExtTextOut function and in place of the GetTextExtentPoint32 function (and occasionally in place of the GetCharWidth32 and GetCharABCWidths functions).

Using GetCharacterPlacement to retrieve intercharacter spacing and index arrays is not always necessary unless justification or kerning is required. For non-Latin fonts, applications can improve the speed at which the ExtTextOut function renders text by using GetCharacterPlacement to retrieve the intercharacter spacing and index arrays before calling ExtTextOut. This is especially useful when rendering the same text repeatedly or when using intercharacter spacing to position the caret. If the lpGlyphs output array is used in the call to ExtTextOut, the ETO_GLYPH_INDEX flag must be set.

GetCharacterPlacement checks the lpOrder, lpDx, lpCaretPos, lpOutString, and lpGlyphs members of the GCP_RESULTS structure and fills the corresponding arrays if these members are not set to NULL. If GetCharacterPlacement cannot fill an array, it sets the corresponding member to NULL. To ensure retrieval of valid information, the application is responsible for setting the member to a valid address before calling the function and for checking the value of the member after the call. If the GCP_JUSTIFY or GCP_USEKERNING values are given, the lpDx and/or lpCaretPos members must have valid addresses. Also, the lpDx member must have a valid address if GCP_JUSTIFYIN is given.

When computing justification, if the trailing characters in the string are spaces, the function reduces the length of the string and removes the spaces prior to computing the justification. If the array consists of only spaces, the function returns an error.

See Also

ExtTextOut, GCP_RESULTS, GetCharABCWidths, GetCharWidth32, GetFontLanguageInfo, GetStringTypeEx, GetTextExtentPoint32, GetTextMetrics


GetCharWidth

The GetCharWidth function retrieves the widths, in logical coordinates, of consecutive characters in a specified range from the current font.

GetCharWidth is maintained for compatibility with 16-bit versions of Windows. Win32-based applications should call the GetCharWidth32 function, which provides more accurate results.

BOOL GetCharWidth(

HDC hdc,	// handle of device context
UINT iFirstChar,	// first character in range to query
UINT iLastChar,	// last character in range to query
LPINT lpBuffer	// address of buffer for widths
);
Parameters

hdc

Identifies the device context.

iFirstChar

Specifies the first character in the group of consecutive characters.

iLastChar

Specifies the last character in the group of consecutive characters, which must not precede the specified first character.

lpBuffer

Points to a buffer to receive the widths.

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.

Remarks

The range is inclusive; that is, the returned widths include the widths of the characters specified by the iFirstChar and iLastChar parameters.

If a character does not exist in the current font, it is assigned the width of the default character.

See Also

GetCharABCWidths, GetCharABCWidthsFloat, GetCharWidth32, GetCharWidthFloat


GetCharWidth32

The GetCharWidth32 function retrieves the widths, in logical coordinates, of consecutive characters in a specified range from the current font. This function supersedes the GetCharWidth function.

BOOL GetCharWidth32(

HDC hdc,	// handle of device context
UINT iFirstChar,	// first character in range to query
UINT iLastChar,	// last character in range to query
LPINT lpBuffer	// address of buffer for widths
);
Parameters

hdc

Identifies the device context.

iFirstChar

Specifies the first character in the group of consecutive characters.

iLastChar

Specifies the last character in the group of consecutive characters, which must not precede the specified first character.

lpBuffer

Points to a buffer to receive the widths.

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.

Remarks

The range is inclusive; that is, the returned widths include the widths of the characters specified by the iFirstChar and iLastChar parameters.

If a character does not exist in the current font, it is assigned the width of the default character.

See Also

GetCharABCWidths, GetCharABCWidthsFloat, GetCharWidth, GetCharWidthFloat


GetCharWidthFloat

The GetCharWidthFloat function retrieves the fractional widths of consecutive characters in a specified range from the current font.

BOOL GetCharWidthFloat(

HDC hdc,	// handle of device context
UINT iFirstChar,	// first-character code point
UINT iLastChar,	// last-character code point
PFLOAT pxBuffer	// address of buffer that receives width-values
);
Parameters

hdc

Identifies the device context.

iFirstChar

Specifies the code point of the first character in the group of consecutive characters.

iLastChar

Specifies the code point of the last character in the group of consecutive characters.

pxBuffer

Points to a buffer to receive the character widths.

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.

Remarks

The returned widths are in the 32-bit IEEE floating-point format. (The widths are measured along the base line of the characters.)

If the iFirstChar parameter identifies the letter a and the iLastChar parameter identifies the letter z, GetCharWidthFloat retrieves the widths of all lowercase characters.

If a character does not exist in the current font, it is assigned the width of the default character.

See Also

GetCharABCWidths, GetCharABCWidthsFloat, GetCharWidth32


GetClassInfo

The GetClassInfo function retrieves information about a window class.

The GetClassInfo function has been superseded by the GetClassInfoEx function. You can still use GetClassInfo, however, if you do not need information about the class small icon.

BOOL GetClassInfo(

HINSTANCE hInstance,	// handle of application instance
LPCTSTR lpClassName,	// address of class name string
LPWNDCLASS lpWndClass	// address of structure for class data
);
Parameters

hInstance

Identifies the instance of the application that created the class. To retrieve information about classes defined by Windows (such as buttons or list boxes), set this parameter to NULL.

lpClassName

Points to a null-terminated string containing the class name. The name must be that of a preregistered class or a class registered by a previous call to the RegisterClass function. Alternatively, this parameter can be an integer atom. If so, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value less than 0xC000, must be in the low-order word of lpClassName; the high-order word must be zero.

lpWndClass

Points to a WNDCLASS structure that receives the information about the class.

Return Values

If the function finds a matching class and successfully copies the data, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

GetClassInfoEx, GetClassLong, GetClassName, GetClassWord, GlobalAddAtom, RegisterClass, WNDCLASS


GetClassInfoEx

The GetClassInfoEx function retrieves information about a window class, including the handle of the small icon associated with the window class. The GetClassInfo function does not retrieve the handle of the small icon.

BOOL GetClassInfoEx(

HINSTANCE hinst,	// handle of application instance
LPCTSTR lpszClass,	// address of class name string
LPWNDCLASSEX lpwcx	// address of structure for class data
);
Parameters

hinst

Identifies the instance of the application that created the class. To retrieve information about classes defined by Windows (such as buttons or list boxes), set this parameter to NULL.

lpszClass

Points to a null-terminated string containing the class name. The name must be that of a preregistered class or a class registered by a previous call to the RegisterClass function. Alternatively, this parameter can be an integer atom. If this parameter is an integer atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value less than 0xC000, must be in the low-order word of lpszClass; the high-order word must be zero.

lpwcx

Points to a WNDCLASSEX structure that receives the information about the class.

Return Values

If the function finds a matching class and successfully copies the data, the return value is nonzero.

If the function does not find a matching class and successfully copy the data, the return value is zero. To get extended error information, call GetLastError.

See Also

GetClassLong, GetClassInfo, GetClassName, GetClassWord, GlobalAddAtom, RegisterClassEx


GetClassLong

The GetClassLong function retrieves the specified 32-bit (long) value from the WNDCLASS structure associated with the specified window.

DWORD GetClassLong(

HWND hWnd,	// handle of window
int nIndex	// offset of value to retrieve
);
Parameters

hWnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the 32-bit value to retrieve. To retrieve a 32-bit value from the extra class memory, specify the positive, zero-based byte offset of the value to be retrieved. Valid values are in the range zero through the number of bytes of extra class memory, minus four; for example, if you specified 12 or more bytes of extra class memory, a value of 8 would be an index to the third 32-bit integer. To retrieve any other value from the WNDCLASS structure, specify one of the following values:

Value	Action
GCW_ATOM	Retrieves an ATOM value that uniquely identifies the window class. This is the same atom that the RegisterClass function returns.
GCL_CBCLSEXTRA	Retrieves the size, in bytes, of the extra memory associated with the class.
GCL_CBWNDEXTRA	Retrieves the size, in bytes, of the extra window memory associated with each window in the class. For information on how to access this memory, see  GetWindowLong and GetWindowWord .
GCL_HBRBACKGROUND	Retrieves the handle of the background brush associated with the class.
GCL_HCURSOR	Retrieves the handle of the cursor associated with the class.
GCL_HICON	Retrieves the handle of the icon associated with the class.
GCL_HICONSM	Retrieves the handle of the small icon associated with the class.
GCL_HMODULE	Retrieves the handle of the module that registered the class.
GCL_MENUNAME	Retrieves the address of the menu name string. The string identifies the menu resource associated with the class.
GCL_STYLE	Retrieves the window-class style bits.
GCL_WNDPROC	Retrieves the address of the window procedure associated with the class.
Return Values

If the function succeeds, the return value is the requested 32-bit value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASS structure used with the RegisterClass function.

See Also

GetClassWord, GetWindowLong, GetWindowWord, RegisterClass, SetClassLong, SetClassWord, WNDCLASS


GetClassName

The GetClassName function retrieves the name of the class to which the specified window belongs.

int GetClassName(

HWND hWnd,	// handle of window
LPTSTR lpClassName,	// address of buffer for class name
int nMaxCount	// size of buffer, in characters
);
Parameters

hWnd

Identifies the window and, indirectly, the class to which the window belongs.

lpClassName

Points to the buffer that is to receive the class name string.

nMaxCount

Specifies the length, in characters, of the buffer pointed to by the lpClassName parameter. The class name string is truncated if it is longer than the buffer.

Return Values

If the function succeeds, the return value is the number of characters copied to the specified buffer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

FindWindow, GetClassInfo, GetClassLong, GetClassWord


GetClassWord

The GetClassWord function retrieves the 16-bit (word) value at the specified offset into the extra class memory for the window class to which the specified window belongs.

Other than GCW_ATOM and GCW_HICONSM, the GCW_ values are obsolete in the Win32 API. You must use the GetClassLong function to retrieve the class values of a window.

WORD GetClassWord(

HWND hWnd,	// handle of window
int nIndex	// offset of value to retrieve
);
Parameters

hWnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the zero-based byte offset of the value to be retrieved. Valid values are in the range zero through the number of bytes of class memory, minus two; for example, if you specified 10 or more bytes of extra class memory, a value of eight would be an index to the fifth 16-bit integer. There is an additional valid value:

Value	Action
GCW_ATOM	Retrieves an ATOM value that uniquely identifies the window class. This is the same atom that the RegisterClass function returns.
GCW_HICONSM	Retrieves the handle of the small icon associated with the window.
Return Values

If the function succeeds, the return value is the requested 16-bit value.

If the function fails, the return value is otherwise, it is zero. To get extended error information, call GetLastError.

Remarks

Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASS structure used with the RegisterClass function.

See Also

GetClassLong, RegisterClass, SetClassLong, SetClassWord, WNDCLASS


GetClientRect

The GetClientRect function retrieves the coordinates of a window’s client area. The client coordinates specify the upper-left and lower-right corners of the client area. Because client coordinates are relative to the upper-left corner of a window’s client area, the coordinates of the upper-left corner are (0,0).

BOOL GetClientRect(

HWND hWnd,	// handle of window
LPRECT lpRect	// address of structure for client coordinates
);
Parameters

hWnd

Identifies the window whose client coordinates are to be retrieved.

lpRect

Points to a RECT structure that receives the client coordinates. The left and top members are zero. The right and bottom members contain the width and height of the window.

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.

See Also

GetWindowRect, RECT


GetClipboardData

The GetClipboardData function retrieves data from the clipboard in a specified format. The clipboard must have been opened previously.

HANDLE GetClipboardData(

UINT uFormat	// clipboard format
);
Parameters

uFormat

Specifies a clipboard format. For a description of the clipboard formats, see the SetClipboardData function.

Return Values

If the function succeeds, the return value is the handle of a clipboard object in the specified format.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

An application can enumerate the available formats in advance by using the EnumClipboardFormats function.

The clipboard controls the handle that the GetClipboardData function returns, not the application. The application should copy the data immediately. The application cannot rely on being able to make long-term use of the handle. The application must not free the handle nor leave it locked.

The operating system performs implicit data format conversions between certain clipboard formats when an application calls the GetClipboardData function. For example, if the CF_OEMTEXT format is on the clipboard, a window can retrieve data in the CF_TEXT format. The format on the clipboard is converted to the requested format on demand. The following table shows the clipboard data type conversions that are available. Note that some of these automatic type conversions are not available on all platforms.

Clipboard Format	Conversion Format	Platform Support
CF_BITMAP	CF_DIB	Windows NT, Windows 95
CF_DIB	CF_BITMAP	Windows NT, Windows 95
CF_DIB	CF_PALETTE	Windows NT, Windows 95
CF_ENHMETAFILE	CF_METAFILEPICT	Windows NT, Windows 95
CF_METAFILEPICT	CF_ENHMETAFILE	Windows NT, Windows 95
CF_OEMTEXT	CF_TEXT	Windows NT, Windows 95
CF_OEMTEXT	CF_UNICODETEXT	Windows NT
CF_TEXT	CF_OEMTEXT	Windows NT, Windows 95
CF_TEXT	CF_UNICODETEXT	Windows NT
CF_UNICODETEXT	CF_OEMTEXT	Windows NT
CF_UNICODETEXT	CF_TEXT	Windows NT
If the operating system provides an automatic type conversion for a particular clipboard format, there is no advantage to placing the conversion format(s) on the clipboard.

If the system provides an automatic type conversion for a particular clipboard format, and you call EnumClipboardFormats to enumerate the clipboard data formats, the operating system first enumerates the format that is on the clipboard, followed by the formats to which it can be converted.

If the clipboard contains data in the CF_PALETTE format, the application should use the SelectPalette and RealizePalette functions to realize any other data in the clipboard against that logical palette.

See SetClipboardData for further information on specific clipboard data formats.

See Also

EnumClipboardFormats, SetClipboardData, RealizePalette, SelectPalette


GetClipboardFormatName

The GetClipboardFormatName function retrieves from the clipboard the name of the specified registered format. The function copies the name to the specified buffer.

int GetClipboardFormatName(

UINT format,	// clipboard format to retrieve
LPTSTR lpszFormatName,	// address of buffer for name
int cchMaxCount	// length of name string in characters
);
Parameters

format

Specifies the type of format to be retrieved. This parameter must not specify any of the predefined clipboard formats.

lpszFormatName

Points to the buffer that is to receive the format name.

cchMaxCount

Specifies the maximum length, in characters, of the string to be copied to the buffer. If the name exceeds this limit, it is truncated.

Return Values

If the function succeeds, the return value is the length, in characters, of the string copied to the buffer.

If the function fails, the return value is zero, indicating that the requested format does not exist or is predefined. To get extended error information, call GetLastError.

See Also

EnumClipboardFormats, RegisterClipboardFormat


GetClipboardOwner

The GetClipboardOwner function retrieves the window handle of the current owner of the clipboard.

HWND GetClipboardOwner(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the handle of the window that owns the clipboard.

If the clipboard is not owned, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The clipboard can still contain data even if the clipboard is not currently owned.

In general, the clipboard owner is the window that last placed data in clipboard. The EmptyClipboard function assigns clipboard ownership.

See Also

EmptyClipboard, GetClipboardViewer


GetClipboardViewer

The GetClipboardViewer function retrieves the handle of the first window in the clipboard viewer chain.

HWND GetClipboardViewer(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the handle of the first window in the clipboard viewer chain.

If there is no clipboard viewer, the return value is NULL. To get extended error information, call GetLastError.

See Also

GetClipboardOwner, SetClipboardViewer


GetClipBox

The GetClipBox function retrieves the dimensions of the tightest bounding rectangle that can be drawn around the current visible area on the device. The visible area is defined by the current clipping region or clip path, as well as any overlapping windows.

int GetClipBox(

HDC hdc,	// handle of the device context
LPRECT lprc	// address of structure with rectangle
);
Parameters

hdc

Identifies the device context.

lprc

Points to a RECT structure that is to receive the rectangle dimensions.

Return Values

If the function succeeds, the return value specifies the clipping box’s complexity and can be any one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
ERROR	An error occurred.
GetClipBox returns logical coordinates based on the given device context.

See Also

RECT


GetClipCursor

The GetClipCursor function retrieves the screen coordinates of the rectangular area to which the cursor is confined.

BOOL GetClipCursor(

LPRECT lpRect	// address of structure for rectangle
);
Parameters

lpRect

Points to a RECT structure that receives the screen coordinates of the confining rectangle. The structure receives the dimensions of the screen if the cursor is not confined to a rectangle.

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.

Remarks

The cursor is a shared resource. If an application confines the cursor with the ClipCursor function, it must later release the cursor by using ClipCursor before relinquishing control to another application.

The calling process must have WINSTA_READATTRIBUTES access to the window station.

See Also

ClipCursor, GetCursorPos, RECT


GetClipRgn

The GetClipRgn function retrieves a handle identifying the current application-defined clipping region for the specified device context.

int GetClipRgn(

HDC hdc,	// handle of device context
HRGN hrgn	// handle of region
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies an existing region before the function is called. After the function returns, this parameter identifies a copy of the current clipping region.

Return Values

If the function succeeds and there is no clipping region for the given device context, the return value is zero. If the function succeeds and there is a clipping region for the given device context, the return value is 1. If an error occurs, the return value is − 1.

Remarks

An application-defined clipping region is a clipping region identified by the SelectClipRgn function. It is not a clipping region created when the application calls the BeginPaint function.

If the function succeeds, the hrgn parameter identifies a copy of the current clipping region. Subsequent changes to this copy will not affect the current clipping region.

See Also

BeginPaint, SelectClipRgn


GetColorAdjustment

The GetColorAdjustment function retrieves the color adjustment values for the specified device context.

BOOL GetColorAdjustment(

HDC hdc,	// handle of device context
LPCOLORADJUSTMENT lpca	// address of COLORADJUSTMENT structure
);
Parameters

hdc

Identifies the device context.

lpca

Points to a COLORADJUSTMENT structure that receives the color adjustment values.

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.

See Also

SetColorAdjustment, COLORADJUSTMENT


GetColorSpace

The GetColorSpace function retrieves the current handle to the logical color space from the specified device context.

HANDLE GetColorSpace(

HDC hdc
);
Parameters

hdc

Handle to a device context.

Return Values

If the function succeeds, the return value is the current handle to the logical color space.

If the function fails, the return value is NULL.

See Also

SetColorSpace


GetCommandLine

The GetCommandLine function returns a pointer to the command-line string for the current process.

LPTSTR GetCommandLine(VOID)

Parameters

This function has no parameters.

Return Values

The return value is a pointer to the command-line string for the current process.

Remarks

Non-Unicode console processes written in C can use the argc and argv arguments to access the command-line arguments. The parameters of the command-line string, excluding the program name, are also available to such non-Unicode applications as a parameter of the WinMain function. The reason for the Unicode exclusion from these options is that WinMain, argc, and argv use the LPSTR data type for parameters, not the LPTSTR datatype.

See Also

CreateProcess, WinMain


GetCommConfig [Now Supported on Windows NT]
GetCommConfig

[Now Supported on Windows NT]

The GetCommConfig function gets the current configuration of a communications device.

BOOL GetCommConfig(

HANDLE hCommDev,	// handle of communications service
LPCOMMCONFIG lpCC,	// address of comm.configuration structure
LPDWORD lpdwSize	// address of size of buffer
);
Parameters

hCommDev

Identifies the open communications device.

lpCC

Points to the buffer that receives the COMMCONFIG structure.

lpdwSize

Points to a 32-bit variable that specifies the size, in bytes, of the buffer pointed to by lpCC. When the function returns, the variable contains the number of bytes copied if the function succeeds, or the number of bytes required if the buffer was too small.

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, use the GetLastError function.

See Also

SetCommConfig, COMMCONFIG


GetCommMask

The GetCommMask function retrieves the value of the event mask for a specified communications device.

BOOL GetCommMask(

HANDLE hFile,	// handle of communications device
LPDWORD lpEvtMask	// address of variable to get event mask
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

lpEvtMask

Points to the 32-bit variable to be filled with a mask of events that are currently enabled. This parameter can be one or more of the following values:

Value	Meaning
EV_BREAK	A break was detected on input.
EV_CTS	The CTS (clear-to-send) signal changed state.
EV_DSR	The DSR (data-set-ready) signal changed state.
EV_ERR	A line-status error occurred. Line-status errors are CE_FRAME, CE_OVERRUN, and CE_RXPARITY.
EV_EVENT1	An event of the first provider-specific type occured.
EV_EVENT2	An event of the second provider-specific type occured.
EV_PERR	A printer error occured.
EV_RING	A ring indicator was detected.
EV_RLSD	The RLSD (receive-line-signal-detect) signal changed state.
EV_RX80FULL	The receive buffer is 80 percent full.
EV_RXCHAR	A character was received and placed in the input buffer.
EV_RXFLAG	The event character was received and placed in the input buffer. The event character is specified in the device’s DCB structure, which is applied to a serial port by using the SetCommState function.
EV_TXEMPTY	The last character in the output buffer was sent.
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.

Remarks

The GetCommMask function uses a 32-bit mask variable to indicate the set of events that can be monitored for a particular communications resource. A handle to the communications resource can be specified in a call to the WaitCommEvent function, which waits for one of the events to occur. To modify the event mask of a communications resource, use the SetCommMask function.

See Also

CreateFile, DCB, SetCommMask, WaitCommEvent,


GetCommModemStatus

The GetCommModemStatus function retrieves modem control-register values.

BOOL GetCommModemStatus(

HANDLE hFile,	// handle of communications device
LPDWORD lpModemStat	// address of control-register values
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

lpModemStat

Points to a 32-bit variable that specifies the current state of the modem control-register values. This parameter can be a combination of the following values:

Value	Meaning
MS_CTS_ON	The CTS (clear-to-send) signal is on.
MS_DSR_ON	The DSR (data-set-ready) signal is on.
MS_RING_ON	The ring indicator signal is on.
MS_RLSD_ON	The RLSD (receive-line-signal-detect) signal is on.
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.

Remarks

The GetCommModemStatus function is useful when you are using the WaitCommEvent function to monitor the CTS, RLSD, DSR, or ring indicator signals. To detect when these signals change state, use WaitCommEvent and then use GetCommModemStatus to determine the state after a change occurs.

The function fails if the hardware does not support the control-register values.

See Also

CreateFile, WaitCommEvent


GetCommProperties

The GetCommProperties function fills a buffer with information about the communications properties for a specified communications device.

BOOL GetCommProperties(

HANDLE hFile,	// handle of communications device
LPCOMMPROP lpCommProp	// address of communications properties structure
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

lpCommProp

Points to a COMMPROP structure in which the communications properties information is returned. This information can be used in subsequent calls to the SetCommState, SetCommTimeouts, or SetupComm function to configure the communications device.

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.

Remarks

The GetCommProperties function returns information from a device driver about the configuration settings that are supported by the driver.

See Also

COMMPROP, CreateFile, SetCommState, SetCommTimeouts, SetupComm


GetCommState

The GetCommState function fills in a device-control block (a DCB structure) with the current control settings for a specified communications device.

BOOL GetCommState(

HANDLE hFile,	// handle of communications device
LPDCB lpDCB	// address of device-control block structure
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

lpDCB

Points to the DCB structure in which the control settings information is returned.

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.

See Also

CreateFile, DCB, SetCommState


GetCommTimeouts

The GetCommTimeouts function retrieves the time-out parameters for all read and write operations on a specified communications device.

BOOL GetCommTimeouts(

HANDLE hFile,	// handle of communications device
LPCOMMTIMEOUTS lpCommTimeouts	// address of comm. time-outs structure
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

lpCommTimeouts

Points to a COMMTIMEOUTS structure in which the time-out information is returned.

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.

Remarks

For more information about time-out values for communications devices, see the SetCommTimeouts function.

See Also

CreateFile, COMMTIMEOUTS, SetCommTimeouts


GetCompressedFileSize

The GetCompressedFileSize function obtains the compressed size, in bytes, of a specified file.

The GetCompressedFileSize function obtains the actual number of bytes of disk storage used to store a specified file. If the file is located on a volume that supports compression, and the file is compressed, the value obtained is the compressed size of the specified file. If the file is not located on a volume that supports compression, or if the file is not compressed, the value obtained is the actual file size, the same as the value returned by a call to GetFileSize.

DWORD GetCompressedFileSize(

LPCTSTR lpFileName,	// pointer to name of file
LPDWORD lpFileSizeHigh	// pointer to DWORD to receive high-order doubleword of file size
);
Parameters

lpFileName

Pointer to a null-terminated string that specifies the name of the file.

lpFileSizeHigh

Pointer to a DWORD variable that the function sets to the high-order doubleword of the compressed file size. The function’s return value is the low-order doubleword of the compressed file size.

This parameter can be NULL if the high-order doubleword of the compressed file size is not needed. Files less than 4 gigabytes in size do not need the high-order doubleword.

Return Values

If the function succeeds, the return value is the low-order doubleword of the actual number of bytes of disk storage used to store the specified file, and if lpFileSizeHigh is non-NULL, the function puts the high-order doubleword of that actual value into the DWORD pointed to by that parameter. This is the compressed file size for compressed files, the actual file size for noncompressed files.

If the function fails, and lpFileSizeHigh is NULL, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

If the function fails, and lpFileSizeHigh is non-NULL, the return value is 0xFFFFFFFF, and GetLastError returns a value other than NO_ERROR.

Remarks

Calling the GetCompressedFileSize function with the name of a nonseeking device, such as a pipe or a communications device, has no meaning.

Note that if the return value is 0xFFFFFFFF and lpFileSizeHigh is non-NULL, an application must call GetLastError to determine whether the function has succeeded or failed.

An application can determine whether a volume is compressed by calling GetVolumeInformation, then checking the status of the FS_VOL_IS_COMPRESSED flag in the DWORD pointed to by that function’s lpFileSystemFlags parameter.

An application can determine whether a file is compressed by implementing the following pseudocode:

call GetVolumeInformation on the file's volume

if the file's volume is compressed

    call GetCompressedFileSize on the file

    call GetFileSize on the file

    if the sizes don't match

        the file is compressed

See Also

GetFileSize, GetVolumeInformation


GetComputerName

The GetComputerName function retrieves the computer name of the current system. This name is established at system startup, when it is initialized from the registry.

BOOL GetComputerName(

LPTSTR lpBuffer,	// address of name buffer
LPDWORD nSize	// address of size of name buffer
);
Parameters

lpBuffer

Points to a buffer to receive the null-terminated character string containing the computer name.

nSize

Points to a variable that specifies the maximum size, in characters, of the buffer. This value should be large enough to contain MAX_COMPUTERNAME_LENGTH + 1 characters.

Return Values

If the function succeeds, the return value is nonzero and the variable represented by the nSize parameter contains the number of characters copied to the destination buffer, not including the terminating null character.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

SetComputerName


GetConsoleCP

Windows NT: The GetConsoleCP function returns the identity of the input code page used by the console associated with the calling process. A console uses its input code page to translate keyboard input into the corresponding character value.

Windows 95: On Japanese and Korean implementations of Windows 95, the GetConsoleCP function returns the VM code page, because the OEM code page can be either 437 or DBCS. On all other implementations of Windows 95, the GetConsoleCP function returns the OEM code page.

UINT GetConsoleCP(VOID)

Parameters

This function has no parameters.

Return Values

The return value is a code that identifies the code page.

Remarks

A code page maps 256 character codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages.

To set a console’s input code page, use the SetConsoleCP function. To set and query a console’s output code page, use the SetConsoleOutputCP and GetConsoleOutputCP functions.

See Also

GetConsoleOutputCP, SetConsoleCP, SetConsoleOutputCP


GetConsoleCursorInfo

The GetConsoleCursorInfo function retrieves information about the size and visibility of the cursor for the specified console screen buffer.

BOOL GetConsoleCursorInfo(

HANDLE hConsoleOutput,	// handle of console screen buffer
PCONSOLE_CURSOR_INFO lpConsoleCursorInfo	// address of cursor information
);
Parameters

hConsoleOutput

Identifies a console screen buffer. The handle must have GENERIC_READ access.

lpConsoleCursorInfo

Points to a CONSOLE_CURSOR_INFO structure in which information about the console’s cursor is returned.

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.

See Also

CONSOLE_CURSOR_INFO, SetConsoleCursorInfo


GetConsoleMode

The GetConsoleMode function reports the current input mode of a console’s input buffer or the current output mode of a console screen buffer.

BOOL GetConsoleMode(

HANDLE hConsoleHandle,	// handle of console input or screen buffer
LPDWORD lpMode	// current mode flags
);
Parameters

hConsoleHandle

Identifies a console input buffer or a screen buffer. The handle must have GENERIC_READ access.

lpMode

Points to a 32-bit variable that indicates the current mode of the specified buffer.

If the hConsoleHandle parameter is an input handle, the mode can be a combination of the following values. When a console is created, all input modes except ENABLE_WINDOW_INPUT are enabled by default.

Value	Meaning
ENABLE_LINE_INPUT	The ReadFile or ReadConsole function returns only when a carriage return character is read. If this mode is disabled, the functions return when one or more characters are available.
ENABLE_ECHO_INPUT	Characters read by the ReadFile or ReadConsole function are written to the active screen buffer as they are read. This mode can be used only if the ENABLE_LINE_INPUT mode is also enabled.
ENABLE_PROCESSED_INPUT	CTRL+C is processed by the system and is not placed in the input buffer. If the input buffer is being read by ReadFile or ReadConsole, other control keys are processed by the system and are not returned in the ReadFile or ReadConsole buffer. If the ENABLE_LINE_INPUT mode is also enabled, backspace, carriage return, and linefeed characters are handled by the system.
ENABLE_WINDOW_INPUT	User interactions that change the size of the console screen buffer are reported in the console’s input buffer. Information about these events can be read from the input buffer by applications using the ReadConsoleInput function, but not by those using ReadFile or ReadConsole.
ENABLE_MOUSE_INPUT	If the mouse pointer is within the borders of the console window and the window has the keyboard focus, mouse events generated by mouse movement and button presses are placed in the input buffer. These events are discarded by ReadFile or ReadConsole, even when this mode is enabled.
If the hConsoleHandle parameter is a screen buffer handle, the mode can be a combination of the following values. When a screen buffer is created, both output modes are enabled by default.

Value	Meaning
ENABLE_PROCESSED_OUTPUT	Characters written by the WriteFile or WriteConsole function or echoed by the ReadFile or ReadConsole function are parsed for ASCII control sequences, and the correct action is performed. Backspace, tab, bell, carriage return, and linefeed characters are processed.
ENABLE_WRAP_AT_EOL_OUTPUT	When writing with WriteFile or WriteConsole or echoing with ReadFile or ReadConsole, the cursor moves to the beginning of the next row when it reaches the end of the current row. This causes the rows displayed in the console window to scroll up automatically when the cursor advances beyond the last row in the window. It also causes the contents of the screen buffer to scroll up (discarding the top row of the screen buffer) when the cursor advances beyond the last row in the screen buffer. If this mode is disabled, the last character in the row is overwritten with any subsequent characters.
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.

Remarks

A console consists of an input buffer and one or more screen buffers. The mode of a console buffer determines how the console behaves during input or output (I/O) operations. One set of flag constants is used with input handles, and another set is used with screen buffer (output) handles. Setting the output modes of one screen buffer does not affect the output modes of other screen buffers.

The ENABLE_LINE_INPUT and ENABLE_ECHO_INPUT modes only affect processes that use ReadFile or ReadConsole to read from the console’s input buffer. Similarly, the ENABLE_PROCESSED_INPUT mode primarily affects ReadFile and ReadConsole users, except that it also determines whether CTRL+C input is reported in the input buffer (to be read by the ReadConsoleInput function) or is passed to a function defined by the application.

The ENABLE_WINDOW_INPUT and ENABLE_MOUSE_INPUT modes determine whether user interactions involving window resizing and mouse actions are reported in the input buffer or discarded. These events can be read by ReadConsoleInput, but they are always filtered by ReadFile and ReadConsole.

The ENABLE_PROCESSED_OUTPUT and ENABLE_WRAP_AT_EOL_OUTPUT modes only affect processes using ReadFile or ReadConsole and WriteFile or WriteConsole.

To change a console’s I/O modes, call SetConsoleMode function.

See Also

ReadConsole, ReadConsoleInput, ReadFile, SetConsoleMode, WriteConsole, WriteFile


GetConsoleOutputCP

Windows NT: The GetConsoleOutputCP function returns the identity of the output code page used by the console associated with the calling process. A console uses its output code page to translate the character values written by the various output functions into the images displayed in the console window.

Windows 95: On Japanese and Korean implementations of Windows 95, the GetConsoleOutputCP function returns the VM code page, because the OEM code page can be either 437 or DBCS. On all other implementations of Windows 95, the GetConsoleOutputCP function returns the OEM code page.

UINT GetConsoleOutputCP(VOID)

Parameters

This function has no parameters.

Return Values

The return value is a code that identifies the code page.

Remarks

A code page maps 256 character codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages.

To set a console’s output code page, use the SetConsoleOutputCP function. To set and query a console’s input code page, use the SetConsoleCP and GetConsoleCP functions.

See Also

GetConsoleCP, SetConsoleCP, SetConsoleOutputCP


GetConsoleScreenBufferInfo

The GetConsoleScreenBufferInfo function retrieves information about the specified console screen buffer.

BOOL GetConsoleScreenBufferInfo(

HANDLE hConsoleOutput,	// handle of console screen buffer
PCONSOLE_SCREEN_BUFFER_INFO lpConsoleScreenBufferInfo	// address of screen buffer info.
);
Parameters

hConsoleOutput

Identifies a console screen buffer. The handle must have GENERIC_READ access.

lpConsoleScreenBufferInfo

Points to a CONSOLE_SCREEN_BUFFER_INFO structure in which the screen buffer information is returned.

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.

Remarks

The rectangle returned in the srWindow member of the CONSOLE_SCREEN_BUFFER_INFO structure can be modified and then passed to the SetConsoleWindowInfo function to scroll the screen buffer in the window, to change the size of the window, or both.

All coordinates returned in the CONSOLE_SCREEN_BUFFER_INFO structure are in character-cell coordinates, where the origin (0, 0) is at the upper-left corner of the screen buffer.

See Also

CONSOLE_SCREEN_BUFFER_INFO, GetLargestConsoleWindowSize, SetConsoleCursorPosition, SetConsoleScreenBufferSize, SetConsoleWindowInfo


GetConsoleTitle

The GetConsoleTitle function retrieves the title bar string for the current console window.

DWORD GetConsoleTitle(

LPTSTR lpConsoleTitle,	// address of buffer for title
DWORD nSize	// size of the buffer
);
Parameters

lpConsoleTitle

Points to a buffer that receives a null-terminated string containing the text that appears in the title bar of the console window.

nSize

Specifies the size, in characters, of the buffer pointed to by the lpConsoleTitle parameter.

Return Values

If the function succeeds, the return value is the length, in characters, of the string copied to the buffer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

To set the title bar string for a console window, use the SetConsoleTitle function.

Windows NT: This function uses either Unicode characters or 8-bit characters from the console's current codepage. The console's codepage defaults initially to the system's OEM codepage. To change the console's codepage, use the SetConsoleCP or SetConsoleOutputCP functions, or use the chcp or mode con cp select= commands.

See Also

SetConsoleCP, SetConsoleOutputCP, SetConsoleTitle


GetCPInfo

The GetCPInfo function retrieves information about any valid installed or available code page.

BOOL GetCPInfo(

UINT CodePage,	// code page identifier
LPCPINFO lpCPInfo	// address of structure for information
);
Parameters

CodePage

Specifies the code page about which information is to be retrieved. You can specify the code page identifier for any installed or available code page, or you can specify one of the following predefined values:

Value	Meaning
CP_ACP	Use the system default ANSI code page
CP_MACCP	Use the system default Macintosh code page
CP_OEMCP	Use the system default OEM code page
lpCPInfo

Points to a CPINFO structure that receives information about the code page.

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 .

Remarks

If the specified code page is not installed or not available, GetCPInfo sets the last-error value to ERROR_INVALID_PARAMETER.

See Also

GetACP, GetOEMCP, CPINFO


GetCurrencyFormat

The GetCurrencyFormat function formats a number string as a currency string for a specified locale.

int GetCurrencyFormat(

LCID Locale,	// locale for which currency string is to be formatted
DWORD dwFlags,	// bit flag that controls the function’s operation
LPCTSTR lpValue,	// pointer to input number string
CONST CURRENCYFMT *lpFormat,	// pointer to a formatting information structure
LPTSTR lpCurrencyStr,	// pointer to output buffer
int cchCurrency	// size of output buffer
);
Parameters

Locale

Specifies the locale for which the currency string is to be formatted. If lpFormat is NULL, the function formats the string according to the currency format for this locale. If lpFormat is not NULL, the function uses the locale only for formatting information not specified in the CURRENCYFMT structure (for example, the locale’s string value for the negative sign).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
dwFlags

A bit flag that controls the operation of the function. If lpFormat is non-NULL, this parameter must be zero.

If lpFormat is NULL, you can specify the LOCALE_NOUSEROVERRIDE flag to format the string using the system default currency format for the specified locale; or you can specify zero to format the string using any user overrides to the locale’s default currency format.

lpValue

Points to a null-terminated string containing the number string to format.

This string can contain only the following characters:

•	Characters ‘0’ through ‘9’

•	One decimal point (dot) if the number is a floating-point value

•	A minus sign in the first character position if the number is a negative value

All other characters are invalid. The function returns an error if the string pointed to by lpValue deviates from these rules.

lpFormat

Pointer to a CURRENCYFMT structure that contains currency formatting information. All members in the structure pointed to by lpFormat must contain appropriate values.

If lpFormat is NULL, the function uses the currency format of the specified locale.

lpCurrencyStr

Points to a buffer to receive the formatted currency string.

cchCurrency

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the lpCurrencyStr buffer. If cchCurrency is zero, the function returns the number of bytes or characters required to hold the formatted currency string, and the buffer pointed to by lpCurrencyStr is not used.

Return Values

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) written to the buffer pointed to by lpCurrencyStr, or if the cchCurrency parameter is zero, the number of bytes or characters required to hold the formatted currency string.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID FLAGS
ERROR_INVALID_PARAMETER

See Also

GetNumberFormat, CURRENCYFMT


GetCurrentDirectory

The GetCurrentDirectory function retrieves the current directory for the current process.

DWORD GetCurrentDirectory(

DWORD nBufferLength,	// size, in characters, of directory buffer
LPTSTR lpBuffer	// address of buffer for current directory
);
Parameters

nBufferLength

Specifies the length, in characters, of the buffer for the current directory string. The buffer length must include room for a terminating null character.

lpBuffer

Points to the buffer for the current directory string. This null-terminated string specifies the absolute path to the current directory.

Return Values

If the function succeeds, the return value specifies the number of characters written to the buffer, not including the terminating null character.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

If the buffer pointed to by lpBuffer is not large enough, the return value specifies the required size of the buffer, including the number of bytes necessary for a terminating null character.

See Also

CreateDirectory, GetSystemDirectory, GetWindowsDirectory, RemoveDirectory, SetCurrentDirectory


GetCurrentFiber

The GetCurrentFiber function returns the address of the current fiber.

PVOID GetCurrentFiber(VOID)

Parameters

This function has no parameters.

Return Values

The return value is the address of the currently running fiber.

Remarks

The CreateFiber and ConvertThreadToFiber functions return the fiber address when the fiber is created. The GetCurrentFiber function allows you to retrieve the address at any other time.

See Also

CreateFiber, ConvertThreadToFiber


GetCurrentHwProfile [New - Windows NT]
GetCurrentHwProfile

[New - Windows NT]

The GetCurrentHwProfile function retrieves information about the current hardware profile for the local computer.

BOOL GetCurrentHwProfile(

LPHW_PROFILE_INFO lpHwProfileInfo	// receives the hardware profile information
);
Parameters

lpHwProfileInfo

Pointer to an HW_PROFILE_INFO structure in which the function returns information about the current hardware profile.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The GetCurrentHwProfile function retrieves the display name and globally unique identifier (GUID) string for the hardware profile. The function also retrieves the reported docking state for portable computers with docking stations.

The system generates a GUID for each hardware profile and stores it as a string in the registry. You can use GetCurrentHwProfile to retrieve the GUID string to use as a registry subkey under your application's configuration settings key in HKEY_CURRENT_USER. This enables you to store each user's settings for each hardware profile. For example, the Colors control panel application could use the subkey to store each user's color preferences for different hardware profiles, such as profiles for the docked and undocked states. Applications that use this functionality can check the current hardware profile when they start up, and update their settings accordingly.

Windows 95: Applications can also update their settings when a system device message, such as DBT_CONFIGCHANGED, indicates that the hardware profile has changed.

Example

#include <windows.h>

#include <stdio.h>

#include <tchar.h>

void main(void) {

   HW_PROFILE_INFO   HwProfInfo;

   if (!GetCurrentHwProfile(&HwProfInfo)) {

      _tprintf(TEXT("GetCurrentHwProfile failed with error %lx\n"),

                 GetLastError());

      return;

   }

   _tprintf(TEXT("DockInfo = %d\n"), HwProfInfo.dwDockInfo);

   _tprintf(TEXT("Profile Guid = %s\n"), HwProfInfo.szHwProfileGuid);

   _tprintf(TEXT("Friendly Name = %s\n"), HwProfInfo.szHwProfileName);

} // main

See Also

DBT_CONFIGCHANGED, HW_PROFILE_INFO


GetCurrentObject

The GetCurrentObject function returns the currently selected object of the specified type.

HGDIOBJ GetCurrentObject(

HDC hdc,	// handle of device context
UINT uObjectType	// object-type identifier
);
Parameters

hdc

Identifies the device context.

uObjectType

Specifies the object type to be queried. This parameter can be one of the following values:

Value	Meaning
OBJ_PEN	Returns the current selected pen.
OBJ_BRUSH	Returns the current selected brush.
OBJ_PAL	Returns the current selected palette.
OBJ_FONT	Returns the current selected font.
OBJ_BITMAP	Returns the current selected bitmap if hdc is a memory device context.
Return Values

If the function succeeds, the return value is the handle of the specified object.

If the function fails, the return value is NULL.

Remarks

An application can use the GetCurrentObject and GetObject functions to retrieve descriptions of the graphic objects currently selected into the given device context.

See Also

DeleteObject, GetObject, SelectObject


GetCurrentPositionEx

The GetCurrentPositionEx function retrieves the current position in logical coordinates.

BOOL GetCurrentPositionEx(

HDC hdc,	// handle of device context
LPPOINT lpPoint	// address of structure receiving current position
);
Parameters

hdc

Identifies the device context.

lpPoint

Points to a POINT structure that receives the coordinates of the current position.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

MoveToEx, POINT


GetCurrentProcess

The GetCurrentProcess function returns a pseudohandle for the current process.

HANDLE GetCurrentProcess(VOID)

Parameters

This function has no parameters.

Return Values

The return value is a pseudohandle to the current process.

Remarks

A pseudohandle is a special constant that is interpreted as the current process handle. The calling process can use this handle to specify its own process whenever a process handle is required. Pseudohandles are not inherited by child processes.

This handle has the maximum possible access to the process object. For systems that support security descriptors, this is the maximum access allowed by the security descriptor for the calling process. For systems that do not support security descriptors, this is PROCESS_ALL_ACCESS. For more information, see Process Objects.

A process can create a “real” handle to itself that is valid in the context of other processes, or that can be inherited by other processes, by specifying the pseudohandle as the source handle in a call to the DuplicateHandle function. A process can also use the OpenProcess function to open a real handle to itself.

The pseudohandle need not be closed when it is no longer needed. Calling the CloseHandle function with a pseudohandle has no effect. If the pseudohandle is duplicated by DuplicateHandle, the duplicate handle must be closed.

See Also

CloseHandle, DuplicateHandle, GetCurrentProcessId, GetCurrentThread, OpenProcess


GetCurrentProcessId

The GetCurrentProcessId function returns the process identifier of the calling process.

DWORD GetCurrentProcessId(VOID)

Parameters

This function has no parameters.

Return Values

The return value is the process identifier of the calling process.

Remarks

Until the process terminates, the process identifier uniquely identifies the process throughout the system.

See Also

GetCurrentProcess, OpenProcess


GetCurrentThread

The GetCurrentThread function returns a pseudohandle for the current thread.

HANDLE GetCurrentThread(VOID)

Parameters

This function has no parameters.

Return Values

The return value is a pseudohandle for the current thread.

Remarks

A pseudohandle is a special constant that is interpreted as the current thread handle. The calling thread can use this handle to specify itself whenever a thread handle is required. Pseudohandles are not inherited by child processes.

This handle has the maximum possible access to the thread object. For systems that support security descriptors, this is the maximum access allowed by the security descriptor for the calling process. For systems that do not support security descriptors, this is THREAD_ALL_ACCESS.

The function cannot be used by one thread to create a handle that can be used by other threads to refer to the first thread. The handle is always interpreted as referring to the thread that is using it. A thread can create a “real” handle of itself that can be used by other threads, or inherited by other processes, by specifying the pseudohandle as the source handle in a call to the DuplicateHandle function.

The pseudohandle need not be closed when it is no longer needed. Calling the CloseHandle function with this handle has no effect. If the pseudohandle is duplicated by DuplicateHandle, the duplicate handle must be closed.

See Also

CloseHandle, DuplicateHandle, GetCurrentProcess, GetCurrentThreadId


GetCurrentThreadId

The GetCurrentThreadId function returns the thread identifier of the calling thread.

DWORD GetCurrentThreadId(VOID)

Parameters

This function has no parameters.

Return Values

The return value is the thread identifier of the calling thread.

Remarks

Until the thread terminates, the thread identifier uniquely identifies the thread throughout the system.

See Also

GetCurrentThread


GetCurrentTime

The GetCurrentTime is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the GetTickCount function or look up the System Up Time counter in the performance data in the registry key HKEY_PERFORMANCE_DATA.


GetCursor

The GetCursor function retrieves the handle of the current cursor.

HCURSOR GetCursor(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the handle of the current cursor.

If there is no cursor, the return value is NULL.

See Also

SetCursor


GetCursorPos

The GetCursorPos function retrieves the cursor’s position, in screen coordinates.

BOOL GetCursorPos(

LPPOINT lpPoint	// address of structure for cursor position
);
Parameters

lpPoint

Points to a POINT structure that receives the screen coordinates of the cursor.

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.

Remarks

The cursor position is always given in screen coordinates and is not affected by the mapping mode of the window that contains the cursor.

The calling process must have WINSTA_READATTRIBUTES access to the window station.

See Also

ClipCursor, POINT, SetCursor, SetCursorPos, ShowCursor


GetDateFormat

The GetDateFormat function formats a date as a date string for a specified locale. The function formats either a specified date or the local system date.

int GetDateFormat(

LCID Locale,	// locale for which date is to be formatted
DWORD dwFlags,	// flags specifying function options
CONST SYSTEMTIME *lpDate,	// date to be formatted
LPCTSTR lpFormat,	// date format string
LPTSTR lpDateStr,	// buffer for storing formatted string
int cchDate	// size of buffer
);
Parameters

Locale

Specifies the locale for which the date string is to be formatted. If lpFormat is NULL, the function formats the string according to the date format for this locale. If lpFormat is not NULL, the function uses the locale only for information not specified in the format picture string (for example, the locale’s day and month names).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
dwFlags

A set of bit flags that specify various function options. If lpFormat is non-NULL, this parameter must be zero.

If lpFormat is NULL, you can specify a combination of the following flags:

Flag	Meaning
LOCALE_NOUSEROVERRIDE	If set, the function formats the string using the system default date format for the specified locale. If not set, the function formats the string using any user overrides to the locale’s default date format.
DATE_SHORTDATE	Use the short date format. This is the default. Cannot be used with DATE_LONGDATE.
DATE_LONGDATE	Use the long date format. Cannot be used with DATE_SHORTDATE.
DATE_USE_ALT_CALENDAR	Use the alternate calendar, if one exists, to format the date string. If this flag is set, the function uses the default format for that alternate calendar, rather than using any user overrides. The user overrides will be used only in the event that there is no default format for the specified alternate calendar.
lpDate

Pointer to a SYSTEMTIME structure that contains the date information to be formatted. If this pointer is NULL, the function uses the current local system date.

lpFormat

Pointer to a format picture string to use to form the date string. If lpFormat is NULL, the function uses the date format of the specified locale.

Use the following elements to construct a format picture string. If you use spaces to separate the elements in the format string, these spaces will appear in the same location in the output string. The letters must be in uppercase or lowercase as shown in the table (for example, “MM” not “mm”). Characters in the format string that are enclosed in single quotation marks will appear in the same location and unchanged in the output string.

Picture	Meaning
d	Day of month as digits with no leading zero for single-digit days.
dd	Day of month as digits with leading zero for single-digit days.
ddd	Day of week as a three-letter abbreviation. The function uses the LOCALE_SABBREVDAYNAME value associated with the specified locale.
dddd	Day of week as its full name. The function uses the LOCALE_SDAYNAME value associated with the specified locale.
M	Month as digits with no leading zero for single-digit months.
MM	Month as digits with leading zero for single-digit months.
MMM	Month as a three-letter abbreviation. The function uses the LOCALE_SABBREVMONTHNAME value associated with the specified locale.
MMMM	Month as its full name. The function uses the LOCALE_SMONTHNAME value associated with the specified locale.
y	Year as last two digits, but with no leading zero for years less than 10.
yy	Year as last two digits, but with leading zero for years less than 10.
yyyy	Year represented by full four digits.
gg	Period/era string. The function uses the CAL_SERASTRING value associated with the specified locale. This element is ignored if the date to be formatted does not have an associated era or period string.
For example, to get the date string

“Wed, Aug 31 94”

use the following picture string:

“ddd',' MMM dd yy”

lpDateStr

Pointer to a buffer that receives the formatted date string.

cchDate

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the lpDateStr buffer. If cchDate is zero, the function returns the number of bytes or characters required to hold the formatted date string, and the buffer pointed to by lpDateStr is not used.

Return Values

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) written to the lpDateStr buffer, or if the cchDate parameter is zero, the number of bytes or characters required to hold the formatted date string.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

Remarks

The day name, abbreviated day name, month name, and abbreviated month name are all localized based on the given locale identifier.

The date values in the SYSTEMTIME structure pointed to by lpDate must be valid. The function checks each of the date values: year, month, day, and day of week. If the day of the week is incorrect, the function uses the correct value, and returns no error. If any of the other date values are outside the correct range, the function fails, and sets the last-error to ERROR_INVALID_PARAMETER.

The function ignores the time portions of the SYSTEMTIME structure pointed to by lpDate: wHour, wMinute, wSecond, and wMilliseconds.

The DATE_SHORTDATE and DATE_LONGDATE flag options are mutually exclusive. If neither one is specified and lpFormat is NULL, then DATE_SHORTDATE is the default.

No errors are returned for a bad format string. The function simply forms the best date string that it can. For example, the only year pictures that are valid are L”yyyy” and L”yy” (the ‘L’ indicates a Unicode (16-bit characters) string). If L”y” is passed in, the function  assumes L”yy”. If L”yyy” is passed in, the function assumes L”yyyy”. If more than 4 date (L”dddd”) or 4 month (L”MMMM”) pictures are passed in, then the function defaults to L”dddd” or L”MMMM”.

Any text that should remain in its exact form in the date string should be enclosed within single quotation marks in the date format picture. The single quotation mark may also be used as an escape character to allow the single quotation mark itself to be displayed in the date string. However, the escape sequence must be enclosed within two single quotation marks. For example, to display the date as "May '93", the format string would be:  L"MMMM ''''yy" The first and last single quotation marks are the enclosing quotation marks. The second and third single quotation marks are the escape sequence to allow the single quotation mark to be displayed before the century.

See Also

GetTimeFormat, SYSTEMTIME


GetDC

The GetDC function retrieves a handle of a display device context (DC) for the client area of the specified window. The display device context can be used in subsequent GDI functions to draw in the client area of the window.

This function retrieves a common, class, or private device context depending on the class style specified for the specified window. For common device contexts, GetDC assigns default attributes to the device context each time it is retrieved. For class and private device contexts, GetDC leaves the previously assigned attributes unchanged.

HDC GetDC(

HWND hWnd	// handle of window
);
Parameters

hWnd

Identifies the window whose device context is to be retrieved.

Return Values

If the function succeeds, the return value identifies the device context for the given window’s client area.

If the function fails, the return value is NULL.

Remarks

After painting with a common device context, the ReleaseDC function must be called to release the device context. Class and private device contexts do not have to be released. The number of device contexts is limited only by available memory.

See Also

ReleaseDC, GetWindowDC


GetDCEx

The GetDCEx function retrieves the handle of a display device (DC) context for the specified window. The display device context can be used in subsequent GDI functions to draw in the client area.

This function is an extension to the GetDC function that gives an application more control over how and whether clipping occurs in the client area.

HDC GetDCEx(

HWND hWnd,	// handle of window
HRGN hrgnClip,	// handle of clip region
DWORD flags	// device-context creation flags
);
Parameters

hWnd

Identifies the window where drawing will occur.

hrgnClip

Specifies a clipping region that may be combined with the visible region of the client window.

flags

Specifies how the device context is created. This parameter can be a combination of the following values:

Value	Meaning
DCX_WINDOW	Returns a device context corresponding to the window rectangle rather than the client rectangle.
DCX_CACHE	Returns a device context from the cache, rather than the OWNDC or CLASSDC window. Essentially overrides CS_OWNDC and CS_CLASSDC.
DCX_PARENTCLIP	Uses the visible region of the parent window. The parent’s WS_CLIPCHILDREN and CS_PARENTDC style bits are ignored. The device context origin is set to the upper-left corner of the window identified by hWnd.
DCX_CLIPSIBLINGS	Excludes the visible regions of all sibling windows above the window identified by hWnd.
DCX_CLIPCHILDREN	Excludes the visible regions of all child windows below the window identified by hWnd.
DCX_NORESETATTRS	Does not reset the attributes of this device context to the default attributes when this device context is released.
DCX_LOCKWINDOWUPDATE	Allows drawing even if there is a LockWindowUpdate call in effect that would otherwise exclude this window. Used for drawing during tracking.
DCX_EXCLUDERGN	The clipping region identified by hrgnClip is excluded from the visible region of the returned device context.
DCX_INTERSECTRGN	The clipping region identified by hrgnClip is intersected with the visible region of the returned device context.
DCX_VALIDATE	When specified with DCX_INTERSECTUPDATE, causes the device context to be completely validated. Using this function with both DCX_INTERSECTUPDATE and DCX_VALIDATE is identical to using the BeginPaint function.
Return Values

If the function succeeds, the return value is the handle of the device context for the given window.

If the function fails, the return value is NULL. An invalid value for the hWnd parameter will cause the function to fail.

Remarks

Unless the display device context belongs to a window class, the ReleaseDC function must be called to release the device context after painting. Because only five common device contexts are available at any given time, failure to release a device context can prevent other applications from accessing a device context.

A device context belonging to the window’s class is returned by the GetDC function if CS_CLASSDC, CS_OWNDC or CS_PARENTDC was specified as a style in the WNDCLASS structure when the class was registered.

See Also

BeginPaint, GetDC, GetWindowDC, ReleaseDC, WNDCLASS


GetDCOrgEx

The GetDCOrgEx function obtains the final translation origin for a specified device context (DC). The final translation origin specifies an offset that Windows uses to translate device coordinates into client coordinates (for coordinates in an application’s window). This function supersedes the GetDCOrg function.

BOOL GetDCOrgEx(

HDC hdc,	// device-context handle
LPPOINT lpPoint	// address of structure that receives translation origin
);
Parameters

hdc

Specifies the device context whose final translation origin is to be retrieved.

lpPoint

Points to a POINT structure that the function will set to the final translation origin, in device coordinates.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The final translation origin is relative to the physical origin of the screen.

See Also

CreateIC, POINT


GetDefaultCommConfig [Now Supported on Windows NT]
GetDefaultCommConfig

[Now Supported on Windows NT]

The GetDefaultCommConfig function gets the default configuration for a communications device.

BOOL GetDefaultCommConfig(

LPCSTR lpszName,
LPCOMMCONFIG lpCC,
LPDWORD lpdwSize
);
Parameters

lpszName

Points to a null-terminated string specifying the name of the device.

lpCC

Points to the buffer that receives the COMMCONFIG structure.

lpdwSize

Points to a 32-bit variable that specifies the size, in bytes, of the buffer pointed to by lpCC. Upon return, the variable contains the number of bytes copied if the function succeeds, or the number of bytes required if the buffer was too small.

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, use the GetLastError function.

See Also

SetDefaultCommConfig, COMMCONFIG


GetDesktopWindow

The GetDesktopWindow function returns the handle of the Windows desktop window. The desktop window covers the entire screen. The desktop window is the area on top of which all icons and other windows are painted.

HWND GetDesktopWindow(VOID)

Parameters

This function has no parameters.

Return Values

The return value is the handle of the desktop window.

See Also

GetWindow


GetDeviceCaps

The GetDeviceCaps function retrieves device-specific information about a specified device.

int GetDeviceCaps(

HDC hdc,	// device-context handle
int nIndex	// index of capability to query
);
Parameters

hdc

Identifies the device context.

nIndex

Specifies the item to return. This parameter can be one of the following values:

Index	Meaning
DRIVERVERSION	The device driver version.
TECHNOLOGY	Device technology. It can be any one of the following values:
Value	Meaning
DT_PLOTTER	Vector plotter
DT_RASDISPLAY	Raster display
DT_RASPRINTER	Raster printer
DT_RASCAMERA	Raster camera
DT_CHARSTREAM	Character stream
DT_METAFILE	Metafile
DT_DISPFILE	Display file
	If the hdc parameter identifies the device context of an enhanced metafile, the device technology is that of the referenced device as given to the CreateEnhMetaFile function. To determine whether it is an enhanced metafile device context, use the GetObjectType function.
HORZSIZE	Width, in millimeters, of the physical screen.
VERTSIZE	Height, in millimeters, of the physical screen.
HORZRES	Width, in pixels, of the screen.
VERTRES	Height, in raster lines, of the screen.
LOGPIXELSX	Number of pixels per logical inch along the screen width.
LOGPIXELSY	Number of pixels per logical inch along the screen height.
BITSPIXEL	Number of adjacent color bits for each pixel.
PLANES	Number of color planes.
NUMBRUSHES	Number of device-specific brushes.
NUMPENS	Number of device-specific pens.
NUMFONTS	Number of device-specific fonts.
NUMCOLORS	Number of entries in the device’s color table, if the device has a color depth of no more than 8 bits per pixel. For devices with greater color depths, -1 is returned.
ASPECTX	Relative width of a device pixel used for line drawing.
ASPECTY	Relative height of a device pixel used for line drawing.
ASPECTXY	Diagonal width of the device pixel used for line drawing.
PDEVICESIZE	Reserved.
CLIPCAPS	Flag that indicates the clipping capabilities of the device. If the device can clip to a rectangle, it is 1. Otherwise, it is 0.
SIZEPALETTE	Number of entries in the system palette. This index is valid only if the device driver sets the RC_PALETTE bit in the RASTERCAPS index and is available only if the driver is compatible with Windows version 3.0 or later.
NUMRESERVED	Number of reserved entries in the system palette. This index is valid only if the device driver sets the RC_PALETTE bit in the RASTERCAPS index and is available only if the driver is compatible with Windows version 3.0 or later.
COLORRES	Actual color resolution of the device, in bits per pixel. This index is valid only if the device driver sets the RC_PALETTE bit in the RASTERCAPS index and is available only if the driver is compatible with Windows version 3.0 or later.
PHYSICALWIDTH	For printing devices: the width of the physical page, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper has a physical width value of 5100 device units. Note that the physical page is almost always greater than the printable area of the page, and never smaller.
PHYSICALHEIGHT	For printing devices: the height of the physical page, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper has a physical height value of 6600 device units. Note that the physical page is almost always greater than the printable area of the page, and never smaller.
PHYSICALOFFSETX	For printing devices: the distance  from the left edge of the physical page to the left edge of the printable area, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper, that cannot print on the leftmost 0.25" of paper, has a horizontal physical offset of 150 device units.
PHYSICALOFFSETY	For printing devices: the distance  from the top edge of the physical page to the top edge of the printable area, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper, that cannot print on the topmost 0.5" of paper, has a vertical physical offset of 300 device units.
VREFRESH	Windows NT only: For display devices: the current vertical refresh rate of the device, in cycles per second (Hz). A vertical refresh rate value of 0 or 1 represents the display hardware’s default refresh rate. This default rate is typically set by switches on a display card or computer motherboard, or by a configuration program that does not use Win32 display functions such as ChangeDisplaySettings.
DESKTOPHORZRES	Windows NT only: Width, in pixels, of the virtual desktop. This value may be larger than HORZRES if the device supports a virtual desktop or multiple displays.
DESKTOPVERTRES	Windows NT only: Height, in pixels, of the virtual desktop. This value may be larger than VERTRES if the device supports a virtual desktop or multiple displays.
BLTALIGNMENT	Windows NT only: Preferred horizontal drawing alignment, expressed as a multiple of pixels. For best drawing performance, windows should be horizontally aligned to a multiple of this value. A value of zero indicates that the device is accelerated, and any alignment may be used.
RASTERCAPS	Value that indicates the raster capabilities of the device, as shown in the following table:
Capability	Meaning
RC_BANDING	Requires banding support.
RC_BITBLT	Capable of transferring bitmaps.
RC_BITMAP64	Capable of supporting bitmaps larger than 64K.
RC_DI_BITMAP	Capable of supporting the SetDIBits and GetDIBits functions.
RC_DIBTODEV	Capable of supporting the SetDIBitsToDevice function.
RC_FLOODFILL	Capable of performing flood fills.
RC_GDI20_OUTPUT	Capable of supporting features of Windows 2.0.
RC_PALETTE	Specifies a palette-based device.
RC_SCALING	Capable of scaling.
RC_STRETCHBLT	Capable of performing the StretchBlt function.
RC_STRETCHDIB	Capable of performing the StretchDIBits function.
CURVECAPS	Value that indicates the curve capabilities of the device, as shown in the following table:
Value	Meaning
CC_NONE	Device does not support curves.
CC_CIRCLES	Device can draw circles.
CC_PIE	Device can draw pie wedges.
CC_CHORD	Device can draw chord arcs.
CC_ELLIPSES	Device can draw ellipses.
CC_WIDE	Device can draw wide borders.
CC_STYLED	Device can draw styled borders.
CC_WIDESTYLED	Device can draw borders that are wide and styled.
CC_INTERIORS	Device can draw interiors.
CC_ROUNDRECT	Device can draw rounded rectangles.
LINECAPS	Value that indicates the line capabilities of the device, as shown in the following table:
Value	Meaning
LC_NONE	Device does not support lines.
LC_POLYLINE	Device can draw a polyline.
LC_MARKER	Device can draw a marker.
LC_POLYMARKER	Device can draw multiple markers.
LC_WIDE	Device can draw wide lines.
LC_STYLED	Device can draw styled lines.
LC_WIDESTYLED	Device can draw lines that are wide and styled.
LC_INTERIORS	Device can draw interiors.
POLYGONALCAPS	Value that indicates the polygon capabilities of the device, as shown in the following table:
Value	Meaning
PC_NONE	Device does not support polygons.
PC_POLYGON	Device can draw alternate-fill polygons.
PC_RECTANGLE	Device can draw rectangles.
PC_WINDPOLYGON	Device can draw winding-fill polygons.
PC_SCANLINE	Device can draw a single scanline.
PC_WIDE	Device can draw wide borders.
PC_STYLED	Device can draw styled borders.
PC_WIDESTYLED	Device can draw borders that are wide and styled.
PC_INTERIORS	Device can draw interiors.
TEXTCAPS	Value that indicates the text capabilities of the device, as shown in the following table:
Bit	Meaning
TC_OP_CHARACTER	Device is capable of character output precision.
TC_OP_STROKE	Device is capable of stroke output precision.
TC_CP_STROKE	Device is capable of stroke clip precision.
TC_CR_90	Device is capable of 90-degree character rotation.
TC_CR_ANY	Device is capable of any character rotation.
TC_SF_X_YINDEP	Device can scale independently in the x- and y-directions.
TC_SA_DOUBLE	Device is capable of doubled character for scaling.
TC_SA_INTEGER	Device uses integer multiples only for character scaling.
TC_SA_CONTIN	Device uses any multiples for exact character scaling.
TC_EA_DOUBLE	Device can draw double-weight characters.
TC_IA_ABLE	Device can italicize.
TC_UA_ABLE	Device can underline.
TC_SO_ABLE	Device can draw strikeouts.
TC_RA_ABLE	Device can draw raster fonts.
TC_VA_ABLE	Device can draw vector fonts.
TC_RESERVED	Reserved; must be zero.
TC_SCROLLBLT	Device cannot scroll using a bit-block transfer. Note that this meaning may be the opposite of what you expect.
Return Values

The return value specifies the value of the desired item.

See Also

CreateEnhMetaFile, CreateIC, DeviceCapabilities, GetDIBits, GetObjectType, SetDIBits, SetDIBitsToDevice, StretchBlt, StretchDIBits


GetDeviceGammaRamp

The GetDeviceGammaRamp function retrieves the gamma ramp on direct color display boards.

BOOL GetDeviceGammaRamp(

HDC hdc,
LPVOID lpRamp
);
Parameters

hdc

Handle to the device context.

lpRamp

Pointer to a set of three arrays of 256-byte elements. These arrays are the mapping between color values in the frame buffer and DAC values. The first array is red, the next is green, and the final one is blue.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Direct color display modes do not use color lookup tables. The direct color modes are usually 16-, 24-, or 32-bit. Not all direct color video boards support loadable gamma ramps. This function succeeds only for those drivers that support loadable gamma ramps in hardware.

See Also

SetDeviceGammaRamp


GetDialogBaseUnits

The GetDialogBaseUnits function returns the dialog box base units used by Windows to create dialog boxes. Both Windows and applications use these units to convert the width and height of dialog boxes and controls from dialog units, as given in dialog box templates, to pixels, and vice versa.

LONG GetDialogBaseUnits(VOID)

Parameters

This function has no parameters.

Return Values

The return value is a 32-bit value that contains the dialog base units. The low-order word of the return value contains the horizontal dialog box base unit, and the high-order word contains the vertical dialog box base unit.

Remarks

The horizontal base unit is equal to the average width, in pixels, of the characters in the system font; the vertical base unit is equal to the height, in pixels, of the font. Furthermore, each horizontal base unit is equal to 4 horizontal dialog units; each vertical base unit is equal to 8 vertical dialog units. Therefore, to convert dialog units to pixels, an application applies the following formulas:

pixelX = (dialogunitX * baseunitX) / 4

pixelY = (dialogunitY * baseunitY) / 8

Similarly, to convert from pixels to dialog units, an application applies the following formulas:

dialogunitX = (pixelX * 4) / baseunitX

dialogunitY = (pixelY * 8) / baseunitY

The multiplication is performed before the division to avoid rounding problems if base units are not divisible by 4 or 8.

See Also

MapDialogRect


GetDIBColorTable

The GetDIBColorTable function retrieves RGB (red, green, blue) color values from a range of entries in the color table of the DIB section bitmap that is currently selected into a specified device context.

UINT GetDIBColorTable(

HDC hdc,	// handle of device context whose DIB is of interest
UINT uStartIndex,	// color table index of first entry to retrieve
UINT cEntries,	// number of color table entries to retrieve
RGBQUAD *pColors	// pointer to buffer that receives color table entries
);
Parameters

hdc

Specifies a device context. A DIB section bitmap must be selected into this device context.

uStartIndex

A zero-based color table index that specifies the first color table entry to retrieve.

cEntries

Specifies the number of color table entries to retrieve.

pColors

Points to a buffer that receives an array of RGBQUAD data structures containing color information from the DIB’s color table. The buffer must be large enough to contain as many RGBQUAD data structures as the value of cEntries.

Return Values

If the function succeeds, the return value is the number of color table entries that the function retrieves.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The GetDIBColorTable function should be called to retrieve the color table for DIB section bitmaps that use 1, 4, or 8 bits per pixel. The biBitCount member of a bitmap’s associated BITMAPINFOHEADER structure specifies the number of bits per pixel. DIB section bitmaps with a biBitCount value greater than 8 do not have a color table, but they do have associated color masks. Call the GetObject function to retrieve those color masks.

See Also

BITMAPINFOHEADER, CreateDIBSection, DIBSECTION, GetObject, RGBQUAD, SetDIBColorTable


GetDIBits

The GetDIBits function retrieves the bits of the specified bitmap and copies them into a buffer using the specified format.

int GetDIBits(

HDC hdc,	// handle of device context
HBITMAP hbmp,	// handle of bitmap
UINT uStartScan,	// first scan line to set in destination bitmap
UINT cScanLines,	// number of scan lines to copy
LPVOID lpvBits,	// address of array for bitmap bits
LPBITMAPINFO lpbi,	// address of structure with bitmap data
UINT uUsage	// RGB or palette index
);
Parameters

hdc

Identifies the device context.

hbmp

Identifies the bitmap.

uStartScan

Specifies the first scan line to retrieve.

cScanLines

Specifies the number of scan lines to retrieve.

lpvBits

Points to a buffer to receive the bitmap data. If this parameter is NULL, the function passes the dimensions and format of the bitmap to the BITMAPINFO structure pointed to by the lpbi parameter.

lpbi

Points to a BITMAPINFO structure that specifies the desired format for the device-independent bitmap (DIB) data.

uUsage

Specifies the format of the bmiColors member of the BITMAPINFO structure. It must be one of the following values:

Value	Meaning
DIB_PAL_COLORS	The color table should consist of an array of 16-bit indices into the current logical palette.
DIB_RGB_COLORS	The color table should consist of literal red, green, blue (RGB) values.
Return Values

If the lpvBits parameter is non-NULL and the function succeeds, the return value is the number of scan lines copied from the bitmap.

Windows 95:

If the lpvBits parameter is NULL and GetDIBits successfully fills the BITMAPINFO structure, the return value is the total number of scan lines in the bitmap.

Windows NT:

If the lpvBits parameter is NULL and GetDIBits successfully fills the BITMAPINFO structure, the return value is non-zero.

If the function fails, the return value is zero.

Remarks

If the requested format for the DIB matches its internal format, the RGB values for the bitmap are copied. If the requested format doesn’t match the internal format, a color table is synthesized. The following table describes the color table synthesized for each format.

Value	Meaning
1_BPP	The color table consists of a black and a white entry.
4_BPP	The color table consists of a mix of colors identical to the standard VGA palette.
8_BPP	The color table consists of a general mix of 256 colors defined by GDI. (Included in these 256 colors are the 20 colors found in the default logical palette.)
24_BPP	No color table is returned.
If the lpvBits parameter is a valid pointer, the first six members of the BITMAPINFOHEADER structure must be initialized to specify the size and format of the DIB. Note that a bottom-up DIB is specified by setting the height to a positive number, while a top-down DIB is specified by setting the height to a negative number. The bitmap’s color table will be appended to the BITMAPINFO structure.

If lpvBits is NULL, GetDIBits examines the first member of the first structure pointed to by lpbi. This member must specify the size, in bytes, of a BITMAPCOREHEADER or a BITMAPINFOHEADER structure. The function uses the specified size to determine how the remaining members should be initialized.

If lpvBits is NULL and the bit count member of BITMAPINFO is initialized to zero, GetDIBits fills in BITMAPINFOHEADER or BITMAPCOREHEADER without the color table. This technique can be used to query bitmap attributes.

The bitmap identified by the hbmp parameter must not be selected into a device context when the application calls this function.

The origin for a bottom-up DIB is the lower-left corner of the bitmap; the origin for a top-down DIB is the upper-left corner.

See Also

BITMAPCOREHEADER, BITMAPINFO, BITMAPINFOHEADER, SetDIBits


GetDiskFreeSpace

The GetDiskFreeSpace function retrieves information about the specified disk, including the amount of free space on the disk.

BOOL GetDiskFreeSpace(

LPCTSTR lpRootPathName,	// address of root path
LPDWORD lpSectorsPerCluster,	// address of sectors per cluster
LPDWORD lpBytesPerSector,	// address of bytes per sector
LPDWORD lpNumberOfFreeClusters,	// address of number of free clusters
LPDWORD lpTotalNumberOfClusters	// address of total number of clusters
);
Parameters

lpRootPathName

Points to a null-terminated string that specifies the root directory of the disk to return information about. If lpRootPathName is NULL, the function uses the root of the current directory.

lpSectorsPerCluster

Points to a variable for the number of sectors per cluster.

lpBytesPerSector

Points to a variable for the number of bytes per sector.

lpNumberOfFreeClusters

Points to a variable for the total number of free clusters on the disk.

lpTotalNumberOfClusters

Points to a variable for the total number of clusters on the disk.

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.

Remarks

Windows 95:

The GetDiskFreeSpace function returns incorrect values for volumes that are larger than 2 gigabytes. The function caps the values stored into *lpNumberOfFreeClusters and *lpTotalNumberOfClusters so as to never report volume sizes that are greater than 2 gigabytes.

Even on volumes that are smaller than 2 gigabytes, the values stored into *lpSectorsPerCluster, *lpNumberOfFreeClusters, and *lpTotalNumberOfClusters values may be incorrect. That is because the operating system manipulates the values so that computations with them yield the correct volume size.

Windows 95 OSR 2: The GetDiskFreeSpaceEx function is available on Windows 95 systems beginning with OEM Service Release 2 (OSR 2). The GetDiskFreeSpaceEx function returns correct values for all volumes, including those that are greater than 2 gigabytes.

See Also

GetDiskFreeSpaceEx, GetDriveType


GetDiskFreeSpaceEx [New - Windows NT] [New - Windows 95, OEM Service Release 2]
GetDiskFreeSpaceEx

[New - Windows NT]

[New - Windows 95, OEM Service Release 2]

The GetDiskFreeSpaceEx function obtains information about the amount of space available on a disk volume: the total amount of space, the total amount of free space, and the total amount of free space available to the user associated with the calling thread.

Windows 95 OSR 2:

The GetDiskFreeSpaceEx function is available on Windows 95 systems beginning with OEM Service Release 2 (OSR 2).

Use the GetVersionEx function to determine that a system is running OSR 2 or a later release of the Windows 95 operating system. The GetVersionEx function fills in the members of an OSVERSIONINFO data structure. If the dwPlatformId member of that structure is VER_PLATFORM_WIN32_WINDOWS, and the low word of the dwBuildNumber member is greater than 1000, the system is running OSR 2 or a later release.

Once you have determined that a system is running OSR 2, call the LoadLibrary or LoadLibraryEx function to load the KERNEL32.DLL file, then call the GetProcAddress function to obtain an address for the GetDiskFreeSpaceEx function. Use that address to call the function.

BOOL GetDiskFreeSpaceEx(

LPCTSTR lpDirectoryName,	// pointer to directory name on disk of interest
PULARGE_INTEGER lpFreeBytesAvailableToCaller,	// pointer to variable to receive free bytes on disk available to the caller
PULARGE_INTEGER lpTotalNumberOfBytes,	// pointer to variable to receive number of bytes on disk
PULARGE_INTEGER lpTotalNumberOfFreeBytes	// pointer to variable to receive free bytes on disk
);
Parameters

lpDirectoryName

Pointer to a null-terminated string that specifies a directory on the disk of interest. This string can be a UNC name.

If lpDirectoryName is NULL, the GetDiskFreeSpaceEx function obtains information about the disk that contains the currect directory.

Note that lpDirectoryName does not have to specify the root directory on a disk. The function accepts any directory on the disk.

lpFreeBytesAvailableToCaller

Pointer to a variable to receive the total number of free bytes on the disk that are available to the user associated with the calling thread.

If the operating system implements per-user quotas, this value may be less than the total number of free bytes on the disk.

lpTotalNumberOfBytes

Pointer to a variable to receive the total number of bytes on the disk.

lpTotalNumberOfFreeBytes

Pointer to a variable to receive the total number of free bytes on the disk.

This parameter can be NULL.

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.

Remarks

Note that the values obtained by this function are of type ULARGE_INTEGER. Be careful not to truncate these values to 32 bits.

The GetDiskFreeSpaceEx function lets you avoid the arithmetic required by the GetDiskFreeSpace function.

See Also

GetDiskFreeSpace


GetDlgCtrlID

The GetDlgCtrlID function returns the identifier of the specified control.

int GetDlgCtrlID(

HWND hwndCtl	// handle of control
);
Parameters

hwndCtl

Identifies the control.

Return Values

If the function succeeds, the return value is the identifier of the control.

If the function fails, the return value is NULL. An invalid value for the hwndCtl parameter, for example, will cause the function to fail.

Remarks

GetDlgCtrlID accepts child window handles as well as handles of controls in dialog boxes. An application sets the identifier for a child window when it creates the window by assigning the identifier value to the hmenu parameter when calling the CreateWindow or CreateWindowEx function.

Although GetDlgCtrlID may return a value if hwndCtl identifies a top-level window, top-level windows cannot have identifiers and such a return value is never valid.

See Also

CreateWindow, CreateWindowEx, GetDlgItem


GetDlgItem

The GetDlgItem function retrieves the handle of a control in the specified dialog box.

HWND GetDlgItem(

HWND hDlg,	// handle of dialog box
int nIDDlgItem	// identifier of control
);
Parameters

hDlg

Identifies the dialog box that contains the control.

nIDDlgItem

Specifies the identifier of the control to be retrieved.

Return Values

If the function succeeds, the return value is the window handle of the given control.

If the function fails, the return value is NULL, indicating an invalid dialog box handle or a nonexistent control.

Remarks

You can use the GetDlgItem function with any parent-child window pair, not just with dialog boxes. As long as the hDlg parameter specifies a parent window and the child window has a unique identifier (as specified by the hMenu parameter in the CreateWindow or CreateWindowEx function that created the child window), GetDlgItem returns a valid handle to the child window.

See Also

CreateWindow, CreateWindowEx, GetDlgItemInt, GetDlgItemText


GetDlgItemInt

The GetDlgItemInt function translates the text of a specified control in a dialog box into an integer value.

UINT GetDlgItemInt(

HWND hDlg,	// handle to dialog box
int nIDDlgItem,	// control identifier
BOOL *lpTranslated,	// points to variable to receive success/failure indicator
BOOL bSigned	// specifies whether value is signed or unsigned
);
Parameters

hDlg

Handle to the dialog box that contains the control of interest.

nIDDlgItem

Dialog item identifier that specifies the control whose text is to be translated.

lpTranslated

Points to a Boolean variable that receives a function success/failure value. TRUE indicates success, FALSE indicates failure.

This parameter is optional: it can be NULL. In that case, the function returns no information about success or failure.

bSigned

Specifies whether the function should examine the text for a minus sign at the beginning and return a signed integer value if it finds one. TRUE specifies that this should be done, FALSE that it should not.

Return Values

If the function succeeds, the variable pointed to by lpTranslated is set to TRUE, and the return value is the translated value of the control text.

If the function fails, the variable pointed to by lpTranslated is set to FALSE, and the return value is zero. Note that, since zero is a possible translated value, a return value of zero does not by itself indicate failure.

If lpTranslated is NULL, the function returns no information about success or failure.

If the bSigned parameter is TRUE, specifying that the value to be retrieved is a signed integer value, cast the return value to an int type.

Remarks

The GetDlgItemInt function retrieves the text of the given control by sending the control a WM_GETTEXT message. The function translates the retrieved text by stripping any extra spaces at the beginning of the text and then converting the decimal digits. The function stops translating when it reaches the end of the text or encounters a nonnumeric character.

If the bSigned parameter is TRUE, the GetDlgItemInt function checks for a minus sign (−) at the beginning of the text and translates the text into a signed integer value. Otherwise, the function creates an unsigned integer value.

The GetDlgItemInt function returns zero if the translated value is greater than INT_MAX (for signed numbers) or UINT_MAX (for unsigned numbers).

See Also

GetDlgCtrlID, GetDlgItem, GetDlgItemText, SetDlgItemInt


GetDlgItemText

The GetDlgItemText function retrieves the title or text associated with a control in a dialog box.

UINT GetDlgItemText(

HWND hDlg,	// handle of dialog box
int nIDDlgItem,	// identifier of control
LPTSTR lpString,	// address of buffer for text
int nMaxCount	// maximum size of string
);
Parameters

hDlg

Identifies the dialog box that contains the control.

nIDDlgItem

Specifies the identifier of the control whose title or text is to be retrieved.

lpString

Points to the buffer to receive the title or text.

nMaxCount

Specifies the maximum length, in characters, of the string to be copied to the buffer pointed to by lpString. If the length of the string exceeds the limit, the string is truncated.

Return Values

If the function succeeds, the return value specifies the number of characters copied to the buffer, not including the terminating null character.

If the function fails, the return value is zero.

Remarks

The GetDlgItemText function sends a WM_GETTEXT message to the control.

See Also

GetDlgItemInt, SetDlgItemInt, SetDlgItemText, WM_GETTEXT


GetDoubleClickTime

The GetDoubleClickTime function retrieves the current double-click time for the mouse. A double-click is a series of two clicks of the mouse button, the second occurring within a specified time after the first. The double-click time is the maximum number of milliseconds that may occur between the first and second click of a double-click.

UINT GetDoubleClickTime(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value specifies the current double-click time, in milliseconds.

See Also

SetDoubleClickTime


GetDriveType

The GetDriveType function determines whether a disk drive is a removable, fixed, CD-ROM, RAM disk, or network drive.

UINT GetDriveType(

LPCTSTR lpRootPathName	// address of root path
);
Parameters

lpRootPathName

Points to a null-terminated string that specifies the root directory of the disk to return information about. If lpRootPathName is NULL, the function uses the root of the current directory.

Return Values

The return value specifies the type of drive. It can be one of the following values:

Value	Meaning
0	The drive type cannot be determined.
1	The root directory does not exist.
DRIVE_REMOVABLE	The drive can be removed from the drive.
DRIVE_FIXED	The disk cannot be removed from the drive.
DRIVE_REMOTE	The drive is a remote (network) drive.
DRIVE_CDROM	The drive is a CD-ROM drive.
DRIVE_RAMDISK	The drive is a RAM disk.
See Also

GetDiskFreeSpace


GetEffectiveClientRect

The GetEffectiveClientRect function calculates the dimensions of a rectangle in the client area. This function has limited utility.

void GetEffectiveClientRect(

HWND hWnd,
LPRECT lprc,
LPINT lpInfo
);
Parameters

hWnd

Handle to the window that has the client area to check.

lprc

Pointer to a RECT structure that receives the dimensions of the rectangle.

lpInfo

Pointer to an array of 16-bit control identifiers for controls in the client area. Each control requires two array elements. The first element must be nonzero, and the second element must be the control identifier. The last element in the array must be zero.

Return Values

This function does not return a value.

See Also

RECT


GetEffectiveRightsFromAcl [New - Windows NT]
GetEffectiveRightsFromAcl

[New - Windows NT]

The GetEffectiveRightsFromAcl function retrieves the effective access rights that an ACL allows for a specified trustee. The trustee’s effective access rights are the access rights that the ACL grants to the trustee or to any groups of which the trustee is a member. The function does not consider the security privileges held by the trustee in determining the effective access rights.

DWORD GetEffectiveRightsFromAcl(

PACL pacl,	// ACL to get trustee’s rights from
PTRUSTEE pTrustee,	// trustee to get rights for
PACCESS_MASK  pAccessRights	// receives trustee’s access rights
);
Parameters

pacl

Pointer to an ACL from which to get the trustee’s effective access rights.

pTrustee

Pointer to a TRUSTEE structure that identifies the trustee. A trustee can be a user, group, or program (such as a Windows NT service). You can use a name or a security identifier (SID) to identify a trustee.

pAccessRights

Pointer to an ACCESS_MASK variable that receives the effective access rights of the trustee.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

The GetEffectiveRightsFromAcl function checks all access-allowed and access-denied ACEs in the ACL to determine the effective rights for the trustee. For all ACEs that allow or deny rights to a group, GetEffectiveRightsFromAcl enumerates the members of the group to determine whether the trustee is a member. The function returns an error if it cannot enumerate the members of a group.

See Also

ACCESS_ALLOWED_ACE, ACCESS_DENIED_ACE, ACCESS_MASK, ACE, GetAuditedPermissionsFromAcl, SID, TRUSTEE


GetEnhMetaFile

The GetEnhMetaFile function creates a handle that identifies the enhanced-format metafile stored in the specified file.

HENHMETAFILE GetEnhMetaFile(

LPCTSTR lpszMetaFile	// address of metafile name
);
Parameters

lpszMetaFile

Points to the null-terminated string that specifies the name of an enhanced metafile.

Return Values

If the function succeeds, the return value is a handle of the enhanced metafile.

If the function fails, the return value is NULL.

Remarks

When the application no longer needs an enhanced-metafile handle, it should delete the handle by calling the DeleteEnhMetaFile function.

A Windows-format metafile must be converted to the enhanced format before it can be processed by the GetEnhMetaFile function. To convert the file, use the SetWinMetaFileBits function.

Where text arguments must use Unicode characters, use this function as a wide-character function. Where text arguments must use characters from the Windows 3.x character set, use this function as an ANSI function.

Windows 95: The maximum length of the description string for an enhanced metafile is 16,384 bytes.

See Also

DeleteEnhMetaFile, GetEnhMetaFile, SetWinMetaFileBits


GetEnhMetaFileBits

The GetEnhMetaFileBits function retrieves the contents of the specified enhanced-format metafile and copies them into a buffer.

UINT GetEnhMetaFileBits(

HENHMETAFILE hemf,	// handle of metafile
UINT cbBuffer,	// size of data buffer, in bytes
LPBYTE lpbBuffer	// address of data buffer
);
Parameters

hemf

Identifies the enhanced metafile.

cbBuffer

Specifies the size, in bytes, of the buffer to receive the data.

lpbBuffer

Points to the buffer to receive the metafile data. The buffer must be sufficiently large to contain the data. If lpbBuffer is NULL, the function returns the size necessary to hold the data.

Return Values

If the function succeeds and the buffer pointer is NULL, the return value is the size of the enhanced metafile, in bytes.

If the function succeeds and the buffer pointer is a valid pointer, the return value is the number of bytes copied to the buffer.

If the function fails, the return value is zero.

Remarks

After the enhanced-metafile bits are retrieved, they can be used to create a memory-based metafile by calling the SetEnhMetaFileBits function.

The GetEnhMetaFileBits function does not invalidate the enhanced-metafile handle. The application must call the DeleteEnhMetaFile function to delete the handle when it is no longer needed.

The metafile contents retrieved by this function are in the enhanced format. To retrieve the metafile contents in the Windows format, use the GetWinMetaFileBits function.

See Also

DeleteEnhMetaFile, GetWinMetaFileBits, SetEnhMetaFileBits


GetEnhMetaFileDescription

The GetEnhMetaFileDescription function retrieves an optional text description from an enhanced-format metafile and copies the string to the specified buffer.

UINT GetEnhMetaFileDescription(

HENHMETAFILE hemf,	// handle of enhanced metafile
UINT cchBuffer,	// size of text buffer, in characters
LPTSTR lpszDescription	// address of text buffer
);
Parameters

hemf

Identifies the enhanced metafile.

cchBuffer

Specifies the size, in characters, of the buffer to receive the data. Only this many characters will be copied.

lpszDescription

Points to the buffer to receive the optional text description.

Return Values

If the optional text description exists and the buffer pointer is NULL, the return value is the length of the text string, in characters.

If the optional text description exists and the buffer pointer is a valid pointer, the return value is the number of characters copied into the buffer.

If the optional text description does not exist, the return value is zero.

If the function fails, the return value is GDI_ERROR.

Remarks

The optional text description contains two strings, the first identifying the application that created the enhanced metafile and the second identifying the picture contained in the metafile. The strings are separated by a null character and terminated with two null characters — for example, “XYZ Graphics Editor\0Bald Eagle\0\0” where \0 represents the null character.

Where text arguments must use Unicode characters, use this function as a wide-character function. Where text arguments must use characters from the Windows 3.x character set, use this function as an ANSI function.

Windows 95: The maximum length of the description string for an enhanced metafile is 16,384 bytes.

See Also

CreateEnhMetaFile


GetEnhMetaFileHeader

The GetEnhMetaFileHeader function retrieves the record containing the header for the specified enhanced-format metafile.

UINT GetEnhMetaFileHeader(

HENHMETAFILE hemf,	// handle of enhanced metafile
UINT cbBuffer,	// size of buffer, in bytes
LPENHMETAHEADER lpemh	// address of buffer to receive data
);
Parameters

hemf

Identifies the enhanced metafile for which the header is to be retrieved.

cbBuffer

Specifies the size, in bytes, of the buffer to receive the data. Only this many bytes will be copied.

lpemh

Points to an ENHMETAHEADER structure to receive the header record. If this parameter is NULL, the function returns the size of the header record.

Return Values

If the function succeeds and the structure pointer is NULL, the return value is the size of the record that contains the header; if the structure pointer is a valid pointer, the return value is the number of bytes copied. Otherwise, it is zero.

Remarks

An enhanced-metafile header contains such information as the metafile’s size, in bytes; the dimensions of the picture stored in the metafile; the number of records stored in the metafile; the offset to the optional text description; the size of the optional palette, and the resolution of the device on which the picture was created.

The record that contains the enhanced-metafile header is always the first record in the metafile.

Windows 95: The maximum length of the description string for an enhanced metafile is 16,384 bytes.

See Also

ENHMETAHEADER, PlayEnhMetaFile


GetEnhMetaFilePaletteEntries

The GetEnhMetaFilePaletteEntries function retrieves optional palette entries from the specified enhanced metafile.

UINT GetEnhMetaFilePaletteEntries(

HENHMETAFILE hemf,	// handle of enhanced metafile
UINT cEntries,	// count of palette entries
LPPALETTEENTRY lppe	// address of palette-entry array
);
Parameters

hemf

Identifies the enhanced metafile.

cEntries

Specifies the number of entries to be retrieved from the optional palette.

lppe

Points to an array of PALETTEENTRY structures to receive the palette colors. The array must contain at least as many structures as there are entries specified by the cEntries parameter.

Return Values

If the array pointer is NULL and the enhanced metafile contains an optional palette, the return value is the number of entries in the enhanced metafile’s palette; if the array pointer is a valid pointer and the enhanced metafile contains an optional palette, the return value is the number of entries copied; if the metafile does not contain an optional palette, the return value is zero. Otherwise, the return value is GDI_ERROR.

Remarks

An application can store an optional palette in an enhanced metafile by calling the CreatePalette and SetPaletteEntries functions before creating the picture and storing it in the metafile. By doing this, the application can achieve consistent colors when the picture is displayed on a variety of devices.

An application that displays a picture stored in an enhanced metafile can call the GetEnhMetaFilePaletteEntries function to determine whether the optional palette exists. If it does, the application can call the GetEnhMetaFilePaletteEntries function a second time to retrieve the palette entries and then create a logical palette (by using the CreatePalette function), select it into its device context (by using the SelectPalette function), and then realize it (by using the RealizePalette function). After the logical palette has been realized, calling the PlayEnhMetaFile function displays the picture using its original colors.

See Also

CreatePalette, PALETTEENTRY, PlayEnhMetaFile, RealizePalette, SelectPalette


GetEnvironmentStrings

The GetEnvironmentStrings function returns the address of the environment block for the current process. This function replaces the GetDOSEnvironment function.

LPVOID GetEnvironmentStrings(VOID)

Parameters

This function has no parameters.

Return Values

The return value is a pointer to an environment block for the current process.

Remarks

Do not use the return value of GetEnvironmentStrings to get or set environment variables. Instead, use the GetEnvironmentVariable and SetEnvironmentVariable functions to access the environment variables within this block. When the block is no longer needed, it should be freed by calling FreeEnvironmentStrings.

A process can use this function’s return value to specify the environment address used by the CreateProcess function.

See Also

CreateProcess, GetEnvironmentVariable, SetEnvironmentVariable, FreeEnvironmentStrings


GetEnvironmentVariable

The GetEnvironmentVariable function retrieves the value of the specified variable from the environment block of the calling process. The value is in the form of a null-terminated string of characters.

DWORD GetEnvironmentVariable(

LPCTSTR lpName,	// address of environment variable name
LPTSTR lpBuffer,	// address of buffer for variable value
DWORD nSize	// size of buffer, in characters
);
Parameters

lpName

Points to a null-terminated string that specifies the environment variable.

lpBuffer

Points to a buffer to receive the value of the specified environment variable.

nSize

Specifies the size, in characters, of the buffer pointed to by the lpBuffer parameter.

Return Values

If the function succeeds, the return value is the number of characters stored into the buffer pointed to by lpBuffer, not including the terminating null character.

If the specified environment variable name was not found in the environment block for the current process, the return value is zero.

If the buffer pointed to by lpBuffer is not large enough, the return value is the buffer size, in characters, required to hold the value string and its terminating null character.

See Also

GetEnvironmentStrings, SetEnvironmentVariable


GetExceptionCode

The GetExceptionCode function retrieves a code that identifies the type of exception that occurred. The function can be called only from within the filter expression or exception-handler block of a try-except exception handler.

DWORD GetExceptionCode(VOID)

Parameters

This function has no parameters.

Return Values

The return value identifies the type of exception. Following are the exception codes likely to occur due to common programming errors:

Value	Meaning
EXCEPTION_ACCESS_VIOLATION
	The thread attempted to read from or write to a virtual address for which it does not have the appropriate access.
EXCEPTION_BREAKPOINT
	A breakpoint was encountered.
EXCEPTION_DATATYPE_MISALIGNMENT
	The thread attempted to read or write data that is misaligned on hardware that does not provide alignment. For example, 16-bit values must be aligned on 2-byte boundaries, 32-bit values on 4-byte boundaries, and so on.
EXCEPTION_SINGLE_STEP
	A trace trap or other single-instruction mechanism signaled that one instruction has been executed.
EXCEPTION_ARRAY_BOUNDS_EXCEEDED
	The thread attempted to access an array element that is out of bounds, and the underlying hardware supports bounds checking.
EXCEPTION_FLT_DENORMAL_OPERAND
	One of the operands in a floating-point operation is denormal. A denormal value is one that is too small to represent as a standard floating-point value.
EXCEPTION_FLT_DIVIDE_BY_ZERO
	The thread attempted to divide a floating-point value by a floating-point divisor of zero.
EXCEPTION_FLT_INEXACT_RESULT
	The result of a floating-point operation cannot be represented exactly as a decimal fraction.
EXCEPTION_FLT_INVALID_OPERATION
	This exception represents any floating-point exception not included in this list.
EXCEPTION_FLT_OVERFLOW
	The exponent of a floating-point operation is greater than the magnitude allowed by the corresponding type.
EXCEPTION_FLT_STACK_CHECK
	The stack overflowed or underflowed as the result of a floating-point operation.
EXCEPTION_FLT_UNDERFLOW
	The exponent of a floating-point operation is less than the magnitude allowed by the corresponding type.
EXCEPTION_INT_DIVIDE_BY_ZERO
	The thread attempted to divide an integer value by an integer divisor of zero.
EXCEPTION_INT_OVERFLOW
	The result of an integer operation caused a carry out of the most significant bit of the result.
EXCEPTION_PRIV_INSTRUCTION
	The thread attempted to execute an instruction whose operation is not allowed in the current machine mode.
EXCEPTION_NONCONTINUABLE_EXCEPTION
	The thread attempted to continue execution after a noncontinuable exception occurred.
Remarks

The GetExceptionCode function can be called only from within the filter expression or exception-handler block of a try-except statement. The filter expression is evaluated if an exception occurs during execution of the try block, and it determines whether the except block is executed. The following example shows the structure of a try-except statement.

try {

    /* try block */

}

except (filter-expression) {

    /* exception handler block */

}

The filter expression can invoke a filter function. The filter function cannot call GetExceptionCode. However, the return value of GetExceptionCode can be passed as a parameter to a filter function. The return value of the GetExceptionInformation function can also be passed as a parameter to a filter function. GetExceptionInformation returns a pointer to a structure that includes the exception-code information.

In the case of nested try-except statements, each statement’s filter expression is evaluated until one is evaluated as EXCEPTION_EXECUTE_HANDLER or EXCEPTION_CONTINUE_EXECUTION. Each filter expression can invoke GetExceptionCode to get the exception code.

The exception code returned is the code generated by a hardware exception, or the code specified in the RaiseException function for a software-generated exception.

See Also

GetExceptionInformation, RaiseException


GetExceptionInformation

The GetExceptionInformation function retrieves a machine-independent description of an exception, and information about the machine state that existed for the thread when the exception occurred. This function can be called only from within the filter expression of a try-except exception handler.

LPEXCEPTION_POINTERS GetExceptionInformation(VOID)

Parameters

This function has no parameters.

Return Values

The return value is a pointer to an EXCEPTION_POINTERS structure that contains pointers to two other structures: an EXCEPTION_RECORD structure containing a description of the exception, and a CONTEXT structure containing the machine-state information.

Remarks

The filter expression (from which the function is called) is evaluated if an exception occurs during execution of the try block, and it determines whether the except block is executed. The following example shows the structure of a try-except statement.

try {

    /* try block */

}

except (filter-expression) {

    /* exception handler block */

}

The filter expression can invoke a filter function. The filter function cannot call GetExceptionInformation. However, the return value of GetExceptionInformation can be passed as a parameter to a filter function.

To pass the EXCEPTION_POINTERS information to the exception-handler block, the filter expression or filter function must copy the pointer or the data to safe storage that the handler can later access.

In the case of nested try-except statements, each statement’s filter expression is evaluated until one is evaluated as EXCEPTION_EXECUTE_HANDLER or EXCEPTION_CONTINUE_EXECUTION. Each filter expression can invoke GetExceptionInformation to get exception information.

See Also

CONTEXT, EXCEPTION_POINTERS, EXCEPTION_RECORD, GetExceptionCode


GetExitCodeProcess

The GetExitCodeProcess function retrieves the termination status of the specified process.

BOOL GetExitCodeProcess(

HANDLE hProcess,	// handle to the process
LPDWORD lpExitCode	// address to receive termination status
);
Parameters

hProcess

Identifies the process.

Windows NT: The handle must have PROCESS_QUERY_INFORMATION access. For more information, see Process Objects.

lpExitCode

Points to a 32-bit variable to receive the process termination status.

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.

Remarks

If the specified process has not terminated, the termination status returned is STILL_ACTIVE. If the process has terminated, the termination status returned may be one of the following:

•	The exit value specified in the ExitProcess or TerminateProcess function.

•	The return value from the main or WinMain function of the process.

•	The exception value for an unhandled exception that caused the process to terminate.

See Also

ExitProcess, ExitThread, TerminateProcess, WinMain


GetExitCodeThread

The GetExitCodeThread function retrieves the termination status of the specified thread.

BOOL GetExitCodeThread(

HANDLE hThread,	// handle to the thread
LPDWORD lpExitCode	// address to receive termination status
);
Parameters

hThread

Identifies the thread.

Windows NT: The handle must have THREAD_QUERY_INFORMATION access. For more information, see Thread Objects.

lpExitCode

Points to a 32-bit variable to receive the thread termination status.

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.

Remarks

If the specified thread has not terminated, the termination status returned is STILL_ACTIVE. If the thread has terminated, the termination status returned may be one of the following:

•	The exit value specified in the ExitThread or TerminateThread function.

•	The return value from the thread function.

•	The exit value of the thread’s process.

See Also

ExitThread, GetExitCodeProcess, TerminateThread


GetExpandedName

The GetExpandedName function retrieves the original name of a compressed file, if the file was compressed by using the Microsoft File Compression Utility (COMPRESS.EXE) and the /r option was specified.

INT GetExpandedName(

LPTSTR lpszSource,	// address of name of compressed file
LPTSTR lpszBuffer	// address of buffer for original filename
);
Parameters

lpszSource

Points to a string that specifies the name of a compressed file.

lpszBuffer

Points to a buffer that receives the name of the compressed file.

Return Values

If the function succeeds, the return value is 1.

If the function fails, the return value is LZERROR_BADVALUE.

Note that GetExpandedName calls neither SetLastError nor SetLastErrorEx; thus, its failure does not affect a thread’s last-error code.

Remarks

The contents of the buffer pointed to by the lpszBuffer parameter is the original filename if the file was compressed by using the /r option. If the /r option was not used, this function duplicates the name in the lpszSource parameter into the lpszBuffer buffer.


GetExplicitEntriesFromAcl [New - Windows NT]
GetExplicitEntriesFromAcl

[New - Windows NT]

The GetExplicitEntriesFromAcl function retrieves an array of EXPLICIT_ACCESS structures that describe the access-control entries (ACEs) in an access-control list (ACL).

DWORD GetExplicitEntriesFromAcl(

PACL pacl,	// pointer to the ACL from which to get entries
PULONG pcCountOfExplicitEntries,	// receives number of entries in the list
PEXPLICIT_ACCESS * pListOfExplicitEntries	// receives pointer to list of entries
);
Parameters

pacl

Pointer to an ACL from which to get ACE information.

pcCountOfExplicitEntries

Pointer to a variable that receives the number of EXPLICIT_ACCESS structures returned in the pListOfExplicitEntries array.

pListOfExplicitEntries

Pointer to a variable that receives a pointer to an array of EXPLICIT_ACCESS structures that describe the ACEs in the ACL. If the function succeeds, you must call the LocalFree function to free the returned buffer.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

Each entry in the array of EXPLICIT_ACCESS structures describes access control information from an ACE for a trustee. A trustee can be a user, group, or program (such as a Windows NT service).

Each EXPLICIT_ACCESS structure specifies a set of access rights and an access mode flag that indicates whether the ACE allows, denies, or audits the specified rights.

For a discretionary ACL (DACL), the access mode flag can be one of the following values from the ACCESS_MODE enumeration.

Value	Meaning
SET_ACCESS	Indicates that an access-allowed ACE for the trustee allows the specified access rights.
DENY_ACCESS	Indicates that an access-denied ACE for the trustee denies the specified access rights.
For a system ACL (SACL), the access mode flag can be a combination of the following values from the ACCESS_MODE enumeration.

Value	Meaning
SET_AUDIT_SUCCESS	Indicates that a system-audit ACE for the trustee generates audit messages for successful attempts to use the specified access rights.
SET_AUDIT_FAILURE	Indicates that a system-audit ACE for the trustee generates audit messages for failed attempts to use the specified access rights.
See Also

ACCESS_ALLOWED_ACE, ACCESS_DENIED_ACE, ACE, ACL, EXPLICIT_ACCESS, LocalFree, SYSTEM_AUDIT_ACE


GetFiberData

The GetFiberData function returns the fiber data associated with the current fiber.

PVOID GetFiberData(VOID)

Parameters

This function has no parameters.

Return Values

The return value is the fiber data for the currently running fiber.

Remarks

The fiber data is the value passed to the CreateFiber or ConvertThreadToFiber functions in the lpParameter parameter. This value is also received as the parameter to the fiber function. It is stored as part of the fiber state information.

See Also

CreateFiber, ConvertThreadToFiber


GetFileAttributes

The GetFileAttributes function returns attributes for a specified file or directory.

DWORD GetFileAttributes(

LPCTSTR lpFileName	// address of the name of a file or directory
);
Parameters

lpFileName

Points to a null-terminated string that specifies the name of a file or directory.

Windows NT:

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the GetFileAttributes function parses paths. An application can transcend this limit and send in paths longer than MAX_PATH characters by calling the wide (W) version of GetFileAttributes and prepending “\\?\” to the path. The “\\?\” tells the function to turn off path parsing; it lets paths longer than MAX_PATH be used with GetFileAttributesW. This also works with UNC names. The “\\?\” is ignored as part of the path. For example, “\\?\C:\myworld\private” is seen as “C:\myworld\private”, and “\\?\UNC\bill_g_1\hotstuff\coolapps” is seen as “\\bill_g_1\hotstuff\coolapps”.

Windows 95:

The lpFileName string must not exceed MAX_PATH characters. Windows 95 does not support the “\\?\” prefix.

Return Values

If the function succeeds, the return value contains the attributes of the specified file or directory.

If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

The attributes can be one or more of the following values:

Value	Meaning
FILE_ATTRIBUTE_ARCHIVE	The file or directory is an archive file or directory. Applications use this flag to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED	The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_DIRECTORY	The “file or directory” is a directory.
FILE_ATTRIBUTE_HIDDEN	The file or directory is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL	The file or directory has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_OFFLINE	The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage.
FILE_ATTRIBUTE_READONLY	The file or directory is read-only. Applications can read the file but cannot write to it or delete it. In the case of a directory, applications cannot delete it.
FILE_ATTRIBUTE_SYSTEM	The file or directory is part of, or is used exclusively by, the operating system.
FILE_ATTRIBUTE_TEMPORARY	The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed.
See Also

DeviceIOControl, FindFirstFile, FindNextFile, SetFileAttributes


GetFileAttributesEx [New - Windows NT]
GetFileAttributesEx

[New - Windows NT]

The GetFileAttributesEx function obtains attribute information about a specified file or directory.

This function is similar to the GetFileAttributes function. GetFileAttributes returns a set of FAT-style attribute information. GetFileAttributesEx is designed to obtain other sets of file or directory attribute information. Currently, GetFileAttributeEx obtains a set of standard attributes that is a superset of the FAT-style attribute information.

BOOL GetFileAttributesEx(

LPCTSTR lpFileName,	// pointer to string that specifies a file or directory
GET_FILEEX_INFO_LEVELS fInfoLevelId,	// value that specifies the type of attribute information to obtain
LPVOID lpFileInformation	// pointer to buffer to receive attribute information
);
Parameters

lpFileName

Pointer to a null-terminated string that specifies a file or directory.

By default, this string is limited to MAX_PATH characters. The limit is related to how the GetFileAttributesEx function parses paths. An application can transcend this limit and send in paths longer than MAX_PATH characters by calling the wide (W) version of GetFileAttributesEx and prepending “\\?\” to the path. The “\\?\” tells the function to turn off path parsing. This technique also works with UNC names. The “\\?\” is ignored as part of the path. For example, “\\?\C:\myworld\private” is seen as “C:\myworld\private”, and “\\?\UNC\peanuts\hotstuff\coolapps” is seen as “\\peanuts\hotstuff\coolapps”.

fInfoLevelId

Enumeration type value that specifies the set of attribute information to obtain.

You can use the following value for fInfoLevelId:

Value	Meaning
GetFileExInfoStandard	The function obtains a standard set of attribute information. The data is returned in a WIN32_FILE_ATTRIBUTE_DATA structure.
Future releases of Win32-based operating systems and extensions may define other values for the GET_FILEEX_INFO_LEVELS enum type.

lpFileInformation

Pointer to a buffer that receives the attribute information.

The type of attribute information stored into this buffer is determined by the value of fInfoLevelId, as follows:

Value of fInfoLevelId	Structure Stored into *lpFileInformation
GetFileExInfoStandard	WIN32_FILE_ATTRIBUTE_DATA.
Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

GetFileAttributes, SetFileAttributes, WIN32_FILE_ATTRIBUTE_DATA


GetFileInformationByHandle

The GetFileInformationByHandle function retrieves information about a specified file.

BOOL GetFileInformationByHandle(

HANDLE hFile,	// handle of file
LPBY_HANDLE_FILE_INFORMATION lpFileInformation	// address of structure
);
Parameters

hFile

Handle to the file that you want to obtain information about.

This handle should not be a pipe handle. The GetFileInformationByHandle function does not work with pipe handles.

lpFileInformation

Points to a BY_HANDLE_FILE_INFORMATION structure that receives the file information. The structure can be used in subsequent calls to GetFileInformationByHandle to refer to the information about the file.

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.

Remarks

Depending on the underlying network components of the operating system and the type of server connected to, the GetFileInformationByHandle function may fail, return partial information, or full information for the given file. In general, you should not use GetFileInformationByHandle unless your application is intended to be run on a limited set of operating system configurations.

See Also

BY_HANDLE_FILE_INFORMATION


GetFileSecurity

The GetFileSecurity function obtains specified information about the security of a file or directory. The information obtained is constrained by the caller’s access rights and privileges.

BOOL GetFileSecurity(

LPCTSTR lpFileName,	// address of string for file name
SECURITY_INFORMATION RequestedInformation,	// requested information
PSECURITY_DESCRIPTOR pSecurityDescriptor,	// address of security descriptor
DWORD nLength,	// size of security descriptor buffer
LPDWORD lpnLengthNeeded	// address of required size of buffer
);
Parameters

lpFileName

Points to a null-terminated string specifying the file or directory for which security information is retrieved.

RequestedInformation

Specifies a SECURITY_INFORMATION structure that identifies the security information being requested.

pSecurityDescriptor

Points to a buffer that receives a copy of the security descriptor of the object specified by the lpFileName parameter. The calling process must have the right to view the specified aspects of the object’s security status. The SECURITY_DESCRIPTOR structure is returned in self-relative format.

nLength

Specifies the size, in bytes, of the buffer pointed to by the pSecurityDescriptor parameter.

lpnLengthNeeded

Points to a variable the function sets to zero if the file descriptor is copied successfully. If the buffer is too small for the security descriptor, this variable receives the number of bytes required. If this variable’s value is greater than that of the nLength parameter when the function returns, none of the security descriptor is copied to the buffer.

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.

Remarks

To read the security descriptor of a file or directory, the calling process must have READ_CONTROL access or be the owner of the file or directory.

To read the system access-control list (SACL) of a file or directory, the SE_SECURITY_NAME privilege must be enabled for the calling process.

See Also

GetKernelObjectSecurity, GetPrivateObjectSecurity, GetUserObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetFileSecurity


GetFileSize

The GetFileSize function retrieves the size, in bytes, of the specified file.

DWORD GetFileSize(

HANDLE hFile,	// handle of file to get size of
LPDWORD lpFileSizeHigh	// address of high-order word for file size
);
Parameters

hFile

Specifies an open handle of the file whose size is being returned. The handle must have been created with either GENERIC_READ or GENERIC_WRITE access to the file.

lpFileSizeHigh

Points to the variable where the high-order word of the file size is returned. This parameter can be NULL if the application does not require the high-order word.

Return Values

If the function succeeds, the return value is the low-order doubleword of the file size, and, if lpFileSizeHigh is non-NULL, the function puts the high-order doubleword of the file size into the variable pointed to by that parameter.

If the function fails and lpFileSizeHigh is NULL, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

If the function fails and lpFileSizeHigh is non-NULL, the return value is 0xFFFFFFFF and GetLastError will return a value other than NO_ERROR.

Remarks

You cannot use the GetFileSize function with a handle of a nonseeking device such as a pipe or a communications device. To determine the file type for hFile, use the GetFileType function.

The GetFileSize function obtains the uncompressed size of a file. Use the GetCompressedFileSize function to obtain the compressed size of a file.

Note that if the return value is 0xFFFFFFFF and lpFileSizeHigh is non-NULL, an application must call GetLastError to determine whether the function has succeeded or failed. The following sample code illustrates this point:

//

// Case One: calling the function with

//           lpFileSizeHigh == NULL

// Try to obtain hFile's size

dwSize = GetFileSize (hFile, NULL) ;

// If we failed ...

if (dwSize == 0xFFFFFFFF) {

    // Obtain the error code.

    dwError = GetLastError() ;

    // Deal with that failure.

    .

    .

    .

    } // End of error handler

//

// Case Two: calling the function with

//           lpFileSizeHigh != NULL

// Try to obtain hFile's huge size.

dwSizeLow = GetFileSize (hFile, & dwSizeHigh) ;

// If we failed ...

if (dwSizeLow == 0xFFFFFFFF

    &&

    (dwError = GetLastError()) != NO_ERROR ){

    // Deal with that failure.

    .

    .

    .

    } // End of error handler.

See Also

GetCompressedFileSize, GetFileType


GetFileTime

The GetFileTime function retrieves the date and time that a file was created, last accessed, and last modified.

BOOL GetFileTime(

HANDLE hFile,	// identifies the file
LPFILETIME lpCreationTime,	// address of creation time
LPFILETIME lpLastAccessTime,	// address of last access time
LPFILETIME lpLastWriteTime	// address of last write time
);
Parameters

hFile

Identifies the files for which to get dates and times. The file handle must have been created with GENERIC_READ access to the file.

lpCreationTime

Points to a FILETIME structure to receive the date and time the file was created. This parameter can be NULL if the application does not require this information.

lpLastAccessTime

Points to a FILETIME structure to receive the date and time the file was last accessed. The last access time includes the last time the file was written to, read from, or, in the case of executable files, run. This parameter can be NULL if the application does not require this information.

lpLastWriteTime

Points to a FILETIME structure to receive the date and time the file was last written to. This parameter can be NULL if the application does not require this information.

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.

Remarks

The FAT and New Technology file systems support the file creation, last access, and last write time values.

Windows 95: The precision of the time for a file in a FAT file system is 2 seconds. The time precision for files in other file systems, such as those connected through a network depends on the file system but may also be limited by the remote device.

See Also

FILETIME, GetFileSize, GetFileType, SetFileTime


GetFileTitle

The GetFileTitle function returns the name of the file identified by the lpszFile parameter.

short GetFileTitle(

LPCTSTR lpszFile,	// pointer to full path and filename for file
LPTSTR lpszTitle,	// pointer to buffer that receives filename
WORD cbBuf	// length of buffer
);
Parameters

lpszFile

Pointer to the name and location of a file.

lpszTitle

Pointer to a buffer into which the function is to copy the name of the file.

cbBuf

Specifies the length, in characters, of the buffer pointed to by the lpszTitle parameter.

Return Values

If the function succeeds, the return value is zero.

If the filename is invalid, the return value is a negative number.

If the buffer pointed to by the lpszTitle parameter is too small, the return value is a positive integer that specifies the required buffer size, in bytes (ANSI version) or characters (Unicode version). The required buffer size includes the terminating null character.

Remarks

The GetFileTitle function returns an error value if the buffer pointed to by the lpszFile parameter contains any of the following elements:

•	An empty string

•	A string containing a wildcard (*), opening bracket ([), or closing bracket (])

•	A string that ends with a colon (:), slash mark (/), or backslash (\)

•	A string whose length exceeded the length of the buffer

•	An invalid character (for example, a space or an unprintable character)

To get the buffer size needed for the name of a file, call the function with lpszTitle set to NULL and cbBuf set to zero. The function will return the required size.

GetFileTitle returns the string that the system would use to display the filename to the user. The display name includes an extension only if that is the user’s preference for displaying filenames. This means that the returned string may not accurately identify the file if it is used in calls to file system functions.

If the lpszTitle buffer is too small, GetFileTitle returns the size required to hold the display name. There is no guaranteed connection between the required size and the characters originally specified in the lpszFile buffer. In porting applications to Windows 95 and Windows NT, developers will need to update any code that relies on such behavior in previous versions of the operating system. The most common case is code that deliberately calls GetFileTitle with lpszTitle set to NULL and cbBuf set to zero, and then uses the return value as an index into the lpszFile string. This technique is no longer supported. You can usually achieve similar results (and superior performance) with run-time library functions such as strrchr, wcsrchr, and _mbsrchr.

See Also

GetOpenFileName, GetSaveFileName


GetFileType

The GetFileType function returns the type of the specified file.

DWORD GetFileType(

HANDLE hFile	// file handle
);
Parameters

hFile

Identifies an open file handle.

Return Values

The return value is one of the following values:

Value	Meaning
FILE_TYPE_UNKNOWN	The type of the specified file is unknown.
FILE_TYPE_DISK	The specified file is a disk file.
FILE_TYPE_CHAR	The specified file is a character file, typically an LPT device or a console.
FILE_TYPE_PIPE	The specified file is either a named or anonymous pipe.
See Also

GetFileSize, GetFileTime


GetFileVersionInfo

The GetFileVersionInfo function returns version information about a specified file.

As with other file installation functions, GetFileVersionInfo works only with Win32 file images. It does not work with 16-bit Windows file images.

BOOL GetFileVersionInfo(

LPTSTR lptstrFilename,	// pointer to filename string
DWORD dwHandle,	// ignored
DWORD dwLen,	// size of buffer
LPVOID lpData	// pointer to buffer to receive file-version info.
);
Parameters

lptstrFilename

Pointer to a null-terminated filename string that specifies the file of interest.

dwHandle

This parameter is ignored.

dwLen

Specifies the size, in bytes, of the buffer pointed to by lpData.

Call the GetFileVersionInfoSize function to determine the size in bytes of a file’s version information. dwLen should be equal to or greater than that value.

If the buffer pointed to by lpData is not large enough, the function truncates the file’s-version information to the size of the buffer.

lpData

Pointer to a buffer to receive file-version information.

You can use this value in a subsequent call to the VerQueryValue function.

The file version information is always in Unicode format.

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.

See Also

GetFileVersionInfoSize, VerQueryValue, VS_VERSION_INFO


GetFileVersionInfoSize

The GetFileVersionInfoSize function determines whether the operating system can obtain version information about a specified file. If version information is available, GetFileVersionInfoSize returns the size in bytes of that information.

As with other file installation functions, GetFileVersionInfo works only with Win32 file images. It does not work with 16-bit Windows file images.

DWORD GetFileVersionInfoSize(

LPTSTR lptstrFilename,	// pointer to filename string
LPDWORD lpdwHandle	// pointer to variable to receive zero
);
Parameters

lptstrFilename

Pointer to a null-terminated filename string that specifies the file of interest.

lpdwHandle

Pointer to a variable that the function sets to zero.

Return Values

If the function succeeds, the return value is the size in bytes of the file’s version information.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Call the GetFileVersionInfoSize function before calling the GetFileVersionInfo function.

See Also

GetFileVersionInfo, VerQueryValue


GetFocus

The GetFocus function retrieves the handle of the window that has the keyboard focus, if the window is associated with the calling thread’s message queue.

HWND GetFocus(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the handle of the window with the keyboard focus. If the calling thread’s message queue does not have an associated window with the keyboard focus, the return value is NULL.

Remarks

Even if GetFocus returns NULL, another thread’s queue may be associated with a window that has the keyboard focus.

Use the GetForegroundWindow function to retrieve the handle to the window with which the user is currently working. You can associate your thread’s message queue with the windows owned by another thread by using the AttachThreadInput function.

See Also

AttachThreadInput, GetForegroundWindow, SetFocus, WM_KILLFOCUS, WM_SETFOCUS


GetFontData

The GetFontData function retrieves font metric data for a TrueType font.

DWORD GetFontData(

HDC hdc,	// handle of device context
DWORD dwTable,	// metric table to query
DWORD dwOffset,	// offset into table being queried
LPVOID lpvBuffer,	// address of buffer for returned data
DWORD cbData	// length of data to query
);
Parameters

hdc

Identifies the device context.

dwTable

Specifies the name of a font metric table from which the font data is to be retrieved. This parameter can identify one of the metric tables documented in the TrueType Font Files specification published by Microsoft Corporation. If this parameter is zero, the information is retrieved starting at the beginning of the font file.

dwOffset

Specifies the offset from the beginning of the font metric table to the location where the function should begin retrieving information. If this parameter is zero, the information is retrieved starting at the beginning of the table specified by the dwTable parameter. If this value is greater than or equal to the size of the table, an error occurs.

lpvBuffer

Points to a buffer to receive the font information. If this parameter is NULL, the function returns the size of the buffer required for the font data.

cbData

Specifies the length, in bytes, of the information to be retrieved. If this parameter is zero, GetFontData returns the size of the data specified in the dwTable parameter.

Return Values

If the function succeeds, the return value is the number of bytes returned.

If the function fails, the return value is GDI_ERROR.

Remarks

An application can sometimes use the GetFontData function to save a TrueType font with a document. To do this, the application determines whether the font can be embedded by checking the otmfsType member of the OUTLINETEXTMETRIC structure. If bit 1 of otmfsType is set, embedding is not permitted for the font. If bit 1 is clear, the font can be embedded. If bit 2 is set, the embedding is read-only. If embedding is permitted, the application can retrieve the entire font file, specifying zero for the dwTable, dwOffset, and cbData parameters.

If an application attempts to use this function to retrieve information for a non-TrueType font, an error occurs.

See Also

GetTextMetrics, OUTLINETEXTMETRIC


GetFontLanguageInfo [Now Supported on Windows NT]
GetFontLanguageInfo

[Now Supported on Windows NT]

The GetFontLanguageInfo function returns information about the currently selected font for the specified display context. Applications typically use this information and the GetCharacterPlacement function to prepare a character string for display.

DWORD GetFontLanguageInfo(

HDC hdc	// handle to a device context
);
Parameters

hdc

Handle to a display context.

Return Values

The return value identifies characteristics of the currently selected font. The function returns 0 if the font is “normalized” and can be treated as a simple Latin font; it returns GCP_ERROR if an error occurs. Otherwise, the function returns a combination of the following values:

Value	Meaning
GCP_DBCS	The character set is DBCS.
GCP_DIACRITIC	The font/language contains diacritic glyphs
FLI_GLYPHS	The font contains extra glyphs not normally accessible using the codepage. Use GetCharacterPlacement to access the glyphs. This value is for information only and is not intended to be passed to GetCharacterPlacement.
GCP_GLYPHSHAPE	The font/language contains multiple glyphs per code point or per code point combination (supports shaping and/or ligation), and the font contains advanced glyph tables to provide extra glyphs for the extra shapes. If this value is given, the lpGlyphs array must be used with the GetCharacterPlacement function and the ETO_GLYPHINDEX value must be passed to the ExtTextOut function when the string is drawn.
GCP_KASHIDA	The font/ language permits Kashidas.
GCP_LIGATE	The font/language contains ligation glyphs which can be substituted for specific character combinations.
GCP_USEKERNING	The font contains a kerning table which can be used to provide better spacing between the characters and glyphs.
GCP_REORDER	The language requires reordering for display--for example, Hebrew or Arabic.
The return value, when masked with FLI_MASK, can be passed directly to the GetCharacterPlacement function.

See Also

ExtTextOut, GetCharacterPlacement


GetForegroundWindow

The GetForegroundWindow function returns the handle of the foreground window (the window with which the user is currently working). The system assigns a slightly higher priority to the thread that creates the foreground window than it does to other threads.

HWND GetForegroundWindow(VOID)

Parameters

This function has no parameters.

Return Values

The return value is the handle of the foreground window.

See Also

SetForegroundWindow


GetForm

The GetForm function initializes a FORM_INFO_1 structure with data describing the specified form for a printer.

BOOL GetForm(

HANDLE hPrinter,	// handle of printer
LPTSTR pFormName,	// address of form name
DWORD Level,	// structure level
LPBYTE pForm,	// address of structure array
DWORD cbBuf,	// count of bytes in array
LPDWORD pcbNeeded	// addr. of variable with count of bytes retrieved (or required)
);
Parameters

hPrinter

Identifies the printer.

pFormName

Points to a null-terminated string that specifies the name of the form.

Level

Specifies the version of the structure to which pForm points. This value must be 1.

pForm

Points to an array of bytes that receives the initialized FORM_INFO_1 structure.

cbBuf

Specifies the size, in bytes, of the pForm array.

pcbNeeded

Points to a value that specifies the number of bytes copied if the function succeeds or the number of bytes required if cbBuf is too small.

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.

Remarks

The printer handle hPrinter is obtained by calling the OpenPrinter function.

See Also

AddForm, DeleteForm, OpenPrinter, SetForm


GetFreeSpace

The GetFreeSpace function is obsolete. It is provided to simplify porting of 16-bit Windows-based applications. Win32-based applications should use the GlobalMemoryStatus function.


GetFullPathName

The GetFullPathName function retrieves the full path and filename of a specified file.

DWORD GetFullPathName(

LPCTSTR lpFileName,	// address of name of file to find path for
DWORD nBufferLength,	// size, in characters, of path buffer
LPTSTR lpBuffer,	// address of path buffer
LPTSTR *lpFilePart	// address of filename in path
);
Parameters

lpFileName

Points to a null-terminated string that specifies a valid filename. This string can use either short (the 8.3 form) or long filenames.

nBufferLength

Specifies the size, in characters, of the buffer for the drive and path.

lpBuffer

Points to a buffer that contains the null-terminated string for the name of the drive and path.

lpFilePart

Points to a variable that receives the address (in lpBuffer) of the final filename component in the path. This filename component is the long filename, if any, rather than the 8.3 form of the filename.

Return Values

If the GetFullPathName function succeeds, the return value is the length, in characters, of the string copied to lpBuffer, not including the terminating null character.

If the lpBuffer buffer is too small, the return value is the size of the buffer, in characters, required to hold the path.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The GetFullPathName function merges the name of the current drive and directory with the specified filename to determine the full path and filename of the specified file. It also calculates the address of the filename portion of the full path and filename. This function does not verify that the resulting path and filename are valid or that they refer to an existing file on the associated volume.

See Also

GetShortPathName, GetTempPath, SearchPath


GetGlyphOutline

The GetGlyphOutline function retrieves the outline or bitmap for a character in the TrueType font that is selected into the specified device context.

DWORD GetGlyphOutline(

HDC hdc,	// handle of device context
UINT uChar,	// character to query
UINT uFormat,	// format of data to return
LPGLYPHMETRICS lpgm,	// address of structure for metrics
DWORD cbBuffer,	// size of buffer for data
LPVOID lpvBuffer,	// address of buffer for data
CONST MAT2 *lpmat2	// address of transformation matrix structure
);
Parameters

hdc

Identifies the device context.

uChar

Specifies the character for which data is to be returned.

uFormat

Specifies the format of the data that the function retrieves. Use one of the following values:

Value	Meaning
GGO_BITMAP	The function retrieves the glyph bitmap. For information about memory allocation, see the following Remarks section.
GGO_NATIVE	The function retrieves the curve data points in the rasterizer’s native format and uses the font’s design units. When this value is specified, any transformation specified in the lpMatrix parameter is ignored.
GGO_METRICS	The function only retrieves the GLYPHMETRICS structure specified by lpgm. The other buffers are ignored. This value affects the meaning of the function’s return value upon failure; see the following Return Value section.
GGO_GRAY2_BITMAP	The function retrieves a glyph bitmap that contains 5 levels of gray.
GGO_GRAY4_BITMAP	The function retrieves a glyph bitmap that contains 17 levels of gray.
GGO_GRAY8_BITMAP	The function retrieves a glyph bitmap that contains 65 levels of gray.
Note that, for the GGO_GRAYn_BITMAP values, the function retrieves a glyph bitmap that contains n^2+1 (n squared plus one) levels of gray.

lpgm

Points to the GLYPHMETRICS structure describing the placement of the glyph in the character cell.

cbBuffer

Specifies the size of the buffer where the function is to copy information about the outline character. If this value is zero, the function returns the required size of the buffer.

lpvBuffer

Points to the buffer where the function is to copy information about the outline character. If this value is NULL, the function returns the required size of the buffer.

lpmat2

Points to a MAT2 structure specifying a transformation matrix for the character.

Return Values

If GGO_BITMAP, GGO_GRAY2_BITMAP, GGO_GRAY4_BITMAP, GGO_GRAY8_BITMAP, or GGO_NATIVE is specified and the function succeeds, the return value is greater than zero; otherwise, the return value is GDI_ERROR. If one of these flags is specified and the buffer size or address is zero, the return value specifies the required buffer size, in bytes.

If GGO_METRICS is specified and the function fails, the return value is GDI_ERROR.

Remarks

The glyph outline returned by the GetGlyphOutline function is for a grid-fitted glyph. (A grid-fitted glyph is a glyph that has been modified so that its bitmapped image conforms as closely as possible to the original design of the glyph.) If an application needs an unmodified glyph outline, it can request the glyph outline for a character in a font whose size is equal to the font’s em unit. The value for a font’s em unit is stored in the otmEMSquare member of the OUTLINETEXTMETRIC structure.

The glyph bitmap returned by GetGlyphOutline when GGO_BITMAP is specified is a doubleword-aligned, row-oriented, monochrome bitmap. When GGO_GRAY2_BITMAP is specified, the bitmap returned is a doubleword-aligned, row-oriented array of bytes whose values range from 0 to 4. When GGO_GRAY4_BITMAP is specified, the bitmap returned is a doubleword-aligned, row-oriented array of bytes whose values range from 0 to 16. When GGO_GRAY8_BITMAP is specified, the bitmap returned is a doubleword-aligned, row-oriented array of bytes whose values range from 0 to 255.

An application can rotate characters retrieved in bitmap format by specifying a 2-by-2 transformation matrix in the lpMatrix parameter.

See Also

FORM_INFO_1, GetOutlineTextMetrics, GLYPHMETRICS, MAT2, OUTLINETEXTMETRIC, POINT


GetGraphicsMode

The GetGraphicsMode function retrieves the current graphics mode for the specified device context.

int GetGraphicsMode(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Values

If the function succeeds, the return value is the current graphics mode. It can be one of the following values:

Value	Meaning
GM_COMPATIBLE	The current graphics mode is the compatible graphics mode, a mode that is compatible with Windows version 3.1. In this graphics mode, an application cannot set or modify the world transformation for the specified device context. The compatible graphics mode is the default graphics mode.
GM_ADVANCED	Windows NT: The current graphics mode is the advanced graphics mode, a mode that allows world transformations. In this graphics mode, an application can set or modify the world transformation for the specified device context. Windows 95: The GM_ADVANCED value is not supported.
Otherwise, the return value is zero.

Remarks

An application can set the graphics mode for a device context by calling the SetGraphicsMode function.

See Also

SetGraphicsMode


GetHandleInformation

The GetHandleInformation function obtains information about certain properties of an object handle. The information is obtained as a set of bit flags.

BOOL GetHandleInformation (

HANDLE hObject,	// handle to an object
LPDWORD lpdwFlags	// points to variable to receive flags
);
Parameters

hObject

Specifies a handle to an object. The GetHandleInformation function obtains information about this object handle.

lpdwFlags

Points to a variable to receive a set of bit flags that specify properties of the object handle. The following flags are defined:

Value	Meaning
HANDLE_FLAG_INHERIT	If this flag is set, a child process created with the bInheritHandles parameter of CreateProcess set to TRUE will inherit the object handle.
HANDLE_FLAG_PROTECT_FROM_CLOSE	If this flag is set, calling the CloseHandle function will not close the object handle.
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.

See Also

CloseHandle, CreateProcess, SetHandleInformation


GetICMProfile

The GetICMProfile function retrieves the name of the color profile file for the device associated with the specified device context.

BOOL GetICMProfile(

HDC hdc,
LPDWORD lpcbName,
LPTSTR lpszFilename
);
Parameters

hdc

Handle to the device context.

lpcbName

Pointer to a DWORD that contains the size, in bytes or characters, of the buffer that receives the filename, depending on whether the ANSI or Unicode version of the function is used.

If the buffer is too small, the function fails, and sets the DWORD pointed to by lpcbName to the minimum required buffer size.

lpszFilename

Pointer to the buffer that receives the null-terminated string specifying the full path of the color profile file.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The function obtains the image color matching profile for the device context regardless of whether image color matching (ICM) is enabled for the device context specified by hdc.

See Also

SetICMProfile


GetIconInfo

The GetIconInfo function retrieves information about the specified icon or cursor.

BOOL GetIconInfo(

HICON hIcon,	// icon handle
PICONINFO piconinfo	// address of icon structure
);
Parameters

hIcon

Identifies the icon or cursor. To retrieve information about a standard icon or cursor, specify one of the following values:

Value	Meaning
IDC_ARROW	Arrow cursor
IDC_IBEAM	I-beam cursor
IDC_WAIT	Hourglass cursor
IDC_CROSS	Crosshair cursor
IDC_UPARROW	Up arrow cursor
IDC_SIZENWSE	Sizing cursor, points northwest and southeast
IDC_SIZENESW	Sizeing cursor, points northeast and southwest
IDC_SIZEWE	Sizing cursor, points west and east
IDC_SIZENS	Sizing cursor, points north and south
IDC_SIZEALL	Sizing cursor, points north, south, east, and west
IDC_NO	“No” cursor
IDC_APPSTARTING	Application-starting cursor (arrow and hourglass)
IDC_HELP	Help cursor (arrow and question mark)
IDI_APPLICATION	Application icon
IDI_HAND	Stop sign icon
IDI_QUESTION	Question-mark icon
IDI_EXCLAMATION	Exclamation point icon
IDI_ASTERISK	Asterisk icon (letter “i” in a circle)
IDI_WINLOGO	Windows logo icon
piconinfo

Points to an ICONINFO structure. The function fills in the structure’s members.

Return Values

If the function succeeds, the return value is nonzero and the function fills in the members of the specified ICONINFO structure.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

GetIconInfo creates bitmaps for the hbmMask and hbmColor members of ICONINFO. The calling application must manage these bitmaps and delete them when they are no longer necessary.

See Also

CreateIcon, CreateIconFromResource, CreateIconIndirect, DestroyIcon, DrawIcon, DrawIconEx, ICONINFO, LoadIcon, LookupIconIdFromDirectory


GetInputState

The GetInputState function determines whether there are mouse-button or keyboard messages in the calling thread’s message queue.

BOOL GetInputState(VOID)

Parameters

This function has no parameters.

Return Values

If the queue contains one or more new mouse-button or keyboard messages, the return value is nonzero.

If the there are no new mouse-button or keyboard messages in the queue, the return value is zero.

See Also

GetQueueStatus


GetJob

The GetJob function retrieves print-job data for the specified printer.

BOOL GetJob(

HANDLE hPrinter,	// handle of printer
DWORD JobId,	// job identifier value
DWORD Level,	// data-structure level
LPBYTE pJob,	// address of data-structure array
DWORD cbBuf,	// count of bytes in array
LPDWORD pcbNeeded	// address of value that contains count of bytes retrieved (or required)
);
Parameters

hPrinter

Identifies the printer for which the print-job data is retrieved.

JobId

Identifies the print job for which data should be retrieved.

Level

Specifies the level of the structure to which pJob points. This value must be either 1 or 2.

pJob

Points to an array that contains either a JOB_INFO_1 or a JOB_INFO_2 structure. If Level is 1, this function stores the data in a JOB_INFO_1 structure; if Level is 2, this function stores the data in a JOB_INFO_2 structure.

cbBuf

Specifies the size, in bytes, of the array.

pcbNeeded

Points to a value that specifies the number of bytes copied if the function succeeds or the number of bytes required if cbBuf is too small.

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.

See Also

AddJob, JOB_INFO_1, JOB_INFO_2, ScheduleJob, SetJob


GetKBCodePage

The GetKBCodePage function is provided for compatibility with earlier versions of Windows. In the Win32 application programming interface (API) it just calls the GetOEMCP function. New applications should use the GetOEMCP function.

UINT GetKBCodePage(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is an OEM code-page identifier, or it is the default identifier if the registry value is not readable. For a list of OEM code-page identifiers, see GetOEMCP.

See Also

GetACP, GetOEMCP


GetKernelObjectSecurity

The GetKernelObjectSecurity function retrieves a copy of the security descriptor protecting a kernel object.

BOOL GetKernelObjectSecurity(

HANDLE Handle,	// handle of object to query
SECURITY_INFORMATION RequestedInformation,	// requested information
PSECURITY_DESCRIPTOR pSecurityDescriptor,	// address of security descriptor
DWORD nLength,	// size of buffer for security descriptor
LPDWORD lpnLengthNeeded	// address of required size of buffer
);
Parameters

Handle

Identifies a kernel object.

RequestedInformation

Specifies a SECURITY_INFORMATION structure that identifies the security information being requested.

pSecurityDescriptor

Points to a buffer the function fills with a copy of the security descriptor of the specified object. The calling process must have the right to view the specified aspects of the object’s security status. The SECURITY_DESCRIPTOR structure is returned in self-relative format.

nLength

Specifies the size, in bytes, of the buffer pointed to by the pSecurityDescriptor parameter.

lpnLengthNeeded

Points to a variable the function sets to zero if the descriptor is copied successfully. If the buffer is too small for the security descriptor, this variable receives the number of bytes required. If this variable’s value is greater than the value of the nLength parameter when the function returns, none of the security descriptor is copied to the buffer.

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.

Remarks

To read the kernel object’s security descriptor, the calling process must be either granted READ_CONTROL access or be the object’s owner. In addition, the calling process must have the SE_SECURITY_NAME privilege to read the system access-control list.

See Also

GetFileSecurity, GetPrivateObjectSecurity, GetUserObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetKernelObjectSecurity


GetKerningPairs

The GetKerningPairs function retrieves the character-kerning pairs for the currently selected font for the specified device context.

DWORD GetKerningPairs(

HDC hdc,	// handle of device context
DWORD nNumPairs,	// number of kerning-pairs to be retrieved
LPKERNINGPAIR lpkrnpair	// address of kerning-pair array
);
Parameters

hdc

Identifies the device context.

nNumPairs

Specifies the number of pairs that fit in the lpkrnpair array. If the font has more than nNumPairs kerning pairs, an error is returned.

lpkrnpair

Points to an array of KERNINGPAIR structures to receive the kerning pairs. The array must contain at least as many structures as specified by the nNumPairs parameter. If this parameter is NULL, the function returns the total number of kerning pairs for the font.

Return Values

If the function succeeds, the return value is the number of kerning pairs returned.

If the function fails, the return value is zero.

See Also

KERNINGPAIR


GetKeyboardLayout [Now Supported on Windows NT]
GetKeyboardLayout

[Now Supported on Windows NT]

The GetKeyboardLayout function retrieves the active keyboard layout for a specified thread. If the dwLayout parameter is zero, the layout for the active thread is returned.

HKL GetKeyboardLayout(

DWORD dwLayout	// thread identifier
);
Parameters

dwLayout

Identifies the thread to query or is zero for the current thread.

Return Values

The return value is the keyboard layout handle for the thread. The low word contains a locale identifier identifying the input language and the high word contains a device handle identifying the physical layout of the keyboard.

See Also

ActivateKeyboardLayout, CreateThread, LoadKeyboardLayout


GetKeyboardLayoutList [Now Supported on Windows NT]
GetKeyboardLayoutList

[Now Supported on Windows NT]

The GetKeyboardLayoutList function retrieves the keyboard layout handles corresponding to the current set of input locales in the system. The function copies the handles to the given buffer.

UINT GetKeyboardLayoutList(

int nBuff,	// size of buffer in array element
HKL FAR *lpList	// buffer for keyboard layout handles
);
Parameters

nBuff

Specifies the maximum number of handles that the buffer can hold.

lpList

Points to the buffer, an array, that receives the keyboard layout handles.

Return Values

If the function succeeds, the return value is the number of layout handles copied to the buffer or, if nBuff is zero, the return value is the size, in array elements, of the buffer needed to receive all current layout handles.

See Also

GetKeyboardLayout


GetKeyboardLayoutName

The GetKeyboardLayoutName function retrieves the name of the active keyboard layout.

BOOL GetKeyboardLayoutName(

LPTSTR pwszKLID	// address of buffer for layout name
);
Parameters

pwszKLID

Points to the buffer of at least KL_NAMELENGTH characters that is to receive the name of the keyboard layout, including the NULL terminator. This will be a copy of the string provided to the LoadKeyboardLayout function, unless layout substitution took place.

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.

Remarks

Windows NT:

GetKeyboardLayoutName gets the name of the active keyboard layout for the system.

Windows 95:

GetKeyboardLayoutName gets the name of the active keyboard layout for the calling thread.

See Also

ActivateKeyboardLayout, LoadKeyboardLayout, UnloadKeyboardLayout


GetKeyboardState

The GetKeyboardState function copies the status of the 256 virtual keys to the specified buffer.

BOOL GetKeyboardState(

PBYTE lpKeyState	// address of array to receive status data
);
Parameters

lpKeyState

Points to the 256-byte array that will receive the status data for each virtual key.

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.

Remarks

An application can call this function to retrieve the current status of all the virtual keys. The status changes as a thread removes keyboard messages from its message queue. The status does not change as keyboard messages are posted to the message queue.

When the function returns, each member of the array pointed to by the lpKeyState parameter contains status data for a virtual key. If the high-order bit is 1, the key is down; otherwise, it is up. If the low-order bit is 1, the key is toggled. A key, such as the CAPS LOCK key, is toggled if it is turned on. The key is off and untoggled if the low-order bit is 0. A toggle key’s indicator light (if any) on the keyboard will be on when the key is toggled, and off when the key is untoggled.

To retrieve status information for an individual key, use the GetKeyState function.

An application can use the virtual-key code constants VK_SHIFT, VK_CONTROL and VK_MENU as indices into the array pointed to by lpKeyState. This gives the status of the SHIFT, CTRL, or ALT keys without distinguishing between left and right. An application can also use the following virtual-key code constants as indices to distinguish between the left and right instances of those keys:

VK_LSHIFT	VK_RSHIFT
VK_LCONTROL	VK_RCONTROL
VK_LMENU	VK_RMENU
These left- and right-distinguishing constants are available to an application only through the GetKeyboardState, SetKeyboardState, GetAsyncKeyState, GetKeyState, and MapVirtualKey functions.

See Also

GetKeyState, GetAsyncKeyState, MapVirtualKey, SetKeyboardState


GetKeyboardType

The GetKeyboardType function retrieves information about the current keyboard.

int GetKeyboardType(

int nTypeFlag	// type of information to retrieve
);
Parameters

nTypeFlag

Specifies the type of keyboard information to be retrieved. This parameter can be one of the following values:

Value	Meaning
0	Keyboard type
1	Keyboard subtype
2	Number of function keys on the keyboard
Return Values

If the function succeeds, the return value specifies the requested information.

If the function fails, the return value is zero.

Remarks

The subtype is an original equipment manufacturer (OEM)-dependent value. The type may be one of the following values:

Value	Meaning
1	IBM PC/XT or compatible (83-key) keyboard
2	Olivetti “ICO” (102-key) keyboard
3	IBM PC/AT (84-key) or similar keyboard
4	IBM enhanced (101- or 102-key) keyboard
5	Nokia 1050 and similar keyboards
6	Nokia 9140 and similar keyboards
7	Japanese keyboard
The application can also determine the number of function keys on a keyboard from the keyboard type. Following are the number of function keys for each keyboard type:

Type	Number of function keys
1	10
2	12 (sometimes 18)
3	10
4	12
5	10
6	24
7	Hardware dependent and specified by the OEM


GetKeyNameText

The GetKeyNameText function retrieves a string that represents the name of a key.

int GetKeyNameText(

LONG lParam,	// second parameter of keyboard message
LPTSTR lpString,	// address of buffer for key name
int nSize	// maximum length of key-name string length
);
Parameters

lParam

Specifies the second parameter of the keyboard message (such as WM_KEYDOWN) to be processed. The function interprets the following portions of lParam:

Bits	Meaning
16−23	Scan code.
24	Extended-key flag. Distinguishes some keys on an enhanced keyboard.
25	“Don’t care” bit. The application calling this function sets this bit to indicate that the function should not distinguish between left and right CTRL and SHIFT keys, for example.
lpString

Points to a buffer that will receive the key name.

nSize

Specifies the maximum length, in characters, of the key name, including the terminating null character. (This parameter should be equal to the size of the buffer pointed to by the lpString parameter.)

Return Values

If the function succeeds, a null-terminated string is copied into the specified buffer, and the return value is the length of the string, in characters, not counting the terminating null character.

Remarks

The format of the key-name string depends on the current keyboard layout. The keyboard driver maintains a list of names in the form of character strings for keys with names longer than a single character. The key name is translated according to the layout of the currently installed keyboard. The name of a character key is the character itself. The names of dead keys are spelled out in full.


GetKeyState

The GetKeyState function retrieves the status of the specified virtual key. The status specifies whether the key is up, down, or toggled (on, off — alternating each time the key is pressed).

SHORT GetKeyState(

int nVirtKey	// virtual-key code
);
Parameters

nVirtKey

Specifies a virtual key. If the desired virtual key is a letter or digit (A through Z, a through z, or 0 through 9), nVirtKey must be set to the ASCII value of that character. For other keys, it must be a virtual-key code.

If a non-English keyboard layout is used, virtual keys with values in the range ASCII A through Z and 0 through 9 are used to specify most of the character keys. For example, for the German keyboard layout, the virtual key of value ASCII O (0x4F) refers to the “o” key, whereas VK_OEM_1 refers to the “o with umlaut” key.

Return Values

If the function succeeds, the return value specifies the status of the given virtual key. If the high-order bit is 1, the key is down; otherwise, it is up. If the low-order bit is 1, the key is toggled. A key, such as the CAPS LOCK key, is toggled if it is turned on. The key is off and untoggled if the low-order bit is 0. A toggle key’s indicator light (if any) on the keyboard will be on when the key is toggled, and off when the key is untoggled.

Remarks

The key status returned from this function changes as a given thread reads key messages from its message queue. The status does not reflect the interrupt-level state associated with the hardware. Use the GetAsyncKeyState function to retrieve that information.

An application calls GetKeyState in response to a keyboard-input message. This function retrieves the state of the key when the input message was generated.

To retrieve state information for all the virtual keys, use the GetKeyboardState function.

An application can use the virtual-key code constants VK_SHIFT, VK_CONTROL, and VK_MENU as values for the nVirtKey parameter. This gives the status of the SHIFT, CTRL, or ALT keys without distinguishing between left and right. An application can also use the following virtual-key code constants as values for nVirtKey to distinguish between the left and right instances of those keys:

VK_LSHIFT	VK_RSHIFT
VK_LCONTROL	VK_RCONTROL
VK_LMENU	VK_RMENU
These left- and right-distinguishing constants are available to an application only through the GetKeyboardState, SetKeyboardState, GetAsyncKeyState, GetKeyState, and MapVirtualKey functions.

See Also

GetAsyncKeyState, GetKeyboardState, MapVirtualKey, SetKeyboardState


GetLargestConsoleWindowSize

The GetLargestConsoleWindowSize function returns the size of the largest possible console window, based on the current font and the size of the display.

COORD GetLargestConsoleWindowSize(

HANDLE hConsoleOutput	// handle of console screen buffer
);
Parameters

hConsoleOutput

Identifies a console screen buffer.

Return Values

If the function succeeds, the return value is a COORD structure that specifies the number of character cell rows (X member) and columns (Y member) in the largest possible console window. Otherwise, the members of the structure are zero.

To get extended error information, call GetLastError.

Remarks

The function does not take into consideration the size of the screen buffer, which means that the window size returned may be larger than the size of the screen buffer. The GetConsoleScreenBufferInfo function can be used to determine the maximum size of the console window, given the current screen buffer size, the current font, and the display size.

See Also

COORD, GetConsoleScreenBufferInfo, SetConsoleWindowInfo


GetLastActivePopup

The GetLastActivePopup function determines which pop-up window owned by the specified window was most recently active.

HWND GetLastActivePopup(

HWND hWnd	// handle of owner window
);
Parameters

hWnd

Identifies the owner window.

Return Values

The return value identifies the most recently active pop-up window. The return value is the same as the hWnd parameter, if any of the following conditions are met:

•	The window identified by hWnd was most recently active.

•	The window identified by hWnd does not own any pop-up windows.

•	The window identified by hWnd is not a top-level window or it is owned by another window.

See Also

AnyPopup, ShowOwnedPopups


GetLastError

The GetLastError function returns the calling thread’s last-error code value. The last-error code is maintained on a per-thread basis. Multiple threads do not overwrite each other’s last-error code.

DWORD GetLastError(VOID)

Parameters

This function has no parameters.

Return Values

The return value is the calling thread’s last-error code value. Functions set this value by calling the SetLastError function. The Return Value section of each reference page notes the conditions under which the function sets the last-error code.

Remarks

You should call the GetLastError function immediately when a function’s return value indicates that such a call will return useful data. That is because some functions call SetLastError(0) when they succeed, wiping out the error code set by the most recently failed function.

Most functions in the Win32 API that set the thread’s last error code value set it when they fail; a few functions set it when they succeed. Function failure is typically indicated by a return value error code such as FALSE, NULL, 0xFFFFFFFF, or −1. Some functions call SetLastError under conditions of success; those cases are noted in each function’s reference page.

Error codes are 32-bit values (bit 31 is the most significant bit). Bit 29 is reserved for application-defined error codes; no system error code has this bit set. If you are defining an error code for your application, set this bit to one. That indicates that the error code has been defined by an application, and ensures that your error code does not conflict with any error codes defined by the operating system.

To obtain an error string for operating system error codes, use the FormatMessage function. For a complete list of error codes, see the WINNT.H header file in the Win32 SDK.

See Also

FormatMessage, SetLastError, SetLastErrorEx


GetLengthSid

The GetLengthSid function returns the length, in bytes, of a valid SID structure. A SID is a security identifier.

DWORD GetLengthSid(

PSID pSid	// address of SID to query
);
Parameters

pSid

Points to the SID structure whose length is returned. The structure is assumed to be valid.

Return Values

If the function succeeds, the return value is the length, in bytes, of the SID structure. If the SID structure is not valid, the return value is undefined. To get extended error information, call GetLastError.

See Also

GetSidLengthRequired, GetSidSubAuthorityCount, IsValidSid, SID


GetLocaleInfo

The GetLocaleInfo function retrieves information about a locale.

int GetLocaleInfo(

LCID Locale,	// locale identifier
LCTYPE LCType,	// type of information
LPTSTR lpLCData,	// address of buffer for information
int cchData	// size of buffer
);
Parameters

Locale

Specifies the locale to retrieve information for. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
LCType

Specifies one of the LCTYPE constants to indicate the type of information to be retrieved.

All LCTYPE values are mutually exclusive, with the exception of LOCALE_NOUSEROVERRIDE. An application may use the binary-OR operator to combine LOCALE_NOUSEROVERRIDE with any other LCTYPE value. If passed such an LCType value, the function bypasses user overrides, and returns the system default value for the requested LCID.

lpLCData

Points to a buffer to receive the requested data.

cchData

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the lpLCData buffer. If cchData is zero, the function returns the number of bytes or characters required to hold the information, and the buffer pointed to by lpLCData is not used.

Return Values

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) written to the destination buffer, or if the cchData parameter is zero, the number of bytes or characters required to hold the locale information.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

Remarks

The GetLocaleInfo function always retrieves information in text format. If the information is a numeric value, the function converts the number to text using decimal notation.

See Also

GetStringTypeA, GetStringTypeEx, GetStringTypeW, GetSystemDefaultLCID, GetUserDefaultLCID, SetLocaleInfo, MAKELCID


GetLocalTime

The GetLocalTime function retrieves the current local date and time.

VOID GetLocalTime(

LPSYSTEMTIME lpSystemTime	// address of system time structure
);
Parameters

lpSystemTime

Points to a SYSTEMTIME structure to receive the current local date and time.

Return Values

This function does not return a value.

See Also

GetSystemTime, SetLocalTime, SYSTEMTIME


GetLogColorSpace

The GetLogColorSpace function retrieves information about the logical color space identified by the specified handle.

BOOL GetLogColorSpace(

HCOLORSPACE hColorSpace,
LPLOGCOLORSPACE lpbuffer,
DWORD nSize
);
Parameters

hColorSpace

Handle to the logical color space.

lpBuffer

Pointer to the LOGCOLORSPACE structure that receives the logical color space information.

nSize

Maximum size of the buffer, in bytes.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

GetLogColorSpace copies as much information to the buffer as space allows. To determine the correct size of the buffer to use, applications should check the lcsSize member in the structure.

See Also

LOGCOLORSPACE


GetLogicalDrives

The GetLogicalDrives function returns a bitmask representing the currently available disk drives.

DWORD GetLogicalDrives(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is a bitmask representing the currently available disk drives. Bit position 0 (the least-significant bit) is drive A, bit position 1 is drive B, bit position 2 is drive C, and so on.

If the function fails, the return value is zero.

See Also

GetLogicalDriveStrings


GetLogicalDriveStrings

The GetLogicalDriveStrings function fills a buffer with strings that specify valid drives in the system.

DWORD GetLogicalDriveStrings(

DWORD nBufferLength,	// size of buffer
LPTSTR lpBuffer	// address of buffer for drive strings
);
Parameters

nBufferLength

Specifies the maximum size, in characters, of the buffer pointed to by lpBuffer. This size does not include the terminating null character.

lpBuffer

Points to a buffer that receives a series of null-terminated strings, one for each valid drive in the system, that end with a second null character. The following example shows the buffer contents with <null> representing the terminating null character.

c:\<null>d:\<null><null>

Return Values

If the function succeeds, the return value is the length, in characters, of the strings copied to the buffer, not including the terminating null character. Note that an ANSI-ASCII null character uses one byte, but a Unicode null character uses two bytes.

If the buffer is not large enough, the return value is greater than nBufferLength. It is the size of the buffer required to hold the drive strings.

If the function fails, the return value is zero. To get extended error information, use the GetLastError function.

Remarks

Each string in the buffer may be used wherever a root directory is required, such as for the GetDriveType and GetDiskFreeSpace functions.

See Also

GetDriveType, GetDiskFreeSpace, GetLogicalDrives


GetMailslotInfo

The GetMailslotInfo function retrieves information about the specified mailslot.

BOOL GetMailslotInfo(

HANDLE hMailslot,	// mailslot handle
LPDWORD lpMaxMessageSize,	// address of maximum message size
LPDWORD lpNextSize,	// address of size of next message
LPDWORD lpMessageCount,	// address of number of messages
LPDWORD lpReadTimeout	// address of read time-out
);
Parameters

hMailslot

Identifies a mailslot. The CreateMailslot function must create this handle.

lpMaxMessageSize

Points to a buffer specifying the maximum message size, in bytes, allowed for this mailslot, when the function returns. This value can be greater than or equal to the value specified in the cbMaxMsg parameter of the CreateMailslot function that created the mailslot. This parameter can be NULL.

lpNextSize

Points to a buffer specifying the size, in bytes, of the next message, when the function returns. The following value has special meaning:

Value	Meaning
MAILSLOT_NO_MESSAGE	There is no next message.
This parameter can be NULL.

lpMessageCount

Points to a buffer specifying the total number of messages waiting to be read, when the function returns. This parameter can be NULL.

lpReadTimeout

Points to a buffer specifying the amount of time, in milliseconds, a read operation can wait for a message to be written to the mailslot before a time-out occurs. This parameter is filled in when the function returns. This parameter can be NULL.

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.

See Also

CreateMailslot, SetMailslotInfo


GetMapMode

The GetMapMode function retrieves the current mapping mode.

int GetMapMode(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Values

If the function succeeds, the return value specifies the mapping mode.

If the function fails, the return value is zero.

Remarks

The following list describes the various mapping modes:

Value	Description
MM_ANISOTROPIC	Logical units are mapped to arbitrary units with arbitrarily scaled axes. Use the SetWindowExtEx and SetViewportExtEx functions to specify the units, orientation, and scaling that you want.
MM_HIENGLISH	Each logical unit is mapped to 0.001 inch. Positive x is to the right; positive y is up.
MM_HIMETRIC	Each logical unit is mapped to 0.01 millimeter. Positive x is to the right; positive y is up.
MM_ISOTROPIC	Logical units are mapped to arbitrary units with equally scaled axes; that is, one unit along the x-axis is equal to one unit along the y-axis. Use the SetWindowExtEx and SetViewportExtEx functions to specify the units and the orientation of the axes that you want. Graphics device interface makes adjustments as necessary to ensure the x and y units remain the same size (for example, if you set the window extent, the viewport will be adjusted to keep the units isotropic).
MM_LOENGLISH	Each logical unit is mapped to 0.01 inch. Positive x is to the right; positive y is up.
MM_LOMETRIC	Each logical unit is mapped to 0.1 millimeter. Positive x is to the right; positive y is up.
MM_TEXT	Each logical unit is mapped to one device pixel. Positive x is to the right; positive y is down.
MM_TWIPS	Each logical unit is mapped to one twentieth of a printer’s point (1/1440 inch, also called a “twip”). Positive x is to the right; positive y is up.
See Also

SetMapMode, SetWindowExtEx, SetViewportExtEx


GetMenu

The GetMenu function retrieves the handle of the menu assigned to the given window.

HMENU GetMenu(

HWND hWnd	// handle of window
);
Parameters

hWnd

Identifies the window whose menu handle is retrieved.

Return Values

If the function succeeds, the return value is the handle of the menu. If the given window has no menu, the return value is NULL. If the window is a child window, the return value is undefined.

See Also

GetSubMenu, SetMenu


GetMenuCheckMarkDimensions

This function is obsolete. Use the GetSystemMetrics with the CXMENUCHECK and CYMENUCHECK values to retrieve the bitmap dimensions.

The GetMenuCheckMarkDimensions function returns the dimensions of the default check mark bitmap. Windows displays this bitmap next to checked menu items. Before calling the SetMenuItemBitmaps function to replace the default check mark bitmap for a menu item, an application must determine the correct bitmap size by calling GetMenuCheckMarkDimensions.

LONG GetMenuCheckMarkDimensions(VOID)

Parameters

This function has no parameters.

Return Values

The return value specifies the height and width, in pixels, of the default check mark bitmap. The high-order word contains the height; the low-order word contains the width.

See Also

SetMenuItemBitmaps


GetMenuContextHelpId

The GetMenuContextHelpId function retrieves the help context identifier associated with the specified menu.

DWORD GetMenuContextHelpId(

HMENU hmenu
);
Parameters

hmenu

Handle to the menu for which the help context identifier is to be retrieved.

Return Values

Returns the help context identifier if the menu has one or zero otherwise.

See Also

SetMenuContextHelpId


GetMenuDefaultItem [Now Supported on Windows NT]
GetMenuDefaultItem

[Now Supported on Windows NT]

The GetMenuDefaultItem function determines the default menu item on the specified menu.

UINT WINAPI GetMenuDefaultItem(

HMENU hMenu,
UINT fByPos,
UINT gmdiFlags
);
Parameters

hMenu

Handle to the menu for which to retrieve the default menu item.

fByPos

Value specifying whether to retrieve the menu item’s identifier or its position. If this parameter is FALSE, the identifier is returned. Otherwise, the position is returned.

gmdiFlags

Value specifying how the function searches for menu items. This parameter can be zero or more of the following values:

Value	Meaning
GMDI_GOINTOPOPUPS	Specifies that if the default item is one that opens a submenu, the function is to search recursively in the corresponding submenu. If the submenu has no default item, the return value identifies the item that opens the submenu. By default, the function returns the first default item on the specified menu, regardless of whether it is an item that opens a submenu.
GMDI_USEDISABLED	Specifies that the function is to return a default item, even if it is disabled.  By default, the function skips disabled or grayed items.
Return Values

If the function succeeds, the return value is the identifier or position of the menu item.

If the function fails, the return value is − 1.

See Also

SetMenuDefaultItem


GetMenuItemCount

The GetMenuItemCount function determines the number of items in the specified menu.

int GetMenuItemCount(

HMENU hMenu	// handle of menu
);
Parameters

hMenu

Identifies the handle of the menu to be examined.

Return Values

If the function succeeds, the return value specifies the number of items in the menu.

If the function fails, the return value is −1. To get extended error information, call GetLastError.

See Also

GetMenuItemID


GetMenuItemID

The GetMenuItemID function retrieves the menu item identifier of a menu item located at the specified position in a menu.

UINT GetMenuItemID(

HMENU hMenu,	// handle of menu
int nPos	// position of menu item
);
Parameters

hMenu

Identifies the menu that contains the item whose identifier is to be retrieved.

nPos

Specifies the zero-based relative position of the menu item whose identifier is to be retrieved.

Return Values

If the function succeeds, the return value specifies the identifier of the given menu item. If the menu item identifier is NULL or if the specified item opens a submenu, the return value is 0xFFFFFFFF.

See Also

GetMenuItemCount, GetMenuString


GetMenuItemInfo [Now Supported on Windows NT]
GetMenuItemInfo

[Now Supported on Windows NT]

The GetMenuItemInfo function retrieves information about a menu item.

BOOL WINAPI GetMenuItemInfo(

HMENU hMenu,
UINT uItem,
BOOL fByPosition,
LPMENUITEMINFO lpmii
);
Parameters

hMenu

Handle to the menu that contains the menu item.

uItem

Identifier or position of the menu item to get information about. The meaning of this parameter depends on the value of fByPosition.

fByPosition

Value specifying the meaning of uItem. If this parameter is FALSE, uItem is a menu item identifier. Otherwise, it is a menu item position.

lpmii

Pointer to a MENUITEMINFO structure that specifies the information to retrieve and receives information about the menu item.

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, use the GetLastError function.

See Also

SetMenuItemInfo, MENUITEMINFO


GetMenuItemRect [Now Supported on Windows NT]
GetMenuItemRect

[Now Supported on Windows NT]

The GetMenuItemRect function retrieves the bounding rectangle for the specified menu item.

BOOL WINAPI GetMenuItemRect(

HWND hWnd,
HMENU hMenu,
UINT uItem,
LPRECT lprcItem
);
Parameters

hWnd

Handle to the window containing the menu.

hMenu

Handle to a menu.

uItem

Zero-based position of the menu item.

lprcItem

Pointer to a RECT structure that receives the bounding rectangle of the specified menu item expressed in screen coordinates.

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, use the GetLastError function.

See Also

RECT


GetMenuState

The GetMenuState function retrieves the menu flags associated with the specified menu item. If the menu item opens a submenu, this function also returns the number of items in the submenu.

The GetMenuState function has been superseded by the GetMenuItemInfo function. You can still use GetMenuState, however, if you do not need any of the extended features of GetMenuItemInfo.

UINT GetMenuState(

HMENU hMenu,	// handle of menu
UINT uId,	// menu item to query
UINT uFlags	// menu flags
);
Parameters

hMenu

Identifies the menu that contains the menu item whose flags are to be retrieved.

uId

Specifies the menu item for which the menu flags are to be retrieved, as determined by the uFlags parameter.

uFlags

Specifies how the uId parameter is interpreted. This parameter can be one of the following values:

Value	Description
MF_BYCOMMAND	Indicates that the uId parameter gives the identifier of the menu item. The MF_BYCOMMAND flag is the default if neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified.
MF_BYPOSITION	Indicates that the uId parameter gives the zero-based relative position of the menu item.
Return Values

If the specified item does not exist, the return value is 0xFFFFFFFF.

If the menu item opens a submenu, the low-order byte of the return value contains the menu flags associated with the item, and the high-order byte contains the number of items in the submenu opened by the item.

Otherwise, the return value is a mask (Boolean OR) of the menu flags. Following are the menu flags associated with the menu item.

Value	Description
MF_CHECKED	Places a check mark next to the item (for drop-down menus, submenus, and shortcut menus only).
MF_DISABLED	Disables the item.
MF_GRAYED	Disables and grays the item.
MF_HILITE	Highlights the item.
MF_MENUBARBREAK	Functions the same as the MF_MENUBREAK flag, except for drop-down menus, submenus, and shortcut menus, where the new column is separated from the old column by a vertical line.
MF_MENUBREAK	Places the item on a new line (for menu bars) or in a new column (for drop-down menus, submenus, and shortcut menus) without separating columns.
MF_SEPARATOR	Creates a horizontal dividing line (for drop-down menus, submenus, and shortcut menus only).
See Also

GetMenu, GetMenuItemCount, GetMenuItemID, GetMenuItemInfo, GetMenuString


GetMenuString

The GetMenuString function copies the text string of the specified menu item into the specified buffer.

GetMenuString works, but is obsolete. Use GetMenuItemInfo instead.

int GetMenuString(

HMENU hMenu,	// handle to the menu
UINT uIDItem,	// menu item identifier
LPTSTR lpString,	// pointer to the buffer for the string
int nMaxCount,	// maximum length of the string
UINT uFlag	// menu flags
);
Parameters

hMenu

Identifies the menu.

uIDItem

Specifies the menu item to be changed, as determined by the uFlag parameter.

lpString

Points to the buffer that is to receive the null-terminated string.

If lpString is NULL, the function returns the length of the menu string.

nMaxCount

Specifies the maximum length, in characters, of the string to be copied. If the string is longer than the maximum specified in the nMaxCount parameter, the extra characters are truncated.

If nMaxCount is 0, the function returns the length of the menu string.

uFlag

Specifies how the uIDItem parameter is interpreted. This parameter must be one of the following values:

Value	Meaning
MF_BYCOMMAND	Indicates that uIDItem gives the identifier of the menu item. If neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified, the MF_BYCOMMAND flag is the default flag.
MF_BYPOSITION	Indicates that uIDItem gives the zero-based relative position of the menu item.
Return Values

If the function succeeds, the return value specifies the number of characters copied to the buffer, not including the terminating null character.

If the function fails, the return value is zero.

Remarks

The nMaxCount parameter must be one larger than the number of characters in the text string to accommodate the terminating null character.

If nMaxCount is 0, the function returns the length of the menu string.

See Also

GetMenuItemID


GetMessage

The GetMessage function retrieves a message from the calling thread’s message queue and places it in the specified structure. This function can retrieve both messages associated with a specified window and thread messages posted via the PostThreadMessage function. The function retrieves messages that lie within a specified range of message values. GetMessage does not retrieve messages for windows that belong to other threads or applications.

BOOL GetMessage(

LPMSG lpMsg,	// address of structure with message
HWND hWnd,	// handle of window
UINT wMsgFilterMin,	// first message
UINT wMsgFilterMax	// last message
);
Parameters

lpMsg

Points to an MSG structure that receives message information from the thread’s message queue.

hWnd

Identifies the window whose messages are to be retrieved. One value has a special meaning:

Value	Meaning
NULL	GetMessage retrieves messages for any window that belongs to the calling thread and thread messages posted to the calling thread via PostThreadMessage.
wMsgFilterMin

Specifies the integer value of the lowest message value to be retrieved.

wMsgFilterMax

Specifies the integer value of the highest message value to be retrieved.

Return Values

If the function retrieves a message other than WM_QUIT, the return value is nonzero.

If the function retrieves the WM_QUIT message, the return value is zero.

If there is an error, the return value is -1. For example, the function fails if hWnd is an invalid window handle.

Remarks

An application typically uses the return value to determine whether to end the main message loop and exit the program.

The GetMessage function only retrieves messages associated with the window identified by the hWnd parameter or any of its children as specified by the IsChild function, and within the range of message values given by the wMsgFilterMin and wMsgFilterMax parameters. If hWnd is NULL, GetMessage retrieves messages for any window that belongs to the calling thread and thread messages posted to the calling thread via PostThreadMessage. GetMessage does not retrieve messages for windows that belong to other threads nor for threads other than the calling thread. Thread messages, posted by the PostThreadmessage function, have a message hWnd value of NULL. If wMsgFilterMin and wMsgFilterMax are both zero, GetMessage returns all available messages (that is, no range filtering is performed).

The WM_KEYFIRST and WM_KEYLAST constants can be used as filter values to retrieve all messages related to keyboard input; the WM_MOUSEFIRST and WM_MOUSELAST constants can be used to retrieve all mouse messages. If the wMsgFilterMin and wMsgFilterMax parameters are both zero, the GetMessage function returns all available messages (that is, without performing any filtering).

GetMessage does not remove WM_PAINT messages from the queue. The messages remain in the queue until processed.

Note that the function return value can be TRUE, FALSE, or -1. Thus, you should avoid code like this:

while (GetMessage( lpMsg, hWnd, 0, 0)) ...

The possibility of a -1 return value means that such code can lead to fatal application errors.

See Also

IsChild, MSG, PeekMessage, PostMessage, PostThreadMessage, WaitMessage


GetMessageExtraInfo

The GetMessageExtraInfo function retrieves extra information associated with the last message retrieved by the GetMessage or PeekMessage function. This information may be added to a message by the driver for a pointing device or keyboard.

LONG GetMessageExtraInfo(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value specifies the extra information. The meaning of the extra information is device specific.

See Also

GetMessage, PeekMessage


GetMessagePos

The GetMessagePos function returns a long value that gives the cursor position in screen coordinates. This position is the point occupied by the cursor when the last message retrieved by the GetMessage function occurred.

DWORD GetMessagePos(VOID)

Parameters

This function has no parameters.

Return Values

The return value specifies the x- and y-coordinates of the cursor position. The x coordinate is in the LOWORD and the y coordinate is in the HIWORD.

Remarks

As noted above, the x-coordinate is in the low-order word of the return value; the y-coordinate is in the high-order word. If the return value is assigned to a variable, you can use the MAKEPOINTS macro to obtain a POINTS structure from the return value. You can also use the LOWORD or HIWORD macro to extract the x- or y-coordinate.

To determine the current position of the cursor instead of the position when the last message occurred, use the GetCursorPos function.

See Also

GetCursorPos, GetMessage, GetMessageTime, HIWORD, LOWORD, MAKEPOINTS, POINTS


GetMessageTime

The GetMessageTime function returns the message time for the last message retrieved by the GetMessage function from the current thread’s message queue. The time is a long integer that specifies the elapsed time, in milliseconds, from the time the system was started to the time the message was created (that is, placed in the thread’s message queue).

LONG GetMessageTime(VOID)

Parameters

This function has no parameters.

Return Values

The return value specifies the message time.

Remarks

The return value from the GetMessageTime function does not necessarily increase between subsequent messages, because the value wraps to zero if the timer count exceeds the maximum value for a long integer.

To calculate time delays between messages, verify that the time of the second message is greater than the time of the first message; then, subtract the time of the first message from the time of the second message.

See Also

GetMessage, GetMessagePos


GetMetaFile

The GetMetaFile function creates a handle that identifies the given Windows-format metafile.

The GetMetaFile function is not implemented in the Win32 API. This function is provided for compatibility with 16-bit versions of Microsoft Windows. Win32-based applications should use the GetEnhMetaFile function.


GetMetaFileBitsEx

The GetMetaFileBitsEx function retrieves the contents of a Windows-format metafile and copies them into the specified buffer.

This function is provided for compatibility with earlier versions of Microsoft Windows. Win32-based applications should use the GetEnhMetaFileBits function.

UINT GetMetaFileBitsEx(

HMETAFILE hmf,	// handle of metafile
UINT nSize,	// size of metafile, in bytes
LPVOID lpvData	// address of metafile data
);
Parameters

hmf

Identifies a Windows-format metafile.

nSize

Specifies the size, in bytes, of the buffer to receive the data.

lpvData

Points to the buffer to receive the metafile data. The buffer must be sufficiently large to contain the data. If lpvData is NULL, the function returns the number of bytes required to hold the data.

Return Values

If the function succeeds and the buffer pointer is NULL, the return value is the number of bytes required for the buffer; if the function succeeds and the buffer pointer is a valid pointer, the return value is the number of bytes copied.

If the function fails, the return value is zero.

Remarks

After the Windows-metafile bits are retrieved, they can be used to create a memory-based metafile by calling the SetMetaFileBitsEx function.

The GetMetaFileBitsEx function does not invalidate the metafile handle. An application must delete this handle by calling the DeleteMetaFile function.

A Windows-format metafile does not support the new curve, path, and transformation functions, such as PolyBezier, BeginPath, and SetWorldTransform. Applications that use these new functions and use metafiles to store pictures created by these functions should use the enhanced format metafile functions.

To convert a Windows-format metafile into an enhanced-format metafile, use the SetWinMetaFileBits function.

See Also

BeginPath, DeleteMetaFile, GetEnhMetaFileBits, PolyBezier, SetMetaFileBitsEx, SetWinMetaFileBits, SetWorldTransform


GetMetaRgn

The GetMetaRgn function retrieves the current metaregion for the specified device context.

int GetMetaRgn(

HDC hdc,	// handle of device context
HRGN hrgn	// handle of region
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies an existing region before the function is called. After the function returns, this parameter identifies a copy of the current metaregion.

Return Values

If the function succeeds, the return value is one.

If the function fails, the return value is zero.

Remarks

If the function succeeds, hrgn identifies a copy of the current metaregion. Subsequent changes to this copy will not affect the current metaregion.

The current clipping region of a device context is defined by the intersection of its clipping region and its metaregion.

See Also

SetMetaRgn


GetMiterLimit

The GetMiterLimit function returns the miter limit for the specified device context.

BOOL GetMiterLimit(

HDC hdc,	// handle of device context
PFLOAT peLimit	// address of variable receiving miter limit
);
Parameters

hdc

Identifies the device context.

peLimit

Points to a floating-point value where the current miter limit will be returned.

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.

Remarks

The miter limit is used when drawing geometric lines that have miter joins.

See Also

ExtCreatePen, SetMiterLimit


GetModuleFileName

The GetModuleFileName function retrieves the full path and filename for the executable file containing the specified module.

Windows 95: The GetModuleFilename function will return long filenames when an application’s version number is greater than or equal to 4.00 and the long filename is available. Otherwise, it returns only 8.3 format filenames.

DWORD GetModuleFileName(

HMODULE hModule,	// handle to module to find filename for
LPTSTR lpFilename,	// pointer to buffer for module path
DWORD nSize	// size of buffer, in characters
);
Parameters

hModule

Identifies the module whose executable filename is being requested. If this parameter is NULL, GetModuleFileName returns the path for the file used to create the calling process.

lpFilename

Points to a buffer that is filled in with the path and filename of the given module.

nSize

Specifies the length, in characters, of the lpFilename buffer. If the length of the path and filename exceeds this limit, the string is truncated.

Return Values

If the function succeeds, the return value is the length, in characters, of the string copied to the buffer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If a module is loaded in two processes, its module filename in one process may differ in case from its module filename in the other process.

See Also

GetModuleHandle, LoadLibrary


GetModuleHandle

The GetModuleHandle function returns a module handle for the specified module if the file has been mapped into the address space of the calling process.

HMODULE GetModuleHandle(

LPCTSTR lpModuleName	// address of module name to return handle for
);
Parameters

lpModuleName

Points to a null-terminated string that names a Win32 module (either a .DLL or .EXE file). If the filename extension is omitted, the default library extension .DLL is appended. The filename string can include a trailing point character (.) to indicate that the module name has no extension. The string does not have to specify a path. The name is compared (case independently) to the names of modules currently mapped into the address space of the calling process.

If this parameter is NULL, GetModuleHandle returns a handle of the file used to create the calling process.

Return Values

If the function succeeds, the return value is a handle to the specified module.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The returned handle is not global, inheritable, or duplicative, and it cannot be used by another process.

The handles returned by GetModuleHandle and LoadLibrary can be used in the same functions — for example, GetProcAddress, FreeLibrary, or LoadResource. The difference between the two functions involves the reference count. LoadLibrary maps the module into the address space of the calling process, if necessary, and increments the module’s reference count, if it is already mapped. GetModuleHandle, however, returns the handle of a mapped module without incrementing its reference count.

Note that the reference count is used in FreeLibrary to determine whether to unmap the function from the address space of the process. For this reason, use care when using a handle returned by GetModuleHandle in a call to FreeLibrary because doing so can cause a dynamic-link library (DLL) module to be unmapped prematurely.

This function must also be used carefully in a multithreaded application. There is no guarantee that the module handle remains valid between the time this function returns the handle and the time it is used by another function. For example, a thread might retrieve a module handle by calling GetModuleHandle. Before the thread uses the handle in another function, a second thread could free the module and the system could load another module, giving it the same handle as the module that was recently freed. The first thread would then be left with a module handle that refers to a module different than the one intended.

See Also

FreeLibrary, GetModuleFileName, GetProcAddress, LoadLibrary, LoadResource


GetMsgProc

The GetMsgProc hook procedure is an application-defined or library-defined callback function that the system calls whenever the GetMessage function has retrieved a message from an application message queue. Before passing the retrieved message to the destination window procedure, the system passes the message to the hook procedure.

LRESULT CALLBACK GetMsgProc(

int code,	// hook code
WPARAM wParam,	// removal flag
LPARAM lParam	// address of structure with message
);
Parameters

code

Specifies whether the hook procedure must process the message. If code is HC_ACTION, the hook procedure must process the message. If code is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies whether the message has been removed from the queue. This parameter can be one of the following values:

Value	Meaning
PM_NOREMOVE	Specifies that the message has not been removed from the queue. (An application called the PeekMessage function, specifying the PM_NOREMOVE flag.)
PM_REMOVE	Specifies that the message has been removed from the queue. (An application called GetMessage, or it called the PeekMessage function, specifying the PM_REMOVE flag.)
lParam

Points to an MSG structure that contains details about the message.

Return Values

The return value should be zero.

Remarks

The GetMsgProc hook procedure can examine or modify the message. After the hook procedure returns control to the system, the GetMessage function returns the message, along with any modifications, to the application that originally called it.

An application installs this hook procedure by specifying the WH_GETMESSAGE hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

GetMsgProc is a placeholder for the application-defined or library-defined function name.

See Also

CallNextHookEx, GetMessage, MSG, PeekMessage, SetWindowsHookEx


GetMultipleTrustee [New - Windows NT]
GetMultipleTrustee

[New - Windows NT]

The GetMultipleTrustee function is provided for future use. Do not call it on Windows NT version 4.0.


GetMultipleTrusteeOperation [New - Windows NT]
GetMultipleTrusteeOperation

[New - Windows NT]

The GetMultipleTrusteeOperation function is provided for future use. Do not call it on Windows NT version 4.0.


GetNamedPipeHandleState

The GetNamedPipeHandleState function retrieves information about a specified named pipe. The information returned can vary during the lifetime of an instance of the named pipe.

BOOL GetNamedPipeHandleState(

HANDLE hNamedPipe,	// handle of named pipe
LPDWORD lpState,	// address of flags indicating pipe state
LPDWORD lpCurInstances,	// address of number of current pipe instances
LPDWORD lpMaxCollectionCount,	// address of max. bytes before remote transmission
LPDWORD lpCollectDataTimeout,	// address of max. time before remote transmission
LPTSTR lpUserName,	// address of user name of client process
DWORD nMaxUserNameSize	// size, in characters, of user name buffer
);
Parameters

hNamedPipe

Identifies the named pipe for which information is wanted. The handle must have GENERIC_READ access to the named pipe.

lpState

Points to a 32-bit variable that indicates the current state of the handle. This parameter can be NULL if this information is not needed. Either or both of the following values can be specified:

Value	Meaning
PIPE_NOWAIT	The pipe handle is in nonblocking mode. If this flag is not specified, the pipe handle is in blocking mode.
PIPE_READMODE_MESSAGE	The pipe handle is in message-read mode. If this flag is not specified, the pipe handle is in byte-read mode.
lpCurInstances

Points to a 32-bit variable that receives the number of current pipe instances. This parameter can be NULL if this information is not required.

lpMaxCollectionCount

Points to a 32-bit variable that receives the maximum number of bytes to be collected on the client’s computer before transmission to the server. This parameter must be NULL if the specified pipe handle is to the server end of a named pipe or if client and server processes are on the same computer. This parameter can be NULL if this information is not required.

lpCollectDataTimeout

Points to a 32-bit variable that receives the maximum time, in milliseconds, that can pass before a remote named pipe transfers information over the network. This parameter must be NULL if the specified pipe handle is to the server end of a named pipe or if client and server processes are on the same computer. This parameter can be NULL if this information is not required.

lpUserName

Points to a buffer that receives the null-terminated string containing the user name string of the client application. This parameter must be NULL if the specified pipe handle is to the client end of a named pipe. This parameter can be NULL if this information is not required.

nMaxUserNameSize

Specifies the size, in characters, of the buffer specified by the lpUserName parameter. This parameter is ignored if lpUserName is NULL.

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.

Remarks

The GetNamedPipeHandleState function returns successfully even if all of the pointers passed to it are NULL.

To set the pipe handle state, use the SetNamedPipeHandleState function.

See Also

SetNamedPipeHandleState


GetNamedPipeInfo

The GetNamedPipeInfo function retrieves information about the specified named pipe.

BOOL GetNamedPipeInfo(

HANDLE hNamedPipe,	// handle of named pipe
LPDWORD lpFlags,	// address of flags indicating type of pipe
LPDWORD lpOutBufferSize,	// address of size, in bytes, of pipe’s output buffer
LPDWORD lpInBufferSize,	// address of size, in bytes, of pipe’s input buffer
LPDWORD lpMaxInstances	// address of max. number of pipe instances
);
Parameters

hNamedPipe

Identifies the named pipe instance. The handle must have GENERIC_READ access to the named pipe.

lpFlags

Points to a 32-bit variable that indicates the type of the named pipe. This parameter can be NULL if this information is not required. Otherwise, use the following values:

Value	Meaning
PIPE_CLIENT_END	The handle refers to the client end of a named pipe instance. This is the default.
PIPE_SERVER_END	The handle refers to the server end of a named pipe instance. If this value is not specified, the handle refers to the client end of a named pipe instance.
PIPE_TYPE_BYTE	The named pipe is a byte pipe. This is the default.
PIPE_TYPE_MESSAGE	The named pipe is a message pipe. If this value is not specified, the pipe is a byte pipe.
lpOutBufferSize

Points to a 32-bit variable that receives the size, in bytes, of the buffer for outgoing data. If the buffer size is zero, the buffer is allocated as needed. This parameter can be NULL if this information is not required.

lpInBufferSize

Points to a 32-bit variable that receives the size, in bytes, of the buffer for incoming data. If the buffer size is zero, the buffer is allocated as needed. This parameter can be NULL if this information is not required.

lpMaxInstances

Points to a 32-bit variable that receives the maximum number of pipe instances that can be created. If the variable is set to PIPE_UNLIMITED_INSTANCES, the number of pipe instances that can be created is limited only by the availability of system resources. This parameter can be NULL if this information is not required.

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.

See Also

CreateNamedPipe, GetNamedPipeHandleState


GetNamedSecurityInfo [New - Windows NT]
GetNamedSecurityInfo

[New - Windows NT]

The GetNamedSecurityInfo function retrieves a copy of the security descriptor for an object specified by name.

DWORD GetNamedSecurityInfo(

LPTSTR pObjectName,	// name of the object
SE_OBJECT_TYPE ObjectType,	// type of object
SECURITY_INFORMATION SecurityInfo,	// type of security information to retrieve
PSID *ppsidOwner,	// receives a pointer to the owner SID
PSID *ppsidGroup,	// receives a pointer to the primary group SID
PACL *ppDacl,	// receives a pointer to the DACL
PACL *ppSacl,	// receives a pointer to the SACL
PSECURITY_DESCRIPTOR *ppSecurityDescriptor	// receives a pointer to the security descriptor
);
Parameters

pObjectName

Pointer to a null-terminated string that specifies the name of the object from which to retrieve security information. For descriptions of the string formats for the different object types, see SE_OBJECT_TYPE.

ObjectType

Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName parameter.

SecurityInfo

A set of SECURITY_INFORMATION bit flags that indicate the type of security information to retrieve. This parameter can be a combination of the following values.

Value	Meaning
OWNER_SECURITY_INFORMATION	If this flag is set, the ppsidOwner parameter receives the security identifier (SID) of the object’s owner.
GROUP_SECURITY_INFORMATION	If this flag is set, the ppsidGroup parameter receives the SID of the object’s primary group.
DACL_SECURITY_INFORMATION	If this flag is set, the ppDacl parameter receives the object’s discretionary access-control list (DACL).
SACL_SECURITY_INFORMATION	If this flag is set, the ppSacl parameter receives the object’s system access-control list (SACL)..
ppsidOwner

Pointer to a variable that receives a pointer to the owner SID in the security descriptor returned in ppSecurityDescriptor. The returned pointer is valid only if you set the OWNER_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the owner SID.

ppsidGroup

Pointer to a variable that receives a pointer to the primary group SID in the returned security descriptor. The returned pointer is valid only if you set the GROUP_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the group SID.

ppDacl

Pointer to a variable that receives a pointer to the DACL in the returned security descriptor. The returned pointer is valid only if you set the DACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the DACL.

ppSacl

Pointer to a variable that receives a pointer to the SACL in the returned security descriptor. The returned pointer is valid only if you set the SACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the SACL.

ppSecurityDescriptor

Pointer to a variable that receives a pointer to the security descriptor of the object. You must call the LocalFree function to free the returned buffer.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

If the ppsidOwner, ppsidGroup, ppDacl, ppSacl parameters are non-NULL, and the SecurityInfo parameter specifies that they be retrieved from the object, those parameters will point to the corresponding parameters in the security descriptor returned in ppSecurityDescriptor.

To read the object’s owner, group and DACL the caller must have READ_CONTROL access or be the owner of the object. The caller must have the SE_SECURITY_NAME privilege enabled to read the SACL.

See Also

ACL, GetSecurityInfo, LocalFree, SE_OBJECT_TYPE, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetNamedSecurityInfo, SetSecurityInfo, SID


GetNearestColor

The GetNearestColor function returns a color value identifying a color from the system palette that will be displayed when the specified color value is used.

COLORREF GetNearestColor(

HDC hdc,	// handle of device context
COLORREF crColor	// color to be matched
);
Parameters

hdc

Identifies the device context.

crColor

Specifies a color value that identifies a requested color.

Return Values

If the function succeeds, the return value identifies a color from the system palette that corresponds to the given color value.

If the function fails, the return value is CLR_INVALID. To get extended error information, call GetLastError.

See Also

GetDeviceCaps, GetNearestPaletteIndex, COLORREF


GetNearestPaletteIndex

The GetNearestPaletteIndex function retrieves the index for the entry in the specified logical palette most closely matching a specified color value.

UINT GetNearestPaletteIndex(

HPALETTE hpal,	// handle of logical color palette
COLORREF crColor	// color to be matched
);
Parameters

hpal

Identifies a logical color palette.

crColor

Specifies a color to be matched.

Return Values

If the function succeeds, the return value is the index of an entry in a logical palette.

If the function fails, the return value is CLR_INVALID. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

If the given logical palette contains entries with the PC_EXPLICIT flag set, the return value is undefined.

See Also

GetDeviceCaps, GetNearestColor, GetPaletteEntries, GetSystemPaletteEntries, COLORREF


GetNextDlgGroupItem

The GetNextDlgGroupItem function retrieves the handle of the first control in a group of controls that precedes (or follows) the specified control in a dialog box.

HWND GetNextDlgGroupItem(

HWND hDlg,	// handle of dialog box
HWND hCtl,	// handle of control
BOOL bPrevious	// direction flag
);
Parameters

hDlg

Identifies the dialog box being searched.

hCtl

Identifies the control to be used as the starting point for the search. If this parameter is NULL, the function uses the last (or first) control in the dialog box as the starting point for the search.

bPrevious

Specifies how the function is to search the group of controls in the dialog box. If this parameter is TRUE, the function searches for the previous control in the group. If it is FALSE, the function searches for the next control in the group.

Return Values

If GetNextDlgGroupItem succeeds, the return value is the handle of the previous (or next) control in the group of controls.

Remarks

The GetNextDlgGroupItem function searches controls in the order (or reverse order) they were created in the dialog box template. The first control in the group must have the WS_GROUP style; all other controls in the group must have been consecutively created and must not have the WS_GROUP style.

When searching for the previous control, the function returns the first control it locates that is visible and not disabled. If the control given by hCtl has the WS_GROUP style, the function temporarily reverses the search to locate the first control having the WS_GROUP style, then resumes the search in the original direction, returning the first control it locates that is visible and not disabled, or returning hwndCtrl if no such control is found.

When searching for the next control, the function returns the first control it locates that is visible, not disabled, and does not have the WS_GROUP style. If it encounters a control having the WS_GROUP style, the function reverses the search, locates the first control having the WS_GROUP style, and returns this control if it is visible and not disabled. Otherwise, the function resumes the search in the original direction and returns the first control it locates that is visible and not disabled, or returns hCtl if no such control is found.

See Also

GetNextDlgTabItem


GetNextDlgTabItem

The GetNextDlgTabItem function retrieves the handle of the first control that has the WS_TABSTOP style that precedes (or follows) the specified control.

HWND GetNextDlgTabItem(

HWND hDlg,	// handle of dialog box
HWND hCtl,	// handle of known control
BOOL bPrevious	// direction flag
);
Parameters

hDlg

Identifies the dialog box to be searched.

hCtl

Identifies the control to be used as the starting point for the search. If this parameter is NULL, the function uses the last (or first) control in the dialog box as the starting point for the search.

bPrevious

Specifies how the function is to search the dialog box. If this parameter is TRUE, the function searches for the previous control in the dialog box. If this parameter is FALSE, the function searches for the next control in the dialog box.

Return Values

If the function succeeds, the return value is the window handle of the previous (or next) control that has the WS_TABSTOP style set.

Remarks

The GetNextDlgTabItem function searches controls in the order (or reverse order) they were created in the dialog box template. The function returns the first control it locates that is visible, not disabled, and has the WS_TABSTOP style. If no such control exists, the function returns hCtl.

See Also

GetDlgItem, GetNextDlgGroupItem


GetNextWindow

The GetNextWindow function retrieves the handle of the next or previous window in the Z order. The next window is below the specified window; the previous window is above. If the specified window is a topmost window, the function retrieves the handle of the next (or previous) topmost window. If the specified window is a top-level window, the function retrieves the handle of the next (or previous) top-level window. If the specified window is a a child window, the function searches for a handle of the next (or previous) child window.

HWND GetNextWindow(

HWND hWnd,	// handle of current window
UINT wCmd	// direction flag
);
Parameters

hWnd

Identifies a window. The window handle retrieved is relative to this window, based on the value of the wCmd parameter.

wCmd

Specifies whether the function returns the handle of the next window or of the previous window. This parameter can be either of the following values:

Value	Meaning
GW_HWNDNEXT	Returns the handle of the window below the given window.
GW_HWNDPREV	Returns the handle of the window above the given window.
Return Values

If the function succeeds, the return value is the handle of the next (or previous) window. If there is no next (or previous) window, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Using this function is the same as calling the GetWindow function with the GW_HWNDNEXT or GW_HWNDPREV flag set.

See Also

GetTopWindow


GetNumberFormat

The GetNumberFormat function formats a number string as a number string customized for a specified locale.

int GetNumberFormat(

LCID Locale,	// locale for which number string is to be formatted
DWORD dwFlags,	// bit flag that controls the function’s operation
LPCTSTR lpValue,	// pointer to input number string
CONST NUMBERFMT *lpFormat,	// pointer to a formatting information structure
LPTSTR lpNumberStr,	// pointer to output buffer
int cchNumber	// size of output buffer
);
Parameters

Locale

Specifies the locale for which the number string is to be formatted. If lpFormat is NULL, the function formats the string according to the number format for this locale. If lpFormat is not NULL, the function uses the locale only for formatting information not specified in the NUMBERFMT structure (for example, the locale’s string value for the negative sign).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
dwFlags

Contains a bit flag that controls the operation of the function. If lpFormat is non-NULL, this parameter must be zero.

If lpFormat is NULL, you can specify the LOCALE_NOUSEROVERRIDE flag to format the string using the system default number format for the specified locale; or you can specify zero to format the string using any user overrides to the locale’s default number format

lpValue

Points to a null-terminated string containing the number string to format.

This string can only contain the following characters:

•	Characters ‘0’ through ‘9’

•	One decimal point (dot) if the number is a floating-point value

•	A minus sign in the first character position if the number is a negative value

All other characters are invalid. The function returns an error if the string pointed to by lpValue deviates from these rules.

lpFormat

Pointer to a NUMBERFMT structure that contains number formatting information. All members in the structure pointed to by lpFormat must contain appropriate values.

If lpFormat is NULL, the function uses the number format of the specified locale.

lpNumberStr

Points to a buffer to receive the formatted number string.

cchNumber

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the lpNumberStr buffer. If cchNumber is zero, the function returns the number of bytes or characters required to hold the formatted number string, and the buffer pointed to by lpNumberStr is not used.

Return Values

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) written to the buffer pointed to by lpNumberStr, or if the cchNumber parameter is zero, the number of bytes or characters required to hold the formatted number string.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID FLAGS
ERROR_INVALID_PARAMETER

See Also

GetCurrencyFormat, NUMBERFMT


GetNumberOfConsoleInputEvents

The GetNumberOfConsoleInputEvents function retrieves the number of unread input records in the console’s input buffer.

BOOL GetNumberOfConsoleInputEvents(

HANDLE hConsoleInput,	// handle of console input buffer
LPDWORD lpcNumberOfEvents	// address for number of events
);
Parameters

hConsoleInput

Identifies the console input buffer. The handle must have GENERIC_READ access.

lpcNumberOfEvents

Points to a 32-bit variable that receives the number of unread input records in the console’s input buffer.

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.

Remarks

The GetNumberOfConsoleInputEvents function reports the total number of unread input records in the input buffer, including keyboard, mouse, and window-resizing input records. Processes using the ReadFile or ReadConsole function can only read keyboard input. Processes using the ReadConsoleInput function can read all types of input records.

A process can specify a console input buffer handle in one of the wait functions to determine when there is unread console input. When the input buffer is not empty, the state of a console input buffer handle is signaled.

To read input records from a console input buffer without affecting the number of unread records, use the PeekConsoleInput function. To discard all unread records in a console’s input buffer, use the FlushConsoleInputBuffer function.

See Also

FlushConsoleInputBuffer, PeekConsoleInput, ReadConsole, ReadConsoleInput, ReadFile


GetNumberOfConsoleMouseButtons

The GetNumberOfConsoleMouseButtons function retrieves the number of buttons on the mouse used by the current console.

BOOL GetNumberOfConsoleMouseButtons(

LPDWORD lpNumberOfMouseButtons	// address of number of buttons
);
Parameters

lpNumberOfMouseButtons

Points to a 32-bit variable that receives the number of mouse buttons.

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.

Remarks

When a console receives mouse input, an INPUT_RECORD structure containing a MOUSE_EVENT_RECORD structure is placed in the console’s input buffer. The dwButtonState member of MOUSE_EVENT_RECORD has a bit indicating the state of each mouse button. The bit is 1 if the button is down and 0 if the button is up. To determine the number of bits that are significant, use GetNumberOfConsoleMouseButtons.

See Also

ReadConsoleInput, INPUT_RECORD, MOUSE_EVENT_RECORD


GetNumberOfEventLogRecords

The GetNumberOfEventLogRecords function retrieves the number of records in the specified event log.

BOOL GetNumberOfEventLogRecords(

HANDLE hEventLog,	// handle to event log
PDWORD NumberOfRecords	// buffer for number of records
);
Parameters

hEventLog

Identifies the open event log. This handle is returned by the OpenEventLog or OpenBackupEventLog function.

NumberOfRecords

Points to a variable that receives the number of records in the given event log.

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.

See Also

GetOldestEventLogRecord, OpenBackupEventLog, OpenEventLog


GetObject

The GetObject function obtains information about a specified graphics object. Depending on the graphics object, the function places a filled-in BITMAP, DIBSECTION, EXTLOGPEN, LOGBRUSH, LOGFONT, or LOGPEN structure, or a count of table entries (for a logical palette), into a specified buffer.

int GetObject(

HGDIOBJ hgdiobj,	// handle to graphics object of interest
int cbBuffer,	// size of buffer for object information
LPVOID lpvObject	// pointer to buffer for object information
);
Parameters

hgdiobj

A handle to the graphics object of interest. This can be a handle to one of the following: a logical bitmap, a brush, a font, a palette, a pen, or a device independent bitmap created by calling the CreateDIBSection function.

cbBuffer

Specifies the number of bytes of information to be written to the buffer.

lpvObject

Points to a buffer that is to receive the information about the specified graphics object.

The following table shows the type of information the buffer receives for each type of graphics object you can specify with hgdiobj:

hgdiobj Type	Data Written to *lpvObject
HBITMAP	BITMAP
HBITMAP returned from a call to CreateDIBSection	DIBSECTION, if cbBuffer is set to sizeof(DIBSECTION), or BITMAP, if cbBuffer is set to sizeof(BITMAP)
HPALETTE	a WORD count of the number of entries in the logical palette
HPEN returned from a call to ExtCreatePen	EXTLOGPEN
HPEN	LOGPEN
HBRUSH	LOGBRUSH
HFONT	LOGFONT
If the lpvObject parameter is NULL, the function return value is the number of bytes required to store the information it writes to the buffer for the specified graphics object.

Return Values

If the function succeeds, and lpvObject is a valid pointer, the return value is the number of bytes stored into the buffer.

If the function succeeds, and lpvObject is NULL, the return value is the number of bytes required to hold the information the function would store into the buffer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The buffer pointed to by the lpvObject parameter must be sufficiently large to receive the information about the graphics object.

If hgdiobj identifies a bitmap created by calling CreateDIBSection, and the specified buffer is large enough, the GetObject function returns a DIBSECTION structure. In addition, the bmBits member of the BITMAP structure contained within the DIBSECTION will contain a pointer to the bitmap’s bit values.

If hgdiobj identifies a bitmap created by any other means, GetObject returns only the width, height, and color format information of the bitmap. You can obtain the bitmap’s bit values by calling the GetDIBits or GetBitmapBits function.

If hgdiobj identifies a logical palette, GetObject retrieves a two-byte integer that specifies the number of entries in the palette. The function does not retrieve the LOGPALETTE structure defining the palette. To retrieve information about palette entries, an application can call the GetPaletteEntries function.

See Also

CreateDIBSection, GetBitmapBits, GetDIBits, GetPaletteEntries, GetRegionData, BITMAP, DIBSECTION, EXTLOGPEN, LOGBRUSH, LOGFONT, LOGPALETTE, LOGPEN


GetObjectType

The GetObjectType identifies the type of the specified object.

DWORD GetObjectType(

HGDIOBJ h	// handle of graphic object
);
Parameters

h

Identifies the object.

Return Values

If the function succeeds, the return value identifies the object. This value can be one of the following:

Value	Meaning
OBJ_BITMAP	Bitmap
OBJ_BRUSH	Brush
OBJ_FONT	Font
OBJ_PAL	Palette
OBJ_PEN	Pen
OBJ_EXTPEN	Extended pen
OBJ_REGION	Region
OBJ_DC	Device context
OBJ_MEMDC	Memory device context
OBJ_METAFILE	Metafile
OBJ_METADC	Metafile device context
OBJ_ENHMETAFILE	Enhanced metafile
OBJ_ENHMETADC	Enhanced metafile device context
If the function fails, the return value is zero.

See Also

GetObject, SelectObject


GetOEMCP

The GetOEMCP function retrieves the current OEM code-page identifier for the system. (OEM stands for original equipment manufacturer.)

UINT GetOEMCP(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the current OEM code-page identifier for the system or a default identifier if no code page is current.

Remarks

Following are the OEM code-page identifiers:

Identifier	Meaning
437	MS-DOS United States
708	Arabic (ASMO 708)
709	Arabic (ASMO 449+, BCON V4)
710	Arabic (Transparent Arabic)
720	Arabic (Transparent ASMO)
737	Greek (formerly 437G)
775	Baltic
850	MS-DOS Multilingual (Latin I)
852	MS-DOS Slavic (Latin II)
855	IBM Cyrillic (primarily Russian)
857	IBM Turkish
860	MS-DOS Portuguese
861	MS-DOS Icelandic
862	Hebrew
863	MS-DOS Canadian-French
864	Arabic
865	MS-DOS Nordic
866	MS-DOS Russian (former USSR)
869	IBM Modern Greek
874	Thai
932	Japan
936	Chinese (PRC, Singapore)
949	Korean
950	Chinese (Taiwan, Hong Kong)
1361	Korean (Johab)
See Also

GetACP


GetOldestEventLogRecord

The GetOldestEventLogRecord function retrieves the absolute record number of the oldest record in the specified event log.

BOOL GetOldestEventLogRecord(

HANDLE hEventLog,	// handle to event log
PDWORD OldestRecord	// buffer for number of oldest record
);
Parameters

hEventLog

Identifies the open event log. This handle is returned by the OpenEventLog or OpenBackupEventLog function.

OldestRecord

Points to the variable that receives the absolute record number of the oldest record in the given event log.

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.

See Also

GetNumberOfEventLogRecords, OpenBackupEventLog, OpenEventLog


GetOpenClipboardWindow

The GetOpenClipboardWindow function retrieves the handle of the window that currently has the clipboard open.

HWND GetOpenClipboardWindow(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the handle of the window that has the clipboard open. If no window has the clipboard open, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If an application or dynamic-link library (DLL) specifies a NULL window handle when calling the OpenClipboard function, the clipboard is opened but is not associated with a window. In such a case, GetOpenClipboardWindow returns NULL.

See Also

GetClipboardOwner, GetClipboardViewer, GetOpenClipboardWindow, OpenClipboard


GetOpenFileName

The GetOpenFileName function creates an Open common dialog box that lets the user specify the drive, directory, and the name of a file or set of files to open.

BOOL GetOpenFileName(

LPOPENFILENAME lpofn	// address of structure with initialization data
);
Parameters

lpofn

Pointer to an OPENFILENAME structure that contains information used to initialize the dialog box. When GetOpenFileName returns, this structure contains information about the user’s file selection.

Return Values

If the user specifies a filename and clicks the OK button, the return value is nonzero. The buffer pointed to by the lpstrFile member of the OPENFILENAME structure contains the full path and filename specified by the user.

If the user cancels or closes the Open dialog box or an error occurs, the return value is zero. To get extended error information, call the CommDlgExtendedError function, which can return one of the following values:

CDERR_FINDRESFAILURE	CDERR_NOHINSTANCE
CDERR_INITIALIZATION	CDERR_NOHOOK
CDERR_LOCKRESFAILURE	CDERR_NOTEMPLATE
CDERR_LOADRESFAILURE	CDERR_STRUCTSIZE
CDERR_LOADSTRFAILURE	FNERR_BUFFERTOOSMALL
CDERR_MEMALLOCFAILURE	FNERR_INVALIDFILENAME
CDERR_MEMLOCKFAILURE	FNERR_SUBCLASSFAILURE
Remarks

By default, Windows 95 and Windows NT version 4.0 display a new version of the Open dialog box that provides user-interface features that are similar to the Windows Explorer. You can provide an OFNHookProc hook procedure for an Explorer-style Open dialog box. To enable the hook procedure, set the OFN_EXPLORER and OFN_ENABLEHOOK flags in the Flags member of the OPENFILENAME structure and specify the address of the hook procedure in the lpfnHook member.

Windows 95 and Windows NT 4.0 continue to support the old-style Open dialog box for applications that want to maintain a user-interface consistent with the Windows 3.1 or Windows NT 3.51 user-interface. To display the old-style Open dialog box, enable an OFNHookProcOldStyle hook procedure and ensure that the OFN_EXPLORER flag is not set.

See Also

CommDlgExtendedError, GetSaveFileName, OFNHookProc , OFNHookProcOldStyle, OPENFILENAME


GetOutlineTextMetrics

The GetOutlineTextMetrics function retrieves text metrics for TrueType fonts.

UINT GetOutlineTextMetrics(

HDC hdc,	// handle of device context
UINT cbData,	// size of metric data array
LPOUTLINETEXTMETRIC lpOTM	// address of metric data array
);
Parameters

hdc

Identifies the device context.

cbData

Specifies the size, in bytes, of the array in which the text metrics are to be returned.

lpOTM

Points to an array of OUTLINETEXTMETRIC structures. If this parameter is NULL, the function returns the size of the buffer required for the retrieved metric data.

Return Values

If the function succeeds, the return value is TRUE or the size of the required buffer.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The OUTLINETEXTMETRIC structure contains most of the text metric information provided for TrueType fonts (including a TEXTMETRIC structure). The sizes returned in the OUTLINETEXTMETRIC structures are in logical units; they depend on the current mapping mode.

See Also

GetTextMetrics, OUTLINETEXTMETRIC, TEXTMETRIC


GetOverlappedResult

The GetOverlappedResult function returns the results of an overlapped operation on the specified file, named pipe, or communications device.

Windows 95: This function works only on serial devices or on files opened by using the DeviceIoControl function.

BOOL GetOverlappedResult(

HANDLE hFile,	// handle of file, pipe, or communications device
LPOVERLAPPED lpOverlapped,	// address of overlapped structure
LPDWORD lpNumberOfBytesTransferred,	// address of actual bytes count
BOOL bWait	// wait flag
);
Parameters

hFile

Identifies the file, named pipe, or communications device. This is the same handle that was specified when the overlapped operation was started by a call to the ReadFile, WriteFile, ConnectNamedPipe, TransactNamedPipe, DeviceIoControl, or WaitCommEvent function.

lpOverlapped

Points to an OVERLAPPED structure that was specified when the overlapped operation was started.

lpNumberOfBytesTransferred

Points to a 32-bit variable that receives the number of bytes that were actually transferred by a read or write operation. For a TransactNamedPipe operation, this is the number of bytes that were read from the pipe. For a DeviceIoControl operation, this is the number of bytes of output data returned by the device driver. For a ConnectNamedPipe or WaitCommEvent operation, this value is undefined.

bWait

Specifies whether the function should wait for the pending overlapped operation to be completed. If TRUE, the function does not return until the operation has been completed. If FALSE and the operation is still pending, the function returns FALSE and the GetLastError function returns ERROR_IO_INCOMPLETE.

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.

Remarks

The results reported by the GetOverlappedResult function are those of the specified handle’s last overlapped operation to which the specified OVERLAPPED structure was provided, and for which the operation’s results were pending. A pending operation is indicated when the function that started the operation returns FALSE, and the GetLastError function returns ERROR_IO_PENDING. When an I/O operation is pending, the function that started the operation resets the hEvent member of the OVERLAPPED structure to the nonsignaled state. Then when the pending operation has been completed, the system sets the event object to the signaled state.

If the bWait parameter is TRUE, GetOverlappedResult determines whether the pending operation has been completed by waiting for the event object to be in the signaled state.

If the hEvent member of the OVERLAPPED structure is NULL, the system uses the state of the hFile handle to signal when the operation has been completed. Use of file, named pipe, or communications-device handles for this purpose is discouraged. It is safer to use an event object because of the confusion that can occur when multiple simultaneous overlapped operations are performed on the same file, named pipe, or communications device. In this situation, there is no way to know which operation caused the object’s state to be signaled.

Specify a manual-reset event object in the OVERLAPPED structure. If an auto-reset event object is used, the event handle must not be specified in any other wait operation in the interval between starting the overlapped operation and the call to GetOverlappedResult. For example, the event object is sometimes specified in one of the wait functions to wait for the operation’s completion. When the wait function returns, the system sets an auto-reset event’s state to nonsignaled, and a subsequent call to GetOverlappedResult with the bWait parameter set to TRUE causes the function to be blocked indefinitely.

See Also

CancelIo, ConnectNamedPipe, CreateEvent, DeviceIoControl, GetLastError, OVERLAPPED, ReadFile, TransactNamedPipe, WaitCommEvent, WriteFile


GetPaletteEntries

The GetPaletteEntries function retrieves a specified range of palette entries from the given logical palette.

UINT GetPaletteEntries(

HPALETTE hpal,	// handle of logical color palette
UINT iStartIndex,	// first entry to retrieve
UINT nEntries,	// number of entries to retrieve
LPPALETTEENTRY lppe	// address of array receiving entries
);
Parameters

hpal

Identifies the logical color palette.

iStartIndex

Specifies the first entry in the logical palette to be retrieved.

nEntries

Specifies the number of entries in the logical palette to be retrieved.

lppe

Points to an array of PALETTEENTRY structures to receive the palette entries. The array must contain at least as many structures as specified by the nEntries parameter.

Return Values

If the function succeeds and the handle of the logical color palette is a valid pointer (not NULL), the return value is the number of entries retrieved from the logical palette. If the function succeeds and handle of the logical color palette is NULL, the return value is the number of entries in the given palette.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

If the nEntries parameter specifies more entries than exist in the palette, the remaining members of the PALETTEENTRY structure are not altered.

See Also

GetDeviceCaps, GetSystemPaletteEntries, SetPaletteEntries, PALETTEENTRY


GetParent

The GetParent function retrieves the handle of the specified child window’s parent window.

HWND GetParent(

HWND hWnd	// handle of child window
);
Parameters

hWnd

Identifies the window whose parent window handle is to be retrieved.

Return Values

If the function succeeds, the return value is the handle of the parent window. If the window has no parent window, the return value is NULL. To get extended error information, call GetLastError.

See Also

SetParent


GetPath

The GetPath function retrieves the coordinates defining the endpoints of lines and the control points of curves found in the path that is selected into the specified device context.

int GetPath(

HDC hdc,	// handle of device context
LPPOINT lpPoints,	// address of array receiving path vertices
LPBYTE lpTypes,	// address of array of path vertex types
int nSize	// count of points defining path
);
Parameters

hdc

Identifies a device context that contains a closed path.

lpPoints

Points to an array of POINT structures that contains the line endpoints and curve control points.

lpTypes

Points to an array of bytes where the vertex types are placed. Values are one of the following:

Type	Description
PT_MOVETO	Specifies that the corresponding point in the lpPoints parameter starts a disjoint figure.
PT_LINETO	Specifies that the previous point and the corresponding point in lpPoints are the endpoints of a line.
PT_BEZIERTO	Specifies that the corresponding point in lpPoints is a control point or ending point for a Bézier curve.
	PT_BEZIERTO values always occur in sets of three. The point in the path immediately preceding them defines the starting point for the Bézier curve. The first two PT_BEZIERTO points are the control points, and the third PT_BEZIERTO point is the ending (if hard-coded) point.
A PT_LINETO or PT_BEZIERTO value may be combined with the following value (by using the bitwise operator OR) to indicate that the corresponding point is the last point in a figure and the figure should be closed:

Flag	Description
PT_CLOSEFIGURE	Specifies that the figure is automatically closed after the corresponding line or curve is drawn. The figure is closed by drawing a line from the line or curve endpoint to the point corresponding to the last PT_MOVETO.
nSize

Specifies the total number of POINT structures that may be placed in the array pointed to by lpPoints. This value must be the same as the number of bytes that may be placed in the array pointed to by lpTypes.

Return Values

If the nSize parameter is nonzero, the return value is the number of points enumerated. If nSize is 0, the return value is the total number of points in the path (and GetPath writes nothing to the buffers). If nSize is nonzero and is less than the number of points in the path, the return value is −1. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_BUFFER_OVERFLOW

Remarks

The device context identified by the hdc parameter must contain a closed path.

The points of the path are returned in logical coordinates. Points are stored in the path in device coordinates, so GetPath changes the points from device coordinates to logical coordinates by using the inverse of the current transformation.

The FlattenPath function may be called before GetPath to convert all curves in the path into line segments.

See Also

FlattenPath, POINT, PolyDraw, WidenPath


GetPixel

The GetPixel function retrieves the red, green, blue (RGB) color value of the pixel at the specified coordinates.

COLORREF GetPixel(

HDC hdc,	// handle of device context
int XPos,	// x-coordinate of pixel
int nYPos	// y-coordinate of pixel
);
Parameters

hdc

Identifies the device context.

nXPos

Specifies the logical x-coordinate of the pixel to be examined.

nYPos

Specifies the logical y-coordinate of the pixel to be examined.

Return Values

If the function succeeds, the return value is an RGB value. If the pixel is outside of the current clipping region, the return value is CLR_INVALID.

Remarks

The pixel must be within the boundaries of the current clipping region.

Not all devices support GetPixel. An application should call GetDeviceCaps to determine whether a specified device supports this function.

See Also

GetDeviceCaps, SetPixel


GetPolyFillMode

The GetPolyFillMode function retrieves the current polygon fill mode.

int GetPolyFillMode(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Values

If the function succeeds, the return value specifies the polygon fill mode, which can be either of the following values:

Value	Meaning
ALTERNATE	Selects alternate mode (fills area between odd-numbered and even-numbered polygon sides on each scan line).
WINDING	Selects winding mode (fills any region with a nonzero winding value).
If an error occurs, the return value is zero.

See Also

SetPolyFillMode


GetPrinter

The GetPrinter function retrieves information about a specified printer.

BOOL GetPrinter(

HANDLE hPrinter,	// handle to printer of interest
DWORD Level,	// version of printer info data structure
LPBYTE pPrinter,	// pointer to array of bytes that receives printer info. structure
DWORD cbBuf,	// size, in bytes, of array of bytes
LPDWORD pcbNeeded	// pointer to variable with count of bytes retrieved (or required)
);
Parameters

hPrinter

Handle to the printer of interest.

Level

Specifies the level, or type, of PRINTER_INFO_* structure that the function stores into the buffer pointed to by pPrinter.

Windows 95: This value can be 1, 2, or 5.

Windows NT: This value can be 1, 2, 3, 4, or 5.

pPrinter

Pointer to a buffer that receives a PRINTER_INFO_* structure. This structure contains information about the specified printer. The type of structure is determined by the value of Level.

Windows 95: The buffer can receive a PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_5 structure.

Windows NT: The buffer can receive a PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_3, PRINTER_INFO_4, or PRINTER_INFO_5 structure.

cbBuf

Specifies the size, in bytes, of the buffer pointed to by pPrinter.

pcbNeeded

Pointer to a variable that the function sets to the size in bytes of the printer information. If cbBuf is smaller than this value, GetPrinter fails, and the value represents the required buffer size. If cbBuf is equal to or greater than this value, GetPrinter succeeds, and the value represents the number of bytes stored into the buffer.

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.

Remarks

If the structure returned in the buffer pointed to by the pPrinter parameter contains a pointer to a security descriptor, only those components of the security descriptor that the caller has permission to read will be present. An application that wants to retrieve particular security descriptor components must open the printer with sufficient access permission. The following table shows the security descriptor components that are retrieved for particular access permission values:

Access Permission	Security Descriptor Components Retrieved
READ_CONTROL	Owner, Primary Group, Discretionary access-control list (ACL)
ACCESS_SYSTEM_SECURITY	System ACL
See Also

AbortPrinter, AddPrinter, ClosePrinter, DeletePrinter, EnumPrinters, PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_3, PRINTER_INFO_4, PRINTER_INFO_5, OpenPrinter, SetPrinter


GetPrinterData

The GetPrinterData function retrieves printer-configuration data for the specified printer.

DWORD GetPrinterData(

HANDLE hPrinter,	// handle of printer object
LPTSTR pValueName,	// address of data type
LPDWORD pType,	// reserved
LPBYTE pData,	// address of array of bytes that receives data
DWORD nSize,	// size, in bytes, of array
LPDWORD pcbNeeded	// address of variable with number of bytes retrieved (or required)
);
Parameters

hPrinter

Identifies the printer for which configuration data should be retrieved.

pValueName

Points to a null-terminated string that specifies the type of data that the function should retrieve.

pType

Points to a variable that receives the data type stored by the SetPrinterData function. GetPrinterData passes pType on as the lpdwType parameter of a RegQueryValueEx function call. This parameter may be NULL.

pData

Points to an array of bytes that receives the configuration data.

nSize

Specifies the size, in bytes, of the buffer pointed to by pData.

pcbNeeded

Points to a value that specifies the number of bytes copied if the function succeeds or the number of bytes required if nSize is too small.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

The printer handle identified by the hPrinter parameter is obtained by calling the OpenPrinter function.

GetPrinterData retrieves printer-configuration data set by the SetPrinter function.

See Also

OpenPrinter, RegQueryValueEx, SetPrinter, SetPrinterData


GetPrinterDriver

The GetPrinterDriver function retrieves driver data for the specified printer.

BOOL GetPrinterDriver(

HANDLE hPrinter,	// printer object
LPTSTR pEnvironment,	// address of environment
DWORD Level,	// structure level
LPBYTE pDriverInfo,	// address of structure array
DWORD cbBuf,	// size, in bytes, of array
LPDWORD pcbNeeded	// address of variable with number of bytes retrieved (or required)
);
Parameters

hPrinter

Identifies the printer for which the driver data should be retrieved.

pEnvironment

Points to a null-terminated string that specifies the environment. For example, “Windows NT x86” specifies Windows NT running on an Intel 80386 or 80486 processor. If this parameter is NULL, the current environment of the calling application and client machine (not of the destination application and print server) is used.

Level

Specifies the version of the structure to which lpbForm points. This value must be either 1, 2., or 3.

pDriverInfo

Points to either a DRIVER_INFO_1, DRIVER_INFO_2, or DRIVER_INFO_3structure. If Level is 1, this array receives a DRIVER_INFO_1 structure; if Level is 2, this array receives a DRIVER_INFO_2 structure, if Level is 3, this array receives a DRIVER_INFO_3 structure.

cbBuf

Specifies the size, in bytes, of the array at which pDriverInfo points.

pcbNeeded

Points to a value that specifies the number of bytes copied if the function succeeds or the number of bytes required if cbBuf is too small.

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.

Remarks

The printer handle identified by the hPrinter parameter should be retrieved by calling the OpenPrinter function.

The DRIVER_INFO_2 and DRIVER_INFO_3 structures contain a full path and filename specifying the location of the printer driver. An application can use the path and filename to load a printer driver by calling the LoadLibrary function and supplying the path and filename as the single argument.

See Also

AddPrinterDriver, DRIVER_INFO_1, DRIVER_INFO_2, EnumPrinterDrivers, LoadLibrary, OpenPrinter


GetPrinterDriverDirectory

The GetPrinterDriverDirectory function retrieves the path of the printer-driver directory.

BOOL GetPrinterDriverDirectory(

LPTSTR pName,	// address of server name
LPTSTR pEnvironment,	// address of environment
DWORD Level,	// address of structure
LPBYTE pDriverDirectory,	// address of structure array that receives path
DWORD cbBuf,	// size, in bytes, of array
LPDWORD pcbNeeded	// address of variable with number of bytes retrieved (or required)
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server on which the printer driver resides. If this parameter is NULL, the local driver-directory path is retrieved.

pEnvironment

Points to a null-terminated string that specifies the environment. For example, “Windows NT x86” specifies Windows NT running on an Intel 80386 or 80486 processor. If this parameter is NULL, the current environment of the calling application and client machine (not of the destination application and print server) is used.

Level

Specifies the structure level. This value must be 1.

pDriverDirectory

Points to an array of bytes that receives the path.

cbBuf

Specifies the size of the array to which pDriverDirectory points.

pcbNeeded

Points to a value that specifies the number of bytes copied if the function succeeds, or the number of bytes required if cbBuf is too small.

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.

See Also

AddPrinterDriver


GetPrintProcessorDirectory

The GetPrintProcessorDirectory function retrieves the path for the print processor on the specified server.

BOOL GetPrintProcessorDirectory(

LPTSTR pName,	// address of server name
LPTSTR pEnvironment,	// address of environment
DWORD Level,	// structure level
LPBYTE pPrintProcessorInfo,	// address of structure array
DWORD cbBuf,	// size, in bytes, of array
LPDWORD pcbNeeded	// address of variable with number of bytes retrieved (or required)
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server. If this parameter is NULL, a local path is returned.

pEnvironment

Points to a null-terminated string that specifies the environment. For example, “Windows NT x86” specifies Windows NT running on an Intel 80386 or 80486 processor. If this parameter is NULL, the current environment of the calling application and client machine (not of the destination application and print server) is used.

Level

Specifies the structure level. This value must be 1.

pPrintProcessorInfo

Points to an array of bytes into which the path is copied.

cbBuf

Specifies the size of the buffer pointed to by pPrintProcessorInfo.

pcbNeeded

Points to a value that specifies the number of bytes copied if the function succeeds, or the number of bytes required if cbBuf is too small.

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.

See Also

AddPrintProcessor


GetPriorityClass

The GetPriorityClass function returns the priority class for the specified process. This value, together with the priority value of each thread of the process, determines each thread’s base priority level.

DWORD GetPriorityClass(

HANDLE hProcess	// handle to the process
);
Parameters

hProcess

Identifies the process.

Windows NT: The handle must have PROCESS_QUERY_INFORMATION access. For more information, see Process Objects.

Return Values

If the function succeeds, the return value is the priority class of the specified process.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

The process’s priority class is one of the following values:

Priority	Meaning
HIGH_PRIORITY_CLASS	Indicates a process that performs time-critical tasks that must be executed immediately for it to run correctly. The threads of a high-priority class process preempt the threads of normal or idle priority class processes. An example is Windows Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class CPU-bound application can use nearly all available cycles.
IDLE_PRIORITY_CLASS	Indicates a process whose threads run only when the system is idle and are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle priority class is inherited by child processes.
NORMAL_PRIORITY_CLASS	Indicates a normal process with no special scheduling needs.
REALTIME_PRIORITY_CLASS	Indicates a process that has the highest possible priority. The threads of a real-time priority class process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.
Remarks

Every thread has a base priority level determined by the thread’s priority value and the priority class of its process. The operating system uses the base priority level of all executable threads to determine which thread gets the next slice of CPU time. Threads are scheduled in a round-robin fashion at each priority level, and only when there are no executable threads at a higher level will scheduling of threads at a lower level take place.

For a table that shows the base priority levels for each combination of priority class and thread priority value, see the SetPriorityClass function.

See Also

GetThreadPriority, SetPriorityClass, SetThreadPriority


GetPriorityClipboardFormat

The GetPriorityClipboardFormat function returns the first available clipboard format in the specified list.

int GetPriorityClipboardFormat(

UINT *paFormatPriorityList,	// address of priority list
int cFormats	// number of entries in list
);
Parameters

paFormatPriorityList

Points to an array of unsigned integers identifying clipboard formats, in priority order. For a description of the clipboard formats, see the SetClipboardData function.

cFormats

Specifies the number of entries in the paFormatPriorityList array. This value must not be greater than the number of entries in the list.

Return Values

If the function succeeds, the return value is the first clipboard format in the list for which data is available. If the clipboard is empty, the return value is NULL. If the clipboard contains data, but not in any of the specified formats, the return value is −1. To get extended error information, call GetLastError.

See Also

CountClipboardFormats, EnumClipboardFormats, GetClipboardFormatName, IsClipboardFormatAvailable, RegisterClipboardFormat, SetClipboardData


GetPrivateObjectSecurity

The GetPrivateObjectSecurity retrieves information from a protected server object’s security descriptor.

BOOL GetPrivateObjectSecurity(

PSECURITY_DESCRIPTOR ObjectDescriptor,	// address of SD to query
SECURITY_INFORMATION SecurityInformation,	// requested information
PSECURITY_DESCRIPTOR ResultantDescriptor,	// address of retrieved SD
DWORD DescriptorLength,	// size of buffer for retrieved SD
PDWORD ReturnLength	// address of buffer size required for SD
);
Parameters

ObjectDescriptor

Points to a SECURITY_DESCRIPTOR structure. This is the security descriptor to be queried.

SecurityInformation

Specifies a SECURITY_INFORMATION structure that identifies the security information being requested.

ResultantDescriptor

Points to a buffer receiving a copy of the requested information from the specified security descriptor. The SECURITY_DESCRIPTOR structure is returned in self-relative format.

DescriptorLength

Specifies the size, in bytes, of the buffer pointed to by the ResultantDescriptor parameter.

ReturnLength

Points to a variable the function sets to zero if the descriptor is copied successfully. If the buffer is too small for the security descriptor, this variable receives the number of bytes required. If this variable’s value is greater than the value of the DescriptorLength parameter when the function returns, the function returns FALSE and none of the security descriptor is copied to the buffer.

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.

Remarks

An application must perform appropriate access/privilege checks and audits before calling this function.

See Also

CreatePrivateObjectSecurity, DestroyPrivateObjectSecurity, GetFileSecurity, GetKernelObjectSecurity, GetUserObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetPrivateObjectSecurity


GetPrivateProfileInt

The GetPrivateProfileInt function retrieves an integer associated with a key in the specified section of the given initialization file. This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

UINT GetPrivateProfileInt(

LPCTSTR lpAppName,	// address of section name
LPCTSTR lpKeyName,	// address of key name
INT nDefault,	// return value if key name is not found
LPCTSTR lpFileName	// address of initialization filename
);
Parameters

lpAppName

Points to a null-terminated string containing the section name in the initialization file.

lpKeyName

Points to the null-terminated string containing the key name whose value is to be retrieved. This value is in the form of a string; the GetPrivateProfileInt function converts the string into an integer and returns the integer.

nDefault

Specifies the default value to return if the key name cannot be found in the initialization file.

lpFileName

Points to a null-terminated string that names the initialization file. If this parameter does not contain a full path to the file, Windows searches for the file in the Windows directory.

Return Values

If the function succeeds, the return value is the integer equivalent of the string following the specified key name in the specified initialization file. If the key is not found, the return value is the specified default value. If the value of the key is less than zero, the return value is zero.

Remarks

The function searches the file for a key that matches the name specified by the lpKeyName parameter under the section name specified by the lpAppName parameter. A section in the initialization file must have the following form:

[section]
key=value
      .
      .
      .

The GetPrivateProfileInt function is not case-sensitive; the strings in lpAppName and lpKeyName can be a combination of uppercase and lowercase letters.

An application can use the GetProfileInt function to retrieve an integer value from the WIN.INI file.

Windows NT:

Calls to private profile functions may be mapped to the registry instead of to the specified initialization files. This mapping occurs when the initialization file and section are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

This mapping is likely if an application modifies system-component initialization files, such as CONTROL.INI, SYSTEM.INI, and WINFILE.INI. In these cases, the GetPrivateProfileInt function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function’s behavior.

The Win32 Profile functions (Get/WriteProfile*, Get/WritePrivateProfile*) use the following steps to locate initialization information:

1.	Look in the registry for the name of the initialization file, say myfile.ini, under IniFileMapping:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping\myfile.ini

2.	Look for the section name specified by lpAppName. This will be a named value under myfile.ini, or a subkey of myfile.ini, or will not exist.

3.	If the section name specified by lpAppName is a named value under myfile.ini, then that value specifies where in the registry you will find the keys for the section.

4.	If the section name specified by lpAppName is a subkey of myfile.ini, then named values under that subkey specify where in the registry you will find the keys for the section. If the key you are looking for does not exist as a named value, then there will be an unnamed value (shown as "<No Name>") that specifies the default location in the registry where you will find the key.

5.	If the section name specified by lpAppName does not exist as a named value or as a subkey under myfile.ini, then there will be an unnamed value (shown as "<No Name>") under myfile.ini that specifies the default location in the registry where you will find the keys for the section.

6.	If there is no subkey for myfile.ini, or if there is no entry for the section name, then look for the actual myfile.ini on the disk and read its contents.

When looking at values in the registry that specify other registry locations, there are several prefixes that change the behavior of the ini file mapping:

! - this character forces all writes to go both to the registry and to the .INI file on disk.

# - this character causes the registry value to be set to the value in the Windows 3.1 .INI file when a new user logs in for the first time after setup.

@ - this character prevents any reads from going to the .INI file on disk if the requested data is not found in the registry.

USR: - this prefix stands for HKEY_CURRENT_USER, and the text after the prefix is relative to that key.

SYS: - this prefix stands for HKEY_LOCAL_MACHINE\SOFTWARE, and the text after the prefix is relative to that key.

See Also

GetProfileInt, WritePrivateProfileString


GetPrivateProfileSection

The GetPrivateProfileSection function retrieves all of the keys and values for the specified section from an initialization file. This function is provided for compatibility with 16-bit applications written for Windows. Win32-based applications should store initialization information in the registry.

Windows 95:

The specified profile section must not exceed 32K.

Windows NT:

The specified profile section has no size limit.

DWORD GetPrivateProfileSection(

LPCTSTR lpAppName,	// address of section name
LPTSTR lpReturnedString,	// address of return buffer
DWORD nSize,	// size of return buffer
LPCTSTR lpFileName	// address of initialization filename
);
Parameters

lpAppName

Points to a null-terminated string containing the section name in the initialization file.

lpReturnedString

Points to a buffer that receives the key name and value pairs associated with the named section. The buffer is filled with one or more null-terminated strings; the last string is followed by a second null character.

nSize

Specifies the size, in characters, of the buffer pointed to by the lpReturnedString parameter.

Windows 95:

The maximum buffer size is 32,767 characters.

Windows NT:

There is no maximum buffer size.

lpFileName

Points to a null-terminated string that names the initialization file. If this parameter does not contain a full path to the file, Windows searches for the file in the Windows directory.

Return Values

The return value specifies the number of characters copied to the buffer, not including the terminating null character. If the buffer is not large enough to contain all the key name and value pairs associated with the named section, the return value is equal to nSize minus two.

Remarks

The data in the buffer pointed to by the lpReturnedString parameter consists of one or more null-terminated strings, followed by a final null character. Each string has the following format:

key=string

The GetPrivateProfileSection function is not case-sensitive; the string pointed to by the lpAppName parameter can be a combination of uppercase and lowercase letters.

This operation is atomic; no updates to the specified initialization file are allowed while the key name and value pairs for the section are being copied to the buffer pointed to by the lpReturnedString parameter.

Windows NT:

Calls to private profile functions may be mapped to the registry instead of to the specified initialization files. This mapping occurs when the initialization file and section are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

This mapping is likely if an application modifies system-component initialization files, such as CONTROL.INI, SYSTEM.INI, and WINFILE.INI. In these cases, the GetPrivateProfileSection function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function’s behavior.

The Win32 Profile functions (Get/WriteProfile*, Get/WritePrivateProfile*) use the following steps to locate initialization information:

1.	Look in the registry for the name of the initialization file, say myfile.ini, under IniFileMapping:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping\myfile.ini

2.	Look for the section name specified by lpAppName. This will be a named value under myfile.ini, or a subkey of myfile.ini, or will not exist.

3.	If the section name specified by lpAppName is a named value under myfile.ini, then that value specifies where in the registry you will find the keys for the section.

4.	If the section name specified by lpAppName is a subkey of myfile.ini, then named values under that subkey specify where in the registry you will find the keys for the section. If the key you are looking for does not exist as a named value, then there will be an unnamed value (shown as "<No Name>") that specifies the default location in the registry where you will find the key.

5.	If the section name specified by lpAppName does not exist as a named value or as a subkey under myfile.ini, then there will be an unnamed value (shown as "<No Name>") under myfile.ini that specifies the default location in the registry where you will find the keys for the section.

6.	If there is no subkey for myfile.ini, or if there is no entry for the section name, then look for the actual myfile.ini on the disk and read its contents.

When looking at values in the registry that specify other registry locations, there are several prefixes that change the behavior of the ini file mapping:

! - this character forces all writes to go both to the registry and to the .INI file on disk.

# - this character causes the registry value to be set to the value in the Windows 3.1 .INI file when a new user logs in for the first time after setup.

@ - this character prevents any reads from going to the .INI file on disk if the requested data is not found in the registry.

USR: - this prefix stands for HKEY_CURRENT_USER, and the text after the prefix is relative to that key.

SYS: - this prefix stands for HKEY_LOCAL_MACHINE\SOFTWARE, and the text after the prefix is relative to that key.

See Also

GetProfileSection, WritePrivateProfileSection


GetPrivateProfileSectionNames

The GetPrivateProfileSectionNames function retrieves the names of all sections in an initialization file. This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

DWORD GetPrivateProfileSectionNames(

LPTSTR lpszReturnBuffer,	// address of return buffer
DWORD nSize,	// size of return buffer
LPCTSTR lpFileName	// address of initialization filename
);
Parameters

lpszReturnBuffer

Points to a buffer that receives the section names associated with the named file. The buffer is filled with one or more null-terminated strings; the last string is followed by a second null character.

nSize

Specifies the size, in characters, of the buffer pointed to by the lpszReturnBuffer parameter.

lpFileName

Points to a null-terminated string that names the initialization file. If this parameter is NULL, the function searches the WIN.INI file. If this parameter does not contain a full path to the file, Windows searches for the file in the Windows directory.

Return Values

The return value specifies the number of characters copied to the specified buffer, not including the terminating null character. If the buffer is not large enough to contain all the section names associated with the specified initialization file, the return value is equal to the length specified by nSize minus two.

Remarks

This operation is atomic; no updates to the initialization file are allowed while the section names are being copied to the buffer.

Calls to profile functions might be mapped to the registry instead of to the initialization files. When the operation has been mapped, the GetPrivateProfileSectionNames function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function’s behavior.

The Win32 Profile functions (Get/WriteProfile*, Get/WritePrivateProfile*) use the following steps to locate initialization information:

1.	Look in the registry for the name of the initialization file, say myfile.ini, under IniFileMapping:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping\myfile.ini

2.	Look for the section name specified by lpAppName. This will be a named value under myfile.ini, or a subkey of myfile.ini, or will not exist.

3.	If the section name specified by lpAppName is a named value under myfile.ini, then that value specifies where in the registry you will find the keys for the section.

4.	If the section name specified by lpAppName is a subkey of myfile.ini, then named values under that subkey specify where in the registry you will find the keys for the section. If the key you are looking for does not exist as a named value, then there will be an unnamed value (shown as "<No Name>") that specifies the default location in the registry where you will find the key.

5.	If the section name specified by lpAppName does not exist as a named value or as a subkey under myfile.ini, then there will be an unnamed value (shown as "<No Name>") under myfile.ini that specifies the default location in the registry where you will find the keys for the section.

6.	If there is no subkey for myfile.ini, or if there is no entry for the section name, then look for the actual myfile.ini on the disk and read its contents.

When looking at values in the registry that specify other registry locations, there are several prefixes that change the behavior of the ini file mapping:

! - this character forces all writes to go both to the registry and to the .INI file on disk.

# - this character causes the registry value to be set to the value in the Windows 3.1 .INI file when a new user logs in for the first time after setup.

@ - this character prevents any reads from going to the .INI file on disk if the requested data is not found in the registry.

USR: - this prefix stands for HKEY_CURRENT_USER, and the text after the prefix is relative to that key.

SYS: - this prefix stands for HKEY_LOCAL_MACHINE\SOFTWARE, and the text after the prefix is relative to that key.

See Also

GetPrivateProfileSection, WritePrivateProfileSection


GetPrivateProfileString

The GetPrivateProfileString function retrieves a string from the specified section in an initialization file. This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

DWORD GetPrivateProfileString(

LPCTSTR lpAppName,	// points to section name
LPCTSTR lpKeyName,	// points to key name
LPCTSTR lpDefault,	// points to default string
LPTSTR lpReturnedString,	// points to destination buffer
DWORD nSize,	// size of destination buffer
LPCTSTR lpFileName	// points to initialization filename
);
Parameters

lpAppName

Points to a null-terminated string that specifies the section containing the key name. If this parameter is NULL, the GetPrivateProfileString function copies all section names in the file to the supplied buffer.

lpKeyName

Pointer to the null-terminated string containing the key name whose associated string is to be retrieved. If this parameter is NULL, all key names in the section specified by the lpAppName parameter are copied to the buffer specified by the lpReturnedString parameter.

lpDefault

Pointer to a null-terminated default string. If the lpKeyName key cannot be found in the initialization file, GetPrivateProfileString copies the default string to the lpReturnedString buffer. This parameter cannot be NULL.

Avoid specifying a default string with trailing blank characters. The function inserts a null character in the lpReturnedString buffer to strip any trailing blanks.

Windows 95: Although lpDefault is declared as a constant parameter, Windows 95 strips any trailing blanks by inserting a null character into the lpDefault string before copying it to the lpReturnedString buffer.

Windows NT: Windows NT does not modify the lpDefault string. This means that if the default string contains trailing blanks, the lpReturnedString and lpDefault strings will not match when compared using the lstrcmp function.

lpReturnedString

Pointer to the buffer that receives the retrieved string.

nSize

Specifies the size, in characters, of the buffer pointed to by the lpReturnedString parameter.

lpFileName

Pointer to a null-terminated string that names the initialization file. If this parameter does not contain a full path to the file, Windows searches for the file in the Windows directory.

Return Values

If the function succeeds, the return value is the number of characters copied to the buffer, not including the terminating null character.

If neither lpAppName nor lpKeyName is NULL and the supplied destination buffer is too small to hold the requested string, the string is truncated and followed by a null character, and the return value is equal to nSize minus one.

If either lpAppName or lpKeyName is NULL and the supplied destination buffer is too small to hold all the strings, the last string is truncated and followed by two null characters. In this case, the return value is equal to nSize minus two.

Remarks

The GetPrivateProfileString function searches the specified initialization file for a key that matches the name specified by the lpKeyName parameter under the section heading specified by the lpAppName parameter. If it finds the key, the function copies the corresponding string to the buffer. If the key does not exist, the function copies the default character string specified by the lpDefault parameter. A section in the initialization file must have the following form:

[section]
key=string
      .
      .
      .

If lpAppName is NULL, GetPrivateProfileString copies all section names in the specified file to the supplied buffer. If lpKeyName is NULL, the function copies all key names in the specified section to the supplied buffer. An application can use this method to enumerate all of the sections and keys in a file. In either case, each string is followed by a null character and the final string is followed by a second null character. If the supplied destination buffer is too small to hold all the strings, the last string is truncated and followed by two null characters.

If the string associated with lpKeyName is enclosed in single or double quotation marks, the marks are discarded when the GetPrivateProfileString function retrieves the string.

The GetPrivateProfileString function is not case-sensitive; the strings can be a combination of uppercase and lowercase letters.

To retrieve a string from the WIN.INI file, use the GetProfileString function.

Windows NT:

Calls to private profile functions may be mapped to the registry instead of to the specified initialization files. This mapping occurs when the initialization file and section are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

This mapping is likely if an application modifies system-component initialization files, such as CONTROL.INI, SYSTEM.INI, and WINFILE.INI. In these cases, the GetPrivateProfileString function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function’s behavior.

The Win32 Profile functions (Get/WriteProfile*, Get/WritePrivateProfile*) use the following steps to locate initialization information:

1.	Look in the registry for the name of the initialization file, say myfile.ini, under IniFileMapping:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping\myfile.ini

2.	Look for the section name specified by lpAppName. This will be a named value under myfile.ini, or a subkey of myfile.ini, or will not exist.

3.	If the section name specified by lpAppName is a named value under myfile.ini, then that value specifies where in the registry you will find the keys for the section.

4.	If the section name specified by lpAppName is a subkey of myfile.ini, then named values under that subkey specify where in the registry you will find the keys for the section. If the key you are looking for does not exist as a named value, then there will be an unnamed value (shown as "<No Name>") that specifies the default location in the registry where you will find the key.

5.	If the section name specified by lpAppName does not exist as a named value or as a subkey under myfile.ini, then there will be an unnamed value (shown as "<No Name>") under myfile.ini that specifies the default location in the registry where you will find the keys for the section.

6.	If there is no subkey for myfile.ini, or if there is no entry for the section name, then look for the actual myfile.ini on the disk and read its contents.

When looking at values in the registry that specify other registry locations, there are several prefixes that change the behavior of the ini file mapping:

! - this character forces all writes to go both to the registry and to the .INI file on disk.

# - this character causes the registry value to be set to the value in the Windows 3.1 .INI file when a new user logs in for the first time after setup.

@ - this character prevents any reads from going to the .INI file on disk if the requested data is not found in the registry.

USR: - this prefix stands for HKEY_CURRENT_USER, and the text after the prefix is relative to that key.

SYS: - this prefix stands for HKEY_LOCAL_MACHINE\SOFTWARE, and the text after the prefix is relative to that key.

See Also

GetProfileString, WritePrivateProfileString


GetPrivateProfileStruct

The GetPrivateProfileStruct function retrieves the data associated with the specified key in the given section of an initialization file. As it retrieves the data, the function calculates a checksum and compares it with the checksum calculated by the WritePrivateProfileStruct function when the data was added to the file.

Win32-based applications should store initialization information in the registry.

BOOL GetPrivateProfileStruct(

LPCTSTR lpszSection,	// address of section name
LPCTSTR lpszKey,	// address of key name
LPVOID lpStruct,	// address of return buffer
UINT uSizeStruct,	// size of return buffer
LPCTSTR szFile	// address of initialization filename
);
Parameters

lpszSection

Points to a null-terminated string containing the section name in the initialization file.

lpszKey

Points to the null-terminated string containing the key name whose data is to be retrieved.

lpStruct

Points to the buffer that receives the data associated with the file, section, and key names.

uSizeStruct

Specifies the size, in bytes, of the buffer pointed to by the lpStruct parameter.

szFile

Points to a null-terminated string that names the initialization file. If this parameter does not contain a full path to the file, Windows searches for the file in the Windows directory.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

A section in the initialization file must have the following form:

[section]
key=data
      .
      .
      .

Calls to private profile functions might be mapped to the registry instead of to the specified initialization files. This mapping is likely if an application modifies system-component initialization files, such as CONTROL.INI, SYSTEM.INI, and WINFILE.INI. In these cases, the GetPrivateProfileStruct function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function’s behavior.

The Win32 Profile functions (Get/WriteProfile*, Get/WritePrivateProfile*) use the following steps to locate initialization information:

1.	Look in the registry for the name of the initialization file, say myfile.ini, under IniFileMapping:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping\myfile.ini

2.	Look for the section name specified by lpAppName. This will be a named value under myfile.ini, or a subkey of myfile.ini, or will not exist.

3.	If the section name specified by lpAppName is a named value under myfile.ini, then that value specifies where in the registry you will find the keys for the section.

4.	If the section name specified by lpAppName is a subkey of myfile.ini, then named values under that subkey specify where in the registry you will find the keys for the section. If the key you are looking for does not exist as a named value, then there will be an unnamed value (shown as "<No Name>") that specifies the default location in the registry where you will find the key.

5.	If the section name specified by lpAppName does not exist as a named value or as a subkey under myfile.ini, then there will be an unnamed value (shown as "<No Name>") under myfile.ini that specifies the default location in the registry where you will find the keys for the section.

6.	If there is no subkey for myfile.ini, or if there is no entry for the section name, then look for the actual myfile.ini on the disk and read its contents.

When looking at values in the registry that specify other registry locations, there are several prefixes that change the behavior of the ini file mapping:

! - this character forces all writes to go both to the registry and to the .INI file on disk.

# - this character causes the registry value to be set to the value in the Windows 3.1 .INI file when a new user logs in for the first time after setup.

@ - this character prevents any reads from going to the .INI file on disk if the requested data is not found in the registry.

USR: - this prefix stands for HKEY_CURRENT_USER, and the text after the prefix is relative to that key.

SYS: - this prefix stands for HKEY_LOCAL_MACHINE\SOFTWARE, and the text after the prefix is relative to that key.

See Also

WritePrivateProfileStruct


GetProcAddress

The GetProcAddress function returns the address of the specified exported dynamic-link library (DLL) function.

FARPROC GetProcAddress(

HMODULE hModule,	// handle to DLL module
LPCSTR lpProcName	// name of function
);
Parameters

hModule

Identifies the DLL module that contains the function. The LoadLibrary or GetModuleHandle function returns this handle.

lpProcName

Points to a null-terminated string containing the function name, or specifies the function’s ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero.

Return Values

If the function succeeds, the return value is the address of the DLL’s exported function.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The GetProcAddress function is used to retrieve addresses of exported functions in DLLs.

The spelling and case of the function name pointed to by lpProcName must be identical to that in the EXPORTS statement of the source DLL’s module-definition (.DEF) file.

The lpProcName parameter can identify the DLL function by specifying an ordinal value associated with the function in the EXPORTS statement. GetProcAddress verifies that the specified ordinal is in the range 1 through the highest ordinal value exported in the .DEF file. The function then uses the ordinal as an index to read the function’s address from a function table. If the .DEF file does not number the functions consecutively from 1 to N (where N is the number of exported functions), an error can occur where GetProcAddress returns an invalid, non-NULL address, even though there is no function with the specified ordinal.

In cases where the function may not exist, the function should be specified by name rather than by ordinal value.

See Also

FreeLibrary, GetModuleHandle, LoadLibrary


GetProcessAffinityMask

The GetProcessAffinityMask function obtains a process affinity mask for the specified process and the system affinity mask for the system.

A process affinity mask is a bit vector in which each bit represents the processors that a process is allowed to run on. A system affinity mask is a bit vector in which each bit represents the processors that are configured into a system.

A process affinity mask is a proper subset of a system affinity mask. A process is only allowed to run on the processors configured into a system.

BOOL GetProcessAffinityMask(

HANDLE hProcess,	// handle to the process of interest
LPDWORD lpProcessAffinityMask,	// pointer to structure to receive process affinity mask
LPDWORD lpSystemAffinityMask	// pointer to structure to receive system affinity mask
);
Parameters

hProcess

An open handle to the process whose affinity mask is desired.

Windows NT: This handle must have PROCESS_QUERY_INFORMATION access. For more information, see Process Objects.

lpProcessAffinityMask

Pointer to a DWORD that the function sets to the process affinity mask for the specified process.

lpSystemAffinityMask

Pointer to a DWORD that the function sets to the system affinity mask for the system.

Return Values

If the function succeeds, the return value is nonzero.

Windows NT: Upon success, the function sets the DWORD variables pointed to by lpProcessAffinityMask and lpSystemAffinityMask to the appropriate affinity masks.

Windows 95: Upon success, the function sets the DWORD variables pointed to by lpProcessAffinityMask and lpSystemAffinityMask to the value one.

If the function fails, the return value is zero, and the values of the DWORD variables pointed to by lpProcessAffinityMask and lpSystemAffinityMask are undefined.

See Also

SetProcessAffinityMask, SetThreadAffinityMask


GetProcessHeap

The GetProcessHeap function obtains a handle to the heap of the calling process. This handle can then be used in calls to the HeapAlloc, HeapReAlloc, HeapFree, and HeapSize functions.

HANDLE GetProcessHeap(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is a handle to the calling process’s heap.

If the function fails, the return value is NULL.

Remarks

GetProcessHeap allows Win32-based applications to allocate memory from the process heap without having to first create a heap with the HeapCreate function, as shown in this example:

HeapAlloc(GetProcessHeap(), 0, dwBytes);

Note that the handle obtained by calling the function should not be used in calls to the HeapDestroy function.

Note, also, that the HEAP_NO_SERIALIZE flag should not be specified when using the HeapAlloc, HeapFree, HeapReAlloc, and HeapSize functions to access the process heap. The system may create additional threads within the application’s process, such as a Ctrl+C handler, that simultaneously access the process heap. For more information about HEAP_NO_SERIALIZE, see the HeapCreate function.

See Also

GetProcessHeaps, HeapAlloc, HeapCreate, HeapDestroy, HeapFree, HeapReAlloc, HeapSize


GetProcessHeaps

The GetProcessHeaps function obtains handles to all of the heaps that are valid for the calling process.

DWORD GetProcessHeaps(

DWORD NumberOfHeaps,	// maximum number of heap handles buffer can receive
PHANDLE ProcessHeaps	// points to buffer to receive array of heap handles
);
Parameters

NumberOfHeaps

Specifies the maximum number of heap handles that can be stored into the buffer pointed to by ProcessHeaps.

ProcessHeaps

Points to a buffer to receive an array of heap handles.

Return Values

The return value is the number of heap handles that are valid for the calling process.

If the return value is less than or equal to NumberOfHeaps, it is also the number of heap handles stored into the buffer pointed to by ProcessHeaps.

If the return value is greater than NumberOfHeaps, the buffer pointed to by ProcessHeaps is too small to hold all the valid heap handles of the calling process.The function will have stored no handles into that buffer. In this situation, use the return value to allocate a buffer that is large enough to receive the handles, and call the function again.

If the return value is zero, the function has failed, because every Win32 process has at least one valid heap, the process heap. To get extended error information, call GetLastError.

Remarks

Use the GetProcessHeap function to obtain a handle to the process heap of the calling process. The GetProcessHeaps function obtains a handle to that heap, plus handles to any additional private heaps created by calling the HeapCreate function.

See Also

GetProcessHeap, HeapCreate


GetProcessPriorityBoost [New - Windows NT]
GetProcessPriorityBoost

[New - Windows NT]

The GetProcessPriorityBoost function returns the priority boost control state of the specified process.

BOOL GetProcessPriorityBoost(

HANDLE hProcess,	// handle to process
PBOOL pDisablePriorityBoost	// indicates priority boost control state
);
Parameters

hProcess

Handle to the process. This handle must have the PROCESS_QUERY_INFORMATION access right. For more information, see Process Objects.

pDisablePriorityBoost

Pointer to a Boolean variable that receives the priority boost control state. A value of TRUE indicates that dynamic boosting is disabled. A value of FALSE indicates normal behavior.

Return Values

If the function succeeds, the return value is nonzero. In that case, the Boolean variable pointed to by the pDisablePriorityBoost parameter receives the priority boost control state.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

SetProcessPriorityBoost


GetProcessShutdownParameters

The GetProcessShutdownParameters function retrieves shutdown parameters for the currently calling process.

BOOL GetProcessShutdownParameters(

LPDWORD lpdwLevel,	// shutdown priority
LPDWORD lpdwFlags	// shutdown flag
);
Parameters

lpdwLevel

Points to a variable that receives the shutdown priority level. Higher levels shut down first. System level shutdown orders are reserved for system components. Higher numbers shut down first. Following are the level conventions:

Value	Meaning
000−0FF	System reserved last shutdown range.
100−1FF	Application reserved last shutdown range.
200−2FF	Application reserved “in between” shutdown range.
300−3FF	Application reserved first shutdown range.
400−4FF	System reserved first shutdown range.
All processes start at shutdown level 0x280.

lpdwFlags

Points to a variable that receives the shutdown flags. It can be the following value:

Value	Meaning
SHUTDOWN_NORETRY	If this process takes longer than the specified timeout to shut down, do not display a retry dialog box for the user. Instead, just cause the process to directly exit.
Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

SetProcessShutdownParameters


GetProcessTimes

The GetProcessTimes function obtains timing information about a specified process.

BOOL GetProcessTimes(

HANDLE hProcess,	// specifies the process of interest
LPFILETIME lpCreationTime,	// when the process was created
LPFILETIME lpExitTime,	// when the process exited
LPFILETIME lpKernelTime,	// time the process has spent in kernel mode
LPFILETIME lpUserTime	// time the process has spent in user mode
);
Parameters

hProcess

An open handle that specifies the process whose timing information is sought. This handle must be created with PROCESS_QUERY_INFORMATION access. For more information, see Process Objects.

lpCreationTime

Points to a FILETIME structure that receives the creation time of the process.

lpExitTime

Points to a FILETIME structure that receives the exit time of the process. If the process has not exited, the content of this structure is undefined.

lpKernelTime

Points to a FILETIME structure that receives the amount of time that the process has executed in kernel mode. The time that each of the threads of the process has executed in kernel mode is determined, and then all of those times are summed together to obtain this value.

lpUserTime

Points to a FILETIME structure that receives the amount of time that the process has executed in user mode. The time that each of the threads of the process has executed in user mode is determined, and then all of those times are summed together to obtain this value.

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.

Remarks

All times are expressed using FILETIME data structures. Such a structure contains two 32-bit values that combine to form a 64-bit count of 100-nanosecond time units.

Process creation and exit times are points in time expressed as the amount of time that has elapsed since midnight on January 1, 1601 at Greenwich, England. The Win32 API provides several functions that an application can use to convert such values to more generally useful forms.

Process kernel mode and user mode times are amounts of time. For example, if a process has spent one second in kernel mode, this function will fill the FILETIME structure specified by lpKernelTime with a 64-bit value of ten million. That is the number of 100-nanosecond units in one second.

See Also

FILETIME, FileTimeToDosDateTime, FileTimeToLocalFileTime, FileTimeToSystemTime


GetProcessVersion

The GetProcessVersion function obtains the major and minor version numbers of the Windows version on which a specified process expects to run.

DWORD GetProcessVersion(

DWORD ProcessId	// identifier specifying the process of interest
);
Parameters

ProcessId

Process identifier that specifies the process of interest. A ProcessId value of zero specifies the calling process.

Return Values

If the function succeeds, the return value is the version of Windows on which the process expects to run. The high word of the return value contains the major version number. The low word of the return value contains the minor version number.

If the function fails, the return value is zero. To get extended error information, call GetLastError. The function fails if ProcessId is an invalid value.

Remarks

The GetProcessVersion function performs less quickly when ProcessId is nonzero, specifying a process other than the calling process.

The version number returned by this function is the version number stamped in the image header of the .EXE file the process is running. Linker programs set this value.


GetProcessWindowStation

The GetProcessWindowStation function returns a handle of the window station associated with the calling process.

HWINSTA GetProcessWindowStation(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is a handle of the window station associated with the calling process.

If the function fails, the return value is NULL. This can occur if the calling process is not an application written for Windows NT. To get extended error information, call GetLastError.

Remarks

The system associates a window station with a process when the process is created. A process can use the SetProcessWindowStation function to change its window station.

The calling process can use the returned handle in calls to the GetUserObjectInformation, GetUserObjectSecurity, SetUserObjectInformation, and SetUserObjectSecurity functions.

See Also

GetThreadDesktop, GetUserObjectInformation, GetUserObjectSecurity, SetProcessWindowStation, SetUserObjectInformation, SetUserObjectSecurity


GetProcessWorkingSetSize

The GetProcessWorkingSetSize function obtains the minimum and maximum working set sizes of a specified process.

The “working set” of a process is the set of memory pages currently visible to the process in physical RAM memory. These pages are resident and available for an application to use without triggering a page fault. The size of a process’ working set is specified in bytes. The minimum and maximum working set sizes affect the virtual memory paging behavior of a process.

BOOL GetProcessWorkingSetSize(

HANDLE hProcess,	// open handle to the process of interest
LPDWORD lpMinimumWorkingSetSize,	// points to variable to receive minimum working set size
LPDWORD lpMaximumWorkingSetSize	// points to variable to receive maximum working set size
);
Parameters

hProcess

An open handle to the process whose working set sizes will be obtained. The handle must have PROCESS_QUERY_INFORMATION access rights. For more information, see Process Objects.

lpMinimumWorkingSetSize

Points to a variable that receives the minimum working set size of the specified process. The virtual memory manager attempts to keep at least this much memory resident in the process whenever the process is active.

lpMaximumWorkingSetSize

Points to a variable that receives the maximum working set size of the specified process. The virtual memory manager attempts to keep no more than this much memory resident in the process whenever the process is active when memory is in short supply.

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.

See Also

SetProcessWorkingSetSize


GetProfileInt

The GetProfileInt function retrieves an integer from the specified key name in the given section of the WIN.INI file. This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

UINT GetProfileInt(

LPCTSTR lpAppName,	// address of section name
LPCTSTR lpKeyName,	// address of key name
INT nDefault	// default value if key name is not found
);
Parameters

lpAppName

Points to a null-terminated string that specifies the section containing the key name.

lpKeyName

Points to the null-terminated string containing the key name whose value is to be retrieved. This value is in the form of a string; the GetProfileInt function converts the string into an integer and returns the integer.

nDefault

Specifies the default value to return if the key name cannot be found in the initialization file.

Return Values

If the function succeeds, the return value is the integer equivalent of the string following the key name in WIN.INI. If the function cannot find the key, the return value is the default value. If the value of the key is less than zero, the return value is zero.

Remarks

If the key name consists of digits followed by characters that are not numeric, the function returns only the value of the digits. For example, the function returns 102 for the following line: KeyName=102abc.

Windows NT:

Calls to profile functions may be mapped to the registry instead of to the initialization files. This mapping occurs when the initialization file and section are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

When the operation has been mapped, the GetProfileInt function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function’s behavior.

The Win32 Profile functions (Get/WriteProfile*, Get/WritePrivateProfile*) use the following steps to locate initialization information:

1.	Look in the registry for the name of the initialization file, say myfile.ini, under IniFileMapping:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping\myfile.ini

2.	Look for the section name specified by lpAppName. This will be a named value under myfile.ini, or a subkey of myfile.ini, or will not exist.

3.	If the section name specified by lpAppName is a named value under myfile.ini, then that value specifies where in the registry you will find the keys for the section.

4.	If the section name specified by lpAppName is a subkey of myfile.ini, then named values under that subkey specify where in the registry you will find the keys for the section. If the key you are looking for does not exist as a named value, then there will be an unnamed value (shown as "<No Name>") that specifies the default location in the registry where you will find the key.

5.	If the section name specified by lpAppName does not exist as a named value or as a subkey under myfile.ini, then there will be an unnamed value (shown as "<No Name>") under myfile.ini that specifies the default location in the registry where you will find the keys for the section.

6.	If there is no subkey for myfile.ini, or if there is no entry for the section name, then look for the actual myfile.ini on the disk and read its contents.

When looking at values in the registry that specify other registry locations, there are several prefixes that change the behavior of the ini file mapping:

! - this character forces all writes to go both to the registry and to the .INI file on disk.

# - this character causes the registry value to be set to the value in the Windows 3.1 .INI file when a new user logs in for the first time after setup.

@ - this character prevents any reads from going to the .INI file on disk if the requested data is not found in the registry.

USR: - this prefix stands for HKEY_CURRENT_USER, and the text after the prefix is relative to that key.

SYS: - this prefix stands for HKEY_LOCAL_MACHINE\SOFTWARE, and the text after the prefix is relative to that key.

See Also

GetPrivateProfileInt, WriteProfileString


GetProfileSection

The GetProfileSection function retrieves all of the keys and values for the specified section of the WIN.INI file. This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

Windows 95:

The specified profile section must not exceed 32K.

Windows NT:

The specified profile section has no size limit.

DWORD GetProfileSection(

LPCTSTR lpAppName,	// address of section name
LPTSTR lpReturnedString,	// address of return buffer
DWORD nSize	// size of return buffer
);
Parameters

lpAppName

Points to a null-terminated string containing the section name in the WIN.INI file.

lpReturnedString

Points to a buffer that receives the keys and values associated with the named section. The buffer is filled with one or more null-terminated strings; the last string is followed by a second null character.

nSize

Specifies the size, in characters, of the buffer pointed to by the lpReturnedString parameter.

Windows 95:

The maximum buffer size is 32,767 characters.

Windows NT:

There is no maximum buffer size.

Return Values

The return value specifies the number of characters copied to the specified buffer, not including the terminating null character. If the buffer is not large enough to contain all the keys and values associated with the named section, the return value is equal to the length specified by nSize minus two.

Remarks

The format of the returned keys and values is one or more null-terminated strings, followed by a final null character. Each string has the following form:

key=string

The GetProfileSection function is not case-sensitive; the strings can be a combination of uppercase and lowercase letters.

This operation is atomic; no updates to the WIN.INI file are allowed while the keys and values for the section are being copied to the buffer.

Windows NT:

Calls to profile functions may be mapped to the registry instead of to the initialization files. This mapping occurs when the initialization file and section are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

When the operation has been mapped, the GetProfileSection function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function’s behavior.

The Win32 Profile functions (Get/WriteProfile*, Get/WritePrivateProfile*) use the following steps to locate initialization information:

1.	Look in the registry for the name of the initialization file, say myfile.ini, under IniFileMapping:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping\myfile.ini

2.	Look for the section name specified by lpAppName. This will be a named value under myfile.ini, or a subkey of myfile.ini, or will not exist.

3.	If the section name specified by lpAppName is a named value under myfile.ini, then that value specifies where in the registry you will find the keys for the section.

4.	If the section name specified by lpAppName is a subkey of myfile.ini, then named values under that subkey specify where in the registry you will find the keys for the section. If the key you are looking for does not exist as a named value, then there will be an unnamed value (shown as "<No Name>") that specifies the default location in the registry where you will find the key.

5.	If the section name specified by lpAppName does not exist as a named value or as a subkey under myfile.ini, then there will be an unnamed value (shown as "<No Name>") under myfile.ini that specifies the default location in the registry where you will find the keys for the section.

6.	If there is no subkey for myfile.ini, or if there is no entry for the section name, then look for the actual myfile.ini on the disk and read its contents.

When looking at values in the registry that specify other registry locations, there are several prefixes that change the behavior of the ini file mapping:

! - this character forces all writes to go both to the registry and to the .INI file on disk.

# - this character causes the registry value to be set to the value in the Windows 3.1 .INI file when a new user logs in for the first time after setup.

@ - this character prevents any reads from going to the .INI file on disk if the requested data is not found in the registry.

USR: - this prefix stands for HKEY_CURRENT_USER, and the text after the prefix is relative to that key.

SYS: - this prefix stands for HKEY_LOCAL_MACHINE\SOFTWARE, and the text after the prefix is relative to that key.

See Also

GetPrivateProfileSection, WriteProfileSection


GetProfileString

The GetProfileString function retrieves the string associated with the specified key in the given section of the WIN.INI file. This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

DWORD GetProfileString(

LPCTSTR lpAppName,	// address of section name
LPCTSTR lpKeyName,	// address of key name
LPCTSTR lpDefault,	// address of default string
LPTSTR lpReturnedString,	// address of destination buffer
DWORD nSize	// size of destination buffer
);
Parameters

lpAppName

Pointer to a null-terminated string that specifies the section containing the key. If this parameter is NULL, the function copies all section names in the file to the supplied buffer.

lpKeyName

Pointer to a null-terminated string containing the key name whose associated string is to be retrieved. If this parameter is NULL, the function copies all keys in the given section to the supplied buffer. Each string is followed by a null character, and the final string is followed by a second null character.

lpDefault

Pointer to a null-terminated default string. If the lpKeyName key cannot be found in the initialization file, GetPrivateProfileString copies the default string to the lpReturnedString buffer. This parameter cannot be NULL.

Avoid specifying a default string with trailing blank characters. The function inserts a null character in the lpReturnedString buffer to strip any trailing blanks.

Windows 95: Although lpDefault is declared as a constant parameter, Windows 95 strips any trailing blanks by inserting a null character into the lpDefault string before copying it to the lpReturnedString buffer.

Windows NT: Windows NT does not modify the lpDefault string. This means that if the default string contains trailing blanks, the lpReturnedString and lpDefault strings will not match when compared using the lstrcmp function.

lpReturnedString

Pointer to a buffer that receives the character string.

nSize

Specifies the size, in characters, of the buffer pointed to by the lpReturnedString parameter.

Return Values

If the function succeeds, the return value is the number of characters copied to the buffer, not including the null-terminating character.

If neither lpAppName nor lpKeyName is NULL and the supplied destination buffer is too small to hold the requested string, the string is truncated and followed by a null character, and the return value is equal to nSize minus one.

If either lpAppName or lpKeyName is NULL and the supplied destination buffer is too small to hold all the strings, the last string is truncated and followed by two null characters. In this case, the return value is equal to nSize minus two.

Remarks

If the string associated with the lpKeyName parameter is enclosed in single or double quotation marks, the marks are discarded when the GetProfileString function returns the string.

The GetProfileString function is not case-sensitive; the strings can contain a combination of uppercase and lowercase letters.

A section in the WIN.INI file must have the following form:

[section]
key=string
      .
      .
      .

An application can use the GetPrivateProfileString function to retrieve a string from a specified initialization file.

The lpDefault parameter must point to a valid string, even if the string is empty (that is, even if its first character is a null character).

Windows NT:

Calls to profile functions may be mapped to the registry instead of to the initialization files. This mapping occurs when the initialization file and section are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

When the operation has been mapped, the GetProfileString function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function’s behavior.

The Win32 Profile functions (Get/WriteProfile*, Get/WritePrivateProfile*) use the following steps to locate initialization information:

1.	Look in the registry for the name of the initialization file, say myfile.ini, under IniFileMapping:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping\myfile.ini

2.	Look for the section name specified by lpAppName. This will be a named value under myfile.ini, or a subkey of myfile.ini, or will not exist.

3.	If the section name specified by lpAppName is a named value under myfile.ini, then that value specifies where in the registry you will find the keys for the section.

4.	If the section name specified by lpAppName is a subkey of myfile.ini, then named values under that subkey specify where in the registry you will find the keys for the section. If the key you are looking for does not exist as a named value, then there will be an unnamed value (shown as "<No Name>") that specifies the default location in the registry where you will find the key.

5.	If the section name specified by lpAppName does not exist as a named value or as a subkey under myfile.ini, then there will be an unnamed value (shown as "<No Name>") under myfile.ini that specifies the default location in the registry where you will find the keys for the section.

6.	If there is no subkey for myfile.ini, or if there is no entry for the section name, then look for the actual myfile.ini on the disk and read its contents.

When looking at values in the registry that specify other registry locations, there are several prefixes that change the behavior of the ini file mapping:

! - this character forces all writes to go both to the registry and to the .INI file on disk.

# - this character causes the registry value to be set to the value in the Windows 3.1 .INI file when a new user logs in for the first time after setup.

@ - this character prevents any reads from going to the .INI file on disk if the requested data is not found in the registry.

USR: - this prefix stands for HKEY_CURRENT_USER, and the text after the prefix is relative to that key.

SYS: - this prefix stands for HKEY_LOCAL_MACHINE\SOFTWARE, and the text after the prefix is relative to that key.

See Also

GetPrivateProfileString, WriteProfileString


GetProp

The GetProp function retrieves a data handle from the property list of the given window. The given character string identifies the handle to be retrieved. The string and handle must have been added to the property list by a previous call to the SetProp function.

HANDLE GetProp(

HWND hWnd,	// handle of window
LPCTSTR lpString	// atom or address of string
);
Parameters

hWnd

Identifies the window whose property list is to be searched.

lpString

Points to a null-terminated character string or contains an atom that identifies a string. If this parameter is an atom, it must have been created by using the GlobalAddAtom function. The atom, a 16-bit value, must be placed in the low-order word of the lpString parameter; the high-order word must be zero.

Return Values

If the property list contains the given string, the return value is the associated data handle. Otherwise, the return value is NULL.

See Also

EnumProps, GlobalAddAtom, RemoveProp, SetProp


GetQueuedCompletionStatus

The GetQueuedCompletionStatus function attempts to dequeue an I/O completion packet from a specified input/output completion port. If there is no completion packet queued, the function waits for a pending input/output operation associated with the completion port to complete. The function returns when it can dequeue a completion packet, or optionally when the function times out. If the function returns because of an I/O operation completion, it sets several variables that provide information about the operation.

BOOL GetQueuedCompletionStatus(

HANDLE CompletionPort,	// the I/O completion port of interest
LPDWORD lpNumberOfBytesTransferred,	// to receive number of bytes transferred during I/O
LPDWORD lpCompletionKey,	// to receive file’s completion key
LPOVERLAPPED *lpOverlapped,	// to receive pointer to OVERLAPPED structure
DWORD dwMilliseconds	// optional timeout value
);
Parameters

CompletionPort

Handle to the input/output completion port of interest. I/O completion ports are created by the CreateIoCompletionPort function.

lpNumberOfBytesTransferred

Points to a variable that the function sets to the number of bytes transferred during an I/O operation that has completed.

lpCompletionKey

Points to a variable that the function sets to the completion key value associated with the file handle whose I/O operation has completed. A completion key is a per-file key that is specified in a call to CreateIoCompletionPort.

lpOverlapped

Points to a variable that the function sets to the address of the OVERLAPPED structure that was specified when the completed input/output operation was started.

The following functions can be used to start input/output operations that complete using I/O completion ports. You must pass the function an OVERLAPPED structure and a file handle associated (by a call to CreateIoCompletionPort) with an I/O completion port to invoke the I/O completion port mechanism:

•	ConnectNamedPipe

•	DeviceIoControl

•	LockFileEx

•	ReadFile

•	TransactNamedPipe

•	WaitCommEvent

•	WriteFile

Even if you have passed the function a file handle associated with a completion port and a valid OVERLAPPED structure, an application can prevent completion port notification. This is done by specifying a valid event handle for the hEvent member of the OVERLAPPED structure, and setting its low-order bit. A valid event handle whose low-order bit is set keeps I/O completion from being queued to the completion port.

dwMilliseconds

Specifies the number of milliseconds that the caller is willing to wait for an completion packet to appear at the I/O completion port. If a completion packet doesn’t appear within the specified time, the function times out, returns FALSE, and sets *lpOverlapped to NULL.

If dwMilliseconds is INFINITE, the function will never time out. If dwMilliseconds is zero and there is no I/O operation to dequeue, the function will time out immediately.

Return Values

If the function dequeues a completion packet for a successful I/O operation from the completion port, the return value is nonzero. The function stores information in the variables pointed to by the lpNumberOfBytesTransferred, lpCompletionKey, and lpOverlapped parameters.

If *lpOverlapped is NULL and the function does not dequeue a completion packet from the completion port, the return value is zero. The function does not store information in the variables pointed to by the lpNumberOfBytesTransferred and lpCompletionKey parameters. To get extended error information, call GetLastError. If the function did not dequeue a completion packet because the wait timed out, the error returned is WAIT_TIMEOUT.

If *lpOverlapped is not NULL and the function dequeues a completion packet for a failed I/O operation from the completion port, the return value is zero. The function stores information in the variables pointed to by lpNumberOfBytesTransferred, lpCompletionKey, and lpOverlapped. To get extended error information, call GetLastError.

Remarks

The I/O system can be instructed to send I/O completion notification packets to input/output completion ports, where they are queued up. The CreateIoCompletionPort function provides a mechanism for this.

When you perform an input/output operation with a file handle that has an associated input/output completion port, the I/O system sends a completion notification packet to the completion port when the I/O operation completes. The I/O completion port places the completion packet in a first-in-first-out queue. The GetQueuedCompletionStatus function retrieves these queued I/O completion packets.

A server application may have several threads calling GetQueuedCompletionStatus for the same completion port. As input operations complete, the operating system queues completion packets to the completion port. If threads are actively waiting in a call to this function, queued requests complete their call.

You can call the PostQueuedCompletionStatus function to post an I/O completion packet to an I/O completion port. The I/O completion packet will satisfy an outstanding call to the GetQueuedCompletionStatus function.

See Also

ConnectNamedPipe, CreateIoCompletionPort, DeviceIoControl, LockFileEx, OVERLAPPED, ReadFile, PostQueuedCompletionStatus, TransactNamedPipe, WaitCommEvent, WriteFile


GetQueueStatus

The GetQueueStatus function returns flags that indicate the type of messages found in the calling thread’s message queue.

DWORD GetQueueStatus(

UINT flags	// queue-status flags
);
Parameters

flags

Specifies queue-status flags giving the types of messages to check for. This parameter can be a combination of the following values:

Value	Meaning
QS_ALLEVENTS	An input, WM_TIMER, WM_PAINT, WM_HOTKEY, or posted message is in the queue.
QS_ALLINPUT	Any message is in the queue.
QS_HOTKEY	A WM_HOTKEY message is in the queue.
QS_INPUT	An input message is in the queue.
QS_KEY	A WM_KEYUP, WM_KEYDOWN, WM_SYSKEYUP, or WM_SYSKEYDOWN message is in the queue.
QS_MOUSE	A WM_MOUSEMOVE message or mouse-button message (WM_LBUTTONUP, WM_RBUTTONDOWN, and so on).
QS_MOUSEBUTTON	A mouse-button message (WM_LBUTTONUP, WM_RBUTTONDOWN, and so on).
QS_MOUSEMOVE	A WM_MOUSEMOVE message is in the queue.
QS_PAINT	A WM_PAINT message is in the queue.
QS_POSTMESSAGE	A posted message (other than those just listed) is in the queue.
QS_SENDMESSAGE	A message sent by another thread or application is in the queue.
QS_TIMER	A WM_TIMER message is in the queue.
Return Values

The high-order word of the return value indicates the types of messages currently in the queue. The low-order word indicates the types of messages that have been added to the queue and that are still in the queue since the last call to the GetQueueStatus, GetMessage, or PeekMessage function.

Remarks

The presence of a QS_ flag in the return value does not guarantee that a subsequent call to the PeekMessage or GetMessage function will return a message. GetMessage and PeekMessage perform some internal filtering that may cause the message to be processed internally. For this reason, the return value from GetQueueStatus should be considered only a hint as to whether GetMessage or PeekMessage should be called.

See Also

GetInputState, GetMessage, PeekMessage


GetRasterizerCaps

The GetRasterizerCaps function returns flags indicating whether TrueType fonts are installed in the system.

BOOL GetRasterizerCaps(

LPRASTERIZER_STATUS lprs,	// address of rasterizer information structure
UINT cb	// number of bytes in structure
);
Parameters

lprs

Points to a RASTERIZER_STATUS structure to receive information about the rasterizer.

cb

Specifies the number of bytes to be copied into the structure pointed to by the lprs parameter.

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.

Remarks

The GetRasterizerCaps function enables applications and printer drivers to determine whether TrueType fonts are installed.

If the TT_AVAILABLE flag is set in the wFlags member of the RASTERIZER_STATUS structure, at least one TrueType font is installed. If the TT_ENABLED flag is set, TrueType is enabled for the system.

The actual number of bytes copied is either the member specified in the cb parameter or the length of the RASTERIZER_STATUS structure, whichever is less.

See Also

GetOutlineTextMetrics, RASTERIZER_STATUS


GetRegionData

The GetRegionData function fills the specified buffer with data describing a region. This data includes the dimensions of the rectangles that make up the region.

DWORD GetRegionData(

HRGN hRgn,	// handle of region
DWORD dwCount,	// size of buffer containing region data
LPRGNDATA lpRgnData	// address of buffer containing region data
);
Parameters

hRgn

Identifies the region.

dwCount

Specifies the size, in bytes, of the lpRgnData buffer.

lpRgnData

Points to a RGNDATA structure that receives the information. If this parameter is NULL, the return value contains the number of bytes needed for the region data.

Return Values

If the function succeeds and dwCount specifies an adequate number of bytes, the return value is 1. If dwCount is too small or lpRgnData is NULL, the return value is the required number of bytes.

If the function fails, the return value is zero.

Remarks

The GetRegionData function is used in conjunction with the ExtCreateRegion function.

See Also

ExtCreateRegion, RGNDATA


GetRgnBox

The GetRgnBox function retrieves the bounding rectangle of the specified region.

int GetRgnBox(

HRGN hrgn,	// handle of a region
LPRECT lprc	// address of structure that receives bounding rect.
);
Parameters

hrgn

Identifies the region.

lprc

Points to a RECT structure that receives the bounding rectangle.

Return Values

The return value specifies the region’s complexity. It can be one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than a single rectangle.
If the hrgn parameter does not identify a valid region, the return value is zero.

See Also

RECT


GetROP2

The GetROP2 function retrieves the foreground mix mode of the specified device context. The mix mode specifies how the pen or interior color and the color already on the screen are combined to yield a new color.

int GetROP2(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Values

If the function succeeds, the return value specifies the foreground mix mode.

If the function fails, the return value is zero.

Remarks

Following are the foreground mix modes:

Mix mode	Description
R2_BLACK	Pixel is always 0.
R2_COPYPEN	Pixel is the pen color.
R2_MASKNOTPEN	Pixel is a combination of the colors common to both the screen and the inverse of the pen.
R2_MASKPEN	Pixel is a combination of the colors common to both the pen and the screen.
R2_MASKPENNOT	Pixel is a combination of the colors common to both the pen and the inverse of the screen.
R2_MERGENOTPEN	Pixel is a combination of the screen color and the inverse of the pen color.
R2_MERGEPEN	Pixel is a combination of the pen color and the screen color.
R2_MERGEPENNOT	Pixel is a combination of the pen color and the inverse of the screen color.
R2_NOP	Pixel remains unchanged.
R2_NOT	Pixel is the inverse of the screen color.
R2_NOTCOPYPEN	Pixel is the inverse of the pen color.
R2_NOTMASKPEN	Pixel is the inverse of the R2_MASKPEN color.
R2_NOTMERGEPEN	Pixel is the inverse of the R2_MERGEPEN color.
R2_NOTXORPEN	Pixel is the inverse of the R2_XORPEN color.
R2_WHITE	Pixel is always 1.
R2_XORPEN	Pixel is a combination of the colors in the pen and in the screen, but not in both.
See Also

SetROP2


GetSaveFileName

The GetSaveFileName function creates a Save common dialog box that lets the user specify the drive, directory, and name of a file to save.

BOOL GetSaveFileName(

LPOPENFILENAME lpofn	// address of structure with initialization data
);
Parameters

lpofn

Pointer to an OPENFILENAME structure that contains information used to initialize the dialog box. When GetSaveFileName returns, this structure contains information about the user’s file selection.

Return Values

If the user specifies a filename and clicks the OK button, the return value is nonzero. The buffer pointed to by the lpstrFile member of the OPENFILENAME structure contains the full path and filename specified by the user.

If the user cancels or closes the Save dialog box or an error occurs, the return value is zero. To get extended error information, call the CommDlgExtendedError function, which can return one of the following values:

CDERR_FINDRESFAILURE	CDERR_NOHINSTANCE
CDERR_INITIALIZATION	CDERR_NOHOOK
CDERR_LOCKRESFAILURE	CDERR_NOTEMPLATE
CDERR_LOADRESFAILURE	CDERR_STRUCTSIZE
CDERR_LOADSTRFAILURE	FNERR_BUFFERTOOSMALL
CDERR_MEMALLOCFAILURE	FNERR_INVALIDFILENAME
CDERR_MEMLOCKFAILURE	FNERR_SUBCLASSFAILURE
Remarks

By default, Windows 95 and Windows NT version 4.0 display a new version of the Save dialog box that provides user-interface features that are similar to the Windows Explorer. You can provide an OFNHookProc hook procedure for an Explorer-style Save dialog box. To enable the hook procedure, set the OFN_EXPLORER and OFN_ENABLEHOOK flags in the Flags member of the OPENFILENAME structure and specify the address of the hook procedure in the lpfnHook member.

Windows 95 and Windows NT 4.0 continue to support the old-style Save dialog box for applications that want to maintain a user-interface consistent with the Windows 3.1 or Windows NT 3.51 user-interface. To display the old-style Save dialog box, enable an OFNHookProcOldStyle hook procedure and ensure that the OFN_EXPLORER flag is not set.

See Also

CommDlgExtendedError, GetOpenFilename, OFNHookProc, OFNHookProcOldStyle, OPENFILENAME


GetScrollInfo

The GetScrollInfo function retrieves the parameters of a scroll bar, including the minimum and maximum scrolling positions, the page size, and the position of the scroll box (thumb).

BOOL GetScrollInfo(

HWND hwnd,	// handle of window with scroll bar
int fnBar,	// scroll bar flag
LPSCROLLINFO lpsi	// pointer to structure for scroll parameters
);
Parameters

hwnd

Identifies a scroll bar control or a window with a standard scroll bar, depending on the value of the fnBar parameter.

fnBar

Specifies the type of scroll bar for which to retrieve parameters. This parameter can be one of the following values:

Value	Meaning
SB_CTL	Retrieves the parameters for a scroll bar control. The hwnd parameter must be the handle of the scroll bar control.
SB_HORZ	Retrieves the parameters for the given window's standard horizontal scroll bar.
SB_VERT	Retrieves the parameters for the given window's standard vertical scroll bar.
lpsi

Points to a SCROLLINFO structure whose fMask member, upon entry to the function, specifies the scroll bar parameters to retrieve. Before returning, the function copies the specified parameters to the appropriate members of the structure.

The fMask member can be a combination of the following values:

Value	Meaning
SIF_PAGE	Copies the scroll page to the nPage member of the SCROLLINFO structure pointed to by lpsi.
SIF_POS	Copies the scroll position to the nPos member of the SCROLLINFO structure pointed to by lpsi.
SIF_RANGE	Copies the scroll range to the nMin and nMax members of the SCROLLINFO structure pointed to by lpsi.
Return Values

If the function retrieved any values, the return value is nonzero.

If the function does not retrieve any values, the return value is zero.

Remarks

The GetScrollInfo function enables applications to use 32-bit scroll positions. Although the messages that indicate scroll-bar position, WM_HSCROLL and WM_VSCROLL, provide only 16 bits of position data, the functions SetScrollInfo and GetScrollInfo provide 32 bits of scroll-bar position data. Thus, an application can call GetScrollInfo while processing either the WM_HSCROLL or WM_VSCROLL messages to obtain 32-bit scroll-bar position data.

The limitation on this technique applies to real-time scrolling of a window’s contents. An application implements real-time scrolling by processing the WM_HSCROLL or WM_VSCROLL messages that carry the SB_THUMBTRACK notification value, thereby tracking the position of the scroll box (thumb) as the user moves it. Unfortunately, there is no function to retrieve the 32-bit position scroll-box position as the user moves the scroll box. Because GetScrollInfo provides only the static position, an application can obtain only 32-bit position data before or after a scroll operation.

See Also

SCROLLINFO, SetScrollInfo, WM_HSCROLL, WM_VSCROLL


GetScrollPos

The GetScrollPos function retrieves the current position of the scroll box (thumb) in the specified scroll bar. The current position is a relative value that depends on the current scrolling range. For example, if the scrolling range is 0 through 100 and the scroll box is in the middle of the bar, the current position is 50.

int GetScrollPos(

HWND hWnd,	// handle of window with scroll bar
int nBar	// scroll bar flags
);
Parameters

hWnd

Identifies a scroll bar control or a window with a standard scroll bar, depending on the value of the nBar parameter.

nBar

Specifies the scroll bar to be examined. This parameter can be one of the following values:

Value	Meaning
SB_CTL	Retrieves the position of the scroll box in a scroll bar control. The hWnd parameter must be the handle of the scroll bar control.
SB_HORZ	Retrieves the position of the scroll box in a window’s standard horizontal scroll bar.
SB_VERT	Retrieves the position of the scroll box in a window’s standard vertical scroll bar.
Return Values

If the function succeeds, the return value is the current position of the scroll box/

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The GetScrollPos function enables applications to use 32-bit scroll positions. Although the messages that indicate scroll bar position, WM_HSCROLL and WM_VSCROLL, are limited to 16 bits of position data, the functions SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange support 32-bit scroll bar position data. Thus, an application can call GetScrollPos while processing either the WM_HSCROLL or WM_VSCROLL messages to obtain 32-bit scroll bar position data.

The limitation on this technique applies to real-time scrolling of a window’s content. An application implements such scrolling by processing the WM_HSCROLL or WM_VSCROLL messages that carry the SB_THUMBTRACK notification message, thereby tracking the position of the scroll box, also known as the thumb, while the user moves it. Unfortunately, there is no function to retrieve the thumb’s 32-bit position while the user moves it. GetScrollPos provides static position data only; an application can therefore only obtain 32-bit position data before or after a scroll has taken place.

See Also

GetScrollRange, ScrollDC, ScrollWindow, SetScrollPos, SetScrollRange, WM_HSCROLL, WM_VSCROLL


GetScrollRange

The GetScrollRange function retrieves the current minimum and maximum scroll box (thumb) positions for the specified scroll bar.

For Windows 95, the GetScrollRange function exists for compatibility with operating system versions earlier than 4.0. With version 4.0 or later, use the GetScrollInfo function.

BOOL GetScrollRange(

HWND hWnd,	// handle of window with scroll bar
int nBar,	// scroll bar flags
LPINT lpMinPos,	// address of variable that receives minimum position
LPINT lpMaxPos	// address of variable that receives maximum position
);
Parameters

hWnd

Identifies a scroll bar control or a window with a standard scroll bar, depending on the value of the nBar parameter.

nBar

Specifies the scroll bar from which the positions are retrieved. This parameter can be one of the following values:

Value	Meaning
SB_CTL	Retrieves the positions of a scroll bar control. The hWnd parameter must be the handle of the scroll bar control.
SB_HORZ	Retrieves the positions of the window’s standard horizontal scroll bar.
SB_VERT	Retrieves the positions of the window’s standard vertical scroll bar.
lpMinPos

Points to the integer variable that receives the minimum position.

lpMaxPos

Points to the integer variable that receives the maximum position.

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.

Remarks

If the specified window does not have standard scroll bars or is not a scroll bar control, the GetScrollRange function copies zero to the lpMinPos and lpMaxPos parameters.

The default range for a standard scroll bar is 0 through 100. The default range for a scroll bar control is empty (both values are zero).

The messages that indicate scroll bar position, WM_HSCROLL and WM_VSCROLL, are limited to 16 bits of position data. However, because SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier for the WM_HSCROLL and WM_VSCROLL messages. See the GetScrollPos function for a description of the technique and its limits.

See Also

GetScrollPos, SetScrollPos, SetScrollRange, WM_HSCROLL, WM_VSCROLL


GetSecurityDescriptorControl

The GetSecurityDescriptorControl function retrieves a security descriptor’s control and revision information.

BOOL GetSecurityDescriptorControl(

PSECURITY_DESCRIPTOR pSecurityDescriptor,	// address of security descriptor
PSECURITY_DESCRIPTOR_CONTROL pControl,	// address of  control structure
LPDWORD lpdwRevision	// address of revision value
);
Parameters

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure whose control and revision information the function retrieves.

pControl

Points to a SECURITY_DESCRIPTOR_CONTROL structure receiving the security descriptor’s control information.

lpdwRevision

Points to a variable receiving the security descriptor’s revision value. This value is always set, even when GetSecurityDescriptorControl returns an error.

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.

See Also

GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL


GetSecurityDescriptorDacl

The GetSecurityDescriptorDacl function retrieves a pointer to the discretionary access-control list (ACL) in a specified security descriptor.

BOOL GetSecurityDescriptorDacl(

PSECURITY_DESCRIPTOR pSecurityDescriptor,	// address of security descriptor
LPBOOL lpbDaclPresent,	// address of flag for presence of disc. ACL
PACL *pDacl,	// address of pointer to ACL
LPBOOL lpbDaclDefaulted	// address of flag for default disc. ACL
);
Parameters

pSecurityDescriptor

Points to the SECURITY_DESCRIPTOR structure containing the discretionary ACL. The function retrieves a pointer to it.

lpbDaclPresent

Points to a flag the function sets to indicate the presence of a discretionary ACL in the specified security descriptor. If this parameter is TRUE, the security descriptor contains a discretionary ACL, and the remaining output parameters in this function receive valid values. If this parameter is FALSE, the security descriptor does not contain a discretionary ACL, and the remaining output parameters do not receive valid values.

pDacl

Points to a pointer to an ACL structure. If a discretionary ACL exists, the function sets the pointer pointed to by pDacl to the address of the security descriptor’s discretionary ACL. If a discretionary ACL does not exist, no value is stored.

If the function stores a NULL value in the pointer pointed to by pDacl, the security descriptor has a NULL discretionary ACL. A NULL discretionary ACL implicitly allows all access to an object.

lpbDaclDefaulted

Points to a flag set to the value of the SE_DACL_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure if a discretionary ACL exists for the security descriptor. If this flag is TRUE, the discretionary ACL was retrieved by a default mechanism; if FALSE, the discretionary ACL was explicitly specified by a user.

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.

See Also

ACL, GetSecurityDescriptorControl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorDacl


GetSecurityDescriptorGroup

The GetSecurityDescriptorGroup function retrieves the primary group information from a security descriptor.

BOOL GetSecurityDescriptorGroup(

PSECURITY_DESCRIPTOR pSecurityDescriptor,	// address of security descriptor
PSID *pGroup,	// address of pointer to group security identifier (SID)
LPBOOL lpbGroupDefaulted	// address of flag for default
);
Parameters

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure whose primary group information the function retrieves.

pGroup

Points to a pointer to a SID structure identifying the primary group when the function returns. (A SID is a security identifier.) If the security descriptor does not contain a primary group, the function sets the pointer pointed to by pGroup to NULL and ignores the remaining output parameter, lpbGroupDefaulted. If the security descriptor contains a primary group, the function sets the pointer pointed to by pGroup to the address of the security descriptor’s group SID structure and provides a valid value for the variable pointed to by lpbGroupDefaulted.

lpbGroupDefaulted

Points to a flag set to the value of the SE_GROUP_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure when the function returns. If the value stored in the variable pointed to by the pGroup parameter is NULL, no value is set.

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.

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorGroup, SID


GetSecurityDescriptorLength

The GetSecurityDescriptorLength function returns the length, in bytes, of a structurally valid SECURITY_DESCRIPTOR structure. The length includes the length of all associated structures, such as SID and ACL structures.

DWORD GetSecurityDescriptorLength(

PSECURITY_DESCRIPTOR pSecurityDescriptor	// address of security descriptor
);
Parameters

pSecurityDescriptor

Points to the SECURITY_DESCRIPTOR structure whose length the function returns. The SECURITY_DESCRIPTOR structure is assumed to be valid.

Return Values

If the function succeeds, the return value is the length, in bytes, of the SECURITY_DESCRIPTOR structure. If the SECURITY_DESCRIPTOR structure is invalid, the return value is undefined.

Remarks

The minimum length of a security descriptor is SECURITY_DESCRIPTOR_MIN_LENGTH. A security descriptor of this length has no associated SID or ACL structures.

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR


GetSecurityDescriptorOwner

The GetSecurityDescriptorOwner function retrieves the owner information from a security descriptor.

BOOL GetSecurityDescriptorOwner(

PSECURITY_DESCRIPTOR pSecurityDescriptor,	// address of security descriptor
PSID *pOwner,	// address of pointer to owner security identifier (SID)
LPBOOL lpbOwnerDefaulted	// address of flag for default
);
Parameters

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure whose owner information the function retrieves.

pOwner

Points to a pointer to a SID structure identifying the owner when the function returns. (A SID is a security identifier.) If the security descriptor does not contain an owner, the function sets the pointer pointed to by pOwner to NULL and ignores the remaining output parameter, lpbOwnerDefaulted. If the security descriptor contains an owner, the function sets the pointer pointed to by pOwner to the address of the security descriptor’s owner SID structure and provides a valid value for the variable pointed to by lpbOwnerDefaulted.

lpbOwnerDefaulted

Points to a flag set to the value of the SE_OWNER_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure when the function returns. If the value stored in the variable pointed to by the pOwner parameter is NULL, no value is set.

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.

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorSacl, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorOwner, SID


GetSecurityDescriptorSacl

The GetSecurityDescriptorSacl function retrieves a pointer to the system access-control list (ACL) in a specified security descriptor.

BOOL GetSecurityDescriptorSacl(

PSECURITY_DESCRIPTOR pSecurityDescriptor,	// address of security descriptor
LPBOOL lpbSaclPresent,	// address of flag for presence of system ACL
PACL *pSacl,	// address of pointer to ACL
LPBOOL lpbSaclDefaulted	// address of flag for default system ACL
);
Parameters

pSecurityDescriptor

Points to the SECURITY_DESCRIPTOR structure containing the system ACL to which the function retrieves a pointer to.

lpbSaclPresent

Points to a flag the function sets to indicate the presence of a system ACL in the specified security descriptor. If this parameter is TRUE, the security descriptor contains a system ACL, and the remaining output parameters in this function receive valid values. If this parameter is FALSE, the security descriptor does not contain a system ACL, and the remaining output parameters do not receive valid values.

pSacl

Points to a pointer to an ACL structure. If a system ACL exists, the function sets the pointer pointed to by pSacl to the address of the security descriptor’s system ACL. If a system ACL does not exist, no value is stored.

If the function stores a NULL value in the pointer pointed to by pSacl, the security descriptor has a NULL system ACL.

lpbSaclDefaulted

Points to a flag set to the value of the SE_SACL_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure if a system ACL exists for the security descriptor.

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.

See Also

ACL, GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorSacl


GetSecurityInfo [New - Windows NT]
GetSecurityInfo

[New - Windows NT]

The GetSecurityInfo function retrieves a copy of the security descriptor for an object specified by a handle.

DWORD GetSecurityInfo(

HANDLE handle,	// handle to the object
SE_OBJECT_TYPE ObjectType,	// type of object
SECURITY_INFORMATION SecurityInfo,	// type of security information to retrieve
PSID *ppsidOwner,	// receives a pointer to the owner SID
PSID *ppsidGroup,	// receives a pointer to the primary group SID
PACL *ppDacl,	// receives a pointer to the DACL
PACL *ppSacl,	// receives a pointer to the SACL
PSECURITY_DESCRIPTOR *ppSecurityDescriptor	// receives a pointer to the security descriptor
);
Parameters

handle

A handle to the object from which to retrieve security information.

ObjectType

Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName parameter.

SecurityInfo

A set of SECURITY_INFORMATION bit flags that indicate the type of security information to retrieve. This parameter can be a combination of the following values.

Value	Meaning
OWNER_SECURITY_INFORMATION	If this flag is set, the ppsidOwner parameter receives the security identifier (SID) of the object’s owner.
GROUP_SECURITY_INFORMATION	If this flag is set, the ppsidGroup parameter receives the SID of the object’s primary group.
DACL_SECURITY_INFORMATION	If this flag is set, the ppDacl parameter receives the object’s discretionary access-control list (DACL).
SACL_SECURITY_INFORMATION	If this flag is set, the ppSacl parameter receives the object’s system access-control list (SACL)..
ppsidOwner

Pointer to a variable that receives a pointer to the owner SID in the security descriptor returned in ppSecurityDescriptor. The returned pointer is valid only if you set the OWNER_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the owner SID.

ppsidGroup

Pointer to a variable that receives a pointer to the primary group SID in the returned security descriptor. The returned pointer is valid only if you set the GROUP_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the group SID.

ppDacl

Pointer to a variable that receives a pointer to the DACL in the returned security descriptor. The returned pointer is valid only if you set the DACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the DACL.

ppSacl

Pointer to a variable that receives a pointer to the SACL in the returned security descriptor. The returned pointer is valid only if you set the SACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the SACL.

ppSecurityDescriptor

Pointer to a variable that receives a pointer to the security descriptor of the object. You must call the LocalFree function to free the returned buffer.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

If the ppsidOwner, ppsidGroup, ppDacl, ppSacl parameters are non-NULL, and the SecurityInfo parameter specifies that they be retrieved from the object, those parameters will point to the corresponding parameters in the security descriptor returned in ppSecurityDescriptor.

To read the object’s owner, group and DACL the caller must have READ_CONTROL access or be the owner of the object. The caller must have the SE_SECURITY_NAME privilege enabled to read the S ACL.

See Also

ACL, GetNamedSecurityInfo, LocalFree, SE_OBJECT_TYPE, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetNamedSecurityInfo, SetSecurityInfo, SID


GetServiceDisplayName

The GetServiceDisplayName function obtains the display name that is associated with a particular service name. The service name is the same as the service’s registry key name.

BOOL GetServiceDisplayName(

SC_HANDLE hSCManager,	// handle to a service control manager database
LPCTSTR lpServiceName,	// the service name
LPTSTR lpDisplayName,	// buffer to receive the service’s display name
LPDWORD lpcchBuffer	// size of display name buffer and display name
);
Parameters

hSCManager

Handle to a machine’s service control manager database. This parameter is an RPC server handle as returned by the OpenSCManager function.

lpServiceName

Points to a null-terminated service name string. This name is the same as the service’s registry key name.

lpDisplayName

Points to a buffer into which the function stores the service’s display name as a null-terminated string. If the function fails, this buffer will contain an empty string.

lpcchBuffer

Points to a DWORD that contains the size, in characters, of the buffer pointed to by lpDisplayName. When the function returns, this DWORD contains the size, in characters, of the service’s display name, excluding the NULL terminator.

If the buffer pointed to by lpDisplayName is too small to contain the display name, the function stores no data into it. When the function returns, the DWORD pointed to by lpcchBuffer contains the size in characters of the service’s display name, excluding the NULL terminator.

Return Values

If the functions succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

There are two names for a service: the service name, which is the actual name of the service’s key in the registry’s Services section, and a more user-friendly display name that appears in the Services Control Panel application and is used with the NET START command. The GetServiceDisplayName and GetServiceKeyName functions let an application map one of these names to the other. An application passes a service’s registry key name to GetServiceDisplayName, and obtains the service’s user-friendly display name. An application passes a service’s display name to GetServiceKeyName, and obtains the service’s registry key name.

See Also

GetServiceKeyName, OpenSCManager


GetServiceKeyName

The GetServiceKeyName function obtains the service name that is associated with a particular service’s display name. The service name is the same as the service’s registry key name.

BOOL GetServiceKeyName(

SC_HANDLE hSCManager,	// handle to a service control manager database
LPCTSTR lpDisplayName,	// the service’s display name
LPTSTR lpServiceName,	// buffer to receive the service name
LPDWORD lpcchBuffer	// size of service name buffer and service name
);
Parameters

hSCManager

Handle to a computer’s service control manager database. This parameter is a remote procedure call (RPC) server handle as returned by OpenSCManager.

lpDisplayName

Points to a null-terminated service display name string.

lpServiceName

Points to a buffer into which the function stores the service name as a null-terminated string. If the function fails, this buffer will contain an empty string.

lpcchBuffer

Points to a DWORD that contains the size in characters of the buffer pointed to by the lpServiceName parameter. When the function returns, this DWORD contains the size, in characters, of the service name, excluding the NULL terminator.

If the buffer pointed to by lpServiceName is too small to contain the service name, the function stores no data in it. When the function returns, the DWORD pointed to by lpcchBuffer contains the size, in characters, of the service name, excluding the NULL terminator.

Return Values

If the functions succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

There are two names for a service: the service name, which is the actual name of the service’s key in the registry’s Services section, and a more user-friendly display name that appears in the Services Control Panel application and is used with the NET START command. The GetServiceDisplayName and GetServiceKeyName functions let an application map one of these names to the other. An application passes a service’s registry key name to GetServiceDisplayName, and obtains the service’s user-friendly display name. An application passes a service’s display name to GetServiceKeyName, and obtains the service’s registry key name.

See Also

GetServiceDisplayName, OpenSCManager


GetShortPathName

The GetShortPathName function obtains the short path form of a specified input path.

DWORD GetShortPathName(

LPCTSTR lpszLongPath,	// points to a null-terminated path string
LPTSTR lpszShortPath,	// points to a buffer to receive the null-terminated short form of the path
DWORD cchBuffer	// specifies the size of the buffer pointed to by lpszShortPath
);
Parameters

lpszLongPath

Points to a null-terminated path string. The function obtains the short form of this path.

lpszShortPath

Points to a buffer to receive the null-terminated short form of the path specified by lpszLongPath.

cchBuffer

Specifies the size, in characters, of the buffer pointed to by lpszShortPath.

Return Values

If the function succeeds, the return value is the length, in characters, of the string copied to lpszShortPath, not including the terminating null character.

If the function fails due to the lpszShortPath buffer being too small to contain the short path string, the return value is the size, in characters, of the short path string. You need to call the function with a short path buffer that is at least as large as the short path string.

If the function fails for any other reason, the return value is zero. To get extended error information, call GetLastError.

Remarks

When an application calls this function and specifies a path on a volume that does not support 8.3 aliases, the function fails with ERROR_INVALID_PARAMETER if the path is longer than 67 bytes.

The path specified by lpszLongPath does not have to be a fully qualified path or a long path. The short form may be longer than the specifed path.

If the specified path is already in its short form, there is no need for any conversion, and the function simply copies the specified path to the buffer for the short path.

You can set lpszShortPath to the same value as lpszLongPath; in other words, you can set the buffer for the short path to the address of the input path string.

You can obtain the long name of a file from the short name by calling the FindFirstFile function.

See Also

GetFullPathName, FindFirstFile


GetSidIdentifierAuthority

The GetSidIdentifierAuthority function returns the address of the SID_IDENTIFIER_AUTHORITY structure in a specified security identifier (SID).

PSID_IDENTIFIER_AUTHORITY GetSidIdentifierAuthority(

PSID pSid	// address of SID to query
);
Parameters

pSid

Points to the SID structure for which the address of the SID_IDENTIFIER_AUTHORITY structure is returned.

Return Values

If the function succeeds, the return value is the address of the SID_IDENTIFIER_AUTHORITY structure for the specified SID structure.

If the function fails, the return value is undefined. The function fails if the SID structure pointed to by the pSid parameter is invalid. To get extended error information, call GetLastError.

See Also

GetLengthSid, GetSidLengthRequired, GetSidSubAuthority, GetSidSubAuthorityCount, IsValidSid, SID, SID_IDENTIFIER_AUTHORITY


GetSidLengthRequired

The GetSidLengthRequired function returns the length, in bytes, of the buffer required to store a SID structure with a specified number of subauthorities.

DWORD GetSidLengthRequired(

UCHAR nSubAuthorityCount	// count of subauthorities
);
Parameters

nSubAuthorityCount

Specifies the number of subauthorities to be stored in the SID structure.

Return Values

The return value is the length, in bytes, of the buffer required to store the SID structure. This function cannot fail.

See Also

AllocateAndInitializeSid, GetLengthSid, GetSidIdentifierAuthority, GetSidSubAuthority, GetSidSubAuthorityCount, InitializeSid, IsValidSid, SID


GetSidSubAuthority

The GetSidSubAuthority function returns the address of a specified subauthority in a SID structure. The subauthority value is a relative identifier (RID). A SID is a security identifier.

PDWORD GetSidSubAuthority(

PSID pSid,	// address of security identifier to query
DWORD nSubAuthority	// index of subauthority to retrieve
);
Parameters

pSid

Points to the SID structure from which the address of a subauthority is to be returned.

nSubAuthority

Specifies an index value identifying the subauthority array element whose address the function will return. The function performs no validation tests on this value. An application can call the GetSidSubAuthorityCount function to discover the range of acceptable values.

Return Values

If the function succeeds, the return value is the address of the specified SID subauthority. To get extended error information, call GetLastError.

If the function fails, the return value is undefined. The function fails if the specified SID structure is invalid or if the index value specified by the nSubAuthority parameter is out of bounds.

See Also

GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthorityCount, IsValidSid, SID


GetSidSubAuthorityCount

The GetSidSubAuthorityCount function returns the address of the field in a SID structure containing the subauthority count. A SID is a security identifier.

PUCHAR GetSidSubAuthorityCount(

PSID pSid	// address of security identifier to query
);
Parameters

pSid

Points to the SID structure from which a pointer to the subauthority count is returned.

Return Values

If the function succeeds, the return value is a pointer to the subauthority count for the specified SID structure.

If the function fails, the return value is undefined. The function fails if the specified SID structure is invalid. To get extended error information, call GetLastError.

See Also

GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthority, IsValidSid, SID


GetStartupInfo

The GetStartupInfo function retrieves the contents of the STARTUPINFO structure that was specified when the calling process was created.

VOID GetStartupInfo(

LPSTARTUPINFO lpStartupInfo	// address of STARTUPINFO structure
);
Parameters

lpStartupInfo

Points to a STARTUPINFO structure that is filled in by the function.

Return Values

This function does not return a value.

Remarks

The STARTUPINFO structure was specified by the process that created the calling process. It can be used to specify properties associated with the main window of the calling process.

See Also

CreateProcess, STARTUPINFO


GetStdHandle

The GetStdHandle function returns a handle for the standard input, standard output, or standard error device.

HANDLE GetStdHandle(

DWORD nStdHandle	// input, output, or error device
);
Parameters

nStdHandle

Specifies the device for which to return the handle. This parameter can have one of the following values:

Value	Meaning
STD_INPUT_HANDLE	Standard input handle
STD_OUTPUT_HANDLE	Standard output handle
STD_ERROR_HANDLE	Standard error handle
Return Values

If the function succeeds, the return value is a handle of the specified device.

If the function fails, the return value is the INVALID_HANDLE_VALUE flag. To get extended error information, call GetLastError.

Remarks

Handles returned by GetStdHandle can be used by applications that need to read from or write to the console. When a console is created, the standard input handle is a handle of the console’s input buffer, and the standard output and standard error handles are handles of the console’s active screen buffer. These handles can be used by the ReadFile and WriteFile functions, or by any of the console functions that access the console input buffer or a screen buffer (for example, the ReadConsoleInput, WriteConsole, or GetConsoleScreenBufferInfo functions).

All handles returned by this function have GENERIC_READ and GENERIC_WRITE access unless the SetStdHandle function has been used to set a standard handle to be some handle with a lesser access.

The standard handles of a process may be redirected by a call to SetStdHandle, in which case GetStdHandle returns the redirected handle. If the standard handles have been redirected, you can specify the CONIN$ value in a call to the CreateFile function to get a handle of a console’s input buffer. Similarly, you can specify the CONOUT$ value to get a handle of a console’s active screen buffer.

See Also

CreateFile, GetConsoleScreenBufferInfo, ReadConsoleInput, ReadFile, SetStdHandle, WriteConsole, WriteFile


GetStockObject

The GetStockObject function retrieves a handle to one of the predefined stock pens, brushes, fonts, or palettes.

HGDIOBJ GetStockObject(

int fnObject	// type of stock object
);
Parameters

fnObject

Specifies the type of stock object. This parameter can be any one of the following values:

Value	Meaning
BLACK_BRUSH	Black brush.
DKGRAY_BRUSH	Dark gray brush.
GRAY_BRUSH	Gray brush.
HOLLOW_BRUSH	Hollow brush (equivalent to NULL_BRUSH).
LTGRAY_BRUSH	Light gray brush.
NULL_BRUSH	Null brush (equivalent to HOLLOW_BRUSH).
WHITE_BRUSH	White brush.
BLACK_PEN	Black pen.
NULL_PEN	Null pen.
WHITE_PEN	White pen.
ANSI_FIXED_FONT	Windows fixed-pitch (monospace) system font.
ANSI_VAR_FONT	Windows variable-pitch (proportional space) system font.
DEVICE_DEFAULT_FONT	Windows NT only: Device-dependent font.
DEFAULT_GUI_FONT	Windows 95 only: Default font for user interface objects such as menus and dialog boxes.
OEM_FIXED_FONT	Original equipment manufacturer (OEM) dependent fixed-pitch (monospace) font.
SYSTEM_FONT	System font. By default, Windows uses the system font to draw menus, dialog box controls, and text. In Windows versions 3.0 and later, the system font is a proportionally spaced font; earlier versions of Windows used a monospace system font.
SYSTEM_FIXED_FONT	Fixed-pitch (monospace) system font used in Windows versions earlier than 3.0. This stock object is provided for compatibility with earlier versions of Windows.
DEFAULT_PALETTE	Default palette. This palette consists of the static colors in the system palette.
Return Values

If the function succeeds, the return value identifies the logical object requested.

If the function fails, the return value is NULL.

Remarks

Use the DKGRAY_BRUSH, GRAY_BRUSH, and LTGRAY_BRUSH stock objects only in windows with the CS_HREDRAW and CS_VREDRAW styles. Using a gray stock brush in any other style of window can lead to misalignment of brush patterns after a window is moved or sized. The origins of stock brushes cannot be adjusted.

The HOLLOW_BRUSH and NULL_BRUSH stock objects are equivalent.

The font used by the DEFAULT_GUI_FONT stock object could change. Use this stock object when you want to use the font that menus, dialog boxes, and other user interface objects use.

It is not necessary (but it is not harmful) to delete stock objects by calling DeleteObject.

See Also

DeleteObject, SelectObject


GetStretchBltMode

The GetStretchBltMode function retrieves the current stretching mode. The stretching mode defines how color data is added to or removed from bitmaps that are stretched or compressed when the StretchBlt function is called.

int GetStretchBltMode(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Values

If the function succeeds, the return value is the current stretching mode.

If the function fails, the return value is zero.

See Also

SetStretchBltMode, StretchBlt


GetStringTypeA

The GetStringTypeA function returns character-type information for the characters in the specified source string. For each character in the string, the function sets one or more bits in the corresponding 16-bit element of the output array. Each bit identifies a given character type, such as whether the character is a letter, a digit, or neither.

BOOL GetStringTypeA(

LCID Locale,	// locale identifer
DWORD dwInfoType,	// information-type options
LPCSTR lpSrcStr,	// pointer to the source string
int cchSrc,	// size, in bytes, of the source string
LPWORD lpCharType	// pointer to the buffer for output
);
Parameters

Locale

Specifies the locale identifier. This value uniquely defines the ANSI code page to use to translate the string pointed to by lpSrcStr from ANSI to Unicode. The function then analyzes each Unicode character for character type information.

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale
LOCALE_USER_DEFAULT	Default user locale
Note that the Locale parameter does not exist in the GetStringTypeW function. Because of that parameter difference, an application cannot automatically invoke the proper A or W version of GetStringType* through the use of the #define UNICODE switch. An application can circumvent this limitation by using GetStringTypeEx, which is the recommended Win32 function.

dwInfoType

Specifies the type of character information the user wants to retrieve. The various types are divided into different levels (see the following Remarks section for a list of the information included in each type). This parameter can specify one of the following character type flags:

CT_CTYPE1	Retrieve character type information.
CT_CTYPE2	Retrieve bidirectional layout information.
CT_CTYPE3	Retrieve text processing information.
lpSrcStr

Points to the string for which character types are requested. If cchSrc is −1, the string is assumed to be null terminated. This must be an ANSI string. Note that this can be a double-byte character set (DBCS) string if the locale is appropriate for DBCS.

cchSrc

Specifies the size, in bytes, of the string pointed to by the lpSrcStr parameter. If this count includes a null terminator, the function returns character type information for the null terminator. If this value is −1, the string is assumed to be null terminated and the length is calculated automatically.

lpCharType

Points to an array of 16-bit values. The length of this array must be large enough to receive one 16-bit value for each character in the source string. When the function returns, this array contains one word corresponding to each character in the source string.

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 one of the following error codes:

ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER

Remarks

The lpSrcStr and lpCharType pointers must not be the same. If they are the same, the function fails and GetLastError returns ERROR_INVALID_PARAMETER.

The Locale parameter is only used to perform string conversion to Unicode. It has nothing to do with the CTYPEs the function returns. The CTYPEs are solely determined by Unicode code points, and do not vary on a locale basis. For example, Greek letters are C1_ALPHA for any Locale value.

The character-type bits are divided into several levels. The information for one level can be retrieved by a single call to this function. Each level is limited to 16 bits of information so that the other mapping routines, which are limited to 16 bits of representation per character, can also return character-type information.

The character types supported by this function include the following.

Ctype 1

These types support ANSI C and POSIX (LC_CTYPE) character-typing functions. A combination of these values is returned in the array pointed to by the lpCharType parameter when the dwInfoType parameter is set to CT_CTYPE1.

Name	Value	Meaning
C1_UPPER	0x0001	Uppercase
C1_LOWER	0x0002	Lowercase
C1_DIGIT	0x0004	Decimal digits
C1_SPACE	0x0008	Space characters
C1_PUNCT	0x0010	Punctuation
C1_CNTRL	0x0020	Control characters
C1_BLANK	0x0040	Blank characters
C1_XDIGIT	0x0080	Hexadecimal digits
C1_ALPHA	0x0100	Any linguistic character: alphabetic, syllabary, or ideographic
The following character types are either constant or computable from basic types and do not need to be supported by this function.

Type	Description
Alphanumeric	Alphabetic characters and digits (C1_ALPHA and C1_DIGIT)
Printable	Graphic characters and blanks (all C1_* types except C1_CNTRL)
Ctype 2

These types support proper layout of Unicode text. The direction attributes are assigned so that the bidirectional layout algorithm standardized by Unicode produces accurate results. These types are mutually exclusive. For more information about the use of these attributes, see The Unicode Standard: Worldwide Character Encoding, Volumes 1 and 2, Addison Wesley Publishing Company: 1991, 1992, ISBN 0201567881.

Name	Value	Meaning
Strong:
C2_LEFTTORIGHT	0x1	Left to right
C2_RIGHTTOLEFT	0x2	Right to left
Weak:
C2_EUROPENUMBER	0x3	European number, European digit
C2_EUROPESEPARATOR	0x4	European numeric separator
C2_EUROPETERMINATOR	0x5	European numeric terminator
C2_ARABICNUMBER	0x6	Arabic number
C2_COMMONSEPARATOR	0x7	Common numeric separator
Neutral:
C2_BLOCKSEPARATOR	0x8	Block separator
C2_SEGMENTSEPARATOR	0x9	Segment separator
C2_WHITESPACE	0xA	White space
C2_OTHERNEUTRAL	0xB	Other neutrals
Not applicable:
C2_NOTAPPLICABLE	0x0	No implicit directionality (for example, control codes)
Ctype 3

These types are intended to be placeholders for extensions to the POSIX types required for general text processing or for the standard C library functions. These types are supported in the current version of Windows NT. A combination of these values is returned when dwInfoType is set to CT_CTYPE3.

Name	Value	Meaning
C3_NONSPACING	0x1	Nonspacing mark
C3_DIACRITIC	0x2	Diacritic nonspacing mark
C3_VOWELMARK	0x4	Vowel nonspacing mark
C3_SYMBOL	0x8	Symbol
C3_KATAKANA	0x10	Katakana character
C3_HIRAGANA	0x20	Hiragana character
C3_HALFWIDTH	0x40	Half-width character
C3_FULLWIDTH	0x80	Full-width character
C3_IDEOGRAPH	0x100	Ideographic character
C3_KASHIDA	0x200	Arabic Kashida character
C3_ALPHA	0x8000	All linguistic characters (alphabetic, syllabary, and ideographic)
Not applicable:
C3_NOTAPPLICABLE	0x0	Not applicable
See Also

GetLocaleInfo, GetStringTypeEx, GetStringTypeW


GetStringTypeEx

The GetStringTypeEx function returns character-type information for the characters in the specified source string. For each character in the string, the function sets one or more bits in the corresponding 16-bit element of the output array. Each bit identifies a given character type, such as whether the character is a letter, a digit, or neither.

Unlike its close relatives GetStringTypeA and GetStringTypeW, GetStringTypeEx exhibits appropriate A or W behavior through the use of the #define UNICODE switch. It is the recommended Win32 function.

BOOL GetStringTypeEx(

LCID Locale,	// locale identifer
DWORD dwInfoType,	// information-type options
LPCTSTR lpSrcStr,	// address of source string
int cchSrc,	// size, in bytes or characters, of source string
LPWORD lpCharType	// address of buffer for output
);
Parameters

Locale

Specifies the locale identifier. This value uniquely defines the ANSI code page to use to translate the string pointed to by lpSrcStr from ANSI to Unicode. The function then analyzes each Unicode character for character type information. Note that the W version of this function ignores this parameter.

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale
LOCALE_USER_DEFAULT	Default user locale
dwInfoType

Specifies the type of character information the user wants to retrieve. The various types are divided into different levels (see the following Remarks section for a list of the information included in each type). This parameter can specify one of the following character type flags:

CT_CTYPE1	Retrieve character type information.
CT_CTYPE2	Retrieve bidirectional layout information.
CT_CTYPE3	Retrieve text processing information.
lpSrcStr

Points to the string for which character types are requested. If cchSrc is −1, the string is assumed to be null terminated. This must be a Unicode string for the W version of this function, and an ANSI string for the A version. Note that for the A  version, this can be a double-byte character set (DBCS) string if the locale is appropriate for DBCS.

cchSrc

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the string pointed to by the lpSrcStr parameter. If this count includes a null terminator, the function returns character type information for the null terminator. If this value is −1, the string is assumed to be null terminated and the length is calculated automatically.

lpCharType

Points to an array of 16-bit values. The length of this array must be large enough to receive one 16-bit value for each character in the source string. When the function returns, this array contains one word corresponding to each character in the source string.

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 one of the following error codes:

ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER

Remarks

The GetStringTypeEx function exists to circumvent a limitation caused by the difference in parameters of GetStringTypeA and GetStringTypeW. That parameter difference prevents an application from automatically invoking the proper A or W version of GetStringType* through the use of the #define UNICODE switch. GetStringTypeEx, on the other hand, behaves properly as regards that switch. Thus, it is the recommended Win32 function.

The Locale parameter is only used to perform string conversion to Unicode. It has nothing to do with the CTYPEs the function returns. The CTYPEs are solely determined by Unicode code points, and do not vary on a locale basis. For example, Greek letters are C1_ALPHA for any Locale value.

The lpSrcStr and lpCharType pointers must not be the same. If they are the same, the function fails and GetLastError returns ERROR_INVALID_PARAMETER.

The character-type bits are divided into several levels. The information for one level can be retrieved by a single call to this function. Each level is limited to 16 bits of information so that the other mapping routines, which are limited to 16 bits of representation per character, can also return character-type information.

The character types supported by this function include the following.

Ctype 1

These types support ANSI C and POSIX (LC_CTYPE) character-typing functions. A combination of these values is returned in the array pointed to by the lpCharType parameter when the dwInfoType parameter is set to CT_CTYPE1.

Name	Value	Meaning
C1_UPPER	0x0001	Uppercase
C1_LOWER	0x0002	Lowercase
C1_DIGIT	0x0004	Decimal digits
C1_SPACE	0x0008	Space characters
C1_PUNCT	0x0010	Punctuation
C1_CNTRL	0x0020	Control characters
C1_BLANK	0x0040	Blank characters
C1_XDIGIT	0x0080	Hexadecimal digits
C1_ALPHA	0x0100	Any linguistic character: alphabetic, syllabary, or ideographic
The following character types are either constant or computable from basic types and do not need to be supported by this function.

Type	Description
Alphanumeric	Alphabetic characters and digits (C1_ALPHA and C1_DIGIT)
Printable	Graphic characters and blank (all C1_* types except C1_CNTRL)
Ctype 2

These types support proper layout of Unicode text. The direction attributes are assigned so that the bidirectional layout algorithm standardized by Unicode produces accurate results. These types are mutually exclusive. For more information about the use of these attributes, see The Unicode Standard: Worldwide Character Encoding, Volumes 1 and 2, Addison Wesley Publishing Company: 1991, 1992, ISBN 0201567881.

Name	Value	Meaning
Strong:
C2_LEFTTORIGHT	0x1	Left to right
C2_RIGHTTOLEFT	0x2	Right to left
Weak:
C2_EUROPENUMBER	0x3	European number, European digit
C2_EUROPESEPARATOR	0x4	European numeric separator
C2_EUROPETERMINATOR	0x5	European numeric terminator
C2_ARABICNUMBER	0x6	Arabic number
C2_COMMONSEPARATOR	0x7	Common numeric separator
Neutral:
C2_BLOCKSEPARATOR	0x8	Block separator
C2_SEGMENTSEPARATOR	0x9	Segment separator
C2_WHITESPACE	0xA	White space
C2_OTHERNEUTRAL	0xB	Other neutrals
Not applicable:
C2_NOTAPPLICABLE	0x0	No implicit directionality (for example, control codes)
Ctype 3

These types are intended to be placeholders for extensions to the POSIX types required for general text processing or for the standard C library functions. These types are supported in the current version of Windows NT. A combination of these values is returned when dwInfoType is set to CT_CTYPE3.

Name	Value	Meaning
C3_NONSPACING	0x1	Nonspacing mark
C3_DIACRITIC	0x2	Diacritic nonspacing mark
C3_VOWELMARK	0x4	Vowel nonspacing mark
C3_SYMBOL	0x8	Symbol
C3_KATAKANA	0x10	Katakana character
C3_HIRAGANA	0x20	Hiragana character
C3_HALFWIDTH	0x40	Half-width character
C3_FULLWIDTH	0x80	Full-width character
C3_IDEOGRAPH	0x100	Ideographic character
C3_KASHIDA	0x200	Arabic Kashida character
C3_ALPHA	0x8000	All linguistic characters (alphabetic, syllabary, and ideographic)
Not applicable:
C3_NOTAPPLICABLE	0x0	Not applicable
See Also

GetLocaleInfo, GetStringTypeA, GetStringTypeW


GetStringTypeW

The GetStringTypeW function returns character-type information for the characters in the specified source string. For each character in the string, the function sets one or more bits in the corresponding 16-bit element of the output array. Each bit identifies a given character type, such as whether the character is a letter, a digit, or neither.

BOOL GetStringTypeW(

DWORD dwInfoType,	// information-type options
LPCWSTR lpSrcStr,	// address of source string
int cchSrc,	// number of characters in string
LPWORD lpCharType	// address of buffer for output
);
Parameters

dwInfoType

Specifies the type of character information the user wants to retrieve. The various types are divided into different levels (see the following Remarks section for a list of the information included in each type). This parameter can specify one of the following character type flags:

CT_CTYPE1	Retrieve character type information.
CT_CTYPE2	Retrieve bidirectional layout information.
CT_CTYPE3	Retrieve text processing information.
lpSrcStr

Points to the string for which character types are requested. If cchSrc is −1, the string is assumed to be null terminated. This must be a Unicode string.

cchSrc

Specifies the size, in characters, of the string pointed to by the lpSrcStr parameter. If this count includes a null terminator, the function returns character type information for the null terminator. If this value is −1, the string is assumed to be null terminated and the length is calculated automatically.

lpCharType

Points to an array of 16-bit values. The length of this array must be large enough to receive one 16-bit value for the number of characters specified in the cchSrc parameter. When the function returns, this array contains one word corresponding to each Unicode character in the source string.

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 one of the following error codes:

ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER

Remarks

Note that the GetStringTypeA function has one more parameter than the GetStringTypeW function: GetStringTypeA has a first parameter that is an LCID named Locale. This parameter does not exist in the GetStringTypeW function. Because of that parameter difference, an application cannot automatically invoke the proper A or W version of GetStringType* through the use of the #define UNICODE switch. An application can circumvent this limitation by using GetStringTypeEx; it is the recommended Win32 function.

The lpSrcStr and lpCharType pointers must not be the same. If they are the same, the function fails and GetLastError returns ERROR_INVALID_PARAMETER.

The character-type bits are divided into several levels. The information for one level can be retrieved by a single call to this function. Each level is limited to 16 bits of information so that the other mapping routines, which are limited to 16 bits of representation per character, can also return character-type information.

The character types supported by this function include the following.

Ctype 1

These types support ANSI C and POSIX (LC_CTYPE) character-typing functions. A combination of these values is returned in the array pointed to by the lpCharType parameter when the dwInfoType parameter is set to CT_CTYPE1.

Name	Value	Meaning
C1_UPPER	0x0001	Uppercase
C1_LOWER	0x0002	Lowercase
C1_DIGIT	0x0004	Decimal digits
C1_SPACE	0x0008	Space characters
C1_PUNCT	0x0010	Punctuation
C1_CNTRL	0x0020	Control characters
C1_BLANK	0x0040	Blank characters
C1_XDIGIT	0x0080	Hexadecimal digits
C1_ALPHA	0x0100	Any linguistic character: alphabetic, syllabary, or ideographic
The following character types are either constant or computable from basic types and do not need to be supported by this function.

Type	Description
Alphanumeric	Alphabetic characters and digits (C1_ALPHA and C1_DIGIT)
Printable	Graphic characters and blanks (all C1_* types except C1_CNTRL)
Ctype 2

These types support proper layout of Unicode text. The direction attributes are assigned so that the bidirectional layout algorithm standardized by Unicode produces accurate results. These types are mutually exclusive. For more information about the use of these attributes, see The Unicode Standard: Worldwide Character Encoding, Volumes 1 and 2, Addison Wesley Publishing Company: 1991, 1992, ISBN 0201567881.

Name	Value	Meaning
Strong:
C2_LEFTTORIGHT	0x1	Left to right
C2_RIGHTTOLEFT	0x2	Right to left
Weak:
C2_EUROPENUMBER	0x3	European number, European digit
C2_EUROPESEPARATOR	0x4	European numeric separator
C2_EUROPETERMINATOR	0x5	European numeric terminator
C2_ARABICNUMBER	0x6	Arabic number
C2_COMMONSEPARATOR	0x7	Common numeric separator
Neutral:
C2_BLOCKSEPARATOR	0x8	Block separator
C2_SEGMENTSEPARATOR	0x9	Segment separator
C2_WHITESPACE	0xA	White space
C2_OTHERNEUTRAL	0xB	Other neutrals
Not applicable:
C2_NOTAPPLICABLE	0x0	No implicit directionality (for example, control codes)
Ctype 3

These types are intended to be placeholders for extensions to the POSIX types required for general text processing or for the standard C library functions. These types are supported in the current version of Windows NT. A combination of these values is returned when dwInfoType is set to CT_CTYPE3.

Name	Value	Meaning
C3_NONSPACING	0x1	Nonspacing mark
C3_DIACRITIC	0x2	Diacritic nonspacing mark
C3_VOWELMARK	0x4	Vowel nonspacing mark
C3_SYMBOL	0x8	Symbol
C3_KATAKANA	0x10	Katakana character
C3_HIRAGANA	0x20	Hiragana character
C3_HALFWIDTH	0x40	Half-width character
C3_FULLWIDTH	0x80	Full-width character
C3_IDEOGRAPH	0x100	Ideographic character
C3_KASHIDA	0x200	Arabic Kashida character
C3_ALPHA	0x8000	All linguistic characters (alphabetic, syllabary, and ideographic)
Not applicable:
C3_NOTAPPLICABLE	0x0	Not applicable
See Also

GetLocaleInfo, GetStringTypeA, GetStringTypeEx


GetSubMenu

The GetSubMenu function retrieves the handle of the drop-down menu or submenu activated by the specified menu item.

HMENU GetSubMenu(

HMENU hMenu,	// handle of menu
int nPos	// menu item position
);
Parameters

hMenu

Identifies the menu.

nPos

Specifies the zero-based relative position in the given menu of an item that activates a drop-down menu or submenu.

Return Values

If the function succeeds, the return value is the handle of the drop-down menu or submenu activated by the menu item. If the menu item does not activate a drop-down menu or submenu, the return value is NULL.

See Also

CreatePopupMenu, GetMenu


GetSysColor

The GetSysColor function retrieves the current color of the specified display element. Display elements are the parts of a window and the Windows display that appear on the system display screen.

DWORD GetSysColor(

int nIndex	// display element
);
Parameters

nIndex

Specifies the display element whose color is to be retrieved. This parameter must be one of the following values:

Value	Meaning
COLOR_3DDKSHADOW	Dark shadow for three-dimensional display elements.
COLOR_3DFACE,  COLOR_BTNFACE	Face color for three-dimensional display elements.
COLOR_3DHILIGHT, COLOR_3DHIGHLIGHT, COLOR_BTNHILIGHT, COLOR_BTNHIGHLIGHT	Highlight color for three-dimensional display elements (for edges facing the light source.)
COLOR_3DLIGHT	Light color for three-dimensional display elements (for edges facing the light source.)
COLOR_3DSHADOW, COLOR_BTNSHADOW	Shadow color for three-dimensional display elements (for edges facing away from the light source).
COLOR_ACTIVEBORDER	Active window border.
COLOR_ACTIVECAPTION	Active window caption.
COLOR_APPWORKSPACE	Background color of multiple document interface (MDI) applications.
COLOR_BACKGROUND, COLOR_DESKTOP	Desktop.
COLOR_BTNTEXT	Text on push buttons.
COLOR_CAPTIONTEXT	Text in caption, size box, and scroll bar arrow box.
COLOR_GRAYTEXT	Grayed (disabled) text. This color is set to 0 if the current display driver does not support a solid gray color.
COLOR_HIGHLIGHT	Item(s) selected in a control.
COLOR_HIGHLIGHTTEXT	Text of item(s) selected in a control.
COLOR_INACTIVEBORDER	Inactive window border.
COLOR_INACTIVECAPTION	Inactive window caption.
COLOR_INACTIVECAPTIONTEXT	Color of text in an inactive caption.
COLOR_INFOBK	Background color for tooltip controls.
COLOR_INFOTEXT	Text color for tooltip controls.
COLOR_MENU	Menu background.
COLOR_MENUTEXT	Text in menus.
COLOR_SCROLLBAR	Scroll bar gray area.
COLOR_WINDOW	Window background.
COLOR_WINDOWFRAME	Window frame.
COLOR_WINDOWTEXT	Text in windows.
Return Values

If the function succeeds, the return value is the red, green, blue (RGB) color value that specifies the color of the given element.

Remarks

System colors for monochrome displays are usually interpreted as shades of gray.

See Also

SetSysColors


GetSysColorBrush

The GetSysColorBrush function retrieves a handle identifying a logical brush that corresponds to the specified color index.

HBRUSH GetSysColorBrush(

int nIndex	// system color index
);
Parameters

nIndex

Specifies a color index. This value corresponds to the color used to paint one of the 21 window elements.

Return Values

If the function succeeds, the return value identifies a logical brush. To get extended error information, call GetLastError.

Remarks

A brush is a bitmap that Windows uses to paint the interiors of filled shapes. An application can retrieve the current system colors by calling the GetSysColor function. An application can set the current system colors by calling the SetSysColors function.

An application must not register a window class for a window using a system brush.

See Also

GetSysColor, SetSysColors


GetSysModalWindow

The GetSysModalWindow function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows.


GetSystemDefaultLangID

The GetSystemDefaultLangID function retrieves the system default language identifier.

LANGID GetSystemDefaultLangID(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the system default language identifier.

Remarks

For more information about language identifiers, see Language Identifiers and Locales.

See Also

GetUserDefaultLangID, MAKELANGID


GetSystemDefaultLCID

The GetSystemDefaultLCID function retrieves the system default locale identifier.

LCID GetSystemDefaultLCID(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the system default locale identifier.

Remarks

For more information about locale identifiers, see Locale Identifiers.

See Also

GetLocaleInfo, GetUserDefaultLCID, MAKELCID


GetSystemDirectory

The GetSystemDirectory function retrieves the path of the Windows system directory. The system directory contains such files as Windows libraries, drivers, and font files.

UINT GetSystemDirectory(

LPTSTR lpBuffer,	// address of buffer for system directory
UINT uSize	// size of directory buffer
);
Parameters

lpBuffer

Points to the buffer to receive the null-terminated string containing the path. This path does not end with a backslash unless the system directory is the root directory. For example, if the system directory is named WINDOWS\SYSTEM on drive C, the path of the system directory retrieved by this function is C:\WINDOWS\SYSTEM.

uSize

Specifies the maximum size of the buffer, in characters. This value should be set to at least MAX_PATH.

Return Values

If the function succeeds, the return value is the length, in characters, of the string copied to the buffer, not including the terminating null character. If the length is greater than the size of the buffer, the return value is the size of the buffer required to hold the path.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Applications should not create files in the system directory. If the user is running a shared version of Windows, the application does not have write access to the system directory. Applications should create files only in the directory returned by the GetWindowsDirectory function.

See Also

GetCurrentDirectory, GetWindowsDirectory, SetCurrentDirectory


GetSystemInfo

The GetSystemInfo function returns information about the current system.

VOID GetSystemInfo(

LPSYSTEM_INFO lpSystemInfo	// address of system information structure
);
Parameters

lpSystemInfo

Points to a SYSTEM_INFO structure to be filled in by this function.

Return Values

This function does not return a value.

See Also

SYSTEM_INFO


GetSystemMenu

The GetSystemMenu function allows the application to access the window menu (also known as the System menu or the Control menu) for copying and modifying.

HMENU GetSystemMenu(

HWND hWnd,	// handle of window to own window menu
BOOL bRevert	// reset flag
);
Parameters

hWnd

Identifies the window that will own a copy of the window menu.

bRevert

Specifies the action to be taken. If this parameter is FALSE, GetSystemMenu returns the handle of the copy of the window menu currently in use. The copy is initially identical to the window menu, but it can be modified.

If this parameter is TRUE, GetSystemMenu resets the window menu back to the Windows default state. The previous window menu, if any, is destroyed.

Return Values

If the bRevert parameter is FALSE, the return value is the handle of a copy of the window menu. If the bRevert parameter is TRUE, the return value is NULL.

Remarks

Any window that does not use the GetSystemMenu function to make its own copy of the window menu receives the standard window menu.

The window menu initially contains items with various identifier values, such as SC_CLOSE, SC_MOVE, and SC_SIZE.

Menu items on the window menu send WM_SYSCOMMAND messages.

All predefined window menu items have identifier numbers greater than 0xF000. If an application adds commands to the window menu, it should use identifier numbers less than 0xF000.

Windows automatically grays items on the standard window menu, depending on the situation. The application can perform its own checking or graying by responding to the WM_INITMENU message that is sent before any menu is displayed.

See Also

GetMenu, WM_INITMENU, WM_SYSCOMMAND


GetSystemMetrics

The GetSystemMetrics function retrieves various system metrics and system configuration settings.

System metrics are the dimensions (widths and heights) of Windows display elements. All dimensions retrieved by GetSystemMetrics are in pixels.

int GetSystemMetrics(

int nIndex	// system metric or configuration setting to retrieve
);
Parameters

nIndex

Specifies the system metric or configuration setting to retrieve. All SM_CX* values are widths. All SM_CY* values are heights. The following values are defined:

Value	Meaning
SM_ARRANGE	Flags specifying how the system arranged minimized windows. For more information about minimized windows, see the following Remarks section.
SM_CLEANBOOT	Value that specifies how the system was started: 0  Normal boot 1  Fail-safe boot 2  Fail-safe with network boot Fail-safe boot (also called SafeBoot) bypasses the user’s startup files.
SM_CMOUSEBUTTONS	Number of buttons on mouse, or zero if no mouse is installed.
SM_CXBORDER,  SM_CYBORDER	The width and height, in pixels, of a window border. This is equivalent to the SM_CXEDGE value for windows with the 3-D look.
SM_CXCURSOR,  SM_CYCURSOR	Width and height, in pixels, of a cursor. These are the cursor dimensions supported by the current display driver. The system cannot create cursors of other sizes.
SM_CXDLGFRAME, SM_CYDLGFRAME	Same as SM_CXFIXEDFRAME and SM_CYFIXEDFRAME.
SM_CXDOUBLECLK,  SM_CYDOUBLECLK	Width and height, in pixels, of the rectangle around the location of a first click in a double-click sequence. The second click must occur within this rectangle for the system to consider the two clicks a double-click. (The two clicks must also occur within a specified time.)
SM_CXDRAG,  SM_CYDRAG	Width and height, in pixels, of a rectangle centered on a drag point to allow for limited movement of the mouse pointer before a drag operation begins. This allows the user to click and release the mouse button easily without unintentionally starting a drag operation.
SM_CXEDGE,  SM_CYEDGE	Dimensions, in pixels, of a 3-D border. These are the 3-D counterparts of SM_CXBORDER and SM_CYBORDER.
SM_CXFIXEDFRAME, SM_CYFIXEDFRAME	Thickness, in pixels, of the frame around the perimeter of a window that has a caption but is not sizable. SM_CXFIXEDFRAME is the width of the horizontal border and SM_CYFIXEDFRAME is the height of the vertical border.  Same as SM_CXDLGFRAME and SM_CYDLGFRAME.
SM_CXFRAME, SM_CYFRAME	Same as SM_CXSIZEFRAME and SM_CYSIZEFRAME.
SM_CXFULLSCREEN, SM_CYFULLSCREEN	Width and height of the client area for a full-screen window. To get the coordinates of the portion of the screen not obscured by the tray, call the SystemParametersInfo function with the SPI_GETWORKAREA value.
SM_CXHSCROLL, SM_CYHSCROLL	Width, in pixels, of the arrow bitmap on a horizontal scroll bar; and height, in pixels, of a horizontal scroll bar.
SM_CXHTHUMB	Width, in pixels, of the thumb box in a horizontal scroll bar.
SM_CXICON,  SM_CYICON	The default width and height, in pixels, of an icon. These values are typically 32x32, but can vary depending on the installed display hardware. The LoadIcon function can only load icons of these dimensions.
SM_CXICONSPACING, SM_CYICONSPACING	Dimensions, in pixels, of a grid cell for items in large icon view. Each item fits into a rectangle of this size when arranged. These values are always greater than or equal to SM_CXICON and SM_CYICON.
SM_CXMAXIMIZED, SM_CYMAXIMIZED	Default dimensions, in pixels, of a maximized top-level window.
SM_CXMAXTRACK, SM_CYMAXTRACK	Default maximum dimensions, in pixels, of a window that has a caption and sizing borders. The user cannot drag the window frame to a size larger than these dimensions. A window can override these values by processing the WM_GETMINMAXINFO message.
SM_CXMENUCHECK, SM_CYMENUCHECK	Dimensions, in pixels, of the default menu check-mark bitmap.
SM_CXMENUSIZE, SM_CYMENUSIZE	Dimensions, in pixels, of menu bar buttons, such as multiple document (MIDI) child close.
SM_CXMIN,  SM_CYMIN	Minimum width and height, in pixels, of a window.
SM_CXMINIMIZED, SM_CYMINIMIZED	Dimensions, in pixels, of a normal minimized window.
SM_CXMINSPACING SM_CYMINSPACING	Dimensions, in pixels, of a grid cell for minimized windows. Each minimized window fits into a rectangle this size when arranged. These values are always greater than or equal to SM_CXMINIMIZED and SM_CYMINIMIZED.
SM_CXMINTRACK, SM_CYMINTRACK	Minimum tracking width and height, in pixels, of a window. The user cannot drag the window frame to a size smaller than these dimensions. A window can override these values by processing the WM_GETMINMAXINFO message.
SM_CXSCREEN,  SM_CYSCREEN	Width and height, in pixels, of the screen.
SM_CXSIZE,  SM_CYSIZE	Width and height, in pixels, of a button in a window's caption or title bar.
SM_CXSIZEFRAME, SM_CYSIZEFRAME	Thickness, in pixels, of the sizing border around the perimeter of a window that can be resized. SM_CXSIZEFRAME is the width of the horizontal border and SM_CYSIZEFRAME is the height of the vertical border.  Same as SM_CXFRAME and SM_CYFRAME.
SM_CXSMICON, SM_CYSMICON	Recommended dimensions, in pixels, of a small icon. Small icons typically appear in window captions and in small icon view.
SM_CXSMSIZE SM_CYSMSIZE	Dimensions, in pixels, of small caption buttons.
SM_CXVSCROLL, SM_CYVSCROLL	Width, in pixels, of a vertical scroll bar; and height, in pixels, of the arrow bitmap on a vertical scroll bar.
SM_CYCAPTION	Height, in pixels, of normal caption area.
SM_CYKANJIWINDOW	For double-byte character set versions of Windows, height, in pixels, of the Kanji window at the bottom of the screen.
SM_CYMENU	Height, in pixels, of single-line menu bar.
SM_CYSMCAPTION	Height, in pixels, of a small caption.
SM_CYVTHUMB	Height , in pixels, of the thumb box in a vertical scroll bar.
SM_DBCSENABLED	TRUE or nonzero if the double-byte character set (DBCS) version of USER.EXE is installed; FALSE, or zero otherwise.
SM_DEBUG	TRUE or nonzero if the debugging version of USER.EXE is installed; FALSE, or zero, otherwise.
SM_MENUDROPALIGNMENT	TRUE, or nonzero if drop-down menus are right-aligned relative to the corresponding menu-bar item; FALSE, or zero if they are left-aligned.
SM_MIDEASTENABLED	TRUE if the system is enabled for Hebrew/Arabic languages.
SM_MOUSEPRESENT	TRUE or nonzero if a mouse is installed; FALSE, or zero, otherwise.
SM_MOUSEWHEELPRESENT	Windows NT only: TRUE or nonzero if a mouse with a wheel is installed; FALSE, or zero, otherwise.
SM_NETWORK	The least significant bit is set if a network is present; otherwise, it is cleared. The other bits are reserved for future use.
SM_PENWINDOWS	TRUE or nonzero if the Microsoft Windows for Pen computing extensions are installed; zero, or FALSE, otherwise.
SM_SECURE	TRUE if security is present, FALSE otherwise.
SM_SHOWSOUNDS	TRUE or nonzero if the user requires an application to present information visually in situations where it would otherwise present the information only in audible form; FALSE, or zero, otherwise.
SM_SLOWMACHINE	TRUE if the computer has a low-end (slow) processor, FALSE otherwise.
SM_SWAPBUTTON	TRUE or nonzero if the meanings of the left and right mouse buttons are swapped; FALSE, or zero, otherwise.
Return Values

If the function succeeds, the return value is the requested system metric or configuration setting.

If the function fails, the return value is zero. GetLastError does not provide extended error information.

Remarks

System metrics may vary from display to display.

The SM_ARRANGE setting specifies how the system arranges minimized windows, and consists of a starting position and a direction. The starting position can be one of the following values.

Value	Meaning
ARW_BOTTOMLEFT	Start at lower-left corner of screen (default position).
ARW_BOTTOMRIGHT	Start at lower-right corner of screen. Equivalent to ARW_STARTRIGHT.
ARW_HIDE	Hide minimized windows by moving them off of the visible area of the screen.
ARW_TOPLEFT	Start at upper-left corner of screen. Equivalent to ARV_STARTTOP.
ARW_TOPRIGHT	Start at upper-right corner of screen. Equivalent to ARW_STARTTOP | SRW_STARTRIGHT.
The direction in which to arrange can be one of the following values.

Value	Meaning
ARW_DOWN	Arrange vertically, top to bottom.
ARW_LEFT	Arrange horizontally, left to right.
ARW_RIGHT	Arrange horizontally, right to left.
ARW_UP	Arrange vertically, bottom to top.


GetSystemPaletteEntries

The GetSystemPaletteEntries function retrieves a range of palette entries from the system palette that is associated with the specified device context.

UINT GetSystemPaletteEntries(

HDC hdc,	// handle of device context
UINT iStartIndex,	// index of first entry to be retrieved
UINT nEntries,	// number of entries to be retrieved
LPPALETTEENTRY lppe	// array receiving system-palette entries
);
Parameters

hdc

Identifies the device context.

iStartIndex

Specifies the first entry to be retrieved from the system palette.

nEntries

Specifies the number of entries to be retrieved from the system palette.

lppe

Points to an array of PALETTEENTRY structures to receive the palette entries. The array must contain at least as many structures as specified by the nEntries parameter. If this parameter is NULL, the function returns the total number of entries in the palette.

Return Values

If the function succeeds, the return value is the number of entries retrieved from the palette.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

See Also

GetDeviceCaps, GetPaletteEntries, PALETTEENTRY


GetSystemPaletteUse

The GetSystemPaletteUse function retrieves the current state of the system (physical) palette for the specified device context.

UINT GetSystemPaletteUse(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Values

If the function succeeds, the return value is the current state of the system palette. It can be any of the following values:

Value	Meaning
SYSPAL_NOSTATIC	The system palette contains no static colors except black and white.
SYSPAL_STATIC	The system palette contains static colors that will not change when an application realizes its logical palette.
SYSPAL_ERROR	The given device context is invalid or does not support a color palette.
To get extended error information, call GetLastError.

Remarks

By default, the system palette contains 20 static colors that are not changed when an application realizes its logical palette. An application can gain access to most of these colors by calling the SetSystemPaletteUse function.

The device context identified by the hdc parameter must represent a device that supports color palettes.

An application can determine whether or not a device supports color palettes by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

See Also

GetDeviceCaps, SetSystemPaletteUse


GetSystemPowerStatus

The GetSystemPowerStatus function retrieves the power status of the system. The status indicates whether the system is running on AC or DC power, whether the battery is currently charging, and how much battery life currently remains.

BOOL GetSystemPowerStatus(

LPSYSTEM_POWER_STATUS lpSystemPowerStatus
);
Parameters

lpSystemPowerStatus

Pointer to a SYSTEM_POWER_STATUS structure that receives status information.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

SYSTEM_POWER_STATUS


GetSystemTime

The GetSystemTime function retrieves the current system date and time. The system time is expressed in Coordinated Universal Time (UTC).

VOID GetSystemTime(

LPSYSTEMTIME lpSystemTime	// address of system time structure
);
Parameters

lpSystemTime

Points to a SYSTEMTIME structure to receive the current system date and time.

Return Values

This function does not return a value.

See Also

GetLocalTime, GetSystemTimeAdjustment, SetSystemTime, SYSTEMTIME


GetSystemTimeAdjustment

The GetSystemTimeAdjustment function determines whether the system is applying periodic time adjustments to its time-of-day clock at each clock interrupt, along with the value and period of any such adjustments. Note that the period of such adjustments is equivalent to the time period between clock interrupts.

BOOL GetSystemTimeAdjustment(

PDWORD lpTimeAdjustment,	// size, in 100-nanosecond units, of a periodic time adjustment
PDWORD lpTimeIncrement,	// time, in 100-nanosecond units, between periodic time adjustments
PBOOL lpTimeAdjustmentDisabled	// whether periodic time adjustment is disabled or enabled
);
Parameters

lpTimeAdjustment

Pointer to a DWORD that the function sets to the number of 100-nanosecond units added to the time-of-day clock at each periodic time adjustment.

lpTimeIncrement

Pointer to a DWORD that the function sets to the interval, counted in 100-nanosecond units, between periodic time adjustments. This interval is the time period between a system’s clock interrupts.

lpTimeAdjustmentDisabled

Pointer to a BOOL that the function sets to indicate whether periodic time adjustment is in effect.

A value of TRUE indicates that periodic time adjustment is disabled. At each clock interrupt, the system merely adds the interval between clock interrupts to the time-of-day clock. The system is free, however, to adjust its time-of-day clock using other techniques. Such other techniques may cause the time-of-day clock to noticeably jump when adjustments are made.

A value of FALSE indicates that periodic time adjustment is being used to adjust the time-of-day clock. At each clock interrupt, the system adds the time increment specified by SetSystemTimeAdjustment’s dwTimeIncrement parameter to the time-of-day clock. The system will not interfere with the time adjustment scheme, and will not attempt to synchronize time of day on its own via other techniques.

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.

Remarks

The GetSystemTimeAdjustment and SetSystemTimeAdjustment functions support algorithms that want to synchronize the time-of-day clock, reported by GetSystemTime and GetLocalTime, with another time source using a periodic time adjustment applied at each clock interrupt.

When periodic time adjustment is in effect, the system adds an adjusting value to the time-of-day clock at a periodic interval, at each clock interrupt. The GetSystemTimeAdjustment function lets a caller determine whether periodic time adjustment is enabled, and if it is, obtain the amount of each adjustment and the time between adjustments. The SetSystemTimeAdjustment function lets a caller enable or disable periodic time adjustment, and set the value of the adjusting increment.

See Also

SetSystemTimeAdjustment, GetSystemTime, GetLocalTime


GetSystemTimeAsFileTime

The GetSystemTimeAsFileTime function obtains the current system date and time. The information is in Coordinated Universal Time (UTC) format.

VOID GetSystemTimeAsFileTime(

LPFILETIME lpSystemTimeAsFileTime	// pointer to a file time structure
);
Parameters

lpSystemTimeAsFileTime

Pointer to a FILETIME structure to receive the current system date and time in UTC format.

Return Values

This function does not return a value.

Remarks

The GetSystemTimeAsFileTime function is equivalent to the following code sequence:

FILETIME ft;

SYSTEMTIME st;

GetSystemTime(&st);

SystemTimeToFileTime(&st,&ft);

See Also

FILETIME, GetSystemTime, SYSTEMTIME, SystemTimeToFileTime


GetTabbedTextExtent

The GetTabbedTextExtent function computes the width and height of a character string. If the string contains one or more tab characters, the width of the string is based upon the specified tab stops. The GetTabbedTextExtent function uses the currently selected font to compute the dimensions of the string.

DWORD GetTabbedTextExtent(

HDC hDC,	// handle of device context
LPCTSTR lpString,	// address of character string
int nCount,	// number of characters in string
int nTabPositions,	// number of tab positions
LPINT lpnTabStopPositions	// address of array of tab positions
);
Parameters

hDC

Identifies the device context.

lpString

Points to a character string.

nCount

Specifies the number of characters in the text string.

nTabPositions

Specifies the number of tab-stop positions in the array pointed to by the lpnTabStopPositions parameter.

lpnTabStopPositions

Points to an array containing the tab-stop positions, in device units. The tab stops must be sorted in increasing order; the smallest x-value should be the first item in the array.

Return Values

If the function succeeds, the return value is the dimensions of the string. The height is in the high-order word and the width is in the low-order word.

If the function fails, the return value is 0. GetTabbedTextExtent will fail if hDC is invalid and if nTabPositions is less than 0.

Remarks

The current clipping region does not affect the width and height returned by the GetTabbedTextExtent function.

Because some devices do not place characters in regular cell arrays (that is, they kern the characters), the sum of the extents of the characters in a string may not be equal to the extent of the string.

If the nTabPositions parameter is zero and the lpnTabStopPositions parameter is NULL, tabs are expanded to eight times the average character width.

If nTabPositions is 1, the tab stops are separated by the distance specified by the first value in the array to which lpnTabStopPositions points.

See Also

GetTextExtentPoint32, HIWORD, LOWORD, TabbedTextOut


GetTapeParameters

The GetTapeParameters function retrieves information that describes the tape or the tape drive.

DWORD GetTapeParameters(

HANDLE hDevice,	// handle of open device
DWORD dwOperation,	// type of information requested
LPDWORD lpdwSize,	// address of returned information
LPVOID lpTapeInformation	// tape media or drive information
);
Parameters

hDevice

Identifies the device about which information is sought. This handle is created by using the CreateFile function.

dwOperation

Specifies the type of information requested. This parameter must be one of the following values:

Value	Description
GET_TAPE_MEDIA_INFORMATION	Retrieves information about the tape in the tape device.
GET_TAPE_DRIVE_INFORMATION	Retrieves information about the tape device.
lpdwSize

Points to a variable that receives the size, in bytes, of the buffer specified by the lpTapeInformation parameter. If the buffer is too small, this parameter receives the required size.

lpTapeInformation

Points to a structure that contains the requested information. If the dwOperation parameter is GET_TAPE_MEDIA_INFORMATION, lpTapeInformation points to a TAPE_GET_MEDIA_PARAMETERS structure.

If dwOperation is GET_TAPE_DRIVE_INFORMATION, lpTapeInformation points to a TAPE_GET_DRIVE_PARAMETERS structure.

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:

Error code	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
Remarks

The block size range values (maximum and minimum) returned by the GetTapeParameters function called with the dwOperation parameter set to the GET_TAPE_DRIVE_INFORMATION value will indicate system limits, not drive limits. However, it is the tape drive device and the media present in the drive that determine the true block size limits. Thus, an application may not be able to set all the block sizes mentioned in the range obtained by specifying GET_TAPE_DRIVE_INFORMATION in dwOperation.

See Also

CreateFile, SetTapeParameters, TAPE_GET_DRIVE_PARAMETERS, TAPE_GET_MEDIA_PARAMETERS


GetTapePosition

The GetTapePosition function retrieves the current address of the tape, in logical or absolute blocks.

DWORD GetTapePosition(

HANDLE hDevice,	// handle of open device
DWORD dwPositionType,	// type of address to obtain
LPDWORD lpdwPartition,	// address of current tape partition
LPDWORD lpdwOffsetLow,	// address of low-order 32 bits of tape position
LPDWORD lpdwOffsetHigh	// address of high-order 32 bits of tape position
);
Parameters

hDevice

Identifies the device on which to get the tape position. This handle is created by using CreateFile.

dwPositionType

Specifies the type of address to obtain. This parameter can be one of the following values:

Value	Description
TAPE_ABSOLUTE_POSITION	The lpdwOffsetLow and lpdwOffsetHigh parameters receive the device-specific block address. The dwPartition parameter receives zero.
TAPE_LOGICAL_POSITION	The lpdwOffsetLow and lpdwOffsetHigh parameters receive the logical block address. The dwPartition parameter receives the logical tape partition.
lpdwPartition

Points to a variable that receives the number of the current tape partition. Partitions are numbered logically from 1 through n, where 1 is the first partition on the tape and n is the last. When a device-specific block address is retrieved, or if the device supports only one partition, this parameter receives zero.

lpdwOffsetLow

Points to a variable that receives the low-order 32 bits of the current tape position.

lpdwOffsetHigh

Points to a variable that receives the high-order 32 bits of the current tape position. This parameter can be NULL if the high-order 32 bits are not required.

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:

Error code	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
Remarks

A logical block address is relative to a partition. The first logical block address on each partition is zero.

Call the GetTapeParameters function to obtain information about the status, capabilities, and capacities of tape drives and media.

See Also

CreateFile, GetTapeParameters, SetTapePosition


GetTapeStatus

The GetTapeStatus function indicates whether the tape device is ready to process tape commands.

DWORD GetTapeStatus(

HANDLE hDevice	// handle of open device
);
Parameters

hDevice

Identifies the device for which to get the device status. This handle is created by using the CreateFile function.

Return Values

If the tape device is ready to accept appropriate tape-access commands without returning errors, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes:

Error code	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
See Also

CreateFile


GetTempFileName

The GetTempFileName function creates a name for a temporary file. The filename is the concatenation of specified path and prefix strings, a hexadecimal string formed from a specified integer, and the .TMP extension.

The specified integer can be nonzero, in which case, the function creates the filename but does not create the file. If you specify zero for the integer, the function creates a unique filename and creates the file in the specified directory.

UINT GetTempFileName(

LPCTSTR lpPathName,	// address of directory name for temporary file
LPCTSTR lpPrefixString,	// address of filename prefix
UINT uUnique,	// number used to create temporary filename
LPTSTR lpTempFileName	// address of buffer that receives the new filename
);
Parameters

lpPathName

Points to a null-terminated string that specifies the directory path for the filename. This string must consist of characters in the ANSI character set. Applications typically specify a period (.) or the result of the GetTempPath function for this parameter. If this parameter is NULL, the function fails.

lpPrefixString

Points to a null-terminated prefix string. The function uses the first three characters of this string as the prefix of the filename. This string must consist of characters in the ANSI character set.

uUnique

Specifies an unsigned integer that the function converts to a hexadecimal string for use in creating the temporary filename.

If uUnique is nonzero, the function appends the hexadecimal string to lpPrefixString to form the temporary filename. In this case, the function does not create the specified file, and does not test whether the filename is unique.

If uUnique is zero, the function uses a hexadecimal string derived from the current system time. In this case, the function uses different values until it finds a unique filename, and then it creates the file in the lpPathName directory.

lpTempFileName

Points to the buffer that receives the temporary filename. This null-terminated string consists of characters in the ANSI character set. This buffer should be at least the length, in bytes, specified by MAX_PATH to accommodate the path.

Return Values

If the function succeeds, the return value specifies the unique numeric value used in the temporary filename. If the uUnique parameter is nonzero, the return value specifies that same number.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The GetTempFileName function creates a temporary filename of the following form:

     path\preuuuu.TMP

The following table describes the filename syntax:

Component	Meaning
path	Path specified by the lpPathName parameter
pre	First three letters of the lpPrefixString string
uuuu	Hexadecimal value of uUnique
When Windows shuts down, temporary files whose names have been created by this function are not automatically deleted.

To avoid problems resulting from converting an ANSI character set string to a Windows string, an application should call the CreateFile function to create a temporary file.

If the uUnique parameter is zero, GetTempFileName attempts to form a unique number based on the current system time. If a file with the resulting filename exists, the number is increased by one and the test for existence is repeated. Testing continues until a unique filename is found. GetTempFileName then creates a file by that name and closes it. When uUnique is nonzero, no attempt is made to create and open the file.

See Also

CreateFile, GetTempPath


GetTempPath

The GetTempPath function retrieves the path of the directory designated for temporary files. This function supersedes the GetTempDrive function.

DWORD GetTempPath(

DWORD nBufferLength,	// size, in characters, of the buffer
LPTSTR lpBuffer	// address of buffer for temp. path
);
Parameters

nBufferLength

Specifies the size, in characters, of the string buffer identified by lpBuffer.

lpBuffer

Points to a string buffer that receives the null-terminated string specifying the temporary file path.

Return Values

If the function succeeds, the return value is the length, in characters, of the string copied to lpBuffer, not including the terminating null character. If the return value is greater than nBufferLength, the return value is the size of the buffer required to hold the path.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The GetTempPath function gets the temporary file path as follows:

1.	The path specified by the TMP environment variable.

2.	The path specified by the TEMP environment variable, if TMP is not defined.

3.	The current directory, if both TMP and TEMP are not defined.

See Also

GetTempFileName


GetTextAlign

The GetTextAlign function retrieves the text-alignment setting for the specified device context.

UINT GetTextAlign(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Values

If the function succeeds, the return value is the status of the text-alignment flags.

If the function fails, the return value is GDI_ERROR. To get extended error information, call GetLastError.

For a list of status return values, see the Remarks section. The return value is a combination of one or more of the following values:

Value	Meaning
TA_BASELINE	The reference point is on the base line of the text.
TA_BOTTOM	The reference point is on the bottom edge of the bounding rectangle.
TA_TOP	The reference point is on the top edge of the bounding rectangle.
TA_CENTER	The reference point is aligned horizontally with the center of the bounding rectangle.
TA_LEFT	The reference point is on the left edge of the bounding rectangle.
TA_RIGHT	The reference point is on the right edge of the bounding rectangle.
TA_RTLREADING	Windows 95 only: The text is laid out in right to left reading order, as opposed to the default left to right order. This only applies when the font selected into the device context is either Hebrew or Arabic.
TA_NOUPDATECP	The current position is not updated after each text output call.
TA_UPDATECP	The current position is updated after each text output call.
When the current font has a vertical default base line (as with Kanji), the following values are used instead of TA_BASELINE and TA_CENTER:

Value	Meaning
VTA_BASELINE	The reference point is on the base line of the text.
VTA_CENTER	The reference point is aligned vertically with the center of the bounding rectangle.
Remarks

The bounding rectangle is a rectangle bounding all of the character cells in a string of text. Its dimensions can be obtained by calling the GetTextExtentPoint32 function.

The text-alignment flags determine how the TextOut and ExtTextOut functions align a string of text in relation to the string’s reference point provided to TextOut or ExtTextOut.

The text-alignment flags are not necessarily single bit flags and may be equal to zero. The flags must be examined in groups of related flags, as shown in the following list:

TA_LEFT, TA_RIGHT, and TA_CENTER
TA_BOTTOM, TA_TOP, and TA_BASELINE
TA_NOUPDATECP and TA_UPDATECP

If the current font has a vertical default base line, the related flags are as shown in the following list:

TA_LEFT, TA_RIGHT, and VTA_BASELINE
TA_BOTTOM, TA_TOP, and VTA_CENTER
TA_NOUPDATECP and TA_UPDATECP

To verify that a particular flag is set in the return value of this function, the application must perform the following steps:

1.	Apply the bitwise OR operator to the flag and its related flags.

2.	Apply the bitwise AND operator to the result and the return value.

3.	Test for the equality of this result and the flag.

See Also

ExtTextOut, GetTextExtentPoint32, SetTextAlign, TextOut


GetTextCharacterExtra

The GetTextCharacterExtra function retrieves the current intercharacter spacing for the specified device context.

int GetTextCharacterExtra(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Values

If the function succeeds, the return value is the current intercharacter spacing.

If the function fails, the return value is 0x8000000.

Remarks

The intercharacter spacing defines the extra space, in logical units along the base line, that the TextOut or ExtTextOut functions add to each character as a line is written. The spacing is used to expand lines of text.

See Also

ExtTextOut, SetTextCharacterExtra, TextOut


GetTextCharset

The GetTextCharset function obtains a character-set identifier for the font that is currently selected into a specified device context.

The function call GetTextCharset(hdc) is equivalent to the function call GetTextCharsetInfo(hdc, NULL, 0).

UINT GetTextCharsetInfo(

HDC hdc,	// handle to device context
);
Parameters

hdc

Handle to a device context. The function obtains a character-set identifier for the font that is selected into this device context.

Return Values

If the function succeeds, the return value identifies the character set of the font that is currently selected into the specified device context. The following character-set identifiers are defined:

ANSI_CHARSET

CHINESEBIG5_CHARSET

DEFAULT_CHARSET

GB2312_CHARSET

HANGEUL_CHARSET

OEM_CHARSET

SHIFTJIS_CHARSET

SYMBOL_CHARSET

Windows 95 only:

ARABIC_CHARSET

BALTIC_CHARSET

EASTEUROPE_CHARSET

GREEK_CHARSET

HEBREW_CHARSET

JOHAB_CHARSET

MAC_CHARSET

RUSSIAN_CHARSET

THAI_CHARSET

TURKISH_CHARSET

If the function fails, the return value is DEFAULT_CHARSET.

See Also

GetTextCharsetInfo


GetTextCharsetInfo

The GetTextCharsetInfo function obtains information about the character set of the font that is currently selected into a specified device context.

UINT GetTextCharsetInfo(

HDC hdc,	// handle to device context
LPFONTSIGNATURE lpSig,	// pointer to structure to receive Unicode and code page data
DWORD dwFlags	// reserved; must be zero
);
Parameters

hdc

Handle to a device context. The function obtains information about the font that is selected into this device context.

lpSig

Pointer to a FONTSIGNATURE data structure that receives font-signature information.

If a TrueType font is currently selected into the device context, the FONTSIGNATURE structure receives information that identifies the codepage and Unicode subranges for which the font provides glyphs.

If a font other than TrueType is currently selected into the device context, the FONTSIGNATURE structure receives zeroes. In this case, use the TranslateCharsetInfo function to obtain generic font-signature information for the character set.

The lpSig parameter can be NULL if you do not need the FONTSIGNATURE information. In this case, you can also call the GetTextCharset function, which is equivalent to calling GetTextCharsetInfo with lpSig set to NULL.

dwFlags

This parameter is reserved for future use. It must be set to zero.

Return Values

If the function succeeds, the return value identifies the character set of the font currently selected into the specified device context. The following character-set identifiers are defined:

ANSI_CHARSET

CHINESEBIG5_CHARSET

DEFAULT_CHARSET

GB2312_CHARSET

HANGEUL_CHARSET

OEM_CHARSET

SHIFTJIS_CHARSET

SYMBOL_CHARSET

Windows 95 only:

ARABIC_CHARSET

BALTIC_CHARSET

EASTEUROPE_CHARSET

GREEK_CHARSET

HEBREW_CHARSET

JOHAB_CHARSET

MAC_CHARSET

RUSSIAN_CHARSET

THAI_CHARSET

TURKISH_CHARSET

If the function fails, the return value is DEFAULT_CHARSET.

See Also

FONTSIGNATURE, GetTextCharset, TranslateCharsetInfo


GetTextColor

The GetTextColor function retrieves the current text color for the specified device context.

COLORREF GetTextColor(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Values

If the function succeeds, the return value is the current text color as a COLORREF value.

If the function fails, the return value is CLR_INVALID.

Remarks

The text color defines the foreground color of characters drawn by using the TextOut or ExtTextOut function.

See Also

ExtTextOut, SetTextColor, TextOut


GetTextExtentExPoint

The GetTextExtentExPoint function retrieves the number of characters in a specified string that will fit within a specified space and fills an array with the text extent for each of those characters. (A text extent is the distance between the beginning of the space and a character that will fit in the space.) This information is useful for word-wrapping calculations.

BOOL GetTextExtentExPoint(

HDC hdc,	// handle of device context
LPCTSTR lpszStr,	// address of character string
int cchString,	// number of characters in string
int nMaxExtent,	// maximum width for formatted string
LPINT lpnFit,	// address of value specifying max. number of chars.
LPINT alpDx,	// address of array for partial string widths
LPSIZE lpSize	// address of structure with string dimensions
);
Parameters

hdc

Identifies the device context.

lpszStr

Points to the null-terminated string for which extents are to be retrieved.

cchString

Specifies the number of bytes in the string pointed to by the lpszStr parameter.

nMaxExtent

Specifies the maximum allowable width, in logical units, of the formatted string.

lpnFit

Points to an integer to receive a count of the maximum number of characters that will fit in the space specified by the nMaxExtent parameter. When the lpnFit parameter is NULL, the nMaxExtent parameter is ignored.

alpDx

Points to an array of integers to receive partial string extents. Each element in the array gives the distance, in logical units, between the beginning of the string and one of the characters that fits in the space specified by the nMaxExtent parameter. Although this array should have at least as many elements as characters specified by the cchString parameter, the function fills the array with extents only for as many characters as are given by the lpnFit parameter. If alpDx is NULL, the function does not compute partial string widths.

lpSize

Points to a SIZE structure that contains the dimensions of the string, in logical units when the function returns. This value cannot be NULL.

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.

Remarks

If both the lpnFit and alpDx parameters are NULL, calling the GetTextExtentExPoint function is equivalent to calling the GetTextExtentPoint function.

See Also

GetTextExtentPoint, SIZE


GetTextExtentPoint

The GetTextExtentPoint function computes the width and height of the specified string of text.

GetTextExtentPoint is provided for compatibility with 16-bit versions of Windows. Win32-based applications should call the GetTextExtentPoint32 function, which provides more accurate results.

BOOL GetTextExtentPoint(

HDC hdc,	// handle of device context
LPCTSTR lpString,	// address of text string
int cbString,	// number of characters in string
LPSIZE lpSize	// address of structure for string size
);
Parameters

hdc

Identifies the device context.

lpString

Points to the string of text. The string does not need to be zero-terminated, since cbString specifies the length of the string.

cbString

Specifies the number of characters in the string.

lpSize

Points to a SIZE structure in which the dimensions of the string are to be returned.

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.

Remarks

The GetTextExtentPoint function uses the currently selected font to compute the dimensions of the string. The width and height, in logical units, are computed without considering any clipping.

Because some devices kern characters, the sum of the extents of the characters in a string may not be equal to the extent of the string.

The calculated string width takes into account the intercharacter spacing set by the SetTextCharacterExtra function.

See Also

GetTextExtentPoint32, SetTextCharacterExtra, SIZE


GetTextExtentPoint32

The GetTextExtentPoint32 function computes the width and height of the specified string of text. This function supersedes the GetTextExtentPoint function.

BOOL GetTextExtentPoint32(

HDC hdc,	// handle of device context
LPCTSTR lpString,	// address of text string
int cbString,	// number of characters in string
LPSIZE lpSize	// address of structure for string size
);
Parameters

hdc

Identifies the device context.

lpString

Points to the string of text. The string does not need to be zero-terminated, since cbString specifies the length of the string.

cbString

Specifies the number of characters in the string.

lpSize

Points to a SIZE structure in which the dimensions of the string are to be returned.

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.

Remarks

The GetTextExtentPoint32 function uses the currently selected font to compute the dimensions of the string. The width and height, in logical units, are computed without considering any clipping.

Because some devices kern characters, the sum of the extents of the characters in a string may not be equal to the extent of the string.

The calculated string width takes into account the intercharacter spacing set by the SetTextCharacterExtra function.

See Also

GetTextExtentPoint, SetTextCharacterExtra, SIZE


GetTextFace

The GetTextFace function retrieves the typeface name of the font that is selected into the specified device context.

int GetTextFace(

HDC hdc,	// handle of device context
int nCount,	// length of buffer receiving typeface name
LPTSTR lpFaceName	// address of buffer receiving typeface name
);
Parameters

hdc

Identifies the device context.

nCount

Specifies the size, in characters, of the buffer.

lpFaceName

Points to the buffer that is to receive the typeface name. If this parameter is NULL, the function returns the number of characters in the name, including the terminating null character.

Return Values

If the function succeeds, the return value is the number of characters copied to the buffer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The typeface name is copied as a null-terminated character string.

If the name is longer than the number of characters specified by the nCount parameter, the name is truncated.

See Also

GetTextAlign, GetTextColor, GetTextExtentPoint32, GetTextMetrics


GetTextMetrics

The GetTextMetrics function fills the specified buffer with the metrics for the currently selected font.

BOOL GetTextMetrics(

HDC hdc,	// handle of device context
LPTEXTMETRIC lptm	// address of text metrics structure
);
Parameters

hdc

Identifies the device context.

lptm

Points to the TEXTMETRIC structure that is to receive the metrics.

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.

See Also

GetTextAlign, GetTextExtentPoint32, GetTextFace, SetTextJustification, TEXTMETRIC


GetThreadContext

The GetThreadContext function retrieves the context of the specified thread.

BOOL GetThreadContext(

HANDLE hThread,	// handle of thread with context
LPCONTEXT lpContext	// address of context structure
);
Parameters

hThread

Identifies an open handle of a thread whose context is to be retrieved.

Windows NT: The handle must have THREAD_GET_CONTEXT access to the thread. For more information, see Thread Objects.

lpContext

Points to the address of a CONTEXT structure that receives the appropriate context of the specified thread. The value of the ContextFlags member of this structure specifies which portions of a thread’s context are retrieved. The CONTEXT structure is highly computer specific. Currently, there are CONTEXT structures defined for Intel, MIPS, Alpha, and PowerPC processors. Refer to the header file WINNT.H for definitions of these structures.

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.

Remarks

The GetThreadContext function is used to retrieve the context of the specified thread. The function allows a selective context to be retrieved based on the value of the ContextFlags member of the CONTEXT structure. The thread handle identified by the hThread parameter is typically being debugged, but the function can also operate when it is not being debugged.

You cannot get a valid context for a running thread. Use the SuspendThread function to suspend the thread before calling GetThreadContext.

See Also

CONTEXT, SetThreadContext, SuspendThread


GetThreadDesktop

The GetThreadDesktop function returns a handle to the desktop associated with a specified thread.

HDESK GetThreadDesktop(

DWORD dwThreadId	// thread identifier
);
Parameters

dwThreadId

Identifies the thread for which to return the desktop handle. The GetCurrentThreadId and CreateProcess functions return thread identifiers.

Return Values

If the function succeeds, the return value is the handle of the desktop associated with the specified thread.

Remarks

The system associates a desktop with a thread when that thread is created. A thread can use the SetThreadDesktop function to change its desktop. The desktop associated with a thread must be on the window station associated with the thread’s process.

The calling process can use the returned handle in calls to the GetUserObjectInformation, GetUserObjectSecurity, SetUserObjectInformation, and SetUserObjectSecurity functions.

Windows 95: Windows 95 does not support multiple desktops, so GetThreadDesktop always returns the same value.

See Also

GetCurrentThreadId, GetProcessWindowStation, GetUserObjectInformation, GetUserObjectSecurity, SetProcessWindowStation, SetThreadDesktop, SetUserObjectInformation, SetUserObjectSecurity


GetThreadLocale

The GetThreadLocale function returns the calling thread’s current locale.

LCID GetThreadLocale(VOID)

Parameters

This function has no parameters.

Return Values

The function returns the calling thread’s 32-bit LCID locale identifier.

Remarks

When a thread is created, it is given the system default thread locale. The system reads the system default thread locale from the registry when the system boots. This system default can be modified for future process and thread creation using Control Panel’s International application.

See Also

SetThreadLocale, GetSystemDefaultLCID, GetUserDefaultLCID


GetThreadPriority

The GetThreadPriority function returns the priority value for the specified thread. This value, together with the priority class of the thread’s process, determines the thread’s base-priority level.

int GetThreadPriority(

HANDLE hThread	// handle to thread
);
Parameters

hThread

Identifies the thread.

Windows NT: The handle must have THREAD_QUERY_INFORMATION access. For more information, see Thread Objects.

Return Values

If the function succeeds, the return value is the thread’s priority level.

If the function fails, the return value is THREAD_PRIORITY_ERROR_RETURN. To get extended error information, call GetLastError.

The thread’s priority level is one of the following values:

Priority	Meaning
THREAD_PRIORITY_ABOVE_NORMAL
	Indicates 1 point above normal priority for the priority class.
THREAD_PRIORITY_BELOW_NORMAL
	Indicates 1 point below normal priority for the priority class.
THREAD_PRIORITY_HIGHEST
	Indicates 2 points above normal priority for the priority class.
THREAD_PRIORITY_IDLE
	Indicates a base-priority level of 1 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base-priority level of 16 for REALTIME_PRIORITY_CLASS processes.
THREAD_PRIORITY_LOWEST
	Indicates 2 points below normal priority for the priority class.
THREAD_PRIORITY_NORMAL
	Indicates normal priority for the priority class.
THREAD_PRIORITY_TIME_CRITICAL
	Indicates a base-priority level of 15 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base-priority level of 31 for REALTIME_PRIORITY_CLASS processes.
Remarks

Every thread has a base-priority level determined by the thread’s priority value and the priority class of its process. The operating system uses the base-priority level of all executable threads to determine which thread gets the next slice of CPU time. Threads are scheduled in a round-robin fashion at each priority level, and only when there are no executable threads at a higher level will scheduling of threads at a lower level take place.

For a table that shows the base-priority levels for each combination of priority class and thread priority value, refer to the SetPriorityClass function.

See Also

GetPriorityClass, SetPriorityClass, SetThreadPriority


GetThreadPriorityBoost [New - Windows NT]
GetThreadPriorityBoost

[New - Windows NT]

The GetThreadPriorityBoost function returns the priority boost control state of the specified thread.

BOOL GetThreadPriorityBoost(

HANDLE hThread,	// handle to thread
PBOOL pDisablePriorityBoost	// indicates priority boost control state
);
Parameters

hThread

Handle to the thread. This thread must have THREAD_QUERY_INFORMATION access. For more information, see Thread Objects.

pDisablePriorityBoost

Pointer to a Boolean variable that receives the priority boost control state. A value of TRUE indicates that dynamic boosting is disabled. A value of FALSE indicates normal behavior.

Return Values

If the function succeeds, the return value is nonzero. In that case, the Boolean variable pointed to by the pDisablePriorityBoost parameter receives the priority boost control state.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

SetThreadPriorityBoost


GetThreadSelectorEntry

The GetThreadSelectorEntry function retrieves a descriptor table entry for the specified selector and thread.

BOOL GetThreadSelectorEntry(

HANDLE hThread,	// handle of thread that contains selector
DWORD dwSelector,	// number of selector value to look up
LPLDT_ENTRY lpSelectorEntry	// address of selector entry structure
);
Parameters

hThread

Identifies a handle of the thread containing the specified selector.

Windows NT: The handle must have THREAD_QUERY_INFORMATION access. For more information, see Thread Objects.

dwSelector

Specifies the global or local selector value to look up in the thread’s descriptor tables.

lpSelectorEntry

Points to a structure that receives a copy of the descriptor table entry if the specified selector has an entry in the specified thread’s descriptor table. This information can be used to convert a segment-relative address to a linear virtual address.

Return Values

If the function succeeds, the return value is nonzero. In that case, the structure pointed to by the lpSelectorEntry parameter receives a copy of the specified descriptor table entry.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

GetThreadSelectorEntry is only functional on x86-based systems. For systems that are not x86-based, the function returns FALSE.

Debuggers use this function to convert segment-relative addresses to linear virtual addresses. The ReadProcessMemory and WriteProcessMemory functions use linear virtual addresses.

See Also

ReadProcessMemory, WriteProcessMemory


GetThreadTimes

The GetThreadTimes function obtains timing information about a specified thread.

BOOL GetThreadTimes(

HANDLE hThread,	// specifies the thread of interest
LPFILETIME lpCreationTime,	// when the thread was created
LPFILETIME lpExitTime,	// when the thread was destroyed
LPFILETIME lpKernelTime,	// time the thread has spent in kernel mode
LPFILETIME lpUserTime	// time the thread has spent in user mode
);
Parameters

hThread

An open handle that specifies the thread whose timing information is sought. This handle must be created with THREAD_QUERY_INFORMATION access. For more information, see Thread Objects.

lpCreationTime

Points to a FILETIME structure that receives the creation time of the thread.

lpExitTime

Points to a FILETIME structure that receives the exit time of the thread. If the thread has not exited, the content of this structure is undefined.

lpKernelTime

Points to a FILETIME structure that receives the amount of time that the thread has executed in kernel mode.

lpUserTime

Points to a FILETIME structure that receives the amount of time that the thread has executed in user mode.

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.

Remarks

All times are expressed using FILETIME data structures. Such a structure contains two 32-bit values that combine to form a 64-bit count of 100-nanosecond time units.

Thread creation and exit times are points in time expressed as the amount of time that has elapsed since midnight on January 1, 1601 at Greenwich, England. The Win32 API provides several functions that an application can use to convert such values to more generally useful forms; see Time and Date Functions, and the functions noted in the following See Also section.

Thread kernel mode and user mode times are amounts of time. For example, if a thread has spent one second in kernel mode, this function will fill the FILETIME structure specified by lpKernelTime with a 64-bit value of ten million. That is the number of 100-nanosecond units in one second.

See Also

FILETIME, FileTimeToDosDateTime, FileTimeToLocalFileTime, FileTimeToSystemTime


GetTickCount

The GetTickCount function retrieves the number of milliseconds that have elapsed since Windows was started.

DWORD GetTickCount(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the number of milliseconds that have elapsed since Windows was started.

Remarks

The elapsed time is stored as a DWORD value. Therefore, the time will wrap around to zero if Windows is run continuously for 49.7 days.

Windows NT: To obtain the time elapsed since the computer was started, look up the System Up Time counter in the performance data in the registry key HKEY_PERFORMANCE_DATA. The value returned is an 8 byte value.


GetTimeFormat

The GetTimeFormat function formats a time as a time string for a specified locale. The function formats either a specified time or the local system time.

int GetTimeFormat(

LCID Locale,	// locale for which time is to be formatted
DWORD dwFlags,	// flags specifying function options
CONST SYSTEMTIME *lpTime,	// time to be formatted
LPCTSTR lpFormat,	// time format string
LPTSTR lpTimeStr,	// buffer for storing formatted string
int cchTime	// size, in bytes or characters, of the buffer
);
Parameters

Locale

Specifies the locale for which the time string is to be formatted. If lpFormat is NULL, the function formats the string according to the time format for this locale. If lpFormat is not NULL, the function uses the locale only for information not specified in the format picture string (for example, the locale’s time markers).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
dwFlags

A set of bit flags that specify various function options. You can specify a combination of the following flags:

Flag	Meaning
LOCALE_NOUSEROVERRIDE	If set, the function formats the string using the system default time format for the specified locale. If not set, the function formats the string using any user overrides to the locale’s default time format. This flag cannot be set if lpFormat is non-NULL.
TIME_NOMINUTESORSECONDS	Do not use minutes or seconds.
TIME_NOSECONDS	Do not use seconds.
TIME_NOTIMEMARKER	Do not use a time marker.
TIME_FORCE24HOURFORMAT	Always use a 24-hour time format.
lpTime

Pointer to a SYSTEMTIME structure that contains the time information to be formatted. If this pointer is NULL, the function uses the current local system time.

lpFormat

Pointer to a format picture to use to form the time string. If lpFormat is NULL, the function uses the time format of the specified locale.

Use the following elements to construct a format picture string. If you use spaces to separate the elements in the format string, these spaces will appear in the same location in the output string. The letters must be in uppercase or lowercase as shown (for example, “ss”, not “SS”). Characters in the format string that are enclosed in single quotation marks will appear in the same location and unchanged in the output string.

Picture	Meaning
h	Hours with no leading zero for single-digit hours; 12-hour clock
hh	Hours with leading zero for single-digit hours; 12-hour clock
H	Hours with no leading zero for single-digit hours; 24-hour clock
HH	Hours with leading zero for single-digit hours; 24-hour clock
m	Minutes with no leading zero for single-digit minutes
mm	Minutes with leading zero for single-digit minutes
s	Seconds with no leading zero for single-digit seconds
ss	Seconds with leading zero for single-digit seconds
t	One character time marker string, such as A or P
tt	Multicharacter time marker string, such as AM or PM
For example, to get the time string

“11:29:40 PM”

use the following picture string:

“hh':'mm':'ss tt”

lpTimeStr

Pointer to a buffer that receives the formatted time string.

cchTime

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the lpTimeStr buffer. If cchTime is zero, the function returns the number of bytes or characters required to hold the formatted time string, and the buffer pointed to by lpTimeStr is not used.

Return Values

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) written to the buffer pointed to by lpTimeStr. If the cchTime parameter is zero, the return value is the number of bytes or characters required to hold the formatted time string.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

Remarks

If a time marker exists and the TIME_NOTIMEMARKER flag is not set, the function localizes the time marker based on the specified locale identifier. Examples of time markers are “AM” and “PM” for US English.

The time values in the SYSTEMTIME structure pointed to by lpTime must be valid. The function checks each of the time values to determine that it is within the appropriate range of values. If any of the time values are outside the correct range, the function fails, and sets the last-error to ERROR_INVALID_PARAMETER.

The function ignores the date portions of the SYSTEMTIME structure pointed to by lpTime: wYear, wMonth, wDayOfWeek, and wDay.

If TIME_NOMINUTESORSECONDS or TIME_NOSECONDS is specified, the function removes the separator(s) preceding the minutes and/or seconds element(s).

If TIME_NOTIMEMARKER is specified, the function removes the separator(s) preceding and following the time marker.

If TIME_FORCE24HOURFORMAT is specified, the function displays any existing time marker, unless the TIME_NOTIMEMARKER flag is also set.

The function does not include milliseconds as part of the formatted time string.

To use the LOCALE_NOUSEROVERRIDE flag, lpFormat must be NULL.

No errors are returned for a bad format string. The function simply forms the best time string that it can. If more than two hour, minute, second, or time marker format pictures are passed in, then the function defaults to two. For example, the only time marker pictures that are valid are L”t” and L”tt” (the ‘L’ indicates a Unicode (16-bit characters) string). If L”ttt” is passed in, the function assumes L”tt”.

See Also

GetDateFormat, SYSTEMTIME


GetTimeZoneInformation

The GetTimeZoneInformation function retrieves the current time-zone parameters. These parameters control the translations between Coordinated Universal Time (UTC) and local time.

DWORD GetTimeZoneInformation(

LPTIME_ZONE_INFORMATION lpTimeZoneInformation	// address of time-zone settings
);
Parameters

lpTimeZoneInformation

Points to a TIME_ZONE_INFORMATION structure to receive the current time-zone parameters.

Return Values

If the function succeeds, the return value is one of the following values:

Value	Meaning
TIME_ZONE_ID_UNKNOWN	The operating system cannot determine the current time zone. This is usually because a previous call to the SetTimeZoneInformation function supplied only the bias (and no transition dates).
TIME_ZONE_ID_STANDARD	The operating system is operating in the range covered by the StandardDate member of the structure pointed to by the lpTimeZoneInformation parameter.
TIME_ZONE_ID_DAYLIGHT	The operating system is operating in the range covered by the DaylightDate member of the structure pointed to by the lpTimeZoneInformation parameter.
If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

Remarks

All translations between UTC time and local time are based on the following formula:

UTC = local time + bias

The bias is the difference, in minutes, between UTC time and local time.

See Also

SetTimeZoneInformation, TIME_ZONE_INFORMATION


GetTokenInformation

The GetTokenInformation function retrieves a specified type of information about an access token. The calling process must have appropriate access rights to obtain the information.

BOOL GetTokenInformation(

HANDLE TokenHandle,	// handle of access token
TOKEN_INFORMATION_CLASS TokenInformationClass,	// type of information to retrieve
LPVOID TokenInformation,	// address of retrieved information
DWORD TokenInformationLength,	// size of information buffer
PDWORD ReturnLength	// address of required buffer size
);
Parameters

TokenHandle

Identifies an access token from which information is retrieved.

TokenInformationClass

Specifies a variable of the TOKEN_INFORMATION_CLASS enumerated type identifying the type of information the function retrieves.

TokenInformation

Points to a buffer the function fills with the requested information. The structure put into this buffer depends upon the type of information specified by the TokenInformationClass parameter, as shown in the following list:

Token Information Class	Structure Returned
TokenUser	TOKEN_USER structure. TOKEN_QUERY access is needed to retrieve this information.
TokenGroups	TOKEN_GROUPS structure. TOKEN_QUERY access is needed to retrieve this information.
TokenPrivileges	TOKEN_PRIVILEGES structure. TOKEN_QUERY access is needed to retrieve this information.
TokenOwner	TOKEN_OWNER structure. TOKEN_QUERY access is needed to retrieve this information.
TokenPrimaryGroup	TOKEN_PRIMARY_GROUP structure. TOKEN_QUERY access is needed to retrieve this information.
TokenDefaultDacl	TOKEN_DEFAULT_DACL structure. TOKEN_QUERY access is needed to retrieve this information.
TokenSource	TOKEN_SOURCE structure. TOKEN_QUERY_SOURCE access is needed to retrieve this information.
TokenType	TOKEN_TYPE enumerated type. TOKEN_QUERY access is needed to retrieve this information.
TokenImpersonationLevel	SECURITY_IMPERSONATION_LEVEL enumerated type. TOKEN_QUERY access is needed to retrieve this information about a token. If the access token is not an impersonation token, the function fails.
TokenStatistics	TOKEN_STATISTICS structure. TOKEN_QUERY access is needed to retrieve this information.
The formats for the retrieved structures and enumerated types are listed in the following Remarks section.

TokenInformationLength

Specifies the size, in bytes, of the buffer pointed to by the TokenInformation parameter.

ReturnLength

Points to a variable receiving the actual number of bytes needed for the buffer pointed to by the TokenInformation parameter. If this value is larger than the value specified in the TokenInformationLength parameter, the function fails and stores no data in the buffer.

If the value of the TokenInformationClass parameter is TokenDefaultDacl and the token has no default access-control list, the function sets the variable pointed to by ReturnLength to zero and stores no data in the buffer.

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.

See Also

AdjustTokenGroups, AdjustTokenPrivileges, OpenProcessToken, OpenThreadToken, SetTokenInformation, SECURITY_IMPERSONATION_LEVEL, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


GetTopWindow

The GetTopWindow function examines the Z order of the child windows associated with the specified parent window and retrieves the handle of the child window at the top of the Z order.

HWND GetTopWindow(

HWND hWnd	// handle of parent window
);
Parameters

hWnd

Identifies the parent window whose child windows are to be examined. If this parameter is NULL, the function returns a handle of the window at the top of the Z order.

Return Values

If the function succeeds, the return value is the handle of the child window at the top of the Z order. If the specified window has no child windows, the return value is NULL. To get extended error information, use the GetLastError function.

See Also

GetNextWindow, GetWindow


GetTrusteeForm [New - Windows NT]
GetTrusteeForm

[New - Windows NT]

The GetTrusteeForm function retrieves the value assigned to the TrusteeForm member of a specified TRUSTEE structure. This value indicates whether the structure uses a name string or a security identifier (SID) to identify the trustee.

TRUSTEE_FORM GetTrusteeForm(

PTRUSTEE pTrustee	// pointer to a TRUSTEE structure
);
Parameters

pTrustee

Pointer to a TRUSTEE structure.

Return Values

The return value is one of the constants from the TRUSTEE_FORM enumeration.

See Also

GetTrusteeName, GetTrusteeType, TRUSTEE, TRUSTEE_FORM


GetTrusteeName [New - Windows NT]
GetTrusteeName

[New - Windows NT]

The GetTrusteeName function retrieves the trustee name from a TRUSTEE structure.

LPTSTR GetTrusteeName(

PTRUSTEE pTrustee	// pointer to a TRUSTEE structure
);
Parameters

pTrustee

Pointer to a TRUSTEE structure.

Return Values

If the TrusteeForm member of the TRUSTEE structure is TRUSTEE_IS_NAME, the return value is the pointer assigned to the ptstrName member of the structure.

If the TrusteeForm member is TRUSTEE_IS_SID, the return value is NULL. The function does not look up the name associated with a security identifier (SID).

Remarks

The GetTrusteeName function does not allocate any memory.

See Also

TRUSTEE, SID


GetTrusteeType [New - Windows NT]
GetTrusteeType

[New - Windows NT]

The GetTrusteeType function retrieves the value assigned to the TrusteeType member of a specified TRUSTEE structure. This value indicates whether the trustee is a user, a group, or the trustee type is unknown.

TRUSTEE_TYPE GetTrusteeType(

PTRUSTEE pTrustee	// pointer to the TRUSTEE structure
);
Parameters

pTrustee

Pointer to a TRUSTEE structure.

Return Values

The return value is one of the constants from the TRUSTEE_TYPE enumeration.

See Also

TRUSTEE, TRUSTEE_TYPE


GetUpdateRect

The GetUpdateRect function retrieves the coordinates of the smallest rectangle that completely encloses the update region of the specified window. If the window was created with the CS_OWNDC style and the mapping mode is not MM_TEXT, GetUpdateRect retrieves the rectangle in logical coordinates. Otherwise, it retrieves the rectangle in client coordinates. If there is no update region, GetUpdateRect retrieves an empty rectangle (sets all coordinates to zero).

BOOL GetUpdateRect(

HWND hWnd,	// handle of window
LPRECT lpRect,	// address of update rectangle coordinates
BOOL bErase	// erase flag
);
Parameters

hWnd

Identifies the window with an update region that is to be retrieved.

lpRect

Points to the RECT structure that receives the coordinates of the enclosing rectangle.

An application can set this parameter to NULL to determine whether an update region exists for the window. If this parameter is NULL, GetUpdateRect returns nonzero if an update region exists, and zero if one does not. This provides a simple and efficient means of determining whether a WM_PAINT message resulted from an invalid area.

bErase

Specifies whether the background in the update region is to be erased. If this parameter is TRUE and the update region is not empty, GetUpdateRect sends a WM_ERASEBKGND message to the specified window to erase the background.

Return Values

If the update region is not empty, the return value is nonzero.

If there is no update region, the return value is zero.

Remarks

The update rectangle retrieved by the BeginPaint function is identical to that retrieved by GetUpdateRect.

BeginPaint automatically validates the update region, so any call to GetUpdateRect made immediately after the call to BeginPaint retrieves an empty update region.

See Also

BeginPaint, GetUpdateRgn, InvalidateRect, RECT, UpdateWindow, ValidateRect


GetUpdateRgn

The GetUpdateRgn function retrieves the update region of a window by copying it into the specified region. The coordinates of the update region are relative to the upper-left corner of the window (that is, they are client coordinates).

int GetUpdateRgn(

HWND hWnd,	// handle of window
HRGN hRgn,	// handle of region
BOOL bErase	// erase background flag
);
Parameters

hWnd

Identifies the window with an update region that is to be retrieved.

hRgn

Identifies the region to receive the update region.

bErase

Specifies whether the window background should be erased and whether nonclient areas of child windows should be drawn. If this parameter is FALSE, no drawing is done.

Return Values

The return value indicates the complexity of the resulting region; it can be one of the following values:

Value	Meaning
COMPLEXREGION	Region consists of more than one rectangle.
ERROR	An error occurred.
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
Remarks

The BeginPaint function automatically validates the update region, so any call to GetUpdateRgn made immediately after the call to BeginPaint retrieves an empty update region.

See Also

GetUpdateRect, InvalidateRgn, UpdateWindow, ValidateRgn


GetUserDefaultLangID

The GetUserDefaultLangID function retrieves the user default language identifier.

LANGID GetUserDefaultLangID(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the user default language identifier.

See Also

GetSystemDefaultLangID, MAKELANGID


GetUserDefaultLCID

The GetUserDefaultLCID function retrieves the user default locale identifier.

LCID GetUserDefaultLCID(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is the user default locale identifier.

Remarks

For more information about locale identifiers, see Locale Identifiers.

See Also

GetLocaleInfo, GetSystemDefaultLCID, MAKELCID


GetUserName

The GetUserName function retrieves the user name of the current thread. This is the name of the user currently logged onto the system.

BOOL GetUserName(

LPTSTR lpBuffer,	// address of name buffer
LPDWORD nSize	// address of size of name buffer
);
Parameters

lpBuffer

Points to the buffer to receive the null-terminated string containing the user’s logon name. If this buffer is not large enough to contain the entire user name, the function fails.

nSize

Pointer to a DWORD that, on input, specifies the maximum size, in characters, of the buffer specified by the lpBuffer parameter. If this buffer is not large enough to contain the entire user name, the function fails. If the function succeeds, it will place the number of characters copied to the buffer into the DWORD that nSize points to.

Return Values

If the function succeeds, the return value is nonzero, and the variable pointed to by nSize contains the number of characters copied to the buffer specified by lpBuffer, including the terminating null character.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If the current thread is impersonating another client, the GetUserName function returns the user name of the client that the thread is impersonating.

See Also

LookupAccountName


GetUserObjectInformation

The GetUserObjectInformation function returns information about a window station or desktop object.

BOOL GetUserObjectInformation(

HANDLE hObj,	// handle of object to get information for
int nIndex,	// type of information to get
PVOID pvInfo,	// points to buffer that receives the information
DWORD nLength,	// size, in bytes, of pvInfo buffer
LPDWORD lpnLengthNeeded	// receives required size, in bytes, of pvInfo buffer
);
Parameters

hObj

Identifies the window station or desktop object for which to return information. This can be an HDESK or HWINSTA handle (for example, a handle returned by CreateWindowStation, OpenWindowStation, CreateDesktop, or OpenDesktop).

nIndex

Specifies the object information to be retrieved. The parameter must be one of the following values:

Value	Description
UOI_FLAGS	Returns handle flags. The pvInfo parameter must point to a USEROBJECTFLAGS structure.
UOI_NAME	Returns a string containing the name of the object.
UOI_TYPE	Returns a string containing the type name of the object.
pvInfo

Points to a buffer to receive the object information.

nLength

Specifies the size, in bytes, of the buffer pointed to by the pvInfo parameter.

lpnLengthNeeded

Points to a variable receiving the number of bytes required to store the requested information. If this variable’s value is greater than the value of the nLength parameter when the function returns, the function returns FALSE, and none of the information is copied to the pvInfo buffer. If the value of the variable pointed to by lpnLengthNeeded is less than or equal to the value of nLength, the entire information block is copied.

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.

See Also

CreateDesktop, CreateWindowStation, GetUserObjectSecurity, OpenDesktop, OpenWindowStation, SetUserObjectInformation, SetUserObjectSecurity, USEROBJECTFLAGS


GetUserObjectSecurity

The GetUserObjectSecurity function retrieves security information for the specified user object.

BOOL GetUserObjectSecurity(

HANDLE hObj,	// handle of user object
PSECURITY_INFORMATION pSIRequested,	// address of requested security information
PSECURITY_DESCRIPTOR pSID,	// address of security descriptor
DWORD nLength,	// size of buffer for security descriptor
LPDWORD lpnLengthNeeded	// address of required size of buffer
);
Parameters

hObj

Identifies the user object for which to return security information.

pSIRequested

Points to a SECURITY_INFORMATION structure specifying the security information being requested.

pSID

Points to a SECURITY_DESCRIPTOR structure in self-relative format that contains the requested information when the function returns.

nLength

Specifies the length, in bytes, of the buffer pointed to by the pSID parameter.

lpnLengthNeeded

Points to a variable receiving the number of bytes required to store the complete security descriptor. If this variable’s value is greater than the value of the nLength parameter when the function returns, the function returns FALSE and none of the security descriptor is copied to the buffer. Otherwise, the entire security descriptor is copied.

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.

See Also

CreatePrivateObjectSecurity, GetKernelObjectSecurity, GetPrivateObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetUserObjectSecurity


GetVersion

The GetVersion function returns the current version number of Windows and information about the operating system platform.

This function has been superseded by GetVersionEx, which is the preferred method for obtaining system version number information. New applications should use GetVersionEx. The GetVersionEx function was developed because many existing Windows applications err when examining the DWORD return value of a GetVersion function call, transposing the major and minor version numbers packed into that DWORD. The GetVersionEx function forces applications to explicitly examine each element of version information, and allows for future enhancements to that information.

DWORD GetVersion(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is a DWORD value that contains the major and minor version numbers of Windows in the low order word, and information about the operating system platform in the high order word.

For all platforms, the low order word contains the version number of Windows. The low-order byte of this word specifies the major version number, in hexadecimal notation. The high-order byte specifies the minor version (revision) number, in hexadecimal notation.

To distinguish between operating system platforms, use the high order bit and the low order byte, as shown in the following table:

Platform	High order bit	Low order byte (major version number)
Windows NT	zero	3 or 4
Windows 95	1	4
Win32s with Windows 3.1	1	3
For Windows NT and Win32s, the remaining bits in the high order word specify the build number.

For Windows 95 the remaining bits of the high order word are reserved.

Remarks

This function does not return the current version number of MS-DOS.

The following code fragment illustrates how to extract information from the GetVersion return value:

dwVersion = GetVersion();

// Get major and minor version numbers of Windows

dwWindowsMajorVersion =  (DWORD)(LOBYTE(LOWORD(dwVersion)));

dwWindowsMinorVersion =  (DWORD)(HIBYTE(LOWORD(dwVersion)));

// Get build numbers for Windows NT or Win32s

if (dwVersion < 0x80000000)                // Windows NT

    dwBuild = (DWORD)(HIWORD(dwVersion));

else if (dwWindowsMajorVersion < 4)        // Win32s

    dwBuild = (DWORD)(HIWORD(dwVersion) & ~0x8000);

else         // Windows 95 -- No build numbers provided

    dwBuild =  0;

See Also

GetVersionEx


GetVersionEx

The GetVersionEx function obtains extended information about the version of the operating system that is currently running.

BOOL GetVersionEx(

LPOSVERSIONINFO lpVersionInformation	// pointer to version information structure
);
Parameters

lpVersionInformation

Pointer to an OSVERSIONINFO data structure that the function fills with operating system version information.

Before calling the GetVersionEx function, set the dwOSVersionInfoSize member of the OSVERSIONINFO data structure to sizeof(OSVERSIONINFO).

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. The function fails if you specify an invalid value for the dwOSVersionInfoSize member of the OSVERSIONINFO structure.

Remarks

The GetVersionEx function supersedes the GetVersion function and is the preferred method for obtaining operating system version number information. New applications should use the GetVersionEx function rather than the GetVersion function.

See Also

OSVERSIONINFO


GetViewportExtEx

The GetViewportExtEx function retrieves the x-extents and y-extents of the current viewport for the specified device context.

BOOL GetViewportExtEx(

HDC hdc,	// handle of device context
LPSIZE lpSize	// address of structure receiving viewport dimensions
);
Parameters

hdc

Identifies the device context.

lpSize

Points to a SIZE structure. The x- and y-extents, in device units, are placed in this structure.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

GetWindowExtEx, SetViewportExtEx, SetWindowExtEx


GetViewportOrgEx

The GetViewportOrgEx function retrieves the x-coordinates and y-coordinates of the viewport origin for the specified device context.

BOOL GetViewportOrgEx(

HDC hdc,	// handle of device context
LPPOINT lpPoint	// address of structure receiving the viewport origin
);
Parameters

hdc

Identifies the device context.

lpPoint

Points to a POINT structure that receives the origin coordinates.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

GetWindowOrgEx, POINT, SetViewportOrgEx, SetWindowOrgEx


GetVolumeInformation

The GetVolumeInformation function returns information about a file system and volume whose root directory is specified.

BOOL GetVolumeInformation(

LPCTSTR lpRootPathName,	// address of root directory of the file system
LPTSTR lpVolumeNameBuffer,	// address of name of the volume
DWORD nVolumeNameSize,	// length of lpVolumeNameBuffer
LPDWORD lpVolumeSerialNumber,	// address of volume serial number
LPDWORD lpMaximumComponentLength,	// address of system’s maximum filename length
LPDWORD lpFileSystemFlags,	// address of file system flags
LPTSTR lpFileSystemNameBuffer,	// address of name of file system
DWORD nFileSystemNameSize	// length of lpFileSystemNameBuffer
);
Parameters

lpRootPathName

Points to a string that contains the root directory of the volume to be described. If this parameter is NULL, the root of the current directory is used. If this parameter is a UNC name, you must follow it with an additional backslash. For example, you would specify \\MyServer\MyShare as \\MyServer\MyShare\.

lpVolumeNameBuffer

Points to a buffer that receives the name of the specified volume.

nVolumeNameSize

Specifies the length, in characters, of the volume name buffer. This parameter is ignored if the volume name buffer is not supplied.

lpVolumeSerialNumber

Points to a variable that receives the volume serial number. This parameter can be NULL if the serial number is not required.

lpMaximumComponentLength

Points to a doubleword value that receives the maximum length, in characters, of a filename component supported by the specified file system. A filename component is that portion of a filename between backslashes.

The value stored in variable pointed to by *lpMaximumComponentLength is used to indicate that long names are supported by the specified file system. For example, for a FAT file system supporting long names, the function stores the value 255, rather than the previous 8.3 indicator. Long names can also be supported on systems that use the New Technology file system.

lpFileSystemFlags

Points to a doubleword that receives flags associated with the specified file system. This parameter can be any combination of the following flags, with one exception: FS_FILE_COMPRESSION and FS_VOL_IS_COMPRESSED are mutually exclusive.

Value	Meaning
FS_CASE_IS_PRESERVED	If this flag is set, the file system preserves the case of filenames when it places a name on disk.
FS_CASE_SENSITIVE	If this flag is set, the file system supports case-sensitive filenames.
FS_UNICODE_STORED_ON_DISK	If this flag is set, the file system supports Unicode in filenames as they appear on disk.
FS_PERSISTENT_ACLS	If this flag is set, the file system preserves and enforces ACLs. For example, NTFS preserves and enforces ACLs, and FAT does not.
FS_FILE_COMPRESSION	The file system supports file-based compression.
FS_VOL_IS_COMPRESSED	The specified volume is a compressed volume; for example, a DoubleSpace volume.
lpFileSystemNameBuffer

Points to a buffer that receives the name of the file system (such as FAT or NTFS).

nFileSystemNameSize

Specifies the length, in characters, of the file system name buffer. This parameter is ignored if the file system name buffer is not supplied.

Return Values

If all the requested information is retrieved, the return value is nonzero.

If not all the requested information is retrieved, the return value is zero. To get extended error information, call GetLastError.

Remarks

If you are attempting to obtain information about a floppy drive that does not have a floppy disk or a CD-ROM drive that does not have a compact disc, the system displays a message box asking the user to insert a floppy disk or a compact disc, respectively. To prevent the system from displaying this message box, call the SetErrorMode function with SEM_FAILCRITICALERRORS.

The FS_VOL_IS_COMPRESSED flag is the only indicator of volume-based compression. The file system name is not altered to indicate compression. This flag comes back set on a DoubleSpace volume, for example. With volume-based compression, an entire volume is either compressed or not compressed.

The FS_FILE_COMPRESSION flag indicates whether a file system supports file-based compression. With file-based compression, individual files can be compressed or not compressed.

The FS_FILE_COMPRESSION and FS_VOL_IS_COMPRESSED flags are mutually exclusive; both bits cannot come back set.

The maximum component length value, stored in the DWORD variable pointed to by lpMaximumComponentLength, is the only indicator that a volume supports longer-than-normal FAT (or other file system) file names. The file system name is not altered to indicate support for long file names.

The GetCompressedFileSize function obtains the compressed size of a file. The GetFileAttributes function can determine whether an individual file is compressed.

See Also

GetCompressedFileSize, GetFileAttributes, SetErrorMode, SetVolumeLabel


GetWindow

The GetWindow function retrieves the handle of a window that has the specified relationship (Z order or owner) to the specified window.

HWND GetWindow(

HWND hWnd,	// handle of original window
UINT uCmd	// relationship flag
);
Parameters

hWnd

Identifies a window. The window handle retrieved is relative to this window, based on the value of the uCmd parameter.

uCmd

Specifies the relationship between the specified window and the window whose handle is to be retrieved. This parameter can be one of the following values:

Value	Meaning
GW_CHILD	The retrieved handle identifies the child window at the top of the Z order, if the specified window is a parent window; otherwise, the retrieved handle is NULL. The function examines only child windows of the specified window. It does not examine descendant windows.
GW_HWNDFIRST	The retrieved handle identifies the window of the same type that is highest in the Z order. If the specified window is a topmost window, the handle identifies the topmost window that is highest in the Z order. If the specified window is a top-level window, the handle identifies the top-level window that is highest in the Z order. If the specified window is a child window, the handle identifies the sibling window that is highest in the Z order.
GW_HWNDLAST	The retrieved handle identifies the window of the same type that is lowest in the Z order. If the specified window is a topmost window, the handle identifies the topmost window that is lowest in the Z order. If the specified window is a top-level window, the handle identifies the top-level window that is lowest in the Z order. If the specified window is a child window, the handle identifies the sibling window that is lowest in the Z order.
GW_HWNDNEXT	The retrieved handle identifies the window below the specified window in the Z order. If the specified window is a topmost window, the handle identifies the topmost window below the specified window. If the specified window is a top-level window, the handle identifies the top-level window below the specified window. If the specified window is a child window, the handle identifies the sibling window below the specified window.
GW_HWNDPREV	The retrieved handle identifies the window above the specified window in the Z order. If the specified window is a topmost window, the handle identifies the topmost window above the specified window. If the specified window is a top-level window, the handle identifies the top-level window above the specified window. If the specified window is a child window, the handle identifies the sibling window above the specified window.
GW_OWNER	The retrieved handle identifies the specified window’s owner window, if any.
Return Values

If the function succeeds, the return value is a window handle. If no window exists with the specified relationship to the specified window, the return value is NULL. To get extended error information, call GetLastError.

See Also

GetActiveWindow, GetNextWindow, GetTopWindow


GetWindowContextHelpId

The GetWindowContextHelpId function retrieves the help context identifier, if any, associated with the specified window.

DWORD GetWindowContextHelpId(

HWND hwnd
);
Parameters

hwnd

Handle to the window for which the help context identifier is to be retrieved.

Return Values

Returns the help context identifier if the window has one or zero otherwise.

See Also

SetWindowContextHelpId


GetWindowDC

The GetWindowDC function retrieves the device context (DC) for the entire window, including title bar, menus, and scroll bars. A window device context permits painting anywhere in a window, because the origin of the device context is the upper-left corner of the window instead of the client area.

GetWindowDC assigns default attributes to the window device context each time it retrieves the device context. Previous attributes are lost.

HDC GetWindowDC(

HWND hWnd	// handle of window
);
Parameters

hWnd

Identifies the window with a device context that is to be retrieved.

Return Values

If the function succeeds, the return value is the handle of a device context for the specified window.

If the function fails, the return value is NULL, indicating an error or an invalid hWnd parameter.

Remarks

GetWindowDC is intended for special painting effects within a window’s nonclient area. Painting in nonclient areas of any window is not recommended.

The GetSystemMetrics function can be used to retrieve the dimensions of various parts of the nonclient area, such as the title bar, menu, and scroll bars.

After painting is complete, the ReleaseDC function must be called to release the device context. Not releasing the window device context has serious effects on painting requested by applications.

See Also

BeginPaint, GetDC, GetSystemMetrics, ReleaseDC


GetWindowExtEx

This function retrieves the x-extents and y-extents of the window for the specified device context.

BOOL GetWindowExtEx(

HDC hdc,	// handle of device context
LPSIZE lpSize	// address of structure receiving window extents
);
Parameters

hdc

Identifies the device context.

lpSize

Points to a SIZE structure. The x- and y-extents in page-space units are placed in this structure.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

GetViewportExtEx, SetViewportExtEx, SetWindowExtEx


GetWindowLong

The GetWindowLong function retrieves information about the specified window. The function also retrieves the 32-bit (long) value at the specified offset into the extra window memory of a window.

LONG GetWindowLong(

HWND hWnd,	// handle of window
int nIndex	// offset of value to retrieve
);
Parameters

hWnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the zero-based offset to the value to be retrieved. Valid values are in the range zero through the number of bytes of extra window memory, minus four; for example, if you specified 12 or more bytes of extra memory, a value of 8 would be an index to the third 32-bit integer. To retrieve any other value, specify one of the following values:

Value	Action
GWL_EXSTYLE	Retrieves the extended window styles.
GWL_STYLE	Retrieves the window styles.
GWL_WNDPROC	Retrieves the address of the window procedure, or a handle representing the address of the window procedure. You must use the CallWindowProc function to call the window procedure.
GWL_HINSTANCE	Retrieves the handle of the application instance.
GWL_HWNDPARENT	Retrieves the handle of the parent window, if any.
GWL_ID	Retrieves the identifier of the window.
GWL_USERDATA	Retrieves the 32-bit value associated with the window. Each window has a corresponding 32-bit value intended for use by the application that created the window.
The following values are also available when the hWnd parameter identifies a dialog box:

Value	Action
DWL_DLGPROC	Retrieves the address of the dialog box procedure, or a handle representing the address of the dialog box procedure. You must use the CallWindowProc function to call the dialog box procedure.
DWL_MSGRESULT	Retrieves the return value of a message processed in the dialog box procedure.
DWL_USER	Retrieves extra information private to the application, such as handles or pointers.
Return Values

If the function succeeds, the return value is the requested 32-bit value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the WNDCLASS structure used with the RegisterClass function.

See Also

CallWindowProc, GetWindowWord, RegisterClass, SetParent, SetWindowLong, SetWindowWord, WNDCLASS


GetWindowOrgEx

The GetWindowOrgEx function retrieves the x-coordinates and y-coordinates of the window origin for the specified device context.

BOOL GetWindowOrgEx(

HDC hdc,	// handle of device context
LPPOINT lpPoint	// address of structure receiving the window origin
);
Parameters

hdc

Identifies the device context.

lpPoint

Points to a POINT structure that receives the coordinates, in page units, of the window origin.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

GetViewportOrgEx, SetViewportOrgEx, SetWindowOrgEx


GetWindowPlacement

The GetWindowPlacement function retrieves the show state and the restored, minimized, and maximized positions of the specified window.

BOOL GetWindowPlacement(

HWND hWnd,	// handle of window
WINDOWPLACEMENT *lpwndpl	// address of structure for position data
);
Parameters

hWnd

Identifies the window.

lpwndpl

Points to the WINDOWPLACEMENT structure that receives the show state and position information.

Before calling GetWindowPlacement, set the length member of the WINDOWPLACEMENT structure to sizeof(WINDOWPLACEMENT).

GetWindowPlacement fails if lpwndpl->length is not set correctly.

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.

Remarks

The flags member of WINDOWPLACEMENT retrieved by this function is always zero. If the window identified by the hWnd parameter is maximized, the showCmd member is SW_SHOWMAXIMIZED. If the window is minimized, showCmd is SW_SHOWMINIMIZED. Otherwise, it is SW_SHOWNORMAL.

The length member of WINDOWPLACEMENT must be set to sizeof(WINDOWPLACEMENT). If this member is not set correctly, the function returns FALSE.

See Also

SetWindowPlacement, WINDOWPLACEMENT


GetWindowRect

The GetWindowRect function retrieves the dimensions of the bounding rectangle of the specified window. The dimensions are given in screen coordinates that are relative to the upper-left corner of the screen.

BOOL GetWindowRect(

HWND hWnd,	// handle of window
LPRECT lpRect	// address of structure for window coordinates
);
Parameters

hWnd

Identifies the window.

lpRect

Points to a RECT structure that receives the screen coordinates of the upper-left and lower-right corners of the window.

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.

See Also

GetClientRect, RECT


GetWindowRgn

The GetWindowRgn function obtains a copy of the window region of a window. The window region of a window is set by calling the SetWindowRgn function. The window region determines the area within the window where the operating system permits drawing. The operating system does not display any portion of a window that lies outside of the window region

int GetWindowRgn(

HWND hWnd,	// handle to window whose window region is to be obtained
HRGN hRgn	// handle to region that receives a copy of the window region
);
Parameters

hWnd

Handle to the window whose window region is to be obtained.

hrgn

Handle to a region. This region receives a copy of the window region.

Return Values

The return value specifies the type of the region that the function obtains. It can be one of the following values:

Value	Meaning
NULLREGION	The region is empty.
SIMPLEREGION	The region is a single rectangle.
COMPLEXREGION	The region is more than one rectangle.
ERROR	An error occurred; the region is unaffected.
Comments

The coordinates of a window’s window region are relative to the upper-left corner of the window, not the client area of the window.

To set the window region of a window, call the SetWindowRgn function.

See Also

SetWindowRgn


GetWindowsDirectory

The GetWindowsDirectory function retrieves the path of the Windows directory. The Windows directory contains such files as Windows-based applications, initialization files, and Help files.

UINT GetWindowsDirectory(

LPTSTR lpBuffer,	// address of buffer for Windows directory
UINT uSize	// size of directory buffer
);
Parameters

lpBuffer

Points to the buffer to receive the null-terminated string containing the path. This path does not end with a backslash unless the Windows directory is the root directory. For example, if the Windows directory is named WINDOWS on drive C, the path of the Windows directory retrieved by this function is C:\WINDOWS. If Windows was installed in the root directory of drive C, the path retrieved is C:\.

uSize

Specifies the maximum size, in characters, of the buffer specified by the lpBuffer parameter. This value should be set to at least MAX_PATH to allow sufficient room in the buffer for the path.

Return Values

If the function succeeds, the return value is the length, in characters, of the string copied to the buffer, not including the terminating null character.

If the length is greater than the size of the buffer, the return value is the size of the buffer required to hold the path.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The Windows directory is the directory where an application should store initialization and help files. If the user is running a shared version of Windows, the Windows directory is guaranteed to be private for each user.

If an application creates other files that it wants to store on a per-user basis, it should place them in the directory specified by the HOMEPATH environment variable. This directory will be different for each user, if so specified by an administrator, via the User Manager administrative tool. HOMEPATH always specifies either the user’s home directory, which is guaranteed to be private for each user, or a default directory (for example, C:\USERS\DEFAULT) where the user will have all access.

See Also

GetCurrentDirectory, GetSystemDirectory


GetWindowTask

The GetWindowTask function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the GetWindowThreadProcessId function.


GetWindowText

The GetWindowText function copies the text of the specified window’s title bar (if it has one) into a buffer. If the specified window is a control, the text of the control is copied.

int GetWindowText(

HWND hWnd,	// handle of window or control with text
LPTSTR lpString,	// address of buffer for text
int nMaxCount	// maximum number of characters to copy
);
Parameters

hWnd

Identifies the window or control containing the text.

lpString

Points to the buffer that will receive the text.

nMaxCount

Specifies the maximum number of characters to copy to the buffer. If the text exceeds this limit, it is truncated.

Return Values

If the function succeeds, the return value is the length, in characters, of the copied string, not including the terminating null character. If the window has no title bar or text, if the title bar is empty, or if the window or control handle is invalid, the return value is zero. To get extended error information, call GetLastError.

This function cannot retrieve the text of an edit control in another application.

Remarks

This function causes a WM_GETTEXT message to be sent to the specified window or control.

This function cannot retrieve the text of an edit control in another application.

See Also

GetWindowTextLength, SetWindowText, WM_GETTEXT


GetWindowTextLength

The GetWindowTextLength function retrieves the length, in characters, of the specified window’s title bar text (if the window has a title bar). If the specified window is a control, the function retrieves the length of the text within the control.

int GetWindowTextLength(

HWND hWnd	// handle of window or control with text
);
Parameters

hWnd

Identifies the window or control.

Return Values

If the function succeeds, the return value is the length, in characters, of the text. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section.

If the window has no text, the return value is zero. To get extended error information, call GetLastError.

Remarks

This function causes a WM_GETTEXTLENGTH message to be sent to the specified window or control.

Under certain conditions, the GetWindowTextLength function may return a value that is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the operating system allowing for the possible existence of DBCS characters within the text. The return value, however, will always be at least as large as the actual length of the text; you can thus always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode. It can also occur when an application uses the ANSI flavor of GetWindowTextLength with a window whose window procedure is Unicode, or the Unicode flavor with a window whose window procedure is ANSI.

To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the GetWindowText function.

See Also

CB_GETLBTEXT, GetWindowText, LB_GETTEXT, SetWindowText, WM_GETTEXT, WM_GETTEXTLENGTH


GetWindowThreadProcessId

The GetWindowThreadProcessId function retrieves the identifier of the thread that created the specified window and, optionally, the identifier of the process that created the window. This function supersedes the GetWindowTask function.

DWORD GetWindowThreadProcessId(

HWND hWnd,	// handle of window
LPDWORD lpdwProcessId	// address of variable for process identifier
);
Parameters

hWnd

Identifies the window.

lpdwProcessId

Points to a 32-bit value that receives the process identifier. If this parameter is not NULL, GetWindowThreadProcessId copies the identifier of the process to the 32-bit value; otherwise, it does not.

Return Values

The return value is the identifier of the thread that created the window.

Remarks

This function replaces the GetWindowTask function of Windows version 3.x.


GetWindowWord

The GetWindowWord function retrieves a 16-bit (word) value at the specified offset into the extra window memory for the specified window.

WORD GetWindowWord(

HWND hWnd,	// handle of window
int nIndex	// offset of value to retrieve
);
Parameters

hWnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the zero-based byte offset of the value to be retrieved. Valid values are in the range zero through the number of bytes of extra window memory, minus two; for example, if you specified 10 or more bytes of extra window memory, a value of 8 would be an index to the fifth 16-bit integer.

Return Values

If the function succeeds, the return value is the requested 16-bit value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the WNDCLASS structure used with the RegisterClass function.

The GWW_ values are obsolete in Win32. You must use the GetWindowLong function to retrieve information about the window.

See Also

GetParent, GetWindowLong, RegisterClass, SetParent, SetWindowLong, SetWindowWord, WNDCLASS


GetWinMetaFileBits

The GetWinMetaFileBits function converts the enhanced-format records from a metafile into Windows-format records and stores the converted records in the specified buffer.

UINT GetWinMetaFileBits(

HENHMETAFILE hemf,	// handle to the enhanced metafile
UINT cbBuffer,	// buffer size
LPBYTE lpbBuffer,	// pointer to buffer
INT fnMapMode,	// mapping mode
HDC hdcRef	// handle of reference device context
);
Parameters

hemf

Identifies the enhanced metafile.

cbBuffer

Specifies the size, in bytes, of the buffer into which the converted records are to be copied.

lpbBuffer

Points to the buffer into which the converted records are to be copied. If lpbBuffer is NULL, GetWinMetaFileBits returns the the number of bytes required to store the converted metafile records.

fnMapMode

Specifies the mapping mode to use in the converted metafile.

hdcRef

Identifies the reference device context.

Return Values

If the function succeeds and the buffer pointer is NULL, the return value is the number of bytes required to store the converted records; if the function succeeds and the buffer pointer is a valid pointer, the return value is the size of the metafile data in bytes.

If the function fails, the return value is zero.

Remarks

This function converts an enhanced metafile into a Windows-format metafile so that its picture can be displayed in an application that recognizes the older format.

Windows uses the reference device context to determine the resolution of the converted metafile.

The GetWinMetaFileBits function does not invalidate the enhanced metafile handle. An application should call the DeleteEnhMetaFile function to release the handle when it is no longer needed.

Due to the limitations of the Windows-format metafile, some information can be lost in the retrieved metafile contents. For example, an original call to the PolyBezier function in the enhanced metafile may be converted into a call to the Polyline function in the Windows-format metafile, because there is no equivalent PolyBezier function in the Windows format.

Windows 3.x applications define the viewport origin and extents of a picture stored in a Windows-format metafile. As a result, the Windows-format records created by GetWinMetaFileBits do not contain the SetViewportOrgEx and SetViewportExtEx functions. However, GetWinMetaFileBits does create Windows-format records for the SetWindowExtEx and SetMapMode functions.

To create a scalable Windows-format metafile, specify MM_ANISOTROPIC as the fnMapMode parameter.

The upper-left corner of the metafile picture is always mapped to the origin of the reference device.

See Also

DeleteEnhMetaFile, PolyBezier, Polyline, SetMapMode, SetViewportOrgEx, SetViewportExtEx, SetWindowExtEx, SetWinMetaFileBits


GetWorldTransform

The GetWorldTransform function retrieves the current world-space to page-space transformation.

BOOL GetWorldTransform(

HDC hdc,	// handle to the device context
LPXFORM lpXform	// pointer to the structure receiving transformation
);
Parameters

hdc

Identifies the device context.

lpXform

Points to an XFORM structure that receives the current world-space to page-space transformation.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The precision of the transformation may be altered if an application calls the ModifyWorldTransform function prior to calling GetWorldTransform. (This is because the internal format for storing transformation values uses a higher precision than a FLOAT value.)

See Also

ModifyWorldTransform, SetWorldTransform


GlobalAddAtom

The GlobalAddAtom function adds a character string to the global atom table and returns a unique value (an atom) identifying the string.

ATOM GlobalAddAtom(

LPCTSTR lpString	// pointer to the string to add
);
Parameters

lpString

Points to the null-terminated string to be added. The string can have a maximum size of 255 bytes. Strings that differ only in case are considered identical. The case of the first string of this name added to the table is preserved and returned by the GlobalGetAtomName function.

Return Values

If the function succeeds, the return value is the newly created atom.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If the string already exists in the global atom table, the atom for the existing string is returned and the atom’s reference count is incremented.

The string associated with the atom is not deleted from memory until its reference count is zero. For more information, see the GlobalDeleteAtom function.

Global atoms are not deleted automatically when the application terminates. For every call to the GlobalAddAtom function, there must be a corresponding call to the GlobalDeleteAtom function.

GlobalAddAtom returns a string atom whose value is in the range 0xC000 through 0xFFFF.

If the lpString parameter has the form “#1234”, GlobalAddAtom returns an integer atom whose value is the 16-bit representation of the decimal number specified in the string (0x04D2, in this example). If the decimal value specified is 0x0000 or a value in the range 0xC000 through 0xFFFF, the return value is zero, indicating an error. If lpString is in the range 0x0001 through 0xBFFF, the return value is the low-order word of lpString.

The MAKEINTATOM macro can be used to convert a WORD value into a string that can be added to the atom table by using the GlobalAddAtom function.

See Also

AddAtom, DeleteAtom, FindAtom, GetAtomName, GlobalDeleteAtom, GlobalFindAtom, GlobalGetAtomName, MAKEINTATOM


GlobalAlloc

The GlobalAlloc function allocates the specified number of bytes from the heap. In the linear Win32 API environment, there is no difference between the local heap and the global heap.

HGLOBAL GlobalAlloc(

UINT uFlags,	// object allocation attributes
DWORD dwBytes	// number of bytes to allocate
);
Parameters

uFlags

Specifies how to allocate memory. If zero is specified, the default is GMEM_FIXED. Except for the incompatible combinations that are specifically noted, any combination of the following flags can be used. To indicate whether the function allocates fixed or movable memory, specify one of the first four flags:

Flag	Meaning
GMEM_FIXED	Allocates fixed memory. This flag cannot be combined with the GMEM_MOVEABLE or GMEM_DISCARDABLE flag. The return value is a pointer to the memory block. To access the memory, the calling process simply casts the return value to a pointer.
GMEM_MOVEABLE	Allocates movable memory. This flag cannot be combined with the GMEM_FIXED flag. The return value is the handle of the memory object. The handle is a 32-bit quantity that is private to the calling process. To translate the handle into a pointer, use the GlobalLock function.
GPTR	Combines the GMEM_FIXED and GMEM_ZEROINIT flags.
GHND	Combines the GMEM_MOVEABLE and GMEM_ZEROINIT flags.
GMEM_DDESHARE	Allocates memory to be used by the dynamic data exchange (DDE) functions for a DDE conversation. Unlike Windows version 3. x, this memory is not shared globally. However, this flag is available for compatibility purposes. It may be used by some applications to enhance the performance of DDE operations and should, therefore, be specified if the memory is to be used for DDE.  Only processes that use DDE or the clipboard for interprocess communications should specify this flag.
GMEM_DISCARDABLE	Allocates discardable memory. This flag cannot be combined with the GMEM_FIXED flag. Some Win32-based applications may ignore this flag.
GMEM_LOWER	Ignored. This flag is provided only for compatibility with Windows version 3. x.
GMEM_NOCOMPACT	Does not compact or discard memory to satisfy the allocation request.
GMEM_NODISCARD	Does not discard memory to satisfy the allocation request.
GMEM_NOT_BANKED	Ignored. This flag is provided only for compatibility with Windows version 3. x.
GMEM_NOTIFY	Ignored. This flag is provided only for compatibility with Windows version 3. x.
GMEM_SHARE	Same as the GMEM_DDESHARE flag.
GMEM_ZEROINIT	Initializes memory contents to zero.
dwBytes

Specifies the number of bytes to allocate. If this parameter is zero and the uFlags parameter specifies the GMEM_MOVEABLE flag, the function returns a handle to a memory object that is marked as discarded.

Return Values

If the function succeeds, the return value is the handle of the newly allocated memory object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If the heap does not contain sufficient free space to satisfy the request, GlobalAlloc returns NULL.

Because NULL is used to indicate an error, virtual address zero is never allocated. It is, therefore, easy to detect the use of a NULL pointer.

All memory is created with execute access; no special function is required to execute dynamically generated code.

Memory allocated with this function is guaranteed to be aligned on an 8-byte boundary.

The GlobalAlloc and LocalAlloc functions are limited to a combined total of 65,536 handles for GMEM_MOVEABLE and LMEM_MOVEABLE memory per process. This limitation does not apply to GMEM_FIXED or LMEM_FIXED memory.

If this function succeeds, it allocates at least the amount of memory requested. If the actual amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual number of bytes allocated, use the GlobalSize function.

See Also

GlobalFree, GlobalLock, GlobalReAlloc, GlobalSize, LocalAlloc


GlobalCompact

The GlobalCompact function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. It has no meaning in the 32-bit environment.


GlobalDeleteAtom

The GlobalDeleteAtom function decrements the reference count of a global string atom. If the atom’s reference count reaches zero, GlobalDeleteAtom removes the string associated with the atom from the global atom table.

ATOM GlobalDeleteAtom(

ATOM nAtom	// atom to delete
);
Parameters

nAtom

Identifies the atom and character string to be deleted.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is the nAtom parameter. To get extended error information, call GetLastError.

Remarks

A string atom’s reference count specifies the number of times the string has been added to or removed from the atom table. The GlobalAddAtom function increments the reference count of a string that already exists in the global atom table each time it is called.

The only way to ensure that an atom has been deleted from the atom table is to call this function repeatedly until it fails. When the reference count is decremented to zero, the next GlobalFindAtom or GlobalDeleteAtom function call fails.

GlobalDeleteAtom has no effect on an integer atom (an atom created by using the MAKEINTATOM macro). The function always returns zero for an integer atom.

See Also

AddAtom, DeleteAtom, FindAtom, GlobalAddAtom, GlobalFindAtom, MAKEINTATOM


GlobalDiscard

The GlobalDiscard function discards the specified global memory block. The lock count of the memory object must be zero.

HGLOBAL GlobalDiscard(

HGLOBAL hglbMem	// handle to the global memory object
);
Parameters

hglbMem

Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Return Values

If the function succeeds, the return value is the handle of the memory object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

GlobalDiscard discards only global objects that the calling process allocated with the GMEM_DISCARDABLE flag. If a process attempts to discard a fixed or locked object, the function fails.

Although GlobalDiscard discards the object’s memory block, the handle of the object remains valid. A process can subsequently pass the handle to the GlobalReAlloc function to allocate another global memory block identified by the same handle.

See Also

GlobalAlloc, GlobalReAlloc


GlobalFindAtom

The GlobalFindAtom function searches the global atom table for the specified character string and retrieves the global atom associated with that string.

ATOM GlobalFindAtom(

LPCTSTR lpString	// pointer to the string to find
);
Parameters

lpString

Points to the null-terminated character string to search for.

Return Values

If the function succeeds, the return value is the global atom associated with the given string.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Even though Windows preserves the case of a string in an atom table as it was originally entered, the search performed by GlobalFindAtom is not case sensitive.

See Also

AddAtom, DeleteAtom, FindAtom, GetAtomName, GlobalAddAtom, GlobalDeleteAtom, GlobalGetAtomName


GlobalFix

The GlobalFix function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the VirtualLock and VirtualUnlock functions.


GlobalFlags

The GlobalFlags function returns information about the specified global memory object.

UINT GlobalFlags(

HGLOBAL hMem	// handle to the global memory object
);
Parameters

hMem

Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Return Values

If the function succeeds, the return value is a 32-bit value specifying the allocation flags and the lock count for the memory object.

If the function fails, the return value is the GMEM_INVALID_HANDLE flag, indicating that the global handle is not valid. To get extended error information, call GetLastError.

Remarks

The low-order byte of the low-order word of the return value contains the lock count of the object. To retrieve the lock count from the return value, use the GMEM_LOCKCOUNT mask with the bitwise AND (&) operator. The lock count of memory objects allocated with the GMEM_FIXED flag is always zero.

The high-order byte of the low-order word of the return value indicates the allocation flags of the memory object. It can be zero or any combination of the following flags:

Flag	Meaning
GMEM_DDESHARE	Memory was allocated for use by the dynamic data exchange (DDE) functions. Unlike Windows version  3. x, this memory is not shared globally. However, this flag is available for compatibility purposes and may be used by some applications to enhance the performance of DDE operations. Only processes that use DDE or the clipboard for interprocess communications should specify this flag.
GMEM_DISCARDABLE	The object’s memory block can be discarded.
GMEM_DISCARDED	The object’s memory block has been discarded.
See Also

GlobalAlloc, GlobalDiscard, GlobalLock, GlobalReAlloc, GlobalUnlock, LocalFlags


GlobalFree

The GlobalFree function frees the specified global memory object and invalidates its handle.

HGLOBAL GlobalFree(

HGLOBAL hMem	// handle to the global memory object
);
Parameters

hMem

Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Return Values

If the function succeeds, the return value is NULL.

If the function fails, the return value is equal to the handle of the global memory object. To get extended error information, call GetLastError.

Remarks

Heap corruption or an access violation exception (EXCEPTION_ACCESS_VIOLATION) may occur if the process tries to examine or modify the memory after it has been freed.

If the hgblMem parameter is NULL, GlobalFree fails and the system generates an access violation exception.

Both GlobalFree and LocalFree will free a locked memory object. A locked memory object has a lock count greater than zero. The GlobalLock function locks a global memory object and increments the lock count by one. The GlobalUnlock function unlocks it and decrements the lock count by one. To get the lock count of a global memory object, use the GlobalFlags function.

Windows NT: However, if an application is running under a debug (DBG) version of Windows NT, such as the one distributed on the SDK CD-ROM, both GlobalFree and LocalFree enter a breakpoint just before freeing a locked object. This lets a programmer double-check the intended behavior. Typing G while using the debugger in this situation lets the freeing operation occur.

See Also

GlobalAlloc, GlobalFlags, GlobalLock, GlobalReAlloc, GlobalUnlock, LocalFree


GlobalGetAtomName

The GlobalGetAtomName function retrieves a copy of the character string associated with the specified global atom.

UINT GlobalGetAtomName(

ATOM nAtom,	// atom identifier
LPTSTR lpBuffer,	// pointer to the buffer for the atom string
int nSize	// size of the buffer
);
Parameters

nAtom

Identifies the global atom associated with the character string to be retrieved.

lpBuffer

Points to the buffer for the character string.

nSize

Specifies the size, in characters, of the buffer.

Return Values

If the function succeeds, the return value is the length of the string copied to the buffer, in characters, not including the terminating null character.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The string returned for an integer atom (an atom created by the MAKEINTATOM macro) is a null-terminated string in which the first character is a pound sign (#) and the remaining characters represent the unsigned integer originally passed to MAKEINTATOM.

See Also

AddAtom, DeleteAtom, FindAtom, GlobalAddAtom, GlobalDeleteAtom, GlobalFindAtom, MAKEINTATOM


GlobalHandle

The GlobalHandle function retrieves the handle associated with the specified pointer to a global memory block.

HGLOBAL GlobalHandle(

LPCVOID pMem	// pointer to the global memory block
);
Parameters

pMem

Points to the first byte of the global memory block. This pointer is returned by the GlobalLock function.

Return Values

If the function succeeds, the return value is the handle of the specified global memory object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

When the GlobalAlloc function allocates a memory object with the GMEM_MOVEABLE flag, it returns the handle of the object. The GlobalLock function converts this handle into a pointer to the memory block, and GlobalHandle converts the pointer back into a handle.

See Also

GlobalAlloc, GlobalLock


GlobalLock

The GlobalLock function locks a global memory object and returns a pointer to the first byte of the object’s memory block. The memory block associated with a locked memory object cannot be moved or discarded. For memory objects allocated with the GMEM_MOVEABLE flag, the function increments the lock count associated with the memory object.

LPVOID GlobalLock(

HGLOBAL hMem	// address of the global memory object
);
Parameters

hMem

Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Return Values

If the function succeeds, the return value is a pointer to the first byte of the memory block.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The internal data structures for each memory object include a lock count that is initially zero. For movable memory objects, GlobalLock increments the count by one, and the GlobalUnlock function decrements the count by one. For each call that a process makes to GlobalLock for an object, it must eventually call GlobalUnlock. Locked memory will not be moved or discarded, unless the memory object is reallocated by using the GlobalReAlloc function. The memory block of a locked memory object remains locked until its lock count is decremented to zero, at which time it can be moved or discarded.

Memory objects allocated with the GMEM_FIXED flag always have a lock count of zero. For these objects, the value of the returned pointer is equal to the value of the specified handle.

If the specified memory block has been discarded or if the memory block has a zero-byte size, this function returns NULL.

Discarded objects always have a lock count of zero.

See Also

GlobalAlloc, GlobalFlags, GlobalReAlloc, GlobalUnlock


GlobalLRUNewest

The GlobalLRUNewest function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the VirtualLock and VirtualUnlock functions.


GlobalLRUOldest

The GlobalLRUOldest function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the VirtualLock and VirtualUnlock functions.


GlobalMemoryStatus

The GlobalMemoryStatus function retrieves information about current available memory. The function returns information about both physical and virtual memory. This function supersedes the GetFreeSpace function.

VOID GlobalMemoryStatus(

LPMEMORYSTATUS lpBuffer	// pointer to the memory status structure
);
Parameters

lpBuffer

Points to a MEMORYSTATUS structure in which information about current memory availability is returned. Before calling this function, the calling process should set the dwLength member of this structure.

Return Values

This function does not return a value.

Remarks

An application can use the GlobalMemoryStatus function to determine how much memory it can allocate without severely impacting other applications.

The information returned is volatile, and there is no guarantee that two sequential calls to this function will return the same information.

See Also

MEMORYSTATUS


GlobalReAlloc

The GlobalReAlloc function changes the size or attributes of a specified global memory object. The size can increase or decrease.

HGLOBAL GlobalReAlloc(

HGLOBAL hMem,	// handle to the global memory object
DWORD dwBytes,	// new size of the block
UINT uFlags	// how to reallocate object
);
Parameters

hMem

Identifies the global memory object to be reallocated. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

dwBytes

Specifies the new size, in bytes, of the memory block. If this parameter is zero and the uFlags parameter specifies the GMEM_MOVEABLE flag, the function returns the handle of a memory object that is marked as discarded. If uFlags specifies the GMEM_MODIFY flag, this parameter is ignored.

uFlags

Specifies how to reallocate the global memory object. If the GMEM_MODIFY flag is specified, this parameter modifies the attributes of the memory object, and the dwBytes parameter is ignored. Otherwise, this parameter controls the reallocation of the memory object.

The GMEM_MODIFY flag can be combined with either or both of the following flags:

Flag	Meaning
GMEM_DISCARDABLE	Allocates discardable memory if the GMEM_MODIFY flag is also specified. This flag is ignored, unless the object was previously allocated as movable or the GMEM_MOVEABLE flag is also specified.
GMEM_MOVEABLE	Windows NT only: Changes a fixed memory object to a movable memory object if the GMEM_MODIFY flag is also specified.
If this parameter does not specify GMEM_MODIFY, it can be any combination of the following flags:

Flag	Meaning
GMEM_MOVEABLE	If dwBytes is zero, discards a previously movable and discardable memory block. If the lock count of the object is not zero or if the block is not movable and discardable, the function fails.  If dwBytes is nonzero, enables the system to move the reallocated block to a new location without changing the movable or fixed attribute of the memory object. If the object is fixed, the handle returned may be different from the handle specified by the hMem parameter. If the object is movable, the block can be moved without invalidating the handle, even if the object is currently locked by a previous call to the GlobalLock function. To get the new address of the memory block, use GlobalLock.
GMEM_NOCOMPACT	Prevents memory from being compacted or discarded to satisfy the allocation request.
GMEM_ZEROINIT	Causes the additional memory contents to be initialized to zero if the memory object is growing in size.
Return Values

If the function succeeds, the return value is the handle of the reallocated memory object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If GlobalReAlloc reallocates a movable object, the return value is the handle of the memory object. To convert the handle to a pointer, use the GlobalLock function.

If GlobalReAlloc reallocates a fixed object, the value of the handle returned is the address of the first byte of the memory block. To access the memory, a process can simply cast the return value to a pointer.

If GlobalReAlloc fails, the original memory is not freed, and the original handle and pointer are still valid.

See Also

GlobalAlloc, GlobalFree, GlobalLock


GlobalSize

The GlobalSize function retrieves the current size, in bytes, of the specified global memory object.

DWORD GlobalSize(

HGLOBAL hMem	// handle to the global memory object
);
Parameters

hMem

Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Return Values

If the function succeeds, the return value is the size, in bytes, of the specified global memory object.

If the specified handle is not valid or if the object has been discarded, the return value is zero. To get extended error information, call GetLastError.

Remarks

The size of a memory block may be larger than the size requested when the memory was allocated.

To verify that the specified object’s memory block has not been discarded, use the GlobalFlags function before calling GlobalSize.

See Also

GlobalAlloc, GlobalFlags, GlobalReAlloc


GlobalUnfix

The GlobalUnfix function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. It has no meaning in the 32-bit environment.


GlobalUnlock

The GlobalUnlock function decrements the lock count associated with a memory object that was allocated with the GMEM_MOVEABLE flag. This function has no effect on memory objects allocated with the GMEM_FIXED flag.

BOOL GlobalUnlock(

HGLOBAL hMem	// handle to the global memory object
);
Parameters

hMem

Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Return Values

If the memory object is still locked after decrementing the lock count, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError. If GetLastError returns NO_ERROR, the memory object is unlocked.

Remarks

The internal data structures for each memory object include a lock count that is initially zero. For movable memory objects, the GlobalLock function increments the count by one, and GlobalUnlock decrements the count by one. For each call that a process makes to GlobalLock for an object, it must eventually call GlobalUnlock. Locked memory will not be moved or discarded, unless the memory object is reallocated by using the GlobalReAlloc function. The memory block of a locked memory object remains locked until its lock count is decremented to zero, at which time it can be moved or discarded.

Memory objects allocated with the GMEM_FIXED flag always have a lock count of zero. If the specified memory block is fixed memory, this function returns TRUE.

If the memory object is already unlocked, GlobalUnlock returns FALSE and GetLastError reports ERROR_NOT_LOCKED. Memory objects allocated with the LMEM_FIXED flag always have a lock count of zero and cause the ERROR_NOT_LOCKED error.

A process should not rely on the return value to determine the number of times it must subsequently call GlobalUnlock for a memory object.

See Also

GlobalAlloc, GlobalFlags, GlobalLock, GlobalReAlloc


GlobalUnWire

The GlobalUnWire function is obsolete. Applications that need to lock a global memory object should use the GlobalLock and GlobalUnlock functions.

This function is provided only for compatibility with 16-bit versions of Windows. New Win32-based applications should not use this function.


GlobalWire

The GlobalWire function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the GlobalLock and GlobalUnlock functions.


GrayString

The GrayString function draws gray text at the specified location. The function draws the text by copying it into a memory bitmap, graying the bitmap, and then copying the bitmap to the screen. The function grays the text regardless of the selected brush and background. GrayString uses the font currently selected for the specified device context.

If the lpOutputFunc parameter is NULL, GDI uses the TextOut function, and the lpData parameter is assumed to be a pointer to the character string to be output. If the characters to be output cannot be handled by TextOut (for example, the string is stored as a bitmap), the application must supply its own output function.

BOOL GrayString(

HDC hDC,	// handle to the device context
HBRUSH hBrush,	// handle to the brush for graying
GRAYSTRINGPROC lpOutputFunc,	// pointer to the callback function
LPARAM lpData,	// pointer to application-defined data
int nCount,	// number of characters to output
int X,	// horizontal position
int Y,	// vertical position
int nWidth,	// width
int nHeight	// height
);
Parameters

hDC

Identifies the device context.

hBrush

Identifies the brush to be used for graying. If this parameter is NULL, the text is grayed with the same brush that was used to draw window text.

lpOutputFunc

Points to the application-defined function that will draw the string, or, if TextOut is to be used to draw the string, it is a NULL pointer. For details, see the OutputProc callback function.

lpData

Specifies a pointer to data to be passed to the output function. If the lpOutputFunc parameter is NULL, lpData must be a pointer to the string to be output.

nCount

Specifies the number of characters to be output. If the nCount parameter is zero, GrayString calculates the length of the string (assuming lpData is a pointer to the string). If nCount is −1 and the function pointed to by lpOutputFunc returns FALSE, the image is shown but not grayed.

X

Specifies the device x-coordinate of the starting position of the rectangle that encloses the string.

Y

Specifies the device y-coordinate of the starting position of the rectangle that encloses the string.

nWidth

Specifies the width, in device units, of the rectangle that encloses the string. If this parameter is zero, GrayString calculates the width of the area, assuming lpData is a pointer to the string.

nHeight

Specifies the height, in device units, of the rectangle that encloses the string. If this parameter is zero, GrayString calculates the height of the area, assuming lpData is a pointer to the string.

Return Values

If the string is drawn, the return value is nonzero.

If either the TextOut function or the application-defined output function returned zero, or there was insufficient memory to create a memory bitmap for graying, the return value is zero.

Remarks

Without calling GrayString, an application can draw grayed strings on devices that support a solid gray color. The system color COLOR_GRAYTEXT is the solid-gray system color used to draw disabled text. The application can call the GetSysColor function to retrieve the color value of COLOR_GRAYTEXT. If the color is other than zero (black), the application can call the SetTextColor function to set the text color to the color value and then draw the string directly. If the retrieved color is black, the application must call GrayString to gray the text.

See Also

DrawText, GetSysColor, OutputProc, SetTextColor, TabbedTextOut, TextOut


Handler

A Handler function is a function that a service process specifies as the control handling function of a particular service. The function can have any application-defined name.

VOID WINAPI Handler(

DWORD fdwControl	// requested control code
);
Parameters

fdwControl

Indicates the requested control code. This value can be one of the standard control codes in the table, or it can be a user-defined control code in the range of 128 to 255, inclusive. For user-defined control codes, the service defines the action associated with the control code.

Value	Meaning
SERVICE_CONTROL_STOP
	Requests the service to stop.
SERVICE_CONTROL_PAUSE
	Requests the service to pause.
SERVICE_CONTROL_CONTINUE
	Requests the paused service to resume.
SERVICE_CONTROL_INTERROGATE
	Requests the service to immediately report its current status information to the service control manager.
SERVICE_CONTROL_SHUTDOWN
	Requests the service to perform cleanup tasks, because the system is shutting down. Due to extremely limited time available for shutdown, this control should only be used by services that absolutely need to shut down —  for instance, when the eventlog service needs to clear a dirty bit in the files that it maintains, or when the server service needs to shut down so that network connections aren’t made when the system is in the shutdown state. If the service takes time to shut down, and sends out STOP_PENDING status messages, it is highly recommended that these messages include a waithint so that the service controller will know how long to wait before indicating to the system that service shutdown is complete. The system gives the service control manager a limited amount of time (about 20 seconds) to complete service shutdown, after which time system shutdown proceeds regardless of whether service shutdown is complete.
Return Values

This function does not return a value.

Remarks

When a Win32 service is started, its ServiceMain function should immediately call the RegisterServiceCtrlHandler function to specify a Handler function to handle control requests.

Whenever it receives a control request from the service control manager, the control dispatcher in the main thread of a Win32 service process invokes the control handler function for the specified service. After handling the control request, the control handler must call the SetServiceStatus function to report its current status to the service control manager.

See Also

RegisterServiceCtrlHandler, ServiceMain, SetServiceStatus


HandlerRoutine

A HandlerRoutine function is a function that a console process specifies to handle control signals received by the process. The function can have any name.

BOOL HandlerRoutine(

DWORD dwCtrlType	//  control signal type
);
Parameters

dwCtrlType

Indicates the type of control signal received by the handler. This value is one of the following:

Signal	Description
CTRL_C_EVENT	A CTRL+C signal was received, either from keyboard input or from a signal generated by the GenerateConsoleCtrlEvent function.
CTRL_BREAK_EVENT	A CTRL+BREAK signal was received, either from keyboard input or from a signal generated by GenerateConsoleCtrlEvent.
CTRL_CLOSE_EVENT	A signal that the system sends to all processes attached to a console when the user closes the console (either by choosing the Close command from the console window’s System menu, or by choosing the End Task command from the Task List).
CTRL_LOGOFF_EVENT	A signal that the system sends to all console processes when a user is logging off. This signal does not indicate which user is logging off, so no assumptions can be made.
CTRL_SHUTDOWN_EVENT	A signal that the system sends to all console processes when the system is shutting down.
Return Values

If the function handles the control signal, it should return TRUE. If it returns FALSE, the next handler function in the list of handlers for this process is used.

Remarks

Each console process has its own list of HandlerRoutine functions. Initially, this list contains only a default handler function that calls ExitProcess. A console process adds or removes additional handler functions by calling the SetConsoleCtrlHandler function, which does not affect the list of handler functions for other processes. When a console process receives any of the control signals, its handler functions are called on a last-registered, first-called basis until one of the handlers returns TRUE. If none of the handlers returns TRUE, the default handler is called.

The CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, and CTRL_SHUTDOWN_EVENT signals give the process an opportunity to clean up before termination. A HandlerRoutine called to handle any of these signals can do one of the following after performing any cleanup operations:

•	Call the ExitProcess function to terminate the process.

•	Return FALSE. If none of the registered handler functions returns TRUE, the default handler terminates the process.

•	Return TRUE. In this case, no other handler functions are called, and the system displays a pop-up dialog box that asks the user whether to terminate the process. The system also displays the dialog box if the process does not respond within a certain time-out period (5 seconds for CTRL_CLOSE_EVENT, and 20 seconds for CTRL_LOGOFF_EVENT and CTRL_SHUTDOWN_EVENT).

A process can use the SetProcessShutdownParameters function to prevent the CTRL_LOGOFF_EVENT and CTRL_SHUTDOWN_EVENT dialog box from being displayed. In this case, the system just terminates the process when a HandlerRoutine returns TRUE or when the time-out period elapses.

See Also

ExitProcess, GenerateConsoleCtrlEvent, GetProcessShutdownParameters, SetConsoleCtrlHandler, SetProcessShutdownParameters


HeapAlloc

The HeapAlloc function allocates a block of memory from a heap. The allocated memory is not movable.

LPVOID HeapAlloc(

HANDLE hHeap,	// handle to the private heap block
DWORD dwFlags,	// heap allocation control flags
DWORD dwBytes	// number of bytes to allocate
);
Parameters

hHeap

Specifies the heap from which the memory will be allocated. This parameter is a handle returned by the HeapCreate or GetProcessHeap function.

dwFlags

Specifies several controllable aspects of heap allocation. Specifying any of these flags will override the corresponding flag specified when the heap was created with HeapCreate. You can specify one or more of the following flags:

Flag	Meaning
HEAP_GENERATE_EXCEPTIONS	Specifies that the operating system will raise an exception to indicate a function failure, such as an out-of-memory condition, instead of returning NULL.
HEAP_NO_SERIALIZE	Specifies that mutual exclusion will not be used while this function is accessing the heap. For more information about HEAP_NO_SERIALIZE, see the Remarks section of HeapCreate.
HEAP_ZERO_MEMORY	Specifies that the allocated memory will be initialized to zero.
dwBytes

Specifies the number of bytes to be allocated.

If the heap specified by the hHeap parameter is a “non-growable” heap, dwBytes must be less than 0x7FFF8. You create a non-growable heap by calling the HeapCreate function with a nonzero value.

Return Values

If the function succeeds, the return value is a pointer to the allocated memory block.

If the function fails and you have not specified HEAP_GENERATE_EXCEPTIONS, the return value is NULL.

If the function fails and you have specified HEAP_GENERATE_EXCEPTIONS, the function may generate the following exceptions:

Value	Meaning
STATUS_NO_MEMORY	The allocation attempt failed because of a lack of available memory or heap corruption.
STATUS_ACCESS_VIOLATION	The allocation attempt failed because of heap corruption or improper function parameters.
Note that heap corruption can lead to either exception. It depends upon the nature of the heap corruption.

If the function fails, it does not call SetLastError. An application cannot call GetLastError for extended error information.

Remarks

If HeapAlloc succeeds, it allocates at least the amount of memory requested. If the actual amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual size of the allocated block, use the HeapSize function.

To free a block of memory allocated by HeapAlloc, use the HeapFree function.

Memory allocated by HeapAlloc is not movable. Since the memory is not movable, it is possible for the heap to become fragmented.

Note that if HEAP_ZERO_MEMORY is not specified, the allocated memory will not be initialized to zero.

See Also

GetProcessHeap, HeapCreate, HeapDestroy, HeapFree, HeapReAlloc, HeapSize, SetLastError


HeapCompact

The HeapCompact function attempts to compact a specified heap. It compacts the heap by coalescing adjacent free blocks of memory and decommitting large free blocks of memory.

UINT HeapCompact(

HANDLE hHeap,	// handle to the heap to compact
DWORD dwFlags	// bit-flags that control heap access during function operation
);
Parameters

hHeap

Handle to the heap that the function will attempt to compact.

dwFlags

A set of bit flags that control heap access during function operation. The following bit flag has meaning:

Value	Meaning
HEAP_NO_SERIALIZE	If this flag is set, heap access is not serialized while the HeapCompact function accesses the heap; heap access is not mutually exclusive. It is safe to set this flag only in a limited set of specific situations. For a discussion of those situations and heap serialization in general, see the Remarks section of HeapCreate.  If this flag is clear, heap access is serialized while HeapCompact accesses the heap; heap access is mutually exclusive. This is the safe and simple default condition.
Return Values

If the function succeeds, the return value is the size, in bytes, of the largest committed free block in the heap. This is an unsigned integer value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

In the unlikely case that there is absolutely no space available in the heap, the function return value is zero, and GetLastError returns the value NO_ERROR.

Remarks

There is no guarantee that an application can successfully allocate a memory block of the size returned by HeapCompact. Other threads or the commit threshold might prevent such an allocation.

See Also

HeapCreate, HeapValidate


HeapCreate

The HeapCreate function creates a heap object that can be used by the calling process. The function reserves a contiguous block in the virtual address space of the process and allocates physical storage for a specified initial portion of this block.

HANDLE HeapCreate(

DWORD flOptions,	// heap allocation flag
DWORD dwInitialSize,	// initial heap size
DWORD dwMaximumSize	// maximum heap size
);
Parameters

flOptions

Specifies optional attributes for the new heap. These flags will affect subsequent access to the new heap through calls to the heap functions (HeapAlloc, HeapFree, HeapReAlloc, and HeapSize). You can specify one or more of the following flags:

Flag	Meaning
HEAP_GENERATE_EXCEPTIONS	Specifies that the system will raise an exception to indicate a function failure, such as an out-of-memory condition, instead of returning NULL.
HEAP_NO_SERIALIZE	Specifies that mutual exclusion will not be used when the heap functions allocate and free memory from this heap. The default, occurring when the HEAP_NO_SERIALIZE flag is not specified, is to serialize access to the heap. Serialization of heap access allows two or more threads to simultaneously allocate and free memory from the same heap.
dwInitialSize

Specifies the initial size, in bytes, of the heap. This value determines the initial amount of physical storage that is allocated for the heap. The value is rounded up to the next page boundary. To determine the size of a page on the host computer, use the GetSystemInfo function.

dwMaximumSize

If dwMaximumSize is a nonzero value, it specifies the maximum size, in bytes, of the heap. The HeapCreate function rounds dwMaximumSize up to the next page boundary, and then reserves a block of that size in the process’s virtual address space for the heap. If allocation requests made by the HeapAlloc or HeapReAlloc functions exceed the initial amount of physical storage specified by dwInitialSize, the system allocates additional pages of physical storage for the heap, up to the heap’s maximum size.

In addition, if dwMaximumSize is nonzero, the heap cannot grow, and an absolute limitation arises: the maximum size of a memory block in the heap is a bit less than 0x7FFF8 bytes. Requests to allocate larger blocks will fail, even if the maximum size of the heap is large enough to contain the block.

If dwMaximumSize is zero, it specifies that the heap is growable. The heap’s size is limited only by available memory. Requests to allocate blocks larger than 0x7FFF8 bytes do not automatically fail; the system calls VirtualAlloc to obtain the memory needed for such large blocks. Applications that need to allocate large memory blocks should set dwMaximumSize to zero.

Return Values

If the function succeeds, the return value is a handle of the newly created heap.

If the function fails, the return value is is NULL. To get extended error information, call GetLastError.

Remarks

The HeapCreate function creates a private heap object from which the calling process can allocate memory blocks by using the HeapAlloc function. The initial size determines the number of committed pages that are initially allocated for the heap. The maximum size determines the total number of reserved pages. These pages create a contiguous block in the process’s virtual address space into which the heap can grow. If requests by HeapAlloc exceed the current size of committed pages, additional pages are automatically committed from this reserved space, assuming that the physical storage is available.

The memory of a private heap object is accessible only to the process that created it. If a dynamic-link library (DLL) creates a private heap, the heap is created in the address space of the process that called the DLL, and it is accessible only to that process.

The system uses memory from the private heap to store heap support structures, so not all of the specified heap size is available to the process. For example, if the HeapAlloc function requests 64 kilobytes (K) from a heap with a maximum size of 64K, the request may fail because of system overhead.

If the HEAP_NO_SERIALIZE flag is not specified (the simple default), the heap will serialize access within the calling process. Serialization ensures mutual exclusion when two or more threads attempt to simultaneously allocate or free blocks from the same heap. There is a small performance cost to serialization, but it must be used whenever multiple threads allocate and free memory from the same heap.

Setting the HEAP_NO_SERIALIZE flag eliminates mutual exclusion on the heap. Without serialization, two or more threads that use the same heap handle might attempt to allocate or free memory simultaneously, likely causing corruption in the heap. The HEAP_NO_SERIALIZE flag can, therefore, be safely used only in the following situations:

•	The process has only one thread.

•	The process has multiple threads, but only one thread calls the heap functions for a specific heap.

•	The process has multiple threads, and the application provides its own mechanism for mutual exclusion to a specific heap.

See Also

GetProcessHeap, GetProcessHeaps, GetSystemInfo, HeapAlloc, HeapDestroy, HeapFree, HeapReAlloc, HeapSize, HeapValidate, VirtualAlloc


HeapDestroy

The HeapDestroy function destroys the specified heap object. HeapDestroy decommits and releases all the pages of a private heap object, and it invalidates the handle of the heap.

BOOL HeapDestroy(

HANDLE hHeap	// handle to the heap
);
Parameters

hHeap

Specifies the heap to be destroyed. This parameter should be a heap handle returned by the HeapCreate function. A heap handle returned by the GetProcessHeap function should not be used.

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.

Remarks

Processes can call HeapDestroy without first calling the HeapFree function to free memory allocated from the heap.

See Also

GetProcessHeap, HeapAlloc, HeapCreate, HeapFree, HeapReAlloc, HeapSize


HeapFree

The HeapFree function frees a memory block allocated from a heap by the HeapAlloc or HeapReAlloc function.

BOOL HeapFree(

HANDLE hHeap,	// handle to the heap
DWORD dwFlags,	// heap freeing flags
LPVOID lpMem	// pointer to the memory to free
);
Parameters

hHeap

Specifies the heap whose memory block the function frees. This parameter is a handle returned by the HeapCreate or GetProcessHeap function.

dwFlags

Specifies several controllable aspects of freeing a memory block. Only one flag is currently defined; however, all other flag values are reserved for future use. Specifying this flag will override the corresponding flag specified in the flOptions parameter when the heap was created by using the HeapCreate function:

Flag	Meaning
HEAP_NO_SERIALIZE	Specifies that mutual exclusion will not be used while the function is accessing the heap. For more information about HEAP_NO_SERIALIZE, see the Remarks for the HeapCreate function.
lpMem

Points to the memory block to free. This pointer is returned by the HeapAlloc or HeapReAlloc function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. An application can call GetLastError for extended error information.

See Also

GetProcessHeap, HeapAlloc, HeapCreate, HeapDestroy, HeapReAlloc, HeapSize, SetLastError


HeapLock

The HeapLock function attempts to acquire the critical section object, or lock, that is associated with a specified heap.

If the function succeeds, the calling thread owns the heap lock. Only the calling thread will be able to allocate or release memory from the heap. The execution of any other thread of the calling process will be blocked if that thread attempts to allocate or release memory from the heap. Such threads will remain blocked until the thread that owns the heap lock calls the HeapUnlock function.

BOOL HeapLock(

HANDLE hHeap	// handle to the heap to lock for exclusive thread access
);
Parameters

hHeap

Handle to the heap to lock for exclusive access by the calling thread.

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.

Remarks

The HeapLock function is primarily useful for preventing the allocation and release of heap memory by other threads while the calling thread uses the HeapWalk function.

Each call to HeapLock must be matched by a corresponding call to the HeapUnlock function. Failure to call HeapUnlock will block the execution of any other threads of the calling process that attempt to access the heap.

See Also

HeapUnlock, HeapWalk


HeapReAlloc

The HeapReAlloc function reallocates a block of memory from a heap. This function enables you to resize a memory block and change other memory block properties. The allocated memory is not movable.

LPVOID HeapReAlloc(

HANDLE hHeap,	// handle to a heap block
DWORD dwFlags,	// heap reallocation flags
LPVOID lpMem,	// pointer to the memory to reallocate
DWORD dwBytes	// number of bytes to reallocate
);
Parameters

hHeap

Specifies the heap from which the memory will be reallocated. This is a handle returned by the HeapCreate or GetProcessHeap function.

dwFlags

Specifies several controllable aspects of heap reallocation. Specifying any of these flags will override the corresponding flag specified in the flOptions parameter when the heap was created by using the HeapCreate function. You can specify one or more of the following flags:

Flag	Meaning
HEAP_GENERATE_EXCEPTIONS	Specifies that the operating-system will raise an exception to indicate a function failure, such as an out-of-memory condition, instead of returning NULL.
HEAP_NO_SERIALIZE	Specifies that mutual exclusion will not be used while this function is accessing the heap. For more information about HEAP_NO_SERIALIZE, see the Remarks section of HeapCreate.
HEAP_REALLOC_IN_PLACE_ONLY	Specifies that there can be no movement when reallocating a memory block to a larger size. If this flag is not specified and the reallocation request is for a larger size, the function may move the block to a new location. If this flag is specified and the block cannot be enlarged without moving, the function will fail, leaving the original memory block unchanged.
HEAP_ZERO_MEMORY	If the reallocation request is for a larger size, this flag specifies that the additional region of memory beyond the original size will be initialized to zero. The contents of the memory block up to its original size are unaffected.
lpMem

Points to the block of memory that the function reallocates. This pointer is returned by an earlier call to the HeapAlloc or HeapReAlloc function.

dwBytes

Specifies the new size of the memory block, in bytes. A memory block’s size can be increased or decreased by using this function.

If the heap specified by the hHeap parameter is a “non-growable” heap, dwBytes must be less than 0x7FFF8. You create a non-growable heap by calling the HeapCreate function with a nonzero value.

Return Values

If the function succeeds, the return value is a pointer to the reallocated memory block.

If the function fails and you have not specified HEAP_GENERATE_EXCEPTIONS, the return value is NULL.

If the function fails and you have specified HEAP_GENERATE_EXCEPTIONS, the function may generate the following exceptions:

Value	Meaning
STATUS_NO_MEMORY	The reallocation attempt failed for lack of available memory.
STATUS_ACCESS_VIOLATION	The reallocation attempt failed because of heap corruption or improper function parameters.
If the function fails, it calls SetLastError. An application can call GetLastError for extended error information.

Remarks

If HeapReAlloc succeeds, it allocates at least the amount of memory requested. If the actual amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual size of the reallocated block, use the HeapSize function.

To free a block of memory allocated by HeapReAlloc, use the HeapFree function.

See Also

GetProcessHeap, HeapAlloc, HeapCreate, HeapDestroy, HeapFree, HeapSize, SetLastError


HeapSize

The HeapSize function returns the size, in bytes, of a memory block allocated from a heap by the HeapAlloc or HeapReAlloc function.

DWORD HeapSize(

HANDLE hHeap,	// handle to the heap
DWORD dwFlags,	// heap size control flags
LPCVOID lpMem	// pointer to memory to return size for
);
Parameters

hHeap

Specifies the heap in which the memory block resides. This handle is returned by the HeapCreate or GetProcessHeap function.

dwFlags

Specifies several controllable aspects of accessing the memory block. Only one flag is currently defined; however, all other flag values are reserved for future use. Specifying this flag will override the corresponding flag specified in the flOptions parameter when the heap was created by using the HeapCreate function:

Value	Meaning
HEAP_NO_SERIALIZE	Specifies that mutual exclusion will not be used while the function is accessing the heap. For more information about HEAP_NO_SERIALIZE, see the Remarks for HeapCreate.
lpaam

Points to the memory block whose size the function will obtain. This is a pointer returned by the HeapAlloc or HeapReAlloc function.

Return Values

If the function succeeds, the return value is the size, in bytes, of the allocated memory block.

If the function fails, the return value is 0xFFFFFFFF. The function does not call SetLastError. An application cannot call GetLastError for extended error information.

See Also

GetProcessHeap, HeapAlloc, HeapCreate, HeapDestroy, HeapFree, HeapReAlloc, SetLastError


HeapUnlock

The HeapUnlock function releases ownership of the critical section object, or lock, that is associated with a specified heap. The HeapUnlock function reverses the action of the HeapLock function.

BOOL HeapUnlock(

HANDLE hHeap	// handle to the heap to unlock
);
Parameters

hHeap

Handle to the heap to unlock.

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.

Remarks

The HeapLock function is primarily useful for preventing the allocation and release of heap memory by other threads while the calling thread uses the HeapWalk function. The HeapUnlock function is the inverse of HeapLock.

Each call to HeapLock must be matched by a corresponding call to the HeapUnlock function. Failure to call HeapUnlock will block the execution of any other threads of the calling process that attempt to access the heap.

See Also

HeapLock, HeapWalk


HeapValidate

The HeapValidate function attempts to validate a specified heap. The function scans all the memory blocks in the heap, and verifies that the heap control structures maintained by the operating system’s heap manager are in a consistent state. You can also use the HeapValidate function to validate a single memory block within a specified heap, without checking the validity of the entire heap.

BOOL HeapValidate(

HANDLE hHeap,	// handle to the heap of interest
DWORD dwFlags,	// bit flags that control heap access during function operation
LPCVOID lpMem	// optional pointer to individual memory block to validate
);
Parameters

hHeap

Handle to the heap of interest. The HeapValidate function attempts to validate this heap, or a single memory block within this heap.

dwFlags

A set of bit flags that control heap access during function operation. The following bit flag has meaning:

Value	Meaning
HEAP_NO_SERIALIZE	If this flag is set, heap access is not serialized while the HeapValidate function accesses the heap; heap access is not mutually exclusive. It is safe to set this flag only in a limited set of specific situations. For a discussion of those situations and heap serialization in general, see the Remarks section of HeapCreate.  If this flag is clear, heap access is serialized while HeapValidate accesses the heap; heap access is mutually exclusive. This is the safe and simple default condition.
lpMem

Points to a memory block within the specified heap. This parameter may be NULL.

If this parameter is NULL, the function attempts to validate the entire heap specified by hHeap.

If this parameter is not NULL, the function attempts to validate the memory block pointed to by lpMem. It does not attempt to validate the rest of the heap.

Return Values

If the specified heap or memory block is valid, the return value is nonzero.

If the specified heap or memory block is invalid, the return value is zero. On a system set up for debugging, the HeapValidate function then displays debugging messages that describe the part of the heap or memory block that is invalid, and stops at a hard-coded breakpoint so that you can examine the system to determine the source of the invalidity. The HeapValidate function does not set the thread’s last error value.

Remarks

There are heap control structures for each memory block in a heap, and for the heap as a whole. When you use the HeapValidate function to validate a complete heap, it checks all of these control structures for consistency.

When you use HeapValidate to validate a single memory block within a heap, it checks only the control structures pertaining to that element. HeapValidate can only validate allocated memory blocks. Calling HeapValidate on a freed memory block will return FALSE because there are no control structures to validate.

If you want to validate the heap elements enumerated by the HeapWalk function, you should only call HeapValidate on the elements that have the PROCESS_HEAP_ENTRY_BUSY bit flag in the wFlags member of the PROCESS_HEAP_ENTRY structure. HeapValidate returns FALSE for all heap elements that do not have this bit set.

See Also

HeapCreate, HeapWalk, PROCESS_HEAP_ENTRY


HeapWalk

The HeapWalk function enumerates the memory blocks in a specified heap.

BOOL HeapWalk(

HANDLE hHeap,	// handle to the heap to enumerate
LPPROCESS_HEAP_ENTRY lpEntry	// points to structure that maintains enumeration state information
);
Parameters

hHeap

Handle to the heap whose memory blocks you wish to enumerate.

dwFlags

Points to a PROCESS_HEAP_ENTRY structure that maintains state informationfor a particular heap enumeration.

If the HeapWalk function succeeds, returning the value TRUE, this structure’s members contain information about the next memory block in the heap.

To initiate a heap enumeration, set the lpData field of the PROCESS_HEAP_ENTRY structure to NULL. To continue a particular heap enumeration, call the HeapWalk function repeatedly, with no changes to hHeap, lpEntry, or any of the members of the PROCESS_HEAP_ENTRY structure.

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.

If the heap enumeration terminates successfully by reaching the end of the heap, the function returns FALSE, and GetLastError returns the error code ERROR_NO_MORE_ITEMS.

Remarks

To initiate a heap enumeration, call HeapWalk with the lpData field of the PROCESS_HEAP_ENTRY structure pointed to by lpEntry set to NULL.

To continue a heap enumeration, call HeapWalk with the same hHeap and lpEntry values, and with the PROCESS_HEAP_ENTRY structure unchanged from the preceding call to HeapWalk. Repeat this process until you have no need for further enumeration, or until the function returns FALSE and GetLastError returns ERROR_NO_MORE_ITEMS, indicating that all of the heap’s memory blocks have been enumerated.

No special call of HeapWalk is needed to terminate the heap enumeration, since no enumeration state data is maintained outside the contents of the PROCESS_HEAP_ENTRY structure.

HeapWalk can fail in a multithreaded application if the heap is not locked during the heap enumeration. Use the HeapLock and HeapUnlock functions to control heap locking during heap enumeration.

See Also

HeapLock, HeapUnlock, HeapValidate, PROCESS_HEAP_ENTRY


HideCaret

The HideCaret function removes the caret from the screen. Hiding a caret does not destroy its current shape or invalidate the insertion point.

BOOL HideCaret(

HWND hWnd	// handle to the window with the caret
);
Parameters

hWnd

Identifies the window that owns the caret. If this parameter is NULL, HideCaret searches the current task for the window that owns the caret.

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.

Remarks

HideCaret hides the caret only if the specified window owns the caret. If the specified window does not own the caret, HideCaret does nothing and returns FALSE.

Hiding is cumulative. If your application calls HideCaret five times in a row, it must also call ShowCaret five times before the caret is displayed.

See Also

CreateCaret, DestroyCaret, GetCaretPos, SetCaretPos, ShowCaret


HiliteMenuItem

The HiliteMenuItem function highlights or removes the highlighting from an item in a menu bar.

BOOL HiliteMenuItem(

HWND hwnd,	// handle to the window with the menu
HMENU hmenu,	// handle to the menu
UINT uItemHilite,	// menu item to highlight or unhighlight
UINT uHilite	// highlight flags
);
Parameters

hwnd

Identifies the window that contains the menu.

hmenu

Identifies the menu bar that contains the item to be highlighted.

uItemHilite

Specifies the menu item to be highlighted. This parameter is either the identifier of the menu item or the offset of the menu item in the menu bar, depending on the value of the uHilite parameter.

uHilite

Specifies flags that control the interpretation of the uItemHilite parameter and indicates whether the menu item is highlighted. This parameter must be a combination of either MF_BYCOMMAND or MF_BYPOSITION and MF_HILITE or MF_UNHILITE.

Value	Meaning
MF_BYCOMMAND	Indicates that uItemHilite gives the identifier of the menu item.
MF_BYPOSITION	Indicates that uItemHilite gives the zero-based relative position of the menu item.
MF_HILITE	Highlights the menu item. If this flag is not specified, the highlighting is removed from the item.
MF_UNHILITE	Removes highlighting from the menu item.
Return Values

If the menu item is set to the specified highlight state, the return value is nonzero.

If the menu item is not set to the specified highlight state, the return value is zero.

Remarks

The MF_HILITE and MF_UNHILITE flags can be used only with the HiliteMenuItem function; they cannot be used with the ModifyMenu function.

See Also

ModifyMenu


ImageList_Add

The ImageList_Add function adds an image or images to an image list.

int ImageList_Add(

HIMAGELIST himl,	// handle to the image list
HBITMAP hbmImage,	// handle to the bitmap containing the image
HBITMAP hbmMask	// handle to the bitmap containing the mask
);
Parameters

himl

Handle to the image list.

hbmImage

Handle to the bitmap that contains the image or images. The number of images is inferred from the width of the bitmap.

hbmMask

Handle to the bitmap that contains the mask. If no mask is used with the image list, this parameter is ignored.

Return Values

If the function succeeds, the return value is the index of the first new image.

If the function fails, the return value is − 1.

Remarks

The ImageList_Add function copies the bitmap to an internal data structure. Be sure to use the DeleteObject function to delete hbmImage and hbmMask after the function returns.

See Also

DeleteObject


ImageList_AddMasked

The ImageList_AddMasked function adds an image or images to an image list, generating a mask from the specified bitmap.

int ImageList_AddMasked(

HIMAGELIST himl,	// handle to the image list
HBITMAP hbmImage,	// handle to the bitmap
COLORREF crMask	// color used to generate mask
);
Parameters

himl

Handle to the image list.

hbmImage

Handle to the bitmap that contains one or more images. The number of images is inferred from the width of the bitmap.

crMask

Color used to generate the mask. Each pixel of this color in the specified bitmap is changed to black, and the corresponding bit in the mask is set to one.

Return Values

If the function succeeds, the return value is the index of the first new image.

If the function fails, the return value is  − 1.

Remarks

The ImageList_AddMasked function copies the bitmap to an internal data structure. Be sure to use the DeleteObject function to delete hbmImage and crMask after the function returns.

See Also

DeleteObject


ImageList_BeginDrag

The ImageList_BeginDrag function begins dragging an image.

BOOL ImageList_BeginDrag(

HIMAGELIST himlTrack,
int iTrack,
int dxHotspot,
int dyHotspot
);
Parameters

himlTrack

Handle to the image list.

iTrack

Index of the image to drag.

dxHotspot and dyHotspot

Location of the drag position relative to the upper-left corner of the image.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

This function creates a temporary image list that is used for dragging. In response to subsequent WM_MOUSEMOVE messages, you can move the drag image by using the ImageList_DragMove function. To end the drag operation, you can use the ImageList_EndDrag function.

See Also

ImageList_DragMove, ImageList_EndDrag, WM_MOUSEMOVE


ImageList_Create

The ImageList_Create function creates a new image list.

HIMAGELIST ImageList_Create(

int cx,
int cy,
UINT flags,
int cInitial,
int cGrow
);
Parameters

cx

Specifies the width, in pixels, of each image.

cy

Specifies the height, in pixels, of each image.

flags

A set of bit flags that specify the type of image list to create. This parameter can be a combination of the following values, but it can include only one of the ILC_COLOR values.

Value	Meaning
ILC_COLOR	Use the default behavior if none of the other ILC_COLOR* flags is specified. Typically, the default is ILC_COLOR4; but for older display drivers, the default is ILC_COLORDDB.
ILC_COLOR4	Use a 4-bit (16 color) device-independent bitmap (DIB) section as the bitmap for the image list.
ILC_COLOR8	Use an 8-bit DIB section. The colors used for the color table are the same colors as the halftone palette.
ILC_COLOR16	Use a 16-bit  (32/64k color) DIB section.
ILC_COLOR24	Use a 24-bit DIB section.
ILC_COLOR32	Use a 32-bit DIB section.
ILC_COLORDDB	Use a device-dependent bitmap.
ILC_MASK	Uses a mask. The image list contains two bitmaps, one of which is a monochrome bitmap used as a mask. If this value is not included, the image list contains only one bitmap.
cInitial

Number of images that the image list initially contains.

cGrow

Amount of images by which the image list can grow when the system needs to resize the list to make room for new images. This parameter represents the number of new images that the resized image list can contain.

Return Values

If the function succeeds, the return value is the handle to the image list.

If the function fails, the return value NULL.


ImageList_Destroy

The ImageList_Destroy function destroys an image list.

BOOL ImageList_Destroy(

HIMAGELIST himl
);
Parameters

himl

Handle to the image list to destroy.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.


ImageList_DragEnter

The ImageList_DragEnter function locks updates to the specified window during a drag operation and displays the drag image at the specified position within the window.

BOOL ImageList_DragEnter(

HWND hwndLock,
int x,
int y
);
Parameters

hwndLock

Handle to the window that owns the drag image.

x

Specifies the x-coordinate at which to display the drag image. The coordinate is relative to the upper-left corner of the window, not the client area.

y

Specifies the y-coordinate at which to display the drag image. The coordinate is relative to the upper-left corner of the window, not the client area.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

To begin a drag operation, use the ImageList_BeginDrag function.

See Also

ImageList_BeginDrag


ImageList_DragLeave

The ImageList_DragLeave function unlocks the specified window and hides the drag image, allowing the window to be updated.

BOOL ImageList_DragLeave(

HWND hwndLock
);
Parameters

hwndLock

Handle to the window that owns the drag image.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.


ImageList_DragMove

The ImageList_DragMove function moves the image that is being dragged during a drag-and-drop operation. This function is typically called in response to a WM_MOUSEMOVE message.

BOOL ImageList_DragMove(

int x,
int y
);
Parameters

x

Specifies the x-coordinate at which to display the drag image. The coordinate is relative to the upper-left corner of the window, not the client area.

y

Specifies the y-coordinate at which to display the drag image. The coordinate is relative to the upper-left corner of the window, not the client area.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

To begin a drag operation, use the ImageList_BeginDrag function.

See Also

ImageList_BeginDrag, WM_MOUSEMOVE


ImageList_DragShowNolock

The ImageList_DragShowNolock function shows or hides the image being dragged.

BOOL ImageList_DragShowNolock(

BOOL fShow
);
Parameters

fShow

Value specifying whether to show or hide the image being dragged. Specify TRUE to show the image, FALSE to hide the image.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.


ImageList_Draw

The ImageList_Draw function draws an image list item in the specified device context.

BOOL ImageList_Draw(

HIMAGELIST himl,	// handle to the image list
int i,	// index of the image to draw
HDC hdcDst,	// handle to the destination device context
int x,	// x-coordinate to draw at
int y,	// y-coordinate to draw at
UINT fStyle	// drawing style
);
Parameters

himl

Handle to the image list.

i

Specifies the index of the image to draw.

hdcDst

Handle to the destination device context.

x

Specifies the x-coordinate at which to draw within the specified device context.

y

Specifies the y-coordinate at which to draw within the specified device context.

fStyle

Flag specifying the drawing style. This parameter can be one or more of the following values:

Value	Meaning
ILD_BLEND25,  ILD_FOCUS	Draws the image, blending 25 percent with the system highlight color. This value has no effect if the image list does not contain a mask.
ILD_BLEND50,  ILD_SELECTED,  ILD_BLEND	Draws the image, blending 50 percent with the system highlight color. This value has no effect if the image list does not contain a mask.
ILD_MASK	Draws the mask.
ILD_NORMAL	Draws the image using the background color for the image list. If the background color is the CLR_NONE value, the image is drawn transparently using the mask.
ILD_TRANSPARENT	Draws the image transparently using the mask, regardless of the background color. This value has no effect if the image list does not contain a mask.
Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.


ImageList_DrawEx

The ImageList_DrawEx function draws an image list item in the specified device context. The function uses the specified drawing style and blends the image with the specified color.

BOOL ImageList_DrawEx(

HIMAGELIST himl,	// handle to the image list
int i,	// index of the image to draw
HDC hdcDst,	// handle to the destination device context
int x,	// x-coordinate to draw at
int y,	// y-coordinate to draw at
int dx,	// width of image
int dy,	// height of image
COLORREF rgbBk,	// background color of image
COLORREF rgbFg,	// foreground color of image
UINT fStyle	// drawing style
);
Parameters

himl

Handle to the image list

i

Index of the image to draw.

hdcDst

Handle to the destination device context.

x

Specifies the x-coordinate at which to draw within the specified device context.

y

Specifies the y-coordinate at which to draw within the specified device context.

dx

Specifies the width of the portion of the image to draw, relative to the upper-left corner of the image. If dx and dy are zero, the function draws the entire image. The function does not ensure that the parameters are valid.

dy

Specifies the height of the portion of the image to draw, relative to the upper-left corner of the image. If dx and dy are zero, the function draws the entire image. The function does not ensure that the parameters are valid.

rgbBk

Background color of the image. This parameter can be an application-defined RGB value or one of the following values:

Value	Meaning
CLR_NONE	No background color. The image is drawn transparently.
CLR_DEFAULT	Default background color. The image is drawn using the background color of the image list.
This parameter is used only if the image list identified by himl was created with the ILC_MASK value.

rgbFg

Foreground color of the image. This parameter can be an application-defined RGB value or one of the following values:

Value	Meaning
CLR_NONE	No blend color. The image is blended with the color of the destination device context.
CLR_DEFAULT	Default foreground color. The image is drawn using the system highlight color as the foreground color.
This parameter is used only if fStyle includes the ILD_BLEND25 or ILD_BLEND50 value.

fStyle

Flag specifying the drawing style. This parameter can be one or more of the following values:

Value	Meaning
ILD_BLEND25,  ILD_FOCUS	Draws the image, blending 25 percent with the blend color specified by rgbFG. This value has no effect if the image list does not contain a mask.
ILD_BLEND50,  ILD_SELECTED,  ILD_BLEND	Draws the image, blending 50 percent with the blend color specified by rgbFG. This value has no effect if the image list does not contain a mask.
ILD_MASK	Draws the mask.
ILD_NORMAL	Draws the image using the background color for the image list. If the background color is the CLR_NONE value, the image is drawn transparently using the mask.
ILD_TRANSPARENT	Draws the image transparently using the mask, regardless of the background color. This value has no effect if the image list does not contain a mask.
Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

RGB


ImageList_EndDrag

The ImageList_EndDrag function ends a drag operation.

BOOL ImageList_EndDrag(VOID)

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.


ImageList_ExtractIcon

The ImageList_ExtractIcon function creates an icon or cursor based on an image and mask in an image list. ImageList_ExtractIcon is a macro that calls the ImageList_GetIcon function.

HICON ImageList_ExtractIcon(

HINSTANCE hi,
HIMAGELIST himl,
int i
);
Parameters

hi

Ignored; set to zero.

himl

Handle to the image list.

i

Index of the image.

Return Values

If the function succeeds, the return value is the handle of the icon or cursor.

If the function fails, the return value is NULL.

See Also

ImageList_GetIcon


ImageList_GetBkColor

The ImageList_GetBkColor function retrieves the current background color for an image list.

COLORREF ImageList_GetBkColor(

HIMAGELIST himl
);
Parameters

himl

Handle to the image list.

Return Values

The return value is the background color.


ImageList_GetDragImage

The ImageList_GetDragImage function retrieves the temporary image list that is used for the drag image. The function also retrieves the current drag position, and the offset of the drag image relative to the drag position.

HIMAGELIST ImageList_GetDragImage(

POINT FAR *ppt,
POINT FAR *pptHotspot
);
Parameters

ppt

Pointer to a POINT structure that receives the current drag position. Can be NULL.

pptHotSpot

Pointer to a POINT structure that receives the offset of the drag image relative to the drag position. Can be NULL.

Return Values

If the function succeeds, the return value is the handle of the image list.

If the function fails, the return value is NULL.

Remarks

The temporary image list is destroyed when the ImageList_EndDrag function is called. To begin a drag operation, use the ImageList_BeginDrag function.

See Also

ImageList_BeginDrag, ImageList_EndDrag, POINT


ImageList_GetIcon

The ImageList_GetIcon function creates an icon or cursor based on an image and mask in an image list.

HICON ImageList_GetIcon(

HIMAGELIST himl,
int i,
UINT flags
);
Parameters

himl

Handle to the image list.

i

Index of the image.

flags

Combination of flags that specify the drawing style. For a list of values, see the description of the ImageList_Draw function.

Return Values

If the function succeeds, the return value is the handle of the icon or cursor.

If the function fails, the return value is NULL.

See Also

ImageList_Draw


ImageList_GetIconSize

The ImageList_GetIconSize function retrieves the dimensions of images in an image list. All images in an image list have the same dimensions.

BOOL ImageList_GetIconSize(

HIMAGELIST himl,
int FAR *cx,
int FAR *cy
);
Parameters

himl

Handle to the image list.

cx

Pointer to integer variable that receives the width, in pixels, of each image.

cy

Pointer to integer variable that receives the height, in pixels, of each image.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.


ImageList_GetImageCount

The ImageList_GetImageCount function retrieves the number of images in an image list.

int ImageList_GetImageCount(;

HIMAGELIST himl
);
Parameters

himl

Handle to the image list.

Return Values

The ImageList_GetImageCount function returns the number of images.


ImageList_GetImageInfo

The ImageList_GetImageInfo function retrieves information about an image.

BOOL ImageList_GetImageInfo(

HIMAGELIST himl,
int i,
IMAGEINFO FAR *pImageInfo
);
Parameters

himl

Handle to the image list.

i

Index of the image.

pImageInfo

Pointer to an IMAGEINFO structure that receives information about the image. The information in this structure can be used to directly manipulate the bitmaps for the image.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

IMAGEINFO


ImageList_LoadBitmap

The ImageList_LoadBitmap function creates an image list from the specified bitmap resource. ImageList_LoadBitmap is a macro that calls the ImageList_LoadImage function.

HIMAGELIST ImageList_LoadBitmap(

HINSTANCE hi,
LPCSTR lpbmp,
int cx,
int cGrow,
COLORREF crMask
);
Parameters

hi

Handle to the instance that contains the bitmap resource.

lpbmp

Name of the resource.

cx

Width of each image. The height of each image and the initial number of images are inferred by the dimensions of the specified bitmap.

cGrow

Amount of images by which the image list can grow when the system needs to resize the list to make room for new images. This parameter represents the number of new images that the resized image list can contain.

crMask

Color used to generate a mask. Each pixel of this color in the specified bitmap is changed to black, and the corresponding bit in the mask is set to one. If this parameter is the CLR_NONE value, no mask is generated.

Return Values

If the function succeeds, the return value is the image list.

If the function fails, the return value is NULL.

See Also

ImageList_LoadImage


ImageList_LoadImage

The ImageList_LoadImage function creates an image list from the specified bitmap, cursor, or icon resource.

HIMAGELIST ImageList_LoadImage(

HINSTANCE hi,
LPCSTR lpbmp,
int cx,
int cGrow,
COLORREF crMask,
UINT uType,
UINT uFlags
);
Parameters

hi

Handle to the instance that contains the resource.

If the hi parameter is zero, the low-order word of this parameter must be the identifier of the OEM image to load. The OEM image identifiers are defined in WINUSER.H. Following are the identifier prefixes and their meanings:

Prefix	Meaning
OBM_	OEM bitmaps
OIC_	OEM icons
OCR_	OEM cursors
lpbmsp

Pointer to a null-terminated string that contains the name of the image to load.

If the uFlags parameter specifies the LR_LOADFROMFILE value, the lpbmp parameter must be the name of the file that contains the image.

cx

Width of each image. The height of each image and the initial number of images are inferred by the dimensions of the specified resource.

cGrow

Amount of images by which the image list can grow when the system needs to resize the list to make room for new images. This parameter represents the number of new images that the resized image list can contain.

crMask

Color used to generate a mask. Each pixel of this color in the specified bitmap, cursor, or icon is changed to black, and the corresponding bit in the mask is set to 1. If this parameter is the CLR_NONE value, no mask is generated.

uType

Flag that specifies the type of image to load. This parameter can be one of the following values:

Value	Meaning
IMAGE_BITMAP	Loads a bitmap.
IMAGE_CURSOR	Loads a cursor.
IMAsssGE_ICON	Loads an icon.
uFlags

Flags that specify how to load the image. This parameter can be a combination of the following values:

Value	Meaning
LR_DEFAULTCOLOR	Uses the color format of the display.
LR_LOADDEFAULTSIZE	Uses the width or height specified by the system metric values for cursors and icons if the cx parameter is set to zero. If this value is not specified and cx is set to zero, the function sets the size to that specified in the resource. If the resource contains multiple images, the function sets the size to that of the first image.
LR_LOADFROMFILE	Loads the image from the file specified by the lpbmp parameter.
LR_LOADMAP3DCOLORS	Searches the color table for the image and replaces the following shades of gray with the corresponding three-dimensional color:
Dk Gray, RGB(128, 128, 128)	COLOR_3DSHADOW
Gray,  RGB(192, 192, 192)	COLOR_3DFACE
Lt Gray,  RGB(223, 223, 223)	COLOR_3DLIGHT
LR_LOADTRANSPARENT	Retrieves the color value of the first pixel in the image and replaces the corresponding entry in the color table with the default window color (the COLOR_WINDOW display color). All pixels in the image that use that entry become the default window value color. This value applies only to images that have corresponding color tables.
LR_MONOCHROME	Loads the image in black and white.
LR_SHARED	Shares the image handle if the image is loaded multiple times. Do not use this value for images that have nontraditional sizes that might change after loading or for images that are loaded from a file.
Return Values

If the function succeeds, the return value is the handle of the image list.

If the function fails, the return value is NULL.

See Also

RGB


ImageList_Merge

The ImageList_Merge function creates a new image by combining two existing images. The function also creates a new image list to store the image.

HIMAGELIST ImageList_Merge(

HIMAGELIST himl1,
int i1,
HIMAGELIST himl2,
int i2,
int dx,
int dy
);
Parameters

himl1

Handle to the first image list.

i1

Index of the first existing image.

himl2

Handle to the second image list.

i2

Index of the second existing image.

dx and dy

Offset of the second image relative to the first image.

Return Values/*

If the function succeeds, the return value is the handle of the new image list.

If the function fails, the return value is NULL.

Remarks

The new image consists of the second existing image drawn transparently over the first. The mask for the new image is the result of performing a logical OR operation on the masks of the two existing images.


ImageList_Read

The ImageList_Read function reads an image list from a stream.

HIMAGELIST ImageList_Read(

LPSTREAM pstm
);
Parameters

pstm

Pointer to the stream.

Return Values

If the function succeeds, the return value is the image list.

If the function fails, the return value is NULL.


ImageList_Remove

The ImageList_Remove function removes an image from an image list.

BOOL ImageList_Remove(

HIMAGELIST himl,
int i
);
// Related macro

BOOL ImageList_RemoveAll(himl);

Parameters

himl

Handle to the image list.

i

Index of the image to remove. If the i parameter is  − 1, the function removes all images.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.


ImageList_Replace

The ImageList_Replace function replaces an image in an image list with a new image.

BOOL ImageList_Replace(

HIMAGELIST himl,
int i,
HBITMAP hbmImage,
HBITMAP hbmMask
);
Parameters

himl

Handle to the image list.

i

Index of the image to replace.

hbmImage

Handle to the bitmap that contains the image.

hbmMask

Handle to the bitmap that contains the mask. If no mask is used with the image list, this parameter is ignored.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The ImageList_Replace function copies the bitmap to an internal data structure. Be sure to use the DeleteObject function to delete hbmImage and hbmMask after the function returns.

See Also

DeleteObject


ImageList_ReplaceIcon

The ImageList_ReplaceIcon function replaces an image with an icon or cursor.

int ImageList_ReplaceIcon(

HIMAGELIST himl,
int i,
HICON hicon
);
Parameters

himl

Handle to the image list.

i

Index of the image to replace.

hicon

Handle to the icon or cursor that contains the bitmap and mask for the new image.

Return Values

If the function succeeds, the return value is the index of the image.

If the function fails, the return value is  − 1.

Remarks

Because the system does not save hicon, you can destroy it after the function returns if the icon or cursor was created by the CreateIcon function. You do not need to destroy hicon if it was loaded by the LoadIcon function; the system automatically frees an icon resource when it is no longer needed.

See Also

CreateIcon, LoadIcon


ImageList_SetBkColor

The ImageList_SetBkColor function sets the background color for an image list.

COLORREF ImageList_SetBkColor(

HIMAGELIST himl,
COLORREF clrBk
);
Parameters

himl

Handle to the image list.

clrBk

Background color to set. This parameter can be the CLR_NONE value; in that case, images are drawn transparently using the mask.

Return Values

If the function succeeds, the return value is the previous background color.

If the function fails, the return value is the CLR_NONE value.


ImageList_SetDragCursorImage

The ImageList_SetDragCursorImage function creates a new drag image by combining the specified image (typically a mouse cursor image) with the current drag image.

BOOL ImageList_SetDragCursorImage(

HIMAGELIST himlDrag,
int iDrag,
int dxHotspot,
int dyHotspot
);
Parameters

himlDrag

Handle to the image list that contains the new image to combine with the drag image.

iDrag

Index of the new image to combine with the drag image.

dxHotspot and dyHotspot

Position of the hot spot within the new image.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.


ImageList_SetIconSize

The ImageList_SetIconSize function sets the dimensions of images in an image list and removes all images from the list.

BOOL ImageList_SetIconSize(

HIMAGELIST himl,
int cx,
int cy
);
Parameters

himl

Handle to the image list.

cx

Width, in pixels, of the images in the image list. All images in an image list have the same dimensions.

cy

Height, in pixels, of the images in the image list. All images in an image list have the same dimensions.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.


ImageList_SetOverlayImage

The ImageList_SetOverlayImage function adds the index of an image to the list of images to be used as overlay masks. Up to four indices can be added to the list.

BOOL ImageList_SetOverlayImage(

HIMAGELIST himl,
int iImage,
int iOverlay
);
Parameters

himl

Handle to the image list.

iImage

Image to use as an overlay mask.

iOverlay

One-based index of the overlay mask.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

An overlay mask is an image drawn transparently over another image. You draw an overlay mask over an image by using the ImageList_Draw or ImageList_DrawEx function with the index of the overlay mask. The index must be specified by using the INDEXTOOVERLAYMASK macro.

See Also

ImageList_Draw, ImageList_DrawEx, INDEXTOOVERLAYMASK


ImageList_Write

The ImageList_Write function writes an image list to a stream.

BOOL ImageList_Write(

HIMAGELIST himl,	// handle to the image list
LPSTREAM pstm	// pointer to the stream to write to
);
Parameters

himl

Handle to the image list.

pstm

Pointer to the stream.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.


ImmAssociateContext [Now Supported on Windows NT]
ImmAssociateContext

[Now Supported on Windows NT]

The ImmAssociateContext function associates the specified input context with the specified window. If hIMC is NULL, the function removes any association the window may have with an input context. By default, the system associates the default input context with each window as it is created.

HIMC ImmAssociateContext(

HWND hWnd,
HIMC hIMC
);
Parameters

hWnd

Handle to the window to be associated with the input context.

hIMC

Handle to the input context.

Return Values

Returns the handle to the input context previously associated with the window.

Remarks

If an application associates an input context with a window, the application must remove that association before destroying the input context. One way to do this is to save and reassociate the handle to the default input context with the window.


ImmConfigureIME [Now Supported on Windows NT]
ImmConfigureIME

[Now Supported on Windows NT]

The ImmConfigureIME function displays the configuration dialog box for the IME.

BOOL ImmConfigureIME(

HKL hKL,
HWND hWnd,
DWORD dwMode,
LPVOID lpdata
);
Parameters

hKL

Handle to the keyboard layout.

hWnd

Handle to the parent window for the dialog box.

dwMode

Type of dialog box to display. This parameter can be one of the following values:

Value	Meaning
IME_CONFIG_GENERAL	Displays general purpose configuration dialog box.
IME_CONFIG_REGWORD	Displays register word dialog box.
IME_CONFIG_SELECTDICTIONARY	Displays dictionary selection dialog box.
lpData

Pointer to supplemental data. If dwMode is IME_CONFIG_REGWORD, this parameter must be the address of a REGISTERWORD structure.

If dwMode is not IME_CONFIG_REGWORD, this parameter is ignored.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

The ImmConfigureIME function is called by the Control Panel.


ImmCreateContext [Now Supported on Windows NT]
ImmCreateContext

[Now Supported on Windows NT]

The ImmCreateContext function creates a new input context, allocating memory for the context and initializing it. An application calls this function to prepare its own input context.

HIMC ImmCreateContext(void);

Return Values

If the function succeeds, the return value is the handle to the new input context.

If the function fails, the return value is NULL.


ImmDestroyContext [Now Supported on Windows NT]
ImmDestroyContext

[Now Supported on Windows NT]

The ImmDestroyContext function releases the input context and frees any memory associated with it.

BOOL ImmDestroyContext(

HIMC hIMC
);
Parameters

hIMC

Handle to the input context to free.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

Any application that creates an input context by using the ImmCreateContext function must call this function to free the context before it terminates.

See Also

ImmCreateContext


ImmEnumRegisterWord [Now Supported on Windows NT]
ImmEnumRegisterWord

[Now Supported on Windows NT]

The ImmEnumRegisterWord function enumerates the register strings having the specified reading string, style, and register string.

UINT ImmEnumRegisterWord(

HKL hKL,
REGISTERWORDENUMPROC lpfnEnumProc,
LPCTSTR lpszReading,
DWORD dwStyle,
LPCTSTR lpszRegister,
LPVOID lpData
);
Parameters

hKL

Handle to the keyboard layout.

lpfnEnumProc

Pointer to the callback function. For more information, see EnumRegisterWordProc.

lpszReading

Pointer to the reading string to be enumerated. If NULL, this function enumerates all available reading strings that match with the specified dwStyle and lpszRegister.

dwStyle

Style to be enumerate. If zero, this function enumerates all available styles that match with the specified lpszReading and lpszRegister.

lpszRegister

Pointer to the register string to enumerate. If NULL, this function enumerates all register strings that match with the specified lpszReading and dwStyle.

lpData

Application-supplied data. The function passes this parameter to the callback function.

Return Values

Returns the last value return by the callback function. Its meaning is defined by the application. The function returns zero if it cannot enumerate the register strings.

Remarks

If dwStyle is zero and both lpszReading and lpszRegister are NULL, the ImmEnumRegisterWord function enumerates all register strings in the IME dictionary.

See Also

EnumRegisterWordProc


ImmEscape [Now Supported on Windows NT]
ImmEscape

[Now Supported on Windows NT]

The ImmEscape function carries out IME-specific subfunctions and is used mainly for country-specific functions.

LRESULT ImmEscape(

HKL hKL,
HIMC hIMC,
UINT uEscape,
LPVOID lpData
);
Parameters

hKL

Handle to the keyboard layout.

hIMC

Handle to the input context.

uEscape

Index of the subfunction. For more information about the escape, see the “IME Escapes” table in Input Method Editor Constants.

lpData

Subfunction-specific data.

Return Values

Returns zero on error; otherwise, returns an escape-specific value.


ImmGetCandidateList [Now Supported on Windows NT]
ImmGetCandidateList

[Now Supported on Windows NT]

The ImmGetCandidateList function retrieves a specified candidate list, copying the list to the specified buffer.

DWORD ImmGetCandidateList(

HIMC hIMC,
DWORD deIndex,
LPCANDIDATELIST lpCandList,
DWORD dwBufLen
);
Parameters

hIMC

Handle to the input context.

deIndex

Zero-based index of the candidate list.

lpCandList

Pointer to the CANDIDATELIST structure that receives the candidate list.

dwBufLen

Size of the buffer, in bytes. If zero, the function returns the size in bytes required to receive the complete candidate list.

Return Values

If the function succeeds, the return value is the number of bytes copied to the specified buffer.

If the function fails, the return value is zero.

See Also

CANDIDATELIST


ImmGetCandidateListCount [Now Supported on Windows NT]
ImmGetCandidateListCount

[Now Supported on Windows NT]

The ImmGetCandidateListCount function retrieves the size, in bytes, of the candidate lists.

DWORD ImeGetCandidateListCount(

HIMC hIMC,
LPDWORD lpdwListCount
);
Parameters

hIMC

Handle to the input context.

lpdwListCount

Pointer to the 32-bit variable that receives the size of the candidate lists.

Return Values

Returns the number of bytes required to receive all candidate lists.

Remarks

Applications typically call this function in response to a IMN_OPENCANDIDATE or IMN_CHANGECANDIDATE message.

See Also

IMN_CHANGECANDIDATE, IMN_OPENCANDIDATE


ImmGetCandidateWindow [Now Supported on Windows NT]
ImmGetCandidateWindow

[Now Supported on Windows NT]

The ImmGetCandidateWindow function gets information about the candidate list window.

BOOL ImmGetCandidateWindow(

HIMC hIMC,
DWORD dwBufLen,
LPCANDIDATEFORM lpCandidate
);
Parameters

hIMC

Handle to the input context.

dwBufLen

Size, in bytes, of the buffer that receives the information.

lpCandidate

Pointer to the CANDIDATEFORM structure that receives information about the candidate window.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

See Also

CANDIDATEFORM


ImmGetCompositionFont [Now Supported on Windows NT]
ImmGetCompositionFont

[Now Supported on Windows NT]

The ImmGetCompositionFont function retrieves information about the logical font currently used to display characters in the composition window.

BOOL ImmGetCompositionFont(

HIMC hIMC,
LPLOGFONT lplf
);
Parameters

hIMC

Handle to the input context.

lplf

Pointer to a LOGFONT structure that receives the font information.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

See Also

LOGFONT


ImmGetCompositionString [Now Supported on Windows NT]
ImmGetCompositionString

[Now Supported on Windows NT]

The ImmGetCompositionString function retrieves information about the composition string.

LONG ImmGetCompositionString(

HIMC hIMC,
DWORD dwIndex,
LPVOID lpBuf,
DWORD dwBufLen
);
Parameters

hIMC

Handle to the input context.

dwIndex

Index of the information to retrieve. This parameter can be one of the values given in the “IME Composition String Values” table in Input Method Editor Constants. For each value except GCS_CURSORPOS and GCS_DELTASTART, the function copies the requested information to the specified buffer. The function returns the cursor and delta position values in the low 16-bits of the return value.

lpBuf

Pointer to the buffer that receives the requested information.

dwBufLen

Size of the buffer, in bytes. If zero, the ImmGetCompositionString function returns the buffer size needed for the complete information.

Return Values

Returns the number of bytes copied to the destination buffer or, if dwBufLen is zero, the buffer size, in bytes, needed to receive all of the requested information. On an error, the function returns one of the following negative error values:

Value	Meaning
IMM_ERROR_NODATA	Composition data is not ready in the input context.
IMM_ERROR_GENERAL	General error detected by IME.
Remarks

An application calls this function in response to the WM_IME_COMPOSITION or WM_IME_STARTCOMPOSITION message. The IMM removes the information when an application calls the ImmReleaseContext function.

See Also

ImmReleaseContext, WM_IME_COMPOSITION


ImmGetCompositionWindow [Now Supported on Windows NT]
ImmGetCompositionWindow

[Now Supported on Windows NT]

The ImmGetCompositionWindow function gets information about the composition window.

BOOL ImmGetCompositionWindow(

HIMC hIMC,
LPCOMPOSITIONFORM lpCompForm
);
Parameters

hIMC

Handle to the input context.

lpCompForm

Pointer to the COMPOSITIONFORM structure that receives information about the composition window.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

See Also

COMPOSITIONFORM


ImmGetContext [Now Supported on Windows NT]
ImmGetContext

[Now Supported on Windows NT]

The ImmGetContext function retrieves the input context associated with the specified window.

HIMC ImmGetContext(

HWND hWnd
);
Parameters

hWnd

Handle to the window to retrieve the input context for.

Return Values

Returns the handle to the input context.

Remarks

An application should routinely use this function to retrieve the current input context before attempting to access information in the context.


ImmGetConversionList [Now Supported on Windows NT]
ImmGetConversionList

[Now Supported on Windows NT]

The ImmGetConversionList function retrieves the list of characters or words from one character or word.

UINT ImmGetConversionList(

HKL hKL,
HIMC hIMC,
LPCTSTR lpSrc,
LPCANDIDATELIST lpDst,
DWORD dwBufLen,
UINT uFlag
);
Parameters

hKL

Handle to the keyboard layout.

hIMC

Handle to the input context.

lpSrc

Pointer to a null-terminated character string.

lpDst

Pointer to the CANDIDATELIST structure that receives the conversion result.

dwBufLen

Size of the destination buffer, in bytes. If zero, the function returns the buffer size needed for the complete conversion result.

uFlag

Action flag. This parameter can be one of the following values:

Value	Meaning
GCL_CONVERSION	Source string is the reading string. The function copies the result string to the destination buffer.
GCL_REVERSECONVERSION	Source string is the result string. The function copies the reading string to the destination buffer.
GCL_REVERSE_LENGTH	Source string is the result string. The function returns the size in bytes of the reading string that would be created if GCL_REVERSECONVERSION were given.
Return Values

Returns the number of bytes copied to the specified buffer or, if dwBufLen is zero, the buffer size needed to receive the list.

See Also

CANDIDATELIST


ImmGetConversionStatus [Now Supported on Windows NT]
ImmGetConversionStatus

[Now Supported on Windows NT]

The ImmGetConversionStatus function gets the current conversion status.

BOOL ImmGetConversionStatus(

HIMC hIMC,
LPDWORD lpfdwConversion,
LPDWORD lpfdwSentence
);
Parameters

hIMC

Handle to the input context for which to retrieve information.

lpfdwConversion

Pointer to a 32-bit variable that receives a combination of conversion mode values. For more information, see the “IME Conversion Mode Values” table in Input Method Editor Constants.

lpfdwSentence

Pointer to a 32-bit variable that receives a sentence mode value. For more information, see the “IME Sentence Mode Values” table in Input Method Editor Constants.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

Conversion and sentence mode values are set only if the IME supports those modes.


ImmGetDefaultIMEWnd [Now Supported on Windows NT]
ImmGetDefaultIMEWnd

[Now Supported on Windows NT]

The ImmGetDefaultIMEWnd function gets the default window handle to the IME class.

HWND ImmGetDefaultIMEWnd(

HWND hWnd
);
Parameters

hWnd

Handle to the window for the application.

Return Values

If the function succeeds, the return value is the default window handle to the IME class.

If the function fails, the return value is NULL.

Remarks

The system creates a default IME window for every thread. The IME window is created based on the IME class. The application can send WM_IME_CONTROL to this window.

See Also

WM_IME_CONTROL


ImmGetDescription [Now Supported on Windows NT]
ImmGetDescription

[Now Supported on Windows NT]

The ImmGetDescription function copies the description of the IME to the specified buffer.

UINT ImmGetDescription(

HKL hKL,
LPTSTR lpszDescription,
UINT uBufLen
);
Parameters

hKL

Handle to the keyboard layout.

lpszDescription

Pointer to the buffer that receives the null-terminated string describing the IME.

uBufLen

Size of the buffer, in bytes. If zero, the function returns the buffer size needed for the complete description, not including terminating null character.

Return Values

Returns the number of bytes copied to the buffer or, if uBufLen is zero, the buffer size in bytes needed to receive the description. Neither value includes the terminating null character.


ImmGetGuideLine [Now Supported on Windows NT]
ImmGetGuideLine

[Now Supported on Windows NT]

The ImmGetGuideLine function gets information about errors. Applications use the information to notify users.

DWORD ImmGetGuideLine(dwBufLen

HIMC hIMC,
DWORD dwIndex,
LPTSTR lpBuf,
DWORD dwBufLen
);
Parameters

hIMC

Handle to the input context.

dwIndex

Type of guideline information to retrieve. Can be one of the following values:

Value	Meaning
GGL_LEVEL	Returns the error level.
GGL_INDEX	Returns the error index.
GGL_STRING	Retrieves the error message string.
GGL_PRIVATE	Returns information about reverse conversion.
lpBuf

Pointer to the buffer that receives the error message string. This parameter can be NULL if dwIndex is not GGL_STRING or GGL_PRIVATE if dwBufLen is zero.

dwBufLen

Size, in bytes, of the buffer pointed to by lpBuf. If zero, the function returns the buffer size needed to receive the error message string, not including the terminating null character.

Return Values

The return value is an error level, an error index, or the size of an error message string, depending on the value of the dwIndex parameter. If dwIndex is GGL_LEVEL, the return value is one of the following:

Value	Meaning
GL_LEVEL_ERROR	Error. The IME may not be able to continue.
GL_LEVEL_FATAL	Fatal error. The IME cannot continue, and data may be lost.
GL_LEVEL_INFORMATION	No error, but information is available for the user.
GL_LEVEL_NOGUIDELINE	No error. Remove previous error message if still visible.
GL_LEVEL_WARNING	Unexpected input or other result. The user should be warned, but the IME can continue.
If dwIndex is GGL_INDEX, the return value is one of the following:

Value	Meaning
GL_ID_CANNOTSAVE	The dictionary or the statistics data cannot be saved.
GL_ID_NOCONVERT	The IME cannot convert any more.
GL_ID_NODICTIONARY	The IME cannot find the dictionary, or the dictionary has an unexpected format.
GL_ID_NOMODULE	The IME can not find the module that IME needs.
GL_ID_READINGCONFLICT	For example, some vowels cannot put together.
GL_ID_TOOMANYSTROKE	There are too many strokes for one character or one clause.
GL_ID_TYPINGERROR	Typing error. The IME can not handle this typing.
GL_ID_UNKNOWN	Unknown error. The application should refer to the error message string.
GL_ID_INPUTREADING	IME accepts reading character input.
GL_ID_INPUTRADICAL	IME accepts radical character input.
GL_ID_INPUTCODE	IME accepts character code input.
GL_ID_CHOOSECANDIDATE	IME accepts candidate string selection.
GL_ID_REVERSECONVERSION	Information about reverse conversion is available.
If dwIndex is GGL_STRING, the return value is the number of bytes of the string copied to the buffer, or if dwBufLen is zero, the return value is the buffer size needed to receive the string.

If dwIndex is GGL_PRIVATE, the return value is the number of bytes of information copied to the buffer. If dwIndex is GGL_PRIVATE and dwBufLen is zero, the return value is the buffer size needed to receive the information.

Remarks

Applications typically call this function after receiving an IMN_GUIDELINE message.


ImmGetIMEFileName [Now Supported on Windows NT]
ImmGetIMEFileName

[Now Supported on Windows NT]

The ImmGetIMEFileName function gets the filename of the IME associated with the specified keyboard layout.

BOOL ImmGetIMEFileName(

HKL hKL,
LPTSTR lpszFileName,
UINT uBufLen
);
Parameters

hKL

Handle to the keyboard layout.

lpszFileName

Pointer to the buffer that receives the filename.

uBufLen

Size in bytes of the buffer. If zero, the function returns the buffer size in bytes needed to receive the filename, not including the termintaing null character.

Return Values

The return value is the number of bytes in the filename copied to the buffer, or if uBufLen is zero, the return value is the buffer size needed for the filename. In either case, the terminating null character is not included.

Remarks

In the registry, the system stores the filename as the IME name value in HKEY_LOCAL_MACHINE root under the \System\CurrentControlSet\control\keyboard layouts\hKL key.


ImmGetOpenStatus [Now Supported on Windows NT]
ImmGetOpenStatus

[Now Supported on Windows NT]

The ImmGetOpenStatus function checks whether the IME is open or closed.

BOOL WINAPI ImmGetOpenStatus(

HIMC hIMC
);
Parameters

hIMC

Handle to the input context.

Return Values

The return value is a nonzero value if the IME is open, FALSE otherwise.


ImmGetProperty [Now Supported on Windows NT]
ImmGetProperty

[Now Supported on Windows NT]

The ImmGetProperty function gets the property and capabilities of the IME associated with the specified keyboard layout.

BOOL ImmGetProperty(

HKL hKL,
DWORD fdwIndex
);
Parameters

hKL

Handle to the keyboard layout.

fdwIndex

Type of property information to retrieve. This parameter can be one of the following values:

Value	Meaning
IGP_PROPERTY	Property information.
IGP_CONVERSION	Conversion capabilities.
IGP_SENTENCE	Sentence mode capabilities.
IGP_UI	User interface capabilities.
IGP_SETCOMPSTR	Composition string capabilities.
IGP_SELECT	Selection inheritance capabilities.
IGP_GETIMEVERSION	Retrieves the Windows version number for which the specified IME was created.
Return Values

Returns the property or capability value, depending on the value of the dwIndex parameter. If dwIndex is IGP_PROPERTY, returns a combination of the following values:

Value	Meaning
IME_PROP_AT_CARET	If set, conversion window is at the caret position. If clear, the window is near caret position.
IME_PROP_SPECIAL_UI	If set, IME has a nonstandard user interface. The application should not draw in the IME window.
IME_PROP_CANDLIST_START_FROM_1	If set, strings in the candidate list are numbered starting at 1. If clear, strings start at 0.
IME_PROP_UNICODE	If set, strings for the input context have Unicode characters. If clear, strings have single and double-byte characters.
If dwIndex is IGP_UI, the return value is a combination of the following values:

Value	Meaning
UI_CAP_2700	Supports text escapement values of 0 or 2700.
UI_CAP_ROT90	Supports text escapement values of 0, 900, 1800, or 2700.
UI_CAP_ROTANY	Supports any text escapement value.
If dwIndex is IGP_SETCOMPSTR, the return value is a combination of the following values:

Value	Meaning
SCS_CAP_COMPSTR	Can create the composition string by using the SCS_SETSTR value of the ImmSetCompositionString function.
SCS_CAP_MAKEREAD	Can create the reading string from corresponding composition string when using the SCS_SETSTR value of the ImmSetCompositionString function.
If dwIndex is IGP_SELECT, the return value is a combination of the following values:

Value	Meaning
SELECT_CAP_CONVMODE	Inherits conversion mode when a new IME is selected.
SELECT_CAP_SENTENCE	Inherits sentence mode when a new IME is selected.
If dwIndex is IGP_GETIMEVERSION, the return value is one of the following values:

Value	Meaning
IMEVER_0310	The IME was created for Windows 3.1
IMEVER_0400	The IME was created for Windows 95.


ImmGetRegisterWordStyle [Now Supported on Windows NT]
ImmGetRegisterWordStyle

[Now Supported on Windows NT]

The ImmGetRegisterWordStyle function gets a list of the styles support by the IME associated with the specified keyboard layout.

UINT ImmGetRegisterWordStyle(

HKL hKL,
UINT nItem,
LPSTYLEBUF lpStyleBuf
);
Parameters

hKL

Handle to the keyboard layout.

nItem

Maximum number of styles that the buffer can hold.

lpStyleBuf

Pointer to the STYLEBUF structure that receives the style information.

Return Values

The return value is the number of layout handles copied to the buffer, or if nItems is zero, the return value is the buffer size in array elements needed to receive all available style information.

See Also

STYLEBUF


ImmGetStatusWindowPos [Now Supported on Windows NT]
ImmGetStatusWindowPos

[Now Supported on Windows NT]

The ImmGetStatusWindowPos function gets the position of the status window.

BOOL ImmGetStatusWindowPos(

HIMC hIMC,
LPPOINT lpptPos
);
Parameters

hIMC

Handle to the input context.

lpptPos

Pointer to the POINT structure that receives the position coordinates. These are screen coordinates, relative to the upper-left corner of the screen.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

See Also

POINT


ImmGetVirtualKey [Now Supported on Windows NT]
ImmGetVirtualKey

[Now Supported on Windows NT]

The ImmGetVirtualKey function recovers the original virtual-key value associated with a key input message that has already been processed by the IME.

UINT ImmGetVirtualKey(

HWND hWnd
);
Parameters

hWnd

Handle to the window that receives the key message.

Return Values

The return value is the original virtual-key value.

Remarks

Although the IME sets the virtual-key value to VK_PROCESSKEY after processing a key input message, an application can recover the original virtual-key value with the ImmGetVirtualKey function. This function can be used only for key input messages containing the VK_PROCESSKEY value.


ImmInstallIME [Now Supported on Windows NT]
ImmInstallIME

[Now Supported on Windows NT]

The ImmInstallIME function installs an IME into the system.

HKL ImmInstallIME(

LPCTSTR lpszIMEFileName,
LPCTSTR lpszLayoutText
);
Parameters

lpszIMEFileName

Pointer to a null-terminated string that specifies the full path of the IME.

lpszLayoutText

Pointer to a null-terminated string that specifies the name of the IME. This name also specifies the layout text of the IME.

Return Values

The return value is the handle to the keyboard layout for the IME.

Remarks

This function is intended to be used by IME setup programs only.


ImmIsIME [Now Supported on Windows NT]
ImmIsIME

[Now Supported on Windows NT]

The ImmIsIME function checks whether the specified handle identifies an IME.

BOOL ImmIsIME(

HKL hKL
);
Parameters

hKL

Handle to the keyboard layout to check.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.


ImmIsUIMessage [Now Supported on Windows NT]
ImmIsUIMessage

[Now Supported on Windows NT]

The ImmIsUIMessage function checks for messages intended for the IME window and sends those messages to the specified window.

BOOL ImmIsUIMessage(

HWND hWndIME,
UINT msg,
WPARAM wParam,
LPARAM lParam
);
Parameters

hWndIME

Handle to a window belonging to the IME window class.

msg

Message to check.

wParam

32-bit message-specific parameter.

lParam

32-bit message-specific parameter.

Return Values

If the message is processed by the IME window, the return value is a nonzero value.

If the message is not processed by the IME window, the return value is zero.

Remarks

An application typically uses this function to display any composition string or candidate list specified by IME. If hWndIME is NULL, the function checks whether the message is a user interface message.


ImmNotifyIME [Now Supported on Windows NT]
ImmNotifyIME

[Now Supported on Windows NT]

The ImmNotifyIME function notifies the IME about changes to the status of the input context.

BOOL ImmNotifyIME(

HIMC hIMC,
DWORD dwAction,
DWORD dwIndex,
DWORD dwValue
);
Parameters

hIMC

Handle to the input context.

dwAction

Notification code. This parameter can be one of the following values:

Value	Meaning
NI_CHANGECANDIDATELIST	An application changed the current selected candidate; dwIndex is an index of a candidate list to be selected and dwValue is not used.
NI_CLOSECANDIDATE	An application directs the IME to close a candidate list; dwIndex is the index of the list to close; dwValue is not used. The IME sends a IMN_CLOSECANDIDATE message to the application if it closes the list.
NI_COMPOSITIONSTR	An application directs the IME to carry out an action on the composition string; dwValue is not used and dwIndex can be CPS_CANCEL, CPS_COMPLETE, CPS_CONVERT, or CPS_REVERT.
NI_OPENCANDIDATE	An application directs the IME to open a candidate list; dwIndex is the index of the list to open; dwValue is not used. The IME sends a IMN_OPENCANDIDATE message to the application if it opens the list.
NI_SELECTCANDIDATESTR	An application selected one of candidates; dwIndex is an index of a candidate list to be selected and dwValue is an index of a candidate string in the selected candidate list.
NI_SETCANDIDATE_PAGESIZE	The dwIndex parameter specifies the candidate list to be changed and must have a value in the range 0 to 31.
NI_SETCANDIDATE_PAGESTART	The dwIndex parameter specifies the candidate list to be changed and must have a value in the range 0 to 31.
dwIndex

Index of a candidate list or, if dwAction is NI_COMPOSITIONSTR, one of the following values:

Value	Meaning
CPS_CANCEL	Clear the composition string and set the status to no composition string.
CPS_COMPLETE	Set the composition string as the result string.
CPS_CONVERT	Convert the composition string.
CPS_REVERT	Cancel the current composition string and revert to the unconverted string.
dwValue

Index of a candidate string or not used, depending on the value of the dwAction parameter.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.


ImmRegisterWord [Now Supported on Windows NT]
ImmRegisterWord

[Now Supported on Windows NT]

The ImmRegisterWord function registers a string into the dictionary of the IME associated with the specified keyboard layout.

BOOL ImmRegisterWord(

HKL hKL,
LPCTSR lpszReading,
DWORD dwStyle,
LPCTSTR lpszRegister
);
Parameters

hKL

Handle to the keyboard layout.

lpszReading

Pointer to a null-terminated string specifying the reading string associated with the string to register.

dwStyle

Style of the register string. This parameter can be IME_REGWORD_STYLE_EUDC to indicate the string is in the EUDC range, or any value in the reserved range IME_REGWORD_STYLE_USER_FIRST to IME_REGWORD_STYLE_USER_LAST to indicate a private style maintained by the specified IME.

lpszRegister

Pointer to a null-terminated string specifying the string to register.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.


ImmReleaseContext [Now Supported on Windows NT]
ImmReleaseContext

[Now Supported on Windows NT]

The ImmReleaseContext function releases the input context and unlocks the memory associated in the context. An application must call this function for each call to the ImmGetContext function.

BOOL ImmReleaseContext(

HWND hWnd,
HIMC hIMC
);
Parameters

hWnd

Handle to the window for which the input context was previously retrieved.

hIMC

Handle to the input context.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

See Also

ImmGetContext


ImmSetCandidateWindow [Now Supported on Windows NT]
ImmSetCandidateWindow

[Now Supported on Windows NT]

The ImmSetCandidateWindow function sets information about the candidate list window.

BOOL ImmSetCandidateWindow(

HIMC hIMC,
LPCANDIDATEFORM lpCandidate
);
Parameters

hIMC

Handle to the input context.

lpCandidate

Pointer to the CANDIDATEFORM structure that contains information about the candidate window.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

ImmSetCandidateWindow causes an IMN_SETCANDIDATEPOS message to be sent to the application.

See Also

CANDIDATEFORM


ImmSetCompositionFont [Now Supported on Windows NT]
ImmSetCompositionFont

[Now Supported on Windows NT]

The ImmSetCompositionFont function sets the logical font to be used to display characters in the composition window.

BOOL ImmSetCompositionFont(

HIMC hIMC,
LPLOGFONT lplf
);
Parameters

hIMC

Handle to the input context.

lplf

Pointer to the LOGFONT structure containing the font information to set.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

Even if an application never uses the composition window, it must set the appropriate font to ensure that characters are displayed properly. This is especially true for vertical writing.

This function causes a IMN_SETCOMPOSITIONFONT message to be sent to the application.

See Also

IMN_SETCOMPOSITIONFONT, LOGFONT


ImmSetCompositionString [Now Supported on Windows NT]
ImmSetCompositionString

[Now Supported on Windows NT]

The ImmSetCompositionString function sets the characters, attributes, and clauses of the composition and reading strings.

BOOL ImmSetCompositionString(

HIMC hIMC,
DWORD dwIndex,
LPCVOID lpComp,
DWORD dwCompLen,
LPCVOID lpRead,
DWORD dwReadLen
);
Parameters

hIMC

Handle to the input context.

dwIndex

Type of information to set. This parameter can be one of one of the following values:

Value	Meaning
SCS_SETSTR	Sets the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must point to a valid string. If either string is too long, the IME truncates it.
SCS_CHANGEATTR	Sets attributes for the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must point to a valid attribute array.
SCS_CHANGECLAUSE	Sets the clause information for the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must point to a valid clause information array.
lpComp

Pointer to the buffer containing the information to set for the composition string. The information is as specified by the dwIndex value.

dwCompLen

Size in bytes of the information buffer for the composition string.

lpRead

Pointer to the buffer containing the information to set for the reading string. The information is as specified by the dwIndex value.

dwReadLen

Size, in bytes, of the information buffer for the reading string.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

When changing attributes, all characters in a clause must have the same attribute. Converted characters must be either ATTR_CONVERTED or ATTR_TARGET_CONVERTED; unconverted characters either ATTR_INPUT or ATTR_TARGET_NOTCONVERTED.

When changing clause information, only the target clause can be changed and only one boundary of the clause can be changed at a time. The target clause has the ATTR_TARGET_CONVERTED or ATTR_TARGET_NOTCONVERTED attribute.

When the IME completes the changes, it sends a WM_IME_COMPOSITION message to the application notifying it of the changes.

See Also

WM_IME_COMPOSITION


ImmSetCompositionWindow [Now Supported on Windows NT]
ImmSetCompositionWindow

[Now Supported on Windows NT]

The ImmSetCompositionWindow function sets the position of the composition window.

BOOL ImmSetCompositionWindow(

HIMC hIMC,
LPCOMPOSITIONFORM lpCompForm
);
Parameters

hIMC

Handle to the input context.

lpCompForm

Pointer to the COMPOSITIONFORM structure that contains the new position and other related information about the composition window.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

The ImmSetCompositionWindow function causes a IMN_SETSCOMPOSITIONWINDOW message to be sent to the application.

See Also

COMPOSITIONFORM


ImmSetConversionStatus [Now Supported on Windows NT]
ImmSetConversionStatus

[Now Supported on Windows NT]

The ImmSetConversionStatus function sets the current conversion status.

BOOL ImmSetConversionStatus(

HIMC hIMC,
DWORD fdwConversion,
DWORD fdwSentence
);
Parameters

hIMC

Handle to the input context.

fdwConvStatus

Conversion mode values. For more information, see the “IME Conversion Mode Values” table in Input Method Editor Constants.

fdwSentence

Sentence mode values. For more information, see the “IME Sentence Mode Values” table in Input Method Editor Constants.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

This function sends a IMN_SETCONVERSIONSTATUS message to the application.


ImmSetOpenStatus [Now Supported on Windows NT]
ImmSetOpenStatus

[Now Supported on Windows NT]

The ImmSetOpenStatus function opens or closes the IME.

BOOL ImmSetOpenStatus(

HIMC hIMC,
BOOL fOpen
);
Parameters

hIMC

Handle to the input context.

fOpen

Open flag. If TRUE, the IME is opened; otherwise, it is closed.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

This function causes a IMN_SETOPENSTATUS message to be sent to the application.

See Also

IMN_SETOPENSTATUS


ImmSetStatusWindowPos [Now Supported on Windows NT]
ImmSetStatusWindowPos

[Now Supported on Windows NT]

The ImmSetStatusWindowPos function sets the position of the status window.

BOOL ImmSetStatusWindowPos(

HIMC hIMC,
LPPOINT lpptPos
);
Parameters

hIMC

Handle to the input context.

lpptPos

Pointer to the POINT structure that receives the new position of the status window.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

The ImmSetStatusWindowPos function causes a IMN_SETSTATUSWINDOWPOS message to be sent to the application.

See Also

IMN_SETSTATUSWINDOWPOS, POINT


ImmSimulateHotKey [Now Supported on Windows NT]
ImmSimulateHotKey

[Now Supported on Windows NT]

The ImmSimulateHotKey function simulates the specified IME hot key, causing the same response as if the user had pressed the hot key in the specified window.

BOOL ImmSimulateHotKey(

HWND hWnd,
DWORD dwHotKeyID
);
Parameters

hWnd

Handle to the window.

dwHotKeyID

Identifier of the IME hot key. Can be one of the values specified in the “IME Hot Key Identifiers” table in Input Method Editor Constants.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.


ImmUnregisterWord [Now Supported on Windows NT]
ImmUnregisterWord

[Now Supported on Windows NT]

The ImmUnregisterWord function removes a register string from the dictionary of the IME associated with the specified keyboard layout.

BOOL ImmUnregisterWord(

HKL hKL,
LPCTSTR lpszReading,
DWORD dwStyle,
LPCTSTR lpszUnregister
);
Parameters

hKL

Handle to the keyboard layout.

lpszReading

Pointer to a null-terminated string specifying the reading string associated with the string to remove.

dwStyle

Style of the register string. Can be IME_REGWORD_STYLE_EUDC to indicate the string is in the EUDC range, or any value in the reserved range IME_REGWORD_STYLE_USER_FIRST to IME_REGWORD_STYLE_USER_LAST to indicate a private style maintained by the specified IME.

lpszUnregister

Pointer to a null-terminated string specifying the register string to remove.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.


ImpersonateDdeClientWindow

The ImpersonateDdeClientWindow function enables a DDE server application to impersonate a DDE client application’s security context in order to protect secure server data from unauthorized DDE clients.

BOOL ImpersonateDdeClientWindow(

HWND hWndClient,	// handle of DDE client window
HWND hWndServer	// handle of DDE server window
);
Parameters

hWndClient

Identifies the DDE client window to impersonate. The client window must have established a DDE conversation with the server window identified by the hWndServer parameter.

hWndServer

Identifies the DDE server window. An application must create the server window before calling this 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.

Remarks

An application should call the RevertToSelf function to undo the impersonation set by the ImpersonateDdeClientWindow function.

A DDEML application should use the DdeImpersonateClient function.

See Also

DdeImpersonateClient, RevertToSelf


ImpersonateLoggedOnUser

The ImpersonateLoggedOnUser function lets the calling thread impersonate a user. The user is represented by a token handle.

BOOL ImpersonateLoggedOnUser(

HANDLE hToken	// handle to a token that represents a logged-on user
);
Parameters

hToken

Handle to a primary or impersonation access token that represents a logged-on user. This can be a token handle returned by a call to LogonUser, DuplicateToken, DuplicateTokenEx, OpenProcessToken, or OpenThreadToken functions. If hToken is a primary token, it must have TOKEN_QUERY and TOKEN_DUPLICATE access. If hToken is an impersonation token, it must have TOKEN_QUERY access.

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.

Remarks

The impersonation lasts until the thread exits or until it calls RevertToSelf.

The calling thread does not need to have any particular privileges to call ImpersonateLoggedOnUser.

See Also

CreateProcessAsUser, DuplicateToken, DuplicateTokenEx, LogonUser, OpenProcessToken, or OpenThreadToken, RevertToSelf


ImpersonateNamedPipeClient

The ImpersonateNamedPipeClient function impersonates a named-pipe client application.

BOOL ImpersonateNamedPipeClient(

HANDLE hNamedPipe	// handle of a named pipe
);
Parameters

hNamedPipe

Identifies a named pipe.

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

Remarks

The ImpersonateNamedPipeClient function allows the server end of a named pipe to impersonate the client end. When this function is called, the named-pipe file system changes the thread of the calling process to start impersonating the security context of the last message read from the pipe. Only the server end of the pipe can call this function.

The server can call the RevertToSelf function when the impersonation is complete.

See Also

DdeImpersonateClient, DuplicateToken, RevertToSelf


ImpersonateSelf

The ImpersonateSelf function obtains an access token that impersonates the security context of the calling process. The token is assigned to the calling thread.

BOOL ImpersonateSelf(

SECURITY_IMPERSONATION_LEVEL ImpersonationLevel	// impersonation level
);
Parameters

ImpersonationLevel

Specifies a SECURITY_IMPERSONATION_LEVEL enumerated type that supplies the impersonation level of the new token.

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.

Remarks

The ImpersonateSelf function is used for tasks, such as enabling a privilege for a single thread rather than for the entire process or for changing the default discretionary access-control list for a single thread.

The server can call the RevertToSelf function when the impersonation is complete.

See Also

DuplicateToken, ImpersonateNamedPipeClient, RevertToSelf, SECURITY_IMPERSONATION_LEVEL


InflateRect

The InflateRect function increases or decreases the width and height of the specified rectangle. The InflateRect function adds dx units to the left and right ends of the rectangle and dy units to the top and bottom. The dx and dy parameters are signed values; positive values increase the width and height, and negative values decrease them.

BOOL InflateRect(

LPRECT lprc,	// address of rectangle
int dx,	// amount to increase or decrease width
int dy	// amount to increase or decrease height
);
Parameters

lprc

Points to the RECT structure that increases or decreases in size.

dx

Specifies the amount to increase or decrease the rectangle width. This parameter must be negative to decrease the width.

dy

Specifies the amount to increase or decrease the rectangle height. This parameter must be negative to decrease the height.

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.

See Also

IntersectRect, OffsetRect, RECT, UnionRect


InitAtomTable

The InitAtomTable function initializes the local atom table and sets it to the specified size.

BOOL InitAtomTable(

DWORD nSize	// size of atom table
);
Parameters

nSize

Specifies the size, in table entries, of the atom table. This value should be a prime number.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

An application need not use this function to use a local atom table. The default size of the local and global atom tables is 37 table entries. If an application does use InitAtomTable, however, it should call the function before any other atom-management function.

If an application uses a large number of local atoms, it can reduce the time required to add an atom to the local atom table or to find an atom in the table by increasing the size of the table. However, this increases the amount of memory required to maintain the table.

The size of the global atom table cannot be changed.

See Also

AddAtom, DeleteAtom, FindAtom, GetAtomName, GlobalAddAtom, GlobalDeleteAtom, GlobalFindAtom, GlobalGetAtomName


InitCommonControls

The InitCommonControls function ensures that the common control dynamic-link library (DLL) is loaded.

void InitCommonControls(VOID);

Return Values

This function does not return a value.


InitializeAcl

The InitializeAcl function creates a new ACL structure.

An ACL is an access-control list.

BOOL InitializeAcl(

PACL pAcl,	// address of access-control list
DWORD nAclLength,	// size of access-control list
DWORD dwAclRevision	// revision level of access-control list
);
Parameters

pAcl

Points to an ACL structure initialized by this function.

nAclLength

Specifies the length, in bytes, of the buffer pointed to by the pAcl parameter. This value must be large enough to contain the ACL header and all of the access-control entries (ACEs) to be stored in the ACL.

When calculating the size of an ACL, note that each ACE in an ACL gets the SID specified by its SidStart member copied to the ACE structure, starting at the ACE’s SidStart member. Thus, each ACE added to the ACL requires room for the ACE plus room for its SID minus the size of the SidStart member (a DWORD).

For example, the size of an ACL buffer large enough to contain a single ACCESS_ALLOWED_ACE is :

    cbAcl =    sizeof(ACL) + sizeof(ACCESS_ALLOWED_ACE)

             + GetLengthSid(pSid) - sizeof(DWORD) ;

Another example: the size of an ACL buffer large enough to contain seven ACCESS_DENIED_ACE structures is :

    cbAcl =  sizeof(ACL) +  7 * ( sizeof(ACCESS_DENIED_ACE) - sizeof(DWORD)) +

             GetLengthSid(pSid1) + GetLengthSid(pSid2) + ... + GetLengthSid(pSid7)

dwAclRevision

Specifies the revision level of the ACL. This parameter must be set to the current revision level, defined as ACL_REVISION for this version of Windows.

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.

Remarks

The ACL initialized by this function contains no ACEs. It is empty, as opposed to being a nonexistent ACL. If an empty ACL is applied to an object, it implicitly denies all access to that object.

See Also

ACCESS_ALLOWED_ACE, ACCESS_DENIED_ACE, ACL, AddAccessAllowedAce, AddAccessDeniedAce, AddAce, AddAuditAccessAce, DeleteAce, GetAce, GetAclInformation, IsValidAcl, SetAclInformation, SID


InitializeCriticalSection

The InitializeCriticalSection function initializes a critical section object.

VOID InitializeCriticalSection(

LPCRITICAL_SECTION lpCriticalSection	// address of critical section object
);
Parameters

lpCriticalSection

Points to the critical section object.

Return Values

This function does not return a value.

Remarks

The threads of a single process can use a critical section object for mutual-exclusion synchronization. The process is responsible for allocating the memory used by a critical section object, which it can do by declaring a variable of type CRITICAL_SECTION. Before using a critical section, some thread of the process must call the InitializeCriticalSection function to initialize the object.

Once a critical section object has been initialized, the threads of the process can specify the object in the EnterCriticalSection, TryEnterCriticalSection, or LeaveCriticalSection function to provide mutually exclusive access to a shared resource. For similar synchronization between the threads of different processes, use a mutex object.

A critical section object cannot be moved or copied. The process must also not modify the object, but must treat it as logically opaque. Use only the functions provided in the Win32 application programming interface (API) to manage critical section objects.

See Also

CreateMutex, DeleteCriticalSection, EnterCriticalSection, LeaveCriticalSection, TryEnterCriticalSection


InitializeSecurityDescriptor

The InitializeSecurityDescriptor function initializes a new security descriptor.

BOOL InitializeSecurityDescriptor(

PSECURITY_DESCRIPTOR pSecurityDescriptor,	// address of security descriptor
DWORD dwRevision	// revision level
);
Parameters

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure that the function initializes.

dwRevision

Specifies the revision level to assign to the security descriptor. This must be SECURITY_DESCRIPTOR_REVISION.

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.

Remarks

The InitializeSecurityDescriptor function initializes a security descriptor in absolute format, rather than self-relative format.

The InitializeSecurityDescriptor function initializes a security descriptor to have no system ACL, no discretionary ACL, no owner, no primary group, and all control flags set to FALSE (NULL). Thus, except for its revision level, it is empty.

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SetSecurityDescriptorDacl, SetSecurityDescriptorGroup, SetSecurityDescriptorOwner, SetSecurityDescriptorSacl


InitializeSid

The InitializeSid function initializes a SID structure. An SID is a security identifier.

BOOL InitializeSid(

PSID Sid,	// address of SID to initialize
PSID_IDENTIFIER_AUTHORITY pIdentifierAuthority,	// address of identifier authority
BYTE nSubAuthorityCount	// count of subauthorities
);
Parameters

Sid

Points to a SID structure to be initialized.

pIdentifierAuthority

Points to a SID_IDENTIFIER_AUTHORITY structure to set in the SID structure.

nSubAuthorityCount

Specifies the number of subauthorities to set in the SID. Values of the subauthority must be set separately, as described in the following Remarks section.

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.

Remarks

Although the InitializeSid function sets the number of subauthorities for the SID, it does not set the subauthority values. This must be done separately, using functions, such as GetSidSubAuthority.

An application can use the AllocateAndInitializeSid function to initialize a SID and set its subauthority values.

See Also

AllocateAndInitializeSid, GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthority, GetSidSubAuthorityCount, IsValidSid, SID, SID_IDENTIFIER_AUTHORITY


InitiateSystemShutdown

The InitiateSystemShutdown function initiates a shutdown and optional restart of the specified computer.

BOOL InitiateSystemShutdown(

LPTSTR lpMachineName,	// address of name of computer to shut down
LPTSTR lpMessage,	// address of message to display in dialog box
DWORD dwTimeout,	// time to display dialog box
BOOL bForceAppsClosed,	// force applications with unsaved changes flag
BOOL bRebootAfterShutdown	// reboot flag
);
Parameters

lpMachineName

Points to the null-terminated string that specifies the network name of the computer to shut down. If lpMachineName is NULL or points to an empty string, the function shuts down the local computer.

lpMessage

Points to a null-terminated string that specifies a message to display in the shutdown dialog box. This parameter can be NULL if no message is required.

dwTimeout

Specifies the time (in seconds) that the dialog box should be displayed. While this dialog box is displayed, the shutdown can be stopped by the AbortSystemShutdown function.

If dwTimeout is not zero, InitiateSystemShutdown displays a dialog box on the specified computer. The dialog box displays the name of the user who called the function, displays the message specified by the lpMessage parameter, and prompts the user to log off. The dialog box beeps when it is created and remains on top of other windows in the system. The dialog box can be moved but not closed. A timer counts down the remaining time before a forced shutdown. If the user logs off, the system shuts down immediately. Otherwise, the computer is shut down when the timer expires.

If dwTimeout is zero, the computer shuts down without displaying the dialog box, and the shutdown cannot be stopped by AbortSystemShutdown.

bForceAppsClosed

Specifies whether applications with unsaved changes are to be forcibly closed. If this parameter is TRUE, such applications are closed. If this parameter is FALSE, a dialog box is displayed prompting the user to close the applications.

bRebootAfterShutdown

Specifies whether the computer is to restart immediately after shutting down. If this parameter is TRUE, the computer is to restart. If this parameter is FALSE, the system flushes all caches to disk, clears the screen, and displays a message indicating that it is safe to power down.

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.

Remarks

To shut down the local computer, the calling process must have the SE_SHUTDOWN_NAME privilege. To shut down a remote computer, the calling process must have the SE_REMOTE_SHUTDOWN_NAME privilege on the remote computer. By default, users can enable the SE_SHUTDOWN_NAME privilege on the computer they are logged onto, and administrators can enable the SE_REMOTE_SHUTDOWN_NAME privilege on remote computers.

Common failures include an invalid or inaccessible computer name or insufficient privilege.

See Also

AbortSystemShutdown


InSendMessage

The InSendMessage function specifies whether the current window procedure is processing a message that was sent from another thread by a call to the SendMessage function.

BOOL InSendMessage(VOID)

Parameters

This function has no parameters.

Return Values

If the window procedure is processing a message sent to it from another thread using the SendMessage function, the return value is nonzero.

If the window procedure is not processing a message sent to it from another thread using the SendMessage function, the return value is zero.

See Also

PostThreadMessage, ReplyMessage, SendMessage


InsertMenu

The InsertMenu function inserts a new menu item into a menu, moving other items down the menu.

The InsertMenu function has been superseded by the InsertMenuItem function. You can still use InsertMenu, however, if you do not need any of the extended features of InsertMenuItem.

BOOL InsertMenu(

HMENU hMenu,	// handle of menu
UINT uPosition,	// menu item that new menu item precedes
UINT uFlags,	// menu item flags
UINT uIDNewItem,	// menu item identifier or handle of drop-down menu or submenu
LPCTSTR lpNewItem	// menu item content
);
Parameters

hMenu

Identifies the menu to be changed.

uPosition

Specifies the menu item before which the new menu item is to be inserted, as determined by the uFlags parameter.

uFlags

Specifies flags that control the interpretation of the uPosition parameter and the content, appearance, and behavior of the new menu item. This parameter must be a combination of one of the following required values and at least one of the values listed in the following Remarks section.

Value	Description
MF_BYCOMMAND	Indicates that the uPosition parameter gives the identifier of the menu item. The MF_BYCOMMAND flag is the default if neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified.
MF_BYPOSITION	Indicates that the uPosition parameter gives the zero-based relative position of the new menu item. If uPosition is 0xFFFFFFFF, the new menu item is appended to the end of the menu.
uIDNewItem

Specifies either the identifier of the new menu item or, if the uFlags parameter has the MF_POPUP flag set, the handle of the drop-down menu or submenu.

lpNewItem

Specifies the content of the new menu item. The interpretation of lpNewItem depends on whether the uFlags parameter includes the MF_BITMAP, MF_OWNERDRAW, or MF_STRING flag, as follows:

Value	Description
MF_BITMAP	Contains a bitmap handle.
MF_OWNERDRAW	Contains a 32-bit value supplied by the application that can be used to maintain additional data related to the menu item. The value is in the itemData member of the structure pointed to by the lparam parameter of the WM_MEASUREITEM or WM_DRAWITEM message sent when the menu item is created or its appearance is updated.
MF_STRING	Contains a pointer to a null-terminated string (the default).
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.

Remarks

The application must call the DrawMenuBar function whenever a menu changes, whether or not the menu is in a displayed window.

The following list describes the flags that can be set in the uFlags parameter:

Value	Description
MF_BITMAP	Uses a bitmap as the menu item. The lpNewItem parameter contains the handle of the bitmap.
MF_CHECKED	Places a check mark next to the menu item. If the application provides check mark bitmaps (see SetMenuItemBitmaps), this flag displays the check mark bitmap next to the menu item.
MF_DISABLED	Disables the menu item so that it cannot be selected, but does not gray it.
MF_ENABLED	Enables the menu item so that it can be selected and restores it from its grayed state.
MF_GRAYED	Disables the menu item and grays it so it cannot be selected.
MF_MENUBARBREAK	Functions the same as the MF_MENUBREAK flag for a menu bar. For a drop-down menu, submenu, or shortcut menu, the new column is separated from the old column by a vertical line.
MF_MENUBREAK	Places the item on a new line (for menu bars) or in a new column (for a drop-down menu, submenu, or shortcut menu) without separating columns.
MF_OWNERDRAW	Specifies that the item is an owner-drawn item. Before the menu is displayed for the first time, the window that owns the menu receives a WM_MEASUREITEM message to retrieve the width and height of the menu item. The WM_DRAWITEM message is then sent to the window procedure of the owner window whenever the appearance of the menu item must be updated.
MF_POPUP	Specifies that the menu item opens a drop-down menu or submenu. The uIDNewItem parameter specifies the handle of the drop-down menu or submenu. This flag is used to add a menu name to a menu bar or a menu item that opens a submenu to a drop-down menu, submenu, or shortcut menu.
MF_SEPARATOR	Draws a horizontal dividing line. This flag is used only in a drop-down menu, submenu, or shortcut menu. The line cannot be grayed, disabled, or highlighted. The lpNewItem and uIDNewItem parameters are ignored.
MF_STRING	Specifies that the menu item is a text string; the lpNewItem parameter points to the string.
MF_UNCHECKED	Does not place a check mark next to the menu item (default). If the application supplies check mark bitmaps (see the SetMenuItemBitmaps function), this flag displays the unchecked bitmap next to the menu item.
The following groups of flags cannot be used together:

•	MF_BYCOMMAND and MF_BYPOSITION

•	MF_DISABLED, MF_ENABLED, and MF_GRAYED

•	MF_BITMAP, MF_STRING, MF_OWNERDRAW, and MF_SEPARATOR

•	MF_MENUBARBREAK and MF_MENUBREAK

•	MF_CHECKED and MF_UNCHECKED

See Also

AppendMenu, DeleteMenu, DrawMenuBar, InsertMenuItem, ModifyMenu, RemoveMenu, SetMenuItemBitmaps, WM_DRAWITEM, WM_MEASUREITEM


InsertMenuItem [Now Supported on Windows NT]
InsertMenuItem

[Now Supported on Windows NT]

The InsertMenuItem function inserts a new menu item at the specified position in a menu.

BOOL WINAPI InsertMenuItem(

HMENU hMenu,
UINT uItem,
BOOL fByPosition,
LPMENUITEMINFO lpmii
);
Parameters

hMenu

Handle to the menu in which the new menu item is inserted.

uItem

Identifier or position of the menu item before which to insert the new item. The meaning of this parameter depends on the value of fByPosition.

fByPosition

Value specifying the meaning of uItem. If this parameter is FALSE, uItem is a menu item identifier. Otherwise, it is a menu item position.

lpmii

Pointer to a MENUITEMINFO structure that contains information about the new menu item.

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, use the GetLastError function.

See Also

MENUITEMINFO


Int32x32To64

The Int32x32To64 function multiplies two signed 32-bit integers, returning a signed 64-bit integer result. The function performs optimally on all Win32 platforms.

LONGLONG Int32x32To64(

LONG Multiplier,	// specifies first signed 32-bit integer for the multiplication
LONG Multiplicand	// specifies second signed 32-bit integer for the multiplication
);
Parameters

Multiplier

Specifies the first signed 32-bit integer for the multiplication.

Multiplicand

Specifies the second signed 32-bit integer for the multiplication.

Return Values

The return value is the signed 64-bit integer result of the multiplication.

Remarks

This function is implemented on all platforms by optimal inline code: a single multiply instruction that returns a 64-bit result.

Please note that the function’s return value is a 64-bit value, not a LARGE_INTEGER structure.

See Also

UInt32x32To64


Int64ShllMod32

The Int64ShllMod32 function performs a left logical shift operation on an unsigned 64-bit integer value. The function provides improved shifting code for left logical shifts where the shift count is in the range 0 − 31.

DWORDLONG Int64ShllMod32(

DWORDLONG Value,	// specifies unsigned 64-bit integer to shift left logically
DWORD ShiftCount	// specifies a shift count in the range 0 − 31
);
Parameters

Value

Specifies the unsigned 64-bit integer to be shifted.

ShiftCount

Specifies a shift count in the range 0 − 31.

Return Values

The return value is the unsigned 64-bit integer result of the left logical shift operation.

Remarks

The shift count is the number of bit positions that the value’s bits move.

In a left logical shift operation on an unsigned value, the value’s bits move to the left, and vacated bits on the right side of the value are set to zero.

A compiler can generate optimal code for a left logical shift operation when the shift count is a constant. However, if the shift count is a variable whose range of values is unknown, the compiler must assume the worst case, leading to non-optimal code: code that calls a subroutine, or code that is inline but branches. By restricting the shift count to the range 0 − 31, the Int64ShllMod32 function lets the compiler generate optimal or near-optimal code.

Please note that the Int64ShllMod32 function’s Value parameter and return value are 64-bit values, not LARGE_INTEGER structures.

See Also

Int64ShraMod32, Int64ShrlMod32


Int64ShraMod32

The Int64ShraMod32 function performs a right arithmetic shift operation on a signed 64-bit integer value. The function provides improved shifting code for right arithmetic shifts where the shift count is in the range 0 − 31.

LONGLONG Int64ShraMod32(

LONGLONG Value,	// specifies signed 64-bit integer to shift right arithmetically
DWORD ShiftCount	// specifies a shift count in the range 0 − 31
);
Parameters

Value

Specifies the signed 64-bit integer to be shifted.

ShiftCount

Specifies a shift count in the range 0 − 31.

Return Values

The return value is the signed 64-bit integer result of the right arithmetic shift operation.

Remarks

The shift count is the number of bit positions that the value’s bits move.

In a right arithmetic shift operation on a signed value, the value’s bits move to the right, and vacated bits on the left side of the value are set to the value of the sign bit.

A compiler can generate optimal code for a right arithmetic shift operation when the shift count is a constant. However, if the shift count is a variable whose range of values is unknown, the compiler must assume the worst case, leading to non-optimal code: code that calls a subroutine, or code that is inline but branches. By restricting the shift count to the range 0 − 31, the Int64ShraMod32 function lets the compiler generate optimal or near-optimal code.

Please note that the Int64ShraMod32 function’s Value parameter and return value are 64-bit values, not LARGE_INTEGER structures.

See Also

Int64ShllMod32, Int64ShrlMod32


Int64ShrlMod32

The Int64ShrlMod32 function performs a right logical shift operation on an unsigned 64-bit integer value. The function provides improved shifting code for right logical shifts where the shift count is in the range 0 − 31.

DWORDLONG Int64ShrlMod32(

DWORDLONG Value,	// specifies unsigned 64-bit integer to shift right logically
DWORD ShiftCount	// specifies a shift count in the range 0 − 31
);
Parameters

Value

Specifies the unsigned 64-bit integer to be shifted.

ShiftCount

Specifies a shift count in the range 0 − 31.

Return Values

The return value is the unsigned 64-bit integer result of the right logical shift operation.

Remarks

The shift count is the number of bit positions that the value’s bits move.

In a right logical shift operation on an unsigned value, the value’s bits move to the right, and vacated bits on the left side of the value are set to zero.

A compiler can generate optimal code for a right logical shift operation when the shift count is a constant. However, if the shift count is a variable whose range of values is unknown, the compiler must assume the worst case, leading to non-optimal code: code that calls a subroutine, or code that is inline but branches. By restricting the shift count to the range 0 − 31, the Int64ShrlMod32 function lets the compiler generate optimal or near-optimal code.

Please note that the Int64ShrlMod32 function’s Value parameter and return value are 64-bit values, not LARGE_INTEGER structures.

See Also

Int64ShllMod32, Int64ShraMod32


InterlockedCompareExchange [New - Windows NT]
InterlockedCompareExchange

[New - Windows NT]

The InterlockedCompareExchange function performs an atomic comparison of the values specified in the Destination and Comperand parameters and exchange of the values, based on the outcome of the comparison. The function prevents more than one thread from using the same variable simultaneously.

PVOID InterlockedCompareExchange(

PVOID *Destination,	// pointer to the destination pointer
PVOID Exchange,	// the exchange value
PVOID Comperand	// the value to compare
);
Parameters

Destination

Specifies the address of the destination value. This is a 32-bit value. The sign is ignored.

Exchange

Specifies the exchange value. This is a 32-bit value. The sign is ignored.

Comperand

Specifies the value to compare to Destination. This is a 32-bit value. The sign is ignored.

Return Values

The return value is the initial value of the destination.

Remarks

The functions InterlockedCompareExchange, InterlockedDecrement, InterlockedExchange, InterlockedExchangeAdd, and InterlockedIncrement provide a simple mechanism for synchronizing access to a variable that is shared by multiple threads. The threads of different processes can use this mechanism if the variable is in shared memory.

The InterlockedCompareExchange function performs an atomic comparison of the Destination value with the Comperand value. If the Destination value is equal to the Comperand value, the Exchange value is stored in the address specified by Destination. Otherwise, no operation is performed.

The variables for InterlockedCompareExchange must be aligned on a 32-bit boundary; otherwise, this function will fail on multiprocessor x86 systems.

See Also

InterlockedDecrement, InterlockedExchange, InterlockedExchangeAdd, InterlockedIncrement


InterlockedDecrement

The InterlockedDecrement function both decrements (decreases by one) the value of the specified 32-bit variable and checks the resulting value. The function prevents more than one thread from using the same variable simultaneously.

LONG InterlockedDecrement(

LPLONG lpAddend	// address of the variable to decrement
);
Parameters

lpAddend

Points to the 32-bit variable to decrement.

Return Values

If the result of the decrement is zero, the return value is zero.

If the result of the decrement is less than zero, the return value is less than zero. If the result of the decrement is greater than zero, the return value is greater than zero. A nonzero return value may not be equal to the result of the decrement.

Remarks

The functions InterlockedDecrement, InterlockedCompareExchange, InterlockedExchange, InterlockedExchangeAdd, and InterlockedIncrement provide a simple mechanism for synchronizing access to a variable that is shared by multiple threads. The threads of different processes can use this mechanism if the variable is in shared memory.

The variable pointed to by the lpAddend parameter must be aligned on a 32-bit boundary; otherwise, this function will fail on multiprocessor x86 systems.

See Also

InterlockedCompareExchange, InterlockedExchange, InterlockedExchangeAdd, InterlockedIncrement


InterlockedExchange

The InterlockedExchange function atomically exchanges a pair of 32-bit values. The function prevents more than one thread from using the same variable simultaneously.

LONG InterlockedExchange(

LPLONG Target,	// address of 32-bit value to exchange
LONG Value	// new value for the LONG value pointed to by Target
);
Parameters

Target

Address of the LONG value to exchange. The function sets this LONG value to Value, and returns its prior value.

Value

Specifies a new value for the LONG value pointed to by Target.

Return Values

The function returns the prior value of the LONG value pointed to by Target.

Remarks

The functions InterlockedExchange, InterlockedCompareExchange, InterlockedDecrement, InterlockedExchangeAdd, and InterlockedIncrement provide a simple mechanism for synchronizing access to a variable that is shared by multiple threads. The threads of different processes can use this mechanism if the variable is in shared memory.

The variable pointed to by the Target parameter must be aligned on a 32-bit boundary; otherwise, this function will fail on multiprocessor x86 systems.

See Also

InterlockedCompareExchange, InterlockedDecrement, InterlockedExchangeAdd, InterlockedIncrement


InterlockedExchangeAdd [New - Windows NT]
InterlockedExchangeAdd

[New - Windows NT]

The InterlockExchangeAdd function performs an atomic addition of an increment value to an addend variable. The function prevents more than one thread from using the same variable simultaneously.

LONG InterlockedExchangeAdd (

PLONG Addend,	// pointer to the addend
LONG Increment	// increment value
);
Parameters

Addend

Specifies the address of the number that will have the Increment number added to it.

Increment

Specifies the number to be added to the variable pointed to by the Addend parameter.

Return Values

The return value is the initial value of the Addend parameter.

Remarks

The functions InterlockedExchangeAdd, InterlockedCompareExchange, InterlockedDecrement, InterlockedExchange, and InterlockedIncrement provide a simple mechanism for synchronizing access to a variable that is shared by multiple threads. The threads of different processes can use this mechanism if the variable is in shared memory.

The InterlockedExchangeAdd function performs an atomic addition of the Increment value to the Addend value. The result is stored in the address specified by Addend. The initial value of Addend is returned as the function value.

The variables for InterlockedExchangeAdd must be aligned on a 32-bit boundary; otherwise, this function will fail on multiprocessor x86 systems.

See Also

InterlockedCompareExchange, InterlockedDecrement, InterlockedExchange, InterlockedIncrement


InterlockedIncrement

The InterlockedIncrement function both increments (increases by one) the value of the specified 32-bit variable and checks the resulting value. The function prevents more than one thread from using the same variable simultaneously.

LONG InterlockedIncrement(

LPLONG lpAddend	// address of the variable to increment
);
Parameters

lpAddend

Points to the 32-bit variable to increment.

Return Values

If the result of the increment is zero, the return value is zero.

If the result of the increment is less than zero, the return value is less than zero. If the result of the increment is greater than zero, the return value is greater than zero. A nonzero return value may not be equal to the result of the increment.

Remarks

The functions InterlockedIncrement, InterlockedCompareExchange, InterlockedDecrement, InterlockedExchange, and InterlockedExchangeAdd provide a simple mechanism for synchronizing access to a variable that is shared by multiple threads. The threads of different processes can use this mechanism if the variable is in shared memory.

The variable pointed to by the lpAddend parameter must be aligned on a 32-bit boundary; otherwise, this function will fail on multiprocessor x86 systems.

See Also

InterlockedCompareExchange, InterlockedDecrement, InterlockedExchange, InterlockedExchangeAdd


IntersectClipRect

The IntersectClipRect function creates a new clipping region from the intersection of the current clipping region and the specified rectangle.

int IntersectClipRect(

HDC hdc,	// handle of device context
int nLeftRect,	// x-coordinate of upper-left corner of rectangle
int nTopRect,	// y-coordinate of upper-left corner of rectangle
int nRightRect,	// x-coordinate of lower-right corner of rectangle
int nBottomRect	// y-coordinate of lower-right corner of rectangle
);
Parameters

hdc

Identifies the device context.

nLeftRect

Specifies the logical x-coordinate of the upper-left corner of the rectangle.

nTopRect

Specifies the logical y-coordinate of the upper-left corner of the rectangle.

nRightRect

Specifies the logical x-coordinate of the lower-right corner of the rectangle.

nBottomRect

Specifies the logical y-coordinate of the lower-right corner of the rectangle.

Return Values

If the function succeeds, the return value specifies the new clipping region’s type and can be any one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
ERROR	An error occurred. (The current clipping region is unaffected.)
Remarks

The lower and rightmost edges of the given rectangle are excluded from the clipping region.

See Also

ExcludeClipRect


IntersectRect

The IntersectRect function calculates the intersection of two source rectangles and places the coordinates of the intersection rectangle into the destination rectangle. If the source rectangles do not intersect, an empty rectangle (in which all coordinates are set to zero) is placed into the destination rectangle.

BOOL IntersectRect(

LPRECT lprcDst,	// address of structure for intersection
CONST RECT *lprcSrc1,	// address of structure with first rectangle
CONST RECT *lprcSrc2	// address of structure with second rectangle
);
Parameters

lprcDst

Points to the RECT structure that is to receive the intersection of the rectangles pointed to by the lprcSrc1 and lprcSrc2 parameters.

lprcSrc1

Points to the RECT structure that contains the first source rectangle.

lprcSrc2

Points to the RECT structure that contains the second source rectangle.

Return Values

If the rectangles intersect, the return value is nonzero.

If the rectangles do not intersect, the return value is zero. To get extended error information, call GetLastError.

See Also

InflateRect, OffsetRect, RECT, UnionRect


InvalidateRect

The InvalidateRect function adds a rectangle to the specified window’s update region. The update region represents the portion of the window’s client area that must be redrawn.

BOOL InvalidateRect(

HWND hWnd,	// handle of window with changed update region
CONST RECT *lpRect,	// address of rectangle coordinates
BOOL bErase	// erase-background flag
);
Parameters

hWnd

Identifies the window whose update region has changed. If this parameter is NULL, Windows invalidates and redraws all windows, and sends the WM_ERASEBKGND and WM_NCPAINT messages to the window procedure before the function returns.

lpRect

Points to a RECT structure that contains the client coordinates of the rectangle to be added to the update region. If this parameter is NULL, the entire client area is added to the update region.

bErase

Specifies whether the background within the update region is to be erased when the update region is processed. If this parameter is TRUE, the background is erased when the BeginPaint function is called. If this parameter is FALSE, the background remains unchanged.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The invalidated areas accumulate in the update region until the region is processed when the next WM_PAINT message occurs or until the region is validated by using the ValidateRect or ValidateRgn function.

Windows sends a WM_PAINT message to a window whenever its update region is not empty and there are no other messages in the application queue for that window.

If the bErase parameter is TRUE for any part of the update region, the background is erased in the entire region, not just in the given part.

See Also

BeginPaint, InvalidateRgn, RECT, ValidateRect, ValidateRgn, WM_ERASEBKGND, WM_NCPAINT, WM_PAINT


InvalidateRgn

The InvalidateRgn function invalidates the client area within the specified region by adding it to the current update region of a window. The invalidated region, along with all other areas in the update region, is marked for painting when the next WM_PAINT message occurs.

BOOL InvalidateRgn(

HWND hWnd,	// handle of window with changed update region
HRGN hRgn,	// handle of region to add
BOOL bErase	// erase-background flag
);
Parameters

hWnd

Identifies the window with an update region that is to be modified.

hRgn

Identifies the region to be added to the update region. The region is assumed to have client coordinates. If this parameter is NULL, the entire client area is added to the update region.

bErase

Specifies whether the background within the update region should be erased when the update region is processed. If this parameter is TRUE, the background is erased when the BeginPaint function is called. If the parameter is FALSE, the background remains unchanged.

Return Values

The return value is always nonzero.

Remarks

Invalidated areas accumulate in the update region until the next WM_PAINT message is processed or until the region is validated by using the ValidateRect or ValidateRgn function.

Windows sends a WM_PAINT message to a window whenever its update region is not empty and there are no other messages in the application queue for that window.

The specified region must have been created by using one of the region functions.

If the bErase parameter is TRUE for any part of the update region, the background in the entire region is erased, not just in the specified part.

See Also

BeginPaint, InvalidateRect, ValidateRect, ValidateRgn, WM_PAINT


InvertRect

The InvertRect function inverts a rectangle in a window by performing a logical NOT operation on the color values for each pixel in the rectangle’s interior.

BOOL InvertRect(

HDC hDC,	// handle of device context
CONST RECT *lprc	// address of structure with rectangle
);
Parameters

hDC

Identifies the device context.

lprc

Points to a RECT structure that contains the logical coordinates of the rectangle to be inverted.

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.

Remarks

On monochrome screens, InvertRect makes white pixels black and black pixels white. On color screens, the inversion depends on how colors are generated for the screen. Calling InvertRect twice for the same rectangle restores the display to its previous colors.

See Also

FillRect, RECT


InvertRgn

The InvertRgn function inverts the colors in the specified region.

BOOL InvertRgn(

HDC hdc,	// handle of device context
HRGN hrgn	// handle of region to be inverted
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies the region for which colors are inverted. The region’s coordinates are presumed to be logical coordinates.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

On monochrome screens, the InvertRgn function makes white pixels black and black pixels white. On color screens, this inversion is dependent on the type of technology used to generate the colors for the screen.

See Also

FillRgn, PaintRgn


IOCTL_DISK_CHECK_VERIFY

The IOCTL_DISK_CHECK_VERIFY function has been superseded by the IOCTL_STORAGE_CHECK_VERIFY function.


IOCTL_DISK_EJECT_MEDIA

The IOCTL_DISK_EJECT_MEDIA function has been superseded by the IOCTL_STORAGE_EJECT_MEDIA function.


IOCTL_DISK_FORMAT_TRACKS

The IOCTL_DISK_FORMAT_TRACKS DeviceIoControl operation formats a specified, contiguous set of tracks on a disk.

dwIoControlCode = IOCTL_DISK_FORMAT_TRACKS;   // operation code

lpInBuffer;         // address of input buffer

nInBufferSize;      // size of input buffer

lpOutBuffer = NULL; // address of output buffer; not used; must be NULL

nOutBufferSize = 0; // size of output buffer; not used; must be zero

lpBytesReturned;    // address of actual bytes of output

Parameters

lpInBuffer

Points to a buffer that contains a FORMAT_PARAMETERS data structure.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer, which must be large enough to contain a FORMAT_PARAMETERS data structure.

lpOutBuffer

Points to an output buffer. Not used with this operation. Set to NULL.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer. Not used with this operation. Set to zero.

lpBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpOutBuffer.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for floppy disk devices only.

See Also

DeviceIoControl, FORMAT_PARAMETERS


IOCTL_DISK_GET_DRIVE_GEOMETRY

The IOCTL_DISK_GET_DRIVE_GEOMETRY DeviceIoControl operation returns information about the physical disk’s geometry: type, number of cylinders, tracks per cylinder, sectors per track, and bytes per sector.

dwIoControlCode = IOCTL_DISK_GET_DRIVE_GEOMETRY;   // operation code

lpInBuffer = NULL;  // address of input buffer; not used; must be NULL

nInBufferSize = 0;  // size of input buffer; not used; must be zero

lpOutBuffer ;       // address of output buffer

nOutBufferSize ;    // size of output buffer

lpBytesReturned ;   // address of actual bytes of output

Parameters

lpInBuffer

Points to an input buffer. Not used with this operation. Set to NULL.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer. Not used with this operation. Set to zero.

lpOutBuffer

Points to a buffer that will receive a DISK_GEOMETRY data structure.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer, which must be greater than or equal to the size of a DISK_GEOMETRY data structure.

lpBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpOutBuffer.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices.

See Also

DeviceIoControl, DISK_GEOMETRY, IOCTL_DISK_GET_MEDIA_TYPES


IOCTL_DISK_GET_DRIVE_LAYOUT

The IOCTL_DISK_GET_DRIVE_LAYOUT DeviceIoControl operation returns information about the number of partitions on a disk and the features of each partition.

dwIoControlCode = IOCTL_DISK_GET_DRIVE_LAYOUT;   // operation code

lpInBuffer = NULL;  // address of input buffer; not used; must be NULL

nInBufferSize = 0;  // size of input buffer; not used; must be zero

lpOutBuffer ;       // address of output buffer

nOutBufferSize ;    // size of output buffer

lpBytesReturned ;   // address of actual bytes of output

Parameters

lpInBuffer

Points to an input buffer. Not used with this operation. Set to NULL.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer. Not used with this operation. Set to zero.

lpOutBuffer

Points to a buffer that will receive a DRIVE_LAYOUT_INFORMATION structure and a series of PARTITION_INFORMATION structures, one of the latter for each partition on the drive.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer, which must be large enough to contain one DRIVE_LAYOUT_INFORMATION data structure and as many PARTITION_INFORMATION data structures as there are partitions on the drive.

lpBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpOutBuffer.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, do not need to handle this operation.

See Also

DeviceIoControl, DRIVE_LAYOUT_INFORMATION, IOCTL_DISK_SET_DRIVE_LAYOUT, PARTITION_INFORMATION


IOCTL_DISK_GET_MEDIA_TYPES

The IOCTL_DISK_GET_MEDIA_TYPES function has been superseded by the IOCTL_STORAGE_GET_MEDIA_TYPES function.


IOCTL_DISK_GET_PARTITION_INFO

The IOCTL_DISK_GET_PARTITION_INFO DeviceIoControl operation returns information about the type, size, and nature of a disk partition.

dwIoControlCode = IOCTL_DISK_GET_PARTITION_INFO ;   // operation code

lpInBuffer = NULL;  // address of input buffer; not used; must be NULL

nInBufferSize = 0;  // size of input buffer; not used; must be zero

lpOutBuffer;        // address of output buffer

nOutBufferSize;     // size of output buffer

lpBytesReturned;    // address of actual bytes of output

Parameters

lpInBuffer

Points to an input buffer. Not used with this operation. Set to NULL.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer. Not used with this operation. Set to zero.

lpOutBuffer

Points to a buffer that will receive a PARTITION_INFORMATION data structure.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer, which must be large enough to contain a PARTITION_INFORMATION data structure.

lpBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpOutBuffer.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, do not need to handle this operation.

See Also

DeviceIoControl, IOCTL_DISK_SET_PARTITION_INFO, PARTITION_INFORMATION


IOCTL_DISK_LOAD_MEDIA

The IOCTL_DISK_LOAD_MEDIA function has been superseded by the IOCTL_STORAGE_LOAD_MEDIA function.


IOCTL_DISK_MEDIA_REMOVAL

The IOCTL_DISK_MEDIA_REMOVAL function has been superseded by the IOCTL_STORAGE_MEDIA_REMOVAL function.


IOCTL_DISK_PERFORMANCE

The IOCTL_DISK_PERFORMANCE DeviceIoControl operation provides disk performance information.

dwIoControlCode = IOCTL_DISK_PERFORMANCE;   // operation code

lpInBuffer = NULL; // address of input buffer; not used; must be NULL

nInBufferSize = 0; // size of input buffer; not used; must be zero

lpOutBuffer;       // address of output buffer

nOutBufferSize;    // size of output buffer

lpBytesReturned;   // address of actual bytes of output

Parameters

lpInBuffer

Points to an input buffer. Not used with this operation. Set to NULL.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer. Not used with this operation. Set to zero.

lpOutBuffer

Points to a buffer that will receive a DISK_PERFORMANCE data structure.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer, which must be large enough to contain a DISK_PERFORMANCE data structure.

lpBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpOutBuffer.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices.

See Also

DeviceIoControl, DISK_PERFORMANCE


IOCTL_DISK_REASSIGN_BLOCKS

The IOCTL_DISK_REASSIGN_BLOCKS DeviceIoControl operation directs the disk device to map one or more blocks to its spare-block pool.

dwIoControlCode = IOCTL_DISK_REASSIGN_BLOCKS;   // operation code

lpInBuffer;          // address of input buffer

nInBufferSize;       // size of input buffer

lpOutBuffer = NULL;  // address of output buffer; not used; must be NULL

nOutBufferSize = 0;  // size of output buffer; not used; must be zero

lpBytesReturned;     // address of actual bytes of output

Parameters

lpInBuffer

Points to a buffer that contains a REASSIGN_BLOCKS data structure specifying the blocks to reassign to its spare block pool.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer, which must be large enough to contain the REASSIGN_BLOCKS data structure. Note that this structure is really a header followed by an array of block specifiers; thus, it varies in size according to the number of blocks to be reassigned; each block after the first adds the size of a DWORD to the overall size.

lpOutBuffer

Points to an output buffer. Not used with this operation. Set to NULL.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer. Not used with this operation. Set to zero.

lpBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpOutBuffer.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices.

See Also

DeviceIoControl, REASSIGN_BLOCKS


IOCTL_DISK_SET_DRIVE_LAYOUT

The IOCTL_DISK_SET_DRIVE_LAYOUT DeviceIoControl operation partitions a disk as specified by drive layout and partition information data.

dwIoControlCode = IOCTL_DISK_SET_DRIVE_LAYOUT;   // operation code

lpInBuffer;          // address of input buffer

nInBufferSize;       // size of input buffer

lpOutBuffer = NULL;  // address of output buffer; not used; must be NULL

nOutBufferSize = 0;  // size of output buffer; not used; must be zero

lpBytesReturned;     // address of actual bytes of output

Parameters

lpInBuffer

Points to a buffer that contains drive layout and partition information data. The data exists as a DRIVE_LAYOUT_INFORMATION data structure and a series of PARTITION_INFORMATION data structures, one of the latter for each proposed partition on the drive.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer, which must be large enough to contain one DRIVE_LAYOUT_INFORMATION data structure and as many PARTITION_INFORMATION data structures as there are proposed partitions on the drive.

lpOutBuffer

Points to an output buffer. Not used with this operation. Set to NULL.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer. Not used with this operation. Set to zero.

lpBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpOutBuffer.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, need not handle this operation.

See Also

DeviceIoControl, DRIVE_LAYOUT_INFORMATION, IOCTL_DISK_GET_DRIVE_LAYOUT, PARTITION_INFORMATION


IOCTL_DISK_SET_PARTITION_INFO

The IOCTL_DISK_SET_PARTITION_INFO DeviceIoControl operation sets the partition type of the specified disk partition.

dwIoControlCode = IOCTL_DISK_SET_PARTITION_INFO;   // operation code

lpInBuffer;          // address of input buffer

nInBufferSize;       // size of input buffer

lpOutBuffer = NULL;  // address of output buffer; not used; must be NULL

nOutBufferSize = 0;  // size of output buffer; not used; must be zero

lpBytesReturned;     // address of actual bytes of output

Parameters

lpInBuffer

Points to a buffer that contains the partition data to be set. The data exists as a SET_PARTITION_INFORMATION data structure.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer, which must be large enough to contain a SET_PARTITION_INFORMATION data structure.

lpOutBuffer

Points to an output buffer. Not used with this operation. Set to NULL.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer. Not used with this operation. Set to zero.

lpBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpOutBuffer. Not used with this operation. Set to NULL.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, need not handle this operation.

See Also

DeviceIoControl, IOCTL_DISK_GET_PARTITION_INFO, SET_PARTITION_INFORMATION


IOCTL_DISK_VERIFY

The IOCTL_DISK_VERIFY DeviceIoControl operation performs a logical format of a specified extent on a disk.

dwIoControlCode = IOCTL_DISK_VERIFY;   // operation code

lpInBuffer;          // address of input buffer

nInBufferSize;       // size of input buffer

lpOutBuffer = NULL;  // address of output buffer; not used; must be NULL

nOutBufferSize = 0;  // size of output buffer; not used; must be zero

lpBytesReturned;     // address of actual bytes of output

Parameters

lpInBuffer

Points to a buffer that contains a VERIFY_INFORMATION data structure.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer, which must be large enough to contain a VERIFY_INFORMATION data structure.

lpOutBuffer

Points to an output buffer. Not used with this operation. Set to NULL.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer. Not used with this operation. Set to zero.

lpBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpOutBuffer.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, need not handle this operation.

See Also

DeviceIoControl, IOCTL_DISK_CHECK_VERIFY, VERIFY_INFORMATION


IOCTL_SERIAL_LSRMST_INSERT

The IOCTL_SERIAL_LSRMST_INSERT DeviceIoControl operation enables or disables the placement of line status and modem status values into the regular data stream that an application acquires through the ReadFile function.

When this line-status and modem-status data placement mode is enabled, status values are preceded in the data stream by an escape character. The user-definable escape character is set by the IOCTL_SERIAL_LSRMST_INSERT operation. Status values consist of 1 to 3 BYTEs. See the Remarks section below for status value details.

dwIoControlCode = IOCTL_SERIAL_LSRMST_INSERT;     // operation code

lpInBuffer;         // address of input buffer

nInBufferSize;      // size of input buffer

lpOutBuffer = NULL; // address of output buffer; not used; must be NULL

nOutBufferSize = 0; // size of output buffer; not used; must be zero

lpBytesReturned;    // address of actual bytes of output

Parameters

lpInBuffer

Points to a buffer that contains a single BYTE.

If the BYTE is a nonzero value, it is the desired line-status and modem-status value escape character. The operation will turn the LSRMST_INSERT line-status and modem-status data placement mode on.

If the BYTE is zero, the operation will turn the LSRMST_INSERT line-status and modem-status data placement mode off.

The escape character can not be the XON or XOFF character.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer. For this operation, this value should be 1.

lpOutBuffer

Points to an output buffer. Not used with this operation. Set to NULL.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer. Not used with this operation. Set to zero.

lpBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpOutBuffer.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

Note that an application that uses this scheme must examine each character in the data stream to determine the presence of modem-status or line-status data.

The following values follow the designated escape character in the data stream if the LSRMST_INSERT mode has been turned on :

Value	Meaning
SERIAL_LSRMST_ESCAPE	Indicates the reception of the escape character itself into the data stream.
SERIAL_LSRMST_LSR_DATA	Indicates that a line status change occurred, and data was available in the receive hardware buffer. Following this BYTE is a BYTE value of the line status register is the BYTE present in the receive hardware buffer when the line status change was processed.
SERIAL_LSRMST_LSR_NODATA	Indicates that a line status change occurred, but no data was available in the receive hardware buffer.
SERIAL_LSRMST_MST	Indicates that a modem status change occurred. Following this BYTE is a BYTE that is the value of the modem status register when the modem status change was processed.
See Also

DeviceIoControl, ReadFile


IOCTL_STORAGE_CHECK_VERIFY

The IOCTL_STORAGE_CHECK_VERIFY DeviceIoControl operation determines whether a device’s media is accessible; for example, whether the media is in the device.

dwIoControlCode = IOCTL_STORAGE_CHECK_VERIFY ;   // operation code

lpInBuffer = NULL;  // address of input buffer; not used; must be NULL

nInBufferSize = 0;  // size of input buffer; not used; must be zero

lpOutBuffer = NULL; // address of output buffer; not used; must be NULL

nOutBufferSize = 0; // size of output buffer; not used; must be zero

lpBytesReturned;    // address of actual bytes of output

Parameters

lpInBuffer

Points to an input buffer. Not used with this operation. Set to NULL.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer. Not used with this operation. Set to zero.

lpOutBuffer

Points to an output buffer. Not used with this operation. Set to NULL.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer. Not used with this operation. Set to zero.

lpBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpOutBuffer.

Return Values

If the operation succeeds and the device media is accessible, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE.

See Also

DeviceIoControl


IOCTL_STORAGE_EJECT_MEDIA

The IOCTL_STORAGE_EJECT_MEDIA DeviceIoControl operation causes media to be ejected from a SCSI device.

dwIoControlCode = IOCTL_STORAGE_EJECT_MEDIA;   // operation code

lpInBuffer = NULL;  // address of input buffer; not used; must be NULL

nInBufferSize = 0;  // size of input buffer; not used; must be zero

lpOutBuffer = NULL; // address of output buffer; not used; must be NULL

nOutBufferSize = 0; // size of output buffer; not used; must be zero

lpBytesReturned;    // address of actual bytes of output

Parameters

lpInBuffer

Points to an input buffer. Not used with this operation. Set to NULL.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer. Not used with this operation. Set to zero.

lpOutBuffer

Points to an output buffer. Not used with this operation. Set to NULL.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer. Not used with this operation. Set to zero.

lpBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpOutBuffer.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

IOCTL_STORAGE_EJECT_MEDIA may or may not be supported on SCSI devices that support removable media.

See Also

DeviceIoControl, IOCTL_DISK_MEDIA_REMOVAL, IOCTL_DISK_LOAD_MEDIA


IOCTL_STORAGE_GET_MEDIA_TYPES

The IOCTL_STORAGE_GET_MEDIA_TYPES DeviceIoControl operation returns information about the types of media a device driver supports.

dwIoControlCode = IOCTL_STORAGE_GET_MEDIA_TYPES;   // operation code

lpInBuffer = NULL;  // address of input buffer; not used; must be NULL

nInBufferSize = 0;  // size of input buffer; not used; must be zero

lpOutBuffer ;       // address of output buffer

nOutBufferSize ;    // size of output buffer

lpBytesReturned;    // address of actual bytes of output

Parameters

lpInBuffer

Points to an input buffer. Not used with this operation. Set to NULL.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer. Not used with this operation. Set to zero.

lpOutBuffer

Points to a buffer that will receive an array of DISK_GEOMETRY data structures specifying the media types the device driver supports.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer, which must be large enough to contain as many DISK_GEOMETRY structures as there are media that the driver supports.

lpBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpOutBuffer.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for all class drivers, as well as non-small computer system interface (SCSI) hard drives and floppy disk devices.

See Also

DeviceIoControl, DISK_GEOMETRY, IOCTL_DISK_GET_DRIVE_GEOMETRY


IOCTL_STORAGE_LOAD_MEDIA

The IOCTL_STORAGE_LOAD_MEDIA DeviceIoControl operation causes media to be loaded into a device.

dwIoControlCode = IOCTL_STORAGE_LOAD_MEDIA;   // operation code

lpInBuffer = NULL;  // address of input buffer; not used; must be NULL

nInBufferSize = 0;  // size of input buffer; not used; must be zero

lpOutBuffer = NULL; // address of output buffer; not used; must be NULL

nOutBufferSize = 0; // size of output buffer; not used; must be zero

lpBytesReturned;    // address of actual bytes of output

Parameters

lpInBuffer

Points to an input buffer. Not used with this operation. Set to NULL.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer. Not used with this operation. Set to zero.

lpOutBuffer

Points to an output buffer. Not used with this operation. Set to NULL.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer. Not used with this operation. Set to zero.

lpBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpOutBuffer.

Remarks

The IOCTL_STORAGE_LOAD_MEDIA is valid only for devices that support loadable media.

See Also

DeviceIoControl, IOCTL_STORAGE_EJECT_MEDIA, IOCTL_STORAGE_MEDIA_REMOVAL


IOCTL_STORAGE_MEDIA_REMOVAL

The IOCTL_STORAGE_MEDIA_REMOVAL DeviceIoControl operation enables or disables the mechanism that ejects media, for those devices possessing that locking capability.

dwIoControlCode = IOCTL_STORAGE_MEDIA_REMOVAL;   // operation code

lpInBuffer;         // address of input buffer

nInBufferSize;      // size of input buffer

lpOutBuffer = NULL; // address of output buffer; not used; must be NULL

nOutBufferSize = 0; // size of output buffer; not used; must be zero

lpBytesReturned;    // address of actual bytes of output

Parameters

lpInBuffer

Points to a buffer that contains a PREVENT_MEDIA_REMOVAL data structure.

A TRUE value for that structure’s PreventMediaRemoval member specifies that media removal is prevented (the device is locked). A FALSE value specifies that media removal is allowed.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer, which must be large enough to contain a PREVENT_MEDIA_REMOVAL data structure.

lpOutBuffer

Points to an output buffer. Not used with this operation. Set to NULL.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer. Not used with this operation. Set to zero.

lpBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpOutBuffer.

Return Values

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

The IOCTL_STORAGE_MEDIA_REMOVAL operation is valid only for devices that support removable media.

See Also

DeviceIoControl, IOCTL_STORAGE_EJECT_MEDIA, IOCTL_STORAGE_LOAD_MEDIA, PREVENT_MEDIA_REMOVAL


IsBadCodePtr

The IsBadCodePtr function determines whether the calling process has read access to the memory at the specified address.

BOOL IsBadCodePtr(

FARPROC lpfn	// address of function
);
Parameters

lpfn

Points to an address in memory.

Return Values

If the calling process has read access to the specified memory, the return value is zero.

If the calling process does not have read access to the specified memory, the return value is nonzero. To get extended error information, call GetLastError.

Remarks

IsBadCodePtr checks the read access only at the specified address and does not guarantee read access to a range of memory.

In a preemptive multitasking environment, it is possible for some other thread to change the process’s access to the memory being tested. Even when the function indicates that the process has read access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

See Also

IsBadHugeReadPtr, IsBadHugeWritePtr, IsBadReadPtr, IsBadStringPtr, IsBadWritePtr


IsBadHugeReadPtr

The IsBadHugeReadPtr function verifies that the calling process has read access to the specified range of memory.

BOOL IsBadHugeReadPtr(

CONST VOID *lp,	// address of memory block
UINT ucb	// size of block
);
Parameters

lp

Points to the first byte of the memory block.

ucb

Specifies the size, in bytes, of the memory block. If this parameter is zero, the return value is zero.

Return Values

If the calling process has read access to all bytes in the specified memory range, the return value is zero.

If the calling process does not have read access to all bytes in the specified memory range, the return value is nonzero. To get extended error information, call GetLastError.

Remarks

If the calling process has read access to some, but not all, of the bytes in the specified memory range, the return value is nonzero.

In a preemptive multitasking environment, it is possible for some other thread to change the process’s access to the memory being tested. Even when the function indicates that the process has read access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

IsBadHugeReadPtr is available for compatibility with earlier versions of Windows that distinguish between normal memory allocations and huge allocations occupying multiple segments. In the Win32 API, this function is equivalent to the IsBadReadPtr function.

See Also

IsBadHugeWritePtr, IsBadReadPtr, IsBadStringPtr, IsBadWritePtr


IsBadHugeWritePtr

The IsBadHugeWritePtr function verifies that the calling process has write access to the specified range of memory.

BOOL IsBadHugeWritePtr(

LPVOID lp,	// address of memory block
UINT ucb	// size of block
);
Parameters

lp

Points to the first byte of the memory block.

ucb

Specifies the size, in bytes, of the memory block. If this parameter is zero, the return value is zero.

Return Values

If the calling process has write access to all bytes in the specified memory range, the return value is zero.

If the calling process does not have write access to all bytes in the specified memory range, the return value is nonzero. To get extended error information, call GetLastError

Remarks

If the calling process has write access to some, but not all, of the bytes in the specified memory range, the return value is nonzero.

In a preemptive multitasking environment, it is possible for some other thread to change the process’s access to the memory being tested. Even when the function indicates that the process has write access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

IsBadHugeWritePtr is available for compatibility with earlier versions of Windows, which distinguish between normal memory allocations and huge allocations occupying multiple segments. In the Win32 API, this function is equivalent to the IsBadWritePtr function.

See Also

IsBadHugeReadPtr, IsBadReadPtr, IsBadStringPtr, IsBadWritePtr


IsBadReadPtr

The IsBadReadPtr function verifies that the calling process has read access to the specified range of memory.

BOOL IsBadReadPtr(

CONST VOID *lp,	// address of memory block
UINT ucb	// size of block
);
Parameters

lp

Points to the first byte of the memory block.

ucb

Specifies the size, in bytes, of the memory block. If this parameter is zero, the return value is zero.

Return Values

If the calling process has read access to all bytes in the specified memory range, the return value is zero.

If the calling process does not have read access to all bytes in the specified memory range, the return value is nonzero. To get extended error information, call GetLastError

Remarks

If the calling process has read access to some, but not all, of the bytes in the specified memory range, the return value is nonzero.

In a preemptive multitasking environment, it is possible for some other thread to change the process’s access to the memory being tested. Even when the function indicates that the process has read access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

See Also

IsBadHugeReadPtr, IsBadHugeWritePtr, IsBadStringPtr, IsBadWritePtr


IsBadStringPtr

The IsBadStringPtr function verifies that the calling process has read access to a range of memory pointed to by a string pointer.

BOOL IsBadStringPtr(

LPCTSTR lpsz,	// address of string
UINT ucchMax	// maximum size of string
);
Parameters

lpsz

Points to a null-terminated string, either Unicode or ASCII.

ucchMax

Specifies the maximum size, in characters, of the string. The function checks for read access in all bytes up to the string’s terminating null character or up to the number of bytes specified by this parameter, whichever is smaller. If this parameter is zero, the return value is zero.

Return Values

If the calling process has read access to all bytes up to the string’s terminating null character or up to the number of bytes specified by ucchMax, the return value is zero.

If the calling process does not have read access to all bytes up to the string’s terminating null character or up to the number of bytes specified by ucchMax, the return value is nonzero. To get extended error information, call GetLastError

Remarks

If the calling process has read access to some, but not all, of the bytes in the specified memory range, the return value is nonzero.

In a preemptive multitasking environment, it is possible for some other thread to change the process’s access to the memory being tested. Even when the function indicates that the process has read access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

See Also

IsBadCodePtr, IsBadHugeReadPtr, IsBadHugeWritePtr, IsBadReadPtr, IsBadWritePtr


IsBadWritePtr

The IsBadWritePtr function verifies that the calling process has write access to the specified range of memory.

BOOL IsBadWritePtr(

LPVOID lp,	// address of memory block
UINT ucb	// size of block
);
Parameters

lp

Points to the first byte of the memory block.

ucb

Specifies the size, in bytes, of the memory block. If this parameter is zero, the return value is zero.

Return Values

If the calling process has write access to all bytes in the specified memory range, the return value is zero.

If the calling process does not have write access to all bytes in the specified memory range, the return value is nonzero. To get extended error information, call GetLastError.

Remarks

If the calling process has write access to some, but not all, of the bytes in the specified memory range, the return value is nonzero.

In a preemptive multitasking environment, it is possible for some other thread to change the process’s access to the memory being tested. Even when the function indicates that the process has write access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

See Also

IsBadCodePtr, IsBadHugeReadPtr, IsBadHugeWritePtr, IsBadReadPtr


IsCharAlpha

The IsCharAlpha function determines whether a character is an alphabetic character. This determination is based on the semantics of the language selected by the user during setup or by using Control Panel.

BOOL IsCharAlpha(

TCHAR ch	// character to test
);
Parameters

ch

Specifies the character to be tested.

Return Values

If the character is alphabetic, the return value is nonzero.

If the character is not alphabetic, the return value is zero. To get extended error information, call GetLastError.

See Also

IsCharAlphaNumeric


IsCharAlphaNumeric

The IsCharAlphaNumeric function determines whether a character is either an alphabetic or a numeric character. This determination is based on the semantics of the language selected by the user during setup or by using Control Panel.

BOOL IsCharAlphaNumeric(

TCHAR ch	// character to test
);
Parameters

ch

Specifies the character to be tested.

Return Values

If the character is alphanumeric, the return value is nonzero.

If the character is not alphanumeric, the return value is zero. To get extended error information, call GetLastError.

See Also

IsCharAlpha


IsCharLower

The IsCharLower function determines whether a character is lowercase. This determination is based on the semantics of the language selected by the user during setup or by using Control Panel.

BOOL IsCharLower(

TCHAR ch	// character to test
);
Parameters

ch

Specifies the character to be tested.

Return Values

If the character is lowercase, the return value is nonzero.

If the character is not lowercase, the return value is zero. To get extended error information, call GetLastError.

See Also

IsCharUpper


IsCharUpper

The IsCharUpper function determines whether a character is uppercase. This determination is based on the semantics of the language selected by the user during setup or by using Control Panel.

BOOL IsCharUpper(

TCHAR ch	// character to test
);
Parameters

ch

Specifies the character to be tested.

Return Values

If the character is uppercase, the return value is nonzero.

If the character is not uppercase, the return value is zero. To get extended error information, call GetLastError.

See Also

IsCharLower


IsChild

The IsChild function tests whether a window is a child window or descendant window of a specified parent window. A child window is the direct descendant of a specified parent window if that parent window is in the chain of parent windows; the chain of parent windows leads from the original overlapped or pop-up window to the child window.

BOOL IsChild(

HWND hWndParent,	// handle of parent window
HWND hWnd	// handle of window to test
);
Parameters

hWndParent

Identifies the parent window.

hWnd

Identifies the window to be tested.

Return Values

If the window is a child or descendant window of the specified parent window, the return value is nonzero.

If the window is not a child or descendant window of the specified parent window, the return value is zero.

See Also

IsWindow, SetParent


IsClipboardFormatAvailable

The IsClipboardFormatAvailable function determines whether the clipboard contains data in the specified format.

BOOL IsClipboardFormatAvailable(

UINT format	// clipboard format
);
Parameters

format

Specifies a standard or registered clipboard format. For a description of the clipboard formats, see the SetClipboardData function.

Return Values

If the clipboard format is available, the return value is nonzero.

If the clipboard format is not available, the return value is zero. To get extended error information, call GetLastError.

Remarks

Typically, an application that recognizes only one clipboard format would call this function when processing the WM_INITMENU or WM_INITMENUPOPUP message. The application would then enable or disable the Paste menu item, depending on the return value. Applications that recognize more than one clipboard format should use the GetPriorityClipboardFormat function for this purpose.

See Also

CountClipboardFormats, EnumClipboardFormats, GetPriorityClipboardFormat, RegisterClipboardFormat, SetClipboardData, WM_INITMENU, WM_INITMENUPOPUP


IsDBCSLeadByte

The IsDBCSLeadByte function determines whether a character is a lead byte — that is, the first byte of a character in a double-byte character set (DBCS).

BOOL IsDBCSLeadByte(

BYTE TestChar	// character to test
);
Parameters

TestChar

Specifies the character to be tested.

Return Values

If the character is a lead byte, the return value is nonzero.

If the character is not a lead byte, the return value is zero. To get extended error information, call GetLastError.

Remarks

Lead bytes are unique to double-byte character sets. A lead byte introduces a double-byte character. Lead bytes occupy a specific range of byte values. The IsDBCSLeadByte function uses the ANSI code page to check lead-byte ranges.

See Also

MultiByteToWideChar


IsDBCSLeadByteEx

The IsDBCSLeadByteEx function determines whether a character is a lead byte — that is, the first byte of a character in a double-byte character set (DBCS).

BOOL IsDBCSLeadByteEx(

UINT CodePage,	// identifier of code page
BYTE TestChar	// character to test
);
Parameters

CodePage

Identifier of the code page to use to check lead-byte ranges. Can be one of the code-page values given in the “Code-Page Identifiers” table in Unicode and Character Set Constants or one of the following predefined values:

Value	Meaning
0	Use system default ANSI code page.
CP_ACP	Use system default ANSI code page.
CP_OEMCP	Use system default OEM code page.
TestChar

Character to test.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.


IsDebuggerPresent [New - Windows NT]
IsDebuggerPresent

[New - Windows NT]

The IsDebuggerPresent function indicates whether the calling process is running under the context of a debugger.

This function is exported from KERNEL32.DLL.

BOOL IsDebuggerPresent(VOID)

Parameters

This function has no parameters.

Return Value

If the current process is running in the context of a debugger, the return value is nonzero.

If the current process is not running in the context of a debugger, the return value is zero.

Remarks

This function allows an application to determine whether or not it is being debugged, so that it can modify its behavior. For example, an application could provide additional information using the OutputDebugString function if it is being debugged.

See Also

OutputDebugString


IsDialogMessage

The IsDialogMessage function determines whether a message is intended for the specified dialog box and, if it is, processes the message.

BOOL IsDialogMessage(

HWND hDlg,	// handle of dialog box
LPMSG lpMsg	// address of structure with message
);
Parameters

hDlg

Identifies the dialog box.

lpMsg

Points to an MSG structure that contains the message to be checked.

Return Values

If the message has been processed, the return value is nonzero.

If the message has not been processed, the return value is zero.

Remarks

Although the IsDialogMessage function is intended for modeless dialog boxes, you can use it with any window that contains controls, enabling the windows to provide the same keyboard selection as is used in a dialog box.

When IsDialogMessage processes a message, it checks for keyboard messages and converts them into selection commands for the corresponding dialog box. For example, the TAB key, when pressed, selects the next control or group of controls, and the DOWN ARROW key, when pressed, selects the next control in a group.

Because the IsDialogMessage function performs all necessary translating and dispatching of messages, a message processed by IsDialogMessage must not be passed to the TranslateMessage or DispatchMessage function.

IsDialogMessage sends WM_GETDLGCODE messages to the dialog box procedure to determine which keys should be processed.

IsDialogMessage can send DM_GETDEFID and DM_SETDEFID messages to the window. These messages are defined in the WINUSER.H header file as WM_USER and WM_USER + 1, so conflicts are possible with application-defined messages having the same values.

See Also

DispatchMessage, DM_GETDEFID, DM_SETDEFID, MSG, TranslateMessage, WM_GETDLGCODE, WM_USER


IsDlgButtonChecked

The IsDlgButtonChecked function determines whether a button control has a check mark next to it or whether a three-state button control is grayed, checked, or neither.

UINT IsDlgButtonChecked(

HWND hDlg,	// handle of dialog box
int nIDButton	// button identifier
);
Parameters

hDlg

Identifies the dialog box that contains the button control.

nIDButton

Specifies the integer identifier of the button control.

Return Values

The return value from a button created with the BS_AUTOCHECKBOX, BS_AUTORADIOBUTTON, BS_AUTO3STATE, BS_CHECKBOX, BS_RADIOBUTTON, or BS_3STATE style can be one of the following:

Value	Meaning
BST_CHECKED	Button is checked.
BST_INDETERMINATE	Button is grayed, indicating an indeterminate state (applies only if the button has the BS_3STATE or BS_AUTO3STATE style).
BST_UNCHECKED	Button is unchecked
If the button has any other style, the return value is zero.

Remarks

The IsDlgButtonChecked function sends a BM_GETCHECK message to the specified button control.

See Also

CheckDlgButton


IsIconic

The IsIconic function determines whether the specified window is minimized (iconic).

BOOL IsIconic(

HWND hWnd	// handle of window
);
Parameters

hWnd

Identifies the window.

Return Values

If the window is iconic, the return value is nonzero.

If the window is not iconic, the return value is zero.

See Also

IsZoomed


IsMenu

The IsMenu function determines whether a handle is a menu handle.

BOOL IsMenu(

HMENU hMenu	// handle to test
);
Parameters

hMenu

The handle to be tested.

Return Values

If hMenu is a menu handle, the return value is nonzero.

If hMenu is not a menu handle, the return value is zero.


IsProcessorFeaturePresent [New - Windows NT]
IsProcessorFeaturePresent

[New - Windows NT]

The IsProcessorFeaturePresent function determines whether the specified processor feature is supported by at least one processor on the current machine.

BOOL IsProcessorFeaturePresent(

DWORD ProcessorFeature	// specifies the processor feature
);
Parameters

ProcessorFeature

Specifies the processor feature to be tested. This value can be one of the following:

Value	Meaning
PF_FLOATING_POINT_PRECISION_ ERRATA	In rare circumstances, a floating-point precision error can occur (Pentium).
PF_FLOATING_POINT_EMULATED	Floating-point operations are emulated using a software emulator.
PF_COMPARE_EXCHANGE_DOUBLE	The compare and exchange double operation is available (Pentium, MIPS, and Alpha).
PF_MMX_INSTRUCTIONS_AVAILABLE	The MMX instruction set is available.
Return Value

If at least one of the processors supports the feature, the return value is nonzero.

If no processor supports the feature, the return value is zero.


IsRectEmpty

The IsRectEmpty function determines whether the specified rectangle is empty. A empty rectangle is one that has no area; that is, the coordinate of the right side is less than or equal to the coordinate of the left side, or the coordinate of the bottom side is less than or equal to the coordinate of the top side.

BOOL IsRectEmpty(

CONST RECT *lprc	// address of structure with rectangle
);
Parameters

lprc

Points to a RECT structure that contains the logical coordinates of the rectangle.

Return Values

If the rectangle is empty, the return value is nonzero.

If the rectangle is not empty, the return value is zero. To get extended error information, call GetLastError.

See Also

EqualRect, PtInRect, RECT


IsTextUnicode

The IsTextUnicode function determines whether a buffer probably contains a form of Unicode text. The function uses various statistical and deterministic methods to make its determination, under the control of flags passed via lpi. When the function returns, the results of such tests are reported via lpi. If all specified tests are passed, the function returns TRUE; otherwise, it returns FALSE.

DWORD IsTextUnicode(

CONST LPVOID lpBuffer,	// pointer to an input buffer to be examined
int cb,	// the size in bytes of the input buffer
LPINT lpi	// pointer to flags that condition text examination and receive results
);
Parameters

lpBuffer

Pointer to the input buffer to be examined.

cb

Specifies the size, in bytes, of the input buffer pointed to by lpBuffer.

lpi

Pointer to an int that, upon entry to the function, contains a set of flags that specify the tests to be applied to the input buffer text. Upon exit from the function, that same int contains a set of bit flags indicating the results of the specified tests: 1 if the contents of the buffer pass a test, 0 for failure. Only flags that are set upon entry to the function are significant upon exit.

If lpi is NULL, the function uses all available tests to determine whether the data in the buffer is probably Unicode text.

Here are the constants used with *lpi’s bit flags:

Value	Meaning
IS_TEXT_UNICODE_ASCII16	The text is Unicode, and contains nothing but zero-extended ASCII values/characters.
IS_TEXT_UNICODE_REVERSE_ASCII16	Same as the preceding, except that the Unicode text is byte-reversed.
IS_TEXT_UNICODE_STATISTICS	The text is probably Unicode, with the determination made by applying statistical analysis. Absolute certainty is not guaranteed. See the note in the following Remarks section.
IS_TEXT_UNICODE_REVERSE_STATISTICS	Same as the preceding, except that the probably-Unicode text is byte-reversed.
IS_TEXT_UNICODE_CONTROLS	The text contains Unicode representations of one or more of these non-printing characters: RETURN, LINEFEED, SPACE, CJK_SPACE, TAB.
IS_TEXT_UNICODE_REVERSE_CONTROLS	Same as the preceding, except that the Unicode characters are byte-reversed.
IS_TEXT_UNICODE_BUFFER_TOO_SMALL	There are too few characters in the buffer for meaningful analysis (fewer than two bytes).
IS_TEXT_UNICODE_SIGNATURE	The text contains the Unicode byte-order mark (BOM) 0xFEFF as its first character.
IS_TEXT_UNICODE_REVERSE_SIGNATURE	The text contains the Unicode byte-reversed byte-order mark (Reverse BOM) 0xFFFE as its first character.
IS_TEXT_UNICODE_ILLEGAL_CHARS	The text contains one of these Unicode-illegal characters: embedded Reverse BOM, UNICODE_NUL, CRLF (packed into one WORD), or 0xFFFF.
IS_TEXT_UNICODE_ODD_LENGTH	The number of characters in the string is odd. A string of odd length cannot (by definition) be Unicode text.
IS_TEXT_UNICODE_NULL_BYTES	The text contains null bytes, which indicate non-ASCII text.
IS_TEXT_UNICODE_UNICODE_MASK	This flag constant is a combination of IS_TEXT_UNICODE_ASCII16, IS_TEXT_UNICODE_STATISTICS, IS_TEXT_UNICODE_CONTROLS, IS_TEXT_UNICODE_SIGNATURE.
IS_TEXT_UNICODE_REVERSE_MASK	This flag constant is a combination of IS_TEXT_UNICODE_REVERSE_ASCII16, IS_TEXT_UNICODE_REVERSE_STATISTICS, IS_TEXT_UNICODE_REVERSE_CONTROLS, IS_TEXT_UNICODE_REVERSE_SIGNATURE.
IS_TEXT_UNICODE_NOT_UNICODE_MASK	This flag constant is a combination of IS_TEXT_UNICODE_ILLEGAL_CHARS, IS_TEXT_UNICODE_ODD_LENGTH, and two currently unused bit flags.
IS_TEXT_UNICODE_NOT_ASCII_MASK	This flag constant is a combination of IS_TEXT_UNICODE_NULL_BYTES and three currently unused bit flags.
Return Values

The function returns nonzero if the data in the buffer passes the specified tests.

The function returns zero if the data in the buffer does not pass the specified tests.

In either case, the int pointed to by lpi contains the results of the specific tests the function applied to make its determination.

Remarks

As noted in the preceding table of flag constants, the IS_TEXT_UNICODE_STATISTICS and IS_TEXT_UNICODE_REVERSE_STATISTICS tests use statistical analysis. These tests are not foolproof. The statistical tests assume certain amounts of variation between low and high bytes in a string, and some ASCII strings can slip through. For example, if lpBuffer points to the ASCII string 0x41, 0x0A, 0x0D, 0x1D (A\n\r^Z), the string passes the IS_TEXT_UNICODE_STATISTICS test, though failure would be preferable.


IsValidAcl

The IsValidAcl function validates an access-control list (ACL).

BOOL IsValidAcl(

PACL pAcl	// address of access-control list
);
Parameters

pAcl

Points to an ACL structure validated by this function. This must be a non-NULL value.

Return Values

If the ACL is valid, the return value is nonzero.

If the ACL is not valid, the return value is zero. To get extended error information, call GetLastError.

Remarks

This function checks the revision level of the ACL and verifies that the number of access-control entries (ACEs) specified in the AceCount member of the ACL structure fits the space specified by the AclSize member of the ACL structure.

If pAcl is NULL, the application will fail with an access violation.

See Also

ACL, GetAclInformation, InitializeAcl


IsValidCodePage

The IsValidCodePage determines whether a specified code page is valid.

BOOL IsValidCodePage(

UINT CodePage	// specifies code page to check
);
Parameters

CodePage

Specifies the code page to check. Each code page is identified by a unique number.

Return Values

If the code page is valid, the return value is nonzero.

If the code page is not valid, the return value is zero. To get extended error information, call GetLastError.

Remarks

A code page is considered valid only if it is installed in the system.

Following are the code-page identifiers:

Identifier	Meaning
037	EBCDIC
437	MS-DOS  United States
500	EBCDIC "500V1"
708	Arabic (ASMO 708)
709	Arabic (ASMO 449+, BCON V4)
710	Arabic (Transparent Arabic)
720	Arabic (Transparent ASMO)
737	Greek (formerly 437G)
775	Baltic
850	MS-DOS  Multilingual (Latin I)
852	MS-DOS  Slavic (Latin II)
855	IBM Cyrillic (primarily Russian)
857	IBM Turkish
860	MS-DOS  Portuguese
861	MS-DOS Icelandic
862	Hebrew
863	MS-DOS Canadian-French
864	Arabic
865	MS-DOS Nordic
866	MS-DOS Russian
869	IBM Modern Greek
874	Thai
875	EBCDIC
932	Japan
936	Chinese (PRC, Singapore)
949	Korean
950	Chinese (Taiwan, Hong Kong)
1026	EBCDIC
1200	Unicode (BMP of ISO 10646)
1250	Windows 3.1 Eastern European
1251	Windows 3.1 Cyrillic
1252	Windows 3.1 US (ANSI)
1253	Windows 3.1 Greek
1254	Windows 3.1 Turkish
1255	Hebrew
1256	Arabic
1257	Baltic
1361	Korean (Johab)
10000	Macintosh Roman
10001	Macintosh Japanese
10006	Macintosh Greek I
10007	Macintosh Cyrillic
10029	Macintosh Latin 2
10079	Macintosh Icelandic
10081	Macintosh Turkish
See Also

GetACP, GetCPInfo, GetOEMCP


IsValidLocale

The IsValidLocale function applies a validity test to a locale identifier. The dwFlags parameter determines the nature of the validity test. Currently, the function tests whether a locale identifier is installed or supported on the calling system.

BOOL IsValidLocale(

LCID Locale,	// locale indentifier to validate
DWORD dwFlags	// specifies validity test
);
Parameters

Locale

Specifies the locale identifier to be validated. You can use the MAKELCID macro to create a locale identifier.

dwFlags

Specifies the validity test to apply to the locale identifier. This parameter can be one of the following values:

Value	Meaning
LCID_INSTALLED	Test whether the locale identifier is both supported and installed.
LCID_SUPPORTED	Test whether the locale identifier is supported.
Return Values

If the locale identifier passes the specified validity test, the return value is nonzero.

If the locale identifier does not pass the specified validity test, the return value is zero.

Remarks

If the LCID_INSTALLED flag is specified and this function returns TRUE, the locale identifier is both supported and installed on the system.

If the LCID_SUPPORTED flag is specified and this function returns TRUE, the locale identifier is supported in the release, but not necessarily installed on the system.

See Also

GetLocaleInfo


IsValidSecurityDescriptor

The IsValidSecurityDescriptor function validates a SECURITY_DESCRIPTOR structure. Validation is performed by checking the revision level of each component in the security descriptor.

BOOL IsValidSecurityDescriptor(

PSECURITY_DESCRIPTOR pSecurityDescriptor	// address of security descriptor
);
Parameters

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure that the function validates.

Return Values

If the structure of the security descriptor is valid, the return value is nonzero.

If the structure of the security descriptor is not valid, the return value is zero. To get extended error information, call GetLastError.

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, InitializeSecurityDescriptor, SECURITY_DESCRIPTOR, SetSecurityDescriptorDacl, SetSecurityDescriptorGroup, SetSecurityDescriptorOwner, SetSecurityDescriptorSacl


IsValidSid

The IsValidSid function validates a SID structure by verifying that the revision number is within a known range and that the number of subauthorities is less than the maximum. A SID is a security identifier.

BOOL IsValidSid(

PSID pSid	// address of SID to query
);
Parameters

pSid

Points to the SID structure to validate. This must be a non-NULL value.

Return Values

If the SID structure is valid, the return value is nonzero.

If the SID structure is not valid, the return value is zero. To get extended error information, call GetLastError.

Remarks

If pSid is NULL, the application will fail with an access violation.

See Also

GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthority, GetSidSubAuthorityCount, SID


IsWindow

The IsWindow function determines whether the specified window handle identifies an existing window.

BOOL IsWindow(

HWND hWnd	// handle of window
);
Parameters

hWnd

Specifies the window handle.

Return Values

If the window handle identifies an existing window, the return value is nonzero.

If the window handle does not identify an existing window, the return value is zero.

See Also

IsWindowEnabled, IsWindowVisible


IsWindowEnabled

The IsWindowEnabled function determines whether the specified window is enabled for mouse and keyboard input.

BOOL IsWindowEnabled(

HWND hWnd	// handle of window to test
);
Parameters

hWnd

Identifies the window to test.

Return Values

If the window is enabled, the return value is nonzero.

If the window is not enabled, the return value is zero.

Remarks

A child window receives input only if it is both enabled and visible.

See Also

EnableWindow, IsWindowVisible


IsWindowUnicode

The IsWindowUnicode function determines whether the specified window is a native Unicode window.

BOOL IsWindowUnicode(

HWND hWnd	// handle of window
);
Parameters

hWnd

Identifies the window.

Return Values

If the window is a native Unicode window, the return value is nonzero.

If the window is not a native Unicode window, the return value is zero.

Remarks

The system does automatic two-way translation (Unicode to ANSI-ASCII) for window messages. For example, if an ANSI-ASCII window message is sent to a Unicode window, the system translates that message into a Unicode message before calling the window procedure. The system calls the IsWindowUnicode function to determine whether to translate the message.

When this function returns FALSE, the window is a native ANSI-ASCII window.


IsWindowVisible

The IsWindowVisible function retrieves the visibility state of the specified window.

BOOL IsWindowVisible(

HWND hWnd	// handle of window
);
Parameters

hWnd

Identifies the window.

Return Values

If the specified window and its parent window have the WS_VISIBLE style, the return value is nonzero.

If the specified window and its parent window do not have the WS_VISIBLE style, the return value is zero. Because the return value specifies whether the window has the WS_VISIBLE style, it may be nonzero even if the window is totally obscured by other windows.

Remarks

The visibility state of a window is indicated by the WS_VISIBLE style bit. When WS_VISIBLE is set, the window is displayed and subsequent drawing into it is displayed as long as the window has the WS_VISIBLE style.

Any drawing to a window with the WS_VISIBLE style will not be displayed if the window is obscured by other windows or is clipped by its parent window.

See Also

ShowWindow


IsZoomed

The IsZoomed function determines whether a window is maximized.

BOOL IsZoomed(

HWND hWnd	// handle of window
);
Parameters

hWnd

Identifies the window.

Return Values

If the window is zoomed, the return value is nonzero.

If the window is not zoomed, the return value is zero.

See Also

IsIconic


JournalPlaybackProc

The JournalPlaybackProc hook procedure is a callback function that inserts mouse and keyboard messages into the system message queue. Typically, an application uses this hook procedure to play back a series of mouse and keyboard messages recorded previously by the JournalRecordProc hook procedure. As long as a JournalPlaybackProc hook procedure is installed, regular mouse and keyboard input is disabled.

LRESULT CALLBACK JournalPlaybackProc(

int code,	// hook code
WPARAM wParam,	// undefined
LPARAM lParam	// address of message being processed
);
Parameters

code

Specifies a code the hook procedure uses to determine how to process the message. This parameter can be one of the following values:

Value	Meaning
HC_GETNEXT	The hook procedure must copy the current mouse or keyboard message to the EVENTMSG structure pointed to by the lParam parameter.
HC_NOREMOVE	An application has called the PeekMessage function with wRemoveMsg set to PM_NOREMOVE, indicating that the message is not removed from the message queue after PeekMessage processing.
HC_SKIP	The hook procedure must prepare to copy the next mouse or keyboard message to the EVENTMSG structure pointed to by lParam. Upon receiving the HC_GETNEXT code, the hook procedure must copy the message to the structure.
HC_SYSMODALOFF	A system-modal dialog box has been destroyed. The hook procedure must resume playing back the messages.
HC_SYSMODALON	A system-modal dialog box is being displayed. Until the dialog box is destroyed, the hook procedure must stop playing back messages.
If code is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies a NULL value.

lParam

Points to an EVENTMSG structure that represents a message being processed by the hook procedure. This parameter is valid only when the code parameter is HC_GETNEXT.

Return Values

To have the system wait before processing the message, the return value must be the amount of time, in clock ticks, that the system should wait. (This value can be computed by calculating the difference between the time members in the current and previous input messages.) To process the message immediately, the return value should be zero. The return value is used only if the hook code is HC_GETNEXT; otherwise, it is ignored.

Remarks

A JournalPlaybackProc hook procedure should copy an input message to the lParam parameter. The message must have been previously recorded by using a JournalRecordProc hook procedure, which should not modify the message.

To retrieve the same message over and over, the hook procedure can be called several times with the code parameter set to HC_GETNEXT without an intervening call with code set to HC_SKIP.

If code is HC_GETNEXT and the return value is greater than zero, the system sleeps for the number of milliseconds specified by the return value. When the system continues, it calls the hook procedure again with code set to HC_GETNEXT to retrieve the same message. The return value from this new call to JournalPlaybackProc should be zero; otherwise, the system will go back to sleep for the number of milliseconds specified by the return value, call JournalPlaybackProc again, and so on. The system will appear to be hung.

Unlike most other global hook procedures, the JournalRecordProc and JournalPlaybackProc hook procedures are always called in the context of the thread that set the hook.

After the hook procedure returns control to the system, the message continues to be processed. If code is HC_SKIP, the hook procedure must prepare to return the next recorded event message on its next call.

An application installs a JournalPlaybackProc hook procedure by specifying the WH_JOURNALPLAYBACK hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

A Win32 JournalRecordProc hook procedure does not need to live in a dynamic-link library. A Win32 JournalRecordProc hook procedure can live in the application itself.

If the user presses CTRL+ESC or CTRL+ALT+DEL during journal playback, the system stops the playback, unhooks the journal playback procedure, and posts a WM_CANCELJOURNAL message to the journaling application.

If the hook procedure returns a message in the range WM_KEYFIRST to WM_KEYLAST, the following conditions apply:

•	The paramL member of the EVENTMSG structure specifies the virtual key code of the key that was pressed.

•	The paramH member of the EVENTMSG structure specifies the scan code.

•	There’s no way to specify a repeast count. The event is always taken to represent one key event.

JournalPlaybackProc is a placeholder for an application-defined or library-defined function name.

See Also

CallNextHookEx, EVENTMSG, JournalRecordProc, PeekMessage, SetWindowsHookEx, WM_CANCELJOURNAL


JournalRecordProc

The JournalRecordProc hook procedure is a callback function that records messages the system removes from the system message queue. Later, an application can use a JournalPlaybackProc hook procedure to play back the messages.

LRESULT CALLBACK JournalRecordProc(

int code,	// hook code
WPARAM wParam,	// undefined
LPARAM lParam	// address of message being processed
);
Parameters

code

Specifies how to process the message. This parameter can be one of the following values:

Value	Meaning
HC_ACTION	The lParam parameter points to an EVENTMSG structure containing information about a message removed from the system queue. The hook procedure must record the contents of the structure by copying them to a buffer or file.
HC_SYSMODALOFF	A system-modal dialog box has been destroyed. The hook procedure must resume recording.
HC_SYSMODALON	A system-modal dialog box is being displayed. Until the dialog box is destroyed, the hook procedure must stop recording.
If code is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies a NULL value.

lParam

Points to an EVENTMSG structure that contains the message to be recorded.

Return Values

The return value is ignored.

Remarks

A JournalRecordProc hook procedure must copy but not modify the messages. After the hook procedure returns control to the system, the message continues to be processed.

An application installs a JournalRecordProc hook procedure by specifying the WH_JOURNALRECORD hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

A Win32 JournalRecordProc hook procedure does not need to live in a dynamic-link library. A Win32 JournalRecordProc hook procedure can live in the application itself.

Unlike most other global hook procedures, the JournalRecordProc and JournalPlaybackProc hook procedures are always called in the context of the thread that set the hook.

An application that has installed a JournalRecordProc hook procedure should watch for the VK_CANCEL virtual keycode (which is implemented as the CTRL+BREAK key combination on most keyboards). This virtual keycode should be interpreted by the application as a signal that the user wishes to stop journal recording. The application should respond by ending the recording sequence and removing the JournalRecordProc hook procedure. Removal is important. It prevents a journaling application from locking up the system by hanging inside a hook procedure.

This role as a signal to stop journal recording means that a CTRL+BREAK key combination cannot itself be recorded. Since the CTRL+C key combination has no such role as a journaling signal, it can be recorded. There are two other key combinations that cannot be recorded: CTRL+ESC and CTRL+ALT+DEL. Those two key combinations cause the system to stop all journaling activities (record or playback), remove all journaling hooks, and post a WM_CANCELJOURNAL message to the journaling application.

JournalRecordProc is a placeholder for an application-defined or library-defined function name.

See Also

CallNextHookEx, EVENTMSG, JournalPlaybackProc, SetWindowsHookEx, WM_CANCELJOURNAL


keybd_event

The keybd_event function synthesizes a keystroke. The system can use such a synthesized keystroke to generate a WM_KEYUP or WM_KEYDOWN message. The keyboard driver’s interrupt handler calls the keybd_event function.

VOID keybd_event(

BYTE bVk,	// virtual-key code
BYTE bScan,	// hardware scan code
DWORD dwFlags,	// flags specifying various function options
DWORD dwExtraInfo	// additional data associated with keystroke
);
Parameters

bVk

Specifies a virtual-key code. The code must be a value in the range 1 to 254.

bScan

Specifies a hardware scan code for the key.

dwFlags

A set of flag bits that specify various aspects of function operation. An application can use any combination of the following predefined constant values to set the flags:

Value	Meaning
KEYEVENTF_EXTENDEDKEY	If specified, the scan code was preceded by a prefix byte having the value 0xE0 (224).
KEYEVENTF_KEYUP	If specified, the key is being released. If not specified, the key is being depressed.
dwExtraInfo

Specifies an additional 32-bit value associated with the key stroke.

Return Values

This function has no return value.

Remarks

Although keybd_event passes an OEM-dependent hardware scan code to Windows, applications should not use the scan code. Windows converts scan codes to virtual-key codes internally and clears the up/down bit in the scan code before passing it to applications.

An application can simulate a press of the PRINTSCREEN key in order to obtain a screen snapshot and save it to the Windows clipboard. To do this, call keybd_event with the bVk parameter set to VK_SNAPSHOT, and the bScan parameter set to 0 for a snapshot of the full screen or set bScan to 1 for a snapshot of the active window.

See Also

GetAsyncKeyState, GetKeyState, MapVirtualKey, SetKeyboardState


KeyboardProc

The KeyboardProc hook procedure is an application-defined or library-defined callback function the system calls whenever an application calls the GetMessage or PeekMessage function and there is a keyboard message (WM_KEYUP or WM_KEYDOWN) to be processed.

LRESULT CALLBACK KeyboardProc(

int code,	// hook code
WPARAM wParam,	// virtual-key code
LPARAM lParam	// keystroke-message information
);
Parameters

code

Specifies a code the hook procedure uses to determine how to process the message. This parameter can be one of the following values:

Value	Meaning
HC_ACTION	The wParam and lParam parameters contain information about a keystroke message.
HC_NOREMOVE	The wParam and lParam parameters contain information about a keystroke message, and the keystroke message has not been removed from the message queue. (An application called the PeekMessage function, specifying the PM_NOREMOVE flag.)
If code is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies the virtual-key code of the key that generated the keystroke message.

lParam

Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag. This parameter can be a combination of the following values:

Value	Description
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user’s holding down the key.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as a function key or a key on the numeric keypad. The value is 1 if the key is an extended key; otherwise, it is 0.
25−28	Reserved.
29	Specifies the context code. The value is 1 if the ALT key is down; otherwise, it is 0.
30	Specifies the previous key state. The value is 1 if the key is down before the message is sent; it is 0 if the key is up.
31	Specifies the transition state. The value is 0 if the key is being pressed and 1 if it is being released.
For more information about the lParam parameter, see Keystroke Message Flags.

Return Values

To prevent Windows from passing the message to the rest of the hook chain or to the target window procedure, the return value must be a nonzero value. To allow Windows to pass the message to the target window procedure, bypassing the remaining procedures in the chain, the return value must be zero.

Remarks

An application installs the hook procedure by specifying the WH_KEYBOARD hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

KeyboardProc is a placeholder for the application-defined or library-defined function name.

See Also

CallNextHookEx, GetMessage, PeekMessage, SetWindowsHookEx, WM_KEYUP, WM_KEYDOWN


KillTimer

The KillTimer function destroys the specified timer.

BOOL KillTimer(

HWND hWnd,	// handle of window that installed timer
UINT uIDEvent	// timer identifier
);
Parameters

hWnd

Identifies the window associated with the specified timer. This value must be the same as the hWnd value passed to the SetTimer function that created the timer.

uIDEvent

Specifies the timer to be destroyed. If the window handle passed to SetTimer is valid, this parameter must be the same as the uIDEvent value passed to SetTimer. If the application calls SetTimer with hWnd set to NULL, this parameter must be the timer identifier returned by SetTimer.

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.

Remarks

The KillTimer function does not remove WM_TIMER messages already posted to the message queue.

See Also

SetTimer, WM_TIMER


LBItemFromPt

The LBItemFromPt function retrieves the index of the item at the specified point in a list box.

int LBItemFromPt(

HWND hLB,
POINT pt,
BOOL bAutoScroll
);
Parameters

hLB

Handle to the list box to check.

pt

POINT structure that contains the screen coordinates to check.

bAutoScroll

Scroll flag. If this parameter is TRUE and the point is directly above or below the list box, the function scrolls the list box by one line and returns  − 1. Otherwise, the function does not scroll the list box.

Return Values

The return value is the item identifier if the point is over a list item, or  − 1 otherwise.

Remarks

The LBItemFromPt function only scrolls the list box if a minimum amount of time has passed since it last did so. Timing prevents the list box from scrolling too quickly if the function is called repeatedly in rapid succession — for example, when DL_DRAGGING notification messages or WM_MOUSEMOVE messages are processed.

If the specified point is outside the client area of the list box and bAutoScroll is TRUE, the function scrolls the list box instead of returning an item identifier.

See Also

DL_DRAGGING, POINT, WM_MOUSEMOVE


LCMapString

The LCMapString function maps one character string to another, performing a specified locale-dependent transformation. The function can also be used to generate a sort key for the input string.

int LCMapString(

LCID Locale,	// locale identifier
DWORD dwMapFlags,	// mapping transformation type
LPCTSTR lpSrcStr,	// address of source string
int cchSrc,	// number of characters in source string
LPTSTR lpDestStr,	// address of destination buffer
int cchDest	// size of destination buffer
);
Parameters

Locale

Specifies a locale identifier. The locale provides a context for the string mapping or sort key generation. An application can use the MAKELCID macro to create a locale identifier.

dwMapFlags

A set of flags that indicate the type of transformation to be used during string mapping or sort key generation. An application can specify more than one of these options on a single transformation, although some combinations are invalid. The following mapping options are defined; restrictions are noted following the table:

Option	Meaning
LCMAP_BYTEREV	Windows NT only: Use byte reversal. For example, if you pass in 0x3450 0x4822 the result is 0x5034 0x2248.
LCMAP_FULLWIDTH	Map single-byte characters to double-byte characters.
LCMAP_HALFWIDTH	Map double-byte characters to single-byte characters.
LCMAP_HIRAGANA	Map double-byte Katakana characters to double-byte Hiragana characters.
LCMAP_KATAKANA	Map double-byte Hiragana characters to double-byte Katakana characters.
LCMAP_LOWERCASE	Use lowercase.
LCMAP_SORTKEY	Produce a normalized wide-character sort key.
LCMAP_UPPERCASE	Use uppercase.
NORM_IGNORECASE	Ignore case.
NORM_IGNOREKANATYPE	Do not differentiate between Hiragana and Katakana characters. Corresponding Hiragana and Katakana will compare as equal.
NORM_IGNORENONSPACE	Ignore nonspacing. This flag also removes Japanese accent characters.
NORM_IGNORESYMBOLS	Ignore symbols.
NORM_IGNOREWIDTH	Do not differentiate between a single-byte character and the same character as a double-byte character.
SORT_STRINGSORT	Treat punctuation the same as symbols.
If the LCMAP_SORTKEY flag is not specified, the LCMapString function performs string mapping. In this case the following restrictions apply:

•	LCMAP_LOWERCASE and LCMAP_UPPERCASE are mutually exclusive.

•	LCMAP_HIRAGANA and LCMAP_KATAKANA are mutually exclusive.

•	LCMAP_HALFWIDTH and LCMAP_FULLWIDTH are mutually exclusive.

•	SORT_STRINGSORT, NORM_IGNOREKANATYPE, NORM_IGNOREWIDTH, and NORM_IGNORECASE are not valid.

•	LCMAP_LOWERCASE and LCMAP_UPPERCASE are not valid in combination with any of the following flags: LCMAP_HIRAGANA, LCMAP_KATAKANA, LCMAP_HALFWIDTH, and LCMAP_FULLWIDTH.

When the LCMAP_SORTKEY flag is specified, the LCMapString function generates a sort key. In this case the following restriction applies:

•	All LCMAP_* options are invalid, with the sole exception of LCMAP_BYTEREV. In other words, LCMAP_SORTKEY is mutually exclusive with all other LCMAP_* flags, with the sole exception of LCMAP_BYTEREV. LCMAP_BYTEREV is valid for Windows NT only.

lpSrcStr

Pointer to a source string that the function maps or uses for sort key generation.

cchSrc

Specifies the number of bytes (ANSI version) or characters (Unicode version) in the string pointed to by the lpSrcStr parameter.

This count can include the NULL terminator, or not include it. If the NULL terminator is included in the character count, it does not greatly affect the mapping behavior. That is because NULL is considered to be unsortable, and always maps to itself.

A cchSrc value of −1 specifies that the string pointed to by lpSrcStr is null-terminated. If this is the case, and LCMapString is being used in its string-mapping mode, the function calculates the string’s length itself, and null-terminates the mapped string stored into *lpDestStr.

lpDestStr

Pointer to a buffer into which the function stores the mapped string or sort key.

If LCMAP_SORTKEY is specified, LCMapString stores a sort key into the buffer. The sort key is stored as an array of byte values in the following format:

[all Unicode sort weights] 0x01 [all Diacritic weights] 0x01 [all Case weights] 0x01 [all Special weights] 0x00

Note that the sort key is null-terminated. This is true regardless of the value of cchSrc. Also note that, even if some of the sort weights are absent from the sort key, due to the presence of one or more ignore flags in dwMapFlags, the 0x01 separators and the 0x00 terminator are still present.

cchDest

Specifies the size in bytes (ANSI version) or characters (Unicode version) of the buffer pointed to by lpDestStr.

If the function is being used for string mapping, the size is a character count. If space for a NULL terminator is included in cchSrc, then cchDest must also include space for a NULL terminator.

If the function is being used to generate a sort key, the size is a byte count. This byte count must include space for the sort key 0x00 terminator.

If cchDest is zero, the function’s return value is the number of characters, or bytes if LCMAP_SORTKEY is specified, required to hold the mapped string or sort key. In this case, the buffer pointed to by lpDestStr is not used.

Return Values

If the function succeeds, and the value of cchDest is nonzero, the return value is the number of characters, or bytes if LCMAP_SORTKEY is specified, written to the buffer. This count includes room for a NULL terminator.

If the function succeeds, and the value of cchDest is zero, the return value is the size of the buffer in characters, or bytes if LCMAP_SORTKEY is specified, required to receive the translated string or sort key. This size includes room for a NULL terminator.

If the function fails, the return value is 0. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER

Remarks

The mapped string is null terminated if the source string is null terminated.

The A version of this function maps strings to and from Unicode based on the specified LCID’s default ANSI code page.

If the LCMAP_HIRAGANA flag is specified to map Katakana characters to Hiragana characters, and LCMAP_FULLWIDTH is not specified, the function only maps full-width characters to Hiragana. In this case, any half-width Katakana characters are placed as-is in the output string, with no mapping to Hiragana. An application must specify LCMAP_FULLWIDTH if it wants half-width Katakana characters mapped to Hiragana.

The lpSrcStr and lpDestStr pointers must not be the same. If they are the same, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER.

Even if the wide-character Unicode version of this function is called, the output string is only in WCHAR or CHAR format if the string mapping mode of LCMapString is used. If the sort key generation mode is used, specified by LCMAP_SORTKEY, the output is an array of byte values. An application can compare sort keys by using a byte-by-byte comparison.

An application can call the function with the NORM_IGNORENONSPACE and NORM_IGNORESYMBOLS flags set, and all other options flags cleared, in order to simply strip characters from the input string. If this is done with an input string that is not null-terminated, it is possible for LCMapString to return an empty string and not return an error.

The LCMapString function ignores the Arabic Kashida. If an application calls the function to create a sort key for a string containing an Arabic Kashida, there will be no sort key value for the Kashida.

The function treats the hyphen and apostrophe a bit differently than other punctuation symbols, so that words like coop and co-op stay together in a list. All punctuation symbols other than the hyphen and apostrophe sort before the alphanumeric characters. An application can change this behavior by setting the SORT_STRINGSORT flag. See CompareString for a more detailed discussion of this issue.

When LCMapString is used to generate a sort key, by setting the LC_MAPSORTKEY flag, the sort key stored into *lpDestStr may contain an odd number of bytes. The LCMAP_BYTEREV option (Windows NT only) only reverses an even number of bytes. If both options are chosen, the last (odd-positioned) byte in the sort key is not reversed. If the terminating 0x00 byte is an odd-positioned byte, then it remains the last byte in the sort key. If the terminating 0x00 byte is an even-positioned byte, it exchanges positions with the byte that precedes it.

See Also

CompareString, FoldString, MAKELCID


LeaveCriticalSection

The LeaveCriticalSection function releases ownership of the specified critical section object.

VOID LeaveCriticalSection(

LPCRITICAL_SECTION lpCriticalSection	// address of critical section object
);
Parameters

lpCriticalSection

Points to the critical section object.

Return Values

This function does not return a value.

Remarks

The threads of a single process can use a critical-section object for mutual-exclusion synchronization. The process is responsible for allocating the memory used by a critical-section object, which it can do by declaring a variable of type CRITICAL_SECTION. Before using a critical section, some thread of the process must call the InitializeCriticalSection function to initialize the object.

A thread uses the EnterCriticalSection or TryEnterCriticalSection function to acquire ownership of a critical section object. To release its ownership, the thread must call LeaveCriticalSection once for each time that it entered the critical section.

If a thread calls LeaveCriticalSection when it does not have ownership of the specified critical section object, an error occurs that may cause another thread using EnterCriticalSection to wait indefinitely.

Any thread of the process can use the DeleteCriticalSection function to release the system resources that were allocated when the critical section object was initialized. After this function has been called, the critical section object can no longer be used for synchronization.

See Also

DeleteCriticalSection, EnterCriticalSection, InitializeCriticalSection, TryEnterCriticalSection


LimitEmsPages

The LimitEmsPages function is obsolete.

This function is provided only for compatibility with 16-bit versions of Windows. New Win32-based applications do not require this function.


LineDDA

The LineDDA function determines which pixels should be highlighted for a line defined by the specified starting and ending points.

BOOL LineDDA(

int nXStart,	// x-coordinate of line’s starting point
int nYStart,	// y-coordinate of line’s starting point
int nXEnd,	// x-coordinate of line’s ending point
int nYEnd,	// y-coordinate of line’s ending point
LINEDDAPROC lpLineFunc,	// address of application-defined callback function
LPARAM lpData	// address of application-defined data
);
Parameters

nXStart

Specifies the x-coordinate of the line’s starting point.

nYStart

Specifies the y-coordinate of the line’s starting point.

nXEnd

Specifies the x-coordinate of the line’s ending point.

nYEnd

Specifies the y-coordinate of the line’s ending point.

lpLineFunc

Specifies the address of an application-defined callback function. For more information, see the LineDDAProc callback function.

lpData

Points to the application-defined data.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The LineDDA function passes the coordinates for each point along the line, except for the line’s ending point, to the application-defined callback function. In addition to passing the coordinates of a point, this function passes any existing application-defined data.

The coordinates passed to the callback function match pixels on a video display only if the default transformations and mapping modes are used.

See Also

LineDDAProc


LineDDAProc

A LineDDAProc function is an application-defined callback function that processes coordinates from the LineDDA function. A value of type LINEDDAPROC is a pointer to such a function.

VOID CALLBACK LineDDAProc(

int X,	// x-coordinate of point being evaluated
int Y,	// y-coordinate of point being evaluated
LPARAM lpData	// address of application-defined data
);
Parameters

X

Specifies the x-coordinate of the current point.

Y

Specifies the y-coordinate of the current point.

lpData

Points to the application-defined data.

Remarks

LineDDAProc is a placeholder for an application-defined function name.

An application registers a LineDDAProc function by passing its address to the LineDDA function.

See Also

LineDDA


LineTo

The LineTo function draws a line from the current position up to, but not including, the specified point.

BOOL LineTo(

HDC hdc,	// device context handle
int nXEnd,	// x-coordinate of line’s ending point
int nYEnd	// y-coordinate of line’s ending point
);
Parameters

hdc

Identifies a device context.

nXEnd

Specifies the x-coordinate of the line’s ending point.

nYEnd

Specifies the y-coordinate of the line’s ending point.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The coordinates of the line’s ending point are specified in logical units.

The line is drawn by using the current pen and, if the pen is a geometric pen, the current brush.

If LineTo succeeds, the current position is set to the specified ending point.

See Also

MoveToEx, Polyline, PolylineTo


LoadAccelerators

The LoadAccelerators function loads the specified accelerator table.

HACCEL LoadAccelerators(

HINSTANCE hInstance,	// handle of application instance
LPCTSTR lpTableName	// address of table-name string
);
Parameters

hInstance

Identifies an instance of the module whose executable file contains the accelerator table to load.

lpTableName

Points to a null-terminated string that names the accelerator table to load. Alternatively, this parameter can specify the resource identifier of an accelerator-table resource in the low-order word and zero in the high-order word. The MAKEINTRESOURCE macro can be used to create this value.

Return Values

If the function succeeds, the return value is the handle of the loaded accelerator table.

If the function fails, the return value is NULL.

Remarks

If the accelerator table has not yet been loaded, the function loads it from the specified executable file.

Accelerator tables loaded from resources are freed automatically when the application terminates.

See Also

CopyAcceleratorTable, CreateAcceleratorTable, DestroyAcceleratorTable, MAKEINTRESOURCE


LoadBitmap

The LoadBitmap function loads the specified bitmap resource from a module’s executable file.

HBITMAP LoadBitmap(

HINSTANCE hInstance,	// handle of application instance
LPCTSTR lpBitmapName	// address of bitmap resource name
);
Parameters

hInstance

Identifies the instance of the module whose executable file contains the bitmap to be loaded.

lpBitmapName

Points to a null-terminated string that contains the name of the bitmap resource to be loaded. Alternatively, this parameter can consist of the resource identifier in the low-order word and zero in the high-order word. The MAKEINTRESOURCE macro can be used to create this value.

Return Values

If the function succeeds, the return value is the handle of the specified bitmap.

If the function fails, the return value is NULL.

Remarks

If the bitmap pointed to by the lpBitmapName parameter does not exist or there is insufficient memory to load the bitmap, the function fails.

An application can use the LoadBitmap function to access the predefined bitmaps used by the Win32 API. To do so, the application must set the hInstance parameter to NULL and the lpBitmapName parameter to one of the following values:

OBM_BTNCORNERS	OBM_OLD_RESTORE
OBM_BTSIZE	OBM_OLD_RGARROW
OBM_CHECK	OBM_OLD_UPARROW
OBM_CHECKBOXES	OBM_OLD_ZOOM
OBM_CLOSE	OBM_REDUCE
OBM_COMBO	OBM_REDUCED
OBM_DNARROW	OBM_RESTORE
OBM_DNARROWD	OBM_RESTORED
OBM_DNARROWI	OBM_RGARROW
OBM_LFARROW	OBM_RGARROWD
OBM_LFARROWD	OBM_RGARROWI
OBM_LFARROWI	OBM_SIZE
OBM_MNARROW	OBM_UPARROW
OBM_OLD_CLOSE	OBM_UPARROWD
OBM_OLD_DNARROW	OBM_UPARROWI
OBM_OLD_LFARROW	OBM_ZOOM
OBM_OLD_REDUCE	OBM_ZOOMD
Bitmap names that begin with OBM_OLD represent bitmaps used by Windows versions earlier than 3.0.

For an application to use any of the OBM_ constants, the constant OEMRESOURCE must be defined before the WINDOWS.H header file is included.

The application must call the DeleteObject function to delete each bitmap handle returned by the LoadBitmap function.

See Also

CreateBitmap, DeleteObject, LoadCursor, LoadIcon, MAKEINTRESOURCE


LoadCursor

The LoadCursor function loads the specified cursor resource from the executable (.EXE) file associated with an application instance.

HCURSOR LoadCursor(

HINSTANCE hInstance,	// handle of application instance
LPCTSTR lpCursorName	// name string or cursor resource identifier
);
Parameters

hInstance

Identifies an instance of the module whose executable file contains the cursor to be loaded.

lpCursorName

Points to a null-terminated string that contains the name of the cursor resource to be loaded. Alternatively, this parameter can consist of the resource identifier in the low-order word and zero in the high-order word. The MAKEINTRESOURCE macro can also be used to create this value.

To use one of the Win32 predefined cursors, the application must set the hInstance parameter to NULL and the lpCursorName parameter to one the following values:

Value	Description
IDC_APPSTARTING	Standard arrow and small hourglass
IDC_ARROW	Standard arrow
IDC_CROSS	Crosshair
IDC_IBEAM	Text I-beam
IDC_ICON	Windows NT only: Empty icon
IDC_NO	Slashed circle
IDC_SIZE	Windows NT only: Four-pointed arrow
IDC_SIZEALL	Same as IDC_SIZE
IDC_SIZENESW	Double-pointed arrow pointing northeast and southwest
IDC_SIZENS	Double-pointed arrow pointing north and south
IDC_SIZENWSE	Double-pointed arrow pointing northwest and southeast
IDC_SIZEWE	Double-pointed arrow pointing west and east
IDC_UPARROW	Vertical arrow
IDC_WAIT	Hourglass
Return Values

If the function succeeds, the return value is the handle of the newly loaded cursor.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

LoadCursor only loads the cursor resource if it has not been loaded; otherwise, it retrieves the handle of the existing resource. This function returns a valid cursor handle only if the lpCursorName parameter points to a cursor resource. If lpCursorName points to any type of resource other than a cursor (such as an icon), the return value is not NULL, even though it is not a valid cursor handle.

The LoadCursor function searches the cursor resource most appropriate for the cursor for the current display device. The cursor resource can be a color or monochrome bitmap.

See Also

LoadImage, MAKEINTRESOURCE, SetCursor, SetCursorPos, ShowCursor


LoadCursorFromFile

The LoadCursorFromFile function creates a cursor based on data contained in a file. The file is specified by its name or by a system cursor identifier. The function returns a handle to the newly created cursor. Files containing cursor data may be in either cursor (.CUR) or animated cursor (.ANI) format.

HCURSOR LoadCursorFromFile (

LPCTSTR lpFileName	// pointer to name of cursor file, or system cursor identifier
);
Parameters

lpFileName

Indicates the source of the file data to be used to create the cursor. The data in the file must be in either .CUR or .ANI format.

If the high-order word of lpszFileName is nonzero, it is a pointer to a string that is a fully qualified name of a file containing cursor data.

If the high-order word of lpszFileName is zero, the low-order word is a system cursor identifier. The function then searches the [Cursors] entry in the WIN.INI file for the file associated with the name of that system cursor. Here is a list of system cursor names and identifiers:

System Cursor Names	System Cursor Identifiers
“Arrow”	OCR_NORMAL
“IBeam”	OCR_IBEAM
“Wait”	OCR_WAIT
“Crosshair”	OCR_CROSS
“UpArrow”	OCR_UP
“Size”	OCR_SIZE
“Icon”	OCR_ICON
“SizeNWSE”	OCR_SIZENWSE
“SizeNESW”	OCR_SIZENESW
“SizeWE”	OCR_SIZEWE
“SizeNS”	OCR_SIZENS
“SizeAll”	OCR_SIZEALL
“No”	OCR_NO
“AppStarting”	OCR_APPSTARTING
For example, if the WIN.INI file contains the following :

[Cursors]

Arrow = "arrow.ani"

Then the call

LoadCursorFromFile((LPWSTR)OCR_NORMAL)

causes the LoadCursorFromFile function to obtain cursor data from the file ARROW.ANI. If the WIN.INI file doesn’t contain an entry for the specified system cursor, the function fails and returns NULL.

Return Values

If the function is successful, the return value is a handle to the new cursor.

If the function fails, the return value is NULL. To get extended error information, call GetLastError. GetLastError may return the following value:

Value	Meaning
ERROR_FILE_NOT_FOUND	The specified file could not be found.
See Also

LoadCursor, SetCursor, SetSystemCursor


LoadIcon

The LoadIcon function loads the specified icon resource from the executable (.EXE) file associated with an application instance.

HICON LoadIcon(

HINSTANCE hInstance,	// handle of application instance
LPCTSTR lpIconName	// icon-name string or icon resource identifier
);
Parameters

hInstance

Identifies an instance of the module whose executable file contains the icon to be loaded. This parameter must be NULL when a standard icon is being loaded.

lpIconName

Points to a null-terminated string that contains the name of the icon resource to be loaded. Alternatively, this parameter can contain the resource identifier in the low-order word and zero in the high-order word. Use the MAKEINTRESOURCE macro to create this value.

To use one of the Windows predefined icons, set the hInstance parameter to NULL and the lpIconName parameter to one of the following values:

Value	Description
IDI_APPLICATION	Default application icon.
IDI_ASTERISK	Asterisk (used in informative messages).
IDI_EXCLAMATION	Exclamation point (used in warning messages).
IDI_HAND	Hand-shaped icon (used in serious warning messages).
IDI_QUESTION	Question mark (used in prompting messages).
IDI_WINLOGO	Windows logo.
Return Values

If the function succeeds, the return value is the handle of the newly loaded icon.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

LoadIcon loads the icon resource only if it has not been loaded; otherwise, it retrieves a handle to the existing resource. The function searches the icon resource for the icon most appropriate for the current display. The icon resource can be a color or monochrome bitmap.

LoadIcon can only load an icon whose size conforms to the SM_CXICON and SM_CYICON system metric values. Use the LoadImage function to load icons of other sizes.

See Also

CreateIcon, LoadImage, MAKEINTRESOURCE


LoadImage [Now Supported on Windows NT]
LoadImage

[Now Supported on Windows NT]

The LoadImage function loads an icon, cursor, or bitmap.

HANDLE LoadImage(

HINSTANCE hinst,	// handle of the instance that contains the image
LPCTSTR lpszName,	// name or identifier of image
UINT uType,	// type of image
int cxDesired,	// desired width
int cyDesired,	// desired height
UINT fuLoad	// load flags
);
Parameters

hinst

Identifies an instance of the module that contains the image to be loaded. To load an OEM image, set this parameter to zero.

lpszName

Identifies the image to load.

If the hinst parameter is non-NULL and the fuLoad parameter does not include LR_LOADFROMFILE, lpszName is a pointer to a null-terminated string that contains the name of the image resource in the hinst module.

If hinst is NULL and LR_LOADFROMFILE is not specified, the low-order word of this parameter must be the identifier of the OEM image to load. The OEM image identifiers are defined in WINUSER.H and have the following prefixes:

Prefix	Meaning
OBM_	OEM bitmaps
OIC_	OEM icons
OCR_	OEM cursors
Windows 95: If the fuLoad parameter includes the LR_LOADFROMFILE value, lpszName is the name of the file that contains the image.

Windows NT: LR_LOADFROMFILE is not supported.

uType

Specifies the type of image to be loaded. This parameter can be one of the following values:

Value	Meaning
IMAGE_BITMAP	Loads a bitmap.
IMAGE_CURSOR	Loads a cursor.
IMAGE_ICON	Loads an icon.
cxDesired

Specifies the width, in pixels, of the icon or cursor. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE, the function uses the SM_CXICON or SM_CXCURSOR system metric value to set the width. If this parameter is zero and LR_DEFAULTSIZE is not used, the function uses the actual resource width.

cyDesired

Specifies the height, in pixels, of the icon or cursor. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE, the function uses the SM_CYICON or SM_CYCURSOR system metric value to set the height. If this parameter is zero and LR_DEFAULTSIZE is not used, the function uses the actual resource height.

fuLoad

Specifies a combination of the following values:

Value	Meaning
LR_DEFAULTCOLOR	The default flag; it does nothing. All it means is "not LR_MONOCHROME".
LR_CREATEDIBSECTION	When the uType parameter specifies IMAGE_BITMAP, causes the function to return a DIB section bitmap rather than a compatible bitmap. This flag is useful for loading a bitmap without mapping it to the colors of the display device.
LR_DEFAULTSIZE	Uses the width or height specified by the system metric values for cursors or icons, if the cxDesired or cyDesired values are set to zero. If this flag is not specified and cxDesired and cyDesired are set to zero, the function uses the actual resource size. If the resource contains multiple images, the function uses the size of the first image.
LR_LOADFROMFILE	Loads the image from the file specified by the lpszName parameter. If this flag is not specified, lpszName is the name of the resource.
LR_LOADMAP3DCOLORS	Searches the color table for the image and replaces the following shades of gray with the corresponding 3D color:
Color	Replaced with
Dk Gray, RGB(128,128,128)	COLOR_3DSHADOW
Gray, RGB(192,192,192)	COLOR_3DFACE
Lt Gray, RGB(223,223,223)	COLOR_3DLIGHT
LR_LOADTRANSPARENT	Retrieves the color value of the first pixel in the image and replaces the corresponding entry in the color table with the default window color (COLOR_WINDOW). All pixels in the image that use that entry become the default window color. This value applies only to images that have corresponding color tables.  If fuLoad includes both the LR_LOADTRANSPARENT and LR_LOADMAP3DCOLORS values, LRLOADTRANSPARENT takes precedence. However, the color table entry is replaced with COLOR_3DFACE rather than COLOR_WINDOW.
LR_MONOCHROME	Loads the image in black and white.
LR_SHARED	Shares the image handle if the image is loaded multiple times. If LR_SHARED is not set, a second call to LoadImage for the same resource will load the image again and return a different handle. Do not use LR_SHARED for images that have non-standard sizes, that may change after loading, or that are loaded from a file.
Return Values

If the function succeeds, the return value is the handle of the newly loaded image.

If the function fails, the return value is NULL.

See Also

CopyImage, GetSystemMetrics, LoadBitmap, LoadCursor, LoadIcon


LoadKeyboardLayout

The implementations of LoadKeyboardLayout in Windows 95 and Windows NT are substantially different. To accommodate these differences, this reference page first presents the Windows 95 implementation in its entirety, followed by the Windows NT version.

Windows 95:

The LoadKeyboardLayout function loads a new keyboard layout into the system. Several keyboard layouts can be loaded at a time, but only one per process is active at a time. Loading multiple keyboard layouts makes it possible to rapidly switch between layouts.

HKL LoadKeyboardLayout(

LPCTSTR pwszKLID,	// name of layout to load
UINT Flags	// keyboard layout flags
);
Parameters

pwszKLID

Points to the buffer that specifies the name of the keyboard layout. This name is a string composed from the hexadecimal value of the primary language identifier (low word) and a device identifier (high word). For example, U.S. English has a language identifier of 0x0409, so the primary U.S. English layout is named “00000409”. Variants of U.S. English layout, such as the Dvorak layout, are named “00010409”, “00020409”, and so on. For a list of the primary language identifiers and secondary language identifiers that make up a language identifier, see the MAKELANGID macro.

Flags

Specifies how the keyboard layout is to be loaded. This parameter can be one of the following values:

Value	Meaning
KLF_ACTIVATE	If the given layout is not already loaded, the function loads and activates the layout for the current thread, inserting the layout at the head of the keyboard layouts list in front of the previously active layout. If the layout is already loaded and the KLF_REORDER value is not given, the function simply rotates the keyboard layouts list, making the next layout the active layout.
KLF_NOTELLSHELL	Prevents a ShellProc hook procedure from receiving an HSHELL_LANGUAGE hook code when the new layout is loaded. This value is typically used when an application loads multiple layouts, one after another. Applying this value to all but the last layout delays the shell’s processing until all layouts have been added.
KLF_REORDER	Moves the given layout to the head of the keyboard layouts list, making that layout the active layout for the current thread. This value reorders the keyboard layouts list even if KLF_ACTIVATE is not given.
KLF_REPLACELANG	If the new layout has the same language identifier as a current layout, the new layout replaces the current one as the layout for that language. If this value is not given and the layouts have the same language identifiers, the current layout is not replaced and the function returns NULL.
KLF_SUBSTITUTE_OK	Substitues the given keyboard layout with another layout preferred by the user. The substitution occurs only if the registry key HKEY_CURRENT_USER\Keyboard Layout\Substitutes explicitly defines a substitution layout. For example, if the key includes the value name “00000409” with value “00010409”, loading the U.S. English layout (“00000409”) causes the Dvorak U.S. English layout (“00010409”) to be loaded instead. The system uses KLF_SUBSTITUTE_OK when booting and it is recommended that all applications use this value too.
Return Values

If the function succeeds, the return value is the keyboard layout handle of the layout matched with the requested name or NULL if no matching keyboard is available.

Remarks

If a layout is to be loaded with the same language as a previously loaded one and the KLF_REPLACELANG flag is not set, the call fails. Only one loaded layout may be associated with a given language. (It is acceptable for multiple IMEs to be loaded with associations to the same language.)

An application can and will typically want to load the default layout or IME for a language and can do so by specifying only a string version of the language identifier. If an application wants to load a specific layout or IME, it should read the registry to determine the specific layout identifier to pass to LoadKeyboardLayout. In this case, a request to activate the default keyboard layout handle for a locale will activate the first matching one. A specific IME should be activated using an explicit keyboard layout handle returned from one of GetKeyboardLayout, GetKeyboardLayoutList or LoadKeyboardLayout.

See Also

ActivateKeyboardLayout, GetKeyboardLayout, GetKeyboardLayoutName, MAKELANGID, UnloadKeyboardLayout

Windows NT:

The LoadKeyboardLayout function loads a keyboard layout.

HKL LoadKeyboardLayout(

LPCTSTR pwszKLID,	// address of buffer for layout name
UINT Flags	// keyboard layout flags
);
Parameters

pwszKLID

Points to the buffer that specifies the name of the keyboard layout. The name should be derived from the hexadecimal value of the language identifier corresponding to the layout. For example, U.S. English has a language identifier of 0x0409, so the primary U.S. English layout is named “00000409”. Variants of U.S. English layout, such as the Dvorak layout, are named “00010409”,  “00020409”, and so on. For a list of the primary language identifiers and sub-language identifiers that make up a language identifier, see the MAKELANGID macro.

Flags

Specifies how the keyboard layout is to be loaded. This parameter can be one of the following values:

Value	Meaning
KLF_ACTIVATE	The function loads the layout if it is not already loaded, and activates it. This value activates the layout for the entire system not just the calling thread.
KLF_REORDER	This flag is meaningful only if the KLF_ACTIVATE flag is set and the layout is already loaded. If these conditions are met and the KLF_REORDER bit is set, the function removes the specified layout from its position in the system’s circular list of loaded layouts, and places it at the head of the list as the active layout.
	If the KLF_ACTIVATE bit is set and the layout is loaded but the KLF_REORDER bit is not set, the function simply rotates the system’s circular list of loaded layouts.
	If the KLF_ACTIVATE flag is set and the layout is not already loaded, it is loaded as the active layout and inserted in the system’s circular list of keyboard layouts ahead of the previously active layout.
KLF_SUBSTITUTE_OK	The specified layout is looked up in the user’s profile (in the registry under the key HKEY_CURRENT_USER\Keyboard Layout\Substitutes) to find a substitution layout preferred by the user. For example, if there was a value in this section of name “00000409” equal to “00010409”, loading the U.S. English layout (“00000409”) with the KLF_SUBSTITUTE_OK flag set would cause the Dvorak U.S. English layout (“00010409”) to be loaded.
KLF_UNLOADPREVIOUS	If KLF_ACTIVATE is specified, and the layout is loaded and activated successfully, the function unloads the previously active layout. Otherwise, the function ignores this flag.
Return Values

If the function succeeds, the return value is the handle of the keyboard layout.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Several keyboard layouts can be loaded at a time, but only one at a time is active. Loading multiple keyboard layouts makes it possible to switch rapidly between layouts.

See Also

ActivateKeyboardLayout, GetKeyboardLayoutName, UnloadKeyboardLayout


LoadLibrary

The LoadLibrary function maps the specified executable module into the address space of the calling process.

HINSTANCE LoadLibrary(

LPCTSTR lpLibFileName	// address of filename of executable module
);
Parameters

lpLibFileName

Points to a null-terminated string that names the executable module (either a .DLL or .EXE file). The name specified is the filename of the module and is not related to the name stored in the library module itself, as specified by the LIBRARY keyword in the module-definition (.DEF) file.

If the string specifies a path but the file does not exist in the specified directory, the function fails.

If a path is not specified and the filename extension is omitted, the default library extension .DLL is appended. However, the filename string can include a trailing point character (.) to indicate that the module name has no extension. When no path is specified, the function searches for the file in the following sequence:

1.	The directory from which the application loaded.

2.	The current directory.

3.	Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path of this directory.

Windows NT: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	Windows NT: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

The first directory searched is the one directory containing the image file used to create the calling process (for more information, see the CreateProcess function). Doing this allows private dynamic-link library (DLL) files associated with a process to be found without adding the process’s installed directory to the PATH environment variable.

Once the function obtains a fully qualified path to a library module file, the path is compared (case independently) to the full paths of library modules currently loaded into the calling process. These libraries include those loaded when the process was starting up as well as those previously loaded by LoadLibrary but not unloaded by FreeLibrary. If the path matches the path of an already loaded module, the function just increments the reference count for the module and returns the module handle for that library.

Return Values

If the function succeeds, the return value is a handle to the module.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

LoadLibrary can be used to map a DLL module and return a handle that can be used in GetProcAddress to get the address of a DLL function. LoadLibrary can also be used to map other executable modules. For example, the function can specify an .EXE file to get a handle that can be used in FindResource or LoadResource.

Module handles are not global or inheritable. A call to LoadLibrary by one process does not produce a handle that another process can use — for example, in calling GetProcAddress. The other process must make its own call to LoadLibrary for the module before calling GetProcAddress.

If the module is a DLL not already mapped for the calling process, the system calls the DLL’s DllEntryPoint function with the DLL_PROCESS_ATTACH value. If the DLL’s entry-point function does not return TRUE, LoadLibrary fails and returns NULL.

Windows 95: If you are using LoadLibrary to load a module that contains a resource whose numeric identifier is greater than 0x7FFF, LoadLibrary fails.

See Also

DllEntryPoint, FindResource, FreeLibrary, GetProcAddress, GetSystemDirectory, GetWindowsDirectory, LoadResource


LoadLibraryEx

The LoadLibraryEx function maps a specified executable module into the address space of the calling process. The executable module can be a .DLL or an .EXE file. The specified module may cause other modules to be mapped into the address space.

HINSTANCE LoadLibraryEx(

LPCTSTR lpLibFileName,	// points to name of executable module
HANDLE hFile,	// reserved, must be NULL
DWORD dwFlags	// entry-point execution flag
);
Parameters

lpLibFileName

Points to a null-terminated string that names a Win32 executable module (either a .DLL or an .EXE file). The name specified is the filename of the executable module. This name is not related to the name stored in a library module itself, as specified by the LIBRARY keyword in the module-definition (.DEF) file.

If the string specifies a path, but the file does not exist in the specified directory, the function fails.

If the string does not specify a path, and the filename extension is omitted, the function appends the default library extension .DLL to the filename. However, the filename string can include a trailing point character (.) to indicate that the module name has no extension.

If the string does not specify a path, the function uses a standard search strategy to find the file. See the Remarks for more information.

If mapping the specified module into the address space causes the operating system to map in other, associated executable modules, the function can use either the standard search strategy or an alternate search strategy to find those modules. See the Remarks for more information.

Once the function obtains a fully qualified path to a library module file, the path is compared (in a case-independent manner) to the full paths of library modules that are currently loaded into the calling process. That set of libraries includes those that were loaded when the process was starting up, as well as those previously loaded by calls to LoadLibrary or LoadLibraryEx but not yet unloaded by calls to FreeLibrary. If the path matches the path of an already loaded module, the function just increments the reference count for the module, and returns the module handle for that library.

hFile

This parameter is reserved for future use. It must be NULL.

dwFlags

Specifies the action to take when loading the module. This parameter can be one of the following values:

Flag	Meaning
DONT_RESOLVE_DLL_REFERENCES
	Windows NT only:  If this value is given, and the executable module is a dynamic-link library (DLL), the operating system does not call the DllEntryPoint function for process and thread initialization and termination. Also, the system does not load additional executable modules that are referenced by the specified module. If this value is not given, and the executable module is a DLL, the operating system calls the DllEntryPoint function for process and thread initialization and termination. The system loads additional executable modules that are referenced by the specified module. The behavior of the function is then identical to that of LoadLibrary in this regard.
LOAD_LIBRARY_AS_DATAFILE
	If this value is given, the function does a simple mapping of the file into the address space. Nothing is done relative to executing or preparing to execute the code in the mapped file. The function loads the module as if it were a data file. You can use the module handle that the function returns in this case with the Win32 functions that operate on resources. Use this flag when you want to load a DLL in order to extract messages or resources from it, and have no intention of executing its code. If this value is not given, the function maps the file into the address space in the manner that is normal for an executable module. The behavior of the function is then identical to that of LoadLibrary in this regard.
LOAD_WITH_ALTERED_SEARCH_PATH
	If this value is given, and lpLibFileName specifies a path, the function uses the alternate file search strategy discussed in the Remarks section following to find associated executable modules that the specified module causes to be loaded. If this value is not given, or if lpLibFileName does not specify a path, the function uses the standard search strategy discussed in the Remarks section following to find associated executable modules that the specified module causes to be loaded. The behavior of the function is then identical to that of LoadLibrary in this regard.
Return Values

If the function succeeds, the return value is a handle to the mapped executable module.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Note that the DONT_RESOLVE_DLL_REFERENCES flag is only implemented on the Windows NT platform. It is not implemented on the Windows 95 platform.

The calling process can use the handle returned by this function to identify the module in calls to the GetProcAddress, FindResource, and LoadResource functions.

The LoadLibraryEx function is very similar to the LoadLibrary function. The differences consist of a set of optional behaviors that LoadLibraryEx provides. First, LoadLibraryEx can map a DLL module without calling the DllEntryPoint function of the DLL. Second, LoadLibraryEx can use either of two file search strategies to find executable modules that are associated with the specified module. Third, LoadLibraryEx can load a module in a way that is optimized for the case where the module will never be executed, loading the module as if it were a data file. You select these optional behaviors by setting the dwFlags parameter; if dwFlags is zero, LoadLibraryEx behaves identically to LoadLibrary.

If no path is specified, the LoadLibraryEx function uses the same standard file search strategy that LoadLibrary, SearchPath, and OpenFile use to find the executable module and any associated executable modules that it causes to be loaded. This standard strategy searches for a file in the following sequence:

1.	The directory from which the application loaded.

2.	The current directory.

3.	Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path of this directory.

Windows NT: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	Windows NT: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

If a path is specified, and the dwFlags parameter is set to LOAD_WITH_ALTERED_SEARCH_PATH, the LoadLibraryEx function uses an alternate file search strategy to find any executable modules that the specified module causes to be loaded. This alternate strategy searches for a file in the following sequence:

1.	The directory specified by the lpLibFileName path. In other words, the directory that the specified executable module is in.

2.	The current directory.

3.	Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path of this directory.

Windows NT: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	Windows NT: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

Note that the standard file search strategy and the alternate search strategy differ in just one way: the standard strategy starts its search in the calling application’s directory, and the alternate strategy starts its search in the directory of the executable module that LoadLibraryEx is loading.

If you specify the alternate search strategy, its behavior continues until all associated executable modules have been located. Once the system starts processing DLL initialization routines, the system reverts to the standard search strategy.

See Also

DllEntryPoint, FindResource, FreeLibrary, GetProcAddress, GetSystemDirectory, GetWindowsDirectory, LoadLibrary, LoadResource, OpenFile, SearchPath


LoadMenu

The LoadMenu function loads the specified menu resource from the executable (.EXE) file associated with an application instance.

HMENU LoadMenu(

HINSTANCE hInstance,	// handle of application instance
LPCTSTR lpMenuName	// menu name string or menu-resource identifier
);
Parameters

hInstance

Identifies the instance of the module containing the menu resource to be loaded.

lpMenuName

Points to a null-terminated string that contains the name of the menu resource. Alternatively, this parameter can consist of the resource identifier in the low-order word and zero in the high-order word. To create this value, use the MAKEINTRESOURCE macro.

Return Values

If the function succeeds, the return value is the handle of the menu resource.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The DestroyMenu function is used, before an application closes, to destroy the menu and free memory that the loaded menu occupied.

See Also

LoadMenuIndirect, MAKEINTRESOURCE


LoadMenuIndirect

The LoadMenuIndirect function loads the specified menu template in memory.

HMENU LoadMenuIndirect(

CONST MENUTEMPLATE *lpMenuTemplate	// address of menu template
);
Parameters

lpMenuTemplate

Points to a menu template or an extended menu template.

A menu template consists of a MENUITEMTEMPLATEHEADER structure followed by one or more contiguous MENUITEMTEMPLATE structures. An extended menu template consists of a MENUEX_TEMPLATE_HEADER structure followed by one or more contiguous MENUEX_TEMPLATE_ITEM structures.

Return Values

If the function succeeds, the return value is the handle of the menu.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

For both the ANSI and the Unicode version of this function, the strings in the MENUITEMTEMPLATE structure must be Unicode strings.

See Also

LoadMenu, MENUEX_TEMPLATE_HEADER, MENUEX_TEMPLATE_ITEM, MENUITEMTEMPLATE, MENUITEMTEMPLATEHEADER


LoadModule

The LoadModule function loads and executes a Windows-based application or creates a new instance of an existing Windows-based application.

This function is provided for compatibility with earlier versions of Windows. Win32-based applications should use the CreateProcess function.

DWORD LoadModule(

LPCSTR lpModuleName,	// address of filename to load
LPVOID lpParameterBlock	// address of parameter block for new module
);
Parameters

lpModuleName

Points to a null-terminated string that contains the filename of the application to run. If the lpModuleName parameter does not contain a directory path, Windows searches for the executable file in this order:

1.	The directory from which the application loaded.

2.	The current directory.

3.	Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path of this directory.

Windows NT: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	Windows NT: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

lpParameterBlock

Points to an application-defined LOADPARMS32 structure that defines the new application’s parameter block.

The LOADPARMS32 structure has the following form:

typedef struct tagLOADPARMS32 {

    LPSTR lpEnvAddress;  // address of environment strings

    LPSTR lpCmdLine;     // address of command line

    LPSTR lpCmdShow;     // how to show new program

    DWORD dwReserved;    // must be zero

} LOADPARMS32;

Member	Description
lpEnvAddress	Points to an array of null-terminated strings that supply the environment strings for the new process. The array has a value of NULL as its last entry. A value of NULL for this parameter causes the new process to start with the same environment as the calling process.
lpCmdLine	Points to a Pascal-style string that contains a correctly formed command line. The first byte of the string contains the number of bytes in the string. The remainder of the string contains the command line arguments, excluding the name of the child process. If there are no command line arguments, this parameter must point to a zero length string; it cannot be NULL.
lpCmdShow	Points to a structure containing two WORD values. The first value must always be set to two. The second value specifies how the application window is to be shown and is used to supply the wShowWindow member of the STARTUPINFO structure to the CreateProcess function. See the description of the nCmdShow parameter of the ShowWindow function for a list of acceptable values.
dwReserved	This parameter is reserved; it must be zero.
Set all unused members to NULL, except for lpCmdLine, which must point to a null-terminated string if it is not used.

Return Values

If the function succeeds, the return value is greater than 31.

If the function fails, the return value is an error value, which may be one of the following:

Value	Meaning
0	The system is out of memory or resources.
ERROR_BAD_FORMAT	The .EXE file is invalid (non-Win32 .EXE or error in .EXE image).
ERROR_FILE_NOT_FOUND	The specified file was not found.
ERROR_PATH_NOT_FOUND	The specified path was not found.
Remarks

Win32-based applications should use the CreateProcess function. In the Win32 API, the implementation of the LoadModule function calls CreateProcess. The following section describes how each parameter for CreateProcess is formed:

CreateProcess parameter	Value
lpszImageName	LoadModule lpModuleName parameter.
lpszCommandLine	LoadModule lpParameterBlock->lpCmdLine.
lpsaProcess	NULL.
lpsaThread	NULL.
fInheritHandles	FALSE.
fdwCreate	0.
lpvEnvironment	LoadModule lpParameterBlock->lpEnvAddress.
lpszCurDir	NULL.
lpsiStartInfo	The structure is initialized to zero. The cb member is set to the size of the structure, and the wShowWindow member is set to the value of the second word of the LoadModule lpParameterBlock->lpCmdShow parameter.
lppiProcInfo.hProcess	The handle is immediately closed.
lppiProcInfo.hThread	The handle is immediately closed.
See Also

CreateProcess, GetSystemDirectory, GetWindowsDirectory, ShowWindow, STARTUPINFO, WinExec


LoadResource

The LoadResource function loads the specified resource into global memory.

HGLOBAL LoadResource(

HMODULE hModule,	// resource-module handle
HRSRC hResInfo	// resource handle
);
Parameters

hModule

Identifies the module whose executable file contains the resource. If hModule is NULL, Windows loads the resource from the module that was used to create the current process.

hResInfo

Identifies the resource to be loaded. This handle must be created by using the FindResource or FindResourceEx function.

Return Values

If the function succeeds, the return value is a handle to the global memory block containing the data associated with the resource.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Both Windows 95 and Windows NT automatically free resources. You do not need to call the FreeResource function to free a resource loaded by using the LoadResource function.

See Also

FindResource, FindResourceEx, FreeResource, LoadLibrary, LoadModule, LockResource


LoadString

The LoadString function loads a string resource from the executable file associated with a specified module, copies the string into a buffer, and appends a terminating null character.

int LoadString(

HINSTANCE hInstance,	// handle of module containing string resource
UINT uID,	// resource identifier
LPTSTR lpBuffer,	// address of buffer for resource
int nBufferMax	// size of buffer
);
Parameters

hInstance

Identifies an instance of the module whose executable file contains the string resource.

uID

Specifies the integer identifier of the string to be loaded.

lpBuffer

Points to the buffer to receive the string.

nBufferMax

Specifies the size of the buffer in bytes (ANSI version) or characters (Unicode version). The string is truncated and null terminated if it is longer than the number of characters specified.

Return Values

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) copied into the buffer, not including the null-terminating character, or zero if the string resource does not exist. To get extended error information, call GetLastError.

See Also

FormatMessage, LoadAccelerators, LoadBitmap, LoadCursor, LoadIcon, LoadMenu, LoadMenuIndirect


LocalAlloc

The LocalAlloc function allocates the specified number of bytes from the heap. In the linear Win32 API environment, there is no difference between the local heap and the global heap.

HLOCAL LocalAlloc(

UINT uFlags,	// allocation attributes
UINT uBytes	// number of bytes to allocate
);
Parameters

uFlags

Specifies how to allocate memory. If zero is specified, the default is the LMEM_FIXED flag. Except for the incompatible combinations that are specifically noted, any combination of the following flags can be specified. To indicate whether the function allocates fixed or movable memory, specify one of the first six flags:

Flag	Meaning
LMEM_FIXED
	Allocates fixed memory. This flag cannot be combined with the LMEM_MOVEABLE or LMEM_DISCARDABLE flag. The return value is a pointer to the memory block. To access the memory, the calling process simply casts the return value to a pointer.
LMEM_MOVEABLE
	Allocates movable memory. This flag cannot be combined with the LMEM_FIXED flag. The return value is the handle of the memory object. The handle is a 32-bit quantity that is private to the calling process. To translate the handle into a pointer, use the LocalLock function.
LPTR
	Combines the LMEM_FIXED and LMEM_ZEROINIT flags.
LHND
	Combines the LMEM_MOVEABLE and LMEM_ZEROINIT flags.
NONZEROLHND
	Same as the LMEM_MOVEABLE flag.
NONZEROLPTR
	Same as the LMEM_FIXED flag.
LMEM_DISCARDABLE
	Allocates discardable memory. This flag cannot be combined with the LMEM_FIXED flag. Some Win32-based applications may ignore this flag.
LMEM_NOCOMPACT
	Does not compact or discard memory to satisfy the allocation request.
LMEM_NODISCARD
	Does not discard memory to satisfy the allocation request.
LMEM_ZEROINIT
	Initializes memory contents to zero.
uBytes

Specifies the number of bytes to allocate. If this parameter is zero and the uFlags parameter specifies the LMEM_MOVEABLE flag, the function returns a handle to a memory object that is marked as discarded.

Return Values

If the function succeeds, the return value is the handle of the newly allocated memory object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If the heap does not contain sufficient free space to satisfy the request, LocalAlloc returns NULL.

The GlobalAlloc and LocalAlloc functions are limited to a combined total of 65,536 handles for GMEM_MOVEABLE and LMEM_MOVEABLE memory per process. This limitation does not apply to GMEM_FIXED or LMEM_FIXED memory.

If this function succeeds, it allocates at least the amount requested. If the amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual number of bytes allocated, use the LocalSize function.

See Also

GlobalAlloc, LocalFree, LocalLock, LocalReAlloc, LocalSize


LocalCompact

The LocalCompact function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows.


LocalDiscard

The LocalDiscard function discards the specified local memory object. The lock count of the memory object must be zero.

HLOCAL LocalDiscard(

HLOCAL hlocMem	// handle of local memory object
);
Parameters

hlocMem

Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Return Values

If the function succeeds, the return value is the handle of the local memory object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

LocalDiscard discards only local objects allocated by a process with the LMEM_DISCARDABLE flag. If a process attempts to discard a fixed or locked object, the function fails.

Although LocalDiscard discards the object’s memory block, the handle of the object remains valid. A process can subsequently pass the handle to the LocalReAlloc function to allocate another local memory object identified by the same handle.

See Also

LocalAlloc, LocalReAlloc


LocalFileTimeToFileTime

The LocalFileTimeToFileTime function converts a local file time to a file time based on the Coordinated Universal Time (UTC).

BOOL LocalFileTimeToFileTime(

CONST FILETIME *lpLocalFileTime,	// address of local file time to convert
LPFILETIME lpFileTime	// address of converted file time
);
Parameters

lpLocalFileTime

Points to a FILETIME structure that specifies the local file time to be converted into a UTC-based file time.

lpFileTime

Points to a FILETIME structure to receive the converted UTC-based file time. This parameter cannot be the same as the lpLocalFileTime parameter.

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, use the GetLastError function.

See Also

FILETIME, FileTimeToLocalFileTime


LocalFlags

The LocalFlags function returns information about the specified local memory object.

UINT LocalFlags(

HLOCAL hMem	// handle of local memory object
);
Parameters

hMem

Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Return Values

If the function succeeds, the return value is a 32-bit value that specifies the allocation flags and the lock count for the memory object.

If the function fails, the return value is the LMEM_INVALID_HANDLE flag, indicating that the local handle is not valid. To get extended error information, call GetLastError.

Remarks

The low-order byte of the low-order word of the return value contains the lock count of the object. To retrieve the lock count from the return value, use the LMEM_LOCKCOUNT mask with the bitwise AND (&) operator. The lock count of memory objects allocated with the LMEM_FIXED flag is always zero.

The high-order byte of the low-order word of the return value indicates the allocation flags of the memory object. It can be zero or any combination of the following flags:

Value	Description
LMEM_DISCARDABLE	The object’s memory block can be discarded.
LMEM_DISCARDED	The object’s memory block has been discarded.
See Also

GlobalFlags, LocalAlloc, LocalDiscard, LocalLock, LocalReAlloc, LocalUnlock


LocalFree

The LocalFree function frees the specified local memory object and invalidates its handle.

HLOCAL LocalFree(

HLOCAL hMem	// handle of local memory object
);
Parameters

hMem

Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Return Values

If the function succeeds, the return value is NULL.

If the function fails, the return value is equal to the handle of the local memory object. To get extended error information, call GetLastError.

Remarks

If the process tries to examine or modify the memory after it has been freed, heap corruption may occur or an access violation exception (EXCEPTION_ACCESS_VIOLATION) may be generated.

If the hMem parameter is NULL, LocalFree ignores the parameter and returns NULL.

LocalFree succeeds even if the memory object is locked by a previous call to the LocalLock function. The LocalLock function locks a local memory object and increments the lock count by one. The LocalUnlock function unlocks it and decrements the lock count by one. To get the lock count of a local memory object, use the LocalFlags function. LocalFree will free a locked memory object. A locked memory object has a lock count greater than zero.

Both GlobalFree and LocalFree will free a locked memory object. However, if you run an application under a debug version of Windows NT or Windows 95, both GlobalFree and LocalFree will issue a message that tells you that this is happening. If you are debugging the application, GlobalFree and LocalFree will enter a hard-coded breakpoint just before freeing a locked object. This lets you double-check the intended behavior.

See Also

GlobalFree, LocalAlloc, LocalFlags, LocalLock, LocalReAlloc, LocalUnlock


LocalHandle

The LocalHandle function retrieves the handle associated with the specified pointer to a local memory object.

HLOCAL LocalHandle(

LPCVOID pMem	// address of local memory object
);
Parameters

pMem

Points to the first byte of the local memory object. This pointer is returned by the LocalLock function.

Return Values

If the function succeeds, the return value is the handle of the specified local memory object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

When the LocalAlloc function allocates a local memory object with the LMEM_MOVEABLE flag, it returns the handle of the object. The LocalLock function converts this handle into a pointer to the object’s memory block, and LocalHandle converts the pointer back into a handle.

See Also

LocalAlloc, LocalLock


LocalLock

The LocalLock function locks a local memory object and returns a pointer to the first byte of the object’s memory block. The memory block associated with a locked memory object cannot be moved or discarded. For memory objects allocated with the LMEM_MOVEABLE flag, the function increments the object’s lock count.

LPVOID LocalLock(

HLOCAL hMem	// handle of local memory object
);
Parameters

hMem

Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Return Values

If the function succeeds, the return value is a pointer to the first byte of the memory block.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The internal data structures for each memory object include a lock count that is initially zero. For movable memory objects, LocalLock increments the count by one, and the LocalUnlock function decrements the count by one. For each call that a process makes to LocalLock for an object, it must eventually call LocalUnlock. Locked memory will not be moved or discarded unless the memory object is reallocated by using the LocalReAlloc function. The memory block of a locked memory object remains locked in memory until its lock count is decremented to zero, at which time it can be moved or discarded.

Memory objects allocated with the LMEM_FIXED flag always have a lock count of zero. For these objects, the value of the returned pointer is equal to the value of the specified handle.

If the specified memory block has been discarded or if the memory block has a zero-byte size, this function returns NULL.

Discarded objects always have a lock count of zero.

See Also

LocalAlloc, LocalFlags, LocalReAlloc, LocalUnlock


LocalReAlloc

The LocalReAlloc function changes the size or the attributes of a specified local memory object. The size can increase or decrease.

HLOCAL LocalReAlloc(

HLOCAL hMem,	// handle of local memory object
UINT uBytes,	// new size of block
UINT uFlags	// how to reallocate object
);
Parameters

hMem

Identifies the local memory object to be reallocated. This handle is returned by either the LocalAlloc or LocalReAlloc function.

uBytes

Specifies the new size, in bytes, of the memory block. If this parameter is zero and the uFlags parameter specifies the LMEM_MOVEABLE flag, the function returns a handle to a memory object that is marked as discarded. If uFlags specifies the LMEM_MODIFY flag, this parameter is ignored.

uFlags

Specifies how to reallocate the local memory object. If the LMEM_MODIFY flag is specified, this parameter modifies the attributes of the memory object, and the uBytes parameter is ignored. Otherwise, this parameter controls the reallocation of the memory object.

The LMEM_MODIFY flag can be combined with either or both of the following flags:

Flag	Meaning
LMEM_DISCARDABLE
	Allocates discardable memory if the LMEM_MODIFY flag is also specified. This flag is ignored, unless the object was previously allocated as movable or the LMEM_MOVEABLE flag is also specified.
LMEM_MOVEABLE
	You cannot combine LMEM_MOVEABLE with LMEM_MODIFY to change a fixed memory object into a movable one. The function returns an error if an application attempts this.
If uFlags does not specify LMEM_MODIFY, this parameter can be any combination of the following flags:

Flag	Meaning
LMEM_MOVEABLE
	If uBytes is zero, discards a previously movable and discardable memory block. If the object’s lock count is not zero or the block is not movable and discardable, the function fails.
	If uBytes is nonzero, enables the system to move the reallocated block to a new location without changing the movable or fixed attribute of the memory object. If the object is fixed, the handle returned may be different from the handle specified in the hMem parameter. If the object is movable, the block can be moved without invalidating the handle, even if the object is currently locked by a previous call to the LocalLock function. To get the new address of the memory block, use LocalLock.
LMEM_NOCOMPACT
	Prevents memory from being compacted or discarded to satisfy the allocation request.
LMEM_ZEROINIT
	Causes the additional memory contents to be initialized to zero if the memory object is growing in size.
Return Values

If the function succeeds, the return value is the handle of the reallocated memory object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If LocalReAlloc reallocates a movable object, the return value is the handle of the memory object. To convert the handle to a pointer, use the LocalLock function.

If LocalReAlloc reallocates a fixed object, the value of the handle returned is the address of the first byte of the memory block. To access the memory, a process can simply cast the return value to a pointer.

See Also

LocalAlloc, LocalFree, LocalLock


LocalShrink

The LocalShrink function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. It has no meaning in the 32-bit environment.


LocalSize

The LocalSize function returns the current size, in bytes, of the specified local memory object.

UINT LocalSize(

HLOCAL  hMem	// handle of local memory object
);
Parameters

hMem

Identifies the local memory object. This handle is returned by the LocalAlloc, LocalReAlloc, or LocalHandle function.

Return Values

If the function succeeds, the return value is the size, in bytes, of the specified local memory object. If the specified handle is not valid or if the object has been discarded, the return value is zero. To get extended error information, call GetLastError.

Remarks

The size of a memory block may be larger than the size requested when the memory was allocated.

To verify that the specified object’s memory block has not been discarded, call the LocalFlags function before calling LocalSize.

See Also

LocalAlloc, LocalFlags, LocalHandle, LocalReAlloc


LocalUnlock

The LocalUnlock function decrements the lock count associated with a memory object that was allocated with the LMEM_MOVEABLE flag. This function has no effect on memory objects allocated with the LMEM_FIXED flag.

BOOL LocalUnlock(

HLOCAL hMem	// handle of local memory object
);
Parameters

hMem

Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Return Values

If the memory object is still locked after decrementing the lock count, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. If GetLastError returns NO_ERROR, the memory object is unlocked.

Remarks

The internal data structures for each memory object include a lock count that is initially zero. For movable memory objects, the LocalLock function increments the count by one, and LocalUnlock decrements the count by one. For each call that a process makes to LocalLock for an object, it must eventually call LocalUnlock. Locked memory will not be moved or discarded unless the memory object is reallocated by using the LocalReAlloc function. The memory block of a locked memory object remains locked until its lock count is decremented to zero, at which time it can be moved or discarded.

If the memory object is already unlocked, LocalUnlock returns FALSE and GetLastError reports ERROR_NOT_LOCKED. Memory objects allocated with the LMEM_FIXED flag always have a lock count of zero and cause the ERROR_NOT_LOCKED error.

A process should not rely on the return value to determine the number of times it must subsequently call LocalUnlock for the memory block.

See Also

LocalAlloc, LocalFlags, LocalLock, LocalReAlloc


LockFile

The LockFile function locks a region in an open file. Locking a region prevents other processes from accessing the region.

BOOL LockFile(

HANDLE hFile,	// handle of file to lock
DWORD dwFileOffsetLow,	// low-order word of lock region offset
DWORD dwFileOffsetHigh,	// high-order word of lock region offset
DWORD nNumberOfBytesToLockLow,	// low-order word of length to lock
DWORD nNumberOfBytesToLockHigh	// high-order word of length to lock
);
Parameters

hFile

Identifies the file with a region to be locked. The file handle must have been created with GENERIC_READ or GENERIC_WRITE access to the file (or both).

dwFileOffsetLow

Specifies the low-order word of the starting byte offset in the file where the lock should begin.

dwFileOffsetHigh

Specifies the high-order word of the starting byte offset in the file where the lock should begin.

nNumberOfBytesToLockLow

Specifies the low-order word of the length of the byte range to be locked.

nNumberOfBytesToLockHigh

Specifies the high-order word of the length of the byte range to be locked.

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.

Remarks

Locking a region of a file gives the locking process exclusive access to the specified region. File locks are not inherited by processes created by the locking process.

Locking a region of a file denies all other processes both read and write access to the specified region. Locking a region that goes beyond the current end-of-file position is not an error.

Locks may not overlap an existing locked region of the file.

The UnlockFile function unlocks a file region locked by LockFile.

See Also

CreateFile, UnlockFile


LockFileEx

The LockFileEx function locks a byte range within an open file for shared or exclusive access.

BOOL LockFileEx(

HANDLE hFile,	// handle of file to lock
DWORD dwFlags,	// functional behavior modification flags
DWORD dwReserved,	// reserved, must be set to zero
DWORD nNumberOfBytesToLockLow,	// low-order 32 bits of length to lock
DWORD nNumberOfBytesToLockHigh,	// high-order 32 bits of length to lock
LPOVERLAPPED lpOverlapped	// addr. of structure with lock region start offset
);
Parameters

hFile

Identifies an open handle to a file that is to have a range of bytes locked for shared or exclusive access. The handle must have been created with either GENERIC_READ or GENERIC_WRITE access to the file.

dwFlags

Specifies flags that modify the behavior of this function. This parameter may be one or more of the following values:

Value	Meaning
LOCKFILE_FAIL_IMMEDIATELY	If this value is specified, the function returns immediately if it is unable to acquire the requested lock. Otherwise, it waits.
LOCKFILE_EXCLUSIVE_LOCK	If this value is specified, the function requests an exclusive lock. Otherwise, it requests a shared lock.
dwReserved

Reserved parameter; must be set to zero.

nNumberOfBytesToLockLow

Specifies the low-order 32 bits of the length of the byte range to lock.

nNumberOfBytesToLockHigh

Specifies the high-order 32 bits of the length of the byte range to lock.

lpOverlapped

Points to an OVERLAPPED structure that the function uses with the locking request. This structure, which is required, contains the file offset of the beginning of the lock range.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero or NULL. To get extended error information, call GetLastError.

Remarks

Locking a region of a file is used to acquire shared or exclusive access to the specified region of the file. File locks are not inherited by a new process during process creation.

Locking a portion of a file for exclusive access denies all other processes both read and write access to the specified region of the file. Locking a region that goes beyond the current end-of-file position is not an error.

Locking a portion of a file for shared access denies all processes write access to the specified region of the file, including the process that first locks the region. All processes can read the locked region.

If an exclusive lock is requested for a range of a file that already has a shared or exclusive lock, this call waits until the lock is granted, unless the LOCKFILE_FAIL_IMMEDIATELY flag is specified.

Locks may not overlap an existing locked region of the file.

See Also

CreateFile, LockFile, OVERLAPPED, UnlockFile, UnlockFileEx


LockResource

The LockResource function locks the specified resource in memory.

LPVOID LockResource(

HGLOBAL hResData	// handle to resource to lock
);
Parameters

hResData

Identifies the resource to be locked. The LoadResource function returns this handle.

Return Values

If the loaded resource is locked, the return value is a pointer to the first byte of the resource; otherwise, it is NULL.

Remarks

It is not necessary for Win32-based applications to unlock resources that were locked by the LockResource function.

Trying to lock a resource by using the handle returned by the FindResource or FindResourceEx function will not work. You will get back a value that is incorrect and points to random data.

See Also

FindResource, FindResourceEx, LoadResource


LockSegment

The LockSegment function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. It has no meaning in the 32-bit environment.


LockServiceDatabase

The LockServiceDatabase function locks a specified database.

SC_LOCK LockServiceDatabase(

SC_HANDLE hSCManager	// handle of service control manager database
);
Parameters

hSCManager

Identifies the service control manager database. The OpenSCManager function returns this handle, which must have SC_MANAGER_LOCK access.

Return Values

If the function succeeds, the return value is a lock to the specified service control manager database.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Errors

The following error code may be set by the service control manager. Other error codes may be set by registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED	The specified handle was not opened with SC_MANAGER_LOCK access.
ERROR_INVALID_HANDLE	The specified handle is invalid.
ERROR_SERVICE_DATABASE_LOCKED	The database is locked.
Remarks

The LockServiceDatabase function tries to acquire a lock on the specified database. Only one process at a time can have a lock on a database.

A lock is a protocol used by setup and configuration programs and the service control manager to serialize access to the service tree in the registry. The only time the service control manager acquires a lock is when it is starting a service. Setup and configuration programs are expected to acquire a lock before using the ChangeServiceConfig or SetServiceObjectSecurity function to reconfigure a service. They should also acquire a lock before using the registry functions to reconfigure a service. The lock prevents the service control manager from starting a service while it is being reconfigured.

A call to the StartService function to start a service in a locked database fails. All other service control manager functions are not affected by a lock.

The lock is held until the SC_LOCK handle is specified in a subsequent call to the UnlockServiceDatabase function. If a process that is holding a lock terminates, the service control manager automatically cleans up and releases the lock.

See Also

ChangeServiceConfig, OpenSCManager, QueryServiceLockStatus, SetServiceObjectSecurity, StartService, UnlockServiceDatabase


LockWindowUpdate

The LockWindowUpdate function disables or reenables drawing in the specified window. Only one window can be locked at a time.

BOOL LockWindowUpdate(

HWND hWndLock	// handle of window to lock
);
Parameters

hWndLock

Specifies the window in which drawing will be disabled. If this parameter is NULL, drawing in the locked window is enabled.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero, indicating that an error occurred or another window was already locked.

Remarks

If an application with a locked window (or any locked child windows) calls the GetDC, GetDCEx, or BeginPaint function, the called function returns a device context with a visible region that is empty. This will occur until the application unlocks the window by calling LockWindowUpdate, specifying a value of NULL for hWndLock.

If an application attempts to draw within a locked window, the system records the extent of the attempted operation in a bounding rectangle. When the window is unlocked, the system invalidates the area within this bounding rectangle, forcing an eventual WM_PAINT message to be sent to the previously locked window and its child windows. If no drawing has occurred while the window updates were locked, no area is invalidated.

LockWindowUpdate does not make the given window invisible and does not clear the WS_VISIBLE style bit.

A locked window cannot be moved.

See Also

BeginPaint, GetDC, GetDCEx, WM_PAINT


LogonUser

The LogonUser function attempts to perform a user logon operation. You specify the user with a user name and domain, and authenticate the user with a clear-text password. If the function succeeds, you receive a handle to a token that represents the logged-on user. You can then use this token handle to impersonate the specified user, or in most cases, to create a process running in the context of the specified user.

BOOL LogonUser(

LPTSTR lpszUsername,	// string that specifies the user name
LPTSTR lpszDomain,	// string that specifies the domain or server
LPTSTR lpszPassword,	// string that specifies the password
DWORD dwLogonType,	// specifies the type of logon operation
DWORD dwLogonProvider,	// specifies the logon provider
PHANDLE phToken	// pointer to variable to receive token handle
);
Parameters

lpszUsername

Pointer to a null-terminated string that specifies the user name. This is the name of the user account to log on to.

lpszDomain

Pointer to a null-terminated string that specifies the domain or server to log on to. If this parameter is “.”, LogonUser searches only the local account database for the account specified in lpszUsername. If this parameter is NULL, LogonUser searches the local account database, and then searches trusted domain account databases, until it finds the lpszUsername account or the search is exhausted without finding the account name.

lpszPassword

Pointer to a null-terminated string that specifies the clear-text password for the user account specified by lpszUsername.

dwLogonType

Specifies the type of logon operation to perform. The following logon types are defined:

Value	Meaning
LOGON32_LOGON_BATCH	This logon type is intended for batch servers, where processes may be executing on behalf of a user without their direct intervention; or for higher performance servers that process many clear-text authentication attempts at a time, such as mail or web servers. LogonUser does not cache credentials for this logon type.
LOGON32_LOGON_INTERACTIVE	This logon type is intended for users who will be interactively using the machine, such as a user being logged on by a terminal server, remote shell, or similar process. This logon type has the additional expense of caching logon information for disconnected operation, and is therefore inappropriate for some client/server applications, such as a mail server.
LOGON32_LOGON_SERVICE	Indicates a service-type logon. The account provided must have the service privilege enabled.
LOGON32_LOGON_NETWORK	This logon type is intended for high performance servers to authenticate clear text passwords. LogonUser does not cache credentials for this logon type. This is the fastest logon path, but there are two limitations.  First, the function returns an impersonation token, not a primary token. You cannot use this token directly in the CreateProcessAsUser function. However, you can call the DuplicateTokenEx function to convert the token to a primary token, and then use it in CreateProcessAsUser.  Second, if you convert the token to a primary token and use it in CreateProcessAsUser to start a process, the new process will not be able to access other network resources, such as remote servers or printers, through the redirector.
dwLogonProvider

Specifies the logon provider. The following logon providers are defined:

Value	Meaning
LOGON32_PROVIDER_DEFAULT	Use the standard logon provider. This is the recommended value for dwLogonProvider. It gives an application the maximum upward compatibility with future releases of Windows NT.
phToken

Pointer to a HANDLE variable that receives a handle to a token that represents the specified user.

You can use the returned handle in calls to the ImpersonateLoggedOnUser function.

In most cases, the returned handle is a primary token that you can use in calls to the CreateProcessAsUser function. However, if you specify the LOGON32_LOGON_NETWORK flag, LogonUser returns an impersonation token that you cannot use in CreateProcessAsUser unless you call DuplicateTokenEx to convert it to a primary token.

When you no longer need this handle, close it by calling the CloseHandle 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.

Remarks

The process that calls LogonUser must have the SE_TCB_NAME privilege. The privilege does not need to be enabled. The LogonUser function enables the privilege as necessary. The function fails if the calling process does not have the SE_TCB_NAME privilege, and GetLastError returns the error code ERROR_PRIVILEGE_NOT_HELD. For more information about privileges, see Privileges.

A user is considered logged on as long as at least one token exists. If you call CreateProcessAsUser and then close the token, the system considers the user as still logged on until the process (and all child processes) have ended.

If the LogonUser call is successful, the system notifies network providers that the logon occurred by calling the provider’s NPLogonNotify entry-point.

See Also

CreateProcessAsUser, ImpersonateLoggedOnUser


LookupAccountName

The LookupAccountName function accepts the name of a system and an account as input. It retrieves a security identifier (SID) for the account and the name of the domain on which the account was found.

BOOL LookupAccountName(

LPCTSTR lpSystemName,	// address of string for system name
LPCTSTR lpAccountName,	// address of string for account name
PSID Sid,	// address of security identifier
LPDWORD cbSid,	// address of size of security identifier
LPTSTR ReferencedDomainName,	// address of string for referenced domain
LPDWORD cbReferencedDomainName,	// address of size of domain string
PSID_NAME_USE peUse	// address of SID-type indicator
);
Parameters

lpSystemName

Points to a null-terminated string specifying the system. This string can be the name of a remote computer. If this string is NULL, the account name is looked up on the local system.

lpAccountName

Points to a null-terminated string specifying the account name.

Sid

Points to a buffer receiving the SID structure that corresponds to the account name pointed to by the lpAccountName parameter.

cbSid

Pointer to a DWORD variable. On input, this value specifies the size, in bytes, of the Sid buffer. If the function fails because the buffer is too small, this variable receives the required buffer size.

ReferencedDomainName

Points to a buffer receiving the name of the domain where the account name is found.

cbReferencedDomainName

Pointer to a DWORD variable. On input, this value specifies the size, in bytes (ANSI version) or characters (Unicode version), of the ReferencedDomainName buffer. If the function fails because the buffer is too small, this variable receives the required buffer size, including the terminating null character.

peUse

Points to a SID_NAME_USE enumerated type indicating the type of the account when the function returns.

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.

Remarks

The LookupAccountName function attempts to find a security identifier for the specified name by first checking a list of well-known SIDs. If the name does not correspond to a well-known SID, the function checks built-in and administratively defined local accounts. Next, the function checks the primary domain. If the name is not found there, trusted domains are checked.

See Also

EqualPrefixSid, GetUserName, LookupAccountSid


LookupAccountSid

The LookupAccountSid function accepts a security identifier (SID) as input. It retrieves the name of the account for this SID and the name of the first domain on which this SID is found.

BOOL LookupAccountSid(

LPCTSTR lpSystemName,	// address of string for system name
PSID Sid,	// address of security identifier
LPTSTR Name,	// address of string for account name
LPDWORD cbName,	// address of size account string
LPTSTR ReferencedDomainName,	// address of string for referenced domain
LPDWORD cbReferencedDomainName,	// address of size domain string
PSID_NAME_USE peUse	// address of structure for SID type
);
Parameters

lpSystemName

Points to a null-terminated string specifying the system. This string can be the name of a remote computer. If this string is NULL, the SID is looked up on the local system.

Sid

Points to a SID structure for which the account name is looked up.

Name

Points to a buffer receiving a null-terminated string representing the account name corresponding to the Sid parameter.

cbName

Pointer to a DWORD variable. On input, this value specifies the size, in bytes (ANSI version) or characters (Unicode version), of the Name buffer. If the function fails because the buffer is too small, this variable receives the required buffer size, including the terminating null character.

ReferencedDomainName

Points to a buffer that will receive a null-terminated string giving the name of the domain where the account name was found.

For Windows NT systems, the domain name returned for most accounts in the local computer’s security database is the computer’s name as of the last start of the system. Backslashes are excluded. If the computer’s name changes, the old name continues to be returned as the domain name until the system is restarted.

For Windows NT Server systems, the domain name returned for most accounts in the local computer’s security database is the name of the domain for which the Windows NT Server is a domain controller.

Some accounts are predefined by the system. The domain name returned for these accounts is BUILTIN.

cbReferencedDomainName

Pointer to a DWORD variable. On input, this value specifies the size, in bytes (ANSI version) or characters (Unicode version), of the ReferencedDomainName buffer. If the function fails because the buffer is too small, this variable receives the required buffer size, including the terminating null character.

peUse

Points to an SID_NAME_USE enumerated type indicating the type of the account when the function returns.

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.

Remarks

The LookupAccountSid function attempts to find a name for the specified security identifier by first checking a list of well-known SIDs. If the supplied SID does not correspond to a well-known SID, the function checks built-in and administratively defined local accounts. Next, the function checks the primary domain. Security identifiers not recognized by the primary domain are checked against the trusted domains corresponding to their SID prefixes.

See Also

EqualPrefixSid, LookupAccountName


LookupIconIdFromDirectory

The LookupIconIdFromDirectory function searches through icon or cursor data for the icon or cursor that best fits the current display device.

int LookupIconIdFromDirectory(

PBYTE presbits,	// address of resource data
BOOL fIcon	// look for icon or cursor
);
Parameters

presbits

Points to the icon or cursor directory data. Because this function does not validate the resource data, it causes a general protection (GP) fault or returns an undefined value if presbits is not pointing to valid resource data.

fIcon

Specifies whether an icon or a cursor is sought. If this parameter is TRUE, the function is searching for an icon; if the parameter is FALSE, the function is searching for a cursor.

Return Values

If the function succeeds, the return value is an integer resource identifier for the icon or cursor that best fits the current display device.

Remarks

A resource file of type RT_GROUP_ICON (RT_GROUP_CURSOR indicates cursors) contains icon (or cursor) data in several device-dependent and device-independent formats. LookupIconIdFromDirectory searches the resource file for the icon (or cursor) that best fits the current display device and returns its integer identifier. The FindResource and FindResourceEx functions use the MAKEINTRESOURCE macro with this identifier to locate the resource in the module.

The icon directory is loaded from a resource file with resource type RT_GROUP_ICON (or RT_GROUP_CURSOR for cursors), and an integer resource name for the specific icon to be loaded. LookupIconIdFromDirectory returns an integer identifier that is the resource name of the icon that best fits the current display device.

The LoadIcon, LoadCursor, and LoadImage (in Windows 95) functions use this function to search the specified resource data for the icon or cursor that best fits the current display device.

See Also

CreateIconFromResource, CreateIconIndirect, FindResource, FindResourceEx, GetIconInfo, LoadCursor, LoadIcon, LoadImage, LookupIconIdFromDirectoryEx, MAKEINTRESOURCE


LookupIconIdFromDirectoryEx [Now Supported on Windows NT]
LookupIconIdFromDirectoryEx

[Now Supported on Windows NT]

The LookupIconIdFromDirectoryEx function searches through icon or cursor data for the icon or cursor that best fits the current display device.

int LookupIconIdFromDirectoryEx(

PBYTE presbits,	// address of resource data
BOOL fIcon,	// icon or cursor flag
int cxDesired,	// desired width of icon or cursor
int cyDesired,	// desired height of icon or cursor
UINT Flags	// resource flags
);
Parameters

presbits

Points to the icon or cursor directory data. Because this function does not validate the resource data, it causes a general protection (GP) fault or returns an undefined value if presbits is not pointing to valid resource data.

fIcon

Specifies whether an icon or a cursor is sought. If this parameter is TRUE, the function is searching for an icon; if the parameter is FALSE, the function is searching for a cursor.

cxDesired

Specifies the desired width, in pixels, of the icon. If this parameter is zero, the function uses the SM_CXICON or SM_CXCURSOR system metric value.

cyDesired

Specifies the desired height, in pixels, of the icon. If this parameter is zero, the function uses the SM_CYICON or SM_CYCURSOR system metric value.

Flags

Specifies a combination of the following values:

Value	Meaning
LR_DEFAULTCOLOR	Uses the default color format.
LR_MONOCHROME	Creates a monochrome icon or cursor.
Return Values

If the function succeeds, the return value is an integer resource identifier for the icon or cursor that best fits the current display device.

Remarks

A resource file of type RT_GROUP_ICON (RT_GROUP_CURSOR indicates cursors) contains icon (or cursor) data in several device-dependent and device-independent formats. LookupIconIdFromDirectoryEx searches the resource file for the icon (or cursor) that best fits the current display device and returns its integer identifier. The FindResource and FindResourceEx functions use the MAKEINTRESOURCE macro with this identifier to locate the resource in the module.

The icon directory is loaded from a resource file with resource type RT_GROUP_ICON (or RT_GROUP_CURSOR for cursors), and an integer resource name for the specific icon to be loaded. LookupIconIdFromDirectoryEx returns an integer identifier that is the resource name of the icon that best fits the current display device.

The LoadIcon, LoadImage, and LoadCursor functions use this function to search the specified resource data for the icon or cursor that best fits the current display device.

See Also

CreateIconFromResourceEx, CreateIconIndirect, FindResource, FindResourceEx, GetIconInfo, LoadCursor, LoadIcon, LoadImage, LookupIconIdFromDirectory, MAKEINTRESOURCE


LookupPrivilegeDisplayName

The LookupPrivilegeDisplayName function retrieves a displayable name representing a specified privilege.

BOOL LookupPrivilegeDisplayName(

LPCTSTR lpSystemName,	// pointer to string specifying the system
LPCTSTR lpName,	// pointer to string specifying the privilege
LPTSTR lpDisplayName,	// pointer to string receiving the displayable name
LPDWORD cbDisplayName,	// pointer to size of string for displayable name
LPDWORD lpLanguageId	// pointer to language identifier
);
Parameters

lpSystemName

Points to a null-terminated string specifying the name of the system on which the displayable privilege name is looked up. If a null string is specified, the function attempts to find the displayable name on the local system.

lpName

Points to a null-terminated string that specifies the name of the privilege, as defined in the WINNT.H header file. For example, this parameter could specify the constant SE_REMOTE_SHUTDOWN_NAME, or its corresponding string, “SeRemoteShutdownPrivilege”.

lpDisplayName

Points to a buffer receiving a null-terminated string giving the privilege’s displayable name. For example, if the lpName parameter is SE_REMOTE_SHUTDOWN_NAME, the displayable name is “Force shutdown from a remote system.”

cbDisplayName

Points to a variable specifying the size, in characters, of the lpDisplayName buffer. When the function returns, this parameter contains the length of the displayable privilege name, not including the terminating null character. If the buffer pointed to by the lpDisplayName parameter is too small, this variable contains the required size when the function returns.

lpLanguageId

Points to a variable receiving the language identifier for the returned displayable name.

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.

Remarks

The LookupPrivilegeDisplayName function retrieves display names only for the privileges specified in the Defined Privileges section of WINNT.H.

See Also

LookupPrivilegeName, LookupPrivilegeValue


LookupPrivilegeName

The LookupPrivilegeName function retrieves the name corresponding to the privilege represented on a specific system by a specified locally unique identifier (LUID).

BOOL LookupPrivilegeName(

LPCTSTR lpSystemName,	// address of string specifying the system
PLUID lpLuid,	// address of locally unique identifier
LPTSTR lpName,	// address of string specifying the privilege
LPDWORD cbName	// address of size of string for displayable name
);
Parameters

lpSystemName

Points to a null-terminated string specifying the name of the system on which the privilege name is looked up. If a null string is specified, the function attempts to find the privilege name on the local system.

lpLuid

Points to the locally unique identifier by which the privilege is known on the target system.

lpName

Points to a buffer that receives a null-terminated string that represents the privilege’s name. For example, this string could be “SeSecurityPrivilege”.

cbName

Points to a variable specifying the size, in characters, of the lpName buffer. When the function returns, this parameter contains the length of the privilege name, not including the terminating null character. If the buffer pointed to by the lpName parameter is too small, this variable contains the required size when the function returns.

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.

Remarks

For this release of Windows NT, only the privileges specified in the Defined Privileges section of WINNT.H are supported by this function.

See Also

LookupPrivilegeDisplayName, LookupPrivilegeValue


LookupPrivilegeValue

The LookupPrivilegeValue function retrieves the locally unique identifier (LUID) used on a specified system to locally represent the specified privilege name.

BOOL LookupPrivilegeValue(

LPCTSTR lpSystemName,	// address of string specifying the system
LPCTSTR lpName,	// address of string specifying the privilege
PLUID lpLuid	// address of locally unique identifier
);
Parameters

lpSystemName

Points to a null-terminated string specifying the name of the system on which the privilege name is looked up. If a null string is specified, the function attempts to find the privilege name on the local system.

lpName

Points to a null-terminated string that specifies the name of the privilege, as defined in the WINNT.H header file. For example, this parameter could specify the constant SE_SECURITY_NAME, or its corresponding string, “SeSecurityPrivilege”.

lpLuid

Points to a variable that receives the locally unique identifier by which the privilege is known on the system specified by the lpSystemName parameter.

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.

Remarks

For this release of Windows NT, only the privileges specified in the Defined Privileges section of WINNT.H are supported by this function.

See Also

LookupPrivilegeDisplayName, LookupPrivilegeName


LookupSecurityDescriptorParts [New - Windows NT]
LookupSecurityDescriptorParts

[New - Windows NT]

The LookupSecurityDescriptorParts function retrieves security information from a self-relative security descriptor.

DWORD LookupSecurityDescriptorParts(

PTRUSTEE *pOwner,	// receives the owner SID from the security descriptor
PTRUSTEE *pGroup,	// receives the group SID from the security descriptor
PULONG cCountOfAccessEntries,	// receives number of access-control entries
PEXPLICIT_ACCESS *pListOfAccessEntries,	// receives an array of DACL access-control entries
PULONG cCountOfAuditEntries,	// receives number of audit-control entries
PEXPLICIT_ACCESS *pListOfAuditEntries,	// receives an array of SACL audit-control entries
PSECURITY_DESCRIPTOR pSD	// pointer that receives the new security descriptor
);
Parameters

pOwner

Pointer to a variable that receives a pointer to a TRUSTEE structure. The function looks up the name associated with the owner SID in the pSD security descriptor, and returns a pointer to the name in the ptstrName member of the TRUSTEE structure. The function sets the TrusteeForm member to TRUSTEE_IS_NAME.

This parameter can be NULL if you are not interested in the name of the owner.

pGroup

Pointer to a variable that receives a pointer to a TRUSTEE structure. The function looks up the name associated with the primary group SID of the security descriptor, and returns a pointer to the name in the ptstrName member of the TRUSTEE structure. The function sets the TrusteeForm member to TRUSTEE_IS_NAME.

This parameter can be NULL if you are not interested in the name of the group.

cCountOfAccessEntries

Pointer to a ULONG that receives the number of EXPLICIT_ACCESS structures returned in the pListOfAccessEntries array. This parameter can be NULL only if the pListOfAccessEntries parameter is also NULL.

pListOfAccessEntries

Pointer to a variable that receives a pointer to an array of EXPLICIT_ACCESS structures that describe the ACEs in the DACL of the security descriptor. The TRUSTEE structure in these EXPLICIT_ACCESS structures use the TRUSTEE_IS_NAME form. For a description of how an array of EXPLICIT_ACCESS structures describes the ACEs in an ACL, see the GetExplicitEntriesFromAcl function. If this parameter is NULL, the cCountOfAccessEntries parameter must also be NULL.

cCountOfAuditEntries

Pointer to a ULONG that receives the number of EXPLICIT_ACCESS structures returned in the pListOfAuditEntries array. This parameter can be NULL only if the pListOfAuditEntries parameter is also NULL.

pListOfAuditEntries

Pointer to a variable that receives a pointer to an array of EXPLICIT_ACCESS structures that describe the ACEs in the SACL of the security descriptor. The TRUSTEE structure in these EXPLICIT_ACCESS structures uses the TRUSTEE_IS_NAME form. If this parameter is NULL, the cCountOfAuditEntries parameter must also be NULL.

pSD

Pointer to an existing self-relative security descriptor from which the function retrieves security information. A self-relative security descriptor stores a SECURITY_DESCRIPTOR structure and associated security information in a contiguous block of memory. This differs from an absolute security descriptor, which contains pointers to the associated security information.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

The LookupSecurityDescriptorParts function retrieves the names of the owner and primary group of the security descriptor. It also returns descriptions of the access-control entries in the DACL and audit-control entries in the SACL of the security descriptor.

The parameters other than pSD can be NULL if you are not interested in the information. If you do not want information about the DACL, both pListOfAccessEntries and cCountOfAccessEntries must be NULL. If you do not want information about the SACL, both pListOfAuditEntries and cCountOfAuditEntries must be NULL. Similarly, if you do want DACL or SACL information, both of the corresponding parameters must be non-NULL.

You must call the LocalFree function to free any buffers returned by the pOwner, pGroup, pListOfAccessEntries, or pListOfAuditEntries parameters.

The LookupSecurityDescriptorParts function is intended for trusted servers that implement or expose security on their own objects. The function works with a self-relative security descriptor suitable for serializing into a stream and storing to disk, as a trusted server might require.

See Also

ACE, ACL, EXPLICIT_ACCESS, LocalFree, SECURITY_DESCRIPTOR, GetExplicitEntriesFromAcl, SID, TRUSTEE


LPtoDP

The LPtoDP function converts logical coordinates into device coordinates. The conversion depends on the mapping mode of the device context, the settings of the origins and extents for the window and viewport, and the world transformation.

BOOL LPtoDP(

HDC hdc,	// handle of device context
LPPOINT lpPoints,	// array of points
int nCount	// count of points
);
Parameters

hdc

Identifies the DC.

lpPoints

Points to an array of POINT structures. The x-coordinates and y-coordinates contained in each of the POINT structures will be transformed.

nCount

Specifies the number of points in the array.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

This function fails if the logical coordinates exceed 32 bits, or if the converted device coordinates exceed 27 bits. In the case of such an overflow, the results for all the points are undefined.

See Also

DPtoLP, POINT


LSEnumProviders

Notice:This is preliminary documentation for technology that will be supported in future releases of Microsoft Windows.

The LSEnumProviders function returns a unique string for each installed license system service provider.

LS_STATUS_CODE LS_API_ENTRY LSEnumProviders(

LS_ULONG Index,	// index of the service provider
LS_STR *Buffer	// pointer to string identifying the service provider
);
Parameters

Index

[in] Specifies the index of the service provider. The first provider has an index of zero, the second has an index of one, and so forth. This index should be incremented by the caller for each successive call to LSEnumProviders until it returns the LS_BAD_INDEX status code.

Buffer

[out] Points to a buffer in which the unique null-terminated string identifying the license system service provider is to be placed. The buffer pointed to by the Buffer parameter must be at least 255 bytes long. The value of LS_ANY indicates that the current index is not in use, but it is not the last index to obtain.

Return Values

If the function succeeds, the return value is LS_SUCCESS.

If the function fails, the return value is a status code. For extended error information, call LSGetMessage to return the status text corresponding to the status code. The LSGetMessage function may return one of the following status codes:

Value	Meaning
LS_BAD_INDEX	An invalid index was specified in a call to the LSEnumProviders or the LSQuery function.
LS_BUFFER_TOO_SMALL	The buffer that the Buffer parameter points to is too small to accommodate the text string to be returned; or the challenge data structure is too small to accommodate the challenge response.
Remarks

The LSEnumProviders function returns a unique string for each installed provider. The unique null-terminated string typically identifies the vendor, product, and version of the license system. This value is the same as the one returned by an appropriate call to the LSQuery function. In a networked environment, it returns the version of the client, not the server.

An application can enumerate the installed license system service providers by calling LSEnumProviders successively. The value specified in the Index parameter is passed in and the calling application should increment it in each call until it returns the LS_BAD_INDEX status code. This code indicates that the value of the Index parameter is higher than the number of providers currently installed.

See Also

LSGetMessage, LSQuery


LSFreeHandle

Notice:This is preliminary documentation for technology that will be supported in future releases of Microsoft Windows.

The LSFreeHandle function frees the licensing handle context.

LS_VOID LS_API_ENTRY LSFreeHandle(

LS_HANDLE  LicenseHandle	// handle to the license context
);
Parameter

LicenseHandle

[in] Specifies the handle to a license context that is no longer valid. This parameter must be a handle created with the LSRequest function.

Return Values

None.

Remarks

Call the LSFreeHandle function after calling the LSRelease function, or after LSRequest returns an error.

See Also

LSRelease, LSRequest


LSGetMessage

Notice:This is preliminary documentation for technology that will be supported in future releases of Microsoft Windows.

The LSGetMessage function returns the message string associated with a license service function status code.

LS_STATUS_CODE LS_API_ENTRY LSGetMessage(

LS_HANDLE LicenseHandle,	// handle to the license context
LS_STATUS_CODE Value,	// any status code returned by a license service function
LS_STR *Buffer,	// pointer to buffer returning error message string
LS_ULONG BufferSize	// maximum size of buffer string
);
Parameters

LicenseHandle

[in] Specifies the handle to the license context. This parameter must be a handle created with the LSRequest function.

Value

[in] Specifies any status code returned by a license service function.

Buffer

[out] Points to a buffer in which a localized error message string will be returned.

BufferSize

[in] Specifies, in bytes, the maximum size of the string returned in the Buffer parameter.

Return Values

If the function succeeds, the return value is LS_SUCCESS.

If the function fails, the return value is a status code. For extended error information, call LSGetMessage to return the status text corresponding to the status code. The LSGetMessage function may return one of the following status codes:

Value	Meaning
LS_BAD_HANDLE	The handle used on the call does not describe a valid licensing system context.
LS_RESOURCES_UNAVAILABLE	The request cannot be completed because of insufficient resources, such as memory.
LS_TEXT_UNAVAILABLE	A warning occurred while looking up an error message string with the LSGetMessage function.
LS_UNKNOWN_STATUS	An unrecognized status code was passed to the LSGetMessage function.
LS_BUFFER_TOO_SMALL	The buffer that the Buffer parameter points to is too small to accommodate the text string to be returned; or the challenge data structure is too small to accommodate the challenge response.
LS_BAD_ARG	One or more of the arguments is incorrect.
Remarks

The LSGetMessage function returns a string describing a specific error, and possibly a suggested action to be taken in response to it. If the value specified in the Value parameter is the constant LS_USE_LAST, then the last error associated with the supplied licensing handle, plus its associated data, is returned. Otherwise, the function uses the supplied error code.

See Also

LSRequest


LSQuery

Notice:This is preliminary documentation for technology that will be supported in future releases of Microsoft Windows.

The LSQuery function returns information about the service provider or the license system context associated with the specified handle obtained by a call to the LSRequest function.

LS_STATUS_CODE LS_API_ENTRY LSQuery(

LS_HANDLE LicenseHandle,	// handle to the license context
LS_ULONG Information,	// index that identifies the license information
LS_VOID *InfoBuffer,	// pointer to buffer for returning license information
LS_ULONG BufferSize,	// maximum size of buffer
LS_ULONG *ActualBufferSize	// pointer to actual count of characters returned in buffer
);
Parameters

LicenseHandle

[in] Specifies the handle to the license context. This parameter must be a handle created with the LSRequest function.

Information

[in] Specifies the index that identifies the information to be returned.

InfoBuffer

[out] Points to a buffer in which the resulting information is to be placed.

BufferSize

[in] Specifies, in bytes, the maximum size of the buffer pointed to by the InfoBuffer parameter.

ActualBufferSize

[out] Points to an LS_ULONG value that specifies the actual number of characters returned in the buffer, not including the trailing NULL byte.

Return Values

If the function succeeds, the return value is LS_SUCCESS.

If the function fails, the return value is a status code. For extended error information, call LSGetMessage to return the status text corresponding to the status code. The LSGetMessage function may return one of the following status codes:

Value	Meaning
LS_BAD_HANDLE	The handle used on the call does not describe a valid licensing system context.
LS_RESOURCES_UNAVAILABLE	The request cannot be completed because of insufficient resources, such as memory.
LS_BAD_INDEX	An invalid index was specified in a call to the LSEnumProviders or the LSQuery function.
LS_BUFFER_TOO_SMALL	The buffer that the Buffer parameter points to is too small to accommodate the text string to be returned; or the challenge data structure is too small to accommodate the challenge response.
LS_BAD_ARG	One or more of the arguments is incorrect.
Remarks

The LSQuery function is used to obtain information about the license obtained from a call to the LSRequest function. For example, an application can determine the license type (demo, concurrent, personal, and so forth) and time restrictions.

The buffer should be large enough to accommodate the expected data. If the buffer is too small, then the status code LS_BUFFER_TOO_SMALL is returned and only the number of bytes specified in the parameter BufferSize is returned.

See Also

LSEnumProviders, LSGetMessage, LSRequest


LSRelease

Notice:This is preliminary documentation for technology that will be supported in future releases of Microsoft Windows.

The LSRelease function requests that the license system release the licensing resources associated with the license context identified by the LicenseHandle parameter.

LS_STATUS_CODE LS_API_ENTRY LSRelease(

LS_HANDLE LicenseHandle,	// handle to the license context
LS_ULONG TotUnitsConsumed,	// units consumed in this handle context
LS_STR *LogComment	// pointer to optional comment associated with the request
);
Parameters

LicenseHandle

[in] Specifies the handle to the license context. This parameter must be a handle created with the LSRequest function.

TotUnitsConsumed

[in] Specifies the total number of units consumed in this handle context since the initial call to the LSRequest function. You can specify this license policy attribute within the application. A value of LS_DEFAULT_UNITS indicates that the license system should determine the appropriate value using its own license policy mechanisms.

LogComment

[in] Points to an optional string indicating a comment that will be associated with the request. The license system can log the comment if logging is supported and enabled. If an error is returned, the license system can log both the error and the comment, but this is not guaranteed. If you do not specify a string, the value must be LS_NULL.

Return Values

If the function succeeds, the return value is LS_SUCCESS.

If the function fails, the return value is a status code. For extended error information, call LSGetMessage to return the status text corresponding to the status code. The LSGetMessage function may return one of the following status codes:

Value	Meaning
LS_BAD_HANDLE	The handle used on the call does not describe a valid licensing system context.
LS_INSUFFICIENT_UNITS	The licensing system cannot locate enough available licensing resources to complete the request.
LS_NETWORK_UNAVAILABLE	The network is unavailable.
LS_BAD_ARG	One or more of the arguments is incorrect.
Remarks

Use the LSRelease function to release licensing resources associated with the license context identified by the LicenseHandle parameter. If a policy that consumes licenses is in effect, and if you choose to implement such a license policy in the application, then you can pass the license units to be consumed in the TotUnitsConsumed parameter.

The LSRelease function does not free the license handle context. See the reference topic for LSFreeHandle.

See Also

LSFreeHandle, LSGetMessage, LSRequest


LSRequest

Notice:This is preliminary documentation for technology that will be supported in future releases of Microsoft Windows.

The LSRequest function asks that the license system grant the licensing resources so the calling application can execute.

LS_STATUS_CODE LS_API_ENTRY LSRequest(

LS_STR *LicenseSystem,	// pointer to string identifying the license system
LS_STR *PublisherName,	// pointer to publisher of product requesting licensing resources
LS_STR *ProductName,	// pointer to name of product requesting licensing resources
LS_STR *Version,	// pointer to version number of product requesting licensing resources
LS_ULONG TotUnitsReserved,	// units required to run the application
LS_STR *LogComment,	// pointer to optional comment associated with the request
LS_CHALLENGE *Challenge,	// pointer to a challenge structure
LS_ULONG *TotUnitsGranted,	// pointer to total number of units granted
LS_HANDLE *LicenseHandle	// pointer to handle to the license context
);
Parameters

LicenseSystem

[in] Points to a string that uniquely identifies the particular license system. You can obtain this string by using the LSEnumProviders function. If the constant LS_ANY is specified, all license system providers will be searched for a license match.

PublisherName

[in] Points to a string containing the name of the publisher of the software product requesting licensing resources. The first 32 characters of the string must be unique. It is recommended that a company name and trademark be used. This string cannot be null, nor can it be LS_ANY.

ProductName

[in] Points to a string containing the name of the software product requesting licensing resources. The first 32 characters of the string must be unique within the PublisherName domain. This string cannot be null, nor can it be LS_ANY.

Version

[in] Points to a string containing the version number of the product. The first 12 characters of the string must be unique within the PublisherName domain. This string cannot be null, nor can it be LS_ANY.

TotUnitsReserved

[in] Specifies the number of units required to run the application. The software publisher may choose to specify this policy attribute within the application. The recommended value of LS_DEFAULT_UNITS allows the license system to determine the proper value using information provided by the license system or the license itself. The license system verifies that the requested number of units exist and it may reserve those units, but no units are actually consumed at this time. The number of units available is returned in the TotUnitsGranted parameter.

LogComment

[in] Points to an optional string indicating a comment that will be associated with the request. The license system can log the comment if logging is supported and enabled. If an error is returned, the license system can log both the error and the comment, but this is not guaranteed. If you do not specify a string, the value must be LS_NULL.

Challenge

[in/out] Points to a challenge structure. The challenge response will also be returned in this structure.

TotUnitsGranted

[out] Points to an LS_ULONG value in which the total number of units granted is returned. The following table describes the TotUnitsGranted return value, given the TotUnitsReserved parameter input value, and the status code returned:

	TotUnitsReserved
Status code returned	LS_DEFAULT_UNITS	Other (specific count)
LS_SUCCESS	(A)	(C)
LS_INSUFFICIENT_UNITS	(B)	(D)
Other errors	(E)	(E)
TotUnitsGranted return values:

(A) The default number of units commensurate with the license granted.

(B) The maximum number of units available to the requesting software. This can be less than the normal default.

(C) The number of units used to grant the request. This value can be greater than or equal to the actual units requested. For example, the license policy may allow only allow increments of five units; therefore, a request of seven units would result in a grant of 10 units.

(D) The maximum number of units available to the requesting software. This can be more or less than the units requested.

(E) Zero is returned.

LicenseHandle

[out] Points to an LS_HANDLE in which a handle to the license context is returned.

Return Values

If the function succeeds, the return value is LS_SUCCESS.

If the function fails, the return value is a status code. For extended error information, call LSGetMessage to return the status text corresponding to the status code. The LSGetMessage function may return one of the following status codes:

Value	Meaning
LS_INSUFFICIENT_UNITS	The licensing system cannot locate enough available licensing resources to complete the request.
LS_SYSTEM_UNAVAILABLE	A licensing system cannot be found to perform the function invoked.
LS_AUTHORIZATION_UNAVAILABLE	The licensing system has no licensing resources to complete the request.
LS_LICENSE_UNAVAILABLE	The licensing system has licensing resources that could satisfy the request, but they are not available at the time of the request.
LS_RESOURCES_UNAVAILABLE	The request cannot be completed because of insufficient resources, such as memory.
LS_NETWORK_UNAVAILABLE	The network is unavailable.
LS_BAD_ARG	One or more of the arguments is incorrect.
Remarks

Use the LSRequest function to request licensing resources to authorize the identified product to execute. If a valid license is found, the challenge response is computed and LS_SUCCESS is returned. At minimum, the PublisherName, ProductName, and Version strings are used to identify a matching license or licenses. Note that an underlying license system service provider may ascertain additional information for the license request — for example, the current user name, computer name, and so forth.

If all service providers cannot satisfy a call to the LSRequest function, then LSRequest returns the handle associated with the last service provider response. Therefore, regardless of whether valid licensing resources are granted, LSRequest always returns a valid license handle. This handle must always be released with the LSFreeHandle function when the application has finished running. If licensing resources are granted, the application must also call LSRelease to free the licensing resources, before calling LSFreeHandle.

A challenge response is not returned unless the license request completes successfully — that is, unless it returns a status code of LS_SUCCESS.

If the number of units requested is greater than the number of units available, the license request is not granted. Upon successful completion, the value returned in the TotUnitsReserved parameter indicates the number of units granted. This is greater than or equal to the number of units requested unless LS_DEFAULT_UNITS was specified. In the case of failure, the value returned in the TotUnitsGranted parameter is zero.

See Also

LS_CHALLENGE, LSEnumProviders, LSFreeHandle, LSGetMessage, LSRelease


LSUpdate

Notice:This is preliminary documentation for technology that will be supported in future releases of Microsoft Windows.

The LSUpdate function updates the synchronization between the licensed application software and the license system.

LS_STATUS_CODE LS_API_ENTRY LSUpdate(

LS_HANDLE LicenseHandle,	// handle to the license context
LS_ULONG TotUnitsConsumed,	// units consumed in this handle context
LS_ULONG TotUnitsReserved,	// units required to run the application
LS_STR *LogComment,	// pointer to optional comment associated with the request
LS_CHALLENGE *Challenge,	// pointer to a challenge structure
LS_ULONG *TotUnitsGranted	// pointer to total number of units granted
);
Parameters

LicenseHandle

[in] Specifies the handle to the license context. This parameter must be a handle created with the LSRequest function.

TotUnitsConsumed

[in] Specifies the total number of units consumed in this handle context since the initial call to the LSRequest function. You can specify this license policy attribute within the application. A value of LS_DEFAULT_UNITS indicates that the license system should determine the appropriate value using its own license policy mechanisms. If an error is returned, no units are consumed.

If the TotUnitsConsumed exceeds the number of units reserved, the error LS_INSUFFICIENT_UNITS is returned and the remaining units are consumed.

TotUnitsReserved

[in] Specifies the total number of units to be reserved. If no additional units are required since the initial call to the LSRequest function or the last call to the LSUpdate function, then this parameter should be the current total returned in the TotUnitsGranted parameter. The total reserved includes the units consumed. That is, if an application requests 100 units, and then consumes 20 units, there are still 100 units reserved but only 80 available for consumption.

If additional units are required, the application must calculate a new total for TotUnitsReserved. You can specify the constant LS_DEFAULT_UNITS, but this does not allocate any additional units.

The license system verifies that the requested number of units exist, and it may reserve those units, but these units are not consumed at this time. This value may be smaller than the original number requested by LSRequest to indicate that fewer units are needed than originally anticipated.

LogComment

[in] Points to an optional string indicating a comment that the license system will associate with the request. The license system can log the comment if logging is supported and enabled. If an error is returned, the license system can log both the error and the comment, but this is not guaranteed. If you do not specify a string, the value must be LS_NULL.

Challenge

[in/out] Points to a challenge structure. The challenge response will also be returned in this structure.

TotUnitsGranted

[out] Points to an LS_ULONG value that returns the total number of units granted since the initial license request. The following table describes the TotUnitsGranted return value, given the TotUnitsReserved parameter input value, and the status code returned:

	TotUnitsReserved
Status code returned	LS_DEFAULT_UNITS	Other (specific count)
LS_SUCCESS	(A)	(C)
LS_INSUFFICIENT_UNITS	(B)	(D)
Other errors	(E)	(E)
TotUnitsGranted return values:

(A) The default number of units commensurate with the license granted.

(B) The maximum number of units available to the requesting software. This can be less than the normal default.

(C) The number of units used to grant the request. This value can differ from the actual units requested. For example, the license policy may only allow only increments of five units; therefore, a request of seven units would result in a grant of 10 units.

(D) The maximum number of units available to the requesting software. This can be more or less than the units requested.

(E) Zero is returned.

Return Values

If the function succeeds, the return value is LS_SUCCESS.

If the function fails, the return value is a status code. For extended error information, call LSGetMessage to return the status text corresponding to the status code. The LSGetMessage function may return one of the following status codes:

Value	Meaning
LS_BAD_HANDLE	The handle used on the call does not describe a valid licensing system context.
LS_INSUFFICIENT_UNITS	The licensing system cannot locate enough available licensing resources to complete the request.
LS_LICENSE_TERMINATED	The licensing system has determined that the resources used to satisfy a previous request are no longer granted to the calling software.
LS_AUTHORIZATION_UNAVAILABLE	The licensing system has no licensing resources to complete the request.
LS_LICENSE_UNAVAILABLE	The licensing system has licensing resources that could satisfy the request, but they are not available at the time of the request.
LS_RESOURCES_UNAVAILABLE	The request cannot be completed because of insufficient resources, such as memory.
LS_NETWORK_UNAVAILABLE	The network is unavailable.
LS_LICENSE_EXPIRED	The license associated with the current context has expired. This may be due to a time-restriction on the license.
LS_BAD_ARG	One or more of the arguments is incorrect.
Remarks

Your application should periodically call the LSUpdate function to verify that the current license is still valid. The application can use the LSQuery function to determine the proper time interval for the current licensing context. A guideline of once an hour may be appropriate, with a minimum interval of 15 minutes. Consult your license system vendor for more information.

The LSUpdate function verifies that the license system context has not changed from the one expected by the licensed software. The LSUpdate function can determine if the licensing resources granted to the specified handle are still reserved for this application. In a distributed license system, an error might indicate a temporary network interruption. It can also determine if the license system has released the licensing resources granted to the specified handle. An error indicates the software no longer has authorization to execute in a typical manner.

The call to the LSUpdate function can also indicate that the current licensing context has expired. For example, in the case of a time-restricted license policy, it returns the warning status LS_LICENSE_EXPIRED.

If the number of new units requested in the TotUnitsReserved parameter is greater than the number available, then the update request fails and it returns the error LS_INSUFFICIENT_UNITS.

If the call completes successfully, the value returned in the TotUnitsGranted parameter indicates the current total of units granted.

If LSUpdate returns an error, it does not return a challenge response. Application software should be prepared to handle vendor-specific error conditions if they arise. If any error is returned, a call to the LSRelease function is still required.

See Also

LS_CHALLENGE, LSGetMessage, LSQuery, LSRelease, LSRequest


lstrcat

The lstrcat function appends one string to another.

LPTSTR lstrcat(

LPTSTR lpString1,	// address of buffer for concatenated strings
LPCTSTR lpString2	// address of string to add to string1
);
Parameters

lpString1

Points to a null-terminated string. The buffer must be large enough to contain both strings.

lpString2

Points to the null-terminated string to be appended to the string specified in the lpString1 parameter.

Return Values

If the function succeeds, the return value is a pointer to the buffer.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

lstrcmp, lstrcmpi, lstrcpy, lstrlen


lstrcmp

The lstrcmp function compares two character strings. The comparison is case sensitive.

int lstrcmp(

LPCTSTR lpString1,	// address of first string
LPCTSTR lpString2	// address of second string
);
Parameters

lpString1

Points to the first null-terminated string to be compared.

lpString2

Points to the second null-terminated string to be compared.

Return Values

If the function succeeds and the string pointed to by lpString1 is less than the string pointed to by lpString2, the return value is negative; if the string pointed to by lpString1 is greater than the string pointed to by lpString2, it is positive. If the strings are equal, the return value is zero.

Remarks

The lstrcmp function compares two strings by checking the first characters against each other, the second characters against each other, and so on until it finds an inequality or reaches the ends of the strings.

The function returns the difference of the values of the first unequal characters it encounters. For example, lstrcmp determines that “abcz” is greater than “abcdefg” and returns the difference of z and d.

The language (locale) selected by the user at setup time, or via the control panel, determines which string is greater (or whether the strings are the same). If no language (locale) is selected, Windows performs the comparison by using default values. In the Windows United States language functions, uppercase characters have lower values than lowercase characters.

With a double-byte character set (DBCS) version of Windows, this function can compare two DBCS strings.

The Win32 lstrcmp function uses a word sort, rather than a string sort. A word sort treats hyphens and apostrophes differently than it treats other symbols that are not alphanumeric, in order to ensure that words such as “coop” and “co-op” stay together within a sorted list. Note that in 16-bit versions of Windows, lstrcmp  uses a string sort. For a detailed discussion of word sorts and string sorts, see the Remarks section of the reference page for the CompareString function .

See Also

CompareString, lstrcat, lstrcmpi, lstrcpy, lstrlen


lstrcmpi

The lstrcmpi function compares two character strings. The comparison is not case sensitive.

int lstrcmpi(

LPCTSTR lpString1,	// address of first string
LPCTSTR lpString2	// address of second string
);
Parameters

lpString1

Points to the first null-terminated string to be compared.

lpString2

Points to the second null-terminated string to be compared.

Return Values

If the function succeeds and the string pointed to by lpString1 is less than the string pointed to by lpString2, the return value is negative; if the string pointed to by lpString1 is greater than the string pointed to by lpString2, it is positive. If the strings are equal, the return value is zero.

Remarks

The lstrcmpi function compares two strings by checking the first characters against each other, the second characters against each other, and so on until it finds an inequality or reaches the ends of the strings.

The function returns the difference of the values of the first unequal characters it encounters. For example, lstrcmpi determines that “abcz” is greater than “abcdefg” and returns the difference of z and d.

The language (locale) selected by the user at setup time, or by using the control panel, determines which string is greater (or whether the strings are the same). If no language (locale) is selected, Windows performs the comparison by using default values.

For some locales, the lstrcmpi function may be insufficient. If this occurs, use CompareString to ensure proper comparison. For example, in Japan call CompareString with the IGNORE_CASE, IGNORE_KANATYPE, and IGNORE_WIDTH values to achieve the most appropriate non-exact string comparison. The IGNORE_KANATYPE and IGNORE_WIDTH values are ignored in non-Asian locales, so you can set these values for all locales and be guaranteed to have a culturally correct “insensitive” sorting regardless of the locale. Note that specifying these values slows performance, so use them only when necessary.

With a double-byte character set (DBCS) version of Windows, this function can compare two DBCS strings.

The Win32 lstrcmpi function uses a word sort, rather than a string sort. A word sort treats hyphens and apostrophes differently than it treats other symbols that are not alphanumeric, in order to ensure that words such as “coop” and “co-op” stay together within a sorted list. Note that in 16-bit versions of Windows, lstrcmpi uses a string sort. For a detailed discussion of word sorts and string sorts, see the Remarks section of the reference page for the CompareString function .

See Also

CompareString, lstrcat, lstrcmp, lstrcpy, lstrlen


lstrcpy

The lstrcpy function copies a string to a buffer.

LPTSTR lstrcpy(

LPTSTR lpString1,	// address of buffer
LPCTSTR lpString2	// address of string to copy
);
Parameters

lpString1

Points to a buffer to receive the contents of the string pointed to by the lpString2 parameter. The buffer must be large enough to contain the string, including the terminating null character.

lpString2

Points to the null-terminated string to be copied.

Return Values

If the function succeeds, the return value is a pointer to the buffer.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

With a double-byte character set (DBCS) version of Windows, this function can be used to copy a DBCS string.

See Also

lstrcat, lstrcmp, lstrcmpi, lstrlen


lstrcpyn

The lstrcpyn function copies a specified number of characters from a source string into a buffer.

LPTSTR lstrcpyn(

LPTSTR lpString1,	// address of target buffer
LPCTSTR lpString2,	// address of source string
int iMaxLength	// number of bytes or characters to copy
);
Parameters

lpString1

Points to a buffer into which the function copies characters. The buffer must be large enough to contain the number of bytes (ANSI version) or characters (Unicode version) specified by iMaxLength, including room for a terminating null character.

lpString2

Points to a null-terminated string from which the function copies characters.

iMaxLength

Specifies the number bytes (ANSI version) or characters (Unicode version) to be copied from the string pointed to by lpString2 into the buffer pointed to by lpString1, including a terminating null character.

Return Values

If the function succeeds, the return value is a pointer to the buffer.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Note that the buffer pointed to by lpString1 must be large enough to include a terminating null character, and the string length value specified by iMaxLength includes room for a terminating null character. Thus, the following code

TCHAR chBuffer[512] ;

lstrcpyn(chBuffer, "abcdefghijklmnop", 4) ;

... copies the string "abc", followed by a terminating null character, to chBuffer.

See Also

lstrcat, lstrcmp, lstrcmpi, lstrcpy, lstrlen


lstrlen

The lstrlen function returns the length in bytes (ANSI version) or characters (Unicode version) of the specified string (not including the terminating null character).

int lstrlen(

LPCTSTR lpString	// address of string to count
);
Parameters

lpString

Points to a null-terminated string.

Return Values

If the function succeeds, the return value specifies the length of the string in bytes (ANSI version) or characters (Unicode version).

See Also

lstrcat, lstrcmp, lstrcmpi, lstrcpy


LZClose

The LZClose function closes a file that was opened by using the LZOpenFile function.

VOID LZClose(

INT hFile	// LZ file handle identifying file to be closed
);
Parameters

hFile

Identifies the source file to be closed.

Return Values

This function does not return a value.

Remarks

The handle identifying the file must be retrieved by calling the LZOpenFile function. If the handle is retrieved by calling the CreateFile or OpenFile function, an error occurs.

If the file is compressed by using the Microsoft File Compression Utility (COMPRESS.EXE) and opened by using LZOpenFile, LZClose frees any global heap space that was allocated to expand the file.

See Also

CreateFile, LZOpenFile, OpenFile


LZCopy

The LZCopy function copies a source file to a destination file. If the source file is compressed with the Microsoft File Compression Utility (COMPRESS.EXE), this function creates a decompressed destination file. If the source file is not compressed, this function duplicates the original file.

LONG LZCopy(

INT hfSource,	// LZ file handle identifying source file
INT hfDest	// LZ file handle identifying destination file
);
Parameters

hfSource

Identifies the source file.

hfDest

Identifies the destination file.

Return Values

If the function succeeds, the return value specifies the size, in bytes, of the destination file.

If the function fails, the return value is an LZERROR_* code. These codes have values less than zero. Note that LZCopy calls neither SetLastError nor SetLastErrorEx; thus, its failure does not affect a thread’s last-error code.

Here is a list of the LZERROR_* codes that LZCopy can return upon failure:

Value	Meaning
LZERROR_BADINHANDLE	The handle identifying the source file is not valid. The file cannot be read.
LZERROR_BADOUTHANDLE	The handle identifying the destination file is not valid. The file cannot be written.
LZERROR_GLOBALLOC	The maximum number of open compressed files has been exceeded or local memory cannot be allocated.
LZERROR_GLOBLOCK	The LZ file handle cannot be locked down.
LZERROR_READ	The source file format is not valid.
Remarks

The handles identifying the source and destination files must be retrieved by calling the LZInit or LZOpenFile function.

The preferred function to use for copying files is LZCopy. The CopyLZFile function is provided for compatibility with 16-bit versions of Windows.

If the function succeeds, the file identified by the hfDest parameter is always uncompressed.

See Also

CopyLZFile, LZInit, LZOpenFile


LZDone

The LZDone function is obsolete. It is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the LZOpenFile function.


LZInit

The LZInit function allocates memory for the internal data structures required to decompress files, and then creates and initializes them.

INT LZInit(

INT hfSource	// handle of source file
);
Parameters

hfSource

Identifies the source file.

Return Values

If the function succeeds, the return value is a new LZ file handle.

If the function fails, the return value is an LZERROR_* code. These codes have values less than zero. Note that LZInit calls neither SetLastError nor SetLastErrorEx; thus, its failure does not affect a thread’s last-error code.

Here is a list of the LZERROR_* codes that LZInit can return upon failure:

Value	Meaning
LZERROR_BADINHANDLE	The handle identifying the source file is not valid. The file cannot be read.
LZERROR_GLOBALLOC	The maximum number of open compressed files has been exceeded or local memory cannot be allocated.
LZERROR_GLOBLOCK	The LZ file handle cannot be locked down.
LZERROR_UNKNOWNALG	The file is compressed with an unrecognized compression algorithm.
Remarks

A maximum of 16 compressed files can be open at any given time. Similarly, a maximum of 16 uncompressed files can be open at any given time. An application should be careful to close the handle returned by LZInit when it is done using the file; otherwise, the application can inadvertently hit the 16-file limit.

The handle this function returns is compatible only with the functions in LZEXPAND.DLL; it should not be used for other file operations.


LZOpenFile

The LZOpenFile function creates, opens, reopens, or deletes the specified file.

INT LZOpenFile(

LPTSTR lpFileName,	// address of name of file to be opened
LPOFSTRUCT lpReOpenBuf,	// address of open file structure
WORD wStyle	// action to take
);
Parameters

lpFileName

Points to a string that specifies the name of a file.

lpReOpenBuf

Points to the OFSTRUCT structure that is to receive information about the file when the file is first opened. The structure can be used in subsequent calls to the LZOpenFile function to refer to the open file.

The szPathName member of this structure contains characters from the original equipment manufacturer (OEM) character set.

wStyle

Specifies the action to take. This parameter can be a combination of the following values:

Value	Meaning
OF_CANCEL	Ignored. In the Win32-based application programming interface (API), the OF_PROMPT style produces a dialog box containing a Cancel button.
OF_CREATE	Directs LZOpenFile to create a new file. If the file already exists, it is truncated to zero length.
OF_DELETE	Deletes the file.
OF_EXIST	Opens the file and then closes it to test for a file’s existence.
OF_PARSE	Fills the OFSTRUCT structure but carries out no other action.
OF_PROMPT	Displays a dialog box if the requested file does not exist. The dialog box informs the user that Windows cannot find the file, and it contains Retry and Cancel buttons. Choosing the Cancel button directs LZOpenFile to return a “file not found” error message.
OF_READ	Opens the file for reading only.
OF_READWRITE	Opens the file for reading and writing.
OF_REOPEN	Opens the file using information in the reopen buffer.
OF_SHARE_DENY_NONE	Opens the file without denying other processes read or write access to the file. LZOpenFile fails if the file has been opened in compatibility mode by any other process.
OF_SHARE_DENY_READ	Opens the file and denies other processes read access to the file. LZOpenFile fails if the file has been opened in compatibility mode or has been opened for read access by any other process.
OF_SHARE_DENY_WRITE	Opens the file and denies other processes write access to the file. LZOpenFile fails if the file has been opened in compatibility mode or has been opened for write access by any other process.
OF_SHARE_EXCLUSIVE	Opens the file in exclusive mode, denying other processes both read and write access to the file. LZOpenFile fails if the file has been opened in any other mode for read or write access, even by the current process.
OF_WRITE	Opens the file for writing only.
Return Values

If the function succeeds and the value specified by the wStyle parameter is not OF_READ, the return value is a handle identifying the file. If the file is compressed and opened with wStyle set to OF_READ, the return value is a special file handle.

If the function fails, the return value is an LZERROR_* code. These codes have values less than zero. Note that LZOpenFile calls neither SetLastError nor SetLastErrorEx; thus, its failure does not affect a thread’s last-error code.

Here is a list of the LZERROR_* codes that LZOpenFile can return upon failure:

Value	Meaning
LZERROR_BADINHANDLE	The handle identifying the source file is not valid. The file cannot be read.
LZERROR_GLOBALLOC	The maximum number of open compressed files has been exceeded or local memory cannot be allocated.
Remarks

If the wStyle parameter is the OF_READ flag (or OF_READ and any of the OF_SHARE_ flags) and the file is compressed, LZOpenFile calls the LZInit function, which performs the required initialization for the decompression operations.

The handle this function returns is compatible only with the functions in LZEXPAND.DLL; it should not be used for other file operations.

See Also

LZClose, LZInit, LZRead


LZRead

The LZRead function reads (at most) the specified number of bytes from a file and copies them into a buffer.

INT LZRead(

INT hFile,	// LZ file handle of file
LPSTR lpBuffer,	// address of buffer for bytes
INT cbRead	// count of bytes
);
Parameters

hFile

Identifies the source file.

lpBuffer

Points to a buffer that receives the bytes read from the file.

cbRead

Specifies the count of bytes to be read.

Return Values

If the function succeeds, the return value specifies the number of bytes read.

If the function fails, the return value is an LZERROR_* code. These codes have values less than zero. Note that LZRead calls neither SetLastError nor SetLastErrorEx; thus, its failure does not affect a thread’s last-error code.

Here is a list of the LZERROR_* codes that LZRead can return upon failure:

Value	Meaning
LZERROR_BADINHANDLE	The handle identifying the source file is not valid. The file cannot be read.
LZERROR_BADOUTHANDLE	The handle identifying the destination file is not valid. The file cannot be written.
LZERROR_BADVALUE	One of the input parameters is not valid.
LZERROR_GLOBALLOC	The maximum number of open compressed files has been exceeded or local memory cannot be allocated.
LZERROR_GLOBLOCK	The LZ file handle cannot be locked down.
LZERROR_READ	The source file format is not valid.
LZERROR_WRITE	There is insufficient space for the output file.
Remarks

The handle identifying the file must be retrieved by calling either the LZInit or LZOpenFile function.

If the file is compressed, LZRead emulates the _lread function on an expanded image of the file and copies the bytes of data into the specified buffer.

Applications must call the LZOpenFile, LZSeek, and LZRead functions instead of the OpenFile, _llseek, and _lread functions.

See Also

LZInit, LZOpenFile, LZSeek


LZSeek

The LZSeek function moves a file pointer a number of bytes from a starting position.

LONG LZSeek(

INT hFile,	// handle of source file
LONG lOffset,	// number of bytes to move
INT iOrigin	// starting position
);
Parameters

hFile

Identifies the source file.

lOffset

Specifies the number of bytes by which to move the file pointer.

iOrigin

Specifies the starting position of the pointer. This parameter must be one of the following values:

Value	Meaning
0	Moves the file pointer lOffset bytes from the beginning of the file.
1	Moves the file pointer lOffset bytes from the current position.
2	Moves the file pointer lOffset bytes from the end of the file.
Return Values

If the function succeeds, the return value specifies the offset from the beginning of the file to the new pointer position.

If the function fails, the return value is an LZERROR_* code. These codes have values less than zero. Note that LZSeek calls neither SetLastError nor SetLastErrorEx; thus, its failure does not affect a thread’s last-error code.

Upon failure, LZSeek can return the following LZERROR_* codes:

Value	Meaning
LZERROR_BADINHANDLE	The handle identifying the source file is not valid. The file cannot be read.
LZERROR_BADVALUE	One of the parameters is outside the range of acceptable values.
LZERROR_GLOBLOCK	The LZ file handle cannot be locked down.
Remarks

The handle identified by the hFile parameter must be retrieved by calling either the LZInit or LZOpenFile function.

If the file is compressed, LZSeek emulates the _llseek function on an expanded image of the file.

See Also

LZInit, LZOpenFile


LZStart

The LZStart function is obsolete. It is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the LZCopy function.


MakeAbsoluteSD

The MakeAbsoluteSD function creates a security descriptor in absolute format by using a security descriptor in self-relative format as a template.

BOOL MakeAbsoluteSD(

PSECURITY_DESCRIPTOR pSelfRelativeSecurityDescriptor,	// address self-relative SD
PSECURITY_DESCRIPTOR pAbsoluteSecurityDescriptor,	// address of absolute SD
LPDWORD lpdwAbsoluteSecurityDescriptorSize,	// address of size of absolute SD
PACL pDacl,	// address of discretionary ACL
LPDWORD lpdwDaclSize,	// address of size of discretionary ACL
PACL pSacl,	// address of system ACL
LPDWORD lpdwSaclSize,	// address of size of system ACL
PSID pOwner,	// address of owner SID
LPDWORD lpdwOwnerSize,	// address of size of owner SID
PSID pPrimaryGroup,	// address of primary-group SID
LPDWORD lpdwPrimaryGroupSize	// address of size of group SID
);
Parameters

pSelfRelativeSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure in self-relative format. The function creates an absolute-format version of this security descriptor without modifying the original security descriptor.

pAbsoluteSecurityDescriptor

Points to a buffer that the function fills with the main body of an absolute-format security descriptor. This information is formatted as a SECURITY_DESCRIPTOR structure.

lpdwAbsoluteSecurityDescriptorSize

Points to a variable specifying the size of the buffer pointed to by the pAbsoluteSecurityDescriptor parameter. If the buffer is not large enough for the security descriptor, the function fails and sets this variable to the minimum required size.

pDacl

Points to a buffer the function fills with the discretionary access-control list (ACL) of the absolute-format security descriptor. The main body of the absolute-format security descriptor references this pointer.

lpdwDaclSize

Points to a variable specifying the size of the buffer pointed to by the pDacl parameter. If the buffer is not large enough for the ACL, the function fails and sets this variable to the minimum required size.

pSacl

Points to a buffer the function fills with the system ACL of the absolute-format security descriptor. The main body of the absolute-format security descriptor references this pointer.

lpdwSaclSize

Points to a variable specifying the size of the buffer pointed to by the pSacl parameter. If the buffer is not large enough for the ACL, the function fails and sets this variable to the minimum required size.

pOwner

Points to a buffer the function fills with the security identifier (SID) of the owner of the absolute-format security descriptor. The main body of the absolute-format security descriptor references this pointer.

lpdwOwnerSize

Points to a variable specifying the size of the buffer pointed to by the pOwner parameter. If the buffer is not large enough for the SID, the function fails and sets this variable to the minimum required size.

pPrimaryGroup

Points to a buffer the function fills with the SID of the absolute-format security descriptor’s primary group. The main body of the absolute-format security descriptor references this pointer.

lpdwPrimaryGroupSize

Points to a variable specifying the size of the buffer pointed to by the pPrimaryGroup parameter. If the buffer is not large enough for the SID, the function fails and sets this variable to the minimum required size.

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.

Remarks

A security descriptor in absolute format contains pointers to the information it contains, rather than the information itself. A security descriptor in self-relative format contains the information in a contiguous block of memory. In a self-relative security descriptor, a SECURITY_DESCRIPTOR structure always starts the information, but the security descriptor’s other components can follow the structure in any order. Instead of using memory addresses, the components of the self-relative security descriptor are identified by offsets from the beginning of the security descriptor. This format is useful when an security descriptor must be stored on a floppy disk or transmitted by means of a communications protocol.

A server that copies secured objects to various media can use the MakeAbsoluteSD function to create an absolute security descriptor from a self-relative security descriptor and the MakeSelfRelativeSD function to create a self-relative security descriptor from an absolute security descriptor.

See Also

MakeSelfRelativeSD, SECURITY_DESCRIPTOR


MakeDragList

The MakeDragList function changes the specified single-selection list box to a drag list box.

BOOL MakeDragList(

HWND hLB
);
Parameters

hLB

Handle to the single-selection list box.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.


MakeProcInstance

The MakeProcInstance function is obsolete. Win32 functions can be called directly.

This function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should not use this function.


MakeSelfRelativeSD

The MakeSelfRelativeSD function creates a security descriptor in self-relative format by using a security descriptor in absolute format as a template.

BOOL MakeSelfRelativeSD(

PSECURITY_DESCRIPTOR pAbsoluteSecurityDescriptor,	// address of absolute SD
PSECURITY_DESCRIPTOR pSelfRelativeSecurityDescriptor,	// address self-relative SD
LPDWORD lpdwBufferLength	// address of SD size
);
Parameters

pAbsoluteSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure in absolute format. The function creates a version of this security descriptor in self-relative format without modifying the original.

pSelfRelativeSecurityDescriptor

Points to a buffer the function fills with a security descriptor in self-relative format.

lpdwBufferLength

Points to a variable specifying the size of the buffer pointed to by the pSelfRelativeSecurityDescriptor parameter. If the buffer is not large enough for the security descriptor, the function fails and sets this variable to the minimum required size.

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.

Remarks

A security descriptor in absolute format contains pointers to the information it contains, rather than containing the information itself. A security descriptor in self-relative format contains the information in a contiguous block of memory. In a self-relative security descriptor, a SECURITY_DESCRIPTOR structure always starts the information, but the security descriptor’s other components can follow the structure in any order. Instead of using memory addresses, the components of the security descriptor are identified by offsets from the beginning of the security descriptor. This format is useful when an security descriptor must be stored on a floppy disk or transmitted by means of a communications protocol.

A server that copies secured objects to various media can use the MakeSelfRelativeSD function to create a self-relative security descriptor from an absolute security descriptor and the MakeAbsoluteSD function to create an absolute security descriptor from a self-relative security descriptor.

See Also

MakeAbsoluteSD, SECURITY_DESCRIPTOR


MapDialogRect

The MapDialogRect function converts (maps) the specified dialog box units to screen units (pixels). The function replaces the coordinates in the specified RECT structure with the converted coordinates, which allows the structure to be used to create a dialog box or position a control within a dialog box.

BOOL MapDialogRect(

HWND hDlg,	// handle of dialog box
LPRECT lpRect	// address of structure with rectangle
);
Parameters

hDlg

Identifies a dialog box. This function accepts only handles for dialog boxes created by one of the dialog box creation functions; handles for other windows are not valid.

lpRect

Points to a RECT structure that contains the dialog box coordinates to be converted.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The MapDialogRect function assumes that the initial coordinates in the RECT structure represent dialog box units. To convert these coordinates from dialog box units to pixels, the function retrieves the current horizontal and vertical base units for the dialog box, then applies the following formulas:

left   = (left   * baseunitX) / 4

right  = (right  * baseunitX) / 4

top    = (top    * baseunitY) / 8

bottom = (bottom * baseunitY) / 8

In most cases, the base units for the dialog box are the same as those retrieved by using the GetDialogBaseUnits function. If the dialog box template has the DS_SETFONT style, however, the base units are the average width and height, in pixels, of the characters in the font given by the template.

See Also

CreateDialog, CreateDialogIndirect, CreateDialogIndirectParam, CreateDialogParam, DialogBox, DialogBoxIndirect, DialogBoxIndirectParam, DialogBoxParam, GetDialogBaseUnits, RECT


MapGenericMask

The MapGenericMask function maps the generic access rights in an access mask to specific and standard access rights. The function applies a mapping supplied in a GENERIC_MAPPING structure.

VOID MapGenericMask(

PDWORD AccessMask,	// address of access mask
PGENERIC_MAPPING GenericMapping	// address of GENERIC_MAPPING structure
);
Parameters

AccessMask

Points to an access mask receiving the specific and standard rights mapped from generic access rights.

GenericMapping

Points to a GENERIC_MAPPING structure specifying a mapping of generic access types to specific and standard access types.

Return Values

This function does not return a value.

Remarks

After calling the MapGenericMask function, the access mask pointed to by the AccessMask parameter has none of its generic bits (GenericRead, GenericWrite, GenericExecute, or GenericAll) or undefined bits set, although it can have other bits set. If bits other than the generic bits are provided on input, this function does not clear them.

See Also

AccessCheck, AreAllAccessesGranted, AreAnyAccessesGranted, GENERIC_MAPPING


MapViewOfFile

The MapViewOfFile function maps a view of a file into the address space of the calling process.

LPVOID MapViewOfFile(

HANDLE hFileMappingObject,	// file-mapping object to map into address space
DWORD dwDesiredAccess,	// access mode
DWORD dwFileOffsetHigh,	// high-order 32 bits of file offset
DWORD dwFileOffsetLow,	// low-order 32 bits of file offset
DWORD dwNumberOfBytesToMap	// number of bytes to map
);
Parameters

hFileMappingObject

Identifies an open handle of a file-mapping object. The CreateFileMapping and OpenFileMapping functions return this handle.

dwDesiredAccess

Specifies the type of access to the file view and, therefore, the protection of the pages mapped by the file. This parameter can be one of the following values:

Value	Meaning
FILE_MAP_WRITE	Read-write access. The hFileMappingObject parameter must have been created with PAGE_READWRITE protection. A read-write view of the file is mapped.
FILE_MAP_READ	Read-only access. The hFileMappingObject parameter must have been created with PAGE_READWRITE or PAGE_READONLY protection. A read-only view of the file is mapped.
FILE_MAP_ALL_ACCESS	Same as FILE_MAP_WRITE.
FILE_MAP_COPY	Copy on write access. If you create the map with PAGE_WRITECOPY and the view with FILE_MAP_COPY, you will receive a view to file. If you write to it, the pages are automatically swappable and the modifications you make will not go to the original data file. Windows 95: You must pass PAGE_WRITECOPY to CreateFileMapping; otherwise, an error will be returned. If you share the mapping between multiple processes using DuplicateHandle or OpenFileMapping and one process writes to a view, the modification is propagated to the other process. The original file does not change. Windows NT: There is no restriction as to how the hFileMappingObject parameter must be created. Copy on write is valid for any type of view.  If you share the mapping between multiple processes using DuplicateHandle or OpenFileMapping and one process writes to a view, the modification is not propagated to the other process. The original file does not change.
dwFileOffsetHigh

Specifies the high-order 32 bits of the file offset where mapping is to begin.

dwFileOffsetLow

Specifies the low-order 32 bits of the file offset where mapping is to begin. The combination of the high and low offsets must specify an offset within the file that matches the system’s memory allocation granularity, or the function fails. That is, the offset must be a multiple of the allocation granularity. Use the GetSystemInfo function, which fills in the members of a SYSTEM_INFO structure, to obtain the system’s memory allocation granularity.

dwNumberOfBytesToMap

Specifies the number of bytes of the file to map. If dwNumberOfBytesToMap is zero, the entire file is mapped.

Return Values

If the function succeeds, the return value is the starting address of the mapped view.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Mapping a file makes the specified portion of the file visible in the address space of the calling process.

Multiple views of a file (or a file-mapping object and its mapped file) are said to be “coherent” if they contain identical data at a specified time. This occurs if the file views are derived from the same file-mapping object. A process can duplicate a file-mapping object handle into another process by using the DuplicateHandle function, or another process can open a file-mapping object by name by using the OpenFileMapping function.

A mapped view of a file is not guaranteed to be coherent with a file being accessed by the ReadFile or WriteFile function.

Windows 95: MapViewOfFile may require the swapfile to grow. If the swapfile cannot grow, the function fails.

Windows NT: If the file-mapping object is backed by the paging file (handle = 0xFFFFFFFF), the paging file must be large enough to hold the entire mapping. If it is not, MapViewOfFile fails.

See Also

CreateFileMapping, DuplicateHandle, GetSystemInfo, MapViewOfFileEx, OpenFileMapping, UnmapViewOfFile, SYSTEM_INFO


MapViewOfFileEx

The MapViewOfFileEx function maps a view of a file into the address space of the calling process. This extended function allows the calling process to specify a suggested memory address for the mapped view.

This function is available for Win32-based applications only.

LPVOID MapViewOfFileEx(

HANDLE hFileMappingObject,	// file-mapping object to map into address space
DWORD dwDesiredAccess,	// access mode
DWORD dwFileOffsetHigh,	// high-order 32 bits of file offset
DWORD dwFileOffsetLow,	// low-order 32 bits of file offset
DWORD dwNumberOfBytesToMap,	// number of bytes to map
LPVOID lpBaseAddress	// suggested starting address for mapped view
);
Parameters

hFileMappingObject

Identifies an open handle to a file-mapping object. The CreateFileMapping and OpenFileMapping functions return this handle.

dwDesiredAccess

Specifies the type of access to the file-mapping object and, therefore, the page protection of the pages mapped by the file. This parameter can be one of the following values:

Value	Meaning
FILE_MAP_WRITE	Read-and-write access. The hFileMappingObject parameter must have been created with PAGE_READWRITE protection. A read-write view of the file is mapped.
FILE_MAP_READ	Read-only access. The hFileMappingObject parameter must have been created with PAGE_READWRITE or PAGE_READONLY protection. A read-only view of the file is mapped.
FILE_MAP_ALL_ACCESS	Same as FILE_MAP_WRITE.
FILE_MAP_COPY	Copy on write access. If you create the map with PAGE_WRITECOPY and the view with FILE_MAP_COPY, you will receive a view to the file. If you write to it, the pages are automatically swappable and the modifications you make will not go to the original data file. Windows 95: You must pass PAGE_WRITECOPY to CreateFileMapping; otherwise, an error will be returned. If you share the mapping between multiple processes using DuplicateHandle or OpenFileMapping and one process writes to a view, the modification is propagated to the other process. The original file does not change. Windows NT: There is no restriction as to how the hFileMappingObject parameter must be created. Copy on write is valid for any type of view.  If you share the mapping between multiple processes using DuplicateHandle or OpenFileMapping and one process writes to a view, the modification is not propagated to the other process. The original file does not change.
dwFileOffsetHigh

Specifies the high-order 32 bits of the file offset where mapping is to begin.

dwFileOffsetLow

Specifies the low-order 32 bits of the file offset where mapping is to begin. The combination of the high and low offsets must specify an offset within the file that matches the system’s memory allocation granularity, or the function fails. That is, the offset must be a multiple of the allocation granularity. Use the GetSystemInfo function, which fills in the members of a SYSTEM_INFO structure, to obtain the system’s memory allocation granularity.

dwNumberOfBytesToMap

Specifies the number of bytes of the file to map. If dwNumberOfBytesToMap is zero, the entire file is mapped.

lpBaseAddress

Points to the memory address in the calling process’s address space where mapping should begin. This must be a multiple of the system’s memory allocation granularity, or the function fails. Use the GetSystemInfo function, which fills in the members of a SYSTEM_INFO structure, to obtain the system’s memory allocation granularity. If there is not enough address space at the specified address, the function fails.

If lpBaseAddress is NULL, the operating system chooses the mapping address. In this case, this function is equivalent to the MapViewOfFile function.

Return Values

If the function succeeds, the return value is the starting address of the mapped view.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Mapping a file makes the specified portion of the file visible in the address space of the calling process.

If a suggested mapping address is supplied, the file is mapped at the specified address (rounded down to the nearest 64K boundary) if there is enough address space at the specified address. If there is not, the function fails.

Typically, the suggested address is used to specify that a file should be mapped at the same address in multiple processes. This requires the region of address space to be available in all involved processes. No other memory allocation, including use of the VirtualAlloc function to reserve memory, can take place in the region used for mapping.

Windows 95: If the lpBaseAddress parameter specifies a base offset, the function succeeds only if the same memory region is available for the memory mapped file in all other 32-bit processes.

Windows NT: If the lpBaseAddress parameter specifies a base offset, the function succeeds if the given memory region is not already in use by the calling process. the system does not guarantee that the same memory region is available for the memory mapped file in other 32-bit processes.

Multiple views of a file (or a file-mapping object and its mapped file) are said to be “coherent” if they contain identical data at a specified time. This occurs if the file views are derived from the same file-mapping object. A process can duplicate a file-mapping object handle into another process by using the DuplicateHandle function, or another process can open a file-mapping object by name by using the OpenFileMapping function.

A mapped view of a file is not guaranteed to be coherent with a file being accessed by the ReadFile or WriteFile function.

See Also

CreateFileMapping, DuplicateHandle, GetSystemInfo, MapViewOfFile, OpenFileMapping, ReadFile, UnmapViewOfFile, SYSTEM_INFO, VirtualAlloc, WriteFile


MapVirtualKey

The MapVirtualKey function translates (maps) a virtual-key code into a scan code or character value, or translates a scan code into a virtual-key code.

UINT MapVirtualKey(

UINT uCode,	// virtual-key code or scan code
UINT uMapType	// translation to perform
);
Parameters

uCode

Specifies the virtual-key code or scan code for a key. How this value is interpreted depends on the value of the uMapType parameter.

uMapType

Specifies the translation to perform. The value of this parameter depends on the value of the uCode parameter:

Value	Meaning
0	uCode is a virtual-key code and is translated into a scan code. If it is a virtual-key code that does not distinguish between left- and right-hand keys, the left-hand scan code is returned. If there is no translation, the function returns 0.
1	uCode is a scan code and is translated into a virtual-key code that does not distinguish between left- and right-hand keys. If there is no translation, the function returns 0.
2	uCode is a virtual-key code and is translated into an unshifted character value in the low-order word of the return value. Dead keys (diacritics) are indicated by setting the top bit of the return value. If there is no translation, the function returns 0.
3	uCode is a scan code and is translated into a virtual-key code that distinguishes between left- and right-hand keys. If there is no translation, the function returns 0.
Return Values

The return value is either a scan code, a virtual-key code, or a character value, depending on the value of uCode and uMapType. If there is no translation, the return value is zero.

Remarks

An application can use MapVirtualKey to translate scan codes to the virtual-key code constants VK_SHIFT, VK_CONTROL, and VK_MENU, and vice versa. These translations do not distinguish between the left and right instances of the SHIFT, CTRL, or ALT keys. An application can get the scan code corresponding to the left or right instance of one of these keys by calling MapVirtualKey with uCode set to one of the following virtual-key code constants:

VK_LSHIFT	VK_RSHIFT
VK_LCONTROL	VK_RCONTROL
VK_LMENU	VK_RMENU
These left- and right-distinguishing constants are available to an application only through the GetKeyboardState, SetKeyboardState, GetAsyncKeyState, GetKeyState, and MapVirtualKey functions.

See Also

GetAsyncKeyState, GetKeyboardState, GetKeyState, SetKeyboardState


MapVirtualKeyEx [Now Supported on Windows NT]
MapVirtualKeyEx

[Now Supported on Windows NT]

The MapVirtualKeyEx function translates (maps) a virtual-key code into a scan code or character value, or translates a scan code into a virtual-key code. The function translates the codes using the input language and physical keyboard layout identified by the given keyboard layout handle.

UINT MapVirtualKeyEx(

UINT uCode,	// virtual-key code or scan code
UINT uMapType,	// translation to perform
HKL dwhkl	// keyboard layout handle
);
Parameters

uCode

Specifies the virtual-key code or scan code for a key. How this value is interpreted depends on the value of the uMapType parameter.

uMapType

Specifies the translation to perform. The value of this parameter depends on the value of the uCode parameter:

Value	Meaning
0	uCode is a virtual-key code and is translated into a scan code. If it is a virtual-key code that does not distinguish between left- and right-hand keys, the left-hand scan code is returned. If there is no translation, the function returns 0.
1	uCode is a scan code and is translated into a virtual-key code that does not distinguish between left- and right-hand keys. If there is no translation, the function returns 0.
2	uCode is a virtual-key code and is translated into an unshifted character value in the low order word of the return value. Dead keys (diacritics) are indicated by setting the top bit of the return value. If there is no translation, the function returns 0.
3	uCode is a scan code and is translated into a virtual-key code that distinguishes between left- and right-hand keys. If there is no translation, the function returns 0.
dwhkl

Identifies the keyboard layout to use for translating the given code. This parameter can be any keyboard layout handle previously returned by the LoadKeyboardLayout function.

Return Values

The return value is either a scan code, a virtual-key code, or a character value, depending on the value of uCode and uMapType. If there is no translation, the return value is zero.

Remarks

An application can use MapVirtualKeyEx to translate scan codes to the virtual-key code constants VK_SHIFT, VK_CONTROL, and VK_MENU, and vice versa. These translations do not distinguish between the left and right instances of the SHIFT, CTRL, or ALT keys. An application can get the scan code corresponding to the left or right instance of one of these keys by calling MapVirtualKeyEx with uCode set to one of the following virtual-key code constants:

VK_LSHIFT	VK_RSHIFT
VK_LCONTROL	VK_RCONTROL
VK_LMENU	VK_RMENU
These left- and right-distinguishing constants are available to an application only through the GetKeyboardState, SetKeyboardState, GetAsyncKeyState, GetKeyState, MapVirtualKey, and MapVirtualKeyEx functions.

See Also

GetAsyncKeyState, GetKeyboardState, GetKeyState, LoadKeyboardLayout, MapVirtualKey, SetKeyboardState


MapWindowPoints

The MapWindowPoints function converts (maps) a set of points from a coordinate space relative to one window to a coordinate space relative to another window.

int MapWindowPoints(

HWND hWndFrom,	// handle of window to be mapped from
HWND hWndTo,	// handle of window to be mapped to
LPPOINT lpPoints,	// address of structure array with points to map
UINT cPoints	// number of structures in array
);
Parameters

hWndFrom

Identifies the window from which points are converted. If this parameter is NULL or HWND_DESKTOP, the points are presumed to be in screen coordinates.

hWndTo

Identifies the window to which points are converted. If this parameter is NULL or HWND_DESKTOP, the points are converted to screen coordinates.

lpPoints

Points to an array of POINT structures that contain the set of points to be converted. This parameter can also point to a RECT structure, in which case the cPoints parameter should be set to 2.

cPoints

Specifies the number of POINT structures in the array pointed to by the lpPoints parameter.

Return Values

If the function succeeds, the low-order word of the return value is the number of pixels added to the horizontal coordinate of each source point in order to compute the horizontal coordinate of each destination point; the high-order word is the number of pixels added to the vertical coordinate of each source point in order to compute the vertical coordinate of each destination point.

See Also

ClientToScreen, POINT, RECT, ScreenToClient


MaskBlt

The MaskBlt function combines the color data for the source and destination bitmaps using the specified mask and raster operation.

BOOL MaskBlt(

HDC hdcDest,	// handle of destination device context
int nXDest,	// x-coord. of upper-left corner of destination rectangle
int nYDest,	// y-coord. of upper-left corner of destination rectangle
int nWidth,	// width of source and destination rectangles
int nHeight,	// height of source and destination rectangles
HDC hdcSrc,	// handle of source device context
int nXSrc,	// x-coord. of upper-left corner of source rectangle
int nYSrc,	// y-coord. of upper-left corner of source rectangle
HBITMAP hbmMask,	// handle of monochrome bit mask
int xMask,	// horizontal pixel offset into the mask bitmap
int yMask,	// vertical pixel offset into the mask bitmap
DWORD dwRop	// raster operation code
);
Parameters

hdcDest

Identifies the destination device context.

nXDest

Specifies the logical x-coordinate of the upper-left corner of the destination rectangle.

nYDest

Specifies the logical y-coordinate of the upper-left corner of the destination rectangle.

nWidth

Specifies the width, in logical units, of the destination rectangle and source bitmap.

nHeight

Specifies the height, in logical units, of the destination rectangle and source bitmap.

hdcSrc

Identifies the device context from which the bitmap is to be copied. It must be zero if the dwRop parameter specifies a raster operation that does not include a source.

nXSrc

Specifies the logical x-coordinate of the upper-left corner of the source bitmap.

nYSrc

Specifies the logical y-coordinate of the upper-left corner of the source bitmap.

hbmMask

Identifies the monochrome mask bitmap combined with the color bitmap in the source device context.

xMask

Specifies the horizontal pixel offset for the mask bitmap specified by the hbmMask parameter.

yMask

Specifies the vertical pixel offset for the mask bitmap specified by the hbmMask parameter.

dwRop

Specifies both foreground and background ternary raster operation codes that the function uses to control the combination of source and destination data. The background raster operation code is stored in the high-order byte of the high-order word of this value; the foreground raster operation code is stored in the low-order byte of the high-order word of this value; the low-order word of this value is ignored, and should be zero. The macro MAKEROP4 creates such combinations of foreground and background raster operation codes.

For a discussion of foreground and background in the context of this function, see the following Remarks section.

For a list of common raster operation codes, see the BitBlt 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.

Remarks

A value of 1 in the mask specified by hbmMask indicates that the foreground raster operation code specified by dwRop should be applied at that location. A value of 0 in the mask indicates that the background raster operation code specified by dwRop should be applied at that location.

If the raster operations require a source, the mask rectangle must cover the source rectangle. If it does not, the function will fail. If the raster operations do not require a source, the mask rectangle must cover the destination rectangle. If it does not, the function will fail.

If a rotation or shear transformation is in effect for the source device context when this function is called, an error occurs. However, other types of transformation are allowed.

If the color formats of the source, pattern, and destination bitmaps differ, this function converts the pattern or source format, or both, to match the destination format.

If the mask bitmap is not a monochrome bitmap, an error occurs.

When an enhanced metafile is being recorded, an error occurs (and the function returns FALSE) if the source device context identifies an enhanced-metafile device context.

Not all devices support the MaskBlt function. An application should call the GetDeviceCaps function to determine whether a device supports this function.

If no mask bitmap is supplied, this function behaves exactly like BitBlt, using the foreground raster operation code.

The pixel offsets in the mask bitmap map to the point (0,0) in the source device context’s bitmap. This is useful in cases where a mask bitmap contains a set of masks; an application can easily apply any one of them to a mask-block transfer task by adjusting the pixel offsets and rectangle sizes sent to MaskBlt.

See Also

BitBlt, GetDeviceCaps, PlgBlt, StretchBlt


MenuHelp

The MenuHelp function processes WM_MENUSELECT and WM_COMMAND messages and displays help text about the current menu in the specified status window.

void MenuHelp(

UINT uMsg,
WPARAM wParam,
LPARAM lParam,
HMENU hMainMenu,
HINSTANCE hInst,
HWND hwndStatus,
UINT FAR *lpwIDs
);
Parameters

uMsg

WM_MENUSELECT or WM_COMMAND message.

wParam

First message parameter.

lParam

Second message parameter.

hMainMenu

Handle to the application’s main menu.

hInst

Handle to the module that contains the string resources.

hwndStatus

Handle to the status window.

lpwIDs

Pointer to an array that contains pairs of string resource identifiers and menu handles. The function searches the array for the handle to the selected menu and, if found, uses the corresponding resource identifier to load the appropriate help string.

Return Values

This function does not return a value.

See Also

WM_COMMAND, WM_MENUSELECT


MenuItemFromPoint [Now Supported on Windows NT]
MenuItemFromPoint

[Now Supported on Windows NT]

The MenuItemFromPoint function determines which menu item, if any, is at the specified location.

UINT WINAPI MenuItemFromPoint(

HWND hWnd,
HMENU hMenu,
POINT ptScreen
);
Parameters

hWnd

Handle to the window containing the menu.

hMenu

Handle to the menu containing the menu items to hit test.

ptScreen

POINT structure specifying the location to test. If hMenu specifies a menu bar, this parameter is in window coordinates. Otherwise, it is in client coordinates.

Return Values

Returns the zero-based position of the menu item at the specified location or −1 if no menu item is at the specified location.

See Also

POINT


MessageBeep

The MessageBeep function plays a waveform sound. The waveform sound for each sound type is identified by an entry in the [sounds] section of the registry.

BOOL MessageBeep(

UINT uType	// sound type
);
Parameters

uType

Specifies the sound type, as identified by an entry in the [sounds] section of the registry. This parameter can be one of the following values:

Value	Sound
0xFFFFFFFF	Standard beep using the computer speaker
MB_ICONASTERISK	SystemAsterisk
MB_ICONEXCLAMATION	SystemExclamation
MB_ICONHAND	SystemHand
MB_ICONQUESTION	SystemQuestion
MB_OK	SystemDefault
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.

Remarks

After queuing the sound, the MessageBeep function returns control to the calling function and plays the sound asynchronously.

If it cannot play the specified alert sound, MessageBeep attempts to play the system default sound. If it cannot play the system default sound, the function produces a standard beep sound through the computer speaker.

The user can disable the warning beep by using the Control Panel Sound application.

See Also

FlashWindow, MessageBox


MessageBox

The MessageBox function creates, displays, and operates a message box. The message box contains an application-defined message and title, plus any combination of predefined icons and push buttons.

int MessageBox(

HWND hWnd,	// handle of owner window
LPCTSTR lpText,	// address of text in message box
LPCTSTR lpCaption,	// address of title of message box
UINT uType	// style of message box
);
Parameters

hWnd

Identifies the owner window of the message box to be created. If this parameter is NULL, the message box has no owner window.

lpText

Points to a null-terminated string containing the message to be displayed.

lpCaption

Points to a null-terminated string used for the dialog box title. If this parameter is NULL, the default title Error is used.

uType

Specifies a set of bit flags that determine the contents and behavior of the dialog box. This parameter can be a combination of flags from the following groups of flags.

Specify one of the following flags to indicate the buttons contained in the message box:

Flag	Meaning
MB_ABORTRETRYIGNORE	The message box contains three push buttons: Abort, Retry, and Ignore.
MB_OK	The message box contains one push button: OK. This is the default.
MB_OKCANCEL	The message box contains two push buttons: OK and Cancel.
MB_RETRYCANCEL	The message box contains two push buttons: Retry and Cancel.
MB_YESNO	The message box contains two push buttons: Yes and No.
MB_YESNOCANCEL	The message box contains three push buttons: Yes, No, and Cancel.
Specify one of the following flags to display an icon in the message box:

Flag	Meaning
MB_ICONEXCLAMATION,  MB_ICONWARNING	An exclamation-point icon appears in the message box.
MB_ICONINFORMATION, MB_ICONASTERISK	An icon consisting of a lowercase letter i in a circle appears in the message box.
MB_ICONQUESTION	A question-mark icon appears in the message box.
MB_ICONSTOP,  MB_ICONERROR,  MB_ICONHAND	A stop-sign icon appears in the message box.
Specify one of the following flags to indicate the default button:

Flag	Meaning
MB_DEFBUTTON1	The first button is the default button.  MB_DEFBUTTON1 is the default unless MB_DEFBUTTON2, MB_DEFBUTTON3, or MB_DEFBUTTON4 is specified.
MB_DEFBUTTON2	The second button is the default button.
MB_DEFBUTTON3	The third button is the default button.
MB_DEFBUTTON4	The fourth button is the default button.
Specify one of the following flags to indicate the modality of the dialog box:

Flag	Meaning
MB_APPLMODAL	The user must respond to the message box before continuing work in the window identified by the hWnd parameter. However, the user can move to the windows of other applications and work in those windows.  Depending on the hierarchy of windows in the application, the user may be able to move to other windows within the application. All child windows of the parent of the message box are automatically disabled, but popup windows are not. MB_APPLMODAL is the default if neither MB_SYSTEMMODAL nor MB_TASKMODAL is specified.
MB_SYSTEMMODAL	Same as MB_APPLMODAL except that the message box has the WS_EX_TOPMOST style. Use system-modal message boxes to notify the user of serious, potentially damaging errors that require immediate attention (for example, running out of memory). This flag has no effect on the user's ability to interact with windows other than those associated with hWnd.
MB_TASKMODAL	Same as MB_APPLMODAL except that all the top-level windows belonging to the current task are disabled if the hWnd parameter is NULL. Use this flag when the calling application or library does not have a window handle available but still needs to prevent input to other windows in the current application without suspending other applications.
In addition, you can specify the following flags:

MB_DEFAULT_DESKTOP_ONLY

The desktop currently receiving input must be a default desktop; otherwise, the function fails. A default desktop is one an application runs on after the user has logged on.

MB_HELP

Adds a Help button to the message box. Choosing the Help button or pressing F1 generates a Help event.

MB_RIGHT

The text is right-justified.

MB_RTLREADING

Displays message and caption text using right-to-left reading order on Hebrew and Arabic systems.

MB_SETFOREGROUND

The message box becomes the foreground window. Internally, Windows calls the SetForegroundWindow function for the message box.

MB_TOPMOST

The message box is created with the WS_EX_TOPMOST window style.

MB_SERVICE_NOTIFICATION

Windows NT only: The caller is a service notifying the user of an event. The function displays a message box on the current active desktop, even if there is no user logged on to the computer.

If this flag is set, the hWnd parameter must be NULL. This is so the message box can appear on a desktop other than the desktop corresponding to the hWnd.

For Windows NT version 4.0, the value of MB_SERVICE_NOTIFICATION has changed. See WINUSER.H for the old and new values. Windows NT 4.0 provides backward compatibility for pre-existing services by mapping the old value to the new value in the implementation of MessageBox and MessageBoxEx. This mapping is only done for executables that have a version number, as set by the linker, less than 4.0.

To build a service that uses MB_SERVICE_NOTIFICATION, and can run on both Windows NT 3.x and Windows NT 4.0, you have two choices.

1.	At link-time, specify a version number less than 4.0; or

2.	At link-time, specify version 4.0. At run-time, use the GetVersionEx function to check the system version. Then when running on Windows NT 3.x, use MB_SERVICE_NOTIFICATION_NT3X; and on Windows NT 4.0, use MB_SERVICE_NOTIFICATION.

MB_SERVICE_NOTIFICATION_NT3X

Windows NT only: This value corresponds to the value defined for MB_SERVICE_NOTIFICATION for Windows NT version 3.51.

Return Values

The return value is zero if there is not enough memory to create the message box.

If the function succeeds, the return value is one of the following menu-item values returned by the dialog box:

Value	Meaning
IDABORT	Abort button was selected.
IDCANCEL	Cancel button was selected.
IDIGNORE	Ignore button was selected.
IDNO	No button was selected.
IDOK	OK button was selected.
IDRETRY	Retry button was selected.
IDYES	Yes button was selected.
If a message box has a Cancel button, the function returns the IDCANCEL value if either the ESC key is pressed or the Cancel button is selected. If the message box has no Cancel button, pressing ESC has no effect.

Remarks

When you use a system-modal message box to indicate that the system is low on memory, the strings pointed to by the lpText and lpCaption parameters should not be taken from a resource file, because an attempt to load the resource may fail.

When an application calls MessageBox and specifies the MB_ICONHAND and MB_SYSTEMMODAL flags for the uType parameter, Windows displays the resulting message box regardless of available memory. When these flags are specified, Windows limits the length of the message box text to three lines. Windows does not automatically break the lines to fit in the message box, however, so the message string must contain carriage returns to break the lines at the appropriate places.

If you create a message box while a dialog box is present, use the handle of the dialog box as the hWnd parameter. The hWnd parameter should not identify a child window, such as a control in a dialog box.

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

FlashWindow, MessageBeep, MessageBoxEx, MessageBoxIndirect, SetForegroundWindow


MessageBoxEx

The MessageBoxEx function creates, displays, and operates a message box. The message box contains an application-defined message and title, plus any combination of predefined icons and push buttons. The wLanguageId parameter specifies which set of language resources is used for the predefined push buttons. For full descriptions of the other parameters of MessageBoxEx, see  MessageBox .

int MessageBoxEx(

HWND hWnd,	// handle of owner window
LPCTSTR lpText,	// address of text in message box
LPCTSTR lpCaption,	// address of title of message box
UINT uType,	// style of message box
WORD wLanguageId	// language identifier
);
Parameters

hWnd

Identifies the owner window of the message box to be created. If this parameter is NULL, the message box has no owner window.

lpCaption

Points to a null-terminated string containing the message to be displayed.

lpszTitle

Points to a null-terminated string used for the dialog box title. If this parameter is NULL, the default title Error is used.

uType

Specifies a set of bit flags that determine the contents and behavior of the dialog box. This parameter can be a combination of flags from the following groups of flags.

Specify one of the following flags to indicate the buttons contained in the message box:

Flag	Meaning
MB_ABORTRETRYIGNORE	The message box contains three push buttons: Abort, Retry, and Ignore.
MB_OK	The message box contains one push button: OK. This is the default.
MB_OKCANCEL	The message box contains two push buttons: OK and Cancel.
MB_RETRYCANCEL	The message box contains two push buttons: Retry and Cancel.
MB_YESNO	The message box contains two push buttons: Yes and No.
MB_YESNOCANCEL	The message box contains three push buttons: Yes, No, and Cancel.
Specify one of the following flags to display an icon in the message box:

Flag	Meaning
MB_ICONEXCLAMATION,  MB_ICONWARNING	An exclamation-point icon appears in the message box.
MB_ICONINFORMATION, MB_ICONASTERISK	An icon consisting of a lowercase letter i in a circle appears in the message box.
MB_ICONQUESTION	A question-mark icon appears in the message box.
MB_ICONSTOP,  MB_ICONERROR,  MB_ICONHAND	A stop-sign icon appears in the message box.
Specify one of the following flags to indicate the default button:

Flag	Meaning
MB_DEFBUTTON1	The first button is the default button.  MB_DEFBUTTON1 is the default unless MB_DEFBUTTON2, MB_DEFBUTTON3, or MB_DEFBUTTON4 is specified.
MB_DEFBUTTON2	The second button is the default button.
MB_DEFBUTTON3	The third button is the default button.
MB_DEFBUTTON4	The fourth button is the default button.
Specify one of the following flags to indicate the modality of the dialog box:

Flag	Meaning
MB_APPLMODAL	The user must respond to the message box before continuing work in the window identified by the hWnd parameter. However, the user can move to the windows of other applications and work in those windows.  Depending on the hierarchy of windows in the application, the user may be able to move to other windows within the application. All child windows of the parent of the message box are automatically disabled, but popup windows are not. MB_APPLMODAL is the default if neither MB_SYSTEMMODAL nor MB_TASKMODAL is specified.
MB_SYSTEMMODAL	Same as MB_APPLMODAL except that the message box has the WS_EX_TOPMOST style. Use system-modal message boxes to notify the user of serious, potentially damaging errors that require immediate attention (for example, running out of memory). This flag has no effect on the user's ability to interact with windows other than those associated with hWnd.
MB_TASKMODAL	Same as MB_APPLMODAL except that all the top-level windows belonging to the current task are disabled if the hWnd parameter is NULL. Use this flag when the calling application or library does not have a window handle available but still needs to prevent input to other windows in the current application without suspending other applications.
In addition, you can specify the following flags:

MB_DEFAULT_DESKTOP_ONLY

The desktop currently receiving input must be a default desktop; otherwise, the function fails. A default desktop is one an application runs on after the user has logged on.

MB_HELP

Adds a Help button to the message box. Choosing the Help button or pressing F1 generates a Help event.

MB_RIGHT

The text is right-justified.

MB_RTLREADING

Displays message and caption text using right-to-left reading order on Hebrew and Arabic systems.

MB_SETFOREGROUND

The message box becomes the foreground window. Internally, Windows calls the SetForegroundWindow function for the message box.

MB_TOPMOST

The message box is created with the WS_EX_TOPMOST window style.

MB_SERVICE_NOTIFICATION

Windows NT only: The caller is a service notifying the user of an event. The function displays a message box on the current active desktop, even if there is no user logged on to the computer.

If this flag is set, the hWnd parameter must be NULL. This is so the message box can appear on a desktop other than the desktop corresponding to the hWnd.

For Windows NT version 4.0, the value of MB_SERVICE_NOTIFICATION has changed. See WINUSER.H for the old and new values. Windows NT 4.0 provides backward compatibility for pre-existing services by mapping the old value to the new value in the implementation of MessageBox and MessageBoxEx. This mapping is only done for executables that have a version number, as set by the linker, less than 4.0.

To build a service that uses MB_SERVICE_NOTIFICATION, and can run on both Windows NT 3.x and Windows NT 4.0, you have two choices.

1.	At link-time, specify a version number less than 4.0; or

2.	At link-time, specify version 4.0. At run-time, use the GetVersionEx function to check the system version. Then when running on Windows NT 3.x, use MB_SERVICE_NOTIFICATION_NT3X; and on Windows NT 4.0, use MB_SERVICE_NOTIFICATION.

MB_SERVICE_NOTIFICATION_NT3X

Windows NT only: This value corresponds to the value defined for MB_SERVICE_NOTIFICATION for Windows NT version 3.51.

wLanguageId

Specifies the language in which to display the text contained in the predefined push buttons. This value must be in the form returned by the MAKELANGID macro.

For a list of the language identifiers supported by Win32, see Language Identifiers. Note that each localized release of Windows typically contains resources only for a limited set of languages. Thus, for example, the U.S. version offers LANG_ENGLISH, the French version offers LANG_FRENCH, the German version offers LANG_GERMAN, and the Japanese version offers LANG_JAPANESE. Each version offers LANG_NEUTRAL. This limits the set of values that can be used with the wLanguageId parameter. Before specifying a language identifier, you should enumerate the locales that are installed on a system.

Return Values

If the function succeeds, the return value is a nonzero menu-item value returned by the dialog box.

Value	Meaning
IDABORT	Abort button was selected.
IDCANCEL	Cancel button was selected.
IDIGNORE	Ignore button was selected.
IDNO	No button was selected.
IDOK	OK button was selected.
IDRETRY	Retry button was selected.
IDYES	Yes button was selected.
If a message box has a Cancel button, the function returns the IDCANCEL value when either the ESC key or Cancel button is pressed. If the message box has no Cancel button, pressing the ESC key has no effect.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

When you create a system-modal message box to indicate that the system is low on memory, the strings passed as the lpText and lpCaption parameters should not be taken from a resource file, because an attempt to load the resource may fail.

When an application calls the MessageBoxEx function and specifies the MB_ICONHAND and MB_SYSTEMMODAL flags for the uType parameter, the Win32 API displays the resulting message box regardless of available memory. When you specify these flags, Windows limits the length of the message-box text to one line.

If you create a message box while a dialog box is present, use the handle of the dialog box as the hWnd parameter. The hWnd parameter should not identify a child window, such as a dialog box.

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

MAKELANGID, MessageBeep, MessageBox, MessageBoxIndirect, SetForegroundWindow


MessageBoxIndirect [Now Supported on Windows NT]
MessageBoxIndirect

[Now Supported on Windows NT]

The MessageBoxIndirect function creates, displays, and operates a message box. The message box contains application-defined message text and title, any icon, and any combination of predefined push buttons.

int MessageBoxIndirect(

LPMSGBOXPARAMS lpMsgBoxParams	// address of structure for message box parameters
);
Parameters

lpMsgBoxParams

Pointer to a MSGBOXPARAMS structure that contains information used to display the message box.

Return Values

The return value is zero if there is not enough memory to create the message box.

If the function succeeds, the return value is one of the following menu-item values returned by the dialog box:

Value	Meaning
IDABORT	Abort button was selected.
IDCANCEL	Cancel button was selected.
IDIGNORE	Ignore button was selected.
IDNO	No button was selected.
IDOK	OK button was selected.
IDRETRY	Retry button was selected.
IDYES	Yes button was selected.
If a message box has a Cancel button, the function returns the IDCANCEL value if either the ESC key is pressed or the Cancel button is selected. If the message box has no Cancel button, pressing ESC has no effect.

Remarks

When you use a system-modal message box to indicate that the system is low on memory, the strings pointed to by the lpszText and lpszCaption members of the MSGBOXPARAMS structure should not be taken from a resource file, because an attempt to load the resource may fail.

When an application calls MessageBoxIndirect and specifies the MB_ICONHAND and MB_SYSTEMMODAL flags for the dwStyle member of the MSGBOXPARAMS structure, Windows displays the resulting message box regardless of available memory. When these flags are specified, Windows limits the length of the message box text to three lines. Windows does not automatically break the lines to fit in the message box, however, so the message string must contain carriage returns to break the lines at the appropriate places.

If you create a message box while a dialog box is present, use the handle of the dialog box as the hWnd parameter. The hWnd parameter should not identify a child window, such as a control in a dialog box.

Windows 95: The system can support a maximum of 16,364 window handles.

See Also

MessageBox, MessageBoxEx, MSGBOXPARAMS


MessageProc

The MessageProc hook procedure is an application-defined callback function the system calls after an input event occurs in a dialog box, message box, menu, or scroll bar, but before the message generated by the input event is processed. The hook procedure can monitor messages for a dialog box, message box, menu, or scroll bar created by a particular application or all applications.

LRESULT CALLBACK MessageProc(

int code,	// hook code
WPARAM wParam,	// undefined
LPARAM lParam	// address of structure with message data
);
Parameters

code

Specifies the type of input event that generated the message. This parameter can be one of the following values:

Value	Meaning
MSGF_DDEMGR	The input event occurred while the Dynamic Data Exchange Management Library (DDEML) was waiting for a synchronous transaction to finish. For more information about DDEML, see Dynamic Data Exchange Management Library.
MSGF_DIALOGBOX	The input event occurred in a message box or dialog box.
MSGF_MENU	The input event occurred in a menu.
MSGF_NEXTWINDOW	The input event occurred as a result of the user’s pressing the ALT+TAB key combination to activate a different window.
MSGF_SCROLLBAR	The input event occurred in a scroll bar.
If code is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and return the value returned by CallNextHookEx.

wParam

Specifies a NULL value.

lParam

Points to an MSG structure.

Return Values

If the hook procedure processes the message, the return value must be a nonzero value. Otherwise, it must be zero.

Remarks

An application installs the hook procedure by specifying the WH_MSGFILTER hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

If an application that uses the DDEML and performs synchronous transactions must process messages before they are dispatched, it must use the WH_MSGFILTER hook.

MessageProc is a placeholder for the application-defined function name.

See Also

CallNextHookEx, SetWindowsHookEx, MSG


ModifyMenu

The ModifyMenu function changes an existing menu item. This function is used to specify the content, appearance, and behavior of the menu item.

The ModifyMenu function has been superseded by the SetMenuItemInfo function. You can still use ModifyMenu, however, if you do not need any of the extended features of SetMenuItemInfo.

BOOL ModifyMenu(

HMENU hMnu,	// handle of menu
UINT uPosition,	// menu item to modify
UINT uFlags,	// menu item flags
UINT uIDNewItem,	// menu item identifier or handle of drop-down menu or submenu
LPCTSTR lpNewItem	// menu item content
);
Parameters

hMnu

Identifies the menu to be changed.

uPosition

Specifies the menu item to be changed, as determined by the uFlags parameter.

uFlags

Specifies flags that control the interpretation of the uPosition parameter and the content, appearance, and behavior of the menu item. This parameter must be a combination of one of the following required values and at least one of the values listed in the following Remarks section.

Value	Meaning
MF_BYCOMMAND	Indicates that the uPosition parameter gives the identifier of the menu item. The MF_BYCOMMAND flag is the default if neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified.
MF_BYPOSITION	Indicates that the uPosition parameter gives the zero-based relative position of the menu item.
uIDNewItem

Specifies either the identifier of the modified menu item or, if the uFlags parameter has the MF_POPUP flag set, the handle of the drop-down menu or submenu.

lpNewItem

Points to the content of the changed menu item. The interpretation of this parameter depends on whether the uFlags parameter includes the MF_BITMAP, MF_OWNERDRAW, or MF_STRING flag.

Value	Meaning
MF_BITMAP	Contains a bitmap handle.
MF_OWNERDRAW	Contains a 32-bit value supplied by an application that is used to maintain additional data related to the menu item. The value is in the itemData member of the structure pointed to by the lparam parameter of the WM_MEASUREITEM or WM_DRAWITEM messages sent when the menu item is created or its appearance is updated.
MF_STRING	Contains a pointer to a null-terminated string (the default).
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.

Remarks

If ModifyMenu replaces a menu item that opens a drop-down menu or submenu, the function destroys the old drop-down menu or submenu and frees the memory used by it.

The application must call the DrawMenuBar function whenever a menu changes, whether or not the menu is in a displayed window. To change the attributes of existing menu items, it is much faster to use the CheckMenuItem and EnableMenuItem functions.

The following list describes the flags that may be set in the uFlags parameter:

Value	Meaning
MF_BITMAP	Uses a bitmap as the menu item. The lpNewItem parameter contains the handle of the bitmap.
MF_BYCOMMAND	Indicates that the uPosition parameter specifies the identifier of the menu item (the default).
MF_BYPOSITION	Indicates that the uPosition parameter specifies the zero-based relative position of the new menu item.
MF_CHECKED	Places a check mark next to the item. If your application provides check mark bitmaps (see the SetMenuItemBitmaps function), this flag displays a checked bitmap next to the menu item.
MF_DISABLED	Disables the menu item so that it cannot be selected, but this flag does not gray it.
MF_ENABLED	Enables the menu item so that it can be selected and restores it from its grayed state.
MF_GRAYED	Disables the menu item and grays it so that it cannot be selected.
MF_MENUBARBREAK	Functions the same as the MF_MENUBREAK flag for a menu bar. For a drop-down menu, submenu, or shortcut menu, the new column is separated from the old column by a vertical line.
MF_MENUBREAK	Places the item on a new line (for menu bars) or in a new column (for a drop-down menu, submenu, or shortcut menu) without separating columns.
MF_OWNERDRAW	Specifies that the item is an owner-drawn item. Before the menu is displayed for the first time, the window that owns the menu receives a WM_MEASUREITEM message to retrieve the width and height of the menu item. The WM_DRAWITEM message is then sent to the window procedure of the owner window whenever the appearance of the menu item must be updated.
MF_POPUP	Specifies that the menu item opens a drop-down menu or submenu. The uIDNewItem parameter specifies the handle of the drop-down menu or submenu. This flag is used to add a menu name to a menu bar or a menu item that opens a submenu to a drop-down menu, submenu, or shortcut menu.
MF_SEPARATOR	Draws a horizontal dividing line. This flag is used only in a drop-down menu, submenu, or shortcut menu. The line cannot be grayed, disabled, or highlighted. The lpNewItem and uIDNewItem parameters are ignored.
MF_STRING	Specifies that the menu item is a text string; the lpNewItem parameter points to the string.
MF_UNCHECKED	Does not place a check mark next to the item (the default). If your application supplies check mark bitmaps (see the SetMenuItemBitmaps function), this flag displays an unchecked bitmap next to the menu item.
The following groups of flags cannot be used together:

•	MF_BYCOMMAND and MF_BYPOSITION

•	MF_DISABLED, MF_ENABLED, and MF_GRAYED

•	MF_BITMAP, MF_STRING, MF_OWNERDRAW, and MF_SEPARATOR

•	MF_MENUBARBREAK and MF_MENUBREAK

•	MF_CHECKED and MF_UNCHECKED

See Also

AppendMenu, CheckMenuItem, DrawMenuBar, EnableMenuItem, SetMenuItemBitmaps, SetMenuItemInfo, WM_DRAWITEM, WM_MEASUREITEM


ModifyWorldTransform

The ModifyWorldTransform function changes the world transformation for a device context using the specified mode.

BOOL ModifyWorldTransform(

HDC hdc,	// handle of device context
CONST XFORM *lpXform,	// address of transformation data
DWORD iMode	// modification mode
);
Parameters

hdc

Specifies the device context.

lpXform

Points to an XFORM structure used to modify the world transformation for the given device context.

iMode

Specifies how the transformation data modifies the current world transformation. This parameter must be one of the following values:

Value	Description
MWT_IDENTITY	Resets the current world transformation by using the identity matrix. If this mode is specified, the XFORM structure pointed to by lpXform is ignored.
MWT_LEFTMULTIPLY	Multiplies the current transformation by the data in the XFORM structure. (The data in the XFORM structure becomes the left multiplicand, and the data for the current transformation becomes the right multiplicand.)
MWT_RIGHTMULTIPLY	Multiplies the current transformation by the data in the XFORM structure. (The data in the XFORM structure becomes the right multiplicand, and the data for the current transformation becomes the left multiplicand.)
Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The ModifyWorldTransform function will fail unless graphics mode for the specified device context has been set to GM_ADVANCED by previously calling the SetGraphicsMode function. Likewise, it will not be possible to reset the graphics mode for the device context to the default GM_COMPATIBLE mode, unless world transform has first been reset to the default identity transform by calling SetWorldTransform or ModifyWorldTransform.

See Also

GetWorldTransform, SetWorldTransform, SetGraphicsMode, XFORM


mouse_event

The mouse_event function synthesizes mouse motion and button clicks.

VOID mouse_event(

DWORD dwFlags,	// flags specifying various motion/click variants
DWORD dx,	// horizontal mouse position or position change
DWORD dy,	// vertical mouse position or position change
DWORD dwData,	// amount of wheel movement
DWORD dwExtraInfo	// 32 bits of application-defined information
);
Parameters

dwFlags

A set of flag bits that specify various aspects of mouse motion and button clicking. The bits in this parameter can be any reasonable combination of the following values:

Value	Meaning
MOUSEEVENTF_ABSOLUTE	Specifies that the dx and dy parameters contain normalized absolute coordinates. If not set, those parameters contain relative data: the change in position since the last reported position. This flag can be set, or not set, regardless of what kind of mouse or mouse-like device, if any, is connected to the system. For further information about relative mouse motion, see the following Remarks section.
MOUSEEVENTF_MOVE	Specifies that movement occurred.
MOUSEEVENTF_LEFTDOWN	Specifies that the left button changed to down.
MOUSEEVENTF_LEFTUP	Specifies that the left button changed to up.
MOUSEEVENTF_RIGHTDOWN	Specifies that the right button changed to down.
MOUSEEVENTF_RIGHTUP	Specifies that the right button changed to up.
MOUSEEVENTF_MIDDLEDOWN	Specifies that the middle button changed to down.
MOUSEEVENTF_MIDDLEUP	Specifies that the middle button changed to up.
MOUSEEVENTF_WHEEL	Windows NT only: Specifies that the wheel has been moved, if the mouse has a wheel. The amount of movement is given in dwData
The flag bits that specify mouse button status are set to indicate changes in status, not ongoing conditions. For example, if the left mouse button is pressed and held down, MOUSEEVENTF_LEFTDOWN is set when the left button is first pressed, but not for subsequent motions. Similarly, MOUSEEVENTF_LEFTUP is set only when the button is first released.

dx

Specifies the mouse’s absolute position along the x-axis or its amount of motion since the last mouse event was generated, depending on the setting of MOUSEEVENTF_ABSOLUTE. Absolute data is given as the mouse’s actual x-coordinate; relative data is given as the number of mickeys moved.

dy

Specifies the mouse’s absolute position along the y-axis or its amount of motion since the last mouse event was generated, depending on the setting of MOUSEEVENTF_ABSOLUTE. Absolute data is given as the mouse’s actual y-coordinate; relative data is given as the number of mickeys moved.

dwData

If dwFlags is MOUSEEVENTF_WHEEL, then dwData specifies the amount of wheel movement. A positive value indicates that the wheel was rotated forward, away from the user; a negative value indicates that the wheel was rotated backward, toward the user. One wheel click is defined as WHEEL_DELTA, which is 120.

If dwFlags is not MOUSEEVENTF_WHEEL, then dwData should be zero.

dwExtraInfo

Specifies an additional 32-bit value associated with the mouse event. An application calls GetMessageExtraInfo to obtain this extra information.

Return Values

This function has no return value.

Remarks

If the mouse has moved, indicated by MOUSEEVENTF_MOVE being set, dx and dy hold information about that motion. The information is given as absolute or relative integer values.

If MOUSEEVENTF_ABSOLUTE value is specified, dx and dy contain normalized absolute coordinates between 0 and 65,535. The event procedure maps these coordinates onto the display surface. Coordinate (0,0) maps onto the upper-left corner of the display surface, (65535,65535) maps onto the lower-right corner.

If the MOUSEEVENTF_ABSOLUTE value is not specified, dx and dy specify relative motions from when the last mouse event was generated (the last reported position). Positive values mean the mouse moved right (or down); negative values mean the mouse moved left (or up).

Relative mouse motion is subject to the effects of the mouse speed and the two mouse threshold values. In Windows NT, an end user sets these three values with the Mouse Tracking Speed slider of Control Panel’s Mouse option; in Windows 95, an end user sets them with the Pointer Speed slider of the Control Panel’s Mouse property sheet. An application obtains and sets these values with the SystemParametersInfo function.

The operating system applies two tests to the specified relative mouse motion. If the specified distance along either the x or y axis is greater than the first mouse threshold value, and the mouse speed is not zero, the operating system doubles the distance. If the specified distance along either the x or y axis is greater than the second mouse threshold value, and the mouse speed is equal to two, the operating system doubles the distance that resulted from applying the first threshold test. It is thus possible for the operating system to multiply relatively-specified mouse motion along the x or y axis by up to four times.

The mouse_event function is used to synthesize mouse events by applications that need to do so. It is also used by applications that need to obtain more information from the mouse than its position and button state. For example, if a tablet manufacturer wants to pass pen-based information to its own applications, it can write a dynamic-link library (DLL) that communicates directly to the tablet hardware, obtains the extra information, and saves it in a queue. The DLL then calls mouse_event with the standard button and x/y position data, along with, in the dwExtraInfo parameter, some pointer or index to the queued extra information. When the application needs the extra information, it calls the DLL with the pointer or index stored in dwExtraInfo, and the DLL returns the extra information.

See Also

GetMessageExtraInfo, SystemParametersInfo


MouseProc

The MouseProc hook procedure is an application-defined or library-defined callback function the system calls whenever an application calls the GetMessage or PeekMessage function and there is a mouse message to be processed.

LRESULT CALLBACK MouseProc(

int nCode,	// hook code
WPARAM wParam,	// message identifier
LPARAM lParam	// mouse coordinates
);
Parameters

nCode

Specifies a code the hook procedure uses to determine how to process the message. This parameter can be one of the following values:

Value	Meaning
HC_ACTION	The wParam and lParam parameters contain information about a mouse message.
HC_NOREMOVE	The wParam and lParam parameters contain information about a mouse message, and the mouse message has not been removed from the message queue. (An application called the PeekMessage function, specifying the PM_NOREMOVE flag.)
If nCode is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies the identifier of the mouse message.

lParam

Points to a MOUSEHOOKSTRUCT structure.

Return Values

To enable the system to process the message, the return value must be zero. To discard the message, the return value must be a nonzero value.

Remarks

The hook procedure must not install a JournalPlaybackProc callback function.

An application installs the hook procedure by specifying the WH_MOUSE hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

MouseProc is a placeholder for the application-defined or library-defined function name.

See Also

CallNextHookEx, GetMessage, JournalPlaybackProc, MOUSEHOOKSTRUCT, PeekMessage, SetWindowsHookEx


MoveFile

The MoveFile function renames an existing file or a directory (including all its children).

BOOL MoveFile(

LPCTSTR lpExistingFileName,	// address of name of the existing file
LPCTSTR lpNewFileName	// address of new name for the file
);
Parameters

lpExistingFileName

Points to a null-terminated string that names an existing file or directory.

lpNewFileName

Points to a null-terminated string that specifies the new name of a file or directory. The new name must not already exist. A new file may be on a different file system or drive. A new directory must be on the same drive.

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.

Remarks

The MoveFile function will move (rename) either a file or a directory (including all its children) either in the same directory or across directories. The one caveat is that the MoveFile function will fail on directory moves when the destination is on a different volume.

See Also

CopyFile, MoveFileEx


MoveFileEx

The MoveFileEx function renames an existing file or directory.

BOOL MoveFileEx(

LPCTSTR lpExistingFileName,	// address of name of the existing file
LPCTSTR lpNewFileName,	// address of new name for the file
DWORD dwFlags	// flag to determine how to move file
);
Parameters

lpExistingFileName

Points to a null-terminated string that names an existing file or directory.

lpNewFileName

Points to a null-terminated string that specifies the new name of lpExistingFileName.

When moving a file, the destination can be on a different file system or drive. If the destination is on another drive, you must set the MOVEFILE_COPY_ALLOWED flag in dwFlags.

When moving a directory, the destination must be on the same drive.

Windows NT:

If dwFlags specifies MOVEFILE_DELAY_UNTIL_REBOOT, lpNewFileName can be NULL. In this case, MoveFileEx registers the lpExistingFileName file to be deleted when the system reboots.

dwFlags

A set of bit flags that specify how to move the file. You can specify any combination of the following values:

Value	Meaning
MOVEFILE_COPY_ALLOWED
	If the file is to be moved to a different volume, the function simulates the move by using the CopyFile and DeleteFile functions. Cannot be combined with the MOVEFILE_DELAY_UNTIL_REBOOT flag.
MOVEFILE_DELAY_UNTIL_REBOOT
	Windows NT only: The function does not move the file until the operating system is restarted. The system moves the file immediately after AUTOCHK is executed, but before creating any paging files. Consequently, this parameter enables the function to delete paging files from previous startups.
MOVEFILE_REPLACE_EXISTING
	If a file of the name specified by lpNewFileName already exists, the function replaces its contents with those specified by lpExistingFileName.
MOVEFILE_WRITE_THROUGH
	Windows NT only: The function does not return until the file has actually been moved on the disk.  Setting this flag guarantees that a move perfomed as a copy and delete operation is flushed to disk before the function returns. The flush occurs at the end of the copy operation.  This flag has no effect if the MOVEFILE_DELAY_UNTIL_REBOOT flag is set.
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.

Remarks

An application cannot specify both MOVEFILE_DELAY_UNTIL_REBOOT and MOVEFILE_COPY_ALLOWED for dwFlags. Function calls that do so will fail.

Windows NT:

If the dwFlags parameter specifies MOVEFILE_DELAY_UNTIL_REBOOT, MoveFileEx stores the locations of the files to be renamed at reboot under the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\
Control\Session Manager\PendingFileRenameOperations

The key is of type REG_MULTI_SZ. Each rename operation is a pair of NULL-terminated strings. The system uses these registry entries to complete the operation at reboot in the same order that they were issued.

For example, on Windows NT, the following code fragment creates registry entries that delete szDstFile and rename szSrcFile to be szDstFile at reboot:

MoveFileEx(szDstFile, NULL, MOVEFILE_DELAY_UNTIL_REBOOT);

MoveFileEx(szSrcFile, szDstFile, MOVEFILE_DELAY_UNTIL_REBOOT);

The system creates the associated PendingFileRenameOperations entries as follows:

szDstFile\0\0

szSrcFile\0szDstFile\0\0

Windows 95:

The MOVEFILE_DELAY_UNTIL_REBOOT flag is not supported. To rename or delete a file at reboot on a Windows 95 system, place an entry in the WININIT.INI file in the Windows directory.

For example, on Windows 95, the following code fragment creates WININIT.INI entries that delete szDstFile and rename szSrcFile to be szDstFile at reboot:

GetWindowsDirectory(szWinInitFile, uSize);

lstrcat(szWinInitFile, "\\WININIT.INI");

WritePrivateProfileString("Rename", "NUL", szDstFile, szWinInitFile);

WritePrivateProfileString("Rename", szDstFile, szSrcFile, szWinInitFile);

See Also

CopyFile, DeleteFile, GetWindowsDirectory, lstrcat, MoveFile, WritePrivateProfileString


MoveMemory

The MoveMemory function moves a block of memory from one location to another.

VOID MoveMemory (

PVOID Destination,	// address of move destination
CONST VOID *Source,	// address of block to move
DWORD Length	// size, in bytes, of block to move
);
Parameters

Destination

Points to the starting address of the destination of the move.

Source

Points to the starting address of the block of memory to move.

Length

Specifies the size, in bytes, of the block of memory to move.

Return Values

This function has no return value.

Remarks

The source and destination blocks may overlap.

See Also

CopyMemory, FillMemory, ZeroMemory


MoveToEx

The MoveToEx function updates the current position to the specified point and optionally returns the previous position.

BOOL MoveToEx(

HDC hdc,	// handle of device context
int X,	// x-coordinate of new current position
int Y,	// y-coordinate of new current position
LPPOINT lpPoint	// address of old current position
);
Parameters

hdc

Identifies a device context.

X

Specifies the x-coordinate of the new position, in logical units.

Y

Specifies the y-coordinate of the new position, in logical units.

lpPoint

Points to a POINT structure in which the previous current position is stored. If this parameter is a NULL pointer, the previous position is not returned.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The MoveToEx function affects all drawing functions.

See Also

AngleArc, LineTo, POINT, PolyBezierTo, PolylineTo


MoveWindow

The MoveWindow function changes the position and dimensions of the specified window. For a top-level window, the position and dimensions are relative to the upper-left corner of the screen. For a child window, they are relative to the upper-left corner of the parent window’s client area.

BOOL MoveWindow(

HWND hWnd,	// handle of window
int X,	// horizontal position
int Y,	// vertical position
int nWidth,	// width
int nHeight,	// height
BOOL bRepaint	// repaint flag
);
Parameters

hWnd

Identifies the window.

X

Specifies the new position of the left side of the window.

Y

Specifies the new position of the top of the window.

nWidth

Specifies the new width of the window.

nHeight

Specifies the new height of the window.

bRepaint

Specifies whether the window is to be repainted. If this parameter is TRUE, the window receives a WM_PAINT message. If the parameter is FALSE, no repainting of any kind occurs. This applies to the client area, the nonclient area (including the title bar and scroll bars), and any part of the parent window uncovered as a result of moving a child window. If this parameter is FALSE, the application must explicitly invalidate or redraw any parts of the window and parent window that need redrawing.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

If the bRepaint parameter is TRUE, Windows sends the WM_PAINT message to the window procedure immediately after moving the window (that is, the MoveWindow function calls the UpdateWindow function). If bRepaint is FALSE, Windows places the WM_PAINT message in the message queue associated with the window. The message loop dispatches the WM_PAINT message only after dispatching all other messages in the queue.

MoveWindow sends WM_WINDOWPOSCHANGING, WM_WINDOWPOSCHANGED, WM_MOVE, WM_SIZE, and WM_NCCALCSIZE messages to the window.

See Also

SetWindowPos, UpdateWindow, WM_GETMINMAXINFO, WM_PAINT


MsgWaitForMultipleObjects

The MsgWaitForMultipleObjects function returns when one of the following occurs:

•	Either any one or all of the specified objects are in the signaled state. The objects can include input event objects, which you specify using the dwWakeMask parameter.

•	The time-out interval elapses.

Note that MsgWaitForMultipleObjects doesn’t return if there was previously unread input of the specified type in the queue. It only wakes up when input arrives.

DWORD MsgWaitForMultipleObjects(

DWORD nCount,	// number of handles in the object handle array
LPHANDLE pHandles,	// pointer to the object-handle array
BOOL fWaitAll,	// wait for all or wait for one
DWORD dwMilliseconds,	// time-out interval in milliseconds
DWORD dwWakeMask	// type of input events to wait for
);
Parameters

nCount

Specifies the number of object handles in the array pointed to by pHandles. The maximum number of object handles is MAXIMUM_WAIT_OBJECTS minus one.

pHandles

Points to an array of object handles. For a list of the object types whose handles can be specified, see the following Remarks section. The array can contain handles of objects of different types.

Windows NT: The handles must have SYNCHRONIZE access.

fWaitAll

Specifies the wait type. If TRUE, the function returns when the states of all objects in the pHandles array, including input events, have been set to signaled. If FALSE, the function returns when the state of any one of the objects is set to signaled. In the latter case, the return value indicates the object whose state caused the function to return.

dwMilliseconds

Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the criteria specified by the fWaitAll or dwWakeMask parameter have not been met. If dwMilliseconds is zero, the function tests the states of the specified objects and returns immediately. If dwMilliseconds is INFINITE, the function’s time-out interval never elapses.

dwWakeMask

Specifies input types for which an input event object handle will be added to the array of object handles. This parameter can be any combination of the following values:

Value	Meaning
QS_ALLINPUT	Any message is in the queue.
QS_HOTKEY	A WM_HOTKEY message is in the queue.
QS_INPUT	An input message is in the queue.
QS_KEY	A WM_KEYUP, WM_KEYDOWN, WM_SYSKEYUP, or WM_SYSKEYDOWN message is in the queue.
QS_MOUSE	A WM_MOUSEMOVE message or mouse-button message (WM_LBUTTONUP, WM_RBUTTONDOWN, and so on).
QS_MOUSEBUTTON	A mouse-button message (WM_LBUTTONUP, WM_RBUTTONDOWN, and so on).
QS_MOUSEMOVE	A WM_MOUSEMOVE message is in the queue.
QS_PAINT	A WM_PAINT message is in the queue.
QS_POSTMESSAGE	A posted message (other than those just listed) is in the queue.
QS_SENDMESSAGE	A message sent by another thread or application is in the queue.
QS_TIMER	A WM_TIMER message is in the queue.
Return Values

If the function succeeds, the return value indicates the event that caused the function to return. The successful return value is one of the following:

Value	Meaning
WAIT_OBJECT_0 to  (WAIT_OBJECT_0 + nCount − 1)	If fWaitAll is TRUE, the return value indicates that the state of all specified objects is signaled. If fWaitAll is FALSE, the return value minus WAIT_OBJECT_0 indicates the pHandles array index of the object that satisfied the wait.
WAIT_OBJECT_0 + nCount	Input of the type specified in the dwWakeMask parameter is available in the thread’s input queue.
WAIT_ABANDONED_0 to  (WAIT_ABANDONED_0 + nCount − 1)	If fWaitAll is TRUE, the return value indicates that the state of all specified objects is signaled and at least one of the objects is an abandoned mutex object. If fWaitAll is FALSE, the return value minus WAIT_ABANDONED_0 indicates the pHandles array index of an abandoned mutex object that satisfied the wait.
WAIT_TIMEOUT	The time-out interval elapsed and the conditions specified by the fWaitAll and dwWakeMask parameters were not satisfied.
If the function fails, the return valueis 0xFFFFFFFF. To get extended error information, call GetLastError.

Remarks

The MsgWaitForMultipleObjects function determines whether the wait criteria have been met. If the criteria have not been met, the calling thread enters an efficient wait state, using very little processor time while waiting for the conditions of the wait criteria to be met.

The function does not modify the states of the specified objects until the states of all objects have been set to signaled. For example, a mutex can be signaled, but the thread does not get ownership until the states of the other objects have also been set to signaled. In the meantime, some other thread may get ownership of the mutex, thereby setting its state to nonsignaled.

When fWaitAll is TRUE, the function’s wait is completed only when the states of all objects have been set to signaled, including the input events specified by dwWaskMask. Therefore, setting fWaitAll to TRUE prevents input from being processed until the state of all objects in the pHandles array have been set to signaled. For this reason, if you set fWaitAll to TRUE, you should use a short timeout value in dwMilliseconds. If you have a thread that creates windows waiting for all objects in the pHandles array, including input events specified by dwWakeMask, with no timeout interval, the system will deadlock. This is because threads that create windows must process messages. DDE sends message to all windows in the system. Therefore, if a thread creates windows, do not set the fWaitAll parameter to TRUE in calls to MsgWaitForMultipleObjects made from that thread.

Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one.

The MsgWaitForMultipleObjects function can specify handles of any of the following object types in the pHandles array:

Object	Description
Change notification	The FindFirstChangeNotification function returns the handle. The state of a change notification object is set to signaled when a specified type of change occurs within a specified directory or directory tree.
Console input	The CreateFile function returns the handle when the CONIN$ value is specified, or the GetStdHandle function returns the handle. The state of the object is set to signaled when there is unread input in the console’s input buffer and nonsignaled when the input buffer is empty.
Event	The CreateEvent or OpenEvent function returns the handle. The state of an event object is set explicitly to signaled by the SetEvent or PulseEvent function. The state of a manual-reset event object must be reset explicitly to nonsignaled by the ResetEvent function. For an auto-reset event object, the wait function resets the object state to nonsignaled before returning. Event objects are also used in overlapped operations, in which the state is set by the system.
Mutex	The CreateMutex or OpenMutex function returns the handle. The state of a mutex object is signaled when it is not owned by any thread. The wait function requests ownership of the mutex for the calling thread, changing the mutex state to nonsignaled when ownership is granted.
Process	The CreateProcess or OpenProcess function returns the handle. The state of a process object is set to signaled when the process terminates.
Semaphore	The CreateSemaphore or OpenSemaphore function returns the handle. A semaphore object maintains a count between zero and the maximum count specified during its creation. Its state is set to signaled when its count is greater than zero and nonsignaled when its count is zero. If the current state of the semaphore is signaled, the wait function decreases the count by one.
Thread	The CreateProcess, CreateThread, or CreateRemoteThread function returns the handle. The state of a thread object is set to signaled when the thread terminates.
Timer	The CreateWaitableTimer or OpenWaitableTimer function returns the handle. Activate the timer by calling the SetWaitableTimer function. The state of an active timer is set to signaled when it reaches its due time. You can deactivate the timer by calling the CancelWaitableTimer function.
In some circumstances, you can specify a handle of a file, named pipe, or communications device as a synchronization object in lpHandles. However, their use for this purpose is discouraged.

See Also

CancelWaitableTimer, CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, FindFirstChangeNotification, GetStdHandle, MsgWaitForMultipleObjectsEx OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, OpenWaitableTimer, PulseEvent, ResetEvent, SetEvent


MsgWaitForMultipleObjectsEx [New - Windows NT]
MsgWaitForMultipleObjectsEx

[New - Windows NT]

The MsgWaitForMultipleObjectsEx function returns when one of the following occurs:

•	Either any one or all of the specified objects are in the signaled state. The array of objects can include input event objects, which you specify using the dwWakeMask parameter.

•	An I/O completion routine or asynchronous procedure call (APC) is queued to the thread.

•	The time-out interval elapses.

The MsgWaitForMultipleObjectsEx function does not return if there is unread input of the specified type in the queue. It returns only when new input arrives.

DWORD MsgWaitForMultipleObjectsEx(

DWORD nCount,	// number of handles in handle array
LPHANDLE pHandles,	// pointer to an object-handle array
DWORD dwMilliseconds,	// time-out interval in milliseconds
DWORD dwWakeMask,	// type of input events to wait for
DWORD dwFlags	// wait flags
);
Parameters

nCount

Specifies the number of object handles in the array pointed to by pHandles. The maximum number of object handles is MAXIMUM_WAIT_OBJECTS minus one.

pHandles

Points to an array of object handles. For a list of the object types whose handles you can specify, see the Remarks section later in this topic. The array can contain handles to multiple types of objects.

Windows NT: The handles must have SYNCHRONIZE access.

dwMilliseconds

Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the conditions specified by the dwWakeMask and dwFlags parameters are not met. If dwMilliseconds is zero, the function tests the states of the specified objects and returns immediately. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.

dwWakeMask

Specifies input types for which an input event object handle will be added to the array of object handles. This parameter can be any combination of the following values:

Value	Meaning
QS_ALLINPUT	Any message is in the queue.
QS_HOTKEY	A WM_HOTKEY message is in the queue.
QS_INPUT	An input message is in the queue.
QS_KEY	A WM_KEYUP, WM_KEYDOWN, WM_SYSKEYUP, or WM_SYSKEYDOWN message is in the queue.
QS_MOUSE	A WM_MOUSEMOVE message or mouse-button message (WM_LBUTTONUP, WM_RBUTTONDOWN, and so on) is in the queue.
QS_MOUSEBUTTON	A mouse-button message (WM_LBUTTONUP, WM_RBUTTONDOWN, and so on) is in the queue.
QS_MOUSEMOVE	A WM_MOUSEMOVE message is in the queue.
QS_PAINT	A WM_PAINT message is in the queue.
QS_POSTMESSAGE	A posted message (other than those just listed) is in the queue.
QS_SENDMESSAGE	A message sent by another thread or application is in the queue.
QS_TIMER	A WM_TIMER message is in the queue.
dwFlags

Specifies the wait type. This parameter can be any combination of the following values:

Value	Meaning
0	The function returns when any one of the objects is signaled. The return value indicates the object whose state caused the function to return.
MWMO_WAITALL	The function returns when all objects in the pHandles array are signaled at the same time.
MWMO_ALERTABLE	The function also returns if an APC has been queued to the thread with QueueUserAPC.
Return Values

If the function succeeds, the return value indicates the event that caused the function to return. The successful return value is one of the following:

Value	Meaning
WAIT_OBJECT_0 to  (WAIT_OBJECT_0 + nCount - 1)	If the MWMO_WAITALL flag is used, the return value indicates that the state of all specified objects is signaled. Otherwise, the return value minus WAIT_OBJECT_0 indicates the pHandles array index of the object that caused the function to return.
WAIT_OBJECT_0 + nCount	Input of the type specified in the dwWakeMask parameter is available in the thread's input queue.
WAIT_ABANDONED_0 to  (WAIT_ABANDONED_0 + nCount - 1)	If the MWMO_WAITALL flag is used, the return value indicates that the state of all specified objects is signaled and at least one of the objects is an abandoned mutex object. Otherwise, the return value minus WAIT_ABANDONED_0 indicates the pHandles array index of an abandoned mutex object that caused the function to return.
WAIT_IO_COMPLETION	The wait was ended by a user-mode asynchronous procedure call (APC) queued to the thread.
WAIT_TIMEOUT	The time-out interval elapsed, but the conditions specified by the dwFlags and dwWakeMask parameters were not met.
If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

Remarks

The MsgWaitForMultipleObjectsEx function determines whether the conditions specified by dwWakeMask and dwFlags have been met. If the conditions have not been met, the calling thread enters an efficient wait state. The thread uses very little processor time while waiting for one of the conditions to be met or for the time-out interval to elapse.

Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. For example, the system decreases the count of a semaphore object by one.

The MsgWaitForMultipleObjectsEx function can specify handles of any of the following object types in the pHandles array:

Object	Description
Change notification	The FindFirstChangeNotification function returns the handle. The state of a change notification object is set to signaled when a specified change occurs within a specified directory or directory tree.
Console input	The CreateFile function returns the handle when the CONIN$ value is specified, or the GetStdHandle function returns the handle. The state of the object is set to signaled when there is unread input in the console's input buffer and nonsignaled when the input buffer is empty.
Event	The CreateEvent or OpenEvent function returns the handle. The state of an event object is set explicitly to signaled by the SetEvent or PulseEvent function. The state of a manual-reset event object must be reset explicitly to nonsignaled by the ResetEvent function. For an auto-reset event object, the wait function resets the object state to nonsignaled before returning. Event objects are also used in overlapped operations, in which the state is set by the system.
Mutex	The CreateMutex or OpenMutex function returns the handle. The state of a mutex object is signaled when it is not owned by any thread. The wait function requests ownership of the mutex for the calling thread, changing the mutex state to nonsignaled when ownership is granted.
Process	The CreateProcess or OpenProcess function returns the handle. The state of a process object is set to signaled when the process terminates.
Semaphore	The CreateSemaphore or OpenSemaphore function returns the handle. A semaphore object maintains a count between zero and the maximum count specified during its creation. Its state is set to signaled when its count is greater than zero and nonsignaled when its count is zero. If the current state of the semaphore is signaled, the wait function decreases the count by one.
Thread	The CreateProcess, CreateThread, or CreateRemoteThread function returns the handle. The state of a thread object is set to signaled when the thread terminates.
Timer	The CreateWaitableTimer or OpenWaitableTimer function returns the handle. Activate the timer by calling the SetWaitableTimer function. The state of an active timer is set to signaled when it reaches its due time. You can deactivate the timer by calling the CancelWaitableTimer function.
In some circumstances, you can specify a handle of a file, named pipe, or communications device as a synchronization object in lpHandles. However, their use for this purpose is discouraged.

See Also

CancelWaitableTimer, CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, CreateWaitableTimer, FindFirstChangeNotification, GetStdHandle, MsgWaitForMultipleObjects, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, OpenWaitableTimer, PulseEvent, QueueUserAPC, ResetEvent, SetEvent, SetWaitableTimer


MulDiv

The MulDiv function multiplies two 32-bit values and then divides the 64-bit result by a third 32-bit value. The return value is rounded up or down to the nearest integer.

int MulDiv(

int nNumber,	// 32-bit signed multiplicand
int nNumerator,	// 32-bit signed multiplier
int nDenominator	// 32-bit signed divisor
);
Parameters

nNumber

Specifies the multiplicand.

nNumerator

Specifies the multiplier.

nDenominator

Specifies the number by which the result of the multiplication (nNumber * nNumerator) is to be divided.

Return Values

If the function succeeds, the return value is the result of the multiplication and division. If either an overflow occurred or nDenominator was 0, the return value is −1.

See Also

Int32x32To64, UInt32x32To64


MultiByteToWideChar

The MultiByteToWideChar function maps a character string to a wide-character (Unicode) string. The character string mapped by this function is not necessarily from a multibyte character set.

int MultiByteToWideChar(

UINT CodePage,	// code page
DWORD dwFlags,	// character-type options
LPCSTR lpMultiByteStr,	// address of string to map
int cchMultiByte,	// number of characters in string
LPWSTR lpWideCharStr,	// address of wide-character buffer
int cchWideChar	// size of buffer
);
Parameters

CodePage

Specifies the code page to be used to perform the conversion. This parameter can be given the value of any codepage that is installed or available in the system. The following values may be used to specify one of the system default code pages:

Value	Meaning
CP_ACP	ANSI code page
CP_MACCP	Macintosh code page
CP_OEMCP	OEM code page
dwFlags

A set of bit flags that indicate whether to translate to precomposed or composite wide characters (if a composite form exists), whether to use glyph characters in place of control characters, and how to deal with invalid characters. You can specify a combination of the following flag constants:

Value	Meaning
MB_PRECOMPOSED	Always use precomposed characters — that is, characters in which a base character and a nonspacing character have a single character value. This is the default translation option. Cannot be used with MB_COMPOSITE.
MB_COMPOSITE	Always use composite characters — that is, characters in which a base character and a nonspacing character have different character values. Cannot be used with MB_PRECOMPOSED.
MB_ERR_INVALID_CHARS	If the function encounters an invalid input character, it fails and GetLastError returns ERROR_NO_UNICODE_TRANSLATION.
MB_USEGLYPHCHARS	Use glyph characters instead of control characters.
A composite character consists of a base character and a nonspacing character, each having different character values. A precomposed character has a single character value for a base/non-spacing character combination. In the character è, the e is the base character and the accent grave mark is the nonspacing character.

The function’s default behavior is to translate to the precomposed form. If a precomposed form does not exist, the function attempts to translate to a composite form.

The flags MB_PRECOMPOSED and MB_COMPOSITE are mutually exclusive. The MB_USEGLYPHCHARS flag and the MB_ERR_INVALID_CHARS can be set regardless of the state of the other flags.

lpMultiByteStr

Points to the character string to be converted.

cchMultiByte

Specifies the size in bytes of the string pointed to by the lpMultiByteStr parameter. If this value is −1, the string is assumed to be null terminated and the length is calculated automatically.

lpWideCharStr

Points to a buffer that receives the translated string.

cchWideChar

Specifies the size, in wide characters, of the buffer pointed to by the lpWideCharStr parameter. If this value is zero, the function returns the required buffer size, in wide characters, and makes no use of the lpWideCharStr buffer.

Return Values

If the function succeeds, and cchWideChar is nonzero, the return value is the number of wide characters written to the buffer pointed to by lpWideCharStr.

If the function succeeds, and cchWideChar is zero, the return value is the required size, in wide characters, for a buffer that can receive the translated string.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

ERROR_NO_UNICODE_TRANSLATION

Remarks

The lpMultiByteStr and lpWideCharStr pointers must not be the same. If they are the same, the function fails, and GetLastError returns the value ERROR_INVALID_PARAMETER.

The function fails if MB_ERR_INVALID_CHARS is set and it encounters an invalid character in the source string.  An invalid character is one that would translate to the default character if MB_ERR_INVALID_CHARS was not set, but is not the default character in the source string, or when a lead byte is found in a string and there is no valid trail byte for DBCS strings. When an invalid character is found, and MB_ERR_INVALID_CHARS is set, the function returns 0 and sets GetLastError with the error ERROR_NO_UNICODE_TRANSLATION.

See Also

WideCharToMultiByte


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

See Also

NETRESOURCE, WNetGetLastError


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.


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.

See Also

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.

See also

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.

See also

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.

See also

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.

See Also

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.

See also

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.

See Also

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.


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.


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 the first release of Windows NT, 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.

See Also

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.

See Also

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.


NetAccessAdd

The NetAccessAdd function is obsolete. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.


NetAccessCheck

The NetAccessCheck function is obsolete. Win32-based applications should use the AccessCheck function.


NetAccessDel

The NetAccessDel function is obsolete. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.


NetAccessEnum

The NetAccessEnum function is obsolete. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.


NetAccessGetInfo

The NetAccessGetInfo function is obsolete. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.


NetAccessGetUserPerms

The NetAccessGetUserPerms function is obsolete. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.


NetAccessSetInfo

The NetAccessSetInfo functions is obsolete. Win32-based applications should use the GetFileSecurity and SetFileSecurity 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(

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

See Also

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(

LPTSTR AlertEventName,
LPVOID VariableInfo,
DWORD VariableInfoSize,
LPTSTR 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.

See Also

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.

See Also

NetApiBufferReallocate


NetApiBufferFree

The NetApiBufferFree function frees the memory that NetApiBufferAllocate allocates. Use this function to free the memory that other LAN Manager functions return.

NET_API_STATUS NetApiBufferFree(

LPVOID Buffer
);
Parameters

Buffer

Pointer to an information buffer that other LAN Manager functions previously returned on a function call.

See Also

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.

See Also

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.

See Also

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.


NetAuditRead

The NetAuditRead function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use event logging.


Netbios

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

UCHAR Netbios(

PNCB pncb	// address of 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.

There are two return value possibilities for accepted asynchronous requests. 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.

Remarks

The Netbios function is primarily for applications written for the IBM NetBIOS system that need to be ported to Windows. Applications that do not have this requirement typically use other interfaces, such as mailslots and named pipes, instead of Netbios.

Netbios contains extensions to the standard IBM NetBIOS 3.0 specification to allow POST routines to be called from C and to operate efficiently in the Windows environment.

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 the address of the finishing network control block. (In the standard IBM NetBIOS 3.0, the address of the network control block is supplied in a nonportable interface.)

Another extension to the NCB structure is a handle of an event (the ncb_event member). The event is set to the nonsignaled state by the system when an asynchronous NetBIOS command is accepted, and it is set to the signaled state when the asynchronous NetBIOS command finishes.

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.

Only manual reset events should be used with Netbios. A specified event should not be associated with more than one active asynchronous NetBIOS command.

In 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 systemwide name table rather the a per-process name table.

See Also

NCB


NetConfigGet

The NetConfigGet function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use the registry.


NetConfigGetAll

The NetConfigGetAll function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use the registry.


NetConfigSet

The NetConfigSet function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use the registry.


NetConnectionEnum

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.


NetErrorLogClear

The NetErrorLogClear function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use event logging.


NetErrorLogRead

The NetErrorLogRead function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use event logging.


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.


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(

LPTSTR servername,
LPTSTR basepath,
LPTSTR 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 to 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.

See Also

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(

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

See Also

NetFileEnum


NetGetAnyDCName

The NetGetAnyDCName function gets the name of any domain controller for a domain that is directly trusted by the server name.

Security Requirements

No special group membership is required to successfully execute NetGetAnyDCName.

NET_API_STATUS NetGetAnyDCName(

    LPCWSTR ServerName,

       LPCWSTR DomainName,

    OUT LPBYTE * Buffer

   );

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.

DomainName

Specifies the name of domain (null for primary domain)

Buffer

Returns a pointer to an allocated buffer containing the server name of a domain controller for the domain.  The server name is prefixed by \\. The buffer should be deallocated using NetApiBufferFree.

Remarks

If ServerName is a standalone Windows NT Workstation or standalone Windows NT Server, no DomainName is valid. If ServerName is a Windows NT Workstation that is a member of a domain or a Windows NT Server member, the DomainName must be in the same domain as ServerName. If ServerName is a Windows NT Server domain controller, the DomainName must be one of the domains trusted by the domain for which the server is a controller . The domain controller that this call finds has been operational at least once during this call.

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_SUCCESS	Buffer successfully contains the name of the domain controller prefixed by \\.
ERROR_NO_LOGON_SERVERS	No domain controllers could be found
ERROR_NO_SUCH_DOMAIN	The specified domain is not a trusted domain.
ERROR_NO_TRUST_LSA_SECRET	The client side of the trust relationship is broken.
ERROR_NO_TRUST_SAM_ACCOUNT	The server side of the trust relationship is broken or the password is broken.
ERROR_DOMAIN_TRUST_INCONSISTENT	The server that responded is not a proper domain controller of the specified domain.
See Also

NetGetDCName


NetGetDCName

The NetGetDCName function returns the name of the Primary Domain Controller (PDC) for the specified domain.

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

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.

See Also

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

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

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

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

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

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

NetGroupSetInfo


NetGroupGetUsers

The NetGroupGetUsers function retrieves a list of the members of a particular global group in the security database.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute NetGroupGetUsers, except when the request is made by a user who has membership in the specified global group, in which case no special group membership is required.

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

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

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

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.

See Also

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.

See Also

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

NetLocalGroupDel


NetLocalGroupAddMember

The NetLocalGroupAddMember function is obsolete. Win32-based applications should use the NetLocalGroupAddMembers function.


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

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

NetLocalGroupAdd


NetLocalGroupDelMember

The NetLocalGroupDelMember function is obsolete. Win32-based applications should use the NetLocalGroupDelMembers function.


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

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

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

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

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

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.

See Also

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(

LPTSTR servername,
LPTSTR msgname,
LPTSTR 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 Windows 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.

See Also

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(

LPTSTR servername,
LPTSTR 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.

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.

See Also

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(

LPTSTR servername,
LPTSTR 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.

See Also

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(

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

See Also

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(

LPTSTR servername,
LPTSTR 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.

See Also

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.

See Also

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(

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


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(

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

See Also

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(

LPTSTR servername,
LPTSTR 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.

See Also

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(

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

See Also

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(

LPTSTR servername,
LPTSTR 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.

See Also

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(

LPTSTR servername,
LPTSTR 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.

See Also

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(

LPTSTR servername,
LPTSTR 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.

See Also

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(

LPTSTR servername,
LPTSTR 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.

See Also

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(

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

See Also

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(

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

See Also

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(

LPTSTR servername,
LPTSTR 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.

See Also

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(

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

See Also

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(

LPTSTR servername,
LPTSTR 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.

See Also

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(

LPTSTR servername,
LPTSTR 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.

See Also

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(

LPTSTR servername,
LPTSTR 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.

See Also

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(

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

See Also

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.

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.


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.

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.

See Also

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.

See Also

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.

See Also

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(

LPTSTR 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 the following value to return the level of information provided.

Value	Meaning
100	The bufptr parameter points to an array of SERVER_INFO_100 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 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.

See Also

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(

LPTSTR servername,
DWORD level,
LPBYTE *bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
DWORD servertype,
LPTSTR 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 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. 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.

See Also

NetServerDiskEnum, NetQueryDisplayInformation, SERVER_INFO_100, SERVER_INFO_101


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(

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

See Also

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(

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

See Also

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(

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

See Also

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.

See Also

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(

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


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.


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.


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.


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.


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(

LPTSTR servername,
LPTSTR UncClientName,
LPTSTR 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.

See Also

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(

LPTSTR servername,
LPTSTR UncClientName,
LPTSTR 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.

See Also

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(

LPTSTR servername,
LPTSTR UncClientName,
LPTSTR 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.

See Also

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(

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

See Also

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(

LPTSTR servername,
LPTSTR 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.

See Also

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(

LPTSTR servername,
LPTSTR 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.

See Also

NetShareAdd


NetShareEnum

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.


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(

LPTSTR servername,
LPTSTR 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 provided.

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

Remarks

You need to free the memory pointed to by bufptr. Use the NetAPIBufferFree function to free the pointer.

See Also

NetShareSetInfo


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(

LPTSTR servername,
LPTSTR 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.

See Also

NetShareGetInfo


NetStatisticsGet

The NetStatisicsGet function is obsolete. Win32-based applications should use the NetStatisticsGet2 function


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(

LPTSTR server,
LPTSTR 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.

See Also

NetServerGetInfo, STAT_SERVER_0, STAT_WORKSTATION_0


NetUseAdd

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.


NetUseDel

The NetUseDel function is obsolete. It is provided only for compatibility with LAN Manager and 16-bit versions of Windows. Win32-based applications should use the WNetCancelConnection2 function.


NetUseEnum

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


NetUseGetInfo

The NetUseGetInfo function is obsolete. It is provided only for compatibility with LAN Manager and 16-bit versions of Windows. Win32-based applications should use the WNetGetConnection function.


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

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

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.
NERR_PasswordTooShort	The password is shorter than required.
See Also

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

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

See Also

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 the buffer in which the data set with the level parameter is stored. The buffer passed in must have been previously allocated with NetApiBufferAlloc. 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. LAN Manager groups are separate and distinct from Windows NT system groups.

See Also

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

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

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

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

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. The returned buffer should be deallocated using the NetApiBufferFree function.

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

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 LAN Manager 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.
See Also

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(

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

Pointer to the buffer in which the data set with the level parameter is stored.

See Also

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(

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

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

See Also

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(

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

See Also

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(

LPTSTR servername,
LPTSTR 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.

See Also

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(

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

See Also

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(

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

See Also

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(

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

See Also

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(

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

See Also

NetWkstaUserGetInfo


NotifyBootConfigStatus

The NotifyBootConfigStatus function notifies the service control manager as to the acceptability of the configuration that booted the system.

An acceptable configuration triggers the storage of that configuration as the last-known good configuration; an unacceptable configuration triggers a system reboot.

BOOL NotifyBootConfigStatus(

BOOL BootAcceptable	// indicates acceptability of boot configuration
);
Parameters

BootAcceptable

Specifies whether the configuration that booted the system is acceptable. If this parameter’s value is TRUE, the service control manager saves the configuration that booted the system as the last-known good configuration. If the parameter’s value is FALSE, the system immediately reboots, using the previously saved last-known good configuration.

Return Values

If the BootAcceptable parameter is FALSE, the function does not return.

If the last-known good configuration was successfully saved, the return value is nonzero.

If an error occurs, the return value is zero. To get extended error information, call GetLastError.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager to set parameters in the configuration registry.

Value	Meaning
ERROR_ACCESS_DENIED	The user does not have permission to perform this operation.  A hard-coded DACL associated with the service control manager object determines who can perform a NotifyBootConfigStatus operation. Only the operating system and members of the Adminstrators local group can do so.
Remarks

Saving the configuration of a running system with this function is an acceptable method for saving the last-known good configuration.

If the boot configuration is found to be unacceptable, this function can be called to a reboot with the existing last-known good configuration. This function can be called only by a process running in the LocalSystem or the Administrator’s security context.


NotifyChangeEventLog

The NotifyChangeEventLog function lets an application receive notification when an event is written to the event log file specified by the hEventLog parameter. When the event is written to the event log file, the function causes the event object specified by the hEvent parameter to become signaled.

BOOL NotifyChangeEventLog(

HANDLE hEventLog,	// handle to an event log
HANDLE hEvent	// handle to a Win32 event
);
Parameters

hEventLog

Handle to an event log file, obtained by calling OpenEventLog function. When an event is written to this log file, the event specified by hEvent becomes signaled.

hEvent

A handle to a Win32 event. This is the event that becomes signaled when an event is written to the event log file specified by the hEventLog parameter.

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.

Remarks

The NotifyChangeEventLog function does not work with remote handles. If hEventLog is the handle of an event log on a remote computer, the NotifiyChangeEventLog function returns FALSE, and GetLastError  returns ERROR_INVALID_HANDLE.

See Also

OpenEventLog


ObjectCloseAuditAlarm

The ObjectCloseAuditAlarm function generates audit messages when a handle of an object is deleted. Alarms are not supported in the current version of Windows NT.

BOOL ObjectCloseAuditAlarm(

LPCTSTR SubsystemName,	// address of string for subsystem name
LPVOID HandleId,	// address of handle identifier
BOOL GenerateOnClose	// flag for audit generation
);
Parameters

SubsystemName

Points to a null-terminated string specifying the name of the subsystem calling the function, for example, “DEBUG” or “WIN32”.

HandleId

Specifies a unique 32-bit value representing the client’s handle of the object. This should be the same value that was passed to the AccessCheckAndAuditAlarm or ObjectOpenAuditAlarm function.

GenerateOnClose

Specifies a flag set by a call to the AccessCheckAndAuditAlarm or ObjectOpenAuditAlarm function when the object handle is created.

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.

Remarks

The ObjectCloseAuditAlarm function requires the calling application to have the SE_AUDIT_NAME privilege. The test for this privilege is always performed against the primary token of the calling process, allowing the calling process to impersonate a client.

See Also

AccessCheck, AccessCheckAndAuditAlarm, AreAllAccessesGranted, AreAnyAccessesGranted, MapGenericMask, ObjectDeleteAuditAlarm, ObjectOpenAuditAlarm, ObjectPrivilegeAuditAlarm, PrivilegeCheck, PrivilegedServiceAuditAlarm


ObjectDeleteAuditAlarm [New - Windows NT]
ObjectDeleteAuditAlarm

[New - Windows NT]

The ObjectDeleteAuditAlarm function generates audit messages when an object is deleted. Windows NT security does not support alarms.

BOOL ObjectDeleteAuditAlarm(

LPCTSTR SubsystemName,	// pointer to string for subsystem name
LPVOID HandleId,	// handle to the object
BOOL GenerateOnClose	// flag for audit generation
);
Parameters

SubsystemName

Pointer to a null-terminated string that specifies the name of the subsystem calling the function; for example, “DEBUG” or “WIN32”. This string appears in the audit log for the object.

HandleId

Specifies a unique 32-bit value representing the client’s handle to the object. This should be the same value that was passed to the AccessCheckAndAuditAlarm or ObjectOpenAuditAlarm function.

GenerateOnClose

Specifies a flag set by a call to the AccessCheckAndAuditAlarm or ObjectOpenAuditAlarm function when the object handle is created.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The ObjectDeleteAuditAlarm function requires the calling application to have the SE_AUDIT_NAME privilege. The test for this privilege is always performed against the primary token of the calling process, allowing the calling process to impersonate a client.

See Also

AccessCheck, AccessCheckAndAuditAlarm, AreAllAccessesGranted, AreAnyAccessesGranted, MapGenericMask, ObjectCloseAuditAlarm, ObjectOpenAuditAlarm, ObjectPrivilegeAuditAlarm, PrivilegeCheck, PrivilegedServiceAuditAlarm


ObjectOpenAuditAlarm

The ObjectOpenAuditAlarm function generates audit messages when a client application attempts to gain access to an object or to create a new one. Alarms are not supported in the current version of Windows NT.

BOOL ObjectOpenAuditAlarm(

LPCTSTR SubsystemName,	// address of string for subsystem name
LPVOID HandleId,	// address of handle identifier
LPTSTR ObjectTypeName,	// address of string for object type
LPTSTR ObjectName,	// address of string for object name
PSECURITY_DESCRIPTOR pSecurityDescriptor,	// address of security descriptor
HANDLE ClientToken,	// handle of client’s access token
DWORD DesiredAccess,	// mask for desired access rights
DWORD GrantedAccess,	// mask for granted access rights
PPRIVILEGE_SET Privileges,	// address of privileges
BOOL ObjectCreation,	// flag for object creation
BOOL AccessGranted,	// flag for results
LPBOOL GenerateOnClose	// address of flag for audit generation
);
Parameters

SubsystemName

Points to a null-terminated string specifying the subsystem calling this function, for example, “DEBUG” or “WIN32”.

HandleId

Points to a unique 32-bit value representing the client’s handle of the object. If the access is denied, this parameter is ignored.

ObjectTypeName

Points to a null-terminated string specifying the type of object to which the client is requesting access. This string appears in the audit log for the object.

ObjectName

Points to a null-terminated string specifying the name of the object to which the client gained access or attempted to gain access. This string appears in the audit log for the object.

pSecurityDescriptor

Points to the SECURITY_DESCRIPTOR structure for the object being accessed.

ClientToken

Identifies an access token representing the client requesting the operation. This handle must be obtained by opening the token of a thread impersonating the client. The token must be open for TOKEN_QUERY access.

DesiredAccess

Specifies the desired access mask. This mask must have been previously mapped by the MapGenericMask function to contain no generic access rights.

GrantedAccess

Specifies an access mask indicating which access rights are granted. This access mask is intended to be the same value set by one of the access-checking functions in its GrantedAccess parameter. Examples of access-checking functions include AccessCheckAndAuditAlarm and AccessCheck.

Privileges

Points to a PRIVILEGE_SET structure that specifies the set of privileges required for the access attempt. This parameter can be NULL.

ObjectCreation

Specifies a flag that determines whether the application creates a new object when access is granted. When this flag is TRUE, the application creates a new object; when it is FALSE, the application opens an existing object.

AccessGranted

Specifies a flag indicating whether access was granted or denied in a previous call to an access-checking function, such as AccessCheck. If access was granted, this flag is TRUE. If not, it is FALSE.

GenerateOnClose

Points to a flag set by the audit-generation routine when the function returns. This flag must be passed to the ObjectCloseAuditAlarm function when the object handle is closed.

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.

Remarks

The ObjectOpenAuditAlarm function requires the calling application to have the SE_AUDIT_NAME privilege. The test for this privilege is always performed against the primary token of the calling process, not the impersonation token of the thread. This allows the calling process to impersonate a client during the call.

See Also

AccessCheck, AccessCheckAndAuditAlarm, AreAllAccessesGranted, AreAnyAccessesGranted, MapGenericMask, ObjectCloseAuditAlarm, ObjectDeleteAuditAlarm, ObjectPrivilegeAuditAlarm, PrivilegeCheck, PrivilegedServiceAuditAlarm, PRIVILEGE_SET, SECURITY_DESCRIPTOR


ObjectPrivilegeAuditAlarm

The ObjectPrivilegeAuditAlarm function generates audit messages as a result of a client’s attempt to perform a privileged operation on a server application object using an already opened handle of that object. Alarms are not supported in the current version of Windows NT.

BOOL ObjectPrivilegeAuditAlarm(

LPCTSTR SubsystemName,	// pointer to string for subsystem name
LPVOID HandleId,	// pointer to handle identifier
HANDLE ClientToken,	// handle to client’s access token
DWORD DesiredAccess,	// mask for desired access rights
PPRIVILEGE_SET Privileges,	// pointer to privileges
BOOL AccessGranted	// flag for results
);
Parameters

SubsystemName

Points to a null-terminated string specifying the name of the subsystem calling the function; for example, “DEBUG” or “WIN32”.

HandleId

Points to a unique 32-bit value representing the client’s handle to the object.

ClientToken

Identifies an access token representing the client requesting the operation. This handle must be obtained by opening the token of a thread impersonating the client. The token must be open for TOKEN_QUERY access.

DesiredAccess

Specifies an access mask indicating the privileged access types being used or whose use is being attempted. The access mask can be mapped by the MapGenericMask function so it does not contain any generic access types.

Privileges

Points to a PRIVILEGE_SET structure specifying the set of privileges required for the requested operation. The information in this structure is supplied by a call to the PrivilegeCheck function. This parameter can be NULL.

AccessGranted

Specifies a flag indicating whether access was granted or denied in a previous call to an access-checking function such as PrivilegeCheck. If access was granted, this flag is TRUE. If not, it is FALSE.

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.

Remarks

The ObjectPrivilegeAuditAlarm function requires the calling process to have SE_AUDIT_NAME privilege. The test for this privilege is always performed against the primary token of the calling process, not the impersonation token of the thread. This allows the calling process to impersonate a client during the call.

The ObjectPrivilegeAuditAlarm function can send many messages to port objects. This can result in a significant delay before the function returns. The design of applications calling ObjectPrivilegeAuditAlarm can take this potential delay into account. For example, this consideration may affect the design of an application using mutexes to lock structures.

See Also

AccessCheck, AccessCheckAndAuditAlarm, AreAllAccessesGranted, AreAnyAccessesGranted, MapGenericMask, ObjectCloseAuditAlarm, ObjectOpenAuditAlarm, PrivilegeCheck, PrivilegedServiceAuditAlarm, PRIVILEGE_SET


OemKeyScan

The OemKeyScan function maps OEM ASCII codes 0 through 0x0FF into the OEM scan codes and shift states. The function provides information that allows a program to send OEM text to another program by simulating keyboard input.

DWORD OemKeyScan(

WORD wOemChar	// ASCII value of OEM character
);
Parameters

wOemChar

Specifies the ASCII value of the OEM character.

Return Values

If the function succeeds, the low-order word of the return value contains the scan code of the given OEM character, and the high-order word contains the shift state, which can be a combination of the following flag bits:

Bit	Meaning
1	Either SHIFT key is pressed.
2	Either CTRL key is pressed.
4	Either ALT key is pressed.
If the character cannot be produced by a single keystroke using the current keyboard layout, the return value is 0xFFFFFFFF.

Remarks

This function does not provide translations for characters that require CTRL+ALT or dead keys. Characters not translated by this function must be copied by simulating input using the ALT+ keypad mechanism. The NUMLOCK key must be off.

This function does not provide translations for characters that cannot be typed with one keystroke using the current keyboard layout, such as characters with diacritics requiring dead keys. Characters not translated by this function may be simulated using the ALT+ keypad mechanism. The NUMLOCK key must be on.

This function is implemented using the VkKeyScan function.

See Also

VkKeyScan


OemToAnsi

The OemToAnsi function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the OemToChar function, which should be used for new Win32-based applications.


OemToAnsiBuff

The OemToAnsiBuff function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the OemToCharBuff function, which should be used for Win32-based applications.


OemToChar

The OemToChar function translates a string from the OEM-defined character set into either an ANSI or a wide-character string. (OEM stands for original equipment manufacturer.) This function supersedes the OemToAnsi function.

BOOL OemToChar(

LPCSTR lpszSrc,	// pointer to string to translate
LPTSTR lpszDst	// pointer to buffer for translated string
);
Parameters

lpszSrc

Points to a null-terminated string of characters from the OEM-defined character set.

lpszDst

Points to the buffer for the translated string. If the OemToChar function is being used as an ANSI function, the string can be translated in place by setting the lpszDst parameter to the same address as the lpszSrc parameter. This cannot be done if OemToChar is being used as a wide-character function.

Return Values

The return value is always nonzero.

See Also

CharToOem, CharToOemBuff, OemToCharBuff


OemToCharBuff

The OemToCharBuff function translates a specified number of characters in a string from the OEM-defined character set into either an ANSI or a wide-character string. (OEM stands for original equipment manufacturer.) This function supersedes the OemToAnsiBuff function.

BOOL OemToCharBuff(

LPCSTR lpszSrc,	// pointer to string to translate
LPTSTR lpszDst,	// pointer to buffer for translated string
DWORD cchDstLength	// size of buffer
);
Parameters

lpszSrc

Points to a buffer containing one or more characters from the OEM-defined character set.

lpszDst

Points to the buffer for the translated string. If the OemToCharBuff function is being used as an ANSI function, the string can be translated in place by setting the lpszDst parameter to the same address as the lpszSrc parameter. This cannot be done if the OemToCharBuff function is being used as a wide-character function.

cchDstLength

Specifies the number of characters to translate in the buffer identified by the lpszSrc parameter.

Return Values

The return value is always nonzero.

See Also

CharToOem, CharToOemBuff, OemToChar


OffsetClipRgn

The OffsetClipRgn function moves the clipping region of a device context by the specified offsets.

int OffsetClipRgn(

HDC hdc,	// handle to device context
int nXOffset,	// offset along x-axis
int nYOffset	// offset along y-axis
);
Parameters

hdc

Identifies the device context.

nXOffset

Specifies the number of logical units to move left or right.

nYOffset

Specifies the number of logical units to move up or down.

Return Values

If the function succeeds, the return value specifies the new region’s complexity and can be any one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
ERROR	An error occurred. (The current clipping region is unaffected.)
See Also

SelectClipRgn


OffsetRect

The OffsetRect function moves the specified rectangle by the specified offsets.

BOOL OffsetRect(

LPRECT lprc,	// pointer to structure with rectangle
int dx,	// horizontal offset
int dy	// vertical offset
);
Parameters

lprc

Points to a RECT structure that contains the logical coordinates of the rectangle to be moved.

dx

Specifies the amount to move the rectangle left or right. This parameter must be a negative value to move the rectangle to the left.

dy

Specifies the amount to move the rectangle up or down. This parameter must be a negative value to move the rectangle up.

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.

See Also

InflateRect, IntersectRect, UnionRect, RECT


OffsetRgn

The OffsetRgn function moves a region by the specified offsets.

int OffsetRgn(

HRGN hrgn,	// handle to region
int nXOffset,	// offset along x-axis
int nYOffset	// offset along y-axis
);
Parameters

hrgn

Identifies the region to be moved.

nXOffset

Specifies the number of logical units to move left or right.

nYOffset

Specifies the number of logical units to move up or down.

Return Values

The return value specifies the new region’s complexity. It can be one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
ERROR	An error occurred; region is unaffected.


OffsetViewportOrgEx

The OffsetViewportOrgEx function modifies the viewport origin for a device context using the specified horizontal and vertical offsets.

BOOL OffsetViewportOrgEx(

HDC hdc,	// handle to device context
int nXOffset,	// horizontal offset
int nYOffset,	// vertical offset
LPPOINT lpPoint	// pointer to structure receiving original origin
);
Parameters

hdc

Identifies the device context.

nXOffset

Specifies the horizontal offset, in device units.

nYOffset

Specifies the vertical offset, in device units.

lpPoint

Points to a POINT structure. The previous viewport origin, in device units, is placed in this structure. If lpPoint is NULL, the previous viewport origin is not returned.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The new origin is the sum of the current origin and the horizontal and vertical offsets.

See Also

GetViewportOrgEx, OffsetWindowOrgEx, SetViewportOrgEx


OffsetWindowOrgEx

The OffsetWindowOrgEx function modifies the window origin for a device context using the specified horizontal and vertical offsets.

BOOL OffsetWindowOrgEx(

HDC hdc,	// handle to device context
int nXOffset,	// horizontal offset
int nYOffset,	// vertical offset
LPPOINT lpPoint	// pointer to structure receiving the original origin
);
Parameters

hdc

Identifies the device context.

nXOffset

Specifies the horizontal offset, in logical units.

nYOffset

Specifies the vertical offset, in logical units.

lpPoint

Points to a POINT structure. The logical coordinates of the previous window origin are placed in this structure. If lpPoint is NULL, the previous origin is not returned.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

GetViewportOrgEx, OffsetViewportOrgEx, POINT


OFNHookProc

An OFNHookProc hook procedure is an application-defined or library-defined callback procedure that is used with the Explorer-style Open and Save As common dialog boxes. The hook procedure receives notification messages sent from the common dialog box. The hook procedure also receives messages for any additional controls that you defined by specifying a child dialog template.

If you do not specify the OFN_EXPLORER flag when you create an Open or Save As common dialog box, and you want a hook procedure, you must use an old-style OFNHookProcOldStyle hook procedure. In this case, the dialog box will have the old-style user interface.

UINT APIENTRY OFNHookProc(

HWND hdlg,	// handle to child dialog window
UINT uiMsg,	// message identifier
WPARAM wParam,	// message parameter
LPARAM lParam	// message parameter
);
Parameters

hdlg

Handle to the child dialog box of the Open or Save As dialog box. Use the GetParent function to get the handle to the Open or Save As dialog box window.

uiMsg

Identifies the message being received.

wParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

lParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

If the uiMsg parameter indicates the WM_INITDIALOG message, lParam is a pointer to an OPENFILENAME structure containing the values specified when the dialog box was created.

Return Values

If the hook procedure returns zero, the default dialog box procedure processes the message.

If the hook procedure returns a nonzero value, the default dialog box procedure ignores the message.

For the CDN_SHAREVIOLATION and CDN_FILEOK notification messages, the hook procedure should return a nonzero value to indicate that it has used the SetWindowLong function to set a nonzero DWL_MSGRESULT value.

Remarks

When you use the GetOpenFileName or GetSaveFileName functions to create an Explorer-style Open or Save As common dialog box, you can provide an OFNHookProc hook procedure. To enable the hook procedure, use the OPENFILENAME structure that you passed to the dialog creation function. Specify the pointer to the hook procedure in the lpfnHook member and specify the OFN_ENABLEHOOK flag in the Flags member.

If you provide a hook procedure for an Explorer-style common dialog box, the system creates a dialog box that is a child of the default dialog box. The hook procedure acts as the dialog procedure for the child dialog. This child dialog is based on the template you specified in the OPENFILENAME structure, or it is a default child dialog if no template is specified. The child dialog is created when the default dialog procedure is processing its WM_INITDIALOG message. After the child dialog processes its own WM_INITDIALOG message, the default dialog procedure moves the standard controls, if necessary, to make room for any additional controls of the child dialog. The system then sends the CDN_INITDONE notification message to the hook procedure.

The hook procedure does not receive messages intended for the standard controls of the default dialog box. You can subclass the standard controls, but this is discouraged because it may make your application incompatible with future versions of the common dialog box. However, the Explorer-style common dialogs provide a set of messages that the hook procedure can use to monitor and control the dialog. These include a set of WM_NOTIFY notification messages sent from the dialog, as well as messages that you can send to retrieve information from the dialog. For a complete list of these messages, see “Explorer-Style Hook Procedures.”

If the hook procedure processes the WM_CTLCOLORDLG message, it must return a valid brush handle for painting the background of the dialog box. In general, if it processes any WM_CTLCOLOR* message, it must return a valid brush handle for painting the background of the specified control.

Do not call the EndDialog function from the hook procedure. Instead, the hook procedure can call the PostMessage function to post a WM_COMMAND message with the IDABORT value to the dialog box procedure. Posting IDABORT closes the dialog box and causes the dialog box function to return FALSE. If you need to know why the hook procedure closed the dialog box, you must provide your own communication mechanism between the hook procedure and your application.

OFNHookProc is a placeholder for the application-defined or library-defined function name. The LPOFNHOOKPROC type is a pointer to either an OFNHookProc or OFNHookProcOldStyle hook procedure.

See Also

GetOpenFileName, GetSaveFileName, OFNHookProcOldStyle, OPENFILENAME


OFNHookProcOldStyle

An OFNHookProcOldStyle hook procedure is an application-defined or library-defined callback procedure that is used with the Open and Save As common dialog boxes. The hook procedure receives messages or notifications intended for the dialog box procedure.

If you specify the OFN_EXPLORER flag when you create an Open or Save As common dialog box, and you want a hook procedure, you must use an Explorer-style OFNHookProc hook procedure.

UINT APIENTRY OFNHookProcOldStyle(

HWND hdlg,	// handle to the dialog box window
UINT uiMsg	// message identifier
WPARAM wParam,	// message parameter
LPARAM lParam	// message parameter
);
Parameters

hdlg

Handle to the Open or Save As dialog box window for which the message is intended.

uiMsg

Identifies the message being received.

wParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

lParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

If the uiMsg parameter indicates the WM_INITDIALOG message, lParam is a pointer to an OPENFILENAME structure containing the values specified when the common dialog box was created.

Return Values

If the hook procedure returns zero, the default dialog box procedure processes the message.

If the hook procedure returns a nonzero value, the default dialog box procedure ignores the message.

Remarks

When you use the GetOpenFileName or GetSaveFileName functions to create an old-style Open or Save As dialog box, you can provide an OFNHookProcOldStyle hook procedure. To enable the hook procedure, use the OPENFILENAME structure that you passed to the dialog creation function. Specify the pointer to the hook procedure in the lpfnHook member and specify the OFN_ENABLEHOOK flag in the Flags member.

The default dialog box procedure processes the WM_INITDIALOG message before passing it to the hook procedure. For all other messages, the hook procedure receives the message first. Then, the return value of the hook procedure determines whether the default dialog procedure processes the message or ignores it.

If the hook procedure processes the WM_CTLCOLORDLG message, it must return a valid brush handle for painting the background of the dialog box. In general, if the hook procedure processes any WM_CTLCOLOR* message, it must return a valid brush handle for painting the background of the specified control.

Do not call the EndDialog function from the hook procedure. Instead, the hook procedure can call the PostMessage function to post a WM_COMMAND message with the IDABORT value to the dialog box procedure. Posting IDABORT closes the dialog box and causes the dialog box function to return FALSE. If you need to know why the hook procedure closed the dialog box, you must provide your own communication mechanism between the hook procedure and your application.

You can subclass the standard controls of the common dialog box. However, the common dialog box procedure may also subclass the controls. Because of this, you should subclass controls when your hook procedure processes the WM_INITDIALOG message. This ensures that your subclass procedure receives the control-specific messages before the subclass procedure set by the dialog box procedure.

OFNHookProcOldStyle is a placeholder for the application-defined or library-defined function name. The LPOFNHOOKPROC type is a pointer to either an OFNHookProcOldStyle or OFNHookProc hook procedure.

See Also

GetOpenFileName, GetSaveFileName, OFNHookProc, OPENFILENAME, WM_INITDIALOG


OpenBackupEventLog

The OpenBackupEventLog function opens a handle of a backup event log. This handle can be used with the BackupEventLog function.

HANDLE OpenBackupEventLog(

LPCTSTR lpUNCServerName,	// backup file server name
LPCTSTR lpFileName	// backup filename
);
Parameters

lpUNCServerName

Points to a null-terminated string that specifies the Universal Naming Convention (UNC) name of the server on which this operation is to be performed. If this parameter is NULL, the operation is performed on the local computer.

lpFileName

Points to a null-terminated string that specifies the name of the backup file. The backup filename may contain a server name to open a backup file on a remote server (in this case, the lpUNCServerName parameter must be NULL).

Return Values

If the function succeeds, the return value is a handle of the backup event log.

If the function fails, the return value is NULL.

Remarks

If the backup filename specifies a remote server, lpUNCServerName must be NULL. You cannot use this function to open a file on a remote server.

See Also

BackupEventLog


OpenClipboard

The OpenClipboard function opens the clipboard for examination and prevents other applications from modifying the clipboard content.

BOOL OpenClipboard(

HWND hWndNewOwner	// handle to window opening clipboard
);
Parameters

hWndNewOwner

Identifies the window to be associated with the open clipboard. If this parameter is NULL, the open clipboard is associated with the current task.

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.

Remarks

OpenClipboard fails if another window has the clipboard open.

An application should call the CloseClipboard function after every successful call to OpenClipboard.

The window identified by the hWndNewOwner parameter does not become the clipboard owner unless the EmptyClipboard function is called.

See Also

CloseClipboard, EmptyClipboard


OpenDesktop

The OpenDesktop function returns a handle to an existing desktop. A desktop is a secure object contained within a window station object. A desktop has a logical display surface and contains windows, menus and hooks.

HDESK OpenDesktop(

LPTSTR lpszDesktop,	// name of the desktop to open
DWORD dwFlags,	// flags to control interaction with other applications
BOOL fInherit,	// specifies whether returned handle is inheritable
DWORD dwDesiredAccess	// specifies access of returned handle
);
Parameters

lpszDesktop

Points to null-terminated string specifying the name of the desktop to be opened. Desktop names are case-insensitive.

dwFlags

A bit flag parameter that controls how the calling application will cooperate with other applications on the desktop. This parameter can specify zero or the following value:

Value	Description
DF_ALLOWOTHERACCOUNTHOOK	Allows processes running in other accounts on the desktop to set hooks in this process.
fInherit

Specifies whether the returned handle is inherited when a new process is created. If this value is TRUE, new processes will inherit the handle.

dwDesiredAccess

Specifies the type of access to the desktop. This parameter can be one or more of the following values:

Value	Description
DESKTOP_CREATEMENU	Required to create a menu on the desktop.
DESKTOP_CREATEWINDOW	Required to create a window on the desktop.
DESKTOP_ENUMERATE	Required for the desktop to be enumerated.
DESKTOP_HOOKCONTROL	Required to establish any of the window hooks.
DESKTOP_JOURNALPLAYBACK	Required to perform journal playback on the desktop.
DESKTOP_JOURNALRECORD	Required to perform journal recording on the desktop.
DESKTOP_READOBJECTS	Required to read objects on the desktop.
DESKTOP_SWITCHDESKTOP	Required to activate the desktop using SwitchDesktop.
DESKTOP_WRITEOBJECTS	Required to write objects on the desktop.
Return Values

If the function succeeds, the return value is the handle to the opened desktop.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The calling process must have an associated window station, either assigned by the system at process creation time or set by the SetProcessWindowStation function.

See Also

CreateDesktop, SetProcessWindowStation, SetThreadDesktop, SwitchDesktop


OpenEvent

The OpenEvent function returns a handle of an existing named event object.

HANDLE OpenEvent(

DWORD dwDesiredAccess,	// access flag
BOOL bInheritHandle,	// inherit flag
LPCTSTR lpName	// pointer to event-object name
);
Parameters

dwDesiredAccess

Specifies the requested access to the event object. For systems that support object security, the function fails if the security descriptor of the specified object does not permit the requested access for the calling process.

This parameter can be any combination of the following values:

Access	Description
EVENT_ALL_ACCESS	Specifies all possible access flags for the event object.
EVENT_MODIFY_STATE	Enables use of the event handle in the SetEvent and ResetEvent functions to modify the event’s state.
SYNCHRONIZE	Windows NT only: Enables use of the event handle in any of the wait functions to wait for the event’s state to be signaled.
bInheritHandle

Specifies whether the returned handle is inheritable. If TRUE, a process created by the CreateProcess function can inherit the handle; otherwise, the handle cannot be inherited.

lpName

Points to a null-terminated string that names the event to be opened. Name comparisons are case sensitive.

Return Values

If the function succeeds, the return value is a handle of the event object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The OpenEvent function enables multiple processes to open handles of the same event object. The function succeeds only if some process has already created the event by using the CreateEvent function. The calling process can use the returned handle in any function that requires a handle of an event object, subject to the limitations of the access specified in the dwDesiredAccess parameter.

The handle can be duplicated by using the DuplicateHandle function. Use the CloseHandle function to close the handle. The system closes the handle automatically when the process terminates. The event object is destroyed when its last handle has been closed.

See Also

CloseHandle, CreateEvent, CreateProcess, DuplicateHandle, PulseEvent, ResetEvent, SetEvent


OpenEventLog

The OpenEventLog function opens a handle of an event log.

HANDLE OpenEventLog(

LPCTSTR lpUNCServerName,	// pointer to server name
LPCTSTR lpSourceName	// pointer to source name
);
Parameters

lpUNCServerName

Points to a null-terminated string that specifies the Universal Naming Convention (UNC) name of the server on which the event log is to be opened. If this parameter is NULL, the log is opened on the local computer.

lpSourceName

Points to a null-terminated string that specifies the name of the source that the returned handle will reference. The source name must be a subkey of a logfile entry under the EventLog key in the registry. For example, the source name WinApp would be valid if the registry had the following form:

HKEY_LOCAL_MACHINE

  System

    CurrentControlSet

      Services

        EventLog

          Application

            WinApp

          Security

          System

If the source name cannot be found, the event logging service uses the Application logfile with no message files for the event identifier or category.

Return Values

If the function succeeds, the return value is the handle of an event log.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

ClearEventLog, CloseEventLog, GetNumberOfEventLogRecords, GetOldestEventLogRecord, ReadEventLog, ReportEvent


OpenFile

The OpenFile function creates, opens, reopens, or deletes a file.

This function is provided for compatibility with 16-bit versions of Windows. In particular, the OpenFile function cannot open a named pipe. Win32-based applications should use the CreateFile function.

HFILE OpenFile(

LPCSTR lpFileName,	// pointer to filename
LPOFSTRUCT lpReOpenBuff,	// pointer to buffer for file information
UINT uStyle	// action and attributes
);
Parameters

lpFileName

Points to a null-terminated string that names the file to be opened. The string must consist of characters from the Windows 3.x character set. The OpenFile function does not support Unicode filenames.

lpReOpenBuff

Points to the OFSTRUCT structure that receives information about the file when it is first opened. The structure can be used in subsequent calls to the OpenFile function to refer to the open file.

The OFSTRUCT structure contains a pathname string member whose length is limited to OFS_MAXPATHNAME characters. OFS_MAXPATHNAME is currently defined to be 128. Because of this, you cannot use the OpenFile function to open a file whose path length exceeds 128 characters. The CreateFile function does not have such a path length limitation.

uStyle

Specifies the action to take. The following values can be combined by using the bitwise OR operator:

Value	Meaning
OF_CANCEL	Ignored. In the Win32 application programming interface (API), the OF_PROMPT style produces a dialog box containing a Cancel button.
OF_CREATE	Creates a new file. If the file already exists, it is truncated to zero length.
OF_DELETE	Deletes the file.
OF_EXIST	Opens the file and then closes it. Used to test for a file’s existence.
OF_PARSE	Fills the OFSTRUCT structure but carries out no other action.
OF_PROMPT	Displays a dialog box if the requested file does not exist. The dialog box informs the user that Windows cannot find the file, and it contains Retry and Cancel buttons. Choosing the Cancel button directs OpenFile to return a file-not-found error message.
OF_READ	Opens the file for reading only.
OF_READWRITE	Opens the file for reading and writing.
OF_REOPEN	Opens the file using information in the reopen buffer.
OF_SHARE_COMPAT	For MS-DOS−based file systems using the Win32 API, opens the file with compatibility mode, allowing any process on a specified computer to open the file any number of times. Other efforts to open with any other sharing mode fail.  Windows NT: This flag is mapped to the CreateFile function's FILE_SHARE_READ | FILE_SHARE_WRITE flags.
OF_SHARE_DENY_NONE	Opens the file without denying read or write access to other processes. On MS-DOS-based file systems using the Win32 API, if the file has been opened in compatibility mode by any other process, the function fails.  Windows NT: This flag is mapped to the CreateFile function's FILE_SHARE_READ | FILE_SHARE_WRITE flags.
OF_SHARE_DENY_READ	Opens the file and denies read access to other processes. On MS-DOS-based file systems using the Win32 API, if the file has been opened in compatibility mode or for read access by any other process, the function fails.  Windows NT: This flag is mapped to the CreateFile function's FILE_SHARE_WRITE flag.
OF_SHARE_DENY_WRITE	Opens the file and denies write access to other processes. On MS-DOS-based file systems using the Win32 API, if the file has been opened in compatibility mode or for write access by any other process, the function fails.   Windows NT: This flag is mapped to the CreateFile function's FILE_SHARE_READ flag.
OF_SHARE_EXCLUSIVE	Opens the file with exclusive mode, denying both read and write access to other processes. If the file has been opened in any other mode for read or write access, even by the current process, the function fails.
OF_VERIFY	Verifies that the date and time of the file are the same as when it was previously opened. This is useful as an extra check for read-only files.
OF_WRITE	Opens the file for writing only.
Return Values

If the function succeeds, the return value specifies a file handle.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

Remarks

If the lpFileName parameter specifies a filename and extension only, this function searches for a matching file in the following directories, in the order shown:

1.	The directory from which the application loaded.

2.	The current directory.

3.	Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path of this directory.

Windows NT: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	Windows NT: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

The lpFileName parameter cannot contain wildcard characters.

The Win32 OpenFile function does not support the OF_SEARCH flag supported by the 16-bit Windows OpenFile function. The OF_SEARCH flag directs Windows to search for a matching file even when the filename includes a full path. To search for a file in a Win32-based application, use the SearchPath function.

To close the file after use, call the _lclose function.

See Also

CreateFile, GetSystemDirectory, GetWindowsDirectory, _lclose, OFSTRUCT, SearchPath


OpenFileMapping

The OpenFileMapping function opens a named file-mapping object.

HANDLE OpenFileMapping(

DWORD dwDesiredAccess,	// access mode
BOOL bInheritHandle,	// inherit flag
LPCTSTR lpName	// pointer to name of file-mapping object
);
Parameters

dwDesiredAccess

Specifies the access to the file-mapping object.

Windows NT:

This access is checked against any security descriptor on the target file-mapping object.

Windows 95:

Windows 95 does not support security descriptors on file mapping objects.

This parameter can be one of the following values:

Value	Meaning
FILE_MAP_WRITE	Read-write access. The target file-mapping object must have been created with PAGE_READWRITE protection. A read-write view of the file is mapped.
FILE_MAP_READ	Read-only access. The target file-mapping object must have been created with PAGE_READWRITE or PAGE_READ protection. A read-only view of the file is mapped.
FILE_MAP_ALL_ACCESS	Same as FILE_MAP_WRITE.
FILE_MAP_COPY	Copy-on-write access. The target file-mapping object must have been created with PAGE_WRITECOPY protection. A copy-on-write view of the file is mapped.
bInheritHandle

Specifies whether the returned handle is to be inherited by a new process during process creation. A value of TRUE indicates that the new process inherits the handle.

lpName

Points to a string that names the file-mapping object to be opened. If there is an open handle to a file-mapping object by this name and the security descriptor on the mapping object does not conflict with the dwDesiredAccess parameter, the open operation succeeds.

Return Values

If the function succeeds, the return value is an open handle to the specified file-mapping object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The handle that OpenFileMapping returns can be used with any function that requires a handle to a file-mapping object.

See Also

CreateFileMapping


OpenIcon

The OpenIcon function restores a minimized (iconic) window to its previous size and position; it then activates the window.

BOOL OpenIcon(

HWND hWnd	// handle to window
);
Parameters

hWnd

Identifies the window to be restored and activated.

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.

Remarks

OpenIcon sends a WM_QUERYOPEN message to the given window.

See Also

CloseWindow, IsIconic, ShowWindow


OpenInputDesktop

The OpenInputDesktop function returns a handle to the desktop that receives user input. The input desktop is a desktop on the window station associated with the logged-on user.

HDESK OpenInputDesktop(

DWORD dwFlags,	// flags to control interaction with other applications
BOOL fInherit,	// specifies whether returned handle is inheritable
DWORD dwDesiredAccess	// specifies access of returned handle
);
Parameters

dwFlags

A bit flag parameter that controls how the calling application will cooperate with other applications on the desktop. This parameter can specify zero or the following value:

Value	Description
DF_ALLOWOTHERACCOUNTHOOK	Allows processes running in other accounts on the desktop to set hooks in this process.
fInherit

Specifies whether the returned handle is inherited when a new process is created. If this value is TRUE, new processes will inherit the handle.

dwDesiredAccess

Specifies the type of access to the desktop. This parameter can be one or more of the following values:

Value	Description
DESKTOP_CREATEMENU	Required to create a menu on the desktop.
DESKTOP_CREATEWINDOW	Required to create a window on the desktop.
DESKTOP_ENUMERATE	Required for the desktop to be enumerated.
DESKTOP_HOOKCONTROL	Required to establish any of the window hooks.
DESKTOP_JOURNALPLAYBACK	Required to perform journal playback on the desktop.
DESKTOP_JOURNALRECORD	Required to perform journal recording on the desktop.
DESKTOP_READOBJECTS	Required to read objects on the desktop.
DESKTOP_SWITCHDESKTOP	Required to activate the desktop using SwitchDesktop.
DESKTOP_WRITEOBJECTS	Required to write objects on the desktop.
Return Values

If the function succeeds, the return value is a handle of the desktop that receives user input.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The calling process must have an associated window station, either assigned by the system at process creation time or set by SetProcessWindowStation The window station associated with the calling process must be capable of receiving input.

An application can use the SwitchDesktop function to change the input desktop.

See Also

SetProcessWindowStation, SwitchDesktop


OpenMutex

The OpenMutex function returns a handle of an existing named mutex object.

HANDLE OpenMutex(

DWORD dwDesiredAccess,	// access flag
BOOL bInheritHandle,	// inherit flag
LPCTSTR lpName	// pointer to mutex-object name
);
Parameters

dwDesiredAccess

Specifies the requested access to the mutex object. For systems that support object security, the function fails if the security descriptor of the specified object does not permit the requested access for the calling process.

This parameter can be any combination of the following values:

Access	Description
MUTEX_ALL_ACCESS	Specifies all possible access flags for the mutex object.
SYNCHRONIZE	Windows NT only: Enables use of the mutex handle in any of the wait functions to acquire ownership of the mutex, or in the ReleaseMutex function to release ownership.
bInheritHandle

Specifies whether the returned handle is inheritable. If TRUE, a process created by the CreateProcess function can inherit the handle; otherwise, the handle cannot be inherited.

lpName

Points to a null-terminated string that names the mutex to be opened. Name comparisons are case sensitive.

Return Values

If the function succeeds, the return value is a handle of the mutex object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The OpenMutex function enables multiple processes to open handles of the same mutex object. The function succeeds only if some process has already created the mutex by using the CreateMutex function. The calling process can use the returned handle in any function that requires a handle of a mutex object, such as the wait functions, subject to the limitations of the access specified in the dwDesiredAccess parameter.

The handle can be duplicated by using the DuplicateHandle function. Use the CloseHandle function to close the handle. The system closes the handle automatically when the process terminates. The mutex object is destroyed when its last handle has been closed.

See Also

CloseHandle, CreateMutex, CreateProcess, DuplicateHandle, ReleaseMutex


OpenPrinter

The OpenPrinter function retrieves a handle identifying the specified printer or print server.

BOOL OpenPrinter(

LPTSTR pPrinterName,	// pointer to printer or server name
LPHANDLE phPrinter,	// pointer to printer or server handle
LPPRINTER_DEFAULTS pDefault	// pointer to printer defaults structure
);
Parameters

pPrinterName

Points to a null-terminated string that specifies the name of the printer or print server.

phPrinter

Points to a variable that receives the handle identifying the opened printer or print server object.

pDefault

Points to a PRINTER_DEFAULTS structure. This value can be NULL.

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.

Remarks

The pDefault parameter allows an application to specify the data type and device mode values that are used for printing documents submitted by the StartDocPrinter function. However, these values can be overridden by using the SetJob function once a document has been started.

The DesiredAccess member of the PRINTER_DEFAULTS data structure pointed to by pDefault specifies the accesses that an application wishes to perform using the handle returned by OpenPrinter. If an application wishes to open a printer to perform administrative tasks, such as the SetPrinter function, it should open the printer with PRINTER_ALL_ACCESS access. If an application wishes only to perform basic printing operations, an access value that includes PRINTER_ACCESS_USE is sufficient.

Windows 95: OpenPrinter ignores the DesiredAccess member of PRINTER_DEFAULTS.

An application can determine what permissions a client has on a print server, or obtain a handle to a print server to call WaitForPrinterChange. To do so, it should call OpenPrinter with pPrinterName set to the name of the server and should specify a server access mask value such as SERVER_ALL_ACCESS. The pDatatype and pDevMode members of the PRINTER_DEFAULTS data structure should be set to NULL. The handle returned by such a call may be passed to the ClosePrinter or WaitForPrinterChange function.

If a user does not hold permission to open a specified printer or print server with the desired access, the OpenPrinter call will fail, and GetLastError will return the value ERROR_ACCESS_DENIED.

See Also

ClosePrinter, SetPrinter, StartDocPrinter, WaitForPrinterChange, PRINTER_DEFAULTS


OpenProcess

The OpenProcess function returns a handle of an existing process object.

HANDLE OpenProcess(

DWORD dwDesiredAccess,	// access flag
BOOL bInheritHandle,	// handle inheritance flag
DWORD dwProcessId	// process identifier
);
Parameters

dwDesiredAccess

Specifies the access to the process object. For operating systems that support security checking, this access is checked against any security descriptor for the target process. Any combination of the following access flags can be specified in addition to the STANDARD_RIGHTS_REQUIRED access flags:

Access	Description
PROCESS_ALL_ACCESS	Specifies all possible access flags for the process object.
PROCESS_CREATE_PROCESS	Used internally.
PROCESS_CREATE_THREAD	Enables using the process handle in the CreateRemoteThread function to create a thread in the process.
PROCESS_DUP_HANDLE	Enables using the process handle as either the source or target process in the DuplicateHandle function to duplicate a handle.
PROCESS_QUERY_INFORMATION	Enables using the process handle in the GetExitCodeProcess and GetPriorityClass functions to read information from the process object.
PROCESS_SET_INFORMATION	Enables using the process handle in the SetPriorityClass function to set the priority class of the process.
PROCESS_TERMINATE	Enables using the process handle in the TerminateProcess function to terminate the process.
PROCESS_VM_OPERATION	Enables using the process handle in the VirtualProtectEx and WriteProcessMemory functions to modify the virtual memory of the process.
PROCESS_VM_READ	Enables using the process handle in the ReadProcessMemory function to read from the virtual memory of the process.
PROCESS_VM_WRITE	Enables using the process handle in the WriteProcessMemory function to write to the virtual memory of the process.
SYNCHRONIZE	Windows NT only: Enables using the process handle in any of the wait functions to wait for the process to terminate.
bInheritHandle

Specifies whether the returned handle can be inherited by a new process created by the current process. If TRUE, the handle is inheritable.

dwProcessId

Specifies the process identifier of the process to open.

Return Values

If the function succeeds, the return value is an open handle of the specified process.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The handle returned by the OpenProcess function can be used in any function that requires a handle to a process, such as the wait functions, provided the appropriate access rights were requested.

When you are finished with the handle, be sure to close it using the CloseHandle function.

See Also

CloseHandle, CreateProcess, CreateRemoteThread, DuplicateHandle, GetCurrentProcess, GetCurrentProcessId, GetExitCodeProcess, GetPriorityClass, ReadProcessMemory, SetPriorityClass, TerminateProcess, VirtualProtectEx, WriteProcessMemory


OpenProcessToken

The OpenProcessToken function opens the access token associated with a process.

BOOL OpenProcessToken(

HANDLE ProcessHandle,	// handle to process
DWORD DesiredAccess,	// desired access to process
PHANDLE TokenHandle	// pointer to handle of open access token
);
Parameters

ProcessHandle

Identifies the process whose access token is opened.

DesiredAccess

Specifies an access mask that specifies the requested types of access to the access token. These requested access types are compared with the token’s discretionary access-control list (ACL) to determine which accesses are granted or denied. The following access rights have been defined for access tokens.

Value	Meaning
TOKEN_ADJUST_DEFAULT	Required to change the default ACL, primary group, or owner of an access token.
TOKEN_ADJUST_GROUPS	Required to change the groups specified in an access token.
TOKEN_ADJUST_PRIVILEGES	Required to change the privileges specified in an access token.
TOKEN_ALL_ACCESS	Combines the STANDARD_RIGHTS_REQUIRED standard access rights and all individual access rights for tokens.
TOKEN_ASSIGN_PRIMARY	Required to attach a primary token to a process in addition to the SE_CREATE_TOKEN_NAME privilege.
TOKEN_DUPLICATE	Required to duplicate an access token.
TOKEN_EXECUTE	Combines the STANDARD_RIGHTS_EXECUTE standard access rights and the TOKEN_IMPERSONATE access right.
TOKEN_IMPERSONATE	Required to attach an impersonation access token to a process.
TOKEN_QUERY	Required to query the contents of an access token.
TOKEN_QUERY_SOURCE	Required to query the source of an access token.
TOKEN_READ	Combines the STANDARD_RIGHTS_READ standard access rights and the TOKEN_QUERY access right.
TOKEN_WRITE	Combines the STANDARD_RIGHTS_WRITE standard access rights and the TOKEN_ADJUST_PRIVILEGES, TOKEN_ADJUST_GROUPS, and TOKEN_ADJUST_DEFAULT access rights.
TokenHandle

Points to a handle identifying the newly-opened access token when the function returns.

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.

See Also

AdjustTokenGroups, AdjustTokenPrivileges, GetTokenInformation, OpenThreadToken, SetTokenInformation


OpenSCManager

The OpenSCManager function establishes a connection to the service control manager on the specified computer and opens the specified database.

SC_HANDLE OpenSCManager(

LPCTSTR lpMachineName,	// pointer to machine name string
LPCTSTR lpDatabaseName,	// pointer to database name string
DWORD dwDesiredAccess	// type of access
);
Parameters

lpMachineName

Points to a null-terminated string that names the target computer. If the pointer is NULL or if it points to an empty string, the function connects to the service control manager on the local computer.

lpDatabaseName

Points to a null-terminated string that names the service control manager database to open. This string should specify ServicesActive. If the pointer is NULL, the ServicesActive database is opened by default.

dwDesiredAccess

Specifies the access to the service control manager. Before granting the requested access, the system checks the access token of the calling process against the discretionary access-control list of the security descriptor associated with the service control manager object. The SC_MANAGER_CONNECT access type is implicitly specified by calling this function. In addition, any or all of the following service control manager object access types can be specified:

Type	Description
SC_MANAGER_ALL_ACCESS
	Includes STANDARD_RIGHTS_REQUIRED, in addition to all of the access types listed in this table.
SC_MANAGER_CONNECT
	Enables connecting to the service control manager.
SC_MANAGER_CREATE_SERVICE
	Enables calling of the CreateService function to create a service object and add it to the database.
SC_MANAGER_ENUMERATE_SERVICE
	Enables calling of the EnumServicesStatus function to list the services that are in the database.
SC_MANAGER_LOCK
	Enables calling of the LockServiceDatabase function to acquire a lock on the database.
SC_MANAGER_QUERY_LOCK_STATUS
	Enables calling of the QueryServiceLockStatus function to retrieve the lock status information for the database.
The dwDesiredAccess parameter can specify any or all of the following generic access types:

Generic access	Service manager access
GENERIC_READ	Combines the following access: STANDARD_RIGHTS_READ, SC_MANAGER_ENUMERATE_SERVICE, and SC_MANAGER_QUERY_LOCK_STATUS.
GENERIC_WRITE	Combines the following access: STANDARD_RIGHTS_WRITE, SC_MANAGER_CREATE_SERVICE, and SC_MANAGER_MODIFY_BOOT_CONFIG.
GENERIC_EXECUTE	Combines the following access: STANDARD_RIGHTS_EXECUTE, SC_MANAGER_CONNECT, and SC_MANAGER_LOCK.
Return Values

If the function succeeds, the return value is a handle to the specified service control manager database.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Error code	Meaning
ERROR_ACCESS_DENIED	The requested access was denied.
ERROR_DATABASE_DOES_NOT_EXIST	The specified database does not exist.
ERROR_INVALID_PARAMETER	A parameter that was specified is invalid.
Remarks

When a process uses the OpenSCManager function to open a handle to a service control manager database, the system performs a security check before granting the requested access. All processes are permitted SC_MANAGER_CONNECT, SC_MANAGER_ENUMERATE_SERVICE, and SC_MANAGER_QUERY_LOCK_STATUS access to all service control manager databases. This enables any process to open a service control manager database handle that it can use in the OpenService, EnumServicesStatus, and QueryServiceLockStatus functions. Only processes with Administrator privileges are able to open a database handle used by the CreateService and LockServiceDatabase functions.

The calling process can use the returned handle to identify the database in the following functions, if the appropriate access rights are enabled:

CreateService
EnumServicesStatus
LockServiceDatabase
OpenService
QueryServiceLockStatus

The returned handle is only valid for the process that called the OpenSCManager function. It can be closed by calling the CloseServiceHandle function.

See Also

CloseServiceHandle, CreateService, EnumServicesStatus, LockServiceDatabase, OpenService, QueryServiceLockStatus


OpenSemaphore

The OpenSemaphore function returns a handle of an existing named semaphore object.

HANDLE OpenSemaphore(

DWORD dwDesiredAccess,	// access flag
BOOL bInheritHandle,	// inherit flag
LPCTSTR lpName	// pointer to semaphore-object name
);
Parameters

dwDesiredAccess

Specifies the requested access to the semaphore object. For systems that support object security, the function fails if the security descriptor of the specified object does not permit the requested access for the calling process.

This parameter can be any combination of the following values:

Access	Description
SEMAPHORE_ALL_ACCESS	Specifies all possible access flags for the semaphore object.
SEMAPHORE_MODIFY_STATE	Enables use of the semaphore handle in the ReleaseSemaphore function to modify the semaphore’s count.
SYNCHRONIZE	Windows NT only: Enables use of the semaphore handle in any of the wait functions to wait for the semaphore’s state to be signaled.
bInheritHandle

Specifies whether the returned handle is inheritable. If TRUE, a process created by the CreateProcess function can inherit the handle; otherwise, the handle cannot be inherited.

lpName

Points to a null-terminated string that names the semaphore to be opened. Name comparisons are case sensitive.

Return Values

If the function succeeds, the return value is a handle of the semaphore object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The OpenSemaphore function enables multiple processes to open handles of the same semaphore object. The function succeeds only if some process has already created the semaphore by using the CreateSemaphore function. The calling process can use the returned handle in any function that requires a handle of a semaphore object, such as the wait functions, subject to the limitations of the access specified in the dwDesiredAccess parameter.

The handle can be duplicated by using the DuplicateHandle function. Use the CloseHandle function to close the handle. The system closes the handle automatically when the process terminates. The semaphore object is destroyed when its last handle has been closed.

See Also

CloseHandle, CreateSemaphore, DuplicateHandle, ReleaseSemaphore


OpenService

The OpenService function opens a handle to an existing service.

SC_HANDLE OpenService(

SC_HANDLE hSCManager,	// handle to service control manager database
LPCTSTR lpServiceName,	// pointer to name of service to start
DWORD dwDesiredAccess	// type of access to service
);
Parameters

hSCManager

Identifies the service control manager (SCM) database. The OpenSCManager function returns this handle.

lpServiceName

Points to a null-terminated string that names the service to open. The maximum string length is 256 characters. The SCM database preserves the case of the characters, but service name comparisons are always case insensitive. A slash (/), backslash (\), comma, and space are invalid service name characters.

dwDesiredAccess

Specifies the access to the service. Before granting the requested access, the system checks the access token of the calling process against the discretionary access-control list of the security descriptor associated with the service object. Any or all of the following service object access types can be specified:

Access	Description
SERVICE_ALL_ACCESS	Includes STANDARD_RIGHTS_REQUIRED in addition to all of the access types listed in this table.
SERVICE_CHANGE_CONFIG	Enables calling of the ChangeServiceConfig function to change the service configuration.
SERVICE_ENUMERATE_DEPENDENTS	Enables calling of the EnumDependentServices function to enumerate all the services dependent on the service.
SERVICE_INTERROGATE	Enables calling of the ControlService function to ask the service to report its status immediately.
SERVICE_PAUSE_CONTINUE	Enables calling of the ControlService function to pause or continue the service.
SERVICE_QUERY_CONFIG	Enables calling of the QueryServiceConfig function to query the service configuration.
SERVICE_QUERY_STATUS	Enables calling of the QueryServiceStatus function to ask the service control manager about the status of the service.
SERVICE_START	Enables calling of the StartService function to start the service.
SERVICE_STOP	Enables calling of the ControlService function to stop the service.
SERVICE_USER_DEFINED_CONTROL	Enables calling of the ControlService function to specify a user-defined control code.
STANDARD_RIGHTS_REQUIRED enables the following service object access types:

Standard rights	Description
DELETE	Enables calling of the DeleteService function to delete the service.
READ_CONTROL	Enables calling of the QueryServiceObjectSecurity function to query the security descriptor of the service object.
WRITE_DAC|WRITE_OWNER	Enables calling of the SetServiceObjectSecurity function to modify the security descriptor of the service object.
The dwDesiredAccess parameter can specify any or all of the following generic access types:

Generic access	Service access
GENERIC_READ	Combines the following access: STANDARD_RIGHTS_READ, SERVICE_QUERY_CONFIG, SERVICE_QUERY_STATUS, SERVICE_INTERROGATE, and SERVICE_ENUMERATE_DEPENDENTS.
GENERIC_WRITE	Combines the following access: STANDARD_RIGHTS_WRITE and SERVICE_CHANGE_CONFIG.
GENERIC_EXECUTE	Combines the following access: STANDARD_RIGHTS_EXECUTE, SERVICE_START, SERVICE_STOP, SERVICE_PAUSE_CONTINUE, and SERVICE_USER_DEFINED_CONTROL.
Return Values

If the function succeeds, the return value is a handle to the service.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Errors

The following error codes can be set by the service control manager. Others can be set by the registry functions that are called by the service control manager.

Error code	Meaning
ERROR_ACCESS_DENIED	The specified service control manager database handle does not have access to the service.
ERROR_INVALID_HANDLE	The specified handle is invalid.
ERROR_INVALID_NAME	The specified service name is invalid.
ERROR_SERVICE_DOES_NOT_EXIST	The specified service does not exist.
Remarks

The calling process can use the returned handle to identify the service in the following functions, if the appropriate access rights are enabled:

ChangeServiceConfig
ControlService
DeleteService
EnumDependentServices
QueryServiceConfig
QueryServiceObjectSecurity
QueryServiceStatus
SetServiceObjectSecurity
StartService

The returned handle is only valid for the process that called OpenService. It can be closed by calling the CloseServiceHandle function.

See Also

ChangeServiceConfig, ControlService, CreateService, DeleteService, EnumDependentServices, OpenSCManager, QueryServiceConfig, QueryServiceObjectSecurity, QueryServiceStatus, SetServiceObjectSecurity, StartService


OpenThreadToken

The OpenThreadToken function opens the access token associated with a thread.

BOOL OpenThreadToken(

HANDLE ThreadHandle,	// handle to thread
DWORD DesiredAccess,	// access to process
BOOL OpenAsSelf,	// flag for process or thread security
PHANDLE TokenHandle	// pointer to handle to open access token
);
Parameters

ThreadHandle

Identifies the thread whose access token is opened.

DesiredAccess

Specifies an access mask that specifies the requested types of access to the access token. These requested access types are reconciled against the token’s discretionary access-control list (ACL) to determine which accesses are granted or denied. The following access rights have been defined for access tokens.

Value	Meaning
TOKEN_ADJUST_DEFAULT	Required to change the default ACL, primary group, or owner of an access token.
TOKEN_ADJUST_GROUPS	Required to change the groups specified in an access token.
TOKEN_ADJUST_PRIVILEGES	Required to change the privileges specified in an access token.
TOKEN_ALL_ACCESS	Combines the STANDARD_RIGHTS_REQUIRED standard access rights and all individual access rights for tokens.
TOKEN_ASSIGN_PRIMARY	Required to attach a primary token to a process in addition to the SE_CREATE_TOKEN_NAME privilege.
TOKEN_DUPLICATE	Required to duplicate an access token.
TOKEN_EXECUTE	Combines the STANDARD_RIGHTS_EXECUTE standard access rights and the TOKEN_IMPERSONATE access right.
TOKEN_IMPERSONATE	Required to attach an impersonation access token to a process.
TOKEN_QUERY	Required to query the contents of an access token.
TOKEN_QUERY_SOURCE	Required to query the source of an access token.
TOKEN_READ	Combines the STANDARD_RIGHTS_READ standard access rights and the TOKEN_QUERY access right.
TOKEN_WRITE	Combines the STANDARD_RIGHTS_WRITE standard access rights and the TOKEN_ADJUST_PRIVILEGES, TOKEN_ADJUST_GROUPS, and TOKEN_ADJUST_DEFAULT access rights.
OpenAsSelf

Specifies a flag indicating whether the access check is to be made against the security context of the thread calling the OpenThreadToken function or against the security context of the process for the calling thread.

If this parameter is FALSE, the access check is performed using the security context for the calling thread. If the thread is impersonating a client, this security context can be that of a client process. If this parameter is TRUE, the access check is made using the security context of the process for the calling thread.

TokenHandle

Points to a handle identifying the newly opened access token when the function returns.

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.

Remarks

The OpenAsSelf parameter allows a server process to open the access token for a client process when the client process has specified the SecurityIdentification impersonation level for the SECURITY_IMPERSONATION_LEVEL enumerated type. Without this parameter, the calling process is not be able to open the client’s access token using the client’s security context, because it is impossible to open executive-level objects using the SecurityIdentification impersonation level.

See Also

AdjustTokenGroups, AdjustTokenPrivileges, GetTokenInformation, OpenProcessToken, SetThreadToken, SetTokenInformation


OpenWaitableTimer [New - Windows NT]
OpenWaitableTimer

[New - Windows NT]

The OpenWaitableTimer function returns a handle to an existing named “waitable” timer object.

HANDLE OpenWaitableTimer(

DWORD dwDesiredAccess,	// access flag
BOOL bInheritHandle,	// inherit flag
LPCTSTR lpTimerName	// pointer to timer object name
);
Parameters

dwDesiredAccess

Specifies the requested access to the timer object. For systems that support object security, the function fails if the security descriptor of the specified object does not permit the requested access for the calling process.

This parameter can be any combination of the following values:

Value	Meaning
TIMER_ALL_ACCESS	Specifies all possible access rights for the timer object.
TIMER_MODIFY_STATE	Enables use of the timer handle in the SetWaitableTimer and CancelWaitableTimer functions to modify the timer’s state.
SYNCHRONIZE	Enables use of the timer handle in any of the wait functions to wait for the timer’s state to be signaled.
bInheritHandle

Specifies whether the returned handle is inheritable. If TRUE, a process created by the CreateProcess function can inherit the handle; otherwise, the handle cannot be inherited.

lpTimerName

Points to a null-terminated string specifying the name of the timer object. The name is limited to MAX_PATH characters and can contain any character except the backslash path-separator character (\). Name comparison is case sensitive.

Return Value

If the function succeeds, the return value is a handle to the timer object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The OpenWaitableTimer function enables multiple processes to open handles to the same timer object. The function succeeds only if some process has already created the timer using the CreateWaitableTimer function. The calling process can use the returned handle in any function that requires the handle of a timer object, such as the wait functions, subject to the limitations of the access specified in the dwDesiredAccess parameter.

The returned handle can be duplicated by using the DuplicateHandle function. Use the CloseHandle function to close the handle. The system closes the handle automatically when the process terminates. The timer object is destroyed when its last handle has been closed.

See Also

CancelWaitableTimer, CloseHandle, CreateProcess, CreateWaitableTimer, DuplicateHandle, SetWaitableTimer


OpenWindowStation

The OpenWindowStation function returns a handle to an existing window station.

HWINSTA OpenWindowStation(

LPTSTR lpszWinSta,	// name of the window station to open
BOOL fInherit,	// specifies whether returned handle is inheritable
DWORD dwDesiredAccess	// specifies access of returned handle
);
Parameters

lpszWinSta

Points to a null-terminated string specifying the name of the window station to be opened. Window station names are case-insensitive.

fInherit

Specifies whether the returned handle is inherited when a new process is created. If this value is TRUE, new processes will inherit the handle.

dwDesiredAccess

Specifies the type of access to the window station. This parameter can be one or more of the following values:

Value	Description
WINSTA_ACCESSCLIPBOARD	Required to use the clipboard.
WINSTA_ACCESSGLOBALATOMS	Required to manipulate global atoms.
WINSTA_CREATEDESKTOP	Required to create new desktop objects on the window station.
WINSTA_ENUMDESKTOPS	Required to enumerate existing desktop objects.
WINSTA_ENUMERATE	Required for the window station to be enumerated.
WINSTA_EXITWINDOWS	Required to successfully call the ExitWindows and ExitWindowsEx functions.
WINSTA_READATTRIBUTES	Required to read the attributes of a window station object.
WINSTA_READSCREEN	Required to access screen contents.
WINSTA_WRITEATTRIBUTES	Required to modify the attributes of a window station object.
Return Values

If the function succeeds, the return value is the handle to the specified window station.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

ExitWindows, ExitWindowsEx


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.

See Also

RASADFunc, RasDial, RASENTRY, RasSetEntryProperties


OutputDebugString

The OutputDebugString function sends a string to the debugger for the current application.

VOID OutputDebugString(

LPCTSTR lpOutputString	// pointer to string to be displayed
);
Parameters

lpOutputString

Points to the null-terminated string to be displayed.

Return Values

This function does not return a value.

Remarks

If the application has no debugger, the system debugger displays the string. If the application has no debugger and the system debugger is not active, OutputDebugString does nothing.


OutputProc

The OutputProc function is an application-defined callback function that draws a string as a result of a call to the GrayString function.

BOOL CALLBACK OutputProc(

HDC hdc,	// handle to device context
LPARAM lpData,	// pointer to string to be drawn
int cchData	// length of string to be drawn
);
Parameters

hdc

Identifies a device context with a bitmap of at least the width and height specified by the nWidth and nHeight parameters passed to GrayString.

lpData

Points to the string to be drawn.

cchData

Specifies the length, in characters, of the string.

Return Values

If it succeeds, the callback function should return TRUE.

If the function fails, the return value is FALSE.

Remarks

The callback function must draw an image relative to the coordinates (0,0).

OutputProc is a placeholder for the application-defined function name.

See Also

GrayString


PackDDElParam

The PackDDElParam function packs a DDE lParam value into an internal structure used for sharing DDE data between processes.

LONG PackDDElParam(

UINT msg,	// DDE message to be posted
UINT uiLo,	// low-order word of lParam of message
UINT uiHi	// high-order word of lParam of message
);
Parameters

msg

Specifies the DDE message to be posted.

uiLo

Specifies a value that corresponds to the Windows 3.x low-order word of an lParam parameter for the DDE message being posted.

uiHi

Specifies a value that corresponds to the Windows 3.x high-order word of an lParam parameter for the DDE message being posted.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The return value must be posted as the lParam parameter of a DDE message; it must not be used for any other purpose. Once the application posts a return value, it need not perform any action to dispose of the lParam parameter.

PackDDElParam eases the porting of 16-bit DDE applications to 32-bit DDE applications.

An application should call this function only for posted DDE messages.

See Also

FreeDDElParam, ReuseDDElParam, UnpackDDElParam


PagePaintHook

A PagePaintHook hook procedure is an application-defined or library-defined callback procedure that is used with the Page Setup dialog box. The hook procedure receives messages that allow you to customize drawing of the sample page in the Page Setup dialog box.

UINT APIENTRY PagePaintHook(

HWND hdlg,	// handle to the dialog box window
UINT uiMsg,	// message identifier
WPARAM wParam,	// message parameter
LPARAM lParam	// message parameter
);
Parameters

hdlg

Handle to the Page Setup dialog box window.

uiMsg

Identifies the message being received.

wParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

lParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

Return Values

If the hook procedure returns TRUE for any of the first three messages of a drawing sequence (WM_PSD_PAGESETUPDLG, WM_PSD_FULLPAGERECT, or WM_PSD_MINMARGINRECT), the dialog box sends no more messages and does not draw in the sample page until the next time the system needs to redraw the sample page. If the hook procedure returns FALSE for all three messages, the dialog box sends the remaining messages of the drawing sequence.

If the hook procedure returns TRUE for any of the remaining messages in a drawing sequence, the dialog box does not draw the corresponding portion of the sample page. If the hook procedure returns FALSE for any of these messages, the dialog box draws that portion of the sample page.

Remarks

The Page Setup dialog box includes an image of a sample page that shows how the user’s selections affect the appearance of the printed output. The image consists of a rectangle that represents the selected paper or envelope type, with a dotted-line rectangle representing the current margins, and partial (greek text) characters to show how text looks on the printed page. When you use the PageSetupDlg function to create a Page Setup dialog box, you can provide a PagePaintHook hook procedure to customize the appearance of the sample page.

To enable the hook procedure, use the PAGESETUPDLG structure that you passed to the dialog creation function. Specify the pointer to the hook procedure in the lpfnPagePaintHook member and specify the PSD_ENABLEPAGEPAINTHOOK flag in the Flags member.

Whenever the dialog box is about to draw the contents of the sample page, the hook procedure receives the following messages in the order in which they are listed:

Message	Meaning
WM_PSD_PAGESETUPDLG	The dialog box is about to draw the sample page. The hook procedure can use this message to prepare to draw the contents of the sample page.
WM_PSD_FULLPAGERECT	The dialog box is about to draw the sample page. This message specifies the bounding rectangle of the sample page.
WM_PSD_MINMARGINRECT	The dialog box is about to draw the sample page. This message specifies the margin rectangle.
WM_PSD_MARGINRECT	The dialog box is about to draw the margin rectangle.
WM_PSD_GREEKTEXTRECT	The dialog box is about to draw the greek text inside the margin rectangle.
WM_PSD_ENVSTAMPRECT	The dialog box is about to draw in the envelope-stamp rectangle of an envelope sample page. This message is sent for envelopes only.
WM_PSD_YAFULLPAGERECT	The dialog box is about to draw the return address portion of an envelope sample page. This message is sent for envelopes and other paper sizes.
PagePaintHook is a placeholder for the application-defined or library-defined function name. The LPPAGEPAINTHOOK type is a pointer to a PagePaintHook hook procedure.

See Also

PageSetupDlg, PAGESETUPDLG


PageSetupDlg

The PageSetupDlg function creates a Page Setup dialog box that enables the user to specify the attributes of a printed page. These attributes include the paper size and source, the page orientation (portrait or landscape), and the width of the page margins.

BOOL PageSetupDlg(

LPPAGESETUPDLG lppsd	pointer to a structure
);
Parameters

lppsd

Pointer to a PAGESETUPDLG structure that contains information used to initialize the dialog box. The structure receives information about the user’s selections when the function returns.

Return Values

If the user clicks the OK button, the return value is nonzero. The members of the PAGESETUPDLG structure pointed to by the lppsd parameter indicate the user’s selections.

If the user cancels or closes the Page Setup dialog box or an error occurs, the return value is zero. To get extended error information, use the CommDlgExtendedError function

See Also

CommDlgExtendedError, PagePaintHook, PAGESETUPDLG, PageSetupHook


PageSetupHook

A PageSetupHook hook procedure is an application-defined or library-defined callback procedure that is used with the Page Setup common dialog box. The hook procedure receives messages or notifications intended for the default dialog box procedure.

UINT APIENTRY PageSetupHook(

HWND hdlg,	// handle to the dialog box window
UINT uiMsg,	// message identifier
WPARAM wParam,	// message parameter
LPARAM lParam	// message parameter
);
Parameters

hdlg

Handle to the Page Setup dialog box window for which the message is intended.

uiMsg

Identifies the message being received.

wParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

lParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

If the uiMsg parameter indicates the WM_INITDIALOG message, lParam is a pointer to a PAGESETUPDLG structure containing the values specified when the common dialog box was created.

Return Values

If the hook procedure returns zero, the default dialog box procedure processes the message.

If the hook procedure returns a nonzero value, the default dialog box procedure ignores the message.

Remarks

When you use the PageSetupDlg function to create a Page Setup common dialog box, you can provide a PageSetupHook hook procedure to process messages or notifications intended for the dialog box procedure. To enable the hook procedure, use the PAGESETUPDLG structure that you passed to the dialog creation function. Specify the pointer to the hook procedure in the lpfnPageSetupHook member and specify the PSD_ENABLEPAGESETUPHOOK flag in the Flags member.

The default dialog box procedure processes the WM_INITDIALOG message before passing it to the hook procedure. For all other messages, the hook procedure receives the message first. Then, the return value of the hook procedure determines whether the default dialog procedure processes the message or ignores it.

If the hook procedure processes the WM_CTLCOLORDLG message, it must return a valid brush handle for painting the background of the dialog box. In general, if the hook procedure processes any WM_CTLCOLOR* message, it must return a valid brush handle for painting the background of the specified control.

Do not call the EndDialog function from the hook procedure. Instead, the hook procedure can call the PostMessage function to post a WM_COMMAND message with the IDABORT value to the dialog box procedure. Posting IDABORT closes the dialog box and causes the dialog box function to return FALSE. If you need to know why the hook procedure closed the dialog box, you must provide your own communication mechanism between the hook procedure and your application.

You can subclass the standard controls of the common dialog box. However, the common dialog box procedure may also subclass the controls. Because of this, you should subclass controls when your hook procedure processes the WM_INITDIALOG message. This ensures that your subclass procedure receives the control-specific messages before the subclass procedure set by the dialog box procedure.

PageSetupHook is a placeholder for the application-defined or library-defined function name. The LPPAGESETUPHOOK type is a pointer to a PageSetupHook hook procedure.

See Also

EndDialog, PageSetupDlg, PAGESETUPDLG, PostMessage, WM_INITDIALOG, WM_CTLCOLORDLG


PaintDesktop [Now Supported on Windows NT]
PaintDesktop

[Now Supported on Windows NT]

The PaintDesktop function fills the clipping region in the specified device context with the desktop pattern or wallpaper. The function is provided primarily for shell desktops.

BOOL WINAPI PaintDesktop(

HDC hdc
);
Parameters

hdc

Identifies the device context.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.


PaintRgn

The PaintRgn function paints the specified region by using the brush currently selected into the device context.

BOOL PaintRgn(

HDC hdc,	// handle to device context
HRGN hrgn	// handle to region to be painted
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies the region to be filled. The region’s coordinates are presumed to be logical coordinates.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

FillRgn


PatBlt

The PatBlt function paints the given rectangle using the brush that is currently selected into the specified device context. The brush color and the surface color(s) are combined by using the given raster operation.

BOOL PatBlt(

HDC hdc,	// handle to device context
int nXLeft,	// x-coord. of upper-left corner of rect. to be filled
int nYLeft,	// y-coord. of upper-left corner of rect. to be filled
int nWidth,	// width of rectangle to be filled
int nHeight,	// height of rectangle to be filled
DWORD dwRop	// raster operation code
);
Parameters

hdc

Identifies the device context.

nXLeft

Specifies the x-coordinate, in logical units, of the upper-left corner of the rectangle to be filled.

nYLeft

Specifies the y-coordinate, in logical units, of the upper-left corner of the rectangle to be filled.

nWidth

Specifies the width, in logical units, of the rectangle.

nHeight

Specifies the height, in logical units, of the rectangle.

dwRop

Specifies the raster operation code. This code may be one of the following values:

Value	Meaning
PATCOPY	Copies the specified pattern into the destination bitmap.
PATINVERT	Combines the colors of the specified pattern with the colors of the destination rectangle by using the Boolean OR operator.
DSTINVERT	Inverts the destination rectangle.
BLACKNESS	Fills the destination rectangle using the color associated with index 0 in the physical palette. (This color is black for the default physical palette.)
WHITENESS	Fills the destination rectangle using the color associated with index 1 in the physical palette. (This color is white for the default physical palette.)
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.

Remarks

The values of the dwRop parameter for this function are a limited subset of the full 256 ternary raster-operation codes; in particular, an operation code that refers to a source rectangle cannot be used.

Not all devices support the PatBlt function. For more information, see the description of the RC_BITBLT capability in the GetDeviceCaps function.

See Also

GetDeviceCaps


PathToRegion

The PathToRegion function creates a region from the path that is selected into the specified device context.

HRGN PathToRegion(

HDC hdc	// handle to device context
);
Parameters

hdc

Identifies a device context that contains a closed path.

Return Values

If the function succeeds, the return value identifies a valid region.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY

Remarks

The device context identified by the hdc parameter must contain a closed path.

After PathToRegion converts a path into a region, Windows discards the closed path from the specified device context.

See Also

BeginPath, EndPath, SetPolyFillMode


PeekConsoleInput

The PeekConsoleInput function reads data from the specified console input buffer without removing it from the buffer.

BOOL PeekConsoleInput(

HANDLE hConsoleInput,	// handle to a console input buffer
PINPUT_RECORD lpBuffer,	// pointer to the buffer for peek data
DWORD nLength,	// number of records to read
LPDWORD lpNumberOfEventsRead	// pointer to number of records read
);
Parameters

hConsoleInput

Identifies the input buffer. The handle must have GENERIC_READ access.

lpBuffer

Points to an INPUT_RECORD buffer that receives the input buffer data.

nLength

Specifies the size, in records, of the buffer pointed to by the lpBuffer parameter.

lpNumberOfEventsRead

Points to a 32-bit variable that receives the number of input records read.

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.

Remarks

If the number of records requested exceeds the number of records available in the buffer, the number available is read. If no data is available, the function returns immediately.

Windows NT: This function uses either Unicode characters or 8-bit characters from the console's current codepage. The console's codepage defaults initially to the system's OEM codepage. To change the console's codepage, use the SetConsoleCP or SetConsoleOutputCP functions, or use the chcp or mode con cp select= commands.

See Also

INPUT_RECORD, ReadConsoleInput, SetConsoleCP, SetConsoleOutputCP, WriteConsoleInput


PeekMessage

The PeekMessage function checks a thread message queue for a message and places the message (if any) in the specified structure.

BOOL PeekMessage(

LPMSG lpMsg,	// pointer to structure for message
HWND hWnd,	// handle to window
UINT wMsgFilterMin,	// first message
UINT wMsgFilterMax,	// last message
UINT wRemoveMsg	// removal flags
);
Parameters

lpMsg

Points to an MSG structure that contains message information from the Windows-based application queue.

hWnd

Identifies the window whose messages are to be examined.

wMsgFilterMin

Specifies the value of the first message in the range of messages to be examined.

wMsgFilterMax

Specifies the value of the last message in the range of messages to be examined.

wRemoveMsg

Specifies how messages are handled. This parameter can be one of the following values:

Value	Meaning
PM_NOREMOVE	Messages are not removed from the queue after processing by PeekMessage.
PM_REMOVE	Messages are removed from the queue after processing by PeekMessage.
You can optionally combine the value PM_NOYIELD with either PM_NOREMOVE or PM_REMOVE. However, PM_NOYIELD has no effect on 32-bit Windows applications. It is defined in Win32 solely to provide compatibility with applications written for previous versions of Windows, where it was used to prevent the current task from halting and yielding system resources to another task. 32-bit Windows applications always run simultaneously.

Return Values

If a message is available, the return value is nonzero.

If no messages are available, the return value is zero.

Remarks

Unlike the GetMessage function, the PeekMessage function does not wait for a message to be placed in the queue before returning.

PeekMessage retrieves only messages associated with the window identified by the hWnd parameter or any of its children as specified by the IsChild function, and within the range of message values given by the wMsgFilterMin and wMsgFilterMax parameters. If hWnd is NULL, PeekMessage retrieves messages for any window that belongs to the current thread making the call. (PeekMessage does not retrieve messages for windows that belong to other threads.) If hWnd is −1, PeekMessage only returns messages with a hWnd value of NULL, as posted by the PostAppMessage function. If wMsgFilterMin and wMsgFilterMax are both zero, PeekMessage returns all available messages (that is, no range filtering is performed).

The WM_KEYFIRST and WM_KEYLAST constants can be used as filter values to retrieve all keyboard messages; the WM_MOUSEFIRST and WM_MOUSELAST constants can be used to retrieve all mouse messages.

The PeekMessage function normally does not remove WM_PAINT messages from the queue. WM_PAINT messages remain in the queue until they are processed. However, if a WM_PAINT message has a null update region, PeekMessage does remove it from the queue.

See Also

GetMessage, IsChild, MSG, PostAppMessage, WaitMessage


PeekNamedPipe

The PeekNamedPipe function copies data from a named or anonymous pipe into a buffer without removing it from the pipe. It also returns information about data in the pipe.

BOOL PeekNamedPipe(

HANDLE hNamedPipe,	// handle to pipe to copy from
LPVOID lpBuffer,	// pointer to data buffer
DWORD nBufferSize,	// size, in bytes, of data buffer
LPDWORD lpBytesRead,	// pointer to number of bytes read
LPDWORD lpTotalBytesAvail,	// pointer to total number of bytes available
LPDWORD lpBytesLeftThisMessage	// pointer to unread bytes in this message
);
Parameters

hNamedPipe

Identifies the pipe. This parameter can be a handle to a named pipe instance, as returned by the CreateNamedPipe or CreateFile function, or it can be a handle to the read end of an anonymous pipe, as returned by the CreatePipe function. The handle must have GENERIC_READ access to the pipe.

lpBuffer

Points to a buffer that receives data read from the pipe. This parameter can be NULL if no data is to be read.

nBufferSize

Specifies the size, in bytes, of the buffer specified by the lpBuffer parameter. This parameter is ignored if lpBuffer is NULL.

lpBytesRead

Points to a 32-bit variable that receives the number of bytes read from the pipe. This parameter can be NULL if no data is to be read.

lpTotalBytesAvail

Points to a 32-bit variable that receives the total number of bytes available to be read from the pipe. This parameter can be NULL if no data is to be read.

lpBytesLeftThisMessage

Points to a 32-bit variable that receives the number of bytes remaining in this message. This parameter will be zero for byte-type named pipes or for anonymous pipes. This parameter can be NULL if no data is to be read.

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.

Remarks

PeekNamedPipe is similar to the ReadFile function with the following exceptions:

•	The data read from the pipe is not removed from the pipe’s buffer.

•	The function always returns immediately, even if there is no data in the pipe. The wait mode of a named pipe handle (blocking or nonblocking) has no effect on the function.

•	The function can return additional information about the contents of the pipe.

If the specified handle is a named pipe handle in byte-read mode, the function reads all available bytes up to the size specified in nBufferSize. For a named pipe handle in message-read mode, the function reads the next message in the pipe. If the message is larger than nBufferSize, the function returns TRUE after reading the specified number of bytes. In this situation, lpBytesLeftThisMessage will receive the number of bytes remaining in the message.

See Also

CreateFile, CreateNamedPipe, CreatePipe, ReadFile, WriteFile


Pie

The Pie function draws a pie-shaped wedge bounded by the intersection of an ellipse and two radials. The pie is outlined by using the current pen and filled by using the current brush.

BOOL Pie(

HDC hdc,	// handle to device context
int nLeftRect,	// x-coord. of bounding rectangle’s upper-left corner
int nTopRect,	// y-coord. of bounding rectangle’s upper-left corner
int nRightRect,	// x-coord. of bounding rectangle’s lower-right corner
int nBottomRect,	// y-coord. of bounding rectangle’s lower-right corner
int nXRadial1,	// x-coord. of first radial’s endpoint
int nYRadial1,	// y-coord. of first radial’s endpoint
int nXRadial2,	// x-coord. of second radial’s endpoint
int nYRadial2	// y-coord. of second radial’s endpoint
);
Parameters

hdc

Identifies the device context.

nLeftRect

Specifies the x-coordinate of the upper-left corner of the bounding rectangle.

nTopRect

Specifies the y-coordinate of the upper-left corner of the bounding rectangle.

nRightRect

Specifies the x-coordinate of the lower-right corner of the bounding rectangle.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the bounding rectangle.

nXRadial1

Specifies the x-coordinate of the endpoint of the first radial.

nYRadial1

Specifies the y-coordinate of the endpoint of the first radial.

nXRadial2

Specifies the x-coordinate of the endpoint of the second radial.

nYRadial2

Specifies the y-coordinate of the endpoint of the second radial.

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.

Remarks

The curve of the pie is defined by an ellipse that fits the specified bounding rectangle. The curve begins at the point where the ellipse intersects the first radial and extends counterclockwise to the point where the ellipse intersects the second radial. (A radial is a line drawn from the center of the ellipse to the specified endpoint on the ellipse.)

The current position is neither used nor updated by the Pie function.

Windows 95: The sum of the coordinates of the bounding rectangle cannot exceed 32,767. The sum of nLeftRect and nRightRect or nTopRect and nBottomRect parameters cannot exceed 32,767.

See Also

AngleArc, Arc, ArcTo, Chord


PlayEnhMetaFile

The PlayEnhMetaFile function displays the picture stored in the specified enhanced-format metafile.

BOOL PlayEnhMetaFile(

HDC hdc,	// handle to a device context
HENHMETAFILE hemf,	// handle to an enhanced metafile
CONST RECT *lpRect	// pointer to bounding rectangle
);
Parameters

hdc

Identifies the device context for the output device on which the picture will appear.

hemf

Identifies the enhanced metafile.

lpRect

Points to a RECT structure that contains the coordinates of the bounding rectangle used to display the picture. The coordinates are specified in logical units.

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.

Remarks

When an application calls the PlayEnhMetaFile function, Windows uses the picture frame in the enhanced-metafile header to map the picture onto the rectangle pointed to by the lpRect parameter. (This picture may be sheared or rotated by setting the world transform in the output device before calling PlayEnhMetaFile.) Points along the edges of the rectangle are included in the picture.

An enhanced-metafile picture can be clipped by defining the clipping region in the output device before playing the enhanced metafile.

If an enhanced metafile contains an optional palette, an application can achieve consistent colors by setting up a color palette on the output device before calling PlayEnhMetaFile. To retrieve the optional palette, use the GetEnhMetaFilePaletteEntries function.

An enhanced metafile can be embedded in a newly created enhanced metafile by calling PlayEnhMetaFile and playing the source enhanced metafile into the device context for the new enhanced metafile.

The states of the output device context are preserved by this function. Any object created but not deleted in the enhanced metafile is deleted by this function.

To stop this function, an application can call the CancelDC function from another thread to terminate the operation. In this case, the function returns FALSE.

Windows 95: PlayEnhMetaFile is subject to the limitations of the Windows 95 GDI. For example, Windows 95 supports only 16-bit signed coordinates. For records that contain 32-bit values, Windows 95 fails to play the record if the values are not in the range -32,768 to 32,767.

See Also

CancelDC, GetEnhMetaFileHeader, GetEnhMetaFilePaletteEntries, RECT, SetWorldTransform


PlayEnhMetaFileRecord

The PlayEnhMetaFileRecord function plays an enhanced-metafile record by executing the graphics device interface (GDI) functions identified by the record.

BOOL PlayEnhMetaFileRecord(

HDC hdc,	// handle to device context
LPHANDLETABLE lpHandletable,	// pointer to metafile handle table
CONST ENHMETARECORD *lpEnhMetaRecord,	// pointer to metafile record
UINT nHandles	// count of handles
);
Parameters

hdc

Identifies the device context passed to the EnumEnhMetaFile function.

lpHandletable

Points to a table of handles identifying GDI objects used when playing the metafile. The first entry in this table contains the enhanced-metafile handle.

lpEnhMetaRecord

Points to the enhanced-metafile record to be played.

nHandles

Specifies the number of handles in the handle table.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

This is an enhanced-metafile function.

An application typically uses PlayEnhMetaFileRecord in conjunction with the EnumEnhMetaFile function to process and play an enhanced-format metafile one record at a time.

The hdc, lpHandletable, and nHandles parameters must be exactly those passed to the EnhMetaFileProc callback procedure by the EnumEnhMetaFile function.

If PlayEnhMetaFileRecord does not recognize a record, it ignores the record and returns TRUE.

Windows 95: PlayEnhMetaFileRecord is subject to the limitations of the Windows 95 GDI. For example, Windows 95 supports only 16-bit signed coordinates. For records that contain 32-bit values, Windows 95 fails to play the record if the values are not in the range -32,768 to 32,767.

See Also

EnumEnhMetaFile, PlayEnhMetaFile


PlayMetaFile

The PlayMetaFile function displays the picture stored in the given Windows-format metafile on the specified device.

This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the PlayEnhMetaFile function.

BOOL PlayMetaFile(

HDC hdc,	// handle to the device context
HMETAFILE hmf	// handle to the metafile
);
Parameters

hdc

Identifies a device context.

hmf

Identifies a Windows-format metafile.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

A Windows-format metafile does not support the new curve, path, and transformation functions such as PolyBezier, BeginPath, and SetWorldTransform. Applications that use these new functions and use metafiles to store pictures created by these functions should use the enhanced-format metafile functions.

To convert a Windows-format metafile into an enhanced format metafile, use the SetWinMetaFileBits function.

A Windows-format metafile can be played multiple times.

A Windows-format metafile can be embedded in a second Windows-format metafile by calling the PlayMetaFile function and playing the source metafile into the device context for the target metafile.

Any object created but not deleted in the Windows-format metafile is deleted by this function.

To stop this function, an application can call the CancelDC function from another thread to terminate the operation. In this case, the function returns FALSE.

See Also

BeginPath, CancelDC, PolyBezier, SetWinMetaFileBits, SetWorldTransform


PlayMetaFileRecord

The PlayMetaFileRecord function plays a Windows-format metafile record by executing the graphics device interface (GDI) function contained within that record.

This function is provided for compatibility with 16-bit versions of Microsoft Windows. Win32-based applications should use the PlayEnhMetaFileRecord function.

BOOL PlayMetaFileRecord(

HDC hdc,	// handle to device context
LPHANDLETABLE lpHandletable,	// pointer to metafile handle table
LPMETARECORD lpMetaRecord,	// pointer to metafile record
UINT nHandles	// count of handles
);
Parameters

hdc

Identifies a device context.

lpHandletable

Points to a table of handles identifying GDI objects used when playing the metafile.

lpMetaRecord

Points to the Windows-format metafile record.

nHandles

Specifies the number of handles in the handle table.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

A Windows-format metafile does not support the new curve, path, and transformation functions, such as PolyBezier, BeginPath, and SetWorldTransform. Applications that use these new functions and use metafiles to store pictures created by these functions, should use the enhanced format metafile functions.

To convert a Windows-format metafile into an enhanced-format metafile, use the SetWinMetaFileBits function.

An application typically uses PlayMetaFileRecord in conjunction with the EnumMetaFile function to process and play a Windows-format metafile one record at a time.

The lpHandletable and nHandles parameters must be identical to those passed to the EnumMetaFileProc callback procedure by EnumMetaFile.

If the PlayMetaFileRecord function does not recognize a record, it ignores the record and returns TRUE.

See Also

BeginPath, EnumMetaFile, PlayMetaFile, PolyBezier, SetWinMetaFileBits, SetWorldTransform


PlgBlt

The PlgBlt function performs a bit-block transfer of the bits of color data from the specified rectangle in the source device context to the specified parallelogram in the destination device context. If the given bitmask handle identifies a valid monochrome bitmap, the function uses this bitmap to mask the bits of color data from the source rectangle.

BOOL PlgBlt(

HDC hdcDest,	// handle to destination device context
CONST POINT *lpPoint,	// vertices of destination parallelogram
HDC hdcSrc,	// handle to source device context
int nXSrc,	// x-coord. of upper-left corner of source rect.
int nYSrc,	// y-coord. of upper-left corner of source rect.
int nWidth,	// width of source rectangle
int nHeight,	// height of source rectangle
HBITMAP hbmMask,	// handle to bitmask
int xMask,	// x-coord. of upper-left corner of bitmask rect.
int yMask	// y-coord. of upper-left corner of bitmask rect.
);
Parameters

hdcDest

Identifies the destination device context.

lpPoint

Points to an array of three points in logical space that identify three corners of the destination parallelogram. The upper-left corner of the source rectangle is mapped to the first point in this array, the upper-right corner to the second point in this array, and the lower-left corner to the third point. The lower-right corner of the source rectangle is mapped to the implicit fourth point in the parallelogram.

hdcSrc

Identifies the source device context.

nXSrc

Specifies the x-coordinate, in logical units, of the upper-left corner of the source rectangle.

nYSrc

Specifies the y-coordinate, in logical units, of the upper-left corner of the source rectangle.

nWidth

Specifies the width, in logical units, of the source rectangle.

nHeight

Specifies the height, in logical units, of the source rectangle.

hbmMask

Identifies an optional monochrome bitmap that is used to mask the colors of the source rectangle.

xMask

Specifies the x-coordinate of the upper-left corner of the the monochrome bitmap.

yMask

Specifies the y-coordinate of the upper-left corner of the the monochrome bitmap.

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.

Remarks

The fourth vertex of the parallelogram (D) is defined by treating the first three points (A, B, and C) as vectors and computing D = B + C − A.

If the bitmask exists, a value of 1 in the mask indicates that the source pixel color should be copied to the destination. A value of 0 in the mask indicates that the destination pixel color is not to be changed.

If the mask rectangle is smaller than the source and destination rectangles, the function replicates the mask pattern.

Scaling, translation, and reflection transformations are allowed in the source device context; however, rotation and shear transformations are not.

If the mask bitmap is not a monochrome bitmap, an error occurs.

The stretching mode for the destination device context is used to determine how to stretch or compress the pixels, if that is necessary.

When an enhanced metafile is being recorded, an error occurs if the source device context identifies an enhanced-metafile device context.

The destination coordinates are transformed according to the destination device context; the source coordinates are transformed according to the source device context. If the source transformation has a rotation or shear, an error is returned.

If the destination and source rectangles do not have the same color format, PlgBlt converts the source rectangle to match the destination rectangle.

Not all devices support the PlgBlt function. For more information, see the description of the RC_BITBLT raster capability in the GetDeviceCaps function.

If the source and destination device contexts represent incompatible devices, PlgBlt returns an error.

See Also

BitBlt, GetDeviceCaps, MaskBlt, SetStretchBltMode, StretchBlt


PolyBezier

The PolyBezier function draws one or more Bézier curves.

BOOL PolyBezier(

HDC hdc,	// handle to device context
CONST POINT *lppt,	// pointer to endpoints and control points
DWORD cPoints	// count of endpoints and control points
);
Parameters

hdc

Identifies a device context.

lppt

Points to an array of POINT structures that contain the endpoints and control points of the curve(s).

cPoints

Specifies the number of points in the lppt array. This value must be one more than three times the number of curves to be drawn, because each Bézier curve requires two control points and an endpoint, and the initial curve requires an additional starting point.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Th Polybezier function draws cubic Bézier curves by using the endpoints and control points specified by the lppt parameter. The first curve is drawn from the first point to the fourth point by using the second and third points as control points. Each subsequent curve in the sequence needs exactly three more points: the ending point of the previous curve is used as the starting point, the next two points in the sequence are control points, and the third is the ending point.

The current position is neither used nor updated by the PolyBezier function. The figure is not filled.

This function draws lines by using the current pen.

See Also

MoveToEx, POINT, PolyBezierTo


PolyBezierTo

The PolyBezierTo function draws one or more Bézier curves.

BOOL PolyBezierTo(

HDC hdc,	// handle to device context
CONST POINT *lppt,	// pointer to endpoints and control points
DWORD cCount	// count of endpoints and control points
);
Parameters

hdc

Identifies a device context.

lppt

Points to an array of POINT structures that contains the endpoints and control points.

cCount

Specifies the number of points in the lppt array. This value must be three times the number of curves to be drawn, because each Bézier curve requires two control points and an ending point.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

This function draws cubic Bézier curves by using the control points specified by the lppt parameter. The first curve is drawn from the current position to the third point by using the first two points as control points. For each subsequent curve, the function needs exactly three more points, and uses the ending point of the previous curve as the starting point for the next.

PolyBezierTo moves the current position to the ending point of the last Bézier curve. The figure is not filled.

This function draws lines by using the current pen.

See Also

MoveToEx, POINT, PolyBezier


PolyDraw

The PolyDraw function draws a set of line segments and Bézier curves.

BOOL PolyDraw(

HDC hdc,	// handle to a device context
CONST POINT *lppt,	// pointer to array of points
CONST BYTE *lpbTypes,	// pointer to line and curve identifiers
int cCount	// count of points
);
Parameters

hdc

Identifies a device context.

lppt

Points to an array of POINT structures that contains the endpoints for each line segment and the endpoints and control points for each Bézier curve.

lpbTypes

Points to an array that specifies how each point in the lppt array is used. Types can be one of the following:

Type	Meaning
PT_MOVETO	Specifies that this point starts a disjoint figure. This point becomes the new current position.
PT_LINETO	Specifies that a line is to be drawn from the current position to this point, which then becomes the new current position.
PT_BEZIERTO	Specifies that this point is a control point or ending point for a Bézier curve.
	PT_BEZIERTO types always occur in sets of three. The current position defines the starting point for the Bézier curve. The first two PT_BEZIERTO points are the control points, and the third PT_BEZIERTO point is the ending point. The ending point becomes the new current position. If there are not three consecutive PT_BEZIERTO points, an error results.
A PT_LINETO or PT_BEZIERTO type can be combined with the following value by using the bitwise operator OR to indicate that the corresponding point is the last point in a figure and the figure is closed:

Value	Meaning
PT_CLOSEFIGURE	Specifies that the figure is automatically closed after the PT_LINETO or PT_BEZIERTO type for this point is done. A line is drawn from this point to the most recent PT_MOVETO or MoveToEx point.
	This value is combined with the PT_LINETO type for a line, or with the PT_BEZIERTO type of the ending point for a Bézier curve, by using the bitwise operator OR.
	The current position is set to the ending point of the closing line.
cCount

Specifies the total number of points in the lppt array, the same as the number of bytes in the lpbTypes array.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The PolyDraw function can be used in place of consecutive calls to MoveToEx, LineTo, and PolyBezierTo functions to draw disjoint figures. The lines and curves are drawn using the current pen and figures are not filled. If there is an active path started by calling BeginPath, PolyDraw adds to the path.

The points contained in the lppt array and in the lpbTypes array indicate whether each point is part of a MoveTo, LineTo, or PolyBezierTo operation. It is also possible to close figures.

This function updates the current position.

See Also

BeginPath, EndPath, LineTo, MoveToEx, POINT, PolyBezierTo, PolyLine


Polygon

The Polygon function draws a polygon consisting of two or more vertices connected by straight lines. The polygon is outlined by using the current pen and filled by using the current brush and polygon fill mode.

BOOL Polygon(

HDC hdc,	// handle to device context
CONST POINT *lpPoints,	// pointer to polygon’s vertices
int nCount	// count of polygon’s vertices
);
Parameters

hdc

Identifies the device context.

lpPoints

Points to an array of POINT structures that specify the vertices of the polygon.

nCount

Specifies the number of vertices in the array. This value must be greater than or equal to 2.

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.

Remarks

The polygon is closed automatically by drawing a line from the last vertex to the first.

The current position is neither used nor updated by the Polygon function.

See Also

GetPolyFillMode, POINT, Polyline, PolylineTo, PolyPolygon, SetPolyFillMode


Polyline

The Polyline function draws a series of line segments by connecting the points in the specified array.

BOOL Polyline(

HDC hdc,	// handle of device context
CONST POINT *lppt,	// address of array containing endpoints
int cPoints	// number of points in the array
);
Parameters

hdc

Identifies a device context.

lppt

Points to an array of POINT structures. Each structure in the array identifies a point in logical space.

cPoints

Specifies the number of points in the array. This number must be greater than or equal to two.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The lines are drawn from the first point through subsequent points by using the current pen. Unlike the LineTo function, the Polyline function neither uses nor updates the current position.

See Also

LineTo, MoveToEx, POINT, PolylineTo, PolyPolyline


PolylineTo

The PolylineTo function draws one or more straight lines.

BOOL PolylineTo(

HDC hdc,	// handle of device context
CONST POINT *lppt,	// address of array of points
DWORD cCount	// number of points in array
);
Parameters

hdc

Identifies the device context.

lppt

Points to an array of POINT structures that contains the vertices of the line.

cCount

Specifies the number of points in the array.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

A line is drawn from the current position to the first point specified by the lppt parameter by using the current pen. For each additional line, the function draws from the ending point of the previous line to the next point specified by lppt.

PolylineTo moves the current position to the ending point of the last line.

If the line segments drawn by this function form a closed figure, the figure is not filled.

See Also

LineTo, MoveToEx, POINT, Polyline


PolyPolygon

The PolyPolygon function draws a series of closed polygons. Each polygon is outlined by using the current pen and filled by using the current brush and polygon fill mode. The polygons drawn by this function can overlap.

BOOL PolyPolygon(

HDC hdc,	// handle of device context
CONST POINT *lpPoints,	// points to array of vertices for all polygons
CONST INT *lpPolyCounts,	// points to array with count of vertices for each polygon
int nCount	// count of polygons
);
Parameters

hdc

Identifies the device context.

lpPoints

Points to an array of POINT structures that define the vertices of the polygons. The polygons are specified consecutively. Each polygon is closed automatically by drawing a line from the last vertex to the first. Each vertex should be specified once.

lpPolyCounts

Points to an array of integers, each of which specifies the number of points in the corresponding polygon. Each integer must be greater than or equal to 2.

nCount

Specifies the total number of polygons.

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.

Remarks

The current position is neither used nor updated by this function.

See Also

GetPolyFillMode, POINT, Polygon, Polyline, PolylineTo, SetPolyFillMode


PolyPolyline

The PolyPolyline function draws multiple series of connected line segments.

BOOL PolyPolyline(

HDC hdc,	// handle of a device context
CONST POINT *lppt,	// address of an array of points
CONST DWORD *lpdwPolyPoints,	// address of an array of values
DWORD cCount	// number of counts in the second array
);
Parameters

hdc

Identifies the device context.

lppt

Points to an array of POINT structures that contains the vertices of the polylines. The polylines are specified consecutively.

lpdwPolyPoints

Points to an array of variables specifying the number of points in the lppt array for the corresponding polyline. Each entry must be greater than or equal to two.

cCount

Specifies the total number of counts in the lpdwPolyPoints array.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The line segments are drawn by using the current pen. The figures formed by the segments are not filled.

The current position is neither used nor updated by this function.

See Also

POINT, Polyline, PolylineTo


PolyTextOut

The PolyTextOut function draws several strings using the font and text colors currently selected in the specified device context.

BOOL PolyTextOut(

HDC hdc,	// handle of device context
CONST POLYTEXT *pptxt,	// address of array of structures that identify strings
int cStrings	// number of structures in array
);
Parameters

hdc

Identifies the device context.

pptxt

Points to an array of POLYTEXT structures describing the strings to be drawn. The array contains one structure for each string to be drawn.

cStrings

Specifies the number of POLYTEXT structures in the pptxt array.

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.

Remarks

Each POLYTEXT structure contains the coordinates of a reference point that Windows uses to align the corresponding string of text. An application can specify how the reference point is used by calling the SetTextAlign function. An application can determine the current text-alignment setting for the specified device context by calling the GetTextAlign function.

To draw a single string of text, the application should call the ExtTextOut function.

See Also

ExtTextOut, GetTextAlign, POLYTEXT, SetTextAlign


PostAppMessage

The PostAppMessage function is obsolete. The function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the PostThreadMessage function.


PostMessage

The PostMessage function places (posts) a message in the message queue associated with the thread that created the specified window and then returns without waiting for the thread to process the message. Messages in a message queue are retrieved by calls to the GetMessage or PeekMessage function.

BOOL PostMessage(

HWND hWnd,	// handle of destination window
UINT Msg,	// message to post
WPARAM wParam,	// first message parameter
LPARAM lParam	// second message parameter
);
Parameters

hWnd

Identifies the window whose window procedure is to receive the message. Two values have special meanings:

Value	Meaning
HWND_BROADCAST	The message is posted to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows. The message is not posted to child windows.
NULL	The function behaves like a call to PostThreadMessage with the dwThreadId parameter set to the identifier of the current thread.
Msg

Specifies the message to be posted.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

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.

Remarks

Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function to obtain a unique message for inter-application communication.

If you send a message in the range below WM_USER to the asynchronous message functions (PostMessage, SendNotifyMessage, and SendMessageCallback), make sure that the message parameters do not include pointers. Otherwise, the functions will return before the receiving thread has had a chance to process the message and the sender will free the memory before it is used.

See Also

GetMessage, PeekMessage, SendMessageCallback, SendNotifyMessage


PostQueuedCompletionStatus

The PostQueuedCompletionStatus function lets you post an I/O completion packet to an I/O completion port. The I/O completion packet will satisfy an outstanding call to the GetQueuedCompletionStatus function. The GetQueuedCompletionStatus function returns with the three values passed as the second, third, and fourth parameters of the call to PostQueuedCompletionStatus.

BOOL PostQueuedCompletionStatus(

HANDLE CompletionPort,	// handle to an I/O completion port
DWORD dwNumberOfBytesTransferred,	// value to return via  //     GetQueuedCompletionStatus’  //     lpNumberOfBytesTranferred
DWORD dwCompletionKey,	// value to return via  //     GetQueuedCompletionStatus’  //     lpCompletionKey
LPOVERLAPPED lpOverlapped	// value to return via  //     GetQueuedCompletionStatus’ lpOverlapped
);
Parameters

CompletionPort

Handle to an I/O completion port that you want to post an I/O completion packet to.

dwNumberOfBytesTransferred

Specifies a value to be returned through the lpNumberOfBytesTransferred parameter of the GetQueuedCompletionStatus function.

dwCompletionKey

Specifies a value to be returned through the lpCompletionKey parameter of the GetQueuedCompletionStatus function.

lpOverlapped

Specifies a value to be returned through the lpOverlapped parameter of the GetQueuedCompletionStatus 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 .

Remarks

For more information concerning dwNumberOfBytesTransferred, dwCompletionKey, and lpOverlapped, see GetQueuedCompletionStatus and the descriptions of the parameters those values are returned through.

See Also

CreateIoCompletionPort, GetQueuedCompletionStatus, OVERLAPPED


PostQuitMessage

The PostQuitMessage function indicates to Windows that a thread has made a request to terminate (quit). It is typically used in response to a WM_DESTROY message.

VOID PostQuitMessage(

int nExitCode	// exit code
);
Parameters

nExitCode

Specifies an application exit code. This value is used as the wParam parameter of the WM_QUIT message.

Return Values

This function does not return a value.

Remarks

The PostQuitMessage function posts a WM_QUIT message to the thread’s message queue and returns immediately; the function simply indicates to the system that the thread is requesting to quit at some time in the future.

When the thread retrieves the WM_QUIT message from its message queue, it should exit its message loop and return control to Windows. The exit value returned to Windows must be the wParam parameter of the WM_QUIT message.

See Also

GetMessage, PeekMessage, PostMessage, WM_DESTROY, WM_QUIT


PostThreadMessage

The PostThreadMessage function places (posts) a message in the message queue of the specified thread and then returns without waiting for the thread to process the message.

BOOL PostThreadMessage(

DWORD idThread,	// thread identifier
UINT Msg,	// message to post
WPARAM wParam,	// first message parameter
LPARAM lParam	// second message parameter
);
Parameters

idThread

Identifies the thread to which the message will be posted.

The function fails if the specified thread does not have a message queue. The system creates a thread's message queue when the thread makes its first call to one of the Win32 USER or GDI functions. For more information, see the Remarks section.

Msg

Specifies the type of message to be posted.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

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 returns ERROR_INVALID_THREAD_ID if idThread is not a valid thread identifier, or if the thread specified by idThread does not have a message queue.

Remarks

The thread to which the message is posted must have created a message queue, or else the call to PostThreadMessage fails. Use one of the following methods to handle this situation:

•	Call PostThreadMessage. If it fails, call the Sleep function and call PostThreadMessage again. Repeat until PostThreadMessage succeeds.

•	Create an event object, then create the thread. Use the WaitForSingleObject function to wait for the event to be set to the signaled state before calling PostThreadMessage. In the thread to which the message will be posted, call PeekMessage(&msg, NULL, WM_USER, WM_USER, PM_NOREMOVE) to force the system to create the message queue. Set the event, to indicate that the thread is ready to receive posted messages.

The thread to which the message is posted retrieves the message by calling the GetMessage or PeekMessage function. The hwnd member of the returned MSG structure is NULL.

See Also

GetCurrentThreadId, GetMessage, GetWindowThreadProcessId, MSG, PeekMessage, PostMessage, Sleep, WaitForSingleObject


PrepareTape

The PrepareTape function prepares the tape to be accessed or removed.

DWORD PrepareTape(

HANDLE hDevice,	// handle of open device
DWORD dwOperation,	// preparation method
BOOL bImmediate	// return after operation begins
);
Parameters

hDevice

Identifies the device preparing the tape. This handle is created by using the CreateFile function.

dwOperation

Specifies how the tape device is to be prepared. This parameter can be one of the following values:

Value	Meaning
TAPE_FORMAT	Performs a low-level format of the tape. Currently, only the QIC117 device supports this feature.
TAPE_LOAD	Loads the tape and moves the tape to the beginning.
TAPE_LOCK	Locks the tape ejection mechanism so that the tape is not ejected accidentally.
TAPE_TENSION	Adjusts the tension by moving the tape to the end of the tape and back to the beginning. This option is not supported by all devices. This value is ignored if it is not supported.
TAPE_UNLOAD	Moves the tape to the beginning for removal from the device. After a successful unload operation, the device returns errors to applications that attempt to access the tape, until the tape is loaded again.
TAPE_UNLOCK	Unlocks the tape ejection mechanism.
bImmediate

Specifies whether to return as soon as the preparation begins. If this parameter is TRUE, the function returns immediately. If it is FALSE, the function does not return until the operation has been completed.

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:

Error	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
Remarks

Some tape devices do not support certain tape operations. See your tape device documentation and use the GetTapeParameters function to determine your tape device’s capabilities.

See Also

CreateFile, GetTapeParameters


PrintDlg

The PrintDlg function displays a Print dialog box or a Print Setup dialog box. The Print dialog box enables the user to specify the properties of a particular print job.

The Print Setup dialog box should not be used in new applications. It has been superseded by the Page Setup common dialog box created by the PageSetupDlg function.

BOOL PrintDlg(

LPPRINTDLG lppd	// address of structure with initialization data
);
Parameters

lppd

Pointer to a PRINTDLG structure that contains information used to initialize the dialog box. When PrintDlg returns, this structure contains information about the user’s selections.

Return Values

If the user clicks the OK button, the return value is nonzero. The members of the PRINTDLGstructure pointed to by the lppd parameter indicate the user’s selections.

If the user cancels or closes the Print or Printer Setup dialog box or an error occurs, the return value is zero. To get extended error information, use the CommDlgExtendedError function, which can return one of the following values:

CDERR_FINDRESFAILURE	PDERR_CREATEICFAILURE
CDERR_INITIALIZATION	PDERR_DEFAULTDIFFERENT
CDERR_LOADRESFAILURE	PDERR_DNDMMISMATCH
CDERR_LOADSTRFAILURE	PDERR_GETDEVMODEFAIL
CDERR_LOCKRESFAILURE	PDERR_INITFAILURE
CDERR_MEMALLOCFAILURE	PDERR_LOADDRVFAILURE
CDERR_MEMLOCKFAILURE	PDERR_NODEFAULTPRN
CDERR_NOHINSTANCE	PDERR_NODEVICES
CDERR_NOHOOK	PDERR_PARSEFAILURE
CDERR_NOTEMPLATE	PDERR_PRINTERNOTFOUND
CDERR_STRUCTSIZE	PDERR_RETDEFFAILURE
Remarks

If the hook procedure (pointed to by the lpfnPrintHook or lpfnSetupHook member of the PRINTDLG structure) processes the WM_CTLCOLORDLG message, the hook procedure must return a handle for the brush that should be used to paint the control background.

See Also

CommDlgExtendedError, CreateDC, DOCINFO, PRINTDLG, PrintHookProc, SetupHookProc, StartDoc, WM_CTLCOLORDLG


PrinterMessageBox

The PrinterMessageBox function displays a message box that lets an application that is printing notify the user of a printing job error. If the owner of the job is logged on remotely, the function sends a net popup to the owner. If the user selects Cancel in the message box, the function cancels the print job; otherwise, the function clears the job error status, and the system tries to print the job again.

HPRINTER PrinterMessageBox (

HANDLE hPrinter,	// handle of printer
DWORD Error,	// error identifier
HWND hWnd,	// handle of owner window
LPTSTR pText,	// pointer to message box text
LPTSTR pCaption,	// pointer to message box title
DWORD dwType	// style of message box
);
Parameters

hPrinter

Identifies the printer to which the job was sent.

Error

Specifies the error that occurred. This parameter can be one of the following values:

Value	Meaning
ERROR_OUT_OF_PAPER	The printer is out of paper.
ERROR_NOT_READY	The printer is not ready.
hWnd

Identifies an owner window for the message box the function creates. If this parameter is NULL, the message box has no owner window.

pText

Points to a null-terminated string that specifies the message to be displayed.

pCaption

Points to a null-terminated string that specifies the dialog box title. If this parameter is NULL, the function uses the default title “Error”.

dwType

Specifies the contents and behavior of the dialog box. This parameter can be a combination of any of the values accepted by the MessageBox function’s fourth parameter; however, it is recommended that an application use the following combination:

   MB_ICONSTOP | MB_RETRYCANCEL | MB_SETFOREGROUND

Return Values

If PrinterMessageBox sends a net popup, the return value is IDOK. Otherwise, the function returns the value returned by the message box the function displays. Two typical return values are the following:

Value	Meaning
IDCANCEL	Cancel button was selected.
IDRETRY	Retry button was selected.
For a more complete list of message box return values, see MessageBox.

See Also

MessageBox


PrinterProperties

The PrinterProperties function displays a printer-properties dialog box for the specified printer.

BOOL PrinterProperties(

HWND hWnd,	// handle of parent window
HANDLE hPrinter	// handle of printer object
);
Parameters

hWnd

Identifies the parent window of the dialog box.

hPrinter

Identifies a printer object.

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.

See Also

OpenPrinter


PrintHookProc

A PrintHookProc hook procedure is an application-defined or library-defined callback procedure that is used with the Print common dialog box. The hook procedure receives messages or notifications intended for the default dialog box procedure.

UINT APIENTRY PrintHookProc(

HWND hdlg,	// handle to the dialog box window
UINT uiMsg,	// message identifier
WPARAM wParam,	// message parameter
LPARAM lParam	// message parameter
);
Parameters

hdlg

Handle to the Print common dialog box window for which the message is intended.

uiMsg

Identifies the message being received.

wParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

lParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

If the uiMsg parameter indicates the WM_INITDIALOG message, lParam is a pointer to a PRINTDLG structure containing the values specified when the common dialog box was created.

Return Values

If the hook procedure returns zero, the default dialog box procedure processes the message.

If the hook procedure returns a nonzero value, the default dialog box procedure ignores the message.

Remarks

When you use the PrintDlg function to create a Print common dialog box, you can provide a PrintHookProc hook procedure to process messages or notifications intended for the dialog box procedure. To enable the hook procedure, use the PRINTDLG structure that you passed to the dialog creation function. Specify the address of the hook procedure in the lpfnPrintHook member and specify the PD_ENABLEPRINTHOOK flag in the Flags member.

The default dialog box procedure processes the WM_INITDIALOG message before passing it to the hook procedure. For all other messages, the hook procedure receives the message first. Then, the return value of the hook procedure determines whether the default dialog procedure processes the message or ignores it.

If the hook procedure processes the WM_CTLCOLORDLG message, it must return a valid brush handle for painting the background of the dialog box. In general, if the hook procedure processes any WM_CTLCOLOR* message, it must return a valid brush handle for painting the background of the specified control.

Do not call the EndDialog function from the hook procedure. Instead, the hook procedure can call the PostMessage function to post a WM_COMMAND message with the IDABORT value to the dialog box procedure. Posting IDABORT closes the dialog box and causes the dialog box function to return FALSE. If you need to know why the hook procedure closed the dialog box, you must provide your own communication mechanism between the hook procedure and your application.

You can subclass the standard controls of the common dialog box. However, the common dialog box procedure may also subclass the controls. Because of this, you should subclass controls when your hook procedure processes the WM_INITDIALOG message. This ensures that your subclass procedure receives the control-specific messages before the subclass procedure set by the dialog box procedure.

PrintHookProc is a placeholder for the application-defined or library-defined function name. The LPPRINTHOOKPROC type is a pointer to a PrintHookProc hook procedure.

See Also

EndDialog, PostMessage, PrintDlg, PRINTDLG, WM_INITDIALOG, WM_CTLCOLORDLG


PrivilegeCheck

The PrivilegeCheck function tests the security context represented by a specific access token to discover whether it contains the specified privileges. This function is typically called by a server application to check the privileges of a client’s access token.

BOOL PrivilegeCheck(

HANDLE ClientToken,	// handle of client’s access token
PPRIVILEGE_SET RequiredPrivileges,	// address of privileges
LPBOOL pfResult	// address of flag for result
);
Parameters

ClientToken

Identifies an access token representing a client process. This handle must have been obtained by opening the token of a thread impersonating the client. The token must be open for TOKEN_QUERY access.

RequiredPrivileges

Points to a PRIVILEGE_SET structure specifying the privileges required.

The specified access token is checked to see which of the specified privileges are present. When a privilege specified in the PRIVILEGE_SET structure is found in the access token, the function sets the SE_PRIVILEGE_USED_FOR_ACCESS attribute for that privilege in the corresponding LUID_AND_ATTRIBUTES structure.

pfResult

Points to a flag the function sets to indicate whether the access token contains any or all of the specified privileges. If PRIVILEGE_SET_ALL_NECESSARY is specified in the Control member of the PRIVILEGE_SET structure pointed to by the RequiredPrivileges parameter, this flag is TRUE only if all requested privileges are present in the access token. If PRIVILEGE_SET_ALL_NECESSARY is not specified, and if any of the privileges are present, this flag is TRUE.

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.

See Also

AccessCheck, AccessCheckAndAuditAlarm, AreAllAccessesGranted, AreAnyAccessesGranted, LookupPrivilegeDisplayName, LookupPrivilegeName, LookupPrivilegeValue, LUID_AND_ATTRIBUTES, ObjectPrivilegeAuditAlarm, PRIVILEGE_SET, PrivilegedServiceAuditAlarm


PrivilegedServiceAuditAlarm

The PrivilegedServiceAuditAlarm function generates audit messages when an attempt is made to perform privileged system service operations. Alarms are not supported in the current version of Windows NT.

BOOL PrivilegedServiceAuditAlarm(

LPCTSTR SubsystemName,	// address of string for subsystem name
LPCTSTR ServiceName,	// address of string for service name
HANDLE ClientToken,	// handle of access token
PPRIVILEGE_SET Privileges,	// address of privileges
BOOL AccessGranted	// flag for granted access rights
);
Parameters

SubsystemName

Points to a null-terminated string specifying the name of the subsystem calling the function, such as “DEBUG” or “WIN32”.

ServiceName

Points to a null-terminated string specifying the name of the privileged subsystem service. For example, “RESET RUNTIME LOCAL SECURITY POLICY” might be specified by a local security authority service used to update the local security policy database.

ClientToken

Identifies an access token representing the client that requested the operation. This handle must have been obtained by opening the token of a thread impersonating the client. The token must be open for TOKEN_QUERY access.

Privileges

Points to a PRIVILEGE_SET structure containing the privileges required to perform the operation. The information in this structure is supplied by a call to the PrivilegeCheck function.

AccessGranted

Specifies a flag indicating whether access was granted or denied in a previous call to an access-checking function, such as PrivilegeCheck. If access is granted, this flag is TRUE. If access is denied, it is FALSE.

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.

Remarks

The PrivilegedServiceAuditAlarm function requires the calling process to have SE_AUDIT_NAME privilege. The test for this privilege is always performed against the primary token of the calling process. This allows the calling process to impersonate a client during the call.

See Also

AccessCheck, AccessCheckAndAuditAlarm, AreAllAccessesGranted, AreAnyAccessesGranted, MapGenericMask, ObjectCloseAuditAlarm, ObjectDeleteAuditAlarm, ObjectOpenAuditAlarm, ObjectPrivilegeAuditAlarm, PrivilegeCheck, PRIVILEGE_SET


PropEnumProc

A PropEnumProc function is an application-defined callback function that receives property entries from a window’s property list. A PropEnumProc function is called as a result of a call to the EnumProps function. A value of type PROPENUMPROC is a pointer to a PropEnumProc function.

BOOL CALLBACK PropEnumProc(

HWND hwnd,	// handle to window whose property list is being enumerated
LPCTSTR lpszString,	// string component of property
HANDLE hData	// data handle component of property
);
Parameters

hwnd

Handle to the window whose property list is being enumerated.

lpszString

Pointer to a null-terminated string. This string is the string component of a property list entry. This is the string that was specified, along with a data handle, when the property was added to the window’s property list via a call to the SetProp function.

hData

Handle to data. This handle is the data component of a property list entry.

Return Values

Return TRUE to continue the property list enumeration.

Return FALSE to stop the property list enumeration.

Remarks

The following restrictions apply to this callback function:

•	The callback function must not yield control or do anything that might yield control to other tasks.

•	The callback function can call the RemoveProp function. However, RemoveProp can remove only the property passed to the callback function through the callback function’s parameters.

•	The callback function should not attempt to add properties.

PropEnumProc is a placeholder for the application-defined function name.

See Also

EnumProps, EnumPropsEx, PropEnumProcEx, RemoveProp, SetProp


PropEnumProcEx

A PropEnumProcEx function is an application-defined callback function that receives property entries from a window’s property list. A PropEnumProcEx function is called as a result of a call to the EnumPropsEx function. A value of type PROPENUMPROCEX is a pointer to a PropEnumProcEx function.

BOOL CALLBACK PropEnumProcEx(

HWND hwnd,	// handle of window with property
LPTSTR lpszString,	// string component of property
HANDLE hData,	// data handle component of property
DWORD dwData	// application-defined data
);
Parameters

hwnd

Handle to the window whose property list is being enumerated.

lpszString

Pointer to a null-terminated string. This string is the string component of a property list entry. This is the string that was specified, along with a data handle, when the property was added to the window’s property list via a call to the SetProp function.

hData

Handle to data. This handle is the data component of a property list entry.

dwData

Application-defined data. This is the value that was specified as the lParam parameter of the call to EnumPropsEx that initiated the enumeration.

Return Values

Return TRUE to continue the property list enumeration.

Return FALSE to stop the property list enumeration.

Remarks

The following restrictions apply to this callback function:

•	The callback function must not yield control or do anything that might yield control to other tasks.

•	The callback function can call the RemoveProp function. However, RemoveProp can remove only the property passed to the callback function through the callback function’s parameters.

•	The callback function should not attempt to add properties.

PropEnumProcEx is a placeholder for the application-defined function name.

See Also

EnumProps, EnumPropsEx, PropEnumProc, RemoveProp, SetProp


PropertySheet

The PropertySheet function creates a property sheet and adds the pages defined in the specified property sheet header structure.

int PropertySheet(

LPCPROPSHEETHEADER lppsph
);
Parameters

lppsph

Pointer to a PROPSHEETHEADER structure that defines the frame and pages of a property sheet.

Return Values

Returns a positive value if successful or − 1 otherwise.

If the dwFlags member of the PROPSHEETHEADER structure specifies the PSH_MODELESS flag, the successful return value is the window handle of the property sheet dialog.

The following return values have a special meaning:

Value	Meaning
ID_PSREBOOTSYSTEM	A page sent the PSM_REBOOTSYSTEM message to the property sheet. The computer must be restarted for the user’s changes to take effect.
ID_PSRESTARTWINDOWS	A page sent the PSM_RESTARTWINDOWS message to the property sheet. Windows must be restarted for the user’s changes to take effect.
Remarks

By default, PropertySheet creates a modal dialog. If the dwFlags member of the PROPSHEETHEADER structure specifies the PSH_MODELESS flag, PropertySheet creates a modeless dialog and returns immediately after the dialog is created. In this case, the PropertySheet return value is the window handle of the modeless dialog.

For a modeless property sheet, your message loop should use PSM_ISDIALOGMESSAGE to pass messages to the property sheet dialog. Your message loop should use PSM_GETCURRENTPAGEHWND to determine when to destroy the dialog. When the user selects the OK or Cancel button, PSM_GETCURRENTPAGEHWND returns NULL, and you can then use the DestroyWindow function to destroy the dialog.

See Also

DestroyWindow, PROPSHEETHEADER, PSM_GETCURRENTPAGEHWND, PSM_ISDIALOGMESSAGE, PSM_REBOOTSYSTEM, PSM_RESTARTWINDOWS


PropSheetPageProc

The PropSheetPageProc function specifies an application-defined callback function that a property sheet calls when a page is created and when it is about to be destroyed. An application can use this function to perform initialization and cleanup operations for the page.

UINT CALLBACK PropSheetPageProc(

HWND hwnd,
UINT uMsg,
LPPROPSHEETPAGE ppsp
);
Parameters

hwnd

Reserved; must be NULL.

uMsg

Action flag. This parameter can be one of the following values:

Value	Meaning
PSPCB_CREATE	A page is being created. Return nonzero to allow the page to be created or zero to prevent it.
PSPCB_RELEASE	A page is being destroyed. The return value is ignored.
ppsp

Pointer to a PROPSHEETPAGE structure that defines the page being created or destroyed.

Return Values

The return value depends on the value of uMsg.

Remarks

An application must specify the address of this callback function in the pfnCallback member of a PROPSHEETPAGE structure before specifying the address of the structure in a call to the CreatePropertySheetPage function.

See Also

CreatePropertySheetPage, PROPSHEETPAGE


PropSheetProc

A PropSheetProc function is an application-defined callback function that the system calls when the property sheet is being created and initialized.

int CALLBACK PropSheetProc(

HWND hwndDlg,	// handle to the property sheet dialog box
UINT uMsg,	// message identifier
LPARAM lParam	// message parameter
);
Parameters

hwndDlg

Handle to the property sheet dialog box.

uMsg

Identifies the message being received. This parameter is one of the following values:

Value	Meaning
PSCB_INITIALIZED	Indicates that the property sheet is being initialized. The lParam value is zero for this message.
PSCB_PRECREATE	Indicates that the property sheet is about to be created. The hwndDlg parameter is NULL and the lParam parameter is a pointer to a dialog template in memory. This template is in the form of a DLGTEMPLATE structure followed by one or more DLGITEMTEMPLATE structures.
lParam

Specifies additional information about the message. The meaning of this value depends on the uMsg parameter.

Return Values

The function returns zero.

Remarks

To enable a PropSheetProc callback function, use the PROPSHEETHEADER structure when you call the PropertySheet function to create the property sheet. Use the pfnCallback member to specify a pointer to the callback function, and set the PSP_USECALLBACK flag in the dwFlags member.

PropSheetProc is a placeholder for the application-defined function name. The PFNPROPSHEETCALLBACK type is a pointer to a PropSheetProc callback function.

See Also

DLGTEMPLATE, DLGITEMTEMPLATE, PropertySheet, PROPSHEETHEADER


PtInRect

The PtInRect function determines whether the specified point lies within the specified rectangle. A point is within a rectangle if it lies on the left or top side or is within all four sides. A point on the right or bottom side is considered outside the rectangle.

BOOL PtInRect(

CONST RECT *lprc,	// address of structure with rectangle
POINT pt	// structure with point
);
Parameters

lprc

Points to a RECT structure that contains the specified rectangle.

pt

Specifies a POINT structure that contains the specified point.

Return Values

If the specified point lies within the rectangle, the return value is nonzero.

If the specified point does not lie within the rectangle, the return value is zero. To get extended error information, call GetLastError.

See Also

EqualRect, IsRectEmpty, POINT, RECT


PtInRegion

The PtInRegion function determines whether the specified point is inside the specified region.

BOOL PtInRegion(

HRGN hrgn,	// handle of region
int X,	// x-coordinate of point
int Y	// y-coordinate of point
);
Parameters

hrgn

Identifies the region to be examined.

X

Specifies the x-coordinate of the point.

Y

Specifies the y-coordinate of the point.

Return Values

If the specified point is in the region, the return value is nonzero.

If the specified point is not in the region, the return value is zero.

See Also

RectInRegion


PtVisible

The PtVisible function indicates whether the specified point is within the clipping region of a device context.

BOOL PtVisible(

HDC hdc,	// handle of device context
int X,	// x-coordinate of point
int Y	// y-coordinate of point
);
Parameters

hdc

Identifies the device context.

X

Specifies the logical x-coordinate of the point.

Y

Specifies the logical y-coordinate of the point.

Return Values

If the specified point is within the clipping region of the device context, the return value is nonzero.

If the specified point is not within the clipping region of the device context, the return value is zero.

See Also

RectVisible


PulseEvent

The PulseEvent function provides a single operation that sets (to signaled) the state of the specified event object and then resets it (to nonsignaled) after releasing the appropriate number of waiting threads.

BOOL PulseEvent(

HANDLE hEvent	// handle of event object
);
Parameters

hEvent

Identifies the event object. The CreateEvent or OpenEvent function returns this handle.

Windows NT: The handle must have EVENT_MODIFY_STATE access. For more information, see Interprocess Synchronization Objects.

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.

Remarks

For a manual-reset event object, all waiting threads that can be released immediately are released. The function then resets the event object’s state to nonsignaled and returns.

For an auto-reset event object, the function resets the state to nonsignaled and returns after releasing a single waiting thread, even if multiple threads are waiting.

If no threads are waiting, or if no thread can be released immediately, PulseEvent simply sets the event object’s state to nonsignaled and returns.

Note that for a thread using the multiple-object wait functions to wait for all specified objects to be signaled, PulseEvent can set the event object’s state to signaled and reset it to nonsignaled without causing the wait function to return. This happens if not all of the specified objects are simultaneously signaled.

See Also

CreateEvent, OpenEvent, ResetEvent, SetEvent


PurgeComm

The PurgeComm function can discard all characters from the output or input buffer of a specified communications resource. It can also terminate pending read or write operations on the resource.

BOOL PurgeComm(

HANDLE hFile,	// handle of communications resource
DWORD dwFlags	// action to perform
);
Parameters

hFile

Identifies the communications resource. The CreateFile function returns this handle.

dwFlags

Specifies the action to take. This parameter can be a combination of the following values:

Value	Meaning
PURGE_TXABORT	Terminates all outstanding write operations and returns immediately, even if the write operations have not been completed.
PURGE_RXABORT	Terminates all outstanding read operations and returns immediately, even if the read operations have not been completed.
PURGE_TXCLEAR	Clears the output buffer (if the device driver has one).
PURGE_RXCLEAR	Clears the input buffer (if the device driver has one).
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.

Remarks

If a thread uses PurgeComm to flush an output buffer, the deleted characters are not transmitted. To empty the output buffer while ensuring that the contents are transmitted, call the FlushFileBuffers function (a synchronous operation). Note, however, that FlushFileBuffers is subject to flow control but not to write time-outs, and it will not return until all pending write operations have been transmitted.

See Also

CreateFile


QueryDosDevice

The QueryDosDevice function lets an application obtain information about MS-DOS device names. The function can obtain the current mapping for a particular MS-DOS device name. The function can also obtain a list of all existing MS-DOS device names.

MS-DOS device names are stored as symbolic links in the Windows NT object name space. The code that converts an MS-DOS path into a corresponding Windows NT path uses these symbolic links to map MS-DOS devices and drive letters. The QueryDosDevice function provides a mechanism whereby a Win32-based application can query the names of the symbolic links used to implement the MS-DOS device namespace as well as the value of each specific symbolic link.

DWORD QueryDosDevice(

LPCTSTR lpDeviceName,	// address of MS-DOS device name string
LPTSTR lpTargetPath,	// address of buffer for storing query results
DWORD ucchMax	// maximum storage capacity of buffer
);
Parameters

lpDeviceName

Pointer to an MS-DOS device name string specifying the target of the query.

This parameter can be NULL. In that case, the QueryDosDevice function will store a list of all existing MS-DOS device names into the buffer pointed to by lpTargetPath.

lpTargetPath

Pointer to a buffer that will receive the result of the query. The function fills this buffer with one or more null-terminated strings. The final null-terminated string is followed by an additional NULL.

If lpDeviceName is non-NULL, the function obtains information about the particular MS-DOS device specified by lpDeviceName. The first null-terminated string stored into the buffer is the current mapping for the device. The other null-terminated strings represent undeleted prior mappings for the device.

If lpDeviceName is NULL, the function obtains a list of all existing MS-DOS device names. Each null-terminated string stored into the buffer is the name of an existing MS-DOS device.

ucchMax

Specifies the maximum number of characters that can be stored into the buffer pointed to by lpTargetPath.

Return Values

If the function succeeds, the return value is the number of characters stored into the buffer pointed to by lpTargetPath.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The DefineDosDevice function provides a means whereby a Win32-based application can create and modify the symbolic links used to implement the MS-DOS device namespace.

MS-DOS device names are global. Once defined, an MS-DOS device name remains visible to all processes until either it is explicity removed or the system reboots.

See Also

DefineDosDevice


QueryPerformanceCounter

The QueryPerformanceCounter function retrieves the current value of the high-resolution performance counter, if one exists.

BOOL QueryPerformanceCounter(

LARGE_INTEGER *lpPerformanceCount	// address of current counter value
);
Parameters

lpPerformanceCount

Points to a variable that the function sets, in counts, to the current performance-counter value. If the installed hardware does not support a high-resolution performance counter, this parameter can be to zero.

Return Values

If the installed hardware supports a high-resolution performance counter, the return value is nonzero.

If the installed hardware does not support a high-resolution performance counter, the return value is zero.

See Also

QueryPerformanceFrequency


QueryPerformanceFrequency

The QueryPerformanceFrequency function retrieves the frequency of the high-resolution performance counter, if one exists.

BOOL QueryPerformanceFrequency(

LARGE_INTEGER *lpFrequency	// address of current frequency
);
Parameters

lpFrequency

Points to a variable that the function sets, in counts per second, to the current performance-counter frequency. If the installed hardware does not support a high-resolution performance counter, this parameter can be to zero.

Return Values

If the installed hardware supports a high-resolution performance counter, the return value is nonzero.

If the installed hardware does not support a high-resolution performance counter, the return value is zero.

See Also

QueryPerformanceCounter


QueryServiceConfig

The QueryServiceConfig function retrieves the configuration parameters of the specified service.

BOOL QueryServiceConfig(

SC_HANDLE hService,	// handle of service
LPQUERY_SERVICE_CONFIG lpServiceConfig,	// address of service config. structure
DWORD cbBufSize,	// size of service configuration buffer
LPDWORD pcbBytesNeeded	// address of variable for bytes needed
);
Parameters

hService

Identifies the service. This handle is returned by the OpenService or CreateService function, and it must have SERVICE_QUERY_CONFIG access.

lpServiceConfig

Points to a QUERY_SERVICE_CONFIG structure in which the service configuration information is returned.

cbBufSize

Specifies the size, in bytes, of the buffer pointed to by the lpServiceConfig parameter.

pcbBytesNeeded

Points to a variable that receives the number of bytes needed to return all the configuration information.

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.

Errors

The following error codes can be set by the service control manager. Others can be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED	The specified handle was not opened with SERVICE_QUERY_CONFIG access.
ERROR_INSUFFICIENT_BUFFER	There is more service configuration information than would fit into the lpServiceConfig buffer. The number of bytes required to get all the information is returned in the pcbBytesNeeded parameter. Nothing is written to the lpServiceConfig buffer.
ERROR_INVALID_HANDLE	The specified handle is invalid.
Remarks

The QueryServiceConfig function returns the service configuration information kept in the registry for a particular service. This configuration information was first set via the CreateService function, and may have been updated via the ChangeServiceConfig function. If the service was running when the configuration information was last changed, the information returned with the QueryServiceConfig will not reflect the true configuration of the service that is running. Instead, it will reflect the configuration of the service when it is run next. Upon stopping the service, the service control manager database will be updated with the configuration that is stored in the registry. The DisplayName key is an exception to this. When the DisplayName key is changed, it takes effect immediately regardless of whether the service is running.

The lpServiceConfig buffer must be large enough to hold the strings pointed to by the members of the QUERY_SERVICE_CONFIG structure.

See Also

ChangeServiceConfig, CreateService, OpenService, QUERY_SERVICE_CONFIG, QueryServiceObjectSecurity, QueryServiceStatus


QueryServiceLockStatus

The QueryServiceLockStatus function retrieves the lock status of the specified service control manager database.

BOOL QueryServiceLockStatus(

SC_HANDLE hSCManager,	// handle of svc. ctrl. mgr. database
LPQUERY_SERVICE_LOCK_STATUS lpLockStatus,	// address of lock status structure
DWORD cbBufSize,	// size of service configuration buffer
LPDWORD pcbBytesNeeded	// address of variable for bytes needed
);
Parameters

hSCManager

Identifies the service control manager database. The OpenSCManager function returns this handle, which must have SC_MANAGER_QUERY_LOCK_STATUS access.

lpLockStatus

Points to a QUERY_SERVICE_LOCK_STATUS structure in which the lock status of the specified database is returned.

cbBufSize

Specifies the size, in bytes, of the buffer pointed to by the lpLockStatus parameter.

pcbBytesNeeded

Points to a variable that receives the number of bytes needed to return all the lock status information.

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.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED
	The specified handle was not opened with SC_MANAGER_QUERY_LOCK_STATUS access.
ERROR_INSUFFICIENT_BUFFER
	There is more lock status information than would fit into the lpLockStatus buffer. The number of bytes required to get all the information is returned in the pcbBytesNeeded parameter. Nothing is written to the lpLockStatus buffer.
ERROR_INVALID_HANDLE
	The specified handle is invalid.
Remarks

The QueryServiceLockStatus function returns a QUERY_SERVICE_LOCK_STATUS structure that indicates whether the specified database is locked. If the database is locked, the structure provides the account name of the user that holds the lock and the length of time that the lock has been held.

A process calls the LockServiceDatabase function to lock a service control manager database and the UnlockServiceDatabase function to release the lock.

The lpLockStatus buffer must be large enough to hold the string pointed to by the lpLockOwner member of the QUERY_SERVICE_LOCK_STATUS structure.

See Also

LockServiceDatabase, OpenSCManager, QUERY_SERVICE_LOCK_STATUS, UnlockServiceDatabase


QueryServiceObjectSecurity

The QueryServiceObjectSecurity function retrieves a copy of the security descriptor protecting a service object.

BOOL QueryServiceObjectSecurity(

SC_HANDLE hService,	// handle of service
SECURITY_INFORMATION dwSecurityInformation,	// type of security information requested
PSECURITY_DESCRIPTOR lpSecurityDescriptor,	// address of security descriptor
DWORD cbBufSize,	// size of security descriptor buffer
LPDWORD pcbBytesNeeded	// address of variable for bytes needed
);
Parameters

hService

Identifies the service. This handle is returned by the OpenService or CreateService function, and it must have READ_CONTROL access.

dwSecurityInformation

Specifies the security information being requested. Any or all of the following flags can be specified:

Value	Meaning
OWNER_SECURITY_INFORMATION	Requests the object’s owner security identifier (SID).
GROUP_SECURITY_INFORMATION	Requests the object’s primary group SID.
DACL_SECURITY_INFORMATION	Requests the object’s discretionary access control list (ACL).
SACL_SECURITY_INFORMATION	Requests the object’s system ACL. The calling process must have the SE_SECURITY_NAME privilege. For more information about privileges, see Privileges.
lpSecurityDescriptor

Points to a buffer that receives a copy of the security descriptor of the specified service object. The calling process must have the appropriate access to view the specified aspects of the object’s security descriptor. The SECURITY_DESCRIPTOR structure is returned in self-relative format.

cbBufSize

Specifies the size, in bytes, of the buffer pointed to by the lpSecurityDescriptor parameter.

pcbBytesNeeded

Points to a variable that receives the number of bytes needed to return all the requested security descriptor information.

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.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED	The specified handle was not opened with READ_CONTROL access, or the calling process is not the owner of the object.
ERROR_INVALID_HANDLE	The specified handle is invalid.
ERROR_INSUFFICIENT_BUFFER	There is more security descriptor information than would fit into the lpSecurityDescriptor buffer. The number of bytes required to get all the information is returned in the pcbBytesNeeded parameter. Nothing is written to the lpSecurityDescriptor buffer.
ERROR_INVALID_PARAMETER	The specified security information is invalid.
Remarks

The initial security descriptor of a service object is created by the service control manager, based on the security descriptor of the process that called the CreateService function to create the service. The security descriptor can be changed by calling the SetServiceObjectSecurity function.

See Also

CreateService, OpenService, SECURITY_DESCRIPTOR, SetServiceObjectSecurity


QueryServiceStatus

The QueryServiceStatus function retrieves the current status of the specified service.

BOOL QueryServiceStatus(

SC_HANDLE hService,	// handle of service
LPSERVICE_STATUS lpServiceStatus	// address of service status structure
);
Parameters

hService

Identifies the service. This handle is returned by the OpenService or the CreateService function, and it must have SERVICE_QUERY_STATUS access.

lpServiceStatus

Points to a SERVICE_STATUS structure in which the status information is returned.

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.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED	The specified handle was not opened with SERVICE_QUERY_STATUS access.
ERROR_INVALID_HANDLE	The specified handle is invalid.
Remarks

The QueryServiceStatus function returns the most recent service status information reported to the service control manager. The service may have just changed its status and may not have updated the service control manager yet. Applications can find out the absolutely latest service status by interrogating the service directly by using the ControlService function with the SERVICE_CONTROL_INTERROGATE control code.

See Also

ControlService, CreateService, OpenService, SERVICE_STATUS, SetServiceStatus


QueueUserAPC [New - Windows NT]
QueueUserAPC

[New - Windows NT]

The QueueUserAPC function adds a user-mode asynchronous procedure call (APC) object to the APC queue of the specified thread.

DWORD QueueUserAPC(

PAPCFUNC pfnAPC,	// pointer to APC function
HANDLE hThread,	// handle to the thread
DWORD dwData	// argument for the APC function
);
Parameters

pfnAPC

Points to the application-supplied APC function to be called when the specified thread performs an alertable wait operation.

hThread

Specifies the handle to the thread. The handle must have THREAD_SET_CONTEXT access. For more information, see Thread Objects.

dwData

Specifies a single DWORD argument that is passed to the APC function pointed to by the pfnAPC parameter.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. There are no error values defined for this function that can be retrieved by calling GetLastError.

Remarks

The APC support provided in the operating system allows an application to queue an APC object to a thread. Each thread has its own APC queue. The queuing of an APC is a request for the thread to call the APC function. The operating system issues a software interrupt to direct the thread to call the APC function.

When a user-mode APC is queued, the thread is not directed to call the APC function unless it is in an alertable state. A thread enters an alertable state by using SleepEx, SignalObjectAndWait, WaitForSingleObjectEx, WaitForMultipleObjectsEx, or MsgWaitForMultipleObjectsEx to perform an alertable wait operation. After the thread is in an alertable state, the thread handles all pending APCs in first in, first out (FIFO) order, and the wait operation returns WAIT_IO_COMPLETION.

If an application queues an APC before the thread begins running, the thread begins by calling the APC function. Once the thread calls an APC function, it calls the APC functions for all APCs in its APC queue.

When the thread is terminated using the ExitThread or TerminateThread function, the APCs in its APC queue are lost. The APC functions are not called.

Note that the ReadFileEx and WriteFileEx functions are implemented using an APC as the completion notification callback mechanism.

See Also

MsgWaitForMultipleObjectsEx, ReadFileEx, SleepEx, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFileEx


RaiseException

The RaiseException function raises an exception in the calling thread.

VOID RaiseException(

DWORD dwExceptionCode,	// exception code
DWORD dwExceptionFlags,	// continuable exception flag
DWORD nNumberOfArguments,	// number of arguments in array
CONST DWORD *lpArguments	// address of array of arguments
);
Parameters

dwExceptionCode

Specifies the application-defined exception code of the exception being raised. The filter expression and exception-handler block of an exception handler can use the GetExceptionCode function to retrieve this value.

Note that the system will clear bit 28 of dwExceptionCode. This bit is a reserved exception bit, used by the system for its own purposes. For example, after calling the RaiseException function with a dwExceptionCode value of 0xEFFFFFFF Windows displays a message indicating that the exception number is 0xEFFFFFFF.

dwExceptionFlags

Specifies the exception flags. This can be either zero to indicate a continuable exception, or EXCEPTION_NONCONTINUABLE to indicate a noncontinuable exception. Any attempt to continue execution after a noncontinuable exception causes the EXCEPTION_NONCONTINUABLE_EXCEPTION exception.

nNumberOfArguments

Specifies the number of arguments in the lpArguments array. This value must not exceed EXCEPTION_MAXIMUM_PARAMETERS. This parameter is ignored if lpArguments is NULL.

lpArguments

Points to an array of 32-bit arguments. This parameter can be NULL. These arguments can contain any application-defined data that needs to be passed to the filter expression of the exception handler.

Return Values

This function does not return a value.

Remarks

The RaiseException function enables a process to use structured exception handling to handle private, software-generated, application-defined exceptions.

Raising an exception causes the exception dispatcher to go through the following search for an exception handler:

1.	The system first attempts to notify the process’s debugger, if any.

2.	If the process is not being debugged, or if the associated debugger does not handle the exception, the system attempts to locate a frame-based exception handler by searching the stack frames of the thread in which the exception occurred. The system searches the current stack frame first, then proceeds backward through preceding stack frames.

3.	If no frame-based handler can be found, or no frame-based handler handles the exception, the system makes a second attempt to notify the process’s debugger.

4.	If the process is not being debugged, or if the associated debugger does not handle the exception, the system provides default handling based on the exception type. For most exceptions, the default action is to call the ExitProcess function.

The values specified in the dwExceptionCode, dwExceptionFlags, nNumberOfArguments, and lpArguments parameters can be retrieved in the filter expression of a try-except frame-based exception handler by calling the GetExceptionInformation function. A debugger can retrieve these values by calling the WaitForDebugEvent function.

See Also

ExitProcess, GetExceptionCode, GetExceptionInformation, WaitForDebugEvent


RASADFunc [New - Windows NT]
RASADFunc

[New - Windows NT]

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.

See Also

RasDial, RASENTRY, RasSetEntryProperties


RasAdminAcceptNewConnection [New - Windows NT]
RasAdminAcceptNewConnection

[New - Windows NT]

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.

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.

See Also

RAS_PARAMETERS, RAS_PORT_1, RAS_PORT_STATISTICS


RasAdminConnectionHangupNotification [New - Windows NT]
RasAdminConnectionHangupNotification

[New - Windows NT]

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.

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.

See Also

RAS_PARAMETERS, RAS_PORT_1, RAS_PORT_STATISTICS


RasAdminFreeBuffer [New - Windows NT]
RasAdminFreeBuffer

[New - Windows NT]

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.
Do not call GetLastError to get error information for this function.

Remarks

Use the RasAdminFreeBuffer function to free the buffers allocated by the RasAdminPortEnum and RasAdminPortGetInfo functions.

See Also

RasAdminPortEnum, RasAdminPortGetInfo


RasAdminGetErrorString [New - Windows NT]
RasAdminGetErrorString

[New - Windows NT]

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.
Do not call GetLastError to get error information for this function.

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.

See Also

LoadLibrary, GlobalAlloc, LoadString


RasAdminGetIpAddressForUser [New - Windows NT]
RasAdminGetIpAddressForUser

[New - Windows NT]

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.

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.

See Also

RasAdminReleaseIpAddress


RasAdminGetUserAccountServer [New - Windows NT]
RasAdminGetUserAccountServer

[New - Windows NT]

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.
Do not call GetLastError to get error information for this function.

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.

See Also

GetComputerName, RasAdminUserGetInfo, RasAdminUserSetInfo


RasAdminPortClearStatistics [New - Windows NT]
RasAdminPortClearStatistics

[New - Windows NT]

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.
Do not call GetLastError to get error information for this function.

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.

See Also

RAS_PORT_STATISTICS, RasAdminPortGetInfo


RasAdminPortDisconnect [New - Windows NT]
RasAdminPortDisconnect

[New - Windows NT]

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.
Do not call GetLastError to get error information for this function.


RasAdminPortEnum [New - Windows NT]
RasAdminPortEnum

[New - Windows NT]

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.
Do not call GetLastError to get error information for this function.

See Also

RAS_PORT_0, RasAdminFreeBuffer


RasAdminPortGetInfo [New - Windows NT]
RasAdminPortGetInfo

[New - Windows NT]

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.
Do not call GetLastError to get error information for this function.

See Also

RAS_PARAMETERS, RAS_PORT_1, RAS_PORT_STATISTICS, RasAdminFreeBuffer


RasAdminReleaseIpAddress [New - Windows NT]
RasAdminReleaseIpAddress

[New - Windows NT]

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

None.

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.

See Also

RasAdminGetIpAddressForUser


RasAdminServerGetInfo [New - Windows NT]
RasAdminServerGetInfo

[New - Windows NT]

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. Do not call GetLastError to get error information for this function.

Remarks

To enumerate all RAS servers in a Windows NT domain, call the NetServerEnum function and specify SV_TYPE_DIALIN for the servertype parameter.

See Also

NetServerEnum, RAS_SERVER_0


RasAdminUserGetInfo [New - Windows NT]
RasAdminUserGetInfo

[New - Windows NT]

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.
Do not call GetLastError to get error information for this function.

See Also

RAS_USER_0, RasAdminGetUserAccountServer, RasAdminUserSetInfo


RasAdminUserSetInfo [New - Windows NT]
RasAdminUserSetInfo

[New - Windows NT]

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.
Do not call GetLastError to get error information for this function.

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.

See Also

RAS_USER_0, RasAdminGetUserAccountServer, RasAdminUserGetInfo


RasConnectionNotification [New - Windows NT]
RasConnectionNotification

[New - Windows NT]

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(

HANDLE hEvent,	// handle to an event object
DWORD dwFlags	// type of event to receive notifications for
);
Parameters

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	A new RAS connection has been created.
RASCN_Disconnection	An existing RAS connection has been terminated.
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.

See Also

CreateEvent, RasEnumConnections


RasCreatePhonebookEntry

The RasCreatePhonebookEntry function creates a new phone-book entry. The function displays a dialog box in which the user types information about 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
LPTSTR 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.
See Also

RasEditPhonebookEntry, RasEntryDlg, RasGetEntryDialParams, RasSetEntryDialParams


RasDeleteEntry [New - Windows NT]
RasDeleteEntry

[New - Windows NT]

The RasDeleteEntry function deletes an entry from a phone book.

DWORD RasDeleteEntry(

LPTSTR lpszPhonebook,	// pointer to full path and filename of phone-book file
LPTSTR 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.

See Also

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

See Also

RasDialDlg, RasDialFunc, RasDialFunc1, RasDialFunc2, RasGetConnectStatus, RasHangUp, RASDIALEXTENSIONS, RASDIALPARAMS, WM_RASDIALEVENT


RasDialDlg [New - Windows NT]
RasDialDlg

[New - Windows NT]

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.

See Also

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

See Also

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.

See Also

RasDial, RasDialFunc, RasDialFunc2, RASCONNSTATE, RasEnumConnections, RasEnumEntries, RasGetConnectStatus, RasGetErrorString, RasHangUp


RasDialFunc2 [New - Windows NT]
RasDialFunc2

[New - Windows NT]

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 that, for 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.

See Also

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
LPTSTR lpszPhonebook,	// pointer to the full path and filename of the phone-book file
LPTSTR 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.
See Also

RasCreatePhonebookEntry, RasEntryDlg, RasGetEntryDialParams, RasSetEntryDialParams


RasEntryDlg [New - Windows NT]
RasEntryDlg

[New - Windows NT]

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.

See Also

RasCreatePhonebookEntry, RasEditPhonebookEntry, RASENTRYDLG


RasEnumAutodialAddresses [New - Windows NT]
RasEnumAutodialAddresses

[New - Windows NT]

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

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

See Also

RASCONN, RasEnumEntries, RasGetConnectStatus


RasEnumDevices [New - Windows NT]
RasEnumDevices

[New - Windows NT]

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

RASDEVINFO


RasEnumEntries

The RasEnumEntries function lists all entry names in a remote access phone book.

DWORD RasEnumEntries (

LPTSTR reserved,	// reserved, must be NULL
LPTSTR 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.

See Also

RASENTRYNAME, RasEnumConnections


RasGetAutodialAddress [New - Windows NT]
RasGetAutodialAddress

[New - Windows NT]

The RasGetAutodialAddress function retrieves information about all the AutoDial entries associated with a network address in the AutoDial mapping database.

DWORD RasGetAutodialAddress(

LPTSTR 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.
See Also

RASAUTODIALENTRY, RasEnumAutodialAddresses, RasSetAutodialAddress


RasGetAutodialEnable [New - Windows NT]
RasGetAutodialEnable

[New - Windows NT]

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.

See Also

RasSetAutodialEnable


RasGetAutodialParam [New - Windows NT]
RasGetAutodialParam

[New - Windows NT]

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

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.

See Also

RASCONNSTATUS, RasDial, RasEnumConnections


RasGetCountryInfo [New - Windows NT]
RasGetCountryInfo

[New - Windows NT]

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.

See Also

RASCTRYINFO


RasGetCredentials [New - Windows NT]
RasGetCredentials

[New - Windows NT]

The RasGetCredentials function retrieves the user credentials associated with a specified RAS phone-book entry.

DWORD RasGetCredentials(

LPTSTR lpszPhonebook,	// pointer to the full path and filename of a phone-book file
LPTSTR 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.

See Also

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(

LPTSTR 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

Points to a RASDIALPARAMS structure that receives the connection parameters associated with the phone-book entry specified by the szEntryName member. On entry, the dwSize member must specify the size of the RASDIALPARAMS structure, and the szEntryName member must specify a valid phone-book entry.

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

RasDial, RASDIALPARAMS, RasCreatePhonebookEntry, RasEditPhonebookEntry, RasSetEntryDialParams


RasGetEntryProperties [New - Windows NT]
RasGetEntryProperties

[New - Windows NT]

The RasGetEntryProperties function retrieves the properties of a phone-book entry.

DWORD RasGetEntryProperties(

LPTSTR lpszPhonebook,	// pointer to full path and filename of phone-book file
LPTSTR 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 Win32 Telephony (TAPI) Programmer’s Reference.

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.

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

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.

See Also

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.

See Also

RASAMB, RasDial, RasEnumConnections, RASPPPNBF, RASPPPIPX, RASPPPIP, RASPROJECTION


RasGetSubEntryHandle [New - Windows NT]
RasGetSubEntryHandle

[New - Windows NT]

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.

See Also

RasDial, RasGetConnectStatus, RasGetProjectionInfo, RasHangUp


RasGetSubEntryProperties [New - Windows NT]
RasGetSubEntryProperties

[New - Windows NT]

The RasGetSubEntryProperties function retrieves information about a subentry for a specified phone-book entry.

DWORD RasGetSubEntryProperties(

LPTSTR lpszPhonebook,	// pointer to full path and filename of phone-book file
LPTSTR 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
);
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.

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.

See Also

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.

See Also

RASCONN, RasDial, RasEnumConnections, RasGetConnectStatus, Sleep


RasMonitorDlg [New - Windows NT]
RasMonitorDlg

[New - Windows NT]

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.

See Also

RASMONITORDLG


RasPBDlgFunc [New - Windows NT]
RasPBDlgFunc

[New - Windows NT]

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.

See Also

RASNOUSER, RasPhonebookDlg


RasPhonebookDlg [New - Windows NT]
RasPhonebookDlg

[New - Windows NT]

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.

See Also

RASPBDLG


RasRenameEntry [New - Windows NT]
RasRenameEntry

[New - Windows NT]

The RasRenameEntry function changes the name of an entry in a phone book.

DWORD RasRenameEntry(

LPTSTR lpszPhonebook,	// pointer to full path and filename of phone-book file
LPTSTR lpszOldEntry,	// pointer to the old entry name
LPTSTR 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.
See Also

RasValidateEntryName


RasSecurityDialogBegin [New - Windows NT]
RasSecurityDialogBegin

[New - Windows NT]

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.

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.

See Also

RasSecurityDialogComplete, RasSecurityDialogReceive, RasSecurityDialogSend


RasSecurityDialogComplete [New - Windows NT]
RasSecurityDialogComplete

[New - Windows NT]

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.

See Also

RasSecurityDialogBegin, RasSecurityDialogComplete, RasSecurityDialogEnd, SECURITY_MESSAGE


RasSecurityDialogEnd [New - Windows NT]
RasSecurityDialogEnd

[New - Windows NT]

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.

See Also

RasSecurityDialogBegin, RasSecurityDialogComplete


RasSecurityDialogGetInfo [New - Windows NT]
RasSecurityDialogGetInfo

[New - Windows NT]

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.

See Also

GetProcAddress, LoadLibrary, RAS_SECURITY_INFO, RasSecurityDialogReceive


RasSecurityDialogReceive [New - Windows NT]
RasSecurityDialogReceive

[New - Windows NT]

The RasSecurityDialogReceive function starts an asynchronous operation that receives a response from a remote user. 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 variable that receives 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.

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.

See Also

CreateEvent, GetProcAddress, LoadLibrary, RASCONNSTATE,  RasSecurityDialogSend,  WaitForSingleObject


RasSecurityDialogSend [New - Windows NT]
RasSecurityDialogSend

[New - Windows NT]

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.

See Also

GetProcAddress, LoadLibrary, RASCONNSTATE, RasSecurityDialogBegin, RasSecurityDialogReceive


RasSetAutodialAddress [New - Windows NT]
RasSetAutodialAddress

[New - Windows NT]

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(

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

See Also

RASAUTODIALENTRY, RasEnumAutodialAddresses, RasGetAutodialAddress


RasSetAutodialEnable [New - Windows NT]
RasSetAutodialEnable

[New - Windows NT]

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.

See Also

RasGetAutodialEnable


RasSetAutodialParam [New - Windows NT]
RasSetAutodialParam

[New - Windows NT]

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

RasGetAutodialParam, RasSetAutodialAddress


RasSetCredentials [New - Windows NT]
RasSetCredentials

[New - Windows NT]

The RasSetCredentials function sets the user credentials associated with a specified RAS phone-book entry.

DWORD RasSetCredentials(

LPTSTR lpszPhonebook,	// pointer to the full path and filename of a phone-book file
LPTSTR lpszEntry,	// pointer to the name of a phone-book entry
LPRASCREDENTIALS lpCredentials	// pointer to structure that specifies the 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 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.

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.

See Also

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(

LPTSTR 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.
See Also

RASDIALPARAMS, RasCreatePhonebookEntry, RasEditPhonebookEntry, RasGetEntryDialParams


RasSetEntryProperties [New - Windows NT]
RasSetEntryProperties

[New - Windows NT]

The RasSetEntryProperties function changes the connection information for an entry in the phone book or creates a new phone-book entry.

DWORD RasSetEntryProperties(

LPTSTR lpszPhonebook,	// pointer to full path and filename of phone-book file
LPTSTR 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 Win32 Telephony (TAPI) Programmer’s Reference.

dwDeviceInfoSize

Specifies the size, in bytes, of the lpbDeviceInfo 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_BUFFER_INVALID	The address or buffer specified by lpRasEntry is invalid.
ERROR_CANNOT_OPEN_PHONEBOOK	The phone book is corrupted or missing components.
See Also

RASENTRY, RasCreatePhonebookEntry, RasGetEntryProperties, RasValidateEntryName


RasSetSubEntryProperties [New - Windows NT]
RasSetSubEntryProperties

[New - Windows NT]

The RasSetSubEntryProperties function creates a new subentry or modifies an existing subentry of a specified phone-book entry.

DWORD RasSetSubEntryProperties(

LPTSTR lpszPhonebook,	// pointer to full path and filename of phone-book file	// pointer to the full path and filename of the phone-book file
LPTSTR lpszEntry,	// pointer to an entry name	// pointer to an entry name
DWORD dwSubEntry,	// index of the subentry	//
LPRASSUBENTRY lpRasSubEntry,	// pointer to structure containing information about subentry	//
DWORD dwcb	// size, in bytes, of the structure	//
);
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.

dwcb

Specifies the size, in bytes, of the lpRasSubEntry 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_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.

See Also

RasGetEntryProperties, RASENTRY, RASSUBENTRY


RasValidateEntryName [New - Windows NT]
RasValidateEntryName

[New - Windows NT]

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(

LPTSTR lpszPhonebook,	// pointer to full path and filename of phone-book file
LPTSTR 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.

See Also

RasCreatePhonebookEntry, RasGetEntryProperties


ReadConsole

The ReadConsole function reads character input from the console input buffer and removes it from the buffer.

BOOL ReadConsole(

HANDLE hConsoleInput,	// handle of a console input buffer
LPVOID lpBuffer,	// address of buffer to receive data
DWORD nNumberOfCharsToRead,	// number of characters to read
LPDWORD lpNumberOfCharsRead,	// address of number of characters read
LPVOID lpReserved	// reserved
);
Parameters

hConsoleInput

Identifies the console input buffer. The handle must have GENERIC_READ access.

lpBuffer

Points to a buffer that receives the data read from the console input buffer.

nNumberOfCharsToRead

Specifies the number of characters to read. Because the function can read either 2-byte Unicode or 1-byte ANSI characters, the size of the buffer pointed to by the lpBuffer parameter should be at least nNumberOfCharsToRead * sizeof(TCHAR).

lpNumberOfCharsRead

Points to a 32-bit variable that receives the number of characters actually read.

lpReserved

Reserved; must be NULL.

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.

Remarks

ReadConsole reads keyboard input from a console’s input buffer. It behaves like the ReadFile function, except that it can read in either Unicode (wide-character) or ANSI mode. To have applications that maintain a single set of sources compatible with both modes, use ReadConsole rather than ReadFile. Although ReadConsole can only be used with a console input buffer handle, ReadFile can be used with other handles (such as files or pipes). ReadConsole fails if used with a standard handle that has been redirected to be something other than a console handle.

All of the input modes that affect the behavior of ReadFile have the same effect on ReadConsole. To retrieve and set the input modes of a console input buffer, use the GetConsoleMode and SetConsoleMode functions.

If the input buffer contains input events other than keyboard events (such as mouse events or window-resizing events), they are discarded. Those events can only be read by using the ReadConsoleInput function.

Windows NT: This function uses either Unicode characters or 8-bit characters from the console's current codepage. The console's codepage defaults initially to the system's OEM codepage. To change the console's codepage, use the SetConsoleCP or SetConsoleOutputCP functions, or use the chcp or mode con cp select= commands.

See Also

GetConsoleMode, ReadConsoleInput, ReadFile, SetConsoleCP, SetConsoleMode, SetConsoleOutputCP, WriteConsole


ReadConsoleInput

The ReadConsoleInput function reads data from a console input buffer and removes it from the buffer.

BOOL ReadConsoleInput(

HANDLE hConsoleInput,	// handle of a console input buffer
PINPUT_RECORD lpBuffer,	// address of the buffer for read data
DWORD nLength,	// number of records to read
LPDWORD lpNumberOfEventsRead	// address of number of records read
);
Parameters

hConsoleInput

Identifies the input buffer. The handle must have GENERIC_READ access.

lpBuffer

Points to an INPUT_RECORD buffer that receives the input buffer data.

nLength

Specifies the size, in input records, of the buffer pointed to by the lpBuffer parameter.

lpNumberOfEventsRead

Points to a 32-bit variable that receives the number of input records read.

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.

Remarks

If the number of records requested in the nLength parameter exceeds the number of records available in the buffer, the number available is read. The function does not return until at least one input record has been read.

A process can specify a console input buffer handle in one of the wait functions to determine when there is unread console input. When the input buffer is not empty, the state of a console input buffer handle is signaled.

To determine the number of unread input records in a console’s input buffer, use the GetNumberOfConsoleInputEvents function. To read input records from a console input buffer without affecting the number of unread records, use the PeekConsoleInput function. To discard all unread records in a console’s input buffer, use the FlushConsoleInputBuffer function.

Windows NT: This function uses either Unicode characters or 8-bit characters from the console's current codepage. The console's codepage defaults initially to the system's OEM codepage. To change the console's codepage, use the SetConsoleCP or SetConsoleOutputCP functions, or use the chcp or mode con cp select= commands.

See Also

FlushConsoleInputBuffer, GetNumberOfConsoleInputEvents, INPUT_RECORD, PeekConsoleInput, ReadConsole, ReadFile, SetConsoleCP, SetConsoleOutputCP, WriteConsoleInput


ReadConsoleOutput

The ReadConsoleOutput function reads character and color attribute data from a rectangular block of character cells in a console screen buffer, and the function writes the data to a rectangular block at a specified location in the destination buffer.

BOOL ReadConsoleOutput(

HANDLE hConsoleOutput,	// handle of a console screen buffer
PCHAR_INFO lpBuffer,	// address of buffer that receives data
COORD dwBufferSize,	// column-row size of destination buffer
COORD dwBufferCoord,	// upper-left cell to write to
PSMALL_RECT lpReadRegion	// address of rectangle to read from
);
Parameters

hConsoleOutput

Identifies the screen buffer. The handle must have GENERIC_READ access.

lpBuffer

Points to a destination buffer that receives the data read from the screen buffer. This pointer is treated as the origin of a two-dimensional array of CHAR_INFO structures whose size is specified by the dwBufferSize parameter.

dwBufferSize

Specifies the size, in character cells, of the lpBuffer parameter. The X member of the COORD structure is the number of columns; the Y member is the number of rows.

dwBufferCoord

Specifies the coordinates of the upper-left cell in the lpBuffer parameter that receives the data read from the screen buffer. The X member of the COORD structure is the column, and the Y member is the row.

lpReadRegion

Points to a SMALL_RECT structure. On input, the structure members specify the upper-left and lower-right coordinates of the screen buffer rectangle from which the function is to read. On output, the structure members specify the actual rectangle that the function copied from.

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.

Remarks

ReadConsoleOutput treats the screen buffer and the destination buffer as two-dimensional arrays (columns and rows of character cells). The rectangle pointed to by the lpReadRegion parameter specifies the size and location of the block to be read from the screen buffer. A destination rectangle of the same size is located with its upper-left cell at the coordinates of the dwBufferCoord parameter in the lpBuffer array. Data read from the cells in the screen buffer source rectangle is copied to the corresponding cells in the destination buffer. If the corresponding cell is outside the boundaries of the destination buffer rectangle (whose dimensions are specified by the dwBufferSize parameter), the data is not copied.

Cells in the destination buffer corresponding to coordinates that are not within the boundaries of the screen buffer are left unchanged. In other words, these are the cells for which no screen buffer data is available to be read.

Before ReadConsoleOutput returns, it sets the members of the structure pointed to by the lpReadRegion parameter to the actual screen buffer rectangle whose cells were copied into the destination buffer. This rectangle reflects the cells in the source rectangle for which there existed a corresponding cell in the destination buffer, because ReadConsoleOutput clips the dimensions of the source rectangle to fit the boundaries of the screen buffer.

If the rectangle specified by lpReadRegion lies completely outside the boundaries of the screen buffer, or if the corresponding rectangle is positioned completely outside the boundaries of the destination buffer, no data is copied. In this case, the function returns with the members of the structure pointed to by the lpReadRegion parameter set such that the Right member is less than the Left, or the Bottom member is less than the Top. To determine the size of the screen buffer, use the GetConsoleScreenBufferInfo function.

The ReadConsoleOutput function has no effect on the screen buffer’s cursor position. The contents of the screen buffer are not changed by the function.

Windows NT: This function uses either Unicode characters or 8-bit characters from the console's current codepage. The console's codepage defaults initially to the system's OEM codepage. To change the console's codepage, use the SetConsoleCP or SetConsoleOutputCP functions, or use the chcp or mode con cp select= commands.

See Also

CHAR_INFO, COORD, ReadConsoleOutputAttribute, ReadConsoleOutputCharacter, SetConsoleCP, SetConsoleOutputCP, SMALL_RECT, WriteConsoleOutput


ReadConsoleOutputAttribute

The ReadConsoleOutputAttribute function copies a specified number of foreground and background color attributes from consecutive cells of a console screen buffer, beginning at a specified location.

BOOL ReadConsoleOutputAttribute(

HANDLE hConsoleOutput,	// handle of a console screen buffer
LPWORD lpAttribute,	// address of buffer to receive attributes
DWORD nLength,	// number of character cells to read from
COORD dwReadCoord,	// coordinates of first cell to read from
LPDWORD lpNumberOfAttrsRead	// address of number of cells read from
);
Parameters

hConsoleOutput

Identifies a console screen buffer. The handle must have GENERIC_READ access.

lpAttribute

Points to a buffer that receives the attributes read from the screen buffer.

nLength

Specifies the number of screen buffer character cells from which to read. The size of the buffer pointed to by the lpAttribute parameter should be nLength * sizeof(WORD).

dwReadCoord

Specifies the coordinates of the first cell in the screen buffer from which to read. The X member of the COORD structure is the column, and the Y member is the row.

lpNumberOfAttrsRead

Points to a 32-bit variable that receives the number of attributes actually read.

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.

Remarks

If the number of attributes to be read from extends beyond the end of the specified screen buffer row, attributes are read from the next row. If the number of attributes to be read from extends beyond the end of the screen buffer, attributes up to the end of the screen buffer are read.

Each attribute specifies the foreground (text) and background colors in which that character cell is drawn. The attribute values are some combination of the following values: FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_RED, FOREGROUND_INTENSITY, BACKGROUND_BLUE, BACKGROUND_GREEN, BACKGROUND_RED, and BACKGROUND_INTENSITY. For example, the following combination of values produces red text on a white background:

FOREGROUND_RED | BACKGROUND_RED | BACKGROUND_GREEN | BACKGROUND_BLUE

See Also

COORD, ReadConsoleOutput, ReadConsoleOutputCharacter, WriteConsoleOutput, WriteConsoleOutputAttribute, WriteConsoleOutputCharacter


ReadConsoleOutputCharacter

The ReadConsoleOutputCharacter function copies a number of characters from consecutive cells of a console screen buffer, beginning at a specified location.

BOOL ReadConsoleOutputCharacter(

HANDLE hConsoleOutput,	// handle of a console screen buffer
LPTSTR lpCharacter,	// address of buffer to receive characters
DWORD nLength,	// number of character cells to read from
COORD dwReadCoord,	// coordinates of first cell to read from
LPDWORD lpNumberOfCharsRead	// address of number of cells read from
);
Parameters

hConsoleOutput

Identifies a console screen buffer. The handle must have GENERIC_READ access.

lpCharacter

Points to a buffer that receives the characters read from the screen buffer.

nLength

Specifies the number of screen buffer character cells from which to read. The size of the buffer pointed to by the lpCharacter parameter should be nLength * sizeof(TCHAR).

dwReadCoord

Specifies the coordinates of the first cell in the screen buffer from which to read. The X member of the COORD structure is the column, and the Y member is the row.

lpNumberOfCharsRead

Points to a 32-bit variable that receives the number of characters actually read.

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.

Remarks

If the number of characters to be read from extends beyond the end of the specified screen buffer row, characters are read from the next row. If the number of characters to be read from extends beyond the end of the screen buffer, characters up to the end of the screen buffer are read.

Windows NT: This function uses either Unicode characters or 8-bit characters from the console's current codepage. The console's codepage defaults initially to the system's OEM codepage. To change the console's codepage, use the SetConsoleCP or SetConsoleOutputCP functions, or use the chcp or mode con cp select= commands.

See Also

COORD, ReadConsoleOutput, ReadConsoleOutputAttribute, SetConsoleCP, SetConsoleOutputCP, WriteConsoleOutput, WriteConsoleOutputAttribute, WriteConsoleOutputCharacter


ReadDirectoryChangesW [New - Windows NT]
ReadDirectoryChangesW

[New - Windows NT]

The ReadDirectoryChangesW function returns information describing the changes occurring within a directory.

BOOL ReadDirectoryChangesW(

HANDLE hDirectory,	// handle to the directory to be watched
LPVOID lpBuffer,	// pointer to the buffer to receive the read results
DWORD nBufferLength,	// length of lpBuffer
BOOL bWatchSubtree,	// flag for monitoring directory or directory tree
DWORD dwNotifyFilter,	// filter conditions to watch for
LPDWORD lpBytesReturned,	// number of bytes returned
LPOVERLAPPED lpOverlapped,	// pointer to structure needed for overlapped I/O
LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine	// pointer to completion routine
);
Parameters

hDirectory

Identifies the directory to be watched. This directory must be opened with the FILE_LIST_DIRECTORY access right.

lpBuffer

Specifies the address of the formatted buffer in which the read results are to be returned. The structure of this buffer is defined by the FILE_NOTIFY_INFORMATION structure. This buffer is filled either synchronously or asynchronously, depending on how the directory is opened and what value is given to the lpOverlapped parameter. For more information, see the Remarks section.

nBufferLength

Specifies the length of the buffer pointed to by the lpBuffer parameter.

bWatchSubtree

Specifies whether the ReadDirectoryChangesW function will monitor the directory or the directory tree. If TRUE is specified, the function monitors the directory tree rooted at the specified directory. If FALSE is specified, the function monitors only the directory specified by the hDirectory parameter.

dwNotifyFilter

Specifies filter criteria the function checks to determine if the wait operation has completed. This parameter can be one or more of the following values:

Value	Meaning
FILE_NOTIFY_CHANGE_FILE_NAME	Any filename change in the watched directory or subtree causes a change notification wait operation to return. Changes include renaming, creating, or deleting a file.
FILE_NOTIFY_CHANGE_DIR_NAME	Any directory-name change in the watched directory or subtree causes a change notification wait operation to return. Changes include creating or deleting a directory.
FILE_NOTIFY_CHANGE_ATTRIBUTES	Any attribute change in the watched directory or subtree causes a change notification wait operation to return.
FILE_NOTIFY_CHANGE_SIZE	Any file-size change in the watched directory or subtree causes a change notification wait operation to return. The operating system detects a change in file size only when the file is written to the disk. For operating systems that use extensive caching, detection occurs only when the cache is sufficiently flushed.
FILE_NOTIFY_CHANGE_LAST_WRITE	Any change to the last write-time of files in the watched directory or subtree causes a change notification wait operation to return. The operating system detects a change to the last write-time only when the file is written to the disk. For operating systems that use extensive caching, detection occurs only when the cache is sufficiently flushed.
FILE_NOTIFY_CHANGE_LAST_ACCESS	Any change to the last access time of files in the watched directory or subtree causes a change notification wait operation to return.
FILE_NOTIFY_CHANGE_CREATION	Any change to the creation time of files in the watched directory or subtree causes a change notification wait operation to return.
FILE_NOTIFY_CHANGE_SECURITY	Any security-descriptor change in the watched directory or subtree causes a change notification wait operation to return.
lpBytesReturned

For synchronous calls, this parameter specifies the number of bytes transferred into the lpBuffer parameter. For asynchronous calls, this parameter is undefined. You must use an asynchronous notification technique to retrieve the number of bytes transferred.

lpOverlapped

Points to an OVERLAPPED structure that supplies data to be used during asynchronous operation. Otherwise, this value is NULL. The Offset and OffsetHigh members of this structure are not used.

lpCompletionRoutine

Points to a completion routine to be called when the operation has been completed and the calling thread is in an alertable wait state. For more information about this completion routine, see FileIOCompletionRoutine.

Return Value

If the function succeeds, the return value is nonzero. For synchronous calls, this means that the operation succeeded. For asynchronous calls, this indicates that the operation was successfully queued.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

To obtain a handle to a directory, use the CreateFile function with FILE_FLAG_BACKUP_SEMANTICS as follows:

hDir = CreateFile (

          DirName,                       // pointer to the file name

          FILE_LIST_DIRECTORY,           // access (read-write) mode

          FILE_SHARE_READ|FILE_SHARE_DELETE,  // share mode

          NULL,                               // security descriptor

          OPEN_EXISTING,                      // how to create

          FILE_FLAG_BACKUP_SEMANTICS,         // file attributes

          NULL                           // file with attributes to copy

        );

A call to ReadDirectoryChangesW can be completed synchronously or asynchronously. To specify asynchronous completion, open the directory with CreateFile as shown above, but additionally specify the FILE_FLAG_OVERLAPPED attribute in the dwFlagsAndAttributes parameter. Then specify an OVERLAPPED structure when you call ReadDirectoryChangesW.

Upon successful synchronous completion, the lpBuffer parameter is a formatted buffer and the number of bytes written to the buffer is available in lpBytesReturned. If the number of bytes transferred is zero, the buffer was too small to provide detailed information on all the changes that occurred in the directory or subtree. In this case, you should compute the changes by enumerating the directory or subtree.

For asynchronous completion, you can receive notification in one of three ways:

•	Using the GetOverlappedResult function. To receive notification through GetOverlappedResult, do not specify a completion routine in the lpCompletionRoutine parameter. Be sure to set the hEvent member of the OVERLAPPED structure to a unique event.

•	Using the GetQueuedCompletionStatus function. To receive notification through GetQueuedCompletionStatus, do not specify a completion routine in lpCompletionRoutine. Associate the directory handle hDirectory with a completion port by calling the CreateIoCompletionPort function.

•	Using a completion routine. To receive notification through a completion routine, do not associate the directory with a completion port. Specify a completion routine in lpCompletionRoutine. This routine is called whenever the operation completes while the thread is in an alertable wait state. The hEvent member of the OVERLAPPED structure is not used by the system, so you can use it yourself.

See Also

CreateFile, CreateIoCompletionPort, FILE_NOTIFY_INFORMATION, FileIOCompletionRoutine, GetOverlappedResult, GetQueuedCompletionStatus, OVERLAPPED


ReadEventLog

The ReadEventLog function reads a whole number of entries from the specified event log. The function can be used to read log entries in forward or reverse chronological order.

BOOL ReadEventLog(

HANDLE hEventLog,	// handle of event log
DWORD dwReadFlags,	// specifies how to read log
DWORD dwRecordOffset,	// number of first record
LPVOID lpBuffer,	// address of buffer for read data
DWORD nNumberOfBytesToRead,	// number of bytes to read
DWORD *pnBytesRead,	// number of bytes read
DWORD *pnMinNumberOfBytesNeeded	// number of bytes required for next record
);
Parameters

hEventLog

Identifies the event log to read. This handle is returned by the OpenEventLog function.

dwReadFlags

Specifies how the read operation is to proceed. This parameter can be any combination of the following values:

Value	Meaning
EVENTLOG_FORWARDS_READ	The log is read in forward chronological order.
EVENTLOG_BACKWARDS_READ	The log is read in reverse chronological order.
EVENTLOG_SEEK_READ	The read operation proceeds from the record specified by the dwRecordOffset parameter. If this flag is used, dwReadFlags must also specify EVENTLOG_FORWARDS_READ or EVENTLOG_BACKWARDS_READ. If the buffer is large enough, more than one record can be read at the specified seek position; the additional flag indicates the direction for successive read operations.
EVENTLOG_SEQUENTIAL_READ	The read operation proceeds sequentially from the last call to the ReadEventLog function using this handle.
dwRecordOffset

Specifies the log-entry record number at which the read operation should start. This parameter is ignored unless the dwReadFlags parameter includes the EVENTLOG_SEEK_READ flag.

lpBuffer

Points to a buffer for the data read from the event log. This parameter cannot be NULL, even if the nNumberOfBytesToRead parameter is zero.

The buffer will be filled with an EVENTLOGRECORD structure.

nNumberOfBytesToRead

Specifies the size, in bytes, of the buffer. This function will read as many whole log entries as will fit in the buffer; the function will not return partial entries, even if there is room in the buffer.

pnBytesRead

Points to a variable that receives the number of bytes read by the function.

pnMinNumberOfBytesNeeded

Points to a variable that receives the number of bytes required for the next log entry. This count is valid only if ReadEventLog returns zero and GetLastError returns ERROR_INSUFFICIENT_BUFFER.

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.

Remarks

When this function returns, the read position in the error log is adjusted by the number of records read. Only a whole number of event log records will be returned.

Note  The configured filename for this source may also be the configured filename for other sources (several sources can exist as subkeys under a single logfile). Therefore, this function may return events that were logged by more than one source.

See Also

ClearEventLog, CloseEventLog, EVENTLOGRECORD, OpenEventLog, ReportEvent


ReadFile

The ReadFile function reads data from a file, starting at the position indicated by the file pointer. After the read operation has been completed, the file pointer is adjusted by the number of bytes actually read, unless the file handle is created with the overlapped attribute. If the file handle is created for overlapped input and output (I/O), the application must adjust the position of the file pointer after the read operation.

BOOL ReadFile(

HANDLE hFile,	// handle of file to read
LPVOID lpBuffer,	// address of buffer that receives data
DWORD nNumberOfBytesToRead,	// number of bytes to read
LPDWORD lpNumberOfBytesRead,	// address of number of bytes read
LPOVERLAPPED lpOverlapped	// address of structure for data
);
Parameters

hFile

Identifies the file to be read. The file handle must have been created with GENERIC_READ access to the file.

Windows NT

For asynchronous read operations, hFile can be any handle opened with the FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle returned by the socket or accept functions.

Windows 95

For asynchronous read operations, hFile can be a communications resource, mailslot, or named pipe handle opened with the FILE_FLAG_OVERLAPPED flag by CreateFile, or a socket handle returned by the socket or accept functions. Windows 95 does not support asynchronous read operations on disk files.

lpBuffer

Points to the buffer that receives the data read from the file.

nNumberOfBytesToRead

Specifies the number of bytes to be read from the file.

lpNumberOfBytesRead

Points to the number of bytes read. ReadFile sets this value to zero before doing any work or error checking. If this parameter is zero when ReadFile returns TRUE on a named pipe, the other end of the message-mode pipe called the WriteFile function with nNumberOfBytesToWrite set to zero.

If lpOverlapped is NULL, lpNumberOfBytesRead cannot be NULL.

If lpOverlapped is not NULL, lpNumberOfBytesRead can be NULL. If this is an overlapped read operation, you can get the number of bytes read by calling GetOverlappedResult. If hFile is associated with an I/O completion port, you can get the number of bytes read by calling GetQueuedCompletionStatus.

lpOverlapped

Points to an OVERLAPPED structure. This structure is required if hFile was created with FILE_FLAG_OVERLAPPED.

If hFile was opened with FILE_FLAG_OVERLAPPED, the lpOverlapped parameter must not be NULL. It must point to a valid OVERLAPPED structure. If hFile was created with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function can incorrectly report that the read operation is complete.

If hFile was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the read operation starts at the offset specified in the OVERLAPPED structure and ReadFile may return before the read operation has been completed. In this case, ReadFile returns FALSE and the GetLastError function returns ERROR_IO_PENDING. This allows the calling process to continue while the read operation finishes. The event specified in the OVERLAPPED structure is set to the signaled state upon completion of the read operation.

If hFile was not opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the read operation starts at the current file position and ReadFile does not return until the operation has been completed.

If hFile is not opened with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the read operation starts at the offset specified in the OVERLAPPED structure. ReadFile does not return until the read operation has been completed.

Return Values

If the function succeeds, the return value is nonzero.

If the return value is nonzero and the number of bytes read is zero, the file pointer was beyond the current end of the file at the time of the read operation. However, if the file was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the return value is FALSE and GetLastError returns ERROR_HANDLE_EOF when the file pointer goes beyond the current end of file.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

ReadFile returns when one of the following is true: a write operation completes on the write end of the pipe, the number of bytes requested has been read, or an error occurs.

If part of the file is locked by another process and the read operation overlaps the locked portion, this function fails.

Applications must not read from nor write to the input buffer that a read operation is using until the read operation completes. A premature access to the input buffer may lead to corruption of the data read into that buffer.

Characters can be read from the console input buffer by using ReadFile with a handle to console input. The console mode determines the exact behavior of the ReadFile function.

If a named pipe is being read in message mode and the next message is longer than the nNumberOfBytesToRead parameter specifies, ReadFile returns FALSE and GetLastError returns ERROR_MORE_DATA. The remainder of the message may be read by a subsequent call to the ReadFile or PeekNamedPipe function.

When reading from a communications device, the behavior of ReadFile is governed by the current communication timeouts as set and retrieved using the SetCommTimeouts and GetCommTimeouts functions. Unpredictable results can occur if you fail to set the timeout values. For more information about communication timeouts, see COMMTIMEOUTS.

If ReadFile attempts to read from a mailslot whose buffer is too small, the function returns FALSE and GetLastError returns ERROR_INSUFFICIENT_BUFFER.

If the anonymous write pipe handle has been closed and ReadFile attempts to read using the corresponding anonymous read pipe handle, the function returns FALSE and GetLastError returns ERROR_BROKEN_PIPE.

The ReadFile function may fail and return ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests.

The ReadFile code to check for the end-of-file condition (eof) differs for synchronous and asynchronous read operations.

When a synchronous read operation reaches the end of a file, ReadFile returns TRUE and sets *lpNumberOfBytesRead to zero. The following sample code tests for end-of-file for a synchronous read operation:

// attempt a synchronous read operation

bResult = ReadFile(hFile, &inBuffer, nBytesToRead, &nBytesRead, NULL) ;

// check for eof

if (bResult &&  nBytesRead == 0, ) {

// we’re at the end of the file

}

An asynchronous read operation can encounter the end of a file during the initiating call to ReadFile, or during subsequent asynchronous operation.

If EOF is detected at ReadFile time for an asynchronous read operation, ReadFile returns FALSE and GetLastError returns ERROR_HANDLE_EOF.

If EOF is detected during subsequent asynchronous operation, the call to GetOverlappedResult to obtain the results of that operation returns FALSE and GetLastError returns ERROR_HANDLE_EOF.

To cancel all pending asynchronous I/O operations, use the CancelIO function. This function only cancels operations issued by the calling thread for the specified file handle. I/O operations that are canceled complete with the error ERROR_OPERATION_ABORTED.

The following sample code illustrates testing for end-of-file for an asynchronous read operation:

// set up overlapped structure fields

// to simplify this sample, we'll eschew an event handle

gOverLapped.Offset     = 0;

gOverLapped.OffsetHigh = 0;

gOverLapped.hEvent     = NULL;

// attempt an asynchronous read operation

bResult = ReadFile(hFile, &inBuffer, nBytesToRead, &nBytesRead,

    &gOverlapped) ;

// if there was a problem, or the async. operation's still pending ...

if (!bResult)

{

    // deal with the error code

    switch (dwError = GetLastError())

    {

        case ERROR_HANDLE_EOF:

        {

            // we're reached the end of the file

            // during the call to ReadFile

            // code to handle that

        }

        case ERROR_IO_PENDING:

        {

            // asynchronous i/o is still in progress

            // do something else for a while

            GoDoSomethingElse() ;

            // check on the results of the asynchronous read

            bResult = GetOverlappedResult(hFile, &gOverlapped,

                &nBytesRead, FALSE) ;

            // if there was a problem ...

            if (!bResult)

            {

                // deal with the error code

                switch (dwError = GetLastError())

                {

                    case ERROR_HANDLE_EOF:

                    {

                        // we're reached the end of the file

                        //during asynchronous operation

                    }

                    // deal with other error cases

                }

            }

        } // end case

        // deal with other error cases

    } // end switch

} // end if

See Also

CancelIo, CreateFile, GetCommTimeouts, GetOverlappedResult, GetQueuedCompletionStatus, OVERLAPPED, PeekNamedPipe, ReadFileEx, SetCommTimeouts, WriteFile


ReadFileEx

The ReadFileEx function reads data from a file asynchronously. It is designed solely for asynchronous operation, unlike the ReadFile function, which is designed for both synchronous and asynchronous operation. ReadFileEx lets an application perform other processing during a file read operation.

The ReadFileEx function reports its completion status asynchronously, calling a specified completion routine when reading is completed and the calling thread is in an alertable wait state.

BOOL ReadFileEx(

HANDLE hFile,	// handle of file to read
LPVOID lpBuffer,	// address of buffer
DWORD nNumberOfBytesToRead,	// number of bytes to read
LPOVERLAPPED lpOverlapped,	// address of offset
LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine	// address of completion routine
);
Parameters

hFile

An open handle that specifies the file entity to be read from. This file handle must have been created with the FILE_FLAG_OVERLAPPED flag and must have GENERIC_READ access to the file.

Windows NT: hFile can be any handle opened with the FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle returned by the socket or accept functions.

Windows 95: hFile can be a communications resource, mailslot, or named pipe handle opened with the FILE_FLAG_OVERLAPPED flag by CreateFile, or a socket handle returned by the socket or accept functions. Windows 95 does not support asynchronous operations on disk files.

lpBuffer

Points to a buffer that receives the data read from the file.

This buffer must remain valid for the duration of the read operation. The application should not use this buffer until the read operation is completed.

nNumberOfBytesToRead

Specifies the number of bytes to be read from the file.

lpOverlapped

Points to an OVERLAPPED data structure that supplies data to be used during the asynchronous (overlapped) file read operation.

If the file specified by hFile supports the concept of byte offsets, the caller of ReadFileEx must specify a byte offset within the file at which reading should begin. The caller specifies the byte offset by setting the OVERLAPPED structure’s Offset and OffsetHigh members.

If the file entity specified by hFile does not support the concept of byte offsets — for example, if it is a named pipe — the caller must set the Offset and OffsetHigh members to zero, or ReadFileEx fails.

The ReadFileEx function ignores the OVERLAPPED structure’s hEvent member. An application is free to use that member for its own purposes in the context of a ReadFileEx call. ReadFileEx signals completion of its read operation by calling, or queueing a call to, the completion routine pointed to by lpCompletionRoutine, so it does not need an event handle.

The ReadFileEx function does use the OVERLAPPED structure’s Internal and InternalHigh members. An application should not set these members.

The OVERLAPPED data structure pointed to by lpOverlapped must remain valid for the duration of the read operation. It should not be a variable that can go out of scope while the file read operation is in progress.

lpCompletionRoutine

Points to the completion routine to be called when the read operation is complete and the calling thread is in an alertable wait state. For more information about the completion routine, see FileIOCompletionRoutine.

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.

If the function succeeds, the calling thread has an asynchronous I/O (input/output) operation pending: the overlapped read operation from the file. When this I/O operation completes, and the calling thread is blocked in an alertable wait state, the system calls the function pointed to by lpCompletionRoutine, and the wait state completes with a return code of WAIT_IO_COMPLETION.

If the function succeeds, and the file reading operation completes, but the calling thread is not in an alertable wait state, the system queues the completion routine call, holding the call until the calling thread enters an alertable wait state. For information about alertable waits and overlapped input/output operations, see Synchronization and Overlapped Input and Output.

If ReadFileEx attempts to read past the end of the file, the function returns zero, and GetLastError returns ERROR_HANDLE_EOF.

Remarks

If a portion of the file specified by hFile is locked by another process, and the read operation specified in a call to ReadFileEx overlaps the locked portion, the call to ReadFileEx fails.

If ReadFileEx attempts to read data from a mailslot whose buffer is too small, the function returns FALSE, and GetLastError returns ERROR_INSUFFICIENT_BUFFER.

Applications must not read from nor write to the input buffer that a read operation is using until the read operation completes. A premature access to the input buffer may lead to corruption of the data read into that buffer.

The ReadFileEx function may fail if there are too many outstanding asynchronous I/O requests. In the event of such a failure, GetLastError can return ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY.

To cancel all pending asynchronous I/O operations, use the CancelIO function. This function only cancels operations issued by the calling thread for the specified file handle. I/O operations that are canceled complete with the error ERROR_OPERATION_ABORTED.

If hFile is a handle to a named pipe or other file entity that doesn’t support the byte-offset concept, the Offset and OffsetHigh members of the OVERLAPPED structure pointed to by lpOverlapped must be zero, or ReadFileEx fails.

An application uses the MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx, WaitForMultipleObjectsEx, and SleepEx functions to enter an alertable wait state. For more information about alertable waits and overlapped input/output, refer to those functions’ reference and Synchronization.

Windows 95: On this platform, neither ReadFileEx nor WriteFileEx can be used by the comm ports to communicate. However, you can use ReadFile and WriteFile to perform asynchronous communication.

See Also

CancelIo, CreateFile, FileIOCompletionRoutine, MsgWaitForMultipleObjectsEx, OVERLAPPED, ReadFile, SleepEx, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFileEx


ReadPrinter

The ReadPrinter function retrieves data from the specified printer.

BOOL ReadPrinter(

HANDLE hPrinter,	// handle of printer object
LPVOID pBuf,	// address of array of bytes that receives data
DWORD cbBuf,	// size, in bytes, of array
LPDWORD pNoBytesRead	// address of variable with number of bytes retrieved
);
Parameters

hPrinter

Identifies the printer for which to retrieve data.

pBuf

Points to an array of bytes that receives the printer data.

cbBuf

Specifies the size, in bytes, of the buffer to which pBuf points.

pNoBytesRead

Points to a variable that receives the number of bytes of data copied into the array to which pBuf points.

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.

Remarks

ReadPrinter returns an error if the device or the printer is not bidirectional.

See Also

OpenPrinter


ReadProcessMemory

The ReadProcessMemory function reads memory in a specified process. The entire area to be read must be accessible, or the operation fails.

BOOL ReadProcessMemory(

HANDLE hProcess,	// handle of the process whose memory is read
LPCVOID lpBaseAddress,	// address to start reading
LPVOID lpBuffer,	// address of buffer to place read data
DWORD nSize,	// number of bytes to read
LPDWORD lpNumberOfBytesRead	// address of number of bytes read
);
Parameters

hProcess

Identifies an open handle of a process whose memory is read. The handle must have PROCESS_VM_READ access to the process.

lpBaseAddress

Points to the base address in the specified process to be read. Before any data transfer occurs, the system verifies that all data in the base address and memory of the specified size is accessible for read access. If this is the case, the function proceeds; otherwise, the function fails.

lpBuffer

Points to a buffer that receives the contents from the address space of the specified process.

nSize

Specifies the requested number of bytes to read from the specified process.

lpNumberOfBytesRead

Points to the actual number of bytes transferred into the specified buffer. If lpNumberOfBytesRead is NULL, the parameter is ignored.

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.

The function fails if the requested read operation crosses into an area of the process that is inaccessible.

Remarks

ReadProcessMemory copies the data in the specified address range from the address space of the specified process into the specified buffer of the current process. Any process that has a handle with PROCESS_VM_READ access can call the function. The process whose address space is read is typically, but not necessarily, being debugged.

The entire area to be read must be accessible. If it is not, the function fails as noted previously.

See Also

WriteProcessMemory


RealizePalette

The RealizePalette function maps palette entries from the current logical palette to the system palette.

UINT RealizePalette(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies the device context (DC) into which a logical palette has been selected.

Return Values

If the function succeeds, the return value is the number of entries in the logical palette mapped to the system palette.

If the function fails, the return value is GDI_ERROR. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

The RealizePalette function modifies the palette for the device associated with the specified device context. If the device context is a memory DC, the color table for the bitmap selected into the DC is modified. If the device context is a display DC, the physical palette for that device is modified.

A logical color palette is a buffer between color-intensive applications and the system, allowing these applications to use as many colors as needed without interfering with colors displayed by other windows.

When an application’s window has the focus and it calls the RealizePalette function, Windows attempts to realize as many of the requested colors as possible. The same is also true for applications with inactive windows.

See Also

CreatePalette, GetDeviceCaps, SelectPalette


Rectangle

The Rectangle function draws a rectangle. The rectangle is outlined by using the current pen and filled by using the current brush.

BOOL Rectangle(

HDC hdc,	// handle of device context
int nLeftRect,	// x-coord. of bounding rectangle’s upper-left corner
int nTopRect,	// y-coord. of bounding rectangle’s upper-left corner
int nRightRect,	// x-coord. of bounding rectangle’s lower-right corner
int nBottomRect	// y-coord. of bounding rectangle’s lower-right corner
);
Parameters

hdc

Identifies the device context.

nLeftRect

Specifies the logical x-coordinate of the upper-left corner of the rectangle.

nTopRect

Specifies the logical y-coordinate of the upper-left corner of the rectangle.

nRightRect

Specifies the logical x-coordinate of the lower-right corner of the rectangle.

nBottomRect

Specifies the logical y-coordinate of the lower-right corner of the rectangle.

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.

Remarks

The current position is neither used nor updated by Rectangle.

See Also

RoundRect


RectInRegion

The RectInRegion function determines whether any part of the specified rectangle is within the boundaries of a region.

BOOL RectInRegion(

HRGN hrgn,	// handle of region
CONST RECT *lprc	// address of structure with rectangle
);
Parameters

hrgn

Identifies the region.

lprc

Points to a RECT structure containing the coordinates of the rectangle. The lower and right edges of the rectangle are not included.

Return Values

If any part of the specified rectangle lies within the boundaries of the region, the return value is nonzero.

If no part of the specified rectangle lies within the boundaries of the region, the return value is zero.

See Also

PtInRegion, RECT


RectVisible

The RectVisible function determines whether any part of the specified rectangle lies within the clipping region of a device context.

BOOL RectVisible(

HDC hdc,	// handle of the device context
CONST RECT *lprc	// address of rectangle structure
);
Parameters

hdc

Identifies the device context.

lprc

Points to a RECT structure that contains the logical coordinates of the specified rectangle.

Return Values

If some portion of the specified rectangle lies within the clipping region, the return value is nonzero.

If no portion of the specified rectangle lies within the clipping region, the return value is zero.

See Also

CreateRectRgn, PtVisible, RECT, SelectClipRgn


RedrawWindow

The RedrawWindow function updates the specified rectangle or region in a window’s client area.

BOOL RedrawWindow(

HWND hWnd,	// handle of window
CONST RECT *lprcUpdate,	// address of structure with update rectangle
HRGN hrgnUpdate,	// handle of update region
UINT flags	// array of redraw flags
);
Parameters

hWnd

Identifies the window to be redrawn. If this parameter is NULL, the desktop window is updated.

lprcUpdate

Points to a RECT structure containing the coordinates of the update rectangle. This parameter is ignored if the hrgnUpdate parameter identifies a region.

hrgnUpdate

Identifies the update region. If both the hrgnUpdate and lprcUpdate parameters are NULL, the entire client area is added to the update region.

flags

Specifies one or more redraw flags. This parameter can be a combination of flags that invalidate or validate a window, control repainting, and control which windows are affected by RedrawWindow.

The following flags are used to invalidate the window:

Flag (invalidation)	Description
RDW_ERASE	Causes the window to receive a WM_ERASEBKGND message when the window is repainted. The RDW_INVALIDATE flag must also be specified; otherwise, RDW_ERASE has no effect.
RDW_FRAME	Causes any part of the nonclient area of the window that intersects the update region to receive a WM_NCPAINT message. The RDW_INVALIDATE flag must also be specified; otherwise, RDW_FRAME has no effect. The WM_NCPAINT message is typically not sent during the execution of RedrawWindow unless either RDW_UPDATENOW or RDW_ERASENOW is specified.
RDW_INTERNALPAINT	Causes a WM_PAINT message to be posted to the window regardless of whether any portion of the window is invalid.
RDW_INVALIDATE	Invalidates lprcUpdate or hrgnUpdate (only one may be non-NULL). If both are NULL, the entire window is invalidated.
The following flags are used to validate the window:

Flag (validation)	Description
RDW_NOERASE	Suppresses any pending WM_ERASEBKGND messages.
RDW_NOFRAME	Suppresses any pending WM_NCPAINT messages. This flag must be used with RDW_VALIDATE and is typically used with RDW_NOCHILDREN. RDW_NOFRAME should be used with care, as it could cause parts of a window to be painted improperly.
RDW_NOINTERNALPAINT	Suppresses any pending internal WM_PAINT messages. This flag does not affect WM_PAINT messages resulting from a non-NULL update area.
RDW_VALIDATE	Validates lprcUpdate or hrgnUpdate (only one may be non-NULL). If both are NULL, the entire window is validated. This flag does not affect internal WM_PAINT messages.
The following flags control when repainting occurs. RedrawWindow will not repaint unless one of these flags is specified.

Flag	Description
RDW_ERASENOW	Causes the affected windows (as specified by the RDW_ALLCHILDREN and RDW_NOCHILDREN flags) to receive WM_NCPAINT and WM_ERASEBKGND messages, if necessary, before the function returns. WM_PAINT messages are received at the ordinary time.
RDW_UPDATENOW	Causes the affected windows (as specified by the RDW_ALLCHILDREN and RDW_NOCHILDREN flags) to receive WM_NCPAINT, WM_ERASEBKGND, and WM_PAINT messages, if necessary, before the function returns.
By default, the windows affected by RedrawWindow depend on whether the given window has the WS_CLIPCHILDREN style. Child windows that are not the WS_CLIPCHILDREN style are unaffected; non-WS_CLIPCHILDREN windows are recursively validated or invalidated until a WS_CLIPCHILDREN window is encountered. The following flags control which windows are affected by the RedrawWindow function:

Flag	Description
RDW_ALLCHILDREN	Includes child windows, if any, in the repainting operation.
RDW_NOCHILDREN	Excludes child windows, if any, from the repainting operation.
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.

Remarks

When RedrawWindow is used to invalidate part of the desktop window, the desktop window does not receive a WM_PAINT message. To repaint the desktop, an application uses the RDW_ERASE flag to generate a WM_ERASEBKGND message.

See Also

GetUpdateRect, GetUpdateRgn, InvalidateRect, InvalidateRgn, RECT, UpdateWindow


RegCloseKey

The RegCloseKey function releases the handle of the specified key.

LONG RegCloseKey(

HKEY hKey	// handle of key to close
);
Parameters

hKey

Identifies the open key to close.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

The handle for a specified key should not be used after it has been closed, because it will no longer be valid. Key handles should not be left open any longer than necessary.

The RegCloseKey function does not necessarily write information to the registry before returning; it can take as much as several seconds for the cache to be flushed to the hard disk. If an application must explicitly write registry information to the hard disk, it can use the RegFlushKey function. RegFlushKey, however, uses many system resources and should be called only when necessary.

See Also

RegCreateKey, RegCreateKeyEx, RegDeleteKey, RegFlushKey, RegOpenKey, RegOpenKeyEx, RegSetValue, RegSetValueEx


RegConnectRegistry

The RegConnectRegistry function establishes a connection to a predefined registry handle on another computer.

LONG RegConnectRegistry(

LPTSTR lpMachineName,	// address of name of remote computer
HKEY hKey,	// predefined registry handle
PHKEY phkResult	// address of buffer for remote registry handle
);
Parameters

lpMachineName

Points to a null-terminated string containing the name of the remote computer. The string has the following form:

\\computername

If lpMachineName is NULL, the local computer name is used.

hKey

Specifies the predefined handle of the registry on the remote computer. Currently, the following values can be used:

HKEY_LOCAL_MACHINE
HKEY_USERS

An application cannot specify the HKEY_CLASSES_ROOT or HKEY_CURRENT_USER value for this parameter.

phkResult

Points to a variable that receives a key handle identifying the predefined handle on the remote computer.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

When a handle returned by RegConnectRegistry is no longer needed, it should be closed by calling RegCloseKey.

See Also

RegCloseKey


RegCreateKey

The RegCreateKey function creates the specified key. If the key already exists in the registry, the function opens it. This function is provided for compatibility with Windows version 3.1. Win32-based applications should use the RegCreateKeyEx function.

LONG RegCreateKey(

HKEY hKey,	// handle of an open key
LPCTSTR lpSubKey,	// address of name of subkey to open
PHKEY phkResult	// address of buffer for opened handle
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

The key opened or created by this function is a subkey of the key identified by hKey.

lpSubKey

Points to a null-terminated string specifying the name of a key that this function opens or creates. This key must be a subkey of the key identified by the hKey parameter.

If hKey is one of the predefined keys, lpSubKey may be NULL. In that case, the handle returned by using phkResult is the same hKey handle passed in to the function.

phkResult

Points to a variable that receives the handle of the opened or created key.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

An application can use the RegCreateKey function to create several keys at once. For example, an application can create a subkey four levels deep at the same time as the three preceding subkeys by specifying a string of the following form for the lpSubKey parameter:

subkey1\subkey2\subkey3\subkey4

The key identified by the hKey parameter must have been opened with KEY_CREATE_SUB_KEY access (KEY_WRITE access includes KEY_CREATE_SUB_KEY access).

If the lpSubKey parameter is the address of an empty string, the function opens and then passes back the key identified by the hKey parameter.

See Also

RegCloseKey, RegCreateKeyEx, RegDeleteKey, RegOpenKey, RegOpenKeyEx, RegSetValue


RegCreateKeyEx

The RegCreateKeyEx function creates the specified key. If the key already exists in the registry, the function opens it.

LONG RegCreateKeyEx(

HKEY hKey,	// handle of an open key
LPCTSTR lpSubKey,	// address of subkey name
DWORD Reserved,	// reserved
LPTSTR lpClass,	// address of class string
DWORD dwOptions,	// special options flag
REGSAM samDesired,	// desired security access
LPSECURITY_ATTRIBUTES lpSecurityAttributes,	// address of key security structure
PHKEY phkResult,	// address of buffer for opened handle
LPDWORD lpdwDisposition	// address of disposition value buffer
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

The key opened or created by the RegCreateKeyEx function is a subkey of the key identified by the hKey parameter.

lpSubKey

Points to a null-terminated string specifying the name of a subkey that this function opens or creates. The subkey specified must be a subkey of the key identified by the hKey parameter. This subkey must not begin with the backslash character (‘\’). This parameter cannot be NULL.

Reserved

Reserved; must be zero.

lpClass

Points to a null-terminated string that specifies the class (object type) of this key. This parameter is ignored if the key already exists.

dwOptions

Specifies special options for the key. This parameter can be one of the following values.

Value	Meaning
REG_OPTION_NON_VOLATILE	This key is not volatile; this is the default. The information is stored in a file and is preserved when the system is restarted. The RegSaveKey function saves keys that are not volatile.
REG_OPTION_VOLATILE	Windows NT: This key is volatile; the information is stored in memory and is not preserved when the system is restarted. The RegSaveKey function does not save volatile keys. This flag is ignored if the key already exists.  Windows 95: This value is ignored in Windows 95. If REG_OPTION_VOLATILE is specified, the RegCreateKeyEx function creates a nonvolatile key and returns ERROR_SUCCESS.
REG_OPTION_BACKUP_RESTORE	Windows NT: If this flag is set, the function ignores the samDesired parameter and attempts to open the key with the access required to backup or restore the key. If the calling thread has the SE_BACKUP_NAME privilege enabled, the key is opened with ACCESS_SYSTEM_SECURITY and KEY_READ access. If the calling thread has the SE_RESTORE_NAME privilege enabled, the key is opened with ACCESS_SYSTEM_SECURITY and KEY_WRITE access. If both privileges are enabled, the key has the combined accesses for both privileges.  Windows 95: This flag is ignored. Windows 95 does not support security in its registry.
samDesired

Specifies an access mask that specifies the desired security access for the new key. This parameter can be a combination of the following values:

Value	Meaning
KEY_ALL_ACCESS	Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, KEY_CREATE_SUB_KEY, KEY_CREATE_LINK, and KEY_SET_VALUE access.
KEY_CREATE_LINK	Permission to create a symbolic link.
KEY_CREATE_SUB_KEY	Permission to create subkeys.
KEY_ENUMERATE_SUB_KEYS	Permission to enumerate subkeys.
KEY_EXECUTE	Permission for read access.
KEY_NOTIFY	Permission for change notification.
KEY_QUERY_VALUE	Permission to query subkey data.
KEY_READ	Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY access.
KEY_SET_VALUE	Permission to set subkey data.
KEY_WRITE	Combination of KEY_SET_VALUE and KEY_CREATE_SUB_KEY access.
lpSecurityAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new key. If lpSecurityAttributes is NULL, the key gets a default security descriptor.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

phkResult

Points to a variable that receives the handle of the opened or created key.

lpdwDisposition

Points to a variable that receives one of the following disposition values:

Value	Meaning
REG_CREATED_NEW_KEY	The key did not exist and was created.
REG_OPENED_EXISTING_KEY	The key existed and was simply opened without being changed.
Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

The key that the RegCreateKeyEx function creates has no values. An application can use the RegSetValue or RegSetValueEx function to set key values.

The key identified by the hKey parameter must have been opened with KEY_CREATE_SUB_KEY access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

An application cannot create a key under HKEY_USERS or HKEY_LOCAL_MACHINE.

An application can use RegCreateKeyEx to temporarily lock a portion of the registry. When the locking process creates a new key, it receives the disposition value REG_CREATED_NEW_KEY, indicating that it “owns” the lock. Another process attempting to create the same key receives the disposition value REG_OPENED_EXISTING_KEY, indicating that another process already owns the lock.

See Also

RegCloseKey, RegCreateKey, RegDeleteKey, RegOpenKey, RegOpenKeyEx, RegSaveKey, SECURITY_ATTRIBUTES


RegDeleteKey

Windows 95: The RegDeleteKey function deletes a key and all its descendents.

Windows NT: The RegDeleteKey function deletes the specified key. This function cannot delete a key that has subkeys.

LONG RegDeleteKey(

HKEY hKey,	// handle of open key
LPCTSTR lpSubKey	// address of name of subkey to delete
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

The key specified by the lpSubKey parameter must be a subkey of the key identified by hKey.

lpSubKey

Points to a null-terminated string specifying the name of the key to delete. This parameter cannot be NULL, and the specified key must not have subkeys.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

If the function succeeds, RegDeleteKey removes the specified key from the registry. The entire key, including all of its values, is removed.

To open the key, use the RegCreateKeyEx or RegOpenKeyEx function. Do not use the RegCreateKey or RegOpenKey functions.

See Also

RegCloseKey, RegCreateKeyEx, RegOpenKeyEx


RegDeleteValue

The RegDeleteValue function removes a named value from the specified registry key.

LONG RegDeleteValue(

HKEY hKey,	// handle of key
LPCTSTR lpValueName	// address of value name
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpValueName

Points to a null-terminated string that names the value to remove. If this parameter is NULL or points to an empty string, the value set by the RegSetValue function is removed.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

The key identified by the hKey parameter must have been opened with KEY_SET_VALUE access (KEY_WRITE access includes KEY_SET_VALUE access).

See Also

RegSetValue, RegSetValueEx


RegEnumKey

The RegEnumKey function enumerates subkeys of the specified open registry key. The function retrieves the name of one subkey each time it is called. This function is provided for compatibility with Windows version 3.1. Win32-based applications should use the RegEnumKeyEx function.

LONG RegEnumKey(

HKEY hKey,	// handle of key to query
DWORD dwIndex,	// index of subkey to query
LPTSTR lpName,	// address of buffer for subkey name
DWORD cbName	// size of subkey buffer
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

The keys returned are relative to the key identified by hKey.

dwIndex

Specifies the index of the subkey to retrieve. This value should be zero for the first call to the RegEnumKey function and then incremented for subsequent calls.

Because subkeys are not ordered, any new subkey will have an arbitrary index. This means that the function may return subkeys in any order.

lpName

Points to a buffer that receives the name of the subkey, including the terminating null character. This function copies only the name of the subkey, not the full key hierarchy, to the buffer.

cbName

Specifies the size, in characters, of the buffer pointed to by the lpName parameter, in characters. To determine the required buffer size, use the RegQueryInfoKey function to determine the size of the largest subkey for the key identified by the hKey parameter. The maximum required buffer size is (MAX_PATH + 1) characters.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

To enumerate subkeys, an application should initially call the RegEnumKey function with the dwIndex parameter set to zero. The application should then increment the dwIndex parameter and call the RegEnumKey function until there are no more subkeys (until the function returns ERROR_NO_MORE_ITEMS).

The application can also set dwIndex to the index of the last key on the first call to the function and decrement the index until the subkey with index 0 is enumerated. To retrieve the index of the last subkey, use the RegQueryInfoKey.

While an application is using the RegEnumKey function, it should not make calls to any registration functions that might change the key being queried.

The key identitied by the hKey parameter must have been opened with KEY_ENUMERATE_SUB_KEYS access (KEY_READ access includes KEY_ENUMERATE_SUB_KEYS access). To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

See Also

RegCloseKey, RegCreateKeyEx, RegDeleteKey, RegEnumKeyEx, RegOpenKeyEx, RegQueryInfoKey, RegQueryValue


RegEnumKeyEx

The RegEnumKeyEx function enumerates subkeys of the specified open registry key. The function retrieves information about one subkey each time it is called. Unlike the RegEnumKey function, RegEnumKeyEx retrieves the class name of the subkey and the time it was last modified.

LONG RegEnumKeyEx(

HKEY hKey,	// handle of key to enumerate
DWORD dwIndex,	// index of subkey to enumerate
LPTSTR lpName,	// address of buffer for subkey name
LPDWORD lpcbName,	// address for size of subkey buffer
LPDWORD lpReserved,	// reserved
LPTSTR lpClass,	// address of buffer for class string
LPDWORD lpcbClass,	// address for size of class buffer
PFILETIME lpftLastWriteTime	// address for time key last written to
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

The enumerated keys are subkeys of the key identified by hKey.

dwIndex

Specifies the index of the subkey to retrieve. This parameter should be zero for the first call to the RegEnumKeyEx function and then incremented for subsequent calls.

Because subkeys are not ordered, any new subkey will have an arbitrary index. This means that the function may return subkeys in any order.

lpName

Points to a buffer that receives the name of the subkey, including the terminating null character. The function copies only the name of the subkey, not the full key hierarchy, to the buffer.

lpcbName

Points to a variable that specifies the size, in characters, of the buffer specified by the lpName parameter. This size should include the terminating null character. When the function returns, the variable pointed to by lpcbName contains the number of characters stored in the buffer. The count returned does not include the terminating null character.

lpReserved

Reserved; must be NULL.

lpClass

Points to a buffer that contains the class of the enumerated subkey when the function returns. This parameter can be NULL if the class is not required.

lpcbClass

Points to a variable that specifies the size, in characters, of the buffer specified by the lpClass parameter. The size should include the terminating null character. When the function returns, lpcbClass contains the number of characters stored in the buffer. The count returned does not include the terminating null character. This parameter can be NULL only if lpClass is NULL.

lpftLastWriteTime

Points to a variable that receives the time the enumerated subkey was last written to.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

To enumerate subkeys, an application should initially call the RegEnumKeyEx function with the dwIndex parameter set to zero. The application should then increment the dwIndex parameter and call RegEnumKeyEx until there are no more subkeys (until the function returns ERROR_NO_MORE_ITEMS).

The application can also set dwIndex to the index of the last subkey on the first call to the function and decrement the index until the subkey with the index 0 is enumerated. To retrieve the index of the last subkey, use the RegQueryInfoKey function.

While an application is using the RegEnumKeyEx function, it should not make calls to any registration functions that might change the key being enumerated.

The key identified by hKey must have been opened with KEY_ENUMERATE_SUB_KEYS access (KEY_READ includes KEY_ENUMERATE_SUB_KEYS). Use the RegCreateKeyEx or RegOpenKeyEx function to open the key.

See Also

RegCreateKeyEx, RegDeleteKey, RegEnumKey, RegOpenKeyEx, RegQueryInfoKey


RegEnumValue

The RegEnumValue function enumerates the values for the specified open registry key. The function copies one indexed value name and data block for the key each time it is called.

LONG RegEnumValue(

HKEY hKey,	// handle of key to query
DWORD dwIndex,	// index of value to query
LPTSTR lpValueName,	// address of buffer for value string
LPDWORD lpcbValueName,	// address for size of value buffer
LPDWORD lpReserved,	// reserved
LPDWORD lpType,	// address of buffer for type code
LPBYTE lpData,	// address of buffer for value data
LPDWORD lpcbData	// address for size of data buffer
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

The enumerated values are associated with the key identified by hKey.

dwIndex

Specifies the index of the value to retrieve. This parameter should be zero for the first call to the RegEnumValue function and then be incremented for subsequent calls.

Because values are not ordered, any new value will have an arbitrary index. This means that the function may return values in any order.

lpValueName

Points to a buffer that receives the name of the value, including the terminating null character.

lpcbValueName

Points to a variable that specifies the size, in characters, of the buffer pointed to by the lpValueName parameter. This size should include the terminating null character. When the function returns, the variable pointed to by lpcbValueName contains the number of characters stored in the buffer. The count returned does not include the terminating null character.

lpReserved

Reserved; must be NULL.

lpType

Points to a variable that receives the type code for the value entry. The type code can be one of the following values:

Value	Meaning
REG_BINARY	Binary data in any form.
REG_DWORD	A 32-bit number.
REG_DWORD_LITTLE_ENDIAN	A 32-bit number in little-endian format (same as REG_DWORD). In little-endian format, the most significant byte of a word is the high-order byte. This is the most common format for computers running Windows NT and Windows 95.
REG_DWORD_BIG_ENDIAN	A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low-order byte.
REG_EXPAND_SZ	A null-terminated string that contains unexpanded references to environment variables (for example, “%PATH%”). It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
REG_LINK	A Unicode symbolic link.
REG_MULTI_SZ	An array of null-terminated strings, terminated by two null characters.
REG_NONE	No defined value type.
REG_RESOURCE_LIST	A device-driver resource list.
REG_SZ	A null-terminated string. It will be a Unicode or ANSI string, depending on whether you use the Unicode or ANSI functions.
The lpType parameter can be NULL if the type code is not required.

lpData

Points to a buffer that receives the data for the value entry. This parameter can be NULL if the data is not required.

lpcbData

Points to a variable that specifies the size, in bytes, of the buffer pointed to by the lpData parameter. When the function returns, the variable pointed to by the lpcbData parameter contains the number of bytes stored in the buffer. This parameter can be NULL, only if lpData is NULL.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

To enumerate values, an application should initially call the RegEnumValue function with the dwIndex parameter set to zero. The application should then increment dwIndex and call the RegEnumValue function until there are no more values (until the function returns ERROR_NO_MORE_ITEMS).

The application can also set dwIndex to the index of the last value on the first call to the function and decrement the index until the value with index 0 is enumerated. To retrieve the index of the last value, use the RegQueryInfoKey function.

While using RegEnumValue, an application should not call any registration functions that might change the key being queried.

The key identified by the hKey parameter must have been opened with KEY_QUERY_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

To determine the maximum size of the name and data buffers, use the RegQueryInfoKey function.

See Also

RegCreateKeyEx, RegEnumKey, RegEnumKeyEx, RegOpenKeyEx, RegQueryInfoKey


RegFlushKey

The RegFlushKey function writes all the attributes of the specified open key into the registry.

LONG RegFlushKey(

HKEY hKey	// handle of key to write
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

It is not necessary to call RegFlushKey to change a key. Registry changes are flushed to disk by the registry using its lazy flusher. Registry changes are also flushed to disk at system shutdown.

Unlike RegCloseKey, the RegFlushKey function returns only when all the data has been written to the registry.

The RegFlushKey function may also write out parts of or all of the other keys. Calling this function excessively can have a negative effect on an application’s performance.

An application should only call RegFlushKey if it requires absolute certainty that registry changes are on disk. In general, RegFlushKey rarely, if ever, need be used.

See Also

RegCloseKey, RegDeleteKey


RegGetKeySecurity

The RegGetKeySecurity function retrieves a copy of the security descriptor protecting the specified open registry key.

LONG RegGetKeySecurity(

HKEY hKey,	// open handle of key to set
SECURITY_INFORMATION SecurityInformation,	// descriptor contents
PSECURITY_DESCRIPTOR pSecurityDescriptor,	// address of descriptor for key
LPDWORD lpcbSecurityDescriptor	// address of size of buffer and descriptor
);
Parameters

hKey

Identifies an open key for which to retrieve the security descriptor.

SecurityInformation

Specifies a SECURITY_INFORMATION structure that indicates the requested security information.

pSecurityDescriptor

Points to a buffer that receives a copy of the requested security descriptor.

lpcbSecurityDescriptor

Points to a variable that specifies the size, in bytes, of the buffer pointed to by the pSecurityDescriptor parameter. When the function returns, the variable contains the number of bytes written to the buffer.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

If the buffer specified by the pSecurityDescriptor parameter is too small, the function returns ERROR_INSUFFICIENT_BUFFER and the lpcbSecurityDescriptor parameter contains the number of bytes required for the requested security descriptor.

To read the security descriptor for the specified key, the calling process must have been granted READ_CONTROL access when the key was opened, or it must be the owner of the key. (READ_CONTROL access is granted by the KEY_READ, KEY_WRITE, KEY_EXECUTE, and KEY_ALL_ACCESS access rights.) In addition, the caller must have the SE_SECURITY_NAME privilege to read the system access-control list (SACL).

For more information about security, see Security.

See Also

RegDeleteKey, RegOpenKeyEx, RegSetKeySecurity, SECURITY_INFORMATION


RegisterClass

The RegisterClass function registers a window class for subsequent use in calls to the CreateWindow or CreateWindowEx function.

The RegisterClass function has been superseded by the RegisterClassEx function. You can still use RegisterClass, however, if you do not need to set the class small icon.

ATOM RegisterClass(

CONST WNDCLASS *lpWndClass	// address of structure with class data
);
Parameters

lpWndClass

Points to a WNDCLASS structure. You must fill the structure with the appropriate class attributes before passing it to the function.

Return Values

If the function succeeds, the return value is an atom that uniquely identifies the class being registered.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

All window classes that an application registers are unregistered when it terminates.

Windows 95: RegisterClass fails if the cbWndExtra or cbClsExtra member of the WNDCLASS structure contains more than 40 bytes.

See Also

CreateWindow, CreateWindowEx, GetClassInfo, GetClassName, RegisterClassEx, UnregisterClass, WindowProc, WNDCLASS


RegisterClassEx [Now Supported on Windows NT]
RegisterClassEx

[Now Supported on Windows NT]

The RegisterClassEx function registers a window class for subsequent use in calls to the CreateWindow or CreateWindowEx function. The RegisterClass function does not allow you to set the small icon.

ATOM RegisterClassEx(

CONST WNDCLASSEX *lpwcx	// address of structure with class data
);
Parameters

lpwcx

Points to a WNDCLASSEX structure. You must fill the structure with the appropriate class attributes before passing it to the function.

Return Values

If the function succeeds, the return value is an atom that uniquely identifies the class being registered.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

All window classes that an application registers are unregistered when it terminates.

Windows 95: RegisterClassEx fails if the cbWndExtra or cbClsExtra member of the WNDCLASSEX structure contains more than 40 bytes.

See Also

CreateWindow, CreateWindowEx, GetClassInfoEx, GetClassName, RegisterClass, UnregisterClass, WindowProc,WNDCLASSEX


RegisterClipboardFormat

The RegisterClipboardFormat function registers a new clipboard format. This format can then be used as a valid clipboard format.

UINT RegisterClipboardFormat(

LPCTSTR lpszFormat	// address of name string
);
Parameters

lpszFormat

Points to a null-terminated string that names the new format.

Return Values

If the function succeeds, the return value identifies the registered clipboard format.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If a registered format with the specified name already exists, a new format is not registered and the return value identifies the existing format. This enables more than one application to copy and paste data using the same registered clipboard format. Note that the format name comparison is case-insensitive.

Registered clipboard formats are identified by values in the range 0xC000 through 0xFFFF.

See Also

CountClipboardFormats, EnumClipboardFormats, GetClipboardFormatName


RegisterDialogClasses

The RegisterDialogClasses function registers any nonstandard window classes required by a screen saver’s configuration dialog box.

BOOL RegisterDialogClasses(

HANDLE hInst	// handle of application instance
);
Parameters

hInst

Identifies an instance of the module registering the window classes.

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.

Remarks

The RegisterDialogClasses function should not be exported. It is called by routines defined in the SCRNSAVE.LIB file.

If a screen saver does not register any special window classes for the configuration dialog box, the RegisterDialogClasses function must return TRUE.

See Also

ScreenSaverConfigureDialog


RegisterEventSource

The RegisterEventSource function returns a handle that can be used with the ReportEvent function to log an event.

Any source name can be used; it will be carried in the event log record so that Event Viewer can use it for filtering.

HANDLE RegisterEventSource(

LPCTSTR lpUNCServerName,	// server name for source
LPCTSTR lpSourceName	// source name for registered handle
);
Parameters

lpUNCServerName

Points to a null-terminated string that specifies the Universal Naming Convention (UNC) name of the server on which this operation is to be performed. If this parameter is NULL, the operation is performed on the local computer.

lpSourceName

Points to a null-terminated string that specifies the name of the source referenced by the returned handle. The source name must be a subkey of a logfile entry under the EventLog key in the registry. For example, the source name WinApp would be valid if the registry had the following form:

HKEY_LOCAL_MACHINE

  System

    CurrentControlSet

      Services

        EventLog

          Application

            WinApp

          Security

          System

If the source name cannot be found, the event logging service uses the Application logfile with no message files for the event identifier or category.

Return Values

If the function succeeds, the return value is a handle that can be used with the ReportEvent function.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

DeregisterEventSource, ReportEvent


RegisterHotKey

The RegisterHotKey function defines a hot key for the current thread.

BOOL RegisterHotKey(

HWND hWnd,	// window to receive hot-key notification
int id,	// identifier of hot key
UINT fsModifiers,	// key-modifier flags
UINT vk	// virtual-key code
);
Parameters

hWnd

Identifies the window that will receive WM_HOTKEY messages generated by the hot key. If this parameter is NULL, WM_HOTKEY messages are posted to the message queue of the calling thread and must be processed in the message loop.

id

Specifies the identifier of the hot key. No other hot key in the calling thread should have the same identifier. An application must specify a value in the range 0x0000 through 0xBFFF. A shared dynamic-link library (DLL) must specify a value in the range 0xC000 through 0xFFFF (the range returned by the GlobalAddAtom function). To avoid conflicts with hot-key identifiers defined by other shared DLLs, a DLL should use the GlobalAddAtom function to obtain the hot-key identifier.

fsModifiers

Specifies keys that must be pressed in combination with the key specified by the nVirtKey parameter in order to generate the WM_HOTKEY message. The fsModifiers parameter can be a combination of the following values:

Value	Meaning
MOD_ALT	Either ALT key must be held down.
MOD_CONTROL	Either CTRL key must be held down.
MOD_SHIFT	Either SHIFT key must be held down.
vk

Specifies the virtual-key code of the hot key.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

When a key is pressed, the system looks for a match against all thread hot keys. Upon finding a match, the system posts the WM_HOTKEY message to the message queue of the thread that registered the hot key. This message is posted to the beginning of the queue so it is removed by the next iteration of the message loop.

This function cannot associate a hot key with a window created by another thread.

RegisterHotKey fails if the keystrokes specified for the hot key have already been registered by another hot key.

If the window identified by the hWnd parameter already registered a hot key with the same identifier as that specified by the id parameter, the new values for the fsModifiers and vk parameters replace the previously specified values for these parameters.

See Also

GlobalAddAtom, UnregisterHotKey, WM_HOTKEY


RegisterServiceCtrlHandler

The RegisterServiceCtrlHandler function registers a function to handle service control requests for a service.

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandler(

LPCTSTR lpServiceName,	// address of name of service
LPHANDLER_FUNCTION lpHandlerProc	// address of handler function
);
Parameters

lpServiceName

Points to a null-terminated string that names the service run by the calling thread. This is the service name that was specified in the CreateService function when the service was created.

lpHandlerProc

Points to the Handler function to be registered.

Return Values

If the function succeeds, the return value is a service status handle.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_INVALID_NAME	The specified service name is invalid.
ERROR_SERVICE_DOES_NOT_EXIST	The specified service does not exist.
Remarks

The ServiceMain function of a new service should immediately call the RegisterServiceCtrlHandler function to register a control handling function with the control dispatcher. This enables the control dispatcher to invoke the specified function when it receives control requests for this service. The threads of the calling process can use the service status handle returned by this function to identify the service in subsequent calls to the SetServiceStatus function.

This function must be called before the first SetServiceStatus call because it returns a service status handle for the caller to use so that no other service can inadvertently set this service’s status, which is maintained by the service control manager. It also needs to be called before the first SetServiceStatus so that a control handler is in place to field control requests by the time the service specifies the controls it accepts through the SetServiceStatus function.

When the control handler function is invoked with a control request, it must call SetServiceStatus to notify the service control manager of its latest status, regardless of whether the status of the service has changed.

The service status handle does not have to be closed.

See Also

CreateService, Handler, ServiceMain, SetServiceStatus


RegisterWindowMessage

The RegisterWindowMessage function defines a new window message that is guaranteed to be unique throughout the system. The returned message value can be used when calling the SendMessage or PostMessage function.

UINT RegisterWindowMessage(

LPCTSTR lpString	// address of message string
);
Parameters

lpString

Points to a null-terminated string that specifies the message to be registered.

Return Values

If the message is successfully registered, the return value is a message identifier in the range 0xC000 through 0xFFFF.

If the function fails, the return value is zero.

Remarks

The RegisterWindowMessage function is typically used to register messages for communicating between two cooperating applications.

If two different applications register the same message string, the applications return the same message value. The message remains registered until the Windows session ends.

Only use RegisterWindowMessage when more than one application must process the same message. For sending private messages within a window class, an application can use any integer in the range WM_USER through 0x7FFF. (Messages in this range are private to a window class, not to an application. For example, predefined control classes such as BUTTON, EDIT, LISTBOX, and COMBOBOX may use values in this range.)

See Also

PostAppMessage, PostMessage, SendMessage


RegLoadKey

The RegLoadKey function creates a subkey under HKEY_USER or HKEY_LOCAL_MACHINE and stores registration information from a specified file into that subkey. This registration information is in the form of a hive. A hive is a discrete body of keys, subkeys, and values that is rooted at the top of the registry hierarchy. A hive is backed by a single file and .LOG file.

LONG RegLoadKey(

HKEY hKey,	// handle of open key
LPCTSTR lpSubKey,	// address of name of subkey
LPCTSTR lpFile	// address of filename for registry information
);
Parameters

hKey

Specifies the key where the subkey will be created. This can be a predefined reserved handle value, or a handle returned by a call to RegConnectRegistry. The predefined reserved handle values are:

HKEY_LOCAL_MACHINE
HKEY_USERS

This function always loads information at the top of the registry hierarchy. The HKEY_CLASSES_ROOT and HKEY_CURRENT_USER handle values cannot be specified for this parameter, because they represent subsets of the HKEY_LOCAL_MACHINE and HKEY_USERS handle values, respectively.

lpSubKey

Points to a null-terminated string that specifies the name of the key to be created under hKey. This subkey is where the registration information from the file will be loaded.

lpFile

Points to a null-terminated string containing the name of a file that has registration information. This file must have been created with the RegSaveKey function. Under the file allocation table (FAT) file system, the filename may not have an extension.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

If hKey is a handle returned by RegConnectRegistry, then the path specified in lpFile is relative to the remote computer.

Windows NT: The calling process must have the SE_RESTORE_NAME privilege. For more information about privileges, see Privileges.

Windows 95: Security privileges are not supported or required.

See Also

RegConnectRegistry, RegDeleteKey, RegReplaceKey, RegRestoreKey, RegSaveKey, RegUnloadKey


RegNotifyChangeKeyValue

The RegNotifyChangeKeyValue function notifies the caller about changes to the attributes or contents of a specified registry key. Note that the function does not notify the caller if the specified key is deleted.

LONG RegNotifyChangeKeyValue(

HKEY hKey,	// handle of key to watch
BOOL bWatchSubtree,	// flag for subkey notification
DWORD dwNotifyFilter,	// changes to be reported
HANDLE hEvent,	// handle of signaled event
BOOL fAsynchronous	// flag for asynchronous reporting
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

bWatchSubtree

Specifies a flag that indicates whether to report changes in the specified key and all of its subkeys or only in the specified key. If this parameter is TRUE, the function reports changes in the key and its subkeys. If the parameter is FALSE, the function reports changes only in the key.

dwNotifyFilter

Specifies a set of flags that control which changes should be reported. This parameter can be a combination of the following values:

Value	Meaning
REG_NOTIFY_CHANGE_NAME	Notify the caller if a subkey is added or deleted.
REG_NOTIFY_CHANGE_ATTRIBUTES	Notify the caller of changes to the attributes of the key, such as the security descriptor information.
REG_NOTIFY_CHANGE_LAST_SET	Notify the caller of changes to a value of the key. This can include adding or deleting a value, or changing an existing value.
REG_NOTIFY_CHANGE_SECURITY	Notify the caller of changes to the security descriptor of the key.
hEvent

Identifies an event. If the fAsynchronous parameter is TRUE, the function returns immediately and changes are reported by signaling this event. If fAsynchronous is FALSE, hEvent is ignored.

fAsynchronous

Specifies a flag that indicates how the function reports changes. If this parameter is TRUE, the function returns immediately and reports changes by signaling the specified event. When this parameter is FALSE, the function does not return until a change has occurred.

If hEvent does not specify a valid event, the fAsynchronous parameter cannot be TRUE.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

If the key identified by the hKey parameter is closed, the event is signaled. This means that an application should not depend on the key being open after returning from a wait operation on the event.

RegNotifyChangeKeyValue does not work with remote handles. If RegNotifyChangeKeyValue is called with an hKey value that is a remote handle, it returns ERROR_INVALID_HANDLE.

See Also

RegDeleteKey, RegEnumKey, RegEnumKeyEx, RegEnumValue, RegQueryInfoKey, RegQueryValue, RegQueryValueEx


RegOpenKey

The RegOpenKey function opens the specified key. This function is provided for compatibility with Windows version 3.1. Win32-based applications should use the RegOpenKeyEx function.

LONG RegOpenKey(

HKEY hKey,	// handle of open key
LPCTSTR lpSubKey,	// address of name of subkey to open
PHKEY phkResult	// address of handle of open key
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

The key opened by the RegOpenKey function is a subkey of the key identified by hKey.

lpSubKey

Points to a null-terminated string containing the name of the key to open. This key must be a subkey of the key identified by the hKey parameter. If this parameter is NULL or a pointer to an empty string, the function returns the same handle that was passed in.

phkResult

Points to a variable that receives the handle of the opened key.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

The RegOpenKey function uses the default security access mask to open a key. If opening the key requires a different mask, the function fails, returning ERROR_ACCESS_DENIED. An application should use the RegOpenKeyEx function to specify an access mask in this situation.

Unlike the RegCreateKey function, RegOpenKey does not create the specified key if the key does not exist in the database.

See Also

RegCloseKey, RegCreateKey, RegCreateKeyEx, RegDeleteKey, RegOpenKeyEx


RegOpenKeyEx

The RegOpenKeyEx function opens the specified key.

LONG RegOpenKeyEx(

HKEY hKey,	// handle of open key
LPCTSTR lpSubKey,	// address of name of subkey to open
DWORD ulOptions,	// reserved
REGSAM samDesired,	// security access mask
PHKEY phkResult	// address of handle of open key
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpSubKey

Points to a null-terminated string containing the name of the subkey to open. If this parameter is NULL or a pointer to an empty string, the function will open a new handle of the key identified by the hKey parameter. In this case, the function will not close the handles previously opened.

ulOptions

Reserved; must be zero.

samDesired

Specifies an access mask that describes the desired security access for the new key. This parameter can be a combination of the following values:

Value	Meaning
KEY_ALL_ACCESS	Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, KEY_CREATE_SUB_KEY, KEY_CREATE_LINK, and KEY_SET_VALUE access.
KEY_CREATE_LINK	Permission to create a symbolic link.
KEY_CREATE_SUB_KEY	Permission to create subkeys.
KEY_ENUMERATE_SUB_KEYS	Permission to enumerate subkeys.
KEY_EXECUTE	Permission for read access.
KEY_NOTIFY	Permission for change notification.
KEY_QUERY_VALUE	Permission to query subkey data.
KEY_READ	Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY access.
KEY_SET_VALUE	Permission to set subkey data.
KEY_WRITE	Combination of KEY_SET_VALUE and KEY_CREATE_SUB_KEY access.
phkResult

Points to a variable that receives the handle of the opened key.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

Unlike the RegCreateKeyEx function, the RegOpenKeyEx function does not create the specified key if the key does not exist in the registry.

See Also

RegCloseKey, RegCreateKeyEx, RegDeleteKey, RegOpenKey


RegQueryInfoKey

The RegQueryInfoKey function retrieves information about a specified registry key.

LONG RegQueryInfoKey (

HKEY hKey,	// handle of key to query
LPTSTR lpClass,	// address of buffer for class string
LPDWORD lpcbClass,	// address of size of class string buffer
LPDWORD lpReserved,	// reserved
LPDWORD lpcSubKeys,	// address of buffer for number of subkeys
LPDWORD lpcbMaxSubKeyLen,	// address of buffer for longest subkey name length
LPDWORD lpcbMaxClassLen,	// address of buffer for longest class string length
LPDWORD lpcValues,	// address of buffer for number of value entries
LPDWORD lpcbMaxValueNameLen,	// address of buffer for longest value name length
LPDWORD lpcbMaxValueLen,	// address of buffer for longest value data length
LPDWORD lpcbSecurityDescriptor,	// address of buffer for security descriptor length
PFILETIME lpftLastWriteTime	// address of buffer for last write time
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpClass

Points to a buffer that receives the key’s class name. This parameter can be NULL.

lpcbClass

Points to a variable that specifies the size, in characters, of the buffer pointed to by the lpClass parameter. This size should include the terminating null character. When the function returns, this variable contains the length of the class string stored in the buffer. The count returned does not include the terminating null character. If the buffer is not big enough, the function returns ERROR_MORE_DATA, and the variable contains the size of the string, in characters, without counting the null character.

If lpClass is NULL, lpcbClass can be NULL.

Windows NT: If the lpClass parameter is a valid address, but the lpcbClass parameter is not (for example, it is NULL), the function returns ERROR_INVALID_PARAMETER.

Windows 95: If the lpClass parameter is a valid address, but the lpcbClass parameter is not (for example, it is NULL), the function returns ERROR_SUCCESS instead of ERROR_INVALID_PARAMETER. To ensure compatibility with other platforms, verify that lpcbClass is valid before calling the function.

lpReserved

Reserved; must be NULL.

lpcSubKeys

Points to a variable that receives the number of subkeys contained by the specified key. This parameter can be NULL.

lpcbMaxSubKeyLen

Points to a variable that receives the length, in characters, of the key’s subkey with the longest name. The count returned does not include the terminating null character. This parameter can be NULL.

lpcbMaxClassLen

Points to a variable that receives the length, in characters, of the longest string specifying a subkey class. The count returned does not include the terminating null character. This parameter can be NULL.

lpcValues

Points to a variable that receives the number of values associated with the key. This parameter can be NULL.

lpcbMaxValueNameLen

Points to a variable that receives the length, in characters, of the key’s longest value name. The count returned does not include the terminating null character. This parameter can be NULL.

lpcbMaxValueLen

Points to a variable that receives the length, in bytes, of the longest data component among the key’s values. This parameter can be NULL.

lpcbSecurityDescriptor

Points to a variable that receives the length, in bytes, of the key’s security descriptor. This parameter can be NULL.

lpftLastWriteTime

Pointer to a FILETIME structure. This parameter can be NULL.

If you are querying the registry on a computer running Windows NT, the function sets the members of the FILETIME structure to indicate the last time that the key or any of its value entries was modified.

If you are querying the registry on a computer running Windows 95, the function sets the members of the FILETIME structure to zero. This is because the Windows 95 operating system does not keep track of registry key last write time information.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

The key identified by the hKey parameter must have been opened with KEY_QUERY_VALUE access (KEY_READ access includes KEY_QUERY_VALUE access).

See Also

FILETIME, RegDeleteKey, RegEnumKey, RegEnumKeyEx, RegEnumValue, RegQueryValue, RegQueryValueEx


RegQueryMultipleValues

The RegQueryMultipleValues function retrieves the type and data for a list of value names associated with an open registry key.

LONG RegQueryMultipleValues(

HKEY hKey,	// handle of key to query
PVALENT val_list,	// address of array of value entry structures
DWORD num_vals,	// size of array of value entry structures
LPTSTR lpValueBuf,	// address of buffer for value information
LPDWORD ldwTotsize	// address of size of value buffer
);
Parameters

hKey

Identifies a currently open key or any of the pre-defined reserved handle values:

HKEY_CLASSES_ROOT
HEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

val_list

Address of an array of VALENT structures that describe one or more value entries. On input, the ve_valuename member of each structure must contain a pointer to the name of a value to retrieve. The function fails if any of the specified values do not exist in the specified key.

If the function succeeds, each element of the array contains the information for the specified value.

num_vals

Specifies the number of elements in the val_list array.

lpValueBuf

Pointer to a buffer. If the function succeeds, the buffer receives the data for each value.

If lpValueBuf is NULL, the function returns success, and ldwTotsize returns the required size, in bytes, of the buffer.

ldwTotsize

Pointer to a value that specifies the size, in bytes, of the buffer pointed to by the lpValueBuf parameter. If the function succeeds, ldwTotsize returns the number of bytes copied to the buffer. If the function fails because the buffer is too small, ldwTotsize receives the required size, in bytes.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes:

Value	Meaning
ERROR_CANTREAD	RegQueryMultipleValues cannot instantiate or access the provider of the dynamic key.
ERROR_MORE_DATA	The buffer pointed to by lpValueBuf was too small. In this case, ldwTotsize returns the required buffer size.
ERROR_TRANSFER_TOO_LONG	The total length of the requested data (size of the val_list array + ldwTotSize) is more than the system limit of one megabyte.
Remarks

The RegQueryMultipleValues function allows an application to query one or more values of a static or dynamic key. If the target key is a static key, the system provides all of the values in an atomic fashion. To prevent excessive serialization, the aggregate data returned by the function can not exceed one megabyte.

If the target key is a dynamic key, its provider must provide all the values in an atomic fashion. This means the provider should fill the results buffer synchronously, providing a consistent view of all the values in the buffer while avoiding excessive serialization. The provider can provide at most one megabyte of total output data during an atomic call to this function.

RegQueryMultipleValues is supported remotely; that is, the hKey parameter passed to the function can refer to a remote computer.

See Also

VALENT


RegQueryValue

The RegQueryValue function retrieves the value associated with the unnamed value for a specified key in the registry. Values in the registry have name, type, and data components. This function retrieves the data for a key’s first value that has a NULL name. This function is provided for compatibility with Windows version 3.1. Win32-based applications should use the RegQueryValueEx function.

LONG RegQueryValue(

HKEY hKey,	// handle of key to query
LPCTSTR lpSubKey,	// address of name of subkey to query
LPTSTR lpValue,	// address of buffer for returned string
PLONG lpcbValue	// address of buffer for size of returned string
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpSubKey

Points to a null-terminated string containing the name of the subkey of the hKey parameter for which a value is to be retrieved. If this parameter is NULL or points to an empty string, the function retrieves the value set by the RegSetValue function for the key identified by hKey.

lpValue

Points to a buffer that receives the value associated with the lpSubKey parameter. The buffer should be big enough to contain the terminating null character. This parameter can be NULL if the data is not required.

If lpValue is NULL, and lpcbValue is not NULL, the function places the size in bytes of the data referenced by the value key, including the terminating null character, into the variable pointed to by lpcbValue. This lets an application determine how to best preallocate a buffer for the value key’s data.

lpcbValue

Points to a variable specifying the size, in bytes, of the buffer pointed to by the lpValue parameter. When the function returns, this variable contains the size of the data copied to lpValue, including the terminating null character.

If the buffer specified by lpValue parameter is not large enough to hold the data, the function returns the value ERROR_MORE_DATA, and stores the required buffer size, in bytes, into the variable pointed to by lpcbValue.

If lpValue is NULL, the function returns ERROR_SUCCESS, and stores the size of the string, in bytes, into the variable pointed to by lpcbValue. This lets an application determine the best way to allocate a buffer for the value key’s data.

In all cases the value returned in lpcbValue always includes the size of the terminating null character in the string.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

The key identified by the hKey parameter must have been opened with KEY_QUERY_VALUE access (KEY_READ access includes KEY_QUERY_VALUE access).

If the ANSI version of this function is used (either by explicitly calling RegQueryValue or by not defining Unicode before including the WINDOWS.H file), this function converts the stored Unicode string to an ANSI string before copying it to the buffer specified by the lpValue parameter.

See Also

RegEnumKey, RegEnumKeyEx, RegEnumValue, RegQueryInfoKey, RegQueryValueEx, RegSetValue, RegSetValueEx


RegQueryValueEx

The RegQueryValueEx function retrieves the type and data for a specified value name associated with an open registry key.

LONG RegQueryValueEx(

HKEY hKey,	// handle of key to query
LPTSTR lpValueName,	// address of name of value to query
LPDWORD lpReserved,	// reserved
LPDWORD lpType,	// address of buffer for value type
LPBYTE lpData,	// address of data buffer
LPDWORD lpcbData	// address of data buffer size
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpValueName

Points to a null-terminated string containing the name of the value to be queried.

lpReserved

Reserved; must be NULL.

lpType

Points to a variable that receives the key’s value type. The value returned through this parameter will be one of the following:

Value	Meaning
REG_BINARY	Binary data in any form.
REG_DWORD	A 32-bit number.
REG_DWORD_LITTLE_ENDIAN	A 32-bit number in little-endian format (same as REG_DWORD). In little-endian format, the most significant byte of a word is the high-order byte. This is the most common format for computers running Windows NT and Windows 95.
REG_DWORD_BIG_ENDIAN	A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low-order byte.
REG_EXPAND_SZ	A null-terminated string that contains unexpanded references to environment variables (for example, “%PATH%”). It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
REG_LINK	A Unicode symbolic link.
REG_MULTI_SZ	An array of null-terminated strings, terminated by two null characters.
REG_NONE	No defined value type.
REG_RESOURCE_LIST	A device-driver resource list.
REG_SZ	A null-terminated string. It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
The lpType parameter can be NULL if the type is not required.

lpData

Points to a buffer that receives the value’s data. This parameter can be NULL if the data is not required.

lpcbData

Points to a variable that specifies the size, in bytes, of the buffer pointed to by the lpData parameter. When the function returns, this variable contains the size of the data copied to lpData.

If the buffer specified by lpData parameter is not large enough to hold the data, the function returns the value ERROR_MORE_DATA, and stores the required buffer size, in bytes, into the variable pointed to by lpcbData.

If lpData is NULL, and lpcbData is non-NULL, the function returns ERROR_SUCCESS, and stores the size of the data, in bytes, in the variable pointed to by lpcbData. This lets an application determine the best way to allocate a buffer for the value key’s data.

If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, then lpData will also include the size of the terminating null character.

The lpcbData parameter can be NULL only if lpData is NULL.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

The key identified by hKey must have been opened with KEY_QUERY_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

This function does not expand the environment-variable names in the value data when the value type is REG_EXPAND_SZ. The ExpandEnvironmentStrings function can be used to expand the environment-variable names.

If the value data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, and the ANSI version of this function is used (either by explicitly calling RegQueryValueEx or by not defining Unicode before including the WINDOWS.H file), this function converts the stored Unicode string to an ANSI string before copying it to the buffer pointed to by lpData.

When calling the RegQueryValueEx function with hKey set to the HKEY_PERFORMANCE_DATA handle and a value string of a specified object, the returned data structure sometimes has unrequested objects. Don’t be surprised; this is normal behavior. When calling the RegQueryValueEx function, you should always expect to walk the returned data structure to look for the requested object.

See Also

ExpandEnvironmentStrings, RegCreateKeyEx, RegEnumKey, RegEnumKeyEx, RegEnumValue, RegOpenKeyEx, RegQueryInfoKey, RegQueryValue


RegReplaceKey

The RegReplaceKey function replaces the file backing a key and all its subkeys with another file, so that when the system is next started, the key and subkeys will have the values stored in the new file.

LONG RegReplaceKey(

HKEY hKey,	// handle of open key
LPCTSTR lpSubKey,	// address of name of subkey
LPCTSTR lpNewFile,	// address of filename for file with new data
LPCTSTR lpOldFile	// address of filename for backup file
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpSubKey

Points to a null-terminated string containing the name of a key whose subkeys and values are replaced by this function. This key must be a subkey of the key identified by the hKey parameter. This parameter can be NULL.

The selected key must be the root of a hive; that is, it must be an immediate descendent of HKEY_LOCAL_MACHINE or HKEY_USERS.

lpNewFile

Points to a null-terminated string containing the name of the file with registration information. This file is typically created by using the RegSaveKey function. Under the file allocation table (FAT) file system, the filename may not have an extension.

lpOldFile

Points to a null-terminated string containing the name of a file that receives a backup copy of the registry information being replaced. If this file is created under the FAT file system, it should not have an extension.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

The file specified by the lpNewFile parameter remains open until the system is restarted.

If hKey is a handle returned by RegConnectRegistry, then the paths specified in lpNewFile and lpOldFile are relative to the remote computer.

Windows NT: The calling process must have the SE_RESTORE_NAME privilege. For more information about privileges, see Privileges.

Windows 95: Security privileges are not supported or required.

See Also

RegConnectRegistry, RegDeleteKey, RegLoadKey, RegRestoreKey


RegRestoreKey

The RegRestoreKey function reads the registry information in a specified file and copies it over the specified key. This registry information may be in the form of a key and multiple levels of subkeys.

LONG RegRestoreKey(

HKEY hKey,	// handle of key where restore begins
LPCTSTR lpFile,	// address of filename containing saved tree
DWORD dwFlags	// optional flags
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

Any information contained in this key and its descendent keys is overwritten by the information in the file pointed to by the lpFile parameter.

lpFile

Points to a null-terminated string containing the name of the file with registry information. This file is typically created by using the RegSaveKey function. Under the file allocation table (FAT) file system, the filename may not have an extension.

dwFlags

Specifies a flag indicating whether the key is volatile. (A volatile key is valid only until the next time the system is started.) This parameter is optional; if no value is specified, the key is not volatile.

This parameter can be the REG_WHOLE_HIVE_VOLATILE flag set. Instead of restoring the given key, this flag causes a new, volatile (memory only) set of registry information to be created. (A hive is a large set of registry information, typically containing all of the pertinent information for part of the system. For example, HKEY_LOCAL_MACHINE\Hardware is a volatile hive.)

If REG_WHOLE_HIVE_VOLATILE is specified, the key identified by the hKey parameter must be either the HKEY_USERS or HKEY_LOCAL_MACHINE value.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

If any subkeys of the hKey parameter are open, RegRestoreKey fails. The function also fails if the calling process does not have the SE_RESTORE_NAME privilege. For more information about privileges, see Privileges.

This function replaces the keys and values below the specified key with the keys and values that are subsidiary to the top-level key in the file, no matter what the name of the top-level key in the file might be. For example, hKey might identify a key A with subkeys B and C, while the lpFile parameter specifies a file containing key X with subkeys Y and Z. After a call to RegRestoreKey, the registry would contain key A with subkeys Y and Z. The value entries of A would be replaced by the value entries of X.

The new information in the file specified by lpFile overwrites the contents of the key specified by the hKey parameter, except for the key name.

If hKey represents a key in a remote computer, the path described by lpFile is relative to the remote computer.

See Also

RegDeleteKey, RegLoadKey, RegReplaceKey, RegSaveKey


RegSaveKey

The RegSaveKey function saves the specified key and all of its subkeys and values to a new file.

LONG RegSaveKey(

HKEY hKey,	// handle of key where save begins
LPCTSTR lpFile,	// address of filename to save to
LPSECURITY_ATTRIBUTES lpSecurityAttributes	// address of security structure
);
Parameters

hKey

Specifies a handle of the key where the save operation is to begin, or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpFile

Points to a null-terminated string containing the name of the file in which the specified key and subkeys are saved. This file cannot already exist. If this filename includes an extension, it cannot be used on file allocation table (FAT) file systems by the RegLoadKey, RegReplaceKey, or RegRestoreKey function.

lpSecurityAttributes

Windows NT: Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new file. If lpSecurityAttributes is NULL, the file gets a default security descriptor.

Windows 95: This parameter is ignored.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

If hKey represents a key on a remote computer, the path described by lpFile is relative to the remote computer.

The RegSaveKey function saves only nonvolatile keys. It does not save volatile keys. A key is made volatile or nonvolatile at its creation; see RegCreateKeyEx.

Windows NT: The calling process must have the SE_BACKUP_NAME privilege. For more information about privileges, see Privileges.

Windows 95: Security privileges are not supported or required.

See Also

RegCreateKeyEx, RegDeleteKey, RegLoadKey, RegReplaceKey, RegRestoreKey, SECURITY_ATTRIBUTES


RegSetKeySecurity

The RegSetKeySecurity function sets the security of an open registry key.

LONG RegSetKeySecurity(

HKEY hKey,	// open handle of key to set
SECURITY_INFORMATION SecurityInformation,	// descriptor contents
PSECURITY_DESCRIPTOR pSecurityDescriptor	// address of descriptor for key
);
Parameters

hKey

Identifies an open key for which the security descriptor is set.

SecurityInformation

Specifies a SECURITY_INFORMATION structure that indicates the contents of the supplied security descriptor.

Because subkeys are not ordered, any new subkey will have an arbitrary index. This means the function may return subkeys in any order.

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure that specifies the security attributes to set for the specified key.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

This function succeeds only if the following conditions are met:

•	If the key’s owner or group is being set, the caller must have WRITE_OWNER permission or have the SE_TAKE_OWNERSHIP_NAME privilege.

•	If the key’s discretionary access-control list (DACL) is being set, the caller must have WRITE_DAC permission or be the object’s owner.

•	If the key’s system access-control list (SACL) is being set, the caller must have the SE_SECURITY_NAME privilege.

If hKey is one of the predefined keys, the predefined key should be closed with RegCloseKey. That ensures that the new security information is in effect the next time the predefined key is referenced.

See Also

RegCloseKey, RegDeleteKey, RegGetKeySecurity, SECURITY_INFORMATION


RegSetValue

The RegSetValue function associates a value with a specified key. This value must be a text string and cannot have a name. This function is provided for compatibility with Windows version 3.1. Win32-based applications should use the RegSetValueEx function, which allows an application to set any number of named values of any data type.

LONG RegSetValue(

HKEY hKey,	// handle of key to set value for
LPCTSTR lpSubKey,	// address of subkey name
DWORD dwType,	// type of value
LPCTSTR lpData,	// address of value data
DWORD cbData	// size of value data
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpSubKey

Points to a null-terminated string containing the name of the subkey with which a value is associated. This parameter can be null or a pointer to an empty string. In this case, the value will be added to the key identified by the hKey parameter.

dwType

Specifies the type of information to be stored. This parameter must be the REG_SZ type. To store other data types, use the RegSetValueEx function.

lpData

Points to a null-terminated string containing the value to set for the specified key.

cbData

Specifies the length, in bytes, of the string pointed to by the lpData parameter, not including the terminating null character.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

If the key specified by the lpSubKey parameter does not exist, the RegSetValue function creates it.

Value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored as files with the filenames stored in the registry. This helps the registry perform efficiently.

The key identified by the hKey parameter must have been opened with KEY_SET_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function. If the ANSI version of this function is used (either by explicitly calling RegSetValue or by not defining Unicode before including the WINDOWS.H file), the lpData parameter must be an ANSI character string. The string is converted to Unicode before it is stored in the registry.

See Also

RegCreateKeyEx, RegFlushKey, RegOpenKeyEx, RegQueryValue, RegQueryValueEx, RegSetValueEx


RegSetValueEx

The RegSetValueEx function stores data in the value field of an open registry key. It can also set additional value and type information for the specified key.

LONG RegSetValueEx(

HKEY hKey,	// handle of key to set value for
LPCTSTR lpValueName,	// address of value to set
DWORD Reserved,	// reserved
DWORD dwType,	// flag for value type
CONST BYTE *lpData,	// address of value data
DWORD cbData	// size of value data
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpValueName

Points to a string containing the name of the value to set. If a value with this name is not already present in the key, the function adds it to the key.

If this parameter is NULL or points to an empty string and the dwType parameter is the REG_SZ type, this function sets the same value the RegSetValue function would set.

Reserved

Reserved; must be zero.

dwType

Specifies the type of information to be stored as the value’s data. This parameter can be one of the following values:

Value	Meaning
REG_BINARY	Binary data in any form.
REG_DWORD	A 32-bit number.
REG_DWORD_LITTLE_ENDIAN	A 32-bit number in little-endian format (same as REG_DWORD). In little-endian format, the most significant byte of a word is the high-order byte. This is the most common format for computers running Windows NT and Windows 95.
REG_DWORD_BIG_ENDIAN	A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low-order byte.
REG_EXPAND_SZ	A null-terminated string that contains unexpanded references to environment variables (for example, “%PATH%”). It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
REG_LINK	A Unicode symbolic link.
REG_MULTI_SZ	An array of null-terminated strings, terminated by two null characters.
REG_NONE	No defined value type.
REG_RESOURCE_LIST	A device-driver resource list.
REG_SZ	A null-terminated string. It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
lpData

Points to a buffer containing the data to be stored with the specified value name.

cbData

Specifies the size, in bytes, of the information pointed to by the lpData parameter. If the data is of type REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ, cbData must include the size of the terminating null character.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

Value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored as files with the filenames stored in the registry. This helps the registry perform efficiently. Application elements such as icons, bitmaps, and executable files should be stored as files and not be placed in the registry.

The key identified by the hKey parameter must have been opened with KEY_SET_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

If dwType is the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type and the ANSI version of this function is used (either by explicitly calling RegSetValueEx or by not defining Unicode before including the WINDOWS.H file), the data pointed to by the lpData parameter must be an ANSI character string. The string is converted to Unicode before it is stored in the registry.

See Also

RegCreateKeyEx, RegFlushKey, RegOpenKeyEx, RegQueryValue, RegQueryValueEx, RegSetValue


RegUnLoadKey

The RegUnLoadKey function unloads the specified key and subkeys from the registry.

LONG RegUnLoadKey(

HKEY hKey,	// handle of open key
LPCTSTR lpSubKey	// address of name of subkey to unload
);
Parameters

hKey

Specifies the key to be unloaded. This can be a predefined reserved handle value, or a handle returned by a call to RegConnectRegistry. The predefined reserved handle values are:

HKEY_LOCAL_MACHINE
HKEY_USERS

lpSubKey

Points to a null-terminated string containing the name of the subkey to be unloaded. The key referred to by the lpSubKey parameter must have been created by using the RegLoadKey function.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

This function removes a hive from the registry but does not modify the file containing the registry information. A hive is a discrete body of keys, subkeys, and values that is rooted at the top of the registry hierarchy.

Windows NT: The calling process must have the SE_RESTORE_NAME privilege. For more information about privileges, see Privileges.

Windows 95: Security privileges are not supported or required.

See Also

RegConnectRegistry, RegDeleteKey, RegLoadKey, RegRestoreKey


ReleaseCapture

The ReleaseCapture function releases the mouse capture from a window in the current thread and restores normal mouse input processing. A window that has captured the mouse receives all mouse input, regardless of the position of the cursor, except when a mouse button is clicked while the cursor hot spot is in the window of another thread.

BOOL ReleaseCapture(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

An application calls this function after calling the SetCapture function.

Windows 95: Calling this function causes the window that is losing the mouse capture to receive a WM_CAPTURECHANGED message.

See Also

GetCapture, SetCapture, WM_CAPTURECHANGED


ReleaseDC

The ReleaseDC function releases a device context (DC), freeing it for use by other applications. The effect of the ReleaseDC function depends on the type of device context. It frees only common and window device contexts. It has no effect on class or private device contexts.

int ReleaseDC(

HWND hWnd,	// handle of window
HDC hDC	// handle of device context
);
Parameters

hWnd

Identifies the window whose device context is to be released.

hDC

Identifies the device context to be released.

Return Values

The return value specifies whether the device context is released. If the device context is released, the return value is 1.

If the device context is not released, the return value is zero.

Remarks

The application must call the ReleaseDC function for each call to the GetWindowDC function and for each call to the GetDC function that retrieves a common device context.

An application cannot use the ReleaseDC function to release a device context that was created by calling the CreateDC function; instead, it must use the DeleteDC function.

See Also

CreateDC, DeleteDC, GetDC, GetWindowDC


ReleaseMutex

The ReleaseMutex function releases ownership of the specified mutex object.

BOOL ReleaseMutex(

HANDLE hMutex	// handle of mutex object
);
Parameters

hMutex

Identifies the mutex object. The CreateMutex or OpenMutex function returns this handle.

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.

Remarks

The ReleaseMutex function fails if the calling thread does not own the mutex object.

A thread gets ownership of a mutex by specifying a handle of the mutex in one of the wait functions. The thread that creates a mutex object can also get immediate ownership without using one of the wait functions. When the owning thread no longer needs to own the mutex object, it calls the ReleaseMutex function.

While a thread has ownership of a mutex, it can specify the same mutex in additional wait-function calls without blocking its execution. This prevents a thread from deadlocking itself while waiting for a mutex that it already owns. However, to release its ownership, the thread must call ReleaseMutex once for each time that the mutex satisfied a wait.

See Also

CreateMutex


ReleaseSemaphore

The ReleaseSemaphore function increases the count of the specified semaphore object by a specified amount.

BOOL ReleaseSemaphore(

HANDLE hSemaphore,	// handle of the semaphore object
LONG lReleaseCount,	// amount to add to current count
LPLONG lpPreviousCount	// address of previous count
);
Parameters

hSemaphore

Identifies the semaphore object. The CreateSemaphore or OpenSemaphore function returns this handle.

Windows NT: This handle must have SEMAPHORE_MODIFY_STATE access. For more information, see Interprocess Synchronization Objects.

lReleaseCount

Specifies the amount by which the semaphore object’s current count is to be increased. The value must be greater than zero. If the specified amount would cause the semaphore’s count to exceed the maximum count that was specified when the semaphore was created, the count is not changed and the function returns FALSE.

lpPreviousCount

Points to a 32-bit variable to receive the previous count for the semaphore. This parameter can be NULL if the previous count is not required.

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.

Remarks

The state of a semaphore object is signaled when its count is greater than zero and nonsignaled when its count is equal to zero. The process that calls the CreateSemaphore function specifies the semaphore’s initial count. Each time a waiting thread is released because of the semaphore’s signaled state, the count of the semaphore is decreased by one.

Typically, an application uses a semaphore to limit the number of threads using a resource. Before a thread uses the resource, it specifies the semaphore handle in a call to one of the wait functions. When the wait function returns, it decreases the semaphore’s count by one. When the thread has finished using the resource, it calls ReleaseSemaphore to increase the semaphore’s count by one.

Another use of ReleaseSemaphore is during an application’s initialization. The application can create a semaphore with an initial count of zero. This sets the semaphore’s state to nonsignaled and blocks all threads from accessing the protected resource. When the application finishes its initialization, it uses ReleaseSemaphore to increase the count to its maximum value, to permit normal access to the protected resource.

See Also

CreateSemaphore, OpenSemaphore


RemoveDirectory

The RemoveDirectory function deletes an existing empty directory.

BOOL RemoveDirectory(

LPCTSTR lpPathName	// address of directory to remove
);
Parameters

lpPathName

Points to a null-terminated string that specifies the path of the directory to be removed. The path must specify an empty directory, and the calling process must have delete access to the directory.

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.

See Also

CreateDirectory


RemoveFontResource

The RemoveFontResource function removes the fonts in the specified file from the Windows font table.

BOOL RemoveFontResource(

LPCTSTR lpFileName	// address of font-resource filename
);
Parameters

lpFileName

Points to a null-terminated string that names a font resource file.

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.

Remarks

An application that adds or removes fonts from the Windows public font table should notify other windows of the change by sending a WM_FONTCHANGE message to all top-level windows in the system. The application sends this message by calling the SendMessage function with the hwnd parameter set to HWND_BROADCAST.

If there are outstanding references to a font, the associated resource remains loaded until no device context is using it.

See Also

AddFontResource, SendMessage


RemoveMenu

The RemoveMenu function deletes a menu item from the specified menu. If the menu item opens a drop-down menu or submenu, RemoveMenu does not destroy the menu or its handle, allowing the menu to be reused. Before this function is called, the GetSubMenu function should retrieve the handle of the drop-down menu or submenu.

BOOL RemoveMenu(

HMENU hMenu,	// handle of menu
UINT uPosition,	// menu item identifier or position
UINT uFlags	// menu item flag
);
Parameters

hMenu

Identifies the menu to be changed.

uPosition

Specifies the menu item to be deleted, as determined by the uFlags parameter.

uFlags

Specifies how the uPosition parameter is interpreted. This parameter must be one of the following values:

Value	Meaning
MF_BYCOMMAND	Indicates that uPosition gives the identifier of the menu item. If neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified, the MF_BYCOMMAND flag is the default flag.
MF_BYPOSITION	Indicates that uPosition gives the zero-based relative position of the menu item.
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.

Remarks

The application must call the DrawMenuBar function whenever a menu changes, whether or not the menu is in a displayed window.

See Also

CreatePopupMenu, DeleteMenu, DrawMenuBar, GetSubMenu


RemoveProp

The RemoveProp function removes an entry from the property list of the specified window. The specified character string identifies the entry to be removed.

HANDLE RemoveProp(

HWND hWnd,	// handle to window
LPCTSTR lpString	// atom or address of string
);
Parameters

hWnd

Identifies the window whose property list is to be changed.

lpString

Points to a null-terminated character string or contains an atom that identifies a string. If this parameter is an atom, it must have been created using the AddAtom function. The atom, a 16-bit value, must be placed in the low-order word of lpString; the high-order word must be zero.

Return Values

If the function succeeds, the return value identifies the specified string. If the string cannot be found in the specified property list, the return value is NULL.

Remarks

An application must free the data handles associated with entries removed from a property list. The application can remove only those properties it has added. It must not remove properties added by other applications or by Windows itself.

The RemoveProp function returns the data handle associated with the string so that the application can free the data associated with the handle.

See Also

AddAtom, EnumProps, EnumPropsEx, GetProp, SetProp


ReplaceText

The ReplaceText function creates a system-defined modeless dialog box that lets the user specify a string to search for and a replacement string, as well as options to control the find and replace operations.

HWND ReplaceText(

LPFINDREPLACE lpfr	// pointer to structure with initialization data
);
Parameters

lpfr

Pointer to a FINDREPLACE structure that contains information used to initialize the dialog box. The dialog box uses this structure to send information about the user’s input to your application. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is the window handle to the dialog box. You can use the window handle to communicate with the dialog box or close it.

If the function fails, the return value is NULL. To get extended error information, call the CommDlgExtendedError function, which can return one of the following error codes:

CDERR_FINDRESFAILURE	CDERR_MEMLOCKFAILURE
CDERR_INITIALIZATION	CDERR_NOHINSTANCE
CDERR_LOADRESFAILURE	CDERR_NOHOOK
CDERR_LOADSTRFAILURE	CDERR_NOTEMPLATE
CDERR_LOCKRESFAILURE	CDERR_STRUCTSIZE
CDERR_MEMALLOCFAILURE	FRERR_BUFFERLENGTHZERO
Remarks

The ReplaceText function does not perform a text replacement operation. Instead, the dialog box sends FINDMSGSTRING registered messages to the window procedure of the owner window of the dialog box. When you create the dialog box, the hwndOwner member of the FINDREPLACE structure identifies the owner window.

Before calling ReplaceText, you must call the RegisterWindowMessage function to get the identifier for the FINDMSGSTRING message. The dialog box procedure uses this identifier to send messages when the user clicks the Find Next, Replace, or Replace All buttons, or when the dialog box is closing. The lParam parameter of a FINDMSGSTRING message contains a pointer to the FINDREPLACE structure. The Flags member of this structure indicates the event that caused the message. Other members of the structure indicate the user’s input.

If you create a Replace dialog box, you must also use the IsDialogMessage function in the main message loop of your application to ensure that the dialog box correctly processes keyboard input, such as the TAB and ESC keys. The IsDialogMessage function returns a value that indicates whether the Replace dialog box processed the message.

You can provide an FRHookProc hook procedure for a Replace dialog box. The hook procedure can process messages sent to the dialog box. To enable a hook procedure, set the FR_ENABLEHOOK flag in the Flags member of the FINDREPLACE structure and specify the address of the hook procedure in the lpfnHook member.

See Also

CommDlgExtendedError, FINDREPLACE, FRHookProc, IsDialogMessage, RegisterWindowMessage, WM_CTLCOLORDLG


ReplyMessage

The ReplyMessage function is used to reply to a message sent through the SendMessage function without returning control to the function that called SendMessage.

BOOL ReplyMessage(

LRESULT lResult	// message-specific reply
);
Parameters

lResult

Specifies the result of the message processing. The possible values are based on the message sent.

Return Values

If the calling thread was processing a message sent from another thread or process, the return value is nonzero.

If the calling thread was not processing a message sent from another thread or process, the return value is zero.

Remarks

By calling this function, the window procedure that receives the message allows the thread that called SendMessage to continue to run as though the thread receiving the message had returned control. The thread that calls the ReplyMessage function also continues to run.

If the message was not sent through SendMessage or if the message was sent by the same thread, ReplyMessage has no effect.

See Also

InSendMessage, SendMessage


ReportEvent

The ReportEvent function writes an entry at the end of the specified event log.

BOOL ReportEvent(

HANDLE hEventLog,	// handle returned by RegisterEventSource
WORD wType,	// event type to log
WORD wCategory,	// event category
DWORD dwEventID,	// event identifier
PSID lpUserSid,	// user security identifier (optional)
WORD wNumStrings,	// number of strings to merge with message
DWORD dwDataSize,	// size of binary data, in bytes
LPCTSTR *lpStrings,	// array of strings to merge with message
LPVOID lpRawData	// address of binary data
);
Parameters

hEventLog

Identifies the event log. This handle is returned by the RegisterEventSource function.

wType

Specifies the type of event being logged. This parameter can be one of the following values:

Value	Meaning
EVENTLOG_ERROR_TYPE	Error event
EVENTLOG_WARNING_TYPE	Warning event
EVENTLOG_INFORMATION_TYPE	Information event
EVENTLOG_AUDIT_SUCCESS	Success Audit event
EVENTLOG_AUDIT_FAILURE	Failure Audit event
For more information about event types, see Event Logging.

wCategory

Specifies the event category. This is source-specific information; the category can have any value.

dwEventID

Specifies the event identifier. The event identifier specifies the message that goes with this event as an entry in the message file associated with the event source.

lpUserSid

Points to the current user’s security identifier. This parameter can be NULL if the security identifier is not required.

wNumStrings

Specifies the number of strings in the array pointed to by the lpStrings parameter. A value of zero indicates that no strings are present.

dwDataSize

Specifies the number of bytes of event-specific raw (binary) data to write to the log. If this parameter is zero, no event-specific data is present.

lpStrings

Points to a buffer containing an array of null-terminated strings that are merged into the message before Event Viewer displays the string to the user. This parameter must be a valid pointer (or NULL), even if wNumStrings is zero.

lpRawData

Points to the buffer containing the binary data. This parameter must be a valid pointer (or NULL), even if the dwDataSize parameter is zero.

Return Values

If the function succeeds, the return value is nonzero, indicating that the entry was written to the log.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

This function is used to log an event. The entry is written to the end of the configured logfile for the source identified by the hEventLog parameter. The ReportEvent function adds the time, the user name, the entry’s length, and the offsets before storing the entry in the log.

See Also

ClearEventLog, CloseEventLog, OpenEventLog, ReadEventLog, RegisterEventSource


ResetDC

The ResetDC function updates the given printer or plotter device context, based on the information in the specified structure.

HDC ResetDC(

HDC hdc,	// handle of device context
CONST DEVMODE *lpInitData	// address of structure with device context information
);
Parameters

hdc

Identifies the device context to update.

lpInitData

Points to a DEVMODE structure containing information about the new device context.

Return Values

If the function succeeds, the return value is the handle of the original device context.

If the function fails, the return value is NULL.

Remarks

An application will typically use the ResetDC function when a window receives a WM_DEVMODECHANGE message. ResetDC can also be used to change the paper orientation or paper bins while printing a document.

The ResetDC function cannot be used to change the driver name, device name, or the output port. When the user changes the port connection or device name, the application must delete the original device context and create a new device context with the new information.

An application can pass an information device context to the ResetDC function. In that situation, ResetDC will always return a printer device context.

See Also

DeviceCapabilities, DEVMODE, Escape


ResetEvent

The ResetEvent function sets the state of the specified event object to nonsignaled.

BOOL ResetEvent(

HANDLE hEvent	// handle of event object
);
Parameters

hEvent

Identifies the event object. The CreateEvent or OpenEvent function returns this handle.

Windows NT: The handle must have EVENT_MODIFY_STATE access. For more information, see Interprocess Synchronization Objects.

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.

Remarks

The state of an event object remains nonsignaled until it is explicitly set to signaled by the SetEvent or PulseEvent function. This nonsignaled state blocks the execution of any threads that have specified the event object in a call to one of the wait functions.

The ResetEvent function is used primarily for manual-reset event objects, which must be set explicitly to the nonsignaled state. Auto-reset event objects automatically change from signaled to nonsignaled after a single waiting thread is released.

See Also

CreateEvent, OpenEvent, PulseEvent, SetEvent


ResetPrinter

The ResetPrinter function lets an application specify the data type and device mode values that are used for printing documents submitted by the StartDocPrinter function. These values can be overridden by using the SetJob function once document printing has started.

BOOL ResetPrinter (

HANDLE hPrinter,	// printer handle
LPPRINTER_DEFAULTS pDefault	// address of printer defaults structure
);
Parameters

hPrinter

Identifies a printer.

pDefault

Points to a PRINTER_DEFAULTS structure.

The ResetPrinter function ignores the DesiredAccess member of the PRINTER_DEFAULTS structure. Set that member to zero.

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.

See Also

OpenPrinter, PRINTER_DEFAULTS, StartDocPrinter, SetJob


ResizePalette

The ResizePalette function increases or decreases the size of a logical palette based on the specified value.

BOOL ResizePalette(

HPALETTE hpal,	// handle of logical palette
UINT nEntries	// number of entries in logical palette
);
Parameters

hpal

Identifies the palette to be changed.

nEntries

Specifies the number of entries in the palette after it has been resized.

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.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

If an application calls ResizePalette to reduce the size of the palette, the entries remaining in the resized palette are unchanged. If the application calls ResizePalette to enlarge the palette, the additional palette entries are set to black (the red, green, and blue values are all 0) and their flags are set to zero.

See Also

GetDeviceCaps


RestoreDC

The RestoreDC function restores a device context (DC) to the specified state. The device context is restored by popping state information off a stack created by earlier calls to the SaveDC function.

BOOL RestoreDC(

HDC hdc,	// handle of device context
int nSavedDC	// specifies state to be restored
);
Parameters

hdc

Identifies the device context.

nSavedDC

Specifies the instance of the device context to be restored. If this parameter is positive, nSavedDC represents a specific instance of the device context to be restored. If this parameter is negative, nSavedDC represents an instance relative to the current device context. For example, −1 restores the most recently saved state.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The stack can contain the state information for several instances of the device context. If the state specified by the given parameter is not at the top of the stack, RestoreDC deletes all state information between the top of the stack and the specified instance.

See Also

SaveDC


ResumeThread

The ResumeThread function decrements a thread’s suspend count. When the suspend count is decremented to zero, the execution of the thread is resumed.

DWORD ResumeThread(

HANDLE hThread	// identifies thread to restart
);
Parameters

hThread

Specifies a handle for the thread to be restarted.

Windows NT: The handle must have THREAD_SUSPEND_RESUME access to the thread. For more information, see Thread Objects.

Return Values

If the function succeeds, the return value is the thread’s previous suspend count.

If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

Remarks

The ResumeThread function checks the suspend count of the subject thread. If the suspend count is 0, the thread is not currently suspended. Otherwise, the subject thread’s suspend count is decremented. If the resulting value is 0, then the execution of the subject thread is resumed.

If the return value is 0, the specified thread was not suspended. If the return value is 1, the specified thread was suspended but was restarted. If the return value is greater than 1, the specified thread is still suspended.

Note that while reporting debug events, all threads within the reporting process are frozen. Debuggers are expected to use the SuspendThread and ResumeThread functions to limit the set of threads that can execute within a process. By suspending all threads in a process except for the one reporting a debug event, it is possible to “single step” a single thread. The other threads are not released by a continue operation if they are suspended.

See Also

SuspendThread


ReuseDDElParam

The ReuseDDElParam function allows an application to reuse a packed DDE lParam parameter, rather than allocating a new packed lParam. Using this function reduces reallocations for applications that pass packed DDE messages.

LONG ReuseDDElParam(

LONG lParam,	// posted lParam to be reused
UINT msgIn,	// identifier of received message
UINT msgOut,	// identifier of posted message
UINT uiLo,	// low-order word of new lParam
UINT uiHi	// high-order word of new lParam
);
Parameters

lParam

Specifies the lParam parameter of the posted DDE message being reused.

msgIn

Specifies the identifier of the received DDE message.

msgOut

Specifies the identifier of the DDE message to be posted. The DDE message will reuse the packed lParam parameter.

uiLo

Specifies the value to be packed into the low-order word of the reused lParam parameter.

uiHi

Specifies the value to be packed into the high-order word of the reused lParam parameter.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The return value must be posted as the lParam parameter of a DDE message; it must not be used for any other purpose. Once the return value is posted, the posting application need not perform any action to dispose of the lParam parameter.

Use ReuseDDElParam instead of FreeDDElParam if the lParam parameter will be reused in a responding message. ReuseDDElParam returns the lParam appropriate for reuse.

This function allocates or frees lParam parameters as needed, depending on the packing requirements of the incoming and outgoing messages. This reduces reallocations in passing DDE messages.

See Also

FreeDDElParam, PackDDElParam, UnpackDDElParam


RevertToSelf

The RevertToSelf function terminates the impersonation of a client application.

BOOL RevertToSelf(VOID)

Parameters

This function has no parameters.

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.

Remarks

It is advisable for a process to call the RevertToSelf function after finishing any impersonation begun by using the DdeImpersonateClient, ImpersonateNamedPipeClient, or ImpersonateSelf function.

See Also

DdeImpersonateClient, ImpersonateNamedPipeClient, ImpersonateSelf


RoundRect

The RoundRect function draws a rectangle with rounded corners. The rectangle is outlined by using the current pen and filled by using the current brush.

BOOL RoundRect(

HDC hdc,	// handle of device context
int nLeftRect,	// x-coord. of bounding rectangle’s upper-left corner
int nTopRect,	// y-coord. of bounding rectangle’s upper-left corner
int nRightRect,	// x-coord. of bounding rectangle’s lower-right corner
int nBottomRect,	// y-coord. of bounding rectangle’s lower-right corner
int nWidth,	// width of ellipse used to draw rounded corners
int nHeight	// height of ellipse used to draw rounded corners
);
Parameters

hdc

Identifies the device context.

nLeftRect

Specifies the x-coordinate of the upper-left corner of the rectangle.

nTopRect

Specifies the y-coordinate of the upper-left corner of the rectangle.

nRightRect

Specifies the x-coordinate of the lower-right corner of the rectangle.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the rectangle.

nWidth

Specifies the width of the ellipse used to draw the rounded corners.

nHeight

Specifies the height of the ellipse used to draw the rounded corners.

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.

Remarks

The current position is neither used nor updated by this function.

Windows 95: The sum of the coordinates of the bounding rectangle cannot exceed 32,767. The sum of nLeftRect and nRightRect or nTopRect and nBottomRect parameters cannot exceed 32,767.

See Also

Rectangle


SaveDC

The SaveDC function saves the current state of the specified device context (DC) by copying data describing selected objects and graphic modes (such as the bitmap, brush, palette, font, pen, region, drawing mode, and mapping mode) to a context stack.

int SaveDC(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies the device context to be saved.

Return Values

If the function succeeds, the return value identifies the saved device context.

If the function fails, the return value is zero.

Remarks

The SaveDC function can be used any number of times to save any number of instances of the device context’s state.

A saved state can later be restored by using the RestoreDC function.

See Also

RestoreDC


ScaleViewportExtEx

The ScaleViewportExtEx function modifies the viewport for a device context (DC) by using the ratios formed by the specified multiplicands and divisors.

BOOL ScaleViewportExtEx(

HDC hdc,	// handle of device context
int Xnum,	// horizontal multiplicand
int Xdenom,	// horizontal divisor
int Ynum,	// vertical multiplicand
int Ydenom,	// vertical divisor
LPSIZE lpSize	// address of previous viewport extents
);
Parameters

hdc

Identifies the device context.

Xnum

Specifies the amount by which to multiply the current horizontal extent.

Xdenom

Specifies the amount by which to divide the current horizontal extent.

Ynum

Specifies the amount by which to multiply the current vertical extent.

Ydenom

Specifies the amount by which to divide the current vertical extent.

lpSize

Points to a SIZE structure. The previous viewport extents (in device units) are placed in this structure. If lpSize is NULL, nothing is returned.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The viewport extents are modified as follows:

    xNewVE = (xOldVE * Xnum) / Xdenom

    yNewVE = (yOldVE * Ynum) / Ydenom

See Also

GetViewportExtEx, SIZE


ScaleWindowExtEx

The ScaleWindowExtEx function modifies the window for a device context using the ratios formed by the specified multiplicands and divisors.

BOOL ScaleWindowExtEx(

HDC hdc,	// handle of device context
int Xnum,	// horizontal multiplicand
int Xdenom,	// horizontal divisor
int Ynum,	// vertical multiplicand
int Ydenom,	// vertical divisor
LPSIZE lpSize	// address of previous window extents
);
Parameters

hdc

Identifies the device context.

Xnum

Specifies the amount by which to multiply the current horizontal extent.

Xdenom

Specifies the amount by which to divide the current horizontal extent.

Ynum

Specifies the amount by which to multiply the current vertical extent.

Ydenom

Specifies the amount by which to divide the current vertical extent.

lpSize

Points to a SIZE structure. The previous window extents (in logical units) are placed in this structure. If lpSize is NULL, nothing is returned.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The window extents are modified as follows:

    xNewWE = (xOldWE * Xnum) / Xdenom

    yNewWE = (yOldWE * Ynum) / Ydenom

See Also

GetWindowExtEx, SIZE


ScheduleJob

The ScheduleJob function requests that the print spooler schedule a specified print job for printing.

BOOL ScheduleJob(

HANDLE hPrinter,	// specifies printer for the print job
DWORD dwJobID	// print job identifier
);
Parameters

hPrinter

Handle that specifies a printer for the print job. This must be a local printer that is configured as a spooled printer. If hPrinter is a handle to a remote printer connection, or if the printer is configured for direct printing, the ScheduleJob function fails.

hPrinter must be the same printer handle specifed in the call to AddJob that obtained the dwJobID print job identifer.

dwJobID

Specifies the print job to be scheduled. You obtain this print job identifer by calling the AddJob 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.

Remarks

You obtain a printer handle by calling the OpenPrinter function.

You must successfully call the AddJob function before calling the ScheduleJob function. AddJob obtains the print job identifer that you pass to ScheduleJob as dwJobID. Both calls must use the same value for hPrinter.

The ScheduleJob function checks for a valid spool file. If there is an invalid spool file, or if it is empty, ScheduleJob deletes both the spool file and the corresponding print job entry in the print spooler.

See Also

AddJob, OpenPrinter


ScreenSaverConfigureDialog

The ScreenSaverConfigureDialog function receives messages sent to a screen saver’s configuration dialog box. A screen saver that allows user configuration must support this function.

BOOL ScreenSaverConfigureDialog(

HWND hDlg,	// handle of dialog box
UINT message,	// message
WPARAM wParam,	// first message parameter
LPARAM lParam	// second message parameter
);
Parameters

hDlg

Identifies the configuration dialog box.

message

Specifies the message.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Values

If the function processes the message, the return value is TRUE; otherwise, it is FALSE, except in response to a WM_INITDIALOG message. In response to a WM_INITDIALOG message, ScreenSaverConfigureDialog should return FALSE if it calls the SetFocus function to set the keyboard focus to one of the controls in the dialog box. Otherwise, the function should return TRUE, in which case the system sets the keyboard focus to the first control in the dialog box that can be given the focus.

Remarks

The dialog box template for the configuration dialog box must have the DLG_SCRNSAVECONFIGURE identifier.

The dialog box procedure is used only if the application specifies the default window class (WC_DIALOG) for the dialog box. The application uses the default class if no explicit class is given in the dialog box template. Although the dialog box procedure is similar to a window procedure, it must not call the DefWindowProc function to process unwanted messages. Unwanted messages are processed internally by the default dialog box procedure.

The ScreenSaverConfigureDialog function must be exported by including it in the EXPORTS statement in the application’s module-definition (.DEF) file.

See Also

DefWindowProc, RegisterDialogClasses, SetFocus


ScreenSaverProc

The ScreenSaverProc function receives messages sent to the specified screen saver window.

LONG ScreenSaverProc(

HWND hWnd,	// handle of screen saver window
UINT message,	// message
WPARAM wParam,	// first message parameter
LPARAM lParam	// second message parameter
);
Parameters

hWnd

Identifies the window.

message

Specifies the message.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Values

The return value is the result of the message processing and depends on the message sent.

Remarks

A screen saver’s ScreenSaverProc window procedure should use the DefScreenSaverProc function instead of the DefWindowProc function to provide default message processing. The DefScreenSaverProc function passes any messages that do not affect screen saver operations to DefWindowProc.

The ScreenSaverProc function must be exported by including it in the EXPORTS statement in the application’s module-definition (.DEF) file.

See Also

DefScreenSaverProc, DefWindowProc


ScreenToClient

The ScreenToClient function converts the screen coordinates of a specified point on the screen to client coordinates.

BOOL ScreenToClient(

HWND hWnd,	// window handle for source coordinates
LPPOINT lpPoint	// address of structure containing coordinates
);
Parameters

hWnd

Identifies the window whose client area will be used for the conversion.

lpPoint

Points to a POINT structure that contains the screen coordinates to be converted.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The function uses the window identified by the hWnd parameter and the screen coordinates given in the POINT structure to compute client coordinates. It then replaces the screen coordinates with the client coordinates. The new coordinates are relative to the upper-left corner of the specified window’s client area.

The ScreenToClient function assumes the specified point is in screen coordinates.

See Also

ClientToScreen, MapWindowPoints, POINT


ScrollConsoleScreenBuffer

The ScrollConsoleScreenBuffer function moves a block of data in a screen buffer. The effects of the move can be limited by specifying a clipping rectangle, so the contents of the screen buffer outside the clipping rectangle are unchanged.

BOOL ScrollConsoleScreenBuffer(

HANDLE hConsoleOutput,	// handle of a console screen buffer
CONST SMALL_RECT *lpScrollRectangle,	// address of screen buffer rect. to move
CONST SMALL_RECT *lpClipRectangle,	// address of affected screen buffer rect.
COORD dwDestinationOrigin,	// new location of screen buffer rect.
CONST CHAR_INFO *lpFill	// address of fill character and color
);
Parameters

hConsoleOutput

Identifies a console screen buffer. The handle must have GENERIC_WRITE access.

lpScrollRectangle

Points to a SMALL_RECT structure whose members specify the upper-left and lower-right coordinates of the screen buffer rectangle to be moved.

lpClipRectangle

Points to a SMALL_RECT structure whose members specify the upper-left and lower-right coordinates of the screen buffer rectangle that is affected by the scrolling. This pointer can be NULL.

dwDestinationOrigin

Specifies the upper-left corner of the new location of the lpScrollRectangle contents.

lpFill

Points to a CHAR_INFO structure that specifies the character and color attributes to be used in filling the cells within the intersection of lpScrollRectangle and lpClipRectangle that were left empty as a result of the move.

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.

Remarks

ScrollConsoleScreenBuffer copies the contents of a rectangular region of a screen buffer, specified by the lpScrollRectangle parameter, to another area of the screen buffer. The target rectangle has the same dimensions as the lpScrollRectangle rectangle with its upper-left corner at the coordinates specified by the dwDestinationOrigin parameter. Those parts of lpScrollRectangle that do not overlap with the target rectangle are filled in with the character and color attributes specified by the lpFill parameter.

The clipping rectangle applies to changes made in both the lpScrollRectangle rectangle and the target rectangle. For example, if the clipping rectangle does not include a region that would have been filled by the contents of lpFill, the original contents of the region are left unchanged.

If the scroll or target regions extend beyond the dimensions of the screen buffer, they are clipped. For example, if lpScrollRectangle is the region contained by (0,0) and (19,19) and dwDestinationOrigin is (10,15), the target rectangle is the region contained by (10,15) and (29,34). However, if the screen buffer is 50 characters wide and 30 characters high, the target rectangle is clipped to (10,15) and (29,29). Changes to the screen buffer are also clipped according to lpClipRectangle, if the parameter specifies a SMALL_RECT structure. If the clipping rectangle is specified as (0,0) and (49,19), only the changes that occur in that region of the screen buffer are made.

Windows NT: This function uses either Unicode characters or 8-bit characters from the console's current codepage. The console's codepage defaults initially to the system's OEM codepage. To change the console's codepage, use the SetConsoleCP or SetConsoleOutputCP functions, or use the chcp or mode con cp select= commands.

See Also

CHAR_INFO, SetConsoleCP, SetConsoleOutputCP, SetConsoleWindowInfo, SMALL_RECT


ScrollDC

The ScrollDC function scrolls a rectangle of bits horizontally and vertically.

BOOL ScrollDC(

HDC hDC,	// handle of device context
int dx,	// horizontal scroll units
int dy,	// vertical scroll units
CONST RECT *lprcScroll,	// address of structure for scrolling rectangle
CONST RECT *lprcClip,	// address of structure for clipping rectangle
HRGN hrgnUpdate,	// handle of scrolling region
LPRECT lprcUpdate	// address of structure for update rectangle
);
Parameters

hDC

Identifies the device context that contains the bits to be scrolled.

dx

Specifies the amount, in device units, of horizontal scrolling. This parameter must be a negative value to scroll to the left.

dy

Specifies the amount, in device units, of vertical scrolling. This parameter must be a negative value to scroll up.

lprcScroll

Points to the RECT structure containing the coordinates of the scrolling rectangle.

lprcClip

Points to the RECT structure containing the coordinates of the clipping rectangle. Only device bits within the clipping rectangle are affected. Bits scrolled from the outside of the rectangle to the inside are painted; bits scrolled from the inside of the rectangle to the outside are not painted.

hrgnUpdate

Identifies the region uncovered by the scrolling process. ScrollDC defines this region; it is not necessarily a rectangle.

lprcUpdate

Points to the RECT structure that receives the coordinates of the rectangle bounding the scrolling update region. This is the largest rectangular area that requires repainting. When the function returns, the values in the structure are in client coordinates, regardless of the mapping mode for the specified device context. This allows applications to use the update region in a call to the InvalidateRgn function, if required.

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.

Remarks

If the lprcUpdate parameter is NULL, Windows does not compute the update rectangle. If both the hrgnUpdate and lprcUpdate parameters are NULL, Windows does not compute the update region. If hrgnUpdate is not NULL, Windows proceeds as though it contains a valid handle of the region uncovered by the scrolling process (defined by ScrollDC).

When you must scroll the entire client area of a window, use the ScrollWindow function; otherwise, use ScrollDC.

See Also

InvalidateRgn, RECT, ScrollWindow


ScrollWindow

The ScrollWindow function scrolls the content of the specified window’s client area. This function exists for backward compatibility. For new applications, use the ScrollWindowEx function.

BOOL ScrollWindow(

HWND hWnd,	// handle of window to scroll
int XAmount,	// amount of horizontal scrolling
int YAmount,	// amount of vertical scrolling
CONST RECT *lpRect,	// address of structure with scroll rectangle
CONST RECT *lpClipRect	// address of structure with clip rectangle
);
Parameters

hWnd

Identifies the window where the client area is to be scrolled.

XAmount

Specifies the amount, in device units, of horizontal scrolling. If the window being scrolled has the CS_OWNDC or CS_CLASSDC style, then this parameter uses logical units rather than device units. This parameter must be a negative value to scroll the content of the window to the left.

YAmount

Specifies the amount, in device units, of vertical scrolling. If the window being scrolled has the CS_OWNDC or CS_CLASSDC style, then this parameter uses logical units rather than device units. This parameter must be a negative value to scroll the content of the window up.

lpRect

Points to the RECT structure specifying the portion of the client area to be scrolled. If this parameter is NULL, the entire client area is scrolled.

lpClipRect

Points to the RECT structure containing the coordinates of the clipping rectangle. Only device bits within the clipping rectangle are affected. Bits scrolled from the outside of the rectangle to the inside are painted; bits scrolled from the inside of the rectangle to the outside are not painted.

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.

Remarks

If the caret is in the window being scrolled, ScrollWindow automatically hides the caret to prevent it from being erased and then restores the caret after the scrolling is finished. The caret position is adjusted accordingly.

The area uncovered by ScrollWindow is not repainted, but it is combined into the window’s update region. The application eventually receives a WM_PAINT message notifying it that the region must be repainted. To repaint the uncovered area at the same time the scrolling is in action, call the UpdateWindow function immediately after calling ScrollWindow.

If the lpRect parameter is NULL, the positions of any child windows in the window are offset by the amount specified by the XAmount and YAmount parameters; invalid (unpainted) areas in the window are also offset. ScrollWindow is faster when lpRect is NULL.

If lpRect is not NULL, the positions of child windows are not changed and invalid areas in the window are not offset. To prevent updating problems when lpRect is not NULL, call UpdateWindow to repaint the window before calling ScrollWindow.

See Also

RECT, ScrollDC, ScrollWindowEx, UpdateWindow


ScrollWindowEx

The ScrollWindowEx function scrolls the content of the specified window’s client area. This function is similar to the ScrollWindow function, but it has additional features.

int ScrollWindowEx(

HWND hWnd,	// handle of window to scroll
int dx,	// amount of horizontal scrolling
int dy,	// amount of vertical scrolling
CONST RECT *prcScroll,	// address of structure with scroll rectangle
CONST RECT *prcClip,	// address of structure with clip rectangle
HRGN hrgnUpdate,	// handle of update region
LPRECT prcUpdate,	// address of structure for update rectangle
UINT flags	// scrolling flags
);
Parameters

hWnd

Identifies the window where the client area is to be scrolled.

dx

Specifies the amount, in device units, of horizontal scrolling. This parameter must be a negative value to scroll to the left.

dy

Specifies the amount, in device units, of vertical scrolling. This parameter must be a negative value to scroll up.

prcScroll

Points to the RECT structure specifying the portion of the client area to be scrolled. If this parameter is NULL, the entire client area is scrolled.

prcClip

Points to the RECT structure containing the coordinates of the clipping rectangle. Only device bits within the clipping rectangle are affected. Bits scrolled from the outside of the rectangle to the inside are painted; bits scrolled from the inside of the rectangle to the outside are not painted.

hrgnUpdate

Identifies the region that is modified to hold the region invalidated by scrolling. This parameter may be NULL.

prcUpdate

Points to the RECT structure receiving the boundaries of the rectangle invalidated by scrolling. This parameter may be NULL.

flags

Specifies flags that control scrolling. This parameter can be one of the following values:

Value	Meaning
SW_ERASE	Erases the newly invalidated region by sending a WM_ERASEBKGND message to the window when specified with the SW_INVALIDATE flag.
SW_INVALIDATE	Invalidates the region identified by the hrgnUpdate parameter after scrolling.
SW_SCROLLCHILDREN	Scrolls all child windows that intersect the rectangle pointed to by the prcScroll parameter. The child windows are scrolled by the number of pixels specified by the dx and dy parameters. Windows sends a WM_MOVE message to all child windows that intersect the prcScroll rectangle, even if they do not move.
Return Values

If the function succeeds, the return value is SIMPLEREGION (rectangular invalidated region), COMPLEXREGION (nonrectangular invalidated region; overlapping rectangles), or NULLREGION (no invalidated region).

If the function fails, the return value is ERROR.

Remarks

If the SW_INVALIDATE and SW_ERASE flags are not specified, ScrollWindowEx does not invalidate the area that is scrolled from. If either of these flags is set, ScrollWindowEx invalidates this area. The area is not updated until the application calls the UpdateWindow function, calls the RedrawWindow function (specifying the RDW_UPDATENOW or RDW_ERASENOW flag), or retrieves the WM_PAINT message from the application queue.

If the window has the WS_CLIPCHILDREN style, the returned areas specified by hrgnUpdate and prcUpdate represent the total area of the scrolled window that must be updated, including any areas in child windows that need updating.

If the SW_SCROLLCHILDREN flag is specified, Windows does not properly update the screen if part of a child window is scrolled. The part of the scrolled child window that lies outside the source rectangle is not erased and is not properly redrawn in its new destination. To move child windows that do not lie completely within the rectangle specified by prcScroll, use the DeferWindowPos function. The cursor is repositioned if the SW_SCROLLCHILDREN flag is set and the caret rectangle intersects the scroll rectangle.

All input and output coordinates (for prcScroll, prcClip, prcUpdate, and hrgnUpdate) are determined as client coordinates, regardless of whether the window has the CS_OWNDC or CS_CLASSDC class style. Use the LPtoDP and DPtoLP functions to convert to and from logical coordinates, if necessary.

See Also

DeferWindowPos, DPtoLP, LPtoDP, RECT, RedrawWindow, ScrollDC, ScrollWindow, UpdateWindow


SearchPath

The SearchPath function searches for the specified file.

DWORD SearchPath(

LPCTSTR lpPath,	// address of search path
LPCTSTR lpFileName,	// address of filename
LPCTSTR lpExtension,	// address of extension
DWORD nBufferLength,	// size, in characters, of buffer
LPTSTR lpBuffer,	// address of buffer for found filename
LPTSTR *lpFilePart	// address of pointer to file component
);
Parameters

lpPath

Points to a null-terminated string that specifies the path to be searched for the file. If this parameter is NULL, the function searches for a matching file in the following directories in the following sequence:

1.	The directory from which the application loaded.

2.	The current directory.

3.	Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path of this directory.

Windows NT: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	Windows NT: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

lpFileName

Points to a null-terminated string that specifies the name of the file to search for.

lpExtension

Points to a null-terminated string that specifies an extension to be added to the filename when searching for the file. The first character of the filename extension must be a period (.). The extension is added only if the specified filename does not end with an extension.

If a filename extension is not required or if the filename contains an extension, this parameter can be NULL.

nBufferLength

Specifies the length, in characters, of the buffer that receives the valid path and filename.

lpBuffer

Points to the buffer for the valid path and filename of the file found.

lpFilePart

Points to the address (within lpBuffer) of the last component of the valid path and filename, which is the address of the character immediately following the final backslash (\) in the path.

Return Values

If the function succeeds, the value returned is the length, in characters, of the string copied to the buffer, not including the terminating null character. If the return value is greater than nBufferLength, the value returned is the size of the buffer required to hold the path.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

FindFirstFile, FindNextFile, GetSystemDirectory, GetWindowsDirectory


SelectClipPath

The SelectClipPath function selects the current path as a clipping region for a device context, combining the new region with any existing clipping region by using the specified mode.

BOOL SelectClipPath(

HDC hdc,	// handle of device context
int iMode	// clipping mode
);
Parameters

hdc

Identifies the device context of the path.

iMode

Specifies the way to use the path. The following values are allowed:

Value	Meaning
RGN_AND	The new clipping region includes the intersection (overlapping areas) of the current clipping region and the current path.
RGN_COPY	The new clipping region is the current path.
RGN_DIFF	The new clipping region includes the areas of the current clipping region with those of the current path excluded.
RGN_OR	The new clipping region includes the union (combined areas) of the current clipping region and the current path.
RGN_XOR	The new clipping region includes the union of the current clipping region and the current path but without the overlapping areas.
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 one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY

Remarks

The device context identified by the hdc parameter must contain a closed path.

See Also

BeginPath, EndPath


SelectClipRgn

The SelectClipRgn function selects a region as the current clipping region for the specified device context.

int SelectClipRgn(

HDC hdc,	// handle of device context
HRGN hrgn	// handle of region to be selected
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies the region to be selected.

Return Values

If the function succeeds, the return value specifies the region’s complexity and can be any one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
ERROR	An error occurred. (The previous clipping region is unaffected.)
Remarks

Only a copy of the selected region is used. The region itself can be selected for any number of other device contexts or it can be deleted.

The SelectClipRgn function assumes that the coordinates for a region are specified in device units.

To remove a device-context’s clipping region, specify a NULL region handle.

See Also

ExtSelectClipRgn


SelectObject

The SelectObject function selects an object into the specified device context. The new object replaces the previous object of the same type.

HGDIOBJ SelectObject(

HDC hdc,	// handle of device context
HGDIOBJ hgdiobj	// handle of object
);
Parameters

hdc

Identifies the device context.

hgdiobj

Identifies the object to be selected. The specified object must have been created by using one of the following functions:

Object	Functions
Bitmap	CreateBitmap, CreateBitmapIndirect, CreateCompatibleBitmap, CreateDIBitmap, CreateDIBSection
	(Bitmaps can be selected for memory device contexts only, and for only one device context at a time.)
Brush	CreateBrushIndirect, CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreateHatchBrush, CreatePatternBrush, CreateSolidBrush
Font	CreateFont, CreateFontIndirect
Pen	CreatePen, CreatePenIndirect
Region	CombineRgn, CreateEllipticRgn, CreateEllipticRgnIndirect, CreatePolygonRgn, CreateRectRgn, CreateRectRgnIndirect
Return Values

If the selected object is not a region and the function succeeds, the return value is the handle of the object being replaced. If the selected object is a region and the function succeeds, the return value is one of the following values:

Value	Meaning
SIMPLEREGION	Region consists of a single rectangle.
COMPLEXREGION	Region consists of more than one rectangle.
NULLREGION	Region is empty.
If an error occurs and the selected object is not a region, the return value is NULL. Otherwise, it is GDI_ERROR.

Remarks

This function returns the previously selected object of the specified type. An application should always replace a new object with the original, default object after it has finished drawing with the new object.

An application cannot select a bitmap into more than one device context at a time.

See Also

CombineRgn, CreateBitmap, CreateBitmapIndirect, CreateBrushIndirect, CreateCompatibleBitmap, CreateDIBitmap, CreateDIBPatternBrush, CreateEllipticRgn, CreateEllipticRgnIndirect, CreateFont, CreateFontIndirect, CreateHatchBrush, CreatePatternBrush, CreatePen, CreatePenIndirect, CreatePolygonRgn, CreateRectRgn, CreateRectRgnIndirect, CreateSolidBrush, SelectClipRgn, SelectPalette


SelectPalette

The SelectPalette function selects the specified logical palette into a device context.

HPALETTE SelectPalette(

HDC hdc,	// handle of device context
HPALETTE hpal,	// handle of logical color palette
BOOL bForceBackground	// foreground/background mode
);
Parameters

hdc

Identifies the device context.

hpal

Identifies the logical palette to be selected.

bForceBackground

Specifies whether the logical palette is forced to be a background palette. If this value is TRUE, the RealizePalette function causes the logical palette to be mapped to the colors already in the physical palette in the best possible way. This is always done, even if the window for which the palette is realized belongs to a thread without active focus.

If this value is FALSE, RealizePalette causes the logical palette to be copied into the device palette when the application is in the foreground. (If the hdc parameter is a memory device context, this parameter is ignored.)

Return Values

If the function succeeds, the return value identifies the device context’s previous logical palette.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

An application can select a logical palette into more than one device context. However, changes to a logical palette will affect all device contexts for which it is selected.

An application might call the SelectPalette function with the bForceBackground parameter set to TRUE if the child windows of a top-level window each realize their own palettes. However, only the child window that needs to realize its palette must set bForceBackground to TRUE; other child windows must set this value to FALSE.

See Also

CreatePalette, GetDeviceCaps, RealizePalette


SendAsyncProc

A SendAsyncProc function is an application-defined callback function that the operating system calls when the SendMessageCallback function is called. The system passes the message to the callback function after passing the message to the destination window procedure. A value of type SENDASYNCPROC is a pointer to such a function.

VOID CALLBACK SendAsyncProc(

HWND hwnd,	// handle of destination window
UINT uMsg,	// message
DWORD dwData,	// application-defined value
LRESULT lResult	// result of message processing
);
Parameters

hwnd

Identifies the window whose window procedure received the message.

If the SendMessageCallback function was called with its hwnd parameter set to HWND_BROADCAST, the operating system calls the SendAsyncProc function once for each top-level window.

uMsg

Specifies the message.

dwData

Specifies an application-defined value sent from the SendMessageCallback function.

lResult

Specifies the result of the message processing and depends on the message.

Return Values

This callback function does not return a value.

Remarks

SendAsyncProc is a placeholder for an application-defined function name.

You install a SendAsyncProc application-defined callback function by passing a SENDASYNCPROC pointer to the SendMessageCallback function.

The callback function is only called when the thread that called SendMessageCallback calls GetMessage, PeekMessage, or WaitMessage.

See Also

GetMessage, PeekMessage, SendMessageCallback, WaitMessage


SendDlgItemMessage

The SendDlgItemMessage function sends a message to the specified control in a dialog box.

LONG SendDlgItemMessage(

HWND hDlg,	// handle of dialog box
int nIDDlgItem,	// identifier of control
UINT Msg,	// message to send
WPARAM wParam,	// first message parameter
LPARAM lParam	// second message parameter
);
Parameters

hDlg

Identifies the dialog box that contains the control.

nIDDlgItem

Specifies the identifier of the control that receives the message.

Msg

Specifies the message to be sent.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Values

The return value specifies the result of the message processing and depends on the message sent.

Remarks

The SendDlgItemMessage function does not return until the message has been processed.

Using SendDlgItemMessage is identical to retrieving a handle of the specified control and calling the SendMessage function.

See Also

SendMessage


SendMessage

The SendMessage function sends the specified message to a window or windows. The function calls the window procedure for the specified window and does not return until the window procedure has processed the message. The PostMessage function, in contrast, posts a message to a thread’s message queue and returns immediately.

LRESULT SendMessage(

HWND hWnd,	// handle of destination window
UINT Msg,	// message to send
WPARAM wParam,	// first message parameter
LPARAM lParam	// second message parameter
);
Parameters

hWnd

Identifies the window whose window procedure will receive the message. If this parameter is HWND_BROADCAST, the message is sent to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent to child windows.

Msg

Specifies the message to be sent.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Values

The return value specifies the result of the message processing and depends on the message sent.

Remarks

Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function to obtain a unique message for inter-application communication.

If the specified window was created by the calling thread, the window procedure is called immediately as a subroutine. If the specified window was created by a different thread, Windows switches to that thread and calls the appropriate window procedure. Messages sent between threads are processed only when the receiving thread executes message retrieval code. The sending thread is blocked until the receiving thread processes the message.

See Also

InSendMessage, PostMessage, RegisterWindowMessage, SendDlgItemMessage


SendMessageCallback

The SendMessageCallback function sends the specified message to a window or windows. The function calls the window procedure for the specified window and returns immediately. After the window procedure processes the message, the system calls the specified callback function, passing the result of the message processing and an application-defined value to the callback function.

BOOL SendMessageCallback(

HWND hWnd,	// handle of destination window
UINT Msg,	// message to send
WPARAM wParam,	// first message parameter
LPARAM lParam,	// second message parameter
SENDASYNCPROC lpResultCallBack,	// function to receive message value
DWORD dwData	// value to pass to callback function
);
Parameters

hWnd

Identifies the window whose window procedure will receive the message. If this parameter is HWND_BROADCAST, the message is sent to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent to child windows.

Msg

Specifies the message to be sent.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

lpResultCallBack

Points to a callback function that the system calls after the window procedure processes the message. See SendAsyncProc for information on suitable callback functions.

If hWnd is HWND_BROADCAST, the operating system calls the SendAsyncProc callback function once for each top-level window.

dwData

Specifies an application-defined value to be sent to the callback function pointed to by the lpfnResultCallBack parameter.

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.

Remarks

If you send a message in the range below WM_USER to the asynchronous message functions (PostMessage, SendNotifyMessage, and SendMessageCallback), make sure that the message parameters do not include pointers. Otherwise, the functions will return before the receiving thread has had a chance to process the message and the sender will free the memory before it is used.

Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function to obtain a unique message for inter-application communication.

The callback function is called only when the thread that called SendMessageCallback also calls GetMessage, PeekMessage, or WaitMessage.

See Also

PostMessage, RegisterWindowMessage, SendAsyncProc, SendMessageCallback, SendNotifyMessage


SendMessageTimeout

The SendMessageTimeout function sends the specified message to a window or windows. The function calls the window procedure for the specified window and, if the specified window belongs to a different thread, does not return until the window procedure has processed the message or the specified time-out period has elapsed. If the window receiving the message belongs to the same queue as the current thread, the window procedure is called directly — the time-out value is ignored.

LRESULT SendMessageTimeout(

HWND hWnd,	// handle of destination window
UINT Msg,	// message to send
WPARAM wParam,	// first message parameter
LPARAM lParam,	// second message parameter
UINT fuFlags,	// how to send the message
UINT uTimeout,	// time-out duration
LPDWORD lpdwResult	// return value for synchronous call
);
Parameters

hWnd

Identifies the window whose window procedure will receive the message. If this parameter is HWND_TOPMOST, the message is sent to all top-level windows in the system, including disabled or invisible unowned windows.

Msg

Specifies the message to be sent.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

fuFlags

Specifies how to send the message. This parameter can be a combination of the following values:

Value	Meaning
SMTO_ABORTIFHUNG	Returns without waiting for the time-out period to elapse if the receiving process appears to be in a “hung” state.
SMTO_BLOCK	Prevents the calling thread from processing any other requests until the function returns.
SMTO_NORMAL	The calling thread is not prevented from processing other requests while waiting for the function to return.
uTimeout

Specifies the duration, in milliseconds, of the time-out period.

lpdwResult

Specifies the result of the message processing and depends on the message sent.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

See Also

InSendMessage, PostMessage, SendDlgItemMessage, SendMessage, SendMessageCallback, SendNotifyMessage


SendNotifyMessage

The SendNotifyMessage function sends the specified message to a window. If the window was created by the calling thread, SendNotifyMessage calls the window procedure for the window and does not return until the window procedure has processed the message. If the window was created by a different thread, SendNotifyMessage passes the message to the window procedure and returns immediately; it does not wait for the window procedure to finish processing the message.

BOOL SendNotifyMessage(

HWND hWnd,	// handle of destination window
UINT Msg,	// message to send
WPARAM wParam,	// first message parameter
LPARAM lParam	// second message parameter
);
Parameters

hWnd

Identifies the window whose window procedure will receive the message. If this parameter is HWND_BROADCAST, the message is sent to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent to child windows.

Msg

Specifies the message to be sent.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

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.

Remarks

If you send a message in the range below WM_USER to the asynchronous message functions (PostMessage, SendNotifyMessage, and SendMessageCallback), make sure that the message parameters do not include pointers. Otherwise, the functions will return before the receiving thread has had a chance to process the message and the sender will free the memory before it is used.

Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function to obtain a unique message for inter-application communication.

See Also

PostMessage, PostThreadMessage, RegisterWindowMessage, SendMessage SendMessageCallback, SendNotifyMessage


ServiceMain

A ServiceMain function is a function that a service process specifies as the entry point function of a particular service. The function can have any application-defined name.

VOID WINAPI ServiceMain(

DWORD dwArgc,	// number of arguments
LPTSTR *lpszArgv	// address of array of argument string pointers
);
Parameters

dwArgc

Specifies the number of arguments in the lpszArgv array.

lpszArgv

Points to an array of pointers that point to null-terminated argument strings. The first argument in the array is the name of the service, and subsequent arguments are any strings passed to the service by the process that called the StartService function to start the service.

Return Values

This function does not return a value.

Remarks

A service process can start one or more services. For each service that it can start, a service process has a SERVICE_TABLE_ENTRY structure that specifies the service name and a pointer to the ServiceMain function for that service.

When the service control manager receives a request to start a service, it starts the service process (if it is not already running). The main thread of the service process calls the StartServiceCtrlDispatcher function with a pointer to an array of SERVICE_TABLE_ENTRY structures. Then the service control manager sends a start request to the service control dispatcher for this service process. The service control dispatcher creates a new thread to execute the ServiceMain function of the service being started.

This function should immediately call the RegisterServiceCtrlHandler function to specify a Handler function to handle control requests. Next, it should call the SetServiceStatus function to send status information to the service control manager. After these calls, the function completes the initialization tasks of the service, and then it waits for the service to terminate.

A ServiceMain function does not return until the service is ready to terminate.

See Also

Handler, RegisterServiceCtrlHandler, SetServiceStatus, SERVICE_TABLE_ENTRY, StartServiceCtrlDispatcher


SetAbortProc

The SetAbortProc function sets the application-defined abort function that allows a print job to be canceled during spooling. This function replaces the SETABORTPROC printer escape.

int SetAbortProc(

HDC hdc,	// handle of device context
ABORTPROC lpAbortProc	// address of abort function
);
Parameters

hdc

Identifies the device context for the print job.

lpAbortProc

Points to the application-defined abort function. For more information about the callback function, see the AbortProc callback function.

Return Values

If the function succeeds, the return value is greater than zero.

If the function fails, the return value is SP_ERROR. To get extended error information, call GetLastError.

See Also

AbortDoc, AbortProc


SetAclInformation

The SetAclInformation function sets information about an access-control list (ACL).

BOOL SetAclInformation(

PACL pAcl,	// address of access-control list
LPVOID pAclInformation,	// address of ACL information
DWORD nAclInformationLength,	// size of ACL information
ACL_INFORMATION_CLASS dwAclInformationClass	// specifies class of requested info
);
Parameters

pAcl

Points to an ACL structure. The function sets information in this ACL.

pAclInformation

Points to a buffer containing the information to be set. For the current version of Windows NT, this must be an ACL_REVISION_INFORMATION structure.

nAclInformationLength

Specifies the size, in bytes, of the buffer pointed to by the pAclInfo parameter.

dwAclInformationClass

Specifies an ACL_INFORMATION_CLASS enumerated type that gives the class of information requested.

Currently, this parameter can be AclRevisionInformation. This means that the buffer pointed to by the pAclInformation parameter contains an ACL_REVISION_INFORMATION structure.

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.

See Also

ACL, ACL_INFORMATION_CLASS, ACL_REVISION_INFORMATION, GetAclInformation, InitializeAcl, IsValidAcl


SetActiveWindow

The SetActiveWindow function activates a window.

HWND SetActiveWindow(

HWND hWnd	// handle of window to activate
);
Parameters

hWnd

Identifies the top-level window to be activated.

Return Values

If the function succeeds, the return value is the handle of the window that was previously active.

Remarks

The SetActiveWindow function activates a window, but not if the application is in the background. The window will be brought into the foreground (top of Z order) if the application is in the foreground when it sets the activation.

If the window identified by the hWnd parameter was created by the calling thread, the active window status of the calling thread is set to hWnd. Otherwise, the active window status of the calling thread is set to NULL.

The SetForegroundWindow window function, on the other hand, activates a window and forces it into the foreground. An application should only call SetForegroundWindow if it needs to display critical errors or information that needs the user’s immediate attention .

See Also

GetActiveWindow, SetForegroundWindow, WM_ACTIVATE


SetArcDirection

The SetArcDirection sets the drawing direction to be used for arc and rectangle functions.

int SetArcDirection(

HDC hdc,	// identifies the device context
int ArcDirection	// specifies the new arc direction
);
Parameters

hdc

Identifies the device context.

ArcDirection

Specifies the new arc direction. This parameter can be one of the following values:

Value	Meaning
AD_COUNTERCLOCKWISE	Figures drawn counterclockwise.
AD_CLOCKWISE	Figures drawn clockwise.
Return Values

If the function succeeds, the return value specifies the old arc direction.

If the function fails, the return value is zero.

Remarks

The default direction is counterclockwise.

The SetArcDirection function specifies the direction in which the following functions draw:

Arc	ArcTo
Chord	Ellipse
Pie	Rectangle
RoundRect


SetBitmapBits

The SetBitmapBits function sets the bits of color data for a bitmap to the specified values.

The SetBitmapBits function is included only for compatibility with earlier versions of Windows. For Win32-based applications, use the SetDIBits function.

LONG SetBitmapBits(

HBITMAP hbmp,	// handle of bitmap
DWORD cBytes,	// number of bytes in bitmap array
CONST VOID * lpBits	// address of array with bitmap bits
);
Parameters

hbmp

Identifies the bitmap to be set.

cBytes

Specifies the number of bytes pointed to by the lpBits parameter.

lpBits

Points to an array of bytes that contain color data for the specified bitmap.

Return Values

If the function succeeds, the return value is the number of bytes used in setting the bitmap bits.

If the function fails, the return value is zero.

Remarks

The array identified by lpBits must be WORD aligned.

See Also

GetBitmapBits, SetDIBits


SetBitmapDimensionEx

The SetBitmapDimensionEx function assigns preferred dimensions to a bitmap. These dimensions can be used by applications; however, they are not used by Windows.

BOOL SetBitmapDimensionEx(

HBITMAP hBitmap,	// handle of bitmap
int nWidth,	// bitmap width in .01-mm units
int nHeight,	// bitmap height in .01-mm units
LPSIZE lpSize	// address of structure for original dimensions
);
Parameters

hBitmap

Identifies the bitmap.  The bitmap cannot be a DIB section bitmap.

nWidth

Specifies the width, in 0.1-millimeter units, of the bitmap.

nHeight

Specifies the height, in 0.1-millimeter units, of the bitmap.

lpSize

Points to a SIZE structure to receive the previous dimensions of the bitmap. This pointer can be NULL.

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.

Remarks

An application can retrieve the dimensions assigned to a bitmap with the SetBitmapDimensionEx function by calling the GetBitmapDimensionEx function.

The bitmap identified by hBitmap cannot be a dib section, which is a bitmap created by the CreateDIBSection function. If the bitmap is a dib section, the SetBitmapDimensionEx function fails.

See Also

CreateDIBSection, GetBitmapDimensionEx, SIZE


SetBkColor

The SetBkColor function sets the current background color to the specified color value, or to the nearest physical color if the device cannot represent the specified color value.

COLORREF SetBkColor(

HDC hdc,	// handle of device context
COLORREF crColor	// background color value
);
Parameters

hdc

Identifies the device context.

crColor

Specifies the new background color.

Return Values

If the function succeeds, the return value specifies the previous background color as a COLORREF value.

If the function fails, the return value is CLR_INVALID.

Remarks

This function fills the gaps between styled lines drawn using a pen created by the CreatePen function; it does not fill the gaps between styled lines drawn using a pen created by the ExtCreatePen function.

If the background mode is OPAQUE, the background color is used to fill gaps between styled lines, gaps between hatched lines in brushes, and character cells. The background color is also used when converting bitmaps from color to monochrome and vice versa.

See Also

CreatePen, ExtCreatePen, GetBKColor, GetBkMode, SetBkMode, COLORREF


SetBkMode

The SetBkMode function sets the background mix mode of the specified device context. The background mix mode is used with text, hatched brushes, and pen styles that are not solid lines.

int SetBkMode(

HDC hdc,	// handle of device context
int iBkMode	// flag specifying background mode
);
Parameters

hdc

Identifies the device context.

iBkMode

Specifies the background mode. This parameter can be either of the following values:

Value	Description
OPAQUE	Background is filled with the current background color before the text, hatched brush, or pen is drawn.
TRANSPARENT	Background remains untouched.
Return Values

If the function succeeds, the return value specifies the previous background mode.

If the function fails, the return value is zero.

Remarks

The SetBkMode function affects the line styles for lines drawn using a pen created by the CreatePen function. SetBkMode does not affect lines drawn using a pen created by the ExtCreatePen function.

The iBkMode parameter can also be set to driver-specific values. GDI passes such values to the device driver and otherwise ignores them.

See Also

CreatePen, ExtCreatePen, GetBkMode


SetBoundsRect

The SetBoundsRect function controls the accumulation of bounding rectangle information for the specified device context. Windows can maintain a bounding rectangle for all drawing operations. An application can examine and set this rectangle. The drawing boundaries are useful for invalidating bitmap caches.

UINT SetBoundsRect(

HDC hdc,	// handle of device context
CONST RECT *lprcBounds,	// address of rectangle coordinates
UINT flags	// controls rectangle combination
);
Parameters

hdc

Identifies the device context for which to accumulate bounding rectangles.

lprcBounds

Points to a RECT structure used to set the bounding rectangle. Rectangle dimensions are in logical coordinates. This parameter can be NULL.

flags

Specifies how the new rectangle will be combined with the accumulated rectangle. This parameter can be a combination of the following values:

Value	Description
DCB_ACCUMULATE	Adds the rectangle specified by the lprcBounds parameter to the bounding rectangle (using a rectangle union operation). Using both DCB_RESET and DCB_ACCUMULATE sets the bounding rectangle to the rectangle specified by the lprcBounds parameter.
DCB_DISABLE	Turns off boundary accumulation.
DCB_ENABLE	Turns on boundary accumulation, which is disabled by default.
DCB_RESET	Clears the bounding rectangle.
Return Values

If the function succeeds, the return value specifies the previous state of the bounding rectangle. This state can be a combination of the following values:

Value	Meaning
DCB_DISABLE	Boundary accumulation is off.
DCB_ENABLE	Boundary accumulation is on. DCB_ENABLE and DCB_DISABLE are mutually exclusive.
DCB_RESET	Bounding rectangle is empty.
DCB_SET	Bounding rectangle is not empty. DCB_SET and DCB_RESET are mutually exclusive.
Remarks

The DCB_SET value is a combination of the bit values DCB_ACCUMULATE and DCB_RESET. Applications that check the DCB_RESET bit to determine whether the bounding rectangle is empty must also check the DCB_ACCUMULATE bit. The bounding rectangle is empty only if the DCB_RESET bit is 1 and the DCB_ACCUMULATE bit is 0.

See Also

GetBoundsRect, RECT


SetBrushOrgEx

The SetBrushOrgEx function sets the brush origin that GDI assigns to the next brush an application selects into the specified device context.

BOOL SetBrushOrgEx(

HDC hdc,	// handle of device context
int nXOrg,	// x-coordinate of new origin
int nYOrg,	// y-coordinate of new origin
LPPOINT lppt	// points to previous brush origin
);
Parameters

hdc

Identifies the device context.

nXOrg

Specifies the x-coordinate, in device units, of the new brush origin. If this value is greater than the brush width, its value is reduced using the modulus operator (nXOrg mod brush width).

nYOrg

Specifies the y-coordinate, in device units, of the new brush origin. If this value is greater than the brush height, its value is reduced using the modulus operator (nYOrg mod brush height).

lppt

Points to a POINT structure that receives the previous brush origin.

This parameter can be NULL if the previous brush origin is not required.

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.

Remarks

A brush is a bitmap that the operating system uses to paint the interiors of filled shapes.

The brush origin is a pair of coordinates specifying the location of one pixel in the bitmap. The default brush origin coordinates are (0,0). For horizontal coordinates, the value 0 corresponds to the leftmost column of pixels; the width corresponds to the rightmost column. For vertical coordinates, the value 0 corresponds to the uppermost row of pixels; the height corresponds to the lowermost row.

The operating system automatically tracks the origin of all window-managed device contexts and adjusts their brushes as necessary to maintain an alignment of patterns on the surface. The brush origin that is set with this call is relative to the upper-left corner of the client area.

An application should call SetBrushOrgEx after setting the bitmap stretching mode to HALFTONE via SetStretchBltMode. This must be done to avoid brush misalignment.

Windows NT: The operating system automatically tracks the origin of all window-managed device contexts and adjusts their brushes as necessary to maintain an alignment of patterns on the surface.

Windows 95: Automatic tracking of the brush origin is not supported. Applications must use the UnrealizeObject, SetBrushOrgEx, and SelectObject functions to align the brush before using it.

See Also

GetBrushOrgEx, POINT, SelectObject, SetStretchBltMode, UnrealizeObject


SetCapture

The SetCapture function sets the mouse capture to the specified window belonging to the current thread. Once a window has captured the mouse, all mouse input is directed to that window, regardless of whether the cursor is within the borders of that window. Only one window at a time can capture the mouse.

If the mouse cursor is over a window created by another thread, the system will direct mouse input to the specified window only if a mouse button is down.

HWND SetCapture(

HWND hWnd	// handle of window to receive mouse capture
);
Parameters

hWnd

Identifies the window in the current thread that is to capture the mouse.

Return Values

If the function succeeds, the return value is the handle of the window that had previously captured the mouse. If there is no such window, the return value is NULL.

Remarks

Only the foreground window can capture the mouse. When a background window attempts to do so, the window receives messages only for mouse events that occur when the cursor hot spot is within the visible portion of the window. Also, even if the foreground window has captured the mouse, the user can still click another window, bringing it to the foreground.

When the window no longer requires all mouse input, the thread that created the window should call the ReleaseCapture function to release the mouse.

This function cannot be used to capture mouse input meant for another process.

Windows 95: Calling this function causes the window that is losing the mouse capture to receive a WM_CAPTURECHANGED message.

See Also

GetCapture, ReleaseCapture, WM_CAPTURECHANGED


SetCaretBlinkTime

The SetCaretBlinkTime function sets the caret blink time to the specified number of milliseconds. The blink time is the elapsed time, in milliseconds, required to invert the caret’s pixels.

BOOL SetCaretBlinkTime(

UINT uMSeconds	// blink time, in milliseconds
);
Parameters

uMSeconds

Specifies the new blink time, in milliseconds.

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.

Remarks

The user can set the blink time using the Control Panel. Applications should respect the setting that the user has chosen. The SetCaretBlinkTime function should only be used by application that allow the user to set the blink time, such as a Control Panel applet.

If you change the blink time, subsequently activated applications will use the modified blink time, even if you restore the previous blink time when you lose the keyboard focus or become inactive. This is due to the multithreaded environment, where deactivation of your application is not synchronized with the activation of another application. This feature allows the system to activate another application even if the current application is hung.

See Also

GetCaretBlinkTime


SetCaretPos

The SetCaretPos function moves the caret to the specified coordinates. If the window that owns the caret was created with the CS_OWNDC class style, then the specified coordinates are subject to the mapping mode of the device context associated with that window.

BOOL SetCaretPos(

int X,	// horizontal position
int Y	// vertical position
);
Parameters

X

Specifies the new x-coordinate of the caret.

Y

Specifies the new y-coordinate of the caret.

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.

Remarks

SetCaretPos moves the caret whether or not the caret is hidden.

The caret is a shared resource; there is only one caret in the system. A window can set the caret position only if it owns the caret.

See Also

GetCaretPos, HideCaret, ShowCaret


SetClassLong

The SetClassLong function replaces the specified 32-bit (long) value at the specified offset into the extra class memory or the WNDCLASS structure for the class to which the specified window belongs.

DWORD SetClassLong(

HWND hWnd,	// handle of window
int nIndex,	// index of value to change
LONG dwNewLong	// new value
);
Parameters

hWnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the 32-bit value to replace. To set a 32-bit value in the extra class memory, specify the positive, zero-based byte offset of the value to be set. Valid values are in the range zero through the number of bytes of extra class memory, minus four; for example, if you specified 12 or more bytes of extra class memory, a value of 8 would be an index to the third 32-bit integer. To set any other value from the WNDCLASS structure, specify one of the following values:

Value	Action
GCL_CBCLSEXTRA	Sets the size, in bytes, of the extra memory associated with the class. Setting this value does not change the number of extra bytes already allocated.
GCL_CBWNDEXTRA	Sets the size, in bytes, of the extra window memory associated with each window in the class. Setting this value does not change the number of extra bytes already allocated. For information on how to access this memory, see SetWindowLong and SetWindowWord.
GCL_HBRBACKGROUND	Replaces the handle of the background brush associated with the class.
GCL_HCURSOR	Replaces the handle of the cursor associated with the class.
GCL_HICON	Replaces the handle of the icon associated with the class.
GCL_HMODULE	Replaces the handle of the module that registered the class.
GCL_MENUNAME	Replaces the address of the menu name string. The string identifies the menu resource associated with the class.
GCL_STYLE	Replaces the window-class style bits.
GCL_WNDPROC	Replaces the address of the window procedure associated with the class.
dwNewLong

Specifies the replacement value.

Return Values

If the function succeeds, the return value is the previous value of the specified 32-bit integer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If you use the SetClassLong function and the GCL_WNDPROC index to replace the window procedure, the window procedure must conform to the guidelines specified in the description of the WindowProc callback function.

Calling SetClassLong with the GCL_WNDPROC index creates a subclass of the window class that affects all windows subsequently created with the class. An application should not subclass a window created by another process.

Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASS structure used with the RegisterClass function.

Use the SetClassLong function with care. For example, it is possible to change the background color for a class by using SetClassLong, but this change does not immediately repaint all windows belonging to the class.

See Also

GetClassLong, GetClassWord, RegisterClass, SetClassWord, SetWindowLong, SetWindowWord, WindowProc, WNDCLASS


SetClassWord

The SetClassWord function replaces the 16-bit (word) value at the specified offset into the extra class memory for the window class to which the specified window belongs.

WORD SetClassWord(

HWND hWnd,	// handle of window
int nIndex,	// index of value to change
WORD wNewWord	// new value
);
Parameters

hWnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the zero-based byte offset of the value to be replaced. Valid values are in the range zero through the number of bytes of class memory minus two; for example, if you specified 10 or more bytes of extra class memory, a value of 8 would be an index to the fifth 16-bit integer.

wNewWord

Specifies the replacement value.

Return Values

If the function succeeds, the return value is the previous value of the specified 16-bit integer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASS structure used with the RegisterClass function.

The GCW_ values are obsolete in the Win32 API. You must use the SetClassLong function to set the class values previously set by using the GCW_ values with the SetClassWord function.

See Also

GetClassLong, GetClassWord, RegisterClass, SetClassLong, WNDCLASS


SetClipboardData

The SetClipboardData function places data on the clipboard in a specified clipboard format. The window must be the current clipboard owner, and the application must have called the OpenClipboard function. (When responding to the WM_RENDERFORMAT and WM_RENDERALLFORMATS messages, the clipboard owner must not call OpenClipboard before calling SetClipboardData.)

HANDLE SetClipboardData(

UINT uFormat,	// clipboard format
HANDLE hMem	// data handle
);
Parameters

uFormat

Specifies a clipboard format. This parameter can be a registered format or any of the standard clipboard formats listed in the following Remarks section. For information about registered clipboard formats, see the RegisterClipboardFormat function.

hMem

Identifies the data in the specified format. This parameter can be NULL, indicating that the window provides data in the specified clipboard format (renders the format) upon request. If a window delays rendering, it must process the WM_RENDERFORMAT and WM_RENDERALLFORMATS messages.

Once SetClipboardData is called, the system owns the object identified by the hMem parameter. The application can read the data, but must not free the handle or leave it locked. If the hMem parameter identifies a memory object, the object must have been allocated using the GlobalAlloc function with the GMEM_MOVEABLE and GMEM_DDESHARE flags.

Return Values

If the function succeeds, the return value is the handle of the data.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The uFormat parameter can identify a registered clipboard format, or it can be one of the following values:

Value	Meaning
CF_BITMAP	A handle to a bitmap (HBITMAP).
CF_DIB	A memory object containing a BITMAPINFO structure followed by the bitmap bits.
CF_DIF	Software Arts’ Data Interchange Format.
CF_DSPBITMAP	Bitmap display format associated with a private format. The hMem parameter must be a handle of data that can be displayed in bitmap format in lieu of the privately formatted data.
CF_DSPENHMETAFILE	Enhanced metafile display format associated with a private format. The hMem parameter must be a handle of data that can be displayed in enhanced metafile format in lieu of the privately formatted data.
CF_DSPMETAFILEPICT	Metafile-picture display format associated with a private format. The hMem parameter must be a handle of data that can be displayed in metafile-picture format in lieu of the privately formatted data.
CF_DSPTEXT	Text display format associated with a private format. The hMem parameter must be a handle of data that can be displayed in text format in lieu of the privately formatted data.
CF_ENHMETAFILE	A handle of an enhanced metafile (HENHMETAFILE).
CF_GDIOBJFIRST through CF_GDIOBJLAST	Range of integer values for application-defined GDI object clipboard formats. Handles associated with clipboard formats in this range are not automatically deleted using the GlobalFree function when the clipboard is emptied. Also, when using values in this range, the hMem parameter is not a handle to a GDI object, but is a handle allocated by the GlobalAlloc function with the GMEM_DDESHARE and GMEM_MOVEABLE flags.
CF_HDROP	A handle of type HDROP that identifies a list of files. An application can retrieve information about the files by passing the handle to the DragQueryFile functions.
CF_LOCALE	The data is a handle to the locale identifier associated with text in the clipboard. When you close the clipboard, if it contains CF_TEXT data but no CF_LOCALE data, the system automatically sets the CF_LOCALE format to the current input locale. You can use the CF_LOCALE format to associate a different locale with the clipboard text. An application that pastes text from the clipboard can retrieve this format to determine which character set was used to generate the text. Note that the clipboard does not support plain text in multiple character sets. To achieve this, use a fomatted text data type such as RTF instead. Windows NT: The system uses the code page associated with CF_LOCALE to implicitly convert from CF_TEXT to CF_UNICODETEXT. Therefore, the correct code page table is used for the conversion.
CF_METAFILEPICT	Handle of a metafile picture format as defined by the METAFILEPICT structure. When passing a CF_METAFILEPICT handle by means of dynamic data exchange (DDE), the application responsible for deleting hMem should also free the metafile referred to by the CF_METAFILEPICT handle.
CF_OEMTEXT	Text format containing characters in the OEM character set. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data.
CF_OWNERDISPLAY	Owner-display format. The clipboard owner must display and update the clipboard viewer window, and receive the WM_ASKCBFORMATNAME, WM_HSCROLLCLIPBOARD, WM_PAINTCLIPBOARD, WM_SIZECLIPBOARD, and WM_VSCROLLCLIPBOARD messages. The hMem parameter must be NULL.
CF_PALETTE	Handle of a color palette. Whenever an application places data in the clipboard that depends on or assumes a color palette, it should place the palette on the clipboard as well.
	If the clipboard contains data in the CF_PALETTE (logical color palette) format, the application should use the SelectPalette and RealizePalette functions to realize (compare) any other data in the clipboard against that logical palette.
	When displaying clipboard data, Windows clipboard always uses as its current palette any object on the clipboard that is in the CF_PALETTE format.
CF_PENDATA	Data for the pen extensions to the Microsoft Windows for Pen Computing.
CF_PRIVATEFIRST through CF_PRIVATELAST	Range of integer values for private clipboard formats. Handles associated with private clipboard formats are not freed automatically; the clipboard owner must free such handles, typically in response to the WM_DESTROYCLIPBOARD message.
CF_RIFF	Represents audio data more complex than can be represented in a CF_WAVE standard wave format.
CF_SYLK	Microsoft Symbolic Link (SYLK) format.
CF_TEXT	Text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data. Use this format for ANSI text.
CF_WAVE	Represents audio data in one of the standard wave formats, such as 11 kHz or 22 kHz pulse code modulation (PCM).
CF_TIFF	Tagged-image file format.
CF_UNICODETEXT	Windows NT only: Unicode text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data.
The operating system performs implicit data format conversions between certain clipboard formats when an application calls the GetClipboardData function. For example, if the CF_OEMTEXT format is on the clipboard, a window can retrieve data in the CF_TEXT format. The format on the clipboard is converted to the requested format on demand. The following table shows the clipboard data type conversions that are available. Note that some of these automatic type conversions are not available on all platforms.

Clipboard Format	Conversion Format	Platform Support
CF_BITMAP	CF_DIB	Windows NT, Windows 95
CF_DIB	CF_BITMAP	Windows NT, Windows 95
CF_DIB	CF_PALETTE	Windows NT, Windows 95
CF_ENHMETAFILE	CF_METAFILEPICT	Windows NT, Windows 95
CF_METAFILEPICT	CF_ENHMETAFILE	Windows NT, Windows 95
CF_OEMTEXT	CF_TEXT	Windows NT, Windows 95
CF_OEMTEXT	CF_UNICODETEXT	Windows NT
CF_TEXT	CF_OEMTEXT	Windows NT, Windows 95
CF_TEXT	CF_UNICODETEXT	Windows NT
CF_UNICODETEXT	CF_OEMTEXT	Windows NT
CF_UNICODETEXT	CF_TEXT	Windows NT
If the operating system provides an automatic type conversion for a particular clipboard format, there is no advantage to placing the conversion format(s) on the clipboard.

When copying bitmaps, it is best to place only the CF_DIB format on the clipboard. This is because the colors in a device-dependent bitmap (CF_BITMAP) are relative to the system palette, which may change before the bitmap is pasted. If only the CF_DIB format is on the clipboard and a window requests the CF_BITMAP format, the system renders the device-dependent bitmap using the current palette at that time.

If you place the CF_BITMAP format on the clipboard (and not CF_DIB), the system renders the CF_DIB clipboard format as soon as the clipboard is closed. This ensures that the correct palette is used to generate the device-independent bitmap (DIB). Conversions between other clipboard formats occur upon demand.

Windows platforms support two clipboard formats for metafiles: CF_ENHMETAFILE and CF_METAFILEPICT. Specify CF_ENHMETAFILE for enhanced metafiles and CF_METAFILEPICT for Windows metafiles.

See Also

BITMAPINFO, GetClipboardData, GlobalAlloc, GlobalFree, METAFILEPICT, OpenClipboard, RealizePalette, RegisterClipboardFormat, SelectPalette, WM_ASKCBFORMATNAME, WM_DESTROYCLIPBOARD, WM_HSCROLLCLIPBOARD, WM_PAINTCLIPBOARD, WM_RENDERFORMAT, WM_RENDERALLFORMATS, WM_SIZECLIPBOARD, WM_VSCROLLCLIPBOARD


SetClipboardViewer

The SetClipboardViewer function adds the specified window to the chain of clipboard viewers. Clipboard viewer windows receive a WM_DRAWCLIPBOARD message whenever the content of the clipboard changes.

HWND SetClipboardViewer(

HWND hWndNewViewer	// handle of clipboard viewer window
);
Parameters

hWndNewViewer

Identifies the window to be added to the clipboard chain.

Return Values

If the function succeeds, the return value identifies the next window in the clipboard viewer chain. If an error occurs or there are no other windows in the clipboard viewer chain, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The windows that are part of the clipboard viewer chain, called clipboard viewer windows, must process the clipboard messages WM_CHANGECBCHAIN and WM_DRAWCLIPBOARD. Each clipboard viewer window calls the SendMessage function to pass these messages to the next window in the clipboard viewer chain.

A clipboard viewer window must eventually remove itself from the clipboard viewer chain by calling the ChangeClipboardChain function — for example, in response to the WM_DESTROY message.

See Also

ChangeClipboardChain, GetClipboardViewer, SendMessage, WM_CHANGECBCHAIN, WM_DRAWCLIPBOARD


SetColorAdjustment

The SetColorAdjustment function sets the color adjustment values for a device context using the specified values.

BOOL SetColorAdjustment(

HDC hdc,	// handle to device context
CONST COLORADJUSTMENT *lpca	// pointer to COLORADJUSTMENT structure
);
Parameters

hdc

Identifies the device context.

lpca

Points to a COLORADJUSTMENT structure containing the color adjustment values.

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.

Remarks

The color adjustment values are used to adjust the input color of the source bitmap for calls to the StretchBlt and StretchDIBits functions when HALFTONE mode is set.

See Also

GetColorAdjustment, StretchBlt, StretchDIBits, SetStretchBltMode, COLORADJUSTMENT


SetColorSpace

The SetColorSpace function sets the color space for the specified device context, defining the endpoints of the logical RGB space in CIE XYZ space.

BOOL SetColorSpace(

HDC hdc,	// handle to the device context
HCOLORSPACE hColorSpace	// handle to the logical color space
);
Parameters

hdc

Handle to the device context.

hColorSpace

Handle to the logical color space.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

GetColorSpace, RGB


SetCommBreak

The SetCommBreak function suspends character transmission for a specified communications device and places the transmission line in a break state until the ClearCommBreak function is called.

BOOL SetCommBreak(

HANDLE hFile	// handle of communications device
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

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.

Remarks

The SetCommBreak function does not flush data that has not been transmitted.

See Also

ClearCommBreak, CreateFile


SetCommConfig [Now Supported on Windows NT]
SetCommConfig

[Now Supported on Windows NT]

The SetCommConfig function sets the current configuration of a communications device.

BOOL SetCommConfig(

HANDLE hCommDev,	// handle of communications device
LPCOMMCONFIG lpCC,	// address of comm. configuration services
DWORD dwSize	// size of structure
);
Parameters

hCommDev

Identifies the open communications device.

lpCC

Points to a COMMCONFIG structure.

dwSize

Specifies the size, in bytes, of the structure pointed to by lpCC.

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.

See Also

GetCommConfig, COMMCONFIG


SetCommMask

The SetCommMask function specifies a set of events to be monitored for a communications device.

BOOL SetCommMask(

HANDLE hFile,	// handle of communications device
DWORD dwEvtMask	// mask that identifies enabled events
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

dwEvtMask

Specifies the events to be enabled. A value of zero disables all events. This parameter can be a combination of the following values:

Value	Meaning
EV_BREAK	A break was detected on input.
EV_CTS	The CTS (clear-to-send) signal changed state.
EV_DSR	The DSR (data-set-ready) signal changed state.
EV_ERR	A line-status error occurred. Line-status errors are CE_FRAME, CE_OVERRUN, and CE_RXPARITY.
EV_RING	A ring indicator was detected.
EV_RLSD	The RLSD (receive-line-signal-detect) signal changed state.
EV_RXCHAR	A character was received and placed in the input buffer.
EV_RXFLAG	The event character was received and placed in the input buffer. The event character is specified in the device’s DCB structure, which is applied to a serial port by using the SetCommState function.
EV_TXEMPTY	The last character in the output buffer was sent.
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.

Remarks

The SetCommMask function specifies the set of events that can be monitored for a particular communications resource. A handle to the communications resource can be specified in a call to the WaitCommEvent function, which waits for one of the events to occur. To get the current event mask of a communications resource, use the GetCommMask function.

If SetCommMask is called for a communications resource while an overlapped wait is pending for that resource, WaitCommEvent returns an error.

See Also

CreateFile, DCB, GetCommMask, SetCommState, WaitCommEvent


SetCommState

The SetCommState function configures a communications device according to the specifications in a device-control block (a DCB structure). The function reinitializes all hardware and control settings, but it does not empty output or input queues.

BOOL SetCommState(

HANDLE hFile,	// handle of communications device
LPDCB lpDCB	// address of device-control block structure
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

lpDCB

Points to a DCB structure containing the configuration information for the specified communications device.

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.

Remarks

The SetCommState function uses a DCB structure to specify the desired configuration. The GetCommState function returns the current configuration.

To set only a few members of the DCB structure, you should modify a DCB structure that has been filled in by a call to GetCommState. This ensures that the other members of the DCB structure have appropriate values.

The SetCommState function fails if the XonChar member of the DCB structure is equal to the XoffChar member.

When SetCommState is used to configure the 8250, the following restrictions apply to the values for the DCB structure’s ByteSize and StopBits members:

•	The number of data bits must be 5 to 8 bits.

•	The use of 5 data bits with 2 stop bits is an invalid combination, as are 6, 7, or 8 data bits with 1.5 stop bits.

See Also

BuildCommDCB, CreateFile, DCB, GetCommState


SetCommTimeouts

The SetCommTimeouts function sets the time-out parameters for all read and write operations on a specified communications device.

BOOL SetCommTimeouts(

HANDLE hFile,	// handle of communications device
LPCOMMTIMEOUTS lpCommTimeouts	// address of communications time-out structure
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

lpCommTimeouts

Points to a COMMTIMEOUTS structure that contains the new time-out values.

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.

See Also

COMMTIMEOUTS, GetCommTimeouts, ReadFile, ReadFileEx, WriteFile, WriteFileEx


SetComputerName

The SetComputerName function sets the computer name to be used the next time the system is restarted.

BOOL SetComputerName(

LPCTSTR lpComputerName	// address of new computer name
);
Parameters

lpComputerName

Points to a null-terminated character string that specifies the name that will be the computer name the next time the computer is started. The name must not be longer than MAX_COMPUTERNAME_LENGTH characters.

Windows 95: If this string contains one or more characters that are outside the standard character set, those characters are coerced into standard characters.

Windows NT: If this string contains one or more characters that are outside the standard character set, SetComputerName returns ERROR_INVALID_PARAMETER. It does not coerce the characters outside the standard set.

The standard character set includes letters, numbers, and the following symbols: ! @ # $ % ^ & ‘ ) ( . - _ { } ~ .

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.

Remarks

Applications using this function must have administrator rights.

See Also

GetComputerName


SetConsoleActiveScreenBuffer

The SetConsoleActiveScreenBuffer function sets the specified screen buffer to be the currently displayed console screen buffer.

BOOL SetConsoleActiveScreenBuffer(

HANDLE hConsoleOutput	// handle of console screen buffer
);
Parameters

hConsoleOutput

Identifies a console screen buffer.

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.

Remarks

A console can have multiple screen buffers. SetConsoleActiveScreenBuffer determines which one is displayed. You can write to an inactive screen buffer and then use SetConsoleActiveScreenBuffer to display the buffer’s contents.

See Also

CreateConsoleScreenBuffer


SetConsoleCP

The SetConsoleCP function sets the input code page used by the console associated with the calling process. A console uses its input code page to translate keyboard input into the corresponding character value.

BOOL SetConsoleCP(

UINT wCodePageID	// code page to set
);
Parameters

wCodePageID

Specifies the identifier of the code page to set. The identifiers of the code pages available on the local computer are stored in the registry under the following key.

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Nls\CodePage

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.

Remarks

A code page maps 256 character codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages.

To determine a console’s current input code page, use the GetConsoleCP function. To set and retrieve a console’s output code page, use the SetConsoleOutputCP and GetConsoleOutputCP functions.

See Also

GetConsoleCP, GetConsoleOutputCP, SetConsoleOutputCP


SetConsoleCtrlHandler

The SetConsoleCtrlHandler function adds or removes an application-defined HandlerRoutine function from the list of handler functions for the calling process. If no handler function is specified, the function sets an inheritable attribute that determines whether the calling process ignores CTRL+C signals.

BOOL SetConsoleCtrlHandler(

PHANDLER_ROUTINE HandlerRoutine,	// address of handler function
BOOL Add	// handler to add or remove
);
Parameters

HandlerRoutine

Points to the application-defined HandlerRoutine function to add or remove. This parameter can be NULL.

Add

Specifies whether to add or remove the function pointed to by the HandlerRoutine parameter from the handler list. If this parameter is TRUE, the handler is added; if it is FALSE, the handler is removed.

If the HandlerRoutine parameter is NULL, a TRUE value causes the calling process to ignore CTRL+C input, and a FALSE value restores normal processing of CTRL+C input. This attribute of ignoring or processing CTRL+C is inherited by child processes.

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.

Remarks

Each console process has its own list of application-defined HandlerRoutine functions that handle CTRL+C and CTRL+BREAK signals. The handler functions also handle signals generated by the system when the user closes the console, logs off, or shuts down the system. Initially, the handler list for each process contains only a default handler function that calls the ExitProcess function. A console process adds or removes additional handler functions by calling the SetConsoleCtrlHandler function, which does not affect the list of handler functions for other processes. When a console process receives any of the control signals, its handler functions are called on a last-registered, first-called basis until one of the handlers returns TRUE. If none of the handlers returns TRUE, the default handler is called.

For console processes, the CTRL+C and CTRL+BREAK key combinations are typically treated as signals (CTRL_C_EVENT and CTRL_C_BREAK_EVENT). When a console window with the keyboard focus receives CTRL+C or CTRL+BREAK, the signal is typically passed to all processes sharing that console.

CTRL+BREAK is always treated as a signal, but typical CTRL+C behavior can be changed in three ways that prevent the handler functions from being called:

•	The SetConsoleMode function can disable the ENABLE_PROCESSED_INPUT mode for a console’s input buffer, so CTRL+C is reported as keyboard input rather than as a signal.

•	Calling SetConsoleCtrlHandler with the NULL and TRUE arguments causes the calling process to ignore CTRL+C signals. This attribute is inherited by child processes, but it can be enabled or disabled by any process without affecting existing processes.

•	If a console process is being debugged and CTRL+C signals have not been disabled, the kernel generates a DBG_CONTROL_C exception. This exception is raised only for the benefit of the debugger, and an application should never use an exception handler to deal with it. If the debugger handles the exception, an application will not notice the CTRL+C, with one exception: alertable waits will terminate. If the debugger passes the exception on unhandled, CTRL+C is passed to the console process and treated as a signal, as previously discussed.

A console process can use the GenerateConsoleCtrlEvent function to send a CTRL+C or CTRL+BREAK signal to a console process group.

The system generates CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, and CTRL_SHUTDOWN_EVENT signals when the user closes the console, logs off, or shuts down the system so that the process has an opportunity to clean up before termination. Console functions, or any C run-time functions that call console functions, may not work reliably during processing of any of the three signals mentioned previously. The reason is that some or all of the internal console cleanup routines may have been called before executing the process signal handler.

See Also

ExitProcess, GenerateConsoleCtrlEvent, GetConsoleMode, HandlerRoutine, SetConsoleMode


SetConsoleCursorInfo

The SetConsoleCursorInfo function sets the size and visibility of the cursor for the specified console screen buffer.

BOOL SetConsoleCursorInfo(

HANDLE hConsoleOutput,	// handle of console screen buffer
CONST CONSOLE_CURSOR_INFO *lpConsoleCursorInfo	// address of cursor information
);
Parameters

hConsoleOutput

Identifies a console screen buffer. The handle must have GENERIC_WRITE access.

lpConsoleCursorInfo

Points to a CONSOLE_CURSOR_INFO structure containing the new specifications for the screen buffer’s cursor.

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.

Remarks

When a screen buffer’s cursor is visible, its appearance can vary, ranging from completely filling a character cell to showing up as a horizontal line at the bottom of the cell. The dwSize member of the CONSOLE_CURSOR_INFO structure specifies the percentage of a character cell that is filled by the cursor. If this member is less than 1 or greater than 100, SetConsoleCursorInfo fails.

See Also

CONSOLE_CURSOR_INFO, GetConsoleCursorInfo, SetConsoleCursorPosition


SetConsoleCursorPosition

The SetConsoleCursorPosition function sets the cursor position in the specified console screen buffer.

BOOL SetConsoleCursorPosition(

HANDLE hConsoleOutput,	// handle of console screen buffer
COORD dwCursorPosition	// new cursor position coordinates
);
Parameters

hConsoleOutput

Identifies a console screen buffer. The handle must have GENERIC_WRITE access.

dwCursorPosition

Specifies a COORD structure containing the new cursor position. The coordinates are the column and row of a screen buffer character cell. The coordinates must be within the boundaries of the screen buffer.

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.

Remarks

The cursor position determines where characters written by the WriteFile or WriteConsole function, or echoed by the ReadFile or ReadConsole function, are displayed. To determine the current position of the cursor, use the GetConsoleScreenBufferInfo function.

If the new cursor position is not within the boundaries of the screen buffer’s window, the window origin changes to make the cursor visible.

See Also

GetConsoleCursorInfo, GetConsoleScreenBufferInfo, ReadConsole, ReadFile, SetConsoleCursorInfo, WriteConsole, WriteFile


SetConsoleMode

The SetConsoleMode function sets the input mode of a console’s input buffer or the output mode of a console screen buffer.

BOOL SetConsoleMode(

HANDLE hConsoleHandle,	// handle of console input or screen buffer
DWORD dwMode	// input or output mode to set
);
Parameters

hConsoleHandle

Identifies a console input buffer or a screen buffer. The handle must have GENERIC_WRITE access.

dwMode

Specifies the input or output mode to set. If the hConsoleHandle parameter is an input handle, the mode can be a combination of the following values. When a console is created, all input modes except ENABLE_WINDOW_INPUT are enabled by default.

Value	Meaning
ENABLE_LINE_INPUT	The ReadFile or ReadConsole function returns only when a carriage return character is read. If this mode is disabled, the functions return when one or more characters are available.
ENABLE_ECHO_INPUT	Characters read by the ReadFile or ReadConsole function are written to the active screen buffer as they are read. This mode can be used only if the ENABLE_LINE_INPUT mode is also enabled.
ENABLE_PROCESSED_INPUT	CTRL+C is processed by the system and is not placed in the input buffer. If the input buffer is being read by ReadFile or ReadConsole, other control keys are processed by the system and are not returned in the ReadFile or ReadConsole buffer. If the ENABLE_LINE_INPUT mode is also enabled, backspace, carriage return, and linefeed characters are handled by the system.
ENABLE_WINDOW_INPUT	User interactions that change the size of the console screen buffer are reported in the console’s input buffer. Information about these events can be read from the input buffer by applications using the ReadConsoleInput function, but not by those using ReadFile or ReadConsole.
ENABLE_MOUSE_INPUT	If the mouse pointer is within the borders of the console window and the window has the keyboard focus, mouse events generated by mouse movement and button presses are placed in the input buffer. These events are discarded by ReadFile or ReadConsole, even when this mode is enabled.
If the hConsoleHandle parameter is a screen buffer handle, the mode can be a combination of the following values. When a screen buffer is created, both output modes are enabled by default.

Value	Meaning
ENABLE_PROCESSED_OUTPUT	Characters written by the WriteFile or WriteConsole function or echoed by the ReadFile or ReadConsole function are examined for ASCII control sequences and the correct action is performed. Backspace, tab, bell, carriage return, and linefeed characters are processed.
ENABLE_WRAP_AT_EOL_OUTPUT	When writing with WriteFile or WriteConsole or echoing with ReadFile or ReadConsole, the cursor moves to the beginning of the next row when it reaches the end of the current row. This causes the rows displayed in the console window to scroll up automatically when the cursor advances beyond the last row in the window. It also causes the contents of the screen buffer to scroll up (discarding the top row of the screen buffer) when the cursor advances beyond the last row in the screen buffer. If this mode is disabled, the last character in the row is overwritten with any subsequent characters.
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.

Remarks

A console consists of an input buffer and one or more screen buffers. The mode of a console buffer determines how the console behaves during input and output (I/O) operations. One set of flag constants is used with input handles, and another set is used with screen buffer (output) handles. Setting the output modes of one screen buffer does not affect the output modes of other screen buffers.

The ENABLE_LINE_INPUT and ENABLE_ECHO_INPUT modes only affect processes that use ReadFile or ReadConsole to read from the console’s input buffer. Similarly, the ENABLE_PROCESSED_INPUT mode primarily affects ReadFile and ReadConsole users, except that it also determines whether CTRL+C input is reported in the input buffer (to be read by the ReadConsoleInput function) or is passed to a HandlerRoutine function defined by the application.

The ENABLE_WINDOW_INPUT and ENABLE_MOUSE_INPUT modes determine whether user interactions involving window resizing and mouse actions are reported in the input buffer or discarded. These events can be read by ReadConsoleInput, but they are always filtered by ReadFile and ReadConsole.

The ENABLE_PROCESSED_OUTPUT and ENABLE_WRAP_AT_EOL_OUTPUT modes only affect processes using ReadFile or ReadConsole and WriteFile or WriteConsole.

To determine the current mode of a console input buffer or a screen buffer, use the GetConsoleMode function.

See Also

GetConsoleMode, HandlerRoutine, ReadConsole, ReadConsoleInput, ReadFile, WriteConsole, WriteFile


SetConsoleOutputCP

The SetConsoleOutputCP function sets the output code page used by the console associated with the calling process. A console uses its output code page to translate the character values written by the various output functions into the images displayed in the console window.

BOOL SetConsoleOutputCP(

UINT wCodePageID	// code page to set
);
Parameters

wCodePageID

Specifies the identifier of the code page to set. The identifiers of the code pages available on the local computer are stored in the registry under the following key.

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Nls\CodePage

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.

Remarks

A code page maps 256 character codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages.

To determine a console’s current output code page, use the GetConsoleOutputCP function. To set and retrieve a console’s input code page, use the SetConsoleCP and GetConsoleCP functions.

See Also

GetConsoleCP, GetConsoleOutputCP, SetConsoleCP


SetConsoleScreenBufferSize

The SetConsoleScreenBufferSize function changes the size of the specified console screen buffer.

BOOL SetConsoleScreenBufferSize(

HANDLE hConsoleOutput,	// handle of console screen buffer
COORD dwSize	// new size in character rows and cols.
);
Parameters

hConsoleOutput

Identifies a console screen buffer. The handle must have GENERIC_WRITE access.

dwSize

Specifies a COORD structure containing the new size, in rows and columns, of the screen buffer. The specified width and height cannot be less than the width and height of the screen buffer’s window. The specified dimensions also cannot be less than the minimum size allowed by the system. This minimum depends on the current font size for the console (selected by the user) and the SM_CXMIN and SM_CYMIN values returned by the GetSystemMetrics 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.

See Also

COORD, GetConsoleScreenBufferInfo, SetConsoleWindowInfo


SetConsoleTextAttribute

The SetConsoleTextAttribute function sets the foreground (text) and background color attributes of characters written to the screen buffer by the WriteFile or WriteConsole function, or echoed by the ReadFile or ReadConsole function. This function affects only text written after the function call.

BOOL SetConsoleTextAttribute(

HANDLE hConsoleOutput,	// handle of console screen buffer
WORD wAttributes	// text and background colors
);
Parameters

hConsoleOutput

Identifies a console screen buffer. The handle must have GENERIC_READ access.

wAttributes

Specifies the foreground and background color attributes. Any combination of the following values can be specified: FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_RED, FOREGROUND_INTENSITY, BACKGROUND_BLUE, BACKGROUND_GREEN, BACKGROUND_RED, and BACKGROUND_INTENSITY. For example, the following combination of values produces white text on a black background:

FOREGROUND_RED | FOREGROUND_GREEN | FOREGROUND_BLUE

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.

Remarks

To determine the current color attributes of a screen buffer, call the GetConsoleScreenBufferInfo function.

See Also

GetConsoleScreenBufferInfo, ReadConsole, ReadFile, WriteConsole, WriteFile


SetConsoleTitle

The SetConsoleTitle function sets the title bar string for the current console window.

BOOL SetConsoleTitle(

LPCTSTR lpConsoleTitle	// address of new title
);
Parameters

lpConsoleTitle

Points to a null-terminated string that contains the string to appear in the title bar of the console window.

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.

Remarks

Windows NT: This function uses either Unicode characters or 8-bit characters from the console's current codepage. The console's codepage defaults initially to the system's OEM codepage. To change the console's codepage, use the SetConsoleCP or SetConsoleOutputCP functions, or use the chcp or mode con cp select= commands.

See Also

GetConsoleTitle, SetConsoleCP, SetConsoleOutputCP


SetConsoleWindowInfo

The SetConsoleWindowInfo function sets the current size and position of a console screen buffer’s window.

BOOL SetConsoleWindowInfo(

HANDLE hConsoleOutput,	// handle of console screen buffer
BOOL bAbsolute,	// coordinate type flag
CONST SMALL_RECT *lpConsoleWindow	// address of new window rectangle
);
Parameters

hConsoleOutput

Identifies a console screen buffer. The handle must have GENERIC_WRITE access.

bAbsolute

Specifies how the coordinates in the structure pointed to by the lpConsoleWindow parameter are used. If bAbsolute is TRUE, the coordinates specify the new upper-left and lower-right corners of the window. If it is FALSE, the coordinates are offsets to the current window-corner coordinates.

lpConsoleWindow

Points to a SMALL_RECT structure that contains values that determine the new upper-left and lower-right corners of the window.

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.

Remarks

The function fails if the specified window rectangle extends beyond the boundaries of the screen buffer. This means that the Top and Left members of the lpConsoleWindow rectangle (or the calculated top and left coordinates, if bAbsolute is FALSE) cannot be less than zero. Similarly, the Bottom and Right members (or the calculated bottom and right coordinates) cannot be greater than (screen buffer height − 1) and (screen buffer width − 1), respectively. The function also fails if the Right member (or calculated right coordinate) is less than or equal to the Left member (or calculated left coordinate) or if the Bottom member (or calculated bottom coordinate) is less than or equal to the Top member (or calculated top coordinate).

For consoles with more than one screen buffer, changing the window location for one screen buffer does not affect the window locations of the other screen buffers.

To determine the current size and position of a screen buffer’s window, use the GetConsoleScreenBufferInfo function. This function also returns the maximum size of the window, given the current screen buffer size, the current font size, and the screen size. The GetLargestConsoleWindowSize function returns the maximum window size given the current font and screen sizes, but it does not consider the size of the screen buffer.

SetConsoleWindowInfo can be used to scroll the contents of the screen buffer by shifting the position of the window rectangle without changing its size.

See Also

GetConsoleScreenBufferInfo, GetLargestConsoleWindowSize, SMALL_RECT, ScrollConsoleScreenBuffer


SetCurrentDirectory

The SetCurrentDirectory function changes the current directory for the current process.

BOOL SetCurrentDirectory(

LPCTSTR lpPathName	// address of name of new current directory
);
Parameters

lpPathName

Points to a null-terminated string that specifies the path to the new current directory. This parameter may be a relative path or a fully qualified path. In either case, the fully qualified path of the specified directory is calculated and stored as the current directory.

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.

Remarks

Each process has a single current directory made up of two parts:

•	A disk designator that is either a drive letter followed by a colon, or a server name and share name (\\servername\sharename)

•	A directory on the disk designator

See Also

GetCurrentDirectory


SetCursor

The SetCursor function establishes the cursor shape.

HCURSOR SetCursor(

HCURSOR hCursor	// handle of cursor
);
Parameters

hCursor

Identifies the cursor. The cursor must have been created by the CreateCursor or loaded by the LoadCursor or LoadImage function. If this parameter is NULL, the cursor is removed from the screen.

Windows 95: The width and height of the cursor must be the values returned by the GetSystemMetrics function for SM_CXCURSOR and SM_CYCURSOR. In addition, the cursor bit depth must match the bit depth of the display or the cursor must be monochrome.

Return Values

The return value is the handle of the previous cursor, if there was one.

If there was no previous cursor, the return value is NULL.

Remarks

The cursor is set only if the new cursor is different from the previous cursor; otherwise, the function returns immediately.

The cursor is a shared resource. A window should set the cursor shape only when the cursor is in its client area or when the window is capturing mouse input. In systems without a mouse, the window should restore the previous cursor before the cursor leaves the client area or before it relinquishes control to another window.

If your application must set the cursor while it is in a window, make sure the class cursor for the specified window’s class is set to NULL. If the class cursor is not NULL, the system restores the class cursor each time the mouse is moved.

The cursor is not shown on the screen if the internal cursor display count is less than zero. This occurs if the application uses the ShowCursor function to hide the cursor more times than to show the cursor.

See Also

CreateCursor, GetCursor, GetSystemMetrics, LoadCursor, LoadImage, SetCursorPos, ShowCursor


SetCursorPos

The SetCursorPos function moves the cursor to the specified screen coordinates. If the new coordinates are not within the screen rectangle set by the most recent ClipCursor function, Windows automatically adjusts the coordinates so that the cursor stays within the rectangle.

BOOL SetCursorPos(

int X,	// horizontal position
int Y	// vertical position
);
Parameters

X

Specifies the new x-coordinate, in screen coordinates, of the cursor.

Y

Specifies the new y-coordinate, in screen coordinates, of the cursor.

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.

Remarks

The cursor is a shared resource. A window should move the cursor only when the cursor is in its client area.

The calling process must have WINSTA_WRITEATTRIBUTES access to the window station.

See Also

ClipCursor, GetCursorPos, SetCaretPos, SetCursor, ShowCursor


SetDebugErrorLevel

The SetDebugErrorLevel function sets the minimum error level at which Windows will generate debugging events and pass them to a debugger.

VOID SetDebugErrorLevel(

DWORD dwLevel	// debugging error level
);
Parameters

dwLevel

Specifies the minimum error level for debugging events. If an error is equal to or above this level, Windows generates a debugging event. This parameter must be one of the following values:

Value	Meaning
0	Does not report any errors. This value is the default error level.
SLE_ERROR	Reports only ERROR level debugging events.
SLE_MINORERROR	Reports only MINORERROR level and ERROR level debugging events.
SLE_WARNING	Reports WARNING level, MINORERROR level, and ERROR level debugging events.
Return Values

This function does not return a value.

Remarks

The debugger calls SetDebugErrorLevel to specify the types of errors that it should be notified about.

If the debugging error level is greater than the error that occurred, the value for the GetLastError function is set, but the kernel does not generate a debugging event.


SetDefaultCommConfig [Now Supported on Windows NT]
SetDefaultCommConfig

[Now Supported on Windows NT]

The SetDefaultCommConfig function sets the default configuration for a communications device.

BOOL SetDefaultCommConfig(

LPCSTR lpszName,
LPCOMMCONFIG lpCC,
DWORD dwSize
);
Parameters

lpszName

Points to a null-terminated string specifying the name of the device.

lpCC

Points to a COMMCONFIG structure. If this parameter is NULL, the default configuration is set to the device driver’s defaults.

dwSize

Specifies the size, in bytes, of the structure pointed to by lpCC.

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.

See Also

GetDefaultCommConfig, COMMCONFIG


SetDeviceGammaRamp

The SetDeviceGammaRamp function sets the gamma ramp on direct color display boards.

BOOL SetDeviceGammaRamp(

HDC hdc,
LPVOID lpRamp
);
Parameters

hdc

Handle to the device context.

lpRamp

Pointer to a set of three arrays of 256-byte elements. These arrays are the mapping between color values in the frame buffer and DAC values. The first array is red, the next is green, and the final one is blue.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Direct color display modes do not use color look-up tables. The direct color modes are usually 16-, 24-, or 32-bit. Not all direct color video boards support loadable gamma ramps. This function succeeds only for those drivers that support loadable gamma ramps in hardware.

See Also

GetDeviceGammaRamp


SetDIBColorTable

The SetDIBColorTable function sets RGB (red, green, blue) color values in a range of entries in the color table of the device-independent bitmap (DIB) that is currently selected into a specified device context.

UINT SetDIBColorTable(

HDC hdc,	// handle of device context whose DIB is of interest
UINT uStartIndex,	// color table index of first entry to set
UINT cEntries,	// number of color table entries to set
CONST RGBQUAD *pColors	// pointer to array of color table entries
);
Parameters

hdc

Specifies a device context. A device-independent bitmap must be selected into this device context.

uStartIndex

A zero-based color table index that specifies the first color table entry to set.

cEntries

Specifies the number of color table entries to set.

pColors

Points to an array of RGBQUAD structures containing new color information for the DIB’s color table.

Return Values

If the function succeeds, the return value is the number of color table entries that the function sets.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

This function should be called to set the color table for device-independent bitmaps that use 1, 4, or 8 bits per pixel. The biBitCount member of a bitmap’s associated BITMAPINFOHEADER structure specifies the number of bits per pixel. Device-independent bitmaps with a biBitCount value greater than 8 do not have a color table.

See Also

BITMAPINFOHEADER, CreateDIBSection, GetDIBColorTable, GetObject, DIBSECTION, RGBQUAD


SetDIBits

The SetDIBits function sets the pixels in a bitmap using the color data found in the specified device-independent bitmap (DIB).

int SetDIBits(

HDC hdc,	// handle of device context
HBITMAP hbmp,	// handle of bitmap
UINT uStartScan,	// starting scan line
UINT cScanLines,	// number of scan lines
CONST VOID *lpvBits,	// array of bitmap bits
CONST BITMAPINFO *lpbmi,	// address of structure with bitmap data
UINT fuColorUse	// type of color indices to use
);
Parameters

hdc

Identifies a device context.

hbmp

Identifies the bitmap that is to be altered using the color data from the specified DIB.

uStartScan

Specifies the starting scan line for the device-independent color data in the array pointed to by the lpvBits parameter.

cScanLines

Specifies the number of scan lines found in the array containing device-independent color data.

lpvBits

Points to the DIB color data, stored as an array of bytes. The format of the bitmap values depends on the biBitCount member of the BITMAPINFO structure pointed to by the lpbmi parameter.

lpbmi

Points to a BITMAPINFO data structure that contains information about the DIB.

fuColorUse

Specifies whether the bmiColors member of the BITMAPINFO structure was provided and, if so, whether bmiColors contains explicit red, green, blue (RGB) values or palette indices. The fuColorUse parameter must be one of the following values:

Value	Meaning
DIB_PAL_COLORS	The color table consists of an array of 16-bit indices into the logical palette of the device context identified by the hdc parameter.
DIB_RGB_COLORS	The color table is provided and contains literal RGB values.
Return Values

If the function succeeds, the return value is the number of scan lines copied.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Optimal bitmap drawing speed is obtained when the bitmap bits are indices into the system palette.

Applications can retrieve the system palette colors and indices by calling the GetSystemPaletteEntries function. After the colors and indices are retrieved, the application can create the DIB. For more information, see System Palette.

The device context identified by the hdc parameter is used only if the DIB_PAL_COLORS constant is set for the fuColorUse parameter; otherwise it is ignored.

The bitmap identified by the hbmp parameter must not be selected into a device context when the application calls this function.

The origin for bottom-up DIBs is the lower-left corner of the bitmap; the origin for top-down DIBs is the upper-left corner of the bitmap.

See Also

GetDIBits, GetSystemPaletteEntries, BITMAPINFO


SetDIBitsToDevice

The SetDIBitsToDevice function sets the pixels in the specified rectangle on the device that is associated with the destination device context using color data from a device-independent bitmap (DIB).

int SetDIBitsToDevice(

HDC hdc,	// handle of device context
int XDest,	// x-coordinate of upper-left corner of dest. rect.
int YDest,	// y-coordinate of upper-left corner of dest. rect.
DWORD dwWidth,	// source rectangle width
DWORD dwHeight,	// source rectangle height
int XSrc,	// x-coordinate of lower-left corner of source rect.
int YSrc,	// y-coordinate of lower-left corner of source rect.
UINT uStartScan,	// first scan line in array
UINT cScanLines,	// number of scan lines
CONST VOID *lpvBits,	// address of array with DIB bits
CONST BITMAPINFO *lpbmi,	// address of structure with bitmap info.
UINT fuColorUse	// RGB or palette indices
);
Parameters

hdc

Identifies the device context.

XDest

Specifies the x-coordinate, in logical units, of the upper-left corner of the destination rectangle.

YDest

Specifies the y-coordinate, in logical units, of the upper-left corner of the destination rectangle.

dwWidth

Specifies the width, in logical units, of the DIB.

dwHeight

Specifies the height, in logical units, of the DIB.

XSrc

Specifies the x-coordinate, in logical units, of the lower-left corner of the DIB.

YSrc

Specifies the y-coordinate, in logical units, of the lower-left corner of the DIB.

uStartScan

Specifies the starting scan line in the DIB.

cScanLines

Specifies the number of DIB scan lines contained in the array pointed to by the lpvBits parameter.

lpvBits

Points to DIB color data stored as an array of bytes.

lpbmi

Points to a BITMAPINFO structure that contains information about the DIB.

fuColorUse

Specifies whether the bmiColors member of the BITMAPINFO structure contains explicit red, green, blue (RGB) values or indices into a palette. The fuColorUse parameter must be one of the following values:

Value	Meaning
DIB_PAL_COLORS	The color table consists of an array of 16-bit indices into the currently selected logical palette.
DIB_RGB_COLORS	The color table contains literal RGB values.
Return Values

If the function succeeds, the return value is the number of scan lines set.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Optimal bitmap drawing speed is obtained when the bitmap bits are indices into the system palette.

Applications can retrieve the system palette colors and indices by calling the GetSystemPaletteEntries function. After the colors and indices are retrieved, the application can create the DIB. For more information about the system palette, see Colors.

The origin of a bottom-up DIB is the lower-left corner of the bitmap; the origin of a top-down DIB is the upper-left corner.

To reduce the amount of memory required to set bits from a large device-independent bitmap on a device surface, an application can band the output by repeatedly calling SetDIBitsToDevice, placing a different portion of the bitmap into the lpvBits array each time. The values of the uStartScan and cScanLines parameters identify the portion of the bitmap contained in the lpvBits array.

The SetDIBitsToDevice function returns an error if it is called by a process that is running in the background while a full-screen MS-DOS session runs in the foreground.

See Also

BITMAPINFO, GetSystemPaletteEntries, SetDIBits, StretchDIBits


SetDlgItemInt

The SetDlgItemInt function sets the text of a control in a dialog box to the string representation of a specified integer value.

BOOL SetDlgItemInt(

HWND hDlg,	// handle of dialog box
int nIDDlgItem,	// identifier of control
UINT uValue,	// value to set
BOOL bSigned	// signed or unsigned indicator
);
Parameters

hDlg

Identifies the dialog box that contains the control.

nIDDlgItem

Specifies the control to be changed.

uValue

Specifies the integer value used to generate the item text.

bSigned

Specifies whether the uValue parameter is signed or unsigned. If this parameter is TRUE, uValue is signed. If this parameter is TRUE and uValue is less than zero, a minus sign is placed before the first digit in the string. If this parameter is FALSE, uValue is unsigned.

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.

Remarks

To set the new text, this function sends a WM_SETTEXT message to the specified control.

See Also

GetDlgItemInt, SetDlgItemText, WM_SETTEXT


SetDlgItemText

The SetDlgItemText function sets the title or text of a control in a dialog box.

BOOL SetDlgItemText(

HWND hDlg,	// handle of dialog box
int nIDDlgItem,	// identifier of control
LPCTSTR lpString	// text to set
);
Parameters

hDlg

Identifies the dialog box that contains the control.

nIDDlgItem

Identifies the control with a title or text that is to be set.

lpString

Points to the null-terminated string that contains the text to be copied to the control.

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.

Remarks

The SetDlgItemText function sends a WM_SETTEXT message to the specified control.

See Also

GetDlgItemInt, GetDlgItemText, SetDlgItemInt, WM_SETTEXT


SetDoubleClickTime

The SetDoubleClickTime function sets the double-click time for the mouse. A double-click is a series of two clicks of a mouse button, the second occurring within a specified time after the first. The double-click time is the maximum number of milliseconds that may occur between the first and second clicks of a double-click.

BOOL SetDoubleClickTime(

UINT uInterval	// double-click interval
);
Parameters

uInterval

Specifies the number of milliseconds that may occur between the first and second clicks of a double-click. If this parameter is set to zero, Windows uses the default double-click time of 500 milliseconds.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The SetDoubleClickTime function alters the double-click time for all windows in the system.

See Also

GetDoubleClickTime


SetEndOfFile

The SetEndOfFile function moves the end-of-file (EOF) position for the specified file to the current position of the file pointer.

BOOL SetEndOfFile(

HANDLE hFile	// handle of file whose EOF is to be set
);
Parameters

hFile

Identifies the file to have its EOF position moved. The file handle must have been created with GENERIC_WRITE access to the file.

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.

Remarks

This function can be used to truncate or extend a file. If the file is extended, the contents of the file between the old EOF position and the new position are not defined.

If you called CreateFileMapping to create a file-mapping object for hFile, you must first call UnmapViewOfFile to unmap all views and call CloseHandle to close the file-mapping object before you can call SetEndOfFile.

See Also

CloseHandle, CreateFile, CreateFileMapping, UnmapViewOfFile


SetEnhMetaFileBits

The SetEnhMetaFileBits function creates a memory-based enhanced-format metafile from the supplied data.

HENHMETAFILE SetEnhMetaFileBits(

UINT cbBuffer,	// buffer size
CONST BYTE *lpData	// buffer that contains enhanced metafile data
);
Parameters

cbBuffer

Specifies the size, in bytes, of the data provided.

lpData

Points to a buffer that contains enhanced-metafile data. (It is assumed that the data in the buffer was obtained by calling the GetEnhMetaFileBits function.)

Return Values

If the function succeeds, the return value is a handle of a memory-based enhanced metafile.

If the function fails, the return value is NULL.

Remarks

When the application no longer needs the enhanced-metafile handle, it should delete the handle by calling the DeleteEnhMetaFile function.

The SetEnhMetaFileBits function does not accept metafile data in the Windows format. To import Windows-format metafiles, use the SetWinMetaFileBits function.

See Also

DeleteEnhMetaFile, GetEnhMetaFileBits, SetWinMetaFileBits


SetEntriesInAcl [New - Windows NT]
SetEntriesInAcl

[New - Windows NT]

The SetEntriesInAcl function creates a new access-control list (ACL) by merging new access-control or audit-control information into an existing ACL.

DWORD SetEntriesInAcl(

ULONG cCountOfExplicitEntries,	// number of entries in the list
PEXPLICIT_ACCESS pListOfExplicitEntries,	// pointer to list of entries with new access data
PACL OldAcl,	// pointer to the original ACL
PACL * NewAcl	// receives a pointer to the new ACL
);
Parameters

cCountOfExplicitEntries

Specifies the number of EXPLICIT_ACCESS structures in the pListOfExplicitEntries array.

pListOfExplicitEntries

Pointer to an array of EXPLICIT_ACCESS structures that describe the access control information to merge into the existing ACL.

OldAcl

Pointer to the existing ACL. This parameter can be NULL, in which case, the function creates a new ACL based on the EXPLICIT_ACCESS entries.

NewAcl

Pointer to a variable that receives a pointer to the new ACL. If the function succeeds, you must call the LocalFree function to free the returned buffer.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

Each entry in the array of EXPLICIT_ACCESS structures specifies access-control or audit-control information for a specified trustee. A trustee can be a user, group, or other SID value, such as a logon identifier or logon type (for instance, a Windows NT service or batch job). You can use a name or a security identifier (SID) to identify a trustee.

You can use the SetEntriesInAcl function to modify the list of ACEs in a DACL or a SACL. A DACL controls access to an object, and a SACL controls the system’s auditing of attempts to access to an object. Note that SetEntriesInAcl does not prevent you from mixing access-control and audit-control information in the same ACL; however, the resulting ACL will contain meaningless entries.

For a DACL, the grfAccessMode member of the EXPLICIT_ACCESS structure specifies whether to allow, deny, or revoke access rights for the trustee. This member can specify one of the following values from the ACCESS_MODE enumeration.

Value	Meaning
GRANT_ACCESS	Creates a new access-allowed ACE that combines the specified rights with any existing rights of the trustee. The new ACE replaces any existing access-allowed ACE for the trustee. The function also modifies or deletes any existing access-denied ACE for the trustee that denies the specified rights.
SET_ACCESS	Similar to GRANT_ACCESS except that the new access-allowed ACE allows only the specified rights, discarding any existing rights. This flag also removes any existing access-denied ACE for the trustee.
DENY_ACCESS	Creates a new access-denied ACE that replaces any existing access-denied ACE for the trustee. The new ACE denies the specified rights in addition to any currently denied rights of the trustee. The function also modifies or deletes any existing access-allowed ACE for the trustee that allows the specified rights.
REVOKE_ACCESS	Removes any existing ACEs for the specified trustee. The function ignores the rights specified in the grfAccessPermissions member of the EXPLICIT_ACCESS structure.
The SetEntriesInAcl function places any new access-denied ACEs at the beginning of the list of ACEs for the new ACL. It places any new access-allowed ACEs just before any existing access-allowed ACEs.

For a SACL, the grfAccessMode member of the EXPLICIT_ACCESS structure can specify the following values.

Value	Meaning
REVOKE_ACCESS	Removes any existing ACEs for the specified trustee. The function ignores the rights specified in the grfAccessPermissions member of the EXPLICIT_ACCESS structure.
SET_AUDIT_SUCCESS	Creates a new system-audit ACE that replaces any existing system-audit ACE for the trustee. The new ACE generates audit messages when the specified trustee successfully uses the specified access rights. The new ACE combines the specified rights with any existing audited access rights for the trustee. You can combine this value with SET_AUDIT_FAILURE.
SET_AUDIT_FAILURE	Creates a new system-audit ACE that replaces any existing system-audit ACE for the trustee. The new ACE generates audit messages for failed attempts to use the specified access rights. The new ACE combines the specified rights with any existing audited access rights for the trustee. You can combine this value with SET_AUDIT_SUCCESS.
The SetEntriesInAcl function places any new system-audit ACEs at the beginning of the list of ACEs for the new ACL.

See Also

ACCESS_ALLOWED_ACE, ACCESS_DENIED_ACE, ACL, EXPLICIT_ACCESS, LocalFree, SYSTEM_AUDIT_ACE


SetEnvironmentVariable

The SetEnvironmentVariable function sets the value of an environment variable for the current process.

BOOL SetEnvironmentVariable(

LPCTSTR lpName,	// address of environment variable name
LPCTSTR lpValue	// address of new value for variable
);
Parameters

lpName

Points to a null-terminated string that specifies the environment variable whose value is being set. The operating system creates the environment variable if it does not exist and lpValue is not NULL.

lpValue

Points to a null-terminated string containing the new value of the specified environment variable. If this parameter is NULL, the variable is deleted from the current process’s environment.

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.

See Also

GetEnvironmentVariable


SetErrorMode

The SetErrorMode function controls how the operating system handles several types of serious errors. You can specify that the operating system will handle these errors or that the application will receive and handle them.

UINT SetErrorMode(

UINT uMode	// set of bit flags that specify error-handling properties
);
Parameters

uMode

A set of bit flags that specify system error-handling properties. The following error mode bit flag constants are defined; you can set any combination of them:

Value	Action
SEM_FAILCRITICALERRORS	If this flag is set, the operating system does not display the critical-error-handler message box when such an error occurs. Instead, the operating system sends the error to the calling process.
SEM_NOALIGNMENTFAULTEXCEPT	If this flag is set, the operating system automatically fixes memory alignment faults and makes them invisible to the application. It does this for the calling process and any descendant processes.  This flag always affects MIPS processors. It has no effect on x86 processors. If the registry value \CurrentControlSet\Control\Session Manager:EnableAlignmentFaultExceptions is set to REG_DWORD 0x0, this key has no effect on ALPHA processors. That is the system default. If the registry key is set to REG_DWORD 0x1, the SEM_NOALIGNMENTFAULTEXCEPT flag does affect ALPHA processors.
SEM_NOGPFAULTERRORBOX	If this flag is set, the operating system does not display the general-protection-fault message box when such an error occurs. This flag should only be set by debugging applications that handle general protection (GP) faults themselves via an appropriate exception handler.
SEM_NOOPENFILEERRORBOX	If this flag is set, the operating system does not display a message box when it fails to find a a file. Instead, the error is returned to the calling process.
Return Values

The return value is the previous state of the error-mode bit flags.

Remarks

A child process inherits the error mode of its parent process.

The default state for the error mode properties set by this function is OFF.

On some non-x86 processors misaligned memory references cause an alignment fault exception. The SEM_NOALIGNMENTFAULTEXCEPT flag lets you control whether the operating system automatically fixes such alignment faults, or makes them visible to an application.

The SEM_NOALIGNMENTFAULTEXCEPT flag always affects MIPS processors. It never affects x86 processors. It affects ALPHA processors only if the registry key \CurrentControlSet\Control\Session Manager:EnableAlignmentFaultExceptions is set to REG_DWORD 0x1. The default setting for that registry key is REG_DWORD 0x0.

On an x86 platform, an application doesn’t need to do anything to have the operating system automatically fix misaligned memory references. The operating system does not make alignment faults visible to an application.

On a MIPS platform, an application must explicitly call SetErrorMode, setting the SEM_NOALIGNMENTFAULTEXCEPT flag, to have the operating system automatically fix alignment faults. The default setting is for the operating system to make alignment faults visible to an application.

On an ALPHA platform, the operating system automatically fixes alignment faults, unless the aforementioned registry key is set to REG_DWORD 0x1. When that registry key is set to REG_DWORD 0x1, the operating system makes alignment faults visible to an application, and an application must then call SetErrorMode to have the operating system automatically fix alignment faults.

Specifying the SEM_NOALIGNMENTFAULTEXCEPT flag on x86 systems is not an error, but implementations of Windows NT are free to silently ignore and not properly preserve the flag. This means that code sequences such as the following are not always valid on x86 systems:

SetErrorMode(SEM_NOALIGNMENTFAULTEXCEPT);

fuOldErrorMode = SetErrorMode(0);

ASSERT(fuOldErrorMode == SEM_NOALIGNMENTFAULTEXCEPT);


SetEvent

The SetEvent function sets the state of the specified event object to signaled.

BOOL SetEvent(

HANDLE hEvent	// handle of event object
);
Parameters

hEvent

Identifies the event object. The CreateEvent or OpenEvent function returns this handle.

Windows NT: The handle must have EVENT_MODIFY_STATE access. For more information, see Interprocess Synchronization Objects.

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.

Remarks

The state of a manual-reset event object remains signaled until it is set explicitly to the nonsignaled state by the ResetEvent function. Any number of waiting threads, or threads that subsequently begin wait operations for the specified event object by calling one of the wait functions, can be released while the object’s state is signaled.

The state of an auto-reset event object remains signaled until a single waiting thread is released, at which time the system automatically sets the state to nonsignaled. If no threads are waiting, the event object’s state remains signaled.

See Also

CreateEvent, OpenEvent, PulseEvent, ResetEvent


SetFileApisToANSI

The SetFileApisToANSI function causes a set of Win32 file functions to use the ANSI character set code page. This function is useful for 8-bit console input and output operations.

VOID SetFileApisToANSI (VOID)

Parameters

This function has no parameters.

Return Values

This function has no return value.

Remarks

The SetFileApisToANSI function complements the SetFileApisToOEM function, which causes the same set of Win32 file functions to use the OEM character set code page.

The 8-bit console functions use the OEM code page by default. All other functions use the ANSI code page by default. This means that strings returned by the console functions may not be processed correctly by other functions, and vice versa. For example, if the FindFirstFileA function returns a string that contains certain extended ANSI characters, and the 8-bit console functions are set to use the OEM code page, then the WriteConsoleA function will not display the string properly.

Use the AreFileApisANSI function to determine which code page the set of file functions is currently using. Use the SetConsoleCP and SetConsoleOutputCP functions to set the code page for the 8-bit console functions.

To solve the problem of code page incompatibility, it is best to use Unicode for console applications. Console applications that use Unicode are much more versatile than those that use 8-bit console functions. Barring that solution, a console application can call the SetFileApisToOEM function to cause the set of Win32 file functions to use OEM character set strings rather than ANSI character set strings. Use the SetFileApisToANSI function to set those functions back to the ANSI code page.

SetFileApisToANSI and SetFileApisToOEM affect these Win32 functions:

_lopen	GetDriveType	LoadLibrary
CopyFile	GetFileAttributes	LoadLibraryEx
CreateDirectory	GetFullPathName	MoveFile
CreateFile	GetModuleFileName	MoveFileEx
CreateProcess	GetModuleHandle	OpenFile
DeleteFile	GetSystemDirectory	RemoveDirectory
FindFirstFile	GetTempFileName	SearchPath
FindNextFile	GetTempPath	SetCurrentDirectory
GetCurrentDirectory	GetVolumeInformation	SetFileAttributes
GetDiskFreeSpace	GetWindowsDirectory
When dealing with command lines, a console application should obtain the command line in Unicode form, and then convert it to OEM form using the relevant character-to-OEM functions. Note also that the argv function uses the ANSI character set.

See Also

AreFileApisANSI, FindFirstFileA, SetFileApisToOEM, SetConsoleCP, SetConsoleOutputCP, WriteConsoleA


SetFileApisToOEM

The SetFileApisToOEM function causes a set of Win32 file functions to use the OEM character set code page. This function is useful for 8-bit console input and output operations.

VOID SetFileApisToOEM(VOID)

Parameters

This function has no parameters.

Return Values

This function has no return value.

Remarks

The SetFileApisToOEM function is complemented by the SetFileApisToANSI function, which causes the same set of Win32 file functions to use the ANSI character set code page.

The 8-bit console functions use the OEM code page by default. All other functions use the ANSI code page by default. This means that strings returned by the console functions may not be processed correctly by other functions, and vice versa. For example, if the FindFirstFileA function returns a string that contains certain extended ANSI characters, and the 8-bit console functions are set to use the OEM code page, then the WriteConsoleA function will not display the string properly.

Use the AreFileApisANSI function to determine which code page the set of file functions is currently using. Use the SetConsoleCP and SetConsoleOutputCP functions to set the code page for the 8-bit console functions.

To solve the problem of code page incompatibility, it is best to use Unicode for console applications. Console applications that use Unicode are much more versatile than those that use 8-bit console functions. Barring that solution, a console application can call the SetFileApisToOEM function to cause the set of Win32 file functions to use OEM character set strings rather than ANSI character set strings. Use the SetFileApisToANSI function to set those functions back to the ANSI code page.

SetFileApisToANSI and SetFileApisToOEM affect these Win32 functions:

_lopen	GetDriveType	LoadLibrary
CopyFile	GetFileAttributes	LoadLibraryEx
CreateDirectory	GetFullPathName	MoveFile
CreateFile	GetModuleFileName	MoveFileEx
CreateProcess	GetModuleHandle	OpenFile
DeleteFile	GetSystemDirectory	RemoveDirectory
FindFirstFile	GetTempFileName	SearchPath
FindNextFile	GetTempPath	SetCurrentDirectory
GetCurrentDirectory	GetVolumeInformation	SetFileAttributes
GetDiskFreeSpace	GetWindowsDirectory
When dealing with command lines, a console application should obtain the command line in Unicode form, and then convert it to OEM form using the relevant character-to-OEM functions. Note also that the argv function uses the ANSI character set.

See Also

AreFileApisANSI, FindFirstFileA, SetConsoleCP, SetConsoleCP, SetConsoleOutputCP, SetFileApisToANSI, WriteConsoleA


SetFileAttributes

The SetFileAttributes function sets a file’s attributes.

BOOL SetFileAttributes(

LPCTSTR lpFileName,	// address of filename
DWORD dwFileAttributes	// address of attributes to set
);
Parameters

lpFileName

Points to a string that specifies the name of the file whose attributes are to be set.

Windows 95: This string must not exceed MAX_PATH characters.

Windows NT: There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the SetFileAttributes function parses paths. An application can transcend this limit and send in paths longer than MAX_PATH characters by calling the wide (W) version of SetFileAttributes and prepending “\\?\” to the path. The “\\?\” tells the function to turn off path parsing; it lets paths longer than MAX_PATH be used with SetFileAttributesW. This also works with UNC names. The “\\?\” is ignored as part of the path. For example, “\\?\C:\myworld\private” is seen as “C:\myworld\private”, and “\\?\UNC\bill_g_1\hotstuff\coolapps” is seen as “\\bill_g_1\hotstuff\coolapps”.

dwFileAttributes

Specifies the file attributes to set for the file. This parameter can be a combination of the following values. However, all other values override FILE_ATTRIBUTE_NORMAL.

Value	Meaning
FILE_ATTRIBUTE_ARCHIVE	The file is an archive file. Applications use this value to mark files for backup or removal.
FILE_ATTRIBUTE_HIDDEN	The file is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL	The file has no other attributes set. This value is valid only if used alone.
FILE_ATTRIBUTE_OFFLINE	The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage.
FILE_ATTRIBUTE_READONLY	The file is read-only. Applications can read the file but cannot write to it or delete it.
FILE_ATTRIBUTE_SYSTEM	The file is part of the operating system or is used exclusively by it.
FILE_ATTRIBUTE_TEMPORARY	The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed.
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.

Remarks

You cannot use the SetFileAttribute function to set a file’s compression state. Setting FILE_ATTRIBUTE_COMPRESSED in the dwFileAttributes parameter does nothing. Use the DeviceIoControl function and the FSCTL_SET_COMPRESSION operation to set a file’s compression state.

See Also

DeviceIoControl, FSCTL_SET_COMPRESSION, GetFileAttributes


SetFilePointer

The SetFilePointer function moves the file pointer of an open file.

DWORD SetFilePointer(

HANDLE hFile,	// handle of file
LONG lDistanceToMove,	// number of bytes to move file pointer
PLONG lpDistanceToMoveHigh,	// address of high-order word of distance to move
DWORD dwMoveMethod	// how to move
);
Parameters

hFile

Identifies the file whose file pointer is to be moved. The file handle must have been created with GENERIC_READ or GENERIC_WRITE access to the file.

lDistanceToMove

Specifies the number of bytes to move the file pointer. A positive value moves the pointer forward in the file and a negative value moves it backward.

lpDistanceToMoveHigh

Points to the high-order word of the 64-bit distance to move. If the value of this parameter is NULL, SetFilePointer can operate only on files whose maximum size is 2^32 − 2. If this parameter is specified, the maximum file size is 2^64 − 2. This parameter also receives the high-order word of the new value of the file pointer.

dwMoveMethod

Specifies the starting point for the file pointer move. This parameter can be one of the following values:

Value	Meaning
FILE_BEGIN	The starting point is zero or the beginning of the file. If FILE_BEGIN is specified, DistanceToMove is interpreted as an unsigned location for the new file pointer.
FILE_CURRENT	The current value of the file pointer is the starting point.
FILE_END	The current end-of-file position is the starting point.
Return Values

If the SetFilePointer function succeeds, the return value is the low-order doubleword of the new file pointer, and if lpDistanceToMoveHigh is not NULL, the function puts the high-order doubleword of the new file pointer into the LONG pointed to by that parameter.

If the function fails and lpDistanceToMoveHigh is NULL, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

If the function fails, and lpDistanceToMoveHigh is non-NULL, the return value is 0xFFFFFFFF and GetLastError will return a value other than NO_ERROR.

Remarks

You cannot use the SetFilePointer function with a handle to a nonseeking device, such as a pipe or a communications device. To determine the file type for hFile, use the GetFileType function.

You should be careful when setting the file pointer in a multithreaded application. For example, an application whose threads share a file handle, update the file pointer, and read from the file must protect this sequence by using a critical section object or mutex object. For more information about these objects, see Mutex Objects and Critical Section Objects.

If the hFile file handle was opened with the FILE_FLAG_NO_BUFFERING flag set, an application can move the file pointer only to sector-aligned positions. A sector-aligned position is a position that is a whole number multiple of the volume’s sector size. An application can obtain a volume’s sector size by calling the GetDiskFreeSpace function. If an application calls SetFilePointer with distance-to-move values that result in a position that is not sector-aligned and a handle that was opened with FILE_FLAG_NO_BUFFERING, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER.

Note that if the return value is 0xFFFFFFFF and if lpDistanceToMoveHigh is non-NULL, an application must call GetLastError to determine whether the function has succeeded or failed. The following sample code illustrates this point:

//

// Case One: calling the function with

//           lpDistanceToMoveHigh == NULL

// try to move hFile's file pointer some distance

dwPointer = SetFilePointer (hFile, lDistance,

                            NULL, FILE_BEGIN) ;

// if we failed ...

if (dwPointer == 0xFFFFFFFF) {

    // obtain the error code

    dwError = GetLastError() ;

    // deal with that failure

    .

    .

    .

    } // end of error handler

//

// Case Two: calling the function with

//           lpDistanceToMoveHigh != NULL

// try to move hFile's file pointer some huge distance

dwPointerLow = SetFilePointer (hFile, lDistanceLow,

                               & lDistanceHigh, FILE_BEGIN) ;

// if we failed ...

if (dwPointerLow == 0xFFFFFFFF

    &&

    (dwError = GetLastError()) != NO_ERROR ){

    // deal with that failure

    .

    .

    .

    } // end of error handler

See Also

GetDiskFreeSpace, GetFileType, ReadFile, ReadFileEx, WriteFile, WriteFileEx


SetFileSecurity

The SetFileSecurity function sets the security of a file or directory object.

BOOL SetFileSecurity(

LPCTSTR lpFileName,	// address of string for filename
SECURITY_INFORMATION SecurityInformation,	// type of information to set
PSECURITY_DESCRIPTOR pSecurityDescriptor	// address of security descriptor
);
Parameters

lpFileName

Points to a null-terminated string specifying the file or directory for which security is set.

SecurityInformation

Specifies a SECURITY_INFORMATION structure identifying the contents of the security descriptor pointed to by the pSecurityDescriptor parameter.

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure.

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.

Remarks

The SetFileSecurity function is successful only if the following conditions are met:

•	If the object’s owner is being set, the calling process must have either WRITE_OWNER permission or be the object’s owner.

•	If the object’s discretionary access-control list (ACL) is being set, the calling process must have either WRITE_DAC permission or be the object’s owner.

•	If the object’s system ACL is being set, the SE_SECURITY_NAME privilege must be enabled for the calling process.

See Also

GetFileSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetKernelObjectSecurity, SetPrivateObjectSecurity, SetUserObjectSecurity


SetFileTime

The SetFileTime function sets the date and time that a file was created, last accessed, or last modified.

BOOL SetFileTime(

HANDLE hFile,	// identifies the file
CONST FILETIME *lpCreationTime,	// time the file was created
CONST FILETIME *lpLastAccessTime,	// time the file was last accessed
CONST FILETIME *lpLastWriteTime	// time the file was last written
);
Parameters

hFile

Identifies the file for which to set the dates and times. The file handle must have been created with GENERIC_WRITE access to the file.

lpCreationTime

Points to a FILETIME structure that contains the date and time the file was created. This parameter can be NULL if the application does not need to set this information.

lpLastAccessTime

Points to a FILETIME structure that contains the date and time the file was last accessed. The last access time includes the last time the file was written to, read from, or (in the case of executable files) run. This parameter can be NULL if the application does not need to set this information.

lpLastWriteTime

Points to a FILETIME structure that contains the date and time the file was last written to. This parameter can be NULL if the application does not want to set this information.

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.

Remarks

The FAT and New Technology file systems support the file creation, last access, and last write time values.

See Also

FILETIME, GetFileSize, GetFileTime, GetFileType


SetFocus

The SetFocus function sets the keyboard focus to the specified window. The window must be associated with the calling thread’s message queue.

HWND SetFocus(

HWND hWnd	// handle of window to receive focus
);
Parameters

hWnd

Identifies the window that will receive the keyboard input. If this parameter is NULL, keystrokes are ignored.

Return Values

If the function succeeds, the return value is the handle of the window that previously had the keyboard focus. If the hWnd parameter is invalid or the window is not associated with the calling thread’s message queue, the return value is NULL.

Remarks

The SetFocus function sends a WM_KILLFOCUS message to the window that loses the keyboard focus and a WM_SETFOCUS message to the window that receives the keyboard focus. It also activates either the window that receives the focus or the parent of the window that receives the focus.

If a window is active but does not have the focus, any key pressed will produce the WM_SYSCHAR, WM_SYSKEYDOWN, or WM_SYSKEYUP message. If the VK_MENU key is also pressed, the lParam parameter of the message will have bit 30 set. Otherwise, the messages produced do not have this bit set.

By using the AttachThreadInput function, a thread can attach its input processing to another thread. This allows a thread to call SetFocus to set the keyboard focus to a window associated with another thread’s message queue.

See Also

AttachThreadInput, GetFocus, WM_KILLFOCUS, WM_SETFOCUS, WM_SYSCHAR, WM_SYSKEYDOWN, WM_SYSKEYUP


SetForegroundWindow

The SetForegroundWindow function puts the thread that created the specified window into the foreground and activates the window. Keyboard input is directed to the window, and various visual cues are changed for the user.

BOOL SetForegroundWindow(

HWND hWnd	// handle of window to bring to foreground
);
Parameters

hWnd

Identifies the window that should be activated and brought to the foreground.

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.

Remarks

The foreground window is the window at the top of the Z order. It is the window that the user is working with. In a preemptive multitasking environment, you should generally let the user control which window is the foreground window. However, an application can call SetForegroundWindow if it wants to put itself into the foreground to display a critical error or information that requires the user’s immediate attention. A good example is a debugger when it hits a breakpoint.

The system assigns a slightly higher priority to the thread that created the foreground window than it does to other threads.

See Also

GetForegroundWindow


SetForm

The SetForm function sets the form information for the specified printer.

BOOL SetForm(

HANDLE hPrinter,	// handle of printer object
LPTSTR pFormName,	// address of form name
DWORD Level,	// structure level
LPBYTE pForm	// address of structure array
);
Parameters

hPrinter

Identifies the printer for which the form information is set.

pFormName

Points to a null-terminated string that specifies the form name for which the form information is set.

Level

Specifies the version of the structure to which pForm points. This value must be 1.

pForm

Points to a FORM_INFO_1 structure.

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.

Remarks

The printer handle hPrinter is obtained by calling the OpenPrinter function.

See Also

GetForm, OpenPrinter, FORM_INFO_1


SetGraphicsMode

The SetGraphicsMode function sets the graphics mode for the specified device context.

int SetGraphicsMode(

HDC hdc,	// handle of the device context
int iMode	// graphics mode
);
Parameters

hdc

Identifies the device context.

iMode

Specifies the graphics mode. This parameter can be one of the following values:

Value	Meaning
GM_COMPATIBLE	Sets the graphics mode that is compatible with Windows version 3.1. This is the default mode. If this value is specified, the application can only modify the world-to-device transform by calling functions that set window and viewport extents and origins, but not by using SetWorldTransform or ModifyWorldTransform; calls to those functions will fail. Examples of functions that set window and viewport extents and origins are SetViewportExtEx and SetWindowExtEx.
GM_ADVANCED	Windows NT: Sets the advanced graphics mode that allows world transformations. This value must be specified if the application will set or modify the world transformation for the specified device context. In this mode all graphics, including text output, fully comforms to the world-to-device transformation specified in the device context. Windows 95: The GM_ADVANCED value is not supported. When playing enhanced metafiles, Windows 95 does its best to ensure that enhanced metafiles on Windows 95 look the same as they do on Windows NT. To accomplish this, Windows 95 may simulate GM_ADVANCED mode when playing specific enhanced metafile records.
Return Values

If the function succeeds, the return value is the old graphics mode.

If the function fails, the return value is zero.

Remarks

There are three areas in which graphics output differs according to the graphics mode:

1.	Text Output: In the GM_COMPATIBLE mode, TrueType (or vector font) text output behaves much the same way as raster font text output with respect to the world-to-device transform in the DC. The TrueType text is always written from left to right and right side up, even if the rest of the graphics will be flipped in the x or y axis. Only the height of the TrueType (or vector font) text is scaled appropriately. The only way to write nonhorizontal text in the GM_COMPATIBLE mode is to specify nonzero escapement and orientation for the logical font selected in this device context.

In the GM_ADVANCED mode, TrueType (or vector font) text output fully conforms to the world-to-device transform in the device context. The raster fonts only have very limited transformation capabilities (stretching by some integer factors). Graphics device interface (GDI) tries to produce the best output it can with raster fonts for non-trivial transforms.

2.	Rectangle Exclusion: If the default GM_COMPATIBLE graphics mode is set, the system excludes bottom and rightmost edges when it draws rectangles.

The GM_ADVANCED graphics mode is required if applications want to draw rectangles that are bottom-right inclusive.

3.	Arc Drawing: If the default GM_COMPATIBLE graphics mode is set, GDI draws arcs using the current arc direction in the device space. With this convention, arcs do not respect page-to-device transforms that require a flip along the x or y axis.

If the GM_ADVANCED graphics mode is set, GDI always draws arcs in the counterclockwise direction in logical space. This is equivalent to the statement that, in the GM_ADVANCED graphics mode, both arc control points and arcs themselves fully respect the device context’s world-to-device transform.

See Also

CreateDC, GetArcDirection, GetDC, GetGraphicsMode, ModifyWorldTransform, SetArcDirection, SetViewportExtent, SetViewportExtEx, SetWindowExtent, SetWindowExtEx, SetWorldTransform


SetHandleCount

The SetHandleCount function sets the number of file handles available to a process. This function has no effect under Windows NT and Windows 95, because there is no explicit file handle limit for applications on these platforms. Under Win32s, there are only 20 file handles available to a process by default; however you could use SetHandleCount to allow a process to use up to 255 file handles.

UINT SetHandleCount(

UINT uNumber	// number of file handles needed
);
Parameters

uNumber

Specifies the number of file handles needed by the application.

Return Values

Under Windows NT and Windows 95, this function simply returns the value specified in the uNumber parameter.

Under Win32s, the return value specifies the number of file handles actually available to the application. It may be fewer than the number specified by the uNumber parameter.

Remarks

Under Windows NT and Windows 95, the maximum number of files that an application can open is determined by the amount of available non-paged memory pool, because each open file handle requires non-paged memory.


SetHandleInformation

The SetHandleInformation function sets certain properties of an object handle. The information is specified as a set of bit flags.

BOOL SetHandleInformation (

HANDLE hObject,	// handle to an object
DWORD dwMask,	// specifies flags to change
DWORD dwFlags	// specifies new values for flags
);
Parameters

hObject

Specifies a handle to an object. The SetHandleInformation function sets information associated with this object handle.

dwMask

A mask that specifies the bit flags to be changed. Use the same flag constants shown in the description of dwFlags.

dwFlags

A set of bit flags that specify properties of the object handle. The following flags are defined:

Value	Meaning
HANDLE_FLAG_INHERIT	If this flag is set, a child process created with the bInheritHandles parameter of CreateProcess set to TRUE will inherit the object handle.
HANDLE_FLAG_PROTECT_FROM_CLOSE	If this flag is set, calling the CloseHandle function will not close the object handle.
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.

Remarks

Note that you must set a change mask bit flag in dwMask in order to set or clear the associated bit flag in dwFlags.

See Also

CreateProcess, CloseHandle, GetHandleInformation


SetICMMode

The SetICMMode function enables or disables image color matching for the specified device context.

int SetICMMode(

HDC hdc,
int fICM
);
Parameters

hdc

Handle to the device context.

fICM

Set to ICM_ON to turn on image color matching; ICM_OFF to turn it off; and ICM_QUERY to return the current mode.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

If ICM_QUERY is specified, the function returns ICM_ON or ICM_OFF to indicate the current mode.

Remarks

This function fails if an appropriate color profile cannot be found for the device.


SetICMProfile

The SetICMProfile function sets the color profile for the specified device context.

BOOL SetICMProfile(

HDC hdc,
LPTSTR lpFileName
);
Parameters

hdc

Handle to the device context.

lpFileName

Pointer to a null-terminated string that names the color profile file.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

GetICMProfile


SetJob

The SetJob function pauses, resumes, cancels, or restarts a print job on a specified printer. You can also use the SetJob function to set print job parameters, such as the print job priority and the document name.

Windows 95: You can use the SetJob function to give a command to a print job, or to set print job parameters, but you can not do both in the same call. Thus, when the Command parameter is non-zero, the function ignores the Level and pJob parameters. To set print job parameters, you must set Command to 0.

Windows NT: You can use the SetJob function to give a command to a print job, or to set print job parameters, or you can do both in the same call. The value of the Command parameter does not affect how the function uses the Level and pJob parameters.

BOOL SetJob(

HANDLE hPrinter,	// handle to printer object
DWORD JobId,	// print job identifier
DWORD Level,	// specifies type of job information structure
LPBYTE  pJob,	// pointer to job information structure
DWORD Command	// job command value
);
Parameters

hPrinter

Handle to the printer object of interest.

JobId

Identifier that specifies the print job. You obtain a print job identifier by calling the AddJob function or the StartDoc function.

Windows NT: If the Level parameter is set to 3, the JobId parameter must match the JobId member of the JOB_INFO_3 structure pointed to by pJob.

Level

Specifies the type of job information structure pointed to by the pJob parameter. You can set the Level parameter to 0, 1, or 2.

When you set Level to 0, pJob should be NULL. Use these values when you are not setting any print job parameters.

Windows NT: You can also set the Level parameter to 3.

Windows 95: The function pays attention to this parameter only if the Command parameter is 0. If Command is non-zero, the function ignores this parameter and the pJob parameter.

pJob

Pointer to a JOB_INFO_1 or JOB_INFO_2 structure. The function uses this structure to set print job parameters.

Windows NT: pJob can also point to a JOB_INFO_3 structure.

If the Level parameter is 0, pJob should be NULL.

If the Level parameter is 1, pJob should point to a JOB_INFO_1 structure. If the Level parameter is 2, pJob should point to a  JOB_INFO_2 structure.

Windows NT: If the Level parameter is 3, pJob should point to a JOB_INFO_3 structure. You must have JOB_ACCESS_ADMINISTER access permission for the jobs specified by the JobId and NextJobId members of the JOB_INFO_3 structure.

Windows 95: The function pays attention to this parameter only if the Command parameter is 0. If Command is non-zero, the function ignores this parameter and the Level parameter.

Command

Specifies the print job operation to perform. You can use one of the following values:

Value	Meaning
JOB_CONTROL_CANCEL	Delete the print job.
JOB_CONTROL_PAUSE	Pause the print job.
JOB_CONTROL_RESTART	Restart the print job. A job can only be restarted if it was printing.
JOB_CONTROL_RESUME	Resume a paused print job.
Windows 95: If you are using the SetJob function to set print job parameters, you must set the Command parameter to 0.

Windows NT: You can use the same call to the SetJob function to set print job parameters and to give a command to a print job. Thus, Command does not need to be 0 if you are setting print job parameters, although it can be.

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.

Remarks

You can use the SetJob function to set various print job parameters by supplying a pointer to a JOB_INFO_1, JOB_INFO_2, or JOB_INFO_3 structure that contains the necessary data.

Windows 95: When you use the function to set print job parameters, you must set the Command parameter to 0.

To remove or delete all of the print jobs for a particular printer, call the SetPrinter function with its Command parameter set to PRINTER_CONTROL_PURGE.

The following members of a JOB_INFO_1 or JOB_INFO_2 structure are ignored on a call to SetJob:

JobId, pPrinterName, pMachineName, pDrivername, Size, Submitted, and Time.

You must have PRINTER_ACCESS_ADMINISTER access permission for a printer in order to change a print job’s position in the print queue.

If you do not want to set a print job’s position in the print queue, you should set the Position member of the JOB_INFO_1 or JOB_INFO_2 structure to JOB_POSITION_UNSPECIFIED.

Windows NT: Use the SetJob function with the JOB_INFO_3 structure to link together a set of print jobs. This can be useful in situations where a single document consists of several parts that you want to render separately.

See Also

AddJob, GetJob, OpenPrinter, SetPrinter, JOB_INFO_1, JOB_INFO_2, JOB_INFO_3


SetKernelObjectSecurity

The SetKernelObjectSecurity function sets the security of a kernel object. For example, this can be a process, thread, or event.

BOOL SetKernelObjectSecurity(

HANDLE Handle,	// handle of object
SECURITY_INFORMATION SecurityInformation,	// type of information to set
PSECURITY_DESCRIPTOR SecurityDescriptor	// address of security descriptor
);
Parameters

Handle

Identifies a kernel object for which security information is set.

SecurityInformation

Specifies a SECURITY_INFORMATION structure identifying the contents of the security descriptor pointed to by the SecurityDescriptor parameter.

SecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure containing the new security information.

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.

Remarks

The SetKernelObjectSecurity function is successful only if the following conditions are met:

•	If the object’s owner is being set, the calling process must have either WRITE_OWNER permission or be the object’s owner.

•	If the object’s discretionary access-control list (ACL) is being set, the calling process must have either WRITE_DAC permission or be the object’s owner.

•	If the object’s system ACL is being set, the SE_SECURITY_NAME privilege must be enabled for the calling process.

See Also

GetKernelObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetFileSecurity, SetPrivateObjectSecurity, SetUserObjectSecurity


SetKeyboardState

The SetKeyboardState function copies a 256-byte array of keyboard key states into the calling thread’s keyboard-input state table. This is the same table accessed by the GetKeyboardState and GetKeyState functions. Changes made to this table do not affect keyboard input to any other thread.

BOOL SetKeyboardState(

LPBYTE lpKeyState	// address of array with virtual-key codes
);
Parameters

lpKeyState

Points to a 256-byte array that contains keyboard key states.

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.

Remarks

Because the SetKeyboardState function alters the input state of the calling thread and not the global input state of the system, an application cannot use SetKeyboardState to set the NUM LOCK, CAPS LOCK, or SCROLL LOCK indicator lights on the keyboard.

See Also

GetAsyncKeyState, GetKeyboardState, GetKeyState, MapVirtualKey


SetLastError

The SetLastError function sets the last-error code for the calling thread.

VOID SetLastError(

DWORD dwErrCode	// per-thread error code
);
Parameters

dwErrCode

Specifies the last-error code for the thread.

Remarks

Error codes are 32-bit values (bit 31 is the most significant bit). Bit 29 is reserved for application-defined error codes; no Win32 API error code has this bit set. If you are defining an error code for your application, set this bit to indicate that the error code has been defined by your application and to ensure that your error code does not conflict with any system-defined error codes.

This function is intended primarily for dynamic-link libraries (DLLs). Calling this function after an error occurs lets the DLL emulate the behavior of a Win32 function.

Most Win32 functions call SetLastError when they fail. Function failure is typically indicated by a return value error code such as FALSE, NULL, 0xFFFFFFFF, or −1. Some functions call SetLastError under conditions of success; those cases are noted in each function’s reference page.

Applications can retrieve the value saved by this function by using the GetLastError function. The use of GetLastError is optional; an application can call it to find out the specific reason for a function failure.

The last-error code is kept in thread local storage so that multiple threads do not overwrite each other’s values.

See Also

GetLastError, SetLastErrorEx, TlsGetValue


SetLastErrorEx

The SetLastErrorEx function sets the last-error code. In Windows 95 and in Windows NT, this function is identical to the SetLastError function. The second parameter is not implemented.

VOID SetLastErrorEx(

DWORD dwErrCode,	// per-thread error code
DWORD dwType	// error type
);
Parameters

dwErrCode

Specifies the last-error code for the thread.

dwType

Specifies the error type. If this process is being controlled by a debugging process, the debugger may take action based on the error type. This parameter can have one of the following values:

Value	Meaning
SLE_ERROR	Invalid data was passed to the function, and complete failure has occurred.
SLE_MINORERROR	Invalid data was passed to the function, but the function has recovered.
SLE_WARNING	Potentially invalid data was passed to the function, but the function has recovered.
0	The last-error code is set without reporting anything to the debugger. Specifying this value is equivalent to using the SetLastError function.
Remarks

Error codes are 32-bit values (bit 31 is the most significant bit). Bit 29 is reserved for application-defined error codes; no Win32 API error code has this bit set. If you are defining an error code for your application, set this bit to indicate that the error code has been defined by the application and to ensure that your error code does not conflict with any system-defined error codes.

This function is intended primarily for dynamic-link libraries (DLLs). Calling this function after an error occurs allows the DLL to emulate the behavior of the Win32 API.

Most Win32 functions call SetLastError when they fail. Function failure is typically indicated by a return value error code such as FALSE, NULL, 0xFFFFFFFF, or −1. Some functions call SetLastError under conditions of success; those cases are noted in each function’s reference page.

Applications can retrieve the value saved by this function by using the GetLastError function.

The last-error code is kept in thread local storage so that multiple threads do not overwrite each other’s values.

See Also

GetLastError, SetLastError


SetLocaleInfo

The SetLocaleInfo function sets an item of locale information. It does so by making an entry in the process portion of the locale table. This setting only affects the user override portion of the locale settings; it does not set the system defaults.

Only certain types of locale information, or LCTYPE values, can be set by this function. See the following Remarks section for a list of valid LCTYPE values.

The locale information is always passed in as a null-terminated Unicode string in the Unicode (W) version of the function, and as a null-terminated ANSI string in the ANSI (A) version. No integers are allowed by this function; any numeric values must be specified as Unicode or ANSI text. Each LCTYPE has a particular format, as noted in Locale Identifiers.

BOOL SetLocaleInfo(

LCID Locale,	// locale identifier
LCTYPE LCType,	// type of information to set
LPCTSTR lpLCData	// pointer to information to set
);
Parameters

Locale

Specifies the locale whose information the function will set.

LCType

Specifies the type of locale information to be set by the function. Note that only one LCTYPE may be specified per call. Not all LCTYPE values are valid; see the list of valid LCTYPE values in the following Remarks section.

lpLCData

Points to a null-terminated string containing the locale information the function will set. This should be an LPWSTR for the Unicode (W) version of the function, and an LPSTR for the ANSI (A) version. The information must be in the specified LCTYPE’s particular format.

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 one of the following error codes:

ERROR_INVALID_ACCESS
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER
Remarks

The following LCTYPE values are valid for this function:

LOCALE_ICALENDARTYPE	LOCALE_SDATE
LOCALE_ICURRDIGITS	LOCALE_SDECIMAL
LOCALE_ICURRENCY	LOCALE_SGROUPING
LOCALE_IDIGITS	LOCALE_SLIST
LOCALE_IFIRSTDAYOFWEEK	LOCALE_SLONGDATE
LOCALE_IFIRSTWEEKOFYEAR	LOCALE_SMONDECIMALSEP
LOCALE_ILZERO	LOCALE_SMONGROUPING
LOCALE_IMEASURE	LOCALE_SMONTHOUSANDSEP
LOCALE_INEGCURR	LOCALE_SNEGATIVESIGN
LOCALE_INEGNUMBER	LOCALE_SPOSITIVESIGN
LOCALE_ITIME	LOCALE_SSHORTDATE
LOCALE_S1159	LOCALE_STHOUSAND
LOCALE_S2359	LOCALE_STIME
LOCALE_SCURRENCY	LOCALE_STIMEFORMAT
See Also

GetLocaleInfo


SetLocalTime

The SetLocalTime function sets the current local time and date.

BOOL SetLocalTime(

CONST SYSTEMTIME *lpSystemTime	// address of local time to set
);
Parameters

lpSystemTime

Points to a SYSTEMTIME structure that contains the current local date and time.

The wDayOfWeek member of the SYSTEMTIME structure is ignored.

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.

Remarks

Windows NT: The SetLocalTime function fails if the calling process does not have the SE_SYSTEMTIME_NAME privilege. This privilege is disabled by default. Use the AdjustTokenPrivileges function to enable this privilege and again to disable it after the time has been set. For more information about security privileges, see Privileges.

Windows 95: Security privileges are not supported or required.

See Also

AdjustTokenPrivileges, GetLocalTime, GetSystemTime, SetSystemTimeAdjustment, SYSTEMTIME


SetMailslotInfo

The SetMailslotInfo function sets the time-out value used by the specified mailslot for a read operation.

BOOL SetMailslotInfo(

HANDLE hMailslot,	// mailslot handle
DWORD lReadTimeout	// read time-out
);
Parameters

hMailslot

Identifies a mailslot. The CreateMailslot function must create this handle.

lReadTimeout

Specifies the amount of time, in milliseconds, a read operation can wait for a message to be written to the mailslot before a time-out occurs. The following values have special meanings:

Value	Meaning
0	Returns immediately if no message is present. (The system does not treat an immediate return as an error.)
MAILSLOT_WAIT_FOREVER	Waits forever for a message.
This time-out value applies to all subsequent read operations and to all inherited mailslot handles.

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.

Remarks

The initial time-out value used by a mailslot for a read operation is typically set by CreateMailslot when the mailslot is created.

See Also

CreateMailslot, GetMailslotInfo


SetMapMode

The SetMapMode function sets the mapping mode of the specified device context. The mapping mode defines the unit of measure used to transform page-space units into device-space units, and also defines the orientation of the device’s x and y axes.

int SetMapMode(

HDC hdc,	// handle of device context
int fnMapMode	// new mapping mode
);
Parameters

hdc

Identifies the device context.

fnMapMode

Specifies the new mapping mode. It can be any one of the following values:

Value	Description
MM_ANISOTROPIC	Logical units are mapped to arbitrary units with arbitrarily scaled axes. Use the SetWindowExtEx and SetViewportExtEx functions to specify the units, orientation, and scaling that you want.
MM_HIENGLISH	Each logical unit is mapped to 0.001 inch. Positive x is to the right; positive y is up.
MM_HIMETRIC	Each logical unit is mapped to 0.01 millimeter. Positive x is to the right; positive y is up.
MM_ISOTROPIC	Logical units are mapped to arbitrary units with equally scaled axes; that is, one unit along the x-axis is equal to one unit along the y-axis. Use the SetWindowExtEx and SetViewportExtEx functions to specify the units and the orientation of the axes that you want. Graphics device interface (GDI) makes adjustments as necessary to ensure the x and y units remain the same size (for example, if you set the window extent, the viewport will be adjusted to keep the units isotropic).
MM_LOENGLISH	Each logical unit is mapped to 0.01 inch. Positive x is to the right; positive y is up.
MM_LOMETRIC	Each logical unit is mapped to 0.1 millimeter. Positive x is to the right; positive y is up.
MM_TEXT	Each logical unit is mapped to one device pixel. Positive x is to the right; positive y is down.
MM_TWIPS	Each logical unit is mapped to one twentieth of a printer’s point (1/1440 inch, also called a “twip”). Positive x is to the right; positive y is up.
Return Values

If the function succeeds, the return value identifies the previous mapping mode.

If the function fails, the return value is zero.

Remarks

The MM_TEXT mode allows applications to work in device pixels, whose size varies from device to device.

The MM_HIENGLISH, MM_HIMETRIC, MM_LOENGLISH, MM_LOMETRIC, and MM_TWIPS modes are useful for applications drawing in physically meaningful units (such as inches or millimeters).

The MM_ISOTROPIC mode ensures a 1:1 aspect ratio.

The MM_ANISOTROPIC mode allows the x-coordinates and y-coordinates to be adjusted independently.

See Also

GetMapMode, SetViewportExtEx, SetViewportOrgEx, SetWindowExtEx, SetWindowOrgEx


SetMapperFlags

The SetMapperFlags function alters the algorithm the font mapper uses when it maps logical fonts to physical fonts.

DWORD SetMapperFlags(

HDC hdc,	// handle of device context
DWORD dwFlag	// font-mapper flag
);
Parameters

hdc

Identifies the device context that contains the font-mapper flag.

dwFlag

Specifies whether the font mapper should attempt to match a font’s aspect ratio to the current device’s aspect ratio. If bit zero is set, the mapper selects only matching fonts.

Return Values

If the function succeeds, the return value is the previous value of the font-mapper flag.

If the function fails, the return value is GDI_ERROR. To get extended error information, call GetLastError.

Remarks

If the dwFlag parameter is set and no matching fonts exist, Windows chooses a new aspect ratio and retrieves a font that matches this ratio.

The remaining bits of the dwFlag parameter must be zero.

See Also

GetAspectRatioFilterEx


SetMenu

The SetMenu function assigns a new menu to the specified window.

BOOL SetMenu(

HWND hWnd,	// handle of window
HMENU hMenu	// handle of menu
);
Parameters

hWnd

Identifies the window to which the menu is to be assigned.

hMenu

Identifies the new menu. If this parameter is NULL, the window’s current menu is removed.

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.

Remarks

The window is redrawn to reflect the menu change.

The SetMenu function replaces the previous menu, if any, but it does not destroy it. An application should call the DestroyMenu function to accomplish this task.

See Also

DestroyMenu, GetMenu


SetMenuContextHelpId

The SetMenuContextHelpId function associates a help context identifier with a menu. All items in the menu share this identifier. It is not possible to attach a help context identifier to the individual menu items.

BOOL SetMenuContextHelpId(

HMENU hmenu,
DWORD dwContextHelpId
);
Parameters

hmenu

Handle to the menu with which to associate the help context identifier.

dwContextHelpId

Help context identifier.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

GetMenuContextHelpId


SetMenuDefaultItem [Now Supported on Windows NT]
SetMenuDefaultItem

[Now Supported on Windows NT]

The SetMenuDefaultItem function sets the default menu item for the specified menu.

BOOL SetMenuDefaultItem(

HMENU hMenu,
UINT uItem,
UINT fByPos
);
Parameters

hMenu

Handle to the menu to set the default item for.

uItem

Identifier or position of the new default menu item or − 1 for no default item. The meaning of this parameter depends on the value of fByPos.

fByPos

Value specifying the meaning of uItem. If this parameter is FALSE, uItem is a menu item identifier. Otherwise, it is a menu item position.

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, use the GetLastError function.

See Also

GetMenuDefaultItem


SetMenuItemBitmaps

The SetMenuItemBitmaps function associates the specified bitmap with a menu item. Whether the menu item is checked or unchecked, Windows displays the appropriate bitmap next to the menu item.

BOOL SetMenuItemBitmaps(

HMENU hMenu,	// handle of menu
UINT uPosition,	// menu item to receive new bitmaps
UINT uFlags,	// menu item flags
HBITMAP hBitmapUnchecked,	// handle of unchecked bitmap
HBITMAP hBitmapChecked	// handle of checked bitmap
);
Parameters

hMenu

Identifies the menu containing the item to receive new check mark bitmaps.

uPosition

Specifies the menu item to be changed, as determined by the uFlags parameter.

uFlags

Specifies how the uPosition parameter is interpreted. The uFlags parameter must be one of the following values:

Value	Meaning
MF_BYCOMMAND	Indicates that uPosition gives the identifier of the menu item. If neither MF_BYCOMMAND nor MF_BYPOSITION is specified, MF_BYCOMMAND is the default flag.
MF_BYPOSITION	Indicates that uPosition gives the zero-based relative position of the menu item.
hBitmapUnchecked

Identifies the bitmap displayed when the menu item is not checked.

hBitmapChecked

Identifies the bitmap displayed when the menu item is checked.

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.

Remarks

If either the hBitmapUnchecked or hBitmapChecked parameter is NULL, Windows displays nothing next to the menu item for the corresponding check state. If both parameters are NULL, Windows displays the default check mark bitmap when the item is checked and removes the bitmap when the item is not checked.

When the menu is destroyed, these bitmaps are not destroyed; it is up to the application to destroy them.

Windows NT: The GetMenuCheckMarkDimensions function retrieves the dimensions of the default check mark used for menu items. These values are used to determine the appropriate size for the bitmaps supplied with this function.

Windows 95: GetMenuCheckMarkDimensions is obsolete. Use GetsystemMetrics with the CXMENUCHECK and CYMENUCHECK values to retrieve the bitmap dimensions.

See Also

GetMenu, GetMenuCheckMarkDimensions


SetMenuItemInfo [Now Supported on Windows NT]
SetMenuItemInfo

[Now Supported on Windows NT]

The SetMenuItemInfo function changes information about a menu item.

BOOL WINAPI SetMenuItemInfo(

HMENU hMenu,
UINT uItem,
BOOL fByPosition,
LPMENUITEMINFO lpmii
);
Parameters

hMenu

Handle to the menu that contains the menu item.

uItem

Identifier or position of the menu item to change. The meaning of this parameter depends on the value of fByPosition.

fByPosition

Value specifying the meaning of uItem. If this parameter is FALSE, uItem is a menu item identifier. Otherwise, it is a menu item position.

lpmii

Pointer to a MENUITEMINFO structure that contains information about the menu item and specifies which menu item attributes to change.

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, use the GetLastError function.

See Also

GetMenuItemInfo, MENUITEMINFO


SetMessageExtraInfo

The SetMessageExtraInfo function sets the extra message information for the current thread. Extra message information is an application- or driver-defined 32-bit value associated with the current thread’s message queue. An application can use the GetMessageExtraInfo function to retrieve a thread’s extra message information.

LPARAM SetMessageExtraInfo(

LPARAM lParam	// application-defined 32-bit value
);
Parameters

lParam

Specifies the 32-bit value to associate with the current thread.

Return Values

The return value is the previous 32-bit value.

See Also

GetMessageExtraInfo


SetMessageQueue

The SetMessageQueue function is obsolete. This function is provided only for compatibility for 16-bit versions of Windows. This function does nothing on Win32 platforms, because message queues are expanded dynamically as necessary.


SetMetaFileBitsEx

The SetMetaFileBitsEx function creates a memory-based Windows-format metafile from the supplied data.

This function is provided for compatibility with earlier versions of Microsoft Windows. Win32-based applications should use the SetEnhMetaFileBits function.

HMETAFILE SetMetaFileBitsEx(

UINT nSize,	// size of Windows-format metafile
CONST BYTE *lpData	// address of buffer containing metafile data
);
Parameters

nSize

Specifies the size, in bytes, of the Windows-format metafile.

lpData

Points to a buffer that contains the Windows-format metafile. (It is assumed that the data was obtained by using the GetMetaFileBitsEx function.)

Return Values

If the function succeeds, the return value is a handle of a memory-based Windows-format metafile.

If the function fails, the return value is NULL.

Remarks

A Windows-format metafile does not support the new curve, path, and transformation functions such as PolyBezier, BeginPath, and SetWorldTransform. Applications that use these new functions and use metafiles to store pictures created by these functions should use the enhanced-format metafile functions.

To convert a Windows-format metafile into an enhanced-format metafile, use the SetWinMetaFileBits function.

When the application no longer needs the metafile handle returned by SetMetaFileBitsEx, it should delete it by calling the DeleteMetaFile function.

See Also

BeginPath, DeleteMetaFile, GetMetaFileBitsEx, PolyBezier, SetEnhMetaFileBits, SetWinMetaFileBits, SetWorldTransform


SetMetaRgn

The SetMetaRgn function intersects the current clipping region for the specified device context with the current metaregion and saves the combined region as the new metaregion for the specified device context. The clipping region is reset to a null region.

int SetMetaRgn(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Values

If the function succeeds, the return value specifies the new clipping region’s complexity and can be any one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
ERROR	An error occurred. (The previous clipping region is unaffected.)
Remarks

The current clipping region of a device context is defined by the intersection of its clipping region and its metaregion.

The SetMetaRgn function should only be called after an application’s original device context was saved by calling the SaveDC function.

See Also

GetMetaRgn, SaveDC


SetMiterLimit

The SetMiterLimit function sets the limit for the length of miter joins for the specified device context.

BOOL SetMiterLimit(

HDC hdc,	// handle of device context
FLOAT eNewLimit,	// new miter limit
PFLOAT peOldLimit	// previous miter limit
);
Parameters

hdc

Identifies the device context.

eNewLimit

Specifies the new miter limit for the device context.

peOldLimit

Points to a floating-point value that receives the previous miter limit. If this parameter is NULL, the previous miter limit is not returned.

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.

Remarks

The miter length is defined as the distance from the intersection of the line walls on the inside of the join to the intersection of the line walls on the outside of the join. The miter limit is the maximum allowed ratio of the miter length to the line width.

The default miter limit is 10.0.

See Also

ExtCreatePen, GetMiterLimit


SetNamedPipeHandleState

The SetNamedPipeHandleState function sets the read mode and the blocking mode of the specified named pipe. If the specified handle is to the client end of a named pipe and if the named pipe server process is on a remote computer, the function can also be used to control local buffering.

BOOL SetNamedPipeHandleState(

HANDLE hNamedPipe,	// handle of named pipe
LPDWORD lpMode,	// address of new pipe mode
LPDWORD lpMaxCollectionCount,	// address of max. bytes before remote transmission
LPDWORD lpCollectDataTimeout	// address of max. time before remote transmission
);
Parameters

hNamedPipe

Identifies the named pipe instance. This parameter can be a handle to the server end of the pipe, as returned by the CreateNamedPipe function, or to the client end of the pipe, as returned by the CreateFile function. The handle must have GENERIC_WRITE access to the named pipe.

lpMode

Points to a 32-bit variable that supplies the new mode. The mode is a combination of a read-mode flag and a wait-mode flag. This parameter can be NULL if the mode is not being set. One of the following read modes can be specified:

Mode	Description
PIPE_READMODE_BYTE	Data is read from the pipe as a stream of bytes. This mode is the default if no read-mode flag is specified.
PIPE_READMODE_MESSAGE	Data is read from the pipe as a stream of messages. The function fails if this flag is specified for a byte-type pipe.
One of the following wait modes can be specified:

Mode	Description
PIPE_WAIT	Blocking mode is enabled. This mode is the default if no wait-mode flag is specified. When a blocking mode pipe handle is specified in the ReadFile, WriteFile, or ConnectNamedPipe function, operations are not finished until there is data to read, all data is written, or a client is connected. Use of this mode can mean waiting indefinitely in some situations for a client process to perform an action.
PIPE_NOWAIT	Nonblocking mode is enabled. In this mode, ReadFile, WriteFile, and ConnectNamedPipe always return immediately. Note that nonblocking mode is supported for compatibility with Microsoft® LAN Manager version 2.0 and should not be used to achieve asynchronous input and output (I/O) with named pipes.
lpMaxCollectionCount

Points to a 32-bit variable that specifies the maximum number of bytes collected on the client computer before transmission to the server. This parameter must be NULL if the specified pipe handle is to the server end of a named pipe or if client and server processes are on the same machine. This parameter is ignored if the client process specifies the FILE_FLAG_WRITE_THROUGH flag in the CreateFile function when the handle was created. This parameter can be NULL if the collection count is not being set.

lpCollectDataTimeout

Points to a 32-bit variable that specifies the maximum time, in milliseconds, that can pass before a remote named pipe transfers information over the network. This parameter must be NULL if the specified pipe handle is to the server end of a named pipe or if client and server processes are on the same computer. This parameter is ignored if the client process specified the FILE_FLAG_WRITE_THROUGH flag in the CreateFile function when the handle was created. This parameter can be NULL if the collection count is not being set.

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.

See Also

ConnectNamedPipe, CreateFile, CreateNamedPipe, GetNamedPipeHandleState, ReadFile, WriteFile


SetNamedSecurityInfo [New - Windows NT]
SetNamedSecurityInfo

[New - Windows NT]

The SetNamedSecurityInfo function sets specified security information in the security descriptor of a specified object. The caller identifies the object by name.

DWORD SetNamedSecurityInfo(

LPTSTR pObjectName,	// name of the object
SE_OBJECT_TYPE ObjectType,	// type of object
SECURITY_INFORMATION SecurityInfo,	// type of security information to set
PSID psidOwner,	// pointer to the new owner SID
PSID psidGroup,	// pointer to the new primary group SID
PACL pDacl,	// pointer to the new DACL
PACL pSacl	// pointer to the new SACL
);
Parameters

pObjectName

Pointer to a null-terminated string that specifies the name of the object for which to set security information. This can be the name of a local or remote file or directory on a NTFS file system, Windows NT network sharename, registry key, semaphore, event, mutex, file mapping, or waitable timer.

For descriptions of the string formats for the different object types, see SE_OBJECT_TYPE.

ObjectType

Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName parameter.

SecurityInfo

A set of SECURITY_INFORMATION bit flags that indicate the type of security information to set. This parameter can be a combination of the following values.

Value	Meaning
OWNER_SECURITY_INFORMATION	Set the owner security identifier (SID) in the object’s security descriptor. The psidOwner parameter points to the new SID.
GROUP_SECURITY_INFORMATION	Set the primary group SID in the object’s security descriptor. The psidGroup parameter points to the new SID.
DACL_SECURITY_INFORMATION	Set the discretionary access-control list (DACL) in the object’s security descriptor. The pDacl parameter points to the new DACL.
SACL_SECURITY_INFORMATION	Set the system access-control list (SACL) in the object’s security descriptor. The pSacl parameter points to the new SACL.
psidOwner

Pointer to a SID that identifies the object’s owner. The SID must be one that can be assigned as the owner SID of a security descriptor. The SecurityInfo parameter must include the OWNER_SECURITY_INFORMATION flag. The caller must have WRITE_OWNER access to the object or have the SE_TAKE_OWNERSHIP_NAME privilege enabled. This parameter can be NULL if you are not setting the owner SID.

psidGroup

Pointer to a SID that identifies the object’s primary group. The SecurityInfo parameter must include the GROUP_SECURITY_INFORMATION flag. This parameter can be NULL if you are not setting the primary group SID.

pDacl

Pointer to the new DACL for the object. The SecurityInfo parameter must include the DACL_SECURITY_INFORMATION flag. The caller must have WRITE_DAC access to the object or be the object’s owner. This parameter can be NULL if you are not setting the DACL.

pSacl

Pointer to the new SACL for the object. The SecurityInfo parameter must include the SACL_SECURITY_INFORMATION flag. The caller must have the SE_SECURITY_NAME privilege enabled. This parameter can be NULL if you are not setting the SACL.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H.

See Also

ACL, GetNamedSecurityInfo, GetSecurityInfo, SE_OBJECT_TYPE, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetSecurityInfo, SID


SetPaletteEntries

The SetPaletteEntries function sets RGB (red, green, blue) color values and flags in a range of entries in a logical palette.

UINT SetPaletteEntries(

HPALETTE hpal,	// handle of logical palette
UINT iStart,	// index of first entry to set
UINT cEntries,	// number of entries to set
CONST PALETTEENTRY *lppe	// address of array of structures
);
Parameters

hpal

Identifies the logical palette.

iStart

Specifies the first logical-palette entry to be set.

cEntries

Specifies the number of logical-palette entries to be set.

lppe

Points to the first member of an array of PALETTEENTRY structures containing the RGB values and flags.

Return Values

If the function succeeds, the return value is the number of entries that were set in the logical palette.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

An application can determine whether or not a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

Even if a logical palette has been selected and realized, changes to the palette do not affect the physical palette in the surface. RealizePalette must be called again to set the new logical palette into the surface.

See Also

GetDeviceCaps, GetPaletteEntries, RealizePalette, PALETTEENTRY


SetParent

The SetParent function changes the parent window of the specified child window.

HWND SetParent(

HWND hWndChild,	// handle of window whose parent is changing
HWND hWndNewParent	// handle of new parent window
);
Parameters

hWndChild

Identifies the child window.

hWndNewParent

Identifies the new parent window. If this parameter is NULL, the desktop window becomes the new parent window.

Return Values

If the function succeeds, the return value is the handle of the previous parent window.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

An application can use the SetParent function to set the parent window of a pop-up, overlapped, or child window. The new parent window and the child window must belong to the same application.

If the window identified by the hWndChild parameter is visible, Windows performs the appropriate redrawing and repainting.

See Also

GetParent


SetPixel

The SetPixel function sets the pixel at the specified coordinates to the specified color.

COLORREF SetPixel(

HDC hdc,	// handle of device context
int X,	// x-coordinate of pixel
int Y,	// y-coordinate of pixel
COLORREF crColor	// pixel color
);
Parameters

hdc

Identifies the device context.

X

Specifies the x-coordinate, in logical units, of the point to be set.

Y

Specifies the y-coordinate, in logical units, of the point to be set.

crColor

Specifies the color to be used to paint the point.

Return Values

If the function succeeds, the return value is the RGB value that the function sets the pixel to. This value may differ from the color specified by crColor; that happens when an exact match for the specified color cannot be found.

If the function fails, the return value is −1. To get extended error information, call GetLastError.

Remarks

The function fails if the pixel coordinates lie outside of the current clipping region.

Not all devices support the SetPixel function. For more information, see GetDeviceCaps.

See Also

GetDeviceCaps, GetPixel, SetPixelV


SetPixelV

The SetPixelV function sets the pixel at the specified coordinates to the closest approximation of the specified color. The point must be in the clipping region and the visible part of the device surface.

BOOL SetPixelV(

HDC hdc,	// handle of device context
int X,	// x-coordinate of pixel
int Y,	// y-coordinate of pixel
COLORREF crColor	// new pixel color
);
Parameters

hdc

Identifies the device context.

X

Specifies the x-coordinate, in logical units, of the point to be set.

Y

Specifies the y-coordinate, in logical units, of the point to be set.

crColor

Specifies the color to be used to paint the point.

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.

Remarks

Not all devices support the SetPixelV function. For more information, see the description of the RC_BITBLT capability in the GetDeviceCaps function.

SetPixelV is faster than SetPixel because it does not need to return the color value of the point actually painted.

See Also

GetDeviceCaps, SetPixel


SetPolyFillMode

The SetPolyFillMode function sets the polygon fill mode for functions that fill polygons.

int SetPolyFillMode(

HDC hdc,	// handle of device context
int iPolyFillMode	// polygon fill mode
);
Parameters

hdc

Identifies the device context.

iPolyFillMode

Specifies the new fill mode. This parameter can be either of the following values:

Value	Meaning
ALTERNATE	Selects alternate mode (fills the area between odd-numbered and even-numbered polygon sides on each scan line).
WINDING	Selects winding mode (fills any region with a nonzero winding value).
Return Values

The return value specifies the previous filling mode. If an error occurs, the return value is zero.

Remarks

In general, the modes differ only in cases where a complex, overlapping polygon must be filled (for example, a five-sided polygon that forms a five-pointed star with a pentagon in the center). In such cases, ALTERNATE mode fills every other enclosed region within the polygon (that is, the points of the star), but WINDING mode fills all regions (that is, the points and the pentagon).

When the fill mode is ALTERNATE, GDI fills the area between odd-numbered and even-numbered polygon sides on each scan line. That is, GDI fills the area between the first and second side, between the third and fourth side, and so on.

When the fill mode is WINDING, GDI fills any region that has a nonzero winding value. This value is defined as the number of times a pen used to draw the polygon would go around the region. The direction of each edge of the polygon is important.

See Also

GetPolyFillMode


SetPort [New - Windows NT]
SetPort

[New - Windows NT]

The SetPort function sets the status associated with a printer port.

BOOL SetPort(

LPTSTR pName,	// pointer to a printer server name
LPTSTR pPortName,	// pointer to a printer port name
DWORD dwLevel,	// version of PORT_INFO_* structure
LPBYTE pPortInfo	// pointer to a PORT_INFO_* structure
);
Parameters

pName

Pointer to a zero-terminated string that specifies the name of the printer server to which the port is connected. Set this parameter to NULL if the port is on the local machine.

pPortName

Pointer to a zero-terminated string that specifies the name of the printer port.

dwLevel

Specifies the type of PORT_INFO_* structure pointed to by the pPortInfo parameter.

This value must be 3, which corresponds to a PORT_INFO_3 data structure.

pPortInfo

Pointer to a PORT_INFO_3 structure that contains the port status information to set.

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.

Remarks

The caller of the SetPort function must have SERVER_ACCESS_ADMINISTER access to the server to which the port is connected.

When you set a printer port status value with the severity value PORT_STATUS_TYPE_ERROR, the print spooler stops sending jobs to the port. The print spooler resumes sending jobs to the port when the port status is cleared by another call to SetPort.

See Also

PORT_INFO_3


SetPrinter

The SetPrinter function sets the state of the specified printer by pausing printing, resuming printing, or clearing all print jobs. The function can also be used to set printer data.

BOOL SetPrinter(

HANDLE hPrinter,	// handle of printer object
DWORD Level,	// structure level
LPBYTE pPrinter,	// address of array containing printer data
DWORD Command	// printer-state command
);
Parameters

hPrinter

Handle to the printer of interest.

Level

Windows 95: Specifies the type of data contained in pPrinter. This parameter must be 0, 2, 3, 4, or 5. This parameter must be zero if Command is not equal to zero.

Windows NT: Specifies the type of data contained in pPrinter. This parameter must be 0, 2, 3, 5, or 6. This parameter must be zero if Command is not equal to zero.

pPrinter

This is either a DWORD value indicating the printer status, or a pointer to an array of bytes that may contain printer data.

If Level is 0, and the Command parameter is PRINTER_CONTROL_SET_STATUS, pPrinter must contain a DWORD value that specifies the new printer status to set. For a list of the possible status values, see the Status member of the PRINTER_INFO_2 structure. Note that PRINTER_STATUS_PAUSED and PRINTER_STATUS_PENDING_DELETION are not valid status values to set.

If Level is 0, but the Command parameter is not PRINTER_CONTROL_SET_STATUS, pPrinter must be NULL.

Windows 95: If Level is 2, 3, 4, or 5, pPrinter points to an array that contains PRINTER_INFO_2, PRINTER_INFO_3, PRINTER_INFO_4, or PRINTER_INFO_5 structures, respectively.

Windows NT: If Level is 2, 3, 5, or 6, pPrinter points to an array that contains PRINTER_INFO_2,  PRINTER_INFO_3, PRINTER_INFO_5, or PRINTER_INFO_6 structures, respectively.

Command

This parameter can be zero or one of the following values. If it is zero, the printer retains its original state and the printer data is reconfigured by using the structure to which pPrinter points.

Value	Meaning
PRINTER_CONTROL_PAUSE	Pauses the printer.
PRINTER_CONTROL_PURGE	Deletes all print jobs in the printer.
PRINTER_CONTROL_RESUME	Resumes a paused printer.
PRINTER_CONTROL_SET_STATUS	Sets the printer status.
If Command is any of the above values, Level must be zero.

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.

Remarks

You can obtain the handle hPrinter is by calling the OpenPrinter function.

To modify the current printer settings, an application should call GetPrinter to retrieve the current settings into a PRINTER_INFO_2 structure, modify the members of that structure as necessary, and then call the SetPrinter function.

The SetPrinter function ignores the following members of a PRINTER_INFO_2 structure:

pServerName, AveragePPM, Status, and cJobs

Pausing a printer suspends scheduling of all print jobs for that printer, except for the one print job that may be currently printing. Print jobs can be submitted to a paused printer, but no jobs will be scheduled to print on that printer until printing is resumed. If a printer is cleared, all print jobs for that printer are deleted, except for the current print job.

If the printer data structure contains a pointer to a security descriptor, only those components of the security descriptor that the caller has permission to write should be present. An application that wants to write particular security descriptor components must open the printer with sufficient access permission to modify those components. The following table shows the security descriptor components that can be modified for particular access permission values:

Access Permission	Modifiable Security Descriptor Components
WRITE_OWNER	Owner, primary proup
WRITE_DAC	Discretionary access-control list (ACL)
ACCESS_SYSTEM_SECURITY	System ACL
If the calling application lacks a required permission, SetPrinter fails. Those components of a security descriptor that an application does not wish to modify should be NULL or not be present, as appropriate. If you do not want to modify the security descriptor, and are calling SetPrinter with a PRINTER_INFO_2 structure, set the pSecurityDescriptor member of that structure to NULL.

Windows 95: SetPrinter does not update the pShareName member in the PRINTER_INFO_2 structure.

Windows 95: SetPrinter is not supported when called against a Windows NT printer from a Windows 95 machine using the printer's UNC name.

See Also

AddPrinter, GetPrinter, OpenPrinter, PRINTER_INFO_2, PRINTER_INFO_3, PRINTER_INFO_4, PRINTER_INFO_5, PRINTER_INFO_6


SetPrinterData

The SetPrinterData function sets the configuration data for a printer.

DWORD SetPrinterData(

HANDLE hPrinter,	// handle of printer object
LPTSTR pValueName,	// address of data type
DWORD Type,	// flag for value type
LPBYTE pData,	// address of array that specifies printer data
DWORD cbData	// size, in bytes, of array
);
Parameters

hPrinter

Identifies the printer for which the configuration data should be set.

pValueName

Points to a null-terminated string that specifies the type of data to be set.

Type

Specifies the type of information to be stored as the value’s data. This parameter can be one of the following values:

Value	Meaning
REG_BINARY	Binary data in any form.
REG_DWORD	A 32-bit number.
REG_DWORD_LITTLE_ENDIAN	A 32-bit number in little-endian format (same as REG_DWORD). In little-endian format, the most significant byte of a word is the high-order byte. This is the most common format for computers running Windows NT and Windows 95.
REG_DWORD_BIG_ENDIAN	A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low-order byte.
REG_EXPAND_SZ	A null-terminated string that contains unexpanded references to environment variables (for example, “%PATH%”). It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
REG_LINK	A Unicode symbolic link.
REG_MULTI_SZ	An array of null-terminated strings, terminated by two null characters.
REG_NONE	No defined value type.
REG_RESOURCE_LIST	A device-driver resource list.
REG_SZ	A null-terminated string. It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
pData

Points to an array of bytes that contains the printer configuration data.

cbData

Specifies the size, in bytes, of the array.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

The handle hPrinter is obtained by calling the OpenPrinter function.

Existing configuration data for a printer can be retrieved by calling the GetPrinter function.

See Also

GetPrinter, GetPrinterData, OpenPrinter


SetPriorityClass

The SetPriorityClass function sets the priority class for the specified process. This value together with the priority value of each thread of the process determines each thread’s base priority level.

BOOL SetPriorityClass(

HANDLE hProcess,	// handle to the process
DWORD dwPriorityClass	// priority class value
);
Parameters

hProcess

Identifies the process.

Windows NT: The handle must have the PROCESS_SET_INFORMATION access right. For more information, see Process Objects.

dwPriorityClass

Specifies the priority class for the process. Specify one of the following values:

Priority	Meaning
HIGH_PRIORITY_CLASS	Specify this class for a process that performs time-critical tasks that must be executed immediately. The threads of the process preempt the threads of normal or idle priority class processes. An example is Windows Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class application can use nearly all available CPU time.
IDLE_PRIORITY_CLASS	Specify this class for a process whose threads run only when the system is idle. The threads of the process are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle-priority class is inherited by child processes.
NORMAL_PRIORITY_CLASS	Specify this class for a process with no special scheduling needs.
REALTIME_PRIORITY_CLASS	Specify this class for a process that has the highest possible priority. The threads of the process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.
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.

Remarks

Every thread has a base priority level determined by the thread’s priority value and the priority class of its process. The system uses the base priority level of all executable threads to determine which thread gets the next slice of CPU time. The SetThreadPriority function enables setting the base priority level of a thread relative to the priority class of its process. For more information, see Scheduling Priorities.

See Also

CreateProcess, CreateThread, GetPriorityClass, GetThreadPriority, SetThreadPriority


SetPrivateObjectSecurity

The SetPrivateObjectSecurity function modifies a private object’s security descriptor.

BOOL SetPrivateObjectSecurity(

SECURITY_INFORMATION SecurityInformation,	// type of security information
PSECURITY_DESCRIPTOR ModificationDescriptor,	// address of SD to apply to object
PSECURITY_DESCRIPTOR *ObjectsSecurityDescriptor,	// address of object’s SD
PGENERIC_MAPPING GenericMapping,	// address of access-mapping structure
HANDLE Token	// handle of client access token
);
Parameters

SecurityInformation

Specifies a SECURITY_INFORMATION structure identifying the contents of the security descriptor pointed to by the ModificationDescriptor parameter.

ModificationDescriptor

Points to a SECURITY_DESCRIPTOR structure to be applied to the object.

ObjectsSecurityDescriptor

Points to a pointer to a SECURITY_DESCRIPTOR structure to be altered by this function. This security descriptor must be in self-relative form.

GenericMapping

Points to a GENERIC_MAPPING structure specifying the mapping of generic to specific and standard access types for the object.

Token

Identifies the access token for the client on whose behalf the private object’s security is being modified. This parameter is required to ensure that the client has provided a legitimate value for a new owner security identifier (SID). The token must be open for TOKEN_QUERY access.

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.

Remarks

The object’s security descriptor must be in self-relative form.

If necessary, the SetPrivateObjectSecurity function allocates additional memory to produce a larger security descriptor.

The SetPrivateObjectSecurity function is successful only if the following conditions are met:

•	If the object’s owner is being set, the calling process must have either WRITE_OWNER permission or be the object’s owner.

•	If the object’s discretionary access-control list (ACL) is being set, the calling process must have either WRITE_DAC permission or be the object’s owner.

•	If the object’s system ACL is being set, the SE_SECURITY_NAME privilege must be enabled for the calling process.

The process calling this function must not be impersonating a client.

See Also

CreatePrivateObjectSecurity, DestroyPrivateObjectSecurity, GENERIC_MAPPING, GetPrivateObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetFileSecurity, SetKernelObjectSecurity, SetUserObjectSecurity


SetProcessAffinityMask [New - Windows NT]
SetProcessAffinityMask

[New - Windows NT]

The SetProcessAffinityMask function sets a processor affinity mask for the threads of a specified process.

A process affinity mask is a bit vector in which each bit represents the processor on which the threads of the process are allowed to run.

The value of the process affinity mask must be a proper subset of the mask values obtained by the GetProcessAffinityMask function.

BOOL SetProcessAffinityMask(

HANDLE hProcess,	// handle to process
DWORD dwProcessAffinityMask	// process affinity mask
);
Parameters

hProcess

A handle to the process whose affinity mask the function sets. This handle must have the PROCESS_SET_INFORMATION access right. For more information, see Process Objects.

dwProcessAffinityMask

Specifies an affinity mask for the threads of the process.

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.

Remarks

Process affinity is inherited by any process that you start with the CreateProcess function.

See Also

CreateProcess, GetProcessAffinityMask


SetProcessPriorityBoost [New - Windows NT]
SetProcessPriorityBoost

[New - Windows NT]

The SetProcessPriorityBoost function disables the ability of Windows NT to temporarily boost the priority of the threads of the specified process.

BOOL SetProcessPriorityBoost(

HANDLE hProcess,	// handle to process
BOOL DisablePriorityBoost	// priority boost control state
);
Parameters

hProcess

Handle to the process. This handle must have the PROCESS_SET_INFORMATION access right. For more information, see Process Objects.

DisablePriorityBoost

A Boolean variable that is used to set the priority boost control state. A value of TRUE indicates that dynamic boosting is to be disabled. A value of FALSE restores normal behavior.

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.

Remarks

When a thread is running in one of the dynamic priority classes, Windows NT temporarily boosts the thread’s priority when it is taken out of a wait state. If SetProcessPriorityBoost is called with the DisablePriorityBoost parameter set to TRUE, its threads’ priorities are not boosted. This setting affects all existing threads and any threads subsequently created by the process. To restore normal behavior, call SetProcessPriorityBoost with DisablePriorityBoost set to FALSE.

See Also

GetProcessPriorityBoost


SetProcessShutdownParameters

The SetProcessShutdownParameters function sets shutdown parameters for the currently calling process. This function sets a shutdown order for a process relative to the other processes in the system.

BOOL SetProcessShutdownParameters(

DWORD dwLevel,	// shutdown priority
DWORD dwFlags	// shutdown flags
);
Parameters

dwLevel

Specifies the shutdown priority for a process relative to other processes in the system. The system shuts down processes from high dwLevel values to low. The highest and lowest shutdown priorities are reserved for system components. This parameter must be in the following range of values:

Value	Meaning
000−0FF	System reserved last shutdown range.
100−1FF	Application reserved last shutdown range.
200−2FF	Application reserved “in between” shutdown range.
300−3FF	Application reserved first shutdown range.
400−4FF	System reserved first shutdown range.
All processes start at shutdown level 0x280.

dwFlags

Specifies a flags parameter. It can be the following value:

Value	Meaning
SHUTDOWN_NORETRY	Specifies whether to retry the shutdown if the specified time-out period expires. If this flag is specified, the system terminates the process without displaying a retry dialog box for the user.
Return Values

If the function is succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Applications running in the system security context do not get shut down by the operating system. They get notified of shutdown or logoff through the callback function installable via SetConsoleCtrlHandler. They also get notified in the order specified by the dwLevel parameter.

See Also

GetProcessShutdownParameters, SetConsoleCtrlHandler


SetProcessWindowStation

The SetProcessWindowStation function assigns a window station to the calling process. This enables the process to access objects in the window station such as desktops, the clipboard, and global atoms. All subsequent operations on the window station use the access rights granted to hWinSta.

BOOL SetProcessWindowStation(

HWINSTA hWinSta	// handle of window station to assign to this process
);
Parameters

hWinSta

Identifies the window station to be assigned to the calling process. This handle is returned by the CreateWindowStation and OpenWindowStation functions.

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.

See Also

CreateWindowStation, GetProcessWindowStation, OpenWindowStation, SetThreadDesktop


SetProcessWorkingSetSize

The SetProcessWorkingSetSize function sets the minimum and maximum working set sizes for a specified process.

The working set of a process is the set of memory pages currently visible to the process in physical RAM memory. These pages are resident and available for an application to use without triggering a page fault. The size of the working set of a process is specified in bytes. The minimum and maximum working set sizes affect the virtual memory paging behavior of a process.

BOOL SetProcessWorkingSetSize(

HANDLE hProcess,	// open handle to the process of interest
DWORD dwMinimumWorkingSetSize,	// specifies minimum working set size
DWORD dwMaximumWorkingSetSize	// specifies maximum working set size
);
Parameters

hProcess

An open handle to the process whose working set sizes will be set.

Windows NT: The handle must have PROCESS_SET_QUOTA access rights. For more information, see Process Objects.

dwMinimumWorkingSetSize

Specifies a minimum working set size for the process. The virtual memory manager attempts to keep at least this much memory resident in the process whenever the process is active.

If both dwMinimumWorkingSetSize and dwMaximumWorkingSetSize have the value 0xffffffff, the function temporarily trims the working set of the specified process to zero. This essentially swaps the process out of physical RAM memory.

dwMaximumWorkingSetSize

Specifies a maximum working set size for the process. The virtual memory manager attempts to keep no more than this much memory resident in the process whenever the process is active and memory is in short supply.

If both dwMinimumWorkingSetSize and dwMaximumWorkingSetSize have the value 0xffffffff, the function temporarily trims the working set of the specified process to zero. This essentially swaps the process out of physical RAM memory.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. Call GetLastError to obtain extended error information.

Remarks

The working set of the specified process can be emptied by specifying the value 0xffffffff for both the minimum and maximum working set sizes.

If the values of either dwMinimumWorkingSetSize or dwMaximumWorkingSetSize are greater than the process’ current working set sizes, the specified process must have the SE_INC_BASE_PRIORITY_NAME privilege. Users in the Administrators and Power Users groups generally have this privilege. For more information about security privileges, see Privileges.

The operating system allocates working set sizes on a first-come, first-served basis. For example, if an application successfully sets 40 megabytes as its minimum working set size on a 64-megabyte system, and a second application requests a 40-megabyte working set size, the operating system denies the second application’s request.

Using the SetProcessWorkingSetSize function to set an application's minimum and maximum working set sizes does not guarantee that the requested memory will be reserved, or that it will remain resident at all times. When the application is idle, or a low-memory situation causes a demand for memory, the operating system can reduce the application's working set. An application can use the VirtualLock function to lock ranges of the application's virtual address space in memory; however, that can potentially degrade the performance of the system.

When you increase the working set size of an application, you are taking away physical memory from the rest of the system. This can degrade the performance of other applications and the system as a whole. It can also lead to failures of operations that require physical memory to be present; for example, creating processes, threads, and kernel pool. Thus, you must use the SetProcessWorkingSetSize function carefully. You must always consider the performance of the whole system when you are designing an application.

See Also

GetProcessWorkingSetSize, VirtualLock


SetProp

The SetProp function adds a new entry or changes an existing entry in the property list of the specified window. The function adds a new entry to the list if the specified character string does not exist already in the list. The new entry contains the string and the handle. Otherwise, the function replaces the string’s current handle with the specified handle.

BOOL SetProp(

HWND hWnd,	// handle of window
LPCTSTR lpString,	// atom or address of string
HANDLE hData	// handle of data
);
Parameters

hWnd

Identifies the window whose property list receives the new entry.

lpString

Points to a null-terminated string or contains an atom that identifies a string. If this parameter is an atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value, must be placed in the low-order word of lpString; the high-order word must be zero.

hData

Identifies data to be copied to the property list. The data handle can identify any value useful to the application.

Return Values

If the data handle and string are added to the property list, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Before destroying a window (that is, before processing the WM_DESTROY message), an application must remove all entries it has added to the property list. The application must use the RemoveProp function to remove the entries.

See Also

EnumProps, EnumPropsEx, GetProp, GlobalAddAtom, RemoveProp


SetRect

The SetRect function sets the coordinates of the specified rectangle. This is equivalent to assigning the left, top, right, and bottom arguments to the appropriate members of the RECT structure.

BOOL SetRect(

LPRECT lprc,	// address of structure with rectangle to set
int xLeft,	// left side
int yTop,	// top side
int xRight,	// right side
int yBottom	// bottom side
);
Parameters

lprc

Points to the RECT structure that contains the rectangle to be set.

xLeft

Specifies the x-coordinate of the rectangle’s upper-left corner.

yTop

Specifies the y-coordinate of the rectangle’s upper-left corner.

xRight

Specifies the x-coordinate of the rectangle’s lower-right corner.

yBottom

Specifies the y-coordinate of the rectangle’s lower-right corner.

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.

See Also

CopyRect, SetRectEmpty, RECT


SetRectEmpty

The SetRectEmpty function creates an empty rectangle in which all coordinates are set to zero.

BOOL SetRectEmpty(

LPRECT lprc	// address of structure with rectangle set to empty
);
Parameters

lprc

Points to the RECT structure that contains the coordinates of the rectangle.

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.

See Also

CopyRect, RECT, SetRect


SetRectRgn

The SetRectRgn function changes a region into a rectangular region with the specified coordinates.

BOOL SetRectRgn(

HRGN hrgn,	// handle of region
int nLeftRect,	// x-coordinate of upper-left corner of rectangle
int nTopRect,	// y-coordinate of upper-left corner of rectangle
int nRightRect,	// x-coordinate of lower-right corner of rectangle
int nBottomRect	// y-coordinate of lower-right corner of rectangle
);
Parameters

hrgn

Identifies the region.

nLeftRect

Specifies the x-coordinate of the upper-left corner of the rectangular region.

nTopRect

Specifies the y-coordinate of the upper-left corner of the rectangular region.

nRightRect

Specifies the x-coordinate of the lower-right corner of the rectangular region.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the rectangular region.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The region does not include the lower and right boundaries of the rectangle.

See Also

CreateRectRgn


SetROP2

The SetROP2 function sets the current foreground mix mode. GDI uses the foreground mix mode to combine pens and interiors of filled objects with the colors already on the screen. The foreground mix mode defines how colors from the brush or pen and the colors in the existing image are to be combined.

int SetROP2(

HDC hdc,	// handle of device context
int fnDrawMode	// drawing mode
);
Parameters

hdc

Identifies the device context.

fnDrawMode

Specifies the new mix mode. This parameter can be any one of the following values:

Mix mode	Description
R2_BLACK	Pixel is always 0.
R2_COPYPEN	Pixel is the pen color.
R2_MASKNOTPEN	Pixel is a combination of the colors common to both the screen and the inverse of the pen.
R2_MASKPEN	Pixel is a combination of the colors common to both the pen and the screen.
R2_MASKPENNOT	Pixel is a combination of the colors common to both the pen and the inverse of the screen.
R2_MERGENOTPEN	Pixel is a combination of the screen color and the inverse of the pen color.
R2_MERGEPEN	Pixel is a combination of the pen color and the screen color.
R2_MERGEPENNOT	Pixel is a combination of the pen color and the inverse of the screen color.
R2_NOP	Pixel remains unchanged.
R2_NOT	Pixel is the inverse of the screen color.
R2_NOTCOPYPEN	Pixel is the inverse of the pen color.
R2_NOTMASKPEN	Pixel is the inverse of the R2_MASKPEN color.
R2_NOTMERGEPEN	Pixel is the inverse of the R2_MERGEPEN color.
R2_NOTXORPEN	Pixel is the inverse of the R2_XORPEN color.
R2_WHITE	Pixel is always 1.
R2_XORPEN	Pixel is a combination of the colors in the pen and in the screen, but not in both.
Return Values

If the function succeeds, the return value specifies the previous mix mode.

If the function fails, the return value is zero.

Remarks

Mix modes define how GDI combines source and destination colors when drawing with the current pen. The mix modes are binary raster operation codes, representing all possible Boolean functions of two variables, using the binary operations AND, OR, and XOR (exclusive OR), and the unary operation NOT. The mix mode is for raster devices only; it is not available for vector devices.

See Also

GetROP2


SetScrollInfo

The SetScrollInfo function sets the parameters of a scroll bar, including the minimum and maximum scrolling positions, the page size, and the position of the scroll box (thumb). The function also redraws the scroll bar, if requested.

int SetScrollInfo(

HWND hwnd,	// handle of window with scroll bar
int fnBar,	// scroll bar flag
LPSCROLLINFO lpsi,	// pointer to structure with scroll parameters
BOOL fRedraw	// redraw flag
);
Parameters

hwnd

Identifies a scroll bar control or a window with a standard scroll bar, depending on the value of the fnBar parameter.

fnBar

Specifies the type of scroll bar for which to set parameters. This parameter can be one of the following values:

Value	Meaning
SB_CTL	Sets the parameters of a scroll bar control. The hwnd parameter must be the handle of the scroll bar control.
SB_HORZ	Sets the parameters of the given window's standard horizontal scroll bar.
SB_VERT	Sets the parameters of the given window's standard vertical scroll bar.
lpsi

Points to a SCROLLINFO structure whose fMask member, upon entry to the function, specifies the scroll bar parameters to set.

The fMask member can be a combination of the following values:

Value	Meaning
SIF_DISABLENOSCROLL	Disables the scroll bar instead of removing it, if the scroll bar’s new parameters make the scroll bar unnecessary.
SIF_PAGE	Sets the scroll page to the value specified in the nPage member of the SCROLLINFO structure pointed to by lpsi.
SIF_POS	Sets the scroll position to the value specified in the nPos member of the SCROLLINFO structure pointed to by lpsi.
SIF_RANGE	Sets the scroll range to the value specified in the nMin and nMax members of the SCROLLINFO structure pointed to by lpsi.
fRedraw

Specifies whether the scroll bar is redrawn to reflect the changes to the scroll bar. If this parameter is TRUE, the scroll bar is redrawn, otherwise, it is not redrawn.

Return Values

The return value is the current position of the scroll box.

Remarks

The SetScrollInfo function performs range checking on the values specified by the nPage and nPos members of the SCROLLINFO structure. The nPage member must specify a value from 0 to nMax - nMin +1. The nPos member must specify a value between nMin and nMax - max(nPage  − 1, 0). If either value is beyond its range, the function sets it to a value that is just within the range.

See Also

GetScrollInfo, SCROLLINFO


SetScrollPos

The SetScrollPos function sets the position of the scroll box (thumb) in the specified scroll bar and, if requested, redraws the scroll bar to reflect the new position of the scroll box. The SetScrollPos function is provided for compatibility with Windows 3.x. Win32-based applications should use the SetScrollInfo function.

int SetScrollPos(

HWND hWnd,	// handle of window with scroll bar
int nBar,	// scroll bar flag
int nPos,	// new position of scroll box
BOOL bRedraw	// redraw flag
);
Parameters

hWnd

Identifies a scroll bar control or a window with a standard scroll bar, depending on the value of the nBar parameter.

nBar

Specifies the scroll bar to be set. This parameter can be one of the following values:

Value	Meaning
SB_CTL	Sets the position of the scroll box in a scroll bar control. The hWnd parameter must be the handle of the scroll bar control.
SB_HORZ	Sets the position of the scroll box in a window’s standard horizontal scroll bar.
SB_VERT	Sets the position of the scroll box in a window’s standard vertical scroll bar.
nPos

Specifies the new position of the scroll box. The position must be within the scrolling range. For more information about the scrolling range, see the SetScrollRange function.

bRedraw

Specifies whether the scroll bar is redrawn to reflect the new scroll box position. If this parameter is TRUE, the scroll bar is redrawn. If it is FALSE, the scroll bar is not redrawn.

Return Values

If the function succeeds, the return value is the previous position of the scroll box.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If the scroll bar is redrawn by a subsequent call to another function, setting the bRedraw parameter to FALSE is useful.

Because the messages that indicate scroll bar position, WM_HSCROLL and WM_VSCROLL, are limited to 16 bits of position data, applications that rely solely on those messages for position data have a practical maximum value of 65,535 for the SetScrollPos function’s nPos parameter.

However, because the SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange functions support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier of the WM_HSCROLL and WM_VSCROLL messages. See GetScrollPos for a description of the technique and its limits.

See Also

GetScrollPos, GetScrollRange, ScrollDC, ScrollWindow, SetScrollRange


SetScrollRange

The SetScrollRange function sets the minimum and maximum position values for the specified scroll bar. It can also be used to hide or show a standard scroll bar.The SetScrollRange function is provided for compatibility with Windows 3.x. Win32-based applications should use the SetScrollInfo function.

BOOL SetScrollRange(

HWND hWnd,	// handle of window with scroll bar
int nBar,	// scroll bar flag
int nMinPos,	// minimum scrolling position
int nMaxPos,	// maximum scrolling position
BOOL bRedraw	// redraw flag
);
Parameters

hWnd

Identifies a scroll bar control or a window with a standard scroll bar, depending on the value of the nBar parameter.

nBar

Specifies the scroll bar to be set. This parameter can be one of the following values:

Value	Meaning
SB_CTL	Sets the range of a scroll bar control. The hWnd parameter must be the handle of the scroll bar control.
SB_HORZ	Sets the range of a window’s standard horizontal scroll bar.
SB_VERT	Sets the range of a window’s standard vertical scroll bar.
nMinPos

Specifies the minimum scrolling position.

nMaxPos

Specifies the maximum scrolling position.

bRedraw

Specifies whether the scroll bar should be redrawn to reflect the change. If this parameter is TRUE, the scroll bar is redrawn. If it is FALSE, the scroll bar is not redrawn.

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.

Remarks

An application should not call the SetScrollRange function to hide a scroll bar while processing a scroll bar message.

If the call to SetScrollRange immediately follows a call to the SetScrollPos function, the bRedraw parameter in SetScrollPos must be zero to prevent the scroll bar from being drawn twice.

The default range for a standard scroll bar is 0 through 100. The default range for a scroll bar control is empty (both the nMinPos and nMaxPos parameter values are zero). The difference between the values specified by the nMinPos and nMaxPos parameters must not be greater than the value of MAXLONG.

Because the messages that indicate scroll bar position, WM_HSCROLL and WM_VSCROLL, are limited to 16 bits of position data, applications that rely solely on those messages for position data have a practical maximum value of 65,535 for the SetScrollRange function’s nMaxPos parameter.

However, because the SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange functions support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier of the WM_HSCROLL and WM_VSCROLL messages. See GetScrollPos for a description of the technique and its limits.

See Also

GetScrollPos, GetScrollRange, SetScrollPos


SetSecurityDescriptorDacl

The SetSecurityDescriptorDacl function sets information in a discretionary access-control list (ACL). If a discretionary ACL is already present in the security descriptor, it is replaced.

BOOL SetSecurityDescriptorDacl(

PSECURITY_DESCRIPTOR pSecurityDescriptor,	// address of security descriptor
BOOL bDaclPresent,	// flag for presence of discretionary ACL
PACL pDacl,	// address of discretionary ACL
BOOL bDaclDefaulted	// flag for default discretionary ACL
);
Parameters

pSecurityDescriptor

Points to the SECURITY_DESCRIPTOR structure to which the function adds the discretionary ACL. This security descriptor must be in absolute format, meaning that its members must be pointers to other structures, rather than offsets to contiguous data.

bDaclPresent

Specifies a flag indicating the presence of a discretionary ACL in the security descriptor. If this parameter is TRUE, the function sets the SE_DACL_PRESENT flag in the SECURITY_DESCRIPTOR_CONTROL structure and uses the values in the pDacl and bDaclDefaulted parameters. If it is FALSE, the function clears the SE_DACL_PRESENT flag, and pDacl and bDaclDefaulted are ignored.

pDacl

Points to an ACL structure specifying the discretionary ACL for the security descriptor. If this parameter is NULL, a NULL discretionary ACL is assigned to the security descriptor, allowing all access to the object. The discretionary ACL is referenced by, not copied into, the security descriptor.

bDaclDefaulted

Specifies a flag indicating the source of the discretionary ACL. If this flag is TRUE, the discretionary ACL has been retrieved by some default mechanism. If FALSE, the discretionary ACL has been explicitly specified by a user. The function stores this value in the SE_DACL_DEFAULTED flag of the SECURITY_DESCRIPTOR_CONTROL structure. If this parameter is not specified, the SE_DACL_DEFAULTED flag is cleared.

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.

Remarks

There is an important difference between an empty and a nonexistent discretionary ACL. When a discretionary ACL is empty, it contains no access-control entries and no access rights have been explicitly granted. As a result, access to the object is implicitly denied. When an object has no DACL, on the other hand, no protection is assigned to the object, and any access request is granted.

There are three possible outcomes in different configurations of the bDaclPresent flag and the pDacl parameter:

•	When the pDacl parameter points to a discretionary ACL and the bDaclPresent flag is TRUE, a discretionary ACL is specified and it must contain access-allowed ACEs to allow access to the object.

•	When the pDacl parameter does not point to a discretionary ACL and the bDaclPresent flag is TRUE, a NULL discretionary ACL is specified. All access is allowed.

•	When the pDacl parameter does not point to a discretionary ACL and the bDaclPresent flag is FALSE, a discretionary ACL can be provided for the object through an inheritance or default mechanism.

See Also

ACL, GetSecurityDescriptorDacl, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorGroup, SetSecurityDescriptorOwner, SetSecurityDescriptorSacl


SetSecurityDescriptorGroup

The SetSecurityDescriptorGroup function sets the primary group information of an absolute-format security descriptor, replacing any primary group information already present in the security descriptor.

BOOL SetSecurityDescriptorGroup(

PSECURITY_DESCRIPTOR pSecurityDescriptor,	// address of security descriptor
PSID pGroup,	// address of SID for group
BOOL bGroupDefaulted	// flag for default
);
Parameters

pSecurityDescriptor

Points to the SECURITY_DESCRIPTOR structure whose primary group is set by this function. The function replaces any existing primary group with the new primary group.

pGroup

Points to a SID structure the function sets as the security descriptor’s new primary group. The SID structure is referenced by, not copied into, the security descriptor. If this parameter is NULL, the function clears the security descriptor’s primary group information. This marks the security descriptor as having no primary group.

bGroupDefaulted

Specifies a flag indicating whether the primary group information was derived from a default mechanism. If this flag is TRUE, it is default information, and the function stores this value as the SE_GROUP_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure. If this parameter is zero, the SE_GROUP_DEFAULTED flag is cleared.

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.

See Also

GetSecurityDescriptorGroup, InitializeSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorDacl, SetSecurityDescriptorOwner, SetSecurityDescriptorSacl, SID


SetSecurityDescriptorOwner

The SetSecurityDescriptorOwner function sets the owner information of an absolute-format security descriptor. It replaces any owner information already present in the security descriptor.

BOOL SetSecurityDescriptorOwner(

PSECURITY_DESCRIPTOR pSecurityDescriptor,	// address of security descriptor
PSID pOwner,	// address of SID for owner
BOOL bOwnerDefaulted	// flag for default
);
Parameters

pSecurityDescriptor

Points to the SECURITY_DESCRIPTOR structure whose owner is set by this function. The function replaces any existing owner with the new owner.

pOwner

Points to a SID structure the function sets as the security descriptor’s new primary owner. The SID structure is referenced by, not copied into, the security descriptor. If this parameter is NULL, the function clears the security descriptor’s owner information. This marks the security descriptor as having no owner.

bOwnerDefaulted

Specifies a flag indicating whether the owner information is derived from a default mechanism. If this flag is TRUE, it is default information. The function stores this value as the SE_OWNER_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure. If this parameter is zero, the SE_OWNER_DEFAULTED flag is cleared.

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.

See Also

GetSecurityDescriptorOwner, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorDacl, SetSecurityDescriptorGroup, SetSecurityDescriptorSacl, SID


SetSecurityDescriptorSacl

The SetSecurityDescriptorSacl function sets information in a system access-control list (ACL). If there is already a system ACL present in the security descriptor, it is replaced.

BOOL SetSecurityDescriptorSacl(

PSECURITY_DESCRIPTOR pSecurityDescriptor,	// address of security descriptor
BOOL bSaclPresent,	// flag for presence of system ACL
PACL pSacl,	// address of system ACL
BOOL bSaclDefaulted	// flag for default system ACL
);
Parameters

pSecurityDescriptor

Points to the SECURITY_DESCRIPTOR structure to which the function adds the system ACL. This security descriptor must be in absolute format, meaning that its members must be pointers to other structures, rather than offsets to contiguous data.

bSaclPresent

Specifies a flag indicating the presence of a system ACL in the security descriptor. If this parameter is TRUE, the function sets the SE_SACL_PRESENT flag in the SECURITY_DESCRIPTOR_CONTROL structure and uses the values in the pSacl and bSaclDefaulted parameters. If it is FALSE, the function does not set the SE_SACL_PRESENT flag, and pSacl and bSaclDefaulted are ignored.

pSacl

Points to an ACL structure that specifies the system ACL for the security descriptor. If this parameter is NULL, a NULL system ACL is assigned to the security descriptor. The system ACL is referenced by, not copied into, the security descriptor.

bSaclDefaulted

Specifies a flag indicating the source of the system ACL. If this flag is TRUE, the system ACL has been retrieved by some default mechanism. If it is FALSE, the system ACL has been explicitly specified by a user. The function stores this value in the SE_SACL_DEFAULTED flag of the SECURITY_DESCRIPTOR_CONTROL structure. If this parameter is not specified, the SE_SACL_DEFAULTED flag is cleared.

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.

See Also

ACL, GetSecurityDescriptorSacl, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorDacl, SetSecurityDescriptorGroup, SetSecurityDescriptorOwner


SetSecurityInfo [New - Windows NT]
SetSecurityInfo

[New - Windows NT]

The SetSecurityInfo function sets specified security information in the security descriptor of a specified object. The caller identifies the object by a handle.

DWORD SetSecurityInfo(

HANDLE handle,	// handle to the object
SE_OBJECT_TYPE ObjectType,	// type of object
SECURITY_INFORMATION SecurityInfo,	// type of security information to set
PSID psidOwner,	// pointer to the new owner SID
PSID psidGroup,	// pointer to the new primary group SID
PACL pDacl,	// pointer to the new DACL
PACL pSacl	// pointer to the new SACL
);
Parameters

handle

A handle to the object for which to set security information.

ObjectType

Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object identified by the handle parameter.

SecurityInfo

A set of SECURITY_INFORMATION bit flags that indicate the type of security information to set. This parameter can be a combination of the following values.

Value	Meaning
OWNER_SECURITY_INFORMATION	Set the owner security identifier (SID) in the object’s security descriptor. The psidOwner parameter points to the new SID.
GROUP_SECURITY_INFORMATION	Set the primary group SID in the object’s security descriptor. The psidGroup parameter points to the new SID.
DACL_SECURITY_INFORMATION	Set the discretionary access-control list (DACL) in the object’s security descriptor. The pDacl parameter points to the new DACL.
SACL_SECURITY_INFORMATION	Set the system access-control list (SACL) in the object’s security descriptor. The pSacl parameter points to the new SACL.
psidOwner

Pointer to a SID that identifies the object’s owner. The SID must be one that can be assigned as the owner SID of a security descriptor. The SecurityInfo parameter must include the OWNER_SECURITY_INFORMATION flag. The caller must have WRITE_OWNER access to the object or have the SE_TAKE_OWNERSHIP_NAME privilege enabled. This parameter can be NULL if you are not setting the owner SID.

psidGroup

Pointer to a SID that identifies the object’s primary group. The SecurityInfo parameter must include the GROUP_SECURITY_INFORMATION flag. This parameter can be NULL if you are not setting the primary group SID.

pDacl

Pointer to the new DACL for the object. The SecurityInfo parameter must include the DACL_SECURITY_INFORMATION flag. The caller must have WRITE_DAC access to the object or be the object’s owner. This parameter can be NULL if you are not setting the DACL.

pSacl

Pointer to the new SACL for the object. The SecurityInfo parameter must include the SACL_SECURITY_INFORMATION flag. The caller must have the SE_SECURITY_NAME privilege enabled. This parameter can be NULL if you are not setting the SACL.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H.

See Also

ACL, GetNamedSecurityInfo, GetSecurityInfo, SE_OBJECT_TYPE, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetNamedSecurityInfo, SID


SetServiceBits

The SetServiceBits function registers a service’s service type with the Service Control Manager and the Server service. The Server service can then announce the registered service type as one it currently supports. The LAN Manager functions NetServerGetInfo and NetServerEnum obtain a specified machine’s supported service types.

A service type is represented as a set of bit flags; the SetServiceBits function sets or clears combinations of those bit flags.

BOOL SetServiceBits(

SERVICE_STATUS_HANDLE hServiceStatus,	// service status handle
DWORD dwServiceBits,	// service type bits to set or clear
BOOL bSetBitsOn,	// flag to set or clear the service type bits
BOOL bUpdateImmediately	// flag to announce server type immediately
);
Parameters

hServiceStatus

A handle to the Service Control Manager’s status information structure for a service. A service obtains a SERVICE_STATUS_HANDLE value by calling the RegisterServiceCtrlHandler function. It is the service’s handle for making calls to the Service Control Manager.

dwServiceBits

A set of bit flags that specifies a service type.

Certain bit flags (0xC00F3F7B) are reserved for use by Microsoft. The SetServiceBits function fails with the error ERROR_INVALID_DATA if any of these bit flags are set in dwServiceBits. There are 18 of these bit flags:

Bit Flag Constant	Value
SV_TYPE_WORKSTATION	0x00000001
SV_TYPE_SERVER	0x00000002
SV_TYPE_DOMAIN_CTRL	0x00000008
SV_TYPE_DOMAIN_BAKCTRL	0x00000010
SV_TYPE_TIME_SOURCE	0x00000020
SV_TYPE_AFP	0x00000040
SV_TYPE_DOMAIN_MEMBER	0x00000100
SV_TYPE_PRINTQ_SERVER	0x00000200
SV_TYPE_DIALIN_SERVER	0x00000400
SV_TYPE_XENIX_SERVER	0x00000800
SV_TYPE_SERVER_UNIX	0x00000800
SV_TYPE_NT	0x00001000
SV_TYPE_WFW	0x00002000
SV_TYPE_POTENTIAL_BROWSER	0x00010000
SV_TYPE_BACKUP_BROWSER	0x00020000
SV_TYPE_MASTER_BROWSER	0x00040000
SV_TYPE_DOMAIN_MASTER	0x00080000
SV_TYPE_LOCAL_LIST_ONLY	0x40000000
SV_TYPE_DOMAIN_ENUM	0x80000000
Certain bit flags (0x00300084) are defined by Microsoft, but are not specifically reserved for systems software. There are four of these bit flags:

Bit Flag Constant	Value
SV_TYPE_SV_TYPE_SQLSERVER	0x00000004
SV_TYPE_NOVELL	0x00000080
SV_TYPE_DOMAIN_CTRL	0x00100000
SV_TYPE_DOMAIN_BAKCTRL	0x00200000
Certain bit flags (0x3FC0C000) are not defined by Microsoft, and their use is not coordinated by Microsoft. Developers of applications that use these bits should be aware that other applications may also use them, thus creating a conflict. There are 10 of these bit flags:

Value	Value
0x00004000	0x02000000
0x00008000	0x04000000
0x00400000	0x08000000
0x00800000	0x10000000
0x01000000	0x20000000
bSetBitsOn

A BOOLEAN that specifies whether the function is to set or clear the bit flags that are set in dwServiceBit. The value TRUE specifies that the bits are to be set; FALSE specifies clearing.

bUpdateImmediately

A BOOLEAN that specifies whether the Server service is to perform an immediate update, announcing the new service type. The value TRUE specifies an immediate update; FALSE specifies otherwise.

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.

See Also

NetServerGetInfo, NetServerEnum, RegisterServiceCtrlHandler, SetServiceStatus


SetServiceObjectSecurity

The SetServiceObjectSecurity function sets the security descriptor of a service object.

BOOL SetServiceObjectSecurity(

SC_HANDLE hService,	// handle of service
SECURITY_INFORMATION dwSecurityInformation,	// type of security information requested
PSECURITY_DESCRIPTOR lpSecurityDescriptor	// address of security descriptor
);
Parameters

hService

Identifies the service. This handle is returned by the OpenService or CreateService function. The access required for this handle depends on the security information specified in the dwSecurityInformation parameter.

dwSecurityInformation

Specifies the security information to be set. Any or all of the following flags can be specified:

Value	Meaning
OWNER_SECURITY_INFORMATION	Sets the object’s owner security identifier (SID). The hService handle must have WRITE_OWNER access, or the calling process must be the object’s owner.
GROUP_SECURITY_INFORMATION	Sets the object’s primary group SID. The hService handle must have WRITE_OWNER access, or the calling process must be the object’s owner.
DACL_SECURITY_INFORMATION	Sets the object’s discretionary access control list (ACL). The hService handle must have WRITE_DAC access, or the calling process must be the object’s owner.
SACL_SECURITY_INFORMATION	Sets the object’s system ACL. The calling process must have the SE_SECURITY_NAME privilege. For more information about security privileges, see Privileges.
lpSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure containing the new security information.

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.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED
	The specified handle was not opened with the required access, or the calling process is not the owner of the object.
ERROR_INVALID_HANDLE
	The specified handle is invalid.
ERROR_INVALID_PARAMETER
	The specified security information or security descriptor is invalid.
ERROR_SERVICE_MARKED_FOR_DELETE
	The specified service has been marked for deletion.
Remarks

The SetServiceObjectSecurity function sets the specified portions of the service object’s security descriptor, based on the information specified in the lpSecurityDescriptor buffer. This function replaces any or all of the security information associated with the service object, according to the flags set in the dwSecurityInformation parameter and subject to the calling process’s access rights.

The initial security descriptor of a service object is created by the service control manager, based on the security descriptor of the process that called the CreateService function to create the service. The security descriptor can be changed by calling the SetServiceObjectSecurity function.

See Also

CreateService, OpenService, QueryServiceObjectSecurity, SECURITY_DESCRIPTOR


SetServiceStatus

The SetServiceStatus function updates the service control manager’s status information for the calling service.

BOOL SetServiceStatus(

SERVICE_STATUS_HANDLE hServiceStatus~,	// service status handle
LPSERVICE_STATUS lpServiceStatus	// address of status structure
);
Parameters

hServiceStatus~

Specifies a handle to the service control manager’s status information structure for the current service. This handle is returned by the RegisterServiceCtrlHandler function.

lpServiceStatus

Points to the SERVICE_STATUS structure the contains the latest status information for the calling service.

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.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_INVALID_HANDLE	The specified handle is invalid.
ERROR_INVALID_DATA	The specified service status structure is invalid.
Remarks

A Win32 service’s ServiceMain function first calls the RegisterServiceCtrlHandler function to get the service’s SERVICE_STATUS_HANDLE. Then it immediately calls the SetServiceStatus function to notify the service control manager of its SERVICE_START_PENDING status.

When a Win32 service receives a control request, the service’s Handler function must call this function, even if the service’s status did not change. A service can also use this function at any time and by any thread of the service to notify the service control manager of status changes. Examples of such unsolicited status updates include:

•	Checkpoint updates that occur when the service is in transition from one state to another (that is, SERVICE_START_PENDING).

•	An update made necessary by the expected occurrence of a fatal error that causes the service to stop.

A service can call this function only after it has called RegisterServiceCtrlHandler to get a service status handle.

See Also

Handler, RegisterServiceCtrlHandler, SERVICE_STATUS, ServiceMain, SetServiceBits


SetStdHandle

The SetStdHandle function is used to set the handle for the standard input, standard output, or standard error device. The specified handle can be used by subsequent calls to the GetStdHandle function to refer to the input, output, or error device.

BOOL SetStdHandle(

DWORD nStdHandle,	// input, output, or error device
HANDLE hHandle	// handle to be a standard handle
);
Parameters

nStdHandle

Specifies the handle to be set. This parameter can have one of the following values:

Value	Meaning
STD_INPUT_HANDLE	Standard input handle
STD_OUTPUT_HANDLE	Standard output handle
STD_ERROR_HANDLE	Standard error handle
hHandle

Supplies the handle to store as standard input, standard output, or standard error.

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.

Remarks

The standard handles of a process may have been redirected by a call to SetStdHandle, in which case GetStdHandle will return the redirected handle. If the standard handles have been redirected, you can specify the CONIN$ value in a call to the CreateFile function to get a handle of a console’s input buffer. Similarly, you can specify the CONOUT$ value to get a handle of the console’s active screen buffer.

See Also

CreateFile, GetStdHandle


SetStretchBltMode

The SetStretchBltMode function sets the bitmap stretching mode in the specified device context.

int SetStretchBltMode(

HDC hdc,	// handle of device context
int iStretchMode	// bitmap stretching mode
);
Parameters

hdc

Identifies the device context.

iStretchMode

Specifies the stretching mode. It can be one of the following values:

Value	Description
BLACKONWHITE	Performs a Boolean AND operation using the color values for the eliminated and existing pixels. If the bitmap is a monochrome bitmap, this mode preserves black pixels at the expense of white pixels.
COLORONCOLOR	Deletes the pixels. This mode deletes all eliminated lines of pixels without trying to preserve their information.
HALFTONE	Maps pixels from the source rectangle into blocks of pixels in the destination rectangle. The average color over the destination block of pixels approximates the color of the source pixels.
	After setting the HALFTONE stretching mode, an application must call the SetBrushOrgEx function to set the brush origin. If it fails to do so, brush misalignment occurs.
STRETCH_ANDSCANS	Same as BLACKONWHITE.
STRETCH_DELETESCANS	Same as COLORONCOLOR.
STRETCH_HALFTONE	Same as HALFTONE.
STRETCH_ORSCANS	Same as WHITEONBLACK.
WHITEONBLACK	Performs a Boolean OR operation using the color values for the eliminated and existing pixels. If the bitmap is a monochrome bitmap, this mode preserves white pixels at the expense of black pixels.
Return Values

If the function succeeds, the return value is the previous stretching mode.

If the function fails, the return value is zero.

Remarks

The stretching mode defines how Windows combines rows or columns of a bitmap with existing pixels on a display device when an application calls the StretchBlt function.

The BLACKONWHITE (STRETCH_ANDSCANS) and WHITEONBLACK (STRETCH_ORSCANS) modes are typically used to preserve foreground pixels in monochrome bitmaps. The COLORONCOLOR (STRETCH_DELETESCANS) mode is typically used to preserve color in color bitmaps.

The HALFTONE mode requires more processing of the source image than the other three modes; it is slower than the others but produces higher quality images. Also note that SetBrushOrgEx must be called after setting the HALFTONE mode to avoid brush misalignment.

Additional stretching modes might also be available depending on the capabilities of the device driver.

See Also

GetStretchBltMode, SetBrushOrgEx, StretchBlt


SetSwapAreaSize

The SetSwapAreaSize function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. It has no meaning in the 32-bit environment.


SetSysColors

The SetSysColors function sets the colors for one or more display elements. Display elements are the various parts of a window and the Windows display that appear on the system display screen.

BOOL WINAPI SetSysColors(

int cElements,	// number of elements to change
CONST INT *lpaElements,	// address of array of elements
CONST COLORREF *lpaRgbValues	// address of array of RGB values
);
Parameters

cElements

Specifies the number of display elements in the array pointed to by the lpaElements parameter.

lpaElements

Points to an array of integers that specify the display elements to be changed. For a list of display elements, see the GetSysColor function.

lpaRgbValues

Points to an array of unsigned long integers that contains the new red, green, blue (RGB) color value for each display element in the array pointed to by the lpaElements parameter.

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.

Remarks

The SetSysColors function sends a WM_SYSCOLORCHANGE message to all windows to inform them of the change in color. It also directs Windows to repaint the affected portions of all currently visible windows.

The SetSysColors function changes the current Windows session only. The new colors are not saved when Windows terminates.

See Also

GetSysColor


SetSysModalWindow

The SetSysModalWindow function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. The new input model does not allow for System Modal windows.


SetSystemCursor

The SetSystemCursor function replaces the contents of the system cursor specified by id with the contents of the cursor specified by hcur, and then destroys hcur. This function lets an application customize the system cursors.

BOOL SetSystemCursor (

HCURSOR hcur,	// set specified system cursor to this cursor’s contents,  // then destroy this
DWORD id	// system cursor specified by its identifier
);
Parameters

hcur

Handle to a cursor. The function replaces the contents of the system cursor specified by id with the contents of the cursor handled by hcur. Then the function destroys hcur by calling DestroyCursor(hCursor).

id

A system cursor identifier. The function replaces the contents of this system cursor with the contents of the cursor handled by hcur.

Following is a list of system cursor identifiers:

Value	Description
OCR_NORMAL	normal arrow cursor
OCR_IBEAM	I-beam cursor
OCR_WAIT	larger hourglass cursor
OCR_CROSS	crosshair cursor
OCR_UP	up arrow cursor
OCR_SIZE	size cursor
OCR_ICON	icon cursor
OCR_SIZENWSE	NW to SE sizing cursor
OCR_SIZENESW	NE to SW sizing cursor
OCR_SIZEWE	horizontal sizing cursor
OCR_SIZENS	vertical sizing cursor
OCR_SIZEALL	horizontal and vertical sizing cursor
OCR_SIZENO	international no symbol cursor
OCR_APPSTARTING	smaller hourglass with arrow cursor
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.

See Also

DestroyCursor, LoadCursor, LoadCursorFromFile, SetCursor


SetSystemPaletteUse

The SetSystemPaletteUse function allows an application to specify whether the system palette contains 2 or 20 static colors. The default system palette contains 20 static colors. (Static colors cannot be changed when an application realizes a logical palette.)

UINT SetSystemPaletteUse(

HDC hdc,	// handle of device context
UINT uUsage	// palette-usage flag
);
Parameters

hdc

Identifies the device context. This device context must refer to a device that supports color palettes.

uUsage

Specifies the new use of the system palette. This parameter can be one of the following values:

Value	Meaning
SYSPAL_NOSTATIC	The system palette contains two static colors (black and white).
SYSPAL_STATIC	The system palette contains static colors that will not change when an application realizes its logical palette.
Return Values

If the function succeeds, the return value is the previous usage of the system palette (it can be either SYSPAL_NOSTATIC or SYSPAL_STATIC).

If the function fails, the return value is SYSPAL_ERROR. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

When an application window moves to the foreground and the SYSPAL_NOSTATIC value is set, the application must call the GetSysColor function to save the current system colors setting. It must also call SetSysColors to set reasonable values using only black and white. When the application returns to the background or terminates, the previous system colors must be restored.

If the function returns SYSPAL_ERROR, the specified device context is invalid or does not support color palettes.

An application must call this function only when its window is maximized and has the input focus.

If an application calls SetSystemPaletteUse with uUsage set to SYSPAL_NOSTATIC, Windows continues to set aside two entries in the system palette for pure white and pure black, respectively.

After calling this function with uUsage set to SYSPAL_NOSTATIC, an application must take the following steps:

1.	Realize the logical palette.

2.	Call the GetSysColor function to save the current system-color settings.

3.	Call the SetSysColors function to set the system colors to reasonable values using black and white. For example, adjacent or overlapping items (such as window frames and borders) should be set to black and white, respectively.

4.	Send the WM_SYSCOLORCHANGE message to other top-level windows to allow them to be redrawn with the new system colors.

When the application’s window loses focus or closes, the application must perform the following steps:

1.	Call SetSystemPaletteUse with the uUsage parameter set to SYSPAL_STATIC.

2.	Realize the logical palette.

3.	Restore the system colors to their previous values.

4.	Send the WM_SYSCOLORCHANGE message.

See Also

GetDeviceCaps, GetSysColor, SetSysColors, GetSystemPaletteUse


SetSystemPowerState

The SetSystemPowerState function suspends the system by shutting power down. Depending on the ForceFlag parameter, the function either suspends operation immediately or requests permission from all applications and device drivers before doing so.

BOOL SetSystemPowerState(

BOOL fSuspend,
BOOL fForce
);
Parameters

fSuspend

Suspension technique. If TRUE, the system suspends using RAM-alive technique. Otherwise, suspends using hibernate technique.

fForce

Forced suspension. If TRUE, the function sends a PBT_APMSUSPEND message to each application and driver, then immediately suspends operation. If FALSE, the function sends a PBT_APMQUERYSUSPEND message to each application to request permission to suspend operation.

Return Values

If power has been suspended and subsequently restored, the return value is nonzero.

If the system was not suspended, the return value is zero. To get extended error information, call GetLastError.

Remarks

If any application or driver denies permission to suspend operation, the function sends a PBT_APMQUERYSUSPENDFAILED message to each application and driver. If power is suspended, this function returns only after system operation is resumed and related WM_POWERBROADCAST messages have been sent to all applications and drivers.

See Also

PBT_APMQUERYSUSPEND, PBT_APMQUERYSUSPENDFAILED, PBT_APMSUSPEND, WM_POWERBROADCAST


SetSystemTime

The SetSystemTime function sets the current system time and date. The system time is expressed in Coordinated Universal Time (UTC).

BOOL SetSystemTime(

CONST SYSTEMTIME *lpSystemTime	// address of system time to set
);
Parameters

lpSystemTime

Points to a SYSTEMTIME structure that contains the current system date and time.

The wDayOfWeek member of the SYSTEMTIME structure is ignored.

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.

Remarks

Windows NT: The SetSystemTime function fails if the calling process does not have the SE_SYSTEMTIME_NAME privilege. This privilege is disabled by default. Use the AdjustTokenPrivileges function to enable this privilege and again to disable it after the time has been set. For more information about security privileges, see Privileges.

Windows 95: Security privileges are not supported or required.

See Also

AdjustTokenPrivileges, GetSystemTime, SetSystemTimeAdjustment, SYSTEMTIME, SystemTimeToTzSpecificLocalTime


SetSystemTimeAdjustment

The SetSystemTimeAdjustment function tells the system to enable or disable periodic time adjustments to its time of day clock. Such time adjustments are used to synchronize the time of day with some other source of time information. When periodic time adjustments are enabled, they are applied at each clock interrupt.

BOOL SetSystemTimeAdjustment(

DWORD dwTimeAdjustment,	// size, in 100-nanosecond units, of a periodic time adjustment
BOOL bTimeAdjustmentDisabled	// whether periodic time adjustment is to be disabled or enabled
);
Parameters

dwTimeAdjustment

Specifies the number of 100-nanosecond units added to the time-of-day clock at each clock interrupt if periodic time adjustment is enabled.

bTimeAdjustmentDisabled

Specifies the time adjustment mode that the system is to use. Periodic system time adjustments can be disabled or enabled.

A value of TRUE specifies that periodic time adjustment is to be disabled. The system is free to adjust time of day using its own internal mechanisms. The value of dwTimeAdjustment is ignored. The system’s internal adjustment mechanisms may cause the time-of-day clock to jump noticeably when adjustments are made.

A value of FALSE specifies that periodic time adjustment is to be enabled, and will be used to adjust the time-of-day clock. The system will not interfere with the time adjustment scheme, and will not attempt to synchronize time of day on its own. The system will add the value of dwTimeAdjustment to the time of day at each clock interrupt.

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. One way the function can fail is if the caller does not possess the SE_SYSTEMTIME_NAME privilege.

Remarks

The GetSystemTimeAdjustment and SetSystemTimeAdjustment functions support algorithms that synchronize the time-of-day clock, reported via GetSystemTime and GetLocalTime, with another time source using a periodic time adjustment.

The SetSystemTimeAdjustment function supports two modes of time synchronization: time-adjustment − disabled and time-adjustment − enabled.

In the first mode, bTimeAdjustmentDisabled is set to FALSE.  At each clock interrupt, the system adds the value of dwTimeAdjustment to the time of day. The clock interrupt rate may be determined by calling GetSystemTimeAdjustment, and looking at the returned value of the DWORD value pointed to by lpTimeIncrement.

In the second mode, bTimeAdjustmentDisabled is set to TRUE.  At each clock interrupt, the system adds the interval between clock interrupts to the time of day. No adjustment to that interval is made. The system is free to periodically refresh the time-of-day clock using other techniques. Such other techniques may cause the time-of-day clock to jump noticeably when adjustments are made.

An application must have system-time privilege (the SE_SYSTEMTIME_NAME privilege) for this function to succeed. The SE_SYSTEMTIME_NAME privilege is disabled by default. Use the AdjustTokenPrivileges function to enable the privilege before calling SetSystemTimeAdjustment, and then to disable the privilege after the SetSystemTimeAdjustment call.

See Also

AdjustTokenPrivileges, GetSystemTimeAdjustment, SetLocalTime, SetSystemTime, SystemTimeToTzSpecificLocalTime


SetTapeParameters

The SetTapeParameters function either specifies the block size of a tape or configures the tape device.

DWORD SetTapeParameters(

HANDLE hDevice,	// handle of open device
DWORD dwOperation,	// type of information to set
LPVOID lpTapeInformation	// address of buffer with information to set
);
Parameters

hDevice

Identifies the device for which to set configuration information. This handle is created by using the CreateFile function.

dwOperation

Specifies the type of information to set. This parameter must be one of the following values:

Value	Description
SET_TAPE_MEDIA_INFORMATION	Sets the tape-specific information specified by the lpTapeInformation parameter.
GET_TAPE_DRIVE_INFORMATION	Sets the device-specific information specified by lpTapeInformation.
lpTapeInformation

Points to a structure that contains the information to set. If the dwOperation parameter is SET_TAPE_MEDIA_INFORMATION, lpTapeInformation points to a TAPE_SET_MEDIA_PARAMETERS structure.

If dwOperation is SET_TAPE_DRIVE_INFORMATION, lpTapeInformation points to a TAPE_SET_DRIVE_PARAMETERS structure.

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:

Error	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
See Also

GetTapeParameters, TAPE_SET_DRIVE_PARAMETERS, TAPE_SET_MEDIA_PARAMETERS


SetTapePosition

The SetTapePosition sets the tape position on the specified device.

DWORD SetTapePosition(

HANDLE hDevice,	// handle of open device
DWORD dwPositionMethod,	// type of positioning to perform
DWORD dwPartition,	// new tape partition
DWORD dwOffsetLow,	// low-order 32 bits of tape position
DWORD dwOffsetHigh,	// high-order 32 bits of tape position
BOOL bImmediate	// return after operation begins
);
Parameters

hDevice

Identifies the device on which to set the tape position. This handle is created by using the CreateFile function.

dwPositionMethod

Specifies the type of positioning to perform. This parameter must be one of the following values:

Value	Meaning
TAPE_ABSOLUTE_BLOCK	Moves the tape to the device-specific block address specified by the dwOffsetLow and dwOffsetHigh parameters. The dwPartition parameter is ignored.
TAPE_LOGICAL_BLOCK	Moves the tape to the block address specified by dwOffsetLow and dwOffsetHigh in the partition specified by dwPartition.
TAPE_REWIND	Moves the tape to the beginning of the current partition. The dwPartition, dwOffsetLow, and dwOffsetHigh parameters are ignored.
TAPE_SPACE_END_OF_DATA	Moves the tape to the end of the data on the partition specified by dwPartition.
TAPE_SPACE_FILEMARKS	Moves the tape forward (or backward) the number of filemarks specified by dwOffsetLow and dwOffsetHigh in the current partition. The dwPartition parameter is ignored.
TAPE_SPACE_RELATIVE_BLOCKS	Moves the tape forward (or backward) the number of blocks specified by dwOffsetLow and dwOffsetHigh in the current partition. The dwPartition parameter is ignored.
TAPE_SPACE_SEQUENTIAL_FMKS	Moves the tape forward (or backward) to the first occurrence of n filemarks in the current partition, where n is the number specified by dwOffsetLow and dwOffsetHigh. The dwPartition parameter is ignored.
TAPE_SPACE_SEQUENTIAL_SMKS	Moves the tape forward (or backward) to the first occurrence of n setmarks in the current partition, where n is the number specified by dwOffsetLow and dwOffsetHigh. The dwPartition parameter is ignored.
TAPE_SPACE_SETMARKS	Moves the tape forward (or backward) the number of setmarks specified by dwOffsetLow and dwOffsetHigh in the current partition. The dwPartition parameter is ignored.
dwPartition

Specifies the partition to position within. If dwPartition is zero, the current partition is used. Partitions are numbered logically from 1 through n, where 1 is the first partition on the tape and n is the last.

dwOffsetLow

Specifies the low-order 32 bits of the block address or count for the position operation specified by the dwPositionMethod parameter.

dwOffsetHigh

Specifies the high-order 32 bits of the block address or count for the position operation specified by the dwPositionMethod parameter. If the high-order 32 bits are not required, this parameter should be zero.

bImmediate

Indicates whether to return as soon as the move operation begins. If this parameter is TRUE, the function returns immediately; if FALSE, the function does not return until the move operation has been completed.

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:

Error	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
Remarks

If the offset specified by dwOffsetLow and dwOffsetHigh specifies the number of blocks, filemarks, or setmarks to move, a positive offset moves the tape forward to the end of the last block, filemark, or setmark. A negative offset moves the tape backward to the beginning of the last block, filemark, or setmark. If the offset is zero, the tape does not move.

To obtain information about the status, capabilities, and capacities of tape drives and media, call the GetTapeParameters function.

See Also

CreateFile, GetTapeParameters, GetTapePosition


SetTextAlign

The SetTextAlign function sets the text-alignment flags for the specified device context.

UINT SetTextAlign(

HDC hdc,	// handle of device context
UINT fMode	// text-alignment flag
);
Parameters

hdc

Identifies the device context.

fMode

Specifies the text alignment by using a mask of the values in the following list. Only one flag can be chosen from those that affect horizontal and vertical alignment. In addition, only one of the two flags that alter the current position can be chosen.

Value	Meaning
TA_BASELINE	The reference point will be on the base line of the text.
TA_BOTTOM	The reference point will be on the bottom edge of the bounding rectangle.
TA_TOP	The reference point will be on the top edge of the bounding rectangle.
TA_CENTER	The reference point will be aligned horizontally with the center of the bounding rectangle.
TA_LEFT	The reference point will be on the left edge of the bounding rectangle.
TA_RIGHT	The reference point will be on the right edge of the bounding rectangle.
TA_NOUPDATECP	The current position is not updated after each text output call. The reference point is passed to the text output function.
TA_RTLREADING	Windows 95 only: The text is laid out in right to left reading order, as opposed to the default left to right order. This applies only when the font selected into the device context is either Hebrew or Arabic.
TA_UPDATECP	The current position is updated after each text output call. The current position is used as the reference point.
When the current font has a vertical default base line, as with Kanji, the following values must be used instead of TA_BASELINE and TA_CENTER:

Value	Meaning
VTA_BASELINE	The reference point will be on the base line of the text.
VTA_CENTER	The reference point will be aligned vertically with the center of the bounding rectangle.
The default values are TA_LEFT, TA_TOP, and TA_NOUPDATECP.

Return Values

If the function succeeds, the return value is the previous text-alignment setting.

If the function fails, the return value is GDI_ERROR. To get extended error information, call GetLastError.

Remarks

The TextOut and ExtTextOut functions use the text-alignment flags to position a string of text on a display or other device. The flags specify the relationship between a reference point and a rectangle that bounds the text. The reference point is either the current position or a point passed to a text output function.

The rectangle that bounds the text is formed by the character cells in the text string.

See Also

ExtTextOut, GetTextAlign, TextOut


SetTextCharacterExtra

The SetTextCharacterExtra function sets the intercharacter spacing. Intercharacter spacing is added to each character, including break characters, when Windows writes a line of text.

int SetTextCharacterExtra(

HDC hdc,	// handle of device context
int nCharExtra	// extra-space value
);
Parameters

hdc

Identifies the device context.

nCharExtra

Specifies the amount of extra space, in logical units, to be added to each character. If the current mapping mode is not MM_TEXT, the nCharExtra parameter is transformed and rounded to the nearest pixel.

Return Values

If the function succeeds, the return value is the previous intercharacter spacing.

If the function fails, the return value is 0x80000000.

See Also

DrawText, GetTextCharacterExtra, TextOut


SetTextColor

The SetTextColor function sets the text color for the specified device context to the specified color.

COLORREF SetTextColor(

HDC hdc,	// handle of device context
COLORREF crColor	// text color
);
Parameters

hdc

Identifies the device context.

crColor

Specifies the color of the text.

Return Values

If the function succeeds, the return value is a color reference for the previous text color.

If the function fails, the return value is CLR_INVALID. To get extended error information, call GetLastError.

Remarks

The text color is used to draw the face of each character written by the TextOut and ExtTextOut functions. The text color is also used in converting bitmaps from color to monochrome and vice versa.

See Also

BitBlt, ExtTextOut, GetTextColor, RGB, SetBkColor, StretchBlt, TextOut


SetTextJustification

The SetTextJustification function specifies the amount of space Windows should add to the break characters in a string of text. The space is added when an application calls the TextOut or ExtTextOut functions.

BOOL SetTextJustification(

HDC hdc,	// handle of device context
int nBreakExtra,	// length of extra space, in logical units
int nBreakCount	// count of space characters in line of text
);
Parameters

hdc

Identifies the device context.

nBreakExtra

Specifies the total extra space, in logical units, to be added to the line of text. If the current mapping mode is not MM_TEXT, the value identified by the nBreakExtra parameter is transformed and rounded to the nearest pixel.

nBreakCount

Specifies the number of break characters in the line.

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.

Remarks

The break character is usually the space character (ASCII 32), but it may be defined by a font as some other character. The GetTextMetrics function can be used to retrieve a font’s break character.

The TextOut function distributes the specified extra space evenly among the break characters in the line.

The GetTextExtentPoint32 function is always used with the SetTextJustification function. The GetTextExtentPoint32 function computes the width of a given line before justification. This width must be known before an appropriate nBreakExtra value can be computed.

SetTextJustification can be used to justify a line that contains multiple strings in different fonts. In this case, each string must be justified separately.

Because rounding errors can occur during justification, Windows keeps a running error term that defines the current error value. When justifying a line that contains multiple runs, GetTextExtentPoint automatically uses this error term when it computes the extent of the next run, allowing TextOut to blend the error into the new run. After each line has been justified, this error term must be cleared to prevent it from being incorporated into the next line. The term can be cleared by calling SetTextJustification with nBreakExtra set to zero.

See Also

ExtTextOut, GetTextExtentPoint32, GetTextMetrics, TextOut


SetThreadAffinityMask

The SetThreadAffinityMask function sets a processor affinity mask for a specified thread.

A thread affinity mask is a bit vector in which each bit represents the processors that a thread is allowed to run on.

A thread affinity mask must be a proper subset of the process affinity mask for the containing process of a thread. A thread is only allowed to run on the processors its process is allowed to run on.

DWORD SetThreadAffinityMask (

HANDLE hThread,	// handle to the thread of interest
DWORD dwThreadAffinityMask	// a thread affinity mask
);
Parameters

hThread

A handle to the thread whose affinity mask the function sets.

Windows NT: This handle must have the THREAD_SET_INFORMATION access right associated with it. For more information, see Thread Objects.

dwThreadAffinityMask

Windows 95: This value must be 1.

Windows NT: Specifies an affinity mask for the thread.

Return Values

If the function succeeds, the return value is nonzero.

Windows 95: The return value is 1. To succeed, hThread must be valid and dwThreadAffinityMask must be 1.

Windows NT: The return value is the thread’s previous affinity mask.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

GetProcessAffinityMask, SetThreadIdealProcessor


SetThreadContext

The SetThreadContext function sets the context in the specified thread.

BOOL SetThreadContext(

HANDLE hThread,	// handle of thread with context
CONST CONTEXT *lpContext	// address of context structure
);
Parameters

hThread

Identifies an open handle of a thread whose context is to be written to.

Windows NT: The handle must have the THREAD_SET_CONTEXT access right to the thread. For more information, see Thread Objects.

lpContext

Points to the address of a CONTEXT structure that contains the context to be set in the specified thread. The value of the ContextFlags member of this structure specifies which portions of a thread’s context to set. Some values in the CONTEXT structure that cannot be specified are silently set to the correct value. This includes bits in the CPU status register that specify the privileged processor mode, global enabling bits in the debugging register, and other states that must be controlled by the operating system.

Return Values

If the context was set, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The function allows the selective context to be set based on the value of the ContextFlags member of the context structure. The thread handle identified by the hThread parameter is typically being debugged, but the function can also operate even when it is not being debugged.

Do not try to set the context for a running thread; the results are unpredictable. Use the SuspendThread function to suspend the thread before calling SetThreadContext.

See Also

CONTEXT, GetThreadContext, SuspendThread


SetThreadDesktop

The SetThreadDesktop function assigns a desktop to the calling thread. All subsequent operations on the desktop use the access rights granted to hDesktop.

BOOL SetThreadDesktop(

HDESK hDesktop	// handle of the desktop to assign to this thread
);
Parameters

hDesktop

Identifies the desktop to be assigned to the calling thread. This handle is returned by the CreateDesktop, GetThreadDesktop, and OpenDesktop functions.

This function will fail if the calling thread has any windows or hooks on its current desktop (unless hDesktop is a handle to the current desktop).

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.

See Also

CreateDesktop, GetThreadDesktop, OpenDesktop, SetProcessWindowStation


SetThreadIdealProcessor [New - Windows NT]
SetThreadIdealProcessor

[New - Windows NT]

The SetThreadIdealProcessor function is used to specify a preferred processor for a thread. The system schedules threads on their preferred processors whenever possible.

DWORD SetThreadIdealProcessor(

HANDLE hThread,	// handle to the thread
DWORD dwIdealProcessor	// ideal processor number
);
Parameters

hThread

Handle to the thread whose preferred processor is to be set. The handle must have the THREAD_SET_INFORMATION access right associated with it. For more information, see Thread Objects.

dwIdealProcessor

Specifies the number of the preferred processor for the thread. A value of MAXIMUM_PROCESSORS tells the system that the thread has no preferred processor.

Return Values

If the function succeeds, the return value is the previous preferred processor or MAXIMUM_PROCESSORS if the thread does not have a preferred processor.

If the function fails, the return value is  − 1. To get extended error information, call GetLastError.

Remarks

You can use the GetSystemInfo function to determine the number of processors on the computer. You can also use the GetProcessAffinityMask function to check the processors on which the thread is allowed to run. Note that GetProcessAffinityMask returns a bit mask whereas SetThreadIdealProcessor uses an integer value to represent the processor.

See Also

GetProcessAffinityMask, GetSystemInfo, SetThreadAffinityMask


SetThreadLocale

The SetThreadLocale function sets the calling thread’s current locale.

BOOL SetThreadLocale (

LCID Locale	// locale identifier
);
Parameters

Locale

Specifies the new locale for the calling thread. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
For more information, see Locale Identifiers.

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.

Remarks

When a thread is created, it is given the system default thread locale. The system reads the system default thread locale from the registry when the system boots. This system default can be modified for future process and thread creation using Control Panel’s International application.

See Also

GetThreadLocale, GetSystemDefaultLCID, GetUserDefaultLCID


SetThreadPriority

The SetThreadPriority function sets the priority value for the specified thread. This value, together with the priority class of the thread’s process, determines the thread’s base priority level.

BOOL SetThreadPriority(

HANDLE hThread,	// handle to the thread
int nPriority	// thread priority level
);
Parameters

hThread

Identifies the thread whose priority value is to be set.

Windows NT: The handle must have the THREAD_SET_INFORMATION access right associated with it. For more information, see Thread Objects.

nPriority

Specifies the priority value for the thread. This parameter can be one of the following values:

Priority	Meaning
THREAD_PRIORITY_ABOVE_NORMAL	Indicates 1 point above normal priority for the priority class.
THREAD_PRIORITY_BELOW_NORMAL	Indicates 1 point below normal priority for the priority class.
THREAD_PRIORITY_HIGHEST	Indicates 2 points above normal priority for the priority class.
THREAD_PRIORITY_IDLE	Indicates a base priority level of 1 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 16 for REALTIME_PRIORITY_CLASS processes.
THREAD_PRIORITY_LOWEST	Indicates 2 points below normal priority for the priority class.
THREAD_PRIORITY_NORMAL	Indicates normal priority for the priority class.
THREAD_PRIORITY_TIME_CRITICAL	Indicates a base priority level of 15 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 31 for REALTIME_PRIORITY_CLASS processes.
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.

Remarks

Every thread has a base priority level determined by the thread’s priority value and the priority class of its process. The system uses the base priority level of all executable threads to determine which thread gets the next slice of CPU time. Threads are scheduled in a round-robin fashion at each priority level, and only when there are no executable threads at a higher level does scheduling of threads at a lower level take place.

The SetThreadPriority function enables setting the base priority level of a thread relative to the priority class of its process. For example, specifying THREAD_PRIORITY_HIGHEST in a call to SetThreadPriority for a thread of an IDLE_PRIORITY_CLASS process sets the thread’s base priority level to 6. For a table that shows the base priority levels for each combination of priority class and thread priority value, see the SetPriorityClass function.

For IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, and HIGH_PRIORITY_CLASS processes, the system dynamically boosts a thread’s base priority level when events occur that are important to the thread. REALTIME_PRIORITY_CLASS processes do not receive dynamic boosts.

All threads initially start at THREAD_PRIORITY_NORMAL. Use the GetPriorityClass and SetPriorityClass functions to get and set the priority class of a process. Use the GetThreadPriority function to get the priority value of a thread.

Use the priority class of a process to differentiate between applications that are time critical and those that have normal or below normal scheduling requirements. Use thread priority values to differentiate the relative priorities of the tasks of a process. For example, a thread that handles input for a window could have a higher priority level than a thread that performs intensive calculations for the CPU.

When manipulating priorities, be very careful  to ensure that a high-priority thread does not consume all of the available CPU time. A thread with a base priority level above 11 interferes with the normal operation of the operating system. Using REALTIME_PRIORITY_CLASS may cause disk caches to not flush, hang the mouse, and so on.

See Also

GetPriorityClass, GetThreadPriority, SetPriorityClass


SetThreadPriorityBoost [New - Windows NT]
SetThreadPriorityBoost

[New - Windows NT]

The SetThreadPriorityBoost function disables the ability of Windows NT to temporarily boost the priority of a thread.

BOOL SetThreadPriorityBoost(

HANDLE hThread,	// handle to thread
BOOL DisablePriorityBoost	// priority boost control state
);
Parameters

hThread

Handle to the thread whose priority is to be boosted. This thread must have the THREAD_SET_INFORMATION access right associated with it. For more information, see Thread Objects.

DisablePriorityBoost

A Boolean variable that is used to set the priority boost control state. A value of TRUE indicates that dynamic boosting is to be disabled. A value of FALSE restores normal behavior.

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.

Remarks

When a thread is running in one of the dynamic priority classes, Windows NT temporarily boosts the thread’s priority when it is taken out of a wait state. If SetThreadPriorityBoost is called with the DisablePriorityBoost parameter set to TRUE, the thread’s priority is not boosted. To restore normal behavior, call SetThreadPriorityBoost with DisablePriorityBoost set to FALSE.

See Also

GetThreadPriorityBoost


SetThreadToken

The SetThreadToken function assigns an impersonation token to a thread. The function can also cause a thread to stop using an impersonation token.

BOOL SetThreadToken(

PHANDLE Thread,	// points to a handle to the thread
HANDLE Token	// handle to the impersonation token
);
Parameters

Thread

Points to a handle to the thread to which the function assigns the impersonation token.

If Thread is NULL, the function assigns the impersonation token to the calling thread.

Token

An open handle to the impersonation token to assign to the thread. This handle must have been opened with TOKEN_IMPERSONATE access rights. For more information, see Access-Token Objects.

If Token is NULL, the function causes the thread to stop using an impersonation token.

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.

See Also

OpenThreadToken


SetTimer

The SetTimer function creates a timer with the specified time-out value.

UINT SetTimer(

HWND hWnd,	// handle of window for timer messages
UINT nIDEvent,	// timer identifier
UINT uElapse,	// time-out value
TIMERPROC lpTimerFunc	// address of timer procedure
);
Parameters

hWnd

Identifies the window to be associated with the timer. This window must be owned by the calling thread. If this parameter is NULL, no window is associated with the timer and the nIDEvent parameter is ignored.

nIDEvent

Specifies a nonzero timer identifier. If the hWnd parameter is NULL, this parameter is ignored.

uElapse

Specifies the time-out value, in milliseconds.

lpTimerFunc

Points to the function to be notified when the time-out value elapses. For more information about the function, see TimerProc.

If lpTimerFunc is NULL, the system posts a WM_TIMER message to the application queue. The hwnd member of the message’s MSG structure contains the value of the hWnd parameter.

Return Values

If the function succeeds, the return value is an integer identifying the new timer. An application can pass this value, or the string identifier, if it exists, to the KillTimer function to destroy the timer. If the function fails to create a timer, the return value is zero.

Remarks

An application can process WM_TIMER messages by including a WM_TIMER case statement in the window procedure or by specifying a TimerProc callback function when creating the timer. When you specify a TimerProc callback function, the DispatchMessage function simply calls the callback function instead of the window procedure. Therefore, you need to dispatch messages in the calling thread, even when you use TimerProc instead of processing WM_TIMER.

The wParam parameter of the WM_TIMER message contains the value of the nIDEvent parameter.

See Also

DispatchMessage, KillTimer, MSG, TimerProc, WM_TIMER


SetTimeZoneInformation

The SetTimeZoneInformation function sets the current time-zone parameters. These parameters control translations from Coordinated Universal Time (UTC) to local time.

BOOL SetTimeZoneInformation(

CONST TIME_ZONE_INFORMATION *lpTimeZoneInformation	// address of time-zone settings
);
Parameters

lpTimeZoneInformation

Points to a TIME_ZONE_INFORMATION structure that contains the time-zone parameters to set.

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.

Remarks

All translations between UTC and local time are based on the following formula:

UTC = local time + bias

The bias is the difference, in minutes, between UTC and local time.

See Also

GetTimeZoneInformation, TIME_ZONE_INFORMATION


SetTokenInformation

The SetTokenInformation function sets various types of information for a specified access token. The information it sets replaces existing information. The calling process must have appropriate access rights to set the information.

BOOL SetTokenInformation(

HANDLE TokenHandle,	// handle of access token
TOKEN_INFORMATION_CLASS TokenInformationClass,	// type of information to set
LPVOID TokenInformation,	// address of information to set
DWORD TokenInformationLength	// size of information buffer
);
Parameters

TokenHandle

Identifies the access token for which information is to be set.

TokenInformationClass

Specifies a variable of the TOKEN_INFORMATION_CLASS enumerated type identifying the type of information the function sets. The valid values from TOKEN_INFORMATION_CLASS are TokenOwner, TokenPrimaryGroup, and TokenDefaultDacl. For more information about these values, see the description of the TokenInformation parameter, following.

TokenInformation

Points to a buffer containing the information set in the access token. The structure of this buffer depends on the type of information specified by the TokenInformationClass parameter. The following three values are valid in calls to this function:

Token Information Class	Structure Provided
TokenOwner	TOKEN_OWNER structure. The TOKEN_ADJUST_DEFAULT access right is needed to set owner information. A valid owner value is a user or group identifier with an attribute allowing assignment as the owner of objects.
TokenPrimaryGroup	TOKEN_PRIMARY_GROUP structure. The TOKEN_ADJUST_DEFAULT access right is needed to set primary group information.
TokenDefaultDacl	TOKEN_DEFAULT_DACL structure. The TOKEN_ADJUST_DEFAULT access right is needed to set information in the default discretionary access-control list (ACL). The ACL structure provided as a new default discretionary ACL is not validated for correctness or consistency. If the TokenInformation parameter is NULL, the current default discretionary ACL is removed and no replacement is established.
The formats for the structures this function can set are listed in the following Remarks section.

TokenInformationLength

Specifies the length, in bytes, of the buffer pointed to by TokenInformation.

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.

Remarks

To set privilege information, an application can call the AdjustTokenPrivileges function. To set a token’s groups, an application can call the AdjustTokenGroups function.

Token-type information can be set only when an access token is created.

See Also

AdjustTokenGroups, AdjustTokenPrivileges, GetTokenInformation, OpenProcessToken, OpenThreadToken, TOKEN_DEFAULT_DACL, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP


SetUnhandledExceptionFilter

The SetUnhandledExceptionFilter function lets an application supersede the top-level exception handler that Win32 places at the top of each thread and process.

After calling this function, if an exception occurs in a process that is not being debugged, and the exception makes it to the Win32 unhandled exception filter, that filter will call the exception filter function specified by the lpTopLevelExceptionFilter parameter.

LPTOP_LEVEL_EXCEPTION_FILTER SetUnhandledExceptionFilter(

LPTOP_LEVEL_EXCEPTION_FILTER lpTopLevelExceptionFilter	// exception filter function
);
Parameters

lpTopLevelExceptionFilter

Supplies the address of a top-level exception filter function that will be called whenever the UnhandledExceptionFilter function gets control, and the process is not being debugged. A value of NULL for this parameter specifies default handling within UnhandledExceptionFilter.

The filter function has syntax congruent to that of UnhandledExceptionFilter: It takes a single parameter of type LPEXCEPTION_POINTERS, and returns a value of type LONG. The filter function should return one of the following values:

Value	Meaning
EXCEPTION_EXECUTE_HANDLER	Return from UnhandledExceptionFilter and execute the associated exception handler. This usually results in process termination.
EXCEPTION_CONTINUE_EXECUTION	Return from UnhandledExceptionFilter and continue execution from the point of the exception. Note that the filter function is free to modify the continuation state by modifying the exception information supplied through its LPEXCEPTION_POINTERS parameter.
EXCEPTION_CONTINUE_SEARCH	Proceed with normal execution of UnhandledExceptionFilter . That means obeying the SetErrorMod flags, or invoking the Application Error pop-up message box.
Return Values

The SetUnhandledExceptionFilter function returns the address of the previous exception filter established with the function. A NULL return value means that there is no current top-level exception handler.

Remarks

Issuing SetUnhandledExceptionFilter replaces the existing top-level exception filter for all existing and all future threads in the calling process.

The exception handler specified by lpTopLevelExceptionFilter is executed in the context of the thread that caused the fault. This can affect the exception handler’s ability to recover from certain exceptions, such as an invalid stack.

See Also

UnhandledExceptionFilter


SetupComm

The SetupComm function initializes the communications parameters for a specified communications device.

BOOL SetupComm(

HANDLE hFile,	// handle of communications device
DWORD dwInQueue,	// size of input buffer
DWORD dwOutQueue	// size of output buffer
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

dwInQueue

Specifies the recommended size, in bytes, of the device’s internal input buffer.

dwOutQueue

Specifies the recommended size, in bytes, of the device’s internal output buffer.

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.

Remarks

After a process uses the CreateFile function to open a handle to a communications device, it can call SetupComm to set the communications parameters for the device. If it does not set them, the device uses the default parameters when the first call to another communications function occurs.

The dwInQueue and dwOutQueue parameters specify the recommended sizes for the internal buffers used by the driver for the specified device. For example, YMODEM protocol packets are slightly larger than 1024 bytes. Therefore, a recommended buffer size might be 1200 bytes for YMODEM communications. For Ethernet-based communications, a recommended buffer size might be 1600 bytes, which is slightly larger than a single Ethernet frame.

The device driver receives the recommended buffer sizes, but is free to use any input and output (I/O) buffering scheme, as long as it provides reasonable performance and data is not lost due to overrun (except under extreme circumstances). For example, the function can succeed even though the driver does not allocate a buffer, as long as some other portion of the operating system provides equivalent functionality.

If the device driver determines that the recommended buffer sizes involve transfers beyond its ability to handle, the function can fail.

See Also

CreateFile, SetCommState


SetupHookProc

A SetupHookProc hook procedure is an application-defined or library-defined callback procedure that is used with the Print Setup common dialog box. The hook procedure receives messages or notifications intended for the default dialog box procedure.

UINT APIENTRY SetupHookProc(

HWND hdlg,	// handle to the dialog box window
UINT uiMsg,	// message identifier
WPARAM wParam,	// message parameter
LPARAM lParam	// message parameter
);
Parameters

hdlg

Handle to the Print Setup common dialog box window for which the message is intended.

uiMsg

Identifies the message being received.

wParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

lParam

Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

Return Values

If the hook procedure returns zero, the default dialog box procedure processes the message.

If the hook procedure returns a nonzero value, the default dialog box procedure ignores the message.

Remarks

The Print Setup dialog box has been superseded by the Page Setup dialog box, which should be used by new applications written for Windows NT or Windows 95. However, for compatibility with earlier versions of Windows, the PrintDlg function continues to support display of the Print Setup dialog box. You can provide a SetupHookProc hook procedure for the Print Setup dialog box to process messages or notifications intended for the dialog box procedure.

To enable the hook procedure, use the PRINTDLG structure that you passed to the dialog creation function. Specify the address of the hook procedure in the lpfnSetupHook member and specify the PD_ENABLESETUPHOOK flag in the Flags member.

The default dialog box procedure processes the WM_INITDIALOG message before passing it to the hook procedure. For all other messages, the hook procedure receives the message first. Then, the return value of the hook procedure determines whether the default dialog procedure processes the message or ignores it.

If the hook procedure processes the WM_CTLCOLORDLG message, it must return a valid brush handle for painting the background of the dialog box. In general, if the hook procedure processes any WM_CTLCOLOR* message, it must return a valid brush handle for painting the background of the specified control.

Do not call the EndDialog function from the hook procedure. Instead, the hook procedure can call the PostMessage function to post a WM_COMMAND message with the IDABORT value to the dialog box procedure. Posting IDABORT closes the dialog box and causes the dialog box function to return FALSE. If you need to know why the hook procedure closed the dialog box, you must provide your own communication mechanism between the hook procedure and your application.

You can subclass the standard controls of the common dialog box. However, the common dialog box procedure may also subclass the controls. Because of this, you should subclass controls when your hook procedure processes the WM_INITDIALOG message. This ensures that your subclass procedure receives the control-specific messages before the subclass procedure set by the dialog box procedure.

SetupHookProc is a placeholder for the application-defined or library-defined function name. The LPSETUPHOOKPROC type is a pointer to a SetupHookProc hook procedure.

See Also

EndDialog, PrintDlg, PRINTDLG, PostMessage, WM_INITDIALOG, WM_CTLCOLORDLG


SetUserObjectInformation

The SetUserObjectInformation function sets information about a window station or desktop object.

BOOL SetUserObjectInformation(

HANDLE hObj,	// handle of the object for which to set information
int nIndex,	// type of information to set
PVOID pvInfo,	// points to a buffer that contains the information
DWORD nLength	// size, in bytes, of pvInfo buffer
);
Parameters

hObj

Identifies the window station or desktop object for which to set object information. This value can be an HDESK or HWINSTA handle (for example, a handle returned by CreateWindowStation, OpenWindowStation, CreateDesktop, or OpenDesktop).

nIndex

Specifies the object information to be set. This parameter must specify the following value:

Value	Description
UOI_FLAGS	Sets the object’s handle flags. The pvInfo parameter must point to a USEROBJECTFLAGS structure.
pvInfo

Points to a buffer containing the object information.

nLength

Specifies the size, in bytes, of the information contained in the buffer pointed to by pvInfo.

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.

See Also

CreateDesktop, CreateWindowStation, GetUserObjectInformation, OpenDesktop,.OpenWindowStation, USEROBJECTFLAGS


SetUserObjectSecurity

The SetUserObjectSecurity function sets the security of a user object. This can be, for example, a window or a DDE conversation.

BOOL SetUserObjectSecurity(

HANDLE hObj,	// handle of user object
PSECURITY_INFORMATION pSIRequested,	// address of security information
PSECURITY_DESCRIPTOR pSID	// address of security descriptor
);
Parameters

hObj

Identifies a user object for which security information is set.

pSIRequested

Points to a SECURITY_INFORMATION structure describing the security information being set.

pSID

Points to a SECURITY_DESCRIPTOR structure containing the new security information.

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.

Remarks

The SetUserObjectSecurity function applies changes specified in a security descriptor to the security descriptor assigned to a user object. The object’s security descriptor must be in self-relative form. If necessary, this function allocates additional memory to increase the size of the security descriptor.

The SetUserObjectSecurity function is successful only if the following conditions are met:

•	If the object’s owner is being set, the calling process must either have WRITE_OWNER permission or be the object’s owner.

•	If the object’s discretionary access-control list (ACL) is being set, the calling process must either have WRITE_DAC permission or be the object’s owner.

•	If the object’s system ACL is being set, the SE_SECURITY_NAME privilege must be enabled for the calling process.

See Also

GetUserObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetFileSecurity, SetKernelObjectSecurity, SetPrivateObjectSecurity


SetViewportExtEx

The SetViewportExtEx function sets the horizontal and vertical extents of the viewport for a device context by using the specified values.

BOOL SetViewportExtEx(

HDC hdc,	// handle of device context
int nXExtent,	// new horizontal viewport extent
int nYExtent,	// new vertical viewport extent
LPSIZE lpSize	// original viewport extent
);
Parameters

hdc

Identifies the device context.

nXExtent

Specifies the horizontal extent, in device units, of the viewport.

nYExtent

Specifies the vertical extent, in device units, of the viewport.

lpSize

Points to a SIZE structure. The previous viewport extents (in device units) are placed in this structure. If lpSize is NULL, nothing is returned.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

When the following mapping modes are set, calls to the SetWindowExtEx and SetViewportExtEx functions are ignored.

•	MM_HIENGLISH

•	MM_HIMETRIC

•	MM_LOENGLISH

•	MM_LOMETRIC

•	MM_TEXT

•	MM_TWIPS

When MM_ISOTROPIC mode is set, an application must call the SetWindowExtEx function before it calls SetViewportExtEx.

See Also

GetViewportExtEx, SetWindowExtEx, SIZE


SetViewportOrgEx

The SetViewportOrgEx function sets the viewport origin of a device context by using the specified coordinates.

BOOL SetViewportOrgEx(

HDC hdc,	// handle of device context
int X,	// new x-coordinate of viewport origin
int Y,	// new y-coordinate of viewport origin
LPPOINT lpPoint	// address of structure receiving original origin
);
Parameters

hdc

Identifies the device context.

X

Specifies the x-coordinate, in device units, of the new viewport origin.

Y

Specifies the y-coordinate, in device units, of the new viewport origin.

lpPoint

Points to a POINT structure. The previous viewport origin (in device coordinates) is placed in this structure. If lpPoint is NULL, nothing is returned.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

GetViewportOrgEx, POINT, SetWindowOrgEx


SetVolumeLabel

The SetVolumeLabel function sets the label of a file system volume.

BOOL SetVolumeLabel(

LPCTSTR lpRootPathName,	// address of name of root directory for volume
LPCTSTR lpVolumeName	// name for the volume
);
Parameters

lpRootPathName

Points to a null-terminated string specifying the root directory of a file system volume. This is the volume the function will label. If this parameter is NULL, the root of the current directory is used.

lpVolumeName

Points to a string specifying a name for the volume. If this parameter is NULL, the function deletes the name of the specified volume.

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.

See Also

GetVolumeInformation


SetWaitableTimer [New - Windows NT]
SetWaitableTimer

[New - Windows NT]

The SetWaitableTimer function activates the specified “waitable” timer. When the due time arrives, the timer is signaled and the thread that set the timer calls the optional completion routine.

BOOL SetWaitableTimer(

HANDLE hTimer,	// handle to a timer object
const LARGE_INTEGER *pDueTime,	// when timer will become signaled
LONG lPeriod,	// periodic timer interval
PTIMERAPCROUTINE pfnCompletionRoutine,	// pointer to the completion routine
LPVOID lpArgToCompletionRoutine,	// data passed to the completion routine
BOOL fResume	// flag for resume state
);
Parameters

hTimer

Identifies the timer object. The CreateWaitableTimer or OpenWaitableTimer function returns this handle.

pDueTime

Specifies when the state of the timer is to be set to signaled, in 100 nanosecond intervals. Use the format described by the FILETIME structure. Positive values indicate absolute time. Negative values indicate relative time. The actual timer accuracy depends on the capability of your hardware.

lPeriod

Specifies the period of the timer, in milliseconds. If lPeriod is zero, the timer is signaled once. If lPeriod is greater than zero, the timer is periodic. A periodic timer automatically reactivates each time the period elapses, until the timer is canceled using the CancelWaitableTimer function or reset using SetWaitableTimer. If lPeriod is less than zero, the function fails.

pfnCompletionRoutine

Specifies an optional completion routine. The completion routine has the following prototype:

VOID

(APIENTRY *PTIMERAPCROUTINE)(

   LPVOID lpArgToCompletionRoutine,

   DWORD dwTimerLowValue,

   DWORD dwTimerHighValue

);

The argument for the completion routine is specified when the timer is made active, in the lpArgToCompletionRoutine parameter. The completion routine also takes two DWORD values that specify the high and low time values of the time at which the timer was signaled. These values are passed to the routine by the system using the FILETIME format..

lpArgToCompletionRoutine

Pointer to the structure that is passed to the function specified by the pointer pfnCompletionRoutine.

fResume

Specifies whether to restore a system in suspended power conservation mode when the timer state is set to signaled. If fResume is TRUE on a platform that does not support a restore, the call will succeed, but GetLastError returns ERROR_NOT_SUPPORTED.

Return Value

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.

Remarks

Timer are initially inactive. Timers are activated by calling SetWaitableTimer. If the timer is already active when you call SetWaitableTimer, the timer is stopped, then it is reactivated. Stopping the timer in this manner does not set the timer state to signaled, so threads blocked in a wait operation on the timer remain blocked.

When the specified due time arrives, the timer becomes inactive. The state of the timer is set to signaled, the timer is reactivated using the specified period, and the thread calls the completion routine. If you call SetWaitableTimer and the thread is not in an alertable state, the completion routine is canceled.

When a manual-reset timer is set to the signaled state, it remains in this state until SetWaitableTimer is called to reset the timer. As a result, a periodic manual-reset timer is set to the signaled state when the initial due time arrives and remains signaled until it is canceled or reset. When a synchronization timer is set to the signaled state, it remains in this state until a thread completes a wait operation on the timer object.

See Also

CancelWaitableTimer, CreateWaitableTimer, FILETIME, OpenWaitableTimer


SetWindowContextHelpId

The SetWindowContextHelpId function associates a help context identifier with the specified window.

BOOL SetWindowContextHelpId(

HWND hwnd,
DWORD dwContextHelpId
);
Parameters

hwnd

Handle to the window with which to associate the help context identifier.

dwContextHelpId

Help context identifier.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

If a child window does not have a help context identifier, it inherits the identifier of its parent window. Likewise, if an owned window does not have a help context identifier, it inherits the identifier of its owner window. This inheritance of help context identifiers allows an application to set just one identifier for a dialog box and all of its controls.

See Also

GetWindowContextHelpId


SetWindowExtEx

The SetWindowExtEx function sets the horizontal and vertical extents of the window for a device context by using the specified values.

BOOL SetWindowExtEx(

HDC hdc,	// handle of device context
int nXExtent,	// new horizontal window extent
int nYExtent,	// new vertical window extent
LPSIZE lpSize	// original window extent
);
Parameters

hdc

Identifies the device context.

nXExtent

Specifies the window’s horizontal extent in logical units.

nYExtent

Specifies the window’s vertical extent in logical units.

lpSize

Points to a SIZE structure. The previous window extents (in logical units) are placed in this structure. If lpSize is NULL, nothing is returned.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

When the following mapping modes are set, calls to the SetWindowExtEx and SetViewportExtEx functions are ignored:

•	MM_HIENGLISH

•	MM_HIMETRIC

•	MM_LOENGLISH

•	MM_LOMETRIC

•	MM_TEXT

•	MM_TWIPS

When MM_ISOTROPIC mode is set, an application must call the SetWindowExtEx function before calling SetViewportExtEx.

See Also

GetWindowExtEx, SetViewportExtEx, SIZE


SetWindowLong

The SetWindowLong function changes an attribute of the specified window. The function also sets a 32-bit (long) value at the specified offset into the extra window memory of a window.

LONG SetWindowLong(

HWND hWnd,	// handle of window
int nIndex,	// offset of value to set
LONG dwNewLong	// new value
);
Parameters

hWnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the zero-based offset to the value to be set. Valid values are in the range zero through the number of bytes of extra window memory, minus 4; for example, if you specified 12 or more bytes of extra memory, a value of 8 would be an index to the third 32-bit integer. To set any other value, specify one of the following values:

Value	Action
GWL_EXSTYLE	Sets a new extended window style.
GWL_STYLE	Sets a new window style.
GWL_WNDPROC	Sets a new address for the window procedure.
GWL_HINSTANCE	Sets a new application instance handle.
GWL_ID	Sets a new identifier of the window.
GWL_USERDATA	Sets the 32-bit value associated with the window. Each window has a corresponding 32-bit value intended for use by the application that created the window.
The following values are also available when the hWnd parameter identifies a dialog box:

Value	Action
DWL_DLGPROC	Sets the new address of the dialog box procedure.
DWL_MSGRESULT	Sets the return value of a message processed in the dialog box procedure.
DWL_USER	Sets new extra information that is private to the application, such as handles or pointers.
dwNewLong

Specifies the replacement value.

Return Values

If the function succeeds, the return value is the previous value of the specified 32-bit integer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

If the previous value of the specified 32-bit integer is zero, and the function succeeds, the return value is zero, but the function does not clear the last error information. This makes it difficult to determine success or failure. To deal with this, you should clear the last error information by calling SetLastError(0) before calling SetWindowLong. Then, function failure will be indicated by a return value of zero and a GetLastError result that is nonzero.

Remarks

The SetWindowLong function fails if the window specified by the hWnd parameter does not belong to the same process as the calling thread.

If you use the SetWindowLong function and the GWL_WNDPROC index to replace the window procedure, the window procedure must conform to the guidelines specified in the description of the WindowProc callback function.

Calling SetWindowLong with the GWL_WNDPROC index creates a subclass of the window class used to create the window. An application should not subclass a window created by another process. The SetWindowLong function creates the window subclass by changing the window procedure associated with a particular window, causing Windows to call the new window procedure instead of the previous one. An application must pass any messages not processed by the new window procedure to the previous window procedure by calling CallWindowProc. This allows the application to create a chain of window procedures.

Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the WNDCLASS structure used with the RegisterClass function.

You must not call SetWindowLong with the GWL_HWNDPARENT index to change the parent of a child window. Instead, use the SetParent function.

See Also

CallWindowProc, GetWindowLong, GetWindowWord, RegisterClass, SetParent, SetWindowWord, WindowProc, WNDCLASS


SetWindowOrgEx

The SetWindowOrgEx function sets the window origin of the device context by using the specified coordinates.

BOOL SetWindowOrgEx(

HDC hdc,	// handle of device context
int X,	// new x-coordinate of window origin
int Y,	// new y-coordinate of window origin
LPPOINT lpPoint	// address of structure receiving original origin
);
Parameters

hdc

Identifies the device context.

X

Specifies the logical x-coordinate of the new window origin.

Y

Specifies the logical y-coordinate of the new window origin.

lpPoint

Points to a POINT structure. The previous origin of the window is placed in this structure. If lpPoint is NULL, nothing is returned.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

GetViewportOrgEx, GetWindowOrgEx, POINT, SetViewportOrgEx


SetWindowPlacement

The SetWindowPlacement function sets the show state and the restored, minimized, and maximized positions of the specified window.

BOOL SetWindowPlacement(

HWND hWnd,	// handle of window
CONST WINDOWPLACEMENT *lpwndpl	// address of structure with position data
);
Parameters

hWnd

Identifies the window.

lpwndpl

Points to a WINDOWPLACEMENT structure that specifies the new show state and window positions.

Before calling SetWindowPlacement, set the length member of the WINDOWPLACEMENT structure to sizeof(WINDOWPLACEMENT).

SetWindowPlacement fails if lpwndpl->length is not set correctly.

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.

Remarks

The length member of WINDOWPLACEMENT must be set to sizeof(WINDOWPLACEMENT). If this member is not set correctly, the function returns FALSE.

See Also

GetWindowPlacement, WINDOWPLACEMENT


SetWindowPos

The SetWindowPos function changes the size, position, and Z order of a child, pop-up, or top-level window. Child, pop-up, and top-level windows are ordered according to their appearance on the screen. The topmost window receives the highest rank and is the first window in the Z order.

BOOL SetWindowPos(

HWND hWnd,	// handle of window
HWND hWndInsertAfter,	// placement-order handle
int X,	// horizontal position
int Y,	// vertical position
int cx,	// width
int cy,	// height
UINT uFlags	// window-positioning flags
);
Parameters

hWnd

Identifies the window.

hWndInsertAfter

Identifies the window to precede the positioned window in the Z order. This parameter must be a window handle or one of the following values:

Value	Meaning
HWND_BOTTOM	Places the window at the bottom of the Z order. If the hWnd parameter identifies a topmost window, the window loses its topmost status and is placed at the bottom of all other windows.
HWND_NOTOPMOST	Places the window above all non-topmost windows (that is, behind all topmost windows). This flag has no effect if the window is already a non-topmost window.
HWND_TOP	Places the window at the top of the Z order.
HWND_TOPMOST	Places the window above all non-topmost windows. The window maintains its topmost position even when it is deactivated.
For more information about how this parameter is used, see the following Remarks section.

X

Specifies the new position of the left side of the window.

Y

Specifies the new position of the top of the window.

cx

Specifies the new width of the window, in pixels.

cy

Specifies the new height of the window, in pixels.

uFlags

Specifies the window sizing and positioning flags. This parameter can be a combination of the following values:

Value	Meaning
SWP_DRAWFRAME	Draws a frame (defined in the window’s class description) around the window.
SWP_FRAMECHANGED	Sends a WM_NCCALCSIZE message to the window, even if the window’s size is not being changed. If this flag is not specified, WM_NCCALCSIZE is sent only when the window’s size is being changed.
SWP_HIDEWINDOW	Hides the window.
SWP_NOACTIVATE	Does not activate the window. If this flag is not set, the window is activated and moved to the top of either the topmost or non-topmost group (depending on the setting of the hWndInsertAfter parameter).
SWP_NOCOPYBITS	Discards the entire contents of the client area. If this flag is not specified, the valid contents of the client area are saved and copied back into the client area after the window is sized or repositioned.
SWP_NOMOVE	Retains the current position (ignores the X and Y parameters).
SWP_NOOWNERZORDER	Does not change the owner window’s position in the Z order.
SWP_NOREDRAW	Does not redraw changes. If this flag is set, no repainting of any kind occurs. This applies to the client area, the nonclient area (including the title bar and scroll bars), and any part of the parent window uncovered as a result of the window being moved. When this flag is set, the application must explicitly invalidate or redraw any parts of the window and parent window that need redrawing.
SWP_NOREPOSITION	Same as the SWP_NOOWNERZORDER flag.
SWP_NOSENDCHANGING	Prevents the window from receiving the WM_WINDOWPOSCHANGING message.
SWP_NOSIZE	Retains the current size (ignores the cx and cy parameters).
SWP_NOZORDER	Retains the current Z order (ignores the hWndInsertAfter parameter).
SWP_SHOWWINDOW	Displays the window.
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.

Remarks

If the SWP_SHOWWINDOW or SWP_HIDEWINDOW flag is set, the window cannot be moved or sized.

All coordinates for child windows are client coordinates (relative to the upper-left corner of the parent window’s client area).

A window can be made a topmost window either by setting the hWndInsertAfter parameter to HWND_TOPMOST and ensuring that the SWP_NOZORDER flag is not set, or by setting a window’s position in the Z order so that it is above any existing topmost windows. When a non-topmost window is made topmost, its owned windows are also made topmost. Its owners, however, are not changed.

If neither the SWP_NOACTIVATE nor SWP_NOZORDER flag is specified (that is, when the application requests that a window be simultaneously activated and its position in the Z order changed), the value specified in hWndInsertAfter is used only in the following circumstances:

•	Neither the HWND_TOPMOST nor HWND_NOTOPMOST flag is specified in hWndInsertAfter.

•	The window identified by hWnd is not the active window.

An application cannot activate an inactive window without also bringing it to the top of the Z order. Applications can change an activated window’s position in the Z order without restrictions, or it can activate a window and then move it to the top of the topmost or non-topmost windows.

If a topmost window is repositioned to the bottom (HWND_BOTTOM) of the Z order or after any non-topmost window, it is no longer topmost. When a topmost window is made non-topmost, its owners and its owned windows are also made non-topmost windows.

A non-topmost window can own a topmost window, but the reverse cannot occur. Any window (for example, a dialog box) owned by a topmost window is itself made a topmost window, to ensure that all owned windows stay above their owner.

If an application is not in the foreground, and should be in the foreground, it must call the SetForegroundWindow function.

See Also

MoveWindow, SetActiveWindow, SetForegroundWindow


SetWindowRgn

The SetWindowRgn function sets the window region of a window. The window region determines the area within the window where the operating system permits drawing. The operating system does not display any portion of a window that lies outside of the window region

int SetWindowRgn(

HWND hWnd,	// handle to window whose window region is to be set
HRGN hRgn,	// handle to region
BOOL bRedraw	// window redraw flag
);
Parameters

hWnd

Handle to the window whose window region is to be set.

hRgn

Handle to a region. The function sets the window region of the window to this region.

If hRgn is NULL, the function sets the window region to NULL.

bRedraw

Boolean value that specifies whether the operating system redraws the window after setting the window region. If bRedraw is TRUE, the operating system does so; otherwise, it does not.

Typically, you set bRedraw to TRUE if the window is visible.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

If the bRedraw parameter is TRUE, the system sends the WM_WINDOWPOSCHANGING and WM_WINDOWPOSCHANGED messages to the window.

The coordinates of a window’s window region are relative to the upper-left corner of the window, not the client area of the window.

After a successful call to SetWindowRgn, the operating system owns the region specified by the region handle hRgn. The operating system does not make a copy of the region. Thus, you should not make any further function calls with this region handle. In particular, do not close this region handle.

To obtain the window region of a window, call the GetWindowRgn function.

See Also

GetWindowRgn, WM_WINDOWPOSCHANGING


SetWindowsHook

The SetWindowsHook function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the SetWindowsHookEx function.


SetWindowsHookEx

The SetWindowsHookEx function installs an application-defined hook procedure into a hook chain. An application installs a hook procedure to monitor the system for certain types of events. A hook procedure can monitor events associated either with a specific thread or with all threads in the system. This function supersedes the SetWindowsHook function.

HHOOK SetWindowsHookEx(

int idHook,	// type of hook to install
HOOKPROC lpfn,	// address of hook procedure
HINSTANCE hMod,	// handle of application instance
DWORD dwThreadId	// identity of thread to install hook for
);
Parameters

idHook

Specifies the type of hook procedure to be installed. This parameter can be one of the following values:

Value	Description
WH_CALLWNDPROC	Installs a hook procedure that monitors messages before the system sends them to the destination window procedure. For more information, see the CallWndProc hook procedure.
WH_CALLWNDPROCRET	Installs a hook procedure that monitors messages after they have been processed by the destination window procedure. For more information, see the CallWndRetProc hook procedure.
WH_CBT	Installs a hook procedure that receives notifications useful to a computer-based training (CBT) application. For more information, see the CBTProc hook procedure.
WH_DEBUG	Installs a hook procedure useful for debugging other hook procedures. For more information, see the DebugProc hook procedure.
WH_GETMESSAGE	Installs a hook procedure that monitors messages posted to a message queue. For more information, see the GetMsgProc hook procedure.
WH_JOURNALPLAYBACK	Installs a hook procedure that posts messages previously recorded by a WH_JOURNALRECORD hook procedure. For more information, see the JournalPlaybackProc hook procedure.
WH_JOURNALRECORD	Installs a hook procedure that records input messages posted to the system message queue. This hook is useful for recording macros. For more information, see the JournalRecordProc hook procedure.
WH_KEYBOARD	Installs a hook procedure that monitors keystroke messages. For more information, see the KeyboardProc hook procedure.
WH_MOUSE	Installs a hook procedure that monitors mouse messages. For more information, see the MouseProc hook procedure.
WH_MSGFILTER	Installs a hook procedure that monitors messages generated as a result of an input event in a dialog box, message box, menu, or scroll bar. For more information, see the MessageProc hook procedure.
WH_SHELL	Installs a hook procedure that receives notifications useful to shell applications. For more information, see the ShellProc hook procedure.
WH_SYSMSGFILTER	Installs a hook procedure that monitors messages generated as a result of an input event in a dialog box, message box, menu, or scroll bar. The hook procedure monitors these messages for all applications in the system. For more information, see the SysMsgProc hook procedure.
lpfn

Points to the hook procedure. If the dwThreadId parameter is zero or specifies the identifier of a thread created by a different process, the lpfn parameter must point to a hook procedure in a dynamic-link library (DLL). Otherwise, lpfn can point to a hook procedure in the code associated with the current process.

hMod

Identifies the DLL containing the hook procedure pointed to by the lpfn parameter. The hMod parameter must be set to NULL if the dwThreadId parameter specifies a thread created by the current process and if the hook procedure is within the code associated with the current process.

dwThreadId

Specifies the identifier of the thread with which the hook procedure is to be associated. If this parameter is zero, the hook procedure is associated with all existing threads.

Return Values

If the function succeeds, the return value is the handle of the hook procedure.

If the function fails, the return value is NULL.

Remarks

An error may occur if the hMod parameter is NULL and the dwThreadId parameter is zero or specifies the identifier of a thread created by another process.

Chaining to the next hook procedure (that is, calling the CallNextHookEx function) is optional. An application or library can call the next hook procedure either before or after any processing in its own hook procedure. Although chaining to the next hook is optional, it is highly recommended; otherwise, the other applications that have installed hooks will not receive hook notifications and may behave incorrectly as a result.

Before terminating, an application must call the UnhookWindowsHookEx function to free system resources associated with the hook.

The scope of a hook depends on the hook type. Some hooks can be set only with system scope; others can also be set for only a specific thread, as shown in the following list:

Hook	Scope
WH_CALLWNDPROC	Thread or system
WH_CBT	Thread or system
WH_DEBUG	Thread or system
WH_GETMESSAGE	Thread or system
WH_JOURNALPLAYBACK	System only
WH_JOURNALRECORD	System only
WH_KEYBOARD	Thread or system
WH_MOUSE	Thread or system
WH_MSGFILTER	Thread or system
WH_SHELL	Thread or system
WH_SYSMSGFILTER	System only
For a specified hook type, thread hooks are called first, then system hooks.

The system hooks are a shared resource, and installing one affects all applications. All system hook functions must be in libraries. System hooks should be restricted to special-purpose applications or to use as a development aid during application debugging. Libraries that no longer need a hook should remove the hook procedure.

See Also

CallNextHookEx, CallWndProc, CallWndRetProc, CBTProc, DebugProc, GetMsgProc, JournalPlaybackProc, JournalRecordProc, KeyboardProc, MouseProc, MessageProc, ShellProc, SysMsgProc, UnhookWindowsHookEx


SetWindowText

The SetWindowText function changes the text of the specified window’s title bar (if it has one). If the specified window is a control, the text of the control is changed.

BOOL SetWindowText(

HWND hWnd,	// handle of window or control
LPCTSTR lpString	// address of string
);
Parameters

hWnd

Identifies the window or control whose text is to be changed.

lpString

Points to a null-terminated string to be used as the new title or control text.

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.

Remarks

The SetWindowText function causes a WM_SETTEXT message to be sent to the specified window or control. If the window is a list box control created with the WS_CAPTION style, however, SetWindowText sets the text for the control, not for the list box entries.

The SetWindowText function does not expand tab characters (ASCII code 0x09). Tab characters are displayed as vertical bar (|) characters.

See Also

GetWindowText, WM_SETTEXT


SetWindowWord

The SetWindowWord function replaces the 16-bit (word) value at the specified offset into the extra window memory for the specified window.

WORD SetWindowWord(

HWND hWnd,	// handle of window
int nIndex,	// offset of value to set
WORD wNewWord	// new value
);
Parameters

hWnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the zero-based byte offset of the value to be replaced. Valid values are in the range zero through the number of bytes of window memory, minus two; for example, if you specified 10 or more bytes of extra window memory, a value of 8 would be an index to the fifth 16-bit integer.

wNewWord

Specifies the replacement value.

Return Values

If the function succeeds, the return value is the previous value of the specified 16-bit integer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the WNDCLASS structure used with the RegisterClass function.

The GWW_ values are obsolete in the Win32 API. You must use the SetWindowLong function to set information about the window.

See Also

GetParent, GetWindowLong, GetWindowWord, RegisterClass, SetParent, SetWindowLong, WNDCLASS


SetWinMetaFileBits

The SetWinMetaFileBits function converts a metafile from the older Windows format to the new enhanced format and stores the new metafile in memory.

HENHMETAFILE SetWinMetaFileBits(

UINT cbBuffer,	// size of buffer
CONST BYTE *lpbBuffer,	// address of buffered metafile data
HDC hdcRef,	// handle of reference device context
CONST METAFILEPICT *lpmfp	// suggested size of metafile picture
);
Parameters

cbBuffer

Specifies the size, in bytes, of the buffer that contains the Windows-format metafile.

lpbBuffer

Points to a buffer that contains the Windows-format metafile data. (It is assumed that the data was obtained by using the GetMetaFileBitsEx or GetWinMetaFileBits function.)

hdcRef

Identifies a reference device context.

lpmfp

Points to a METAFILEPICT structure that contains the suggested size of the metafile picture and the mapping mode that was used when the picture was created.

Return Values

If the function succeeds, the return value is a handle of a memory-based enhanced metafile.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Windows uses the reference device context’s resolution data and the data in the METAFILEPICT structure to scale a picture. If the hdcRef parameter is NULL, Windows uses resolution data for the current output device. If the lpmfp parameter is NULL, Windows uses the MM_ANISOTROPIC mapping mode to scale the picture so that it fits the entire device surface. The hMF field in the METAFILEPICT structure is not used.

When the application no longer needs the enhanced metafile handle, it should delete it by calling the DeleteEnhMetaFile function.

The handle returned by this function can be used with other enhanced-metafile functions.

If the reference device context is not identical to the device in which the metafile was originally created, some GDI functions that use device units may not draw the picture correctly.

See Also

DeleteEnhMetaFile, GetWinMetaFileBits, GetMetaFileBitsEx, METAFILEPICT, PlayEnhMetaFile


SetWorldTransform

The SetWorldTransform function sets a two-dimensional linear transformation between world space and page space for the specified device context. This transformation can be used to scale, rotate, shear, or translate graphics output.

BOOL SetWorldTransform(

HDC hdc,	// handle of device context
CONST XFORM *lpXform	// address of transformation data
);
Parameters

hdc

Identifies the device context.

lpXform

Points to an XFORM structure that contains the transformation data.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

For any coordinates (x, y) in world space, the transformed coordinates in page space (x’, y’) can be determined by the following algorithm:

x' = x * eM11 + y * eM21 + eDx,

y' = x * eM12 + y * eM22 + eDy,

where the transformation matrix is represented by the following:

| eM11 eM12 0 |

| eM21 eM22 0 |

| eDx  eDy  1 |

The mapping mode (defined by the current window and viewport extents origins) serves to define units and scales.

The world transformation is usually used to scale or rotate logical images in a device-independent way.

The default world transformation is the identity matrix with zero offset.

The SetWorldTransform function will fail unless the graphics mode for the given device context has been set to GM_ADVANCED by previously calling the SetGraphicsMode function. Likewise, it will not be possible to reset the graphics mode for the device context to the default GM_COMPATIBLE mode, unless the world transformation has first been reset to the default identity transformation by calling SetWorldTransform or ModifyWorldTransform.

See Also

GetWorldTransform, ModifyWorldTransform, SetGraphicsMode, SetMapMode, SetViewportExtEx, SetViewportOrgEx, SetWindowExtEx, SetWindowOrgEx, XFORM


SHAddToRecentDocs [Now Supported on Windows NT]
SHAddToRecentDocs

[Now Supported on Windows NT]

Adds a document to the shell’s list of recently used documents or clears all documents from the list. The user gains access to the list through the Start menu of the Windows taskbar.

WINSHELLAPI void WINAPI SHAddToRecentDocs(

UINT uFlags,
LPCVOID pv
);
Parameters

uFlags

Flag that indicates the meaning of the pv parameter. This parameter can be one of the following values:

SHARD_PATH	pv is the address of a path string.
SHARD_PIDL	pv is the address of an item identifier list.
pv

Pointer to a buffer that contains the path and filename of the document, or the address of an ITEMIDLIST structure that contains an item identifier list uniquely identifying the document. If this parameter is NULL, the function clears all documents from the list.

Return Values

No return value.


SHAppBarMessage [Now Supported on Windows NT]
SHAppBarMessage

[Now Supported on Windows NT]

Sends an appbar message to the system.

WINSHELLAPI UINT APIENTRY SHAppBarMessage(

DWORD dwMessage,
PAPPBARDATA pData
);
Parameters

dwMessage

Identifier of the appbar message to send. This parameter can be one of the following values:

ABM_ACTIVATE	Notifies the system that an appbar has been activated.
ABM_GETAUTOHIDEBAR	Retrieves the handle of the autohide appbar associated with a particular edge of the screen.
ABM_GETSTATE	Retrieves the autohide and always-on-top states of the Windows taskbar.
ABM_GETTASKBARPOS	Retrieves the bounding rectangle of the Windows taskbar.
ABM_NEW	Registers a new appbar and specifies the message identifier that the system should use to send notification messages to the appbar.
ABM_QUERYPOS	Requests a size and screen position for an appbar.
ABM_REMOVE	Unregisters an appbar, removing bar from the system’s internal list.
ABM_SETAUTOHIDEBAR	Registers or unregisters an autohide appbar for an edge of the screen.
ABM_SETPOS	Sets the size and screen position of an appbar.
ABM_WINDOWPOSCHANGED	Notifies the system when an appbar’s position has changed.
pData

Pointer to an APPBARDATA structure. The content of the structure depends on the value of dwMessage.

Return Values

Returns a message-dependent value. For more information, see the documentation for the individual appbar messages.

See Also

APPBARDATA


SHBrowseForFolder [Now Supported on Windows NT]
SHBrowseForFolder

[Now Supported on Windows NT]

Displays a dialog box that enables the user to select a shell folder.

WINSHELLAPI LPITEMIDLIST WINAPI SHBrowseForFolder(

LPBROWSEINFO lpbi
);
Parameters

lpbi

Pointer to a BROWSEINFO structure that contains information used to display the dialog box.

Return Values

Returns a pointer to an item identifier list that specifies the location of the selected folder relative to the root of the name space. If the user chooses the Cancel button in the dialog box, the return value is NULL.

The calling application is responsible for freeing the returned item identifier list using the shell’s task allocator.

See Also

BROWSEINFO


SHChangeNotify [Now Supported on Windows NT]
SHChangeNotify

[Now Supported on Windows NT]

Notifies the system of an event that an application has performed. An application should use this function if it performs an action that may affect the shell.

WINSHELLAPI void WINAPI SHChangeNotify(

LONG wEventId,
UINT uFlags,
LPCVOID dwItem1,
LPCVOID dwItem2
);
Parameters

wEventId

Array of flags that specifies the events. This parameter can be a combination of the following values:

SHCNE_ASSOCCHANGED	Changed a file type association.
SHCNE_ATTRIBUTES	Changed a file’s attributes.
SHCNE_CREATE	Created a file.
SHCNE_DELETE	Deleted a file.
SHCNE_DRIVEADD	Added a network drive.
SHCNE_DRIVEADDGUI	Added a network drive by way of a graphic user interface.
SHCNE_DRIVEREMOVED	Removed a network drive.
SHCNE_INTERRUPT	Performed the event as a result of a system interrupt.
SHCNE_MEDIAINSERTED	Added removable media, such as a CD-ROM.
SHCNE_MEDIAREMOVED	Removed a removable medium, such as a CD-ROM.
SHCNE_MKDIR	Created a new directory.
SHCNE_NETSHARE	Shared a resource on the network.
SHCNE_NETUNSHARE	Stopped sharing a resource.
SHCNE_RENAMEFOLDER	Renamed a folder.
SHCNE_RENAMEITEM	Renamed an item in a folder.
SHCNE_RMDIR	Removed a directory.
SHCNE_SERVERDISCONNECT	Disconnected a network server.
SHCNE_UPDATEDIR	Updated the contents of a directory.
SHCNE_UPDATEIMAGE	Changed an image in the system global image list.
SHCNE_UPDATEITEM	Changed the properties of a printer or file.
uFlags

Flag that indicates the meaning of dwItem1 and dwItem2. This parameter can be one of the following values:

SHCNF_DWORD	The dwItem1 and dwItem2 parameters are doubleword values.
SHCNF_FLUSH	Flushes the system event buffer. The function does not return until the system is finished processing the given event.
SHCNF_FLUSHNOWAIT	Flushes the system event buffer. The function returns immediately regardless of whether the system is finished processing the given event.
SHCNF_IDLIST	dwItem1 and dwItem2 are the addresses of item identifier lists.
SHCNF_PATH	dwItem1 and dwItem2 are path names.
SHCNF_PRINTER	dwItem1 and dwItem2 are printer “friendly” names.
dwItem1

First event-dependent value.

dwItem2

Second event-dependent value.

Return Values

No return value.


Shell_NotifyIcon [Now Supported on Windows NT]
Shell_NotifyIcon

[Now Supported on Windows NT]

Sends a message to the system to add, modify, or delete an icon from the taskbar status area.

WINSHELLAPI BOOL WINAPI Shell_NotifyIcon(

DWORD dwMessage,	// message identifier
PNOTIFYICONDATA pnid	// pointer to structure
);
Parameters

dwMessage

Identifier of the message to send. This parameter can be one of these values:

NIM_ADD	Adds an icon to the status area.
NIM_DELETE	Deletes an icon from the status area.
NIM_MODIFY	Modifies an icon in the status area.
pnid

Pointer to a NOTIFYICONDATA structure. The content of the structure depends on the value of dwMessage.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.


ShellAbout

The ShellAbout function displays a Shell About dialog box.

int ShellAbout (

HWND hWnd,	// handle of parent window
LPCTSTR szApp,	// title bar and first line text
LPCTSTR szOtherStuff,	// other dialog text
HICON hIcon	// icon to display
);
Parameters

hWnd

Identifies a parent window. This parameter can be NULL.

szApp

Points to text that the function displays in the title bar of the Shell About dialog box and on the first line of the dialog box after the text “Microsoft Windows” or “Microsoft Windows NT.” If the text contains a “#” separator, dividing it into two parts, the function displays the first part in the title bar, and the second part on the first line after the text “Microsoft Windows” or “Microsoft Windows NT.”

szOtherStuff

Points to text that the function displays in the dialog box after the version and copyright information.

hIcon

Identifies an icon that the function displays in the dialog box. If this parameter is NULL, the function displays the Microsoft Windows or Microsoft Windows NT icon.

Return Values

If the function succeeds in displaying the dialog box, the return value is TRUE; otherwise the return value is FALSE.

Remarks

Please note that the ShellAbout function dialog box uses text and a default icon that are specific to either Microsoft Windows or Microsoft Windows NT.

An example of a Shell About dialog box can be seen by selecting the About Program Manager command in Program Manager.


ShellExecute

The ShellExecute function opens or prints a specified file. The file can be an executable file or a document file. See ShellExecuteEx also.

HINSTANCE ShellExecute(

HWND hwnd,	// handle to parent window
LPCTSTR lpOperation,	// pointer to string that specifies operation to perform
LPCTSTR lpFile,	// pointer to filename or folder name string
LPCTSTR lpParameters,	// pointer to string that specifies executable-file parameters
LPCTSTR lpDirectory,	// pointer to string that specifies default directory
INT nShowCmd	// whether file is shown when opened
);
Parameters

hwnd

Specifies a parent window. This window receives any message boxes that an application produces. For example, an application may report an error by producing a message box.

lpOperation

Pointer to a null-terminated string that specifies the operation to perform. The following operation strings are valid:

String	Meaning
“open”	The function opens the file specified by lpFile. The file can be an executable file or a document file. The file can be a folder to open.
“print”	The function prints the file specified by lpFile. The file should be a document file. If the file is an executable file, the function opens the file, as if “open” had been specified.
“explore”	The function explores the folder specified by lpFile.
The lpOperation parameter can be NULL. In that case, the function opens the file specified by lpFile.

lpFile

Pointer to a null-terminated string that specifies the file to open or print or the folder to open or explore. The function can open an executable file or a document file. The function can print a document file.

lpParameters

If lpFile specifies an executable file, lpParameters is a pointer to a null-terminated string that specifies parameters to be passed to the application.

If lpFile specifies a document file, lpParameters should be NULL.

lpDirectory

Pointer to a null-terminated string that specifies the default directory.

nShowCmd

If lpFile specifies an executable file, nShowCmd specifies how the application is to be shown when it is opened.  This parameter can be one of the following values:

Value	Meaning
SW_HIDE	Hides the window and activates another window.
SW_MAXIMIZE	Maximizes the specified window.
SW_MINIMIZE	Minimizes the specified window and activates the next top-level window in the Z order.
SW_RESTORE	Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when restoring a minimized window.
SW_SHOW	Activates the window and displays it in its current size and position.
SW_SHOWDEFAULT	Sets the show state based on the SW_ flag specified in the STARTUPINFO structure passed to the CreateProcess function by the program that started the application. An application should call ShowWindow with this flag to set the initial show state of its main window.
SW_SHOWMAXIMIZED	Activates the window and displays it as a maximized window.
SW_SHOWMINIMIZED	Activates the window and displays it as a minimized window.
SW_SHOWMINNOACTIVE	Displays the window as a minimized window. The active window remains active.
SW_SHOWNA	Displays the window in its current state. The active window remains active.
SW_SHOWNOACTIVATE	Displays a window in its most recent size and position. The active window remains active.
SW_SHOWNORMAL	Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when displaying the window for the first time.
If lpFile specifies a document file, nShowCmd should be zero.

Return Values

If the function succeeds, the return value is the instance handle of the application that was run, or the handle of a dynamic data exchange (DDE) server application.

If the function fails, the return value is an error value that is less than or equal to 32. The following table lists these error values:

Value	Meaning
0	The operating system is out of memory or resources.
ERROR_FILE_NOT_FOUND	The specified file was not found.
ERROR_PATH_NOT_FOUND	The specified path was not found.
ERROR_BAD_FORMAT	The .EXE file is invalid (non-Win32 .EXE or error in .EXE image).
SE_ERR_ACCESSDENIED	The operating system denied access to the specified file.
SE_ERR_ASSOCINCOMPLETE	The filename association is incomplete or invalid.
SE_ERR_DDEBUSY	The DDE transaction could not be completed because other DDE transactions were being processed.
SE_ERR_DDEFAIL	The DDE transaction failed.
SE_ERR_DDETIMEOUT	The DDE transaction could not be completed because the request timed out.
SE_ERR_DLLNOTFOUND	The specified dynamic-link library was not found.
SE_ERR_FNF	The specified file was not found.
SE_ERR_NOASSOC	There is no application associated with the given filename extension.
SE_ERR_OOM	There was not enough memory to complete the operation.
SE_ERR_PNF	The specified path was not found.
SE_ERR_SHARE	A sharing violation occurred.
Remarks

The file specified by the lpFile parameter can be a document file or an executable file. If the file is a document file, the ShellExecute function opens or prints it, depending on the value of the lpOperation parameter. If the file is an executable file, the ShellExecute function opens it, even if lpOperation specifies printing.

You can use ShellExecute to open or explore a shell folder. To open a folder, use either of the following calls:

ShellExecute(handle, NULL, path_to_folder, NULL, NULL, SW_SHOWNORMAL);

or

ShellExecute(handle, "open", path_to_folder, NULL, NULL, SW_SHOWNORMAL);

To explore a folder, use the following call:

ShellExecute(handle, "explore", path_to_folder, NULL, NULL, SW_SHOWNORMAL);

If lpOperation is NULL, the function opens the file specified by lpFile. If lpOperation is “open” or “explore”, the function will force an open window or explorer.

See Also

FindExecutable, ShellExecuteEx


ShellExecuteEx [Now Supported on Windows NT]
ShellExecuteEx

[Now Supported on Windows NT]

The ShellExecuteEx function performs an action on a file. The file can be an executable file or a document.

WINSHELLAPI BOOL WINAPI ShellExecuteEx(

LPSHELLEXECUTEINFO lpExecInfo	// pointer to SHELLEXECUTEINFO structure
);
Parameters

lpExecInfo

Pointer to a SHELLEXECUTEINFO structure that contains and receives information about the application to start.

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.

Remarks

If the function succeeds, it sets the hInstApp member of the SHELLEXECUTEINFO structure to the instance handle of the application that the function started. If the function fails, hInstApp is one of the SE_ERR_ error values indicating the cause of the failure. (An instance handle will always be greater than 32, and an error value less than 32.) Note that the SE_ERR_ error values are for compatibility with the ShellExecute function; use the GetLastError function to retrieve error information.

Last error values returned by GetLastError correspond to the SE_ERR_ values and may be one of the following:

Value	Meaning
ERROR_FILE_NOT_FOUND	The specified file was not found.
ERROR_PATH_NOT_FOUND	The specified path was not found.
ERROR_DDE_FAIL	The DDE transaction failed.
ERROR_NO_ASSOCIATION	There is no application associated with the given filename extension.
ERROR_ACCESS_DENIED
ERROR_DLL_NOT_FOUND
ERROR_CANCELLED	The function prompted the user for the location of the application, but the user cancelled the request.
ERROR_NOT_ENOUGH_MEMORY
ERROR_SHARING_VIOLATION	A sharing violation occurred.
See Also

ShellExecute, SHELLEXECUTEINFO


ShellProc

The ShellProc hook procedure is an application-defined or library-defined callback function a shell application uses to receive useful notifications from the system.

LRESULT CALLBACK ShellProc(

int nCode,	// hook code
WPARAM wParam,	// event-specific information
LPARAM lParam	// event-specific information
);
Parameters

nCode

Specifies the hook code. This parameter can be one of the following values:

Value	Meaning
HSHELL_ACTIVATESHELLWINDOW	The shell should activate its main window.
HSHELL_GETMINRECT	Windows 95 only: A window is being minimized or maximized and the system needs the coordinates of the minimized rectangle for the window. The wParam parameter contains the handle of the window, and the lParam parameter contains the address of a RECT structure that receives the coordinates.
HSHELL_LANGUAGE	Windows 95 only: Keyboard language was changed or a new keyboard layout was loaded.
HSHELL_REDRAW	Windows 95 only: The title of a window in the task bar has been redrawn. The wParam parameter contains the handle of the window.
HSHELL_TASKMAN	Windows 95 only: The user has selected the task list. The wParam parameter is undefined and should be ignored. A shell application that provides a task list should return TRUE to prevent Windows from starting its task list.
HSHELL_WINDOWACTIVATED	Windows 95 only: The activation has changed to a different top-level, unowned window. The wParam parameter contains the handle of the window.
HSHELL_WINDOWCREATED	A top-level, unowned window has been created. The window exists when the system calls a ShellProc function.
HSHELL_WINDOWDESTROYED	A top-level, unowned window is about to be destroyed. The window still exists when the system calls a ShellProc function.
If nCode is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies additional information the shell application may require. If the nCode parameter is HSHELL_ACTIVATESHELLWINDOW, the wParam parameter is not used. If nCode is HSHELL_WINDOWCREATED or HSHELL_WINDOWDESTROYED, wParam specifies the handle of the window being created or destroyed, respectively.

lParam

Windows 95:

Specifies additional information. The exact value depends on the value of the nCode parameter. If nCode is HSHELL_GETMINRECT, lParam is LPRECT. If nCode is HSHELL_WINDOWSACTIVATED, lParam is fFullScreen. If nCode is HSHELL_REDRAW, lParam is fNewFlash.

Windows NT:

This parameter must be zero.

Return Values

The return value should be zero.

Remarks

An application installs the hook procedure by specifying the WH_SHELL hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

ShellProc is a placeholder for the application-defined or library-defined function name.

See Also

CallNextHookEx, SendMessage, SetWindowsHookEx


SHFileOperation [Now Supported on Windows NT]
SHFileOperation

[Now Supported on Windows NT]

Performs a copy, move, rename, or delete operation on a file system object.

WINSHELLAPI int WINAPI SHFileOperation(

LPSHFILEOPSTRUCT lpFileOp
);
Parameters

lpFileOp

Pointer to an SHFILEOPSTRUCT structure that contains information the function needs to carry out the operation.

Return Values

Returns zero if successful or nonzero if an error occurs.

See Also

SHFILEOPSTRUCT


SHFreeNameMappings [Now Supported on Windows NT]
SHFreeNameMappings

[Now Supported on Windows NT]

Frees a filename mapping object that was retrieved by the SHFileOperation function.

WINSHELLAPI void WINAPI SHFreeNameMappings(;

HANDLE hNameMappings
);
Parameters

hNameMappings

Handle of the filename mapping object to free.

Return Values

No return value.


SHGetDataFromIDList [Now Supported on Windows NT]
SHGetDataFromIDList

[Now Supported on Windows NT]

The ShGetDataFromIDList function retrieves extended property data from a relative IDList.

HRESULT ShGetDataFromIDList(

LPSHELLFOLDER psf,	//Points to the parent folder
LPCITEMIDLIST pidl,	//Points to an item identifier struct
int nFormat,	//Specifies a format
PVOID pv,	//Points to a buffer for a structure
int cb	//Size of the buffer passed in
);
Parameters

psf

Pointer to the parent folder.

pidl

Pointer to an ITEMIDLIST structure that identifies the subfolder relative to its parent folder.

nFormat

Specifies one of the following formats:

SHGDFIL_FINDDATA	Format used for file system objects.
SHGDFIL_NETRESOURCE	Format used for network resources.
pv

Pointer to a buffer for either a WIN32_FIND_DATA or NET_RESOURCE structure, depending on the value of the nFormat parameter. For more information, see the Remarks section below.

cb

Size of the buffer passed in. This value should be either sizeof(WIN32_FIND_DATA) for SHGDFIL_FINDDATA or, sizeof(NETRESOURCE) + 1024 to retrieve a SHGDFIL_NETRESOURCE structure.

Return Values

The return value is NOERROR if the format is supported and the function succeeds. If the psf, pidl, pv, or cb parameters do not match the nFormat parameter, or if nFormat is not one of the specific SHGDFIL_ values shown, E_INVALIDARG is also returned.

Remarks

If nFormat is SHGDFIL_NETRESURCE, there are two possible cases. If the buffer is large enough, the net resource’s string information (fields for the network name, local name, provider, and comments) will be placed into the buffer. If the buffer is not large enough, only the net resource structure will be placed into the buffer and the string information pointers will be NULL.


SHGetDesktopFolder [Now Supported on Windows NT]
SHGetDesktopFolder

[Now Supported on Windows NT]

Retrieves the IShellFolder interface for the desktop folder, which is the root of the shell’s name space.

WINSHELLAPI HRESULT WINAPI SHGetDesktopFolder(

LPSHELLFOLDER *ppshf
);
Parameters

ppshf

Address that receives an IShellFolder interface pointer for the desktop folder. The calling application is responsible for eventually freeing the interface by calling its Release method.

Return Values

Returns NOERROR if successful or an OLE-defined error result otherwise.

See Also

IShellFolder


SHGetFileInfo [Now Supported on Windows NT]
SHGetFileInfo

[Now Supported on Windows NT]

Retrieves information about an object in the file system, such as a file, a folder, a directory, or a drive root.

WINSHELLAPI DWORD WINAPI SHGetFileInfo(

LPCTSTR pszPath,
DWORD dwFileAttributes,
SHFILEINFO FAR *psfi,
UINT cbFileInfo,
UINT uFlags
);
Parameters

pszPath

Pointer to a buffer that contains the path and filename. Both absolute and relative paths are valid. If uFlags includes the SHGFI_PIDL, value pszPath must be the address of an ITEMIDLIST structure that contains the list of item identifiers that uniquely identifies the file within the shell’s name space.

This string can use either short (the 8.3 form) or long filenames.

dwFileAttributes

Array of file attribute flags (FILE_ATTRIBUTE_ values). If uFlags does not include the SHGFI_USEFILEATTRIBUTES value, this parameter is ignored.

psfi and cbFileInfo

Address and size, in bytes, of the SHFILEINFO structure that receives the file information.

uFlags

Flag that specifies the file information to retrieve. This parameter can be a combination of the following values:

SHGFI_ATTRIBUTES	Retrieves the file attribute flags. The flags are copied to the dwAttributes member of the structure specified by psfi.
SHGFI_DISPLAYNAME	Retrieves the display name for the file. The name is copied to the szDisplayName member of the structure specified by psfi. The returned display name uses the long filename, if any, rather than the 8.3 form of the filename.
SHGFI_EXETYPE	Returns the type of the executable file if pszPath identifies an executable file. For more information, see the comments below.
SHGFI_ICON	Retrieves the handle of the icon that represents the file and the index of the icon within the system image list. The handle is copied to the hIcon member of the structure specified by psfi, and the index is copied to the iIcon member. The return value is the handle of the system image list.
SHGFI_ICONLOCATION	Retrieves the name of the file that contains the icon representing the file. The name is copied to the szDisplayName member of the structure specified by psfi.
SHGFI_LARGEICON	Modifies SHGFI_ICON, causing the function to retrieve the file’s large icon.
SHGFI_LINKOVERLAY	Modifies SHGFI_ICON, causing the function to add the link overlay to the file’s icon.
SHGFI_OPENICON	Modifies SHGFI_ICON, causing the function to retrieve the file’s open icon. A container object displays an open icon to indicate that the container is open.
SHGFI_PIDL	Indicates that pszPath is the address of an ITEMIDLIST structure rather than a path name.
SHGFI_SELECTED	Modifies SHGFI_ICON, causing the function to blend the file’s icon with the system highlight color.
SHGFI_SHELLICONSIZE	Modifies SHGFI_ICON, causing the function to retrieve a shell-sized icon. If this flag is not specified, the function sizes the icon according to the system metric values.
SHGFI_SMALLICON	Modifies SHGFI_ICON, causing the function to retrieve the file’s small icon.
SHGFI_SYSICONINDEX	Retrieves the index of the icon within the system image list. The index is copied to the iIcon member of the structure specified by psfi. The return value is the handle of the system image list.
SHGFI_TYPENAME	Retrieves the string that describes the file’s type. The string is copied to the szTypeName member of the structure specified by psfi.
SHGFI_USEFILEATTRIBUTES	Indicates that the function should use the dwFileAttributes parameter.
To retrieve the executable file type, uFlags must specify only SHGFI_EXETYPE. The return value specifies the type of the executable file:

0	Nonexecutable file or an error condition.
LOWORD = NE or PE HIWORD = 3.0, 3.5, or 4.0	Windows application
LOWORD = MZ HIWORD = 0	MS-DOS .EXE, .COM or .BAT file
LOWORD = PE HIWORD = 0	Win32 console application
Return Values

•	Returns a value whose meaning depends on the uFlags parameter. If uFlags specifies the SHGFI_EXETYPE value, the return value indicates the type of the executable file. For more information, see the comments below.

•	If uFlags includes the SHGFI_ICON or SHGFI_SYSICONINDEX value, the return value is the handle of the system image list that contains the large icon images. If the SHGFI_SMALLICON value is also included, the return value is the handle of the image list that contains the small icon images.

•	If uFlags does not include SHGFI_EXETYPE, SHGFI_ICON, SHGFI_SYSICONINDEX, or SHGFI_SMALLICON, the return value is nonzero the function succeeds, or zero otherwise.


SHGetInstanceExplorer [Now Supported on Windows NT]
SHGetInstanceExplorer

[Now Supported on Windows NT]

Retreives the address of the Explorer’s IUnknown interface.

WINSHELLAPI HRESULT WINAPI SHGetInstanceExplorer(

IUnknown *ppunk
);
Parameters

ppunk

Pointer to a value that receives the address of the Explorer’s IUnknown interface.

Return Values

Returns NOERROR if successful or E_FAIL otherwise.


SHGetMalloc [Now Supported on Windows NT]
SHGetMalloc

[Now Supported on Windows NT]

Retrieves a pointer to the shell’s IMalloc interface. A shell extension must use this interface to allocate memory that is later freed by the shell.

HRESULT SHGetMalloc(

LPMALLOC *ppMalloc
);
Parameters

ppMalloc

Address of a value that receives the address of the shell’s IMalloc interface.

Return Values

Returns the NOERROR value if successful or E_FAIL otherwise.


SHGetPathFromIDList [Now Supported on Windows NT]
SHGetPathFromIDList

[Now Supported on Windows NT]

Converts an item identifier list to a file system path.

WINSHELLAPI BOOL WINAPI SHGetPathFromIDList(

LPCITEMIDLIST pidl,
LPSTR pszPath
);
Parameters

pidl

Pointer to an item identifier list that specifies a file or directory location relative to the root of the name space (the desktop).

pszPath

Pointer to a buffer that receives the file system path. The size of this buffer is assumed to be MAX_PATH bytes.

Return Values

Returns TRUE if successful or FALSE if an error occurs — for example, if the location specified by the pidl parameter is not part of the file system.


SHGetSpecialFolderLocation [Now Supported on Windows NT]
SHGetSpecialFolderLocation

[Now Supported on Windows NT]

Retrieves the location of a special folder.

WINSHELLAPI HRESULT WINAPI SHGetSpecialFolderLocation(;

HWND hwndOwner,
int nFolder,
LPITEMIDLIST *ppidl
);
Parameters

hwndOwner

Handle of the owner window that the client should specify if it displays a dialog box or message box.

nFolder

Value specifying the folder to retrieve the location of. This parameter can be one of the following values:

CSIDL_BITBUCKET	Recycle bin — file system directory containing file objects in the user’s recycle bin. The location of this directory is not in the registry; it is marked with the hidden and system attributes to prevent the user from moving or deleting it.
CSIDL_CONTROLS	Control Panel — virtual folder containing icons for the control panel applications.
CSIDL_DESKTOP	Windows desktop — virtual folder at the root of the name space.
CSIDL_DESKTOPDIRECTORY	File system directory used to physically store file objects on the desktop (not to be confused with the desktop folder itself).
CSIDL_DRIVES	My Computer — virtual folder containing everything on the local computer: storage devices, printers, and Control Panel. The folder may also contain mapped network drives.
CSIDL_FONTS	Virtual folder containing fonts.
CSIDL_NETHOOD	File system directory containing objects that appear in the network neighborhood.
CSIDL_NETWORK	Network Neighborhood — virtual folder representing the top level of the network hierarchy.
CSIDL_PERSONAL	File system directory that serves as a common respository for documents.
CSIDL_PRINTERS	Printers folder — virtual folder containing installed printers.
CSIDL_PROGRAMS	File system directory that contains the user’s program groups (which are also file system directories).
CSIDL_RECENT	File system directory that contains the user’s most recently used documents.
CSIDL_SENDTO	File system directory that contains Send To menu items.
CSIDL_STARTMENU	File system directory containing Start menu items.
CSIDL_STARTUP	File system directory that corresponds to the user’s Startup program group.
CSIDL_TEMPLATES	File system directory that serves as a common repository for document templates.
ppidl

Address that receives a pointer to an item identifier list specifying the folder’s location relative to the root of the name space (the desktop).

Return Values

Returns NOERROR if successful or an OLE-defined error result otherwise.


SHLoadInProc [Now Supported on Windows NT]
SHLoadInProc

[Now Supported on Windows NT]

Creates an instance of the specified object class from within the context of the shell’s process.

WINSHELLAPI HRESULT WINAPI SHLoadInProc(

REFCLSID rclsid
);
Parameters

rclsid

CLSID of the object class to be created.

Return Values

Returns NOERROR if successful or an OLE-defined error result otherwise.


ShowCaret

The ShowCaret function makes the caret visible on the screen at the caret’s current position. When the caret becomes visible, it begins flashing automatically.

BOOL ShowCaret(

HWND hWnd	// handle of window with caret
);
Parameters

hWnd

Identifies the window that owns the caret. If this parameter is NULL, ShowCaret searches the current task for the window that owns the caret.

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.

Remarks

ShowCaret shows the caret only if the specified window owns the caret, the caret has a shape, and the caret has not been hidden two or more times in a row. If one or more of these conditions is not met, ShowCaret does nothing and returns FALSE.

Hiding is cumulative. If your application calls HideCaret five times in a row, it must also call ShowCaret five times before the caret reappears.

The caret is a shared resource; there is only one caret in the system. A window should show a caret only when the window has the keyboard focus or is active.

See Also

CreateCaret, DestroyCaret, GetCaretPos, HideCaret, SetCaretPos


ShowCursor

The ShowCursor function displays or hides the cursor.

int ShowCursor(

BOOL bShow	// cursor visibility flag
);
Parameters

bShow

Specifies whether the internal display counter is to be incremented or decremented. If bShow is TRUE, the display count is incremented by one. If bShow is FALSE, the display count is decremented by one.

Return Values

The return value specifies the new display counter.

Remarks

This function sets an internal display counter that determines whether the cursor should be displayed. The cursor is displayed only if the display count is greater than or equal to 0. If a mouse is installed, the initial display count is 0. If no mouse is installed, the display count is −1.

See Also

ClipCursor, GetCursorPos, SetCursor, SetCursorPos


ShowHideMenuCtl

The ShowHideMenuCtl function sets or removes the specified menu item’s check-mark attribute, and shows or hides the corresponding control. The function adds a check mark to the specified menu item if it does not have one and then displays the corresponding control. If the menu item already has a check mark, the function removes the check mark and hides the corresponding control.

BOOL ShowHideMenuCtl(

HWND hWnd,	// handle to MDI child window
UINT uFlags,	// message
LPINT lpInfo	// first message parameter
);
Parameters

hWnd

Handle to the window that contains the menu and controls.

uFlags

Identifier of the menu item to receive or lose a check mark.

lpInfo

Pointer to an array that contains pairs of values. The second value in the first pair must be the handle to the application’s main menu. Each subsequent pair consists of a menu item identifier and a control window identifier. The function searches the array for a value that matches uFlags and, if the value is found, checks or unchecks the menu item and shows or hides the corresponding control.

Return Values

If the function shows or hides the control, the return value is nonzero.

If the function does not show or hide the control, the return value is zero.


ShowOwnedPopups

The ShowOwnedPopups function shows or hides all pop-up windows owned by the specified window.

BOOL ShowOwnedPopups(

HWND hWnd,	// handle of window
BOOL fShow	// window visibility flag
);
Parameters

hWnd

Identifies the window that owns the pop-up windows to be shown or hidden.

fShow

Specifies whether pop-up windows are to be shown or hidden. If this parameter is TRUE, all hidden pop-up windows are shown. If this parameter is FALSE, all visible pop-up windows are hidden.

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.

Remarks

ShowOwnedPopups shows only windows hidden by a previous call to ShowOwnedPopups. For example, if a pop-up window is hidden by using the ShowWindow function, subsequently calling ShowOwnedPopups with the fShow parameter set to TRUE does not cause the window to be shown.

See Also

IsWindowVisible, ShowWindow


ShowScrollBar

The ShowScrollBar function shows or hides the specified scroll bar.

BOOL ShowScrollBar(

HWND hWnd,	// handle of window with scroll bar
int wBar,	// scroll bar flag
BOOL bShow	// scroll bar visibility flag
);
Parameters

hWnd

Identifies a scroll bar control or a window with a standard scroll bar, depending on the value of the wBar parameter.

wBar

Specifies the scroll bar(s) to be shown or hidden. This parameter can be one of the following values:

Value	Meaning
SB_BOTH	Shows or hides a window’s standard horizontal and vertical scroll bars.
SB_CTL	Shows or hides a scroll bar control. The hWnd parameter must be the handle of the scroll bar control.
SB_HORZ	Shows or hides a window’s standard horizontal scroll bars.
SB_VERT	Shows or hides a window’s standard vertical scroll bar.
bShow

Specifies whether the scroll bar is shown or hidden. If this parameter is TRUE, the scroll bar is shown; otherwise, it is hidden.

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.

Remarks

While processing a scroll bar message, an application should not call this function to hide a scroll bar.

See Also

GetScrollPos, GetScrollRange, ScrollDC, ScrollWindow, SetScrollPos, SetScrollRange


ShowWindow

The ShowWindow function sets the specified window’s show state.

BOOL ShowWindow(

HWND hWnd,	// handle of window
int nCmdShow	// show state of window
);
Parameters

hWnd

Identifies the window.

nCmdShow

Specifies how the window is to be shown. This parameter is ignored the first time an application calls ShowWindow, if the program that launched the application provides a STARTUPINFO structure. Otherwise, the first time ShowWindow is called, the value should be the value obtained by the WinMain function in its nCmdShow parameter. In subsequent calls, this parameter can be one of the following values:

Value	Meaning
SW_HIDE	Hides the window and activates another window.
SW_MAXIMIZE	Maximizes the specified window.
SW_MINIMIZE	Minimizes the specified window and activates the next top-level window in the Z order.
SW_RESTORE	Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when restoring a minimized window.
SW_SHOW	Activates the window and displays it in its current size and position.
SW_SHOWDEFAULT	Sets the show state based on the SW_ flag specified in the STARTUPINFO structure passed to the CreateProcess function by the program that started the application.
SW_SHOWMAXIMIZED	Activates the window and displays it as a maximized window.
SW_SHOWMINIMIZED	Activates the window and displays it as a minimized window.
SW_SHOWMINNOACTIVE	Displays the window as a minimized window. The active window remains active.
SW_SHOWNA	Displays the window in its current state. The active window remains active.
SW_SHOWNOACTIVATE	Displays a window in its most recent size and position. The active window remains active.
SW_SHOWNORMAL	Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when displaying the window for the first time.
Return Values

If the window was previously visible, the return value is nonzero.

If the window was previously hidden, the return value is zero.

Remarks

The first time a program calls ShowWindow, it uses the WinMain function’s nCmdShow parameter as its nCmdShow parameter. Subsequent calls to ShowWindow must use one of the values in the given list, instead of the one specified by the WinMain function’s nCmdShow parameter.

As noted in the discussion of the nCmdShow parameter, the nCmdShow value is ignored in the first call to ShowWindow if the program that launched the application specifies startup information in the STARTUPINFO structure. In this case, ShowWindow uses the information specified in the STARTUPINFO structure to show the window. On subsequent calls, the application must call ShowWindow with nCmdShow set to SW_SHOWDEFAULT to use the startup information provided by the program that launched the application. For example, Program Manager specifies that applications start with a minimized main window. This behavior is designed for the following situations:

•	Applications create their main window by calling CreateWindow with the WS_VISIBLE flag set.

•	Applications create their main window by calling CreateWindow with the WS_VISIBLE flag cleared, and later call ShowWindow with the SW_SHOW flag set to make it visible.

See Also

CreateProcess, CreateWindow, ShowOwnedPopups, STARTUPINFO, WinMain


ShowWindowAsync [Now Supported on Windows NT]
ShowWindowAsync

[Now Supported on Windows NT]

The ShowWindowAsync function sets the show state of a window created by a different thread.

BOOL ShowWindowAsync(

HWND hWnd,	// handle of window
int nCmdShow	// show state of window
);
Parameters

hWnd

Identifies the window.

nCmdShow

Specifies how the window is to be shown. For a list of possible values, see the description of the ShowWindow function.

Return Values

If the window was previously visible, the return value is nonzero.

If the window was previously hidden, the return value is zero.

Remarks

This function posts a show-window event to the message queue of the given window. An application can use this function to avoid becoming hung while waiting for a hung application to finish processing a show-window event.

See Also

ShowWindow


SignalObjectAndWait [New - Windows NT]
SignalObjectAndWait

[New - Windows NT]

The SignalObjectAndWait function allows the caller to atomically signal an object and wait on another object.

BOOL SignalObjectAndWait(

HANDLE hObjectToSignal,	// handle of object to signal
HANDLE hObjectToWaitOn,	// handle of object to wait for
DWORD dwMilliseconds,	// time-out interval in milliseconds
BOOL bAlertable	// alertable flag
);
Parameters

hObjectToSignal

Specifies the handle to the object to signal. This object can be a semaphore, a mutex, or an event. If the handle is a semaphore, SEMAPHORE_MODIFY_STATE access is required. If the handle is an event, EVENT_MODIFY_STATE access is required. If the handle is a mutex, SYNCHRONIZE access is assumed, because only the owner of a mutex may release it. For more information, see Interprocess Synchronization Objects.

hObjectToWaitOn

Specifies the handle of the object to wait for. For a list of the object types whose handles you can specify, see the Remarks section later in this topic.

dwMilliseconds

Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the object's state is nonsignaled and no completion or asynchronous procedure call (APC) objects are queued. If dwMilliseconds is zero, the function tests the object's state, checks for queued completion routines or APCs, and returns immediately. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.

bAlertable

Specifies whether the function returns when the system queues an I/O completion routine or an APC for the calling thread. If TRUE, the function returns, and the thread calls the completion routine or APC function. If FALSE, the function does not return, and the thread does not call the completion routine or APC function.

Return Values

If the function succeeds, the return value indicates the event that caused the function to return.

If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

Upon success, the return value is one of the following values:

Value	Meaning
WAIT_ABANDONED	The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to nonsignaled.
WAIT_IO_COMPLETION	One or more I/O completion routines or user-mode APCs are queued for execution.
WAIT_OBJECT_0	The state of the specified object is signaled.
WAIT_TIMEOUT	The time-out interval elapsed, and the object's state is nonsignaled.
Remarks

A completion routine is queued for execution when the ReadFileEx or WriteFileEx function in which it was specified has been completed. The wait function returns and the completion routine is executed only if bAlertable is TRUE, and the calling thread is the thread that initiated the read or write operation.

The SignalObjectAndWait function can wait for the following objects:

Object	Description
Change notification	The FindFirstChangeNotification function returns the handle. The state of a change notification object is set to signaled when a specified change occurs within a specified directory or directory tree.
Console input	The handle is returned by the CreateFile function when the CONIN$ value is specified, or by the GetStdHandle function. The state of the object is set to signaled when there is unread input in the console's input buffer, and nonsignaled when the input buffer is empty.
Event	The CreateEvent or OpenEvent function returns the handle. The state of an event object is set explicitly to signaled by the SetEvent or PulseEvent function. The state of a manual-reset event object must be reset explicitly to nonsignaled by the ResetEvent function. For an auto-reset event object, the wait function resets the object state to nonsignaled before returning. Event objects are also used in overlapped operations, in which the state is set by the system.
Mutex	The CreateMutex or OpenMutex function returns the handle. The state of a mutex object is signaled when it is not owned by any thread. The wait function requests ownership of the mutex for the calling thread, changing the mutex state to nonsignaled when ownership is granted.
Process	The CreateProcess or OpenProcess function returns the handle. The state of a process object is signaled when the process terminates.
Semaphore	The CreateSemaphore or OpenSemaphore function returns the handle. A semaphore object maintains a count between zero and the maximum count specified during its creation. Its state is set to signaled when its count is greater than zero, and nonsignaled when its count is zero. If the current state of the semaphore is signaled, the wait function decreases the count by one.
Thread	The CreateProcess, CreateThread, or CreateRemoteThread function returns the handle. The state of a thread object is signaled when the thread terminates.
Timer	The CreateWaitableTimer or OpenWaitableTimer function returns the handle. Activate the timer by calling the SetWaitableTimer function. The state of an active timer is signaled when it reaches its due time. Deactivate the timer by calling the CancelWaitableTimer function.
You have to be careful when using the wait functions and DDE. If a thread creates any windows, it must process messages. DDE sends messages to all windows in the system. If you have a thread that uses a wait function with no time-out interval, the system will deadlock. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects or MsgWaitForMultipleObjectsEx, rather than SignalObjectAndWait.

See Also

CancelWaitableTimer, CreateEvent, CreateMutex, CreateProcess, CreateThread, CreateRemoteThread, CreateSemaphore, CreateWaitableTimer, FindFirstChangeNotification, MsgWaitForMultipleObjects, MsgWaitForMultipleObjectsEx, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, OpenWaitableTimer, PulseEvent, ReadFileEx, ResetEvent, SetEvent, SetWaitableTimer, WriteFileEx


SizeofResource

The SizeofResource function returns the size, in bytes, of the specified resource.

DWORD SizeofResource(

HMODULE hModule,	// resource-module handle
HRSRC hResInfo	// resource handle
);
Parameters

hModule

Identifies the module whose executable file contains the resource.

hResInfo

Identifies the resource. This handle must be created by using the FindResource or FindResourceEx function.

Return Values

If the function succeeds, the return value is the number of bytes in the resource.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The value returned may be larger than the actual resource because of alignment. An application should not rely upon this value for the exact size of a resource.

See Also

FindResource, FindResourceEx, LoadResource, LockResource


Sleep

The Sleep function suspends the execution of the current thread for a specified interval.

VOID Sleep(

DWORD dwMilliseconds	// sleep time in milliseconds
);
Parameters

dwMilliseconds

Specifies the time, in milliseconds, for which to suspend execution. A value of zero causes the thread to relinquish the remainder of its time slice to any other thread of equal priority that is ready to run. If there are no other threads of equal priority ready to run, the function returns immediately, and the thread continues execution. A value of INFINITE causes an infinite delay.

Return Values

This function does not return a value.

Remarks

A thread can relinquish the remainder of its time slice by calling this function with a sleep time of zero milliseconds.

You have to be careful when using Sleep and DDE. If a thread creates any windows, it must process messages. DDE sends messages to all windows in the system. If you have a thread that uses a wait function with no time-out interval, the system will deadlock. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects or MsgWaitForMultipleObjectsEx, rather than Sleep.

See Also

MsgWaitForMultipleObjects, MsgWaitForMultipleObjectsEx, SleepEx


SleepEx

The SleepEx function causes the current thread to enter a wait state until one of the following occurs:

•	An I/O completion callback function is called

•	An asynchronous procedure call (APC) is queued to the thread.

•	The time-out interval elapses

DWORD SleepEx(

DWORD dwMilliseconds,	// time-out interval in milliseconds
BOOL bAlertable	// early completion flag
);
Parameters

dwMilliseconds

Specifies the time, in milliseconds, that the delay is to occur. A value of zero causes the function to return immediately. A value of INFINITE causes an infinite delay.

bAlertable

Specifies whether the function may terminate early due to an I/O completion callback function or an APC. If bAlertable is FALSE, the function does not return until the time-out period has elapsed. If an I/O completion callback occurs, the function does not return and the I/O completion function is not executed. If an APC is queued to the thread, the function does not return and the APC function is not executed.

If bAlertable is TRUE and the thread that called this function is the same thread that called the extended I/O function (ReadFileEx or WriteFileEx), the function returns when either the time-out period has elapsed or when an I/O completion callback function occurs. If an I/O completion callback occurs, the I/O completion function is called. If an APC is queued to the thread (QueueUserAPC), the function returns when either the timer-out period has elapsed or when the APC function is called.

Return Values

The return value is zero if the specified time interval expired.

The return value is WAIT_IO_COMPLETION if the function returned due to one or more I/O completion callback functions. This can happen only if bAlertable is TRUE, and if the thread that called the SleepEx function is the same thread that called the extended I/O function.

Remarks

This function can be used with the ReadFileEx or WriteFileEx functions to suspend a thread until an I/O operation has been completed. These functions specify a completion routine that is to be executed when the I/O operation has been completed. For the completion routine to be executed, the thread that called the I/O function must be in an alertable wait state when the completion callback function occurs. A thread goes into an alertable wait state by calling either SleepEx, MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx, or WaitForMultipleObjectsEx, with the function’s bAlertable parameter set to TRUE.

A thread can relinquish the remainder of its time slice by calling this function with a sleep time of zero milliseconds.

You have to be careful when using SleepEx and DDE. If a thread creates any windows, it must process messages. DDE sends messages to all windows in the system. If you have a thread that uses a wait function with no time-out interval, the system will deadlock. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects or MsgWaitForMultipleObjectsEx, rather than SleepEx.

See Also

MsgWaitForMultipleObjects, MsgWaitForMultipleObjectsEx, QueueUserAPC, ReadFileEx, Sleep, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFileEx


SnmpExtensionInit

The extensible agent calls the SnmpExtensionInit function in the extension agent DLL to perform bilateral initialization of both the extension and the extensible agents.

BOOL SnmpExtensionInit(

DWORD dwTimeZeroReference,
HANDLE *hPollForTrapEvent,
AsnObjectIdentifier *supportedView
);
Parameters

dwTimeZeroReference

[in] Specifies a time-zero reference for the extension agent.

hPollForTrapEvent

[out] Points to an event handle that will indicate that there are traps available when the extensible agent polls the SnmpExtensionTrap function entry point.

supportedView

[out] Points to an object identifier variable structure that specifies the MIB subtree that the extension agent supports.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The dwTimeZeroReference parameter allows all extension agents to report time information from the same reference point. The extension agent can compute elapsed time by subtracting dwTimeZeroReference from the value returned by the GetCurrentTime function. This time reference is necessary to implement traps and initiate some MIB variables.

An extension agent notifies the extensible agent that it needs to send a trap by setting the state of the hPollForTrapEvent parameter that is passed back during the SnmpExtensionInit entry point to signaled. Once this event has been set to the signaled state, the extensible agent repeatedly calls the extension agent's SnmpExtensionTrap entry point until it returns a value of FALSE. This indicates that the extension agent has no more traps to send. An extension agent application typically creates the hPollForTrapEvent event handle with the CreateEvent function during initialization. It typically sets hPollForTrapEvent to the signaled state with the SetEvent function.

If the extension agent does not generate traps, the hPollForTrapEvent parameter should return a value of NULL.

See Also

SnmpExtensionTrap, GetCurrentTime, CreateEvent, SetEvent


SnmpExtensionInitEx

The SnmpExtensionInitEx function identifies any additional management information base (MIB) subtrees the extension agent supports. The extensible agent calls the SnmpExtensionInitEx function in the extension agent DLL during the extensible agent’s service startup.

BOOL SnmpExtensionInitEx(

AsnObjectIdentifier *supportedView	// pointer to next MIB subtree
);
Parameters

supportedView

[out] Pointer to an AsnObjectIdentifier structure that specifies the next MIB subtree that the extension agent supports.

Return Values

If the supportedView 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 extensible agent repeatedly calls the SnmpExtensionInitEx function entry point so extension agents can register support for additional MIB subtrees. The extension agent must keep track of which MIB subtrees have already been registered.

See Also

SnmpExtensionInit, AsnObjectIdentifier


SnmpExtensionQuery

The extensible agent calls the SnmpExtensionQuery function in the extension agent DLL to resolve SNMP requests that contain variables within one or more of the extension agent’s registered MIB subtrees.

BOOL  SnmpExtensionQuery(

BYTE requestType,
RFC1157VarBindList *variableBindings,
AsnInteger *errorStatus,
AsnInteger *errorIndex
);
Parameters

requestType

[in] Specifies the SNMP request type. This parameter can be one of the following values:

Value	Meaning
ASN_RFC1157_GETREQUEST	Search and receive a value from a specified variable.
ASN_RFC1157_GETNEXTREQUEST	Search and receive a value from a variable without knowing the name of the variable.
ASN_RFC1157_SETREQUEST	Store a value within a specific variable.
variableBindings

[in/out] Points to the variable bindings list.

errorStatus

[out] Points to a variable in which the error status result will be returned. This parameter can be one of the following values:

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] Points 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 extensible agent must resolve a Get, Get Next, or Set command within the subtree indicated by the SnmpExtensionInit function, it must call the SnmpExtensionQuery function. For Get or Set commands, the extension agent must follow the rules in RFC 1157 to either resolve the variable bindings request or generate an error.

A Get Next command is more complicated to process because the extension agent may not be able to resolve the requested variable binding. If the variable binding can be resolved, the extension agent must follow the rules in RFC 1157 to either resolve the variable bindings request or generate an error. If the extension agent cannot resolve the variable binding, it must change the name field of the RFC1157VarBind structure to the value following the MIB subtree value specified in the supportedView parameter of the SnmpExtensionInit function. For example, if the agent supports view ".1.3.6.1.4.1.77.1", a Get Next command 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 extensible agent to continue the attempt to resolve the variable bindings with other extension agents.

It is important to note that the extensible agent and the extension agent may need to exchange dynamically allocated memory during a call to the SnmpExtensionQuery function. The extensible agent dynamically allocates the object identifier in each RFC1157VarBind 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 extensible agent needs to release this memory after the object is placed in the response.

In order to avoid heap corruption and memory leaks, both the extensible agent and the extension agent must use memory allocation routines that resolve to the same heap. Extension agents should use the SnmpUtilMemAlloc function to allocate memory and the SnmpUtilMemFree function to release memory. These functions are located in the utility dynamic-link library SNMPAPI.DLL.

See Also

RFC1157VarBind, SnmpExtensionInit, SnmpUtilMemAlloc, SnmpUtilMemFree


SnmpExtensionTrap

The extensible agent calls the SnmpExtensionTrap function in the extension agent DLL to retrieve traps generated by the extension agent.

BOOL SnmpExtensionTrap(

AsnObjectIdentifier *enterprise,	// Generating enterprise
AsnInteger *genericTrap,	// Generating trap type
AsnInteger *specificTrap,	// Enterprise specific type
AsnTimeticks *timeStamp,	// Time stamp
RFC1157VarBindList *variableBindings	// Variable bindings
);
Parameters

enterprise

[out] Points to an object identifier that indicates the originating object generating the trap. The extensible agent does not free the memory for this variable.

genericTrap

[out] Points to 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 specific-trap parameter.
specificTrap

[out] Points to an indication of the specific trap generated.

timeStamp

[out] Points to a variable to receive the time stamp.

variableBindings

[out] Points to the variable bindings list. The memory for the list will be allocated by the extension agent. The extensible agent will free the memory with a call to the SnmpUtilVarBindListFree function.

Return Values

If the SnmpExtensionTrap function returns a trap in its parameters, the return value is TRUE. Otherwise, the extensible agent repeatedly calls the function until it returns a value of FALSE.

Remarks

The extensible agent repeatedly calls the SnmpExtensionTrap function once the hPollForTrapEvent event handle of the SnmpExtensionInit function has been set to the signaled state. Each successful call returns data from a single trap. It returns FALSE to indicate that its parameters do not represent valid trap data and to stop the extensible agent’s repeated calls.

The extension agent must not free the memory for the variableBindings parameter. The extensible agent automatically performs this action. Use the SnmpUtilMemAlloc function to allocate memory for each RFC1157VarBind structure.

It is important to note that earlier documentation stated that the extension agent should dynamically allocate memory for the enterprise object identifier because the extensible agent would attempt to release the memory after sending a trap. The extensible agent will not release the memory associated with the enterprise object identifier. The recommendation is that you return a pointer to a static AsnObjectIdentifier structure instead.

See Also

SetEvent, SnmpUtilMemAlloc, SnmpUtilVarBindListFree, RFC1157VarBindList, SnmpExtensionInit


SnmpMgrClose

The SnmpMgrClose function closes communications sockets and data structures associated with the specified session.

BOOL SnmpMgrClose(

LPSNMP_MGR_SESSION session	// SNMP session pointer
);
Parameters

session

[in] Points to an internal structure that specifies the session to close.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. This function may return Windows Sockets Error codes.

See Also

SnmpMgrOpen, SnmpMgrRequest


SnmpMgrGetTrap

The SnmpMgrGetTrap function returns outstanding trap data that the caller has not received if trap reception is enabled.

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
RFC1157VarBindList *variableBindings	// variable bindings
);
Parameters

enterprise

[out] Points to an object identifier that specifies the enterprise that generated the SNMP trap.

IPAddress

[out] Points to the IP address of the enterprise that generated the SNMP trap.

genericTrap

[out] Points to 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] Points to an indication of the specific trap generated.

timeStamp

[out] Points to a variable to receive the time stamp.

variableBindings

[out] Points to the variable bindings list.

Return Values

If the function returns a trap, the return value is TRUE.

You should call the SnmpMgrGetTrap function repeatedly until GetLastError returns a value of FALSE. 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

You must allocate memory for the list member of the RFC1157VarBindList structure with the SnmpUtilMemAlloc function but you do not need to free it.

Once an operating system completes a task, it sends a trap signal. An internal SNMP signal checks for the trap signal to notify the SNMP manager of the completed task. The event that the phTrapAvailable parameter of the SnmpMgrTrapListen function points to allows event-driven acquisition of SNMP traps. You can ignore the trap and poll the SnmpMgrGetTrap function for traps at regular intervals instead.

Another method to acquire traps is to create a thread to wait on the event using the WaitForSingleObject function. When the event occurs, the thread should clear the event using the ResetEvent function. Then the thread should repeatedly call SnmpMgrGetTrap until it returns a value of FALSE.

Always call the SnmpMgrTrapListen function before calling SnmpMgrGetTrap to receive traps. If an SNMP manager application calls SnmpMgrGetTrap first to receive traps, it returns a value of FALSE, even if there are traps available. If the application calls GetLastError before calling SnmpMgrTrapListen, GetLastError returns the error code SNMP_MGMTAPI_TRAP_ERRORS.

See Also

SnmpMgrTrapListen, SnmpUtilMemAlloc, WaitForSingleObject, RFC1157VarBindList, ResetEvent


SnmpMgrOidToStr

The SnmpMgrStrToOid function converts an internal object identifier to a string object identifier or object descriptor representation.

BOOL SnmpMgrOidToStr(

AsnObjectIdentifier *oid,	// object identifier to convert
LPSTR *string	// string object identifier representation
);
Parameters

oid

[in] Points to an object identifier variable to be converted.

string

[out] Points to a null-terminated string that will receive the converted value.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. This function may return Windows Sockets error codes.

Remarks

This function looks for the file MIB.BIN. If it does not find the file, it generates an error.

See Also

SnmpMgrStrToOid


SnmpMgrOpen

The SnmpMgrOpen function initializes communications sockets and data structures, allowing communications with the specified agent.

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

See Also

SnmpMgrClose, SnmpMgrRequest


SnmpMgrRequest

The SnmpMgrRequest function requests the specified operation be performed with the specified agent.

SNMPAPI SnmpMgrRequest(

LPSNMP_MGR_SESSION session,	// SNMP session pointer
BYTE requestType,	// Get, GetNext, or Set
RFC1157VarBindList *variableBindings,	// variable bindings
AsnInteger *errorStatus,	// result error status
AsnInteger *errorIndex	// result error index
);
Parameters

session

[in] Points 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:

Value	Meaning
ASN_RFC1157_GETREQUEST	Search and receive a value from a specified variable.
ASN_RFC1157_GETNEXTREQUEST	Search and receive a value from a variable without knowing the name of the variable.
ASN_RFC1157_SETREQUEST	Store a value within a specific variable.
variableBindings

[in/out] Points to the variable bindings list.

errorStatus

[out] Points to a variable in which the error status result will be returned. This parameter can be one of the following values:

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

For more information, see RFC 1157.

See Also

SnmpMgrOpen, SnmpMgrClose


SnmpMgrStrToOid

The SnmpMgrStrToOid function converts a string object identifier or object descriptor representation to an internal object identifier.

BOOL SnmpMgrStrToOid(

LPSTR string,	// string object identifier to be converted
AsnObjectIdentifier *oid	// object identifier internal representation
);
Parameters

string

[in] Points to a null-terminated string to be converted.

oid

[out] Points to an object identifier variable that will receive the converted value.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. This function does not return Windows Sockets error codes.

Remarks

The SnmpMgrStrToOid function looks for the file MIB.BIN. If the function does not find the file, it generates an error.

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.

See Also

SnmpMgrOidToStr


SnmpMgrTrapListen

The SnmpMgrTrapListen function registers the ability of a manager application to receive SNMP traps.

BOOL SnmpMgrTrapListen(

HANDLE *phTrapAvailable	// event handle indicating trap(s) available
);
Parameters

phTrapAvailable

[out] Points to an event handle that will be used to indicate that there are traps available, and that the application should call the SnmpMgrGetTrap function.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. 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 4.0 only if the SNMP Trap Service has been started. See Turning SNMP On and Off for additional information.

The event that the phTrapAvailable parameter points to allows event-driven acquisition of SNMP traps. If you call the SnmpMgrTrapListen function first, you can ignore the event handle and poll the SnmpMgrGetTrap function for traps at regular intervals instead.

Another method to acquire traps is to create a thread to wait on the event using the WaitForSingleObject function. When the call initiates an event, the thread should clear the event using the ResetEvent function. Then the thread should repeatedly call the SnmpMgrGetTrap function until it returns a value of FALSE.

Always call the SnmpMgrTrapListen function before calling SnmpMgrGetTrap to receive traps. If an SNMP manager application calls SnmpMgrGetTrap first to receive traps, it returns a value of FALSE, even if there are traps available. If the application calls GetLastError before calling SnmpMgrTrapListen, GetLastError returns the error code SNMP_MGMTAPI_TRAP_ERRORS.

See Also

SnmpMgrGetTrap, WaitForSingleObject, ResetEvent


SnmpUtilMemAlloc

The SnmpUtilMemAlloc function allocates dynamic memory from the process heap.

LPVOID SnmpUtilMemAlloc(

UINT Size	// bytes to allocate
);
Parameters

Size

[in] 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.

See Also

SnmpUtilMemFree, SnmpUtilMemReAlloc


SnmpUtilMemFree

The SnmpUtilMemFree function frees the specified memory object.

VOID SnmpUtilMemFree(

LPVOID Addr	// pointer to memory object
);
Parameters

Addr

[in/out] Pointer to the memory object to be released.

Return Values

None.

Remarks

Use the SnmpUtilMemAlloc function to allocate memory.

See Also

SnmpUtilMemAlloc, SnmpUtilMemReAlloc


SnmpUtilMemReAlloc

The SnmpUtilMemReAlloc function changes the size of the specified memory object.

LPVOID SnmpUtilMemReAlloc(

LPVOID Addr,	// pointer to memory object
UINT Size	// bytes to allocate
);
Parameters

Addr

[in] Pointer to the memory object to be resized.

Size

[in] 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

Use the SnmpUtilMemFree function to release memory that the SnmpUtilMemReAlloc function allocates.

See Also

SnmpUtilMemAlloc, SnmpUtilMemFree


SnmpUtilOidAppend

The SnmpUtilOidAppend function appends the source object identifier to the destination object identifier.

SNMPAPI SnmpUtilOidAppend(

AsnObjectIdentifier *DestObjId,	// destination object identifier
AsnObjectIdentifier *SrcObjId	// source object identifier
);
Parameters

DestObjId

[in/out] Points to an AsnObjectIdentifier structure to receive the copy.

SrcObjId

[in] Points to an AsnObjectIdentifier structure to append.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. 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.

Use the SnmpUtilOidFree function to free memory that the SnmpUtilOidAppend function allocates for the destination.

See Also

SnmpUtilMemReAlloc, SnmpUtilOidFree


SnmpUtilOidCmp

The SnmpUtilOidCmp function compares two object identifiers.

SNMPAPI SnmpUtilOidCmp(

AsnObjectIdentifier *ObjIdA,	// first object identifier
AsnObjectIdentifier *ObjIdB	// second object identifier
);
Parameters

ObjIdA

[in] Points to an AsnObjectIdentifier structure to compare.

ObjIdB

[in] Points to an AsnObjectIdentifier structure to compare.

Return Values

The function returns a value greater than zero if ObjIdA is greater than ObjIdB, zero if ObjIdA equals ObjIdB, and less than zero if ObjIdA is less than ObjIdB.

Remarks

The SnmpUtilOidCmp function calls the SnmpUtilOidNCmp function.

See Also

SnmpUtilOidNCmp


SnmpUtilOidCpy

The SnmpUtilOidCpy function copies the variable pointed to by the SrcObjId parameter to the DestObjId  parameter, allocating any necessary memory for the destination’s copy.

SNMPAPI SnmpUtilOidCpy(

AsnObjectIdentifier *DestObjId,	// destination object identifier
AsnObjectIdentifier *SrcObjId	// source object identifier
);
Parameters

DestObjId

[out] Points to an AsnObjectIdentifier structure to receive the copy.

SrcObjId

[in] Points to an AsnObjectIdentifier structure to copy.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The application can free memory that the SnmpUtilOidCpy function allocates for the destination with the SnmpUtilOidFree function.

See Also

SnmpUtilOidFree


SnmpUtilOidFree

The SnmpUtilOidFree function frees any allocated data associated with the object identifier.

VOID SnmpUtilOidFree(

AsnObjectIdentifier *Obj	// object identifier to free
);
Parameters

Obj

[in/out] Points to an AsnObjectIdentifier structure whose allocated data should be freed.

Return Values

No return value.

See Also

SnmpUtilOidAppend


SnmpUtilOidNCmp

The SnmpUtilOidNCmp function compares two object identifier variables up to the length specified by the Len parameter.

SNMPAPI SnmpUtilOidNCmp(

AsnObjectIdentifier *ObjIdA,	// first object identifier
AsnObjectIdentifier *ObjIdB,	// second object identifier
UINT Len	// maximum length to compare
);
Parameters

ObjIdA

[in] Points to an AsnObjectIdentifier structure to compare.

ObjIdB

[in] Points to an AsnObjectIdentifier structure to compare.

Len

[in] Indicates the number of subidentifiers to compare.

Return Values

The function returns a value greater than zero if ObjIdA is greater than ObjIdB, zero if ObjIdA equals ObjIdB, and less than zero if ObjIdA is less than ObjIdB.

See Also

SnmpUtilOidCmp


SnmpUtilPrintAsnAny

The SnmpUtilPrintAsnAny function prints the value of the Any parameter to the standard output.

VOID SnmpUtilPrintAsnAny(

AsnAny *Any
);
Parameters

Any

[in] Points to an AsnAny structure for a value to print.

Return Values

No return value.

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.

See Also

AsnAny


SnmpUtilVarBindCpy

The SnmpUtilVarBindCpy function copies the RFC1157VarBind structure, and allocates any memory necessary for the destination structure.

SNMPAPI SnmpUtilVarBindCpy(

RFC1157VarBind *dst,	// destination variable bindings
RFC1157VarBind *src	// source variable bindings
);
Parameters

dst

[out] Points to an RFC1157VarBind structure to receive the copy.

src

[in] Points to an RFC1157VarBind structure to copy.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Use the SnmpUtilVarBindFree function to free memory that the SnmpUtilVarBindCpy function allocates for the destination.

See Also

RFC1157VarBind, SnmpUtilVarBindFree


SnmpUtilVarBindListCpy

The SnmpUtilVarBindListCpy function copies the RFC1157VarBindList structure, and allocates any necessary memory for the destination's copy.

SNMPAPI SnmpUtilVarBindListCpy(

RFC1157VarBindList *dst,	// destination variable bindings list
RFC1157VarBindList *src	// source variable bindings list
);
Parameters

dst

[out] Points to an RFC1157VarBindList structure to receive the copy.

src

[in] Points to an RFC1157VarBindList structure to copy.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Use the SnmpUtilVarBindListFree function to free memory that the SnmpUtilVarBindListCpy function allocates for the destination.

See Also

RFC1157VarBindList, SnmpUtilVarBindListFree, SnmpUtilOidCpy


SnmpUtilVarBindFree

The SnmpUtilVarBindFree function frees any allocated data associated with an RFC1157VarBind structure.

VOID SnmpUtilVarBindFree(

RFC1157VarBind *VarBind	// variable binding to free
);
Parameters

VarBind

[in/out] Points to an RFC1157VarBind structure whose allocated data should be freed.

Return Values

No return value.

See Also

RFC1157VarBind, SnmpUtilVarBindListFree


SnmpUtilVarBindListFree

The SnmpUtilVarBindListFree function frees any allocated data associated with an RFC1157VarBindList structure.

VOID SnmpUtilVarBindListFree(

RFC1157VarBindList *VarBindList	// variable bindings list to free
);
Parameters

VarBindList

[in/out] Points to an RFC1157VarBindList structure whose allocated data should be freed.

Return Values

No return value.

See Also

RFC1157VarBindList, SnmpUtilVarBindFree


SOBailOut

Allows the file parser to return an error condition.

The parser should return from the VwReadStreamFunc function as soon as possible after this function is called.

VOID SOBailOut(

WORD wError,
HPROC reserved
);
Parameters

wError

Error flag. This parameter can be one of these values:

SOERROR_BADFILE	Invalid file format
SOERROR_EOF	Unexpected end of file (EOF)
SOERROR_GENERAL	Unspecified error
reserved

Reserved; do not use.

Return Values

None.


SOBeginTable

Starts a table definition, indicating that the text in subsequent output calls is part of a table.

This function must be called between paragraphs and before row and cell formats are specified.

VOID SOBeginTable(

HPROC reserved
);
Parameters

reserved

Reserved; do not use.

Return Values

None.


SOEndColumnInfo

Ends the definition of column information.

The file parser must call this function immediately after setting the column information. This function can only be called from the VwStreamSection function.

VOID SOEndColumnInfo(

HPROC reserved
);
Parameters

reserved

Reserved; do not use.

Return Values

None.


SOEndFieldInfo

Ends the definition of field information.

The file parser must have previously called the SOStartFieldInfo function.

The file parser calls this function immediately after setting the field information. This function can only be called from the VwStreamSection function.

VOID SOEndFieldInfo(

HPROC reserved
);
Parameters

reserved

Reserved; do not use.

Return Values

None.


SOEndFontTable

Ends the definition of a font table.

The file parser must call this function immediately after setting font entries. This function can only be called from the VwStreamSection function.

VOID SOEndFontTable(

HPROC reserved
);
Parameters

reserved

Reserved; do not use.

Return Values

None.


SOEndPalette

Ends the definition of a color palette.

The file parser calls this function immediately after specifying the last palette entry.

VOID SOEndPalette(

HPROC reserved
);
Parameters

reserved

Reserved; do not use.

Return Values

None.


SOEndTable

Ends a table definition, indicating that the text in subsequent output calls is no longer part of a table.

The function must be called after a row break.

VOID SOEndTable(

HPROC reserved
);
Parameters

reserved

Reserved; do not use.

Return Values

None.


SOEndTabStops

Ends the definition of tabs stops for a paragraph.

To set tab stops, use the SOPutTabStop function.

The file parser calls this function immediately after setting the last tab stop for the paragraph.

VOID SOEndTabStops(

HPROC reserved
);
Parameters

reserved

Reserved; do not use.

Return Values

None.


SOGetInfo

Retrieves information about a spreadsheet.

VOID SOGetInfo(

WORD wInfo,
void VWPTR *pInfo,
HPROC reserved
);
Parameters

wInfo

Information type. If this parameter is the SOINFO_COLUMNRANGE value, the function retrieves the range of columns for a spreadsheet to read.

pInfo

Address of a 32-bit variable that receives the first column number in the low-order word and the second column number in the high-order word.

reserved

Reserved; do not use.

Return Values

None.


SOGetScanLineBuffer

Retrieves the address of the buffer for storing the current scan line.

This function is called from the VwStreamReadFunc function for each scan line produced.

This function sets the variable pointed to by ppScanLineData to the address where the scan line data should be built.

WORD SOGetScanLineBuffer(

VOID VWPTR *ppScanLineData,
HPROC reserved
);
Parameters

ppScanLineData

Address of the variable that receives the address of the scan line data buffer.

reserved

Reserved; do not use.

Return Values

Returns the size, in bytes, of the scan line data buffer. The size is the maximum number of bytes that may be accessed using the returned address and is guaranteed to be sufficient to hold a scan line as wide as the entire tile.


SOPutBitmapHeader

Outputs information about a bitmap.

VOID SOPutBitmapHeader(

PSOBITMAPHEADER pBitmapHeader,
HPROC reserved
);
Parameters

pBitmapHeader

Address of the SOBITMAPHEADER structure that contains the bitmap header information.

reserved

Reserved; do not use.

Return Values

None.


SOPutBreak

Sets a paragraph, cell, record, page, section, or other type of break.

In spreadsheet sections, the last cell in a section must have an associated SO_CELLBREAK break before the SO_SECTIONBREAK or SO_EOFBREAK break.

In database sections, the last record in a section must have an associated SO_RECORDBREAK break before the SO_SECTIONBREAK or SO_EOFBREAK break.

In word processing sections, the last paragraph does not need an SO_PARABREAK break before the SO_SECTIONBREAK or SO_EOFBREAK break.

WORD SOPutBreak(

WORD wType,
DWORD dwInfo,
HPROC reserved
);
Parameters

wType

Type of break. This parameter can one of these values:

SO_CELLBREAK	Regular cell break
SO_EOFBREAK	End of file (EOF) break, which implies a section break
SO_PARABREAK	Regular paragraph break
SO_RECORDBREAK	Regular record break
SO_SECTIONBREAK	Section break
SO_SUBDOCBEGINBREAK	Subdocument’s begin break
SO_SUBDOCENDBREAK	Subdocument’s end break
dwInfo

Data to save for each record. This data is for database section breaks. For all other section types, this parameter should be zero.

dwInfo is saved after every SOPutBreak function and, like the regular save information, should represent the next record, not the one just read.

reserved

Reserved; do not use.

Return Values

Returns the SO_STOP value to direct the file parser to stop processing and return or the SO_CONTINUE value to direct the file parser to continue processing.


SOPutChar

Outputs a character, applying the current font, height, and attributes.

The character is assumed to belong to the character set selected by the open function and is countable and visible.

VOID SOPutChar(

WORD wCh,
HPROC reserved
);
Parameters

wCh

Character value. This parameter must be within the range specified by the current character set.

reserved

Reserved; do not use.

Return Values

None.


SOPutCharAttr

Sets the style attributes for characters in text.

VOID SOPutCharAttr(

WORD wAttr,
WORD wState,
HPROC reserved
);
Parameters

wAttr

Style attribute type. This parameter can be one of these values:

SO_BOLD	Bold
SO_CAPS	All capital letters
SO_DOTUNDERLINE	Dotted underline
SO_DUNDERLINE	Double underline
SO_ITALIC	Italic
SO_OUTLINE	Outlined rather than solid
SO_SHADOW	Shadow slightly beneath and behind
SO_SMALLCAPS	Small capital letters
SO_STRIKEOUT	Strikeout
SO_SUBSCRIPT	Subscript
SO_SUPERSCRIPT	Superscript
SO_UNDERLINE	Single underline
SO_WORDUNDERLINE	Underline
wState

Style attribute state. This parameter can be the SO_ON or SO_OFF value.

reserved

Reserved; do not use.

Return Values

None.


SOPutCharFontById

Sets the font for characters in text.

VOID SOPutCharFontById(

DWORD dwFontId,
HPROC reserved
);
Parameters

dwFontId

Font identifier, relative to the previously given font table.

reserved

Reserved; do not use.

Return Values

None.


SOPutCharFontByName

Sets the font for characters in text.

VOID SOPutCharFontByName(

WORD wFontType,
WORD pFontName,
HPROC reserved
);
Parameters

wFontType

Font family. This parameter can be one of these values:

SO_FAMILYDECORATIVE	Fancy display font
SO_FAMILYMODERN	Fixed width
SO_FAMILYROMAN	Variable width with serifs
SO_FAMILYSCRIPT	Handwriting
SO_FAMILYSWISS	Variable width without serifs
SO_FAMILYSYMBOL	Symbol font
SO_FAMILYUNKNOWN	Not known
pFontName

Address of a null-terminated string specifying the name of the font.

reserved

Reserved; do not use.

Return Values

None.


SOPutCharHeight

Sets the height, in half points, of a character in text.

VOID SOPutCharHeight(

WORD wHeight,
HPROC reserved
);
Parameters

wHeight

Height, in half points, of the character.

reserved

Reserved; do not use.

Return Values

None.


SOPutCharX

Outputs a character, applying the specified character type.

The character is assumed to belong to the character set selected by the open function.

VOID SOPutCharX(

WORD wCh,
WORD wType,
HPROC reserved
);
Parameters

wCh

Character value. This parameter must be within the range specified by the current character set.

wType

Type flag. This parameter can be one or more of these values:

SO_COUNT	The character is countable and may be deleted. Characters without this value are for display purposes and do not enter into character count calculations for write back.
SO_HIDDEN	The character is not visible on the display.
SO_LIMITEDIT	Consecutive characters of this type will be deleted as a group. No write back command will begin on one of these characters, but it may encompass a group of these characters.
reserved

Reserved; do not use.

Return Values

None.


SOPutColumnInfo

Sets column information.

The file parser must call the SOStartColumnInfo function before calling this function.

This function can only be called from the VwStreamSection function.

VOID SOPutColumnInfo(

PSOCOLUMN pColumn,
HPROC reserved
);
Parameters

pColumn

Address of the SOCOLUMN structure containing the column information.

reserved

Reserved; do not use.

Return Values

None.


SOPutDataCell

Outputs data for a cell.

VOID SOPutCell(

PSODATACELL pCell,
HPROC reserved
);
Parameters

pCell

Address of a SODATACELL structure.

reserved

Reserved; do not use.

Return Values

None.


SOPutEmbeddedObject

Sets an embedded graphics object.

The file parser must set the SOEMBEDDEDOBJECT structure with the appropriate values.

VOID SOPutEmbeddedObject(

PSOEMBEDDEDOBJECT pObject,
HPROC reserved
);
Parameters

pObject

Address of the SOEMBEDDEDOBJECT structure that contains information about the object to be embedded.

reserved

Reserved; do not use.

Return Values

None.


SOPutField

Outputs data for a field.

This function is used for all wStorage types except the SO_FIELDTEXTVAR value.

VOID SOPutField(

void VWPTR *pData,
HPROC reserved
);
Parameters

pData

Address of the data for the field.

reserved

Reserved; do not use.

Return Values

None.


SOPutFieldInfo

Sets field information.

The file parser must call the SOStartFieldInfo function before calling this function.

This function can only be called from the VwStreamSection function.

VOID SOPutFieldInfo(

PSOFIELD pField,
HPROC reserved
);
Parameters

pField

Address of the SOFIELD structure containing the field information.

reserved

Reserved; do not use.

Return Values

None.


SOPutFontTableEntry

Sets a font table entry.

The file parser must call the SOStartFontTable function before calling this function. SOPutFontTableEntry must be called once for each font to be added to the table. Font identifiers must be unique, but they can be given in any order.

This function can only be called from the VwStreamSection function.

VOID SOPutFontTableEntry(

DWORD dwFontId,
WORD wFontType,
Char VWPTR *pFontName,
HPROC reserved
);
Parameters

dwFontId

Font identifier. This parameter can be any number, but it must be unique within the font table.

wFontType

Font family. This parameter can be one of these values:

SO_FAMILYDECORATIVE	Fancy display font
SO_FAMILYMODERN	Fixed width
SO_FAMILYROMAN	Variable width with serifs
SO_FAMILYSCRIPT	Handwriting
SO_FAMILYSWISS	Variable width without serifs
SO_FAMILYSYMBOL	Symbol font
SO_FAMILYUNKNOWN	Not known
pFontName

Address of a null-terminated string specifying the name of the font.

reserved

Reserved; do not use.

Return Values

None.


SOPutHdrEntry

Sets strings for the header information.

This function can only be called from the VwStreamSection function.

VOID SOPutHdrEntry(

char VWPTR *pLabel,
char VWPTR *pData,
WORD wId,
HPROC reserved
);
Parameters

pLabel

Label that the display engine should use when presenting this value.

pData

Value to display.

wId

Identifier for this item that the display engine and filter agree upon.

reserved

Reserved; do not use.

Return Values

None.


SOPutMoreText

Outputs the text for a cell and indicates whether there is more text to be output for the cell.

This function is used to output a sequence of text initially started by using the SOPutText function.

If there is more text to output, the file parser must use a subsequent call or calls to the SOPutMoreText function to output the text. The 128 byte limit is for the convenience of the function processing SOPutMoreText.

VOID SOPutMoreText(

WORD wCount,
char VWPTR *pText,
WORD bMore,
HPROC reserved
);
Parameters

wCount

Number of characters pointed to by pText. The number must not exceed 128 bytes.

pText

Address of the string of text characters to output.

bMore

More data flag. This parameter can be the SO_YES value to indicate more text to be output or the SO_NO value to indicate none.

reserved

Reserved; do not use.

Return Values

None.


SOPutMoreVarField

Outputs data for a variable field and indicates whether there is more data to be output for the field.

This function can be called any number of times.

If there is more data to output, the file parser must use a subsequent call or calls to SOPutMoreVarField to output the data. The 128 byte limit is for the convenience of the function processing SOPutMoreVarField.

This function is used to output a sequence of data initially started using the SOPutVarField function.

VOID SOPutMoreVarField(

VOID VWPTR *pData,
WORD wCount,
WORD bMore,
HPROC reserved
);
Parameters

pData

Address of the data for the field.

wCount

Number of bytes pointed to by pData. The number must not exceed 128 bytes.

bMore

More data flag. This parameter can be the SO_YES value to indicate more data to be output or the SO_NO value to indicate none.

reserved

Reserved; do not use.

Return Values

None.


SOPutPaletteEntry

Sets the colors for a palette entry.

The file parser must call the SOStartPalette function before calling this function.

The order of calls to this function determines the order of entries in the color table for an image. The first palette entry is color 0, the color displayed for pixels with a value of 0; the second palette entry is color 1; and so on.

VOID SOPutPaletteEntry(

unsigned char Red,
unsigned char Green,
unsigned char Blue,
HPROC reserved
);
Parameters

Red

Relative red intensity in the range 0 to 255.

Green

Relative green intensity in the range 0 to 255.

Blue

Relative blue intensity in the range 0 to 255.

reserved

Reserved; do not use.

Return Values

None.


SOPutParaAlign

Sets the alignment for a paragraph.

VOID SOPutParAlign(

WORD wType,
HPROC reserved
);
Parameters

wType

Type of alignment. This parameter can be the SO_ALIGNLEFT, SO_ALIGNRIGHT, SO_ALIGNCENTER, or SO_ALIGNJUSTIFY value.

reserved

Reserved; do not use.

Return Values

None.


SOPutParaIndents

Sets indents for a paragraph. Indents are relative to the corresponding left or right margin.

VOID SOPutParaIndents(

LONG dwLeft,
LONG dwRight,
LONG dwFirst,
HPROC reserved
);
Parameters

dwLeft

Width, in twips, of the left indent. The indent is measured from the left page margin.

dwRight

Width, in twips, of the right indent. The indent is measured from the right page margin.

dwFirst

Width, in twips, of the left indent for the first line in the paragraph. The indent is measured from the left page margin.

reserved

Reserved; do not use.

Return Values

None.


SOPutParaMargins

Sets paragraph margins. The margins are relative to the left or right edge of the page.

VOID SOPutParaMargins(

LONG dwLeft,
LONG dwRight,
HPROC reserved
);
Parameters

dwLeft

Width, in twips, of the left margin.

dwRight

Width, in twips, of the right margin.

reserved

Reserved; do not use.

Return Values

None.


SOPutParaSpacing

Sets the spacing for a paragraph.

VOID SOPutParaSpacing(

WORD wLineHeightType,
DWORD dwLineHeight,
DWORD dwSpaceBefore,
DWORD dwSpaceAfter,
HPROC reserved
);
Parameters

wLineHeightType

Type of line height. This parameter can be one of these values:

SO_HEIGHTATLEAST	Sets the line height to the height given by dwLineHeight or sets it to fit the tallest character in the line, whichever height is greater.
SO_HEIGHTAUTO	Sets the line height automatically to fit the tallest character in the line.
SO_HEIGHTEXACTLY	Sets the line height to the height given by dwLineHeight.
dwLineHeight

Baseline to baseline height, in twips.

dwSpaceBefore

Space before the paragraph, in twips.

dwSpaceAfter

Space after the paragraph, in twips.

reserved

Reserved; do not use.

Return Values

None.


SOPutScanLineData

Sets the bit values in a single scan line of a bitmap.

The bitmap format must have been previously defined by using the SOPutBitmapHeader function.

VOID SOPutScanLineData(

U_BYTE VWPTR *pScanLineData,
HPROC reserved
);
Parameters

pScanLineData

Address of the bitmap data for the current scan line.

reserved

Reserved; do not use.

Return Values

None.


SOPutSectionName

Sets the name of a section.

VOID SOPutSectionName(

char VWPTR *pName,
HPROC reserved
);
Parameters

pName

Address of a null-terminated string specifying the name of the section.

reserved

Reserved; do not use.

Return Values

None.


SOPutSectionType

Outputs a section type.

VOID SOPutSectionType(

WORD wType,
HPROC reserved
);
Parameters

wType

Section type. This parameter can be one of these values:

SO_BITMAP	Sets the section type to be a bitmap. When generating output for the section, the file parser should use only general and bitmap stream output functions.
SO_CELLS	Sets the section type to be a spreadsheet consisting of cells. When generating output for the section, the file parser should use only the general and spreadsheet stream output functions.
SO_FIELDS	Sets the section type to be a database consisting of fields. When generating output for the section, the file parser should use only the general and database stream output functions.
SO_PARAGRAPHS	Sets the section type to be a word processing document consisting of paragraphs. When generating output for the section, the file parser should use only general and word processing stream output functions.
SO_VECTOR	Sets the section type to be a vector graphics section consisting of graphics objects. When generating output for the section, the file parser should use only the general and vector graphics stream output functions.
reserved

Reserved; do not use.

Return Values

None.


SOPutSpecialCharX

Outputs a special character, applying the specified character type.

VOID SOPutSpecialCharX(

WORD wCh,
WORD wType,
HPROC reserved
);
Parameters

wCh

Character value. This parameter can be one of these values:

SO_CHDATE	Automatic current date
SO_CHHHYPHEN	Nonbreaking hyphen
SO_CHHLINE	Hard line break
SO_CHHPAGE	Hard page break
SO_CHHSPACE	Nonbreaking space
SO_CHPAGENUMBER	Automatic page number
SO_CHSHYPHEN	Hyphen
SO_CHTAB	Tab
SO_CHTIME	Automatic current time
SO_CHUNKNOWN	Default character
wType

Type flag. This parameter can be one or more of these values:

SO_COUNT	The character is countable and may be deleted. Characters without this value are for display purposes and do not enter into character count calculations for write back.
SO_HIDDEN	The character is not visible on the display.
SO_LIMITEDIT	Consecutive characters of this type will be deleted as a group. No write back command will begin on one of these characters, but it may encompass a group of these characters.
reserved

Reserved; do not use.

Return Values

None.


SOPutSubdocInfo

Outputs subdocument data.

VOID SOPutSubdocInfo(

WORD wType,
WORD wSubType,
HPROC reserved
);
Parameters

wType

Type of data. This parameter can be one of these values:

SO_COMMENT	The data is a comment.
SO_FOOTER	The data applies to the document footer.
SO_FOOTNOTE	The data applies to a footnote.
SO_HEADER	The data applies to the document header.
wSubType

Subtype of data. This parameter can be one of these values:

SO_BOTH	The data is for a header or footer on both left and right pages. This value is used with SO_HEADER or SO_FOOTER.
SO_LEFT	The data is for a header or footer on even pages only. This value is used with SO_HEADER or SO_FOOTER.
SO_RIGHT	The data is for a header or footer on odd pages only. This value is used with SO_HEADER or SO_FOOTER.
0 through 65535	The data is a footnote number. This value is used with SO_FOOTNOTE only.
If wType is SO_COMMENT, no subtype is needed.

reserved

Reserved; do not use.

Return Values

None.


SOPutTableCellInfo

Sets cell information.

VOID SOPutTableCellInfo(

PSOTABLECELLINFO pCellInfo,
HPROC reserved
);
Parameters

pCellInfo

Address of a SOTABLECELLINFO structure containing information about the cell.

reserved

Reserved; do not use.

Return Values

None.


SOPutTableRowFormat

Sets the format of a row in a table.

VOID SOPutTableRowFormat(

WORD wLeftEdge,
WORD wRowHeight,
WORD wRowHeightType,
WORD wCellMargin,
WORD wRowAlignment,
WORD wNumCells,
HPROC reserved
);
Parameters

wLeftEdge

Position, in twips, of the left edge of the table, relative to the left margin.

wRowHeight

Row height, in twips.

wRowHeightType

Type of height for the row. This parameter can be one of these values:

SO_HEIGHTATLEAST	Sets the  row height at least as high as that given by wRowHeight.
SO_HEIGHTAUTO	Sets the  row height automatically to fit text in the row.
SO_HEIGHTEXACTLY	Sets the row height exactly as given by wRowHeight.
wCellMargin

White space on either side of text in a cell within the specified cell width. It is equal to half the total white space between adjacent cells.

wRowAlignment

Alignment of row within margins. This parameter can be the SO_ALIGNLEFT, SO_ALIGNRIGHT, or SO_ALIGNCENTER value.

wNumCells

Number of cells in the row.

reserved

Reserved; do not use.

Return Values

None.


SOPutTabStop

Sets a tab stop for the paragraph.

The file parser must call the SOStartTabStops function before calling this function and can set multiple tab stops for a paragraph by calling it multiple times. The file parser must not call any other output function while setting tab stops and must call the SOEndTabStops function after setting the last tab stop.

VOID SOPutTabStop(

PSOTAB pTabs,
HPROC reserved
);
Parameters

pTabs

Address of the SOTAB structure containing the tab stop information.

reserved

Reserved; do not use.

Return Values

None.


SOPutTextCell

Outputs the text for a cell and indicates whether there is more text to be output for the cell.

If there is more text to be output, the file parser must use a subsequent call or calls to the SOPutMoreText function to output the text.

VOID SOPutTextCell(

PSOTEXTCELL pCell,
WORD wCount,
char VWPTR *pText,
HPROC reserved
);
Parameters

pCell

Address of a SOTEXTCELL structure.

wCount

Number of characters pointed to by pText. The number must not exceed 128 bytes.

pText

Address of the string of text characters to be output.

bMore

More data flag. This parameter can be the SO_YES value to indicate more text to be output or the SO_NO value to indicate none.

reserved

Reserved; do not use.

Return Values

None.


SOPutVarField

Outputs data for a variable field and indicates whether there is more data to be output for the field.

If there is more data to be output, the file parser must use a subsequent call or calls to the SOPutMoreVarField function to output the data.

VOID SOPutVarField(

void VWPTR *pData,
WORD wCount,
WORD *bMore,
HPROC reserved
);
Parameters

pData

Address of the data for the variable field.

wCount

Number of bytes pointed to by pData. The number must not exceed 128 bytes.

bMore

More data flag. This parameter can be the SO_YES value to indicate more data to be output or the SO_NO value to indicate none.

reserved

Reserved; do not use.

Return Values

None.


SOPutVectorHeader

Outputs the vector header, specifying the display resolution, x- and y-axis orientation, background color, and color value type (RGB or palette).

VOID SOPutVectorHeader(

PSOVECTORHEADER pVectorHeader,
HPROC reserved
);
Parameters

pVectorHeader

Address of a SOVECTORHEADER structure.

reserved

Reserved; do not use.

Return Values

None.


SOSetDateBase

Sets the base date. All subsequent dates are calculated as the sum of the base date and the given date value.

This function can only be called from the VwStreamSection function.

VOID SOSetDataBase(

DWORD dwBase,
WORD wFlags,
HPROC reserved
);
Parameters

dwBase

Base number of Julian days to be automatically added to dates. All dates are entered in Julian day format in the following manner:

Jan. 1, 4713 B.C.	Julian Day 1
Jan. 1, 1 A.D.	Julian Day 1721424
Jan. 1, 1900	Julian Day 2415021
Jan. 1, 1904	Julian Day 2416481
Formats supporting dates before 1582 are not supported.

wFlags

Action flag. This parameter can be the SO_LOTUSHELL value to correct for the Lotus 1-2-3® 1990 leap year bug.

reserved

Reserved; do not use.

Return Values

None.


SOStartColumnInfo

Starts the definition of column information.

The file parser must call this function immediately before setting the information. This function can only be called from the VwStreamSection function.

VOID SOStartColumnInfo(

HPROC reserved
);
Parameters

reserved

Reserved; do not use.

Return Values

None.


SOStartFieldInfo

Starts the definition of field information.

The file parser calls this function immediately before setting field information. This function can only be called from the VwStreamSection function.

VOID SOStartFieldInfo(

HPROC reserved
);
Parameters

reserved

Reserved; do not use.

Return Values

None.


SOStartFontTable

Starts the definition of a font table.

The file parser must call this function immediately before setting font entries. The function can only be called from the VwStreamSection function.

VOID SOStartFontTable(

HPROC reserved
);
Parameters

reserved

Reserved; do not use.

Return Values

None.


SOStartPalette

Starts the definition of a color palette.

The file parser calls this function immediately before defining palette entries.

VOID SOStartPalette(

HPROC reserved
);
Parameters

reserved

Reserved; do not use.

Return Values

None.


SOStartTabStops

Starts the definition of tab stops for a paragraph.

To set tab stops, use the SOPutTabStop function.

The file parser calls this function immediately before setting the first tab stop for the paragraph.

VOID SOStartTabStops(

HPROC reserved
);
Parameters

reserved

Reserved; do not use.

Return Values

None.


SoundSentryProc

The SoundSentryProc function is a library-defined callback function that produces a customized visual signal when the SoundSentry accessibility feature is on and a Windows-based application (or a non-Windows-based application running in a window) generates a sound through the computer’s built-in speaker.

LRESULT CALLBACK SoundSentryProc(

DWORD dwMillisec,	// duration of visual signal
DWORD fdwEffect	// effect-type flag
);
Parameters

dwMillisec

Specifies the duration, in milliseconds, of the visual signal that is displayed when a Windows-based application (or a non-Windows-based application running in a window) generates a sound.

fdwEffect

Specifies the type of visual signal to display. Currently, this value must always be SSWF_CUSTOM.

Return Values

If the visual signal was or will be displayed correctly, the return value is TRUE. If the signal is asynchronous and the status is not available when the function is called, it should return TRUE.

If an error prevented the signal from being displayed, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The library that contains the SoundSentryProc function must be a 32-bit DLL, and the DLL must export a function with the name “SoundSentryProc.”

The SoundSentryProc function is called only after an application or library calls the SystemParametersInfo function, specifying the SPI_SETSOUNDSENTRY value and the address of a SOUNDSENTRY structure whose iWindowsEffect member is set to SSWF_CUSTOM.

See Also

SOUNDSENTRY, SystemParametersInfo


SOVectorAttr

Sets attributes related to drawing vector graphics objects.

VOID SOVectorAttr(

INT nItemId,
DWORD wDataSize,
VOID VWPTR *pData,
HPROC reserved
);
Parameters

nItemId

Action identifier. This parameter, which specifies the action to carry out and determines the appropriate values for wDataSize and pData, can be one of the vector attribute values in “Constants” later in this topic.

wDataSize

Size, in bytes, of data pointed to by pData.

pData

Address of a buffer containing the information used to carry out the requested action. The meaning and format of the buffer depends on the value of nItemId.

reserved

Reserved; do not use.

Return Values

None.


SOVectorObject

Draws or defines the given vector graphics object.

VOID SOVectorObject(

INT nItemId,
DWORD wDataSize,
VOID VWPTR *pData,
HPROC reserved
);
Parameters

nItemId

Action flag. This parameter, which specifies the action to carry out and determines the appropriate values for wDataSize and pData, can be one of the vector object values in “Constants” later in this topic.

wDataSize

Size, in bytes, of the data pointed to by pData.

pData

Address of a buffer containing the information used to carry out the requested action. The meaning and format of the buffer depends on the value of nItemId.

reserved

Reserved; do not use.

Return Values

None.


SUUserPopData

Pops user data. The data must have been pushed previously by using the SUUserPushData function.

VOID SUUserPopData(

VOID VWPTR *pData,
HPROC reserved
);
Parameters

pData

Address of the VwStreamUserSaveType structure receiving the data.

reserved

Reserved; do not use.

Return Values

None.


SUUserPushData

Pushes user data.

The data can be retrieved by using the SUUserPopData function.

VOID SUUserPushData(

VOID VWPTR *pData,
HPROC reserved
);
Parameters

pData

Address of a VwStreamUserSaveType structure containing the data to be saved.

reserved

Reserved; do not use.

Return Values

None.


SUUserRetrieveData

Retrieves user data.

The data must have been previously saved by using the SUUserSaveData function.

This function should not be used. The SUUserPopData function should be used instead.

VOID SUUserRetrieveData(

WORD wIndex,
VOID VWPTR *pData,
HPROC reserved
);
Parameters

wIndex

Index value specifying the data to retrieve. This value must have been previously returned by the SUUserSaveData function.

pData

Address of the VwStreamUserSaveType structure receiving the data.

reserved

Reserved; do not use.

Return Values

None.


SUUserSaveData

Saves user data.

This function should not be used. The SUUserPushData function should be used instead.

VOID SUUserSaveData(

VOID VWPTR *pData,
HPROC reserved
);
Parameters

pData

Address of a VwStreamUserSaveType structure containing the data to be saved.

reserved

Reserved; do not use.

Return Values

Returns the index used to retrieve the data. Indexes are guaranteed to be zero-based and sequential.


StartDoc

The StartDoc function starts a print job. This function replaces the STARTDOC printer escape.

int StartDoc(

HDC hdc,	// handle of device context
CONST DOCINFO *lpdi	// address of structure with file names
);
Parameters

hdc

Identifies the device context for the print job.

lpdi

Points to a DOCINFO structure containing the name of the document file and the name of the output file.

Return Values

If the function succeeds, the return value is greater than zero. This value is the print job identifier for the document.

If the function fails, the return value is less than or equal to zero. To get extended error information, call GetLastError.

Remarks

Applications should call the StartDoc function immediately before beginning a print job. Using this function ensures that multipage documents are not interspersed with other print jobs.

Applications can use the value returned by StartDoc to retrieve or set the priority of a print job. Call the GetJob or SetJob function and supply this value as one of the required arguments.

See Also

DOCINFO, EndDoc, GetJob, SetJob


StartDocPrinter

The StartDocPrinter function informs the print spooler that a document is to be spooled for printing.

DWORD StartDocPrinter(

HANDLE hPrinter,	// handle of printer object
DWORD Level,	// structure level
LPBYTE pDocInfo	// address of structure
);
Parameters

hPrinter

Identifies the printer.

Level

Specifies the version of the structure to which pDocInfo points. This value must be 1 for Windows NT. For Windows 95, you can also select a value of 2. (See DOC_INFO_2 following.)

pDocInfo

Points to a DOC_INFO_1 structure or a DOC_INFO_2 structure. If dwlevel is 1, the function stores the data in a DOC_INFO_1 structure. If dwlevel is 2, the function stores the data in a DOC_INFO_2 structure.

Windows 95: The DOC_INFO_2 structure has the following form:

typedef struct _DOC_INFO_2 { // dci2

    LPTSTR pDocName;

    LPTSTR pOutputFile;

    LPTSTR pDatatype;

    DWORD dwMode;

    DWORD JobId;

} DOC_INFO_2;

Return Values

If the function succeeds, the return value identifies the print job.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The printer handle identified by the hPrinter parameter is obtained by calling the OpenPrinter function.

The return value will never be greater than 2^31 − 1.

See Also

DOC_INFO_1, OpenPrinter


StartPage

The StartPage function prepares the printer driver to accept data.

int StartPage(

HDC hDC	// handle of device context
);
Parameters

hDC

Identifies the device context for the print job.

Return Values

If the function succeeds, the return value is greater than zero.

If the function fails, the return value is less than or equal to zero. To get extended error information, call GetLastError.

Remarks

The system disables the ResetDC function between calls to the StartPage and EndPage functions. This means that you cannot change the device mode except at page boundaries. After calling EndPage, you can call ResetDC to change the device mode, if necessary. Note that a call to ResetDC resets all device context attributes back to default values.

Windows 3.x: EndPage resets the device context attributes back to default values. You must re-select objects and set up the mapping mode again before printing the next page.

Windows 95: EndPage does not reset the device context attributes. However, the next StartPage call does reset the device context attributes to default values. At that time, you must re-select objects and set up the mapping mode again before printing the next page. Note that StartPage also resets the device context state stack used by the SaveDC and RestoreDC functions to default values.

Windows NT: Beginning with Windows NT Version 3.5, neither EndPage or StartPage resets the device context attributes. Device context attributes remain constant across subsequent pages. You do not need to re-select objects and set up the mapping mode again before printing the next page; however, doing so will produce the same results and reduce code differences between Windows 95 and Windows NT.

See Also

EndPage, ResetDC


StartPagePrinter

The StartPagePrinter function informs the spooler that a page is about to be printed on the specified printer.

BOOL StartPagePrinter(

HANDLE hPrinter	// handle of printer object
);
Parameters

hPrinter

Identifies a printer.

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.

Remarks

The printer handle identified by the hPrinter parameter is obtained by calling the OpenPrinter function.

When an application has finished writing a page, it should call the EndPagePrinter function to inform the spooler that the page is complete.

See Also

EndPagePrinter, OpenPrinter


StartService

The StartService function starts the execution of a service.

BOOL StartService(

SC_HANDLE hService,	// handle of service
DWORD dwNumServiceArgs,	// number of arguments
LPCTSTR *lpServiceArgVectors	// address of array of argument string pointers
);
Parameters

hService

Identifies the service. This handle is returned by the OpenService or CreateService function, and it must have SERVICE_START access.

dwNumServiceArgs

Specifies the number of argument strings in the lpServiceArgVectors array. If lpServiceArgVectors is NULL, this parameter can be zero.

lpServiceArgVectors

Points to an array of pointers that point to null-terminated argument strings passed to a service. Driver services do not receive these arguments. If no arguments are passed to the service being started, this parameter can be NULL. The service accesses these arguments through its ServiceMain function. Note that in the array of arguments passed to the ServiceMain function, the first argument (argv[0]) is the name of the service by default, followed by the arguments, if any, in the lpServiceArgVectors array.

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.

Errors

The following error codes can be set by the service control manager. Others can be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED	The specified handle was not opened with SERVICE_START access.
ERROR_INVALID_HANDLE	The specified handle is invalid.
ERROR_PATH_NOT_FOUND	The service binary file could not be found.
ERROR_SERVICE_ALREADY_RUNNING	An instance of the service is already running.
ERROR_SERVICE_DATABASE_LOCKED	The database is locked.
ERROR_SERVICE_DEPENDENCY_DELETED	The service depends on a service that does not exist or has been marked for deletion.
ERROR_SERVICE_DEPENDENCY_FAIL	The service depends on another service that has failed to start.
ERROR_SERVICE_DISABLED	The service has been disabled.
ERROR_SERVICE_LOGON_FAILED	The service could not be logged on.
ERROR_SERVICE_MARKED_FOR_DELETE	The service has been marked for deletion.
ERROR_SERVICE_NO_THREAD	A thread could not be created for the Win32 service.
ERROR_SERVICE_REQUEST_TIMEOUT	The service did not respond to the start request in a timely fashion.
Remarks

When a driver service is started, the StartService function does not return until the device driver has finished initializing.

When a service is started, the service control manager spawns the service process, if necessary. If the specified service shares a process with other services, the required process may already exist. The StartService function does not wait for the first status update from the new service (which may take a while). Instead, it returns when the service control manager receives notification from the service control dispatcher that the ServiceMain thread for this service was created successfully.

The service control manager sets the following default status values before returning from StartService:

•	Current state of the service is set to SERVICE_START_PENDING.

•	Controls accepted is set to none (zero).

•	The CheckPoint value is set to zero.

•	The WaitHint time is set to 2 seconds.

The calling process can determine if the new service has finished its initialization by calling the QueryServiceStatus function periodically to query the service’s status.

A service cannot call StartService during initialization. The reason is that the Service Control Manager locks the service control database during initialization, so a call to StartService will block. Once the service reports to the Service Control Manager that it has successfully started, it can call StartService.

See Also

ControlService, CreateService, OpenService, QueryServiceStatus, ServiceMain


StartServiceCtrlDispatcher

The StartServiceCtrlDispatcher function connects the main thread of a service process to the service control manager, which causes the thread to be the service control dispatcher thread for the calling process.

BOOL StartServiceCtrlDispatcher(

LPSERVICE_TABLE_ENTRY lpServiceStartTable	// address of service table
);
Parameters

lpServiceStartTable

Points to an array of SERVICE_TABLE_ENTRY structures containing one entry for each service that can execute in the calling process. The members of the last entry in the table must have NULL values to designate the end of the table.

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.

Errors

The following error code can be set by the service control manager. Other error codes can be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_INVALID_DATA	The specified dispatch table contains entries that are not in the proper format.
Remarks

When the service control manager starts a service process, it waits for the process to call the StartServiceCtrlDispatcher function. The main thread of a service process should make this call as soon as possible after it starts up. If StartServiceCtrlDispatcher succeeds, it connects the calling thread to the service control manager and does not return until all running services in the process have terminated. The service control manager uses this connection to send control and service start requests to the main thread of the service process. The main thread acts as a dispatcher by invoking the appropriate Handler function to handle control requests, or by creating a new thread to execute the appropriate ServiceMain function when a new service is started.

The lpServiceStartTable parameter contains an entry for each service that can run in the calling process. Each entry specifies the ServiceMain function for that service. For SERVICE_WIN32_SHARE_PROCESS services, each entry must contain the name of a service. This name is the service name that was specified by the CreateService function when the service was installed. For SERVICE_WIN32_OWN_PROCESS services, the service name in the table entry is ignored.

If a service runs in its own process, the main thread of the service process should immediately call StartServiceCtrlDispatcher. All initialization tasks are done in the service’s ServiceMain function when the service is started.

If multiple services share a process and some common process-wide initialization needs to be done before any ServiceMain function is called, the main thread can do the work before calling StartServiceCtrlDispatcher, as long as it takes less than 30 seconds. Otherwise, another thread must be created to do the process-wide initialization, while the main thread calls StartServiceCtrlDispatcher and becomes the service control dispatcher. Any service-specific initialization should still be done in the individual service main functions.

See Also

ControlService, Handler, RegisterServiceCtrlHandler, ServiceMain, SERVICE_TABLE_ENTRY


StretchBlt

The StretchBlt function copies a bitmap from a source rectangle into a destination rectangle, stretching or compressing the bitmap to fit the dimensions of the destination rectangle, if necessary. Windows stretches or compresses the bitmap according to the stretching mode currently set in the destination device context.

BOOL StretchBlt(

HDC hdcDest,	// handle of destination device context
int nXOriginDest,	// x-coordinate of upper-left corner of dest. rect.
int nYOriginDest,	// y-coordinate of upper-left corner of dest. rect.
int nWidthDest,	// width of destination rectangle
int nHeightDest,	// height of destination rectangle
HDC hdcSrc,	// handle of source device context
int nXOriginSrc,	// x-coordinate of upper-left corner of source rectangle
int nYOriginSrc,	// y-coordinate of upper-left corner of source rectangle
int nWidthSrc,	// width of source rectangle
int nHeightSrc,	// height of source rectangle
DWORD dwRop	// raster operation code
);
Parameters

hdcDest

Identifies the destination device context.

nXOriginDest

Specifies the x-coordinate, in logical units, of the upper-left corner of the destination rectangle.

nYOriginDest

Specifies the y-coordinate, in logical units, of the upper-left corner of the destination rectangle.

nWidthDest

Specifies the width, in logical units, of the destination rectangle.

nHeightDest

Specifies the height, in logical units, of the destination rectangle.

hdcSrc

Identifies the source device context.

nXOriginSrc

Specifies the x-coordinate, in logical units, of the upper-left corner of the source rectangle.

nYOriginSrc

Specifies the y-coordinate, in logical units, of the upper-left corner of the source rectangle.

nWidthSrc

Specifies the width, in logical units, of the source rectangle.

nHeightSrc

Specifies the height, in logical units, of the source rectangle.

dwRop

Specifies the raster operation to be performed. Raster operation codes define how Windows combines colors in output operations that involve a brush, a source bitmap, and a destination bitmap.

See the BitBlt function for a list of common raster operation codes.

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.

Remarks

StretchBlt stretches or compresses the source bitmap in memory and then copies the result to the destination rectangle. The color data for pattern or destination pixels is merged after the stretching or compression occurs.

When an enhanced metafile is being recorded, an error occurs (and the function returns FALSE) if the source device context identifies an enhanced-metafile device context.

If the specified raster operation requires a brush, Windows uses the brush currently selected into the destination device context.

The destination coordinates are transformed by using the transformation currently specified for the destination device context; the source coordinates are transformed by using the transformation currently specified for the source device context.

If the source transformation has a rotation or shear, an error occurs.

If destination, source, and pattern bitmaps do not have the same color format, StretchBlt converts the source and pattern bitmaps to match the destination bitmap.

If StretchBlt must convert a monochrome bitmap to a color bitmap, it sets white bits (1) to the background color and black bits (0) to the foreground color. To convert a color bitmap to a monochrome bitmap, it sets pixels that match the background color to white (1) and sets all other pixels to black (0). The foreground and background colors of the device context with color are used.

StretchBlt creates a mirror image of a bitmap if the signs of the nWidthSrc and nWidthDest parameters or of the nHeightSrc and nHeightDest parameters differ. If nWidthSrc and nWidthDest have different signs, the function creates a mirror image of the bitmap along the x-axis. If nHeightSrc and nHeightDest have different signs, the function creates a mirror image of the bitmap along the y-axis.

Not all devices support the StretchBlt function. For more information, see the GetDeviceCaps function.

See Also

BitBlt, GetDeviceCaps, MaskBlt, PlgBlt, SetStretchBltMode


StretchDIBits

The StretchDIBits function copies the color data for a rectangle of pixels in a device-independent bitmap (DIB) to the specified destination rectangle. If the destination rectangle is larger than the source rectangle, this function stretches the rows and columns of color data to fit the destination rectangle. If the destination rectangle is smaller than the source rectangle, this function compresses the rows and columns by using the specified raster operation.

int StretchDIBits(

HDC hdc,	// handle of device context
int XDest,	// x-coordinate of upper-left corner of dest. rect.
int YDest,	// y-coordinate of upper-left corner of dest. rect.
int nDestWidth,	// width of destination rectangle
int nDestHeight,	// height of destination rectangle
int XSrc,	// x-coordinate of upper-left corner of source rect.
int YSrc,	// y-coordinate of upper-left corner of source rect.
int nSrcWidth,	// width of source rectangle
int nSrcHeight,	// height of source rectangle
CONST VOID *lpBits,	// address of bitmap bits
CONST BITMAPINFO *lpBitsInfo,	// address of bitmap data
UINT iUsage,	// usage
DWORD dwRop	// raster operation code
);
Parameters

hdc

Identifies the destination device context.

XDest

Specifies the x-coordinate, in logical units, of the upper-left corner of the destination rectangle.

YDest

Specifies the y-coordinate, in logical units, of the upper-left corner of the destination rectangle.

nDestWidth

Specifies the width, in logical units, of the destination rectangle.

nDestHeight

Specifies the height, in logical units, of the destination rectangle.

XSrc

Specifies the x-coordinate, in pixels, of the source rectangle in the DIB.

YSrc

Specifies the y-coordinate, in pixels, of the source rectangle in the DIB.

nSrcWidth

Specifies the width, in pixels, of the source rectangle in the DIB.

nSrcHeight

Specifies the height, in pixels, of the source rectangle in the DIB.

lpBits

Points to the DIB bits, which are stored as an array of bytes.

lpBitsInfo

Points to a BITMAPINFO structure that contains information about the DIB.

iUsage

Specifies whether the bmiColors member of the BITMAPINFO structure was provided and, if so, whether bmiColors contains explicit red, green, blue (RGB) values or indices. The iUsage parameter must be one of the following values:

Value	Description
DIB_PAL_COLORS	The array contains 16-bit indices into the logical palette of the source device context.
DIB_RGB_COLORS	The color table contains literal RGB values.
dwRop

Specifies how the source pixels, the destination device context’s current brush, and the destination pixels are to be combined to form the new image.

Return Values

If the function succeeds, the return value is the number of scan lines copied.

If the function fails, the return value is GDI_ERROR. To get extended error information, call GetLastError.

Remarks

The origin of a bottom-up DIB is the bottom-left corner; the origin of a top-down DIB is the upper-left corner.

StretchDIBits creates a mirror image of a bitmap if the signs of the nSrcWidth and nDestWidth parameters, or of the nSrcHeight and nDestHeight parameters differ. If nSrcWidth and nDestWidth have different signs, the function creates a mirror image of the bitmap along the x-axis. If nSrcHeight and nDestHeight have different signs, the function creates a mirror image of the bitmap along the y-axis.

See Also

SetMapMode, SetStretchBltMode, BITMAPINFO


StrokeAndFillPath

The StrokeAndFillPath function closes any open figures in a path, strokes the outline of the path by using the current pen, and fills its interior by using the current brush.

BOOL StrokeAndFillPath(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

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 one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY

Remarks

The device context identified by the hdc parameter must contain a closed path.

The StrokeAndFillPath function has the same effect as closing all the open figures in the path, and stroking and filling the path separately, except that the filled region will not overlap the stroked region even if the pen is wide.

See Also

BeginPath, FillPath, SetPolyFillMode, StrokePath


StrokePath

The StrokePath function renders the specified path by using the current pen.

BOOL StrokePath(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies a device context that contains a closed path.

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 one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY

Remarks

The device context identified by the hdc parameter must contain a closed path.

See Also

BeginPath, EndPath, ExtCreatePen


SubtractRect

The SubtractRect function obtains the coordinates of a rectangle determined by subtracting one rectangle from another.

BOOL SubtractRect(

LPRECT lprcDst,	// pointer to destination rectangle
CONST RECT *lprcSrc1,	// pointer to rectangle to subtract from
CONST RECT *lprcSrc2	// pointer to rectangle to subtract
);
Parameters

lprcDst

Points to a RECT structure that receives the coordinates of the rectangle determined by subtracting the rectangle pointed to by lprcSrc2 from the rectangle pointed to by lprcSrc1.

lprcSrc1

Points to a RECT structure from which the function subtracts the rectangle pointed to by lprcSrc2.

lprcSrc2

Points to a RECT structure that the function subtracts from the rectangle pointed to by lprcSrc1.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The function only subtracts the rectangle specified by lprcSrc2 from the rectangle specified by lprcSrc1 when the rectangles intersect completely in either the x- or y-direction. For example, if *lprcSrc1 has the coordinates (10,10,100,100) and *lprcSrc2 has the coordinates (50,50,150,150), the function sets the coordinates of the rectangle pointed to by lprcDst to (10,10,100,100). If *lprcSrc1 has the coordinates (10,10,100,100) and *lprcSrc2 has the coordinates (50,10,150,150), however, the function sets the coordinates of the rectangle pointed to by lprcDst to (10,10,50,100).

See Also

IntersectRect, RECT, UnionRect


SuspendThread

The SuspendThread function suspends the specified thread.

DWORD SuspendThread(

HANDLE hThread	// handle to the thread
);
Parameters

hThread

Identifies the thread.

Windows NT: The handle must have THREAD_SUSPEND_RESUME access. For more information, see Thread Objects.

Return Values

If the function succeeds, the return value is the thread’s previous suspend count; otherwise, it is 0xFFFFFFFF. To get extended error information, use the GetLastError function.

Remarks

If the function succeeds, execution of the specified thread is suspended and the thread’s suspend count is incremented.

Suspending a thread causes the thread to stop executing user-mode (application) code.

Each thread has a suspend count (with a maximum value of MAXIMUM_SUSPEND_COUNT). If the suspend count is greater than zero, the thread is suspended; otherwise, the thread is not suspended and is eligible for execution. Calling SuspendThread causes the target thread’s suspend count to be incremented. Attempting to increment past the maximum suspend count causes an error without incrementing the count.

The ResumeThread function decrements the suspend count of a suspended thread.

See Also

ResumeThread


SwapMouseButton

The SwapMouseButton function reverses or restores the meaning of the left and right mouse buttons.

BOOL SwapMouseButton(

BOOL fSwap	// reverse or restore buttons
);
Parameters

fSwap

Specifies whether the mouse button meanings are reversed or restored. If this parameter is TRUE, the left button generates right-button messages and the right button generates left-button messages. If this parameter is FALSE, the buttons are restored to their original meanings.

Return Values

If the meaning of the mouse buttons was reversed previously, before the function was called, the return value is nonzero.

If the meaning of the mouse buttons was not reversed, the return value is zero.

Remarks

Button swapping is provided as a convenience to people who use the mouse with their left hands. The SwapMouseButton function is usually called by Control Panel only. Although an application is free to call the function, the mouse is a shared resource and reversing the meaning of its buttons affects all applications.

See Also

SetDoubleClickTime


SwitchDesktop

The SwitchDesktop function makes a desktop visible and activates it. This enables the desktop to receive input from the user. The calling process must have DESKTOP_SWITCHDESKTOP access to the desktop for the SwitchDesktop function to succeed.

BOOL SwitchDesktop(

HDESK hDesktop	// handle of desktop to activate
);
Parameters

hDesktop

Identifies the desktop to be made visible and active. This handle is returned by the CreateDesktop and OpenDesktop functions.

The SwitchDesktop function will fail if the desktop belongs to an invisible window station.

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.

See Also

CreateDesktop, OpenDesktop


SwitchToFiber

The SwitchToFiber function schedules a fiber.

VOID SwitchToFiber(

LPVOID lpFiber	// pointer to fiber to switch to
);
Parameters

lpFiber

Specifies the address of the fiber to switch to.

Return Values

This function does not return a value.

Remarks

The SwitchToFiber function is used to manually schedule a fiber. This function saves the state information of the current fiber and restores the state of the specified fiber. The caller of this routine must be a fiber.

You create fibers with CreateFiber. Before you can schedule fibers associated with a thread, you must call ConvertThreadToFiber to set up an area in which to save the fiber state information. The thread is now the currently executing fiber.

Warning  Avoid making the following call:

SwitchToFiber( GetCurrentFiber() );

This call causes unpredictable problems.

See Also

CreateFiber, ConvertThreadToFiber


SwitchToThread [New - Windows NT]
SwitchToThread

[New - Windows NT]

The SwitchToThread function causes the calling thread to yield execution to another thread that is ready to run on the current processor. The operating system selects the thread to yield to.

BOOL SwitchToThread(VOID)

Parameters

This function has no parameters.

Return Values

If calling the SwitchToThread function causes the operating system to switch execution to another thread, the return value is nonzero.

If there are no other threads ready to execute, the operating system does not switch execution to another thread, and the return value is zero.

Remarks

The yield of execution is in effect for up to one thread-scheduling time slice. After that, the operating system reschedules execution for the yielding thread. The rescheduling is determined by the priority of the yielding thread and the status of other threads that are available to run.

Note that the yield of execution is limited to the processor of the calling thread. The operating system will not switch execution to another processor, even if that processor is idle or is running a thread of lower priority.

See Also

SuspendThread


SysMsgProc

The SysMsgProc hook procedure is a library-defined callback function the system calls after an input event occurs in a dialog box, message box, menu, or scroll bar, but before the message generated by the input event is processed. The hook procedure can monitor messages for any dialog box, message box, menu, or scroll bar in the system.

LRESULT CALLBACK SysMsgProc(

int nCode,	// message flag
WPARAM wParam,	// undefined
LPARAM lParam	// address of structure with message data
);
Parameters

nCode

Specifies the type of input event that generated the message. This parameter can be one of the following values:

Value	Meaning
MSGF_DIALOGBOX	The input event occurred in a message box or dialog box.
MSGF_MENU	The input event occurred in a menu.
MSGF_SCROLLBAR	The input event occurred in a scroll bar.
MSGF_NEXTWINDOW	The input event occurred as a result of the user’s pressing the ALT+TAB key combination to activate a different window.
If nCode is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies a NULL value.

lParam

Points to an MSG message structure.

Return Values

If the hook procedure processes the message, the return value must be nonzero. Otherwise, it must be zero.

Remarks

An application installs the hook procedure by specifying the WH_SYSMSGFILTER hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

SysMsgProc is a placeholder for the library-defined function name.

See Also

CallNextHookEx, MSG, SetWindowsHookEx


SystemParametersInfo

The SystemParametersInfo function queries or sets systemwide parameters. This function can also update the user profile while setting a parameter.

BOOL SystemParametersInfo(

UINT uiAction,	// system parameter to query or set
UINT uiParam,	// depends on action to be taken
PVOID pvParam,	// depends on action to be taken
UINT fWinIni	// user profile update flag
);
Parameters

uiAction

Specifies the systemwide parameter to query or set. This parameter can be one of the following values:

Value	Meaning
SPI_GETACCESSTIMEOUT	Retrieves information about the time-out period associated with the accessibility features. The pvParam parameter must point to an ACCESSTIMEOUT structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(ACCESSTIMEOUT).
SPI_GETANIMATION	Retrieves the animation effects associated with user actions. The pvParam parameter must point to an ANIMATIONINFO structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(ANIMATIONINFO).
SPI_GETBEEP	Indicates whether the warning beeper is on. The pvParam parameter is a pointer to a BOOL that receives TRUE if the beeper is on, or FALSE if it is off.
SPI_GETBORDER	Retrieves the border multiplier factor that determines the width of a window’s sizing border. The pvParam parameter must point to an integer variable.
SPI_GETDEFAULTINPUTLANG	Returns the keyboard layout handle for the system default input language. The pvParam parameter must point to the 32-bit variable that receives the keyboard layout handle for the default language. The uiParam parameter is not used.
SPI_GETDRAGFULLWINDOWS	Determines whether dragging of full windows is enabled. The pvParam parameter must point to a BOOL variable that receives TRUE if enabled, or FALSE otherwise.  Windows 95: This flag is supported only if Windows Plus! is installed. See SPI_GETWINDOWSEXTENSION.
SPI_GETFASTTASKSWITCH	This flag is obsolete. Previous versions of Windows use this flag to determine whether ALT+TAB fast task switching is enabled. Beginning with Windows 95 and Windows NT version 4.0, fast task switching is always enabled.
SPI_GETFILTERKEYS	Retrieves information about the FilterKeys accessibility feature. The pvParam parameter must point to a FILTERKEYS structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(FILTERKEYS).
SPI_GETFONTSMOOTHING	Indicates whether the font smoothing feature is enabled. This feature uses font anti-aliasing to make font curves appear smoother by painting pixels at different gray levels.  The pvParam parameter is a pointer to a BOOL variable that receives TRUE if the feature is enabled, or FALSE if it is not. Windows 95: This flag is supported only if Windows Plus! is installed. See SPI_GETWINDOWSEXTENSION.
SPI_GETGRIDGRANULARITY	Retrieves the current granularity value of the desktop sizing grid. The pvParam parameter must point to an integer variable that receives the granularity.
SPI_GETHIGHCONTRAST	Windows 95 only: Retrieves information about the HighContrast accessibility feature. The pvParam parameter must point to a HIGHCONTRAST structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(HIGHCONTRAST).
SPI_GETICONMETRICS	Retrieves the metrics associated with icons. The pvParam parameter must point to an ICONMETRICS structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(ICONMETRICS).
SPI_GETICONTITLELOGFONT	Retrieves the logical font information for the current icon-title font. The uiParam parameter specifies the size of a LOGFONT structure, and the pvParam parameter must point to the LOGFONT structure to fill in.
SPI_GETICONTITLEWRAP	Determines whether icon-title wrapping is enabled. The pvParam parameter must point to a BOOL variable that receives TRUE if enabled, or FALSE otherwise.
SPI_GETKEYBOARDDELAY	Retrieves the keyboard repeat-delay setting. The pvParam parameter must point to an integer variable that receives the setting.
SPI_GETKEYBOARDPREF	Determines whether the user relies on the keyboard instead of the mouse, and wants applications to display keyboard interfaces that would otherwise be hidden. The pvParam parameter must point to a BOOL variable that receives TRUE if the user relies on the keyboard; the variable receives FALSE otherwise.
SPI_GETKEYBOARDSPEED	Retrieves the keyboard repeat-speed setting. The pvParam parameter must point to a DWORD variable that receives the setting.
SPI_GETLOWPOWERACTIVE	This flag is not supported for 32-bit applications on Windows NT or Windows 95. Windows 95 only: For 16-bit Windows applications, this value determines whether the low-power phase of screen saving is enabled or not. The pvParam parameter must point to a BOOL variable that receives TRUE if enabled, or FALSE if disabled.
SPI_GETLOWPOWERTIMEOUT	This flag is not supported for 32-bit applications on Windows NT or Windows 95. Windows 95 only: For 16-bit Windows applications, this value retrieves the time-out value for the low-power phase of screen saving. The pvParam parameter must point to an integer value that receives the value.
SPI_GETMENUDROPALIGNMENT	Determines whether pop-up menus are left-aligned or right-aligned, relative to the corresponding menu-bar item. The pvParam parameter must point to a BOOL variable that receives TRUE if left-aligned, or FALSE otherwise.
SPI_GETMINIMIZEDMETRICS	Retrieves the metrics associated with minimized windows. The pvParam parameter must point to a MINIMIZEDMETRICS structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(MINIMIZEDMETRICS).
SPI_GETMOUSE	Retrieves the two mouse threshold values and the mouse speed. The pvParam parameter must point to an array of three integers that receives these values. See mouse_event for further information.
SPI_GETMOUSEHOVERHEIGHT	Windows NT only: Gets the height, in pixels, of the rectangle within which the mouse pointer has to stay for TrackMouseEvent to generate a WM_MOUSEHOVER message. The height is returned in a UINT pointed to by the pvParam parameter.
SPI_GETMOUSEHOVERTIME	Windows NT only: Gets the time, in milliseconds, that the mouse pointer has to stay in the hover rectangle for TrackMouseEvent to generate a WM_MOUSEHOVER message. The time is returned in a UINT pointed to by the pvParam parameter.
SPI_GETMOUSEHOVERWIDTH	Windows NT only: Gets the width, in pixels, of the rectangle within which the mouse pointer has to stay for TrackMouseEvent to generate a WM_MOUSEHOVER message. The width is returned in a UINT pointed to by the pvParam parameter.
SPI_GETMOUSEKEYS	Retrieves information about the MouseKeys accessibility feature. The pvParam parameter must point to a MOUSEKEYS structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(MOUSEKEYS).
SPI_GETMOUSETRAILS	Windows 95 only: Indicates whether the Mouse Trails feature is enabled. This feature improves the visibility of mouse cursor movements by briefly showing a trail of cursors and quickly erasing them. The pvParam parameter is a pointer to an INT variable that receives a value. If the value is zero or 1, the feature is disabled. If the value is greater than 1, the feature is enabled and the value indicates the number of cursors drawn in the trail. The uiParam parameter is not used.
SPI_GETNONCLIENTMETRICS	Retrieves the metrics associated with the nonclient area of nonminimized windows. The pvParam parameter must point to a NONCLIENTMETRICS structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(NONCLIENTMETRICS).
SPI_GETPOWEROFFACTIVE	This flag is not supported for 32-bit applications on Windows NT or Windows 95. Windows 95 only: For 16-bit Windows applications, this value determines whether the power-off phase of screen saving is enabled or not. The pvParam parameter must point to a BOOL variable that receives TRUE if enabled, or FALSE if disabled.
SPI_GETPOWEROFFTIMEOUT	This flag is not supported for 32-bit applications on Windows NT or Windows 95. Windows 95 only: For 16-bit Windows applications, this value retrieves the time-out value for the power-off phase of screen saving. The pvParam parameter must point to an integer value that receives the value.
SPI_GETSCREENREADER	Windows 95 only: Determines whether a screen reviewer utility is running. A screen reviewer utility directs textual information to an output device, such as a speech synthesizer or Braille display. When this flag is set, an application should provide textual information in situations where it would otherwise present the information graphically.  The pvParam parameter is a pointer to a BOOL variable that receives TRUE if a screen reviewer utility is running, or FALSE if it is not.
SPI_GETSCREENSAVEACTIVE	Determines whether screen saving is enabled. The pvParam parameter must point to a BOOL variable that receives TRUE if enabled, or FALSE otherwise.
SPI_GETSCREENSAVETIMEOUT	Retrieves the screen saver time-out value, in seconds. The pvParam parameter must point to an integer variable that receives the value.
SPI_GETSERIALKEYS	Windows 95 only: Retrieves information about the SerialKeys accessibility feature. The pvParam parameter must point to a SERIALKEYS structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(SERIALKEYS).
SPI_GETSHOWSOUNDS	Determines whether the Show Sounds accessibility flag is on or off. If it is on, the user requires an application to present information visually in situations where it would otherwise present the information only in audible form. The pvParam parameter must point to a BOOL variable that receives TRUE if the feature is on, or FALSE if it is off. Using this value is equivalent to calling GetSystemMetrics (SM_SHOWSOUNDS). That is the recommended call.
SPI_GETSNAPTODEFBUTTON	Windows NT only: Determines whether the snap-to-default-button feature is enabled. If enabled, the mouse cursor automatically moves to the default button, such as “OK” or “Apply”, of a dialog box. The pvParam parameter must point to a BOOL variable that receives TRUE if the feature is on, or FALSE if it is off.
SPI_GETSOUNDSENTRY	Retrieves information about the SoundSentry accessibility feature. The pvParam parameter must point to a SOUNDSENTRY structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(SOUNDSENTRY).
SPI_GETSTICKYKEYS	Retrieves information about the StickyKeys accessibility feature. The pvParam parameter must point to a STICKYKEYS structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(STICKYKEYS).
SPI_GETTOGGLEKEYS	Retrieves information about the ToggleKeys accessibility feature. The pvParam parameter must point to a TOGGLEKEYS structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(TOGGLEKEYS).
SPI_GETWHEELSCROLLLINES	Windows NT only: Gets the number of lines to scroll when the mouse wheel is rotated. The number of lines is returned in a UINT pointed to by pvParam. The default value is 3.
SPI_GETWINDOWSEXTENSION	Windows 95 only: Indicates whether the Windows extension, Windows Plus!, is installed. Set the uiParam parameter to 1. The pvParam parameter is not used. The function returns TRUE if the extension is installed, or FALSE if it is not.
SPI_GETWORKAREA	Retrieves the size of the working area. The working area is the portion of the screen not obscured by the tray. The pvParam parameter must point to the RECT structure that receives the coordinates of the working area.
SPI_ICONHORIZONTALSPACING	Sets the width of an icon cell. The uiParam parameter specifies the width, in pixels.
SPI_ICONVERTICALSPACING	Sets the height of an icon cell. The uiParam parameter specifies the height, in pixels.
SPI_LANGDRIVER	Not implemented.
SPI_SCREENSAVERRUNNING	Windows 95 only: Used internally; applications should not use this flag.
SPI_SETACCESSTIMEOUT	Sets the time-out period associated with the accessibility features. The pvParam parameter must point to an ACCESSTIMEOUT structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(ACCESSTIMEOUT).
SPI_SETANIMATION	Sets the animation effects associated with user actions. The pvParam parameter must point to an ANIMATIONINFO structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(ANIMATIONINFO).
SPI_SETBEEP	Turns the warning beeper on or off. The uiParam parameter specifies TRUE for on, or FALSE for off.
SPI_SETBORDER	Sets the border multiplier factor that determines the width of a window’s sizing border. The uiParam parameter specifies the new value.
SPI_SETDEFAULTINPUTLANG	Sets the default input language for the system shell and applications. The specified language must be displayable using the current system character set. The uiParam parameter is not used. The pvParam parameter must point to a 32-bit variable that contains the keyboard layout handle for the default language.
SPI_SETDESKPATTERN	Sets the current desktop pattern by causing Windows to read the Pattern= setting from the WIN.INI file.
SPI_SETDESKWALLPAPER	Sets the desktop wallpaper. The pvParam parameter must point to a null-terminated string containing the name of a bitmap file.
SPI_SETDOUBLECLICKTIME	Sets the double-click time for the mouse to the value of the uiParam parameter. The double-click time is the maximum number of milliseconds that can occur between the first and second clicks of a double-click.
SPI_SETDOUBLECLKHEIGHT	Sets the height of the double-click rectangle to the value of the uiParam parameter. The double-click rectangle is the rectangle within which the second click of a double-click must fall for it to be registered as a double-click.
SPI_SETDOUBLECLKWIDTH	Sets the width of the double-click rectangle to the value of the uiParam parameter. The double-click rectangle is the rectangle within which the second click of a double-click must fall for it to be registered as a double-click.
SPI_SETDRAGFULLWINDOWS	Sets dragging of full windows either on or off. The uiParam parameter specifies TRUE for on, or FALSE for off. Windows 95: This flag is supported only if Windows Plus! is installed. See SPI_GETWINDOWSEXTENSION.
SPI_SETDRAGHEIGHT	Sets the height, in pixels, of the rectangle used to detect the start of a drag operation.  See SM_CXDRAG and SM_CYDRAG in the table under the nIndex parameter of GetSystemMetrics.
SPI_SETDRAGWIDTH	Sets the width, in pixels, of the rectangle used to detect the start of a drag operation. See SM_CXDRAG and SM_CYDRAG in the table under the nIndex parameter of GetSystemMetrics.
SPI_SETFASTTASKSWITCH	This flag is obsolete. Previous versions of Windows use this flag to enable or disable ALT+TAB fast task switching. Beginning with Windows 95 and Windows NT version 4.0, fast task switching is always enabled.
SPI_SETFILTERKEYS	Sets the parameters of the FilterKeys accessibility feature. The pvParam parameter must point to a FILTERKEYS structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(FILTERKEYS).
SPI_SETFONTSMOOTHING	Enables or disables the font smoothing feature, which uses font anti-aliasing to make font curves appear smoother by painting pixels at different gray levels.  To enable the feature, set the uiParam parameter to TRUE. To disable the feature, set uiParam to FALSE.  Windows 95: This flag is supported only if Windows Plus! is installed. See SPI_GETWINDOWSEXTENSION.
SPI_SETGRIDGRANULARITY	Sets the granularity of the desktop sizing grid to the value of the uiParam parameter.
SPI_SETHANDHELD	Used internally; applications should not use this value.
SPI_SETHIGHCONTRAST	Windows 95 only: Sets the parameters of the HighContrast accessibility feature. The pvParam parameter must point to a HIGHCONTRAST structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(HIGHCONTRAST).
SPI_SETICONMETRICS	Sets the metrics associated with icons. The pvParam parameter must point to an ICONMETRICS structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(ICONMETRICS).
SPI_SETICONTITLELOGFONT	Sets the font that is used for icon titles. The uiParam parameter specifies the size of a LOGFONT structure, and the pvParam parameter must point to a LOGFONT structure.
SPI_SETICONTITLEWRAP	Turns icon-title wrapping on or off. The uiParam parameter specifies TRUE for on, or FALSE for off.
SPI_SETKEYBOARDDELAY	Sets the keyboard repeat-delay setting to the value of the uiParam parameter.
SPI_SETKEYBOARDPREF	Windows 95 only: Sets the keyboard preference. The uiParam parameter specifies TRUE if the user relies on the keyboard instead of the mouse, and wants applications to display keyboard interfaces that would otherwise be hidden; uiParam is FALSE otherwise.
SPI_SETKEYBOARDSPEED	Sets the keyboard repeat-speed setting to the value of the uiParam parameter.
SPI_SETLANGTOGGLE	Sets the hot key set for switching between input languages. The uiParam and pvParam parameters are not used. The value sets the shortcut keys in the keyboard property sheets by reading the registry again. The registry must be set before this flag is used. the path in the registry is \HKEY_CURRENT_USER\keyboard layout\toggle. Valid values are “1” = ALT+SHIFT, “2” = CTRL+SHIFT, and “3” = none.
SPI_SETLOWPOWERACTIVE	Windows 95 only: Activates or deactivates the low-power phase of screen saving. Set uiParam to 1 to activate, or 0 to deactivate. The pvParam parameter must be NULL.
SPI_SETLOWPOWERTIMEOUT	Windows 95 only: Retrieves the time-out value, in seconds, for the low-power phase of screen saving. The uiParam parameter specifies the new value. The pvParam parameter must be NULL.
SPI_SETMENUDROPALIGNMENT	Sets the alignment value of pop-up menus. The uiParam parameter specifies TRUE for right alignment, or FALSE for left alignment.
SPI_SETMINIMIZEDMETRICS	Sets the metrics associated with minimized windows. The pvParam parameter must point to a MINIMIZEDMETRICS structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(MINIMIZEDMETRICS).
SPI_SETMOUSE	Sets the two mouse threshold values and the mouse speed. The pvParam parameter must point to an array of three integers that specifies these values. See mouse_event for further information.
SPI_SETMOUSEBUTTONSWAP	Swaps or restores the meaning of the left and right mouse buttons. The uiParam parameter specifies TRUE to swap the meanings of the buttons, or FALSE to to restore their original meanings.
SPI_SETMOUSEHOVERHEIGHT	Windows NT only: Sets the height, in pixels, of the rectangle within which the mouse pointer has to stay for TrackMouseEvent to generate a WM_MOUSEHOVER message. The height is set from the uiParam parameter.
SPI_SETMOUSEHOVERTIME	Windows NT only: Sets the time, in milliseconds, that the mouse pointer has to stay in the hover rectangle for TrackMouseEvent to generate a WM_MOUSEHOVER message. This is used only if you pass HOVER_DEFAULT in the dwHoverTime parameter in the call to TrackMouseEvent. The time is set from the uiParam parameter.
SPI_SETMOUSEHOVERWIDTH	Windows NT only: Sets the width, in pixels, of the rectangle within which the mouse pointer has to stay for TrackMouseEvent to generate a WM_MOUSEHOVER message. The width is set from the uiParam parameter.
SPI_SETMOUSEKEYS	Sets the parameters of the MouseKeys accessibility feature. The pvParam parameter must point to a MOUSEKEYS structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(MOUSEKEYS).
SPI_SETMOUSETRAILS	Windows 95 only: Enables or disables the Mouse Trails feature, which improves the visibility of mouse cursor movements by briefly showing a trail of cursors and quickly erasing them. To disable the feature, set the uiParam parameter to zero or 1. To enable the feature, set uiParam to a value greater than 1 to indicate the number of cursors drawn in the trail.
SPI_SETNONCLIENTMETRICS	Sets the metrics associated with the nonclient area of nonminimized windows. The pvParam parameter must point to a NONCLIENTMETRICS structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(NONCLIENTMETRICS).
SPI_SETPENWINDOWS	Windows 95 only: Specifies that pen windows is being loaded or unloaded. The uiParam parameter is TRUE when loading and FALSE when unloading pen windows. The pvParam parameter is NULL.
SPI_SETPOWEROFFACTIVE	Windows 95 only: Activates or deactivates the power-off phase of screen saving. Set uiParam to 1 to activate, or 0 to deactivate. The pvParam parameter must be NULL.
SPI_SETPOWEROFFTIMEOUT	Windows 95 only: Retrieves the time-out value, in seconds, for the power-off phase of screen saving. The uiParam parameter specifies the new value. The pvParam parameter must be NULL.
SPI_SETSCREENREADER	Windows 95 only: Indicates whether a screen review utility is running. The uiParam parameter specifies TRUE for on, or FALSE for off.
SPI_SETSCREENSAVEACTIVE	Sets the state of the screen saver. The uiParam parameter specifies TRUE to activate screen saving, or FALSE to deactivate it.
SPI_SETSCREENSAVETIMEOUT	Sets the screen saver time-out value to the value of the uiParam parameter. This value is the amount of time, in seconds, that the system must be idle before the screen saver activates.
SPI_SETSERIALKEYS	Windows 95 only: Sets the parameters of the SerialKeys accessibility feature. The pvParam parameter must point to a SERIALKEYS structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(SERIALKEYS).
SPI_SETSHOWSOUNDS	Sets the ShowSounds accessibility feature as on or off. The uiParam parameter specifies TRUE for on, or FALSE for off.
SPI_SETSNAPTODEFBUTTON	Windows NT only: Enables or disables the snap-to-default-button feature. If enabled, the mouse cursor automatically moves to the default button, such as “OK” or “Apply”, of a dialog box. Set the uiParam parameter to TRUE to enable the feature, or FALSE to disable it.
SPI_SETSOUNDSENTRY	Sets the parameters of the SoundSentry accessibility feature. The pvParam parameter must point to a SOUNDSENTRY structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(SOUNDSENTRY).
SPI_SETSTICKYKEYS	Sets the parameters of the StickyKeys accessibility feature. The pvParam parameter must point to a STICKYKEYS structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(STICKYKEYS).
SPI_SETTOGGLEKEYS	Sets the parameters of the ToggleKeys accessibility feature. The pvParam parameter must point to a TOGGLEKEYS structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(TOGGLEKEYS).
SPI_SETWHEELSCROLLLINES	Windows NT only: Sets the number of lines to scroll when the mouse wheel is rotated. The number of lines is set from the uiParam parameter. The number of lines is the suggested number of lines to scroll when the mouse wheel is rolled without using modifier keys. If the number is 0, then no scrolling should occur. If the number of lines to scroll is greater than the number of lines viewable, and in particular if it is WHEEL_PAGESCROLL (#defined as UINT_MAX), the scroll operation should be interpreted as clicking once in the page down or page up regions of the scroll bar.
SPI_SETWORKAREA	Sets the size of the work area. The work area is the portion of the screen not obscured by the taskbar. The pvParam parameter must point to the RECT structure that contains the coordinates of the work area.
uiParam

Depends on the system parameter being queried or set. For more information about systemwide parameters, see the uiAction parameter. If not otherwise indicated, specify zero.

pvParam

Depends on the system parameter being queried or set. For more information about systemwide parameters, see the uiAction parameter. If not otherwise indicated, specify NULL.

fWinIni

If a system parameter is being set, specifies whether the user profile is to be updated, and if so, whether the WM_SETTINGCHANGE message is to be broadcast to all top-level windows to notify them of the change. This parameter can be zero or can be one of the following values:

Value	Action
SPIF_UPDATEINIFILE	Writes the new system-wide parameter setting to the user profile.
SPIF_SENDCHANGE	Broadcasts the WM_SETTINGCHANGE message after updating the user profile.
SPIF_SENDWININICHANGE	Same as SPIF_SENDCHANGE.
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.

Remarks

This function is intended for use with applications, such as the Control Panel, that allow the user to customize the Windows environment.

A keyboard layout name should be derived from the hexadecimal value of the language identifier corresponding to the layout. For example, U.S. English has a language identifier of 0x0409, so the primary U.S. English layout is named “00000409.” Variants of U.S. English layout, such as the Dvorak layout, are named “00010409,” “00020409” and so on. For a list of the primary language identifiers and sublanguage identifiers that make up a language identifier, see the MAKELANGID macro.

See Also

ACCESSTIMEOUT, ANIMATIONINFO, FILTERKEYS, GetLastError, GetSystemMetrics, HIGHCONTRAST, ICONMETRICS, LOGFONT, MAKELANGID, MINIMIZEDMETRICS, mouse_event, MOUSEKEYS, NONCLIENTMETRICS, RECT, SERIALKEYS, SOUNDSENTRY, STICKYKEYS, TOGGLEKEYS, TrackMouseEvent WM_SETTINGCHANGE


SystemTimeToFileTime

The SystemTimeToFileTime function converts a system time to a file time.

BOOL SystemTimeToFileTime(

CONST SYSTEMTIME *lpSystemTime,	// address of system time to convert
LPFILETIME lpFileTime	// address of buffer for converted file time
);
Parameters

lpSystemTime

Points to a SYSTEMTIME structure that contains the time to be converted.

The wDayOfWeek member of the SYSTEMTIME structure is ignored.

lpFileTime

Points to a FILETIME structure to receive the converted system time.

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.

See Also

DosDateTimeToFileTime, FILETIME, FileTimeToDosDateTime, FileTimeToSystemTime, SYSTEMTIME


SystemTimeToTzSpecificLocalTime

The SystemTimeToTzSpecificLocalTime function converts a Coordinated Universal Time (UTC) to a specified time zone’s corresponding local time.

BOOL SystemTimeToTzSpecificLocalTime(

LPTIME_ZONE_INFORMATION lpTimeZoneInformation,	// pointer to time zone of interest
LPSYSTEMTIME lpUniversalTime,	// pointer to universal time of interest
LPSYSTEMTIME lpLocalTime	// pointer to structure to receive local time
);
Parameters

lpTimeZoneInformation

Pointer to a TIME_ZONE_INFORMATION structure that specifies the time zone of interest.

If lpTimeZoneInformation is NULL, the function uses the currently active time zone.

lpUniversalTime

Pointer to a SYSTEMTIME structure that specifies a UTC. The function converts this universal time to the specified time zone’s corresponding local time.

lpLocalTime

Pointer to a SYSTEMTIME structure that receives the local time information.

Return Values

If the function succeeds, the return value is nonzero, and the function sets the members of the SYSTEMTIME structure pointed to by lpLocalTime to the appropriate local time values.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The SystemTimeToTzSpecificLocalTime function works in Windows NT. If called in Windows 95, the function fails, and returns FALSE.

See Also

GetSystemTime, GetTimeZoneInformation, SYSTEMTIME, TIME_ZONE_INFORMATION


TabbedTextOut

The TabbedTextOut function writes a character string at a specified location, expanding tabs to the values specified in an array of tab-stop positions. Text is written in the currently selected font.

LONG TabbedTextOut(

HDC hDC,	// handle of device context
int X,	// x-coordinate of starting position
int Y,	// y-coordinate of starting position
LPCTSTR lpString,	// address of string
int nCount,	// number of characters in string
int nTabPositions,	// number of tabs in array
LPINT lpnTabStopPositions,	// address of array for tab positions
int nTabOrigin	// x-coordinate for tab expansion
);
Parameters

hDC

Identifies the device context.

X

Specifies the x-coordinate of the starting point of the string, in logical units.

Y

Specifies the y-coordinate of the starting point of the string, in logical units.

lpString

Points to the character string to draw. The string does not need to be zero-terminated, since nCount specifies the length of the string.

nCount

Specifies the number of characters in the string.

nTabPositions

Specifies the number of values in the array of tab-stop positions.

lpnTabStopPositions

Points to an array containing the tab-stop positions, in device units. The tab stops must be sorted in increasing order; the smallest x-value should be the first item in the array.

Windows 95: A tab stop can be specified as a negative value, which causes text to be right-aligned on the tab stop rather than left-aligned.

nTabOrigin

Specifies the x-coordinate of the starting position from which tabs are expanded, in logical units.

Return Values

If the function succeeds, the return value is the dimensions, in logical units, of the string. The height is in the high-order word and the width is in the low-order word.

Remarks

If the nTabPositions parameter is zero and the lpnTabStopPositions parameter is NULL, tabs are expanded to eight times the average character width.

If nTabPositions is 1, the tab stops are separated by the distance specified by the first value in the lpnTabStopPositions array.

If the lpnTabStopPositions array contains more than one value, a tab stop is set for each value in the array, up to the number specified by nTabPositions.

The nTabOrigin parameter allows an application to call the TabbedTextOut function several times for a single line. If the application calls TabbedTextOut more than once with the nTabOrigin set to the same value each time, the function expands all tabs relative to the position specified by nTabOrigin.

By default, the current position is not used or updated by the TabbedTextOut function. If an application needs to update the current position when it calls TabbedTextOut, the application can call the SetTextAlign function with the wFlags parameter set to TA_UPDATECP. When this flag is set, Windows ignores the X and Y parameters on subsequent calls to the TabbedTextOut function, using the current position instead.

See Also

DrawText, GetTabbedTextExtent, GrayString, SetTextAlign, TextOut


TerminateProcess

The TerminateProcess function terminates the specified process and all of its threads.

BOOL TerminateProcess(

HANDLE hProcess,	// handle to the process
UINT uExitCode	// exit code for the process
);
Parameters

hProcess

Identifies the process to terminate.

Windows NT: The handle must have PROCESS_TERMINATE access. For more information, see Process Objects.

uExitCode

Specifies the exit code for the process and for all threads terminated as a result of this call. Use the GetExitCodeProcess function to retrieve the process’s exit value. Use the GetExitCodeThread function to retrieve a thread’s exit value.

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.

Remarks

The TerminateProcess function is used to unconditionally cause a process to exit. Use it only in extreme circumstances. The state of global data maintained by dynamic-link libraries (DLLs) may be compromised if TerminateProcess is used rather than ExitProcess.

TerminateProcess causes all threads within a process to terminate, and causes a process to exit, but DLLs attached to the process are not notified that the process is terminating.

Terminating a process causes the following:

1.	All of the object handles opened by the process are closed.

2.	All of the threads in the process terminate their execution.

3.	The state of the process object becomes signaled, satisfying any threads that had been waiting for the process to terminate.

4.	The states of all threads of the process become signaled, satisfying any threads that had been waiting for the threads to terminate.

5.	The termination status of the process changes from STILL_ACTIVE to the exit value of the process.

Terminating a process does not cause child processes to be terminated.

Terminating a process does not necessarily remove the process object from the system. A process object is deleted when the last handle to the process is closed.

See Also

ExitProcess, OpenProcess, GetExitCodeProcess, GetExitCodeThread


TerminateThread

The TerminateThread function terminates a thread.

BOOL TerminateThread(

HANDLE hThread,	// handle to the thread
DWORD dwExitCode	// exit code for the thread
);
Parameters

hThread

Identifies the thread to terminate.

Windows NT: The handle must have THREAD_TERMINATE access. For more information, see Thread Objects.

dwExitCode

Specifies the exit code for the thread. Use the GetExitCodeThread function to retrieve a thread’s exit value.

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.

Remarks

TerminateThread is used to cause a thread to exit. When this occurs, the target thread has no chance to execute any user-mode code and its initial stack is not deallocated. DLLs attached to the thread are not notified that the thread is terminating.

TerminateThread is a dangerous function that should only be used in the most extreme cases. You should call TerminateThread only if you know exactly what the target thread is doing, and you control all of the code that the target thread could possibly be running at the time of the termination. For example, TerminateThread can result in the following problems:

•	If the target thread owns a critical section, the critical section will not be released.

•	If the target thread is executing certain kernel32 calls when it is terminated, the kernel32 state for the thread’s process could be inconsistent.

•	If the target thread is manipulating the global state of a shared DLL, the state of the DLL could be destroyed, affecting other users of the DLL.

A thread cannot protect itself against TerminateThread, other than by controlling access to its handles. The thread handle returned by the CreateThread and CreateProcess functions has THREAD_TERMINATE access, so any caller holding one of these handles can terminate your thread.

If the target thread is the last thread of a process when this function is called, the thread’s process is also terminated.

The state of the thread object becomes signaled, releasing any other threads that had been waiting for the thread to terminate. The thread’s termination status changes from STILL_ACTIVE to the value of the dwExitCode parameter.

Terminating a thread does not necessarily remove the thread object from the system. A thread object is deleted when the last thread handle is closed.

See Also

CreateProcess, CreateThread, ExitThread, GetExitCodeThread


TextOut

The TextOut function writes a character string at the specified location, using the currently selected font.

BOOL TextOut(

HDC hdc,	// handle of device context
int nXStart,	// x-coordinate of starting position
int nYStart,	// y-coordinate of starting position
LPCTSTR lpString,	// address of string
int cbString	// number of characters in string
);
Parameters

hdc

Identifies the device context.

nXStart

Specifies the logical x-coordinate of the reference point that Windows uses to align the string.

nYStart

Specifies the logical y-coordinate of the reference point that Windows uses to align the string.

lpString

Points to the string to be drawn. The string does not need to be zero-terminated, since cbString specifies the length of the string.

cbString

Specifies the number of characters in the string.

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.

Remarks

The interpretation of the reference point depends on the current text-alignment mode. An application can retrieve this mode by calling the GetTextAlign function; an application can alter this mode by calling the SetTextAlign function.

By default, the current position is not used or updated by this function. However, an application can call the SetTextAlign function with the fMode parameter set to TA_UPDATECP to permit Windows to use and update the current position each time the application calls TextOut for a specified device context. When this flag is set, Windows ignores the nXStart and nYStart parameters on subsequent TextOut calls.

When the TextOut function is placed inside a path bracket, the system generates a path for the TrueType text that includes each character plus its character box. The region generated is the character box minus the text, rather than the text itself. You can obtain the region enclosed by the outline of the TrueType text by setting the background mode to transparent before placing the TextOut function in the path bracket. Following is sample code that demonstrates this procedure.

// Obtain the window's client rectangle

GetClientRect(hwnd, &r);

// THE FIX: by setting the background mode

// to transparent, the region is the text itself

// SetBkMode(hdc, TRANSPARENT);

// Bracket begin a path

BeginPath(hdc);

// Send some text out into the world

TextOut(hdc, r.left, r.top, "Defenestration can be hazardous", 4);

// Bracket end a path

EndPath(hdc);

// Derive a region from that path

SelectClipPath(hdc, RGN_AND);

// This generates the same result as SelectClipPath()

// SelectClipRgn(hdc, PathToRegion(hdc));

// Fill the region with grayness

FillRect(hdc, &r, GetStockObject(GRAY_BRUSH));

See Also

GetTextAlign, SetTextAlign, TabbedTextOut


TileWindows [Now Supported on Windows NT]
TileWindows

[Now Supported on Windows NT]

The TileWindows function tiles the specified windows, or the child windows of the specified parent window.

WORD WINAPI TileWindows(

HWND hwndParent,	// handle of parent window
UINT wHow,	// types of windows not to arrange
CONST RECT *lpRect,	// rectangle to arrange windows in
UINT cKids,	// number of windows to arrange
const HWND FAR *lpKids	// array of window handles
);
Parameters

hwndParent

Identifies the parent window. If this parameter is NULL, the desktop window is assumed.

wHow

Specifies the types of windows not to arrange, and whether to tile vertically or horizontally. This parameter can be one of the following values combined with zero or more of the values listed with the CascadeWindows function:

Value	Meaning
MDITILE_HORIZONTAL	Tiles windows horizontally.
MDITILE_VERTICAL	Tiles windows vertically.
lpRect

Points to a SMALL_RECT structure that specifies the rectangular area, in screen coordinates, within which the windows are arranged. If this parameter is NULL, the client area of the parent window is used.

cKids

Specifies the number of elements in the array specified by the lpKids parameter. This parameter is ignored if lpKids is NULL.

lpKids

Points to an array of window handles identifying the windows to arrange. If this parameter is NULL, the child windows of the specified parent window (or of the desktop window) are arranged.

Return Values

If the function succeeds, the return value is the number of windows arranged.

If the function fails, the return value is zero.

See Also

CascadeWindows, SMALL_RECT


TimerProc

The TimerProc function is an application-defined callback function that processes WM_TIMER messages.

VOID CALLBACK TimerProc(

HWND hwnd,	// handle of window for timer messages
UINT uMsg,	// WM_TIMER message
UINT idEvent,	// timer identifier
DWORD dwTime	// current system time
);
Parameters

hwnd

Identifies the window associated with the timer.

uMsg

Specifies the WM_TIMER message.

idEvent

Specifies the timer’s identifier.

dwTime

Specifies the number of milliseconds that have elapsed since Windows was started. This is the value returned by the GetTickCount function.

Return Values

This function does not return a value.

Remarks

TimerProc is a placeholder for the application-defined function name.

See Also

GetTickCount, KillTimer, SetTimer, WM_TIMER


TlsAlloc

The TlsAlloc function allocates a thread local storage (TLS) index. Any thread of the process can subsequently use this index to store and retrieve values that are local to the thread.

DWORD TlsAlloc(VOID)

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is a TLS index.

If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

Remarks

The threads of the process can use the TLS index in subsequent calls to the TlsFree, TlsSetValue, or TlsGetValue functions.

TLS indexes are typically allocated during process or dynamic-link library (DLL) initialization. Once allocated, each thread of the process can use a TLS index to access its own TLS storage slot. To store a value in its slot, a thread specifies the index in a call to TlsSetValue. The thread specifies the same index in a subsequent call to TlsGetValue, to retrieve the stored value.

The constant TLS_MINIMUM_AVAILABLE defines the minimum number of TLS indexes available in each process. This minimum is guaranteed to be at least 64 for all systems.

TLS indexes are not valid across process boundaries. A DLL cannot assume that an index assigned in one process is valid in another process.

A DLL might use TlsAlloc, TlsSetValue, TlsGetValue, and TlsFree as follows:

1.	When a DLL attaches to a process, the DLL uses TlsAlloc to allocate a TLS index. The DLL then allocates some dynamic storage and uses the TLS index in a call to TlsSetValue to store the address in the TLS slot. This concludes the per-thread initialization for the initial thread of the process. The TLS index is stored in a global or static variable of the DLL.

2.	Each time the DLL attaches to a new thread of the process, the DLL allocates some dynamic storage for the new thread and uses the TLS index in a call to TlsSetValue to store the address in the TLS slot. This concludes the per-thread initialization for the new thread.

3.	Each time an initialized thread makes a DLL call requiring the data in its dynamic storage, the DLL uses the TLS index in a call to TlsGetValue to retrieve the address of the dynamic storage for that thread.

For additional information on thread local storage, see Thread Local Storage.

See Also

TlsFree, TlsGetValue, TlsSetValue


TlsFree

The TlsFree function releases a thread local storage (TLS) index, making it available for reuse.

BOOL TlsFree(

DWORD dwTlsIndex	// TLS index to free
);
Parameters

dwTlsIndex

Specifies a TLS index that was allocated by the TlsAlloc 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.

Remarks

If the threads of the process have allocated dynamic storage and used the TLS index to store pointers to this storage, they should free the storage before calling TlsFree. The TlsFree function does not free any dynamic storage that has been associated with the TLS index. It is expected that DLLs call this function (if at all) only during their process detach routine.

For a brief discussion of typical uses of the TLS functions, see the Remarks section of the TlsAlloc function.

See Also

TlsAlloc, TlsGetValue, TlsSetValue


TlsGetValue

The TlsGetValue function retrieves the value in the calling thread’s thread local storage (TLS) slot for a specified TLS index. Each thread of a process has its own slot for each TLS index.

LPVOID TlsGetValue(

DWORD dwTlsIndex	// TLS index to retrieve value for
);
Parameters

dwTlsIndex

Specifies a TLS index that was allocated by the TlsAlloc function.

Return Values

If the function succeeds, the return value is the value stored in the calling thread’s TLS slot associated with the specified index.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Note that the data stored in a TLS slot can have a value of zero. In this case, the return value is zero and GetLastError returns NO_ERROR.

Remarks

TLS indexes are typically allocated by the TlsAlloc function during process or DLL initialization. Once allocated, each thread of the process can use a TLS index to access its own TLS storage slot for that index. The storage slot for each thread is initialized to NULL. A thread specifies a TLS index in a call to TlsSetValue, to store a value in its slot. The thread specifies the same index in a subsequent call to TlsGetValue, to retrieve the stored value.

TlsSetValue and TlsGetValue were implemented with speed as the primary goal. These functions perform minimal parameter validation and error checking. In particular, this function succeeds if dwTlsIndex is in the range 0 through (TLS_MINIMUM_AVAILABLE − 1). It is up to the programmer to ensure that the index is valid.

Win32 functions that return indications of failure call SetLastError when they fail. They generally do not call SetLastError when they succeed. The TlsGetValue function is an exception to this general rule. The TlsGetValue function calls SetLastError to clear a thread’s last error when it succeeds. That allows checking for the error-free retrieval of NULL values.

See Also

GetLastError, SetLastError, TlsAlloc, TlsFree, TlsSetValue


TlsSetValue

The TlsSetValue function stores a value in the calling thread’s thread local storage (TLS) slot for a specified TLS index. Each thread of a process has its own slot for each TLS index.

BOOL TlsSetValue(

DWORD dwTlsIndex,	// TLS index to set value for
LPVOID lpTlsValue	// value to be stored
);
Parameters

dwTlsIndex

Specifies a TLS index that was allocated by the TlsAlloc function.

lpTlsValue

Specifies the value to be stored in the calling thread’s TLS slot specified by dwTlsIndex.

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.

Remarks

TLS indexes are typically allocated by the TlsAlloc function during process or DLL initialization. Once allocated, each thread of the process can use a TLS index to access its own TLS storage slot for that index. The storage slot for each thread is initialized to NULL. A thread specifies a TLS index in a call to TlsSetValue, to store a value in its slot. The thread specifies the same index in a subsequent call to TlsGetValue, to retrieve the stored value.

TlsSetValue and TlsGetValue were implemented with speed as the primary goal. These functions perform minimal parameter validation and error checking. In particular, this function succeeds if dwTlsIndex is in the range 0 through (TLS_MINIMUM_AVAILABLE − 1). It is up to the programmer to ensure that the index is valid.

See Also

TlsAlloc, TlsFree, TlsGetValue


ToAscii

The ToAscii function translates the specified virtual-key code and keyboard state to the corresponding Windows character or characters. The function translates the code using the input language and physical keyboard layout identified by the given keyboard layout handle.

int ToAscii(

UINT uVirtKey,	// virtual-key code
UINT uScanCode,	// scan code
PBYTE lpKeyState,	// address of key-state array
LPWORD lpChar,	// buffer for translated key
UINT uFlags	// active-menu flag
);
Parameters

uVirtKey

Specifies the virtual-key code to be translated.

uScanCode

Specifies the hardware scan code of the key to be translated. The high-order bit of this value is set if the key is up (not pressed).

lpKeyState

Points to a 256-byte array that contains the current keyboard state. Each element (byte) in the array contains the state of one key. If the high-order bit of a byte is set, the key is down (pressed).

The low bit, if set, indicates that the key is toggled on. In this function, only the toggle bit of the CAPS LOCK key is relevant. The toggle state of the NUM LOCK and SCROLL LOCK keys is ignored.

lpChar

Points to the buffer that will receive the translated Windows character or characters.

uFlags

Specifies whether a menu is active. This parameter must be 1 if a menu is active, or 0 otherwise.

Return Values

If the specified key is a dead key, the return value is negative. Otherwise, it is one of the following values:

Value	Meaning
0	The specified virtual key has no translation for the current state of the keyboard.
1	One Windows character was copied to the buffer.
2	Two characters were copied to the buffer. This usually happens when a dead-key character (accent or diacritic) stored in the keyboard layout cannot be composed with the specified virtual key to form a single character.
Remarks

The parameters supplied to the ToAscii function might not be sufficient to translate the virtual-key code, because a previous dead key is stored in the keyboard layout.

Typically, ToAscii performs the translation based on the virtual-key code. In some cases, however, bit 15 of the uScanCode parameter may be used to distinguish between a key press and a key release. The scan code is used for translating ALT+number key combinations.

Although NUM LOCK is a toggle key that affects keyboard behavior, ToAscii ignores the toggle setting (the low bit) of lpKeyState (VK_NUMLOCK, because the uVirtKey parameter alone is sufficient to distinguish the cursor movement keys (VK_HOME, VK_INSERT, and so on) from the numeric keys (VK_DECIMAL, VK_NUMPAD0 - VK_NUMPAD9).

See Also

OemKeyScan, ToUnicode, VkKeyScan


ToAsciiEx [Now Supported on Windows NT]
ToAsciiEx

[Now Supported on Windows NT]

The ToAsciiEx function translates the specified virtual-key code and keyboard state to the corresponding Windows character or characters. The function translates the code using the input language and physical keyboard layout identified by the given keyboard layout handle.

int ToAsciiEx(

UINT uVirtKey,	// virtual-key code
UINT uScanCode,	// scan code
PBYTE lpKeyState,	// address of key-state array
LPWORD lpChar,	// buffer for translated key
UINT uFlags,	// active-menu flag
HKL dwhkl	// keyboard layout handle
);
Parameters

uVirtKey

Specifies the virtual-key code to be translated.

uScanCode

Specifies the hardware scan code of the key to be translated. The high-order bit of this value is set if the key is up (not pressed).

lpKeyState

Points to a 256-byte array that contains the current keyboard state. Each element (byte) in the array contains the state of one key. If the high-order bit of a byte is set, the key is down (pressed).

The low bit, if set, indicates that the key is toggled on. In this function, only the toggle bit of the CAPS LOCK key is relevant. The toggle state of the NUM LOCK and SCROLL LOCK keys is ignored.

lpChar

Points to the buffer that will receive the translated Windows character or characters.

uFlags

Specifies whether a menu is active. This parameter must be 1 if a menu is active, zero otherwise.

dwhkl

Identifies the keyboard layout to use to translate the given code. This parameter can be any keyboard layout handle previously returned by the LoadKeyboardLayout function.

Return Values

If the specified key is a dead key, the return value is negative. Otherwise, it is one of the following values:

Value	Meaning
0	The specified virtual key has no translation for the current state of the keyboard.
1	One Windows character was copied to the buffer.
2	Two characters were copied to the buffer. This usually happens when a dead-key character (accent or diacritic) stored in the keyboard layout cannot be composed with the specified virtual key to form a single character.
Remarks

The parameters supplied to the ToAsciiEx function might not be sufficient to translate the virtual-key code, because a previous dead key is stored in the keyboard layout.

Typically, ToAsciiEx performs the translation based on the virtual-key code. In some cases, however, bit 15 of the uScanCode parameter may be used to distinguish between a key press and a key release. The scan code is used for translating ALT+number key combinations.

Although NUM LOCK is a toggle key that affects keyboard behavior, ToAsciiEx ignores the toggle setting (the low bit) of lpKeyState (VK_NUMLOCK, because the uVirtKey parameter alone is sufficient to distinguish the cursor movement keys (VK_HOME, VK_INSERT, and so on) from the numeric keys (VK_DECIMAL, VK_NUMPAD0 - VK_NUMPAD9).

See Also

LoadKeyboardLayout, MapVirtualKeyEx, OemKeyScan, ToAscii, VkKeyScan


ToUnicode

The ToUnicode function translates the specified virtual-key code and keyboard state to the corresponding Unicode character or characters.

int ToUnicode(

UINT wVirtKey,	// virtual-key code
UINT wScanCode,	// scan code
PBYTE lpKeyState,	// address of key-state array
LPWSTR pwszBuff,	// buffer for translated key
int cchBuff,	// size of translated key buffer
UINT wFlags	// set of function-conditioning flags
);
Parameters

wVirtKey

Specifies the virtual-key code to be translated.

wScanCode

Specifies the hardware scan code of the key to be translated. The high-order bit of this value is set if the key is up.

lpKeyState

Points to a 256-byte array that contains the current keyboard state. Each element (byte) in the array contains the state of one key. If the high-order bit of a byte is set, the key is down.

pwszBuff

Points to the buffer that receives the translated Unicode character or characters.

cchBuff

Specifies the size in characters of the buffer pointed to by the pwszBuff parameter.

wFlags

A set of bit flags that condition the behavior of the function. Set bit 0 if a menu is active. Bits 1 through 31 are reserved.

Return Values

The function returns one of the following values:

Value	Meaning
− 1	The specified virtual key is a dead-key character (accent or diacritic). This value is returned regardless of the keyboard layout, even if several characters have been typed and are stored in the keyboard state. If possible, even with Unicode keyboard layouts, the function has written a spacing version of the dead-key character to the buffer specified by pwszBuffer. For example, the function writes the character SPACING ACUTE (0x00B4), rather than the character NON_SPACING ACUTE (0x0301).
0	The specified virtual key has no translation for the current state of the keyboard. Nothing was written to the buffer specified by pwszBuffer.
1	One character was written to the buffer specified by pwszBuffer.
2 or more	Two or more characters were written to the buffer specified by pwszBuff. The most common cause for this is that a dead-key character (accent or diacritic) stored in the keyboard layout could not be combined with the specified virtual key to form a single character.
Remarks

The parameters supplied to the ToUnicode function might not be sufficient to translate the virtual-key code because a previous dead key is stored in the keyboard layout.

Typically, ToUnicode performs the translation based on the virtual-key code. In some cases, however, bit 15 of the wScanCode parameter can be used to distinguish between a key press and a key release.

See Also

ToAscii, VkKeyScan


ToUnicodeEx

The ToUnicodeEx function translates the specified virtual-key code and keyboard state to the corresponding Unicode character or characters.

int ToUnicodeEx(

UINT wVirtKey,	// virtual-key code
UINT wScanCode,	// scan code
PBYTE lpKeyState,	// address of key-state array
LPWSTR pwszBuff,	// buffer for translated key
int cchBuff,	// size of translated key buffer
UINT wFlags,	// set of function-conditioning flags
HKL dwhkl	// keyboard layout handle
);
Parameters

wVirtKey

Specifies the virtual-key code to be translated.

wScanCode

Specifies the hardware scan code of the key to be translated. The high-order bit of this value is set if the key is up.

lpKeyState

Points to a 256-byte array that contains the current keyboard state. Each element (byte) in the array contains the state of one key. If the high-order bit of a byte is set, the key is down.

pwszBuff

Points to the buffer that receives the translated Unicode character or characters.

cchBuff

Specifies the size in characters of the buffer pointed to by the pwszBuff parameter.

wFlags

A set of bit flags that condition the behavior of the function. Set bit 0 if a menu is active. Bits 1 through 31 are reserved.

dwhkl

Identifies the keyboard layout to use to translate the given code. This parameter can be any keyboard layout handle previously returned by the LoadKeyboardLayout function.

Return Values

The function returns one of the following values:

Value	Meaning
− 1	The specified virtual key is a dead-key character (accent or diacritic). This value is returned regardless of the keyboard layout, even if several characters have been typed and are stored in the keyboard state. If possible, even with Unicode keyboard layouts, the function has written a spacing version of the dead-key character to the buffer specified by pwszBuffer. For example, the function writes the character SPACING ACUTE (0x00B4), rather than the character NON_SPACING ACUTE (0x0301).
0	The specified virtual key has no translation for the current state of the keyboard. Nothing was written to the buffer specified by pwszBuffer.
1	One character was written to the buffer specified by pwszBuffer.
2 or more	Two or more characters were written to the buffer specified by pwszBuff. The most common cause for this is that a dead-key character (accent or diacritic) stored in the keyboard layout could not be combined with the specified virtual key to form a single character.
Remarks

The parameters supplied to the ToUnicodeEx function might not be sufficient to translate the virtual-key code because a previous dead key is stored in the keyboard layout.

Typically, ToUnicodeEx performs the translation based on the virtual-key code. In some cases, however, bit 15 of the wScanCode parameter can be used to distinguish between a key press and a key release.

See Also

ToAscii, ToUnicode, VkKeyScan


TrackMouseEvent [New - Windows NT]
TrackMouseEvent

[New - Windows NT]

The TrackMouseEvent function posts messages when the mouse pointer leaves a window or hovers over a window for a specified amount of time.

BOOL TrackMouseEvent(

LPTRACKMOUSEEVENT lpEventTrack	// pointer to a TRACKMOUSEEVENT structure
);
Parameters

lpEventTrack

Pointer to a TRACKMOUSEEVENT structure.

Return Values

If the function succeeds, the return value is nonzero .

If the function fails, return value is zero. To get extended error information, call GetLastError.

The messages that the function can post are the following:

Message	Meaning
WM_MOUSEHOVER	The mouse hovered over the client area of the window for the period of time specified in a prior call to TrackMouseEvent. Hover tracking stops when this message is generated. The application must call TrackMouseEvent again if it requires further tracking of mouse hover behavior.
WM_MOUSELEAVE	The mouse left the client area of the window specified in a prior call to TrackMouseEvent. All tracking requested by TrackMouseEvent is canceled when this message is generated. The application must call TrackMouseEvent when the mouse re-enters its window if it requires further tracking of mouse hover behavior.
Remarks

The mouse pointer is considered to be hovering when it stays within a specified rectangle for a specified period of time. Call SystemParametersInfo and use the values SPI_GETMOUSEHOVERWIDTH, SPI_GETMOUSEHOVERHEIGHT, and SPI_GETMOUSEHOVERTIME to retrieve the size of the rectangle and the time.

See Also

SystemParametersInfo, TRACKMOUSEEVENT


TrackPopupMenu

The TrackPopupMenu function displays a shortcut menu at the specified location and tracks the selection of items on the menu. The shortcut menu can appear anywhere on the screen.

BOOL TrackPopupMenu(

HMENU hMenu,	// handle of shortcut menu
UINT uFlags,	// screen-position and mouse-button flags
int x,	// horizontal position, in screen coordinates
int y,	// vertical position, in screen coordinates
int nReserved,	// reserved, must be zero
HWND hWnd,	// handle of owner window
CONST RECT *prcRect	// points to RECT that specifies no-dismissal area
);
Parameters

hMenu

Identifies the shortcut menu to be displayed. The handle can be obtained by calling CreatePopupMenu to create a new shortcut menu, or by calling GetSubMenu to retrieve the handle of a submenu associated with an existing menu item.

uFlags

A set of bit flags that specify function options.

Use one of the following bit flag constants to specify how the function positions the popup menu horizontally:

Value	Meaning
TPM_CENTERALIGN	If this flag is set, the function centers the shortcut menu horizontally relative to the coordinate specified by the x parameter.
TPM_LEFTALIGN	If this flag is set, the function positions the shortcut menu so that its left side is aligned with the coordinate specified by the x parameter.
TPM_RIGHTALIGN	Positions the shortcut menu so that its right side is aligned with the coordinate specified by the x parameter.
Use one of the following bit flag constants to specify which mouse button the shortcut menu tracks:

Value	Meaning
TPM_LEFTBUTTON	If this flag is set, the shortcut menu tracks the left mouse button.
TPM_RIGHTBUTTON	If this flag is set, the shortcut menu tracks the right mouse button
x

Specifies the horizontal location of the shortcut menu, in screen coordinates.

y

Specifies the vertical location of the shortcut menu, in screen coordinates.

nReserved

Reserved; must be zero.

hWnd

Identifies the window that owns the shortcut menu. This window receives all messages from the menu. The window does not receive a WM_COMMAND message from the menu until the function returns.

prcRect

Points to a RECT structure that specifies the portion of the screen in which the user can select without dismissing the shortcut menu. If this parameter is NULL, the shortcut menu is dismissed if the user clicks outside the shortcut menu.

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.

See Also

CreatePopupMenu, GetSubMenu, RECT, WM_COMMAND


TrackPopupMenuEx [Now Supported on Windows NT]
TrackPopupMenuEx

[Now Supported on Windows NT]

The TrackPopupMenuEx function displays a shortcut menu at the specified location and tracks the selection of items on the shortcut menu. The shortcut menu can appear anywhere on the screen.

BOOL TrackPopupMenuEx(

HMENU hmenu,
UINT fuFlags,
int x,
int y,
HWND hwnd,
LPTPMPARAMS lptpm
);
Parameters

hmenu

Handle to the shortcut menu to be displayed. This handle can be obtained by calling the CreatePopupMenu function to create a new shortcut menu or by calling the GetSubMenu function to retrieve the handle to a submenu associated with an existing menu item.

fuFlags

Positioning and other options. This parameter, which can be zero or more of the values listed with the TrackPopupMenu function, may also include one of the following values:

Value	Meaning
TPM_HORIZONTAL	If the menu cannot be shown at the specified location without overlapping the excluded rectangle, the system tries to accommodate the requested horizontal alignment before the requested vertical alignment.
TPM_VERTICAL	If the menu cannot be shown at the specified location without overlapping the excluded rectangle, the system tries to accommodate the requested vertical alignment before the requested horizontal alignment.
The excluded rectangle is a portion of the screen that the menu should not overlap; it is specified by lptpm.

x

Horizontal location of the shortcut menu, in screen coordinates.

y

Vertical location of the shortcut menu, in screen coordinates.

hwnd

Handle to the window that owns the shortcut menu. This window receives all messages from the menu. The window does not receive a WM_COMMAND message from the menu until the function returns.

lptpm

Pointer to a TPMPARAMS structure that specifies an area of the screen the menu should not overlap. This parameter can be NULL.

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, use the GetLastError function.

See Also

CreatePopupMenu, GetSubMenu, TPMPARAMS, TrackPopupMenu, WM_COMMAND


TransactNamedPipe

The TransactNamedPipe function combines into a single network operation the functions that write a message to and read a message from the specified named pipe.

BOOL TransactNamedPipe(

HANDLE hNamedPipe,	// handle of named pipe
LPVOID lpInBuffer,	// address of write buffer
DWORD nInBufferSize,	// size of the write buffer, in bytes
LPVOID lpOutBuffer,	// address of read buffer
DWORD nOutBufferSize,	// size of read buffer, in bytes
LPDWORD lpBytesRead,	// address of variable for bytes actually read
LPOVERLAPPED lpOverlapped	// address of overlapped structure
);
Parameters

hNamedPipe

Identifies the named pipe returned by the CreateNamedPipe or CreateFile function.

lpInBuffer

Points to the buffer containing the data written to the pipe.

nInBufferSize

Specifies the size, in bytes, of the write buffer.

lpOutBuffer

Points to the buffer that receives the data read from the pipe.

nOutBufferSize

Specifies the size, in bytes, of the read buffer.

lpBytesRead

Points to the variable that receives the number of bytes read from the pipe.

If lpOverlapped is NULL, lpBytesRead cannot be NULL.

If lpOverlapped is not NULL, lpBytesRead can be NULL. If this is an overlapped read operation, you can get the number of bytes read by calling GetOverlappedResult. If hNamedPipe is associated with an I/O completion port, you can get the number of bytes read by calling GetQueuedCompletionStatus.

lpOverlapped

Points to an OVERLAPPED structure. This structure is required if hNamedPipe was opened with FILE_FLAG_OVERLAPPED.

If hNamedPipe was opened with FILE_FLAG_OVERLAPPED, the lpOverlapped parameter must not be NULL. It must point to a valid OVERLAPPED structure. If hNamedPipe was created with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function can incorrectly report that the opeation is complete.

If hNamePipe was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, TransactNamedPipe is executed as an overlapped operation. The OVERLAPPED structure should contain a manual-reset event object (which can be created by using the CreateEvent function). If the operation cannot be completed immediately, TransactNamedPipe returns FALSE and GetLastError returns ERROR_IO_PENDING. In this situation, the event object is set to the nonsignaled state before TransactNamedPipe returns, and it is set to the signaled state when the transaction has finished. For more information about overlapped operations, see Pipes.

If hNamedPipe was not opened with FILE_FLAG_OVERLAPPED, TransactNamedPipe does not return until the operation is complete.

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.

Remarks

TransactNamedPipe fails if the server did not create the pipe as a message-type pipe or if the pipe handle is not in message-read mode. For example, if a client is running on the same machine as the server and uses the \\.\pipe\pipename format to open the pipe, the pipe is opened in byte mode by the named pipe file system (NPFS). If the client uses the form \\server\pipe\pipename, the redirector opens the pipe in message mode. A byte mode pipe handle can be changed to message-read mode with the SetNamedPipeHandleState function.

The function cannot be completed successfully until data is written into the buffer specified by the lpOutBuffer parameter. The lpOverlapped parameter is available to enable the calling thread to perform other tasks while the operation is executing in the background.

If the message to be read is longer than the buffer specified by the nOutBufferSize parameter, TransactNamedPipe returns FALSE and the GetLastError function returns ERROR_MORE_DATA. The remainder of the message can be read by a subsequent call to ReadFile, ReadFileEx, or PeekNamedPipe.

See Also

CreateEvent, CreateFile, CreateNamedPipe, GetOverlappedResult, GetQueuedCompletionStatus, PeekNamedPipe, ReadFile, ReadFileEx, SetNamedPipeHandleState, OVERLAPPED


TranslateAccelerator

The TranslateAccelerator function processes accelerator keys for menu commands. The function translates a WM_KEYDOWN or WM_SYSKEYDOWN message to a WM_COMMAND or WM_SYSCOMMAND message (if there is an entry for the key in the specified accelerator table) and then sends the WM_COMMAND or WM_SYSCOMMAND message directly to the appropriate window procedure. TranslateAccelerator does not return until the window procedure has processed the message.

int TranslateAccelerator(

HWND hWnd,	// handle of destination window
HACCEL hAccTable,	// handle of accelerator table
LPMSG lpMsg	// address of structure with message
);
Parameters

hWnd

Identifies the window whose messages are to be translated.

hAccTable

Identifies an accelerator table. The accelerator table must have been loaded by a call to the LoadAccelerators function or created by a call to the CreateAcceleratorTable function.

lpMsg

Points to an MSG structure that contains message information retrieved from the calling thread’s message queue by using the GetMessage or PeekMessage function.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

To differentiate the message that this function sends from messages sent by menus or controls, the high-order word of the wParam parameter of the WM_COMMAND or WM_SYSCOMMAND message contains the value 1.

Accelerator key combinations used to select items from the window menu are translated into WM_SYSCOMMAND messages; all other accelerator key combinations are translated into WM_COMMAND messages.

When TranslateAccelerator returns a nonzero value and the message is translated, the application should not use the TranslateMessage function to process the message again.

An accelerator need not correspond to a menu command.

If the accelerator command corresponds to a menu item, the application is sent WM_INITMENU and WM_INITMENUPOPUP messages, as if the user were trying to display the menu. However, these messages are not sent if any of the following conditions exist:

•	The window is disabled.

•	The menu item is disabled.

•	The accelerator key combination does not correspond to an item on the window menu and the window is minimized.

•	A mouse capture is in effect. For information about mouse capture, see the SetCapture function.

If the specified window is the active window and no window has the keyboard focus (which is generally the case if the window is minimized), TranslateAccelerator translates WM_SYSKEYUP and WM_SYSKEYDOWN messages instead of WM_KEYUP and WM_KEYDOWN messages.

If an accelerator keystroke occurs that corresponds to a menu item when the window that owns the menu is minimized, TranslateAccelerator does not send a WM_COMMAND message. However, if an accelerator keystroke occurs that does not match any of the items in the window’s menu or in the window menu, the function sends a WM_COMMAND message, even if the window is minimized.

See Also

CreateAcceleratorTable, GetMessage, LoadAccelerators, MSG, PeekMessage, SetCapture, TranslateMessage, WM_COMMAND, WM_INITMENU, WM_INITMENUPOPUP, WM_KEYDOWN, WM_SYSKEYDOWN, WM_SYSCOMMAND


TranslateCharsetInfo [Now Supported on Windows NT]
TranslateCharsetInfo

[Now Supported on Windows NT]

The TranslateCharsetInfo function translates based on the specified character set, code page, or font signature value, setting all members of the destination structure to appropriate values.

UINT TranslateCharsetInfo(

DWORD FAR *lpSrc,
LPCHARSETINFO lpCs,
DWORD dwFlags
);
Parameters

lpSrc

Address or value as defined by the dwFlags parameter. If dwFlags is TCI_SRCFONTSIG, this parameter is the address of the fsCsb member of a FONTSIGNATURE structure. Otherwise, this parameter is a 32-bit value.

lpCs

Pointer to a CHARSETINFO structure that receives the translated character set information.

dwFlags

Translation flags. This parameter can be one of the following values:

Value	Meaning
TCI_SRCCHARSET	Source contains the character set value in the low word, and zero in the high word.
TCI_SRCCODEPAGE	Source is a code-page value in the low word and zero in the high word.
TCI_SRCFONTSIG	Source is the code-page bitfield portion of a FONTSIGNATURE structure. On input this should have only one Windows code-page bit set, either for an ANSI code-page value or for a common ANSI and OEM value (for OEM values, bits 32-63 must be clear.). On output this will have only one bit set. If the TCI_SRCFONTSIG value is given, the lpSrc parameter must be the address of the codepage bit field. If any other TCI_ value is given, the lpSrc parameter must be a value not an address.
Return Values

If the function succeeds, it returns a nonzero value.

If the function fails, it returns zero. To get extended error information, call GetLastError.

See Also

CHARSETINFO, FONTSIGNATURE


TranslateMDISysAccel

The TranslateMDISysAccel function processes accelerator keystrokes for window menu commands of the multiple document interface (MDI) child windows associated with the specified MDI client window. The function translates WM_KEYUP and WM_KEYDOWN messages to WM_SYSCOMMAND messages and sends them to the appropriate MDI child windows.

BOOL TranslateMDISysAccel(

HWND hWndClient,	// handle of MDI client window
LPMSG lpMsg	// address of structure with message data
);
Parameters

hWndClient

Identifies the MDI client window.

lpMsg

Points to a message retrieved by using the GetMessage or PeekMessage function. The message must be an MSG structure and contain message information from the application’s message queue.

Return Values

If the message is translated into a system command, the return value is nonzero.

If the message is not translated into a system command, the return value is zero.

See Also

GetMessage, PeekMessage, TranslateAccelerator, MSG, WM_KEYDOWN, WM_KEYUP, WM_SYSCOMMAND


TranslateMessage

The TranslateMessage function translates virtual-key messages into character messages. The character messages are posted to the calling thread’s message queue, to be read the next time the thread calls the GetMessage or PeekMessage function.

BOOL TranslateMessage(

CONST MSG *lpMsg	// address of structure with message
);
Parameters

lpMsg

Points to an MSG structure that contains message information retrieved from the calling thread’s message queue by using the GetMessage or PeekMessage function.

Return Values

If the message is translated (that is, a character message is posted to the thread’s message queue), the return value is nonzero.

If the message is not translated (that is, a character message is not posted to the thread’s message queue), the return value is zero.

Windows NT: The TranslateMessage function returns a nonzero value for function and arrow keys as well as for character and digit keys.

Remarks

The TranslateMessage function does not modify the message pointed to by the lpMsg parameter.

WM_KEYDOWN and WM_KEYUP combinations produce a WM_CHAR or WM_DEADCHAR message. WM_SYSKEYDOWN and WM_SYSKEYUP combinations produce a WM_SYSCHAR or WM_SYSDEADCHAR message.

TranslateMessage produces WM_CHAR messages only for keys that are mapped to ASCII characters by the keyboard driver.

If applications process virtual-key messages for some other purpose, they should not call TranslateMessage. For instance, an application should not call TranslateMessage if the TranslateAccelerator function returns TRUE.

See Also

GetMessage, PeekMessage, TranslateAccelerator, WM_CHAR, WM_DEADCHAR, WM_KEYDOWN, WM_KEYUP, WM_SYSCHAR, WM_SYSDEADCHAR, WM_SYSKEYDOWN, WM_SYSKEYUP


TransmitCommChar

The TransmitCommChar function transmits a specified character ahead of any pending data in the output buffer of the specified communications device.

BOOL TransmitCommChar(

HANDLE hFile,	// handle of communications device
char cChar	// character to transmit
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

cChar

Specifies the character to be transmitted.

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.

Remarks

The TransmitCommChar function is useful for sending an interrupt character (such as a CTRL+C) to a host system.

If the device is not transmitting, TransmitCommChar cannot be called repeatedly. Once TransmitCommChar places a character in the output buffer, the character must be transmitted before the function can be called again. If the previous character has not yet been sent, TransmitCommChar returns an error.

Character transmission is subject to normal flow control and handshaking. This function can only be called synchronously.

See Also

CreateFile, WaitCommEvent


TryEnterCriticalSection [New - Windows NT]
TryEnterCriticalSection

[New - Windows NT]

The TryEnterCriticalSection function attempts to enter a critical section without blocking. If the call is successful, the calling thread takes ownership of the critical section.

BOOL TryEnterCriticalSection(

LPCRITICAL_SECTION lpCriticalSection	// pointer to critical section object
);
Parameters

lpCriticalSection

Specifies the critical section object.

Return Values

If the critical section is successfully entered or the current thread already owns the critical section, the return value is nonzero.

If another thread already owns the critical section, the return value is zero.

Remarks

The threads of a single process can use a critical section object for mutual-exclusion synchronization. The process is responsible for allocating the memory used by a critical section object, which it can do by declaring a variable of type CRITICAL_SECTION. Before using a critical section, some thread of the process must call the InitializeCriticalSection function to initialize the object.

To enable mutually exclusive use of a shared resource, each thread calls the EnterCriticalSection or TryEnterCriticalSection function to request ownership of the critical section before executing any section of code that uses the protected resource. The difference is that TryEnterCriticalSection returns immediately, regardless of whether it obtained ownership of the critical section, while EnterCriticalSection blocks until the thread can take ownership of the critical section. When it has finished executing the protected code, the thread uses the LeaveCriticalSection function to relinquish ownership, enabling another thread to become the owner and gain access to the protected resource. The thread must call LeaveCriticalSection once for each time that it entered the critical section.

Any thread of the process can use the DeleteCriticalSection function to release the system resources that were allocated when the critical section object was initialized. After this function has been called, the critical section object can no longer be used for synchronization.

See Also

DeleteCriticalSection, EnterCriticalSection, InitializeCriticalSection, LeaveCriticalSection


UInt32x32To64

The UInt32x32To64 function multiplies two unsigned 32-bit integers, returning an unsigned 64-bit integer result. The function performs optimally on all Win32 platforms.

DWORDLONG UInt32x32To64(

DWORD Multiplier,	// specifies first unsigned 32-bit integer for the multiplication
DWORD Multiplicand	// specifies second unsigned 32-bit integer for the multiplication
);
Parameters

Multiplier

Specifies the first unsigned 32-bit integer for the multiplication.

Multiplicand

Specifies the second unsigned 32-bit integer for the multiplication.

Return Values

The return value is the unsigned 64-bit integer result of the multiplication.

Remarks

This function is implemented on all platforms by optimal inline code: a single multiply instruction that returns a 64-bit result.

Please note that the function’s return value is a 64-bit value, not a LARGE_INTEGER structure.

See Also

Int32x32To64


UndeleteFile

The UndeleteFile function is an application-defined callback function that File Manager calls when the user chooses the Undelete command from the File Manager File menu.

DWORD APIENTRY UndeleteFile(

HWND hwndOwner,	// handle of File Manager window
LPSTR lpszDir	// address of name of initial directory
);
Parameters

hwndOwner

Identifies the File Manager window. An “undelete” dynamic-link library (DLL) should use this handle to specify the owner window for any dialog box or message box the DLL may display.

lpszDir

Points to a null-terminated string that contains the name of the initial directory.

Return Values

If the function succeeds, the return value is one of the following:

Value	Meaning
−l	An error occurred.
IDOK	A file was undeleted. File Manager repaints its windows.
IDCANCEL	No file was undeleted.


UnhandledExceptionFilter

The UnhandledExceptionFilter function passes unhandled exceptions to the debugger, if the process is being debugged. Otherwise, it optionally displays an Application Error message box and causes the exception handler to be executed. This function can be called only from within the filter expression of a try-except exception handler.

LONG UnhandledExceptionFilter(

STRUCT _EXCEPTION_POINTERS *ExceptionInfo	// address of exception info
);
Parameters

ExceptionInfo

Points to an EXCEPTION_POINTERS structure containing a description of the exception and the processor context at the time of the exception. This pointer is the return value of a call to the GetExceptionInformation function.

Return Values

The function returns one of the following values:

Value	Meaning
EXCEPTION_CONTINUE_SEARCH	The process is being debugged, so the exception should be passed (as second chance) to the application’s debugger.
EXCEPTION_EXECUTE_HANDLER	If the SEM_NOGPFAULTERRORBOX flag was specified in a previous call to SetErrorMode, no Application Error message box is displayed. The function returns control to the exception handler, which is free to take any appropriate action.
Remarks

If the process is not being debugged, the function displays an Application Error message box, depending on the current error mode. The default behavior is to display the dialog box, but this can be disabled by specifying SEM_NOGPFAULTERRORBOX in a call to the SetErrorMode function.

The system uses UnhandledExceptionFilter internally to handle exceptions that occur during process and thread creation.

See Also

EXCEPTION_POINTERS, GetExceptionInformation, SetErrorMode, SetUnhandledExceptionFilter, UnhandledExceptionFilter


UnhookWindowsHook

The UnhookWindowsHook function is obsolete, but is provided for compatibility with 16-bit versions of Windows. For Win32-based applications, use the UnhookWindowsHookEx function.


UnhookWindowsHookEx

The UnhookWindowsHookEx function removes a hook procedure installed in a hook chain by the SetWindowsHookEx function.

BOOL UnhookWindowsHookEx(

HHOOK hhk	// handle of hook procedure to remove
);
Parameters

hhk

Identifies the hook to be removed. This parameter is a hook handle obtained by a previous call to SetWindowsHookEx.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The hook procedure can be in the state of being called by another thread even after UnhookWindowsHookEx returns. If the hook procedure is not being called concurrently, the hook procedure is removed immediately before UnhookWindowsHookEx returns.

See Also

SetWindowsHookEx, UnhookWindowsHook


UnionRect

The UnionRect function creates the union of two rectangles. The union is the smallest rectangle that contains both source rectangles.

BOOL UnionRect(

LPRECT lprcDst,	// address of structure for union
CONST RECT *lprcSrc1,	// address of structure with first rectangle
CONST RECT *lprcSrc2	// address of structure with second rectangle
);
Parameters

lprcDst

Points to the RECT structure that will receive a rectangle containing the rectangles pointed to by the lprcSrc1 and lprcSrc2 parameters.

lprcSrc1

Points to the RECT structure that contains the first source rectangle.

lprcSrc2

Points to the RECT structure that contains the second source rectangle.

Return Values

If the specified structure contains a nonempty rectangle, the return value is nonzero.

If the specified structure does not contain a nonempty rectangle, the return value is zero. To get extended error information, call GetLastError.

Remarks

Windows ignores the dimensions of an empty rectangle — that is, a rectangle in which all coordinates are set to zero, so that it has no height or no width.

See Also

InflateRect, IntersectRect, OffsetRect, RECT


UnloadKeyboardLayout

The UnloadKeyboardLayout function removes a keyboard layout.

BOOL UnloadKeyboardLayout(

HKL hkl	// handle of keyboard layout
);
Parameters

hkl

Identifies the keyboard layout to unload.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. The function can fail for the following reasons:

•	An invalid keyboard layout handle was passed.

•	The layout was preloaded.

•	The layout is in use.

Remarks

Windows 95: UnloadKeyboardLayout cannot unload the system default keyboard layout. This ensures that an appropriate character set is always available for the user to type commands for the shell or names for the file system.

Windows NT: UnloadKeyboardLayout can unload the system default keyboard layout.

See Also

ActivateKeyboardLayout, GetKeyboardLayoutName, LoadKeyboardLayout


UnlockFile

The UnlockFile function unlocks a region in an open file. Unlocking a region enables other processes to access the region.

BOOL UnlockFile(

HANDLE hFile,	// handle of file to unlock
DWORD dwFileOffsetLow,	// low-order word of lock region offset
DWORD dwFileOffsetHigh,	// high-order word of lock region offset
DWORD nNumberOfBytesToUnlockLow,	// low-order word of length to unlock
DWORD nNumberOfBytesToUnlockHigh	// high-order word of length to unlock
);
Parameters

hFile

Identifies a file that contains a region locked with LockFile. The file handle must have been created with either GENERIC_READ or GENERIC_WRITE access to the file.

dwFileOffsetLow

Specifies the low-order word of the starting byte offset in the file where the locked region begins.

dwFileOffsetHigh

Specifies the high-order word of the starting byte offset in the file where the locked region begins.

nNumberOfBytesToUnlockLow

Specifies the low-order word of the length of the byte range to be unlocked.

nNumberOfBytesToUnlockHigh

Specifies the high-order word of the length of the byte range to be unlocked.

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.

Remarks

Unlocking a region of a file releases a lock on the file. The region to unlock must correspond exactly to an existing locked region. For example, two adjacent regions of a file cannot be locked separately and then unlocked as a single region that spans both locked regions.

A process should not be terminated with a portion of a file locked and a file that has locked regions should not be closed.

This function works on a file allocation table (FAT) − based file system only if the operating system is running SHARE.EXE.

See Also

CreateFile, LockFile


UnlockFileEx

The UnlockFileEx function unlocks a previously locked byte range in an open file.

BOOL UnlockFileEx(

HANDLE hFile,	// handle of file to unlock
DWORD dwReserved,	// reserved, must be set to zero
DWORD nNumberOfBytesToUnlockLow,	// low order 32-bits of length to unlock
DWORD nNumberOfBytesToUnlockHigh,	// high order 32-bits of length to unlock
LPOVERLAPPED lpOverlapped	// addr. of struct. with unlock region start offset
);
Parameters

hFile

Identifies an open handle to a file that is to have an existing locked region unlocked. The handle must have been created with either GENERIC_READ or GENERIC_WRITE access to the file.

dwReserved

Reserved parameter; must be zero.

nNumberOfBytesToUnlockLow

Specifies the low-order 32-bits of the length of the byte range to unlock.

nNumberOfBytesToUnlockHigh

Specifies the high-order 32-bits of the length of the byte range to unlock.

lpOverlapped

Points to an OVERLAPPED structure that the function uses with the unlocking request. This structure contains the file offset of the beginning of the unlock range.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero or NULL. To get extended error information, call GetLastError.

Remarks

Unlocking a region of a file releases a previously acquired lock on a file. The region to unlock must correspond exactly to an existing locked region. Two adjacent regions of a file can not be locked separately and then unlocked using a single region that spans both locked regions.

If a process terminates with a portion of a file locked or closes a file that has outstanding locks, the behavior is not specified.

See Also

CreateFile, LockFile, LockFileEx, OVERLAPPED, UnlockFile


UnlockResource

The UnlockResource function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. It is not necessary for Win32-based applications to unlock resources.

See Also

LoadResource, LockResource


UnlockSegment

The UnlockSegment function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. Segments have no meaning in the 32-bit environment.


UnlockServiceDatabase

The UnlockServiceDatabase function unlocks a service control manager database by releasing the specified lock.

BOOL UnlockServiceDatabase(

SC_LOCK ScLock	// service control manager database lock to be released
);
Parameters

ScLock

Specifies a lock obtained from a previous call to the LockServiceDatabase 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.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_INVALID_SERVICE_LOCK	The specified lock is invalid.
See Also

LockServiceDatabase, QueryServiceLockStatus


UnmapViewOfFile

The UnmapViewOfFile function unmaps a mapped view of a file from the calling process’s address space.

BOOL UnmapViewOfFile(

LPCVOID lpBaseAddress	// address where mapped view begins
);
Parameters

lpBaseAddress

Points to the base address of the mapped view of a file that is to be unmapped. This value must be identical to the value returned by a previous call to the MapViewOfFile or MapViewOfFileEx function.

Return Values

If the function succeeds, the return value is nonzero, and all dirty pages within the specified range are written “lazily” to disk.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Although an application may close the file handle used to create a file mapping object, the system holds the corresponding file open until the last view of the file is unmapped.

Windows 95: Files for which the last view has not yet been unmapped are held open with the same sharing restrictions as the original file handle.

Windows NT: Files for which the last view has not yet been unmapped are held open with no sharing restrictions.

See Also

MapViewOfFile, MapViewOfFileEx


UnpackDDElParam

The UnpackDDElParam function unpacks a DDE lParam value received from a posted DDE message.

BOOL UnpackDDElParam(

UINT msg,	// posted DDE message
LONG lParam,	// lParam of posted DDE message
PUINT puiLo,	// address of low-order word of lParam
PUINT puiHi	// address of high-order word of lParam
);
Parameters

msg

Specifies the posted DDE message.

lParam

Specifies the lParam parameter of the posted DDE message that was received. The application must free the memory object specified by the lParam parameter by calling the FreeDDElParam function.

puiLo

Points to a value the function will set to the low-order word of lParam.

puiHi

Points to a value the function will set to the high-order word of lParam.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

PackDDElParam eases the porting of 16-bit DDE applications to 32-bit DDE applications.

See Also

FreeDDElParam, PackDDElParam, ReuseDDElParam


UnrealizeObject

The UnrealizeObject function resets a logical palette. It directs the system to realize the palette as though it had not previously been realized. The next time the application calls the RealizePalette function for the specified palette, the system completely remaps the logical palette to the system palette.

If hgdiobj is a brush, UnrealizeObject does nothing, and the function returns TRUE. Use SetBrushOrgEx to set the origin of a brush.

BOOL UnrealizeObject(

HGDIOBJ hgdiobj	// logical palette handle
);
Parameters

hgdiobj

Identifies the logical palette to be reset.

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.

Remarks

The UnrealizeObject function should not be used with stock objects. The default palette, obtained by calling GetStockObject(DEFAULT_PALETTE), is a stock object.

A palette identified by hgdiobj can be the currently selected palette of a device context.

See Also

GetStockObject, RealizePalette, SetBrushOrgEx


UnregisterClass

The UnregisterClass function removes a window class, freeing the memory required for the class.

BOOL UnregisterClass(

LPCTSTR lpClassName,	// address of class name string
HINSTANCE hInstance	// handle of application instance
);
Parameters

lpClassName

Points to a null-terminated string or is an integer atom. If this parameter is an integer atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value less than 0xC000, must be in the low-order word of lpClassName; the high-order word must be zero.

If lpClassName is a string, it specifies the window class name. This class name must have been registered by a previous call to the RegisterClass function. System global classes, such as dialog box controls, cannot be unregistered.

hInstance

Identifies the instance of the module that created the class.

Return Values

If the function succeeds, the return value is nonzero.

If the class could not be found or if a window still exists that was created with the class, the return value is zero. To get extended error information, call GetLastError.

Remarks

Before calling this function, an application must destroy all windows created with the specified class.

All window classes that an application registers are unregistered when it terminates.

See Also

GlobalAddAtom, RegisterClass


UnregisterHotKey

The UnregisterHotKey function frees a hot key previously registered by the calling thread.

BOOL UnregisterHotKey(

HWND hWnd,	// window associated with hot key
int id	// identifier of hot key
);
Parameters

hWnd

Identifies the window associated with the hot key to be freed. This parameter should be NULL if the hot key is not associated with a window.

id

Specifies the identifier of the hot key to be freed.

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.

See Also

RegisterHotKey, WM_HOTKEY


UpdateColors

The UpdateColors function updates the client area of the specified device context by remapping the current colors in the client area to the currently realized logical palette.

BOOL UpdateColors(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

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.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

An inactive window with a realized logical palette may call UpdateColors as an alternative to redrawing its client area when the system palette changes.

The UpdateColors function typically updates a client area faster than redrawing the area. However, because UpdateColors performs the color translation based on the color of each pixel before the system palette changed, each call to this function results in the loss of some color accuracy.

This function must be called soon after a WM_PALETTECHANGED message is received.

See Also

GetDeviceCaps, RealizePalette


UpdateICMRegKey

The UpdateICMRegKey function installs, removes, or queries registry entries that identify ICC color profiles or color-matching DLLs. The function carries out the action specified by the nCommand parameter.

BOOL UpdateICMRegKey(

DWORD dwReserved,
DWORD CMID,
LPTSTR lpszFileName,
UINT nCommand
);
Parameters

dwReserved

Reserved; must be zero.

CMID

Profile identifier of the color-matching DLL to use with the profile.

lpszFileName

Pointer to a zero-terminated string that specifies the filename of an ICC color profile or address of a DEVMODE structure, depending on the value of nCommand.

nCommand

Action flag. This parameter can have one of the following values:

ICM_ADDPROFILE	Adds the ICC profile to the ICM branch in the registry.
ICM_DELETEPROFILE	Deletes the ICC profile from the ICM branch in the registry.
ICM_QUERYPROFILE	Determines if the profile is in the ICM branch of the registry.
ICM_SETDEFAULTPROFILE	Makes the profile first among equals.
ICM_REGISTERICMATCHER	Equates a CMID to a color-matching DLL.
ICM_UNREGISTERICMATCHER	Removes the reference between CMID and a color-matching DLL.
ICM_QUERYMATCH	Determines if a profile exists based on the DEVMODE pointed to by lpszFileName.
Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

GDI uses the registry to keep track of ICC profiles installed in the system (listed in the registry). Although not required, if ICC profiles are copied to a local directory, they should be placed in the Color directory in the Windows System directory.

See Also

DEVMODE


UpdateResource

The UpdateResource function adds, deletes, or replaces a resource in an executable file.

BOOL UpdateResource(

HANDLE hUpdate,	// update-file handle
LPCTSTR lpType,	// address of resource type to update
LPCTSTR lpName,	// address of resource name to update
WORD wLanguage,	// language identifier of resource
LPVOID lpData,	// address of resource data
DWORD cbData	// length of resource data, in bytes
);
Parameters

hUpdate

Specifies an update-file handle. This handle is returned by the BeginUpdateResource function.

lpType

Points to a null-terminated string specifying the resource type to be updated. This parameter can also be an integer value passed to the MAKEINTRESOURCE macro, or it can be one of the following predefined resource types:

Value	Meaning
RT_ACCELERATOR	Accelerator table
RT_ANICURSOR	Animated cursor
RT_ANIICON	Animated icon
RT_BITMAP	Bitmap resource
RT_CURSOR	Hardware-dependent cursor resource
RT_DIALOG	Dialog box
RT_FONT	Font resource
RT_FONTDIR	Font directory resource
RT_GROUP_CURSOR	Hardware-independent cursor resource
RT_GROUP_ICON	Hardware-independent icon resource
RT_ICON	Hardware-dependent icon resource
RT_MENU	Menu resource
RT_MESSAGETABLE	Message-table entry
RT_RCDATA	Application-defined resource (raw data)
RT_STRING	String-table entry
RT_VERSION	Version resource
lpName

Points to a null-terminated string specifying the name of the resource to be updated. This parameter can also be an integer value passed to the MAKEINTRESOURCE macro.

wLanguage

Specifies the language identifier of the resource to be updated. For a list of the primary language identifiers and sublanguage identifiers that make up a language identifier, see the MAKELANGID macro

lpData

Points to the resource data to be inserted into the executable file. If the resource is one of the predefined types, the data must be valid and properly aligned. Note that this is the raw binary data stored in the executable file, not the data provided by LoadIcon, LoadString, or other resource-specific load functions. All data containing strings or text must be in Unicode format; lpData must not point to ANSI data.

If lpData is NULL, the specified resource is deleted from the executable file.

cbData

Specifies the size, in bytes, of the resource data at lpData.

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.

Remarks

An application can use UpdateResource repeatedly to make changes to the resource data. Each call to UpdateResource contributes to an internal list of additions, deletions, and replacements but does not actually write the data to the executable file. The application must use the EndUpdateResource function to write the accumulated changes to the executable file.

See Also

BeginUpdateResource, EndUpdateResource, LoadIcon, LoadString, LockResource, MAKEINTRESOURCE, MAKELANGID, SizeofResource


UpdateWindow

The UpdateWindow function updates the client area of the specified window by sending a WM_PAINT message to the window if the window’s update region is not empty. The function sends a WM_PAINT message directly to the window procedure of the specified window, bypassing the application queue. If the update region is empty, no message is sent.

BOOL UpdateWindow(

HWND hWnd	// handle of window
);
Parameters

hWnd

Identifies the window to be updated.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

See Also

ExcludeUpdateRgn, GetUpdateRect, GetUpdateRgn, InvalidateRect, InvalidateRgn, WM_PAINT


ValidateRect

The ValidateRect function validates the client area within a rectangle by removing the rectangle from the update region of the specified window.

BOOL ValidateRect(

HWND hWnd,	// handle of window
CONST RECT *lpRect	// address of validation rectangle coordinates
);
Parameters

hWnd

Identifies the window whose update region is to be modified. If this parameter is NULL, Windows invalidates and redraws all windows and sends the WM_ERASEBKGND and WM_NCPAINT messages to the window procedure before the function returns.

lpRect

Points to a RECT structure that contains the client coordinates of the rectangle to be removed from the update region. If this parameter is NULL, the entire client area is removed.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The BeginPaint function automatically validates the entire client area. Neither the ValidateRect nor ValidateRgn function should be called if a portion of the update region must be validated before the next WM_PAINT message is generated.

Windows continues to generate WM_PAINT messages until the current update region is validated.

See Also

BeginPaint, InvalidateRect, InvalidateRgn, RECT, ValidateRgn, WM_PAINT


ValidateRgn

The ValidateRgn function validates the client area within a region by removing the region from the current update region of the specified window.

BOOL ValidateRgn(

HWND hWnd,	// handle of window
HRGN hRgn	// handle of valid region
);
Parameters

hWnd

Identifies the window whose update region is to be modified.

hRgn

Identifies a region that defines the area to be removed from the update region. If this parameter is NULL, the entire client area is removed.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The specified region must have been created by a region function. The region coordinates are assumed to be client coordinates.

The BeginPaint function automatically validates the entire client area. Neither the ValidateRect nor ValidateRgn function should be called if a portion of the update region must be validated before the next WM_PAINT message is generated.

See Also

BeginPaint, ExcludeUpdateRgn, InvalidateRect, InvalidateRgn, ValidateRect, WM_PAINT


VerFindFile

The VerFindFile function determines where to install a file based on whether it locates another version of the file in the system. The values VerFindFile returns in the specified buffers are used in a subsequent call to VerInstallFile.

As with the other file installation functions, VerFindFile will only work with Win32 file images. 16-bit Windows file images are not supported.

DWORD VerFindFile(

DWORD dwFlags,	// bit flags that condition function behavior
LPTSTR szFileName,	// file to be installed
LPTSTR szWinDir,	// Windows directory
LPTSTR szAppDir,	// directory where related files are being installed
LPTSTR szCurDir,	// receives path of directory where file is currently installed
PUINT lpuCurDirLen,	// size of string in szCurDir
LPTSTR szDestDir,	// receives path of recommended destination directory
PUINT lpuDestDirLen	// size of string in szDestDir
);
Parameters

dwFlags

Contains a bitmask of flags. This parameter can be the following value:

Flag	Description
VFFF_ISSHAREDFILE	The source file can be shared by multiple applications. An application can use this information to determine where the file should be copied.
All other values are reserved.

szFileName

Points to the name of the file to be installed. The filename can include only the filename and extension, not a path.

szWinDir

Points to the directory in which Windows is running or will be run. This string is returned by the GetWindowsDirectory function.

szAppDir

Points to the directory where the installation program is installing a set of related files. If the installation program is installing an application, this is the directory where the application will reside. This parameter also points to the application’s current directory unless otherwise specified.

szCurDir

Points to a buffer that receives the path to a current version of the file being installed. The path is a zero-terminated string. If a current version is not installed, the buffer will contain a zero-length string. The buffer should be at least _MAX_PATH characters long, although this is not required.

lpuCurDirLen

Points to a variable that contains the length of the szCurDir buffer. This pointer must not be NULL.

When the function returns, lpuCurDirLen contains the size, in characters, of the data returned in szCurDir, including the terminating null character. If the buffer is too small to contain all the data, lpuCurDirLen will be the size of the buffer required to hold the path.

szDestDir

Points to a buffer that receives the path to the installation location recommended by VerFindFile. The path is a zero-terminated string. The buffer should be at least _MAX_PATH characters long, although this is not required.

lpuDestDirLen

Points to a variable that contains the length of the szDestDir buffer. This pointer must not be NULL.

When the function returns, lpuDestDirLen contains the size, in characters, of the data returned in szDestDir, including the terminating null character. If the buffer is too small to contain all the data, lpuDestDirLen will be the size of the buffer needed to hold the path.

Return Values

The return value is a bitmask that indicates the status of the file. It can be one or more of the following values:

Value	Meaning
VFF_CURNEDEST	The currently installed version of the file is not in the recommended destination.
VFF_FILEINUSE	Windows is using the currently installed version of the file; therefore, the file cannot be overwritten or deleted.
VFF_BUFFTOOSMALL	At least one of the buffers was too small to contain the corresponding string. An application should check the output buffers to determine which buffer was too small.
All other values are reserved.

Remarks

VerFindFile searches for a copy of the specified file by using the OpenFile function. However, it determines the system directory from the specified Windows directory, or searches the path.

If the dwFlags parameter indicates that the file is private to this application (not VFFF_ISSHAREDFILE), VerFindFile recommends installing the file in the application’s directory. Otherwise, if the system is running a shared copy of Windows, the function recommends installing the file in the Windows directory. If the system is running a private copy of Windows, the function recommends installing the file in the system directory.

See Also

GetWindowsDirectory, OpenFile, VerInstallFile


VerInstallFile

The VerInstallFile function attempts to install the specified file based on information returned from the VerFindFile function. VerInstallFile decompresses the file, if necessary, assigns a unique filename, and checks for errors, such as outdated files.

As with the other file installation functions, VerInstallFile will only work with Win32 file images. 16-bit Windows file images are not supported.

DWORD VerInstallFile(

DWORD uFlags,	// bit flags that condition function behavior
LPTSTR szSrcFileName,	// file to install
LPTSTR szDestFileName,	// new name of file to install
LPTSTR szSrcDir,	// source directory of file to install
LPTSTR szDestDir,	// directory in which to install file
LPTSTR szCurDir,	// directory where file is currently installed
LPTSTR szTmpFile,	// receives name of temporary copy of file used during installation
PUINT lpuTmpFileLen	// size of string in szTmpFile
);
Parameters

uFlags

Contains a bitmask of flags. This parameter can be one of the following values:

Flag	Description
VIFF_FORCEINSTALL	Installs the file regardless of mismatched version numbers. The function checks only for physical errors during installation.
VIFF_DONTDELETEOLD	Installs the file without deleting the previously installed file, if the previously installed file is not in the destination directory.
All other values are reserved.

szSrcFileName

Points to the name of the file to be installed. This is the filename in the directory pointed to by the szSrcDir parameter; the filename can include only the filename and extension, not a path.

szDestFileName

Points to the name VerInstallFile will give the new file upon installation. This filename may be different from the filename in the szSrcFileName directory. The new name should include only the filename and extension, not a path.

szSrcDir

Points to a buffer that contains the name of the directory where the new file is found.

szDestDir

Points to a buffer that contains the name of the directory where the new file should be installed. VerFindFile returns this value in its szDestDir parameter.

szCurDir

Points to a buffer that contains the name of the directory where the preexisting version of this file is found. VerFindFile returns this value in its szCurDir parameter.

szTmpFile

Points to a buffer that should be empty upon the initial call to VerInstallFile. The function fills the buffer with the name of a temporary copy of the source file. The buffer should be at least _MAX_PATH characters long, although this is not required.

lpuTmpFileLen

Points to a variable that contains the length of the szTmpFile buffer. This pointer must not be NULL.

When the function returns, lpuTmpFileLen contains the size, in characters, of the data returned in szTmpFile, including the terminating null character. If the buffer is too small to contain all the data, lpuTmpFileLen will be the size of the buffer required to hold the data.

Return Values

The return value is a bitmask that indicates exceptions. It can be one or more of the following values:

Value	Meaning
VIF_TEMPFILE	The temporary copy of the new file is in the destination directory. The cause of failure is reflected in other flags.
VIF_MISMATCH	The new and preexisting files differ in one or more attributes. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag set.
VIF_SRCOLD	The file to install is older than the preexisting file. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag set.
VIF_DIFFLANG	The new and preexisting files have different language or code-page values. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag set.
VIF_DIFFCODEPG	The new file requires a code page that cannot be displayed by the version of Windows currently running. This error can be overridden by calling VerInstallFile with the VIFF_FORCEINSTALL flag set.
VIF_DIFFTYPE	The new file has a different type, subtype, or operating system from the preexisting file. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag set.
VIF_WRITEPROT	The preexisting file is write protected. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag set.
VIF_FILEINUSE	The preexisting file is in use by Windows and cannot be deleted.
VIF_OUTOFSPACE	The function cannot create the temporary file due to insufficient disk space on the destination drive.
VIF_ACCESSVIOLATION	A read, create, delete, or rename operation failed due to an access violation.
VIF_SHARINGVIOLATION	A read, create, delete, or rename operation failed due to a sharing violation.
VIF_CANNOTCREATE	The function cannot create the temporary file. The specific error may be described by another flag.
VIF_CANNOTDELETE	The function cannot delete the destination file, or cannot delete the existing version of the file located in another directory. If the VIF_TEMPFILE bit is set, the installation failed, and the destination file probably cannot be deleted.
VIF_CANNOTDELETECUR	The existing version of the file could not be deleted and VIFF_DONTDELETEOLD was not specified.
VIF_CANNOTRENAME	The function cannot rename the temporary file, but already deleted the destination file.
VIF_OUTOFMEMORY	The function cannot complete the requested operation due to insufficient memory. Generally, this means the application ran out of memory attempting to expand a compressed file.
VIF_CANNOTREADSRC	The function cannot read the source file. This could mean that the path was not specified properly.
VIF_CANNOTREADDST	The function cannot read the destination (existing) files. This prevents the function from examining the file’s attributes.
VIF_BUFFTOOSMALL	The szTmpFile buffer was too small to contain the name of the temporary source file. When the function returns, lpuTmpFileLen contains the size of the buffer required to hold the filename.
All other values are reserved.

Remarks

VerInstallFile copies the file from the source directory to the destination directory. If szCurDir indicates that a previous version of the file exists on the system, VerInstallFile compares the files’ version stamp information. If the previously installed version of the file is more recent than the new version, or if the files’ attributes are significantly different, for example, if they are in different languages, then VerInstallFile returns with one or more recoverable error codes.

VerInstallFile leaves the temporary file in the destination directory. The application can either override the error or delete the temporary file. If the application overrides the error, VerInstallFile deletes the previously installed version and renames the temporary file with the original filename.

See Also

VerFindFile


VerLanguageName

The VerLanguageName function retrieves a description string for the language associated with a specified binary Microsoft language identifier.

DWORD VerLanguageName(

DWORD wLang,	// Microsoft language identifier
LPTSTR szLang,	// pointer to buffer for language description string
DWORD nSize	// size of buffer
);
Parameters

wLang

Specifies the binary Microsoft language identifier. For a complete list of the language identifiers supported by Win32, see Language Identifiers.

For example, the description string associated with the language identifier 0x040A is “Spanish (Traditional Sort)”. If the identifier is unknown, the szLang parameter points to a default string (“Language Neutral”).

szLang

Points to the buffer to receive the null-terminated string representing the language specified by the wLang parameter.

nSize

Indicates the size of the buffer, in characters, pointed to by szLang.

Return Values

If the return value is less than or equal to the buffer size, the return value is the size, in characters, of the string returned in the buffer. This value does not include the terminating null character.

If the return value is greater than the buffer size, the return value is the size of the buffer required to hold the entire string. The string is truncated to the length of the existing buffer.

If an error occurs, the return value is zero. Unknown language identifiers do not produce errors.

Remarks

Typically, an installation program uses this function to translate a language identifier returned by the VerQueryValue function. The text string may be used in a dialog box that asks the user how to proceed in the event of a language conflict.

See Also

VerQueryValue


VerQueryValue

The VerQueryValue function returns selected version information from the specified version-information resource. To retrieve the appropriate resource, the GetFileVersionInfo function must be called before VerQueryValue.

As with the other file installation functions, VerQueryValue will only work with Win32 file images. 16-bit Windows file images are not supported.

BOOL VerQueryValue(

const LPVOID pBlock,	// address of buffer for version resource
LPTSTR lpSubBlock,	// address of value to retrieve
LPVOID *lplpBuffer,	// address of buffer for version pointer
PUINT puLen	// address of version-value length buffer
);
Parameters

pBlock

Points to the buffer containing the version-information resource returned by GetFileVersionInfo.

lpSubBlock

Points to a zero-terminated string specifying which version-information value to retrieve. The string consists of names separated by backslashes (\) and can have one of the following forms:

Form	Description
\	Specifies the root block. The function retrieves a pointer to the VS_FIXEDFILEINFO structure for the version-information resource.
\VarFileInfo\Translation	Specifies the translation table in the variable information structure. The function retrieves a pointer to an array of language and character-set identifiers. An application uses these identifiers to create the name of a language-specific structure in the version-information resource.
\StringFileInfo\lang-charset\string-name	Specifies a value in a language-specific structure. The lang-charset name is a concatenation of a language and character-set identifier pair found in the translation table for the resource. The lang-charset name must be specified as a hexadecimal string. The string-name name is one of the predefined strings described in the following Remarks section.
lplpBuffer

Points to a buffer that receives a pointer to the version-information value.

puLen

Points to a buffer that receives the length, in characters, of the version-information value.

Return Values

If the specified structure exists and version information is available, the return value is nonzero. If the address of the length buffer is zero, no value is available for the specified version-information name.

If the specified name does not exist or the specified resource is not valid, the return value is zero.

Remarks

The Win32 API contains the following predefined version information strings:

CompanyName FileDescription FileVersion InternalName LegalCopyright OriginalFilename ProductName ProductVersion

The following example shows how to retrieve the FileDescription string-value from a block of version information:

VerQueryValue(pBlock,

              TEXT("\\StringFileInfo\\040904E4\\FileDescription"),

              &lpBuffer,

              &dwBytes);

Call the GetFileVersionInfoSize and GetFileVersionInfo functions to properly initialize the pBlock buffer before calling the VerQueryValue function.

See Also

GetFileVersionInfo, GetFileVersionInfoSize, VS_FIXEDFILEINFO, VS_VERSION_INFO


VirtualAlloc

The VirtualAlloc function reserves or commits a region of pages in the virtual address space of the calling process. Memory allocated by this function is automatically initialized to zero.

LPVOID VirtualAlloc(

LPVOID lpAddress,	// address of region to reserve or commit
DWORD dwSize,	// size of region
DWORD flAllocationType,	// type of allocation
DWORD flProtect	// type of access protection
);
Parameters

lpAddress

Specifies the desired starting address of the region to allocate. If the memory is being reserved, the specified address is rounded down to the next 64-kilobyte boundary. If the memory is already reserved and is being committed, the address is rounded down to the next page boundary. To determine the size of a page on the host computer, use the GetSystemInfo function. If this parameter is NULL, the system determines where to allocate the region.

dwSize

Specifies the size, in bytes, of the region. If the lpAddress parameter is NULL, this value is rounded up to the next page boundary. Otherwise, the allocated pages include all pages containing one or more bytes in the range from lpAddress to (lpAddress+dwSize). This means that a 2-byte range straddling a page boundary causes both pages to be included in the allocated region.

flAllocationType

Specifies the type of allocation. You can specify any combination of the following flags:

Flag	Meaning
MEM_COMMIT	Allocates physical storage in memory or in the paging file on disk for the specified region of pages.
	An attempt to commit an already committed page will not cause the function to fail. This means that a range of committed or decommitted pages can be committed without having to worry about a failure.
MEM_RESERVE	Reserves a range of the process’s virtual address space without allocating any physical storage. The reserved range cannot be used by any other allocation operations (the malloc function, the LocalAlloc function, and so on) until it is released. Reserved pages can be committed in subsequent calls to the VirtualAlloc function.
MEM_TOP_DOWN	Allocates memory at the highest possible address.
flProtect

Specifies the type of access protection. If the pages are being committed, any one of the following flags can be specified, along with the PAGE_GUARD and PAGE_NOCACHE protection modifier flags, as desired:

Flag	Meaning
PAGE_READONLY	Enables read access to the committed region of pages. An attempt to write to the committed region results in an access violation. If the system differentiates between read-only access and execute access, an attempt to execute code in the committed region results in an access violation.
PAGE_READWRITE	Enables both read and write access to the committed region of pages.
PAGE_EXECUTE	Enables execute access to the committed region of pages. An attempt to read or write to the committed region results in an access violation.
PAGE_EXECUTE_READ	Enables execute and read access to the committed region of pages. An attempt to write to the committed region results in an access violation.
PAGE_EXECUTE_READWRITE	Enables execute, read, and write access to the committed region of pages.
PAGE_GUARD	Pages in the region become guard pages. Any attempt to read from or write to a guard page causes the operating system to raise a STATUS_GUARD_PAGE exception and turn off the guard page status. Guard pages thus act as a one-shot access alarm. The PAGE_GUARD flag is a page protection modifier. An application uses it with one of the other page protection flags, with one exception: It cannot be used with PAGE_NOACCESS. When an access attempt leads the operating system to turn off guard page status, the underlying page protection takes over. If a guard page exception occurs during a system service, the service typically returns a failure status indicator.
PAGE_NOACCESS	Disables all access to the committed region of pages. An attempt to read from, write to, or execute in the committed region results in an access violation exception, called a general protection (GP) fault.
PAGE_NOCACHE	Allows no caching of the committed regions of pages. The hardware attributes for the physical memory should be specified as “no cache.” This is not recommended for general usage. It is useful for device drivers; for example, mapping a video frame buffer with no caching. This flag is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.
Return Values

If the function succeeds, the return value is the base address of the allocated region of pages.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

VirtualAlloc can perform the following operations:

•	Commit a region of pages reserved by a previous call to the VirtualAlloc function.

•	Reserve a region of free pages.

•	Reserve and commit a region of free pages.

You can use VirtualAlloc to reserve a block of pages and then make additional calls to VirtualAlloc to commit individual pages from the reserved block. This enables a process to reserve a range of its virtual address space without consuming physical storage until it is needed.

Each page in the process’s virtual address space is in one of three states:

State	Meaning
Free	The page is not committed or reserved and is not accessible to the process. VirtualAlloc can reserve, or simultaneously reserve and commit, a free page.
Reserved	The range of addresses cannot be used by other allocation functions, but the page is not accessible and has no physical storage associated with it. VirtualAlloc can commit a reserved page, but it cannot reserve it a second time. The VirtualFree function can release a reserved page, making it a free page.
Committed	Physical storage is allocated for the page, and access is controlled by a protection code. The system initializes and loads each committed page into physical memory only at the first attempt to read or write to that page. When the process terminates, the system releases the storage for committed pages. VirtualAlloc can commit an already committed page. This means that you can commit a range of pages, regardless of whether they have already been committed, and the function will not fail. VirtualFree can decommit a committed page, releasing the page’s storage, or it can simultaneously decommit and release a committed page.
If the lpAddress parameter is not NULL, the function uses the lpAddress and dwSize parameters to compute the region of pages to be allocated. The current state of the entire range of pages must be compatible with the type of allocation specified by the flAllocationType parameter. Otherwise, the function fails and none of the pages are allocated. This compatibility requirement does not preclude committing an already committed page; see the preceding list.

The PAGE_GUARD protection modifier flag establishes guard pages. Guard pages act as one-shot access alarms. See Guard Pages.

See Also

GlobalAlloc, HeapAlloc, VirtualFree, VirtualLock, VirtualProtect, VirtualQuery


VirtualAllocEx [New - Windows NT]
VirtualAllocEx

[New - Windows NT]

The VirtualAllocEx function reserves, commits, or both, a region of memory within the virtual address space of a specified process. The function initializes the memory it allocates to zero.

The difference between the VirtualAllocEx function and the VirtualAlloc function is that VirtualAlloc allocates memory within the address space of the calling process, while VirtualAllocEx lets you specify a process.

LPVOID VirtualAllocEx(

HANDLE hProcess,	// process within which to allocate memory
LPVOID lpAddress,	// desired starting address of allocation
DWORD dwSize,	// size, in bytes, of region to allocate
DWORD flAllocationType,	// type of allocation
DWORD flProtect	// type of access protection
);
Parameters

hProcess

Handle to a process. The function allocates memory within the virtual address space of this process.

You must have PROCESS_VM_OPERATION access to the process. If you do not, the function fails.

lpAddress

Pointer that specifies a desired starting address for the region of pages that you want to allocate.

If you are reserving memory, the function rounds this address down to the nearest 64-kilobyte boundary.

If you are committing memory that is already reserved, the function rounds this address down to the nearest page boundary. To determine the size of a page on the host computer, use the GetSystemInfo function.

If lpAddress is NULL, the function determines where to allocate the region.

dwSize

Specifies the size, in bytes, of the region of memory to allocate.

If lpAddress is NULL, the function rounds dwSize up to the next page boundary.

If lpAddress is not NULL, the function allocates all pages that contain one or more bytes in the range from lpAddress to (lpAddress+dwSize). This means, for example, that a 2-byte range that straddles a page boundary causes the function to allocate both pages.

flAllocationType

A set of bit flags that specifies the type of memory allocation. You can set one or more of the following flags:

Flag	Meaning
MEM_COMMIT	The function allocates actual physical storage in memory or in the paging file on disk for the specified region of memory pages. The function initializes the memory to zero.
	An attempt to commit a memory page that is already committed does not cause the function to fail. This means that you can commit a range of pages without first determining the current commitment state of each page. If a memory page is not yet reserved, setting this flag causes the function to both reserve and commit the memory page.
MEM_RESERVE	The function reserves a range of the process’s virtual address space without allocating any actual physical storage in memory or in the paging file on disk.  Other memory allocation functions, such as malloc and LocalAlloc, cannot use a reserved range of memory until it is released.  You can commit reserved memory pages in subsequent calls to the VirtualAllocEx function.
MEM_TOP_DOWN	The function allocates memory at the highest possible address.
flProtect

A set of bit flags that specifies access protection for the region of pages you are allocating. You can specify one of the following flags, along with the PAGE_GUARD and PAGE_NOCACHE protection modifier flags, as desired:

Flag	Meaning
PAGE_READONLY	Enables read permission to the committed region of pages. An attempt to write to the committed region results in an access violation. If the system differentiates between read-only permission and execute permission, an attempt to execute code in the committed region results in an access violation.
PAGE_READWRITE	Enables both read and write permission to the committed region of pages.
PAGE_EXECUTE	Enables execute permission to the committed region of pages. An attempt to read or write to the committed region results in an access violation.
PAGE_EXECUTE_READ	Enables execute and read permission to the committed region of pages. An attempt to write to the committed region results in an access violation.
PAGE_EXECUTE_READWRITE	Enables execute, read, and write permission to the committed region of pages.
PAGE_GUARD	Pages in the region become guard pages. Any attempt to read from or write to a guard page causes the operating system to raise a STATUS_GUARD_PAGE exception and turn off the guard page status. Guard pages thus act as a one-shot access alarm. The PAGE_GUARD flag is a page protection modifier. An application uses it with one of the other page protection flags, with one exception: It cannot be used with PAGE_NOACCESS. When an access attempt leads the operating system to turn off guard page status, the underlying page protection takes over. If a guard page exception occurs during a system service, the service typically returns a failure status indicator.
PAGE_NOACCESS	Disables all access to the committed region of pages. An attempt to read from, write to, or execute in the committed region results in an access violation exception, called a general protection (GP) fault.
PAGE_NOCACHE	Allows no caching of the committed regions of pages. The hardware attributes for the physical memory should be specified as “no cache.” This is not recommended for general usage. It is useful for device drivers; for example, mapping a video frame buffer with no caching. This flag is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.
A set of bit flags that specifies access protection for the region of pages you are allocating. You can specify one of the following flags, along with the PAGE_GUARD and PAGE_NOCACHE protection modifier flags, as desired:

Return Values

If the function succeeds, the return value is the base address of the allocated region of pages.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The VirtualAllocEx function can perform the following operations:

•	Commit a region of pages reserved by a previous call to the VirtualAllocEx  function.

•	Reserve a region of free pages.

•	Reserve and commit a region of free pages.

You can use VirtualAllocEx to reserve a block of pages and then make additional calls to VirtualAllocEx to commit individual pages from the reserved block. This lets you reserve a range of a process’s virtual address space without consuming physical storage until it is needed.

Each page of memory in a process’s virtual address space is in one of three states:

State	Meaning
Free	The page is not committed or reserved and is not accessible to the process. The VirtualAllocEx function can reserve, or simultaneously reserve and commit, a free page.
Reserved	The page is reserved. The range of addresses cannot be used by other allocation functions, but the page is not accessible and has no physical storage associated with it. The VirtualAllocEx function can commit a reserved page, but it cannot reserve it a second time. You can use the VirtualFreeEx function to release a reserved page in a specified process, making it a free page.
Committed	Physical storage is allocated for the page, and access is controlled by a protection code. The system initializes and loads each committed page into physical memory only at the first attempt to read or write to that page. When the process terminates, the system releases the storage for committed pages. The VirtualAllocEx function can commit an already committed page. This means that you can commit a range of pages, regardless of whether they have already been committed, and the function will not fail. You can use the VirtualFreeEx function to decommit a committed page in a specified process, or to simultaneously decommit and free a committed page.
If the lpAddress parameter is not NULL, the function uses the lpAddress and dwSize parameters to compute the region of pages to be allocated. The current state of the entire range of pages must be compatible with the type of allocation specified by the flAllocationType parameter. Otherwise, the function fails and none of the pages is allocated. This compatibility requirement does not preclude committing an already committed page; see the preceding list.

The PAGE_GUARD protection modifier flag establishes guard pages. Guard pages act as one-shot access alarms. For more information see Guard Pages.

See Also

GlobalAlloc, HeapAlloc, VirtualAlloc, VirtualFree, VirtualFreeEx, VirtualLock, VirtualProtect, VirtualQuery


VirtualFree

The VirtualFree function releases or decommits (or both) a region of pages within the virtual address space of the calling process.

BOOL VirtualFree(

LPVOID lpAddress,	// address of region of committed pages
DWORD dwSize,	// size of region
DWORD dwFreeType	// type of free operation
);
Parameters

lpAddress

Points to the base address of the region of pages to be freed. If the dwFreeType parameter includes the MEM_RELEASE flag, this parameter must be the base address returned by the VirtualAlloc function when the region of pages was reserved.

dwSize

Specifies the size, in bytes, of the region to be freed. If the dwFreeType parameter includes the MEM_RELEASE flag, this parameter must be zero. Otherwise, the region of affected pages includes all pages containing one or more bytes in the range from the lpAddress parameter to (lpAddress+dwSize). This means that a 2-byte range straddling a page boundary causes both pages to be freed.

dwFreeType

Specifies the type of free operation. One, but not both, of the following flags can be specified:

Flag	Meaning
MEM_DECOMMIT	Decommits the specified region of committed pages.
	An attempt to decommit an uncommitted page will not cause the function to fail. This means that a range of committed or uncommitted pages can be decommitted without having to worry about a failure.
MEM_RELEASE	Releases the specified region of reserved pages. If this flag is specified, the dwSize parameter must be zero, or the function fails.
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.

Remarks

VirtualFree can perform one of the following operations:

•	Decommit a region of committed or uncommitted pages.

•	Release a region of reserved pages.

•	Decommit and release a region of committed or uncommitted pages.

To release a region of pages, the entire range of pages must be in the same state (all reserved or all committed) and the entire region originally reserved by the VirtualAlloc function must be released at the same time. If only part of the pages in the original reserved region are committed, you must first call VirtualFree to decommit the committed pages and then call VirtualFree again to release the entire block.

Pages that have been released are free pages available for subsequent allocation operations. Attempting to read from or write to a free page results in an access violation exception.

VirtualFree can decommit an uncommitted page; this means that a range of committed or uncommitted pages can be decommitted without having to worry about a failure. Decommitting a page releases its physical storage, either in memory or in the paging file on disk. If a page is decommitted but not released, its state changes to reserved, and it can be committed again by a subsequent call to VirtualAlloc. Attempting to read from or write to a reserved page results in an access violation exception.

The current state of the entire range of pages must be compatible with the type of free operation specified by the dwFreeType parameter. Otherwise, the function fails and no pages are released or decommitted.

See Also

GlobalAlloc, GlobalFree, VirtualAlloc


VirtualFreeEx [New - Windows NT]
VirtualFreeEx

[New - Windows NT]

The VirtualFreeEx function releases, decommits, or both, a region of memory within the virtual address space of a specified process.

The difference between the VirtualFreeEx function and the VirtualFree function is that VirtualFree frees memory within the address space of the calling process, while VirtualFreeEx lets you specify a process.

BOOL VirtualFreeEx(

HANDLE hProcess,	// process within which to free memory
LPVOID lpAddress,	// starting address of memory region to free
DWORD dwSize,	// size, in bytes, of memory region to free
DWORD dwFreeType	// type of free operation
);
Parameters

hProcess

Handle to a process. The function frees memory within the virtual address space of this process.

You must have PROCESS_VM_OPERATION access to this process. If you do not, the function fails.

lpAddress

Pointer to the starting address of the region of memory to free.

If the MEM_RELEASE flag is set in the dwFreeType parameter, lpAddress must be the base address returned by the VirtualAllocEx function when the region was reserved.

dwSize

Specifies the size, in bytes, of the region of memory to free.

If the MEM_RELEASE flag is set in the dwFreeType parameter, dwSize must be zero. The function frees the entire region that was reserved in the initial allocation call to VirtualAllocEx.

If the MEM_DECOMMIT flag is set, the function decommits all memory pages that contain one or more bytes in the range from the lpAddress parameter to (lpAddress+dwSize). This means, for example, that a 2-byte region of memory that straddles a page boundary causes both pages to be decommitted.

The function decommits the entire region that was reserved by VirtualAllocEx. If the following three conditions are met:

•	the MEM_DECOMMIT flag is set

•	lpAddress is the base address returned by the VirtualAllocEx function when the region was reserved

•	dwSize is zero

The entire region the enters the reserved state.

dwFreeType

Set of bit flags that specifies the type of free operation. You must set one of the following two flags:

Flag	Meaning
MEM_DECOMMIT	The function decommits the specified region of pages. The pages enter the reserved state.
	The function does not fail if you attempt to decommit an uncommitted page. This means that you can decommit a range of pages without first determining their current commitment state.
MEM_RELEASE	The function releases the specified region of pages. The pages enter the free state. If you specify this flag, dwSize must be zero, and lpAddress must point to the base address returned by the VirtualAllocEx function when the region was reserved. The function fails if either of these conditions is not met.
	If any pages in the region are currently committed, the function first decommits and then releases them.  The function does not fail if you attempt to release pages that are in different states, some reserved and some committed. This means that you can release a range of pages without first determining their current commitment state.
Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Each page of memory in a process’s virtual address space is in one of three states:

State	Meaning
Free	The page is neither committed nor reserved. The page is not accessible to the process. Attempting to read from or write to a free page results in an access violation exception. You can use the VirtualFreeEx function to put reserved or committed memory pages into the free state.
Reserved	The page is reserved. The range of addresses cannot be used by other allocation functions. The page is not accessible and has no physical storage associated with it.  Attempting to read from or write to a free page results in an access violation exception. You can use the VirtualFreeEx function to put committed memory pages into the reserved state, and to put reserved memory pages into the free state.
Committed	The page is committed. Physical storage in memory or in the paging file on disk is allocated for the page, and access is controlled by a protection code.  The operating system initializes and loads each committed page into physical memory only at the first attempt to read from or write to that page.  When a process terminates, the operating system releases all storage for committed pages.  You can use the VirtualAllocEx function to put committed memory pages into either the reserved or free state.
The VirtualFreeEx function can perform the following operations:

•	Decommit a region of committed or uncommitted pages. After this operation, the pages are in the reserved state.

•	Release a region of reserved pages. After this operation, the pages are in the free state.

•	Decommit and release a region of committed or uncommitted pages. After this operation, the pages are in the free state.

The VirtualFreeEx function can decommit a range of pages that are in different states, some committed and some uncommitted. This means that you can decommit a range of pages without first determining the current commitment state of each page. Decommitting a page releases its physical storage, either in memory or in the paging file on disk.

If a page is decommitted but not released, its state changes to reserved. You can subsequently call VirtualAllocEx to commit it, or VirtualFreeEx to release it. Attempting to read from or write to a reserved page results in an access violation exception.

The VirtualFreeEx function can release a range of pages that are in different states, some reserved and some committed. This means that you can release a range of pages without first determining the current commitment state of each page.  The entire range of pages originally reserved by the VirtualAllocEx function must be released at the same time.

If a page is released, its state changes to free, and it is available for subsequent allocation operations. Attempting to read from or write to a free page results in an access violation exception.

See Also

GlobalAlloc, GlobalFree, VirtualAlloc, VirtualAllocEx, VirtualFree


VirtualLock

The VirtualLock function locks the specified region of the process’s virtual address space into memory, ensuring that subsequent access to the region will not incur a page fault.

BOOL VirtualLock(

LPVOID lpAddress,	// address of first byte of range to lock
DWORD dwSize	// number of bytes in range to lock
);
Parameters

lpAddress

Points to the base address of the region of pages to be locked.

dwSize

Specifies the size, in bytes, of the region to be locked. The region of affected pages includes all pages that contain one or more bytes in the range from the lpAddress parameter to (lpAddress+dwSize). This means that a 2-byte range straddling a page boundary causes both pages to be locked.

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.

Remarks

All pages in the specified region must be committed. Memory protected with the PAGE_NOACCESS flag cannot be locked.

Locking pages into memory may degrade the performance of the system by reducing the available RAM and forcing the system to swap out other critical pages to the paging file. By default, a process can lock a maximum of 30 pages. The default limit is intentionally small to avoid severe performance degradation. Applications that need to lock larger numbers of pages must first call the SetProcessWorkingSetSize function to increase their minimum and maximum working set sizes. The maximum number of pages that a process can lock is equal to the number of pages in its minimum working set minus a small overhead.

Pages that a process has locked remain resident even when the process is idle for extended periods.

To unlock a region of locked pages, use the VirtualUnlock function. Locked pages are automatically unlocked when the process terminates.

This function is not like the GlobalLock or LocalLock function in that it does not increment a lock count and translate a handle into a pointer. There is no lock count for virtual pages, so multiple calls to the VirtualUnlock function are never required to unlock a region of pages.

Windows 95:

On Windows 95, the VirtualLock function is implemented as a stub that has no effect and always returns TRUE.

See Also

GlobalLock, LocalLock, SetProcessWorkingSetSize, VirtualUnlock


VirtualProtect

The VirtualProtect function changes the access protection on a region of committed pages in the virtual address space of the calling process. This function differs from VirtualProtectEx, which changes the access protection of any process.

BOOL VirtualProtect(

LPVOID lpAddress,	// address of region of committed pages
DWORD dwSize,	// size of the region
DWORD flNewProtect,	// desired access protection
PDWORD lpflOldProtect	// address of variable to get old protection
);
Parameters

lpAddress

Points to the base address of the region of pages whose access protection attributes are to be changed.

All pages in the specified region must have been allocated in a single call to the VirtualAlloc or VirtualAllocEx function. The pages cannot span adjacent regions that were allocated by separate calls to VirtualAlloc or VirtualAllocEx.

dwSize

Specifies the size, in bytes, of the region whose access protection attributes are to be changed. The region of affected pages includes all pages containing one or more bytes in the range from the lpAddress parameter to (lpAddress+dwSize). This means that a 2-byte range straddling a page boundary causes the protection attributes of both pages to be changed.

flNewProtect

Specifies the new access protection. You can specify any one of the following flags, along with the PAGE_GUARD and PAGE_NOCACHE protection modifier flags, as necessary:

Value	Meaning
PAGE_READONLY	Enables read access to the committed region of pages. An attempt to write to the committed region results in an access violation. If the system differentiates between read-only access and execute access, an attempt to execute code in the committed region results in an access violation.
PAGE_READWRITE	Enables both read and write access to the committed region of pages.
PAGE_WRITECOPY	Gives copy-on-write access to the committed region of pages.
PAGE_EXECUTE	Enables execute access to the committed region of pages. An attempt to read or write to the committed region results in an access violation.
PAGE_EXECUTE_READ	Enables execute and read access to the committed region of pages. An attempt to write to the committed region results in an access violation.
PAGE_EXECUTE_READWRITE	Enables execute, read, and write access to the committed region of pages.
PAGE_EXECUTE_WRITECOPY	Enables execute, read, and write access to the committed region of pages. The pages are shared read-on-write and copy-on-write.
PAGE_GUARD	Pages in the region become guard pages. Any attempt to access a guard page causes the operating system to raise a STATUS_GUARD_PAGE exception and turn off the guard page status. Guard pages thus act as a one-shot access alarm. The PAGE_GUARD flag is a page protection modifier. An application uses it with one of the other page protection flags, with one exception: it cannot be used with PAGE_NOACCESS. When an access attempt leads the operating system to turn off guard page status, the underlying page protection takes over. If a guard page exception occurs during a system service, the service typically returns a failure status indicator.
PAGE_NOACCESS	Disables all access to the committed region of pages. An attempt to read from, write to, or execute in the committed region results in an access violation exception, called a general protection (GP) fault.
PAGE_NOCACHE	Allows no caching of the committed regions of pages. The hardware attributes for the physical memory should be specified as “no cache.” This is not recommended for general usage. It is useful for device drivers; for example, mapping a video frame buffer with no caching. This flag is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.
lpflOldProtect

Points to a variable that the function sets to the previous access protection value of the first page in the specified region of pages. If this parameter is NULL or does not point to a valid variable, the function fails.

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.

Remarks

You can set the access protection value on committed pages only. If the state of any page in the specified region is not committed, the function fails and returns without modifying the access protection of any pages in the specified region.

The VirtualProtect function changes the access protection of memory in the calling process, and the VirtualProtectEx function changes the access protection of memory in a specified process.

The PAGE_GUARD protection modifier flag establishes guard pages. Guard pages act as one-shot access alarms. See Guard Pages for further discussion of guard pages.

See Also

VirtualAlloc, VirtualProtectEx


VirtualProtectEx

The VirtualProtectEx function changes the access protection on a region of committed pages in the virtual address space of a specified process. Note that this function differs from VirtualProtect, which changes the access protection on the calling process only.

BOOL VirtualProtectEx(

HANDLE hProcess,	// handle of process
LPVOID lpAddress,	// address of region of committed pages
DWORD dwSize,	// size of region
DWORD flNewProtect,	// desired access protection
PDWORD lpflOldProtect	// address of variable to get old protection
);
Parameters

hProcess

Identifies the process whose memory protection is to be changed. The handle must have PROCESS_VM_OPERATION access. For more information on PROCESS_VM_OPERATION, see OpenProcess.

lpAddress

Points to the base address of the region of pages whose access protection attributes are to be changed.

All pages in the specified region must have been allocated in a single call to the VirtualAlloc or VirtualAllocEx function. The pages cannot span adjacent regions that were allocated by separate calls to VirtualAlloc or VirtualAllocEx.

dwSize

Specifies the size, in bytes, of the region whose access protection attributes are changed. The region of affected pages includes all pages containing one or more bytes in the range from the lpAddress parameter to (lpAddress+dwSize). This means that a 2-byte range straddling a page boundary causes the protection attributes of both pages to be changed.

flNewProtect

Specifies the new access protection. Any one of the following flags can be specified, along with the PAGE_GUARD and PAGE_NOCACHE protection modifier flags, as desired:

Value	Meaning
PAGE_READONLY	Enables read access to the committed region of pages. An attempt to write to the committed region results in an access violation. If the system differentiates between read-only access and execute access, an attempt to execute code in the committed region results in an access violation.
PAGE_READWRITE	Enables both read and write access to the committed region of pages.
PAGE_WRITECOPY	Gives copy-on-write access to the committed region of pages.
PAGE_EXECUTE	Enables execute access to the committed region of pages. An attempt to read or write to the committed region results in an access violation.
PAGE_EXECUTE_READ	Enables execute and read access to the committed region of pages. An attempt to write to the committed region results in an access violation.
PAGE_EXECUTE_READWRITE	Enables execute, read, and write access to the committed region of pages.
PAGE_EXECUTE_WRITECOPY	Enables execute, read, and write access to the committed region of pages. The pages are shared read-on-write and copy-on-write.
PAGE_GUARD	Pages in the region become guard pages. Any attempt to read from or write to a guard page causes the operating system to raise a STATUS_GUARD_PAGE exception, and turn off the guard page status. Guard pages thus act as a one-shot access alarm. The PAGE_GUARD flag is a page protection modifier. An application uses it with one of the other page protection flags, with one exception: it cannot be used with PAGE_NOACCESS. When an access attempt leads the operating system to turn off guard page status, the underlying page protection takes over. If a guard page exception occurs during a system service, the service typically returns a failure status indicator.
PAGE_NOACCESS	Disables all access to the committed region of pages. An attempt to read from, write to, or execute in the committed region results in an access violation exception, called a general protection (GP) fault.
PAGE_NOCACHE	Allows no caching of the committed regions of pages. The hardware attributes for the physical memory should be set to “no cache.” This is not recommended for general usage. It is useful for device drivers; for example, mapping a video frame buffer with no caching. This flag is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.
lpflOldProtect

Points to a variable that receives the previous access protection of the first page in the specified region of pages. If this parameter is NULL or does not point to a valid variable, the function fails.

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.

Remarks

The access protection value can be set only on committed pages. If the state of any page in the specified region is not committed, the function fails and returns without modifying the access protection of any pages in the specified region.

VirtualProtectEx is identical to the VirtualProtect function except that it changes the access protection of memory in a specified process.

The PAGE_GUARD protection modifier flag establishes guard pages. Guard pages act as one-shot access alarms. See Guard Pages. for further discussion of guard pages.

See Also

VirtualAlloc, VirtualProtect, VirtualQueryEx


VirtualQuery

The VirtualQuery function provides information about a range of pages in the virtual address space of the calling process.

DWORD VirtualQuery(

LPCVOID lpAddress,	// address of region
PMEMORY_BASIC_INFORMATION lpBuffer,	// address of information buffer
DWORD dwLength	// size of buffer
);
Parameters

lpAddress

Points to the base address of the region of pages to be queried. This value is rounded down to the next page boundary. To determine the size of a page on the host computer, use the GetSystemInfo function.

lpBuffer

Points to a MEMORY_BASIC_INFORMATION structure in which information about the specified page range is returned.

dwLength

Specifies the size, in bytes, of the buffer pointed to by the lpBuffer parameter.

Return Values

The return value is the actual number of bytes returned in the information buffer.

Remarks

VirtualQuery provides information about a region of consecutive pages beginning at a specified address that share the following attributes:

•	The state of all pages is the same with the MEM_COMMIT, MEM_RESERVE, MEM_FREE, MEM_PRIVATE, MEM_MAPPED, or MEM_IMAGE flag.

•	If the initial page is not free, all pages in the region are part of the same initial allocation of pages reserved by a call to the VirtualAlloc function.

•	The access of all pages is the same with the PAGE_READONLY, PAGE_READWRITE, PAGE_NOACCESS, PAGE_WRITECOPY, PAGE_EXECUTE, PAGE_EXECUTE_READ, PAGE_EXECUTE_READWRITE, PAGE_EXECUTE_WRITECOPY, PAGE_GUARD, or PAGE_NOCACHE flag.

The function determines the attributes of the first page in the region and then scans subsequent pages until it scans the entire range of pages or until it encounters a page with a nonmatching set of attributes. The function returns the attributes and the size, in bytes, of the region of pages with matching attributes. For example, if there is a 40 megabyte (MB) region of free memory, and VirtualQuery is called on a page that is 10 MB into the region, the function will obtain a state of MEM_FREE and a size of 30 MB.

This function reports on a region of pages in the memory of the calling process, and the VirtualQueryEx function reports on a region of pages in the memory of a specified process.

See Also

GetSystemInfo, MEMORY_BASIC_INFORMATION, VirtualQueryEx


VirtualQueryEx

The VirtualQueryEx function provides information about a range of pages within the virtual address space of a specified process.

DWORD VirtualQueryEx(

HANDLE hProcess,	// handle of process
LPCVOID lpAddress,	// address of region
PMEMORY_BASIC_INFORMATION lpBuffer,	// address of information buffer
DWORD dwLength	// size of buffer
);
Parameters

hProcess

Identifies the process whose memory information is queried. The handle must have PROCESS_QUERY_INFORMATION access.

lpAddress

Points to the base address of the region of pages to be queried. This value is rounded down to the next page boundary. To determine the size of a page on the host computer, use the GetSystemInfo function.

lpBuffer

Points to a MEMORY_BASIC_INFORMATION structure in which information about the specified page range is returned.

dwLength

Specifies the size, in bytes, of the buffer pointed to by the lpBuffer parameter.

Return Values

The return value is the actual number of bytes returned in the information buffer.

Remarks

VirtualQueryEx provides information about a region of consecutive pages beginning at a specified address that share the following attributes:

•	The state of all pages is the same with the MEM_COMMIT, MEM_RESERVE, MEM_FREE, MEM_PRIVATE, MEM_MAPPED, or MEM_IMAGE flag.

•	If the initial page is not free, all pages in the region are part of the same initial allocation of pages reserved by a call to the VirtualAlloc function.

•	The access of all pages is the same with the PAGE_READONLY, PAGE_READWRITE, PAGE_NOACCESS, PAGE_WRITECOPY, PAGE_EXECUTE, PAGE_EXECUTE_READ, PAGE_EXECUTE_READWRITE, PAGE_EXECUTE_WRITECOPY, PAGE_GUARD, or PAGE_NOCACHE flag.

The VirtualQueryEx function determines the attributes of the first page in the region and then scans subsequent pages until it scans the entire range of pages, or until it encounters a page with a nonmatching set of attributes. The function returns the attributes and the size, in bytes, of the region of pages with matching attributes. For example, if there is a 40 megabyte (MB) region of free memory, and VirtualQueryEx is called on a page that is 10 MB into the region, the function will obtain a state of MEM_FREE and a size of 30 MB.

This function is identical to the VirtualQuery function, except that it enables access to information about memory in a specified process.

See Also

GetSystemInfo, MEMORY_BASIC_INFORMATION, VirtualAlloc, VirtualProtectEx, VirtualQuery


VirtualUnlock

The VirtualUnlock function unlocks a specified range of pages in the virtual address space of a process, enabling the system to swap the pages out to the paging file if necessary.

BOOL VirtualUnlock(

LPVOID lpAddress,	// address of first byte of range
DWORD dwSize	// number of bytes in range
);
Parameters

lpAddress

Points to the base address of the region of pages to be unlocked.

dwSize

Specifies the size, in bytes, of the region being unlocked. The region of affected pages includes all pages containing one or more bytes in the range from the lpAddress parameter to (lpAddress+dwSize). This means that a 2-byte range straddling a page boundary causes both pages to be unlocked.

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.

Remarks

For the function to succeed, the range specified need not match a range passed to a previous call to the VirtualLock function, but all pages in the range must be locked.

See Also

VirtualLock


VkKeyScan

The VkKeyScan function translates a character to the corresponding virtual-key code and shift state for the current keyboard.

SHORT VkKeyScan(

TCHAR ch	// character to translate
);
Parameters

ch

Specifies the character to be translated into a virtual-key code.

Return Values

If the function succeeds, the low-order byte of the return value contains the virtual-key code and the high-order byte contains the shift state, which can be a combination of the following flag bits:

Bit	Meaning
1	Either SHIFT key is pressed.
2	Either CTRL key is pressed.
4	Either ALT key is pressed.
If the function finds no key that translates to the passed character code, both the low-order and high-order bytes contain −1.

Remarks

For keyboard layouts that use the right-hand ALT key as a shift key (for example, the French keyboard layout), the shift state is represented by the value 6, because the right-hand ALT key is converted internally into CTRL+ALT.

Translations for the numeric keypad (VK_NUMPAD0 through VK_DIVIDE) are ignored. This function is intended to translate characters into keystrokes from the main keyboard section only. For example, the character “7” is translated into VK_7, not VK_NUMPAD7.

VkKeyScan is used by applications that send characters by using the WM_KEYUP and WM_KEYDOWN messages.

See Also

GetAsyncKeyState, GetKeyboardState, GetKeyNameText, GetKeyState, SetKeyboardState, WM_KEYDOWN, WM_KEYUP


VkKeyScanEx [Now Supported on Windows NT]
VkKeyScanEx

[Now Supported on Windows NT]

The VkKeyScanEx function translates a character to the corresponding virtual-key code and shift state. The function translates the character using the input language and physical keyboard layout identified by the given keyboard layout handle.

SHORT VkKeyScanEx(

CHAR ch,	// character to translate
HKL dwhkl	// keyboard layout handle
);
Parameters

ch

Specifies the character to be translated into a virtual-key code.

dwhkl

Identifies the keyboard layout to use to translate the character. This parameter can be any keyboard layout handle previously returned by the LoadKeyboardLayout function.

Return Values

If the function succeeds, the low-order byte of the return value contains the virtual-key code and the high-order byte contains the shift state, which can be a combination of the following flag bits:

Bit	Meaning
1	Either SHIFT key is pressed.
2	Either CTRL key is pressed.
4	Either ALT key is pressed.
If the function finds no key that translates to the passed character code, both the low-order and high-order bytes contain −1.

Remarks

For keyboard layouts that use the right-hand ALT key as a shift key (for example, the French keyboard layout), the shift state is represented by the value 6, because the right-hand ALT key is converted internally into CTRL+ALT.

Translations for the numeric keypad (VK_NUMPAD0 through VK_DIVIDE) are ignored. This function is intended to translate characters into keystrokes from the main keyboard section only. For example, the character “7” is translated into VK_7, not VK_NUMPAD7.

VkKeyScanEx is used by applications that send characters by using the WM_KEYUP and WM_KEYDOWN messages.

See Also

GetAsyncKeyState, GetKeyboardState, GetKeyNameText, GetKeyState, LoadKeyboardLayout, SetKeyboardState, ToAsciiEx, VkKeyScan


VwStreamCloseFunc

Closes the file. The file parser must carry out any necessary cleanup, such as closing any other open files related to the given file.

VOID VwStreamCloseFunc(

SOFILE hFile,
HPROC reserved
);
Parameters

hFile

Handle of the file for execute input and output (XIO) routines.

reserved

Reserved; do not use.

Return Values

None.


VwStreamOpenFunc

Checks the validity of the specified file and returns information about the file parser.

INT VwStreamOpenFunc(

SOFILE hFile,
INT wFileId,
U_BYTE VWPTR *pFileName,
SOFILTERINFO VWPTR *pFilterInfo,
HPROC reserved
);
Parameters

hFile

Handle of the file for execute input and output (XIO) routines.

wFileId

Identifier for the file.

pFileName

Address of the null-terminated string specifying the base name of the file. This string does not include path information.

pFilterInfo

Address of the SOFILTERINFO structure that receives information about the file parser.

reserved

Reserved; do not use.

Return Values

Returns the VWERR_OK value if successful or one of the following error values otherwise:

VWERR_BADFILE	Corrupt or unreadable file
VWERR_EMPTYFILE	Empty file
VWERR_PROTECTEDFILE	Password-protected or encrypted file
VWERR_SUPFILEOPENFAILS	Supplementary file failed to open


VwStreamReadFunc

Outputs characters, cells, or fields, depending on the current section type and file contents.

INT VwStreamReadFunc(

SOFILE hFile,
HPROC reserved
);
Parameters

hFile

Handle of the file for execute input and output (XIO) routines.

reserved

Reserved; do not use.

Return Values

Returns zero if successful or  − 1 if the end of the file is reached.


VwStreamReadRecordFunc

Outputs a single record by calling various stream output functions.

This function should output a single record and then call the SOPutBreak function with the SO_RECORDBREAK value before returning. The SO_EOFBREAK and SO_SECTIONBREAK conditions do not need to be trapped by this function.

VOID VwStreamReadRecordFunc(

SOFILE hFile,
DWORD dwData,
HPROC reserved
);
Parameters

hFile

Handle of the file for execute input and output (XIO) routines.

dwData

Data to be saved for the record.

reserved

Reserved; do not use.

Return Values

None.


VwStreamSectionFunc

Sets the parameters for a section.

At a minimum, this function should call the SOPutSectionType and SOPutSectionName functions to set the section type and name. The function should also set the cell width if the section is a spreadsheet or the field format if the section is a database.

The display engine calls the function after calling the VwStreamOpenFunc function but before calling the VwStreamReadFunc function. It is also called after any VwStreamReadFunc that ends with a call to the SOPutBreak function with the SO_SECTIONBREAK value.

INT VwStreamSectionFunc(

SOFILE hFile,
HPROC reserved
);
Parameters

hFile

Handle of the file for execute input and output (XIO) routines.

reserved

Reserved; do not use.

Return Values

Always returns zero.


VwStreamSeekFunc

Same definition as the line filters Seek function.

INT VwStreamSeekFunc(

SOFILE hFile,
HPROC reserved
);
Parameters

hFile

Handle of the file for execute input and output (XIO) routines.

reserved

Reserved; do not use.

Return Values

Returns zero if successful or  − 1 if the function fails.


VwStreamTellFunc

Same definition as the line filters Tell function.

INT VwStreamTellFunc(

SOFILE hFile,
HPROC reserved
);
Parameters

hFile

Handle of the file for execute input and output (XIO) routines.

reserved

Reserved; do not use.

Return Values

Returns zero if successful or  − 1 if the function fails.


WaitCommEvent

The WaitCommEvent function waits for an event to occur for a specified communications device. The set of events that are monitored by this function is contained in the event mask associated with the device handle.

BOOL WaitCommEvent(

HANDLE hFile,	// handle of communications device
LPDWORD lpEvtMask,	// address of variable for event that occurred
LPOVERLAPPED lpOverlapped,	// address of overlapped structure
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

lpEvtMask

Points to a 32-bit variable that receives a mask indicating the type of event that occurred. If an error occurs, the value is zero; otherwise, it is one of the following values:

Value	Meaning
EV_BREAK	A break was detected on input.
EV_CTS	The CTS (clear-to-send) signal changed state.
EV_DSR	The DSR (data-set-ready) signal changed state.
EV_ERR	A line-status error occurred. Line-status errors are CE_FRAME, CE_OVERRUN, and CE_RXPARITY.
EV_RING	A ring indicator was detected.
EV_RLSD	The RLSD (receive-line-signal-detect) signal changed state.
EV_RXCHAR	A character was received and placed in the input buffer.
EV_RXFLAG	The event character was received and placed in the input buffer. The event character is specified in the device’s DCB structure, which is applied to a serial port by using the SetCommState function.
EV_TXEMPTY	The last character in the output buffer was sent.
lpOverlapped

Points to an OVERLAPPED structure. This structure is required if hFile was opened with FILE_FLAG_OVERLAPPED.

If hFile was opened with FILE_FLAG_OVERLAPPED, the lpOverlapped parameter must not be NULL. It must point to a valid OVERLAPPED structure. If hFile was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function can incorrectly report that the operation is complete.

If hFile was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, WaitCommEvent is performed as an overlapped operation. In this case, the OVERLAPPED structure must contain a handle to a manual-reset event object (created by using the CreateEvent function).

If hFile handle was not opened with FILE_FLAG_OVERLAPPED, WaitCommEvent does not return until one of the specified events or an error occurs.

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.

Remarks

The WaitCommEvent function monitors a set of events for a specified communications resource. To set and query the current event mask of a communications resource, use the SetCommMask and GetCommMask functions.

If the overlapped operation cannot be completed immediately, the function returns FALSE and the GetLastError function returns ERROR_IO_PENDING, indicating that the operation is executing in the background. When this happens, the system sets the hEvent member of the OVERLAPPED structure to the not-signaled state before WaitCommEvent returns, and then it sets it to the signaled state when one of the specified events or an error occurs. The calling process can use one of the wait functions to determine the event object’s state and then use the GetOverlappedResult function to determine the results of the WaitCommEvent operation. GetOverlappedResult reports the success or failure of the operation, and the variable pointed to by the lpEvtMask parameter is set to indicate the event that occurred.

If a process attempts to change the device handle’s event mask by using the SetCommMask function while an overlapped WaitCommEvent operation is in progress, WaitCommEvent returns immediately. The variable pointed to by the lpEvtMask parameter is set to zero.

See Also

CreateFile, DCB, GetCommMask, GetOverlappedResult, OVERLAPPED, SetCommMask, SetCommState


WaitForDebugEvent

The WaitForDebugEvent function waits for a debugging event to occur in a process being debugged.

BOOL WaitForDebugEvent(

LPDEBUG_EVENT lpDebugEvent,	// address of structure for event information
DWORD dwMilliseconds	// number of milliseconds to wait for event
);
Parameters

lpDebugEvent

Points to a DEBUG_EVENT structure that is filled with information about the debugging event.

dwMilliseconds

Specifies the number of milliseconds to wait for a debugging event. If this parameter is zero, the function tests for a debugging event and returns immediately. If the parameter is INFINITE, the function does not return until a debugging event has occurred.

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.

Remarks

Only the thread that created the process being debugged can call WaitForDebugEvent.

See Also

ContinueDebugEvent, DebugActiveProcess, DebugBreak, DEBUG_EVENT, OutputDebugString


WaitForInputIdle

The WaitForInputIdle function waits until the given process is waiting for user input with no input pending, or until the time-out interval has elapsed.

The WaitForInputIdle function only works with GUI applications. If a console application calls the function, it returns immediately, with no wait.

DWORD WaitForInputIdle(

HANDLE hProcess,	// handle to process
DWORD dwMilliseconds	// time-out interval in milliseconds
);
Parameters

hProcess

Identifies the process.

dwMilliseconds

Specifies the time-out interval, in milliseconds. If dwMilliseconds is INFINITE, the function does not return until the process is idle.

Return Values

The following table shows the possible return values:

Value	Meaning
0	The wait was satisfied successfully.
WAIT_TIMEOUT	The wait was terminated because the time-out interval elapsed.
0xFFFFFFFF	An error occurred. To get extended error information, use the GetLastError function.
Remarks

The WaitForInputIdle function enables a thread to suspend its execution until a specified process has finished its initialization and is waiting for user input with no input pending. This can be useful for synchronizing a parent process and a newly created child process. When a parent process creates a child process, the CreateProcess function returns without waiting for the child process to finish its initialization. Before trying to communicate with the child process, the parent process can use WaitForInputIdle to determine when the child’s initialization has been completed. For example, the parent process should use WaitForInputIdle before trying to find a window associated with the child process.

The WaitForInputIdle function can be used at any time, not just during application startup.

See Also

CreateProcess


WaitForMultipleObjects

The WaitForMultipleObjects function returns when one of the following occurs:

•	Either any one or all of the specified objects are in the signaled state.

•	The time-out interval elapses.

DWORD WaitForMultipleObjects(

DWORD nCount,	// number of handles in the object handle array
CONST HANDLE *lpHandles,	// pointer to the object-handle array
BOOL bWaitAll,	// wait flag
DWORD dwMilliseconds	// time-out interval in milliseconds
);
Parameters

nCount

Specifies the number of object handles in the array pointed to by lpHandles. The maximum number of object handles is MAXIMUM_WAIT_OBJECTS.

lpHandles

Points to an array of object handles. For a list of the object types whose handles can be specified, see the following Remarks section. The array can contain handles of objects of different types.

Windows NT: The handles must have SYNCHRONIZE access. For more information, see Access Masks and Access Rights.

bWaitAll

Specifies the wait type. If TRUE, the function returns when the state all objects in the lpHandles array is signaled. If FALSE, the function returns when the state of any one of the objects set to is signaled. In the latter case, the return value indicates the object whose state caused the function to return.

dwMilliseconds

Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the conditions specified by the bWaitAll parameter are not met. If dwMilliseconds is zero, the function tests the states of the specified objects and returns immediately. If dwMilliseconds is INFINITE, the function’s time-out interval never elapses.

Return Values

If the function succeeds, the return value indicates the event that caused the function to return.

If the function fails, the return value is WAIT_FAILED. To get extended error information, call GetLastError.

The return value upon success is one of the following values:

Value	Meaning
WAIT_OBJECT_0 to (WAIT_OBJECT_0 + nCount − 1)	If bWaitAll is TRUE, the return value indicates that the state of all specified objects is signaled.  If bWaitAll is FALSE, the return value minus WAIT_OBJECT_0 indicates the lpHandles array index of the object that satisfied the wait. If more than one object became signalled during the call, this is the array index of the signalled object with the smallest index value of all the signalled objects.
WAIT_ABANDONED_0 to (WAIT_ABANDONED_0 + nCount − 1)	If bWaitAll is TRUE, the return value indicates that the state of all specified objects is signaled and at least one of the objects is an abandoned mutex object.  If bWaitAll is FALSE, the return value minus WAIT_ABANDONED_0 indicates the lpHandles array index of an abandoned mutex object that satisfied the wait.
WAIT_TIMEOUT	The time-out interval elapsed and the conditions specified by the bWaitAll parameter are not satisfied.
Remarks

The WaitForMultipleObjects function determines whether the wait criteria have been met. If the criteria have not been met, the calling thread enters an efficient wait state, consuming very little processor time while waiting for the criteria to be met.

When bWaitAll is TRUE, the function’s wait operation is completed only when the states of all objects have been set to signaled. The function does not modify the states of the specified objects until the states of all objects have been set to signaled. For example, a mutex can be signaled, but the thread does not get ownership until the states of the other objects are also set to signaled. In the meantime, some other thread may get ownership of the mutex, thereby setting its state to nonsignaled.

Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one.

The WaitForMultipleObjects function can specify handles of any of the following object types in the lpHandles array:

Object	Description
Change notification	The FindFirstChangeNotification function returns the handle. A change notification object’s state is signaled when a specified type of change occurs within a specified directory or directory tree.
Console input	The handle is returned by the CreateFile function when the CONIN$ value is specified, or by the GetStdHandle function. The object’s state is signaled when there is unread input in the console’s input buffer, and it is nonsignaled when the input buffer is empty.
Event	The CreateEvent or OpenEvent function returns the handle. An event object’s state is set explicitly to signaled by the SetEvent or PulseEvent function. A manual-reset event object’s state must be reset explicitly to nonsignaled by the ResetEvent function. For an auto-reset event object, the wait function resets the object’s state to nonsignaled before returning. Event objects are also used in overlapped operations, in which the state is set by the system.
Mutex	The CreateMutex or OpenMutex function returns the handle. A mutex object’s state is signaled when it is not owned by any thread. The wait function requests ownership of the mutex for the calling thread, changing the mutex’s state to nonsignaled when ownership is granted.
Process	The CreateProcess or OpenProcess function returns the handle. A process object’s state is signaled when the process terminates.
Semaphore	The CreateSemaphore or OpenSemaphore function returns the handle. A semaphore object maintains a count between zero and some maximum value. Its state is signaled when its count is greater than zero and nonsignaled when its count is zero. If the current state is signaled, the wait function decreases the count by one.
Thread	The CreateProcess, CreateThread, or CreateRemoteThread function returns the handle. A thread object’s state is signaled when the thread terminates.
Timer	The CreateWaitableTimer or OpenWaitableTimer function returns the handle. Activate the timer by calling the SetWaitableTimer function. The state of an active timer is signaled when it reaches its due time. You can deactivate the timer by calling the CancelWaitableTimer function. The state of an active timer is signaled when it reaches its due time. You can deactivate the timer by calling the CancelWaitableTimer function.
In some circumstances, you can specify a handle of a file, named pipe, or communications device as a synchronization object in lpHandles. However, their use for this purpose is discouraged.

You have to be careful when using the wait functions and DDE. If a thread creates any windows, it must process messages. DDE sends messages to all windows in the system. If you have a thread that uses a wait function with no time-out interval, the system will deadlock. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects or MsgWaitForMultipleObjectsEx, rather than WaitForMultipleObjects.

See Also

CancelWaitableTimer, CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, CreateWaitableTimer, FindFirstChangeNotification, GetStdHandle, MsgWaitForMultipleObjects, MsgWaitForMultipleObjectsEx, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, OpenWaitableTimer, PulseEvent, QueueUserAPC, ResetEvent, SetEvent, SetWaitableTimer


WaitForMultipleObjectsEx

The WaitForMultipleObjectsEx function returns when one of the following occurs:

•	Either any one or all of the specified objects are in the signaled state.

•	An I/O completion routine or asynchronous procedure call (APC) is queued to the thread.

•	The time-out interval elapses.

DWORD WaitForMultipleObjectsEx(

DWORD nCount,	// number of handles in handle array
CONST HANDLE *lpHandles,	// points to the object-handle array
BOOL bWaitAll,	// wait flag
DWORD dwMilliseconds,	// time-out interval in milliseconds
BOOL bAlertable	// alertable wait flag
);
Parameters

nCount

Specifies the number of object handles to wait for in the array pointed to by lpHandles. The maximum number of object handles is MAXIMUM_WAIT_OBJECTS.

lpHandles

Points to an array of object handles. For a list of the object types whose handles can be specified, see the following Remarks section. The array can contain handles of objects of different types.

Windows NT: The handles must have SYNCHRONIZE access. For more information, see Access Masks and Access Rights.

bWaitAll

Specifies the wait type. If TRUE, the function returns when the states all objects in the lpHandles array are set to signaled. If FALSE, the function returns when the state of any one of the objects is set to signaled. In the latter case, the return value indicates the object whose state caused the function to return.

dwMilliseconds

Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the criteria specified by the bWaitAll parameter are not met and no completion routines or APCs are queued. If dwMilliseconds is zero, the function tests the states of the specified objects and checks for queued completion routines or APCs and then returns immediately. If dwMilliseconds is INFINITE, the function’s time-out interval never elapses.

bAlertable

Specifies whether the function returns when the system queues an I/O completion routine or APC. If TRUE, the function returns and the completion routine or APC function is executed. If FALSE, the function does not return and the completion routine or APC function is not executed.

A completion routine is queued when the ReadFileEx or WriteFileEx function in which it was specified has completed. The wait function returns and the completion routine is called only if bAlertable is TRUE and the calling thread is the thread that initiated the read or write operation. An APC is queued when you call QueueUserAPC.

Return Values

If the function succeeds, the return value indicates the event that caused the function to return.

If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

The return value on success is one of the following values:

Value	Meaning
WAIT_OBJECT_0 to (WAIT_OBJECT_0 + nCount − 1)	If bWaitAll is TRUE, the return value indicates that the state of all specified objects is signaled.  If bWaitAll is FALSE, the return value minus WAIT_OBJECT_0 indicates the lpHandles array index of the object that satisfied the wait. If more than one object became signalled during the call, this is the array index of the signalled object with the smallest index value of all the signalled objects.
WAIT_ABANDONED_0 to (WAIT_ABANDONED_0 + nCount − 1)	If bWaitAll is TRUE, the return value indicates that the state of all specified objects is signaled, and at least one of the objects is an abandoned mutex object.  If bWaitAll is FALSE, the return value minus WAIT_ABANDONED_0 indicates the lpHandles array index of an abandoned mutex object that satisfied the wait.
WAIT_IO_COMPLETION	One or more I/O completion routines are queued for execution.
WAIT_TIMEOUT	The time-out interval elapsed, the conditions specified by the bWaitAll parameter were not satisfied, and no completion routines are queued.
Remarks

The WaitForMultipleObjectsEx function determines whether the wait criteria have been met. If the criteria have not been met, the calling thread enters an efficient wait state, using very little processor time while waiting for the criteria to be met.

When bWaitAll is TRUE, the function’s wait operation is completed only when the states of all objects have been set to signaled. The function does not modify the states of the specified objects until the states of all objects have been set to signaled. For example, a mutex can be signaled, but the thread does not get ownership until the states of the other objects are also set to signaled. In the meantime, some other thread may get ownership of the mutex, thereby setting its state to nonsignaled.

Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one.

The WaitForMultipleObjectsEx function can specify handles of any of the following object types in the lpHandles array:

Object	Description
Change notification	The FindFirstChangeNotification function returns the handle. A change notification object’s state is signaled when a specified type of change occurs within a specified directory or directory tree.
Console input	The handle is returned by the CreateFile function when the CONIN$ value is specified, or by the GetStdHandle function. The object’s state is signaled when there is unread input in the console’s input buffer, and it is nonsignaled when the input buffer is empty.
Event	The CreateEvent or OpenEvent function returns the handle. An event object’s state is set explicitly to signaled by the SetEvent or PulseEvent function. A manual-reset event object’s state must be reset explicitly to nonsignaled by the ResetEvent function. For an auto-reset event object, the wait function resets the object’s state to nonsignaled before returning. Event objects are also used in overlapped operations, in which the state is set by the system.
Mutex	The CreateMutex or OpenMutex function returns the handle. A mutex object’s state is signaled when it is not owned by any thread. The wait function requests ownership of the mutex for the calling thread, changing the mutex’s state to nonsignaled when ownership is granted.
Process	The CreateProcess or OpenProcess function returns the handle. A process object’s state is signaled when the process terminates.
Semaphore	The CreateSemaphore or OpenSemaphore function returns the handle. A semaphore object maintains a count between zero and some maximum value. Its state is signaled when its count is greater than zero and nonsignaled when its count is zero. If the current state is signaled, the wait function decreases the count by one.
Thread	The CreateProcess, CreateThread, or CreateRemoteThread function returns the handle. A thread object’s state is signaled when the thread terminates.
Timer	The CreateWaitableTimer or OpenWaitableTimer function returns the handle. Activate the timer by calling the SetWaitableTimer function. The state of an active timer is signaled when it reaches its due time. You can deactivate the timer by calling the CancelWaitableTimer function. The state of an active timer is signaled when it reaches its due time. You can deactivate the timer by calling the CancelWaitableTimer function.
In some circumstances, you can specify a handle of a file, named pipe, or communications device as a synchronization object in lpHandles. However, their use for this purpose is discouraged.

You have to be careful when using the wait functions and DDE. If a thread creates any windows, it must process messages. DDE sends messages to all windows in the system. If you have a thread that uses a wait function with no time-out interval, the system will deadlock. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects or MsgWaitForMultipleObjectsEx, rather than WaitForMultipleObjectsEx.

See Also

CancelWaitableTimer, CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateWaitableTimer, CreateThread, FindFirstChangeNotification, GetStdHandle, MsgWaitForMultipleObjects, MsgWaitForMultipleObjectsEx, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, OpenWaitableTimer, PulseEvent, QueueUserAPC, ReadFileEx, ResetEvent, SetEvent, SetWaitableTimer, WriteFileEx


WaitForPrinterChange

The WaitForPrinterChange function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the FindFirstPrinterChangeNotification, FindNextPrinterChangeNotification, and FindClosePrinterChangeNotification functions to monitor the occurrence of requested changes on a printer or print server.when one or more requested changes occur on a printer or print server.


WaitForSingleObject

The WaitForSingleObject function returns when one of the following occurs:

•	The specified object is in the signaled state.

•	The time-out interval elapses.

DWORD WaitForSingleObject(

HANDLE hHandle,	// handle of object to wait for
DWORD dwMilliseconds	// time-out interval in milliseconds
);
Parameters

hHandle

Identifies the object. For a list of the object types whose handles can be specified, see the following Remarks section.

Windows NT: The handle must have SYNCHRONIZE access. For more information, see Access Masks and Access Rights.

dwMilliseconds

Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the object’s state is nonsignaled. If dwMilliseconds is zero, the function tests the object’s state and returns immediately. If dwMilliseconds is INFINITE, the function’s time-out interval never elapses.

Return Values

If the function succeeds, the return value indicates the event that caused the function to return.

If the function fails, the return value is WAIT_FAILED. To get extended error information, call GetLastError.

The return value on success is one of the following values:

Value	Meaning
WAIT_ABANDONED	The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to nonsignaled.
WAIT_OBJECT_0	The state of the specified object is signaled.
WAIT_TIMEOUT	The time-out interval elapsed, and the object’s state is nonsignaled.
Remarks

The WaitForSingleObject function checks the current state of the specified object. If the object’s state is nonsignaled, the calling thread enters an efficient wait state. The thread consumes very little processor time while waiting for the object state to become signaled or the time-out interval to elapse.

Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one.

The WaitForSingleObject function can wait for the following objects:

Object	Description
Change notification	The FindFirstChangeNotification function returns the handle. A change notification object’s state is signaled when a specified type of change occurs within a specified directory or directory tree.
Console input	The handle is returned by the CreateFile function when the CONIN$ value is specified, or by the GetStdHandle function. The object’s state is signaled when there is unread input in the console’s input buffer, and it is nonsignaled when the input buffer is empty.
Event	The CreateEvent or OpenEvent function returns the handle. An event object’s state is set explicitly to signaled by the SetEvent or PulseEvent function. A manual-reset event object’s state must be reset explicitly to nonsignaled by the ResetEvent function. For an auto-reset event object, the wait function resets the object’s state to nonsignaled before returning. Event objects are also used in overlapped operations, in which the state is set by the system.
Mutex	The CreateMutex or OpenMutex function returns the handle. A mutex object’s state is signaled when it is not owned by any thread. The wait function requests ownership of the mutex for the calling thread, changing the mutex’s state to nonsignaled when ownership is granted.
Process	The CreateProcess or OpenProcess function returns the handle. A process object’s state is signaled when the process terminates.
Semaphore	The CreateSemaphore or OpenSemaphore function returns the handle. A semaphore object maintains a count between zero and some maximum value. Its state is signaled when its count is greater than zero and nonsignaled when its count is zero. If the current state is signaled, the wait function decreases the count by one.
Thread	The CreateProcess, CreateThread, or CreateRemoteThread function returns the handle. A thread object’s state is signaled when the thread terminates.
Timer	The CreateWaitableTimer or OpenWaitableTimer function returns the handle. Activate the timer by calling the SetWaitableTimer function. The state of an active timer is signaled when it reaches its due time. You can deactivate the timer by calling the CancelWaitableTimer function. The state of an active timer is signaled when it reaches its due time. You can deactivate the timer by calling the CancelWaitableTimer function.
In some circumstances, you can specify a handle of a file, named pipe, or communications device as a synchronization object in lpHandles. However, their use for this purpose is discouraged.

You have to be careful when using the wait functions and DDE. If a thread creates any windows, it must process messages. DDE sends messages to all windows in the system. If you have a thread that uses a wait function with no time-out interval, the system will deadlock. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects or MsgWaitForMultipleObjectsEx, rather than WaitForSingleObject.

See Also

CancelWaitableTimer, CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, CreateWaitableTimer, FindFirstChangeNotification, GetStdHandle, MsgWaitForMultipleObjects, MsgWaitForMultipleObjectsEx, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, OpenWaitableTimer, PulseEvent, ResetEvent, SetEvent, SetWaitableTimer


WaitForSingleObjectEx

The WaitForSingleObjectEx function returns when one of the following occurs:

•	The specified object is in the signaled state.

•	An I/O completion routine or asynchronous procedure call (APC) is queued to the thread.

•	The time-out interval elapses.

DWORD WaitForSingleObjectEx(

HANDLE hHandle,	// handle of object to wait for
DWORD dwMilliseconds,	// time-out interval in milliseconds
BOOL bAlertable	// return to execute I/O completion routine if TRUE
);
Parameters

hHandle

Identifies the object. For a list of the object types whose handles can be specified, see the following Remarks section.

Windows NT: The handle must have SYNCHRONIZE access. For more information, see Access Masks and Access Rights.

dwMilliseconds

Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the object’s state is nonsignaled and no completion routines or APCs are queued. If dwMilliseconds is zero, the function tests the object’s state and checks for queued completion routines or APCs and then returns immediately. If dwMilliseconds is INFINITE, the function’s time-out interval never elapses.

bAlertable

Specifies whether the function returns when the system queues an I/O completion routine or APC. If TRUE, the function returns and the completion routine or APC function is executed. If FALSE, the function does not return, and the completion routine or APC function is not executed.

A completion routine is queued when the ReadFileEx or WriteFileEx function in which it was specified has completed. The wait function returns and the completion routine is called only if bAlertable is TRUE, and the calling thread is the thread that initiated the read or write operation. An APC is queued when you call QueueUserAPC.

Return Values

If the function succeeds, the return value indicates the event that caused the function to return.

If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

The successful return value is one of the following:

Value	Meaning
WAIT_OBJECT_0	The state of the specified object is signaled.
WAIT_ABANDONED	The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to nonsignaled.
WAIT_IO_COMPLETION	One or more I/O completion routines are queued for execution.
WAIT_TIMEOUT	The time-out interval elapsed, and the object’s state is nonsignaled.
Remarks

The WaitForSingleObjectEx function determines whether the wait criteria have been met. If the criteria have not been met, the calling thread enters an efficient wait state, consuming very little processor time while waiting for the criteria to be met.

Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one.

The WaitForSingleObjectEx function can wait for the following objects:

Object	Description
Change notification	The FindFirstChangeNotification function returns the handle. A change notification object’s state is signaled when a specified type of change occurs within a specified directory or directory tree.
Console input	The handle is returned by the CreateFile function when the CONIN$ value is specified, or by the GetStdHandle function. The object’s state is signaled when there is unread input in the console’s input buffer, and it is nonsignaled when the input buffer is empty.
Event	The CreateEvent or OpenEvent function returns the handle. An event object’s state is set explicitly to signaled by the SetEvent or PulseEvent function. A manual-reset event object’s state must be reset explicitly to nonsignaled by the ResetEvent function. For an auto-reset event object, the wait function resets the object’s state to nonsignaled before returning. Event objects are also used in overlapped operations, in which the state is set by the system.
Mutex	The CreateMutex or OpenMutex function returns the handle. A mutex object’s state is signaled when it is not owned by any thread. The wait function requests ownership of the mutex for the calling thread, changing the mutex’s state to nonsignaled when ownership is granted.
Process	The CreateProcess or OpenProcess function returns the handle. A process object’s state is signaled when the process terminates.
Semaphore	The CreateSemaphore or OpenSemaphore function returns the handle. A semaphore object maintains a count between zero and some maximum value. Its state is signaled when its count is greater than zero and nonsignaled when its count is zero. If the current state is signaled, the wait function decreases the count by one.
Thread	The CreateProcess, CreateThread, or CreateRemoteThread function returns the handle. A thread object’s state is signaled when the thread terminates.
Timer	The CreateWaitableTimer or OpenWaitableTimer function returns the handle. Activate the timer by calling the SetWaitableTimer function. The state of an active timer is signaled when it reaches its due time. You can deactivate the timer by calling the CancelWaitableTimer function. The state of an active timer is signaled when it reaches its due time. You can deactivate the timer by calling the CancelWaitableTimer function.
In some circumstances, you can specify a handle of a file, named pipe, or communications device as a synchronization object in lpHandles. However, their use for this purpose is discouraged.

You have to be careful when using the wait functions and DDE. If a thread creates any windows, it must process messages. DDE sends messages to all windows in the system. If you have a thread that uses a wait function with no time-out interval, the system will deadlock. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects or MsgWaitForMultipleObjectsEx, rather than WaitForSingleObjectEx.

See Also

CancelWaitableTimer, CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, CreateWaitableTimer, FindFirstChangeNotification, GetStdHandle, MsgWaitForMultipleObjects, MsgWaitForMultipleObjectsEx, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, OpenWaitableTimer, PulseEvent, QueueUserAPC, ReadFileEx, ResetEvent, SetEvent, SetWaitableTimer, WriteFileEx


WaitMessage

The WaitMessage function yields control to other threads when a thread has no other messages in its message queue. The WaitMessage function suspends the thread and does not return until a new message is placed in the thread’s message queue.

BOOL WaitMessage(VOID)

Parameters

This function has no parameters.

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.

See Also

GetMessage, PeekMessage


WaitNamedPipe

The WaitNamedPipe function waits until either a time-out interval elapses or an instance of the specified named pipe is available to be connected to (that is, the pipe’s server process has a pending ConnectNamedPipe operation on the pipe).

BOOL WaitNamedPipe(

LPCTSTR lpNamedPipeName,	// address of name of pipe to wait for
DWORD nTimeOut	// time-out interval, in milliseconds
);
Parameters

lpNamedPipeName

Points to a null-terminated string that specifies the name of the named pipe. The string must include the name of the computer on which the server process is executing. A period may be used for the servername if the pipe is local. The following pipe name format is used:

\\servername\pipe\pipename

nTimeOut

Specifies the number of milliseconds that the function will wait for an instance of the named pipe to be available. One of the following values can be used instead of specifying a number of milliseconds:

Value	Meaning
NMPWAIT_USE_DEFAULT_WAIT	The time-out interval is the default value specified by the server process in the CreateNamedPipe function.
NMPWAIT_WAIT_FOREVER	The function does not return until an instance of the named pipe is available.
Return Values

If an instance of the pipe is available before the time-out interval elapses, the return value is nonzero.

If an instance of the pipe is not available before the time-out interval elapses, the return value is zero. To get extended error information, call GetLastError.

Remarks

If no instances of the specified named pipe exist, the WaitNamedPipe function returns immediately, regardless of the time-out value.

If the function succeeds, the process should use the CreateFile function to open a handle to the named pipe. A return value of TRUE indicates that there is at least one instance of the pipe available. A subsequent CreateFile call to the pipe can fail, because the instance was closed by the server or opened by another client.

See Also

CallNamedPipe, ConnectNamedPipe, CreateFile, CreateNamedPipe


WideCharToMultiByte

The WideCharToMultiByte function maps a wide-character string to a new character string. The new character string is not necessarily from a multibyte character set.

int WideCharToMultiByte(

UINT CodePage,	// code page
DWORD dwFlags,	// performance and mapping flags
LPCWSTR lpWideCharStr,	// address of wide-character string
int cchWideChar,	// number of characters in string
LPSTR lpMultiByteStr,	// address of buffer for new string
int cchMultiByte,	// size of buffer
LPCSTR lpDefaultChar,	// address of default for unmappable characters
LPBOOL lpUsedDefaultChar	// address of flag set when default char. used
);
Parameters

CodePage

Specifies the code page used to perform the conversion. This parameter can be given the value of any codepage that is installed or available in the system. The following values may be used to specify one of the system default code pages:

Value	Meaning
CP_ACP	ANSI code page
CP_MACCP	Macintosh code page
CP_OEMCP	OEM code page
dwFlags

A set of bit flags that specify the handling of unmapped characters. The function performs more quickly when none of these flags is set. The following flag constants are defined:

Value	Meaning
WC_COMPOSITECHECK	Convert composite characters to precomposed characters.
WC_DISCARDNS	Discard nonspacing characters during conversion.
WC_SEPCHARS	Generate separate characters during conversion. This is the default conversion behavior.
WC_DEFAULTCHAR	Replace exceptions with the default character during conversion.
When WC_COMPOSITECHECK is specified, the function converts composite characters to precomposed characters. A composite character consists of a base character and a nonspacing character, each having different character values. A precomposed character has a single character value for a base/nonspacing character combination. In the character è, the e is the base character, and the accent grave mark is the nonspacing character.

When an application specifies WC_COMPOSITECHECK, it can use the last 3 flags in this list (WC_DISCARDNS, WC_SEPCHARS, and WC_DEFAULTCHAR) to customize the conversion to precomposed characters. These flags determine the function’s behavior when there is no precomposed mapping for a base/nonspace character combination in a wide-character string. These last 3 flags can only be used if the WC_COMPOSITECHECK flag is set.

The function’s default behavior is to generate separate characters (WC_SEPCHARS) for unmapped composite characters.

lpWideCharStr

Points to the wide-character string to be converted.

cchWideChar

Specifies the number of characters in the string pointed to by the lpWideCharStr parameter. If this value is −1, the string is assumed to be null-terminated and the length is calculated automatically.

lpMultiByteStr

Points to the buffer to receive the translated string.

cchMultiByte

Specifies the size in characters of the buffer pointed to by the lpMultiByteStr parameter. If this value is zero, the function returns the number of bytes required for the buffer. (In this case, the lpMultiByteStr buffer is not used.)

lpDefaultChar

Points to the character used if a wide character cannot be represented in the specified code page. If this parameter is NULL, a system default value is used. The function is faster when both lpDefaultChar and lpUsedDefaultChar are NULL.

lpUsedDefaultChar

Points to a flag that indicates whether a default character was used. The flag is set to TRUE if one or more wide characters in the source string cannot be represented in the specified code page. Otherwise, the flag is set to FALSE. This parameter may be NULL. The function is faster when both lpDefaultChar and lpUsedDefaultChar are NULL.

Return Values

If the function succeeds, and cchMultiByte is nonzero, the return value is the number of bytes written to the buffer pointed to by lpMultiByteStr.

If the function succeeds, and cchMultiByte is zero, the return value is the required size, in bytes, for a buffer that can receive the translated string.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER

Remarks

The lpMultiByteStr and lpWideCharStr pointers must not be the same. If they are the same, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER.

An application can use the lpDefaultChar parameter to change the default character used for the conversion.

As noted earlier, the WideCharToMultiByte function operates most efficiently when both lpDefaultChar and lpUsedDefaultChar are NULL. The following table shows the behavior of WideCharToMultiByte for the four combinations of lpDefaultChar and lpUsedDefaultChar :

lpDefaultChar	lpUsedDefaultChar	Result
NULL	NULL	No default checking. This is the most efficient, quick way to use this function.
non-NULL	NULL	Uses the specified default character, but does not set lpUsedDefaultChar.
NULL	non-NULL	Uses the system default character and sets lpUsedDefaultChar if necessary.
non-NULL	non-NULL	Uses the specified default character and sets lpUsedDefaultChar if necessary.
See Also

MultiByteToWideChar


WidenPath

The WidenPath function redefines the current path as the area that would be painted if the path were stroked using the pen currently selected into the given device context.

BOOL WidenPath(

HDC hdc	// handle of device context
);
Parameters

hdc

Identifies a device context that contains a closed path.

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 one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY

Remarks

The WidenPath function is successful only if the current pen is a geometric pen created by the ExtCreatePen function, or if the pen is created with the CreatePen function and has a width, in device units, of more than one.

The device context identified by the hdc parameter must contain a closed path.

Any Bézier curves in the path are converted to sequences of straight lines approximating the widened curves. As such, no Bézier curves remain in the path after WidenPath is called.

See Also

BeginPath, CreatePen, EndPath, ExtCreatePen, SetMiterLimit


WindowFromDC

The WindowFromDC function returns the handle of the window associated with the given display device context (DC). Output functions that use the given device context draw into this window.

HWND WindowFromDC(

HDC hDC	// handle of window
);
Parameters

hDC

Identifies the device context from which a handle for the associated window is to be retrieved.

Return Values

If the function succeeds, the return value is the handle of the window associated with the given display device context.

If the function fails, the return value is NULL.

See Also

GetDC, GetDCEx, GetWindowDC


WindowFromPoint

The WindowFromPoint function retrieves the handle of the window that contains the specified point.

HWND WindowFromPoint(

POINT Point	// structure with point
);
Parameters

Point

Specifies a POINT structure that defines the point to be checked.

Return Values

If the function succeeds, the return value is the handle of the window that contains the point. If no window exists at the given point, the return value is NULL.

Remarks

The WindowFromPoint function does not retrieve the handle of a hidden or disabled window, even if the point is within the window. An application should use the ChildWindowFromPoint function for a nonrestrictive search.

See Also

ChildWindowFromPoint, POINT, WindowFromDC


WindowProc

The WindowProc function is an application-defined callback function that processes messages sent to a window.

LRESULT CALLBACK WindowProc(

HWND hwnd,	// handle of window
UINT uMsg,	// message identifier
WPARAM wParam,	// first message parameter
LPARAM lParam	// second message parameter
);
Parameters

hwnd

Identifies the window.

uMsg

Specifies the message.

wParam

Specifies additional message information. The contents of this parameter depend on the value of the uMsg parameter.

lParam

Specifies additional message information. The contents of this parameter depend on the value of the uMsg parameter.

Return Values

The return value is the result of the message processing and depends on the message sent.

Remarks

WindowProc is a placeholder for the application-defined function name.

See Also

CallWindowProc, DefWindowProc, RegisterClass


WinExec

The WinExec function runs the specified application.

This function is provided for compatibility with earlier versions of Windows. For Win32-based applications, use the CreateProcess function.

UINT WinExec(

LPCSTR lpCmdLine,	// address of command line
UINT uCmdShow	// window style for new application
);
Parameters

lpCmdLine

Points to a null-terminated character string that contains the command line (filename plus optional parameters) for the application to be executed. If the name of the executable file in the lpCmdLine parameter does not contain a directory path, Windows searches for the executable file in this sequence:

1.	The directory from which the application loaded.

2.	The current directory.

3.	The Windows system directory. The GetSystemDirectory function retrieves the path of this directory.

4.	The Windows directory. The GetWindowsDirectory function retrieves the path of this directory.

5.	The directories listed in the PATH environment variable.

uCmdShow

Specifies how a Windows-based application window is to be shown and is used to supply the wShowWindow member of the STARTUPINFO parameter to the CreateProcess function. For a list of the acceptable values, see the description of the nCmdShow parameter of the ShowWindow function. For a non-Windows − based application, the PIF file, if any, for the application determines the window state.

Return Values

If the function succeeds, the return value is greater than 31.

If the function fails, the return value is one of the following error values:

Value	Meaning
0	The system is out of memory or resources.
ERROR_BAD_FORMAT	The .EXE file is invalid (non-Win32 .EXE or error in .EXE image).
ERROR_FILE_NOT_FOUND	The specified file was not found.
ERROR_PATH_NOT_FOUND	The specified path was not found.
Remarks

Win32-based applications should use the CreateProcess function rather than this function. The WinExec function exists in Win32 to provide compatibility with earlier versions of Windows. For more information about how the WinExec function is implemented, see the Remarks section of the LoadModule function.

In Win32, the WinExec function returns when the started process calls the GetMessage function or a time-out limit is reached. To avoid waiting for the time out delay, call the GetMessage function as soon as possible in any process started by a call to WinExec.

See Also

CreateProcess, GetMessage, GetSystemDirectory, GetWindowsDirectory, LoadModule, ShowWindow


WinHelp

The WinHelp function starts Windows Help (WINHELP.EXE) and passes additional data indicating the nature of the help requested by the application. The application specifies the name and, where required, the directory path of the help file to display.

BOOL WinHelp(

HWND hWndMain,	// handle of window requesting Help
LPCTSTR lpszHelp,	// address of directory-path string
UINT uCommand,	// type of Help
DWORD dwData	// additional data
);
Parameters

hWndMain

Identifies the window requesting Help. The WinHelp function uses this handle to keep track of which applications have requested Help.

lpszHelp

Points to a null-terminated string containing the path, if necessary, and the name of the Help file that the Help application is to display.

The filename may be followed by an angle bracket (>) and the name of a secondary window if the topic is to be displayed in a secondary window rather than in the primary window. The name of the secondary window must have been defined in the [WINDOWS] section of the Help project (.HPJ) file.

uCommand

Specifies the type of help requested. For a list of possible values and how they affect the value to place in the dwData parameter, see the Remarks section.

dwData

Specifies additional data. The value used depends on the value of the uCommand parameter. For a list of possible values, see the Remarks section.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Before closing the window that requested Help, the application must call WinHelp with the uCommand parameter set to HELP_QUIT. Until all applications have done this, Windows Help will not terminate. Note that calling WinHelp with the HELP_QUIT command is not necessary if you used the HELP_CONTEXTPOPUP command to start Help

The following table shows the possible values for the uCommand parameter and the corresponding formats of the dwData parameter:

uCommand	Action	dwData
HELP_COMMAND	Executes a Help macro or macro string.	Address of a string that specifies the name of the Help macro(s) to execute. If the string specifies multiple macros names, the names must be separated by semicolons. You must use the short form of the macro name for some macros because Help does not support the long name.
HELP_CONTENTS	Displays the topic specified by the Contents option in the [OPTIONS] section of the .HPJ file. This is for backward compatibility. New applications should provide a .CNT file and use the HELP_FINDER command.	Ignored, set to 0.
HELP_CONTEXT	Displays the topic identified by the specified context identifier defined in the [MAP] section of the .HPJ file.	Unsigned long integer containing the context identifier for the topic.
HELP_CONTEXTPOPUP	Displays, in a pop-up window, the topic identified by the specified context identifier defined in the [MAP] section of the .HPJ file.	Unsigned long integer containing the context identifier for a topic.
HELP_FORCEFILE	Ensures that WinHelp is displaying the correct help file. If the incorrect help file is being displayed, WinHelp opens the correct one; otherwise, there is no action.	Ignored, set to 0.
HELP_HELPONHELP	Displays help on how to use Windows Help, if the WINHELP.HLP file is available.	Ignored, set to 0.
HELP_INDEX	Displays the Index in the Help Topics dialog box. This command is for backward compatibility. New applications should use the HELP_FINDER command.	Ignored, set to 0.
HELP_KEY	Displays the topic in the keyword table that matches the specified keyword, if there is an exact match. If there is more than one match, displays the Index with the topics listed in the Topics Found list box.	Address of a keyword string.
HELP_MULTIKEY	Displays the topic specified by a keyword in an alternative keyword table.	Address of a MULTIKEYHELP structure that specifies a table footnote character and a keyword.
HELP_PARTIALKEY	Displays the topic in the keyword table that matches the specified keyword, if there is an exact match. If there is more than one match, displays the Index tab. To display the Index without passing a keyword (the third result), you should use a pointer to an empty string.	Address of a keyword  string.
HELP_QUIT	Informs the Help application that it is no longer needed. If no other applications have asked for Help, Windows closes the Help application.	Ignored, set to 0.
HELP_SETCONTENTS	Specifies the Contents topic. The Help application displays this topic when the user clicks the Contents button.	Unsigned long integer containing the context identifier for the Contents topic.
HELP_SETINDEX	Specifies a keyword table to be displayed in the Index of the Help Topics dialog box.	Unsigned long integer containing the context identifier for the Index topic.
HELP_SETWINPOS	Displays the Help window, if it is minimized or in memory, and sets its size and position as specified.	Address of a HELPWININFO structure that specifies the size and position of either a primary or secondary Help window.
See Also

HELPWININFO, MULTIKEYHELP


WinLoadTrustProvider [New - Windows NT]
WinLoadTrustProvider

[New - Windows NT]

The WinLoadTrustProvider function loads a trust provider DLL into the address space of the calling process. The function loads the trust provider that has registered itself as being able to process the specified action identifier. You can use WinLoadTrustProvider to determine whether the local computer has a trust provider that supports the specified action identifier. WinLoadTrustProvider does not perform the action.

BOOL WinLoadTrustProvider(

GUID * ActionID	// pointer to a trust provider action identifier
);
Parameters

ActionID

Pointer to a GUID structure that identifies a trust provider action.

The WinTrust service is designed to work with trust providers implemented by third parties. Each trust provider provides its own unique set of action identifiers. For information about the action identifiers supported by a trust provider, see the documentation for that trust provider.

Return Values

If the function locates and loads a trust provider that supports the specified action identifier, the return value is a nonzero value.

If the function fails to locate or load the trust provider, the return value is zero. To get extended error information, call GetLastError.

Remarks

You do not need to call the WinLoadTrustProvider function before calling the WinVerifyTrust function to perform the specified action. WinVerifyTrust automatically loads the trust provider if it has not already been loaded. Preloading is recommended, however, because it reduces the time required for the first call to WinVerifyTrust.

See Also

GUID, WinVerifyTrust


WinMain

The WinMain function is called by the system as the initial entry point for a Win32-based application.

int WINAPI WinMain(

HINSTANCE hInstance,	// handle to current instance
HINSTANCE hPrevInstance,	// handle to previous instance
LPSTR lpCmdLine,	// pointer to command line
int nCmdShow	// show state of window
);
Parameters

hInstance

Identifies the current instance of the application.

hPrevInstance

Identifies the previous instance of the application. For a Win32-based application, this parameter is always NULL. If you need to detect whether another instance already exists, create a named mutex using the CreateMutex function. If the GetLastError function returns ERROR_ALREADY_EXISTS, another instance of your application exists (it created the mutex).

lpCmdLine

Points to a null-terminated string specifying the command line for the application.

nCmdShow

Specifies how the window is to be shown. This parameter can be one of the following values:

Value	Meaning
SW_HIDE	Hides the window and activates another window.
SW_MINIMIZE	Minimizes the specified window and activates the top-level window in the system’s list.
SW_RESTORE	Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position (same as SW_SHOWNORMAL).
SW_SHOW	Activates a window and displays it in its current size and position.
SW_SHOWMAXIMIZED	Activates a window and displays it as a maximized window.
SW_SHOWMINIMIZED	Activates a window and displays it as an icon.
SW_SHOWMINNOACTIVE	Displays a window as an icon. The active window remains active.
SW_SHOWNA	Displays a window in its current state. The active window remains active.
SW_SHOWNOACTIVATE	Displays a window in its most recent size and position. The active window remains active.
SW_SHOWNORMAL	Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position (same as SW_RESTORE).
Return Values

If the function succeeds, terminating when it receives a WM_QUIT message, it should return the exit value contained in that message’s wParam parameter. If the function terminates before entering the message loop, it should return 0.

Remarks

WinMain initializes an application, displays its main window, and then enters a message retrieval-and-dispatch loop that is the top-level control structure for the remainder of the application’s execution. The message loop terminates when a WM_QUIT message is received. At that point, WinMain exits the application, returning the value passed in the WM_QUIT message’s wParam parameter. If WM_QUIT was received as a result of calling PostQuitMessage, the value of wParam is the value of the PostQuitMessage function’s nExitCode parameter. For more information, see Creating a Message Loop.

See Also

CreateMutex, DispatchMessage, GetMessage, PostQuitMessage, TranslateMessage


WinSubmitCertificate [New - Windows NT]
WinSubmitCertificate

[New - Windows NT]

The WinSubmitCertificate function passes a WIN_CERTIFICATE structure to all trust providers registered with the WinTrust service.

BOOL WinSubmitCertificate(

LPWIN_CERTIFICATE lpCertificate	// pointer to a WIN_CERTIFICATE structure
);
Parameters

lpCertificate

Pointer to a WIN_CERTIFICATE structure.

Return Values

If the function succeeds, the return value is a nonzero value.

If the lpCertificate parameter is invalid, the return value is zero. To get extended error information, call GetLastError.

Remarks

A call to WinSubmitCertificate causes WinTrust to load all registered trust providers and submit the certificate to them. Each trust provider can save a copy of the certificate for future use, or discard it. For example, Microsoft’s Software Publisher Trust Provider might save certificates related to software publishing, but discard other certificates. WinSubmitCertificate does not return any indication of whether any trust provider saved the certificate.

See Also

WIN_CERTIFICATE


WinTrustProviderClientInitialize [New - Windows NT]
WinTrustProviderClientInitialize

[New - Windows NT]

The WinTrustProviderClientInitialize function is an initialization function that WinTrust calls when it loads the client component of a trust provider DLL. Each trust provider must export a WinTrustProviderClientInitialize function.

BOOL WinTrustProviderClientInitialize(

DWORD dwWinTrustRevision,	// WinTrust revision level
LPWINTRUST_CLIENT_TP_INFO lpWinTrustInfo,	// pointer to information about WinTrust
LPWSTR lpProviderName,	// administrator-assigned name of the trust provider
LPWINTRUST_PROVIDER_CLIENT_INFO *lpTrustProviderInfo	// receives information about the trust provider
);
Parameters

dwWinTrustRevision

Indicates the revision level of the WinTrust component that calls this function. WinTrust sets this value to WIN_TRUST_REVISION_1_0.

lpWinTrustInfo

Pointer to a WINTRUST_CLIENT_TP_INFO structure that contains information that WinTrust passes to the trust provider. This structure includes a dispatch table of functions implemented by WinTrust for use by the client component of a trust provider.

The information in this buffer is read-only. It is valid until the trust provider DLL is unloaded. The trust provider can reference the information rather than copy it.

lpProviderName

Pointer to a null-terminated Unicode string that contains the trust provider name. The system administrator assigned this name to the registry key that stores configuration information for the trust provider. The pointer is read-only and valid until the trust provider DLL is unloaded. The trust provider can reference the information rather than copy it.

lpTrustProviderInfo

Pointer to a variable that receives a pointer to a buffer allocated by the trust provider. The buffer contains a WINTRUST_PROVIDER_CLIENT_INFO structure with information about the trust provider. The information includes the revision level of the trust provider, a dispatch table, and an array of GUIDs that identify the action identifiers that the trust provider supports. WinTrust treats the buffer as read-only, and continues to reference this buffer until it unloads the trust provider DLL. The trust provider must not change the information in the buffer, or deallocate the memory before it is unloaded; doing so could corrupt the system.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

When WinTrust loads a trust provider, it calls the trust provider’s WinTrustProviderClientInitialize function. This gives the trust provider an opportunity to initialize itself, and to exchange information between WinTrust and the trust provider.

The LPWINTRUST_PROVIDER_CLIENT_INITIALIZE type is a pointer to a WinTrustProviderClientInitialize function.

See Also

WINTRUST_CLIENT_TP_INFO, WINTRUST_PROVIDER_CLIENT_INFO


WinTrustProviderClientUnload [New - Windows NT]
WinTrustProviderClientUnload

[New - Windows NT]

The WinTrustProviderClientUnload function indicates that WinTrust is preparing to unload the trust provider DLL from the client application. However, WinTrust does not guarantee that it will call this function before the client process exits. Therefore, the trust provider should use other cleanup mechanisms, if necessary.

VOID WinTrustProviderClientUnload(

LPVOID lpTrustProviderInfo	// pointer to buffer allocated by the trust provider
);
Parameters

lpTrustProviderInfo

Pointer to the buffer that the trust provider allocated during its initialization. The trust provider passed this pointer to WinTrust in the WinTrustProviderClientInitialize call.

Return Values

None.

Remarks

The LPWINTRUST_PROVIDER_CLIENT_UNLOAD type is a pointer to a WinTrustProviderClientUnload function.

See Also

WinTrustProviderClientInitialize


WinTrustProviderPing [New - Windows NT]
WinTrustProviderPing

[New - Windows NT]

The WinTrustProviderPing function enables the client component of a trust provider to contact its server counterpart.

The current release of WinTrust does not include the WinTrust server component. Consequently, WinTrust does not implement this function and trust provider DLLs do not need to implement it.

DWORD WinTrustProviderPing(

LPWSTR  lpProviderName,	// administrator-assigned name of the trust provider
DWORD dwClientParameter,	// parameter passed by client to server
LPDWORD lpdwServerReturnValue	// receives value returned by server
);
Parameters

lpProviderName

Pointer to a null-terminated Unicode string that contains the name of the trust provider. The system administrator assigned this name to the registry key that stores configuration information for the trust provider. WinTrust passes this name to the client component of the trust provider in the WinTrustProviderClientInitialize call.

dwClientParameter

A value specified by the client component of the trust provider. WinTrust passes this value to the server component of the trust provider.

lpdwServerReturnValue

Pointer to a DWORD that receives the value returned by the server component of the trust provider.

Remarks

The LPWINTRUST_PROVIDER_PING type is a pointer to a WinTrustProviderPing function.

See Also

WinTrustProviderClientInitialize, WinTrustProviderServerInitialize


WinTrustProviderServerInitialize [New - Windows NT]
WinTrustProviderServerInitialize

[New - Windows NT]

The WinTrustProviderServerInitialize function is an initialization function that WinTrust calls when it loads the server component of a trust provider DLL.

The current release of WinTrust does not include the WinTrust server component. Consequently, WinTrust does not call this function and trust provider DLLs do not need to export it.

BOOL WinTrustProviderServerInitialize(

DWORD dwWinTrustRevision,	// WinTrust revision level
LPWINTRUST_SERVER_TP_INFO lpWinTrustInfo,	// pointer to information about WinTrust
LPWSTR lpProviderName,	// pointer to the name of the trust provider
LPWINTRUST_PROVIDER_SERVER_INFO *lpTrustProviderInfo	// pointer to buffer that receives information about the trust provider
);
Parameters

dwWinTrustRevision

Indicates the revision level of the WinTrust component that calls this function. WinTrust sets this value to WIN_TRUST_REVISION_1_0.

lpWinTrustInfo

Pointer to a WINTRUST_SERVER_TP_INFO structure that contains information that WinTrust passes to the trust provider. This structure includes a dispatch table of functions implemented by WinTrust for use by the server component of a trust provider.

The information in this buffer is read-only. It is valid until the trust provider DLL is unloaded. The trust provider can reference the information rather than copy it.

lpProviderName

Pointer to a null-terminated Unicode string that contains the name that the system administrator assigned to the registry key that stores configuration information for the trust provider. The pointer is read-only and valid until the trust provider DLL is unloaded. The trust provider can reference the information rather than copy it.

lpTrustProviderInfo

Pointer to a variable that receives a pointer to a buffer allocated by the trust provider. The buffer contains a WINTRUST_PROVIDER_SERVER_INFO structure with information about the trust provider. The information includes the revision level of the trust provider and a dispatch table. WinTrust treats the buffer as read-only, and continues to reference this buffer until it unloads the trust provider DLL. The trust provider must not change the information in the buffer, or deallocate the memory before it is unloaded; doing so could corrupt the system.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The LPWINTRUST_PROVIDER_SERVER_INITIALIZE type is a pointer to a WinTrustProviderServerInitialize function.

See Also

WINTRUST_PROVIDER_SERVER_INFO, WINTRUST_SERVER_TP_INFO


WinTrustProviderServerUnload [New - Windows NT]
WinTrustProviderServerUnload

[New - Windows NT]

The WinTrustProviderServerUnload function indicates that WinTrust is preparing to unload the trust provider DLL from the WinTrust server process.

The current release of WinTrust does not include the WinTrust server component. Consequently, a trust provider DLL does not need to implement this function.

VOID WinTrustProviderServerUnload(

LPVOID lpTrustProviderInfo	// pointer to buffer allocated by the trust provider
);
Parameters

lpTrustProviderInfo

Pointer to the buffer that the trust provider allocated during its initialization. The trust provider passed this pointer to WinTrust in the WinTrustProviderServerInitialize call.

Return Values

None.

Remarks

The LPWINTRUST_PROVIDER_SERVER_UNLOAD type is a pointer to a WinTrustProviderServerUnload function.

See Also

WinTrustProviderServerInitialize


WinTrustProviderSubmitCertificate [New - Windows NT]
WinTrustProviderSubmitCertificate

[New - Windows NT]

The WinTrustProviderSubmitCertificate function passes a WIN_CERTIFICATE structure to a trust provider. When an application calls the WinSubmitCertificate function, WinTrust loads and calls the WinTrustProviderSubmitCertificate function of all registered trust providers.

VOID WinTrustProviderSubmitCertificate (

LPWIN_CERTIFICATE  lpCertificate	// pointer to the certificate
);
Parameters

lpCertificate

Pointer to a WIN_CERTIFICATE structure that may contain a certificate of interest to the trust provider.

Return Values

None.

Remarks

Each trust provider can either save the certificate for future use, or ignore it.

WinTrust calls the WinTrustProviderSubmitCertificate function only on the client component of the trust provider.

Each trust provider must implement the WinTrustProviderSubmitCertificate function. The trust provider provides WinTrust with a pointer to its implementation when WinTrust calls the trust provider’s WinTrustProviderClientInitialize initialization function.

The LPWINTRUST_PROVIDER_SUBMIT_CERTIFICATE type is a pointer to a WinTrustProviderSubmitCertificate function.

See Also

WIN_CERTIFICATE, WinTrustProviderClientInitialize


WinTrustProviderVerifyTrust [New - Windows NT]
WinTrustProviderVerifyTrust

[New - Windows NT]

The WinTrustProviderVerifyTrust function performs a specified verification action on a specified subject. When an application calls the WinVerifyTrust function, WinTrust calls the WinTrustProviderVerifyTrust function of the trust provider that supports the specified action identifier.

LONG WinTrustProviderVerifyTrust(

HWND hwnd,	// handle to a window for interacting with the user
GUID *ActionID,	// pointer to a trust provider action identifier
LPVOID  ActionData	// pointer to an action-specific data structure
);
Parameters

hwnd

Handle to the caller’s window. The trust provider can use this value to determine whether it can interact with the user to perform the verification operation indicated by the action identifier. However, trust providers typically perform verification operations without input from the user. This parameter can be one of the following values.

Value	Meaning
INVALID_HANDLE_VALUE	There is no interactive user. The trust provider performs the verification operation without the user’s assistance.
zero	The trust provider can use the interactive desktop to display its user interface.
A valid window handle	The trust provider can assume that any value other than zero or INVALID_HANDLE_VALUE is a valid window handle that it can use to interact with the user.
ActionID

Pointer to a GUID structure that identifies the action to perform. Each trust provider supports a unique set of action identifiers. The trust provider determines whether the subject identified by the ActionData parameter is trusted for the specified action.

ActionData

Pointer to a buffer that contains information that the trust provider needs to process the specified action identifier. Typically, the data in the buffer includes information that identifies the subject that the trust provider must evaluate. The format and contents of the buffer depend on the action identifier and the trust provider.

Return Values

If the trust provider verifies that the subject is trusted for the specified action, the return value is ERROR_SUCCESS.

Otherwise, the return value is a status code that indicates the error that occurred. For example, a trust provider might indicate that the subject is not trusted, or is trusted but with limitations or warnings. The return value can be a trust-provider − specific value described in the documentation for an individual trust provider, or it can be one of the following error codes defined in WINERROR.H.

Value	Meaning
TRUST_E_SUBJECT_NOT_TRUSTED	The subject is not trusted for the specified action. Most trust providers return a more detailed error code that describes the reason that the subject is not trusted.
TRUST_E_ACTION_UNKNOWN	The trust provider does not support the specified action.
TRUST_E_SUBJECT_FORM_UNKNOWN	The trust provider does not support the form specified for the subject.
Remarks

Each trust provider DLL must implement the WinTrustProviderVerifyTrust function. WinTrust gets a pointer to the trust provider’s WinTrustProviderVerifyTrust implementation when WinTrust calls the trust provider’s WinTrustProviderClientInitialize initialization function.

A trust provider’s WinTrustProviderVerifyTrust function executes in the process of the application that called the WinVerifyTrust function. The function also executes in the security context of the application.

The LPWINTRUST_PROVIDER_VERIFY_TRUST type is a pointer to a WinTrustProviderVerifyTrust function.

See Also

GUID, WinTrustProviderClientInitialize, WinVerifyTrust


WinTrustSipInitialize [New - Windows NT]
WinTrustSipInitialize

[New - Windows NT]

The WinTrustSipInitialize function is an initialization function that WinTrust calls when it loads a Subject Interface Package (SIP) DLL. Each SIP must export a WinTrustSipInitialize function.

BOOL WinTrustSipInitialize(

DWORD dwWinTrustRevision,	// WinTrust revision level
LPWINTRUST_SIP_INFO *lpSipInfo	// receives a pointer to a SIP information structure
);
Parameters

dwWinTrustRevision

Indicates the revision level of the WinTrust component that calls this function. WinTrust sets this value to WIN_TRUST_REVISION_1_0.

lpSipInfo

Pointer to a variable that receives a pointer to a buffer allocated by the SIP. The buffer contains a WINTRUST_SIP_INFO structure that describes the SIP. WinTrust continues to reference this buffer until it unloads the SIP. The SIP must not change the information in the buffer, or deallocate the memory before it is unloaded; doing so could corrupt the system.

Return Values

If the SIP successfully initializes itself, the return value is a nonzero value.

If the SIP did not successfully initialize itself, the return value is zero. In this case, WinTrust makes no further calls to the SIP. The SIP can use the SetLastError function to provide extended error information.

Remarks

The LPWINTRUST_SUBJECT_PACKAGE_INITIALIZE type is a pointer to a WinTrustSipInitialize function.

See Also

WINTRUST_SIP_INFO


WinTrustSubjectCheckContentInfo [New - Windows NT]
WinTrustSubjectCheckContentInfo

[New - Windows NT]

The WinTrustSubjectCheckContentInfo function verifies that a specified certificate adequately represents the contents of the specified subject.

BOOL WinTrustSubjectCheckContentInfo(

LPWIN_TRUST_SIP_SUBJECT  lpSubject,	// pointer to description of the subject
LPWIN_CERTIFICATE lpSignedData	// pointer to a certificate for the subject
);
Parameters

lpSubject

Pointer to a WIN_TRUST_SIP_SUBJECT structure that describes the subject to compare to the certificate.

lpSignedData

Pointer to a WIN_CERT_TYPE_PKCS_SIGNED_DATA type of WIN_CERTIFICATE structure. The data in the bCertificate member of this structure is in the format of a PKCS #7 Signed Data structure. For details on this data format, see The Public-Key Cryptography Standards (PKCS), published by RSA Data Security, Inc.

The SIP can use information from the ContentInfo member of this PKCS #7 structure to determine what must be verified about the subject. For example, a Portable Executable (PE) image may include resource information and debug information in a digest of the image. If it does, the SIP can find that information in the ContentInfo member of the corresponding PKCS #7 Signed Data structure. The SIP should not depend on the contents of the PKCS #7 structure other than the ContentInfo member.

Return Values

If the information in lpSignedData adequately represents the subject, the return value is nonzero. Otherwise, the return value is zero.

Remarks

A trust provider calls the WinTrustSubjectCheckContentInfo function to verify that the signature in a certificate matches the contents of a specified subject. The trust provider calls the WinTrust implementation of this function. WinTrust then calls the WinTrustSubjectCheckContentInfo implementation of the appropriate Subject Interface Package (SIP). The appropriate SIP is the one registered to handle the type of subject specified by the lpSubject parameter.

To verify a signature, the trust provider first calls the WinTrustSubjectEnumCertificates function to enumerate the types of certificates contained in the subject. Next, the trust provider calls the WinTrustSubjectGetCertificate function to get the certificate needed to authenticate the subject. Typically, this is a certificate that contains a PKCS #7 Signed Data structure from the subject. Then the trust provider calls WinTrustSubjectCheckContentInfo to determine whether the ContentInfo member of the PKCS #7 Signed Data structure matches the subject. If the return value indicates that the SIP has verified the ContentInfo member, the trust provider must also check the signature of the PKCS #7 Signed Data structure. To do this, the trust provider must digest the PKCS structure and compare it to the signature value in that structure.

Each Subject Interface Package (SIP) DLL must implement the WinTrustSubjectCheckContentInfo function. WinTrust gets a pointer to the SIP’s WinTrustSubjectCheckContentInfo implementation when WinTrust calls the SIP’s WinTrustSipInitialize initialization function.

The SIP implementation of WinTrustSubjectCheckContentInfo compares the information in the PKCS #7’s ContentInfo member to information that it retrieves from the subject identified by the lpSubject parameter. To do this, the SIP generates new ContentInfo information from the subject, which it then compares to the ContentInfo member of the PKCS #7 Signed Data structure. The ContentInfo member contains a message digest of the subject that is important in verifying the validity of the subject. Note that other information in the ContentInfo member may not match the subject. For example, the name of the file is not important because the name can change without affecting the integrity of the subject.

The LPWINTRUST_SUBJECT_CHECK_CONTENT_INFO type is a pointer to a WinTrustSubjectCheckContentInfo function.

See Also

WIN_CERTIFICATE, WIN_TRUST_SIP_SUBJECT, WinTrustSipInitialize, WinTrustSubjectEnumCertificates, WinTrustSubjectGetCertificate


WinTrustSubjectEnumCertificates [New - Windows NT]
WinTrustSubjectEnumCertificates

[New - Windows NT]

The WinTrustSubjectEnumCertificates function determines the types of certificates bundled within a subject. You can retrieve a list of all the certificate types that the subject contains, or you can determine whether the subject contains a specified certificate type.

BOOL WinTrustSubjectEnumCertificates(

LPWIN_TRUST_SIP_SUBJECT  lpSubject,	// pointer to description of the subject
DWORD dwTypeFilter,	// type of certificate to enumerate
LPDWORD lpCertificateCount,	// receives number of certificates of the specified type
LPDWORD lpIndices,	// pointer to an array that receives the certificate types
DWORD dwIndexCount	// size of the array
);
Parameters

lpSubject

Pointer to a WIN_TRUST_SIP_SUBJECT structure that identifies the subject from which to get certificate information.

dwTypeFilter

Specifies the type of certificate to list. This parameter can be zero to list certificates of all types, or it can be one of the following values.

Value	Meaning
WIN_CERT_TYPE_X509	The certificate contains an X.509 Certificate.
WIN_CERT_TYPE_PKCS_SIGNED_DATA	The certificate contains a PKCS SignedData structure.
WIN_CERT_TYPE_RESERVED_1	Reserved.
lpCertificateCount

Pointer to a DWORD that receives the number of certificates of the specified type in the subject identified by lpSubject. This value indicates the number that could be returned even if the lpIndices array is not large enough to hold them all.

lpIndices

Pointer to an array of DWORD values that receives a list of WIN_CERT_TYPE_xxx values indicating the types of certificates bundled within the subject. You can use these certificate type values in the WinTrustSubjectGetCertificate function to retrieve the actual certificates.

The value returned in lpCertificateCount indicates the number of valid entries returned in the array. If dwIndexCount is less than the value returned in lpCertificateCount, the array contains garbage, and you need to call WinTrustSubjectEnumCertificates again with a larger array.

dwIndexCount

Indicates the number of entries that can be returned in the lpIndices array.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

A trust provider calls the WinTrustSubjectEnumCertificates function to retrieve the types of certificates in the specified subject. The trust provider calls the WinTrust implementation of this function. WinTrust then calls the WinTrustSubjectEnumCertificates implementation of the appropriate Subject Interface Package (SIP). The appropriate SIP is the one registered to handle the type of subject specified by the lpSubject parameter.

Each Subject Interface Package (SIP) DLL must implement the WinTrustSubjectEnumCertificates function. WinTrust gets a pointer to the SIP’s WinTrustSubjectEnumCertificates implementation when WinTrust calls the SIP’s WinTrustSipInitialize initialization function.

The LPWINTRUST_SUBJECT_ENUM_CERTIFICATES type is a pointer to a WinTrustSubjectEnumCertificates function.

See Also

WIN_TRUST_SIP_SUBJECT, WinTrustSipInitialize


WinTrustSubjectGetCertHeader [New - Windows NT]
WinTrustSubjectGetCertHeader

[New - Windows NT]

The WinTrustSubjectGetCertHeader function retrieves the header part of a WIN_CERTIFICATE structure from the specified subject. The caller specifies the type of certificate to retrieve. The returned information does not include the data in the bCertificate member of the WIN_CERTIFICATE structure.

BOOL WinTrustSubjectGetCertHeader(

LPWIN_TRUST_SIP_SUBJECT  lpSubject,	// pointer to description of the subject
DWORD dwCertificateIndex,	// type of certificate to retrieve
LPWIN_CERTIFICATE lpCertificateHeader	// pointer to a buffer that receives the certificate header
);
Parameters

lpSubject

Pointer to a WIN_TRUST_SIP_SUBJECT structure that identifies the subject from which to get a certificate header.

dwCertificateIndex

Specifies the type of certificate to retrieve. You can call the WinTrustSubjectEnumCertificates function to enumerate the types of certificates that the subject contains.

lpCertificateHeader

Pointer to a WIN_CERTIFICATE structure that receives the certificate header.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

A trust provider calls the WinTrust implementation of the WinTrustSubjectGetCertHeader function. WinTrust then calls the WinTrustSubjectGetCertHeader implementation of the appropriate Subject Interface Package (SIP). The appropriate SIP is the one registered to handle the type of subject specified by the lpSubject parameter.

Each Subject Interface Package (SIP) DLL must implement the WinTrustSubjectGetCertHeader function. WinTrust gets a pointer to the SIP’s WinTrustSubjectGetCertHeader implementation when WinTrust calls the SIP’s WinTrustSipInitialize initialization function.

The LPWINTRUST_SUBJECT_GET_CERT_HEADER type is a pointer to a WinTrustSubjectGetCertHeader function.

See Also

WIN_CERTIFICATE, WIN_TRUST_SIP_SUBJECT, WinTrustSipInitialize, WinTrustSubjectEnumCertificates


WinTrustSubjectGetCertificate [New - Windows NT]
WinTrustSubjectGetCertificate

[New - Windows NT]

The WinTrustSubjectGetCertificate function retrieves a specified certificate from a subject.

BOOL WinTrustSubjectGetCertificate(

LPWIN_TRUST_SIP_SUBJECT  lpSubject,	// pointer to description of the subject
DWORD dwCertificateIndex,	// type of certificate to retrieve
LPWIN_CERTIFICATE lpCertificate,	// pointer to a buffer that receives the certificate
LPDWORD lpRequiredLength	// pointer to the size, in bytes, of the buffer
);
Parameters

lpSubject

Pointer to a WIN_TRUST_SIP_SUBJECT structure that identifies the subject from which to get a certificate.

dwCertificateIndex

Specifies the type of certificate to retrieve. You can call the WinTrustSubjectEnumCertificates function to enumerate the types of certificates that the subject contains.

lpCertificate

Pointer to buffer that receives the WIN_CERTIFICATE structure header and the associated certificate data.

lpRequiredLength

Pointer to a DWORD. On input, it specifies the size, in bytes, of the lpCertificate buffer. On output, it receives the length of the returned certificate. If the buffer is not large enough to hold the certificate, the function fails, and lpRequiredLength returns the required buffer size.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

A trust provider calls the WinTrust implementation of the WinTrustSubjectGetCertificate function. WinTrust then calls the WinTrustSubjectGetCertificate implementation of the appropriate Subject Interface Package (SIP). The appropriate SIP is the one registered to handle the type of subject specified by the lpSubject parameter.

Each Subject Interface Package (SIP) DLL must implement the WinTrustSubjectGetCertificate function. WinTrust gets a pointer to the SIP’s WinTrustSubjectGetCertificate implementation when WinTrust calls the SIP’s WinTrustSipInitialize initialization function.

The LPWINTRUST_SUBJECT_GET_CERTIFICATE type is a pointer to a WinTrustSubjectGetCertificate function.

See Also

WIN_CERTIFICATE, WIN_TRUST_SIP_SUBJECT, WinTrustSipInitialize, WinTrustSubjectEnumCertificates


WinTrustSubjectGetName [New - Windows NT]
WinTrustSubjectGetName

[New - Windows NT]

The WinTrustSubjectGetName function retrieves the name of a subject from a PKCS #7 Signed Data certificate that represents the subject. A trust provider can use the name to store and retrieve certificates associated with the subject.

BOOL WinTrustSubjectGetName(

LPWIN_TRUST_SIP_SUBJECT  lpSubject,	// pointer to description of the subject
LPWIN_CERTIFICATE lpSignedData,	// pointer to a signed data certificate
LPWSTR lpBuffer,	// pointer to a buffer that receives the subject name
LPDWORD lpRequiredLength	// pointer to the size, in bytes, of the buffer
);
Parameters

lpSubject

Pointer to a WIN_TRUST_SIP_SUBJECT structure that identifies the type of subject. Note that the function retrieves the subject’s name from the lpSignedData structure, not from the subject.

lpSignedData

Pointer to a WIN_CERTIFICATE structure that contains a PKCS #7 Signed Data structure. The function retrieves the subject name from the data associated with this structure.

lpBuffer

Pointer to a buffer that receives a null-terminated, Unicode string that names the subject.

lpRequiredLength

Pointer to a DWORD. On input, it specifies the size, in bytes, of the lpBuffer buffer. On output, it receives the size, in bytes, of the returned string, including the terminating null character. If the buffer is not large enough to hold the string, the function fails, and lpRequiredLength returns the required buffer size.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

A trust provider calls the WinTrust implementation of the WinTrustSubjectGetName function. WinTrust then calls the WinTrustSubjectGetName implementation of the appropriate Subject Interface Package (SIP). The appropriate SIP is the one registered to handle the type of subject specified by the lpSubject parameter.

Each Subject Interface Package (SIP) DLL must implement the WinTrustSubjectGetName function. WinTrust gets a pointer to the SIP’s WinTrustSubjectGetName implementation when WinTrust calls the SIP’s WinTrustSipInitialize initialization function.

A SIP’s implementation of WinTrustSubjectGetName returns a name associated with the subject. This may be a filename, if the subject is a file, or some other string that identifies the subject. The purpose of this function is to provide a string that a trust provider can use to store and retrieve certificates associated with the subject. The name does not need to be unique, but it should identify the subject and be the same each time it is retrieved.

The LPWINTRUST_SUBJECT_GET_NAME type is a pointer to a WinTrustSubjectGetName function.

See Also

WIN_CERTIFICATE, WIN_TRUST_SIP_SUBJECT, WinTrustSipInitialize


WinVerifyTrust [New - Windows NT]
WinVerifyTrust

[New - Windows NT]

The WinVerifyTrust function performs a specified verification action on a specified subject. The function passes the inquiry to the trust provider, if any, that supports the action identifier.

LONG WinVerifyTrust(

HWND hwnd,	// handle to a window for interacting with the user
GUID *ActionID,	// pointer to a trust provider action identifier
LPVOID ActionData	// pointer to a buffer containing action-specific data
);
Parameters

hwnd

Handle to the caller’s window. The trust provider can use this value to determine whether it can interact with the user. However, trust providers typically perform verification actions with input from the user.

This parameter can be one of the following values.

Value	Meaning
INVALID_HANDLE_VALUE	There is no interactive user. The trust provider performs the verification action without the user’s assistance.
Zero	The trust provider can use the interactive desktop to display its user interface.
A valid window handle	A trust provider can treat any value other than INVALID_HANDLE_VALUE or zero as a valid window handle that it can use to interact with the user.
ActionID

Pointer to a GUID structure that identifies an action, and implicitly, the trust provider that supports the action identifier. This value indicates the type of verification action to perform on the subject identified by the ActionData parameter.

The WinTrust service is designed to work with trust providers implemented by third parties. Each trust provider provides its own unique set of action identifiers. For information about the action identifiers supported by a trust provider, see the documentation for that trust provider.

For example, Microsoft provides a Software Publisher Trust Provider that can establish the trustworthiness of software being downloaded from a public network, such as the internet. The Software Publisher Trust Provider supports the following action identifiers.

Value	Description
WIN_SPUB_ACTION_TRUSTED_PUBLISHER
	The ActionData parameter is a pointer to a WIN_SPUB_TRUSTED_PUBLISHER_DATA structure.
WIN_SPUB_ACTION_NT_ACTIVATE_IMAGE
	The ActionData parameter is a pointer to a WIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT structure.
WIN_SPUB_ACTION_PUBLISHED_SOFTWARE
	The ActionData parameter is a pointer to a WIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT structure.
ActionData

Pointer to a buffer that contains information that the trust provider needs to process the specified action identifier. Typically, the data in the buffer includes information that identifies the subject that the trust provider must evaluate.

The format of the data depends on the action identifier. For information about the data required for a specific action identifier, see the documentation for the trust provider that supports that action.

Return Values

If the trust provider verifies that the subject is trusted for the specified action, the return value is ERROR_SUCCESS.

Otherwise, the return value is the status code returned by the trust provider. For example, a trust provider might indicate that the subject is not trusted, or is trusted but with limitations or warnings. The return value can be a trust-provider-specific value described in the documentation for an individual trust provider, or it can be one of the following error codes.

Value	Meaning
TRUST_E_SUBJECT_NOT_TRUSTED	The subject failed the specified verification action. Most trust providers return a more detailed error code that describes the reason for the failure.
TRUST_E_PROVIDER_UNKNOWN	The trust provider is not recognized on this system.
TRUST_E_ACTION_UNKNOWN	The trust provider does not support the specified action.
TRUST_E_SUBJECT_FORM_UNKNOWN	The trust provider does not support the form specified for the subject.
Remarks

The WinVerifyTrust function enables applications to invoke a trust provider to verify that a specified subject satisfies the criteria of a specified verification operation. The ActionID parameter identifies the verification operation, and the ActionData parameter identifies the subject. A trust provider is a DLL registered with WinTrust. When you call WinVerifyTrust, the WinTrust service forwards the call to the registered trust provider, if there is one, that supports the specified action identifier.

For example, the Software Publisher Trust Provider can verify that an executable image file comes from a trusted software publisher and that the file has not been modified since it was published. In this case, the ActionData parameter specifies the name of the file and the type of file, such as a Microsoft Portable Executable image file or a Java class file.

Each trust provider supports a specific set of actions that it can evaluate. Each action has a globally unique identifier (GUID) that identifies it. A trust provider can support any number of action identifiers, but two trust providers cannot support the same action identifier.

See Also

GUID, WIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT


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.

See Also

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

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

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.

See Also

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

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.

See Also

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.

See Also

WNetAddConnection2, WNetCancelConnection2, WNetDisconnectDialog, WNetGetLastError


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.

See Also

WNetAddConnection2, WNetCancelConnection2, WNetConnectionDialog, WNetGetLastError


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

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.

See Also

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.

See Also

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.

See Also

GetLastError


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.

See Also

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

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.

See Also

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_GLOBALNET	All resources on the network.
RESOURCE_REMEMBERED	All remembered (persistent) connections (dwUsage 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 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)

See Also

NETRESOURCE, WNetCloseEnum, WNetEnumResource, WNetGetLastError


WriteConsole

The WriteConsole function writes a character string to a console screen buffer beginning at the current cursor location.

BOOL WriteConsole(

HANDLE hConsoleOutput,	// handle to a console screen buffer
CONST VOID *lpBuffer,	// pointer to buffer to write from
DWORD nNumberOfCharsToWrite,	// number of characters to write
LPDWORD lpNumberOfCharsWritten,	// pointer to number of characters written
LPVOID lpReserved	// reserved
);
Parameters

hConsoleOutput

Identifies the console screen buffer to be written to. The handle must have GENERIC_WRITE access.

lpBuffer

Points to a buffer that contains characters to be written to the screen buffer.

nNumberOfCharsToWrite

Specifies the number of characters to write.

lpNumberOfCharsWritten

Points to a 32-bit variable that receives the number of characters actually written.

lpReserved

Reserved; must be NULL.

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.

Remarks

WriteConsole writes characters to a console screen buffer. It behaves like the WriteFile function, except it can write in either Unicode (wide-character) or ANSI mode. To create an application that maintains a single set of sources compatible with both modes, use WriteConsole rather than WriteFile. Although WriteConsole can be used only with a console screen buffer handle, WriteFile can be used with other handles (such as files or pipes). WriteConsole fails if used with a standard handle that has been redirected to be something other than a console handle.

Although an application can use WriteConsole in ANSI mode to write ANSI characters, consoles do not support ANSI escape sequences. However, some Win32 functions provide equivalent functionality: for example, SetCursorPos, SetConsoleTextAttribute, and GetConsoleCursorInfo.

WriteConsole writes characters to the screen buffer at the current cursor position. The cursor position advances as characters are written. The SetConsoleCursorPosition function sets the current cursor position.

Characters are written using the foreground and background color attributes associated with the screen buffer. The SetConsoleTextAttribute function changes these colors. To determine the current color attributes and the current cursor position, use GetConsoleScreenBufferInfo.

All of the input modes that affect the behavior of WriteFile have the same effect on WriteConsole. To retrieve and set the output modes of a console screen buffer, use the GetConsoleMode and SetConsoleMode functions.

Windows NT: This function uses either Unicode characters or 8-bit characters from the console's current codepage. The console's codepage defaults initially to the system's OEM codepage. To change the console's codepage, use the SetConsoleCP or SetConsoleOutputCP functions, or use the chcp or mode con cp select= commands.

See Also

GetConsoleCursorInfo, GetConsoleMode, GetConsoleScreenBufferInfo, ReadConsole, SetConsoleCP, SetConsoleCursorPosition, SetConsoleMode, SetConsoleOutputCP, SetConsoleTextAttribute, SetCursorPos, WriteFile


WriteConsoleInput

The WriteConsoleInput function writes data directly to the console input buffer.

BOOL WriteConsoleInput(

HANDLE hConsoleInput,	// handle to a console input buffer
CONST INPUT_RECORD *lpBuffer,	// pointer to the buffer for write data
DWORD nLength,	// number of records to write
LPDWORD lpNumberOfEventsWritten	// pointer to number of records written
);
Parameters

hConsoleInput

Identifies the input buffer. The handle must have GENERIC_WRITE access.

lpBuffer

Points to an INPUT_RECORD buffer containing data to be written to the input buffer.

nLength

Specifies the number of input records to be written.

lpNumberOfEventsWritten

Points to a 32-bit variable that receives the number of input records actually written.

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.

Remarks

WriteConsoleInput places input records into the input buffer behind any pending events in the buffer. The input buffer grows dynamically, if necessary, to hold as many events as are written.

Windows NT: This function uses either Unicode characters or 8-bit characters from the console's current codepage. The console's codepage defaults initially to the system's OEM codepage. To change the console's codepage, use the SetConsoleCP or SetConsoleOutputCP functions, or use the chcp or mode con cp select= commands.

See Also

INPUT_RECORD, PeekConsoleInput, ReadConsoleInput, SetConsoleCP, SetConsoleOutputCP


WriteConsoleOutput

The WriteConsoleOutput function writes character and color attribute data to a specified rectangular block of character cells in a console screen buffer. The data to be written is taken from a correspondingly sized rectangular block at a specified location in the source buffer.

BOOL WriteConsoleOutput(

HANDLE hConsoleOutput,	// handle to a console screen buffer
CONST CHAR_INFO *lpBuffer,	// pointer to buffer with data to write
COORD dwBufferSize,	// column-row size of source buffer
COORD dwBufferCoord,	// upper-left cell to write from
PSMALL_RECT lpWriteRegion	// pointer to rectangle to write to
);
Parameters

hConsoleOutput

Identifies the screen buffer. The handle must have GENERIC_WRITE access.

lpBuffer

Points to a source buffer that contains the data to be written to the screen buffer. This pointer is treated as the origin of a two-dimensional array of CHAR_INFO structures whose size is specified by the dwBufferSize parameter.

dwBufferSize

Specifies the size, in character cells, of the buffer pointed to by the lpBuffer parameter. The X member of the COORD structure is the number of columns; the Y member is the number of rows.

dwBufferCoord

Specifies the coordinates of the upper-left cell in the buffer pointed to by the lpBuffer parameter to write data from. The X member of the COORD structure is the column, and the Y member is the row.

lpWriteRegion

Points to a SMALL_RECT structure. On input, the structure members specify the upper-left and lower-right coordinates of the screen buffer rectangle to write to. On output, the structure members specify the actual rectangle that was written to.

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.

Remarks

WriteConsoleOutput treats the source buffer and the destination screen buffer as two-dimensional arrays (columns and rows of character cells). The rectangle pointed to by the lpWriteRegion parameter specifies the size and location of the block to be written to in the screen buffer. A rectangle of the same size is located with its upper-left cell at the coordinates of the dwBufferCoord parameter in the lpBuffer array. Data from the cells that are in the intersection of this rectangle and the source buffer rectangle (whose dimensions are specified by the dwBufferSize parameter) is written to the destination rectangle.

Cells in the destination rectangle whose corresponding source location are outside the boundaries of the source buffer rectangle are left unaffected by the write operation. In other words, these are the cells for which no data is available to be written.

Before WriteConsoleOutput returns, it sets the members of lpWriteRegion to the actual screen buffer rectangle affected by the write operation. This rectangle reflects the cells in the destination rectangle for which there existed a corresponding cell in the source buffer, because WriteConsoleOutput clips the dimensions of the destination rectangle to the boundaries of the screen buffer.

If the rectangle specified by lpWriteRegion lies completely outside the boundaries of the screen buffer, or if the corresponding rectangle is positioned completely outside the boundaries of the source buffer, no data is written. In this case, the function returns with the members of the structure pointed to by the lpWriteRegion parameter set such that the Right member is less than the Left, or the Bottom member is less than the Top. To determine the size of the screen buffer, use the GetConsoleScreenBufferInfo function.

WriteConsoleOutput has no effect on the cursor position.

Windows NT: This function uses either Unicode characters or 8-bit characters from the console's current codepage. The console's codepage defaults initially to the system's OEM codepage. To change the console's codepage, use the SetConsoleCP or SetConsoleOutputCP functions, or use the chcp or mode con cp select= commands.

See Also

CHAR_INFO, COORD, GetConsoleScreenBufferInfo, ReadConsoleOutput, ReadConsoleOutputAttribute, ReadConsoleOutputCharacter, SetConsoleCP, SetConsoleOutputCP, SMALL_RECT, WriteConsoleOutputAttribute, WriteConsoleOutputCharacter


WriteConsoleOutputAttribute

The WriteConsoleOutputAttribute function copies a number of foreground and background color attributes to consecutive cells of a console screen buffer, beginning at a specified location.

BOOL WriteConsoleOutputAttribute(

HANDLE hConsoleOutput,	// handle to a console screen buffer
CONST WORD *lpAttribute,	// pointer to buffer to write attributes from
DWORD nLength,	// number of character cells to write to
COORD wWriteCoord,	// coordinates of first cell to write to
LPDWORD lpNumberOfAttrsWritten	// pointer to number of cells written to
);
Parameters

hConsoleOutput

Identifies the screen buffer. The handle must have GENERIC_WRITE access.

lpAttribute

Points to a buffer that contains the attributes to write to the screen buffer.

nLength

Specifies the number of screen buffer character cells to write to.

dwWriteCoord

Specifies the column and row coordinates of the first cell in the screen buffer to write to.

lpNumberOfAttrsWritten

Points to a 32-bit variable that receives the number of attributes actually written to the screen buffer.

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.

Remarks

If the number of attributes to be written to extends beyond the end of the specified row in the screen buffer, attributes are written to the next row. If the number of attributes to be written to extends beyond the end of the screen buffer, the attributes are written up to the end of the screen buffer.

The character values at the positions written to are not changed.

Each attribute specifies the foreground (text) and background colors in which that character cell is drawn. The attribute values are some combination of the following values: FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_RED, FOREGROUND_INTENSITY, BACKGROUND_BLUE, BACKGROUND_GREEN, BACKGROUND_RED, and BACKGROUND_INTENSITY. For example, the following combination of values produces red text on a white background:

FOREGROUND_RED | BACKGROUND_RED | BACKGROUND_GREEN | BACKGROUND_BLUE

See Also

ReadConsoleOutput, ReadConsoleOutputAttribute, ReadConsoleOutputCharacter, WriteConsoleOutput, WriteConsoleOutputCharacter


WriteConsoleOutputCharacter

The WriteConsoleOutputCharacter function copies a number of characters to consecutive cells of a console screen buffer, beginning at a specified location.

BOOL WriteConsoleOutputCharacter(

HANDLE hConsoleOutput,	// handle to a console screen buffer
LPCTSTR lpCharacter,	// pointer to buffer to write characters from
DWORD nLength,	// number of character cells to write to
COORD dwWriteCoord,	// coordinates of first cell to write to
LPDWORD lpNumberOfCharsWritten	// pointer to number of cells written to
);
Parameters

hConsoleOutput

Identifies the screen buffer. The handle must have GENERIC_WRITE access.

lpCharacter

Points to a buffer that contains the characters to write to the screen buffer.

nLength

Specifies the number of screen buffer character cells to write to.

dwWriteCoord

Specifies the column and row coordinates of the first cell in the screen buffer to write to.

lpNumberOfCharsWritten

Points to a 32-bit variable that receives the number of characters actually written.

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.

Remarks

If the number of characters to be written to extends beyond the end of the specified row in the screen buffer, characters are written to the next row. If the number of characters to be written to extends beyond the end of the screen buffer, characters are written up to the end of the screen buffer.

The attribute values at the positions written to are not changed.

Windows NT: This function uses either Unicode characters or 8-bit characters from the console's current codepage. The console's codepage defaults initially to the system's OEM codepage. To change the console's codepage, use the SetConsoleCP or SetConsoleOutputCP functions, or use the chcp or mode con cp select= commands.

See Also

ReadConsoleOutput, ReadConsoleOutputAttribute, ReadConsoleOutputCharacter, SetConsoleCP, SetConsoleOutputCP, WriteConsoleOutput, WriteConsoleOutputAttribute


WriteFile

The WriteFile function writes data to a file and is designed for both synchronous and asynchronous operation. The function starts writing data to the file at the position indicated by the file pointer. After the write operation has been completed, the file pointer is adjusted by the number of bytes actually written, except when the file is opened with FILE_FLAG_OVERLAPPED. If the file handle was created for overlapped input and output (I/O), the application must adjust the position of the file pointer after the write operation is finished.

BOOL WriteFile(

HANDLE hFile,	// handle to file to write to
LPCVOID lpBuffer,	// pointer to data to write to file
DWORD nNumberOfBytesToWrite,	// number of bytes to write
LPDWORD lpNumberOfBytesWritten,	// pointer to number of bytes written
LPOVERLAPPED lpOverlapped	// pointer to structure needed for overlapped I/O
);
Parameters

hFile

Identifies the file to be written to. The file handle must have been created with GENERIC_WRITE access to the file.

Windows NT

For asynchronous write operations, hFile can be any handle opened with the FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle returned by the socket or accept functions.

Windows 95

For asynchronous write operations, hFile can be a communications resource, mailslot, or named pipe handle opened with the FILE_FLAG_OVERLAPPED flag by CreateFile, or a socket handle returned by the socket or accept functions. Windows 95 does not support asynchronous write operations on disk files.

lpBuffer

Points to the buffer containing the data to be written to the file.

nNumberOfBytesToWrite

Specifies the number of bytes to write to the file.

Unlike the MS-DOS operating system, Windows NT interprets a value of zero as specifying a null write operation. A null write operation does not write any bytes but does cause the time stamp to change.

Named pipe write operations across a network are limited to 65535 bytes.

lpNumberOfBytesWritten

Points to the number of bytes written by this function call. WriteFile sets this value to zero before doing any work or error checking.

If lpOverlapped is NULL, lpNumberOfBytesWritten cannot be NULL.

If lpOverlapped is not NULL, lpNumberOfBytesWritten can be NULL. If this is an overlapped write operation, you can get the number of bytes written by calling GetOverlappedResult. If hFile is associated with an I/O completion port, you can get the number of bytes written by calling GetQueuedCompletionStatus.

lpOverlapped

Points to an OVERLAPPED structure. This structure is required if hFile was opened with FILE_FLAG_OVERLAPPED.

If hFile was opened with FILE_FLAG_OVERLAPPED, the lpOverlapped parameter must not be NULL. It must point to a valid OVERLAPPED structure. If hFile was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function can incorrectly report that the write operation is complete.

If hFile was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the write operation starts at the offset specified in the OVERLAPPED structure and WriteFile may return before the write operation has been completed. In this case, WriteFile returns FALSE and the GetLastError function returns ERROR_IO_PENDING. This allows the calling process to continue processing while the write operation is being completed. The event specified in the OVERLAPPED structure is set to the signaled state upon completion of the write operation.

If hFile was not opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the write operation starts at the current file position and WriteFile does not return until the operation has been completed.

If hFile was not opened with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the write operation starts at the offset specified in the OVERLAPPED structure and WriteFile does not return until the write operation has been completed.

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.

Remarks

If part of the file is locked by another process and the write operation overlaps the locked portion, this function fails.

Applications must not read from nor write to the output buffer that a write operation is using until the write operation completes. Premature access of the output buffer may lead to corruption of the data written from that buffer.

Characters can be written to the screen buffer using WriteFile with a handle to console output. The exact behavior of the function is determined by the console mode. The data is written to the current cursor position. The cursor position is updated after the write operation.

Unlike the MS-DOS operating system, Windows NT interprets zero bytes to write as specifying a null write operation and WriteFile does not truncate or extend the file. To truncate or extend a file, use the SetEndOfFile function.

When writing to a nonblocking, byte-mode pipe handle with insufficient buffer space, WriteFile returns TRUE with *lpNumberOfBytesWritten < nNumberOfBytesToWrite.

When an application uses the WriteFile function to write to a pipe, the write operation may not finish if the pipe buffer is full. The write operation is completed when a read operation (using the ReadFile function) makes more buffer space available.

If the anonymous read pipe handle has been closed and WriteFile attempts to write using the corresponding anonymous write pipe handle, the function returns FALSE and GetLastError returns ERROR_BROKEN_PIPE.

The WriteFile function may fail with ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests.

To cancel all pending asynchronous I/O operations, use the CancelIO function. This function only cancels operations issued by the calling thread for the specified file handle. I/O operations that are canceled complete with the error ERROR_OPERATION_ABORTED.

If hFile is a handle to a named pipe, the Offset and OffsetHigh members of the OVERLAPPED structure pointed to by lpOverlapped must be zero, or the function will fail.

See Also

CancelIo, CreateFile, GetLastError, GetOverlappedResult, GetQueuedCompletionStatus, OVERLAPPED, ReadFile, SetEndOfFile, WriteFileEx


WriteFileEx

The WriteFileEx function writes data to a file. It is designed solely for asynchronous operation, unlike WriteFile, which is designed for both synchronous and asynchronous operation.

WriteFileEx reports its completion status asynchronously, calling a specified completion routine when writing is completed and the calling thread is in an alertable wait state.

BOOL WriteFileEx(

HANDLE hFile,	// handle to output file
LPCVOID lpBuffer,	// pointer to input buffer
DWORD nNumberOfBytesToWrite,	// number of bytes to write
LPOVERLAPPED lpOverlapped,	// pointer to async. i/o data
LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine	// ptr. to completion routine
);
Parameters

hFile

An open handle that specifies the file entity to be written to. This file handle must have been created with the FILE_FLAG_OVERLAPPED flag and with GENERIC_WRITE access to the file.

Windows NT: hFile can be any handle opened with the FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle returned by the socket or accept functions.

Windows 95: hFile can be a communications resource, mailslot, or named pipe handle opened with the FILE_FLAG_OVERLAPPED flag by CreateFile, or a socket handle returned by the socket or accept functions. Windows 95 does not support asynchronous operations on disk files.

lpBuffer

Points to the buffer containing the data to be written to the file.

This buffer must remain valid for the duration of the write operation. The caller must not use this buffer until the write operation is completed.

nNumberOfBytesToWrite

Specifies the number of bytes to write to the file.

If nNumberOfBtyesToWrite is zero, this function does nothing; in particular, it does not truncate the file. For additional discussion, see the following Remarks section.

lpOverlapped

Points to an OVERLAPPED data structure that supplies data to be used during the overlapped (asynchronous) write operation.

For files that support byte offsets, you must specify a byte offset at which to start writing to the file. You specify this offset by setting the Offset and OffsetHigh members of the OVERLAPPED structure. For files that do not support byte offsets — named pipes, for example — you must set Offset and OffsetHigh to zero, or WriteFileEx fails.

The WriteFileEx function ignores the OVERLAPPED structure’s hEvent member. An application is free to use that member for its own purposes in the context of a WriteFileEx call. WriteFileEx signals completion of its writing operation by calling, or queueing a call to, the completion routine pointed to by lpCompletionRoutine, so it does not need an event handle.

The WriteFileEx function does use the Internal and InternalHigh members of the OVERLAPPED structure. You should not change the value of these members.

The OVERLAPPED data structure must remain valid for the duration of the write operation. It should not be a variable that can go out of scope while the write operation is pending completion.

lpCompletionRoutine

Points to a completion routine to be called when the write operation has been completed and the calling thread is in an alertable wait state. For more information about this completion routine, see FileIOCompletionRoutine.

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.

If the WriteFileEx function succeeds, the calling thread has an asynchronous I/O (input/output) operation pending: the overlapped write operation to the file. When this I/O operation finishes, and the calling thread is blocked in an alertable wait state, the operating system calls the function pointed to by lpCompletionRoutine, and the wait completes with a return code of WAIT_IO_COMPLETION.

If the function succeeds and the file-writing operation finishes, but the calling thread is not in an alertable wait state, the system queues the call to *lpCompletionRoutine, holding the call until the calling thread enters an alertable wait state. See Synchronization for more information about alertable wait states and overlapped input/output operations.

Remarks

If part of the output file is locked by another process, and the specified write operation overlaps the locked portion, the WriteFileEx function fails.

Applications must not read from nor write to the output buffer that a write operation is using until the write operation completes. Premature access of the output buffer may lead to corruption of the data written from that buffer.

The WriteFileEx function may fail, returning the messages ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY if there are too many outstanding asynchronous I/O requests.

To cancel all pending asynchronous I/O operations, use the CancelIO function. This function only cancels operations issued by the calling thread for the specified file handle. I/O operations that are canceled complete with the error ERROR_OPERATION_ABORTED.

If hFile is a handle to a named pipe, or other file entity that doesn’t support byte offsets, the Offset and OffsetHigh members of the OVERLAPPED structure pointed to by lpOverlapped must be zero, or the WriteFileEx function fails.

An application uses the WaitForSingleObjectEx, WaitForMultipleObjectsEx, MsgWaitForMultipleObjectsEx, SignalObjectAndWait, and SleepEx functions to enter an alertable wait state. Refer to Synchronization for more information about alertable wait states and overlapped input/output operations.

Windows 95: On this platform, neither WriteFileEx nor ReadFileEx can be used by the comm ports to communicate. However, you can use WriteFile and ReadFile to perform asynchronous communication.

See Also

CancelIo, CreateFile, FileIOCompletionRoutine, MsgWaitForMultipleObjectsEx, OVERLAPPED, ReadFileEx, SetEndOfFile, SleepEx, SignalObjectAndWait, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFile


WritePrinter

The WritePrinter function informs the print spooler that data should be written to the specified printer.

BOOL WritePrinter(

HANDLE hPrinter,	// handle to printer object
LPVOID pBuf,	// pointer to array that contains printer data
DWORD cbBuf,	// size, in bytes, of array
LPDWORD pcWritten	// addr. of variable with count of bytes written
);
Parameters

hPrinter

Identifies the printer.

pBuf

Points to an array of bytes that contains the data that should be written to the printer.

cbBuf

Specifies the size, in bytes, of the array.

pcWritten

Points to a value that specifies the number of bytes of data that were written to the printer.

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.

See Also

OpenPrinter


WritePrivateProfileSection

The WritePrivateProfileSection function replaces the keys and values under the specified section in an initialization file.

This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

BOOL WritePrivateProfileSection(

LPCTSTR lpAppName,	// pointer to string with section name
LPCTSTR lpString,	// pointer to string with data
LPCTSTR lpFileName	// pointer to string with filename
);
Parameters

lpAppName

Points to a null-terminated string containing the name of the section in which data is written. This section name is typically the name of the calling application.

lpString

Points to a buffer containing the new key names and associated values that are written to the named section.

lpFileName

Points to a null-terminated string containing the name of the initialization file. If this parameter does not contain a full path for the file, the function searches the Windows directory for the file. If the file does not exist and lpFileName does not contain a full path, the function creates the file in the Windows directory. The function does not create a file if lpFileName contains the full path and filename of a file that does not exist.

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.

Remarks

The data in the buffer pointed to by the lpString parameter consists of one or more null-terminated strings, followed by a final null character. Each string has the following form:

key=string

The WritePrivateProfileSection function is not case-sensitive; the string pointed to by the lpAppName parameter can be a combination of uppercase and lowercase letters.

If no section name matches the string pointed to by the lpAppName parameter, WritePrivateProfileSection creates the section at the end of the specified initialization file and initializes the new section with the specified key name and value pairs.

WritePrivateProfileSection deletes the existing keys and values for the named section and inserts the key names and values in the buffer pointed to by the lpString parameter. The function does not attempt to correlate old and new key names; if the new names appear in a different order from the old names, any comments associated with preexisting keys and values in the initialization file will probably be associated with incorrect keys and values.

This operation is atomic; no operations that read from or write to the specified initialization file are allowed while the information is being written.

Windows 95:

Windows 95 keeps a cached version of WIN.INI to improve performance. If all three parameters are NULL, the function flushes the cache. The function always returns FALSE after flushing the cache, regardless of whether the flush succeeds or fails.

Windows NT:

Windows NT maps most .INI file references to the registry, using the mapping defined under the following registry key:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

This mapping is likely if an application modifies system-component initialization files, such as as CONTROL.INI, SYSTEM.INI, and WINFILE.INI. In this case, the WritePrivateProfileSection function writes information to the registry, not to the initialization file; the change in the storage location has no effect on the function’s behavior.

The Win32 Profile functions (Get/WriteProfile*, Get/WritePrivateProfile*) use the following steps to locate initialization information:

1.	Look in the registry for the name of the initialization file, say myfile.ini, under IniFileMapping:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping\myfile.ini

2.	Look for the section name specified by lpAppName. This will be a named value under myfile.ini, or a subkey of myfile.ini, or will not exist.

3.	If the section name specified by lpAppName is a named value under myfile.ini, then that value specifies where in the registry you will find the keys for the section.

4.	If the section name specified by lpAppName is a subkey of myfile.ini, then named values under that subkey specify where in the registry you will find the keys for the section. If the key you are looking for does not exist as a named value, then there will be an unnamed value (shown as "<No Name>") that specifies the default location in the registry where you will find the key.

5.	If the section name specified by lpAppName does not exist as a named value or as a subkey under myfile.ini, then there will be an unnamed value (shown as "<No Name>") under myfile.ini that specifies the default location in the registry where you will find the keys for the section.

6.	If there is no subkey for myfile.ini, or if there is no entry for the section name, then look for the actual myfile.ini on the disk and read its contents.

When looking at values in the registry that specify other registry locations, there are several prefixes that change the behavior of the ini file mapping:

! - this character forces all writes to go both to the registry and to the .INI file on disk.

# - this character causes the registry value to be set to the value in the Windows 3.1 .INI file when a new user logs in for the first time after setup.

@ - this character prevents any reads from going to the .INI file on disk if the requested data is not found in the registry.

USR: - this prefix stands for HKEY_CURRENT_USER, and the text after the prefix is relative to that key.

SYS: - this prefix stands for HKEY_LOCAL_MACHINE\SOFTWARE, and the text after the prefix is relative to that key.

See Also

GetPrivateProfileSection, RegCreateKeyEx, RegSetValueEx, WriteProfileSection


WritePrivateProfileString

The WritePrivateProfileString function copies a string into the specified section of the specified initialization file.

This function is provided for compatibility with 16-bit Windows-based applications. WIn32-based applications should store initialization information in the registry.

BOOL WritePrivateProfileString(

LPCTSTR lpAppName,	// pointer to section name
LPCTSTR lpKeyName,	// pointer to key name
LPCTSTR lpString,	// pointer to string to add
LPCTSTR lpFileName	// pointer to initialization filename
);
Parameters

lpAppName

Points to a null-terminated string containing the name of the section to which the string will be copied. If the section does not exist, it is created. The name of the section is case-independent; the string can be any combination of uppercase and lowercase letters.

lpKeyName

Points to the null-terminated string containing the name of the key to be associated with a string. If the key does not exist in the specified section, it is created. If this parameter is NULL, the entire section, including all entries within the section, is deleted.

lpString

Points to a null-terminated string to be written to the file. If this parameter is NULL, the key pointed to by the lpKeyName parameter is deleted.

Windows 95: This platform does not support the use of the TAB (\t) character as part of this parameter.

lpFileName

Points to a null-terminated string that names the initialization file.

Return Values

If the function successfully copies the string to the initialization file, the return value is nonzero.

If the function fails, or if it flushes the cached version of the most recently accessed initialization file, the return value is zero. To get extended error information, call GetLastError.

Remarks

Windows 95:

Windows 95 keeps a cached version of WIN.INI to improve performance. If all three parameters are NULL, the function flushes the cache. The function always returns FALSE after flushing the cache, regardless of whether the flush succeeds or fails.

A section in the initialization file must have the following form:

[section]
key=string
      .
      .
      .

If the lpFileName parameter does not contain a full path and filename for the file, WritePrivateProfileString searches the Windows directory for the file. If the file does not exist, this function creates the file in the Windows directory.

If lpFileName contains a full path and filename and the file does not exist, WriteProfileString creates the file. The specified directory must already exist.

Windows NT:

Windows NT maps most .INI file references to the registry, using the mapping defined under the following registry key:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

Windows NT keeps a cache for the IniFileMapping registry key. Calling WritePrivateProfileStringW with the value of all arguments set to NULL will cause Windows NT to refresh its cache of the IniFileMappingKey for the specified .INI file.

The Win32 Profile functions (Get/WriteProfile*, Get/WritePrivateProfile*) use the following steps to locate initialization information:

1.	Look in the registry for the name of the initialization file, say myfile.ini, under IniFileMapping:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping\myfile.ini

2.	Look for the section name specified by lpAppName. This will be a named value under myfile.ini, or a subkey of myfile.ini, or will not exist.

3.	If the section name specified by lpAppName is a named value under myfile.ini, then that value specifies where in the registry you will find the keys for the section.

4.	If the section name specified by lpAppName is a subkey of myfile.ini, then named values under that subkey specify where in the registry you will find the keys for the section. If the key you are looking for does not exist as a named value, then there will be an unnamed value (shown as "<No Name>") that specifies the default location in the registry where you will find the key.

5.	If the section name specified by lpAppName does not exist as a named value or as a subkey under myfile.ini, then there will be an unnamed value (shown as "<No Name>") under myfile.ini that specifies the default location in the registry where you will find the keys for the section.

6.	If there is no subkey for myfile.ini, or if there is no entry for the section name, then look for the actual myfile.ini on the disk and read its contents.

When looking at values in the registry that specify other registry locations, there are several prefixes that change the behavior of the ini file mapping:

! - this character forces all writes to go both to the registry and to the .INI file on disk.

# - this character causes the registry value to be set to the value in the Windows 3.1 .INI file when a new user logs in for the first time after setup.

@ - this character prevents any reads from going to the .INI file on disk if the requested data is not found in the registry.

USR: - this prefix stands for HKEY_CURRENT_USER, and the text after the prefix is relative to that key.

SYS: - this prefix stands for HKEY_LOCAL_MACHINE\SOFTWARE, and the text after the prefix is relative to that key.

An application using the WritePrivateProfileStringW function to enter .INI file information into the registry should follow these guidelines:

•	Ensure that no .INI file of the specified name exists on the system.

•	Ensure that there is a key entry in the registry that specifies the .INI file. This entry should be under the path HKEY_LOCAL_MACHINE\SOFTWARE \Microsoft\Windows NT\CurrentVersion\IniFileMapping.

•	Specify a value for that .INI file key entry that specifies a section. That is to say, an application must specify a section name, as it would appear within an .INI file or registry entry. Here is an example: [My Section].

•	For system files, specify SYS for an added value.

•	For application files, specify USR within the added value. Here is an example: “My Section: USR: App Name\Section”. And, since USR indicates a mapping under HKEY_CURRENT_USER, the application should also create a key under HKEY_CURRENT_USER that specifies the application name listed in the added value. For the example just given, that would be “App Name”.

•	After following the preceding steps, an application setup program should call WritePrivateProfileStringW with the first three parameters set to NULL, and the fourth parameter set to the INI filename. For example:

WritePrivateProfileStringW( NULL, NULL, NULL, L"appname.ini" );

•	Such a call causes the mapping of an .INI file to the registry to take effect before the next system reboot. The operating system re-reads the mapping information into shared memory. A user will not have to reboot their computer after installing an application in order to have future invocations of the application see the mapping of the .INI file to the registry.

The following sample code illustrates the preceding guidelines and is based on several assumptions:

•	There is an application named “App Name.”

•	That application uses an .INI file named “appname.ini.”

•	There is a section in the .INI file that we want to look like this:

[Section1]

  FirstKey = It all worked out okay.

  SecondKey = By golly, it works.

  ThirdKey = Another test.

•	The user will not have to reboot the system in order to have future invocations of the application see the mapping of the .INI file to the registry.

Here is the sample code :

// include files

#include <stdio.h>

#include <windows.h>

// a main function

main()

{

  // local variables

  CHAR inBuf[80];

  HKEY  hKey1, hKey2;

  DWORD  dwDisposition;

  LONG   lRetCode;

  // try to create the .INI file key

  lRetCode = RegCreateKeyEx ( HKEY_LOCAL_MACHINE,

                              "SOFTWARE\\Microsoft\\Windows NT

                               \\CurrentVersion\\IniFileMapping\\appname.ini",

                              0, NULL, REG_OPTION_NON_VOLATILE, KEY_WRITE,

                              NULL, &hKey1,

                              &dwDisposition);

  // if we failed, note it, and leave

  if (lRetCode != ERROR_SUCCESS){

    printf ("Error in creating appname.ini key\n");

    return (0) ;

    }

  // try to set a section value

  lRetCode = RegSetValueEx ( hKey1,

                             "Section1",

                             0,

                             REG_SZ,

                             "USR:App Name\\Section1",

                             20);

  // if we failed, note it, and leave

  if (lRetCode != ERROR_SUCCESS) {

    printf ( "Error in setting Section1 value\n");

    return (0) ;

    }

  // try to create an App Name key

  lRetCode = RegCreateKeyEx ( HKEY_CURRENT_USER,

                              "App Name",

                              0, NULL, REG_OPTION_NON_VOLATILE, KEY_WRITE,

                              NULL, &hKey2,

                              &dwDisposition);

  // if we failed, note it, and leave

  if (lRetCode != ERROR_SUCCESS) {

    printf ("Error in creating App Name key\n");

    return (0) ;

    }

  // force the operating system to re-read the mapping into shared memory

  //    so that future invocations of the application will see it

  //    without the user having to reboot the system

  WritePrivateProfileStringW( NULL, NULL, NULL, L"appname.ini" );

  // if we get this far, all has gone well

  // let's write some added values

  WritePrivateProfileString ("Section1", "FirstKey",

                             "It all worked out okay.", "appname.ini");

  WritePrivateProfileString ("Section1", "SecondKey",

                             "By golly, it works.", "appname.ini");

  WritePrivateProfileSection ("Section1", "ThirdKey = Another Test.",

                              "appname.ini");

  // let's test our work

  GetPrivateProfileString ("Section1", "FirstKey",

                           "Bogus Value: Get didn't work", inBuf, 80,

                           "appname.ini");

  printf ("%s", inBuf);

  // okay, we are outta here

  return(0);

}

See Also

GetPrivateProfileString, WriteProfileString


WritePrivateProfileStruct

The WritePrivateProfileStruct function copies data into the specified key in the given section of an initialization file. As it copies the data, the function calculates a checksum and appends it to the end of the data. The GetPrivateProfileStruct function uses the checksum to ensure the integrity of the data. This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

BOOL WritePrivateProfileStruct(

LPCTSTR lpszSection,	// pointer to section name
LPCTSTR lpszKey,	// pointer to key name
LPVOID lpStruct,	// pointer to buffer that contains data to add
UINT uSizeStruct,	// size, in bytes, of the buffer
LPCTSTR szFile	// pointer to initialization filename
);
Parameters

lpszSection

Points to a null-terminated string containing the name of the section to which the string will be copied. If the section does not exist, it is created. The name of the section is case independent, the string can be any combination of uppercase and lowercase letters.

lpszKey

Points to the null-terminated string containing the name of the key to be associated with a string. If the key does not exist in the specified section, it is created. If this parameter is NULL, the entire section, including all keys and entries within the section, is deleted.

lpStruct

Points to a buffer that contains the data to copy. If this parameter is NULL, the given key is deleted.

uSizeStruct

Specifies the size, in bytes, of the buffer pointed to by the lpStruct parameter.

szFile

Points to a null-terminated string that names the initialization file. If this parameter is NULL, the given information is copied into the WIN.INI file.

Return Values

If the function successfully copies the string to the initialization file, the return value is nonzero.

If the function fails, or if it flushes the cached version of the most recently accessed initialization file, the return value is zero. To get extended error information, call GetLastError.

Remarks

Windows 95 keeps a cached version of WIN.INI to improve performance. If all three parameters are NULL, the function flushes the cache. The function always returns FALSE after flushing the cache, regardless of whether the flush succeeds or fails.

A section in the initialization file must have the following form:

[section]
key=string
      .
      .
      .

If the szFile parameter does not contain a full path and filename for the file, WritePrivateProfileString searches the Windows directory for the file. If the file does not exist, this function creates the file in the Windows directory.

If szFile contains a full path and filename and the file does not exist, WriteProfileString creates the file. The specified directory must already exist.

The Win32 Profile functions (Get/WriteProfile*, Get/WritePrivateProfile*) use the following steps to locate initialization information:

1.	Look in the registry for the name of the initialization file, say myfile.ini, under IniFileMapping:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping\myfile.ini

2.	Look for the section name specified by lpAppName. This will be a named value under myfile.ini, or a subkey of myfile.ini, or will not exist.

3.	If the section name specified by lpAppName is a named value under myfile.ini, then that value specifies where in the registry you will find the keys for the section.

4.	If the section name specified by lpAppName is a subkey of myfile.ini, then named values under that subkey specify where in the registry you will find the keys for the section. If the key you are looking for does not exist as a named value, then there will be an unnamed value (shown as "<No Name>") that specifies the default location in the registry where you will find the key.

5.	If the section name specified by lpAppName does not exist as a named value or as a subkey under myfile.ini, then there will be an unnamed value (shown as "<No Name>") under myfile.ini that specifies the default location in the registry where you will find the keys for the section.

6.	If there is no subkey for myfile.ini, or if there is no entry for the section name, then look for the actual myfile.ini on the disk and read its contents.

When looking at values in the registry that specify other registry locations, there are several prefixes that change the behavior of the ini file mapping:

! - this character forces all writes to go both to the registry and to the .INI file on disk.

# - this character causes the registry value to be set to the value in the Windows 3.1 .INI file when a new user logs in for the first time after setup.

@ - this character prevents any reads from going to the .INI file on disk if the requested data is not found in the registry.

USR: - this prefix stands for HKEY_CURRENT_USER, and the text after the prefix is relative to that key.

SYS: - this prefix stands for HKEY_LOCAL_MACHINE\SOFTWARE, and the text after the prefix is relative to that key.

See Also

GetPrivateProfileString, WriteProfileString


WriteProcessMemory

The WriteProcessMemory function writes memory in a specified process. The entire area to be written to must be accessible, or the operation fails.

BOOL WriteProcessMemory(

HANDLE hProcess,	// handle to process whose memory is written to
LPVOID lpBaseAddress,	// address to start writing to
LPVOID lpBuffer,	// pointer to buffer to write data to
DWORD nSize,	// number of bytes to write
LPDWORD lpNumberOfBytesWritten	// actual number of bytes written
);
Parameters

hProcess

Identifies an open handle to a process whose memory is to be written to. The handle must have PROCESS_VM_WRITE and PROCESS_VM_OPERATION access to the process.

lpBaseAddress

Points to the base address in the specified process to be written to. Before any data transfer occurs, the system verifies that all data in the base address and memory of the specified size is accessible for write access. If this is the case, the function proceeds; otherwise, the function fails.

lpBuffer

Points to the buffer that supplies data to be written into the address space of the specified process.

nSize

Specifies the requested number of bytes to write into the specified process.

lpNumberOfBytesWritten

Points to the actual number of bytes transferred into the specified process. This parameter is optional. If lpNumberOfBytesWritten is NULL, the parameter is ignored.

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. The function will fail if the requested write operation crosses into an area of the process that is inaccessible.

Remarks

WriteProcessMemory copies the data from the specified buffer in the current process to the address range of the specified process. Any process that has a handle with PROCESS_VM_WRITE and PROCESS_VM_OPERATION access to the process to be written to can call the function. The process whose address space is being written to is typically, but not necessarily, being debugged.

The entire area to be written to must be accessible. If it is not, the function fails as noted previously.

See Also

ReadProcessMemory


WriteProfileSection

The WriteProfileSection function replaces the contents of the specified section in the WIN.INI file with the specified keys and values.

This function is provided for compatibility with 16-bit Windows applications. Win32-based applications should store initialization information in the registry.

BOOL WriteProfileSection(

LPCTSTR lpAppName,	// pointer to section name
LPCTSTR lpString	// pointer to buffer with data
);
Parameters

lpAppName

Points to a null-terminated string containing the name of the section in which data is written. This section name is typically the name of the calling application.

lpString

Points to a buffer containing the new key names and associated values that are written to the named section.

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.

Remarks

Windows 95:

If there is no section in WIN.INI that matches the specified section name, WriteProfileSection creates the section at the end of the file and initializes the new section with the key name and value pairs specified in the lpString parameter.

Keys and values in the lpString buffer consist of one or more null-terminated strings, followed by a final null character. Each string has the following form:

key=string

The WriteProfileSection function is not case-sensitive; the strings can be a combination of uppercase and lowercase letters.

WriteProfileSection deletes the existing keys and values for the named section and inserts the key names and values in the buffer pointed to by lpString. The function does not attempt to correlate old and new key names; if the new names appear in a different order from the old names, any comments associated with preexisting keys and values in the initialization file will probably be associated with incorrect keys and values.

This operation is atomic; no other operations that read from or write to the initialization file are allowed while the information is being written.

Windows NT:

Windows NT maps most .INI file references to the registry, using the mapping defined under the following registry key:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

When the operation has been mapped, the WriteProfileSection function writes information to the registry, not to the initialization file; the change in the storage location has no effect on the function’s behavior.

The Win32 Profile functions (Get/WriteProfile*, Get/WritePrivateProfile*) use the following steps to locate initialization information:

1.	Look in the registry for the name of the initialization file, say myfile.ini, under IniFileMapping:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping\myfile.ini

2.	Look for the section name specified by lpAppName. This will be a named value under myfile.ini, or a subkey of myfile.ini, or will not exist.

3.	If the section name specified by lpAppName is a named value under myfile.ini, then that value specifies where in the registry you will find the keys for the section.

4.	If the section name specified by lpAppName is a subkey of myfile.ini, then named values under that subkey specify where in the registry you will find the keys for the section. If the key you are looking for does not exist as a named value, then there will be an unnamed value (shown as "<No Name>") that specifies the default location in the registry where you will find the key.

5.	If the section name specified by lpAppName does not exist as a named value or as a subkey under myfile.ini, then there will be an unnamed value (shown as "<No Name>") under myfile.ini that specifies the default location in the registry where you will find the keys for the section.

6.	If there is no subkey for myfile.ini, or if there is no entry for the section name, then look for the actual myfile.ini on the disk and read its contents.

When looking at values in the registry that specify other registry locations, there are several prefixes that change the behavior of the ini file mapping:

! - this character forces all writes to go both to the registry and to the .INI file on disk.

# - this character causes the registry value to be set to the value in the Windows 3.1 .INI file when a new user logs in for the first time after setup.

@ - this character prevents any reads from going to the .INI file on disk if the requested data is not found in the registry.

USR: - this prefix stands for HKEY_CURRENT_USER, and the text after the prefix is relative to that key.

SYS: - this prefix stands for HKEY_LOCAL_MACHINE\SOFTWARE, and the text after the prefix is relative to that key.

See Also

GetProfileSection, WritePrivateProfileSection


WriteProfileString

The WriteProfileString function copies a string into the specified section of the WIN.INI file.

This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

BOOL WriteProfileString(

LPCTSTR lpAppName,	// pointer to section name
LPCTSTR lpKeyName,	// pointer to key name
LPCTSTR lpString	// pointer to string to write
);
Parameters

lpAppName

Points to a null-terminated string that specifies the section to which the string is to be copied. If the section does not exist, it is created. The name of the section is not case-sensitive; the string can be any combination of uppercase and lowercase letters.

lpKeyName

Points to a null-terminated string containing the key to be associated with the string. If the key does not exist in the specified section, it is created. If this parameter is NULL, the entire section, including all entries in the section, is deleted.

lpString

Points to a null-terminated string to be written to the file. If this parameter is NULL, the key pointed to by the lpKeyName parameter is deleted.

Windows 95: This platform does not support the use of the TAB (\t) character as part of this parameter.

Return Values

If the function successfully copies the string to the WIN.INI file, the return value is nonzero.

If the function fails, or if it flushes the cached version of WIN.INI, the return value is zero. To get extended error information, call GetLastError.

Remarks

Windows 95:

Windows 95 keeps a cached version of WIN.INI to improve performance. If all three parameters are NULL, the function flushes the cache. The function always returns FALSE after flushing the cache, regardless of whether the flush succeeds or fails.

A section in the WIN.INI file must have the following form:

[section]
key=string
    .
    .
    .

Windows NT:

Windows NT maps most .INI file references to the registry, using the mapping defined under the following registry key:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

When the operation has been mapped, the WriteProfileString function writes information to the registry, not to the initialization file; the change in the storage location has no effect on the function’s behavior.

The Win32 Profile functions (Get/WriteProfile*, Get/WritePrivateProfile*) use the following steps to locate initialization information:

1.	Look in the registry for the name of the initialization file, say myfile.ini, under IniFileMapping:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping\myfile.ini

2.	Look for the section name specified by lpAppName. This will be a named value under myfile.ini, or a subkey of myfile.ini, or will not exist.

3.	If the section name specified by lpAppName is a named value under myfile.ini, then that value specifies where in the registry you will find the keys for the section.

4.	If the section name specified by lpAppName is a subkey of myfile.ini, then named values under that subkey specify where in the registry you will find the keys for the section. If the key you are looking for does not exist as a named value, then there will be an unnamed value (shown as "<No Name>") that specifies the default location in the registry where you will find the key.

5.	If the section name specified by lpAppName does not exist as a named value or as a subkey under myfile.ini, then there will be an unnamed value (shown as "<No Name>") under myfile.ini that specifies the default location in the registry where you will find the keys for the section.

6.	If there is no subkey for myfile.ini, or if there is no entry for the section name, then look for the actual myfile.ini on the disk and read its contents.

When looking at values in the registry that specify other registry locations, there are several prefixes that change the behavior of the ini file mapping:

! - this character forces all writes to go both to the registry and to the .INI file on disk.

# - this character causes the registry value to be set to the value in the Windows 3.1 .INI file when a new user logs in for the first time after setup.

@ - this character prevents any reads from going to the .INI file on disk if the requested data is not found in the registry.

USR: - this prefix stands for HKEY_CURRENT_USER, and the text after the prefix is relative to that key.

SYS: - this prefix stands for HKEY_LOCAL_MACHINE\SOFTWARE, and the text after the prefix is relative to that key.

See Also

GetProfileString, WritePrivateProfileString


WriteTapemark

The WriteTapemark function writes a specified number of filemarks, setmarks, short filemarks, or long filemarks to a tape device. These tapemarks divide a tape partition into smaller areas.

DWORD WriteTapemark(

HANDLE hDevice,	// handle to open device
DWORD dwTapemarkType,	// type of tapemarks to write
DWORD dwTapemarkCount,	// number of tapemarks to write
BOOL bImmediate	// return after write begins
);
Parameters

hDevice

Identifies the device on which to write tapemarks. This handle is created by using the CreateFile function.

dwTapemarkType

Specifies the type of tapemarks to write. This parameter can be one of the following values:

Value	Description
TAPE_FILEMARKS	Writes the number of filemarks specified by the dwTapemarkCount parameter.
TAPE_LONG_FILEMARKS	Writes the number of long filemarks specified by dwTapemarkCount.
TAPE_SETMARKS	Writes the number of setmarks specified by dwTapemarkCount.
TAPE_SHORT_FILEMARKS	Writes the number of short filemarks specified by dwTapemarkCount.
dwTapemarkCount

Specifies the number of tapemarks to write.

bImmediate

Specifies whether to return as soon as the operation begins. If this parameter is TRUE, the function returns immediately; if it is FALSE, the function does not return until the operation has been completed.

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:

Error	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
Remarks

Filemarks, setmarks, short filemarks, and long filemarks are special recorded elements that denote the linear organization of the tape. None of these marks contain user data. Filemarks are the most general marks; setmarks provide a hierarchy not available with filemarks.

A short filemark contains a short erase gap that cannot be overwritten unless the write operation is performed from the beginning of the partition or from an earlier long filemark.

A long filemark contains a long erase gap that allows an application to position the tape at the beginning of the filemark and to overwrite the filemark and the erase gap.

See Also

CreateFile


wsprintf

The wsprintf function formats and stores a series of characters and values in a buffer. Any arguments are converted and copied to the output buffer according to the corresponding format specification in the format string. The function appends a terminating null character to the characters it writes, but the return value does not include the terminating null character in its character count.

int wsprintf(

LPTSTR lpOut,	// pointer to buffer for output
LPCTSTR lpFmt,	// pointer to format-control string
...	// optional arguments
);
Parameters

lpOut

Points to a buffer to receive the formatted output.

lpFmt

Points to a null-terminated string that contains the format-control specifications. In addition to ordinary ASCII characters, a format specification for each argument appears in this string. For more information about the format specification, see the Remarks section.

...

Specifies one or more optional arguments. The number and type of argument parameters depend on the corresponding format-control specifications in the lpFmt parameter.

Return Values

If the function succeeds, the return value is the number of characters stored in the output buffer, not counting the terminating null character.

If the function fails, the return value is less than the length of the format-control string. To get extended error information, call GetLastError.

Remarks

The format-control string contains format specifications that determine the output format for the arguments following the lpFmt parameter. Format specifications, discussed below, always begin with a percent sign (%). If a percent sign is followed by a character that has no meaning as a format field, the character is not formatted (for example, %% produces a single percent-sign character).

The format-control string is read from left to right. When the first format specification (if any) is encountered, it causes the value of the first argument after the format-control string to be converted and copied to the output buffer according to the format specification. The second format specification causes the second argument to be converted and copied, and so on. If there are more arguments than format specifications, the extra arguments are ignored. If there are not enough arguments for all of the format specifications, the results are undefined.

A format specification has the following form:

%[-][#][0][width][.precision]type

Each field is a single character or a number signifying a particular format option. The type characters that appear after the last optional format field determine whether the associated argument is interpreted as a character, a string, or a number. The simplest format specification contains only the percent sign and a type character (for example, %s). The optional fields control other aspects of the formatting. Following are the optional and required fields and their meanings:

Field	Meaning
−	Pad the output with blanks or zeros to the right to fill the field width, justifying output to the left. If this field is omitted, the output is padded to the left, justifying it to the right.
#	Prefix hexadecimal values with 0x (lowercase) or 0X (uppercase).
0	Pad the output value with zeros to fill the field width. If this field is omitted, the output value is padded with blank spaces.
width	Copy the specified minimum number of characters to the output buffer. The width field is a nonnegative integer. The width specification never causes a value to be truncated; if the number of characters in the output value is greater than the specified width, or if the width field is not present, all characters of the value are printed, subject to the precision specification.
.precision	For numbers, copy the specified minimum number of digits to the output buffer. If the number of digits in the argument is less than the specified precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds the specified precision. If the specified precision is 0 or omitted entirely, or if the period (.) appears without a number following it, the precision is set to 1.
	For strings, copy the specified maximum number of characters to the output buffer.
type	Output the corresponding argument as a character, a string, or a number. This field can be any of the following character sequences:
Sequence	Insert
c	A single character. The wsprintf function ignores character arguments with a numeric value of zero. This sequence is interpreted as type WCHAR when the calling application uses the #define UNICODE compile flag and as type CHAR otherwise.
C	A single character. This sequence is interpreted as type CHAR when the calling application uses the #define UNICODE compile flag and as type WCHAR otherwise.
d	A signed decimal integer argument. This sequence is equivalent to the i sequence.
hc, hC	A single character. The wsprintf function ignores character arguments with a numeric value of zero. This sequence is always interpreted as type CHAR, even when the calling application uses the #define UNICODE compile flag.
hs, hS	A string. This sequence is always interpreted as type LPSTR, even when the calling application uses the #define UNICODE compile flag.
i	A signed decimal integer. This sequence is equivalent to the d sequence.
lc, lC	A single character. The wsprintf function ignores character arguments with a numeric value of zero. This sequence is always interpreted as type WCHAR, even when the calling application does not use the #define UNICODE compile flag.
ld	A long signed decimal integer. This sequence is equivalent to the li sequence.
li	A long signed decimal integer. This sequence is equivalent to the ld sequence.
ls, lS	A string. This sequence is always interpreted as type LPWSTR, even when the calling application does not use the #define UNICODE compile flag. This sequence is equivalent to the ws sequence.
lu	A long unsigned integer.
lx, lX	A long unsigned hexadecimal integer in lowercase or uppercase.
s	A string. This sequence is interpreted as type LPWSTR when the calling application uses the #define UNICODE compile flag and as type LPSTR otherwise.
S	A string. This sequence is interpreted as type LPSTR when the calling application uses the #define UNICODE compile flag and as type LPWSTR otherwise.
u	An unsigned integer argument.
x, X	An unsigned hexadecimal integer in lowercase or uppercase.
Note  Unlike other Windows functions, wsprintf uses the C calling convention (_cdecl), rather than the Pascal calling convention. As a result, it is the responsibility of the calling process to pop arguments off the stack, and arguments are pushed on the stack from right to left. In C-language modules, the C compiler performs this task.

See Also

wvsprintf


wvsprintf

The wvsprintf function formats and stores a series of characters and values in a buffer. The items pointed to by the argument list are converted and copied to an output buffer according to the corresponding format specification in the format-control string. The function appends a terminating null character to the characters it writes, but the return value does not include the terminating null character in its character count.

int wvsprintf(

LPTSTR lpOutput,	// pointer to buffer for output
LPCTSTR lpFormat,	// pointer to format-control string
va_list arglist	// variable argument list of format-control arguments
);
Parameters

lpOutput

Points to a buffer to receive the formatted output.

lpFormat

Points to a null-terminated string that contains the format-control specifications. In addition to ordinary ASCII characters, a format specification for each argument appears in this string. For more information about the format specification, see the wsprintf function.

arglist

A variable argument list; each element of the list specifies an argument for the format-control string. The number, type, and interpretation of the arguments depend on the corresponding format-control specifications in the lpFmt parameter.

Return Values

If the function succeeds, the return value is the number of characters stored in the buffer, not counting the terminating null character.

If the function fails, the return value is less than the length of the format-control string. To get extended error information, call GetLastError.

Remarks

The function copies the format-control string into the output buffer character by character, starting with the first character in the string. When it encounters a format specification in the string, the function retrieves the value of the next available argument (starting with the first argument in the list), converts that value into the specified format, and copies the result to the output buffer. The function continues to copy characters and expand format specifications in this way until it reaches the end of the format-control string. If there are more arguments than format specifications, the extra arguments are ignored. If there are not enough arguments for all of the format specifications, the results are undefined.

See Also

wsprintf


Yield

The Yield function is obsolete. This function is provided only for compatibility with 16-bit versions of Windows. In the Win32-based application programming interface (API), this function does nothing.

Threads that contain windows should use the DispatchMessage, PeekMessage, or TranslateMessage functions. The message-loop functions handle message synchronization properly and yield at the appropriate times.

Threads that do not contain windows should use the Sleep function with a sleep time of zero milliseconds to give up the remainder of their current time slice.

Threads that create a process can use WaitForInputIdle to wait until the new process has finished its initialization.

See Also

DispatchMessage, PeekMessage, Sleep, TranslateMessage, WaitForInputIdle


ZeroMemory

The ZeroMemory function fills a block of memory with zeros.

VOID ZeroMemory(

PVOID Destination,	// address of block to fill with zeros
DWORD Length	// size, in bytes, of block to fill with zeros
);
Parameters

Destination

Points to the starting address of the block of memory to fill with zeros.

Length

Specifies the size, in bytes, of the block of memory to fill with zeros.

Return Values

This function has no return value.

See Also

CopyMemory, FillMemory, MoveMemory


A

ABC width

The amount of spacing required for a single glyph in a font. "A" spacing is added to the current position before drawing the glyph. "B" spacing is the width of the black part of the glyph. "C" spacing is added to the current position to account for the white space to the right of the glyph. The total advanced width is given by A+B+C. See also glyph.

absolute security descriptor

A security descriptor structure that contains pointers to the security information associated with an object. See also security descriptor, self-relative security descriptor.

accelerator table

An array of ACCEL data structures, each of which defines a keyboard accelerator. See also keyboard accelerator.

access-control entry (ACE)

An entry in an access-control list (ACL). An access-control entry contains a security identifier and may also contain a set of access rights. Access-control entries are used to grant or deny access to a user or group and to audit the access attempts of a user or group. See also access-control list (ACL), security identifier (SID).

access-control list (ACL)

A list of security protections that applies to an object. (An object can be a file, process, event, or anything else having a security descriptor.) An entry in an access-control list (ACL) is an access-control entry (ACE). There are two types of access-control list: discretionary and system. See also access-control entry (ACE), discretionary access-control list (DACL), security descriptor, system access-control list (SACL).

access mask

A 32-bit value that specifies the rights that are granted or denied in an access-control entry (ACE). An access mask is also used to request access rights when an object is opened. See also access-control entry (ACE).

access time

The last time a file was written to, read from, or run, if the file is executable.

access token

A group of security attributes permanently attached to a process when a user logs on to the operating system. An access token contains privileges and security identifiers for a user, global group, or local group. The privileges regulate the use of some system services and the security identifiers regulate access to objects that are protected by access-control lists (ACLs). There are two kinds of access token: primary and impersonation. See also impersonation token, primary token, privilege, process, security identifier (SID).

ACE

See access-control entry (ACE).

ACL

See access-control list (ACL).

active screen buffer

The screen buffer that is currently displayed in a console's window.

active window

A top-level window of the application with which the user is working. Windows identifies the active window by positioning it at the top of the Z order and highlighting its title bar and border. See also window.

Adaptive Differential Pulse Code Modulation (ADPCM)

An audio-compression technique.

additive color technology

The color technology, used by video displays, that is based on the three primary colors red, green, and blue (RGB). Other colors (except black) are a combination of two or more of the primaries in varying amounts. Black is defined as the absence of the primaries.

ADPCM

See Adaptive Differential Pulse Code Modulation (ADPCM).

alertable wait

(1) A wait operation initiated when a thread calls either the WaitForSingleObjectEx, WaitForMultipleObjectsEx, or SleepEx function with the function's fAlertable flag set to TRUE. In an alertable wait, the wait function returns when a ReadFileEx or WriteFileEx function completion routine is queued for execution.

(2) A wait function operation in which the function can return when the specified conditions are satisfied, or when the system queues a completion routine for execution by the waiting thread. See also completion routine, wait function.

animation

The display of a series of graphic images that simulates motion. Animation can be frame based or cast based.

anonymous pipe

An unnamed, one-way pipe that transfers data between a parent and child process, or between two child processes of the same parent process. An anonymous pipe is created by the CreatePipe function that returns two handles (one to the read end and one to the write end of the pipe). The creating parent process controls whether these handles are inherited by its child processes. See also child process, handle, parent process, pipe.

application-defined control

A control belonging to a window class supplied by an application.

application-defined resource

A resource whose format is defined and recognized by a specific application. See also custom resource.

association

The process of matching a filename extension with a specific application. When an extension and an application have been associated, applications can use the association to find and start other applications or to open and print files.

asynchronous input and output (I/O)

A type of I/O in which some file I/O functions return immediately, even though an I/O request is still pending. This enables an application to continue with other processing and wait for the I/O to finish at a later time. See also overlapped input and output (I/O).

asynchronous procedure call (APC)

A function that executes asynchronously in the context of a particular thread. When an APC is queued to a thread, the system issues a software interrupt. The next time the thread is scheduled, it will run the APC. APCs made by the system are called "kernel-mode APCs." APCs made by an application are called "user-mode APCs." A thread must be in an alertable state to run a user-mode APC.

asynchronous task handle

The handle returned by the WSAAsyncGetXByY routines. This handle is used to identify the outstanding operation and allow the application to cancel it if needed.

atom

An integer that identifies a character string in an atom table.

atom name

The character string identified by an atom.

atom table

A table, defined by the operating system, that stores character strings and their associated atoms. A global atom table is available to all applications. A local atom table can be used only by the application that created it.

attribute

A characteristic of a file. The six Windows file attributes indicate whether a file is read only, hidden, system, archived, a directory, or normal. See also directory.

auto-reset event object

See event object.

auxiliary audio device

Audio devices whose output is mixed with the Musical Instrument Digital Interface (MIDI) and waveform output devices in a multimedia computer. An example of an auxiliary audio device is the compact disc audio output from a CD-drive.


B

background window

Any window created by a thread other than the foreground thread.

base character

A character followed by a nonspacing character; typically, this is a letter that receives an accent mark. For example, in the character è, an accented e, the e is the base character. See also nonspacing character.

base class

The window class an application uses as the starting point when creating a superclass. See also superclass.

base line

An imaginary line where the capital letters for a given font rest. See also font.

base priority

A thread priority value that provides the basis for calculating the thread's dynamic priority. This value is set to one of the five levels within the priority class of the thread's process. The scheduler can temporarily boost the priority of a thread, but it cannot reduce it below this base. See also dynamic priority, priority class, process, thread.

basic challenge protocol

A security mechanism that all LSAPI-compliant license systems support. It requires independent maintenance of a minimum of four secret values by both the licensed application and the license server, and mutual authentication of one value before the license server grants licensing resources. See also License Service Application Programming Interface (LSAPI), MD4 Message-Digest Algorithm, secret.

beginning-of-medium marker

The position on a tape where you can begin recording data.

beginning-of-partition marker

The position in a partition where you can begin recording data. If there is only one partition, this position is usually equivalent to the beginning-of-medium marker.

Bezier spline

An irregular curve defined by four points: two endpoints and two control points. The endpoints determine where the curve begins and ends. The control points determine the shape of the curve; however, unlike the endpoints, the control points do not intersect the curve.

bit count

The number of bits of data in a color plane that represent a single pixel. See also pixel.

bitmap

An array of bits that contains data that describes the colors found in a rectangular region on the screen (or the rectangular region found on a page of printer paper). See also rectangular region.

bitmapped image

A rectangular image on a video display (or page of printer paper) represented by the color data in a bitmap.

blink time

The elapsed time, in milliseconds, required to invert the caret display. This value is half of the flash time. See also caret, flash time.

blocking input and output (I/O)

A wait mode for I/O operations on a named pipe where functions wait for a process on the other end of the pipe to perform an action. In nonblocking wait mode, the functions return if their operations are not finished immediately. See also named pipe, pipe, process.

bottom-up DIB

A device-independent bitmap (DIB) whose origin lies at the bottom-left corner. See also top-down DIB.

bounding rectangle

A Windows or graphics device interface (GDI) object. In the case of some GDI objects, the dimensions of this rectangle are inclusive-exclusive when no world transformation has been set, and inclusive-inclusive when a world transformation has been set.

break key

In Media Control Interface (MCI), a keystroke that interrupts a wait operation. By default, MCI defines this key as ^CTRL+BREAK^. An application can redefine this key by using the MCI_BREAK command message.

breakpoint

A location in a process where execution is stopped to allow the developer to examine the process's code, variables, and register values, and, as necessary, make changes, continue execution, or terminate execution.

brush

A bitmap that is used to fill the interior of closed shapes, polygons, ellipses, and paths. See also bitmap, ellipse, path, polygon.

brush origin

A coordinate that specifies the location of one of the pixels in a brush's bitmap. Windows maps this pixel to the upper left corner of the window that contains the object to be painted. See also bitmap, pixel, window.

button

An element in the Windows user interface that enables a user to provide input to an application. Buttons are typically used in dialog boxes.

byte-order mark

A special Unicode character (0xFEFF) that is placed at the beginning of Unicode text files to indicate that the text is in Unicode format.

byte reversed

A Unicode file in which the most significant byte is first (as on Motorola architectures).

byte type pipe

A named pipe where data is written as a stream of bytes. See also named pipe.


C

caret

A flashing line, block, or bitmap that marks the location of the insertion point in a window's client area. See also bitmap.

CD-ROM extended architecture (CD-XA)

An extension of the CD-ROM standard that provides for storage of compressed audio data along with other data on a compact disc. This standard also defines the way data is read from a disc. Audio signals are combined with text and graphic data on a single track so they can be read at virtually the same time.

channel

A method, provided by Musical Instrument Digital Interface (MIDI), for sending messages to an individual device within a MIDI setup. There are 16 MIDI channel numbers. Devices in a MIDI setup can be directed to respond only to messages marked with a channel number specific to the device.

channel map

A channel map, provided by the MIDI Mapper, that can redirect Musical Instrument Digital Interface (MIDI) messages from one channel to another. See also MIDI Mapper, Musical Instrument Digital Interface (MIDI).

character code

A numeric value that represents a particular character in a set, such as the ASCII character set. See also code page.

character set

A mapping of characters to their identifying numeric values. See also multibyte character set, single-byte character set, Unicode.

character-mode application

An application that does not provide its own graphical user interface (GUI). The Win32 API provides consoles for managing input and output (I/O) for character-mode applications. See also console.

check box

A square box operated by the user to choose from a set of related but independent options. A checked check box contains an X. Repeatedly checking a check box toggles it from state to state. A standard check box has two states: checked and unchecked. A three-state check box has an additional state: disabled (grayed). In versions of standard and three-state check boxes, Windows is responsible for changing the state of the check box.

child process

A process (child) initiated by another process (the parent). The child process can operate independently from the parent process. Further, the parent process can suspend or terminate without affecting the child process. See also parent process.

child window

A window that has the WS_CHILD style. A child window always appears within the client area of its parent window.

child-window identifier

An application-defined value assigned to a child window. An application that creates multiple child windows of the same class uses the identifiers to distinguish among the child windows.

chord

A region bounded by the intersection of an ellipse and a secant. In Windows, a chord is outlined by using the current pen and filled by using the current brush. See also ellipse, secant.

chunk

The basic building block of a Resource Interchange File Format (RIFF) file, consisting of an identifier (called a chunk identifier), a chunk-size variable, and a chunk data area of variable size.

class cursor

The default cursor for a window class. The class cursor is specified by the hCursor member of a WNDCLASS structure. See also cursor.

class icon

The default icon for a window class. The class icon is identified by the hIcon member of a WNDCLASS structure. See also icon.

class menu

The default menu for a window class. All windows of a given class use the same menu unless the application specifies a different menu when creating a window of that class. See also menu, window.

click

To press and release a mouse button.

client area

The part of a window where the application displays output such as text or graphics.

client coordinates

Coordinates relative to the upper left corner of a window's client area.

clip path

One or more irregular shapes in a window's client area where clipped output appears. The edges of a clip path can be straight lines, Bezier curves, or combinations of the two. See also irregular shape.

clipboard

A set of functions and messages used to transfer information between applications or within an application.

clipboard format

The format of data on the clipboard. A window can copy information to the clipboard using multiple clipboard formats. A clipboard format is identified by a unique unsigned integer value. See also clipboard, window.

clipboard owner

The window associated with the information on the clipboard. It is possible for there to be no clipboard owner. See also clipboard, window.

clipboard viewer

A window that displays the contents of the clipboard. See also clipboard, window.

clipping

The process of limiting output to part of the client area in a window. See also window.

clipping region

A polygon or ellipse in a window's client area where clipped output appears. See also ellipse, polygon.

CMY format

See cyan, magenta, yellow (CMY) format.

code page

A mapping of characters to 256 8-bit character codes. See also character code.

coherent

A description of file views that contain identical data at a given time. File views are coherent if they are derived from the same file-mapping object.

Color common dialog box

A common dialog box that displays available colors and controls that let the user define a custom color. See also common dialog box.

color palette

An array containing the RGB (red, green, blue) values identifying the colors that can currently be displayed or drawn on the output device. Color palettes are used by devices that are capable of generating many colors but can only display or draw a subset of these at any given time.

color plane

An array of bits that represents the red, green, blue, or intensity components for the pixels in a bitmapped image. See also bitmapped image, pixel.

command item

A menu item that, when chosen, sends a command message to the window procedure of the window that owns the menu. See also menu item, window.

command message

In Media Control Interface (MCI), a symbolic constant that represents a unique command for an MCI device. Command messages have associated data structures that provide information a device requires to carry out a request.

command string

In Media Control Interface (MCI), a null-terminated character string that represents a command for an MCI device. The text string contains all the information that an MCI device needs to carry out a request. MCI parses the text string and translates it into an equivalent command message and data structure that it then sends to an MCI device driver.

comment

A string of text inserted between records in a metafile. See also metafile.

committed page

A page of memory in a process's virtual address space for which physical storage has been allocated. The storage is either in RAM or on disk.

common dialog box

A dialog box that an application displays by calling a single function rather than by creating a dialog box procedure and a resource file containing the dialog box template. See also resource file.

common display context

The default display context assigned to a window that does not specify CS_OWNDC or CS_CLASSDC as the window's class style. See also display context, window.

communications resource

A physical or logical device that provides a single bidirectional, asynchronous data stream. Serial ports, parallel ports, fax machines, and modems are examples of communications resources. For each communications resource, there is a service provider, consisting of a library or driver, that enables applications to access the resource.

compact disc − digital audio (CD-DA)

An optical data-storage format that provides for the storage of up to 73 minutes of high-quality digital-audio data on a compact disc. Also known as Red Book audio.

compact disc − read-only memory (CD-ROM)

An optical data-storage technology that allows large quantities of data to be stored on a compact disc.

compatible device context (DC)

A virtual-device context that provides a means of storing an image that was created on a physical screen. (Compatible DCs are sometimes referred to as "memory" DCs.) See also device context.

completion routine

A function specified in a call to either the ReadFileEx or WriteFileEx function. A completion routine is queued for execution when the read or write operation is finished. The completion routine is not executed until the thread that called the ReadFileEx and WriteFileEx function enters an alertable wait. See also alertable wait.

composite character

An accented character represented by two character values, one for the base character and another for the nonspacing accent character. See also base character, nonspacing character, precomposed character.

compound device

A Media Control Interface (MCI) device that requires a device element, usually a data file. An example of a compound device is the MCI waveform audio driver. See also device element.

compound file

A number of individual files bound together in one physical file. Each individual file in a compound file can be accessed as if it were a single physical file.

console

An interface that provides input and output to character-mode applications. See also character-mode application.

console modes

Settings associated with a console that determine the behavior of some of its input and output operations.

console process

A character-mode process whose entry point is the main function. A console process uses the console functions or the file input and output (I/O) functions for I/O, while a graphical user interface (GUI) process uses the USER/graphic device interface (GDI) functions. See also process.

console window

A window managed by the system that a console uses to receive input and display output.

container

A network resource that contains other network resources. The contained resources can be such objects as servers or printers, or containers that can also contain further objects and containers. See also sharepoint.

context record

A record of the machine state created when an exception occurs. The context record is saved in a CONTEXT structure.

control

A child window used in conjunction with another window to carry out simple input and output (I/O) tasks.

control change

See MIDI control-change message.

control identifier

A number that an application uses to uniquely identify a control.

control message

A message sent to a control to request information or perform an action.

control set

A set of configurable options for a computer. See also profile.

control style

A value, similar to a window style, that specifies the appearance and behavior of a control. The window procedure for the control uses the style to determine how to draw the control and process input.

coordinate space

A planar space based on the Cartesian coordinate system. This system requires two axes that are perpendicular and equal in length. There are four coordinate spaces in Windows: world, page, device, and physical device (client area, or desktop, or page of printer paper).

Coordinated Universal Time

The standard international time used internally by Windows NT.

cosmetic pen

A pen with dimensions specified in device units. See also pen.

counter

A general term referring to an incrementing variable.

critical section

An object used to synchronize the threads of a single process. Only one thread at a time can own a critical-section object.

current directory

The directory at the end of the active path. This is the directory where the active application started, unless explicitly changed. See also directory.

current position

The starting point for any line-drawing or curve-drawing operations.

current selection

The portion of a document the user has marked in preparation for carrying out a command.

cursor

A small bitmap whose location on the screen is controlled by a pointing device, such as a mouse, pen, or trackball. See also bitmap.

cursor handle

A unique value of the HCURSOR type that identifies a cursor.

custom cursor

A cursor designed for use in a specific application.

custom icon

An icon designed for use in a specific application. See also icon.

custom resource

See application-defined resource.

cyan, magenta, yellow (CMY) format

A color format that identifies a given color with a cyan, magenta, yellow (CMY) format triplet. This format is used by printers and other ink-based devices.


D

DACL

See discretionary access-control list.

DBCS

See double-byte character set.

DC

See device context.

DDE

See dynamic data exchange.

DDE client application

An application that requests a conversation with a dynamic data exchange (DDE) server application, and receives data from the server during the conversation. See also DDE server application.

DDE conversation

The interaction between a dynamic data exchange (DDE) client and a DDE server application.

DDE server application

An application that provides data to a dynamic data exchange (DDE) client application during a DDE conversation. See also DDE client application, DDE conversation.

DDE transaction

An exchange of messages or data between a dynamic data exchange (DDE) client application and a DDE server application. See also DDE client application.

dead key

A key used with another key to create an accented character. A dead key, when pressed, produces no visible character but indicates that the accent mark it represents is to be combined with the character produced by the next letter key pressed. See also key.

deadlock

A bug where the execution of thread A is blocked indefinitely waiting for thread B to perform some action, while thread B is blocked waiting for thread A. For example, two threads on opposite ends of a named pipe can become deadlocked if each thread waits to read data written by the other thread. A single thread can also deadlock itself. See also named pipe, thread.

debugger

An application that enables a developer to observe and correct programming errors by stepping through an application program, examining data, and checking conditions.

debugging

The process of observing and correcting logical and syntactical errors in an application.

debugging event

An event that occurs in a process being debugged that causes the kernel to notify the debugger. Also, the notification the kernel sends to the debugger. See also debugger, process.

default color palette

An array of RGB values identifying the colors that can be used with a device context by default. Windows associates the default color palette with a context whenever an application creates a context for a device that supports color palettes. The default color palette ensures that colors are available for use by an application without requiring additional action by the application.

default window procedure

A system-defined function that provides default processing for messages an application-defined window procedure does not process. See also window procedure.

desktop wallpaper

The pattern created by the bitmap that the desktop window uses to paint the background of the screen.

desktop window

A system-defined window that paints the background of the screen and serves as the base for all windows displayed by all Windows applications.

detached process

A console process that does not have access to the console of its parent process. Typically, a detached process runs in the background, but it can use the AllocConsole function to create a new console if it needs to print a message to the screen or get input from the user. See also console process, parent process.

device capabilities

The curve-, line-, polygon-, raster-, and text-drawing capabilities of a display or printer.

device context

A data structure defining the graphic objects, their associated attributes, and the graphic modes affecting output on a device. See also graphic modes, graphic objects.

device coordinate space

One of four coordinate spaces used for all graphic device interface (GDI) drawing operations.

device-dependent bitmap

An array of bits that can only be used with a particular display or printer.

device element

Data required for operation of Media Control Interface (MCI) compound devices. The device element is generally an input or output data file.

device-independent bitmap (DIB)

An array of bits combined with several structures that specify the width and height of the bitmapped image (in pixels), the color format of the device where the image was created, and the resolution of the device used to create that image. See also bitmapped image, pixel.

device type

A class of Media Control Interface (MCI) devices that respond to a common set of commands.

DIB palette

The logical color palette created when a device-independent bitmap (DIB) was created. See also color palette.

DIB pattern-brush

A logical brush created from a device-independent bitmap (DIB). See also device-independent bitmap (DIB), logical brush.

digital differential analyzer (DDA)

An algorithm that determines which pixels on a video display (or dots on a printed page) are part of a line or curve. See also pixel.

directory

An organizational construct supported by most disk-based operating systems. Rather than listing all the files on a volume at once, users can create multiple directories to contain groups of files. Directories can also contain other directories.

disabled window

A window that cannot receive input from keyboard, mouse, or other input device.

discretionary access-control list (DACL)

An access-control list that is controlled by the owner of an object and that specifies the access particular users or groups can have to the object. See also access-control list (ACL), system access-control list.

disk drive

A physical device that reads from or writes to disks. Disk drives are referenced by letters, typically A for the first floppy-disk drive, B for the second floppy-disk, C for the first fixed-disk drive, D for the second fixed-disk drive, and so on. Each drive on an operating system is assigned a unique letter to distinguish it from other drives.

display context

A special device context that treats each window like a separate screen surface. See also device context, window.

display driver

A Windows dynamic-link library (DLL) that contains functions that process input from the graphics engine and convert that input into device-specific commands. These commands are processed by the display adapter. See also dynamic-link library (DLL).

display element

The parts of a window and the Windows display that appear on the system display screen.

division type

The technique used to represent the time between Musical Instruments Digital Interface (MIDI) events in a MIDI sequencer.

DLL

See dynamic-link library (DLL).

domain

A group of workstations and servers that share a single group name.

double-byte character set (DBCS)

A mapping of characters to their identifying numeric values, in which each value is 2 bytes wide. Double-byte character sets are sometimes used for languages that have more than 256 characters. For example, a double-byte character set is used to encode Japanese (Kanji) characters. See also multibyte character set.

double-click

To press and release a mouse button twice in quick succession.

drag

To move the mouse while holding down a mouse button.

drag-drop

To select one or more files in File Manager, drag them to an open application, and drop them there.

driver service

A service that follows the device driver protocols for Windows NT rather than using the Service Control Manager interface.

drop-down combo box

A combo box, created by using the CBS_DROPDOWN style, containing a drop-down list and a selection field that can be edited by the user.

drop-down list

A list in a combo box that is visible only when it is opened by the user. Combo boxes with the CBS_DROPDOWN and CBS_DROPDOWNLIST styles contain drop-down lists.

drop-down list box

A combo box, created by using the CBS_DROPDOWNLIST style, containing a drop-down list and a selection field that cannot be edited by the user. A drop-down list box can be used in place of a list box when screen space is tight.

due time

The time at which the state of the waitable timer is to be set to signaled. This value is specified when the timer is started. A positive value indicates an absolute time. A negative value indicates a relative time.

dynamic data exchange (DDE)

A form of interprocess communications that uses shared memory to exchange data between applications. Applications can use DDE for one-time data transfers and for ongoing exchanges in applications that send updates to one another as new data becomes available.

dynamic-link library (DLL)

A .DLL file that contains one or more functions compiled, linked, and stored separately from the processes that use them. The operating system maps the DLLs into the process's address space when the process is starting up or while it is running. The process then executes functions in the DLL. See also process.

dynamic priority

A thread priority value used by the scheduler in making scheduling decisions. The value for each thread can never be lower than the thread's base priority, but it can be raised and then lowered to enhance responsiveness to input or other significant events. See also base priority, thread.


E

early-warning position

A physical mark or device-computed position immediately before the end-of-partition marker.

edit control

An element of the Windows user interface that allows the user to enter and edit text. Edit controls are typically used in dialog boxes.

ellipse

A closed curve defined by two fixed points such that the sum of the distances from any point on the curve to the two fixed points is constant.

elliptical region

A region with the shape of an ellipse. See also ellipse, region.

embedded font

A TrueType font stored as part of a document. (By storing a font in a document, the document's author is guaranteed that the original appearance and format of the document remain intact.) See also TrueType font.

end cap

A geometric pen attribute that specifies the shape of the pen. There are three types of end caps: flat, round, and square.

end-of-medium marker

The last position on a tape where you can record data.

end-of-partition marker

The last position on a partition where you can record data.

end-of-tape marker

Same as end-of-medium marker.

enhanced metafile

One of two metafile formats. This format, used in applications written to run with the Win32 application programming interface (API), consists of a header, a table of handles to graphics device interface (GDI) objects, a private palette, and an array of metafile records. See also handle.

environment variable

A symbolic variable that represents some element of the operating system, such as a path, a filename, or other literal data. For example, the environment variable PATH represents the directories to search for executable files. See also directory, path.

erase gap

An area of erased tape or a pattern that the device does not recognize as a marker or as user data; it is used to locate a filemark to be overwritten.

escapement

An angle defined by the escapement vector and the x-axis of a device. The base line of a string of text is parallel to the escapement vector. See also x-axis.

event object

An interprocess synchronization object whose state is explicitly set to signaled by the SetEvent or PulseEvent function. A manual-reset event object's state must be explicitly reset to the nonsignaled state by the ResetEvent function. A wait function resets an auto-reset event object's state to nonsignaled before returning. See also synchronization object, wait function.

exception

An event that occurs during the execution of a program and that requires the execution of software outside the normal flow of control.

exception record

A record of an exception. The exception record is saved in an EXCEPTION_RECORD structure.


F

family name

One of two attributes used to organize TrueType fonts. Family names include Courier New, Arial, and Times New Roman. (The other attribute used to organize TrueType fonts is the style name.) See also TrueType font.

FAT

See file allocation table (FAT).

file

A named, ordered collection of information, such as a program, a set of data used by a program, or a user-created document. A file is the basic unit of storage that enables a computer to distinguish one set of information from another.

file allocation table (FAT)

A table that contains the status of various segments of disk space used for file storage. Also, the file system that maintains the table.

file element

A complete file contained in a Resource Interchange File Format (RIFF) compound file.

file handle

A unique identifier that Windows assigns to a file when the file is opened or created. A file handle is valid until the file is closed.

file-mapping object

An object whose handle can be used to create a view to a file or piece of memory. The CreateFileMapping function creates file-mapping objects. See also handle.

file pointer

A pointer to the next byte to be read or written in a file.

file system

A part of the operating system that enables you to store, access, and organize files on storage devices, such as hard or floppy disks or tape drives. File allocation table (FAT) and New Technology file system (NTFS) are examples of file systems.

file time

A 64-bit value representing the number of 100-nanosecond intervals that have elapsed since January 1, 1601.

file view

A copy of a file or piece of memory that appears in a process's virtual address space. The MapViewOfFile function creates a file view in the process's address space and returns a pointer to the file view.

filemark

A special recorded element that contains no user data and is used to provide a segmentation scheme. A normal filemark does not contain an erase gap.

filled path

A path that is filled by using the brush currently selected into an application's device context. See also device context, path.

filter expression

An expression that is part of a frame-based exception handler. When an exception occurs during the execution of the guarded body of code in a frame-based exception handler, the system evaluates the filter expression to determine whether the exception handler code is to be executed. See also frame-based exception handler, guarded body of code.

filter function

A function called by a filter expression in a frame-based exception handler. See also frame-based exception handler.

Find common dialog box

A common dialog box that displays an edit control in which the user can type a string that the application should search. See also common dialog box.

first-chance notification

The first time the kernel notifies the debugger of an exception. See also debugger.

flash time

The elapsed time, in milliseconds, required to display, invert, and restore the caret display. This value is twice as much as the blink time. See also blink time, caret.

flattened path

A path altered by converting each curve (in the path) into a series of line segments. See also path.

floating pop-up menu

A pop-up menu that is not attached to a menu bar. See also pop-up menu.

FM synthesizer

See frequency modulation (FM) synthesizer.

font

(1) A collection of characters and symbols that share a common design.

(2) A drawing object used to write text on a display surface.

Font common dialog box

A common dialog box that displays lists of fonts and point sizes that correspond to available fonts. See also common dialog box.

font mapper

An algorithm that Windows uses to determine which available font most closely matches a requested font. See also font.

font table

An array that identifies each of the fonts whose resources have been loaded. Only fonts whose resources have been loaded can be used for text output. See also font.

foreground window

The window with which the user is currently working. The system assigns a slightly higher priority to the thread that created the foreground window than it does to other threads.

form type

A four-character code (FOURCC) identifying the type of data contained in a Resource Interchange File Format (RIFF) chunk. For example, a RIFF chunk with a form type of WAVE contains waveform audio data.

FOURCC (Four-Character Code)

A code used to identify Resource Interchange File Format (RIFF) chunks. A FOURCC is a 32-bit quantity represented as a sequence of one to four ASCII alphanumeric characters, padded on the right with blank characters.

frame-based exception handler

A mechanism used by a developer to deal with the possibility that an exception may occur in a certain sequence of code. A frame-based exception handler consists of a guarded body of code, a filter expression, and an exception handler. See also filter expression, guarded body of code.

free page

A page of memory in a process's virtual address space that is available to be reserved or committed. A process cannot access a free page. See also committed page, reserved page.

frequency

With respect to the high-resolution performance counter, the number of counts per second. This value is processor dependent.

frequency modulation (FM) synthesizer

A synthesizer that creates sounds by combining the output of digital oscillators using a frequency modulation technique.


G

General MIDI

A synthesizer specification created by the MIDI Manufacturers Association (MMA) defining a common configuration and set of capabilities for consumer Musical Instrument Digital Interface (MIDI) synthesizers.

geometric pen

A pen with dimensions that are specified in world units. A geometric pen may possess attributes usually associated with a brush, such as pattern and hatch. See also brush, geometric pen, pen.

global atom

An atom stored in the global atom table. The value of a global atom is unique among all others in the operating system. See also atom.

global atom table

See atom table.

global subclassing

A type of subclassing in which an application replaces the window-procedure address stored in the WNDCLASS structure of a window class with the address of a subclass procedure. All subsequent windows created with the class use the subclass procedure rather than the original window procedure. See also subclassing, window, window procedure.

glyph

The bitmap, collection of points, or collection of graphic commands that define a single character or symbol in a font. See also bitmap, font.

graceful disconnect

In a graceful disconnect, all the data sent by both sides are delivered and there is full acknowledgment of the session termination by both sides. This contrasts with an abortive disconnect, in which one side unilaterally terminates the connection, disregarding any queued data. As a result, in an abortive disconnect there may be data loss.

graphic modes

A set of modes that define how the Win32 API draws output with the objects found in a device context. See also device context.

graphic objects

The pen, brush, bitmap, palette, region, and path associated with a device context. See also bitmap, brush, device context, palette, path, region.

graphical user interface (GUI) process

A process whose entry point is the WinMain function. A GUI process uses the USER/graphics device interface (GDI) functions for input and output (I/O), while a console process uses the console functions or the file I/O functions. See also console process.

graphics device interface

A dynamic-link library that processes graphics function calls from a Windows-based application and passes those calls to the appropriate device driver. See also dynamic-link library (DLL).

group box

A rectangle used to group related controls (usually check boxes or radio buttons). Because its sole purpose is to organize other controls, a group box cannot be selected. See also check box, radio button.

guarded body of code

A set of one or more statements for which an exception or termination handler provides protection.

GUI process

See graphical user interface (GUI) process.


H

handle

A variable that identifies an object; an indirect reference to an operating system resource.

hatched brush

A logical brush created from one of twenty predefined bitmaps. See also bitmap, logical brush.

hidden window

A window that does not have the WS_VISIBLE style. A hidden window does not appear on the screen. As a result, it cannot receive user input or display output, although it can receive input from Windows and other applications.

high-performance file system (HPFS)

A file system that supports extended attributes and long, mixed-case filenames, and improves operating system performance by implementing several levels of caching. HPFS files are not supported on 32-bit versions of Microsoft Windows.

high-resolution performance counter

Hardware that provides high-resolution timing useful in improving the performance of applications.

hit testing

(1) The process of detecting user input by using the position of the mouse cursor hot spot. See also hot spot.

(2) A procedure for determining the current cursor position related to a given region. See also region.

hive

A discrete body of registry information, typically rooted at the top of the registry hierarchy. Each hive is usually supported by a single file of registry data.

HLS format

A color format that identifies a given color with a HLS (hue, luminosity, and saturation) triplet.

HMS time format

A time format used by Media Control Interface (MCI) to express time in hours, minutes, and seconds. The HMS time format is used primarily by videodisc devices.

hollow brush

See null brush.

hook

A point in the Windows message-handling mechanism where an application can install a subroutine to monitor messages.

hook chain

A list of pointers to the hook procedures associated with a hook. When a message occurs that is monitored by the hook, Windows calls the first hook procedure in the chain.

hook procedure

An application-defined callback function whose address has been installed in a hook chain.

hot key

A key combination that generates a WM_HOTKEY message.

hot spot

The pixel in a cursor that marks the exact screen location affected by a mouse action, such as a button click. Mouse messages include the coordinates of the hot spot. See also cursor, pixel.

HPFS

See high-performance file system (HPFS).


I

icon

A small bitmap that usually represents a minimized application. Icons may also serve as symbols in warning messages or other windows. See also bitmap.

icon handle

A unique value of the HICON type that identifies an icon. See also icon.

iconic

Minimized. If an icon represents a minimized application, the application's window is said to be iconic. See also icon, window.

ideographic

A single character that represents a word, object or a phrase — for example, a single character that means "month." This term would apply to the Han script.

IMA

See Interactive Multimedia Association (IMA) and International MIDI Association (IMA).

image

A rectangular region on a video display that contains a graphical representation of an object. See also rectangular region.

impersonation token

An access token that has been created to capture the security information of a client process, allowing a server to "impersonate" the client process in security operations. See also access token, primary token.

import library

A .LIB file that contains information about one or more dynamic-link libraries (DLLs), but does not contain the DLL's executable code. The linker uses an import library when building an executable module of a process, to provide the information needed to resolve the external references to DLL functions. See also dynamic-link library, process.

information context

A device context used strictly for data retrieval; it cannot be used for any drawing operations. See also device context.

input buffer

A buffer containing a queue of input records with information about keyboard, mouse, and window-sizing events for a console. See also console.

input event

An event--such as a keystroke, mouse movement, or mouse-button click--that causes a console to place an INPUT_RECORD structure in its input buffer. A console process can get information about an input event by reading from the console's input buffer.

instance

An instantiation of a particular object type in a class, such as a specific process or thread. All instances of a given type have identical performance counters.

instance subclassing

A type of subclassing where an application replaces the window-procedure address of a single instance of a window with the address of a subclass procedure. See also subclassing, window.

integer atom

An atom that identifies an integer value. See also atom.

Interactive Multimedia Association (IMA)

A professional trade association of companies, institutions, and individuals involved in producing and using interactive multimedia technology.

interlocked operation

The thread that performs an interlocked operation on a LONG variable is guaranteed to have exclusive access to the variable until the operation is complete.

International MIDI Association (IMA)

The nonprofit organization that circulates information about the Musical Instrument Digital Interface (MIDI) specification.

irregular curve

A curve that does not fit the perimeter of a conic section.

irregular shape

A shape composed of curves and straight line segments.

item name

A string that identifies a unit of data a server can pass to a client during a transaction.


J

join style

A geometric pen attribute that specifies how the ends of connected lines are joined. See also geometric pen.


K

key

An entry (or node) in the registry. A key may have one or more values, subkeys, or both. With the exception of four predefined keys, all keys are subkeys of other keys. See also registry, subkey.

keyboard accelerator

A keystroke or combination of keystrokes that sends a command message to the specified application window.

keyboard focus

A property of the window currently receiving keyboard input. Only one window at a time can have the keyboard focus. See also window.


L

language identifier

A 16-bit value that identifies a language and, where appropriate, the variant of the language being used. A language identifier is a combination of a primary language identifier and a sublanguage identifier. For example, if the primary language identifier specifies English, the sublanguage identifier might specify Australian English.

last-chance notification

The last time the kernel notifies the debugger of an exception. If the debugger does not handle an exception after last-chance notification, the kernel terminates the process being debugged. See also debugger, process.

last-error code

A per-thread value set by Win32 functions when an error occurs. The last-error code can be retrieved by using the GetLastError function.

LCID

See locale identifier.

license

The certificate that grants a software product the permission to run. It can be in the form of a paper certificate with manually entered information, a binary file, or a combination of the two. An LSAPI-compliant license must contain a minimum of the software publisher name, the product name, the version, four secret values, and a license policy. See also License Service Application Programming Interface (LSAPI), secret.

license policy

The terms under which a software product is granted permission to run. Examples of types of license policy include concurrent use, dynamic allocation, personal use, time-restricted, and site license.

license server

The part of a license system that runs on a file or applications server. See also license system.

License Service Application Programming Interface (LSAPI)

A standardized set of functions that provides license-tracking services within applications. These services include the ability to request that the licensing system grant the application software rights to run, release those rights when they are no longer needed, and update the state of the licensing resources granted to the software product. The LSAPI specification provides a standard interface between LSAPI-enabled software and LSAPI-compliant software licensing products. See also basic challenge protocol.

license system

A software product that tracks the use of desktop applications. See also license server.

line

A set of highlighted pixels on a video display (or a series of dots on a printed page) that is defined by two points: a starting point and an ending point. See also pixel.

line and curve attributes

The width, color, style, and (in the case of lines or curves drawn with a geometric pen) end cap, join style, and transformation of a line or curve. See also end cap, geometric pen, join style, transformation.

list box

A control window that contains a list of items that can be selected by the user.

LIST chunk

A Resource Interchange File Format (RIFF) chunk with a chunk identifier of LIST. LIST chunks contain a series of subchunks.

list type

A four-character code (FOURCC) identifying the type of data contained in a Resource Interchange File Format (RIFF) chunk with a chunk identifier of LIST. For example, a LIST chunk with a list type of INFO contains a list of information about a file, such as the creation date and author.

load-time linking

Dynamic linking that occurs when a program (either an application or another dynamic-link library [DLL]) makes an explicit call to a DLL function. This requires that the executable module of the program be built by linking with the DLL's import library. When the program is executed, the operating system uses the information provided by the import library to locate the executable module of the DLL, which is mapped into the address space of the process. See also import library, process.

local atom

An atom stored in an application's atom table. The value of a local atom is unique within the application but may not be unique throughout the operating system. See also atom, atom table.

local atom table

See atom table.

locale identifier (LCID)

A DWORD value containing the language identifer in the lower word and a reserved value in the upper word. The identifier supplied in an LCID is a standard international numeric abbreviation. This LCID has the components necessary to uniquely identify one of the installed system-defined locales.

locally unique identifier (LUID)

A 64-bit value guaranteed to be unique on the operating system that generated it (until the system is restarted).

Locator

See Microsoft Locator.

logfile

A configuration registry key that specifies the filename of an event log. Logfiles are subkeys of the EventLog registration key. See also key, subkey.

logging off

The action of stopping all processes running in the security context of the process that called the Exit function.

logical brush

A description of a bitmap. A logical brush can be selected into a device context. See also bitmap, device context.

logical coordinate space

Another name for the world or page coordinate space. If an application has set a world-space to page-space transformation, the logical space is the world space; otherwise, the logical space is the page space.

logical palette

An array of colors, or "color palette," that an application creates and associates with a device context and uses for graphics output. See also device context.

logical volume

See partition.

long filemark

A filemark that contains a long erase gap that enables an application to position the tape at the beginning of the filemark and to overwrite the filemark and the erase gap. See also erase gap.

LSAPI

See License Service Application Programming Interface

LSAPI-enabled application

A desktop application that makes calls to the LSAPI function layer to register license usage. See also License Service Application Programming Interface (LSAPI).

LSAPI-compliant licensing system

A software licensing product that conforms to the LSAPI standard and supports the LSAPI interface. See also License Service Application Programming Interface (LSAPI).

LUID

See locally unique identifier.


M

mailslot

A pseudofile used for one-way interprocess communications.

mailslot client

A process that writes a message to a mailslot.

mailslot server

A process that creates and owns a mailslot and can read messages from it. See also process.

main window

The window that serves as the primary interface between the user and an application.

manual-reset event object

See event object.

mapping

A representation of the elements (or points) from a source coordinate space on a target coordinate space.

mapping mode

An algorithm that specifies the size of the units used for any drawing operations associated with a particular device context.

matrix

An n-dimensional array that is used to specify a transformation. Transformations in a two-dimensional space require either a two-dimensional or a three-dimensional array.

maximize box

A window component that, when clicked, causes Windows to enlarge the window to the size of the screen.

maximized window

A window that has the WS_MAXIMIZE style. A maximized top level window fills the screen; a maximized child window fills the client area of its parent window.

maximum tracking size

The largest window size the user can produce by dragging the sizing border.

MCI

See Media Control Interface.

MD4 Message-Digest Algorithm

An algorithm that LSAPI uses in the basic challenge protocol security mechanism. The MD4 Message-Digest Algorithm from RSA Data Security, Inc., uses a message of arbitrary length as input, and returns a 128-bit message digest. See also basic challenge protocol, License Service Application Programming Interface (LSAPI), secret.

MDI client window

See multiple document interface client window.

MDI frame window

See multiple document interface frame window.

Media Control Interface (MCI)

High-level control software that provides a device-independent interface to multimedia devices and media files. MCI includes a command-message interface and a command-string interface.

memory device context (DC)

See compatible device context (DC).

menu

A list of items that represent an application's commands. A menu item can be either a string or a bitmap. See also bitmap, menu item.

menu bar

The topmost menu in a hierarchy of menus. A menu bar typically contains one or more menu items that the user can select to display pop-up menus. See also menu, menu item, pop-up menu.

menu handle

A unique value of the type HMENU used to identify a menu. See also menu.

menu item

A string or bitmap displayed in a menu. Choosing a menu item either sends a command message or activates a pop-up menu. See also bitmap, pop-up menu.

message

A data packet used for communicating information or a request. Messages can be passed between the operating system and an application, different applications, threads within an application, and windows within an application. See also thread, window.

message loop

A program loop that retrieves messages from a thread's message queue and dispatches them to the appropriate window procedures. See also message queue.

message parameters

A pair of 32-bit values that contains information a window procedure uses while processing a message.

message queue

An operating system-defined memory object that holds an ordered list of messages awaiting processing. The system message queue holds mouse and keyboard input waiting to be passed to a thread's message queue. A thread's message queue holds messages waiting to be retrieved by a thread's message loop. See also message loop.

message-type pipe

A named pipe where data is written as a stream of messages. See also named pipe.

metafile

A collection of structures that stores a picture in a device-independent format. (There are two metafile formats: the enhanced format and the Windows format.)

metafile bits

The binary representation of a metafile. The bits include the header, an optional palette, an optional text description of the metafile contents, and the metafile records. See also metafile record, palette.

metafile device context (DC)

A device context that is used for metafile operations. See also device context.

metafile handle table

An array of handles that identify pens, brushes, fonts, and other objects used to create the picture stored in the metafile. See also brush, font, handle, metafile, pen.

metafile header

A structure that specifies the size of the picture stored in the metafile, the size of the metafile (in bytes), the number of entries in the metafile palette, the number of records in the metafile, a pointer to the metafile description (if one exists), and a pointer to the metafile palette (if one exists). See also metafile, metafile palette, palette.

metafile palette

An array of red, green, blue (RGB) values that represent the colors used to create the picture stored in a metafile. See also metafile.

metafile record

A variable-length structure. In most cases, this structure represents a call made to a graphics device interface (GDI) function to create part of the picture stored in the metafile. See also metafile.

Microsoft Locator

A Windows NT implementation of the Microsoft RPC name-service interface (NSI) for distributed applications. The server application registers its availability, in the form of a name-service entry, with the Locator database. Client applications query the Locator for information such as interface UUIDs, object UUIDs, and network addresses.

MIDI

See Musical Instrument Digital Interface.

MIDI control-change message

A Musical Instrument Digital Interface (MIDI) message sent to a synthesizer to change different synthesizer control settings. An example of a control-change message is the volume controller message, which changes the volume of a specific MIDI channel.

MIDI Manufacturers Association (MMA)

A collective organization composed of Musical Instrument Digital Interface (MIDI) instrument manufacturers and MIDI software companies. The MMA works with the MIDI Standard Committee to maintain the MIDI specification.

MIDI Mapper

Windows systems software that modifies Musical Instrument Digital Interface (MIDI) output messages and redirects them to a MIDI output device using values stored in a MIDI setup map. The MIDI Mapper can change the destination channel and output device for a message, as well as modify program-change messages, volume values, and key values.

MIDI mapping

The process of translating and redirecting Musical Instrument Digital Interface (MIDI) messages according to data defined in a MIDI map setup.

MIDI program-change message

A Musical Instrument Digital Interface (MIDI) message sent to a synthesizer to change the patch on a specific MIDI channel.

MIDI sequence

Musical Instrument Digital Interface (MIDI) data that can be played by a MIDI sequencer.

MIDI sequencer

A program that creates or plays songs stored as Musical Instrument Digital Interface (MIDI) files. When a sequencer plays MIDI files, it sends MIDI data from the file to a MIDI synthesizer, which produces the sounds. Windows provides a MIDI sequencer, accessible through media control interface (MCI), that plays MIDI files. See also Media Control Interface (MCI).

MIDI setup map

A complete set of data for the Musical Instrument Digital Interface (MIDI) Mapper to use when redirecting MIDI messages. Only one setup map can be in effect at a given time, but the user can have several setup maps available and can choose between them by using the MIDI Mapper Control Panel option.

minimize box

A window component that, when clicked, causes Windows to reduce the window to the size of an icon.

minimized window

A window that has the WS_MINIMIZE style. A minimized window is the same size as an icon. Windows displays a minimized top-level window at the bottom of the screen; Windows displays a minimized child window at the bottom of its parent window's client area.

minimum tracking size

The smallest window size the user can produce by dragging the window's sizing border.

MMA

See MIDI Manufacturers Association.

module-definition file

A text file (.DEF) that contains one or more statements describing various attributes of an executable module. A dynamic-link library (DLL) must have a .DEF file to specify the DLL's name and a list of its exported functions. See also dynamic-link library (DLL).

mouse capture

The act of channeling mouse input to a specific window without regard to the position of the mouse-cursor hot spot. See also hot spot, window.

MS-DOS date

A date in the format used by MS-DOS. The date is a packed 16-bit value in which bits in the value represent the day, month, and year.

MS-DOS time

A time in the format used by MS-DOS. The time is a packed 16-bit value in which bits in the value represent the hour, minute, and second.

MSF time format

A time format used by Media Control Interface (MCI) to express time in minutes, seconds, and frames. The number of frames in a second depends on the type of device being used; compact disc audio devices use 75 frames per second. The MSF time format is used primarily by compact disc audio devices.

multibyte character set

A character set in which each character is identified by using more than one byte--for example, a double-byte character set (DBCS). Although Unicode characters are 2 bytes wide, the Unicode character set is not referred to by this term. See also double-byte character set (DBCS), single-byte character set, Unicode.

multiple document interface (MDI) client window

A window that belongs to the MDICLIENT window class. An MDI client window serves as the background for MDI child windows, and it provides support for creating and manipulating child windows. See also window.

multiple document interface (MDI) frame window

The main window of a multiple document interface (MDI) application. See also window.

multiple-selection list box

A list box in which more than one item can be selected at the same time.

Musical Instrument Digital Interface (MIDI)

A standard protocol for communication between musical instruments and computers.

mutex object

An interprocess synchronization object whose state is set to signaled when it is not owned by any thread, and nonsignaled when it is owned. Only one thread at a time can own a mutex. See also nonsignaled, signaled, synchronization object.


N

named pipe

A one-way or two-way pipe used for communications between a server process and one or more client processes. A server process specifies a name when it creates one or more instances of a named pipe. Each instance of the pipe can be connected to a client process that uses the pipe name to open a handle to the other end of the pipe. See also handle, pipe.

network provider

The supplier of a complete implementation of a networking system: for example, Microsoft Server or Novell Netware.

network root

The topmost container resource in a network hierarchy. The network root can contain the network providers on a system.

New Technology file system (NTFS)

A file system that supports object-oriented applications by treating all files as objects with user-defined and system-defined attributes. NTFS provides all the capabilities of the file allocation table (FAT) file system without many of its limitations.

nonclient area

The parts of a window that are not a part of the client area. A window's nonclient area consists of the border, menu bar, title bar, scroll bar, System menu, Minimize button, and Maximize button. See also menu bar, scroll bar, window.

nonqueued message

A message sent directly to a window procedure.

nonsignaled

The state of an object used for synchronization in one of the wait functions is either signaled or nonsignaled. A nonsignaled state can prevent the wait function from returning. See also signaled, wait function.

nonspacing character

A character that prints over the preceding character--typically, an accent mark. See also base character.

normal filemark

A filemark that does not contain an erase gap. See also erase gap.

notification message

A message a control sends to its parent window when events, such as input from the user, occur.

NTFS

See New Technology File System (NTFS).

null brush

A logical brush created from a bitmap that matches the current window background colors. (A null brush is identical to a hollow brush.) See also bitmap, hollow brush, logical brush.


O

object

(1) An internal structure that represents a system resource, such as a file, a thread, or a graphic image. See also thread.

(2) A network resource that does not contain any further network resources. It is not necessarily possible to connect to an object.

object type

A measurable entity, such as a processor, disk, or thread.

Open common dialog box

A common dialog box that displays a list of filenames matching any specified extensions, directories, or drives. By selecting one of the listed filenames, the user indicates the file an application should open. See also common dialog box, directory.

overlapped input and output (I/O)

See asynchronous input and output (I/O).

overlapped window

A style of window meant to serve as an application's main window.

owned window

A window that has an owner. Being owned affects the window's position in the Z order and its visibility and can determine when the window is destroyed.

owner window

A window that affects aspects of another window's appearance and behavior.

owner-drawn button

A button with the style BS_OWNERDRAW. Unlike all other button types, an owner-drawn button has no predefined appearance or behavior. Also, the application, not Windows, is responsible for painting it. See also button.

owner-drawn control

A predefined control that sends messages to its parent window when it must be drawn.

owner-drawn item

A menu item whose appearance is controlled by a menu's owner window rather than by Windows. See also menu item, window.


P

page

A unit of memory that is used by the system in managing memory. The size of a page is computer dependent and can be determined by using the GetSystemInfo function. The system manages memory by assigning pages of memory to specific processes, moving pages to and from a paging file on disk to keep the most recently used pages in physical memory (RAM), and maintaining a page map for each process that keeps track of the current physical location of each committed page in a process's virtual address space. See also committed page, page map.

page coordinate space

The coordinate space in which all graphics device interface (GDI) drawing operations begin if an application has not set the world-space to page-space transformation.

page map

An internal data structure maintained by the system for each process that maps the pages of a process's virtual address space with the corresponding pages of physical storage. See also page.

paging file

A disk file that the system uses to increase the amount of physical storage.

palette

An array of colors currently available on a device.

palette animation

A method of updating the colors in the logical palette.

PANOSE numbers

Special values specified by an application to select a particular font.

parent process

A process (parent) that initiates and controls another process (child) in a multitasking environment. The parent process defines the environment for the child process. The parent process can suspend or complete its own processing while the child process continues its operation. See also child process.

parent window

A window that has one or more child windows.

partition

A logically distinct portion of memory or a storage device that the system references as though it were a physically separate unit. The partition is referenced as a separate volume. For example, a single fixed disk may be divided into two partitions, referred to as C and D, even though they exist on the same physical volume.

parts per quarter note (PPQN)

A time format used for Musical Instrument Digital Interface (MIDI) sequences. PPQN is the most common time format used with standard MIDI files.

patch

A particular setup of a Musical Instrument Digital Interface (MIDI) synthesizer that results in a particular sound, usually a sound simulating a specific musical instrument. Patches are also called programs. A MIDI program-change message changes the patch setting in a synthesizer. Patch also refers to the connection or connections between MIDI devices. See also Musical Instrument Digital Interface (MIDI).

patch caching

A technique that enables some internal Musical Instrument Digital Interface (MIDI) synthesizer device drivers to preload their patch data, reducing the delay between the moment the synthesizer receives a MIDI program-change message and the moment it plays a note using the new patch. Patch caching also ensures that required patches are available (the synthesizer might load only a subset of its patches). See also Musical Instrument Digital Interface (MIDI), patch.

path

(1) A string that describes the location of a file or directory on a volume relative to the current directory or the root directory.

(2) One or more figures that are filled, outlined, or filled and outlined. See also directory, volume.

path bracket

One or more graphics device interface (GDI) functions embedded between a BeginPath and an EndPath function. (The BeginPath function defines the start of the bracket; the EndPath function defines the end.)

pattern brush

A logical brush created from an application-defined bitmap. See also bitmap, logical brush.

pen

A drawing tool used to draw lines and curves.

pen style

One of the cosmetic and geometric pen attributes that define the appearance of lines drawn with the pen. There are eight possible styles: solid, dashed, dotted, dashed and dotted, dash followed by two dots, invisible, inside frame, and user defined. See also cosmetic pen, geometric pen, pen.

pen type

An attribute that determines whether the pen's dimensions are specified in world units or device units.

performance monitoring

The process of determining the system resources an application consumes, such as processor time and memory.

persistent connection

A network connection that Windows restores automatically when the user logs on.

physical brush

A bitmap that Windows uses to paint the interior of filled shapes. A physical brush is a device driver's approximation of a logical brush. See also bitmap, logical brush.

physical device

The fourth and final coordinate space for most graphics device interface (GDI) drawing operations. (The points in this coordinate space may correspond to the desktop, a client area, or a page of printer paper.)

physical palette

See system palette.

picture frame

A rectangle defining the width and height of the picture stored in a metafile. (The dimensions of this rectangle are always specified in .01-mm units.) See also metafile.

pie

A region bounded by the intersection of an ellipse and two radials. In Windows, a pie is outlined by using the current pen and filled by using the current brush. See also ellipse, radial.

pipe

A communication conduit with two ends. A process with a handle to one end can communicate through a pipe with a process having a handle to the other end. Pipes can be one way (where one end is read only and the other end is write only) or two way (where both ends of the pipe can be used for reading or writing). The Win32 application programming interface (API) provides both anonymous (unnamed) pipes and named pipes. See also anonymous pipe, handle, named pipe, process.

pipe instance

A separate conduit for named pipe communications between a client and a server process. A named pipe can have multiple instances, where all instances share the same pipe name but each instance has its own buffers and handles. See also handle, named pipe.

pitch scale factor

In waveform audio, the amount by which a waveform audio driver scales the pitch. A scale factor of two results in a one-octave increase in pitch. Pitch scaling requires specialized hardware. The playback rate and sample rate are not changed.

pixel

The smallest definable unit on a video display. (A pixel's size is a function of video-display technology.)

playback rate scale factor

In waveform audio, the amount by which the waveform audio driver scales the playback rate. Playback scaling is accomplished through software; the sample rate is not changed, but the driver interpolates by skipping or synthesizing samples. For example, if the playback rate is changed by a factor of two, the driver skips every other sample.

playing a metafile

The process of converting the records in a metafile into the respective device commands and drawing the corresponding picture on the device. See also metafile.

Point-to-Point Protocol (PPP)

The Point-to-Point Protocol, or PPP, is an industry-standard suite of control protocols that allow multiple network protocols to be carried on a point-to-point link. Windows NT supports IP, IPX, and NBF connections using PPP. This allows the use of applications that write to a network-specific interface, connections to third-party PPP servers, and remote access to the Internet.

polygon

A closed figure with straight sides. In Windows, a polygon is outlined by using the current pen and filled by using the current brush. See also brush, pen.

polygon fill mode

An algorithm that determines the parts of a region that can be filled, painted, inverted, or clipped. See also region.

polygonal region

A region with the shape of a polygon. See also polygon, region.

polyphony

The maximum number of notes that a Musical Instrument Digital Interface (MIDI) output device can play simultaneously.

pop-up item

A menu item that, when chosen, displays a pop-up menu. See also menu item, pop-up menu.

pop-up menu

A menu that is hidden until the user performs an action that causes Windows to display the menu. See also menu.

pop-up window

A special type of overlapped window typically used for dialog boxes, message boxes, and other temporary windows that appear outside an application's main window.

PPP

See Point-to-Point Protocol.

PPQN

See parts per quarter note.

precomposed character

An accented character represented by a single character value. See also base character, composite character, nonspacing character.

predefined control

A control belonging to a window class supplied by Windows.

preimaging

The process of building a movie frame in a memory buffer before it is displayed.

primary domain

The domain used by the local computer as its usual and default network environment. See also domain.

primary language identifier

An 8-bit value identifying the primary language in a language identifier. See also language identifier, sublanguage identifier.

primary thread

The initial thread of a process. Also called the main thread or thread 1. When the main or WinMain function of a primary thread returns, the ExitProcess function is called implicitly, terminating all other threads of the process. A primary thread does not differ from other threads with respect to signals because all signals are delivered to the thread that caused them. See also process, thread.

primary token

An access token that is typically created only by the Windows NT® executive layer. It may be assigned to a process to represent the default security information for that process. See also access token, impersonation token.

Print common dialog box

A common dialog box that displays information about the installed printer and its configuration. By altering and selecting controls in this dialog box, the user specifies how output should be printed and starts the printing process. See also common dialog box.

Print-setup common dialog box

A common dialog box that displays the current printer configuration and provides options for setting the paper orientation, size, and source. See also common dialog box.

priority class

A process priority category (high, normal, or idle) used to determine the scheduling priorities of a process's threads. Each priority class has five levels. See also thread.

private memory

Pages of a process's memory that cannot be accessed by other processes. All memory objects allocated by the GlobalAlloc, LocalAlloc, VirtualAlloc, and HeapAlloc functions are in private pages.

privilege

A locally unique identifier used to regulate the use of some system services. See also locally unique identifier (LUID).

process

An executing application that consists of a private virtual address space, code, data, and other operating system resources, such as files, pipes, and synchronization objects that are visible to the process. A process also contains one or more threads that run in the context of the process. See also pipe, process, thread.

profile

A set of configurable options for a user. See also control set.

push button

A rounded rectangle used by the user to start or cancel an operation by clicking the rectangle, which "pushes" the button. A default push button is "pushed" when the user presses the ENTER key. See also button.


Q

queued message

A message in a message queue. See also message queue.


R

race condition

A bug in a multithreaded process where the code of thread A relies on thread B to complete some action, but where there is no synchronization between the two threads. The process works if thread B wins the race by completing its action before thread A needs it, but the process fails if thread A wins the race. See also process, thread.

radial

A line drawn from the center of an ellipse to a point on the ellipse. See also ellipse.

radio button

A round button operated by the user to choose from a set of related but mutually exclusive options. The check mark for a radio button is a black dot. A radio button can assume two states: checked (dot) or unchecked (no dot). In automatic radio buttons, Windows is responsible for changing the state of the radio button.

raster device

A device that creates text and graphics output by highlighting rows and columns of pixels (in the case of video displays) or rows and columns of dots (in the case of printers). See also pixel.

rasterizer

A Windows dynamic-link library that converts the graphics commands and hints for TrueType glyphs into actual bitmaps that are drawn on a video display or page of paper. See also bitmap, glyph, dynamic-link library (DLL).

rectangular region

A region with the shape of a rectangle. See also region.

Red Book audio

See compact disc − digital audio (CD-DA).

red, green, blue (RGB) format

A color format that identifies a given color with a red, green, blue (RGB) triplet. This format is used by video displays.

reference count

The number of times a string has been added to or deleted from an atom table. The AddAtom or GlobalAddAtom function increments the count; the DeleteAtom or GlobalDeleteAtom function decrements the count. See also atom table.

reference device

The device where the original picture was created.

reference device context (DC)

The device context associated with the reference device.

reflection

A transformation that creates a mirror image of an object.

region

A rectangle, polygon, ellipse (or a combination of two or more of these shapes) used by Windows-based applications to define a part of the client area to be painted, inverted, filled with output, framed, or used for hit testing. See also ellipse, hit testing, polygon.

region operation

A procedure such as inverting, painting, clipping, or hit testing. See also clipping, hit testing.

registered clipboard format

A clipboard format registered by an application, as opposed to a standard clipboard format.

registry

The database in which configuration information is registered. This database takes the place of most configuration and initialization files for Windows and new Windows-based applications.

regular curve

A curve that defines the perimeter of a conic section.

relative identifier (RID)

The portion of a security identifier (SID) that identifies a user or group in relation to the authority that issued the SID. See also security identifier (SID).

render

To make data available in a specific clipboard format. See also clipboard format.

Replace common dialog box

A common dialog box that displays two edit controls where the user can type strings: The first string identifies a word or value that the application should replace, and the second string identifies the replacement word or value. See also common dialog box, edit control.

reserved page

A page of memory in a process's virtual address space that has been set aside for future use. The page is not accessible and has no physical storage associated with it. A reserve page reserves a range of virtual addresses that cannot be used subsequently by other allocation operations.

resolution

(1) For joysticks, the minimum and maximum intervals between joystick messages sent for a captured joystick.

(2) For timers, the accuracy of the timer event. A resolution value of zero means that the event must occur at the exact time requested; a resolution value of ten means that the event must occur within ten milliseconds of the requested time.

resource

Binary data the resource compiler or developer adds to an application's executable file. Windows resources include icons, cursors, menus, dialog boxes, bitmaps, fonts, keyboard-accelerator tables, message-table entries, string-table entries, version data, and user-defined data.

resource compiler

An application that creates a binary resource file based on the resource-definition file. The resource compiler can also append binary resource data to an executable file and create a resource table in the executable file's header. See also resource table.

resource-definition file

A text file containing descriptions of an application's resources. The resource compiler creates a binary resource file based on the contents of the resource-definition file. Resource-definition files usually have a .RC extension.

resource file

A binary file created by the resource compiler that contains an application's resource data. Resource files usually have a .RES extension. See also resource compiler.

Resource Interchange File Format (RIFF)

A tagged-file specification used to define standard formats for multimedia files. Tagged-file structure helps prevent compatibility problems that often occur when file-format definitions change over time. Because each piece of data in the file is identified by a standard header, an application that does not recognize a given data element can skip over the unknown information. See also tagged file format.

resource object

An object file that consists of the resource file and the resource table. The linker links the resource object to the executable file. See also resource file.

resource table

Data the resource compiler adds to the header of an application's executable file. This data includes the location, name, type, language, and so on, of each resource in the executable file. See also resource compiler.

restore box

A bitmap that, when clicked, restores the window to its previous size and position.

restored window

A window that does not have the WS_MAXIMIZE or WS_MINIMIZE style.

RGB format

See red, green, blue (RGB) format.

RID

See relative identifier (RID).

RIFF

See Resource Interchange File Format (RIFF).

RIFF chunk

A chunk with chunk identifier Resource Interchange File Format (RIFF) that includes an identifying code and zero or more subchunks, the contents of which depend on the form type.

RIFF file

A file whose format complies with one of the published Resource Interchange File Format (RIFF) forms. Examples of RIFF files include WAVE files for waveform audio data, RMID files for Musical Instrument Digital Interface (MIDI) sequences, and RDIB files for device-independent bitmaps.

RIFF form

A file-format specification based on the Resource Interchange File Format (RIFF) standard.

root directory

The topmost directory on a volume. Files and directories on a volume are organized in a tree structure whose entry point is the root directory. The root directory is referenced in a path by a single backslash (\\) or a leading backslash in a longer path (\\MYDIR\\MYFILE.TXT). See also directory, path, volume.

rotation

A transformation that rotates an object with respect to the coordinate-space origin.

run-time linking

Dynamic linking that occurs when the LoadLibrary and GetProcAddress functions are used to get the starting address of a dynamic-link library (DLL) function.


S

SACL

See system access control list.

sample

A discrete piece of waveform data represented by a single numerical value. Sampling is the process of converting analog data to digital data by taking samples of the analog waveform at regular intervals.

sampling rate

The rate at which a waveform audio driver performs audio-to-digital or digital-to-audio conversion. For compact disc − digital audio (CD-DA), the sampling rate is 44.1 kHz. See also compact disc − digital audio

Save As common dialog box

A common dialog box that displays a list of filenames matching any specified extensions, directories, or drives. By selecting one of the listed filenames, the user indicates what file an application should save. See also common dialog box.

scalable font

A TrueType font. See also TrueType font.

scaling

A transformation that alters the apparent size of an object.

scan code

A device-dependent value that identifies a physical key on the keyboard. Each key on a keyboard generates two unique scan codes--one when the user presses the key and the other when the user releases the key.

scan line

A single row of adjacent pixels on a video display. See also pixel.

scheduler

The component of the operating system that determines which of the competing threads receives the next slice of the processor's time. See also thread.

screen buffer

A two-dimensional array of character and color data for output in a console window. A screen buffer can be accessed for reading and writing whether it is active or inactive. Its character data can be either a Unicode™ or ANSI value. See also console window.

screen coordinates

Coordinates relative to the upper left corner of the screen.

scroll bar

An element of the Windows user interface that converts mouse or keyboard input into values that a window procedure can use to shift the contents of a window's client area either horizontally or vertically. See also window procedure.

scroll bar control

A predefined control window that belongs to the SCROLLBAR window class. See also window.

scroll box

A movable area in a scroll bar that indicates the position of the information currently displayed in the associated window. The position of the scroll box is relative to the total amount of information available for display. See also scroll bar.

scrolling

The process of shifting a data object in a window's client area in order to see parts of the object that extend beyond the border of the client area.

scrolling range

The minimum and maximum values that a scroll bar can report. See also scroll bar.

secant

A line drawn through two points on an ellipse. See also ellipse.

secret

A key value that the software publisher chooses and then typically encrypts within the software license. An LSAPI-compliant license must have a minimum of four secrets, each 4 bytes (32 bits) long. See also basic challenge protocol, License Service Application Programming Interface (LSAPI), MD4 Message-Digest Algorithm.

security descriptor

A structure that contains the security information associated with an object. An absolute security descriptor contains pointers to the information, and a self-relative security descriptor stores the structure and associated information contiguously in memory. See also absolute security descriptor, self-relative security descriptor.

security domain

A collection of nodes in a security database that share a common set of user and group accounts.

security identifier (SID)

A structure of variable length that uniquely identifies a user or group on all Windows NT® implementations.

seek

(1) With file input and output (I/O), to change the current position in the file. (The current position is the location where the next read or write operation will take place.)

(2) With a media device (such as a hard disk), to position the medium so a certain sector can be accessed. The seek operation involves a physical movement of the device, so the time it takes can often be perceived by the user.

selection field

The portion of a combo box that displays the currently selected item. Selecting an item in the list causes that item to appear in the selection field. In simple and drop-down combo boxes, the selection field is an edit control and can be used to enter input not in the list.

self-relative security descriptor

See security descriptor.

semaphore object

An interprocess synchronization object that maintains a count between zero and some maximum value. The object's state is set to signaled when its count is greater than zero, and nonsignaled when its count is zero. See also synchronization object.

sequence

See MIDI sequence.

sequencer

See MIDI sequencer.

service

An executable object that is installed in a registry database maintained by the Service Control Manager. The executable file associated with a service can be started at boot time by a boot program or by the system, or it can be started on demand by the Service Control Manager. The two types of service are Win32 service and driver service. See also driver service, Win32 service.

service control manager

A Windows NT system process that provides a unified and secure means of controlling Win32 and driver services. Each computer that is running Windows NT has a service control manager process that is started during system startup.

service name

A string that a server application responds to when a client attempts to establish a conversation with the server.

setmark

A special recorded element that contains no user data and is used to provide a segmentation scheme hierarchically superior to filemarks. Setmarks typically provide faster positioning on high-capacity tapes.

share mode

A condition that indicates whether a file is to be shared for reading, writing, both, or neither.

shared arena

The Windows 95 shared arena (or shared address space) is the memory in the address range between 2 GB and 3 GB. It contains components that must be mapped into the address space of every process, such as the 16-bit global heap, shared system DLLs, and file views of file mapping objects. The DPMI server also allocates memory in this address range.

shared memory

Memory that two or more processes can read from and write to. If the file-mapping object that references the shared memory has a name, the memory is referred to as "named shared memory."

sharepoint

A network resource that remote applications can address specifically and use across a network--for example, a printer or a shared directory. See also container.

shearing

A transformation that alters the apparent length and orientation of vertical or horizontal lines in an object.

shell

An application that enables users to group, start, and otherwise control other applications.

short filemark

A filemark that contains a short erase gap that cannot be overwritten unless the write operation is performed from the beginning of the partition or from an earlier long filemark.

show state

The collective qualities of a window at a given time (whether active or visible; minimized; maximized; or restored).

shut down

To stop all processes, flush all file-system buffers to disk, and bring the system to a condition in which it is safe to turn off the computer.

sibling window

A child window that has the same parent window as one or more other child windows.

SID

See security identifier (SID).

signaled

The state of an object used for synchronization in one of the wait functions. A signaled state can enable the wait function to return. See also nonsignaled, wait function.

signature

A 4-byte value that identifies an enhanced metafile. See also enhanced metafile.

simple combo box

A combo box in which the list box is visible at all times.

simple device

A media control interface (MCI) device that does not require a device element (data file) for playback. The MCI compact disc audio driver is an example of a simple device.

simple list

A list in a combo box that is always visible. Combo boxes with the CBS_SIMPLE style contain simple lists.

single-byte character set

to their identifying numeric values, in which each value is one byte wide. The ANSI and original equipment manufacturer (OEM) character sets are single-byte character sets. See also character set, multibyte character set, Unicode.

single-selection list box

A list box in which only one item can be selected at a time.

sizing border A type of window border that enables the user to size the window by clicking and dragging the border.

SMPTE

See Society of Motion Picture and Television Engineers.

SMPTE division type

One of four SMPTE timing formats. SMPTE time is expressed in hours, minutes, seconds, and frames. The SMPTE division type specifies the frames-per-second value corresponding to a given SMPTE time. For example, a SMPTE time of one hour, 30 minutes, 24 seconds, and 15 frames is useful only if the frames-per-second value, or SMPTE division type, is known.

SMPTE offset

A Musical Instrument Digital Interface (MIDI) event that designates the SMPTE time at which playback of a MIDI file is to start. SMPTE offsets are used only with MIDI files using SMPTE division type.

SMPTE time

A standard representation of time developed for the video and film industries. SMPTE time is used with Musical Instrument Digital Interface (MIDI) audio because many people use MIDI to score films and video. SMPTE time is an absolute time format expressed in hours, minutes, seconds, and frames. Standard SMPTE division types are 24, 25, and 30 frames per second.

Society of Motion Picture and Television Engineers (SMPTE)

An association of engineers involved in movie, television, and video production. SMPTE also refers to SMPTE time, the timing standard that this group adopted.

solid brush

A logical brush created from a bitmap that contains pixels of the same color. See also bitmap, logical brush, pixel.

source

A configuration registry key that specifies message-file names for replacement strings in events logged by an application, service, or group of applications. Sources are subkeys of logfile keys. See also key, logfile, subkey.

square-wave synthesizer

A synthesizer that produces sound by adding square waves of various frequencies. A square wave is a rectangular waveform.

standard cursors

The default cursors that Windows automatically displays when users move windows or icons, resize windows, or wait. Standard cursors include an arrow, hourglass, crosshair, and I-beam. Standard cursors are also known as system cursors. See also cursor, icon, window.

standard icons

The default icons that Windows displays in system message boxes. Standard icons include, among other bitmaps, a stop sign and a circled exclamation point. See also icon.

standard resource

A resource whose format is defined and recognized by Windows. Standard resources include icons, cursors, menus, dialog boxes, bitmaps, fonts, keyboard accelerator tables, message-table entries, string-table entries, and version data.

standard scroll bar

A scroll bar created as part of the nonclient area of an overlapped, pop-up, or child window. See also scroll bar.

standard VGA

A video adapter that supports a resolution of 640 by 480 pixels and 16 simultaneous colors. See also pixel.

static control

An element of the Windows user interface used to display text and graphics that require no response from the user. Static controls are typically used in dialog boxes.

stock brush

One of seven logical brushes maintained by Windows. See also logical brush.

stock pen

A cosmetic pen created and maintained by the window manager. There are three kinds of stock pens: black, white, and invisible. See also cosmetic pen.

streaming

The process of transferring information from a storage device, such as a hard disk or CD-ROM, to a device driver.

string atom

An atom that identifies a character string in an atom table. See also atom, atom table.

string handle

A doubleword value, assigned by the operating system, that identifies a string passed between a dynamic data exchange (DDE) client and a DDE server. See also dynamic data exchange (DDE).

stroked path

A path that is outlined by using the pen that is currently selected into an application's device context. See also device context, path, pen.

structured exception handling

A mechanism for handling hardware- and software-generated exceptions. Structured exception handling gives developers complete control over the handling of exceptions, provides support for debuggers, and is usable across all programming languages and computers.

style names

One of two attributes used to organize TrueType® fonts. Style names include extra-bold, bold, and italic. (The other attribute used to organize TrueType fonts is the family name.) See also TrueType font.

subclass procedure

An application-defined window procedure that replaces a window's original window procedure when the window is subclassed. See also subclassing, window procedure.

subclassing

A technique that allows an application to intercept and process messages sent or posted to a particular window before the window has a chance to process them. See also subclass procedure.

subdirectory

A directory within another directory. See also directory.

subkey

An entry (or node) in the registry subordinate to a given key. With the exception of four predefined keys, all keys are subkeys of other keys. See also key, registry.

sublanguage identifier

An 8-bit value identifying the variant of a language in a language identifier. See also language identifier, primary language identifier.

subtractive color technology

The color technology, used by ink-based printers, that is based on the three primary colors cyan, yellow, and magenta. Other colors (except white) are obtained by combining two or more of the primaries in varying amounts. White is defined as the absence of the primaries. Black is defined as the presence of all the primaries.

super VGA

A video adapter that supports resolutions higher than 640-by-480 pixels or more than 16 simultaneous colors (or both).

superclass procedure

An application-defined window procedure that replaces the window procedure for a window of a particular window class when the class is superclassed. See also superclassing, window procedure.

superclassing

A technique that allows an application to create a new window class that has the basic functionality of the existing class, but with enhancements provided by the application. See also superclass procedure.

syllabary

A single character that represents what we would call a syllable, using consonant/vowel combinations as their linguistically-discrete units — for example, the sound created by "ta." This term would apply to Kana (Katakana and Hiragana) and Hangul scripts. Linguists use the word "syllabary" to define a system of phonemic (linguistically-distinct) syllabic units used in a language.

synchronization object

An object whose handle can be specified in one of the wait functions to coordinate the execution of multiple threads. Synchronization objects include change notification, console input, event, mutex, process, thread, and semaphore objects. See also object, wait function.

system access-control list (SACL)

An access-control list (ACL) that is controlled by a system administrator and used to control the generation of audit messages. See also access-control list (ACL), discretionary access-control list (DACL).

system directory

The directory that contains Windows libraries, drivers, and font files. See also directory.

system-exclusive data

In Musical Instrument Digital Interface (MIDI), messages understood only by MIDI devices from a specific manufacturer. MIDI device manufacturers can use system-exclusive data to define custom messages that can be exchanged between their MIDI devices. (The standard MIDI specification defines only a framework for system-exclusive messages.) See also Musical Instrument Digital Interface.

System menu

A pop-up menu, defined mainly by the operating system, that typically contains commands used to set a window's size or position, close a window or application, or activate a different application. See also pop-up menu.

system metric

A dimension of a Windows display element, such as the border width, scroll bar arrow height, icon height, and so on. System metrics may also describe other aspects of the operating system, such as whether a mouse is installed, whether the current version of Windows supports double-byte characters, and so on. See also scroll bar.

system paging file

The storage file that the kernel uses to hold pages of memory swapped out of RAM.

system palette

An array that identifies all of the colors that can be displayed simultaneously on a device. For most displays, this array is a subset of all possible colors that can appear on the display.

system time

The "real-time" clock format. System time uses a structure containing individual members for the date and time.


T

tagged file format

A file format in which data is tagged using standard headers that identify information type and length. See also Resource Interchange File Format (RIFF).

tape drive

A device that reads from and writes to a tape.

tape volume

A recording medium and its physical carrier.

tempo

The speed at which a Musical Instrument Digital Interface (MIDI) file is played. Tempo is measured in beats per minute (BPM); typical MIDI tempo is 120 BPM. See also Musical Instrument Digital Interface.

tension

To move the tape to the end-of-medium marker and back to the beginning-of-medium marker in one command.

termination handler

A mechanism by which a developer ensures that a block of termination code is executed. A termination handler consists of a guarded body of code and a termination block. See also guarded body of code.

thread

The basic entity to which the operating system allocates CPU time. A thread can execute any part of the application's code, including a part currently being executed by another thread. All threads of a process share the virtual address space, global variables, and operating system resources of the process. See also process.

thread affinity mask

A bit vector in which each bit represents the processors that a thread is allowed to run on.

thread local storage

A storage method in which an index can be used by multiple threads of the same process to store and retrieve a different value for each thread. See also thread.

threshold

For the joystick interface, the amount, in device units, that the stick coordinates must change before the application is notified of the movement. A high threshold reduces the number of joystick messages sent to an application, but it also reduces the sensitivity of the joystick.

time-out value

The interval, in milliseconds, measured by a timer.

timer

An internal routine that causes the system to send a WM_TIMER message whenever a specified interval elapses.

timer object

An interprocess synchronization object whose state is set to signaled when the specified due time arrives. See also due time, synchronization object.

time slice

A unit of processor time (in clock ticks) allocated to a thread. See also thread.

time stamp

A tag that enables a Musical Instrument Digital Interface (MIDI) sequencer to replay recorded MIDI data at the proper moment. See also Musical Instrument Digital Interface.

title bar

A window component that displays an application-defined line of text. Typically, the text identifies the application or indicates the purpose of the window.

TLS

See thread local storage.

TMSF time format

A time format used by Media Control Interface (MCI) to express time in tracks, minutes, seconds, and frames. The number of frames in a second depends on the type of device being used; compact disc audio devices use 75 frames per second. The TMSF time format is used primarily by compact disc audio devices. See also Media Control Interface (MCI).

token

See access token.

top-down DIB

A device-independent bitmap (DIB) whose origin lies at the top-left corner. See also bottom-up DIB.

top-level window

A window that has no parent window.

topic name

A string that identifies the type of data requested by a dynamic data exchange (DDE) client application.

topmost window

A window with the WS_EX_TOPMOST style. A topmost window overlaps all other non-topmost windows.

track

A sequence of sound on a compact disc − digital audio (CD-DA) disc. With a Musical Instrument Digital Interface (MIDI) file, information can be separated into tracks, defined by the creator of the file. MIDI file tracks can correspond to MIDI channels, or they can correspond to parts of a song (such as melody or chorus); a CD-DA track usually corresponds to a song. See also compact disc − digital audio.

transaction filter

A flag that prevents the Data Exchange Management Library (DDEML) from passing an unwanted type of transaction to an application's dynamic data exchange (DDE) callback function. See also dynamic data exchange (DDE).

transformation

An algorithm that alters ("transforms") the size, orientation, and shape of objects.

translation

A transformation that shifts an object farther from or closer to the coordinate-space origin.

TrueType font

A font whose glyphs are stored as a collection of line and curve commands plus a collection of hints. Windows uses the line and curve commands to define the outline of the glyph's bitmap. Windows uses the hints to adjust the length of the lines and shapes of the curves. These hints and the respective adjustments are based on the amount of scaling used to reduce or increase the size of the bitmap. See also bitmap, font, glyph.

try block

A guarded body of code in a try-except frame-based exception handler or try-finally termination handler. See also frame-based exception handler, guarded body of code, termination handler.


U

Unicode

A 16-bit character set capable of encoding all known characters and used as a worldwide character-encoding standard. Windows uses Unicode exclusively at the system level.

universal well-known security identifier (SID)

An SID that is meaningful on all secure systems using the security model implemented in Windows NT®.

user-defined pen

A cosmetic or geometric pen that uses a unique series of dashes, dots, or dashes and dots defined by the user. See also cosmetic pen, geometric pen.

UTC

See Coordinated Universal Time.


V

value

Data associated with a key. A key may have zero or more values. Each value has three parts: a name, a type, and data. See also key.

vector device

A device that creates text and graphics output by drawing lines.

viewport

A rectangle in device space that is used to specify a transformation between page and device space. The viewport extents are always measured in pixels for a video display or dots for printers.

viewport extent

The width or height of the viewport.

viewport origin

The corner of the viewport from which the extents are measured. (The viewport-origin coordinates are specified with respect to the device-space origin.)

virtual-key code

A device-independent value that identifies the purpose of a keystroke as interpreted by the Windows keyboard device driver.

visible region

The part of the client area that is visible to the user.

visible window

A window that has the WS_VISIBLE style. A visible window is displayed on the screen and can receive user input.

volatile key

A key that is valid only until the next time the operating system is started. See also key.

volume

A storage medium, such as a disk or tape, that is formatted to contain files and directories. A volume is accessed through a disk drive. In a path, a volume is referenced by the letter of the disk drive that accesses the volume. For example, a fixed disk may be referred to as C. A single volume may be divided into more than one logical volume, also called a partition. Each partition is referenced by a unique volume identifier.

volume scalar

A component of a Musical Instrument Digital Interface (MIDI) Mapper patch map that adjusts the volume of a patch on a synthesizer. For example, if the bass patch on a synthesizer is too loud relative to the piano patch, the volume scalar can reduce the volume for the bass or increase the volume for the piano. (Applications playing waveform audio can also adjust the output volume.) See also MIDI Mapper, patch.


W

waitable timer object

See timer object.

wait function

A function that blocks the execution of the calling thread until a specified set of conditions has been met.

waiting thread

A thread whose execution is blocked while waiting for a wait function to return. See also wait function.

WAVE file

A Microsoft standard file format for storing waveform audio data. WAVE files have a .WAV filename extension.

waveform audio

A technique of recreating an audio waveform from digital samples of the waveform.

wide character

A synonym for a Unicode™ character; Unicode characters are 2 bytes wide.

widened path

A modified path. See also path.

wildcard characters

Characters that represent one or more characters in a filename. The Windows wildcard characters are the question mark (?) and the asterisk (*). The question mark matches any single character; the asterisk matches any combination of characters. For example, if a directory contains files with the names BAT, B12, BOAT, and CAT, the pattern b\* matches the names BAT, B12, and BOAT. The pattern b?t matches only the name BAT.

Win32 service

A service that conforms to the interface rules of the Service Control Manger. This enables the Service Control Manager to start the service at system startup or on demand and enables communication between the service and service control programs. A Win32 service can execute in its own process, or it can share a process with other Win32 services.

window

A rectangle in page space that is used to specify a transformation between page and device space.

window extent

The width or height of the window.

window handle

A 32-bit value, assigned by Windows, that uniquely identifies a window.

window name

A text string that identifies a window for the user.

window origin

(1) The upper left corner of a window's client area.

(2) The corner of the window from which the extents are measured. (The window-origin coordinates are specified with respect to the page-space origin.)

window procedure

A function, called by the operating system, that controls the appearance and behavior of its associated windows. The procedure receives and processes all messages to these windows.

window style

A named constant that defines an aspect of the window's appearance and behavior not specified by the window's class.

window text

See window name.

Windows directory

The directory that contains Windows-based applications, initialization files, and Help files. See also directory.

Windows metafile

One of two metafile formats. This format, used for applications written to run with Windows version 3.x, consists of a header and an array of metafile records. See also metafile record.

Windows time

The number of milliseconds since Windows started running. This time is recorded as a 32-bit value, so it overflows to zero every 49.7 days.

world coordinate space

The coordinate space in which all graphics device interface (GDI) drawing operations begin if an application has set the world-space to page-space transformation.

world space

The coordinate space in which all graphics device interface (GDI) drawing operations begin if an application has set the world-space to page-space transformation. Applications use world space to rotate shear, or reflect graphics output. World space measures 2^(32) units high by 2^(32) units wide, and is one of four coordinate spaces used in the Win32 API. See also device coordinate space, page coordinate space, and physical device.


X

x-axis

The axis that normally extends horizontally across a coordinate space.


Y

y-axis

The axis that normally extends vertically across a coordinate space.


Z

Z order

A stack of overlapping windows. Each window has a unique position in the Z order.


Interfaces

The following interfaces are arranged in alphabetical order by interface type. The shell interfaces are used with shell extensions, shell links, name spaces, and appbars. The rich edit OLE interfaces and methods are used with rich text edit controls.

Shell Library Interfaces

ICommDlgBrowser
IContextMenu
IContextMenu2
ICopyHook
IEnumIDList
IExtractIcon
IFileViewer
IFileViewerSite
INotifyReplica
IPersistFolder
IReconcilableObject
IReconcileInitiator
IShellBrowser
IShellExecuteHook
IShellExtInit
IShellFolder
IShellIcon
IShellLink
IShellPropSheetExt
IShellView

Rich Edit OLE Interfaces

IRichEditOle
IRichEditOleCallback


ICommDlgBrowser

The ICommDlgBrowser interface is used by the common file dialog boxes to extend the behavior of the shell browser. This interface is received by calling QueryInterface on the IShellBrowser object.

When to Implement

This interface is implemented only by the common file-dialog boxes.

When to Use

Use ICommDlgBrowser when you want to provide special behavior when hosted inside the common dialog boxes.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
ICommDlgBrowser Methods	Description
OnDefaultCommand	Called when a user double-clicks in the view or presses the ENTER key.
OnStateChange	Called after a state of change has occurred in a common dialog box.
IncludeObject	Allows common dialog filter objects that the view presents..


ICommDlgBrowser::OnDefaultCommand Beta] NT Beta] [Now Supported on Windows NT]
ICommDlgBrowser::OnDefaultCommand

[Now Supported on Windows NT]

OnDefaultCommand is called when a user double-clicks in the view or presses the ENTER key.

HRESULT OnDefaultCommand( )

This method has no parameters.

Return Values

Returns NOERROR if successful or an OLE-defined error code otherwise.

Remarks

The browser should return S_OK if it has processed the action or S_FALSE to let the view perform the default action.

Notes to Callers

Allows the default command to be handled by the common dialog box instead of the view.

See Also

ICommDlgBrowser


ICommDlgBrowser::OnStateChange [Now Supported on Windows NT]
ICommDlgBrowser::OnStateChange

[Now Supported on Windows NT]

OnStateChange is called after a certain state has changed in the IShellView, as identified by the parameter passed in.

HRESULT OnStateChange(

ULONG uChange	Specifies the change in state
);
Parameters

uChange

Specifies the change in the selection state. This parameter can be one of the following values:

Value	Meaning
CDBOSC_SETFOCUS	The focus has been set to the view.
CDBOSC_KILLFOCUS	The focus has been lost from the view.
CDBOSC_SELCHANGE	The selection has changed.
CDBOSC_RENAME	An item has been renamed.
Return Values

OnStateChange does not return a value.

Remarks

OnStateChange is used to let the common file dialogs track the state of the view and change its UI as needed.

Notes to Callers

When items in the view are selected, or when the view loses the focus, it needs to call this member to notify the common dialog that either the view state or selection state is changing.

See Also

ICommDlgBrowser


ICommDlgBrowser::IncludeObject [Now Supported on Windows NT]
ICommDlgBrowser::IncludeObject

[Now Supported on Windows NT]

IncludeObject is used to allow the common dialog filter objects that the view presents.

HRESULT IncludeObject(

LPCITEMIDLIST pidl	//Pointer to an identifier list.
);
Parameters

pidl

Pointer to a identifier list (IDLIST) that is relative to the folder.

Return Values

The browser should return S_OK to include the object in the view, S_FALSE to hide it.

Remarks

IncludeObject is called by the IEnumIDList implementation when hosted in the file dialogs. The enumerator should call this function to let the common dialog filter out objects it does not want to display. Typically, the file dialogs will get the display text of the item, and filter by the extension.

Notes to Callers

Call before returning an object in the shell folder’s IDList enumerator.

See Also

ICommDlgBrowser


IContextMenu

The IContextMenu interface is used to either create or merge a context menu associated with a certain object.

Default context menus are available for most objects that are visible within the Explorer’s name space, such as files, folders, and printer objects. System-provided context menus are adaptable to file objects of any type, provided you have made the appropriate registry entries.

When to Implement

Implement IContexMenu in the following situations:

•	To add dynamic menu items to a context menu associated with an object in the shell’s name space. Implementation is accomplished by means of a handler located within an COM in-process server DLL.

•	To allow menu items to be dynamically added to non-default drag-and-drop menus. Implementation is accomplished by means of a handler.

•	Applications may either create or merge context menus of items in the shell’ name space (or extended name space). This is accomplished by an application calling IContextMenu using IShellFolder::GetUIObjectOf.

•	A namespace extension should implement IContextMenu so that either the shell or another application can access context menus belonging to items in its own name space. This is accomplished by using IShellFolder::GetUIObjectOf.

Shell extensions based on this interface must be initialized by using the IShellExtInit interface and menu items can be inserted by using either the InsertMenu or InsertMenuItem functions.

Also of note is that shell extensions do not work unless all appropriate registry entries are made.

When to Use

You don’t call this interface directly. It is called by the shell when a user selects a context menu item that has been added by a handler registered under the appropriate registry keys, or when an application includes it as the riid parameter in a call to IShellFolder::GetUIObjectOf.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IContextMenu Methods	Description
QueryContextMenu	Adds commands to a context menu.
InvokeCommand	Carries out a menu command, either in response to user input or otherwise. For an example, see IExtractIcon.
GetCommandString	Retrieves the language-independent name of a menu command or the help text for a menu command.


IContextMenu::GetCommandString [Now Supported on Windows NT]
IContextMenu::GetCommandString

[Now Supported on Windows NT]

Retrieves the language-independent command string or the help text for a context menu item.

HRESULT GetCommandString(

UINT idCmd,	//Menu item identifier offset
UINT uFlags,	//Specifies information to retrieve
UINT *pwReserved,	//Reserved; must be NULL
LPSTR pszName,	//Address of buffer to receive string
UINT cchMax	//Size of the buffer that receives the string
);
Parameters

idCmd

Menu item identifier offset.

uFlags

Flag specifying the information to retrieve. This parameter can be one of the following values:

Value	Meaning
GCS_HELPTEXT	Returns the help text for the menu item.
GCS_VALIDATE	Validates that the menu item exists.
GCS_VERB	Returns the language-independent command name for the menu item.
pwReserved

Reserved. Applications must specify NULL when calling this method, and handles must ignore this parameter when called.

pszName

Address of the buffer that receives the null-terminated string being retrieved.

cchMax

Size of the buffer that receives the null-terminated string.

Return Values

Returns NOERROR if successful or an OLE-defined error code otherwise.

Comments

The language-independent command name is a name that can be passed to the IContextMenu::InvokeCommand method to activates a command by an application. The help text is a description that the Explorer displays in its status bar; it should be reasonably short (under 40 characters).

See Also

IContextMenu


IContextMenu::InvokeCommand [Now Supported on Windows NT]
IContextMenu::InvokeCommand

[Now Supported on Windows NT]

Carries out the command associated with a context menu item.

HRESULT InvokeCommand(

LPCMINVOKECOMMANDINFO lpici	//Points to a command info structure
);
Parameters

lpici

Pointer to a CMINVOKECOMMANDINFO structure containing information about the command.

Return Values

Returns NOERROR if successful or an OLE-defined error code otherwise.

The shell calls this method when the user chooses a command that the handler added to a context menu. This method may also be called by an application without any corresponding user action.

See Also

CMINVOKECOMMANDINFO, IContextMenu


IContextMenu::QueryContextMenu [Now Supported on Windows NT]
IContextMenu::QueryContextMenu

[Now Supported on Windows NT]

Adds menu items to the specified menu. The menu items should be inserted at a specified position in the menu, and their menu item identifiers must be in a given range.

HRESULT QueryContextMenu(

HMENU hmenu,	//Handle of the menu
UINT indexMenu,	//Location to insert first menu item
UINT idCmdFirst,	//Minimum value for a menu item identifier
UINT idCmdLast,	//Maximum value for a menu item identifier
UINT uFlags	//Specifies zero or more status values
);
Parameters

hmenu

Handle of the menu. The handler should specify this handle when calling the InsertMenu or InsertMenuItem function.

indexMenu

Zero-based position at which to insert the first menu item.

idCmdFirst

Minimum value that the handler can specify for a menu item identifier.

idCmdLast

Maximum value that the handler can specify for menu item identifiers.

uFlags

Flag specifying zero or more of the following values:

CMF_DEFAULTONLY	The user is activating the default action, typically by double-clicking. This value provides a hint for the context menu to add nothing if it does not modify the default item in the menu. A context menu extension or drag-and-drop handler should not add any menu items if this value is specified. A name space extension should add only the default item (if any).
CMF_EXPLORE	Context menu handlers should ignore this value. It is specified when the context menu is for an object in the Explorer.
CMF_NORMAL	Indicates normal operation. A context menu extension, name-space extension, or drag and drop handler can add any menu items.
CMF_VERBSONLY	Context menu handlers should ignore this value. This value is specified if the context menu is for a shortcut object. This value is specified if the context menu is for a shortcut object.
The remaining bits of the low-order word are reserved by the system. The high-order word may be used for context-specific communications.

Return Values

Returns an HRESULT structure in which, if the method is successful, the code member contains the menu identifier offset of the last menu item added plus one.

Comments

The actual identifier of each menu item should be idCmdFirst plus a menu identifier offset in the range zero through (idCmdLast − idCmdFirst).

See Also

IContextMenu, InsertMenu, InsertMenuItem


IContextMenu2

The IContextMenu2 interface is used to either create or merge a context menu associated with a certain object when a client of IContextMenu is supposed to handle messages associated with owner-drawn menu items.

When to Implement

Implement IContexMenu2 if your object is a client of IContextMenu when owner-drawn messages are an issue: Do so if it is possible to receive one of the following messages while calling TrackPopupMenu in the window procedure of the menu’s owner window:

WM_INITPOPUP

WM_DRAWITEM

WM_MEASUREITEM

These messages are sent only if a QueryInterface call for an IContextMenu2 interface pointer is successful, indicating that the object supports this interface.

When to Use

You do not call this interface directly. IContextMenu2 is used by the operating system only when it has confirmed that the application is aware of this interface.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IContextMenu2 Methods	Description
QueryContextMenu	Adds commands to a context menu.
HandleMenuMsg	Handles messages related to drawing owner-drawn menu items.
InvokeCommand	Carries out a menu command, either in response to user input or otherwise. For an example, see IExtractIcon.
GetCommandString	Retrieves the language-independent name of a menu command or the help text for a menu command.


IContextMenu2::GetCommandString [Now Supported on Windows NT]
IContextMenu2::GetCommandString

[Now Supported on Windows NT]

Retrieves the language-independent command string or the help text for a context menu item.

HRESULT GetCommandString(

UINT idCmd,	//Menu item identifier offset
UINT uFlags,	//Specifies information to retrieve
UINT *pwReserved,	//Reserved; must be NULL
LPSTR pszName,	//Address of buffer to receive string
UINT cchMax	//Size of the buffer that receives the string
);
Parameters

idCmd

Menu item identifier offset.

uFlags

Flag specifying the information to retrieve. This parameter can be one of the following values:

Value	Meaning
GCS_HELPTEXT	Returns the help text for the menu item.
GCS_VALIDATE	Validates that the menu item exists.
GCS_VERB	Returns the language-independent command name for the menu item.
pwReserved

Reserved. Applications must specify NULL when calling this method, and handles must ignore this parameter when called.

pszName

Address of the buffer that receives the null-terminated string being retrieved.

cchMax

Size of the buffer that receives the null-terminated string.

Return Values

Returns NOERROR if successful or an OLE-defined error code otherwise.

Remarks

The language-independent command name is a name that can be passed to the IContextMenu::InvokeCommand method to activates a command by an application. The help text is a description that the Explorer displays in its status bar; it should be reasonably short (under 40 characters).

See Also

IContextMenu2, IContextMenu


IContextMenu2::HandleMenuMsg [Now Supported on Windows NT]
IContextMenu2::HandleMenuMsg

[Now Supported on Windows NT]

Allows client objects of IContextMenu to handle messages associated with owner-drawn menu items.

HRESULT HandleMenuMsg(

UINT uMsg,	//Specifies the message
WPARAM wParam,	//Depends on the contents of uMsg
LPARAMlParam	//Depends on the contents of uMsg
);
Parameters

uMsg

Specifies the message to be processed. If it is either WM_INITPOPUP, WM_DRAWITEM, or WM_MEASUREITEM, the client object being called may provide owner-drawn menu items.

wParam

Specifies additional message information. The value of this parameter depends on the value of the uMsg parameter.

lParam

Specifies additional message information. The value of this parameter depends on the value of the uMsg parameter.

Return Values

Returns NOERROR if successful or an OLE-defined error code otherwise.

Remarks

HandleMenuMsg is called when a client of IContextMenu is aware of the IContextMenu2 interface and receives one of the messages specified in the description of the uMsg parameter while the client is processing menu messages.

See Also

IContextMenu2, IContextMenu


IContextMenu2::InvokeCommand [Now Supported on Windows NT]
IContextMenu2::InvokeCommand

[Now Supported on Windows NT]

Carries out the command associated with a context menu item.

HRESULT InvokeCommand(

LPCMINVOKECOMMANDINFO lpici	//Points to a command info structure
);
Parameters

lpici

Pointer to a CMINVOKECOMMANDINFO structure containing information about the command.

Return Values

Returns NOERROR if successful or an OLE-defined error code otherwise.

The shell calls this method when the user chooses a command that the handler added to a context menu. This method may also be called by an application without any corresponding user action.

See Also

CMINVOKECOMMANDINFO, IContextMenu2, IContextMenu


IContextMenu2::QueryContextMenu [Now Supported on Windows NT]
IContextMenu2::QueryContextMenu

[Now Supported on Windows NT]

Adds menu items to the specified menu. The menu items should be inserted at a specified position in the menu, and their menu item identifiers must be in a given range.

HRESULT QueryContextMenu(

HMENU hmenu,	//Handle of the menu
UINT indexMenu,	//Location to insert first menu item
UINT idCmdFirst,	//Minimum value for a menu item identifier
UINT idCmdLast,	//Maximum value for a menu item identifier
UINT uFlags	//Specifies zero or more status values
);
Parameters

hmenu

Handle of the menu. The handler should specify this handle when calling the InsertMenu or InsertMenuItem function.

indexMenu

Zero-based position at which to insert the first menu item.

idCmdFirst

Minimum value that the handler can specify for a menu item identifier.

idCmdLast

Maximum value that the handler can specify for menu item identifiers.

uFlags

Flag specifying zero or more of the following values:

CMF_DEFAULTONLY	The user is activating the default action, typically by double-clicking. This value provides a hint for the context menu to add nothing if it does not modify the default item in the menu. A context menu extension or drag-and-drop handler should not add any menu items if this value is specified. A name space extension should add only the default item (if any).
CMF_EXPLORE	Context menu handlers should ignore this value. It is specified when the context menu is for an object in the Explorer.
CMF_NORMAL	Indicates normal operation. A context menu extension, name-space extension, or drag-and-drop handler can add any menu items.
CMF_VERBSONLY	Context menu handlers should ignore this value. This value is specified if the context menu is for a shortcut object. This value is specified if the context menu is for a shortcut object.
The remaining bits of the low-order word are reserved by the system. The high-order word may be used for context-specific communications.

Return Values

Returns an HRESULT structure in which, if the method is successful, the code member contains the menu identifier offset of the last menu item added plus one.

Remarks

The actual identifier of each menu item should be idCmdFirst plus a menu identifier offset in the range zero through (idCmdLast − idCmdFirst).

See Also

IContextMenu2, IContextMenu, InsertMenu, InsertMenuItem


ICopyHook

The ICopyHook interface is a COM-based interface used to create a copy hook handler, a shell extension, that determines whether it is all right to move, copy, rename, or delete a shell folder or printer object. The shell calls ICopyHook::CopyCallback prior to performing one of these operations.

The copy hook handler, which is an OLE in-process server (a DLL), does not perform the task itself, but does approve or disapprove the action. If the shell receives approval from the copy hook handler, it performs the file system operation. Copy hook handlers are not informed about the success of an operation, so cannot monitor actions taken on folder objects, except via FindFirstChangeNotify.

A folder object can have multiple copy hook handlers. For example, even if the shell already has a copy hook handler registered for a particular folder object, you can still register one of your own. If two or more copy hook handlers are registered for an object, the shell simply calls each of them before performing one the specified file system operations.

The shell initializes ICopyHook directly, without using the IShellExtInit or IPersistFile interfaces first.

CopyCallback returns an integer value that indicates whether or not the shell should perform the operation. The shell will call each copy hook handler registered for a folder object until either all the handlers have been called or one of them has returned a value other than IDYES. The handler can also return IDYES to specify that the operation should be performed, or IDNO or IDCANCEL to specify that the operation should be discontinued.

When to Implement

Implement a copy hook handler, for example for shared folders, when you want to be able to control when, or if. these file system operations are performed on a given object.

When to Use

You don’t call this shell extension directly. ICopyHook::CopyCallback is called by the shell prior to moving, copying, renaming, or deleting a shell folder object.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
ICopyHook Methods	Description
CopyCallback	Determines whether a move, copy, delete, or rename operation on a folder object should be allowed or disallowed.


ICopyHook::CopyCallback [Now Supported on Windows NT]
ICopyHook::CopyCallback

[Now Supported on Windows NT]

Either allows the shell to move, copy, delete, or rename a folder or printer object, or disallows the shell from carrying out the operation. The shell calls each copy hook handler registered (see Comments below) for a folder or printer object until either all the handlers have been called or one of them returns IDCANCEL.

UINT CopyCallback(

HWND hwnd,	//Handle of the parent window for displaying UI objects
UINT wFunc,	//Operation to perform.
UINT wFlags,	//Flags that control the operation
LPCSTR pszSrcFile,	//Pointer to the source file
DWORD dwSrcAttribs,	//Source file attributes
LPCSTR pszDestFile,	//Pointer to the destination file
DWORD dwDestAttribs	//Destination file attributes
);
Parameters

hwnd

Handle of the window that the copy hook handler should use as the parent window for any user interface elements the handler may need to display. If FOF_SILENT is specified, the method should ignore this parameter.

wFunc

Operation to perform. This parameter can be one of the following values:

FO_COPY 0x0002	Copies the file specified by pszSrcFile to the location specified by pszDestFile.
FO_DELETE 0x0003	Deletes the file specified by pszSrcFile.
FO_MOVE 0x0001	Moves the file specified by pszSrcFile to the location specified by pszDestFile.
FO_RENAME 0x0004	Renames the file specified by pszSrcFile.
PO_DELETE 0x0013	Deletes the printer specified by pszSrcFile.
PO_PORTCHANGE 0x0020	Changes the printer port. The pszSrcFile and pszDestFile parameters contain double null-terminated lists of strings. Each list contains the printer name followed by the port name. The port name in pszSrcFile is the current printer port, and the port name in pszDestFile is the new printer port.
PO_RENAME 0x0014	Renames the printer specified by pszSrcFile.
PO_REN_PORT 0x0034	Combination of PO_RENAME and PO_PORTCHANGE.
wFlags

Flags that control the operation. This parameter can be a combination of the following values:

FOF_ALLOWUNDO 0x0040	Preserves undo information (when possible).
FOF_CONFIRMMOUSE 0x0002	Not implemented.
FOF_FILESONLY 0x0080	Not implemented. The shell calls a copy hook handler only for folder objects, not files.
FOF_MULTIDESTFILES 0x0001	The SHFileOperation function specified multiple destination files (one for each source file) rather than one directory where all the source files are to be deposited. A copy hook handler typically ignores this value.
FOF_NOCONFIRMATION 0x0010	Responds with “yes to all” for any dialog box that is displayed.
FOF_NOCONFIRMMKDIR 0x0200	Does not confirm the creation of any needed directories if the operation requires a new directory to be created.
FOF_RENAMEONCOLLISION 0x0008	Gives the file being operated on a new name, such as, “Copy #1 of ...”, in a copy, move, or rename operation when a file with the target name already exists.
FOF_SILENT 0x0004	Displays no progress dialog box.
FOF_SIMPLEPROGRESS 0x0100	Displays a progress dialog box, but the dialog box does not show the names of the files.
pszSrcFile

Pointer to a string that contains the name of the source file.

dwSrcAttribs

Attributes of the source file. This parameter can be a combination of any of the file attribute flags (FILE_ATTRIBUTE_*) defined in the Windows header files.

pszDestFile

Pointer to a string that contains the name of the destination file.

dwDestAttribs

Attributes of the destination file. This parameter can be a combination of any of the file attribute flags (FILE_ATTRIBUTE_*) defined in the Windows header files.

Return Value

Returns an integer value that indicates whether or not the shell should perform the operation. It can be one of the following:

IDYES

Allows the operation.

IDNO

Prevents the operation on this file, but continues with any other operations (for example, a batch copy operation).

IDCANCEL

Prevents the current operation and cancels any pending operations.

Comments

You need to register your copyhook handler. For example, …\directory copyhook handlers are registered under HKEY_CLASSES_ROOT\directory\shellex\CopyHookHandlers\your_copyhook\{copyhook CLSID value}. Other registry keys associated with shell extensions are: *, Folder, Drives, Printers, Unknown, and AudioCD.

The shell initializes the ICopyHook  interface directly, when ICopyHook::CopyCallback is called, without using an IShellExtInit or IPersistFile interface first.

See Also

ICopyHook, SHFileOperation


IEnumIDList

The IEnumIDList interface enumerates item identifiers associated with shell folder objects. First, use IShellFolder::EnumObjects to create an item enumeration object and then use IEnumIDList to iterate through the item IDs in the enumeration object.

IEnumIDList has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. Next iterates through the item IDs one or more at a time, Skip passes over the next item ID in the list, Reset returns to the beginning of the item ID list, and Clone returns a duplicate item enumeration object.

When to Implement

You can implement this interface when you want a caller to be able to enumerate the item IDs contained in a folder object. You get a pointer to IEnumIDList through IShellFolder::EnumObjects.

When to Use

You don’t use this interface directly. IShellFolder::EnumObjects creates an enumeration object of this kind. In this case, the enumeration is a set of item identifiers. The shell calls then IEnumIDList  methods to enumerate the items contained in a enumeration object.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IEnumIDList Methods	Description
Next	Retrieves the specified number of item identifiers.
Skip	Skip over the specified number of items.
Reset	Return to the beginning of the enumeration.
Clone	Creates a new item enumeration object identical to the current one.


IEnumIDList::Clone [Now Supported on Windows NT]
IEnumIDList::Clone

[Now Supported on Windows NT]

Creates a new item enumeration object with the same contents and state as the current one.

HRESULT Clone(

IEnumIDList FAR * pEnumIDList,
IEnumIDList **ppenum
);
•	Returns the NOERROR value if successful or an OLE-defined error value otherwise.

Parmeters

pEnumIDList

Address of the IEnumIDList interface. In C++, this parameter is implicit.

ppenum

Address that receives a pointer to the new enumeration object. The calling application must eventually free the new object by calling its Release member function.

This member function makes it possible to record a particular point in the enumeration sequence and then return to that point at a later time.

See Also

IEnumIDList


IEnumIDList::Next [Now Supported on Windows NT]
IEnumIDList::Next

[Now Supported on Windows NT]

Retrieves the specified number of item identifiers in the enumeration sequence and advances the current position.

HRESULT Next(

IEnumIDList FAR *pEnumIDList,
ULONG celt,
LPITEMIDLIST *rgelt,
ULONG *pceltFetched
);
•	Returns the NOERROR value if successful, the S_FALSE value if there are no more items in the enumeration sequence, or an OLE-defined error value if an error occurs.

Parameters

pEnumIDList

Address of the IEnumIDList interface. In C++, this parameter is implicit.

celt

Specifies the number of elements in the array pointed to by the rgelt parameter.

rgelt

Address of an array in which to return the item identifiers. The calling application must free the item identifiers by using the task allocator (retrieved by the SHGetMalloc function).

pceltFetched

Address of a value that receives a count of the item identifiers actually returned in rgelt. The count can be smaller than the value specified in the celt parameter. This parameter can be NULL if, and only if, celt is one.

If this member function returns any value other than NOERROR, no entries in the rgelt array are valid on exit. They are all in an indeterminate state.

See Also

IEnumIDList


IEnumIDList::Reset [Now Supported on Windows NT]
IEnumIDList::Reset

[Now Supported on Windows NT]

Returns to the beginning of the enumeration sequence.

HRESULT Reset(

IEnumIDList FAR *pEnumIDList,
);
•	Returns the NOERROR value if successful or an OLE-defined error value otherwise.

Parameters

pEnumIDList

Address of the IEnumIDList interface. In C++, this parameter is implicit.

See Also

IEnumIDList


IEnumIDList::Skip [Now Supported on Windows NT]
IEnumIDList::Skip

[Now Supported on Windows NT]

Skips over the specified number of elements in the enumeration sequence.

HRESULT Skip(

IEnumIDList FAR *pEnumIDList,
ULONG celt
);
•	Returns the NOERROR value if successful or an OLE-defined error value otherwise.

Parameters

pEnumIDList

Address of the IEnumIDList interface. In C++, this parameter is implicit.

celt

Number of item identifiers to skip.

See Also

IEnumIDList


IExtractIcon

The IExtractIcon interface is used by the shell to retrieve icons for objects it displays.

The operating system provides default icons for file objects but you can specify custom icons by making appropriate registry entries and, in some cases, by using IExtractIcon.

When to Implement

You implement IExtractIcon to provide either instance-specific icons for objects in a particular class, or icons for subfolders that extend the Explorer’s name space. These implementations are accomplished by writing handler code in an OLE in-process server COM DLL.

In addition, if you implement IShellFolder, you will need to provide an implementation of IExtractIcon that callers can obtain by using IShellFolder::GetUIObjectOf.

Shell extensions based on IExtractIcon must be initialized by using IPersistFile::Load. You should also note that shell extensions do not work unless all appropriate registry entries are made.

When to Use

In most cases, you don’t call this interface directly. It is usually called by the shell when an icon has been made available by a properly registered handler. However, you can call IExtractIcon directly if you want to delegate the task of icon extracting to another object.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IExtractIcon Methods	Description
GetIconLocation	Retrieves the icon location for an object.
Extract	Extracts an icon from the specified location.


IExtractIcon::Extract [Now Supported on Windows NT]
IExtractIcon::Extract

[Now Supported on Windows NT]

Extracts an icon image from the specified location.

HRESULT Extract(

LPCSTR pszFile,	//Points to the icon location specifier
UINT nIconIndex,	//Icon index
HICON *phiconLarge,	//Points to variable for large icon handle
HICON *phiconSmall,	//Points to variable for small icon handle
UINT nIconSize	//Specifies the size of the large icon required
);
Parameters

pszFile

Pointer to a null-terminated string specifying the icon location.

nIconIndex

Icon index.

phiconLarge and phiconSmall

Pointer to the variable that receives the handle of the large icon.

phiconSmall

Pointer to the variable that receives the handle of the small icon.

nIconSize

Value specifying the size, in pixels, of the icon required. The LOWORD and HIWORD specify the size of the large and small icons, respectively. The size specified can be the width or height. The width of an icon always equals its height.

Return Values

Returns NOERROR if the function extracted the icon or S_FALSE if the calling application should extract the icon.

Remarks

The icon location and index are the same values returned by the IExtractIcon::GetIconLocation method. If this function returns S_FALSE, these values must specify an icon filename and index that form legal parameters for a call to ExtractIcon. If this function does not return S_FALSE, the calling application should make no assumptions about the meanings of the pszFile and nIconIndex parameters.

See Also

IExtractIcon, IExtractIcon::GetIconLocation


IExtractIcon::GetIconLocation [Now Supported on Windows NT]
IExtractIcon::GetIconLocation

[Now Supported on Windows NT]

Retrieves the location and index of an icon.

HRESULT GetIconLocation(

UINT uFlags,	//Status values
LPSTR szIconFile,	//Address of buffer receiving icon location
INT cchMax,	//Size of buffer receiving icon location
int *piIndex,	//Pointer that receivs the icon index
UINT *pwFlags	//Pointer to zero or more values
);
Parameters

uFlags

Flags. This parameter can be zero or the following values:

GIL_FORSHELL	The icon is to be displayed in a shell folder.
GIL_OPENICON	The icon should be in the “open” state if both open- and closed-state images are available. If this flag is not specified the icon should be in the normal or “closed” state. This flag is typically used for folder objects.
szIconFile and cchMax

Address of the buffer that receives the icon location. The icon location is a null-terminated string that identifies the location of the icon.

cchMax

Size of the buffer that receives the icon location.

piIndex

Pointer to an integer that receives the icon index, which further describes the icon location.

pwFlags

Pointer to an unsigned integer that receives zero or more of the following values:

GIL_DONTCACHE	The physical image bits for this icon should not be cached by the caller. This distinction is important to consider because a GIL_DONTCACHELOCATION flag may be introducted in future versions of the shell..
GIL_NOTFILENAME	The location is not a filename/index pair. Callers that decide to extract the icon from the location must call this object’s IExtractIcon::Extract method to obtain the desired icon images.
GIL_PERCLASS	All objects of this class have the same icon. This flag is used internally by the shell. Typical implementations of IExtractIcon do not require this flag because it implies that an icon handler is not required to resolve the icon on a per-object basis. the recommended method for implementing per-class icons is to register a DefaultIcon for the class.
GIL_PERINSTANCE	Each object of this class has its own icon. Used internally by the shell to handle cases like setup.exe where more than one object with identical names could be known to the shell and have different icons. Typical implementations of IExtractIcon do not require this flag.
GIL_SIMULATEDOC	The caller should create a document icon using the specified icon.
Return Values

Returns NOERROR if the function returned a valid location or S_FALSE if the shell should use a default icon.

See Also

IExtractIcon, IExtractIcon::Extract


IFileViewer

Designates an interface that allows a registered file viewer to be notified when it must show or print a file. The shell calls this interface when the user selects the Quick View command from a file’s context menu and the file is a type that the file viewer recognizes. The IFileViewer interface has the following member functions:

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IFileViewer Methods	Description
PrintTo	Prints a file.
Show	Displays a file.
ShowInitialize	Prepares to display a file.


IFileViewer::PrintTo [Now Supported on Windows NT]
IFileViewer::PrintTo

[Now Supported on Windows NT]

Prints a file.

The shell specifies the name of the file to print by calling the file viewer’s IPersistFile::Load member function.

HRESULT PrintTo(

IFileViewer FAR *pFileViewer,
LPSTR pszDriver,
BOOL fSuppressUI
);
Parameters

pFileViewer

Address of the IFileViewer interface. In C++, this parameter is implicit.

pszDriver

Address of a buffer that contains the name of the printer device driver that should print the file. If this parameter is NULL, the file viewer determines which device driver to use.

fSuppressUI

User interface suppression flag. If this parameter TRUE, the file viewer should not display any UI whatsoever, including error messages, during the print operation. If this parameter FALSE, the file viewer can show dialog boxes, as needed.

Return Values

Returns the NOERROR value if successful or an OLE-defined error value otherwise.

See Also

IFileViewer


IFileViewer::Show [Now Supported on Windows NT]
IFileViewer::Show

[Now Supported on Windows NT]

Displays a file.

The shell specifies the name of the file to display by calling the file viewer’s IPersistFile::Load member function.

IFileViewer::Show can fail only if IFileViewer::ShowInitialize was not called first, and the return value must be E_UNEXPECTED in that case. Otherwise, IFileViewer::Show must return NOERROR.

HRESULT Show(

IFileViewer FAR *pFileViewer,
LPFVSHOWINFO pvsi
);
Parameters

pFileViewer

Address of the IFileViewer interface. In C++, this parameter is implicit.

pvsi

Address of an FVSHOWINFO structure containing information that the file viewer uses to display the file. A file viewer can return information to the shell by modifying the members of the structure.

Return Values

Returns the NOERROR value if successful or the E_UNEXPECTED value if the IFileViewer::ShowInitialize member function was not called before IFileViewer::Show.

See Also

IFileViewer


IFileViewer::ShowInitialize [Now Supported on Windows NT]
IFileViewer::ShowInitialize

[Now Supported on Windows NT]

Allows a file viewer to determine whether it can display a file and, if it can, to perform initialization operations before showing the file.

The shell calls this member function before the IFileViewer::Show member function. The shell specifies the name of the file to display by calling the file viewer’s IPersistFile::Load member function.

IFileViewer::ShowInitialize must perform all operations that are prone to failure so that if it succeeds, IFileViewer::Show will not fail.

HRESULT ShowInitialize(

IFileViewer FAR *pFileViewer,
LPFILEVIEWERSITE lpfsi
);
Parameters

pFileViewer

Address of the IFileViewer interface. In C++, this parameter is implicit.

lpfsi

Address of a IFileViewerSite interface. A file viewer uses this interface to retrieve the handle of the current pinned window or to specify a new pinned window.

Return Values

Returns the NOERROR value if successful or an OLE-defined error value otherwise.

See Also

IFileViewer


IFileViewerSite

Designates an interface that allows a file viewer to retrieve the handle of the current pinned window or to set a new pinned window. The pinned window is the window in which the current file viewer is displaying a file. When the user selects a new file to view, the shell directs the file viewer to display the new file in the pinned window rather than to create a new window.

The IFileViewerSite interface has the following member functions.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IFileViewerSite Methods	Description
GetPinnedWindow	Retrives the handle of the current pinned window.
SetPinnedWindow	Sets a new pinned window.


IFileViewerSite::GetPinnedWindow [Now Supported on Windows NT]
IFileViewerSite::GetPinnedWindow

[Now Supported on Windows NT]

Retrieves the handle of the current pinned window, if it exists.

HRESULT GetPinnedWindow(

IFileViewerSite FAR *pFileVS,
HWND *phwnd
);
Parameters

pFileVS

Address of the IFileViewerSite interface. In C++, this parameter is implicit.

phwnd

Address of a window handle of the current pinned window or NULL if no pinned window exists.

Return Values

Returns the NOERROR value if successful or an OLE-defined error value otherwise.

See Also

IFileViewerSite


IFileViewerSite::SetPinnedWindow [Now Supported on Windows NT]
IFileViewerSite::SetPinnedWindow

[Now Supported on Windows NT]

Sets a new pinned window.

When the user selects a new file to view, the shell directs the file viewer to display the new file in the pinned window instead of creating a new window.

HRESULT SetPinnedWindow(

IFileViewerSite FAR *pFileVS,
HWND *hwnd
);
Parameters

pFileVs

Address of the IFileViewerSite interface. In C++, this parameter is implicit.

hwnd

Handle of the new pinned window or NULL if there is to be no pinned window.

Return Values

Returns the NOERROR value if successful or an OLE-defined error value otherwise.

See Also

IFileViewerSite


INotifyReplica

The INotifyReplica interface provides the initiator with the means to notify an object that it may be subject to subsequent reconciliation. This interface has the YouAreAReplica member function. The briefcase reconciler is responsible for implementing this interface.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
INotifyReplica Methods	Description
YouAreAReplica	Notifies an object that it may be subject to reconciliation.


INotifyReplica::YouAreAReplica [Now Supported on Windows NT]
INotifyReplica::YouAreAReplica

[Now Supported on Windows NT]

Notifies an object that it may be subject to subsequent reconciliation through the IReconilableObject::Reconcile member function.

An object may be notified that it is a replica more than once. Briefcase reconcilers are not required to implement this interface. Initiators are not required to call this interface if it is implemented. However, an object’s implementation of IReconcilableObject::Reconcile may reasonably fail if that object has not previously been notified through INotifyReplica::YouAreAReplica that it may be subject to reconciliation.

Briefcase calls INotifyReplica when objects are added to it.

HRESULT INotifyReplica::YouAreAReplica(

ULONG ulcOtherReplicas,
IMoniker ** rgpmkOtherReplicas
);
Parameters

ulcOtherReplicas

Number of other replicas of the object. This parameter must not be zero.

rgpmkOtherReplicas

Address of an array that contains the addresses of the monikers to use to access the other replicas.

Return Values

Returns the S_OK value if successful. Otherwise, the member function returns one of the following error values:

E_UNEXPECTED	Unspecified error.
See Also

INotifyReplica


IPersistFolder

The IPersistFolder interface is used to initialize shell folder objects.

When to Implement

When implementing a shell namespace extension, specifically IShellFolder, you need to implement this interface so the folder object can be initialized this is how the folder is told where it is in the shell namespace.

When to Use

You don’t use this interface directly. It is used by the file system implementation of IShellFolder::BindToObject when it is initializing a shell folder object.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IPersist Method	Description
GetClassID	Returns the class identifier (CLSID) for the component object.
IIPersisFolder Method	Description
Initialize	Called when the Explorer initializes a shell folder object.


IPersistFolder::Initialize [Now Supported on Windows NT]
IPersistFolder::Initialize

[Now Supported on Windows NT]

The IPersistFolder::Initialize method is called whenever the Explorer is initializing a shell folder object.

HRESULT Initialize(

LPCITEMIDLIST pidl,	//Folder’s absolute location.
);
Parameters

pidl

Pointer to the ITEMIDLIST (tem identifiier list) structure that specifies the absolute location of the folder.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

Notes to Implementors

All objects that implement IShellFolder for use in the shell’s name space must implement this method. When a folder’s location in the name space is not a relevant consideration, Initialize can simply return NOERROR. When the location is relevant to the folder, you should store the fully qualified IDLIST passed in for future reference.

For example, if the folder implementation needs to construct a fully qualified PIDL to elements that it contains, the PIDL passed to Initialize should be used to construct those fully qualified PIDLs.

See Also

IPersistFolder, IShellExtInit, IShellFolder, ITEMIDLIST


IReconcilableObject

The IReconcilableObject interface carries out the reconciliation of a document. The briefcase reconciler is responsible for implementing this interface.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IReconcilableObject Methods	Description
GetProgressFeedbackMaxEstimate	Receives estimate of work required to complete a reconciliation.
Reconcile	Reconciles the state of an object with one or more other objects.


IReconcilableObject::GetProgressFeedbackMaxEstimate Windows NT Beta] [Now Supported on Windows NT]
IReconcilableObject::GetProgressFeedbackMaxEstimate

[Now Supported on Windows NT]

Retrieves an estimated measurement of the amount of work required to complete a reconciliation. This value corresponds to a similar value that is passed with the IReconcileInitiator::SetProgressFeedback member function during reconciliation. Reconcilers typically use this member function to estimate the work needed to reconcile an embedded document.

HRESULT IReconcilableObject::GetProgressFeedbackMaxEstimate(

IMoniker ** pulProgressMax
);
Parameters

pulProgressMax

Address of the variable that receives the work estimate value.

The work estimate value, if available, is only approximate.

Return Values

Returns the S_OK value if successful. Otherwise, the member function returns one of the following error values:

OLE_E_NOTRUNNING	The object is an OLE embedded document that must be run before this operation can be carried out. The object state is unchanged as a result of the call.
E_UNEXPECTED	Unspecified error.
See Also

IReconcilableObject


IReconcilableObject::Reconcile [Now Supported on Windows NT]
IReconcilableObject::Reconcile

[Now Supported on Windows NT]

Reconciles the state of an object with one or more other objects. The reconciliation updates the internal state of the object by merging the states of all objects to form a combined state.

HRESULT IReconcilableObject::Reconcile(

IreconcileInitiator *pInitiator,
DWORD dwFlags,
HWND hwndOwner,
HWND hwndProgressFeedback,
ULONG ulcInput,
IMoniker **rgpmkOtherInput,
LONG *plOutIndex,
IStorage *pstgNewResidues,
void *pvReserved
);
Parameters

pInitiator

Address of the IReconcileInitiator interface for the initiator of the reconciliation process. This parameter must not be NULL.

dwFlags

Control flags for the reconciliation. This parameter may be zero or a combination of these values:

RECONCILEF_FEEDBACKWINDOWVALID
	hwndProgressFeedback is valid.
RECONCILEF_MAYBOTHERUSER
	The briefcase reconciler can prompt for user interaction if it is needed. Without this value, user interaction is not permitted. hwndOwner is valid.
RECONCILEF_NORESIDUESOK
	The briefcase reconciler can ignore requests for residues and carry out reconciliation. Reconcilers that do not support residues should check for this value whenever an initiator requests residues. Without this value, a reconciler that does not support residues must immediately return REC_E_NORESIDUES.
RECONCILEF_OMITSELFRESIDUE
	The briefcase reconciler can discard any residue associated with this object. Initiators typically use this value for reconciliations that loop from generation to generation.
RECONCILEF_ONLYYOUWERECHANGED
	The Reconcile member function is being called to propagate changes in the changed object to other unchanged objects. This value will only be set if the HKEY_CLASSES_ROOT\CLSID\clsid_of_reconciler\SingleChangeHook key exists in the registry. If that key is not present in the registry, the initiator carries out reconciliation by making the other unchanged objects binary identical copies of the changed object. The rgpmkOtherInput monikers identify the other objects. This value will only be set in dwFlags if RECONCILEF_YOUMAYDOTHEUPDATES is also set. If the briefcase reconciler completes the updates itself successfully, REC_S_IDIDTHEUPDATES should be returned and the variable pointed to by plOutIndex should be set to  − 1L. Note that S_OK should not be returned on success if this value is set in dwFlags. The initiator will not save the source object’s storage if Reconcile returns REC_S_IDIDTHEUPDATES. If the reconciler wishes to fall back to the initiator’s bit copy implementation, it may return S_FALSE.
RECONCILEF_RESUMEDRECONCILIATION
	The briefcase reconciler should resume reconciliation, using the partial residues provided. Without this value, the reconciler should ignore any “considered but rejected” information in any of the input versions.
RECONCILEF_YOUMAYDOTHEUPDATES
	The briefcase reconciler may do the updates itself. Without this value, the reconciler may not do the updates itself. If reconciliation is completed successfully, the reconciler should return REC_S_IDIDTHEUPDATES if it did the updates itself or S_OK if it did not do the updates itself.
hwndOwner

Handle of the parent window to use for child windows that the briefcase reconciler creates. This parameter is valid only if RECONCILEF_MAYBOTHERUSER is specified in dwFlags.

hwndProgressFeedback

Handle of the progress feedback window displayed by the initiator. This parameter is valid only if RECONCILEF_FEEDBACKWINDOWVALID is specified in dwFlags. The briefcase reconciler may call the SetWindowText function using this window handle to display additional reconciliation status information to the user.

ulcInput

Number of versions or partial residues specified in dwFlags. This parameter must not be zero.

rgpmkOtherInput

Address of an array that contains the addresses of the monikers to use to access the versions or partial residues to be reconciled.

plOutIndex

Address of the variable that receives an index value indicating whether the result of the reconciliation is identical to one of the initial versions. The variable is set to  − 1L if the reconciliation result is a combination of two or more versions. Otherwise, it is a zero-based index, with 0 indicating this object, 1 indicating the first version, 2 indicating the second version, and so on.

pstgNewResidues

Address of the IStorage interface used to store newly created residues. This parameter may be NULL to indicate that residues should not be saved.

pvReserved

Reserved; must be NULL.

Return Values

Returns one of the following success values if successful:

S_OK
	Reconciliation was completed successfully, and the changes must be propagated to the other objects.
S_FALSE
	No reconciliation actions were performed. The briefcase reconciler wishes to fall back to the initiator’s bit copy implementation. This value may only be returned if RECONCILEF_ONLYYOUWERECHANGED is set in dwFlags.
REC_S_IDIDTHEUPDATES
	Reconciliation was completed successfully, and all the objects involved (the object implementing the Reconcile member function and all the other objects described by the passed-in monikers) have been updated appropriately. The initiator does not need, therefore, to do anything further to propagate the changes. The variable pointed to by plOutIndex should be set to  − 1L if Reconcile returns this value. The initiator will not save the source object’s storage if Reconcile returns this value. This value may only be returned if RECONCILEF_YOUMAYDOTHEUPDATES was set in dwFlags.
REC_S_NOTCOMPLETE
	The briefcase reconciler completed some, but not all, of the reconciliation. It may need user interaction. The changes will not be propagated to other objects.
REC_S_NOTCOMPLETEBUTPROPAGATE
	The briefcase reconciler completed some, but not all, of the reconciliation. It may need user interaction. The changes will be propagated to the other objects.
Otherwise, the member function returns one of the following error values:

REC_E_NORESIDUES
	The briefcase reconciler does not support the generation of residues, so the request for residues is denied. The state of the object is unchanged.
REC_E_ABORTED
	The briefcase reconciler terminated reconciliation in response to a termination request from the initiator (for more information, see IReconcileInitiator::SetAbortCallback). The state of the object is unspecified.
REC_E_TOODIFFERENT
	Reconciliation cannot be carried out because the provided document versions are too dissimilar.
REC_E_INEEDTODOTHEUPDATES
	The object’s Reconcile implementation was called with RECONCILEF_YOUMAYDOTHEUPDATES clear in dwFlags; the object’s Reconcile implementation requires that value to be set in dwFlags.
OLE_E_NOTRUNNING
	The object is an OLE embedded object that must be run before this operation can be carried out. The state of the object is unchanged.
E_UNEXPECTED
	Unspecified error.
See Also

IReconcilableObject


IReconcileInitiator

The IReconcileInitiator interface provides the briefcase reconciler with the means to notify the initiator of its progress, to set a termination object, and to request a given version of a document. The initiator is responsible for implementing this interface.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IReconcileInitiator Methods	Description
SetAbortCallback	Sets the object through which the initiator can terminate a reconciliation.
SetProgressFeedback	Indicates the amount of progress in the reconciliation.


IReconcileInitiator::SetAbortCallback [Now Supported on Windows NT]
IReconcileInitiator::SetAbortCallback

[Now Supported on Windows NT]

Sets the object through which the initiator can asynchronously terminate a reconciliation. A briefcase reconciler typically sets this object for reconciliations that are lengthy or involve user interaction.

The initiator can accept or reject the object. If the initiator accepts the object, the briefcase reconciler must later remove the object by subsequently calling this function with a NULL parameter when the reconciliation is complete. Because the reconciler removes the object after completing reconciliation, there may be times when the initiator releases the object after reconciliation is complete. In such cases, the reconciler ignores the request to terminate.

If the reconciliation is terminated, the IReconcilableObject::Reconcile member function must return either the REC_E_ABORTED or REC_E_NOTCOMPLETE value.

HRESULT IReconcileInitiator::SetAbortCallback(

IUnknown *pUnkForAbort
);
Parameteres

pUnkForAbort

Address of the IUnknown interface for the object. The initiator signals a request to terminate the reconciliation by using the IUnknown::Release member function to release the object. This parameter may be NULL to direct the initiator to remove the previously specified object.

Return Values

Returns the S_OK value if successful. Otherwise, the member function returns one of the following error values:

REC_E_NOCALLBACK	The initiator does not support termination of reconciliation operations and does not hold the specified object.
E_UNEXPECTED	Unspecified error.
See Also

IReconcileInitiator


IReconcileInitiator::SetProgressFeedback Beta] Windows NT Beta] [Now Supported on Windows NT]
IReconcileInitiator::SetProgressFeedback

[Now Supported on Windows NT]

Indicates the amount of progress the briefcase reconciler has made toward completing the reconciliation. The amount is a fraction of 1 and is computed as the quotient of the ulProgress and ulProgressMax. Reconcilers should call this member function periodically during their reconciliation process.

The initiator typically uses this measure of progress to update a thermometer gauge or some other form of visual feedback for the user. The briefcase reconciler can change the value of ulProgressMax from call to call. This means successive calls to this member function do not necessarily indicate steady forward progress. Backward progress is legal, although not desirable. It is the responsibility of the initiator to determine whether backward progress should be revealed to the user.

HRESULT IReconcileInitiator::SetProgressFeedback(

ULONG ulProgress,
ULONG ulProgressMax
);
Parameters

ulProgress

Numerator of the progress fraction.

ulProgressMax

Denominator of the progress fraction.

Return Values

Returns the S_OK value if successful or the E_UNEXPECTED value if some unspecified error occurred.

See Also

IReconcileInitiator


IRichEditOle

Specifies an interface used by the client of a rich text edit control to carry out OLE-related operations. The IRichEditOle interface has the following methods:

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IRichEditOle Methods	Description
GetClientSite	Retrieves an IOleClientSite interface to use when creating a new object.
GetObjectCount	Returns the number of objects contained in a rich edit control.
GetLinkCount	Returns the number of objects in a rich edit control that are links.
GetObject	Returns information from a REOBJECT structure about an object in a rich edit control.
InsertObject	Inserts an object into a rich edit control.
ConvertObject	Converts an object to a new type.
ActivateAs	Unloads objects of the old class, telling OLE to treat those objects as objects of the new class, and reloading the objects.
SetHostNames	Sets the “host names” to be given to objects as they are inserted to a rich edit control.
SetLinkAvailable	Sets the value of the link available bit in the object’s flags.
SetDvaspect	Sets the aspect that a rich edit control uses to draw an object.
HandsOffStorage	Tells a rich edit control to release its reference to the storage interface associated with the specified object.
SaveCompleted	Tells a rich edit control that the most recent save operation has been completed, and that it should hold on to a different storage for the object.
InPlaceDeactivate	Tells a rich edit control to deactivate the currently active in-place object, if any.
ContextSensitiveHelp	Tells a rich edit control to transition into or out of context-sensitive help mode.
GetClipboardData	Retrieves a clipboard object for a range in an edit control.
ImportDataObject	Imports a clipboard object into a rich edit control, replacing the current selection.


IRichEditOle::ActivateAs

Handles OLE “Activate As” behavior by unloading all objects of the old class, telling OLE to treat those objects as objects of the new class, and reloading the objects. If objects cannot be reloaded, they are deleted.

HRESULT ActivateAs(

REFCLSID rclsid,
REFCLSID rclsidAs
);
Parameters

rclsid

Class identifier of the old class.

rclsidAs

Class identifier of the new class.

Return Values

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or an SCODE returned from OLE.

See Also

IRichEditOle


IRichEditOle::ContextSensitiveHelp

Tells a rich edit control that it should transition into or out of context sensitive help mode. A rich edit control calls the ContextSensitiveHelp method of any in place object which is currently active if a state change is occuring.

HRESULT ContextSensitiveHelp(

BOOL fEnterMode
);
Parameters

fEnterMode

TRUE if entering context sensitive help mode; otherwise, FALSE.

Return Values

Returns success status. Can use GetScode to retrieve an SCODE. Can be S_OK on success or some other value returned by OLE.

See Also

IRichEditOle


IRichEditOle::ConvertObject

Converts an object to a new type. This call does reload the object but does not force an update; the caller must do this.

HRESULT ConvertObject(

LONG iob,
REFCLSID rclsidNew,
LPCSTR lpstrUserTypeNew
);
Parameters

iob

Index of the object to convert. If this parameter is REO_IOB_SELECTION, the selected object is to be converted.

rclsidNew

Class identifier of the class to which the object is to be converted.

szUserTypeNew

User-visible type name of the class to which the object is to be converted.

Return Values

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_INVALIDARG if the index is invalid, or an SCODE returned from OLE.

See Also

IRichEditOle


IRichEditOle::GetClientSite

Retrieves an IOleClientSite interface to be used when creating a new object. All objects inserted into a rich edit control must use client site interfaces returned by this function. A client site may be used with exactly one object.

HRESULT GetClientSite(

LPOLECLIENTSITE FAR * lplpolesite
);
Parameters

lplpoleclientsite

Pointer to the pointer variable that receives the address of the IOleClientSite interface.

Return Values

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_OUTOFMEMORY if memory could not be allocated for the client site.

See Also

IRichEditOle


IRichEditOle::GetClipboardData

Retrieves a clipboard object for a range in an edit control.

HRESULT GetClipboardData(

CHARRANGE FAR * lpchrg,
DWORD reco,
LPDATAOBJECT FAR * lplpdataobj
);
Parameters

lpchrg

Pointer to the CHARRANGE structure specifying the range to create the clipboard object for.

reco

Clipboard operation flag. Can be one of these values.

RECO_COPY	Copy to the clipboard.
RECO_CUT	Cut to the clipboard.
RECO_DRAG	Drag operation (drag and drop)
RECO_DROP	Drop operation (drag and drop).
RECO_PASTE	Paste from the clipboard.
lplpdataobj

Pointer to the DATAOBJECT structure that receives the clipboard object representing the range specified in the lpchrg parameter.

Return Values

Returns success status.

See Also

CHARRANGE, IRichEditOle


IRichEditOle::GetLinkCount

Returns the number of objects in a rich edit control that are links.

LONG GetLinkCount();

Return Values

Returns the number of links.

See Also

IRichEditOle


IRichEditOle::GetObject

Returns information from a REOBJECT structure about an object in a rich edit control.

HRESULT GetObject(

LONG iob,
REOBJECT FAR * lpreobject,
DWORD dwFlags
);
Parameters

iob

Zero-based index specifying which object to return information about. If this parameter is REO_IOB_USE_CP, information about the object at the character position specified by the REOBJECT structure is returned.

lpreobject

Pointer to a REOBJECT structure that receives information about the object. The reference count of the interfaces returned in this structure has been incremented; it is the responsibility of the caller to use the Release function to decrement the count.

dwFlags

Operation flags specifying which interfaces to return in the structure. Can be a combination of these values:

REO_GETOBJ_POLEOBJ	Get OLE object interface.
REO_GETOBJ_PSTG	Get Storage interface.
REO_GETOBJ_POLESITE	Get OLE site interface.
REO_GETOBJ_NO_INTERFACES	Get no interfaces.
REO_GETOBJ_ALL_INTERFACES	Get all interfaces.
Return Values

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_INVALIDARG if no buffer for the REOBJECT structure was given, or the iob or character position is invalid.

See Also

IRichEditOle, REOBJECT


IRichEditOle::GetObjectCount

Returns the number of objects currently contained in a rich edit control.

LONG GetObjectCount();

Return Values

Returns the number of objects.

See Also

IRichEditOle


IRichEditOle::HandsOffStorage

Tells a rich edit control to release its reference to the storage interface associated with the specified object. This call does not call the object’s IPersistStorage::HandsOffStorage method, the caller must do that.

HRESULT HandsOffStorage(

LONG iob
);
Parameters

iob

Index of the object whose storage is to be released. If this parameter is REO_IOB_SELECTION, the selected object’s storage is to be released.

Return Values

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_INVALIDARG if the index is invalid.

See Also

IPersistStorage::HandsOffStorage, IRichEditOle


IRichEditOle::ImportDataObject

Imports a clipboard object into a rich edit control, replacing the current selection.

HRESULT ImportDataObject(

LPDATAOBJECT lpdataobj,
CLIPFORMAT cf,
HGLOBAL hMetaPict
);
Parameters

lpdataobj

Pointer to a DATAOBJECT structure specifying the clipboard object to import.

cf

Clipboard format to use or zero to use the best available format.

hMetaPict

Handle to a metafile containing the icon view of an object. Used only if the DVASPECT_ICON display aspect is required by Paste Special command.

Return Values

Returns success status.

See Also

IRichEditOle


IRichEditOle::InPlaceDeactivate

Tells a rich edit control to deactivate the currently active in-place object, if any.

HRESULT InPlaceDeactivate();

Return Values

Returns success status. Can use GetScode to retrieve an SCODE. Can be S_OK on success or some other value returned by OLE. No error is returned if there is no active in-place object.

See Also

IRichEditOle


IRichEditOle::InsertObject

Inserts an object into a rich edit control.

HRESULT InsertObject(

REOBJECT FAR * lpreobject
);
Parameters

lpreobject

Pointer to a REOBJECT structure containing the object information and interfaces. The rich edit control automatically increments the reference count for the interfaces if it holds onto them, so the caller can safely release the interfaces if not needed.

Return Values

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_OUTOFMEMORY if memory could not be allocated to insert the object.

If the cp member of the REOBJECT structure is REO_CP_SELECTION, the selection is replaced with the specified object.

See Also

IRichEditOle, REOBJECT


IRichEditOle::SaveCompleted

Tells a rich edit control that the most recent save operation has been completed, and that it should hold on to a different storage for the object.

HRESULT SaveCompleted(

LONG iob,
LPSTORAGE lpstg
);
Parameters

iob

Index of the object whose storage is being specified. If this parameter is REO_IOB_SELECTION, the selected object is used.

pstg

New storage for the object. If the storage is not NULL, the rich edit control releases any storage it is currently holding for the object, and uses this new storage instead.

Return Values

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_INVALIDARG if the index is invalid.

See Also

IRichEditOle


IRichEditOle::SetDvaspect

Sets the aspect that a rich edit control uses to draw an object. This call does not change the drawing information cached in the object; this must be done by the caller. The call does cause the object to be redrawn.

HRESULT SetDvaspect(

LONG iob,
DWORD dvaspect
);
Parameters

iob

Index of the object whose aspect is to be set. If this parameter is REO_IOB_SELECTION, the aspect of the selected object is to be set.

dvaspect

Aspect to use when drawing. The values are defined by OLE.

Return Values

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_INVALIDARG if the index is invalid.

See Also

IRichEditOle


IRichEditOle::SetHostNames

Sets the “host names” to be given to objects as they are inserted to a rich edit control. The host names are used in the user interface of servers to describe the container context of opened objects.

HRESULT SetHostNames(

LPCSTR lpstrContainerApp,
LPCSTR lpstrContainerObj
);
Parameters

szContainerApp

Null-terminated name of the container application.

szContainerObj

Null-terminated name of the container document or object.

Return Values

Returns success status. Use GetScode to retrieve an scode. Can be S_OK on success or E_OUTOFMEMORY if memory could not be allocated to remember the strings.

See Also

IRichEditOle


IRichEditOle::SetLinkAvailable

Sets the value of the link available bit in the object’s flags. The link available bit defaults to TRUE. It should be set to FALSE if any errors occur on the link which would indicate problems connecting to the linked object or application. When those problems are repaired, the bit should be set to TRUE again.

HRESULT SetLinkAvailable(

LONG iob,
BOOL fAvailable
);
Parameters

iob

Index of object whose bit is to be set. If this parameter is REO_IOB_SELECTION, the bit on the selected object is to be set.

fAvailable

Value to set the bit to. Can be TRUE or FALSE.

Return Values

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_INVALIDARG if the index is invalid.

See Also

IRichEditOle


IRichEditOleCallback

Specifies an interface used by a rich text edit control to retrieve OLE-related information from its client. A rich edit control’s client is responsible for implementing this interface and assigning it to the control by using the EM_SETOLEINTERFACE message. The IRichEditOleCallback interface has the following methods:

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IRichEditOleCallback Methods	Description
GetNewStorage	Provides storage for a new object pasted from the clipboard or read in from an RTF stream.
GetInPlaceContext	Provides the application and document level interfaces and information required to support in-place activation.
ShowContainerUI	Tells the application whether to display its container user interface.
QueryInsertObject	Queries the application as to whether an object should be inserted.
DeleteObject	Notification that an object is about to be deleted from a rich edit control.
QueryAcceptData	Called on a paste or drag to determine if the data pasted/dragged should be accepted.
ContextSensitiveHelp	Tells the application that it should transition into or out of context sensitive help mode.
GetClipboardData	Allows the client to supply its own clipboard object.
GetDragDropEffect	Allows the client to specify the effects of a drop operation.
GetContextMenu	Queries the application for a context menu to use on a right mouse button down event.


IRichEditOleCallback::ContextSensitiveHelp NT Beta]
IRichEditOleCallback::ContextSensitiveHelp

Tells the application that it should transition into or out of context sensitive help mode. This member should implement the functionality described for IOleInPlaceSite::ContextSensitiveHelp (as described in the OLE documentation).

HRESULT ContextSensitiveHelp(

BOOL fEnterMode
);
Parameters

fEnterMode

TRUE if entering context sensitive help mode; otherwise, FALSE.

Return Values

Returns success status.

See Also

IRichEditOleCallback


IRichEditOleCallback::DeleteObject

Notification that an object is about to be deleted from a rich edit control. The object is not necessarily being released when this member is called.

HRESULT DeleteObject(

LPOLEOBJECT lpoleobj
);
Parameters

lpoleobj

Pointer to the OLEOBJECT structure specifying the object that is being deleted.

Return Values

No return value.

See Also

IRichEditOleCallback


IRichEditOleCallback::GetClipboardData Beta]
IRichEditOleCallback::GetClipboardData

Allows the client to supply its own clipboard object.

HRESULT GetClipboardData(

CHARRANGE FAR * lpchrg,
DWORD reco,
LPDATAOBJECT FAR * lplpdataobj
);
Parameters

lpchrg

Pointer to the CHARRANGE structure specifying the range the clipboard object is for.

reco

Clipboard operation flag. Can be one of these values.

RECO_COPY	Copy to the clipboard.
RECO_CUT	Cut to the clipboard.
RECO_DRAG	Drag operation (drag and drop)
RECO_DROP	Drop operation (drag and drop).
RECO_PASTE	Paste from the clipboard.
lplpdataobj

Pointer to the pointer variable that receives the address of the IDataObject implementation representing the range specified in the lpchrg parameter. The value of lppdataobj is ignored if an error is returned.

Return Values

Returns success status. If the SCODE of the return value is E_NOTIMPL, the rich edit control creates its own clipboard object. If the SCODE of the return value is a failure other than E_NOTIMPL the operation fails.

See Also

CHARRANGE, IDataObject, IRichEditOleCallback


IRichEditOleCallback::GetContextMenu Beta]
IRichEditOleCallback::GetContextMenu

Queries the application for a context menu to use on a right mouse down.

HRESULT GetContextMenu(

WORD seltyp,
LPOLEOBJECT lpoleobj,
CHARRANGE FAR * lpchrg,
HMENU FAR * lphmenu
);
Parameters

seltype

selection type

lpoleobj

Pointer to a OLEOBJECT structure specifying the first selected OLE object if the selection contains one or more objects NULL otherwise. The caller must use AddRef to increment the object reference count if it holds onto it.

lpchrg

Pointer to a CHARRANGE structure containing the current selection.

lphmenu

Pointer to a variable containing the handle of a context menu to use. This parameter is ignored if an error is returned. A rich edit control destroys the menu when it is finished with it so the client should not.

Return Values

Returns success status.

See Also

CHARRANGE, IRichEditOleCallback


IRichEditOleCallback::GetDragDropEffect Beta]
IRichEditOleCallback::GetDragDropEffect

Allows the client to specify the effects of a drop operation.

HRESULT GetDragDropEffect(

BOOL fDrag,
DWORD grfKeyState,
LPDWORD pdwEffect
);
Parameters

fDrag

TRUE if the query is for a IDropTarget::DragEnter or IDropTarget::DragOver FALSE if the query is for IDropTarget::Drop.

grfKeyState

Key state as defined by OLE.

pdwEffect

Pointer to the variable that contains the effect normally used by a rich edit control. On return, the variable is set to the effect to use.

Return Values

No return value.

See Also

IDropTarget::DragEnter, IDropTarget::DragOver, IDropTarget::Drop IRichEditOleCallback


IRichEditOleCallback::GetInPlaceContext Beta]
IRichEditOleCallback::GetInPlaceContext

Provides the application and document level interfaces and information required to support in-place activation.

HRESULT GetInPlaceContext(

LPOLEINPLACEFRAME FAR * lplpFrame,
LPOLEINPLACEUIWINDOW FAR * lplpDoc,
LPOLEINPLACEFRAMEINFO lpFrameInfo
);
Parameters

lplpframe

Pointer to the pointer variable that receives the address of the IOleInPlaceFrame interface that represents the frame window of the a rich edit control client. Use the AddRef method to increment the reference count the rich edit control releases the interface when it no longer needed.

lplpDoc

Pointer to the pointer variable that receives the address of the IOleInPlaceUIWindow interface that represents the document window of the rich edit control client. An interface need not be returned if the frame and document windows are the same. Use the AddRef method to increment the reference count the rich edit control releases the interface when it no longer needed.

lpFrameInfo

Pointer to the OLEINPLACEFRAMEINFO structure that receives the accelerator information.

Return Values

Returns success status.

See Also

IOleInPlaceFrame, IRichEditOleCallback, OLEINPLACEFRAMEINFO


IRichEditOleCallback::GetNewStorage Beta]
IRichEditOleCallback::GetNewStorage

Provides storage for a new object pasted from the clipboard or read in from an RTF stream.

HRESULT GetNewStorage(

LPSTORAGE FAR * lplpstg
);
Parameters

lplpstg

Address to the pointer variable that receives the address of the IStorage interface created for the new object.

Return Values

Returns success status.

This method must be implemented to allow cut/copy/paste and drag and drop of OLE objects.

See Also

IRichEditOleCallback, IStorage


IRichEditOleCallback::QueryAcceptData Beta]
IRichEditOleCallback::QueryAcceptData

Called on a paste or drag to determine if the data pasted/dragged should be accepted.

HRESULT QueryAcceptData(

LPDATAOBJECT lpdataobj,
CLIPFORMAT FAR * lpcfFormat,
DWORD reco,
BOOL fReally,
HGLOBAL hMetaPict
);
Parameters

lpdataobj

Pointer to the DATAOBJECT structure specifying the data object being pasted or dragged.

lpcfFormat

Pointer to the clipboard format that will be used for the paste or drop operation. If the value pointed to by lpcfFormat is zero, the best available format will be used. If the callback changes the value pointed to by lpcfFormat, the rich edit control only uses that format and the operation will fail if the format is not available.

reco

Clipboard operation flag. Can be one of these values.

RECO_DROP	Drop operation (drag and drop).
RECO_PASTE	Paste from the clipboard.
fReally

Nonzero if the paste or drop is actually happening, zero if this is just a query, such as for EM_CANPASTE.

hMetaPict

Handle to a metafile containing the icon view of an object if DVASPECT_ICON is being imposed on a object by Paste Special.

Return Values

Returns success status. If the SCODE of the result is a failure SCODE, the rich edit control refuses the data and terminates the operation. If the SCODE of the result is S_OK, the control checks the data itself for acceptable formats. A return of a successful SCODE other than S_OK means that the callback either checked the data itself (if fReally is FALSE) or imported the data itself (if fReally is TRUE).

If the application returns a successful result other than S_OK, a rich edit control will not check the read-only state of the edit control.

See Also

IRichEditOleCallback


IRichEditOleCallback::QueryInsertObject Beta]
IRichEditOleCallback::QueryInsertObject

Queries the application as to whether an object should be inserted. This member is called when pasting and when reading RTF.

HRESULT QueryInsertObject(

LPCLSID lpclsid,
LPSTORAGE lpstg,
LONG cp
);
Parameters

lpclsid

Class identifier of the object to be inserted.

lpstg

Storage containing the object.

cp

Character position at which the object will be inserted.

Return Values

Returns success status. If the SCODE of the result is not S_OK, the object is not inserted.

See Also

IRichEditOleCallback


IRichEditOleCallback::ShowContainerUI Beta]
IRichEditOleCallback::ShowContainerUI

Tells the application whether to display its container user interface. The rich edit control looks ahead for doubleclicks and defers the call if appropriate (as described in the OLE documentation). Applications may defer hiding adornments until an IOleInPlaceFrame::SetBorderSpace call is received.

HRESULT ShowContainerUI(

BOOL fShow
);
Parameters

fShow

Show container UI flag. TRUE to show, FALSE otherwise.

Return Values

Returns success status.

This function is called by the OnUIActivate and OnUIDeActivate methods of the IOleInPlaceSite interface.

See Also

IRichEditOleCallback, OnUIActivate, OnUIDeActivate


IShellBrowser

The IShellBrowser interface provides services for namespace extensions and is the companion to the IShellView interface implemented by namespace extensions.. It is similar to the “site” interfaces that are often found in OLE hosting scenarios, such as IOleControl and IOleControlSite. This allows the extension to communicate with the host of the namespace, providing UI elements like menus, status text, and tool bars. This interface also provides the extension with a way to access storage to save its persistent view state.

IShellBrowser derives from IOleWindow and it represents the container’s top-level window, allowing the contained views to insert their menus into the composite menu, install the composite menu into the appropriate window frame and remove the container’s menu elements from the composite menu. It sets and displays status text relevant to the in-place object. It also enables or disables the frame’s modeless dialog boxes, and translates accelerator keystrokes intended for the container’s frame.

When to Implement

You do not implement this interface directly. IShellBrowser is implemented by the Windows Explorer and by the Windows File Open Dialog.

When to Use

When implementing a namespace extension, notably IShellView, you will use the IShellBrowser implementation that is passed to use IShellBrowser::CreateViewWindow to communicate with the  Explorer.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IOleWindow Methods	Description
GetWindow	Returns a handle to one of the windows participating in in-place activation.
ContextSensitiveHelp	Determines whether context-sensitive help mode should be entered during an in-place activation session.
IShellBrowser Methods	Description
InsertMenusSB	Inserts the Explorer’s menu items to an empty menu created by the view.
SetMenuSB	Installs the composite menu in the Explorer.
RemoveMenusSB	Gives the container a chance to remove its items from a composite menu. It  perform tasks that are the opposite of InsertMenuSB.
SetStatusTextSB	Sets and displays status text in the Explorer window.
EnableModelessSB	Enables or disables modeless windows of the Explorer, such as a floating toolbar.
TranslateAcceleratorSB	Reserved for future use.
BrowseObject	Tells the Explorer to browse in another folder.
GetViewStateStream	Returns a view-specific stream that can be used to read and write the persistent data for a view.
GetControlWindow	Gets the window handle of an Explorer control.
SendControlMsg	Sends messages to Explorer controls.
QueryActiveShellView	Returns the currently activated (displayed) shellview object.
OnViewWindowActive	Informs the Explorer that the view was activated.
SetToolbarItems	Adds toolbar items to the Explorer’s toolbar.


IShellBrowser::BrowseObject [Now Supported on Windows NT]
IShellBrowser::BrowseObject

[Now Supported on Windows NT]

Tells the Explorer  to browse to another folder.

HRESULT BrowseObject(

LPCITEMIDLIST pidl,	// Address of item identifier list
UINT *wFlags	// Specifies the folder to be browsed
);
Parameters

pidl

Address of an ITEMIDLIST (item identifier list) structure that specifies an object’s location. This value is dependent on the wFlags parameter.

wFlags

Flag specifying the folder to be browsed. It can be zero or more of the following values. The first three specify whether another window is to be created.

SBSP_SAMEBROWSER	Browse to another folder with the same Explorer window.
SBSP_NEWBROWSER	Creates another window for the specified folder.
SBSP_DEFBROWSER	The default behavior is to respect the view option (the user setting to create new windows or to browse in place). In most cases, callers should use this flag.
The following flags specify either the open, explore, or default mode. These values are ignored if SBSP_SAMEBROWSER or (SBSP_DEFBROWSER && (single window browser || explorer)).

SBSP_OPENMODE	Use a normal folder window.
SBSP_EXPLOREMODE	Use an Explorer window.
SBSP_DEFMODE	Us the same one as the current window.
The following flags specify the pidl parameter’s category:

SBSP_ABSOLUTE	An absolute pidl (relative from the desktop).
SBSP_RELATIVE	A relative pidl (relative from the current folder).
SBSP_PARENT	Browse the parent folder (ignores the pidl).
Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

Views can use this method to force the Explorer to browse to a specific place in the namespace. Typically, these are folders contained in the view.

See Also

IShellBrowser


IShellBrowser::EnableModelessSB [Now Supported on Windows NT]
IShellBrowser::EnableModelessSB

[Now Supported on Windows NT]

Tells the Explorer to enable or disable its modeless dialog boxes.

HRESULT EnableModelessSB(

BOOL fEnable	// Enable or disable modeless dialog
);
Parameters

fEnable

Specifies whether the modeless dialog boxes are to be enabled by specifying TRUE or disabled by specifying FALSE.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

This method is similar to IOleInPlaceFrame::EnableModeless. Although the current version of the Explorer does not have any modeless dialog boxes, the view should call this member appropriately when it wants to disable or enable modeless dialog boxes associated with the Explorer window.

See Also

IShellBrowser


IShellBrowser::GetControlWindow [Now Supported on Windows NT]
IShellBrowser::GetControlWindow

[Now Supported on Windows NT]

GetControlWindow can be called by the shell view object to get the window handle of an Explorer control, either for a toolbar or for a status window.

HRESULT GetControlWindow(

UINT id,	// Identifier of an Explorer control
HWND *lphwnd	// Handle of the control’s window
);
Parameters

id

Specifies the identifer for either a toolbar (FCW_TOOLBAR), for a status window (FCW_STATUS), or for a tree (FCW_TREE).

lphwnd

Pointer to the window handle of the Explorer control.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

GetControlWindow is used so views can directly manipulate the toolbar and status bar. FCW_TREE should be used only to sense whether the tree is present; that is, whether the folder is in Explorer mode or folder mode.

Notes to Callers

This is used to manipulate and test the state of these windows. Do not send messages directly to these controls; instead, use IShellBrowser::SendControlMsg. Be prepared for the returns of this call to be NULL. Future versions of the Explorer may not include a toolbar, status bar, or tree window.

Notes to Implementors

IShellBrowser::GetControlWindow returns the hwnds of these controls if they exist in your implementation.

See Also

IShellBrowser


IShellBrowser::GetViewStateStream [Now Supported on Windows NT]
IShellBrowser::GetViewStateStream

[Now Supported on Windows NT]

The browser provides an IStream interface as the storage for view-specific state information.

HRESULT GetViewStateStream(

DWORD grfMode,	// Specifies the mode
LPSTREAM *ppStrm	// Points to the LPSTREAM variable
);
Parameters

grfMode

Specifiies the read-write access. This may be set to STGM_READ, STGM_WRITE, or STGM_READWRITE. For more information about these values see the STGM enumeration.

ppStrm

Pointer to the address of  the LPSTREAM variable to be filled.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

Used to save and restore the persistent state for a view. For example, the icon positions the column widths, and the current scroll position.

Notes to Callers:

Use GetViewStateStream when the view is being created to read in the saved view state and when the view is being closed to save any changes to the view state. Typically, the view calls this member with STGM_READ when creating a view window and with STGM_WRITE when the SaveViewState method of its IShellView interface is called.

Notes to Implementors:

Each shell view should have its own view stream. The Explorer implements an MRU (most recently used) list of view streams that are stored on a per-user basis in the registry.

See Also

IShellBrowser


IShellBrowser::InsertMenusSB [Now Supported on Windows NT]
IShellBrowser::InsertMenusSB

[Now Supported on Windows NT]

Allows the Explorer to insert its menu groups into the composite menu being displayed while viewing or using an extended namespace.

HRESULT InsertMenusSB(

HMENU hmenuShared,	// A handle to an empty menu
LPOLEMENUGROUPWIDTHS lpMenuWidths	// Points to OLEMENUGROUPWIDTHS
);
Parameters

hmenuShared

Specifies a handle to an empty menu.

lpMenuWidths

Points to an OLEMENUGROUPWIDTHS array of 6 LONG values. The container fills in elements 0,2, and 4 to reflect the number of menu elements it provided in the File, View, and Window menu groups.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

This method is similar to IOleInPlaceFrame::InsertMenus. The Explorer puts File and Edit pulldown menus in the File menu group, View and Tools in the Container menu group, and Help in the Window menu group. Each pulldown menu will have a unique identifier, FCIDM_MENU_FILE/EDIT/VIEW/TOOLS/HELP. The view is allowed to insert menu items into those submenus by their identifiers, which is different from OLE’s in-place activation mechanism. The command IDs for menus that the view inserts into either the Explorer’s submenus or its own submenus, must be between FCIDM_SHVIEWFIRST and FCIDM_SHVIEWLAST.

Notes to Callers

This method is called by namespace extensions when they are first being activated so they can insert their menus into the frame-level user interface.

The object application asks the container to add its menus to the menu specified in hmenuShared and to set the group counts in the OLEMENUGROUPWIDTHS array pointed to by lpMenuWidths. The object application then adds its own menus and counts. Objects can call IOleInPlaceFrame::InsertMenus as many times as necessary to build up the composite menus. The container should use the initial menu handle associated with the composite menu for all items in the drop-down menus.

Notes to Implementors

For IShellBrowser implementations, the menu identifiers must be in the range of FCIDM_BROWSERFIRST to FCIDM_BROWSERLAST.

See Also

IShellBrowser


IShellBrowser::OnViewWindowActive [Now Supported on Windows NT]
IShellBrowser::OnViewWindowActive

[Now Supported on Windows NT]

The shell view window calls OnViewWindowActive when the view window or one of its child windows gets the focus.

HRESULT OnViewWindowActive(

IShellView *ppshv	// Points to the view’s address
);
Parameters

ppshv

Points to the address of the currently active shell view object.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

The view must pass its IShellView implementation to this routine, although the current version of the Explorer does not use this parameter.

Notes to Callers

The shell view window must call this member before calling IShellBrowser::InsertMenusSB because it will insert a different set of menu items depending on whether the view has the focus.

Notes to Implementors

Lets you know that the view is getting the focus, for example, on a mouse click.

See Also

IShellBrowser


IShellBrowser::QueryActiveShellView [Now Supported on Windows NT]
IShellBrowser::QueryActiveShellView

[Now Supported on Windows NT]

QueryActiveShellView returns the currently activated (displayed) shell view object.

HRESULT QueryActiveShellView(

IShellView **ppshv	// Points to the view’s address
);
Parameters

ppshv

Points to the address of the currently active shell view object.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Notes to callers

QueryActiveShellView is useful because it is possible for an IShellBrowser to host several shell views simultaneously. However, the current version of the Explorer does not do this.

See Also

IShellBrowser


IShellBrowser::RemoveMenusSB [Now Supported on Windows NT]
IShellBrowser::RemoveMenusSB

[Now Supported on Windows NT]

Gives the container a chance to remove its menu elements from the in-place composite menu and free all associated resources.

HRESULT RemoveMenusSB(

HMENU hmenuShared	// Handle to in-place composite menu
);
Parameters

hmenuShared

Specifies a handle to the in-place composite menu that was constructed by calls to IShellBrowser::InsertMenusSB and the Win32 InsertMenu function.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

This method is similar to IOleInPlaceFrame::RemoveMenus.

The object should always give the container a chance to remove its menu elements from the composite menu before deactivating the shared user interface.

Notes to Callers

Called by the object application while it is being UI-deactivated to remove its menus.

See Also

IShellBrowser


IShellBrowser::SendControlMsg [Now Supported on Windows NT]
IShellBrowser::SendControlMsg

[Now Supported on Windows NT]

SendControlMsg can be called by the shell view object to send control messages to an Explorer control, either for a toobar or for a status bar window.

HRESULT SendControlMsg(

UINT id,	// Identifies a control
UINT uMsg,	// Specifies the message to be sent
WPARAM wParam,	// Depends on uMsg
LPARAM lParam,	// Depends on uMsg
LRESULT *pref	// Points to the SendMessage return value
);
Parameters

id

Specifies the identifer for either a toolbar (FCW_TOOLBAR) or for a status bar window (FCW_STATUS).

uMsg

Specifies the message to be sent to the control.

wParam

This value depends on the message specified in the uMsg parameter.

lParam

This value depends on the message specified in the uMsg parameter.

pret

Pointer to the return value of the SendMessage function.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

Refer to the commctrl.h header file to find the messages that can be sent to the toolbar or status bar control.

Notes to Callers

Use of this call requires diligent attention because leaving either the status bar or toolbar in an inappropriate state will affect the performance of the Explorer.

Notes to Implementors

If your Explorer does not have these controls you can return E_NOTIMPL.

See Also

IShellBrowser


IShellBrowser::SetMenuSB [Now Supported on Windows NT]
IShellBrowser::SetMenuSB

[Now Supported on Windows NT]

Installs the composite menu in the view window. Similar to IOleInPlaceFrame::SetMenu.

RESULT SetMenuSB(

HMENU hmenuShared,	// A handle to the composite menu
HOLEMENU holemenuReserved	// Reserved for future use
);
Parameters

hmenuShared

Specifiies a handle to the composite menu constructed by calls to IShellBrowser::InsertMenusSB and the Win32 InsertMenu function.

holemenuReserved

Reserved for future use.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

This method is similar to IOleInPlaceFrame::SetMenu. However, the Explorer performs menu dispatch based on the menu item ID.

The availability of specific menu items depends on whether the view has the focus. Accordingly, it is necessary to call IShellBrowser::OnViewWindowActive whenever the view window (or one of it’s child windows) has the focus.

Notes to Callers

The object calls IShellBrowser::SetMenuSB to ask the container to install the composite menu structure set up by calls to IShellBrowser::InsertMenusSB.

Notes to Implementers

A container’s implementation of this method should call the Windows SetMenu function.

See Also

IShellBrowser


IShellBrowser::SetStatusTextSB [Now Supported on Windows NT]
IShellBrowser::SetStatusTextSB

[Now Supported on Windows NT]

Sets and displays status text about the in-place object in the container’s frame-window status line.

HRESULT SetStatusTextSB(

LPCOLESTR lpszStatusText	// Address of string with the message
);
Parameters

lpszStatusText

Points to a null-terminated character string containing the message to display.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

It is also possible to send messages directly to the status window by using SendControlMsg.

Notes to Callers

Use this method to set the contents of the status bar.

See Also

IShellBrowser


IShellBrowser::SetToolbarItems [Now Supported on Windows NT]
IShellBrowser::SetToolbarItems

[Now Supported on Windows NT]

The SetToolbarItems method can be called by the view to add toolbar items to the Explorer’s toolbar.

HRESULT SetToolbarItems(

LPTBBUTTON lpButtons,	// Points to an array of items
UINT nButtons,	// Number of buttons in the array
UINT uFlags	// Specifies button location
);
Parameters

lpButtons

Points to an array of toolbar items.

nButtons

Number of buttons in the lpButtons array.

uFlags

Flags specifying where the toolbar buttons should go.

FCT_ADDTOEND	Add at the right side of the toolbar.
FCT_CONFIGABLE	Not implemented.
FCT_MERGE	Merge the toolbar items instead of replacing all of the buttons with those provided by the view. This is the recommended choice.
Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

This is the way toolbars are merged into the Explorer’s toolbar.

Notes to Callers

See the Common Controls TOOLBAR control for the definition of TBBUTTON.

See Also

IShellBrowser


IShellBrowser::TranslateAcceleratorSB Beta] [Now Supported on Windows NT]
IShellBrowser::TranslateAcceleratorSB

[Now Supported on Windows NT]

This method is not used in the Explorer at this time.

HRESULT TranslateAcceleratorSB(

LPMSG lpmsg,	// Points to an MSG structure
WORD wID	// Contains the command identifier value
);
Parameters

lpmsg

Points to an MSG structure containing the keystroke message.

wID

Contains the command identifier value corresponding to the keystroke in the container-provided accelerator table. Containers should use this value instead of translating again.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

This method is similar to IOleInPlaceFrame::TranslateAccelerator but is not used.

See Also

IShellBrowser


IShellExecuteHook

Extends the behavior of ShellExecute or ShellExecuteEx. Typically implemented by subsystems that expose the names of objects that users might type into the Start.Run... dialog.

When to Implement

You should implement IShellExecuteHook when you have named objects that users would expect to be able to run in the Start.Run... dialog.

When to Use

You do not use this interface directly. It is generally used by the ShellExecuteEx code.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IShellExecuteHook	Description
Execute	Fill in this field.


IShellExecuteHook::Execute [Now Supported on Windows NT]
IShellExecuteHook::Execute

[Now Supported on Windows NT]

Provides a hook with an opportunity to intercept a command and perform an alternate action.

HRESULT Execute(

LPSHELLEXECUTEINFO pei	// Points to a SHELLEXECUTEINFO struct.
);
Parameters

pei

Pointer to a SHELLEXECUTEINFO structure. This structure is discussed further under ShellExecuteEx.

Return Values

Returns NOERROR if the hook is implemented in the executable or S_FALSE if it is not. It is an OLE-defined error value otherwise.

Remarks

Execute provides the hook the chance to pick off a command to be executed and perform some other action.

See Also

IShellExecuteHook, IShellExtInit, ITEMIDLIST


IShellExtInit

The IShellExtInit interface is used to initialize shell extensions for property sheets, context menus, and drag-and-drop handlers (extensions that add items to context menus during non-default drag-and-drop operations).

When to Implement

Implement IShellExtInit when you are writing a handler based on IContextMenu or IShellPropSheetExt.

Note that shell extensions based on other interfaces do not use this method of initialization

When to Use

You don’t use this interface directly. It is called by the shell to initialize the handler.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IShellExtInit Method	Description
Initialize	Initializes the shell extension.


IShellExtInit::Initialize [Now Supported on Windows NT]
IShellExtInit::Initialize

[Now Supported on Windows NT]

Initializes a property sheet extension, context menu extension, or drag and drop handler.

HRESULT Initialize(

LPCITEMIDLIST pidlFolder,	// Points to an ITEMIDLIST structure
LPDATAOBJECT lpdobj,	// Points to an IDataObject interface
HKEY hkeyProgID	// Registry key for the file object or folder type
);
Parameters

pidlFolder

Pointer to an ITEMIDLIST (item identifier list) structure that uniquely identifies a folder. For property sheet extensions, this parameter is NULL. For context menu extensions, it is the IDList for the folder that cotains the item whose context menu is being displayed. For non-default drag-and-drop menu extensions, this parameter must specify the target folder.

lpdobj

Pointer to an IDataObject interface object that can be used to retrieve the objects being acted upon.

hkeyProgID

Registry key for the file object or folder type.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

The meanings of some parameters depend on the extension type. For drag and drop handlers, the item identifier list specifies the destination folder (the drop target), the IDataObject interface identifies the items being dropped, and the registry key specifies the file class of the destination folder.

For context menu extensions, the item identifier list specifies the folder that contains the selected file objects, the IDataObject interface identifies the selected file objects, and the registry key specifies the file class of the file object that has the focus.

Notes to Implementors

This is the first method that the shell calls after it creates an instance of a property sheet extension, context menu extension, or drag and drop handler.

See Also

IShellExtInit, ITEMIDLIST


IShellFolder

The IShellFolder interface is used to manage folders.

When to Implement

Implement IShellFolder for objects that extend the shell’s namespace. For example, if you create a separate name space that requires a rooted Explorer; or if you install a new name space directly within the hierarchy of the system name space.Only you know anything about the contents of your name space so you are responsible for implementing everything needed to access your data.

When to Use

Use IShellFolder when you need to display or operate on the contents of the shell’s namespace. Objects that support IShellFolder are usually created by other shell folder objects, with the root object (the Desktop shell folder) being returned from the SHGetDesktopFolder function.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IShellFolder Methods	Description
ParseDisplayName	Translates a display name into an item identifier list.
EnumObjects	Enumerates the objects in a folder.
BindToObject	Retrieves the IShellFolder interface for the specified subfolder.
BindToStorage	Returns the storage instance of a subfolder.
CompareIDs	Compares two item identifier lists and returns the result.
CreateViewObject	Creates a view object of the folder itself.
GetAttributesOf	Retrieves the attributes of the specified file object or subfolder.
GetUIObjectOf	Creates an OLE interface that can be used to carry out operations on a file object or subfolder.
GetDisplayNameOf	Retreives the display name of a file object or subfolder.
SetNameOf	Sets the display name of the specified file object or subfolder and changes its identifier accordingly.


IShellFolder::BindToObject [Now Supported on Windows NT]
IShellFolder::BindToObject

[Now Supported on Windows NT]

Creates an IShellFolder object for a subfolder.

HRESULT BindToObject(

LPCITEMIDLIST pidl,	// Pointer to an ITEMIDLIST
LPBC pbcReserved,	// Reserved—specify NULL
REFIID riid,	// Interface to return
LPVOID *ppvOut	// Address that receives interface pointer
);
Parameters

pidl

Pointer to an ITEMIDLIST structure that identifies the subfolder relative to its parent folder.

pbcReserved

Reserved. Callers should specify NULL for this parameter; callees should ignore it.

riid

Identifier of the interface to return. This parameter must point to the IID_IShellFolder interface identifier.

ppvOut

Address that receives the interface pointer. If an error occurs, a NULL pointer is returned in this address.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

Use BindToObject to access the COM interface to the sub-folder or sub-object.

See Also

IShellFolder, ITEMIDLIST, SHGetDeskTopFolder


IShellFolder::BindToStorage [Now Supported on Windows NT]
IShellFolder::BindToStorage

[Now Supported on Windows NT]

Reserved for a future use. This method should return E_NOTIMPL.


IShellFolder::CompareIDs [Now Supported on Windows NT]
IShellFolder::CompareIDs

[Now Supported on Windows NT]

Determines the relative ordering of two file objects or folders, given their item identifier lists.

HRESULT CompareIDs(

LPARAM lParam,	// Type of comparison to perform
LPCITEMIDLIST pidl1,	// Address of ITEMIDLIST structure
LPCITEMIDLIST pidl2	// Address of ITEMIDLIST structure
);
Parameters

lParam

Value specifying the type of comparison to perform. The calling application should always specify zero, indicating that the two items should be sorted by name.

pidl1 and pidl2

Addresses of two ITEMIDLIST structures that uniquely identify the items to be compared. Both item identifier lists are relative to the parent folder.

Return Values

Returns a handle to a result code. If this method is successful, the CODE field of the status code (SCODE) has the following meaning:

CODE field	Meaning
Less than zero	The first item should precede the second (pidl1 < pidl2).
Greater than zero	The first item should follow the second (pidl1 > pidl2)
Zero	The two items are the same (pidl1 = pidl2).
Remarks

Passing 0 as the lParam indicates sort by name. 0x00000001-0x7fffffff are for folder specific sorting rules. 0x80000000-0xfffffff are used the system.

See Also

IShellFolder, ITEMIDLIST


IShellFolder::CreateViewObject [Now Supported on Windows NT]
IShellFolder::CreateViewObject

[Now Supported on Windows NT]

Creates a view object of a folder.

HRESULT CreateViewObject(

HWND hwndOwner,	// Handle of owner window
REFIID riid,	// Interface identifier
LPVOID *ppvOut	// Reserved
);
Parameters

hwndOwner

Specifies the owner window for any modal dialog boxes or message boxes within this call. It may be different from hwndParen passed in a call to IShellView::CreateViewWindow.

Handle of the owner window from which to create the view object.

riid

Identifier of the interface to return.

ppvOut

Specifies the address that receives a pointer to the view object.

Return Values

Returns NOERROR if successful or an OLE defined error value otherwiise.

Remarks

It is important to remember that the COM object created by CreateViewObject must be a different object than the shell folder object. The Explorer may call CreateViewObject more than once to create more than one view object and expects them to behave as independent objects. A new view object must be created for each call.

See Also

IShellFolder


IShellFolder::EnumObjects [Now Supported on Windows NT]
IShellFolder::EnumObjects

[Now Supported on Windows NT]

Determines the contents of a folder by creating an item enumeration object (a set of item identifiers) that can be retrieved using the IEnumIDList interface.

HRESULT EnumObjects(

HWND hwndOwner,	// Handle of owner window
DWORD grfFlags,	// ems to include in enumeration
LPENUMIDLIST *ppenumIDList	// Pointer to IEnumIDList
);
Parameters

hwndOwner

Handle of the owner window that the client should specify if it displays a dialog box or message box.

grfFlags

Flags determining which items to iclude in the enumeration. For a list of possible values, see the description of the SHCONTF type.

ppenumIDList

Address that receives a pointer to the IEnumIDList interface created by this method. If an error occurs, a NULL pointer is returned in this address.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

The calling application must free the returned IEnumIDList object by calling its Release method.

This method is similar to the method defined by OLE.

See Also

IEnumIDList, IOleContainer::EnumObjects, IShellFolder, SHGetDeskTopFolder


IShellFolder::GetAttributesOf [Now Supported on Windows NT]
IShellFolder::GetAttributesOf

[Now Supported on Windows NT]

Retrieves the attributes of one or more file objects or subfolders.

HRESULT GetAttributesOf(

UINT cidl,	// Number of file objects
LPCITEMIDLIST *apidl,	// Pointer to array of pointers to ITEMIDLIST structures
ULONG *rgfInOut	// Address of value containing attributes of the file objects
);
Parameters

cidl

Number of file objects to get the attributes of.

apidl

Pointer to an array of pointers to ITEMIDLIST structures, each of which uniquely identifies a file object relative to the parent folder. Each ITEMIDLIST structure must contain exactly one SHITEMID structure followed by a terminating zero.

rgfInOut

Address of a ULONG value that specifies the common (logically AND’ed) attributes of specified file objects.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

The following tables list the attribute flags that may be returned by this method. File object attributes include capability flags, display attributes, contents flags, and miscellaneous attributes.

A file object’s capability flags may include zero or more of the following values:

SFGAO_CANCOPY	The specified file objects or folders can be copied (same value as the DROPEFFECT_COPY flag).
SFGAO_CANDELETE	The specified file objects or folders can be deleted.
SFGAO_CANLINK	It is possible to create shortcuts for the specified file objects or folders (same value as the DROPEFFECT_LINK flag).
SFGAO_CANMOVE	The specified file objects or folders can be moved (same value as the DROPEFFECT_MOVE flag).
SFGAO_CANRENAME	The specified file objects or folders can be renamed.
SFGAO_CAPABILITYMASK	Mask for the capability flags.
SFGAO_DROPTARGET	The specified file objects or folders are drop targets.
SFGAO_HASPROPSHEET	The specified file objects or folders have property sheets.
A file object’s display attributes may include zero or more of the following values:

SFGAO_DISPLAYATTRMASK	Mask for the display attributes.
SFGAO_GHOSTED	The specified file objects or folders should be displayed using a ghosted icon.
SFGAO_LINK	The specified file objects are shortcuts.
SFGAO_READONLY	The specified file objects or folders are read-only.
SFGAO_SHARE	The specified folders are shared.
A file object’s contents flags may include zero or more of the following values:

SFGAO_CONTENTSMASK	Mask for the contents attributes.
SFGAO_HASSUBFOLDER	The specified folders have subfolders (and are, therefore, expandable in the left pane of Windows Explorer).
A file object may have zero or more of the following miscellaneous attributes:

SFGAO_FILESYSTEM	The specified folders or file objects are part of the file system (that is, they are files, directories, or root directories).
SFGAO_FILESYSANCESTOR	The specified folders contain one or more file system folders.
SFGAO_FOLDER	The specified items are folders.
SFGAO_REMOVABLE	The specified file objects or folders are on removable media.
SFGAO_VALIDATE	Validate cached information.
Remarks

You can optimize this operation by not returning unspecified flags.

See Also

IShellFolder, ITEMIDLIST, SHITEMID


IShellFolder::GetDisplayNameOf [Now Supported on Windows NT]
IShellFolder::GetDisplayNameOf

[Now Supported on Windows NT]

Retrieves the display name for the specified file object or subfolder, returning it in a STRRET structure.

HRESULT GetDisplayNameOf(

LPCITEMIDLIST pidl,	// Pointer to an ITEMIDLIST
DWORD uFlags,	// Type of display to return
LPSTRRET lpName	// Pointer to a STRRET structure
);
Parameters

pidl

Pointer to an ITEMIDLIST structure that uniquely identifies the file object or subfolder relative to the parent folder.

uFlags

Value indicating the type of display name to return. For a list of possible values, see the description of the SHGNO enumerated type.

lpName

Pointer to a STRRET structure in which to return the display name. The string returned in this structure depends on the type of display name requested.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

If the ID contains the display name (in the local character set), it returns the offset to the name. If not, it returns a pointer to the display name string (UNICODE) allocated by the task allocator, or it fills in a buffer. The type of string returned depends on the type of display specified. Values identifying different types of display names are contained in the enumeration SHGNO.

See Also

IShellFolder, ITEMIDLIST, STRRET, SHGNO


IShellFolder::GetUIObjectOf [Now Supported on Windows NT]
IShellFolder::GetUIObjectOf

[Now Supported on Windows NT]

Creates a COM object that can be used to carry out actions on the specified file objects or folders, typically, to create context menus or carry out drag-and-drop operations.

HRESULT GetUIObjectOf(

HWND hwndOwner,	// Handle to owner window
UINT cidl,	// Number of objects specified in apidl
LPCITEMIDLIST *apidl,	// Pointer to an array of pointers to an ITEMIDLIST structure
REFIID riid,	// Interface to return
UINT *prgfInOut,	// Reserved
LPVOID *ppvOut	// Address to receive interface pointer
);
Parameters

hwndOwner

Handle of the owner window that the client should specify if it displays a dialog box or message box.

cidl

Number of file objects or subfolders specified by apidl.

apidl

Pointer to an array of pointers to ITEMIDLIST structures, each of which uniquely identifies a file object or subfolder relative to the parent folder. Each item identifier list must contain exactly one SHITEMID structure followed by a terminating zero.

riid

Specifies the type and the interface of the COM object to return. This parameter can be a pointer to the IID_IExtractIcon, IID_IContextMenu, IID_IDataObject, or IID_IDropTarget interface identifier.

prgfInOut

Reserved.

ppvOut

Address that receives the interface pointer. If an error occurs, a NULL pointer is returned in this address.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

GetUIObjectOf creates a UI object to be used for specified objects. Either IID_IDataObject (transfer operations) or IID_IContextMenu (context menu operations) is passed in the riid parameter.

See Also

IShellFolder, ITEMIDLIST, SHITEMID


IShellFolder::ParseDisplayName [Now Supported on Windows NT]
IShellFolder::ParseDisplayName

[Now Supported on Windows NT]

Translates a file object or folder’s display name into an item identifier.

HRESULT ParseDisplayName(

HWND hwndOwner,	// Handle of owner window
LPBC pbcReserved,	// Reserved
LPOLESTR lpszDisplayName,	// Pointer to diplay name
ULONG *pchEaten,	// Pointer to value for parsed characters
LPITEMIDLIST *ppidl,	// Pointer to new item identifier list
ULONG *pdwAttributes	// Address receiving attributes of file object
);
Parameters

hwndOwner

Handle of the owner window that the client should specify if it displays a dialog box or message box.

pbcReserved

Reserved; this parameter is always NULL.

lpszDisplayName

Pointer to a null-terminated Unicode string specifying the display name. This parameter must be a display name for parsing — that is, a display name retrieved using the SHGDN_FORPARSING value.

pchEaten

Pointer to an unsigned long value that receives the number of characters of the display name that were parsed.

ppidl

Address that receives a pointer to the new item identifier list for the object. If an error occurs, a NULL is returned in this address.

The returned item identifier list specifies the relative path (from the parent folder) that corresponds to the specified display name. It contains only one SHITEMID structure followed by a terminating zero.

pdwAttributes

Address that receives the attributes of the file object. Can be NULL if the caller does not need attribute data.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

This method is similar to the 	IParseDisplayName::ParseDisplayName method defined by OLE.

See Also

IParseDisplayName::ParseDisplayName, IShellFolder, IShellLink, SHITEMID


IShellFolder::SetNameOf [Now Supported on Windows NT]
IShellFolder::SetNameOf

[Now Supported on Windows NT]

Changes the name of a file object or subfolder, changing its item identifier in the process.

HRESULT SetNameOf(

HWND hwndOwner,	// Handle of owner window
LPCITEMIDLIST pidl,	// Pointer to an ITEMIDLIST structure
LPCOLESTR lpszName,	// Pointer to string specifying new display name
DWORD uFlags,	// Type of name specified in lpszName
LPITEMIDLIST *ppidlOut	// Pointer to new ITEMIDLIST
);
Parameters

hwndOwner

Handle of the owner window that the client should specify if it displays a dialog box or message box.

pidl

Pointer to an ITEMIDLIST structure that uniquely identifies the file object or subfolder relative to the parent folder.

lpszName

Pointer to a null-terminated string that specifies the new display name.

uFlags

Value indicating the type of name specified by the lpszName parameter. For a list of possible values, see the description of the SHCONTF enumerated type.

ppidlOut

Address in which the method returns a pointer to the new ITEMIDLIST structure. This parameter can be NULL, and in that case, the method does not return the new ITEMIDLIST for the object.

If this parameter is not NULL, this method frees the specified ITEMIDLIST structure and allocates a new one using the task allocator. The calling application is responsible for freeing the new ITEMIDLIST structure. If an error occurs, the method returns NULL in this address.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

SetNameOf sets the display name of the specified object. If it also changes the item identifier, then it returns the new item identifier ( a pidl), which is allocated by the task allocator. Changing the display name of a file system object or folder within renames the file or directory.

See Also

IShellFolder, ITEMIDLIST


IShellIcon

The IShellIcon interface is used to obtain an icon index for an IShellFolder object. Only one instance of the interface for the folder  is required instead of an instance for each object, as is the case for IExtractIcon.

When to Implement

Implement IShellIcon as part of an IShellFolder implementation as a quick way to obtain the icon for an object in the folder.

If IShellIcon is not implemented by an IShellFolder object, IShellFolder::GetUIObjectOf(..., IID_IExtractIcon, ...) is used to get an icon for all objects.

When to Use

Use IShellIcon when getting icon indexes for items in a shell folder.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IShellIcon Methods	Description
GetIconOf	Retrieves an icon for an object in a folder.


IShellIcon::GetIconOf [Now Supported on Windows NT]
IShellIcon::GetIconOf

[Now Supported on Windows NT]

Retrieves an icon for an object inside a specific folder.

HRESULT GetIconOf(

LPCITEMIDLIST pidl,	// Points to an item identifier list
UINT flags,	// Flags specifying the display state
LPINT lpIconIndex	// Points to where the icon index is to be returned
);
Parameters

pidl

Pointer to the ITEMIDLIST (item identifier list) structure that specifies the relative location of the folder.

flags

This parameter can be zero or one of the following values:

Value	Meaning
GIL_FORSHELL	The icon is to be displayed in a shell folder.
GIL_OPENICON	The icon should be in the “open” state if both open- and closed-state images are available. If this flag is not specified the icon should be in the normal or “closed” state. This flag is typically used for folder objects.
lpIconIndex

Pointer to the location where the icon index will be returned.

Return Values

Returns NOERROR if lpIconIndex contains the  correct system imagelist index. S_FALSE is returned if an icon cannot be obtained for this object.

The following standard imagelist indexes can be returned:

Value	Meaning
0	Document (blank page, not associated)
1	Document (with data on the page)
2	Application (file extension must be .exe, .com, .bat)
3	Folder (plain)
4	Folder (open)
Remarks

If you are unable to get an icon for this object using GetIconOf, use IShellFolder::GetUIObjectOf to get an object that supports IExtractIcon::Extract.

Notes to Callers

The indexes returned are from the system image list.

Notes to Implementors

This method cannot be implemented external to the shell itself.

See Also

IShellIcon


IShellLink

Designates an interface that allows an application to create and resolve shell links.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IShellLink Methods	Description
GetArguments	Retrieves the command-line arguments associated with a shell link object.
GetDescription	Retrieves the description string for a shell link object.
GetHotkey	Retrieves the hot key for a shell link object.
GetIconLocation	Retrieves the location (path and index) of the icon for a shell link object.
GetIDList	Retrieves the list of item identifiers for a shell link object.
GetPath	Retrieves the path and filename of a shell link object.
GetShowCmd	Retrieves the show (SW_) command for a shell link object.
GetWorkingDirectory	Retrieves the name of the working directory for a shell link object.
Resolve	Resolves a shell link by searching for the shell link object and updating the shell link path and its list of identifiers (if necessary).
SetArguments	Sets the command-line arguments associated with a shell link object.
SetDescription	Sets the description string for a shell link object.
SetHotkey	Sets the hot key for a shell link object.
SetIconLocation	Sets the location (path and index) of the icon for a shell link object.
SetIDList	Sets the list of item identifiers for a shell link object.
SetPath	Sets the path and filename of a shell link object.
SetRelativePath	Sets the relative path for a shell link object.
SetShowCmd	Sets the show (SW_) command for a shell link object.
SetWorkingDirectory	Sets the name of the working directory for a shell link object.


IShellLink::GetArguments [Now Supported on Windows NT]
IShellLink::GetArguments

[Now Supported on Windows NT]

Retrieves the command-line arguments associated with a shell link object.

HRESULT STDMETHODCALLTYPE GetArguments(

ISHELLLINK FAR *pShlLnk,
LPSTR pszArgs,
int cchMaxPath
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszArgs

Pointer to a buffer that receives the command-line arguments.

cchMaxPath

Maximum number of characters to copy to the buffer pointed to by pszArgs.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::GetDescription [Now Supported on Windows NT]
IShellLink::GetDescription

[Now Supported on Windows NT]

Retrieves the description string for a shell link object.

RESULT STDMETHODCALLTYPE GetDescription(

ISHELLLINK FAR *pShlLnk,
LPSTR pszName,
int cchMaxName
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszName

Pointer to a buffer that receives the description string.

cchMaxName

Maximum number of characters to copy to the buffer pointed to by pszName.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::GetHotkey [Now Supported on Windows NT]
IShellLink::GetHotkey

[Now Supported on Windows NT]

Retrieves the hot key for a shell link object.

HRESULT STDMETHODCALLTYPE GetHotkey(

ISHELLLINK FAR *pShlLnk,
WORD *pwHotkey
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pwHotkey

Pointer to the hot key. The virtual-key code is in the low-order byte, and the modifier flags are in the high-order byte. The modifier flags can be a combination of the following values:

HOTKEYF_ALT	ALT key
HOTKEYF_CONTROL	CTRL key
HOTKEYF_EXT	Extended key
HOTKEYF_SHIFT	SHIFT key
Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::GetIconLocation [Now Supported on Windows NT]
IShellLink::GetIconLocation

[Now Supported on Windows NT]

Retrieves the location (path and index) of the icon for a shell link object.

HRESULT STDMETHODCALLTYPE GetIconLocation(

ISHELLLINK FAR *pShlLnk,
LPSTR pszIconPath,
int cchIconPath,
int *piIcon
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszIconPath

Pointer to a buffer that receives the path of the file containing the icon.

cchIconPath

Maximum number of characters to copy to the buffer pointed to by pszIconPath.

piIcon

Pointer to a value that receives the index of the icon.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::GetIDList [Now Supported on Windows NT]
IShellLink::GetIDList

[Now Supported on Windows NT]

Retrieves the list of item identifiers for a shell link object.

HRESULT STDMETHODCALLTYPE GetIDList(

ISHELLLINK FAR *pShlLnk,
LPITEMIDLIST *ppidl
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

ppidl

Pointer to a pointer to a list of item identifiers.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::GetPath [Now Supported on Windows NT]
IShellLink::GetPath

[Now Supported on Windows NT]

Retrieves the path and filename of a shell link object.

HRESULT STDMETHODCALLTYPE GetPath(

IShellLink FAR *pShlLnk,
LPSTR pszFile,
int cchMaxPath,
WIN32_FIND_DATA *pfd,
DWORD fFlags
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszFile

Pointer to a buffer that receives the path and filename of the shell link object.

cchMaxPath

Maximum number of bytes to copy to the buffer pointed to by pszFile.

pfd

Pointer to a WIN32_FIND_DATA structure that contains information about the shell link object.

fFlags

Flags that specify the type of path information to retrieve. This parameter can be a combination of the following values:

SLGP_SHORTPATH	Retrieves the standard short (8.3) filename.
SLGP_UNCPRIORITY	Retrieves the Universal Naming Convention (UNC) path name of the file.
Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink, WIN32_FIND_DATA


IShellLink::GetShowCmd [Now Supported on Windows NT]
IShellLink::GetShowCmd

[Now Supported on Windows NT]

Retrieves the show command for a shell link object.

HRESULT STDMETHODCALLTYPE GetShowCmd(

ISHELLLINK FAR *pShlLnk,
int *piShowCmd
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

piShowCmd

Pointer to the show command. For a list of show commands, see the description of the ShowWindow function.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink, ShowWindow


IShellLink::GetWorkingDirectory [Now Supported on Windows NT]
IShellLink::GetWorkingDirectory

[Now Supported on Windows NT]

Retrieves the name of the working directory for a shell link object.

HRESULT STDMETHODCALLTYPE GetWorkingDirectory(

ISHELLLINK FAR *pShlLnk,
LPSTR pszDir,
int cchMaxPath
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszDir

Pointer to a buffer that receives the name of the working directory.

cchMaxPath

Maximum number of characters to copy to the buffer pointed to by pszDir. The name of the working directory is truncated if it is longer than the maximum specified by this parameter.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::Resolve [Now Supported on Windows NT]
IShellLink::Resolve

[Now Supported on Windows NT]

Resolves a shell link. The system searches for the shell link object and updates the shell link path and its list of identifiers (if necessary).

HRESULT STDMETHODCALLTYPE Resolve(

ISHELLLINK FAR *pShlLnk,
HWND hwnd,
DWORD fFlags
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

hwnd

Handle of a window that the shell uses as the parent window for a dialog box. The shell displays the dialog box if it needs to prompt the user for more information while resolving a shell link.

fFlags

Action flags. This parameter can be a combination of the following values:

SLR_ANY_MATCH	Resolves the link, displaying a dialog box if the system needs information from the user.
SLR_NO_UI	Prevents the shell from displaying a dialog box if it cannot resolve the shell link. When this flag is specified, the high-order word of fFlags specifies a timeout duration, in milliseconds. The function returns if the link cannot be resolved within the timeout duration. If the high-order word is set to zero, the timeout duration defaults to 3000 milliseconds (3 seconds).
SLR_UPDATE	Directs the shell to update the path to the link and the list of identifiers if the link object has been changed. If this value is used, it is not necessary to call the IPersistFile::IsDirty method to determine whether the link object has changed.
Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

When this method is called, the system retrieves the path associated with the current link object and searches for the object in that path. If the system finds the object, it resolves the link. If the system cannot find the object, it looks in the same directory for an object with the same file creation time and attributes, but with a different name. This type of search resolves a link to an object that has been renamed.

If the system still cannot find the link object, it searches the subdirectories of the current directory. It does a recursive search of the directory tree looking for a match with either the same name or creation time. If it does not find a match after that, the shell displays a dialog box prompting the user for a location. An application can suppress the dialog box by specifying the SLR_NO_UI value in a call to this method.

See Also

IShellLink


IShellLink::SetArguments [Now Supported on Windows NT]
IShellLink::SetArguments

[Now Supported on Windows NT]

Sets the command-line arguments for a shell link object.

HRESULT STDMETHODCALLTYPE SetArguments(

ISHELLLINK FAR *pShlLnk,
LPCSTR pszArgs
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszArgs

Pointer to a buffer that contains the new command-line arguments.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

This method is useful when creating a link to an application that takes special flags as arguments, such as a compiler.

See Also

IShellLink


IShellLink::SetDescription [Now Supported on Windows NT]
IShellLink::SetDescription

[Now Supported on Windows NT]

Sets the description for a shell link object. The description can be any application-defined string.

HRESULT STDMETHODCALLTYPE SetDescription(

ISHELLLINK FAR *pShlLnk,
LPCSTR pszName
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszName

Pointer to a buffer containing the new description string.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::SetHotkey [Now Supported on Windows NT]
IShellLink::SetHotkey

[Now Supported on Windows NT]

Sets a hot key for a shell link object.

HRESULT STDMETHODCALLTYPE SetHotkey(

ISHELLLINK FAR *pShlLnk,
WORD wHotkey
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

wHotkey

Hot key. The virtual-key code is in the low-order byte, and the modifier flags are in the high-order byte. The modifier flags can be a combination of the values specified in the description of the IShellLink::GetHotkey method.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Setting a hot key allows the user to activate the object by pressing a particular combination of keys.

See Also

IShellLink, IShellLink::GetHotkey


IShellLink::SetIconLocation [Now Supported on Windows NT]
IShellLink::SetIconLocation

[Now Supported on Windows NT]

Sets the location (path and index) of the icon for a shell link object.

HRESULT STDMETHODCALLTYPE SetIconLocation(

ISHELLLINK FAR *pShlLnk,
LPCSTR pszIconPath,
int iIcon
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszIconPath

Pointer to a buffer that contains the path of the file containing the icon.

iIcon

Index of the icon.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::SetIDList [Now Supported on Windows NT]
IShellLink::SetIDList

[Now Supported on Windows NT]

Sets the list of item identifiers for a shell link object.

HRESULT STDMETHODCALLTYPE SetIDList(

ISHELLLINK FAR *pShlLnk,
LPCITEMIDLIST pidl
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pidl

Pointer to a list of item identifiers.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

This method is useful when an application needs to set a shell link to an object that is not a file, such as a Control Panel application, a printer, or another computer.

See Also

IShellLink


IShellLink::SetPath [Now Supported on Windows NT]
IShellLink::SetPath

[Now Supported on Windows NT]

Sets the path and filename of a shell link object.

HRESULT STDMETHODCALLTYPE SetPath(

ISHELLLINK FAR *pShlLnk,
LPCSTR pszFile
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszFile

Pointer to a buffer that contains the new path.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::SetRelativePath [Now Supported on Windows NT]
IShellLink::SetRelativePath

[Now Supported on Windows NT]

Sets the relative path to the shell link object.

HRESULT STDMETHODCALLTYPE SetRelativePath(

ISHELLLINK FAR *pShlLnk,
LPCSTR pszPathRel,
LPCITEMIDLIST pidlRel
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszPathRel

Pointer to a buffer that contains the new relative path.

pidlRel

Pointer to a list of item identifiers that identify the object.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::SetShowCmd [Now Supported on Windows NT]
IShellLink::SetShowCmd

[Now Supported on Windows NT]

Sets the show command for a shell link object. The show command sets the initial show state of the window.

HRESULT STDMETHODCALLTYPE SetShowCmd(

ISHELLLINK FAR *pShlLnk,
int iShowCmd
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

iShowCmd

Show command. For a list of the show commands, see the description of the ShowWindow function.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink, ShowWindow


IShellLink::SetWorkingDirectory [Now Supported on Windows NT]
IShellLink::SetWorkingDirectory

[Now Supported on Windows NT]

Sets the name of the working directory for a shell link object.

HRESULT STDMETHODCALLTYPE SetWorkingDirectory(

ISHELLLINK FAR *pShlLnk,
LPCSTR pszDir
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszDir

Pointer to a buffer that contains the name of the new working directory.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

The working directory must be set only if the object requires it to be set. For example, if an application creates a shell link to a Microsoft Word document that uses a template that resides in a different directory, the application would use this method to set the working directory.

See Also

IShellLink


IShellPropSheetExt

Designates an interface that allows a property sheet handler to add or replace pages in the property sheet for a file object.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IShellPropSheetExt Methods	Description
AddPages	Adds one or more pages to a property sheet for a file object.
ReplacePage	Replaces a page in a property sheet for a control panel object.


IShellPropSheetExt::AddPages [Now Supported on Windows NT]
IShellPropSheetExt::AddPages

[Now Supported on Windows NT]

Adds one or more pages to a property sheet that the shell displays for a file object. When it is about to display the property sheet, the shell calls the AddPages method of each property sheet handler registered to the file type.

HRESULT STDMETHODCALLTYPE AddPages(

IShellPropSheetExt FAR *pProp,
LPFNADDPROPSHEETPAGE lpfnAddPage,
LPARAM lParam
);
Parameters

pProp

Pointer to the IShellPropSheetExt interface. In C++, this parameter is implicit.

lpfnAddPage

Pointer to a function that the property sheet handler calls to add a page to the property sheet. The function takes a property sheet handle returned by the CreatePropertySheetPage function and the lParam parameter passed to the AddPages method.

lParam

Parameter to pass to the function specified by lpfnAddPage.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

For each page it needs to add to a property sheet, a property sheet handler fills a PROPSHEETPAGE structure, calls CreatePropertySheetPage, and then calls the function specified by lpfnAddPage.

See Also

CreatePropertySheetPage, IShellPropSheetExt, PROPSHEETPAGE


IShellPropSheetExt::ReplacePage [Now Supported on Windows NT]
IShellPropSheetExt::ReplacePage

[Now Supported on Windows NT]

Replaces a page in a property sheet for a control panel object.

HRESULT STDMETHODCALLTYPE ReplacePage(

IShellPropSheetExt FAR *pProp,
UINT uPageID,
LPFNADDPROPSHEETPAGE lpfnReplacePage,
LPARAM lParam
);
Parameters

pProp

Pointer to the IShellPropSheetExt interface. In C++, this parameter is implicit.

uPageID

Identifier of the page to replace. The values for this parameter for control panels can be found in the CPLEXT.H header file.

lpfnReplacePage

Pointer to a function that the property sheet handler calls to replace a page to the property sheet. The function takes a property sheet handle returned by the CreatePropertySheetPage function and the lParam parameter passed to the ReplacePage method.

lParam

Parameter to pass to the function specified by lpfnReplacePage.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

To replace a page, a property sheet handler fills a PROPSHEETPAGE structure, calls CreatePropertySheetPage, and then calls the function specified by lpfnReplacePage.

See Also

CreatePropertySheetPage, IShellPropSheetExt, PROPSHEETPAGE


IShellView

The IShellView interface is implemented to present a view in the Windows Explorer or folder windows. The object that exposes IShellView is created by a call to IShellFolder::CreateViewObject. This provides the channel of communication between a view object and the Explorer’s outermost frame window. The communication involves the translation of messages, the state of the frame window (activated or deactivated), and the state of the document window (Activated or deactivated), the merging of menus, and toolbar items.

When to Implement

This interface is implemented by namespace extensions that want to represent themselves in the Explorer’s namespace. This object is created by the IShellFolder object that hosts the view.

When to Use

These methods are used by the shell view’s Explorer window to manipulate objects while they are active.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IOleWindow Methods	Description
GetWindow	Returns a handle to one of the windows participating in in-place activation.
ContextSensitiveHelp	Determines whether context-sensitive help mode should be entered during an in-place activation session.
IShellView Methods	Description
TranslateAccelerator	Translates accelerator key strokes when a namespace extension’s view has the focus.
EnableModeless	Enables or disables modeless dialog boxes. Not in use by the Explorer at this time.
EnableModelessSV	Not in use at this time.
UIActivate	Passes a value when the state of the view window is changed by events not caused by the shell view itself.
Refresh	Responds to user input to refresh the display.
CreateViewWindow	Creates the view window.
DestroyViewWindow	Destroys the view window.
GetCurrentInfo	Returns the folder settings.
AddPropertySheetPages	Allows the view to add pages to the options property sheet.
SaveViewState	Saves the current view state into a stream obtained by the view by calling IShellBrowser::GetViewStateStream.
SelectItem	Changes the state of items within the shell view window.
GetItemObject	Allows callers to get an object that represents something in the view.


IShellView::AddPropertySheetPages [Now Supported on Windows NT]
IShellView::AddPropertySheetPages

[Now Supported on Windows NT]

Provides a way for the view to add pages to the Options property sheet.

HRESULT AddPropertySheetPages(

DWORD dwReserved,	// Reserved.
LPFNADDPROPSHEETPAGE lpfn,	// Points to the callback that adds pages
LPARAM lparam	// lparam to be passed to the callback function
);
Parameters

dwReserved

This parameter is reserved for future use.

lpfn

Pointer to the callback function used to add the pages.

lparam

Specifies the lParam that must be passed to the callback in the lpfn parameter.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

Allows the view to add property pages to the View.Options... property page.

Notes to implementors

The Explorer calls this method when it is opening the View.Options... property sheet. Views can add pages by creating them and calling the callback function with the page handles.

See Also

IShellView, CreatePropertySheetPage


IShellView::CreateViewWindow [Now Supported on Windows NT]
IShellView::CreateViewWindow

[Now Supported on Windows NT]

CreateViewWindow creates a view window. This can be either the right pane of the Explorer or the client window of a folder window.

RESULT CreateViewWindow(

ISHELLLINK *lpPrevView,	// Points to previous view
LPFOLDERSETTINGS lpfs,	// Points to FOLDERSETTINGS
IShellBrowser *psb,	// Points to shell browser
RECT *prcView,	// Points to the rect the defines the view size
HWND *phWnd	// Points to the returned window handle
);
Parameters

lpPrevView

Pointer to the view window being exited. Views can use it to talk to a previous view of the same implementation. This can be used to optimize browsing between like views. This pointer may be NULL.

lpfs

Pointer to a FOLDERSETTINGS structure. The view should use this when creating its view.

psb

Pointer to the current instance of IShellBrowser. The view should AddRef this pointer and keep it to allow communication with the Explorer window.

prcView

Specifies the dimensions in client coordinates in which the view should create itself.

phWnd

Pointer to the handle of the window being created.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

This is the call that creates the view.

Notes to Callers

Call this method when the view needs to be created.

Notes to Implementors

Create your view window and restore any persistent state by calling IShellBrowser::GetViewStateStream.

See Also

IShellView, IShellBrowser::GetViewStateStream


IShellView::DestroyViewWindow [Now Supported on Windows NT]
IShellView::DestroyViewWindow

[Now Supported on Windows NT]

DestroyViewWindow destroys the view window.

HRESULT DestroyViewWindow(

Parameters

This method has no parameters.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

The Explorer calls this method when a folder window or the Explorer is being closed.

Notes to Implementors

Clean up all state that represents the view, including the window and any other associated resources.

See Also

IShellView


IShellView::EnableModeless [Now Supported on Windows NT]
IShellView::EnableModeless

[Now Supported on Windows NT]

If the view owns any modeless dialog boxes, it should disable all of them when this member is called with FALSE and keep them disabled until it is called again with TRUE.

HRESULT EnableModeless(

LPFOLDERSETTINGS fEnable	// Boolean flags
);
Parameters

fEnable

Specifies TRUE to enable modeless dialog box windows, FALSE to disable them.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellView


IShellView::EnableModelessSV

Currently not in use.


IShellView::GetCurrentInfo [Now Supported on Windows NT]
IShellView::GetCurrentInfo

[Now Supported on Windows NT]

Obtains information about the current folder settings.

HRESULT GetCurrentInfo(

LPFOLDERSETTINGS lpfs	// Points to the folder settings
);
Parameters

lpfs

Pointer to a FOLDERSETTINGS structure to receive the settings.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

The Explorer uses GetCurrentInfo to query the view for standard settings.

Notes to Callers

Used to get the current view settings of the view.

Notes to Implementors

Return as many of the settings as apply. This is intended to let browsing from view to view maintain the same basic settings. For example, if the user sets Details view, going from one folder to the other in Explorer mode, it should remain in Details view.

See Also

IShellView


IShellView::GetItemObject [Now Supported on Windows NT]
IShellView::GetItemObject

[Now Supported on Windows NT]

Returns an interface that refers to data presented in the view.

HRESULT GetItemObject(

UINT uItem,	// Specifies background object constants
REFIIDriid,	// Identifies the interface to return
LPVOID *ppv	// Address that receives the interface pointer
);
Parameters

uItem

Specifies constants that refer to an aspect of the view. It can be any of the following values.

Value	Meaning
SVGIO_BACKGROUND	Refers to the background of the view. It is used with IID_IContextMenu to get a context menu for the view background.
SVGIO_SELECTION	Refers to the currently selected items. IID_IDataObject uses this constant to get a data object that represents the selected items.
SVGIO_ALLVIEW	Same as SVGIO_SELECTION but refers to all items in the view.
riid

Identifier of the interface to return.

ppv

Address that receives the interface pointer. If an error occurs, the pointer returned must be NULL.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

Used by the common dialogs to get the selected items from the view.

See Also

IShellView


IShellView::Refresh [Now Supported on Windows NT]
IShellView::Refresh

[Now Supported on Windows NT]

Refreshes the view’s contents in response to an event such as when a user hits the F5 key.

HRESULT Refresh(

Parameters

This method has no parameters.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

Tells the view to refresh its contents, revalidating any view information it has.

Notes to Callers

The Explorer calls this method when F5 is pressed on an already open view.

Notes to Implementors

Refill the view by going to any underlying storage for the contents.

See Also

IShellView


IShellView::SaveViewState [Now Supported on Windows NT]
IShellView::SaveViewState

[Now Supported on Windows NT]

Allows the shell view to store its view settings so the current state can be restored during a subsequent browsing session.

HRESULT SaveViewState(

Parameters

This method has no parameters.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

The shell view is supposed to get a view stream by calling IShellBrowser::GetViewStateStream and store the current view state in that stream.

Notes to Callers

The Explorer calls this method when it wants to save the view state for a view.

Notes to Implementors

Be sure to make the format of the data stored in the stream robust and versionable.

See Also

IShellBrowser::GetViewStateStream, IShellView


IShellView::SelectItem [Now Supported on Windows NT]
IShellView::SelectItem

[Now Supported on Windows NT]

Changes the selection state of one or more items within the shell view window.

HRESULT SelectItem(

LPCITEMIDLIST pidlItem,	// Points to item ID list
UINT uFlags	// Specifies the selection state
);
Parameters

pidlItem

Pointer to the item ID list. If this parameter is NULL and uFlags is SVSI_DESELECTOTHERS, all items should be deselected.

uFlags

Flag specifying what type of selection to apply. This parameter can be one of the following values:

Value	Meaning
SVSI_DESELECT	Deselect the specified item.
SVSI_DESELECTOTHERS	If pidlItem is NULL, deselect all items.
SVSI_EDIT	Put the pidlItem in edit mode.
SVSI_ENSUREVISIBLE	Ensure the item is displayed on the screen.
SVSI_FOCUSED	The item should be given the focus.
SVSI_SELECT	The item should be selected.
Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

This method is used to implement functionality in the Explorer.

Notes to Implementors

SelectItem is used to implement the File Target command of the shell shortcut property sheet.

See Also

IShellView


IShellView::TranslateAccelerator [Now Supported on Windows NT]
IShellView::TranslateAccelerator

[Now Supported on Windows NT]

Processes menu accelerator-key messages from the container’s message queue.

HRESULT TranslateAccelerator(

LPMSG lpmsg	// Points to a message that may need translating.
);
Parameters

lpmsg

Pointer to the message that might need to be translated.

Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Returning S_OK indicates that the message was translated and should not be translated or dispatched by the Explorer.

Remarks

TranslateAccelerator is called by the Explorer to let the view translate its accelerators.

Notes to Callers

The Explorer calls this method before any other translation if the view has the focus. If the view does not have the focus (if the tree has it, for example) this is called after the Explorer translates its own accelerators.

Notes to Implementors

By default, the view should return S_FALSE so that the Explorer can either do it’s own accelerator translation or normal menu dispatching. The view should return S_OK only if it has processed the message as the accelerator and does not want the Explorer to process it further.

See Also

IShellView


IShellView::UIActivate [Now Supported on Windows NT]
IShellView::UIActivate

[Now Supported on Windows NT]

Called by the Explorer whenever the activation state of the view window is changed by a certain event that is not caused by the shell view itself. For example, if the TAB key is pressed when the tree has the focus, the view should be given the focus.

HRESULT UIActivate(

UINT uState	// activation state flag
);
Parameters

uState

Flag specifying the activation state of the window. This parameter can be one of the following values:

Value	Meaning
SVUIA_ACTIVATE_FOCUS	The Explorer has just created the view window with the input focus. This means the shell view should be able to set menu items appropriate for the focused state.
SVUIA_ACTIVATE_NOFOCUS	The shell view is either losing the input focus or it has just been created without the input focus. The shell view should be able to set menu items appropriate for the nonfocused state. This means no selection-specific items should be added.
SVUIA_DEACTIVATE	The Explorer is about to destroy the shell view window. The shell view should remove all extended UIs, typically merged menu and modeless popup windows.
Return Values

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

To remerge menu items, the shell view typically hooks the WM_SETFOCUS message and calls IShellBrowser::OnViewWindowActivated before remerging. The shell view should not hook the WM_KILLFOCUS message  to remerge menu items.

Notes to Callers

Call this method to inform the view of activation state change.

Notes to Implementors

Use this method to track activation state and change any behavior, as appropriate.

See Also

IShellView


ABM_ACTIVATE

Notifies the system that an appbar has been activated. An appbar should call this message in response to the WM_ACTIVATE message.

SHAppBarMessage(ABM_ACTIVATE, pabd);

Parameters

pabd

Pointer to an APPBARDATA structure that identifies the appbar to activate. You must specify the cbSize and hWnd members when sending this message; all other members are ignored.

Return Values

Always returns TRUE.

Remarks

This message is ignored if the hWnd member of the structure pointed to by pabd identifies an autohide appbar. The system automatically sets the Z order for an autohide appbar.

See Also

APPBARDATA


ABM_GETAUTOHIDEBAR

Retrieves the handle of the autohide appbar associated with an edge of the screen.

hwndAutoHide = (HWND) SHAppBarMessage(ABM_GETAUTOHIDEBAR, pabd);

Parameters

pabd

Pointer to an APPBARDATA structure that specifies the screen edge. You must specify the cbSize, hWnd, and uEdge members when sending this message; all other members are ignored.

Return Values

Returns the handle of the autohide appbar. The return value is NULL if an error occurs or if no autohide appbar is associated with the given edge.

See Also

APPBARDATA


ABM_GETSTATE

Retrieves the autohide and always-on-top states of the Windows taskbar.

fuState = (UINT) SHAppBarMessage(ABM_GETSTATE, pabd);

Parameters

pabd

Pointer to an APPBARDATA structure. You must specify the cbSize and hWnd members when sending this message; all other members are ignored.

Return Values

Returns zero if the taskbar is not in the autohide or always-on-top state. Otherwise, the return value is one or both of the following values:

ABS_ALWAYSONTOP	The taskbar is in the always-on-top state.
ABS_AUTOHIDE	The taskbar is in the autohide state.
See Also

APPBARDATA


ABM_GETTASKBARPOS

Retrieves the bounding rectangle of the Windows taskbar.

fResult = (BOOL) SHAppBarMessage(ABM_GETTASKBARPOS, pabd);

Parameters

pabd

Pointer to an APPBARDATA structure whose rc member receives the bounding rectangle, in screen coordinates, of the taskbar. You must specify the cbSize and hWnd when sending this message; all other members are ignored.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

APPBARDATA


ABM_NEW

Registers a new appbar and specifies the message identifier that the system should use to send notification messages to the appbar. An appbar should send this message before sending any other appbar messages.

fRegistered = (BOOL) SHAppBarMessage(ABM_NEW, pabd);

Parameters

pabd

Pointer to an APPBARDATA structure that contains the new appbar’s window handle and message identifier. You must specify the cbSize, hWnd, and uCallbackMessage members when sending this message; all other members are ignored.

Return Values

Returns TRUE if successful or FALSE if an error occurs or the appbar is already registered.

See Also

APPBARDATA


ABM_QUERYPOS

Requests a size and screen position for an appbar. The message proposes a screen edge and a bounding rectangle for the appbar. The system adjusts the bounding rectangle so that the appbar does not interfere with the Windows taskbar or any other appbars. An appbar should send this message before sending the ABM_SETPOS message.

SHAppBarMessage(ABM_QUERYPOS, pabd);

Parameters

pabd

Pointer to an APPBARDATA structure. The uEdge member specifies a screen edge, and the rc member contains the proposed bounding rectangle. When the SHAppBarMessage function returns, rc contains the approved bounding rectangle. You must specify the cbSize, hWnd, uEdge, and rc members when sending this message; all other members are ignored.

Return Values

Always returns TRUE.

See Also

APPBARDATA


ABM_REMOVE

Unregisters an appbar, removing it from the system’s internal list. The system no longer sends notification messages to the appbar nor prevents other applications from using the screen area occupied by the appbar.

SHAppBarMessage(ABM_REMOVE, pabd);

Parameters

pabd

Pointer to an APPBARDATA structure that contains the handle of the appbar to unregister. You must specify the cbSize and hWnd members when sending this message; all other members are ignored.

Return Values

Always returns TRUE.

This message causes the system to send the ABN_POSCHANGED notification message to all appbars.

See Also

APPBARDATA


ABM_SETAUTOHIDEBAR

Registers or unregisters an autohide appbar for an edge of the screen. The system allows only one autohide appbar for each edge on a first come, first served basis.

fSuccess = (BOOL) SHAppBarMessage(ABM_SETAUTOHIDEBAR, pabd);

Parameters

pabd

Pointer to an APPBARDATA structure. The uEdge member specifies the screen edge. The lParam parameter is set to TRUE to register the appbar or FALSE to unregister it. You must specify the cbSize, hWnd, uEdge, and lParam members when sending this message; all other members are ignored.

Return Values

Returns TRUE if successful or FALSE if an error occurs or an autohide appbar is already registered for the given edge.

See Also

APPBARDATA


ABM_SETPOS

Sets the size and screen position of an appbar. The message specifies a screen edge to and the bounding rectangle for the appbar. The system may adjust the bounding rectangle so that the appbar does not interfere with the Windows taskbar or any other appbars.

SHAppBarMessage(ABM_SETPOS, pabd);

Parameters

pabd

Pointer to an APPBARDATA structure. The uEdge member specifies a screen edge, and the rc member contains the bounding rectangle. When the SHAppBarMessage function returns, rc contains the approved bounding rectangle. You must specify the cbSize, hWnd, uEdge, and rc members when sending this message; all other members are ignored.

Return Values

Always returns TRUE.

This message causes the system to send the ABN_POSCHANGED notification message to all appbars.

See Also

APPBARDATA


ABM_WINDOWPOSCHANGED

Notifies the system when an appbar’s position has changed. An appbar should call this message in response to the WM_WINDOWPOSCHANGED message.

SHAppBarMessage(ABM_WINDOWPOSCHANGED, pabd);

Parameters

pabd

Pointer to an APPBARDATA structure that identifies the appbar to activate. You must specify the cbSize and hWnd members when sending this message; all other members are ignored.

Return Values

Always returns TRUE.

Remarks

This message is ignored if the hWnd member of the structure pointed to by pabd identifies an autohide appbar.

See Also

APPBARDATA


ABN_FULLSCREENAPP

Notifies an appbar when a full-screen application is opening or closing. When a full-screen application is opening, an appbar must drop to the bottom of the Z order. When it is closing, the appbar should restore its Z order position. This notification is sent in the form of an application-defined message that is set by the ABM_NEW message.

ABN_FULLSCREENAPP

fOpen = (BOOL) lParam;

Parameters

fOpen

Flag specifying whether a full screen application is opening or closing. This parameter is TRUE if opening or FALSE if closing.

Return Values

No return value.


ABN_POSCHANGED

Notifies an appbar when an event has occurred that may effect the appbar’s size and position. Events include changes in the taskbar’s size, position, and visibility state, as well as the addition, removal, or resizing of another appbar on the same side of the screen.

Return Values

No return value.

Remarks

An appbar should respond to this notification message by sending the ABM_QUERYPOS and ABM_SETPOS messages. If its position has changed, the appbar should call the MoveWindow function to move itself to the new position.

See Also

MoveWindow


ABN_STATECHANGE

Notifies an appbar that the taskbar’s autohide or always-on-top state has changed — that is, the user has checked or unchecked the “Always on top” or “Auto hide” check box on the taskbar’s property sheet. An appbar can use this notification message to set its state to conform to that of the taskbar, if desired.

ABN_STATECHANGE

Return Values

No return value.


ABN_WINDOWARRANGE

Notifies an appbar that the user has selected the Cascade, Tile Horizontally, or Tile Vertically command from the taskbar’s context menu.

ABN_WINDOWARRANGE

fBeginning = (BOOL) lParam;

Parameters

fBeginning

Flag specifying whether the cascade or tile operation is beginning. This parameter is TRUE if the operation is beginning and the windows have not yet been moved. It is FALSE if the operation has completed.

Return Values

No return value.

Remarks

The system sends this notification message twice — first with lParam set to TRUE and then with lParam set to FALSE. The first notification is sent before the windows are cascaded or tiled, and the second is sent after the cascade or tile operation has occurred.


ACM_OPEN

The ACM_OPEN message opens an AVI clip and displays its first frame in an animation control. You can send this message explicitly or by using the Animate_Open macro.

ACM_OPEN

wParam = 0;

lParam = (LPARAM) (LPSTR) lpszName;

Parameters

lpszName

Pointer to a buffer that contains the path of the .AVI file or the name of an AVI resource. Alternatively, this parameter can consist of the AVI resource identifier in the low-order word and zero in the high-order word. To create this value, use the MAKEINTRESOURCE macro. The control loads an AVI resource from the module specified by the instance handle passed to the CreateWindow function, the Animate_Create macro, or the dialog box creation function that created the control.

The AVI file or resource specified by lpszName must not contain audio. It must be silent.

If this parameter is NULL, the system closes the .AVI file that was previously opened for the specified animation control, if any.

Return Values

If the operation succeeds, the return value is a nonzero value.

If the operation fails, the return value is zero.

Remarks

You can only open silent AVI clips. AVI files or resources containing audio will not load. ACM_OPEN and Animate_Open fail if lpszSource specifies a non-silent AVI clip.

You can use Animate_Close to close an .AVI file or AVI resource that was previously opened for the specified animation control.

The Animate_Open and Animate_Close macros are defined in COMMCTRL.H.

See Also

Animate_Close, Animate_Open, MAKEINTRESOURCE


ACM_PLAY

The ACM_PLAY message plays an AVI clip in an animation control. The control plays the clip in the background while the thread continues executing. You can send this message explicitly or by using the Animate_Play macro.

ACM_PLAY

wParam = (WPARAM) (UINT) cRepeat;

lParam = (LPARAM) MAKELONG(wFrom, wTo);

Parameters

cRepeat

Number of times to replay the AVI clip. A value of  − 1 means replay the clip indefinitely.

wFrom

Zero-based index of the frame where playing begins. The value must be less than 65,536. A value of zero means begin with the first frame in the AVI clip.

wTo

Zero-based index of the frame where playing ends. The value must be less than 65,536. A value of  − 1 means end with the last frame in the AVI clip.

Return Values

If the operation succeeds, the return value is a nonzero value.

If the operation fails, the return value is zero.

Remarks

You can use Animate_Seek to direct the animation control to display a particular frame of the AVI clip.

The Animate_Play and Animate_Seek macros are defined in COMMCTRL.H.

See Also

Animate_Play, Animate_Seek


ACM_STOP

The ACM_STOP message stops playing an AVI clip in an animation control. You can send this message explicitly or by using the Animate_Stop macro.

ACM_STOP

wParam = 0;

lParam = 0;

Return Values

If the operation succeeds, the return value is a nonzero value.

If the operation fails, the return value is zero.

See Also

Animate_Stop


ACN_START

The ACN_START notification message notifies an animation control’s parent window that the associated AVI clip has started playing. This notification message is sent in the form of a WM_COMMAND message.

ACN_START

Return Values

No return value.

See Also

WM_COMMAND


ACN_STOP

The ACN_STOP notification message notifies an animation control’s parent window that the associated AVI clip has stopped playing. This notification message is sent in the form of a WM_COMMAND message.

ACN_STOP

Return Values

No return value.

See Also

WM_COMMAND


BM_CLICK

An application sends a BM_CLICK message to simulate the user clicking a button. This message causes the button to receive a WM_LBUTTONDOWN and a WM_LBUTTONUP message, and the button’s parent window to receive a BN_CLICKED notification message.

BM_CLICK

wParam = 0;     // not used; must be zero

lParam = 0;     // not used; must be zero

Parameters

This message has no parameters.

Return Values

This message does not return a value.

See Also

BN_CLICKED, WM_LBUTTONDOWN, WM_LBUTTONUP


BM_GETCHECK

An application sends a BM_GETCHECK message to retrieve the check state of a radio button or check box.

BM_GETCHECK

wParam = 0;     // not used; must be zero

lParam = 0;     // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value from a button created with the BS_AUTOCHECKBOX, BS_AUTORADIOBUTTON, BS_AUTO3STATE, BS_CHECKBOX, BS_RADIOBUTTON, or BS_3STATE style can be one of the following:

Value	Meaning
BST_CHECKED	Button is checked.
BST_INDETERMINATE	Button is grayed, indicating an indeterminate state (applies only if the button has the BS_3STATE or BS_AUTO3STATE style).
BST_UNCHECKED	Button is unchecked
If the button has any other style, the return value is zero.

See Also

BM_GETSTATE, BM_SETCHECK


BM_GETIMAGE

An application sends a BM_GETIMAGE message to retrieve the handle of the image (icon or bitmap) associated with the button.

BM_GETIMAGE

wParam = (WPARAM) fImageType; // image-type flag

lParam = 0;                   // not used, must be zero

Parameters

fImageType

Value of wParam. Specifies the type of image to associate with the button. This parameter can be one of the following values:

IMAGE_BITMAP
IMAGE_ICON

Return Values

The return value is the handle of the image, if any; otherwise, it is NULL.

See Also

BM_SETIMAGE


BM_GETSTATE

An application sends a BM_GETSTATE message to determine the state of a button or check box.

BM_GETSTATE

wParam = 0;     // not used; must be zero

lParam = 0;     // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value specifies the current state of the button. You can use the following bitmasks to extract information about the state:

Value	Meaning
0x0003	Specifies the check state (radio buttons and check boxes only). A value of BST_UNCHECKED indicates the button is unchecked; a value of BST_CHECKED indicates the button is checked. A radio button is checked when it contains a dot; a check box is checked when it contains an X. A value of BST_INDETERMINATE indicates the check state is indeterminate (applies only if the button has the BS_3STATE or BS_AUTO3STATE style). A three-state check box is grayed when its state is indeterminate.
BST_CHECKED	Indicates the button is checked.
BST_FOCUS	Specifies the focus state. A nonzero value indicates that the button has the keyboard focus.
BST_INDETERMINATE	Indicates the button is grayed because the state of the button is indeterminate. This value applies only if the button has the BS_3STATE or BS_AUTO3STATE style.
BST_PUSHED	Specifies the highlight state. A nonzero value indicates that the button is highlighted. A button is automatically highlighted when the user positions the cursor over it and presses and holds the left mouse button. The highlighting is removed when the user releases the mouse button.
BST_UNCHECKED	Indicates the button is unchecked. Same as the Windows NT return value of zero.
See Also

BM_GETCHECK, BM_SETSTATE


BM_SETCHECK

An application sends a BM_SETCHECK message to set the check state of a radio button or check box.

BM_SETCHECK

wParam = (WPARAM) fCheck; // check state

lParam = 0;               // not used; must be zero

Parameters

fCheck

Value of wParam. Specifies the check state. This parameter can be one of the following values:

Value	Meaning
BST_CHECKED	Sets the button state to checked.
BST_INDETERMINATE	Sets the button state to grayed, indicating an indeterminate state. Use this value only if the button has the BS_3STATE or BS_AUTO3STATE style.
BST_UNCHECKED	Sets the button state to unchecked
Return Values

This message always returns zero.

Remarks

The BM_SETCHECK message has no effect on push buttons.

See Also

BM_GETCHECK, BM_GETSTATE, BM_SETSTATE


BM_SETIMAGE

An application sends a BM_SETIMAGE message to associate a new image (icon or bitmap) with the button.

BM_SETIMAGE

wParam = (WPARAM) fImageType;       // image-type flag

lParam = (LPARAM) (HANDLE) hImage;  // handle of the image

Parameters

fImageType

Value of wParam. Specifies the type of image to associate with the button. This parameter can be one of the following values:

IMAGE_BITMAP
IMAGE_ICON

hImage

Value of lParam. Identifies the image to associate with the button.

Return Values

The return value is the handle of the image previously associated with the button, if any; otherwise, it is NULL.

See Also

BM_GETIMAGE


BM_SETSTATE

An application sends a BM_SETSTATE message to change the highlight state of a button. The highlight state indicates whether the button is highlighted as if the user had pushed it.

BM_SETSTATE

wParam = (WPARAM) fState;   // highlight state

lParam = 0;                 // not used; must be zero

Parameters

fState

Value of wParam. Specifies whether the button is to be highlighted. A value of TRUE highlights the button. A value of FALSE removes any highlighting.

Return Values

This message always returns zero.

Remarks

Highlighting only affects the appearance of a button. It has no effect on the check state of a radio button or check box.

A button is automatically highlighted when the user positions the cursor over it and presses and holds the left mouse button. The highlighting is removed when the user releases the mouse button.

See Also

BM_GETSTATE, BM_SETCHECK


BM_SETSTYLE

An application sends a BM_SETSTYLE message to change the style of a button.

BM_SETSTYLE

wParam =  (WPARAM) LOWORD(dwStyle); // style

lParam =  MAKELPARAM(fRedraw, 0);   // redraw flag

Parameters

dwStyle

Value of wParam. Specifies the button style. For an explanation of button styles, see the following Remarks section.

fRedraw

Value of the low-order word of lParam. Specifies whether the button is to be redrawn. A value of TRUE redraws the button; a value of FALSE does not redraw the button.

Return Values

This message always returns zero.

Remarks

Following are the available button styles:

Style	Meaning
BS_3STATE	Creates a button that is the same as a check box, except that the box can be grayed as well as checked or unchecked. Use the grayed state to show that the state of the check box is not determined.
BS_AUTO3STATE	Creates a button that is the same as a three-state check box, except that the box changes its state when the user selects it. The state cycles through checked, grayed, and unchecked.
BS_AUTOCHECKBOX	Creates a button that is the same as a check box, except that the check state automatically toggles between checked and unchecked each time the user selects the check box.
BS_AUTORADIOBUTTON	Creates a button that is the same as a radio button, except that when the user selects it, Windows automatically sets the button’s check state to checked and automatically sets the check state for all other buttons in the same group to unchecked.
BS_CHECKBOX	Creates a small, empty check box with text. By default, the text is displayed to the right of the check box. To display the text to the left of the check box, combine this flag with the BS_LEFTTEXT style (or with the equivalent BS_RIGHTBUTTON style).
BS_DEFPUSHBUTTON	Creates a push button that behaves like a BS_PUSHBUTTON style button, but also has a heavy black border. If the button is in a dialog box, the user can select the button by pressing the ENTER key, even when the button does not have the input focus. This style is useful for enabling the user to quickly select the most likely (default) option.
BS_GROUPBOX	Creates a rectangle in which other controls can be grouped. Any text associated with this style is displayed in the rectangle’s upper left corner.
BS_LEFTTEXT	Places text on the left side of the radio button or check box when combined with a radio button or check box style. Same as the BS_RIGHTBUTTON style.
BS_OWNERDRAW	Creates an owner-drawn button. The owner window receives a WM_MEASUREITEM message when the button is created and a WM_DRAWITEM message when a visual aspect of the button has changed. Do not combine the BS_OWNERDRAW style with any other button styles.
BS_PUSHBUTTON	Creates a push button that posts a WM_COMMAND message to the owner window when the user selects the button.
BS_RADIOBUTTON	Creates a small circle with text. By default, the text is displayed to the right of the circle. To display the text to the left of the circle, combine this flag with the BS_LEFTTEXT style (or with the equivalent BS_RIGHTBUTTON style). Use radio buttons for groups of related, but mutually exclusive choices.
BS_USERBUTTON	Obsolete, but provided for compatibility with 16-bit versions of Windows. Win32-based applications should use BS_OWNERDRAW instead.
BS_BITMAP	Specifies that the button displays a bitmap.
BS_BOTTOM	Places text at the bottom of the button rectangle.
BS_CENTER	Centers text horizontally in the button rectangle.
BS_ICON	Specifies that the button displays an icon.
BS_LEFT	Left-justifies the text in the button rectangle. However, if the button is a check box or radio button that does not have the BS_RIGHTBUTTON style, the text is left justified on the right side of the check box or radio button.
BS_MULTILINE	Wraps the button text to multiple lines if the text string is too long to fit on a single line in the button rectangle.
BS_NOTIFY	Enables a button to send BN_DBLCLK, BN_KILLFOCUS, and BN_SETFOCUS notification messages to its parent window. Note that buttons send the BN_CLICKED notification message regardless of whether it has this style.
BS_PUSHLIKE	Makes a button (such as a check box, three-state check box, or radio button) look and act like a push button. The button looks raised when it isn’t pushed or checked, and sunken when it is pushed or checked.
BS_RIGHT	Right-justifies text in the button rectangle. However, if the button is a check box or radio button that does not have the BS_RIGHTBUTTON style, the text is right justified on the right side of the check box or radio button.
BS_RIGHTBUTTON	Positions a radio button’s circle or a check box’s square on the right side of the button rectangle. Same as the BS_LEFTTEXT style.
BS_TEXT	Specifies that the button displays text.
BS_TOP	Places text at the top of the button rectangle.
BS_VCENTER	Places text in the middle (vertically) of the button rectangle.
See Also

WM_COMMAND, WM_DRAWITEM, WM_MEASUREITEM


BN_CLICKED

The BN_CLICKED notification message is sent when the user clicks a button. The parent window of the button receives this notification message through the WM_COMMAND message. Unlike the other button notification messages, this message is intended for applications written for any version of Windows.

BN_CLICKED

idButton = (int) LOWORD(wParam);    // identifier of button

hwndButton = (HWND) lParam;         // handle of button

Remarks

A disabled button does not send a BN_CLICKED notification message to its parent window.

See Also

WM_COMMAND


BN_DBLCLK

The BN_DBLCLK notification message is sent when the user double-clicks a button that has the BS_OWNERDRAW or BS_RADIOBUTTON style. The parent window of the button receives this notification message through a WM_COMMAND message.

BN_DBLCLK

idButton = (int) LOWORD(wParam);    // identifier of button

hwndButton = (HWND) lParam;         // handle of button

BN_DBLCLK is the same as the BN_DOUBLECLICKED notification message.

This notification is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

See Also

BN_CLICKED, BN_DOUBLECLICKED, WM_COMMAND


BN_DISABLE

The BN_DISABLE notification message is sent when a button is disabled. The parent window of the button receives this notification message through the WM_COMMAND message.

BN_DISABLE

This notification message is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

See Also

DRAWITEMSTRUCT, WM_COMMAND, WM_DRAWITEM


BN_DOUBLECLICKED

The BN_DOUBLECLICKED notification message is sent when the user double-clicks a button that has the BS_OWNERDRAW or BS_RADIOBUTTON style. The parent window of the button receives this notification message through the WM_COMMAND message.

BN_DOUBLECLICKED

BN_DOUBLECLICKED is the same as the BN_DBLCLK notification message.

This notification is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

See Also

BN_DBLCLK, DRAWITEMSTRUCT, WM_COMMAND, WM_DRAWITEM


BN_HILITE

The BN_HILITE notification message is sent when the user selects a button. The parent window of the button receives this notification message through the WM_COMMAND message.

BN_HILITE

This notification message is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

BN_HILITE is the same as the BN_PUSHED notification message.

See Also

BN_PUSHED, BN_UNHILITE, DRAWITEMSTRUCT, WM_COMMAND, WM_DRAWITEM


BN_KILLFOCUS

The BN_KILLFOCUS notification message is sent when a button loses the keyboard focus. The button must have the BS_NOTIFY style to send this notification message. The parent window of the button receives this notification message through the WM_COMMAND message.

BN_KILLFOCUS

See Also

BN_SETFOCUS, WM_COMMAND


BN_PAINT

The BN_PAINT notification message is sent when a button should be painted. The parent window of the button receives this notification message through the WM_COMMAND message.

BN_PAINT

This notification message is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

See Also

DRAWITEMSTRUCT, WM_COMMAND, WM_DRAWITEM


BN_PUSHED

The BN_PUSHED notification message is sent when the push state of a button is set to pushed. The parent window of the button receives this notification message through the WM_COMMAND message.

BN_PUSHED

BN_PUSHED is the same as the BN_HILITE notification message.

This notification message is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

See Also

BN_HILITE, BN_UNPUSHED, DRAWITEMSTRUCT, WM_COMMAND, WM_DRAWITEM


BN_SETFOCUS

The BN_SETFOCUS notification message is sent when a button receives the keyboard focus. The button must have the BS_NOTIFY style to send this notification message. The parent window of the button receives this notification message through the WM_COMMAND message.

BN_SETFOCUS

See Also

BN_KILLFOCUS, WM_COMMAND


BN_UNHILITE

The BN_UNHILITE notification message is sent when the highlight should be removed from a button. The parent window of the button receives this notification message through the WM_COMMAND message.

BN_HILITE

BN_UNHILITE is the same as the BN_UNPUSHED notification message.

This notification message is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

See Also

BN_HILITE, BN_UNPUSHED, DRAWITEMSTRUCT, WM_COMMAND, WM_DRAWITEM


BN_UNPUSHED

The BN_UNPUSHED notification message is sent when the push state of a button is set to unpushed. The parent window of the button receives this notification message through the WM_COMMAND message.

BN_PUSHED

BN_UNPUSHED is the same as the BN_UNHILITE notification message.

This notification message is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

See Also

BN_PUSHED, DRAWITEMSTRUCT, WM_COMMAND, WM_DRAWITEM


CB_ADDSTRING

An application sends a CB_ADDSTRING message to add a string to the list box of a combo box. If the combo box does not have the CBS_SORT style, the string is added to the end of the list. Otherwise, the string is inserted into the list, and the list is sorted.

CB_ADDSTRING

wParam = 0;                         // not used; must be zero

lParam = (LPARAM) (LPCTSTR) lpsz;    // address of string to add

Parameters

lpsz

Value of lParam. Points to the null-terminated string to be added. If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, the value of the lpsz parameter is stored as item data rather than the string it would otherwise point to. The item data can be retrieved or modified by sending the CB_GETITEMDATA or CB_SETITEMDATA message.

Return Values

The return value is the zero-based index to the string in the list box of the combo box. If an error occurs, the return value is CB_ERR. If insufficient space is available to store the new string, it is CB_ERRSPACE.

Remarks

If you create an owner-drawn combo box with the CBS_SORT style but without the CBS_HASSTRINGS style, the WM_COMPAREITEM message is sent one or more times to the owner of the combo box so the new item can be properly placed in the list.

To insert a string at a specific location within the list, use the CB_INSERTSTRING message.

See Also

CB_DIR, CB_INSERTSTRING, WM_COMPAREITEM


CB_DELETESTRING

An application sends a CB_DELETESTRING message to delete a string in the list box of a combo box.

CB_DELETESTRING

wParam = (WPARAM) index;  // item to delete

lParam = 0;               // not used; must be zero

Parameters

index

Value of wParam. Specifies the zero-based index of the string to delete.

Return Values

The return value is a count of the strings remaining in the list. If the index parameter specifies an index greater than the number of items in the list, the return value is CB_ERR.

Remarks

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, Windows sends a WM_DELETEITEM message to the owner of the combo box so the application can free any additional data associated with the item.

See Also

CB_RESETCONTENT, WM_DELETEITEM


CB_DIR

An application sends a CB_DIR message to add a list of filenames to the list box of a combo box.

CB_DIR

wParam = (WPARAM) (UINT) uAttrs;          // file attributes

lParam = (LPARAM) (LPCTSTR) lpszFileSpec; // address of filename

Parameters

uAttrs

Value of wParam. Specifies the attributes of the files to be added to the list box. It can be any combination of the following values:

Value	Meaning
DDL_ARCHIVE	Includes archived files.
DDL_DIRECTORY	Includes subdirectories. Subdirectory names are enclosed in square brackets ([ ]).
DDL_DRIVES	Includes drives. Drives are listed in the form [-x-], where x is the drive letter.
DDL_EXCLUSIVE	Includes only files with the specified attributes. By default, read-write files are listed even if DDL_READWRITE is not specified.
DDL_HIDDEN	Includes hidden files.
DDL_READONLY	Includes read-only files.
DDL_READWRITE	Includes read-write files with no additional attributes.
DDL_SYSTEM	Includes system files.
lpszFileSpec

Value of lParam. Points to the null-terminated string that specifies the filename to add to the list. If the filename contains any wildcards (for example, *.*), all files that match and have the attributes specified by the uAttrs parameter are added to the list.

Return Values

The return value is the zero-based index of the last filename added to the list. If an error occurs, the return value is CB_ERR. If insufficient space is available to store the new strings, it is CB_ERRSPACE.

See Also

CB_ADDSTRING, CB_INSERTSTRING, DlgDirList, DlgDirListComboBox


CB_FINDSTRING

An application sends a CB_FINDSTRING message to search the list box of a combo box for an item beginning with the characters in a specified string.

CB_FINDSTRING

wParam = (WPARAM) indexStart;        // item before start of search

lParam = (LPARAM) (LPCSTR) lpszFind  // prefix string address

Parameters

indexStart

Value of wParam. Specifies the zero-based index of the item preceding the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the indexStart parameter. If indexStart is −1, the entire list box is searched from the beginning.

lpszFind

Value of lParam. Points to the null-terminated string that contains the prefix to search for. The search is not case sensitive, so this string can contain any combination of uppercase and lowercase letters.

Return Values

The return value is the zero-based index of the matching item. If the search is unsuccessful, it is CB_ERR.

Remarks

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, what the CB_FINDSTRING message does depends on whether your application uses the CBS_SORT style. If you use the CBS_SORT style, WM_COMPAREITEM messages are sent to the owner of the combo box to determine which item matches the specified string. If you do not use the CBS_SORT style, the CB_FINDSTRING message searches for a list item that matches the value of the lpszFind parameter.

See Also

CB_FINDSTRINGEXACT, CB_SELECTSTRING, CB_SETCURSEL, WM_COMPAREITEM


CB_FINDSTRINGEXACT

An application sends a CB_FINDSTRINGEXACT message to find the first list box string in a combo box that matches the string specified in the lpszFind parameter.

CB_FINDSTRINGEXACT

wParam = (WPARAM) indexStart;      // item before start of search

lParam = (LPARAM)(LPCSTR)lpszFind; // address of string to search for

Parameters

indexStart

Value of wParam. Specifies the zero-based index of the item preceding the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the indexStart parameter. If indexStart is −1, the entire list box is searched from the beginning.

lpszFind

Value of lParam. Points to the null-terminated string to search for. This string can contain a complete filename, including the extension. The search is not case sensitive, so this string can contain any combination of uppercase and lowercase letters.

Return Values

The return value is the zero-based index of the matching item. If the search is unsuccessful, it is CB_ERR.

Remarks

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, what the CB_FINDSTRINGEXACT message does depends on whether your application uses the CBS_SORT style. If you use the CBS_SORT style, WM_COMPAREITEM messages are sent to the owner of the combo box to determine which item matches the specified string. If you do not use the CBS_SORT style, the CB_FINDSTRINGEXACT message searches for a list item that matches the value of the lpszFind parameter.

See Also

CB_FINDSTRING, CB_SELECTSTRING, WM_COMPAREITEM


CB_GETCOUNT

An application sends a CB_GETCOUNT message to retrieve the number of items in the list box of a combo box.

CB_GETCOUNT

wParam = 0;     // not used; must be zero

lParam = 0;     // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is the number of items in the list box. If an error occurs, it is CB_ERR.

Remarks

The index is zero-based, so the returned count is one greater than the index value of the last item.


CB_GETCURSEL

An application sends a CB_GETCURSEL message to retrieve the index of the currently selected item, if any, in the list box of a combo box.

CB_GETCURSEL

wParam = 0;     // not used; must be zero

lParam = 0;     // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is the zero-based index of the currently selected item. If no item is selected, it is CB_ERR.

See Also

CB_SELECTSTRING, CB_SETCURSEL


CB_GETDROPPEDCONTROLRECT

An application sends a CB_GETDROPPEDCONTROLRECT message to retrieve the screen coordinates of the drop-down list box of a combo box.

CB_GETDROPPEDCONTROLRECT

wParam = 0;                         // not used; must be zero

lParam = (LPARAM) (RECT FAR*) lprc; // address of RECT structure

Parameters

lprc

Value of lParam. Points to the RECT structure that is to receive the coordinates.

Return Values

This message always returns CB_OKAY.

See Also

RECT


CB_GETDROPPEDSTATE

An application sends a CB_GETDROPPEDSTATE message to determine whether the list box of a combo box is dropped down.

CB_GETDROPPEDSTATE

wParam = 0;     // not used; must be zero

lParam = 0;     // not used; must be zero

Parameters

This message has no parameters.

Return Values

If the list box is visible, the return value is TRUE; otherwise, it is FALSE.

See Also

CB_SHOWDROPDOWN


CB_GETDROPPEDWIDTH

An application sends the CB_GETDROPPEDWIDTH message to retrieve the minimum allowable width, in pixels, of the list box of a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

CB_GETDROPPEDWIDTH

wParam = 0;     // not used, must be zero

lParam = 0;     // not used, must be zero

Parameters

This message has no parameters.

Return Values

If the message succeeds, the return value is the width, in pixels.

If the message fails, the return value is CB_ERR.

Remarks

By default, the minimum allowable width of the drop-down list box is 0. The width of the list box is either the minimum allowable width or the combo box width, whichever is larger.

See Also

CB_SETDROPPEDWIDTH


CB_GETEDITSEL

An application sends a CB_GETEDITSEL message to get the starting and ending character positions of the current selection in the edit control of a combo box.

CB_GETEDITSEL

wParam = (WPARAM) (LPDWORD) lpdwStart; // receives starting position

lParam = (LPARAM) (LPDWORD) lpdwEnd;   // receives ending position

Parameters

lpdwStart

Value of wParam. Points to a 32-bit value that receives the starting position of the selection. This parameter can be set to NULL.

lpdwEnd

Value of lParam. Points to a 32-bit value that receives the ending position of the selection. This parameter can be set to NULL.

Return Values

The return value is a zero-based 32-bit value with the starting position of the selection in the low-order word and with the ending position of the first character after the last selected character in the high-order word.

See Also

CB_SETEDITSEL


CB_GETEXTENDEDUI

An application sends a CB_GETEXTENDEDUI message to determine whether a combo box has the default user interface or the extended user interface.

CB_GETEXTENDEDUI

wParam = 0;     // not used; must be zero

lParam = 0;     // not used; must be zero

Parameters

This message has no parameters.

Return Values

If the combo box has the extended user interface, the return value is TRUE; otherwise, it is FALSE.

Remarks

By default, the F4 key opens or closes the list and the DOWN ARROW changes the current selection. In a combo box with the extended user interface, the F4 key is disabled and pressing the DOWN ARROW key opens the drop-down list.

See Also

CB_SETEXTENDEDUI


CB_GETHORIZONTALEXTENT

An application sends the CB_GETHORIZONTALEXTENT message to retrieve from a combo box the width, in pixels, by which the list box can be scrolled horizontally (the scrollable width). This is applicable only if the list box has a horizontal scroll bar.

CB_GETHORIZONTALEXTENT

wParam = 0;     // not used, must be zero

lParam = 0;     // not used, must be zero

Parameters

This message has no parameters.

Return Values

The return value is the scrollable width, in pixels.

See Also

CB_SETHORIZONTALEXTENT


CB_GETITEMDATA

An application sends a CB_GETITEMDATA message to a combo box to retrieve the application-supplied 32-bit value associated with the specified item in the combo box.

CB_GETITEMDATA

wParam = (WPARAM) index;  // item index

lParam = 0;               // not used; must be zero

Parameters

index

Value of wParam. Specifies the zero-based index of the item.

Return Values

The return value is the 32-bit value associated with the item. If an error occurs, it is CB_ERR.

If the item is in an owner-drawn combo box created without the CBS_HASSTRINGS style, the return value is the 32-bit value contained in the lParam parameter of the CB_ADDSTRING or CB_INSERTSTRING message that added the item to the combo box. If the CBS_HASSTRINGS style was not used, the return value is the lParam parameter contained in a CB_SETITEMDATA message.

See Also

CB_ADDSTRING, CB_INSERTSTRING, CB_SETITEMDATA


CB_GETITEMHEIGHT

An application sends a CB_GETITEMHEIGHT message to determine the height of list items or the selection field in a combo box.

CB_GETITEMHEIGHT

wParam = (WPARAM) index;  // item index

lParam = 0;               // not used; must be zero

Parameters

index

Value of wParam. Specifies the combo box component whose height is to be retrieved.

This parameter must be −1 to retrieve the height of the selection field. It must be zero to retrieve the height of list items, unless the combo box has the CBS_OWNERDRAWVARIABLE style. In that case, the index parameter is the zero-based index of a specific list item.

Return Values

The return value is the height, in pixels, of the list items in a combo box. If the combo box has the CBS_OWNERDRAWVARIABLE style, it is is the height of the item specified by the index parameter. If index is −1, the return value is the height of the edit control (or static-text) portion of the combo box. If an error occurs, the return value is CB_ERR.

See Also

CB_SETITEMHEIGHT, WM_MEASUREITEM


CB_GETLBTEXT

An application sends a CB_GETLBTEXT message to retrieve a string from the list of a combo box.

CB_GETLBTEXT

wParam = (WPARAM) index;                // item index

lParam = (LPARAM) (LPCSTR) lpszBuffer;  // address of buffer

Parameters

index

Value of wParam. Specifies the zero-based index of the string to retrieve.

lpszBuffer

Value of lParam. Points to the buffer that receives the string. The buffer must have sufficient space for the string and a terminating null character. You can send a CB_GETLBTEXTLEN message prior to the CB_GETLBTEXT message to retrieve the length, in bytes, of the string.

Return Values

The return value is the length of the string, in bytes, excluding the terminating null character. If the index parameter does not specify a valid index, the return value is CB_ERR.

Remarks

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, the buffer pointed to by the lpszBuffer parameter of the message receives the 32-bit value associated with the item (the item data).

See Also

CB_GETLBTEXTLEN


CB_GETLBTEXTLEN

An application sends a CB_GETLBTEXTLEN message to retrieve the length, in characters, of a string in the list of a combo box.

CB_GETLBTEXTLEN

wParam = (WPARAM) index;  // item index

lParam = 0;               // not used; must be zero

Parameters

index

Value of wParam. Specifies the zero-based index of the string.

Return Values

The return value is the length of the string, in characters, excluding the terminating null character. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section.

If the index parameter does not specify a valid index, the return value is CB_ERR.

Remarks

Under certain conditions, the return value is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the operating system allowing for the possible existence of double-byte character set (DBCS) characters within the text. The return value, however, will always be at least as large as the actual length of the text; so you can always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode.

To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the GetWindowText function.

See Also

CB_GETLBTEXT, GetWindowText, LB_GETTEXT, WM_GETTEXT


CB_GETLOCALE

An application sends a CB_GETLOCALE message to retrieve the current locale of the combo box. The locale is used to determine the correct sorting order of displayed text for combo boxes with the CBS_SORT style and text added by using the CB_ADDSTRING message.

CB_GETLOCALE

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is a 32-bit value that specifies the current locale of the combo box. The high word contains the country code and the low-order word contains the language identifier.

Remarks

The language identifier is made up of a sublanguage identifier and a primary language identifier. The PRIMARYLANGID macro obtains the primary language identifier and the SUBLANGID macro obtains the sublanguage identifier.

See Also

CB_ADDSTRING, CB_SETLOCALE, PRIMARYLANGID, SUBLANGID


CB_GETTOPINDEX

An application sends the CB_GETTOPINDEX message to retrieve the zero-based index of the first visible item in the list box portion of a combo box. Initially the item with index 0 is at the top of the list box, but if the list box contents have been scrolled, another item may be at the top.

CB_GETTOPINDEX

wParam = 0;     // not used, must be zero

lParam = 0;     // not used, must be zero

Parameters

This message has no parameters.

Return Values

If the message is successful, the return value is the index of the first visible item in the list box of the combo box.

If the message fails, the return value is CB_ERR.

See Also

CB_SETTOPINDEX


CB_INITSTORAGE

An application sends the CB_INITSTORAGE message before adding a large number of items to the list box portion of a combo box. This message allocates memory for storing list box items.

CB_INITSTORAGE

wParam = (WPARAM) (int) cItems;  // number of items to add

lParam = (LPARAM) (DWORD) cb;    // amount of memory to allocate, in bytes

Parameters

cItems

Specifies the number of items to add.

cb

Specifies the amount of memory to allocate for item strings, in bytes.

Return Values

If the message is successful, the return value is the maximum number of items that the memory object can store.

If the message fails, the return value is CB_ERR.

Remarks

Windows 95: This message helps speed up the initialization of combo boxes that have a large number of items (over 100). It reserves the specified amount of memory so that subsequent CB_ADDSTRING, CB_INSERTSTRING, and CB_DIR messages take the shortest possible time. You can use estimates for the cItems and cb parameters. If you overestimate, the extra memory is allocated, if you underestimate, the normal allocation is used for items that exceed the requested amount.

Windows NT: This message is not needed on Windows NT. It does not reserve the specified amount of memory, because available memory is virtually unlimited. The return value is always the value specified in the cItems parameter.

See Also

CB_ADDSTRING, CB_DIR, CB_INSERTSTRING


CB_INSERTSTRING

An application sends a CB_INSERTSTRING message to insert a string into the list box of a combo box. Unlike the CB_ADDSTRING message, the CB_INSERTSTRING message does not cause a list with the CBS_SORT style to be sorted.

CB_INSERTSTRING

wParam = (WPARAM) index;          // item index

lParam = (LPARAM) (LPCTSTR) lpsz; // address of string to insert

Parameters

index

Value of wParam. Specifies the zero-based index of the position at which to insert the string. If this parameter is −1, the string is added to the end of the list.

lpsz

Value of lParam. Points to the null-terminated string to be inserted. If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, the value of the lpsz parameter is stored rather than the string it would otherwise point to.

Return Values

The return value is the index of the position at which the string was inserted. If an error occurs, the return value is CB_ERR. If there is insufficient space available to store the new string, it is CB_ERRSPACE.

See Also

CB_ADDSTRING, CB_DIR


CB_LIMITTEXT

An application sends a CB_LIMITTEXT message to limit the length of the text the user may type into the edit control of a combo box.

CB_LIMITTEXT

wParam = (WPARAM) cchLimit;   // maximum number of characters

lParam = 0;                   // not used; must be zero

Parameters

cchLimit

Value of wParam. Specifies the maximum number of characters the user can enter. If this parameter is zero, the text length is set to 0x7FFFFFFE characters.

Return Values

The return value is always TRUE.

Remarks

If the combo box does not have the CBS_AUTOHSCROLL style, setting the text limit to be larger than the size of the edit control has no effect.

The CB_LIMITTEXT message limits only the text the user can enter. It has no effect on any text already in the edit control when the message is sent, nor does it affect the length of the text copied to the edit control when a string in the list box is selected.

The default limit to the text a user can enter in the edit control is 30,000 characters.


CB_RESETCONTENT

An application sends a CB_RESETCONTENT message to remove all items from the list box and edit control of a combo box.

CB_RESETCONTENT

wParam = 0;     // not used; must be zero

lParam = 0;     // not used; must be zero

Parameters

This message has no parameters.

Return Values

This message always returns CB_OKAY.

Remarks

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, the owner of the combo box receives a WM_DELETEITEM message for each item in the combo box.

See Also

CB_DELETESTRING, WM_DELETEITEM


CB_SELECTSTRING

An application sends a CB_SELECTSTRING message to search the list of a combo box for an item that begins with the characters in a specified string. If a matching item is found, it is selected and copied to the edit control.

CB_SELECTSTRING

wParam = (WPARAM) indexStart;          // item before first selection

lParam = (LPARAM) (LPCSTR) lpszSelect; // address of prefix string

Parameters

indexStart

Value of wParam. Specifies the zero-based index of the item preceding the first item to be searched. When the search reaches the bottom of the list, it continues from the top of the list back to the item specified by the indexStart parameter. If indexStart is −1, the entire list is searched from the beginning.

lpszSelect

Value of lParam. Points to the null-terminated string that contains the prefix to search for. The search is not case sensitive, so this string can contain any combination of uppercase and lowercase letters.

Return Values

If the string is found, the return value is the index of the selected item. If the search is unsuccessful, the return value is CB_ERR and the current selection is not changed.

Remarks

A string is selected only if the characters from the starting point match the characters in the prefix string.

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, what the CB_SELECTSTRING message does depends on whether you use the CBS_SORT style. If the CBS_SORT style is used, the system sends WM_COMPAREITEM messages to the owner of the combo box to determine which item matches the specified string. If you do not use the CBS_SORT style, CB_SELECTSTRING attempts to match the DWORD value against the value of the lpszSelect parameter.

See Also

CB_FINDSTRING, CB_FINDSTRINGEXACT, CB_SETCURSEL, WM_COMPAREITEM


CB_SETCURSEL

An application sends a CB_SETCURSEL message to select a string in the list of a combo box. If necessary, the list scrolls the string into view. The text in the edit control of the combo box changes to reflect the new selection, and any previous selection in the list is removed.

CB_SETCURSEL

wParam = (WPARAM) index;  // item index

lParam = 0;               // not used; must be zero

Parameters

index

Value of wParam. Specifies the zero-based index of the string to select. If the index parameter is −1, any current selection in the list is removed and the edit control is cleared.

Return Values

If the message is successful, the return value is the index of the item selected. If index is greater than the number of items in the list or if index is set to −1, the return value is CB_ERR and the selection is cleared.

See Also

CB_FINDSTRING, CB_GETCURSEL, CB_SELECTSTRING


CB_SETDROPPEDWIDTH

An application sends the CB_SETDROPPEDWIDTH message to set the maximum allowable width, in pixels, of the list box of a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

CB_SETDROPPEDWIDTH

wParam = (WPARAM) wWidth,     // width of list box, in pixels

lParam = 0,                   // not used, must be zero

Parameters

wWidth

Specifies the width of the list box, in pixels.

Return Values

If the message is successful, The return value is the new width of the list box.

If the message fails, the return value is CB_ERR.

Remarks

By default, the minimum allowable width of the drop-zdown list box is 0. The width of the list box is either the minimum allowable width or the combo box width, whichever is larger.

See Also

CB_GETDROPPEDWIDTH


CB_SETEDITSEL

An application sends a CB_SETEDITSEL message to select characters in the edit control of a combo box.

CB_SETEDITSEL

wParam = 0;                                // not used; must be zero

lParam = MAKELPARAM((ichStart), (ichEnd);  // start and end position

Parameters

ichStart

Value of the low-order word of lParam; this specifies the starting position. If this parameter is set to −1, the selection, if any, is removed.

ichEnd

Value of the high-order word of lParam; this specifies the ending position. If this parameter is set to −1, all text from the starting position to the last character in the edit control is selected.

Return Values

If the message succeeds, the return value is TRUE. If the message is sent to a combo box with the CBS_DROPDOWNLIST style, it is CB_ERR.

Remarks

The positions are zero-based. The first character of the edit control is in the zero position. The first character after the last selected character is in the ending position. For example, to select the first four characters of the edit control, use a starting position of 0 and an ending position of 4.

See Also

CB_GETEDITSEL


CB_SETEXTENDEDUI

An application sends a CB_SETEXTENDEDUI message to select either the default user interface or the extended user interface for a combo box that has the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

CB_SETEXTENDEDUI

wParam = (WPARAM) (BOOL) fExtended;    // extended user interface flag

lParam = 0;                            // not used; must be zero

Parameters

fExtended

Value of wParam. Specifies whether the combo box uses the extended user interface or the default user interface. A value of TRUE selects the extended user interface; a value of FALSE selects the standard user interface.

Return Values

If the operation succeeds, the return value is CB_OKAY. If an error occurs, it is CB_ERR.

Remarks

By default, the F4 key opens or closes the list and the DOWN ARROW changes the current selection. In the extended user interface, the F4 key is disabled and the DOWN ARROW key opens the drop-down list.

See Also

CB_GETEXTENDEDUI


CB_SETHORIZONTALEXTENT

An application sends the CB_SETHORIZONTALEXTENT message to set the width, in pixels, by which a list box can be scrolled horizontally (the scrollable width). If the width of the list box is smaller than this value, the horizontal scroll bar horizontally scrolls items in the list box. If the width of the list box is equal to or greater than this value, the horizontal scroll bar is hidden or, if the combo box has the CBS_DISABLENOSCROLL style, disabled.

CB_SETHORIZONTALEXTENT

wParam = (WPARAM) cxExtent;            // scrollable width of list box, in pixels

lParam = 0;                            // not used, must be zero

Parameters

cxExtent

Specifies the scrollable width of the list box, in pixels.

Return Values

No return value.

See Also

CB_GETHORIZONTALEXTENT


CB_SETITEMDATA

An application sends a CB_SETITEMDATA message to set the 32-bit value associated with the specified item in a combo box.

CB_SETITEMDATA

wParam = (WPARAM) index;            // item index

lParam = (LPARAM) (DWORD) dwData;   // item data

Parameters

index

Value of wParam. Specifies the item’s zero-based index.

dwData

Value of lParam. Specifies the new value to be associated with the item.

Return Values

If an error occurs, the return value is CB_ERR.

Remarks

If the specified item is in an owner-drawn combo box created without the CBS_HASSTRINGS style, this message replaces the 32-bit value in the lParam parameter of the CB_ADDSTRING or CB_INSERTSTRING message that added the item to the combo box.

See Also

CB_ADDSTRING, CB_GETITEMDATA, CB_INSERTSTRING


CB_SETITEMHEIGHT

An application sends a CB_SETITEMHEIGHT message to set the height of list items or the selection field in a combo box.

CB_SETITEMHEIGHT

wParam = (WPARAM) index;        // item index

lParam = (LPARAM) (int) height; // item height

Parameters

index

Value of wParam. Specifies the component of the combo box for which to set the height.

This parameter must be −1 to set the height of the selection field. It must be zero to set the height of list items, unless the combo box has the CBS_OWNERDRAWVARIABLE style. In that case, the index parameter is the zero-based index of a specific list item.

height

Value of lParam. Specifies the height, in pixels, of the combo box component identified by index.

Return Values

If the index or height is invalid, the return value is CB_ERR.

Remarks

The selection field height in a combo box is set independently of the height of the list items. An application must ensure that the height of the selection field is not smaller than the height of a particular list item.

See Also

CB_GETITEMHEIGHT, WM_MEASUREITEM


CB_SETLOCALE

An application sends a CB_SETLOCALE message to set the current locale of the combo box. If the combo box has the CBS_SORT style and strings are added using CB_ADDSTRING, the locale of a combo box affects how list items are sorted.

CB_SETLOCALE

wParam = (WPARAM) (WORD) wLocaleID; // locale identifier

lParam = 0;                         // not used; must be zero

Parameters

wLocaleID

Value of wParam. Specifies the locale identifier for the combo box to use for sorting when adding text.

Return Values

The return value is the previous locale identifier. If wParam specifies a locale not installed on the system, the return value is CB_ERR and the current combo box locale is not changed.

Remarks

Use the MAKELCID macro to construct a locale identifier and the MAKELANGID macro to construct a language identifier. The language identifier is made up of a primary language identifier and a sublanguage identifier.

See Also

CB_ADDSTRING, CB_GETLOCALE, MAKELANGID, MAKELCID


CB_SETTOPINDEX

An application sends the CB_SETTOPINDEX message to ensure that a particular item is visible in the list box of a combo box. The system scrolls the list box contents so that either the specified item appears at the top of the list box or the maximum scroll range has been reached.

CB_SETTOPINDEX

wParam = (WPARAM) index;            // zero-based index of item list

lParam = 0;                         // not used, must be zero

Parameters

index

Specifies the zero-based index of the list item.

Return Values

If the message is successful, the return value is zero.

If the message fails, the return value is CB_ERR.

See Also

CB_GETTOPINDEX


CB_SHOWDROPDOWN

An application sends a CB_SHOWDROPDOWN message to show or hide the list box of a combo box that has the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

CB_SHOWDROPDOWN

wParam = (WPARAM) (BOOL) fShow;     // the show/hide flag

lParam = 0;                         // not used; must be zero

Parameters

fShow

Value of wParam. Specifies whether the drop-down list box is to be shown or hidden. A value of TRUE shows the list box; a value of FALSE hides it.

Return Values

The return value is always TRUE.

Remarks

This message has no effect on a combo box created with the CBS_SIMPLE style.

See Also

CB_GETDROPPEDSTATE


CBN_CLOSEUP

The CBN_CLOSEUP notification message is sent when the list box of a combo box has been closed. The parent window of the combo box receives this notification message through the WM_COMMAND message.

CBN_CLOSEUP

idComboBox = (int) LOWORD(wParam);  // identifier of combo box

hwndComboBox = (HWND) lParam;       // handle of combo box

Remarks

This notification message is not sent to a combo box that has the CBS_SIMPLE style.

In general, you cannot predict the order in which notifications will be sent. In particular, a CBN_SELCHANGE notification message may occur either before or after a CBN_CLOSEUP notification message.

See Also

CBN_DROPDOWN, CBN_SELCHANGE, WM_COMMAND


CBN_DBLCLK

The CBN_DBLCLK notification message is sent when the user double-clicks a string in the list box of a combo box. The parent window of the combo box receives this notification message through the WM_COMMAND message.

CBN_DBLCLK

idComboBox = (int) LOWORD(wParam);  // identifier of combo box

hwndComboBox = (HWND) lParam;       // handle of combo box

Remarks

This notification message occurs only for a combo box with the CBS_SIMPLE style. In a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST style, a double-click cannot occur because a single click closes the list box.

See Also

CBN_SELCHANGE, WM_COMMAND


CBN_DROPDOWN

The CBN_DROPDOWN notification message is sent when the list box of a combo box is about to be made visible. The parent window of the combo box receives this notification message through the WM_COMMAND message.

CBN_DROPDOWN

idComboBox = (int) LOWORD(wParam);  // identifier of combo box

hwndComboBox = (HWND) lParam;       // handle of combo box

Remarks

This notification message can occur only for a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

See Also

CBN_CLOSEUP, WM_COMMAND


CBN_EDITCHANGE

The CBN_EDITCHANGE notification message is sent after the user has taken an action that may have altered the text in the edit control portion of a combo box. Unlike the CBN_EDITUPDATE notification message, this notification message is sent after Windows updates the screen. The parent window of the combo box receives this notification message through the WM_COMMAND message.

CBN_EDITCHANGE

idComboBox = (int) LOWORD(wParam);  // identifier of combo box

hwndComboBox = (HWND)lParam;        // handle of combo box

Remarks

If the combo box has the CBS_DROPDOWNLIST style, this notification message does not occur.

See Also

CBN_EDITUPDATE, WM_COMMAND


CBN_EDITUPDATE

The CBN_EDITUPDATE notification message is sent when the edit control portion of a combo box is about to display altered text. This notification message is sent after the control has formatted the text, but before it displays the text. The parent window of the combo box receives this notification message through the WM_COMMAND message.

CBN_EDITUPDATE

idComboBox = (int) LOWORD(wParam);  // identifier of combo box

hwndComboBox = (HWND) lParam;       // handle of combo box

Remarks

If the combo box has the CBS_DROPDOWNLIST style, this notification message does not occur.

See Also

CBN_EDITCHANGE, WM_COMMAND


CBN_ERRSPACE

The CBN_ERRSPACE notification message is sent when a combo box cannot allocate enough memory to meet a specific request. The parent window of the combo box receives this notification message through the WM_COMMAND message.

CBN_ERRSPACE

idComboBox = (int) LOWORD(wParam);  // identifier of combo box

hwndComboBox = (HWND) lParam;       // handle of combo box

See Also

WM_COMMAND


CBN_KILLFOCUS

The CBN_KILLFOCUS notification message is sent when a combo box loses the keyboard focus. The parent window of the combo box receives this notification message through the WM_COMMAND message.

CBN_KILLFOCUS

idComboBox = (int) LOWORD(wParam);  // identifier of combo box

hwndComboBox = (HWND) lParam;       // handle of combo box

See Also

CBN_SETFOCUS, WM_COMMAND


CBN_SELCHANGE

The CBN_SELCHANGE notification message is sent when the selection in the list box of a combo box is about to be changed as a result of the user either clicking in the list box or changing the selection by using the arrow keys. The parent window of the combo box receives this message through the WM_COMMAND message.

CBN_SELCHANGE

idComboBox = (int) LOWORD(wParam);  // identifier of combo box

hwndComboBox = (HWND) lParam;       // handle of combo box

See Also

CBN_DBLCLK, WM_COMMAND


CBN_SELENDCANCEL

The CBN_SELENDCANCEL notification message is sent when the user selects an item, but then selects another control or closes the dialog box. It indicates the user’s initial selection is to be ignored. The parent window of the combo box receives this notification message through the WM_COMMAND message.

CBN_SELENDCANCEL

idComboBox = (int) LOWORD(wParam);  // identifier of combo box

hwndComboBox = (HWND) lParam;       // handle of combo box

Remarks

In a combo box with the CBS_SIMPLE style, the CBN_SELENDCANCEL notification message is not sent. The CBN_SELENDOK notification message is sent immediately before every CBN_SELCHANGE notification message.

If the WS_EX_NOPARENTNOTIFY extended window style is specified for the combo box, the CBN_SELENDCANCEL notification message is not sent.

See Also

CBN_SELCHANGE, CBN_SELENDOK, WM_COMMAND


CBN_SELENDOK

The CBN_SELENDOK notification message is sent when the user selects a list item, or selects an item and then closes the list. It indicates that the user’s selection is to be processed. The parent window of the combo box receives this notification message through the WM_COMMAND message.

CBN_SELENDOK

idComboBox = (int) LOWORD(wParam);  // identifier of combo box

hwndComboBox = (HWND) lParam;       // handle of combo box

Remarks

In a combo box with the CBS_SIMPLE style, the CBN_SELENDOK notification message is sent immediately before every CBN_SELCHANGE notification message.

If the WS_EX_NOPARENTNOTIFY extended window style is specified for the combo box, the CBN_SELENDOK notification message is not sent.

See Also

CBN_SELCHANGE, CBN_SELENDCANCEL, WM_COMMAND


CBN_SETFOCUS

The CBN_SETFOCUS notification message is sent when a combo box receives the keyboard focus. The parent window of the combo box receives this notification message through the WM_COMMAND message.

CBN_SETFOCUS

idComboBox = (int) LOWORD(wParam);  // identifier of combo box

hwndComboBox = (HWND) lParam;       // handle of combo box

See Also

CBN_KILLFOCUS, WM_COMMAND


CDM_GETFILEPATH [New - Windows NT]
CDM_GETFILEPATH

[New - Windows NT]

The CDM_GETFILEPATH message retrieves the path and filename of the selected file in an Explorer-style Open or Save As common dialog box. The dialog box must have been created with the OFN_EXPLORER flag; otherwise, the message fails.

CDM_GETFILEPATH

wParam = (WPARAM) cbmax;

lParam = (LPARAM) (LPTSTR) psz;

// Corresponding macro

int CommDlg_OpenSave_GetFilePath(hdlg, psz, cbmax);

Parameters

hdlg

Handle of the common dialog box window to receive the message.

psz

Pointer to the buffer that receives the filename and path.

cbmax

Size, in bytes (ANSI version) or characters (Unicode version), of the psz buffer.

Return Values

If the message succeeds, the return value is the size, in bytes or characters, of the filename and path string, including the terminating NULL character. This is either the number of bytes or characters copied to the psz buffer, or the required buffer size if the buffer is too small.

If an error occurs, the return value is less than zero.

See Also

GetOpenFileName, GetSaveFileName, OPENFILENAME


CDM_GETFOLDERIDLIST [New - Windows NT]
CDM_GETFOLDERIDLIST

[New - Windows NT]

The CDM_GETFOLDERIDLIST message retrieves the address of the item identifier list corresponding to the folder that an Explorer-style Open or Save As common dialog box currently has open. The dialog box must have been created with the OFN_EXPLORER flag; otherwise, the message fails.

CDM_GETFOLDERIDLIST

wParam = (WPARAM) cbmax;

lParam = (LPARAM) (LPVOID) pidl;

// Corresponding macro

int CommDlg_OpenSave_GetFolderIDList(hdlg, pidl, cbmax);

Parameters

hdlg

Handle of the common dialog box window to receive the message.

pidl

Pointer to the buffer that receives the list of item identifiers.

cbmax

Size, in bytes, of the pidl buffer.

Return Values

If the message succeeds, the return value is the size, in bytes, of the list of item identifiers. This is either the number of bytes copied to the pidl buffer, or the required buffer size if the buffer is too small.

If an error occurs, the return value is less than zero.

See Also

GetOpenFileName, GetSaveFileName, OPENFILENAME


CDM_GETFOLDERPATH [New - Windows NT]
CDM_GETFOLDERPATH

[New - Windows NT]

The CDM_GETFOLDERPATH message retrieves the path of the currently open folder or directory for an Explorer-style Open or Save As common dialog box. The dialog box must have been created with the OFN_EXPLORER flag; otherwise, the message fails.

CDM_GETFOLDERPATH

wParam = (WPARAM) cbmax;

lParam = (LPARAM) (LPTSTR) psz;

// Corresponding macro

int CommDlg_OpenSave_GetFolderPath(hdlg, psz, cbmax);

Parameters

hdlg

Handle of the common dialog box window to receive the message.

psz

Pointer to the buffer that receives the path.

cbmax

Size, in bytes (ANSI version) or characters (Unicode version), of the psz buffer.

Return Values

If the message succeeds, the return value is the size, in bytes or characters, of the path string, including the terminating NULL character. This is either the number of bytes or characters copied to the psz buffer, or the required buffer size if the buffer is too small.

If an error occurs, the return value is less than zero.

See Also

GetOpenFileName, GetSaveFileName, OPENFILENAME


CDM_GETSPEC [New - Windows NT]
CDM_GETSPEC

[New - Windows NT]

The CDM_GETSPEC message retrieves the filename (not including the path) of the currently selected file in an Explorer-style Open or Save As common dialog box. The dialog box must have been created with the OFN_EXPLORER flag; otherwise, the message fails.

CDM_GETSPEC

wParam = (WPARAM) cbmax;

lParam = (LPARAM) (LPTSTR) psz;

// Corresponding macro

int CommDlg_OpenSave_GetSpec(hdlg, psz, cbmax);

Parameters

hdlg

Handle of the common dialog box window to receive the message.

psz

Address of the buffer that receives the filename.

cbmax

Size, in bytes (ANSI version) or characters (Unicode version), of the psz buffer.

Return Values

If the message succeeds, the return value is the size, in bytes or characters, of the filename string, including the terminating NULL character. This is either the number of bytes or characters copied to the psz buffer, or the required buffer size if the buffer is too small.

If an error occurs, the return value is less than zero.

See Also

GetOpenFileName, GetSaveFileName, OPENFILENAME


CDM_HIDECONTROL [New - Windows NT]
CDM_HIDECONTROL

[New - Windows NT]

The CDM_HIDECONTROL message hides the specified control in an Explorer-style Open or Save As common dialog box. The dialog box must have been created with the OFN_EXPLORER flag; otherwise, the message fails.

CDM_HIDECONTROL

wParam = (WPARAM) id;

lParam = 0;

// corresponding macro

void CommDlg_OpenSave_HideControl(hdlg, id);

Parameters

hdlg

Handle of the common dialog box window to receive the message.

id

Identifier of the control to hide.

Return Values

No return value.

See Also

GetOpenFileName, GetSaveFileName, OPENFILENAME


CDM_SETCONTROLTEXT [New - Windows NT]
CDM_SETCONTROLTEXT

[New - Windows NT]

The CDM_SETCONTROLTEXT message sets the text for the specified control in an Explorer-style Open or Save As common dialog box. The dialog box must have been created with the OFN_EXPLORER flag; otherwise, the message fails.

CDM_SETCONTROLTEXT

wParam = (WPARAM) id;

lParam = (LPARAM) (LPSTR) text;

// corresponding macro

void CommDlg_OpenSave_SetControlText(hdlg, id, text)

Parameters

hdlg

Handle of the common dialog box window to receive the message.

id

Identifier of the control to whose text is set.

text

Pointer to a null-terminated string specifying the new text for the control.

Return Values

No return value.

See Also

GetOpenFileName, GetSaveFileName, OPENFILENAME


CDM_SETDEFEXT [New - Windows NT]
CDM_SETDEFEXT

[New - Windows NT]

The CDM_SETDEFEXT message sets the default filename extension for an Explorer-style Open or Save As common dialog box. The dialog box must have been created with the OFN_EXPLORER flag; otherwise, the message fails.

CDM_SETDEFEXT

wParam = 0;

lParam = (LPARAM) (LPSTR) pszext;

// corresponding macro

void CommDlg_OpenSave_SetDefExt(hdlg, pszext)

Parameters

hdlg

Handle of the common dialog box window to receive the message.

pszext

Pointer to the new filename extension. Must not include the dot (.).

Return Values

No return value.

See Also

GetOpenFileName, GetSaveFileName, OPENFILENAME


CDN_FILEOK [New - Windows NT]
CDN_FILEOK

[New - Windows NT]

The CDN_FILEOK notification message is sent by an Explorer-style Open or Save As common dialog box when the user specifies a filename and clicks the OK button. Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

CDN_FILEOK

lpon = (LPOFNOTIFY) lParam;

Parameters

lpon

Pointer to an OFNOTIFY structure.

The OFNOTIFY structure contains an NMHDR structure whose code member indicates the CDN_FILEOK notification code.

The OFNOTIFY structure also contains a pointer to an OPENFILENAME structure whose lpstrFile member specifies the address of the selected filename.

Return Values

If the hook procedure returns zero, the dialog box accepts the specified filename and closes.

To reject the specified filename and force the dialog box to remain open, return a nonzero value from the hook procedure and call the SetWindowLong function to set a nonzero DWL_MSGRESULT value.

Remarks

The system sends this notification only if the dialog box was created using the OFN_EXPLORER value.

See Also

GetOpenFileName, GetSaveFileName, NMHDR, OFNHookProc, OFNOTIFY, OPENFILENAME, SetWindowLong, WM_NOTIFY


CDN_FOLDERCHANGE [New - Windows NT]
CDN_FOLDERCHANGE

[New - Windows NT]

The CDN_FOLDERCHANGE notification message is sent by an Explorer-style Open or Save As common dialog box when a new folder is opened. Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

CDN_FOLDERCHANGE

lpon = (LPOFNOTIFY) lParam;

Parameters

lpon

Pointer to an OFNOTIFY structure.

The OFNOTIFY structure contains an NMHDR structure whose code member indicates the CDN_FOLDERCHANGE notification code.

Return Values

The return value is ignored.

Remarks

The system sends this notification only if the dialog box was created using the OFN_EXPLORER value.

To get the path of the newly opened folder, the hook procedure can send the CDM_GETFOLDERPATH message to the dialog box.

See Also

CDM_GETFOLDERPATH, GetOpenFileName, GetSaveFileName, NMHDR, OFNHookProc, OFNOTIFY, WM_NOTIFY


CDN_HELP [New - Windows NT]
CDN_HELP

[New - Windows NT]

The CDN_HELP notification message is sent by an Explorer-style Open or Save As common dialog box when the user clicks the Help button. Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

CDN_HELP

lpon = (LPOFNOTIFY) lParam;

Parameters

lpon

Pointer to an OFNOTIFY structure.

The OFNOTIFY structure contains an NMHDR structure whose code member indicates the CDN_HELP notification code.

Return Values

The return value is ignored.

Remarks

The system sends this notification only if the dialog box was created using the OFN_EXPLORER value.

See Also

GetOpenFileName, GetSaveFileName, NMHDR, OFNHookProc, OFNOTIFY, OPENFILENAME, WM_NOTIFY


CDN_INITDONE [New - Windows NT]
CDN_INITDONE

[New - Windows NT]

The CDN_INITDONE notification message is sent by an Explorer-style Open or Save As common dialog box when the system has finished arranging the controls in the dialog box. The system moves the standard controls to make room for the controls of the child dialog box. Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

CDN_INITDONE

lpon = (LPOFNOTIFY) lParam;

Parameters

lpon

Pointer to an OFNOTIFY structure.

The OFNOTIFY structure contains an NMHDR structure whose code member indicates the CDN_INITDONE notification code.

Return Values

The return value is ignored.

Remarks

The system sends this notification only if the dialog box was created using the OFN_EXPLORER value.

See Also

GetOpenFileName, GetSaveFileName, NMHDR, OFNHookProc, OFNOTIFY, OPENFILENAME, WM_NOTIFY


CDN_SELCHANGE [New - Windows NT]
CDN_SELCHANGE

[New - Windows NT]

The CDN_SELCHANGE notification message is sent by an Explorer-style Open or Save As common dialog box when the selection changes in the list box that displays the contents of the currently opened folder or directory. Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

CDN_SELCHANGE

lpon = (LPOFNOTIFY) lParam;

Parameters

lpon

Pointer to an OFNOTIFY structure.

The OFNOTIFY structure contains an NMHDR structure whose code member indicates the CDN_SELCHANGE notification code.

Return Values

The return value is ignored.

Remarks

The system sends this notification only if the dialog box was created using the OFN_EXPLORER value.

To get the name of the newly selected file or folder, the hook procedure can send the CDM_GETFILEPATH or CDM_GETSPEC message to the common dialog box.

See Also

CDM_GETFILEPATH, CDM_GETSPEC, GetOpenFileName, GetSaveFileName, NMHDR, OFNHookProc, OFNOTIFY, WM_NOTIFY


CDN_SHAREVIOLATION [New - Windows NT]
CDN_SHAREVIOLATION

[New - Windows NT]

The CDN_SHAREVIOLATION notification message is sent by an Explorer-style Open or Save As common dialog box when the user clicks the OK button and a network sharing violation occurs for the selected file. Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

CDN_SHAREVIOLATION

lpon = (LPOFNOTIFY) lParam;

Parameters

lpon

Pointer to an OFNOTIFY structure. The pszFile member of this structure points to the name of the file that had the sharing violation.

The OFNOTIFY structure contains an NMHDR structure whose code member indicates the CDN_SHAREVIOLATION notification code.

Return Values

The return value indicates how the dialog box should handle the sharing violation.

If the hook procedure returns zero, the dialog box displays the standard warning message for a sharing violation.

To prevent the display of the standard warning message, return a nonzero value from the hook procedure and call the SetWindowLong function to set one of the following DWL_MSGRESULT values:

OFN_SHAREFALLTHROUGH	Causes the dialog box to return the filename without warning the user about the sharing violation.
OFN_SHARENOWARN	Causes the dialog box to reject the filename without warning the user about the sharing violation.
Remarks

The system sends this notification only if the dialog box was created using the OFN_EXPLORER value.

The system sends this notification only if the the OFN_SHAREAWARE value was not specified when the dialog box was created.

See Also

GetOpenFileName, GetSaveFileName, NMHDR, OFNHookProc, OFNOTIFY, OPENFILENAME, SetWindowLong, WM_NOTIFY


CDN_TYPECHANGE [New - Windows NT]
CDN_TYPECHANGE

[New - Windows NT]

The CDN_TYPECHANGE notification message is sent by an Explorer-style Open or Save As common dialog box when the user selects a new file type from the file types combo box. Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

CDN_TYPECHANGE

lpon = (LPOFNOTIFY) lParam;

Parameters

lpon

Address of an OFNOTIFY structure.

The OFNOTIFY structure contains an NMHDR structure whose code member indicates the CDN_TYPECHANGE notification code.

The OFNOTIFY structure also contains a pointer to an OPENFILENAME structure whose nFilterIndex member indicates the one-based index of the newly selected file type filter.

Return Values

The return value is ignored.

Remarks

The system sends this notification only if the dialog box was created using the OFN_EXPLORER value.

See Also

GetOpenFileName, GetSaveFileName, NMHDR, OFNHookProc, OFNOTIFY, OPENFILENAME, WM_NOTIFY


COLOROKSTRING

A Color dialog box sends the COLOROKSTRING registered message to your hook procedure when the user selects a color and clicks the OK button. The hook procedure can accept the color and allow the dialog box to close, or reject the color and force the dialog box to remain open.

MessageID = RegisterWindowMessage(COLOROKSTRING);
wParam = 0;
lpcc = (LPCHOOSECOLOR) lParam;

Parameters

lpcc

Pointer to a CHOOSECOLOR structure. The rgbResult member of this structure contains the RGB color value of the selected color.

Return Values

If the hook procedure returns zero, the Color dialog box accepts the selected color and closes.

If the hook procedure returns a nonzero value, the Color dialog box rejects the selected color and remains open.

Remarks

The hook procedure must specify the COLOROKSTRING constant in a call to the RegisterWindowMessage function to get the identifier for the message sent by the dialog box.

See Also

CHOOSECOLOR, RegisterWindowMessage


CPL_DBLCLK

The CPL_DBLCLK message is sent to the CPlApplet function of a Control Panel application when the user double-clicks the icon of a dialog box supported by the application.

CPL_DBLCLK

uAppNum = (UINT) lParam1;   // application number

lData = (LONG) lParam2;     // application-defined value

Parameters

uAppNum

Value of lParam1. Specifies the dialog box number. This number must be in the range zero through one less than the value returned in response to the CPL_GETCOUNT message (CPL_GETCOUNT − 1).

lData

Value of lParam2. Specifies the value that the Control Panel application loaded into the lData member of the CPLINFO or NEWCPLINFO structure for the dialog box. The application loads lData member in response to the CPL_INQUIRE or CPL_NEWINQUIRE message.

Return Values

If the CPlApplet function processes this message successfully, the return value is zero; otherwise, it is nonzero.

Remarks

In response to this message, a Control Panel application must display the corresponding dialog box.

See Also

CPL_GETCOUNT, CPL_INQUIRE, CPL_NEWINQUIRE, CPL_SELECT, CPlApplet, CPLINFO, NEWCPLINFO


CPL_EXIT

The CPL_EXIT message is sent once to the CPlApplet function of a Control Panel application before the controlling application releases the DLL containing the application.

CPL_EXIT

Parameters

This function has no parameters.

Return Values

If the CPlApplet function processes this message successfully, it should return zero.

Remarks

This message is sent after the last CPL_STOP message is sent.

In response to this message, a Control Panel application must free any memory that it has allocated and perform global-level cleanup.

See Also

CPL_STOP, CPlApplet, FreeLibrary


CPL_GETCOUNT

The CPL_GETCOUNT message is sent to the CPlApplet function of a Control Panel application to retrieve the number of dialog boxes supported by the application.

CPL_GETCOUNT

Parameters

This function has no parameters.

Return Values

The CPlApplet function should return the number of dialog boxes that the Control Panel application supports.

Remarks

This message is sent immediately after the CPL_INIT message.

See Also

CPL_INIT, CPlApplet


CPL_INIT

The CPL_INIT message is sent to the CPlApplet function of a Control Panel application to prompt it to perform global initialization, especially memory allocation.

CPL_INIT

Parameters

This function has no parameters.

Return Values

If initialization succeeds, the CPlApplet function should return a nonzero value. Otherwise, it should return zero. If CPlApplet returns zero, the controlling application ends communication and releases the DLL containing the Control Panel application.

Remarks

Because this is the only way a Control Panel application can signal an error condition, the application should allocate memory in response to this message.

This message is sent immediately after the DLL containing the application is loaded.

See Also

CPlApplet, FreeLibrary


CPL_INQUIRE

The CPL_INQUIRE message is sent to the CPlApplet function of a Control Panel application to request information about a dialog box that the application supports.

CPL_INQUIRE

uAppNum = (UINT) lParam1;     // application number

lpcpli = (LPCPLINFO) lParam2; // structure for application info.

Parameters

uAppNum

Value of lParam1. Specifies the dialog box number. This number must be in the range zero through one less than the value returned in response to the CPL_GETCOUNT message (CPL_GETCOUNT − 1).

lpcpli

Value of lParam2. Points to a CPLINFO structure. The application must fill this structure with resource identifiers for the icon, short name, description, and any user-defined value associated with the dialog box.

Return Values

If the CPlApplet function processes this message successfully, it should return zero.

Remarks

The Control Panel sends the CPL_INQUIRE message once for each dialog box supported by your application. The Control Panel also sends a CPL_NEWINQUIRE message for each dialog box. These messages are sent immediately after the CPL_GETCOUNT message. However, the system does not guarantee the order in which the CPL_INQUIRE and CPL_NEWINQUIRE messages are sent.

You can perform initialization for the dialog box when you receive CPL_INQUIRE. If you must allocate memory, do so in response to the CPL_INIT message.

On Windows 95 and Windows NT version 4.0, the system caches the information returned in the CPLINFO structure used by CPL_INQUIRE. This provides significantly better performance because the system only needs to load your application the first time the Control Panel starts up. On the other hand, the CPL_NEWINQUIRE message returns information in a form that the system cannot cache. For this reason, most CPlApplet functions should process CPL_INQUIRE and ignore CPL_NEWINQUIRE.

The only applications that should use CPL_NEWINQUIRE are those that need to change their icon or display strings based on the state of the computer. In this case, your CPL_INQUIRE handler should specify the CPL_DYNAMIC_RES value for the idIcon, idName, or idInfo members of the CPLINFO structure, rather than specifying a valid resource identifier. This causes the Control Panel to send the CPL_NEWINQUIRE message each time it needs the icon and display strings, allowing you to specify information based on the current state of the computer. Of course, this is significantly slower than using cached information.

See Also

CPL_GETCOUNT, CPL_INIT, CPL_NEWINQUIRE, CPlApplet, CPLINFO


CPL_NEWINQUIRE

The CPL_NEWINQUIRE message is sent to the CPlApplet function of a Control Panel application to request information about a dialog box that the application supports.

For better performance, most applications should ignore CPL_NEWINQUIRE and process the CPL_INQUIRE message instead. The CPL_NEWINQUIRE message is useful only for applications that need to change their icon or display strings based on the state of the computer.

CPL_NEWINQUIRE

uAppNum = (UINT) lParam1;         // application number

lpncpli = (LPNEWCPLINFO) lParam2; // structure for appl. info.

Parameters

uAppNum

Value of lParam1. Specifies the dialog box number. This number must be in the range zero through one less than the value returned in response to the CPL_GETCOUNT message (CPL_GETCOUNT − 1).

lpncpli

Value of lParam2. Specifies the address of a NEWCPLINFO structure. The Control Panel application should fill this structure with information about the dialog box.

Return Values

If the CPlApplet function processes this message successfully, it should return zero.

Remarks

The Control Panel sends the CPL_NEWINQUIRE message once for each dialog box supported by your application. The Control Panel also sends a CPL_INQUIRE message for each dialog box. These messages are sent immediately after the CPL_GETCOUNT message. However, the system does not guarantee the order in which the CPL_INQUIRE and CPL_NEWINQUIRE messages are sent.

You can perform initialization for the dialog box when you receive CPL_INQUIRE. If you must allocate memory, do so in response to the CPL_INIT message.

The CPL_NEWINQUIRE message was introduced in Windows version 3.1 as a replacement for CPL_INQUIRE. However, CPL_INQUIRE is the preferred message for Windows 95 and Windows NT version 4.0. This is because CPL_NEWINQUIRE returns information in a form that the system cannot cache. Consequently, applications that process CPL_NEWINQUIRE must be loaded each time the Control Panel needs the information, resulting in a significant reduction in performance.

The only applications that should use CPL_NEWINQUIRE are those that need to change their icon or display strings based on the state of the computer. In this case, your CPL_INQUIRE handler should specify the CPL_DYNAMIC_RES value for the idIcon, idName, or idInfo members of the CPLINFO structure, rather than specifying a valid resource identifier. This causes the Control Panel to send the CPL_NEWINQUIRE message each time it needs the icon and display strings, allowing you to specify information based on the current state of the computer. Of course, this is significantly slower than using cached information.

See Also

CPL_GETCOUNT, CPL_INIT, CPL_INQUIRE, CPlApplet, CPLINFO, NEWCPLINFO


CPL_SELECT

The CPL_SELECT message is obsolete. This message was used by versions of Windows earlier than Windows 95 and Windows NT version 4.0. Current versions of Windows do not send this message.


CPL_STOP

The CPL_STOP message is sent to the CPlApplet function of a Control Panel application when the application controlling the Control Panel application closes. The controlling application sends the message once for each dialog box that the application supports.

CPL_STOP

uAppNum = (UINT) lParam1;   // application number

lData = (LONG) lParam2;     // application-defined value

Parameters

uAppNum

Value of lParam1. Specifies the dialog box number.

lData

Value of lParam2. Specifies the value that the Control Panel application loaded into the lData member of the CPLINFO or NEWCPLINFO structure for the dialog box. The application loads lData member in response to the CPL_INQUIRE or CPL_NEWINQUIRE message.

Return Values

If the CPlApplet function processes this message successfully, it should return zero.

Remarks

In response to this message, a Control Panel application must perform cleanup for the given dialog box.

See Also

CPL_EXIT, CPL_GETCOUNT, CPL_INQUIRE, CPL_NEWINQUIRE, CPlApplet, CPLINFO, NEWCPLINFO


DBT_CONFIGCHANGECANCELED

The operating system sends the DBT_CONFIGCHANGECANCELED device message when a request to change the current configuration (dock or undock) has been canceled.

To send the DBT_CONFIGCHANGECANCELED device message, the operating system sends the WM_DEVICECHANGE message with wParam set to DBT_CONFIGCHANGECANCELED and lParam set to zero.

Parameters

lParam

lParam is zero when the WM_DEVICECHANGE message is sent with wParam set to DBT_CONFIGCHANGECANCELED.

Return Values

Return TRUE.

See Also

DBT_CONFIGCHANGED, DBT_QUERYCHANGECONFIG, WM_DEVICECHANGE


DBT_CONFIGCHANGED

The operating system sends the DBT_CONFIGCHANGED device message to indicate that the current configuration has changed, due to a dock or undock. An application or driver that stores data in the registry under the HKEY_CURRENT_CONFIG key should update the data.

To send the DBT_CONFIGCHANGED device message, the operating system sends the WM_DEVICECHANGE message with wParam set to DBT_CONFIGCHANGED and lParam set to zero.

Parameters

lParam

lParam is zero when the WM_DEVICECHANGE message is sent with wParam set to DBT_CONFIGCHANGED.

Return Values

Return TRUE.

See Also

DBT_CONFIGCHANGECANCELED, DBT_QUERYCHANGECONFIG, WM_DEVICECHANGE


DBT_DEVICEARRIVAL

The operating system sends the DBT_DEVICEARRIVAL device message when a device has been inserted and becomes available.

To send the DBT_DEVICEARRIVAL device message, the operating system sends the WM_DEVICECHANGE message with wParam set to DBT_DEVICEARRIVAL and lParam set to the address of a DEV_BROADCAST_HDR structure identifying the device inserted.

dwData = (DWORD) lParam;

Parameters

dwData

Address of a DEV_BROADCAST_HDR structure identifying the device inserted.

Return Values

Return TRUE.

See Also

DEV_BROADCAST_HDR, WM_DEVICECHANGE


DBT_DEVICEQUERYREMOVE

The operating system sends the DBT_DEVICEQUERYREMOVE device message to request permission to remove a device. Any application can deny this request and cancel the removal.

To send the DBT_DEVICEQUERYREMOVE device message, the operating system sends the WM_DEVICECHANGE message with wParam set to DBT_DEVICEQUERYREMOVE and lParam set to the address of a DEV_BROADCAST_HDR structure identifying the device to remove.

dwData = (DWORD) lParam;

Parameters

dwData

Address of a DEV_BROADCAST_HDR structure identifying the device to remove.

Return Values

Return TRUE to grant permission to remove a device.

Return BROADCAST_QUERY_DENY to deny permission to remove a device.

See Also

DEV_BROADCAST_HDR, WM_DEVICECHANGE


DBT_DEVICEQUERYREMOVEFAILED

The operating system sends the DBT_DEVICEQUERYREMOVEFAILED device message when a request to remove a device has been canceled.

To send the DBT_DEVICEQUERYREMOVEFAILED device message, the operating system sends the WM_DEVICECHANGE message with wParam set to DBT_DEVICEQUERYREMOVEFAILED and lParam set to the address of a DEV_BROADCAST_HDR structure identifying the device.

dwData = (DWORD) lParam;

Parameters

dwData

Address of a DEV_BROADCAST_HDR structure identifying the device.

Return Values

Return TRUE.

See Also

DEV_BROADCAST_HDR, WM_DEVICECHANGE


DBT_DEVICEREMOVECOMPLETE

The operating system sends the DBT_DEVICEREMOVECOMPLETE device message when a device has been removed.

To send the DBT_DEVICEREMOVECOMPLETE device message, the operating system sends the WM_DEVICECHANGE message with wParam set to DBT_DEVICEREMOVECOMPLETE and lParam set to the address of a DEV_BROADCAST_HDR structure identifying the device removed.

dwData = (DWORD) lParam;

Parameters

dwData

Address of a DEV_BROADCAST_HDR structure identifying the device removed.

Return Values

Return TRUE.

Remarks

The operating system may send a DBT_DEVICEREMOVECOMPLETE message without sending corresponding DBT_DEVICEQUERYREMOVE and DBT_DEVICEREMOVEPENDING messages. In such cases, the applications and drivers must recover from the loss of the device as best they can.

See Also

DBT_DEVICEQUERYREMOVE, DBT_DEVICEREMOVEPENDING, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DBT_DEVICEREMOVEPENDING

The operating system sends the DBT_DEVICEREMOVEPENDING device message when the device is about to be removed. This message is the last chance for applications and drivers to prepare for the removal of the device.

To send the DBT_DEVICEREMOVEPENDING device message, the operating system sends the WM_DEVICECHANGE message with wParam set to DBT_DEVICEREMOVEPENDING and lParam set to the address of a DEV_BROADCAST_HDR structure identifying the device to remove.

dwData = (DWORD) lParam;

Parameters

dwData

Address of a DEV_BROADCAST_HDR structure identifying the device to remove.

Return Values

Return TRUE.

Remarks

This message cannot be denied.

See Also

DEV_BROADCAST_HDR, WM_DEVICECHANGE


DBT_DEVICETYPESPECIFIC

The operating system sends the DBT_DEVICETYPESPECIFIC device message when a device-specific event occurs.

To send the DBT_DEVICETYPESPECIFIC device message, the operating system sends the WM_DEVICECHANGE message with wParam set to DBT_DEVICETYPESPECIFIC and lParam set as described in the following.

dwData = (DWORD) lParam;

Parameters

dwData

Address of a DEV_BROADCAST_HDR structure identifying the device. lParam is application-defined. May be zero.

Return Values

Return TRUE.

See Also

DEV_BROADCAST_HDR, WM_DEVICECHANGE


DBT_QUERYCHANGECONFIG

The operating system sends the DBT_QUERYCHANGECONFIG device message to request permission to change the current configuration (dock or undock). Any application can deny this request and cancel the change.

To send the DBT_QUERYCHANGECONFIG device message, the operating system sends the WM_DEVICECHANGE message with wParam set to DBT_QUERYCHANGECONFIG and lParam set to zero.

Parameters

lParam

lParam is zero when the WM_DEVICECHANGE message is sent with wParam set to DBT_QUERYCHANGECONFIG.

Return Values

Return TRUE to grant permission to change the configuration.

Return BROADCAST_QUERY_DENY to deny permission to change the configuration.

See Also

DBT_CONFIGCHANGECANCELED, DBT_CONFIGCHANGED, WM_DEVICECHANGE


DBT_USERDEFINED

The DBT_USERDEFINED device message identifies a user-defined system message.

To send the DBT_USERDEFINED device message, send the WM_DEVICECHANGE message with wParam set to DBT_USERDEFINED and lParam set as described following.

dwData = (DWORD) lParam;

Parameters

dwData

Address of the user-defined data. The data must be in the format specified by the _DEV_BROADCAST_USERDEFINED structure. lParam is application-defined. May be zero.

See Also

_DEV_BROADCAST_USERDEFINED, WM_DEVICECHANGE


DL_BEGINDRAG

The DL_BEGINDRAG notification message notifies the parent window of a drag list box that the user has clicked the left mouse button on a list item. A drag list box sends DL_BEGINDRAG in the form of a drag list message.

DL_BEGINDRAG

idCtl = (int) wParam;

pDragInfo = (LPDRAGLISTINFO) lParam;

Parameters

idCtl

Control identifier of the drag list box.

pDragInfo

Pointer to a DRAGLISTINFO structure that contains the DL_BEGINDRAG notification code, the handle to the drag list box, and the cursor position.

Return Values

The parent window should return TRUE to begin a drag operation or FALSE to prevent a drag operation.

Remarks

When processing this notification message, a window procedure typically determines the list item at the specified cursor position by using the LBItemFromPt function and then returns TRUE or FALSE, depending on whether the item should be dragged. Before returning TRUE, the window procedure should save the index of the list item, so the application knows which item to move or copy when the drag operation is completed.

See Also

DRAGLISTINFO, LBItemFromPt


DL_CANCELDRAG

The DL_CANCELDRAG notification message signals that the user has canceled a drag operation by clicking the right mouse button or pressing the ESC key. A drag list box sends DL_CANCELDRAG to its parent window in the form of a drag list message.

DL_CANCELDRAG

idCtl = (int) wParam;

pDragInfo = (LPDRAGLISTINFO) lParam;

Parameters

idCtl

Control identifier of the drag list box.

pDragInfo

Pointer to a DRAGLISTINFO structure that contains the DL_CANCELDRAG notification code, the handle to the drag list box, and the cursor position.

Return Values

No return value.

Remarks

By processing the DL_CANCELDRAG notification message, an application can reset its internal state to indicate that dragging is not in effect.

See Also

DRAGLISTINFO


DL_DRAGGING

The DL_DRAGGING notification message signals that the user has moved the mouse while dragging an item. DL_DRAGGING is also sent periodically during dragging even if the mouse is not moved. A drag list box sends this notification to its parent window in the form of a drag list message.

DL_DRAGGING

idCtl = (int) wParam;

pDragInfo = (LPDRAGLISTINFO) lParam;

Parameters

idCtl

Control identifier of the drag list box.

pDragInfo

Pointer to a DRAGLISTINFO structure that contains the DL_DRAGGING notification code, the handle to the drag list box, and the cursor position.

Return Values

The return value determines the type of mouse cursor that the drag list should set; it can be the DL_STOPCURSOR, DL_COPYCURSOR, or DL_MOVECURSOR value. If any other value is returned, the cursor does not change.

Remarks

A window procedure typically processes the DL_DRAGGING notification message by determining the item under the cursor and then drawing an insert icon. To get the item under the cursor, use the LBItemFromPt function, specifying TRUE for the bAutoScroll parameter. This option causes the drag list box to scroll periodically if the cursor is above or below its client area. To draw the insert icon, use the DrawInsert function.

See Also

DrawInsert, DRAGLISTINFO, LBItemFromPt


DL_DROPPED

The DL_DROPPED notification message signals that the user has completed a drag operation by releasing the left mouse button. A drag list box sends DL_DROPPED to its parent window in the form of a drag list message.

DL_BEGINDRAG

idCtl = (int) wParam;

pDragInfo = (LPDRAGLISTINFO) lParam;

Parameters

idCtl

Control identifier of the drag list box.

pDragInfo

Pointer to a DRAGLISTINFO structure that contains the DL_DROPPED notification code, the handle to the drag list box, and the cursor position.

Return Values

No return value.

Remarks

A window procedure typically processes this notification message by inserting or copying the dragged list item before the list item under the cursor. To retrieve the index of the item at the cursor position, use the LBItemFromPoint function. Note that the DL_DROPPED notification message is sent even if the cursor is not on a list item. In that case, LBItemFromPoint returns − 1.

See Also

DRAGLISTINFO


DM_GETDEFID

An application sends a DM_GETDEFID message to retrieve the identifier of the default push button control for a dialog box.

DM_GETDEFID

Parameters

This message has no parameters.

Return Values

If a default push button exists, the high-order word of the return value contains the value DC_HASDEFID and the low-order word contains the control identifier. Otherwise, the return value is zero.

Remarks

The DefDlgProc function processes this message.

See Also

DefDlgProc, DM_SETDEFID


DM_REPOSITION

The DM_REPOSITION message repositions a top-level dialog box so that it fits within the desktop area. An application can send this message to a dialog box after resizing it to ensure that the entire dialog box remains visible.

DM_REPOSITION

wParam = 0;

lParam = 0;

Parameters

This message has no parameters.

Return Values

This message has no return value.

Remarks

This message has no effect if the dialog box is a child window.


DM_SETDEFID

An application sends a DM_SETDEFID message to change the identifier of the default push button for a dialog box.

DM_SETDEFID

wParam = idControl; // identifier of new default push button

Parameters

idControl

Value of wParam. Specifies the identifier of a push button control that will become the default.

Remarks

This message is processed by the DefDlgProc function. To set the default push button, the function can send WM_GETDLGCODE and BM_SETSTYLE messages to the given control and the current default push button.

Using the DM_SETDEFID message can result in more than one button appearing to have the default push button state. When Windows brings up a dialog, it draws the first push button in the dialog template with the default state border. Sending a DM_SETDEFID message to change the default button will not always remove the default state border from the first push button. In these cases, the application should send a BM_SETSTYLE message to change the first push button border style.

Return Values

The return value is always TRUE.

See Also

BM_SETSTYLE, DefDlgProc, DM_GETDEFID, EM_SETLIMITTEXT, WM_GETDLGCODE


EM_CANPASTE

The EM_CANPASTE message determines whether a rich edit control can paste a specified clipboard format.

EM_CANPASTE

wParam = (WPARAM) (UINT) uFormat;

lParam = 0;

Parameters

uFormat

Value identifying the clipboard format to try, or zero to try any format currently on the clipboard.

Return Values

Returns a nonzero value if the clipboard format can be pasted or zero otherwise.


EM_CANUNDO

An application sends an EM_CANUNDO message to determine whether an edit-control operation can be undone; that is, whether the control can respond to the EM_UNDO message.

EM_CANUNDO

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

If the edit control can correctly process the EM_UNDO message, the return value is TRUE; otherwise, it is FALSE.

See Also

EM_UNDO


EM_CHARFROMPOS

An application sends an EM_CHARFROMPOS message to retrieve the zero-based character index and zero-based line index of the character nearest the specified point in an edit control.

EM_CHARFROMPOS

wParam = 0;

lParam = MAKELPARAM(x, y)

Parameters

x

Value of the low-order word of lParam. Specifies the x-coordinate of a point in the edit control's client area. The coordinate is relative to the upper-left corner of the client area.

y

Value of the high-order word of lParam. Specifies the y-coordinate of a point in the edit control's client area. The coordinate is relative to the upper-left corner of the client area.

Return Values

The return value specifies the character index in the low-order word and the line index in the high-order word. For single-line edit controls, the line index is always 0. The return value is the last character in the edit control if the given point is beyond the last character in the control. The return value is −1 if the specified point is outside the client area of the edit control.

See Also

EM_POSFROMCHAR


EM_DISPLAYBAND

The EM_DISPLAYBAND message displays a portion of a rich edit control’s contents, as previously formatted for a device using the EM_FORMATRANGE message.

EM_DISPLAYBAND

wParam = 0;

lParam = (LPARAM) (LPRECT) lprc;

Parameters

lprc

Pointer to a RECT structure specifying the area of the device to display to.

Return Values

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

Remarks

Text and OLE objects are clipped by the rectangle. The application does not need to set the clipping region.

See Also

EM_FORMATRANGE, RECT


EM_EMPTYUNDOBUFFER

An application sends an EM_EMPTYUNDOBUFFER message to reset the undo flag of an edit control. The undo flag is set whenever an operation within the edit control can be undone.

EM_EMPTYUNDOBUFFER

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

This message does not return a value.

Remarks

The undo flag is automatically reset whenever the edit control receives a WM_SETTEXT or EM_SETHANDLE message.

See Also

EM_CANUNDO, EM_SETHANDLE, EM_UNDO, WM_SETTEXT


EM_EXGETSEL

The EM_EXGETSEL message retrieves the starting and ending character positions of the selection in a rich edit control.

EM_EXGETSEL

wParam = 0;

lParam = (LPARAM) (CHARRANGE FAR *) lpchr;

Parameters

lpchr

Pointer to a CHARRANGE structure that receives the selection range.

Return Values

No return value.

See Also

CHARRANGE


EM_EXLIMITTEXT

The EM_EXLIMITTEXT message sets an upper limit to the amount of text in a rich edit control.

EM_EXLIMITTEXT

wParam = 0;

lParam = (LPARAM) (DWORD) cchTextMax;

Parameters

cchTextMax

Maximum amount of text or zero for the default maximum. An OLE object counts as a single character. The default maximum is 32K.

Return Values

No return value.


EM_EXLINEFROMCHAR

The EM_EXLINEFROMCHAR message determines which line contains the specified character in a rich edit control.

EM_EXLINEFROMCHAR

wParam = 0;

lParam = (LPARAM) (DWORD) ichCharPos;

Parameters

ichCharPos

Zero-based index of the character.

Return Values

Returns the zero-based index of the line.


EM_EXSETSEL

The EM_EXSETSEL message selects a range of characters and/or OLE objects in a rich edit control.

EM_EXSETSEL

wParam = 0;

lParam = (LPARAM) (CHARRANGE FAR *) ichCharRange;

Parameters

ichCharRange

Zero-based index of the character.

Return Values

Returns the zero-based index of the line.


EM_FINDTEXT

The EM_FINDTEXT message finds text within a rich edit control.

EM_FINDTEXT

wParam = (WPARAM) (UINT) fuFlags;

lParam = (LPARAM) (FINDTEXT FAR *) lpFindText;

Parameters

fuFlags

Zero or more of the FT_MATCHCASE and FT_WHOLEWORD values.

lpFindText

Pointer to a FINDTEXT structure containing information about the find operation.

Return Values

Returns the zero-based character position of the next match, or  − 1 if there are no more matches.

See Also

FINDTEXT


EM_FINDTEXTEX

Finds text within a rich edit control.

EM_FINDTEXTEX

wParam = (WPARAM) (UINT) fuFlags;

lParam = (LPARAM) (FINDTEXTEX FAR *) lpFindText;

Parameters

fuFlags

Zero or more of the FT_MATCHCASE and FT_WHOLEWORD values.

lpFindText

Address of a FINDTEXTEX structure containing information about the find operation.

Return Values

Returns the zero-based character position of the next match or  − 1 if there are no more matches.

See Also

FINDTEXTEX


EM_FINDWORDBREAK

The EM_FINDWORDBREAK message finds the next word break before or after the specified character position, or retrieves information about the character at that position.

EM_FINDWORDBREAK

wParam = (WPARAM) (UINT) code;

lParam = (LPARAM) (DWORD) ichStart;

Parameters

code

Action to take. This parameter can be one of these values:

Value	Meaning
WB_CLASSIFY	Returns the character class and word break flags of the character at the specified position.
WB_ISDELIMITER	Returns TRUE if the character at the specified position is a delimiter, or FALSE otherwise.
WB_LEFT	Finds the nearest character before the specified position that begins a word.
WB_LEFTBREAK	Finds the next word end before the specified position. Same as WB_PREVBREAK.
WB_MOVEWORDLEFT	Finds the next character that begins a word before the specified position. This value is used during CTRL+LEFT key processing. Same as WB_MOVEWORDPREV.
WB_MOVEWORDRIGHT	Finds the next character that begins a word after the specified position. This value is used during CTRL+RIGHT key processing. Same as WB_MOVEWORDNEXT.
WB_RIGHT	Finds the next character that begins a word after the specified position.
WB_RIGHTBREAK	Finds the next end-of-word delimiter after the specified position. Same as WB_NEXTBREAK.
ichStart

Zero-based character position to start from.

Return Values

Returns the character index of the word break, unless the code parameter is the WB_CLASSIFY or WB_ISDELIMITER value. For more information, see the description of the code parameter.

Remarks

If code is WB_LEFT and WB_RIGHT, the word break procedure finds word breaks only after delimiters. This matches the functionality of an edit control. If code is WB_MOVEWORDLEFT or WB_MOVEWORDRIGHT, the word break procedure also compares character classes and word break flags.

For information about character classes and word break flags, see Word and Line Breaks.


EM_FMTLINES

An application sends an EM_FMTLINES message to set the inclusion flag of soft linebreak characters on or off within a multiline edit control. A soft linebreak consists of two carriage returns and a linefeed and is inserted at the end of a line that is broken because of wordwrapping.

EM_FMTLINES

wParam = (WPARAM) (BOOL) fAddEOL;   // linebreak flag

lParam = 0;                         // not used; must be zero

Parameters

fAddEOL

Value of wParam. Specifies whether soft-linebreak characters are to be inserted. A value of TRUE inserts the characters; a value of FALSE removes them.

Return Values

The return value is identical to the fAddEOL parameter.

Remarks

This message affects only the buffer returned by the EM_GETHANDLE message and the text returned by the WM_GETTEXT message. It has no effect on the display of the text within the edit control.

The EM_FMTLINES message does not affect a line that ends with a hard linebreak. A hard linebreak consists of one carriage return and a linefeed.

Note that the size of the text changes when this message is processed.

See Also

EM_GETHANDLE, WM_GETTEXT


EM_FORMATRANGE

The EM_FORMATRANGE message formats a range of text in a rich edit control for a specific device.

EM_FORMATRANGE

wParam = (WPARAM) (BOOL) fRender;

lParam = (LPARAM) (FORMATRANGE FAR *) lpFmt;

Parameters

fRender

Value specifying whether to render the text. If this parameter is nonzero, the text is rendered. Otherwise, the text is just measured.

lpFmt

Pointer to a FORMATRANGE structure containing information about the output device, or NULL to free information cached by the control.

This message is typically used with the EM_DISPLAYBAND message to format a rich edit control’s contents for an output device such as a printer.

It is very important to free cached information after the last time you use this message by specifying NULL in lpFmt. In addition, after using this message for one device, you must free cached information before using it again for a different device.

Return Values

Returns the index of the last character that fits in the region plus one.

See Also

EM_DISPLAYBAND, FORMATRANGE


EM_GETCHARFORMAT

The EM_GETCHARFORMAT message determines the current character formatting in a rich edit control.

EM_GETCHARFORMAT

wParam = (WPARAM) (BOOL) fSelection;

lParam = (LPARAM) (CHARFORMAT FAR *) lpFmt;

Parameters

fSelection

Value specifying whether to get the default character formatting or the current selection’s character formatting. If this parameter is zero, the default formatting is returned. Otherwise, the current selection’s formatting is returned.

lpFmt

Pointer to a CHARFORMAT structure to fill in. If the selection formatting is being retrieved, the structure receives the attributes of the first character, and the dwMask member specifies which attributes are consistent throughout the entire selection.

Return Values

Returns the value of the dwMask member of the CHARFORMAT structure.

See Also

CHARFORMAT


EM_GETEVENTMASK

The EM_GETEVENTMASK message retrieves the event mask for a rich edit control. The event mask specifies which notification messages the control sends to its parent window.

EM_GETEVENTMASK

wParam = 0;  // not used; must be zero

lParam = 0;  // not used; must be zero

Return Values

Returns the event mask for the rich edit control.


EM_GETFIRSTVISIBLELINE

An application sends an EM_GETFIRSTVISIBLELINE message to determine the uppermost visible line in an edit control.

EM_GETFIRSTVISIBLELINE

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is the zero-based index of the uppermost visible line in a multiline edit control. For single-line edit controls, the return value is the zero-based index of the first visible character.


EM_GETHANDLE

An application sends an EM_GETHANDLE message to retrieve a handle of the memory currently allocated for a multiline edit control’s text.

EM_GETHANDLE

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is a memory handle identifying the buffer that holds the content of the edit control. If an error occurs, such as sending the message to a single-line edit control, the return value is zero.

Remarks

In a 16-bit Windows-based application, the handle is a local memory handle and can be used only by functions that take a local memory handle as a parameter. The application can send this message to a multiline edit control in a dialog box only if it created the dialog box with the DS_LOCALEDIT style flag set. If the DS_LOCALEDIT style is not set, the return value is still nonzero, but the return value will not be meaningful.

See Also

EM_SETHANDLE


EM_GETIMECOLOR

Retrieves the IME composition color. This message is available only in Asian-language versions of the operating system.

EM_GETIMECOLOR
wParam = (WPARAM) 0;
lParam = (LPARAM) (COMPCOLOR *) aCompColor;

Parameters

aCompColor

Address of a 4-element array of COMPCOLOR structures that receives the composition color.

Return Values

Returns nonzero if successful, zero otherwise.

See Also

COMPCOLOR


EM_GETIMEOPTIONS

Retrieves the current IME options. This message is available only in Asian-language versions of the operating system.

EM_GETIMEOPTIONS
wParam = (WPARAM) 0;
lParam = (LPARAM) 0;

Return Values

Returns a combination of the IME option values described for the EM_SETIMEOPTIONS message.

See Also

EM_SETIMEOPTIONS


EM_GETLIMITTEXT

An application sends the EM_GETLIMITTEXT message to retrieve the current text limit, in characters, for an edit control.

EM_GETLIMITTEXT

wParam = 0;  // not used, must be zero

lParam = 0;  // not used, must be zero

Parameters

This message has no parameters.

Return Values

The return value is the text limit.

See Also

EM_SETLIMITTEXT


EM_GETLINE

An application sends an EM_GETLINE message to copy a line of text from an edit control and place it in a specified buffer.

EM_GETLINE

wParam = (WPARAM) line;          // line number to retrieve

lParam = (LPARAM) (LPCSTR) lpch; // address of buffer for line

Parameters

line

Value of wParam. Specifies the zero-based index of the line to retrieve from a multiline edit control. A value of zero specifies the topmost line. This parameter is ignored by a single-line edit control.

lpch

Value of lParam. Points to the buffer that receives a copy of the line. The first word of the buffer specifies the maximum number of characters that can be copied to the buffer.

Return Values

The return value is the number of characters copied. The return value is zero if the line number specified by the line parameter is greater than the number of lines in the edit control.

Remarks

The copied line does not contain a terminating null character.

See Also

EM_LINELENGTH, WM_GETTEXT


EM_GETLINECOUNT

An application sends an EM_GETLINECOUNT message to retrieve the number of lines in a multiline edit control.

EM_GETLINECOUNT

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is an integer specifying the number of lines in the multiline edit control. If no text is in the edit control, the return value is 1.

See Also

EM_GETLINE, EM_LINELENGTH


EM_GETMARGINS

An application sends the EM_GETMARGINS message to retrieve the widths of the left and right margins for an edit control.

EM_GETMARGINS

wParam = 0;  // not used, must be zero

lParam = 0;  // not used, must be zero

Parameters

This message has no parameters.

Return Values

Returns the width of the left margin in the low-order word, and the width of the right margin in the high-order word.

See Also

EM_SETMARGINS


EM_GETMODIFY

An application sends an EM_GETMODIFY message to determine whether the content of an edit control has been modified.

EM_GETMODIFY

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

If the content of edit control has been modified, the return value is TRUE; otherwise, it is FALSE.

Remarks

Windows maintains an internal flag indicating whether the content of the edit control has been changed. This flag is cleared when the edit control is first created; alternatively, an application can send an EM_SETMODIFY message to the edit control to clear the flag.

See Also

EM_SETMODIFY


EM_GETOLEINTERFACE

The EM_GETOLEINTERFACE message retrieves an IRichEditOle object that a client can use to access a rich edit control’s OLE functionality.

EM_GETOLEINTERFACE

wParam = 0;

lParam = (LPARAM) (LPVOID FAR *) ppObject;

Parameters

ppObject

Address at which the control stores a pointer to the IRichEditOle object. The control calls the AddRef function for the object before returning, so the calling application must call the Release function when it is done with the object.

Return Values

Returns a nonzero value if successful, or zero otherwise.

See Also

IRichEditOle


EM_GETOPTIONS

Retrieves the rich edit control options.

EM_GETOPTIONS
wParam = (WPARAM) 0;
lParam = (LPARAM) 0;

Return Values

Returns the current option values. Can be a combination of values described for the EM_SETOPTIONS message.

See Also

EM_SETOPTIONS


EM_GETPARAFORMAT

The EM_GETPARAFORMAT message retrieves the paragraph formatting of the current selection in a rich edit control.

EM_GETPARAFORMAT

wParam = 0;

lParam = (LPARAM) (PARAFORMAT FAR *) lpFmt;

Parameters

lpFmt

Pointer to a PARAFORMAT structure that receives the paragraph formatting attributes of the current selection.

If more than one paragraph is selected, the structure receives the attributes of the first paragraph, and the dwMask member specifies which attributes are consistent throughout the entire selection.

Return Values

Returns the value of the dwMask member of the PARAFORMAT structure.

See Also

PARAFORMAT


EM_GETPASSWORDCHAR

An application sends an EM_GETPASSWORDCHAR message to retrieve the password character displayed in an edit control when the user enters text.

EM_GETPASSWORDCHAR

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value specifies the character to be displayed in place of the character typed by the user. The return value is NULL if no password character exists.

Remarks

If the edit control is created with the ES_PASSWORD style, the default password character is set to an asterisk (*).

See Also

EM_SETPASSWORDCHAR


EM_GETPUNCTUATION

Gets the current punctuation characters for the rich edit control. This message is available only in Asian-language versions of the operating system.

EM_GETPUNCTUATION
wParam = (WPARAM) (UINT) fType;
lParam = (LPARAM) (PUNCTUATION FAR *) punctTable;

Parameters

fType

Punctuation type flag. Can be one of the following values:

Value	Meaning
PC_LEADING	Leading punctuation characters
PC_FOLLOWING	Following punctuation characters
PC_DELIMITER	Delimiter
The PC_OVERFLOW value is not supported.

punctTable

Address of a PUNCTUATION structure that receives the punctuation characters.

Return Values

Returns nonzero if successful; zero otherwise.

See Also

PUNCTUATION


EM_GETRECT

An application sends an EM_GETRECT message to retrieve the formatting rectangle of an edit control. The formatting rectangle is the limiting rectangle of the text. The limiting rectangle is independent of the size of the edit-control window.

EM_GETRECT

wParam = 0;                    // not used; must be zero

lParam (LPARAM) (LPRECT) lprc; // address of structure for rectangle

Parameters

lprc

Value of lParam. Points to the RECT structure that receives the formatting rectangle.

Return Values

The return value is not a meaningful value.

Remarks

You can modify the formatting rectangle of a multiline edit control by using the EM_SETRECT and EM_SETRECTNP messages.

See Also

EM_SETRECT, EM_SETRECTNP, RECT


EM_GETSEL

An application sends an EM_GETSEL message to get the starting and ending character positions of the current selection in an edit control.

EM_GETSEL

wParam = (WPARAM) (LPDWORD) lpdwStart; // receives starting position

lParam = (LPARAM) (LPDWORD) lpdwEnd;   // receives ending position

Parameters

lpdwStart

Value of wParam. Points to a 32-bit value that receives the starting position of the selection. This parameter can be NULL.

lpdwEnd

Value of lParam. Points to a 32-bit value that receives the position of the first nonselected character after the end of the selection. This parameter can be NULL.

Return Values

The return value is a zero-based 32-bit value with the starting position of the selection in the low-order word and the position of the first character after the last selected character in the high-order word. If either of these values exceeds 65, 535, the return value is -1.

Remarks

In a rich edit control, if the selection is not entirely contained in the first 64K, use the message EM_EXGETSEL.

See Also

EM_EXGETSEL, EM_SETSEL


EM_GETSELTEXT

The EM_GETSELTEXT message retrieves the currently selected text in a rich edit control.

EM_GETSELTEXT

wParam = 0;

lParam = (LPARAM) (LPSTR) lpBuf;

Parameters

lpBuf

Pointer to a buffer that receives the selected text. The calling application must ensure that the buffer is large enough to hold the selected text.

Return Values

Returns the number of characters copied, not including the terminating null character.


EM_GETTEXTRANGE

The EM_GETTEXTRANGE message retrieves a specified range of characters from a rich edit control.

EM_GETTEXTRANGE

wParam = 0;

lParam = (LPARAM) (TEXTRANGE FAR *) lpRange;

Parameters

lpRange

Pointer to a TEXTRANGE structure that specifies the range of characters to retrieve and a buffer to copy the characters to.

Return Values

Returns the number of characters copied, not including the terminating null character.

See Also

TEXTRANGE


EM_GETTHUMB

An application sends the EM_GETTHUMB message to retrieve the position of the scroll box (thumb) in a multiline edit control.

EM_GETTHUMB

wParam = 0;  // not used, must be zero

lParam = 0;  // not used, must be zero

Parameters

This message has no parameters.

Return Values

The return value is the position of the scroll box.


EM_GETWORDBREAKPROC

An application sends an EM_GETWORDBREAKPROC message to an edit control to retrieve the address of the current wordwrap function.

EM_GETWORDBREAKPROC

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value specifies the address of the application-defined wordwrap function. The return value is NULL if no wordwrap function exists.

Remarks

A wordwrap function scans a text buffer that contains text to be sent to the display, looking for the first word that does not fit on the current display line. The wordwrap function places this word at the beginning of the next line on the display. A wordwrap function defines the point at which Windows should break a line of text for multiline edit controls, usually at a space character that separates two words.

See Also

EditWordBreakProc, EM_FMTLINES, EM_SETWORDBREAKPROC


EM_GETWORDBREAKPROCEX

Retrieves the address of the currently registered extended word break procedure.

EM_GETWORDBREAKPROCEX
wParam = (WPARAM) 0;
lParam = (LPARAM) 0;

Return Values

Returns the address of the current procedure.


EM_GETWORDWRAPMODE

Gets the current word wrapping and word breaking options for the rich edit control. This message is available only in Asian-language versions of the operating system.

EM_GETWORDWRAPMODE
wParam = (WPARAM) 0;
lParam = (LPARAM) 0:

Return Values

Returns the current word wrapping and word breaking options.

Remarks

This message must not be sent by the application-defined word breaking procedure.


EM_HIDESELECTION

The EM_HIDESELECTION message hides or shows the selection in a rich edit control.

EM_HIDESELECTION

wParam = (WPARAM) (BOOL) fHide;

lParam = (LPARAM) (BOOL) fChangeStyle;

Parameters

fHide

Value specifying whether to hide or show the selection. If this parameter is zero, the selection is shown. Otherwise, the selection is hidden.

fChangeStyle

Value specifying whether to change the control’s ES_NOHIDESEL window style. If this parameter is zero, the selection is temporarily shown or hidden. Otherwise, the style is changed.

If this parameter is nonzero and the control has the focus, the selection is hidden or shown as appropriate.

Return Values

No return value.


EM_LIMITTEXT

An application sends an EM_LIMITTEXT message to limit the amount of text the user may enter into an edit control.

EM_LIMITTEXT

wParam = (WPARAM) cchMax;   // text length, in characters

lParam = 0;                 // not used; must be zero

Parameters

cchMax

Value of wParam. Specifies the maximum number of characters the user can enter. If this parameter is zero, the text length is set to 0x7FFFFFFE characters for single-line edit controls or 0xFFFFFFFF for multiline edit controls.

Return Values

This message does not return a value.

Remarks

The EM_LIMITTEXT message limits only the text the user can enter. It has no effect on any text already in the edit control when the message is sent, nor does it affect the length of the text copied to the edit control by the WM_SETTEXT message. If an application uses the WM_SETTEXT message to place more text into an edit control than is specified in the EM_LIMITTEXT message, the user can edit the entire contents of the edit control.

The default limit to the amount of text a user can enter in an edit control is 30,000 characters.

In a rich edit control, use the message EM_EXLIMITTEXT for text length values greater than 64K.

See Also

EM_EXLIMITTEXT, WM_SETTEXT


EM_LINEFROMCHAR

An application sends an EM_LINEFROMCHAR message to retrieve the index of the line that contains the specified character index in a multiline edit control. A character index is the number of characters from the beginning of the edit control.

EM_LINEFROMCHAR

wParam = (WPARAM) ich;  // character index

lParam = 0;             // not used; must be zero

Parameters

ich

Value of wParam. Specifies the character index of the character contained in the line whose number is to be retrieved. If the ich parameter is −1, either the line number of the current line (the line containing the caret) is retrieved or, if there is a selection, the line number of the line containing the beginning of the selection is retrieved.

Return Values

The return value is the zero-based line number of the line containing the character index specified by ich.

Remarks

In a rich edit control, if the character index is greater than 64K, use the message EM_EXLINEFROMCHAR.

See Also

EM_EXLINEFROMCHAR, EM_LINEINDEX


EM_LINEINDEX

An application sends an EM_LINEINDEX message to retrieve the character index of a line in a multiline edit control. The character index is the number of characters from the beginning of the edit control to the specified line.

EM_LINEINDEX

wParam = (WPARAM) line; // line number

lParam = 0;             // not used; must be zero

Parameters

line

Value of wParam. Specifies the zero-based line number. A value of −1 specifies the current line number (the line that contains the caret).

Return Values

The return value is the character index of the line specified in the line parameter, or it is −1 if the specified line number is greater than the number of lines in the edit control.

See Also

EM_LINEFROMCHAR


EM_LINELENGTH

An application sends an EM_LINELENGTH message to retrieve the length of a line, in characters, in an edit control.

EM_LINELENGTH

wParam = (WPARAM) ich;  // character index

lParam = 0;             // not used; must be zero

Parameters

ich

Value of wParam. Specifies the character index of a character in the line whose length is to be retrieved when EM_LINELENGTH is sent to a multiline edit control. If this parameter is −1, the message returns the number of unselected characters on lines containing selected characters. For example, if the selection extended from the fourth character of one line through the eighth character from the end of the next line, the return value would be 10 (three characters on the first line and seven on the next).

Return Values

The return value is the length, in characters, of the line specified by the ich parameter when an EM_LINELENGTH message is sent to a multiline edit control. The return value is the length, in characters, of the text in the edit control when an EM_LINELENGTH message is sent to a single-line edit control.

Remarks

Use the EM_LINEINDEX message to retrieve a character index for a given line number within a multiline edit control.

See Also

EM_LINEINDEX


EM_LINESCROLL

An application sends an EM_LINESCROLL message to scroll the text vertically or horizontally in a multiline edit control.

EM_LINESCROLL

wParam = (WPARAM) cxScroll; // characters to scroll horizontally

lParam = (LPARAM) cyScroll; // lines to scroll vertically

Parameters

cxScroll

Value of wParam. Specifies the number of characters to scroll horizontally.

cyScroll

Value of lParam. Specifies the number of lines to scroll vertically.

Return Values

If the message is sent to a multiline edit control, the return value is TRUE; if the message is sent to a single-line edit control, the return value is FALSE.

Remarks

The edit control does not scroll vertically past the last line of text in the edit control. If the current line plus the number of lines specified by the cyScroll parameter exceeds the total number of lines in the edit control, the value is adjusted so that the last line of the edit control is scrolled to the top of the edit-control window.

The EM_LINESCROLL message can be used to scroll horizontally past the last character of any line.


EM_PASTESPECIAL

The EM_PASTESPECIAL message pastes a specific clipboard format in a rich edit control.

EM_PASTESPECIAL

wParam = (WPARAM) (UINT) uFormat;

lParam = (REPASTESPECIAL FAR *) lpRePasteSpecial;

Parameters

uFormat

Clipboard format to paste. For a list of clipboard formats, see SetClipboardData.

lpRePasteSpecial

The address of a REPASTESPECIAL structure or NULL. If an object is being pasted in, the REPASTESPECIAL structure is filled in with the desired display aspect. If lParam is NULL or REPASTESPECIAL.dwAspect is zero, the display aspect used will be the contents of the object descriptor.

Return Values

No return value.

See Also

REPASTESPECIAL, SetClipboardData


EM_POSFROMCHAR

An application sends the EM_POSFROMCHAR message to retrieve the coordinates of the specified character in an edit control.

EM_POSFROMCHAR

wParam = (LPPOINT) lpPoint;        // address of structure

                                   // receiving character position

lParam = (LPARAM) wCharIndex;      // zero-based index of character

Parameters

lpPoint

Value of wParam. Address of a POINT structure that receives the coordinates of the specified character. The coordinates in the structure locate the upper-left corner of the character. If the wCharIndex is greater than the index of the last character in the control, the returned coordinates are of the position just past the last character of the control. The coordinates are relative to the upper-left corner of the edit control’s client area.

wCharIndex

Value of lParam. Specifies the zero-based index of the character.

Return Value

This message does not return a value.

Remarks

For a single-line edit control, the y-coordinate is always zero. A returned coordinate can be negative if the character has been scrolled outside the edit control’s client area. The coordinates are truncated to integer values.

See Also

EM_CHARFROMPOS


EM_REPLACESEL

An application sends an EM_REPLACESEL message to replace the current selection in an edit control with the specified text.

EM_REPLACESEL

fCanUndo = (BOOL) wParam ;        // flag that specifies whether replacement can be undone

lpszReplace = (LPCTSTR) lParam ;  // pointer to replacement text string

Parameters

fCanUndo

Value of wParam. Specifies whether the replacement operation can be undone. If this is TRUE, the operation can be undone. If this is FALSE , the operation cannot be undone.

lpszReplace

Value of lParam. Points to a null-terminated string containing the replacement text.

Return Values

This message does not return a value.

Remarks

Use the EM_REPLACESEL message to replace only a portion of the text in an edit control. To replace all of the text, use the WM_SETTEXT message.

If there is no current selection, the replacement text is inserted at the current location of the caret.

See Also

WM_SETTEXT


EM_REQUESTRESIZE

The EM_REQUESTRESIZE message forces a rich edit control to send an EN_REQUESTRESIZE notification message to its parent window.

EM_REQUESTRESIZE

wParam = 0;

lParam = 0;

Return Values

No return value.

Remarks

This message is useful during WM_SIZE processing for the parent of a bottomless rich edit control.

See Also

EN_REQUESTRESIZE, WM_SIZE


EM_SCROLL

An application sends an EM_SCROLL message to scroll the text vertically in a multiline edit control. This message is equivalent to sending a WM_VSCROLL message to the edit control.

EM_SCROLL

wParam = (WPARAM) (INT) nScroll;    // scroll action

lParam = 0;                         // not used; must be zero

Parameters

nScroll

Value of wParam. Specifies the action the scroll bar is to take. This parameter may be one of the following values:

Value	Meaning
SB_LINEDOWN	Scrolls down one line.
SB_LINEUP	Scrolls up one line.
SB_PAGEDOWN	Scrolls down one page.
SB_PAGEUP	Scrolls up one page.
Return Values

If the message is successful, the high-order word of the return value is TRUE, and the low-order word is the number of lines that the command scrolls. The number returned may not be the same as the actual number of lines scrolled if the scrolling moves to the beginning or the end of the text. If the nScroll parameter specifies an invalid value, the return value is FALSE.

Remarks

An application should use the EM_LINESCROLL message to scroll to a specific line or character position.

An application should use the EM_SCROLLCARET message to scroll the caret into view.

See Also

EM_LINESCROLL, EM_SCROLLCARET, WM_VSCROLL


EM_SCROLLCARET

An application sends an EM_SCROLLCARET message to scroll the caret into view in an edit control.

EM_SCROLLCARET

wParam = 0 ;    // not used now; reserved for future use; must be zero

lParam = 0 ;    // not used now; reserved for future use;  must be zero

Parameters

wParam

This parameter is currently unused. It is reserved for future use. It should be set to zero.

lParam

This parameter is currently unused. It is reserved for future use. It should be set to zero.

Return Values

The return value is nonzero if the message is sent to an edit control.

Remarks

In previous versions of Windows, scrolling the caret into view was done by specifying wParam = FALSE in the EM_SETSEL message. A Win32-based application should use the EM_SCROLLCARET message to scroll the caret into view.

See Also

EM_SETSEL


EM_SELECTIONTYPE

The EM_SELECTIONTYPE message determines the selection type for a rich edit control.

EM_SELECTIONTYPE

wParam = 0;

lParam = 0;

Return Values

Returns SEL_EMPTY if the selection is empty, or one or more of the following values:

Value	Contents of the selection
SEL_TEXT	Text
SEL_OBJECT	At least one OLE object
SEL_MULTICHAR	More than one character of text
SEL_MULTIOBJECT	More than one OLE object
Remarks

This message is useful during WM_SIZE processing for the parent of a bottomless rich edit control.

See Also

WM_SIZE


EM_SETBKGNDCOLOR

The EM_SETBKGNDCOLOR message sets the background color for a rich edit control.

EM_SETBKGNDCOLOR

wParam = (WPARAM) (BOOL) fUseSysColor;

lParam = (LPARAM) (COLORREF) clr;

Parameters

fUseSysColor

Value specifying whether to use the system color. If this parameter is nonzero, the background is set to the window background system color. Otherwise, the background is set to the specified color.

clr

COLORREF structure specifying the color if fUseSysColor is zero.

Return Values

Returns the old background color.

See Also

COLORREF


EM_SETCHARFORMAT

The EM_SETCHARFORMAT message sets character formatting in a rich edit control.

EM_SETCHARFORMAT

wParam = (WPARAM) (UINT) uFlags;

lParam = (LPARAM) (CHARFORMAT FAR *) lpFmt;

Parameters

uFlags

Character formatting that applies to the control. If this parameter is zero, the default character format is set. Otherwise, it can be one of the following values:

Value	Meaning
SCF_ALL	Applies the formatting to all text in the control.
SCF_SELECTION	Applies the formatting to the current selection. If the selection is empty, the character formatting is applied to the insertion point, and the new character format is in effect only until the insertion point changes.
SCF_WORD | SCF_SELECTION	Applies the formatting to the selected word or words. If the selection is empty but the insertion point is inside a word, the formatting is applied to the word. The SCF_WORD value must be used in conjunction with the SCF_SELECTION value.
lpFmt

Pointer to a CHARFORMAT structure specifying the character formatting to use. Only the formatting attributes specified by the dwMask member are changed.

Return Values

Returns a nonzero value if successful or zero otherwise.

See Also

CHARFORMAT


EM_SETEVENTMASK

The EM_SETEVENTMASK message sets the event mask for a rich edit control. The event mask specifies which notification messages the control sends to its parent window.

EM_SETEVENTMASK

wParam = 0;

lParam = (LPARAM) (DWORD) dwMask;

Parameters

dwMask

New event mask for the rich edit control.

Return Values

Returns the previous event mask.

Remarks

The default event mask (before any is set) is ENM_NONE.


EM_SETHANDLE

An application sends an EM_SETHANDLE message to set the handle of the memory that will be used by a multiline edit control.

EM_SETHANDLE

wParam = (WPARAM) (HLOCAL) hloc; // handle of memory buffer

lParam = 0;                      // not used; must be zero

Parameters

hloc

Value of wParam. Identifies the memory the edit control uses to store the currently displayed text instead of allocating its own memory. If necessary, the control reallocates this memory.

Return Values

This message does not return a value.

Remarks

Before an application sets a new memory handle, it should send an EM_GETHANDLE message to retrieve the handle of the current memory buffer and should free that memory.

An edit control automatically reallocates the given buffer whenever it needs additional space for text, or it removes enough text so that additional space is no longer needed.

Sending an EM_SETHANDLE message clears the undo buffer (EM_CANUNDO returns zero) and the internal modification flag (EM_GETMODIFY returns zero). The edit control window is redrawn.

An application can send this message to a multiline edit control in a dialog box only if it has created the dialog box with the DS_LOCALEDIT style flag set.

See Also

EM_CANUNDO, EM_GETHANDLE, EM_GETMODIFY


EM_SETIMECOLOR

Sets the IME composition color. This message is available only in Asian-language versions of the operating system.

EM_SETIMECOLOR
wParam = (WPARAM) 0;
lParam = (LPARAM) (COMPCOLOR *) aCompColor;

Parameters

aCompColor

Address of a four-element array of COMPCOLOR structures that contains the composition color to be set.

Return Values

Returns nonzero if successful, zero otherwise.

See Also

EM_GETIMECOLOR, COMPCOLOR


EM_SETIMEOPTIONS

Sets the IME options. This message is available only in Asian-language versions of the operating system.

EM_SETIMEOPTIONS
wParam = (WPARAM) (UINT) fOperation;
lParam = (LPARAM) (int) fOptions;

Parameters

fOperation

Operation flag. Can be one of the following values:

ECOOP_SET	Set the options to those specified by fOptions.
ECOOP_OR	Combine the specified options with the current options.
ECOOP_AND	Retain only those current options that are also specified by fOptions.
ECOOP_XOR	Logically Exclusive OR the current options with those specified by fOptions.
fOptions

IME option flag. Can be a combination of the following values:

IMF_CLOSESTATUSWINDOW	Closes the IME status window when the control receives the input focus.
IMF_FORCEACTIVE	Activates the IME when the control receives the input focus.
IMF_FORCEDISABLE	Disables the IME when the control receives the input focus.
IMF_FORCEENABLE	Enables the IME when the control receives the input focus.
IMF_FORCEINACTIVE	Inactivates the IME when the control receives the input focus.
IMF_FORCENONE	Disables IME handling.
IMF_FORCEREMEMBER	Restores the previous IME status when the control receives the input focus.
IMF_MULTIPLEEDIT	Specifies that the composition string will not be canceled or determined by focus changes. This allows an application to have separate comosition strings on each rich edit control.
Return Values

Returns nonzero if successful, zero otherwise.

See Also

EM_GETIMEOPTIONS


EM_SETLIMITTEXT

An application sends the EM_SETLIMITTEXT message to set the text limit for an edit control. The text limit is the maximum amount of text, in bytes, that the edit control can contain.

EM_SETLIMITTEXT

wParam = (WPARAM) cbMax;    // new text limits, in bytes

lParam = 0;                 // not used, must be zero

Parameters

cbMax

Value of wParam. Specifies the new text limit, in bytes. If this parameter is 0, Windows sets the maximum text limit. The maximum text limit is 32,766 bytes for a single-line edit control, and 65,535 bytes for a multiline edit control.

Return Values

This message does not return a value.

Remarks

The EM_SETLIMITTEXT message replaces the EM_LIMITTEXT message.

See Also

EM_GETLIMITTEXT


EM_SETMARGINS

An application sends the EM_SETMARGINS message to set the widths of the left and right margins for an edit control. The message redraws the control to reflect the new margins.

EM_SETMARGINS

wParam = (WPARAM) fwMargin;                    // left and/or right margins

lParam = (LPARAM) MAKELONG(wLeft, wRight);     // width of left or right margins, in pixels

Parameters

fwMargin

Value of wParam. Specifies the margins to set. This parameter can be a combination of the following values:

Value	Meaning
EC_LEFTMARGIN	Sets the left margin.
EC_RIGHTMARGIN	Sets the right margin.
EC_USEFONTINFO	Uses information about the current font of the edit control to set the margins. For a single-line edit control, margins are set to the average width of characters in the font. For a multiline edit control, the right margin is set to the “A” width of the font (the distance added to the current position before drawing a character), and the left margin is set to the “C” width (the distance added to the current position to provide white space to the right of a character).
If EC_USEFONTINFO is specified, the lParam parameter is ignored.

wLeft

Value of the low-order word of lParam. Specifies the width of the left margin, in pixels. This value is ignored if fwMargin does not include EC_LEFTMARGIN or if EC_USEFONTINFO is specified.

wRight

Value of the high-order word of lParam. Specifies the width of the right margin, in pixels. This value is ignored if fwMargin does not include EC_RIGHTMARGIN or if EC_USEFONTINFO is specified.

Return Values

This message does not return a value.

See Also

EM_GETMARGINS


EM_SETMODIFY

An application sends an EM_SETMODIFY message to set or clear the modification flag for an edit control. The modification flag indicates whether the text within the edit control has been modified. It is automatically set whenever the user changes the text. An EM_GETMODIFY message can be sent to retrieve the value of the modification flag.

EM_SETMODIFY

wParam = (WPARAM) (UINT) fModified;    // modification flag

lParam = 0;                            // not used; must be zero

Parameters

fModified

Value of wParam. Specifies the new value for the modification flag. A value of TRUE indicates the text has been modified, and a value of FALSE indicates it has not been modified.

Return Values

This message does not return a value.

Remarks

In a rich edit control, objects created without the REO_DYNAMICSIZE flag will lock in their extents when the modify flag is set to FALSE.

See Also

EM_GETMODIFY, REOBJECT


EM_SETOLEINTERFACE

The EM_SETOLEINTERFACE message gives a rich edit control an IRichEditOleCallback object that the control uses to get OLE-related resources and information from the client.

EM_SETOLEINTERFACE

wParam = 0;

lParam = (LPARAM) (IRichEditOleCallback FAR *) lpObj;

Parameters

lpObj

Pointer to an IRichEditOleCallback object. The control calls the AddRef function for the object before returning.

Return Values

Returns a nonzero value if successful or zero otherwise.


EM_SETOPTIONS

Sets the options for a rich edit control.

EM_SETOPTIONS
wParam = (WPARAM) (UINT) fOperation;
lParam = (LPARAM) (UINT) fOptions;

Parameters

fOperation

Operation flag. Can be one of these values:

ECOOP_SET	Set the options to those specified by fOptions.
ECOOP_OR	Combine the specified options with the current options.
ECOOP_AND	Retain only those current options that are also specified by fOptions.
ECOOP_XOR	Logically Exclusive OR the current options with those specified by fOptions.
fOptions

Rich edit control options. Can be a combination of these values:

Value	Meaning
ECO_AUTOWORDSELECTION	Automatic selection of word on doubleclick.
ECO_AUTOVSCROLL	Same as ES_AUTOVSCROLL style.
ECO_AUTOHSCROLL	Same as ES_AUTOHSCROLL style.
ECO_NOHIDESEL	Same as ES_NOHIDESEL style.
ECO_READONLY	Same as ES_READONLY style.
ECO_WANTRETURN	Same as ES_WANTRETURN style.
ECO_SAVESEL	Same as ES_SAVESEL style.
ECO_SELECTIONBAR	Same as ES_SELECTIONBAR style.
ECO_VERTICAL	Same as ES_VERTICAL style. Available in Asian-language versions only.
Return Values

Returns current option of edit control.


EM_SETPARAFORMAT

The EM_SETPARAFORMAT message sets the paragraph formatting for the current selection in a rich edit control.

EM_SETPARAFORMAT

wParam = 0;  // not used; must be zero

lParam = (LPARAM) (PARAFORMAT FAR *) lpFmt;

Parameters

lpFmt

Pointer to a PARAFORMAT structure specifying the new paragraph formatting attributes. Only the attributes specified by the dwMask member are changed.

Return Values

Returns a nonzero value if successful, or zero otherwise.

See Also

PARAFORMAT


EM_SETPASSWORDCHAR

An application sends an EM_SETPASSWORDCHAR message to set or remove the password character for a single-line edit control when the user types text. When a password character is set, that character is displayed in place of each character the user types.

EM_SETPASSWORDCHAR

wParam = (WPARAM) (UINT) ch;    // character to display

lParam = 0;                     // not used; must be zero

Parameters

ch

Value of wParam. Specifies the character to be displayed in place of the character typed by the user. If this parameter is zero, the characters typed by the user are displayed.

Return Values

This message does not return a value.

Remarks

When the EM_SETPASSWORDCHAR message is received by an edit control, the edit control redraws all visible characters by using the character specified by the ch parameter.

If the edit control is created with the ES_PASSWORD style, the default password character is set to an asterisk (*). This style is removed if an EM_SETPASSWORDCHAR message is sent with the ch parameter set to zero.

See Also

EM_GETPASSWORDCHAR


EM_SETPUNCTUATION

Sets the punctuation characters for a rich edit control. This message is available only in Asian-language versions of the operating system.

EM_SETPUNCTUATION
wParam = (WPARAM) (UINT) fType;
lParam = (LPARAM) (PUNCTUATION FAR *) punctTable;

Parameters

fType

Punctuation type flag. Can be one of the following values:

Value	Meaning
PC_LEADING	Leading punctuation characters.
PC_FOLLOWING	Following punctuation characters.
PC_DELIMITER	Delimiter.
The PC_OVERFLOW value is not supported.

punctTable

Address of a PUNCTUATION structure that contains the punctuation characters.

Return Values

Returns nonzero if successful; zero otherwise.

See Also

PUNCTUATION


EM_SETREADONLY

An application sends an EM_SETREADONLY message to set or remove the read-only style (ES_READONLY) of an edit control.

EM_SETREADONLY

wParam = (WPARAM) (BOOL) fReadOnly;  // read-only flag

lParam = 0;                          // not used; must be zero

Parameters

fReadOnly

Value of wParam. Specifies whether to set or remove the ES_READONLY style. A value of TRUE sets the ES_READONLY style; a value of FALSE removes the ES_READONLY style.

Return Values

If the operation succeeds, the return value is nonzero; otherwise, it is zero.

Remarks

When an edit control has the ES_READONLY style, the user cannot change the text within the edit control.

To determine whether an edit control has the ES_READONLY style, use the GetWindowLong function with the GWL_STYLE flag.

See Also

GetWindowLong


EM_SETRECT

An application sends an EM_SETRECT message to set the formatting rectangle of a multiline edit control. The formatting rectangle is the limiting rectangle of the text. The limiting rectangle is independent of the size of the edit control window. When the edit control is first created, the formatting rectangle is the same as the client area of the edit control window. By using the EM_SETRECT message, an application can make the formatting rectangle larger or smaller than the edit control window.

This message is processed only by multiline edit controls.

EM_SETRECT

wParam = 0;                         // not used; must be zero

lParam = (LPARAM) (LPRECT) lprc;    // address of new rectangle

Parameters

lprc

Value of lParam. Points to a RECT structure that specifies the new dimensions of the rectangle.

Return Values

This message does not return a value.

Remarks

The EM_SETRECT message causes the text of the edit control to be redrawn. To change the size of the formatting rectangle without redrawing the text, use the EM_SETRECTNP message.

If the edit control does not have a horizontal scroll bar, and the formatting rectangle is set to be larger than the edit control window, lines of text exceeding the width of the edit control window (but smaller than the width of the formatting rectangle) are clipped instead of wrapped.

If the edit control contains a border, the formatting rectangle is reduced by the size of the border. If you are adjusting the rectangle returned by an EM_GETRECT message, you must remove the size of the border before using the rectangle with the EM_SETRECT message.

See Also

EM_GETRECT, EM_SETRECTNP, RECT


EM_SETRECTNP

An application sends an EM_SETRECTNP message to set the formatting rectangle of a multiline edit control. The formatting rectangle is the limiting rectangle of the text. The limiting rectangle is independent of the size of the edit control window. When the edit control is first created, the formatting rectangle is the same as the client area of the edit control window. By using the EM_SETRECTNP message, an application can make the formatting rectangle larger or smaller than the edit control window.

The EM_SETRECTNP message is identical to the EM_SETRECT message, except that the edit control window is not redrawn.

This message is processed only by multiline edit controls.

EM_SETRECTNP

wParam = 0;                         // not used; must be zero

lParam = (LPARAM) (LPRECT) lprc;    // address of new rectangle

Parameters

lprc

Value of lParam. Points to a RECT structure that specifies the new dimensions of the rectangle.

Return Values

This message does not return a value.

See Also

EM_SETRECT, RECT


EM_SETSEL

An application sends an EM_SETSEL message to select a range of characters in an edit control.

EM_SETSEL

wParam = (WPARAM) (INT) nStart;    // starting position

lParam = (LPARAM) (INT) nEnd;      // ending position

Parameters

nStart

Value of wParam. Specifies the starting character position of the selection.

nEnd

Specifies the ending character position of the selection.

Return Values

This message does not return a value.

Remarks

In a rich edit control, if the selection is not entirely contained in the first 64K, use the message EM_EXSETSEL.

If the nStart parameter is 0 and the nEnd parameter is −1, all the text in the edit control is selected. If nStart is −1, any current selection is removed. The caret is placed at the end of the selection indicated by the greater of the two values nEnd and nStart.

In previous versions of Windows, the wParam parameter is a flag that is set to FALSE to scroll the caret into view or set to TRUE to omit the scrolling. A Win32-based application should use the EM_SCROLLCARET message to scroll the caret into view.

In earlier versions of Windows, the starting and ending positions of the selection are indicated by the low- and high-order words, respectively, of the lParam parameter.

See Also

EM_GETSEL, EM_REPLACESEL, EM_SCROLLCARET, EM_EXSETSEL


EM_SETTABSTOPS

An application sends an EM_SETTABSTOPS message to set the tab stops in a multiline edit control. When text is copied to the control, any tab character in the text causes space to be generated up to the next tab stop.

This message is processed only by multiline edit controls.

EM_SETTABSTOPS

wParam = (WPARAM) cTabs;               // number of tab stops

lParam = (LPARAM) (LPDWORD) lpdwTabs;  // tab stop array

Parameters

cTabs

Value of wParam. Specifies the number of tab stops contained in the lpdwTabs parameter. If this parameter is zero, the lpdwTabs parameter is ignored and default tab stops are set at every 32 dialog box units. If this parameter is 1, tab stops are set at every n dialog box units, where n is the distance pointed to by the ldpwTabs parameter. If the cTabs parameter is greater than 1, lpdwTabs points to an array of tab stops.

lpdwTabs

Value of lParam. Points to an array of unsigned integers specifying the tab stops, in dialog units. If the cTabs parameter is 1, lpdwTabs points to an unsigned integer containing the distance between all tab stops, in dialog box units.

Return Values

If all the tabs are set, the return value is TRUE; otherwise, it is FALSE.

Remarks

The EM_SETTABSTOPS message does not automatically redraw the edit control window. If the application is changing the tab stops for text already in the edit control, it should call the InvalidateRect function to redraw the edit control window.

See Also

GetDialogBaseUnits, InvalidateRect


EM_SETTARGETDEVICE

The EM_SETTARGETDEVICE message sets the target device and line width used for WYSIWYG (what you see is what you get) formatting in a rich edit control.

EM_SETTARGETDEVICE

wParam = (WPARAM) (HDC) hdcTarget;

lParam = (LPARAM) (int) cxLineWidth;

Parameters

hdcTarget

Handle to a device context for the target device.

cxLineWidth

Line width to use for formatting.

Return Values

Returns a nonzero value if successful or zero otherwise.


EM_SETWORDBREAK

The EM_SETWORDBREAK message is not supported. Applications that must replace the default wordwrap function of a multiline edit control with an application-defined wordwrap function should use the EM_SETWORDBREAKPROC message.


EM_SETWORDBREAKPROC

An application sends the EM_SETWORDBREAKPROC message to an edit control to replace the default wordwrap function with an application-defined wordwrap function.

EM_SETWORDBREAKPROC

wParam = 0;                                 // not used; must be zero

lParam = (LPARAM)(EDITWORDBREAKPROC)ewbprc; // function address

Parameters

ewbprc

Value of lParam. Specifies the address of the application-defined wordwrap function. For more information about breaking lines, see the description of the EditWordBreakProc callback function.

Return Values

This message does not return a value.

Remarks

A wordwrap function scans a text buffer that contains text to be sent to the screen, looking for the first word that does not fit on the current screen line. The wordwrap function places this word at the beginning of the next line on the screen.

A wordwrap function defines the point at which Windows should break a line of text for multiline edit controls, usually at a space character that separates two words. Either a multiline or a single-line edit control might call this function when the user presses arrow keys in combination with the CTRL key to move the caret to the next word or previous word. The default wordwrap function breaks a line of text at a space character. The application-defined function may define the wordwrap to occur at a hyphen or a character other than the space character.

See Also

EditWordBreakProc, EM_FMTLINES, EM_GETWORDBREAKPROC


EM_SETWORDBREAKPROCEX

Sets the extended word-break procedure.

EM_SETWORDBREAKPROCEX
wParam = (WPARAM) 0;
lParam = (LPARAM) pfnWordBreakProcEx;

Parameters

pfnWordBreakprocEx

Address of an EditWordBreakProcEx function or NULL to use the default procedure.

Return Values

Returns the address of the previous extended word-break procedure.

See Also

EditWordBreakProcEx, EM_GETWORDBREAKPROCEX


EM_SETWORDWRAPMODE

Sets the word-wrapping and word-breaking options for the rich edit control. This message is available only in Asian-language versions of the operating system.

EM_SETWORDWRAPMODE
wParam = (WPARAM) (UINT) fOptions;
lParam = (LPARAM) 0:

Parameters

fOptions

Options flag. Can be a combination of the following values:

Value	Meaning
WBF_WORDWRAP	Enables Asian-specific word-wrap operation, such as Kinsoku in Japanese.
WBF_WORDBREAK	Enables English word-breaking operation in Japanese and Chinese. Enables Hangeul word-breaking operation.
WBF_OVERFLOW	Recognizes overflow punctuation. (Not currently supported.)
WBF_LEVEL1	Sets level 1 punctuation table as default.
WBF_LEVEL2	Sets level 2 punctuation table as default.
WBF_CUSTOM	Sets application-defined punctuation table.
Return Values

Returns the current word-wrapping and word-breaking options.

Remarks

This message must not be sent by the application-defined word-breaking procedure.


EM_STREAMIN

The EM_STREAMIN message replaces the contents of a rich edit control with the specified data stream.

EM_STREAMIN

wParam = (WPARAM) (UINT) uFormat;

lParam = (LPARAM) (EDITSTREAM FAR *) lpStream;

Parameters

uFormat

One of the following data formats:

Value	Meaning
SF_TEXT	Text
SF_RTF	Rich Text Format (RTF)
Both data formats may be combined with the SFF_SELECTION flag. If the SFF_SELECTION flag is specified, the stream replaces the contents of the current selection. Otherwise, the stream replaces the entire contents of the control.

The SF_RTF format may be combined with the SFF_PLAINRTF flag. If the SFF_PLAINRTF flag is specified, language-specific RTF keywords in the stream are ignored. Only keywords common to all languages are streamed in.

lpStream

Pointer to an EDITSTREAM structure. The control reads (streams in) the data by repeatedly calling the function specified by the structure’s pfnCallback member.

Return Values

Returns the number of characters read.

See Also

EDITSTREAM


EM_STREAMOUT

The EM_STREAMOUT message writes (streams out) the contents of a rich edit control to the specified data stream.

EM_STREAMOUT

wParam = (WPARAM) (UINT) uFormat;

lParam = (LPARAM) (EDITSTREAM FAR *) lpStream;

Parameters

uFormat

Value specifying one of the following data formats:

Value	Meaning
SF_TEXT	Text with spaces in place of OLE objects
SF_RTF	Rich Text Format (RTF)
SF_RTFNOOBJS	RTF with spaces in place of OLE object.
SF_TEXTIZED	Text with a text representation of OLE objects.
The SF_RTFNOOBJS option is useful if an application stores OLE objects itself, as RTF representation of OLE objects is not very compact. The control word \objattph followed by a space denotes the object position.

All data formats may be combined with the SFF_SELECTION flag. If the SFF_SELECTION flag is specified, only the contents of the current selection are streamed out. Otherwise, the entire contents of the control are streamed out.

The SF_RTF and SF_RTFNOOBJS formats may be combined with the SFF_PLAINRTF flag. If the SFF_PLAINRTF flag is specified, language-specific RTF keywords are ignored. Only keywords common to all languages are streamed out.

lpStream

Pointer to an EDITSTREAM structure. The control streams out the data by repeatedly calling the function specified by the structure’s pfnCallback member.

Return Values

Returns the number of characters written to the data stream.

See Also

EDITSTREAM


EM_UNDO

An application sends an EM_UNDO message to undo the last edit control operation.

EM_UNDO

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

For a single-line edit control, the return value is always TRUE. For a multiline edit control, the return value is TRUE if the undo operation is successful, or FALSE if the undo operation fails.

Remarks

An undo operation can also be undone. For example, you can restore deleted text with the first EM_CANUNDO message, and remove the text again with a second EM_CANUNDO message as long as there is no intervening edit operation.

See Also

EM_CANUNDO


EN_CHANGE

The EN_CHANGE notification message is sent when the user has taken an action that may have altered text in an edit control. Unlike the EN_UPDATE notification message, this notification message is sent after Windows updates the screen. The parent window of the edit control receives this notification message through the WM_COMMAND message.

EN_CHANGE

idEditCtrl = (int) LOWORD(wParam); // identifier of edit control

hwndEditCtrl = (HWND) lParam;      // handle of edit control

See Also

EN_UPDATE, WM_COMMAND


EN_CORRECTTEXT

Notifies a rich edit control’s parent window that a SYV_CORRECT gesture occurred. A rich edit control sends this notification message in the form of a WM_NOTIFY message.

EN_CORRECTTEXT
wParam = (WPARAM) (UINT) uID;
lParam = (LPARAM) (ENCORRECTTEXT FAR *) lpEnCorrectText;

Parameters

uID

Identifier of the rich edit control.

lpEnCorrectText

Pointer to an ENCORRECTTEXT structure specifying the selection to be corrected.

Return Values

Returns zero to ignore the action, nonzero to process it.

Remarks

This message is sent only if pen capabilities are available.

See Also

ENCORRECTTEXT, WM_NOTIFY


EN_DROPFILES

The EN_DROPFILE notification message notifies a rich edit control’s parent window that the user is attempting to drop files into the control. A rich edit control sends this notification message in the form of a WM_NOTIFY message when it receives the WM_DROPFILES message.

EN_DROPFILES

wParam = (WPARAM) (UINT) uID;

lParam = (LPARAM) (ENDROPFILES FAR *) lpEnDropFiles;

Parameters

uID

Identifier of the rich edit control.

lpEnDropFiles

Pointer to an ENDROPFILES structure.

Return Values

Returns a nonzero value to allow the drop operation or zero to ignore the drop.

Remarks

For a rich edit control to receive WM_DROPFILES messages, the parent window must register the control as a drop target by using the DragAcceptFiles function. The control does not register itself.

See Also

DragAcceptFiles, ENDROPFILES, WM_DROPFILES, WM_NOTIFY


EN_ERRSPACE

The EN_ERRSPACE notification message is sent when an edit control cannot allocate enough memory to meet a specific request. The parent window of the edit control receives this notification message through the WM_COMMAND message.

EN_ERRSPACE

idEditCtrl = (int) LOWORD(wParam); // identifier of edit control

hwndEditCtrl = (HWND) lParam;      // handle of edit control

See Also

WM_COMMAND


EN_HSCROLL

The EN_HSCROLL notification message is sent when the user clicks an edit control’s horizontal scroll bar. The parent window of the edit control receives this notification message through the WM_COMMAND message. The parent window is notified before the screen is updated.

EN_HSCROLL

idEditCtrl = (int) LOWORD(wParam); // identifier of edit control

hwndEditCtrl = (HWND) lParam;      // handle of edit control

See Also

EN_VSCROLL, WM_COMMAND


EN_IMECHANGE

Notifies a rich edit control’s parent that the IME conversion status has changed. This message is available only for Asian-language versions of the operating system.

EN_IMECHANGE
wParam = (WPARAM) (UINT) uID;
lParam = (LPARAM) 0;

Parameters

uID

Identifier of the rich edit control.

Return Values

Returns zero.


EN_KILLFOCUS

The EN_KILLFOCUS notification message is sent when an edit control loses the keyboard focus. The parent window of the edit control receives this notification message through the WM_COMMAND message.

EN_KILLFOCUS

idEditCtrl = (int) LOWORD(wParam); // identifier of edit control

wNotifyCode = HIWORD(wParam);      // notification code

hwndEditCtrl = (HWND) lParam;      // handle of edit control

Remarks

In previous versions of Windows, the notification code was in HIWORD(lParam).

See Also

EN_SETFOCUS, WM_COMMAND


EN_MAXTEXT

The EN_MAXTEXT notification message is sent when the current text insertion has exceeded the specified number of characters for the edit control. The text insertion has been truncated.

This message is also sent when an edit control does not have the ES_AUTOHSCROLL style and the number of characters to be inserted would exceed the width of the edit control.

This message is also sent when an edit control does not have the ES_AUTOVSCROLL style and the total number of lines resulting from a text insertion would exceed the height of the edit control.

The parent window of the edit control receives this notification message through the WM_COMMAND message.

EN_MAXTEXT

idEditCtrl = (int) LOWORD(wParam); // identifier of edit control

hwndEditCtrl = (HWND) lParam;      // handle of edit control

See Also

WM_COMMAND


EN_MSGFILTER

The EN_MSGFILTER notification message notifies a rich edit control’s parent window of a keyboard or mouse event in the control. A rich edit control sends this notification message in the form of a WM_NOTIFY message.

EN_MSGFILTER

wParam = (WPARAM) (UINT) uID;

lParam = (LPARAM) (MSGFILTER) lpMsgFilter;

Parameters

uID

Identifier of the rich edit control.

lpMsgFilter

Pointer to a MSGFILTER structure containing information about the keyboard or mouse message. If the parent window modifies this structure and returns a nonzero value, the modified message is processed instead of the original one.

Return Values

Returns a nonzero value if the control should process the event, or zero if the control should ignore the event.

See Also

MSGFILTER, WM_NOTIFY


EN_OLEOPFAILED

Notifies a rich edit control’s parent window that a user action on an OLE object has failed.

EN_OLEOPFAILED
wParam = (WPARAM) (UINT) uID;
lParam = (LPARAM) (ENOLEOPFAILED *) lpeoof;

Parameters

uID

Identifier of the rich edit control.

lpeoof

Pointer to an ENOLEOPFAILED structure that contains information about the failure.

Return Values

Returns zero.

ENOLEOPFAILED


EN_PROTECTED

The EN_PROTECTED notification message notifies a rich edit control’s parent window that the user is taking an action that would change a protected range of text. A rich edit control sends this notification message in the form of a WM_NOTIFY message.

EN_PROTECTED

wParam = (WPARAM) (UINT) uID;

lParam = (LPARAM) (ENPROTECTED FAR *) lpEnProtected;

Parameters

uID

Identifier of the rich edit control.

lpEnProtected

Pointer to an ENPROTECTED structure containing information about the message that triggered the notification.

Return Values

Returns zero to allow the operation or a nonzero value to prevent it.

Remarks

If zero is returned and the msg, wParam, and lParam members of the ENPROTECTED structure are changed, the control processes the revised message instead of the original message.

See Also

ENPROTECTED, WM_NOTIFY


EN_REQUESTRESIZE

The EN_REQUESTRESIZE notification message notifies a rich edit control’s parent window that the control’s contents are either smaller or larger than the control’s window size. A rich edit control sends this notification message in the form of a WM_NOTIFY message.

EN_REQUESTRESIZE

wParam = (WPARAM) (UINT) uID;

lParam = (LPARAM) (REQRESIZE FAR *) lpReSize;

Parameters

uID

Identifier of the rich edit control.

lpReSize

Pointer to a REQRESIZE structure.

Return Values

No return value.

Remarks

To support the bottomless behavior of a rich edit control, the parent window must resize the control when it receives this notification message.

See Also

REQRESIZE, WM_NOTIFY


EN_SAVECLIPBOARD

Notifies the rich edit control’s parent window that the control is closing and the clipboard contains information.

EN_SAVECLIPBOARD
wParam = (WPARAM) (UINT) uID;
lParam = (LPARAM) (ENSAVECLIPBOARD *) lpesc;

Parameters

uID

Identifier of the rich edit control.

lpesc

Pointer to an ENSAVECLIPBOARD structure that contains information about clipboard information.

Return Values

Returns zero if the clipboard should be made available to other applications, nonzero if the clipboard should not be saved.

See Also

ENSAVECLIPBOARD


EN_SELCHANGE

The EN_SELCHANGE notification message notifies a rich edit control’s parent window that the current selection has changed. A rich edit control sends this notification message in the form of a WM_NOTIFY message.

EN_SELCHANGE

wParam = (WPARAM) (UINT) uID;

lParam = (LPARAM) (SELCHANGE FAR *) lpSelChange;

Parameters

uID

Identifier of the rich edit control.

lpSelChange

Pointer to a SELCHANGE structure.

Return Values

No return value.

See Also

SELCHANGE, WM_NOTIFY


EN_SETFOCUS

The EN_SETFOCUS notification message is sent when an edit control receives the keyboard focus. The parent window of the edit control receives this notification message through the WM_COMMAND message.

EN_SETFOCUS

idEditCtrl = (int) LOWORD(wParam); // identifier of edit control

wNotifyCode = HIWORD(wParam);      // notification code

hwndEditCtrl = (HWND) lParam;      // handle of edit control

Remarks

In previous versions of Windows, the notification code was in HIWORD(lParam).

See Also

EN_KILLFOCUS, WM_COMMAND


EN_STOPNOUNDO

Notifies a rich edit control’s parent window that an action occurred for which the control cannot allocate enough memory to maintain the undo state. A rich edit control sends this notification message in the form of a WM_NOTIFY message.

EN_STOPNOUNDO
wParam = (WPARAM) (UINT) uID;
lParam = (LPARAM) (NMHDR FAR *) lpNmHdr;

Parameters

uID

Identifier of the rich edit control.

lpNmHdr

Pointer to an NMHDR structure.

Return Values

Returns zero to continue the action, nonzero to stop it.

See Also

NMHDR, WM_NOTIFY


EN_UPDATE

The EN_UPDATE notification message is sent when an edit control is about to display altered text. This notification message is sent after the control has formatted the text, but before it displays the text. This makes it possible to resize the edit control window, if necessary. The parent window of the edit control receives this notification message through the WM_COMMAND message.

EN_UPDATE

idEditCtrl = (int) LOWORD(wParam); // identifier of edit control

hwndEditCtrl = (HWND) lParam;      // handle of edit control

See Also

EN_CHANGE, WM_COMMAND


EN_VSCROLL

The EN_VSCROLL notification message is sent when the user clicks an edit control’s vertical scroll bar. The parent window of the edit control receives this notification message through the WM_COMMAND message. The parent window is notified before the screen is updated.

EN_VSCROLL

idEditCtrl = (int) LOWORD(wParam); // identifier of edit control

hwndEditCtrl = (HWND) lParam;      // handle of edit control

See Also

EN_HSCROLL, WM_COMMAND


FILEOKSTRING

An Open or Save As dialog box sends the FILEOKSTRING registered message to your hook procedure when the user specifies a filename and clicks the OK button. The hook procedure can accept the filename and allow the dialog box to close, or reject the filename and force the dialog box to remain open.

For Explorer-style Open and Save As dialog boxes, this message has been superseded by the CDN_FILEOK notification message.

MessageID = RegisterWindowMessage(FILEOKSTRING);
wParam = 0;
lpofn = (LPOPENFILENAME) lParam;

Parameters

lpofn

Pointer to an OPENFILENAME structure. The lpstrFile member of this structure contains the drive, path, and filename specified by the user.

Return Values

If the hook procedure returns zero, the Open or Save As dialog box accepts the specified filename and closes.

If the hook procedure returns a nonzero value, the Open or Save As dialog box rejects the specified filename and remains open.

Remarks

The hook procedure must specify the FILEOKSTRING constant in a call to the RegisterWindowMessage function to get the identifier for the message sent by the dialog box.

See Also

CDN_FILEOK, OPENFILENAME, RegisterWindowMessage


FINDMSGSTRING

A Find or Replace dialog box sends the FINDMSGSTRING registered message to the window procedure of its owner window when the user clicks the Find Next, Replace, or Replace All button, or closes the dialog box.

MessageID = RegisterWindowMessage(FINDMSGSTRING);
wParam = 0;
lpfr = (LPFINDREPLACE) lParam;

Parameters

lpfr

Pointer to a FINDREPLACE structure. The members of this structure contain the latest user input, including the string to search for, the replacement string (if any) and the search-and-replacement options.

Return Values

No return value.

Remarks

You must specify the FINDMSGSTRING constant in a call to the RegisterWindowMessage function to get the identifier for the message sent by the dialog box.

When you create the dialog box, use the hwndOwner member of the FINDREPLACE structure to identify the window to receive FINDMSGSTRING messages.

The Flags member of the FINDREPLACE structure includes one of the following flags to indicate the event that caused the message:

Flag	Meaning
FR_DIALOGTERM	The dialog box is closing. After the owner window processes this message, the handle of the dialog box is no longer valid.
FR_FINDNEXT	The user clicked the Find Next button in a Find or Replace dialog box. The lpstrFindWhat member specifies the string to search for.
FR_REPLACE	The user clicked the Replace button in a Replace dialog box. The lpstrFindWhat member specifies the string to replace and the lpstrReplaceWith member specifies the replacement string.
FR_REPLACEALL	The user clicked the Replace All button in a Replace dialog box. The lpstrFindWhat member specifies the string to replace and the lpstrReplaceWith member specifies the replacement string.
For a Find Next or Replace All message, the Flags member can include any combination of the following flags to indicate the search options:

Flag	Meaning
FR_DOWN	If set, the Down button of the direction radio buttons is selected indicating that user wants to search from the current location to the end of the document. If FR_DOWN is not set, the Up button is selected so the user wants to search to the beginning of the document.
FR_MATCHCASE	If set, the Match Case check box is checked indicating that the user wants the search to be case-sensitive. If FR_MATCHCASE is not set, the check box is unchecked so the search should be case-insensitive.
FR_WHOLEWORD	If set, the Match Whole Word Only check box is checked indicating that the user wants to search only for whole words that match the search string. If FR_WHOLEWORD is not set, the check box is unchecked so you should also search for word fragments that match the search string.
See Also

FINDREPLACE, RegisterWindowMessage


FM_GETDRIVEINFO

A File Manager extension sends an FM_GETDRIVEINFO message to retrieve drive information from the active File Manager window.

FM_GETDRIVEINFO

wParam = 0;                                        // not used, must be zero

lParam = (LPARAM) (LPFMS_GETDRIVEINFO) lpfmsgdi;   // drive data

Parameters

lpfmsgdi

Value of lParam. Points to an FMS_GETDRIVEINFO structure that receives drive information.

Return Values

The return value is always nonzero.

Remarks

If 0xFFFFFFFF is returned in the dwTotalSpace or dwFreeSpace member of the FMS_GETDRIVEINFO structure, the extension library must compute the value or values.

See Also

FMExtensionProc, FMS_GETDRIVEINFO


FM_GETFILESEL

A File Manager extension sends an FM_GETFILESEL message to retrieve information about a selected file from the active File Manager window (either the directory window or the Search Results window).

FM_GETFILESEL

wParam = (WPARAM) index;                            // index of selected file

lParam = (LPARAM) (LPFMS_GETFILESEL) lpfmsgfs;      // file data

Parameters

index

Value of wParam. Specifies the zero-based index of the selected file to retrieve.

lpfmsgfs

Value of lParam. Points to an FMS_GETFILESEL structure that receives information about the selection.

Return Values

The return value is the zero-based index of the selected file that was retrieved.

Remarks

An extension can use the FM_GETSELCOUNT message to get the count of selected files.

See Also

FMExtensionProc, FMS_GETFILESEL, FM_GETFILESELLFN, FM_GETSELCOUNT, FM_GETSELCOUNTLFN


FM_GETFILESELLFN

A File Manager extension sends an FM_GETFILESELLFN message to retrieve information about a selected file from the active File Manager window (either the directory window or the Search Results window). The selected file can have a long filename.

FM_GETFILESELLFN

wParam = (WPARAM) index;                       // index of selected file

lParam = (LPARAM) (LPFMS_GETFILESEL) lpfmsgfs; // selection data

Parameters

index

Value of wParam. Specifies the zero-based index of the selected file to retrieve.

lpfmsgfs

Value of lParam. Points to an FMS_GETFILESEL structure that receives information about the selection.

Return Values

The return value is the zero-based index of the selected file that was retrieved.

Remarks

Only extensions that support long filenames (for example, network-aware extensions) should use this message.

An extension can use the FM_GETSELCOUNT message to get the count of selected files.

See Also

FMExtensionProc, FM_GETFILESEL, FM_GETSELCOUNT, FM_GETSELCOUNTLFN


FM_GETFOCUS

A File Manager extension sends a FM_GETFOCUS message to retrieve the type of the File Manager window that has the input focus.

FM_GETFOCUS

wParam = 0;     // not used, must be zero

lParam = 0;     // not used, must be zero

Parameters

This message has no parameters.

Return Values

The return value is the type of File Manager window that has input focus. It can be one of the following values:

Value	Meaning
FMFOCUS_DIR	Directory portion of a directory window
FMFOCUS_TREE	Tree portion of a directory window
FMFOCUS_DRIVES	Drive bar of a directory window
FMFOCUS_SEARCH	Search Results window


FM_GETSELCOUNT

A File Manager extension sends a FM_GETSELCOUNT message to retrieve a count of the selected files in the active File Manager window (either the directory window or the Search Results window).

FM_GETSELCOUNT

wParam = 0; // not used, must be zero

lParam = 0; // not used, must be zero

Parameters

This message has no parameters.

Return Values

The return value is the number of selected files.

See Also

FM_GETFILESEL, FM_GETFILESELLFN, FM_GETSELCOUNTLFN


FM_GETSELCOUNTLFN

A File Manager extension sends an FM_GETSELCOUNTLFN message to retrieve the number of selected files in the active File Manager window (either the directory window or the Search Results window). The count includes files that have long filenames.

FM_GETSELCOUNTLFN

wParam = 0; // not used, must be zero

lParam = 0; // not used, must be zero

Parameters

This message has no parameters.

Return Values

The return value is the number of selected files.

Remarks

Only extensions that support long filenames (for example, network-aware extensions) should use this message.

See Also

FM_GETFILESEL, FM_GETFILESELLFN, FM_GETSELCOUNT


FM_REFRESH_WINDOWS

A File Manager extension sends an FM_REFRESH_WINDOWS message to cause File Manager to repaint either its active window or all of its windows.

FM_REFRESH_WINDOWS

wParam = (WPARAM) (BOOL) fRepaint;  // repaint flag

lParam = 0;                         // not used, must be zero

Parameters

fRepaint

Value of wParam. Specifies whether File Manager repaints its active window or all of its windows. If this parameter is TRUE, File Manager repaints all of its windows. Otherwise, File Manager repaints only its active window.

Return Values

This message does not return a meaningful value.

Remarks

File-system changes caused by an extension are automatically detected by File Manager. An extension should use this message only in situations where drive connections are made or canceled.

See Also

FMExtensionProc


FM_RELOAD_EXTENSIONS

A File Manager extension (or another application) sends an FM_RELOAD_EXTENSIONS message to cause File Manager to reload all extension DLLs listed in the [AddOns] section of the WINFILE.INI file.

FM_RELOAD_EXTENSIONS

wParam = 0; // not used, must be zero

lParam = 0; // not used, must be zero

Parameters

This message has no parameters.

Return Values

This message does not return a meaningful value.

Remarks

Other applications can use the PostMessage function to send this message to File Manager. To obtain the appropriate File Manager window handle, an application can specify “WFS_Frame” as the lpszClassName parameter in a call to the FindWindow function.

See Also

FindWindow, FMExtensionProc, PostMessage


FMEVENT_HELPMENUITEM

The FMEVENT_HELPMENUITEM message is sent to a File Manager extension DLL procedure when the user presses F1 on a menu or toolbar command item. The extension should call WinHelp, with that function’s hwnd parameter set to the value of the extension procedure’s hwnd parameter.

FMEVENT_HELPMENUITEM

uItem = (UINT) lParam;  /* command item for which help is sought */

Parameters

uItem

Identifies the menu or toolbar command item for which help is sought. The extension procedure uses this value to determine how best to call WinHelp.

Return Values

An extension DLL procedure should return zero if it processes this message.

See Also

FMExtensionProc, WinHelp, FMEVENT_HELPSTRING


FMEVENT_HELPSTRING

The FMEVENT_HELPSTRING message is sent to a File Manager extension DLL procedure when File Manager wants a help string for a menu or toolbar command item.

FMEVENT_HELPSTRING

lpfmshs = (LPFMS_HELPSTRING) lParam;  /* pointer to data transfer structure */

Parameters

lpfmshs

Points to an FMS_HELPSTRING structure that communicates command item help string data.

The FMS_HELPSTRING structure identifies the command item for which a help string is wanted, along with a handle to its menu. An application then writes the appropriate help string to the FMS_HELPSTRING structure’s szHelp member.

Return Values

An extension DLL procedure should return zero if it processes this message.

See Also

FMExtensionProc, FMEVENT_HELPMENUITEM


FMEVENT_INITMENU

The FMEVENT_INITMENU message is sent to an extension DLL when the user selects the menu for the extension from the File Manager menu bar. The extension can use this notification to initialize menu items in the menu.

FMEVENT_INITMENU

hmenu = (HMENU) lParam; /* handle of File Manager menu */

Parameters

hmenu

Specifies the handle of the File Manager menu bar.

Return Values

An extension DLL should return zero if it processes this message.

Remarks

An extension DLL receives this message only when the user selects the top-level menu. If the extension contains submenus, it must initialize them at the same time it initializes the top-level menu.

See Also

FMExtensionProc


FMEVENT_LOAD

The FMEVENT_LOAD message is sent to an extension DLL when File Manager is loading the DLL.

FMEVENT_LOAD

lpfmsld = (LPFMS_LOAD) lParam;  /* address of struct. with delta */

Parameters

lpfmsld

Points to an FMS_LOAD structure that specifies the menu-item delta value. An extension DLL should save the menu-item delta value and fill the other structure members with information about the extension.

Return Values

An extension DLL must return TRUE to continue loading the DLL. If the DLL returns FALSE, File Manager calls the FreeLibrary function and ends any communication with the extension DLL.

Remarks

An application should fill the dwSize, szMenuName, and hMenu members in the FMS_LOAD structure. It should also save the value of the wMenuDelta member and use it to identify menu items when modifying the menu.

See Also

FMExtensionProc, FMS_LOAD, FreeLibrary


FMEVENT_SELCHANGE

The FMEVENT_SELCHANGE message is sent to an extension DLL when the user selects a filename in the File Manager directory window or Search Results window.

FMEVENT_SELCHANGE

Parameters

This message has no parameters.

Return Values

An extension DLL should return zero if it processes this message.

Remarks

Changes in the tree portion of the directory window do not produce this message.

Because the user can change the selection many times, the extension DLL must return promptly after processing this message to avoid slowing the selection process for the user.

See Also

FMExtensionProc


FMEVENT_TOOLBARLOAD

The FMEVENT_TOOLBARLOAD message is sent to an extension DLL when File Manager is loading its toolbar. This message allows an extension DLL to add a button to the File Manager toolbar.

FMEVENT_TOOLBARLOAD

lpfmstbl = (LPFMS_TOOLBARLOAD) lParam;   /* toolbar data */

Parameters

lpfmstbl

Points to an FMS_TOOLBARLOAD structure. If the extension DLL adds a button to the toolbar in File Manager, the DLL should fill the structure with information about the button.

Return Values

An extension DLL must return TRUE to add the button to the toolbar. If the DLL returns FALSE, File Manager does not add the button.

See Also

FMExtensionProc, FMS_TOOLBARLOAD


FMEVENT_UNLOAD

The FMEVENT_UNLOAD message is sent to an extension DLL when File Manager is unloading the DLL.

FMEVENT_UNLOAD

Parameters

This message has no parameters.

Return Values

An extension DLL should return zero if it processes this message.

Remarks

The hwnd and hMenu values passed with the FMEVENT_LOAD and FMEVENT_INITMENU messages may not be valid at the time this message is sent.

See Also

FMExtensionProc


FMEVENT_USER_REFRESH

The FMEVENT_USER_REFRESH message is sent to an extension DLL when the user chooses the Refresh command from the Window menu in File Manager. The extension can use this notification to update its menu.

FMEVENT_USER_REFRESH

Parameters

This message has no parameters.

Return Values

An extension DLL should return zero if it processes this message.

See Also

FMExtensionProc


HDM_DELETEITEM

The HDM_DELETEITEM message deletes an item from a header control. You can send this message explicitly or by using the Header_DeleteItem macro.

HDM_DELETEITEM

wParam = (WPARAM) (int) index;

lParam = 0;

Parameters

index

Index of the item to delete.

Return Values

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

See Also

Header_DeleteItem


HDM_GETITEM

The HDM_GETITEM message retrieves information about an item in a header control. You can send this message explicitly or by using the Header_GetItem macro.

HDM_GETITEM

wParam = (WPARAM) (int) index;

lParam = (LPARAM) (HD_ITEM FAR*) phdi;

Parameters

index

Index of the item for which information is to be retrieved.

phdi

Pointer to an HD_ITEM structure. When the message is sent, the mask member indicates the type of information being requested. When the message returns, the other members receive the requested information. If the mask member specifies zero, the message returns TRUE but copies no information to the structure.

Return Values

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

See Also

HD_ITEM, Header_GetItem


HDM_GETITEMCOUNT

The HDM_GETITEMCOUNT message retrieves a count of the items in a header control. You can send this message explicitly or by using the Header_GetItemCount macro.

HDM_GETITEMCOUNT

wParam = 0;

lParam = 0;

Return Values

If the operation succeeds, the return value is the number of items.

If the operation fails, the return value is − 1.

See Also

Header_GetItemCount


HDM_HITTEST

The HDM_HITTEST message tests a point to determine which header item, if any, is at the specified point.

HDM_HITTEST

wParam = 0;

lParam = (LPARAM) (HD_HITTESTINFO FAR *) phdhti;

Parameters

phdhti

Pointer to an HD_HITTESTINFO structure that contains the position to test and receives information about the results of the test.

Return Values

Returns the index of the item at the specified position, if any, or  − 1 otherwise.

See Also

HD_HITTESTINFO


HDM_INSERTITEM

The HDM_INSERTITEM message inserts a new item into a header control. You can send this message explicitly or by using the Header_InsertItem macro.

HDM_INSERTITEM

wParam = (WPARAM) (int) index;

lParam = (LPARAM) (const HD_ITEM FAR*) phdi;

Parameters

index

Index of the item after which the new item is to be inserted. The new item is inserted at the end of the header control if index is greater than or equal to the number of items in the control. If index is zero, the new item is inserted at the beginning of the header control.

phdi

Pointer to an HD_ITEM structure that contains information about the new item.

Return Values

If the operation succeeds, the return value is the index of the new item.

If the operation fails, the return value is − 1.

See Also

HD_ITEM, Header_InsertItem


HDM_LAYOUT

The HDM_LAYOUT message retrieves the size and position of a header control within a given rectangle. This message is used to determine the appropriate dimensions for a new header control that is to occupy the given rectangle. You can send this message explicitly or by using the Header_Layout macro.

HDM_LAYOUT

wParam = 0;

lParam = (LPARAM) (HD_LAYOUT FAR*) playout;

Parameters

playout

Pointer to an HD_LAYOUT structure. The prc member specifies the coordinates of a rectangle, and the pwpos member receives the size and position for the header control within the rectangle.

Return Values

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

See Also

HD_LAYOUT, Header_Layout


HDM_SETITEM

The HDM_SETITEM message sets the attributes of the specified item in a header control. You can send this message explicitly or by using the Header_SetItem macro.

HDM_SETITEM

wParam = (WPARAM) (int) index;

lParam = (LPARAM) (const HD_ITEM FAR*) phdi;

Parameters

index

Index of the item whose attributes are to be changed.

phdi

Pointer to an HD_ITEM structure. When the message is sent, the mask member indicates the attributes to set. The other members specify new attributes.

Return Values

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

Remarks

The HDN_ITEMCHANGING notification message is sent to the parent window before the item attributes are changed. The parent window can return FALSE to prevent the changes, and in that case, HDM_SETITEM returns FALSE. If the parent window returns TRUE, the changes are made and the parent window receives the HDN_ITEMCHANGED notification message.

See Also

HD_ITEM, HDN_ITEMCHANGED, HDN_ITEMCHANGING, Header_SetItem


HDN_BEGINTRACK

The HDN_BEGINTRACK notification message notifies a header control’s parent window that the user has begun dragging a divider in the control (that is, the user has pressed the left mouse button while the mouse cursor is on a divider in the header control). This notification message is sent in the form of a WM_NOTIFY message.

HDN_BEGINTRACK

phdn = (HD_NOTIFY FAR *) lParam;

Parameters

phdn

Pointer to an HD_NOTIFY structure that contains information about the header control and the item whose divider is to be dragged.

Return Values

Returns FALSE to allow tracking of the divider or TRUE to prevent tracking.

See Also

HD_NOTIFY, WM_NOTIFY


HDN_DIVIDERDBLCLICK

The HDN_DIVIDERDBLCLICK notification message notifies a header control’s parent window that the user double-clicked the divider area of the control. This notification message is sent in the form of a WM_NOTIFY message.

HDN_DIVIDERDBLCLICK

phdn = (HD_NOTIFY FAR *) lParam;

Parameters

phdn

Pointer to an HD_NOTIFY structure that contains information about the header control and the item whose divider was double-clicked.

Return Values

No return value.

See Also

HD_NOTIFY, WM_NOTIFY


HDN_ENDTRACK

The HDN_ENDTRACK notification message notifies a header control’s parent window that the user has finished dragging a divider. This notification message sent in the form of a WM_NOTIFY message.

HDN_ENDTRACK

phdn = (HD_NOTIFY FAR *) lParam;

Parameters

phdn

Pointer to an HD_NOTIFY structure that contains information about the header control and the item whose divider was dragged.

Return Values

No return value.

See Also

HD_NOTIFY, WM_NOTIFY


HDN_ITEMCHANGED

The HDN_ITEMCHANGED notification message notifies a header control’s parent window that the attributes of a header item have changed. This notification message is sent in the form of a WM_NOTIFY message.

HDN_ITEMCHANGED

phdr = (HD_NOTIFY FAR *) lParam;

Parameters

phdr

Pointer to an HD_NOTIFY structure that contains information about the header control, including the attributes that have changed.

Return Values

No return value.

See Also

HD_NOTIFY, WM_NOTIFY


HDN_ITEMCHANGING

The HDN_ITEMCHANGING notification message notifies a header control’s parent window that the attributes of a header item are about to change. This notification message is sent in the form of a WM_NOTIFY message.

HDN_ITEMCHANGING

phdr = (HD_NOTIFY FAR *) lParam;

Parameters

phdr

Pointer to an HD_NOTIFY structure that contains information about the header control and the header item, including the attributes that are about to change.

Return Values

Returns FALSE to allow the changes or TRUE to prevent them.

See Also

HD_NOTIFY, WM_NOTIFY


HDN_ITEMCLICK

The HDN_ITEMCLICK notification message notifies a header control’s parent window that the user clicked the control. This notification message is sent in the form of a WM_NOTIFY message.

HDN_ITEMCLICK

phdr = (HD_NOTIFY FAR *) lParam;

Parameters

phdr

Pointer to an HD_NOTIFY structure that identifies the header control and specifies the index of the header item that was clicked and the mouse button used to click the item. The pitem member is set to NULL.

Return Values

No return value.

Remarks

A header control sends this notification message after the user releases the left mouse button.

See Also

HD_NOTIFY, WM_NOTIFY


HDN_ITEMDBLCLICK

The HDN_ITEMDBLCLICK notification message notifies a header control’s parent window that the user double-clicked the control. This notification message is sent in the form of a WM_NOTIFY message. Only header controls that have the HDS_BUTTONS style send this notification.

HDN_ITEMDBLCLICK

pnmhdr = (NMHDR FAR *) lParam;

Parameters

pnmhdr

Pointer to an NMHDR structure that contains the handle and identifier of the header control and the HDN_ITEMDBLCLICK notification code.

Return Values

No return value.

See Also

NMHDR, WM_NOTIFY


HDN_TRACK

The HDN_TRACK notification message notifies a header control’s parent window that the user is dragging a divider in the header control. This notification message is sent in the form of a WM_NOTIFY message.

HDN_TRACK

phdr = (HD_NOTIFY FAR *) lParam;

Parameters

phdr

Pointer to an HD_NOTIFY structure that contains information about the header control and the item whose divider is being dragged.

Return Values

Returns FALSE to continue tracking the divider or TRUE to end tracking.

See Also

HD_NOTIFY, WM_NOTIFY


HELPMSGSTRING

A common dialog box sends the HELPMSGSTRING registered message to the window procedure of its owner window when the user clicks the Help button.

For Explorer-style Open and Save As dialog boxes, this message has been superseded by the CDN_HELP notification message.

MessageID = RegisterWindowMessage(HELPMSGSTRING);
hdlg = (HWND) wParam;
lpStruct = (LPVOID) lParam;

Parameters

hdlg

Handle of the common dialog box.

lpStruct

Pointer to the initialization structure for the common dialog box. This structure can be a CHOOSECOLOR, CHOOSEFONT, FINDREPLACE, OPENFILENAME, PRINTDLG or PAGESETUPDLG structure.

Return Values

No return value.

Remarks

You must specify the HELPMSGSTRING constant in a call to the RegisterWindowMessage function to get the identifier for the message sent by the dialog box.

When you create the dialog box, use the hwndOwner member of the initialization structure to identify the window to receive HELPMSGSTRING messages.

See Also

CDN_HELP, CHOOSECOLOR, CHOOSEFONT, FINDREPLACE, OPENFILENAME, PRINTDLG, PAGESETUPDLG, RegisterWindowMessage


HKM_GETHOTKEY

The HKM_GETHOTKEY message retrieves the virtual-key code and modifier flags of a hot key from a hot-key control.

HKM_GETHOTKEY

wParam = 0;

lParam = 0;

Return Values

Returns the virtual-key code and modifier flags. The virtual-key code is in the low-order byte, and the modifier flags are in the high-order byte. The modifier flags can be a combination of the following values:

Value	Meaning
HOTKEYF_ALT	ALT key
HOTKEYF_CONTROL	CTRL key
HOTKEYF_EXT	Extended key
HOTKEYF_SHIFT	SHIFT key
Remarks

The 16-bit value returned by this message can be used as the wParam parameter in the WM_SETHOTKEY message.

See Also

WM_SETHOTKEY


HKM_SETHOTKEY

The HKM_SETHOTKEY message sets the hot key combination for a hot-key control.

HKM_SETHOTKEY

wParam = MAKEWORD(bVKHotKey, bfMods);

lParam = 0;

Parameters

bVKHotKey

Virtual-key code of the hot key.

bfMods

Modifier flags indicating the keys that, when used in combination with bVKHotKey, define a hot-key combination. For a list of modifier flag values, see the description of the HKM_GETHOTKEY message.

Return Values

No return value.

See Also

HKM_GETHOTKEY


HKM_SETRULES

The HKM_SETRULES message defines the invalid combinations and the default modifier combination for a hot-key control.

HKM_SETRULES

wParam = (WPARAM) fwCombInv;

lParam = MAKELPARAM(fwModInv, 0);

Parameters

fwCombInv

Array of flags that specify invalid key combinations. This parameter can be a combination of the following values:

Value	Meaning
HKCOMB_A	ALT
HKCOMB_C	CTRL
HKCOMB_CA	CTRL+ALT
HKCOMB_NONE	Unmodified keys
HKCOMB_S	SHIFT
HKCOMB_SA	SHIFT+ALT
HKCOMB_SC	SHIFT+CTRL
HKCOMB_SCA	SHIFT+CTRL+ALT
fwModInv

Array of flags that specify the key combination to use when the user enters an invalid combination. For a list of modifier flag values, see the description of the HKM_GETHOTKEY message.

Return Values

No return value.

Remarks

When a user enters an invalid key combination, as defined by flags specified in fwCombInv, the system uses the bitwise-OR operator to combine the keys entered by the user with the flags specified in fwModInv. The resulting key combination is converted into a string and then displayed in the hot-key control.

See Also

HKM_GETHOTKEY


IMC_CLOSESTATUSWINDOW

An application sends the IMC_CLOSESTATUSWINDOW message to the IME window to hide the status window.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_CLOSESTATUSWINDOW;
lParam = (LPARAM) 0;

Return Values

Returns zero if successful, nonzero otherwise.

Remarks

When the status window of IME is already hidden, this message does nothing. Although an application may send this message to the IME window, the application does not receive the corresponding IMN_CLOSESTATUSWINDOW message.


IMC_GETCANDIDATEPOS

An application sends the IMC_GETCANDIDATEPOS message to an IME window to get the position of the candidate window. Because the IME may adjust the position of a candidate window, an application uses this message to get the actual position to decide whether to reposition the window.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETCANDIDATEPOS;
lParam = (LPARAM) &CandForm;

Parameters

lParam

Pointer to the CANDIDATEFORM structure that receives the position of the candidate window.

Return Values

Returns zero if successful, nonzero otherwise.

Remarks

The returned position is in window coordinates relative to the window having the current input focus.

See Also

CANDIDATEFORM


IMC_GETCOMPOSITIONFONT

An application sends the IMC_GETCOMPOSITIONFONT message to an IME window to retrieve the logical font used for displaying intermediate characters in the composition window.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETCOMPOSITIONFONT;
lParam = (LPARAM) &LogFont;

Parameters

lParam

Pointer to the LOGFONT structure that receives information about the logical font.

Return Values

Returns zero if successful, nonzero otherwise.

See Also

LOGFONT


IMC_GETCOMPOSITIONWINDOW

An application sends the IMC_GETCOMPOSITIONWINDOW message to an IME window to get the position of the composition window. Because the IME may adjust the position of a composition window, an application uses this message to get the actual position to decide whether to reposition the window.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETCOMPOSITIONWINDOW;
lParam = (LPARAM) &CompForm;

Parameters

lParam

Pointer to the COMPOSITIONFORM structure that receives the position of the composition window.

Return Values

Returns zero if successful, nonzero otherwise.

Remarks

The returned position is in window coordinates relative to the window having the current input focus.

See Also

COMPOSITIONFORM


IMC_GETCONVERSIONMODE

An application sends the IMC_GETCONVERSIONMODE message to an IME window to obtain the current conversion mode. The window retrieves the current conversion mode from the current input context.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETCONVERSIONMODE;
lParam = 0;

Return Values

Returns a combination of the values given in the “IME Conversion Modes” table in Input Method Editor Constants.


IMC_GETOPENSTATUS

An application sends the IMC_GETOPENSTATUS message to an IME window to determine whether the IME is open.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETOPENSTATUS;
lParam = 0;

Return Values

Returns nonzero if the current IME is open, zero otherwise.


IMC_GETSENTENCEMODE

An application sends the IMC_GETSENTENCEMODE message to an IME window to obtain current sentence mode.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETSENTENCEMODE;
lParam = 0;

Return Values

Returns a combination of the values given in the “IME Sentence Modes” table in Input Method Editor Constants.


IMC_GETSTATUSWINDOWPOS

An application sends the IMC_GETSTATUSWINDOWPOS message to an IME window to get the position of the status window.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETSTATUSWINDOWPOS;
lParam = 0;

Return Values

Returns a POINTS structure that contains the x- and y-coordinates of the status window position.

See Also

POINTS


IMC_OPENSTATUSWINDOW

An application sends the IMC_OPENSTATUSWINDOW message to the IME window to show the status window. This message is ignored if the system is not in the show IME status mode. The user can set or clear the show IME status mode from the task bar.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_OPENSTATUSWINDOW;
lParam = (LPARAM) 0;

Return Values

Returns zero if successful, nonzero otherwise.

Remarks

If the status window is already shown, this message does nothing. Although the application may send this message to the IME window, the application does not receive the corresponding IMN_OPENSTATUSWINDOW message.


IMC_SETCANDIDATEPOS

An application sends the IMC_SETCANDIDATEPOS message to an IME window to set the position of the candidate window. This message is intended for applications that display composition characters on their own but use the IME window to display candidates.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETCANDIDATEPOS;
lParam = (LPARAM) &CandForm;

Parameters

lParam

Pointer to the CANDIDATEFORM structure that contains the x- and y-coordinates for the candidate window. The application should set the dwIndex member in the structure.

Return Values

Return zero if successful, nonzero otherwise.

See Also

CANDIDATEFORM


IMC_SETCOMPOSITIONFONT

An application sends the IMC_SETCOMPOSITIONFONT message to an IME window to specify the logical font to use for displaying intermediate characters in the composition window.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETCOMPOSITIONFONT;
lParam = (LPARAM) &LogFont;

Parameters

lParam

Pointer to the LOGFONT structure that contains information about the logical font.

Return Values

Returns zero if successful, nonzero otherwise.

Remarks

When processing this message, the IME window changes the current selected font in the input context.

See Also

LOGFONT


IMC_SETCOMPOSITIONWINDOW

An application sends the IMC_SETCOMPOSITIONWINDOW message to an IME window to set the style of the composition window. The message set this style in the current input context and the style is subsequently applied to each IME window that receives that input context.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETCOMPOSITIONWINDOW;
lParam = (LPARAM) &CompForm;

Parameters

lParam

Pointer to the COMPOSITIONFORM structure that contains the style information.

Return Values

Returns zero if successful, nonzero otherwise.

Remarks

By default, the IME window has the CFS_POINT style. This means the IME window uses the current caret position and window client area when it opens composition window.

See Also

COMPOSITIONFORM


IMC_SETCONVERSIONMODE

An application sends the IMC_SETCONVERSIONMODE message to an IME window to set current conversion mode.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETCONVERSIONMODE;
lParam = (LPARAM) cMode;

Parameters

lParam

Conversion mode. Can be one of the values given in the “IME Conversion Modes” table in Input Method Editor Constants.

Return Values

Returns zero if successful, nonzero otherwise.


IMC_SETOPENSTATUS

An application sends the IMC_SETOPENSTATUS message to an IME window to open or close the current IME.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETOPENSTATUS;
lParam = (LPARAM) bOpen;

Parameters

lParam

Open status. If TRUE, the IME is opened, closed otherwise.

Return Values

Returns zero if successful, nonzero otherwise.

Remarks

When processing this message, the IME window changes the current input context.


IMC_SETSENTENCEMODE

An application sends the IMC_SETSENTENCEMODE message to an IME window to set the current sentence mode.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETSENTENCEMODE;
lParam = 0;

Parameters

lParam

Sentence mode. Can be one of the values given in the “IME Sentence Modes” table in Input Method Editor Constants.

Return Values

Returns zero if successful, nonzero otherwise.


IMC_SETSTATUSWINDOWPOS

An application sends the IMC_SETSTATUSWINDOWPOS message to an IME window to set the position of the status window.

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETSTATUSWINDOWPOS;
lParam = (LPARAM) &pts;

Parameters

lParam

Pointer to a POINTS structure that contains the x- and y-coordinates of the position of the status window.

Return Values

Returns zero if successful, nonzero otherwise.

See Also

POINTS


IMN_CHANGECANDIDATE

The IMN_CHANGECANDIDATE message is sent to the application when an IME is about to change the content of the candidate window. An application should process this notification message if it displays candidates itself. The application receives this notification message through the WM_IME_NOTIFY message.

fCandidates = (DWORD) lParam;

Parameters

fCandidates

Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be changed.

Return Values

No return value.

Remarks

The IME window changes the appearance of the candidate window when it processes this message. An application can get information about the system window with the ImmGetCandidateListCount and ImmGetCandidateList functions.

See Also

ImmGetCandidateList, ImmGetCandidateListCount, WM_IME_NOTIFY


IMN_CLOSECANDIDATE

The IMN_CLOSECANDIDATE message is sent to the application when an IME is about to close the candidate window. An application should process this message if it displays candidates itself. The application receives this notification message through the WM_IME_NOTIFY message.

fCandidate = (DWORD) lParam;

Parameters

fCandidates

Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be closed.

Return Values

No return value.

Remarks

By default, the IME window destroys a candidate window when it processes this message.

See Also

WM_IME_NOTIFY


IMN_CLOSESTATUSWINDOW

The IMN_CLOSESTATUSWINDOW message is sent to the application when an IME is about to close the status window. An application should process this notification message if it displays the status window for the IME. The application receives this notification message through the WM_IME_NOTIFY message.

Return Values

No return value.

Remarks

The IME window closes the status window when it processes this message.

See Also

WM_IME_NOTIFY


IMN_GUIDELINE

The IMN_GUIDELINE message is sent when an IME is about to show an error message or other information. An application processes this message by calling the ImmGetGuideLine function to retrieve the error message or information from the IME. The application receives this notification message through the WM_IME_NOTIFY message.

Return Values

No return value.

Remarks

The IME window displays the error message or information string in an information window.

See Also

ImmGetGuideLine, WM_IME_NOTIFY


IMN_OPENCANDIDATE

The IMN_OPENCANDIDATE message is sent to the application when an IME is about to open the candidate window. An application should process this message if it displays candidates itself. The application can retrieve a list of candidates to display by using the ImmGetCandidateList function. The application receives this notification message through the WM_IME_NOTIFY message.

fCandidate = (DWORD) lParam;

Parameters

fCandidates

Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be opened.

Return Values

No return value.

Remarks

By default, the IME window creates a candidate window when it processes this message.

See Also

ImmGetCandidateList, WM_IME_NOTIFY


IMN_OPENSTATUSWINDOW

The IMN_OPENSTATUSWINDOW message is sent when an IME is about to create the status window. An application processes this message to display the status window for the IME by itself. The application receives this notification message through the WM_IME_NOTIFY message.

Return Values

No return value.

Remarks

The IME window creates a status window when it processes this message and sets the strings to display in the window into the input context. Applications can get information about the status window by using the ImmGetConversionStatus function.

See Also

ImmGetConversionStatus, WM_IME_NOTIFY


IMN_SETCANDIDATEPOS

The IMN_SETCANDIDATEPOS message is sent when the IME is about to move the candidate window. An application should process this message if it displays the candidate window itself. The application receives this notification message through the WM_IME_NOTIFY message.

fCandidates = (DWORD) lParam;

Parameters

fCandidates

Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be moved.

Return Values

No return value.

Remarks

The IME window moves the candidate window when it processes this message.

See Also

WM_IME_NOTIFY


IMN_SETCOMPOSITIONFONT

The IMN_SETCOMPOSITIONFONT message is sent when the font of the input context is updated. The application receives this notification message through the WM_IME_NOTIFY message.

Return Values

No return value.

Remarks

The application can get information about the font by using the ImmGetCompositionFont function. The IME window subsequently uses the font to draw the composition string.

See Also

ImmGetCompositionFont, WM_IME_NOTIFY


IMN_SETCOMPOSITIONWINDOW

The IMN_SETCOMPOSITIONWINDOW message is sent when the style or position of the composition window is updated. The application receives this notification message through the WM_IME_NOTIFY message.

Return Values

No return value.

Remarks

The application can get information about the composition form by using the IMC_GETCOMPOSITIONWINDOW message.

See Also

IMC_GETCOMPOSITIONWINDOW, WM_IME_NOTIFY


IMN_SETCONVERSIONMODE

The IMN_SETCONVERSIONMODE message is sent when the conversion mode of the input context is updated. The application receives this notification message through the WM_IME_NOTIFY message.

Return Values

No return value.

Remarks

The application can get information about the conversion mode by using the ImmGetConversionStatus function.

See Also

ImmGetConversionStatus, WM_IME_NOTIFY


IMN_SETOPENSTATUS

The IMN_SETOPENSTATUS message is sent when the open status of the input context is updated. The application receives this notification message through the WM_IME_NOTIFY message.

Return Values

No return value.

Remarks

The application can get information about the open status by using the ImmGetOpenStatus function.

See Also

ImmGetOpenStatus, WM_IME_NOTIFY


IMN_SETSENTENCEMODE

The IMN_SETSENTENCEMODE message is sent when the sentence mode of the input context is updated. The application receives this notification message through the WM_IME_NOTIFY message.

Return Values

No return value.

Remarks

The application can get information about the sentence mode by using the ImmGetConversionStatus function.

See Also

ImmGetConversionStatus, WM_IME_NOTIFY


IMN_SETSTATUSWINDOWPOS

The IMN_SETSTATUSWINDOWPOS message is sent when the status window position in the input context is updated. The application receives this notification message through the WM_IME_NOTIFY message.

Return Values

No return value.

Remarks

The application can get information about the status window position by using the IMC_GETSTATUSWINDOWPOS message.

See Also

IMC_GETSTATUSWINDOWPOS, WM_IME_NOTIFY


LB_ADDFILE

An application sends an LB_ADDFILE message to add the specified filename to a list box that contains a directory listing.

LB_ADDFILE

wParam = 0;                               // not used; must be zero

lParam = (LPARAM) (LPCTSTR) lpszFilename; // name of file to add

Parameters

lpszFilename

Value of lParam. Points to the name of the file to add.

Return Values

The return value is the zero-based index of the file that was added, or LB_ERR if an error occurs.

Remarks

The list box to which lpszFilename is added must have been filled by the DlgDirList function.

See Also

DlgDirList, LB_ADDSTRING


LB_ADDSTRING

An application sends an LB_ADDSTRING message to add a string to a list box. If the list box does not have the LBS_SORT style, the string is added to the end of the list. Otherwise, the string is inserted into the list and the list is sorted.

LB_ADDSTRING

wParam = 0;                         // not used; must be zero

lParam = (LPARAM) (LPCTSTR) lpsz;   // address of string to add

Parameters

lpsz

Value of lParam. Points to the null-terminated string that is to be added.

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the value of the lpsz parameter is stored as item data instead of the string it would otherwise point to. You can send the LB_GETITEMDATA and LB_SETITEMDATA messages to retrieve or modify the item data.

Return Values

The return value is the zero-based index of the string in the list box. If an error occurs, the return value is LB_ERR. If there is insufficient space to store the new string, the return value is LB_ERRSPACE.

Remarks

If you create an owner-drawn list box with the LBS_SORT style but not the LBS_HASSTRINGS style, the system sends the WM_COMPAREITEM message one or more times to the owner of the list box to place the new item properly in the list box.

See Also

LB_DELETESTRING, LB_INSERTSTRING, LB_SELECTSTRING, WM_COMPAREITEM


LB_DELETESTRING

An application sends an LB_DELETESTRING message to delete a string in a list box.

LB_DELETESTRING

wParam = (WPARAM) index;    // index of string to delete

lParam = 0;                 // not used; must be zero

Parameters

index

Value of wParam. Specifies the zero-based index of the string to be deleted.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

Return Values

The return value is a count of the strings remaining in the list. The return value is LB_ERR if the index parameter specifies an index greater than the number of items in the list.

Remarks

If an application creates the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the system sends a WM_DELETEITEM message to the owner of the list box so the application can free any additional data associated with the item.

See Also

LB_ADDSTRING, LB_INSERTSTRING, WM_DELETEITEM


LB_DIR

An application sends an LB_DIR message to add a list of filenames to a list box.

LB_DIR

wParam = (WPARAM) (UINT) uAttrs;          // file attributes

lParam = (LPARAM) (LPCTSTR) lpszFileSpec; // filename address

Parameters

uAttrs

Value of wParam. Specifies the attributes of the files to be added to the list box. This parameter can be a combination of the following values:

Value	Description
DDL_ARCHIVE	Includes archived files.
DDL_DIRECTORY	Includes subdirectories. Subdirectory names are enclosed in square brackets ([ ]).
DDL_DRIVES	Includes drives. Drives are listed in the form [-x-], where x is the drive letter.
DDL_EXCLUSIVE	Includes only files with the specified attributes. By default, read-write files are listed even if DDL_READWRITE is not specified.
DDL_HIDDEN	Includes hidden files.
DDL_READONLY	Includes read-only files.
DDL_READWRITE	Includes read-write files with no additional attributes.
DDL_SYSTEM	Includes system files.
lpszFileSpec

Value of lParam. Points to the null-terminated string that specifies the filename to add to the list. If the filename contains wildcards (for example, *.*), all files that match the wildcards and have the attributes specified by the uAttrs parameter are added to the list.

Return Values

The return value is the zero-based index of the last filename added to the list. If an error occurs, the return value is LB_ERR. If there is insufficient space to store the new strings, the return value is LB_ERRSPACE.

See Also

DlgDirList


LB_FINDSTRING

An application sends an LB_FINDSTRING message to find the first string in a list box that contains the specified prefix.

LB_FINDSTRING

wParam = (WPARAM) indexStart;           // item before start of search

lParam = (LPARAM) (LPCTSTR) lpszFind;   // search string address

Parameters

indexStart

Value of wParam. Specifies the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the indexStart parameter. If indexStart is −1, the entire list box is searched from the beginning.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

lpszFind

Value of lParam. Points to the null-terminated string that contains the prefix to search for. The search is case independent, so this string can contain any combination of uppercase and lowercase letters.

Return Values

The return value is the index of the matching item, or LB_ERR if the search was unsuccessful.

Remarks

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, this message returns the index of the item with a long value (supplied as the lParam parameter of the LB_ADDSTRING or LB_INSERTSTRING message) that matches the value supplied as the lpszFind parameter.

See Also

LB_ADDSTRING, LB_INSERTSTRING, LB_SELECTSTRING


LB_FINDSTRINGEXACT

An application sends a LB_FINDSTRINGEXACT message to find the first list box string that matches the string specified in the lpszFind parameter.

LB_FINDSTRINGEXACT

wParam = (WPARAM) indexStart;      // item before start of search

lParam = (LPARAM)(LPCSTR)lpszFind; // address of search string

Parameters

indexStart

Value of wParam. Specifies the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the indexStart parameter. If indexStart is  − 1, the entire list box is searched from the beginning.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

lpszFind

Value of lParam. Points to the null-terminated string to search for. This string can contain a complete filename, including the extension. The search is not case sensitive, so this string can contain any combination of uppercase and lowercase letters.

Return Values

The return value is the zero-based index of the matching item, or LB_ERR if the search was unsuccessful.

Remarks

If an application creates the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the action taken by LB_FINDSTRINGEXACT depends on whether the LBS_SORT style is used. If LBS_SORT is used, the system sends WM_COMPAREITEM messages to the list box owner to determine which item matches the specified string. Otherwise, LB_FINDSTRINGEXACT attempts to match the 32-bit value against the value of the lpszFind parameter.

See Also

LB_FINDSTRING, LB_SELECTSTRING, WM_COMPAREITEM


LB_GETANCHORINDEX

An application sends an LB_GETANCHORINDEX message to retrieve the index of the anchor item—that is, the item from which a multiple selection starts. A multiple selection spans all items from the anchor item to the caret item.

LB_GETANCHORINDEX

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is the index of the anchor item.

See Also

LB_SETANCHORINDEX


LB_GETCARETINDEX

An application sends an LB_GETCARETINDEX message to determine the index of the item that has the focus rectangle in a multiple-selection list box. The item may or may not be selected.

LB_GETCARETINDEX

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is the zero-based index of the list box item that has the focus rectangle. If the list box is a single-selection list box, the return value is the zero-based index of the item that is selected, if any.

See Also

LB_SETCARETINDEX


LB_GETCOUNT

An application sends an LB_GETCOUNT message to retrieve the number of items in a list box.

LB_GETCOUNT

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is the number of items in the list box, or LB_ERR if an error occurs.

Remarks

The returned count is one greater than the index value of the last item (the index is zero-based).

See Also

LB_SETCOUNT


LB_GETCURSEL

Send an LB_GETCURSEL message to retrieve the index of the currently selected item, if any, in a single-selection list box.

LB_GETCURSEL

wParam = 0;     // not used; must be zero

lParam = 0;     // not used; must be zero

Parameters

This message has no parameters.

Return Values

In a single-selection list box, the return value is the zero-based index of the currently selected item. If there is no selection, the return value is LB_ERR.

Remarks

Do not send this message to a multiple-selection list box.

To retrieve the indexes of the selected items in a multiple-selection list box, use the LB_GETSELITEMS message. To determine whether the item that has the focus rectangle in a multiple selection list box is selected, use the LB_GETSEL message.

If sent to a multiple-selection list box, LB_GETCURSEL returns the index of the item that has the focus rectangle. If no items are selected, it returns zero.

See Also

LB_GETCARETINDEX, LB_GETSEL, LB_GETSELITEMS, LB_SETCURSEL


LB_GETHORIZONTALEXTENT

An application sends an LB_GETHORIZONTALEXTENT message to retrieve from a list box the width, in pixels, by which the list box can be scrolled horizontally (the scrollable width) if the list box has a horizontal scroll bar.

LB_GETHORIZONTALEXTENT

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is the scrollable width, in pixels, of the list box.

Remarks

To respond to the LB_GETHORIZONTALEXTENT message, the list box must have been defined with the WS_HSCROLL style.

See Also

LB_SETHORIZONTALEXTENT


LB_GETITEMDATA

An application sends an LB_GETITEMDATA message to retrieve the application-defined 32-bit value associated with the specified list box item.

LB_GETITEMDATA

wParam = (WPARAM) index;    // item index

lParam = 0;                 // not used; must be zero

Parameters

index

Value of wParam. Specifies the index of the item.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

Return Values

The return value is the 32-bit value associated with the item, or LB_ERR if an error occurs. If the item is in an owner-drawn list box and was created without the LBS_HASSTRINGS style, this 32-bit value was in the lParam parameter of the LB_ADDSTRING or LB_INSERTSTRING message that added the item to the list box. Otherwise, it is the value in the lParam of an LB_SETITEMDATA message.

See Also

LB_ADDSTRING, LB_INSERTSTRING, LB_SETITEMDATA


LB_GETITEMHEIGHT

An application sends an LB_GETITEMHEIGHT message to retrieve the height of items in a list box.

LB_GETITEMHEIGHT

wParam = (WPARAM) index;    // item index

lParam = 0;                 // not used; must be zero

Parameters

index

Value of wParam. Specifies the zero-based index of the list box item. This index is used only if the list box has the LBS_OWNERDRAWVARIABLE style; otherwise, it must be  zero.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

Return Values

The return value is the height, in pixels, of each item in the list box. The return value is the height of the item specified by the index parameter if the list box has the LBS_OWNERDRAWVARIABLE style. The return value is LB_ERR if an error occurs.

See Also

LB_SETITEMHEIGHT


LB_GETITEMRECT

An application sends an LB_GETITEMRECT message to retrieve the dimensions of the rectangle that bounds a list box item as it is currently displayed in the list box.

LB_GETITEMRECT

wParam = (WPARAM) index;            // item index

lParam = (LPARAM) (RECT FAR*) lprc; // address of rectangle

Parameters

index

Value of wParam. Specifies the zero-based index of the item.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

lprc

Value of lParam. Points to a RECT structure that will receive the client coordinates for the item in the list box.

Return Values

If an error occurs, the return value is LB_ERR.

See Also

RECT


LB_GETLOCALE

An application sends an LB_GETLOCALE message to retrieve the current locale of the list box. You can use the locale to determine the correct sorting order of displayed text (for list boxes with the LBS_SORT style) and of text added by the LB_ADDSTRING message.

LB_GETLOCALE

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is a 32-bit value that specifies the current locale of the list box. The high-order word contains the country code and the low-order word contains the language identifier.

Remarks

The language identifier consists of a sublanguage identifier and a primary language identifier. Use the PRIMARYLANGID macro to extract the primary language identifier from the low-order word of the return value, and the SUBLANGID macro to extract the sublanguage identifier.

See Also

LB_ADDSTRING, LB_SETLOCALE, PRIMARYLANGID, SUBLANGID


LB_GETSEL

An application sends an LB_GETSEL message to retrieve the selection state of an item.

LB_GETSEL

wParam = (WPARAM) index;    // item index

lParam = 0;                 // not used; must be zero

Parameters

index

Value of wParam. Specifies the zero-based index of the item.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

Return Values

If an item is selected, the return value is greater than zero; otherwise, it is zero. If an error occurs, the return value is LB_ERR.

See Also

LB_SETSEL


LB_GETSELCOUNT

An application sends an LB_GETSELCOUNT message to retrieve the total number of selected items in a multiple-selection list box.

LB_GETSELCOUNT

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is the count of selected items in the list box. If the list box is a single-selection list box, the return value is LB_ERR.

See Also

LB_SETSEL


LB_GETSELITEMS

An application sends an LB_GETSELITEMS message to fill a buffer with an array of integers that specify the item numbers of selected items in a multiple-selection list box.

LB_GETSELITEMS

wParam = (WPARAM) cItems;           // maximum number of items

lParam = (LPARAM) (LPINT) lpnItems; // address of buffer

Parameters

cItems

Value of wParam. Specifies the maximum number of selected items whose item numbers are to be placed in the buffer.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

lpnItems

Value of lParam. Points to a buffer large enough for the number of integers specified by the cItems parameter.

Return Values

The return value is the number of items placed in the buffer. If the list box is a single-selection list box, the return value is LB_ERR.

See Also

LB_GETSELCOUNT


LB_GETTEXT

An application sends an LB_GETTEXT message to retrieve a string from a list box.

LB_GETTEXT

wParam = (WPARAM) index;                // item index

lParam = (LPARAM) (LPCTSTR) lpszBuffer; // address of buffer

Parameters

index

Value of wParam. Specifies the zero-based index of the string to retrieve.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

lpszBuffer

Value of lParam. Points to the buffer that will receive the string. The buffer must have sufficient space for the string and a terminating null character. An LB_GETTEXTLEN message can be sent before the LB_GETTEXT message to retrieve the length, in characters, of the string.

Return Values

The return value is the length of the string, in characters, excluding the terminating null character. If index does not specify a valid index, the return value is LB_ERR.

Remarks

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the buffer pointed to by the lpszBuffer parameter will receive the 32-bit value associated with the item (the item data).

See Also

LB_GETTEXTLEN


LB_GETTEXTLEN

An application sends an LB_GETTEXTLEN message to retrieve the length of a string in a list box.

LB_GETTEXTLEN

wParam = (WPARAM) index;    // item index

lParam = 0;                 // not used; must be zero

Parameters

index

Value of wParam. Specifies the zero-based index of the string.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

Return Values

The return value is the length of the string, in characters, excluding the terminating null character. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section.

If the index parameter does not specify a valid index, the return value is LB_ERR.

Remarks

Under certain conditions, the return value is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the operating system allowing for the possible existence of double-byte character set (DBCS) characters within the text. The return value, however, will always be at least as large as the actual length of the text; you can thus always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode.

To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the GetWindowText function.

See Also

CB_GETLBTEXT, GetWindowText, LB_GETTEXT, WM_GETTEXT


LB_GETTOPINDEX

An application sends an LB_GETTOPINDEX message to retrieve the index of the first visible item in a list box. Initially the item with index 0 is at the top of the list box, but if the list box contents have been scrolled another item may be at the top.

LB_GETTOPINDEX

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is the index of the first visible item in the list box.

See Also

LB_SETTOPINDEX


LB_INITSTORAGE

Allocates memory for storing list box items. An application sends this message before adding a large number of items to a list box.

LB_INITSTORAGE

wParam = (WPARAM) (int) cItems;  // number of items to add

lParam = (LPARAM) (DWORD) cb;   // amount of memory to allocate, in bytes

Parameters

cItems

Specifies the number of items to add.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

cb

Specifies the amount of memory, in bytes, to allocate for item strings.

Return Values

The return value is the maximum number of items that the memory object can store before another memory reallocation is needed, if successful. It is LB_ERRSPACE if not enough memory is available.

Remarks

Windows 95: This message helps speed up the initialization of list boxes that have a large number of items (more than 100). It reserves the specified amount of memory so that subsequent LB_ADDSTRING, LB_INSERTSTRING, LB_DIR, and LB_ADDFILE messages take the shortest possible time. You can use estimates for the cItems and cb parameters. If you overestimate, the extra memory is allocated; if you underestimate, the normal allocation is used for items that exceed the requested amount.

Windows NT: This message is not needed on Windows NT. It does not reserve the specified amount of memory, because available memory is virtually unlimited. The return value is always the value specified in the cItems parameter.

See Also

LB_ADDFILE, LB_ADDSTRING, LB_DIR, LB_INSERTSTRING


LB_INSERTSTRING

An application sends an LB_INSERTSTRING message to insert a string into a list box. Unlike the LB_ADDSTRING message, the LB_INSERTSTRING message does not cause a list with the LBS_SORT style to be sorted.

LB_INSERTSTRING

wParam = (WPARAM) index;          // item index

lParam = (LPARAM) (LPCTSTR) lpsz; // address of string to insert

Parameters

index

Value of wParam. Specifies the zero-based index of the position at which to insert the string. If this parameter is −1, the string is added to the end of the list.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

lpsz

Value of lParam. Points to the null-terminated string to be inserted.

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the value of the lpsz parameter is stored as item data instead of the string it would otherwise point to. You can send the LB_GETITEMDATA and LB_SETITEMDATA messages to retrieve or modify the item data.

Return Values

The return value is the index of the position at which the string was inserted. If an error occurs, the return value is LB_ERR. If there is insufficient space to store the new string, the return value is LB_ERRSPACE.

See Also

LB_ADDSTRING, LB_SELECTSTRING


LB_ITEMFROMPOINT

An application sends this message to retrieve the zero-based index of the item nearest the specified point in a list box.

LB_ITEMFROMPOINT

wParam = 0;                                // not used, must be zero

lParam = (LPARAM) MAKELPARAM(xPos, yPos);  // coordinates of point

Parameters

xPos

Value of the low-order word of lParam. Specifies the x-coordinate of a point, relative to the upper-left corner of the client area of the list box.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of a point, relative to the upper-left corner of the client area of the list box.

Return Values

The return value contains the index of the nearest item in the low-order word. The high-order word is zero if the specified point is in the client area of the list box, or one if it is outside the client area.


LB_RESETCONTENT

An application sends an LB_RESETCONTENT to remove all items from a list box.

LB_RESETCONTENT

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

This message does not return a value.

Remarks

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the owner of the list box receives a WM_DELETEITEM message for each item in the list box.

See Also

WM_DELETEITEM


LB_SELECTSTRING

An application sends an LB_SELECTSTRING message to search a list box for an item that begins with the characters in a specified string. If a matching item is found, the item is selected.

LB_SELECTSTRING

wParam = (WPARAM) indexStart;        // item before start of search

lParam = (LPARAM)(LPCTSTR)lpszFind;  // address of search string

Parameters

indexStart

Value of wParam. Specifies the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the indexStart parameter. If indexStart is −1, the entire list box is searched from the beginning.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

lpszFind

Value of lParam. Points to the null-terminated string that contains the prefix to search for. The search is case independent, so this string can contain any combination of uppercase and lowercase letters.

Return Values

If the search is successful, the return value is the index of the selected item. If the search is unsuccessful, the return value is LB_ERR and the current selection is not changed.

Remarks

The list box is scrolled, if necessary, to bring the selected item into view.

Do not use this message with a list box that has the LBS_MULTIPLESEL style.

An item is selected only if its initial characters from the starting point match the characters in the string specified by the lpszFind parameter.

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, this message returns the index of the item whose long value (supplied as the lParam parameter of the LB_ADDSTRING or LB_INSERTSTRING message) matches the value supplied as the lParam parameter of LB_SELECTSTRING.

See Also

LB_ADDSTRING, LB_FINDSTRING, LB_INSERTSTRING


LB_SELITEMRANGE

An application sends an LB_SELITEMRANGE message to select one or more consecutive items in a multiple-selection list box.

LB_SELITEMRANGE

wParam = (WPARAM) (BOOL) fSelect;   // selection flag

lParam = MAKELPARAM(wFirst, wLast); // first and last items

Parameters

fSelect

Value of wParam. Specifies how to set the selection. If the fSelect parameter is TRUE, the string is selected and highlighted; if fSelect is zero, the highlight is removed and the string is no longer selected.

wFirst

Value of the low-order word of lParam. Specifies the zero-based index of the first item to select.

wLast

Value of the high-order word of lParam. Specifies the zero-based index of the last item to select.

Return Values

If an error occurs, the return value is LB_ERR.

Remarks

Use this message only with multiple-selection list boxes.

This message can select a range only within the first 65,536 items.

See Also

LB_SELITEMRANGEEX, LB_SETSEL


LB_SELITEMRANGEEX

An application sends an LB_SELITEMRANGEEX message to select one or more consecutive items in a multiple-selection list box.

LB_SELITEMRANGEEX

wParam = (WPARAM) wFirst; // first item

lParam = (LPARAM) wLast); // last item

Parameters

wFirst

Value of wParam. Specifies the zero-based index of the first item to select.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

wLast

Value of lParam. Specifies the zero-based index of the last item to select.

Return Values

If an error occurs, the return value is LB_ERR.

Remarks

If the wFirst parameter is less than the wLast parameter, the specified range of items is selected. If wFirst is greater than wLast, the selection is removed from the specified range of items.

Use this message only with multiple-selection list boxes.

This message can select a range only within the first 65,536 items.

See Also

LB_SELITEMRANGE, LB_SETSEL


LB_SETANCHORINDEX

An application sends an LB_SETANCHORINDEX message to set the anchor item—that is, the item from which a multiple selection starts. A multiple selection spans all items from the anchor item to the caret item.

LB_SETANCHORINDEX

wParam = (WPARAM) index; // index to set as anchor

lParam = 0;              // not used; must be zero

Parameters

index

Value of wParam. Specifies the index of the new anchor item.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

Return Values

If the message succeeds, the return value is zero.

If the message fails, the return value is LB_ERR.

See Also

LB_GETANCHORINDEX


LB_SETCARETINDEX

An application sends an LB_SETCARETINDEX message to set the focus rectangle to the item at the specified index in a multiple-selection list box. If the item is not visible, it is scrolled into view.

LB_SETCARETINDEX

wParam = (WPARAM) index;            // item index

lParam = MAKELPARAM(fScroll, 0);    // flag for scrolling item

Parameters

index

Value of wParam. Specifies the zero-based index of the list box item that is to receive the focus rectangle.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

fScroll

Value of lParam. If this value is FALSE, the item is scrolled until it is fully visible; if it is TRUE, the item is scrolled until it is at least partially visible.

Return Values

If an error occurs, the return value is LB_ERR.

See Also

LB_GETCARETINDEX


LB_SETCOLUMNWIDTH

An application sends an LB_SETCOLUMNWIDTH message to a multiple-column list box (created with the LBS_MULTICOLUMN style) to set the width, in pixels, of all columns in the list box.

LB_SETCOLUMNWIDTH

wParam = (WPARAM) cxColumn; // column width in pixels

lParam = 0;                 // not used; must be zero

Parameters

cxColumn

Value of wParam. Specifies the width, in pixels, of all columns.

Return Values

This message does not return a value.

See Also

LB_SETTABSTOPS


LB_SETCOUNT

An application sends an LB_SETCOUNT message to set the count of items in a list box created with the LBS_NODATA style and not created with the LBS_HASSTRINGS style.

LB_SETCOUNT

wParam = (WPARAM) (int) cItems; // count of list box items

lParam = 0;                     // not used; must be zero

Parameters

cItems

Value of wParam. Specifies the new count of items in the list box.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

Return Values

If an error occurs, the return value is LB_ERR. If there is insufficient memory to store the items, the return value is LB_ERRSPACE.

Remarks

The LB_SETCOUNT message is supported only by list boxes created with the LBS_NODATA style and not created with the LBS_HASSTRINGS style. All other list boxes return LB_ERR.

See Also

LB_GETCOUNT


LB_SETCURSEL

An application sends an LB_SETCURSEL message to select a string and scroll it into view, if necessary. When the new string is selected, the list box removes the highlight from the previously selected string.

LB_SETCURSEL

wParam = (WPARAM) index;    // item index

lParam = 0;                 // not used; must be zero

Parameters

index

Value of wParam. Specifies the zero-based index of the string that is selected. If the index parameter is -1, the list box is set to have no selection.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

Return Values

If an error occurs, the return value is LB_ERR. If the index parameter is −1, the return value is LB_ERR even though no error occurred.

Remarks

Use this message only with single-selection list boxes. You cannot use it to set or remove a selection in a multiple-selection list box.

See Also

LB_GETCURSEL


LB_SETHORIZONTALEXTENT

An application sends an LB_SETHORIZONTALEXTENT message to set the width, in pixels, by which a list box can be scrolled horizontally (the scrollable width). If the width of the list box is smaller than this value, the horizontal scroll bar horizontally scrolls items in the list box. If the width of the list box is equal to or greater than this value, the horizontal scroll bar is hidden.

LB_SETHORIZONTALEXTENT

wParam = (WPARAM) cxExtent; // horizontal scroll width

lParam = 0;                 // not used; must be zero

Parameters

cxExtent

Value of wParam. Specifies the number of pixels by which the list box can be scrolled.

Windows 95: The wParam parameter is limited to 16-bit values.

Return Values

This message does not return a value.

Remarks

To respond to the LB_SETHORIZONTALEXTENT message, the list box must have been defined with the WS_HSCROLL style.

See Also

LB_GETHORIZONTALEXTENT


LB_SETITEMDATA

An application sends an LB_SETITEMDATA message to set a 32-bit value associated with the specified item in a list box.

LB_SETITEMDATA

wParam = (WPARAM) index;    // item index

lParam = (LPARAM) dwData;   // value to associate with item

Parameters

index

Value of wParam. Specifies the zero-based index of the item.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

dwData

Value of lParam. Specifies the 32-bit value to be associated with the item.

Return Values

If an error occurs, the return value is LB_ERR.

Remarks

If the item is in an owner-drawn list box created without the LBS_HASSTRINGS style, this message replaces the 32-bit value contained in the lParam parameter of the LB_ADDSTRING or LB_INSERTSTRING message that added the item to the list box.

See Also

LB_ADDSTRING, LB_GETITEMDATA, LB_INSERTSTRING


LB_SETITEMHEIGHT

An application sends an LB_SETITEMHEIGHT message to set the height, in pixels, of items in a list box. If the list box has the LBS_OWNERDRAWVARIABLE style, this message sets the height of the item specified by the index parameter. Otherwise, this message sets the height of all items in the list box.

LB_SETITEMHEIGHT

wParam = (WPARAM) index;        // item index

lParam = MAKELPARAM(cyItem, 0); // item height

Parameters

index

Value of wParam. Specifies the zero-based index of the item in the list box. Use this parameter only if the list box has the LBS_OWNERDRAWVARIABLE style; otherwise, set it to zero.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

cyItem

Value of lParam. Specifies the height, in pixels, of the item.

Return Values

If the index or height is invalid, the return value is LB_ERR.

See Also

LB_GETITEMHEIGHT


LB_SETLOCALE

An application sends an LB_SETLOCALE message to set the current locale of the list box. You can use the locale to determine the correct sorting order of displayed text (for list boxes with the LBS_SORT style) and of text added by the LB_ADDSTRING message.

LB_SETLOCALE

wParam = (WPARAM) wLocaleID;    // locale identifier

lParam = 0;                     // not used; must be zero

Parameters

wLocaleID

Value of wParam. Specifies the locale identifier that the list box will use for sorting when adding text.

Return Values

The return value is the previous locale identifier. If the wLocaleID parameter specifies a locale that is not installed on the system, the return value is LB_ERR and the current list box locale is not changed.

Remarks

Use the MAKELCID macro to construct a locale identifier.

See Also

LB_ADDSTRING, LB_GETLOCALE, MAKELCID


LB_SETSEL

An application sends an LB_SETSEL message to select a string in a multiple-selection list box.

LB_SETSEL

wParam = (WPARAM) (BOOL) fSelect;   // selection flag

lParam = (LPARAM) (UINT) index;     // item index

Parameters

fSelect

Value of wParam. Specifies how to set the selection. If the fSelect parameter is TRUE, the string is selected and highlighted; if fSelect is FALSE, the highlight is removed and the string is no longer selected.

index

Value of lParam. Specifies the zero-based index of the string to set. If index is −1, the selection is added to or removed from all strings, depending on the value of fSelect.

Return Values

If an error occurs, the return value is LB_ERR.

Remarks

Use this message only with multiple-selection list boxes.

See Also

LB_GETSEL, LB_SELITEMRANGE


LB_SETTABSTOPS

An application sends an LB_SETTABSTOPS message to set the tab-stop positions in a list box.

LB_SETTABSTOPS

wParam = (WPARAM) cTabs;            // number of tab stops

lParam = (LPARAM) (LPINT) lpnTabs;  // address of tab-stop array

Parameters

cTabs

Value of wParam. Specifies the number of tab stops in the list box.

lpnTabs

Value of lParam. Points to the first member of an array of integers containing the tab stops, in dialog box units. The tab stops must be sorted in ascending order; backward tabs are not allowed.

Return Values

If all the specified tabs are set, the return value is TRUE; otherwise, it is FALSE.

Remarks

To respond to the LB_SETTABSTOPS message, the list box must have been created with the LBS_USETABSTOPS style.

If cTabs parameter is 0 and lpnTabs is NULL, the default tab stop is two dialog box units. If cTabs is 1, the list box will have tab stops separated by the distance specified by lpnTabs.

If lpnTabs points to more than a single value, a tab stop will be set for each value in lpnTabs, up to the number specified by cTabs.

A dialog box unit is a horizontal or vertical distance. One horizontal dialog box unit is equal to 0.25 of the current dialog box base-width unit. These units are computed based on the height and width of the current system font. The GetDialogBaseUnits function returns the current dialog box base units, in pixels.

See Also

GetDialogBaseUnits


LB_SETTOPINDEX

An application sends an LB_SETTOPINDEX message to ensure that a particular item in a list box is visible.

LB_SETTOPINDEX

wParam = (WPARAM) index;    // item index

lParam = 0;                 // not used; must be zero

Parameters

index

Value of wParam. Specifies the zero-based index of the item in the list box.

Windows 95: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a listbox is limited only by available memory.

Return Values

If an error occurs, the return value is LB_ERR.

Remarks

The system scrolls the list box contents so that either the specified item appears at the top of the list box or the maximum scroll range has been reached.

See Also

LB_GETTOPINDEX


LBN_DBLCLK

An application sends the LBN_DBLCLK notification message when the user double-clicks a string in a list box. The parent window of the list box receives this notification message through the WM_COMMAND message.

LBN_DBLCLK

idListBox = (int) LOWORD(wParam);  // identifier of list box

hwndListBox = (HWND) lParam;       // handle of list box

Remarks

Only a list box that has the LBS_NOTIFY style will send this notification message.

See Also

LBN_SELCHANGE, WM_COMMAND


LBN_ERRSPACE

An application sends the LBN_ERRSPACE notification message when a list box cannot allocate enough memory to meet a specific request. The parent window of the list box receives this notification message through the WM_COMMAND message.

LBN_ERRSPACE

idListBox = (int) LOWORD(wParam);  // identifier of list box

hwndListBox = (HWND) lParam;       // handle of list box

See Also

WM_COMMAND


LBN_KILLFOCUS

An application sends the LBN_KILLFOCUS notification message when a list box loses the keyboard focus. The parent window of the list box receives this notification message through the WM_COMMAND message.

LBN_KILLFOCUS

idListBox = (int) LOWORD(wParam);  // identifier of list box

hwndListBox = (HWND) lParam;       // handle of list box

See Also

LBN_SETFOCUS, WM_COMMAND


LBN_SELCANCEL

An application sends the LBN_SELCANCEL notification message when the user cancels the selection in a list box. The parent window of the list box receives this notification message through the WM_COMMAND message.

LBN_SELCANCEL

idListBox = (int) LOWORD(wParam);  // identifier of list box

hwndListBox = (HWND) lParam;       // handle of list box

Remarks

This notification message applies only to list boxes of the LBS_NOTIFY style.

See Also

LB_SETCURSEL, LBN_DBLCLK, LBN_SELCHANGE, WM_COMMAND


LBN_SELCHANGE

An application sends the LBN_SELCHANGE notification message when the selection in a list box is about to change. The parent window of the list box receives this notification message through the WM_COMMAND message.

LBN_SELCHANGE

idListBox = (int) LOWORD(wParam);  // identifier of list box

hwndListBox = (HWND) lParam;       // handle of list box

Remarks

This notification message is not sent if the LB_SETCURSEL message changes the selection.

This notification message applies only to a list box that has the LBS_NOTIFY style.

For a multiple-selection list box, the LBN_SELCHANGE notification is sent whenever the user presses an arrow key, even if the selection does not change.

See Also

LB_SETCURSEL, LBN_DBLCLK, LBN_SELCANCEL, WM_COMMAND


LBN_SETFOCUS

An application sends the LBN_SETFOCUS notification message when a list box receives the keyboard focus. The parent window of the list box receives this notification message through the WM_COMMAND message.

LBN_SETFOCUS

idListBox = (int) LOWORD(wParam);  // identifier of list box

hwndListBox = (HWND) lParam;       // handle of list box

See Also

LBN_KILLFOCUS, WM_COMMAND


LBSELCHSTRING

An Open or Save As dialog box sends the LBSELCHSTRING registered message to your hook procedure when the selection changes in any of the list boxes or combo boxes of the dialog box.

For Explorer-style Open and Save As dialog boxes, this message has been superseded by the CDN_SELCHANGE and CDN_TYPECHANGE messages.

MessageID = RegisterWindowMessage(LBSELCHSTRING);
idListBox = (UINT) wParam;
iItem = LOWORD (lParam);
iType = HIWORD (lParam);

Parameters

idListBox

Identifier of the list box or combo box in which the selection changed.

iItem

Item number of the selected string in the list box or combo box.

iType

Type of selection change. This parameter can be one of the following values:

CD_LBSELCHANGE	The item identified by iItem is the only item selected in a single-selection list box.
CD_LBSELADD	The item identified by iItem is one of the items selected in a multiple-selection list box.
CD_LBSELSUB	The item identified by iItem is no longer selected in a multiple-selection list box.
CD_LBSELNOITEMS	No items exist in a multiple-selection list box.
Return Values

No return value.

Remarks

The hook procedure must specify the LBSELCHSTRING constant in a call to the RegisterWindowMessage function to get the identifier for the message sent by the dialog box.

See Also

CDN_SELCHANGE, CDN_TYPECHANGE, RegisterWindowMessage


LVM_ARRANGE

The LVM_ARRANGE message arranges items in icon view. You can send this message explicitly or by using the ListView_Arrange macro.

LVM_ARRANGE

wParam = (WPARAM) (int) code;

lParam = 0;

Parameters

code

Specifies the alignment, which can be one of the following values:

Value	Meaning
LVA_ALIGNLEFT	Aligns items along the left edge of the window.
LVA_ALIGNTOP	Aligns items along the top edge of the window.
LVA_DEFAULT	Aligns items according to the list view control’s current alignment styles (the default value).
LVA_SNAPTOGRID	Snaps all icons to the nearest grid position.
Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_Arrange


LVM_CREATEDRAGIMAGE

The LVM_CREATEDRAGIMAGE message creates a drag image list for the specified item. You can send this message explicitly or by using the ListView_CreateDragImage macro.

LVM_CREATEDRAGIMAGE

wParam = (WPARAM) (int) iItem;

lParam = (LPARAM) (LPPOINT) lpptUpLeft;

Parameters

iItem

Index of the item.

lpptUpLeft

Pointer to a POINT structure that receives the initial location of the upper-left corner of the image, in view coordinates.

Return Values

Returns the handle to the drag image list if successful or NULL otherwise.

See Also

ListView_CreateDragImage, POINT


LVM_DELETEALLITEMS

The LVM_DELETEALLITEMS message removes all items from a list view control. You can send this message explicitly or by using the ListView_DeleteAllItems macro.

LVM_DELETEALLITEMS

wParam = 0;

lParam = 0;

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_DeleteAllItems


LVM_DELETECOLUMN

The LVM_DELETECOLUMN message removes a column from a list view control. You can send this message explicitly or by using the ListView_DeleteColumn macro.

LVM_DELETECOLUMN

wParam = (WPARAM) (int) iCol;

lParam = 0;

Parameters

iCol

Index of the column to delete.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_DeleteColumn


LVM_DELETEITEM

The LVM_DELETEITEM message removes an item from a list view control. You can send this message explicitly or by using the ListView_DeleteItem macro.

LVM_DELETEITEM

wParam = (WPARAM) (int) iItem;

lParam = 0;

Parameters

iItem

Index of the list view item to delete.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_DeleteItem


LVM_EDITLABEL

The LVM_EDITLABEL message begins in-place editing of the specified list view item’s text. The message implicitly selects and focuses the specified item. You can send this message explicitly or by using the ListView_EditLabel macro.

LVM_EDITLABEL

wParam = (WPARAM) (int) iItem;

lParam = 0;

Parameters

iItem

Index of the list view item. To cancel editing, set iItem to −1.

Return Values

Returns the handle of the edit control that is used to edit the item text if successful or NULL otherwise.

Remarks

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it.

The control must have the focus before you send this message to the control. Focus can be set using the SetFocus function.

See Also

ListView_EditLabel, WM_CANCELMODE, SetFocus


LVM_ENSUREVISIBLE

The LVM_ENSUREVISIBLE message ensures that a list view item is entirely or at least partially visible, scrolling the list view control if necessary. You can send this message explicitly or by using the ListView_EnsureVisible macro.

LVM_ENSUREVISIBLE

wParam = (WPARAM) (int) i;

lParam = (LPARAM) (BOOL) fPartialOk;

Parameters

i

Index of the list view item.

fPartialOK

Value specifying whether the item must be entirely visible. If this parameter is TRUE, no scrolling occurs if the item is at least partially visible.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_EnsureVisible


LVM_FINDITEM

The LVM_FINDITEM message searches for a list view item with the specified characteristics. You can send this message explicitly or by using the ListView_FindItem macro.

LVM_FINDITEM

wParam = (WPARAM) (int) iStart;

lParam = (LPARAM) (const LV_FINDINFO FAR *) plvfi;

Parameters

iStart

Index of the item to begin the search with or −1 to start from the beginning. The specified item is itself excluded from the search.

plvfi

Pointer to an LV_FINDINFO structure that contains information about what to search for.

Return Values

Returns the index of the item if successful or −1 otherwise.

See Also

ListView_FindItem, LV_FINDINFO


LVM_GETBKCOLOR

The LVM_GETBKCOLOR message retrieves the background color of a list view control. You can send this message explicitly or by using the ListView_GetBkColor macro.

LVM_GETBKCOLOR

wParam = 0;

lParam = 0;

Return Values

Returns the background color of the list view control.

See Also

ListView_GetBkColor


LVM_GETCALLBACKMASK

The LVM_GETCALLBACKMASK message retrieves the callback mask for a list view control. You can send this message explicitly or by using the ListView_GetCallbackMask macro.

LVM_GETCALLBACKMASK

wParam = 0;

lParam = 0;

Return Values

Returns the callback mask.

See Also

ListView_GetCallbackMask


LVM_GETCOLUMN

The LVM_GETCOLUMN message retrieves the attributes of a list view control’s column. You can send this message explicitly or by using the ListView_GetColumn macro.

LVM_GETCOLUMN

wParam = (WPARAM) (int) iCol;

lParam = (LPARAM) (LV_COLUMN FAR *) pcol;

Parameters

iCol

Index of the column.

pcol

Pointer to an LV_COLUMN structure that specifies the information to retrieve and receives information about the column. The mask member specifies which column attributes to retrieve.

If the mask member specifies the LVCF_TEXT value, the pszText member must contain the pointer to the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_GetColumn, LV_COLUMN


LVM_GETCOLUMNWIDTH

The LVM_GETCOLUMNWIDTH message retrieves the width of a column in report or list view. You can send this message explicitly or by using the ListView_GetColumnWidth macro.

LVM_GETCOLUMNWIDTH

wParam = (WPARAM) (int) iCol;

lParam = 0;

Parameters

iCol

Index of the column. This parameter is ignored in list view.

Return Values

Returns the column width if successful or zero otherwise.

See Also

ListView_GetColumnWidth


LVM_GETCOUNTPERPAGE

The LVM_GETCOUNTPERPAGE message calculates the number of items that can fit vertically in the visible area of a list view control when in list or report view. Only fully-visible items are counted. You can send this message explicitly, or by using the ListView_GetCountPerPage macro.

LVM_GETCOUNTPERPAGE

wParam = 0;

lParam = 0;

Return Values

Returns the number of fully-visible items if successful. If the current view is icon or small icon view, the return value is the total number of items in the list view control.

See Also

ListView_GetCountPerPage


LVM_GETEDITCONTROL

The LVM_GETEDITCONTROL message retrieves the handle to the edit control being used to edit a list view item’s text. You can send this message explicitly or by using the ListView_GetEditControl macro.

LVM_GETEDITCONTROL

wParam = 0;

lParam = 0;

Return Values

Returns the handle to the edit control if successful or NULL otherwise.

Remarks

If no label is being edited, the return value is NULL. The edit control is not created until after the LVN_BEGINLABELEDIT notification message is sent.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it. To cancel editing, you can send the list view control a WM_CANCELMODE message.

The list view item being edited is the currently focused item — that is, the item in the focused state. To find an item based on its state, use the LVM_GETNEXTITEM message.

See Also

ListView_GetEditControl, LVN_BEGINLABELEDIT, LVM_GETNEXTITEM, WM_CANCELMODE


LVM_GETIMAGELIST

The LVM_GETIMAGELIST message retrieves the handle to an image list used for drawing list view items. You can send this message explicitly or by using the ListView_GetImageList macro.

LVM_GETIMAGELIST

wParam = (WPARAM) (int) iImageList;

lParam = 0;

Parameters

iImageList

Image list to retrieve. This parameter can be one of the following values:

Value	Meaning
LVSIL_NORMAL	Image list with large icons
LVSIL_SMALL	Image list with small icons
LVSIL_STATE	Image list with state images
Return Values

Returns the handle of the specified image list if successful or NULL otherwise.

See Also

ListView_GetImageList


LVM_GETISEARCHSTRING [New - Windows NT]
LVM_GETISEARCHSTRING

[New - Windows NT]

The LVM_GETISEARCHSTRING message retrieves the incremental search string of a list-view control. You can send this message explicitly or by using the ListView_GetISearchString macro.

LVM_GETISEARCHSTRING

wParam = 0;

lParam = (LPARAM) (LPSTR) lpsz;

Parameters

lpsz

Pointer to a buffer that receives the incremental search string.

Return Values

Returns the number of characters in the incremental search string, or zero if the list-view control is not in incremental search mode.

Remarks

The incremental search string is the character sequence that the user types while the list view has the input focus. Each time the user types a character, the system appends the character to the search string and then searches for a matching item. If the system finds a match, it selects the item and, if necessary, scrolls it into view.

A timeout period is associated with each character that the user types. If the timeout period elapses before the user types another character, the incremental search string is reset.

See Also

ListView_GetISearchString


LVM_GETITEM

The LVM_GETITEM message retrieves some or all of a list view item’s attributes. You can send this message explicitly or by using the ListView_GetItem macro.

LVM_GETITEM

wParam = 0;

lParam = (LPARAM) (LV_ITEM FAR*) pitem;

Parameters

pitem

Pointer to an LV_ITEM structure that specifies the information to retrieve and receives information about the list view item.

When the message is sent, the iItem and iSubItem members identify the item or subitem to retrieve information about and the mask member specifies which attributes to retrieve. For a list of possible values, see the description of the LV_ITEM structure.

If the mask member specifies the LVIF_TEXT value, the pszText member must contain the pointer to the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

If the mask member specifies the LVIF_STATE value, the stateMask member specifies which item states are to be returned.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_GetItem, LV_ITEM


LVM_GETITEMCOUNT

The LVM_GETITEMCOUNT message retrieves the number of items in a list view control. You can send this message explicitly or by using the ListView_GetItemCount macro.

LVM_GETITEMCOUNT

wParam = 0;

lParam = 0;

Return Values

Returns the number of items.

See Also

ListView_GetItemCount


LVM_GETITEMPOSITION

The LVM_GETITEMPOSITION message retrieves the position of a list view item. You can send this message explicitly or by using the ListView_GetItemPosition macro.

LVM_GETITEMPOSITION

wParam = (WPARAM) (int) i;

lParam = (LPARAM) (POINT FAR *) ppt;

Parameters

i

Index of the list view item.

ppt

Pointer to a POINT structure that receives the position of the item’s upper-left corner, in view coordinates.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_GetItemPosition, POINT


LVM_GETITEMRECT

The LVM_GETITEMRECT message retrieves the bounding rectangle for all or part of an item in the current view. You can send this message explicitly or by using the ListView_GetItemRect macro.

LVM_GETITEMRECT

wParam = (WPARAM) (int) i;

lParam = (LPARAM) (LPRECT) prc;

Parameters

i

Index of the list view item.

prc

Pointer to a RECT structure that receives the bounding rectangle. When the message is sent, the left member of this structure contains the value of the code parameter.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

This parameter is specified by the left member of the RECT structure pointed to by prc.

See Also

ListView_GetItemRect, RECT


LVM_GETITEMSPACING

The LVM_GETITEMSPACING message determines the spacing between items in a list view control. You can send this message explicitly or by using the ListView_GetItemSpacing macro.

LVM_GETITEMSPACING

wParam = (WPARAM) (BOOL) fSmall;

lParam = 0;

Parameters

fSmall

View to retrieve the item spacing for. This parameter is TRUE for small icon view, or FALSE for icon view.

Return Values

Returns the amount of spacing between items.

See Also

ListView_GetItemSpacing


LVM_GETITEMSTATE

The LVM_GETITEMSTATE message retrieves the state of a list view item. You can send this message explicitly or by using the ListView_GetItemState macro.

LVM_GETITEMSTATE

wParam = (WPARAM) (int) i;

lParam = (LPARAM) (UINT) mask;

Parameters

hwnd

Handle to the list view control.

i

Index of the list view item.

mask

Mask that specifies which of the item’s state flags to return.

Return Values

Returns the item’s state flags.

See Also

ListView_GetItemState


LVM_GETITEMTEXT

The LVM_GETITEMTEXT message retrieves the text of a list view item or subitem. You can send this message explicitly or by using the ListView_GetItemText macro.

LVM_GETITEMTEXT

wParam = (WPARAM) (int) iItem;

lParam = (LPARAM) (LV_ITEM FAR *) pitem;

Parameters

iItem

Index of the list view item.

pitem

Pointer to an LV_ITEM structure. The iSubItem member specifies the index of a subitem, or it can be zero to get the item label. The pszText member points to a buffer that receives the text, and the cchTextMax member specifies the size of the buffer.

Return Values

If you send this message explicitly, it returns the length of the retrieved string.

If you can send this message implicitly by using the ListView_GetItemText macro, there is no return value.

See Also

ListView_GetItemText, LV_ITEM


LVM_GETNEXTITEM

The LVM_GETNEXTITEM message searches for a list view item that has the specified properties and bears the specified relationship to a specified item. You can send this message explicitly or by using the ListView_GetNextItem macro.

LVM_GETNEXTITEM

wParam = (WPARAM) (int) iStart;

lParam = MAKELPARAM((UINT) flags, 0);

Parameters

iStart

Index of the item to begin the searching with, or −1 to find the first item that matches the specified flags. The specified item itself is excluded from the search.

flags

Geometric relation of the requested item to the specified item and, if specified, the state of the requested item.

The geometric relation can be one of the following values:

Value	Meaning
LVNI_ABOVE	Searches for an item that is above the specified item.
LVNI_ALL	Searches for a subsequent item by index (the default value).
LVNI_BELOW	Searches for an item that is below the specified item.
LVNI_TOLEFT	Searches for an item to the left of the specified item.
LVNI_TORIGHT	Searches for an item to the right of the specified item.
The state can be zero, or it can be one or more of the following values:

Value	Meaning
LVNI_CUT	The item has the LVIS_CUT state flag set.
LVNI_DROPHILITED	The item has the LVIS_DROPHILITED state flag set.
LVNI_FOCUSED	The item has the LVIS_FOCUSED state flag set.
LVNI_SELECTED	The item has the LVIS_SELECTED state flag set.
If an item does not have all of the specified state flags set, the search continues with the next item.

Return Values

Returns the index of the next item if successful or −1 otherwise.

See Also

ListView_GetNextItem


LVM_GETORIGIN

The LVM_GETORIGIN message retrieves the current view origin for a list view control. You can send this message explicitly or by using the ListView_GetOrigin macro.

LVM_GETORIGIN

wParam = 0;

lParam = (LPARAM) (LPPOINT) lpptOrg;

Parameters

lpptOrg

Pointer to a POINT structure that receives the view origin.

Return Values

Returns TRUE if successful or FALSE if the current view is list or report view.

See Also

ListView_GetOrigin, POINT


LVM_GETSELECTEDCOUNT

The LVM_GETSELECTEDCOUNT message determines the number of selected items in a list view control. You can send this message explicitly or by using the ListView_GetSelectedCount macro.

LVM_GETSELECTEDCOUNT

wParam = 0;

lParam = 0;

Return Values

Returns the number of selected items.

See Also

ListView_GetSelectedCount


LVM_GETSTRINGWIDTH

The LVM_GETSTRINGWIDTH message determines the width of a specified string, using the specified list view control’s current font. You can send this message explicitly or by using the ListView_GetStringWidth macro.

LVM_GETSTRINGWIDTH

wParam = 0;

lParam = (LPARAM) (LPCSTR) psz;

Parameters

psz

Pointer to a null-terminated string.

Return Values

Returns the string width if successful or zero otherwise.

Remarks

The LVM_GETSTRINGWIDTH message returns the exact width, in pixels, of the specified string. If you use the returned string width as the column width in the LVM_SETCOLUMNWIDTH message, the string will be truncated. To get the column width that can contain the string without truncating it, you must add padding to the returned string width.

See Also

ListView_GetStringWidth, LVM_SETCOLUMNWIDTH


LVM_GETTEXTBKCOLOR

The LVM_GETTEXTBKCOLOR message retrieves the text background color of a list view control. You can send this message explicitly or by using the ListView_GetTextBkColor macro.

LVM_GETTEXTBKCOLOR

wParam = 0;

lParam = 0;

Return Values

Returns the background color of the text.

See Also

ListView_GetTextBkColor


LVM_GETTEXTCOLOR

The LVM_GETTEXTCOLOR message retrieves the text color of a list view control. You can send this message explicitly or by using the ListView_GetTextColor macro.

LVM_GETTEXTCOLOR

wParam = 0;

lParam = 0;

Return Values

Returns the text color.

See Also

ListView_GetTextColor


LVM_GETTOPINDEX

The LVM_GETTOPINDEX message retrieves the index of the topmost visible item when in list or report view. You can send this message explicitly or by using the ListView_GetTopIndex macro.

LVM_GETTOPINDEX

wParam = 0;

lParam = 0;

Return Values

Returns the index of the item if successful or zero if the list view control is in icon or small icon view.

See Also

ListView_GetTopIndex


LVM_GETVIEWRECT

The LVM_GETVIEWRECT message retrieves the bounding rectangle of all items in the list view control. The list view must be in icon or small icon view. You can send this message explicitly or by using the ListView_GetViewRect macro.

LVM_GETVIEWRECT

wParam = 0;

lParam = (LPARAM) (RECT FAR *) prc;

Parameters

prc

Pointer to a RECT structure that receives the bounding rectangle. All coordinates are relative to the visible area of the list view control.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_GetViewRect, RECT


LVM_HITTEST

The LVM_HITTEST message determines which list view item, if any, is at a specified position. You can send this message explicitly or by using the ListView_HitTest macro.

LVM_HITTEST

wParam = 0;

lParam = (LPARAM) (LV_HITTESTINFO FAR *) pinfo;

Parameters

pinfo

Pointer to an LV_HITTESTINFO structure that contains the position to hit test and receives information about the results of the hit test.

Return Values

Returns the index of the item at the specified position, if any, or −1 otherwise.

See Also

ListView_HitTest, LV_HITTESTINFO


LVM_INSERTCOLUMN

The LVM_INSERTCOLUMN message inserts a new column in a list view control. You can send this message explicitly or by using the ListView_InsertColumn macro.

LVM_INSERTCOLUMN

wParam = (WPARAM) (int) iCol;

lParam = (LPARAM) (const LV_COLUMN FAR *) pcol;

Parameters

iCol

Index of the new column.

pcol

Pointer to an LV_COLUMN structure that contains the attributes of the new column.

Return Values

Returns the index of the new column if successful or −1 otherwise.

See Also

ListView_InsertColumn, LV_COLUMN


LVM_INSERTITEM

The LVM_INSERTITEM message inserts a new item in a list view control. You can send this message explicitly or by using the ListView_InsertItem macro.

LVM_INSERTITEM

wParam = 0;

lParam = (LPARAM) (const LV_ITEM FAR *) pitem;

Parameters

pitem

Pointer to an LV_ITEM structure that specifies the attributes of the list view item. The iItem member specifies the index of the new item.

You cannot use ListView_InsertItem or LVM_INSERTITEM to insert subitems; the iSubItem member of the LV_ITEM structure must be zero.

Return Values

Returns the index of the new item if successful or −1 otherwise.

Remarks

If a list view control has either the LVS_SORTASCENDING or LVS_SORTDESCENDING window style, an LVM_INSERTITEM message will fail if you try to insert an item that has LPSTR_TEXTCALLBACK as the pszText member of its LV_ITEM structure.

See Also

ListView_InsertItem, LV_ITEM


LVM_REDRAWITEMS

The LVM_REDRAWITEMS message forces a list view control to redraw a range of items. You can send this message explicitly or by using the ListView_RedrawItems macro.

LVM_REDRAWITEMS

wParam = (int) iFirst;  // index of first item to redraw

lParam = (int) iLast;  // index of last item to redraw

Parameters

iFirst

Index of the first item to redraw.

iLast

Index of the last item to redraw.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The specified items are not actually redrawn until the list view window receives a WM_PAINT message to repaint. To repaint immediately, call the UpdateWindow function after using this macro.

See Also

ListView_RedrawItems, UpdateWindow, WM_PAINT


LVM_SCROLL

The LVM_SCROLL message scrolls the content of a list view control. You can send this message explicitly or by using the ListView_Scroll macro.

LVM_SCROLL

wParam = (int) dx;  // amount of horizontal scrolling, in pixels or columns

lParam = (int) dy;  // amount of vertical scrolling, in pixels

Parameters

dx

Integer value that specifies the amount of horizontal scrolling.

If the view type of the list view control is icon view, small icon view, or report view, this value specifies the number of pixels to scroll. If the view type of the list view control is list view, this value specifies the number of columns to scroll.

dy

Integer value that specifies the amount of vertical scrolling.

If the view type of the list view control is icon view, small icon view, or list view, this value specifies the number of pixels to scroll. If the view type of the list view control is report view, this value specifies the number of lines to scroll.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_Scroll


LVM_SETBKCOLOR

The LVM_SETBKCOLOR message sets the background color of a list view control. You can send this message explicitly or by using the ListView_SetBkColor macro.

LVM_SETBKCOLOR

wParam = 0;

lParam = (LPARAM) (COLORREF) clrBk;

Parameters

clrBk

Background color to set or the CLR_NONE value for no background color. List view controls with background colors redraw themselves significantly faster than those without background colors.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_SetBkColor


LVM_SETCALLBACKMASK

The LVM_SETCALLBACKMASK message changes the callback mask for a list view control. You can send this message explicitly or by using the ListView_SetCallbackMask macro.

LVM_SETCALLBACKMASK

wParam = (WPARAM) (UINT) mask;

lParam = 0;

Parameters

hwnd

Handle to the list view control.

mask

Specifies the value of the callback mask. The bits of the mask indicate the item states or images for which the application stores the current state data. This value can be any combination of the following constants:

Value	Meaning
LVIS_CUT	The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED	The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED	The item has the focus.
LVIS_SELECTED	The item is selected.
LVIS_OVERLAYMASK	The application stores the image list index of the current overlay image for each item.
LVIS_STATEIMAGEMASK	The application stores the image list index of the current state image for each item.
For more information about overlay images and state images, see List View Image Lists.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The callback mask of a list view control is a set of bit flags that specify the item states for which the application, rather than the control, stores the current data. The callback mask applies to all of the control’s items, unlike the callback item designation, which applies to a specific item. The callback mask is zero by default, meaning that the list view control stores all item state information. After creating a list view control and initializing its items, you can send the LVM_SETCALLBACKMASK message to change the callback mask. To get the current callback mask, send the LVM_GETCALLBACKMASK message.

For more information, see Callback Items and the Callback Mask.

See Also

ListView_SetCallbackMask, LVM_GETCALLBACKMASK, LVN_GETDISPINFO


LVM_SETCOLUMN

The LVM_SETCOLUMN message sets the attributes of a list view column. You can send this message explicitly or by using the ListView_SetColumn macro.

LVM_SETCOLUMN

wParam = (WPARAM) (int) iCol;

lParam = (LPARAM) (const LV_COLUMN FAR *) pcol;

Parameters

iCol

Index of the column.

pcol

Pointer to an LV_COLUMN structure that contains the new column attributes. The mask member specifies which column attributes to set.

If the mask member specifies the LVCF_TEXT value, the pszText member is the pointer to a null-terminated string and the cchTextMax member is ignored.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_SetColumn, LV_COLUMN


LVM_SETCOLUMNWIDTH

The LVM_SETCOLUMNWIDTH message changes the width of a column in report or list view. You can send this message explicitly or by using the ListView_SetColumnWidth macro.

LVM_SETCOLUMNWIDTH

wParam = (WPARAM) (int) iCol;

lParam = MAKELPARAM((int) cx, 0);

Parameters

iCol

Index of the column. In list view, the iCol parameter must be −1.

cx

New width of the column, in list view coordinates, or one of the following values:

Value	Meaning
LVSCW_AUTOSIZE	Automatically sizes the column.
LVSCW_AUTOSIZE_USEHEADER	Automatically sizes the column to fit the header text.
See Also

ListView_SetColumnWidth


LVM_SETIMAGELIST

The LVM_SETIMAGELIST message assigns an image list to a list view control. You can send this message explicitly or by using the ListView_SetImageList macro.

LVM_SETIMAGELIST

wParam = (WPARAM) (int) iImageList;

lParam = (LPARAM) (HIMAGELIST) himl;

Parameters

himl

Handle to the image list to assign.

iImageList

Type of image list. This parameter can be one of the following values:

Value	Meaning
LVSIL_NORMAL	Image list with large icons
LVSIL_SMALL	Image list with small icons
LVSIL_STATE	Image list with state images
Return Values

Returns the handle of the image list previously associated with the control if successful; NULL otherwise.

See Also

ListView_SetImageList


LVM_SETITEM

The LVM_SETITEM message sets some or all of a list view item’s attributes. You can send this message explicitly or by using the ListView_SetItem macro.

LVM_SETITEM

wParam = 0;

lParam = (LPARAM) (const LV_ITEM FAR *) pitem;

Parameters

pitem

Pointer to an LV_ITEM structure that contains the new item attributes. The iItem and iSubItem members identify the item or subitem, and the mask member specifies which attributes to set.

If the mask member specifies the LVIF_TEXT value, the pszText member is the pointer to a null-terminated string and the cchTextMax member is ignored.

If the mask member specifies the LVIF_STATE value, the stateMask member specifies which item states to change and the state member contains the values for those states.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_SetItem, LV_ITEM


LVM_SETITEMCOUNT

The LVM_SETITEMCOUNT message prepares a list view control for adding a large number of items. You can send this message explicitly or by using the ListView_SetItemCount macro.

LVM_SETITEMCOUNT

wParam = (WPARAM) (int) cItems;

lParam = 0;

Parameters

cItems

Number of items that the list view control will ultimately contain.

Return Values

No return value.

Remarks

By sending the LVM_SETITEMCOUNT message before adding a large number of items, you enable a list view control to reallocate its internal data structures only once rather than every time you add an item.

See Also

ListView_SetItemCount


LVM_SETITEMPOSITION

The LVM_SETITEMPOSITION message moves an item to a specified position in a list view control, which must be in icon or small icon view. You can send this message explicitly or by using the ListView_SetItemPosition macro.

LVM_SETITEMPOSITION

wParam = (LPARAM) (int) i;

lParam = MAKELPARAM((int) x, (int) y);

Parameters

i

Index of the list view item.

x and y

New position of the item’s upper-left corner, in view coordinates.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

If the list view control has the LVS_AUTOARRANGE style, the list view control is arranged after the position of the item is set.

See Also

ListView_SetItemPosition


LVM_SETITEMPOSITION32

The LVM_SETITEMPOSITION32 message moves an item to a specified position in a list view control, which must be in icon or small icon view. This message differs from the LVM_SETITEMPOSITION message in that it uses 32-bit coordinates. You can send this message explicitly or by using the ListView_SetItemPosition32 macro.

LVM_SETITEMPOSITION32

wParam = (WPARAM) (int) iItem;

lParam = (LPARAM) (LPPOINT) lpptNewPos;

Parameters

iItem

Index of the list view item to set the position of.

lpptNewPos

Pointer to a POINT structure that contains the new position of the item, in list view coordinates.

Return Values

No return value.

If you send this message by using the ListView_SetItemPosition32 macro, it has no return value.

See Also

ListView_SetItemPosition32, LVM_SETITEMPOSITION, POINT


LVM_SETITEMSTATE

The LVM_SETITEMSTATE message changes the state of an item in a list view control. You can explicitly send this message or by using the ListView_SetItemState macro.

LVM_SETITEMSTATE

wParam = (WPARAM) (int) i;

lParam = (LPARAM) (LV_ITEM FAR *) pitem;

Parameters

i

Index of the list view item.

pitem

Pointer to an LV_ITEM structure. The stateMask member specifies which state bits to change, and the state member contains the new values for those bits. The other members are ignored.

Return Values

If you send this message explicitly, it returns TRUE if successful or FALSE otherwise.

If you send this message implicitly by using the ListView_SetItemState macro, there is no return value.

See Also

ListView_SetItemState, LV_ITEM


LVM_SETITEMTEXT

The LVM_SETITEMTEXT message changes the text of a list view item or subitem. You can send this message explicitly or by using the ListView_SetItemText macro.

LVM_SETITEMTEXT

wParam = (WPARAM) (int) i;

lParam = (LPARAM) (LV_ITEM FAR *) pitem;

Parameters

i

Index of the list view item.

pitem

Pointer to an LV_ITEM structure. The iSubItem member is the index of the subitem, or it can be zero to set the item label. The pszText member is the pointer to a null-terminated string containing the new text; it can also be NULL.

Return Values

If you send this message explicitly, it returns TRUE if successful or FALSE otherwise.

If you send this message implicitly by using the ListView_SetItemText macro, there is no return value.

See Also

ListView_SetItemText, LV_ITEM


LVM_SETTEXTBKCOLOR

The LVM_SETTEXTBKCOLOR message sets the background color of text in a list view control. You can send this message explicitly or by using the ListView_SetTextBkColor macro.

LVM_SETTEXTBKCOLOR

wParam = 0;

lParam = (LPARAM) (COLORREF) clrText;

Parameters

clrText

New text color.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_SetTextBkColor


LVM_SETTEXTCOLOR

The LVM_SETTEXTCOLOR message sets the text color of a list view control. You can send this message explicitly or by using the ListView_SetTextColor macro.

LVM_SETTEXTCOLOR

wParam = 0;

lParam = (LPARAM) (COLORREF) clrText;

Parameters

clrText

New text color.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_SetTextColor


LVM_SORTITEMS

The LVM_SORTITEMS message uses an application-defined comparison function to sort the items of a list view control. The index of each item changes to reflect the new sequence. You can send this message explicitly or by using the ListView_SortItems macro.

LVM_SORTITEMS

wParam = (WPARAM) (LPARAM) lParamSort;

lParam = (LPARAM) (PFNLVCOMPARE) pfnCompare;

Parameters

lParamSort

Application-defined value that is passed to the comparison function.

pfnCompare

Pointer to the application-defined comparison function. The comparison function is called during the sort operation each time the relative order of two list items needs to be compared.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The comparison function has the following form:

int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2,

LPARAM lParamSort);

The lParam1 parameter is the 32-bit value associated with the first item being compared; and the lParam2 parameter is the value associated with the second item. These are the values that were specified in the lParam member of the items’ LV_ITEM structure when they were inserted into the list. The lParamSort parameter is the same value passed to the LVM_SORTITEMS message.

The comparison function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

See Also

ListView_SortItems, LV_ITEM


LVM_UPDATE

The LVM_UPDATE message updates a list view item. If the list view control has the LVS_AUTOARRANGE style, this macro causes the list view control to be arranged. You can send this message explicitly or by using the ListView_Update macro.

LVM_UPDATE

wParam = (WPARAM) iItem;

lParam = 0;

Parameters

iItem

Index of the item to update.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

ListView_Update


LVN_BEGINDRAG

The LVN_BEGINDRAG notification message notifies a list view control’s parent window that a drag-and-drop operation involving the left mouse button is being initiated. This notification message is sent in the form of a WM_NOTIFY message.

LVN_BEGINDRAG

pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv

Pointer to an NM_LISTVIEW structure. The iItem member identifies the item being dragged, and the other members are zero.

Return Values

No return value.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_BEGINLABELEDIT

The LVN_BEGINLABELEDIT notification message notifies a list view control’s parent window about the start of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

LVN_BEGINLABELEDIT

pdi = (LV_DISPINFO FAR *) lParam;

Parameters

pdi

Pointer to an LV_DISPINFO structure. The item member of this structure is an LV_ITEM structure whose iItem member identifies the item being edited.

Return Values

To allow the user to edit the label, return FALSE.

To prevent the user from editing the label, return TRUE.

Remarks

When the user begins editing an item label, the parent window of the list view control receives an LVN_BEGINLABELEDIT notification message. When the user cancels or completes the editing, the parent window receives an LVN_ENDLABELEDIT notification message.

See Also

LV_DISPINFO, LV_ITEM, LVN_ENDLABELEDIT, WM_NOTIFY


LVN_BEGINRDRAG

The LVN_BEGINRDRAG notification message notifies a list view control’s parent window that a drag-and-drop operation involving the right mouse button is being initiated. This notification message is sent in the form of a WM_NOTIFY message.

LVN_BEGINRDRAG

pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv

Pointer to an NM_LISTVIEW structure. The iItem member identifies the item being dragged, and the other members are zero.

Return Values

No return value.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_COLUMNCLICK

The LVN_COLUMNCLICK notification message notifies a list view control’s parent window that a column was clicked. This notification message is sent in the form of a WM_NOTIFY message.

LVN_COLUMNCLICK

pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv

Pointer to an NM_LISTVIEW structure. The iItem member is  − 1, and the iSubItem member identifies the column. All other members are zero.

Return Values

No return value.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_DELETEALLITEMS

The LVN_DELETEALLITEMS notification message notifies a list view control’s parent window that all items in the control were deleted. This notification message is sent in the form of a WM_NOTIFY message.

LVN_DELETEALLITEMS

pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv

Pointer to an NM_LISTVIEW structure. The iItem member is  − 1, and the other members are zero.

Return Values

No return value.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_DELETEITEM

The LVN_DELETEITEM notification message notifies a list view control’s parent window that an item was deleted. This notification message is sent in the form of a WM_NOTIFY message.

LVN_DELETEITEM

pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv

Pointer to an NM_LISTVIEW structure. The iItem member identifies the deleted item, and the other members are zero.

Return Values

No return value.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_ENDLABELEDIT

The LVN_ENDLABELEDIT notification message notifies a list view control’s parent window about the end of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

LVN_ENDLABELEDIT

pdi = (LV_DISPINFO FAR *) lParam;

Parameters

pdi

Pointer to an LV_DISPINFO structure. The item member of this structure is an LV_ITEM structure whose iItem member identifies the item being edited.

If the user cancels editing, the pszText member of the LV_ITEM structure is NULL; otherwise, pszText is a pointer to the edited text.

Return Values

If the pszText member of the LV_ITEM structure is non-NULL, return TRUE to set the item’s label to the edited text. Return FALSE to reject the edited text and revert to the original label.

If the pszText member of the LV_ITEM structure is NULL, the return value is ignored.

Remarks

When the user begins editing an item label, the parent window of the list view control receives an LVN_BEGINLABELEDIT notification message. When the user cancels or completes the editing, the parent window receives an LVN_ENDLABELEDIT notification message.

The pszText member of the LV_ITEM structure contained within the LV_DISPINFO structure pointed to by pdi contains a valid value when the LVN_ENDLABELEDIT message is sent, regardless of whether the LVIF_TEXT flag is set in the mask member of the LV_ITEM structure. Note that NULL is a valid value for pszText, indicating the cancellation of the label editing operation.

See Also

LVN_BEGINLABELEDIT, LV_DISPINFO, LV_ITEM, WM_NOTIFY


LVN_GETDISPINFO

The LVN_GETDISPINFO notification message is sent by a list view control to its parent window. It is a request for the parent window to provide information needed to display or sort a list view item. The LVN_GETDISPINFO notification message is sent in the form of a WM_NOTIFY message.

LVN_GETDISPINFO

pnmv = (LV_DISPINFO FAR *) lParam;

Parameters

pnmv

Pointer to an LV_DISPINFO structure. On input, the LV_ITEM structure contained in this structure specifies the type of information required and identifies the item or subitem of interest.

Use the LV_ITEM structure to return the requested information to the control. If your message handler sets the LVIF_DI_SETITEM flag in the mask member of the LV_ITEM.structure, the list view control stores the requested information, and will not ask for it again.

Return Values

No return value.

Remarks

A list view control sends the LVN_GETDISPINFO message for items for which the application stores callback information. The information can be the text or icon information stored for a callback item. It can also be item state information specified by the list view control’s callback mask.

For more information, see Callback Items and the Callback Mask.

See Also

LV_DISPINFO, LV_ITEM, LVN_SETDISPINFO, WM_NOTIFY


LVN_INSERTITEM

The LVN_INSERTITEM notification message notifies a list view control’s parent window that a new item was inserted. This notification message is sent in the form of a WM_NOTIFY message.

LVN_INSERTITEM

pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv

Pointer to an NM_LISTVIEW structure. The iItem member identifies the new item, and the other members are zero.

Return Values

No return value.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_ITEMCHANGED

The LVN_ITEMCHANGED notification message notifies a list view control’s parent window that an item has changed. This notification message is sent in the form of a WM_NOTIFY message.

LVN_ITEMCHANGED

pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv

Pointer to an NM_LISTVIEW structure that identifies the item and specifies which of its attributes have changed.

Return Values

No return value.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_ITEMCHANGING

The LVN_ITEMCHANGING notification message notifies a list view control’s parent window that an item is changing. This notification message is sent in the form of a WM_NOTIFY message.

LVN_ITEMCHANGING

pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv

Pointer to an NM_LISTVIEW structure that identifies the item and specifies which of its attributes are changing.

Return Values

Returns TRUE to prevent the change or FALSE to allow the change.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_KEYDOWN

The LVN_KEYDOWN notification message notifies a list view control’s parent window that a key has been pressed. This notification message is sent in the form of a WM_NOTIFY message.

LVN_KEYDOWN

pnkd = (LV_KEYDOWN FAR *) lParam;

Parameters

pnkd

Pointer to an LV_KEYDOWN structure.

Return Values

No return value.

See Also

LV_KEYDOWN, WM_NOTIFY


LVN_SETDISPINFO

The LVN_SETDISPINFO notification message notifies a list view control’s parent window that it must update the information it maintains for an item. This notification message is sent in the form of a WM_NOTIFY message.

LVN_SETDISPINFO

pnmv = (LV_DISPINFO FAR *) lParam;

Parameters

pnmv

Pointer to an LV_DISPINFO structure that specifies information for the changed item.

Return Values

No return value.

Remarks

The pszText member of the LV_ITEM structure contained within the LV_DISPINFO structure pointed to by pnmv contains a valid value when the LVN_SETDISPINFO message is sent, regardless of whether the LVIF_TEXT flag is set in the mask member of the LV_ITEM structure.

See Also

LV_DISPINFO, LV_ITEM, LVN_GETDISPINFO, WM_NOTIFY


NIM_ADD

Adds an icon to the taskbar status area.

fAdded = Shell_NotifyIcon(NIM_ADD, pnid);

Parameters

pnid

Address of an NOTIFYICONDATA structure that contains information about the icon to add.

Return Values

Returns TRUE if successful or FALSE otherwise.


NIM_DELETE

Deletes an icon from the taskbar status area.

fDeleted = Shell_NotifyIcon(NIM_DELETE, pnid);

Parameters

pnid

Address of an NOTIFYICONDATA structure that contains information about the icon to delete.

Return Values

Returns TRUE if successful or FALSE otherwise.


NIM_MODIFY

Changes the icon, tooltip text, or notification message identifier for an icon in the taskbar status area.

fModified = Shell_NotifyIcon(NIM_MODIFY, pnid);

Parameters

pnid

Address of an NOTIFYICONDATA structure that contains the information used to change the icon, tooltip text, or notification message identifier for the icon.

Return Values

Returns TRUE if successful or FALSE otherwise.


NM_CLICK

The NM_CLICK notification message notifies the parent window of a control that the user has clicked the left mouse button within the control. NM_CLICK is sent in the form of a WM_NOTIFY message.

NM_CLICK

pnmh = (NMHDR FAR *) lParam;


NM_DBLCLK

The NM_DBLCLK notification message notifies the parent window of a control that the user has double-clicked the left mouse button within the control. NM_DBLCLK is sent in the form of a WM_NOTIFY message.

NM_DBLCLK

pnmh = (NMHDR FAR *) lParam;


NM_KILLFOCUS

The NM_KILLFOCUS notification message notifies the parent window of a control that the control has lost the input focus. NM_KILLFOCUS is sent in the form of a WM_NOTIFY message.

NM_KILLFOCUS

pnmh = (NMHDR FAR *) lParam;


NM_OUTOFMEMORY

The NM_OUTOFMEMORY notification message notifies the parent window of a control that the control could not complete an operation because there was not enough memory available. NM_OUTOFMEMORY is sent in the form of a WM_NOTIFY message.

NM_OUTOFMEMORY

pnmh = (NMHDR FAR *) lParam;


NM_RCLICK

The NM_RCLICK notification message notifies the parent window of a control that the user has clicked the right mouse button within the control. NM_RCLICK is sent in the form of a WM_NOTIFY message.

NM_RCLICK

pnmh = (NMHDR FAR *) lParam;


NM_RDBLCLK

The NM_RDBLCLK notification message notifies the parent window of a control that the user has double-clicked the right mouse button within the control. NM_RDBLCLK is sent in the form of a WM_NOTIFY message.

NM_RDBLCLK

pnmh = (NMHDR FAR *) lParam;


NM_RETURN

The NM_RETURN notification message notifies the parent window of a control that the control has the input focus and that the user has pressed the ENTER key. NM_RETURN is sent in the form of a WM_NOTIFY message.

NM_RETURN

pnmh = (NMHDR FAR *) lParam;


NM_SETFOCUS

The NM_SETFOCUS notification message notifies the parent window of a control that the control has received the input focus. NM_SETFOCUS is sent in the form of a WM_NOTIFY message.

NM_SETFOCUS

pnmh = (NMHDR FAR *) lParam;


PBM_DELTAPOS

The PBM_DELTAPOS message advances the current position of a progress bar by a specified increment and redraws the bar to reflect the new position.

PBM_DELTAPOS

wParam = (WPARAM) nIncrement

lParam = 0;

Parameters

nIncrement

Amount to advance the position.

Return Values

Returns the previous position.


PBM_SETPOS

The PBM_SETPOS message sets the current position for a progress bar and redraws the bar to reflect the new position.

PBM_SETPOS

wParam = (WPARAM) nNewPos;

lParam = 0;

Parameters

nNewPos

New position.

Return Values

Returns the previous position.


PBM_SETRANGE

The PBM_SETRANGE message sets the minimum and maximum values for a progress bar and redraws the bar to reflect the new range.

PBM_SETRANGE

wParam = 0;

lParam = MAKELPARAM(nMinRange, nMaxRange);

Parameters

nMinRange

Minimum range value. By default, the minimum value is zero.

nMaxRange

Maximum range value. By default, the maximum value is 100.

Return Values

Returns the previous range values if successful, or zero otherwise. The low-order word specifies the previous minimum value, and the high-order word specifies the previous maximum value.


PBM_SETSTEP

The PBM_SETSTEP message specifies the step increment for a progress bar. The step increment is the amount by which the progress bar increases its current position whenever it receives a PBM_STEPIT message. By default, the step increment is set to 10.

PBM_SETSTEP

wParam = (WPARAM) nStepInc;

lParam = 0;

Parameters

nStepInc

New step increment.

Return Values

Returns the previous step increment.

See Also

PBM_STEPIT


PBM_STEPIT

The PBM_STEPIT message advances the current position for a progress bar by the step increment and redraws the bar to reflect the new position. An application sets the step increment by sending the PBM_SETSTEP message.

PBM_STEPIT

wParam = 0;

lParam = 0;

Return Values

Returns the previous position.

Remarks

When the position exceeds the maximum range value, this message resets the current position so that the progress indicator starts over again from the beginning.

See Also

PBM_SETSTEP


PBT_APMBATTERYLOW

The PBT_APMBATTERYLOW message is sent to notify applications that battery power is low. A window receives this message through the WM_POWERBROADCAST message.

PBT_APMBATTERYLOW

dwData = (DWORD) lParam;

Parameters

dwData

Reserved, must be zero.

Return Values

No return value.

Remarks

This message is broadcast when a system’s APM BIOS signals an APM battery low notification. Because some APM BIOS implementations do not provide battery low notifications, this message may never be sent on some machines.

See Also

WM_POWERBROADCAST


PBT_APMOEMEVENT

The PBT_APMOEMEVENT message is sent when an APM BIOS signals an APM OEM event. A window receives this message through the WM_POWERBROADCAST message.

PBT_APMOEMEVENT

dwEventCode = (DWORD) lParam;

Parameters

dwEventCode

OEM-defined event code that was signaled by the system’s APM BIOS. OEM event codes are in the range 0200h - 02FFh.

Return Values

No return value.

Remarks

Because not all APM BIOS implementations provide OEM event notifications, this message may never be sent on some machines.

See Also

WM_POWERBROADCAST


PBT_APMPOWERSTATUSCHANGE

The PBT_APMPOWERSTATUSCHANGE message is sent when a change in the power status of the computer is detected, such as a switch from battery power to A/C or a drop in remaining battery power below a threshold. A window receives this message through the WM_POWERBROADCAST message.

dwData = (DWORD) lParam;

Parameters

dwData

Reserved; must be 0.

Return Values

No return value.

Remarks

An application should process this message by calling the GetSystemPowerStatus function to retrieve the current power status of the computer. In particular, the application should check the ACLineStatus, BatteryFlag, BatteryLifeTime, and BatteryLifePercent members of the SYSTEM_POWER_STATUS structure for any changes. This message can occur when the battery life time drops to less than 5 minutes, or when the percentage of battery life drops below 10 percent.

See Also

GetSystemPowerStatus, SYSTEM_POWER_STATUS, WM_POWERBROADCAST


PBT_APMQUERYSUSPEND

The PBT_APMQUERYSUSPEND message is sent to request permission to suspend the computer. An application that grants permission should carry out preparations for the suspension before returning. A window receives this message through the WM_POWERBROADCAST message.

Flags = (DWORD) lParam;

Parameters

Flags

Action flags. If bit 0 is 1, the application can prompt the user for directions on how to prepare for the suspension; otherwise, the application must prepare without user interaction. All other bit values are reserved.

Return Values

Return TRUE to grant the request to suspend. To deny the request, return BROADCAST_QUERY_DENY.

Remarks

An application should process this message by first determining whether permission to suspend can be granted. It must not grant permission if doing so would cause a loss of data. The application can prompt the user for directions on how to prepare for suspension only if bit 0 in the Flags parameter is set.

See Also

WM_POWERBROADCAST


PBT_APMQUERYSUSPENDFAILED

The PBT_APMQUERYSUSPENDFAILED message is sent as a notification that permission to suspend the computer was denied. This message is sent if any application or driver returned BROADCAST_QUERY_DENY to a previous PBT_APMQUERYSUSPEND message. A window receives this message through the WM_POWERBROADCAST message.

dwData = (DWORD) lParam;

Parameters

dwData

Reserved; must be zero.

Return Values

No return value.

Remarks

Applications typically respond to this message by resuming normal operation.

See Also

PBT_APMQUERYSUSPEND, WM_POWERBROADCAST


PBT_APMRESUMECRITICAL

The PBT_APMRESUMECRITICAL message is sent as a notification that the system has resumed operation after a critical suspension caused by a failing battery. A driver receives this message through the WM_POWERBROADCAST message.

dwData = (DWORD) lParam;

Parameters

dwData

Reserved; must be 0.

Return Values

No return value.

Remarks

Because a critical suspension occurs without prior notification, resources and data previously available to a driver may not be present when the driver receives this message. The driver should attempt to restore its state to the best of its ability. While in a critical suspension, the system maintains the state of the DRAM and local hard disks, but may not maintain net connections. A driver may have to take action with respect to files that were open on the network prior to the critical suspension.

This message is not sent to applications.

See Also

WM_POWERBROADCAST


PBT_APMRESUMESUSPEND

The PBT_APMRESUMESUSPEND message is sent as a notification that the system has resumed opration after being suspended. A window receives this message through the WM_POWERBROADCAST message.

dwData = (DWORD) lParam;

Parameters

dwData

Reserved; must be 0.

Return Values

No return value.

Remarks

Applications may receive this message at any time without a preceding PBT_APMSUSPEND message.

See Also

PBT_APMSUSPEND, WM_POWERBROADCAST


PBT_APMSUSPEND

The PBT_APMSUSPEND is sent immediately before the computer is suspended. This message is typically sent when all applications and installable drivers have returned TRUE to a previous PBT_APMQUERYSUSPEND message. A window receives this message through the WM_POWERBROADCAST message.

dwData = (DWORD) lParam;

Parameters

dwData

Reserved; must be 0.

Return Values

No return value.

Remarks

An application should process this message by completing all tasks necessary to save data. This message may also be sent, without a prior PBT_APMQUERYSUSPEND message, if an application or device driver uses the SetSystemPowerState function to force suspension.

See Also

PBT_APMQUERYSUSPEND, SetSystemPowerState, WM_POWERBROADCAST


PSM_ADDPAGE

The PSM_ADDPAGE message adds a new page to the end of an existing property sheet. You can send this message explicitly or by using the PropSheet_AddPage macro.

PSM_ADDPAGE

wParam = 0;

lParam = (LPARAM) (HPROPSHEETPAGE) hpage);

Parameters

hpage

Handle to the page to add. The page must have been created by a previous call to the CreatePropertySheetPage function.

Return Values

No return value.

Remarks

The property sheet is not resized to fit the new page. The new page should be no larger than the largest page currently in the property sheet.

See Also

CreatePropertySheetPage, PropSheet_AddPage


PSM_APPLY

The PSM_APPLY message simulates the choice of the Apply Now button, indicating that one or more pages have changed and the changes need to be validated and recorded. The property sheet sends the PSN_KILLACTIVE notification message to the current page. If the current page returns FALSE, the property sheet sends the PSN_APPLY notification message to all pages. You can send the PSM_APPLY message explicitly or by using the PropSheet_Apply macro.

PSM_APPLY

wParam = 0;

lParam = 0;

Return Values

Returns TRUE if all pages successfully applied the changes or FALSE otherwise.

See Also

PropSheet_Apply, PSN_APPLY, PSN_KILLACTIVE


PSM_CANCELTOCLOSE

The PSM_CANCELTOCLOSE message disables the Cancel button and changes the text of the OK button to “Close.” An application sends this message after applying a change that cannot be canceled. You can send this message explicitly or by using the PropSheet_CancelToClose macro.

PSM_CANCELTOCLOSE

wParam = 0;

lParam = 0;

Return Values

No return value.

See Also

PropSheet_CancelToClose


PSM_CHANGED

The PSM_CHANGED message informs a property sheet that information in a page has changed. The property sheet enables the Apply Now button. You can send this macro explicitly or by using the PropSheet_Changed macro.

PSM_CHANGED

wParam = (WPARAM) (HWND) hwndPage;

lParam = 0;

Parameters

hwndPage

Handle to the page that has changed.

Return Values

No return value.

See Also

PropSheet_Changed


PSM_GETCURRENTPAGEHWND

The PSM_GETCURRENTPAGEHWND message retrieves a handle to the window of the current page of a property sheet. You can send the message explicitly or by using the PropSheet_GetCurrentPageHwnd macro.

PSM_GETCURRENTPAGEHWND

wParam = 0;

lParam = 0;

Return Values

Returns a handle to the window of the current property sheet page.

Remarks

Use the PSM_GETCURRENTPAGEHWND message with modeless property sheets to determine when to destroy the dialog box. When the user selects the OK or Cancel button, PSM_GETCURRENTPAGEHWND returns NULL, and you can then use the DestroyWindow function to destroy the dialog box.

See Also

DestroyWindow, PropertySheet, PropSheet_GetCurrentPageHwnd


PSM_GETTABCONTROL

The PSM_GETTABCONTROL message retrieves the handle to the tab control of a property sheet. You can send this message explicitly or by using the PropSheet_GetTabControl macro.

PSM_GETTABCONTROL

wParam = 0;

lParam = 0;

Return Values

Returns the handle to the tab control.

See Also

PropSheet_GetTabControl


PSM_ISDIALOGMESSAGE

The PSM_ISDIALOGMESSAGE message passes a message to a property sheet dialog box and indicates whether the dialog processed the message. You can send the PSM_ISDIALOGMESSAGE message explicitly or by using the PropSheet_IsDialogMessage macro.

PSM_ISDIALOGMESSAGE

wParam = 0;

lParam = (LPARAM)pMsg;

Parameters

pMsg

Pointer to a MSG structure that contains the message to be checked.

Return Values

If the message has been processed, the return value is TRUE.

If the message has not been processed, the return value is FALSE.

Remarks

Your message loop should use the PSM_ISDIALOGMESSAGE message with modeless property sheets to pass messages to the property sheet dialog box.

If the return value indicates that the message was processed, it must not be passed to the TranslateMessage or DispatchMessage function.

See Also

DispatchMessage, MSG, PropertySheet, PropSheet_IsDialogMessage, TranslateMessage


PSM_PRESSBUTTON

The PSM_PRESSBUTTON message simulates the choice of a property sheet button. You can send this message explicitly or by using the PropSheet_PressButton macro.

PSM_PRESSBUTTON

wParam = (WPARAM) (int) iButton;

lParam = 0;

Parameters

iButton

Index of the button to choose. This parameter can be one of the following values:

Value	Meaning
PSBTN_APPLYNOW	Chooses the Apply Now button.
PSBTN_BACK	Chooses the Back button.
PSBTN_CANCEL	Chooses the Cancel button.
PSBTN_FINISH	Chooses the Finish button.
PSBTN_HELP	Chooses the Help button.
PSBTN_NEXT	Chooses the Next button.
PSBTN_OK	Chooses the OK button.
Return Values

No return value.

See Also

PropSheet_PressButton


PSM_QUERYSIBLINGS

The PSM_QUERYSIBLINGS message forwards the message to each page in the property sheet. If a page returns a nonzero value, the property sheet does not send the message to subsequent pages. You can send the PSM_QUERYSIBLINGS message explicitly or by using the PropSheet_QuerySiblings macro.

PSM_QUERYSIBLINGS

wParam = (WPARAM) param1;

lParam = (LPARAM) param2;

Parameters

param1

First application-defined parameter.

param2

Second application-defined parameter.

Return Values

Returns the nonzero value from a page in the property sheet, or zero if no page returns a nonzero value.

See Also

PropSheet_QuerySiblings


PSM_REBOOTSYSTEM

The PSM_REBOOTSYSTEM message indicates that the system needs to be restarted for the changes to take effect. An application should send this message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message. You can send the PSM_REBOOTSYSTEM message explicitly or by using the PropSheet_RebootSystem macro.

PSM_REBOOTSYSTEM

wParam = 0;

lParam = 0;

Return Values

No return value.

Remarks

This message causes the PropertySheet function to return the ID_PSREBOOTSYSTEM value, but only if the user chooses the OK button to close the property sheet. It is the application’s responsibility to reboot the system, which can be done by using the ExitWindowsEx function.

This message supersedes all PSM_RESTARTWINDOWS messages that precede or follow it.

See Also

ExitWindowsEx, PropertySheet, PropSheet_RebootSystem, PSN_APPLY, PSN_KILLACTIVE, PSM_RESTARTWINDOWS


PSM_REMOVEPAGE

The PSM_REMOVEPAGE message removes a page from a property sheet. You can send this message explicitly or by using the PropSheet_RemovePage macro.

PSM_REMOVEPAGE

wParam = (WPARAM) (int) index;

lParam = (LPARAM) (HPROPSHEETPAGE) hpage);

Parameters

hpage and index

Handle to the page to remove, and the zero-based index of the page to remove. An application can specify the handle or the index, or both. If both are specified, hpage takes precedence.

Return Values

No return value.

See Also

PropSheet_RemovePage


PSM_RESTARTWINDOWS

The PSM_RESTARTWINDOWS message indicates that Windows needs to be restarted for the changes to take effect. An application should send this message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message. You can send the PSM_RESTARTWINDOWS message explicitly or by using the PropSheet_RestartWindows macro.

PSM_RESTARTWINDOWS

wParam = 0;

lParam = 0;

Return Values

No return value.

Remarks

This message causes the PropertySheet function to return the ID_PSRESTARTWINDOWS value, but only if the user chooses the OK button to close the property sheet. It is the application’s responsibility to restart Windows, which can be done by using the ExitWindowsEx function.

See Also

ExitWindowsEx, PropertySheet, PropSheet_RestartWindows, PSN_APPLY, PSN_KILLACTIVE


PSM_SETCURSEL

The PSM_SETCURSEL message activates the given page in a property sheet. You can send this message explicitly or by using the PropSheet_SetCurSel macro.

PSM_SETCURSEL

wParam = (WPARAM) (int) index;

lParam = (LPARAM) (HPROPSHEETPAGE) hpage;

Parameters

hpage

Handle to the page to activate. An application can specify the handle or the index, or both. If both are specified, hpage takes precedence.

index

Zero-based index of the page to activate.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The window that is losing the activation receives the PSN_KILLACTIVE notification message, and the window that is gaining the activation receives the PSN_SETACTIVE notification message.

See Also

PropSheet_SetCurSel, PSN_KILLACTIVE, PSN_SETACTIVE


PSM_SETCURSELID

The PSM_SETCURSELID message activates the given page in a property sheet based on the resource identifier of the page. You can send this message explicitly or by using the PropSheet_SetCurSelByID macro.

PSM_SETCURSELID

wParam = 0;

lParam = (LPARAM) (int) id;

Parameters

id

Resource identifier of the page to activate.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The window that is losing the activation receives the PSN_KILLACTIVE notification message, and the window that is gaining the activation receives the PSN_SETACTIVE notification message.

See Also

PropSheet_SetCurSelByID, PSN_KILLACTIVE, PSN_SETACTIVE


PSM_SETFINISHTEXT

The PSM_SETFINISHTEXT message sets the text of the Finish button in a wizard property sheet, shows and enables the button, and hides the Next and Back buttons. You can send this message explicitly or by using the PropSheet_SetFinishText macro.

PSM_SETFINISHTEXT

wParam = 0;

lParam = (LPARAM) (LPSTR) lpszText;

Parameters

lpszText

Pointer to the new text for the Finish button.

Return Values

No return value.

Remarks

This message causes the DM_SETDEFID message to be sent to the property sheet dialog box. The wParam parameter specifies the identifier of the Finish button.

See Also

DM_SETDEFID, PropSheet_SetFinishText


PSM_SETTITLE

The PSM_SETTITLE message sets the title of a property sheet. You can send this message explicitly or by using the PropSheet_SetTitle macro.

PSM_SETTITLE

wParam = (WPARAM) (DWORD) dwStyle

lParam = (LPARAM) (LPCSTR) lpszText;

Parameters

dwStyle

Flag that indicates whether to include the prefix “Properties for” with the specified title string. If dwStyle is the PSH_PROPTITLE value, the prefix is included. Otherwise, the prefix is not used.

lpszText

Pointer to a buffer that contains the title string. If the high-order word of this parameter is NULL, the property sheet loads the string resource specified in the low-order word.

Return Values

No return value.

See Also

PropSheet_SetTitle


PSM_SETWIZBUTTONS

The PSM_SETWIZBUTTONS message enables or disables the Back, Next, and Finish buttons in a wizard property sheet. You can send or post this message explicitly to a wizard property sheet, or you can use the PropSheet_SetWizButtons macro to post the message.

PSM_SETWIZBUTTONS

wParam = 0;

lParam = (LPARAM) (DWORD) dwFlags;

Parameters

dwFlags

Specifies the buttons to display and enable. A wizard property sheet displays the Back button and either the Next or Finish button. This parameter can include the PSWIZB_BACK flag and one of the PSWIZB_NEXT, PSWIZB_FINISH, or PSWIZB_DISABLEDFINISH flags.

Value	Meaning
PSWIZB_BACK	Enables the Back button.
PSWIZB_NEXT	Enables the Next button.
PSWIZB_FINISH	Displays an enabled Finish button in place of the Next button.
PSWIZB_DISABLEDFINISH	Displays a disabled Finish button in place of the Next button.
Return Values

No return value.

Remarks

If you send the PSM_SETWIZBUTTONS message during your handling of the PSN_SETACTIVE notification message, use the PostMessage function rather than the SendMessage function. Otherwise, the system will not update the buttons properly. At any other time, you can use SendMessage to send PSM_SETWIZBUTTONS.

See Also

PostMessage, PropSheet_SetWizButtons, SendMessage


PSM_UNCHANGED

The PSM_UNCHANGED message informs a property sheet that information in a page has reverted to the previously saved state. The property sheet disables the Apply Now button if no other pages have registered changes with the property sheet. You can send this message explictly or by using the PropSheet_UnChanged macro.

PSM_UNCHANGED

wParam = (WPARAM) (HWND) hwndPage;

lParam = 0;

Parameters

hwndPage

Handle to the page that has reverted to the previously saved state.

Return Values

No return value.

See Also

PropSheet_UnChanged


PSN_APPLY

The PSN_APPLY notification message indicates that the user chose the OK or Apply Now button and wants all changes to take effect. This notification message is sent in the form of a WM_NOTIFY message.

PSN_APPLY

lpnmhdr = (NMHDR FAR *) lParam;

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle to the property sheet.

Return Values

Returns the PSNRET_INVALID_NOCHANGEPAGE value to prevent the changes from taking effect and to return the focus to the page, or the PSNRET_NOERROR value to accept the changes and allow the property sheet to be destroyed.

Remarks

To set the return value, the dialog box procedure for the page must use the SetWindowLong function with the DWL_MSGRESULT value, and the dialog box procedure must return TRUE.

A page should not call the EndDialog function when processing this notification message.

The property sheet is destroyed if the user chooses the OK button and the application returns the PSNRET_NOERROR value in response to this notification.

To receive this notification, a page must set the DWL_MSGRESULT value to FALSE in response the PSN_KILLACTIVE notification message.

The PSHNOTIFY structure is supplied with the PSN_APPLY notification message. The lParam member in this structure is TRUE if the user clicked the Ok or Cancel button, and is FALSE if the user clicked the Close button.

See Also

EndDialog, NMHDR, PSN_KILLACTIVE, PSHNOTIFY, SetWindowLong, WM_NOTIFY


PSN_HELP

The PSN_HELP notification message notifies a page that the user has chosen the Help button. This notification message is sent in the form of a WM_NOTIFY message.

PSN_HELP

lpnmhdr = (NMHDR FAR *) lParam;

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle to the property sheet.

Return Values

No return value.

Remarks

An application should display help information for the page.

See Also

NMHDR, WM_NOTIFY


PSN_KILLACTIVE

The PSN_KILLACTIVE notification message notifies a page that it is about to lose the activation either because another page is being activated or the user has chosen the OK button. This notification message is sent in the form of a WM_NOTIFY message.

PSN_KILLACTIVE

lpnmhdr = (NMHDR FAR *) lParam;

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle to the property sheet.

Return Values

Returns TRUE to prevent the page from losing the activation or FALSE to allow it.

Remarks

An application should validate the information that the user has typed.

To set the return value, the dialog box procedure for the page must use the SetWindowLong function with the DWL_MSGRESULT value, and the dialog box procedure must return TRUE.

If the dialog box procedure sets DWL_MSGRESULT to TRUE, it should display a message box to explain the problem to the user.

See Also

SetWindowLong, NMHDR, WM_NOTIFY


PSN_QUERYCANCEL

The PSN_QUERYCANCEL notification message indicates that the user chose the Cancel button. This notification message is sent in the form of a WM_NOTIFY message.

PSN_QUERYCANCEL

lpnmhdr = (NMHDR FAR *) lParam;

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle of the property sheet.

Return Values

Returns TRUE to prevent the cancel operation or FALSE to allow it.

Remarks

A property sheet page can use this notification message to ask the user to verify the cancel operation.

See Also

NMHDR, WM_NOTIFY


PSN_RESET

The PSN_RESET notification message notifies a page that the user has chosen the Cancel button and the property sheet is about to be destroyed. All changes made since the user last chose the Apply Now button are canceled. This notification message is sent in the form of a WM_NOTIFY message.

PSN_RESET

lpnmhdr = (NMHDR FAR *) lParam;

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle of the property sheet.

Return Values

No return value.

Remarks

An application can use this notification message as an opportunity to perform cleanup operations.

A page should not call the EndDialog function when processing this notification message.

The PSHNOTIFY structure is supplied with the PSN_RESET notification message. The lParam member in this structure is TRUE if the user clicked the Ok or Cancel button, and is FALSE if the user clicked the Close button.

See Also

EndDialog, NMHDR, PSHNOTIFY, WM_NOTIFY


PSN_SETACTIVE

The PSN_SETACTIVE notification message notifies a page that it is about to be activated. This notification message is sent in the form of a WM_NOTIFY message.

PSN_SETACTIVE

lpnmhdr = (NMHDR FAR *) lParam;

Parameters

lpnmhdr

Pointer to the property sheet.

Return Values

Returns zero to accept the activation or −1 to activate the next or previous page (depending on whether the user chose the Next or Back button). To set the activation to a particular page, return the resource identifier of the page.

Remarks

The PSN_SETACTIVE notification message is sent before the page is visible. An application can use this notification to initialize data in the page.

To set the return value, the dialog box procedure for the page must use the SetWindowLong function with the DWL_MSGRESULT value, and the dialog box procedure must return TRUE.

See Also

NMHDR, SetWindowLong, WM_NOTIFY


PSN_WIZBACK

The PSN_WIZBACK notification message notifies a page that the user has chosen the Back button in a wizard property sheet. This notification message is sent in the form of a WM_NOTIFY message.

PSN_WIZBACK

lpnmhdr = (NMHDR FAR *) lParam;

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle of the property sheet.

Return Values

Returns −1 to prevent the property sheet from advancing to the previous page.

See Also

NMHDR, WM_NOTIFY


PSN_WIZFINISH

The PSN_WIZFINISH notification message notifies a page that the user has chosen the Finish button in a wizard property sheet. This notification message is sent in the form of a WM_NOTIFY message.

PSN_WIZFINISH

lpnmhdr = (NMHDR FAR *) lParam;

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle to the property sheet.

Return Values

Returns a nonzero value to prevent the property sheet from being destroyed.

See Also

NMHDR, WM_NOTIFY


PSN_WIZNEXT

The PSN_WIZNEXT notification message notifies a page that the user has chosen the Next button in a wizard property sheet. This notification message is sent in the form of a WM_NOTIFY message.

PSN_WIZNEXT

lpnmhdr = (NMHDR FAR *) lParam;

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle to the property sheet.

Return Values

Returns −1 to prevent the property sheet from advancing to the next page.

See Also

NMHDR, WM_NOTIFY


SB_GETBORDERS

The SB_GETBORDERS message retrieves the current widths of the horizontal and vertical borders of a status window.

SB_GETBORDERS

wParam = 0;

lParam = (LPARAM) (LPINT) aBorders;

Parameters

aBorders

Pointer to an integer array that has three elements. The first element receives the width of the horizontal border, the second receives the width of the vertical border, and the third receives the width of the border between rectangles.

Return Values

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

Remarks

The borders determine the spacing between the outside edge of the window and the rectangles within the window that contain text. The borders also determine the spacing between rectangles.


SB_GETPARTS

The SB_GETPARTS message retrieves a count of the parts in a status window. The message also retrieves the coordinate of the right edge of the specified number of parts.

SB_GETPARTS

wParam = (WPARAM) nParts;

lParam = (LPARAM) (LPINT) aRightCoord;

Parameters

nParts

Number of parts for which to retrieve coordinates. If this parameter is greater than the number of parts in the window, the message retrieves coordinates for existing parts only.

aRightCoord

Pointer to an integer array that has the same number of elements as parts specified by nParts. Each element in the array receives the client coordinate of the right edge of the corresponding part. If an element is set to − 1, the position of the right edge for that part extends to the right edge of the window. To retrieve the current number of parts, set this parameter to zero.

Return Values

Returns the number of parts in the window if successful, or zero otherwise.


SB_GETRECT

The SB_GETRECT message retrieves the bounding rectangle of a part in a status window.

SB_GETRECT

wParam = (WPARAM) iPart;

lParam = (LPARAM) (LPRECT) lprc;

Parameters

iPart

Zero-based index of the part whose bounding rectangle is to be retrieved.

lprc

Pointer to a RECT structure that receives the bounding rectangle.

Return Values

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

See Also

RECT


SB_GETTEXT

The SB_GETTEXT message retrieves the text from the specified part of a status window.

SB_GETTEXT

wParam = (WPARAM) iPart;

lParam = (LPARAM) (LPSTR) szText;

Parameters

iPart

Zero-based index of the part from which to retrieve text.

szText

Pointer to the buffer that receives the text. This parameter is a null-terminated string.

Return Values

Returns a 32-bit value that consists of two 16-bit values. The low word specifies the length, in characters, of the text. The high word specifies the type of operation used to draw the text. The type can be one of the following values:

Value	Meaning
0	The text is drawn with a border to appear lower than the plane of the window.
SBT_NOBORDERS	The text is drawn without borders.
SBT_POPOUT	The text is drawn with a border to appear higher than the plane of window.
SBT_RTLREADING	Displays text using right-to-left reading order on Hebrew or Arabic systems.
If the text has the SBT_OWNERDRAW drawing type, this message returns the 32-bit value associated with the text instead of the length and operation type.


SB_GETTEXTLENGTH

The SB_GETTEXTLENGTH message retrieves the length, in characters, of the text from the specified part of a status window.

SB_GETTEXTLENGTH

wParam = (WPARAM) iPart;

lParam = 0;

Parameters

iPart

Zero-based index of the part from which to retrieve text.

Return Values

Returns a 32-bit value that consists of two 16-bit values. The low word specifies the length, in characters, of the text. The high word specifies the type of operation used to draw the text. The type can be one of the following values:

Value	Meaning
0	The text is drawn with a border to appear lower than the plane of the window.
SBT_NOBORDERS	The text is drawn without borders.
SBT_OWNERDRAW	The text is drawn by the parent window.
SBT_POPOUT	The text is drawn with a border to appear higher than the plane of the window.
SBT_RTLREADING	Displays text using right-to-left reading order on Hebrew or Arabic systems.


SB_SETMINHEIGHT

The SB_SETMINHEIGHT message sets the minimum height of a status window’s drawing area.

SB_SETMINHEIGHT

wParam = (WPARAM) minHeight;

lParam = 0;

Parameters

minHeight

Minimum height, in pixels, of the window.

Return Values

No return value.

Remarks

The minimum height is the sum of wParam and twice the width, in pixels, of the vertical border of the status window. An application must send the WM_SIZE message to the status window to redraw the window. The wParam and lParam parameters of the WM_SIZE message should be set to zero.

See Also

WM_SIZE


SB_SETPARTS

The SB_SETPARTS message sets the number of parts in a status window and the coordinate of the right edge of each part.

SB_SETPARTS

wParam = (WPARAM) nParts;

lParam = (LPARAM) (LPINT) aWidths;

Parameters

nParts

Number of parts to set. The number of parts cannot be greater than 255.

aWidths

Pointer to an integer array that has the same number of elements as parts specified by nParts. Each element in the array specifies the position, in client coordinates, of the right edge of the corresponding part. If an element is  − 1, the position of the right edge for that part extends to the right edge of the window.

Return Values

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.


SB_SETTEXT

The SB_SETTEXT message sets the text in the specified part of a status window.

SB_SETTEXT

wParam = (WPARAM) iPart | uType;

lParam = (LPARAM) (LPSTR) szText;

Parameters

iPart

Zero-based index of the part to set. If this value is 255, the status window is assumed to be a simple window having only one part.

uType

Type of drawing operation. This parameter can be one of the following values:

Value	Meaning
0	The text is drawn with a border to appear lower than the plane of the window.
SBT_NOBORDERS	The text is drawn without borders.
SBT_OWNERDRAW	The text is drawn by the parent window.
SBT_POPOUT	The text is drawn with a border to appear higher than the plane of the window.
SBT_RTLREADING	Displays text using right-to-left reading order on Hebrew or Arabic systems.
szText

Pointer to a null-terminated string that specifies the text to set. If uType is SBT_OWNERDRAW, this parameter represents 32 bits of data. The parent window must interpret the data and draw the text when it receives the WM_DRAWITEM message.

Return Values

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

Remarks

The message invalidates the portion of the window that has changed, causing it to display the new text when the window next receives the WM_PAINT message.

See Also

WM_DRAWITEM, WM_PAINT


SB_SIMPLE

The SB_SIMPLE message specifies whether a status window displays simple text or displays all window parts set by a previous SB_SETPARTS message.

SB_SIMPLE

wParam = (WPARAM) (BOOL) fSimple;

lParam = 0;

Parameters

fSimple

Display type flag. If this parameter is TRUE, the window displays simple text. If it is FALSE, it displays multiple parts.

Return Values

Returns FALSE if an error occurs.

Remarks

If the status window is being changed from nonsimple to simple, or vice versa, the window is immediately redrawn.

See Also

SB_SETPARTS


SBM_ENABLE_ARROWS

An application sends the SBM_ENABLE_ARROWS message to enable or disable one or both arrows of a scroll bar control.

SBM_ENABLE_ARROWS

wParam = (WPARAM) fuArrowFlags; // scroll-bar arrow flags

lParam = 0;                     // not used; must be zero

Parameters

fuArrowFlags

Specifies whether the scroll bar arrows are enabled or disabled and indicates which arrows are enabled or disabled. This parameter can be one of the following values:

Value	Meaning
ESB_DISABLE_BOTH	Disables both arrows on a scroll bar.
ESB_DISABLE_DOWN	Disables the down arrow on a vertical scroll bar.
ESB_DISABLE_LTUP	Disables the left arrow on a horizontal scroll bar or the up arrow on a vertical scroll bar.
ESB_DISABLE_LEFT	Disables the left arrow on a horizontal scroll bar.
ESB_DISABLE_RTDN	Disables the right arrow on a horizontal scroll bar or the down arrow on a vertical scroll bar.
ESB_DISABLE_UP	Disables the up arrow on a vertical scroll bar.
ESB_ENABLE_BOTH	Enables both arrows on a scroll bar.
Return Values

If the message succeeds, the return value is TRUE; otherwise, it is FALSE.


SBM_GETPOS

An application sends the SBM_GETPOS message to retrieve the current position of the scroll box of a scroll bar control. The current position is a relative value that depends on the current scrolling range. For example, if the scrolling range is 0 through 100 and the scroll box is in the middle of the bar, the current position is 50.

SBM_GETPOS

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

If the message succeeds, the return value is the current position of the scroll box in the scroll bar.

See Also

SBM_GETRANGE, SBM_SETPOS, SBM_SETRANGE, SBM_SETRANGEREDRAW


SBM_GETRANGE

An application sends the SBM_GETRANGE message to a scroll bar control to retrieve the minimum and maximum position values for the control.

SBM_GETRANGE

wParam = (WPARAM) (LPINT) lpnMinPos; // minimum position

lParam = (LPARAM) (LPINT) lpnMaxPos; // maximum position

Parameters

lpnMinPos

Points to a value that receives the minimum scrolling position.

lpnMaxPos

Points to a value that receives the maximum scrolling position.

Return Values

This message does not return a value.

See Also

SBM_GETPOS, SBM_SETPOS, SBM_SETRANGE, SBM_SETRANGEREDRAW


SBM_GETSCROLLINFO

An application sends the SBM_GETSCROLLINFO message to retrieve the parameters of a scroll bar.

SBM_GETSCROLLINFO

wParam = 0;                             // not used, must be zero

lParam = (LPARAM) (LPSCROLLINFO) lpsi;  // scroll bar parameters

Parameters

lpsi

Value of lParam. Points to a SCROLLINFO structure whose fMask member, when the message is sent, specifies the scroll bar parameters to retrieve. Before returning, the message copies the specified parameters to the appropriate members of the structure.

The fMask member can be a combination of the following values:

Value	Meaning
SIF_ALL	Combination of SIF_PAGE, SIF_POS, and SIF_RANGE.
SIF_PAGE	Copies the scroll page to the nPage member of the SCROLLINFO structure pointed to by lpsi.
SIF_POS	Copies the scroll position to the nPos member of the SCROLLINFO structure pointed to by lpsi.
SIF_RANGE	Copies the scroll range to the nMin and nMax members of the SCROLLINFO structure pointed to by lpsi.
Return Values

If the message retrieved any values, the return value is TRUE; otherwise, it is FALSE.

See Also

SBM_SETSCROLLINFO, SCROLLINFO


SBM_SETPOS

An application sends the SBM_SETPOS message to a scroll bar control to set the position of the scroll box (thumb) and, if requested, redraw the scroll bar to reflect the new position of the scroll box.

SBM_SETPOS

wParam = (WPARAM) nPos;           // new position of scroll box

lParam = (LPARAM) (BOOL) fRedraw; // redraw flag

Parameters

nPos

Specifies the new position of the scroll box. It must be within the scrolling range.

fRedraw

Specifies whether the scroll bar should be redrawn to reflect the new scroll box position. If this parameter is TRUE, the scroll bar is redrawn. If it is FALSE, the scroll bar is not redrawn.

Return Values

If the position of the scroll box changed, the return value is the previous position of the scroll box; otherwise, it is zero.

Remarks

If the scroll bar control is redrawn by a subsequent call to another function, setting the fRedraw parameter to FALSE is useful.

See Also

SBM_GETPOS, SBM_GETRANGE, SBM_SETRANGE, SBM_SETRANGEREDRAW


SBM_SETRANGE

An application sends the SBM_SETRANGE message to a scroll bar control to set the minimum and maximum position values for the control.

SBM_SETRANGE

wParam = (WPARAM) nMinPos; // minimum scrolling position

lParam = (LPARAM) nMaxPos; // maximum scrolling position

Parameters

nMinPos

Specifies the minimum scrolling position.

fMaxPos

Specifies the maximum scrolling position.

Return Values

If the position of the scroll box changed, the return value is the previous position of the scroll box; otherwise, it is zero.

Remarks

The default minimum and maximum position values are zero. The difference between the values specified by the nMinPos and nMaxPos parameters must not be greater than the value of MAXLONG.

If the minimum and maximum position values are equal, the scroll bar control is hidden and, in effect, disabled.

See Also

SBM_GETPOS, SBM_GETRANGE, SBM_SETPOS, SBM_SETRANGEREDRAW


SBM_SETRANGEREDRAW

An application sends the SBM_SETRANGEREDRAW message to a scroll bar control to set the minimum and maximum position values and to redraw the control.

SBM_SETRANGEREDRAW

wParam = (WPARAM) nMinPos; // minimum scrolling position

lParam = (LPARAM) nMaxPos  // maximum scrolling position

Parameters

nMinPos

Specifies the minimum scrolling position.

fMaxPos

Specifies the maximum scrolling position.

Return Values

If the position of the scroll box changed, the return value is the previous position of the scroll box; otherwise, it is zero.

Remarks

The default minimum and maximum position values are zero. The difference between the values specified by the nMinPos and nMaxPos parameters must not be greater than the value of MAXLONG.

If the minimum and maximum position values are equal, the scroll bar control is hidden and, in effect, disabled.

See Also

SBM_GETPOS, SBM_GETRANGE, SBM_SETPOS, SBM_SETRANGE


SBM_SETSCROLLINFO

An application sends the SBM_GETSCROLLINFO message to set the parameters of a scroll bar.

SBM_SETSCROLLINFO

wParam = (WPARAM) fRedraw;              // redraw flag

lParam = (LPARAM) (LPSCROLLINFO) lpsi;  // scroll bar parameters

Parameters

fRedraw

Value of wParam. Specifies whether the scroll bar is redrawn to reflect the new scroll box position. If this parameter is TRUE, the scroll bar is redrawn. If it is FALSE, the scroll bar is not redrawn.

lpsi

Value of lParam. Points to a SCROLLINFO structure whose fMask member, when the message is sent, specifies the scroll bar parameters to set.

The fMask member can be a combination of the following values:

Value	Meaning
SIF_ALL	Combination of SIF_PAGE, SIF_POS, and SIF_RANGE.
SIF_PAGE	Sets the scroll page to the value specified in the nPage member of the SCROLLINFO structure pointed to by lpsi.
SIF_POS	Sets the scroll position to the value specified in the nPos member of the SCROLLINFO structure pointed to by lpsi.
SIF_RANGE	Sets the scroll range to the value specified in the nMin and nMax members of the SCROLLINFO structure pointed to by lpsi.
Return Values

The return value is the current position of the scroll box.

See Also

SBM_GETSCROLLINFO, SCROLLINFO


SETRGBSTRING

The hook procedure of a Color dialog box can send the SETRGBSTRING registered message to the dialog box to set the current color selection.

MessageID = RegisterWindowMessage(SETRGBSTRING);
wParam = 0;
lParam = (COLORREF) rgbColor;

Parameters

rgbColor

Specifies the RGB value of the color to select in the Color dialog box. You can use the RGB macro to specify the red, green, and blue intensities of an RGB color value.

Return Values

No return value.

Remarks

If rgbColor matches one of the basic colors or one of the 16 custom colors, the dialog box procedure selects that color. The dialog box procedure also updates all the controls in the custom color extension of the Color dialog box, if it is open.

If rgbColor does not match a basic or custom color, the dialog box procedure does not change the current color selection, but it does update the custom color controls, if they are visible.

For example, the following sample code gets the SETRGBSTRING message identifier and then sets the color selection to blue.

UINT uiSetRGB;

uiSetRGB = RegisterWindowMessage(SETRGBSTRING);

SendMessage(hwndDlg, uiSetRGB, 0, (LPARAM) RGB(0, 0, 255));

See Also

RegisterWindowMessage, RGB, SendMessage


SHAREVISTRING

An Open or Save As dialog box sends the SHAREVISTRING registered message to your hook procedure if a sharing violation occurs for the selected file when the user clicks the OK button.

For Explorer-style Open and Save As dialog boxes, this message has been superseded by the CDN_SHAREVIOLATION notification message.

MessageID = RegisterWindowMessage(SHAREVISTRING);
wParam = 0;
lpofn = (LPOPENFILENAME) lParam;

Parameters

lpofn

Pointer to a OPENFILENAME structure. The lpstrFile member of this structure contains the filename that caused the sharing violation.

Return Values

The hook procedure must return one of the following values to indicate how the dialog box should handle the sharing violation:

Return value	Description
OFN_SHAREFALLTHROUGH	Accept the filename
OFN_SHARENOWARN	Reject the filename but do not warn the user. The application is responsible for displaying a warning message.
OFN_SHAREWARN	Rejects the filename and displays a warning message (the same result as if there were no hook procedure).
Remarks

The hook procedure must specify the SHAREVISTRING constant in a call to the RegisterWindowMessage function to get the identifier for the message sent by the dialog box.

The dialog box sends the SHAREVISTRING registered message only if you did not specify the OFN_SHAREAWARE flag in the Flags member of the OPENFILENAME structure when you created the dialog.

If the hook procedure returns an undefined value, the dialog box responds as if OFN_SHAREWARN was returned.

See Also

CDN_SHAREVIOLATION, OPENFILENAME, RegisterWindowMessage


STM_GETICON

An application sends the STM_GETICON message to retrieve the handle of the icon associated with a static control that has the SS_ICON style.

STM_GETICON

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is the handle of the icon, or NULL if either the static control has no associated icon or if an error occurred.

See Also

STM_SETICON


STM_GETIMAGE

An application sends an STM_GETIMAGE message to retrieve the handle of the image associated with a static control.

STM_GETIMAGE

wParam = (WPARAM) fImageType;  // image-type flag

lParam = 0;                    // not used; must be zero

Parameters

fImageType

Value of wParam. Specifies the type of image to retrieve. This parameter can be one of the following values:

IMAGE_BITMAP
IMAGE_CURSOR
IMAGE_ENHMETAFILE
IMAGE_ICON

Return Values

The return value is the handle of the image, if any; otherwise, it is NULL.

See Also

STM_SETIMAGE


STM_SETICON

An application sends the STM_SETICON message to associate an icon with an icon control.

STM_SETICON

wParam = (WPARAM) (HICON) hicon;    // handle of the icon

lParam = 0;                         // not used; must be zero

Parameters

hicon

Value of wParam. Identifies the icon to associate with the icon control.

Return Values

The return value is the handle of the icon previously associated with the icon control, or zero if an error occurs.

See Also

LoadIcon, STM_GETICON


STM_SETIMAGE

An application sends an STM_SETIMAGE message to associate a new image (icon or bitmap) with a static control.

STM_SETIMAGE

wParam = (WPARAM) fImageType;       // image-type flag

lParam = (LPARAM) (HANDLE) hImage;  // handle of the image

Parameters

fImageType

Value of wParam. Specifies the type of image to associate with the static control. This parameter can be one of the following values:

IMAGE_BITMAP
IMAGE_CURSOR
IMAGE_ENHMETAFILE
IMAGE_ICON

hImage

Value of lParam. Identifies the image to associate with the static control.

Return Values

The return value is the handle of the image previously associated with the static control, if any; otherwise, it is NULL.

See Also

STM_GETIMAGE


STN_CLICKED

The STN_CLICKED notification message is sent when the user clicks a static control that has the SS_NOTIFY style. The parent window of the control receives this notification message through the WM_COMMAND message.

STN_CLICKED
idStatic = (int) LOWORD(wParam);    // identifier of static control
hwndStatic = (HWND) LOWORD(lParam); // handle of static control

See Also

STN_DBLCLK, WM_COMMAND


STN_DBLCLK

The STN_DBLCLK notification message is sent when the user double-clicks a static control that has the SS_NOTIFY style. The parent window of the control receives this notification message through the WM_COMMAND message.

STN_DBLCLK
idStatic = (int) LOWORD(wParam);    // identifier of static control
hwndStatic = (HWND) LOWORD(lParam); // handle of static control

See Also

STN_CLICKED, WM_COMMAND


STN_DISABLE

The STN_DISABLE notification message is sent when a static control is disabled. The static control must have the SS_NOTIFY style to receive this notification message. The parent window of the control receives this notification message through the WM_COMMAND message.

STN_DISABLE
idStatic = (int) LOWORD(wParam);    // identifier of static control
hwndStatic = (HWND) LOWORD(lParam); // handle of static control

See Also

STN_ENABLE, WM_COMMAND


STN_ENABLE

The STN_ENABLE notification message is sent when a static control is enabled. The static control must have the SS_NOTIFY style to receive this notification message. The parent window of the control receives this notification message through the WM_COMMAND message.

STN_ENABLE
idStatic = (int) LOWORD(wParam);    // identifier of static control
hwndStatic = (HWND) LOWORD(lParam); // handle of static control

See Also

STN_DISABLE, WM_COMMAND


TB_ADDBITMAP

The TB_ADDBITMAP message adds one or more images to the list of button images available for a toolbar.

TB_ADDBITMAP

wParam = (WPARAM) nButtons;

lParam = (LPARAM) (LPTBADDBITMAP) lptbab;

Parameters

nButtons

Number of button images in the bitmap.

lptbab

Pointer to a TBADDBITMAP structure that contains the identifier of a bitmap resource and the handle to the module instance with the executable file that contains the bitmap resource.

Return Values

Returns the index of the first new image if successful or  − 1 otherwise.

Remarks

If the toolbar was created by using the CreateWindowEx function, you must send the TB_BUTTONSTRUCTSIZE message to the toolbar before sending TB_ADDBITMAP.

See Also

CreateWindowEx, TBADDBITMAP, TB_BUTTONSTRUCTSIZE


TB_ADDBUTTONS

The TB_ADDBUTTONS message adds one or more buttons to a toolbar.

TB_ADDBUTTONS

wParam = (WPARAM) (UINT) uNumButtons;

lParam = (LPARAM) (LPTBBUTTON) lpButtons;

Parameters

uNumButtons

Number of buttons to add.

lpButtons

Pointer to an array of TBBUTTON structures that contains information about the buttons to add. There must be the same number of elements in the array as buttons specified by uNumButtons.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

If the toolbar was created by using the CreateWindowEx function, you must send the TB_BUTTONSTRUCTSIZE message to the toolbar before sending TB_ADDBUTTONS.

See Also

CreateWindowEx, TBBUTTON, TB_BUTTONSTRUCTSIZE


TB_ADDSTRING

The TB_ADDSTRING message adds a new string to the list of strings available for a toolbar.

TB_ADDSTRING

wParam = (WPARAM) (HINSTANCE) hinst;

lParam = (LPARAM) MAKELONG(idString, 0);

Parameters

hinst

Handle to the module instance with an executable file that contains the string resource. If idString points to one or more strings to add, this parameter is zero.

idString

Resource identifier for the string resource, or the address of a buffer that contains one or more null-terminated strings to add to the list, depending on the value of hinst. The last string must be terminated with two null characters.

Return Values

Returns the index of the first new string if successful or  − 1 otherwise.


TB_AUTOSIZE

The TB_AUTOSIZE message causes a toolbar to be resized.

TB_AUTOSIZE

wParam = 0;

lParam = 0;

Return Values

No return value.

Remarks

An application sends the TB_AUTOSIZE message after causing the size of a toolbar to change either by setting the button or bitmap size or by adding strings for the first time.


TB_BUTTONCOUNT

The TB_BUTTONCOUNT message retrieves a count of the buttons currently in the toolbar.

TB_BUTTONCOUNT

wParam = 0;

lParam = 0;

Return Values

Returns the count of the buttons.


TB_BUTTONSTRUCTSIZE

The TB_BUTTONSTRUCTSIZE message specifies the size of the TBBUTTON structure.

wParam = (WPARAM) cb;

lParam = 0;

Parameters

cb

Size, in bytes, of the TBBUTTON structure.

The system uses the size to determine which version of the common control dynamic-link library (DLL) is being used.

If an application uses the CreateWindowEx function to create the toolbar, the application must send this message to the toolbar before sending the TB_ADDBITMAP or TB_ADDBUTTONS message. The CreateToolBarEx function automatically sends TB_BUTTONSTRUCTSIZE, and the size of the TBBUTTON structure is a parameter of the function.

Return Values

No return value.

See Also

CreateWindowEx, TB_ADDBITMAP, TB_ADDBUTTONS, TBBUTTON


TB_CHANGEBITMAP

The TB_CHANGEBITMAP message changes the bitmap for a button in a toolbar.

TB_CHANGEBITMAP

wParam = (WPARAM) idButton;

lParam = (LPARAM) MAKELPARAM(iBitmap, 0);

Parameters

idButton

Command identifier of the button that is to receive a new bitmap.

iBitmap

Zero-based index of an image in the toolbar’s image list. The system displays the specified image in the button.

Return Values

Returns TRUE if successful or FALSE otherwise.


TB_CHECKBUTTON

The TB_CHECKBUTTON message checks or unchecks a given button in a toolbar.

TB_CHECKBUTTON

wParam = (WPARAM) idButton;

lParam = (LPARAM) MAKELONG(fCheck, 0);

Parameters

idButton

Command identifier of the button to check.

fCheck

Check flag. If this parameter TRUE, the check is added. If it is FALSE, the check is removed.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

When a button has been checked, it appears to have been pressed.


TB_COMMANDTOINDEX

The TB_COMMANDTOINDEX message retrieves the zero-based index for the button associated with the specified command identifier.

TB_COMMANDTOINDEX

wParam = (WPARAM) idButton;

lParam = 0;

Parameters

idButton

Command identifier associated with the button.

Return Values

Returns the zero-based index for the button.


TB_CUSTOMIZE

The TB_CUSTOMIZE message displays the Customize Toolbar dialog box.

TB_CUSTOMIZE

wParam = 0;

lParam = 0;

Return Values

No return value.


TB_DELETEBUTTON

The TB_DELETEBUTTON message deletes a button from the toolbar.

TB_DELETEBUTTON

wParam = (WPARAM) iButton;

lParam = 0;

Parameters

iButton

Zero-based index of the button to delete.

Return Values

Returns TRUE if successful or FALSE otherwise.


TB_ENABLEBUTTON

The TB_ENABLEBUTTON message enables or disables the specified button in a toolbar.

TB_ENABLEBUTTON

wParam = (WPARAM) idButton;

lParam = (LPARAM) MAKELONG(fEnable, 0);

Parameters

idButton

Command identifier of the button to enable or disable.

fEnable

Enable flag. If this parameter is TRUE, the button is enabled. If it is FALSE, the button is disabled.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

When a button has been enabled, it can be pressed and checked.


TB_GETBITMAP

The TB_GETBITMAP message retrieves the index of the bitmap associated with a button in a toolbar.

TB_GETBITMAP

wParam = (WPARAM) idButton;

lParam = 0;

Parameters

idButton

Command identifier of the button whose bitmap index is to be retrieved.

Return Values

If successful, the message returns the index of the bitmap. If unsuccessful, it returns zero.


TB_GETBITMAPFLAGS

The TB_GETBITMAPFLAGS message retrieves the bitmap flags.

TB_GETBITMAPFLAGS

wParam = 0;

lParam = 0;

Return Values

Returns the TBBF_LARGE value if the display can handle large bitmaps (that is, if the width of the display has at least 120 pixels per logical inch). Otherwise, the return value is zero.


TB_GETBUTTON

The TB_GETBUTTON message retrieves information about the specified button in a toolbar.

TB_GETBUTTON

wParam = (WPARAM) iButton;

lParam = (LPARAM) (LPTBBUTTON) lpButton;

Parameters

iButton

Zero-based index of the button for which to retrieve information.

lpButton

Pointer to the TBBUTTON structure that receives the button information.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TBBUTTON


TB_GETBUTTONTEXT

The TB_GETBUTTONTEXT message retrieves the text of a button in a toolbar.

TB_GETBUTTONTEXT

wParam = (WPARAM) idButton;

lParam = (LPARAM) (LPSTR) lpszText;

Parameters

idButton

Command identifier of the button whose text is to be retrieved.

lpszText

Pointer to a buffer that receives the button text.

Return Values

Returns the length, in characters, of the string copied to the specified buffer if successful. The length does not include the terminating null character. Otherwise, the return value is  − 1.


TB_GETITEMRECT

The TB_GETITEMRECT message retrieves the bounding rectangle of a button in a toolbar.

wParam = (WPARAM) iButton;

lParam = (LPARAM) (LPRECT) lprc;

Parameters

iButton

Zero-based index of the button for which to retrieve information.

lprc

Pointer to a RECT structure that receives the coordinates of the bounding rectangle.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

This message does not retrieve the bounding rectangle for buttons whose state is set to the TBSTATE_HIDDEN value.

See Also

RECT


TB_GETROWS

The TB_GETROWS message retrieves the number of rows of buttons in a toolbar with the TBSTYLE_WRAPABLE style.

TB_GETROWS

wParam = 0;

lParam = 0;

Return Values

Returns the number of rows.


TB_GETSTATE

The TB_GETSTATE message retrieves information about the state of the specified button in a toolbar, such as whether it is enabled, pressed, or checked.

TB_GETSTATE

wParam = (WPARAM) idButton;

lParam = 0;

Parameters

idButton

Command identifier of the button for which to retrieve information.

Return Values

Returns the button state information if successful or  − 1 otherwise. The button state information can be a combination of the values listed in Button States.


TB_GETTOOLTIPS

The TB_GETTOOLTIPS message retrieves the handle to the tooltip control, if any, associated with the toolbar.

TB_GETTOOLTIPS

wParam = 0;

lParam = 0;

Return Values

Returns the handle to the tooltip control or NULL if the toolbar has no associated tooltip.


TB_HIDEBUTTON

The TB_HIDEBUTTON message hides or shows the specified button in a toolbar.

TB_HIDEBUTTON

wParam = (WPARAM) idButton;

lParam = (LPARAM) MAKELONG(fShow, 0);

Parameters

idButton

Command identifier of the button to hide or show.

fShow

Show flag. If this parameter is TRUE, the button is hidden. If it is FALSE, the button is shown.

Return Values

Returns TRUE if successful or FALSE otherwise.


TB_INDETERMINATE

The TB_INDETERMINATE message sets or clears the indeterminate state of the specified button in a toolbar.

TB_INDETERMINATE

wParam = (WPARAM) idButton;

lParam = (LPARAM) MAKELONG(fIndeterminate, 0);

Parameters

idButton

Command identifier of the button whose indeterminate state is to be set or cleared.

fIndeterminate

Indeterminate flag. If this parameter is TRUE, the indeterminate state is set. If it is FALSE, the state is cleared.

Return Values

Returns TRUE if successful or FALSE otherwise.


TB_INSERTBUTTON

The TB_INSERTBUTTON message inserts a button in a toolbar.

TB_INSERTBUTTON

wParam = (WPARAM) iButton;

lParam = (LPARAM) (LPTBBUTTON) lpButton;

Parameters

iButton

Zero-based index of a button. The message inserts the new button to the left of this button.

lpButton

Pointer to a TBBUTTON structure containing information about the button to insert.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TBBUTTON


TB_ISBUTTONCHECKED

The TB_ISBUTTONCHECKED message determines whether the specified button in a toolbar is checked.

TB_ISBUTTONCHECKED

wParam = (WPARAM) idButton;

lParam = 0;

Parameters

idButton

Command identifier of the button.

Return Values

Returns nonzero if the button is checked or zero otherwise.


TB_ISBUTTONENABLED

The TB_ISBUTTONENABLED message determines whether the specified button in a toolbar is enabled.

TB_ISBUTTONENABLED

wParam = (WPARAM) idButton;

lParam = 0;

Parameters

idButton

Command identifier of the button.

Return Values

Returns nonzero if the button is enabled or zero otherwise.


TB_ISBUTTONHIDDEN

The TB_ISBUTTONHIDDEN message determines whether the specified button in a toolbar is hidden.

TB_ISBUTTONHIDDEN

wParam = (WPARAM) idButton;

lParam = 0;

Parameters

idButton

Command identifier of the button.

Return Values

Returns nonzero if the button is hidden or zero otherwise.


TB_ISBUTTONINDETERMINATE

The TB_ISBUTTONINDETERMINATE message determines whether the specified button in a toolbar is indeterminate.

TB_ISBUTTONINDETERMINATE

wParam = (WPARAM) idButton;

lParam = 0;

Parameters

idButton

Command identifier of the button.

Return Values

Returns nonzero if the button is indeterminate or zero otherwise.


TB_ISBUTTONPRESSED

The TB_ISBUTTONPRESSED message determines whether the specified button in a toolbar is pressed.

TB_ISBUTTONPRESSED

wParam = (WPARAM) idButton;

lParam = 0;

Parameters

idButton

Command identifier of the button.

Return Values

Returns nonzero if the button is pressed or zero otherwise.


TB_PRESSBUTTON

The TB_PRESSBUTTON message presses or releases the specified button in a toolbar.

TB_PRESSBUTTON

wParam = (WPARAM) idButton;

lParam = (LPARAM) MAKELONG(fPress, 0);

Parameters

idButton

Command identifier of the button to press or release.

fPress

Press flag. If this parameter is TRUE, the button is pressed. If it is FALSE, the button is released.

Return Values

Returns TRUE if successful or FALSE otherwise.


TB_SAVERESTORE

The TB_SAVERESTORE message saves or restores the state of the toolbar.

TB_SAVERESTORE

wParam = (WPARAM) (BOOL) fSave;

lParam = (LPARAM)  (TBSAVEPARAMS *)ptbsp;

Parameters

fSave

Save or restore flag. If this parameter is TRUE, the information is saved. If it is FALSE, it is restored.

ptbsp

Pointer to a TBSAVEPARAMS structure that specifies the registry key, subkey, and value name for the toolbar state information.

Return Values

No return value.

See Also

TBSAVEPARAMS


TB_SETBITMAPSIZE

The TB_SETBITMAPSIZE message sets the size of the bitmapped images to be added to a toolbar.

TB_SETBITMAPSIZE

wParam = 0;

lParam = (LPARAM) MAKELONG(dxBitmap, dyBitmap)

Parameters

dxBitmap

Width, in pixels, of the bitmapped images.

dyBitmap

Height, in pixels, of the bitmapped images.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The size can be set only before adding any bitmaps to the toolbar. If an application does not explicitly set the bitmap size, the size defaults to 16 by 15 pixels.


TB_SETBUTTONSIZE

The TB_SETBUTTONSIZE sets the size of the buttons to be added to a toolbar.

TB_SETBUTTONSIZE

wParam = 0;

lParam = (LPARAM) MAKELONG(dxButton, dyButton)

Parameters

dxButton

Width, in pixels, of the buttons.

dyButton

Height, in pixels, of the buttons.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The size can be set only before adding any buttons to the toolbar. If an application does not explicitly set the button size, the size defaults to 24 by 22 pixels.


TB_SETCMDID

The TB_SETCMDID message sets the command identifier of a toolbar button.

TB_SETCMDID

wParam = (WPARAM) (UINT) index;

lParam = (WPARAM) (UINT) cmdId;

Parameters

index

Zero-based index of the button whose command identifier is to be set.

cmdId

Command identifier.

Return Values

Returns TRUE if successful or FALSE otherwise.


TB_SETPARENT

The TB_SETPARENT message sets the parent window for a toolbar.

TB_SETPARENT

wParam = (WPARAM) (HWND) hwndParent;

lParam = 0;

Parameters

hwndParent

Handle to the new parent window.

Return Values

No return value.


TB_SETROWS

The TB_SETROWS message sets the number of rows of buttons in a toolbar.

TB_SETROWS

wParam = (WPARAM) MAKEWPARAM(cRows, fLarger);

lParam = (LPARAM) (LPRECT) lprc;

Parameters

cRows

Number of rows requested. The minimum number of rows is one, and the maximum is equal to the number of buttons in the toolbar.

fLarger

Flag that indicates whether to create more rows than requested when the system cannot create the number of rows specified by cRows. If this parameter is TRUE, the system creates more rows. If it is FALSE, the system creates fewer rows.

lprc

Pointer to a RECT structure that receives the bounding rectangle of the toolbar after the rows are set.

Return Values

No return value.

Remarks

Because the system does not break up button groups when setting the number of rows, the resulting number of rows might differ from the number requested.

See Also

RECT


TB_SETSTATE

The TB_SETSTATE message sets the state for the specified button in a toolbar.

TB_SETSTATE

wParam = (WPARAM) idButton;

lParam = (LPARAM) MAKELONG(fState, 0);

Parameters

idButton

Command identifier of the button.

fState

State flags. This parameter can be a combination of the values listed in Toolbar Button States.

Return Values

Returns TRUE if successful or FALSE otherwise.


TB_SETTOOLTIPS

The TB_SETTOOLTIPS message associates a tooltip control with a toolbar.

TB_SETTOOLTIPS

wParam = (WPARAM) (HWND) hwndToolTip;

lParam = 0;

Parameters

hwndToolTip

Handle to the tooltip control.

Return Values

No return value.

Remarks

Any buttons added to a toolbar before sending the TB_SETTOOLTIPS message are not registered with the tooltip control.


TBM_CLEARSEL

The TBM_CLEARSEL message clears the current selection in a trackbar.

TBM_CLEARSEL

wParam = (WPARAM) (BOOL) fRedraw;

lParam = 0;

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the trackbar is redrawn after the selection is cleared.

Return Values

No return value.


TBM_CLEARTICS

The TBM_CLEARTICS message removes the current tick marks from a trackbar.

TBM_CLEARTICS

wParam = (WPARAM) (BOOL) fRedraw;

lParam = 0;

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the trackbar is redrawn after the tick marks are cleared.

Return Values

No return value.


TBM_GETCHANNELRECT

The TBM_GETCHANNELRECT message retrieves the size and position of the bounding rectangle for a trackbar’s channel. (The channel is the area over which the slider moves and which contains the highlight when a range is selected.)

TBM_GETCHANNELRECT
wParam = 0;

lParam = (LPARAM) (LPRECT) lprc;

Parameters

lprc

Pointer to a RECT structure that contains the size and position of the channel’s bounding rectangle when the function returns.

Return Values

No return value.

See Also

RECT


TBM_GETLINESIZE

The TBM_GETLINESIZE message retrieves the size of the line for a trackbar. The line size affects how much the slider moves for the TB_LINEUP and TB_LINEDOWN notification messages.

TBM_GETLINESIZE
wParam = 0;

lParam = 0;

Return Values

Returns a 32-bit value that specifies the size of a line for the trackbar.

Remarks

The default setting for the line size is 1.


TBM_GETNUMTICS

The TBM_GETNUMTICS message retrieves the number of tick marks in a trackbar.

TBM_GETNUMTICS
wParam = 0;

lParam = 0;

Return Values

Returns the number of tick marks.

Remarks

This message returns all of the tick marks, including the first and last tick marks created by the trackbar.


TBM_GETPAGESIZE

The TBM_GETPAGESIZE message retrieves the size of the page for a trackbar. The page size affects how much the slider moves for the TB_PAGEUP and TB_PAGEDOWN notification messages.

TBM_GETPAGESIZE
wParam = 0;

lParam = 0;

Return Values

Returns a 32-bit value that specifies the size of a page for the trackbar.


TBM_GETPOS

The TBM_GETPOS message retrieves the current position of the slider in a trackbar.

TBM_GETPOS

wParam = 0;

lParam = 0;

Return Values

Returns a 32-bit value that specifies the current position.


TBM_GETPTICS

The TBM_GETPTICS message retrieves the pointer to the array that contains the positions of tick marks for a trackbar.

TBM_GETPTICS

wParam = 0;

lParam = 0;

Return Values

Returns the pointer to the array.


TBM_GETRANGEMAX

The TBM_GETRANGEMAX message retrieves the maximum position for the slider in a trackbar.

TBM_GETRANGEMAX

wParam = 0;

lParam = 0;

Return Values

Returns a 32-bit value that specifies the maximum position.


TBM_GETRANGEMIN

The TBM_GETRANGEMIN message retrieves the minimum position for the slider in a trackbar.

TBM_GETRANGEMIN

wParam = 0;

lParam = 0;

Return Values

Returns a 32-bit value that specifies the minimum position.


TBM_GETSELEND

The TBM_GETSELEND message retrieves the ending position of the current selection in a trackbar.

TBM_GETSELEND

wParam = 0;

lParam = 0;

Return Values

Returns a 32-bit value that specifies the ending position of the current selection.


TBM_GETSELSTART

The TBM_GETSELSTART message retrieves the starting position of the current selection in a trackbar.

TBM_GETSELSTART

wParam = 0;

lParam = 0;

Return Values

Returns a 32-bit value that specifies the starting position of the current selection.


TBM_GETTHUMBLENGTH

The TBM_GETTHUMBLENGTH message retrieves the length of the slider in a trackbar.

TBM_GETTHUMBLENGTH

wParam = 0;

lParam = 0;

Return Values

Returns the length, in pixels, of the slider.


TBM_GETTHUMBRECT

The TBM_GETTHUMBRECT message retrieves the size and position of the bounding rectangle for the slider in a trackbar.

TBM_GETTHUMBRECT

wParam = 0;

lParam = (LPARAM) (LPRECT) lprc;

Parameters

lprc

Pointer to a RECT structure that contains the bounding rectangle for the slider when the function returns.

Return Values

No return value.

See Also

RECT


TBM_GETTIC

The TBM_GETTIC message retrieves the position of a tick mark in a trackbar.

TBM_GETTIC

wParam = (WPARAM) (WORD) iTic;

lParam = 0;

Parameters

iTic

Zero-based index identifying a tick mark.

Return Values

Returns the position of the specified tick mark or  − 1 if iTic does not specify a valid index.


TBM_GETTICPOS

The TBM_GETTICPOS message retrieves the current physical position of a tick mark in a trackbar.

TBM_GETTICPOS

wParam = (WPARAM) (WORD) iTic;

lParam = 0;

Parameters

iTic

Zero-based index identifying a tick mark.

Return Values

Returns the physical position, in client coordinates, of the specified tick mark or − 1 if iTic does not specify a valid index.


TBM_SETLINESIZE

The TBM_SETLINESIZE message sets the size of the line for a trackbar. The line size affects how much the slider moves for the TB_LINEUP and TB_LINEDOWN notification messages.

TBM_SETLINESIZE
wParam = 0;

lParam = (LONG) lLineSize;

Parameters

lLineSize

New line size.

Return Values

Returns a 32-bit value that specifies the previous line size.


TBM_SETPAGESIZE

The TBM_SETPAGESIZE message sets the size of the page for a trackbar. The page size affects how much the slider moves for the TB_PAGEUP and TB_PAGEDOWN notification messages.

TBM_SETPAGESIZE
wParam = 0;

lParam = (LONG) lPageSize;

Parameters

lPageSize

New page size.

Return Values

Returns a 32-bit value that specifies the previous page size.


TBM_SETPOS

The TBM_SETPOS message sets the current position of the slider in a trackbar.

TBM_SETPOS

wParam = (WPARAM) (BOOL) fPosition;

lParam = (LPARAM) (LONG) lPosition;

Parameters

fPosition

Position flag. If this parameter is TRUE, the message sets the slider to the position given by lPosition. Otherwise, the message ensures that the current position is within the current minimum and maximum positions, but it does not move the slider.

lPosition

New position of the slider.

Return Values

No return value.


TBM_SETRANGE

The TBM_SETRANGE message sets the range (minimum and maximum positions) for the slider in a trackbar.

TBM_SETRANGE

wParam = (WPARAM) (BOOL) fRedraw;

lParam = (LPARAM) MAKELONG(lMinimum, lMaximum);

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the slider is redrawn after the range is set.

lMinimum

Minimum position for the slider.

lMaximum

Maximum position for the slider.

Return Values

No return value.


TBM_SETRANGEMAX

The TBM_SETRANGEMAX message sets the maximum position for the slider in a trackbar.

TBM_SETRANGEMAX

wParam = (WPARAM) fRedraw;

lParam = (LPARAM) lMaximum;

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the slider is redrawn after the range is set.

lMaximum

Maximum position for the slider.

Return Values

No return value.


TBM_SETRANGEMIN

The TBM_SETRANGEMIN message sets the minimum position for the slider in a trackbar.

TBM_SETRANGEMIN

wParam = (WPARAM) fRedraw;

lParam = (LPARAM) lMinimum;

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the slider is redrawn after the range is set.

lMinimum

Minimum position for the slider.

Return Values

No return value.


TBM_SETSEL

The TBM_SETSEL message sets the starting and ending positions for the current selection in a trackbar.

TBM_SETSEL

wParam = (WPARAM) (BOOL) fRedraw;

lParam = (LPARAM) MAKELONG(lMinimum, lMaximum);

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the slider is redrawn after the selection is set.

lMinimum

Starting position for the slider.

lMaximum

Ending position for the slider.

Return Values

No return value.


TBM_SETSELEND

The TBM_SETSELEND message sets the ending position of the current selection in a trackbar.

TBM_SETSELEND

wParam = (WPARAM) (BOOL) fRedraw;

lParam = (LPARAM) (LONG) lEnd;

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the slider is redrawn after the selection is set.

lEnd

Ending position of the selection.

Return Values

No return value.


TBM_SETSELSTART

The TBM_SETSELSTART message sets the starting position of the current selection in a trackbar.

TBM_SETSELSTART

wParam = (WPARAM) (BOOL) fRedraw;

lParam = (LPARAM) (LONG) lStart;

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the slider is redrawn after the selection is set.

lStart

Starting position of the selection.

Return Values

No return value.


TBM_SETTHUMBLENGTH

The TBM_SETTHUMBLENGTH message sets the length of the slider in a trackbar.

TBM_SETTHUMBLENGTH

wParam = (WPARAM) (UINT) iLength;

lParam = 0;

Parameters

iLength

Length, in pixels, of the slider.

Return Values

No return value.


TBM_SETTIC

The TBM_SETTIC message sets the position of a tick mark in a trackbar.

TBM_SETTIC

wParam = 0;

lParam = (LPARAM) (LONG) lPosition;

Parameters

lPosition

Position of the tick mark. This parameter must specify a positive value.

Return Values

Returns TRUE if the tick mark is set or FALSE otherwise.

Remarks

A trackbar creates its own first and last tick marks. An application should not use this message to set the first and last marks.


TBM_SETTICFREQ

The TBM_SETTICFREQ message sets the interval frequency for tick marks in a trackbar. For example, if the frequency is set to two, a tick mark is displayed for every other increment in the trackbar’s range. The default setting for the frequency is one; that is, every increment in the range is associated with a tick mark.

TBM_SETTICFREQ

wParam = (WPARAM) wFreq;

lParam = (LPARAM) (LONG) lPosition;

Parameters

wFreq

Frequency of the tick marks.

lPosition

Position of the tick mark. This parameter must specify a positive value.

Return Values

No return value.

Remarks

The trackbar must have the TBS_AUTOTICKS style to use this message.


TBN_BEGINADJUST

The TBN_BEGINADJUST notification message notifies a toolbar’s parent window that the user has begun customizing a toolbar. This message is sent in the form of a WM_NOTIFY message.

TBN_BEGINADJUST

pnmhdr = (NMHDR FAR *) lParam;

Parameters

pnmhdr

Pointer to an NMHDR structure that contains information about the notification message.

Return Values

No return value.

See Also

NMHDR, WM_NOTIFY


TBN_BEGINDRAG

The TBN_BEGINDRAG notification message notifies a toolbar’s parent window that the user has begun dragging a button in a toolbar. This message is sent in the form of a WM_NOTIFY message.

TBN_BEGINDRAG

ptbn = (TBNOTIFY FAR *) lParam;

Parameters

ptbn

Pointer to a TBNOTIFY structure. The iItem member contains the zero-based index of the button being dragged.

Return Values

No return value.

See Also

TBNOTIFY, WM_NOTIFY


TBN_CUSTHELP

The TBN_CUSTHELP notification message notifies a toolbar’s parent window that the user has chosen the Help button in the Customize Toolbar dialog box. This message is sent in the form of a WM_NOTIFY message.

TBN_CUSTHELP

pnmhdr = (NMHDR FAR *) lParam;

Parameters

pnmhdr

Pointer to an NMHDR structure that contains information about the notification message.

Return Values

No return value.

See Also

NMHDR, WM_NOTIFY


TBN_ENDADJUST

The TBN_ENDADJUST notification message notifies a toolbar’s parent window that the user has stopped customizing a toolbar. This message is sent in the form of a WM_NOTIFY message.

TBN_ENDADJUST

pnmhdr = (NMHDR FAR *) lParam;

Parameters

pnmhdr

Pointer to an NMHDR structure that contains information about the notification message.

Return Values

No return value.

See Also

NMHDR, WM_NOTIFY


TBN_ENDDRAG

The TBN_ENDDRAG notification message notifies the toolbar’s parent window that the user has stopped dragging a button in a toolbar. This message is sent in the form of a WM_NOTIFY message.

TBN_ENDDRAG

ptbn = (TBNOTIFY FAR *) lParam;

Parameters

ptbn

Pointer to a TBNOTIFY structure. The iItem member contains the zero-based index of the button being dragged.

Return Values

No return value.

See Also

TBNOTIFY, WM_NOTIFY


TBN_GETBUTTONINFO

The TBN_GETBUTTONINFO message retrieves toolbar customization information and notifies the toolbar’s parent window of any changes being made to the toolbar. This is sent in the form of a WM_NOTIFY message.

TBN_GETBUTTONINFO

ptbn = (TBNOTIFY FAR *) lParam;

Parameters

ptbn

Pointer to a TBNOTIFY structure. The iItem member specifies a zero-based index that provides a count of the buttons the customize dialog box displays as both available and present on the toolbar.

The pszText member specifies the address of the current button text, and cchText specifies its length in characters. The application should fill the structure with information about the button.

Return Values

Returns TRUE if button information was copied to the specified structure or FALSE otherwise.

Remarks

The toolbar control allocates a buffer, and the receiver (parent window) must copy the text into that buffer. The cchText member contains the length of the buffer allocated by the toolbar when TBN_GETBUTTONINFO is sent to the parent window.

See Also

TBNOTIFY, WM_NOTIFY


TBN_QUERYDELETE

The TBN_QUERYDELETE notification message notifies the toolbar’s parent window whether a button may be deleted from a toolbar while the user is customizing a toolbar. This message is sent in the form of a WM_NOTIFY message.

TBN_QUERYDELETE

ptbn = (TBNOTIFY FAR *) lParam;

Parameters

ptbn

Pointer to a TBNOTIFY structure. The iItem member contains the zero-based index of the button to be deleted.

Return Values

Returns TRUE to allow the button to be deleted or FALSE to prevent the button from being deleted.

See Also

TBNOTIFY, WM_NOTIFY


TBN_QUERYINSERT

The TBN_QUERYINSERT notification message notifies the toolbar’s parent window whether a button may be inserted to the left of the specified button while the user is customizing a toolbar. This message is sent in the form of a WM_NOTIFY message.

TBN_QUERYINSERT

ptbn = (TBNOTIFY FAR *) lParam;

Parameters

ptbn

Pointer to a TBNOTIFY structure. The iItem member contains the zero-based index of the button to be inserted.

Return Values

Returns TRUE to allow a button to inserted in front of the given button or FALSE to prevent the button from being inserted.

See Also

TBNOTIFY, WM_NOTIFY


TBN_RESET

The TBN_RESET notification message notifies the toolbar’s parent window that the user has reset the content of the Customize Toolbar dialog box. This message is sent in the form of a WM_NOTIFY message.

TBN_RESET

pnmhdr = (NMHDR FAR *) lParam;

Parameters

pnmhdr

Pointer to an NMHDR structure that contains information about the notification message.

Return Values

No return value.

See Also

NMHDR, WM_NOTIFY


TBN_TOOLBARCHANGE

The TBN_TOOLBARCHANGE notification message notifies the toolbar’s parent window that the user has customized a toolbar. This message is sent in the form of a WM_NOTIFY message.

TBN_TOOLBARCHANGE

pnmhdr = (NMHDR FAR *) lParam;

Parameters

pnmhdr

Pointer to an NMHDR structure that contains information about the notification message.

Return Values

No return value.

See Also

NMHDR, WM_NOTIFY


TCM_ADJUSTRECT

The TCM_ADJUSTRECT message calculates a tab control’s display area given a window rectangle or calculates the window rectangle that would correspond to a specified display area. You can send this message explicitly or by using the TabCtrl_AdjustRect macro.

TCM_ADJUSTRECT

wParam = (WPARAM) (BOOL) fLarger;  // operation to perform

lParam = (LPARAM) (LPRECT) prc;    // pointer to a RECT structure

Parameters

fLarger

Operation to perform. If this parameter is TRUE, prc specifies a display rectangle and receives the corresponding window rectangle. If this parameter is FALSE, prc specifies a window rectangle and receives the corresponding display area.

prc

Pointer to a RECT structure that specifies the given rectangle and receives the calculated rectangle.

Return Values

No return value.

See Also

RECT, TabCtrl_AdjustRect


TCM_DELETEALLITEMS

The TCM_DELETEALLITEMS message removes all items from a tab control. You can send this message explicitly or by using the TabCtrl_DeleteAllItems macro.

TCM_DELETEALLITEMS

wParam = 0;           // not used; must be zero

lParam = 0;           // not used; must be zero

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TabCtrl_DeleteAllItems


TCM_DELETEITEM

The TCM_DELETEITEM message removes an item from a tab control. You can send this message explicitly or by using the TabCtrl_DeleteItem macro.

TCM_DELETEITEM

wParam = (WPARAM) (int) iItem;  // index of the item to delete

lParam = 0;                     // not used; must be zero

Parameters

iItem

Index of the item to delete.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TabCtrl_DeleteItem


TCM_GETCURFOCUS

The TCM_GETCURFOCUS message returns the index of the item that has the focus in a tab control. You can send this message explicitly or by using the TabCtrl_GetCurFocus macro.

TCM_GETCURFOCUS

wParam = 0;  // not used; must be zero

lParam = 0;  // not used; must be zero

Return Values

Returns the index of the tab item that has the focus

Remarks

The item that has the focus may be different than the selected item.

See Also

TabCtrl_GetCurFocus


TCM_GETCURSEL

The TCM_GETCURSEL message determines the currently selected tab in a tab control. You can send this message explicitly or by using the TabCtrl_GetCurSel macro.

TCM_GETCURSEL

wParam = 0;   // not used; must be zero

lParam = 0;   // not used; must be zero

Return Values

Returns the index of the selected tab if successful or  − 1 if no tab is selected.

See Also

TabCtrl_GetCurSel


TCM_GETIMAGELIST

The TCM_GETIMAGELIST message retrieves the image list associated with a tab control. You can send this message explicitly or by using the TabCtrl_GetImageList macro.

TCM_GETIMAGELIST

wParam = 0;   // not used; must be zero

lParam = 0;   // not used; must be zero

Return Values

Returns the handle to the image list if successful or NULL otherwise.

See Also

TabCtrl_GetImageList


TCM_GETITEM

The TCM_GETITEM message retrieves information about a tab in a tab control. You can send this message explicitly or by using the TabCtrl_GetItem macro.

TCM_GETITEM

wParam = (WPARAM) (int) iItem;

lParam = (LPARAM) (TC_ITEM FAR *) pitem;

Parameters

iItem

Index of the tab.

pitem

Pointer to a TC_ITEM structure that specifies the information to retrieve and receives information about the tab. When the message is sent, the mask member specifies which attributes to return.

If the mask member specifies the TCIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TabCtrl_GetItem, TC_ITEM


TCM_GETITEMCOUNT

The TCM_GETITEMCOUNT message retrieves the number of tabs in the tab control. You can send this message explicitly or by using the TabCtrl_GetItemCount macro.

TCM_GETITEMCOUNT

wParam = 0;   // not used; must be zero

lParam = 0;   // not used; must be zero

Return Values

Returns the number of items if successful or zero otherwise.

See Also

TabCtrl_GetItemCount


TCM_GETITEMRECT

The TCM_GETITEMRECT message retrieves the bounding rectangle for a tab in a tab control. You can send this message explicitly or by using the TabCtrl_GetItemRect macro.

TCM_GETITEMRECT

wParam = (WPARAM) (int) iItem;       // index of the tab

lParam = (LPARAM) (RECT FAR *) prc;  // pointer to a structure to receive rectangle of tab

Parameters

iItem

Index of the tab.

prc

Pointer to a RECT structure that receives the bounding rectangle of the tab, in viewport coordinates.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

RECT, TabCtrl_GetItemRect


TCM_GETROWCOUNT

The TCM_GETROWCOUNT message retrieves the current number of rows of tabs in a tab control. You can send this message explicitly or by using the TabCtrl_GetRowCount macro.

TCM_GETROWCOUNT

wParam = 0;   // not used; must be zero

lParam = 0;   // not used; must be zero

Return Values

Returns the number of rows of tabs.

Remarks

Only tab controls that have the TCS_MULTILINE style can have multiple rows of tabs.

See Also

TabCtrl_GetRowCount


TCM_GETTOOLTIPS

The TCM_GETTOOLTIPS message retrieves the handle to the tooltip control associated with a tab control. You can send this message explicitly or by using the TabCtrl_GetToolTips macro.

TCM_GETTOOLTIPS

wParam = 0;   // not used; must be zero

lParam = 0;   // not used; must be zero

Return Values

Returns the handle to the tooltip control if successful or NULL otherwise.

Remarks

A tab control creates a tooltip control if it has the TCS_TOOLTIPS style. You can also assign a tooltip control to a tab control by using the TCM_SETTOOLTIPS message.

See Also

TabCtrl_GetToolTips, TCM_SETTOOLTIPS


TCM_HITTEST

The TCM_HITTEST message determines which tab, if any, is at a specified screen position. You can send this message explicitly or by using the TabCtrl_HitTest macro.

TCM_HITTEST

wParam = 0;    // not used; must be zero

lParam = (LPARAM) (TC_HITTESTINFO FAR *) pinfo; \\pointer to struct specifying position to test

Parameters

pinfo

Pointer to a TC_HITTESTINFO structure that specifies the screen position to test.

Return Values

Returns the index of the tab or  − 1 if no tab is at the specified position.

See Also

TabCtrl_HitTest, TC_HITTESTINFO


TCM_INSERTITEM

The TCM_INSERTITEM message inserts a new tab in a tab control. You can send this message explicitly or by using the TabCtrl_InsertItem macro.

TCM_INSERTITEM

wParam = (WPARAM) (int) iItem;                 \\index of the new tab

lParam = (LPARAM) (const TC_ITEM FAR*) pitem;  \\pointer to struct specifying tab attributes

Parameters

iItem

Index of the new tab.

pitem

Pointer to a TC_ITEM structure that specifies the attributes of the tab.

Return Values

Returns the index of the new tab if successful or  − 1 otherwise.

See Also

TabCtrl_InsertItem, TC_ITEM


TCM_REMOVEIMAGE

The TCM_REMOVEIMAGE message removes an image from a tab control’s image list. You can send this message explicitly or by using the TabCtrl_RemoveImage macro.

TCM_REMOVEIMAGE

wParam = (WPARAM) (int) iImage;  // index of the image to remove

lParam = 0;                      // not used; must be zero

Parameters

iImage

Index of the image to remove.

Return Values

No return value.

Remarks

The tab control updates each tab’s image index, so each tab remains associated with the same image it had been.

See Also

TabCtrl_RemoveImage


TCM_SETCURFOCUS

The TCM_SETCURFOCUS message sets the focus to a specified tab in a tab control. You can send this message explicitly or by using the TabCtrl_SetCurFocus macro.

TCM_SETCURFOCUS

wParam = (WPARAM) (int) iItem;  // index of the tab that gets the focus

lParam = 0;                     // not used; must be zero

Parameters

iItem

Specifies the index of the tab that gets the focus.

Return Values

No return value.

Remarks

If the tab control has the TCS_BUTTONS style (button mode), the tab with the focus may be different from the selected tab. For example, when a tab is selected, the user can press the arrow keys to set the focus to a different tab without changing the selected tab. In button mode, TCM_SETCURFOCUS sets the input focus to the button associated with the specified tab, but it does not change the selected tab.

If the tab control does not have the TCS_BUTTONS style, changing the focus also changes selected tab. In this case, the tab control sends the TCN_SELCHANGING and TCN_SELCHANGE notification messages to its parent window.

See Also

TabCtrl_GetCurFocus, TCM_GETCURFOCUS, TCN_SELCHANGE, TCN_SELCHANGING, TCM_SETCURFOCUS


TCM_SETCURSEL

The TCM_SETCURSEL message selects a tab in a tab control. You can send this message explicitly or by using the TabCtrl_SetCurSel macro.

TCM_SETCURSEL

wParam = (WPARAM) (int) iItem;  // index of the tab to select

lParam = 0;                     // not used; must be zero

Parameters

iItem

Index of the tab to select.

Return Values

Returns the index of the previously selected tab if successful or  − 1 otherwise.

Remarks

A tab control does not send a TCN_SELCHANGING or TCN_SELCHANGE notification message when a tab is selected using this message.

See Also

TabCtrl_SetCurSel, TCN_SELCHANGE, TCN_SELCHANGING


TCM_SETIMAGELIST

The TCM_SETIMAGELIST message assigns an image list to a tab control. You can send this message explicitly or by using the TabCtrl_SetImageList macro.

TCM_SETIMAGELIST

wParam = 0;                           // not used; must be zero

lParam = (LPARAM) (HIMAGELIST) himl;  // handle of image list to assign to tab control

Parameters

himl

Handle of the image list to assign to the tab control.

Return Values

Returns the handle to the previous image list or NULL if there is no previous image list.

See Also

TabCtrl_SetImageList


TCM_SETITEM

The TCM_SETITEM message sets some or all of a tab’s attributes. You can send this message explicitly or by using the TabCtrl_SetItem macro.

TCM_SETITEM

wParam = (WPARAM) (int) iItem;            // index of the item

lParam = (LPARAM) (TC_ITEM FAR *) pitem;  // pointer to struct containing item attributes

Parameters

iItem

Index of the item.

pitem

Pointer to a TC_ITEM structure that contains the new item attributes. The mask member specifies which attributes to set.

If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TabCtrl_SetItem, TC_ITEM


TCM_SETITEMEXTRA

The TCM_SETITEMEXTRA message sets the number of bytes per tab reserved for application-defined data in a tab control. You can send this message explicitly or by using the TabCtrl_SetItemExtra macro.

TCM_SETITEMEXTRA

wParam = (WPARAM) (int) cb;  // number of extra bytes

lParam = 0;                  // not used; must be zero

Parameters

cb

Number of extra bytes.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

By default, the number of extra bytes is four. An application that changes the number of extra bytes cannot use the TC_ITEM structure to retrieve and set the application-defined data for a tab. Instead, you must define a new structure that consists of the TC_ITEMHEADER structure followed by application-defined members.

An application should only change the number of extra bytes when a tab control does not contain any tabs.

See Also

TabCtrl_SetItemExtra, TC_ITEM, TC_ITEMHEADER


TCM_SETITEMSIZE

The TCM_SETITEMSIZE message sets the width and height of tabs in a fixed-width or owner-drawn tab control. You can send this message explicitly or by using the TabCtrl_SetItemSize macro.

TCM_SETITEMSIZE

wParam = 0;                   // not used; must be zero

lParam = MAKELPARAM(cx, cy);  // new width and height, in pixels

Parameters

cx and cy

New width and height, in pixels.

Return Values

Returns the old width and height. The width is in the low-order word of the return value, and the height is in the high-order word.

See Also

TabCtrl_SetItemSize


TCM_SETPADDING

The TCM_SETPADDING message sets the amount of space (padding) around each tab’s icon and label in a tab control. You can send this message explicitly or by using the TabCtrl_SetPadding macro.

TCM_SETPADDING

wParam = 0;                   // not used; must be zero

lParam = MAKELPARAM(cx, cy);  // amount of horizontal and vertical padding, in pixels

Parameters

cx and cy

Amount of horizontal and vertical padding, in pixels.

Return Values

No return value.

See Also

TabCtrl_SetPadding


TCM_SETTOOLTIPS

The TCM_SETTOOLTIPS message assigns a tooltip control to a tab control. You can send this message explicitly or by using the TabCtrl_SetToolTips macro.

TCM_SETTOOLTIPS

wParam = (WPARAM) (HWND) hwndTT;  // handle to the tooltip control

lParam = 0;                       // not used; must be zero

Parameters

hwndTT

Handle to the tooltip control.

Return Values

No return value.

Remarks

You can get the tooltip control associated with a tab control by using the TCM_GETTOOLTIPS message.

See Also

TabCtrl_SetToolTips, TCM_GETTOOLTIPS


TCN_KEYDOWN

The TCN_KEYDOWN notification message notifies a tab control’s parent window that a key has been pressed. This message is sent in the form of a WM_NOTIFY message.

TCN_KEYDOWN

pnm = (TC_KEYDOWN FAR *) lParam;

Parameters

pnm

Pointer to a TC_KEYDOWN structure.

Return Values

No return value.

See Also

TC_KEYDOWN, WM_NOTIFY


TCN_SELCHANGE

The TCN_SELCHANGE notification message notifies a tab control’s parent window that the currently selected tab has changed. This message is sent in the form of a WM_NOTIFY message.

TCN_SELCHANGE

idTabCtl = (int) LOWORD(wParam);

lpnmhdr = (LPNMHDR) lParam;

Parameters

idTabCtl

Specifies the child window identifier of the tab control.

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle of the tab control. The idFrom member is the child window identifier of the tab control. The code member is TCN_SELCHANGE.

Return Values

No return value.

Remarks

To determine the currently selected tab, use the TabCtrl_GetCurSel macro.

See Also

NMHDR, TabCtrl_GetCurSel, TCN_SELCHANGING, WM_NOTIFY


TCN_SELCHANGING

The TCN_SELCHANGING notification message notifies a tab control’s parent window that the currently selected tab is about to change. This message is sent in the form of a WM_NOTIFY message.

TCN_SELCHANGING

idTabCtl = (int) LOWORD(wParam);

lpnmhdr = (LPNMHDR) lParam;

Parameters

idTabCtl

Specifies the child window identifier of the tab control.

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle of the tab control. The idFrom member is the child window identifier of the tab control. The code member is TCN_SELCHANGING.

Return Values

Returns TRUE to prevent the selection from changing or FALSE to allow the selection to change.

Remarks

To determine the currently selected tab, use the TabCtrl_GetCurSel macro.

See Also

NMHDR, TabCtrl_GetCurSel, TCN_SELCHANGE, WM_NOTIFY


TTM_ACTIVATE

The TTM_ACTIVATE message activates or deactivates a tooltip control.

TTM_ACTIVATE

wParam = (WPARAM) (BOOL) fActivate;

lParam = 0;

Parameters

fActivate

Activation flag. If this parameter is TRUE, the tooltip control is activated. If it is FALSE, the tooltip control is deactivated.

Return Values

No return value.


TTM_ADDTOOL

The TTM_ADDTOOL message registers a tool with a tooltip control.

TTM_ADDTOOL

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

lpti

Pointer to a TOOLINFO structure containing information that the tooltip control needs to display text for the tool. Before sending this message, you must set the cbSize member of this structure to sizeof(TOOLINFO).

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TOOLINFO


TTM_DELTOOL

The TTM_DELTOOL message removes a tool from a tooltip control.

TTM_DELTOOL

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

lpti

Pointer to a TOOLINFO structure. The hwnd and uId members identify the tool to remove, and the cbSize member must specify the size of the structure. All other members are ignored.

Return Values

No return value.

See Also

TOOLINFO


TTM_ENUMTOOLS

The TTM_ENUMTOOLS message retrieves the information that a tooltip control maintains about the current tool; that is, the tool for which the tooltip is currently displaying text.

TTM_ENUMTOOLS

wParam = (WPARAM) (UINT) iTool;

lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

iTool

Zero-based index of the tool for which to retrieve information.

lpti

Pointer to a TOOLINFO structure that receives information about the tool. Before sending this message, the cbSize member must specify the size of the structure.

Return Values

Returns TRUE if any tools are enumerated or FALSE otherwise.

Remarks

Retrieves the information that a tooltip control maintains about a tool.

See Also

TOOLINFO


TTM_GETCURRENTTOOL

The TTM_GETCURRENTTOOL message retrieves the text that a tooltip control maintains for a tool.

TTM_GETCURRENTTOOL

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

lpti

Pointer to a TOOLINFO structure that receives information about the current tool. Before sending this message, you must set the cbSize member of this structure to sizeof(TOOLINFO).

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TOOLINFO


TTM_GETTEXT

The TTM_GETTEXT message retrieves a count of the tools maintained by a tooltip control.

TTM_GETTEXT

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

lpti

Pointer to a TOOLINFO structure. When sending the message, the hwnd and uId members identify a tool. If the tooltip control includes the tool, the lpszText member receives the pointer to the string. Before sending this message, you must set the cbSize member of this structure to sizeof(TOOLINFO).

Return Values

No return value.

See Also

TOOLINFO


TTM_GETTOOLCOUNT

The TTM_GETTOOLCOUNT message retrieves the information that a tooltip control maintains about a tool.

TTM_GETTOOLCOUNT

wParam = 0;

lParam = 0;

Return Values

Returns a count of tools.


TTM_GETTOOLINFO

The TTM_GETTOOLINFO message retrieves the information that a tooltip control maintains about a tool.

TTM_GETTOOLINFO

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

lpti

Pointer to a TOOLINFO structure. When sending the message, the hwnd and uId members identify a tool, and the cbSize member must specify the size of the structure. If the tooltip control includes the tool, the structure receives information about the tool.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TOOLINFO


TTM_HITTEST

The TTM_HITTEST message tests a point to determine whether it is within the bounding rectangle of the specified tool and, if the point is within, retrieves information about the tool.

TTM_HITTEST

wParam = 0;

lParam = (LPARAM) (LPHITTESTINFO) lphti;

Parameters

lphti

Pointer to a TTHITTESTINFO structure. When sending the message, the hwnd member must specify the handle of a tool and the pt member must specify the coordinates of a point. If the return value is TRUE, the ti member (a TOOLINFO structure) receives information about the tool that occupies the point. Before sending this message, you must set the cbSize member of the ti structure to sizeof(TOOLINFO).

Return Values

Returns TRUE if the tool occupies the specified point or FALSE otherwise.

See Also

TOOLINFO, TTHITTESTINFO


TTM_NEWTOOLRECT

The TTM_NEWTOOLRECT message sets a new bounding rectangle for a tool.

TTM_NEWTOOLRECT

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

lpti

Pointer to a TOOLINFO structure. The hwnd and uId members identify a tool, and the rect member specifies the new bounding rectangle. Before sending this message, you must set the cbSize member of this structure to sizeof(TOOLINFO).

Return Values

No return value.

See Also

TOOLINFO


TTM_RELAYEVENT

The TTM_RELAYEVENT message passes a mouse message to a tooltip control for processing.

TTM_RELAYEVENT

wParam = 0;

lParam = (LPARAM) (LPMSG) lpmsg;

Parameters

lpmsg

Pointer to an MSG structure that contains the message to relay.

Return Values

No return value.

Remarks

A tooltip control processes only the following messages passed to it by the TTM_RELAYEVENT message.

WM_LBUTTONDOWN	WM_MOUSEMOVE
WM_LBUTTONUP	WM_RBUTTONDOWN
WM_MBUTTONDOWN	WM_RBUTTONUP
WM_MBUTTONUP
All other messages are ignored.

See Also

MSG


TTM_SETDELAYTIME

The TTM_SETDELAYTIME message sets the initial, reshow, and autopopup durations for a tooltip control.

TTM_SETDELAYTIME

wParam = (WPARAM) uFlag;

lParam = (LPARAM) (int) iDelay;

Parameters

uFlag

Duration to set. This parameter can be one of the following values:

Value	Meaning
TTDT_AUTOMATIC	Automatically calculates the initial, reshow, and autopopup durations based on the value of iDelay.
TTDT_AUTOPOP	Sets the length of time before the tooltip window is hidden if the cursor remains stationary in the tool’s bounding rectangle after the tooltip window has appeared.
TTDT_INITIAL	Sets the length of time that the cursor must remain stationary within the bounding rectangle of a tool before the tooltip window is displayed.
TTDT_RESHOW	Sets the length of the delay before subsequent tooltip windows are displayed when the cursor is moved from one tool to another.
iDelay

New duration, in milliseconds.

Return Values

No return value.


TTM_SETTOOLINFO

The TTM_SETTOOLINFO message sets the information that a tooltip control maintains for a tool.

TTM_SETTOOLINFO

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

lpti

Pointer to a TOOLINFO structure that specifies the information to set. Before sending this message, you must set the cbSize member of this structure to sizeof(TOOLINFO).

Return Values

No return value.

See Also

TOOLINFO


TTM_UPDATETIPTEXT

The TTM_UPDATETIPTEXT message sets the tooltip text for a tool.

TTM_UPDATETIPTEXT

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

lpti

Pointer to a TOOLINFO structure. The hinst and lpszText members must specify the instance handle and the pointer to the text. The hwnd and uId members identify the tool to update. Before sending this message, you must set the cbSize member of this structure to sizeof(TOOLINFO).

Return Values

No return value.

See Also

TOOLINFO


TTM_WINDOWFROMPOINT

The TTM_WINDOWFROMPOINT message allows a subclass procedure to cause a tooltip to display text for a window other than the one beneath the mouse cursor.

TTM_WINDOWFROMPOINT

wParam = 0;

lParam = (POINT FAR *) lppt;

Parameters

lppt

Pointer to a POINT structure that defines the point to be checked.

Return Values

The return value is the handle to the window that contains the point, or NULL if no window exists at the specified point.

Remarks

This message is intended to be processed by an application that subclasses a tooltip. It is not intended to be sent by an application. A tooltip sends this message to itself before displaying the text for a window. By changing the coordinates of the point specified by lppt, the subclass procedure can cause the tooltip to display text for a window other than the one beneath the mouse cursor.

See Also

POINT


TTN_NEEDTEXT

The TTN_NEEDTEXT notification message retrieves text for a tool. This notification message is sent in the form of a WM_NOTIFY message.

TTN_NEEDTEXT

idTT = (int) wParam;

lpttt = (LPTOOLTIPTEXT) lParam;

Parameters

idTT

Identifier of the tooltip control.

lpttt

Pointer to a TOOLTIPTEXT structure. The hdr member identifies the tool for which text is needed. The receiving window can specify the string by taking one of the following actions:

•	Copying the text to the buffer specified by the szText member.

•	Copying the address of the buffer that contains the text to the lpszText member.

•	Copying the identifier of a string resource to the lpszText member and copying the handle of the instance that contains the resource to the hinst member.

Return Values

No return value.

Remarks

This notification message is sent to the window specified in the hwnd member of the TOOLINFO structure for the tool. This notification is sent only if the LPSTR_TEXTCALLBACK value is specified when the tool is added to a tooltip control.

When a TTN_NEEDTEXT notification is received, the application can set or clear the TTF_RTLREADING value in the uFlags member of the TOOLTIPTEXT structure pointed to by lpttt as required. This is the only flag that can be changed during the notification callback.

See Also

TOOLINFO, TOOLTIPTEXT, WM_NOTIFY


TTN_POP

The TTN_POP notification message notifies the owner window that a tooltip is about to be hidden. This notification message is sent in the form of a WM_NOTIFY message.

TTN_POP

idTT = (int) wParam;

pnmh = (NMHDR FAR *) lParam;

Parameters

idTT

Identifier of the tooltip control.

lpttt

Return Values

No return value.

Remarks

Address of an NMHDR structure.

See Also

NMHDR, WM_NOTIFY


TTN_SHOW

The TTN_SHOW notification message notifies the owner window that a tooltip is about to be displayed. This notification message is sent in the form of a WM_NOTIFY message.

TTN_SHOW

idTT = (int) wParam;

pnmh = (NMHDR FAR *) lParam;

Parameters

idTT

Identifier of the tooltip control.

lpttt

Return Values

No return value.

Remarks

Address of an NMHDR structure.

See Also

NMHDR, WM_NOTIFY


TVM_CREATEDRAGIMAGE

The TVM_CREATEDRAGIMAGE message creates a dragging bitmap for the specified item in a tree-view control, creates an image list for the bitmap, and adds the bitmap to the image list. An application can display the image when dragging the item by using the image-list functions. You can send this message explicitly or by using the TreeView_CreateDragImage macro.

TVM_CREATEDRAGIMAGE

wParam = 0;

lParam = (LPARAM) (HTREEITEM) hitem;

Parameters

hitem

Handle to the item that receives the new dragging bitmap.

Return Values

Returns the handle of the image list to which the dragging bitmap was added if successful or NULL otherwise.

Remarks

If you create a tree-view control without an associated image list, you cannot use the TVM_CREATEDRAGIMAGE message to create the image to display during a drag operation. You must implement your own way to support drag and drop cursor.

See Also

TreeView_CreateDragImage


TVM_DELETEITEM

The TVM_DELETEITEM message removes an item from a tree-view control. You can send this message explicitly or by using the TreeView_DeleteItem or TreeView_DeleteAllItems macro.

TVM_DELETEITEM

wParam = 0;

lParam = (LPARAM) (HTREEITEM) hitem;

Parameters

hitem

Handle to the item to delete. If hitem is the TVI_ROOT value, all items are deleted from the tree-view control.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

If the item label is being edited, the edit operation is canceled and the parent window receives the TVN_ENDLABELEDIT notification message. The parent window receives a TVN_DELETEITEM notification message when the item is removed.

See Also

TreeView_DeleteAllItems, TreeView_DeleteItem, TVN_DELETEITEM, TVN_ENDLABELEDIT


TVM_EDITLABEL

The TVM_EDITLABEL message begins in-place editing of the specified item’s text, replacing the text of the item with a single-line edit control containing the text. This message implicitly selects and focuses the specified item. You can send this message explicitly or by using the TreeView_EditLabel macro.

TVM_EDITLABEL

wParam = 0;

lParam = (LPARAM) (HTREEITEM) hitem;

Parameters

hitem

Handle to the item to edit.

Return Values

Returns the handle to the edit control used to edit the item text if successful or NULL otherwise.

Remarks

This message sends a TVN_BEGINLABELEDIT notification message to the parent of the tree-view control.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but do not destroy it.

The control must have the focus before you send this message to the control. Focus can be set using the SetFocus function.

See Also

TreeView_EditLabel, TVN_BEGINLABELEDIT, SetFocus


TVM_ENDEDITLABELNOW

The TVM_ENDEDITLABELNOW message ends the editing of a tree-view item’s label. You can send this message explicitly or by using the TreeView_EndEditLabelNow macro.

TVM_ENDEDITLABELNOW

wParam = (WPARAM) (BOOL) fCancel;

lParam = 0;

Parameters

fCancel

Variable that indicates whether the editing is canceled without being saved to the label. If this parameter is TRUE, the system cancels editing without saving the changes. Otherwise, the system saves the changes to the label.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

This message causes the TVN_ENDLABELEDIT notification message to be sent to the parent window of the tree-view control.

See Also

TreeView_EndEditLabelNow, TVN_ENDLABELEDIT


TVM_ENSUREVISIBLE

The TVM_ENSUREVISIBLE message ensures that a tree-view item is visible, expanding the parent item or scrolling the tree-view control, if necessary. You can send this message explicitly or by using the TreeView_EnsureVisible macro.

TVM_ENSUREVISIBLE

wParam = 0;

lParam = (LPARAM) (HTREEITEM) hitem;

Parameters

hitem

Handle to the item.

Return Values

Returns TRUE if the system scrolled the items in the tree-view control to ensure that the specified item is visible. Otherwise, the message returns FALSE.

Remarks

If the TVM_ENSUREVISIBLE message expands the parent item, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

See Also

TreeView_EnsureVisible, TVN_ITEMEXPANDED, TVN_ITEMEXPANDING


TVM_EXPAND

The TVM_EXPAND message expands or collapses the list of child items, if any, associated with the specified parent item. You can send this message explicitly or by using the TreeView_Expand macro.

TVM_EXPAND

wParam = (WPARAM) (UINT) flag;

lParam = (LPARAM) (HTREEITEM) hitem;

Parameters

flag

Action flag. This parameter can be one of the following values:

Value	Meaning
TVE_COLLAPSE	Collapses the list.
TVE_COLLAPSERESET	Collapses the list and removes the child items. Note that TVE_COLLAPSE must also be specified.
TVE_EXPAND	Expands the list.
TVE_TOGGLE	Collapses the list if it is currently expanded or expands it if it is currently collapsed.
hitem

Handle to the parent item to expand or collapse.

Return Values

Returns TRUE if any change took place or FALSE otherwise.

Remarks

This message does not send the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages to the parent window.

See Also

TreeView_Expand, TVN_ITEMEXPANDED, TVN_ITEMEXPANDING


TVM_GETCOUNT

The TVM_GETCOUNT message retrieves a count of the items in a tree-view control. You can send this message explicitly or by using the TreeView_GetCount macro.

TVM_GETCOUNT

wParam = 0;

lParam = 0;

Return Values

Returns the count of items.

See Also

TreeView_GetCount


TVM_GETEDITCONTROL

The TVM_GETEDITCONTROL message retrieves the handle to the edit control being used to edit a tree-view item’s text. You can send this message explicitly or by using the TreeView_GetEditControl macro.

TVM_GETEDITCONTROL

wParam = 0;

lParam = 0;

Return Values

Returns the handle to the edit control if successful or NULL otherwise.

See Also

TreeView_GetEditControl


TVM_GETIMAGELIST

The TVM_GETIMAGELIST message retrieves the handle to the normal or state image list associated with a tree-view control. You can send this message explicitly or by using the TreeView_GetImageList macro.

TVM_GETIMAGELIST

wParam = (WPARAM) iImage;

lParam = 0;

Parameters

iImage

Type of image list to retrieve. This parameter can be one of the following values:

Value	Meaning
TVSIL_NORMAL	Retrieves the normal image list, which contains the selected and unselected images for the tree-view item.
TVSIL_STATE	Retrieves the state image list, which contains the images for tree-view items that are in a user-defined state.
Return Values

Returns the handle to the image list.

See Also

TreeView_GetImageList


TVM_GETINDENT

The TVM_GETINDENT message retrieves the amount, in pixels, that child items are indented relative to their parent items. You can send this message explicitly or by using the TreeView_GetIndent macro.

TV_GETINDENT

wParam = 0;

lParam = 0;

Return Values

Returns the amount of indentation.

See Also

TreeView_GetIndent


TVM_GETISEARCHSTRING

The TVM_GETISEARCHSTRING message retrieves the incremental search string for a tree-view control. The tree-view control uses the incremental search string to select an item based on characters typed by the user. You can send this message explicitly or by using the TreeView_GetISearchString macro.

TVM_GETISEARCHSTRING

wParam = 0;

lParam = (LPARAM) (LPSTR) lpsz;

Parameters

lpsz

Pointer to the buffer that receives the incremental search string.

Return Values

Returns the number of characters in the incremental search string.

If the tree-view control is not in incremental search mode, the return value is zero.

See Also

TreeView_GetISearchString


TVM_GETITEM

The TVM_GETITEM message retrieves some or all of a tree-view item’s attributes. You can send this message explicitly or by using the TreeView_GetItem macro.

TVM_GETITEM

wParam = 0;

lParam = (LPARAM) (TV_ITEM FAR*) pitem;

Parameters

pitem

Pointer to a TV_ITEM structure that specifies the information to retrieve and receives information about the item. When the message is sent, the hItem member identifies the item to retrieve information about and the mask member specifies the attributes to retrieve.

If mask specifies the TVIF_TEXT value, the pszText member must contain the pointer to the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

If mask specifies the TVIF_STATE value, the stateMask member indicates which item states are to be returned.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TreeView_GetItem, TV_ITEM


TVM_GETITEMRECT

The TVM_GETITEMRECT message retrieves the bounding rectangle for a tree-view item and indicates whether the item is visible. You can send this message explicitly or by using the TreeView_GetItemRect macro.

TVM_GETITEMRECT

wParam = (WPARAM) (BOOL) fItemRect;

lParam = (LPARAM) (RECT FAR*) prc;

Parameters

fItemRect

Value specifying the portion of the item for which to retrieve the bounding rectangle. If this parameter is TRUE, the bounding rectangle includes only the text of the item. Otherwise, it includes the entire line that the item occupies in the tree-view control.

prc

Pointer to a RECT structure that receives the bounding rectangle. The coordinates are relative to the upper-left corner of the tree-view control.

Return Values

If the item is visible and retrieves the bounding rectangle, the return value is TRUE. Otherwise, the message returns FALSE and does not retrieve the bounding rectangle.

See Also

RECT, TreeView_GetItemRect


TVM_GETNEXTITEM

The TVM_GETNEXTITEM message retrieves the tree-view item that bears the specified relationship to a specified item. You can send this message explicitly, by using the TreeView_GetNextItem macro, or by using one of the following related macros: TreeView_GetChild, TreeView_GetDropHilite, TreeView_GetFirstVisible, TreeView_GetNextSibling, TreeView_GetNextVisible, TreeView_GetParent, TreeView_GetPrevSibling, TreeView_GetPrevVisible, TreeView_GetRoot, or TreeView_GetSelection.

TVM_GETNEXTITEM

wParam = (WPARAM) (UINT) flag;

lParam = (LPARAM) (HTREEITEM) hitem;

Parameters

flag

Flag specifying the item to retrieve. This parameter can be one of the following values:

Value	Message
TVGN_CARET	Retrieves the currently selected item. You can use the TreeView_GetSelection macro to send this message.
TVGN_CHILD	Retrieves the first child item of the item specified by the hitem parameter. You can use the TreeView_GetChild macro to send this message.
TVGN_DROPHILITE	Retrieves the item that is the target of a drag-and-drop operation. You can use the TreeView_GetDropHilite macro to send this message.
TVGN_FIRSTVISIBLE	Retrieves the first visible item. You can use the TreeView_GetFirstVisible macro to send this message.
TVGN_NEXT	Retrieves the next sibling item. You can use the TreeView_GetNextSibling macro to send this message.
TVGN_NEXTVISIBLE	Retrieves the next visible item that follows the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible. You can use the TreeView_GetNextVisible macro to send this message.
TVGN_PARENT	Retrieves the parent of the specified item. You can use the TreeView_GetParent macro to send this message.
TVGN_PREVIOUS	Retrieves the previous sibling item. You can use the TreeView_GetPrevSibling macro to send this message.
TVGN_PREVIOUSVISIBLE	Retrieves the first visible item that precedes the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible. You can use the TreeView_GetPrevVisible macro to send this message.
TVGN_ROOT	Retrieves the topmost or very first item of the tree-view control. You can use the TreeView_GetRoot macro to send this message.
hitem

Handle to an item.

Return Values

Returns the handle to the item if successful or NULL otherwise.

See Also

TreeView_GetChild, TreeView_GetDropHilite, TreeView_GetFirstVisible, TreeView_GetNextSibling, TreeView_GetNextVisible, TreeView_GetParent, TreeView_GetPrevSibling, TreeView_GetPrevVisible, TreeView_GetRoot, TreeView_GetSelection, TVM_GETITEMRECT


TVM_GETVISIBLECOUNT

The TVM_GETVISIBLECOUNT message obtains the number of items that are fully visible in the client window of a tree-view control. You can send this message explicitly, or by using the TreeView_GetVisibleCount macro.

TVM_GETVISIBLECOUNT

wParam = 0;

lParam = 0;

Return Values

Returns the number of items that are fully visible in the client window of the tree-view control.

Remarks

Note that the return value is the number of fully-visible items. If you can see all of 20 items, and part of one more item, the return value is 20, not 21.

See Also

TreeView_GetVisibleCount


TVM_HITTEST

The TVM_HITTEST message determines the location of the specified point relative to the client area of a tree-view control. You can send this message explicitly or by using the TreeView_HitTest macro.

TVM_HITTEST

wParam = 0;

lParam = (LPARAM) (LPTV_HITTESTINFO) lpht;

Parameters

lpht

Pointer to a TV_HITTESTINFO structure. When the message is sent, the pt member specifies the coordinates of the point to test. When the message returns, the hItem member is the handle to the item at the specified point or NULL if no item occupies the point. Also, when the message returns, the flags member is a hit-test value that indicates the location of the specified point. For a list of hit-test values, see the description of the TV_HITTESTINFO structure.

Return Values

Returns the handle to the tree-view item that occupies the specified point or NULL if no item occupies the point.

See Also

TreeView_HitTest, TV_HITTESTINFO


TVM_INSERTITEM

The TVM_INSERTITEM message inserts a new item in a tree-view control. You can send this message explicitly or by using the TreeView_InsertItem macro.

TVM_INSERTITEM

wParam = 0;

lParam = (LPARAM) (LPTV_INSERTSTRUCT) lpis;

Parameters

lpis

Pointer to a TV_INSERTSTRUCT structure that specifies the attributes of the tree-view item.

Return Values

Returns the handle to the new item if successful or NULL otherwise.

See Also

TreeView_InsertItem, TV_INSERTSTRUCT, TVN_ENDLABELEDIT


TVM_SELECTITEM

The TVM_SELECTITEM message selects the specified tree-view item, scrolls the item into view, or redraws the item in the style used to indicate the target of a drag-and-drop operation. You can send this message explicitly or by using the TreeView_Select, TreeView_SelectItem, or TreeView_SelectDropTarget macro.

TV_SELECTITEM

wParam = (WPARAM) flag;

lParam = (LPARAM) (HTREEITEM) hitem;

Parameters

flag

Action flag. This parameter can be one of the following values:

Value	Meaning
TVGN_CARET	Sets the selection to the given item.
TVGN_DROPHILITE	Redraws the given item in the style used to indicate the target of a drag and drop operation.
TVGN_FIRSTVISIBLE	Scrolls the tree view vertically so that the given item is the first visible item.
hitem

Handle to an item. If hitem is NULL, the selection is removed from the currently selected item, if any.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

If the TVGN_CARET value is specified, the parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages. Also, if the specified item is the child of a collapsed parent item, the parent’s list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Using the TreeView_SelectItem macro is equivalent to sending the TVM_SELECTITEM message with flag set to the TVGN_CARET value. Using the TreeView_SelectDropTarget macro is equivalent to sending the TVM_SELECTITEM message with flag set to the TVGN_DROPHILITE value. Using TreeView_SelectSetFirstVisible is equivalent to sending the TVM_SELECTITEM message with flag set to the TVGN_FIRSTVISIBLE value.

See Also

TreeView_Select, TreeView_SelectItem, or TreeView_SelectDropTarget, TVN_ITEMEXPANDED, TVN_ITEMEXPANDING, TVN_SELCHANGED, TVN_SELCHANGING


TVM_SETIMAGELIST

The TVM_SETIMAGELIST message sets the normal or state image list for a tree-view control and redraws the control using the new images. You can send this message explicitly or by using the TreeView_SetImageList macro.

TVM_SETIMAGELIST

wParam = (WPARAM) iImage;

lParam = (LPARAM) (HIMAGELIST) himl;

Parameters

iImage

Type of image list to set. For a list of possible values, see the description of the TVM_GETIMAGELIST message.

himl

Handle to the image list. If himl is NULL, all images are removed from the tree-view control.

Return Values

Returns the handle to the previous image list, if any, or NULL otherwise.

See Also

TreeView_SetImageList, TVM_GETIMAGELIST


TVM_SETINDENT

The TVM_SETINDENT message sets the width of indentation for a tree-view control and redraws the control to reflect the new width. You can send this message explicitly or by using the TreeView_SetIndent macro.

TVM_SETINDENT

wParam = (WPARAM) indent;

lParam = 0;

Parameters

indent

Width, in pixels, of the indentation. If this parameter is less than the system-defined minimum width, the new width is set to the system-defined minimum.

Return Values

No return value.

See Also

TreeView_SetIndent


TVM_SETITEM

The TVM_SETITEM sets some or all of a tree-view item’s attributes. You can send this message explicitly or by using the TreeView_SetItem macro.

TVM_SETITEM

wParam = 0;

lParam = (LPARAM) (const TV_ITEM FAR*) pitem;

Parameters

pitem

Pointer to a TV_ITEM structure that contains the new item attributes. The hItem member identifies the item, and the mask member specifies which attributes to set.

If mask specifies the TVIF_TEXT value, the pszText member is the pointer to a null-terminated string and the cchTextMax member is ignored.

If mask specifies the TVIF_STATE value, the stateMask member indicates which item states to change and the state member contains the values for those states.

Return Values

Returns zero if successful or −1 otherwise.

See Also

TreeView_SetItem, TV_ITEM


TVM_SORTCHILDREN

The TVM_SORTCHILDREN message sorts the child items of the specified parent item in a tree-view control. You can send this message explicitly or by using the TreeView_SortChildren macro.

TVM_SORTCHILDREN

wParam = 0;  // reserved for future use; must be zero

lParam = (LPARAM) (HTREEITEM) hitem;

Parameters

fRecurse

Reserved for future use. Must be zero.

hitem

Handle to the parent item whose child items are to be sorted.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TreeView_SortChildren


TVM_SORTCHILDRENCB

The TVM_SORTCHILDRENCB message sorts tree-view items using an application-defined callback function that compares the items. You can send this message explicitly or by using the TreeView_SortChildrenCB macro.

TVM_SORTCHILDRENCB

wParam = 0;  // reserved for future use; must be zero

lParam = (LPARAM) (LPTV_SORTCB) psort;

Parameters

fRecurse

Reserved for future use. Must be zero.

psort

Pointer to a TV_SORTCB structure. The lpfnCompare member is the pointer to the application-defined callback function, which is called during the sort operation each time the relative order of two list items needs to be compared. For more information about the callback function, see the description of TV_SORTCB.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TreeView_SortChildrenCB, TV_SORTCB


TVN_BEGINDRAG

The TVN_BEGINDRAG notification message notifies a tree-view control’s parent window that a drag-and-drop operation involving the left mouse button is being initiated. This notification message is sent in the form of a WM_NOTIFY message.

TVN_BEGINDRAG

pnmtv = (NM_TREEVIEW FAR *) lParam

Parameters

pnmtv

Pointer to an NM_TREEVIEW structure. The itemNew member is a TV_ITEM structure that contains valid information about the item being dragged in the hItem, state, and lParam members. The ptDrag member specifies the current screen coordinates of the mouse.

Return Values

No return value.

Remarks

A tree-view control that has the TVS_DISABLEDRAGDROP style does not send this notification message.

See Also

NM_TREEVIEW, TV_ITEM, WM_NOTIFY


TVN_BEGINLABELEDIT

The TVN_BEGINLABELEDIT notification message notifies a tree-view control’s parent window about the start of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

TVN_BEGINLABELEDIT

ptvdi = (TV_DISPINFO FAR *) lParam

Parameters

ptvdi

Pointer to a TV_DISPINFO structure. The item member is a TV_ITEM structure that contains valid information about the item being edited in the hItem, state, lParam, and pszText members.

Return Values

Returns TRUE to cancel label editing.

See Also

TV_DISPINFO, TV_ITEM, WM_NOTIFY


TVN_BEGINRDRAG

The TVN_BEGINRDRAG notification message notifies a tree-view control’s parent window about the initiation of a drag-and-drop operation involving the right mouse button. This notification message is sent in the form of a WM_NOTIFY message.

TVN_BEGINRDRAG

pnmtv = (NM_TREEVIEW FAR *) lParam

Parameters

pnmtv

Pointer to an NM_TREEVIEW structure. The itemNew member is a TV_ITEM structure that contains valid information in the hItem, state, and lParam members about the item to be dragged. The ptDrag member specifies the current screen coordinates of the mouse.

Return Values

No return value.

See Also

NM_TREEVIEW, TV_ITEM, WM_NOTIFY


TVN_DELETEITEM

The TVN_DELETEITEM notification message notifies a tree-view control’s parent window that an item has been deleted. This notification message is sent in the form of a WM_NOTIFY message.

TVN_DELETEITEM

pnmtv = (NM_TREEVIEW FAR *) lParam

Parameters

pnmtv

Pointer to an NM_TREEVIEW structure. The itemOld member is a TV_ITEM structure containing valid information about the item that was deleted in the hItem and lParam members.

Return Values

No return value.

See Also

NM_TREEVIEW, TV_ITEM, WM_NOTIFY


TVN_ENDLABELEDIT

The TVN_ENDLABELEDIT notification message notifies a tree-view control’s parent window about the end of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

TVN_ENDLABELEDIT

ptvdi = (TV_DISPINFO FAR *) lParam

Parameters

ptvdi

Pointer to a TV_DISPINFOstructure. The item member of this structure is a TV_ITEM structure whose hItem, lParam, and pszText members contain valid information about the item that was edited.

If label editing was canceled, the pszText member of the TV_ITEM structure is NULL; otherwise, pszText is a pointer to the edited text.

Return Values

If the pszText member is non-NULL, return TRUE to set the item’s label to the edited text. Return FALSE to reject the edited text and revert to the original label.

If the pszText member is NULL, the return value is ignored.

See Also

WM_NOTIFY, TV_DISPINFO, TV_ITEM


TVN_GETDISPINFO

The TVN_GETDISPINFO notification message requests that a tree-view control’s parent window provide information needed to display or sort an item. This notification message is sent in the form of a WM_NOTIFY message.

TVN_GETDISPINFO

ptvdi = (TV_DISPINFO FAR *) lParam

Parameters

ptvdi

Pointer to a TV_DISPINFO structure. The item member is a TV_ITEM structure whose mask, hItem, state, and lParam members specify the type of information required. You must fill the members of the structure with the appropriate information.

Return Values

No return value.

Remarks

See Also

TV_DISPINFO, TV_ITEM, WM_NOTIFY


TVN_ITEMEXPANDED

The TVN_ITEMEXPANDED notification message notifies a tree-view control’s parent window that a parent item’s list of child items has expanded or collapsed. This notification message is sent in the form of a WM_NOTIFY message.

TVN_ITEMEXPANDED

pnmtv = (NM_TREEVIEW FAR *) lParam

Parameters

pnmtv

Pointer to an NM_TREEVIEW structure. The itemNew member is a TV_ITEM structure that contains valid information about the parent item in the hItem, state, and lParam members. The action member indicates whether the list expanded or collapsed. For a list of possible values, see the description of the TVM_EXPAND message.

Return Values

No return value.

See Also

NM_TREEVIEW, TV_ITEM, TVM_EXPAND, WM_NOTIFY


TVN_ITEMEXPANDING

The TVN_ITEMEXPANDING notification message notifies a tree-view control’s parent window that a parent item’s list of child items is about to expand or collapse. This notification message is sent in the form of a WM_NOTIFY message.

TVN_ITEMEXPANDING

pnmtv = (NM_TREEVIEW FAR *) lParam

Parameters

pnmtv

Pointer to an NM_TREEVIEW structure. The itemNew member is a TV_ITEM structure that contains valid information about the parent item in the hItem, state, and lParam members. The action member indicates whether the list is to expand or collapse. For a list of possible values, see the description of the TVM_EXPAND message.

Return Values

Returns TRUE to prevent the list from expanding or collapsing.

See Also

NM_TREEVIEW, TV_ITEM, TVM_EXPAND, WM_NOTIFY


TVN_KEYDOWN

The TVN_KEYDOWN notification message notifies a tree-view control’s parent window that the user pressed a key and the tree-view control has the input focus. This notification message is sent in the form of a WM_NOTIFY message.

TVN_ITEMEXPANDING

ptvkd = (TV_KEYDOWN FAR *) lParam

Parameters

ptvkd

Pointer to a TV_KEYDOWN structure. The wVKey member specifies the virtual-key code.

Return Values

No return value.

See Also

TV_KEYDOWN, WM_NOTIFY


TVN_SELCHANGED

The TVN_SELCHANGED notification message notifies a tree-view control’s parent window that the selection has changed from one item to another. This notification message is sent in the form of a WM_NOTIFY message.

TVN_SELCHANGED

pnmtv = (NM_TREEVIEW FAR *) lParam

Parameters

pnmtv

Pointer to an NM_TREEVIEW structure. The itemOld and itemNew members of the NM_TREEVIEW structure are TV_ITEM structures that contain information about the previously selected item and the newly selected item. Only the mask, hItem, state, and lParam members of these structures are valid. The stateMask members of the TV_ITEM structures specified by itemOld and itemNew are undefined on input.

The action member of the NM_TREEVIEW structure indicates the type of action that caused the selection to change. It can be one of the following values:

Value	Meaning
TVC_BYKEYBOARD	By a key stroke
TVC_BYMOUSE	By a mouse click
TVC_UNKNOWN	Unknown
Return Values

No return value.

See Also

NM_TREEVIEW, WM_NOTIFY


TVN_SELCHANGING

The TVN_SELCHANGING notification message notifies a tree-view control’s parent window that the selection is about to change from one item to another. This notification message is sent in the form of a WM_NOTIFY message.

TVN_SELCHANGING

pnmtv = (NM_TREEVIEW FAR *) lParam

Parameters

pnmtv

Pointer to an NM_TREEVIEW structure. The itemOld and itemNew members contain valid information about the currently selected item and the newly selected item. The action member indicates whether a mouse or keyboard action is causing the selection to change. For a list of possible values, see the description of the TVN_SELCHANGED notification message.

Return Values

Returns TRUE to prevent the selection from changing.

See Also

NM_TREEVIEW, TVN_SELCHANGED, WM_NOTIFY


TVN_SETDISPINFO

The TVN_SETDISPINFO notification message notifies a tree-view control’s parent window that it must update the information it maintains about an item. This notification message is sent in the form of a WM_NOTIFY message.

TVN_SETDISPINFO

ptvdi = (TV_DISPINFO FAR *) lParam

Parameters

ptvdi

Pointer to a TV_DISPINFO structure. The item member is a TV_ITEM structure that contains valid information about the item in the hItem and lParam members.

Return Values

No return value.

Remarks

The system sends this notification message when the user has finished editing the label of an item whose text is set to LPSTR_TEXTCALLBACK. The notification gives the parent window the opportunity to store the new item text.

See Also

TV_DISPINFO, TV_ITEM, WM_NOTIFY


UDM_GETACCEL

The UDM_GETACCEL message retrieves acceleration information for an up-down control.

UDM_GETACCEL

wParam = (WPARAM) cAccels;

lParam = (LPARAM) (LPUDACCEL) paAccels;

Parameters

cAccels

Number of elements in the array specified by paAccels.

paAccels

Address of an array of UDACCEL structures that receives acceleration information.

Return Values

The return value is the number of accelerator structures retrieved.

See Also

UDACCEL


UDM_GETBASE

The UDM_GETBASE message retrieves the current radix base (that is, either base 10 or 16) for an up-down control.

UDM_GETBASE

wParam = 0;

lParam = 0;

Return Values

The return value is the current base value.


UDM_GETBUDDY

The UDM_GETBUDDY message retrieves the handle of the current buddy window.

UDM_GETBUDDY

wParam = 0;

lParam = 0;

Return Values

The return value is the handle of the current buddy window.


UDM_GETPOS

The UDM_GETPOS message retrieves the current position of an up-down control.

UDM_GETPOS

wParam = 0;

lParam = 0;

Return Values

The return value is the current position in the low-order word. If an error occurred, the high-order word is nonzero.

Remarks

When processing this message, the up-down control updates its current position based on the caption of the buddy window. The up-down control returns an error if there is no buddy window or if the caption specifies an invalid or out-of-range value.


UDM_GETRANGE

The UDM_GETRANGE message retrieves the minimum and maximum positions (range) for an up-down control.

UDM_GETRANGE

wParam = 0;

lParam = 0;

Return Values

The return value is a 32-bit value that contains the minimum and maximum positions. The low-order word is the maximum position for the control, and the high-order word is the minimum position.


UDM_SETACCEL

The UDM_SETACCEL message sets the acceleration for an up-down control.

UDM_SETACCEL

wParam = (WPARAM) nAccels;

lParam = (LPARAM) (LPUDACCEL) aAccels;

Parameters

nAccels

Number of UDACCEL structures specified by aAccels.

aAccels

Address of an array of UDACCEL structures that contains acceleration information. Elements should be sorted in ascending order based on the nSec member.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

UDACCEL


UDM_SETBASE

The UDM_SETBASE message sets the radix base for an up-down control. The base value determines whether the buddy window displays numbers in decimal or hexadecimal digits. Hexadecimal numbers are always unsigned, and decimal numbers are signed.

UDM_SETBASE

wParam = (WPARAM) nBase;

lParam = 0;

Parameters

nBase

New base value for the control. This parameter can be 10 for decimal or 16 for hexadecimal.

Return Values

The return value is the previous base value. If an invalid base is given, the return value is zero.


UDM_SETBUDDY

The UDM_SETBUDDY message sets the buddy window for an up-down control.

UDM_SETBUDDY

wParam = (WPARAM) (HWND) hwndBuddy;

lParam = 0;

Parameters

hwndBuddy

Handle of the new buddy window.

Return Values

The return value is the handle of the previous buddy window.


UDM_SETPOS

The UDM_SETPOS message sets the current position for an up-down control.

UDM_SETPOS

wParam = 0;

lParam = (LPARAM) MAKELONG((short) nPos, 0);

Parameters

nPos

New position for the up-down control. This parameter must be in the range specified by the upper and lower limits for the control.

Return Values

The return value is the previous position.


UDM_SETRANGE

The UDM_SETRANGE message sets the minimum and maximum positions (range) for an up-down control.

UDM_SETRANGE

wParam = 0;

lParam = (LPARAM) MAKELONG((short) nUpper, (short) nLower);

Parameters

nUpper and nLower

Maximum position and minimum position for the up-down control. Neither position can be greater than the UD_MAXVAL value or less than the UD_MINVAL value. In addition, the difference between the two positions cannot exceed UD_MAXVAL.

Return Values

No return value.

Remarks

The maximum position can be less than the minimum position. Clicking the up arrow moves the current position closer to the maximum position, and clicking the down arrow moves towards the minimum position.


UDN_DELTAPOS

The operating system sends the UDN_DELTAPOS notification message to the parent window of an up-down control when the position of the control is about to change. This happens when the user requests a change in the value by pressing the control’s up or down arrow. The UDN_DELTAPOS message is sent before the WM_VSCROLL or WM_HSCROLL message that actually changes the control’s position. This lets you examine, allow, modify, or disallow the change. The UDN_DELTAPOS message is sent in the form of a WM_NOTIFY message.

UDN_DELTAPOS

pnmud = (NM_UPDOWN FAR *) lParam

Parameters

pnmud

Pointer to an NM_UPDOWN structure that contains information about the position change.

The iPos member of this structure contains the current position of the control.

The iDelta member of the structure is a signed integer that contains the proposed change in position. If the user has clicked on the up button, this is a positive value. If the user has clicked on the down button, this is a negative value.

Return Values

Return TRUE in response to this message to prevent the change in the control’s position.

Return FALSE to allow the change in the control’s position.

See Also

NM_UPDOWN, WM_COMMAND, WM_VSCROLL


WM_ACTIVATE

The WM_ACTIVATE message is sent when a window is being activated or deactivated. This message is sent first to the window procedure of the top-level window being deactivated; it is then sent to the window procedure of the top-level window being activated.

WM_ACTIVATE

fActive = LOWORD(wParam);           // activation flag

fMinimized = (BOOL) HIWORD(wParam); // minimized flag

hwndPrevious = (HWND) lParam;       // window handle

Parameters

fActive

Value of the low-order word of wParam. Specifies whether the window is being activated or deactivated. This parameter can be one of the following values:

Value	Meaning
WA_ACTIVE	Activated by some method other than a mouse click (for example, by a call to the SetActiveWindow function or by use of the keyboard interface to select the window).
WA_CLICKACTIVE	Activated by a mouse click.
WA_INACTIVE	Deactivated.
fMinimized

Value of the high-order word of wParam. Specifies the minimized state of the window being activated or deactivated. A nonzero value indicates the window is minimized.

hwndPrevious

Value of lParam. Identifies the window being activated or deactivated, depending on the value of the fActive parameter. If the value of fActive is WA_INACTIVE, hwndPrevious is the handle of the window being activated. If the value of fActive is WA_ACTIVE or WA_CLICKACTIVE, hwndPrevious is the handle of the window being deactivated. This handle can be NULL.

Return Values

If an application processes this message, it should return zero.

Default Action

If the window is being activated and is not minimized, the DefWindowProc function sets the keyboard focus to the window.

Remarks

If the window is activated by a mouse click, it also receives a WM_MOUSEACTIVATE message.

See Also

DefWindowProc, SetActiveWindow, WM_MOUSEACTIVATE, WM_NCACTIVATE


WM_ACTIVATEAPP

The WM_ACTIVATEAPP message is sent when a window belonging to a different application than the active window is about to be activated. The message is sent to the application whose window is being activated and to the application whose window is being deactivated.

WM_ACTIVATEAPP

fActive = (BOOL) wParam;        // activation flag

dwThreadID = (DWORD) lParam:    // thread identifier

Parameters

fActive

Value of wParam. Specifies whether the window is being activated or deactivated. This parameter is TRUE if the window is being activated; it is FALSE if the window is being deactivated.

dwThreadID

Value of lParam. Specifies a thread identifier. If the fActive parameter is TRUE, dwThreadID is the identifier of the thread that owns the window being deactivated. If fActive is FALSE, dwThreadID is the identifier of the thread that owns the window being activated.

Return Values

If an application processes this message, it should return zero.

See Also

WM_ACTIVATE


WM_ASKCBFORMATNAME

The WM_ASKCBFORMATNAME message is sent to the clipboard owner by a clipboard viewer window to request the name of a CF_OWNERDISPLAY clipboard format.

WM_ASKCBFORMATNAME

cchName = (DWORD) wParam            // size of buffer

lpszFormatName = (LPTSTR) lParam    // buffer to receive format name

Parameters

cchName

Value of wParam. Specifies the size, in characters, of the buffer pointed to by the lpszFormatName parameter.

lpszFormatName

Value of lParam. Points to the buffer that is to receive the clipboard format name.

Return Values

If an application processes this message, it should return zero.

Remarks

In response to this message, the clipboard owner should copy the name of the owner-display format to the specified buffer, not exceeding the buffer size specified by the cchName parameter.

A clipboard viewer window sends this message to the clipboard owner to determine the name of the CF_OWNERDISPLAY format — for example, to initialize a menu listing available formats.


WM_CANCELJOURNAL

The WM_CANCELJOURNAL message is posted to an application when a user cancels the application’s journaling activities. The message is posted with a NULL window handle.

WM_CANCELJOURNAL

wParam = 0; // not used, must be zero

lParam = 0; // not used, must be zero

Parameters

This message has no parameters.

Return Values

This message does not return a value. It is meant to be processed from within an application’s main loop or a GetMessage hook procedure, not from a window procedure.

Remarks

Journal record and playback modes are modes imposed on the system that let an application sequentially record or play back user input. The system enters these modes when an application installs a JournalRecordProc or JournalPlaybackProc hook procedure. When the system is in either of these journaling modes, applications must take turns reading input from the input queue. If any one application stops reading input while the system is in a journaling mode, other applications are forced to wait.

To ensure a robust system, one that cannot be hung up by any one application, Windows NT automatically cancels any journalling activities when a user presses CTRL+ESC or CTRL+ALT+DEL. The system then unhooks any journaling hook procedures, and posts a WM_CANCELJOURNAL message, with a NULL window handle, to the application that set the journaling hook.

Since the WM_CANCELJOURNAL has a NULL window handle, it cannot be dispatched to a window procedure. There are two ways for an application to see a WM_CANCELJOURNAL message: If the application is running in its own main loop, it must catch the message between its call to GetMessage or PeekMessage and its call to DispatchMessage. If the application is not running in its own main loop, it must set a GetMsgProc hook procedure (via a call to SetWindowsHookEx specifying the WH_GETMESSAGE hook type) that watches for the message.

When an application sees a WM_CANCELJOURNAL message, it can assume two things: the user has intentionally cancelled the journal record or playback mode, and the system has already unhooked any journal record or playback hook procedures.

Note that the key combinations mentioned above (CTRL+ESC or CTRL+ALT+DEL) cause the system to cancel journaling. If any one application is hung, they give the user a means of recovery. The VK_CANCEL virtual keycode (usually implemented as the CTRL+BREAK key combination) is what an application that is in journal record mode should watch for as a signal that the user wishes to cancel the journaling activity. The difference is that watching for VK_CANCEL is a suggested behavior for journaling applications, whereas CTRL+ESC or CTRL+ALT+DEL cause the system to cancel journalling regardless of a journalling application’s behavior.

See Also

DispatchMessage, GetMessage, JournalPlaybackProc, JournalRecordProc, GetMsgProc, PeekMessage, SetWindowsHookEx


WM_CANCELMODE

The WM_CANCELMODE message is sent to the focus window when a dialog box or message box is displayed; this enables the focus window to cancel modes, such as mouse capture.

WM_CANCELMODE

Parameters

This message has no parameters.

Return Values

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function cancels internal processing of standard scroll bar input, cancels internal menu processing, and releases the mouse capture.

See Also

DefWindowProc, ReleaseCapture


WM_CAPTURECHANGED

The WM_CAPTURECHANGED message is sent to the window that is losing the mouse capture.

WM_CAPTURECHANGED

hwndNewCapture = (HWND) lParam;    // handle of window to gain mouse capture

Parameters

hwndNewCapture

Value of lParam. Identifies the window that is gaining the mouse capture.

Return Values

An application should return zero if it processes this message.

Remarks

A window receives this message even if it calls ReleaseCapture itself. An application should not attempt to set the mouse capture in response to this message.

When it receives this message, a window should redraw itself, if necessary, to reflect the new mouse-capture state.

See Also

ReleaseCapture, SetCapture


WM_CHANGECBCHAIN

The WM_CHANGECBCHAIN message is sent to the first window in the clipboard viewer chain when a window is being removed from the chain.

WM_CHANGECBCHAIN

hwndRemove = (HWND) wParam;     // handle of window being removed

hwndNext = (HWND) lParam;       // handle of next window in chain

Parameters

hwndRemove

Value of wParam. Identifies the window being removed from the clipboard viewer chain.

hwndNext

Value of lParam. Identifies the next window in the chain following the window being removed. This parameter is NULL if the window being removed is the last window in the chain.

Return Values

If an application processes this message, it should return zero.

Remarks

Each clipboard viewer window saves the handle of the next window in the clipboard viewer chain. Initially, this handle is the return value of the SetClipboardViewer function.

When a clipboard viewer window receives the WM_CHANGECBCHAIN message, it should call the SendMessage function to pass the message to the next window in the chain, unless the next window is the window being removed. In this case, the clipboard viewer should save the handle specified by hwndNext as the next window in the chain.

See Also

SendMessage, SetClipboardViewer


WM_CHAR

The WM_CHAR message is posted to the window with the keyboard focus when a WM_KEYDOWN message is translated by the TranslateMessage function. WM_CHAR contains the character code of the key that was pressed.

WM_CHAR

chCharCode = (TCHAR) wParam;    // character code

lKeyData = lParam;              // key data

Parameters

chCharCode

Value of wParam. Specifies the character code of the key.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table:

Value	Description
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30	Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31	Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.
Return Values

An application should return zero if it processes this message.

Remarks

Because there is not necessarily a one-to-one correspondence between keys pressed and character messages generated, the information in the high-order word of the lKeyData parameter is generally not useful to applications. The information in the high-order word applies only to the most recent WM_KEYDOWN message that precedes the posting of the WM_CHAR message.

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and the right CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Some other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

TranslateMessage, WM_KEYDOWN


WM_CHARTOITEM

The WM_CHARTOITEM message is sent by a list box with the LBS_WANTKEYBOARDINPUT style to its owner in response to a WM_CHAR message.

WM_CHARTOITEM

nKey = LOWORD(wParam);          // key value

nCaretPos = HIWORD(wParam);     // caret position

hwndListBox = (HWND) lParam;    // handle of list box

Parameters

nKey

Value of the low-order word of wParam. Specifies the value of the key the user pressed.

nCaretPos

Value of the high-order word of wParam. Specifies the current position of the caret.

hwndListBox

Value of lParam. Identifies the list box.

Return Values

The return value specifies the action that the application performed in response to the message. A return value of −1 or −2 indicates that the application handled all aspects of selecting the item and requires no further action by the list box. A return value of 0 or greater specifies the zero-based index of an item in the list box and indicates that the list box should perform the default action for the keystroke on the given item.

Default Action

The DefWindowProc function returns −1.

Remarks

Only owner-drawn list boxes that do not have the LBS_HASSTRINGS style can receive this message.

See Also

DefWindowProc, WM_CHAR, WM_VKEYTOITEM


WM_CHILDACTIVATE

The WM_CHILDACTIVATE message is sent to a multiple document interface (MDI) child window when the user clicks the window’s title bar or when the window is activated, moved, or sized.

WM_CHILDACTIVATE

Parameters

This message has no parameters.

Return Values

If an application processes this message, it should return zero.

See Also

MoveWindow, SetWindowPos


WM_CHOOSEFONT_GETLOGFONT

Send the WM_CHOOSEFONT_GETLOGFONT message to a Font dialog box to retrieve information about the user’s current font selections.

WM_CHOOSEFONT_GETLOGFONT

wParam = 0;                // not used, must be zero

lParam = (LPLOGFONT) lplf; // address of struct. with font data

Parameters

lplf

Pointer to a LOGFONT structure that receives information about the user’s current font selections.

Return Values

This message does not return a value.

Remarks

The ChooseFont function creates a Font dialog box. When the user closes the Font dialog box, the ChooseFont function returns information about the user’s font selections in the CHOOSEFONT structure. The lpLogFont member of the CHOOSEFONT structure is a pointer to a LOGFONT structure.

Use the WM_CHOOSEFONT_GETLOGFONT message to get information about the user’s current font selections while the Font dialog box is open. For example, if you enable the Apply button in the Font dialog box, send the message to get the font information to apply to the current text selection.

Typically, you enable a CFHookProc hook procedure to process WM_COMMAND messages for the Apply button. When the user clicks the Apply button, the hook procedure sends the WM_CHOOSEFONT_GETLOGFONT message to the dialog box.

See Also

CFHookProc, ChooseFont, CHOOSEFONT, LOGFONT, WM_COMMAND


WM_CHOOSEFONT_SETFLAGS

Send the WM_CHOOSEFONT_SETFLAGS message to a Font dialog box to set the display options for the dialog box.

WM_CHOOSEFONT_SETFLAGS

wParam = 0;                   // not used, must be zero

lParam = (LPCHOOSEFONT) lpcf; // address of struct. with flags data

Parameters

lpcf

Pointer to a CHOOSEFONT structure that contains new settings in the Flags member.

Return Values

No return value.

Remarks

The ChooseFont function creates a Font dialog box and uses a CHOOSEFONT structure to specify the initial values for the Flags member. Use the WM_CHOOSEFONT_SETFLAGS message to specify different values for the Flags member while the Font dialog box is open.

Typically, you should send the WM_CHOOSEFONT_SETFLAGS message from a CFHookProc hook procedure.

See Also

CFHookProc, ChooseFont, CHOOSEFONT


WM_CHOOSEFONT_SETLOGFONT

Send the WM_CHOOSEFONT_SETLOGFONT message to a Font dialog box to set the current logical font information.

WM_CHOOSEFONT_SETLOGFONT

wParam = 0;                // not used, must be zero

lParam = (LPLOGFONT) lplf; // address of struct. with font data

Parameters

lplf

Pointer to a LOGFONT structure that contains information about the current logical font.

Return Values

No return value.

Remarks

When you call the ChooseFont function to create a Font dialog box, you can use the lpLogFont member of the CHOOSEFONT structure to specify a LOGFONT structure containing initial values for the dialog box. Use the WM_CHOOSEFONT_SETLOGFONT message to specify a LOGFONT structure with different values while the Font dialog box is open.

Typically, you would send the WM_CHOOSEFONT_SETLOGFONT message from a CFHookProc hook procedure. The hook procedure can also send the WM_CHOOSEFONT_GETLOGFONT and WM_CHOOSEFONT_SETFLAGS messages.

See Also

CFHookProc, ChooseFont, CHOOSEFONT, LOGFONT, WM_CHOOSEFONT_GETLOGFONT, WM_CHOOSEFONT_SETFLAGS


WM_CLEAR

An application sends a WM_CLEAR message to an edit control or combo box to delete (clear) the current selection, if any, from the edit control.

WM_CLEAR

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

This message does not return a value.

Remarks

The deletion performed by the WM_CLEAR message can be undone by sending the edit control an EM_UNDO message.

To delete the current selection and place the deleted content on the clipboard, use the WM_CUT message.

When sent to a combo box, the WM_CLEAR message is handled by its edit control. This message has no effect when sent to a combo box with the CBS_DROPDOWNLIST style.

See Also

EM_UNDO, WM_COPY, WM_CUT, WM_PASTE


WM_CLOSE

The WM_CLOSE message is sent as a signal that a window or an application should terminate.

WM_CLOSE

Parameters

This message has no parameters.

Return Values

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function calls the DestroyWindow function to destroy the window.

Remarks

An application can prompt the user for confirmation, prior to destroying a window, by processing the WM_CLOSE message and calling the DestroyWindow function only if the user confirms the choice.

See Also

DefWindowProc, DestroyWindow


WM_COMMAND

The WM_COMMAND message is sent when the user selects a command item from a menu, when a control sends a notification message to its parent window, or when an accelerator keystroke is translated.

WM_COMMAND

wNotifyCode = HIWORD(wParam); // notification code

wID = LOWORD(wParam);         // item, control, or accelerator identifier

hwndCtl = (HWND) lParam;      // handle of control

Parameters

wNotifyCode

Value of the high-order word of wParam. Specifies the notification code if the message is from a control. If the message is from an accelerator, this parameter is 1. If the message is from a menu, this parameter is 0.

wID

Value of the low-order word of wParam. Specifies the identifier of the menu item, control, or accelerator.

hwndCtl

Value of lParam. Identifies the control sending the message if the message is from a control. Otherwise, this parameter is NULL.

Return Values

If an application processes this message, it should return zero.

Remarks

Accelerator keystrokes that select items from the window menu are translated into WM_SYSCOMMAND messages.

If an accelerator keystroke occurs that corresponds to a menu item when the window that owns the menu is minimized, no WM_COMMAND message is sent. However, if an accelerator keystroke occurs that does not match any of the items in the window’s menu or in the window menu, a WM_COMMAND message is sent, even if the window is minimized.

If an application enables a menu separator, the system sends a WM_COMMAND message with the low-word of the wParam parameter set to zero when the user selects the separator.

See Also

WM_SYSCOMMAND


WM_COMPACTING

The WM_COMPACTING message is sent to all top-level windows when Windows detects more than 12.5 percent of system time over a 30- to 60-second interval is being spent compacting memory. This indicates that system memory is low.

WM_COMPACTING

wCompactRatio = wParam; // compacting ratio

Parameters

wCompactRatio

Value of wParam. Specifies the ratio of central processing unit (CPU) time currently spent by Windows compacting memory to CPU time currently spent by Windows performing other operations. For example, 0x8000 represents 50 percent of CPU time spent compacting memory.

Return Values

If an application processes this message, it should return zero.

Remarks

When an application receives this message, it should free as much memory as possible, taking into account the current level of activity of the application and the total number of applications running with Windows.


WM_COMPAREITEM

Windows sends the WM_COMPAREITEM message to determine the relative position of a new item in the sorted list of an owner-drawn combo box or list box. Whenever the application adds a new item, Windows sends this message to the owner of a combo box or list box created with the CBS_SORT or LBS_SORT style.

WM_COMPAREITEM

idCtl = wParam;                       // control identifier

lpcis = (LPCOMPAREITEMSTRUCT) lParam; // structure with items

Parameters

idCtl

Value of wParam. Specifies the identifier of the control that sent the WM_COMPAREITEM message.

lpcis

Value of lParam. Points to a COMPAREITEMSTRUCT structure that contains the identifiers and application-supplied data for two items in the combo or list box.

Return Values

The return value indicates the relative position of the two items. It may be any of the following:

Value	Meaning
−1	Item 1 precedes item 2 in the sorted order.
0	Items 1 and 2 are equivalent in the sorted order.
1	Item 1 follows item 2 in the sorted order.
Remarks

When the owner of an owner-drawn combo box or list box receives this message, the owner returns a value indicating which of the items specified by the COMPAREITEMSTRUCT structure will appear before the other. Typically, Windows sends this message several times until it determines the exact position for the new item.

See Also

COMPAREITEMSTRUCT


WM_CONTEXTMENU

The WM_CONTEXTMENU message notifies a window that the user clicked the right mouse button (right clicked) in the window.

hwnd = (HWND) wParam;

xPos = LOWORD(lParam);

yPos = HIWORD(lParam);

Parameters

hwnd

Handle to the window in which the user right clicked the mouse. This can be a child window of the window receiving the message. For more information about processing this message, see the Remarks section.

xPos

Horizontal position of the cursor, in screen coordinates, at the time of the mouse click.

yPos

Vertical position of the cursor, in screen coordinates, at the time of the mouse click.

Return Values

No return value.

Remarks

A window can process this message by displaying a shortcut menu using the TrackPopupMenu or TrackPopupMenuEx function.

If a window does not display a shortcut menu it should pass this message to the DefWindowProc function. If a window is a child window, DefWindowProc sends the message to the parent. Otherwise, DefWindowProc displays a default shortcut menu if the specified position is in the window’s caption.

DefWindowProc generates the WM_CONTEXTMENU message when it processes the WM_RBUTTONUP or WM_NCRBUTTONUP message.

See Also

DefWindowProc, TrackPopupMenu, TrackPopupMenuEx, WM_NCRBUTTONUP, WM_RBUTTONUP


WM_COPY

An application sends the WM_COPY message to an edit control or combo box to copy the current selection to the clipboard in CF_TEXT format.

WM_COPY

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

This message does not return a value.

Remarks

When sent to a combo box, the WM_COPY message is handled by its edit control. This message has no effect when sent to a combo box with the CBS_DROPDOWNLIST style.

See Also

WM_CLEAR, WM_CUT, WM_PASTE


WM_COPYDATA

The WM_COPYDATA message is sent when an application passes data to another application.

WM_COPYDATA

wParam = (WPARAM) (HWND) hwnd;            // handle of sending window

lParam = (LPARAM) (PCOPYDATASTRUCT) pcds; // pointer to structure with data

Parameters

hwnd

Identifies the window passing the data.

pcds

Points to a COPYDATASTRUCT structure that contains the data to be passed.

Return Values

If the receiving application processes this message, it should return TRUE; otherwise, it should return FALSE.

Remarks

An application must use the SendMessage function to send this message, not the PostMessage function.

The data being passed must not contain pointers or other references to objects not accessible to the application receiving the data.

While this message is being sent, the referenced data must not be changed by another thread of the sending process.

The receiving application should consider the data read-only. The pcds parameter is valid only during the processing of the message. The receiving application should not free the memory referenced by pcds. If the receiving application must access the data after SendMessage returns, it must copy the data into a local buffer.

See Also

PostMessage, SendMessage, COPYDATASTRUCT


WM_CPL_LAUNCH

An application sends the WM_CPL_LAUNCH message to Windows Control Panel to request that a Control Panel application be started.

WM_CPL_LAUNCH

hwnd = (HWND) wParam;          // handle of sending window

lpszAppName = (LPSTR) lParam;  // application-name string

Parameters

hwnd

Value of wParam. Specifies the handle of the window sending the message. The WM_CPL_LAUNCHED message is sent to this window.

lpszAppName

Value of lParam. Specifies a far pointer to a string containing the name of the Control Panel application to open.

Return Values

If the application starts, the return value is TRUE; otherwise, it is FALSE.

See Also

WM_CPL_LAUNCHED


WM_CPL_LAUNCHED

The WM_CPL_LAUNCHED message is sent when a Control Panel application, started by the WM_CPL_LAUNCH message, has closed. The WM_CPL_LAUNCHED message is sent to the window identified by the wParam parameter of the WM_CPL_LAUNCH message that started the application.

WM_CPL_LAUNCHED

fAppStarted = (BOOL) wParam;

Parameters

fAppStarted

Value of wParam. Specifies whether the application was started. If the application was started, this parameter is TRUE; otherwise, it is FALSE.

Return Values

The value returned by the application is ignored for this message.

See Also

WM_CPL_LAUNCH


WM_CREATE

The WM_CREATE message is sent when an application requests that a window be created by calling the CreateWindowEx or CreateWindow function. The window procedure of the new window receives this message after the window is created, but before the window becomes visible. The message is sent before the CreateWindowEx or CreateWindow function returns.

WM_CREATE

lpcs = (LPCREATESTRUCT) lParam; // structure with creation data

Parameters

lParam

Value of lParam. Points to a CREATESTRUCT structure that contains information about the window being created. The members of CREATESTRUCT are identical to the parameters of the CreateWindowEx function.

Return Values

If an application processes this message, it should return 0 to continue creation of the window. If the application returns −1, the window is destroyed and the CreateWindowEx or CreateWindow function returns a NULL handle.

See Also

CreateWindow, CreateWindowEx, CREATESTRUCT, WM_NCCREATE


WM_CTLCOLORBTN

The WM_CTLCOLORBTN message is sent to the parent window of a button when the button is about to be drawn. By responding to this message, the parent window can set a button’s text and background colors.

WM_CTLCOLORBTN

hdcButton = (HDC) wParam;   // handle of button display context

hwndButton = (HWND) lParam; // handle of button

Parameters

hdcButton

Value of wParam. Identifies the display context for the button.

hwndButton

Value of lParam. Identifies the button.

Return Values

If an application processes this message, it must return the handle of a brush. Windows uses the brush to paint the background of the button.

Default Action

The DefWindowProc function selects the default system colors for the button.

Remarks

The WM_CTLCOLORBTN message is never sent between threads. It is sent only within one thread.

The text color of a check box or radio button applies to the box or button, its check mark, and the text. The focus rectangle for these buttons remains the system default color (typically black). The text color of a group box applies to the text but not to the line that defines the box. The text color of a push button applies only to its focus rectangle; it does not affect the color of the text.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC


WM_CTLCOLORDLG

The WM_CTLCOLORDLG message is sent to a dialog box before Windows draws the dialog box. By responding to this message, the dialog box can set its text and background colors by using the given display device context handle.

WM_CTLCOLORDLG

hdcDlg = (HDC) wParam;   // handle of dialog box display context

hwndDlg = (HWND) lParam; // handle of dialog box

Parameters

hdcDlg

Value of wParam. Identifies the device context for the dialog box.

hwndDlg

Value of lParam. Identifies the dialog box.

Return Values

If an application processes this message, it must return the handle of a brush. Windows uses the brush to paint the background of the dialog box.

Default Action

The DefWindowProc function selects the default system colors for the dialog box.

Remarks

The WM_CTLCOLORDLG message is never sent between threads. It is sent only within one thread.

Note that the WM_CTLCOLORDLG message is sent to the dialog box itself; all of the other WM_CTLCOLOR* messages are sent to the owner of the control.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC


WM_CTLCOLOREDIT

The WM_CTLCOLOREDIT message is sent to the parent window of an edit control when the control is about to be drawn. By responding to this message, the parent window can use the given device context handle to set the text and background colors of the edit control.

WM_CTLCOLOREDIT

hdcEdit = (HDC) wParam;   // handle of display context

hwndEdit = (HWND) lParam; // handle of static control

Parameters

hdcEdit

Value of wParam. Identifies the device context for the edit control window.

hwndEdit

Value of lParam. Identifies the edit control.

Return Values

If an application processes this message, it must return the handle of a brush. Windows uses the brush to paint the background of the edit control.

Default Action

The DefWindowProc function selects the default system colors for the edit control.

Remarks

The WM_CTLCOLOREDIT message is never sent between threads, it is only sent within the same thread.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC


WM_CTLCOLORLISTBOX

The WM_CTLCOLORLISTBOX message is sent to the parent window of a list box before Windows draws the list box. By responding to this message, the parent window can set the text and background colors of the list box by using the given display device context handle.

WM_CTLCOLORLISTBOX

hdcLB = (HDC) wParam;   // handle of list box display context

hwndLB = (HWND) lParam; // handle of list box

Parameters

hdcLB

Value of wParam. Identifies the device context for the list box.

hwndLB

Value of lParam. Identifies the list box.

Return Values

If an application processes this message, it must return the handle of a brush. Windows uses the brush to paint the background of the list box.

Default Action

The DefWindowProc function selects the default system colors for the list box.

Remarks

The WM_CTLCOLORLISTBOX message is never sent between threads. It is sent only within one thread.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC


WM_CTLCOLORMSGBOX

The WM_CTLCOLORMSGBOX message is sent to the owner window of a message box before Windows draws the message box. By responding to this message, the owner window can set the text and background colors of the message box by using the given display device context handle.

WM_CTLCOLORMSGBOX

hdcMB = (HDC) wParam;   // handle of message box display context

hwndMB = (HWND) lParam; // handle of message box

Parameters

hdcMB

Value of wParam. Identifies the device context for the message box.

hwndMB

Value of lParam. Identifies the message box.

Return Values

If an application processes this message, it must return the handle of a brush. Windows uses the brush to paint the background of the message box.

Default Action

The DefWindowProc function selects the default system colors for the message box.

Remarks

The WM_CTLCOLORMSGBOX message is never sent between threads. It is sent only within one thread.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC


WM_CTLCOLORSCROLLBAR

The WM_CTLCOLORSCROLLBAR message is sent to the parent window of a scroll bar control when the control is about to be drawn. By responding to this message, the parent window can use the given display context handle to set the background color of the scroll bar control.

WM_CTLCOLORSCROLLBAR

hdcSB  = (HDC) wParam;   // handle of scroll-bar display context

hwndSB = (HWND) lParam;  // handle of scroll bar

Parameters

hdcSB

Value of wParam. Identifies the device context for the scroll bar control.

hwndSB

Value of lParam. Identifies the scroll bar.

Return Values

If an application processes this message, it must return the handle of a brush. Windows uses the brush to paint the background of the scroll bar control.

Default Action

The DefWindowProc function selects the default system colors for the scroll bar control.

Remarks

The WM_CTLCOLORSCROLLBAR message is never sent between threads; it is only sent within the same thread.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSTATIC


WM_CTLCOLORSTATIC

The WM_CTLCOLORSTATIC message is sent to the parent window of a static control when the control is about to be drawn. By responding to this message, the parent window can use the given device context handle to set the text and background colors of the static control.

WM_CTLCOLORSTATIC

hdcStatic = (HDC) wParam;   // handle of display context

hwndStatic = (HWND) lParam; // handle of static control

Parameters

hdcStatic

Value of wParam. Identifies the device context for the static control window.

hwndStatic

Value of lParam. Identifies the static control.

Return Values

If an application processes this message, the return value is the handle of a brush that Windows uses to paint the background of the static control.

Default Action

The DefWindowProc function selects the default system colors for the static control.

Remarks

The WM_CTLCOLORSTATIC message is never sent between threads; it is sent only within the same thread.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR


WM_CUT

An application sends a WM_CUT message to an edit control or combo box to delete (cut) the current selection, if any, in the edit control and copy the deleted text to the clipboard in CF_TEXT format.

WM_CUT

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

This message does not return a value.

Remarks

The deletion performed by the WM_CUT message can be undone by sending the edit control an EM_UNDO message.

To delete the current selection without placing the deleted text on the clipboard, use the WM_CLEAR message.

When sent to a combo box, the WM_CUT message is handled by its edit control. This message has no effect when sent to a combo box with the CBS_DROPDOWNLIST style.

See Also

EM_UNDO, WM_CLEAR, WM_COPY, WM_PASTE


WM_DDE_ACK

The WM_DDE_ACK message notifies a DDE application of the receipt and processing of a WM_DDE_POKE, WM_DDE_EXECUTE, WM_DDE_DATA, WM_DDE_ADVISE, WM_DDE_UNADVISE, or WM_DDE_INITIATE message, and in some cases, of a WM_DDE_REQUEST message.

WM_DDE_ACK

// Response to WM_DDE_INITIATE

wParam = (WPARAM) hwnd;          // handle of posting application

lParam = MAKELPARAM(aApp, aTopic) // application and topic atoms

// Response to WM_DDE_EXECUTE

wParam = (WPARAM) hwnd;         // handle of posting application

lParam = (LPARAM) lPackedVal;   // packed status flags and data handle

// Response to all other messages

wParam = (WPARAM) hwnd;         // handle of posting application

lParam = (LPARAM) lPackedVal;   // packed status flags and item

Parameters

When responding to WM_DDE_INITIATE:

hwnd

Value of wParam. Identifies the server window posting the message.

aApp

Value of the low-order word of lParam. Contains an atom that identifies the replying application.

aTopic

Value of the high-order word of lParam. Contains an atom that identifies the topic for which a conversation is being established.

When responding to WM_DDE_EXECUTE:

hwnd

Value of wParam. Identifies the server window posting the message.

lPackedVal

Value of lParam. The component parameters that are packed into lPackedVal are extracted by calling the UnpackDDElParam function. The low-order word is wStatus. The high-order word is the same hCommands that was received in the WM_DDE_EXECUTE message.

Parameter	Description
wStatus	Specifies a DDEACK structure containing a series of flags that indicate the status of the response.
hCommands	Identifies a global memory object that contains the command string.
When replying to all other messages:

hwnd

Value of wParam. Identifies the client or server window posting the message.

lPackedVal

Value of lParam. The component parameters that are packed into lPackedVal are extracted by calling the UnpackDDElParam function. The low-order word is wStatus. The high-order word is aItem.

Parameter	Description
wStatus	Specifies a DDEACK structure containing a series of flags that indicate the status of the response.
aItem	Contains a global atom that identifies the name of the data item for which the response is sent.
Remarks

Posting

Except in response to the WM_DDE_INITIATE message, the application posts the WM_DDE_ACK message by calling the PostMessage function, not by calling the SendMessage function. When responding to WM_DDE_INITIATE, the application sends the WM_DDE_ACK message by calling SendMessage. In this case, neither the application-name atom nor the topic-name atom should be NULL (even if the WM_DDE_INITIATE message specified NULL atoms).

When acknowledging any message with an accompanying aItem atom, the application posting WM_DDE_ACK can either reuse the aItem atom that accompanied the original message, or it can delete it and create a new one.

When acknowledging WM_DDE_EXECUTE, the application that posts WM_DDE_ACK should reuse the global memory object identified in the original WM_DDE_EXECUTE message.

All posted WM_DDE_ACK messages must create or reuse the lPackedVal parameter by calling the PackDDElParam function or the ReuseDDElParam function.

If an application has initiated the termination of a conversation by posting WM_DDE_TERMINATE and is awaiting confirmation, the waiting application should not acknowledge (positively or negatively) any subsequent messages sent by the other application. The waiting application should delete any atoms or shared memory objects received in these intervening messages. Memory objects should not be freed if the fRelease flag is set to FALSE in WM_DDE_POKE, and WM_DDE_DATA messages.

Receiving

The application that receives a WM_DDE_ACK message should delete all atoms accompanying the message. If the application receives a WM_DDE_ACK in response to a message with an accompanying hData object, and the object was sent with the fRelease flags set to FALSE, the application is responsible for deleteing the hData object.

If the application receives a negative WM_DDE_ACK message posted in reply to a WM_DDE_ADVISE message, the application should delete the global memory object posted with the original WM_DDE_ADVISE message (in hOptions). If the application receives a negative WM_DDE_ACK message posted in reply to a WM_DDE_DATA, WM_DDE_POKE, or WM_DDE_EXECUTE message, the application should delete the global memory object posted with the original WM_DDE_DATA, WM_DDE_POKE, or WM_DDE_EXECUTE message (in hCommands).

The application that receives a posted WM_DDE_ACK message must free the lPackedVal parameter by using the FreeDDElParam function.

See Also

DDEACK, FreeDDElParam, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_ADVISE, WM_DDE_DATA, WM_DDE_EXECUTE, WM_DDE_INITIATE, WM_DDE_POKE, WM_DDE_REQUEST, WM_DDE_TERMINATE, WM_DDE_UNADVISE


WM_DDE_ADVISE

A DDE client application posts the WM_DDE_ADVISE message to a DDE server application to request the server to supply an update for a data item whenever the item changes.

WM_DDE_ADVISE

wParam = (WPARAM) hwnd;        // handle of posting application

lParam = (LPARAM) lPackedVal;  // packed DDEADVISE and item atom

Parameters

hwnd

Value of wParam. Identifies the client window posting the message.

lPackedVal

Value of lParam. The component parameters packed into lPackedVal are extracted by calling the UnpackDDElParam function. The low-order word is hOptions. The high-order word is aItem.

Parameter	Description
hOptions	Identifies a global memory object containing a DDEADVISE structure that specifies how the data is to be sent.
aItem	Contains an atom that identifies the requested data item.
Remarks

If a client application supports more than one clipboard format for a single topic and item, it can post multiple WM_DDE_ADVISE messages for the topic and item, specifying a different clipboard format with each message. Note that a server can support multiple formats only for hot data links, not warm data links.

Posting

The client application posts the WM_DDE_ADVISE message by calling the PostMessage function, not the SendMessage function.

The client application allocates hOptions by calling the GlobalAlloc function with the GMEM_DDESHARE option. It allocates aItem by calling the GlobalAddAtom function.

The client application must create or reuse the WM_DDE_ADVISE lPackedVal parameter by calling the PackDDElParam function or the ReuseDDElParam function with hOptions supplied as the low-order word and aItem supplied as the high-order word.

If the receiving (server) application responds with a negative WM_DDE_ACK message, the posting (client) application must delete the hOptions object.

The fRelease flag is not used in WM_DDE_ADVISE messages, but their data-freeing behavior is similar to that of WM_DDE_DATA and WM_DDE_POKE messages where fRelease is TRUE.

Receiving

The server application posts the WM_DDE_ACK message to respond positively or negatively. When posting WM_DDE_ACK, the application can reuse the aItem atom or delete it and create a new one. If the WM_DDE_ACK message is positive, the application should delete the hOptions object; otherwise, the application should not delete the object.

The server must create or reuse the WM_DDE_ACK lPackedVal parameter by calling the PackDDElParam function or the ReuseDDElParam function with wStatus supplied as the low-order word and aItem supplied as the high-order word.

See Also

DDEADVISE, FreeDDElParam, GlobalAddAtom, GlobalAlloc, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_ACK, WM_DDE_DATA, WM_DDE_POKE, WM_DDE_REQUEST


WM_DDE_DATA

A DDE server application posts a WM_DDE_DATA message to a DDE client application to pass a data item to the client or to notify the client of the availability of a data item.

WM_DDE_DATA

wParam = (WPARAM) hwnd;         // handle of posting application

lParam = (LPARAM) lPackedVal;   // packed DDEDATA and item atom

Parameters

hwnd

Value of wParam. Identifies the server window posting the message.

lPackedVal

Value of lParam. The component parameters that are packed into lPackedVal are extracted by calling the UnpackDDElParam function. The low-order word is hData or NULL. The high-order word is aItem.

Parameter	Description
hData	Identifies a global memory object containing a DDEDATA structure with the data and additional information. The handle should be set to NULL if the server is notifying the client that the data-item value has changed during a warm data link. A warm link is established by the client sending a WM_DDE_ADVISE message with the fDeferUpd bit set.
aItem	Contains an atom that identifies the data item for which the data or notification is sent.
Remarks

Posting

The server application posts the WM_DDE_DATA message by calling the PostMessage function, not the SendMessage function.

The server application allocates hData by calling the GlobalAlloc function with the GMEM_DDESHARE option. It allocates aItem by calling the GlobalAddAtom function.

The server must create or reuse the WM_DDE_DATA lPackedVal parameter by calling the PackDDElParam function or the ReuseDDElParam function with hData supplied as the low-order word and aItem supplied as the high-order word.

If the receiving (client) application responds with a negative WM_DDE_ACK message, the posting (server) application must delete the hData object; otherwise, the client must delete the hData object after extracting its contents by calling the UnpackDDElParam function.

If the server application sets the fRelease member of the DDEDATA structure to FALSE, the server is responsible for deleting hData upon receiving either a positive or negative acknowledgement.

The server application should not set both the fAckReq and fRelease members of the DDEDATA structure to FALSE. If both members are set to FALSE, it is impossible for the server to determine when to delete hData.

Receiving

If fAckReq is TRUE, the client application should post the WM_DDE_ACK message to respond positively or negatively. When posting WM_DDE_ACK, the client can either reuse the aItem atom, or it can delete it and create a new one.

The client must create or reuse the WM_DDE_ACK lPackedVal parameter by calling the PackDDElParam function or the ReuseDDElParam function with wStatus supplied as the low-order word and aItem supplied as the high-order word.

If fAckReq is FALSE, the client application should delete the aItem atom.

If the posting (server) application specified hData as NULL, the receiving (client) application can request the server to send the data by posting a WM_DDE_REQUEST message.

After processing a WM_DDE_DATA message in which hData is not NULL, the client should free hData, unless one of the following conditions is true:

•	The fRelease member is FALSE.

•	The fRelease member is TRUE, but the client application responds with a negative WM_DDE_ACK message.

See Also

DDEDATA, FreeDDElParam, GlobalAddAtom, GlobalAlloc, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_ACK, WM_DDE_ADVISE, WM_DDE_POKE, WM_DDE_REQUEST


WM_DDE_EXECUTE

A DDE client application posts a WM_DDE_EXECUTE message to a DDE server application to send a string to the server to be processed as a series of commands. The server application is expected to post a WM_DDE_ACK message in response.

WM_DDE_EXECUTE

wParam = (WPARAM) hwnd;        // handle of posting application

lParam = (LPARAM) hCommands;   // handle to global object

Parameters

hwnd

Value of wParam. Identifies the client window posting the message.

hCommands

Value of lParam. Contains a global memory object that references an ANSI or Unicode command string, depending on the types of windows involved in the conversation.

Remarks

The command string is a null-terminated string consisting of one or more opcode strings enclosed in single brackets ([ ]).

Each opcode string has the following syntax, where the parameters list is optional:

opcode parameters

The opcode is any application-defined single token. It cannot include spaces, commas, parentheses, brackets, or quotation marks.

The parameters list can contain any application-defined value or values. Multiple parameters are separated by commas, and the entire parameter list is enclosed in parentheses. Parameters cannot include commas or parentheses except inside a quoted string. If a bracket or parenthesis character is to appear in a quoted string, it need not be doubled, as was the case under the old rules.

Following are some valid command strings:

[connect][download(query1,results.txt)][disconnect]

[query("sales per employee for each district")]

[open("sample.xlm")][run("r1c1")]

[quote_case("This is a "" character")]

[bracket_or_paren_case("()s or []s should be no problem.")]

Note that, under the old rules, parentheses and brackets had to be doubled, as follows:

[bracket_or_paren_case("(())s or [[]]s should be no problem.")]

Servers should be able to parse commands in either form.

Unicode execute strings should be used only when both the client and server window handles cause the IsWindowUnicode function to return TRUE.

Posting

The client application posts the WM_DDE_EXECUTE message by calling the PostMessage function, not the SendMessage function.

The client application allocates hCommands by calling the GlobalAlloc function with the GMEM_DDESHARE option.

When processing the WM_DDE_ACK message that the server posts in reply to a WM_DDE_EXECUTE message, the client application must delete the hCommands object sent back in the WM_DDE_ACK message.

Receiving

The server application posts the WM_DDE_ACK message to respond positively or negatively. The server should reuse the hCommands object.

Unless specified otherwise by a sub-protocol, the server should not post the WM_DDE_ACK message until all the actions specified by the execute command string are completed. The one exception to this rule is when the string causes the server to terminate the conversation.

See Also

GlobalAlloc, IsWindowUnicode, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_ACK


WM_DDE_INITIATE

A DDE client application sends a WM_DDE_INITIATE message to initiate a conversation with a server application responding to the specified application and topic names. Upon receiving this message, all server applications with names that match the specified application and that support the specified topic are expected to acknowledge it. (For more information, see the WM_DDE_ACK message.)

WM_DDE_INITIATE

wParam = (WPARAM) hwnd;             // handle of posting appl.

lParam = MAKELPARAM(aApp, aTopic);  // appl. and topic atoms

Parameters

hwnd

Value of wParam. Identifies the client window sending the message.

aApp

Value of the low-order word of lParam. Contains an atom that identifies the application with which a conversation is requested. The application name cannot contain slashes (/) or backslashes (\). These characters are reserved for network implementations. If aApp is NULL, a conversation with all applications is requested.

aTopic

Value of the high-order word of lParam. Contains an atom that identifies the topic for which a conversation is requested. If the topic is NULL, conversations for all available topics are requested.

Remarks

If aApp is NULL, any server application can respond. If aTopic is NULL, any topic is valid. Upon receiving a WM_DDE_INITIATE request with the aTopic parameter set to NULL, a server must send a WM_DDE_ACK message for each of the topics it supports.

Sending

The client application sends WM_DDE_INITIATE by calling the SendMessage function, not the PostMessage function. The client broadcasts the message to all top-level windows by setting the first parameter of SendMessage to −1.

If the client application has already obtained the window handle of the desired server, it can send WM_DDE_INITIATE directly to the server window by passing the server’s window handle as the first parameter of SendMessage.

The client application allocates aApp and aTopic by calling GlobalAddAtom.

When SendMessage returns, the client application must delete the aApp and aTopic atoms.

Receiving

To complete the initiation of a conversation, the server application must respond with one or more WM_DDE_ACK messages, where each message is for a separate topic. When sending WM_DDE_ACK message, the server should create new aApp and aTopic atoms; it should not reuse the atoms sent with WM_DDE_INITIATE.

See Also

GlobalAddAtom, GlobalAlloc, PostMessage, SendMessage, WM_DDE_ACK


WM_DDE_POKE

A DDE client application posts a WM_DDE_POKE message to a DDE server application. A client uses this message to request the server to accept an unsolicited data item. The server is expected to reply with a WM_DDE_ACK message indicating whether it accepted the data item.

WM_DDE_POKE

wParam = (WPARAM) hwnd;        // handle of posting application

lParam = (LPARAM) lPackedVal;  // packed DDEPOKE and item atom

Parameters

hwnd

Value of wParam. Identifies the client window posting the message.

lPackedVal

Value of lParam. The component parameters that are packed into lPackedVal are extracted by calling the UnpackDDElParam function. The low-order word is hData. The high-order word is aItem.

Parameter	Description
hData	Identifies a global memory object containing a DDEPOKE structure with the data and additional information.
aItem	Contains a global atom that identifies the data item for which the data or notification is being sent.
Remarks

Posting

The client application posts the WM_DDE_POKE message by using the PostMessage function.

The client application must allocate memory for the hData object by using the GlobalAlloc function with the GMEM_DDESHARE option. The client application must delete the hData object if either of the following conditions is true:

•	The server application responds with a negative WM_DDE_ACK message.

•	The fRelease member is FALSE, but the server application responds with either a positive or negative WM_DDE_ACK.

The client application must create the aItem atom by using the GlobalAddAtom function.

The client application must create or reuse the WM_DDE_POKE lPackedVal parameter by calling the PackDDElParam function or the ReuseDDElParam function with hData supplied as the low-order word and aItem supplied as the high-order word.

Receiving

The server application should post the WM_DDE_ACK message to respond positively or negatively. When posting WM_DDE_ACK, the server can either reuse the aItem atom, or it can delete it and create a new one.

The server must create or reuse the WM_DDE_ACK lPackedVal parameter by calling the PackDDElParam function or the ReuseDDElParam function with wStatus supplied as the low-order word and aItem supplied as the high-order word.

To free the hData object, the server should call the GlobalFree function. Also, if the data format is either CF_DSPMETAFILEPICT or CF_METAFILEPICT, the server must also call DeleteMetaFile with the embedded metafile handle. These two formats have an extra level of indirection; that is, an application must lock hData to get a pointer to a handle, then lock that handle to get a pointer to a METAFILEPICT structure, and finally call DeleteMetaFile with the handle from the hMF member of the METAFILEPICT structure.

To free the lPackedVal object, the server should call the FreeDDElParam function.

See Also

DDEPOKE, DeleteMetaFile, FreeDDElParam, GlobalAddAtom, GlobalAlloc, GlobalFree, METAFILEPICT, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_ACK


WM_DDE_REQUEST

A DDE client application posts a WM_DDE_REQUEST message to a DDE server application to request the value of a data item.

WM_DDE_REQUEST

wParam = (WPARAM) hwnd;        // handle of posting application

lParam = (LPARAM) lParam;      // holds cfFormat and aItem

Parameters

hwnd

Value of wParam. Identifies the client window sending the message.

lParam

Holds the cfFormat and aItem parameters.

Parameter	Description
cfFormat	This is the LOWORD of lParam. Specifies a standard or registered clipboard format.
aItem	This is the HIWORD of lParam. Contains an atom that identifies the data item requested from the server.
Remarks

Posting

The client application posts the WM_DDE_REQUEST message by calling the PostMessage function, not the SendMessage function.

The client application allocates aItem by calling the GlobalAddAtom function.

Receiving

If the receiving (server) application can satisfy the request, it responds with a WM_DDE_DATA message containing the requested data. Otherwise, it responds with a negative WM_DDE_ACK message.

When responding with either a WM_DDE_DATA or WM_DDE_ACK message, the server application can either reuse the aItem atom or it can delete the atom and create a new one.

See Also

GlobalAddAtom, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_ACK, WM_DDE_DATA


WM_DDE_TERMINATE

A DDE application (client or server) posts a WM_DDE_TERMINATE message to terminate a conversation.

WM_DDE_TERMINATE

wParam = (WPARAM) hwnd; // handle of posting window

lParam = 0;             // not used, must be zero

Parameters

hwnd

Value of wParam. Identifies the client or server window posting the message.

Remarks

Posting

The client or server application posts the WM_DDE_TERMINATE message by calling the PostMessage function, not the SendMessage function.

While waiting for confirmation of the termination, the posting application should not post any other messages to the receiving application. If the sending application receives messages (other than WM_DDE_TERMINATE) from the receiving application, it should delete any atoms or shared memory objects accompanying the messages, except hData objects associated with WM_DDE_POKE or WM_DDE_DATA messages that do not have the fRelease flag set.

Receiving

The client or server application should respond by posting a WM_DDE_TERMINATE message.

See Also

PostMessage, SendMessage, WM_DDE_DATA, WM_DDE_POKE


WM_DDE_UNADVISE

A DDE client application posts a WM_DDE_UNADVISE message to inform a DDE server application that the specified item or a particular clipboard format for the item should no longer be updated. This terminates the warm or hot data link for the specified item.

WM_DDE_UNADVISE

wParam = (WPARAM) hwnd;        // handle of posting application

lParam = (LPARAM) lParam;      // format and item atom

Parameters

hwnd

Value of wParam. Identifies the client window sending the message.

lParam

Holds the cfFormat and aItem parameters.

Parameter	Description
cfFormat	This is the LOWORD of lParam. Specifies the clipboard format of the item for which the update request is being retracted. If cfFormat is NULL, all active WM_DDE_ADVISE conversations for the item are to be terminated.
aItem	This is the HIWORD of lParam. Contains a global atom that identifies the item for which the update request is being retracted. When aItem is NULL, all active WM_DDE_ADVISE links associated with the conversation are to be terminated.
Remarks

Posting

The client application posts the WM_DDE_UNADVISE message by calling the PostMessage function, not the SendMessage function.

The client application allocates aItem by calling the GlobalAddAtom function.

Receiving

The server application posts the WM_DDE_ACK message to respond positively or negatively. When posting WM_DDE_ACK, the server can either reuse the aItem atom, or it can delete the atom and create a new one.

See Also

GlobalAddAtom, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_ACK, WM_DDE_ADVISE


WM_DEADCHAR

WM_DEADCHAR

chCharCode = (TCHAR) wParam;    // character code

lKeyData = lParam;              // key data

The WM_DEADCHAR message is posted to the window with the keyboard focus when a WM_KEYUP message is translated by the TranslateMessage function. WM_DEADCHAR specifies a character code generated by a dead key. A dead key is a key that generates a character, such as the umlaut (double-dot), that is combined with another character to form a composite character. For example, the umlaut-O character (Ö) is generated by typing the dead key for the umlaut character, and then typing the O key.

Parameters

chCharCode

Value of wParam. Specifies the character code generated by the dead key.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table:

Value	Description
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30	Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31	Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.
Return Values

An application should return zero if it processes this message.

Remarks

The WM_DEADCHAR message typically is used by applications to give the user feedback about each key pressed. For example, an application can display the accent in the current character position without moving the caret.

Because there is not necessarily a one-to-one correspondence between keys pressed and character messages generated, the information in the high-order word of the lKeyData parameter is generally not useful to applications. The information in the high-order word applies only to the most recent WM_KEYDOWN message that precedes the posting of the WM_DEADCHAR message.

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and the right CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Some other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

TranslateMessage, WM_KEYDOWN, WM_KEYUP, WM_SYSDEADCHAR


WM_DELETEITEM

The WM_DELETEITEM message is sent to the owner of a list box or combo box when the list box or combo box is destroyed or when items are removed by the LB_DELETESTRING, LB_RESETCONTENT, CB_DELETESTRING, or CB_RESETCONTENT message. Windows sends a WM_DELETEITEM message for each deleted item. Windows sends the WM_DELETEITEM message for any deleted list box or combo box item with nonzero item data.

WM_DELETEITEM

idCtl = wParam;                      // control identifier

lpdis = (LPDELETEITEMSTRUCT) lParam; // structure with item information

Parameters

idCtl

Value of wParam. Specifies the identifier of the control that sent the WM_DELETEITEM message.

lpdis

Value of lParam. Points to a DELETEITEMSTRUCT structure that contains information about the item deleted from a list box.

Return Values

An application should return TRUE if it processes this message.

See Also

CB_DELETESTRING, CB_RESETCONTENT, DELETEITEMSTRUCT, LB_DELETESTRING, LB_RESETCONTENT


WM_DESTROY

The WM_DESTROY message is sent when a window is being destroyed. It is sent to the window procedure of the window being destroyed after the window is removed from the screen.

This message is sent first to the window being destroyed and then to the child windows (if any) as they are destroyed. During the processing of the message, it can be assumed that all child windows still exist.

WM_DESTROY

Parameters

This message has no parameters.

Return Values

If an application processes this message, it should return zero.

Remarks

If the window being destroyed is part of the clipboard viewer chain (set by calling the SetClipboardViewer function), the window must remove itself from the chain by processing the ChangeClipboardChain function before returning from the WM_DESTROY message.

See Also

ChangeClipboardChain, DestroyWindow, PostQuitMessage, SetClipboardViewer, WM_CLOSE


WM_DESTROYCLIPBOARD

The WM_DESTROYCLIPBOARD message is sent to the clipboard owner when a call to the EmptyClipboard function empties the clipboard.

WM_DESTROYCLIPBOARD

Parameters

This message has no parameters.

Return Values

If an application processes this message, it should return zero.

See Also

EmptyClipboard


WM_DEVICECHANGE

The WM_DEVICECHANGE device message notifies an application or device driver of a change to the hardware configuration of a device or the computer.

Event = (UINT) wParam;
dwData = (DWORD) lParam;

Parameters

Event

Event type. This parameter can be one of the following values:

Value	Meaning
DBT_CONFIGCHANGECANCELED	A request to change the current configuration (dock or undock) has been canceled.
DBT_CONFIGCHANGED	The current configuration has changed, due to a dock or undock.
DBT_DEVICEARRIVAL	A device has been inserted and is now available.
DBT_DEVICEQUERYREMOVE	Permission is requested to remove a device. Any application can deny this request and cancel the removal.
DBT_DEVICEQUERYREMOVEFAILED	A request to remove a device has been canceled.
DBT_DEVICEREMOVECOMPLETE	A device has been removed.
DBT_DEVICEREMOVEPENDING	A device is about to be removed. Cannot be denied.
DBT_DEVICETYPESPECIFIC	A device-specific event has occurred.
DBT_QUERYCHANGECONFIG	Permission is requested to change the current configuration (dock or undock).
DBT_USERDEFINED	The meaning of this message is user-defined.
dwData

Address of a structure that contains event-specific data. Its meaning depends on the given event.

Return Values

Return TRUE to grant a requested action.

Return QUERY_BROADCAST_DENY to deny a requested action.

Remarks

For devices that offer software-controllable features, such as ejection and locking, the operating system typically sends a DBT_DEVICEREMOVEPENDING message to let applications and device drivers end their use of the device gracefully.

If the operating system forcibly removes a device, it may not send a DBT_DEVICEQUERYREMOVE message before doing so.

DBT_CONFIGCHANGECANCELED, DBT_CONFIGCHANGED, DBT_DEVICEARRIVAL, DBT_DEVICEQUERYREMOVE, DBT_DEVICEQUERYREMOVEFAILED, DBT_DEVICEREMOVECOMPLETE, DBT_DEVICEREMOVEPENDING, DBT_DEVICETYPESPECIFIC, DBT_QUERYCHANGECONFIG, DBT_USERDEFINED


WM_DEVMODECHANGE

The WM_DEVMODECHANGE message is sent to all top-level windows whenever the user changes device-mode settings.

WM_DEVMODECHANGE

lpszDev = (LPCTSTR) lParam; // address of device name

Parameters

lpszDev

Value of lParam. Points to the device name specified in the WIN.INI file.

Return Values

An application should return zero if it processes this message.

Remarks

Windows NT: Calls to functions that change the WIN.INI file may be mapped to the registry instead. This mapping occurs when WIN.INI and the section being changed are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Description\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

The change in the storage location has no effect on the behavior of this message.

See Also

WM_WININICHANGE


WM_DISPLAYCHANGE

The WM_DISPLAYCHANGE message is sent to all windows when the display resolution has changed.

WM_DISPLAYCHANGE

cBitsPerPixel = wParam;

cxScreen = LOWORD(lParam);

cyScreen = HIWORD(lParam);

Parameters

cBitsPerPixel

Specifies the new image depth of the display in bits per pixel.

cxScreen

Specifies the new horizontal resolution of the screen.

cyScreen

Specifies the new vertical resolution of the screen.


WM_DRAWCLIPBOARD

The WM_DRAWCLIPBOARD message is sent to the first window in the clipboard viewer chain when the content of the clipboard changes. This enables a clipboard viewer window to display the new content of the clipboard.

WM_DRAWCLIPBOARD

Parameters

This message has no parameters.

Remarks

Only clipboard viewer windows receive this message. These are windows that have been added to the clipboard viewer chain by using the SetClipboardViewer function.

Each window that receives the WM_DRAWCLIPBOARD message must call the SendMessage function to pass the message on to the next window in the clipboard viewer chain. The handle of the next window in the chain is returned by SetClipboardViewer, and may change in response to a WM_CHANGECBCHAIN message.

See Also

SendMessage, SetClipboardViewer, WM_CHANGECBCHAIN


WM_DRAWITEM

The WM_DRAWITEM message is sent to the owner window of an owner-drawn button, combo box, list box, or menu when a visual aspect of the button, combo box, list box, or menu has changed.

WM_DRAWITEM

idCtl = (UINT) wParam;             // control identifier

lpdis = (LPDRAWITEMSTRUCT) lParam; // item-drawing information

Parameters

idCtl

Value of wParam. Specifies the identifier of the control that sent the WM_DRAWITEM message. If the message was sent by a menu, this parameter is zero.

lpdis

Value of lParam. Points to a DRAWITEMSTRUCT structure containing information about the item to be drawn and the type of drawing required.

Return Values

If an application processes this message, it should return TRUE.

Default Action

The DefWindowProc function draws the focus rectangle for an owner-drawn list box item.

Remarks

The itemAction member of the DRAWITEMSTRUCT structure specifies the drawing operation that an application should perform.

Before returning from processing this message, an application should ensure that the device context identified by the hDC member of the DRAWITEMSTRUCT structure is in the default state.

See Also

DefWindowProc, DRAWITEMSTRUCT


WM_DROPFILES

The WM_DROPFILES message is sent when the user releases the left mouse button while the cursor is in the window of an application that has registered itself as a recipient of dropped files.

WM_DROPFILES

hDrop = (HANDLE) wParam;  // handle of internal drop structure

Parameters

hDrop

Value of wParam. Identifies an internal structure describing the dropped files. This handle is used by the DragFinish, DragQueryFile, and DragQueryPoint functions to retrieve information about the dropped files.

Return Values

An application should return zero if it processes this message.

See Also

DragAcceptFiles, DragFinish, DragQueryFile, DragQueryPoint


WM_ENABLE

The WM_ENABLE message is sent when an application changes the enabled state of a window. It is sent to the window whose enabled state is changing. This message is sent before the EnableWindow function returns, but after the enabled state (WS_DISABLED style bit) of the window has changed.

WM_ENABLE

fEnabled = (BOOL) wParam;   // enabled/disabled flag

Parameters

fEnabled

Value of wParam. Specifies whether the window has been enabled or disabled. This parameter is TRUE if the window has been enabled or FALSE if the window has been disabled.

Return Values

If an application processes this message, it should return zero.

See Also

EnableWindow


WM_ENDSESSION

The WM_ENDSESSION message is sent to an application after Windows processes the results of the WM_QUERYENDSESSION message. The WM_ENDSESSION message informs the application whether the Windows session is ending.

WM_ENDSESSION

fEndSession = (BOOL) wParam;     // end-session flag

fLogOff =  lParam                // logoff flag

Parameters

fEndSession

Value of wParam. Specifies whether the session is being ended. If the session is being ended, this parameter is TRUE; otherwise, it is FALSE.

fLogOff

Value of lParam. Indicates whether the user is logging off or shutting down the system. Supported values include: ENDSESSION_LOGOFF.

Return Values

If an application processes this message, it should return zero.

Remarks

If the fEndSession parameter is TRUE, the Windows session can end any time after all applications have returned from processing this message. Therefore, an application should perform all tasks required for termination before returning from this message.

The application need not call the DestroyWindow or PostQuitMessage function when the session is ending.

See Also

DestroyWindow, PostQuitMessage, WM_QUERYENDSESSION


WM_ENTERIDLE

The WM_ENTERIDLE message is sent to the owner window of a modal dialog box or menu that is entering an idle state. A modal dialog box or menu enters an idle state when no messages are waiting in its queue after it has processed one or more previous messages.

WM_ENTERIDLE

fuSource = wParam;    // idle-source flag

hwnd = (HWND) lParam; // handle of dialog box or owner window

Parameters

fuSource

Value of wParam. Specifies whether the message is the result of a dialog box or a menu being displayed. This parameter can be one of the following values:

Value	Meaning
MSGF_DIALOGBOX	The system is idle because a dialog box is displayed.
MSGF_MENU	The system is idle because a menu is displayed.
hwnd

Value of lParam. Contains the handle of the dialog box (if fuSource is MSGF_DIALOGBOX) or of the window containing the displayed menu (if fuSource is MSGF_MENU).

Return Values

An application should return zero if it processes this message.

Remarks

The DefWindowProc function returns zero.

See Also

DefWindowProc


WM_ENTERMENULOOP

The WM_ENTERMENULOOP message informs an application’s main window procedure that a menu modal loop has been entered.

WM_ENTERMENULOOP

wParam = (BOOL) fIsTrackPopupMenu  // flags a shortcut menu

lParam = 0 ;                       // not used; must be zero

Parameters

fIsTrackPopupMenu

Specifies whether the menu involved is a shortcut menu. This parameter has a value of TRUE if it is a shortcut menu, FALSE if it isn’t.

Return Values

An application should return zero if it processes this message.

Remarks

The DefWindowProc function returns zero.

See Also

DefWindowProc, WM_EXITMENULOOP


WM_ENTERSIZEMOVE

The WM_ENTERSIZEMOVE message is sent once to a window when it enters the moving or sizing mode. The window enters the moving or sizing mode when the user clicks the window’s title bar or sizing border, or when the window passes the WM_SYSCOMMAND message to the DefWindowProc function and the wParam parameter of the message specifies the SC_MOVE or SC_SIZE value. Windows sends the WM_ENTERSIZEMOVE message regardless of whether the dragging of full windows is enabled.

WM_ENTERSIZEMOVE

wParam = 0;  // not used, must be zero

lParam = 0;  // not used, must be zero

Parameters

This message has no parameters.

Return Values

An application should return zero if it processes this message.

See Also

DefWindowProc, WM_EXITSIZEMOVE, WM_SYSCOMMAND


WM_ERASEBKGND

An application sends the WM_ERASEBKGND message when the window background must be erased (for example, when a window is resized). The message is sent to prepare an invalidated portion of a window for painting.

WM_ERASEBKGND

hdc = (HDC) wParam; // handle of device context

Parameters

hdc

Value of wParam. Identifies the device context.

Return Values

An application should return nonzero if it erases the background; otherwise, it should return zero.

Remarks

The DefWindowProc function erases the background by using the class background brush specified by the hbrBackground member of the WNDCLASS structure. If hbrBackground is NULL, the application should process the WM_ERASEBKGND message and erase the background.

An application should return nonzero in response to WM_ERASEBKGND if it processes the message and erases the background; this indicates that no further erasing is required. If the application returns zero, the window will remain marked for erasing. (Typically, this indicates that the fErase member of the PAINTSTRUCT structure will be TRUE.)

See Also

BeginPaint, DefWindowProc, PAINTSTRUCT, WM_ICONERASEBKGND, WNDCLASS


WM_EXITMENULOOP

The WM_EXITMENULOOP message informs an application’s main window procedure that a menu modal loop has been exited.

WM_EXITLOOP

wParam = (BOOL) fIsTrackPopupMenu    // flags a shortcut menu

lParam = 0 ;                         // not used; must be zero

Parameters

fIsTrackPopupMenu

Specifies whether the menu involved is a shortcut menu. This parameter has a value of TRUE if it is a shortcut menu, FALSE if it isn’t.

Return Values

An application should return zero if it processes this message.

Remarks

The DefWindowProc function returns zero.

See Also

DefWindowProc, WM_ENTERMENULOOP


WM_EXITSIZEMOVE

The WM_EXITSIZEMOVE message is sent once to a window after it has exited the moving or sizing mode.

WM_EXITSIZEMOVE

wParam = 0;  // not used; must be zero

lParam = 0;  // not used; must be zero

Parameters

This message has no parameters.

Return Values

An application should return zero if it processes this message.

See Also

WM_ENTERSIZEMOVE


WM_FONTCHANGE

An application sends the WM_FONTCHANGE message to all top-level windows in the system after changing the pool of font resources.

WM_FONTCHANGE

wParam = 0; // not used, must be zero

lParam = 0; // not used, must be zero

Parameters

This message has no parameters.

Remarks

An application that adds or removes fonts from the system (for example, by using the AddFontResource or RemoveFontResource function) should send this message to all top-level windows.

To send the WM_FONTCHANGE message to all top-level windows, an application can call the SendMessage function with the hwnd parameter set to HWND_BROADCAST.

See Also

AddFontResource, RemoveFontResource, SendMessage


WM_GETDLGCODE

The WM_GETDLGCODE message is sent to the dialog box procedure associated with a control. Normally, Windows handles all arrow-key and TAB-key input to the control. By responding to the WM_GETDLGCODE message, an application can take control of a particular type of input and process the input itself.

WM_GETDLGCODE

Parameters

This message has no parameters.

Return Values

The return value is one or more of the following values, indicating which type of input the application processes.

Value	Meaning
DLGC_BUTTON	Button.
DLGC_DEFPUSHBUTTON	Default push button.
DLGC_HASSETSEL	EM_SETSEL messages.
DLGC_RADIOBUTTON	Radio button.
DLGC_STATIC	Static control.
DLGC_UNDEFPUSHBUTTON	Nondefault push button.
DLGC_WANTALLKEYS	All keyboard input.
DLGC_WANTARROWS	Direction keys.
DLGC_WANTCHARS	WM_CHAR messages.
DLGC_WANTMESSAGE	All keyboard input (the application passes this message on to a control).
DLGC_WANTTAB	TAB key.
Default Action

The DefWindowProc function returns zero.

Remarks

Although the DefWindowProc function always returns zero in response to the WM_GETDLGCODE message, the window procedure for the predefined control classes return a code appropriate for each class.

The WM_GETDLGCODE message and the returned values are useful only with user-defined dialog box controls or standard controls modified by subclassing.

See Also

DefWindowProc, EM_SETSEL, WM_CHAR


WM_GETFONT

An application sends a WM_GETFONT message to a control to retrieve the font with which the control is currently drawing its text.

WM_GETFONT

wParam = 0; // not used, must be zero

lParam = 0; // not used, must be zero

Parameters

This message has no parameters.

Return Values

The return value is the handle of the font used by the control, or NULL if the control is using the system font.

See Also

WM_SETFONT


WM_GETHOTKEY

An application sends a WM_GETHOTKEY message to determine the hot key associated with a window.

WM_GETHOTKEY

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is the virtual-key code and modifiers for the hot key, or NULL if no hot key is associated with the window. The virtual-key code is in the low byte of the return value and the modifiers are in the high byte. The modifiers can be a combination of the following flags:

Value	Meaning
HOTKEYF_ALT	ALT key
HOTKEYF_CONTROL	CTRL key
HOTKEYF_EXT	Extended key
HOTKEYF_SHIFT	SHIFT key
Remarks

These hot keys are unrelated to the hot keys set by the RegisterHotKey function.

See Also

RegisterHotKey, WM_SETHOTKEY


WM_GETICON

The WM_GETICON message is sent to a window to retrieve the handle of the large or small icon associated with a window. Windows retrieves the large icon when drawing a minimized window, and the small icon when drawing a title bar.

WM_GETICON

fType = wParam;  // icon type

Parameters

fType

Value of wParam. Specifies the type of icon being retrieved. This parameter can be one of the following values:

Value	Meaning
ICON_BIG	Retrieve the large icon for the window.
ICON_SMALL	Retrieve the small icon for the window.
Return Values

The return value is the handle of the large or small icon, depending on the value of fType. When an application receives this message, it can return the handle of a large or small icon, or pass the message to DefWindowProc.

Default Action

DefWindowProc returns the handle of the large or small icon associated with the window, depending on the value of fType.

Remarks

When an application receives this message, it can return the handle of a large or small icon, or pass the message to DefWindowProc.

See Also

DefWindowProc, WM_SETICON


WM_GETMINMAXINFO

The WM_GETMINMAXINFO message is sent to a window when the size or position of the window is about to change. An application can use this message to override the window’s default maximized size and position, or its default minimum or maximum tracking size.

WM_GETMINMAXINFO

lpmmi = (LPMINMAXINFO) lParam; // address of structure

Parameters

lpmmi

Value of lParam. Points to a MINMAXINFO structure that contains the default maximized position and dimensions, and the default minimum and maximum tracking sizes. An application can override the defaults by setting the members of this structure.

Return Values

If an application processes this message, it should return zero.

Remarks

The maximum tracking size is the largest window size that can be produced by using the borders to size the window. The minimum tracking size is the smallest window size that can be produced by using the borders to size the window.

See Also

MoveWindow, SetWindowPos, MINMAXINFO


WM_GETTEXT

An application sends a WM_GETTEXT message to copy the text that corresponds to a window into a buffer provided by the caller.

WM_GETTEXT

wParam = (WPARAM) cchTextMax;   // number of characters to copy

lParam = (LPARAM) lpszText;     // address of buffer for text

Parameters

cchTextMax

Value of wParam. Specifies the maximum number of characters to be copied, including the terminating null character.

lpszText

Value of lParam. Points to the buffer that is to receive the text.

Return Values

The return value is the number of characters copied.

Default Action

The DefWindowProc function copies the text associated with the window into the specified buffer and returns the number of characters copied.

Remarks

For an edit control, the text to be copied is the content of the edit control. For a combo box, the text is the content of the edit control (or static-text) portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title. To copy the text of an item in a list box, an application can use the LB_GETTEXT message.

When the WM_GETTEXT message is sent to a static control with the SS_ICON style, the handle of the icon will be returned in the first four bytes of the buffer pointed to by lpszText. This is true only if the WM_SETTEXT message has been used to set the icon.

In a rich edit control, if the text to be copied exceeds 64K, use either the message EM_STREAMOUT or EM_GETSELTEXT.

See Also

DefWindowProc, EM_GETSELTEXT, EM_STREAMOUT, GetWindowText, GetWindowTextLength, LB_GETTEXT, WM_GETTEXTLENGTH, WM_SETTEXT


WM_GETTEXTLENGTH

An application sends a WM_GETTEXTLENGTH message to determine the length, in characters, of the text associated with a window. The length does not include the terminating null character.

WM_GETTEXTLENGTH

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

The return value is the length, in characters, of the text.

Default Action

The DefWindowProc function returns the length, in characters, of the text. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section.

Remarks

For an edit control, the text to be copied is the content of the edit control. For a combo box, the text is the content of the edit control (or static-text) portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title. To determine the length of an item in a list box, an application can use the LB_GETTEXTLEN message.

Under certain conditions, the DefWindowProc function returns a value that is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the operating system allowing for the possible existence of DBCS characters within the text. The return value, however, will always be at least as large as the actual length of the text; you can thus always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode.

To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the GetWindowText function.

See Also

CB_GETLBTEXT, DefWindowProc, GetWindowText, GetWindowTextLength, LB_GETTEXT, LB_GETTEXTLEN, WM_GETTEXT


WM_HELP

The WM_HELP message indicates that the user pressed the F1 key. If a menu is active when F1 is pressed, WM_HELP is sent to the window associated with the menu; otherwise, WM_HELP is sent to the window that has the keyboard focus. If no Window has the keyboard focus, WM_HELP is sent to the currently active window.

WM_HELP

lphi = (LPHELPINFO) lParam;

Parameters

lphi

Pointer to a HELPINFO structure that contains information about the menu item, control, dialog box, or window for which help is requested.

Return Values

Returns TRUE.

Remarks

The DefWindowProc function passes WM_HELP to the parent window of a child window or to the owner of a top-level window.

See Also

DefWindowProc, HELPINFO


WM_HOTKEY

The WM_HOTKEY message is posted when the user presses a hot key registered by the RegisterHotKey function. The message is placed at the top of the message queue associated with the thread that registered the hot key.

WM_HOTKEY

idHotKey = (int) wParam;              // identifier of hot key

fuModifiers = (UINT) LOWORD(lParam);  // key-modifier flags

uVirtKey = (UINT) HIWORD(lParam);     // virtual-key code

Parameters

idHotKey

Value of wParam. Specifies the identifier of the hot key that generated the message. If the message was generated by a system-defined hot key, the idHotKey parameter will be one of the following values:

Value	Meaning
IDHOT_SNAPDESKTOP	The “snap desktop” hot key was pressed.
IDHOT_SNAPWINDOW	The “snap window” hot key was pressed.
fuModifiers

Specifies the keys that were to be pressed in combination with the key specified by the nVirtKey parameter to generate the WM_HOTKEY message. The fuModifiers parameter can be a combination of the following values:

Value	Meaning
MOD_ALT	Either ALT key was held down.
MOD_CONTROL	Either CTRL key was held down.
MOD_SHIFT	Either SHIFT key was held down.
MOD_WIN	Either WINDOWS key was held down. These keys appear only on the Microsoft Ergonomic Keyboard and are labeled with the Microsoft Windows logo.
uVirtKey

Specifies the virtual key code of the hot key.

Remarks

WM_HOTKEY is unrelated to the WM_GETHOTKEY and WM_SETHOTKEY hot keys. The WM_HOTKEY message is sent for generic hot keys while the WM_SET\GETHOTKEY messages relate to window activation hot keys.

See Also

RegisterHotKey, WM_GETHOTKEY, WM_SETHOTKEY


WM_HSCROLL

The WM_HSCROLL message is sent to a window when a scroll event occurs in the window’s standard horizontal scroll bar. This message is also sent to the owner of a horizontal scroll bar control when a scroll event occurs in the control.

WM_HSCROLL

nScrollCode = (int) LOWORD(wParam);  // scroll bar value

nPos = (short int) HIWORD(wParam);   // scroll box position

hwndScrollBar = (HWND) lParam;       // handle of scroll bar

Parameters

nScrollCode

Value of the low-order word of wParam. Specifies a scroll bar value that indicates the user’s scrolling request. This parameter can be one of the following values:

Value	Meaning
SB_BOTTOM	Scrolls to the lower right.
SB_ENDSCROLL	Ends scroll.
SB_LINELEFT	Scrolls left by one unit.
SB_LINERIGHT	Scrolls right by one unit.
SB_PAGELEFT	Scrolls left by the width of the window.
SB_PAGERIGHT	Scrolls right by the width of the window.
SB_THUMBPOSITION	Scrolls to the absolute position. The current position is specified by the nPos parameter.
SB_THUMBTRACK	Drags scroll box to the specified position. The current position is specified by the nPos parameter.
SB_TOP	Scrolls to the upper left.
nPos

Value of the high-order word of wParam. Specifies the current position of the scroll box if the nScrollCode parameter is SB_THUMBPOSITION or SB_THUMBTRACK; otherwise, nPos is not used.

hwndScrollBar

Value of lParam. Identifies the control if WM_HSCROLL is sent by a scroll bar control. If WM_HSCROLL is sent by a window’s standard scroll bar, hwndScrollBar is not used.

Return Values

If an application processes this message, it should return zero.

Remarks

The SB_THUMBTRACK notification message is typically used by applications that provide feedback as the user drags the scroll box.

If an application scrolls the content of the window, it must also reset the position of the scroll box by using the SetScrollPos function.

Note that the WM_HSCROLL message carries only 16 bits of scroll box position data. Thus, applications that rely solely on WM_HSCROLL (and WM_VSCROLL) for scroll position data have a practical maximum position value of 65,535.

However, because the SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange functions support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier of the WM_HSCROLL and WM_VSCROLL messages. See GetScrollPos for a description of the technique and its limits.

See Also

GetScrollPos, GetScrollRange, SetScrollPos, SetScrollRange, WM_VSCROLL


WM_HSCROLLCLIPBOARD

The WM_HSCROLLCLIPBOARD message is sent to the clipboard owner by a clipboard viewer window. This occurs when the clipboard contains data in the CF_OWNERDISPLAY format and an event occurs in the clipboard viewer’s horizontal scroll bar. The owner should scroll the clipboard image and update the scroll bar values.

WM_HSCROLLCLIPBOARD

hwndViewer = (HWND) wParam;         // handle of clipboard viewer window

nScrollCode = (int) LOWORD(lParam); // scroll bar code

nPos = (int) HIWORD(lParam);        // scroll box position

Parameters

hwndViewer

Value of wParam. Identifies the clipboard viewer window.

nScrollCode

Value of the low-order word of lParam. Specifies a scroll bar event. This parameter can be one of the following values:

Value	Meaning
SB_BOTTOM	Scroll to lower right.
SB_ENDSCROLL	End scroll.
SB_LINEDOWN	Scroll one line down.
SB_LINEUP	Scroll one line up.
SB_PAGEDOWN	Scroll one page down.
SB_PAGEUP	Scroll one page up.
SB_THUMBPOSITION	Scroll to absolute position. The current position is specified by the nPos parameter.
SB_TOP	Scroll to upper left.
nPos

Value of the high-order word of lParam. Specifies the current position of the scroll box if the nScrollCode parameter is SB_THUMBPOSITION; otherwise, the nPos parameter is not used.

Return Values

If an application processes this message, it should return zero.

Remarks

The clipboard owner can use the ScrollWindow function to scroll the image in the clipboard viewer window and invalidate the appropriate region.

See Also

ScrollWindow


WM_ICONERASEBKGND

The WM_ICONERASEBKGND message is sent to a minimized window when the background of the icon must be filled before painting the icon. A window receives this message only if a class icon is defined for the window; otherwise, WM_ERASEBKGND is sent.

WM_ICONERASEBKGND

hdc = (HDC) wParam; // handle of device context

Parameters

hdc

Value of wParam. Identifies the device context of the icon.

Return Values

An application should return nonzero if it processes this message.

Remarks

The DefWindowProc function fills the icon background with the class background brush of the parent window.

See Also

DefWindowProc, WM_ERASEBKGND


WM_IME_CHAR

The WM_IME_CHAR message is sent to an application when the IME gets a character of the conversion result. Unlike the WM_CHAR message, this message can include double-byte as well as single-byte character values.

chCharCode1 = (TCHAR) wParam;
chCharCode2 = (TCHAR) wParam>>8;
lKeyData = lParam;

Parameters

chCharCode1 and chCharCode2

Single- or double-byte character value.

lKeyData

Repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown following:

Bit	Meaning
0 - 15	Repeat count: Since the first byte and second byte is continuous, this is always 1.
16 - 23	Scan Code: Scan code for complete a FE character.
24 - 28	Not used.
29	Context code.
31	Conversion state.
Remarks

If the WM_IME_CHAR message includes a double-byte character, the DefWindowProc function converts this message into two WM_CHAR messages, each containing one byte of the double-byte character.

See Also

DefWindowProc, WM_CHAR


WM_IME_COMPOSITION

The WM_IME_COMPOSITION message is sent to an application when the IME changes composition status as a result of a key stroke. An application should process this message if it displays composition characters itself. Otherwise, it should send the message to the IME window.

chDBCS = (WORD) wParam;
fFlags = (BOOL) lParam;

Parameters

chDBCS

DBCS character representing the latest change to the composition string.

fFlags

Change flag, indicating how the composition string or character changed. This parameter can be one or more of the following values:

GCS_COMPSTR	GCS_SETCURSORPOS
GCS_COMPATTR	GCS_RESULTSTR
GCS_COMPCLAUSE	GCS_RESULTCLAUSE
GCS_COMPREADSTR	GCS_RESULTREADSTR
GCS_COMPREADATTR	GCS_RESULTREADCLAUSE
GCS_COMPREADCLAUSE	GCR_ERRORSTR
GCS_TYPINGINFO	GCR_INFOSTR
Return Values

No return value.

Remarks

For more information about these values, see the “IME Composition String Values” table in Input Method Editor Constants.

The fFlags parameter can also be a combination of the following values:

Value	Meaning
CS_INSERTCHAR	Specifies that the given composition character should be inserted at the current insertion point. An application should display the composition character if it processes this message.
CS_NOMOVECARET	Specifies that the application must not move the caret position as a result of processing the message. For example, if an IME specifies a combination of CS_INSERTCHAR and CS_NOMOVECARET, the application should insert the given character at the current caret position but should not move caret to the next position. A subsequent WM_IME_COMPOSITION message with GCS_RESULTSTR will replace this character.
If the application has created an IME window, it should pass this message to that window. The DefWindowProc function processes this message by passing it to the default IME window.The IME window processes this message by updating its appearance based on the change flag given. An application can call ImmGetCompositionString to retrieve the new composition status.

If none of the GCS_ values are set, the message indicates that the current composition has been canceled and applications that draw the composition string should delete the string.

See Also

DefWindowProc, ImmGetCompositionString


WM_IME_COMPOSITIONFULL

The WM_IME_COMPOSITIONFULL message is sent to an application when the IME window finds no space to extend the area for the composition window. The application should use the IMC_SETCOMPOSITIONWINDOW message to specify how to display the window.

Return Values

No return value.

Remarks

The wParam and lParam parameters are not used. The IME window, not the IME, sends this notification message by using the SendMessage message.

See Also

IMC_SETCOMPOSITIONWINDOW, SendMessage


WM_IME_CONTROL

The WM_IME_CONTROL message directs the IME window to carry out the requested command. An application uses this message to control the IME window created by the application.

wParam = (WPARAM) (DWORD) dwCommand;
lParam = (LPARAM) (DWORD) dwData;

Parameters

dwCommand

Command value. This parameter can be one of the following values:

IMC_GETCANDIDATEPOS	IMC_OPENSTATUSWINDOW
IMC_GETCOMPOSITIONFONT	IMC_SETCANDIDATEPOS
IMC_GETCOMPOSITIONWINDOW	IMC_SETCOMPOSITIONFONT
IMC_GETCONVERSIONMODE	IMC_SETCOMPOSITIONWINDOW
IMC_GETOPENSTATUS	IMC_SETCONVERSIONMODE
IMC_GETSENTENCEMODE	IMC_SETOPENSTATUS
IMC_GETSTATUSWINDOWPOS	IMC_SETSENTENCEMODE
IMC_CLOSESTATUSWINDOW	IMC_SETSTATUSWINDOWPOS
For more information about these commands, see the individual descriptions.

dwData

Command-specific value.

Return Values

Returns a command-specific value.

See Also

IMC_CLOSESTATUSWINDOW, IMC_GETCANDIDATEPOS, IMC_GETCOMPOSITIONFONT, IMC_GETCOMPOSITIONWINDOW, IMC_GETCONVERSIONMODE, IMC_GETOPENSTATUS, IMC_GETSENTENCEMODE, IMC_GETSTATUSWINDOWPOS, IMC_OPENSTATUSWINDOW, IMC_SETCANDIDATEPOS, IMC_SETCOMPOSITIONFONT, IMC_SETCOMPOSITIONWINDOW, IMC_SETCONVERSIONMODE, IMC_SETOPENSTATUS, IMC_SETSENTENCEMODE, IMC_SETSTATUSWINDOWPOS


WM_IME_ENDCOMPOSITION

The WM_IME_ENDCOMPOSITION message is sent to an application when the IME ends composition. An application should process this message if it displays composition characters itself.

Return Values

No return value.

Remarks

The wParam and lParam parameters are not used.

If an application has created an IME window, it should pass this message to that window. The DefWindowProc function processes this message by passing it to default IME window.

See Also

DefWindowProc


WM_IME_KEYDOWN

The WM_IME_KEYDOWN message is sent to an application by the IME to notify the application of a key press. The parameters and return value for this message are identical to the WM_KEYDOWN message. An application can process this message or pass it to the DefWindowProc function to generate a matching WM_KEYDOWN message. This message is usually generated by the IME to keep message order.

nVirtKey = (int) wParam;    // virtual-key code
lKeyData = lParam;          // key data

See Also

DefWindowProc


WM_IME_KEYUP

The WM_IME_KEYUP message is sent to an application by the IME to notify the application of a key release. The parameters and return value for this message are identical to the WM_KEYUP message. An application can process this message or pass it to the DefWindowProc function to generate a matching WM_KEYUP message. This message is usually generated by the IME to keep message order.

nVirtKey = (int) wParam;    // virtual-key code
lKeyData = lParam;          // key data

See Also

DefWindowProc


WM_IME_NOTIFY

The WM_IME_NOTIFY message is sent to an application to notify it of changes to the IME window. An application processes this message if it is responsible for managing the IME window.

dwCommand = (DWORD) wParam;
dwData = (DWORD) lParam;

Parameters

dwCommand

Command value. This parameter may be one of the following values:

IMN_CHANGECANDIDATE	IMN_SETCANDIDATEPOS
IMN_CLOSECANDIDATE	IMN_SETCOMPOSITIONFONT
IMN_CLOSESTATUSWINDOW	IMN_SETCOMPOSITIONWINDOW
IMN_GUIDELINE	IMN_SETCONVERSIONMODE
IMN_OPENCANDIDATE	IMN_SETOPENSTATUS
IMN_OPENSTATUSWINDOW	IMN_SETSENTENCEMODE
IMN_PRIVATE	IMN_SETSTATUSWINDOWPOS
For more information about these commands, see the corresponding descriptions.

dwData

Command-specific value.

Return Values

Returns a command-specific value.

IMN_CHANGECANDIDATE, IMN_OPENCANDIDATE, IMN_OPENSTATUSWINDOW, IMN_SETCANDIDATEPOS, IMN_SETCOMPOSITIONFONT, IMN_SETCOMPOSITIONWINDOW, IMN_SETCONVERSIONMODE, IMN_SETOPENSTATUS, IMN_SETSENTENCEMODE, IMN_SETSTATUSWINDOWPOS


WM_IME_SELECT

The WM_IME_SELECT message is sent to an application when the system is about to change the current IME. An application that has created an IME window should pass this message to that window so that it can retrieve the keyboard layout handle for the newly selected IME.

fSeleft = (BOOL) wParam;
hKL = (HANDLE) lParam;

Parameters

fSelect

Selection flag. If TRUE, the specified IME is selected; if FALSE, the specified IME is no longer selected.

hKL

Handle to the keyboard layout associated with the IME.

Return Values

No return value.

Remarks

The DefWindowProc function processes this message by passing the information to the default IME window.

See Also

DefWindowProc


WM_IME_SETCONTEXT

The WM_IME_SETCONTEXT message is sent to an application when a window of the application is activated. If the application has created an IME window, it should call the ImmIsUIMessage function. Otherwise, it should pass this message to the DefWindowProc function.

fSet = (BOOL) wParam;
iShow = (DWORD) lParam;

Parameters

fSet

Active flag. If TRUE, the input context is active. If FALSE, the context is inactive.

iShow

Show flags. Can be a combination of the following values:

Value	Description
ISC_SHOWUICOMPOSITIONWINDOW	Shows the composition window by UI window.
ISC_SHOWUIGUIDWINDOW	Shows the guide window by UI window
ISC_SHOWUISOFTKBD	Shows the soft keyboard by UI window
ISC_SHOWUICANDIDATEWINDOW	Shows the candidate window of Index 0 by UI window.
ISC_SHOWUICANDIDATEWINDOW << 1	Shows the candidate window of Index 1 by UI window.
ISC_SHOWUICANDIDATEWINDOW << 2	Shows the candidate window of Index 2 by UI window.
ISC_SHOWUICANDIDATEWINDOW << 3	Shows the candidate window of Index 3 by UI window.
If the application draws the composition window, the default IME window does not need to show its composition window. In this case, the application must clear the ISC_SHOWUICOMPOSITIONWINDOW value from the lParam parameter before passing the message to the DefWindowProc or ImmIsUIMessage functions.

Return Values

Returns the value returned by DefWindowProc or ImmIsUIMessage.

See Also

DefWindowProc, ImmIsUIMessage


WM_IME_STARTCOMPOSITION

The WM_IME_STARTCOMPOSITION message is sent immediately before the IME generates composition string as a result of a key stroke. The message is a notification to an IME window to open its composition window. An application should process this message if it displays composition characters itself.

Return Values

No return value.

Remarks

The wParam and lParam parameters are not used.

If an application has created an IME window, it should pass the WM_IME_STARTCOMPOSITION message to that window. The DefWindowProc function processes this message by passing it to the default IME window.

See Also

DefWindowProc


WM_INITDIALOG

The WM_INITDIALOG message is sent to the dialog box procedure immediately before a dialog box is displayed. Dialog box procedures typically use this message to initialize controls and carry out any other initialization tasks that affect the appearance of the dialog box.

WM_INITDIALOG

hwndFocus = (HWND) wParam; // handle of control to receive focus

lInitParam = lParam;       // initialization parameter

Parameters

hwndFocus

Value of wParam. Identifies the control to receive the default keyboard focus. Windows assigns the default keyboard focus only if the dialog box procedure returns TRUE.

lInitParam

Value of lParam. Specifies additional initialization data. This data is passed to Windows as the lParamInit parameter in a call to the CreateDialogIndirectParam, CreateDialogParam, DialogBoxIndirectParam, or DialogBoxParam function used to create the dialog box. This parameter is zero if any other dialog box creation function is used.

Return Values

The dialog box procedure should return TRUE to direct Windows to set the keyboard focus to the control given by hwndFocus. Otherwise, it should return FALSE to prevent Windows from setting the default keyboard focus.

Remarks

The control to receive the default keyboard focus is always the first control in the dialog box that is visible, not disabled, and that has the WS_TABSTOP style. When the dialog box procedure returns TRUE, Windows checks the control to ensure that the procedure has not disabled it. If it has been disabled, Windows sets the keyboard focus to the next control that is visible, not disabled, and has the WS_TABSTOP.

An application can return FALSE only if it has set the keyboard focus to one of the controls of the dialog box.

See Also

CreateDialogIndirectParam, CreateDialogParam, DialogBoxIndirectParam, DialogBoxParam, SetFocus


WM_INITMENU

The WM_INITMENU message is sent when a menu is about to become active. It occurs when the user clicks an item on the menu bar or presses a menu key. This allows the application to modify the menu before it is displayed.

WM_INITMENU

hmenuInit = (HMENU) wParam; // handle of menu to initialize

Parameters

hmenuInit

Value of wParam. Identifies the menu to be initialized.

Return Values

If an application processes this message, it should return zero.

Remarks

A WM_INITMENU message is sent only when a menu is first accessed; only one WM_INITMENU message is generated for each access. For example, moving the mouse across several menu items while holding down the button does not generate new messages. WM_INITMENU does not provide information about menu items.

See Also

WM_INITMENUPOPUP


WM_INITMENUPOPUP

The WM_INITMENUPOPUP message is sent when a drop-down menu or submenu is about to become active. This allows an application to modify the menu before it is displayed, without changing the entire menu.

WM_INITMENUPOPUP

hmenuPopup = (HMENU) wParam;         // handle of submenu

uPos = (UINT) LOWORD(lParam);        // submenu item position

fSystemMenu = (BOOL) HIWORD(lParam); // window menu flag

Parameters

hmenuPopup

Value of wParam. Identifies the drop-down menu or submenu.

uPos

Value of the low-order word of lParam. Specifies the zero-based relative position of the menu item that opens the drop-down menu or submenu.

fSystemMenu

Value of the high-order word of lParam. Specifies whether the drop-down menu is the window menu (also known as the System menu or the Control menu). If the menu is the window menu, this parameter is TRUE; otherwise, it is FALSE.

Return Values

If an application processes this message, it should return zero.

See Also

WM_INITMENU


WM_INPUTLANGCHANGE

The WM_INPUTLANGCHANGE message is sent to the topmost affected window after a task's locale has been changed. It should be used to make any application-specific settings and passed on to the DefWindowProc function to be passed on to any children.

WM_INPUTLANGCHANGE
charset = wParam;
hkl = (HKL) lParam;

Parameters

charset

Value of wParam. Specifies the character set of the new keyboard layout.

hkl

Value of lParam. Identifies the new keyboard layout.

Return Values

An application should return nonzero if it processes this message.

See Also

DefWindowProc, WM_INPUTLANGCHANGEREQUEST


WM_INPUTLANGCHANGEREQUEST

The WM_INPUTLANGCHANGEREQUEST message is posted to the application's top-level window when the user chooses an input language, either with an input language change hotkey or from the system languages menu. An application can accept the change by passing the message to the DefWindowProc function or reject the change (and prevent it from taking place) by returning immediately.

WM_INPUTLANGCHANGEREQUEST
fSysCharSet = (BOOL) wParam

hkl = (HKL) lParam;

Parameters

wParam

The lowest bit of this parameter is set if the handle of the keyboard layout can be used with the system character set. The other bits are reserved. For example, in the Russian-language version of Windows 95, this parameter has the low bit set for keyboard layout handles for English (US) and Russian, but cleared for other handles.

hkl

Value of lParam. Identifies the keyboard layout to switch to.

Return Values

This message is posted, not sent, to the application, so the return value is ignored. To accept the change, the application should pass the message on to DefWindowProc. To reject the change, the application should return zero without calling DefWindowProc.

See Also

DefWindowProc, WM_INPUTLANGCHANGE


WM_KEYDOWN

The WM_KEYDOWN message is posted to the window with the keyboard focus when a nonsystem key is pressed. A nonsystem key is a key that is pressed when the ALT key is not pressed.

WM_KEYDOWN

nVirtKey = (int) wParam;    // virtual-key code

lKeyData = lParam;          // key data

Parameters

nVirtKey

Value of wParam. Specifies the virtual-key code of the nonsystem key.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table:

Value	Description
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is always 0 for a WM_KEYDOWN message.
30	Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31	Specifies the transition state. The value is always 0 for a WM_KEYDOWN message.
Return Values

An application should return zero if it processes this message.

Default Action

If the F10 key is pressed, the DefWindowProc function sets an internal flag. When DefWindowProc receives the WM_KEYUP message, the function checks whether the internal flag is set and, if so, sends a WM_SYSCOMMAND message to the top-level window. The wParam parameter of the message is set to SC_KEYMENU.

Remarks

Because of the autorepeat feature, more than one WM_KEYDOWN message may be posted before a WM_KEYUP message is posted. The previous key state (bit 30) can be used to determine whether the WM_KEYDOWN message indicates the first down transition or a repeated down transition.

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

DefWindowProc, WM_CHAR, WM_KEYUP, WM_SYSCOMMAND


WM_KEYUP

The WM_KEYUP message is posted to the window with the keyboard focus when a nonsystem key is released. A nonsystem key is a key that is pressed when the ALT key is not pressed, or a keyboard key that is pressed when a window has the keyboard focus.

WM_KEYUP

nVirtKey = (int) wParam;    // virtual-key code

lKeyData = lParam;          // key data

Parameters

nVirtKey

Value of wParam. Specifies the virtual-key code of the nonsystem key.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table:

Value	Description
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key. The repeat count is always one for a WM_KEYUP message.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is always 0 for a WM_KEYUP message.
30	Specifies the previous key state. The value is always 1 for a WM_KEYUP message.
31	Specifies the transition state. The value is always 1 for a WM_KEYUP message.
Return Values

An application should return zero if it processes this message.

Default Action

The DefWindowProc function sends a WM_SYSCOMMAND message to the top-level window if the F10 key or the ALT key was released. The wParam parameter of the message is set to SC_KEYMENU.

Remarks

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

DefWindowProc, WM_KEYDOWN, WM_SYSCOMMAND


WM_KILLFOCUS

The WM_KILLFOCUS message is sent to a window immediately before it loses the keyboard focus.

WM_KILLFOCUS

hwndGetFocus = (HWND) wParam; // handle of window receiving focus

Parameters

hwndGetFocus

Value of wParam. Identifies the window that receives the keyboard focus (may be NULL).

Return Values

An application should return zero if it processes this message.

Remarks

If an application is displaying a caret, the caret should be destroyed at this point.

See Also

SetFocus, WM_SETFOCUS


WM_LBUTTONDBLCLK

The WM_LBUTTONDBLCLK message is posted when the user double-clicks the left mouse button while the cursor is in the client area of a window. If the mouse is not captured, the message is posted to the window beneath the cursor. Otherwise, the message is posted to the window that has captured the mouse.

WM_LBUTTONDBLCLK

fwKeys = wParam;        // key flags

xPos = LOWORD(lParam);  // horizontal position of cursor

yPos = HIWORD(lParam);  // vertical position of cursor

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Return Values

If an application processes this message, it should return zero.

Remarks

Only windows that have the CS_DBLCLKS style can receive WM_LBUTTONDBLCLK messages, which Windows generates whenever the user presses, releases, and again presses the left mouse button within the system’s double-click time limit. Double-clicking the left mouse button actually generates four messages: WM_LBUTTONDOWN, WM_LBUTTONUP, WM_LBUTTONDBLCLK, and WM_LBUTTONUP again.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, GetDoubleClickTime, MAKEPOINTS, POINTS, SetCapture, SetDoubleClickTime, WM_LBUTTONDOWN, WM_LBUTTONUP


WM_LBUTTONDOWN

The WM_LBUTTONDOWN message is posted when the user presses the left mouse button while the cursor is in the client area of a window. If the mouse is not captured, the message is posted to the window beneath the cursor. Otherwise, the message is posted to the window that has captured the mouse.

WM_LBUTTONDOWN

fwKeys = wParam;        // key flags

xPos = LOWORD(lParam);  // horizontal position of cursor

yPos = HIWORD(lParam);  // vertical position of cursor

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Return Values

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, MAKEPOINTS, POINTS, SetCapture, WM_LBUTTONDBLCLK, WM_LBUTTONUP


WM_LBUTTONUP

The WM_LBUTTONUP message is posted when the user releases the left mouse button while the cursor is in the client area of a window. If the mouse is not captured, the message is posted to the window beneath the cursor. Otherwise, the message is posted to the window that has captured the mouse.

WM_LBUTTONUP

fwKeys = wParam;        // key flags

xPos = LOWORD(lParam);  // horizontal position of cursor

yPos = HIWORD(lParam);  // vertical position of cursor

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Return Values

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, MAKEPOINTS, POINTS, SetCapture, WM_LBUTTONDBLCLK, WM_LBUTTONDOWN


WM_MBUTTONDBLCLK

The WM_MBUTTONDBLCLK message is posted when the user double-clicks the middle mouse button while the cursor is in the client area of a window. If the mouse is not captured, the message is posted to the window beneath the cursor. Otherwise, the message is posted to the window that has captured the mouse.

WM_MBUTTONDBLCLK

fwKeys = wParam;        // key flags

xPos = LOWORD(lParam);  // horizontal position of cursor

yPos = HIWORD(lParam);  // vertical position of cursor

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Return Values

If an application processes this message, it should return zero.

Remarks

Only windows that have the CS_DBLCLKS style can receive WM_MBUTTONDBLCLK messages, which Windows generates whenever the user presses, releases, and again presses the middle mouse button within the system’s double-click time limit. Double-clicking the middle mouse button actually generates four messages: WM_MBUTTONDOWN, WM_MBUTTONUP, WM_MBUTTONDBLCLK, and WM_MBUTTONUP again.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, GetDoubleClickTime, MAKEPOINTS, POINTS, SetCapture, SetDoubleClickTime, WM_MBUTTONDOWN, WM_MBUTTONUP


WM_MBUTTONDOWN

The WM_MBUTTONDOWN message is posted when the user presses the middle mouse button while the cursor is in the client area of a window. If the mouse is not captured, the message is posted to the window beneath the cursor. Otherwise, the message is posted to the window that has captured the mouse.

WM_MBUTTONDOWN

fwKeys = wParam;        // key flags

xPos = LOWORD(lParam);  // horizontal position of cursor

yPos = HIWORD(lParam);  // vertical position of cursor

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Return Values

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, MAKEPOINTS, POINTS, SetCapture, WM_MBUTTONDBLCLK, WM_MBUTTONUP


WM_MBUTTONUP

The WM_MBUTTONUP message is posted when the user releases the middle mouse button while the cursor is in the client area of a window. If the mouse is not captured, the message is posted to the window beneath the cursor. Otherwise, the message is posted to the window that has captured the mouse.

WM_MBUTTONUP

fwKeys = wParam;        // key flags

xPos = LOWORD(lParam);  // horizontal position of cursor

yPos = HIWORD(lParam);  // vertical position of cursor

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, MAKEPOINTS, POINTS, SetCapture, WM_MBUTTONDBLCLK, WM_MBUTTONDOWN


WM_MDIACTIVATE

An application sends the WM_MDIACTIVATE message to a multiple document interface (MDI) client window to instruct the client window to activate a different MDI child window. As the client window processes this message, it sends WM_MDIACTIVATE to the child window being deactivated and to the child window being activated.

WM_MDIACTIVATE

// Message sent to MDI client

wParam = (WPARAM) (HWND) hwndChildAct; // child to activate

lParam = 0;                            // not used; must be zero

// Message received by MDI child

hwndChildDeact = (HWND) wParam;        // child being deactivated

hwndChildAct = (HWND) lParam;          // child being activated

Parameters

In messages sent to an MDI client window:

hwndChildAct

Value of wParam. Identifies the MDI child window to be activated.

In messages received by an MDI child window:

hwndChildDeact

Value of wParam. Identifies the MDI child window being deactivated.

hwndChildAct

Value of lParam. Identifies the MDI child window being activated.

Return Values

If an application sends this message to an MDI client window, the return value is zero. An MDI child window should return zero if it processes this message.

Remarks

An MDI child window is activated independently of the MDI frame window. When the frame window becomes active, the child window last activated by using the WM_MDIACTIVATE message receives the WM_NCACTIVATE message to draw an active window frame and title bar; the child window does not receive another WM_MDIACTIVATE message.

See Also

WM_MDIGETACTIVE, WM_MDINEXT, WM_NCACTIVATE


WM_MDICASCADE

An application sends the WM_MDICASCADE message to a multiple document interface (MDI) client window to arrange all its child windows in a cascade format.

WM_MDICASCADE

wParam = (WPARAM) (UINT) fuCascade;  // cascade flag

lParam = 0;                          // not used; must be zero

Parameters

fuCascade

Value of wParam. Specifies a cascade flag. The only flag currently available, MDITILE_SKIPDISABLED, prevents disabled MDI child windows from being cascaded.

Return Values

If the message succeeds, the return value is TRUE.

If the message fails, the return value is FALSE.

See Also

WM_MDIICONARRANGE, WM_MDITILE


WM_MDICREATE

An application sends the WM_MDICREATE message to a multiple document interface (MDI) client window to create an MDI child window.

WM_MDICREATE

wParam = 0;                                     // not used; must be zero

lParam = (LPARAM) (LPMDICREATESTRUCT) lpmdic;   // creation data

Parameters

lpmdic

Points to an MDICREATESTRUCT structure containing information that Windows uses to create the MDI child window.

Return Values

If the message succeeds, the return value is the handle of the new child window.

If the message fails, the return value is NULL.

Remarks

The MDI child window is created with the style bits WS_CHILD, WS_CLIPSIBLINGS, WS_CLIPCHILDREN, WS_SYSMENU, WS_CAPTION, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX, plus additional style bits specified in the MDICREATESTRUCT structure to which the lpmdic parameter points. Windows adds the title of the new child window to the Window menu of the frame window. An application should use this message to create all child windows of the client window.

If an MDI client window receives any message that changes the activation of its child windows while the active child window is maximized, Windows restores the active child window and maximizes the newly activated child window.

When an MDI child window is created, Windows sends the WM_CREATE message to the window. The lParam parameter of the WM_CREATE message contains a pointer to a CREATESTRUCT structure. The lpCreateParams member of this structure contains a pointer to the MDICREATESTRUCT structure passed with the WM_MDICREATE message that created the MDI child window.

An application should not send a second WM_MDICREATE message while a WM_MDICREATE message is still being processed. For example, it should not send a WM_MDICREATE message while an MDI child window is processing its WM_MDICREATE message.

See Also

CreateMDIWindow, CREATESTRUCT, MDICREATESTRUCT, WM_CREATE, WM_MDIDESTROY


WM_MDIDESTROY

An application sends the WM_MDIDESTROY message to a multiple document interface (MDI) client window to close an MDI child window.

WM_MDIDESTROY

wParam = (WPARAM) (HWND) hwndChild; // handle of child to close

lParam = 0;                         // not used; must be zero

Parameters

hwndChild

Value of wParam. Identifies the MDI child window to be closed.

Return Values

This message always returns zero.

Remarks

This message removes the title of the MDI child window from the MDI frame window and deactivates the child window. An application should use this message to close all MDI child windows.

If an MDI client window receives a message that changes the activation of its child windows and the active MDI child window is maximized, Windows restores the active child window and maximizes the newly activated child window.

See Also

WM_MDICREATE


WM_MDIGETACTIVE

An application sends the WM_MDIGETACTIVE message to a multiple document interface (MDI) client window to retrieve the handle of the active MDI child window.

WM_MDIGETACTIVE

wParam = 0;                      // not used; must be zero

lParam = (LPBOOL) lpfMaximized;  // optional pointer to maximized state flag

Parameters

lpfMaximized

Value of lparam. This is an optional pointer to a maximized state flag variable. If lpfMaximized is non-NULL, the BOOL it points to is set to indicate the maximized state of the MDI child window. TRUE indicates that the window is maximized, FALSE indicates that it is not. This is equivalent to the indication supplied by the high-order word of the return value of the WM_MDIGETACTIVE message under Windows version 3.x. If lpfMaximized is NULL, the parameter is ignored.

Return Values

The return value is the handle of the active MDI child window.

Remarks

Note carefully a change in how this message indicates maximization. In Windows version 3.x, the message return value includes a flag indicating whether the MDI child window is maximized. In the Win32 application programming interface (API), the return value does not include this flag. In Win32, the MDI child window’s maximized state is indicated by setting a BOOL variable via the optional parameter in lParam, lpfMaximized.


WM_MDIICONARRANGE

An application sends the WM_MDIICONARRANGE message to a multiple document interface (MDI) client window to arrange all minimized MDI child windows. It does not affect child windows that are not minimized.

WM_MDIICONARRANGE

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

See Also

WM_MDICASCADE, WM_MDITILE


WM_MDIMAXIMIZE

An application sends the WM_MDIMAXIMIZE message to a multiple document interface (MDI) client window to maximize an MDI child window. Windows resizes the child window to make its client area fill the client window. Windows places the child window’s window menu icon in the rightmost position of the frame window’s menu bar, and places the child window’s restore icon in the leftmost position. Windows also appends the title bar text of the child window to that of the frame window.

WM_MDIMAXIMIZE

wParam = (WPARAM) (HWND) hwndMax; // handle of child to maximize

lParam = 0;                       // not used; must be zero

Parameters

hwndMax

Value of wParam. Identifies the MDI child window to be maximized.

Return Values

The return value is always zero.

Remarks

If an MDI client window receives any message that changes the activation of its child windows while the currently active MDI child window is maximized, Windows restores the active child window and maximizes the newly activated child window.

See Also

WM_MDIRESTORE


WM_MDINEXT

An application sends the WM_MDINEXT message to a multiple document interface (MDI) client window to activate the next or previous child window.

WM_MDINEXT

wParam = (WPARAM) (HWND) hwndChild; // handle of child

lParam = (LPARAM) fNext;            // next or previous child

Parameters

hwndChild

Value of wParam. Identifies the MDI child window. Windows activates the child window that is immediately before or after the given child window, depending on the value of the fNext parameter. If the hwndChild parameter is NULL, Windows activates the child window that is immediately before or after the currently active child window.

fNext

Value of lParam. If this parameter is zero, Windows activates the next MDI child window and places the child window identified by the hwndChild parameter behind all other child windows. If this parameter is nonzero, Windows activates the previous child window, placing it in front of the child window identified by hwndChild.

Return Values

The return value is always zero.

Remarks

If an MDI client window receives any message that changes the activation of its child windows while the active MDI child window is maximized, Windows restores the active child window and maximizes the newly activated child window.

See Also

WM_MDIACTIVATE, WM_MDIGETACTIVE


WM_MDIREFRESHMENU

An application sends the WM_MDIREFRESHMENU message to a multiple document interface (MDI) client window to refresh the Window menu of the MDI frame window.

WM_MDIREFRESHMENU

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

If the message succeeds, the return value is the handle of the frame window menu.

If the message fails, the return value is NULL.

Remarks

After sending this message, an application must call the DrawMenuBar function to update the menu bar.

See Also

DrawMenuBar, WM_MDISETMENU


WM_MDIRESTORE

An application sends the WM_MDIRESTORE message to a multiple document interface (MDI) client window to restore an MDI child window from maximized or minimized size.

WM_MDIRESTORE

wParam = (WPARAM) (HWND) hwndRes; // handle of child to restore

lParam = 0;                       // not used; must be zero

Parameters

hwndRes

Value of wParam. Identifies the MDI child window to be restored.

Return Values

The return value is always zero.

See Also

WM_MDIMAXIMIZE


WM_MDISETMENU

An application sends the WM_MDISETMENU message to a multiple document interface (MDI) client window to replace the entire menu of an MDI frame window, to replace the Window menu of the frame window, or both.

WM_MDISETMENU

wParam = (WPARAM) (HMENU) hmenuFrame;  // handle of frame menu

lParam = (LPARAM) (HMENU) hmenuWindow; // handle of Window menu

Parameters

hmenuFrame

Value of wParam. Identifies the new frame window menu. If this parameter is NULL, the frame window menu is not changed.

hmenuWindow

Value of lParam. Identifies the new Window menu. If this parameter is NULL, the Window menu is not changed.

Return Values

If the message succeeds, the return value is the handle of the old frame window menu.

If the message fails, the return value is zero.

Remarks

After sending this message, an application must call the DrawMenuBar function to update the menu bar.

If this message replaces the Window menu, the MDI child window menu items are removed from the previous Window menu and added to the new Window menu.

If an MDI child window is maximized and this message replaces the MDI frame window menu, the System menu icon and restore icon are removed from the previous frame window menu and added to the new frame window menu.

See Also

DrawMenuBar, WM_MDIREFRESHMENU


WM_MDITILE

An application sends the WM_MDITILE message to a multiple document interface (MDI) client window to arrange all of its MDI child windows in a tile format.

WM_MDITILE

wParam = (WPARAM) (UINT) fuTile; // tiling flag

lParam = 0;                      // not used; must be zero

Parameters

fuTile

Specifies a tiling flag. This parameter can be one of the following values:

Value	Meaning
MDITILE_HORIZONTAL	Tiles MDI child windows so that they are wide rather than tall.
MDITILE_SKIPDISABLED	Prevents disabled MDI child windows from being tiled.
MDITILE_VERTICAL	Tiles MDI child windows so that they are tall rather than wide.
Return Values

If the message succeeds, the return value is TRUE.

If the message fails, the return value is FALSE.

See Also

WM_MDICASCADE, WM_MDIICONARRANGE


WM_MEASUREITEM

The WM_MEASUREITEM message is sent to the owner window of an owner-drawn button, combo box, list box, list view control, or menu item when the control or menu is created.

WM_MEASUREITEM

idCtl = (UINT) wParam;                // control identifier

lpmis = (LPMEASUREITEMSTRUCT) lParam; // item-size information

Parameters

idCtl

Value of wParam. Contains the value of the CtlID member of the MEASUREITEMSTRUCT structure pointed to by the lpmis parameter. This value identifies the control that sent the WM_MEASUREITEM message.

If the value is zero, the message was sent by a menu. If the value is nonzero, the message was sent by a combo box or by a list box. If the value is nonzero, and the value of the itemID member of the MEASUREITEMSTRUCT pointed to by lpmis is (UINT) −1, the message was sent by a combo edit field.

lpmis

Value of lParam. Points to a MEASUREITEMSTRUCT structure that contains the dimensions of the owner-drawn control or menu item.

Return Values

If an application processes this message, it should return TRUE.

Remarks

When the owner window receives the WM_MEASUREITEM message, the owner fills in the MEASUREITEMSTRUCT structure pointed to by the lParam parameter of the message and returns; this informs Windows of the dimensions of the control. If a list box or combo box is created with the LBS_OWNERDRAWVARIABLE or CBS_OWNERDRAWVARIABLE style, this message is sent to the owner for each item in the control; otherwise, this message is sent once.

Windows sends the WM_MEASUREITEM message to the owner window of combo boxes and list boxes created with the OWNERDRAWFIXED style before sending the WM_INITDIALOG message. As a result, when the owner receives this message, Windows has not yet determined the height and width of the font used in the control; function calls and calculations requiring these values should occur in the main function of the application or library.

See Also

MEASUREITEMSTRUCT, WM_INITDIALOG


WM_MENUCHAR

The WM_MENUCHAR message is sent when a menu is active and the user presses a key that does not correspond to any mnemonic or accelerator key. This message is sent to the window that owns the menu.

WM_MENUCHAR

chUser = (char) LOWORD(wParam); // ASCII character

fuFlag = (UINT) HIWORD(wParam); // menu flag

hmenu = (HMENU) lParam;         // handle of menu

Parameters

chUser

Value of the low-order word of wParam. Specifies the ASCII character that corresponds to the key the user pressed.

fuFlag

Value of the high-order word of wParam. Specifies the type of the active menu. This parameter can be one of the following values:

Value	Meaning
MF_POPUP	drop-down menu, submenu, or shortcut menu
MF_SYSMENU	window menu (System menu or Control menu)
hmenu

Value of lParam. Identifies the active menu.

Return Values

An application that processes this message should return one of the following values in the high-order word of the return value:

Value	Meaning
0	Informs Windows that it should discard the character the user pressed and create a short beep on the system speaker.
1	Informs Windows that it should close the active menu.
2	Informs Windows that the low-order word of the return value specifies the zero-based relative position of a menu item. This item is selected by Windows.
Remarks

The low-order word is ignored if the high-order word contains 0 or 1. An application should process this message when an accelerator is used to select a menu item that displays a bitmap.


WM_MENUSELECT

The WM_MENUSELECT message is sent to a menu’s owner window when the user selects a menu item.

WM_MENUSELECT

uItem = (UINT) LOWORD(wParam);   // menu item or submenu index

fuFlags = (UINT) HIWORD(wParam); // menu flags

hmenu = (HMENU) lParam;          // handle of menu clicked

Parameters

uItem

Value of the low-order word of wParam. If the selected item is a command item, this parameter contains the identifier of the menu item. If the selected item opens a drop-down menu or submenu, this parameter contains the menu index of the drop-down menu or submenu in the main menu, and the hMenu parameter then contains the handle of the main (clicked) menu; use the GetSubMenu function to get the menu handle of the drop-down menu or submenu.

fuFlags

Value of the high-order word of wParam. Specifies one or more menu flags. This parameter can be a combination of the following values:

Value	Description
MF_BITMAP	Item displays a bitmap.
MF_CHECKED	Item is checked.
MF_DISABLED	Item is disabled.
MF_GRAYED	Item is grayed.
MF_HILITE	Item is highlighted.
MF_MOUSESELECT	Item is selected with the mouse.
MF_OWNERDRAW	Item is an owner-drawn item.
MF_POPUP	Item opens a drop-down menu or submenu.
MF_SYSMENU	Item is contained in the window menu (also known as the System menu or Control menu). The hmenu parameter identifies the window menu associated with the message.
hmenu

Value of lParam. Identifies the menu that was clicked.

Return Values

If an application processes this message, it should return zero.

Remarks

If the fuFlags parameter contains 0xFFFF and the hmenu parameter contains NULL, Windows has closed the menu.

Do not use the value −1 for fuFlags. That is because fuFlags is specified as (UINT) HIWORD(wParam). If HIWORD(wParam) were 0xFFFF, fuFlags (because of the UINT cast) would be 0x0000FFFF, not −1.

See Also

GetSubMenu


WM_MOUSEACTIVATE

The WM_MOUSEACTIVATE message is sent when the cursor is in an inactive window and the user presses a mouse button. The parent window receives this message only if the child window passes it to the DefWindowProc function.

WM_MOUSEACTIVATE

hwndTopLevel = (HWND) wParam;       // handle of top-level parent

nHittest = (INT) LOWORD(lParam);    // hit-test value

uMsg =    (UINT) HIWORD(lParam);    // mouse message

Parameters

hwndTopLevel

Value of wParam. Identifies the top-level parent window of the window being activated.

nHittest

Value of the low-order word of lParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

uMsg

Value of the high-order word of lParam. Specifies the identifier of the mouse message generated when the user pressed a mouse button. The mouse message is either discarded or posted to the window, depending on the return value.

Return Values

The return value specifies whether the window should be activated and whether the identifier of the mouse message should be discarded. It must be one of the following values:

Value	Meaning
MA_ACTIVATE	Activates the window, and does not discard the mouse message.
MA_ACTIVATEANDEAT	Activates the window, and discards the mouse message.
MA_NOACTIVATE	Does not activate the window, and does not discard the mouse message.
MA_NOACTIVATEANDEAT	Does not activate the window, but discards the mouse message.
Default Action

The DefWindowProc function passes the message to a child window’s parent window before any processing occurs. The parent window determines whether to activate the child window. If it activates the child window, the parent window should return TRUE to prevent the system from processing the message further.

See Also

DefWindowProc, WM_NCHITTEST


WM_MOUSEMOVE

The WM_MOUSEMOVE message is posted to a window when the cursor moves. If the mouse is not captured, the message is posted to the window that contains the cursor. Otherwise, the message is posted to the window that has captured the mouse.

WM_MOUSEMOVE

fwKeys = wParam;        // key flags

xPos = LOWORD(lParam);  // horizontal position of cursor

yPos = HIWORD(lParam);  // vertical position of cursor

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Remarks

The MAKEPOINTS macro can be used to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, MAKEPOINTS, POINTS, SetCapture


WM_MOUSEWHEEL [New - Windows NT]
WM_MOUSEWHEEL

[New - Windows NT]

The WM_MOUSEWHEEL message is sent to the focus window when the mouse wheel is rotated. The DefWindowProc function propagates the message to the window’s parent. There should be no internal forwarding of the message, since DefWindowProc propagates it up the parent chain until it finds a window that processes it.

WM_MOUSEWHEEL

fwKeys = LOWORD(wParam);    // key flags

zDelta = (short) HIWORD(wParam);    // wheel rotation

xPos = (short) LOWORD(lParam);    // horizontal position of pointer

yPos = (short) HIWORD(lParam);    // vertical position of pointer

Parameters

fwKeys

Value of the low-order word of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
zDelta

The value of the high-order word of wParam. Indicates the distance that the wheel is rotated, expressed in multiples or divisions of WHEEL_DELTA, which is 120. A positive value indicates that the wheel was rotated forward, away from the user; a negative value indicates that the wheel was rotated backward, toward the user.

xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the pointer, relative to the upper-left corner of the screen.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the pointer, relative to the upper-left corner of the screen.

Remarks

The zDelta parameter will be a multiple of WHEEL_DELTA, which is set at 120. This is the threshold for action to be taken, and one such action (for example, scrolling one increment) should occur for each delta.

The delta was set to 120 to allow Microsoft or other vendors to build finer-resolution wheels in the future, including perhaps a freely-rotating wheel with no notches. The expectation is that such a device would send more messages per rotation, but with a smaller value in each message. To support this possibility, you should either add the incoming delta values until WHEEL_DELTA is reached (so for a given delta-rotation you get the same response), or scroll partial lines in response to the more frequent messages. You could also choose your scroll granularity and accumulate deltas until it is reached.

See Also

GetSystemMetrics, mouse_event, SystemParametersInfo


WM_MOVE

The WM_MOVE message is sent after a window has been moved.

WM_MOVE

xPos = (int) LOWORD(lParam);    // horizontal position

yPos = (int) HIWORD(lParam);    // vertical position

Parameters

xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the upper-left corner of the client area of the window.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the upper-left corner of the client area of the window.

Return Values

If an application processes this message, it should return zero.

Remarks

The xPos and yPos parameters are given in screen coordinates for overlapped and pop-up windows and in parent-client coordinates for child windows.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

MAKEPOINTS, POINTS


WM_MOVING

The WM_MOVING message is sent to a window that the user is moving. By processing this message, an application can monitor the size and position of the drag rectangle and, if needed, change its size or position.

fwSide = wParam;	// edge of window to be moved

lprc = (LPRECT) lParam;	// screen coordinates of drag rectangle

Parameters

fwSide

Value of wParam. Indicates which edge of the window is being moved. This parameter can be a combination of the following values:

Value	Meaning
WMSZ_BOTTOM	Bottom edge
WMSZ_BOTTOMLEFT	Bottom-left corner
WMSZ_BOTTOMRIGHT	Bottom-right corner
WMSZ_LEFT	Left edge
WMSZ_RIGHT	Right edge
WMSZ_TOP	Top edge
WMSZ_TOPLEFT	Top-left corner
WMSZ_TOPRIGHT	Top-right corner
lprc

Value of lParam. Address of a RECT structure with the screen coordinates of the drag rectangle. To change the size or position of the drag rectangle, an application must change the members of this structure.

Return Values

An application should return TRUE if it processes this message.

See Also

RECT, WM_MOVE, WM_SIZING


WM_NCACTIVATE

The WM_NCACTIVATE message is sent to a window when its nonclient area needs to be changed to indicate an active or inactive state.

WM_NCACTIVATE

fActive = (BOOL) wParam;	// new state of the title bar or icon

Parameters

fActive

Value of wParam. Specifies when a title bar or icon needs to be changed to indicate an active or inactive state. If an active title bar or icon is to be drawn, the fActive parameter is TRUE. It is FALSE for an inactive title bar or icon.

Return Values

When the fActive parameter is FALSE, an application should return TRUE to indicate that Windows should proceed with the default processing, or it should return FALSE to prevent the title bar or icon from being deactivated. When fActive is TRUE, the return value is ignored.

Default Action

The DefWindowProc function draws the title bar or icon title in its active colors when the fActive parameter is TRUE and in its inactive colors when fActive is FALSE.

See Also

DefWindowProc


WM_NCCALCSIZE

The WM_NCCALCSIZE message is sent when the size and position of a window’s client area must be calculated. By processing this message, an application can control the content of the window’s client area when the size or position of the window changes.

WM_NCCALCSIZE

fCalcValidRects = (BOOL) wParam;        // valid area flag

lpncsp = (LPNCCALCSIZE_PARAMS) lParam;  // points to size calculation data

   or

lpncsp = (LPRECT) lParam;               // points to new window coordinates

Parameters

fCalcValidRects

Value of wParam. A Boolean value that, if TRUE, specifies that the application should indicate which part of the client area contains valid information. The operating system copies the valid information to the specified area within the new client area. Also, if this parameter is TRUE, lParam points to an NCCALCSIZE_PARAMS structure.

If this parameter is FALSE, the application does not need to indicate the valid part of the client area. Also, if this parameter is FALSE, lParam points to a RECT structure.

lpncsp

Value of lParam.

If wParam  is TRUE, lParam points to an NCCALCSIZE_PARAMS structure that contains information an application can use to calculate the new size and position of the client rectangle.

If wParam  is FALSE, lParam points to a RECT structure that contains the new coordinates of the window that has been moved or resized. This is equivalent to rgrc[0] of an NCCALCSIZE_PARAMS structure.

Return Values

If the fCalcValidRects parameter is FALSE, the application should return zero.

If fCalcValidRects is TRUE, the application can return zero or a valid combination of the following values:

Value	Meaning
WVR_ALIGNTOP, WVR_ALIGNLEFT, WVR_ALIGNBOTTOM, WVR_ALIGNRIGHT
	These values, used in combination, specify that the client area of the window is to be preserved and aligned appropriately relative to the new position of the window. For example, to align the client area to the lower-left corner, return the WVR_ALIGNLEFT and WVR_ALIGNTOP values.
WVR_HREDRAW, WVR_VREDRAW
	These values, used in combination with any other values, cause the window to be completely redrawn if the client rectangle changes size horizontally or vertically. These values are similar to the CS_HREDRAW and CS_VREDRAW class styles.
WVR_REDRAW
	This value causes the entire window to be redrawn. It is a combination of WVR_HREDRAW and WVR_VREDRAW values.
WVR_VALIDRECTS
	This value indicates that, upon return from WM_NCCALCSIZE, the rectangles specified by the rgrc[1] and rgrc[2] members of the NCCALCSIZE_PARAMS structure contain valid source and destination area rectangles, respectively. Windows combines these rectangles to calculate the area of the window to be preserved. Windows copies any part of the window image that is within the source rectangle and clips the image to the destination rectangle. Both rectangles are in parent-relative or screen-relative coordinates.
	This return value allows an application to implement more elaborate client-area preservation strategies, such as centering or preserving a subset of the client area.
If fCalcValidRects is TRUE and an application returns zero, the old client area is preserved and is aligned with the upper-left corner of the new client area.

Default Action

The window may be redrawn, depending on whether the CS_HREDRAW or CS_VREDRAW class style is specified. This is the default, backward-compatible processing of this message by the DefWindowProc function (in addition to the usual client rectangle calculation described in the preceding table).

See Also

DefWindowProc, MoveWindow, SetWindowPos, NCCALCSIZE_PARAMS, RECT


WM_NCCREATE

The WM_NCCREATE message is sent prior to the WM_CREATE message when a window is first created.

WM_NCCREATE

lpcs = (LPCREATESTRUCT) lParam; // initialization data

Parameters

lpcs

Value of wParam. Points to the CREATESTRUCT structure for the window.

Return Values

If an application processes this message, it should return TRUE to continue creation of the window. If the application returns FALSE, the CreateWindow or CreateWindowEx function will return a NULL handle.

Default Action

The DefWindowProc function returns TRUE.

See Also

CreateWindow, CreateWindowEx, DefWindowProc, CREATESTRUCT, WM_CREATE


WM_NCDESTROY

The WM_NCDESTROY message informs a window that its nonclient area is being destroyed. The DestroyWindow function sends the WM_NCDESTROY message to the window following the WM_DESTROY message. WM_DESTROY is used to free the allocated memory object associated with the window.

WM_NCDESTROY

Parameters

This message has no parameters.

Return Values

If an application processes this message, it should return zero.

Remarks

This message frees any memory internally allocated for the window.

See Also

DestroyWindow, WM_DESTROY, WM_NCCREATE


WM_NCHITTEST

The WM_NCHITTEST message is sent to a window when the cursor moves, or when a mouse button is pressed or released. If the mouse is not captured, the message is sent to the window beneath the cursor. Otherwise, the message is posted to the window that has captured the mouse.

WM_NCHITTEST

xPos = LOWORD(lParam);  // horizontal position of cursor

yPos = HIWORD(lParam);  // vertical position of cursor

Parameters

xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the screen.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the screen.

Return Values

The return value of the DefWindowProc function is one of the following values, indicating the position of the cursor hot spot:

Value	Location of hot spot
HTBORDER	In the border of a window that does not have a sizing border
HTBOTTOM	In the lower horizontal border of a window
HTBOTTOMLEFT	In the lower-left corner of a window border
HTBOTTOMRIGHT	In the lower-right corner of a window border
HTCAPTION	In a title bar
HTCLIENT	In a client area
HTERROR	On the screen background or on a dividing line between windows (same as HTNOWHERE, except that the DefWindowProc function produces a system beep to indicate an error)
HTGROWBOX	In a size box (same as HTSIZE)
HTHSCROLL	In a horizontal scroll bar
HTLEFT	In the left border of a window
HTMENU	In a menu
HTNOWHERE	On the screen background or on a dividing line between windows
HTREDUCE	In a Minimize button
HTRIGHT	In the right border of a window
HTSIZE	In a size box (same as HTGROWBOX)
HTSYSMENU	In a System menu or in a Close button in a child window
HTTOP	In the upper horizontal border of a window
HTTOPLEFT	In the upper-left corner of a window border
HTTOPRIGHT	In the upper right corner of a window border
HTTRANSPARENT	In a window currently covered by another window
HTVSCROLL	In the vertical scroll bar
HTZOOM	In a Maximize button
Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

DefWindowProc, MAKEPOINTS, POINTS


WM_NCLBUTTONDBLCLK

The WM_NCLBUTTONDBLCLK message is posted when the user double-clicks the left mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

WM_NCLBUTTONDBLCLK

nHittest = (INT) wParam;    // hit-test value

pts = MAKEPOINTS(lParam);   // position of cursor

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Values

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function tests the given point to find out the location of the cursor and performs the appropriate action. If appropriate, DefWindowProc sends the WM_SYSCOMMAND message to the window.

Remarks

A window need not have the CS_DBLCLKS style to receive WM_NCLBUTTONDBLCLK messages.

Windows generates a WM_NCLBUTTONDBLCLK message when the user presses, releases, and again presses the left mouse button within the system’s double-click time limit. Double-clicking the left mouse button actually generates four messages: WM_NCLBUTTONDOWN, WM_NCLBUTTONUP, WM_NCLBUTTONDBLCLK, and WM_NCLBUTTONUP again.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCLBUTTONDOWN, WM_NCLBUTTONUP, WM_SYSCOMMAND


WM_NCLBUTTONDOWN

The WM_NCLBUTTONDOWN message is posted when the user presses the left mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

WM_NCLBUTTONDOWN

nHittest = (INT) wParam;    // hit-test value

pts = MAKEPOINTS(lParam);   // position of cursor

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Values

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function tests the given point to find out the location of the cursor and performs the appropriate action. If appropriate, DefWindowProc sends the WM_SYSCOMMAND message to the window.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCLBUTTONDBLCLK, WM_NCLBUTTONUP, WM_SYSCOMMAND


WM_NCLBUTTONUP

The WM_NCLBUTTONUP message is posted when the user releases the left mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

WM_NCLBUTTONUP

nHittest = (INT) wParam;    // hit-test value

pts = MAKEPOINTS(lParam);   // mouse-cursor coordinates

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Values

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function tests the given point to find out the location of the cursor and performs the appropriate action. If appropriate, DefWindowProc sends the WM_SYSCOMMAND message to the window.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCLBUTTONDBLCLK, WM_NCLBUTTONDOWN, WM_SYSCOMMAND


WM_NCMBUTTONDBLCLK

The WM_NCMBUTTONDBLCLK message is posted when the user double-clicks the middle mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

WM_NCMBUTTONDBLCLK

nHittest = (INT) wParam;    // hit-test value

pts = MAKEPOINTS(lParam);   // position of cursor

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Values

If an application processes this message, it should return zero.

Remarks

A window need not have the CS_DBLCLKS style to receive WM_NCMBUTTONDBLCLK messages.

Windows generates a WM_NCMBUTTONDBLCLK message when the user presses, releases, and again presses the middle mouse button within the system’s double-click time limit. Double-clicking the middle mouse button actually generates four messages: WM_NCMBUTTONDOWN, WM_NCMBUTTONUP, WM_NCMBUTTONDBLCLK, and WM_NCMBUTTONUP again.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCMBUTTONDOWN, WM_NCMBUTTONUP, WM_SYSCOMMAND


WM_NCMBUTTONDOWN

The WM_NCMBUTTONDOWN message is posted when the user presses the middle mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

WM_NCMBUTTONDOWN

nHittest = (INT) wParam;    // hit-test value

pts = MAKEPOINTS(lParam);   // position of cursor

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Values

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCMBUTTONDBLCLK, WM_NCMBUTTONUP, WM_SYSCOMMAND


WM_NCMBUTTONUP

The WM_NCMBUTTONUP message is posted when the user releases the middle mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

WM_NCMBUTTONUP

nHittest = (INT) wParam;    // hit-test value

pts = MAKEPOINTS(lParam);   // position of cursor

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Values

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCMBUTTONDBLCLK, WM_NCMBUTTONDOWN, WM_SYSCOMMAND


WM_NCMOUSEMOVE

The WM_NCMOUSEMOVE message is posted to a window when the cursor is moved within the nonclient area of the window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

WM_NCMOUSEMOVE

nHittest = (INT) wParam;    // hit-test value

pts = MAKEPOINTS(lParam);   // position of cursor

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Values

If an application processes this message, it should return zero.

Remarks

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_SYSCOMMAND


WM_NCPAINT

An application sends the WM_NCPAINT message to a window when its frame must be painted.

WM_NCPAINT

hrgn = (HRGN) wParam;   // handle of update region

Parameters

hrgn

Value of wParam. Identifies the update region of the window. The update region is clipped to the window frame.

Return Values

An application should return zero if it processes this message.

Remarks

The DefWindowProc function paints the window frame.

An application can intercept this message and paint its own custom window frame. The clipping region for a window is always rectangular, even if the shape of the frame is altered.

See Also

DefWindowProc, GetWindowDC, WM_PAINT


WM_NCRBUTTONDBLCLK

The WM_NCRBUTTONDBLCLK message is posted when the user double-clicks the right mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

WM_NCRBUTTONDBLCLK

nHittest = (INT) wParam;    // hit-test value

pts = MAKEPOINTS(lParam);   // position of cursor

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Values

If an application processes this message, it should return zero.

Remarks

A window need not have the CS_DBLCLKS style to receive WM_NCRBUTTONDBLCLK messages.

Windows generates a WM_NCRBUTTONDBLCLK message when the user presses, releases, and again presses the right mouse button within the system’s double-click time limit. Double-clicking the right mouse button actually generates four messages: WM_NCRBUTTONDOWN, WM_NCRBUTTONUP, WM_NCRBUTTONDBLCLK, and WM_NCRBUTTONUP again.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCRBUTTONDOWN, WM_NCRBUTTONUP, WM_SYSCOMMAND


WM_NCRBUTTONDOWN

The WM_NCRBUTTONDOWN message is posted when the user presses the right mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

WM_NCRBUTTONDOWN

nHittest = (INT) wParam;    // hit-test value

pts = MAKEPOINTS(lParam);   // position of cursor

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Values

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCRBUTTONDBLCLK, WM_NCRBUTTONUP, WM_SYSCOMMAND


WM_NCRBUTTONUP

The WM_NCRBUTTONUP message is posted when the user releases the right mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

WM_NCRBUTTONUP

nHittest = (INT) wParam;    // hit-test value

pts = MAKEPOINTS(lParam);   // position of cursor

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Values

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCRBUTTONDBLCLK, WM_NCRBUTTONDOWN, WM_SYSCOMMAND


WM_NEXTDLGCTL

The WM_NEXTDLGCTL message is sent to a dialog box procedure to set the keyboard focus to a different control in the dialog box.

WM_NEXTDLGCTL

wCtlFocus = wParam;              // identifies control for focus

fHandle = (BOOL) LOWORD(lParam); // wParam handle flag

Parameters

wCtlFocus

Value of wParam. If the fHandle parameter is TRUE, the wCtlFocus parameter identifies the control that receives the focus. If fHandle is FALSE, wCtlFocus is a flag that indicates whether the next or previous control with the WS_TABSTOP style receives the focus. If wCtlFocus is zero, the next control receives the focus; otherwise, the previous control with the WS_TABSTOP style receives the focus.

fHandle

Value of lParam. Contains a flag that indicates how Windows uses the wCtlFocus parameter. If the fHandle parameter is TRUE, wCtlFocus is a handle associated with the control that receives the focus; otherwise, wCtlFocus is a flag that indicates whether the next or previous control with the WS_TABSTOP style receives the focus.

Return Values

An application should return zero if it processes this message.

Remarks

The effect of this message differs from that of the SetFocus function because WM_NEXTDLGCTL modifies the border around the control.

Do not use the SendMessage function to send a WM_NEXTDLGCTL message if your application will concurrently process other messages that set the focus. Use the PostMessage function instead.

See Also

PostMessage, SendMessage, SetFocus


WM_NOTIFY

The WM_NOTIFY message informs the parent window of a control that an event has occurred in the control or that the control requires some kind of information.

WM_NOTIFY

idCtrl = (int) wParam;

pnmh = (LPNMHDR) lParam;

Parameters

idCtrl

Identifier of the control sending the message. This identifier is not guaranteed to be unique. An application should use the hwindFrom or idFrom member of the NMHDR structure (passed as the lParam parameter) to identify the control.

pnmh

Pointer to an NMHDR structure that contains the notification code and additional information. For some notification messages, this parameter points to a larger structure that has the NMHDR structure as its first member.

Return Values

The return value is ignored except for notification messages that specify otherwise.

See Also

NMHDR


WM_NOTIFYFORMAT

Common controls, custom controls, and their parent windows use the WM_NOTIFYFORMAT message to determine whether the control should use ANSI or Unicode structures in the WM_NOTIFY notification messages that the control uses to communicate with its parent window. WM_NOTIFYFORMAT messages are sent from a control to its parent window, and from the parent window to the control.

hwndFrom = (HWND) wParam;        // handle of the window sending this message

Command =  lParam;               // command value specifying the nature of this message

Parameters

hwndFrom

Value of wParam. Handle of the window that is sending the WM_NOTIFYFORMAT message. If Command is NF_QUERY, hwndFrom is the handle of a control. If Command is NF_REQUERY, this is the handle of the parent window of a control.

Command

Value of lParam. A command value that specifies the nature of the WM_NOTIFYFORMAT message. The following values are defined:

Value	Meaning
NF_QUERY	The message is a query to determine whether ANSI or Unicode structures should be used in WM_NOTIFY messages. This command is sent from a control to its parent window. This command is sent during the creation of a control, and in response to an NF_REQUERY command.
NF_REQUERY	The message is a request that a control send an NF_QUERY form of this message to its parent window. This command is sent from a control’s parent window to the control. The parent window is asking the control to requery it about the type of structures to use in WM_NOTIFY messages.
Return Values

The return value is one of the following :

Value	Meaning
NFR_ANSI	ANSI structures should be used in WM_NOTIFY messages sent by the control.
NFR_UNICODE	Unicode structures should be used in WM_NOTIFY messages sent by the control.
0	An error occurred.
If Command is NF_REQUERY, the return value is the result of the requery operation.

Remarks

When a common control is created, the control sends a WM_NOTIFYFORMAT message to its parent window to determine the type of structures to use in WM_NOTIFY messages. If the parent window does not handle this message, the DefWindowProc function responds according to the type of the parent window. That is, if the parent window is a Unicode window, DefWindowProc returns NFR_UNICODE, and if the parent window is an ANSI window, DefWindowProc returns NFR_ANSI. If the parent window is a dialog box and does not handle this message, the DefDlgProc function similarly responds according to the type of the dialog box (Unicode or ANSI).

A parent window can change the type of structures a common control uses in WM_NOTIFY messages by setting lParam to NF_REQUERY and sending a WM_NOTIFYFORMAT message to the control. This causes the control to send an NF_QUERY form of the WM_NOTIFYFORMAT message to the parent window.

See Also

DefDlgProc, DefWindowProc, WM_NOTIFY


WM_PAINT

An application sends the WM_PAINT message when Windows or another application makes a request to paint a portion of an application’s window. The message is sent when the UpdateWindow or RedrawWindow function is called, or by the DispatchMessage function when the application obtains a WM_PAINT message by using the GetMessage or PeekMessage function.

WM_PAINT

hdc = (HDC) wParam; // the device context to draw in

Parameters

hdc

Identifies the device context to draw in. If this parameter is NULL, use the default device context. This parameter is used by some common controls to enable drawing in a device context other than the default device context. Other windows can safely ignore this parameter.

Return Values

An application should return zero if it processes this message.

Remarks

The DefWindowProc function validates the update region. The function may also send the WM_NCPAINT message to the window procedure if the window frame must be painted and send the WM_ERASEBKGND message if the window background must be erased.

The system sends this message when there are no other messages in the application’s message queue. DispatchMessage determines where to send the message; GetMessage determines which message to dispatch. GetMessage returns the WM_PAINT message when there are no other messages in the application’s message queue, and DispatchMessage sends the message to the appropriate window procedure.

A window may receive internal paint messages as a result of calling RedrawWindow with the RDW_INTERNALPAINT flag set. In this case, the window may not have an update region. An application should call the GetUpdateRect function to determine whether the window has an update region. If GetUpdateRect returns zero, the application should not call the BeginPaint and EndPaint functions.

An application must check for any necessary internal painting by looking at its internal data structures for each WM_PAINT message, because a WM_PAINT message may have been caused by both a non-NULL update region and a call to RedrawWindow with the RDW_INTERNALPAINT flag set.

Windows sends an internal WM_PAINT message only once. After an internal WM_PAINT message is returned from GetMessage or PeekMessage or is sent to a window by UpdateWindow, Windows does not post or send further WM_PAINT messages until the window is invalidated or until RedrawWindow is called again with the RDW_INTERNALPAINT flag set.

For some common controls, the default WM_PAINT message processing checks the wParam parameter. If wParam is non-NULL, the control assumes that the value is an HDC and paints using that device context.

See Also

BeginPaint, DefWindowProc, DispatchMessage, EndPaint, GetMessage, GetUpdateRect, PeekMessage, RedrawWindow, UpdateWindow, WM_ERASEBKGND, WM_NCPAINT


WM_PAINTCLIPBOARD

The WM_PAINTCLIPBOARD message is sent to the clipboard owner by a clipboard viewer window when the clipboard contains data in the CF_OWNERDISPLAY format and the clipboard viewer’s client area needs repainting.

WM_PAINTCLIPBOARD

hwndViewer = (HWND) wParam;     // handle of clipboard viewer window

hglbPs = (HGLOBAL) lParam;      // handle of PAINTSTRUCT object

Parameters

hwndViewer

Value of wParam. Identifies the clipboard viewer window.

hglbPs

Value of lParam. Identifies a global DDESHARE object that contains a PAINTSTRUCT structure. The structure defines the part of the client area to paint.

Return Values

If an application processes this message, it should return zero.

Remarks

To determine whether the entire client area or just a portion of it needs repainting, the clipboard owner must compare the dimensions of the drawing area given in the rcpaint member of PAINTSTRUCT to the dimensions given in the most recent WM_SIZECLIPBOARD message.

The clipboard owner must use the GlobalLock function to lock the memory that contains the PAINTSTRUCT structure. Before returning, the clipboard owner must unlock that memory by using the GlobalUnlock function.

See Also

GlobalLock, GlobalUnlock, PAINTSTRUCT, WM_SIZECLIPBOARD


WM_PAINTICON

The WM_PAINTICON message is sent to a minimized window when the icon is to be painted but only if the application is written for Windows 3.x. A window receives this message only if a class icon is defined for the window; otherwise, WM_PAINT is sent instead.

WM_PAINTICON

Parameters

This message has no parameters.

Return Values

An application should return zero if it processes this message.

Remarks

The DefWindowProc function draws the class icon. For compatibility with Windows 3.x, wParam is TRUE. However, this value has no significance.

See Also

DefWindowProc, WM_ICONERASEBKGND, WM_PAINT


WM_PALETTECHANGED

The WM_PALETTECHANGED message is sent to all top-level and overlapped windows after the window with the keyboard focus has realized its logical palette, thereby changing the system palette. This message enables a window that uses a color palette but does not have the keyboard focus to realize its logical palette and update its client area.

WM_PALETTECHANGED

hwndPalChg = (HWND) wParam; // handle of window that changed palette

Parameters

hwndPalChg

Value of wParam. Identifies the window that caused the system palette to change.

Remarks

This message must be sent to all top-level and overlapped windows, including the one that changed the system palette. If any child windows use a color palette, this message must be passed on to them as well.

To avoid creating an infinite loop, a window that receives this message must not realize its palette, unless it determines that wParam does not contain its own window handle.

See Also

WM_PALETTEISCHANGING, WM_QUERYNEWPALETTE


WM_PALETTEISCHANGING

The WM_PALETTEISCHANGING message informs applications that an application is going to realize its logical palette.

WM_PALETTEISCHANGING

hwndRealize = (HWND) wParam; // window to realize palette

Parameters

hwndRealize

Value of wParam. Identifies the window that is going to realize its logical palette.

Return Values

If an application processes this message, it should return zero.

Remarks

The application changing its palette does not wait for acknowledgment of this message before changing the palette and sending the WM_PALETTECHANGED message. As a result, the palette may already be changed by the time an application receives this message.

If the application either ignores or fails to process this message and a second application realizes its palette while the first is using palette indices, there is a strong possibility that the user will see unexpected colors during subsequent drawing operations.

See Also

WM_PALETTECHANGED, WM_QUERYNEWPALETTE


WM_PARENTNOTIFY

The WM_PARENTNOTIFY message is sent to the parent of a child window when the child window is created or destroyed, or when the user clicks a mouse button while the cursor is over the child window. When the child window is being created, the system sends WM_PARENTNOTIFY just before the CreateWindow or CreateWindowEx function that creates the window returns. When the child window is being destroyed, Windows sends the message before any processing to destroy the window takes place.

WM_PARENTNOTIFY

fwEvent = LOWORD(wParam);  // event flags

idChild = HIWORD(wParam);  // identifier of child window

lValue = lParam;           // child handle, or cursor coordinates

Parameters

fwEvent

Value of the low-order word of wParam. Specifies the event for which the parent is being notified. This parameter can be one of the following values:

Value	Meaning
WM_CREATE	The child window is being created.
WM_DESTROY	The child window is being destroyed.
WM_LBUTTONDOWN	The user has placed the cursor over the child window and has clicked the left mouse button.
WM_MBUTTONDOWN	The user has placed the cursor over the child window and has clicked the middle mouse button.
WM_RBUTTONDOWN	The user has placed the cursor over the child window and has clicked the right mouse button.
idChild

Value of the high-order word of wParam. If the fwEvent parameter is the WM_CREATE or WM_DESTROY value, idChild specifies the identifier of the child window. Otherwise, idChild is undefined.

lValue

Contains the handle of the child window, if the fwEvent parameter is the WM_CREATE or WM_DESTROY value; otherwise, lValue contains the x- and y-coordinates of the cursor. The x-coordinate is in the low-order word and the y-coordinate is in the high-order word.

Return Values

If an application processes this message, it should return zero.

Remarks

This message is also sent to all ancestor windows of the child window, including the top-level window.

All child windows, except those that have the WS_EX_NOPARENTNOTIFY extended window style, send this message to their parent windows. By default, child windows in a dialog box have the WS_EX_NOPARENTNOTIFY style, unless the CreateWindowEx function is called to create the child window without this style.

See Also

CreateWindow, CreateWindowEx, WM_CREATE, WM_DESTROY, WM_LBUTTONDOWN, WM_MBUTTONDOWN, WM_RBUTTONDOWN


WM_PASTE

An application sends a WM_PASTE message to an edit control or combo box to copy the current content of the clipboard to the edit control at the current caret position. Data is inserted only if the clipboard contains data in CF_TEXT format.

WM_PASTE

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

This message does not return a value.

Remarks

When sent to a combo box, the WM_PASTE message is handled by its edit control. This message has no effect when sent to a combo box with the CBS_DROPDOWNLIST style.

See Also

WM_CLEAR, WM_COPY, WM_CUT


WM_POWER

The WM_POWER message is sent when the system, typically a battery-powered personal computer, is about to enter suspended mode.

The WM_POWER message is obsolete. It is provided to simplify porting of 16-bit Windows-based applications. New Win32-based applications should use the WM_POWERBROADCAST message.

WM_POWER

fwPowerEvt = wParam;    // power-event notification message

Parameters

fwPowerEvt

Value of wParam. Specifies a power-event notification message. This parameter can be one of the following values:

Value	Meaning
PWR_CRITICALRESUME	Indicates that the system is resuming operation after entering suspended mode without first sending a PWR_SUSPENDREQUEST notification message to the application. An application should perform any necessary recovery actions.
PWR_SUSPENDREQUEST	Indicates that the system is about to enter suspended mode.
PWR_SUSPENDRESUME	Indicates that the system is resuming operation after having entered suspended mode normally — that is, the system sent a PWR_SUSPENDREQUEST notification message to the application before the system was suspended. An application should perform any necessary recovery actions.
Return Values

The value an application returns depends on the value of the wParam parameter. If wParam is PWR_SUSPENDREQUEST, the return value is PWR_FAIL to prevent the system from entering the suspended state; otherwise, it is PWR_OK. If wParam is PWR_SUSPENDRESUME or PWR_CRITICALRESUME, the return value is zero.

Remarks

This message is sent only to an application that is running on a system that conforms to the Advanced Power Management (APM) basic input/output system (BIOS) specification. The message is sent by the power-management driver to each window returned by the EnumWindows function.

The suspended mode is the state in which the greatest amount of power savings occurs, but all operational data and parameters are preserved. Random-access memory (RAM) contents are preserved, but many devices are likely to be turned off.

See Also

EnumWindows, WM_POWERBROADCAST


WM_POWERBROADCAST

The WM_POWERBROADCAST message is sent to an application to notify it of power-management events.

dwPowerEvent = (DWORD) wParam;
dwData = (DWORD) lParam;

Parameters

dwPowerEvent

Event notification message. This parameter can be one of the following values:

Value	Meaning
PBT_APMBATTERYLOW	Battery power is low.
PBT_APMOEMEVENT	OEM-defined event occurred.
PBT_APMPOWERSTATUSCHANGE	Power status has changed.
PBT_APMQUERYSUSPEND	Request for permission to suspend.
PBT_APMQUERYSUSPENDFAILED	Suspension request denied.
PBT_APMRESUMECRITICAL	Operation resuming after critical suspension.
PBT_APMRESUMESUSPEND	Operation resuming after suspension.
PBT_APMSUSPEND	System is suspending operation.
dwData

Function-specific data. For most messages, this parameter is reserved and not used.

However, if wParam is one of the resume notifications (PBT_APMRESUME*), the lParam parameter can specify the PBTF_APMRESUMEFROMFAILURE flag. This flag indicates that a suspend operation failed after the PBT_APMSUSPEND message was sent.

Return Values

Return TRUE to grant a request.

Return BROADCAST_QUERY_DENY to deny a request.


WM_PRINT

The WM_PRINT message is sent to a window to request that it draw itself in the specified device context, most commonly in a printer device context.

WM_PRINT

hdc = (HDC) wParam;

uFlags = lParam;

Parameters

hdc

Identifies the device context to draw in.

uFlags

Specifies the drawing options. This parameter can be one or more of these flags:

Value	Meaning
PRF_CHECKVISIBLE	Draw the window only if it is visible.
PRF_CHILDREN	Draw all visible children windows.
PRF_CLIENT	Draw the client area of the window.
PRF_ERASEBKGND	Erase the background before drawing the window.
PRF_NONCLIENT	Draw the nonclient area of the window.
PRF_OWNED	Draw all owned windows.
Remarks

The DefWindowProc function processes this message based on which drawing option is specified: if PRF_CHECKVISIBLE is specified and the window is not visible, do nothing, if PRF_NONCLIENT is specified, draw the nonclient area in the given device context, if PRF_ERASEBKGND is specified, send the window a WM_ERASEBKGND message, if PRF_PRINTCLIENT is specified, send the window a WM_PRINTCLIENT message, if PRF_PRINTCHILDREN is set, send each visible child window a WM_PRINT message, if PRF_OWNED is set, send each visible owned window a WM_PRINT message.

See Also

DefWindowProc, WM_ERASEBKGND, WM_PRINTCLIENT


WM_PRINTCLIENT

The WM_PRINTCLIENT message is sent to a window to request that it draw its client area in the specified device context, most commonly in a printer device context.

WM_PRINTCLIENT

hdc = (HDC) wParam;

uFlags = lParam;

Parameters

hdc

Identifies the device context to draw in.

uFlags

Specifies drawing options. This parameter can be one or more of these flags:

Value	Meaning
PRF_CHECKVISIBLE	Draw the window only if it is visible.
PRF_CHILDREN	Draw all visible children windows.
PRF_CLIENT	Draw the client area of the window.
PRF_ERASEBKGND	Erase the background before drawing the window.
PRF_NONCLIENT	Draw the nonclient area of the window.
PRF_OWNED	Draw all owned windows.
Remarks

A window can process this message in much the same manner as WM_PAINT, except that BeginPaint and EndPaint need not be called (a device context is provided), and the window should draw its entire client area rather than just the invalid region.

Windows that can be used anywhere in the system, such as controls, should process this message. It is probably worthwhile for other windows to process this message as well because it is relatively easy to implement.

See Also

BeginPaint, EndPaint, WM_PAINT


WM_PSD_ENVSTAMPRECT

The WM_PSD_ENVSTAMPRECT message notifies the hook procedure of a Page Setup dialog box that the dialog box is about to draw the envelope-stamp rectangle of the sample page.

WM_PSD_ENVSTAMPRECT

hDC = (WPARAM) (HDC) wParam;             // handle of the device context

lprcEnvStamp = (LPARAM) (LPRECT) lParam; // envelope-stamp rectangle

Parameters

hDC

Value of wParam. Identifies the device context for the sample page.

lprcMargin

Value of lParam. Pointer to a RECT structure that contains the coordinates, in pixels, of the envelope-stamp rectangle.

Return Values

If the hook procedure returns TRUE, the dialog box does not draw the envelope-stamp portion of the sample page.

If the hook procedure returns FALSE, the dialog box draws the envelope-stamp portion of the sample page.

Remarks

The Page Setup dialog box includes an image of a sample page that shows how the user’s selections affect the appearance of the printed output. When you call the PageSetupDlg function, you can provide a PagePaintHook hook procedure to customize the appearance of the sample page. Whenever the dialog box is about to draw the contents of the sample page, the dialog box sends a sequence of WM_PSD* messages to the hook procedure.

A hook procedure receives this message only if the selected paper type is an envelope.

See Also

PagePaintHook, PageSetupDlg, RECT, WM_PSD_PAGESETUPDLG


WM_PSD_FULLPAGERECT

The WM_PSD_FULLPAGERECT message informs a PagePaintHook hook procedure of the coordinates of the sample page rectangle in the Page Setup dialog box. The dialog box sends this message when it is about to draw the contents of the sample page.

WM_PSD_FULLPAGERECT

hDC = (WPARAM) (HDC) wParam;         // handle of the device context

lprcPage = (LPARAM) (LPRECT) lParam; // dimensions of page rectangle

Parameters

hDC

Value of wParam. Handle of the device context for the sample page.

lprcPage

Value of lParam. Pointer to a RECT structure that contains the coordinates, in pixels, of the sample page.

Return Values

If the hook procedure returns TRUE, the dialog box sends no more WM_PSD* messages and does not draw in the sample page until the next time the system needs to redraw the sample page.

If the hook procedure returns FALSE, the dialog box sends the remaining messages of the drawing sequence.

Remarks

The Page Setup dialog box includes an image of a sample page that shows how the user’s selections affect the appearance of the printed output. When you call the PageSetupDlg function, you can provide a PagePaintHook hook procedure to customize the appearance of the sample page. Whenever the dialog box is about to draw the contents of the sample page, the dialog box sends a sequence of WM_PSD* messages to the hook procedure.

See Also

PagePaintHook, PageSetupDlg, RECT, WM_PSD_PAGESETUPDLG


WM_PSD_GREEKTEXTRECT

The WM_PSD_GREEKTEXTRECT message notifies the hook procedure of a Page Setup dialog box that the dialog box is about to draw greek text inside the margin rectangle of the sample page.

WM_PSD_GREEKTEXTRECT

hDC = (WPARAM) (HDC) wParam;              // handle of the device context

lprcGreekText = (LPARAM) (LPRECT) lParam; // greek text rectangle

Parameters

hDC

Value of wParam. Identifies the device context for the sample page.

lprcMargin

Value of lParam. Pointer to a RECT structure that contains the coordinates, in pixels, of the greek text rectangle.

Return Values

If the hook procedure returns TRUE, the dialog box does not draw the greek text portion of the sample page.

If the hook procedure returns FALSE, the dialog box draws the greek text portion of the sample page.

Remarks

The Page Setup dialog box includes an image of a sample page that shows how the user’s selections affect the appearance of the printed output. When you call the PageSetupDlg function, you can provide a PagePaintHook hook procedure to customize the appearance of the sample page. Whenever the dialog box is about to draw the contents of the sample page, the dialog box sends a sequence of WM_PSD* messages to the hook procedure.

See Also

PagePaintHook, PageSetupDlg, RECT, WM_PSD_PAGESETUPDLG


WM_PSD_MARGINRECT

The WM_PSD_MARGINRECT message notifies the hook procedure of a Page Setup dialog box that the dialog box is about to draw the margin rectangle of the sample page.

WM_PSD_MARGINRECT

hDC = (WPARAM) (HDC) wParam;           // handle of the device context

lprcMargin = (LPARAM) (LPRECT) lParam; // margin rectangle

Parameters

hDC

Value of wParam. Identifies the device context for the sample page.

lprcMargin

Value of lParam. Pointer to a RECT structure that contains the coordinates, in pixels, of the margin rectangle.

Return Values

If the hook procedure returns TRUE, the dialog box does not draw the margin rectangle in the sample page.

If the hook procedure returns FALSE, the dialog box draws the margin rectangle in the sample page.

Remarks

The Page Setup dialog box includes an image of a sample page that shows how the user’s selections affect the appearance of the printed output. When you call the PageSetupDlg function, you can provide a PagePaintHook hook procedure to customize the appearance of the sample page. Whenever the dialog box is about to draw the contents of the sample page, the dialog box sends a sequence of WM_PSD* messages to the hook procedure.

See Also

PagePaintHook, PageSetupDlg, RECT, WM_PSD_PAGESETUPDLG


WM_PSD_MINMARGINRECT

The WM_PSD_MINMARGINRECT message informs a PagePaintHook hook procedure of the coordinates of the margin rectangle in the sample page. A Page Setup dialog box sends this message when it is about to draw the contents of the sample page.

WM_PSD_MINMARGINRECT

hDC = (WPARAM) (HDC) wParam;              // handle of the device context

lprcMinMargin = (LPARAM) (LPRECT) lParam; // minimum margin rectangle

Parameters

hDC

Value of wParam. Identifies the device context for the sample page.

lprcMinMargin

Value of lParam. Pointer to a RECT structure that contains the coordinates, in pixels, of the minimum margin rectangle.

Return Values

If the hook procedure returns TRUE, the dialog box sends no more WM_PSD* messages and does not draw in the sample page until the next time the system needs to redraw the sample page.

If the hook procedure returns FALSE, the dialog box sends the remaining messages of the drawing sequence.

Remarks

The Page Setup dialog box includes an image of a sample page that shows how the user’s selections affect the appearance of the printed output. When you call the PageSetupDlg function, you can provide a PagePaintHook hook procedure to customize the appearance of the sample page. Whenever the dialog box is about to draw the contents of the sample page, the dialog box sends a sequence of WM_PSD* messages to the hook procedure.

See Also

PagePaintHook, PageSetupDlg, RECT, WM_PSD_PAGESETUPDLG


WM_PSD_PAGESETUPDLG

The WM_PSD_PAGESETUPDLG message notifies a PagePaintHook hook procedure that the Page Setup dialog box is about to draw the contents of the sample page. The hook procedure can use this message to carry out initialization tasks related to drawing the contents of the sample page.

WM_PSD_PAGESETUPDLG

wPaper = LOWORD(wParam);         // paper-size flag

wFlags = HIWORD(wParam);         // paper-orientation flag

lppsd = (LPPAGESETUPDLG) lParam; // dialog box information

Parameters

wPaper

Value of the low-order word of wParam. Specifies a value that indicates the paper size. This value can be one of the DMPAPER_ values listed in the description of the DEVMODE structure.

wFlags

Value of the high-order word of wParam. Indicates the orientation of the paper or envelope, and whether the printer is a dot matrix or HPPCL (Hewlett Packard Printer Control Language) device. This parameter can be one of the following values:

0x0001	Paper in landscape mode (dot matrix)
0x0003	Paper in landscape mode (HPPCL)
0x0005	Paper in portrait mode (dot matrix)
0x0007	Paper in portrait mode (HPPCL)
0x000b	Envelope in landscape mode (HPPCL)
0x000d	Envelope in portrait mode (dot matrix)
0x0019	Envelope in landscape mode (dot matrix)
0x001f	Envelope in portrait mode (HPPCL)
lppsd

Value of lParam. Points to a PAGESETUPDLG structure that contains information used to initialize the Page Setup dialog box.

Return Values

If the hook procedure returns TRUE, the dialog box sends no more WM_PSD* messages and does not draw in the sample page until the next time the system needs to redraw the sample page.

If the hook procedure returns FALSE, the dialog box sends the remaining messages of the drawing sequence.

Remarks

The Page Setup dialog box includes an image of a sample page that shows how the user’s selections affect the appearance of the printed output. When you call the PageSetupDlg function, you can provide a PagePaintHook hook procedure to customize the appearance of the sample page. Whenever the dialog box is about to draw the contents of the sample page, the dialog box sends a sequence of WM_PSD* messages to the hook procedure.

The first three messages of a drawing sequence (WM_PSD_PAGESETUPDLG, WM_PSD_FULLPAGERECT, or WM_PSD_MINMARGINRECT) provide information that the hook procedure can use to draw the contents of the sample page. The remaining messages (WM_PSD_MARGINRECT, WM_PSD_GREEKTEXTRECT, WM_PSD_ENVSTAMPRECT, WM_PSD_YAFULLPAGERECT) notify the hook procedure that the dialog box is about to draw a specific portion of the sample page. This allows the hook procedure to selectively draw portions of the sample page.

See Also

DEVMODE, PagePaintHook, PageSetupDlg, PAGESETUPDLG, WM_PSD_ENVSTAMPRECT, WM_PSD_FULLPAGERECT, WM_PSD_GREEKTEXTRECT, WM_PSD_MARGINRECT, WM_PSD_MINMARGINRECT, WM_PSD_YAFULLPAGERECT


WM_PSD_YAFULLPAGERECT

The WM_PSD_YAFULLPAGERECT message notifies the hook procedure of a Page Setup dialog box that the dialog box is about to draw the return address portion of an envelope sample page.

WM_PSD_YAFULLPAGERECT

hDC = (WPARAM) (HDC) wParam;               // handle of the device context

lprcYaFullPage = (LPARAM) (LPRECT) lParam; // dimensions of page rectangle

Parameters

hDC

Value of wParam. Handle of the device context for the sample page.

lprcPage

Value of lParam. Pointer to a RECT structure that contains the coordinates, in pixels, of the sample page.

Return Values

If the hook procedure returns TRUE, the dialog box does not draw the return address portion of an envelope sample page.

If the hook procedure returns FALSE, the dialog box draws the return address portion of an envelope sample page.

If the paper type is not an envelope, the return value has no effect.

Remarks

The Page Setup dialog box includes an image of a sample page that shows how the user’s selections affect the appearance of the printed output. When you call the PageSetupDlg function, you can provide a PagePaintHook hook procedure to customize the appearance of the sample page. Whenever the dialog box is about to draw the contents of the sample page, the dialog box sends a sequence of WM_PSD* messages to the hook procedure.

See Also

PagePaintHook, PageSetupDlg, RECT, WM_PSD_PAGESETUPDLG


WM_QUERYDRAGICON

The WM_QUERYDRAGICON message is sent to a minimized (iconic) window. The window is about to be dragged by the user but does not have an icon defined for its class. An application can return the handle of an icon or cursor. The system displays this cursor or icon while the user drags the icon.

WM_QUERYDRAGICON

Parameters

This message has no parameters.

Return Values

An application should return the handle of a cursor or icon that Windows is to display while the user drags the icon. The cursor or icon must be compatible with the display driver’s resolution. If the application returns NULL, the system displays the default cursor.

Default Action

The DefWindowProc function returns the handle of the default cursor.

Remarks

When the user drags the icon of a window without a class icon, Windows replaces the icon with a default cursor. If the application requires a different cursor to be displayed during dragging, it must return the handle of the cursor or icon compatible with the display driver’s resolution. If an application returns the handle of a color cursor or icon, the system converts the cursor or icon to black and white. The application can call the LoadCursor or LoadIcon function to load a cursor or icon from the resources in its executable (.EXE) file and to retrieve this handle.

See Also

DefWindowProc, LoadCursor, LoadIcon


WM_QUERYENDSESSION

The WM_QUERYENDSESSION message is sent when the user chooses to end the Windows session or when an application calls the ExitWindows function. If any application returns zero, the Windows session is not ended. Windows stops sending WM_QUERYENDSESSION messages as soon as one application returns zero.

After processing this message, Windows sends the WM_ENDSESSION message with the wParam parameter set to the results of the WM_QUERYENDSESSION message.

WM_QUERYENDSESSION

nSource = (UINT) wParam;    // source of end-session request

fLogOff = lParam            // logoff flag

Parameters

nSource

Reserved for future use.

fLogOff

Value of lParam. Indicates whether the user is logging off or shutting down the system. Supported values include: ENDSESSION_LOGOFF.

Return Values

If an application can terminate conveniently, it should return TRUE; otherwise, it should return FALSE.

Remarks

By default, the DefWindowProc function returns TRUE for this message.

Windows NT: When an application returns TRUE for this message, it receives the WM_ENDSESSION message and it is terminated, regardless of how the other applications respond to the WM_QUERYENDSESSION message.

Windows 95: After all applications return TRUE for this message, they receive the WM_ENDSESSION and they are terminated.

See Also

DefWindowProc, ExitWindows, WM_ENDSESSION


WM_QUERYNEWPALETTE

The WM_QUERYNEWPALETTE message informs a window that it is about to receive the keyboard focus, giving the window the opportunity to realize its logical palette when it receives the focus.

WM_QUERYNEWPALETTE

Parameters

This message has no parameters.

Return Values

If the window realizes its logical palette, it must return TRUE; otherwise, it must return FALSE.

See Also

WM_PALETTECHANGED, WM_PALETTEISCHANGING


WM_QUERYOPEN

The WM_QUERYOPEN message is sent to an icon when the user requests that the window be restored to its previous size and position.

WM_QUERYOPEN

Parameters

This message has no parameters.

Return Values

If the icon can be opened, an application that processes this message should return TRUE; otherwise, it should return FALSE to prevent the icon from being opened.

Default Action

The DefWindowProc function returns TRUE.

Remarks

While processing this message, the application should not perform any action that would cause an activation or focus change (for example, creating a dialog box).

See Also

DefWindowProc


WM_QUEUESYNC

The WM_QUEUESYNC message is sent by a computer-based training (CBT) application to separate user-input messages from other messages sent through the WH_JOURNALPLAYBACK hook procedure.

WM_QUEUESYNC

wParam = 0; // not used, must be zero

lParam = 0; // not used, must be zero

Parameters

This message has no parameters.

Return Values

A CBT application should return zero if it processes this message.

Remarks

Whenever a CBT application uses the WH_JOURNALPLAYBACK hook procedure, the first and last messages are WM_QUEUESYNC. This allows the CBT application to intercept and examine user-initiated messages without doing so for events that it sends.

If an application specifies a NULL window handle, the message is posted to the message queue of the active window.


WM_QUIT

The WM_QUIT message indicates a request to terminate an application and is generated when the application calls the PostQuitMessage function. It causes the GetMessage function to return zero.

WM_QUIT

nExitCode = (int) wParam;   // exit code

Parameters

nExitCode

Value of wParam. Specifies the exit code given in the PostQuitMessage function.

Return Values

This message does not have a return value, because it causes the message loop to terminate before the message is sent to the application’s window procedure.

See Also

GetMessage, PostQuitMessage


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.

See Also

RasDial, RasDialFunc, RasDialFunc1, RASCONNSTATE


WM_RBUTTONDBLCLK

The WM_RBUTTONDBLCLK message is posted when the user double-clicks the right mouse button while the cursor is in the client area of a window. If the mouse is not captured, the message is posted to the window beneath the cursor. Otherwise, the message is posted to the window that has captured the mouse.

WM_RBUTTONDBLCLK

fwKeys = wParam;        // key flags

xPos = LOWORD(lParam);  // horizontal position of cursor

yPos = HIWORD(lParam);  // vertical position of cursor

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper left corner of the client area.

Return Values

If an application processes this message, it should return zero.

Remarks

Only windows that have the CS_DBLCLKS style can receive WM_RBUTTONDBLCLK messages, which Windows generates whenever the user presses, releases, and again presses the right mouse button within the system’s double-click time limit. Double-clicking the right mouse button actually generates four messages: WM_RBUTTONDOWN, WM_RBUTTONUP, WM_RBUTTONDBLCLK, and WM_RBUTTONUP again.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, GetDoubleClickTime, MAKEPOINTS, POINTS, SetCapture, SetDoubleClickTime, WM_RBUTTONDOWN, WM_RBUTTONUP


WM_RBUTTONDOWN

The WM_RBUTTONDOWN message is posted when the user presses the right mouse button while the cursor is in the client area of a window. If the mouse is not captured, the message is posted to the window beneath the cursor. Otherwise, the message is posted to the window that has captured the mouse.

WM_RBUTTONDOWN

fwKeys = wParam;        // key flags

xPos = LOWORD(lParam);  // horizontal position of cursor

yPos = HIWORD(lParam);  // vertical position of cursor

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper left corner of the client area.

Return Values

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, MAKEPOINTS, POINTS, SetCapture, WM_RBUTTONDBLCLK, WM_RBUTTONUP


WM_RBUTTONUP

The WM_RBUTTONUP message is posted when the user releases the right mouse button while the cursor is in the client area of a window. If the mouse is not captured, the message is posted to the window beneath the cursor. Otherwise, the message is posted to the window that has captured the mouse.

WM_RBUTTONUP

fwKeys = wParam;        // key flags

xPos = LOWORD(lParam);  // horizontal position of cursor

yPos = HIWORD(lParam);  // vertical position of cursor

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper left corner of the client area.

Return Values

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, MAKEPOINTS, POINTS, SetCapture, WM_RBUTTONDBLCLK, WM_RBUTTONDOWN


WM_RENDERALLFORMATS

The WM_RENDERALLFORMATS message is sent to the clipboard owner before it is destroyed, if the clipboard owner has delayed rendering one or more clipboard formats. For the content of the clipboard to remain available to other applications, the clipboard owner must render data in all the formats it is capable of generating, and place the data on the clipboard by calling the SetClipboardData function.

WM_RENDERALLFORMATS

Parameters

This message has no parameters.

Return Values

If an application processes this message, it should return zero.

Remarks

When responding to a WM_RENDERALLFORMATS message, the clipboard owner must call the OpenClipboard and EmptyClipboard functions before calling SetClipboardData.

When the application returns, the system removes any unrendered formats from the list of available clipboard formats. For information about delayed rendering, see SetClipboardData.

See Also

EmptyClipboard, OpenClipboard, SetClipboardData, WM_RENDERFORMAT


WM_RENDERFORMAT

The WM_RENDERFORMAT message is sent to the clipboard owner if it has delayed rendering a specific clipboard format and if an application has requested data in that format. The clipboard owner must render data in the specified format and place it on the clipboard by calling the SetClipboardData function.

WM_RENDERFORMAT

uFormat = (UINT) wParam;    // clipboard format

Parameters

uFormat

Specifies the clipboard format to be rendered.

Return Values

If an application processes this message, it should return zero.

Remarks

When responding to a WM_RENDERFORMAT message, the clipboard owner must not open the clipboard before calling SetClipboardData.

See Also

SetClipboardData, WM_RENDERALLFORMATS


WM_SETCURSOR

The WM_SETCURSOR message is sent to a window if the mouse causes the cursor to move within a window and mouse input is not captured.

WM_SETCURSOR

hwnd = (HWND) wParam;       // handle of window with cursor

nHittest = LOWORD(lParam);  // hit-test code

wMouseMsg = HIWORD(lParam); // mouse-message identifier

Parameters

hwnd

Value of wParam. Identifies the window that contains the cursor.

nHittest

Value of the low-order word of lParam. Specifies the hit-test code.

wMouseMsg

Value of the high-order word of lParam. Specifies the identifier of the mouse message.

Default Action

The DefWindowProc function passes the WM_SETCURSOR message to a parent window before processing. If the parent window returns TRUE, further processing is halted. Passing the message to a window’s parent window gives the parent window control over the cursor’s setting in a child window. The DefWindowProc function also uses this message to set the cursor to an arrow if it is not in the client area, or to the registered class cursor if it is in the client area. If the low-order word of the lParam parameter is HTERROR and the high-order word of lParam specifies that one of the mouse buttons is pressed, DefWindowProc calls the MessageBeep function.

Remarks

The high-order word of lParam is zero when the window enters menu mode.

See Also

DefWindowProc, MessageBeep


WM_SETFOCUS

The WM_SETFOCUS message is sent to a window after it has gained the keyboard focus.

WM_SETFOCUS

hwndLoseFocus = (HWND) wParam; // handle of window losing focus

Parameters

hwndLoseFocus

Value of wParam. Identifies the window that has lost the keyboard focus (may be NULL).

Return Values

An application should return zero if it processes this message.

Remarks

To display a caret, an application should call the appropriate caret functions when it receives the WM_SETFOCUS message.

See Also

SetFocus, WM_KILLFOCUS


WM_SETFONT

An application sends a WM_SETFONT message to specify the font that a control is to use when drawing text.

WM_SETFONT

wParam = (WPARAM) hfont;            // handle of font

lParam = MAKELPARAM(fRedraw, 0);    // redraw flag

Parameters

hfont

Value of wParam. Identifies the font. If this parameter is NULL, the control uses the default system font to draw text.

fRedraw

Value of lParam. Specifies whether the control should be redrawn immediately upon setting the font. Setting the fRedraw parameter to TRUE causes the control to redraw itself.

Return Values

This message does not return a value.

Remarks

The WM_SETFONT message applies to all controls, not just those in dialog boxes.

The best time for the owner of a dialog box control to set the font of the control is when it receives the WM_INITDIALOG message. The application should call the DeleteObject function to delete the font when it is no longer needed; for example, after it destroys the control.

The size of the control does not change as a result of receiving this message. To avoid clipping text that does not fit within the boundaries of the control, the application should correct the size of the control window before it sets the font.

When a dialog box uses the DS_SETFONT style to set the text in its controls, Windows sends the WM_SETFONT message to the dialog box procedure before it creates the controls. An application can create a dialog box that contains the DS_SETFONT style by calling any of the following functions:

•	CreateDialogIndirect

•	CreateDialogIndirectParam

•	DialogBoxIndirect

•	DialogBoxIndirectParam

See Also

CreateDialogIndirect, CreateDialogIndirectParam, DeleteObject, DialogBoxIndirect, DialogBoxIndirectParam, WM_INITDIALOG, DLGTEMPLATE


WM_SETHOTKEY

An application sends a WM_SETHOTKEY message to a window to associate a hot key with the window. When the user presses the hot key, the system activates the window.

WM_SETHOTKEY

wParam = (WPARAM) MAKEWORD(vkey, modifiers)   // virtual-key code and modifiers of hot key

lParam = 0;                                   // not used; must be zero

Parameters

vkey

Value of wParam. Specifies the virtual-key code and modifiers of the hot key to associate with the window. The virtual-key code is in the low byte of the parameter and the modifier flags are in the high byte. Setting this parameter to NULL removes the hot key associated with a window. The modifier byte can be a combination of the following flags:

Value	Meaning
HOTKEYF_ALT	ALT key
HOTKEYF_CONTROL	CTRL key
HOTKEYF_EXT	Extended key
HOTKEYF_SHIFT	SHIFT key
Return Values

The return value is one of the following:

Value	Meaning
−1	The function is unsuccessful — the hot key is invalid.
..0	The function is unsuccessful — the window is invalid.
..1	The function is successful, and no other window has the same hot key.
..2	The function is successful, but another window already has the same hot key.
Remarks

A hot key cannot be associated with a child window.

VK_ESCAPE, VK_SPACE, and VK_TAB are invalid hot keys.

When the user presses the hot key, the system generates a WM_SYSCOMMAND message with wParam equal to SC_HOTKEY.

A window can only have one hot key. If the window already has a hot key associated with it, the new hot key replaces the old one. If more than one window has the same hot key, the window that is activated by the hot key is random.

These hot keys are unrelated to the hot keys set by RegisterHotKey.

See Also

RegisterHotKey, WM_GETHOTKEY, WM_SYSCOMMAND


WM_SETICON

An application sends the WM_SETICON message to associate a new large or small icon with a window. Windows draws the large icon when the window is minimized, and the small icon in the window’s title bar.

WM_SETICON

wParam = (WPARAM) fType;          // icon type

lParam = (LPARAM) (HICON) hicon;  // handle of icon

Parameters

fType

Value of wParam. Specifies the type of icon being set. This parameter can be one of the following values:

Value	Meaning
ICON_BIG	Set the large icon for the window.
ICON_SMALL	Set the small icon for the window.
hicon

Value of lParam. Identifies the new large or small icon. If this parameter is NULL, the icon indicated by fType is removed.

Return Values

The return value is the handle of the previous large or small icon, depending on the value of fType. It is NULL if the window previously had no icon of the type indicated by fType.

Default Action

The DefWindowProc function returns the handle of the previous large or small icon associated with the window, depending on the value of fType.

See Also

DefWindowProc, WM_GETICON


WM_SETREDRAW

An application sends the WM_SETREDRAW message to a window to allow changes in that window to be redrawn or to prevent changes in that window from being redrawn.

WM_SETREDRAW

wParam = (WPARAM) fRedraw;  // state of redraw flag

lParam = 0;                 // not used; must be zero

Parameters

fRedraw

Value of wParam. Specifies the state of the redraw flag. If this parameter is TRUE, the redraw flag is set. If the parameter is FALSE, the flag is cleared.

Return Values

An application should return zero if it processes this message.

Remarks

This message sets or clears the redraw flag. If the redraw flag is cleared, the content of the given window is not updated after each change, and the window is not repainted until the redraw flag is set. For example, an application that must add several items to a list box can clear the redraw flag, add the items, and then set the redraw flag. Finally, the application can call the InvalidateRect function to cause the list box to be repainted.

See Also

InvalidateRect


WM_SETTEXT

An application sends a WM_SETTEXT message to set the text of a window.

WM_SETTEXT

wParam = 0;                     // not used; must be zero

lParam = (LPARAM)(LPCTSTR)lpsz; // address of window-text string

Parameters

lpsz

Value of lParam. Points to a null-terminated string that is the window text.

Return Values

The return value is TRUE if the text is set. It is FALSE (for an edit control), LB_ERRSPACE (for a list box), or CB_ERRSPACE (for a combo box) if insufficient space is available to set the text in the edit control. It is CB_ERR if this message is sent to a combo box without an edit control.

Default Action

The DefWindowProc function sets and displays the window text.

Remarks

For an edit control, the text is the contents of the edit control. For a combo box, the text is the contents of the edit-control portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title.

This message does not change the current selection in the list box of a combo box. An application should use the CB_SELECTSTRING message to select the item in a list box that matches the text in the edit control.

See Also

DefWindowProc, CB_SELECTSTRING, WM_GETTEXT


WM_SETTINGCHANGE

The system sends the WM_SETTINGCHANGE message to all top-level windows when the SystemParametersInfo function changes a system-wide setting. The system sends this message only if the SystemParametersInfo caller specifies the SPIF_SENDCHANGE flag.

An application can send WM_SETTINGCHANGE to all top-level windows when it makes changes to system parameters. For example, you can send this message after a call to the WriteProfileString, WriteProfileSection, or SetLocaleInfo functions, or after making changes to system parameters in the registry.

The WM_SETTINGCHANGE message is the same as the older WM_WININICHANGE message.

WM_SETTINGCHANGE

wParam = wFlag;                         // system-wide parameter flag

lParam = (LPARAM) (LPCTSTR) pszSection; // name of changed section or registry

Parameters

wFlag

Value of wParam. When the system sends the message as a result of a SystemParametersInfo call, this parameter is a flag that indicates the system parameter that was changed. For a list of values, see the SystemParametersInfo function.

When an application sends the message, this parameter must be NULL.

pszMetrics

Value of lParam. Pointer to a string that indicates the area containing the system parameter that was changed. For example, this string can be the name of a registry key or the name of a section in the WIN.INI file.

This parameter is not particularly useful in determining which system parameter changed. For example, when the string is a registry name, it typically indicates only the leaf node in the registry, not the whole path. In addition, some applications send this message with lParam set to NULL. In general, when you receive this message, you should check and reload any system parameter settings that are used by your application.

Return Values

If you process this message, return zero.

Remarks

To send the WM_SETTINGCHANGE message to all top-level windows, use the SendMessage function with the hwnd parameter set to HWND_BROADCAST.

Calls to functions that change the WIN.INI file might be mapped to the registry instead. This mapping occurs when the WIN.INI file and the section being changed are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

The change in the storage location has no effect on the behavior of this message.

See Also

SendMessage, SetLocaleInfo, SystemParametersInfo, WM_WININICHANGE, WriteProfileSection, WriteProfileString


WM_SHOWWINDOW

The WM_SHOWWINDOW message is sent to a window when the window is about to be hidden or shown.

WM_SHOWWINDOW

fShow = (BOOL) wParam;      // show/hide flag

fnStatus = (int) lParam;    // status flag

Parameters

fShow

Value of wParam. Specifies whether a window is being shown. It is TRUE if the window is being shown or FALSE if the window is being hidden.

fnStatus

Value of lParam. Specifies the status of the window being shown. The fnStatus parameter is zero if the message is sent because of a call to the ShowWindow function; otherwise, fnStatus is one of the following values:

Value	Meaning
SW_OTHERUNZOOM	Window is being uncovered because a maximize window was restored or minimized.
SW_OTHERZOOM	Window is being covered by another window that has been maximized.
SW_PARENTCLOSING	Window’s owner window is being minimized.
SW_PARENTOPENING	Window’s owner window is being restored.
Return Values

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function hides or shows the window, as specified by the message.

Remarks

If a window has the WS_VISIBLE style when it is created, the window receives this message after it is created, but before it is displayed. A window also receives this message when its visibility state is changed by the ShowWindow or ShowOwnedPopups function.

The WM_SHOWWINDOW message is not sent under the following circumstances:

•	When a top-level, overlapped window is created with the WS_MAXIMIZE or WS_MINIMIZE style.

•	When the SW_SHOWNORMAL flag is specified in the call to the ShowWindow function.

See Also

DefWindowProc, ShowOwnedPopups, ShowWindow


WM_SIZE

The WM_SIZE message is sent to a window after its size has changed.

WM_SIZE

fwSizeType = wParam;      // resizing flag

nWidth = LOWORD(lParam);  // width of client area

nHeight = HIWORD(lParam); // height of client area

Parameters

fwSizeType

Value of wParam. Specifies the type of resizing requested. This parameter can be one of the following values:

Value	Meaning
SIZE_MAXHIDE	Message is sent to all pop-up windows when some other window is maximized.
SIZE_MAXIMIZED	Window has been maximized.
SIZE_MAXSHOW	Message is sent to all pop-up windows when some other window has been restored to its former size.
SIZE_MINIMIZED	Window has been minimized.
SIZE_RESTORED	Window has been resized, but neither the SIZE_MINIMIZED nor SIZE_MAXIMIZED value applies.
nWidth

Value of the low-order word of lParam. Specifies the new width of the client area.

nHeight

Value of the high-order word of lParam. Specifies the new height of the client area.

Return Values

If an application processes this message, it should return zero.

Remarks

If the SetScrollPos or MoveWindow function is called for a child window as a result of the WM_SIZE message, the bRedraw parameter should be nonzero to cause the window to be repainted.

Although the width and height of a window are 32-bit values, the nWidth and nHeight parameters of the WM_SIZE message contain only the low-order 16 bits.

See Also

MoveWindow, SetScrollPos


WM_SIZECLIPBOARD

The WM_SIZECLIPBOARD message is sent to the clipboard owner by a clipboard viewer window when the clipboard contains data in the CF_OWNERDISPLAY format and the clipboard viewer’s client area has changed size.

WM_SIZECLIPBOARD

hwndViewer = (HWND) wParam;  // handle of clipboard viewer window

hglbRc = (HGLOBAL) lParam;   // handle of RECT object

Parameters

hwndViewer

Value of wParam. Identifies the clipboard viewer window.

hglbRc

Value of lParam. Identifies a global memory object that contains a RECT structure. The structure specifies the new dimensions of the clipboard viewer’s client area.

Remarks

When the clipboard viewer window is about to be destroyed or resized, a WM_SIZECLIPBOARD message is sent with a null rectangle (0, 0, 0, 0) as the new size. This permits the clipboard owner to free its display resources.

The clipboard owner must use the GlobalLock function to lock the memory object that contains RECT. Before returning, the clipboard owner must unlock the object by using the GlobalUnlock function.

See Also

GlobalLock, GlobalUnlock, RECT


WM_SIZING

The WM_SIZING message is sent to a window that the user is resizing. By processing this message, an application can monitor the size and position of the drag rectangle and, if needed, change its size or position.

fwSide = wParam;         // edge of window being sized

lprc = (LPRECT) lParam;  // screen coordinates of drag rectangle

Parameters

fwSide

Value of wParam. Indicates which edge of the window is being sized. This parameter can be a combination of the following values:

Value	Meaning
WMSZ_BOTTOM	Bottom edge
WMSZ_BOTTOMLEFT	Bottom-left corner
WMSZ_BOTTOMRIGHT	Bottom-right corner
WMSZ_LEFT	Left edge
WMSZ_RIGHT	Right edge
WMSZ_TOP	Top edge
WMSZ_TOPLEFT	Top-left corner
WMSZ_TOPRIGHT	Top-right corner
lprc

Address of a RECT structure with the screen coordinates of the drag rectangle. To change the size or position of the drag rectangle, an application must change the members of this structure.

Return Values

An application should return TRUE if it processes this message.

See Also

RECT, WM_MOVING, WM_SIZE


WM_SPOOLERSTATUS

The WM_SPOOLERSTATUS message is sent from Windows Print Manager whenever a job is added to or removed from the Print Manager queue.

WM_SPOOLERSTATUS

fwJobStatus = wParam;       // job-status flag

cJobsLeft = LOWORD(lParam); // number of jobs remaining

Parameters

fwJobStatus

Value of wParam. Specifies the PR_JOBSTATUS flag.

cJobsLeft

Value of the low-order word of lParam. Specifies the number of jobs remaining in the Print Manager queue.

Return Values

An application should return zero if it processes this message.

Remarks

This message is for informational purposes only.


WM_STYLECHANGED

The WM_STYLECHANGED message is sent to a window after the SetWindowLong function has changed one or more of the window’s styles.

WM_STYLECHANGED

wStyleType = wParam;            // extended or nonextended styles

lpss = (LPSTYLESTRUCT) lParam;  // structure containing new styles

Parameters

wStyleType

Value of wParam. Specifies whether the window’s extended or nonextended styles have changed. This parameter can be a combination of the following values:

Value	Meaning
GWL_EXSTYLE	The window’s extended styles have changed.
GWL_STYLE	The window’s nonextended styles have changed.
lpss

Value of lParam. Points to a STYLESTRUCT structure that contains the new styles for the window. An application can examine the styles, but can not change them.

Return Values

An application should return zero if it processes this message.

See Also

SetWindowLong, STYLESTRUCT, WM_STYLECHANGING


WM_STYLECHANGING

The WM_STYLECHANGING message is sent to a window when the SetWindowLong function is about to change one or more of the window’s styles.

WM_STYLECHANGING

wStyleType = wParam;            // extended or nonextended styles

lpss = (LPSTYLESTRUCT) lParam;  // structure containing new styles

Parameters

wStyleType

Value of wParam. Specifies whether the window’s extended or nonextended styles have changed. This parameter can be a combination of the following values:

Value	Meaning
GWL_EXSTYLE	The window’s extended styles are changing.
GWL_STYLE	The window’s nonextended styles are changing.
lpss

Value of lParam. Points to a STYLESTRUCT structure that contains the proposed new styles for the window. An application can examine the styles and, if necessary, change them.

Return Values

An application should return zero if it processes this message.

See Also

STYLESTRUCT, WM_STYLECHANGED


WM_SYSCHAR

The WM_SYSCHAR message is posted to the window with the keyboard focus when a WM_SYSKEYDOWN message is translated by the TranslateMessage function. It specifies the character code of a system character key — that is, a character key that is pressed while the ALT key is down.

WM_SYSCHAR

chCharCode = (TCHAR) wParam;   // character code

lKeyData = lParam;             // key data

Parameters

chCharCode

Value of wParam. Specifies the character code of the window menu key.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table:

Value	Meaning
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30	Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31	Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.
Return Values

An application should return zero if it processes this message.

Remarks

When the context code is zero, the message can be passed to the TranslateAccelerator function, which will handle it as though it were a standard key message instead of a system character-key message. This allows accelerator keys to be used with the active window even if the active window does not have the keyboard focus.

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; the PRINT SCRN key; the BREAK key; the NUMLOCK key; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

TranslateAccelerator, TranslateMessage, WM_SYSKEYDOWN


WM_SYSCOLORCHANGE

The WM_SYSCOLORCHANGE message is sent to all top-level windows when a change is made to a system color setting.

WM_SYSCOLORCHANGE

Parameters

This message has no parameters.

Remarks

Windows sends a WM_PAINT message to any window that is affected by a system color change.

Applications that have brushes using the existing system colors should delete those brushes and recreate them using the new system colors.

Top level windows that use common controls must forward the WM_SYSCOLORCHANGE message to the controls; otherwise, the controls will not be notified of the color change. This ensures that the colors used by your common controls are consistent with those used by other user interface objects. For example, a toolbar control uses the "3D Objects" color to draw its buttons. If the user changes the 3D Objects color but the WM_SYSCOLORCHANGE message is not forwarded to the toolbar, the toolbar buttons will remain in their original color while the color of other buttons in the system changes.

See Also

WM_PAINT


WM_SYSCOMMAND

A window receives this message when the user chooses a command from the window menu (also known as the System menu or Control menu) or when the user chooses the Maximize button or Minimize button.

WM_SYSCOMMAND

uCmdType = wParam;        // type of system command requested

xPos = LOWORD(lParam);    // horizontal postion, in screen coordinates

yPos = HIWORD(lParam);    // vertical postion, in screen coordinates

Parameters

uCmdType

Specifies the type of system command requested. This can be one of these values:

Value	Meaning
SC_CLOSE	Closes the window.
SC_CONTEXTHELP	Changes the cursor to a question mark with a pointer. If the user then clicks a control in the dialog box, the control receives a WM_HELP message.
SC_DEFAULT	Selects the default item; the user double-clicked the window menu.
SC_HOTKEY	Activates the window associated with the application-specified hot key. The low-order word of lParam identifies the window to activate.
SC_HSCROLL	Scrolls horizontally.
SC_KEYMENU	Retrieves the window menu as a result of a keystroke.
SC_MAXIMIZE (or SC_ZOOM)	Maximizes the window.
SC_MINIMIZE (or SC_ICON)	Minimizes the window.
SC_MONITORPOWER	Windows 95 only: Sets the state of the display. This command supports devices that have power-saving features, such as a battery-powered personal computer.
SC_MOUSEMENU	Retrieves the window menu as a result of a mouse click.
SC_MOVE	Moves the window.
SC_NEXTWINDOW	Moves to the next window.
SC_PREVWINDOW	Moves to the previous window.
SC_RESTORE	Restores the window to its normal position and size.
SC_SCREENSAVE	Executes the screen saver application specified in the [boot] section of the SYSTEM.INI file.
SC_SIZE	Sizes the window.
SC_TASKLIST	Executes or activates Windows Task Manager.
SC_VSCROLL	Scrolls vertically.
xPos

Specifies the horizontal position of the cursor, in screen coordinates, if a window menu command is chosen with the mouse. Otherwise, the xPos parameter is not used.

yPos

Specifies the vertical position of the cursor, in screen coordinates, if a window menu command is chosen with the mouse. This parameter is −1 if the command is chosen using a system accelerator, or zero if using a mnenomic.

Return Values

An application should return zero if it processes this message.

Remarks

The DefWindowProc function carries out the window menu request for the predefined actions specified in the previous table.

In WM_SYSCOMMAND messages, the four low-order bits of the uCmdType parameter are used internally by Windows. To obtain the correct result when testing the value of uCmdType, an application must combine the value 0xFFF0 with the uCmdType value by using the bitwise AND operator.

The menu items in a window menu can be modified by using the GetSystemMenu, AppendMenu, InsertMenu, ModifyMenu, InsertMenuItem, and SetMenuItem functions. Applications that modify the window menu must process WM_SYSCOMMAND messages.

An application can carry out any system command at any time by passing a WM_SYSCOMMAND message to DefWindowProc. Any WM_SYSCOMMAND messages not handled by the application must be passed to DefWindowProc. Any command values added by an application must be processed by the application and cannot be passed to DefWindowProc.

Accelerator keys that are defined to choose items from the window menu are translated into WM_SYSCOMMAND messages; all other accelerator keystrokes are translated into WM_COMMAND messages.

See Also

AppendMenu, DefWindowProc, GetSystemMenu, InsertMenu, ModifyMenu, WM_COMMAND


WM_SYSDEADCHAR

The WM_SYSDEADCHAR message is sent to the window with the keyboard focus when a WM_SYSKEYDOWN message is translated by the TranslateMessage function. WM_SYSDEADCHAR specifies the character code of a system dead key — that is, a dead key that is pressed while holding down the ALT key.

WM_SYSDEADCHAR

chCharCode = (TCHAR) wParam;    // character code

lKeyData = lParam;              // key data

Parameters

chCharCode

Value of wParam. Specifies the character code generated by the system dead key — that is, a dead key that is pressed while holding down the ALT key.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table:

Value	Description
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30	Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31	Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.
Return Values

An application should return zero if it processes this message.

Remarks

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

TranslateMessage, WM_DEADCHAR, WM_SYSKEYDOWN


WM_SYSKEYDOWN

The WM_SYSKEYDOWN message is posted to the window with the keyboard focus when the user holds down the ALT key and then presses another key. It also occurs when no window currently has the keyboard focus; in this case, the WM_SYSKEYDOWN message is sent to the active window. The window that receives the message can distinguish between these two contexts by checking the context code in the lKeyData parameter.

WM_SYSKEYDOWN

nVirtKey = (int) wParam;    // virtual-key code

lKeyData = lParam;          // key data

Parameters

nVirtKey

Value of wParam. Specifies the virtual-key code of the key being pressed.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table:

Value	Description
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is 1 if the ALT key is down while the key is pressed; it is 0 if the WM_SYSKEYDOWN message is posted to the active window because no window has the keyboard focus.
30	Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31	Specifies the transition state. The value is always 0 for a WM_SYSKEYDOWN message.
Return Values

An application should return zero if it processes this message.

Default Action

The DefWindowProc function examines the given key and generates a WM_SYSCOMMAND message if the key is either TAB or ENTER.

Remarks

When the context code is zero, the message can be passed to the TranslateAccelerator function, which will handle it as though it were a normal key message instead of a system character-key message. This allows accelerator keys to be used with the active window even if the active window does not have the keyboard focus.

Because of automatic repeat, more than one WM_SYSKEYDOWN message may occur before a WM_SYSKEYUP message is sent. The previous key state (bit 30) can be used to determine whether the WM_SYSKEYDOWN message indicates the first down transition or a repeated down transition.

For enhanced 101- and 102-key keyboards, enhanced keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lParam parameter.

See Also

DefWindowProc, TranslateAccelerator, WM_SYSCOMMAND, WM_SYSKEYUP


WM_SYSKEYUP

The WM_SYSKEYUP message is posted to the window with the keyboard focus when the user releases a key that was pressed while the ALT key was held down. It also occurs when no window currently has the keyboard focus; in this case, the WM_SYSKEYUP message is sent to the active window. The window that receives the message can distinguish between these two contexts by checking the context code in the lKeyData parameter.

WM_SYSKEYUP

nVirtKey = (int) wParam;    // virtual-key code

lKeyData = lParam;          // key data

Parameters

nVirtKey

Value of wParam. Specifies the virtual-key code of the key being released.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table:

Value	Description
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key. The repeat count is always one for a WM_SYSKEYUP message.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is 1 if the ALT key is down while the key is released; it is 0 if the WM_SYSKEYDOWN message is posted to the active window because no window has the keyboard focus.
30	Specifies the previous key state. The value is always 1 for a WM_SYSKEYUP message.
31	Specifies the transition state. The value is always 1 for a WM_SYSKEYUP message.
Return Values

An application should return zero if it processes this message.

Default Action

The DefWindowProc function sends a WM_SYSCOMMAND message to the top-level window if the F10 key or the ALT key was released. The wParam parameter of the message is set to SC_KEYMENU.

Remarks

When the context code is zero, the message can be passed to the TranslateAccelerator function, which will handle it as though it were a normal key message instead of a system character-key message. This allows accelerator keys to be used with the active window even if the active window does not have the keyboard focus.

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lKeyData parameter.

For non-U.S. enhanced 102-key keyboards, the right ALT key is handled as a CTRL+ALT key. The following table shows the sequence of messages that result when the user presses and releases this key:

Message	Virtual-key code
WM_KEYDOWN	VK_CONTROL
WM_KEYDOWN	VK_MENU
WM_KEYUP	VK_CONTROL
WM_SYSKEYUP	VK_MENU
See Also

DefWindowProc, TranslateAccelerator, WM_SYSCOMMAND, WM_SYSKEYDOWN


WM_TCARD

The WM_TCARD message is sent to an application that has initiated a training card with Windows Help. The message informs the application when the user clicks an authorable button. An application initiates a training card by specifying the HELP_TCARD command in a call to the WinHelp function.

WM_TCARD

idAction = wParam;

dwActionData = lParam;

Parameters

idAction

Value of wParam. Indicates the action the user has taken. This parameter can be one of these values:

Value	Meaning
IDABORT	The user clicked an authorable Abort button.
IDCANCEL	The user clicked an authorable Cancel button.
IDCLOSE	The user closed the training card.
IDHELP	The user clicked an authorable Windows Help button.
IDIGNORE	The user clicked an authorable Ignore button.
IDOK	The user clicked an authorable OK button.
IDNO	The user clicked an authorable No button.
IDRETRY	The user clicked an authorable Retry button.
HELP_TCARD_DATA	The user clicked an authorable button. The lParam parameter contains a long integer specified by the help author.
HELP_TCARD_NEXT	The user clicked an authorable Next button.
HELP_TCARD_OTHER_CALLER	Another application has requested training cards.
IDYES	The user clicked an authorable Yes button.
dwActionData

Value of lParam. If idAction specifies HELP_TCARD_DATA, this parameter is a long integer specified by the help author. Otherwise, this parameter is zero.

Return Values

The return value is ignored; use zero.

See Also

WinHelp


WM_TIMECHANGE

An application sends the WM_TIMECHANGE message to all top-level windows after changing the system time.

WM_TIMECHANGE

wParam = 0; // not used, must be zero

lParam = 0; // not used, must be zero

Parameters

This message has no parameters.

Return Values

An application should return zero if it processes this message.

Remarks

An application that changes the system time should send this message to all top-level windows. To send the WM_TIMECHANGE message to all top-level windows, an application can use the SendMessage function with the hwnd parameter set to HWND_TOPMOST.

See Also

SendMessage


WM_TIMER

The WM_TIMER message is posted to the installing thread’s message queue or sent to the appropriate TimerProc callback function after each interval specified in the SetTimer function used to install a timer.

WM_TIMER

wTimerID = wParam;            // timer identifier

tmprc = (TIMERPROC *) lParam; // address of timer callback

Parameters

wTimerID

Value of wParam. Specifies the timer identifier.

tmprc

Value of lParam. Points to an application-defined callback function that was passed to the SetTimer function when the timer was installed. If the tmprc parameter is not NULL, Windows passes the WM_TIMER message to the specified callback function rather than posting the message to the thread’s message queue.

Return Values

An application should return zero if it processes this message.

Remarks

The DispatchMessage function forwards this message when no other messages are in the thread’s message queue.

See Also

DispatchMessage, SetTimer, TimerProc


WM_UNDO

An application sends a WM_UNDO message to an edit control to undo the last operation. When this message is sent to an edit control, the previously deleted text is restored or the previously added text is deleted.

WM_UNDO

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

Parameters

This message has no parameters.

Return Values

If the message succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

WM_CLEAR, WM_COPY, WM_CUT, WM_PASTE


WM_USER

The WM_USER constant is used by applications to help define private messages.

WM_USER

Remarks

The WM_USER constant is used to distinguish between message values that are reserved for use by Windows and values that can be used by an application to send messages within a private window class. There are five ranges of message numbers:

Range	Meaning
0 through WM_USER − 1	Messages reserved for use by Windows.
WM_USER through 0x7FFF	Integer messages for use by private window classes.
0x8000 through 0xBFFF	Messages reserved for future use by Windows.
0xC000 through 0xFFFF	String messages for use by applications.
Greater than 0xFFFF	Reserved by Windows for future use.
Message numbers in the first range (0 through WM_USER − 1) are defined by Windows. Values in this range that are not explicitly defined are reserved for future use by Windows.

Message numbers in the second range (WM_USER through 0x7FFF) can be defined and used by an application to send messages within a private window class. These values cannot be used to define messages that are meaningful throughout an application, because some predefined window classes already define values in this range. For example, predefined control classes such as BUTTON, EDIT, LISTBOX, and COMBOBOX may use these values. Messages in this range should not be sent to other applications unless the applications have been designed to exchange messages and to attach the same meaning to the message numbers.

Message numbers in the third range (0x8000 through 0xBFFF) are reserved for future use by Windows.

Message numbers in the fourth range (0xC000 through 0xFFFF) are defined at run time when an application calls the RegisterWindowMessage function to retrieve a message number for a string. All applications that register the same string can use the associated message number for exchanging messages. The actual message number, however, is not a constant and cannot be assumed to be the same between different Windows sessions.

Message numbers in the fifth range (greater than 0xFFFF) are reserved for future use by Windows.

See Also

RegisterWindowMessage


WM_USERCHANGED

The WM_USERCHANGED message is sent to all windows after the user has logged on or off. When the user logs on or off, the system updates the user-specific settings. The system sends this message immediately after updating the settings.

WM_USERCHANGED

wParam = 0;       // not used, must be zero

lParam = 0;       // not used, must be zero

Return Values

An application should return zero if it processes this message.


WM_VKEYTOITEM

The WM_VKEYTOITEM message is sent by a list box with the LBS_WANTKEYBOARDINPUT style to its owner in response to a WM_KEYDOWN message.

WM_VKEYTOITEM

vkey = LOWORD(wParam);      // virtual-key code

nCaretPos = HIWORD(wParam); // caret position

hwndLB = lParam;            // handle of list box

Parameters

vkey

Value of the low-order word of wParam. Specifies the virtual-key code of the key the user pressed.

nCaretPos

Value of the high-order word of wParam. Specifies the current position of the caret.

hwndLB

Value of lParam. Identifies the list box.

Return Values

The return value specifies the action that the application performed in response to the message. A return value of −2 indicates that the application handled all aspects of selecting the item and requires no further action by the list box. A return value of −1 indicates that the list box should perform the default action in response to the keystroke. A return value of 0 or greater specifies the index of an item in the list box and indicates that the list box should perform the default action for the keystroke on the given item.

Default Action

The DefWindowProc function returns −1.

See Also

DefWindowProc, WM_CHARTOITEM, WM_KEYDOWN


WM_VSCROLL

The WM_VSCROLL message is sent to a window when a scroll event occurs in the window’s standard vertical scroll bar. This message is also sent to the owner of a vertical scroll bar control when a scroll event occurs in the control.

WM_VSCROLL

nScrollCode = (int) LOWORD(wParam); // scroll bar value

nPos = (short int) HIWORD(wParam);  // scroll box position

hwndScrollBar = (HWND) lParam;      // handle of scroll bar

Parameters

nScrollCode

Value of the low-order word of wParam. Specifies a scroll bar value that indicates the user’s scrolling request. This parameter can be one of the following values:

Value	Meaning
SB_BOTTOM	Scrolls to the lower right.
SB_ENDSCROLL	Ends scroll.
SB_LINEDOWN	Scrolls one line down.
SB_LINEUP	Scrolls one line up.
SB_PAGEDOWN	Scrolls one page down.
SB_PAGEUP	Scrolls one page up.
SB_THUMBPOSITION	Scrolls to the absolute position. The current position is specified by the nPos parameter.
SB_THUMBTRACK	Drags scroll box to the specified position. The current position is specified by the nPos parameter.
SB_TOP	Scrolls to the upper left.
nPos

Value of the high-order word of wParam. Specifies the current position of the scroll box if the nScrollCode parameter is SB_THUMBPOSITION or SB_THUMBTRACK; otherwise, nPos is not used.

hwndScrollBar

Value of lParam. Identifies the control if WM_VSCROLL is sent by a scroll bar control. If WM_VSCROLL is sent by a window’s standard scroll bar, hwndScrollBar is not used.

Return Values

If an application processes this message, it should return zero.

Remarks

The SB_THUMBTRACK notification message is typically used by applications that provide feedback as the user drags the scroll box.

If an application scrolls the content of the window, it must also reset the position of the scroll box by using the SetScrollPos function.

Note that the WM_VSCROLL message carries only 16 bits of scroll box position data. Thus, applications that rely solely on WM_VSCROLL (and WM_HSCROLL) for scroll position data have a practical maximum position value of 65,535.

However, because the SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange functions support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier of the WM_HSCROLL and WM_VSCROLL messages. See GetScrollPos for a description of the technique and its limits.

See Also

GetScrollPos, GetScrollRange, SetScrollPos, SetScrollRange, WM_HSCROLL


WM_VSCROLLCLIPBOARD

The WM_VSCROLLCLIPBOARD message is sent to the clipboard owner by a clipboard viewer window when the clipboard contains data in the CF_OWNERDISPLAY format and an event occurs in the clipboard viewer’s vertical scroll bar. The owner should scroll the clipboard image and update the scroll bar values.

WM_VSCROLLCLIPBOARD

hwndViewer = (HWND) wParam;         // handle of clipboard viewer window

nScrollCode = (int) LOWORD(lParam); // scroll bar code

nPos = (int) HIWORD(lParam);        // scroll box position

Parameters

hwndViewer

Value of wParam. Identifies the clipboard viewer window.

nScrollCode

Value of the low-order word of lParam. Specifies a scroll bar event. This parameter can be one of the following values:

Value	Meaning
SB_BOTTOM	Scroll to lower right.
SB_ENDSCROLL	End scroll.
SB_LINEDOWN	Scroll one line down.
SB_LINEUP	Scroll one line up.
SB_PAGEDOWN	Scroll one page down.
SB_PAGEUP	Scroll one page up.
SB_THUMBPOSITION	Scroll to absolute position. The current position is specified by the nPos parameter.
SB_TOP	Scroll to upper left.
nPos

Value of the high-order word of lParam. Specifies the current position of the scroll box if the nScrollCode parameter is SB_THUMBPOSITION; otherwise, the nPos parameter is not used.

Return Values

If an application processes this message, it should return zero.

Remarks

The clipboard owner can use the ScrollWindow function to scroll the image in the clipboard viewer window and invalidate the appropriate region.

See Also

ScrollWindow


WM_WINDOWPOSCHANGED

The WM_WINDOWPOSCHANGED message is sent to a window whose size, position, or place in the Z order has changed as a result of a call to the SetWindowPos function or another window-management function.

WM_WINDOWPOSCHANGED

lpwp = (LPWINDOWPOS) lParam; // points to size and position data

Parameters

lpwp

Value of lParam. Points to a WINDOWPOS structure that contains information about the window’s new size and position.

Return Values

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function sends the WM_SIZE and WM_MOVE messages to the window.

Remarks

The WM_SIZE and WM_MOVE messages are not sent if an application handles the WM_WINDOWPOSCHANGED message without calling DefWindowProc. It is more efficient to perform any move or size change processing during the WM_WINDOWPOSCHANGED message without calling DefWindowProc.

See Also

DefWindowProc, EndDeferWindowPos, SetWindowPos, WINDOWPOS, WM_MOVE, WM_SIZE, WM_WINDOWPOSCHANGING


WM_WINDOWPOSCHANGING

The WM_WINDOWPOSCHANGING message is sent to a window whose size, position, or place in the Z order is about to change as a result of a call to the SetWindowPos function or another window-management function.

WM_WINDOWPOSCHANGING

lpwp = (LPWINDOWPOS) lParam; // points to size and position data

Parameters

lpwp

Value of lParam. Points to a WINDOWPOS structure that contains information about the window’s new size and position.

Return Values

If an application processes this message, it should return zero.

Default Action

For a window with the WS_OVERLAPPED or WS_THICKFRAME style, the DefWindowProc function sends the WM_GETMINMAXINFO message to the window. This is done to validate the new size and position of the window and to enforce the CS_BYTEALIGNCLIENT and CS_BYTEALIGNWINDOW client styles. By not passing the WM_WINDOWPOSCHANGING message to the DefWindowProc function, an application can override these defaults.

Remarks

While this message is being processed, modifying any of the values in WINDOWPOS affects the window’s new size, position, or place in the Z order. An application can prevent changes to the window by setting or clearing the appropriate bits in the flags member of WINDOWPOS.

See Also

DefWindowProc, EndDeferWindowPos, SetWindowPos, WINDOWPOS, WM_GETMINMAXINFO, WM_MOVE, WM_SIZE, WM_WINDOWPOSCHANGED


WM_WININICHANGE

The WM_WININICHANGE is obsolete. It is included for compatibility with earlier versions of Windows. New applications should use the WM_SETTINGCHANGE message.


Animate_Close

The Animate_Close macro closes an AVI clip and displays its first frame in an animation control. You can use this macro or explicitly send the ACM_OPEN message.

BOOL Animate_Close(

HWND hwnd
);
Parameters

hwnd

Handle to the animation control.

Return Values

The Animate_Close macro always returns FALSE.

Remarks

You can use Animate_Close to close an .AVI file or AVI resource that was previously opened for the specified animation control.

The Animate_Close macro is defined in COMMCTRL.H.

See Also

ACM_OPEN, Animate_Open, MAKEINTRESOURCE


Animate_Create

The Animate_Create macro creates an animation control. Animate_Create calls the CreateWindow function.

HWND Animate_Create(

HWND hwndP,
UINT id,
DWORD dwStyle,
HINSTANCE hInstance
);
Parameters

hwndP

Handle to the parent window.

id

Child window identifier of the animation control.

dwStyle

Window styles. For a list of the animation-control style values, see Animation Control Styles.

hInstance

Handle to the instance of the module that is creating the animation control.

Return Values

Returns the handle to the animation control.

Remarks

The Animate_Create macro sets the width and height of the animation control to zero if the ACS_CENTER style is specified. If the ACS_CENTER style is not specified, Animate_Create sets the width and height based on the dimensions of a frame in the AVI clip.

See Also

CreateWindow


Animate_Open

The Animate_Open macro opens an AVI clip and displays its first frame in an animation control. You can use this macro or explicitly send the ACM_OPEN message.

BOOL Animate_Open(

hwnd,
lpszName
);
Parameters

hwnd

Handle to the animation control.

lpszName

Pointer to a buffer that contains the path of the .AVI file or the name of an AVI resource. Alternatively, this parameter can consist of the AVI resource identifier in the low-order word and zero in the high-order word. To create this value, use the MAKEINTRESOURCE macro. The control loads an AVI resource from the module specified by the instance handle passed to the CreateWindow function, the Animate_Create macro, or the dialog box creation function that created the control.

The AVI file or resource specified by lpszName must not contain audio. It must be silent.

If this parameter is NULL, the system closes the .AVI file that was previously opened for the specified animation control, if any.

Return Values

If the operation succeeds, the return value is a nonzero value.

If the operation fails, the return value is zero.

Remarks

You can only open silent AVI clips. AVI files or resources containing audio will not load. ACM_OPEN and Animate_Open fail if lpszSource specifies a non-silent AVI clip.

You can use Animate_Close to close an .AVI file or AVI resource that was previously opened for the specified animation control.

The Animate_Open macro is defined in COMMCTRL.H.

See Also

ACM_OPEN, Animate_Close, MAKEINTRESOURCE


Animate_Play

The Animate_Play macro plays an AVI clip in an animation control. The control plays the clip in the background while the thread continues executing. You can use this macro or explicitly send the ACM_PLAY message.

BOOL Animate_Play(

hwndAnim,
wFrom,
wTo,
cRepeat
);
Parameters

hwndAnim

Handle to the animation control in which to play the AVI clip.

wFrom

Zero-based index of the frame where playing begins. The value must be less than 65,536. A value of zero means begin with the first frame in the AVI clip.

wTo

Zero-based index of the frame where playing ends. The value must be less than 65,536. A value of  − 1 means end with the last frame in the AVI clip.

cRepeat

Number of times to replay the AVI clip. A value of  − 1 means replay the clip indefinitely.

Return Values

If the operation succeeds, the return value is a nonzero value.

If the operation fails, the return value is zero.

Remarks

You can use Animate_Seek to direct the animation control to display a particular frame of the AVI clip.

The Animate_Play macro is defined in COMMCTRL.H.

See Also

ACM_PLAY, Animate_Seek


Animate_Seek

The Animate_Seek macro directs an animation control to display a particular frame of an AVI clip. The control displays the clip in the background while the thread continues executing. You can use this macro or explicitly send the ACM_PLAY message.

BOOL Animate_Seek(

hwndAnim,
wFrame
);
Parameters

hwndAnim

Handle to the animation control in which to display  the AVI frame.

wFrame

Zero-based index of the frame to display.

Return Values

If the operation succeeds, the return value is a nonzero value.

If the operation fails, the return value is zero.

Remarks

The Animate_Seek macro is defined in COMMCTRL.H.

See Also

ACM_PLAY, Animate_Play


Animate_Stop

The Animate_Stop macro stops playing an AVI clip in an animation control. You can use this macro or explicitly send the ACM_STOP message.

BOOL Animate_Stop(

hwnd
);
Parameters

hwnd

Handle to the animation control.

Return Values

If the operation succeeds, the return value is a nonzero value.

If the operation fails, the return value is zero.

Remarks

The Animate_Stop macro is defined in COMMCTRL.H.

See Also

ACM_STOP


CMYK

The CMYK macro creates a CMYK color value by combining the specified cyan, magenta, yellow, and black values.

COLORREF CMYK(

c,
m,
y,
k
);
See Also

GetCValue, GetMValue, GetKValue, GetYValue


FORWARD_WM_NOTIFY

The FORWARD_WM_NOTIFY macro sends or posts the WM_NOTIFY message.

VOID FORWARD_WM_NOTIFY(

hwnd,
idFrom,
pnmhdr,
fn
);
Parameters

hwnd

Handle to the window that receives the WM_NOTIFY message.

idFrom

Identifier of the control sending the message.

pnmhdr

Pointer to an NMHDR structure that contains the notification code and additional information. For some notification messages, this parameter points to a larger structure that has the NMHDR structure as its first member.

fn

Function that sends or posts the WM_NOTIFY message. This parameter can be either the SendMessage or PostMessage function.

Return Values

Returns a value whose meaning depends on the fn parameter.

Remarks

The FORWARD_WM_NOTIFY macro is defined as follows:

#define FORWARD_WM_NOTIFY(hwnd, idFrom, pnmhdr, fn) \

    (void)(fn)((hwnd), WM_NOTIFY, (WPARAM)(int)(id), \

    (LPARAM)(NMHDR FAR*)(pnmhdr))

See Also

NMHDR, PostMessage, SendMessage, WM_NOTIFY


GetBValue

The GetBValue macro retrieves an intensity value for the blue component of a 32-bit red, green, blue (RGB) value.

BYTE GetBValue(

WORD rgb	// 32-bit RGB value
);
Parameters

rgb

Specifies an RGB color value.

Return Values

The return value is the intensity of the blue component of the specified RGB color.

Remarks

The intensity value is in the range 0 through 255.

The GetBValue macro is defined as follows:

#define GetBValue(rgb)   ((BYTE) ((rgb) >> 16))

See Also

GetGValue, GetRValue, PALETTEINDEX, PALETTERGB, RGB


GetCValue

The GetCValue macro retrieves the cyan color value from a CMYK color value.

BYTE GetCValue(

cmyk
);
See Also

CMYK, GetKValue, GetMValue, GetYValue


GetGValue

The GetGValue macro retrieves an intensity value for the green component of a 32-bit red, green, blue (RGB) value.

BYTE GetGValue(

DWORD rgb	// 32-bit RGB value
);
Parameters

rgb

Specifies an RGB color value.

Return Values

The return value is the intensity of the green component of the specified RGB color.

Remarks

The intensity value is in the range 0 through 255.

The GetGValue macro is defined as follows:

#define GetGValue(rgb)   ((BYTE) (((WORD) (rgb)) >> 8))

See Also

GetBValue, GetRValue, PALETTEINDEX, PALETTERGB, RGB


GetKValue

The GetKValue macro retrieves the black color value from a CMYK color value.

BYTE GetKValue(

cmyk
);
See Also

CMYK, GetCValue, GetMValue, GetYValue


GetMValue

The GetMValue macro retrieves the magenta color value from a CMYK color value.

BYTE GetMValue(

cmyk
);
See Also

CMYK, GetCValue, GetKValue, GetYValue


GetRValue

The GetRValue macro retrieves an intensity value for the red component of a 32-bit red, green, blue (RGB) value.

BYTE GetRValue(

DWORD rgb	// 32-bit RGB value
);
Parameters

rgb

Specifies an RGB color value.

Return Values

The return value is the intensity of the red component of the specified RGB color.

Remarks

The intensity value is in the range 0 through 255.

The GetRValue macro is defined as follows:

#define GetRValue(rgb)   ((BYTE) (rgb))

See Also

GetBValue, GetGValue, PALETTEINDEX, PALETTERGB, RGB


GetYValue

The GetYValue macro retrieves the yellow color value from a CMYK color value.

BYTE GetYValue(

cmyk
);
See Also

CMYK, GetCValue, GetMValue, GetKValue


HANDLE_WM_NOTIFY

The HANDLE_WM_NOTIFY macro calls a function that processes the WM_NOTIFY message.

HANDLE_WM_NOTIFY(

hwnd,
wParam,
lParam,
fn
);
Parameters

hwnd

Handle to the window that received WM_NOTIFY.

wParam

First parameter of WM_NOTIFY.

lParam

Second parameter of WM_NOTIFY.

fn

Function that is to process WM_NOTIFY.

Return Values

Returns a value whose meaning depends on the fn parameter.

Remarks

The HANDLE_WM_NOTIFY macro is defined as follows:

#define HANDLE_WM_NOTIFY(hwnd, wParam, lParam, fn) \

    (fn)((hwnd), (int)(wParam), (NMHDR FAR*)(lParam))

See Also

WM_NOTIFY


HasOverlappedIoCompleted [New - Windows NT]
HasOverlappedIoCompleted

[New - Windows NT]

The HasOverlappedIoCompleted macro provides a high performance test operation that can be used to poll for the completion of an outstanding I/O operation.

BOOL HasOverlappedIoCompleted(

LPOVERLAPPED lpOverlapped
);
Parameters

lpOverlapped

Points to an OVERLAPPED structure that was specified when the overlapped I/O operation was started.

Return Value

Returns TRUE if the I/O operation has completed, and FALSE otherwise.

Remarks

To cancel all pending asynchronous I/O operations, use the CancelIO function. This function only cancels operations issued by the calling thread for the specified file handle. I/O operations that are canceled complete with the error ERROR_OPERATION_ABORTED.

To get more details about a completed I/O operation, call the GetOverlappedResult or GetQueuedCompletionStatus function.

The HasOverlappedIoCompleted macro is defined as follows:

#define HasOverlappedIoCompleted(lpOverlapped) \

    ((lpOverlapped)->Internal != STATUS_PENDING)

See Also

CancelIo, ConnectNamedPipe, DeviceIoControl, OVERLAPPED, ReadFile, TransactNamedPipe, WaitCommEvent, WriteFile


Header_DeleteItem

The Header_DeleteItem macro deletes an item from a header control. You can use this macro or explicitly send the HDM_DELETEITEM message.

BOOL Header_DeleteItem(

hwndHD,
index
);
Parameters

hwndHD

Handle to the header control.

index

Index of the item to delete.

Return Values

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

Remarks

The Header_DeleteItem macro is defined as follows:

#define Header_DeleteItem(hwndHD, index)     \

      (BOOL)SendMessage((hwndHD), HDM_DELETEITEM, (WPARAM)(int)(index), 0L)

See Also

HDM_DELETEITEM


Header_GetItem

The Header_GetItem macro retrieves information about an item in a header control. You can use this macro or explicitly send the HDM_GETITEM message.

BOOL Header_GetItem(

hwndHD,
index,
phdi
);
Parameters

hwndHD

Handle to the header control.

index

Index of the item for which information is to be retrieved.

phdi

Pointer to an HD_ITEM structure. When the message is sent, the mask member indicates the type of information being requested. When the message returns, the other members receive the requested information. If the mask member specifies zero, the message returns TRUE but copies no information to the structure.

Return Values

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

Remarks

The Header_GetItem macro is defined as follows:

#define Header_GetItem(hwndHD, index, phdi)      \

    (BOOL)SendMessage((hwndHD), HDM_GETITEM,   \

    (WPARAM)(int)(index), (LPARAM)(HD_ITEM FAR*)(phdi))

See Also

HD_ITEM, HDM_GETITEM


Header_GetItemCount

The Header_GetItemCount macro retrieves a count of the items in a header control. You can use this macro or explicitly send the HDM_GETITEMCOUNT message.

int Header_GetItemCount(

hwndHD
);
Parameters

hwndHD

Handle to the header control.

Return Values

If the operation succeeds, the return value is the number of items.

If the operation fails, the return value is − 1.

Remarks

The Header_GetItemCount macro is defined as follows:

#define Header_GetItemCount(hwndHD)   \

       (int)SendMessage((hwndHD), HDM_GETITEMCOUNT, 0, 0L)

See Also

HDM_GETITEMCOUNT


Header_InsertItem

The Header_InsertItem macro inserts a new item into a header control. You can use this macro or explicitly send the HDM_INSERTITEM message.

int Header_InsertItem(

hwndHD,
index,
phdi
);
Parameters

hwndHD

Handle to the header control.

index

Index of the item after which the new item is to be inserted. The new item is inserted at the end of the header control if index is greater than or equal to the number of items in the control. If index is zero, the new item is inserted at the beginning of the header control.

phdi

Pointer to an HD_ITEM structure that contains information about the new item.

Return Values

If the operation succeeds, the return value is the index of the new item.

If the operation fails, the return value is − 1.

Remarks

The Header_InsertItem macro is defined as follows:

#define Header_InsertItem(hwndHD, index, phdi) \

    (int)SendMessage((hwndHD), HDM_INSERTITEM, (WPARAM)(int)(index), \

    (LPARAM)(const HD_ITEM FAR*)(phdi))

See Also

HDM_INSERTITEM, HD_ITEM


Header_Layout

The Header_Layout macro retrieves the size and position of a header control within a given rectangle. This macro is used to determine the appropriate dimensions for a new header control that is to occupy the given rectangle. You can use this macro or explicitly send the HDM_LAYOUT message.

BOOL Header_Layout(

hwndHD,
playout
);
Parameters

hwndHD

Handle to the header control.

playout

Pointer to an HD_LAYOUT structure. The prc member specifies the coordinates of a rectangle, and the pwpos member receives the size and position for the header control within the rectangle.

Return Values

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

Remarks

The Header_Layout macro is defined as follows:

#define Header_Layout(hwndHD, playout) \

    (BOOL)SendMessage((hwndHD), HDM_LAYOUT, 0, \

    (LPARAM)(HD_LAYOUT FAR*)(playout))

See Also

HD_LAYOUT, HDM_LAYOUT


Header_SetItem

The Header_SetItem macro sets the attributes of the specified item in a header control. You can use this macro or explicitly send the HDM_SETITEM message.

BOOL Header_SetItem(

hwndHD,
index,
phdi
);
Parameters

hwndHD

Handle to the header control.

index

Index of the item whose attributes are to be changed.

phdi

Pointer to an HD_ITEM structure. When the HDM_SETITEM message is sent, the mask member indicates the attributes to set. The other members specify new attributes.

Return Values

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

Remarks

The HDN_ITEMCHANGING notification message is sent to the parent window before the item attributes are changed. The parent window can return FALSE to prevent the changes, and in that case, the Header_SetItem macro returns FALSE. If the parent window returns TRUE, the changes are made and the parent window receives the HDN_ITEMCHANGED notification message.

The Header_SetItem macro is defined as follows:

#define Header_SetItem(hwndHD, index, phdi) \

    (BOOL)SendMessage((hwndHD), HDM_SETITEM,  \

    (WPARAM)(int)(index), (LPARAM)(const HD_ITEM FAR*)(phdi))

See Also

HD_ITEM, HDM_SETITEM, HDN_ITEMCHANGED, HDN_ITEMCHANGING


HIBYTE

The HIBYTE macro retrieves the high-order byte from the given 16-bit value.

BYTE HIBYTE(

WORD wValue	// value from which high-order byte is retrieved
);
Parameters

wValue

Specifies the value to be converted.

Return Values

The return value is the high-order byte of the specified value.

Remarks

The HIBYTE macro is defined as follows:

#define HIBYTE(w)   ((BYTE) (((WORD) (w) >> 8) & 0xFF))

See Also

HIWORD, LOBYTE


HIWORD

The HIWORD macro retrieves the high-order word from the given 32-bit value.

WORD HIWORD(

DWORD dwValue	// value from which high-order word is retrieved
);
Parameters

dwValue

Specifies the value to be converted.

Return Values

The return value is the high-order word of the specified value.

Remarks

The HIWORD macro is defined as follows:

#define HIWORD(l)   ((WORD) (((DWORD) (l) >> 16) & 0xFFFF))

See Also

HIBYTE, LOWORD


ImageList_AddIcon

The ImageList_AddIcon macro adds an icon or cursor to an image list. ImageList_AddIcon calls the ImageList_ReplaceIcon function.

int ImageList_AddIcon(

HIMAGELIST himl,	// handle to the image list
HICON hicon	// handle to the icon or cursor
);
Parameters

himl

Handle to the image list. If this parameter identifies a masked image list, the macro copies both the image and mask bitmaps of the icon or cursor. If this parameter identifies a nonmasked image list, the macro copies only the image bitmap.

hicon

Handle to the icon or cursor that contains the bitmap and mask for the new image.

Return Values

If the macro succeeds, the return value is the index of the new image.

If the macro fails, the return value is  − 1.

Remarks

Because the system does not save hicon, you can destroy it after the macro returns if the icon or cursor was created by the CreateIcon function. You do not need to destroy hicon if it was loaded by the LoadIcon function; the system automatically frees an icon resource when it is no longer needed.

The ImageList_AddIcon macro is defined as follows:

#define  ImageList_AddIcon(himl, hicon) ImageList_ReplaceIcon(himl, -1, hicon)

See Also

CreateIcon, ImageList_ReplaceIcon, LoadIcon


INDEXTOOVERLAYMASK [Now Supported on Windows NT]
INDEXTOOVERLAYMASK

[Now Supported on Windows NT]

The INDEXTOOVERLAYMASK macro prepares the index of an overlay mask so that the ImageList_Draw function can use it.

UINT INDEXTOOVERLAYMASK(

UINT iOverlay
);
Parameters

iOverlay

Index of an overlay mask.

Remarks

The INDEXTOOVERLAYMASK macro is defined as follows:

#define INDEXTOOVERLAYMASK(i) ((i) << 8)


INDEXTOSTATEIMAGEMASK [Now Supported on Windows NT]
INDEXTOSTATEIMAGEMASK

[Now Supported on Windows NT]

The INDEXTOSTATEIMAGEMASK macro prepares the index of a state image so that a tree-view control or list-view control can use the index to retrieve the state image for an item.

UINT INDEXTOSTATEIMAGEMASK(

UINT i
);
Parameters

i

Index of a state image.

Remarks

The INDEXTOSTATEIMAGEMASK macro is defined as follows:

#define INDEXTOSTATEIMAGEMASK(i) ((i) << 12)


LANGIDFROMLCID

The LANGIDFROMLCID macro retrieves a language identifier from a locale identifier.

WORD LANGIDFROMLCID(

LCID lcid	// locale identifier
);
Parameters

lcid

Specifies the locale identifier. This parameter may have been created by using the MAKELCID macro.

Return Values

The return value is a language identifier.

Remarks

The LANGIDFROMLCID macro is defined as follows:

#define LANGIDFROMLCID(lcid)   ((WORD) (lcid))

See Also

MAKELANGID, MAKELCID, PRIMARYLANGID, SUBLANGID


ListView_Arrange

The ListView_Arrange macro arranges items in icon view. You can use this macro or explicitly send the LVM_ARRANGE message.

BOOL ListView_Arrange(

HWND hwnd,
UINT code
);
Parameters

hwnd

Handle to the list view control.

code

Specifies the alignment, which can be one of the following values:

Value	Meaning
LVA_ALIGNLEFT	Aligns items along the left edge of the window.
LVA_ALIGNTOP	Aligns items along the top edge of the window.
LVA_DEFAULT	Aligns items according to the list view control’s current alignment styles (the default value).
LVA_SNAPTOGRID	Snaps all icons to the nearest grid position.
Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LVM_ARRANGE


ListView_CreateDragImage

The ListView_CreateDragImage macro creates a drag image list for the specified item. You can use this macro or explicitly send the LVM_CREATEDRAGIMAGE message.

HIMAGELIST ListView_CreateDragImage(

HWND hwnd,
int iItem,
LPPOINT lpptUpLeft
);
Parameters

hwnd

Handle to the list view control.

iItem

Index of the item.

lpptUpLeft

Pointer to a POINT structure that receives the initial location of the upper-left corner of the image, in view coordinates.

Return Values

Returns the handle to the drag image list if successful or NULL otherwise.

See Also

LVM_CREATEDRAGIMAGE, POINT


ListView_DeleteAllItems

The ListView_DeleteAllItems macro removes all items from a list view control. You can use this macro or explicitly send the LVM_DELETEALLITEMS message.

BOOL ListView_DeleteAllItems(

HWND hwnd
);
Parameters

hwnd

Handle to the list view control.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LVM_DELETEALLITEMS


ListView_DeleteColumn

The ListView_DeleteColumn macro removes a column from a list view control. You can use this macro or explicitly send the LVM_DELETECOLUMN message.

BOOL ListView_DeleteColumn(

HWND hwnd,
int iCol
);
Parameters

hwnd

Handle to the list view control.

iCol

Index of the column to delete.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LVM_DELETECOLUMN


ListView_DeleteItem

The ListView_DeleteItem macro removes an item from a list view control. You can use this macro or explicitly send the LVM_DELETEITEM message.

BOOL ListView_DeleteItem(

HWND hwnd,
int iItem
);
Parameters

hwnd

Handle to the list view control.

iItem

Index of the list view item to delete.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LVM_DELETEITEM


ListView_EditLabel

The ListView_EditLabel macro begins in-place editing of the specified list view item’s text. The message implicitly selects and focuses the specified item. You can use this macro or explicitly send the LVM_EDITLABEL message.

HWND ListView_EditLabel(

HWND hwnd,
int iItem
);
Parameters

hwnd

Handle to the list view control.

iItem

Index of the list view item. To cancel editing, set iItem to −1.

Return Values

Returns the handle of the edit control that is used to edit the item text if successful or NULL otherwise.

Remarks

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it.

The control must have the focus before you send this message to the control. Focus can be set using the SetFocus function.

See Also

LVM_EDITLABEL, WM_CANCELMODE, SetFocus


ListView_EnsureVisible

The ListView_EnsureVisible macro ensures that a list view item is entirely or at least partially visible, scrolling the list view control if necessary. You can use this macro or explicitly send the LVM_ENSUREVISIBLE message.

BOOL ListView_EnsureVisible(

HWND hwnd,
nt i,
BOOL fPartialOK
);
Parameters

hwnd

Handle to the list view control.

i

Index of the list view item.

fPartialOK

Value specifying whether the item must be entirely visible. If this parameter is TRUE, no scrolling occurs if the item is at least partially visible.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LVM_ENSUREVISIBLE


ListView_FindItem

The ListView_FindItem macro searches for a list view item with the specified characteristics. You can use this macro or explicitly send the LVM_FINDITEM message.

int ListView_FindItem(

HWND hwnd,
int iStart,
const LV_FINDINFO FAR* plvfi
);
Parameters

hwnd

Handle to the list view control.

iStart

Index of the item to begin the search with or −1 to start from the beginning. The specified item is itself excluded from the search.

plvfi

Pointer to an LV_FINDINFO structure that contains information about what to search for.

Return Values

Returns the index of the item if successful or −1 otherwise.

See Also

LV_FINDINFO, LVM_FINDITEM


ListView_GetBkColor

The ListView_GetBkColor macro retrieves the background color of a list view control. You can use this macro or explicitly send the LVM_GETBKCOLOR message.

COLORREF ListView_GetBkColor(

HWND hwnd
);
Parameters

hwnd

Handle to the list view control.

Return Values

Returns the background color of the list view control.

See Also

LVM_GETBKCOLOR


ListView_GetCallbackMask

The ListView_GetCallbackMask macro retrieves the callback mask for a list view control. You can use this macro or explicitly send the LVM_GETCALLBACKMASK message.

UINT ListView_GetCallbackMask(

HWND hwnd
);
Parameters

hwnd

Handle to the list view control.

Return Values

Returns the callback mask.

See Also

LVM_GETCALLBACKMASK, LVM_SETCALLBACKMASK


ListView_GetColumn

The ListView_GetColumn macro retrieves the attributes of a list view control’s column. You can use this macro or explicitly send the LVM_GETCOLUMN message.

BOOL ListView_GetColumn(

HWND hwnd,
int iCol,
LV_COLUMN FAR* pcol
);
Parameters

hwnd

Handle to the list view control.

iCol

Index of the column.

pcol

Pointer to an LV_COLUMN structure that specifies the information to retrieve and receives information about the column. The mask member specifies which column attributes to retrieve.

If the mask member specifies the LVCF_TEXT value, the pszText member must contain the pointer to the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LV_COLUMN, LVM_GETCOLUMN


ListView_GetColumnWidth

The ListView_GetColumnWidth macro retrieves the width of a column in report or list view. You can use this macro or explicitly send the LVM_GETCOLUMNWIDTH message.

int ListView_GetColumnWidth(

HWND hwnd,
int iCol
);
Parameters

hwnd

Handle to the list view control.

iCol

Index of the column. This parameter is ignored in list view.

Return Values

Returns the column width if successful or zero otherwise.

See Also

LVM_GETCOLUMNWIDTH


ListView_GetCountPerPage

The ListView_GetCountPerPage macro calculates the number of items that can fit vertically in the visible area of a list view control when in list or report view. Only fully visible items are counted. You can use this macro or explicitly send the LVM_GETCOUNTPERPAGE message.

int ListView_GetCountPerPage(

HWND hwnd
);
Parameters

hwnd

Handle to the list view control.

Return Values

Returns the number of fully-visible items if successful. If the current view is icon or small icon view, the return value is the total number of items in the list view control.

See Also

LVM_GETCOUNTPERPAGE


ListView_GetEditControl

The ListView_GetEditControl macro retrieves the handle to the edit control being used to edit a list view item’s text. You can use this macro or explicitly send the LVM_GETEDITCONTROL message.

HWND ListView_GetEditControl(

HWND hwnd
);
Parameters

hwnd

Handle to the list view control.

Return Values

Returns the handle to the edit control if successful or NULL otherwise.

Remarks

If no label is being edited, the return value is NULL. The edit control is not created until after the LVN_BEGINLABELEDIT notification message is sent.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it. To cancel editing, you can send the list view control a WM_CANCELMODE message.

The list view item being edited is the currently focused item — that is, the item in the focused state. To find an item based on its state, use the LVM_GETNEXTITEM message.

See Also

LVN_BEGINLABELEDIT, LVM_GETEDITCONTROL, LVM_GETNEXTITEM, WM_CANCELMODE


ListView_GetImageList

The ListView_GetImageList macro retrieves the handle to an image list used for drawing list view items. You can use this macro or explicitly send the LVM_GETIMAGELIST message.

HIMAGELIST ListView_GetImageList(

HWND hwnd,
int iImageList
);
Parameters

hwnd

Handle to the list view control.

iImageList

Image list to retrieve. This parameter can be one of the following values:

Value	Meaning
LVSIL_NORMAL	Image list with large icons
LVSIL_SMALL	Image list with small icons
LVSIL_STATE	Image list with state images
Return Values

Returns the handle of the specified image list if successful or NULL otherwise.

See Also

LVM_GETIMAGELIST


ListView_GetISearchString

The ListView_GetISearchString macro retrieves the incremental search string of a list-view control. You can use this macro or explicitly send the LVM_GETISEARCHSTRING message.

BOOL ListView_GetISearchString(

HWND hwnd,
LPSTR lpsz
);
Parameters

hwnd

Handle to the list view control.

lpsz

Pointer to a buffer that receives the incremental search string.

Return Values

Returns the number of characters in the incremental search string, or zero if the list-view control is not in incremental search mode.

Remarks

The incremental search string is the character sequence that the user types while the list view has the input focus. Each time the user types a character, the system appends the character to the search string and then searches for a matching item. If the system finds a match, it selects the item and, if necessary, scrolls it into view.

A timeout period is associated with each character that the user types. If the timeout period elapses before the user types another character, the incremental search string is reset.

See Also

LVM_GETISEARCHSTRING


ListView_GetItem

The ListView_GetItem macro retrieves some or all of a list view item’s attributes. You can use this macro or explicitly send the LVM_GETITEM message.

BOOL ListView_GetItem(

HWND hwnd,
LV_ITEM FAR *pitem
);
Parameters

hwnd

Handle to the list view control.

pitem

Pointer to an LV_ITEM structure that specifies the information to retrieve and receives information about the list view item.

When the LVM_GETITEM message is sent, the iItem and iSubItem members identify the item or subitem to retrieve information about and the mask member specifies which attributes to retrieve. For a list of possible values, see the description of the LV_ITEM structure.

If the mask member specifies the LVIF_TEXT value, the pszText member must contain the pointer to the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

If the mask member specifies the LVIF_STATE value, the stateMask member specifies which item states are to be returned.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LV_ITEM, LVM_GETITEM


ListView_GetItemCount

The ListView_GetItemCount macro retrieves the number of items in a list view control. You can use this macro or explicitly send the LVM_GETITEMCOUNT message.

int ListView_GetItemCount(

HWND hwnd
);
Parameters

hwnd

Handle to the list view control.

Return Values

Returns the number of items.

See Also

LVM_GETITEMCOUNT


ListView_GetItemPosition

The ListView_GetItemPosition macro retrieves the position of a list view item. You can use this macro or explicitly send the LVM_GETITEMPOSITION message.

BOOL ListView_GetItemPosition(

HWND hwnd,
int i,
POINT FAR *ppt
);
Parameters

hwnd

Handle to the list view control.

i

Index of the list view item.

ppt

Pointer to a POINT structure that receives the position of the item’s upper-left corner, in view coordinates.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LVM_GETITEMPOSITION, POINT


ListView_GetItemRect

The ListView_GetItemRect macro retrieves the bounding rectangle for all or part of an item in the current view. You can use this macro or explicitly send the LVM_GETITEMRECT message.

BOOL ListView_GetItemRect(

HWND hwnd,
int i,
RECT FAR *prc,
int code
);
Parameters

hwnd

Handle to the list view control.

i

Index of the list view item.

prc

Pointer to a RECT structure that receives the bounding rectangle. When the LVM_GETITEMRECT message is sent, the left member of this structure contains the value of the code parameter.

code

Portion of the list view item for which to retrieve the bounding rectangle. This parameter can be one of the following values:

Value	Meaning
LVIR_BOUNDS	Returns the bounding rectangle of the entire item, including the icon and label.
LVIR_ICON	Returns the bounding rectangle of the icon or small icon.
LVIR_LABEL	Returns the bounding rectangle of the item text.
LVIR_SELECTBOUNDS	Returns the union of the LVIR_ICON and LVIR_LABEL rectangles, but excludes columns in details view.
Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

This parameter is specified by the left member of the RECT structure pointed to by prc.

See Also

LVM_GETITEMRECT, RECT


ListView_GetItemSpacing

The ListView_GetItemSpacing macro determines the spacing between items in a list view control. You can use this macro or explicitly send the LVM_GETITEMSPACING message.

DWORD ListView_GetItemSpacing(

HWND hwnd,
BOOL fSmall
);
Parameters

hwnd

Handle to the list view control.

fSmall

View to retrieve the item spacing for. This parameter is TRUE for small icon view, or FALSE for icon view.

Return Values

Returns the amount of spacing between items.

See Also

LVM_GETITEMSPACING


ListView_GetItemState

The ListView_GetItemState macro retrieves the state of a list view item. You can use this macro or explicitly send the LVM_GETITEMSTATE message.

UINT WINAPI ListView_GetItemState(

HWND hwnd,
int i,
UINT mask
);
Parameters

hwnd

Handle to the list view control.

i

Index of the list view item.

mask

Mask that specifies which of the item’s state flags to return.

Return Values

Returns the item’s state flags.

See Also

LVM_GETITEMSTATE


ListView_GetItemText

The ListView_GetItem macro retrieves the text of a list view item or subitem. You can use this macro or explicitly send the LVM_GETITEMTEXT message.

void WINAPI ListView_GetItemText(

HWND hwnd,
int iItem,
int iSubItem,
LPSTR pszText,
int cchTextMax
);
Parameters

hwnd

Handle to the list view control.

iItem

Index of the list view item.

iSubItem

Index of the subitem, or zero to retrieve the item label.

pszText

Pointer to the buffer that receives the item or subitem text.

cchTextMax

Size of the buffer, in bytes.

Return Values

The ListView_GetItemText macro does not return a value.

If you send the LVM_GETITEMTEXT message explicitly, it returns the length of the retrieved string.

See Also

LV_ITEM, LVM_GETITEMTEXT


ListView_GetNextItem

The ListView_GetNextItem macro searches for a list view item that has the specified properties and bears the specified relationship to a specified item. You can use this macro or explicitly send the LVM_GETNEXTITEM message.

int ListView_GetNextItem(

HWND hwnd,
int iStart,
UINT flags
);
Parameters

hwnd

Handle to the list view control.

iStart

Index of the item to begin the searching with, or −1 to find the first item that matches the specified flags. The specified item itself is excluded from the search.

flags

Geometric relation of the requested item to the specified item and, if specified, the state of the requested item.

The geometric relation can be one of the following values:

Value	Meaning
LVNI_ABOVE	Searches for an item that is above the specified item.
LVNI_ALL	Searches for a subsequent item by index (the default value).
LVNI_BELOW	Searches for an item that is below the specified item.
LVNI_TOLEFT	Searches for an item to the left of the specified item.
LVNI_TORIGHT	Searches for an item to the right of the specified item.
The state can be zero, or it can be one or more of the following values:

Value	Meaning
LVNI_CUT	The item has the LVIS_CUT state flag set.
LVNI_DROPHILITED	The item has the LVIS_DROPHILITED state flag set.
LVNI_FOCUSED	The item has the LVIS_FOCUSED state flag set.
LVNI_SELECTED	The item has the LVIS_SELECTED state flag set.
If an item does not have all of the specified state flags set, the search continues with the next item.

Return Values

Returns the index of the next item if successful or −1 otherwise.

See Also

LVM_GETNEXTITEM


ListView_GetOrigin

The ListView_GetOrigin macro retrieves the current view origin for a list view control. You can use this macro or explicitly send the LVM_GETORIGIN message.

BOOL ListView_GetOrigin(

HWND hwnd,
LPPOINT lpptOrg
);
Parameters

hwnd

Handle to the list view control.

lpptOrg

Pointer to a POINT structure that receives the view origin.

Return Values

Returns TRUE if successful or FALSE if the current view is list or report view.

See Also

LVM_GETORIGIN, POINT


ListView_GetSelectedCount

The ListView_GetSelectedCount macro determines the number of selected items in a list view control. You can use this macro or explicitly send the LVM_GETSELECTEDCOUNT message.

UINT ListView_GetSelectedCount(

HWND hwnd
);
Parameters

hwnd

Handle to the list view control.

Return Values

Returns the number of selected items.

See Also

LVM_GETSELECTEDCOUNT


ListView_GetStringWidth

The ListView_GetStringWidth macro determines the width of a specified string, using the specified list view control’s current font. You can use this macro or explicitly send the LVM_GETSTRINGWIDTH message.

int ListView_GetStringWidth(

HWND hwnd,
LPCSTR psz
);
Parameters

hwnd

Handle to the list view control.

psz

Pointer to a null-terminated string.

Return Values

Returns the string width if successful or zero otherwise.

Remarks

The ListView_GetStringWidth macro returns the exact width, in pixels, of the specified string. If you use the returned string width as the column width in a call to the ListView_SetColumnWidth macro, the string will be truncated. To get the column width that can contain the string without truncating it, you must add padding to the returned string width.

See Also

ListView_SetColumnWidth, LVM_GETSTRINGWIDTH


ListView_GetTextBkColor

The ListView_GetTextBkColor macro retrieves the text background color of a list view control. You can use this macro or explicitly send the LVM_GETTEXTBKCOLOR message.

COLORREF ListView_GetTextBkColor(

HWND hwnd
);
Parameters

hwnd

Handle to the list view control.

Return Values

Returns the background color of the text.

See Also

LVM_GETTEXTBKCOLOR


ListView_GetTextColor

The ListView_GetTextColor macro retrieves the text color of a list view control. You can use this macro or explicitly send the LVM_GETTEXTCOLOR message.

COLORREF ListView_GetTextColor(

HWND hwnd
);
Parameters

hwnd

Handle to the list view control.

Return Values

Returns the text color.

See Also

LVM_GETTEXTCOLOR


ListView_GetTopIndex

The ListView_GetTopIndex macro retrieves the index of the topmost visible item when in list or report view. You can use this macro or explicitly send the LVM_GETTOPINDEX message.

int ListView_GetTopIndex(

HWND hwnd
);
Parameters

hwnd

Handle to the list view control.

Return Values

Returns the index of the item if successful or zero if the list view control is in icon or small icon view.

See Also

LVM_GETTOPINDEX


ListView_GetViewRect

The ListView_GetViewRect macro retrieves the bounding rectangle of all items in the list view control. The list view must be in icon or small icon view. You can use this macro or explicitly send the LVM_GETVIEWRECT message.

BOOL ListView_GetViewRect(

HWND hwnd,
RECT FAR *prc
);
Parameters

hwnd

Handle to the list view control.

prc

Pointer to a RECT structure that receives the bounding rectangle. All coordinates are relative to the visible area of the list view control.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LVM_GETVIEWRECT, RECT


ListView_HitTest

The ListView_HitTest macro determines which list view item, if any, is at a specified position. You can use this macro or explicitly send the LVM_HITTEST message.

int ListView_HitTest(

HWND hwnd,
LV_HITTESTINFO FAR *pinfo
);
Parameters

hwnd

Handle to the list view control.

pinfo

Pointer to an LV_HITTESTINFO structure that contains the position to hit test and receives information about the results of the hit test.

Return Values

Returns the index of the item at the specified position, if any, or −1 otherwise.

See Also

LV_HITTESTINFO, LVM_HITTEST


ListView_InsertColumn

The ListView_InsertColumn macro inserts a new column in a list view control. You can use this macro or explicitly send the LVM_INSERTCOLUMN message.

int ListView_InsertColumn(

HWND hwnd,
int iCol,
const LV_COLUMN FAR *pcol
);
Parameters

hwnd

Handle to the list view control.

iCol

Index of the new column.

pcol

Pointer to an LV_COLUMN structure that contains the attributes of the new column.

Return Values

Returns the index of the new column if successful or −1 otherwise.

See Also

LVM_INSERTCOLUMN, LV_COLUMN


ListView_InsertItem

The ListView_InsertItem macro inserts a new item in a list view control. You can use this macro or explicitly send the LVM_INSERTITEM message.

int ListView_InsertItem(

HWND hwnd,
const LV_ITEM FAR *pitem
);
Parameters

hwnd

Handle to the list view control.

pitem

Pointer to an LV_ITEM structure that specifies the attributes of the list view item. The iItem member specifies the index of the new item.

You cannot use ListView_InsertItem or LVM_INSERTITEM to insert subitems; the iSubItem member of the LV_ITEM structure must be zero.

Return Values

Returns the index of the new item if successful or −1 otherwise.

Remarks

If a list view control has either the LVS_SORTASCENDING or LVS_SORTDESCENDING window style, an LVM_INSERTITEM message will fail if you try to insert an item that has LPSTR_TEXTCALLBACK as the pszText member of its LV_ITEM structure.

See Also

LV_ITEM, LVM_INSERTITEM


ListView_RedrawItems

The ListView_RedrawItems macro forces a list view control to redraw a range of items. You can use this macro or explicitly send the LVM_REDRAWITEMS message.

BOOL ListView_RedrawItems(

HWND hwnd,
int iFirst,
int iLast
);
Parameters

hwnd

Handle to the list view control.

iFirst

Index of the first item to redraw.

iLast

Index of the last item to redraw.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The specified items are not actually redrawn until the list view window receives a WM_PAINT message to repaint. To repaint immediately, call the UpdateWindow function after using this macro.

See Also

LVM_REDRAWITEMS, UpdateWindow, WM_PAINT


ListView_Scroll

The ListView_Scroll macro scrolls the content of a list view control. You can use this macro or explicitly send the LVM_SCROLL message.

BOOL ListView_Scroll(

HWND hwnd,
nt dx,
int dy
);
Parameters

hwnd

Handle to the list view control.

dx

Integer value that specifies the amount of horizontal scrolling.

If the view type of the list view control is icon view, small icon view, or report view, this value specifies the number of pixels to scroll. If the view type of the list view control is list view, this value specifies the number of columns to scroll.

dy

Integer value that specifies the amount of vertical scrolling.

If the view type of the list view control is icon view, small icon view, or list view, this value specifies the number of pixels to scroll. If the view type of the list view control is report view, this value specifies the number of lines to scroll.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LVM_SCROLL


ListView_SetBkColor

The ListView_SetBkColor macro sets the background color of a list view control. You can use this macro or explicitly send the LVM_SETBKCOLOR message.

BOOL ListView_SetBkColor(

HWND hwnd,
COLORREF clrBk
);
Parameters

hwnd

Handle to the list view control.

clrBk

Background color to set or the CLR_NONE value for no background color. List view controls with background colors redraw themselves significantly faster than those without background colors.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LVM_SETBKCOLOR


ListView_SetCallbackMask

The ListView_SetCallbackMask macro changes the callback mask for a list view control. You can use this macro or explicitly send the LVM_SETCALLBACKMASK message.

BOOL ListView_SetCallbackMask(

WND hwnd,
UINT mask
);
Parameters

hwnd

Handle to the list view control.

mask

Specifies the value of the callback mask. The bits of the mask indicate the item states or images for which the application stores the current state data. This value can be any combination of the following constants:

Value	Meaning
LVIS_CUT	The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED	The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED	The item has the focus.
LVIS_SELECTED	The item is selected.
LVIS_OVERLAYMASK	The application stores the image list index of the current overlay image for each item.
LVIS_STATEIMAGEMASK	The application stores the image list index of the current state image for each item.
For more information about overlay images and state images, see List View Image Lists.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The callback mask of a list view control is a set of bit flags that specify the item states for which the application, rather than the control, stores the current data. The callback mask applies to all of the control’s items, unlike the callback item designation, which applies to a specific item. The callback mask is zero by default, meaning that the list view control stores all item state information. After creating a list view control and initializing its items, you can use the ListView_SetCallbackMask macro or LVM_SETCALLBACKMASK message to change the callback mask. To get the current callback mask, send the LVM_GETCALLBACKMASK message.

For more information, see Callback Items and the Callback Mask.

See Also

LVM_GETCALLBACKMASK, LVM_SETCALLBACKMASK, LVN_GETDISPINFO


ListView_SetColumn

The ListView_SetColumn macro sets the attributes of a list view column. You can use this macro or explicitly send the LVM_SETCOLUMN message.

BOOL ListView_SetColumn(

HWND hwnd,
int iCol,
LV_COLUMN FAR *pcol
);
Parameters

hwnd

Handle to the list view control.

iCol

Index of the column.

pcol

Pointer to an LV_COLUMN structure that contains the new column attributes. The mask member specifies which column attributes to set.

If the mask member specifies the LVCF_TEXT value, the pszText member is the pointer to a null-terminated string and the cchTextMax member is ignored.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LV_COLUMN, LVM_SETCOLUMN


ListView_SetColumnWidth

The ListView_SetColumnWidth macro changes the width of a column in report or list view. You can use this macro or explicitly send the LVM_SETCOLUMNWIDTH message.

BOOL ListView_SetColumnWidth(

HWND hwnd,
int iCol,
int cx
);
Parameters

hwnd

Handle to the list view control.

iCol

Index of the column. In list view, the iCol parameter must be −1.

cx

New width of the column, in list view coordinates, or one of the following values:

Value	Meaning
LVSCW_AUTOSIZE	Automatically sizes the column.
LVSCW_AUTOSIZE_USEHEADER	Automatically sizes the column to fit the header text.
See Also

LVM_SETCOLUMNWIDTH


ListView_SetImageList

The ListView_SetImageList macro assigns an image list to a list view control. You can use this macro or explicitly send the LVM_SETIMAGELIST message.

HIMAGELIST ListView_SetImageList(

HWND hwnd,
HIMAGELIST himl,
int iImageList
);
Parameters

hwnd

Handle to the list view control.

himl

Handle to the image list to assign.

iImageList

Type of image list. This parameter can be one of the following values:

Value	Meaning
LVSIL_NORMAL	Image list with large icons
LVSIL_SMALL	Image list with small icons
LVSIL_STATE	Image list with state images
Return Values

Returns the handle of the image list previously associated with the control if successful; NULL otherwise.

See Also

LVM_SETIMAGELIST


ListView_SetItem

The ListView_SetItem macro sets some or all of a list view item’s attributes. You can use this macro or explicitly send the LVM_SETITEM message.

BOOL ListView_SetItem(

HWND hwnd,
const LV_ITEM FAR *pitem
);
Parameters

hwnd

Handle to the list view control.

pitem

Pointer to an LV_ITEM structure that contains the new item attributes. The iItem and iSubItem members identify the item or subitem, and the mask member specifies which attributes to set.

If the mask member specifies the LVIF_TEXT value, the pszText member is the pointer to a null-terminated string and the cchTextMax member is ignored.

If the mask member specifies the LVIF_STATE value, the stateMask member specifies which item states to change and the state member contains the values for those states.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LV_ITEM, LVM_SETITEM


ListView_SetItemCount

The ListView_SetItemCount macro prepares a list view control for adding a large number of items. You can use this macro or explicitly send the LVM_SETITEMCOUNT message.

VOID ListView_SetItemCount(

HWND hwnd,
int cItems
);
Parameters

hwnd

Handle to the list view control.

cItems

Number of items that the list view control will ultimately contain.

Return Values

No return value.

Remarks

By using the ListView_SetItemCount macro or the LVM_SETITEMCOUNT message  before adding a large number of items, you enable a list view control to reallocate its internal data structures only once rather than every time you add an item.

See Also

LVM_SETITEMCOUNT


ListView_SetItemPosition

The ListView_SetItemPosition macro moves an item to a specified position in a list view control, which must be in icon or small icon view. You can use this macro or explicitly send the LVM_SETITEMPOSITION message.

BOOL ListView_SetItemPosition(

HWND hwnd,
int i,
int x,
int y
);
Parameters

hwnd

Handle to the list view control.

i

Index of the list view item.

x and y

New position of the item’s upper-left corner, in view coordinates.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

If the list view control has the LVS_AUTOARRANGE style, the list view control is arranged after the position of the item is set.

See Also

LVM_SETITEMPOSITION


ListView_SetItemPosition32

The ListView_SetItemPosition32 macro moves an item to a specified position in a list view control, which must be in icon or small icon view. This macro differs from the ListView_SetItemPosition macro in that it uses 32-bit coordinates. You can use the ListView_SetItemPosition32 macro or explicitly send the LVM_SETITEMPOSITION32 message.

void ListView_SetItemPosition32(

HWND hwnd,
int iItem,
nt x,
int y
);
Parameters

hwnd

Handle to the list view control.

iItem

Index of the list view item to set the position of.

x and y

New horizontal and vertical coordinates of the item.

Return Values

No return value.

See Also

ListView_SetItemPosition, LVM_SETITEMPOSITION32, POINT


ListView_SetItemState

The ListView_SetItemState macro changes the state of an item in a list view control. You can use this macro or explicitly send the LVM_SETITEMSTATE message.

BOOL WINAPI ListView_SetItemState(

HWND hwnd,
int i,
UINT state,
UINT mask
);
Parameters

hwnd

Handle to the list view control.

i

Index of the list view item.

state

New state bits for the item.

mask

Mask specifying which of the item’s current state bits to change.

Return Values

No return value.

See Also

LVM_SETITEMSTATE


ListView_SetItemText

The ListView_SetItemText macro changes the text of a list view item or subitem. You can use this macro or explicitly send the LVM_SETITEMTEXT message.

VOID WINAPI ListView_SetItemText(

HWND hwnd,
int i,
int iSubItem,
LPCSTR pszText
);
Parameters

hwnd

Handle to the list view control.

i

Index of the list view item.

iSubItem

Index of the subitem or zero to set the item label.

pszText

Pointer to a null-terminated string that contains the new text. This parameter can be NULL.

Return Values

No return value.

See Also

LVM_SETITEMTEXT


ListView_SetTextBkColor

The ListView_SetTextBkColor macro sets the background color of text in a list view control. You can use this macro or explicitly send the LVM_SETTEXTBKCOLOR message.

BOOL ListView_SetTextBkColor(

HWND hwnd,
COLORREF clrText
);
Parameters

hwnd

Handle to the list view control.

clrText

New text color.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LVM_SETTEXTBKCOLOR


ListView_SetTextColor

The ListView_SetTextColor macro sets the text color of a list view control. You can use this macro or explicitly send the LVM_SETTEXTCOLOR message.

BOOL ListView_SetTextColor(

HWND hwnd,
COLORREF clrText
);
Parameters

hwnd

Handle to the list view control.

clrText

New text color.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LVM_SETTEXTCOLOR


ListView_SortItems

The ListView_SortItems macro uses an application-defined comparison function to sort the items of a list view control. The index of each item changes to reflect the new sequence. You can use this macro or explicitly send the LVM_SORTITEMS message.

BOOL ListView_SortItems(

HWND hwnd,
PFNLVCOMPARE pfnCompare,
LPARAM lParamSort
);
Parameters

hwnd

Handle to the list view control.

pfnCompare

Pointer to the application-defined comparison function. The comparison function is called during the sort operation each time the relative order of two list items needs to be compared.

lParamSort

Application-defined value that is passed to the comparison function.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The comparison function has the following form:

int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2,

LPARAM lParamSort);

The lParam1 parameter is the 32-bit value associated with the first item being compared; and the lParam2 parameter is the value associated with the second item. These are the values that were specified in the lParam member of the items’ LV_ITEM structure when they were inserted into the list. The lParamSort parameter is the same value passed to the LVM_SORTITEMS message.

The comparison function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

See Also

LV_ITEM, LVM_SORTITEMS


ListView_Update

The ListView_Update macro updates a list view item. If the list view control has the LVS_AUTOARRANGE style, this macro causes the list view control to be arranged. You can use this macro or explicitly send the LVM_UPDATE message.

BOOL ListView_Update(

HWND hwnd,
int iItem
);
Parameters

hwnd

Handle to the list view control.

iItem

Index of the item to update.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

LVM_UPDATE


LOBYTE

The LOBYTE macro retrieves the low-order byte from the given 16-bit value.

BYTE LOBYTE(

WORD wValue	// value from which low-order byte is retrieved
);
Parameters

wValue

Specifies the value to be converted.

Return Values

The return value is the low-order byte of the specified value.

Remarks

The LOBYTE macro is defined as follows:

#define LOBYTE(w)   ((BYTE) (w))

See Also

HIBYTE, LOWORD


LOWORD

The LOWORD macro retrieves the low-order word from the given 32-bit value.

WORD LOWORD(

DWORD dwValue	// value from which low-order word is retrieved
);
Parameters

dwValue

Specifies the value to be converted.

Return Values

The return value is the low-order word of the specified value.

Remarks

The LOWORD macro is defined as follows:

#define LOWORD(l)   ((WORD) (l))

See Also

HIWORD, LOBYTE


MAKEINTATOM

The MAKEINTATOM macro creates an integer atom that represents a character string of decimal digits.

Integer atoms created by this macro can be added to an atom table by using the AddAtom or GlobalAddAtom function.

LPTSTR MAKEINTATOM(

WORD wInteger	// integer to make into atom
);
Parameters

wInteger

Specifies the numeric value to be made into an integer atom.

Return Values

The return value is a pointer to the atom created for the given integer.

Remarks

Although the return value of the MAKEINTATOM macro is cast as an LPTSTR value, it cannot be used as a string pointer except when it is passed to atom-management functions that require an LPTSTR argument.

The DeleteAtom and GlobalDeleteAtom functions always succeed for integer atoms, even though they do nothing. The string returned by the GetAtomName and GlobalGetAtomName functions for an integer atom is a null-terminated string in which the first character is a pound sign (#) and the remaining characters are the decimal digits used in the MAKEINTATOM macro.

The MAKEINTATOM macro is defined as follows:

#define MAKEINTATOM(i)   (LPTSTR) ((DWORD) ((WORD) (i)))

See Also

AddAtom, DeleteAtom, GetAtomName, GlobalAddAtom, GlobalDeleteAtom, GlobalGetAtomName


MAKEINTRESOURCE

The MAKEINTRESOURCE macro converts an integer value to a resource type compatible with Win32 resource-management functions. This macro is used in place of a string containing the name of the resource.

LPTSTR MAKEINTRESOURCE(

WORD wInteger	// integer to convert
);
Parameters

wInteger

Specifies the integer value to be converted.

Return Values

The return value is the specified value in the low-order word and zero in the high-order word.

Remarks

The return value should be passed only to the Win32 resource-management functions, as the lpType parameter.

The MAKEINTRESOURCE macro is defined as follows:

#define MAKEINTRESOURCE(i)  (LPTSTR) ((DWORD) ((WORD) (i)))


MAKELANGID

The MAKELANGID macro creates a language identifier from a primary language identifier and a sublanguage identifier.

WORD MAKELANGID(

USHORT usPrimaryLanguage,	// primary language identifier
USHORT usSubLanguage	// sublanguage identifier
);
Parameters

usPrimaryLanguage

Specifies the primary language identifier. This parameter can be one of the following values:

LANG_AFRIKAANS	LANG_ICELANDIC
LANG_ALBANIAN	LANG_INDONESIAN
LANG_ARABIC	LANG_ITALIAN
LANG_BASQUE	LANG_JAPANESE
LANG_BELARUSIAN	LANG_KOREAN
LANG_BULGARIAN	LANG_LATVIAN
LANG_CATALAN	LANG_LITHUANIAN
LANG_CHINESE	LANG_NEUTRAL
LANG_CROATIAN	LANG_NORWEGIAN
LANG_CZECH	LANG_POLISH
LANG_DANISH	LANG_PORTUGUESE
LANG_DUTCH	LANG_ROMANIAN
LANG_ENGLISH	LANG_RUSSIAN
LANG_ESTONIAN	LANG_SERBIAN
LANG_FAEROESE	LANG_SLOVAK
LANG_FARSI	LANG_SLOVENIAN
LANG_FINNISH	LANG_SPANISH
LANG_FRENCH	LANG_SWEDISH
LANG_GERMAN	LANG_THAI
LANG_GREEK	LANG_TURKISH
LANG_HEBREW	LANG_UKRANIAN
LANG_HUNGARIAN	LANG_VIETNAMESE
For a user-defined language, usPrimaryLanguage can be a value in the range 0x0200 to 0x03FF. All other values are reserved for system use.

usSubLanguage

Specifies the sublanguage identifier. This parameter can be one of the following values:

SUBLANG_ARABIC_SAUDI_ARABIA	SUBLANG_GERMAN
SUBLANG_ARABIC_IRAQ	SUBLANG_GERMAN_SWISS
SUBLANG_ARABIC_EGYPT	SUBLANG_GERMAN_AUSTRIAN
SUBLANG_ARABIC_LIBYA	SUBLANG_GERMAN_LUXEMBOURG
SUBLANG_ARABIC_ALGERIA	SUBLANG_GERMAN_LIECHTENSTEIN
SUBLANG_ARABIC_MOROCCO	SUBLANG_ITALIAN
SUBLANG_ARABIC_TUNISIA	SUBLANG_ITALIAN_SWISS
SUBLANG_ARABIC_OMAN	SUBLANG_KOREAN
SUBLANG_ARABIC_YEMEN	SUBLANG_KOREAN_JOHAB
SUBLANG_ARABIC_SYRIA	SUBLANG_NEUTRAL
SUBLANG_ARABIC_JORDAN	SUBLANG_NORWEGIAN_BOKMAL
SUBLANG_ARABIC_LEBANON	SUBLANG_NORWEGIAN_NYNORSK
SUBLANG_ARABIC_KUWAIT	SUBLANG_PORTUGUESE
SUBLANG_ARABIC_UAE	SUBLANG_PORTUGUESE_BRAZILIAN
SUBLANG_ARABIC_BAHRAIN	SUBLANG_SERBIAN_LATIN
SUBLANG_ARABIC_QATAR	SUBLANG_SERBIAN_CYRILLIC
SUBLANG_CHINESE_TRADITIONAL	SUBLANG_SPANISH
SUBLANG_CHINESE_SIMPLIFIED	SUBLANG_SPANISH_MEXICAN
SUBLANG_CHINESE_HONGKONG	SUBLANG_SPANISH_MODERN
SUBLANG_CHINESE_SINGAPORE	SUBLANG_SPANISH_GUATEMALA
SUBLANG_DEFAULT	SUBLANG_SPANISH_COSTA_RICA
SUBLANG_DUTCH	SUBLANG_SPANISH_PANAMA
SUBLANG_DUTCH_BELGIAN	SUBLANG_SPANISH_DOMINICAN_ REPUBLIC
SUBLANG_ENGLISH_US	SUBLANG_SPANISH_VENEZUELA
SUBLANG_ENGLISH_UK	SUBLANG_SPANISH_COLOMBIA
SUBLANG_ENGLISH_AUS	SUBLANG_SPANISH_PERU
SUBLANG_ENGLISH_CAN	SUBLANG_SPANISH_ARGENTINA
SUBLANG_ENGLISH_NZ	SUBLANG_SPANISH_ECUADOR
SUBLANG_ENGLISH_EIRE	SUBLANG_SPANISH_CHILE
SUBLANG_ENGLISH_SOUTH_ AFRICA	SUBLANG_SPANISH_URUGUAY
SUBLANG_ENGLISH_JAMAICA	SUBLANG_SPANISH_PARAGUAY
SUBLANG_ENGLISH_CARIBBEAN	SUBLANG_SPANISH_BOLIVIA
SUBLANG_ENGLISH_BELIZE	SUBLANG_SPANISH_EL_SALVADOR
SUBLANG_ENGLISH_TRINIDAD	SUBLANG_SPANISH_HONDURAS
SUBLANG_FRENCH	SUBLANG_SPANISH_NICARAGUA
SUBLANG_FRENCH_BELGIAN	SUBLANG_SPANISH_PUERTO_RICO
SUBLANG_FRENCH_CANADIAN	SUBLANG_SWEDISH
SUBLANG_FRENCH_SWISS	SUBLANG_SWEDISH_FINLAND
SUBLANG_FRENCH_LUXEMBOURG	SUBLANG_SYS_DEFAULT
For a user-defined sublanguage, usSubLanguage can be a value in the range 0x20 to 0x3F. All other values are reserved for system use.

Return Values

The return value is a language identifier.

Remarks

The following three combinations of usPrimaryLanguage and usSubLanguage have special meaning:

Primary language ID	Sublanguage ID	Meaning
LANG_NEUTRAL	SUBLANG_NEUTRAL	Language neutral
LANG_NEUTRAL	SUBLANG_DEFAULT	User default language
LANG_NEUTRAL	SUBLANG_SYS_DEFAULT	System default language
The MAKELANGID macro is defined as follows:

#define MAKELANGID(p, s) ((((WORD) (s)) << 10) | (WORD) (p))

See Also

EnumSystemLocales, LANGIDFROMLCID, MAKELCID, PRIMARYLANGID, SUBLANGID


MAKELCID

The MAKELCID macro creates a locale identifier from a language identifier.

DWORD MAKELCID(

WORD wLanguageID,	// language identifier
WORD wSortID	// sorting identifier
);
Parameters

wLanguageID

Specifies the language identifier. This parameter is a combination of a primary language identifier and a sublanguage identifier and is usually created by using the MAKELANGID macro.

wSortID

Specifies the sort identifier. Use the value SORT_DEFAULT for this parameter.

Return Values

The return value is a locale identifier.

Remarks

The MAKELCID macro is defined as follows:

#define MAKELCID(lgid, srtid)  \

    ((DWORD)((((DWORD)((WORD  )(srtid))) << 16) |  \

            ((DWORD)((WORD  )(lgid)))))

See Also

LANGIDFROMLCID, MAKELANGID, SORTIDFROMLCID


MAKELONG

The MAKELONG macro creates an unsigned 32-bit value by concatenating two given 16-bit values.

DWORD MAKELONG(

WORD wLow,	// low-order word of long value
WORD wHigh	// high-order word of long value
);
Parameters

wLow

Specifies the low-order word of the new long value.

wHigh

Specifies the high-order word of the new long value.

Return Values

The return value is an unsigned 32-bit value.

Remarks

The MAKELONG macro is defined as follows:

#define MAKELONG(a, b) \

    ((LONG) (((WORD) (a)) | ((DWORD) ((WORD) (b))) << 16))


MAKELPARAM

The MAKELPARAM macro creates an unsigned 32-bit value for use as an lParam parameter in a message. The macro concatenates two given 16-bit values.

LPARAM MAKELPARAM(

WORD wLow,	// low-order word
WORD wHigh	// high-order word
);
Parameters

wLow

Specifies the low-order word of the new long value.

wHigh

Specifies the high-order word of the new long value.

Return Values

The return value is an unsigned 32-bit value.

Remarks

The MAKELPARAM macro is defined as follows:

#define MAKELPARAM(l, h)   ((LPARAM) MAKELONG(l, h))

See Also

MAKELONG, MAKELRESULT, MAKEWPARAM


MAKELRESULT

The MAKELRESULT macro creates an unsigned 32-bit value for use as a return value from a window procedure. The macro concatenates two given 16-bit values.

LRESULT MAKELRESULT(

WORD wLow,	// low-order word
WORD wHigh	// high-order word
);
Parameters

wLow

Specifies the low-order word of the new long value.

wHigh

Specifies the high-order word of the new long value.

Return Values

The return value is an unsigned 32-bit value.

Remarks

The MAKELRESULT macro is defined as follows:

#define MAKELRESULT(l, h)   ((LRESULT) MAKELONG(l, h))

See Also

MAKELONG, MAKELPARAM, MAKEWPARAM


MAKEPOINTS

The MAKEPOINTS macro converts a value that contains the x- and y-coordinates of a point into a POINTS structure.

POINTS MAKEPOINTS(

DWORD dwValue	// coordinates of a point
);
Parameters

dwValue

Specifies the coordinates of a point. The x-coordinate is in the low-order word, and the y-coordinate is in the high-order word.

Return Values

The return value is a pointer to a POINTS structure.

Remarks

The MAKEPOINTS macro is defined as follows:

#define MAKEPOINTS(l)   (*((POINTS FAR *) & (l)))

See Also

GetMessagePos


MAKEROP4

The MAKEROP4 macro creates a quaternary raster operation code for use with the MaskBlt function. The macro takes two ternary raster operation codes as input, one for the foreground and one for the background, and packs their Boolean operation indexes into the high-order word of a 32-bit value. The low-order word of this value will be ignored.

DWORD MAKEROP4(

DWORD fore,	// foreground ternary raster operation code
DWORD back	// background ternary raster operation code
);
Parameters

fore

Specifies a foreground ternary raster operation code.

back

Specifies a background ternary raster operation code

Return Values

The return value is a DWORD quaternary raster operation code for use with the MaskBlt function.

Remarks

The MAKEROP4 macro is defined as follows:

#define MAKEROP4(fore,back)

          (DWORD)((((back) << 8) & 0xFF000000) | (fore))

See Also

MaskBlt


MAKEWORD

The MAKEWORD macro creates an unsigned 16-bit integer by concatenating two given unsigned character values.

WORD MAKEWORD(

BYTE bLow,	// low-order byte of short value
BYTE bHigh	// high-order byte of short value
);
Parameters

bLow

Specifies the low-order byte of the new short value.

bHigh

Specifies the high-order byte of the new short value.

Return Values

The return value is an unsigned 16-bit integer value.

Remarks

The MAKEWORD macro is defined as follows:

#define MAKEWORD(a, b) \

    ((WORD) (((BYTE) (a)) | ((WORD) ((BYTE) (b))) << 8))


MAKEWPARAM

The MAKEWPARAM macro creates an unsigned 32-bit value for use as a wParam parameter in a message. The macro concatenates two given 16-bit values.

LPARAM MAKEWPARAM(

WORD wLow,	// low-order word
WORD wHigh	// high-order word
);
Parameters

wLow

Specifies the low-order word of the new long value.

wHigh

Specifies the high-order word of the new long value.

Return Values

The return value is an unsigned 32-bit value.

Remarks

The MAKEWPARAM macro is defined as follows:

#define MAKEWPARAM(l, h)   ((LPARAM) MAKELONG(l, h))

See Also

MAKELONG, MAKELPARAM, MAKELRESULT


max

The max macro compares two values and returns the larger one. The data type can be any numeric data type, signed or unsigned. The data type of the arguments and the return value is the same.

max(

value1,	// low-order word
value2	// high-order word
);
Parameters

value1

Specifies the first of two values.

value2

Specifies the second of two values.

Return Values

The return value is the greater of the two specified values.

Remarks

The max macro is defined as follows:

#define max(a, b)  (((a) > (b)) ? (a) : (b))

See Also

min


min

The min macro compares two values and returns the smaller one. The data type can be any numeric data type, signed or unsigned. The data type of the arguments and the return value is the same.

min(

value1,
value2
);
Parameters

value1

Specifies the first of two values.

value2

Specifies the second of two values.

Return Values

The return value is the smaller of the two specified values.

Remarks

The min macro is defined as follows:

#define min(a, b)  (((a) < (b)) ? (a) : (b))

See Also

max


PALETTEINDEX

The PALETTEINDEX macro accepts an index to a logical-color palette entry and returns a palette-entry specifier consisting of a 32-bit COLORREF value that specifies the color associated with the given index. An application using a logical color palette can pass this specifier, instead of an explicit red, green, blue (RGB) value, to GDI functions that expect a color. This allows the function to use the color in the specified palette entry.

COLORREF PALETTEINDEX(

WORD wPaletteIndex	// index to palette entry
);
Parameters

wPaletteIndex

Specifies an index to the palette entry containing the color to be used for a graphics operation.

Return Values

The return value is a logical-palette index specifier.

Remarks

The PALETTEINDEX macro is defined as follows:

#define PALETTEINDEX(i) /

    ((COLORREF) (0x01000000 | (DWORD) (WORD) (i)))

See Also

PALETTERGB, RGB


PALETTERGB

The PALETTERGB macro accepts three values that represent the relative intensities of red, green, and blue and returns a palette-relative red, green, blue (RGB) specifier consisting of 2 in the high-order byte and an RGB value in the three low-order bytes. An application using a color palette can pass this specifier, instead of an explicit RGB value, to functions that expect a color.

COLORREF PALETTERGB(

BYTE bRed,	// red component of palette-relative RGB
BYTE bGreen,	// green component of palette-relative RGB
BYTE bBlue	// blue component of palette-relative RGB
);
Parameters

bRed

Specifies the intensity of the red color field.

bGreen

Specifies the intensity of the green color field.

bBlue

Specifies the intensity of the blue color field.

Return Values

The return value is a palette-relative RGB specifier. For output devices that support logical palettes, Windows matches a palette-relative RGB value to the nearest color in the logical palette of the device context as though the application had specified an index to that palette entry. If an output device does not support a system palette, Windows uses the palette-relative RGB as though it were a conventional RGB doubleword returned by the RGB macro.

Remarks

The PALETTERGB macro is defined as follows:

#define PALETTERGB(r, g, b)  (0x02000000 | RGB(r, g, b))

See Also

PALETTEINDEX, RGB


POINTSTOPOINT

The POINTSTOPOINT macro copies the contents of a POINTS structure into a POINT structure.

POINTSTOPOINT(

POINT pt,	// POINT structure
POINTS pts	// POINTS structure
);
Parameters

pt

Specifies the POINT structure to receive the contents of the POINTS structure.

pts

Specifies the POINTS structure to copy.

Remarks

The POINTSTOPOINT macro is defined as follows:

#define POINTSTOPOINT(pt, pts) {(pt).x = (SHORT) LOWORD(pts); \

                               (pt).y = (SHORT) HIWORD(pts);}

See Also

MAKEPOINTS, POINTTOPOINTS


POINTTOPOINTS

The POINTTOPOINTS macro converts a POINT structure to a POINTS structure.

POINTS POINTTOPOINTS(

POINT pt	// coordinates of a point
);
Parameters

pt

Specifies the POINT structure to convert.

Return Values

The return value is a POINTS structure.

Remarks

The POINTTOPOINTS macro is defined as follows:

#define POINTTOPOINTS(pt) \

    (MAKELONG((short) ((pt).x), (short) ((pt).y)))

See Also

MAKEPOINTS, POINTSTOPOINT


PRIMARYLANGID

The PRIMARYLANGID macro extracts a primary language identifier from a language identifier.

WORD PRIMARYLANGID(

WORD lgid	// language identifier
);
Parameters

lgid

Specifies the language identifier. This value is a combination of a primary language identifier and a sublanguage identifier and is usually created by using the MAKELANGID macro.

Return Values

The return value is a primary language identifier. The following primary language identifiers are defined:

LANG_AFRIKAANS	LANG_ICELANDIC
LANG_ALBANIAN	LANG_INDONESIAN
LANG_ARABIC	LANG_ITALIAN
LANG_BASQUE	LANG_JAPANESE
LANG_BELARUSIAN	LANG_KOREAN
LANG_BULGARIAN	LANG_LATVIAN
LANG_CATALAN	LANG_LITHUANIAN
LANG_CHINESE	LANG_NEUTRAL
LANG_CROATIAN	LANG_NORWEGIAN
LANG_CZECH	LANG_POLISH
LANG_DANISH	LANG_PORTUGUESE
LANG_DUTCH	LANG_ROMANIAN
LANG_ENGLISH	LANG_RUSSIAN
LANG_ESTONIAN	LANG_SERBIAN
LANG_FAEROESE	LANG_SLOVAK
LANG_FARSI	LANG_SLOVENIAN
LANG_FINNISH	LANG_SPANISH
LANG_FRENCH	LANG_SWEDISH
LANG_GERMAN	LANG_THAI
LANG_GREEK	LANG_TURKISH
LANG_HEBREW	LANG_UKRANIAN
LANG_HUNGARIAN	LANG_VIETNAMESE
Remarks

The PRIMARYLANGID macro is defined as follows:

#define PRIMARYLANGID(lgid)    ((WORD  )(lgid) & 0x3ff)

See Also

EnumSystemLocales, LANGIDFROMLCID, MAKELANGID, SUBLANGID


PropSheet_AddPage

The PropSheet_AddPage macro adds a new page to the end of an existing property sheet. You can use this macro or explicitly send the PSM_ADDPAGE message.

BOOL PropSheet_AddPage(

hPropSheetDlg,
hpage
);
Parameters

hPropSheetDlg

Handle to the property sheet.

hpage

Handle to the page to add. The page must have been created by a previous call to the CreatePropertySheetPage function.

Return Values

No return value.

Remarks

The property sheet is not resized to fit the new page. The new page should be no larger than the largest page currently in the property sheet.

See Also

CreatePropertySheetPage, PSM_ADDPAGE


PropSheet_Apply

The PropSheet_Apply macro simulates the choice of the Apply Now button, indicating that one or more pages have changed and the changes need to be validated and recorded. The property sheet sends the PSN_KILLACTIVE notification message to the current page. If the current page returns FALSE, the property sheet sends the PSN_APPLY notification message to all pages. You can use this macro or explicitly send the PSM_APPLY message.

BOOL PropSheet_Apply(

hPropSheetDlg
);
Parameters

hPropSheetDlg

Handle to the property sheet.

Return Values

Returns TRUE if all pages successfully applied the changes or FALSE otherwise.

See Also

PSM_APPLY, PSN_APPLY, PSN_KILLACTIVE


PropSheet_CancelToClose

The PropSheet_CancelToClose macro disables the Cancel button and changes the text of the OK button to “Close.” An application sends the PSM_CANCELTOCLOSE message after applying a change that cannot be canceled. You can use this macro or explicitly send the PSM_CANCELTOCLOSE message.

VOID PropSheet_CancelToClose(

hPropSheetDlg
);
Parameters

hPropSheetDlg

Handle to the property sheet.

Return Values

No return value.

See Also

PSM_CANCELTOCLOSE


PropSheet_Changed

The PropSheet_Changed macro informs a property sheet that information in a page has changed. The property sheet enables the Apply Now button. You can use this macro or explicitly send the PSM_CHANGED message.

BOOL PropSheet_Changed(

hPropSheetDlg,
hwndPage
);
Parameters

hPropSheetDlg

Handle to the property sheet.

hwndPage

Handle to the page that has changed.

Return Values

No return value.

See Also

PSM_CHANGED


PropSheet_GetCurrentPageHwnd

The PropSheet_GetCurrentPageHwnd macro retrieves a handle to the window of the current page of a property sheet. You can use this macro or explicitly send the PSM_GETCURRENTPAGEHWND message.

HWND PropSheet_GetCurrentPageHwnd(

hDlg
);
Parameters

hDlg

Handle to the property sheet.

Return Values

Returns a handle to the window of the current property sheet page.

Remarks

Use the PropSheet_GetCurrentPageHwnd macro with modeless property sheets to determine when to destroy the dialog box. When the user selects the OK or Cancel button, PropSheet_GetCurrentPageHwnd returns NULL, and you can then use the DestroyWindow function to destroy the dialog box.

See Also

DestroyWindow, PropertySheet, PSM_GETCURRENTPAGEHWND


PropSheet_GetTabControl

The PropSheet_GetTabControl macro retrieves the handle to the tab control of a property sheet. You can use this macro or explicitly send the PSM_GETTABCONTROL message.

HWND PropSheet_GetTabControl(

hPropSheetDlg
);
Parameters

hPropSheetDlg

Handle to the property sheet.

Return Values

Returns the handle to the tab control.

See Also

PSM_GETTABCONTROL


PropSheet_IsDialogMessage

The PropSheet_IsDialogMessage macro passes a message to a property sheet dialog box and indicates whether the dialog processed the message. You can use this macro or explicitly send the PSM_ISDIALOGMESSAGE message.

BOOL PropSheet_IsDialogMessage(

hDlg,
pMsg
);
Parameters

hDlg

Handle to the property sheet.

pMsg

Pointer to a MSG structure that contains the message to be checked.

Return Values

If the macro has been processed, the return value is TRUE.

If the macro has not been processed, the return value is FALSE.

Remarks

Your message loop should use the PSM_ISDIALOGMESSAGEmessage with modeless property sheets to pass messages to the property sheet dialog box.

If the return value indicates that the PSM_ISDIALOGMESSAGE message was processed, it must not be passed to the TranslateMessage or DispatchMessage function.

See Also

DispatchMessage, MSG, PropertySheet, PSM_ISDIALOGMESSAGE, TranslateMessage


PropSheet_PressButton

The PropSheet_PressButton macro simulates the choice of a property sheet button. You can use this macro or explicitly send the PSM_PRESSBUTTON message.

BOOL PropSheet_PressButton(

hPropSheetDlg,
iButton
);
Parameters

hPropSheetDlg

Handle to the property sheet.

iButton

Index of button to choose. This parameter can be one of the following values:

Value	Meaning
PSBTN_APPLYNOW	Chooses the Apply Now button.
PSBTN_BACK	Chooses the Back button.
PSBTN_CANCEL	Chooses the Cancel button.
PSBTN_FINISH	Chooses the Finish button.
PSBTN_HELP	Chooses the Help button.
PSBTN_NEXT	Chooses the Next button.
PSBTN_OK	Chooses the OK button.
Return Values

No return value.

See Also

PSM_PRESSBUTTON


PropSheet_QuerySiblings

The PropSheet_QuerySiblings macro forwards the PSM_QUERYSIBLINGS message to each page in the property sheet. If a page returns a nonzero value, the property sheet does not send the message to subsequent pages. You can use this macro or explicitly send the PSM_QUERYSIBLINGS message.

int PropSheet_QuerySiblings(

hPropSheetDlg,
param1,
param2
);
Parameters

hPropSheetDlg

Handle to the property sheet.

param1

First application-defined parameter.

param2

Second application-defined parameter.

Return Values

Returns the nonzero value from a page in the property sheet, or zero if no page returns a nonzero value.

See Also

PSM_QUERYSIBLINGS


PropSheet_RebootSystem

The PropSheet_RebootSystem macro indicates that the system needs to be restarted for the changes to take effect. You can use the PropSheet_RebootSystem macro or explicitly send the PSM_REBOOTSYSTEM message. An application should send the PSM_REBOOTSYSTEM message only in response to the PSN_APPLY or PSN_KILLACTIVE_win32_PSN_KILLACTIVE notification message.

VOID PropSheet_RebootSystem(

hPropSheetDlg
);
Parameters

hPropSheetDlg

Handle to the property sheet.

Return Values

No return value.

Remarks

This macro causes the PropertySheet function to return the ID_PSREBOOTSYSTEM value, but only if the user chooses the OK button to close the property sheet. It is the application’s responsibility to reboot the system, which can be done by using the ExitWindowsEx function.

This macro supersedes all PropSheet_RebootSystem macros that precede or follow it.

See Also

ExitWindowsEx, PropertySheet, PSM_REBOOTSYSTEM, PSM_RESTARTWINDOWS, PSN_APPLY, PSN_KILLACTIVE


PropSheet_RemovePage

The PropSheet_RemovePage macro removes a page from a property sheet. You can use this macro or explicitly send the PSM_REMOVEPAGE message.

VOID PropSheet_RemovePage(

hPropSheetDlg,
index,
hpage
);
Parameters

hPropSheetDlg

Handle to the property sheet.

hpage and index

Handle to the page to remove, and the zero-based index of the page to remove. An application can specify the handle or the index, or both. If both are specified, hpage takes precedence.

Return Values

No return value.

See Also

PSM_REMOVEPAGE


PropSheet_RestartWindows

The PropSheet_RestartWindows macro sends a PSM_RESTARTWINDOWS message indicating that Windows needs to be restarted for changes to take effect. You can use the PropSheet_RestartWindows macro or explicitly send the PSM_RESTARTWINDOWS message. An application should send the PSM_RESTARTWINDOWS message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message.

VOID PropSheet_RestartWindows(

hPropSheetDlg
);
Parameters

hPropSheetDlg

Handle to the property sheet.

Return Values

No return value.

Remarks

The PSM_RESTARTWINDOWS message causes the PropertySheet function to return the ID_PSRESTARTWINDOWS value, but only if the user chooses the OK button to close the property sheet. It is the application’s responsibility to restart Windows, which can be done by using the ExitWindowsEx function.

See Also

ExitWindowsEx, PropertySheet, PSM_RESTARTWINDOWS, PSN_APPLY, PSN_KILLACTIVE


PropSheet_SetCurSel

The PropSheet_SetCurSel macro activates the given page in a property sheet. You can use this macro or explicitly send the PSM_SETCURSEL message.

BOOL PropSheet_SetCurSel(

hPropSheetDlg,
hpage,
index
);
Parameters

hPropSheetDlg

Handle to the property sheet.

hpage and index

Handle to the page to activate, and the zero-based index of the page to activate. An application can specify the handle or the index, or both. If both are specified, hpage takes precedence.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The window that is losing the activation receives the PSN_KILLACTIVE notification message, and the window that is gaining the activation receives the PSN_SETACTIVE notification message.

See Also

PSM_SETCURSEL, PSN_KILLACTIVE, PSN_SETACTIVE


PropSheet_SetCurSelByID

The PropSheet_SetCurSelByID macro activates the given page in a property sheet based on the resource identifier of the page. You can use this macro or explicitly send the PSM_SETCURSELID message.

BOOL PropSheet_SetCurSelByID(

hPropSheetDlg,
id
);
Parameters

hPropSheetDlg

Handle to the property sheet.

id

Resource identifier of the page to activate.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The window that is losing the activation receives the PSN_KILLACTIVE notification message, and the window that is gaining the activation receives the PSN_SETACTIVE notification message.

See Also

PSM_SETCURSELID, PSN_KILLACTIVE, PSN_SETACTIVE


PropSheet_SetFinishText

The PropSheet_SetFinishText macro sets the text of the Finish button in a wizard property sheet, shows and enables the button, and hides the Next and Back buttons. You can use this macro or explicitly send the PSM_SETFINISHTEXT message.

VOID PropSheet_SetFinishText(

hPropSheetDlg,
lpszText
);
Parameters

hPropSheetDlg

Handle to the property sheet.

lpszText

Pointer to the new text for the Finish button.

Return Values

No return value.

Remarks

This macro causes the DM_SETDEFID message to be sent to the property sheet dialog box. The wParam parameter specifies the identifier of the Finish button.

See Also

DM_SETDEFID, PSM_SETFINISHTEXT


PropSheet_SetTitle

The PropSheet_SetTitle macro sets the title of a property sheet. You can use this macro or explicitly send the PSM_SETTITLE message.

VOID PropSheet_SetTitle(

hPropSheetDlg,
dwStyle,
lpszText
);
Parameters

hPropSheetDlg

Handle to the property sheet.

dwStyle

Flag that indicates whether to include the prefix “Properties for” with the specified title string. If dwStyle is the PSH_PROPTITLE value, the prefix is included. Otherwise, the prefix is not used.

lpszText

Pointer to a buffer that contains the title string. If the high-order word of this parameter is NULL, the property sheet loads the string resource specified in the low-order word.

Return Values

No return value.

See Also

PSM_SETTITLE


PropSheet_SetWizButtons

The PropSheet_SetWizButtons macro posts the PSM_SETWIZBUTTONS message to a wizard property sheet. The PSM_SETWIZBUTTONS message enables or disables the Back, Next, and Finish buttons in a wizard property sheet. You can use this macro or explicitly send or post the PSM_SETWIZBUTTONS message.

VOID PropSheet_SetWizButtons(

HWND  hPropSheetDlg,	// handle to the property sheet
DWORD dwFlags	// specifies the buttons to display and enable
);
Parameters

hPropSheetDlg

Handle to the property sheet.

dwFlags

Specifies the buttons to display and enable. A wizard property sheet displays the Back button and either the Next or Finish button. This parameter can include the PSWIZB_BACK flag and one of the PSWIZB_NEXT, PSWIZB_FINISH, or PSWIZB_DISABLEDFINISH flags.

Value	Meaning
PSWIZB_BACK	Enables the Back button.
PSWIZB_NEXT	Enables the Next button.
PSWIZB_FINISH	Displays an enabled Finish button in place of the Next button.
PSWIZB_DISABLEDFINISH	Displays a disabled Finish button in place of the Next button.
Return Values

No return value.

See Also

PSM_SETWIZBUTTONS


PropSheet_UnChanged

The PropSheet_UnChanged macro informs a property sheet that information in a page has reverted to the previously saved state. The property sheet disables the Apply Now button if no other pages have registered changes with the property sheet. You can use this macro or explicitly send the PSM_UNCHANGED message.

VOID PropSheet_UnChanged(hPropSheetDlg, hwndPage)

hPropSheetDlg,
hwndPage
);
Parameters

hPropSheetDlg

Handle to the property sheet.

hwndPage

Handle to the page that has reverted to the previously saved state.

Return Values

No return value.

See Also

PSM_UNCHANGED


RGB

The RGB macro selects a red, green, blue (RGB) color based on the arguments supplied and the color capabilities of the output device.

COLORREF RGB(

BYTE bRed,	// red component of color
BYTE bGreen,	// green component of color
BYTE bBlue	// blue component of color
);
Parameters

cRed

Specifies the intensity of the red color.

cGreen

Specifies the intensity of the green color.

cBlue

Specifies the intensity of the blue color.

Return Values

The return value is the resultant RGB color.

Remarks

The intensity for each argument is in the range 0 through 255. If all three intensities are zero, the result is black. If all three intensities are 255, the result is white.

For information about using color values in a color palette, see the descriptions of the PALETTEINDEX and PALETTERGB macros.

The RGB macro is defined as follows:

#define RGB(r, g ,b)  ((DWORD) (((BYTE) (r) | \

    ((WORD) (g) << 8)) | \

    (((DWORD) (BYTE) (b)) << 16)))

See Also

PALETTEINDEX, PALETTERGB


SOANGLETENTHS

Sets the angle in tenths of a degree.

SOANGLETENTHS(AngleInTenthsOfADegree)


SOPALETTEINDEX

Creates a palette-index color value. Index must specify a valid palette entry index. When this color value is used, the system uses the color from the given palette entry.

SOPALETTEINDEX(Index)


SOPALETTERGB

Creates a palette-relative RGB color value. Red, Green, and Blue specify the red, green, and blue color intensities and must be in the range 0 to 255. When this color value is specified, the system uses the palette entry that has the color that most closely matches this value.

SOPALETTERGB(Red, Green, Blue)


SORGB

Creates an RGB color value. Red, Green, and Blue specify the red, green, and blue color intensities and must be in the range 0 to 255.

SORGB(Red, Green, Blue)


SOSETRATIO

Sets the ratio. Numerator and Denominator specify the ratio factors and must be values in the range 0 to 65,535.

SOSETRATIO(Numerator, Denominator)


SORTIDFROMLCID

The SORTIDFROMLCID macro retrieves a sort identifier from a locale identifier.

WORD SORTIDFROMLCID(

LCID lcid	// locale identifier
);
Parameters

lcid

Specifies the locale identifier. This parameter may have been created by using the MAKELCID macro.

Return Values

The return value is a sort identifier.

Remarks

The SORTIDFROMLCID macro is defined as follows:

#define SORTIDFROMLCID(lcid) \

          ((WORD  )((((DWORD)(lcid)) & NLS_VALID_LOCALE_MASK) >> 16))

The following sort identifiers are defined:

Value	Meaning
SORT_DEFAULT	Specifies the default sort.
SORT_JAPANESE_XJIS	Specifies Japanese XJIS order.
SORT_JAPANESE_UNICODE	Specifies Japanese Unicode order.
SORT_CHINESE_BIG5	Specifies Chinese BIG5 order.
SORT_CHINESE_UNICODE	Specifies Chinese Unicode order.
SORT_KOREAN_KSC	Specifies Korean KSC order.
SORT_KOREAN_UNICODE	Specifies Korean Unicode order.
See Also

MAKELANGID, MAKELCID, PRIMARYLANGID, SUBLANGID


SUBLANGID

The SUBLANGID macro extracts a sublanguage identifier from a language identifier.

WORD SUBLANGID(

WORD lgid	// language identifier
);
Parameters

lgid

Specifies the language identifier. This value is a combination of a primary language identifier and a sublanguage identifier and is usually created by using the MAKELANGID macro.

Return Values

The return value is a sublanguage identifier. The following sublanguage identifiers are defined:

SUBLANG_ARABIC_SAUDI_ARABIA	SUBLANG_GERMAN
SUBLANG_ARABIC_IRAQ	SUBLANG_GERMAN_SWISS
SUBLANG_ARABIC_EGYPT	SUBLANG_GERMAN_AUSTRIAN
SUBLANG_ARABIC_LIBYA	SUBLANG_GERMAN_LUXEMBOURG
SUBLANG_ARABIC_ALGERIA	SUBLANG_GERMAN_LIECHTENSTEIN
SUBLANG_ARABIC_MOROCCO	SUBLANG_ITALIAN
SUBLANG_ARABIC_TUNISIA	SUBLANG_ITALIAN_SWISS
SUBLANG_ARABIC_OMAN	SUBLANG_KOREAN
SUBLANG_ARABIC_YEMEN	SUBLANG_KOREAN_JOHAB
SUBLANG_ARABIC_SYRIA	SUBLANG_NEUTRAL
SUBLANG_ARABIC_JORDAN	SUBLANG_NORWEGIAN_BOKMAL
SUBLANG_ARABIC_LEBANON	SUBLANG_NORWEGIAN_NYNORSK
SUBLANG_ARABIC_KUWAIT	SUBLANG_PORTUGUESE
SUBLANG_ARABIC_UAE	SUBLANG_PORTUGUESE_BRAZILIAN
SUBLANG_ARABIC_BAHRAIN	SUBLANG_SERBIAN_LATIN
SUBLANG_ARABIC_QATAR	SUBLANG_SERBIAN_CYRILLIC
SUBLANG_CHINESE_TRADITIONAL	SUBLANG_SPANISH
SUBLANG_CHINESE_SIMPLIFIED	SUBLANG_SPANISH_MEXICAN
SUBLANG_CHINESE_HONGKONG	SUBLANG_SPANISH_MODERN
SUBLANG_CHINESE_SINGAPORE	SUBLANG_SPANISH_GUATEMALA
SUBLANG_DEFAULT	SUBLANG_SPANISH_COSTA_RICA
SUBLANG_DUTCH	SUBLANG_SPANISH_PANAMA
SUBLANG_DUTCH_BELGIAN	SUBLANG_SPANISH_DOMINICAN_ REPUBLIC
SUBLANG_ENGLISH_US	SUBLANG_SPANISH_VENEZUELA
SUBLANG_ENGLISH_UK	SUBLANG_SPANISH_COLOMBIA
SUBLANG_ENGLISH_AUS	SUBLANG_SPANISH_PERU
SUBLANG_ENGLISH_CAN	SUBLANG_SPANISH_ARGENTINA
SUBLANG_ENGLISH_NZ	SUBLANG_SPANISH_ECUADOR
SUBLANG_ENGLISH_EIRE	SUBLANG_SPANISH_CHILE
SUBLANG_ENGLISH_SOUTH_ AFRICA	SUBLANG_SPANISH_URUGUAY
SUBLANG_ENGLISH_JAMAICA	SUBLANG_SPANISH_PARAGUAY
SUBLANG_ENGLISH_CARIBBEAN	SUBLANG_SPANISH_BOLIVIA
SUBLANG_ENGLISH_BELIZE	SUBLANG_SPANISH_EL_SALVADOR
SUBLANG_ENGLISH_TRINIDAD	SUBLANG_SPANISH_HONDURAS
SUBLANG_FRENCH	SUBLANG_SPANISH_NICARAGUA
SUBLANG_FRENCH_BELGIAN	SUBLANG_SPANISH_PUERTO_RICO
SUBLANG_FRENCH_CANADIAN	SUBLANG_SWEDISH
SUBLANG_FRENCH_SWISS	SUBLANG_SWEDISH_FINLAND
SUBLANG_FRENCH_LUXEMBOURG	SUBLANG_SYS_DEFAULT
Remarks

The SUBLANGID macro is defined as follows:

#define SUBLANGID(lgid)        ((WORD  )(lgid) >> 10)

See Also

EnumSystemLocales, LANGIDFROMLCID, MAKELANGID, PRIMARYLANGID


TabCtrl_AdjustRect

The TabCtrl_AdjustRect macro calculates a tab control’s display area given a window rectangle or calculates the window rectangle that would correspond to a specified display area. You can use this macro or explicitly send the TCM_ADJUSTRECT message.

VOID TabCtrl_AdjustRect(

HWND hwnd,
BOOL fLarger,
RECT FAR *prc
);
Parameters

hwnd

Handle to the tab control.

fLarger

Operation to perform. If this parameter is TRUE, prc specifies a display rectangle and receives the corresponding window rectangle. If this parameter is FALSE, prc specifies a window rectangle and receives the corresponding display area.

prc

Pointer to a RECT structure that specifies the given rectangle and receives the calculated rectangle.

Return Values

No return value.

See Also

RECT, TCM_ADJUSTRECT


TabCtrl_DeleteAllItems

The TabCtrl_DeleteAllItems macro removes all items from a tab control. You can use this macro or explicitly send the TCM_DELETEALLITEMS message.

BOOL TabCtrl_DeleteAllItems(

HWND hwnd
);
Parameters

hwnd

Handle to the tab control.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TCM_DELETEALLITEMS


TabCtrl_DeleteItem

The TabCtrl_DeleteItem macro removes an item from a tab control. You can use this macro or explicitly send the TCM_DELETEITEM message.

BOOL TabCtrl_DeleteItem(

HWND hwnd,
int iItem
);
Parameters

hwnd

Handle to the tab control.

iItem

Index of the item to delete.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TCM_DELETEITEM


TabCtrl_GetCurFocus

The TabCtrl_GetCurFocus macro returns the index of the item that has the focus in a tab control. You can use this macro or explicitly send the TCM_GETCURFOCUS message.

int TabCtrl_GetCurFocus(

HWND hwnd
);
Parameters

hwnd

Handle to the tab control.

Return Values

Returns the index of the tab item that has the focus

Remarks

The item that has the focus may be different than the selected item.

See Also

TCM_GETCURFOCUS


TabCtrl_GetCurSel

The TabCtrl_GetCurSel macro determines the currently selected tab in a tab control. You can use this macro or explicitly send the TCM_GETCURSEL message.

int TabCtrl_GetCurSel(

HWND hwnd
);
Parameters

hwnd

Handle to the tab control.

Return Values

Returns the index of the selected tab if successful or  − 1 if no tab is selected.

See Also

TCM_GETCURSEL


TabCtrl_GetImageList

The TabCtrl_GetImageList macro retrieves the image list associated with a tab control. You can use this macro or explicitly send the TCM_GETIMAGELIST message.

HIMAGELIST TabCtrl_GetImageList(

HWND hwnd
);
Return Values

Returns the handle to the image list if successful or NULL otherwise.

See Also

TCM_GETIMAGELIST


TabCtrl_GetItem

The TabCtrl_GetItem macro retrieves information about a tab in a tab control. You can use this macro or explicitly send the TCM_GETITEM message.

BOOL TabCtrl_GetItem(

HWND hwnd,
int iItem,
TC_ITEM FAR *pitem
);
Parameters

hwnd

Handle to the tab control.

iItem

Index of the tab.

pitem

Pointer to a TC_ITEM structure that specifies the information to retrieve and receives information about the tab. When the message is sent, the mask member specifies which attributes to return.

If the mask member specifies the TCIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TC_ITEM, TCM_GETITEM


TabCtrl_GetItemCount

The TabCtrl_GetItemCount macro retrieves the number of tabs in the tab control. You can use this macro or explicitly send the TCM_GETITEMCOUNT message.

int TabCtrl_GetItemCount(

HWND hwnd
);
Parameters

hwnd

Handle to the tab control.

Return Values

Returns the number of items if successful or zero otherwise.

See Also

TCM_GETITEMCOUNT


TabCtrl_GetItemRect

The TabCtrl_GetItemRect macro retrieves the bounding rectangle for a tab in a tab control. You can use this macro or explicitly send the TCM_GETITEMRECT message.

BOOL TabCtrl_GetItemRect(

HWND hwnd,
int iItem,
RECT FAR *prc
);
Parameters

hwnd

Handle to the tab control.

iItem

Index of the tab.

prc

Pointer to a RECT structure that receives the bounding rectangle of the tab, in viewport coordinates.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

RECT, TCM_GETITEMRECT


TabCtrl_GetRowCount

The TabCtrl_GetRowCount macro retrieves the current number of rows of tabs in a tab control. You can use this macro or explicitly send the TCM_GETROWCOUNT message.

int TabCtrl_GetRowCount(

HWND hwnd
);
Parameters

hwnd

Handle to the tab control.

Return Values

Returns the number of rows of tabs.

Remarks

Only tab controls that have the TCS_MULTILINE style can have multiple rows of tabs.

See Also

TCM_GETROWCOUNT


TabCtrl_GetToolTips

The TabCtrl_GetToolTips macro retrieves the handle to the tooltip control associated with a tab control. You can use this macro or explicitly send the TCM_GETTOOLTIPS message.

int TabCtrl_GetToolTips(

HWND hwnd
);
Parameters

hwnd

Handle to the tab control.

Return Values

Returns the handle to the tooltip control if successful or NULL otherwise.

Remarks

A tab control creates a tooltip control if it has the TCS_TOOLTIPS style. You can also assign a tooltip control to a tab control by using the TCM_SETTOOLTIPS message.

See Also

TCM_GETTOOLTIPS, TCM_SETTOOLTIPS


TabCtrl_HitTest

The TabCtrl_HitTest macro determines which tab, if any, is at a specified screen position. You can use this macro or explicitly send the TCM_HITTEST message.

int TabCtrl_HitTest(

HWND hwnd,
TC_HITTESTINFO FAR *pinfo
);
Parameters

hwnd

Handle to the tab control.

pinfo

Pointer to a TC_HITTESTINFO structure that specifies the screen position to test.

Return Values

Returns the index of the tab or  − 1 if no tab is at the specified position.

See Also

TC_HITTESTINFO, TCM_HITTEST


TabCtrl_InsertItem

The TabCtrl_InsertItem macro inserts a new tab in a tab control. You can use this macro or explicitly send the TCM_INSERTITEM message.

int TabCtrl_InsertItem(

HWND hwnd,
int iItem,
const TC_ITEM FAR *pitem
);
Parameters

hwnd

Handle to the tab control.

iItem

Index of the new tab.

pitem

Pointer to a TC_ITEM structure that specifies the attributes of the tab.

Return Values

Returns the index of the new tab if successful or  − 1 otherwise.

See Also

TC_ITEM, TCM_INSERTITEM


TabCtrl_RemoveImage

The TabCtrl_RemoveImage macro removes an image from a tab control’s image list. You can use this macro or explicitly send the TCM_REMOVEIMAGE message.

void TabCtrl_RemoveImage(

HWND hwnd,
int iImage
);
Parameters

hwnd

Handle to the tab control.

iImage

Index of the image to remove.

Return Values

No return value.

Remarks

The tab control updates each tab’s image index, so each tab remains associated with the same image it had been.

See Also

TCM_REMOVEIMAGE


TabCtrl_SetCurFocus

The TabCtrl_SetCurFocus macro sets the focus to a specified tab in a tab control. You can use this macro, or you can explicitly send the TCM_SETCURFOCUS message.

VOID TabCtrl_SetCurFocus(

HWND hwnd,	// handle to the tab control
int  iItem	// index of the tab that gets the focus
);
Parameters

hwnd

Handle to the tab control.

iItem

Specifies the zero-based index of the tab that gets the focus.

Return Valuess

No return value.

Remarks

If the tab control has the TCS_BUTTONS style (button mode), the tab with the focus may be different from the selected tab. For example, when a tab is selected, the user can press the arrow keys to set the focus to a different tab without changing the selected tab. In button mode, the TabCtrl_SetCurFocus macro sets the input focus to the button associated with the specified tab, but it does not change the selected tab.

If the tab control does not have the TCS_BUTTONS style, changing the focus also changes selected tab. In this case, the tab control sends the TCN_SELCHANGING and TCN_SELCHANGE notification messages to its parent window.

See Also

TabCtrl_GetCurFocus, TCM_GETCURFOCUS, TCN_SELCHANGE, TCN_SELCHANGING, TCM_SETCURFOCUS


TabCtrl_SetCurSel

The TabCtrl_SetCurSel macro selects a tab in a tab control. You can use this macro or explicitly send the TCM_SETCURSEL message.

int TabCtrl_SetCurSel(

HWND hwnd,
int iItem
);
Parameters

hwnd

Handle to the tab control.

iItem

Index of the tab to select.

Return Values

Returns the index of the previously selected tab if successful or  − 1 otherwise.

Remarks

A tab control does not send a TCN_SELCHANGING or TCN_SELCHANGE notification message when a tab is selected using the TCM_SETCURSEL message.

See Also

TCM_SETCURSEL, TCN_SELCHANGE, TCN_SELCHANGING


TabCtrl_SetImageList

The TabCtrl_SetImageList macro assigns an image list to a tab control. You can use this macro or explicitly send the TCM_SETIMAGELIST message.

BOOL TabCtrl_SetImageList(

HWND hwnd,
HIMAGELIST himl
);
Parameters

hwnd

Handle to the tab control.

himl

Handle of the image list to assign to the tab control.

Return Values

Returns the handle to the previous image list or NULL if there is no previous image list.

See Also

TCM_SETIMAGELIST


TabCtrl_SetItem

The TabCtrl_SetItem macro sets some or all of a tab’s attributes. You can use this macro or explicitly send the TCM_SETITEM message.

BOOL TabCtrl_SetItem(

HWND hwnd,
int iItem,
TC_ITEM FAR *pitem
);
Parameters

hwnd

Handle to the tab control.

iItem

Index of the item.

pitem

Pointer to a TC_ITEM structure that contains the new item attributes. The mask member specifies which attributes to set.

If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TC_ITEM, TCM_SETITEM


TabCtrl_SetItemExtra

The TabCtrl_SetItemExtra macro sets the number of bytes per tab reserved for application-defined data in a tab control. You can use this macro or explicitly send the TCM_SETITEMEXTRA message.

BOOL TabCtrl_SetItemExtra(

HWND hwnd,
int cb
);
Parameters

hwnd

Handle to the tab control.

cb

Number of extra bytes.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

By default, the number of extra bytes is four. An application that changes the number of extra bytes cannot use the TC_ITEM structure to retrieve and set the application-defined data for a tab. Instead, you must define a new structure that consists of the TC_ITEMHEADER structure followed by application-defined members.

An application should only change the number of extra bytes when a tab control does not contain any tabs.

See Also

TC_ITEM, TC_ITEMHEADER, TCM_SETITEMEXTRA


TabCtrl_SetItemSize

The TabCtrl_SetItemSize macro sets the width and height of tabs in a fixed-width or owner-drawn tab control. You can use this macro or explicitly send the TCM_SETITEMSIZE message.

DWORD TabCtrl_SetItemSize(

HWND hwnd,
int cx,
int cy
);
Parameters

hwnd

Handle to the tab control.

cx and cy

New width and height, in pixels.

Return Values

Returns the old width and height. The width is in the low-order word of the return value, and the height is in the high-order word.

See Also

TCM_SETITEMSIZE


TabCtrl_SetPadding

The TabCtrl_SetPadding macro sets the amount of space (padding) around each tab’s icon and label in a tab control. You can use this macro or explicitly send the TCM_SETPADDING message.

void TabCtrl_SetPadding(

HWND hwnd,
int cx,
int cy
);
Parameters

cx and cy

Amount of horizontal and vertical padding, in pixels.

hwnd

Handle to the tab control.

Return Values

No return value.

See Also

TCM_SETPADDING


TabCtrl_SetToolTips

The TabCtrl_SetToolTips macro assigns a tooltip control to a tab control. You can use this macro or explicitly send the TCM_SETTOOLTIPS message.

void TabCtrl_SetToolTips(

HWND hwndTab,
HWND hwndTT
);
Parameters

hwndTab

Handle to the tab control.

hwndTT

Handle to the tooltip control.

Return Values

No return value.

Remarks

You can get the tooltip control associated with a tab control by using the TCM_GETTOOLTIPS message.

See Also

TCM_GETTOOLTIPS, TCM_SETTOOLTIPS


TEXT Macro
TEXT

The TEXT macro identifies a string as Unicode when the UNICODE compile flag is used or as an ANSI string when Unicode is not defined.

TEXT(

LPTSTR string	// address of ANSI or Unicode string
);
Parameters

string

Specifies the string to be interpreted as either Unicode or ANSI.

Remarks

The TEXT macro is defined as follows:

#define TEXT(quote) L##quote


TreeView_CreateDragImage

The TreeView_CreateDragImage macro creates a dragging bitmap for the specified item in a tree-view control, creates an image list for the bitmap, and adds the bitmap to the image list. An application can display the image when dragging the item by using the image list functions. You can use this macro or explicitly send the TVM_CREATEDRAGIMAGE message.

HIMAGELIST TreeView_CreateDragImage(

hwnd,
hitem
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to the item that receives the new dragging bitmap.

Return Values

Returns the handle of the image list to which the dragging bitmap was added if successful or NULL otherwise.

Remarks

If you create a tree-view control without an associated image list, you cannot use the TreeView_CreateDragImage macro to create the image to display during a drag operation. You must implement your own way to support drag and drop cursor.

See Also

TVM_CREATEDRAGIMAGE


TreeView_DeleteAllItems

The TreeView_DeleteAllItems macro removes an item from a tree-view control. You can use this macro, the TreeView_DeleteItem macro, or explicitly send the TVM_DELETEITEM message.

BOOL TreeView_DeleteAllItems(

hwnd
);
Parameters

hwnd

Handle to the tree-view control.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

If the item label is being edited, the edit operation is canceled and the parent window receives the TVN_ENDLABELEDIT notification message. The parent window receives a TVN_DELETEITEM notification message when the item is removed.

See Also

TreeView_DeleteItem, TVM_DELETEITEM, TVN_DELETEITEM, TVN_ENDLABELEDIT


TreeView_DeleteItem

The TreeView_DeleteItem macro removes an item from a tree-view control. You can use this macro, the TreeView_DeleteAllItems macro, or explicitly send the TVM_DELETEITEM message.

BOOL TreeView_DeleteItem(

hwnd,
hitem
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to the item to delete. If hitem is the TVI_ROOT value, all items are deleted from the tree-view control.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

If the item label is being edited, the edit operation is canceled and the parent window receives the TVN_ENDLABELEDIT notification message. The parent window receives a TVN_DELETEITEM notification message when the item is removed.

See Also

TreeView_DeleteAllItems, TVM_DELETEITEM, TVN_DELETEITEM, TVN_ENDLABELEDIT


TreeView_EditLabel

The TreeView_EditLabel macro begins in-place editing of the specified item’s text, replacing the text of the item with a single-line edit control containing the text. This macro implicitly selects and focuses the specified item. You can use this macro or explicitly send the TVM_EDITLABEL message.

HWND TreeView_EditLabel(

hwnd,
hitem
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to the item to edit.

Return Values

Returns the handle to the edit control used to edit the item text if successful or NULL otherwise.

Remarks

This macro sends a TVN_BEGINLABELEDIT notification message to the parent of the tree-view control.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but do not destroy it.

The control must have the focus before you send this message to the control. Focus can be set using the SetFocus function.

See Also

TVM_EDITLABEL, TVN_BEGINLABELEDIT, SetFocus


TreeView_EndEditLabelNow

The TreeView_EndEditLabelNow macro ends the editing of a tree-view item’s label. You can use this macro or explicitly send the TVM_ENDEDITLABELNOW message.

BOOL TreeView_EndEditLabelNow(

hwnd,
fCancel
);
Parameters

hwnd

Handle to the tree-view control.

fCancel

Variable that indicates whether the editing is canceled without being saved to the label. If this parameter is TRUE, the system cancels editing without saving the changes. Otherwise, the system saves the changes to the label.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

This macro causes the TVN_ENDLABELEDIT notification message to be sent to the parent window of the tree-view control.

See Also

TVM_ENDEDITLABELNOW, TVN_ENDLABELEDIT


TreeView_EnsureVisible

The TreeView_EnsureVisible macro ensures that a tree-view item is visible, expanding the parent item or scrolling the tree-view control, if necessary. You can use this macro or explicitly send the TVM_ENSUREVISIBLE message.

BOOL TreeView_EnsureVisible(

hwnd,
hitem
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to the item.

Return Values

Returns TRUE if the system scrolled the items in the tree-view control to ensure that the specified item is visible. Otherwise, the macro returns FALSE.

Remarks

If the TreeView_EnsureVisible macro expands the parent item, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

See Also

TVM_ENSUREVISIBLE, TVN_ITEMEXPANDED, TVN_ITEMEXPANDING


TreeView_Expand

The TreeView_Expand macro expands or collapses the list of child items, if any, associated with the specified parent item. You can use this macro or explicitly send the TVM_EXPAND message.

BOOL TreeView_Expand(

hwnd,
hitem,
flag
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to the parent item to expand or collapse.

flag

Action flag. This parameter can be one of the following values:

Value	Meaning
TVE_COLLAPSE	Collapses the list.
TVE_COLLAPSERESET	Collapses the list and removes the child items. Note that TVE_COLLAPSE must also be specified.
TVE_EXPAND	Expands the list.
TVE_TOGGLE	Collapses the list if it is currently expanded or expands it if it is currently collapsed.
Return Values

Returns TRUE if any change took place or FALSE otherwise.

Remarks

This macro does not send the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages to the parent window.

See Also

TVM_EXPAND, TVN_ITEMEXPANDED, TVN_ITEMEXPANDING


TreeView_GetChild

The TreeView_GetChild macro retrieves the first child item of the specified tree-view item. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_CHILD flag.

HTREEITEM TreeView_GetChild(

hwnd,
hitem,
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to a tree-view item.

Return Values

Returns the handle to the item if successful or NULL otherwise.

See Also

TreeView_GetNextItem, TreeView_GetNextSibling, TreeView_GetParent, TreeView_GetPrevSibling, TVM_GETNEXTITEM


TreeView_GetCount

The TreeView_GetCount macro retrieves a count of the items in a tree-view control. You can use this macro or explicitly send the TVM_GETCOUNT message.

UINT TreeView_GetCount(

hwnd
);
Parameters

hwnd

Handle to the tree-view control.

Return Values

Returns the count of items.

See Also

TVM_GETCOUNT


TreeView_GetDropHilite

The TreeView_GetDropHilite macro retrieves the tree-view item that is the target of a drag-and-drop operation. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_DROPHILITE flag.

HTREEITEM TreeView_GetDropHilite(

hwnd
);
Parameters

hwnd

Handle to the tree-view control.

Return Values

Returns the handle to the item if successful or NULL otherwise.

See Also

TVM_GETNEXTITEM


TreeView_GetEditControl

The TreeView_GetEditControl macro retrieves the handle to the edit control being used to edit a tree-view item’s text. You can use this macro or explicitly send the TVM_GETEDITCONTROL message.

HWND TreeView_GetEditControl(

hwnd
);
Parameters

hwnd

Handle to the tree-view control.

Return Values

Returns the handle to the edit control if successful or NULL otherwise.

See Also

TVM_GETEDITCONTROL


TreeView_GetFirstVisible

The TreeView_GetFirstVisible macro retrieves the first visible item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_FIRSTVISIBLE flag.

HTREEITEM TreeView_GetFirstVisible(

hwnd
);
Parameters

hwnd

Handle to the tree-view control.

Return Values

Returns the handle to the item if successful or NULL otherwise.

See Also

TreeView_GetNextVisible, TreeView_GetPrevVisible, TVM_GETITEMRECT, TVM_GETNEXTITEM


TreeView_GetImageList

The TreeView_GetImageList macro retrieves the handle to the normal or state image list associated with a tree-view control. You can use this macro or explicitly send the TVM_GETIMAGELIST message.

HIMAGELIST TreeView_GetImageList(

hwnd,
iImage
);
Parameters

hwnd

Handle to the image list.

iImage

Type of image list to retrieve. This parameter can be one of the following values:

Value	Meaning
TVSIL_NORMAL	Retrieves the normal image list, which contains the selected and unselected images for the tree-view item.
TVSIL_STATE	Retrieves the state image list, which contains the images for tree-view items that are in a user-defined state.
Return Values

Returns the handle to the image list.

See Also

TVM_GETIMAGELIST


TreeView_GetIndent

The TreeView_GetIndent macro retrieves the amount, in pixels, that child items are indented relative to their parent items. You can use this macro or explicitly send the TVM_GETINDENT message.

UINT TreeView_GetIndent(

hwnd
);
Parameters

hwnd

Handle to the tree-view control.

Return Values

Returns the amount of indentation.

See Also

TVM_GETINDENT


TreeView_GetISearchString

The TreeView_GetISearchString macro retrieves the incremental search string for a tree-view control. The tree-view control uses the incremental search string to select an item based on characters typed by the user. You can use this macro or explicitly send the TVM_GETISEARCHSTRING message.

BOOL TreeView_GetISearchString(

hwnd,
lpsz
);
Parameters

hwnd

Handle to the tree-view control.

lpsz

Pointer to the buffer that receives the incremental search string.

Return Values

Returns the number of characters in the incremental search string.

If the tree-view control is not in incremental search mode, the return value is zero.

See Also

TVM_GETISEARCHSTRING


TreeView_GetItem

The TreeView_GetItem macro retrieves some or all of a tree-view item’s attributes. You can use this macro or explicitly send the TVM_GETITEM message.

BOOL TreeView_GetItem(

hwnd,
pitem
);
Parameters

hwnd

Handle to the tree-view control.

pitem

Pointer to a TV_ITEM structure that specifies the information to retrieve and receives information about the item. When the TVM_GETITEM message is sent, the hItem member identifies the item to retrieve information about and the mask member specifies the attributes to retrieve.

If mask specifies the TVIF_TEXT value, the pszText member must contain the pointer to the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

If mask specifies the TVIF_STATE value, the stateMask member indicates which item states are to be returned.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TV_ITEM, TVM_GETITEM


TreeView_GetItemRect

The TreeView_GetItemRect macro retrieves the bounding rectangle for a tree-view item and indicates whether the item is visible. You can use this macro or explicitly send the TVM_GETITEMRECT message.

BOOL TreeView_GetItemRect(

hwnd,
hitem,
prc,
fItemRect
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to the tree-view item.

prc

Pointer to a RECT structure that receives the bounding rectangle. The coordinates are relative to the upper-left corner of the tree-view control.

fItemRect

Value specifying the portion of the item for which to retrieve the bounding rectangle. If this parameter is TRUE, the bounding rectangle includes only the text of the item. Otherwise, it includes the entire line that the item occupies in the tree-view control.

Return Values

If the item is visible and retrieves the bounding rectangle, the return value is TRUE. Otherwise, the TVM_GETITEMRECT message returns FALSE and does not retrieve the bounding rectangle.

See Also

RECT, TVM_GETITEMRECT


TreeView_GetNextItem

The TreeView_GetNextItem macro retrieves the tree-view item that bears the specified relationship to a specified item. You can use this macro or one of the related macros, or you can explicitly send the TVM_GETNEXTITEM message.

HTREEITEM TreeView_GetNextItem(

hwnd,
hitem,
flag
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to an item.

flag

Flag specifying the item to retrieve. This parameter can be one of the following values:

Value	Message
TVGN_CARET	Retrieves the currently selected item. You can use the TreeView_GetSelection macro to send this message.
TVGN_CHILD	Retrieves the first child item of the item specified by the hitem parameter. You can use the TreeView_GetChild macro to send this message.
TVGN_DROPHILITE	Retrieves the item that is the target of a drag-and-drop operation. You can use the TreeView_GetDropHilite macro to send this message.
TVGN_FIRSTVISIBLE	Retrieves the first visible item. You can use the TreeView_GetFirstVisible macro to send this message.
TVGN_NEXT	Retrieves the next sibling item. You can use the TreeView_GetNextSibling macro to send this message.
TVGN_NEXTVISIBLE	Retrieves the next visible item that follows the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible. You can use the TreeView_GetNextVisible macro to send this message.
TVGN_PARENT	Retrieves the parent of the specified item. You can use the TreeView_GetParent macro to send this message.
TVGN_PREVIOUS	Retrieves the previous sibling item. You can use the TreeView_GetPrevSibling macro to send this message.
TVGN_PREVIOUSVISIBLE	Retrieves the first visible item that precedes the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible. You can use the TreeView_GetPrevVisible macro to send this message.
TVGN_ROOT	Retrieves the topmost or very first item of the tree-view control. You can use the TreeView_GetRoot macro to send this message.
Return Values

Returns the handle to the item if successful or NULL otherwise.

See Also

TreeView_GetChild, TreeView_GetDropHilite, TreeView_GetFirstVisible, TreeView_GetNextSibling, TreeView_GetNextVisible, TreeView_GetParent, TreeView_GetPrevSibling, TreeView_GetPrevVisible, TreeView_GetRoot, TreeView_GetSelection, TVM_GETITEMRECT, TVM_GETNEXTITEM


TreeView_GetNextSibling

The TreeView_GetNextSibling macro retrieves the next sibling item of a specified item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_NEXT flag.

HTREEITEM TreeView_GetNextSibling(

hwnd,
hitem
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to an item.

Return Values

Returns the handle to the item if successful or NULL otherwise.

See Also

TreeView_GetChild, TreeView_GetNextItem, TreeView_GetParent, TreeView_GetPrevSibling, TVM_GETNEXTITEM


TreeView_GetNextVisible

The TreeView_GetNextVisible macro retrieves the next visible item that follows a specified item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_NEXTVISIBLE flag.

HTREEITEM TreeView_GetNextVisible(

hwnd,
hitem
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to an item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible.

Return Values

Returns the handle to the item if successful or NULL otherwise.

See Also

TreeView_GetFirstVisible, TreeView_GetNextItem, TreeView_GetPrevVisible, TVM_GETITEMRECT, TVM_GETNEXTITEM


TreeView_GetParent

The TreeView_GetParent macro retrieves the parent item of the specified tree-view item. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_PARENT flag.

HTREEITEM TreeView_GetParent(

hwnd,
hitem
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to an item.

Return Values

Returns the handle to the item if successful or NULL otherwise.

See Also

TreeView_GetChild, TreeView_GetNextItem, TreeView_GetNextSibling, TreeView_GetPrevSibling, TVM_GETNEXTITEM


TreeView_GetPrevSibling

The TreeView_GetPrevSibling macro retrieves the previous sibling item of a specified item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_PREVIOUS flag.

HTREEITEM TreeView_GetPrevSibling(

hwnd,
hitem
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to an item.

Return Values

Returns the handle to the item if successful or NULL otherwise.

See Also

TreeView_GetChild, TreeView_GetNextItem, TreeView_GetNextSibling, TreeView_GetParent, TVM_GETNEXTITEM


TreeView_GetPrevVisible

The TreeView_GetPrevVisible macro retrieves the first visible item that precedes a specified item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_PREVIOUSVISIBLE flag.

HTREEITEM TreeView_GetPrevVisible(

hwnd,
hitem
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to an item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible.

Return Values

Returns the handle to the item if successful or NULL otherwise.

See Also

TreeView_GetFirstVisible, TreeView_GetNextItem, TreeView_GetNextVisible, TVM_GETITEMRECT, TVM_GETNEXTITEM


TreeView_GetRoot

The TreeView_GetRoot macro retrieves the topmost or very first item of the tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_ROOT flag.

HTREEITEM TreeView_GetRoot(

hwnd
);
Parameters

hwnd

Handle to the tree-view control.

Return Values

Returns the handle to the item if successful or NULL otherwise.

See Also

TreeView_GetNextItem, TVM_GETNEXTITEM


TreeView_GetSelection

The TreeView_GetSelection macro retrieves the currently selected item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_CARET flag.

HTREEITEM TreeView_GetSelection(

hwnd
);
Parameters

hwnd

Handle to the tree-view control.

Return Values

Returns the handle to the item if successful or NULL otherwise.

See Also

TreeView_GetNextItem, TVM_GETNEXTITEM


TreeView_GetVisibleCount

The TreeView_GetVisibleCount macro obtains the number of items that are fully visible in the client window of a tree-view control. You can use this macro or explicitly send the TVM_GETVISIBLECOUNT message.

UINT TreeView_GetVisibleCount(

hwnd
);
Parameters

hwnd

Handle to the tree-view control.

Return Values

Returns the number of items that are fully visible in the client window of the tree-view control.

Remarks

Note that the return value is the number of fully-visible items. If you can see all of 20 items, and part of one more item, the return value is 20, not 21.

See Also

TVM_GETVISIBLECOUNT


TreeView_HitTest

The TreeView_HitTest macro determines the location of the specified point relative to the client area of a tree-view control. You can use this macro or explicitly send the TVM_HITTEST message.

HTREEITEM TreeView_HitTest(

hwnd,
lpht
);
Parameters

hwnd

Handle to the tree-view control.

lpht

Pointer to a TV_HITTESTINFO structure. When the message is sent, the pt member specifies the coordinates of the point to test. When the message returns, the hItem member is the handle to the item at the specified point or NULL if no item occupies the point. Also, when the message returns, the flags member is a hit-test value that indicates the location of the specified point. For a list of hit-test values, see the description of the TV_HITTESTINFO structure.

Return Values

Returns the handle to the tree-view item that occupies the specified point or NULL if no item occupies the point.

See Also

TV_HITTESTINFO, TVM_HITTEST


TreeView_InsertItem

The TreeView_InsertItem macro inserts a new item in a tree-view control. You can use this macro or explicitly send the TVM_INSERTITEM message.

HTREEITEM TreeView_InsertItem(

hwnd,
lpis
);
Parameters

hwnd

Handle to the tree-view control.

lpis

Pointer to a TV_INSERTSTRUCT structure that specifies the attributes of the tree-view item.

Return Values

Returns the handle to the new item if successful or NULL otherwise.

See Also

TV_INSERTSTRUCT, TVM_INSERTITEM, TVN_ENDLABELEDIT


TreeView_Select

The TreeView_Select macro selects the specified tree-view item, scrolls the item into view, or redraws the item in the style used to indicate the target of a drag-and-drop operation. You can use this macro, the TreeView_SelectItem or TreeView_SelectDropTarget macro, or explicitly send the TVM_SELECTITEM message.

BOOL TreeView_Select(

hwnd,
hitem,
flag
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to an item. If the hitem parameter is NULL, the selection is removed from the currently selected item, if any.

flag

Action flag. This parameter can be one of the following values:

Value	Meaning
TVGN_CARET	Sets the selection to the given item.
TVGN_DROPHILITE	Redraws the given item in the style used to indicate the target of a drag and drop operation.
TVGN_FIRSTVISIBLE	Scrolls the tree view vertically so that the given item is the first visible item.
Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

If the TVGN_CARET value is specified, the parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages. Also, if the specified item is the child of a collapsed parent item, the parent’s list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

See Also

TreeView_SelectDropTarget, TreeView_SelectItem, TreeView_SelectSetFirstVisible, TVM_SELECTITEM, TVN_ITEMEXPANDED, TVN_ITEMEXPANDING, TVN_SELCHANGED, TVN_SELCHANGING


TreeView_SelectItem

The TreeView_SelectItem macro selects the specified tree-view item, scrolls the item into view, or redraws the item in the style used to indicate the target of a drag-and-drop operation. You can use this macro, the TreeView_Select or TreeView_SelectDropTarget macro, or explicitly send the TVM_SELECTITEM message.

BOOL TreeView_SelectItem(

hwnd,
hitem
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to an item. If the hitem parameter is NULL, the selection is removed from the currently selected item, if any.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

If the TVGN_CARET value is specified, the parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages. Also, if the specified item is the child of a collapsed parent item, the parent’s list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Using the TreeView_SelectItem macro is equivalent to sending the TVM_SELECTITEM message with its flag parameter set to the TVGN_CARET value.

See Also

TreeView_Select, TreeView_SelectDropTarget, TreeView_SelectSetFirstVisible, TVM_SELECTITEM, TVM_SELECTITEM, TVN_ITEMEXPANDED, TVN_ITEMEXPANDING, TVN_SELCHANGED, TVN_SELCHANGING


TreeView_SelectDropTarget

The TreeView_SelectDropTarget macro selects the specified tree-view item, scrolls the item into view, or redraws the item in the style used to indicate the target of a drag-and-drop operation. You can use this macro, the TreeView_Select or TreeView_SelectItem macro, or explicitly send the TVM_SELECTITEM message.

BOOL TreeView_SelectDropTarget(

hwnd,
hitem
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to an item. If the hitem parameter is NULL, the selection is removed from the currently selected item, if any.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

If the TVGN_CARET value is specified, the parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages. Also, if the specified item is the child of a collapsed parent item, the parent’s list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Using the TreeView_SelectDropTarget macro is equivalent to sending the TVM_SELECTITEM message with its flag parameter set to the TVGN_DROPHILITE value.

See Also

TreeView_Select, TreeView_SelectItem, TreeView_SelectSetFirstVisible, TVM_SELECTITEM, TVN_ITEMEXPANDED, TVN_ITEMEXPANDING, TVN_SELCHANGED, TVN_SELCHANGING


TreeView_SelectSetFirstVisible

The TreeView_SelectSetFirstVisible macro selects the specified tree-view item, scrolls the item into view, or redraws the item in the style used to indicate the target of a drag-and-drop operation. You can use this macro, the TreeView_Select or TreeView_SelectItem macro, or explicitly send the TVM_SELECTITEM message.

BOOL TreeView_SelectSetFirstVisible(

hwnd,
hitem
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to an item. If the hitem parameter is NULL, the selection is removed from the currently selected item, if any.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

If the TVGN_CARET value is specified, the parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages. Also, if the specified item is the child of a collapsed parent item, the parent’s list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Using the TreeView_SelectSetFirstVisible macro is equivalent to sending the TVM_SELECTITEM message with its flag parameter set to the TVGN_FIRSTVISIBLE value.

See Also

TreeView_Select, TreeView_SelectItem, TreeView_SelectDropTarget, TVM_SELECTITEM, TVN_ITEMEXPANDED, TVN_ITEMEXPANDING, TVN_SELCHANGED, TVN_SELCHANGING


TreeView_SetImageList

The TreeView_SetImageList macro sets the normal or state image list for a tree-view control and redraws the control using the new images. You can use this macro or explicitly send the TVM_SETIMAGELIST message.

HIMAGELIST TreeView_SetImageList(

hwnd,
himl,
iImage
);
Parameters

hwnd

Handle to the tree-view control.

himl

Handle to the image list. If himl is NULL, all images are removed from the tree-view control.

iImage

Type of image list to set. For a list of possible values, see the description of the TVM_GETIMAGELIST message.

Return Values

Returns the handle to the previous image list, if any, or NULL otherwise.

See Also

TVM_GETIMAGELIST, TVM_SETIMAGELIST


TreeView_SetIndent

The TreeView_SetIndent macro sets the width of indentation for a tree-view control and redraws the control to reflect the new width. You can use this macro or explicitly send the TVM_SETINDENT message.

BOOL TreeView_SetIndent(

hwnd,
indent
);
Parameters

hwnd

Handle to the tree-view control.

indent

Width, in pixels, of the indentation. If this parameter is less than the system-defined minimum width, the new width is set to the system-defined minimum.

Return Values

No return value.

See Also

TVM_SETINDENT


TreeView_SetItem

The TreeView_SetItem macro sets some or all of a tree-view item’s attributes. You can use this macro or explicitly send the TVM_SETITEM message.

BOOL TreeView_SetItem(

hwnd,
pitem
);
Parameters

hwnd

Handle to the tree-view control.

pitem

Pointer to a TV_ITEM structure that contains the new item attributes. The hItem member identifies the item, and the mask member specifies which attributes to set.

If mask specifies the TVIF_TEXT value, the pszText member is the pointer to a null-terminated string and the cchTextMax member is ignored.

If mask specifies the TVIF_STATE value, the stateMask member indicates which item states to change and the state member contains the values for those states.

Return Values

Returns zero if successful or  − 1 otherwise.

See Also

TV_ITEM, TVM_SETITEM


TreeView_SortChildren

The TreeView_SortChildren macro sorts the child items of the specified parent item in a tree-view control. You can use this macro or explicitly send the TVM_SORTCHILDREN message.

BOOL TreeView_SortChildren(

hwnd,
hitem,
fRecurse
);
Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to the parent item whose child items are to be sorted.

fRecurse

Reserved for future use. Must be zero.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TVM_SORTCHILDREN


TreeView_SortChildrenCB

The TreeView_SortChildrenCB macro sorts tree-view items using an application-defined callback function that compares the items. You can use this macro or explicitly send the TVM_SORTCHILDRENCB message.

BOOL TreeView_SortChildrenCB(

hwnd,
psort,
fRecurse
);
Parameters

hwnd

Handle to the tree-view control.

psort

Pointer to a TV_SORTCB structure. The lpfnCompare member is the pointer to the application-defined callback function, which is called during the sort operation each time the relative order of two list items needs to be compared. For more information about the callback function, see the description of TV_SORTCB.

fRecurse

Reserved for future use. Must be zero.

Return Values

Returns TRUE if successful or FALSE otherwise.

See Also

TV_SORTCB, TVM_SORTCHILDRENCB


Obsolete Programming Elements

The following table provides a list of function calls and messages that required implementation changes in the Win32 API.

Element	Support	Win32 API Comment
AccessResource	Dropped	No equivalent.
AllocDSToCSAlias	Dropped	No equivalent.
AllocResource	Dropped	No equivalent.
AllocSelector	Dropped	No equivalent.
ChangeSelector	Dropped	No equivalent.
CloseSound	Dropped	Replaced by multimedia sound support.
CountVoiceNotes	Dropped	Replaced by multimedia sound support.
DefineHandleTable	Dropped	No equivalent.
DeviceMode	Dropped	Replaced by portable DocumentProperties.
DlgDirSelect	Dropped	Replaced by portable DlgDirSelectEx.
DlgDirSelectComboBox	Dropped	Replaced by portable DlgDirSelectComboBoxEx.
DOS3Call	Dropped	Replaced by named, portable function.
ExtDeviceMode	Dropped	Replaced by portable DocumentProperties.
FlushComm	Dropped	Replaced by PurgeComm.
FreeSelector	Dropped	No equivalent.
GetAspectRatioFilter	Dropped	Replaced by portable GetAspectRatioFilterEx.
GetBitmapDimension	Dropped	Replaced by portable GetBitmapDimensionEx.
GetBrushOrg	Dropped	Replaced by portable GetBrushOrgEx.
GetCodeHandle	Dropped	No equivalent.
GetCodeInfo	Dropped	No equivalent.
GetCommError	Dropped	Replaced by GetCommState.
GetCurrentPDB	Dropped	No equivalent.
GetCurrentPosition	Dropped	Replaced by portable GetCurrentPositionEx.
GetDCOrg	Dropped	Replaced by portable GetDCOrgEx.
GetDOSEnvironment	Dropped	No equivalent.
GetEnvironment	Dropped	No equivalent.
GetFreeSpace	Dropped	Replaced by GlobalMemoryStatus.
GetFreeSystemResources	Dropped	Replaced by GlobalMemoryStatus.
GetInstanceData	Dropped	No equivalent; use alternative supported IPC mechanism.
GetKBCodePage	Dropped	No function equivalent.
GetMetaFileBits	Dropped	Replaced by portable GetEnhMetaFileBits.
GetSystemDebugState	Dropped	No function equivalent.
GetTempDrive	Dropped	Replaced by portable GetTempPath.
GetTextExtent	Dropped	Replaced by portable GetTextExtentPoint32.
GetTextExtentEx	Dropped	Replaced by portable GetTextExtentExPoint.
GetThresholdEvent	Dropped	Replaced by multimedia sound support.
GetThresholdStatus	Dropped	Replaced by multimedia sound support.
GetViewportExt	Dropped	Replaced by portable GetViewportExtEx.
GetViewportOrg	Dropped	Replaced by portable GetViewportOrgEx.
GetWindowExt	Dropped	Replaced by portable GetWindowExtEx.
GetWindowOrg	Dropped	Replaced by portable GetWindowOrgEx.
GetWinFlags	Dropped	No equivalent.
GlobalCompact	Dropped	No equivalent.
GlobalDosAlloc	Dropped	No equivalent.
GlobalDosFree	Dropped	No equivalent.
GlobalFix	Dropped	No equivalent.
GlobalLRUNewest	Dropped	No equivalent.
GlobalLRUOldest	Dropped	No equivalent.
GlobalNotify	Dropped	No equivalent.
GlobalPageLock	Dropped	No equivalent.
GlobalPageUnlock	Dropped	No equivalent.
GlobalUnfix	Dropped	No equivalent.
GlobalUnwire	Dropped	No equivalent.
GlobalWire	Dropped	No equivalent.
IsGDIObject	Dropped	No equivalent.
LimitEmsPages	Dropped	No equivalent.
LocalCompact	Dropped	No equivalent.
LocalInit	Dropped	No equivalent.
LocalNotify	Dropped	No equivalent.
LocalShrink	Dropped	No equivalent.
LockInput	Dropped	No equivalent.
LockSegment	Dropped	No equivalent.
MoveTo	Dropped	Replaced by portable MoveToEx.
NetBIOSCall	Dropped	Replaced by named, portable function.
OffsetViewportOrg	Dropped	Replaced by portable OffsetViewportOrgEx.
OffsetWindowOrg	Dropped	Replaced by portable OffsetWindowOrgEx.
OpenComm	Dropped	Replaced by CreateFile.
OpenSound	Dropped	Replaced by multimedia sound support.
ProfClear	Dropped	Replaced by profile-string function.
ProfFinish	Dropped	Replaced by profile-string function.
ProfFlush	Dropped	Replaced by profile-string function.
ProfInsChk	Dropped	Replaced by profile-string function.
ProfSampRate	Dropped	Replaced by profile-string function.
ProfSetup	Dropped	Replaced by profile-string function.
ProfStart	Dropped	Replaced by profile-string function.
ProfStop	Dropped	Replaced by profile-string function.
ReadComm	Dropped	Replaced by ReadFile.
ScaleViewportExt	Dropped	Replaced by portable ScaleViewportExtEx.
ScaleWindowExt	Dropped	Replaced by portable ScaleWindowExtEx.
SetBitmapDimension	Dropped	Replaced by portable SetBitmapDimensionEx.
SetCommEventMask	Dropped	Replaced by SetCommMask.
SetEnvironment	Dropped	No equivalent.
SetMetaFileBits	Dropped	Replaced by portable SetEnhMetaFileBits.
SetResourceHandler	Dropped	No equivalent.
SetSoundNoise	Dropped	Replaced by multimedia sound support.
SetSwapAreaSize	Dropped	No equivalent.
SetViewportExt	Dropped	Replaced by portable SetViewportExtEx.
SetViewportOrg	Dropped	Replaced by portable SetViewportOrgEx.
SetVoiceAccent	Dropped	Replaced by multimedia sound support.
SetVoiceEnvelope	Dropped	Replaced by multimedia sound support.
SetVoiceNote	Dropped	Replaced by multimedia sound support.
SetVoiceQueueSize	Dropped	Replaced by multimedia sound support.
SetVoiceSound	Dropped	Replaced by multimedia sound support.
SetVoiceThreshold	Dropped	Replaced by multimedia sound support.
SetWindowExt	Dropped	Replaced by portable SetWindowExtEx.
SetWindowOrg	Dropped	Replaced by portable SetWindowOrgEx.
StartSound	Dropped	Replaced by multimedia sound support.
StopSound	Dropped	Replaced by multimedia sound support.
SwitchStackBack	Dropped	No equivalent.
SwitchStackTo	Dropped	No equivalent.
SyncAllVoices	Dropped	Replaced by multimedia sound support.
UngetCommChar	Dropped	No equivalent.
UnlockSegment	Dropped	No equivalent.
ValidateCodeSegments	Dropped	No equivalent.
ValidateFreeSpaces	Dropped	No equivalent.
WaitSoundState	Dropped	Replaced by multimedia sound support.
WriteComm	Dropped	Replaced by WriteFile.
WM_CTLCOLOR	Dropped	Replaced by WM_CTLCOLOR<type> messages.
GCW_HCURSOR	Dropped	Replaced by GCL_HCURSOR.
GCW_HBRBACKGROUND	Dropped	Replaced by GCL_HBRBACKGROUND.
GCW_HICON	Dropped	Replaced by GCL_HICON.
GWW_HINSTANCE	Dropped	Replaced by GWL_HINSTANCE.
GWW_HWNDPARENT	Dropped	Replaced by GWL_HWNDPARENT.
GWW_ID	Dropped	Replaced by GWL_ID.
GWW_USERDATA	Dropped	Replaced by GWL_USERDATA.
READ	Dropped	Replaced by OF_READ.
WRITE	Dropped	Replaced by OF_WRITE.
READ_WRITE	Dropped	Replaced by OF_READ_WRITE.
MAKEPOINT	Dropped	Replaced by LONG2POINT.


ABC

The ABC structure contains the width of a character in a TrueType font.

typedef struct _ABC { // abc

    int     abcA;

    UINT    abcB;

    int     abcC;

} ABC;

Members

abcA

Specifies the “A” spacing of the character. The “A” spacing is the distance to add to the current position before drawing the character glyph.

abcB

Specifies the “B” spacing of the character. The “B” spacing is the width of the drawn portion of the character glyph.

abcC

Specifies the “C” spacing of the character. The “C” spacing is the distance to add to the current position to provide white space to the right of the character glyph.

Remarks

The total width of a character is the summation of the “A,” “B,” and “C” spaces. Either the “A” or the “C” space can be negative to indicate underhangs or overhangs.

See Also

GetCharABCWidths


ABCFLOAT

The ABCFLOAT structure contains the A, B, and C widths of a font character.

typedef struct _ABCFLOAT { // abcf

    FLOAT   abcfA;

    FLOAT   abcfB;

    FLOAT   abcfC;

} ABCFLOAT;

Members

abcfA

Specifies the “A” spacing of the character. The “A” spacing is the distance to add to the current position before drawing the character glyph.

abcfB

Specifies the “B” spacing of the character. The “B” spacing is the width of the drawn portion of the character glyph.

abcfC

Specifies the “C” spacing of the character. The “C” spacing is the distance to add to the current position to provide white space to the right of the character glyph.

Remarks

The A, B, and C widths are measured along the base line of the font.

The character increment (total width) of a character is the sum of the “A,” “B,” and “C” spaces. Either the “A” or the “C” space can be negative to indicate underhangs or overhangs.

See Also

GetCharABCWidthsFloat


ACCEL

The ACCEL structure defines an accelerator key used in an accelerator table.

typedef struct tagACCEL { // accl

    BYTE   fVirt;

    WORD   key;

    WORD   cmd;

} ACCEL;

Members

fVirt

Specifies the accelerator flags. This member can be a combination of the following values:

Value	Meaning
FALT	The ALT key must be held down when the accelerator key is pressed.
FCONTROL	The CTRL key must be held down when the accelerator key is pressed.
FNOINVERT	Specifies that no top-level menu item is highlighted when the accelerator is used. If this flag is not specified, a top-level menu item will be highlighted, if possible, when the accelerator is used.
FSHIFT	The SHIFT key must be held down when the accelerator key is pressed.
FVIRTKEY	The key member specifies a virtual-key code. If this flag is not specified, key is assumed to specify an ASCII character code.
key

Specifies the accelerator key. This member can be either a virtual-key code or an ASCII character code.

cmd

Specifies the accelerator identifier. This value is placed in the low-order word of the wParam parameter of the WM_COMMAND or WM_SYSCOMMAND message when the accelerator is pressed.

See Also

WM_COMMAND, WM_SYSCOMMAND


AccelTableEntry

The AccelTableEntry structure describes the data in an individual accelerator table resource.

struct AccelTableEntry {

    WORD fFlags;

    WORD wAnsi;

    WORD wId;

    WORD padding;

};

Members

fFlags

Specifies a set of flags that you can use to describe keyboard accelerator characteristics. This member can have one or more of the following values.

Value	Meaning
FVIRTKEY	The accelerator key is a virtual-key code. If this flag is not specified, the accelerator key is assumed to specify an ASCII character code.
FNOINVERT	A menu item on the menu bar is not highlighted when an accelerator is used.
FSHIFT	The accelerator is activated only if the user presses the SHIFT key. This flag applies only to virtual keys.
FCONTROL	The accelerator is activated only if the user presses the CTRL key. This flag applies only to virtual keys.
FALT	The accelerator is activated only if the user presses the ALT key. This flag applies only to virtual keys.
0x80	The entry is last in an accelerator table.
wAnsi

Specifies an ANSI character value or a virtual-key code that identifies the accelerator key.

wId

Identifies the keyboard accelerator. This is the value passed to the window procedure when the user presses the specified key.

padding

The number of bytes inserted to ensure that the structure is aligned on a DWORD boundary.

Remarks

The AccelTableEntry structure is repeated for all accelerator table entries in the resource. The last entry in the table is flagged with the value 0x0080.

You can compute the number of elements in the table if you divide the length of the resource by eight. Then your application can randomly access the individual fixed-length entries.

See Also

CreateAcceleratorTable


ACCESS_ALLOWED_ACE

The ACCESS_ALLOWED_ACE structure defines an access-control entry (ACE) for the discretionary access-control list (ACL) that controls access to an object. An access-allowed ACE allows access to an object for a specific subject identified by a security identifier (SID).

typedef struct _ACCESS_ALLOWED_ACE { // aaace

    ACE_HEADER Header;

    ACCESS_MASK Mask;

    DWORD SidStart;

} ACCESS_ALLOWED_ACE;

Members

Header

Specifies an ACE_HEADER structure.

Mask

Specifies an ACCESS_MASK structure that specifies the access rights granted by this ACE.

SidStart

Specifies a SID. The access rights specified by the Mask member are granted to any subject possessing an enabled SID matching this member.

Remarks

ACE structures must be aligned on doubleword boundaries. All Windows memory-management functions return doubleword-aligned handles to memory.

See Also

AddAccessAllowedAce, AddAce, GetAce, ACCESS_DENIED_ACE, ACCESS_MASK, ACE_HEADER, ACL, SID, SYSTEM_ALARM_ACE, SYSTEM_AUDIT_ACE


ACCESS_DENIED_ACE

The ACCESS_DENIED_ACE structure defines an access-control entry (ACE) for the discretionary access-control list (ACL) controlling access to an object. An access-denied ACE denies access to an object for a specific subject identified by a security identifier (SID).

typedef struct _ACCESS_DENIED_ACE { // adace

    ACE_HEADER Header;

    ACCESS_MASK Mask;

    DWORD SidStart;

} ACCESS_DENIED_ACE;

Members

Header

Specifies an ACE_HEADER structure.

Mask

Specifies an ACCESS_MASK structure specifying the access rights explicitly denied by this ACE.

SidStart

Specifies a SID. The access rights specified by the Mask member are denied to any subject possessing an enabled SID matching this member.

Remarks

ACE structures must be aligned on doubleword boundaries. All Windows memory-management functions return doubleword-aligned handles to memory.

See Also

AddAccessDeniedAce, ACCESS_ALLOWED_ACE, ACCESS_MASK, ACE_HEADER, ACL, SID, SYSTEM_ALARM_ACE, SYSTEM_AUDIT_ACE


ACCESS_MASK

The ACCESS_MASK structure is one doubleword value containing standard, specific, and generic rights. These rights are used in access-control entries (ACEs) and are the primary means of specifying the requested or granted access to an object.

typedef DWORD ACCESS_MASK;

The bits in this value are allocated as follows:

Bits	Meaning
0 through 15	Specific rights. Contains the access mask specific to the object type associated with the mask.
16 through 23	Standard rights. Contains the object’s standard access rights and can be a combination of the following predefined flags:
	Bit	Flag	Meaning
	16	DELETE	Delete access
	17	READ_CONTROL	Read access to the owner, group, and discretionary access-control list (ACL) of the security descriptor
	18	WRITE_DAC	Write access to the discretionary access-control list (ACL)
	19	WRITE_OWNER	Write access to owner
	20	SYNCHRONIZE	Windows NT: Synchronize access
Bits	Meaning
24	Access system security (ACCESS_SYSTEM_SECURITY). This flag is not a typical access type. It is used to indicate access to a system ACL. This type of access requires the calling process to have a specific privilege.
25	Maximum allowed (MAXIMUM_ALLOWED)
26 through 27	Reserved
28	Generic all (GENERIC_ALL)
29	Generic execute (GENERIC_EXECUTE)
30	Generic write (GENERIC_WRITE)
31	Generic read (GENERIC_READ)
The following constants represent the specific and standard access rights:

#define SPECIFIC_RIGHTS_ALL           0x0000FFFF

#define STANDARD_RIGHTS_REQUIRED      0x000F0000

#define STANDARD_RIGHTS_ALL           0x001F0000

See Also

GENERIC_MAPPING


ACCESSTIMEOUT

The ACCESSTIMEOUT structure contains information about the time-out period associated with the Win32 accessibility features. The accessibility time-out period is the length of time that must pass without keyboard and mouse input before the operating system automatically turns off accessibility features. The accessibility features affected by the time-out are the FilterKeys features (SlowKeys, BounceKeys, and RepeatKeys), MouseKeys, ToggleKeys, and StickyKeys. The accessibility time-out is designed for computers that are shared by several users so that options selected by one user do not inconvenience a subsequent user.

Windows 95: The accessibility time-out affects the High Contrast Mode setting.

typedef struct tagACCESSTIMEOUT {     // ato

    UINT cbSize;

    DWORD dwFlags;

    DWORD iTimeOutMSec;

} ACCESSTIMEOUT;

Members

cbSize

Specifies the size, in bytes, of this structure.

dwFlags

A set of bit flags that specify properties of the time-out behavior for accessibility features. The following values are defined:

Value	Meaning
ATF_ONOFFFEEDBACK	If this flag is set, the operating system plays a descending siren sound when the time-out period elapses and the accessibility features are turned off.
ATF_AVAILABLE	If this flag is set, you can set a time-out period for accessibility features. An application can retrieve this value, but cannot set it.
ATF_TIMEOUTON	If this flag is set, a time-out period has been set for accessibility features. If this flag is not set, the features will not time out even though a time-out period is specified.
iTimeOutMSec

Specifies the time-out period, in milliseconds.

Remarks

Use an ACCESSTIMEOUT structure when calling the SystemParametersInfo function with the uiAction parameter set to the SPI_GETACCESSTIMEOUT or SPI_SETACCESSTIMEOUT value. When using SPI_GETACCESSTIMEOUT, you must specify the cbSize member of the ACCESSTIMEOUT structure; the SystemParametersInfo function fills in the remaining members. Specify all structure members when using the SPI_SETACCESSTIMEOUT value.

See Also

SystemParametersInfo


ACE

An ACE is an access-control entry (ACE) in an access-control list (ACL).

Following are the currently defined ACE types:

ACE type	Structure	ACL Type
Access allowed	ACCESS_ALLOWED_ACE	Discretionary
Access denied	ACCESS_DENIED_ACE	Discretionary
System alarm	SYSTEM_ALARM_ACE	System
System audit	SYSTEM_AUDIT_ACE	System
System-alarm ACEs are not supported in the current version of Windows NT.

Remarks

An ACL contains a list of ACEs. An ACE defines access to an object for a specific user or group or defines the types of access that generate system-administration messages or alarms for a specific user or group. The user or group is identified by a security identifier (SID).

Each ACE starts with an ACE_HEADER structure. The format of the data following the header varies according to the ACE type specified in the header.

See Also

AddAce, ACCESS_ALLOWED_ACE, ACCESS_DENIED_ACE, ACL, SYSTEM_ALARM_ACE, SYSTEM_AUDIT_ACE


ACE_HEADER

The ACE_HEADER structure describes the type and size of an access-control entry (ACE).

typedef struct _ACE_HEADER { // acehdr

    BYTE AceType;

    BYTE AceFlags;

    WORD AceSize;

} ACE_HEADER;

Members

AceType

Specifies the ACE type. This member can be one of the following values:

Value	ACE type
ACCESS_ALLOWED_ACE_TYPE	Access-allowed (defined by the ACCESS_ALLOWED_ACE structure)
ACCESS_DENIED_ACE_TYPE	Access-denied (defined by the ACCESS_DENIED_ACE structure)
SYSTEM_AUDIT_ACE_TYPE	System-audit (defined by the SYSTEM_AUDIT_ACE structure)
System-alarm ACEs are not supported in the current version of Windows NT. Applications cannot use the SYSTEM_ALARM_ACE_TYPE value or SYSTEM_ALARM_ACE structure.

AceFlags

Specifies a set of ACE type-specific control flags. This member can be a combination of the following values:

Value	Meaning
CONTAINER_INHERIT_ACE
	The ACE is inherited by container objects, such as directories.
INHERIT_ONLY_ACE
	The ACE does not apply to the container object, but to objects contained by it.
NO_PROPAGATE_INHERIT_ACE
	The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE bits are not propagated to an inherited ACE.
OBJECT_INHERIT_ACE
	The ACE is inherited by noncontainer objects, such as files created within the container object to which the ACE is assigned.
FAILED_ACCESS_ACE_FLAG
	Used with system-audit and system-alarm ACEs to indicate a message is generated for failed access attempts.
SUCCESSFUL_ACCESS_ACE_FLAG
	Used with system-audit and system-alarm ACEs to indicate a message is generated for successful access attempts.
AceSize

Specifies the size, in bytes, of the ACE.

Remarks

An ACE defines access to an object for a specific user or group or defines the types of access that generate system-administration messages or alarms for a specific user or group. The user or group is identified by a security identifier (SID).

See Also

ACCESS_ALLOWED_ACE, ACCESS_DENIED_ACE, ACL, SYSTEM_ALARM_ACE, SYSTEM_AUDIT_ACE


ACL

The ACL structure is the header of an access-control list (ACL). A complete ACL consists of an ACL structure followed by an ordered list of zero or more access-control entries (ACEs).

typedef struct _ACL { // acl

    BYTE AclRevision;

    BYTE Sbz1;

    WORD AclSize;

    WORD AceCount;

    WORD Sbz2;

} ACL;

Members

AclRevision

Specifies the ACL’s revision level. This value should be ACL_REVISION. All ACEs in an ACL must be at the same revision level.

Sbz1

Specifies a zero byte of padding that aligns the AclRevision member on a 16-bit boundary.

AclSize

Specifies the size, in bytes, of the ACL. This value includes both the ACL structure and all the ACEs.

AceCount

Specifies the number of ACEs stored in the ACL.

Sbz2

Specifies two zero bytes of padding that align the ACL structure on a 32-bit boundary.

Remarks

An ACL includes a sequential list of zero or more ACEs. The individual ACEs in an ACL are numbered from 0 to n, where n+1 is the number of ACEs in the ACL. When editing an ACL, an application refers to an ACE within the ACL by its index.

There are two types of ACL: discretionary and system.

A discretionary ACL is controlled by the owner of an object or anyone granted WRITE_DAC access to the object. It specifies the access particular users and groups can have to an object. For example, the owner of a file can use a discretionary ACL to control which users and groups can and cannot have access to the file.

An object may also have system-level security information associated with it, in the form of a system ACL controlled by a system administrator. A system ACL can allow the system administrator to audit any attempts to gain access to an object.

Three ACE structures are currently defined:

ACE structure	Description
ACCESS_ALLOWED_ACE	Grants specified rights to a user or group. This ACE is stored in a discretionary ACL.
ACCESS_DENIED_ACE	Denies specified rights to a user or group. This ACE is stored in a discretionary ACL.
SYSTEM_AUDIT_ACE	Specifies what types of access will cause system-level audits. This ACE is stored in a system ACL.
A fourth ACE structure, SYSTEM_ALARM_ACE, is not currently supported by Windows NT.

The ACL structure is to be treated as though it were opaque and applications are not to attempt to work with its members directly. To ensure that ACLs are semantically correct, applications can use the functions listed in the SeeAlso section to create and manipulate ACLs.

Each ACL and ACE structure begins on a doubleword boundary.

See Also

AddAce, DeleteAce, GetAclInformation, GetSecurityDescriptorDacl, GetSecurityDescriptorSacl, InitializeAcl, IsValidAcl, SetAclInformation, SetSecurityDescriptorDacl, SetSecurityDescriptorSacl


ACL_REVISION_INFORMATION

The ACL_REVISION_INFORMATION structure contains revision information about an ACL structure.

typedef struct _ACL_REVISION_INFORMATION {

    DWORD   AclRevision;

} ACL_REVISION_INFORMATION;

Members

AclRevision

Specifies a revision number. The current revision number is ACL_REVISION.

See Also

GetAclInformation, SetAclInformation, ACL, ACL_INFORMATION_CLASS, ACL_SIZE_INFORMATION


ACL_SIZE_INFORMATION

The ACL_SIZE_INFORMATION structure contains information about the size of an ACL structure.

typedef struct _ACL_SIZE_INFORMATION {

    DWORD   AceCount;

    DWORD   AclBytesInUse;

    DWORD   AclBytesFree;

} ACL_SIZE_INFORMATION;

Members

AceCount

Specifies the number of access-control entries (ACEs) in the access-control list (ACL).

AclBytesInUse

Specifies the number of bytes in the ACL actually used to store the ACEs and ACL structure. This may be less than the total number of bytes allocated to the ACL.

AclBytesFree

Specifies the number of unused bytes in the ACL.

See Also

GetAclInformation, SetAclInformation, ACL, ACL_INFORMATION_CLASS, ACL_REVISION_INFORMATION


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

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.

See Also

NAME_BUFFER, NCB


ADDJOB_INFO_1

The ADDJOB_INFO_1 structure identifies a print job as well as the directory and file in which an application can store that job.

typedef struct _ADDJOB_INFO_1 { // aji1

    LPTSTR  Path;

    DWORD   JobId;

} ADDJOB_INFO_1;

Members

Path

Points to a null-terminated string that contains the path and filename that the application can use to store the print job.

JobId

Identifies the print job.

See Also

AddJob


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.

See Also

NetAlertRaise


ANIMATIONINFO

The ANIMATIONINFO structure specifies the animation effects associated with user actions. This structure is used with the SystemParametersInfo function when the SPI_GETANIMATION or SPI_SETANIMATION action value is specified.

typedef struct tagANIMATIONINFO {

    UINT cbSize;

    int  iMinAnimate;

} ANIMATIONINFO, FAR *LPANIMATIONINFO;

Members

cbSize

Specifies the size of the structure, in bytes.

iMinAnimate

Indicates that minimize and restore animation is enabled (if the member is a nonzero value) or not enabled (if zero).

See Also

SystemParametersInfo


APPBARDATA

typedef struct _AppBarData { // abd

    DWORD  cbSize;           // sizeof(APPBARDATA)

    HWND   hWnd;             // handle of appbar

    UINT   uCallbackMessage; // see below

    UINT   uEdge;            // see below

    RECT   rc;               // see below

    LPARAM lParam;           // see below

} APPBARDATA, *PAPPBARDATA;

Members

uCallbackMessage

Application-defined message identifier. The application uses the specified identifier for notification messages that it sends to the the appbar identified by the hWnd member. This member is used when sending the ABM_NEW message.

uEdge

Flag that specifies an edge of the screen. This member can be one of the following values:

ABE_BOTTOM	Bottom edge
ABE_LEFT	Left edge
ABE_RIGHT	Right edge
ABE_TOP	Top edge
This member is used when sending the ABM_GETAUTOHIDEBAR, ABM_QUERYPOS, ABM_SETAUTOHIDEBAR, and ABM_SETPOS messages.

rc

RECT structure that contains the bounding rectangle, in screen coordinates, of an appbar or the Windows taskbar. This member is used when sending the ABM_GETTASKBARPOS, ABM_QUERYPOS, and ABM_SETPOS messages.

lParam

Message-dependent value. This member is used with the ABM_SETAUTOHIDEBAR message.

Remarks

This structure is used with the SHAppBarMessage function.

See Also

SHAppBarMessage


AsnAny

The AsnAny structure contains an SNMP variable type and value. This structure is a member of the RFC1157VarBind structure that is used as a parameter in many of the SNMP functions.

typedef struct {
    BYTE asnType;
     union {
    // RFC 1155 SimpleSyntax (subset of ISO ASN.1)
       AsnInteger           number;
       AsnOctetString       string;
       AsnObjectIdentifier  object;

    // ISO ASN.1
       AsnSequence          sequence;

    // RFC 1155 ApplicationSyntax
       AsnIPAddress         address;
       AsnCounter           counter;
       AsnGauge             gauge;
       AsnTimeticks         ticks;
       AsnOpaque            arbitrary;
} asnValue;
} AsnAny;

Members

asnType

Indicates the variable's type. This member can be only one of the following values:

Value	Meaning	Printed as
ASN_INTEGER	Indicates an integer variable.	%ld(long)
ASN_OCTETSTRING	Indicates an octet string variable.	putchar <oct>
ASN_OBJECTIDENTIFIER	Indicates an object identifier variable.	.1.2.3.4
ASN_SEQUENCE	Indicates an ASN sequence variable.	ASN_OCTET STRING
ASN_RFC1155_IPADDRESS	Indicates an IP address variable.	157.578.160
ASN_RFC1155_COUNTER	Indicates a counter variable.	%lu (unsigned log)
ASN_RFC1155_GAUGE	Indicates a gauge variable.	%lu (unsigned log)
ASN_RFC1155_TIMETICKS	Indicates a timeticks variable.	%lu (unsigned log)
ASN_RFC1155_OPAQUE	Indicates an opaque variable.	0x5 ox3 ox
ASN_RFC1213_DISPSTRING	Indicates a display string variable.	ASN_OCTET STRING
asnValue

Contains the variable's value. This member can be only one of the following:

Value	Meaning
number	Accesses an integer variable
string	Accesses an octet string variable
object	Accesses an object identifier variable
sequence	Accesses an ASN sequence variable
address	Accesses an IP address variable
counter	Accesses a counter variable
gauge	Accesses a gauge variable
ticks	Accesses a timeticks variable
arbitrary	Accesses an opaque variable
For more information, see RFC 1155.

See Also

RFC1157VarBind


AsnObjectIdentifier

The AsnObjectIdentifier structure represents objects as defined in RFC 1155.

typedef struct {

    UINT idLength;

    UINT * ids ;

} AsnObjectIdentifier;

Members

idLength

Specifies the number of integers in the object.

ids

Pointer to an array of integers that represents the object identifier.

Remarks

None.

See Also

RFC 1155


AsnOctetString

The AsnOctetString structure contains octet quantities, usually bytes, as defined in RFC 1155.

typedef struct {

    BYTE  * stream;

    UINT  length;

    BOOL  dynamic;

} AsnOctetString;

Members

stream

Pointer to the octet stream.

length

The number of octets in the data stream.

dynamic

Flag that specifies if 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 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.

See Also

RFC 1155, SnmpUtilMemFree, SnmpUtilMemAlloc


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.

See Also

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.

See Also

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.

See Also

NetAuditRead


BITMAP

The BITMAP structure defines the type, width, height, color format, and bit values of a bitmap.

typedef struct tagBITMAP {  // bm

   LONG   bmType;

   LONG   bmWidth;

   LONG   bmHeight;

   LONG   bmWidthBytes;

   WORD   bmPlanes;

   WORD   bmBitsPixel;

   LPVOID bmBits;

} BITMAP;

Members

bmType

Specifies the bitmap type. This member must be zero.

bmWidth

Specifies the width, in pixels, of the bitmap. The width must be greater than zero.

bmHeight

Specifies the height, in pixels, of the bitmap. The height must be greater than zero.

bmWidthBytes

Specifies the number of bytes in each scan line. This value must be divisible by 2, because Windows assumes that the bit values of a bitmap form an array that is word aligned.

bmPlanes

Specifies the count of color planes.

bmBitsPixel

Specifies the number of bits required to indicate the color of a pixel.

bmBits

Points to the location of the bit values for the bitmap. The bmBits member must be a long pointer to an array of character (1-byte) values.

Remarks

The bitmap formats currently used are monochrome and color. The monochrome bitmap uses a one-bit, one-plane format. Each scan is a multiple of 32 bits.

Scans are organized as follows for a monochrome bitmap of height n:

    Scan 0

    Scan 1

    .

    .

    .

    Scan n-2

    Scan n-1

The pixels on a monochrome device are either black or white. If the corresponding bit in the bitmap is 1, the pixel is set to the foreground color; if the corresponding bit in the bitmap is zero, the pixel is set to the background color.

All devices that have the RC_BITBLT device capability support bitmaps. For more information, see GetDeviceCaps.

Each device has a unique color format. To transfer a bitmap from one device to another, use the GetDIBits and SetDIBits functions.

See Also

CreateBitmapIndirect, GetObject


BITMAPCOREHEADER

The BITMAPCOREHEADER structure contains information about the dimensions and color format of a device-independent bitmap (DIB).

typedef struct tagBITMAPCOREHEADER { // bmch

        DWORD   bcSize;

        WORD    bcWidth;

        WORD    bcHeight;

        WORD    bcPlanes;

        WORD    bcBitCount;

} BITMAPCOREHEADER;

Members

bcSize

Specifies the number of bytes required by the structure.

bcWidth

Specifies the width of the bitmap, in pixels.

bcHeight

Specifies the height of the bitmap, in pixels.

bcPlanes

Specifies the number of planes for the target device. This value must be 1.

bcBitCount

Specifies the number of bits per pixel. This value must be 1, 4, 8, or 24.

Remarks

The BITMAPCOREINFO structure combines the BITMAPCOREHEADER structure and a color table to provide a complete definition of the dimensions and colors of a DIB. For more information about specifying a device-independent bitmap, see BITMAPCOREINFO structure.

An application should use the information stored in the bcSize member to locate the color table in a BITMAPCOREINFO structure, using a method such as the following:

pColor = ((LPBYTE) pBitmapCoreInfo +

        (WORD) (pBitmapCoreInfo -> bcSize))


BITMAPCOREINFO

The BITMAPCOREINFO structure defines the dimensions and color information for a device-independent bitmap (DIB).

typedef struct _BITMAPCOREINFO {    // bmci

        BITMAPCOREHEADER  bmciHeader;

        RGBTRIPLE         bmciColors[1];

} BITMAPCOREINFO;

Members

bmciHeader

Specifies a BITMAPCOREHEADER structure that contains information about the dimensions and color format of a DIB.

bmciColors

Specifies an array of RGBTRIPLE structures that define the colors in the bitmap.

Remarks

A DIB consists of two parts: a BITMAPCOREINFO structure describing the dimensions and colors of the bitmap, and an array of bytes defining the pixels of the bitmap. The bits in the array are packed together, but each scan line must be padded with zeroes to end on a LONG boundary. The origin of the bitmap is the lower left corner.

The bcBitCount member of the BITMAPCOREHEADER structure determines the number of bits that define each pixel and the maximum number of colors in the bitmap. This member can be one of the following values:

Value	Meaning
1	The bitmap is monochrome, and the bmciColors member contains two entries. Each bit in the bitmap array represents a pixel. If the bit is clear, the pixel is displayed with the color of the first entry in the bmciColors table; if the bit is set, the pixel has the color of the second entry in the table.
4	The bitmap has a maximum of 16 colors, and the bmciColors member contains up to 16 entries. Each pixel in the bitmap is represented by a 4-bit index into the color table. For example, if the first byte in the bitmap is 0x1F, the byte represents two pixels. The first pixel contains the color in the second table entry, and the second pixel contains the color in the sixteenth table entry.
8	The bitmap has a maximum of 256 colors, and the bmciColors member contains up to 256 entries. In this case, each byte in the array represents a single pixel.
24	The bitmap has a maximum of 2 (24)  colors, and the bmciColors member is NULL. Each three-byte triplet in the bitmap array represents the relative intensities of red, green, and blue, respectively, for a pixel.
The colors in the bmciColors table should appear in order of importance.

Alternatively, for functions that use DIBs, the bmciColors member can be an array of 16-bit unsigned integers that specify indices into the currently realized logical palette, instead of explicit RGB values. In this case, an application using the bitmap must call the DIB functions (CreateDIBitmap, CreateDIBPatternBrush, and CreateDIBSection) with the iUsage parameter set to DIB_PAL_COLORS.

Note  The bmciColors member should not contain palette indices if the bitmap is to be stored in a file or transferred to another application. Unless the application has exclusive use and control of the bitmap, the bitmap color table should contain explicit RGB values.

See Also

BITMAPCOREHEADER, CreateDIBitmap, CreateDIBPatternBrush, CreateDIBSection, RGBTRIPLE


BITMAPFILEHEADER

The BITMAPFILEHEADER structure contains information about the type, size, and layout of a file that contains a device-independent bitmap (DIB).

typedef struct tagBITMAPFILEHEADER { // bmfh

        WORD    bfType;

        DWORD   bfSize;

        WORD    bfReserved1;

        WORD    bfReserved2;

        DWORD   bfOffBits;

} BITMAPFILEHEADER;

Members

bfType

Specifies the file type. It must be BM.

bfSize

Specifies the size, in bytes, of the bitmap file.

bfReserved1

Reserved; must be zero.

bfReserved2

Reserved; must be zero.

bfOffBits

Specifies the offset, in bytes, from the BITMAPFILEHEADER structure to the bitmap bits.

Remarks

A BITMAPINFO or BITMAPCOREINFO structure immediately follows the BITMAPFILEHEADER structure in the DIB file.

See Also

BITMAPCOREINFO, BITMAPINFO


BITMAPINFO

The BITMAPINFO structure defines the dimensions and color information for a Windows device-independent bitmap (DIB).

typedef struct tagBITMAPINFO { // bmi

   BITMAPINFOHEADER bmiHeader;

   RGBQUAD          bmiColors[1];

} BITMAPINFO;

Members

bmiHeader

Specifies a BITMAPINFOHEADER structure that contains information about the dimensions and color format of a DIB.

bmiColors

Specifies an array of RGBQUAD or doubleword data types that define the colors in the bitmap.

Remarks

A device-independent bitmap consists of two distinct parts: a BITMAPINFO structure describing the dimensions and colors of the bitmap, and an array of bytes defining the pixels of the bitmap. The bits in the array are packed together, but each scan line must be padded with zeroes to end on a LONG data-type boundary. If the height is positive, the bitmap is a bottom-up DIB and its origin is the lower left corner. If the height is negative, the bitmap is a top-down DIB and its origin is the upper left corner.

The biBitCount member of the BITMAPINFOHEADER structure determines the number of bits that define each pixel and the maximum number of colors in the bitmap. This member can be one of the following values:

Value	Meaning
1	The bitmap is monochrome, and the bmiColors member contains two entries. Each bit in the bitmap array represents a pixel. If the bit is clear, the pixel is displayed with the color of the first entry in the bmiColors table; if the bit is set, the pixel has the color of the second entry in the table.
4	The bitmap has a maximum of 16 colors, and the bmiColors member contains up to 16 entries. Each pixel in the bitmap is represented by a 4-bit index into the color table. For example, if the first byte in the bitmap is 0x1F, the byte represents two pixels. The first pixel contains the color in the second table entry, and the second pixel contains the color in the sixteenth table entry.
8	The bitmap has a maximum of 256 colors, and the bmiColors member contains up to 256 entries. In this case, each byte in the array represents a single pixel.
16	The bitmap has a maximum of 2^16 colors. If the biCompression member of the BITMAPINFOHEADER is BI_RGB, the bmiColors member is NULL. Each WORD in the bitmap array represents a single pixel. The relative intensities of red, green, and blue are represented with 5 bits for each color component. The value for blue is in the least significant 5 bits, followed by 5 bits each for green and red, respectively. The most significant bit is not used. If the biCompression member of the BITMAPINFOHEADER is BI_BITFIELDS, the bmiColors member contains three DWORD color masks that specify the red, green, and blue components, respectively, of each pixel. Each WORD in the bitmap array represents a single pixel. Windows NT: When the biCompression member is BI_BITFIELDS, bits set in each DWORD mask must be contiguous and should not overlap the bits of another mask. All the bits in the pixel do not have to be used.  Windows 95: When the biCompression member is BI_BITFIELDS, Windows 95 supports only the following 16bpp color masks: A 5-5-5 16-bit image, where the blue mask is 0x001F, the green mask is 0x03E0, and the red mask is 0x7C00; and a 5-6-5 16-bit image, where the blue mask is 0x001F, the green mask is 0x07E0, and the red mask is 0xF800.
24	The bitmap has a maximum of 2^24 colors, and the bmiColors member is NULL. Each 3-byte triplet in the bitmap array represents the relative intensities of blue, green, and red, respectively, for a pixel.
32	The bitmap has a maximum of 2^32 colors. If the biCompression member of the BITMAPINFOHEADER is BI_RGB, the bmiColors member is NULL. Each DWORD in the bitmap array represents the relative intensities of blue, green, and red, respectively, for a pixel. The high byte in each DWORD is not used. If the biCompression member of the BITMAPINFOHEADER is BI_BITFIELDS, the bmiColors member contains three DWORD color masks that specify the red, green, and blue components, respectively, of each pixel. Each DWORD in the bitmap array represents a single pixel. Windows NT: When the biCompression member is BI_BITFIELDS, bits set in each DWORD mask must be contiguous and should not overlap the bits of another mask. All the bits in the pixel do not have to be used.  Windows 95: When the biCompression member is BI_BITFIELDS, Windows 95 supports only the following 32bpp color mask: The blue mask is 0x000000FF, the green mask is 0x0000FF00, and the red mask is 0x00FF0000.
The biClrUsed member of the BITMAPINFOHEADER structure specifies the number of color indices in the color table that are actually used by the bitmap. If the biClrUsed member is set to zero, the bitmap uses the maximum number of colors corresponding to the value of the biBitCount member.

The colors in the bmiColors table should appear in order of importance.

Alternatively, for functions that use DIBs, the bmiColors member can be an array of 16-bit unsigned integers that specify indices into the currently realized logical palette, instead of explicit RGB values. In this case, an application using the bitmap must call the DIB functions (CreateDIBitmap, CreateDIBPatternBrush, and CreateDIBSection) with the iUsage parameter set to DIB_PAL_COLORS.

If the bitmap is a packed bitmap (a bitmap in which the bitmap array immediately follows the BITMAPINFO header and which is referenced by a single pointer), the biClrUsed member must be set to an even number when using the DIB_PAL_COLORS mode so the DIB bitmap array starts on a doubleword boundary.

Note  The bmiColors member should not contain palette indices if the bitmap is to be stored in a file or transferred to another application. Unless the application has exclusive use and control of the bitmap, the bitmap color table should contain explicit RGB values.

See Also

BITMAPINFOHEADER, CreateDIBitmap, CreateDIBPatternBrush, CreateDIBSection, RGBQUAD


BITMAPINFOHEADER

The BITMAPINFOHEADER structure contains information about the dimensions and color format of a device-independent bitmap (DIB).

typedef struct tagBITMAPINFOHEADER{ // bmih

   DWORD  biSize;

   LONG   biWidth;

   LONG   biHeight;

   WORD   biPlanes;

   WORD   biBitCount

   DWORD  biCompression;

   DWORD  biSizeImage;

   LONG   biXPelsPerMeter;

   LONG   biYPelsPerMeter;

   DWORD  biClrUsed;

   DWORD  biClrImportant;

} BITMAPINFOHEADER;

Members

biSize

Specifies the number of bytes required by the structure.

biWidth

Specifies the width of the bitmap, in pixels.

biHeight

Specifies the height of the bitmap, in pixels. If biHeight is positive, the bitmap is a bottom-up DIB and its origin is the lower left corner. If biHeight is negative, the bitmap is a top-down DIB and its origin is the upper left corner.

biPlanes

Specifies the number of planes for the target device. This value must be set to 1.

biBitCount

Specifies the number of bits per pixel. This value must be 1, 4, 8, 16, 24, or 32.

biCompression

Specifies the type of compression for a compressed bottom-up bitmap (top-down DIBs cannot be compressed). It can be one of the following values:

Value	Description
BI_RGB	An uncompressed format.
BI_RLE8	A run-length encoded (RLE) format for bitmaps with 8 bits per pixel. The compression format is a two-byte format consisting of a count byte followed by a byte containing a color index. For more information, see the following Remarks section.
BI_RLE4	An RLE format for bitmaps with 4 bits per pixel. The compression format is a two-byte format consisting of a count byte followed by two word-length color indices. For more information, see the following Remarks section.
BI_BITFIELDS	Specifies that the bitmap is not compressed and that the color table consists of three doubleword color masks that specify the red, green, and blue components, respectively, of each pixel. This is valid when used with 16- and 32-bits-per-pixel bitmaps.
biSizeImage

Specifies the size, in bytes, of the image. This may be set to 0 for BI_RGB bitmaps.

biXPelsPerMeter

Specifies the horizontal resolution, in pixels per meter, of the target device for the bitmap. An application can use this value to select a bitmap from a resource group that best matches the characteristics of the current device.

biYPelsPerMeter

Specifies the vertical resolution, in pixels per meter, of the target device for the bitmap.

biClrUsed

Specifies the number of color indices in the color table that are actually used by the bitmap. If this value is zero, the bitmap uses the maximum number of colors corresponding to the value of the biBitCount member for the compression mode specified by biCompression.

If biClrUsed is nonzero and the biBitCount member is less than 16, the biClrUsed member specifies the actual number of colors the graphics engine or device driver accesses. If biBitCount is 16 or greater, then biClrUsed member specifies the size of the color table used to optimize performance of Windows color palettes. If biBitCount equals 16 or 32, the optimal color palette starts immediately following the three doubleword masks.

If the bitmap is a packed bitmap (a bitmap in which the bitmap array immediately follows the BITMAPINFO header and which is referenced by a single pointer), the biClrUsed member must be either 0 or the actual size of the color table.

biClrImportant

Specifies the number of color indices that are considered important for displaying the bitmap. If this value is zero, all colors are important.

Remarks

The BITMAPINFO structure combines the BITMAPINFOHEADER structure and a color table to provide a complete definition of the dimensions and colors of a DIB. For more information about DIBs, see the description of the BITMAPINFO data structure.

An application should use the information stored in the biSize member to locate the color table in a BITMAPINFO structure, as follows:

pColor = ((LPSTR)pBitmapInfo +

    (WORD)(pBitmapInfo->bmiHeader.biSize));

Windows supports formats for compressing bitmaps that define their colors with eight or four bits per pixel. Compression reduces the disk and memory storage required for the bitmap. The following paragraphs describe these formats.

When the biCompression member is BI_RLE8, the bitmap is compressed by using a run-length encoding (RLE) format for an 8-bit bitmap. This format can be compressed in encoded or absolute modes. Both modes can occur anywhere in the same bitmap.

•	Encoded mode consists of two bytes: the first byte specifies the number of consecutive pixels to be drawn using the color index contained in the second byte. In addition, the first byte of the pair can be set to zero to indicate an escape that denotes an end of line, end of bitmap, or delta. The interpretation of the escape depends on the value of the second byte of the pair, which can be one of the following:

Value	Meaning
0	End of line.
1	End of bitmap.
2	Delta. The two bytes following the escape contain unsigned values indicating the horizontal and vertical offsets of the next pixel from the current position.
•	In absolute mode, the first byte is zero and the second byte is a value in the range 03H through FFH. The second byte represents the number of bytes that follow, each of which contains the color index of a single pixel. When the second byte is 2 or less, the escape has the same meaning as in encoded mode. In absolute mode, each run must be aligned on a word boundary.

The following example shows the hexadecimal values of an 8-bit compressed bitmap.

03 04 05 06 00 03 45 56 67 00 02 78 00 02 05 01

02 78 00 00 09 1E 00 01

This bitmap would expand as follows (two-digit values represent a color index for a single pixel):

04 04 04

06 06 06 06 06

45 56 67

78 78

move current position 5 right and 1 down

78 78

end of line

1E 1E 1E 1E 1E 1E 1E 1E 1E

end of RLE bitmap

When the biCompression member is BI_RLE4, the bitmap is compressed by using a run-length encoding format for a 4-bit bitmap, which also uses encoded and absolute modes:

•	In encoded mode, the first byte of the pair contains the number of pixels to be drawn using the color indices in the second byte. The second byte contains two color indices, one in its high-order four bits and one in its low-order four bits. The first of the pixels is drawn using the color specified by the high-order four bits, the second is drawn using the color in the low-order four bits, the third is drawn using the color in the high-order four bits, and so on, until all the pixels specified by the first byte have been drawn.

•	In absolute mode, the first byte is zero, the second byte contains the number of color indices that follow, and subsequent bytes contain color indices in their high- and low-order four bits, one color index for each pixel. In absolute mode, each run must be aligned on a word boundary. The end-of-line, end-of-bitmap, and delta escapes described for BI_RLE8 also apply to BI_RLE4 compression.

The following example shows the hexadecimal values of a 4-bit compressed bitmap.

03 04 05 06 00 06 45 56 67 00 04 78 00 02 05 01

04 78 00 00 09 1E 00 01

This bitmap would expand as follows (single-digit values represent a color index for a single pixel):

0 4 0

0 6 0 6 0

4 5 5 6 6 7

7 8 7 8

move current position 5 right and 1 down

7 8 7 8

end of line

1 E 1 E 1 E 1 E 1

end of RLE bitmap

If biHeight is negative, indicating a top-down DIB, biCompression must be either BI_RGB or BI_BITFIELDS. Top-down DIBs cannot be compressed.

See Also

BITMAPINFO


BITMAPV4HEADER

The BITMAPV4HEADER structure contains information about a Win32 version 4.0 bitmap.

typedef struct {
    DWORD        bV4Size;
    LONG         bV4Width;
    LONG         bV4Height;
    WORD         bV4Planes;
    WORD         bV4BitCount;
    DWORD        bV4V4Compression;
    DWORD        bV4SizeImage;
    LONG         bV4XPelsPerMeter;
    LONG         bV4YPelsPerMeter;
    DWORD        bV4ClrUsed;
    DWORD        bV4ClrImportant;
    DWORD        bV4RedMask;
    DWORD        bV4GreenMask;
    DWORD        bV4BlueMask;
    DWORD        bV4AlphaMask;
    DWORD        bV4CSType;
    CIEXYZTRIPLE bV4Endpoints;
    DWORD        bV4GammaRed;
    DWORD        bV4GammaGreen;
    DWORD        bV4GammaBlue;
} BITMAPV4HEADER, FAR *LPBITMAPV4HEADER, *PBITMAPV4HEADER;


BLOB

A BLOB structure contains information about a block of data.

typedef struct _BLOB {

    ULONG   cbSize;

    BYTE    *pBlobData;

} BLOB;

Members

cbSize

Specifies the size in bytes of the block of data pointed to by pBlobData

Addresses

Points to a block of data.

Remarks

The structure name BLOB comes from the acronym BLOB, which stands for “Binary Large OBject”.

Note that this structure description says nothing about the nature of the data pointed to by pBlobData.

See Also

SERVICE_INFO


BROWSEINFO

Contains parameters for the the SHBrowseForFolder function and receives information about the folder selected by the user.

typedef struct _browseinfo {

    HWND hwndOwner;          // see below

    LPCITEMIDLIST pidlRoot;  // see below

    LPSTR pszDisplayName;    // see below

    LPCSTR lpszTitle;        // see below

    UINT ulFlags;            // see below

    BFFCALLBACK lpfn;        // see below

    LPARAM lParam;           // see below

    int iImage;              // see below

} BROWSEINFO, *PBROWSEINFO, *LPBROWSEINFO;

Members

hwndOwner

Handle of the owner window for the dialog box.

pidlRoot

Pointer to an item identifier list (an ITEMIDLIST structure) specifying the location of the “root” folder to browse from. Only the specified folder and its subfolders appear in the dialog box. This member can be NULL, and in that case, the name space root (the desktop folder) is used.

pszDisplayName

Pointer to a buffer that receives the display name of the folder selected by the user. The size of this buffer is assumed to be MAX_PATH bytes.

lpszTitle

Pointer to a null-terminated string that is displayed above the tree view control in the dialog box. This string can be used to specify instructions to the user.

ulFlags

Value specifying the types of folders to be listed in the dialog box as well as other options. This member can include zero or more of the following values:

BIF_BROWSEFORCOMPUTER	Only returns computers. If the user selects anything other than a computer, the OK button is grayed.
BIF_BROWSEFORPRINTER	Only returns printers. If the user selects anything other than a printer, the OK button is grayed.
BIF_DONTGOBELOWDOMAIN	Does not include network folders below the domain level in the tree view control.
BIF_RETURNFSANCESTORS	Only returns file system ancestors. If the user selects anything other than a file system ancestor, the OK button is grayed.
BIF_RETURNONLYFSDIRS	Only returns file system directories. If the user selects folders that are not part of the file system, the OK button is grayed.
BIF_STATUSTEXT	Includes a status area in the dialog box. The callback function can set the status text by sending messages to the dialog box.
lpfn

Address an application-defined function that the dialog box calls when events occur. For more information, see the description of the BrowseCallbackProc function. This member can be NULL.

lParam

Application-defined value that the dialog box passes to the callback function (if one is specified).

iImage

Variable that receives the image associated with the selected folder. The image is specified as an index to the system image list.

See Also

BrowseCallbackProc, ITEMIDLIST, SHBrowseForFolder


BY_HANDLE_FILE_INFORMATION

The BY_HANDLE_FILE_INFORMATION structure contains information retrieved by the GetFileInformationByHandle function.

typedef struct _BY_HANDLE_FILE_INFORMATION { // bhfi

    DWORD    dwFileAttributes;

    FILETIME ftCreationTime;

    FILETIME ftLastAccessTime;

    FILETIME ftLastWriteTime;

    DWORD    dwVolumeSerialNumber;

    DWORD    nFileSizeHigh;

    DWORD    nFileSizeLow;

    DWORD    nNumberOfLinks;

    DWORD    nFileIndexHigh;

    DWORD    nFileIndexLow;

} BY_HANDLE_FILE_INFORMATION;

Members

dwFileAttributes

Specifies file attributes. This member can be one or more of the following values:

Value	Meaning
FILE_ATTRIBUTE_ARCHIVE
	The file is an archive file. Applications use this value to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED
	The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_DIRECTORY
	The file is a directory.
FILE_ATTRIBUTE_HIDDEN
	The file is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL
	The file has no other attributes. This value is valid only if used alone.
FILE_ATTRIBUTE_OFFLINE
	The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage.
FILE_ATTRIBUTE_READONLY
	The file is read-only. Applications can read the file but cannot write to it or delete it.
FILE_ATTRIBUTE_SYSTEM
	The file is part of the operating system or is used exclusively by it.
FILE_ATTRIBUTE_TEMPORARY
	The file is being used for temporary storage. Applications should write to the file only if absolutely necessary. Most of the file’s data remains in memory without being flushed to the media because the file will soon be deleted.
ftCreationTime

Specifies the time the file was created. If the underlying file system does not support this time member, ftCreationTime is zero.

ftLastAccessTime

Specifies the time the file was last accessed. If the underlying file system does not support this time member, ftLastAccessTime is zero.

ftLastWriteTime

Specifies the last time the file was written to.

dwVolumeSerialNumber

Specifies the serial number of the volume that contains the file.

nFileSizeHigh

Specifies the high-order word of the file size.

nFileSizeLow

Specifies the low-order word of the file size.

nNumberOfLinks

Specifies the number of links to this file. For the FAT file system this member is always 1. For NTFS, it may be more than 1.

nFileIndexHigh

Specifies the high-order word of a unique identifier associated with the file.

nFileIndexLow

Specifies the low-order word of a unique identifier associated with the file. This identifier and the volume serial number uniquely identify a file. This number may change when the system is restarted or when the file is opened. After a process opens a file, the identifier is constant until the file is closed. An application can use this identifier and the volume serial number to determine whether two handles refer to the same file.

See Also

GetFileInformationByHandle


CANDIDATEFORM

The CANDIDATEFORM structure contains position information for the candidate window.

typedef _tagCANDIDATEFORM {
    DWORD  dwIndex;
    DWORD  dwStyle;
    POINT  ptCurrentPos;
    RECT   rcArea;
} CANDIDATEFORM;

Members

dwIndex

Candidate list identifier. Can be 0 for the first list, 1 for the second, and so on. The maximum index is 31.

dwStyle

Position style. This member can be one of the following values:

CFS_CANDIDATEPOS	Display the upper-left corner of the candidate list window at the position given by ptCurrentPos. The coordinates are relative to the upper-left corner of the window containing the list window, and are subject to adjustment by the system.
CFS_EXCLUDE	Exclude the candidate window from the area given by rcArea. The ptCurrentPos member specifies the coordinates of the current point of interest, typically the caret position.
ptCurrentPos

Coordinates of the upper-left corner of the candidate window or the caret position, depending on the value of dwStyle.

rcArea

Coordinates of the upper-left and lower-right corners of the exclusion area.


CANDIDATELIST

The CANDIDATELIST structure contains information about a candidate list.

typedef struct _tagCANDIDATELIST {
    DWORD  dwSize;
    DWORD  dwStyle;
    DWORD  dwCount;
    DWORD  dwSelection;
    DWORD  dwPageStart;
    DWORD  dwPageSize;
    DWORD  dwOffset[];
} CANDIDATELIST;

Members

dwSize

Size, in bytes, of the structure, the offset array, and all candidate strings.

dwStyle

Candidate style values. This member can be one or more of the following values:

Value	Meaning
IME_CAND_UNKNOWN	Candidates are in a style other than listed here.
IME_CAND_READ	Candidates are in same reading.
IME_CAND_CODE	Candidates are in a code range.
IME_CAND_MEANING	Candidates are in same meaning.
IME_CAND_RADICAL	Candidates use same radical character.
IME_CAND_STROKES	Candidates are in same number of strokes.
For the IME_CAND_CODE style, the candidate list has a special structure depending on the value of the dwCount member. If dwCount is 1, the dwOffset member contains a single DBCS character rather than an offset, and no candidate string is provided. If the dwCount member is greater than 1, the dwOffset member contains valid offsets, and the candidate strings are text representations of individual DBCS character values in hexadecimal notation.

dwCount

Number of candidate strings.

dwSelection

Index of the selected candidate string.

dwPageStart

Index of the first candidate string in the candidate window. This varies as the user presses the PAGE UP and PAGE DOWN keys.

dwPageSize

Number of candidate strings to be shown in one page in the candidate window. The user can move to the next page by pressing IME-defined keys, such as the PAGE UP or PAGE DOWN key. If this number is zero, an application can define a proper value by itself.

dwOffset

Offset to the start of the first candidate string, relative to the start of this structure. The offsets for subsequent strings immediately follow this member, forming an array of 32-bit offsets.

Remarks

The candidate strings immediately follow the last offset in the dwOffset array.


CBT_CREATEWND

The CBT_CREATEWND structure contains information passed to a WH_CBT hook procedure before a window is created.

typedef struct tagCBT_CREATEWND { // cbtcw

    LPCREATESTRUCT lpcs;

    HWND           hwndInsertAfter;

} CBT_CREATEWND;

Members

lpcs

Points to a CREATESTRUCT structure that contains initialization parameters for the window about to be created.

hwndInsertAfter

Identifies the window whose position in the Z order precedes that of the window being created.

See Also

CBTProc, CREATESTRUCT, SetWindowsHookEx


CBTACTIVATESTRUCT

The CBTACTIVATESTRUCT structure contains information passed to a WH_CBT hook procedure before a window is activated.

typedef struct tagCBTACTIVATESTRUCT { // cas

    BOOL fMouse;

    HWND hWndActive;

} CBTACTIVATESTRUCT;

Members

fMouse

Specifies whether the window is being activated as a result of a mouse click. This value is TRUE if a mouse click is causing the activation or FALSE if it is not.

hWndActive

Identifies the active window.

See Also

SetWindowsHookEx


CHAR_INFO

The CHAR_INFO structure specifies the Unicode or ANSI character and the foreground (text) and background color attributes of a screen buffer character cell. This structure is used by console functions to read from and write to a console screen buffer.

typedef struct _CHAR_INFO { // chi

    union {                /* Unicode or ANSI character  */

        WCHAR UnicodeChar;

        CHAR AsciiChar;

    } Char;

    WORD Attributes;       // text and background colors

} CHAR_INFO, *PCHAR_INFO;

Members

Char

Specifies either the Unicode (wide-character) or ANSI character of a screen buffer character cell, depending on whether the Unicode or ANSI version of the function is used.

Attributes

Specifies the foreground (text) and background colors in which a screen buffer character cell is drawn. This member can be zero, or it can be any combination of the following values:

BACKGROUND_BLUE	FOREGROUND_BLUE
BACKGROUND_GREEN	FOREGROUND_GREEN
BACKGROUND_RED	FOREGROUND_RED
BACKGROUND_INTENSITY	FOREGROUND_INTENSITY
See Also

ReadConsoleOutput, ScrollConsoleScreenBuffer, WriteConsoleOutput


CHARFORMAT

The CHARFORMAT structure contains information about character formatting in a rich edit control.

typedef struct _charformat {

    UINT     cbSize;

    _WPAD    _wPad1;

    DWORD    dwMask;

    DWORD    dwEffects;

    LONG     yHeight;

    LONG     yOffset;

    COLORREF crTextColor;

    BYTE     bCharSet;

    BYTE     bPitchAndFamily;

    CHAR    szFaceName[LF_FACESIZE];

    _WPAD    _wPad2;

} CHARFORMAT;

Members

cbSize

Size in bytes of this structure. Must be set before passing the structure to the rich edit control.

dwMask

Members containing valid information or attributes to set. This member can be zero or more of the following values:

Value	Meaning
CFM_BOLD	The CFE_BOLD value of the dwEffects member is valid.
CFM_COLOR	The crTextColor member and the CFE_AUTOCOLOR value of the dwEffects member are valid.
CFM_FACE	The szFaceName member is valid.
CFM_ITALIC	The CFE_ITALIC value of the dwEffects member is valid.
CFM_OFFSET	The yOffset member is valid.
CFM_PROTECTED	The CFE_PROTECTED value of the dwEffects member is valid.
CFM_SIZE	The yHeight member is valid.
CFM_STRIKEOUT	The CFE_STRIKEOUT value of the dwEffects member is valid.
CFM_UNDERLINE.	The CFE_UNDERLINE value of the dwEffects member is valid.
dwEffects

Character effects. This member can be a combination of the following values:

Value	Meaning
CFE_AUTOCOLOR	The text color is the return value of GetSysColor (COLOR_WINDOWTEXT).
CFE_BOLD	Characters are bold.
CFE_ITALIC	Characters are italic.
CFE_STRIKEOUT	Characters are struck out.
CFE_UNDERLINE	Characters are underlined.
CFE_PROTECTED	Characters are protected; an attempt to modify them will cause an EN_PROTECTED notification message.
yHeight

Character height.

yOffset

Character offset from the baseline. If this member is positive, the character is a superscript; if it is negative, the character is a subscript.

crTextColor

Text color. This member is ignored if the CFE_AUTOCOLOR character effect is specified.

bCharSet

Character set value. Can be one of the values specified for the lfCharSet member of the LOGFONT structure.

bPitchAndFamily

Font family and pitch. This member is the same as the lfPitchAndFamily member of the LOGFONT structure.

szFaceName

Null-terminated character array specifying the font face name.

Remarks

This structure is used with the EM_GETCHARFORMAT and EM_SETCHARFORMAT messages.

See Also

GetSysColor, EM_GETCHARFORMAT, EM_SETCHARFORMAT, EN_PROTECTED, LOGFONT


CHARRANGE

The CHARRANGE structure specifies a range of characters in a rich edit control. This structure is used with the EM_EXGETSEL and EM_EXSETSEL messages.

If the cpMin and cpMax members are equal, the range is empty. The range includes everything if cpMin is 0 and cpMax is  − 1.

typedef struct _charrange {

    LONG cpMin;

    LONG cpMax;

} CHARRANGE;

Members

cpMin

Index of first intercharacter position.

cpMax

Index of last intercharacter position.

EM_EXGETSEL, EM_EXSETSEL


CHARSET

The CHARSET structure specifies the Unicode blocks and the character sets supported by a given font.

typedef struct tagCHARSET { // chst

    DWORD aflBlock[3];

    DWORD flLang;

} CHARSET;

Members

aflBlock

Specifies which (if any) of the 96 Unicode blocks are supported by a font. If the font contains at least one character in the given block, the corresponding bit is set.

flLang

Identifies the character set supported by the font. This member can be one of the following values:

Value	Meaning
CS_UGL	Supports the Universal Glyph List (UGL) character set.
CS_LATIN	Supports the Latin character set.
CS_GREEK	Supports the Greek character set.
CS_WIN30	Supports the Windows 3.0 character set.
Bits 0 and 31 of flLang are reserved and must be set to zero.


CHARSETINFO

The CHARSETINFO structure contains information about a character set.

typedef struct {
    UINT ciCharset;
    UINT ciACP;
    FONTSIGNATURE fs;
} CHARSETINFO;

Members

ciCharset

Character set value.

ciACP

ANSI code-page value.

fs

A FONTSIGNATURE structure that identifies the Unicode and code-page font signature values. Only one Windows code-page will be set when this structure is set by the function.

See Also

FONTSIGNATURE, TranslateCharsetInfo


CHOOSECOLOR

The CHOOSECOLOR structure contains information the ChooseColor function uses to initialize the Color common dialog box. After the user closes the dialog box, the system returns information about the user’s selection in this structure.

typedef struct {   // cc

    DWORD        lStructSize;

    HWND         hwndOwner;

    HWND         hInstance;

    COLORREF     rgbResult;

    COLORREF*    lpCustColors;

    DWORD        Flags;

    LPARAM       lCustData;

    LPCCHOOKPROC lpfnHook;

    LPCTSTR      lpTemplateName;

} CHOOSECOLOR;

Members

lStructSize

Specifies the length, in bytes, of the structure.

hwndOwner

Identifies the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.

hInstance

If the CC_ENABLETEMPLATEHANDLE flag is set in the Flags member, hInstance is the handle of a memory object containing a dialog box template. If the CC_ENABLETEMPLATE flag is set, hInstance identifies a module that contains a dialog box template named by the lpTemplateName member. If neither CC_ENABLETEMPLATEHANDLE nor CC_ENABLETEMPLATE is set, this member is ignored.

rgbResult

If the CC_RGBINIT flag is set, rgbResult specifies the color initially selected when the dialog box is created. If the specified color value is not among the available colors, the system selects the nearest solid color available. If rgbResult is zero or CC_RGBINIT is not set, the initially selected color is black. If the user clicks the OK button, rgbResult specifies the user’s color selection.

lpCustColors

Pointer to an array of 16 COLORREF values that contain red, green, blue (RGB) values for the custom color boxes in the dialog box. If the user modifies these colors, the system updates the array with the new RGB values. To preserve new custom colors between calls to the ChooseColor function, you should allocate static memory for the array.

Flags

A set of bit flags that you can use to initialize the Color common dialog box. When the dialog box returns, it sets these flags to indicate the user’s input. This member can be a combination of the following flags:

Flag	Meaning
CC_ENABLEHOOK	Enables the hook procedure specified in the lpfnHook member of this structure. This flag is used only to initialize the dialog box.
CC_ENABLETEMPLATE	Indicates that the hInstance and lpTemplateName members specify a dialog box template to use in place of the default template. This flag is used only to initialize the dialog box.
CC_ENABLETEMPLATEHANDLE	Indicates that the hInstance member identifies a data block that contains a preloaded dialog box template. The system ignores the lpTemplateName member if this flag is specified. This flag is used only to initialize the dialog box.
CC_FULLOPEN	Causes the dialog box to display the additional controls that allow the user to create custom colors. If this flag is not set, the user must click the Define Custom Color button to display the custom color controls.
CC_PREVENTFULLOPEN	Disables the Define Custom Colors button.
CC_RGBINIT	Causes the dialog box to use the color specified in the rgbResult member as the initial color selection.
CC_SHOWHELP	Causes the dialog box to display the Help button. The hwndOwner member must specify the window to receive the HELPMSGSTRING registered messages that the dialog box sends when the user clicks the Help button.
lCustData

Specifies application-defined data that the system passes to the hook procedure identified by the lpfnHook member. When the system sends the WM_INITDIALOG message to the hook procedure, the message’s lParam parameter is a pointer to the CHOOSECOLOR structure specified when the dialog was created. The hook procedure can use this pointer to get the lCustData value.

lpfnHook

Pointer to a CCHookProc hook procedure that can process messages intended for the dialog box. This member is ignored unless the CC_ENABLEHOOK flag is set in the Flags member.

lpTemplateName

Pointer to a null-terminated string that names the dialog box template resource in the module identified by the hInstance member. This template is substituted for the standard dialog box template. For numbered dialog box resources, lpTemplateName can be a value returned by the MAKEINTRESOURCE macro. This member is ignored unless the CC_ENABLETEMPLATE flag is set in the Flags member.

See Also

CCHookProc, ChooseColor, MAKEINTRESOURCE, WM_INITDIALOG


CHOOSEFONT

The CHOOSEFONT structure contains information that the ChooseFont function uses to initialize the Font common dialog box. After the user closes the dialog box, the system returns information about the user’s selection in this structure.

typedef struct {    // cf

    DWORD        lStructSize;

    HWND         hwndOwner;

    HDC          hDC;

    LPLOGFONT    lpLogFont;

    INT          iPointSize;

    DWORD        Flags;

    DWORD        rgbColors;

    LPARAM       lCustData;

    LPCFHOOKPROC lpfnHook;

    LPCTSTR      lpTemplateName;

    HINSTANCE    hInstance;

    LPTSTR       lpszStyle;

    WORD         nFontType;

    WORD         ___MISSING_ALIGNMENT__;

    INT          nSizeMin;

    INT          nSizeMax;

} CHOOSEFONT;

Members

lStructSize

Specifies the length, in bytes, of the structure.

hwndOwner

Identifies the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.

hDC

Identifies the device context (or information context) of the printer whose fonts will be listed in the dialog box. This member is used only if the Flags member specifies the CF_PRINTERFONTS or CF_BOTH flag; otherwise, this member is ignored.

lpLogFont

Pointer to a LOGFONT structure. If you set the CF_INITTOLOGFONTSTRUCT flag in the Flags member and initialize the LOGFONT members, the ChooseFont function initializes the dialog box with a font that is the closest possible match. If the user clicks the OK button, ChooseFont sets the members of the LOGFONT structure based on the user’s selections.

iPointSize

Specifies the size of the selected font, in units of 1/10 of a point. The ChooseFont function sets this value after the user closes the dialog box.

Flags

A set of bit flags that you can use to initialize the Font common dialog box. When the dialog box returns, it sets these flags to indicate the user’s input. This member can be a combination of the following flags:

Flag	Meaning
CF_APPLY	Causes the dialog box to display the Apply button. You should provide a hook procedure to process WM_COMMAND messages for the Apply button. The hook procedure can send the WM_CHOOSEFONT_GETLOGFONT message to the dialog box to retrieve the address of the LOGFONT structure that contains the current selections for the font.
CF_ANSIONLY	This flag is obsolete. To limit font selections to all scripts except those that use the OEM or Symbol character sets, use CF_SCRIPTSONLY. To get the Windows 3.1 CF_ANSIONLY behavior, use CF_SELECTSCRIPT and specify ANSI_CHARSET in the lfCharSet member of the LOGFONT structure pointed to by lpLogFont.
CF_BOTH	Causes the dialog box to list the available printer and screen fonts. The hDC member identifies the device context (or information context) associated with the printer. This flag is a combination of the CF_SCREENFONTS and CF_PRINTERFONTS flags.
CF_TTONLY	Specifies that ChooseFont should only enumerate and allow the selection of TrueType fonts.
CF_EFFECTS	Causes the dialog box to display the controls that allow the user to specify strikeout, underline, and text color options. If this flag is set, you can use the rgbColors member to specify the initial text color. You can use the lfStrikeOut and lfUnderline members of the LOGFONT structure pointed to by lpLogFont to specify the initial settings of the strikeout and underline check boxes. ChooseFont can use these members to return the user’s selections.
CF_ENABLEHOOK	Enables the hook procedure specified in the lpfnHook member of this structure.
CF_ENABLETEMPLATE	Indicates that the hInstance and lpTemplateName members specify a dialog box template to use in place of the default template.
CF_ENABLETEMPLATEHANDLE	Indicates that the hInstance member identifies a data block that contains a preloaded dialog box template. The system ignores the lpTemplateName member if this flag is specified.
CF_FIXEDPITCHONLY	Specifies that ChooseFont should select only fixed-pitch fonts.
CF_FORCEFONTEXIST	Specifies that ChooseFont should indicate an error condition if the user attempts to select a font or style that does not exist.
CF_INITTOLOGFONTSTRUCT	Specifies that ChooseFont should use the LOGFONT structure pointed to by the lpLogFont member to initialize the dialog box controls.
CF_LIMITSIZE	Specifies that ChooseFont should select only font sizes within the range specified by the nSizeMin and nSizeMax members.
CF_NOOEMFONTS	Same as the CF_NOVECTORFONTS flag.
CF_NOFACESEL	When using a LOGFONT structure to initialize the dialog box controls, use this flag to selectively prevent the dialog box from displaying an initial selection for the font name combo box. This is useful when there is no single font name that applies to the text selection.
CF_NOSCRIPTSEL	Disables the Script combo box. When this flag is set, the lfCharSet member of the LOGFONT structure is set to DEFAULT_CHARSET when ChooseFont returns. This flag is used only to initialize the dialog box.
CF_NOSTYLESEL	When using a LOGFONT structure to initialize the dialog box controls, use this flag to selectively prevent the dialog box from displaying an initial selection for the font style combo box. This is useful when there is no single font style that applies to the text selection.
CF_NOSIZESEL	When using a LOGFONT structure to initialize the dialog box controls, use this flag to selectively prevent the dialog box from displaying an initial selection for the font size combo box. This is useful when there is no single font size that applies to the text selection.
CF_NOSIMULATIONS	Specifies that ChooseFont should not allow graphics device interface (GDI) font simulations.
CF_NOVECTORFONTS	Specifies that ChooseFont should not allow vector font selections.
CF_NOVERTFONTS	Causes the Font dialog box to list only horizontally oriented fonts.
CF_PRINTERFONTS	Causes the dialog box to list only the fonts supported by the printer associated with the device context (or information context) identified by the hDC member.
CF_SCALABLEONLY	Specifies that ChooseFont should allow only the selection of scalable fonts. (Scalable fonts include vector fonts, scalable printer fonts, TrueType fonts, and fonts scaled by other technologies.)
CF_SCREENFONTS	Causes the dialog box to list only the screen fonts supported by the system.
CF_SCRIPTSONLY	Specifies that ChooseFont should allow selection of fonts for all non-OEM and Symbol character sets, as well as the ANSI character set. This supersedes the CF_ANSIONLY value.
CF_SELECTSCRIPT	When specified on input, only fonts with the character set identified in the lfCharSet member of the LOGFONT structure are displayed. The user will not be allowed to change the character set specified in the Scripts combo box.
CF_SHOWHELP	Causes the dialog box to display the Help button. The hwndOwner member must specify the window to receive the HELPMSGSTRING registered messages that the dialog box sends when the user clicks the Help button.
CF_USESTYLE	Specifies that the lpszStyle member points to a buffer that contains style data that ChooseFont should use to initialize the Font Style combo box. When the user closes the dialog box, ChooseFont copies style data for the user’s selection to this buffer.
CF_WYSIWYG	Specifies that ChooseFont should allow only the selection of fonts available on both the printer and the display. If this flag is specified, the CF_BOTH and CF_SCALABLEONLY flags should also be specified.
rgbColors

If the CF_EFFECTS flag is set, rgbColors specifies the initial text color. When ChooseFont returns successfully, this member contains the RGB value of the text color the user selected.

lCustData

Specifies application-defined data that the system passes to the hook procedure identified by the lpfnHook member. When the system sends the WM_INITDIALOG message to the hook procedure, the message’s lParam parameter is a pointer to the CHOOSEFONT structure specified when the dialog was created. The hook procedure can use this pointer to get the lCustData value.

lpfnHook

Pointer to a CFHookProc hook procedure that can process messages intended for the dialog box. This member is ignored unless the CF_ENABLEHOOK flag is set in the Flags member.

lpTemplateName

Pointer to a null-terminated string that names the dialog box template resource in the module identified by the hInstance member. This template is substituted for the standard dialog box template. For numbered dialog box resources, lpTemplateName can be a value returned by the MAKEINTRESOURCE macro. This member is ignored unless the CF_ENABLETEMPLATE flag is set in the Flags member.

hInstance

If the CF_ENABLETEMPLATEHANDLE flag is set in the Flags member, hInstance is the handle of a memory object containing a dialog box template. If the CF_ENABLETEMPLATE flag is set, hInstance identifies a module that contains a dialog box template named by the lpTemplateName member. If neither CF_ENABLETEMPLATEHANDLE nor CF_ENABLETEMPLATE is set, this member is ignored.

lpszStyle

Pointer to a buffer that contains style data. If the CF_USESTYLE flag is specified, ChooseFont uses the data in this buffer to initialize the font style combo box. When the user closes the dialog box, ChooseFont copies the string in the font style combo box into this buffer.

nFontType

Specifies the type of the selected font when ChooseFont returns. This member can be a combination of the following values:

Value	Meaning
BOLD_FONTTYPE	The font weight is bold. This information is duplicated in the lfWeight member of the LOGFONT structure and is equivalent to FW_BOLD.
ITALIC_FONTTYPE	The italic font attribute is set. This information is duplicated in the lfItalic member of the LOGFONT structure.
PRINTER_FONTTYPE	The font is a printer font.
REGULAR_FONTTYPE	The font weight is normal. This information is duplicated in the lfWeight member of the LOGFONT structure and is equivalent to FW_REGULAR.
SCREEN_FONTTYPE	The font is a screen font.
SIMULATED_FONTTYPE	The font is simulated by the graphics device interface (GDI).
nSizeMin

Specifies the minimum point size a user can select. ChooseFont recognizes this member only if the CF_LIMITSIZE flag is specified.

nSizeMax

Specifies the maximum point size a user can select. ChooseFont recognizes this member only if the CF_LIMITSIZE flag is specified.

See Also

ChooseFont, LOGFONT, MAKEINTRESOURCE


CIDA

This structure corresponds to the CF_IDLIST clipboard format.

typedef struct _IDA {

    UINT cidl;        // number array elements

    UINT aoffset[1];  // see below

} CIDA, * LPIDA;

Member

aoffset

Array of offsets relative to the beginning of the CIDA structure. The first element is the offset of the ITEMIDLIST structure for a folder (absolute from the root). Subsequent elements are offsets of ITEMIDLIST structures for file objects (relative from the parent folder).

See Also

ITEMIDLIST


CIEXYZ

The CIEXYZ structure contains the x, y, and z coordinates of a specific color in a specified color space.

typedef struct tagCIEXYZ
{
    FXPT2DOT30 ciexyzX;

    FXPT2DOT30 ciexyzY;

    FXPT2DOT30 ciexyzZ;

} CIEXYZ;
typedef CIEXYZ FAR* LPCIEXYZ;

Members

ciexyzX

x coordinate in fix point (2.30).

ciexyzY

y coordinate in fix point (2.30).

ciexyzZ

z coordinate in fix point (2.30).


CIEXYZTRIPLE

The CIEXYZTRIPLE structure contains the x, y, and z coordinates of the three colors that correspond to the red, green, and blue endpoints for a specified logical color space.

typedef struct tagCIEXYZTRIPLE
{
    CIEXYZ  ciexyzRed;

    CIEXYZ  ciexyzGreen;

    CIEXYZ  ciexyzBlue;

} CIEXYZTRIPLE;
typedef CIEXYZTRIPLE FAR* LPCIEXYZTRIPLE;

Members

ciexyzRed;

xyz coordinates of red endpoint.

ciexyzGreen

xyz coordinates of green endpoint.

ciexyzBlue

xyz coordinates of blue endpoint.


CLIENTCREATESTRUCT

The CLIENTCREATESTRUCT structure contains information about the menu and first multiple document interface (MDI) child window of an MDI client window. An application passes a pointer to this structure as the lpvParam parameter of the CreateWindow function when creating an MDI client window.

typedef struct tagCLIENTCREATESTRUCT { // ccs

    HANDLE hWindowMenu;

    UINT   idFirstChild;

} CLIENTCREATESTRUCT;

Members

hWindowMenu

Identifies the handle of the MDI application’s Window menu. An MDI application can retrieve this handle from the menu of the MDI frame window by using the GetSubMenu function.

idFirstChild

Specifies the child window identifier of the first MDI child window created. Windows increments the identifier for each additional MDI child window the application creates, and reassigns identifiers when the application destroys a window to keep the range of identifiers contiguous. These identifiers are used in WM_COMMAND messages sent to the application’s MDI frame window when a child window is chosen from the Window menu; they should not conflict with any other command identifiers.

See Also

CreateWindow, GetSubMenu, MDICREATESTRUCT, WM_COMMAND


CMINVOKECOMMANDINFO

Contains information about a context menu command.

typedef struct _CMInvokeCommandInfo {

    DWORD cbSize;        // sizeof(CMINVOKECOMMANDINFO)

    DWORD fMask;

    HWND hwnd;

    LPCSTR lpVerb;

    LPCSTR lpParameters;

    LPCSTR lpDirectory;

    int nShow;

    DWORD dwHotKey;

    HANDLE hIcon;

} CMINVOKECOMMANDINFO, *LPCMINVOKECOMMANDINFO;

Members

fMask

Value specifying zero or more of the following flags:

CMIC_MASK_HOTKEY	Specifies that the dwHotKey member is valid.
CMIC_MASK_ICON	Specifies that the hIcon member is valid.
CMIC_MASK_FLAG_NO_UI	Prevents the system from displaying user interface elements (for example, error messages) while carrying out a command.
hwnd

Handle of the window that owned the context menu, such as the desktop, the explorer, or the tray. An extension might specify this handle as the owner window of any message boxes or dialog boxes it displays.

lpVerb

32-bit value containing zero in the high-order word and the menu-identifier offset of the command to carry out in the low-order word. The shell specifies this value (using the MAKEINTRESOURCE macro) when the user chooses a menu command.

If the high-order word is not zero, this member is the address of a null-terminated string specifying the language-independent name of the command to carry out. This member is typically a string when a command is being activated by an application. The system provides predefined constant values for the following command strings:

Value	String
CMDSTR_NEWFOLDER	“NewFolder”
CMDSTR_VIEWDETAILS	“ViewDetails”
CMDSTR_VIEWLIST	“ViewList”
lpParameters

Optional parameters. This member is always NULL for menu items inserted by a shell extension.

lpDirectory

Optional working directory name. This member is always NULL for menu items inserted by a shell extension.

nShow

Flag to pass to the ShowWindow function if the command displays a window or starts an application.

dwHotKey

Optional hot key to assign any application activated by the command. If fMask does not specify CMIC_MASK_HOTKEY, this member is ignored.

hIcon

Icon to use for any application activated by the command. If the fMask member does not specify CMIC_MASK_ICON, this member is ignored.

Remarks

The address of this structure is passed to the IContextMenu::InvokeCommand method.

See Also

IContextMenu::InvokeCommand, MAKEINTRESOURCE, ShowWindow


COLORADJUSTMENT

The COLORADJUSTMENT structure defines the color adjustment values used by the StretchBlt and StretchDIBits functions when the stretch mode is HALFTONE.

typedef struct  tagCOLORADJUSTMENT {    // ca

    WORD  caSize;

    WORD  caFlags;

    WORD  caIlluminantIndex;

    WORD  caRedGamma;

    WORD  caGreenGamma;

    WORD  caBlueGamma;

    WORD  caReferenceBlack;

    WORD  caReferenceWhite;

    SHORT caContrast;

    SHORT caBrightness;

    SHORT caColorfulness;

    SHORT caRedGreenTint;

} COLORADJUSTMENT;

Members

caSize

Specifies the size, in bytes, of the structure.

caFlags

Specifies how the output image should be prepared. This member may be set to NULL or any combination of the following values:

Value	Meaning
CA_NEGATIVE	Specifies that the negative of the original image should be displayed.
CA_LOG_FILTER	Specifies that a logarithmic function should be applied to the final density of the output colors. This will increase the color contrast when the luminance is low.
caIlluminantIndex

Specifies the type of standard light source under which the image is viewed. This member may be set to one of the following values:

Value	Meaning
ILLUMINANT_DEVICE_DEFAULT	Device’s default. Standard used by output devices.
ILLUMINANT_A	Tungsten lamp.
ILLUMINANT_B	Noon sunlight.
ILLUMINANT_C	NTSC daylight.
ILLUMINANT_D50	Normal print.
ILLUMINANT_D55	Bond paper print.
ILLUMINANT_D65	Standard daylight. Standard for CRTs and pictures.
ILLUMINANT_D75	Northern daylight.
ILLUMINANT_F2	Cool white lamp
ILLUMINANT_TUNGSTEN	Same as ILLUMINANT_A.
ILLUMINANT_DAYLIGHT	Same as ILLUMINANT_C.
ILLUMINANT_FLUORESCENT	Same as ILLUMINANT_F2.
ILLUMINANT_NTSC	Same as ILLUMINANT_C.
caRedGamma

Specifies the nth power gamma-correction value for the red primary of the source colors. The value must be in the range from 2500 to 65,000. A value of 10,000 means no gamma-correction.

caGreenGamma

Specifies the nth power gamma-correction value for the green primary of the source colors. The value must be in the range from 2500 to 65,000. A value of 10,000 means no gamma-correction.

caBlueGamma

Specifies the nth power gamma-correction value for the blue primary of the source colors. The value must be in the range from 2500 to 65,000. A value of 10,000 means no gamma-correction.

caReferenceBlack

Specifies the black reference for the source colors. Any colors that are darker than this are treated as black. The value must be in the range from 0 to 4000.

caReferenceWhite

Specifies the white reference for the source colors. Any colors that are lighter than this are treated as white. The value must be in the range from 6000 to 10,000.

caContrast

Specifies the amount of contrast to be applied to the source object. The value must be in the range from  − 100 to 100. A value of 0 means no contrast adjustment.

caBrightness

Specifies the amount of brightness to be applied to the source object. The value must be in the range from  − 100 to 100. A value of 0 means no brightness adjustment.

caColorfulness

Specifies the amount of colorfulness to be applied to the source object. The value must be in the range from  − 100 to 100. A value of 0 means no colorfulness adjustment.

caRedGreenTint

Specifies the amount of red or green tint adjustment to be applied to the source object. The value must be in the range from  − 100 to 100. Positive numbers adjust towards red and negative numbers adjust towards green. Zero means no tint adjustment.

See Also

SetStretchBltMode, StretchBlt, StretchDIBits


COLORMAP

The COLORMAP structure contains information used by the CreateMappedBitmap function to map the colors of the bitmap.

typedef struct _COLORMAP {

    COLORREF from;

    COLORREF to;

} COLORMAP, FAR* LPCOLORMAP;

Members

from

Color to map from.

to

Color to map to.

See Also

CreateMappedBitmap


COLORREF

The COLORREF value is a 32-bit value used to specify an RGB color.

Remarks

When specifying an explicit RGB color, the COLORREF value has the following hexadecimal form:

0x00bbggrr

The low-order byte contains a value for the relative intensity of red; the second byte contains a value for green; and the third byte contains a value for blue. The high-order byte must be zero. The maximum value for a single byte is 0xFF.

See Also

GetBValue, GetGValue, GetRValue, RGB


COMMCONFIG

The COMMCONFIG structure contains information about the configuration state of a communications device.

typedef struct _COMM_CONFIG {
    DWORD dwSize;
    WORD  wVersion;

    WORD  wReserved;
    DCB   dcb;
    DWORD dwProviderSubType;
    DWORD dwProviderOffset;
    DWORD dwProviderSize;
    WCHAR wcProviderData[1];
} COMMCONFIG, *LPCOMMCONFIG;

Members

dwSize

Specifies the size, in bytes, of the COMMCONFIG structure.

wVersion

Specifies the version number of the COMMCONFIG structure. This parameter can be 1. The version of the provider-specific structure should be included in the wcProviderData member.

wReserved

Reserved; do not use.

dcb

Specifies a device-control block (DCB) structure for RS-232 serial devices. A DCB structure is always present regardless of the port driver subtype specified in the device’s COMMPROP structure.

dwProviderSubType

Identifies the type of communications provider, and thus the format of the provider-specific data. For a list of communications provider types, see the description of the COMMPROP structure.

dwProviderOffset

Specifies the offset, in bytes, of the provider-specific data relative to the beginning of the structure. This member is zero if there is no provider-specific data.

dwProviderSize

Specifies the size, in bytes, of the provider-specific data.

wcProviderData

Contains the provider-specific data, if any. This member may be of any size or may be omitted. Because the COMMCONFIG structure may be expanded in the future, applications should use the dwProviderOffset member to determine the location of this member.

Remarks

If the provider subtype is PST_RS232 or PST_PARALLELPORT the wcProviderData member is omitted. If the provider subtype is PST_MODEM, the wcProviderData member contains a MODEMSETTINGS structure.

See Also

DCB, COMMPROP, GetCommProperties, MODEMSETTINGS


COMMPROP

The COMMPROP structure is used by the GetCommProperties function to return information about a given communications driver.

typedef struct _COMMPROP { // cmmp

    WORD  wPacketLength;       // packet size, in bytes

    WORD  wPacketVersion;      // packet version

    DWORD dwServiceMask;       // services implemented

    DWORD dwReserved1;         // reserved

    DWORD dwMaxTxQueue;        // max Tx bufsize, in bytes

    DWORD dwMaxRxQueue;        // max Rx bufsize, in bytes

    DWORD dwMaxBaud;           // max baud rate, in bps

    DWORD dwProvSubType;       // specific provider type

    DWORD dwProvCapabilities;  // capabilities supported

    DWORD dwSettableParams;    // changable parameters

    DWORD dwSettableBaud;      // allowable baud rates

    WORD  wSettableData;       // allowable byte sizes

    WORD  wSettableStopParity; // stop bits/parity allowed

    DWORD dwCurrentTxQueue;    // Tx buffer size, in bytes

    DWORD dwCurrentRxQueue;    // Rx buffer size, in bytes

    DWORD dwProvSpec1;         // provider-specific data

    DWORD dwProvSpec2;         // provider-specific data

    WCHAR wcProvChar[1];       // provider-specific data

} COMMPROP;

Members

wPacketLength

Specifies the size, in bytes, of the entire data packet, regardless of the amount of data requested.

wPacketVersion

Specifies the version of the structure.

dwServiceMask

Specifies a bitmask indicating which services are implemented by this provider. The SP_SERIALCOMM value is always specified for communications providers, including modem providers.

dwReserved1

Reserved; do not use.

dwMaxTxQueue

Specifies the maximum size, in bytes, of the driver’s internal output buffer. A value of zero indicates that no maximum value is imposed by the serial provider.

dwMaxRxQueue

Specifies the maximum size, in bytes, of the driver’s internal input buffer. A value of zero indicates that no maximum value is imposed by the serial provider.

dwMaxBaud

Specifies the maximum allowable baud rate, in bits per second (bps). This member can be one of the following values:

Value	Meaning
BAUD_075	75 bps
BAUD_110	110 bps
BAUD_134_5	134.5 bps
BAUD_150	150 bps
BAUD_300	300 bps
BAUD_600	600 bps
BAUD_1200	1200 bps
BAUD_1800	1800 bps
BAUD_2400	2400 bps
BAUD_4800	4800 bps
BAUD_7200	7200 bps
BAUD_9600	9600 bps
BAUD_14400	14400 bps
BAUD_19200	19200 bps
BAUD_38400	38400 bps
BAUD_56K	56K bps
BAUD_57600	57600 bps
BAUD_115200	115200 bps
BAUD_128K	128K bps
BAUD_USER	Programmable baud rates available
dwProvSubType

Specifies the specific communications provider type:

Value	Meaning
PST_FAX	FAX device
PST_LAT	LAT protocol
PST_MODEM	Modem device
PST_NETWORK_BRIDGE	Unspecified network bridge
PST_PARALLELPORT	Parallel port
PST_RS232	RS-232 serial port
PST_RS422	RS-422 port
PST_RS423	RS-423 port
PST_RS449	RS-449 port
PST_SCANNER	Scanner device
PST_TCPIP_TELNET	TCP/IP Telnet® protocol
PST_UNSPECIFIED	Unspecified
PST_X25	X.25 standards
dwProvCapabilities

Specifies a bitmask indicating the capabilities offered by the provider. This member can be one of the following values:

Value	Meaning
PCF_16BITMODE	Special 16-bit mode supported
PCF_DTRDSR	DTR (data-terminal-ready)/DSR (data-set-ready) supported
PCF_INTTIMEOUTS	Interval time-outs supported
PCF_PARITY_CHECK	Parity checking supported
PCF_RLSD	RLSD (receive-line-signal-detect) supported
PCF_RTSCTS	RTS (request-to-send)/CTS (clear-to-send) supported
PCF_SETXCHAR	Settable XON/XOFF supported
PCF_SPECIALCHARS	Special character support provided
PCF_TOTALTIMEOUTS	Total (elapsed) time-outs supported
PCF_XONXOFF	XON/XOFF flow control supported
dwSettableParams

Specifies a bitmask indicating the communications parameter that can be changed. This member can be one of the following values:

Value	Meaning
SP_BAUD	Baud rate
SP_DATABITS	Data bits
SP_HANDSHAKING	Handshaking (flow control)
SP_PARITY	Parity
SP_PARITY_CHECK	Parity checking
SP_RLSD	RLSD (receive-line-signal-detect)
SP_STOPBITS	Stop bits
dwSettableBaud

Specifies a bitmask indicating the baud rates that can be used. For values, see the dwMaxBaud member.

wSettableData

Specifies a bitmask indicating the number of data bits that can be set. This member can be one of the following values:

Value	Meaning
DATABITS_5	5 data bits
DATABITS_6	6 data bits
DATABITS_7	7 data bits
DATABITS_8	8 data bits
DATABITS_16	16 data bits
DATABITS_16X	Special wide path through serial hardware lines
wSettableStopParity

Specifies a bitmask indicating the stop bit and parity settings that can be selected. This member can be one of the following values:

Value	Meaning
STOPBITS_10	1 stop bit
STOPBITS_15	1.5 stop bits
STOPBITS_20	2 stop bits
PARITY_NONE	No parity
PARITY_ODD	Odd parity
PARITY_EVEN	Even parity
PARITY_MARK	Mark parity
PARITY_SPACE	Space parity
dwCurrentTxQueue

Specifies the size, in bytes, of the driver’s internal output buffer. A value of zero indicates that the value is unavailable.

dwCurrentRxQueue

Specifies the size, in bytes, of the driver’s internal input buffer. A value of zero indicates that the value is unavailable.

dwProvSpec1

Specifies provider-specific data. Applications should ignore this member unless they have detailed information about the format of the data required by the provider.

Set this member to COMMPROP_INITIALIZED before calling the GetCommProperties function to indicate that the wPacketLength member is already valid.

dwProvSpec2

Specifies provider-specific data. Applications should ignore this member unless they have detailed information about the format of the data required by the provider.

wcProvChar

Specifies provider-specific data. Applications should ignore this member unless they have detailed information about the format of the data required by the provider.

Remarks

The contents of the dwProvSpec1, dwProvSpec2, and wcProvChar members depend on the provider subtype (specified by the dwProvSubType member).

If the provider subtype is PST_MODEM, these members are used as follows:

Value	Meaning
dwProvSpec1	Not used.
dwProvSpec2	Not used.
wcProvChar	Contains a MODEMDEVCAPS structure.
See Also

GetCommProperties


COMMTIMEOUTS

The COMMTIMEOUTS structure is used in the SetCommTimeouts and GetCommTimeouts functions to set and query the time-out parameters for a communications device. The parameters determine the behavior of ReadFile, WriteFile, ReadFileEx, and WriteFileEx operations on the device.

typedef struct _COMMTIMEOUTS {   // ctmo

    DWORD ReadIntervalTimeout;

    DWORD ReadTotalTimeoutMultiplier;

    DWORD ReadTotalTimeoutConstant;

    DWORD WriteTotalTimeoutMultiplier;

    DWORD WriteTotalTimeoutConstant;

} COMMTIMEOUTS,*LPCOMMTIMEOUTS;

Members

ReadIntervalTimeout

Specifies the maximum time, in milliseconds, allowed to elapse between the arrival of two characters on the communications line. During a ReadFile operation, the time period begins when the first character is received. If the interval between the arrival of any two characters exceeds this amount, the ReadFile operation is completed and any buffered data is returned. A value of zero indicates that interval time-outs are not used.

A value of MAXDWORD, combined with zero values for both the ReadTotalTimeoutConstant and ReadTotalTimeoutMultiplier members, specifies that the read operation is to return immediately with the characters that have already been received, even if no characters have been received.

ReadTotalTimeoutMultiplier

Specifies the multiplier, in milliseconds, used to calculate the total time-out period for read operations. For each read operation, this value is multiplied by the requested number of bytes to be read.

ReadTotalTimeoutConstant

Specifies the constant, in milliseconds, used to calculate the total time-out period for read operations. For each read operation, this value is added to the product of the ReadTotalTimeoutMultiplier member and the requested number of bytes.

A value of zero for both the ReadTotalTimeoutMultiplier and ReadTotalTimeoutConstant members indicates that total time-outs are not used for read operations.

WriteTotalTimeoutMultiplier

Specifies the multiplier, in milliseconds, used to calculate the total time-out period for write operations. For each write operation, this value is multiplied by the number of bytes to be written.

WriteTotalTimeoutConstant

Specifies the constant, in milliseconds, used to calculate the total time-out period for write operations. For each write operation, this value is added to the product of the WriteTotalTimeoutMultiplier member and the number of bytes to be written.

A value of zero for both the WriteTotalTimeoutMultiplier and WriteTotalTimeoutConstant members indicates that total time-outs are not used for write operations.

Remarks

If an application sets ReadIntervalTimeout and ReadTotalTimeoutMultiplier to MAXDWORD and sets ReadTotalTimeoutConstant to a value greater than zero and less than MAXDWORD, one of the following occurs when the ReadFile function is called:

•	If there are any characters in the input buffer, ReadFile returns immediately with the characters in the buffer.

•	If there are no characters in the input buffer, ReadFile waits until a character arrives and then returns immediately.

•	If no character arrives within the time specified by ReadTotalTimeoutConstant, ReadFile times out.

See Also

GetCommTimeouts, ReadFile, ReadFileEx, SetCommTimeouts, WriteFile, WriteFileEx


COMPAREITEMSTRUCT

The COMPAREITEMSTRUCT structure supplies the identifiers and application-supplied data for two items in a sorted, owner-drawn list box or combo box.

Whenever an application adds a new item to an owner-drawn list box or combo box created with the CBS_SORT or LBS_SORT style, Windows sends the owner a WM_COMPAREITEM message. The lParam parameter of the message contains a long pointer to a COMPAREITEMSTRUCT structure. Upon receiving the message, the owner compares the two items and returns a value indicating which item sorts before the other.

typedef struct tagCOMPAREITEMSTRUCT { // cis

    UINT  CtlType;

    UINT  CtlID;

    HWND  hwndItem;

    UINT  itemID1;

    DWORD itemData1;

    UINT  itemID2;

    DWORD itemData2;

} COMPAREITEMSTRUCT;

Members

CtlType

Specifies ODT_LISTBOX (an owner-drawn list box) or ODT_COMBOBOX (an owner-drawn combo box).

CtlID

Specifies the identifier of the list box or combo box.

hwndItem

Identifies the control.

itemID1

Specifies the index of the first item in the list box or combo box being compared.

itemData1

Specifies application-supplied data for the first item being compared. (This value was passed as the lParam parameter of the message that added the item to the list box or combo box.)

itemID2

Specifies the index of the second item in the list box or combo box being compared.

itemData2

Specifies application-supplied data for the second item being compared. This value was passed as the lParam parameter of the message that added the item to the list box or combo box.

See Also

WM_COMPAREITEM


COMPCOLOR

The COMPCOLOR structure contains color settings for a composition string.

typedef struct {
    COLORREF crText;
    COLORREF crBackground;
    DWORD dwEffects;
} COMPCOLOR;

Members

crText

Color of text.

crBackground

Color of background.

dwEffects

Character effect values as described for the dwEffects member in the CHARFORMAT structure.

See Also

CHARFORMAT


COMPOSITIONFORM

The COMPOSITIONFORM structure contains position information for a composition window.

typedef _tagCOMPOSITIONFORM {
    DWORD  dwStyle;
    POINT  ptCurrentPos;
    RECT   rcArea;
} COMPOSITIONFORM;

Members

dwStyle

Position style. This member can be one of the following values:

Value	Meaning
CFS_DEFAULT	Move the composition window to the default position. The IME window can display the composition window outside the client area, such as in a floating window.
CFS_FORCE_POSITION	Display the upper-left corner of the composition window at exactly the position given by ptCurrentPos. The coordinates are relative to the upper-left corner of the window containing the composition window and are not subject to adjustment by the IME.
CFS_POINT	Display the upper-left corner of the composition window at the position given by ptCurrentPos. The coordinates are relative to the upper-left corner of the window containing the composition window and are subject to adjustment by the IME.
CFS_RECT	Display the composition window at the position given by rcArea. The coordinates are relative to the upper-left of the window containing the composition window.
ptCurrentPos

Coordinates of the upper-left corner of the composition window.

rcArea

Coordinates of the upper-left and lower-right corners of the composition window.

Remarks

Some IME windows adjust the composition window position specified by the system or the application. The CFS_FORCE_POSITION directs the IME window to skip this adjustment.


COMSTAT

The COMSTAT structure contains information about a communications device. This structure is filled by the ClearCommError function.

typedef struct _COMSTAT { // cst

    DWORD fCtsHold : 1;   // Tx waiting for CTS signal

    DWORD fDsrHold : 1;   // Tx waiting for DSR signal

    DWORD fRlsdHold : 1;  // Tx waiting for RLSD signal

    DWORD fXoffHold : 1;  // Tx waiting, XOFF char rec'd

    DWORD fXoffSent : 1;  // Tx waiting, XOFF char sent

    DWORD fEof : 1;       // EOF character sent

    DWORD fTxim : 1;      // character waiting for Tx

    DWORD fReserved : 25; // reserved

    DWORD cbInQue;        // bytes in input buffer

    DWORD cbOutQue;       // bytes in output buffer

} COMSTAT, *LPCOMSTAT;

Members

fCtsHold

Specifies whether transmission is waiting for the CTS (clear-to-send) signal to be sent. If this member is TRUE, transmission is waiting.

fDsrHold

Specifies whether transmission is waiting for the DSR (data-set-ready) signal to be sent. If this member is TRUE, transmission is waiting.

fRlsdHold

Specifies whether transmission is waiting for the RLSD (receive-line-signal-detect) signal to be sent. If this member is TRUE, transmission is waiting.

fXoffHold

Specifies whether transmission is waiting because the XOFF character was received. If this member is TRUE, transmission is waiting.

fXoffSent

Specifies whether transmission is waiting because the XOFF character was transmitted. If this member is TRUE, transmission is waiting. Transmission halts when the XOFF character is transmitted to a system that takes the next character as XON, regardless of the actual character.

fEof

Specifies whether the end-of-file (EOF) character has been received. If this member is TRUE, the EOF character has been received.

fTxim

If this member is TRUE, there is a character queued for transmission that has come to the communications device by way of the TransmitCommChar function. The communications device transmits such a character ahead of other characters in the device’s output buffer.

fReserved

Reserved; do not use.

cbInQue

Specifies the number of bytes received by the serial provider but not yet read by a ReadFile operation.

cbOutQue

Specifies the number of bytes of user data remaining to be transmitted for all write operations. This value will be zero for a nonoverlapped write.

See Also

ClearCommError, ReadFile, TransmitCommChar


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.

See Also

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.

See Also

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.

See Also

NetConnectionEnum


CONSOLE_CURSOR_INFO

The CONSOLE_CURSOR_INFO structure contains information about the console cursor.

typedef struct _CONSOLE_CURSOR_INFO { // cci

    DWORD  dwSize;

    BOOL   bVisible;

} CONSOLE_CURSOR_INFO, *PCONSOLE_CURSOR_INFO;

Members

dwSize

Specifies a number between 1 and 100, indicating the percentage of the character cell that is filled by the cursor. The cursor appearance varies, ranging from completely filling the cell to showing up as a horizontal line at the bottom of the cell.

bVisible

Specifies the visibility of the cursor. If the cursor is visible, this member is TRUE.

See Also

GetConsoleCursorInfo, SetConsoleCursorInfo


CONSOLE_SCREEN_BUFFER_INFO

The CONSOLE_SCREEN_BUFFER_INFO structure contains information about a console screen buffer.

typedef struct _CONSOLE_SCREEN_BUFFER_INFO { // csbi

    COORD      dwSize;

    COORD      dwCursorPosition;

    WORD       wAttributes;

    SMALL_RECT srWindow;

    COORD      dwMaximumWindowSize;

} CONSOLE_SCREEN_BUFFER_INFO ;

Members

dwSize

Specifies the size, in character columns and rows, of the screen buffer.

dwCursorPosition

Specifies the column and row coordinates of the cursor in the screen buffer.

wAttributes

Specifies the foreground (text) and background color attributes to be used for characters that are written to a screen buffer by the WriteFile and WriteConsole functions, or echoed to a screen buffer by the ReadFile and ReadConsole functions. The attribute values are some combination of the following values: FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_RED, FOREGROUND_INTENSITY, BACKGROUND_BLUE, BACKGROUND_GREEN, BACKGROUND_RED, and BACKGROUND_INTENSITY. For example, the following combination of values produces red text on a white background:

FOREGROUND_RED | BACKGROUND_RED | BACKGROUND_GREEN | BACKGROUND_BLUE

srWindow

Specifies a SMALL_RECT structure that contains the screen buffer coordinates of the upper-left and lower-right corners of the display window.

dwMaximumWindowSize

Specifies the maximum size of the console window, given the current screen buffer size and font and the screen size.

See Also

GetConsoleScreenBufferInfo, ReadConsole, ReadFile, SMALL_RECT, WriteConsole, WriteFile


CONTEXT

A CONTEXT structure contains processor-specific register data. The Windows NT operating system uses CONTEXT structures to perform various internal operations. Currently, there are CONTEXT structures defined for Intel, MIPS, Alpha, and PowerPC, processors. Refer to the header file WinNT.h for definitions of these structures.


CONVCONTEXT

The CONVCONTEXT structure contains information supplied by a DDE client application. The information is useful for specialized or cross-language DDE conversations.

typedef struct tagCONVCONTEXT {   // cc

    UINT  cb;

    UINT  wFlags;

    UINT  wCountryID;

    int   iCodePage;

    DWORD dwLangID;

    DWORD dwSecurity;

    SECURITY_QUALITY_OF_SERVICE qos;  // client side's quality of service

} CONVCONTEXT;

Members

cb

Specifies the structure’s size, in bytes.

wFlags

Specifies conversation context flags. Currently, no flags are defined for this member.

wCountryID

Specifies the country-code identifier for topic-name and item-name strings.

iCodePage

Specifies the code page for topic-name and item-name strings. Non-multilingual clients should set this member to CP_WINANSI. Unicode clients should set this value to CP_WINUNICODE.

dwLangID

Specifies the language identifier for topic-name and item-name strings.

dwSecurity

Specifies a private (application-defined) security code.

qos

Specifies the quality of service a DDE client wants from the system during a given conversation. The quality of service level specified lasts for the duration of the conversation. It cannot be changed once the conversation is started.


CONVINFO

The CONVINFO structure contains information about a DDE conversation.

typedef struct tagCONVINFO {  // ci

    DWORD       cb;

    DWORD       hUser;

    HCONV       hConvPartner;

    HSZ         hszSvcPartner;

    HSZ         hszServiceReq;

    HSZ         hszTopic;

    HSZ         hszItem;

    UINT        wFmt;

    UINT        wType;

    UINT        wStatus;

    UINT        wConvst;

    UINT        wLastError;

    HCONVLIST   hConvList;

    CONVCONTEXT ConvCtxt;

    HWND        hwnd;

    HWND        hwndPartner;

} CONVINFO;

Members

cb

Specifies the structure’s size, in bytes.

hUser

Identifies application-defined data.

hConvPartner

Identifies the partner application in the DDE conversation. This member is zero if the partner has not registered itself (using the DdeInitialize function) to make DDE Management Library (DDEML) function calls. An application should not pass this member to any DDEML function except DdeQueryConvInfo.

hszSvcPartner

Identifies the service name of the partner application.

hszServiceReq

Identifies the service name of the server application that was requested for connection.

hszTopic

Identifies the name of the requested topic.

hszItem

Identifies the name of the requested item. This member is transaction specific.

wFmt

Specifies the format of the data being exchanged. This member is transaction specific.

wType

Specifies the type of the current transaction. This member is transaction specific; it can be one of the following values:

Value	Meaning
XTYP_ADVDATA	Informs a client that advise data from a server has arrived.
XTYP_ADVREQ	Requests a server to send updated data to the client during an advise loop. This transaction results when the server calls DdePostAdvise.
XTYP_ADVSTART	Requests a server to begin an advise loop with a client.
XTYP_ADVSTOP	Notifies a server that an advise loop is stopping.
XTYP_CONNECT	Requests a server to establish a conversation with a client.
XTYP_CONNECT_CONFIRM	Notifies a server that a conversation with a client has been established.
XTYP_DISCONNECT	Notifies a server that a conversation has terminated.
XTYP_EXECUTE	Requests a server to execute a command sent by a client.
XTYP_MONITOR	Notifies an application registered as APPCMD_MONITOR that DDE data is being transmitted.
XTYP_POKE	Requests a server to accept unsolicited data from a client.
XTYP_REGISTER	Notifies other DDEML applications that a server has registered a service name.
XTYP_REQUEST	Requests a server to send data to a client.
XTYP_UNREGISTER	Notifies other DDEML applications that a server has unregistered a service name.
XTYP_WILDCONNECT	Requests a server to establish multiple conversations with the same client.
XTYP_XACT_COMPLETE	Notifies a client that an asynchronous data transaction has been completed.
wStatus

Specifies the status of the current conversation. This member can be a combination of the following values:

Value	Meaning
ST_ADVISE	One or more links are in progress.
ST_BLOCKED	The conversation is blocked.
ST_BLOCKNEXT	The conversation will block after calling the next callback.
ST_CLIENT	The conversation handle passed to the DdeQueryConvInfo function is a client-side handle. If the handle is zero, the conversation handle passed to the DdeQueryConvInfo function is a server-side handle.
ST_CONNECTED	The conversation is connected.
ST_INLIST	The conversation is a member of a conversation list.
ST_ISLOCAL	Both sides of the conversation are using the DDEML.
ST_ISSELF	Both sides of the conversation are using the same instance of the DDEML.
ST_TERMINATED	The conversation has been terminated by the partner.
wConvst

Specifies the conversation state. This member can be one of the following values:

Value	Meaning
XST_ADVACKRCVD	The advise transaction has just been completed.
XST_ADVDATAACKRCVD	The advise data transaction has just been completed.
XST_ADVDATASENT	Advise data has been sent and is awaiting an acknowledgement.
XST_ADVSENT	An advise transaction is awaiting an acknowledgement.
XST_CONNECTED	The conversation has no active transactions.
XST_DATARCVD	The requested data has just been received.
XST_EXECACKRCVD	An execute transaction has just been completed.
XST_EXECSENT	An execute transaction is awaiting an acknowledgement.
XST_INCOMPLETE	The last transaction failed.
XST_INIT1	Mid-initiate state 1.
XST_INIT2	Mid-initiate state 2.
XST_NULL	Pre-initiate state.
XST_POKEACKRCVD	A poke transaction has just been completed.
XST_POKESENT	A poke transaction is awaiting an acknowledgement.
XST_REQSENT	A request transaction is awaiting an acknowledgement.
XST_UNADVACKRCVD	An unadvise transaction has just been completed.
XST_UNADVSENT	An unadvise transaction is awaiting an acknowledgement.
wLastError

Specifies the error value associated with the last transaction.

hConvList

Identifies the conversation list if the handle of the current conversation is in a conversation list. This member is NULL if the conversation is not in a conversation list.

ConvCtxt

Specifies the conversation context.

hwnd

Identifies the window of the calling application involved in the conversation.

hwndPartner

Identifies the window of the partner application involved in the current conversation.

See Also

CONVCONTEXT, DdeInitialize, DdePostAdvise, DdeQueryConvInfo


COORD

The COORD structure defines the coordinates of a character cell in a console screen buffer. The origin of the coordinate system (0,0) is at the top, left cell of the buffer.

typedef struct _COORD { // coord.

    SHORT X;      // horizontal coordinate

    SHORT Y;      // vertical coordinate

} COORD;

Members

X

Horizontal or column value.

Y

Vertical or row value.


COPYDATASTRUCT

The COPYDATASTRUCT structure contains data to be passed to another application by the WM_COPYDATA message.

typedef struct tagCOPYDATASTRUCT {  // cds

    DWORD dwData;

    DWORD cbData;

    PVOID lpData;

} COPYDATASTRUCT;

Members

dwData

Specifies up to 32 bits of data to be passed to the receiving application.

cbData

Specifies the size, in bytes, of the data pointed to by the lpData member.

lpData

Points to data to be passed to the receiving application. This member can be NULL.

See Also

WM_COPYDATA


CPINFO

The CPINFO structure contains information about a code page.

struct _cpinfo {

    UINT MaxCharSize;

    BYTE DefaultChar[MAX_DEFAULTCHAR];

    BYTE LeadByte[MAX_LEADBYTES];

} CPINFO;

Members

MaxCharSize

Specifies the maximum length, in bytes, of a character in this code page.

DefaultChar

Specifies the default character used in translations into this code page. This character is used by the WideCharToMultiByte function if an explicit default character is not given.

LeadByte

Specifies a fixed-length array of lead-byte ranges, where the number of lead-byte ranges is variable. If there are no lead bytes in this code page, then every element of the array is NULL. If there are lead bytes in this code page, a starting value and ending value is given for each range. Ranges are inclusive. The maximum number of lead-byte ranges for any code page is 5. The array uses two bytes to describe each range, with a double-byte null terminator after the last range.

Remarks

Lead bytes are unique to double-byte character sets (DBCS). A lead byte is the first byte of a 2-byte character in a DBCS. Lead bytes occupy a specific range of byte values.

See Also

GetCPInfo, WideCharToMultiByte


CPLINFO

The CPLINFO structure contains resource information and an application-defined value for a dialog box supported by a Control Panel application. The CPlApplet function of the Control Panel application returns this information to the Control Panel in response to a CPL_INQUIRE message.

typedef struct tagCPLINFO { // cpli

    int  idIcon;

    int  idName;

    int  idInfo;

    LONG lData;

} CPLINFO;

Members

idIcon

Specifies the resource identifier of the icon that represents the dialog box.

idName

Specifies the resource identifier of the string containing the short name for the dialog box. This name is intended to be displayed below the icon.

idInfo

Specifies the resource identifier of the string containing the description for the dialog box. The description is the descriptive string that is intended to be displayed when the application icon is selected.

lData

Specifies data defined by the application. When the Control Panel sends the CPL_DBLCLK and CPL_STOP messages, it passes this value back to your application.

Remarks

If the icon or display strings of the dialog box can change based on the state of the computer, you can specify the CPL_DYNAMIC_RES value for the idIcon, idName, or idInfo members rather than specifying a valid resource identifier. This causes the Control Panel to send the CPL_NEWINQUIRE message each time it needs the icon and display strings. By processing CPL_NEWINQUIRE, you can specify information based on the current state of the computer. Using this technique is significantly slower, however, because the Control Panel needs to load your application each time it sends the CPL_NEWINQUIRE message.

See Also

CPL_DBLCLK, CPL_INQUIRE, CPL_NEWINQUIRE, CPL_STOP, CPlApplet


CREATE_PROCESS_DEBUG_INFO

The CREATE_PROCESS_DEBUG_INFO structure contains process creation information that can be used by a debugger.

typedef struct _CREATE_PROCESS_DEBUG_INFO { // cpdi

    HANDLE hFile;

    HANDLE hProcess;

    HANDLE hThread;

    LPVOID lpBaseOfImage;

    DWORD dwDebugInfoFileOffset;

    DWORD nDebugInfoSize;

    LPVOID lpThreadLocalBase;

    LPTHREAD_START_ROUTINE lpStartAddress;

    LPVOID lpImageName;

    WORD fUnicode;

} CREATE_PROCESS_DEBUG_INFO;

Members

hFile

Identifies an open handle of the process’s image file. If this member is NULL, the handle is not valid. Otherwise, the debugger can use the member to read from and write to the image file.

hProcess

Identifies an open handle of the process. If this member is NULL, the handle is not valid. Otherwise, the debugger can use the member to read from and write to the process’s memory.

hThread

Identifies an open handle of the initial thread of the process identified by the hProcess member. If hThread is NULL, the handle is not valid. Otherwise, the debugger has THREAD_GET_CONTEXT, THREAD_SET_CONTEXT, and THREAD_SUSPEND_RESUME access to the thread, allowing the debugger to read from and write to the registers of the thread and to control execution of the thread.

lpBaseOfImage

Points to the base address of the executable image that the process is running.

dwDebugInfoFileOffset

Specifies the offset to the debugging information in the file identified by the hFile member. The kernel expects the debugging information to be in Microsoft® CodeView® version 4.0 format. This format is currently a derivative of COFF (Common Object File Format).

nDebugInfoSize

Specifies the size, in bytes, of the debugging information in the file. If this value is zero, there is no debugging information.

lpThreadLocalBase

Points to a block of data. At offset 0x2C into this block is another pointer, called ThreadLocalStoragePointer, that points to an array of per-module thread local storage blocks. This gives a debugger access to per-thread data in the threads of the process being debugged using the same algorithms that a compiler would use.

lpStartAddress

Points to the starting address of the thread. This value may only be an approximation of the thread’s starting address, because any application with appropriate access to the thread can change the thread’s context by using the SetThreadContext function.

lpImageName

Points to the filename associated with the hFile parameter. This parameter may be NULL, or it may contain the address of a string pointer in the address space of the process being debugged. That address may, in turn, either be NULL or point to the actual filename. If fUnicode is a nonzero value, the name string is Unicode; otherwise, it is ANSI.

This member is strictly optional. Debuggers must be prepared to handle the case where lpImageName is NULL or *lpImageName (in the address space of the process being debugged) is NULL. Specifically, Windows does not provide an image name for a create process event, and will not likely pass an image name for the first DLL event. Windows also does not provide this information in the case of debug events that originate from a call to the DebugActiveProcess function.

fUnicode

Indicates whether a file name specified by the lpImageName member is Unicode or ANSI. A nonzero value indicates Unicode; zero indicates ANSI.

See Also

CREATE_THREAD_DEBUG_INFO, DebugActiveProcess, DEBUG_EVENT, LOAD_DLL_DEBUG_INFO, SetThreadContext


CREATE_THREAD_DEBUG_INFO

The CREATE_THREAD_DEBUG_INFO structure contains thread-creation information that can be used by a debugger.

typedef struct _CREATE_THREAD_DEBUG_INFO { // ctdi

    HANDLE hThread;

    LPVOID lpThreadLocalBase;

    LPTHREAD_START_ROUTINE lpStartAddress;

} CREATE_THREAD_DEBUG_INFO;

Members

hThread

Identifies a handle of the thread whose creation caused the debugging event. If this member is NULL, the handle is not valid. Otherwise, the debugger has THREAD_GET_CONTEXT, THREAD_SET_CONTEXT, and THREAD_SUSPEND_RESUME access to the thread, allowing the debugger to read from and write to the registers of the thread and control execution of the thread.

lpThreadLocalBase

Points to a block of data. At offset 0x2C into this block is another pointer, called ThreadLocalStoragePointer, that points to an array of per-module thread local storage blocks. This gives a debugger access to per-thread data in the threads of the process being debugged using the same algorithms that a compiler would use.

lpStartAddress

Points to the starting address of the thread. This value may only be an approximation of the thread’s starting address, because any application with appropriate access to the thread can change the thread’s context by using the SetThreadContext function.

See Also

CREATE_PROCESS_DEBUG_INFO, DEBUG_EVENT, LOAD_DLL_DEBUG_INFO, SetThreadContext


CREATESTRUCT

The CREATESTRUCT structure defines the initialization parameters passed to the window procedure of an application.

typedef struct tagCREATESTRUCT { // cs

    LPVOID    lpCreateParams;

    HINSTANCE hInstance;

    HMENU     hMenu;

    HWND      hwndParent;

    int       cy;

    int       cx;

    int       y;

    int       x;

    LONG      style;

    LPCTSTR   lpszName;

    LPCTSTR   lpszClass;

    DWORD     dwExStyle;

} CREATESTRUCT;

Members

lpCreateParams

Points to data to be used for creating the window.

Windows NT: This member is the address of a SHORT (16_bit) value that specifies the size, in bytes, of the window creation data. The value is immediately followed by the creation data. For more information, see the following Remarks section.

hInstance

Identifies the module that owns the new window.

hMenu

Identifies the menu to be used by the new window.

hwndParent

Identifies the parent window, if the window is a child window. If the window is owned, this member identifies the owner window. If the window is not a child or owned window, this member is NULL.

cy

Specifies the height of the new window, in pixels.

cx

Specifies the width of the new window, in pixels.

y

Specifies the y-coordinate of the upper left corner of the new window. If the new window is a child window, coordinates are relative to the parent window. Otherwise, the coordinates are relative to the screen origin.

x

Specifies the x-coordinate of the upper left corner of the new window. If the new window is a child window, coordinates are relative to the parent window. Otherwise, the coordinates are relative to the screen origin.

style

Specifies the style for the new window.

lpszName

Points to a null-terminated string that specifies the name of the new window.

lpszClass

Points to a null-terminated string that specifies the class name of the new window.

dwExStyle

Specifies the extended style for the new window.

Remarks

Windows NT: Referring to the lpCreateParams member of the CREATESTRUCT structure, because the pointer may not be DWORD aligned, an application should access the data using a pointer that has been declared using the UNALIGNED type, as shown in the following example:

typedef struct tagMyData {

    . . .;	// define creation data here

} MYDATA;

typedef struct tagMyDlgData {

    SHORT    cbExtra;

    MYDATA  myData;

} MYDLGDATA, UNALIGNED *PMYDLGDATA;

PMYDLGDATA pMyDlgdata =

    (PMYDLGDATA) (((LPCREATESTRUCT) lParam)->lpcreateParams);

See Also

CreateWindow, CreateWindowEx


CSADDR_INFO

The CSADDR_INFO structure contains Windows Sockets address information for a network service or name space provider. The GetAddressByName function obtains Windows Sockets address information using CSADDR_INFO structures.

typedef struct _CSADDR_INFO {

    SOCKET_ADDRESS  LocalAddr;

    SOCKET_ADDRESS  RemoteAddr;

    INT             iSocketType;

    INT             iProtocol;

} CSADDR_INFO;

Members

LocalAddr

Specifies a Windows Sockets local address.

In a client application, pass this address to the bind function to obtain access to a network service.

In a network service, pass this address to the bind function so that the service is bound to the appropriate local address.

RemoteAddr

Specifies a Windows Sockets remote address. There are several uses for this remote address:

•	You can use this remote address to connect to the service via the connect function. This is useful if an application performs send/receive operations that involve connection-oriented protocols.

•	You can use this remote address with the sendto function when you are communicating over a connectionless (datagram) protocol. If you are using a connectionless protocol, such as UDP, sendto is typically the way you pass data to the remote system.

iSocketType

Specifies the type of the Windows socket. The following socket types are defined in WINSOCK.H:

Value	Socket Type
SOCK_STREAM	Stream.This is a protocol that sends data as a stream of bytes, with no message boundaries.
SOCK_DGRAM	Datagram. This is a connectionless protocol. There is no virtual circuit setup. There are typically no reliability guarantees. Services use recvfrom to obtain datagrams. The listen and accept functions do not work with datagrams.
SOCK_RDM	Reliably-Delivered Message. This is a protocol that preserves message boundaries in data.
SOCK_SEQPACKET	Sequenced packet stream. This is a protocol that is essentially the same as SOCK_RDM.
iProtocol

Specifies a value to pass as the protocol parameter to the socket function to open a socket for this service.

See Also

bind, connect, GetAddressByName, recv, send, sendto


CURRENCYFMT

The CURRENCYFMT structure contains information that defines the format of a currency string. The GetCurrencyFormat function uses this information to customize a currency string for a specified locale.

typedef struct _currencyfmt {

    UINT      NumDigits;

    UINT      LeadingZero;

    UINT      Grouping;

    LPTSTR    lpDecimalSep;

    LPTSTR    lpThousandSep;

    UINT      NegativeOrder;

    UINT      PositiveOrder;

    LPTSTR    lpCurrencySymbol;
} CURRENCYFMT;

Members

NumDigits

Specifies the number of fractional digits. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_IDIGITS.

LeadingZero

Specifies whether to use leading zeroes in decimal fields. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_ILZERO.

Grouping

Specifies the size of each group of digits to the left of the decimal. Values in the range 0 − 9 are valid.

lpDecimalSep

Points to a null-terminated decimal separator string.

lpThousandSep

Points to a null-terminated thousand separator string.

NegativeOrder

Specifies the negative currency mode. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_INEGCURR.

PositiveOrder

Specifies the positive currency mode. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_ICURRENCY.

lpCurrencySymbol

Points to a null-terminated currency symbol string.

Remarks

For more information about the LCTYPE constants, see LCTYPE Constants.

See Also

GetCurrencyFormat


CURSORDIR

The CURSORDIR structure contains the dimensions of an individual cursor image in a resource group.

struct CURSORDIR {

    WORD Width;

    WORD Height;

} CURSORDIR;

Members

Width

Specifies the width of the cursor, in pixels. Acceptable values are 16, 32, and 64.

Height

Specifies the height of the cursor, in pixels. Acceptable values are 16, 32, and 64.

Remarks

The CURSORDIR structure is passed in the RESDIR structure if the RESDIR structure describes a cursor.

See Also

RESDIR


CURSORSHAPE

The CURSORSHAPE structure contains information about a cursor.

typedef struct tagCURSORSHAPE {    // cs

    int     xHotSpot;

    int     yHotSpot;

    int     cx;

    int     cy;

    int     cbWidth;

    BYTE    Planes;

    BYTE    BitsPixel;

} CURSORSHAPE, FAR *LPCURSORSHAPE;

Members

xHotSpot

Specifies the horizontal position of the hot spot, relative to the upper left corner of the cursor bitmap.

yHotSpot

Specifies the vertical position of the hot spot, relative to the upper left corner of the cursor bitmap.

cx

Specifies the width, in pixels, of the cursor.

cy

Specifies the height, in pixels, of the cursor.

cbWidth

Width, in bytes, of the cursor bitmap.

Planes

Specifies the number of color planes.

BitsPixel

Specifies the number of bits used to indicate the color of a single pixel in the cursor.

Remarks

When an application passes a cursor handle to the LockResource function, the function returns a pointer to a buffer containing information about the cursor. An application can use the CURSORSHAPE structure to access the information.

See Also

LockResource


CWPRETSTRUCT

The CWPRETSTRUCT structure defines the message parameters passed to a WH_CALLWNDPROCRET hook procedure.

typedef struct tagCWPRETSTRUCT { // cwprs

    LRESULT lResult;

    LPARAM  lParam;

    WPARAM  wParam;

    DWORD   message;

    HWND    hwnd;

} CWPRETSTRUCT;

Members

lResult

Specifies the return value of the window procedure that processed the message specified by the message value.

lParam

Specifies additional information about the message. The exact meaning depends on the message value.

wParam

Specifies additional information about the message. The exact meaning depends on the message value.

message

Specifies the message.

hwnd

Identifies the window that processed the message specified by the message value.

See Also

CallWndRetProc, SetWindowsHook, SetWindowsHookEx


CWPSTRUCT

The CWPSTRUCT structure defines the message parameters passed to a WH_CALLWNDPROC hook procedure.

typedef struct tagCWPSTRUCT { // cwps

    LPARAM  lParam;

    WPARAM  wParam;

    UINT    message;

    HWND    hwnd;

} CWPSTRUCT;

Members

lParam

Specifies additional information about the message. The exact meaning depends on the message value.

wParam

Specifies additional information about the message. The exact meaning depends on the message value.

message

Specifies the message.

hwnd

Identifies the window to receive the message.

See Also

CallWndProc, SetWindowsHook, SetWindowsHookEx


DATATYPES_INFO_1

The DATATYPES_INFO_1 structure contains information about the data type used to record a print job.

typedef struct _DATATYPES_INFO_1 {

    LPTSTR pName;

} DATATYPES_INFO_1;

Members

pName

Points to a null-terminated string that identifies the data type used to record a print job.

See Also

EnumPrintProcessorDataTypes


DCB

The DCB structure defines the control setting for a serial communications device.

typedef struct _DCB { // dcb

    DWORD DCBlength;           // sizeof(DCB)

    DWORD BaudRate;            // current baud rate

    DWORD fBinary: 1;          // binary mode, no EOF check

    DWORD fParity: 1;          // enable parity checking

    DWORD fOutxCtsFlow:1;      // CTS output flow control

    DWORD fOutxDsrFlow:1;      // DSR output flow control

    DWORD fDtrControl:2;       // DTR flow control type

    DWORD fDsrSensitivity:1;   // DSR sensitivity

    DWORD fTXContinueOnXoff:1; // XOFF continues Tx

    DWORD fOutX: 1;            // XON/XOFF out flow control

    DWORD fInX: 1;             // XON/XOFF in flow control

    DWORD fErrorChar: 1;       // enable error replacement

    DWORD fNull: 1;            // enable null stripping

    DWORD fRtsControl:2;       // RTS flow control

    DWORD fAbortOnError:1;     // abort reads/writes on error

    DWORD fDummy2:17;          // reserved

    WORD wReserved;            // not currently used

    WORD XonLim;               // transmit XON threshold

    WORD XoffLim;              // transmit XOFF threshold

    BYTE ByteSize;             // number of bits/byte, 4-8

    BYTE Parity;               // 0-4=no,odd,even,mark,space

    BYTE StopBits;             // 0,1,2 = 1, 1.5, 2

    char XonChar;              // Tx and Rx XON character

    char XoffChar;             // Tx and Rx XOFF character

    char ErrorChar;            // error replacement character

    char EofChar;              // end of input character

    char EvtChar;              // received event character

    WORD wReserved1;           // reserved; do not use

} DCB;

Members

DCBlength

Specifies the length, in bytes, of the DCB structure.

BaudRate

Specifies the baud rate at which the communications device operates. This member can be an actual baud rate value, or one of the following baud rate indexes:

CBR_110	CBR_19200
CBR_300	CBR_38400
CBR_600	CBR_56000
CBR_1200	CBR_57600
CBR_2400	CBR_115200
CBR_4800	CBR_128000
CBR_9600	CBR_256000
CBR_14400
fBinary

Specifies whether binary mode is enabled. The Win32 API does not support nonbinary mode transfers, so this member should be TRUE. Trying to use FALSE will not work.

Under Windows 3.1, if this member is FALSE, nonbinary mode is enabled, and the character specified by the EofChar member is recognized on input and remembered as the end of data.

fParity

Specifies whether parity checking is enabled. If this member is TRUE, parity checking is performed and errors are reported.

fOutxCtsFlow

Specifies whether the CTS (clear-to-send) signal is monitored for output flow control. If this member is TRUE and CTS is turned off, output is suspended until CTS is sent again.

fOutxDsrFlow

Specifies whether the DSR (data-set-ready) signal is monitored for output flow control. If this member is TRUE and DSR is turned off, output is suspended until DSR is sent again.

fDtrControl

Specifies the DTR (data-terminal-ready) flow control. This member can be one of the following values:

Value	Meaning
DTR_CONTROL_DISABLE	Disables the DTR line when the device is opened and leaves it disabled.
DTR_CONTROL_ENABLE	Enables the DTR line when the device is opened and leaves it on.
DTR_CONTROL_HANDSHAKE	Enables DTR handshaking. If handshaking is enabled, it is an error for the application to adjust the line by using the EscapeCommFunction function.
fDsrSensitivity

Specifies whether the communications driver is sensitive to the state of the DSR signal. If this member is TRUE, the driver ignores any bytes received, unless the DSR modem input line is high.

fTXContinueOnXoff

Specifies whether transmission stops when the input buffer is full and the driver has transmitted the XoffChar character. If this member is TRUE, transmission continues after the input buffer has come within XoffLim bytes of being full and the driver has transmitted the XoffChar character to stop receiving bytes. If this member is FALSE, transmission does not continue until the input buffer is within XonLim bytes of being empty and the driver has transmitted the XonChar character to resume reception.

fOutX

Specifies whether XON/XOFF flow control is used during transmission. If this member is TRUE, transmission stops when the XoffChar character is received and starts again when the XonChar character is received.

fInX

Specifies whether XON/XOFF flow control is used during reception. If this member is TRUE, the XoffChar character is sent when the input buffer comes within XoffLim bytes of being full, and the XonChar character is sent when the input buffer comes within XonLim bytes of being empty.

fErrorChar

Specifies whether bytes received with parity errors are replaced with the character specified by the ErrorChar member. If this member is TRUE and the fParity member is TRUE, replacement occurs.

fNull

Specifies whether null bytes are discarded. If this member is TRUE, null bytes are discarded when received.

fRtsControl

Specifies the RTS (request-to-send) flow control. If this value is zero, the default is RTS_CONTROL_HANDSHAKE. This member can be one of the following values:

Value	Meaning
RTS_CONTROL_DISABLE	Disables the RTS line when the device is opened and leaves it disabled.
RTS_CONTROL_ENABLE	Enables the RTS line when the device is opened and leaves it on.
RTS_CONTROL_HANDSHAKE	Enables RTS handshaking. The driver raises the RTS line when the “type-ahead” (input) buffer is less than one-half full and lowers the RTS line when the buffer is more than three-quarters full. If handshaking is enabled, it is an error for the application to adjust the line by using the EscapeCommFunction function.
RTS_CONTROL_TOGGLE	Specifies that the RTS line will be high if bytes are available for transmission. After all buffered bytes have been sent, the RTS line will be low.
fAbortOnError

Specifies whether read and write operations are terminated if an error occurs. If this member is TRUE, the driver terminates all read and write operations with an error status if an error occurs. The driver will not accept any further communications operations until the application has acknowledged the error by calling the ClearCommError function.

fDummy2

Reserved; do not use.

wReserved

Not used; must be set to zero.

XonLim

Specifies the minimum number of bytes allowed in the input buffer before the XON character is sent.

XoffLim

Specifies the maximum number of bytes allowed in the input buffer before the XOFF character is sent. The maximum number of bytes allowed is calculated by subtracting this value from the size, in bytes, of the input buffer.

ByteSize

Specifies the number of bits in the bytes transmitted and received.

Parity

Specifies the parity scheme to be used. This member can be one of the following values:

Value	Meaning
EVENPARITY	Even
MARKPARITY	Mark
NOPARITY	No parity
ODDPARITY	Odd
StopBits

Specifies the number of stop bits to be used. This member can be one of the following values:

Value	Meaning
ONESTOPBIT	1 stop bit
ONE5STOPBITS	1.5 stop bits
TWOSTOPBITS	2 stop bits
XonChar

Specifies the value of the XON character for both transmission and reception.

XoffChar

Specifies the value of the XOFF character for both transmission and reception.

ErrorChar

Specifies the value of the character used to replace bytes received with a parity error.

EofChar

Specifies the value of the character used to signal the end of data.

EvtChar

Specifies the value of the character used to signal an event.

wReserved1

Reserved; do not use.

Remarks

When a DCB structure is used to configure the 8250, the following restrictions apply to the values specified for the ByteSize and StopBits members:

•	The number of data bits must be 5 to 8 bits.

•	The use of 5 data bits with 2 stop bits is an invalid combination, as is 6, 7, or 8 data bits with 1.5 stop bits.

See Also

BuildCommDCB, ClearCommError, EscapeCommFunction, GetCommState, SetCommState


DDEACK

The DDEACK structure contains status flags that a DDE application passes to its partner as part of the WM_DDE_ACK message. The flags provide details about the application’s response to the messages WM_DDE_DATA, WM_DDE_POKE, WM_DDE_EXECUTE, WM_DDE_ADVISE, WM_DDE_UNADVISE, and WM_DDE_REQUEST.

typedef struct { // ddeack

    unsigned short bAppReturnCode:8,

    reserved:6,

    fBusy:1,

    fAck:1;

} DDEACK;

Members

bAppReturnCode

Specifies an application-defined return code.

fBusy

Indicates whether the application was busy and unable to respond to the partner’s message at the time the message was received. A nonzero value indicates the partner was busy and unable to respond. The fBusy member is defined only when the fAck member is zero.

fAck

Indicates whether the application accepted the message from its partner. A nonzero value indicates the partner accepted the message.

See Also

WM_DDE_ACK, WM_DDE_ADVISE, WM_DDE_DATA, WM_DDE_EXECUTE, WM_DDE_REQUEST, WM_DDE_POKE, WM_DDE_UNADVISE


DDEADVISE

The DDEADVISE structure contains flags that specify how a DDE server application should send data to a client application during an advise loop. A client passes the handle of a DDEADVISE structure to a server as part of a WM_DDE_ADVISE message. This structure supersedes the DDELN structure.

typedef struct { // ddeadv

    unsigned short reserved:14,

        fDeferUpd:1,

        fAckReq:1;

    short cfFormat;

} DDEADVISE;

Members

fDeferUpd

Indicates whether the server should defer sending updated data to the client. If this value is nonzero, the server should send a WM_DDE_DATA message with a NULL data handle whenever the data item changes. In response, the client can post a WM_DDE_REQUEST message to the server to get a handle of the updated data.

fAckReq

Indicates whether the server should set the fAckReq flag in the WM_DDE_DATA messages it posts to the client. If this value is nonzero, the server should set the fAckReq bit.

cfFormat

Specifies the client application’s preferred data format. The format must be a standard or registered clipboard format. The following standard clipboard formats can be used:

CF_BITMAP
CF_DIB
CF_DIF
CF_ENHMETAFILE
CF_METAFILEPICT
CF_OEMTEXT
CF_PALETTE
CF_PENDATA
CF_RIFF
CF_SYLK
CF_TEXT
CF_TIFF
CF_WAVE
CF_UNICODETEXT

See Also

WM_DDE_ADVISE, WM_DDE_DATA, WM_DDE_UNADVISE


DDEDATA

The DDEDATA structure contains the data, and information about the data, sent as part of a WM_DDE_DATA message. This structure supersedes the DDEUP structure.

typedef struct { // ddedat

    unsigned short unused:12,

        fResponse:1,

        fRelease:1,

        reserved:1,

        fAckReq:1;

    short cfFormat;

    BYTE  Value[1];

} DDEDATA;

Members

fResponse

Indicates whether the data was sent in response to a WM_DDE_REQUEST message or a WM_DDE_ADVISE message. If this value is nonzero, the data was sent in response to a WM_DDE_REQUEST message.

fRelease

Indicates whether the application receiving the WM_DDE_POKE message should free the data. If this value is nonzero, the application should free the data.

fAckReq

Indicates whether the application receiving the WM_DDE_DATA message should acknowledge receipt of the data by sending a WM_DDE_ACK message. If this value is nonzero, the application should send the acknowledgment.

cfFormat

Specifies the format of the data. The format should be a standard or registered clipboard format. The following standard clipboard formats can be used:

CF_BITMAP
CF_DIB
CF_DIF
CF_ENHMETAFILE
CF_METAFILEPICT
CF_OEMTEXT
CF_PALETTE
CF_PENDATA
CF_RIFF
CF_SYLK
CF_TEXT
CF_TIFF
CF_WAVE
CF_UNICODETEXT

Value

Contains the data. The length and type of data depend on the cfFormat member.

See Also

DDEUP, WM_DDE_ACK, WM_DDE_ADVISE, WM_DDE_DATA, WM_DDE_POKE, WM_DDE_REQUEST


DDELN

The DDELN structure is obsolete. Win32-based applications should use the DDEADVISE structure.

typedef struct { // ddeln

    unsigned short unused:13,

        fRelease:1,

        fDeferUpd:1,

        fAckReq:1;

    short cfFormat;

} DDELN;

See Also

DDEADVISE, WM_DDE_ADVISE, WM_DDE_UNADVISE


DDEML_MSG_HOOK_DATA

The DDEML_MSG_HOOK_DATA structure contains information about a DDE message, and provides read access to the data referenced by the message. This structure is intended to be used by a DDE Management Library (DDEML) monitoring application.

typedef struct tagDDEML_MSG_HOOK_DATA { // dmhd

    UINT  uiLo;

    UINT  uiHi;

    DWORD cbData;

    DWORD Data[8];

} DDEML_MSG_HOOK_DATA;

Members

uiLo

Specifies the unpacked low-order word of the lParam parameter associated with the DDE message.

uiHi

Specifies the unpacked high-order word of the lParam parameter associated with the DDE message.

cbData

Specifies the amount, in bytes, of data being passed with the message. This value can be greater than 32.

Data

Contains the first 32 bytes of data being passed with the message
(8 * sizeof(DWORD)).

See Also

MONCBSTRUCT, MONCONVSTRUCT, MONERRSTRUCT, MONHSZSTRUCT, MONLINKSTRUCT, MONMSGSTRUCT


DDEPOKE

The DDEPOKE structure contains the data, and information about the data, sent as part of a WM_DDE_POKE message. This structure supersedes the DDEUP structure.

typedef struct { // ddepok

    unsigned short unused:13,

        fRelease:1,

        fReserved:2;

    short cfFormat;

    BYTE  Value[1];

} DDEPOKE;

Members

fRelease

Indicates whether the application receiving the WM_DDE_POKE message should free the data. If this value is nonzero, the application should free the data.

fReserved

Reserved; do not use.

cfFormat

Specifies the format of the data. The format should be a standard or registered clipboard format. The following standard clipboard formats can be used:

CF_BITMAP
CF_DIB
CF_DIF
CF_ENHMETAFILE
CF_METAFILEPICT
CF_OEMTEXT
CF_PALETTE
CF_PENDATA
CF_RIFF
CF_SYLK
CF_TEXT
CF_TIFF
CF_WAVE
CF_UNICODETEXT

Value

Contains the data. The length and type of data depend on the value of the cfFormat member.

See Also

DDEUP, WM_DDE_POKE


DDEUP

The DDEUP structure is obsolete. Win32-based applications should use the DDEDATA and DDEPOKE structures.

typedef struct { // ddeup

    unsigned short unused:12,

        fAck:1,

        fRelease:1,

        fReserved:1,

        fAckReq:1;

    short cfFormat;

    BYTE rgb[1];

} DDEUP;

See Also

WM_DDE_DATA, WM_DDE_POKE


DEBUG_EVENT

The DEBUG_EVENT structure describes a debugging event.

typedef struct _DEBUG_EVENT { // de

    DWORD dwDebugEventCode;

    DWORD dwProcessId;

    DWORD dwThreadId;

    union {

        EXCEPTION_DEBUG_INFO Exception;

        CREATE_THREAD_DEBUG_INFO CreateThread;

        CREATE_PROCESS_DEBUG_INFO CreateProcessInfo;

        EXIT_THREAD_DEBUG_INFO ExitThread;

        EXIT_PROCESS_DEBUG_INFO ExitProcess;

        LOAD_DLL_DEBUG_INFO LoadDll;

        UNLOAD_DLL_DEBUG_INFO UnloadDll;

        OUTPUT_DEBUG_STRING_INFO DebugString;

        RIP_INFO RipInfo;

    } u;

} DEBUG_EVENT;

Members

dwDebugEventCode

Specifies a debugging event code that identifies the type of debugging event. This parameter can be one of the following values:

Value	Meaning
EXCEPTION_DEBUG_EVENT
	Reports an exception debugging event. The value of u.Exception specifies an EXCEPTION_DEBUG_INFO structure.
CREATE_THREAD_DEBUG_EVENT
	Reports a create-thread debugging event. The value of u.CreateThread specifies a CREATE_THREAD_DEBUG_INFO structure.
CREATE_PROCESS_DEBUG_EVENT
	Reports a create-process debugging event. The value of u.CreateProcessInfo specifies a CREATE_PROCESS_DEBUG_INFO structure.
EXIT_THREAD_DEBUG_EVENT
	Reports an exit-thread debugging event. The value of u.ExitThread specifies an EXIT_THREAD_DEBUG_INFO structure.
EXIT_PROCESS_DEBUG_EVENT
	Reports an exit-process debugging event. The value of u.ExitProcess specifies an EXIT_PROCESS_DEBUG_INFO structure.
LOAD_DLL_DEBUG_EVENT
	Reports a load-dynamic-link-library (DLL) debugging event. The value of u.LoadDll specifies a LOAD_DLL_DEBUG_INFO structure.
UNLOAD_DLL_DEBUG_EVENT
	Reports an unload-DLL debugging event. The value of u.UnloadDll specifies an UNLOAD_DLL_DEBUG_INFO structure.
OUTPUT_DEBUG_STRING_EVENT
	Reports an output-debugging-string debugging event. The value of u.DebugString specifies an OUTPUT_DEBUG_STRING_INFO structure.
RIP_EVENT
	Reports a RIP-debugging event (system debugging error). The value of u.RipInfo specifies a RIP_INFO structure.
dwProcessId

Specifies the identifier of the process in which the debugging event occurred. A debugger uses this value to locate the debugger’s per-process structure. These values are not necessarily small integers that can be used as table indices.

dwThreadId

Specifies the identifier of the thread in which the debugging event occurred. A debugger uses this value to locate the debugger’s per-thread structure. These values are not necessarily small integers that can be used as table indices.

u

Specifies additional information relating to the debugging event. This union takes on the type and value appropriate to the type of debugging event, as described in the dwDebugEventCode member.

Remarks

If the WaitForDebugEvent function succeeds, it fills in the members of a DEBUG_EVENT structure.

See Also

CREATE_PROCESS_DEBUG_INFO, CREATE_THREAD_DEBUG_INFO, EXIT_PROCESS_DEBUG_INFO, EXIT_THREAD_DEBUG_INFO, EXCEPTION_DEBUG_INFO, LOAD_DLL_DEBUG_INFO, OUTPUT_DEBUG_STRING_INFO, UNLOAD_DLL_DEBUG_INFO, WaitForDebugEvent


DEBUGHOOKINFO

The DEBUGHOOKINFO structure contains debugging information.

typedef struct tagDEBUGHOOKINFO { // dh

    DWORD  idThread;

    DWORD  idThreadInstaller;

    LPARAM lParam;

    WPARAM wParam;

    int    code;

} DEBUGHOOKINFO;

Members

idThread

Identifies the thread containing the filter function.

idThreadInstaller

Identifies the thread that installed the debugging filter function.

lParam

Specifies the value to be passed to the hook in the lParam parameter of the DebugProc callback function.

wParam

Specifies the value to be passed to the hook in the wParam parameter of the DebugProc callback function.

code

Specifies the value to be passed to the hook in the nCode parameter of the DebugProc callback function.

See Also

DebugProc, SetWindowsHook, SetWindowsHookEx


DELETEITEMSTRUCT

The DELETEITEMSTRUCT structure describes a deleted list box or combo box item. The lParam parameter of a WM_DELETEITEM message contains a pointer to this structure. When an item is removed from a list box or combo box or when a list box or combo box is destroyed, Windows sends the WM_DELETEITEM message to the owner for each deleted item.

Windows NT: Windows sends a WM_DELETEITEM message only for items deleted from an owner-drawn list box (with the LBS_OWNERDRAWFIXED or LBS_OWNERDRAWVARIABLE style) or owner-drawn combo box (with the CBS_OWNERDRAWFIXED or CBS_OWNERDRAWVARIABLE style).

Windows 95: Windows sends the WM_DELETEITEM message for any deleted list box or combo box item with nonzero item data.

typedef struct tagDELETEITEMSTRUCT { // ditms

    UINT CtlType;

    UINT CtlID;

    UINT itemID;

    HWND hwndItem;

    UINT itemData;

} DELETEITEMSTRUCT;

Members

CtlType

Specifies one of the following values to indicate whether the item was deleted from a list box or a combo box:

Value	Meaning
ODT_LISTBOX	A list box.
ODT_COMBOBOX	A combo box.
CtlID

Specifies the identifier of the list box or combo box.

itemID

Specifies index of the item in the list box or combo box being removed.

hwndItem

Identifies the control.

itemData

Specifies application-defined data for the item. This value is passed to the control in the lParam parameter of the message that adds the item to the list box or combo box.

See Also

WM_DELETEITEM


DEV_BROADCAST_HDR

The DEV_BROADCAST_HDR structure contains information about the device affected by a WM_DEVICECHANGE message.

typedef struct _DEV_BROADCAST_HDR {
    ULONG dbch_size;

    ULONG dbch_devicetype;

    ULONG dbch_reserved;

} DEV_BROADCAST_HDR;
typedef DEV_BROADCAST_HDR *PDEV_BROADCAST_HDR;

Members

dbch_size

Size of this structure, in bytes.

dbch_devicetype

Type of device. Can be one of these values:

Value	Meaning
DBT_DEVTYP_OEM	OEM- or IHV-defined device type.
DBT_DEVTYP_VOLUME	Logical volume.
DBT_DEVTYP_PORT	Port device (serial or parallel).
dbch_reserved

Reserved; do not use.

See Also

WM_DEVICECHANGE


DEV_BROADCAST_OEM

The DEV_BROADCAST_OEM structure contains information about a OEM-defined device type.

typedef struct _DEV_BROADCAST_OEM {
    ULONG dbco_size;

    ULONG dbco_devicetype;

    ULONG dbco_reserved;

    ULONG dbco_identifier;

    ULONG dbco_suppfunc;

} DEV_BROADCAST_OEM;
typedef DEV_BROADCAST_OEM *PDEV_BROADCAST_OEM;

Members

dbco_size

Size of this structure, in bytes.

dbco_devicetype

DBT_DEVTYPE_OEM.

dbco_reserved

Reserved; do not use.

dbco_identifier

Globally unique identifier (GUID) for the device. Use the uuidgen utility to create this identifier.

dbco_suppfunc

OEM-specific function value. Possible values depend on the device.


DEV_BROADCAST_PORT

The DEV_BROADCAST_PORT structure contains information about a modem, serial, or parallel port.

typedef struct _DEV_BROADCAST_PORT {
    ULONG dbcp_size;

    ULONG dbcp_devicetype;

    ULONG dbcp_reserved;

    char dbcp_name[1];

} DEV_BROADCAST_PORT;
typedef DEV_BROADCAST_PORT *PDEV_BROADCAST_PORT;

Members

dbcp_size

Size of this structure, in bytes.

dbcp_devicetype

DBT_DEVTYP_VOLUME.

dbcp_reserved

Reserved; do not use.

dbcp_name

Null-terminated string specifying the friendly name of the port or the device connected to the port. Friendly names are intended to help the user quickly and accurately identify the device—for example, “COM1”, “Hayes 2400 Smartmodem”, and “LPT1” are considered friendly names.


_DEV_BROADCAST_USERDEFINED

The _DEV_BROADCAST_USERDEFINED structure contains the user-defined message and optional data associated with the DBT_USERDEFINED device message.

struct _DEV_BROADCAST_USERDEFINED {
    struct _DEV_BROADCAST_HDR dbud_dbh;
    char  dbud_szName[1];           // ASCIIZ name
//    BYTE  dbud_rgbUserDefined[];  // Optional user-defined contents
};

Members

dbud_dbh

Information about the device affected by a WM_DEVICECHANGE message as specified by the DEV_BROADCAST_HDR structure. Because the _DEV_BROADCAST_USERDEFINED structure is variable length, dbud_dbh.dbch_size must be the size in bytes of the entire structure, including the variable length part.

dbud_szName

A case-sensitive, null-terminated string that names the message. The name must consist of the vendor name, a backslash, followed by arbitrary user-defined null-terminated text. For example:

"WidgetWare\QueryScannerShutdown"

or

"WidgetWare\Video Q39S\AdapterReady"

dbud_rgbUserDefined

Optional user-defined information.

Because this structure contains variable length fields, use this structure tag as a template for creating a pointer to a user-defined structure. Note that the structure must not contain pointers. For example:

#define NAME_LENGTH 32

#define USER_LENGTH 50

typedef struct tagWIDGET_WARE_DEV_BROADCAST_USERDEFINED
{
    struct _DEV_BROADCAST_HDR DBHeader;
    char  szName[NAME_LENGTH]
    BYTE  UserDefined[USER_LENGTH];

} WIDGET_WARE_DEV_BROADCAST_USERDEFINED;

See Also

DBT_USERDEFINED, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DEV_BROADCAST_VOLUME

The DEV_BROADCAST_VOLUME structure contains information about a logical volume.

typedef struct _DEV_BROADCAST_VOLUME {
    ULONG dbcv_size;

    ULONG dbcv_devicetype;

    ULONG dbcv_reserved;

    ULONG dbcv_unitmask;

    USHORT dbcv_flags;

} DEV_BROADCAST_VOLUME;
typedef DEV_BROADCAST_VOLUME *PDEV_BROADCAST_VOLUME;

Members

dbcv_size

Size of this structure, in bytes.

dbcv_devicetype

DBT_DEVTYP_VOLUME.

dbcv_reserved

Reserved; do not use.

dbcv_unitmask

Logical unit mask identifying one or more logical units. Each bit in the mask corresponds to one logical drive. Bit 0 represents drive A, bit 1 drive B, and so on.

dbcv_flags

Flags indicating whether drive or media.

Value	Meaning
DBTF_MEDIA	Change affects media in drive. If not set, change affects physical device or drive.
DBTF_NET	Indicated logical volume is a network volume.
Remarks

Although the dbcv_unitmask member may specify more than one volume in any given message, this does not guarantee that only message is generated for a given event. Multiple system components may independently generate messages for logical volumes at the same time.


DEVMODE

The DEVMODE data structure contains information about the device initialization and environment of a printer.

typedef struct _devicemode {    // dvmd

    BCHAR  dmDeviceName[CCHDEVICENAME];

    WORD   dmSpecVersion;

    WORD   dmDriverVersion;

    WORD   dmSize;

    WORD   dmDriverExtra;

    DWORD  dmFields;

    short  dmOrientation;

    short  dmPaperSize;

    short  dmPaperLength;

    short  dmPaperWidth;

    short  dmScale;

    short  dmCopies;

    short  dmDefaultSource;

    short  dmPrintQuality;

    short  dmColor;

    short  dmDuplex;

    short  dmYResolution;

    short  dmTTOption;

    short  dmCollate;

    BCHAR  dmFormName[CCHFORMNAME];

    WORD  dmLogPixels;

    DWORD  dmBitsPerPel;

    DWORD  dmPelsWidth;

    DWORD  dmPelsHeight;

    DWORD  dmDisplayFlags;

    DWORD  dmDisplayFrequency;

#if(WINVER >= 0x0400)

    DWORD  dmICMMethod;         // Windows 95 only

    DWORD  dmICMIntent;         // Windows 95 only

    DWORD  dmMediaType;         // Windows 95 only

    DWORD  dmDitherType;        // Windows 95 only

    DWORD  dmReserved1;         // Windows 95 only

    DWORD  dmReserved2;         // Windows 95 only

#endif /* WINVER >= 0x0400 */

} DEVMODE;

Members

dmDeviceName

Specifies the the “friendly” name of the printer; for example, “PCL/HP LaserJet” in the case of PCL/HP LaserJet®. This string is unique among device drivers. Note that this name may be truncated to fit in the dmDeviceName array.

dmSpecVersion

Specifies the version number of the initialization data specification on which the structure is based.

dmDriverVersion

Specifies the printer driver version number assigned by the printer driver developer.

dmSize

Specifies the size, in bytes, of the DEVMODE structure, not including any private driver-specific data that might follow the structure’s public members. You can use this member to determine the number of bytes of public data regardless of the version of the DEVMODE structure being used.

dmDriverExtra

Contains the number of bytes of private driver-data that follow this structure. If a device driver does not use device-specific information, set this member to zero.

dmFields

A set of bit flags that specify whether certain members of the DEVMODE structure have been initialized. If a field is initialized, its corresponding bit flag is set, otherwise the bit flag is clear.  A printer driver supports only those DEVMODE structure members that are appropriate for the printer technology.

The following bit flags are defined, and are listed here with the corresponding structure members:

Value	Structure Member
DM_ORIENTATION	dmOrientation
DM_PAPERSIZE	dmPaperSize
DM_PAPERLENGTH	dmPaperLength
DM_PAPERWIDTH	dmPaperWidth
DM_SCALE	dmScale
DM_COPIES	dmCopies
DM_DEFAULTSOURCE	dmDefaultSource
DM_PRINTQUALITY	dmPrintQuality
DM_COLOR	dmColor
DM_DUPLEX	dmDuplex
DM_YRESOLUTION	dmYResolution
DM_TTOPTION	dmTTOption
DM_COLLATE	dmCollate
DM_FORMNAME	dmFormName
DM_LOGPIXELS	dmLogPixels
DM_BITSPERPEL	dmBitsPerPel
DM_PELSWIDTH	dmPelsWidth
DM_PELSHEIGHT	dmPelsHeight
DM_DISPLAYFLAGS	dmDisplayFlags
DM_DISPLAYFREQUENCY	dmDisplayFrequency
DM_ICMMETHOD	Windows 95 only: dmICMMethod
DM_ICMINTENT	Windows 95 only: dmICMIntent
DM_MEDIATYPE	Windows 95 only: dmMediaType
DM_DITHERTYPE	Windows 95 only: dmDitherType
dmOrientation

Selects the orientation of the paper. This member can be either DMORIENT_PORTRAIT (1) or DMORIENT_LANDSCAPE (2).

dmPaperSize

Selects the size of the paper to print on. This member can be set to zero if the length and width of the paper are both set by the dmPaperLength and dmPaperWidth members. Otherwise, the dmPaperSize member can be set to one of the following predefined values:

Value	Meaning
DMPAPER_LETTER	Letter, 8 1/2- by 11-inches
DMPAPER_LEGAL	Legal, 8 1/2- by 14-inches
DMPAPER_A4	A4 Sheet, 210- by 297-millimeters
DMPAPER_CSHEET	C Sheet, 17- by 22-inches
DMPAPER_DSHEET	D Sheet, 22- by 34-inches
DMPAPER_ESHEET	E Sheet, 34- by 44-inches
DMPAPER_LETTERSMALL	Letter Small, 8 1/2- by 11-inches
DMPAPER_TABLOID	Tabloid, 11- by 17-inches
DMPAPER_LEDGER	Ledger, 17- by 11-inches
DMPAPER_STATEMENT	Statement, 5 1/2- by 8 1/2-inches
DMPAPER_EXECUTIVE	Executive, 7 1/4- by 10 1/2-inches
DMPAPER_A3	A3 sheet, 297- by 420-millimeters
DMPAPER_A4SMALL	A4 small sheet, 210- by 297-millimeters
DMPAPER_A5	A5 sheet, 148- by 210-millimeters
DMPAPER_B4	B4 sheet, 250- by 354-millimeters
DMPAPER_B5	B5 sheet, 182- by 257-millimeter paper
DMPAPER_FOLIO	Folio, 8 1/2- by 13-inch paper
DMPAPER_QUARTO	Quarto, 215- by 275-millimeter paper
DMPAPER_10X14	10- by 14-inch sheet
DMPAPER_11X17	11- by 17-inch sheet
DMPAPER_NOTE	Note, 8 1/2- by 11-inches
DMPAPER_ENV_9	#9 Envelope, 3 7/8- by 8 7/8-inches
DMPAPER_ENV_10	#10 Envelope, 4 1/8- by 9 1/2-inches
DMPAPER_ENV_11	#11 Envelope, 4 1/2- by 10 3/8-inches
DMPAPER_ENV_12	#12 Envelope, 4 3/4- by 11-inches
DMPAPER_ENV_14	#14 Envelope, 5- by 11 1/2-inches
DMPAPER_ENV_DL	DL Envelope, 110- by 220-millimeters
DMPAPER_ENV_C5	C5 Envelope, 162- by 229-millimeters
DMPAPER_ENV_C3	C3 Envelope,  324- by 458-millimeters
DMPAPER_ENV_C4	C4 Envelope,  229- by 324-millimeters
DMPAPER_ENV_C6	C6 Envelope,  114- by 162-millimeters
DMPAPER_ENV_C65	C65 Envelope, 114- by 229-millimeters
DMPAPER_ENV_B4	B4 Envelope,  250- by 353-millimeters
DMPAPER_ENV_B5	B5 Envelope,  176- by 250-millimeters
DMPAPER_ENV_B6	B6 Envelope,  176- by 125-millimeters
DMPAPER_ENV_ITALY	Italy Envelope, 110- by 230-millimeters
DMPAPER_ENV_MONARCH	Monarch Envelope, 3 7/8- by 7 1/2-inches
DMPAPER_ENV_PERSONAL	6 3/4 Envelope, 3 5/8- by 6 1/2-inches
DMPAPER_FANFOLD_US	US Std Fanfold, 14 7/8- by 11-inches
DMPAPER_FANFOLD_STD_GERMAN	German Std Fanfold, 8 1/2- by 12-inches
DMPAPER_FANFOLD_LGL_GERMAN	German Legal Fanfold, 8 1/2- by 13-inches
dmPaperLength

Overrides the length of the paper specified by the dmPaperSize member, either for custom paper sizes or for devices such as dot-matrix printers, which can print on a page of arbitrary length. These values, along with all other values in this structure that specify a physical length, are in tenths of a millimeter.

dmPaperWidth

Overrides the width of the paper specified by the dmPaperSize member.

dmScale

Specifies the factor by which the printed output is to be scaled. The apparent page size is scaled from the physical page size by a factor of dmScale/100. For example, a letter-sized page with a dmScale value of 50 would contain as much data as a page of 17- by 22-inches because the output text and graphics would be half their original height and width.

dmCopies

Selects the number of copies printed if the device supports multiple-page copies.

dmDefaultSource

Reserved; must be zero.

dmPrintQuality

Specifies the printer resolution. There are four predefined device-independent values:

DMRES_HIGH
DMRES_MEDIUM
DMRES_LOW
DMRES_DRAFT

If a positive value is given, it specifies the number of dots per inch (DPI) and is therefore device dependent.

dmColor

Switches between color and monochrome on color printers. Following are the possible values:

DMCOLOR_COLOR
DMCOLOR_MONOCHROME

dmDuplex

Selects duplex or double-sided printing for printers capable of duplex printing. Following are the possible values:

DMDUP_SIMPLEX
DMDUP_HORIZONTAL
DMDUP_VERTICAL

dmYResolution

Specifies the y-resolution, in dots per inch, of the printer. If the printer initializes this member, the dmPrintQuality member specifies the x-resolution, in dots per inch, of the printer.

dmTTOption

Specifies how TrueType® fonts should be printed. This member can be one of the following values:

Value	Meaning
DMTT_BITMAP	Prints TrueType fonts as graphics. This is the default action for dot-matrix printers.
DMTT_DOWNLOAD	Downloads TrueType fonts as soft fonts. This is the default action for Hewlett-Packard printers that use Printer Control Language (PCL).
DMTT_SUBDEV	Substitute device fonts for TrueType fonts. This is the default action for PostScript® printers.
dmUnusedPadding

Used to align the structure to a DWORD boundary. This should not be used or referenced. Its name and usage is reserved, and can change in future releases.

dmCollate

Specifies whether collation should be used when printing multiple copies. (This member is ignored unless the printer driver indicates support for collation by setting the dmFields member to DM_COLLATE.) This member can be be one of the following values:

Value	Meaning
DMCOLLATE_TRUE	Collate when printing multiple copies.
DMCOLLATE_FALSE	Do not collate when printing multiple copies.
Using DMCOLLATE_TRUE provides faster, more efficient output for collation, since the data is sent to the device driver just once, no matter how many copies are required. The printer is told to simply print the page again.

dmFormName

Windows NT: Specifies the name of the form to use; for example, “Letter” or “Legal”. A complete set of names can be retrieved by using the EnumForms function.

Windows 95: Printer drivers do not use this member.

dmLogPixels

Specifies the number of pixels per logical inch. Printer drivers do not use this member.

dmBitsPerPel

Specifies the color resolution, in bits per pixel, of the display device (for example: 4 bits for 16 colors, 8 bits for 256 colors, or 16 bits for 65536 colors). Display drivers use this member, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.

dmPelsWidth

Specifies the width, in pixels, of the visible device surface. Display drivers use this member, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.

dmPelsHeight

Specifies the height, in pixels, of the visible device surface. Display drivers use this member, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.

dmDisplayFlags

Specifies the device’s display mode. This member can be one of the following values:

Value	Meaning
DM_GRAYSCALE	Specifies that the display is a noncolor device. If this flag is not set, color is assumed.
DM_INTERLACED	Specifies that the display mode is interlaced. If the flag is not set, noninterlaced is assumed.
Display drivers use this member, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.

dmDisplayFrequency

Specifies the frequency, in hertz (cycles per second), of the display device in a particular mode. This value is also known as the display device’s vertical refresh rate. Display drivers use this member. It is used, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.

When you call the EnumDisplaySettings function, the dmDisplayFrequency member may return with the value 0 or 1. These values represent the display hardware’s default refresh rate. This default rate is typically set by switches on a display card or computer motherboard, or by a configuration program that does not use Win32 display functions such as ChangeDisplaySettings.

dmICMMethod

Windows 95:

Specifies how ICM is handled. For a non-ICM application, this member determines if ICM is enabled or disabled. For ICM applications, Windows examines this member to determine how to handle ICM support. This member can be one of the following predefined values, or a driver-defined value greater than the value of DMICMMETHOD_USER:

Value	Meaning
DMICMMETHOD_NONE	Windows 95 only: Specifies that ICM is disabled.
DMICMMETHOD_SYSTEM	Windows 95 only: Specifies that ICM is handled by Windows.
DMICMMETHOD_DRIVER	Windows 95 only: Specifies that ICM is handled by the device driver.
DMICMMETHOD_DEVICE	Windows 95 only: Specifies that ICM is handled by the destination device.
The printer driver must provide a user interface for setting this member. Most printer drivers support only the DMICMMETHOD_SYSTEM or DMICMMETHOD_NONE value. Drivers for PostScript printers support all values.

Windows NT:

This member is not supported on Windows NT.

dmICMIntent

Windows 95:

Specifies which of the three possible color matching methods, or intents, should be used by default. This member is primarily for non-ICM applications. ICM applications can establish intents by using the ICM functions. This member can be one of the following predefined values, or a driver defined value greater than the value of DMICM_USER:

Value	Meaning
DMICM_SATURATE	Windows 95 only: Color matching should optimize for color saturation. This value is the most appropriate choice for business graphs when dithering is not desired.
DMICM_CONTRAST	Windows 95 only: Color matching should optimize for color contrast. This value is the most appropriate choice for scanned or photographic images when dithering is desired.
DMICM_COLORMETRIC	Windows 95 only: Color matching should optimize to match the exact color requested. This value is most appropriate for use with business logos or other images when an exact color match is desired.
Windows NT:

This member is not supported on Windows NT.

dmMediaType

Windows 95:

Specifies the type of media being printed on. The member can be one of the following predefined values, or a driver-defined value greater than the value of DMMEDIA_USER:

Value	Meaning
DMMEDIA_STANDARD	Windows 95 only: Plain paper.
DMMEDIA_GLOSSY	Windows 95 only: Glossy paper.
DMMEDIA_TRANSPARENCY	Windows 95 only: Transparent film.
Windows NT:

This member is not supported on Windows NT.

dmDitherType

Windows 95:

Specifies how dithering is to be done. The member can be one of the following predefined values, or a driver-defined value greater than the value of DMDITHER_USER:

Value	Meaning
DMDITHER_NONE	Windows 95 only: No dithering.
DMDITHER_COARSE	Windows 95 only: Dithering with a coarse brush.
DMDITHER_FINE	Windows 95 only: Dithering with a fine brush.
DMDITHER_LINEART	Windows 95 only: Line art dithering, a special dithering method that produces well defined borders between black, white, and gray scalings. It is not suitable for images that include continuous graduations in intensisty and hue such as scanned photographs.
DMDITHER_GRAYSCALE	Windows 95 only: Device does grayscaling.
Windows NT:

This member is not supported on Windows NT.

dmReserved1

Windows 95: Not used; must be zero.

Windows NT: This member is not supported on Windows NT.

dmReserved2

Windows 95: Not used; must be zero.

Windows NT: This member is not supported on Windows NT.

Remarks

A device driver's private data follows the public portion of the DEVMODE structure. The size of the public data can vary for different versions of the structure. The dmSize member specifies the number of bytes of public data, and the dmDriverExtra member specifies the number of bytes of private data.

See Also

AdvancedDocumentProperties, CreateDC, CreateIC, DeviceCapabilities, DocumentProperties, OpenPrinter


DEVNAMES

The DEVNAMES structure contains strings that identify the driver, device, and output port names for a printer. The PrintDlg function uses these strings to initialize members in the system-defined Print dialog box. When the user closes the dialog box, information about the selected printer is returned in this structure.

typedef struct tagDEVNAMES { // dvnm

    WORD wDriverOffset;

    WORD wDeviceOffset;

    WORD wOutputOffset;

    WORD wDefault;

    // driver, device, and port name strings follow wDefault

} DEVNAMES;

Members

wDriverOffset

(Input/Output) Specifies the offset in characters from the beginning of this structure to a null-terminated string that contains the filename (without the extension) of the device driver. On input, this string is used to determine the printer to display initially in the dialog box.

wDeviceOffset

(Input/Output) Specifies the offset in characters from the beginning of this structure to the null-terminated string (maximum of 32 bytes including the null) that contains the name of the device. This string must be identical to the dmDeviceName member of the DEVMODE structure.

wOutputOffset

(Input/Output) Specifies the offset in characters from the beginning of this structure to the null-terminated string that contains the device name for the physical output medium (output port).

wDefault

Specifies whether the strings contained in the DEVNAMES structure identify the default printer. This string is used to verify that the default printer has not changed since the last print operation. If any of the strings do not match, a warning message is displayed informing the user that the document may need to be reformatted.

On output, the wDefault member is changed only if the Print Setup dialog box was displayed and the user chose the OK button. The DN_DEFAULTPRN flag is used if the default printer was selected. If a specific printer is selected, the flag is not used. All other flags in this member are reserved for internal use by the Print Dialog box procedure.

See Also

DEVMODE, PrintDlg


DIBSECTION

The DIBSECTION structure contains information about a device-independent bitmap created by calling the CreateDIBSection function. A DIBSECTION structure includes information about the bitmap’s dimensions, color format, color masks, optional file mapping object, and optional bit values storage offset. An application can obtain a filled-in DIBSECTION structure for a given device-independent bitmap by calling the GetObject function.

typedef struct tagDIBSECTION {

    BITMAP              dsBm;

    BITMAPINFOHEADER    dsBmih;

    DWORD               dsBitfields[3];

    HANDLE              dshSection;

    DWORD               dsOffset;

} DIBSECTION;

Members

dsBm

A BITMAP data structure that contains information about the device-independent bitmap: its type, its dimensions, its color capacities, and a pointer to its bit values.

dsBmih

A BITMAPINFOHEADER data structure that contains information about the color format of the device-independent bitmap.

dsBitfields

Specifies three DWORD color masks for the device-independent bitmap. This field is only valid when the biBitCount member of the BITMAPINFOHEADER structure has a value greater than 8. Each color mask indicates the bits within a bit value doubleword that are used to encode one of the three color channels (red, green, and blue).

dshSection

Contains a handle to the file mapping object that the CreateDIBSection function used to create the device-independent bitmap. If CreateDIBSection was called with a NULL value for its hSection parameter, causing the operating system to allocate memory for the bitmap, the dshSection member will be NULL.

dsOffset

Specifies the offset to the bitmap’s bit values within the file mapping object referenced by dshSection. If dshSection is NULL, the dsOffset value has no meaning.

See Also

BITMAP, BITMAPINFOHEADER, CreateDIBSection, GetDIBColorTable, GetObject


DirEntry

The DirEntry structure contains a unique ordinal that identifies an individual font in the font resource group.

struct DirEntry {

    WORD fontOrdinal;

};

Member

fontOrdinal

Specifies a unique ordinal identifier for an individual font in a font resource group.

Remarks

The FontDirEntry structure for the specified font directly follows the DirEntry structure for that font.

See Also

FontDirEntry, FontGroupHdr


DISK_GEOMETRY

The DISK_GEOMETRY structure describes the geometry of disk devices and media.

typedef struct _DISK_GEOMETRY {

   LARGE_INTEGER  Cylinders;

   MEDIA_TYPE  MediaType;

   DWORD  TracksPerCylinder;

   DWORD  SectorsPerTrack;

   DWORD  BytesPerSector;

} DISK_GEOMETRY ;

Members

Cylinders

The number of cylinders.

MediaType

The type of media. See MEDIA_TYPE.

TracksPerCylinder

The number of tracks per cylinder.

SectorsPerTrack

The number of sectors per track.

BytesPerSector

The number of bytes per sector

Remarks

The DeviceIoControl function receives a DISK_GEOMETRY structure in response to an IOCTL_DISK_GET_DRIVE_GEOMETRY device input and output contol (IOCTL) operation. The DeviceIoControl function receives an array of DISK_GEOMETRY structures in response to an IOCTL_DISK_GET_MEDIA_TYPES device I/O operation.

See Also

DeviceIoControl, IOCTL_DISK_GET_DRIVE_GEOMETRY, IOCTL_DISK_GET_MEDIA_TYPES, MEDIA_TYPE


DISK_PERFORMANCE

The DISK_PERFORMANCE structure provides disk performance information.

typedef struct _DISK_PERFORMANCE {

        LARGE_INTEGER BytesRead;

        LARGE_INTEGER BytesWritten;

        LARGE_INTEGER ReadTime;

        LARGE_INTEGER WriteTime;

        DWORD ReadCount;

        DWORD WriteCount;

        DWORD QueueDepth;

} DISK_PERFORMANCE ;

Members

BytesRead

Specifies the number of bytes read.

BytesWritten

Specifies the number of bytes written.

ReadTime

Specifies the time it took to complete the read.

WriteTime

Specifies the time it took to complete the write.

ReadCount

Specifies the number of read operations.

WriteCount

Specifies the number of write operations.

QueueDepth

Specifies the depth of the queue.

Remarks

The DeviceIoControl function receives a DISK_PERFORMANCE structure in response to an IOCTL_DISK_PERFORMANCE device I/O operation.

See Also

DeviceIoControl, IOCTL_DISK_PERFORMANCE


DLGITEMTEMPLATE

The DLGITEMTEMPLATE structure defines the dimensions and style of a control in a dialog box. One or more of these structures are combined with a DLGTEMPLATE structure to form a standard template for a dialog box.

typedef struct { // dlit

    DWORD style;

    DWORD dwExtendedStyle;

    short x;

    short y;

    short cx;

    short cy;

    WORD  id;

} DLGITEMTEMPLATE;

Members

style

Specifies the style of the control. This member can be a combination of window style values (such as WS_BORDER) and one or more of the control style values (such as BS_PUSHBUTTON and ES_LEFT).

dwExtendedStyle

Specifies extended styles for a window. This member is not used to create controls in dialog boxes, but applications that use dialog box templates can use it to create other types of windows.

x

Specifies the x-coordinate, in dialog box units, of the upper-left corner of the control. This coordinate is always relative to the upper-left corner of the dialog box’s client area.

y

Specifies the y-coordinate, in dialog box units, of the upper-left corner of the control. This coordinate is always relative to the upper-left corner of the dialog box’s client area.

cx

Specifies the width, in dialog box units, of the control.

cy

Specifies the height, in dialog box units, of the control.

id

Specifies the control identifier.

Remarks

In a standard template for a dialog box, the DLGITEMTEMPLATE structure is always immediately followed by three variable-length arrays specifying the class, title, and creation data for the control. Each array consists of one or more 16-bit elements.

Each DLGITEMTEMPLATE structure in the template must be aligned on a DWORD boundary. The class and title arrays must be aligned on WORD boundaries. The creation data array must be aligned on a DWORD boundary.

Immediately following each DLGITEMTEMPLATE structure is a class array that identifies the window class of the control. If the first element of this array is any value other than 0xFFFF, the system treats the array as a null-terminated Unicode string that specifies the name of a registered window class. If the first element is 0xFFFF, the array has one additional element that specifies the ordinal value of a predefined system class. The ordinal can be one of the following atom values.

Value	Meaning
0x0080	Button
0x0081	Edit
0x0082	Static
0x0083	List box
0x0084	Scroll bar
0x0085	Combo box
Following the class array is a title array that contains the initial text or resource identifier of the control. If the first element of this array is 0xFFFF, the array has one additional element that specifies an ordinal value of a resource, such as an icon, in an executable file. You can use a resource identifier for controls, such as static icon controls, that load and display an icon or other resource rather than text. If the first element is any value other than 0xFFFF, the system treats the array as a null-terminated Unicode string that specifies the initial text.

The creation data array begins at the next DWORD boundary after the title array. This creation data can be of any size and format. If the first byte of the creation data array is nonzero, it indicates the size, in bytes, of the creation data (including the size byte). The control’s window procedure must be able to interpret the data. When the system creates the control, it passes a pointer to this data in the lParam parameter of the WM_CREATE message that it sends to the control.

If you specify character strings in the class and title arrays, you must use Unicode strings. To create code that works on both Windows NT and Windows 95, use the MultiByteToWideChar function to generate these Unicode strings.

The x, y, cx, and cy members specify values in dialog box units. You can convert these values to screen units (pixels) by using the MapDialogRect function.

See Also

CreateDialogIndirect, CreateDialogIndirectParam, CreateWindowEx, DialogBoxIndirect, DialogBoxIndirectParam, DLGITEMTEMPLATEEX, DLGTEMPLATE, DLGTEMPLATEEX, MapDialogRect, MultiByteToWideChar, WM_CREATE


DLGITEMTEMPLATEEX

The DLGITEMTEMPLATEEX structure is not defined in any standard header file. The structure definition is provided here to explain the format of an extended template for a dialog box.

For each control in a dialog box, an extended dialog box template has a block of data that uses the DLGITEMTEMPLATEEX format to describe the control. For a description of the format of an extended dialog box template, see DLGTEMPLATEEX.

// typedef struct {

//     DWORD  helpID;

//     DWORD  exStyle;

//     DWORD  style;

//     short  x;

//     short  y;

//     short  cx;

//     short  cy;

//     WORD   id;

//     sz_Or_Ord windowClass; // name or ordinal of a window class

//     sz_Or_Ord title;       // title string or ordinal of a resource

//     WORD   extraCount;     // bytes of following creation data

// } DLGITEMTEMPLATEEX;

Members

helpID

Specifies the help context identifier for the control. When the system sends a WM_HELP message, it passes the helpID value in the dwContextId member of the HELPINFO structure.

dwExtendedStyle

Specifies extended styles for a window. This member is not used to create controls in dialog boxes, but applications that use dialog box templates can use it to create other types of windows.

style

Specifies the style of the control. This member can be a combination of window style values (such as WS_BORDER) and one or more of the control style values (such as BS_PUSHBUTTON and ES_LEFT).

x

Specifies the x-coordinate, in dialog box units, of the upper-left corner of the control. This coordinate is always relative to the upper-left corner of the dialog box’s client area.

y

Specifies the y-coordinate, in dialog box units, of the upper-left corner of the control. This coordinate is always relative to the upper-left corner of the dialog box’s client area.

cx

Specifies the width, in dialog box units, of the control.

cy

Specifies the height, in dialog box units, of the control.

id

Specifies the control identifier.

windowClass

Specifies a variable-length array of 16-bit elements that identifies the window class of the control. If the first element of this array is any value other than 0xFFFF, the system treats the array as a null-terminated Unicode string that specifies the name of a registered window class.

If the first element is 0xFFFF, the array has one additional element that specifies the ordinal value of a predefined system class. The ordinal can be one of the following atom values.

Value	Meaning
0x0080	Button
0x0081	Edit
0x0082	Static
0x0083	List box
0x0084	Scroll bar
0x0085	Combo box
title

Specifies a variable-length array of 16-bit elements that contains the initial text or resource identifier of the control. If the first element of this array is 0xFFFF, the array has one additional element that specifies an ordinal value that identifies a resource, such as an icon, in an executable file. You can use a resource identifier for controls, such as static icon controls, that load and display an icon or other resource rather than text.

If the first element is any value other than 0xFFFF, the system treats the array as a null-terminated Unicode string that specifies the initial text.

extraCount

Specifies the number of bytes of creation data that follow this member. If this value is greater than zero, the creation data begins at the next DWORD boundary. This creation data can be of any size and format. The control’s window procedure must be able to interpret the data. When the system creates the control, it passes a pointer to this data in the lParam parameter of the WM_CREATE message that it sends to the control.

Remarks

An extended template for a dialog box consists of a DLGTEMPLATEEX header followed by a DLGITEMTEMPLATEEX structure for each control in the dialog box.

Each DLGITEMTEMPLATEEX structure must be aligned on a DWORD boundary. The variable-length windowClass and title arrays must be aligned on WORD boundaries. The creation data array, if any, must be aligned on a DWORD boundary.

If you specify character strings in the windowClass and title arrays, you must use Unicode strings. To create code that works on both Windows NT and Windows 95, use the MultiByteToWideChar function to generate these Unicode strings.

The x, y, cx, and cy members specify values in dialog box units. You can convert these values to screen units (pixels) by using the MapDialogRect function.

See Also

CreateDialogIndirect, CreateDialogIndirectParam, CreateWindowEx, DialogBoxIndirect, DialogBoxIndirectParam, DLGITEMTEMPLATE, DLGTEMPLATE, DLGTEMPLATEEX, MapDialogRect, MultiByteToWideChar


DLGTEMPLATE

The DLGTEMPLATE structure defines the dimensions and style of a dialog box. This structure, always the first in a standard template for a dialog box, also specifies the number of controls in the dialog box and therefore specifies the number of subsequent DLGITEMTEMPLATE structures in the template.

typedef struct { // dltt

    DWORD style;

    DWORD dwExtendedStyle;

    WORD  cdit;

    short x;

    short y;

    short cx;

    short cy;

} DLGTEMPLATE;

Members

style

Specifies the style of the dialog box. This member can be a combination of window style values (such as WS_CAPTION and WS_SYSMENU) and one or more of the following dialog box style values:

Value	Meaning
DS_3DLOOK	Gives the dialog box a nonbold font and draws three-dimensional borders around control windows in the dialog box.  The DS_3DLOOK style is required only by Win32-based applications compiled for versions of Windows earlier than Windows 95 or Windows NT 4.0. The system automatically applies the three-dimensional look to dialog boxes created by applications compiled for current versions of Windows.
DS_ABSALIGN	Indicates that the coordinates of the dialog box are screen coordinates. If this style is not specified, Windows assumes they are client coordinates.
DS_CENTER	Centers the dialog box in the working area; that is, the area not obscured by the tray.
DS_CENTERMOUSE	Centers the mouse cursor in the dialog box.
DS_CONTEXTHELP	Includes a question mark in the title bar of the dialog box. When the user clicks the question mark, the cursor changes to a question mark with a pointer. If the user then clicks a control in the dialog box, the control receives a WM_HELP message. The control should pass the message to the dialog box procedure, which should call the WinHelp function using the HELP_WM_HELP command. The Help application displays a pop-up window that typically contains help for the control.  Note that DS_CONTEXTHELP is only a placeholder. When the dialog box is created, the system checks for DS_CONTEXTHELP and, if it is there, adds WS_EX_CONTEXTHELP to the extended style of the dialog box. WS_EX_CONTEXTHELP cannot be used with the WS_MAXIMIZEBOX or WS_MINIMIZEBOX styles.
DS_CONTROL	Creates a dialog box that works well as a child window of another dialog box, much like a page in a property sheet. This style allows the user to tab among the control windows of a child dialog box, use its accelerator keys, and so on.
DS_FIXEDSYS	Causes the dialog box to use the SYSTEM_FIXED_FONT instead of the default SYSTEM_FONT. SYSTEM_FIXED_FONT is a monospace font compatible with the System font in Windows versions earlier than 3.0.
DS_LOCALEDIT	Applies to 16-bit applications only. This style directs edit controls in the dialog box to allocate memory from the application’s data segment. Otherwise, edit controls allocate storage from a global memory object.
DS_MODALFRAME	Creates a dialog box with a modal dialog-box frame that can be combined with a title bar and System menu by specifying the WS_CAPTION and WS_SYSMENU styles.
DS_NOFAILCREATE	Windows 95 only: Creates the dialog box even if errors occur — for example, if a child window cannot be created or if the system cannot create a special data segment for an edit control.
DS_NOIDLEMSG	Suppresses WM_ENTERIDLE messages that Windows would otherwise send to the owner of the dialog box while the dialog box is displayed.
DS_SETFONT	Indicates that the header of the dialog box template contains additional data specifying the font to use for text in the client area and controls of the dialog box. The font data begins on the WORD boundary that follows the title array. It specifies a 16-bit point size value and a Unicode font name string. If possible, the system creates a font according to the specified values. Then the system passes the handle of the font to the dialog box and to each control by sending them the WM_SETFONT message.  If this style is not specified, the dialog box template does not include the font data.
DS_SETFOREGROUND	Causes the system to use the SetForegroundWindow function to bring the dialog box to the foreground.
DS_SYSMODAL	Creates a system-modal dialog box. This style causes the dialog box to have the WS_EX_TOPMOST style, but otherwise has no effect on the dialog box or the behavior of other windows in the system when the dialog box is displayed.
dwExtendedStyle

Specifies extended styles for a window. This member is not used to create dialog boxes, but applications that use dialog box templates can use it to create other types of windows.

cdit

Specifies the number of items in the dialog box.

x

Specifies the x-coordinate, in dialog box units, of the upper-left corner of the dialog box.

y

Specifies the y-coordinate, in dialog box units, of the upper-left corner of the dialog box.

cx

Specifies the width, in dialog box units, of the dialog box.

cy

Specifies the height, in dialog box units, of the dialog box.

Remarks

In a standard template for a dialog box, the DLGTEMPLATE structure is always immediately followed by three variable-length arrays that specify the menu, class, and title for the dialog box. When the DS_SETFONT style is given, these arrays are also followed by a 16-bit value specifying point size and another variable-length array specifying a typeface name. Each array consists of one or more 16-bit elements. The menu, class, title, and font arrays must be aligned on WORD boundaries.

Immediately following the DLGTEMPLATE structure is a menu array that identifies a menu resource for the dialog box. If the first element of this array is 0x0000, the dialog box has no menu and the array has no other elements. If the first element is 0xFFFF, the array has one additional element that specifies the ordinal value of a menu resource in an executable file. If the first element has any other value, the system treats the array as a null-terminated Unicode string that specifies the name of a menu resource in an executable file.

Following the menu array is a class array that identifies the window class of the control. If the first element of the array is 0x0000, the system uses the predefined dialog box class for the dialog box and the array has no other elements. If the first element is 0xFFFF, the array has one additional element that specifies the ordinal value of a predefined system window class. If the first element has any other value, the system treats the array as a null-terminated Unicode string that specifies the name of a registered window class.

Following the class array is a title array that specifies a null-terminated Unicode string that contains the title of the dialog box. If the first element of this array is 0x0000, the dialog box has no title and the array has no other elements.

The 16-bit point size value and the typeface array follow the title array, but only if the style member specifies the DS_SETFONT style. The point size value specifies the point size of the font to use for the text in the dialog box and its controls. The typeface array is a null-terminated Unicode string specifying the name of the typeface for the font. When these values are given, Windows creates a font having the given size and typeface (if possible) and sends a WM_SETFONT message to the dialog box procedure and the control window procedures as it creates the dialog box and controls.

Following the DLGTEMPLATE header in a standard dialog box template are one or more DLGITEMTEMPLATE structures that define the dimensions and style of the controls in the dialog box. The cdit member specifies the number of DLGITEMTEMPLATE structures in the template. These DLGITEMTEMPLATE structures must be aligned on DWORD boundaries.

If you specify character strings in the menu, class, title, or typeface arrays, you must use Unicode strings. To create code that works on both Windows NT and Windows 95, use the MultiByteToWideChar function to generate these Unicode strings.

The x, y, cx, and cy members specify values in dialog box units. You can convert these values to screen units (pixels) by using the MapDialogRect function.

See Also

CreateDialogIndirect, CreateDialogIndirectParam, DialogBoxIndirect, DialogBoxIndirectParam, DLGITEMTEMPLATE, DLGITEMTEMPLATEEX, DLGTEMPLATEEX, MapDialogRect, MultiByteToWideChar


DLGTEMPLATEEX

The DLGTEMPLATEEX structure is not defined in any standard header file. The structure definition is provided here to explain the format of an extended template for a dialog box.

An extended dialog box template begins with a DLGTEMPLATEEX header that describes the dialog box and specifies the number of controls in the dialog box. For each control in a dialog box, an extended dialog box template has a block of data that uses the DLGITEMTEMPLATEEX format to describe the control.

// typedef struct {

//     WORD   dlgVer;

//     WORD   signature;

//     DWORD  helpID;

//     DWORD  exStyle;

//     DWORD  style;

//     WORD   cDlgItems;

//     short  x;

//     short  y;

//     short  cx;

//     short  cy;

//     sz_Or_Ord menu;         // name or ordinal of a menu resource

//     sz_Or_Ord windowClass;  // name or ordinal of a window class

//     WCHAR  title[titleLen]; // title string of the dialog box

//     short  pointsize;       // only if DS_SETFONT flag is set

//     short  weight;          // only if DS_SETFONT flag is set

//     short  bItalic;         // only if DS_SETFONT flag is set

//     WCHAR  font[fontLen];   // typeface name, if DS_SETFONT is set

// } DLGTEMPLATEEX;

Members

dlgVer

Indicates whether a template is an extended dialog box template. A value of 0xFFFF indicates an extended dialog box template. In this case, the signature member specifies the template version number. If dlgVer is any value other than 0xFFFF, this is a standard template that uses the DLGTEMPLATE and DLGITEMTEMPLATE structures.

signature

Specifies the version number of the extended dialog box template. This member must specify 1.

helpID

Specifies the help context identifier for the dialog box window. When the system sends a WM_HELP message, it passes this value in the dwContextId member of the HELPINFO structure.

exStyle

Specifies extended styles for a window. This member is not used to create dialog boxes, but applications that use dialog box templates can use it to create other types of windows.

style

Specifies the style of the dialog box. This member can be a combination of window style values (such as WS_CAPTION and WS_SYSMENU) and one or more of the following dialog box style values.

Value	Meaning
DS_3DLOOK	Gives the dialog box a nonbold font and draws three-dimensional borders around control windows in the dialog box.  The DS_3DLOOK style is required only by Win32-based applications compiled for versions of Windows earlier than Windows 95 or Windows NT 4.0. The system automatically applies the three-dimensional look to dialog boxes created by applications compiled for current versions of Windows.
DS_ABSALIGN	Indicates that the coordinates of the dialog box are screen coordinates. If this style is not specified, the system treats them as client coordinates.
DS_CENTER	Centers the dialog box in the working area; that is, the area not obscured by the tray.
DS_CENTERMOUSE	Centers the mouse cursor in the dialog box.
DS_CONTEXTHELP	Includes a question mark in the title bar of the dialog box. When the user clicks the question mark, the cursor changes to a question mark with a pointer. If the user then clicks a control in the dialog box, the control receives a WM_HELP message. The control should pass the message to the dialog procedure, which should call the WinHelp function using the HELP_WM_HELP command. The Help application displays a pop-up window that typically contains help for the control.  Note that DS_CONTEXTHELP is only a placeholder. When the dialog box is created, the system checks for DS_CONTEXTHELP and, if it is there, adds WS_EX_CONTEXTHELP to the extended style of the dialog box. You cannot use the WS_EX_CONTEXTHELP style with the WS_MAXIMIZEBOX or WS_MINIMIZEBOX styles.
DS_CONTROL	Creates a dialog box that works well as a child window of another dialog box, much like a page in a property sheet. This style allows the user to tab among the control windows of a child dialog box, use its accelerator keys, and so on.
DS_FIXEDSYS	Causes the dialog box to use the SYSTEM_FIXED_FONT instead of the default SYSTEM_FONT. SYSTEM_FIXED_FONT is a monospace font compatible with the System font in Windows versions earlier than 3.0.
DS_LOCALEDIT	Applies to 16-bit applications only. This style directs edit controls in the dialog box to allocate memory from the application’s data segment. Otherwise, edit controls allocate storage from a global memory object.
DS_MODALFRAME	Creates a dialog box with a modal dialog-box frame that can be combined with a title bar and System menu by specifying the WS_CAPTION and WS_SYSMENU styles.
DS_NOFAILCREATE	Windows 95 only: Creates the dialog box even if errors occur — for example, if a child window cannot be created or if the system cannot create a special data segment for an edit control.
DS_NOIDLEMSG	Suppresses WM_ENTERIDLE messages that Windows would otherwise send to the owner of the dialog box while the dialog box is displayed.
DS_SETFONT	Indicates that the DLGTEMPLATEEX header of the extended dialog box template contains four additional members (pointsize, weight, bItalic, and font) that describe the font to use for the text in the client area and controls of the dialog box. If possible, the system creates a font according to the values specified in these members. Then the system passes the handle of the font to the dialog box and to each control by sending them the WM_SETFONT message.  If this style is not specified, the extended dialog box template does not include the pointsize, weight, bItalic, and font members.
DS_SETFOREGROUND	Causes the system to use the SetForegroundWindow function to bring the dialog box to the foreground.
DS_SYSMODAL	Creates a system-modal dialog box. This style causes the dialog box to have the WS_EX_TOPMOST style. Otherwise, it has no effect on the dialog box or the behavior of other windows in the system when the dialog box is displayed.
cDlgItems

Specifies the number of controls in the dialog box.

x

Specifies the x-coordinate, in dialog box units, of the upper-left corner of the dialog box.

y

Specifies the y-coordinate, in dialog box units, of the upper-left corner of the dialog box.

cx

Specifies the width, in dialog box units, of the dialog box.

cy

Specifies the height, in dialog box units, of the dialog box.

menu

Specifies a variable-length array of 16-bit elements that identifies a menu resource for the dialog box. If the first element of this array is 0x0000, the dialog box has no menu and the array has no other elements. If the first element is 0xFFFF, the array has one additional element that specifies the ordinal value of a menu resource in an executable file. If the first element has any other value, the system treats the array as a null-terminated Unicode string that specifies the name of a menu resource in an executable file.

windowClass

Specifies a variable-length array of 16-bit elements that identifies the window class of the dialog box. If the first element of the array is 0x0000, the system uses the predefined dialog box class for the dialog box and the array has no other elements. If the first element is 0xFFFF, the array has one additional element that specifies the ordinal value of a predefined system window class. If the first element has any other value, the system treats the array as a null-terminated Unicode string that specifies the name of a registered window class.

title

Specifies a null-terminated Unicode string that contains the title of the dialog box. If the first element of this array is 0x0000, the dialog box has no title and the array has no other elements.

pointsize

Specifies the point size of the font to use for the text in the dialog box and its controls. The pointsize, weight, bItalic, and font members are present in an extended dialog box template only if the style member specifies the DS_SETFONT style.

weight

Specifies the weight of the font in the range 0 through 1000. This can be any of the values listed for the lfWeight member of the LOGFONT structure. This member is present only if the style member specifies DS_SETFONT.

bItalic

Indicates whether the font is italic. If this value is TRUE, the font is italic. This member is present only if the style member specifies DS_SETFONT.

font

Specifies a null-terminated Unicode string that contains the name of the typeface for the font. This member is present only if the style member specifies DS_SETFONT.

Remarks

You can use an extended dialog box template instead of a standard dialog box template in the CreateDialogIndirectParam and DialogBoxIndirectParam functions and the CreateDialogIndirect and DialogBoxIndirect macros. A standard dialog box template uses the DLGTEMPLATE and DLGITEMTEMPLATE structures.

Following the DLGTEMPLATEEX header in an extended dialog box template is one or more DLGITEMTEMPLATEEX structures that describe the controls of the dialog box. The cDlgItems member specifies the number of DLGITEMTEMPLATEEX structures in the template.

Each DLGITEMTEMPLATEEX structure in the template must be aligned on a DWORD boundary. If the style member specifies the DS_SETFONT style, the first DLGITEMTEMPLATEEX structure begins on the first DWORD boundary after the font string. If DS_SETFONT is not specified, the first structure begins on the first DWORD boundary after the title string.

The menu, windowClass, title, and font arrays must be aligned on WORD boundaries.

If you specify character strings in the menu, windowClass, title, and font arrays, you must use Unicode strings. To create code that works on both Windows NT and Windows 95, use the MultiByteToWideChar function to generate these Unicode strings.

The x, y, cx, and cy members specify values in dialog box units. You can convert these values to screen units (pixels) by using the MapDialogRect function.

See Also

CreateDialogIndirect, CreateDialogIndirectParam, DialogBoxIndirect, DialogBoxIndirectParam, DLGITEMTEMPLATE, DLGITEMTEMPLATEEX, DLGTEMPLATE, MapDialogRect, MultiByteToWideChar, WM_SETFONT


DOC_INFO_1

The DOC_INFO_1 structure describes a document that will be printed.

typedef struct _DOC_INFO_1 { // dci1

    LPTSTR pDocName;

    LPTSTR pOutputFile;

    LPTSTR pDatatype;

} DOC_INFO_1;

Members

pDocName

Points to a null-terminated string that specifies the name of the document.

pOutputFile

Points to a null-terminated string that specifies the name of an output file.

pDatatype

Points to a null-terminated string that identifies the type of data used to record the document.

See Also

StartDocPrinter


DOC_INFO_2

The DOC_INFO_2 structure describes a document that will be printed.

typedef struct _DOC_INFO_2 { // dci2

    LPTSTR pDocName;

    LPTSTR pOutputFile;

    LPTSTR pDatatype;

    DWORD  dwMode;

    DWORD  JobId;

} DOC_INFO_2;

Members

pDocName

Points to a null-terminated string that specifies the name of the document.

pOutputFile

Points to a null-terminated string that specifies the name of an output file.

pDatatype

Points to a null-terminated string that identifies the type of data used to record the document.

dwMode

Informs the print spooler of the nature of the data to follow. If this value is zero, the print spooler treats the data sent by subsequent calls to WritePrinter as a normal print job (whether or not it is spooled depends on the printer property). If this value is DI_CHANNEL, only a communications channel is opened. In this case, the data passed into subsequent calls to WritePrinter is sent to the printer or subsequent calls to ReadPrinter retrieve data from the printer. This mode remains effective until EndDoc is called.

JobId

Reserved for internal use; should be zero.

See Also

EndDoc, ReadPrinter, StartDocPrinter, WritePrinter


DOCINFO

The DOCINFO structure contains the input and output filenames and other information used by the StartDoc function.

typedef struct {    // di

    int     cbSize;

    LPCTSTR lpszDocName;

    LPCTSTR lpszOutput;

    LPCTSTR lpszDatatype;   // Windows 95 only; ignored on Windows NT

    DWORD   fwType;         // Windows 95 only; ignored on Windows NT

} DOCINFO;

Members

cbSize

Specifies the size, in bytes, of the structure.

lpszDocName

Points to a null-terminated string that specifies the name of the document.

lpszOutput

Points to a null-terminated string that specifies the name of an output file. If this pointer is NULL, the output will be sent to the device identified by the device context handle that was passed to the StartDoc function.

lpszDatatype

Windows 95: Points to a null-terminated string that specifies the type of data used to record the print job.

Windows NT: This member is ignored.

fwType

Windows 95: Specifies additional information about the print job. Can be zero or DI_APPBANDING if the application will use banding. For optimal performance during printing, banding applications should specify DI_APPBANDING.

Windows NT: This member is ignored.

See Also

StartDoc


DRAGLISTINFO

The DRAGLISTINFO structure contains information about a drag event. The pointer to DRAGLISTINFO is passed as the lParam parameter of the drag list message.

Typedef struct {

    UINT uNotification;

    HWND hWnd;

    POINT ptCursor;

} DRAGLISTINFO, FAR *LPDRAGLISTINFO;

Members

uNotification

Notification code that specifies the type of drag event. This member can be one of the following values:

Value	Meaning
DL_BEGINDRAG	The user has clicked the left mouse button on a list item.
DL_CANCELDRAG	The user has canceled the drag operation by clicking the right mouse button or pressing the ESC key.
DL_DRAGGING	The user has moved the mouse while dragging an item.
DL_DROPPED	The user has released the left mouse button, completing a drag operation.
hWnd

Handle to drag list box.

ptCursor

POINT structure that contains the current x- and y-coordinates of the mouse cursor.

See also

DL_BEGINDRAG, DL_CANCELDRAG, DL_DRAGGING, DL_DROPPED, POINT


DRAWITEMSTRUCT

The DRAWITEMSTRUCT structure provides information the owner window must have to determine how to paint an owner-drawn control or menu item. The owner window of the owner-drawn control or menu item receives a pointer to this structure as the lParam parameter of the WM_DRAWITEM message.

typedef struct tagDRAWITEMSTRUCT {  // dis

    UINT  CtlType;

    UINT  CtlID;

    UINT  itemID;

    UINT  itemAction;

    UINT  itemState;

    HWND  hwndItem;

    HDC   hDC;

    RECT  rcItem;

    DWORD itemData;

} DRAWITEMSTRUCT;

Members

CtlType

Specifies the control type. This member can be one of the following values:

Value	Meaning
ODT_BUTTON	Owner-drawn button
ODT_COMBOBOX	Owner-drawn combo box
ODT_LISTBOX	Owner-drawn list box
ODT_LISTVIEW	List view control
ODT_MENU	Owner-drawn menu item
ODT_STATIC	Owner-drawn static control
ODT_TAB	Tab control
CtlID

Specifies the identifier of the combo box, list box, button, or static control. This member is not used for a menu item.

itemID

Specifies the menu item identifier for a menu item or the index of the item in a list box or combo box. For an empty list box or combo box, this member can be −1. This allows the application to draw only the focus rectangle at the coordinates specified by the rcItem member even though there are no items in the control. This indicates to the user whether the list box or combo box has the focus. How the bits are set in the itemAction member determines whether the rectangle is to be drawn as though the list box or combo box has the focus.

itemAction

Specifies the drawing action required. This member can be one or more of the following values:

Value	Meaning
ODA_DRAWENTIRE	The entire control needs to be drawn.
ODA_FOCUS	The control has lost or gained the keyboard focus. The itemState member should be checked to determine whether the control has the focus.
ODA_SELECT	The selection status has changed. The itemState member should be checked to determine the new selection state.
itemState

Specifies the visual state of the item after the current drawing action takes place. This member can be a combination of the following values:

Value	Meaning
ODS_CHECKED	The menu item is to be checked. This bit is used only in a menu.
ODS_COMBOBOXEDIT	The drawing takes place in the selection field (edit control) of an ownerdrawn combo box.
ODS_DEFAULT	The item is the default item.
ODS_DISABLED	The item is to be drawn as disabled.
ODS_FOCUS	The item has the keyboard focus.
ODS_GRAYED	The item is to be grayed. This bit is used only in a menu.
ODS_SELECTED	The menu item’s status is selected.
hwndItem

Identifies the control for combo boxes, list boxes, buttons, and static controls. For menus, this member identifies the menu containing the item.

hDC

Identifies a device context; this device context must be used when performing drawing operations on the control.

rcItem

Specifies a rectangle that defines the boundaries of the control to be drawn. This rectangle is in the device context specified by the hDC member. Windows automatically clips anything the owner window draws in the device context for combo boxes, list boxes, and buttons, but does not clip menu items. When drawing menu items, the owner window must not draw outside the boundaries of the rectangle defined by the rcItem member.

itemData

Specifies the application-defined 32-bit value associated with the menu item. For a control, this parameter specifies the value last assigned to the list box or combo box by the LB_SETITEMDATA or CB_SETITEMDATA message. If the list box or combo box has the LBS_HASSTRINGS or CBS_HASSTRINGS style, this value is initially zero. Otherwise, this value is initially the value that was passed to the list box or combo box in the lParam parameter of one of the following messages:

CB_ADDSTRING
CB_INSERTSTRING
LB_ADDSTRING
LB_INSERTSTRING

If ctlType is ODT_BUTTON or ODT_STATIC, itemData is zero.

See Also

CB_ADDSTRING, CB_INSERTSTRING, CB_SETITEMDATA, LB_ADDSTRING, LB_INSERTSTRING, LB_SETITEMDATA, WM_DRAWITEM


DRAWTEXTPARAMS

The DRAWTEXTPARAMS structure contains extended formatting options for the DrawTextEx function.

typedef struct {

    UINT cbSize;

    int  iTabLength;

    int  iLeftMargin;

    int  iRightMargin;

    UINT uiLengthDrawn;

} DRAWTEXTPARAMS, FAR *LPDRAWTEXTPARAMS;

Members

cbSize

Specifies the structure size, in bytes.

iTabLength

Specifies the size of each tab stop, in units equal to the average character width.

iLeftMargin

Specifies the left margin, in units equal to the average character width.

iRightMargin

Specifies the right margin, in units equal to the average character width.

uiLengthDrawn

Receives the number of characters processed by DrawTextEx, including white-space characters. The number can be the length of the string or the index of the first line that falls below the drawing area. Note that DrawTextEx always processes the entire string if the DT_NOCLIP formatting flag is specified.

See Also

DrawTextEx


DRIVE_LAYOUT_INFORMATION

The DRIVE_LAYOUT_INFORMATION structure provides information about a drive’s partitions.

typedef struct _DRIVE_LAYOUT_INFORMATION {

   DWORD  PartitionCount;

   DWORD  Signature;

   PARTITION_INFORMATION  PartitionEntry[1];

} DRIVE_LAYOUT_INFORMATION;

Members

PartitionCount

The number of partitions on the drive.

Signature

A drive signature value.

PartitionEntry

A variable-sized array of PARTITION_INFORMATION structures, one structure for each partition on the drive.

Remarks

The DeviceIoControl function receives a DRIVE_LAYOUT_INFORMATION structure in response to an IOCTL_DISK_GET_DRIVE_LAYOUT device I/O operation. The DeviceIoControl function  uses a DRIVE_LAYOUT_INFORMATION structure as input to an IOCTL_DISK_SET_DRIVE_LAYOUT device I/O operation.

See Also

DeviceIoControl, IOCTL_DISK_GET_DRIVE_LAYOUT, IOCTL_DISK_SET_DRIVE_LAYOUT, PARTITION_INFORMATION


DRIVER_INFO_1

The DRIVER_INFO_1 structure identifies a printer driver.

typedef struct _DRIVER_INFO_1 { // dri1

    LPTSTR pName;

} DRIVER_INFO_1;

Members

pName

Points to a null-terminated string that specifies the name of a printer driver.

See Also

EnumPrinterDrivers


DRIVER_INFO_2

The DRIVER_INFO_2 structure identifies a printer driver, the driver version number, the environment for which the driver was written, the name of the file in which the driver is stored, and so on.

typedef struct _DRIVER_INFO_2 { // dri2

    DWORD  cVersion;

    LPTSTR pName;

    LPTSTR pEnvironment;

    LPTSTR pDriverPath;

    LPTSTR pDataFile;

    LPTSTR pConfigFile;

} DRIVER_INFO_2;

Members

cVersion

Specifies a printer-driver version number.

pName

Points to a null-terminated string that specifies the name of the driver (for example, “QMS 810”).

pEnvironment

Points to a null-terminated string that specifies the environment for which the driver was written (for example, “Windows NT x86” or “Windows NT R4000”).

pDriverPath

Points to null-terminated string that specifies a filename or full path and filename for the file that contains the device driver (for example, “c:\drivers\pscript.dll”).

pDataFile

Points to a null-terminated string that specifies a filename or a full path and filename for the file that contains driver data (for example, “c:\drivers\QMS810.PPD”).

pConfigFile

Points to a null-terminated string that specifies a filename or a full path and filename for the device-driver’s configuration DLL (for example, “c:\drivers\PSCRPTUI.DLL”).

See Also

AddPrinterDriver, GetPrinterDriver


DRIVER_INFO_3

The DRIVER_INFO_3 structure contains printer driver information.

typedef struct _DRIVER_INFO_3 { // dri3

    DWORD  cVersion;

    LPTSTR pName;

    LPTSTR pEnvironment;

    LPTSTR pDriverPath;

    LPTSTR pDataFile;

    LPTSTR pConfigFile;

    LPTSTR pHelpFile;

    LPTSTR pDependentFiles;

    LPTSTR pMonitorName;

    LPTSTR pDefaultDataType;

} DRIVER_INFO_3;

Members

cVersion

Specifies a printer-driver version number.

pName

Points to a null-terminated string that specifies the name of the driver (for example, “QMS 810”).

pEnvironment

Points to a null-terminated string that specifies the environment for which the driver was written (for example, “Windows x86” or “Windows NT R4000”).

pDriverPath

Points to a null-terminated string that specifies a filename or full path and filename for the file that contains the device driver (for example, “C:\DRIVERS\PSCRIPT.DLL”).

pDataFile

Points to a null-terminated string that specifies a filename or a full path and filename for the file that contains driver data (for example, “C:\DRIVERS\QMS810.PPD”).

pConfigFile

Points to a null-terminated string that specifies a filename or a full path and filename for the device driver’s configuration dynamic-link library (for example, “C:\DRIVERS\PSCRPTUI.DLL”).

pHelpFile

Points to a null-terminated string that specifies a filename or a full path and filename for the device driver’s help file.

pDependentFiles

Points to a null-terminated string that specifies the files the driver is dependent on. Each filename in the string is also terminated with a null (for example, “PSCRIPT.DLL\0QMS810.PPD\0PSCRPTUI.DLL\0PSPCRIPTUI.HLP\0PSTEST.TXT\0\0”).

pMonitorName

Points to a null-terminated string that specifies a language monitor (for example, “PJL monitor”). This member can be NULL and should be specified only for printers capable of bidirectional communication.

pDefaultDataType

Points to a null-terminated string that specifies the default data type of the print job (for example, “EMF”).

See Also

AddPrinterDriver, EnumPrinterDrivers, GetPrinterDriver


DROPFILES

Defines the CF_HDROP and CF_PRINTERS clipboard formats. In the CF_HDROP case, the data that follows is a double − null-terminated list of file names. For CF_PRINTERS, the data that follows are the printer friendly names.

typedef struct _DROPFILES {

    DWORD pFiles; // offset of file list

    POINT pt;     // drop point (coordinates depend on fNC)

    BOOL fNC;     // see below

    BOOL fWide;   // TRUE if file contains wide characters,

                  // FALSE otherwise

} DROPFILES, FAR * LPDROPFILES;

Members

fNC

Nonclient area flag. If this member is TRUE, pt specifies the screen coordinates of a point in a window’s nonclient area. If it is FALSE, pt specifies the client coordinates of a point in the client area.


EDITSTREAM

The EDITSTREAM structure contains information about a data stream used with a rich edit control.

typedef struct _editstream {

    DWORD dwCookie;

    DWORD dwError;

    EDITSTREAMCALLBACK pfnCallback;

} EDITSTREAM;

Members

dwCookie

Application-defined value that is passed to the callback function.

dwError

Error encountered while streaming. If there was no error, this member is zero.

pfnCallback

Pointer to an application-defined function that the control calls to transfer data.

This structure is used with the EM_STREAMIN message to read (stream in) data into a rich edit control, replacing its contents. It is used with the EM_STREAMOUT message to write (stream out) the contents of a rich edit control.

The control calls the callback function repeatedly, transferring a portion of the data with each call. The callback function has the following form:

DWORD CALLBACK EditStreamCallback(DWORD dwCookie,

    LPBYTE pbBuff, LONG cb, LONG FAR *pcb);

dwCookie

Value of the dwCookie member of the EDITSTREAM structure.

pbBuff

Pointer to the buffer to read from or write to.

cb

Count of bytes to read or write.

pcb

Pointer to a variable that receives the number of bytes actually read or written.

Return Value

The return value is zero to continue to the stream operation, or nonzero to abort it.

See Also

EM_STREAMIN, EM_STREAMOUT


EMR

The EMR structure provides the base structure for all enhanced metafile records. An enhanced metafile record contains the parameters for a specific GDI function used to create part of a picture in an enhanced format metafile.

typedef struct tagEMR
{
    DWORD iType;

    DWORD nSize;
} EMR, *PEMR;

Members

iType

Specifies the record type.

nSize

Size of the record, in bytes. This member must be a multiple of four.


EMRANGLEARC

The EMRANGLEARC structure contains members for the AngleArc enhanced metafile record.

typedef struct tagEMRANGLEARC
{
    EMR     emr;
    POINTL  ptlCenter;

    DWORD   nRadius;
    FLOAT   eStartAngle;
    FLOAT   eSweepAngle;
} EMRANGLEARC, *PEMRANGLEARC;

Members

emr

Base structure for all record types.

ptlCenter

Logical coordinates of circle’s center.

nRadius

Circle’s radius, in logical units.

eStartAngle

Arc’s start angle, in degrees.

eSweepAngle

Arc’s sweep angle, in degrees.

See Also

AngleArc


EMRARC, EMRARCTO, EMRCHORD, EMRPIE

The EMRARC, EMRARCTO, EMRCHORD, and EMRPIE structures contain members for the Arc, ArcTo, Chord, and Pie enhanced metafile records.

typedef struct tagEMRARC
{
    EMR    emr;

    RECTL  rclBox;
    POINTL ptlStart;
    POINTL ptlEnd;
} EMRARC,   *PEMRARC,
  EMRARCTO, *PEMRARCTO,
  EMRCHORD, *PEMRCHORD,
  EMRPIE,   *PEMRPIE;

Members

emr

Base structure for all record types.

rclBox

Bounding rectangle.

ptlStart

Coordinates of first radial ending point.

ptlEnd

Coordinates of second radial ending point.

See Also

Arc, ArcTo, Chord, Pie


EMRBITBLT

The EMRBITBLT structure contains members for the BitBlt enhanced metafile record. Note that graphics device interface (GDI) converts the device-dependent bitmap into a device-independent bitmap (DIB) before storing it in the metafile record.

typedef struct tagEMRBITBLT
{
    EMR      emr;

    RECTL    rclBounds;

    LONG     xDest;

    LONG     yDest;

    LONG     cxDest;

    LONG     cyDest;

    DWORD    dwRop;

    LONG     xSrc;

    LONG     ySrc;

    XFORM    xformSrc;

    COLORREF crBkColorSrc;

    DWORD    iUsageSrc;

    DWORD    offBmiSrc;

    DWORD    offBitsSrc;

    DWORD    cbBitsSrc;

} EMRBITBLT, *PEMRBITBLT;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

xDest

Logical x-coordinate of the upper-left corner of the destination rectangle.

yDest

Logical y-coordinate of the upper-left corner of the destination rectangle.

dwRop

Raster-operation code. These codes define how the color data of the source rectangle is to be combined with the color data of the destination rectangle to achieve the final color.

xSrc

Logical x-coordinate of the upper-left corner of the source rectangle.

ySrc

Logical y-coordinate of the upper-left corner of the source rectangle.

xformSrc

World-space to page-space transformation of the source device context.

crBkColorSrc

Background color (the RGB value) of the source device context.

iUsageSrc

Value of the bmiColors member of the BITMAPINFO structure. The iUsageSrc member can be either the DIB_PAL_COLORS, DIB_PAL_INDICES or DIB_RGB_COLORS value.

offBmiSrc

Offset to source BITMAPINFO structure.

cbBmiSrc

Size of source BITMAPINFO structure.

offBitsSrc

Offset to source bitmap bits.

cbBitsSrc

Size of source bitmap bits.

See Also

BitBlt, BITMAPINFO, RGB


EMRCREATEBRUSHINDIRECT

The EMRCREATEBRUSHINDIRECT structure contains members for the CreateBrushIndirect enhanced metafile record.

typedef struct tagEMRCREATEBRUSHINDIRECT
{
    EMR      emr;

    DWORD    ihBrush;

    LOGBRUSH lb;

} EMRCREATEBRUSHINDIRECT, *PEMRCREATEBRUSHINDIRECT;

Members

emr

Base structure for all record types.

ihBrush

Index of brush in handle table.

lb

LOGBRUSH structure containing information about the brush. The lbStyle member must be either the BS_SOLID, BS_HOLLOW, BS_NULL, or BS_HATCHED value.

See Also

CreateBrushIndirect, LOGBRUSH


EMRCREATECOLORSPACE

The EMRCREATECOLORSPACE structure contains members for the CreateColorSpace enhanced metafile record.

typedef struct tagEMRCREATECOLORSPACE
{
    EMR           emr;

    DWORD         ihCS;

    LOGCOLORSPACE lcs;

} EMRCREATECOLORSPACE, *PEMRCREATECOLORSPACE;

Members

emr

Base structure for all record types

ihCS

Index of the color cpace in handle table

lcs

Logical color space

See Also

CreateColorSpace


EMRCREATEDIBPATTERNBRUSHPT

The EMRCREATEDIBPATTERNBRUSHPT structure contains members for the CreateDIBPatternBrushPt enhanced metafile record. The BITMAPINFO structure is followed by the bitmap bits that form a packed device-independent bitmap (DIB).

typedef struct tagEMRCREATEDIBPATTERNBRUSHPT
{
    EMR   emr;

    DWORD ihBrush;

    DWORD iUsage;

    DWORD offBmi;

    DWORD cbBmi;

    DWORD offBits;

    DWORD cbBits;

} EMRCREATEDIBPATTERNBRUSHPT,
PEMRCREATEDIBPATTERNBRUSHPT;

Members

emr

Base structure for all record types.

ihBrush

Index of brush in handle table.

iUsage

Value specifying whether the bmiColors member of the BITMAPINFO structure was provided and, if so, whether bmiColors contains explicit red, green, blue (RGB) values or indices. The iUsage member must be either the DIB_PAL_COLORS, DIB_PAL_INDICES, or DIB_RGB_COLORS value.

offBmi

Offset to BITMAPINFO structure.

cbBmi

Size of BITMAPINFO structure.

offBits

Offset to bitmap bits.

cbBits

Size of bitmap bits.

See Also

BITMAPINFO, CreateDIBPatternBrushPt, RGB


EMRCREATEMONOBRUSH

The EMRCREATEMONOBRUSH structure contains members for the CreatePatternBrush (when passed a monochrome bitmap) or CreateDIBPatternBrush (when passed a monochrome DIB) enhanced metafile records.

typedef struct tagEMRCREATEMONOBRUSH
{
    EMR   emr;

    DWORD ihBrush;

    DWORD iUsage;

    DWORD offBmi;

    DWORD cbBmi;

    DWORD offBits;

    DWORD cbBits;

} EMRCREATEMONOBRUSH, *PEMRCREATEMONOBRUSH;

Members

emr

Base structure for all record types.

ihBrush

Index of brush in handle table.

iUsage

Value specifying whether the bmiColors member of the BITMAPINFO structure was provided and, if so, whether bmiColors contains explicit red, green, blue (RGB) values or indices. The iUsage member must be either the DIB_PAL_COLORS, DIB_PAL_INDICES, or DIB_RGB_COLORS value.

offBmi

Offset to BITMAPINFO structure.

cbBmi

Size of BITMAPINFO structure.

offBits

Offset to bitmap bits.

cbBits

Size of bitmap bits.

See Also

BITMAPINFO, CreateDIBPatternBrush, CreatePatternBrush, RGB


EMRCREATEPALETTE

The EMRCREATEPALETTE structure contains members for the CreatePalette enhanced metafile record.

typedef struct tagEMRCREATEPALETTE
{
    EMR        emr;

    DWORD      ihPal;

    LOGPALETTE lgpl;

} EMRCREATEPALETTE, *PEMRCREATEPALETTE;

Members

emr

Base structure for all record types.

ihPal

Index of palette in handle table.

lgpl

LOGPALETTE structure that contains information about the palette. Note that peFlags members in the PALETTEENTRY structures do not contain any flags.

See Also

CreatePalette, LOGPALETTE, PALETTEENTRY


EMRCREATEPEN

The EMRCREATEPEN structure contains members for the CreatePen enhanced metafile record.

typedef struct tagEMRCREATEPEN
{
    EMR    emr;

    DWORD  ihPen;

    LOGPEN lopn;

} EMRCREATEPEN, *PEMRCREATEPEN;

Members

emr

Base structure for all record types

ihPen

Index to pen in handle table

lopn

Logical pen

See Also

CreatePen


EMRELLIPSE, EMRRECTANGLE

The EMRELLIPSE and EMARRECTANGLE structures contain members for the Ellipse and Rectangle enhanced metafile records.

typedef struct tagEMRELLIPSE
{
    EMR   emr;

    RECTL rclBox;

} EMRELLIPSE,  *PEMRELLIPSE,
  EMRRECTANGLE, *PEMRRECTANGLE;

Members

emr

Base structure for all record types.

rclBox

Bounding rectangle.

See Also

Ellipse, Rectangle


EMREOF

The EMREOF structure contains data for the enhanced metafile record that indicates the end of the metafile.

typedef struct tagEMREOF
{
    EMR     emr;
    DWORD   nPalEntries;

    DWORD   offPalEntries;

    DWORD   nSizeLast;

} EMREOF, *PEMREOF;

Members

emr

Base structure for all record types.

nPalEntries

Number of palette entries.

offPalEntires

Offset to palette entries.

nSizeLast

Same size as the nSize member of the EMR structure. This member must be the last doubleword of the record. If palette entries exist, they precede this member.

See Also

EMR


EMREXCLUDECLIPRECT, EMRINTERSECTCLIPRECT

The EMREXCLUDECLIPRECT and EMRINTERSECTCLIPRECTstructures contain members for the ExcludeClipRect and IntersectClipRect enhanced metafile records.

typedef struct tagEMREXCLUDECLIPRECT
{
    EMR   emr;      // base structure for all record types
    RECTL rclClip;  // clipping rectangle
} EMREXCLUDECLIPRECT,   *PEMREXCLUDECLIPRECT,
  EMRINTERSECTCLIPRECT, *PEMRINTERSECTCLIPRECT;

Members

emr

Base structure for all record types.

rclClip

Clipping rectangle.

ExcludeClipRect, IntersectClipRect


EMREXTCREATEFONTINDIRECTW

The EMREXTCREATEFONTINDIRECTW structure contains members for the CreateFontIndirect enhanced metafile record.

typedef struct tagEMREXTCREATEFONTINDIRECTW
{
    EMR         emr;

    DWORD       ihFont;

    EXTLOGFONTW elfw;

} EMREXTCREATEFONTINDIRECTW,
PEMREXTCREATEFONTINDIRECTW;

Members

emr

Base structure for all record types.

ihFont

Index to the font in handle table.

elfw

Logical font.

See Also

CreateFontIndirect


EMREXTCREATEPEN

The EMREXTCREATEPEN structure contains members for the ExtCreatePen enhanced metafile record. If the record contains a BITMAPINFO structure, it is followed by the bitmap bits that form a packed device-independent bitmap (DIB).

typedef struct tagEMREXTCREATEPEN
{
    EMR       emr;

    DWORD     ihPen;

    DWORD     offBmi;

    DWORD     cbBmi;

    DWORD     offBits;

    DWORD     cbBits;

    EXTLOGPEN elp;

} EMREXTCREATEPEN, *PEMREXTCREATEPEN;

Members

emr

Base structure for all record types.

ihPen

Index to pen in handle table.

offBmi

Offset to BITMAPINFO structure, if any.

cbBmi

Size of BITMAPINFO structure, if any.

offBits

Offset to brush bitmap bits, if any.

cbBits

Size of brush bitmap bits, if any.

elp

Extended logical pen, including the elpStyleEntry member of the EXTLOGPEN structure.

See Also

BITMAPINFO, ExtCreatePen, EXTLOGPEN


EMREXTFLOODFILL

The EMREXTFLOODFILL structure contains members for the ExtFloodFill enhanced metafile record.

typedef struct tagEMREXTFLOODFILL
{
    EMR     emr;

    POINTL  ptlStart;

    COLORREF crColor;

    DWORD   iMode;

} EMREXTFLOODFILL, *PEMREXTFLOODFILL;

Members

emr

Base structure for all record types.

ptlStart

Coordinates where filling begins.

crColor

Color of fill.

iMode

Type of fill operation to be performed. This member must be either the FLOODFILLBORDER or FLOODFILLSURFACE value.

See Also

ExtFloodFill


EMREXTSELECTCLIPRGN

The EMREXTSELECTCLIPRGN structure contains members for the ExtSelectClipRgn enhanced metafile record.

typedef struct tagEMREXTSELECTCLIPRGN
{
    EMR   emr;

    DWORD cbRgnData;

    DWORD iMode;

    BYTE  RgnData[1]; //

} EMREXTSELECTCLIPRGN, *PEMREXTSELECTCLIPRGN;

Members

emr

Base structure for all record types.

cbRgnData

Size of region data, in bytes.

iMode

Operation to be performed. This member must be one of the following values: RGN_AND, RGN_COPY, RGN_DIFF, RGN_OR, or RGN_XOR.

See Also

ExtSelectClipRgn


EMREXTTEXTOUTA, EMREXTTEXTOUTW

The EMREXTTEXTOUTA and EMREXTTEXTOUTW structures contain members for the ExtTextOut, TextOut, or DrawText enhanced metafile records.

typedef struct tagEMREXTTEXTOUTA
{
    EMR     emr;

    RECTL   rclBounds;

    DWORD   iGraphicsMode;

    FLOAT   exScale;

    FLOAT   eyScale;
    EMRTEXT emrtext;

} EMREXTTEXTOUTA, *PEMREXTTEXTOUTA,
  EMREXTTEXTOUTW, *PEMREXTTEXTOUTW;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

iGraphicsMode

Current graphics mode. This member can be either the GM_COMPATIBLE or GM_ADVANCED value.

exScale

X-scaling factor from page units to .01mm units if the graphics mode is the GM_COMPATIBLE value.

eyScale

Y-scaling factor from page units to .01mm units if the graphics mode is the GM_COMPATIBLE value.

emrtext

EMRTEXT structure, which is followed by the string and the intercharacter spacing array.

See Also

DrawText, ExtTextOut, TextOut, EMRTEXT


EMRFILLPATH, EMRSTROKEANDFILLPATH, EMRSTROKEPATH

The EMRFILLPATH, EMRSTROKEANDFILLPATH, and EMRSTROKEPATH structures contain members for the FillPath, StrokeAndFillPath, and StrokePath enhanced metafile records.

typedef struct tagEMRFILLPATH
{
    EMR   emr;

    RECTL rclBounds;

} EMRFILLPATH,          *PEMRFILLPATH,
  EMRSTROKEANDFILLPATH, *PEMRSTROKEANDFILLPATH,
  EMRSTROKEPATH,        *PEMRSTROKEPATH;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

See Also

FillPath, StrokeAndFillPath, StrokePath


EMRFILLRGN

The EMRFILLRGN structure contains members for the FillRgn enhanced metafile record.

typedef struct tagEMRFILLRGN
{
    EMR   emr;

    RECTL rclBounds;

    DWORD cbRgnData;

    DWORD ihBrush;

    BYTE  RgnData[1];

} EMRFILLRGN, *PEMRFILLRGN;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

cbRgnData

Size of region data, in bytes.

ihBrush

Index of brush, in handle table.

RgnData

Buffer containing RGNDATA structure.

See Also

FillRgn, RGNDATA


EMRFORMAT

The EMRFORMAT structure contains information that identifies graphics data in an enhanced metafile. A GDICOMMENT_MULTIFORMATS enhanced metafile public comment contains an array of EMRFORMAT structures.

typedef struct tagEMRFORMAT   {

    DWORD   dSignature;

    DWORD   nVersion;

    DWORD   cbData;

    DWORD   offData;

} EMRFORMAT;

Members

dSignature

Contains a picture format identifier. The following identifier values are defined:

Identifier	Meaning
ENHMETA_SIGNATURE	The picture is in enhanced metafile format.
0x46535045	The picture is in encapsulated PostScript file format.
nVersion

Contains a picture version number. The following version number value is defined:

Version	Meaning
1	This is the version number of a level 1 encapsulated PostScript file.
cbData

Specifies the size, in bytes, of the picture data.

offData

Specifies an offset to the picture data. The offset is figured from the start of the GDICOMMENT_MULTIFORMATS public comment within which this EMRFORMAT structure is embedded. The offset must be a DWORD offset.

Remarks

GdiComment discusses enhanced metafile public comments in general, and the GDICOMMENT_MULTIFORMATS public comment in particular.

See Also

GdiComment


EMRFRAMERGN

The EMRFRAMERGN structure contains members for the FrameRgn enhanced metafile record.

typedef struct tagEMRFRAMERGN
{
    EMR   emr;

    RECTL rclBounds;

    DWORD cbRgnData;

    DWORD ihBrush;

    SIZEL szlStroke;

    BYTE  RgnData[1];

} EMRFRAMERGN, *PEMRFRAMERGN;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

cbRgnData

Size of region data, in bytes.

ihBrush

Index of brush, in handle table.

szlStroke

Width and height of region frame.

RgnData

Buffer containing RGNDATA structure.

See Also

FrameRgn, RGNDATA


EMRGDICOMMENT

The EMRGDICOMMENT structure contains application-specific data. This enhanced metafile record is only meaningful to applications that know the format of the data and how to utilize it. This record is ignored by graphics device interface (GDI) during playback of the enhanced metafile.

typedef struct tagEMRGDICOMMENT
{
    EMR   emr;

    DWORD cbData;

    BYTE  Data[1];

} EMRGDICOMMENT, *PEMRGDICOMMENT;

Members

emr

Base structure for all record types.

cbData

Size of data buffer, in bytes.

Data[1]

Application-specific data.


EMRINVERTRGN, EMRPAINTRGN

The EMRINVERTRGN and EMRPAINTRGN structures contain members for the InvertRgn and PaintRgn enhanced metafile records.

typedef struct tagEMRINVERTRGN
{
    EMR   emr;

    RECTL rclBounds;

    DWORD cbRgnData;

    BYTE  RgnData[1];

} EMRINVERTRGN, *PEMRINVERTRGN,
  EMRPAINTRGN,  *PEMRPAINTRGN;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

cbRgnData

Size of region data, in bytes.

RgnData

Buffer containing RGNDATA structure.

See Also

InvertRgn, PaintRgn


EMRLINETO, EMRMOVETOEX

The EMRLINETO and EMRMOVETOEX structures contains members for the LineTo and MoveToEx enhanced metafile records.

typedef struct tagEMRLINETO
{
    EMR    emr;

    POINTL ptl;

} EMRLINETO,   *PEMRLINETO,
  EMRMOVETOEX, *PEMRMOVETOEX;

Members

emr

Base structure for all record types.

ptl

Coordinates of the line’s ending point for the LineTo function or coordinates of the new current position for the MoveToEx function.

See Also

LineTo, MoveToEx


EMRMASKBLT

The EMRMASKBLT structure contains members for the MaskBlt enhanced metafile record. Note that graphics device interface (GDI) converts the device-dependent bitmap into a device-independent bitmap (DIB) before storing it in the metafile record.

typedef struct tagEMRMASKBLT
{
    EMR     emr;

    RECTL   rclBounds;

    LONG    xDest;

    LONG    yDest;

    LONG    cxDest;

    LONG    cyDest;

    DWORD   dwRop;

    LONG    xSrc;

    LONG    ySrc;

    XFORM   xformSrc;

    COLORREF crBkColorSrc;

    DWORD   iUsageSrc;

    DWORD   offBmiSrc;

    DWORD   cbBmiSrc;

    DWORD   offBitsSrc;

    DWORD   cbBitsSrc;

    LONG    xMask;

    LONG    yMask;

    DWORD   iUsageMask;

    DWORD   offBmiMask;

    DWORD   cbBmiMask;

    DWORD   offBitsMask;

    DWORD   cbBitsMask;

} EMRMASKBLT, *PEMRMASKBLT;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

xDest

Logical x-coordinate of the upper-left corner of the destination rectangle.

yDest

Logical y-coordinate of the upper-left corner of the destination rectangle.

cxDest

Logical width of destination rectangle

cyDest

Logical height of destination rectangle

dwRop

Raster-operation code. These codes define how the color data of the source rectangle is to be combined with the color data of the destination rectangle to achieve the final color.

xSrc

Logical x-coordinate of the upper-left corner of the source rectangle.

ySrc

Logical y-coordinate of the upper-left corner of the source rectangle.

xformSrc

World-space to page-space transformation of the source device context.

crBkColorSrc

Background color (the RGB value) of the source device context.

iUsageSrc

Value of the bmiColors member of the source BITMAPINFO structure. The iUsageSrc member can be either the DIB_PAL_COLORS, DIB_PAL_INDICES, or DIB_RGB_COLORS value.

offBmiSrc

Offset to source BITMAPINFO structure.

cbBmiSrc

Size of source BITMAPINFO structure.

offBitsSrc

Offset to source bitmap bits.

cbBitsSrc

Size of source bitmap bits.

xMask

Horizontal pixel offset into mask bitmap

yMask

Vertical pixel offset into mask bitmap

iUsageMask

Value of the bmiColors member of the mask BITMAPINFO structure.

offBmiMask

Offset to mask BITMAPINFO structure.

cbBmiMask

Size of mask BITMAPINFO structure.

offBitsMask

Offset to mask bitmap bits.

cbBitsMask

Size of mask bitmap bits.

See Also

BITMAPINFO, MaskBlt, RGB


EMRMODIFYWORLDTRANSFORM

The EMRMODIFYWORLDTRANSFORM structure contains members for the ModifyWorldTransform enhanced metafile record.

typedef struct tagEMRMODIFYWORLDTRANSFORM
{
    EMR   emr;

    XFORM xform;

    DWORD iMode;

transformation
} EMRMODIFYWORLDTRANSFORM,
PEMRMODIFYWORLDTRANSFORM;

Members

emr

Base structure for all record types.

xform

World-space to page-space transformation data.

iMode

Value specifying how the transformation data modifies the current world transformation. This member can be one of the following values: MWT_IDENTITY, MWT_LEFTMULTIPLY, or MWT_RIGHTMULTIPLY.

See Also

ModifyWorldTransform


EMROFFSETCLIPRGN

The EMROFFSETCLIPRGN structure contains members for the OffsetClipRgn enhanced metafile record.

typedef struct tagEMROFFSETCLIPRGN
{
    EMR    emr;

    POINTL ptlOffset;

} EMROFFSETCLIPRGN, *PEMROFFSETCLIPRGN;

Members

emr

Base structure for all record types.

ptlOffset

Logical coordinates of offset.

See Also

OffsetClipRgn


EMRPLGBLT

The EMRPLGBLT structure contains members for the PlgBlt enhanced metafile record. Note that graphics device interface (GDI) converts the device-dependent bitmap into a device-independent bitmap (DIB) before storing it in the metafile record.

typedef struct tagEMRPLGBLT
{
    EMR      emr;

    RECTL    rclBounds;

    POINTL   aptlDest[3];

    LONG    xSrc;

    LONG    ySrc;

    LONG     cxSrc;

    LONG     cySrc;

    XFORM   xformSrc;

    COLORREF crBkColorSrc;

    DWORD    iUsageSrc;

    DWORD    offBmiSrc;

    DWORD   cbBmiSrc;

    DWORD   offBitsSrc;

    DWORD   cbBitsSrc;

    LONG    xMask;
    LONG    yMask;

    DWORD   iUsageMask;

    DWORD   offBmiMask;

    DWORD   cbBmiMask;
    DWORD   offBitsMask;
    DWORD   cbBitsMask;
} EMRPLGBLT, *PEMRPLGBLT;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

aptlDest

Array of three points in logical space that identify three corners of the destination parallelogram. The upper-left corner of the source rectangle is mapped to the first point in this array, the upper-right corner to the second point in this array, and the lower-left corner to the third point. The lower-right corner of the source rectangle is mapped to the implicit fourth point in the parallelogram.

xSrc

Logical x-coordinate of the upper-left corner of the source rectangle.

ySrc

Logical y-coordinate of the upper-left corner of the source rectangle.

cxSrc

Logical width of source

cySrc

Logical height of source

xformSrc

World-space to page-space transformation of the source device context.

crBkColorSrc

Background color (the RGB value) of the source device context.

iUsageSrc

Value of the bmiColors member of the BITMAPINFO structure. The iUsageSrc member can be either the DIB_PAL_COLORS, DIB_PAL_INDICES, or DIB_RGB_COLORS value.

offBmiSrc

Offset to source BITMAPINFO structure.

cbBmiSrc

Size of source BITMAPINFO structure.

offBitsSrc

Offset to source bitmap bits.

cbBitsSrc

Size of source bitmap bits.

xMask

Horizontal pixel offset into mask bitmap.

yMask

Vertical pixel offset into mask bitmap.

iUsageMask

Value of the bmiColors member of the mask BITMAPINFO structure.

offBmiMask

Offset to mask BITMAPINFO structure.

cbBmiMask

Size of mask BITMAPINFO structure.

offBitsMask

Offset to mask bitmap bits.

cbBitsMask

Size of mask bitmap bits.

See Also

BITMAPINFO, PlgBlt, RGB


EMRPOLYDRAW

The EMRPOLYDRAW structure contains members for the PolyDraw enhanced metafile record.

typedef struct tagEMRPOLYDRAW
{
    EMR    emr;

    RECTL  rclBounds;

    DWORD  cptl;

    POINTL aptl[1];

    BYTE   abTypes[1];

} EMRPOLYDRAW, *PEMRPOLYDRAW;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

cptl

Number of points.

aptl

Array of 32-bit points.

abTypes

Array of values that specifies how each point in the aptl array is used. This member can be one of the following values: PT_MOVETO, PT_LINETO, or PT_BEZIERTO. The PT_LINETO or PT_BEZIERTO value can be combined with the PT_CLOSEFIGURE value by using the bitwise-xOR operator.

See Also

PolyDraw


EMRPOLYDRAW16

The EMRPOLYDRAW16 structure contains members for the PolyDraw enhanced metafile record.

typedef struct tagEMRPOLYDRAW16
{
    EMR    emr;

    RECTL  rclBounds;

    DWORD  cpts;

    POINTS apts[1];

    BYTE   abTypes[1];

} EMRPOLYDRAW16, *PEMRPOLYDRAW16;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

cpts

Number of points.

apts

Array of 16-bit points.

abTypes

Array of values that specifies how each point in the apts array is used. This member can be one of the following values: PT_MOVETO, PT_LINETO, or PT_BEZIERTO. The PT_LINETO or PT_BEZIERTO value can be combined with the PT_CLOSEFIGURE value by using the bitwise-OR operator.

See Also

PolyDraw


EMRPOLYLINE, EMRPOLYBEZIER, EMRPOLYGON, EMRPOLYBEZIERTO, EMRPOLYLINETO

The EMRPOLYLINE, EMRPOLYBEZIER, EMRPOLYGON, EMRPOLYBEZIERTO, and EMRPOLYLINETO structures contain members for the Polyline, PolyBezier, Polygon, PolyBezierTo, and PolylineTo enhanced metafile records.

typedef struct tagEMRPOLYLINE
{
    EMR    emr;
    RECTL  rclBounds;

    DWORD  cptl;

    POINTL aptl[1];

} EMRPOLYLINE,     *PEMRPOLYLINE,
  EMRPOLYBEZIER,   *PEMRPOLYBEZIER,
  EMRPOLYGON,      *PEMRPOLYGON,
  EMRPOLYBEZIERTO, *PEMRPOLYBEZIERTO,
  EMRPOLYLINETO,   *PEMRPOLYLINETO;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

cptl

Number of points array.

aptl

Array of 32-bit points.

See Also

PolyBezier, PolyBezierTo, Polygon, Polyline, PolylineTo


EMRPOLYLINE16, EMRPOLYBEZIER16, EMRPOLYGON16, EMRPOLYBEZIERTO16, EMRPOLYLINETO16

The EMRPOLYLINE16, EMRPOLYBEZIER16, EMRPOLYGON16, EMRPOLYBEZIERTO16, and EMRPOLYLINETO16 structures contain members for the Polyline, PolyBezier, Polygon, PolyBezierTo, and PolylineTo enhanced metafile records.

typedef struct tagEMRPOLYLINE
{
    EMR    emr;

    RECTL  rclBounds;

    DWORD  cpts;

    POINTL apts[1];

} EMRPOLYLINE16,     *PEMRPOLYLINE16,
  EMRPOLYBEZIER16,   *PEMRPOLYBEZIER16,
  EMRPOLYGON16,      *PEMRPOLYGON16,
  EMRPOLYBEZIERTO16, *PEMRPOLYBEZIERTO16,
  EMRPOLYLINETO16,   *PEMRPOLYLINETO16;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

cpts

Number of points in the array.

apts

Array of 16-bit points.

See Also

PolyBezier, PolyBezierTo, Polygon, Polyline, PolylineTo


EMRPOLYPOLYLINE, EMRPOLYPOLYGON

The EMRPOLYPOLYLINE and EMRPOLYPOLYGON structures contain members for the PolyPolyline and PolyPolygon enhanced metafile records.

typedef struct tagEMRPOLYPOLYLINE
{
    EMR     emr;

    RECTL   rclBounds;

    DWORD   nPolys;

    DWORD   cptl;

    DWORD   aPolyCounts[1];

    POINTL  aptl[1];

} EMRPOLYPOLYLINE, *PEMRPOLYPOLYLINE,
  EMRPOLYPOLYGON,  *PEMRPOLYPOLYGON;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

nPolys

Number of polys.

cpt1

Total number of points in all polys.

aPolyCounts

Array of point counts for each poly.

aptl

Array of 32-bit points.

See Also

PolyPolyline, PolyPolygon


EMRPOLYPOLYLINE16, EMRPOLYPOLYGON16

The EMRPOLYPOLYLINE16 and EMRPOLYPOLYGON16 structures contain members for the PolyPolyline and PolyPolygon enhanced metafile records.

typedef struct tagEMRPOLYPOLYLINE16
{
    EMR     emr;

    RECTL   rclBounds;
    DWORD   nPolys;

    DWORD   cpts;

    DWORD   aPolyCounts[1];

    POINTS  apts[1];

} EMRPOLYPOLYLINE16, *PEMRPOLYPOLYLINE16,
  EMRPOLYPOLYGON16,  *PEMRPOLYPOLYGON16;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

nPolys

Number of polys.

cpt1

Total number of points in all polys.

aPolyCounts

Array of point counts for each poly.

aptl

Array of 16-bit points.

See Also

PolyPolyline, PolyPolygon


EMRPOLYTEXTOUTA, EMRPOLYTEXTOUTW

The EMRPOLYTEXTOUTA and EMRPOLYTEXTOUTW structures contain members for the PolyTextOut enhanced metafile record.

typedef struct tagEMRPOLYTEXTOUTA
{
    EMR     emr;

    RECTL   rclBounds;

    DWORD   iGraphicsMode;

    FLOAT   exScale;

    FLOAT   eyScale;

    LONG    cStrings;

    EMRTEXT aemrtext[1];

} EMRPOLYTEXTOUTA, *PEMRPOLYTEXTOUTA,
  EMRPOLYTEXTOUTW, *PEMRPOLYTEXTOUTW;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

iGraphicsMode

Current graphics mode. This member can be either the GM_COMPATIBLE or GM_ADVANCED value.

exScale

X-scaling factor from page units to .01mm units if the graphics mode is the GM_COMPATIBLE value.

eyScale

Y-scaling factor from page units to .01mm units if the graphics mode is the GM_COMPATIBLE value.

cStrings

Number of strings.

aemrtext

EMRTEXT structure, which is followed by the string and the intercharacter spacing array.

See Also

EMRTEXT


EMRRESIZEPALETTE

The EMRRESIZEPALETTE structure contains members for the ResizePalette enhanced metafile record.

typedef struct tagEMRRESIZEPALETTE
{
    EMR   emr;

    DWORD ihPal;

    DWORD cEntries;

} EMRRESIZEPALETTE, *PEMRRESIZEPALETTE;

Members

emr

Base structure for all record types.

ihPal

Index of palette in handle table.

cEntries

Number of entries in palette after resizing.

See Also

ResizePalette


EMRRESTOREDC

The EMRRESTOREDC structure contains members for the RestoreDC enhanced metafile record.

typedef struct tagEMRRESTOREDC
{
    EMR  emr;

    LONG iRelative;

} EMRRESTOREDC, *PEMRRESTOREDC;

Members

emr

Base structure for all record types.

iRelative

Relative instance to restore.

See Also

RestoreDC


EMRROUNDRECT

The EMRROUNDRECT structure contains members for the RoundRect enhanced metafile record.

typedef struct tagEMRROUNDRECT
{
    EMR   emr;

    RECTL rclBox;

    SIZEL szlCorner;

} EMRROUNDRECT, *PEMRROUNDRECT;

Members

emr

Base structure for all record types.

szlCorner

Width and height of the ellipse used to draw rounded corners.

See Also

RoundRect


EMRSCALEVIEWPORTEXTEX, EMRSCALEWINDOWEXTEX

The EMRSCALEVIEWPORTEXTEX and EMRSCALEWINDOWEXTEX structures contain members for the ScaleViewportExtEx and ScaleWindowExtEx enhanced metafile records.

typedef struct tagEMRSCALEVIEWPORTEXTEX
{
    EMR  emr;

    LONG xNum;

    LONG xDenom;

    LONG yNum;

    LONG yDenom;

} EMRSCALEVIEWPORTEXTEX, *PEMRSCALEVIEWPORTEXTEX,

  EMRSCALEWINDOWEXTEX,   *PEMRSCALEWINDOWEXTEX;

Members

emr

Base structure for all record types.

xNum

Horizontal multiplicand.

xDenom

Horizontal divisor.

yNum

Vertical multiplicand.

yDenom

Vertical divisor.

See Also

ScaleViewportExtEx, ScaleWindowExtEx


EMRSELECTCOLORSPACE, EMRDELETECOLORSPACE

The EMRSELECTCOLORSPACE and EMRDELETECOLORSPACE structures contain members for the SelectColorSpace and DeleteColorSpace enhanced metafile records.

typedef struct tagEMRSELECTCOLORSPACE

{

    EMR     emr;

    DWORD   ihCS;

} EMRSELECTCOLORSPACE, *PEMRSELECTCOLORSPACE,
  EMRDELETECOLORSPACE, *PEMRDELETECOLORSPACE;

Members

emr

Base structure for all record types.

ihCS

Color space handle index.

See Also

DeleteColorSpace


EMRSELECTOBJECT, EMRDELETEOBJECT

The EMRSELECTOBJECT and EMRDELETEOBJECT structures contain members for the SelectObject and DeleteObject enhanced metafile records.

typedef struct tagEMRSELECTOBJECT
{
    EMR   emr;

    DWORD ihObject;
} EMRSELECTOBJECT, *PEMRSELECTOBJECT,
  EMRDELETEOBJECT, *PEMRDELETEOBJECT;

Members

emr

Base structure for all record types.

ihObject

Index of object in handle table.

See Also

SelectObject, DeleteObject


EMRSELECTPALETTE

The EMRSELECTPALETTE structure contains members for the SelectPalette enhanced metafile record. Note that the bForceBackground parameter in SelectPalette is always recorded as TRUE, which causes the palette to be realized as a background palette.

typedef struct tagEMRSELECTPALETTE

{
    EMR   emr;

    DWORD ihPal;

} EMRSELECTPALETTE, *PEMRSELECTPALETTE;

Members

emr

Base structure for all record types.

ihPal

Index to logical palette in handle table.

See Also

SelectPalette


EMRSETARCDIRECTION

The EMRSETARCDIRECTION structure contains members for the SetArcDirection enhanced metafile record.

typedef struct tagEMRSETARCDIRECTION
{
    EMR   emr;

    DWORD iArcDirection;
} EMRSETARCDIRECTION, *PEMRSETARCDIRECTION;

Members

emr

Base structure for all record types.

iArcDirection

Arc direction. This member can be either the AD_CLOCKWISE or AD_COUNTERCLOCKWISE value.

See Also

Arc, SetArcDirection


EMRSETBKCOLOR, EMRSETTEXTCOLOR

The EMRSETBKCOLOR and EMRSETTEXTCOLOR structures contain members for the SetBkColor and SetTextColor enhanced metafile records.

typedef struct tagEMRSETTEXTCOLOR
{
    EMR      emr;

    COLORREF crColor;

} EMRSETBKCOLOR,   *PEMRSETBKCOLOR,
  EMRSETTEXTCOLOR, *PEMRSETTEXTCOLOR;

Members

emr

Base structure for all record types.

crColor

Color value.

See Also

SetBkColor, SetTextColor


EMRSETCOLORADJUSTMENT

The EMRSETCOLORADJUSTMENT structure contains members for the SetColorAdjustment enhanced metafile record.

typedef struct tagEMRSETCOLORADJUSTMENT
{
    EMR  emr;

    COLORADJUSTMENT ColorAdjustment;

} EMRSETCOLORADJUSTMENT, *PEMRSETCOLORADJUSTMENT;

Members

emr

Base structure for all record types.

ColorAdjustment

COLORADJUSTMENT structure.

See Also

SetColorAdjustment


EMRSETDIBITSTODEVICE

The EMRSETDIBITSTODEVICE structure contains members for the SetDIBitsToDevice enhanced metafile record.

typedef struct tagEMRSETDIBITSTODEVICE
{
    EMR   emr;

    RECTL rclBounds;

    LONG  xDest;

    LONG  yDest;

    LONG  xSrc;

    LONG  ySrc;

    LONG  cxSrc;

    LONG  cySrc;

    DWORD offBmiSrc;

    DWORD cbBmiSrc;

    DWORD offBitsSrc;

    DWORD cbBitsSrc;

    DWORD iUsageSrc;

    DWORD iStartScan;

    DWORD cScans;

} EMRSETDIBITSTODEVICE, *PEMRSETDIBITSTODEVICE;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

xDest

Logical x-coordinate of the upper-left corner of the destination rectangle.

yDest

Logical y-coordinate of the upper-left corner of the destination rectangle.

xSrc

Logical x-coordinate of the lower-left corner of the source device-independent bitmap (DIB).

ySrc

Logical y-coordinate of the lower-left corner of the source DIB.

cxSrc

Width of source rectangle.

cyScr

Height of source rectangle.

offBmiSrc

Offset to source BITMAPINFO structure.

cbBmiSrc

Size of source BITMAPINFO structure.

offBitsSrc

Offset to source bitmap bits.

cbBitsSrc

Size of source bitmap bits.

iUsageSrc

Value of the bmiColors member of the BITMAPINFO structure. The iUsageSrc member can be either the DIB_PAL_COLORS, DIB_PAL_INDICES, or DIB_RGB_COLORS value.

iStartScan

First scan line in array.

cScans

Number of scan lines.

See Also

BITMAPINFO, SetDIBitsToDevice


EMRSETMAPPERFLAGS

The EMRSETMAPPERFLAGS structure contains members for the SetMapperFlags enhanced metafile record.

typedef struct tagEMRSETMAPPERFLAGS
{
    EMR   emr;

    DWORD dwFlags;

} EMRSETMAPPERFLAGS, *PEMRSETMAPPERFLAGS;

Members

emr

Base structure for all record types.

dwFlags

Font mapper flag.

See Also

SetMapperFlags


EMRSETMITERLIMIT

The EMRSETMITERLIMIT structure contains members for the SetMiterLimit enhanced metafile record.

typedef struct tagEMRSETMITERLIMIT
{
    EMR   emr;
    FLOAT eMiterLimit;

} EMRSETMITERLIMIT, *PEMRSETMITERLIMIT;

Members

emr

Base structure for all record types.

eMiterLimit

New miter limit.

See Also

SetMiterLimit


EMRSETPALETTEENTRIES

The EMRSETPALETTEENTRIES structure contains members for the SetPaletteEntries enhanced metafile record.

typedef struct tagEMRSETPALETTEENTRIES
{
    EMR          emr;

    DWORD        ihPal;

    DWORD        iStart;

    DWORD        cEntries;

    PALETTEENTRY aPalEntries[1];

} EMRSETPALETTEENTRIES, *PEMRSETPALETTEENTRIES;

Members

emr

Base structure for all record types.

ihPal

Palette handle index.

iStart

Index of first entry to set.

cEntries

Number of entries.

aPalEntries

Array of PALETTEENTRY structures. Note that peFlags members in the structures do not contain any flags.

See Also

PALETTEENTRY, SetPaletteEntries


EMRSETPIXELV

The EMRSETPIXELV structure contains members for the SetPixelV enhanced metafile record. When an enhanced metafile is created, calls to SetPixel are also recorded in this record.

typedef struct tagEMRSETPIXELV
{
    EMR     emr;

    POINTL  ptlPixel;

    COLORREF crColor;

} EMRSETPIXELV, *PEMRSETPIXELV;

Members

emr

Base structure for all record types.

ptlPixel

Logical coordinates of pixel.

crColor

Color value.

See Also

SetPixelV, SetPixel


EMRSETVIEWPORTEXTEX, EMRSETWINDOWEXTEX

The EMRSETVIEWPORTEXTEX and EMRSETWINDOWEXTEX structures contains members for the SetViewportExtEx and SetWindowExtEx enhanced metafile records.

typedef struct tagEMRSETVIEWPORTEXTEX
{
    EMR   emr;

    SIZEL szlExtent;

} EMRSETVIEWPORTEXTEX, *PEMRSETVIEWPORTEXTEX,
  EMRSETWINDOWEXTEX,   *PEMRSETWINDOWEXTEX;

Members

emr

Base structure for all record types.

szlExtent

Horizontal and vertical extents. For SetViewportExtEx, the extents are in device units, and for SetWindowExtEx, the extents are in logical units.

See Also

SetViewportExtEx, SetWindowExtEx


EMRSETVIEWPORTORGEX, EMRSETWINDOWORGEX, EMRSETBRUSHORGEX

The EMRSETVIEWPORTORGEX, EMRSETWINDOWORGEX, and EMRSETBRUSHORGEX structures contain members for the SetViewportOrgEx, SetWindowOrgEx, and SetBrushOrgEx enhanced metafile records.

typedef struct tagEMRSETVIEWPORTORGEX
{
    EMR    emr;

    POINTL ptlOrigin;

} EMRSETVIEWPORTORGEX, *PEMRSETVIEWPORTORGEX,
  EMRSETWINDOWORGEX,   *PEMRSETWINDOWORGEX,
  EMRSETBRUSHORGEX,    *PEMRSETBRUSHORGEX;

Members

emr

Base structure for all record types.

ptlOrigin

Coordinate of origin.

See Also

SetBrushOrgEx, SetViewportOrgEx, SetWindowOrgEx


EMRSETWORLDTRANSFORM

The EMRSETWORLDTRANSFORM structure contains members for the SetWorldTransform enhanced metafile record.

typedef struct tagEMRSETWORLDTRANSFORM
{
    EMR   emr;

    XFORM xform;

} EMRSETWORLDTRANSFORM, *PEMRSETWORLDTRANSFORM;

Members

emr

Base structure for all record types.

xform

World-space to page-space transformation data.

See Also

SetWorldTransform


EMRSTRETCHBLT

The EMRSTRETCHBLT structure contains members for the StretchBlt enhanced metafile record. Note that graphics device interface (GDI) converts the device-dependent bitmap into a device-independent bitmap (DIB) before storing it in the metafile record.

typedef struct tagEMRSTRETCHBLT
{
    EMR      emr;

    RECTL    rclBounds;

    LONG     xDest;

    LONG     yDest;

    LONG     cxDest;

    LONG     cyDest;

    DWORD    dwRop;

    LONG     xSrc;

    LONG     ySrc;

    XFORM    xformSrc;

    COLORREF crBkColorSrc;

    DWORD    iUsageSrc;

    DWORD    offBmiSrc;

    DWORD    cbBmiSrc;

    DWORD    offBitsSrc;

    DWORD    cbBitsSrc;

    LONG     cxSrc;

    LONG     cySrc;

} EMRSTRETCHBLT, *PEMRSTRETCHBLT;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

xDest

Logical x-coordinate of the upper-left corner of the destination rectangle.

yDest

Logical y-coordinate of the upper-left corner of the destination rectangle.

cxDest

Logical width of destination rectangle

cyDest

Logical height of destination rectangle

dwRop

Raster-operation code. These codes define how the color data of the source rectangle is to be combined with the color data of the destination rectangle to achieve the final color.

xSrc

Logical x-coordinate of the upper-left corner of the source rectangle.

ySrc

Logical y-coordinate of the upper-left corner of the source rectangle.

xformSrc

World-space to page-space transformation of the source device context.

crBkColorSrc

Background color (the RGB value) of the source device context.

iUsageSrc

Value of the bmiColors member of the BITMAPINFO structure. The iUsageSrc member can be either the DIB_PAL_COLORS, DIB_PAL_INDICES, or DIB_RGB_COLORS value.

offBmiSrc

Offset to source BITMAPINFO structure.

cbBmiSrc

Size of source BITMAPINFO structure.

offBitsSrc

Offset to source bitmap bits.

cbBitsSrc

Size of source bitmap bits.

cxSrc

Width of source rectangle.

cySrc

Height of source rectangle.

See Also

BITMAPINFO, RGB, StretchBlt


EMRSTRETCHDIBITS

The EMRSTRETCHDIBITS structure contains members for the StretchDIBits enhanced metafile record.

typedef struct tagEMRSTRETCHDIBITS
{
    EMR   emr;
    RECTL rclBounds;

    LONG  xDest;

    LONG  yDest;

    LONG  xSrc;

    LONG  ySrc;

    LONG  cxSrc;

    LONG  cySrc;
    DWORD offBmiSrc;
    DWORD cbBmiSrc;

    DWORD offBitsSrc;

    DWORD cbBitsSrc;

    DWORD iUsageSrc;

    DWORD dwRop;

    LONG  cxDest;

    LONG  cyDest;

} EMRSTRETCHDIBITS, *PEMRSTRETCHDIBITS;

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

xDest

Logical x-coordinate of the upper-left corner of the destination rectangle.

yDest

Logical y-coordinate of the upper-left corner of the destination rectangle.

xSrc

Logical x-coordinate of the upper-left corner of the source rectangle.

ySrc

Logical y-coordinate of the upper-left corner of the source rectangle.

cxSrc

Width of source rectangle.

cyScr

Height of source rectangle.

offBmiSrc

Offset to source BITMAPINFO structure.

cbBmiSrc

Size of source BITMAPINFO structure.

offBitsSrc

Offset to source bitmap bits.

cbBitsSrc

Size of source bitmap bits.

iUsageSrc

Value of the bmiColors member of the BITMAPINFO structure. The iUsageSrc member can be either the DIB_PAL_COLORS, DIB_PAL_INDICES, or DIB_RGB_COLORS value.

dwRop

Raster-operation code. These codes define how the color data of the source rectangle is to be combined with the color data of the destination rectangle to achieve the final color.

cxDest

Logical width of destination rectangle

cyDest

Logical height of destination rectangle

See Also

BITMAPINFO, StretchDIBits


EMRTEXT

The EMRTEXT structure contains members for text output.

typedef struct tagEMRTEXT

{
    POINTL ptlReference;

    DWORD  nChars;

    DWORD  offString;

    DWORD  fOptions;

    RECTL  rcl;

    DWORD  offDx;

} EMRTEXT, *PEMRTEXT;

Members

ptlReference

Logical coordinates of the reference point used to position the string.

nChars

Number of characters in string.

offString

Offset to string.

fOptions

Value specifying how to use the application-defined rectangle. This member can be a combination of the ETO_CLIPPED and ETO_OPAQUE values.

rcl

Optional clipping and/or opaquing rectangle.

offDx

Offset to intercharacter spacing array.

Remarks

The EMRTEXT structure is used as a member in the EMREXTTEXTOUT and EMRPOLYTEXTOUT structures.


Enhanced Metafile Records with No Parameters

typedef struct tagABORTPATH

{

    EMR emr;

} EMRABORTPATH,      *PEMRABORTPATH,
  EMRBEGINPATH,      *PEMRBEGINPATH,
  EMRENDPATH,        *PEMRENDPATH,
  EMRCLOSEFIGURE,    *PEMRCLOSEFIGURE,
  EMRFLATTENPATH,    *PEMRFLATTENPATH,
  EMRWIDENPATH,      *PEMRWIDENPATH,
  EMRSETMETARGN,     *PEMRSETMETARGN,
  EMRSAVEDC,         *PEMRSAVEDC,
  EMRREALIZEPALETTE, *PEMRREALIZEPALETTE;

Contains data for the AbortPath, BeginPath, EndPath, CloseFigure, FlattenPath, WidenPath, SetMetaRgn, SaveDC, and RealizePalette enhanced metafile records.


Enhanced Metafile Records with One Parameter

Contains parameters for the SelectClipPath, SetBkMode, SetPolyFillMode, SetROP2, SetStretchBltMode, SetTextAlign, and EnableICM enhanced metafile records.

typedef struct tagEMRSELECTCLIPPATH
{
    EMR   emr;

    DWORD iMode;

} EMRSELECTCLIPPATH,    *PEMRSELECTCLIPPATH,
  EMRSETBKMODE,         *PEMRSETBKMODE,
  EMRSETMAPMODE,        *PEMRSETMAPMODE,
  EMRSETPOLYFILLMODE,   *PEMRSETPOLYFILLMODE,
  EMRSETROP2,           *PEMRSETROP2,
  EMRSETSTRETCHBLTMODE, *PEMRSETSTRETCHBLTMODE,
  EMRSETTEXTALIGN,	      *PEMRSETTEXTALIGN,
  EMRENABLEICM, 	       *PEMRENABLEICM

Members

emr

Base structure for all record types.

iMode

Value and meaning that varies depending on the function contained in the enhanced metafile record. For a description of this member, see the documentation of the functions contained in this record .

See Also

SelectClipPath, SetBkMode, SetPolyFillMode, SetROP2, SetStretchBltMode, SetTextAlign


ENCORRECTTEXT

Contains information about the selected text to be corrected.

typedef struct _encorrecttext {
    NMHDR nmhdr;     // notification header
    CHARRANGE chrg;  // current selection
    WORD seltyp;     // selection type
} ENCORRECTTEXT;

Members

seltyp

Value specifying the contents of the new selection. This member is SEL_EMPTY if the selection is empty or one or more of the following values:

Value	Meaning
SEL_TEXT	Text
SEL_OBJECT	At least one OLE object
SEL_MULTICHAR	More than one character of text
SEL_MULTIOBJECT	More than one OLE object


ENDROPFILES

The ENDDROPFILES structure contains information associated with an EN_DROPFILES notification message. A rich edit control sends this notification message when it receives a WM_DROPFILES message.

typedef struct _endropfiles {

    NMHDR nmhdr;

    HANDLE hDrop;

    LONG cp;

    BOOL fProtected;

} ENDROPFILES;

Members

nmhdr

Notification header.

hDrop

Handle to the dropped files list (same as with WM_DROPFILES). This handle is used with the DragFinish, DragQueryFile, and DragQueryPoint functions.

cp

Character position at which the dropped files would be inserted.

fProtected

Boolean value specifying whether the specified character position is protected (TRUE) or not protected (FALSE).

See Also

DragFinish, DragQueryFile, DragQueryPoint, EN_DROPFILES, WM_DROPFILES


ENHMETAHEADER

The ENHMETAHEADER structure contains enhanced-metafile data such as the dimensions of the picture stored in the enhanced metafile, the count of records in the enhanced metafile, the resolution of the device on which the picture was created, and so on.

This structure is always the first record in an enhanced metafile.

typedef struct tagENHMETAHEADER { // enmh

    DWORD iType;

    DWORD nSize;

    RECTL rclBounds;

    RECTL rclFrame;

    DWORD dSignature;

    DWORD nVersion;

    DWORD nBytes;

    DWORD nRecords;

    WORD  nHandles;

    WORD  sReserved;

    DWORD nDescription;

    DWORD offDescription;

    DWORD nPalEntries;

    SIZEL szlDevice;

    SIZEL szlMillimeters;

    DWORD cbPixelFormat;

    DWORD offPixelFormat;

    DWORD bOpenGL;

} ENHMETAHEADER;

Members

iType

Specifies the record type. This member must specify the value assigned to the EMR_HEADER constant.

nSize

Specifies the structure size, in bytes.

rclBounds

Specifies the dimensions, in device units, of the smallest rectangle that can be drawn around the picture stored in the metafile. This rectangle is supplied by graphics device interface (GDI). Its dimensions include the right and bottom edges.

rclFrame

Specifies the dimensions, in .01 millimeter units, of a rectangle that surrounds the picture stored in the metafile. This rectangle must be supplied by the application that creates the metafile. Its dimensions include the right and bottom edges.

dSignature

Specifies a doubleword signature. This member must specify the value assigned to the ENHMETA_SIGNATURE constant.

nVersion

Specifies the metafile version. The current version value is 0x10000.

nBytes

Specifies the size of the enhanced metafile, in bytes.

nRecords

Specifies the number of records in the enhanced metafile.

nHandles

Specifies the number of handles in the enhanced-metafile handle table. (Index zero in this table is reserved.)

sReserved

Reserved; must be zero.

nDescription

Specifies the number of characters in the array that contains the description of the enhanced metafile’s contents. This member should be set to zero if the enhanced metafile does not contain a description string.

offDescription

Specifies the offset from the beginning of the ENHMETAHEADER structure to the array that contains the description of the enhanced metafile’s contents. This member should be set to zero if the enhanced metafile does not contain a description string.

nPalEntries

Specifies the number of entries in the enhanced metafile’s palette.

szlDevice

Specifies the resolution of the reference device, in pixels.

szlMillimeters

Specifies the resolution of the reference device, in millimeters.

cbPixelFormat

Specifies the size of the last recorded pixel format in a metafile. If a pixel format is set in a reference DC at the start of recording, cbPixelFormat is set to the size of the PIXELFORMATDESCRIPTOR. When no pixel format is set when a metafile is recorded, this member is set to zero. If more than a single pixel format is set, the header points to the last pixel format.

offPixelFormat

Specifies the offset of pixel format used when recording a metafile. If a pixel format is set in a reference DC at the start of recording or during recording, offPixelFormat is set to the offset of the PIXELFORMATDESCRIPTOR in the metafile. When no pixel format is set when a metafile is recorded, this member is set to zero. If more than a single pixel format is set, the header points to the last pixel format.

bOpenGL

Specifies whether any OpenGL records are present in a metafile. bOpenGL is a simple Boolean flag that you can use to determine whether an enhanced metafile requires OpenGL handling. When a metafile contains OpenGL records, bOpenGL is TRUE; otherwise it is FALSE.

See Also

ENHMETARECORD


ENHMETARECORD

The ENHMETARECORD structure contains data that describes a graphics device interface (GDI) function used to create part of a picture in an enhanced-format metafile.

typedef struct tagENHMETARECORD { // enmr

    DWORD iType;

    DWORD nSize;

    DWORD dParm[1];

} ENHMETARECORD;

Members

iType

Specifies the record type.

nSize

Specifies the size of the record, in bytes.

dParm

Specifies an array of parameters passed to the GDI function identified by the record.

See Also

ENHMETAHEADER


ENOLEOPFAILED

Contains information about a failed OLE operation.

typedef struct {
    NMHDR nmhdr;
    LONG iob;
    LONG lOper;
    HRESULT hr;
} ENOLEOPFAILED;

Members

nmhdr

Notification header.

iob

Object index.

lOper

OLE operation that failed. This can be OLEOP_DOVERB to indicate that IOleObject::DoVerb failed.

hr

Error code returned by the object on the operation.

See Also

EN_OLEOPFAILED, IOleObject::DoVerb


ENPROTECTED

The ENPROTECTED structure contains information associated with an EN_PROTECTED notification message. A rich edit control sends this notification when the user attempts to edit protected text.

typedef struct _enprotected {

    NMHDR nmhdr;

    _WPAD _wPad1;

    UINT msg;

    _WPAD _wPad2;

    WPARAM wParam;

    LPARAM lParam;

    CHARRANGE chrg;

} ENPROTECTED;

Members

nmhdr

Notification header.

msg

Message that triggered the notification.

wParam

wParam parameter of the message.

lParam

lParam parameter of the message.

chrg

Current selection.

See Also

EN_PROTECTED


ENSAVECLIPBOARD

Contains information about objects and text on the clipboard.

typedef struct {
    NMHDR nmhdr;
    LONG cObjectCount;
    LONG cch;
} ENSAVECLIPBOARD;

Members

nmhdr

Notification header.

cObjectCount

Number of objects on the clipboard.

cch

Number of characters on the clipboard.


ENUM_SERVICE_STATUS

The ENUM_SERVICE_STATUS structure is used by the EnumDependentServices and EnumServicesStatus functions to return the name of a service in a service control manager database and to return information about that service.

typedef struct _ENUM_SERVICE_STATUS { // ess

    LPTSTR lpServiceName;

    LPTSTR lpDisplayName;

    SERVICE_STATUS ServiceStatus;

} ENUM_SERVICE_STATUS, *LPENUM_SERVICE_STATUS;

Members

lpServiceName

Points to a null-terminated string that names a service in a service control manager database. The maximum string length is 256 characters. The service control manager database preserves the case of the characters, but service name comparisons are always case insensitive. A slash (/), backslash (\), comma, and space are invalid service name characters.

lpDisplayName

Points to a null-terminated string that is to be used by user interface programs to identify the service. This string has a maximum length of 256 characters. The name is case-preserved in the Service Control Manager. Display name comparisons are always case-insensitive.

ServiceStatus

Specifies a SERVICE_STATUS structure in which status information about the lpServiceName service is returned.

See Also

EnumDependentServices, EnumServicesStatus, SERVICE_STATUS


ENUMLOGFONT

The ENUMLOGFONT structure defines the attributes of a font, the complete name of a font, and the style of a font.

typedef struct tagENUMLOGFONT { // elf

    LOGFONT elfLogFont;

    BCHAR    elfFullName[LF_FULLFACESIZE];

    BCHAR    elfStyle[LF_FACESIZE];

} ENUMLOGFONT;

Members

elfLogFont

Specifies a LOGFONT structure that defines the attributes of a font.

elfFullName

Specifies a unique name for the font. For example, “ABCD Font Company TrueType Bold Italic Sans Serif”.

elfStyle

Specifies the style of the font. For example, “Bold Italic”.

See Also

EnumFontFamProc, LOGFONT


ENUMLOGFONTEX

The ENUMLOGFONTEX structure contains information about an enumerated font.

typedef struct tagENUMLOGFONTEX {
    LOGFONT  elfLogFont;
    BCHAR  elfFullName[LF_FULLFACESIZE];
    BCHAR  elfStyle[LF_FACESIZE];
    BCHAR  elfScript[LF_FACESIZE];
} ENUMLOGFONTEX;

Members

elfLogFont

Specifies a LOGFONT structure that contains values defining the font attributes.

elfFullName

Specifies a null-terminated string specifying the unique name of the font. For example, “ABC Font Company TrueType Bold Italic Sans Serif”.

elfStyle

Specifies a null-terminated string specifying the style of the font. For example, “Bold Italic”.

elfScript

Specifies a null-terminated string specifying the script of the font. For example, “Cyrillic”.

See Also

EnumFontFamExProc, EnumFontFamiliesEx, LOGFONT


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.

See Also

NetAlertRaise


EVENTLOGRECORD

The EVENTLOGRECORD structure contains information about an event record.

typedef struct _EVENTLOGRECORD { // evlr

    DWORD  Length;

    DWORD  Reserved;

    DWORD  RecordNumber;

    DWORD  TimeGenerated;

    DWORD  TimeWritten;

    DWORD  EventID;

    WORD   EventType;

    WORD   NumStrings;

    WORD   EventCategory;

    WORD   ReservedFlags;

    DWORD  ClosingRecordNumber;

    DWORD  StringOffset;

    DWORD  UserSidLength;

    DWORD  UserSidOffset;

    DWORD  DataLength;

    DWORD  DataOffset;

    //

    // Then follow:

    //

    // TCHAR SourceName[]

    // TCHAR Computername[]

    // SID   UserSid

    // TCHAR Strings[]

    // BYTE  Data[]

    // CHAR  Pad[]

    // DWORD Length;

    //

} EVENTLOGRECORD;

Members

Length

Specifies the length, in bytes, of this event record. Note that this value is stored at both ends of the entry to ease moving forward or backward through the log. The length includes any pad bytes inserted at the end of the record for DWORD alignment.

Reserved

Reserved.

RecordNumber

Contains a record number that can be used with the EVENTLOG_SEEK_READ flag passed in a call to the ReadEventLog function to begin reading at a specified record.

TimeGenerated

The time at which this entry was submitted. This time is measured in the number of seconds elapsed since 00:00:00 January 1, 1970.

TimeWritten

Specifies the time at which this entry was received by the service to be written to the logfile. This time is measured in the number of seconds elapsed since 00:00:00 January 1, 1970.

EventID

Identifies the event. This is specific to the source that generated the event log entry, and is used, together with SourceName, to identify a message in a message file that is presented to the user while viewing the log.

EventType

Specifies the type of event. This member can be one of the following values:

Value	Meaning
EVENTLOG_ERROR_TYPE	Error event
EVENTLOG_WARNING_TYPE	Warning event
EVENTLOG_INFORMATION_TYPE	Information event
EVENTLOG_AUDIT_SUCCESS	Success Audit event
EVENTLOG_AUDIT_FAILURE	Failure Audit event
For more information about event types, see Event Logging.

NumStrings

Specifies the number of strings present in the log (at the position indicated by StringOffset). These strings are merged into the message before it is displayed to the user.

EventCategory

Specifies a subcategory for this event. This subcategory is source specific.

ReservedFlags

Reserved.

ClosingRecordNumber

Reserved.

StringOffset

Specifies the offset of the strings within this event log entry.

UserSidLength

Specifies the length, in bytes, of the UserSid member. This value can be zero if no security identifier was provided.

UserSidOffset

Specifies the offset of the security identifier within this event record.

DataLength

Specifies the length, in bytes, of the event-specific data (at the position indicated by DataOffset).

DataOffset

Specifies the offset of the event-specific information within this log. This information could be something specific (a disk driver might log the number of retries, for example), followed by binary information specific to the event being logged and to the source that generated the entry.

SourceName

Contains the variable-length null-terminated string specifying the name of the source (application, service, driver, subsystem) that generated the entry. This is the name used to retrieve from the registry the name of the file containing the message strings for this source. It is used, together with the event identifier, to get the message string that describes this event.

Computername

Contains the variable-length null-terminated string specifying the name of the computer that generated this event. There may also be some pad bytes after this field to ensure that the UserSid is aligned on a DWORD boundary.

UserSid

Specifies the security identifier of the active user at the time this event was logged. This member may be empty if the UserSidLength member is zero.

The defined members are followed by the replacement strings for the message identified by the event identifier, the binary information, some pad bytes to make sure the full entry is on a DWORD boundary, and finally the length of the log entry again. Because the strings and the binary information can be of any length, no structure members are defined to reference them.

The event identifier together with SourceName and a language identifier identify a message string that describes the event in more detail. The strings are used as replacement strings and are merged into the message string to make a complete message. The message strings are contained in a message file specified in the source entry in the registry.

The binary information is information that is specific to the event. It could be the contents of the processor registers when a device driver got an error, a dump of an invalid packet that was received from the network, a dump of all the structures in a program (when the data area was detected to be corrupt), and so on. This information should be useful to the writer of the device driver or the application in tracking down bugs or unauthorized breaks into the application.

See Also

ReadEventLog


EVENTMSG

The EVENTMSG structure contains information about a hardware message sent to the system message queue. This structure is used to store message information for the JournalPlaybackProc callback function.

typedef struct tagEVENTMSG {    // em

    UINT  message;

    UINT  paramL;

    UINT  paramH;

    DWORD time;

    HWND  hwnd;

} EVENTMSG;

Members

message

Specifies the message.

paramL

Specifies additional information about the message. The exact meaning depends on the message value.

paramH

Specifies additional information about the message. The exact meaning depends on the message value.

time

Specifies the time at which the message was posted.

hwnd

Identifies the window to which the message was posted.

See Also

JournalPlaybackProc, SetWindowsHookEx


EXCEPTION_DEBUG_INFO

The EXCEPTION_DEBUG_INFO structure contains exception information that can be used by a debugger.

typedef struct _EXCEPTION_DEBUG_INFO { // exdi

    EXCEPTION_RECORD ExceptionRecord;

    DWORD dwFirstChance;

} EXCEPTION_DEBUG_INFO;

Members

ExceptionRecord

Contains an EXCEPTION_RECORD structure with information specific to the exception. This includes the exception code, flags, address, a pointer to a related exception, extra parameters, and so on.

dwFirstChance

Indicates whether the debugger has previously encountered the exception specified by the ExceptionRecord member. If the dwFirstChance member is nonzero, this is the first time the debugger has encountered the exception. Debuggers typically handle breakpoint and single-step exceptions when they are first encountered. If this member is zero, the debugger has previously encountered the exception. This occurs only if, during the search for structured exception handlers, either no handler was found or the exception was continued.

See Also

DEBUG_EVENT, EXCEPTION_RECORD


EXCEPTION_POINTERS

The EXCEPTION_POINTERS structure contains an exception record with a machine-independent description of an exception and a context record with a machine-dependent description of the processor context at the time of the exception.

typedef struct _EXCEPTION_POINTERS { // exp

    PEXCEPTION_RECORD ExceptionRecord;

    PCONTEXT ContextRecord;

} EXCEPTION_POINTERS;

Members

ExceptionRecord

Points to an EXCEPTION_RECORD structure that contains a machine-independent description of the exception.

ContextRecord

Points to a CONTEXT structure that contains a processor-specific description of the state of the processor at the time of the exception.

See Also

GetExceptionInformation, CONTEXT, EXCEPTION_RECORD


EXCEPTION_RECORD

The EXCEPTION_RECORD structure describes an exception.

typedef struct _EXCEPTION_RECORD { // exr

    DWORD ExceptionCode;

    DWORD ExceptionFlags;

    struct _EXCEPTION_RECORD *ExceptionRecord;

    PVOID ExceptionAddress;

    DWORD NumberParameters;

    DWORD ExceptionInformation[EXCEPTION_MAXIMUM_PARAMETERS];

} EXCEPTION_RECORD;

Members

ExceptionCode

Specifies the reason the exception occurred. This is the code generated by a hardware exception, or the code specified in the RaiseException function for a software-generated exception. Following are the exception codes likely to occur due to common programming errors:

Value	Meaning
EXCEPTION_ACCESS_VIOLATION
	The thread tried to read from or write to a virtual address for which it does not have the appropriate access.
EXCEPTION_ARRAY_BOUNDS_EXCEEDED
	The thread tried to access an array element that is out of bounds and the underlying hardware supports bounds checking.
EXCEPTION_BREAKPOINT
	A breakpoint was encountered.
EXCEPTION_DATATYPE_MISALIGNMENT
	The thread tried to read or write data that is misaligned on hardware that does not provide alignment. For example, 16-bit values must be aligned on 2-byte boundaries; 32-bit values on 4-byte boundaries, and so on.
EXCEPTION_FLT_DENORMAL_OPERAND
	One of the operands in a floating-point operation is denormal. A denormal value is one that is too small to represent as a standard floating-point value.
EXCEPTION_FLT_DIVIDE_BY_ZERO
	The thread tried to divide a floating-point value by a floating-point divisor of zero.
EXCEPTION_FLT_INEXACT_RESULT
	The result of a floating-point operation cannot be represented exactly as a decimal fraction.
EXCEPTION_FLT_INVALID_OPERATION
	This exception represents any floating-point exception not included in this list.
EXCEPTION_FLT_OVERFLOW
	The exponent of a floating-point operation is greater than the magnitude allowed by the corresponding type.
EXCEPTION_FLT_STACK_CHECK
	The stack overflowed or underflowed as the result of a floating-point operation.
EXCEPTION_FLT_UNDERFLOW
	The exponent of a floating-point operation is less than the magnitude allowed by the corresponding type.
EXCEPTION_ILLEGAL_INSTRUCTION
	The thread tried to execute an invalid instruction.
EXCEPTION_IN_PAGE_ERROR
	The thread tried to access a page that was not present, and the system was unable to load the page. For example, this exception might occur if a network connection is lost while running a program over the network.
EXCEPTION_INT_DIVIDE_BY_ZERO
	The thread tried to divide an integer value by an integer divisor of zero.
EXCEPTION_INT_OVERFLOW
	The result of an integer operation caused a carry out of the most significant bit of the result.
EXCEPTION_INVALID_DISPOSITION
	An exception handler returned an invalid disposition to the exception dispatcher. Programmers using a high-level language such as C should never encounter this exception.
EXCEPTION_NONCONTINUABLE_EXCEPTION
	The thread tried to continue execution after a noncontinuable exception occurred.
EXCEPTION_PRIV_INSTRUCTION
	The thread tried to execute an instruction whose operation is not allowed in the current machine mode.
EXCEPTION_SINGLE_STEP
	A trace trap or other single-instruction mechanism signaled that one instruction has been executed.
EXCEPTION_STACK_OVERFLOW
	The thread used up its stack.
Another exception code is likely to occur when debugging console processes. It does not arise because of a programming error. The DBG_CONTROL_C exception code occurs when CTRL+C is input to a console process that handles CTRL+C signals and is being debugged. This exception code is not meant to be handled by applications. It is raised only for the benefit of the debugger, and is raised only when a debugger is attached to the console process.

ExceptionFlags

Specifies the exception flags. This member can be either zero, indicating a continuable exception, or EXCEPTION_NONCONTINUABLE indicating a noncontinuable exception. Any attempt to continue execution after a noncontinuable exception causes the EXCEPTION_NONCONTINUABLE_EXCEPTION exception.

ExceptionRecord

Points to an associated EXCEPTION_RECORD structure. Exception records can be chained together to provide additional information when nested exceptions occur.

ExceptionAddress

Specifies the address where the exception occurred.

NumberParameters

Specifies the number of parameters associated with the exception. This is the number of defined elements in the ExceptionInformation array.

ExceptionInformation

Specifies an array of additional 32-bit arguments that describe the exception. The RaiseException function can specify this array of arguments. For most exception codes, the array elements are undefined. For the following exception code, the array elements are defined as follows:

Exception code	Array contents
EXCEPTION_ACCESS_VIOLATION
	The first element of the array contains a read-write flag that indicates the type of operation that caused the access violation. If this value is zero, the thread attempted to read the inaccessible data. If this value is 1, the thread attempted to write to an inaccessible address.
	The second array element specifies the virtual address of the inaccessible data.
See Also

EXCEPTION_DEBUG_INFO, EXCEPTION_POINTERS, GetExceptionInformation, RaiseException, UnhandledExceptionFilter


EXPLICIT_ACCESS [New - Windows NT]
EXPLICIT_ACCESS

[New - Windows NT]

The EXPLICIT_ACCESS structure specifies access-control information for a specified trustee. Access control functions, such as SetEntriesInAcl and GetExplicitEntriesFromAcl, use this structure to describe the information in an access-control entry (ACE) of an access-control list (ACL).

typedef struct _EXPLICIT_ACCESS {

    DWORD        grfAccessPermissions;

    ACCESS_MODE  grfAccessMode;

    DWORD        grfInheritance;

    TRUSTEE      Trustee;

} EXPLICIT_ACCESS, *PEXPLICIT_ACCESS;

Members

grfAccessPermissions

A set of bit flags that use the ACCESS_MASK format to specify the access rights that an ACE allows, denies, or audits for the trustee. The functions that use the EXPLICIT_ACCESS structure do not convert, interpret, or validate the bits in this mask.

grfAccessMode

Specifies a value from the ACCESS_MODE enumeration. For a discretionary ACL (DACL), this flag indicates whether the ACL allows or denies the specified access rights. For a system ACL (SACL), this flag indicates whether the ACL generates audit messages for successful attempts to use the specified access rights, or failed attempts, or both. When modifying an existing ACL, you can specify the REVOKE_ACCESS flag to remove any existing ACEs for the specified trustee.

grfInheritance

A set of bit flags that determines whether other containers or objects can inherit the ACE from the primary object to which the ACL is attached. The value of this member corresponds to the inheritance portion (low-order byte) of the AceFlags member of the ACE_HEADER structure. This parameter can be NO_INHERITANCE to indicate that the ACE is not inheritable; or it can be a combination of the following values.

Value	Meaning
CONTAINER_INHERIT_ACE
	Other containers that are contained by the primary object inherit the ACE.
INHERIT_ONLY_ACE
	The ACE does not apply to the primary object to which the ACL is attached, but objects contained by the primary object inherit the ACE.
NO_PROPAGATE_INHERIT_ACE
	The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE flags are not propagated to an inherited ACE.
OBJECT_INHERIT_ACE
	Noncontainer objects contained by the primary object inherit the ACE.
SUB_CONTAINERS_ONLY_INHERIT
	Other containers that are contained by the primary object inherit the ACE. This flag corresponds to the CONTAINER_INHERIT_ACE flag.
SUB_OBJECTS_ONLY_INHERIT
	Noncontainer objects contained by the primary object inherit the ACE. This flag corresponds to the OBJECT_INHERIT_ACE flag.
SUB_CONTAINERS_AND_OBJECTS_INHERIT
	Both containers and noncontainer objects that are contained by the primary object inherit the ACE. This flag corresponds to the combination of the CONTAINER_INHERIT_ACE and OBJECT_INHERIT_ACE flags.
Trustee

A TRUSTEE structure that identifies the user, group, or program (such as a Windows NT service) to which the ACE applies.

See Also

ACCESS_MODE, ACE, ACE_HEADER, ACL, BuildExplicitAccessWithName, BuildSecurityDescriptor, GetExplicitEntriesFromAcl, LookupSecurityDescriptorParts, SetEntriesInAcl, TRUSTEE


EXIT_PROCESS_DEBUG_INFO

The EXIT_PROCESS_DEBUG_INFO structure contains an exiting process’s exit code.

typedef struct _EXIT_PROCESS_DEBUG_INFO { // epdi

    DWORD dwExitCode;

} EXIT_PROCESS_DEBUG_INFO;

Members

dwExitCode

Specifies the exit code for the process.

See Also

DEBUG_EVENT


EXIT_THREAD_DEBUG_INFO

The EXIT_THREAD_DEBUG_INFO structure contains an exiting thread’s exit code.

typedef struct _EXIT_THREAD_DEBUG_INFO { // etdi

    DWORD dwExitCode;

} EXIT_THREAD_DEBUG_INFO;

Members

dwExitCode

Specifies the exit code for the thread.

See Also

DEBUG_EVENT


EXT_BUTTON

The EXT_BUTTON structure contains information about a button that a File Manager extension dynamic-link library is adding to the toolbar of File Manager.

typedef struct _EXT_BUTTON { /* extbtn */

    WORD idCommand;

    WORD idsHelp;

    WORD fsStyle;

} EXT_BUTTON;

Members

idCommand

Specifies the command identifier for the button.

idsHelp

Specifies the identifier of the Help string for the button.

fsStyle

Specifies the style of the button.

See Also

FMEVENT_TOOLBARLOAD, FMS_TOOLBARLOAD


EXTLOGFONT

The EXTLOGFONT structure defines the attributes of a font.

typedef struct tagEXTLOGFONT {

    LOGFONT elfLogFont;

    BCHAR    elfFullName[LF_FULLFACESIZE];

    BCHAR    elfStyle[LF_FACESIZE];

    DWORD   elfVersion;

    DWORD   elfStyleSize;

    DWORD   elfMatch;

    DWORD   elfReserved;

    BYTE    elfVendorId[ELF_VENDOR_SIZE];

    DWORD   elfCulture;

    PANOSE  elfPanose;

} EXTLOGFONT;

Members

elfLogFont

Specifies some of the attributes of the given font. This member is a LOGFONT structure.

elfFullName

Specifies a unique name for the font (for example, ABCD Font Company TrueType Bold Italic Sans Serif).

elfStyle

Specifies the style of the font (for example, Bold Italic).

elfVersion

Reserved. Must be zero.

elfStyleSize

This member only has meaning for hinted fonts. It specifies the point size at which the font is hinted. If set to zero, which is its default value, the font is hinted at the point size corresponding to the lfHeight member of the LOGFONT structure specified by elfLogFont.

elfMatch

A unique identifier for an enumerated font. This will be filled in by the graphics device interface (GDI) upon font enumeration.

elfReserved

Reserved; must be zero.

elfVendorId

A 4-byte identifier of the font vendor.

elfCulture

Reserved; must be zero.

elfPanose

A PANOSE structure that specifies the shape of the font. If all members of this structure are set to zero, the elfPanose member is ignored by the font mapper.

See Also

LOGFONT, PANOSE


EXTLOGPEN

The EXTLOGPEN structure defines the pen style, width, and brush attributes for an extended pen. This structure is used by the GetObject function when it retrieves a description of a pen that was created when an application called the ExtCreatePen function.

typedef struct tagEXTLOGPEN { // exlp

    UINT     elpPenStyle;

    UINT     elpWidth;

    UINT     elpBrushStyle;

    COLORREF elpColor;

    LONG     elpHatch;

    DWORD    elpNumEntries;

    DWORD    elpStyleEntry[1];

} EXTLOGPEN;

Members

elpPenStyle

Specifies a combination of pen type, style, end cap style, and join style. The values from each category can be retrieved by using a bitwise AND with the appropriate mask.

The elpPenStyle member masked with PS_TYPE_MASK has one of the following pen type values:

Value	Meaning
PS_GEOMETRIC	The pen is geometric.
PS_COSMETIC	The pen is cosmetic.
The elpPenStyle member masked with PS_STYLE_MASK has one of the following pen styles values:

Value	Meaning
PS_SOLID	The pen is solid.
PS_DASH	The pen is dashed.
PS_DOT	The pen is dotted.
PS_DASHDOT	The pen has alternating dashes and dots.
PS_DASHDOTDOT	The pen has alternating dashes and double dots.
PS_NULL	The pen is invisible.
PS_USERSTYLE	The pen will use a styling array supplied by the user.
PS_INSIDEFRAME	The pen is solid. When this pen is used in any GDI drawing function that takes a bounding rectangle, the dimensions of the figure are shrunk so that it fits entirely in the bounding rectangle, taking into account the width of the pen. This applies only to PS_GEOMETRIC pens.
The following category applies only to PS_GEOMETRIC pens. The elpPenStyle member masked with PS_ENDCAP_MASK has one of the following end cap values:

Value	Meaning
PS_ENDCAP_ROUND	Line end caps are round.
PS_ENDCAP_SQUARE	Line end caps are square.
PS_ENDCAP_FLAT	Line end caps are flat.
The following category applies only to PS_GEOMETRIC pens. The elpPenStyle member masked with PS_JOIN_STYLE has one of the following join values:

Value	Meaning
PS_JOIN_BEVEL	Line joins are beveled.
PS_JOIN_MITER	Line joins are mitered when they are within the current SetMiterLimit limit. A join is beveled when it would exceed the limit.
PS_JOIN_ROUND	Line joins are round.
elpWidth

Specifies the width of the pen. If the elpPenStyle member specifies geometric lines, this value is the width, in logical units, of the line. Otherwise, the lines are cosmetic and this value is 1.

elpBrushStyle

Specifies the brush style of the pen. The elpBrushStyle member values can be one of the following:

Value	Description
BS_DIBPATTERN	Specifies a pattern brush defined by a device-independent bitmap (DIB) specification. If elpBrushStyle is BS_DIBPATTERN, the elpHatch member contains a handle to a packed DIB.
BS_DIBPATTERNPT	Specifies a pattern brush defined by a device-independent bitmap (DIB) specification. If elpBrushStyle is BS_DIBPATTERNPT, the elpHatch member contains a pointer to a packed DIB.
BS_HATCHED	Specifies a hatched brush.
BS_HOLLOW	Specifies a hollow or NULL brush.
BS_PATTERN	Specifies a pattern brush defined by a memory bitmap.
BS_SOLID	Specifies a solid brush.
elpColor

If elpBrushStyle is BS_SOLID or BS_HATCHED, elpColor specifies the color in which the pen is to be drawn. For BS_HATCHED, the SetBkMode and SetBkColor functions determine the background color.

If elpBrushStyle is BS_HOLLOW or BS_PATTERN, elpColor is ignored.

If elpBrushStyle is BS_DIBPATTERN or BS_DIBPATTERNPT, the low-order word of elpColor specifies whether the bmiColors members of the BITMAPINFO structure contain explicit red, green, blue (RGB) values or indexes into the currently realized logical palette. The elpColor value must be one of the following:

Value	Meaning
DIB_PAL_COLORS	The color table consists of an array of 16-bit indexes into the currently realized logical palette.
DIB_RGB_COLORS	The color table contains literal RGB values.
elpHatch

If elpBrushStyle is BS_PATTERN, elpHatch is a handle to the bitmap that defines the pattern.

If elpBrushStyle is BS_SOLID or BS_HOLLOW, elpHatch is ignored.

If elpBrushStyle is BS_DIBPATTERN, the elpHatch member is a handle to a packed DIB. To obtain this handle, an application calls the GlobalAlloc function to allocate a block of global memory and then fills the memory with the packed DIB. A packed DIB consists of a BITMAPINFO structure immediately followed by the array of bytes that define the pixels of the bitmap.

If elpBrushStyle is BS_DIBPATTERNPT, the elpHatch member is a pointer to a packed DIB.

If elpBrushStyle is BS_HATCHED, the elpHatch member specifies the orientation of the lines used to create the hatch. It can be any one of the following values:

Value	Meaning
HS_BDIAGONAL	45-degree upward hatch (left to right)
HS_CROSS	Horizontal and vertical crosshatch
HS_DIAGCROSS	45-degree crosshatch
HS_FDIAGONAL	45-degree downward hatch (left to right)
HS_HORIZONTAL	Horizontal hatch
HS_VERTICAL	Vertical hatch
elpNumEntries

Specifies the number of entries in the style array in the elpStyleEntry member. This value is zero if elpPenStyle does not specify PS_USERSTYLE.

elpStyleEntry

Specifies a user-supplied style array. The array is specified with a finite length, but it is used as if it repeated indefinitely. The first entry in the array specifies the length of the first dash. The second entry specifies the length of the first gap. Thereafter, lengths of dashes and gaps alternate.

If elpWidth specifies geometric lines, the lengths are in logical units. Otherwise, the lines are cosmetic and lengths are in device units.

See Also

BITMAPINFO, ExtCreatePen, GetObject, GlobalAlloc, SetBkColor, SetBkMode


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.

See Also

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;
    LPTSTR    fi3_pathname;
    LPTSTR    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.

See Also

NetFileEnum, NetFileGetInfo


FILE_NOTIFY_INFORMATION

The FIND_NOTIFY_INFORMATION structure describes the changes found by the ReadDirectoryChangesW function.

typedef struct _FILE_NOTIFY_INFORMATION {

   DWORD NextEntryOffset;

   DWORD Action;

   DWORD FileNameLength;

   WCHAR FileName[1];

} FILE_NOTIFY_INFORMATION;

Members

NextEntryOffset

Specifies the number of bytes that must be skipped to get to the next record. A value of zero indicates that this is the last record.

Action

Specifies the type of change that occurred.

Value	Meaning
FILE_ACTION_ADDED	The file was added to the directory.
FILE_ACTION_REMOVED	The file was removed from the directory.
FILE_ACTION_MODIFIED	The file was modified. This can be a change in the time stamp or attributes.
FILE_ACTION_RENAMED_OLD_NAME	The file was renamed and this is the old name.
FILE_ACTION_RENAMED_NEW_NAME	The file was renamed and this is the new name.
FileNameLength

Specifies the length, in bytes, of the filename portion of the record. Note that this length does not include the terminating null character.

FileName

This is a variable-length field that contains the filename relative to the directory handle. The filename is in the Unicode character format and is not null-terminated.

See Also

ReadDirectoryChangesW


FILEDESCRIPTOR

Describes the properties of a file that is being copied by means of the clipboard during an OLE drag and drop operation.

typedef struct _FILEDESCRIPTOR { // fod

    DWORD    dwFlags;          // see below

    CLSID    clsid;            // file class identifier

    SIZEL    sizel;            // width and height of file icon

    POINTL   pointl;           // screen coordinates of file object

    DWORD    dwFileAttributes; // file attribute flags (FILE_ATTRIBUTE_)

    FILETIME ftCreationTime;   // time of file creation

    FILETIME ftLastAccessTime; // time of last access to file

    FILETIME ftLastWriteTime;  // time of last write operation

    DWORD    nFileSizeHigh;    // high-order word of file size, in bytes

    DWORD    nFileSizeLow;     // low-order word of file size, in bytes

    CHAR     cFileName[ MAX_PATH ]; // name of file (null-terminated)

} FILEDESCRIPTOR, *LPFILEDESCRIPTOR;

Members

dwFlags

Array of flags that indicate which of the other structure members contain valid data. This member can be a combination of these values:

FD_ACCESSTIME	The ftLastAccessTime member is valid.
FD_ATTRIBUTES	The dwFileAttributes member is valid.
FD_CLSID	The clsid member is valid.
FD_CREATETIME	The ftCreationTime member is valid.
FD_FILESIZE	The nFileSizeHigh and nFileSizeLow members are valid.
FD_LINKUI	Treat the operation as “Link.”
FD_SIZEPOINT	The sizel and pointl members are valid.
FD_WRITESTIME	The ftLastWriteTime member is valid.


FILEGROUPDESCRIPTOR

Defines the CF_FILEGROUPDESCRIPTOR clipboard format.

typedef struct _FILEGROUPDESCRIPTOR { // fgd

     UINT cItems;           // number of elements in fgd

     FILEDESCRIPTOR fgd[1]; // array of file descriptor structures

} FILEGROUPDESCRIPTOR, * LPFILEGROUPDESCRIPTOR;


FILETIME

The FILETIME structure is a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601.

typedef struct _FILETIME { // ft

    DWORD dwLowDateTime;

    DWORD dwHighDateTime;

} FILETIME;

Members

dwLowDateTime

Specifies the low-order 32 bits of the file time.

dwHighDateTime

Specifies the high-order 32 bits of the file time.

Remarks

It is not recommended that you add and subtract values from the FILETIME structure to obtain relative times. Instead, you should

•	Copy the resulting FILETIME structure to a LARGE_INTEGER structure.

•	Use normal 64-bit arithmetic on the LARGE_INTEGER value.

See Also

CompareFileTime, GetFileTime, LARGE_INTEGER


FILTERKEYS

The FILTERKEYS structure contains information about the FilterKeys accessibility feature, which allow a user with disabilities to set the keyboard repeat rate (RepeatKeys), acceptance delay (SlowKeys), and bounce rate (BounceKeys).

typedef struct tagFILTERKEYS {     // fk

    UINT  cbSize;

    DWORD dwFlags;

    DWORD iWaitMSec;

    DWORD iDelayMSec;

    DWORD iRepeatMSec;

    DWORD iBounceMSec;

} FILTERKEYS;

Members

cbSize

Specifies the structure size, in bytes.

dwFlags

A set of bit flags that specify properties of the FilterKeys feature. The following bit-flag values are defined:

Value	Meaning
FKF_AVAILABLE	The FilterKeys features are available.
FKF_CLICKON	The computer makes a click sound when a key is pressed or accepted, that is, if SlowKeys is on, the acceptance is separated from the press and gets a separate click..
FKF_FILTERKEYSON	The FilterKeys features are on.
FKF_HOTKEYACTIVE	The user can turn the FilterKeys feature on and off by holding down the SHIFT key for eight seconds.
FKF_HOTKEYSOUND	If this flag is set, the computer plays a siren sound when the user turns the FilterKeys feature on or off by using the hot key.
FKF_CONFIRMHOTKEY	Windows 95 only: A confirmation dialog box appears when the the FilterKeys features are activated by using the hot key.
FKF_INDICATOR	Windows 95 only: A visual indicator is displayed when the FilterKeys features are on.
iWaitMSec

Specifies the length of time, in milliseconds, that the user must hold down a key before it is accepted by the computer.

iDelayMSec

Specifies the length of time, in milliseconds, that the user must hold down a key before it begins to repeat.

iRepeatMSec

Specifies the length of time, in milliseconds, between each repetition of the keystroke.

iBounceMSec

Specifies the amount of time, in milliseconds, that must elapse after releasing a key before the computer will accept a subsequent press of the same key.

Remarks

Use a FILTERKEYS structure when calling the SystemParametersInfo function with the wAction parameter set to the SPI_GETFILTERKEYS or SPI_SETFILTERKEYS value. When using SPI_GETFILTERKEYS,you must specify the cbSize member of the FILTERKEYS structure; the SystemParametersInfo function fills the remaining members. Specify all structure members when using the SPI_SETFILTERKEYS value.

Either iDelayMSec or iBounceMSec, or both, must be zero; they cannot both be nonzero at the same time.

If iBounceMSec is nonzero, the BounceKeys feature is on and the SlowKeys feature is off (the iDelayMSec value is ignored). If iBounceMSec is zero, the BounceKeys feature is off.

If iDelayMSec is nonzero and iBounceMSec is zero, the SlowKeys feature is on; otherwise, it is off.

See Also

SystemParametersInfo


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.

See Also

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.

See Also

FIND_NAME_BUFFER, NCB


FINDREPLACE

The FINDREPLACE structure contains information that the FindText and ReplaceText functions use to initialize the Find and Replace common dialog boxes. The FINDMSGSTRING registered message uses this structure to pass the user’s search or replacement input to the owner window of a Find or Replace common dialog box.

typedef struct {    // fr

    DWORD        lStructSize;

    HWND         hwndOwner;

    HINSTANCE    hInstance;

    DWORD        Flags;

    LPTSTR        lpstrFindWhat;

    LPTSTR        lpstrReplaceWith;

    WORD         wFindWhatLen;

    WORD         wReplaceWithLen;

    LPARAM        lCustData;

    LPFRHOOKPROC lpfnHook;

    LPCTSTR       lpTemplateName;

} FINDREPLACE;

Members

lStructSize

Specifies the length, in bytes, of the structure.

hwndOwner

Identifies the window that owns the dialog box. The window procedure of the specified window receives FINDMSGSTRING messages from the dialog box. This member can be any valid window handle, but it must not be NULL.

hInstance

If the FR_ENABLETEMPLATEHANDLE flag is set in the Flags member, hInstance is the handle of a memory object containing a dialog box template. If the FR_ENABLETEMPLATE flag is set, hInstance identifies a module that contains a dialog box template named by the lpTemplateName member. If neither flag is set, this member is ignored.

Flags

A set of bit flags that you can use to initialize the dialog box. The dialog box sets these flags when it sends the FINDMSGSTRING registered message to indicate the user’s input. This member can be a combination of the following flags:

Flag	Meaning
FR_DIALOGTERM
	If set in a FINDMSGSTRING message, indicates that the dialog box is closing. When you receive a message with this flag set, the dialog box window handle returned by the FindText or ReplaceText function is no longer valid.
FR_DOWN
	If set, the Down button of the direction radio buttons in a Find dialog box is selected indicating that you should search from the current location to the end of the document. If not set, the Up button is selected so you should search to the beginning of the document. You can set this flag to initialize the dialog box. If set in a FINDMSGSTRING message, indicates the user’s selection.
FR_ENABLEHOOK
	Enables the hook function specified in the lpfnHook member. This flag is used only to initialize the dialog box.
FR_ENABLETEMPLATE
	Indicates that the hInstance and lpTemplateName members specify a dialog box template to use in place of the default template. This flag is used only to initialize the dialog box.
FR_ENABLETEMPLATEHANDLE
	Indicates that the hInstance member identifies a data block that contains a preloaded dialog box template. The system ignores the lpTemplateName member if this flag is specified.
FR_FINDNEXT
	If set in a FINDMSGSTRING message, indicates that the user clicked the Find Next button in a Find or Replace dialog box. The lpstrFindWhat member specifies the string to search for.
FR_HIDEUPDOWN
	If set when initializing a Find dialog box, hides the search direction radio buttons.
FR_HIDEMATCHCASE
	If set when initializing a Find or Replace dialog box, hides the Match Case check box.
FR_HIDEWHOLEWORD
	If set when initializing a Find or Replace dialog box, hides the Match Whole Word Only check box.
FR_MATCHCASE
	If set, the Match Case check box is checked indicating that the search should be case-sensitive. If not set, the check box is unchecked so the search should be case-insensitive. You can set this flag to initialize the dialog box. If set in a FINDMSGSTRING message, indicates the user’s selection.
FR_NOMATCHCASE
	If set when initializing a Find or Replace dialog box, disables the Match Case check box.
FR_NOUPDOWN
	If set when initializing a Find dialog box, disables the search direction radio buttons.
FR_NOWHOLEWORD
	If set when initializing a Find or Replace dialog box, disables the Whole Word check box.
FR_REPLACE
	If set in a FINDMSGSTRING message, indicates that the user clicked the Replace button in a Replace dialog box. The lpstrFindWhat member specifies the string to be replaced and the lpstrReplaceWith member specifies the replacement string.
FR_REPLACEALL
	If set in a FINDMSGSTRING message, indicates that the user clicked the Replace All button in a Replace dialog box. The lpstrFindWhat member specifies the string to be replaced and the lpstrReplaceWith member specifies the replacement string.
FR_SHOWHELP
	Causes the dialog box to display the Help button. The hwndOwner member must specify the window to receive the HELPMSGSTRING registered messages that the dialog box sends when the user clicks the Help button.
FR_WHOLEWORD
	If set, the Match Whole Word Only check box is checked indicating that you should search only for whole words that match the search string. If not set, the check box is unchecked so you should also search for word fragments that match the search string. You can set this flag to initialize the dialog box. If set in a FINDMSGSTRING message, indicates the user’s selection.
lpstrFindWhat

Pointer to a buffer that a FINDMSGSTRING message uses to pass the null terminated search string that the user typed in the “Find What:” edit control. You must dynamically allocate the buffer or use a global or static array so it does not go out of scope before the dialog box closes. The buffer should be at least 80 characters long. If the buffer contains a string when you initialize the dialog box, the string is displayed in the “Find What:” edit control.

If a FINDMSGSTRING message specifies the FR_FINDNEXT flag, lpstrFindWhat contains the string to search for. The FR_DOWN, FR_WHOLEWORD, and FR_MATCHCASE flags indicate the direction and type of search. If a FINDMSGSTRING message specifies the FR_REPLACE or FR_REPLACE flags, lpstrFindWhat contains the string to be replaced.

lpstrReplaceWith

Pointer to a buffer that a FINDMSGSTRING message uses to pass the null terminated replacement string that the user typed in the “Replace With:” edit control. You must dynamically allocate the buffer or use a global or static array so it does not go out of scope before the dialog box closes. If the buffer contains a string when you initialize the dialog box, the string is displayed in the “Replace With:” edit control.

If a FINDMSGSTRING message specifies the FR_REPLACE or FR_REPLACEALL flags, lpstrReplaceWith contains the replacement string .

The FindText function ignores this member.

wFindWhatLen

Specifies the length, in bytes, of the buffer pointed to by the lpstrFindWhat member.

wReplaceWithLen

Specifies the length, in bytes, of the buffer pointed to by the lpstrReplaceWith member.

lCustData

Specifies application-defined data that the system passes to the hook procedure identified by the lpfnHook member. When the system sends the WM_INITDIALOG message to the hook procedure, the message’s lParam parameter is a pointer to the FINDREPLACE structure specified when the dialog was created. The hook procedure can use this pointer to get the lCustData value.

lpfnHook

Pointer to an FRHookProc hook procedure that can process messages intended for the dialog box. This member is ignored unless the FR_ENABLEHOOK flag is set in the Flags member.

If the hook procedure returns FALSE in response to the WM_INITDIALOG message, the hook procedure must display the dialog box or else the dialog box will not be shown. To do this, first perform any other paint operations, and then call the ShowWindow and UpdateWindow functions.

lpTemplateName

Pointer to a null-terminated string that names the dialog box template resource in the module identified by the hInstance member. This template is substituted for the standard dialog box template. For numbered dialog box resources, this can be a value returned by the MAKEINTRESOURCE macro. This member is ignored unless the FR_ENABLETEMPLATE flag is set in the Flags member.

See Also

FindText, FRHookProc, MAKEINTRESOURCE, ReplaceText, ShowWindow, UpdateWindow, WM_INITDIALOG


FINDTEXT

The FINDTEXT structure contains information about text to search for in a rich edit control. This structure is used with the EM_FINDTEXT message.

typedef struct _findtext {

    CHARRANGE chrg;

    LPSTR lpstrText;

} FINDTEXT;

Members

chrg

Range to search.

lpstrText

Null-terminated string to find.

See Also

EM_FINDTEXT


FINDTEXTEX

Contains information about text to search for in a rich edit control. This structure is used with the EM_FINDTEXTEX message.

typedef struct _findtextex {
    CHARRANGE chrg;      // range to search
    LPSTR lpstrText;     // null-terminated string to find
    CHARRANGE chrgText;  // range in which text is found
} FINDTEXTEX;


FIXED

The FIXED structure contains the integral and fractional parts of a fixed-point real number.

typedef struct _FIXED { // fix

    WORD  fract;

    short value;

} FIXED;

Members

fract

Specifies the fractional part of the number.

value

Specifies the integer part of the number.

Remarks

The FIXED structure is used to describe the elements of the MAT2 structure.

See Also

MAT2


FMS_GETDRIVEINFO

The FMS_GETDRIVEINFO structure contains information about the drive selected in the active File Manager window (the directory window or the Search Results window).

typedef struct _FMS_GETDRIVEINFO { /* fmsgdi */

    DWORD dwTotalSpace;

    DWORD dwFreeSpace;

    TCHAR  szPath[260];

    TCHAR  szVolume[14];

    TCHAR  szShare[128];

} FMS_GETDRIVEINFO;

Members

dwTotalSpace

Specifies the total amount of storage space, in bytes, on the disk associated with the drive.

dwFreeSpace

Specifies the amount of free storage space, in bytes, on the disk associated with the drive.

szPath

Specifies the null-terminated path of the current directory.

szVolume

Specifies the null-terminated volume label of the disk associated with the drive.

szShare

Specifies the null-terminated name of the sharepoint (if the drive is being accessed through a network).

See Also

FMExtensionProc, FM_GETDRIVEINFO


FMS_GETFILESEL

The FMS_GETFILESEL structure contains information about a selected file in the active File Manager window (the directory window or the Search Results window).

typedef struct _FMS_GETFILESEL { /* fmsgfs */

    FILETIME ftTime;

    DWORD    dwSize;

    BYTE     bAttr;

    TCHAR     szName[260];

} FMS_GETFILESEL;

Members

ftTime

Specifies the time and date the file was created.

dwSize

Specifies the size, in bytes, of the file.

bAttr

Specifies the attributes of the file.

szName

Specifies the null-terminated full path and filename of the selected file.

See Also

FMExtensionProc


FMS_LOAD

The FMS_LOAD structure contains information that File Manager uses to add a custom menu provided by a File Manager extension DLL. The structure also provides a delta value that the extension DLL can use to manipulate the custom menu after File Manager has loaded the menu.

typedef struct _FMS_LOAD { /* fmsld */

    DWORD dwSize;

    TCHAR  szMenuName[MENU_TEXT_LEN];

    HMENU hMenu;

    UINT  wMenuDelta;

} FMS_LOAD;

Members

dwSize

Specifies the length, in bytes, of the structure.

szMenuName

Specifies the null-terminated name for a menu item that appears on the menu bar in File Manager.

hMenu

Identifies the pop-up menu added to the menu bar in File Manager.

wMenuDelta

Specifies the menu-item delta value. To avoid conflicts with its own menu items, File Manager renumbers the menu-item identifiers in the pop-up menu identified by the hMenu member by adding this delta value to each identifier. An extension DLL that must modify a menu item must identify the item by adding the delta value to the menu item’s identifier. The value of this member can vary from session to session.

See Also

FMExtensionProc


FMS_TOOLBARLOAD

The FMS_TOOLBARLOAD structure contains information about custom buttons to be added to the File Manager toolbar. The buttons are provided by a File Manager extension DLL.

typedef struct _FMS_TOOLBARLOAD { /* fmstbl */

    DWORD        dwSize;

    LPEXT_BUTTON lpButtons;

    WORD         cButtons;

    WORD         cBitmaps;

    WORD         idBitmap;

    HBITMAP      hBitmap;

} FMS_TOOLBARLOAD;

Members

dwSize

Specifies the size, in bytes, of the structure. File Manager sets the size before calling the extension and checks the size after the extension procedure returns.

lpButtons

Points to an array of EXT_BUTTON structures that specify the style, command identifier, and Help string identifier for each toolbar button.

cButtons

Specifies the number of EXT_BUTTON structures in the array pointed to by the lpButtons member. This number equals the number of buttons and separators to add to the toolbar.

cBitmaps

Specifies the number of buttons represented by the given bitmap.

idBitmap

Specifies the identifier of a bitmap resource in the executable file for the extension DLL. The bitmap resource contains images for the number of buttons specified by cBitmaps. File Manager loads the bitmap resource, then uses it to display the buttons.

hBitmap

Specifies the handle of a bitmap that the File Manager will use to obtain and display button images if idBitmap is 0.

See Also

FMEVENT_TOOLBARLOAD, EXT_BUTTON


FOCUS_EVENT_RECORD

The FOCUS_EVENT_RECORD structure is used to report focus events in a console INPUT_RECORD structure. These events are used internally and should be ignored.

typedef struct _FOCUS_EVENT_RECORD { // fer

    BOOL bSetFocus;

} FOCUS_EVENT_RECORD;

Members

bSetFocus

Used internally.

See Also

INPUT_RECORD


FOLDERSETTINGS

The FOLDERSETTINGS structure is passed from one folder view to another when the user is browsing. It calls IShellView::GetCurrentInfo to get the current settings and passes them to IShellView::CreateViewWindow to allow the next folder view to “inherit” it. These setttings assume a particular UI, which the shell’s folder view has. Shell extensions may or may not use these settings.

typedef struct {

    UINT     ViewMode;

    UINT     fFlags;

}FOLDERSETTINGS; *LPFOLDERSETTINGS;

Members

ViewMode

Specifies the view mode. Can be set to any of the following values:

Value	Meaning
FVM_ICON	The large icon is displayed.
FVM_SMALLICON	The small icon is displayed.
FVM_LIST	Object names are displayed in a list view.
FVM_DETAILS	Object names and other selected information is shown, such as the size or date last updated.
fFlags

Specifies the view mode. Can be set to any of the following values:

Value	Description
FWF_AUTOARRANGE	Automatically arrange the elements in the view. This implies LVS_AUTOARRANGE if the ListView control is used to implement the view.
FWF_ABBREVIATEDNAMES	Names should be abbreviated. This value is not currently supported.
FWF_SNAPTOGRID	Items should be arranged on a grid. This value is not currently used.
FWF_OWNERDATA	This value is not currently used.
FWF_BESTFITWINDOW	Enable the best-fit window mode. Let the view size the window to fit its contents as well as possible.
FWF_DESKTOP	Make the folder behave like the desktop. This value applies only to the desktop view and is not used for typical shell folders.
FWF_SINGLESEL	Do not allow more than a single item to be selected. This is used in the common dialogs.
FWF_NOSUBFOLDERS	Do not show subfolders.
FWF_TRANSPARENT	Draw transparently. This is used only for the desktop.
FWF_NOCLIENTEDGE	Do not add WS_EX_CLIENTEDGE to the folder. This is used only for the desktop.
FWF_NOSCROLL	Do not add scroll bars. This is used only for the desktop.
See Also

IShellView::CreateViewWindow, IShellView::GetCurrentInfo


FontDirEntry

The FontDirEntry structure contains information about an individual font in a font resource group.

struct FontDirEntry {

    WORD dfVersion;

    DWORD dfSize;

    char dfCopyright[60];

    WORD dfType;

    WORD dfPoints;

    WORD dfVertRes;

    WORD dfHorizRes;

    WORD dfAscent;

    WORD dfInternalLeading;

    WORD dfExternalLeading;

    BYTE dfItalic;

    BYTE dfUnderline;

    BYTE dfStrikeOut;

    WORD dfWeight;

    BYTE dfCharSet;

    WORD dfPixWidth;

    WORD dfPixHeight;

    BYTE dfPitchAndFamily;

    WORD dfAvgWidth;

    WORD dfMaxWidth;

    BYTE dfFirstChar;

    BYTE dfLastChar;

    BYTE dfDefaultChar;

    BYTE dfBreakChar;

    WORD dfWidthBytes;

    DWORD dfDevice;

    DWORD dfFace;

    DWORD dfReserved;

    char szDeviceName[];

    char szFaceName[];

};

Members

dfVersion

Specifies a user-defined version number for the resource data that tools can use to read and write resource files.

dfSize

Specifies the size of the file, in bytes.

dfCopyright[60]

Contains a 60-character string with the font supplier's copyright information.

dfType

Specifies the type of font file.

dfPoints

Specifies the point size at which this character set looks best.

dfVertRes

Specifies the vertical resolution, in dots per inch, at which this character set was digitized.

dfHorizRes

Specifies the horizontal resolution, in dots per inch, at which this character set was digitized.

dfAscent

Specifies the distance from the top of a character definition cell to the baseline of the typographical font.

dfInternalLeading

Specifies the amount of leading inside the bounds set by the dfPixHeight member. Accent marks and other diacritical characters can occur in this area.

dfExternalLeading

Specifies the amount of extra leading that the application adds between rows.

dfItalic

Specifies an italic font if not equal to zero.

dfUnderline

Specifies an underlined font if not equal to zero.

dfStrikeOut

Specifies a strikeout font if not equal to zero.

dfWeight

Specifies the weight of the font in the range 0 through 1000. For example, 400 is roman and 700 is bold. If this value is zero, a default weight is used. For additional defined values, see the description of the LOGFONT structure.

dfCharSet

Specifies the character set of the font. For predefined values, see the description of the LOGFONT structure.

dfPixWidth

Specifies the width of the grid on which a vector font was digitized. For raster fonts, if the member is not equal to zero, it represents the width for all the characters in the bitmap. If the member is equal to zero, the font has variable-width characters.

dfPixHeight

Specifies the height of the character bitmap for raster fonts or the height of the grid on which a vector font was digitized.

dfPitchAndFamily

Specifies the pitch and the family of the font. For additional information, see the description of the LOGFONT structure.

dfAvgWidth

Specifies the average width of characters in the font (generally defined as the width of the letter x). This value does not include the overhang required for bold or italic characters.

dfMaxWidth

Specifies the width of the widest character in the font.

dfFirstChar

Specifies the first character code defined in the font.

dfLastChar

Specifies the last character code defined in the font.

dfDefaultChar

Specifies the character to substitute for characters not in the font.

dfBreakChar

Specifies the character that will be used to define word breaks for text justification.

dfWidthBytes

Specifies the number of bytes in each row of the bitmap. This value is always even so that the rows start on word boundaries. For vector fonts, this member has no meaning.

dfDevice

Specifies the offset in the file to a null-terminated string that specifies a device name. For a generic font, this value is zero.

dfFace

Specifies the offset in the file to a null-terminated string that names the typeface.

dfReserved

This member is reserved.

szDeviceName

Array that contains a null-terminated string that specifies the name of the device if this font file is designated for a specific device.

szFaceName

Array that contains a null-terminated string that specifies the typeface name of the font.

Remarks

There is one FontDirEntry structure for every font in the .RES file. Applications that generate .RES files with font resources must also add to the file a FontDirEntry structure for each font.

Font declarations can be mixed with other resource declarations in the .RC file because fonts do not need to be contiguous in the .RES file.

See Also

DirEntry, FontGroupHdr, LOGFONT


FontGroupHdr

The FontGroupHdr structure contains the information necessary for an application to access a specific font.

struct FontGroupHdr {

    WORD NumberOfFonts;

    DirEntry  DE [1];

};

Members

NumberOfFonts

Specifies the number of individual fonts associated with this resource.

DE [1]

Specifies a DirEntry structure that contains a unique ordinal identifier for each font in the resource. The DE [1] member is a placeholder for the variable-length array of DirEntry structures.

Remarks

The FontGroupHdr structure follows the data for the individual fonts in the .RES file. The resource compiler automatically adds the FontGroupHdr structure, generally as the last entry in the file.

See Also

DirEntry, FontDirEntry


FONTSIGNATURE

The FONTSIGNATURE structure contains information identifying the code-pages and Unicode subranges for which a given font provides glyphs.

typedef struct tagFONTSIGNATURE {
    DWORD  fsUsb[4];
    DWORD  fsCsb[2];
} FONTSIGNATURE;

Members

fsUsb

A 128-bit Unicode subset bitfield (USB) identifying up to 126 Unicode subranges. Each bit, except the two most significant bits, represents a single subrange. The most significant bit is always 1 and identifies the bitfield as a font signature; the second most significant bit is reserved and must be 0. Unicode subranges are numbered in accordance with the ISO 10646 standard.

fsCsb

A 64-bit, code-page bitfield (CPB) that identifies a specific character set or code-page. Windows code-pages are in the lower 32 bits of this bitfield. The high 32 are used for non-Windows code-pages. For more information, see Code-Page Bitfields.

Remarks

GDI relies on Windows code-pages fitting within a 32-bit value. Furthermore, the highest two bits within this value are reserved for GDI internal use and may not be assigned to code-pages.


FORM_INFO_1

The FORM_INFO_1 structure contains information about a print form. The information includes the print form’s origin, its name, its dimensions, and the dimensions of its printable area.

typedef struct _FORM_INFO_1 { // fi1

    DWORD Flags;

    LPTSTR pName;

    SIZEL  Size;

    RECTL  ImageableArea;

} FORM_INFO_1;

Members

Flags

A set of bit-flags that specify form properties. The following bit-flag is defined:

Value	Meaning
FORM_BUILTIN	If this bit-flag is set, the form is built-in. If this bit-flag is clear, the form is user-defined.
pName

Points to a null-terminated string that specifies the name of the form.

Size

Specifies the width and height, in thousandths of millimeters, of the form.

ImageableArea

Specifies the width and height, in thousandths of millimeters, of the form.

See Also

AddForm, GetForm, SetForm


FORMAT_PARAMETERS

The FORMAT_PARAMETERS structure provides information used in formatting a contiguous set of disk tracks.

typedef struct _FORMAT_PARAMETERS{

   MEDIA_TYPE MediaType;

   DWORD StartCylinderNumber;

   DWORD EndCylinderNumber;

   DWORD StartHeadNumber;

   DWORD EndHeadNumber;

} FORMAT_PARAMETERS ;

Members

MediaType

Specifies the media type. See MEDIA_TYPE.

StartCylinderNumber

Specifies the cylinder number at which to begin the format.

EndCylinderNumber

Specifies the cylinder number at which to end the format.

StartHeadNumber

Specifies the beginning head location.

EndHeadNumber

Specifies the ending head location.

Remarks

The DeviceIoControl function uses a FORMAT_PARAMETERS structure as input to an IOCTL_DISK_FORMAT_TRACKS device I/O operation.

See Also

DeviceIoControl, IOCTL_DISK_FORMAT_TRACKS, MEDIA_TYPE


FORMATRANGE

The FORMATRANGE structure contains information that a rich edit control uses to format its output for a particular device. This structure is used with the EM_FORMATRANGE message.

typedef struct _formatrange {

    HDC hdc;

    HDC hdcTarget;

    RECT rc;

    RECT rcPage;

    CHARRANGE chrg;

} FORMATRANGE;

Members

hdc

Device to render to.

hdcTarget

Target device to format for.

rc

Area to render to. Units are in TWIPS

rcPage

Entire area of rendering device. Units are in TWIPS

chrg

Range of text to format.

See Also

EM_FORMATRANGE


FVSHOWINFO

Contains information that the IFileViewer::Show member function uses to display a file.

typedef struct {

    DWORD     cbSize;    // size of structure, in bytes

    HWND      hwndOwner; // see below

    int       iShow;     // see below

    DWORD     dwFlags;   // see below

    RECT      rect;      // see below

    LPUNKNOWN punkrel;   // see below

    OLECHAR   strNewFile[MAX_PATH];  // see below

} FVSHOWINFO, *LPFVSHOWINFO;

Members

hwndOwner

Handle of the owner window. When a file viewer creates a window to display a file, it should specify this handle as the owner of the window.

iShow

Show command. For a list of show commands, see the description of the ShowWindow function.

dwFlags

Show information flags. This member can be a combination of these values:

FVSIF_CANVIEWIT	The file viewer can display the file.
FVSIF_NEWFAILED	The file viewer specified a new file to display, but no viewer could display the file. The file viewer should either terminate or continue to display the previous file.
FVSIF_NEWFILE	A drag and drop operation has dropped a file on the file viewer window. The file viewer passes the name of the file to the shell by copying the name to strNewFile. The shell attempts to load a file viewer that can display the new file.
FVSIF_PINNED	A pinned window exists. A file viewer should either use the pinned window to display the file or set a new pinned window and display the file in it.
FVSIF_RECT	rect contains valid data.
rect

Address of a RECT structure that specifies the size and position of the file viewer’s window. This member is valid only if dwFlags includes the FVSIF_RECT value.

punkrel

Address of an interface whose Release member function is called by a new file viewer to release the previous file viewer. This member is used when a drag and drop operation drops a file on the file viewer’s window.

strNewFile

Address of a string that specifies the name of a new file to display. A file viewer sets this member when a drag and drop operation drops a file on the file viewer’s window.

The shell uses this structure to pass information to a file viewer, and a file viewer uses it to return information to the shell.


GCP_RESULTS

The GCP_RESULTS structure contains information about characters in a string. This structure receives the results of the GetCharacterPlacement function. For some languages, the first element in the arrays may contain more, language-dependent information.

typedef struct tagGCP_RESULTS {
    DWORD  lStructSize;
    LPTSTR  lpOutString;
    UINT  *lpOrder;
    INT  *lpDx;
    INT  *lpCaretPos;
    LPTSTR lpClass;
    UINT  *lpGlyphs;
    UINT  nGlyphs;
    UINT  nMaxFit;
} GCP_RESULTS;

Members

lStructSize

Specifies the size, in bytes, of the structure.

lpOutString

Pointer to the buffer that receives the output string or is NULL if the output string is not needed. The output string is a version of the original string that is in the order that will be displayed on a given device. Typically the output string is identical to the original string, but may be different if the string needs reordering and the GCP_REORDER flag is set or if the the original string exceeds the maximum extent and the GCP_MAXEXTENT flag is set.

lpOrder

Address of the array that receives the ordering indices for the characters in the output string or is NULL if the ordering indices are not needed. The original string needs reordering if the GetFontLanguageInfo function returns the GCP_REORDER value. This is typically used when GetFontLanguageInfo returns the GCP_REORDER flag. For example, in Hebrew, in which the text runs from right to left, the lpOrder array gives the exact locations of each element in the original string.

lpDx

Pointer to the array that receives the distances between adjacent character cells or is NULL if these distances are not needed. If glyph rendering is done, the distances are for the glyphs not the characters, so the resulting array can be used with the ExtTextOut function.

The distances in this array are in display order. To find the distance for the ith character in the original string, use the lpOrder array as follows:

width = lpDx[lpOrder[i]];

On input, this member may contain justification weight values if the GCP_JUSTIFYIN value is given with the GetCharacterPlacement function.

lpCaretPos

Pointer to the array that receives the caret position values or is NULL if caret positions are not needed. Each value specifies the caret position immediately before the corresponding character. In some languages the position of the caret for each character may not be immediately to the left of the character. For example, in Hebrew, in which the text runs from right to left, the caret position is to the right of the character. If glyph ordering is done, lpCaretPos matches the original string not the output string. This means that some adjacent values may be the same.

The values in this array are in input order. To find the caret position value for the ith character in the original string, use the array as follows:

position = lpCaretPos[i];

lpClass

Pointer to the array that contains and/or receives character classifications. The values indicate how to lay out characters in the string and are similar (but not identical) to the CT_CTYPE2 values returned by the GetStringTypeEx function. Each element of the array can be set to zero or one of the following values:

Value	Meaning
GCPCLASS_ARABIC	Arabic character.
GCPCLASS_HEBREW	Hebrew character.
GCPCLASS_LATIN	Character from a Latin or other single-byte character set for a left-to-right language.
GCPCLASS_LATINNUMBER	Digit from a Latin or other single-byte character set for a left-to-right language.
GCPCLASS_LOCALNUMBER	Digit from the character set associated with the current font.
In addition, the following can be used when supplying values in the lpClass array with the GCP_CLASSIN flag.

Value	Meaning
GCPCLASS_LATINNUMERICSEPARATOR	Input only. Character used to separate Latin digits, such as acomma or decimal point.
GCPCLASS_LATINNUMERICTERMINATOR	Input only. Character used to terminate Latin digits, such as a plus or minus sign.
GCPCLASS_NEUTRAL	Input only. character has no specific classification.
GCPCLASS_NUMERICSEPARATOR	Input only. Character used to separate digits, such as a comma or decimal point.
For languages that use the GCP_REORDER flag, the following values can also be used with the GCP_CLASSIN flag. Unlike the preceding values, which can be used anywhere in the lpClass array, all of the following values are used only in the first location in the array. All combine with other classifications. Note that GCPCLASS_PREBOUNDLTR and GCPCLASS_PREBOUNDRTL are mutually exclusive, as are GCPCLASSPOSTBOUNDLTR and GCPCLASSPOSTBOUNDRTL.

Value	Meaning
GCPCLASS_PREBOUNDLTR	Set lpClass[0] to GCP_CLASS_PREBOUNDLTR to bind the string to left-to-right reading order before the string.
GCPCLASS_PREBOUNDRTL	Set lpClass[0] to GCP_CLASS_PREBOUNDRTL to bind the string to right-to-left reading order before the string.
GCPCLASS_POSTBOUNDLTR	Set lpClass[0] to GCP_CLASS_POSTBOUNDLTR to bind the string to left-to-right reading order after the string.
GCPCLASS_POSTBOUNDRTL	Set lpClass[0] to GCP_CLASS_POSTBOUNDRTL to bind the string to right-to-left reading order after the string.
To force the layout of a character to be carried out in a specific way, preset the classification for the corresponding array element; the function leaves such preset classifications unchanged and computes classifications only for array elements that have been set to zero. Preset classifications are used only if the GCP_CLASSIN flag is set and the lpclass array is supplied.

If getFontLanguageInfo does not return GCP_REORDER for the current font, only the GCPCLASS_LATIN value is meaningful.

lpGlyphs

Pointer to the array that receives the values identifying the glyphs used for rendering the string or is NULL if glyph rendering is not needed. The number of glyphs in the array may be less than the number of characters in the original string if the string contains ligated glyphs. Also if reordering is required, the order of the glyphs may not be sequential.

This array is useful if more than one operation is being done on a string which has any form of ligation, kerning or order-switching. Using the values in this array for subsequent operations saves the time otherwise required to generate the glyph indices each time.

This array always contains glyph indices and the ETO_GLYPH_INDEX value must always be used when this array is used with the ExtTextOut function.

When GCP_LIGATE is used, you can limit the number of characters that will be ligated together. (In Arabic for example, three-character ligations are common). This is done by setting the maximum required in lpGcpResults->lpGlyphs[0]. If no maximum is required, you should set this field to zero.

For languages such as Arabic, where GetFontLanguageInfo returns the GCP_GLYPHSHAPE flag, the glyphs for a character will be different depending on whether the character is at the beginning, middle, or end of a word. Typically, the first character in the input string will also be the first character in a word, and the last character in the input string will be treated as the last character in a word. However, if the displayed string is a subset of the complete string, such as when displaying a section of scrolled text, this may not be true. In these cases, it is desirable to force the first or last characters to be shaped as not being initial or final forms. To do this, again, the first location in the lpGlyphs array is used by performing an OR operation of the ligation value above with the values GCPGLYPH_LINKBEFORE and/or GCPGLYPH_LINKAFTER. For example, a value of GCPGLYPH_LINKBEFORE | 2 means that two-character ligatures are the maximum required, and the first character in the string should be treated as if it is in the middle of a word.

nGlyphs

On input, this member must be set to the size of the arrays pointed to by the array pointer members. On output, this is set to the number of glyphs filled in, in the output arrays. If glyph substitution is not required (that is, each input character maps to exactly one glyph), this member is the same as it is on input.

nMaxFit

Number of characters that fit within the extents specified by the nMaxExtent parameter of the GetCharacterPlacement function. If the GCP_MAXEXTENT or GCP_JUSTIFY value is set, this value may be less than the number of characters in the original string. This member is set regardless of whether the GCP_MAXEXTENT or GCP_JUSTIFY value is given. Unlike nGlyphs, which specifies the number of output glyphs, nMaxFit refers to the number of characters from the input string. For Latin SBCS languages, this will be the same.

Remarks

Whether the lpGlyphs, lpOutString, or neither is required depends on the results of the GetFontLanguageInfo call.

In the case of a font for a language such as English, in which none of the GCP_DBCS, GCP_REORDER, GCP_GLYPHSHAPE, GCP_LIGATE, GCP_DIACRITIC, or GCP_KASHIDA flags are returned, neither of the arrays is required for proper operation. (Though not required, they can still be used. If the lpOutString array is used, it will be exactly the same as the lpInputString passed to GetCharacterPlacement.) Note, however, that if GCP_MAXEXTENT is used, then lpOutString will contain the truncated string if it is used, NOT an exact copy of the original.

In the case of fonts for languages such as Hebrew, which DO have reordering but do not typically have extra glyph shapes, lpOutString should be used. This will give the string on the screen-readable order. However, the lpGlyphs array is not typically needed. (Hebrew can have extra glyphs, if the font is a TrueType/Open font.)

In the case of languages such as Thai or Arabic, in which GetFontLanguageInfo returns the GCP_GLYPHSHAPE flag, the lpOutString will give the display-readable order of the string passed to GetCharacterPlacement, but the values will still be the unshaped characters. For proper display, the lpGlyphs array must be used.

See Also

ExtTextOut, GetCharacterPlacement, GetFontLanguageInfo


GENERIC_MAPPING

The GENERIC_MAPPING structure defines the mapping of generic access rights to specific and standard access rights for an object. When a client application requests generic access to an object, that request is mapped to the access rights defined in this structure.

typedef struct _GENERIC_MAPPING { // gm

    ACCESS_MASK GenericRead;

    ACCESS_MASK GenericWrite;

    ACCESS_MASK GenericExecute;

    ACCESS_MASK GenericAll;

} GENERIC_MAPPING;

Members

GenericRead

Specifies an access mask defining read access to an object.

GenericWrite

Specifies an access mask defining write access to an object.

GenericExecute

Specifies an access mask defining execute access to an object.

GenericAll

Specifies an access mask defining all possible types of access to an object.

See Also

AccessCheck, AccessCheckAndAuditAlarm, CreatePrivateObjectSecurity, MapGenericMask, SetPrivateObjectSecurity, ACCESS_MASK


GLYPHMETRICS

The GLYPHMETRICS structure contains information about the placement and orientation of a glyph in a character cell.

typedef struct _GLYPHMETRICS { // glmt

    UINT  gmBlackBoxX;

    UINT  gmBlackBoxY;

    POINT gmptGlyphOrigin;

    short gmCellIncX;

    short gmCellIncY;

} GLYPHMETRICS;

Members

gmBlackBoxX

Specifies the width of the smallest rectangle that completely encloses the glyph (its “black box”).

gmBlackBoxY

Specifies the height of the smallest rectangle that completely encloses the glyph (its “black box”).

gmptGlyphOrigin

Specifies the x- and y-coordinates of the upper left corner of the smallest rectangle that completely encloses the glyph.

gmCellIncX

Specifies the horizontal distance from the origin of the current character cell to the origin of the next character cell.

gmCellIncY

Specifies the vertical distance from the origin of the current character cell to the origin of the next character cell.

Remarks

Values in the GLYPHMETRICS structure are specified in device units.

See Also

GetGlyphOutline


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.

See Also

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.

See Also

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

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.

See Also

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

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.

See Also

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

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.

See Also

NetHandleGetInfo, NetHandleSetInfo


HANDLETABLE

The HANDLETABLE structure is an array of handles, each of which identifies a graphics device interface (GDI) object.

typedef struct tagHANDLETABLE { // ht

    HGDIOBJ objectHandle[1];

} HANDLETABLE;

Members

objectHandle

Contains an array of handles.

See Also

EnhMetaFileProc, EnumMetaFileProc


HD_HITTESTINFO

The HD_HITTESTINFO structure contains information about a hit test.

typedef struct _HD_HITTESTINFO {

    POINT pt;

    UINT flags;

    int iItem;

} HD_HITTESTINFO;

Members

pt

Points to test, in client coordinates

flags

Variable that receives information about the results of a hit test. This member can be one or more of the following values:

Value	Meaning
HHT_NOWHERE	The point is inside the bounding rectangle of the header control but is not over a header item.
HHT_ONDIVIDER	The point is on the divider between two header items.
HHT_ONDIVOPEN	The point is on the divider of an item that has a width of zero. Dragging the divider reveals the item instead of resizing the item to the left of the divider.
HHT_ONHEADER	The point is inside the bounding rectangle of the header control.
HHT_TOLEFT	The point is to the left of the bounding rectangle of the header control.
HHT_TORIGHT	The point is to the right of the bounding rectangle of the header control.
Two of these values can be combined, such as when the position is above and to the left of the client area.

iItem

Receives the index of item at point, if any.

Remarks

This structure is used with the HDM_HITTEST message.

See Also

HDM_HITTEST


HD_ITEM

The HD_ITEM structure contains information about an item in a header control.

typedef struct _HD_ITEM {   hdi

    UINT     mask;

    int      cxy;

    LPTSTR   pszText;

    HBITMAP  hbm;

    int      cchTextMax;

    int      fmt;

    LPARAM   lParam;

} HD_ITEM;

Members

mask

Mask flags that indicate which of the other structure members contain valid data. This member can be a combination of the following values:

Value	Meaning
HDI_BITMAP	The hbm member is valid.
HDI_FORMAT	The fmt member is valid.
HDI_HEIGHT	The cxy member is valid and specifies the height of the item.
HDI_LPARAM	The lParam member is valid.
HDI_TEXT	The pszText and cchTextMax members are valid.
HDI_WIDTH	The cxy member is valid and specifies the width of the item.
cxy

Width or height of item.

pszText

Pointer to item string.

hbm

Handle to item bitmap.

cchTextMax

Length of item string, in characters.

fmt

A set of bit flags that specify the item’s format.

This member can include one of the following text justification or right-to-left reading order bit flags:

Value	Meaning
HDF_CENTER	Centers the contents of the item.
HDF_LEFT	Left aligns the contents of the item.
HDF_RIGHT	Right aligns the contents of the item.
HDF_RTLREADING	Displays text using right-to-left reading order on Hebrew or Arabic systems.
The preceding value is combined with one of the following values:

Value	Meaning
HDF_BITMAP	The item displays a bitmap.
HDF_OWNERDRAW	The owner window of the header control draws the item.
HDF_STRING	The item displays a string.
You can use the HDF_JUSTIFYMASK mask to isolate the text justification portion of the fmt member.

lParam

Application-defined item data.


HD_LAYOUT

The HD_LAYOUT structure contains information used to set the size and position of a header control.

typedef struct _HD_LAYOUT {  // hdl

    RECT FAR*      prc;

    WINDOWPOS FAR* pwpos;

} HD_LAYOUT;

Members

prc

Pointer to a RECT structure that contains the coordinates of a rectangle that the header control is to occupy.

pwpos

Pointer to a WINDOWPOS structure that receives information about the appropriate size and position of the header control.

Remarks

This structure is used with the HDM_LAYOUT message.

See Also

HDM_LAYOUT, RECT, WINDOWPOS


HD_NOTIFY

The HD_NOTIFY structure contains information used to process notification messages from a header control.

typedef struct _HD_NOTIFY {  // hdn

    NMHDR         hdr;

    int           iItem;

    int           iButton;

    HD_ITEM FAR*  pitem;

} HD_NOTIFY;

Members

hdr

Specifies a NMHDR structure. The code member of this structure identifies the notification message being sent. It can be one of the following notification codes: HDN_BEGINTRACK, HDN_DIVIDERDBLCLICK, HDN_ENDTRACK, HDN_ITEMCHANGED, HDN_ITEMCHANGING, HDN_ITEMCLICK, or HDN_TRACK.

iItem

Specifies the index of item associated with notification.

iButton

Specifies the index of the mouse button involved in generating the notification message. This member can be one of these values:

Value	Meaning
0	Left button
1	Right button
2	Middle button
pitem

Pointer to an HD_ITEM structure that contains information about the header item associated with the notification message.

Remarks

When a header control sends the HDN_BEGINTRACK, HDN_DIVIDERDBLCLICK, HDN_ENDTRACK, HDN_ITEMCHANGED, HDN_ITEMCHANGING, HDN_ITEMCLICK, or HDN_TRACK notification codes, it passes a pointer to an HD_NOTIFY structure as the lParam parameter of a WM_NOTIFY message.

See Also

HD_ITEM, HDN_BEGINTRACK, HDN_DIVIDERDBLCLICK, HDN_ENDTRACK, HDN_ITEMCHANGED, HDN_ITEMCHANGING, HDN_ITEMCLICK, HDN_TRACK, WM_NOTIFY


HELPINFO

The HELPINFO structure contains information about an item for which context-sensitive help has been requested.

typedef  struct  tagHELPINFO {  // hi

    UINT     cbSize;

    int      iContextType

    int      iCtrlId;

    HANDLE   hItemHandle;

    DWORD    dwContextId;

    POINT    MousePos;

} HELPINFO, FAR *LPHELPINFO;

Members

cbSize

Specifies the structure size, in bytes.

iContextType

Specifies the type of context for which help is requested. This member can be one of the following values:

Value	Meaning
HELPINFO_MENUITEM	Help requested for a menu item
HELPINFO_WINDOW	Help requested for a control or window
iCtrlId

Specifies the identifier of the window or control if iContextType is HELPINFO_WINDOW. Specifies the identifier of the menu item if iContextType is HELPINFO_MENUITEM.

hItemHandle

Identifies the child window or control if iContextType is HELPINFO_WINDOW. Identifies the associated menu if iContextType is HELPINFO_MENUITEM.

dwContextId

Specifies the help context identifier of the window or control.

MousePos

Specifies a POINT structure that contains the screen coordinates of the mouse cursor. This is useful for providing help based on the position of the mouse cursor.

See Also

POINT


HELPWININFO

The HELPWININFO structure contains the size and position of either a primary or a secondary Help window. An application can set this information by calling the WinHelp function with the HELP_SETWINPOS value.

typedef struct {    // hwi

    int   wStructSize;

    int   x;

    int   y;

    int   dx;

    int   dy;

    int   wMax;

    TCHAR rgchMember[2];

} HELPWININFO;

Members

wStructSize

Specifies the structure size, in bytes.

x

Specifies the x-coordinate of the upper-left corner of the window, in screen coordinates.

y

Specifies the y-coordinate of the upper-left corner of the window, in screen coordinates.

dx

Specifies the window width, in pixels.

dy

Specifies the window height, in pixels.

wMax

Specifies how to show the window. This member must be one of the following values:

Value	Action
SW_HIDE	Hides the window and passes activation to another window.
SW_MINIMIZE	Minimizes the specified window and activates the top-level window in the Z order.
SW_RESTORE	Same as SW_SHOWNORMAL.
SW_SHOW	Activates a window and displays it in its current size and position.
SW_SHOWMAXIMIZED	Activates the window and displays it as a maximized window.
SW_SHOWMINIMIZED	Activates the window and displays it as an icon.
SW_SHOWMINNOACTIVE	Displays the window as an icon. The window that is currently active remains active.
SW_SHOWNA	Displays the window in its current state. The window that is currently active remains active.
SW_SHOWNOACTIVATE	Displays a window in its most recent size and position. The window that is currently active remains active.
SW_SHOWNORMAL	Activates and displays the window. Whether the window is minimized or maximized, Windows restores it to its original size and position.
rgchMember

Specifies the name of the window.

Remarks

Windows Help divides the display into 1024 units in both the x- and y-directions. To create a secondary window that fills the upper-left quadrant of the display, for example, an application would specify zero for the x and y members and 512 for the dx and dy members.

See Also

WinHelp


HIGHCONTRAST

The HIGHCONTRAST structure contains information about the High Contrast Mode accessibility feature, which sets the appearance scheme of the user interface for maximum visibility for a visually-impaired user, and advises applications to comply with this appearance scheme.

typedef struct tagHIGHCONTRAST {     // hc

    UINT             cbSize;

    DWORD            dwFlags;

    LPTSTR           lpszDefaultScheme;

} HIGHCONTRAST, FAR* LPHIGHCONTRAST;

Members

cbSize

Specifies the size, in bytes, of this structure.

dwFlags

Specifies a combination of the following values:

Value	Meaning
HCF_AVAILABLE	The High Contrast Mode is available.
HCF_CONFIRMHOTKEY	A confirmation dialog appears when the the High Contrast Mode is activated by using the hot key.
HCF_HIGHCONTRASTON	The High Contrast Mode is on.
HCF_HOTKEYACTIVE	The user can turn the High Contrast Mode on and off by simultaneously pressing the left ALT, left SHIFT, and PRINT SCREEN keys.
HCF_HOTKEYAVAILABLE	The hot key associated with the High Contrast Mode can be enabled. An application can retrieve this value, but cannot set it.
HCF_HOTKEYSOUND	A siren is played when the user turns the High Contrast Mode on or off by using the hot key.
HCF_INDICATOR	A visual indicator is displayed when the High Contrast Mode is on. This value is not currently used and is ignored.
lpszDefaultScheme

Points to a string that contains the name of the default color scheme.

Remarks

An application uses this structure when calling the SystemParametersInfo function with the SPI_GETHIGHCONTRAST or SPI_SETHIGHCONTRAST value. When using SPI_GETHIGHCONTRAST, an application must specify the cbSize member of the HIGHCONTRAST structure; the SystemParametersInfo function fills the remaining members. An application must specify all structure members when using the SPI_SETHIGHCONTRAST value.

See Also

SystemParametersInfo


HSZPAIR

The HSZPAIR structure contains a DDE service name and topic name. A DDE server application can use this structure during an XTYP_WILDCONNECT transaction to enumerate the service-topic pairs that it supports.

typedef struct tagHSZPAIR {   // hp

    HSZ hszSvc;

    HSZ hszTopic;

} HSZPAIR;

Members

hszSvc

Identifies a service name.

hszTopic

Identifies a topic name.


HW_PROFILE_INFO [New - Windows NT]
HW_PROFILE_INFO

[New - Windows NT]

The HW_PROFILE_INFO structure contains information about a hardware profile. The GetCurrentHwProfile function uses this structure to retrieve the current hardware profile for the local computer.

typedef struct tagHW_PROFILE_INFO {

    DWORD           dwDockInfo;

    TCHAR           szHwProfileGuid[HW_PROFILE_GUIDLEN];

    TCHAR           szHwProfileName[MAX_PROFILE_LEN];

} HW_PROFILE_INFO, *LPHW_PROFILE_INFO;

Members

dwDockInfo

A set of bit flags that indicate the docking state of the computer. This member can be a combination of the following values.

Value	Meaning
DOCKINFO_DOCKED	The computer is docked. This flag is always set for desktop systems that cannot be undocked.
DOCKINFO_UNDOCKED	The computer is undocked. This flag is always set for desktop systems that cannot be undocked.
DOCKINFO_USER_SUPPLIED	If this flag is set, GetCurrentHwProfile retrieved the current docking state from information provided by the user in the Hardware Profiles page of the System control panel application.  Currently, Windows NT and Windows 95 are not able to detect the docking state. Consequently, this flag is always set.
DOCKINFO_USER_DOCKED	The computer is docked, according to information provided by the user. This value is a combination of the DOCKINFO_USER_SUPPLIED and DOCKINFO_DOCKED flags.
DOCKINFO_USER_UNDOCKED	The computer is undocked, according to information provided by the user. This value is a combination of the DOCKINFO_USER_SUPPLIED and DOCKINFO_UNDOCKED flags.
szHwProfileGuid

A null-terminated string that contains the globally unique identifier (GUID) string for the current hardware profile. The string returned by GetCurrentHwProfile encloses the GUID in curly braces “{}” and includes a null-terminator; for example:

“{12340001-4980-1920-6788-123456789012}”

You can use this string as a registry subkey under your application’s configuration settings key in HKEY_CURRENT_USER. This enables you to store settings for each hardware profile.

szHwProfileName

A null-terminated string that contains the display name for the current hardware profile.

See Also

GetCurrentHwProfile


ICONINFO

The ICONINFO structure contains information about an icon or a cursor.

typedef struct _ICONINFO { // ii

   BOOL    fIcon;

   DWORD   xHotspot;

   DWORD   yHotspot;

   HBITMAP hbmMask;

   HBITMAP hbmColor;

} ICONINFO;

Members

fIcon

Specifies whether this structure defines an icon or a cursor. A value of TRUE specifies an icon; FALSE specifies a cursor.

xHotspot

Specifies the x-coordinate of a cursor’s hot spot. If this structure defines an icon, the hot spot is always in the center of the icon, and this member is ignored.

yHotspot

Specifies the y-coordinate of the cursor’s hot spot. If this structure defines an icon, the hot spot is always in the center of the icon, and this member is ignored.

hbmMask

Specifies the icon bitmask bitmap. If this structure defines a black and white icon, this bitmask is formatted so that the upper half is the icon AND bitmask and the lower half is the icon XOR bitmask. Under this condition, the height should be an even multiple of two. If this structure defines a color icon, this mask only defines the AND bitmask of the icon.

hbmColor

Identifies the icon color bitmap. This member can be optional if this structure defines a black and white icon. The AND bitmask of hbmMask is applied with the SRCAND flag to the destination; subsequently, the color bitmap is applied (using XOR) to the destination by using the SRCINVERT flag.

See Also

CreateIconIndirect, GetIconInfo


ICONMETRICS

The ICONMETRICS structure contains the scalable metrics associated with icons. This structure is used with the SystemParametersInfo function when the SPI_GETICONMETRICS or SPI_SETICONMETRICS action is specified.

typedef struct tagICONMETRICS {

    UINT    cbSize;

    int     iHorzSpacing;

    int     iVertSpacing;

    int     iTitleWrap;

    LOGFONT lfFont;

} ICONMETRICS, FAR *LPICONMETRICS;

Members

cbSize

Specifies the size of the structure, in bytes.

iHorzSpacing and iVertSpacing

Horizontal and vertical space, in pixels, for each arranged icon.

iTitleWrap

Title-wrapping flag. If this member is nonzero, icon titles wrap to a new line. If this member is zero, titles do not wrap.

lfFont

Specifies the font to use for icon titles.

See Also

SystemParametersInfo


ICONRESDIR

The ICONRESDIR structure contains the dimensions and color format of an individual icon image in a resource group.

struct ICONRESDIR {

    BYTE Width;

    BYTE Height;

    BYTE ColorCount;

    BYTE reserved;

} ICONRESDIR;

Members

Width

Specifies the width of the icon, in pixels. Acceptable values are 16, 32, and 64.

Height

Specifies the height of the icon, in pixels. Acceptable values are 16, 32, and 64.

ColorCount

Specifies the number of colors in the icon. Acceptable values are 2, 8, and 16.

reserved

Reserved; must be set to the same value as that of the reserved field in the icon file header.

Remarks

The ICONRESDIR structure is passed in the RESDIR structure if the RESDIR structure describes an icon.

See Also

RESDIR


IMAGEINFO

The IMAGEINFO structure contains information about an image in an image list. This structure is used with the ImageList_GetImageInfo function.

typedef struct _IMAGEINFO {

    HBITMAP hbmImage;  // bitmap containing the images

    HBITMAP hbmMask;   // handle to a monochrome bitmap

    int     Unused1;   // not used

    int     Unused2;   // not used

    RECT    rcImage;   // bounding rectangle of the image

} IMAGEINFO;

Members

hbmMask

Handle to a monochrome bitmap that contains the masks for the images. If the image list does not contain a mask, this member is NULL.

rcImage

Bounding rectangle of the image within the bitmap specified by hbmImage.


INPUT_RECORD

The INPUT_RECORD structure is used to report input events in the console input buffer. These records can be read from the input buffer by using the ReadConsoleInput or PeekConsoleInput function, or written to the input buffer by using the WriteConsoleInput function.

typedef struct _INPUT_RECORD { // ir

    WORD EventType;

    union {

        KEY_EVENT_RECORD KeyEvent;

        MOUSE_EVENT_RECORD MouseEvent;

        WINDOW_BUFFER_SIZE_RECORD WindowBufferSizeEvent;

        MENU_EVENT_RECORD MenuEvent;

        FOCUS_EVENT_RECORD FocusEvent;

    } Event;

} INPUT_RECORD;

Members

EventType

Identifies the type of input event and the event record stored in the Event member.

This member can have one of the following values:

Value	Meaning
KEY_EVENT
	The Event member contains a KEY_EVENT_RECORD structure with information about a keyboard event.
MOUSE_EVENT
	The Event member contains a MOUSE_EVENT_RECORD structure with information about a mouse movement or button press event.
WINDOW_BUFFER_SIZE_EVENT
	The Event member contains a WINDOW_BUFFER_SIZE_RECORD structure with information about the new size of the screen buffer.
MENU_EVENT
	The Event member contains a MENU_EVENT_RECORD structure. These events are used internally and should be ignored.
FOCUS_EVENT
	The Event member contains a FOCUS_EVENT_RECORD structure. These events are used internally and should be ignored.
Event

Contains a KEY_EVENT_RECORD, MOUSE_EVENT_RECORD, WINDOW_BUFFER_SIZE_RECORD, MENU_EVENT_RECORD, or FOCUS_EVENT_RECORD structure, depending on the event type specified by the EventType member.

See Also

FOCUS_EVENT_RECORD, KEY_EVENT_RECORD, MENU_EVENT_RECORD, MOUSE_EVENT_RECORD, PeekConsoleInput, ReadConsoleInput, WriteConsoleInput


ITEMIDLIST

Contains a list of item identifiers.

typedef struct _ITEMIDLIST { // idl

    SHITEMID mkid;  // list of item identifers

} ITEMIDLIST, * LPITEMIDLIST;

typedef const ITEMIDLIST * LPCITEMIDLIST;


JOB_INFO_1

The JOB_INFO_1 structure specifies print-job information such as the job-identifier value, the name of the printer for which the job is spooled, the name of the machine that created the print job, the name of the user that owns the print job, and so on.

typedef struct _JOB_INFO_1 {    // ji1

    DWORD  JobId;

    LPTSTR pPrinterName;

    LPTSTR pMachineName;

    LPTSTR pUserName;

    LPTSTR pDocument;

    LPTSTR pDatatype;

    LPTSTR pStatus;

    DWORD  Status;

    DWORD  Priority;

    DWORD  Position;

    DWORD  TotalPages;

    DWORD  PagesPrinted;

    SYSTEMTIME Submitted;

} JOB_INFO_1;

Members

JobId

Specifies a job identifier.

pPrinterName

Points to a null-terminated string that specifies the name of the printer for which the job is spooled.

pMachineName

Points to a null-terminated string that specifies the name of the machine that created the print job.

pUserName

Points to a null-terminated string that specifies the name of the user that owns the print job.

pDocument

Points to a null-terminated string that specifies the name of the print job (for example, “MS-WORD: Review.doc”).

pDatatype

Points to a null-terminated string that specifies the type of data used to record the print job.

pStatus

Points to a null-terminated string that specifies the status of the print job. This member should be checked prior to Status and, if pStatus is NULL, the status is defined by the contents of the Status member.

Status

Specifies the job status. This member can be one or more of the following values:

JOB_STATUS_DELETING
JOB_STATUS_ERROR
JOB_STATUS_OFFLINE
JOB_STATUS_PAPEROUT
JOB_STATUS_PAUSED
JOB_STATUS_PRINTED
JOB_STATUS_PRINTING
JOB_STATUS_SPOOLING

Priority

Specifies the job priority. This member can be one of the following values or in the range between 1 through 99 (MIN_PRIORITY through MAX_PRIORITY):

Value	Meaning
MIN_PRIORITY	Minimum priority.
MAX_PRIORITY	Maximum priority.
DEF_PRIORITY	Default priority.
Position

Specifies the job’s position in the print queue.

TotalPages

Specifies how many pages the document contains.

PagesPrinted

Specifies the number of pages that have printed.

Submitted

Specifies the time that this document was spooled.

See Also

EnumJobs, GetJob, SetJob


JOB_INFO_2

The JOB_INFO_2 structure describes a full set of values associated with a job.

typedef struct _JOB_INFO_2 { // ji2

    DWORD      JobId;

    LPTSTR     pPrinterName;

    LPTSTR     pMachineName;

    LPTSTR     pUserName;

    LPTSTR     pDocument;

    LPTSTR     pNotifyName;

    LPTSTR     pDatatype;

    LPTSTR     pPrintProcessor;

    LPTSTR     pParameters;

    LPTSTR     pDriverName;

    LPDEVMODE  pDevMode;

    LPTSTR     pStatus;

    PSECURITY_DESCRIPTOR pSecurityDescriptor;

    DWORD      Status;

    DWORD      Priority;

    DWORD      Position;

    DWORD      StartTime;

    DWORD      UntilTime;

    DWORD      TotalPages;

    DWORD      Size;

    SYSTEMTIME Submitted;

    DWORD      Time;

    DWORD      PagesPrinted ;

} JOB_INFO_2;

Members

JobId

Specifies a job identifier value.

pPrinterName

Points to a null-terminated string that specifies the name of the printer for which the job is spooled.

pMachineName

Points to a null-terminated string that specifies the name of the machine that created the print job.

pUserName

Points to a null-terminated string that specifies the name of the user who owns the print job.

pDocument

Points to a null-terminated string that specifies the name of the print job (for example, “MS-WORD: Review.doc”).

pNotifyName

Points to a null-terminated string that specifies the name of the user who should be notified when the job has been printed or when an error occurs while printing the job.

pDatatype

Points to a null-terminated string that specifies the type of data used to record the print job.

pPrintProcessor

Points to a null-terminated string that specifies the name of the print processor that should be used to print the job.

pParameters

Points to a null-terminated string that specifies print-processor parameters.

pDriverName

Points to a null-terminated string that specifies the name of the printer driver that should be used to process the print job.

pDevMode

Points to a DEVMODE structure that contains device-initialization and environment data for the printer driver.

pStatus

Points to a null-terminated string that specifies the status of the print job. This member should be checked prior to Status and, if pStatus is NULL, the status is defined by the contents of the Status member.

pSecurityDescriptor

The value of this member is NULL. Retrieval and setting of document security descriptors is not supported in this release.

Status

Specifies the job status. This member can be one or more of the following values:

JOB_STATUS_PAUSED
JOB_STATUS_ERROR
JOB_STATUS_DELETING
JOB_STATUS_SPOOLING
JOB_STATUS_PRINTING
JOB_STATUS_OFFLINE
JOB_STATUS_PAPEROUT
JOB_STATUS_PRINTED

Priority

Specifies the job priority. This member can be one of the following values or in the range between 1 through 99 (MIN_PRIORITY through MAX_PRIORITY):

Value	Meaning
MIN_PRIORITY	Minimum priority.
MAX_PRIORITY	Maximum priority.
DEF_PRIORITY	Default priority.
Position

Specifies the job’s position in the print queue.

StartTime

Specifies the earliest time that the job can be printed.

UntilTime

Specifies the the latest time that the job can be printed.

TotalPages

Specifies the number of pages required for the job.

Size

Specifies the size, in bytes, of the job.

Submitted

Specifies the time when the job was submitted.

Time

Specifies the total time, in seconds, that has elapsed since the job began printing.

PagesPrinted

Specifies the number of pages that have printed.

See Also

DEVMODE, EnumJobs, GetJob, SetJob


JOB_INFO_3 [New - Windows NT]
JOB_INFO_3

[New - Windows NT]

The JOB_INFO_3 structure is used to link together a set of print jobs.

typedef struct _JOB_INFO_3 { // ji2

    DWORD      JobId;

    DWORD      JobIdNextJob;

    DWORD      Reserved;

} JOB_INFO_3;

Members

JobId

Print job identifer.

JobIdNextJob

Print job identifier for the next print job in the linked set of print jobs.

Reserved

This value is reserved for future use. You must set it to zero.

See Also

EnumJobs, GetJob, SetJob


KERNINGPAIR

The KERNINGPAIR structure defines a kerning pair.

typedef struct tagKERNINGPAIR { // kp

    WORD  wFirst;

    WORD  wSecond;

    int  iKernAmount;

} KERNINGPAIR;

Members

wFirst

Specifies the character code for the first character in the kerning pair.

wSecond

Specifies the character code for the second character in the kerning pair.

iKernAmount

Specifies the amount this pair will be kerned if they appear side by side in the same font and size. This value is typically negative, because pair kerning usually results in two characters being set more tightly than normal. The value is given in logical units — that is, it depends on the current mapping mode.

See Also

GetKerningPairs


KEY_EVENT_RECORD

The KEY_EVENT_RECORD structure is used to report keyboard input events in a console INPUT_RECORD structure.

typedef struct _KEY_EVENT_RECORD { // ker

    BOOL bKeyDown;

    WORD wRepeatCount;

    WORD wVirtualKeyCode;

    WORD wVirtualScanCode;

    union {

        WCHAR UnicodeChar;

        CHAR  AsciiChar;

    } uChar;

    DWORD dwControlKeyState;

} KEY_EVENT_RECORD;

Members

bKeyDown

Specifies TRUE if the key is being pressed, FALSE if the key is being released.

wRepeatCount

Specifies a count indicating that a key is being held down. For example, when a key is held down, you might get five events with this member equal to 1, one event with this member equal to 5, or multiple events with this member greater than or equal to 1.

wVirtualKeyCode

Specifies the virtual-key code that identifies the given key in a device-independent manner.

wVirtualScanCode

Specifies the virtual scan code of the given key that represents the device-dependent value generated by the keyboard hardware.

uChar

Specifies the translated Unicode or ASCII character, depending on whether the wide-character (Unicode) or ANSI version of the ReadConsoleInput function was used.

dwControlKeyState

Indicates the state of the control keys. This member can be a combination of the following values:

Value	Meaning
CAPSLOCK_ON	The CAPS LOCK light is on.
ENHANCED_KEY	The key is enhanced.
LEFT_ALT_PRESSED	The left ALT key is pressed.
LEFT_CTRL_PRESSED	The left CTRL key is pressed.
NUMLOCK_ON	The NUM LOCK light is on.
RIGHT_ALT_PRESSED	The right ALT key is pressed.
RIGHT_CTRL_PRESSED	The right CTRL key is pressed.
SCROLLLOCK_ON	The SCROLL LOCK light is on.
SHIFT_PRESSED	The SHIFT key is pressed.
Remarks

Enhanced keys for the IBM® 101- and 102-key keyboards are the INS, DEL, HOME, END, PAGE UP, PAGE DOWN, and direction keys in the clusters to the left of the keypad; and the divide (/) and ENTER keys in the keypad.

Keyboard input events are generated when any key, including control keys, is pressed or released. However, the ALT key when pressed and released without combining with another character, has special meaning to Windows and is not passed through to the application. Also, the CTRL+C key combination is not passed through if the input handle is in processed mode (ENABLE_PROCESSED_INPUT).

See Also

PeekConsoleInput, ReadConsoleInput, WriteConsoleInput, INPUT_RECORD


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.

See Also

NCB


LARGE_INTEGER

The LARGE_INTEGER structure is used to represent a 64-bit signed integer value.

typedef union _LARGE_INTEGER {

    struct {

        DWORD LowPart;

        LONG  HighPart;

    };

    LONGLONG QuadPart;

} LARGE_INTEGER;

Members

LowPart

Specifies the low-order 32 bits.

HighPart

Specifies the high-order 32 bits.

QuadPart

Specifies a 64-bit signed integer.

Remarks

The LARGE_INTEGER structure is actually a union. If your compiler has built-in support for 64-bit integers, use the QuadPart member to store the 64-bit integer. Otherwise, use the LowPart and HighPart members to store the 64-bit integer.

See Also

LUID, ULARGE_INTEGER


LDT_ENTRY

The LDT_ENTRY structure describes an entry in the descriptor table. This structure is valid only on x86-based systems.

typedef struct _LDT_ENTRY { // ldte

    WORD LimitLow;

    WORD BaseLow;

    union {

        struct {

            BYTE BaseMid;

            BYTE Flags1;

            BYTE Flags2;

            BYTE BaseHi;

        } Bytes;

        struct {

            DWORD BaseMid : 8;

            DWORD Type : 5;

            DWORD Dpl : 2;

            DWORD Pres : 1;

            DWORD LimitHi : 4;

            DWORD Sys : 1;

            DWORD Reserved_0 : 1;

            DWORD Default_Big : 1;

            DWORD Granularity : 1;

            DWORD BaseHi : 8;

        } Bits;

    } HighWord;

} LDT_ENTRY, *PLDT_ENTRY;

Members

LimitLow

Contains the low 16 bits of the address of the last byte in the segment.

BaseLow

Contains the low 16 bits of the base address of the segment.

HighWord

Contains the high two words of the descriptor. This member may be interpreted as bytes or collections of bits, depending on the level of detail required.

The members of the Bits structure are as follows:

Member	Contents
BaseMid	Middle bits (16−23) of the base address of the segment.
Type	Bitmask that indicates the type of segment. This member can be one of the following values:
Value	Meaning
0	Read-only data segment
1	Read-write data segment
2	Unused segment
3	Read-write expand-down data segment
4	Execute-only code segment
5	Executable-readable code segment
6	Execute-only “conforming” code segment
7	Executable-readable “conforming” code segment
Dpl	Privilege level of the descriptor. This member is an integer value in the range 0 (most privileged) through 3 (least privileged).
Pres	Present flag. This member is 1 if the segment is present in physical memory or 0 if it is not.
LimitHi	High bits (16−19) of the address of the last byte in the segment.
Sys	Space that is available to system programmers. This member might be used for marking segments in some system-specific way.
Reserved_0	Reserved.
Default_Big	Size of segment. If the segment is a data segment, this member contains 1 if the segment is larger than 64 kilobytes (K) or 0 if the segment is smaller than or equal to 64K.
	If the segment is a code segment, this member contains 1 if the segment is a code segment and runs with the default (native mode) instruction set. This member contains 0 if the code segment is an 80286 code segment and runs with 16-bit offsets and the 80286-compatible instruction set.
Granularity	Granularity. This member contains 0 if the segment is byte granular, 1 if the segment is page granular.
BaseHi	High bits (24−31) of the base address of the segment.
The members of the Bytes structure are as follows:

Member	Contents
BaseMid	Middle bits (16−23) of the base address of the segment.
Flags1	Values of the Type, Dpl, and Pres members in the Bits structure.
Flags2	Values of the LimitHi, Sys, Reserved_0, Default_Big, and Granularity members in the Bits structure.
BaseHi	High bits (24−31) of the base address of the segment.
Remarks

The GetThreadSelectorEntry function fills this structure with information from an entry in the descriptor table. You can use this information to convert a segment-relative address to a linear virtual address.

The base address of a segment is the address of offset 0 in the segment. To calculate this value, combine the BaseLow, BaseMid, and BaseHi members.

The limit of a segment is the address of the last byte that can be addressed in the segment. To calculate this value, combine the LimitLow and LimitHi members.

See Also

GetThreadSelectorEntry


LIST_ENTRY

The LIST_ENTRY structure is available for any entry in a double-linked list.

typedef struct _LIST_ENTRY { // le

    struct _LIST_ENTRY *Flink;

    struct _LIST_ENTRY *Blink;

} LIST_ENTRY;

Members

Flink

Points to the preceding entry in a double-linked list.

Blink

Points to the next entry in a double-linked list.

Remarks

This structure can be used as the beginning of a double-linked list or as any subsequent entry in the list.


LOAD_DLL_DEBUG_INFO

The LOAD_DLL_DEBUG_INFO structure contains information about a dynamic-link library (DLL) that has just been loaded.

typedef struct _LOAD_DLL_DEBUG_INFO { // lddi

    HANDLE hFile;

    LPVOID lpBaseOfDll;

    DWORD  dwDebugInfoFileOffset;

    DWORD  nDebugInfoSize;

    LPVOID lpImageName;

    WORD fUnicode;

} LOAD_DLL_DEBUG_INFO;

Members

hFile

Identifies a handle of the DLL. If this member is NULL, the handle is not valid. Otherwise, the member is opened for reading and read-sharing in the context of the debugger.

lpBaseOfDll

Points to the base address of the DLL in the address space of the process loading the DLL.

dwDebugInfoFileOffset

Specifies the offset to the debugging information in the file identified by the hFile member. The kernel expects the debugging information to be in CodeView 4.0 format. This format is currently a derivative of Common Object File Format (COFF).

nDebugInfoSize

Specifies the size, in bytes, of the debugging information in the file. If this value is zero, there is no debugging information.

lpImageName

Points to the filename associated with hFile. This member may be NULL, or it may contain the address of a string pointer in the address space of the process being debugged. That address may, in turn, either be NULL or point to the actual filename. If fUnicode is a nonzero value, the name string is Unicode; otherwise, it is ANSI.

This member is strictly optional. Debuggers must be prepared to handle the case where lpImageName is NULL or *lpImageName (in the address space of the process being debugged) is NULL. Specifically, this release of Windows NT will never provide an image name for a create process event, and it will not likely pass an image name for the first DLL event. This version of Windows NT will also never provide this information in the case of debugging events that originate from a call to the DebugActiveProcess function.

fUnicode

Indicates whether a filename specified by lpImageName is Unicode or ANSI. A nonzero value for this member indicates Unicode; zero indicates ANSI.

See Also

CREATE_PROCESS_DEBUG_INFO, CREATE_THREAD_DEBUG_INFO, DebugActiveProcess, DEBUG_EVENT


LOCALESIGNATURE

The LOCALESIGNATURE structure contains extended font-signature information, including two code-page bitfields (CPBs) that define the default and supported character sets and code-pages. This structure is typically used to represent the relationships between font coverage and locales.

typedef struct tagLOCALESIGNATURE {
    DWORD  lsUsb[4];
    DWORD  lsCsbDefault[2];
    DWORD  lsCsbSupported[2];
} LOCALESIGNATURE;

Members

lsUsb

A 128-bit Unicode subset bitfield (USB) identifying up to 126 Unicode subranges. Each bit, except the two most significant bits, represents a single subrange. The most significant bit is always 1 and identifies the bitfield as a font signature; the second most significant is reserved and must be 0. Unicode subranges are numbered in accordance with the ISO 10646 standard.

lsCsbDefault

A code-page bitfield that indicates the default OEM and ANSI code-pages for a locale. The code-pages may be identified by separate bits or a single bit representing a common ANSI and OEM code-page. For a list of possible bitfield values, see Code-Page Bitfields.

lsCsbSupported

A code-page bitfield that indicates all the code-pages in which the locale can be supported. For a list of possible bitfield values, see Code-Page Bitfields.


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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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>

See Also

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.

See Also

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.

See Also

NetUserGetLocalGroups


LOCALHEADER

The LOCALHEADER structure contains the x- and y-coordinates of a hotspot associated with the cursor identified by a RESDIR structure.

typedef struct tagLOCALHEADER {

    WORD xHotSpot;

    WORD yHotSpot;

} LOCALHEADER;

Members

xHotSpot

Specifies the x-coordinate, in pixels, of the cursor hot spot.

yHotSpot

Specifies the y-coordinate, in pixels, of the cursor hot spot.

Remarks

The LOCALHEADER structure is the first data written to the RT_CURSOR resource if a RESDIR structure contains information about a cursor.

See Also

CURSORDIR, RESDIR


LOGBRUSH

The LOGBRUSH structure defines the style, color, and pattern of a physical brush. It is used by the CreateBrushIndirect and ExtCreatePen functions.

typedef struct tagLOGBRUSH { // lb

   UINT     lbStyle;

   COLORREF lbColor;

   LONG     lbHatch;

} LOGBRUSH;

Members

lbStyle

Specifies the brush style. The lbStyle member must be one of the following styles:

Value	Meaning
BS_DIBPATTERN	A pattern brush defined by a device-independent bitmap (DIB) specification. If lbStyle is BS_DIBPATTERN, the lbHatch member contains a handle to a packed DIB. Windows 95: Creating brushes from bitmaps or DIBs larger than 8x8 pixels is not supported. If a larger bitmap is given, only a portion of the bitmap is used.
BS_DIBPATTERN8X8	Same as BS_DIBPATTERN.
BS_DIBPATTERNPT	A pattern brush defined by a device-independent bitmap (DIB) specification. If lbStyle is BS_DIBPATTERNPT, the lbHatch member contains a pointer to a packed DIB.
BS_HATCHED	Hatched brush.
BS_HOLLOW	Hollow brush.
BS_NULL	Same as BS_HOLLOW.
BS_PATTERN	Pattern brush defined by a memory bitmap.
BS_PATTERN8X8	Same as BS_PATTERN.
BS_SOLID	Solid brush.
lbColor

Specifies the color in which the brush is to be drawn. If lbStyle is the BS_HOLLOW or BS_PATTERN style, lbColor is ignored.

If lbStyle is BS_DIBPATTERN or BS_DIBPATTERNBT, the low-order word of lbColor specifies whether the bmiColors members of the BITMAPINFO structure contain explicit red, green, blue (RGB) values or indices into the currently realized logical palette. The lbColor member must be one of the following values:

Value	Meaning
DIB_PAL_COLORS	The color table consists of an array of 16-bit indices into the currently realized logical palette.
DIB_RGB_COLORS	The color table contains literal RGB values.
lbHatch

Specifies a hatch style. The meaning depends on the brush style defined by lbStyle.

If lbStyle is BS_DIBPATTERN, the lbHatch member contains a handle to a packed DIB. If lbStyle is BS_DIBPATTERNPT, the lbHatch member contains a pointer to a packed DIB.

If lbStyle is BS_HATCHED, the lbHatch member specifies the orientation of the lines used to create the hatch. It can be one of the following values:

Value	Meaning
HS_BDIAGONAL	A 45-degree upward, left-to-right hatch
HS_CROSS	Horizontal and vertical cross-hatch
HS_DIAGCROSS	45-degree crosshatch
HS_FDIAGONAL	A 45-degree downward, left-to-right hatch
HS_HORIZONTAL	Horizontal hatch
HS_VERTICAL	Vertical hatch
If lbStyle is BS_PATTERN, lbHatch is a handle to the bitmap that defines the pattern. The bitmap cannot be a DIB section bitmap, which is created by the CreateDIBSection function.

If lbStyle is BS_SOLID or BS_HOLLOW, lbHatch is ignored.

Remarks

Although lbColor controls the foreground color of a hatch brush, the SetBkMode and SetBkColor functions control the background color.

See Also

BITMAPINFO, CreateBrushIndirect, CreateDIBSection, ExtCreatePen, SetBkColor, SetBkMode


LOGCOLORSPACE

The LOGCOLORSPACE structure contains information that defines a logical color space.

typedef struct tagLOGCOLORSPACE {
    DWORD         lcsSignature;

    DWORD         lcsVersion;

    DWORD         lcsSize;

    LCSCSTYPE     lcsCSType;

    LCSGAMUTMATCH lcsIntent;

    CIEXYZTRIPLE  lcsEndpoints;
    DWORD         lcsGammaRed;
    DWORD         lcsGammaGreen;

    DWORD         lcsGammaBlue;
    TCHAR         lcsFilename[MAX_PATH];

} LOGCOLORSPACE, *LPLOGCOLORSPACE;

Members

lcsSignature

Color space signature.

lcsVersion

Version number; must be 0x400.

lcsSize

Size of this structure, in bytes.

lcsCSType

Color space type. Can be one of the following values:

Value	Meaning
LCS_DEVICE_RGB	Color values are device RGB values. The values are passed to the device without translation.
LCS_DEVICE_CMYK	Color values are device CMYK values. The values are passed to the device without translation
LCS_CALIBRATED_RGB	Color values are calibrated RGB values. The values are translated using the endpoints specified by the lcsEndpoints member before being passed to the device.
If LCS_CALIBRATED_RGB is not specified, the lcsEndpoints member is ignored.

lcsIntent

The gamut matching method. Can be one of the following values:

Value	Meaning
LCS_GM_BUSINESS	Maintain saturation. Used for business charts and other situations in which undithered colors are required.
LCS_GM_GRAPHICS	Maintain colormetric match. Used for graphic designs and named colors.
LCS_GM_IMAGES	Maintain contrast. Used for photographs and natural images.
lcsEndpoints

Red, green, blue endpoints.

lcsGammaRed

Scale of the red coordinate.

lcsGammaGreen

Scale of the green coordinate.

lcsGammaBlue

Scale of the blue coordinate.

lcsFilename

A null-terminated string that names a color profile file. This member is typically set to zero, but may be used to set the color space to be exactly as specified by the color profile. This is useful for devices that input color values for a specific printer, or when using an installable image color matcher. If a color profile is specified, all other members of this structure should be set to reasonable values, even if the values are not 100 percent accurate.

See Also

RGB, CMYK


LOGFONT

The LOGFONT structure defines the attributes of a font.

typedef struct tagLOGFONT { // lf

   LONG lfHeight;

   LONG lfWidth;

   LONG lfEscapement;

   LONG lfOrientation;

   LONG lfWeight;

   BYTE lfItalic;

   BYTE lfUnderline;

   BYTE lfStrikeOut;

   BYTE lfCharSet;

   BYTE lfOutPrecision;

   BYTE lfClipPrecision;

   BYTE lfQuality;

   BYTE lfPitchAndFamily;

   TCHAR lfFaceName[LF_FACESIZE];

} LOGFONT;

Members

lfHeight

Specifies the height, in logical units, of the font’s character cell or character. The character height value (also known as the em height) is the character cell height value minus the internal-leading value. The font mapper interprets the value specified in lfHeight in the following manner:

Value	Meaning
> 0	The font mapper transforms this value into device units and matches it against the cell height of the available fonts.
0	The font mapper uses a default height value when it searches for a match.
< 0	The font mapper transforms this value into device units and matches its absolute value against the character height of the available fonts.
For all height comparisons, the font mapper looks for the largest font that does not exceed the requested size.

This mapping occurs when the font is used for the first time.

For the MM_TEXT mapping mode, you can use the following formula to specify a height for a font with a given point size:

lfHeight = -MulDiv(PointSize, GetDeviceCaps(hDC, LOGPIXELSY), 72);

lfWidth

Specifies the average width, in logical units, of characters in the font. If lfWidth is zero, the aspect ratio of the device is matched against the digitization aspect ratio of the available fonts to find the closest match, determined by the absolute value of the difference.

lfEscapement

Specifies the angle, in tenths of degrees, between the escapement vector and the x-axis of the device. The escapement vector is parallel to the base line of a row of text.

Windows NT:

When the graphics mode is set to GM_ADVANCED, you can specify the escapement angle of the string independently of the orientation angle of the string’s characters.

When the graphics mode is set to GM_COMPATIBLE, lfEscapement specifies both the escapement and orientation. You should set lfEscapement and lfOrientation to the same value.

Windows 95:

The lfEscapement member specifies both the escapement and orientation. You should set lfEscapement and lfOrientation to the same value.

lfOrientation

Specifies the angle, in tenths of degrees, between each character’s base line and the x-axis of the device.

lfWeight

Specifies the weight of the font in the range 0 through 1000. For example, 400 is normal and 700 is bold. If this value is zero, a default weight is used.

The following values are defined for convenience:

Value	Weight
FW_DONTCARE	0
FW_THIN	100
FW_EXTRALIGHT	200
FW_ULTRALIGHT	200
FW_LIGHT	300
FW_NORMAL	400
FW_REGULAR	400
FW_MEDIUM	500
FW_SEMIBOLD	600
FW_DEMIBOLD	600
FW_BOLD	700
FW_EXTRABOLD	800
FW_ULTRABOLD	800
FW_HEAVY	900
FW_BLACK	900
lfItalic

Specifies an italic font if set to TRUE.

lfUnderline

Specifies an underlined font if set to TRUE.

lfStrikeOut

Specifies a strikeout font if set to TRUE.

lfCharSet

Specifies the character set. The following values are predefined:

ANSI_CHARSET
DEFAULT_CHARSET
SYMBOL_CHARSET
SHIFTJIS_CHARSET
GB2312_CHARSET
HANGEUL_CHARSET
CHINESEBIG5_CHARSET
OEM_CHARSET

Windows 95 only:

JOHAB_CHARSET
HEBREW_CHARSET
ARABIC_CHARSET
GREEK_CHARSET
TURKISH_CHARSET
THAI_CHARSET
EASTEUROPE_CHARSET
RUSSIAN_CHARSET
MAC_CHARSET
BALTIC_CHARSET

The OEM_CHARSET value specifies a character set that is operating-system dependent.

You can use the DEFAULT_CHARSET value to allow the name and size of a font to fully describe the logical font. If the specified font name does not exist, a font from any character set can be substituted for the specified font, so you should use DEFAULT_CHARSET sparingly to avoid unexpected results.

Fonts with other character sets may exist in the operating system. If an application uses a font with an unknown character set, it should not attempt to translate or interpret strings that are rendered with that font.

This parameter is important in the font mapping process. To ensure consistent results, specify a specific character set. If you specify a typeface name in the lfFaceName member, make sure that the lfCharSet value matches the character set of the typeface specified in lfFaceName.

lfOutPrecision

Specifies the output precision. The output precision defines how closely the output must match the requested font’s height, width, character orientation, escapement, pitch, and font type. It can be one of the following values:

Value	Meaning
OUT_CHARACTER_PRECIS	Not used.
OUT_DEFAULT_PRECIS	Specifies the default font mapper behavior.
OUT_DEVICE_PRECIS	Instructs the font mapper to choose a Device font when the system contains multiple fonts with the same name.
OUT_OUTLINE_PRECIS	Windows NT: This value instructs the font mapper to choose from TrueType and other outline-based fonts. Windows 95: This value is not used.
OUT_RASTER_PRECIS	Instructs the font mapper to choose a raster font when the system contains multiple fonts with the same name.
OUT_STRING_PRECIS	This value is not used by the font mapper, but it is returned when raster fonts are enumerated.
OUT_STROKE_PRECIS	Windows NT: This value is not used by the font mapper, but it is returned when TrueType, other outline-based fonts, and vector fonts are enumerated.  Windows 95: This value is used to map vector fonts, and is returned when TrueType or vector fonts are enumerated.
OUT_TT_ONLY_PRECIS	Instructs the font mapper to choose from only TrueType fonts. If there are no TrueType fonts installed in the system, the font mapper returns to default behavior.
OUT_TT_PRECIS	Instructs the font mapper to choose a TrueType font when the system contains multiple fonts with the same name.
Applications can use the OUT_DEVICE_PRECIS, OUT_RASTER_PRECIS, and OUT_TT_PRECIS values to control how the font mapper chooses a font when the operating system contains more than one font with a given name. For example, if an operating system contains a font named Symbol in raster and TrueType form, specifying OUT_TT_PRECIS forces the font mapper to choose the TrueType version. Specifying OUT_TT_ONLY_PRECIS forces the font mapper to choose a TrueType font, even if it must substitute a TrueType font of another name.

lfClipPrecision

Specifies the clipping precision. The clipping precision defines how to clip characters that are partially outside the clipping region. It can be one or more of the following values:

Value	Meaning
CLIP_DEFAULT_PRECIS	Specifies default clipping behavior.
CLIP_CHARACTER_PRECIS	Not used.
CLIP_STROKE_PRECIS	Not used by the font mapper, but is returned when raster, vector, or TrueType fonts are enumerated. Windows NT: For compatibility, this value is always returned when enumerating fonts.
CLIP_MASK	Not used.
CLIP_EMBEDDED	You must specify this flag to use an embedded read-only font.
CLIP_LH_ANGLES	When this value is used, the rotation for all fonts depends on whether the orientation of the coordinate system is left-handed or right-handed.  If not used, device fonts always rotate counterclockwise, but the rotation of other fonts is dependent on the orientation of the coordinate system. For more information about the orientation of coordinate systems, see the description of the nOrientation parameter
CLIP_TT_ALWAYS	Not used.
lfQuality

Specifies the output quality. The output quality defines how carefully the graphics device interface (GDI) must attempt to match the logical-font attributes to those of an actual physical font. It can be one of the following values:

Value	Meaning
DEFAULT_QUALITY	Appearance of the font does not matter.
DRAFT_QUALITY	Appearance of the font is less important than when PROOF_QUALITY is used. For GDI raster fonts, scaling is enabled, which means that more font sizes are available, but the quality may be lower. Bold, italic, underline, and strikeout fonts are synthesized if necessary.
PROOF_QUALITY	Character quality of the font is more important than exact matching of the logical-font attributes. For GDI raster fonts, scaling is disabled and the font closest in size is chosen. Although the chosen font size may not be mapped exactly when PROOF_QUALITY is used, the quality of the font is high and there is no distortion of appearance. Bold, italic, underline, and strikeout fonts are synthesized if necessary.
lfPitchAndFamily

Specifies the pitch and family of the font. The two low-order bits specify the pitch of the font and can be one of the following values:

DEFAULT_PITCH
FIXED_PITCH
VARIABLE_PITCH

Bits 4 through 7 of the member specify the font family and can be one of the following values:

FF_DECORATIVE
FF_DONTCARE
FF_MODERN
FF_ROMAN
FF_SCRIPT
FF_SWISS

The proper value can be obtained by using the Boolean OR operator to join one pitch constant with one family constant.

Font families describe the look of a font in a general way. They are intended for specifying fonts when the exact typeface desired is not available. The values for font families are as follows:

Value	Meaning
FF_DECORATIVE	Novelty fonts. Old English is an example.
FF_DONTCARE	Don’t care or don’t know.
FF_MODERN	Fonts with constant stroke width (monospace), with or without serifs. Monospace fonts are usually modern. Pica, Elite, and CourierNew® are examples.
FF_ROMAN	Fonts with variable stroke width (proportional) and with serifs. MS® Serif is an example.
FF_SCRIPT	Fonts designed to look like handwriting. Script and Cursive are examples.
FF_SWISS	Fonts with variable stroke width (proportional) and without serifs. MS® Sans Serif is an example.
lfFaceName

A null-terminated string that specifies the typeface name of the font. The length of this string must not exceed 32 characters, including the null terminator. The EnumFontFamilies function can be used to enumerate the typeface names of all currently available fonts. If lfFaceName is an empty string, GDI uses the first font that matches the other specified attributes.

See Also

CreateFont, CreateFontIndirect, EnumFontFamilies


LOGPALETTE

The LOGPALETTE structure defines a logical color palette.

typedef struct tagLOGPALETTE { // lgpl

    WORD         palVersion;

    WORD         palNumEntries;

    PALETTEENTRY palPalEntry[1];

} LOGPALETTE;

Members

palVersion

Specifies the Windows version number for the structure (currently 0x300).

palNumEntries

Specifies the number of entries in the logical color palette.

palPalEntry

Specifies an array of PALETTEENTRY structures that define the color and usage of each entry in the logical palette.

Remarks

The colors in the palette-entry table should appear in order of importance because entries earlier in the logical palette are most likely to be placed in the system palette.

See Also

CreatePalette, PALETTEENTRY


LOGPEN

The LOGPEN structure defines the style, width, and color of a pen. The CreatePenIndirect function uses the LOGPEN structure.

typedef struct tagLOGPEN { // lgpn

    UINT     lopnStyle;

    POINT    lopnWidth;

    COLORREF lopnColor;

} LOGPEN;

Members

lopnStyle

Specifies the pen style, which can be one of the following values:

Value	Meaning
PS_SOLID	Pen is solid.
PS_DASH	Pen is dashed.
PS_DOT	Pen is dotted.
PS_DASHDOT	Pen has alternating dashes and dots.
PS_DASHDOTDOT	Pen has dashes and double dots.
PS_NULL	Pen is invisible.
PS_INSIDEFRAME	Pen is solid. When this pen is used in any graphics device interface (GDI) drawing function that takes a bounding rectangle, the dimensions of the figure are shrunk so that it fits entirely in the bounding rectangle, taking into account the width of the pen. This applies only to geometric pens.
lopnWidth

Specifies the POINT structure that contains the pen width, in logical units. If the pointer member is NULL, the pen is one pixel wide on raster devices. The y member in the POINT structure for lopnWidth is not used.

lopnColor

Specifies the pen color.

Remarks

If the width of the pen is greater than 1 and the pen style is PS_INSIDEFRAME, the line is drawn inside the frame of all GDI objects except polygons and polylines. If the pen color does not match an available red, green, blue (RGB) value, the pen is drawn with a logical (dithered) color. If the pen width is less than or equal to 1, the PS_INSIDEFRAME style is identical to the PS_SOLID style.

See Also

CreatePenIndirect, POINT, RGB


LS_CHALLDATA

Notice:This is preliminary documentation for technology that will be supported in future releases of Microsoft Windows.

The LS_CHALLDATA structure is passed in the LS_CHALLENGE structure. The LS_CHALLDATA structure passes the challenge from the application to the license system, and passes the response from the license system back to the application.

typedef struct _LS_CHALLDATA {

    LS_ULONG SecretIndex;

    LS_ULONG Random;

    LS_MSG_DIGEST MsgDigest;

} LS_CHALLDATA;

Members

SecretIndex

Specifies the index of the secret value to be challenged. Note: The secret index is 1-based, so the first secret must have an index of 1.

Random

Specifies a random 32-bit value.

MsgDigest

Structure that contains the message digest that is computed by the MD4 Message-Digest Algorithm from RSA Data Security, Inc.

Remarks

In the basic challenge protocol, the application must choose the index of the secret to be challenged, and it must generate a random number. It must then compute a message digest using the MD4 Message-Digest Algorithm. The input to the algorithm is formed by concatenating the input parameters to the function being called, the random number, the index of the secret to be challenged, and the actual secret value. The first input parameter should be the name of the license service function being called, either LSRequest or LSUpdate. All parameters should be in the order specified in the prototypes for those functions, and you should exclude the values of the Challenge and LicenseHandle parameters. Copy string parameters without null terminators. The application then passes the algorithm output to the license system.

The license system authenticates the message digest and computes a new message digest consisting of the input parameters to the license service function, the output parameters, the random number, the index of the secret to be challenged, and the actual secret value. The last output parameter should be the returned status. This new message digest is passed back to the application, which, in turn, authenticates it. All parameters should be in the order specified in the prototypes for the LSRequest or LSUpdate function, and you should exclude the values of the Challenge and LicenseHandle parameters. Note that the actual secret value never passes between the application and the license system in plain text.

If the function h(x) is the algorithm that, given input x, returns the output of the MD4 Message-Digest Algorithm, then the following briefly illustrates the basic protocol.

The application passes the LS_CHALLDATA structure to the license system:

R, X, h(in + R + X + S (X) )

The license system passes a new LS_MSG_DIGEST to the application:

h(in + out + R + X + S (X) )

where R is the random number, X is the index of the secret to be challenged, in is a byte stream that encodes the input parameters, S indicates a secret, S (X)  is the actual secret value, out is a byte stream that encodes the output parameters, and + denotes concatenation.

This data format can be invalid if the Protocol specified in the LS_CHALLENGE structure is not LS_BASIC_PROTOCOL. Other protocols may define their own LS_CHALLDATA format.

See Also

LS_CHALLENGE, LS_MSG_DIGEST


LS_CHALLENGE

Notice:This is preliminary documentation for technology that will be supported in future releases of Microsoft Windows.

The LS_CHALLENGE structure is used for both the challenge and the response of the LSRequest and LSUpdate license service functions. It is the main structure in the challenge/response mechanism, and it is supported by all challenge/response protocols.

typedef struct _LS_CHALLENGE {

    LS_ULONG Protocol;

    LS_ULONG Size;

    LS_CHALLDATA ChallengeData;

} LS_CHALLENGE;

Members

Protocol

Specifies the protocol setting for license authentication.

Size

Specifies the size, in bytes, of the ChallengeData (LS_CHALLDATA) structure.

ChallengeData

Structure that contains the challenge that the application passes to the license system, and the response the license system returns to the application.

Remarks

Use the LS_CHALLDATA structure to pass the challenge to the license system. The license system also returns the challenge response in the LS_CHALLDATA structure. Therefore, the number of bytes specified in the Size member on entry must be large enough to accommodate the challenge response. If the structure is not large enough to accommodate it, the error LS_BUFFER_TOO_SMALL is returned.

Because the LS_CHALLDATA structure can vary depending on the protocol specified in the Protocol member, this structure must be a single contiguous entity in memory, and must not exceed the number of bytes specified in the Size member. It cannot contain any pointers.

LSAPI passes the Protocol, the Size of the LS_CHALLDATA structure, and the actual data contained in the structure to the license system. The license system, in turn, casts the byte sequence into the appropriate structure based on the Protocol specified.

The constant value LS_BASIC_PROTOCOL specifies a standard basic challenge protocol that is supported by all LSAPI-compliant license systems. When the Protocol specified is LS_OUT_OF_BAND_PROTOCOL, there is no challenge and no response.

See Also

LS_CHALLDATA, LS_MSG_DIGEST


LS_MSG_DIGEST

Notice:This is preliminary documentation for technology that will be supported in future releases of Microsoft Windows.

The LS_MSG_DIGEST structure is passed in the LS_CHALLDATA structure. The MD4 Message-Digest Algorithm from RSA Data Security, Inc., computes the LS_MSG_DIGEST structure by using the following elements as input: the input and output parameters to the LSRequest or LSUpdate license service functions; a random number; the index of an application secret; and the actual application secret.

typedef struct _LS_MSG_DIGEST {

    LS_STR MessageDigest[16];

} LS_MSG_DIGEST;

Members

MessageDigest[16]

Specifies a 128-bit message digest that is the output of the MD4 Message-Digest Algorithm.

See Also

LS_CHALLDATA, LS_CHALLENGE


LUID

An LUID is a 64-bit value guaranteed to be unique only on the system on which it was generated. The uniqueness of a locally unique identifier (LUID) is guaranteed only until the system is restarted.

An LUID is not for direct manipulation. Applications are to use functions and structures to manipulate LUID values.

typedef LARGE_INTEGER LUID

See Also

AllocateLocallyUniqueId, LookupPrivilegeName, LookupPrivilegeValue, PrivilegeCheck, LUID_AND_ATTRIBUTES, PRIVILEGE_SET


LUID_AND_ATTRIBUTES

The LUID_AND_ATTRIBUTES structure represents a locally unique identifier (LUID) and its attributes.

typedef struct _LUID_AND_ATTRIBUTES { // luaa

    LUID   Luid;

    DWORD  Attributes;

} LUID_AND_ATTRIBUTES;

Members

Luid

Specifies an LUID value.

Attributes

Specifies attributes of the LUID. This value contains up to 32 one-bit flags. Its meaning is dependent on the definition and use of the LUID.

Remarks

An LUID_AND_ATTRIBUTES structure can represent an LUID whose attributes change frequently, such as when it is used to represent privileges in the PRIVILEGE_SET structure. Privileges are represented by LUIDs and have attributes indicating whether they are currently enabled or disabled.

See Also

AllocateLocallyUniqueId, LUID, PRIVILEGE_SET, TOKEN_PRIVILEGES


LV_COLUMN

The LV_COLUMN structure contains information about a column in a list view control. This structure is also used to receive information about a column.

typedef struct _LV_COLUMN {

    UINT mask;

    int fmt;

    int cx;

    LPTSTR pszText;

    int cchTextMax;

    int iSubItem;

} LV_COLUMN;

Members

mask

Specifies which members of this structure contain valid information. This member can be zero, or one or more of the following values:

Value	Meaning
LVCF_FMT	The fmt member is valid.
LVCF_SUBITEM	The iSubItem member is valid.
LVCF_TEXT	The pszText member is valid.
LVCF_WIDTH	The cx member is valid.
fmt

Specifies the alignment of the column heading and the subitem text in the column. This member can be one of the following values:

Value	Meaning
LVCFMT_CENTER	Text is centered.
LVCFMT_LEFT	Text is left-aligned.
LVCFMT_RIGHT	Text is right-aligned.
The leftmost column in a list view control must be left aligned.

cx

Specifies the width, in pixels, of the column.

pszText

Pointer to a null-terminated string that contains the column heading if the structure contains information about a column. If the structure is receiving information about a column, this member specifies the address of the buffer that receives the column heading.

cchTextMax

Specifies the size, in characters, of the buffer pointed to by the pszText member. If the structure is not receiving information about a column, this member is ignored.

iSubItem

Specifies the index of subitem associated with column.

Remarks

This structure is used with the LVM_GETCOLUMN, LVM_SETCOLUMN, LVM_INSERTCOLUMN, and LVM_DELETECOLUMN messages.

See Also

LVM_DELETECOLUMN, LVM_GETCOLUMN, LVM_INSERTCOLUMN, LVM_SETCOLUMN


LV_DISPINFO

The LV_DISPINFO structure contains information needed to display an owner-drawn item in a list view control.

typedef struct tagLV_DISPINFO {

    NMHDR   hdr;

    LV_ITEM item;

} LV_DISPINFO;

Members

hdr

Specifies a NMHDR structure. The code member of this structure identifies the notification message being sent. It can be one of the following notification codes: LVN_GETDISPINFO or LVN_SETDISPINFO.

item

Specifies an LV_ITEM structure that identifies the item or subitem. The structure either contains or receives information about the item. The mask member contains a set of bit flags that specify which item attributes are relevant. You can set one or more of the following bit flags:

Value	Meaning
LVIF_IMAGE	The iImage member specifies, or is to receive, the index of the item’s icon in the image list.
LVIF_STATE	The state member specifies, or is to receive, the state of the item.
LVIF_TEXT	The pszText member specifies the new item text or the address of a buffer that is to receive the item text.
If the structure is receiving item text, the pszText and cchTextMax members specify the address and size of a buffer. You can either copy text to the buffer or assign the address of a string to the pszText member. In the latter case, you must not change or delete the string until the corresponding item text is deleted or two additional LVN_GETDISPINFO messages have been sent.

If you are handling the LVN_GETDISPINFO message, you can set the LVIF_DI_SETITEM flag in the mask member. This tells the operating system to store the requested list item information, and not ask for it again.

Remarks

When a list view control sends the LVN_GETDISPINFO or LVN_SETDISPINFO notification codes, it passes a pointer to an LV_DISPINFO structure as the lParam parameter of a WM_NOTIFY message.

See Also

LV_ITEM, LVN_GETDISPINFO, LVN_SETDISPINFO, WM_NOTIFY


LV_FINDINFO

The LV_FINDINFO structure contains information used to search for a list view item.

typedef struct _LV_FINDINFO {

    UINT flags;

    LPCTSTR psz;

    LPARAM lParam;

    POINT pt;

    UINT vkDirection;

} LV_FINDINFO;

Members

flags

Type of search to perform. This member can be one or more of the following values:

Value	Meaning
LVFI_PARAM	Searches based on the lParam member. The lParam member of the matching item’s LV_ITEM structure must match the lParam member of this structure. If this value is specified, all other values are ignored.
LVFI_PARTIAL	Matches if the item text begins with the string pointed to by the psz member. This value implies use of LVFI_STRING.
LVFI_STRING	Searches based on the item text. Unless additional values are specified, the item text of the matching item must exactly match the string pointed to by the psz member.
LVFI_WRAP	Continues the search at the beginning if no match is found.
LVFI_NEARESTXY	Finds the item nearest the specified position in the specified direction.
psz

Pointer to a null-terminated string to compare with the item text if flags specifies LVFI_STRING or LVFI_PARTIAL.

lParam

Value to compare with the lParam member of a list view item’s LV_ITEM structure if the flags member specifies LVFI_PARAM.

pt

POINT structure that specifies the starting position to search from. This member is used only if LVFI_NEARESTXY is specified.

vkDirection

Direction to search in. This member is used only if LVFI_NEARESTXY is specified. If this member used, it specifies the virtual-key code of an arrow key.

Remarks

The LV_FINDINFO structure is used with the LVM_FINDITEM message.

See Also

LV_ITEM, LVM_FINDITEM, POINT


LV_HITTESTINFO

The LV_HITTESTINFO structure contains information about a hit test.

typedef struct _LV_HITTESTINFO {

    POINT pt;

    UINT flags;

    int iItem;

} LV_HITTESTINFO;

Members

pt

Position to hit test, in client coordinates.

flags

Variable that receives information about the results of a hit test. This member can be one or more of the following values:

Value	Meaning
LVHT_ABOVE	The position is above the client area of the control.
LVHT_BELOW	The position is below the client area of the control.
LVHT_NOWHERE	The position is inside the list view control’s client window, but it is not over a list item.
LVHT_ONITEMICON	The position is over a list view item’s icon.
LVHT_ONITEMLABEL	The position is over a list view item’s text.
LVHT_ONITEMSTATEICON	The position is over the state image of a list view item.
LVHT_TOLEFT	The position is to the left of the list view control’s client area.
LVHT_TORIGHT	The position is to the right of the list view control’s client area.
You can use LVHT_ABOVE, LVHT_BELOW, LVHT_TOLEFT, and LVHT_TORIGHT to determine whether to scroll the contents of a list view control. Two of these values may be combined — for example, if the position is above and to the left of the client area.

You can test for LVHT_ONITEM to determine whether a specified position is over a list view item. This value is a bitwise-OR operation on LVHT_ONITEMICON, LVHT_ONITEMLABEL, and LVHT_ONITEMSTATEICON.

iItem

Receives the index of the matching item.

Remarks

This structure is used with the LVM_HITTEST message.

See Also

LVM_HITTEST


LV_ITEM

The LV_ITEM structure specifies or receives the attributes of a list view item.

typedef struct _LV_ITEM {

    UINT   mask;

    int    iItem;

    int    iSubItem;

    UINT   state;

    UINT   stateMask;

    LPTSTR  pszText;

    int    cchTextMax;

    int    iImage;       // index of the list view item’s icon

    LPARAM lParam;       // 32-bit value to associate with item

} LV_ITEM;

Members

mask

A set of bit flags that specify attributes of this data structure or of an operation that is using this structure.

The following bit flags specify the members of the LV_ITEM structure that contain valid data or need to be filled in. One or more of these bit flags may be set:

Value	Meaning
LVIF_TEXT	The pszText member is valid or needs to be filled in.
LVIF_IMAGE	The iImage member is valid or needs to be filled in.
LVIF_PARAM	The lParam member is valid or needs to be filled in.
LVIF_STATE	The state member is valid or needs to be filled in..
The following bit flag is used with the LVN_GETDISPINFO notification message:

Value	Meaning
LVIF_DI_SETITEM	The operating system should store the requested list item information, and not ask for it again.
iItem

Specifies the zero-based index of the item to which this structure refers.

iSubItem

Specifies the one-based index of the subitem to which this structure refers, or zero if this structure refers to an item rather than a subitem.

state

Specifies the current state of the item if the item’s state is being retrieved, or the new state if the item’s state is being set. The stateMask member specifies the bits of the state member that are valid. This member can be any valid combination of state values. For a list of item states, see List View Item States.

stateMask

Specifies the bits of the state member that are valid.

pszText

Pointer to a null-terminated string that contains the item text if the structure specifies item attributes. If this member is the LPSTR_TEXTCALLBACK value, the item is a callback item. Do not set the pszText member to LPSTR_TEXTCALLBACK if the list view control has LVS_SORTASCENDING or LVS_SORTDESCENDING style.

If the structure is receiving item attributes, this member is the pointer to the buffer that receives the item text.

cchTextMax

Size of the buffer pointed to by the pszText member if the structure is receiving item attributes. If the structure specifies item attributes, this member is ignored.

iImage

Index of the list view item’s icon in the icon and small icon image lists.

If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the list view control sends the parent an LVN_GETDISPINFO notification message to get the index when it needs to display the image.

lParam

A 32-bit value to associate with the item. If you use the LVM_SORTITEMS message, the list view control passes this value to the application-defined comparison function. You can also use the LVM_FINDITEM message to search a list view control for an item with a specified lParam value.

Remarks

The LV_ITEM structure is used with a number of messages, including LVM_GETITEM, LVM_SETITEM, LVM_INSERTITEM, and LVM_DELETEITEM.

See Also

LVM_DELETEITEM, LVM_GETITEM, LVM_INSERTITEM, LVM_SETITEM


LV_KEYDOWN

The LV_KEYDOWN structure contains information about a keyboard event in a list view control.

typedef struct tagLV_KEYDOWN {

    NMHDR hdr;

    WORD wVKey;

    UINT flags;

} LV_KEYDOWN;

Members

hdr

Specifies a NMHDR structure. The code member of this structure identifies the notification message being sent. It can be the LVN_KEYDOWN notification code.

wVKey

Specifies a virtual-key code.

flags

This member is always zero.

Remarks

When a list view control sends the LVN_KEYDOWN notification code, it passes a pointer to an LV_KEYDOWN structure as the lParam parameter of a WM_NOTIFY message.

See Also

LVN_KEYDOWN, WM_NOTIFY


MAT2

The MAT2 structure contains the values for a transformation matrix used by the GetGlyphOutline function.

typedef struct _MAT2 { // mt2

    FIXED eM11;

    FIXED eM12;

    FIXED eM21;

    FIXED eM22;

} MAT2;

Members

eM11

Specifies a fixed-point value for the M11 component of a 3 by 3 transformation matrix.

eM12

Specifies a fixed-point value for the M12 component of a 3 by 3 transformation matrix.

eM21

Specifies a fixed-point value for the M21 component of a 3 by 3 transformation matrix.

eM22

Specifies a fixed-point value for the M22 component of a 3 by 3 transformation matrix.

Remarks

The identity matrix produces a transformation in which the transformed graphical object is identical to the source object. In the identity matrix, the value of eM11 is 1, the value of eM12 is zero, the value of eM21 is zero, and the value of eM22 is 1.

See Also

GetGlyphOutline


MDICREATESTRUCT

The MDICREATESTRUCT structure contains information about the class, title, owner, location, and size of a multiple document interface (MDI) child window.

typedef struct tagMDICREATESTRUCT { // mdic

    LPCTSTR szClass;

    LPCTSTR szTitle;

    HANDLE  hOwner;

    int     x;

    int     y;

    int     cx;

    int     cy;

    DWORD   style;

    LPARAM  lParam;

} MDICREATESTRUCT;

Members

szClass

Points to a null-terminated string specifying the name of the window class of the MDI child window. The class name must have been registered by a previous call to the RegisterClass function.

szTitle

Points to a null-terminated string that represents the title of the MDI child window. Windows displays the title in the child window’s title bar.

hOwner

Identifies the instance of the application creating the MDI client window.

x

Specifies the initial horizontal position, in client coordinates, of the MDI child window. If this member is CW_USEDEFAULT, the MDI child window is assigned the default horizontal position.

y

Specifies the initial vertical position, in client coordinates, of the MDI child window. If this member is CW_USEDEFAULT, the MDI child window is assigned the default vertical position.

cx

Specifies the initial width, in device units, of the MDI child window. If this member is CW_USEDEFAULT, the MDI child window is assigned the default width.

cy

Specifies the initial height, in device units, of the MDI child window. If this member is set to CW_USEDEFAULT, the MDI child window is assigned the default height.

style

Specifies the style of the MDI child window. If the MDI client window was created with the MDIS_ALLCHILDSTYLES window style, this member can be any combination of the window styles listed in the description of the CreateWindow function. Otherwise, this member can be one or more of the following values:

Value	Meaning
WS_MINIMIZE	Creates an MDI child window that is initially minimized.
WS_MAXIMIZE	Creates an MDI child window that is initially maximized.
WS_HSCROLL	Creates an MDI child window that has a horizontal scroll bar.
WS_VSCROLL	Creates an MDI child window that has a vertical scroll bar.
lParam

Specifies an application-defined 32-bit value.

Remarks

When the MDI child window is created, Windows sends the WM_CREATE message to the window. The lParam parameter of WM_CREATE contains a pointer to a CREATESTRUCT structure. The lpCreateParams member of this structure contains a pointer to the MDICREATESTRUCT structure passed with the WM_MDICREATE message that created the MDI child window.

See Also

CLIENTCREATESTRUCT, CREATESTRUCT, WM_CREATE


MEASUREITEMSTRUCT

The MEASUREITEMSTRUCT structure informs Windows of the dimensions of an owner-drawn control or menu item. This allows Windows to process user interaction with the control correctly.

typedef struct tagMEASUREITEMSTRUCT {   // mis

    UINT  CtlType;      // type of control

    UINT  CtlID;        // combo box, list box, or button identifier

    UINT  itemID;       // menu item, variable-height list box, or combo box identifier

    UINT  itemWidth;    // width of menu item, in pixels

    UINT  itemHeight;   // height of single item in list box menu, in pixels

    DWORD itemData;     // application-defined 32-bit value

} MEASUREITEMSTRUCT;

Members

CtlType

Specifies the control type. This member can be one of the following values:

Value	Meaning
ODT_BUTTON	Owner-drawn button
ODT_COMBOBOX	Owner-drawn combo box
ODT_LISTBOX	Owner-drawn list box
ODT_LISTVIEW	Owner-draw listview control
ODT_MENU	Owner-drawn menu
CtlID

Specifies the identifier of the combo box, list box, or button. This member is not used for a menu.

itemID

Specifies the identifier for a menu item or the position of a list box or combo box item. This value is specified for a list box only if it has the LBS_OWNERDRAWVARIABLE style; this value is specified for a combo box only if it has the CBS_OWNERDRAWVARIABLE style.

itemWidth

Specifies the width, in pixels, of a menu item. Before returning from the message, the owner of the owner-drawn menu item must fill this member.

itemHeight

Specifies the height, in pixels, of an individual item in a list box or a menu. Before returning from the message, the owner of the owner-drawn combo box, list box, or menu item must fill out this member.

itemData

Specifies the application-defined 32-bit value associated with the menu item. For a control, this member specifies the value last assigned to the list box or combo box by the LB_SETITEMDATA or CB_SETITEMDATA message. If the list box or combo box has the LB_HASSTRINGS or CB_HASSTRINGS style, this value is initially zero. Otherwise, this value is initially the value passed to the list box or combo box in the lParam parameter of one of the following messages:

CB_ADDSTRING
CB_INSERTSTRING
LB_ADDSTRING
LB_INSERTSTRING

Remarks

The owner window of an owner-drawn control receives a pointer to the MEASUREITEMSTRUCT structure as the lParam parameter of a WM_MEASUREITEM message. The owner-drawn control sends this message to its owner window when the control is created. The owner then fills in the appropriate members in the structure for the control and returns. This structure is common to all owner-drawn controls.

If an application does not fill the appropriate members of MEASUREITEMSTRUCT, the control or menu item may not be drawn properly.

See Also

CB_ADDSTRING, CB_INSERTSTRING, CB_SETITEMDATA, LB_ADDSTRING, LB_INSERTSTRING, LB_SETITEMDATA, WM_MEASUREITEM


MEMORY_BASIC_INFORMATION

The MEMORY_BASIC_INFORMATION structure contains information about a range of pages in the virtual address space of a process. The VirtualQuery and VirtualQueryEx functions use this structure.

typedef struct _MEMORY_BASIC_INFORMATION { // mbi

    PVOID BaseAddress;            // base address of region

    PVOID AllocationBase;         // allocation base address

    DWORD AllocationProtect;      // initial access protection

    DWORD RegionSize;             // size, in bytes, of region

    DWORD State;                  // committed, reserved, free

    DWORD Protect;                // current access protection

    DWORD Type;                   // type of pages

} MEMORY_BASIC_INFORMATION;

typedef MEMORY_BASIC_INFORMATION *PMEMORY_BASIC_INFORMATION;

Members

BaseAddress

Points to the base address of the region of pages.

AllocationBase

Points to the base address of a range of pages allocated by the VirtualAlloc function. The page pointed to by the BaseAddress member is contained within this allocation range.

AllocationProtect

Specifies the access protection given when the region was initially allocated. One of the following flags can be present, along with the PAGE_GUARD and PAGE_NOCACHE protection modifier flags:

Flag	Meaning
PAGE_READONLY	Enables read access to the committed region of pages. An attempt to write to the committed region results in an access violation. If the system differentiates between read-only access and execute access, an attempt to execute code in the committed region results in an access violation.
PAGE_READWRITE	Enables both read and write access to the committed region of pages.
PAGE_WRITECOPY	Gives copy-on-write access to the committed region of pages.
PAGE_EXECUTE	Enables execute access to the committed region of pages. An attempt to read or write to the committed region results in an access violation.
PAGE_EXECUTE_READ	Enables execute and read access to the committed region of pages. An attempt to write to the committed region results in an access violation.
PAGE_EXECUTE_READWRITE	Enables execute, read, and write access to the committed region of pages.
PAGE_EXECUTE_WRITECOPY	Enables execute, read, and write access to the committed region of pages. The pages are shared read-on-write and copy-on-write.
PAGE_GUARD	Protects the page with the underlying page protection. However, access to the region causes a “guard page entered” condition to be raised in the subject process. This flag is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.
PAGE_NOACCESS	Disables all access to the committed region of pages. An attempt to read from, write to, or execute in the committed region results in an access violation exception, called a general protection (GP) fault.
PAGE_NOCACHE	Allows no caching of the committed regions of pages. The hardware attributes for the physical memory should be set to no cache. This is not recommended for general usage. It is useful for device drivers; for example, mapping a video frame buffer with no caching. This flag is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.
RegionSize

Specifies the size, in bytes, of the region beginning at the base address in which all pages have identical attributes.

State

Specifies the state of the pages in the region. One of the following states is indicated:

State	Meaning
MEM_COMMIT	Indicates committed pages for which physical storage has been allocated, either in memory or in the paging file on disk.
MEM_FREE	Indicates free pages not accessible to the calling process and available to be allocated. For free pages, the information in the AllocationBase, AllocationProtect, Protect, and Type members is undefined.
MEM_RESERVE	Indicates reserved pages where a range of the process’s virtual address space is reserved without allocating any physical storage. For reserved pages, the information in the Protect member is undefined.
Protect

Specifies the access protection of the pages in the region. One of the flags listed for the AllocationProtect member is specified.

Type

Specifies the type of pages in the region. The following types are defined:

Type	Meaning
MEM_IMAGE	Indicates that the memory pages within the region are mapped into the view of an image section.
MEM_MAPPED	Indicates that the memory pages within the region are mapped into the view of a section.
MEM_PRIVATE	Indicates that the memory pages within the region are private (not shared by other processes).
See Also

VirtualAlloc, VirtualQuery, VirtualQueryEx


MEMORYSTATUS

The MEMORYSTATUS structure contains information about current memory availability. The GlobalMemoryStatus function uses this structure.

typedef struct _MEMORYSTATUS { // mst

    DWORD dwLength;        // sizeof(MEMORYSTATUS)

    DWORD dwMemoryLoad;    // percent of memory in use

    DWORD dwTotalPhys;     // bytes of physical memory

    DWORD dwAvailPhys;     // free physical memory bytes

    DWORD dwTotalPageFile; // bytes of paging file

    DWORD dwAvailPageFile; // free bytes of paging file

    DWORD dwTotalVirtual;  // user bytes of address space

    DWORD dwAvailVirtual;  // free user bytes

} MEMORYSTATUS, *LPMEMORYSTATUS;

Members

dwLength

Indicates the size of the structure. The calling process should set this member prior to calling GlobalMemoryStatus.

dwMemoryLoad

Specifies a number between 0 and 100 that gives a general idea of current memory utilization, in which 0 indicates no memory use and 100 indicates full memory use.

dwTotalPhys

Indicates the total number of bytes of physical memory.

dwAvailPhys

Indicates the number of bytes of physical memory available.

dwTotalPageFile

Indicates the total number of bytes that can be stored in the paging file. Note that this number does not represent the actual physical size of the paging file on disk.

dwAvailPageFile

Indicates the number of bytes available in the paging file.

dwTotalVirtual

Indicates the total number of bytes that can be described in the user mode portion of the virtual address space of the calling process.

dwAvailVirtual

Indicates the number of bytes of unreserved and uncommitted memory in the user mode portion of the virtual address space of the calling process.

See Also

GlobalMemoryStatus


MENU_EVENT_RECORD

The MENU_EVENT_RECORD structure reports menu events in a console INPUT_RECORD structure. These events are used internally and should be ignored.

typedef struct _MENU_EVENT_RECORD { // mer

    UINT dwCommandId;

} MENU_EVENT_RECORD, *PMENU_EVENT_RECORD;

Members

dwCommandId

Used internally.

See Also

INPUT_RECORD


MENUEX_TEMPLATE_HEADER

The MENUEX_TEMPLATE_HEADER structure defines the header for an extended menu template. The structure definition given here is for explanation only; it is not present in any standard header file.

// typedef struct

//     WORD  wVersion;

//     WORD  wOffset;

//     DWORD dwHelpId;

// } MENUEX_TEMPLATE_HEADER;

Members

wVersion

Template version number. This member must be 1 for extended menu templates.

wOffset

Offset of the first MENUEX_TEMPLATE_ITEM structure, relative to the end of this structure member. If the first item definition immediately follows the dwHelpId member, this member should be 4.

dwHelpId

Help identifier of menu bar

Remarks

An extended menu template consists of a MENUEX_TEMPLATE_HEADER structure followed by one or more contiguous MENUEX_TEMPLATE_ITEM structures. The MENUEX_TEMPLATE_ITEM structures, which are variable in length, are aligned on doubleword boundaries. To create a menu from an extended menu template in memory, use the LoadMenuIndirect function.

See Also

LoadMenuIndirect, MENUEX_TEMPLATE_ITEM


MENUEX_TEMPLATE_ITEM

The MENUEX_TEMPLATE_ITEM structure defines a menu item in an extended menu template. The structure definition given here is for explanation only; it is not present in any standard header file.

// typedef struct {

//     DWORD  dwType;

//     DWORD  dwState;

//     UINT   uId;

//     WORD   bResInfo;

//     WCHAR  szText[1];

//     // DWORD dwHelpId;

// } MENUEX_TEMPLATE_ITEM;

Members

dwType

Menu item type. This member can be a combination of the type (beginning with MFT) values listed with the MENUITEMINFO structure.

dwState

Menu item state. This member can be a combination of the state (beginning with MFS) values listed with the MENUITEMINFO structure.

uId

Menu item identifier. This is an application-defined 16-bit value that identifies the menu item. In an extended menu resource, items that open drop-down menus or submenus as well as command items can have identifiers.

bResInfo

Value specifying whether the menu item is the last item in the menu bar, drop-down menu, submenu, or shortcut menu and whether it is an item that opens a drop-down menu or submenu. This member can be zero or more of these values:

Value	Meaning
0x80	The structure defines the last menu item in the menu bar, drop-down menu, submenu, or shortcut menu.
0x01	The structure defines a item that opens a drop-down menu or submenu. Subsequent structures define menu items in the corresponding drop-down menu or submenu.
For 32-bit applications, this member is a WORD; for 16-bit applications, it is a BYTE.

szText

Menu item text. This member, which is a null-terminated Unicode string, is aligned on a word boundary. The size of the menu item definition varies depending on the length of this string.

dwHelpId

Help identifier for a drop-down menu or submenu. This member, which is included only for items that open drop-down menus or submenus, is located at the first doubleword boundary following the variable-length szText member.

Remarks

An extended menu template consists of a MENUEX_TEMPLATE_HEADER structure followed by one or more contiguous MENUEX_TEMPLATE_ITEM structures. The MENUEX_TEMPLATE_ITEM structures, which are variable in length, are aligned on doubleword boundaries. To create a menu from an extended menu template in memory, use the LoadMenuIndirect function.

See Also

LoadMenuIndirect, MENUEX_TEMPLATE_HEADER, MENUITEMINFO


MenuHeader

The MenuHeader structure contains version information for the menu resource.

struct MenuHeader {

    WORD wVersion;

    WORD cbHeaderSize;

};

Members

wVersion

Specifies the version number of the menu template. This member must be equal to zero to indicate that this is an RT_MENU created with a standard menu template.

cbHeaderSize

Specifies the size of the menu template header. This value is zero for menus you create with a standard menu template.

See Also

MENUEX_TEMPLATE_HEADER, MENUEX_TEMPLATE_ITEM, MENUITEMTEMPLATE, MENUITEMTEMPLATEHEADER, NormalMenuItem, PopupMenuItem


MENUHELPID

The MENUHELPID structure is the final data written to the RT_MENU resource for a menu or submenu if the resInfo member of the PopupMenuItem structure is set to MFR_POPUP.

typedef struct MENUHELPID {

    DWORD helpID;

} MENUHELPID;

Member

helpID

Specifies a numeric expression indicating the identifier used to identify the menu during WM_HELP processing.

See Also

MenuHeader, PopupMenuItem


MENUITEMINFO

The MENUITEMINFO structure contains information about a menu item.

typedef struct tagMENUITEMINFO {
    UINT    cbSize;

    UINT    fMask;

    UINT    fType;

    UINT    fState;

    UINT    wID;

    HMENU   hSubMenu;

    HBITMAP hbmpChecked;

    HBITMAP hbmpUnchecked;

    DWORD   dwItemData;

    LPTSTR  dwTypeData;

    UINT    cch;

} MENUITEMINFO, FAR *LPMENUITEMINFO;

Members

cbsize

Size of structure, in bytes.

fMask

Members to retrieve or set. This member can be one or more of these values:

Value	Meaning
MIIM_CHECKMARKS	Retrieves or sets the hbmpChecked and hbmpUnchecked members.
MIIM_DATA	Retrieves or sets the dwItemData member.
MIIM_ID	Retrieves or sets the wID member.
MIIM_STATE	Retrieves or sets the fState member.
MIIM_SUBMENU	Retrieves or sets the hSubMenu member.
MIIM_TYPE	Retrieves or sets the fType and dwTypeData members.
fType

Menu item type. This member can be one or more of these values:

Value	Meaning
MFT_BITMAP	Displays the menu item using a bitmap. The low-order word of the dwTypeData member is the bitmap handle, and the cch member is ignored.
MFT_MENUBARBREAK	Places the menu item on a new line (for a menu bar) or in a new column (for a drop-down menu, submenu, or shortcut menu). For a drop-down menu, submenu, or shortcut menu, a vertical line separates the new column from the old.
MFT_MENUBREAK	Places the menu item on a new line (for a menu bar) or in a new column (for a drop-down menu, submenu, or shortcut menu). For a drop-down menu, submenu, or shortcut menu, the columns are not separated by a vertical line.
MFT_OWNERDRAW	Assigns responsibility for drawing the menu item to the window that owns the menu. The window receives a WM_MEASUREITEM message before the menu is displayed for the first time, and a WM_DRAWITEM message whenever the appearance of the menu item must be updated. If this value is specified, the dwTypeData member contains an application-defined 32-bit value.
MFT_RADIOCHECK	Displays checked menu items using a radio-button mark instead of a check mark if the hbmpChecked member is NULL.
MFT_RIGHTJUSTIFY	Right-justifies the menu item and any subsequent items. This value is valid only if the menu item is in a menu bar.
MFT_SEPARATOR	Specifies that the menu item is a separator. A menu item separator appears as a horizontal dividing line. The dwTypeData and cch members are ignored. This value is valid only in a drop-down menu, submenu, or shortcut menu.
MFT_STRING	Displays the menu item using a text string. The dwTypeData member is the pointer to a null-terminated string, and the cch member is the length of the string.
The MFT_BITMAP, MFT_SEPARATOR, and MFT_STRING values cannot be combined with one another.

fState

Menu item state. This member can be one or more of these values:

Value	Meaning
MFS_CHECKED	Checks the menu item. For more information about checked menu items, see the hbmpChecked member.
MFS_DEFAULT	Specifies that the menu item is the default. A menu can contain only one default menu item, which is displayed in bold.
MFS_DISABLED	Disables the menu item so that it cannot be selected, but does not gray it.
MFS_ENABLED	Enables the menu item so that it can be selected. This is the default state.
MFS_GRAYED	Disables the menu item and grays it so that it cannot be selected.
MFS_HILITE	Highlights the menu item.
MFS_UNCHECKED	Unchecks the menu item. For more information about unchecked menu items, see the hbmpUnchecked member.
MFS_UNHILITE	Removes the highlight from the menu item. This is the default state.
wID

Application-defined 16-bit value that identifies the menu item.

hSubMenu

Handle to the drop-down menu or submenu associated with the menu item. If the menu item is not an item that opens a drop-down menu or submenu, this member is NULL.

hbmpChecked

Handle to the bitmap to display next to the item if it is checked. If this member is NULL, a default bitmap is used. If the MFT_RADIOCHECK type value is specified, the default bitmap is a bullet. Otherwise, it is a check mark.

hbmpUnchecked

Handle to the bitmap to display next to the item if it is not checked. If this member is NULL, no bitmap is used.

dwItemData

Application-defined value associated with the menu item.

dwTypeData

Content of the menu item. The meaning of this member depends on the menu item type: the MFT_BITMAP, MFT_SEPARATOR, or MFT_STRING values.

cch

Length of the menu item text, when information is received about a menu item of the MFT_STRING type. This value is zero for other menu item types. This member is ignored when the content of a menu item is set.

Remarks

The MENUITEMINFO structure is used with the GetMenuItemInfo, InsertMenuItem, and SetMenuItemInfo functions.

See Also

GetMenuItemInfo, InsertMenuItem, SetMenuItemInfo, WM_DRAWITEM, WM_MEASUREITEM


MENUITEMTEMPLATE

The MENUITEMTEMPLATE structure defines a menu item in a menu template.

typedef struct {         // mit

    WORD mtOption;       // menu item flags

    WORD mtID;           // menu item identifier (omitted for pop-up items)

    WCHAR mtString[1];   // null-terminated string for menu item

} MENUITEMTEMPLATE;

Members

mtOption

Specifies one or more of the following predefined menu options that control the appearance of the menu item:

Value	Meaning
MF_CHECKED	Indicates that the menu item has a check mark next to it.
MF_GRAYED	Indicates that the menu item is initially inactive and drawn with a gray effect.
MF_HELP	Indicates that the menu item has a vertical separator to its left.
MF_MENUBARBREAK	Indicates that the menu item is placed in a new column. The old and new columns are separated by a bar.
MF_MENUBREAK	Indicates that the menu item is placed in a new column.
MF_OWNERDRAW	Indicates that the owner window of the menu is responsible for drawing all visual aspects of the menu item, including highlighted, checked, and inactive states. This option is not valid for an item in a menu bar.
MF_POPUP	Indicates that the item is one that opens a drop-down menu or submenu.
mtID

Specifies the menu item identifier of a command item; a command item sends a command message to its owner window. The MENUITEMTEMPLATE structure for an item that opens a drop-down menu or submenu does not contain the mtID member.

mtString

Specifies the null-terminated string for the menu item.

See Also

LoadMenuIndirect, MENUITEMTEMPLATEHEADER


MENUITEMTEMPLATEHEADER

The MENUITEMTEMPLATEHEADER structure defines the header for a menu template. A complete menu template consists of a header and one or more menu item lists.

typedef struct {          // mith

    WORD versionNumber;   // version number; must be zero

    WORD offset;          // offset first MENUITEMTEMPLATE structure

} MENUITEMTEMPLATEHEADER;

Members

versionNumber

Specifies the version number. This member must be zero.

offset

Specifies the offset, in bytes, from the end of the header. The menu item list begins at this offset. Usually, this member is zero, and the menu item list follows immediately after the header.

Remarks

One or more MENUITEMTEMPLATE structures are combined to form the menu item list.

See Also

LoadMenuIndirect, MENUITEMTEMPLATE


MESSAGE_RESOURCE_BLOCK

The MESSAGE_RESOURCE_BLOCK structure contains information about message strings with identifiers in the range indicated by the LowId and HighId members.

typedef struct _MESSAGE_RESOURCE_BLOCK {

    ULONG LowId;

    ULONG HighId;

    ULONG OffsetToEntries;

} MESSAGE_RESOURCE_BLOCK, *PMESSAGE_RESOURCE_BLOCK;

Members

LowId

Specifies the lowest message identifier contained within this MESSAGE_RESOURCE_BLOCK.

HighId

Specifies the highest message identifier contained within this MESSAGE_RESOURCE_BLOCK.

OffsetToEntries

Specifies the offset, in bytes, from the beginning of the MESSAGE_RESOURCE_DATA structure to the MESSAGE_RESOURCE_ENTRY structures in this MESSAGE_RESOURCE_BLOCK. The MESSAGE_RESOURCE_ENTRY structures contain the message strings.

See Also

MESSAGE_RESOURCE_DATA, MESSAGE_RESOURCE_ENTRY


MESSAGE_RESOURCE_DATA

The MESSAGE_RESOURCE_DATA structure contains information about formatted text for display as an error message or in a message box in a message table resource.

typedef struct _MESSAGE_RESOURCE_DATA {

    ULONG NumberOfBlocks;

    MESSAGE_RESOURCE_BLOCK Blocks[ 1 ];

} MESSAGE_RESOURCE_DATA, *PMESSAGE_RESOURCE_DATA;

Members

NumberOfBlocks

Specifies the number of MESSAGE_RESOURCE_BLOCK structures.

Blocks[ 1 ]

Array that contains the number of MESSAGE_RESOURCE_BLOCK structures indicated by the NumberOfBlocks member. The MESSAGE_RESOURCE_BLOCK Blocks[ 1 ] member is a placeholder for the variable length array of Blocks.

Remarks

A MESSAGE_RESOURCE_DATA structure can contain one or more MESSAGE_RESOURCE_BLOCK structures, which can each contain one or more MESSAGE_RESOURCE_ENTRY structures.

See Also

MESSAGE_RESOURCE_BLOCK, MESSAGE_RESOURCE_ENTRY


MESSAGE_RESOURCE_ENTRY

The MESSAGE_RESOURCE_ENTRY structure contains the error message or message box display text for a message table resource.

typedef struct _MESSAGE_RESOURCE_ENTRY {

    USHORT Length;

    USHORT Flags;

    UCHAR Text[ 1 ];

} MESSAGE_RESOURCE_ENTRY, *PMESSAGE_RESOURCE_ENTRY;

Members

Length

Specifies the length, in bytes, of the message string in this structure.

Flags

Indicates that the string is encoded in Unicode if equal to the value 0x0001; indicates that the string is encoded in ANSI if equal to the value 0x0000.

Text[ 1 ]

An array that contains the error message or message box display text. The Text[ 1 ] member is a placeholder for the variable-length Text array.

See Also

MESSAGE_RESOURCE_BLOCK, MESSAGE_RESOURCE_DATA


METAFILEPICT

The METAFILEPICT structure defines the metafile picture format used for exchanging metafile data through the clipboard.

typedef struct tagMETAFILEPICT { // mfp

    LONG      mm;

    LONG      xExt;

    LONG      yExt;

    HMETAFILE hMF;

} METAFILEPICT;

Members

mm

Specifies the mapping mode in which the picture is drawn.

xExt

Specifies the size of the metafile picture for all modes except the MM_ISOTROPIC and MM_ANISOTROPIC modes. (For more information about these modes, see the yExt member.) The x-extent specifies the width of the rectangle within which the picture is drawn. The coordinates are in units that correspond to the mapping mode.

yExt

Specifies the size of the metafile picture for all modes except the MM_ISOTROPIC and MM_ANISOTROPIC modes. The y-extent specifies the height of the rectangle within which the picture is drawn. The coordinates are in units that correspond to the mapping mode.

For MM_ISOTROPIC and MM_ANISOTROPIC modes, which can be scaled, the xExt and yExt members contain an optional suggested size in MM_HIMETRIC units. For MM_ANISOTROPIC pictures, xExt and yExt can be zero when no suggested size is supplied. For MM_ISOTROPIC pictures, an aspect ratio must be supplied even when no suggested size is given. (If a suggested size is given, the aspect ratio is implied by the size.) To give an aspect ratio without implying a suggested size, set xExt and yExt to negative values whose ratio is the appropriate aspect ratio. The magnitude of the negative xExt and yExt values is ignored; only the ratio is used.

hMF

Identifies a memory metafile.

See Also

SetClipboardData


METAHEADER

The METAHEADER structure contains information about a Windows-format metafile.

typedef struct tagMETAHEADER {  // mh

    WORD  mtType;

    WORD  mtHeaderSize;

    WORD  mtVersion;

    DWORD mtSize;

    WORD  mtNoObjects;

    DWORD mtMaxRecord;

    WORD  mtNoParameters;

} METAHEADER;

Members

mtType

Specifies whether the metafile is in memory or recorded in a disk file. This member can be one of the following values:

Value	Meaning
1	Metafile is in memory.
2	Metafile is in a disk file.
mtHeaderSize

Specifies the size, in words, of the metafile header.

mtVersion

Specifies the Windows version number. The version number for metafiles that support device-independent bitmaps (DIBs) is 0x0300. Otherwise, the version number is 0x0100.

mtSize

Specifies the size, in words, of the file.

mtNoObjects

Specifies the maximum number of objects that exist in the metafile at the same time.

mtMaxRecord

Specifies the size, in words, of the largest record in the metafile.

mtNoParameters

Reserved.

See Also

METARECORD


METARECORD

The METARECORD structure contains a Windows-format metafile record.

typedef struct tagMETARECORD {  // mr

    DWORD rdSize;

    WORD  rdFunction;

    WORD  rdParm[1];

} METARECORD;

Members

rdSize

Specifies the size, in words, of the record.

rdFunction

Specifies the function number.

rdParm

Specifies an array of words containing the function parameters, in reverse of the order they are passed to the function.

See Also

METAHEADER


MINIMIZEDMETRICS

The MINIMIZEDMETRICS structure contains the scalable metrics associated with minimized windows. This structure is used with the SystemParametersInfo function when the SPI_GETMINIMIZEDMETRICS or SPI_SETMINIMIZEDMETRICS action value is specified.

typedef struct tagMINIMIZEDMETRICS {

    UINT    cbSize;

    int     iWidth;

    int     iHorzGap;

    int     iVertGap;

    int     iArrange;

}   MINIMIZEDMETRICS, FAR *LPMINIMIZEDMETRICS;

Members

cbSize

Specifies the size of the structure, in bytes.

iWidth

Specifies the width, in pixels, of minimized windows.

iHorzGap and iVertGap

Specifies the amount of horizontal and vertical space, in pixels, between arranged minimized windows.

iArrange

Specifies the starting position and direction used when arranging minimized windows. The starting position must be one of the following values:

Value	Meaning
ARW_BOTTOMLEFT	Start at the lower-left corner of the work area.
ARW_BOTTOMRIGHT	Start at the lower-right corner of the work area.
ARW_TOPLEFT	Start at the upper-left corner of the work area.
ARW_TOPRIGHT	Start at the upper-right corner of the work area.
The direction must be one of the following values:

Value	Meaning
ARW_LEFT	Arrange left (valid with ARW_BOTTOMRIGHT and ARW_TOPRIGHT only).
ARW_RIGHT	Arrange right (valid with ARW_BOTTOMLEFT and ARW_TOPLEFT only).
ARW_UP	Arrange up (valid with ARW_BOTTOMLEFT and ARW_BOTTOMRIGHT only).
ARW_DOWN	Arrange down (valid with ARW_TOPLEFT and ARW_TOPRIGHT only).
See Also

SystemParametersInfo


MINMAXINFO

The MINMAXINFO structure contains information about a window’s maximized size and position and its minimum and maximum tracking size.

typedef struct tagMINMAXINFO {  // mmi

    POINT ptReserved;

    POINT ptMaxSize;

    POINT ptMaxPosition;

    POINT ptMinTrackSize;

    POINT ptMaxTrackSize;

} MINMAXINFO;

Members

ptReserved

Reserved; do not use.

ptMaxSize

Specifies the maximized width (point.x) and the maximized height (point.y) of the window.

ptMaxPosition

Specifies the position of the left side of the maximized window (point.x) and the position of the top of the maximized window (point.y).

ptMinTrackSize

Specifies the minimum tracking width (point.x) and the minimum tracking height (point.y) of the window.

ptMaxTrackSize

Specifies the maximum tracking width (point.x) and the maximum tracking height (point.y) of the window.

See Also

POINT, WM_GETMINMAXINFO


MODEMDEVCAPS

The MODEMDEVCAPS structure contains information about the capabilities of a modem.

typedef struct modemdevcaps_tag {
    DWORD dwActualSize;               // size of returned data, in bytes
    DWORD dwRequiredSize;             // total size of structure
    DWORD dwDevSpecificOffset;        // offset of provider-defined data
    DWORD dwDevSpecificSize;          // size of provider-defined data

    // Product and version identification
    DWORD dwModemProviderVersion;     // provider version number
    DWORD dwModemManufacturerOffset;  // offset of manufacturer name
    DWORD dwModemManufacturerSize;    // length of manufacturer name
    DWORD dwModemModelOffset;         // offset of model name
    DWORD dwModemModelSize;           // length of model name
    DWORD dwModemVersionOffset;       // offset of version name
    DWORD dwModemVersionSize;         // length of version name

    // Local option capabilities
    DWORD dwDialOptions;              // bitmap of supported values
    DWORD dwCallSetupFailTimer;       // maximum in seconds
    DWORD dwInactivityTimeout;        // maximum in tenths of seconds
    DWORD dwSpeakerVolume;            // bitmap of supported values
    DWORD dwSpeakerMode;              // bitmap of supported values
    DWORD dwModemOptions;             // bitmap of supported values
    DWORD dwMaxDTERate;               // maximum value in bit/s
    DWORD dwMaxDCERate;               // maximum value in bit/s

    // Variable portion for strings and provider-specific data
    BYTE abVariablePortion [1];       // variable-length data
} MODEMDEVCAPS, *PMODEMDEVCAPS, *LPMODEMDEVCAPS;

Members

dwActualSize

Specifies the size, in bytes, of the data actually returned to the application. This member may be less than the dwRequiredSize member, if an application did not allocate enough space for the variable-length portion of the structure.

dwRequiredSize

Specifies the number of bytes required for the entire MODEMDEVCAPS structure, including the variable-length portion.

dwDevSpecificOffset

Specifies the offset of the provider-defined portion of the structure, in bytes relative to the beginning of the structure.

dwDevSpecificSize

Specifies the size of the provider-defined portion of the structure, in bytes.

dwModemProviderVersion

Specifies the version of the service provider. The format and use of this member depends on the service provider.

dwModemManufacturerOffset

Specifies the offset of a text string that contains the name of the modem manufacturer. The offset is specified in bytes relative to the beginning of the structure.

dwModemManufacturerSize

Specifies the length of the modem manufacturer name, in bytes. The string is not null-terminated.

dwModemModelOffset

Specifies the offset of a text string that contains the model of the modem. The offset is specified in bytes relative to the beginning of the structure.

dwModemModelSize

Specifies the length of the model name, in bytes. The string is not null-terminated.

dwModemVersionOffset

Specifies the offset of a text string that gives the version and revision of the attached modem, if the provider could determine the information. The offset is specified in bytes relative to the beginning of the structure.

dwModemVersionSize

Specifies the length of the modem version string, in bytes. The string is not null-terminated.

dwDialOptions

Specifies dialing options that are supported by the modem device. This member can be zero or more of the following values:

Value	Meaning
DIALOPTION_DIALBILLING	Specifies that the modem supports waiting for billing tone (bong).
DIALOPTION_DIALQUIET	Specifies that the modem supports waiting for quiet.
DIALOPTION_DIALDIALTONE	Specifies that the modem supports waiting for a dial tone.
dwCallSetupFailTimer

Specifies the maximum call setup timeout supported by the modem, in seconds. This is the largest value that can be specified for the corresponding member of the MODEMSETTINGS structure.

dwInactivityTimeout

Specifies the maximum inactivity timeout supported by the modem, in tenths of seconds. This is the largest value that can be specified for the corresponding member of the MODEMSETTINGS structure.

dwSpeakerVolume

Specifies the speaker volume settings supported by the modem. This member can be zero or more of the following values:

Value	Meaning
MDMVOLFLAG_LOW	The modem supports low (MDMVOL_LOW) volume.
MDMVOLFLAG_MEDIUM	The modem supports medium (MDMVOL_MEDIUM) volume.
MDMVOLFLAG_HIGH	The modem supports high (MDMVOL_HIGH) volume.
dwSpeakerMode

Specifies the speaker mode settings supported by the modem. This member can be zero or more of the following values:

Value	Meaning
MDMSPKRFLAG_OFF	The modem supports the MDMSPKR_OFF speaker mode.
MDMSPKRFLAG_DIAL	The modem supports the MDMSPKR_DIAL speaker mode.
MDMSPKRFLAG_ON	The modem supports the MDMSPKR_ON speaker mode.
MDMSPKRFLAG_CALLSETUP	The modem supports the MDMSPKR_CALLSETUP speaker mode.
dwModemOptions

Specifies supported modem options. This member can be zero or more of the following values:

MDM_BLIND_DIAL	MDM_FLOWCONTROL_SOFT
MDM_CCITT_OVERRIDE	MDM_FORCED_EC
MDM_CELLULAR	MDM_SPEED_ADJUST
MDM_COMPRESSION	MDM_TONE_DIAL
MDM_ERROR_CONTROL	MDM_V23_OVERRIDE
MDM_FLOWCONTROL_HARD
When MODEMDEVCAPS is used to set modem options, as part of the MODEMSETTINGS structure, these values are used as follows:

Value	Meaning
MDM_CCITT_OVERRIDE	When set, CCITT modulations are enabled for V.21 and V.22 or V.23. When clear, bell modulations are enabled for 103 and 212A.
MDM_V23_OVERRIDE	When set, CCITT modulations are enabled for V.23. When clear, CCITT modulations are enabled for V.21 and V.22.
For V.23 to be set, both MDM_CCITT_OVERRIDE and MDM_V23_OVERRIDE must be set.

dwMaxDTERate

Maximum DTE rate in bits per second.

dwMaxDCERate

Maximum DCE rate in bits per second.

abVariablePortion

Contains variable-length information, including strings and any provider-defined information.

See Also

MODEMSETTINGS


MODEMSETTINGS

The MODEMSETTINGS structure contains information about a modem’s configuration.

typedef struct modemsettings_tag {
    DWORD dwActualSize;               // size of returned data, in bytes
    DWORD dwRequiredSize;             // total size of structure
    DWORD dwDevSpecificOffset;        // offset of provider-defined data
    DWORD dwDevSpecificSize;          // size of provider-defined data

    // Static local options (read/write)
    DWORD dwCallSetupFailTimer;       // call setup timeout, in seconds
    DWORD dwInactivityTimeout;        // inactivity timeout, in tenths of seconds
    DWORD dwSpeakerVolume;            // speaker volume level
    DWORD dwSpeakerMode;              // speaker mode
    DWORD dwPreferredModemOptions;    // bitmap specifying preferred options

    // negotiated options (read only) for current or last call
    DWORD dwNegotiatedModemOptions;   // bitmap specifying actual options
    DWORD dwNegotiatedDCERate;        // DCE rate, in bits per second

    // Variable portion for proprietary expansion
    BYTE  abVariablePortion[1];       // variable-length data
} MODEMSETTINGS, *PMODEMSETTINGS, *LPMODEMSETTINGS;

Members

dwActualSize

Specifies the size, in bytes, of the data actually returned to the application. This member may be less than the dwRequiredSize member if an application did not allocate enough space for the variable-length portion of the structure.

dwRequiredSize

Specifies the number of bytes required for the entire MODEMDEVCAPS structure, including the variable-length portion.

dwDevSpecificOffset

Specifies the offset of the provider-defined portion of the structure, in bytes relative to the beginning of the structure.

dwDevSpecificSize

Specifies the size of the provider-defined portion of the structure, in bytes.

dwCallSetupFailTimer

Specifies the maximum number of seconds the modem should wait, after dialing is completed, for an indication that a modem-to-modem connection has been established. If a connection is not established in this interval, the call is assumed to have failed. This member is equivalent to register S7 in Hayes® compatible modems.

dwInactivityTimeout

Specifies the maximum number of seconds of inactivity allowed after a connection is established. If no data is either transmitted or received for this period of time, the call is automatically terminated. This time-out is used to avoid excessive long distance charges or online service charges if an application unexpectedly locks up or the user leaves.

dwSpeakerVolume

Specifies the volume level of the monitor speaker when the speaker is on. This member can be one of the following values:

Value	Meaning
MDMVOL_LOW	Low volume.
MDMVOL_MEDIUM	Medium volume.
MDMVOL_HIGH	High volume.
The MODEMDEVCAPS structure specifies the speaker volumes a modem supports. Actual volumes are hardware-specific.

dwSpeakerMode

Specifies when the speaker should be on. This member can be one of the following values:

Value	Meaning
MDMSPKR_OFF	The speaker is always off.
MDMSPKR_CALLSETUP	The speaker is on until a connection is established.
MDMSPKR_ON	The speaker is always on.
MDMSPKR_DIAL	The speaker is on until a connection is established, except that it is off while the modem is actually dialing.
dwPreferredModemOptions

Specifies the modem options requested by the application. The local and remote modems negotiate modem options during call setup; this member specifies the initial negotiating position of the local modem.

The dwModemOptions member of the MODEMDEVCAPSstructure specifies the modem options supported by the local modem. For a list of modem options, see the description of the MODEMDEVCAPS structure.

dwNegotiatedModemOptions

Specifies the modem options that are actually in effect. This member is filled in after a connection is established and the local and remote modems negotiate modem options.

The dwModemOptions member of the MODEMDEVCAPS structure specifies the modem options supported by the local modem. For a list of modem options, see the description of the MODEMDEVCAPS structure.

dwNegotiatedDCERate

Specifies the DCE rate that is in effect. This member is filled in after a connection is established and the local and remote modems negotiate modem modulations.

abVariablePortion

Contains provider-defined information, if any.

See Also

MODEMDEVCAPS


MONCBSTRUCT

The MONCBSTRUCT structure contains information about the current DDE transaction. A DDE debugging application can use this structure when monitoring transactions that the system passes to the DDE callback functions of other applications.

typedef struct tagMONCBSTRUCT { // mcbst

    UINT   cb;

    DWORD  dwTime;

    HANDLE hTask;

    DWORD  dwRet;

    UINT   wType;

    UINT   wFmt;

    HCONV  hConv;

    HSZ    hsz1;

    HSZ    hsz2;

    HDDEDATA hData;

    DWORD    dwData1;

    DWORD    dwData2;

    CONVCONTEXT cc;

    DWORD  cbData;

    DWORD  Data[8];

} MONCBSTRUCT;

Members

cb

Specifies the structure’s size, in bytes.

dwTime

Specifies the Windows time that the transaction occurred. Windows time is the number of milliseconds that have elapsed since the system was booted.

hTask

Identifies the task (application instance) containing the DDE callback function that received the transaction.

dwRet

Specifies the value returned by the DDE callback function that processed the transaction.

wType

Identifies the transaction type.

wFmt

Specifies the format of the data exchanged (if any) during the transaction.

hConv

Identifies the conversation in which the transaction took place.

hsz1

Identifies a string.

hsz2

Identifies a string.

hData

Identifies the data exchanged (if any) during the transaction.

dwData1

Specifies additional data.

dwData2

Specifies additional data.

cc

Specifies a CONVCONTEXT structure containing language information used to share data in different languages.

cbData

Specifies the amount, in bytes, of data being passed with the transaction. This value may be more than 32 bytes.

Data

Contains the first 32 bytes of data being passed with the transaction
(8 * sizeof(DWORD)).

See Also

CONVCONTEXT, MONERRSTRUCT, MONHSZSTRUCT, MONLINKSTRUCT, MONMSGSTRUCT


MONCONVSTRUCT

The MONCONVSTRUCT structure contains information about a DDE conversation. A DDE monitoring application can use this structure to obtain information about a conversation that has been established or has terminated.

typedef struct tagMONCONVSTRUCT { // mcvst

    UINT   cb;

    BOOL   fConnect;

    DWORD  dwTime;

    HANDLE hTask;

    HSZ    hszSvc;

    HSZ    hszTopic;

    HCONV  hConvClient;

    HCONV  hConvServer;

} MONCONVSTRUCT;

Members

cb

Specifies the structure’s size, in bytes.

fConnect

Indicates whether the conversation is currently established. A value of TRUE indicates the conversation is established; FALSE indicates it is not.

dwTime

Specifies the Windows time at which the conversation was established or terminated. Windows time is the number of milliseconds that have elapsed since the system was booted.

hTask

Identifies a task (application instance) that is a partner in the conversation.

hszSvc

Identifies the service name on which the conversation is established.

hszTopic

Identifies the topic name on which the conversation is established.

hConvClient

Identifies the client conversation.

hConvServer

Identifies the server conversation.

Remarks

Because string handles are local to the process, the hszSvc and hszTopic members are global atoms. Similarly, conversation handles are local to the instance; therefore, the hConvClient and hConvServer members are window handles.

The hConvClient and hConvServer members of the MONCONVSTRUCT structure do not hold the same value as would be seen by the applications engaged in the conversation. Instead, they hold a globally unique pair of values that identify the conversation.

See Also

MONCBSTRUCT, MONERRSTRUCT, MONHSZSTRUCT, MONLINKSTRUCT, MONMSGSTRUCT


MONERRSTRUCT

The MONERRSTRUCT structure contains information about the current DDE error. A DDE monitoring application can use this structure to monitor errors returned by DDE Management Library functions.

typedef struct tagMONERRSTRUCT { // mest

    UINT   cb;

    UINT   wLastError;

    DWORD  dwTime;

    HANDLE hTask;

} MONERRSTRUCT;

Members

cb

Specifies the structure’s size, in bytes.

wLastError

Identifies the current error.

dwTime

Specifies the Windows time that the error occurred. Windows time is the number of milliseconds that have elapsed since the system was booted.

hTask

Identifies the task (application instance) that called the DDE function that caused the error.

See Also

MONCBSTRUCT, MONCONVSTRUCT, MONHSZSTRUCT, MONLINKSTRUCT, MONMSGSTRUCT


MONHSZSTRUCT

The MONHSZSTRUCT structure contains information about a DDE string handle. A DDE monitoring application can use this structure when monitoring the activity of the string manager component of the DDE Management Library.

typedef struct tagMONHSZSTRUCT { // mhst

    UINT   cb;

    BOOL   fsAction;

    DWORD  dwTime;

    HSZ    hsz;

    HANDLE hTask;

    TCHAR   str[1];

} MONHSZSTRUCT;

Members

cb

Specifies the structure’s size, in bytes.

fsAction

Specifies the action being performed on the string identified by the hsz member.

Value	Meaning
MH_CLEANUP	An application is freeing its DDE resources, causing the system to delete string handles the application had created. (The application called the DdeUninitialize function.)
MH_CREATE	An application is creating a string handle. (The application called the DdeCreateStringHandle function.)
MH_DELETE	An application is deleting a string handle. (The application called the DdeFreeStringHandle function.)
MH_KEEP	An application is increasing the usage count of a string handle. (The application called the DdeKeepStringHandle function.)
dwTime

Specifies the Windows time when the action specified by the fsAction member takes place. Windows time is the number of milliseconds that have elapsed since the system was booted.

hsz

Identifies the string. Because string handles are local to the process, this member is a global atom.

hTask

Identifies the task (application instance) performing the action on the string handle.

str

Points to the string identified by the hsz member.

See Also

MONCBSTRUCT, MONCONVSTRUCT, MONERRSTRUCT, MONLINKSTRUCT, MONMSGSTRUCT


MONITOR_INFO_1

The MONITOR_INFO_1 structure identifies an installed monitor.

typedef struct _MONITOR_INFO_1 { // mi1

    LPTSTR pName;

} MONITOR_INFO_1;

Members

pName

Points to a null-terminated string that identifies an installed monitor.

See Also

EnumMonitors, MONITOR_INFO_2


MONITOR_INFO_2

The MONITOR_INFO_2 structure identifies a monitor.

typedef struct _MONITOR_INFO_2 { // mi2

    LPTSTR pName;

    LPTSTR pEnvironment ;

    LPTSTR pDLLName ;

} MONITOR_INFO_2;

Members

pName

Points to a null-terminated string that is the name of the monitor.

pEnvironment

Points to a null-terminated environment string specifying the environment in which the monitor dynamic-link library (DLL) is designed to run.

pDLLName

Points to a null-terminated string that is the name of the monitor DLL.

See Also

EnumMonitors, MONITOR_INFO_1


MONLINKSTRUCT

The MONLINKSTRUCT structure contains information about a DDE advise loop. A DDE monitoring application can use this structure to obtain information about an advise loop that has started or ended.

typedef struct tagMONLINKSTRUCT { // mlst

    UINT   cb;

    DWORD  dwTime;

    HANDLE hTask;

    BOOL   fEstablished;

    BOOL   fNoData;

    HSZ    hszSvc;

    HSZ    hszTopic;

    HSZ    hszItem;

    UINT   wFmt;

    BOOL   fServer;

    HCONV  hConvServer;

    HCONV  hConvClient;

} MONLINKSTRUCT;

Members

cb

Specifies the structure’s size, in bytes.

dwTime

Specifies the Windows time when the advise loop was started or ended. Windows time is the number of milliseconds that have elapsed since the system was booted.

hTask

Identifies a task (application instance) that is a partner in the advise loop.

fEstablished

Indicates whether an advise loop was successfully established. A value of TRUE indicates an advise loop was established; FALSE indicates it was not.

fNoData

Indicates whether the XTYPF_NODATA flag is set for the advise loop. A value of TRUE indicates the flag is set; FALSE indicates it is not.

hszSvc

Identifies the service name of the server in the advise loop.

hszTopic

Identifies the topic name on which the advise loop is established.

hszItem

Identifies the item name that is the subject of the advise loop.

wFmt

Specifies the format of the data exchanged (if any) during the advise loop.

fServer

Indicates whether the link notification came from the server. A value of TRUE indicates the notification came from the server; FALSE indicates otherwise.

hConvServer

Identifies the server conversation.

hConvClient

Identifies the client conversation.

Remarks

Because string handles are local to the process, the hszSvc, hszTopic, and hszItem members are global atoms.

The hConvClient and hConvServer members of the MONLINKSTRUCT structure do not hold the same value as would be seen by the applications engaged in the conversation. Instead, they hold a globally unique pair of values that identify the conversation.

See Also

MONCBSTRUCT, MONERRSTRUCT, MONHSZSTRUCT, MONMSGSTRUCT


MONMSGSTRUCT

The MONMSGSTRUCT structure contains information about a DDE message. A DDE monitoring application can use this structure to obtain information about a DDE message that was sent or posted.

typedef struct tagMONMSGSTRUCT { // mmst

    UINT   cb;

    HWND   hwndTo;

    DWORD  dwTime;

    HANDLE hTask;

    UINT   wMsg;

    WPARAM wParam;

    LPARAM lParam;

    DDEML_MSG_HOOK_DATA dmhd;

} MONMSGSTRUCT;

Members

cb

Specifies the structure’s size, in bytes.

hwndTo

Identifies the window that receives the DDE message.

dwTime

Specifies the Windows time at which the message was sent or posted. Windows time is the number of milliseconds that have elapsed since the system was booted.

hTask

Identifies the task (application instance) containing the window that receives the DDE message.

wMsg

Specifies the identifier of the DDE message.

wParam

Specifies the wParam parameter of the DDE message.

lParam

Specifies the lParam parameter of the DDE message.

dmhd

Specifies a DDEML_MSG_HOOK_DATA structure that contains additional information about the DDE message.

See Also

DDEML_MSG_HOOK_DATA, MONCBSTRUCT, MONCONVSTRUCT, MONERRSTRUCT, MONHSZSTRUCT, MONLINKSTRUCT


MOUSE_EVENT_RECORD

The MOUSE_EVENT_RECORD structure is used in a console INPUT_RECORD structure to report mouse input events.

typedef struct _MOUSE_EVENT_RECORD { // mer

    COORD dwMousePosition;

    DWORD dwButtonState;

    DWORD dwControlKeyState;

    DWORD dwEventFlags;

} MOUSE_EVENT_RECORD;

Members

dwMousePosition

Specifies the location of the cursor in terms of the screen buffer’s character-cell coordinates.

dwButtonState

Indicates the status of the mouse buttons. The least significant bit corresponds to the leftmost mouse button. The next least significant bit corresponds to the rightmost mouse button. The next bit indicates the next-to-leftmost mouse button. The bits then correspond left to right to the mouse buttons. A bit is 1 if the button was pressed.

The following constants are defined for the first five mouse buttons:

FROM_LEFT_1ST_BUTTON_PRESSED
RIGHTMOST_BUTTON_PRESSED
FROM_LEFT_2ND_BUTTON_PRESSED
FROM_LEFT_3RD_BUTTON_PRESSED
FROM_LEFT_4TH_BUTTON_PRESSED

dwControlKeyState

Indicates the state of the control keys. This member can be a combination of the following values:

Value	Meaning
RIGHT_ALT_PRESSED	The right ALT key is pressed.
LEFT_ALT_PRESSED	The left ALT key is pressed.
RIGHT_CTRL_PRESSED	The right CTRL key is pressed.
LEFT_CTRL_PRESSED	The left CTRL key is pressed.
CAPSLOCK_ON	The CAPS LOCK light is on.
ENHANCED_KEY	The key is enhanced.
NUMLOCK_ON	The NUM LOCK light is on.
SCROLLLOCK_ON	The SCROLL LOCK light is on.
SHIFT_PRESSED	The SHIFT key is pressed.
dwEventFlags

Indicates the type of mouse event. If this value is zero, it indicates a mouse button being pressed or released. Otherwise, the value is one of the following:

Value	Meaning
DOUBLE_CLICK	The second click (button press) of a double-click occurred. The first click is returned as a regular button-press event.
MOUSE_MOVED	A change in mouse position occurred.
Remarks

Mouse events are placed in the input buffer when the console is in mouse mode (ENABLE_MOUSE_INPUT).

Mouse events are generated whenever the user moves the mouse, or presses or releases one of the mouse buttons. Mouse events are placed in a console’s input buffer only when the console group has the keyboard focus and the cursor is within the borders of the console’s window.

See Also

INPUT_RECORD, PeekConsoleInput, ReadConsoleInput, WriteConsoleInput


MOUSEHOOKSTRUCT

The MOUSEHOOKSTRUCT structure contains information about a mouse event.

typedef struct tagMOUSEHOOKSTRUCT { // ms

    POINT pt;

    HWND  hwnd;

    UINT  wHitTestCode;

    DWORD dwExtraInfo;

} MOUSEHOOKSTRUCT;

Members

pt

Specifies a POINT structure that contains the x- and y-coordinates of the cursor, in screen coordinates.

hwnd

Identifies the window that will receive the mouse message corresponding to the mouse event.

wHitTestCode

Specifies the hit-test value. For a list of hit-test values, see the description of the WM_NCHITTEST message.

dwExtraInfo

Specifies extra information associated with the message.

See Also

GetMessageExtraInfo, POINT, SetWindowsHook, SetWindowsHookEx, WM_NCHITTEST


MOUSEKEYS

The MOUSEKEYS structure contains information about the MouseKeys accessibility feature. When the MouseKeys feature is active, the user can use the numeric keypad to control the mousepointer, and to click, double-click, drag, and drop. By pressing NUMLOCK, the user can toggle the numeric keypad between mouse control mode and normal operation.

typedef struct _MOUSEKEYS {     // mk

    DWORD cbSize;

    DWORD dwFlags;

    DWORD iMaxSpeed;

    DWORD iTimeToMaxSpeed;

    DWORD iCtrlSpeed;

    DWORD dwReserved1;

    DWORD dwReserved2;

} MOUSEKEYS;

Members

cbSize

Specifies the size, in bytes, of this structure.

dwFlags

A set of bit-flags that specify properties of the FilterKeys feature. The following bit-flag values are defined:

Value	Meaning
MKF_AVAILABLE	If this flag is set, the MouseKeys feature is available.
MKF_CONFIRMHOTKEY	Windows 95 only: A confirmation dialog box appears when the MouseKeys feature is activated by using the hot key.
MKF_HOTKEYACTIVE	If this flag is set, the user can turn the MouseKeys feature on and off by using the hot key, which is LEFT ALT+LEFT SHIFT+NUM LOCK.
MKF_HOTKEYSOUND	If this flag is set, the system plays a siren sound when the user turns the MouseKeys feature on or off by using the hot key.
MKF_INDICATOR	Windows 95 only: A visual indicator is displayed when the MouseKeys feature is on.
MKF_MOUSEKEYSON	If this flag is set, the MouseKeys feature is on.
MKF_MODIFIERS	Windows 95 only: The CTRL key increases cursor speed by the value specified by the iCtrlSpeed member, and the SHIFT key causes the cursor to delay briefly after moving a single pixel, allowing fine positioning of the cursor. If this value is not specified, the CTRL and SHIFT keys are ignored while the user moves the mouse cursor using the arrow keys.
MKF_REPLACENUMBERS	Windows 95 only:The numeric keypad moves the mouse when the NUM LOCK key is on. If this flag is not specified, the numeric keypad moves the mouse cursor when the NUM LOCK key is off.
iMaxSpeed

Specifies the maximum speed the mouse cursor attains when an arrow key is held down.

Windows 95: Range checking is not performed.

Windows NT: Valid values are from 10 to 360.

iTimeToMaxSpeed

Specifies the length of time, in milliseconds, that it takes for the mouse cursor to reach maximum speed when an arrow key is held down. Valid values are from 1000 to 5000.

iCtrlSpeed

Windows 95: Specifies the multiplier to apply to the mouse cursor speed when the user holds down the CTRL key while using the arrow keys to move the cursor. this value is ignored if MKF_MODIFIERS is not set.

Windows NT: This member is reserved for future use. It must be set to zero.

dwReserved1

This member is reserved for future use. It must be set to zero.

dwReserved2

This member is reserved for future use. It must be set to zero.

Remarks

An application uses a MOUSEKEYS structure when calling the SystemParametersInfo function with the wAction parameter set to the SPI_GETMOUSEKEYS or SPI_SETMOUSEKEYS value. When using SPI_GETMOUSEKEYS, an application must specify the cbSize member of the MOUSEKEYS structure; the SystemParametersInfo function fills the remaining members. An application must specify all structure members when using the SPI_SETMOUSEKEYS value.

See Also

SystemParametersInfo


MSG

The MSG structure contains message information from a thread’s message queue.

typedef struct tagMSG {     // msg

    HWND   hwnd;

    UINT   message;

    WPARAM wParam;

    LPARAM lParam;

    DWORD  time;

    POINT  pt;

} MSG;

Members

hwnd

Identifies the window whose window procedure receives the message.

message

Specifies the message number.

wParam

Specifies additional information about the message. The exact meaning depends on the value of the message member.

lParam

Specifies additional information about the message. The exact meaning depends on the value of the message member.

time

Specifies the time at which the message was posted.

pt

Specifies the cursor position, in screen coordinates, when the message was posted.

See Also

GetMessage, PeekMessage


MSG_INFO_0

The MSG_INFO_0 structure specifies a message alias.

typedef struct _MSG_INFO_0 {
    LPTSTR  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.

See Also

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 {
    LPTSTR  msgi1_name;
    DWORD   msgi1_forward_flag;
    LPTSTR  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.
See Also

NetMessageNameEnum, NetMessageNameGetInfo


MSGBOXPARAMS

The MSGBOXPARAMS structure contains information used to display a message box. The MessageBoxIndirect function uses this structure.

typedef struct {

    UINT      cbSize;

    HWND      hwndOwner;

    HINSTANCE hInstance;

    LPCSTR    lpszText;

    LPCSTR    lpszCaption;

    DWORD     dwStyle;

    LPCSTR    lpszIcon;

    DWORD     dwContextHelpId;

    MSGBOXCALLBACK lpfnMsgBoxCallback;

    DWORD     dwLanguageId;

} MSGBOXPARAMS, *PMSGBOXPARAMS, FAR *LPMSGBOXPARAMS;

Members

cbSize

Specifies the structure size, in bytes.

hwndOwner

Identifies the owner window. This member can be NULL.

hInstance

Identifies the instance containing the icon resource identified by the lpszIcon member, and the string resource identified by the lpszText or lpszCaption member.

lpszText

Points to a null-terminated string, or the identifier of a string resource, that contains the message to be displayed.

lpszCaption

Points to a null-terminated string, or the identifier of a string resource, that contains the message box title. If this member is NULL, the default title Error is used.

dwStyle

Specifies a set of bit flags that determine the contents and behavior of the dialog box. This member can be a combination of flags described for the uType parameter of the MessageBoxEx function.

In addition, you can specify the MB_USERICON flag if you want the message box to display the icon specified by the lpszIcon member.

lpszIcon

Identifies an icon resource. This parameter can be either a null-terminated string or an integer resource identifier passed to the MAKEINTRESOURCE macro.

To load one of the Windows predefined icons, set the hInstance member to NULL and set lpszIcon to one of the values listed with the LoadIcon function.

This member is ignored if the dwStyle member does not specify the MB_USERICON flag.

dwContextHelpId

Identifies a Help context. If a Help event occurs, this value is specified in the HELPINFO structure that the message box sends to the owner window or callback function.

lpfnMsgBoxCallback

Points to the callback function that processes Help events for the message box. The callback function has the following form:

VOID CALLBACK MsgBoxCallback(LPHELPINFO lpHelpInfo);

If this member is NULL, the message box sends WM_HELP messages to the owner window when help events occur.

dwLanguageId

Specifies the language in which to display the text contained in the predefined push buttons. This value must be in the form returned by the MAKELANGID macro.

For a list of the language identifiers supported by Win32, see Language Identifiers. Note that each localized release of Windows typically contains resources only for a limited set of languages. Thus, for example, the U.S. version offers LANG_ENGLISH, the French version offers LANG_FRENCH, the German version offers LANG_GERMAN, and the Japanese version offers LANG_JAPANESE. Each version offers LANG_NEUTRAL. This limits the set of values that can be used with the wLanguageId parameter. Before specifying a language identifier, you should enumerate the locales that are installed on a system.

See Also

HELPINFO, LoadIcon, MAKEINTRESOURCE, MAKELANGID, MessageBoxEx, MessageBoxIndirect, WM_HELP


MSGFILTER

The MSGFILTER structure contains information about a keyboard or mouse event. A rich edit control sends this structure to its parent window as part of an EN_MSGFILTER notification message, enabling the parent to change the message or prevent it from being processed.

typedef struct _msgfilter {

    NMHDR nmhdr;

    UINT msg;

    _WPAD _wPad1;

    WPARAM wParam;

    _WPAD _wPad2;

    LPARAM lParam;

} MSGFILTER;

Members

nmhdr

Specifies a NMHDR structure. The code member of the NMHDR structure is the EN_MSGFILTER notification code that identifies the message being sent.

msg

Specifies the keyboard or mouse message identifier.

wParam

Specifies the wParam parameter of the message.

lParam

Specifies the lParam parameter of the message.

See Also

EN_MSGFILTER


MULTIKEYHELP

The MULTIKEYHELP structure specifies a keyword table and an associated keyword to be used by Windows Help.

typedef struct tagMULTIKEYHELP { // mkh

    DWORD  mkSize;

    TCHAR  mkKeylist;

    TCHAR  szKeyphrase[1];

} MULTIKEYHELP;

Members

mkSize

Specifies the structure size, in bytes.

mkKeylist

Specifies a single character that identifies the keyword table to search.

szKeyphrase

Contains a null-terminated text string that specifies the keyword to locate in the keyword table.

See Also

WinHelp


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

ADAPTER_STATUS, NCB


NCB

The NCB structure describes a network control block. 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	Enables extensions to the transport interface. NCBACTION commands are 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.
NCBADDGRNAME	Adds a group name to the local name table.
NCBADDNAME	Adds a unique name to the local name table.
NCBASTAT	Retrieves the status of the 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 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 broadcast datagram from any host.
NCBDGSEND	Sends datagram to a specified name.
NCBDGSENDBC	Sends a broadcast datagram to every host on the local area network (LAN).
NCBENUM	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.
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	Notifies the user of LAN failures that last for more than one minute.
NCBLISTEN	Enables a session to be opened with another name.
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 any other NCB command that specifies the same number in the ncb_lana_num member will be accepted.
	The IBM NetBIOS 3.0 specification documents several NCB_RESET NCB’s. Win32 implements the NCB.RESET using the dynamic link routine interface. Particular values can be passed in specific bytes of the NCB, more specifically:
	• 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 an 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. Support for this command in the system is optional and system-specific.
NCBUNLINK	Unlinks the adapter.
ncb_retcode

Specifies the return code. This value is set to NRC_PENDING while an asynchronous operation is in progress. One of the following return code values can be specified:

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 the Netbios function.
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 return code is not part of the IBM NetBIOS 3.0 specification.
NRC_SYSTEM	A system error occurred.
NRC_PENDING	An asynchronous operation is not yet finished.
ncb_lsn

Specifies the local session number. This number uniquely identifies a session within an environment.

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 (see NCBRESET) is always 0x01. Netbios assigns values in the range 0x02 to 0xFE for the remaining names.

ncb_buffer

Points to the message buffer.

ncb_length

Specifies the size, in bytes, of the message buffer.

ncb_callname

Specifies the string that contains the remote name. Trailing space characters should be supplied to make the length of the string equal to NCBNAMSZ.

ncb_name

Specifies the string that contains the local name. Trailing space characters should be supplied to make the length of the string equal to NCBNAMSZ.

ncb_rto

Specifies the receive time-out period, in 500-millisecond units, for the session. A value of zero implies no time-out. Specified with the NCBCALL or NCBLISTEN command. Affects subsequent NCBRECV commands.

ncb_sto

Specifies the send time-out period, in 500-millisecond units, for the session. A value of zero implies no time-out. Specified with the NCBCALL or NCBLISTEN command. Affects subsequent NCBSEND and NCBCHAINSEND commands.

ncb_post

Specifies the address of the routine to call when the asynchronous NCB finishes. The completion routine is passed 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 a Windows event that is set to the signaled state when the asynchronous network control block finishes. The event is signaled if the Netbios function returns a nonzero value.

The ncb_event member must be zero if the ncb_command member does not have the ASYNCH value set or if ncb_post is nonzero. Otherwise, NRC_ILLCMD is returned.

The event specified by ncb_event is set to the nonsignaled state by the system when an asynchronous NetBIOS command is accepted, and it is set to the signaled state when the asynchronous NetBIOS command finishes.

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.

Only manual reset events should be used with Netbios. A given event should not be associated with more than one active asynchronous NetBIOS command.

See Also

ACTION_HEADER, ADAPTER_STATUS, FIND_NAME_BUFFER, FIND_NAME_HEADER, LANA_ENUM, NAME_BUFFER, Netbios, SESSION_BUFFER, SESSION_HEADER


NCCALCSIZE_PARAMS

The NCCALCSIZE_PARAMS structure contains information that an application can use while processing the WM_NCCALCSIZE message to calculate the size, position, and valid contents of the client area of a window.

typedef struct _NCCALCSIZE_PARAMS { // nccp

    RECT        rgrc[3];

    PWINDOWPOS  lppos;

} NCCALCSIZE_PARAMS;

Members

rgrc

Specifies an array of rectangles. The first contains the new coordinates of a window that has been moved or resized. The second contains the coordinates of the window before it was moved or resized. The third contains the coordinates of the window’s client area before the window was moved or resized. If the window is a child window, the coordinates are relative to the client area of the parent window. If the window is a top-level window, the coordinates are relative to the screen origin.

lppos

Points to a WINDOWPOS structure that contains the size and position values specified in the operation that moved or resized the window.

See Also

MoveWindow, RECT, SetWindowPos, WINDOWPOS, WM_NCCALCSIZE


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.

See Also

NDdeSetShareSecurity, NDdeShareSetInfo, WinMain


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

See Also

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.

See Also

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	Represents the password, which will never expire on the account. This value is valid only for Windows NT.
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.

See Also

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	Represents the password, which will never expire on the account. This value is valid only for Windows NT.
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.

See Also

NetUserAdd, NetUserSetInfo, NetQueryDisplayInformation


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.

See Also

WNetAddConnection, WNetCloseEnum, WNetEnumResource, WNetOpenEnum


NEWCPLINFO

The NEWCPLINFO structure contains resource information and an application-defined value for a dialog box supported by a Control Panel application. The CPlApplet function of the Control Panel application returns this information to the Control Panel in response to a CPL_NEWINQUIRE message.

typedef struct tagNEWCPLINFO {  // ncpli

    DWORD dwSize;

    DWORD dwFlags;

    DWORD dwHelpContext;

    LONG  lData;

    HICON hIcon;

    TCHAR  szName[32];

    TCHAR  szInfo[64];

    TCHAR  szHelpFile[128];

} NEWCPLINFO;

Members

dwSize

Specifies the length of the structure, in bytes.

dwFlags

This member is ignored.

dwHelpContext

This member is ignored.

lData

Specifies data defined by the application. When the Control Panel sends the CPL_DBLCLK and CPL_STOP messages, it passes this value back to your application.

hIcon

Identifies the icon that represents the dialog box. This icon is intended to be displayed by the application that controls the Control Panel application.

szName

Specifies a null-terminated string that contains the dialog box name. The name is intended to be displayed below the icon.

szInfo

Specifies a null-terminated string containing the dialog box description. The description is intended to be displayed when the icon for the dialog box is selected.

szHelpFile

This member is ignored.

See Also

CPL_DBLCLK, CPL_NEWINQUIRE, CPL_STOP, CPlApplet, CPLINFO


NEWHEADER

The NEWHEADER structure contains the number of icon or cursor components in a resource group.

struct NEWHEADER {

    WORD Reserved;

    WORD ResType;

    WORD ResCount;

} NEWHEADER, *PNEWHEADER;

NEWHEADER NewHeader;

Members

Reserved

Reserved; must be zero.

ResType

Specifies the resource type. This member must be 14 for icons and 12 for cursors.

ResCount

Specifies the number of icon or cursor components in the resource group.

Remarks

One or more RESDIR structures immediately follow the NEWHEADER structure in the .RES file. The ResCount member specifies the number of RESDIR structures.

See Also

RESDIR


NEWTEXTMETRIC

The NEWTEXTMETRIC structure contains data that describes a physical font.

typedef struct tagNEWTEXTMETRIC { // ntm

    LONG   tmHeight;

    LONG   tmAscent;

    LONG   tmDescent;

    LONG   tmInternalLeading;

    LONG   tmExternalLeading;

    LONG   tmAveCharWidth;

    LONG   tmMaxCharWidth;

    LONG   tmWeight;

    LONG   tmOverhang;

    LONG   tmDigitizedAspectX;

    LONG   tmDigitizedAspectY;

    BCHAR  tmFirstChar;

    BCHAR  tmLastChar;

    BCHAR  tmDefaultChar;

    BCHAR  tmBreakChar;

    BYTE   tmItalic;

    BYTE   tmUnderlined;

    BYTE   tmStruckOut;

    BYTE   tmPitchAndFamily;

    BYTE   tmCharSet;

    DWORD  ntmFlags;

    UINT   ntmSizeEM;

    UINT   ntmCellHeight;

    UINT   ntmAvgWidth;

} NEWTEXTMETRIC;

Members

tmHeight

Specifies the height (ascent + descent) of characters.

tmAscent

Specifies the ascent (units above the base line) of characters.

tmDescent

Specifies the descent (units below the base line) of characters.

tmInternalLeading

Specifies the amount of leading (space) inside the bounds set by the tmHeight member. Accent marks and other diacritical characters may occur in this area. The designer may set this member to zero.

tmExternalLeading

Specifies the amount of extra leading (space) that the application adds between rows. Since this area is outside the font, it contains no marks and is not altered by text output calls in either OPAQUE or TRANSPARENT mode. The designer may set this member to zero.

tmAveCharWidth

Specifies the average width of characters in the font (generally defined as the width of the letter x). This value does not include overhang required for bold or italic characters.

tmMaxCharWidth

Specifies the width of the widest character in the font.

tmWeight

Specifies the weight of the font.

tmOverhang

Specifies the extra width per string that may be added to some synthesized fonts. When synthesizing some attributes, such as bold or italic, graphics device interface (GDI) or a device may have to add width to a string on both a per-character and per-string basis. For example, GDI makes a string bold by expanding the spacing of each character and overstriking by an offset value; it italicizes a font by shearing the string. In either case, there is an overhang past the basic string. For bold strings, the overhang is the distance by which the overstrike is offset. For italic strings, the overhang is the amount the top of the font is sheared past the bottom of the font.

The tmOverhang member enables the application to determine how much of the character width returned by a GetTextExtentPoint32 function call on a single character is the actual character width and how much is the per-string extra width. The actual width is the extent minus the overhang.

tmDigitizedAspectX

Specifies the horizontal aspect of the device for which the font was designed.

tmDigitizedAspectY

Specifies the vertical aspect of the device for which the font was designed. The ratio of the tmDigitizedAspectX and tmDigitizedAspectY members is the aspect ratio of the device for which the font was designed.

tmFirstChar

Specifies the value of the first character defined in the font.

tmLastChar

Specifies the value of the last character defined in the font.

tmDefaultChar

Specifies the value of the character to be substituted for characters that are not in the font.

tmBreakChar

Specifies the value of the character to be used to define word breaks for text justification.

tmItalic

Specifies an italic font if it is nonzero.

tmUnderlined

Specifies an underlined font if it is nonzero.

tmStruckOut

Specifies a strikeout font if it is nonzero.

tmPitchAndFamily

Specifies the pitch and family of the selected font. The low-order bit (bit 0) specifies the pitch of the font. If it is 1, the font is variable pitch (or proportional). If it is 0, the font is fixed pitch (or monospace). Bits 1 and 2 specify the font type. If both bits are 0, the font is a raster font; if bit 1 is 1 and bit 2 is 0, the font is a vector font; if bit 1 is 0 and bit 2 is set, or if both bits are 1, the font is some other type. Bit 3 is 1 if the font is a device font; otherwise, it is 0.

The four high-order bits designate the font family. The tmPitchAndFamily member can be combined with the hexadecimal value 0xF0 by using the bitwise AND operator and can then be compared with the font family names for an identical match. For more information about the font families, see the LOGFONT structure.

tmCharSet

Specifies the character set of the font.

ntmFlags

Specifies whether the font is italic, underscored, outlined, bold, and so forth. The following list shows the bits corresponding to each font type:

Bit	Meaning
0	Italic
1	Underscore
2	Negative
3	Outline
4	Strikeout
5	Bold
ntmSizeEM

Specifies the size of the em square for the font. This value is in “notional units” (that is, the units for which the font was designed).

ntmCellHeight

Specifies the height, in notional units, of the font. This value should be compared with the value of the ntmSizeEM member.

ntmAvgWidth

Specifies the average width of characters in the font, in notional units. This value should be compared with the value of the ntmSizeEM member.

Remarks

The last four members of the NEWTEXTMETRIC structure are not included in the TEXTMETRIC structure; in all other respects, the structures are identical.

The sizes in the NEWTEXTMETRIC structure are typically given in logical units; that is, they depend on the current mapping mode of the display context.

See Also

EnumFontFamilies, GetTextExtentPoint32, GetTextMetrics, LOGFONT


NEWTEXTMETRICEX

The NEWTEXTMETRICEX structure contains information about a physical font.

typedef struct tagNEWTEXTMETRICEX {
    NEWTEXTMETRIC  ntmentm;
    FONTSIGNATURE  ntmeFontSignature;
} NEWTEXTMETRICEX;

Members

ntmentm

Specifies a NEWTEXTMETRIC structure.

ntmeFontSignature

Specifies a FONTSIGNATURE structure indicating the coverage of the font.

See Also

NEWTEXTMETRIC


NM_LISTVIEW

The NM_LISTVIEW structure contains information about a list view notification message.

typedef struct tagNM_LISTVIEW {

    NMHDR hdr;

    int   iItem;

    int   iSubItem;

    UINT  uNewState;

    UINT  uOldState;

    UINT  uChanged;

    POINT ptAction;

    LPARAM lParam;

} NM_LISTVIEW;

Members

hdr

Specifies an NMHDR structure. The code member of the NMHDR structure can one of the following notification codes that identify the message being sent: LVN_BEGINDRAG, LVN_BEGINRDRAG, LVN_COLUMNCLICK, LVN_DELETEALLITEMS, LVN_DELETEITEM, LVN_INSERTITEM, LVN_ITEMCHANGED, or LVN_ITEMCHANGING.

iItem

Identifies the list view item, or −1 if not used.

iSubItem

Identifies the subitem, or zero if none.

uNewState

Specifies the new item state. This member is zero for notification messages that do not use it.

uOldState

Specifies the old item state. This member is zero for notification messages that do not use it.

uChanged

A set of bit flags that indicate the item attributes that have changed. This member is zero for notifications that do not use it. Otherwise, it can have the same values as the mask member of the LV_ITEM structure.

ptAction

Specifies a POINT structure that indicates the location at which the event occurred. This member is valid only for the LVN_BEGINDRAG and LVN_BEGINRDRAG notification messages.

Remarks

The address of the NM_LISTVIEW structure is specified as the lParam parameter of the WM_NOTIFY message for several list view notification messages.

See Also

LV_ITEM, LVN_BEGINDRAG, LVN_BEGINRDRAG, LVN_COLUMNCLICK, LVN_DELETEALLITEMS, LVN_DELETEITEM, LVN_INSERTITEM, LVN_ITEMCHANGED, LVN_ITEMCHANGING, WM_NOTIFY


NM_TREEVIEW

The NM_TREEVIEW structure contains information about a tree view notification message.

typedef struct _NM_TREEVIEW {  nmtv

    NMHDR    hdr;

    UINT     action;

    TV_ITEM  itemOld;

    TV_ITEM  itemNew;

    POINT    ptDrag;

} NM_TREEVIEW;

typedef NM_TREEVIEW FAR *LPNM_TREEVIEW;

Members

hdr

Specifies an NMHDR structure. The code member of the NMHDR structure can one of the following notification codes that identify the message being sent: TVN_BEGINDRAG, TVN_BEGINRDRAG, TVN_DELETEITEM, TVN_ITEMEXPANDED, TVN_ITEMEXPANDING, TVN_SELCHANGED, TVN_SELCHANGING.

action

Specifies a notification-specific action flag.

itemOld

Specifies a TV_ITEM structure that contains information about the old item state. This member is zero for notification messages that do not use it.

itemNew

Specifies a TV_ITEM structure that contains information about the new item state. This member is zero for notification messages that do not use it.

ptDrag

Specifies a POINT structure that contains the client coordinates of the mouse at the time the event occurred that caused the notification message to be sent.

Remarks

The address of this structure is specified as the lParam parameter of the WM_NOTIFY message for several tree-view notification messages.

See Also

POINT, TV_ITEM, TVN_BEGINDRAG, TVN_BEGINRDRAG, TVN_DELETEITEM, TVN_ITEMEXPANDED, TVN_ITEMEXPANDING, TVN_SELCHANGED, TVN_SELCHANGING, WM_NOTIFY


NM_UPDOWN

The NM_UPDOWN structure contains information about an up-down control notification message.

typedef struct _NM_UPDOWN {  nmud

    NMHDR    hdr;       // notification message header

    int     iPos;        // current position

    int  iDelta;      // proposed change in position

} NM_UPDOWNW;

Members

hdr

Specifies an NMHDR structure. The code member of the NMHDR structure can be the following notification code that identifies the message being sent: UDN_DELTAPOS.

iPos

Signed integer value that is the current position of the up-down control.

iDelta

Signed integer value that is the proposed change in the position of the up-down control.

Remarks

The address of this structure is specified as the lParam parameter of the WM_NOTIFY message for the UDN_DELTAPOS notification message.

See Also

NMHDR, UDN_DELTAPOS, WM_NOTIFY


NMHDR

The NMHDR structure contains information about a notification message. The pointer to this structure is specified as the lParam member of the WM_NOTIFY message.

typedef struct tagNMHDR {

    HWND hwndFrom;

    UINT idFrom;

    UINT code;

} NMHDR;

Members

hwndFrom

Window handle of control sending message

idFrom

Identifier of control sending message

code

Specifies the notification code. This member can be a control-specific notification code, or it can be one of the following common notification values:

Value	Meaning
NM_CLICK	The user has clicked the left mouse button within the control.
NM_DBLCLK	The user has double-clicked the left mouse button within the control.
NM_KILLFOCUS	The control has lost the input focus.
NM_OUTOFMEMORY	The control could not complete an operation because there was not enough memory available.
NM_RCLICK	The user has clicked the right mouse button within the control.
NM_RDBLCLK	The user has double-clicked the right mouse button within the control.
NM_RETURN	The control has the input focus, and the user has pressed the ENTER key.
NM_SETFOCUS	The control has received the input focus.


NONCLIENTMETRICS

The NONCLIENTMETRICS structure contains the scalable metrics associated with the nonclient area of a nonminimized window. This structure is used by the SPI_GETNONCLIENTMETRICS and SPI_SETNONCLIENTMETRICS actions of SystemParametersInfo.

typedef struct tagNONCLIENTMETRICS {

    UINT    cbSize;

    int     iBorderWidth;

    int     iScrollWidth;

    int     iScrollHeight;

    int     iCaptionWidth;

    int     iCaptionHeight;

    LOGFONT lfCaptionFont;

    int     iSmCaptionWidth;

    int     iSmCaptionHeight;

    LOGFONT lfSmCaptionFont;

    int     iMenuWidth;

    int     iMenuHeight;

    LOGFONT lfMenuFont;

    LOGFONT lfStatusFont;

    LOGFONT lfMessageFont;

} NONCLIENTMETRICS, FAR* LPNONCLIENTMETRICS;

Members

cbSize

Specifies the size of the structure, in bytes.

iBorderWidth

Specifies the thickness, in pixels, of the sizing border.

iScrollWidth

Specifies the width, in pixels, of a standard vertical scroll bar.

iScrollHeight

Specifies the height, in pixels, of a standard horizontal scroll bar.

iCaptionWidth

Specifies the width, in pixels, of caption buttons.

iCaptionHeight

Specifies the height, in pixels, of caption buttons.

lfCaptionFont

Contains information about the caption font.

iSmCaptionWidth

Specifies the width, in pixels, of small caption buttons.

iSmCaptionHeight

Specifies the height, in pixels, of small captions.

iMenuWidth

Specifies the width, in pixels, of menu-bar buttons.

iMenuHeight

Specifies the height, in pixels, of a menu bar.

lfMenuFont

Contains information about the font used in menu bars.

lfStatusFont

Contains information about the font used in status bars.

lfMessageFont

Contains information about the font used in message boxes.

See Also

SystemParametersInfo


NormalMenuItem

The NormalMenuItem structure contains information about each item in a menu resource that does not open a menu or a submenu.

struct NormalMenuItem {

    WORD resInfo;

    szOrOrd menuText;

};

Members

resInfo

A set of bit flags that specify the type of menu item. This member can be one of the following values.

Value	Meaning
MFR_END	The menu item is the last in this submenu or menu resource; this flag is used internally by the system.
MFR_POPUP	The menu item opens a menu or a submenu; the flag is used internally by the system.
menuText

Specifies a null-terminated Unicode string that contains the text for this menu item. There is no fixed limit on the size of this string.

Remarks

There is one NormalMenuItem structure for each menu item that does not open a menu or a submenu. Indicate the last menu item on a menu by setting the resInfo member to MFR_END.

A menu separator is a special type of menu item that is inactive but appears as a dividing bar between two active menu items. Indicate a menu separator by leaving the menuText member empty.

See Also

MenuHeader, MENUITEMINFO, PopupMenuItem


NOTIFYICONDATA

Contains information that the system needs to process taskbar status area messages.

typedef struct _NOTIFYICONDATA { // nid

    DWORD cbSize;

    HWND hWnd;

    UINT uID;

    UINT uFlags;

    UINT uCallbackMessage;

    HICON hIcon;

    char szTip[64];

} NOTIFYICONDATA, *PNOTIFYICONDATA;

Members

cbSize

Size of the NOTIFYICONDATA structure.

hWnd

Handle of the window that receives notification messages associated with an icon in the taskbar status area.

uID

Application-defined identifier of the taskbar icon.

uFlags

Array of flags that indicate which of the other members contain valid data. This member can be a combination of these values:

NIF_ICON	The hIcon member is valid.
NIF_MESSAGE	The uCallbackMessage member is valid.
NIF_TIP	The szTip member is valid.
uCallbackMessage

Application-defined message identifier. The system uses the specified identifier for notification messages that it sends to the window identified by hWnd whenever a mouse event occurs in the bounding rectangle of the icon.

hIcon

Handle of the icon to add, modify, or delete.

szTip

Tooltip text to display for the icon.


NRESARRAY

Defines the CF_NETRESOURCE clipboard format.

typedef struct _NRESARRAY { // anr

    UINT        cItems;

    NETRESOURCE nr[1];

} NRESARRAY, * LPNRESARRAY;

Members

cItems

Number of elements in nr.

nr

Array of NETRESOURCE structures that contain information about network resources. The string members (LPSTR types) in the structure contain offsets instead of addresses.


NS_SERVICE_INFO

The NS_SERVICE_INFO structure contains information about a network service or a network service type in the context of a specified name space, or a set of default name spaces.

typedef struct _NS_SERVICE_INFO {

    DWORD   dwNameSpace;

    SERVICE_INFO ServiceInfo;

} NS_SERVICE_INFO;

Members

dwNameSpace

Specifies the name space or a set of default name spaces to which this service information applies.

Use one of the following constant values to specify a name space:

Value	Name Space
NS_DEFAULT	A set of default name spaces. The set of default name spaces typically includes all the name spaces installed on the system. System administrators, however, can exclude particular name spaces from the set.
NS_DNS	The Domain Name System used in the Internet to resolve the name of the host.
NS_MS
NS_NDS	The NetWare 4 provider.
NS_NETBT	The NetBIOS over TCP/IP layer. The operating system registers their computer names with NetBIOS. This name space is used to convert a computer name to an IP address that uses this registration.
NS_NIS
NS_SAP	The NetWare Service Advertising Protocol. This can access the Netware bindery, if appropriate. NS_SAP is a dynamic name space that enables the registration of services.
NS_STDA
NS_TCPIP_HOSTS	Lookup value in the <systemroot>\system32\drivers\etc\posts file.
NS_TCPIP_LOCAL	Local TCP/IP name resolution mechanisms, including comparisons against the local host name and lookup value in the cache of host to IP address mappings.
NS_WINS
NS_X500
ServiceInfo

A SERVICE_INFO structure that contains information about a network service or network service type.

See Also

GetService, SetService, SERVICE_INFO


NUMBERFMT

The NUMBERFMT structure contains information that defines the format of a number string. The GetNumberFormat function uses this information to customize a number string for a specified locale.

typedef struct _numberfmt {

    UINT      NumDigits;

    UINT      LeadingZero;

    UINT      Grouping;

    LPTSTR    lpDecimalSep;

    LPTSTR    lpThousandSep;

    UINT      NegativeOrder;

} NUMBERFMT;

Members

NumDigits

Specifies the number of fractional digits. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_IDIGITS.

LeadingZero

Specifies whether to use leading zeroes in decimal fields. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_ILZERO.

Grouping

Specifies the size of each group of digits to the left of the decimal. Values in the range 0 − 9 are valid.

lpDecimalSep

Points to a null-terminated decimal separator string.

lpThousandSep

Points to a null-terminated thousand separator string.

NegativeOrder

Specifies the negative number mode. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_INEGNUMBER.

Remarks

For more information about the LCTYPE constants, see LCTYPE Constants.

See Also

GetNumberFormat


OFNOTIFY [New - Windows NT]
OFNOTIFY

[New - Windows NT]

The OFNOTIFY structure contains information about the WM_NOTIFY message sent to a hook procedure from an Explorer-style Open or Save As dialog box. The address of the OFNOTIFY structure is passed as the lParam parameter of the WM_NOTIFY message.

typedef struct _OFNOTIFY {  // on

    NMHDR          hdr;

    LPOPENFILENAME lpOFN;

    LPTSTR         pszFile;

} OFNOTIFY, FAR *LPOFNOTIFY;

Members

hdr

Specifies an NMHDR structure. The code member of the NMHDR structure can be one of the following notification codes that identify the message being sent: CDN_FILEOK, CDN_FOLDERCHANGE, CDN_HELP, CDN_INITDONE, CDN_SELCHANGE, CDN_SHAREVIOLATION, CDN_TYPECHANGE.

lpOFN

Pointer to the OPENFILENAME structure that was specified when the Open or Save As dialog box was created. For some of the notification messages, this structure contains additional information about the event that caused the notification.

pszFile

Pointer to the filename for which a network sharing violation has occurred. This member is valid only with the CDN_SHAREVIOLATION notification message.

See Also

CDN_FILEOK, CDN_FOLDERCHANGE, CDN_HELP, CDN_INITDONE, CDN_SELCHANGE, CDN_SHAREVIOLATION, CDN_TYPECHANGE, NMHDR, OPENFILENAME


OFSTRUCT

The OFSTRUCT structure contains information about a file that the OpenFile function opened or attempted to open.

typedef struct _OFSTRUCT { // of

    BYTE cBytes;

    BYTE fFixedDisk;

    WORD nErrCode;

    WORD Reserved1;

    WORD Reserved2;

    CHAR szPathName[OFS_MAXPATHNAME];

} OFSTRUCT;

Members

cBytes

Specifies the length, in bytes, of the structure.

fFixedDisk

Specifies whether the file is on a hard (fixed) disk. This member is nonzero if the file is on a hard disk.

nErrCode

Specifies the MS-DOS error code if the OpenFile function failed.

Reserved1

Reserved; do not use.

Reserved2

Reserved; do not use.

szPathName

Specifies the path and filename of the file. This string consists of characters from the Windows character set.

See Also

OpenFile


OPENFILENAME

The OPENFILENAME structure contains information that the GetOpenFileName and GetSaveFileName functions use to initialize an Open or Save As common dialog box. After the user closes the dialog box, the system returns information about the user’s selection in this structure.

typedef struct tagOFN { // ofn

    DWORD         lStructSize;

    HWND          hwndOwner;

    HINSTANCE     hInstance;

    LPCTSTR       lpstrFilter;

    LPTSTR        lpstrCustomFilter;

    DWORD         nMaxCustFilter;

    DWORD         nFilterIndex;

    LPTSTR        lpstrFile;

    DWORD         nMaxFile;

    LPTSTR        lpstrFileTitle;

    DWORD         nMaxFileTitle;

    LPCTSTR       lpstrInitialDir;

    LPCTSTR       lpstrTitle;

    DWORD         Flags;

    WORD          nFileOffset;

    WORD          nFileExtension;

    LPCTSTR       lpstrDefExt;

    DWORD         lCustData;

    LPOFNHOOKPROC lpfnHook;

    LPCTSTR       lpTemplateName;

} OPENFILENAME;

Members

lStructSize

Specifies the length, in bytes, of the structure.

hwndOwner

Identifies the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.

hInstance

If the OFN_ENABLETEMPLATEHANDLE flag is set in the Flags member, hInstance is the handle of a memory object containing a dialog box template. If the OFN_ENABLETEMPLATE flag is set, hInstance identifies a module that contains a dialog box template named by the lpTemplateName member. If neither flag is set, this member is ignored.

If the OFN_EXPLORER flag is set, the system uses the specified template to create a dialog box that is a child of the default Explorer-style dialog box. If the OFN_EXPLORER flag is not set, the system uses the template to create an old-style dialog box that replaces the default dialog box.

lpstrFilter

Pointer to a buffer containing pairs of null-terminated filter strings. The last string in the buffer must be terminated by two NULL characters.

The first string in each pair is a display string that describes the filter (for example, “Text Files”), and the second string specifies the filter pattern (for example, “*.TXT”). To specify multiple filter patterns for a single display string, use a semicolon to separate the patterns (for example, “*.TXT;*.DOC;*.BAK”). A pattern string can be a combination of valid filename characters and the asterisk (*) wildcard character. Do not include spaces in the pattern string.

The operating system does not change the order of the filters. It displays them in the File Types combo box in the order specified in lpstrFilter.

If lpstrFilter is NULL, the dialog box does not display any filters.

lpstrCustomFilter

Pointer to a static buffer that contains a pair of null-terminated filter strings for preserving the filter pattern chosen by the user. The first string is your display string that describes the custom filter, and the second string is the filter pattern selected by the user. The first time your application creates the dialog box, you specify the first string, which can be any nonempty string. When the user selects a file, the dialog box copies the current filter pattern to the second string. The preserved filter pattern can be one of the patterns specified in the lpstrFilter buffer, or it can be a filter pattern typed by the user. The system uses the strings to initialize the user-defined file filter the next time the dialog box is created. If the nFilterIndex member is zero, the dialog box uses the custom filter.

If this member is NULL, the dialog box does not preserve user-defined filter patterns.

If this member is not NULL, the value of the nMaxCustFilter member must specify the size, in bytes (ANSI version) or characters (Unicode version), of the lpstrCustomFilter buffer.

nMaxCustFilter

Specifies the size, in bytes or characters, of the buffer identified by lpstrCustomFilter. This buffer should be at least 40 characters long. This member is ignored if lpstrCustomFilter is NULL or points to a NULL string.

nFilterIndex

Specifies the index of the currently selected filter in the File Types control. The buffer pointed to by lpstrFilter contains pairs of strings that define the filters. The first pair of strings has an index value of 1, the second pair 2, and so on. An index of zero indicates the custom filter specified by lpstrCustomFilter. You can specify an index on input to indicate the initial filter description and filter pattern for the dialog box. When the user selects a file, nFilterIndex returns the index of the currently displayed filter.

If nFilterIndex is zero and lpstrCustomFilter is NULL, the system uses the first filter in the lpstrFilter buffer. If all three members are zero or NULL, the system does not use any filters and does not show any files in the file list control of the dialog box.

lpstrFile

Pointer to a buffer that contains a filename used to initialize the File Name edit control. The first character of this buffer must be NULL if initialization is not necessary. When the GetOpenFileName or GetSaveFileName function returns successfully, this buffer contains the drive designator, path, filename, and extension of the selected file.

If the OFN_ALLOWMULTISELECT flag is set and the user selects multiple files, the buffer contains the current directory followed by the filenames of the selected files. For Explorer-style dialog boxes, the directory and filename strings are NULL separated, with an extra NULL character after the last filename. For old-style dialog boxes, the strings are space separated and the function uses short filenames for filenames with spaces. You can use the FindFirstFile function to convert between long and short filenames.

If the buffer is too small, the function returns FALSE and the CommDlgExtendedError function returns FNERR_BUFFERTOOSMALL. In this case, the first two bytes of the lpstrFile buffer contain the required size, in bytes or characters.

nMaxFile

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the buffer pointed to by lpstrFile. The GetOpenFileName and GetSaveFileName functions return FALSE if the buffer is too small to contain the file information. The buffer should be at least 256 characters long.

lpstrFileTitle

Pointer to a buffer that receives the filename and extension (without path information) of the selected file. This member can be NULL.

nMaxFileTitle

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the buffer pointed to by lpstrFileTitle. This member is ignored if lpstrFileTitle is NULL.

lpstrInitialDir

Pointer to a string that specifies the initial file directory. If this member is NULL, the system uses the current directory as the initial directory.

lpstrTitle

Pointer to a string to be placed in the title bar of the dialog box. If this member is NULL, the system uses the default title (that is, “Save As” or “Open”).

Flags

A set of bit flags you can use to initialize the dialog box. When the dialog box returns, it sets these flags to indicate the user’s input. This member can be a combination of the following flags:

Flag	Meaning
OFN_ALLOWMULTISELECT
	Specifies that the File Name list box allows multiple selections. If you also set the OFN_EXPLORER flag, the dialog box uses the Explorer-style user interface; otherwise, it uses the old-style user interface.  If the user selects more than one file, the lpstrFile buffer returns the path to the current directory followed by the filenames of the selected files. The nFileOffset member is the offset to the first filename, and the nFileExtension member is not used. For Explorer-style dialog boxes, the directory and filename strings are NULL separated, with an extra NULL character after the last filename. This format enables the Explorer-style dialogs to return long filenames that include spaces. For old-style dialog boxes, the directory and filename strings are separated by spaces and the function uses short filenames for filenames with spaces. You can use the FindFirstFile function to convert between long and short filenames.  If you specify a custom template for an old-style dialog box, the definition of the File Name list box must contain the LBS_EXTENDEDSEL value.
OFN_CREATEPROMPT
	If the user specifies a file that does not exist, this flag causes the dialog box to prompt the user for permission to create the file. If the user chooses to create the file, the dialog box closes and the function returns the specified name; otherwise, the dialog box remains open.
OFN_ENABLEHOOK
	Enables the hook function specified in the lpfnHook member.
OFN_ENABLETEMPLATE
	Indicates that the lpTemplateName member points to the name of a dialog template resource in the module identified by the hInstance member. If the OFN_EXPLORER flag is set, the system uses the specified template to create a dialog box that is a child of the default Explorer-style dialog box. If the OFN_EXPLORER flag is not set, the system uses the template to create an old-style dialog box that replaces the default dialog box.
OFN_ENABLETEMPLATEHANDLE
	Indicates that the hInstance member identifies a data block that contains a preloaded dialog box template. The system ignores the lpTemplateName if this flag is specified. If the OFN_EXPLORER flag is set, the system uses the specified template to create a dialog box that is a child of the default Explorer-style dialog box. If the OFN_EXPLORER flag is not set, the system uses the template to create an old-style dialog box that replaces the default dialog box.
OFN_EXPLORER
	Indicates that any customizations made to the Open or Save As dialog box use the new Explorer-style customization methods. For more information, see the “Explorer-Style Hook Procedures” and “Explorer-Style Custom Templates” sections of the Common Dialog Box Library overview. By default, the Open and Save As dialog boxes use the Explorer-style user interface regardless of whether this flag is set. This flag is necessary only if you provide a hook procedure or custom template, or set the OFN_ALLOWMULTISELECT flag.  If you want the old-style user interface, omit the OFN_EXPLORER flag and provide a replacement old-style template or hook procedure. If you want the old style but do not need a custom template or hook procedure, simply provide a hook procedure that always returns FALSE.
OFN_EXTENSIONDIFFERENT
	Specifies that the user typed a filename extension that differs from the extension specified by lpstrDefExt. The function does not use this flag if lpstrDefExt is NULL.
OFN_FILEMUSTEXIST
	Specifies that the user can type only names of existing files in the File Name entry field. If this flag is specified and the user enters an invalid name, the dialog box procedure displays a warning in a message box. If this flag is specified, the OFN_PATHMUSTEXIST flag is also used.
OFN_HIDEREADONLY
	Hides the Read Only check box.
OFN_LONGNAMES
	For old-style dialog boxes, this flag causes the dialog box to use long filenames. If this flag is not specified, or if the OFN_ALLOWMULTISELECT flag is also set, old-style dialog boxes use short filenames (8.3 format) for filenames with spaces.  Explorer-style dialog boxes ignore this flag and always display long filenames.
OFN_NOCHANGEDIR
	Restores the current directory to its original value if the user changed the directory while searching for files.
OFN_NODEREFERENCELINKS
	Directs the dialog box to return the path and filename of the selected shortcut (.LNK) file. If this value is not given, the dialog box returns the path and filename of the file referenced by the shortcut
OFN_NOLONGNAMES
	For old-style dialog boxes, this flag causes the dialog box to use short filenames (8.3 format).  Explorer-style dialog boxes ignore this flag and always display long filenames.
OFN_NONETWORKBUTTON
	Hides and disables the Network button.
OFN_NOREADONLYRETURN
	Specifies that the returned file does not have the Read Only check box checked and is not in a write-protected directory.
OFN_NOTESTFILECREATE
	Specifies that the file is not created before the dialog box is closed. This flag should be specified if the application saves the file on a create-nonmodify network sharepoint. When an application specifies this flag, the library does not check for write protection, a full disk, an open drive door, or network protection. Applications using this flag must perform file operations carefully, because a file cannot be reopened once it is closed.
OFN_NOVALIDATE
	Specifies that the common dialog boxes allow invalid characters in the returned filename. Typically, the calling application uses a hook procedure that checks the filename by using the FILEOKSTRING message. If the text box in the edit control is empty or contains nothing but spaces, the lists of files and directories are updated. If the text box in the edit control contains anything else, nFileOffset and nFileExtension are set to values generated by parsing the text. No default extension is added to the text, nor is text copied to the buffer specified by lpstrFileTitle.
	If the value specified by nFileOffset is less than zero, the filename is invalid. Otherwise, the filename is valid, and nFileExtension and nFileOffset can be used as if the OFN_NOVALIDATE flag had not been specified.
OFN_OVERWRITEPROMPT
	Causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file.
OFN_PATHMUSTEXIST
	Specifies that the user can type only valid paths and filenames. If this flag is used and the user types an invalid path and filename in the File Name entry field, the dialog box function displays a warning in a message box.
OFN_READONLY
	Causes the Read Only check box to be checked initially when the dialog box is created. This flag indicates the state of the Read Only check box when the dialog box is closed.
OFN_SHAREAWARE
	Specifies that if a call to the OpenFile function fails because of a network sharing violation, the error is ignored and the dialog box returns the selected filename.  If this flag is not set, the dialog box notifies your hook procedure when a network sharing violation occurs for the filename specified by the user. If you set the OFN_EXPLORER flag, the dialog box sends the CDN_SHAREVIOLATION message to the hook procedure. If you do not set OFN_EXPLORER, the dialog box sends the SHAREVISTRING registered message to the hook procedure.
OFN_SHOWHELP
	Causes the dialog box to display the Help button. The hwndOwner member must specify the window to receive the HELPMSGSTRING registered messages that the dialog box sends when the user clicks the Help button. An Explorer-style dialog box sends a CDN_HELP notification message to your hook procedure when the user clicks the Help button.
nFileOffset

Specifies a zero-based offset from the beginning of the path to the filename in the string pointed to by lpstrFile. For example, if lpstrFile points to the following string, “c:\dir1\dir2\file.ext”, this member contains the value 13 to indicate the offset of the “file.ext” string.

nFileExtension

Specifies a zero-based offset from the beginning of the path to the filename extension in the string pointed to by lpstrFile. For example, if lpstrFile points to the following string, “c:\dir1\dir2\file.ext”, this member contains the value 18. If the user did not type an extension and lpstrDefExt is NULL, this member specifies an offset to the terminating null character. If the user typed “.” as the last character in the filename, this member specifies zero.

lpstrDefExt

Points to a buffer that contains the default extension. GetOpenFileName and GetSaveFileName append this extension to the filename if the user fails to type an extension. This string can be any length, but only the first three characters are appended. The string should not contain a period (.). If this member is NULL and the user fails to type an extension, no extension is appended.

lCustData

Specifies application-defined data that the system passes to the hook procedure identified by the lpfnHook member. When the system sends the WM_INITDIALOG message to the hook procedure, the message’s lParam parameter is a pointer to the OPENFILENAME structure specified when the dialog box was created. The hook procedure can use this pointer to get the lCustData value.

lpfnHook

Pointer to a hook procedure. This member is ignored unless the Flags member includes the OFN_ENABLEHOOK flag.

If the OFN_EXPLORER flag is not set in the Flags member, lpfnHook is a pointer to an OFNHookProcOldStyle hook procedure that receives messages intended for the dialog box. The hook procedure returns FALSE to pass a message to the default dialog box procedure or TRUE to discard the message.

If OFN_EXPLORER is set, lpfnHook is a pointer to an OFNHookProc hook procedure. The hook procedure receives notification messages sent from the dialog box. The hook procedure also receives messages for any additional controls that you defined by specifying a child dialog template. The hook procedure does not receive messages intended for the standard controls of the default dialog box.

lpTemplateName

Pointer to a null-terminated string that names a dialog template resource in the module identified by the hInstance member. For numbered dialog box resources, this can be a value returned by the MAKEINTRESOURCE macro. This member is ignored unless the OFN_ENABLETEMPLATE flag is set in the Flags member.

If the OFN_EXPLORER flag is set, the system uses the specified template to create a dialog box that is a child of the default Explorer-style dialog box. If the OFN_EXPLORER flag is not set, the system uses the template to create an old-style dialog box that replaces the default dialog box.

See Also

GetOpenFileName, GetSaveFileName


OSVERSIONINFO

The OSVERSIONINFO data structure contains operating system version information. The information includes major and minor version numbers, a build number, a platform identifier, and descriptive text about the operating system. This structure is used with the GetVersionEx function.

typedef struct _OSVERSIONINFO{

    DWORD dwOSVersionInfoSize;

    DWORD dwMajorVersion;

    DWORD dwMinorVersion;

    DWORD dwBuildNumber;

    DWORD dwPlatformId;

    TCHAR szCSDVersion[ 128 ];

} OSVERSIONINFO;

Members

dwOSVersionInfoSize

Specifies the size, in bytes, of this data structure. Set this member to sizeof(OSVERSIONINFO) before calling the GetVersionEx function.

dwMajorVersion

Identifies the major version number of the operating system. For example, for Windows NT version 3.51, the major version number is 3; and for Windows NT version 4.0, the major version number is 4.

dwMinorVersion

Identifies the minor version number of the operating system. For example, for Windows NT version 3.51, the minor version number is 51; and for Windows NT version 4.0, the minor version number is 0.

dwBuildNumber

Windows NT: Identifies the build number of the operating system.

Windows 95: Identifies the build number of the operating system in the low-order word. The high-order word contains the major and minor version numbers.

dwPlatformId

Identifies the operating system platform. This member can be one of the following values:

Value	Platform
VER_PLATFORM_WIN32s	Win32s on Windows 3.1.
VER_PLATFORM_WIN32_WINDOWS	Win32 on Windows 95.
VER_PLATFORM_WIN32_NT	Win32 on Windows NT.
szCSDVersion

Windows NT: Contains a null-terminated string, such as "Service Pack 3", that indicates the latest Service Pack installed on the system. If no Service Pack has been installed, the string is empty.

Windows 95: Contains a null-terminated string that provides arbitrary additional information about the operating system.

See Also

GetVersionEx


OUTLINETEXTMETRIC

The OUTLINETEXTMETRIC structure contains metrics describing a TrueType font.

typedef struct _OUTLINETEXTMETRIC { // otm

    UINT   otmSize;

    TEXTMETRIC otmTextMetrics;

    BYTE   otmFiller;

    PANOSE otmPanoseNumber;

    UINT   otmfsSelection;

    UINT   otmfsType;

    int    otmsCharSlopeRise;

    int    otmsCharSlopeRun;

    int    otmItalicAngle;

    UINT   otmEMSquare;

    int    otmAscent;

    int    otmDescent;

    UINT   otmLineGap;

    UINT   otmsCapEmHeight;

    UINT   otmsXHeight;

    RECT   otmrcFontBox;

    int    otmMacAscent;

    int    otmMacDescent;

    UINT   otmMacLineGap;

    UINT   otmusMinimumPPEM;

    POINT  otmptSubscriptSize;

    POINT  otmptSubscriptOffset;

    POINT  otmptSuperscriptSize;

    POINT  otmptSuperscriptOffset;

    UINT   otmsStrikeoutSize;

    int    otmsStrikeoutPosition;

    int    otmsUnderscoreSize;

    int    otmsUnderscorePosition;

    PSTR   otmpFamilyName;

    PSTR   otmpFaceName;

    PSTR   otmpStyleName;

    PSTR   otmpFullName;

} OUTLINETEXTMETRIC;

Members

otmSize

Specifies the size, in bytes, of the OUTLINETEXTMETRIC structure.

otmTextMetrics

Specifies a TEXTMETRIC structure containing further information about the font.

otmFiller

Specifies a value that causes the structure to be byte aligned.

otmPanoseNumber

Specifies the PANOSE number for this font.

otmfsSelection

Specifies the nature of the font pattern. This member can be a combination of the following bits:

Bit	Meaning
0	Italic
1	Underscore
2	Negative
3	Outline
4	Strikeout
5	Bold
otmfsType

Specifies whether the font is licensed. Licensed fonts must not be modified or exchanged. If bit 1 is set, the font may not be embedded in a document. If bit 1 is clear, the font can be embedded. If bit 2 is set, the embedding is read-only.

otmsCharSlopeRise

Specifies the slope of the cursor. This value is 1 if the slope is vertical. Applications can use this value and the value of the otmsCharSlopeRun member to create an italic cursor that has the same slope as the main italic angle (specified by the otmItalicAngle member).

otmsCharSlopeRun

Specifies the slope of the cursor. This value is zero if the slope is vertical. Applications can use this value and the value of the otmsCharSlopeRise member to create an italic cursor that has the same slope as the main italic angle (specified by the otmItalicAngle member).

otmItalicAngle

Specifies the main italic angle of the font, in tenths of a degree counterclockwise from vertical. Regular (roman) fonts have a value of zero. Italic fonts typically have a negative italic angle (that is, they lean to the right).

otmEMSquare

Specifies the number of logical units defining the x- or y-dimension of the em square for this font. (The number of units in the x- and y-directions are always the same for an em square.)

otmAscent

Specifies the maximum distance characters in this font extend above the base line. This is the typographic ascent for the font.

otmDescent

Specifies the maximum distance characters in this font extend below the base line. This is the typographic descent for the font.

otmLineGap

Specifies typographic line spacing.

otmsCapEmHeight

Not supported.

otmsXHeight

Not supported.

otmrcFontBox

Specifies the bounding box for the font.

otmMacAscent

Specifies the maximum distance characters in this font extend above the base line for the Macintosh® computer.

otmMacDescent

Specifies the maximum distance characters in this font extend below the base line for the Macintosh® computer.

otmMacLineGap

Specifies line-spacing information for the Macintosh® computer.

otmusMinimumPPEM

Specifies the smallest recommended size for this font, in pixels per em-square.

otmptSubscriptSize

Specifies the recommended horizontal and vertical size for subscripts in this font.

otmptSubscriptOffset

Specifies the recommended horizontal and vertical offset for subscripts in this font. The subscript offset is measured from the character origin to the origin of the subscript character.

otmptSuperscriptSize

Specifies the recommended horizontal and vertical size for superscripts in this font.

otmptSuperscriptOffset

Specifies the recommended horizontal and vertical offset for superscripts in this font. The superscript offset is measured from the character base line to the base line of the superscript character.

otmsStrikeoutSize

Specifies the width of the strikeout stroke for this font. Typically, this is the width of the em dash for the font.

otmsStrikeoutPosition

Specifies the position of the strikeout stroke relative to the base line for this font. Positive values are above the base line and negative values are below.

otmsUnderscoreSize

Specifies the thickness of the underscore character for this font.

otmsUnderscorePosition

Specifies the position of the underscore character for this font.

otmpFamilyName

Specifies the offset from the beginning of the structure to a string specifying the family name for the font.

otmpFaceName

Specifies the offset from the beginning of the structure to a string specifying the typeface name for the font. (This typeface name corresponds to the name specified in the LOGFONT structure.)

otmpStyleName

Specifies the offset from the beginning of the structure to a string specifying the style name for the font.

otmpFullName

Specifies the offset from the beginning of the structure to a string specifying the full name for the font. This name is unique for the font and often contains a version number or other identifying information.

Remarks

The sizes returned in OUTLINETEXTMETRIC are given in logical units; that is, they depend on the current mapping mode of the specified display context.

See Also

GetOutlineTextMetrics, LOGFONT, TEXTMETRIC


OUTPUT_DEBUG_STRING_INFO

The OUTPUT_DEBUG_STRING_INFO structure contains the address, format, and length, in bytes, of a debugging string.

typedef struct _OUTPUT_DEBUG_STRING_INFO { // odsi

    LPSTR lpDebugStringData;

    WORD  fUnicode;

    WORD  nDebugStringLength;

} OUTPUT_DEBUG_STRING_INFO;

Members

lpDebugStringData

Points to the address of the debugging string in the calling process’s address space. The debugger can use the ReadProcessMemory function to retrieve the value of the string.

fUnicode

Specifies the format of the debugging string. If this member is zero, the debugging string is 8-bit ASCII; if it is nonzero, the string is 16-bit Unicode™.

nDebugStringLength

Specifies the length, in bytes, of the debugging string. The length includes the string’s terminating null character.

See Also

DEBUG_EVENT, ReadProcessMemory


OVERLAPPED

The OVERLAPPED structure contains information used in asynchronous input and output (I/O).

typedef struct _OVERLAPPED { // o

    DWORD  Internal;

    DWORD  InternalHigh;

    DWORD  Offset;

    DWORD  OffsetHigh;

    HANDLE hEvent;

} OVERLAPPED;

Members

Internal

Reserved for operating system use. This member, which specifies a system-dependent status, is valid when the GetOverlappedResult function returns without setting the extended error information to ERROR_IO_PENDING.

InternalHigh

Reserved for operating system use. This member, which specifies the length of the data transferred, is valid when the GetOverlappedResult function returns TRUE.

Offset

Specifies a file position at which to start the transfer. The file position is a byte offset from the start of the file. The calling process sets this member before calling the ReadFile or WriteFile function. This member is ignored when reading from or writing to named pipes and communications devices.

OffsetHigh

Specifies the high word of the byte offset at which to start the transfer. This member is ignored when reading from or writing to named pipes and communications devices.

hEvent

Identifies an event set to the signaled state when the transfer has been completed. The calling process sets this member before calling the ReadFile, WriteFile, ConnectNamedPipe, or TransactNamedPipe function.

Remarks

You can use the HasOverlappedIoCompleted macro to determine whether an asynchronous I/O operation has completed. You can use the CancelIo function to cancel an asynchronous I/O operation.

See Also

CancelIo, ConnectNamedPipe, CreateFile, GetOverlappedResult, HasOverlappedIoCompleted, ReadFile, ReadFileEx, TransactNamedPipe, WriteFile, WriteFileEx


PAGESETUPDLG

The PAGESETUPDLG structure contains information the PageSetupDlg function uses to initialize the Page Setup common dialog box. After the user closes the dialog box, the system returns information about the user-defined page parameters in this structure.

typedef struct tagPSD {  // psd

    DWORD           lStructSize;

    HWND            hwndOwner;

    HGLOBAL         hDevMode;

    HGLOBAL         hDevNames;

    DWORD           Flags;

    POINT           ptPaperSize;

    RECT            rtMinMargin;

    RECT            rtMargin;

    HINSTANCE       hInstance;

    LPARAM          lCustData;

    LPPAGESETUPHOOK lpfnPageSetupHook;

    LPPAGEPAINTHOOK lpfnPagePaintHook;

    LPCTSTR         lpPageSetupTemplateName;

    HGLOBAL         hPageSetupTemplate;

} PAGESETUPDLG, * LPPAGESETUPDLG;

Members

lStructSize

Specifies the size, in bytes, of this structure.

hwndOwner

Identifies the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.

hDevMode

Handle to a global memory object that contains a DEVMODE structure. On input, if a handle is given, the values in the corresponding DEVMODE structure are used to initialize the controls in the dialog box. On output, the dialog box sets hDevMode to a global memory handle for a DEVMODE structure that contains values specifying the user’s selections. If the user’s selections are not available, the dialog box sets hDevMode to NULL.

hDevNames

Handle to a global memory object that contains a DEVNAMES structure. This structure contains three strings that specify the driver name, the printer name, and the output port name. On input, if a handle is given, the strings in the corresponding DEVNAMES structure are used to initialize controls in the dialog box. On output, the dialog box sets hDevNames to a  global memory handle for a DEVNAMES structure that contains strings specifying the user’s selections. If the user’s selections are not available, the dialog box sets hDevNames to NULL.

Flags

A set of bit flags that you can use to initialize the Page Setup common dialog box. When the dialog box returns, it sets these flags to indicate the user’s input. This member can be a combination of the following flags:

PSD_DEFAULTMINMARGINS
	Sets the minimum values that the user can specify for the page margins to be the minimum margins allowed by the printer. This is the default. This flag is ignored if the PSD_MARGINS and PSD_MINMARGINS flags are also specified.
PSD_DISABLEMARGINS
	Disables the margin controls, preventing the user from setting the margins.
PSD_DISABLEORIENTATION
	Disables the orientation controls, preventing the user from setting the page orientation.
PSD_DISABLEPAGEPAINTING
	Prevents the dialog box from drawing the contents of the sample page. If you enable a PagePaintHook hook procedure, you can still draw the contents of the sample page.
PSD_DISABLEPAPER
	Disables the paper controls, preventing the user from setting page parameters such as the paper size and source.
PSD_DISABLEPRINTER
	Disables the Printer button, preventing the user from invoking a dialog box that contains additional printer setup information.
PSD_ENABLEPAGEPAINTHOOK
	Enables the hook procedure specified in the lpfnPagePaintHook member.
PSD_ENABLEPAGESETUPHOOK
	Enables the hook procedure specified in the lpfnPageSetupHook member.
PSD_ENABLEPAGESETUPTEMPLATE
	Indicates that the hInstance and lpPageSetupTemplateName members specify a dialog box template to use in place of the default template.
PSD_ENABLEPAGESETUPTEMPLATEHANDLE
	Indicates that the hPageSetupTemplate member identifies a data block that contains a preloaded dialog box template. The system ignores the lpPageSetupTemplateName member if this flag is specified.
PSD_INHUNDREDTHSOFMILLIMETERS
	Indicates that hundredths of millimeters are the unit of measurement for margins and paper size. The values in the rtMargin, rtMinMargin, and ptPaperSize members are in hundredths of millimeters. You can set this flag on input to override the default unit of measurement for the user’s locale. When the function returns, the dialog box sets this flag to indicate the units used.
PSD_INTHOUSANDTHSOFINCHES
	Indicates that thousandths of inches are the unit of measurement for margins and paper size. The values in the rtMargin, rtMinMargin, and ptPaperSize members are in thousandths of inches. You can set this flag on input to override the default unit of measurement for the user’s locale. When the function returns, the dialog box sets this flag to indicate the units used.
PSD_INWININIINTLMEASURE
	Not implemented.
PSD_MARGINS
	Causes the system to use the values specified in the rtMargin member as the initial widths for the left, top, right, and bottom margins. If PSD_MARGINS is not set, the system sets the initial widths to one inch for all margins.
PSD_MINMARGINS
	Causes the system to use the values specified in the rtMinMargin member as the minimum allowable widths for the left, top, right, and bottom margins. The system prevents the user from entering a width that is less than the specified minimum. If PSD_MINMARGINS is not specified, the system sets the minimum allowable widths to those allowed by the printer.
PSD_NOWARNING
	Prevents the system from displaying a warning message when there is no default printer.
PSD_RETURNDEFAULT
	PageSetupDlg does not display the dialog box. Instead, it sets the hDevNames and hDevMode members to handles to DEVMODE and DEVNAMES structures that are initialized for the system default printer. PageSetupDlg returns an error if either hDevNames or hDevMode is not NULL.
PSD_SHOWHELP
	Causes the dialog box to display the Help button. The hwndOwner member must specify the window to receive the HELPMSGSTRING registered messages that the dialog box sends when the user clicks the Help button.
ptPaperSize

Specifies the dimensions of the paper selected by the user. The PSD_INTHOUSANDTHSOFINCHES or PSD_INHUNDREDTHSOFMILLIMETERS flag indicates the units of measurement.

rtMinMargin

Specifies the minimum allowable widths for the left, top, right, and bottom margins. The system ignores this member if the PSD_MINMARGINS flag is not set. These values must be less than or equal to the values specified in the rtMargin member. The PSD_INTHOUSANDTHSOFINCHES or PSD_INHUNDREDTHSOFMILLIMETERS flag indicates the units of measurement.

rtMargin

Specifies the widths of the left, top, right, and bottom margins. If you set the PSD_MARGINS flag, rtMargin specifies the initial margin values. When PageSetupDlg returns, rtMargin contains the margin widths selected by the user. The PSD_INHUNDREDTHSOFMILLIMETERS or PSD_INTHOUSANDTHSOFINCHES flag indicates the units of measurement.

hInstance

If the PSD_ENABLEPAGESETUPTEMPLATE flag is set in the Flags member, hInstance is the handle of the application or module instance that contains the dialog box template named by the lpPageSetupTemplateName member.

lCustData

Specifies application-defined data that the system passes to the hook procedure identified by the lpfnPageSetupHook member. When the system sends the WM_INITDIALOG message to the hook procedure, the message’s lParam parameter is a pointer to the PAGESETUPDLG structure specified when the dialog was created. The hook procedure can use this pointer to get the lCustData value.

lpfnPageSetupHook

Pointer to a PageSetupHook hook procedure that can process messages intended for the dialog box. This member is ignored unless the PSD_ENABLEPAGESETUPHOOK flag is set in the Flags member.

lpfnPagePaintHook

Pointer to a PagePaintHook hook procedure that receives WM_PSD_* messages from the dialog box whenever the sample page is redrawn. By processing the messages, the hook procedure can customize the appearance of the sample page. This member is ignored unless the PSD_ENABLEPAGEPAINTHOOK flag is set in the Flags member.

lpPageSetupTemplateName

Pointer to a null-terminated string that names the dialog box template resource in the module identified by the hInstance member. This template is substituted for the standard dialog box template. For numbered dialog box resources, lpPageSetupTemplateName can be a value returned by the MAKEINTRESOURCE macro. This member is ignored unless the PSD_ENABLEPAGESETUPTEMPLATE flag is set in the Flags member.

hPageSetupTemplate

If the PSD_ENABLEPAGESETUPTEMPLATEHANDLE flag is set in the Flags member, hPageSetupTemplate is the handle of a memory object containing a dialog box template.

Remarks

If the PSD_INHUNDREDTHSOFMILLIMETERS and PSD_INTHOUSANDTHSOFINCHES flags are not specified, the system queries the LOCALE_IMEASURE value of the default user locale to determine the unit of measure (either hundredths of millimeters or thousandths of inches) for the margin widths and paper size.

If both hDevNames and hDevMode have valid handles and the printer name specified by the wDeviceOffset member of the DEVNAMES structure is not the same as the name specified by the dmDeviceName member of the DEVMODE structure, the system uses the name specified by wDeviceOffset by default.

See Also

DEVMODE, DEVNAMES, MAKEINTRESOURCE, PagePaintHook, PageSetupDlg, PageSetupHook, WM_INITDIALOG


PAINTSTRUCT

The PAINTSTRUCT structure contains information for an application. This information can be used to paint the client area of a window owned by that application.

typedef struct tagPAINTSTRUCT { // ps

    HDC  hdc;

    BOOL fErase;

    RECT rcPaint;

    BOOL fRestore;

    BOOL fIncUpdate;

    BYTE rgbReserved[32];

} PAINTSTRUCT;

Members

hdc

Identifies the display DC to be used for painting.

fErase

Specifies whether the background must be erased. This value is nonzero if the application should erase the background. The application is responsible for erasing the background if a window class is created without a background brush. For more information, see the description of the hbrBackground member of the WNDCLASS structure.

rcPaint

Specifies a RECT structure that specifies the upper left and lower right corners of the rectangle in which the painting is requested.

fRestore

Reserved; used internally by Windows.

fIncUpdate

Reserved; used internally by Windows.

rgbReserved

Reserved; used internally by Windows.

See Also

BeginPaint, RECT, WNDCLASS


PALETTEENTRY

The PALETTEENTRY structure specifies the color and usage of an entry in a logical color palette. A logical palette is defined by a LOGPALETTE structure.

typedef struct tagPALETTEENTRY { // pe

    BYTE peRed;

    BYTE peGreen;

    BYTE peBlue;

    BYTE peFlags;

} PALETTEENTRY;

Members

peRed

Specifies a red intensity value for the palette entry.

peGreen

Specifies a green intensity value for the palette entry.

peBlue

Specifies a blue intensity value for the palette entry.

peFlags

Specifies how the palette entry is to be used. The peFlags member may be set to NULL or one of the following values:

Value	Meaning
PC_EXPLICIT	Specifies that the low-order word of the logical palette entry designates a hardware palette index. This flag allows the application to show the contents of the display device palette.
PC_NOCOLLAPSE	Specifies that the color be placed in an unused entry in the system palette instead of being matched to an existing color in the system palette. If there are no unused entries in the system palette, the color is matched normally. Once this color is in the system palette, colors in other logical palettes can be matched to this color.
PC_RESERVED	Specifies that the logical palette entry be used for palette animation. This flag prevents other windows from matching colors to the palette entry since the color frequently changes. If an unused system-palette entry is available, the color is placed in that entry. Otherwise, the color is not available for animation.
See Also

LOGPALETTE


PANOSE

The PANOSE structure describes the PANOSE font-classification values for a TrueType font. These characteristics are then used to associate the font with other fonts of similar appearance but different names.

typedef struct tagPANOSE { // pnse

    BYTE bFamilyType;

    BYTE bSerifStyle;

    BYTE bWeight;

    BYTE bProportion;

    BYTE bContrast;

    BYTE bStrokeVariation;

    BYTE bArmStyle;

    BYTE bLetterform;

    BYTE bMidline;

    BYTE bXHeight;

} PANOSE

Members

bFamilyType

For Latin fonts, bFamilyType can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_FAMILY_TEXT_DISPLAY	Text and display
PAN_FAMILY_SCRIPT	Script
PAN_FAMILY_DECORATIVE	Decorative
PAN_FAMILY_PICTORIAL	Pictorial
bSerifStyle

Specifies the serif style. For Latin fonts, bSerifStyle can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_SERIF_COVE	Cove
PAN_SERIF_OBTUSE_COVE	Obtuse cove
PAN_SERIF_SQUARE_COVE	Square cove
PAN_SERIF_OBTUSE_SQUARE_COVE	Obtuse square cove
PAN_SERIF_SQUARE	Square
PAN_SERIF_THIN	Thin
PAN_SERIF_BONE	Bone
PAN_SERIF_EXAGGERATED	Exaggerated
PAN_SERIF_TRIANGLE	Triangle
PAN_SERIF_NORMAL_SANS	Normal sans serif
PAN_SERIF_OBTUSE_SANS	Obtuse sans serif
PAN_SERIF_PERP_SANS	Perp sans serif
PAN_SERIF_FLARED	Flared
PAN_SERIF_ROUNDED	Rounded
bWeight

For Latin fonts, bWeight can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_WEIGHT_VERY_LIGHT	Very light
PAN_WEIGHT_LIGHT	Light
PAN_WEIGHT_THIN	Thin
PAN_WEIGHT_BOOK	Book
PAN_WEIGHT_MEDIUM	Medium
PAN_WEIGHT_DEMI	Demibold
PAN_WEIGHT_BOLD	Bold
PAN_WEIGHT_HEAVY	Heavy
PAN_WEIGHT_BLACK	Black
PAN_WEIGHT_NORD	Nord
bProportion

For Latin fonts, bProportion can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_PROP_OLD_STYLE	Old style
PAN_PROP_MODERN	Modern
PAN_PROP_EVEN_WIDTH	Even width
PAN_PROP_EXPANDED	Expanded
PAN_PROP_CONDENSED	Condensed
PAN_PROP_VERY_EXPANDED	Very expanded
PAN_PROP_VERY_CONDENSED	Very condensed
PAN_PROP_MONOSPACED	Monospaced
bContrast

For Latin fonts, bContrast can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_CONTRAST_NONE	None
PAN_CONTRAST_VERY_LOW	Very low
PAN_CONTRAST_LOW	Low
PAN_CONTRAST_MEDIUM_LOW	Medium low
PAN_CONTRAST_MEDIUM	Medium
PAN_CONTRAST_MEDIUM_HIGH	Medium high
PAN_CONTRAST_HIGH	High
PAN_CONTRAST_VERY_HIGH	Very high
bStrokeVariation

For Latin fonts, bStrokeVariation can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_STROKE_GRADUAL_DIAG	Gradual/diagonal
PAN_STROKE_GRADUAL_TRAN	Gradual/transitional
PAN_STROKE_GRADUAL_VERT	Gradual/vertical
PAN_STROKE_GRADUAL_HORZ	Gradual/horizontal
PAN_STROKE_RAPID_VERT	Rapid/vertical
PAN_STROKE_RAPID_HORZ	Rapid/horizontal
PAN_STROKE_INSTANT_VERT	Instant/vertical
bArmStyle

For Latin fonts, bArmStyle can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_STRAIGHT_ARMS_HORZ	Straight arms/horizontal
PAN_STRAIGHT_ARMS_WEDGE	Straight arms/wedge
PAN_STRAIGHT_ARMS_VERT	Straight arms/vertical
PAN_STRAIGHT_ARMS_SINGLE_SERIF	Straight arms/single-serif
PAN_STRAIGHT_ARMS_DOUBLE_SERIF	Straight arms/double-serif
PAN_BENT_ARMS_HORZ	Nonstraight arms/horizontal
PAN_BENT_ARMS_WEDGE	Nonstraight arms/wedge
PAN_BENT_ARMS_VERT	Nonstraight arms/vertical
PAN_BENT_ARMS_SINGLE_SERIF	Nonstraight arms/single-serif
PAN_BENT_ARMS_DOUBLE_SERIF	Nonstraight arms/double-serif
bLetterform

For Latin fonts, bLetterform can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_LETT_NORMAL_CONTACT	Normal/contact
PAN_LETT_NORMAL_WEIGHTED	Normal/weighted
PAN_LETT_NORMAL_BOXED	Normal/boxed
PAN_LETT_NORMAL_FLATTENED	Normal/flattened
PAN_LETT_NORMAL_ROUNDED	Normal/rounded
PAN_LETT_NORMAL_OFF_CENTER	Normal/off center
PAN_LETT_NORMAL_SQUARE	Normal/square
PAN_LETT_OBLIQUE_CONTACT	Oblique/contact
PAN_LETT_OBLIQUE_WEIGHTED	Oblique/weighted
PAN_LETT_OBLIQUE_BOXED	Oblique/boxed
PAN_LETT_OBLIQUE_FLATTENED	Oblique/flattened
PAN_LETT_OBLIQUE_ROUNDED	Oblique/rounded
PAN_LETT_OBLIQUE_OFF_CENTER	Oblique/off center
PAN_LETT_OBLIQUE_SQUARE	Oblique/square
bMidline

For Latin fonts, bMidline can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_MIDLINE_STANDARD_TRIMMED	Standard/trimmed
PAN_MIDLINE_STANDARD_POINTED	Standard/pointed
PAN_MIDLINE_STANDARD_SERIFED	Standard/serifed
PAN_MIDLINE_HIGH_TRIMMED	High/trimmed
PAN_MIDLINE_HIGH_POINTED	High/pointed
PAN_MIDLINE_HIGH_SERIFED	High/serifed
PAN_MIDLINE_CONSTANT_TRIMMED	Constant/trimmed
PAN_MIDLINE_CONSTANT_POINTED	Constant/pointed
PAN_MIDLINE_CONSTANT_SERIFED	Constant/serifed
PAN_MIDLINE_LOW_TRIMMED	Low/trimmed
PAN_MIDLINE_LOW_POINTED	Low/pointed
PAN_MIDLINE_LOW_SERIFED	Low/serifed
bXHeight

For Latin fonts, bXHeight can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_XHEIGHT_CONSTANT_SMALL	Constant/small
PAN_XHEIGHT_CONSTANT_STD	Constant/standard
PAN_XHEIGHT_CONSTANT_LARGE	Constant/large
PAN_XHEIGHT_DUCKING_SMALL	Ducking/small
PAN_XHEIGHT_DUCKING_STD	Ducking/standard
PAN_XHEIGHT_DUCKING_LARGE	Ducking/large


PARAFORMAT

The PARAFORMAT structure contains information about paragraph formatting attributes in a rich edit control. This structure is used with the EM_GETPARAFORMAT and EM_SETPARAFORMAT messages.

typedef struct _paraformat {

    UINT cbSize;

    _WPAD _wPad1;

    DWORD dwMask;

    WORD  wNumbering;

    WORD  wReserved;

    LONG  dxStartIndent;

    LONG  dxRightIndent;

    LONG  dxOffset;

    WORD  wAlignment;

    SHORT cTabCount;

    LONG  rgxTabs[MAX_TAB_STOPS];

} PARAFORMAT;

Members

cbSize

Size in bytes of this structure. Must be filled before passing to the rich edit control.

dwMask

Members containing valid information or attributes to set. This parameter can be zero or more of these values:

Value	Meaning
PFM_ALIGNMENT	The wAlignment member is valid.
PFM_NUMBERING	The wNumbering member is valid.
PFM_OFFSET	The dxOffset member is valid.
PFM_OFFSETINDENT	The dxStartIndent member is valid and specifies a relative value.
PFM_RIGHTINDENT	The dxRightIndent member is valid.
PFM_STARTINDENT	The dxStartIndent member is valid.
PFM_TABSTOPS	The cTabStobs and rgxTabStops members are valid.
If both PFM_STARTINDENT and PFM_OFFSETINDENT are specified, PFM_STARTINDENT takes precedence.

wNumbering

Value specifying numbering options. This member can be zero or PFN_BULLET.

dxStartIndent

Indentation of the first line in the paragraph. If the paragraph formatting is being set and PFM_OFFSETINDENT is specified, this member is treated as a relative value that is added to the starting indentation of each affected paragraph.

dxRightIndent

Size of the right indentation, relative to the right margin.

dxOffset

Indentation of the second line and subsequent lines, relative to the starting indentation. The first line is indented if this member is negative, or outdented is this member is positive.

wAlignment

Value specifying the paragraph alignment. This member can be one of the following values:

Value	Meaning
PFA_LEFT	Paragraphs are aligned with the left margin.
PFA_RIGHT	Paragraphs are aligned with the right margin.
PFA_CENTER	Paragraphs are centered.
cTabCount

Number of tab stops.

rgxTabs

Array of absolute tab stop positions.

See Also

EM_GETPARAFORMAT, EM_SETPARAFORMAT


PARTITION_INFORMATION

The PARTITION_INFORMATION structure provides information about a disk partition.

typedef struct _PARTITION_INFORMATION {

    LARGE_INTEGER StartingOffset;

    LARGE_INTEGER PartitionLength;

    DWORD HiddenSectors;

    DWORD PartitionNumber;

    BYTE  PartitionType;

    BOOLEAN BootIndicator;

    BOOLEAN RecognizedPartition;

    BOOLEAN RewritePartition;

} PARTITION_INFORMATION, *PPARTITION_INFORMATION;

Members

StartingOffset

Specifies the starting offset of the partition.

PartitionLength

Specifies the length of the partition.

HiddenSectors

Specifies the number of hidden sectors in the partition.

PartitionNumber

Specifies the number of the partition (1-based).

PartitionType

Specifies the type of partition. This member can be one of the following values: Value	Meaning
PARTITION_ENTRY_UNUSED	Entry unused.
PARTITION_FAT_12	Specifies a partition with 12-bit FAT entries.
PARTITION_XENIX_1	Specifies a Xenix type 1 partition.
PARTITION_XENIX_2	Specifies a Xenix type 2 partition.
PARTITION_FAT_16	Specifies a partition with 16-bit FAT entries.
PARTITION_EXTENDED	Specifies an extended partition entry.
PARTITION_HUGE	Specifies an MS-DOS V4 huge partition.
PARTITION_IFS	Specifies an IFS partition.
PARTITION_PREP	Specifies a PowerPC Reference Platform partition.
PARTITION_UNIX	Specifies a UNIX partition.
VALID_NTFT	Specifies an NTFT partition.
PARTITION_XINT13	Specifies a Windows 95 partition that uses extended int13 services.
PARTITION_XINT13_EXTENDED	Same as PARTITION_EXTENDED, but uses extended int13 services.
BootIndicator

Specifies whether the partition is bootable.

RecognizedPartition

Specifies whether the partition is recognized.

RewritePartition

Specifies whether the partition information has changed. When you change a partition (with IOCTL_DISK_SET_DRIVE_LAYOUT), the system uses this member to determine which partitions have changed and need their information rewritten.

Remarks

The DeviceIoControl function receives a PARTITION_INFORMATION structure in response to an IOCTL_DISK_GET_PARTITION_INFO or IOCTL_DISK_GET_DRIVE_LAYOUT device input and output control (IOCTL) operation. The DeviceIoControl function uses a PARTITION_INFORMATION structure as input to an IOCTL_DISK_SET_DRIVE_LAYOUT device IOCTL operation.

See Also

DeviceIoControl, IOCTL_DISK_GET_DRIVE_LAYOUT, IOCTL_DISK_GET_PARTITION_INFO, IOCTL_DISK_SET_DRIVE_LAYOUT


POINT

The POINT structure defines the x- and y- coordinates of a point.

typedef struct tagPOINT { // pt

    LONG x;

    LONG y;

} POINT;

Members

x

Specifies the x-coordinate of the point.

y

Specifies the y-coordinate of the point.

See Also

ChildWindowFromPoint, GetBrushOrgEx, PtInRect, SetBrushOrgEx, WindowFromPoint


POINTFX

The POINTFX structure contains the coordinates of points that describe the outline of a character in a TrueType font.

typedef struct tagPOINTFX { // ptfx

    FIXED x;

    FIXED y;

} POINTFX;

Members

x

Specifies the x-component of a point on the outline of a TrueType character.

y

Specifies the y-component of a point on the outline of a TrueType character.

Remarks

The POINTFX structure is a member of the TTPOLYCURVE and TTPOLYGONHEADER structures. Values in the POINTFX structure are specified in device units.

See Also

FIXED, TTPOLYCURVE, TTPOLYGONHEADER


POINTL

The POINTL structure contains the coordinates of a point.

typedef struct _POINTL { // ptl

    LONG x;

    LONG y;

} POINTL;

Members

x

Specifies the horizontal (x) coordinate of the point.

y

Specifies the vertical (y) coordinate of the point.


POINTS

The POINTS structure defines the coordinates of a point.

typedef struct tagPOINTS { // pts

    SHORT x;

    SHORT y;

} POINTS;

Members

x

Specifies the x-coordinate of the point.

y

Specifies the y-coordinate of the point.

See Also

ChildWindowFromPoint, PtInRect, WindowFromPoint, POINT


POLYTEXT

The POLYTEXT structure describes how the PolyTextOut function should draw a string of text.

typedef struct _POLYTEXT { // ptxt

    int     x;

    int     y;

    UINT    n;

    LPCTSTR lpstr;

    UINT    uiFlags;

    RECT    rcl;

    int     *pdx;

} POLYTEXT;

Members

x

Specifies the horizontal reference point for the string. The string is aligned to this point using the current text-alignment mode.

y

Specifies the vertical reference point for the string. The string is aligned to this point using the current text-alignment mode.

n

Specifies the number of characters in the string.

uiFlags

Specifies whether the string is to be opaque or clipped and whether the string is accompanied by an array of character-width values. This member can be one or more of the following values:

Value	Meaning
ETO_OPAQUE	The rectangles given for each string is to be opaqued with the current background color.
ETO_CLIPPED	Each string is to be clipped to its given rectangle.
lpstr

Points to a string of text to be drawn by the PolyTextOut function.

rcl

Specifies a rectangle structure that contains the dimensions of the opaquing or clipping rectangle. This member is ignored if neither of the ETO_OPAQUE nor the ETO_CLIPPED value is specified for the uiFlags member.

pdx

Specifies in an array the width value for each character in the string.

See Also

PolyTextOut


PopupMenuItem

The PopupMenuItem structure contains information about the menu items in a menu resource that open a menu or a submenu.

struct PopupMenuItem {

    DWORD type;

    DWORD state;

    DWORD id;

    WORD resInfo;

    szOrOrd menuText;

};

Members

type

Specifies a set of type flags that you can use to describe the menu item. Some of the values this member can have include:

Value	Meaning
MF_END	The menu item is the last on the menu; the flag is used internally by the system.
MF_POPUP	The menu item opens a menu or a submenu; the flag is used internally by the system.
If you specify MF_POPUP, it indicates that the menu item is one that opens a menu or a submenu.

In addition to the values MF_END and MF_POPUP, this member can also be a combination of the type values listed with the dwType member of the MENUITEMINFO structure. The type values are those that begin with MFT_. To use these predefined MFT_* type values, include the following statement in your .RC file:

#include “WINUSER.H”

state

Specifies a set of state flags that you can use to describe the menu item. This member can be a combination of the state values listed with the dwState member of the MENUITEMINFO structure. The state values are those that begin with MFS_. To use these predefined MFS_* state values, include the following statement in your .RC file:

#include “WINUSER.H”

id

A numeric expression that identifies the menu item that is passed in the WM_COMMAND message.

resInfo

A set of bit flags that specify the type of menu item. This member can be one of the following values.

Value	Meaning
MFR_END	The menu item is the last in this submenu or menu resource; this flag is used internally by the system.
MFR_POPUP	The menu item opens a menu or a submenu; the flag is used internally by the system.
menuText

Specifies a null-terminated Unicode string that contains the text for this menu item. There is no fixed limit on the size of this string.

Remarks

There is one PopupMenuItem structure for each menu item that opens a menu or a submenu. Identify this type of menu item by setting the type member to MF_POPUP and by setting the MFR_POPUP bit in the resInfo member to 0x0001. In this case, the final data written to the RT_MENU resource for the menu or submenu is the MENUHELPID structure. MENUHELPID contains a numeric expression that identifies the menu during WM_HELP processing.

Additionally, every PopupMenuItem structure that has the MFR_POPUP bit set in the resInfo member will be followed by a MENUHELPID structure plus an additional number of PopupMenuItem structures, one for each menu item in that submenu. The last PopupMenuItem structure in the submenu will have the MFR_END bit set in the resInfo member. To find the end of the resource, look for a matching MFR_END for every MFR_POPUP plus one additional MFR_END that matches the outermost set of menu items.

Indicate the last menu item by setting the type member to MF_END. Because you can nest submenus, there can be multiple levels of MF_END. In these instances, the menu items are sequential.

See Also

MenuHeader, MENUHELPID, MENUITEMINFO, NormalMenuItem


PORT_INFO_1

The PORT_INFO_1 structure identifies a supported printer port.

typedef struct _PORT_INFO_1 { // pi1

    LPTSTR pName;

} PORT_INFO_1;

Members

pName

Points to a null-terminated string that identifies a supported printer port (for example, “LPT1:”).

See Also

EnumPorts


PORT_INFO_2 [Now Supported on Windows NT]
PORT_INFO_2

[Now Supported on Windows NT]

The PORT_INFO_2 structure identifies a supported printer port.

typedef struct _PORT_INFO_2 { // pi2

    LPSTR pPortName;

    LPSTR pMonitorName

    LPSTR pDescription;

    DWORD fPortType;

    DWORD Reserved;

} PORT_INFO_2;

Members

pPortName

Points to a null-terminated string that identifies a supported printer port (for example, “LPT1:”).

pMonitorName

Points to a null-terminated string that identifies an installed monitor (for example, “PJL monitor”).

pDescription

Points to a null-terminated string that describes the port in more detail (for example, if pPortName is “LPT1:”, pDescription is “printer port”).

fPortType

Identifies the type of port. Can be one of these values:

PORT_TYPE_WRITE

PORT_TYPE_READ

PORT_TYPE_REDIRECTED

PORT_TYPE_NET_ATTACHED

Reserved

Reserved; must be zero.

Remarks

Use the PORT_INFO_2 structure when calling EnumPorts if there are multiple monitors installed that support the same ports.

See Also

EnumPorts


PORT_INFO_3 [New - Windows NT]
PORT_INFO_3

[New - Windows NT]

The PORT_INFO_3 structure specifies the status value of a printer port.

typedef struct _PORT_INFO_3 { // pi3

    DWORD dwStatus;

    LPTSTR pszStatus;

    DWORD dwSeverity;

} PORT_INFO_3;

Members

dwStatus

Specifies the new port status value. This value is used only if the pszStatus member is NULL.

This member can be one of the following values:

Value	Meaning
0	Clears the printer port status.
PORT_STATUS_OFFLINE	The port’s printer is offline.
PORT_STATUS_PAPER_JAM	The port’s printer has a paper jam.
PORT_STATUS_PAPER_OUT	The port’s printer is out of paper.
PORT_STATUS_OUTPUT_BIN_FULL	The port’s printer’s output bin is full.
PORT_STATUS_PAPER_PROBLEM	The port’s printer has a paper problem.
PORT_STATUS_NO_TONER	The port’s printer is out of toner.
PORT_STATUS_DOOR_OPEN	The door of the port’s printer is open.
PORT_STATUS_OUT_OF_MEMORY	The port’s printer is out of memory.
PORT_STATUS_TONER_LOW	The port’s printer is low on toner.
PORT_STATUS_WARMING_UP	The port’s printer is warming up.
PORT_STATUS_POWER_SAVE	The port’s printer is in a power-conservation mode.
pzStatus

Pointer to a new printer port status value string to set. Use this member if there is no suitable status value among those listed for dwStatus.

dwSeverity

Specifies the severity of the port status value.

This member can be one of the following values:

Value	Meaning
PORT_STATUS_TYPE_ERROR	The port status value indicates an error.
PORT_STATUS_TYPE_WARNING	The port status value is a warning.
PORT_STATUS_TYPE_INFORMATIONAL	The port status value is informational.
Remarks

When you set a printer port status value with the severity value PORT_STATUS_TYPE_ERROR, the print spooler stops sending jobs to the port. The print spooler does not resume sending jobs to the port until another SetPort call is made to clear the status.

See Also

SetPort


PREVENT_MEDIA_REMOVAL

The PREVENT_MEDIA_REMOVAL structure provides removable media locking data.

typedef struct _PREVENT_MEDIA_REMOVAL{

   BOOLEAN PreventMediaRemoval;

} PREVENT_MEDIA_REMOVAL ;

Members

PreventMediaRemoval

Specifies whether the media is to be locked (if TRUE) or not (if FALSE).

Remarks

The DeviceIoControl function uses a PREVENT_MEDIA_REMOVAL structure as input to an IOCTL_DISK_MEDIA_REMOVAL device input and output operation.

See Also

DeviceIoControl, IOCTL_DISK_MEDIA_REMOVAL


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.

See Also

NetAlertRaise


PRINTDLG

The PRINTDLG structure contains information that the PrintDlg function uses to initialize the Print common dialog box. After the user closes the dialog box, the system returns information about the user-defined print selections in this structure.

typedef struct tagPD {  // pd

    DWORD     lStructSize;

    HWND      hwndOwner;

    HANDLE    hDevMode;

    HANDLE    hDevNames;

    HDC       hDC;

    DWORD     Flags;

    WORD      nFromPage;

    WORD      nToPage;

    WORD      nMinPage;

    WORD      nMaxPage;

    WORD      nCopies;

    HINSTANCE hInstance;

    DWORD     lCustData;

    LPPRINTHOOKPROC lpfnPrintHook;

    LPSETUPHOOKPROC lpfnSetupHook;

    LPCTSTR    lpPrintTemplateName;

    LPCTSTR    lpSetupTemplateName;

    HANDLE    hPrintTemplate;

    HANDLE    hSetupTemplate;

} PRINTDLG;

Members

lStructSize

Specifies the structure size, in bytes.

hwndOwner

Identifies the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.

hDevMode

Identifies a movable global memory object that contains a DEVMODE structure. Before a call to the PrintDlg function, the structure members may contain data used to initialize the dialog controls. When PrintDlg returns, the structure members specify the state of the dialog box controls.

If you use the structure to initialize the dialog box controls, you must allocate space for and create the DEVMODE structure. (You should allocate a movable block of memory.)

If you do not use the structure to initialize the dialog box controls, hDevMode may be NULL. In this case, PrintDlg allocates memory for the structure, initializes its members, and returns a handle that identifies it.

If the device driver for the specified printer does not support extended device modes, hDevMode is NULL when PrintDlg returns.

If the device name (specified by the dmDeviceName member of the DEVMODE structure) does not appear in the [devices] section of WIN.INI, PrintDlg returns an error.

Because this structure is a movable global memory object, the value of hDevMode may change during the execution of PrintDlg.

For a discussion of how the system resolves a possible data collision between values specified by the hDevMode and hDevNames members, see the following Remarks section.

hDevNames

Identifies a movable global memory object that contains a DEVNAMES structure. This structure contains three strings that specify the driver name, the printer name, and the output port name. Before the call to PrintDlg, the structure members contain strings used to initialize dialog box controls. When PrintDlg returns, the structure members contain the strings typed by the user. The calling application uses these strings to create a device context or an information context.

If you use the structure to initialize the dialog box controls, you must allocate space for and create the DEVNAMES structure. (You should allocate a movable block of global memory.)

If you do not use the structure to initialize the dialog box controls, hDevNames may be NULL. In this case, PrintDlg allocates memory for the structure, initializes its members (by using the printer name specified in the DEVMODE structure), and returns a handle that identifies it. PrintDlg uses the first port name that appears in the [devices] section of WIN.INI when it initializes the members in the DEVNAMES structure. For example, the function uses “LPT1:” as the port name if the following string appears in the [devices] section:

PCL / HP LaserJet=HPPCL,LPT1:,LPT2:

If both hDevMode and hDevNames are NULL, PrintDlg initializes hDevNames using the current default printer.

Because this structure is a movable global memory object, the value of hDevNames may change during the execution of PrintDlg.

For a discussion of how the system resolves a possible data collision between values specified by hDevNames and hDevMode, see the Remarks section later in this topic.

hDC

Identifies a device context or an information context, depending on whether the Flags member specifies the PD_RETURNDC or PC_RETURNIC flag. If neither flag is specified, the value of this member is undefined. If both flags are specified, PD_RETURNDC has priority.

Flags

A set of bit flags that you can use to initialize the Print common dialog box. When the dialog box returns, it sets these flags to indicate the user’s input. This member can be a combination of the following flags:

PD_ALLPAGES
	The default flag that indicates that the All radio button is initially selected. This flag is used as a placeholder to indicate that the PD_PAGENUMS and PD_SELECTION flags are not specified.
PD_COLLATE
	Places a checkmark in the Collate check box when set on input. When the PrintDlg function returns, this flag indicates that the user selected the Collate option and the printer driver does not support collation. In this case, the application must provide collation. If PrintDlg sets the PD_COLLATE flag on return, the dmCollate member of the DEVMODE structure is undefined.
PD_DISABLEPRINTTOFILE
	Disables the Print to File check box.
PD_ENABLEPRINTHOOK
	Enables the hook procedure specified in the lpfnPrintHook member. This enables the hook procedure for the Print dialog box.
PD_ENABLEPRINTTEMPLATE
	Indicates that the hInstance and lpPrintTemplateName members specify a dialog box template to use in place of the default template for the Print dialog box.
PD_ENABLEPRINTTEMPLATEHANDLE
	Indicates that the hPrintTemplate member identifies a data block that contains a preloaded dialog box template. The system uses this template in place of the default template for the Print dialog box. The system ignores the lpPrintTemplateName member if this flag is specified.
PD_ENABLESETUPHOOK
	Enables the hook procedure specified in the lpfnSetupHook member. This enables the hook procedure for the Print Setup dialog box.
PD_ENABLESETUPTEMPLATE
	Indicates that the hInstance and lpSetupTemplateName members specify a dialog box template to use in place of the default template for the Print Setup dialog box.
PD_ENABLESETUPTEMPLATEHANDLE
	Indicates that the hSetupTemplate member identifies a data block that contains a preloaded dialog box template. The system uses this template in place of the default template for the Print Setup dialog box. The system ignores the lpSetupTemplateName member if this flag is specified.
PD_HIDEPRINTTOFILE
	Hides the Print to File check box.
PD_NOPAGENUMS
	Disables the Pages radio button and the associated edit controls.
PD_NOSELECTION
	Disables the Selection radio button.
PD_NOWARNING
	Prevents the warning message from being displayed when there is no default printer.
PD_PAGENUMS
	Causes the Pages radio button to be in the selected state when the dialog box is created. When PrintDlg returns, this flag is set if the Pages radio button is in the selected state.
PD_PRINTSETUP
	Causes the system to display the Print Setup dialog box rather than the Print dialog box.
PD_PRINTTOFILE
	Causes the Print to File check box to be checked when the dialog box is created.  When PrintDlg returns, this flag is set if the check box  is checked. In this case, the offset indicated by the wOutputOffset member of the DEVNAMES structure contains the string “FILE:”. When you call the StartDoc function to start the printing operation, specify this “FILE:” string in the lpszOutput member of the DOCINFO structure. Specifying this string causes the print subsystem to query the user for the name of the output file.
PD_RETURNDC
	Causes PrintDlg to return a device context matching the selections the user made in the dialog box. The device context is returned in hDC.
PD_RETURNDEFAULT
	The PrintDlg function does not display the dialog box. Instead, it sets the hDevNames and hDevMode members to handles to DEVMODE and DEVNAMES structures that are initialized for the system default printer. Both hDevNames or hDevMode must be NULL, or PrintDlg returns an error. If the system default printer is supported by an old printer driver (earlier than Windows version 3.0), only hDevNames is returned; hDevMode is NULL.
PD_RETURNIC
	Similar to the PD_RETURNDC flag, except that this flag returns an information context rather than a device context. If neither PD_RETURNDC nor PD_RETURNIC is specified, hDC is undefined on output.
PD_SELECTION
	Causes the Selection radio button to be in the selected state when the dialog box is created. When PrintDlg returns, this flag is specified if the Selection radio button is selected. If neither PD_PAGENUMS nor PD_SELECTION is set, the All radio button is selected.
PD_SHOWHELP
	Causes the dialog box to display the Help button. The hwndOwner member must specify the window to receive the HELPMSGSTRING registered messages that the dialog box sends when the user clicks the Help button.
PD_USEDEVMODECOPIES
	Same as PD_USEDEVMODECOPIESANDCOLLATE
PD_USEDEVMODECOPIESANDCOLLATE
	Disables the Copies edit control if the printer driver does not support multiple copies, and disables the Collate checkbox if the printer driver does not support collation. If this flag is not specified, PrintDlg stores the user selections for the Copies and Collate options in the dmCopies and dmCollate members of the DEVMODE structure.
	If this flag isn’t set, the copies and collate information is returned in the DEVMODE structure if the driver supports multiple copies and collation. If the driver doesn’t support multiple copies and collation, the information is returned in the PRINTDLG structure. This means that an application only has to look at nCopies and PD_COLLATE to determine how many copies it needs to render and whether it needs to print them collated.
nFromPage

Specifies the initial value for the starting page edit control. When the PrintDlg function returns, nFromPage specifies the starting page specified by the user. This value is valid only if the PD_PAGENUMS flag is specified.

nToPage

Specifies the initial value for the ending page edit control. When the PrintDlg function returns, nToPage specifies the ending page specified by the user. This value is valid only if the PD_PAGENUMS flag is specified.

nMinPage

Specifies the minimum value for the range of pages specified in the From and To page edit controls.

nMaxPage

Specifies the maximum value for the range of pages specified in the From and To page edit controls.

nCopies

Contains the initial number of copies for the Copies edit control if hDevMode is NULL; otherwise, the dmCopies member of the DEVMODE structure contains the initial value. When PrintDlg returns, this member contains the actual number of copies to print. If the printer driver does not support multiple copies, this value may be greater than one and the application must print all requested copies. If the PD_USEDEVMODECOPIESANDCOLLATE value is set in the Flags member, nCopies is always set to 1 on return and the dmCopies member in the DEVMODE receives the actual number of copies to print.

hInstance

If the PD_ENABLEPRINTTEMPLATE or PD_ENABLESETUPTEMPLATE flag is set in the Flags member, hInstance is the handle of the application or module instance that contains the dialog box template named by the lpPrintTemplateName or lpSetupTemplateName member.

lCustData

Specifies application-defined data that the system passes to the hook procedure identified by the lpfnPrintHook or lpfnSetupHook member. When the system sends the WM_INITDIALOG message to the hook procedure, the message’s lParam parameter is a pointer to the PRINTDLG structure specified when the dialog was created. The hook procedure can use this pointer to get the lCustData value.

lpfnPrintHook

Pointer to a PrintHookProc hook procedure that can process messages intended for the Print dialog box. This member is ignored unless the PD_ENABLEPRINTHOOK flag is set in the Flags member.

lpfnSetupHook

Pointer to a SetupHookProc hook procedure that can process messages intended for the Print Setup dialog box. This member is ignored unless the PD_ENABLESETUPHOOK flag is set in the Flags member.

lpPrintTemplateName

Pointer to a null-terminated string that names a dialog box template resource in the module identified by the hInstance member. This template is substituted for the standard Print dialog box template. This member is ignored unless the PD_ENABLEPRINTTEMPLATE flag is set in the Flags member.

lpSetupTemplateName

Pointer to a null-terminated string that names a dialog box template resource in the module identified by the hInstance member. This template is substituted for the standard Print Setup dialog box template. This member is ignored unless the PD_ENABLESETUPTEMPLATE flag is set in the Flags member.

hPrintTemplate

If the PD_ENABLEPRINTTEMPLATEHANDLE flag is set in the Flags member, hPrintTemplate is the handle of a memory object containing a dialog box template. This template is substituted for the standard Print dialog box template.

hSetupTemplate

If the PD_ENABLESETUPTEMPLATEHANDLE flag is set in the Flags member, hSetupTemplate is the handle of a memory object containing a dialog box template. This template is substituted for the standard Print Setup dialog box template.

Remarks

There might be data collision between the values specified by hDevNames and hDevMode because the wDeviceOffset member of the DEVNAMES structure is supposed to be identical to the dmDeviceName member of the DEVMODE structure. If it is not, the system resolves the data collision by using the value of wDeviceOffset.

If the user checks the Collate check box in the common Print dialog box, but the printer driver does not support collation, the Flags member of the PRINTDLG structure returned by PrintDlg includes the PD_COLLATE flag. In addition, the dmCollate member of the DEVMODE structure identified by the hDevMode member is set to COLLATE_TRUE. If the PD_COLLATE flag is set, the application must simulate collation.

If the PD_USEDEVMODECOPIESANDCOLLATE flag is set, the Collate check box is grayed out if the printer driver does not support collation. This ensures that the user can only select one copy, and nCopies will be one. If the driver does support multiple copies, dmCopies will contain the number of copies, and nCopies will be one.

On entry to PrintDlg, the nCopies member of the PRINTDLG structure specifies the number of copies if PD_USEDEVMODECOPIESANDCOLLATE is not set. On exit from PrintDlg, nCopies contains the number of copies if the printer driver does not support multiple copies. Otherwise it is set to one. If nCopies is greater than one on exit from PrintDlg, the application must print multiple copies of the document.

See Also

CreateDC, CreateIC, PrintDlg, DEVMODE, DEVNAMES, WM_INITDIALOG


PRINTER_DEFAULTS

The PRINTER_DEFAULTS structure specifies the default data type, environment, initialization data, and access rights for a printer.

typedef struct _PRINTER_DEFAULTS {  // pd

    LPTSTR      pDatatype;

    LPDEVMODE   pDevMode;

    ACCESS_MASK DesiredAccess;

} PRINTER_DEFAULTS;

Members

pDatatype

Points to a null-terminated string that specifies the default data type for a printer.

pDevMode

Points to a DEVMODE structure that identifies the default environment and initialization data for a printer.

DesiredAccess

Specifies desired access rights for a printer. The OpenPrinter function uses this member to set access rights to the printer. These rights can affect the operation of the SetPrinter and DeletePrinter functions.

This member can be set to PRINTER_ACCESS_ADMINISTER, PRINTER_ACCESS_USE, or any generic security value (for example, WRITE_DACL). If an application wishes to open a printer to perform administrative tasks, such as the SetPrinter function, it must open the printer with PRINTER_ACCESS_ADMINISTER access.

See Also

DeletePrinter, DEVMODE, OpenPrinter, SetPrinter


PRINTER_INFO_1

The PRINTER_INFO_1 structure specifies general printer information.

typedef struct _PRINTER_INFO_1 { // pri1

    DWORD  Flags;

    LPTSTR pDescription;

    LPTSTR pName;

    LPTSTR pComment;

} PRINTER_INFO_1;

Members

Flags

Specifies information about the returned data. Following are the values for this member

Value	Meaning
PRINTER_ENUM_EXPAND	A print provider can set this flag as a hint to a calling application to enumerate this object further if default expansion is enabled. For example, when domains are enumerated, a print provider might indicate the user’s domain by setting this flag.
PRINTER_ENUM_CONTAINER	If this flag is set, the printer object may contain enumerable objects. For example, the object may be a print server that contains printers.
PRINTER_ENUM_ICON1	Indicates that, where appropriate, an application should display an icon identifying the object as a top-level network name, such as Microsoft Windows Network.
PRINTER_ENUM_ICON2	Indicates that, where appropriate, an application should display an icon that identifies the object as a network domain.
PRINTER_ENUM_ICON3	Indicates that, where appropriate, an application should display an icon that identifies the object as a print server.
PRINTER_ENUM_ICON4	Reserved for future use.
PRINTER_ENUM_ICON5	Reserved for future use.
PRINTER_ENUM_ICON6	Reserved for future use.
PRINTER_ENUM_ICON7	Reserved for future use.
PRINTER_ENUM_ICON8	Indicates that, where appropriate, an application should display an icon that identifies the object as a printer.
pDescription

Windows NT: Points to a null-terminated string that describes the contents of the structure.

Windows 95: Points to a null-terminated string that describes the printer. The string contains the pPrinterName, pDriverName, and pComment members of the PRINTER_INFO_2 structure concatenated and separated by commas.

pName

Windows NT: Points to a null-terminated string that names the contents of the structure.

Windows 95: Points to a null-terminated string that specifies the name of the printer.

pComment

Windows NT: Points to a null-terminated string that contains additional data describing the structure.

Windows 95: Points to a null-terminated string that provides a brief description of the printer.

See Also

GetPrinter, EnumPrinters, PRINTER_INFO_2, PRINTER_INFO_3, PRINTER_INFO_4


PRINTER_INFO_2

The PRINTER_INFO_2 structure specifies detailed printer information.

typedef struct _PRINTER_INFO_2 { // pri2

    LPTSTR    pServerName;

    LPTSTR    pPrinterName;

    LPTSTR    pShareName;

    LPTSTR    pPortName;

    LPTSTR    pDriverName;

    LPTSTR    pComment;

    LPTSTR    pLocation;

    LPDEVMODE pDevMode;

    LPTSTR    pSepFile;

    LPTSTR    pPrintProcessor;

    LPTSTR    pDatatype;

    LPTSTR    pParameters;

    PSECURITY_DESCRIPTOR pSecurityDescriptor;

    DWORD     Attributes;

    DWORD     Priority;

    DWORD     DefaultPriority;

    DWORD     StartTime;

    DWORD     UntilTime;

    DWORD     Status;

    DWORD     cJobs;

    DWORD     AveragePPM;

} PRINTER_INFO_2;

Members

pServerName

Points to a null-terminated string identifying the server that controls the printer. If this string is NULL, the printer is controlled locally.

pPrinterName

Points to a null-terminated string that specifies the name of the printer.

pShareName

Points to a null-terminated string that identifies the sharepoint for the printer. (This string is used only if the PRINTER_ATTRIBUTE_SHARED constant was set for the Attributes member.)

pPortName

Points to a null-terminated string that identifies the port(s) used to transmit data to the printer. If a printer is connected to more than one port, the names of each port must be separated by commas (for example, “LPT1:,LPT2:,LPT3:”).

pDriverName

Points to a null-terminated string that specifies the name of the printer driver.

pComment

Points to a null-terminated string that provides a brief description of the printer.

pLocation

Points to a null-terminated string that specifies the physical location of the printer (for example, “Bldg. 38, Room 1164”).

pDevMode

Points to a DEVMODE structure that defines default printer data such as the paper orientation and the resolution.

pSepFile

Points to a null-terminated string that specifies the name of the file used to create the separator page. This page is used to separate print jobs sent to the printer.

pPrintProcessor

Points to a null-terminated string that specifies the name of the print processor used by the printer.

pDatatype

Points to a null-terminated string that specifies the data type used to record the print job.

pParameters

Points to a null-terminated string that specifies the default print-processor parameters.

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure for the printer. This member may be NULL.

Attributes

Specifies the printer attributes. This member can be one of the following values:

PRINTER_ATTRIBUTE_DEFAULT
PRINTER_ATTRIBUTE_DIRECT
PRINTER_ATTRIBUTE_DO_COMPLETE_FIRST
PRINTER_ATTRIBUTE_ENABLE_BIDI (Windows 95 only)
PRINTER_ATTRIBUTE_ENABLE_DEVQ
PRINTER_ATTRIBUTE_KEEPPRINTEDJOBS
PRINTER_ATTRIBUTE_QUEUED
PRINTER_ATTRIBUTE_SHARED
PRINTER_ATTRIBUTE_WORK_OFFLINE (Windows 95 only)

Priority

Specifies a priority value that the spooler uses to route print jobs.

DefaultPriority

Specifies the default priority value assigned to each print job.

StartTime

Specifies the earliest time at which the printer will print a job. This value is expressed as minutes elapsed since 12:00 A.M. GMT (Greenwich Mean Time).

UntilTime

Specifies the latest time at which the printer will print a job. This value is expressed as minutes elapsed since 12:00 A.M. GMT (Greenwich Mean Time).

Status

Specifies the printer status. This member can be one of the following values:

Windows NT:

PRINTER_STATUS_PAUSED
PRINTER_STATUS_PENDING_DELETION

Windows 95:

PRINTER_STATUS_BUSY
PRINTER_STATUS_DOOR_OPEN
PRINTER_STATUS_ERROR
PRINTER_STATUS_INITIALIZING
PRINTER_STATUS_IO_ACTIVE
PRINTER_STATUS_MANUAL_FEED
PRINTER_STATUS_NO_TONER
PRINTER_STATUS_NOT_AVAILABLE
PRINTER_STATUS_OFFLINE
PRINTER_STATUS_OUT_OF_MEMORY
PRINTER_STATUS_OUTPUT_BIN_FULL
PRINTER_STATUS_PAGE_PUNT
PRINTER_STATUS_PAPER_JAM
PRINTER_STATUS_PAPER_OUT
PRINTER_STATUS_PAPER_PROBLEM
PRINTER_STATUS_PAUSED
PRINTER_STATUS_PENDING_DELETION
PRINTER_STATUS_PRINTING
PRINTER_STATUS_PROCESSING
PRINTER_STATUS_TONER_LOW
PRINTER_STATUS_UNAVAILABLE
PRINTER_STATUS_USER_INTERVENTION
PRINTER_STATUS_WAITING
PRINTER_STATUS_WARMING_UP

cJobs

Specifies the number of print jobs that have been queued for the printer.

AveragePPM

Specifies the average number of pages per minute that have been printed on the printer.

Remarks

Windows 95: The PRINTER_STATUS_PAGE_PUNT value specifies that the page is being “punted” (that is, not printed) because it is too complex for the printer to print.

See Also

DEVMODE, EnumPrinters, PRINTER_INFO_1, PRINTER_INFO_3, PRINTER_INFO_4, SECURITY_DESCRIPTOR


PRINTER_INFO_3

The PRINTER_INFO_3 structure specifies printer security information.

typedef struct _PRINTER_INFO_3 { // pri3

    PSECURITY_DESCRIPTOR pSecurityDescriptor;

} PRINTER_INFO_3;

Members

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure that specifies a printer’s security information.

Remarks

The PRINTER_INFO_3 structure lets an application get and set a printer’s security descriptor. The caller may do so even if it lacks specific printer permissions, as long as it has the standard rights described in SetPrinter and GetPrinter. Thus, an application may temporarily deny all access to a printer, while allowing the owner of the printer to have access to the printer’s discretionary ACL.

See Also

SetPrinter, GetPrinter, PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4, SECURITY_DESCRIPTOR


PRINTER_INFO_4

The PRINTER_INFO_4 structure specifies general printer information.

The structure can be used to retrieve minimal printer information on a call to EnumPrinters. Such a call is a fast and easy way to retrieve the names and attributes of all locally installed printers on a system and all remote printer connections that a user has established.

typedef struct _PRINTER_INFO_4 { // pri4

    LPTSTR  pPrinterName;

    LPTSTR  pServerName;

    DWORD  Attributes;

} PRINTER_INFO_4;

Members

pPrinterName

Points to a null-terminated string that specifies the name of the printer (local or remote).

pServerName

Points to a null-terminated string that is the name of the server.

Attributes

Specifies information about the returned data.

Value	Meaning
PRINTER_ATTRIBUTE_LOCAL	The printer is a local printer.
PRINTER_ATTRIBUTE_NETWORK	The printer is a remote printer.
Remarks

The PRINTER_INFO_4 structure provides an easy and extremely fast way to retrieve the names of the printers installed on a local machine, as well as the remote connections that a user has established. When EnumPrinters is called with a PRINTER_INFO_4 data structure, that function queries the registry for the specified information, then returns immediately. This differs from the behavior of EnumPrinters when called with other levels of PRINTER_INFO_xxx data structures. In particular, when EnumPrinters is called with a level 2 (PRINTER_INFO_2) data structure, it performs an OpenPrinter call on each remote connection. If a remote connection is down, if the remote server no longer exists, or if the remote printer no longer exists, the function must wait for RPC to time out and consequently fail the OpenPrinter call. This can take a while. Passing a PRINTER_INFO_4 structure lets an application retrieve a bare minimium of required information; if more detailed information is desired, a subsequent EnumPrinter level 2 call can be made.

See Also

GetPrinter, EnumPrinters, OpenPrinter, PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_3


PRINTER_INFO_5 [Now Supported on Windows NT]
PRINTER_INFO_5

[Now Supported on Windows NT]

The PRINTER_INFO_5 structure specifies detailed printer information.

typedef struct _PRINTER_INFO_5 { // pri5

    LPTSTR    pPrinterName;

    LPTSTR    pPortName;

    DWORD     Attributes;

    DWORD     DeviceNotSelectedTimeout;

    DWORD     TransmissionRetryTimeout;

} PRINTER_INFO_5;

Members

pPrinterName

Pointer to a null-terminated string that specifies the name of the printer.

pPortName

Pointer to a null-terminated string that identifies the port(s) used to transmit data to the printer. If a printer is connected to more than one port, the names of each port must be separated by commas (for example, “LPT1:,LPT2:,LPT3:”).

Attributes

Specifies the printer attributes. This member can be one of the following values:

PRINTER_ATTRIBUTE_QUEUED
PRINTER_ATTRIBUTE_DIRECT
PRINTER_ATTRIBUTE_DEFAULT
PRINTER_ATTRIBUTE_SHARED
PRINTER_ATTRIBUTE_WORK_OFFLINE

DeviceNotSelectedTimeout

Windows 95: Specifies the maximum time, in milliseconds, allowed to elapse between attempts to select a device.

Windows NT: This value is not used.

TransmissionRetryTimeout

Windows 95: Specifies the maximum time, in milliseconds, allowed to elapse between transmission retries.

Windows NT: This value is not used.

See Also

EnumPrinters, GetPrinter, SetPrinter, PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_3, PRINTER_INFO_4


PRINTER_INFO_6 [New - Windows NT]
PRINTER_INFO_6

[New - Windows NT]

The PRINTER_INFO_6 specifies the status value of a printer.

typedef struct _PRINTER_INFO_6 { // pri6

    DWORD     dwStatus;

} PRINTER_INFO_6;

Members

dwStatus

Specifies the printer status. This member can be one of the following values:

Value	Meaning
PRINTER_STATUS_BUSY	The printer is busy.
PRINTER_STATUS_DOOR_OPEN	The printer door is open.
PRINTER_STATUS_ERROR	The printer is in an error state.
PRINTER_STATUS_INITIALIZING	The printer is initializing.
PRINTER_STATUS_IO_ACTIVE	The printer is in an active input/output state
PRINTER_STATUS_MANUAL_FEED	The printer is in a manual feed state.
PRINTER_STATUS_NO_TONER	The printer is out of toner.
PRINTER_STATUS_NOT_AVAILABLE	The printer is not available for printing.
PRINTER_STATUS_OFFLINE	The printer is offline.
PRINTER_STATUS_OUT_OF_MEMORY	The printer has run out of memory.
PRINTER_STATUS_OUTPUT_BIN_FULL	The printer's output bin is full.
PRINTER_STATUS_PAGE_PUNT	The printer cannot print the current page.
PRINTER_STATUS_PAPER_JAM	Paper is jammed in the printer
PRINTER_STATUS_PAPER_OUT	The printer is out of paper.
PRINTER_STATUS_PAPER_PROBLEM	The printer has a paper problem.
PRINTER_STATUS_PAUSED	The printer is paused.
PRINTER_STATUS_PENDING_DELETION	The printer is deleting a print job.
PRINTER_STATUS_PRINTING	The printer is printing.
PRINTER_STATUS_PROCESSING	The printer is processing a print job.
PRINTER_STATUS_TONER_LOW	The printer is low on toner.
PRINTER_STATUS_UNAVAILABLE	The printer is not available for printing.
PRINTER_STATUS_USER_INTERVENTION	The user needs to do something to the printer.
PRINTER_STATUS_WAITING	The printer is waiting.
PRINTER_STATUS_WARMING_UP	The printer is warming up.
See Also

SetPrinter, PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_3, PRINTER_INFO_4, PRINTER_INFO_5


PRINTER_NOTIFY_INFO

The PRINTER_NOTIFY_INFO structure contains printer information returned by the FindNextPrinterChangeNotification function. The function returns this information after a wait operation on a printer change notification object has been satisfied.

typedef struct _PRINTER_NOTIFY_INFO {

    DWORD  Version;

    DWORD  Flags;

    DWORD  Count;

    PRINTER_NOTIFY_INFO_DATA  aData[1];

} PRINTER_NOTIFY_INFO;

Members

Version

Specifies the version of this structure. Set this member to 2.

Flags

Contains a bit flag to indicate the state of the notification structure. If the PRINTER_NOTIFY_INFO_DISCARDED bit is set, it indicates that some notifications had to be discarded.

Count

Specifies the number of PRINTER_NOTIFY_INFO_DATA elements in the aData array.

aData

An array of PRINTER_NOTIFY_INFO_DATA structures. Each element of the array identifies a single job or printer information field, and provides the current data for that field.

Remarks

If the Flags member has the PRINTER_NOTIFY_INFO_DISCARDED bit set, this indicates that an overflow or error occured, and notifications may have been lost. In this case, you must call FindNextPrinterChangeNotification and specify the PRINTER_NOTIFY_OPTIONS_REFRESH flag to retrieve all current information. Until you request this refresh operation, the system will not send additional notifications for this change notification object.

See Also

FindNextPrinterChangeNotification, PRINTER_NOTIFY_INFO_DATA


PRINTER_NOTIFY_INFO_DATA

The PRINTER_NOTIFY_INFO_DATA structure identifies a job or printer information field and provides the current data for that field.

The FindNextPrinterChangeNotification function returns a PRINTER_NOTIFY_INFO structure, which contains an array of PRINTER_NOTIFY_INFO_DATA structures.

typedef struct _PRINTER_NOTIFY_INFO_DATA {

    WORD   Type;

    WORD   Field;

    DWORD  Reserved;

    DWORD  Id;

    union {

        DWORD  adwData[2];

        struct {

            DWORD  cbBuf;

            LPVOID pBuf;

        } Data;

    } NotifyData;

} PRINTER_NOTIFY_INFO_DATA;

Members

Type

Indicates the type of information provided. This member can be one of the following values:

Value	Meaning
PRINTER_NOTIFY_TYPE	Indicates that the Field member specifies a PRINTER_NOTIFY_FIELD_* constant.
JOB_NOTIFY_TYPE	Indicates that the Field member specifies a JOB_NOTIFY_FIELD_* constant.
Field

Indicates the field that changed. For a list of possible values, see the following Remarks section.

Reserved

Reserved.

Id

Indicates the job identifier if the Type member specifies JOB_NOTIFY_TYPE. If the Type member specfies PRINTER_NOTIFY_TYPE, this member is undefined.

NotifyData

A union of data information based on the Type and Field members. For a description of the type of data associated with each field, see the following Remarks section.

The NotifyData union can be one of the following members:

Member	Meaning
adwData	An array of two DWORD values. For information fields that use only a single DWORD, the data is in adwData[0]
Data	The following members are contained in the Data structure:
Member	Meaning
cbBuf	Indicates the size, in bytes, of the buffer pointed to by pBuf.
pBuf	Points to a buffer that contains the field’s current data.
Remarks

If the Type member specifies PRINTER_NOTIFY_TYPE, the Field member can be one of the following values:

Field	Type of data
PRINTER_NOTIFY_FIELD_PRINTER_NAME
	pBuf points to a null-terminated string containing the name of the printer.
PRINTER_NOTIFY_FIELD_SHARE_NAME
	pBuf points to a null-terminated string that identifies the sharepoint for the printer.
PRINTER_NOTIFY_FIELD_DRIVER_NAME
	pBuf points to a null-terminated string containing the name of the printer’s driver.
PRINTER_NOTIFY_FIELD_COMMENT
	pBuf points to a null-terminated string containing the new comment string, which is typically a brief description of the printer.
PRINTER_NOTIFY_FIELD_LOCATION
	pBuf points to a null-terminated string containing the new physical location of the printer (for example, “Bldg. 38, Room 1164”).
PRINTER_NOTIFY_FIELD_DEVMODE
	pBuf points to a DEVMODE structure that defines default printer data such as the paper orientation and the resolution.
PRINTER_NOTIFY_FIELD_SEPFILE
	pBuf points to a null-terminated string that specifies the name of the file used to create the separator page. This page is used to separate print jobs sent to the printer.
PRINTER_NOTIFY_FIELD_PRINT_PROCESSOR
	pBuf points to a null-terminated string that specifies the name of the print processor used by the printer.
PRINTER_NOTIFY_FIELD_PARAMETERS
	pBuf points to a null-terminated string that specifies the default print-processor parameters.
PRINTER_NOTIFY_FIELD_DATATYPE
	pBuf points to a null-terminated string that specifies the data type used to record the print job.
PRINTER_NOTIFY_FIELD_SECURITY_DESCRIPTOR
	pBuf points to a SECURITY_DESCRIPTOR structure for the printer. The pointer may be NULL if there is no security descriptor.
PRINTER_NOTIFY_FIELD_ATTRIBUTES
	adwData[0] specifies the printer attributes, which can be one of the following values:  PRINTER_ATTRIBUTE_QUEUED PRINTER_ATTRIBUTE_DIRECT PRINTER_ATTRIBUTE_DEFAULT PRINTER_ATTRIBUTE_SHARED
PRINTER_NOTIFY_FIELD_PRIORITY
	adwData[0] specifies a priority value that the spooler uses to route print jobs.
PRINTER_NOTIFY_FIELD_DEFAULT_PRIORITY
	adwData[0] specifies the default priority value assigned to each print job.
PRINTER_NOTIFY_FIELD_START_TIME
	adwData[0] specifies the earliest time at which the printer will print a job. (This value is specified in minutes elapsed since 12:00 A.M.)
PRINTER_NOTIFY_FIELD_UNTIL_TIME
	adwData[0] specifies the latest time at which the printer will print a job. (This value is specified in minutes elapsed since 12:00 A.M.)
PRINTER_NOTIFY_FIELD_STATUS
	adwData[0] specifies the printer status. For a list of possible values, see the PRINTER_INFO_2 structure.
PRINTER_NOTIFY_FIELD_CJOBS
	adwData[0] specifies the number of print jobs that have been queued for the printer.
PRINTER_NOTIFY_FIELD_AVERAGE_PPM
	adwData[0] specifies the average number of pages per minute that have been printed on the printer.
If the Type member specifies JOB_NOTIFY_TYPE, the Field member can be one of the following values:

Field	Type of data
JOB_NOTIFY_FIELD_PRINTER_NAME
	pBuf points to a null-terminated string containing the name of the printer for which the job is spooled.
JOB_NOTIFY_FIELD_MACHINE_NAME
	pBuf points to a null-terminated string that specifies the name of the machine that created the print job.
JOB_NOTIFY_FIELD_PORT_NAME
	pBuf points to a null-terminated string that identifies the port(s) used to transmit data to the printer. If a printer is connected to more than one port, the names of the ports are separated by commas (for example, “LPT1:,LPT2:,LPT3:”).
JOB_NOTIFY_FIELD_USER_NAME
	pBuf points to a null-terminated string that specifies the name of the user who sent the print job.
JOB_NOTIFY_FIELD_NOTIFY_NAME
	pBuf points to a null-terminated string that specifies the name of the user who should be notified when the job has been printed or when an error occurs while printing the job.
JOB_NOTIFY_FIELD_DATATYPE
	pBuf points to a null-terminated string that specifies the type of data used to record the print job.
JOB_NOTIFY_FIELD_PRINT_PROCESSOR
	pBuf points to a null-terminated string that specifies the name of the print processor to be used to print the job.
JOB_NOTIFY_FIELD_PARAMETERS
	pBuf points to a null-terminated string that specifies print-processor parameters.
JOB_NOTIFY_FIELD_DRIVER_NAME
	pBuf points to a null-terminated string that specifies the name of the printer driver that should be used to process the print job.
JOB_NOTIFY_FIELD_DEVMODE
	pBuf points to a DEVMODE structure that contains device-initialization and environment data for the printer driver.
JOB_NOTIFY_FIELD_STATUS
	adwData[0] specifies the job status. For a list of possible values, see the JOB_INFO_2 structure.
JOB_NOTIFY_FIELD_STATUS_STRING
	pBuf points to a null-terminated string that specifies the status of the print job.
JOB_NOTIFY_FIELD_DOCUMENT
	pBuf points to a null-terminated string that specifies the name of the print job (for example, “MS-WORD: Review.doc”).
JOB_NOTIFY_FIELD_PRIORITY
	adwData[0] specifies the job priority.
JOB_NOTIFY_FIELD_POSITION
	adwData[0] specifies the job’s position in the print queue.
JOB_NOTIFY_FIELD_SUBMITTED
	pBuf points to a SYSTEMTIME structure that specifies the time when the job was submitted.
JOB_NOTIFY_FIELD_START_TIME
	adwData[0] specifies the earliest time that the job can be printed. (This value is specified in minutes elapsed since 12:00 A.M.)
JOB_NOTIFY_FIELD_UNTIL_TIME
	adwData[0] specifies the the latest time that the job can be printed. (This value is specified in minutes elapsed since 12:00 A.M.)
JOB_NOTIFY_FIELD_TIME
	adwData[0] specifies the total time, in seconds, that has elapsed since the job began printing.
JOB_NOTIFY_FIELD_TOTAL_PAGES
	adwData[0] specifies the size, in pages, of the job.
JOB_NOTIFY_FIELD_PAGES_PRINTED
	adwData[0] specifies the number of pages that have printed.
JOB_NOTIFY_FIELD_TOTAL_BYTES
	adwData[0] specifies the size, in bytes, of the job.
JOB_NOTIFY_FIELD_BYTES_PRINTED
	adwData[0] specifies the number of bytes that have been printed on this job. For this field, the change notification object is signaled when bytes are sent to the printer.
See Also

DEVMODE, FindNextPrinterChangeNotification, JOB_INFO_2, PRINTER_INFO_2, PRINTER_NOTIFY_INFO, SECURITY_DESCRIPTOR, SYSTEMTIME


PRINTER_NOTIFY_OPTIONS

The PRINTER_NOTIFY_OPTIONS structure specifies options for a change notification object that monitors a printer or print server.

typedef struct _PRINTER_NOTIFY_OPTIONS {

    DWORD  Version;

    DWORD  Flags;

    DWORD  Count;

    PPRINTER_NOTIFY_OPTIONS_TYPE  pTypes;

} PRINTER_NOTIFY_OPTIONS;

Members

Version

Specifies the version of this structure. Set this member to 2.

Flags

Contains a bit flag. If you set the PRINTER_NOTIFY_OPTIONS_REFRESH flag in a call to the FindNextPrinterChangeNotification function, the function provides current data for all monitored printer information fields. The FindFirstPrinterChangeNotification function ignores the Flags member.

Count

Specifies the number of elements in the pTypes array.

pTypes

Points to an array of PRINTER_NOTIFY_OPTIONS_TYPE structures. Use one element of this array to specify the printer information fields to monitor, and one element to specify the job information fields to monitor. You can monitor either printer information, job information, or both.

Remarks

Use this structure with the FindFirstPrinterChangeNotification function to specify the set of printer or job information fields to monitor for change.

Use this structure with the FindNextPrinterChangeNotification function to request the current data for all monitored printer and job information fields. In this case, the Flags member specifies the PRINTER_NOTIFY_OPTIONS_REFRESH flag, and the function ignores the other structure members.

See Also

FindFirstPrinterChangeNotification, FindNextPrinterChangeNotification, PRINTER_NOTIFY_OPTIONS_TYPE


PRINTER_NOTIFY_OPTIONS_TYPE

The PRINTER_NOTIFY_OPTIONS_TYPE structure specifies the set of printer or job information fields to be monitored by a printer change notification object.

A call to the FindFirstPrinterChangeNotification function specifies a PRINTER_NOTIFY_OPTIONS structure, which contains an array of PRINTER_NOTIFY_OPTIONS_TYPE structures.

typedef struct _PRINTER_NOTIFY_OPTIONS_TYPE {

    WORD   Type;

    WORD   Reserved0;

    DWORD  Reserved1;

    DWORD  Reserved2;

    DWORD  Count;

    PWORD  pFields;

} PRINTER_NOTIFY_OPTIONS_TYPE;

Members

Type

Specifies the type to watch. This member can be one of the following values:

Value	Meaning
PRINTER_NOTIFY_TYPE	Indicates that the fields specified in the pFields array are PRINTER_NOTIFY_FIELD_* constants.
JOB_NOTIFY_TYPE	Indicates that the fields specified in the pFields array are JOB_NOTIFY_FIELD_* constants.
Reserved0

Reserved.

Reserved1

Reserved.

Reserved2

Reserved.

Count

Specifies the number of elements in the pFields array.

pFields

Points to an array of 16-bit values. Each element of the array specifies a job or printer information field of interest. For a list of supported printer and job information fields, see the PRINTER_NOTIFY_INFO_DATA structure.

See Also

FindFirstPrinterChangeNotification, PRINTER_NOTIFY_INFO_DATA, PRINTER_NOTIFY_OPTIONS


PRINTPROCESSOR_INFO_1

The PRINTPROCESSOR_INFO_1 structure specifies the name of an installed print processor.

typedef struct _PRINTPROCESSOR_INFO_1 { // ppi1

    LPTSTR pName;

} PRINTPROCESSOR_INFO_1;

Members

pName

Points to a null-terminated string that specifies the name of an installed print processor.

See Also

EnumPrintProcessors


PRIVILEGE_SET

The PRIVILEGE_SET structure specifies a set of privileges. It is also used to indicate which, if any, privileges are held by a user or group requesting access to an object.

typedef struct _PRIVILEGE_SET { // ps

    DWORD PrivilegeCount;

    DWORD Control;

    LUID_AND_ATTRIBUTES Privilege[ANYSIZE_ARRAY];

} PRIVILEGE_SET;

Members

PrivilegeCount

Specifies the number of privileges in the privilege set.

Control

Specifies a control flag related to the privileges. The PRIVILEGE_SET_ALL_NECESSARY control flag is currently defined. It indicates that all of the specified privileges must be held by the process requesting access. If this flag is not set, the presence of any privileges in the user’s access token grants the access.

Privilege

Specifies an array of LUID_AND_ATTRIBUTES structures describing the set’s privileges. The following attributes are defined for privileges:

Attribute	Description
SE_PRIVILEGE_ENABLED_BY_DEFAULT
	The privilege is enabled by default.
SE_PRIVILEGE_ENABLED
	The privilege is enabled.
SE_PRIVILEGE_USED_FOR_ACCESS
	The privilege was used to gain access to an object or service. This flag is used to identify the relevant privileges in a set passed by a client application that may contain unnecessary privileges.
Remarks

A privilege is used to control access to an object or service more strictly than is typical with discretionary access control. A system manager uses privileges to control which users are able to manipulate system resources. An application uses privileges when it changes a system-wide resource, such as when it changes the system time or shuts down the system.

See Also

PrivilegeCheck, LUID, LUID_AND_ATTRIBUTES


PROCESS_HEAP_ENTRY

The PROCESS_HEAP_ENTRY structure contains information about a heap element. The HeapWalk function uses a PROCESS_HEAP_ENTRY structure to enumerate the elements of a heap.

typedef struct _PROCESS_HEAP_ENTRY {

    PVOID lpData;

    DWORD cbData;

    BYTE cbOverhead;

    BYTE iRegionIndex;

    WORD wFlags;

    union {

        struct {

            HANDLE hMem;

            DWORD dwReserved[ 3 ];

        } Block;

        struct {

            DWORD dwCommittedSize;

            DWORD dwUnCommittedSize;

            LPVOID lpFirstBlock;

            LPVOID lpLastBlock;

        } Region;

    };

} PROCESS_HEAP_ENTRY;

Members

lpData

Points to the data portion of the heap element.

To initiate a HeapWalk heap enumeration, set lpData to NULL.

If the PROCESS_HEAP_REGION bit flag is set in the wFlags member, lpData points to the first virtual address used by the region.

If the PROCESS_HEAP_UNCOMMITTED_RANGE bit flag is set in wFlags, lpData points to the beginning of the range of uncommitted memory.

cbData

Specifies the size, in bytes, of the data portion of the heap element.

If the PROCESS_HEAP_REGION bit flag is set in wFlags, cbData specifies the total size, in bytes, of the address space that is reserved for this region.

If the PROCESS_HEAP_UNCOMMITTED_RANGE bit flag is set in wFlags, cbData specifies the size, in bytes, of the range of uncommitted memory.

cbOverhead

Specifies the size, in bytes, of the data used by the system to maintain information about the heap element. These overhead bytes are in addition to the cbData bytes of the data portion of the heap element.

If the PROCESS_HEAP_REGION bit flag is set in wFlags, cbOverhead specifies the size, in bytes, of the heap control structures that describe the region.

If the PROCESS_HEAP_UNCOMMITTED_RANGE bit flag is set in wFlags, cbOverhead specifies the size, in bytes, of the control structures that describe this uncommitted range.

iRegionIndex

Identifies the heap region that contains the heap element. A heap consists of one or more regions of virtual memory, each with a unique region index.

In the first heap entry returned for most heap regions, HeapWalk sets the PROCESS_HEAP_REGION flag in the wFlags member. When this flag is set, the members of the Region structure contain additional information about the region.

The HeapAlloc function sometimes uses the VirtualAlloc function to allocate large blocks from a growable heap. The heap manager treats such a large block allocation as a separate region with a unique region index. HeapWalk does not set the PROCESS_HEAP_REGION flag in the heap entry returned for a large block region, so the members of the Region structure are not valid. You can use the VirtualQuery function to get additional information about a large block region.

wFlags

A set of bit flags that specify properties of the heap element. Some of these flags affect the meaning of other members of this PROCESS_HEAP_ENTRY data structure. The following bit-flag constants are defined:

Value	Meaning
PROCESS_HEAP_REGION	If this flag is set, the heap element is located at the beginning of a region of contiguous virtual memory in use by the heap.  If this flag is set, the lpData member of the structure points to the first virtual address used by the region; the cbData member specifies the total size, in bytes, of the address space that is reserved for this region; and the cbOverhead member specifies the size, in bytes, of the heap control structures that describe the region. If this flag is set, the Region structure becomes valid. The dwCommittedSize, dwUnCommittedSize, lpFirstBlock, and lpLastBlock members of the structure contain additional information about the region.
PROCESS_HEAP_UNCOMMITTED_RANGE	If this flag is set, the heap element is located in a range of uncommitted memory within the heap region.  If this flag is set, the lpData member points to the beginning of the range of uncommitted memory; the cbData member specifies the size, in bytes, of the range of uncommitted memory; and the cbOverhead member specifies the size, in bytes, of the control structures that describe this uncommitted range.
PROCESS_HEAP_ENTRY_BUSY	If this flag is set, the heap element is an allocated block.  If both this flag and the PROCESS_HEAP_ENTRY_MOVEABLE flag are set, the Block structure becomes valid. The hMem member of the Block structure contains a handle to the allocated, moveable memory block.
PROCESS_HEAP_ENTRY_MOVEABLE	This flag is only valid if the PROCESS_HEAP_ENTRY_BUSY flag is set, indicating that the heap element is an allocated block. If this flag is valid and set, the block was allocated with the LMEM_MOVEABLE or GMEM_MOVEABLE flag, and the Block structure becomes valid. The hMem member of the Block structure contains a handle to the allocated, moveable memory block.
PROCESS_HEAP_ENTRY_DDESHARE	This flag is only valid if the PROCESS_HEAP_ENTRY_BUSY flag is set, indicating that the heap element is an allocated block. If this flag is valid and set, the block was allocated with the GMEM_DDESHARE flag. For a discussion of the GMEM_DDESHARE flag, see GlobalAlloc .
Block

This structure is valid only if both the PROCESS_HEAP_ENTRY_BUSY and PROCESS_HEAP_ENTRY_MOVEABLE flags in wFlags are set.

The members of the Block structure are as follows:

Member	Description
hMem	Contains a handle to the allocated, moveable memory block.
dwReserved	Reserved; not used.
Region

This structure is valid only if the PROCESS_HEAP_REGION flag is set in the wFlags member.

The members of the Region structure are as follows:

Member	Description
dwCommittedSize	Specifies the number of bytes in the heap region that are currently committed as free memory blocks, busy memory blocks, or heap control structures. This is an optional field that is set to zero if the number of committed bytes is not available.
dwUnCommittedSize	Specifies the number of bytes in the heap region that are currently uncommitted. This is an optional field that is set to zero if the number of uncommitted bytes is not available.
lpFirstBlock	Pointer to the first valid memory block in this heap region.
lpLastBlock	Pointer to the first invalid memory block in thisheap region.
See Also

GlobalAlloc, HeapAlloc, HeapWalk, VirtualAlloc, VirtualQuery


PROCESS_INFORMATION

The PROCESS_INFORMATION structure is filled in by the CreateProcess function with information about a newly created process and its primary thread.

typedef struct _PROCESS_INFORMATION { // pi

    HANDLE hProcess;

    HANDLE hThread;

    DWORD dwProcessId;

    DWORD dwThreadId;

} PROCESS_INFORMATION;

Members

hProcess

Returns a handle to the newly created process. The handle is used to specify the process in all functions that perform operations on the process object.

hThread

Returns a handle to the primary thread of the newly created process. The handle is used to specify the thread in all functions that perform operations on the thread object.

dwProcessId

Returns a global process identifier that can be used to identify a process. The value is valid from the time the process is created until the time the process is terminated.

dwThreadId

Returns a global thread identifiers that can be used to identify a thread. The value is valid from the time the thread is created until the time the thread is terminated.

See Also

CreateProcess


PROPSHEETHEADER

The PROPSHEETHEADER structure defines the frame and pages of a property sheet.

typedef struct _PROPSHEETHEADER { // psh

    DWORD      dwSize;

    DWORD      dwFlags;

    HWND       hwndParent;

    HINSTANCE  hInstance;

    union {

        HICON  hIcon;

        LPCTSTR pszIcon;

    };

    LPCTSTR     pszCaption;

    UINT       nPages

    union {

        UINT  nStartPage

        LPCTSTR pStartPage;

    };

    union {

        LPCPROPSHEETPAGE    ppsp;

        HPROPSHEETPAGE FAR *phpage;

    };

    PFNPROPSHEETCALLBACK pfnCallback;

} PROPSHEETHEADER, FAR *LPPROPSHEETHEADER;

typedef const PROPSHEETHEADER FAR *LPCPROPSHEETHEADER;

Members

dwSize

Size, in bytes, of this structure.

dwFlags

Array of flags that indicate which other members to use and which to ignore. This member can be a combination of the following values:

Value	Meaning
PSH_DEFAULT	Uses the default meaning for all structure members.
PSH_HASHELP	Displays the property sheet Help button. The Help button is enabled only when the PSP_HASHELP flag is set in the PROPSHEETPAGE structure for the active page.  If any of the initial property sheet pages sets the PSP_HASHELP flag, the Help button is automatically displayed regardless of the PSH_HASHELP flag. However, PSH_HASHELP is useful when none of the initial pages set PSP_HASHELP, but pages added later might.
PSH_MODELESS	Causes the PropertySheet function to create the property sheet as a modeless dialog instead of the default modal behavior. When this flag is set, PropertySheet returns immediately after the dialog is created and the return value from PropertySheet is the window handle of the property sheet dialog.
PSH_NOAPPLYNOW	Removes the Apply Now button.
PSH_PROPSHEETPAGE	Uses ppsp and ignores phpage when creating the pages for the property sheet.
PSH_PROPTITLE	Includes “Properties for” with the string specified by pszCaption in the title bar of the property sheet.
PSH_USECALLBACK	Calls the function specified by pfnCallback when initializing the property sheet defined by this structure.
PSH_USEHICON	Uses hIcon as the small icon in the title bar of the property sheet dialog box.
PSH_USEICONID	Uses pszIcon as the name of the icon resource to load and use as the small icon in the title bar of the property sheet dialog box.
PSH_USEPSTARTPAGE	Uses pStartPage and ignores nStartPage when displaying the initial page of the property sheet.
PSH_WIZARD	Creates a wizard property sheet.
PSH_RTLREADING	Displays the title of the property sheet dialog using right-to-left reading order on Hebrew or Arabic systems.
hwndParent

Handle of the owner window.

hInstance

Handle of the instance from which to load the icon or title string resource. If pszIcon or pszCaption identifies a resource to load, this member must be specified.

hIcon

Handle of the icon to use as the small icon in the title bar of the property sheet dialog box. If dwFlags does not include the PSH_USEHICON value, this member is ignored.

pszIcon

Icon resource to use as the small icon in the title bar of the property sheet dialog box. This member can specify either the identifier of the icon resource or the pointer to the string that specifies the name of the icon resource. If dwFlags does not include the PSH_USEICONID value, this member is ignored.

pszCaption

Title of the property sheet dialog box. This member can specify either the identifier of a string resource or the pointer to a string that specifies the title. If dwFlags includes the PSH_PROPTITLE value, the string “Properties for” is used with the title.

nPages

Number of elements in the phpage array.

nStartPage

Zero-based index of the initial page that appears when the property sheet dialog box is created.

pStartPage

Name of the initial page that appears when the property sheet dialog box is created. This member can specify either the identifier of a string resource or the pointer to a string that specifies the name.

ppsp

Pointer to an array of PROPSHEETPAGE structures that define the pages in the property sheet. If dwFlags does not include the PSH_PROPSHEETPAGE value, this member is ignored.

phpage

Pointer to an array that contains handles of property sheet pages. Each handle must have been created by a previous call to the CreatePropertySheetPage function. If dwFlags includes the PSH_PROPSHEETPAGE value, this member is ignored.

pfnCallback

Pointer to an application-defined callback function that is called when the property sheet is initialized. For more information about the callback function, see the description of the PropSheetProc function. If dwFlags does not include the PSP_USECALLBACK value, this member is ignored.

See Also

CreatePropertySheetPage, PropertySheet, PROPSHEETPAGE, PropSheetProc


PROPSHEETPAGE

The PROPSHEETPAGE structure defines a page in a property sheet.

typedef struct _PROPSHEETPAGE { // psp

    DWORD     dwSize;

    DWORD     dwFlags;

    HINSTANCE hInstance;

    union {

        LPCTSTR        pszTemplate;

        LPCDLGTEMPLATE pResource;

    };

    union {

        HICON  hIcon;

        LPCTSTR pszIcon;

    };

    LPCTSTR pszTitle;

    DLGPROC pfnDlgProc;

    LPARAM  lParam;

    LPFNPSPCALLBACK pfnCallback;

    UINT FAR * pcRefParent;

} PROPSHEETPAGE, FAR *LPPROPSHEETPAGE;

typedef const PROPSHEETPAGE FAR *LPCPROPSHEETPAGE;

Members

dwSize

Size, in bytes, of the structure. The size includes any extra application-defined data at the end of the structure.

dwFlags

A set of bit flags that enable optional attributes of the property sheet page, and indicate the valid members of the PROPSHEETPAGE structure. This member can be a combination of the following values.

Value	Meaning
PSP_DEFAULT	Uses the default meaning for all structure members.
PSP_DLGINDIRECT	Creates the page from the dialog box template in memory pointed to by the pResource member. The PropertySheet function assumes that the template is in writeable memory; a read-only template will cause an exception on some versions of Windows. If this flag is not set, the page loads the dialog box template from the resource identified by the pszTemplate member.
PSP_HASHELP	Enables the property sheet Help button when this page is active.
PSP_USECALLBACK	Calls the function specified by pfnCallback when creating or destroying the property sheet page defined by this structure.
PSP_USEHICON	Uses hIcon as the small icon on the tab for the page.
PSP_USEICONID	Uses pszIcon as the name of the icon resource to load and use as the small icon on the tab for the page.
PSP_USEREFPARENT	Maintains the reference count specified by pcRefParent for the lifetime of the property sheet page created from this structure.
PSP_USETITLE	Uses pszTitle as the title of the property sheet dialog box instead of the title stored in the dialog box template.
PSP_RTLREADING	When this page is active, displays the text of pszTitle using right-to-left reading order on Hebrew or Arabic systems.
hInstance

Handle to the instance from which to load the dialog box template, icon, or title string resource.

pszTemplate

Dialog box template to use to create the page. This member can specify either the resource identifier of the template or the address of a string that specifies the name of the template. If dwFlags includes the PSP_DLGINDIRECT value, this member is ignored.

pResource

Pointer to a dialog box template in memory. The PropertySheet function assumes that the template is in writeable memory; a read-only template will cause an exception on some versions of Windows. If dwFlags does not include the PSP_DLGINDIRECT value, this member is ignored.

hIcon

Handle to the icon to use as the small icon in the tab for the page. If dwFlags does not include the PSP_USEHICON value, this member is ignored.

pszIcon

Icon resource to use as the small icon in the tab for the page. This member can specify either the identifier of the icon resource or the pointer to the string that specifies the name of the icon resource. If dwFlags does not include the PSP_USEICONID value, this member is ignored.

pszTitle

Title of the property sheet dialog box. This title overrides the title specified in the dialog box template. This member can specify either the identifier of a string resource or the pointer to a string that specifies the title. If dwFlags does not include the PSP_USETITLE value, this member is ignored.

pfnDlgProc

Pointer to the dialog box procedure for the page. The dialog box procedure must not call the EndDialog function.

lParam

Application-defined data.

pfnCallback

Pointer to an application-defined callback function that is called when the page is created and when it is about to be destroyed. For more information about the callback function, see PropSheetPageProc. If dwFlags does not include the PSP_USECALLBACK value, this member is ignored.

pcRefParent

Pointer to the reference count value. If dwFlags does not include the PSP_USERREFPARENT value, this member is ignored.

Remarks

When the PropertySheet function creates the page, the dialog box procedure for the page receives a WM_INITDIALOG message. The lParam parameter of this message points to the PROPSHEETPAGE structure used to create the page.

See Also

EndDialog, PropSheetPageProc, PropertySheet, WM_INITDIALOG


PROTOCOL_INFO

The PROTOCOL_INFO structure contains information about a protocol.

typedef  struct _PROTOCOL_INFO {

    DWORD  dwServiceFlags;

    INT  iAddressFamily;

    INT  iMaxSockAddr;

    INT  iMinSockAddr;

    INT  iSocketType;

    INT  iProtocol;

    DWORD  dwMessageSize;

    LPTSTR  lpProtocol;

} PROTOCOL_INFO;

Members

dwServiceFlags

A set of bit flags that specify the services provided by the protocol. One or more of the following bit flags may be set:

Value	Meaning
XP_CONNECTIONLESS	If this flag is set, the protocol providesconnectionless (datagram) service. If this flag is clear, the protocol provides connection-oriented data transfer.
XP_GUARANTEED_DELIVERY	If this flag is set, the protocol guarantees that all data sent will reach the intended destination. If this flag is clear, there is no such guarantee.
XP_GUARANTEED_ORDER	If this flag is set, the protocol guarantees that data will arrive in the order in which it was sent. Note that this characteristic does not guarantee delivery of the data, but guarantees only its order. If this flag is clear, the order of data sent is not guaranteed.
XP_MESSAGE_ORIENTED	If this flag is set, the protocol is message-oriented. A message-oriented protocol honors message boundaries. If this flag is clear, the protocol is stream-oriented, and the concept of message boundaries is irrelevant.
XP_PSEUDO_STREAM	If this flag is set, the protocol is a message-oriented protocol that ignores message boundaries for all receive operations.  This optional capability is useful when you do not want the protocol to frame messages. An application that requires stream-oriented characteristics can open a socket with type SOCK_STREAM for transport protocols that support this functionality, regardless of the value of iSocketType.
XP_GRACEFUL_CLOSE	If this flag is set, the protocol supports two-phase close operations, also known as “graceful” close operations. If this flag is clear, the protocol supports only abortive close operations.
XP_EXPEDITED_DATA	If this flag is set, the protocol supports expedited data, also known as “urgent data.”
XP_CONNECT_DATA	If this flag is set, the protocol supports connect data.
XP_DISCONNECT_DATA	If this flag is set, the protocol supports disconnect data.
XP_SUPPORTS_BROADCAST	If this flag is set, the protocol supports a broadcast mechanism.
XP_SUPPORTS_MULTICAST	If this flag is set, the protocol supports a multicast mechanism.
XP_BANDWIDTH_ALLOCATION	If this flag is set, the protocol supports a mechanism for allocating a guaranteed bandwidth to an application.
XP_FRAGMENTATION	If this flag isset, the protocol supports message fragmentation; physical network MTU is hidden from applications.
XP_ENCRYPTS	If this flag is set, the protocol supports data encryption.
iAddressFamily

Specifies the value to pass as the af parameter when you call the socket function to open a socket for the protocol. This address family value uniquely defines the structure of Protocol addresses, also known as SOCKADDRs, used by the protocol.

iMaxSockAddr

Specifies the maximum length of a socket address supported by the protocol.

iMinSockAddr

Specifies the minimum length of a socket address supported by the protocol.

iSocketType

Specifies the value to pass as the type parameter when you call the socket function to open a socket for the protocol.

Note that if XP_PSEUDO_STREAM is set in dwServiceFlags, the application can specify SOCK_STREAM as the type parameter to socket, regardless of the value of iSocketType.

iProtocol

Specifies the value to pass as the protocol parameter when you call the socket function to open a socket for the protocol.

dwMessageSize

Specifies the maximum message size supported by the protocol. This is the maximum size of a message that can be sent from or received by the host. For protocols that do not support message framing, the actual maximum size of a message that can be sent to a given address may be less than this value.

The following special message size values are defined:

Value	Meaning
0	The protocol is stream-oriented; the concept of message size is not relevant.
0xFFFFFFFF	The protocol is message-oriented, but there is no maximum message size.
lpProtocol

Points to a zero-terminated string that supplies a name for the protocol; for example, “SPX2.”

See Also

EnumProtocols, socket


PROVIDOR_INFO_1

The PROVIDOR_INFO_1 structure identifies a print provider.

typedef struct _PROVIDOR_INFO_1 { // pi1

    LPTSTR pName;

    LPTSTR pEnvironment ;

    LPTSTR pDLLName ;

} PROVIDOR_INFO_1;

Members

pName

Points to a null-terminated string that is the name of the print provider.

pEnvironment

Points to a null-terminated environment string specifying the environment the provider dynamic-link library (DLL) is designed to run in.

pDLLName

Points to a null-terminated string that is the name of the provider DLL.

See Also

MONITOR_INFO_2


PSHNOTIFY

The PSHNOTIFY structure contains information for the PSN_APPLY and PSN_RESET notification messages.

typedef struct _PSHNOTIFY {
    NMHDR hdr;

    LPARAM lParam;

} PSHNOTIFY, FAR *LPPSHNOTIFY;

Members

hdr

Specifies an NMHDR structure. The code member of the NMHDR structure can be one of the following notification codes that identify the message being sent: PSN_APPLY or PSN_RESET.

lParam

Close flag. TRUE if the OK or Cancel button is used to close the property sheet. FALSE if the Close button used.

See Also

PSN_APPLY, PSN_RESET


PUNCTUATION

The PUNCTUATION structure contains information about the punctuation used in a rich edit control.

typedef struct _punctuation {
    UINT   iSize;          // size of table; see below
    LPSTR  szPunctuation;  // punctuation; see below
} PUNCTUATION;

Members

iSize

Size in bytes of buffer pointed to by the szPunctuation member.

szPunctuation

Address of the buffer containing the punctuation characters.

Remarks

This structure is used only in Asian-language versions of the operating system.


QUERY_SERVICE_CONFIG

The QUERY_SERVICE_CONFIG structure is used by the QueryServiceConfig function to return configuration information about an installed service.

typedef struct _QUERY_SERVICE_CONFIG { // qsc

    DWORD dwServiceType;

    DWORD dwStartType;

    DWORD dwErrorControl;

    LPTSTR lpBinaryPathName;

    LPTSTR lpLoadOrderGroup;

    DWORD dwTagId;

    LPTSTR lpDependencies;

    LPTSTR lpServiceStartName;

    LPTSTR lpDisplayName;

} QUERY_SERVICE_CONFIG, LPQUERY_SERVICE_CONFIG;

Members

dwServiceType

The value returned includes one of the following service type flags to indicate the type of service. In addition, for a SERVICE_WIN32 service, the SERVICE_INTERACTIVE_PROCESS flag might be set, indicating that the service process can interact with the desktop.

Value	Meaning
SERVICE_WIN32_OWN_PROCESS	A service type flag that indicates a Win32 service that runs in its own process.
SERVICE_WIN32_SHARE_PROCESS	A service type flag that indicates a Win32 service that shares a process with other services.
SERVICE_KERNEL_DRIVER	A service type flag that indicates a Windows NT device driver.
SERVICE_FILE_SYSTEM_DRIVER	A service type flag that indicates a Windows NT file system driver.
SERVICE_INTERACTIVE_PROCESS	A flag that indicates a Win32 service process that can interact with the desktop.
dwStartType

Specifies when to start the service. One of the following values is specified:

Value	Meaning
SERVICE_BOOT_START	Specifies a device driver started by the operating system loader. This value is valid only if the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_SYSTEM_START	Specifies a device driver started by the IoInitSystem function. This value is valid only if the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_AUTO_START	Specifies a device driver or Win32 service started by the service control manager automatically during system startup.
SERVICE_DEMAND_START	Specifies a device driver or Win32 service started by the service control manager when a process calls the StartService function.
SERVICE_DISABLED	Specifies a device driver or Win32 service that can no longer be started.
dwErrorControl

Specifies the severity of the error if this service fails to start during startup, and determines the action taken by the startup program if failure occurs. One of the following values can be specified:

Value	Meaning
SERVICE_ERROR_IGNORE
	The startup (boot) program logs the error but continues the startup operation.
SERVICE_ERROR_NORMAL
	The startup program logs the error and displays a message box pop-up but continues the startup operation.
SERVICE_ERROR_SEVERE
	The startup program logs the error. If the last-known good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known-good configuration.
SERVICE_ERROR_CRITICAL
	The startup program logs the error, if possible. If the last-known good configuration is being started, the startup operation fails. Otherwise, the system is restarted with the last-known good configuration.
lpBinaryPathName

Points to a null-terminated string that contains the fully qualified path to the service binary file.

lpLoadOrderGroup

Points to a null-terminated string that names the load ordering group of which this service is a member. If the pointer is NULL or if it points to an empty string, the service does not belong to a group. The registry has a list of load ordering groups located at:

HKEY_LOCAL_MACHINE\System
\CurrentControlSet\Control\ServiceGroupOrder.

The startup program uses this list to load groups of services in a specified order with respect to the other groups in the list. You can place a service in a group so that another service can depend on the group.

The order in which a service starts is determined by the following criteria:

1.	The order of groups in the registry’s load-ordering group list. Services in groups in the load-ordering group list are started first, followed by services in groups not in the load-ordering group list and then services that do not belong to a group.

2.	The service’s dependencies listed in the lpszDependencies parameter and the dependencies of other services dependent on the service.

dwTagId

Specifies a unique tag value for this service in the group specified by the lpLoadOrderGroup parameter. A value of zero indicates that the service has not been assigned a tag. You can use a tag for ordering service startup within a load order group by specifying a tag order vector in the registry located at:

HKEY_LOCAL_MACHINE\System\CurrentControlSet
\Control\GroupOrderList

Tags are only evaluated for SERVICE_KERNEL_DRIVER and SERVICE_FILE_SYSTEM_DRIVER type services that have SERVICE_BOOT_START or SERVICE_SYSTEM_START start types.

lpDependencies

Points to an array of null-separated names of services or load ordering groups that must start before this service. The array is doubly null-terminated. If the pointer is NULL or if it points to an empty string, the service has no dependencies. If a group name is specified, it must be prefixed by the SC_GROUP_IDENTIFIER (defined in the WINSVC.H file) character to differentiate it from a service name, because services and service groups share the same name space. Dependency on a service means that this service can only run if the service it depends on is running. Dependency on a group means that this service can run if at least one member of the group is running after an attempt to start all members of the group.

lpServiceStartName

Points to a null-terminated string. If the service type is SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS, this name is the account name in the form of “DomainName\Username”, which the service process will be logged on as when it runs. If the account belongs to the built-in domain, “.\Username” can be specified. If NULL is specified, the service will be logged on as the LocalSystem account.

If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, this name is the Windows NT driver object name (that is, \FileSystem\Rdr or \Driver\Xns) which the input and output (I/O) system uses to load the device driver. If NULL is specified, the driver is run with a default object name created by the I/O system based on the service name.

lpDisplayName

Points to a null-terminated string that is to be used by user interface programs to identify the service. This string has a maximum length of 256 characters. The name is case-preserved in the service control manager. Display name comparisons are always case-insensitive.

Remarks

The configuration information for a service is initially specified when the service is created by a call to the CreateService function. The information can be modified by calling the ChangeServiceConfig function.

See Also

ChangeServiceConfig, CreateService, QueryServiceConfig, StartService


QUERY_SERVICE_LOCK_STATUS

The QUERY_SERVICE_LOCK_STATUS structure is used by the QueryServiceLockStatus function to return information about the lock status of a service control manager database.

typedef struct _QUERY_SERVICE_LOCK_STATUS { // qsls

    DWORD fIsLocked;

    LPTSTR lpLockOwner;

    DWORD dwLockDuration;

} QUERY_SERVICE_LOCK_STATUS, * LPQUERY_SERVICE_LOCK_STATUS ;

Members

fIsLocked

Specifies whether the database is locked. If this member is nonzero, the database is locked. If it is zero, the database is unlocked.

lpLockOwner

Points to a null-terminated string containing the name of the user who acquired the lock.

dwLockDuration

Specifies the time, in seconds, since the lock was first acquired.

See Also

QueryServiceLockStatus


RAS_PARAMETERS [New - Windows NT]
RAS_PARAMETERS

[New - Windows NT]

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.

See Also

RasAdminAcceptNewConnection, RasAdminConnectionHangupNotification, RasAdminPortGetInfo


RAS_PARAMS_VALUE [New - Windows NT]
RAS_PARAMS_VALUE

[New - Windows NT]

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.

See Also

RAS_PARAMETERS, RAS_PARAMS_FORMAT


RAS_PORT_0 [New - Windows NT]
RAS_PORT_0

[New - Windows NT]

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.

See Also

RAS_PORT_1, RAS_PORT_STATISTICS, RasAdminGetUserAccountServer, RasAdminPortEnum


RAS_PORT_1 [New - Windows NT]
RAS_PORT_1

[New - Windows NT]

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.

See Also

RAS_PARAMETERS, RAS_PORT_0, RAS_PORT_STATISTICS, RAS_PPP_PROJECTION_RESULT, RasAdminAcceptNewConnection, RasAdminConnectionHangupNotification, RasAdminPortGetInfo


RAS_PORT_STATISTICS [New - Windows NT]
RAS_PORT_STATISTICS

[New - Windows NT]

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.

See Also

RAS_PORT_0, RasAdminAcceptNewConnection, RasAdminConnectionHangupNotification, RasAdminPortClearStatistics, RasAdminPortGetInfo


RAS_PPP_ATCP_RESULT [New - Windows NT]
RAS_PPP_ATCP_RESULT

[New - Windows NT]

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;

See Also

RAS_PPP_PROJECTION_RESULT


RAS_PPP_IPCP_RESULT [New - Windows NT]
RAS_PPP_IPCP_RESULT

[New - Windows NT]

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.

See Also

RAS_PORT_1, RAS_PPP_PROJECTION_RESULT, RasAdminPortGetInfo


RAS_PPP_IPXCP_RESULT [New - Windows NT]
RAS_PPP_IPXCP_RESULT

[New - Windows NT]

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.

See Also

RAS_PORT_1, RAS_PPP_PROJECTION_RESULT, RasAdminPortGetInfo


RAS_PPP_NBFCP_RESULT [New - Windows NT]
RAS_PPP_NBFCP_RESULT

[New - Windows NT]

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.

See Also

RAS_PORT_1, RAS_PPP_PROJECTION_RESULT, RasAdminPortGetInfo


RAS_PPP_PROJECTION_RESULT [New - Windows NT]
RAS_PPP_PROJECTION_RESULT

[New - Windows NT]

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.

See Also

RAS_PORT_1, RAS_PPP_ATCP_RESULT, RAS_PPP_IPCP_RESULT, RAS_PPP_IPXCP_RESULT, RAS_PPP_NBFCP_RESULT, RasAdminPortGetInfo


RAS_SECURITY_INFO [New - Windows NT]
RAS_SECURITY_INFO

[New - Windows NT]

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.

See Also

RasSecurityDialogGetInfo, RasSecurityDialogReceive


RAS_SERVER_0 [New - Windows NT]
RAS_SERVER_0

[New - Windows NT]

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

RasAdminServerGetInfo


RAS_USER_0 [New - Windows NT]
RAS_USER_0

[New - Windows NT]

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.

See Also

RasAdminUserGetInfo, RasAdminUserSetInfo


RASADPARAMS [New - Windows NT]
RASADPARAMS

[New - Windows NT]

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.

See Also

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.

See Also

RasGetProjectionInfo, RASPROJECTION


RASAUTODIALENTRY [New - Windows NT]
RASAUTODIALENTRY

[New - Windows NT]

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.

See Also

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.

See Also

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

See Also

RasGetConnectStatus, RasDial, RASCONNSTATE


RASCREDENTIALS [New - Windows NT]
RASCREDENTIALS

[New - Windows NT]

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.

See Also

RasGetCredentials, RasSetCredentials


RASCTRYINFO [New - Windows NT]
RASCTRYINFO

[New - Windows NT]

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.

See Also

RasGetCountryInfo


RASDEVINFO [New - Windows NT]
RASDEVINFO

[New - Windows NT]

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

Specifies a null-terminated string containing the name of a TAPI device.

See Also

RasEnumDevices


RASDIALDLG [New - Windows NT]
RASDIALDLG

[New - Windows NT]

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.

See Also

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 phonebook. If this bit flag is zero, RasDial ignores the prefix and suffix that is in the RAS phonebook. If no phonebook 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 phonebook, 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 phonebook, and ignores the setting specified by the RDEOPT_SetModemSpeaker bit flag. If no phonebook 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 phonebook setting or the default setting.
RDEOPT_IgnoreSoftwareCompression	If this bit flag is one, RasDial ignores the software compression setting that is in the RAS phonebook, 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 phonebook, and ignores the setting specified by the RDEOPT_SetSoftwareCompression bit flag. If no phonebook 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 phonebook 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.

See Also

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

See Also

RasDial


RASENTRY [New - Windows NT]
RASENTRY

[New - Windows NT]

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

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

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

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

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

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

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

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

RASADFunc, RasGetCountryInfo, RasSetEntryProperties, RasSetSubEntryProperties


RASENTRYDLG [New - Windows NT]
RASENTRYDLG

[New - Windows NT]

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.

See Also

RasEntryDlg


RASENTRYNAME

The RASENTRYNAME structure contains an entry name from a remote access phonebook. 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 phonebook entry.

See Also

RasEnumEntries


RASIPADDR [New - Windows NT]
RASIPADDR

[New - Windows NT]

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.

See Also

RASENTRY


RASMONITORDLG [New - Windows NT]
RASMONITORDLG

[New - Windows NT]

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.

See Also

RasMonitorDlg


RASNOUSER [New - Windows NT]
RASNOUSER

[New - Windows NT]

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.

See Also

RasPBDlgFunc, RasPhonebookDlg


RASPBDLG [New - Windows NT]
RASPBDLG

[New - Windows NT]

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.

See Also

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.

See Also

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

See Also

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.

See Also

RasGetProjectionInfo, RASPROJECTION


RASSLIP [New - Windows NT]
RASSLIP

[New - Windows NT]

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.

See Also

RASENTRY, RasGetProjectionInfo, RASPROJECTION


RASTERIZER_STATUS

The RASTERIZER_STATUS structure contains information about whether TrueType is installed. This structure is filled when an application calls the GetRasterizerCaps function.

typedef struct _RASTERIZER_STATUS {    // rs

    short nSize;

    short wFlags;

    short nLanguageID;

} RASTERIZER_STATUS;

Members

nSize

Specifies the size, in bytes, of the RASTERIZER_STATUS structure.

wFlags

Specifies whether at least one TrueType font is installed and whether TrueType is enabled. This value is TT_AVAILABLE, TT_ENABLED, or both if TrueType is on the system.

nLanguageID

Specifies the language in the system’s SETUP.INF file.

See Also

GetRasterizerCaps


REASSIGN_BLOCKS

The REASSIGN_BLOCKS structure provides disk-block reassignment data. It is a variable-length structure whose last member is an array of block numbers to be reassigned.

typedef struct _REASSIGN_BLOCKS {

    WORD   Reserved;

    WORD   Count;

    DWORD BlockNumber[1];

} REASSIGN_BLOCKS ;

Members

Reserved

This member is reserved. Do not use it. Set it to zero.

Count

Specifies the number of blocks to be reassigned. This is the number of elements that are in the BlockNumber member array.

BlockNumber

An array of Count block numbers, one for each block to be reassigned.

Remarks

The DeviceIoControl function uses a REASSIGN_BLOCKS structure as input to an IOCTL_DISK_REASSIGN_BLOCKS device input and output control operation.

See Also

DeviceIoControl, IOCTL_DISK_REASSIGN_BLOCKS


RASSUBENTRY [New - Windows NT]
RASSUBENTRY

[New - Windows NT]

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;

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

See Also

RasGetSubEntryProperties, RasSetSubEntryProperties


RECT

The RECT structure defines the coordinates of the upper-left and lower-right corners of a rectangle.

typedef struct _RECT {    // rc

    LONG left;

    LONG top;

    LONG right;

    LONG bottom;

} RECT;

Members

left

Specifies the x-coordinate of the upper-left corner of the rectangle.

top

Specifies the y-coordinate of the upper-left corner of the rectangle.

right

Specifies the x-coordinate of the lower-right corner of the rectangle.

bottom

Specifies the y-coordinate of the lower-right corner of the rectangle.

Remarks

When RECT is passed to the FillRect function, the rectangle is filled up to, but not including, the right column and bottom row of pixels. This structure is identical to the RECTL structure.

See Also

FillRect, RECTL, SMALL_RECT


RECTL

The RECTL structure defines the coordinates of the upper-left and lower-right corners of a rectangle.

typedef struct _RECTL { // rcl

    LONG left;

    LONG top;

    LONG right;

    LONG bottom;

} RECTL;

Members

left

Specifies the x-coordinate of the upper-left corner of the rectangle.

top

Specifies the y-coordinate of the upper-left corner of the rectangle.

right

Specifies the x-coordinate of the lower-right corner of the rectangle.

bottom

Specifies the y-coordinate of the lower-right corner of the rectangle.

Remarks

When RECTL is passed to the FillRect function, the rectangle is filled up to, but not including, the right column and bottom row of pixels. This structure is identical to the RECT structure.

See Also

FillRect, RECT, SMALL_RECT


REGISTERWORD

The REGISTERWORD structure contains reading information or a word to register. You can pass this structure to the ImmConfigureIME function to have the information or word appear as an initial value in the configuration dialog box of the input method editor.

typedef struct tagREGISTERWORD {

    LPTSTR  lpReading;

    LPTSTR  lpWord;

} REGISTERWORD;

Members

lpReading

Pointer to the reading information for the word to register. If the reading information is not needed, it can be NULL.

lpWord

Pointer to the word to register. If a word is not needed, it can be NULL.

See Also

ImmConfigureIME


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.

See Also

WNetAddConnection2, UNIVERSAL_NAME_INFO


REOBJECT

The REOBJECT structure contains information about an object.

typedef struct _reobject {
    DWORD  cbStruct;           // size of structure in bytes
    LONG   cp;                 // character position of object
    CLSID  clsid;              // class identifier of object
    LPOLEOBJECT      poleobj;  // OLE object interface
    LPSTORAGE        pstg;     // associated storage interface
    LPOLECLIENTSITE  polesite; // associated client site interface
    SIZEL  sizel;              // size of object (may be 0,0)
    DWORD  dvaspect;           // display aspect to use
    DWORD  dwFlags;            // object status flags
    DWORD  dwUser;             // user-defined value
} REOBJECT;

Members

cbStruct

Size, in bytes, of this structure.

cp

Character position of the object.

clsid

Class identifier of the object.

poleobj

Points to an instance of the IOleObject interface for the object.

pstg

Points to an instance of the IStorage interface. This is the storage object associated with the object.

polesite

Points to an instance of the IOleClientSite interface. This is the object’s client site in the rich edit control. This address must have been obtained from the IRichEditOle::GetClientSite method.

sizel

SIZEL structure specifying the size of the object. A 0,0 on insert indicates that an object is free to determine its size until the modify flag is turned off.

dvAspect

Display aspect to use.

dwFlags

Object status flags. Can be a combination of the following values:

Value	Meaning
REO_BELOWBASELINE	Object sits below the baseline of the surrounding text; the default is to sit on the baseline.
REO_BLANK	Object is brand new. This gives the object an opportunity to save nothing and be deleted from the control automatically.
REO_DONTUSEPALETTE	Prevents creation and realization of a half-tone palette before rendering the object. Applies to 32-bit platforms only.
REO_DYNAMICSIZE	Object always determines its extents and may change despite the modify flag being turned off.
REO_GETMETAFILE	The rich edit control retrieved the metafile from the object to correctly determine the object’s extents. This flag can be read but not set.
REO_HILITED	Object is currently highlighted to indicate selection. Occurs when focus is in the control and REO_SELECTED is set. This flag can be read but not set.
REO_INPLACEACTIVE	Object is currently in place active. This flag can be read but not set.
REO_INVERTEDSELECT	Object is to be drawn entirely inverted when selected; the default is to be drawn with a border.
REO_LINK	Object is a link. This flag can be read but not set.
REO_LINKAVAILABLE	Object is a link and is believed to be available. This flag can be read but not set.
REO_OPEN	Object is currently open in its server. This flag can be read but not set.
REO_RESIZABLE	Object may be resized.
REO_SELECTED	Object is currently selected in the rich edit control. This flag can be read but not set.
REO_STATIC	Object is a static object. This flag can be read but not set.
dwUser

Reserved for user-defined values.

See Also

IOleClientSite, IOleObject, IRichEditOle::GetClientSite, IStorage


REPASTESPECIAL

Contains information identifying whether the display aspect of a pasted object should be based on the content of the object or the icon that represent the object.

typedef struct _repastespecial {
    DWORD  dwAspect;  // display aspect for object
    DWORD  dwParam;   // aspect data
} REPASTESPECIAL;

Members

dwAspect

Display aspect. Can be DVASPECT_CONTENT if the aspect of the pasted object is based on the content of the object, or DVASPECT_ICON if the aspect is based on the icon view of the object.

dwParam

Aspect data. If dwAspect is DVASPECT_ICON, this member contains the handle to the metafile with the icon view of the object.


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.

See Also

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

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.

See Also

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

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

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.

See Also

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.

See Also

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;
    DWORD          rp0_interval;
    DWORD          rp0_pulse;
    DWORD          rp0_guardtime;
    DWORD          rp0_random;
} REPL_INFO_0, *PREPL_INFO_0, *LPREPL_INFO_0;

Members

rp0_role

A Unicode string that 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_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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

NetReplSetInfo


REQRESIZE

The REQRESIZE structure contains the requested size of a rich edit control. A rich edit control sends this structure to its parent window as part of an EN_REQUESTRESIZE notification message.

typedef struct _reqresize {

    NMHDR nmhdr;

    RECT rc;

} REQRESIZE;

Members

nmhdr

Notification header.

rc

Requested new size.

See Also

EN_REQUESTRESIZE


RESDIR

The RESDIR structure contains information about an individual icon or cursor component in a resource group. There is one RESDIR structure for each group component.

typedef struct tagRESDIR

{

    union

    {

        ICONRESDIR   Icon;

        CURSORDIR    Cursor;

    } ResInfo;

    WORD    Planes;

    WORD    BitCount;

    DWORD   BytesInRes;

    WORD  IconCursorId;

} RESDIR;

Members

Icon

Specifies an ICONRESDIR structure that contains the width, height, and color count of the indicated icon.

Cursor

Specifies a CURSORDIR structure that contains the width and height of the indicated cursor.

Planes

Specifies the number of color planes in the icon or cursor bitmap.

BitCount

Specifies the number of bits per pixel in the icon or cursor bitmap.

BytesInRes

Specifies the size of the resource, in bytes.

IconCursorId

Specifies the icon or cursor with a unique ordinal identifier.

Remarks

One or more RESDIR structures immediately follow the NEWHEADER structure in the .RES file. The ResCount member of the NEWHEADER structure specifies the number of RESDIR structures. Note that the RESDIR structure consists of either an ICONRESDIR structure or a CURSORDIR structure followed by the Planes, BitCount, BytesInRes and IconCursorId members. If the RESDIR structure contains information about a cursor, the first two WORDS the resource compiler writes to the RT_CURSOR resource are the xHotSpot and yHotSpot members of the LOCALHEADER structure.

See Also

CURSORDIR, ICONRESDIR, LOCALHEADER, NEWHEADER


RESOURCEHEADER

The RESOURCEHEADER structure contains information about the resource header itself and the data specific to this resource. This structure is not a true C-language structure, because it contains variable-length members. This structure was created solely to depict data organization in the resource file and does not appear in any of the header files shipped with the Microsoft Win32 Software Development Kit (SDK).

struct RESOURCEHEADER {

    DWORD DataSize;

    DWORD HeaderSize;

    [Ordinal or name TYPE];

    [Ordinal or name NAME];

    DWORD DataVersion;

    WORD MemoryFlags;

    WORD LanguageId;

    DWORD Version;

    DWORD Characteristics;

};

Members

DataSize

Specifies the size, in bytes, of the data that follows the resource header for this particular resource. It does not include any file padding between this resource and any resource that follows it in the resource file.

HeaderSize

Specifies the size, in bytes, of the resource header data that follows.

TYPE

Identifies the resource type. The TYPE member can either be a numeric value or a null-terminated Unicode string that specifies the name of the type. See the following Remarks section for a description of Name or Ordinal type members.

If the TYPE member is a numeric value, it can specify either a standard or a user-defined resource type. If the member is a string, then it is a user-defined resource type.

Following are the standard Windows resource types.

Resource Type Name	Type number
RT_CURSOR	1
RT_BITMAP	2
RT_ICON	3
RT_MENU	4
RT_DIALOG	5
RT_STRING	6
RT_FONTDIR	7
RT_FONT	8
RT_ACCELERATOR	9
RT_RCDATA	10
RT_MESSAGETABLE	11
RT_GROUP_CURSOR	12
RT_GROUP_ICON	14
RT_VERSION	16
RT_DLGINCLUDE	17
RT_PLUGPLAY	19
RT_VXD	20
RT_ANICURSOR	21
RT_ANIICON	22
Values less than 256 are reserved for system use.

NAME

Specifies a name that identifies the particular resource. The NAME member, like the TYPE member, can either be a numeric value or a null-terminated Unicode string. See the following Remarks section for a description of Name or Ordinal type members.

You do not need to add padding for DWORD alignment between the TYPE and NAME members because they contain WORD data. However, you may need to add a WORD of padding after the NAME member to align the rest of the header on DWORD boundaries.

DataVersion

Specifies a predefined resource data version. This will determine which version of the resource data the application should use.

MemoryFlags

Specifies a set of attribute flags that can describe the state of the resource. Modifiers in the .RC script file assign these attributes to the resource. The script identifiers can assign the following flag values.

Flag description	Value
MOVEABLE	0x0010
FIXED	~MOVEABLE
PURE	0x0020
IMPURE	~PURE
PRELOAD	0x0040
LOADONCALL	~PRELOAD
DISCARDABLE	0x1000
The only attribute a Win32-based application uses is the DISCARDABLE attribute. The remaining attributes are permitted in the script for compatibility with existing scripts, but they are ignored.

The resource compiler for Windows NT always ignores the MOVEABLE, IMPURE, and PRELOAD attribute flags. See Resource-Definition Statements for additional information about resource attributes.

LanguageId

Specifies the language for the resource or set of resources. Set the value for this member with the optional LANGUAGE Statement resource definition statement. The parameters are constants from the WINNT.H file.

Each resource includes a language identifier so the system or application can select a language appropriate for the current locale of the system. If there are multiple resources of the same type and name that differ only in the language of the strings within the resources, you will need to specify a LanguageId for each one.

Version

Specifies a user-defined version number for the resource data that tools can use to read and write resource files. Set this value with the optional VERSION resource definition statement.

Characteristics

Specifies user-defined information about the resource that tools can use to read and write resource files. Set this value with the optional CHARACTERISTICS resource definition statement.

Remarks

A variable type member is called a Name or Ordinal member, and it is used in most places in the resource file where an identifier appears. The first WORD of a Name or Ordinal type member indicates whether the member is a numeric value or a string. If the first WORD in the member is equal to the value 0xffff, which is an invalid Unicode character, then the following WORD is a type number. Otherwise, the member contains a Unicode string. For additional information about resource definition statements see Single-Line Statements and Multiline Statements.

See Also

CHARACTERISTICS Statement, LANGUAGE Statement, VERSION Statement


RFC1157VarBind

The RFC1157VarBind structure represents an SNMP variable binding as defined in RFC 1157.

typedef struct vb {
    AsnObjectName   name;
    AsnObjectSyntax value;
} RFC1157VarBind;

Members

name

Indicates the variable's name as an object identifier.

value

Contains the variable's value.

For more information, see RFC 1155 and RFC 1157.


RFC1157VarBindList

The RFC1157VarBindList structure represents an SNMP variable bindings list as defined in RFC 1157.

typedef struct {
    RFC1157VarBind *list;
    UINT           len;
} RFC1157VarBindList;

Members

list

A pointer that references an array to access individual variable bindings.

len

Contains the number of variable bindings in the list.

For more information, see RFC 1157.

See Also

RFC1157VarBind


RGBQUAD

The RGBQUAD structure describes a color consisting of relative intensities of red, green, and blue.

typedef struct tagRGBQUAD { // rgbq

    BYTE    rgbBlue;

    BYTE    rgbGreen;

    BYTE    rgbRed;

    BYTE    rgbReserved;

} RGBQUAD;

Members

rgbBlue

Specifies the intensity of blue in the color.

rgbGreen

Specifies the intensity of green in the color.

rgbRed

Specifies the intensity of red in the color.

rgbReserved

Reserved; must be zero.

Remarks

The bmiColors member of the BITMAPINFO structure consists of an array of RGBQUAD structures.

See Also

BITMAPINFO, CreateDIBitmap, CreateDIBSection, GetDIBits, SetDIBits, SetDIBitsToDevice, StretchDIBits


RGBTRIPLE

The RGBTRIPLE structure describes a color consisting of relative intensities of red, green, and blue. The bmciColors member of the BITMAPCOREINFO structure consists of an array of RGBTRIPLE structures.

typedef struct tagRGBTRIPLE { // rgbt

    BYTE rgbtBlue;

    BYTE rgbtGreen;

    BYTE rgbtRed;

} RGBTRIPLE;

Members

rgbtBlue

Specifies the intensity of blue in the color.

rgbtGreen

Specifies the intensity of green in the color.

rgbtRed

Specifies the intensity of red in the color.

See Also

BITMAPCOREINFO


RGNDATA

The RGNDATA structure contains a header and an array of rectangles that compose a region. The rectangles are sorted top to bottom, left to right. They do not overlap.

typedef struct _RGNDATA { // rgnd

    RGNDATAHEADER rdh;

    char          Buffer[1];

} RGNDATA;

Members

rdh

Specifies a RGNDATAHEADER structure. The members of this structure specify the type of region (whether it is rectangular or trapezoidal), the number of rectangles that make up the region, the size of the buffer that contains the rectangle structures, and so on.

Buffer

Specifies an arbitrary-size buffer that contains the RECT structures that make up the region.

See Also

RECT, RGNDATAHEADER


RGNDATAHEADER

The RGNDATAHEADER structure describes the data returned by the GetRegionData function.

typedef struct _RGNDATAHEADER { // rgndh

    DWORD dwSize;

    DWORD iType;

    DWORD nCount;

    DWORD nRgnSize;

    RECT  rcBound;

} RGNDATAHEADER;

Members

dwSize

Specifies the size, in bytes, of the header.

iType

Specifies the type of region. This value must be RDH_RECTANGLES.

nCount

Specifies the number of rectangles that make up the region.

nRgnSize

Specifies the size of the buffer required to receive the RECT structure that specifies the coordinates of the rectangles that make up the region. If the size is not known, this member can be zero.

rcBound

Specifies a bounding rectangle for the region.

See Also

GetRegionData, RECT, RGNDATA


RIP_INFO

The RIP_INFO structure contains the error and address, format, and length, in bytes, of a debugging string.

typedef struct _RIP_INFO { /* ri */

    DWORD  dwError;

    DWORD  dwType;

} RIP_INFO;

Members

dwError

Specifies the error that caused the RIP debug event. For more information about exception handling, see Errors.

dwType

Specifies additional information about the type of error that caused the RIP debug event. This may be one of the following values:

Value	Meaning
SLE_ERROR	Indicates that invalid data was passed to the function that failed. This caused the application to fail.
SLE_MINORERROR	Indicates that invalid data was passed to the function, but the error probably will not cause the application to fail.
SLE_WARNING	Indicates that potentially invalid data was passed to the function, but the function completed processing.
0	Indicates that only dwError was set.
See Also

DEBUG_EVENT


SCROLLINFO

The SCROLLINFO structure contains scroll bar parameters to be set by the SetScrollInfo function (or SBM_SETSCROLLINFO message), or retrieved by the GetScrollInfo function (or SBM_GETSCROLLINFO message).

typedef struct tagSCROLLINFO {  // si

    UINT cbSize;

    UINT fMask;

    int  nMin;

    int  nMax;

    UINT nPage;

    int  nPos;

    int  nTrackPos;

}   SCROLLINFO;

typedef SCROLLINFO FAR *LPSCROLLINFO;

Members

cbSize

Specifies the size, in bytes, of this structure.

fMask

Specifies the scroll bar parameters to set or retrieve. This member can be a combination of the following values:

Value	Meaning
SIF_ALL	Combination of SIF_PAGE, SIF_POS, and SIF_RANGE.
SIF_DISABLENOSCROLL	This value is used only when setting a scroll bar’s parameters. If the scroll bar’s new parameters make the scroll bar unnecessary, disable the scroll bar instead of removing it.
SIF_PAGE	The nPage member contains the page size for a proportional scroll bar.
SIF_POS	The nPos parameter contains the scroll box position.
SIF_RANGE	The nMin and nMax members contain the minimum and maximum values for the scrolling range.
nMin

Specifies the minimum scrolling position.

nMax

Specifies the maximum scrolling position.

nPage

Specifies the page size. A scroll bar uses this value to determine the appropriate size of the proportional scroll box.

nPos

Specifies the position of the scroll box.

nTrackPos

Specifies the immediate position of a scroll box that the user is dragging. An application can retrieve this value while processing the SB_THUMBTRACK notification message. An application cannot set the immediate scroll position; the SetScrollInfo function ignores this member.

See Also

SBM_GETSCROLLINFO, SBM_SETSCROLLINFO, GetScrollInfo, SetScrollInfo


SECURITY_ATTRIBUTES

The SECURITY_ATTRIBUTES structure contains the security descriptor for an object and specifies whether the handle retrieved by specifying this structure is inheritable.

typedef struct _SECURITY_ATTRIBUTES { // sa

    DWORD  nLength;

    LPVOID lpSecurityDescriptor;

    BOOL   bInheritHandle;

} SECURITY_ATTRIBUTES;

Members

nLength

Specifies the size, in bytes, of this structure. Set this value to the size of the SECURITY_ATTRIBUTES structure.

Windows NT: Some functions that use the SECURITY_ATTRIBUTES structure do not verify the value of the nLength member. However, an application should still set it properly. That ensures current, future, and cross-platform compatibility.

lpSecurityDescriptor

Points to a security descriptor for the object that controls the sharing of it. If NULL is specified for this member, the object may be assigned the default security descriptor of the calling process.

bInheritHandle

Specifies whether the returned handle is inherited when a new process is created. If this member is TRUE, the new process inherits the handle.

Remarks

A pointer to a SECURITY_ATTRIBUTES structure is used as a parameter in most kernel and window-management functions in the Win32 API that return a handle of an object.

See Also

SECURITY_DESCRIPTOR


SECURITY_DESCRIPTOR

The SECURITY_DESCRIPTOR structure contains the security information associated with an object. Applications use this structure to set and query an object’s security status.

Applications are not to modify the SECURITY_DESCRIPTOR structure directly. For creating and manipulating a security descriptor, use the functions listed in the See Also section.

typedef PVOID PSECURITY_DESCRIPTOR;

Remarks

A security descriptor includes information that specifies the following components of an object’s security:

•	An owner (SID)

•	A primary group (SID)

•	A discretionary ACL

•	A system ACL

•	Qualifiers for the preceding items

Security descriptors use access-control lists (ACLs) and security identifiers (SIDs) to specify the information in this list.

A security descriptor can be in absolute or self-relative form. In self-relative form, all members of the structure are located contiguously in memory. In absolute form, the structure only contains pointers to the members.

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SetSecurityDescriptorDacl, SetSecurityDescriptorGroup, SetSecurityDescriptorOwner, SetSecurityDescriptorSacl


SECURITY_DESCRIPTOR_CONTROL

The SECURITY_DESCRIPTOR_CONTROL structure contains a set of bit flags that qualify the meaning of a security descriptor or its individual members.

typedef WORD SECURITY_DESCRIPTOR_CONTROL;

Each security descriptor has an associated SECURITY_DESCRIPTOR_CONTROL structure. Applications can use the Win32 API functions to set and retrieve a security descriptor’s SECURITY_DESCRIPTOR_CONTROL values. These functions are listed in the See Also section.

The following constants are defined for setting and retrieving SECURITY_DESCRIPTOR_CONTROL bit flags:

Value	Meaning
SE_OWNER_DEFAULTED	Instead of the original provider of the security descriptor, a default mechanism provided the security descriptor’s owner security identifier (SID). This can affect the treatment of the SID with respect to inheritance of an owner. This flag is ignored if the owner member is NULL. The SetSecurityDescriptorOwner function sets this flag.
SE_GROUP_DEFAULTED	Instead of the the original provider of the security descriptor, a default mechanism provided the security descriptor’s group SID. This can affect the treatment of the SID with respect to inheritance of a primary group. This flag is ignored if the group member is NULL. The SetSecurityDescriptorGroup function sets this flag.
SE_DACL_PRESENT	The security descriptor contains a discretionary access-control list (ACL). If this flag is set and the discretionary ACL is NULL, an empty ACL is being explicitly specified. An empty ACL has a size but no access-control entries (ACEs). A NULL ACL has no pointer to an ACL. This flag allows functions to determine whether a security descriptor points to a NULL ACL or no ACL at all. The SetSecurityDescriptorDacl function sets this flag.
SE_DACL_DEFAULTED	Instead of the the original provider of the security descriptor, a default mechanism provided the discretionary ACL. This can affect the treatment of the ACL with respect to inheritance of an ACL. If the SE_DACL_PRESENT flag is not set, this flag is ignored. The SetSecurityDescriptorDacl function sets this flag.
SE_SACL_PRESENT	The security descriptor contains a system ACL. If this flag is set and the Sacl member is NULL, an empty ACL is being explicitly specified. This flag allows functions to determine whether a security descriptor points to a NULL ACL or no ACL at all. The SetSecurityDescriptorSacl function sets this flag.
SE_SACL_DEFAULTED	Instead of the the original provider of the security descriptor, a default mechanism provided the ACL. This can affect the treatment of the ACL with respect to inheritance of an ACL. If the SE_SACL_PRESENT flag is not set, this flag is ignored. The SetSecurityDescriptorSacl function sets this flag.
SE_SELF_RELATIVE	The security descriptor is in self-relative form and all members of the security descriptor are contiguous in memory. All pointer members are expressed as offsets from the beginning of the security descriptor. This form is useful for treating security descriptors as opaque structures for transmission in a communications protocol or for storage on secondary media.
See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, SetSecurityDescriptorDacl, SetSecurityDescriptorGroup, SetSecurityDescriptorOwner, SetSecurityDescriptorSacl


SECURITY_INFORMATION

The SECURITY_INFORMATION structure identifies the object-related security information being set or queried. This security information includes:

•	The owner of an object

•	The primary group of an object

•	The discretionary access-control list (ACL) of an object

•	The system ACL of an object

typedef DWORD SECURITY_INFORMATION;

Each item of security information is designated by a bit flag. The following values specify the bits:

Value	Meaning
OWNER_SECURITY_INFORMATION	Indicates the owner identifier of the object is being referenced.
GROUP_SECURITY_INFORMATION	Indicates the primary group identifier of the object is being referenced.
DACL_SECURITY_INFORMATION	Indicates the discretionary ACL of the object is being referenced.
SACL_SECURITY_INFORMATION	Indicates the system ACL of the object is being referenced.
See Also

GetFileSecurity, GetKernelObjectSecurity, GetPrivateObjectSecurity, GetUserObjectSecurity, SetFileSecurity, SetKernelObjectSecurity, SetPrivateObjectSecurity, SetUserObjectSecurity


SECURITY_MESSAGE [New - Windows NT]
SECURITY_MESSAGE

[New - Windows NT]

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.

See Also

RasSecurityDialogBegin, RasSecurityDialogComplete


SECURITY_QUALITY_OF_SERVICE

The SECURITY_QUALITY_OF_SERVICE data structure contains information used to support client impersonation. A client can specify this information when it connects to a server; the information determines whether or not the server may impersonate the client, and if so, to what extent.

typedef struct _SECURITY_QUALITY_OF_SERVICE { // sqos

    DWORD Length;

    SECURITY_IMPERSONATION_LEVEL ImpersonationLevel;

    SECURITY_CONTEXT_TRACKING_MODE ContextTrackingMode;

    BOOLEAN EffectiveOnly;

} SECURITY_QUALITY_OF_SERVICE;

Members

Length

Specifies the size, in bytes, of this structure.

ImpersonationLevel

Specifies what the server may be told about the client, and how the server may represent, or impersonate, the client. Security impersonation levels govern the degree to which a server process can act on behalf of a client process. This member is a SECURITY_IMPERSONATION_LEVEL enumeration type value.

ContextTrackingMode

Specifies whether the server is to be given a snapshot of the client’s security context (called static tracking), or is to be continually updated to track changes to the client’s security context (called dynamic tracking). The value SECURITY_STATIC_TRACKING specifies static tracking, and the value SECURITY_DYNAMIC_TRACKING specifies dynamic tracking. Not all communications mechanisms support dynamic tracking; those that do not will default to static tracking.

EffectiveOnly

Specifies whether or not the server may enable or disable privileges and groups that the client’s security context may include.

See Also

DdeSetQualityOfService, SECURITY_IMPERSONATION_LEVEL


SELCHANGE

The SELCHANGE stucture contains information associated with an EN_SELCHANGE notification message. A rich edit control sends this notification to its parent window when the current selection changes.

typedef struct _selchange {

    NMHDR nmhdr;

    CHARRANGE chrg;

    WORD seltyp;

} SELCHANGE;

Members

nmhdr

Notification header.

chrg

New selection range.

seltyp

Value specifying the contents of the new selection. This member is SEL_EMPTY if the selection is empty or one or more of the following values:

Value	Contents of the selection
SEL_TEXT	Text
SEL_OBJECT	At least one OLE object
SEL_MULTICHAR	More than one character of text
SEL_MULTIOBJECT	More than one OLE object
See Also

EN_SELCHANGE


SERIALKEYS

The SERIALKEYS structure contains information about the SerialKeys accessibility feature, which interprets data from a communication aid attached to a serial port as commands causing the system to simulate keyboard and mouse input.

typedef struct tagSERIALKEYS {     // sk

    DWORD cbSize;

    DWORD dwFlags;

    LPSTR lpszActivePort;

    LPSTR lpszPort;

    DWORD iBaudRate;

    DWORD iPortState;

} SERIALKEYS, FAR* LPSERIALKEYS;

Members

cbSize

Specifies the structure size, in bytes.

dwFlags

Specifies a combination of the following values:

Value	Meaning
SERKF_ACTIVE	The SerialKeys feature is currently receiving input on the serial port specified by lpszPort.
SERKF_AVAILABLE	The SerialKeys feature is available.
SERKF_INDICATOR	A visual indicator is displayed when the SerialKeys feature is on. This value is not currently used and is ignored.
SERKF_SERIALKEYSON	The SerialKeys feature is on.
lpszActivePort

Points to a string that contains the name of the serial port that receives input from the communication aid when the SerialKeys feature is on. If no port is being used, this member is NULL. If this member is “Auto”, the system watches all unused serial ports for input from communication aids.

lpszPort

Reserved; must be NULL.

iBaudRate

Specifies the baud rate setting for the serial port specified by the lpszActivePort member. This member should be set to one of the CBR_ values defined in the Windows header files. If lpszActivePort is NULL, this member is zero.

iPortState

Specifies the state of the port specified by the lpszActivePort member. If lpszActivePort is NULL, iPortState is zero; otherwise, it is one of the following values:

Value	Meaning
0	All input on this port is ignored by the SerialKeys feature.
1	Input on this port is watched for SerialKeys activation sequences when no other application has the port open.
2	All input on this port is treated as SerialKeys commands.
Remarks

An application uses this structure when calling the SystemParametersInfo function with the SPI_GETSERIALKEYS or SPI_SETSERIALKEYS value. When using SPI_GETSERIALKEYS, an application must specify the cbSize, lpszActivePort, and lpszPort members of the SERIALKEYS structure; the SystemParametersInfo function fills the remaining members. An application must specify all structure members when using the SPI_SETSERIALKEYS value.

See Also

SystemParametersInfo


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

See Also

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;
    LPTSTR    sv101_name;
    DWORD     sv101_version_major;
    DWORD     sv101_version_minor;
    DWORD     sv101_type;
    LPTSTR    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 LAN Manager software. 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 LAN Manager software.

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.

See Also

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;
    LPTSTR    sv102_name;
    DWORD     sv102_version_major;
    DWORD     sv102_version_minor;
    DWORD     sv102_type;
    LPTSTR    sv102_comment;
    DWORD     sv102_users;
    LONG      sv102_disc;
    BOOL      sv102_hidden;
    DWORD     sv102_announce;
    DWORD     sv102_anndelta;
    LPTSTR    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 LAN Manager software. 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 LAN Manager software.

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.

See Also

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;
     LPTSTR         sv402_alerts;
     DWORD          sv402_security;
     DWORD          sv402_numadmin;
     DWORD          sv402_lanmask;
     LPTSTR         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;
     LPTSTR         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.

See Also

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;
     LPTSTR         sv403_alerts;
     DWORD          sv403_security;
     DWORD          sv403_numadmin;
     DWORD          sv403_lanmask;
     LPTSTR         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;
     LPTSTR         sv403_srvheuristics;
     DWORD          sv403_auditedevents;
     DWORD          sv403_autoprofile;
     LPTSTR         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.

See Also

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.

See Also

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;
    LPTSTR    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 LAN Manager 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.

See Also

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

See Also

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.

See Also

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.

See Also

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

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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 LAN Manager server announcements, in seconds.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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;
    LPTSTR    svti0_transportname;
    [size_is(svti0_transportaddresslength)]    LPBYTE svti0_transportaddress;
    DWORD     svti0_transportaddresslength;
    LPTSTR    svti0_networkaddress;
} SERVER_TRANSPORT_INFO_0, *PSERVER_TRANSPORT_INFO_0, *LPSERVER_TRANSPORT_INFO_0;

#else

typedef struct _SERVER_TRANSPORT_INFO_0 {
    DWORD     svti0_numberofvcs;
    LPTSTR    svti0_transportname;
    LPBYTE    svti0_transportaddress;
    DWORD     svti0_transportaddresslength;
    LPTSTR    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.

See Also

NetServerTransportAdd


SERVICE_ADDRESS

The SERVICE_ADDRESS structure contains address information for a service. The structure can accomodate many types of interprocess communications (IPC) mechanisms and their address forms, including remote procedure calls (RPCs), named pipes, and sockets.

typedef struct _SERVICE_ADDRESS {

    DWORD   dwAddressType;

    DWORD   dwAddressFlags;

    DWORD   dwAddressLength;

    DWORD   dwPrincipalLength;

    BYTE   *lpAddress;

    BYTE   *lpPrincipal;

} SERVICE_ADDRESS;

Members

dwAddressType

Specifies the address family that the socket address pointed to by lpAddress belongs to.

dwAddressFlags

A set of bit flags that specify properties of the address. The following bit flags are defined:

Value	Meaning
SERVICE_ADDRESS_FLAG_RPC_CN	If this bit flag is set, the service supports connection-oriented RPC over this transport protocol.
SERVICE_ADDRESS_FLAG_RPC_DG	If this bit flag is set, the service supports datagram-oriented RPC over this transport protocol.
SERVICE_ADDRESS_FLAG_RPC_NB	If this bit flag is set, the service supports NetBIOS RPC over this transport protocol.
dwAddressLength

Specifies the size, in bytes, of the address.

dwPrincipalLength

This member is reserved for future use. It must be zero.

lpAddress

Points to a socket address of the appropriate type.

lpPrincipal

This member is reserved for future use. It must be NULL.

See Also

SERVICE_ADDRESSES, SERVICE_INFO


SERVICE_ADDRESSES

The SERVICE_ADDRESSES structure contains an array of SERVICE_ADDRESS data structures.

typedef struct _SERVICE_ADDRESSES {

    DWORD   dwAddressCount;

    SERVICE_ADDRESS   Addresses[1];

} SERVICE_ADDRESSES;

Members

dwAddressCount

Specifies the number of SERVICE_ADDRESS structures in the Addresses array.

Addresses

An array of SERVICE_ADDRESS data structures. Each SERVICE_ADDRESS structure contains information about a network service address.

See Also

SERVICE_ADDRESS, SERVICE_INFO


SERVICE_INFO

The SERVICE_INFO structure contains information about a network service or a network service type.

typedef struct _SERVICE_INFO {

    LPGUID   lpServiceType;

    LPTSTR   lpServiceName;

    LPTSTR   lpComment;

    LPTSTR   lpLocale;

    DWORD    dwDisplayHint;

    DWORD    dwVersion;

    DWORD    dwTime;

    LPTSTR   lpMachineName;

    LPSERVICE_ADDRESSES lpServiceAddress;

    BLOB ServiceSpecificInfo;

} SERVICE_INFO;

Members

lpServiceType

Points to a GUID that is the type of the network service.

lpServiceName

Points to a zero-terminated string that is the name of the network service.

If you are calling the SetService function with the dwNameSpace parameter set to NS_DEFAULT, the network service name must be a common name A common name is what the network service is commonly known as. An example of a common name for a network service is “My SQL Server”.

If you are calling the SetService function with the dwNameSpace parameter set to a specific service name, the network service name can be a common name or a distinguished name. A distinguished name distinguishes the service to a unique location with a directory service. An example of a distinguished name for a network service is “MS\\SYS\\NT\\DEV\\My SQL Server”.

lpComment

Points to a zero-terminated string that is a comment or description for the network service. For example, “Used for development upgrades.”

lpLocale

Points to a zero-terminated string that contains locale information.

dwDisplayHint

Specifies a hint as to how to display the network service in a network browsing user interface. This can be one of the following values:

Value	Meaning
RESOURCEDISPLAYTYPE_DOMAIN	Display the network service as a domain.
RESOURCEDISPLAYTYPE_FILE	Display the network service as a file.
RESOURCEDISPLAYTYPE_GENERIC	The method used to display the object does not matter.
RESOURCEDISPLAYTYPE_GROUP	Display the network service as a group.
RESOURCEDISPLAYTYPE_SERVER	Display the network service as a server.
RESOURCEDISPLAYTYPE_SHARE	Display the network service as a sharepoint.
RESOURCEDISPLAYTYPE_TREE	Display the network service as a tree.
dwVersion

Specifies version information for the network service. The high word of this value specifies a major version number. The low word of this value specifies a minor version number.

dwTime

This member is reserved for future use. It must be set to zero.

lpMachineName

Points to a zero-terminated string that is the name of the computer on which the network service is running.

lpServiceAddress

Points to a SERVICE_ADDRESSES structure that contains an array of SERVICE_ADDRESS structures. Each SERVICE_ADDRESS structure contains information about a network service address.

A network service can call the getsockname function to determine the local address of the system.

ServiceSpecificInfo

A BLOB structure that specifies service-defined information.

Note that, in general, the data pointed to by the BLOB structure’s pBlobData member must not contain any pointers. That is because only the network service knows the format of the data; copying the data without such knowledge would lead to pointer invalidation. If the data pointed to by pBlobData contains variable-sized elements, offsets from pBlobData can be used to indicate the location of those elements. There is one exception to this general rule: when pBlobData points to a SERVICE_TYPE_INFO_ABS structure. This is possible because both the SERVICE_TYPE_INFO_ABS structure, and any SERVICE_TYPE_VALUE_ABS structures it contains are predefined, and thus their formats are known to the operating system.

See Also

BLOB, GetService, NS_SERVICE_INFO, SetService, SERVICE_ADDRESS, SERVICE_ADDRESSES, SERVICE_TYPE_INFO_ABS, SERVICE_TYPE_VALUE_ABS


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.

See Also

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.

See Also

NetServiceEnum, NetServiceGetInfo


SERVICE_INFO_2

The SERVICE_INFO_2 structure describes the attributes of LAN Manager services.

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.

See Also

NetServiceEnum, NetServiceGetInfo, NetServiceInstall


SERVICE_STATUS

The SERVICE_STATUS structure contains information about a service. The ControlService, EnumDependentServices, EnumServicesStatus, and QueryServiceStatus functions use this structure to return information about a service. A service uses this structure in the SetServiceStatus function to report its current status to the service control manager.

typedef struct _SERVICE_STATUS { // ss

    DWORD dwServiceType;

    DWORD dwCurrentState;

    DWORD dwControlsAccepted;

    DWORD dwWin32ExitCode;

    DWORD dwServiceSpecificExitCode;

    DWORD dwCheckPoint;

    DWORD dwWaitHint;

} SERVICE_STATUS, *LPSERVICE_STATUS;

Members

dwServiceType

The value returned includes one of the following service type flags to indicate the type of service. In addition, for a SERVICE_WIN32 service, the SERVICE_INTERACTIVE_PROCESS flag might be set, indicating that the service process can interact with the desktop.

Value	Meaning
SERVICE_WIN32_OWN_PROCESS	A service type flag that indicates a Win32 service that runs in its own process.
SERVICE_WIN32_SHARE_PROCESS	A service type flag that indicates a Win32 service that shares a process with other services.
SERVICE_KERNEL_DRIVER	A service type flag that indicates a Windows NT device driver.
SERVICE_FILE_SYSTEM_DRIVER	A service type flag that indicates a Windows NT file system driver.
SERVICE_INTERACTIVE_PROCESS	A flag that indicates a Win32 service process that can interact with the desktop.
dwCurrentState

Indicates the current state of the service. One of the following values is specified:

Value	Meaning
SERVICE_STOPPED	The service is not running.
SERVICE_START_PENDING	The service is starting.
SERVICE_STOP_PENDING	The service is stopping.
SERVICE_RUNNING	The service is running.
SERVICE_CONTINUE_PENDING	The service continue is pending.
SERVICE_PAUSE_PENDING	The service pause is pending.
SERVICE_PAUSED	The service is paused.
dwControlsAccepted

Specifies the control codes that the service will accept and process. A user interface process can control a service by specifying a control command in the ControlService function. By default, all services accept the SERVICE_CONTROL_INTERROGATE value. Any or all of the following flags can be specified to enable the other control codes.

Value	Meaning
SERVICE_ACCEPT_STOP
	The service can be stopped. This enables the SERVICE_CONTROL_STOP value.
SERVICE_ACCEPT_PAUSE_CONTINUE
	The service can be paused and continued. This enables the SERVICE_CONTROL_PAUSE and SERVICE_CONTROL_CONTINUE values.
SERVICE_ACCEPT_SHUTDOWN
	The service is notified when system shutdown occurs. This enables the system to send a SERVICE_CONTROL_SHUTDOWN value to the service. The ControlService function cannot send this control code.
dwWin32ExitCode

Specifies a Win32 error code that the service uses to report an error that occurs when it is starting or stopping. To return an error code specific to the service, the service must set this value to ERROR_SERVICE_SPECIFIC_ERROR to indicate that the dwServiceSpecificExitCode member contains the error code. The service should set this value to NO_ERROR when it is running and on normal termination.

dwServiceSpecificExitCode

Specifies a service specific error code that the service returns when an error occurs while the service is starting or stopping. This value is ignored unless the dwWin32ExitCode member is set to ERROR_SERVICE_SPECIFIC_ERROR.

dwCheckPoint

Specifies a value that the service increments periodically to report its progress during a lengthy start, stop, or continue operation. For example, the service should increment this value as it completes each step of its initialization when it is starting up. The user interface program that invoked the operation on the service uses this value to track the progress of the service during a lengthy operation. This value is not valid and should be zero when the service does not have a start, stop, or continue operation pending.

dwWaitHint

Specifies an estimate of the amount of time, in milliseconds, that the service expects a pending start, stop, or continue operation to take before the service makes its next call to the SetServiceStatus function with either an incremented dwCheckPoint value or a change in dwCurrentState. If the amount of time specified by dwWaitHint passes, and dwCheckPoint has not been incremented, or dwCurrentState has not changed, the service control manager or service control program can assume that an error has occurred.

See Also

ControlService, EnumDependentServices, EnumServicesStatus, QueryServiceStatus, SetServiceStatus


SERVICE_TABLE_ENTRY

The SERVICE_TABLE_ENTRY structure is used by the StartServiceCtrlDispatcher function to specify the ServiceMain function for a Win32 service that can run in the calling process.

typedef struct _SERVICE_TABLE_ENTRY { // ste

    LPTSTR lpServiceName;

    LPSERVICE_MAIN_FUNCTION lpServiceProc;

} SERVICE_TABLE_ENTRY, *LPSERVICE_TABLE_ENTRY;

Members

lpServiceName

Points to a null-terminated string that names a service that can run in this service process. This string is ignored if the service is installed in the service control manager database as a SERVICE_WIN32_OWN_PROCESS service type. For a SERVICE_WIN32_SHARE_PROCESS service process, this string names the service that uses the ServiceMain function pointed to by the lpServiceProc member.

lpServiceProc

Points to a ServiceMain function.

See Also

ServiceMain, StartServiceCtrlDispatcher


SERVICE_TYPE_INFO_ABS

The SERVICE_TYPE_INFO_ABS structure contains information about a network service type. You use a SERVICE_TYPE_INFO_ABS structure to add a network service type to a name space.

typedef struct _SERVICE_TYPE_INFO_ABS {

    LPTSTR                  lpTypeName;

    DWORD                   dwValueCount;

    SERVICE_TYPE_VALUE_ABS  Values[1];

} SERVICE_TYPE_INFO_ABS

Members

lpTypeName

Points to a zero-terminated string that is the name of the network service type.  This name is the same in all name spaces, and is used by the GetTypeByName and GetNameByType functions.

dwValueCount

Specifies the number of SERVICE_TYPE_VALUE_ABS structures in the Values member array that follows dwValueCount.

Values[1]

An array of SERVICE_TYPE_VALUE_ABS structures.

Each of these structures contains information about a service type value that the operating system or network service may need when an instance of this network service type is registered with a name space.

The information in these structures may be specific to a name-space. For example, if a network service uses the SAP name space, but does not have a GUID that contains the SAP identifier (SAPID), it defines the SAPID in a SERVICE_TYPE_VALUE_ABS structure.

Remarks

When you use the SetService function to add a network service type to a name space, the SERVICE_TYPE_INFO_ABS structure is passed as the ServiceSpecificInfo BLOB member of a SERVICE_INFO structure. Although the ServiceSpecificInfo member generally should not contain pointers, an exception is made in the case of the SERVICE_TYPE_INFO_ABS and SERVICE_TYPE_VALUE_ABS structures.

See Also

SetService, SERVICE_INFO, SERVICE_TYPE_VALUE_ABS


SERVICE_TYPE_VALUE_ABS

The SERVICE_TYPE_VALUE_ABS structure contains information about a network-service type value. This information may be specific to a name space.

typedef struct _SERVICE_TYPE_VALUE_ABS {

    DWORD   dwNameSpace;

    DWORD   dwValueType;

    DWORD   dwValueSize;

    LPTSTR  lpValueName;

    PVOID   lpValue;

} SERVICE_TYPE_VALUE_ABS

Members

dwNameSpace

Specifies the name space, or a set of default name spaces, for which the network service type value is intended. Name-space providers will look only at values intended for their name space.

Use one of the following constants to specify a name space:

Value	Name Space
NS_DEFAULT	A set of default name spaces. The function queries each name space within this set. The set of default name spaces typically includes all the name spaces installed on the system. System administrators, however, can exclude particular name spaces from the set. NS_DEFAULT is the value that most applications should use for dwNameSpace.
NS_DNS	The Domain Name System used in the Internet for host name resolution.
NS_NETBT	The NetBIOS over TCP/IP layer. All Windows NT systems register their computer names with NetBIOS. This name space is used to convert a computer name to an IP address that uses this registration. Note that NS_NETBT may access a WINS server to perform the resolution.
NS_SAP	The Netware Service Advertising Protocol. This may access the Netware bindery if appropriate. NS_SAP is a dynamic name space that allows registration of services.
NS_TCPIP_HOSTS	Lookup value in the <systemroot>\system32\drivers\etc\hosts file.
NS_TCPIP_LOCAL	Local TCP/IP name resolution mechanisms, including comparisons against the local host name and looks up host names and IP addresses in cache of host to IP address mappings.
dwValueType

Specifies the type of the value data. You can specify one of the following types:

Value	Meaning
REG_BINARY	Binary data in any form.
REG_DWORD	A 32-bit number.
REG_MULTI_SZ	An array of null-terminated strings, terminated by two null characters.
REG_SZ	A null-terminated string.
dwValueSize

Specifies the size, in bytes, of the value data. In the case of REG_SZ and REG_MULTI_SZ string data, the terminating characters are counted as part of the size.

lpValueName

Points to a zero-terminated string that is the name of the value. This name is specific to a name space.

Several commonly used value name strings are associated with defined constants. These name strings include the following:

Constant	Name String
SERVICE_TYPE_VALUE_SAPID	"SapId"
SERVICE_TYPE_VALUE_CONN	"ConnectionOriented"
SERVICE_TYPE_VALUE_TCPPORT	"TcpPort"
SERVICE_TYPE_VALUE_UDPPORT	"UdpPort"
lpValue

Points to the value data.

Remarks

When you use the SetService function to add a network service type to a name space, a SERVICE_TYPE_INFO_ABS structure is passed as the ServiceSpecificInfo BLOB member of a SERVICE_INFO structure. Although the ServiceSpecificInfo member generally should not contain pointers, an exception is made in the case of the SERVICE_TYPE_INFO_ABS and SERVICE_TYPE_VALUE_ABS structures.

See Also

SetService, SERVICE_INFO, SERVICE_TYPE_INFO_ABS


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.

See Also

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.

See Also

NCB, SESSION_BUFFER


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

See Also

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 {
    LPTSTR    sesi1_cname;  // client name (no backslashes)
    LPTSTR    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.
See Also

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{
    LPTSTR    sesi2_cname;  // client name (no backslashes)
    LPTSTR    sesi2_username;
    DWORD     sesi2_num_opens;
    DWORD     sesi2_time;
    DWORD     sesi2_idle_time;
    DWORD     sesi2_user_flags;
    LPTSTR    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.

See Also

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 {
    LPTSTR    sesi10_cname; // client name (no backslashes)
    LPTSTR    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.

See Also

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 {
    LPTSTR    sesi502_cname; // client name (no backslashes)
    LPTSTR    sesi502_username;
    DWORD     sesi502_num_opens;
    DWORD     sesi502_time;
    DWORD     sesi502_idle_time;
    DWORD     sesi502_user_flags;
    LPTSTR    sesi502_cltype_name;
    LPTSTR    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.

See Also

NetSessionEnum


SET_PARTITION_INFORMATION

The SET_PARTITION_INFORMATION structure provides information used to set a disk partition’s type.

typedef struct _SET_PARTITION_INFORMATION {

   BYTE PartitionType;

} SET_PARTITION_INFORMATION ;

Members

PartitionType

Specifies the type of partition. This member can be one of the following values: Value	Meaning
PARTITION_ENTRY_UNUSED	Entry unused.
PARTITION_FAT_12	Specifies a partition with 12-bit FAT entries.
PARTITION_XENIX_1	Specifies a Xenix type 1 partition.
PARTITION_XENIX_2	Specifies a Xenix type 2 partition.
PARTITION_FAT_16	Specifies a partition with 16-bit FAT entries.
PARTITION_EXTENDED	Specifies an extended partition entry.
PARTITION_HUGE	Specifies an MS-DOS V4 huge partition.
PARTITION_IFS	Specifies an IFS partition.
PARTITION_UNIX	Specifies a UNIX partition.
VALID_NTFT	Specifies an NTFT partition.
PARTITION_XINT13	Specifies a Windows 95 partition that uses extended int13 services.
PARTITION_XINT13_EXTENDED	Same as PARTITION_EXTENDED, but uses extended int13 services.
Remarks

The DeviceIoControl function uses a SET_PARTITION_INFORMATION structure as input to an IOCTL_DISK_SET_PARTITION_INFO device input and output control operation.

See Also

DeviceIoControl, IOCTL_DISK_GET_PARTITION_INFO, IOCTL_DISK_SET_PARTITION_INFO, PARTITION_INFORMATION


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 {
    LPTSTR    shi0_netname;
} SHARE_INFO_0, *PSHARE_INFO_0, *LPSHARE_INFO_0;

Members

shi0_netname

A Unicode string containing the sharename of a resource.

See Also

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 number of connections.

typedef struct _SHARE_INFO_1 {
    LPTSTR    shi1_netname;
    DWORD     shi1_type;
    LPTSTR    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.

See Also

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 {
    LPTSTR    shi2_netname;
    DWORD     shi2_type;
    LPTSTR    shi2_remark;
    DWORD     shi2_permissions;
    DWORD     shi2_max_uses;
    DWORD     shi2_current_uses;
    LPTSTR    shi2_path;
    LPTSTR    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).

See Also

NetShareAdd, NetShareEnum, NetShareGetInfo, NetShareSetInfo


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 {
    LPTSTR    shi502_netname;
    DWORD     shi502_type;
    LPTSTR    shi502_remark;
    DWORD     shi502_permissions;
    DWORD     shi502_max_uses;
    DWORD     shi502_current_uses;
    LPTSTR    shi502_path;
    LPTSTR    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 Windows NT security descriptor associated with this share.

See Also

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

See Also

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

See Also

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 Windows NT security descriptor associated with this share.

See Also

NetShareSetInfo


SHELLEXECUTEINFO

Specifies an enumerated type that defines flags used with the IShellFolder::EnumObjects method.

The SHELLEXECUTEINFO structure contains information used by the ShellExecuteEx function.

typedef struct _SHELLEXECUTEINFO {   // sei

    DWORD     cbSize;

    ULONG     fMask;

    HWND      hwnd;

    LPCSTR    lpVerb;

    LPCSTR    lpFile;

    LPCSTR    lpParameters;

    LPCSTR    lpDirectory;

    int       nShow;

    HINSTANCE hInstApp;

    // Optional members

    LPVOID lpIDList;

    LPCSTR lpClass;

    HKEY   hkeyClass;

    DWORD  dwHotKey;

    HANDLE hIcon;

    HANDLE hProcess;

} SHELLEXECUTEINFO, FAR *LPSHELLEXECUTEINFO;

Members

cbSize

Specifies the size, in bytes, of the structure.

fMask

This is an array of flags that indicate the content and validity of the other structure members. You can specify a combination of the following values:

Value	Meaning
SEE_MASK_CLASSKEY	Use the class key given by the hkeyClass member.
SEE_MASK_CLASSNAME	Use the class name given by the lpClass member.
SEE_MASK_CONNECTNETDRV	The lpFile member is a Universal Naming Convention (UNC) path of a file on a network. Validate the share and connect to a drive letter.
SEE_MASK_DOENVSUBST	Expand any environment variables specified in the string given by the lpDirectory or lpFile member.
SEE_MASK_FLAG_DDEWAIT	Wait for the DDE conversation to terminate before returning, if the ShellExecuteEx function causes a DDE conversation to start.
SEE_MASK_FLAG_NO_UI	Do not display an error message box if an error occurs.
SEE_MASK_HOTKEY	Use the hot key given by the dwHotKey member.
SEE_MASK_ICON	Use the icon given by the hIcon member.
SEE_MASK_IDLIST	Use the item identifier list given by the lpIDList member.
SEE_MASK_INVOKEIDLIST	Use the item identifier list given by the lpIDList member to invoke an application. If this member is NULL, the function creates an item identifier list and invokes the application. SEE_MASK_INVOKEIDLIST overrides SEE_MASK_IDLIST.
SEE_MASK_NOCLOSEPROCESS	Leave the process running after the ShellExecuteEx function exits. The hProcess member receives the handle of the process.
hwnd

Handle to the parent window for any message boxes that the system may produce while executing this function (for example, for error reporting).

lpVerb

Pointer to a string specifying the name of a verb. The verb specifies an action for the application to perform. This member defaults to “Open” if no verb is specified.

lpFile

Pointer to a list of null-terminated strings that specify the names of the files to open or print. The function can open an executable file or a document file. The function can print a document file. If the path is not included with a name, the current directory is assumed.

lpParameters

Pointer to a null-terminated string containing the application parameters. The parameters must be separated by spaces. To include double quotation marks, you must enclose the marks in double quotation marks, as in the following example:

sei.lpParameters = "An example: \"\"\"quoted text\"\"\"";

In this case, the application receives three parameters: An, example:, and “quoted text”.

If lpFile specifies a document file, lpParameters should be NULL.

lpDirectory

Pointer to a null-terminated string that specifies the name of the working directory. If this member is not specified, the current directory is used as the working directory.

nShow

Show flags. Can be one of the SW_ values described for the ShowWindow function. If lpFile specifies an executable file, nShow specifies how the application is to be shown when it is opened. If lpFile specifies a document file, nShow should be zero.

hInstApp

Handle to the instance of the application that was started or an error value if the application could not be started. (This handle could also be the handle of a dynamic data exchange [DDE] server application.) This member is set on return. Error values can be one of the following:

Value	Meaning
SE_ERR_FNF	File not found
SE_ERR_PNF	Path not found
SE_ERR_ACCESSDENIED	Access denied
SE_ERR_OOM	Out of memory
SE_ERR_DLLNOTFOUND	Dynamic-link library not found
SE_ERR_SHARE	Cannot share open file
SE_ERR_ASSOCINCOMPLETE	File association information not complete
SE_ERR_DDETIMEOUT	DDE operation timed out
SE_ERR_DDEFAIL	DDE operation failed
SE_ERR_DDEBUSY	DDE operation busy
SE_ERR_NOASSOC	File association not available
lpIDList

Pointer to an ITEMIDLIST structure that contains an item identifier list that uniquely identifies the file to execute. Ignored if fMask is not set to SEE_MASK_IDLIST.

lpClass

Pointer to a null-terminated string specifying the name of a file class or a globally unique identifier (GUID). Ignored if fMask is not set to SEE_MASK_CLASSNAME.

hkeyClass

Handle to the registry key for the file class. Ignored if fMask is not set to SEE_MASK_CLASSKEY.

dwHotKey

Hot key to associate with the application. The low-order word is the virtual-key code, and the high-order word is a modifier flag (HOTKEYF_). For a list of modifier flags, see the description of the WM_SETHOTKEY message. Ignored if fMask is not set to SEE_MASK_HOTKEY.

hIcon

Handle to the icon for the file class. Ignored if fMask is not set to SEE_MASK_ICON.

hProcess

Handle to the newly started application. This member is set on return and is always NULL if fMask is not set to SEE_MASK_NOCLOSEPROCESS.

See Also

ITEMIDLIST, ShellExecuteEx, ShowWindow, WM_SETHOTKEY


SHFILEINFO

Contains information about a file object.

typedef struct _SHFILEINFO { // shfi

    HICON hIcon;

    int   iIcon;

    DWORD dwAttributes;

    char  szDisplayName[MAX_PATH];

    char  szTypeName[80];

} SHFILEINFO;

Members

hIcon

Handle of the icon that represents the file.

iIcon

Index of the icon image within the system image list.

dwAttributes

Array of flags that indicates the attributes of the file object. For information about the flags, see the description of the IShellFolder::GetAttributesOf method.

szDisplayName

String that contains the name of the file as it appears in the Windows shell, or path and filename of the file that contains the icon representing the file.

szTypeName

String that describes the type of the file.

Remarks

This structure is used with the SHGetFileInfo function.

See Also

IShellFolder::GetAttributesOf, SHGetFileInfo


SHFILEOPSTRUCT

Contains information that the SHFileOperation function uses to perform file operations.

typedef struct _SHFILEOPSTRUCT { // shfos

    HWND         hwnd;

    UINT         wFunc;

    LPCSTR       pFrom;

    LPCSTR       pTo;

    FILEOP_FLAGS fFlags;

    BOOL         fAnyOperationsAborted;

    LPVOID       hNameMappings;

    LPCSTR       lpszProgressTitle;

} SHFILEOPSTRUCT, FAR *LPSHFILEOPSTRUCT;

Members

hwnd

Handle of the dialog box to use to display information about the status of the operation.

wFunc

Operation to perform. This member can be one of the following values:

FO_COPY	Copies the files specified by pFrom to the location specified by pTo.
FO_DELETE	Deletes the files specified by pFrom (pTo is ignored).
FO_MOVE	Moves the files specified by pFrom to the location specified by pTo.
FO_RENAME	Renames the files specified by pFrom.
pFrom

Pointer to a buffer that specifies one or more source file names. Multiple names must be null-separated. The list of names must be double null-terminated.

pTo

Pointer to a buffer that contains the name of the destination file or directory. The buffer can contain mutiple destination file names if the fFlags member specifies FOF_MULTIDESTFILES. Multiple names must be null-separated. The list of names must be double null-terminated.

fFlags

Flags that control the file operation. This member can be a combination of the following values:

FOF_ALLOWUNDO	Preserves undo information, if possible.
FOF_CONFIRMMOUSE	Not implemented.
FOF_FILESONLY	Performs the operation only on files if a wildcard filename (*.*) is specified.
FOF_MULTIDESTFILES	Indicates that the pTo member specifies multiple destination files (one for each source file) rather than one directory where all source files are to be deposited.
FOF_NOCONFIRMATION	Responds with “yes to all” for any dialog box that is displayed.
FOF_NOCONFIRMMKDIR	Does not confirm the creation of a new directory if the operation requires one to be created.
FOF_RENAMEONCOLLISION	Gives the file being operated on a new name (such as “Copy #1 of...”) in a move, copy, or rename operation if a file of the target name already exists.
FOF_SILENT	Does not display a progress dialog box.
FOF_SIMPLEPROGRESS	Displays a progress dialog box, but does not show the filenames.
FOF_WANTMAPPINGHANDLE	Fills in the hNameMappings member. The handle must be freed by using the SHFreeNameMappings function.
fAnyOperationsAborted

Value that receives TRUE if the user aborted any file operations before they were completed or FALSE otherwise.

hNameMappings

Handle of a filename mapping object that contains an array of SHNAMEMAPPING structures. Each structure contains the old and new path names for each file that was moved, copied, or renamed. This member is used only if fFlags includes FOF_WANTMAPPINGHANDLE.

lpszProgressTitle

Pointer to a string to use as the title for a progress dialog box. This member is used only if fFlags includes FOF_SIMPLEPROGRESS.

Remarks

If pFrom or pTo are unqualified names, the current directories are taken from the global current drive and directory settings as managed by the GetCurrentDirectory and SetCurrentDirectory functions.

See Also

GetCurrentDirectory, SetCurrentDirectory, SHFileOperation, SHFreeNameMappings, SHNAMEMAPPING


SHITEMID

Defines an item identifier.

typedef struct _SHITEMID {       // mkid

    USHORT cb;       // size of identifier, including cb itself

    BYTE   abID[1];  // variable length item identifier

} SHITEMID, * LPSHITEMID;

typedef const SHITEMID  * LPCSHITEMID;


SHNAMEMAPPING

Contains the old and new path names for each file that was moved, copied, or renamed by the SHFileOperation function.

typedef struct _SHNAMEMAPPING { // shnm

    LPSTR pszOldPath; // address of old path name

    LPSTR pszNewPath; // pointer to new path name

    int   cchOldPath; // number of characters in old path name

    int   cchNewPath; // number of characters in new path name

} SHNAMEMAPPING, FAR *LPSHNAMEMAPPING;

See Also

SHFileOperation, SHFILEOPSTRUCT


SID

The SID structure is a variable-length structure used to uniquely identify users or groups. SID stands for security identifier.

Applications are not to modify the SID structure directly. To create and manipulate a security identifier, use the functions listed in the See Also section.

typedef PVOID PSID;

See Also

AllocateAndInitializeSid, CopySid, EqualSid, FreeSid, GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthority, GetSidSubAuthorityCount, InitializeSid, IsValidSid, LookupAccountName, LookupAccountSid


SID_AND_ATTRIBUTES

The SID_AND_ATTRIBUTES structure represents a security identifier (SID) and its attributes. SIDs are used to uniquely identify users or groups.

typedef struct _SID_AND_ATTRIBUTES { // saa

    PSID  Sid;

    DWORD Attributes;

} SID_AND_ATTRIBUTES ;

Members

Sid

Points to a SID structure.

Attributes

Specifies attributes of the SID. This value contains up to 32 one-bit flags. Its meaning depends on the definition and use of the SID.

Remarks

A group is represented by a SID. SIDs have attributes that indicate whether they are currently enabled, disabled, or mandatory, and how they are used. A SID_AND_ATTRIBUTES structure can represent a SID whose attributes change frequently. For example, it is used to represent groups in the TOKEN_GROUPS structure.

See Also

SID, TOKEN_GROUPS, TOKEN_USER


SID_IDENTIFIER_AUTHORITY

The SID_IDENTIFIER_AUTHORITY structure represents the top-level authority of a security identifier (SID).

typedef struct _SID_IDENTIFIER_AUTHORITY { // sia

    BYTE Value[6];

} SID_IDENTIFIER_AUTHORITY ;

Members

Value

An array of six bytes specifying a SID’s top-level authority.

Remarks

The identifier authority value identifies the agency that issued the SID. Some identifier authorities are predefined:

Identifier authority	Value
SECURITY_NULL_SID_AUTHORITY	0
SECURITY_WORLD_SID_AUTHORITY	1
SECURITY_LOCAL_SID_AUTHORITY	2
SECURITY_CREATOR_SID_AUTHORITY	3
SECURITY_NT_AUTHORITY	5
A SID must contain a top-level authority and at least one relative identifier (RID) value.

See Also

AllocateAndInitializeSid, GetSidIdentifierAuthority, InitializeSid, SID


SINGLE_LIST_ENTRY

The SINGLE_LIST_ENTRY structure is available for any entry in a single-linked list.

typedef struct _SINGLE_LIST_ENTRY { // sle

    struct _SINGLE_LIST_ENTRY *Next;

} SINGLE_LIST_ENTRY;

Members

Next

Points to the next entry in a single-linked list.

Remarks

This structure can be used as the beginning of a single-linked list or as any subsequent entry in the list.


SIZE

The SIZE structure specifies the width and height of a rectangle.

typedef struct tagSIZE { // siz

    LONG cx;

    LONG cy;

} SIZE;

Members

cx

Specifies the rectangle’s width.

cy

Specifies the rectangle’s height.

Remarks

The rectangle dimensions stored in this structure may correspond to viewport extents, window extents, text extents, bitmap dimensions, or the aspect-ratio filter for some extended functions.

See Also

GetAspectRatioFilterEx, GetBitmapDimensionEx, GetTextExtentPoint32, GetViewportExtEx, GetWindowExtEx, ScaleViewportExtEx, ScaleWindowExtEx, SetBitmapDimensionEx, SetViewportExtEx, SetWindowExtEx


SMALL_RECT

The SMALL_RECT structure defines the coordinates of the upper left and lower right corners of a rectangle.

typedef struct _SMALL_RECT { // srct

    SHORT Left;

    SHORT Top;

    SHORT Right;

    SHORT Bottom;

} SMALL_RECT;

Members

Left

Specifies the x-coordinate of the upper left corner of the rectangle.

Top

Specifies the y-coordinate of the upper left corner of the rectangle.

Right

Specifies the x-coordinate of the lower right corner of the rectangle.

Bottom

Specifies the y-coordinate of the lower right corner of the rectangle.

Remarks

This structure is used by console functions to specify rectangular areas of console screen buffers, where the coordinates specify the rows and columns of screen-buffer character cells.

See Also

RECT, RECTL


SOARCINFO

Contains information defining the arc to be drawn.

typedef struct SOARCINFOtag {

    SORECT Rect;        // see below

    SOANGLE StartAngle; // see below

    SOANGLE EndAngle;   // see below

} SOARCINFO, VWPTR *PSOARCINFO;

Members

Rect

Rectangle that bounds the ellipse containing the arc.

StartAngle

Angle specifying the starting point of the arc. The angle is defined in tenths of a degree, counterclockwise from the positive x-axis. To set this member, use the SOANGLETENTHS macro.

EndAngle

Angle specifying the ending point of the arc. The angle is defined in tenths of a degree, counterclockwise from the positive x-axis. To set this member, use the SOANGLETENTHS macro.


SOBITMAPHEADER

Contains information about the bitmap to be output.

typedef struct SOBITMAPHEADERtag {

    WORD wStructSize;   // see below

    WORD wImageFlags;   // see below

    WORD wImageWidth;   // see below

    WORD wImageLength;  // see below

    WORD wTileWidth;    // see below

    WORD wTileLength;   // see below

    WORD wBitsPerPixel; // see below

    WORD wNPlanes;      // see below

    WORD wHDpi;         // see below

    WORD wVDpi;         // see below

} SOBITMAPHEADER, VWPTR *PSOBITMAPHEADER;

Members

wStructSize

Size, in bytes, of the structure.

wImageFlags

Image flags. This member can be a combination of one (and only one) color format value and other attribute values.

The color format can be one of these values:

SO_BGRCOLOR	Pixel values are RGB color values (24-bit only); bytes are stored consecutively in the order B,G,R.
SO_BLACKANDWHITE	Pixels are black or white (1 bit per pixel only).
SO_COLORPALETTE	Pixel values are indexes into the color palette for the bitmap.
SO_GRAYSCALE	Pixel values are gray scale values.
SO_RGBCOLOR	Pixel values are RGB color values (24-bit only); bytes are stored consecutively in the order R,G,B.
Other attributes can be a combination of these values:

SO_BOTTOMTOTOP	The image is provided in scan lines from the bottom up. The default is top to bottom.
SO_WHITEZERO	For gray scale images and black and white images only, a pixel with a value of zero is a white pixel, and increasing pixel values become darker. By default, a value of zero is defined as a black pixel with increasing values becoming lighter.
wImageWidth

Horizontal width, in pixels, of the image.

wImageLength

Vertical length, in pixels, of the image.

wTileWidth

Horizontal width, in pixels, of the tile.

wTileLength

Vertical length, in pixels, of the tile.

wBitsPerPixel

Number of consecutive bits that define the pixel color. The number is currently limited to 1, 4, 8, or 24.

wNPlanes

Color planes. This member must be 1.

wHDpi

Horizontal resolution, in pixels per inch, of the display on which the image originated. If the resolution is not known, this member can be zero.

wVDpi

Vertical resolution, in pixels per inch, of the display on which the image originated. If the resolution is not known, this member can be zero.


SOBORDER

Contains information about the border around a cell in table.

typedef struct SOBORDERtag {
    WORD wWidth;         // see below
    SOCOLORREF rgbColor; // see below
    WORD wFlags;         // see below
} SOBORDER, VWPTR * PSOBORDER;

Members

wWidth

Width, in twips, of the border.

rgbColor

Color of the border. This member can be a RGB color value. To set this member, use the SORGB macro.

wFlags

Type of border and the edges to which it applies. This member can be a combination of the SO_BORDERNONE, SO_BORDERDOUBLE, SO_BORDERHAIRLINE, SO_BORDERTHICK, SO_BORDERSHADOW, and SO_BORDERDOTTED values.


SOCOLUMN

Contains information about the columns in a spreadsheet.

typedef struct SOCOLUMNtag {

    WORD wStructSize; // see below

    LONG dwWidth;     // see below

    char szName[40];  // see below

} SOCOLUMN, VWPTR * PSOCOLUMN;

Members

wStructSize

Size, in bytes, of the structure.

dwWidth

Width, in characters, of the column.

szName

Null-terminated string specifying the name of the column.


SOCPARCANGLE

Contains information defining an arc for use in vector graphics output.

typedef struct SOCPARCANGLEtag {

    SOPOINT Center;     // center point

    SOANGLE SweepAngle; // sweep angle

} SOCPARCANGLE, VWPTR *PSOCPARCANGLE;


SOCPPIEANGLE

Contains information defining a pie shape for use in vector graphics output.

typedef struct SOCPPIEANGLEtag {

    INT nRadius;        // radius

    SOANGLE StartAngle; // starting angle

    SOANGLE SweepAngle; // sweep angle

} SOCPPIEANGLE, VWPTR *PSOCPPIEANGLE;


SOCPTEXTATPOINT

Contains information defining the format and length of text for use in vector graphics output.

typedef struct SOCPTEXTATPOINTtag {

    WORD wFormat;    // format of text

    INT nTextLength; // text length

} SOCPTEXTATPOINT, VWPTR *PSOCPTEXTATPOINT;


SODATACELL

Contains information about the data to be placed in a cell of a spreadsheet.

typedef struct SODATACELLtag {

    WORD wStructSize;   //see below

    WORD wStorage;      //see below

    WORD wDisplay;      //see below

    DWORD dwSubDisplay; //see below

    WORD wPrecision;    //see below

    WORD wAlignment;    //see below

    WORD wAttribute;    //see below

    union {

        SOINT32S Int32S; //see below

        SOINT32U Int32U; //see below

        BYTE IEEE4[4];   //see below

        BYTE IEEE8[8];   //see below

        BYTE IEEE10[10]; //see below

        BYTE BCD8[8];    //see below

    } uStorage;

} SODATACELL, VWPTR * PSODATACELL;

Members

wStructSize

Size, in bytes, of the structure.

wStorage

Storage type. This member can be one of these values:

SO_CELLBCD8I	Packed BCD excess-63.
SO_CELLEMPTY	The cell is empty.
SO_CELLERROR	The cell has an error condition.
SO_CELLIEEE4I	IEEE 4-byte in Intel® (PC) ordering.
SO_CELLIEEE8I	IEEE 8-byte in Intel (PC) ordering.
SO_CELLIEEE10I	IEEE 10-byte in Intel (PC) ordering.
SO_CELLINT32S	32-bit signed integer.
SO_CELLINT32U	32-bit unsigned integer.
wDisplay

Display type. This member can be one of these values:

SO_CELLBOOL	Boolean (0 = FALSE and 1 = TRUE).
SO_CELLDATE	Julian Days since the base date. wStorage may be either an IEEE or integer value.
SO_CELLDATETIME	Julian Days since the base date. wStorage may be either an IEEE or integer value.
SO_CELLDECIMAL	Decimal notation.
SO_CELLDOLLARS	Dollar sign.
SO_CELLEXPONENT	Exponential notation.
SO_CELLNUMBER	General number format.
SO_CELLPERCENT	Percent (not constrained to 0 − 100).
SO_CELLTIME	Decimal part of a day if wStorage is an IEEE value or seconds since 00:00 if wStorage is an integer value.
dwSubDisplay

Display subtype. The values depend on wDisplay value.

For SO_CELLNUMBER and SO_CELLDOLLARS, this member can be a combination of one negative-number format, thousands separator, and cell multiplier.

Negative Number Format
SO_CELLNEG_MINUS	Negative numbers have a minus sign.
SO_CELLNEG_MINUSRED	Negative numbers have a minus sign and are red.
SO_CELLNEG_PAREN	Negative numbers have parentheses.
SO_CELLNEG_PARENRED	Negative numbers have parentheses and are red.
Thousands Separator
SO_CELL1000SEP_COMMA	Commas as 1,000s separator.
SO_CELL1000SEP_NONE	No 1000s separator.
Cell Multiplier
SO_CELLMULT_1	Used for all file parsers.
SO_CELLMULT_01	Used only for Microsoft® Excel viewer.
SO_CELLMULT_05	Used only for Lotus viewer.
SO_CELLMULT_005	Used only for Lotus viewer.
SO_CELLMULT_0005	Used only for Lotus viewer.
SO_CELLMULT_00005	Used only for Lotus viewer.
SO_CELLMULT_500	Used only for Lotus viewer.
SO_CELLMULT_5000	Used only for Lotus viewer.
SO_CELLMULT_0625	Used only for Lotus viewer.
SO_CELLMULT_015625	Used only for Lotus viewer.
For SO_CELLDATETIME, SO_CELLDATE, and SO_CELLTIME, this member can be a combination of one date separator, day format, month format, year format, day of week format, and time format.

Date Separator
SO_CELLDATESEP_MINUS
SO_CELLDATESEP_NONE
SO_CELLDATESEP_PERIOD
SO_CELLDATESEP_SPACE
Day Format
SO_CELLDAY_NONE
SO_CELLDAY_NUMBER
Month Format
SO_CELLMONTH_ABBREV
SO_CELLMONTH_FULL
SO_CELLMONTH_NONE
SO_CELLMONTH_NUMBER
Year Format
SO_CELLYEAR_ABBREV
SO_CELLYEAR_FULL
SO_CELLYEAR_NONE
Day of Week Format
SO_CELLDAYOFWEEK_ABBREV
SO_CELLDAYOFWEEK_FULL
SO_CELLDAYOFWEEK_NONE
Time Format
SO_CELLTIME_HHMM24
SO_CELLTIME_HHMMAM
SO_CELLTIME_HHMMHMS	For example, 14h45m
SO_CELLTIME_HHMMSS24
SO_CELLTIME_HHMMSSAM
SO_CELLTIME_HHMMSSHMS	For example, 14h45m34s
SO_CELLTIME_NONE
wPrecision

Precision or positioning value, depending on the wDisplay value.

For SO_CELLNUMBER and SO_CELLDOLLARS, this member specifies the number of places to the right of the decimal point.

For SO_CELLDATETIME, SO_CELLDATE, and SO_CELLTIME, this member specifies the position in the date time string of each element. It must be a combination of one value for each of the day of week position, month position, day position, year position, and time position.

Day of Week Position
SO_CELLDAYOFWEEK_1
SO_CELLDAYOFWEEK_2
SO_CELLDAYOFWEEK_3
SO_CELLDAYOFWEEK_4
SO_CELLDAYOFWEEK_5
Month Position
SO_CELLMONTH_1
SO_CELLMONTH_2
SO_CELLMONTH_3
SO_CELLMONTH_4
SO_CELLMONTH_5
Day Position
SO_CELLDAY_1
SO_CELLDAY_2
SO_CELLDAY_3
SO_CELLDAY_4
SO_CELLDAY_5
Year Position
SO_CELLYEAR_1
SO_CELLYEAR_2
SO_CELLYEAR_3
SO_CELLYEAR_4
SO_CELLYEAR_5
Time Position
SO_CELLTIME_1
SO_CELLTIME_2
SO_CELLTIME_3
SO_CELLTIME_4
SO_CELLTIME_5
wAlignment

Alignment of data in the cell. This member can be the SO_CELLLEFT, SO_CELLRIGHT, or SO_CELLCENTER value.

wAttribute

Attribute of data in the cell. This member can be a combination of the SO_CELLBOLD, SO_CELLITALIC, SO_CELLUNDERLINE, and SO_CELLSTRIKEOUT values.

Int32S

Signed 32-bit integer.

Int32U

Unsigned 32-bit integer.

IEEE4

Four-byte array representing an IEEE 4-byte floating-point number.

IEEE8

Eight-byte array representing an IEEE 8-byte floating-point number.

IEEE10

Ten-byte array representing an IEEE 10-byte floating-point number.

BCD8

Eight-byte array representing an excess-63 floating-point packed BCD.


SOEMBEDDEDGRAPHIC

Contains information about the size and positioning of an embedded graphics object.

typedef struct SOEMBEDDEDGRAPHICtag {

    SOPOINT Size;       // see below

    SORECT Crop;        // see below

    SOPOINT ScaledSize; // see below

    WORD wBorder;       // see below

    DWORD dwFlags;      // see below

} SOEMBEDDEDGRAPHIC;

Members

Size

Initial size of the image before scaling and cropping.

Crop

Cropping amount on the top, bottom, left, and right edges.

ScaledSize

Final size of the image after scaling and cropping.

wBorder

Border thickness, in twips. If this member is zero, there is no border.

dwFlags

Flags. This member can be a combination of these values:

SO_CENTERIMAGE	The image is centered in its final rectangle.
SO_MAINTAINASPECT	The image aspect ratio is preserved.


SOEMBEDDEDOBJECT

Contains information about an embedded object.

typedef struct SOEMBEDDEDOBJECTtag {

    WORD wStructSize;   // see below

    WORD wObjectType;   // see below

    char szFile[144];   // see below

    WORD wFIType;       // see below

    DWORD dwFileOffset; // see below

    SOEMBEDINFO Info;   // see below

} SOEMBEDDEDOBJECT, VWPTR * PSOEMBEDDEDOBJECT;

Members

wStructSize

Size, in bytes, of the structure.

wObjectType

Type of object type. This member can be the SOEMBED_GRAPHIC or SO_UNKNOWN value.

szFile

Null-terminated string specifying the path and filename of the file that contains the object. If the object is in the current file, this member is NULL.

wFIType

File identifier for object’s file. If the object type is the SO_UNKNOWN value, this member is zero.

dwFileOffset

Offset, in bytes, to the embedded object from the start of the given file.

Info

Union containing object-specific information.


SOEMBEDINFO

Contains information specific to embedded graphics objects.

typedef union SOEMBEDINFOtag {
    SOEMBEDDEDGRAPHIC Graphic; // embedded graphics structure
} SOEMBEDINFO;


SOFIELD

Contains information about a field in a database.

typedef struct SOFIELDtag {

    WORD wStructSize;

    LONG dwWidth;

    char szName[40];

    WORD wStorage;

    WORD wDisplay;

    DWORD dwSubDisplay;

    WORD wPrecision;

    WORD wAlignment;

} SOFIELD, VWPTR * PSOFIELD;

Members

wStructSize

Size, in bytes, of the structure.

dwWidth

Width, in characters, of the column.

szName

Null-terminated string specifying the name of the field.

wStorage

Storage type. This member can be one of these values:

SO_CELLBCD8I	Packed BCD excess-63.
SO_CELLEMPTY	The cell is empty.
SO_CELLERROR	The cell has an error condition.
SO_CELLIEEE4I	IEEE 4-byte in Intel (PC) ordering.
SO_CELLIEEE8I	IEEE 8-byte in Intel (PC) ordering.
SO_CELLIEEE10I	IEEE 10-byte in Intel (PC) ordering.
SO_CELLINT32S	32-bit signed integer.
SO_CELLINT32U	32-bit unsigned integer.
SO_FIELDTEXTFIX	The field contains a string of fixed length.
SO_FIELDTEXTVAR	The field contains a string of unknown length.
wDisplay

Display type. For more information, see the wDisplay member in the SODATACELL structure.

dwSubDisplay

Display subtype. For more information, see the dwSubDisplay member in the SODATACELL structure.

wPrecision

Precision or positioning value. For more information, see the wPrecision member in the SODATACELL structure.

If wStorage is the SO_FIELDTEXTFIX value, this member specifies the number of characters in the string.

wAlignment

Alignment of data in the cell. This member can be the SO_CELLLEFT, SO_CELLRIGHT, or SO_CELLCENTER value.


SOFILTERINFO

Contains information identifying the file parser.

typedef struct SOFILTERINFOtag {

    INT wFilterCharSet;      // see below

    U_BYTE szFilterName[32]; // see below

} SOFILTERINFO;

Members

wFilterCharSet

Character set used for text by the file parser. This member must be the SO_WINDOWS value.

szFilterName

Null-terminated string specifying the name of the file parser. The name should identify either the format of the files being parsed or the product that created the files.


SOGROUPINFO

Contains information about a group for use with vector graphics output.

typedef struct SOGROUPINFOtag {

    WORD wStructSize;    // see below

    SORECT BoundingRect; // see below

    INT nTransforms;     // see below

} SOGROUPINFO, VWPTR *PSOGROUPINFO;

Members

wStructSize

Size, in bytes, of the structure.

BoundingRect

Rectangle that bounds all points displayed in the group. This rectangle does not cause clipping to occur. If clipping is needed, a clipping path must be selected.

nTransforms

Number of transformation structures following this structure.


SOLOGBRUSH

Contains information defining a logical brush for use with vector graphics output.

typedef struct SOLOGBRUSHtag {

    WORD lbStyle;       // see below

    SOCOLORREF lbColor; // see below

    INT lbHatch;        // see below

} SOLOGBRUSH, VWPTR *PSOLOGBRUSH;

Members

lbStyle

Brush style. This member can be the SOBS_HATCHED, SOBS_HOLLOW, or SOBS_SOLID value.

lbColor

Color of the brush. This member can be an RGB or palette-relative value. To set this member, use the SORGB or SOPALETTERGB macro.

lbHatch

Hatch style. This member is used only if lbStyle is SO_HATCHED. This member can be the SOHS_BDIAGONAL, SOHS_CROSS, SOHS_DIAGCROSS, SOHS_FDIAGONAL, SOHS_HORIZONTAL, or SOHS_VERTICAL value.

For a complete definition of the members, see the LOGBRUSH structure.


SOLOGFONT

Contains information that defines a logical font for use with vector graphics output. The lfHeight and lfWidth members must be in the same logical units as all of the other drawing commands. For a description of the members, see the LOGFONT structure.

typedef struct SOLOGFONTtag {
    INT lfHeight;                   // font height

    INT lfWidth;                    // font width

    INT lfEscapement;               // angle of text line

    INT lfOrientation;              // angle of character baseline

    INT lfWeight;                   // font weight

    BYTE lfItalic;                  // italics

    BYTE lfUnderline;               // underline

    BYTE lfStrikeOut;               // strikeout

    BYTE lfCharSet;                 // character set

    BYTE lfOutputPrecision;         // output precision

    BYTE lfClipPrecision;           // clipping precision

    BYTE lfQuality;                 // output quality

    BYTE lfPitchAndFamily;          // pitch and family of font

    BYTE lfFaceName[SOLF_FACESIZE]; // typeface name of font

} SOLOGFONT, VWPTR *PSOLOGFONT;


SOLOGPEN

Contains information that defines a logical pen for use with vector graphics output. For a complete definition of the members, see the LOGPEN structure.

typedef struct SOLOGPENtag {

    INT loPenStyle;     // see below

    SOPOINT loWidth;    // see below

    SOCOLORREF loColor; // see below

} SOLOGPEN, VWPTR *PSOLOGPEN;

Memebers

loPenStyle

Pen Style. This member can be the SOPS_SOLID, SOPS_DASH, SOPS_DOT, SOPS_DASHDOT, SOPS_DASHDOTDOT, SOPS_NULL, or SOPS_INSIDEFRAME value.

loWidth

Width, in logical units, of the pen. The x member in the POINT structure is used, and the y member is ignored.

loColor

Color of the brush. This member can be an RGB or palette-relative value. To set this member, use the SORGB or SOPALETTERGB macro.


SOPARAINDENTS

Contains information about paragraph indents for use with vector graphics output.

typedef struct SOPARAINDENTStag {

    INT FirstLineIndent; // see below

    INT LeftIndent;      // see below

    INT RightIndent;     // see below

} SOPARAINDENTS, VWPTR *PSOPARAINDENTS;

Members

FirstLineIndent

Distance, from the left edge of the frame, to indent the first line of each paragraph.

LeftIndent

Distance, from the left edge of the frame, to indent all lines but the the first line of each paragraph.

RightIndent

Distance, from the right edge of the frame, to indent all lines of each paragraph.


SOPATHINFO

Contains information about a path for use with vector graphics output.

typedef struct SOPATHINFOtag {

    WORD wStructSize;    // see below

    SORECT BoundingRect; // see below

    INT nTransforms;     // see below

} SOPATHINFO, VWPTR *PSOPATHINFO;

Members

wStructSize

Size, in bytes, of the structure.

BoundingRect

Rectangle that bounds all points displayed in the path. This rectangle does not cause clipping to occur. If clipping is needed, a clipping path must be selected.

nTransforms

Number of transformation structures following this structure.


SOPOINT

Contains coordinates for a point.

typedef struct SOPOINTtag {

    INT x;  // x-coordinate

    INT y;  // y-coordinate

} SOPOINT, VWPTR *PSOPOINT;


SOPOLYINFO

Contains information about the type and number of vertices of a polyline, polygon, spline, or Bezier curve.

typedef struct SOPOLYINFOtag {

    WORD wFormat; // see below

    INT nPoints;  // see below

} SOPOLYINFO, VWPTR *PSOPOLYINFO;

Members

wFormat

Format type. This member can be one of these values:

SOPT_BEZIERCLOSE	SOPT_POLYGON
SOPT_BEZIEROPEN	SOPT_POLYLINE
SOPT_CPPOLYGON	SOPT_SPLINECLOSE
SOPT_CPPOLYLINE	SOPT_SPLINEOPEN
nPoints

Number of vertices in the object.


SORECT

Contains the dimensions of a rectangle.

typedef struct SORECTtag {

    INT left;    // x-coordinate of upper left corner

    INT top;     // y-coordinate of upper left corner

    INT right;   // x-coordinate of lower right corner

    INT bottom;  // y-coordinate of lower right corner

} SORECT, VWPTR *PSORECT;


SOTAB

Contains information about tab stops.

typedef struct SOTABtag {

    WORD wType;    // see below

    WORD wChar;    // see below

    WORD wLeader;  // see below

    LONG dwOffset; // see below

} SOTAB, VWPTR * PSOTAB;

Members

wType

Type of tab stop. This member can be the SO_TABLEFT, SO_TABRIGHT, SO_TABCENTER, or SO_TABCHAR value.

wChar

Alignment character if wType is SO_TABCHAR. Tabs are aligned on this character.

wLeader

Repeating leader character for the tab. If this member is zero, there is no leader.

dwOffset

Offset of the tab from the left page margin.


SOTABLECELLINFO

Contains information about cells in a table.

typedef struct SOTABLECELLINFOtag {

    WORD wWidth;             // see below

    WORD wMerge;             // see below

    WORD wShading;           // see below

    PSOBORDER pLeftBorder;   // see below

    PSOBORDER pRightBorder;  // see below

    PSOBORDER pTopBorder;    // see below

    PSOBORDER pBottomBorder; // see below

} SOTABLECELLINFO, VWPTR *PSOTABLECELLINFO;

Members

wWidth

Width, in twips, of the cell.

wMerge

Merge flag specifying whether the cell is merged with any neighboring cells. This member can be a combination of the SO_MERGELEFT, SO_MERGERIGHT, SO_MERGEABOVE, and SO_MERGEBELOW values.

wShading

Intensity value for background shading in the range of 0 to 255. If this member is zero, there is no background shading.

pLeftBorder

Left border.

pRightBorder

Right border.

pTopBorder

Top border.

pBottomBorder

Bottom border.


SOTEXTATARCANGLE

Contains information about text for use with vector graphics output.

typedef struct SOTEXTATARCANGLEtag {

    SOARCINFO ArcInfo; // see below

    WORD wFormat;      // see below

    INT nTextLength;   // see below

} SOTEXTATARCANGLE, VWPTR *PSOTEXTATARCANGLE;

Members

ArcInfo

Arc information defining the arc relative to which the text is located. Only the starting angle is used to locate the point; the ending angle is ignored.

wFormat

Alignment format, indicating the relationship between the given point and the base line or bounding rectangle of the text. This member can be a combination of these values:

SOTA_BASELINE	Aligns the point and base line of the font.
SOTA_BOTTOM	Aligns the point and bottom of the bounding rectangle.
SOTA_CENTER	Aligns the point and horizontal center of the bounding rectangle.
SOTA_LEFT	Aligns the point and left side of the bounding rectangle.
SOTA_RIGHT	Aligns the point and right side of the bounding rectangle.
SOTA_TOP	Aligns the point and top of the bounding rectangle.
nTextLength

Length of text string that follows the structure.


SOTEXTATPOINT

Contains information about text at a point.

typedef struct SOTEXTATPOINTtag {

    SOPOINT Point;   // see below

    WORD wFormat;    // see below

    INT nTextLength; // see below

} SOTEXTATPOINT, VWPTR *PSOTEXTATPOINT;

Members

Point

Point that locates the text.

wFormat

Alignment format, indicating the relationship between the point and the base line or bounding rectangle of the text. This member can be a combination of these values:

SOTA_BASELINE	Aligns the point and base line of the font.
SOTA_BOTTOM	Aligns the point and bottom of the bounding rectangle.
SOTA_CENTER	Aligns the point and horizontal center of the bounding rectangle.
SOTA_LEFT	Aligns the point and left side of the bounding rectangle.
SOTA_RIGHT	Aligns the point and right side of the bounding rectangle.
SOTA_TOP	Aligns the point and top of the bounding rectangle.
nTextLength

Length of the text string that follows the structure.


SOTEXTCELL

Contains information about the alignment and attributes of text in a spreadsheet cell.

typedef struct SOTEXTCELLtag {

    WORD wStructSize; // see below

    WORD wAlignment;  // see below

    WORD wAttribute;  // see below

} SOTEXTCELL, VWPTR * PSOTEXTCELL;

Members

wStructSize

Size, in bytes, of the structure.

wAlignment

Alignment. This member can be the SO_CELLLEFT, SO_CELLRIGHT, SO_CELLCENTER, or SO_CELLFILL value.

wAttribute

Attributes. This member can be a combination of the SO_CELLBOLD, SO_CELLITALIC, SO_CELLUNDERLINE, and SO_CELLSTRIKEOUT values.


SOTEXTINRECT

Contains information about text for use with vector graphics output.typedef struct SOTEXTINRECTtag {

    SORECT Rect;     // see below

    WORD wFormat;    // see below

    INT nTextLength; // see below

} SOTEXTINRECT, VWPTR *PSOTEXTINRECT;

Members

Rect

Rectangle in which text is formatted.

wFormat

Format of the string. This member can be a combination of these values:

SODT_BOTTOM	SODT_NOPREFIX
SODT_CALCRECT	SODT_RIGHT
SODT_CENTER	SODT_SINGLELINE
SODT_EXPANDTABS	SODT_TABSTOP
SODT_EXTERNALLEADING	SODT_TOP
SODT_LEFT	SODT_VCENTER
SODT_NOCLIP	SODT_WORDBREAK
nTextLength

Length of the text string that follows the structure.


SOTRANSFORM

Contains information about a transformation for use with vector graphics output.

typedef struct SOTRANSFORMtag {

    WORD wTransformFlags;  // see below

    SOPOINT Origin;        // see below

    INT xOffset;           // see below

    INT yOffset;           // see below

    SORATIO xScale;        // see below

    SORATIO yScale;        // see below

    SORATIO xSkew;         // see below

    SORATIO ySkew;         // see below

    SOANGLE RotationAngle; // see below

} SOTRANSFORM, VWPTR *PSOTRANSFORM;

Members

wTransformFlags

Type of transformation. This member can be a combination of these values:

SOTF_NOTRANSFORM	SOTF_XSKEW
SOTF_ROTATE	SOTF_YOFFSET
SOTF_XOFFSET	SOTF_YSCALE
SOTF_XSCALE	SOTF_YSKEW
TSOTF_ROTATE may be combined only with SOTF_XOFFSET and SOTF_YOFFSET. In addition, no other values may be combined with SOTF_NOTRANSFORM.

Origin

Point of origin for all transformations, except for SOTF_XOFFSET and SOTF_YOFFSET.

xOffset and yOffset

Offset values to use for the SOTF_XOFFSET and OTF_YOFFSET transformations. The x and y members of this value are added to the x- and y-coordinates of all points in the transformed object.

xScale

Ratio to use for SOTF_XSCALE transformations. This ratio is used to scale the image on the x-axis from the given origin. To set this member, use the SOSETRATIO macro.

yScale

Ratio to use for SOTF_YSCALE transformations. This ratio is used to scale the image on the y-axis from the given origin. To set this member, use the SOSETRATIO macro.

xSkew

Ratio to use for SOTF_XSKEW transformations. This ratio used to skew the image horizontally from the given origin. To set this member, use the SOSETRATIO macro.

ySkew

Ratio to use for SOTF_YSKEW transformations. This ratio used to skew the image vertically from the given origin. To set this member, use the SOSETRATIO macro.

RotationAngle

Angle, in tenths of a degree, to use for SOTF_ROTATE transformations. All points are rotated this many degrees about the given origin. This value must be set by using the SOANGLETENTHS macro. A SOANGLE variable should not be set directly. Additional macros will be made available as needed.

The transformation equation follows.

x' = Origin.x + (xScale * (x-Origin.x)) + (xSkew*(y-Origin.y)) + xOffset
y' = Origin.y + (yScale * (y-Origin.y)) + (ySkew*(x-Origin.x)) + yOffset


SOVECTORHEADER

Contains information defining the size and attributes of the rectangle in which vector graphics are drawn.

typedef struct SOVECTORHEADERtag {

    WORD wStructSize;    // see below

    SORECT BoundingRect; // see below

    WORD wHDPI;          // see below

    WORD wVDPI;          // see below

    WORD wImageFlags;    // see below

    SOCOLOR BkgColor;    // see below

} SOVECTORHEADER, VWPTR *PSOVECTORHEADER;

Members

wStructSize

Size, in bytes, of the structure.

BoundingRect

Rectangle that bounds all drawing commands.

wHDpI

Dots per inch resolution along the x-axis.

wVDpI

Dots per inch resolution along the y-axis.

wImageFlags

Image flags. This member can be a combination of these values:

SO_VECTORCOLORPALETTE	Uses a color palette. Color values must be palette entry indexes or palette-relative RGB values.
SO_VECTORRGBCOLOR	Uses RGB color values.
SO_XISLEFT	Has positive x-coordinates left of the y-axis.
SO_YISUP	Has positive y-coordinates up from the x-axis.
BkgColor

Color of the background in the bounding rectangle. This value must be set by using one of the three color macros: SOPALETTEINDEX, SORGB, or SOPALETTERGB. However, SORGB should not be used if a palette is defined.


SOUNDSENTRY

The SOUNDSENTRY structure contains information about the SoundSentry accessibility feature. When the SoundSentry feature is on, the computer displays a visual indication only when a sound is generated.

Windows 95: The visual indication is displayed when a sound is generated through the computer’s internal speaker.

Windows NT: The visual indication is displayed when a sound is generated through either the multimedia sound services or through the computer’s speaker.

typedef struct tagSOUNDSENTRY {     // ss

    UINT cbSize;

    DWORD dwFlags;

    DWORD iFSTextEffect;

    DWORD iFSTextEffectMSec;

    DWORD iFSTextEffectColorBits;

    DWORD iFSGrafEffect;

    DWORD iFSGrafEffectMSec;

    DWORD iFSGrafEffectColor;

    DWORD iWindowsEffect;

    DWORD iWindowsEffectMSec;

    LPTSTR lpszWindowsEffectDLL;

    DWORD iWindowsEffectOrdinal;

} SOUNDSENTRY, *LPSOUNDSENTRY;

Members

cbSize

Specifies the size, in bytes, of this structure.

dwFlags

A set of bit flags that specify properties of the SoundSentry feature. The following bit-flag values are defined:

Value	Meaning
SSF_AVAILABLE	If this flag is set, the SoundSentry feature is available.
SSF_SOUNDSENTRYON	If this flag is set, the SoundSentry feature is on.
iFSTextEffect

Windows 95: Specifies the visual signal to present when a text-mode application generates a sound while running in a full-screen virtual machine. This member can be one of the following values:

Value	Meaning
SSTF_BORDER	Flash the screen border (that is, the overscan area), which is unavailable on some displays.
SSTF_CHARS	Flash characters in the corner of the screen.
SSTF_DISPLAY	Flash the entire display.
SSTF_NONE	No visual signal.

Windows NT: This member is reserved for future use. It must be set to zero.

iFSTextEffectMSec

Windows 95: Specifies the duration, in milliseconds, of the visual signal that is displayed when a full-screen, text-mode application generates a sound.

Wndows NT: This member is reserved for future use. It must be set to zero.

iFSTextEffectColorBits

Windows 95: Specifies the RGB value of the color to be used when displaying the visual signal shown when a full-screen, text-mode application generates a sound.

Windows NT: This member is reserved for future use. It must be set to zero.

iFSGrafEffect

Windows 95: Specifies the visual signal to present when a graphics-mode application generates a sound while running in a full-screen virtual machine. This member can be one of the following values:

Value	Meaning
SSGF_DISPLAY	No visual signal.
SSGF_NONE	Flash the entire display.
Windows NT: This member is reserved for future use. It must be set to zero.

iFSGrafEffectMSec

Windows 95: Specifies the duration, in milliseconds, of the visual signal that is displayed when a full-screen, graphics-mode application generates a sound.

Windows NT: This member is reserved for future use. It must be set to zero.

iFSGrafEffectColor

Windows 95: Specifies the RGB value of the color to be used when displaying the visual signal shown when a full-screen, graphics-mode application generates a sound.

Windows NT: This member is reserved for future use. It must be set to zero.

iWindowsEffect

Specifies the visual signal to display when a sound is generated by a Windows-based application or an MS-DOS application running in a window. This member can be one of the following values:

Value	Meaning
SSWF_CUSTOM	Call the SoundSentryProc routine exported by the DLL specified by the iFSWindowsEffectDLL member.
SSWF_DISPLAY	Flash the entire display.
SSWF_NONE	No visual signal.
SSWF_TITLE	Flash the title bar of the active window.
SSWF_WINDOW	Flash the active window.
iWindowsEffectMSec

Windows 95: Specifies the duration, in milliseconds, of the visual signal that is displayed when a Windows-based application (or a non-Windows-based application running in a window) generates a sound.

Windows NT: This member is reserved for future use. It must be set to zero.

lpszWindowsEffectDLL

Points to the buffer that contains the name of the DLL that contains a SoundSentryProc callback function. The length of the name must not exceed the value of MAX_PATH. This member is NULL if no DLL is used. When retrieving information about the SoundSentry feature, the size of the buffer must be equal to, or larger than, the value of MAX_PATH.

iWindowsEffectOrdinal

This member is reserved for future use on both platforms. It must be set to zero.

Remarks

An application uses a SOUNDSENTRY structure when calling the SystemParametersInfo function with the wAction parameter set to SPI_GETSOUNDSENTRY or SPI_SETSOUNDSENTRY. When using SPI_GETSOUNDSENTRY, an application must specify the cbSize member of the SOUNDSENTRY structure; the SystemParametersInfo function fills the remaining members. An application must specify the cbSize, dwFlags, and iWindowsEffect members when using the SPI_SETSOUNDSENTRY value.

See Also

SoundSentryProc, SystemParametersInfo


STARTUPINFO

The STARTUPINFO structure is used with the CreateProcess function to specify main window properties if a new window is created for the new process. For graphical user interface (GUI) processes, this information affects the first window created by the CreateWindow function and shown by the ShowWindow function. For console processes, this information affects the console window if a new console is created for the process. A process can use the GetStartupInfo function to retrieve the STARTUPINFO structure specified when the process was created.

typedef struct _STARTUPINFO { // si

    DWORD   cb;

    LPTSTR  lpReserved;

    LPTSTR  lpDesktop;

    LPTSTR  lpTitle;

    DWORD   dwX;

    DWORD   dwY;

    DWORD   dwXSize;

    DWORD   dwYSize;

    DWORD   dwXCountChars;

    DWORD   dwYCountChars;

    DWORD   dwFillAttribute;

    DWORD   dwFlags;

    WORD    wShowWindow;

    WORD    cbReserved2;

    LPBYTE  lpReserved2;

    HANDLE  hStdInput;

    HANDLE  hStdOutput;

    HANDLE  hStdError;

} STARTUPINFO, *LPSTARTUPINFO;

Members

cb

Specifies the size, in bytes, of the structure.

lpReserved

Reserved. Set this member to NULL before passing the structure to CreateProcess.

lpDesktop

Windows NT only: Points to a zero-terminated string that specifies either the name of the desktop only or the name of both the window station and desktop for this process. A backslash in the string pointed to by lpDesktop indicates that the string includes both desktop and window station names. Otherwise, the lpDesktop string is interpreted as a desktop name. If lpDesktop is NULL, the new process inherits the window station and desktop of its parent process.

lpTitle

For console processes, this is the title displayed in the title bar if a new console window is created. If NULL, the name of the executable file is used as the window title instead. This parameter must be NULL for GUI or console processes that do not create a new console window.

dwX, dwY

Ignored unless dwFlags specifies STARTF_USEPOSITION. Specifies the x and y offsets, in pixels, of the upper left corner of a window if a new window is created. The offsets are from the upper left corner of the screen. For GUI processes, the specified position is used the first time the new process calls CreateWindow to create an overlapped window if the x parameter of CreateWindow is CW_USEDEFAULT.

dwXSize, dwYSize

Ignored unless dwFlags specifies STARTF_USESIZE. Specifies the width (dwXSize) and height (dwYSize), in pixels, of the window if a new window is created. For GUI processes, this is used only the first time the new process calls CreateWindow to create an overlapped window if the nWidth parameter of CreateWindow is CW_USEDEFAULT.

dwXCountChars, dwYCountChars

Ignored unless dwFlags specifies STARTF_USECOUNTCHARS. For console processes, if a new console window is created, dwXCountChars specifies the screen buffer width in character columns, and dwYCountChars specifies the screen buffer height in character rows. These values are ignored in GUI processes.

dwFillAttribute

Ignored unless dwFlags specifies STARTF_USEFILLATTRIBUTE. Specifies the initial text and background colors if a new console window is created in a console application. These values are ignored in GUI applications. This value can be any combination of the following values: FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_RED, FOREGROUND_INTENSITY, BACKGROUND_BLUE, BACKGROUND_GREEN, BACKGROUND_RED, and BACKGROUND_INTENSITY. For example, the following combination of values produces red text on a whilte background:

FOREGROUND_RED | BACKGROUND_RED | BACKGROUND_GREEN | BACKGROUND_BLUE

dwFlags

This is a bit field that determines whether certain STARTUPINFO members are used when the process creates a window. Any combination of the following values can be specified:

Value	Meaning
STARTF_USESHOWWINDOW	If this value is not specified, the wShowWindow member is ignored.
STARTF_USEPOSITION	If this value is not specified, the dwX and dwY members are ignored.
STARTF_USESIZE	If this value is not specified, the dwXSize and dwYSize members are ignored.
STARTF_USECOUNTCHARS	If this value is not specified, the dwXCountChars and dwYCountChars members are ignored.
STARTF_USEFILLATTRIBUTE	If this value is not specified, the dwFillAttribute member is ignored.
STARTF_FORCEONFEEDBACK	If this value is specified, the cursor is in feedback mode for two seconds after CreateProcess is called. If during those two seconds the process makes the first GUI call, the system gives five more seconds to the process. If during those five seconds the process shows a window, the system gives five more seconds to the process to finish drawing the window.
	The system turns the feedback cursor off after the first call to GetMessage, regardless of whether the process is drawing.
	For more information on feedback, see the following Remarks section.
STARTF_FORCEOFFFEEDBACK	If specified, the feedback cursor is forced off while the process is starting. The normal cursor is displayed. For more information on feedback, see the following Remarks section.
STARTF_USESTDHANDLES	If this value is specified, sets the standard input of the process, standard output, and standard error handles to the handles specified in the hStdInput, hStdOutput, and hStdError members of the STARTUPINFO structure. The CreateProcess function’s fInheritHandles parameter must be set to TRUE for this to work properly.
	If this value is not specified, the hStdInput, hStdOutput, and hStdError members of the STARTUPINFO structure are ignored.
wShowWindow

Ignored unless dwFlags specifies STARTF_USESHOWWINDOW. The wshowWindow member can be any of the SW_ constants defined in WINUSER.H. For GUI processes, wShowWindow specifies the default value the first time ShowWindow is called. The nCmdShow parameter of ShowWindow is ignored. In subsequent calls to ShowWindow, the wShowWindow member is used if the nCmdShow parameter of ShowWindow is set to SW_SHOWDEFAULT.

cbReserved2

Reserved; must be zero.

lpReserved2

Reserved; must be NULL.

hStdInput

Ignored unless dwFlags specifies STARTF_USESTDHANDLES. Specifies a handle that will be used as the standard input handle of the process if STARTF_USESTDHANDLES is specified.

hStdOutput

Ignored unless dwFlags specifies STARTF_USESTDHANDLES. Specifies a handle that will be used as the standard output handle of the process if STARTF_USESTDHANDLES is specified.

hStdError

Ignored unless dwFlags specifies STARTF_USESTDHANDLES. Specifies a handle that will be used as the standard error handle of the process if STARTF_USESTDHANDLES is specified.

Remarks

If a GUI process is being started and neither STARTF_FORCEONFEEDBACK or STARTF_FORCEOFFFEEDBACK is specified, the process feedback cursor is used. A GUI process is one whose subsystem is specified as “windows.”

See Also

CreateProcess, CreateWindow, GetMessage, GetStartupInfo, PeekMessage, ShowWindow, WinMain


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.

See Also

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.

See Also

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.

See Also

NetAlertRaise


STICKYKEYS

The STICKYKEYS structure contains information about the StickyKeys accessibility feature. When the StickyKeys feature is on, the user can press a modifier key (SHIFT, CTRL, or ALT) and then another key in sequence rather than at the same time, to enter shifted (modified) characters and other key combinations.

typedef struct tagSTICKYKEYS {     // sk

    DWORD cbSize;

    DWORD dwFlags;

} STICKYKEYS, *LPSTICKYKEYS;

Members

cbSize

Specifies the size, in bytes, of this structure.

dwFlags

A set of bit-flags that specify properties of the StickyKeys feature. The following bit-flag values are defined:

Value	Meaning
SKF_AUDIBLEFEEDBACK	If this flag is set, the system plays a sound when the user latches, locks, or releases modifier keys using the StickyKeys feature.
SKF_AVAILABLE	If this flag is set, the StickyKeys feature is available.
SKF_CONFIRMHOTKEY	Windows 95 only: A confirmation dialog appears when the StickyKeys feature is activated by using the hot key.
SKF_HOTKEYACTIVE	If this flag is set, the user can turn the StickyKeys feature on and off by pressing the SHIFT key five times.
SKF_HOTKEYSOUND	If this flag is set, the system plays a siren sound when the user turns the StickyKeys feature on or off by using the hot key.
SKF_INDICATOR	Windows 95 only: A visual indicator should be displayed when the StickyKeys feature is on.
SKF_STICKYKEYSON	If this flag is set, the StickyKeys feature is on.
SKF_TRISTATE	If this flag is set, pressing a modifier key twice in a row locks down the key until the user presses it a third time.
SKF_TWOKEYSOFF	If this flag is set, releasing a modifier key that has been pressed in combination with any other key turns off the StickyKeys feature.
Remarks

An application uses a STICKYKEYS structure when calling the SystemParametersInfo function with the wAction parameter set to SPI_GETSTICKYKEYS or SPI_SETSTICKYKEYS. When using SPI_GETSTICKYKEYS, an application must specify the cbSize member of the STICKYKEYS structure; the SystemParametersInfo function fills the remaining members. You must specify all structure members when using the SPI_SETSTICKYKEYS value.

See Also

SystemParametersInfo


STRRET

Contains strings returned from IShellFolder methods, such as GetDisplayNameOf.

typedef struct _STRRET { // str

    UINT uType;

    union

    {

        LPWSTR pOleStr;        // pointer to OLE string to free

        UINT   uOffset;        // offset into item identifier list

        char   cStr[MAX_PATH]; // buffer to receive the display name

    } DUMMYUNIONNAME;

} STRRET, *LPSTRRET;

Member

uType

Value that specifies the desired format of the string. This member can be one of the following values:

STRRET_CSTR	The string is returned in cStr.
STRRET_OFFSET	The string is located at uOffset bytes from the beginning of the item identifier list.
STRRET_WSTR	The string is at the address pointed to by pOleStr.
Remarks

The system may or may not provide the display name in the desired format. When IShellFolder::GetDisplayNameOf returns, the uType member indicates the format.

See Also

IShellFolder::GetDisplayNameOf


String

The String structure depicts the organization of data in a file-version resource. This structure is not a true C-language structure because it contains variable-length members. This structure was created solely to depict the organization of data in a version resource and does not appear in any of the header files shipped with the Microsoft® Win32® Software Development Kit (SDK).

The String structure contains a string that describes a specific aspect of a file.

String {

    WORD   wLength;

    WORD   wValueLength;

    WORD   wType;

    WCHAR  szKey[];

    WORD   Padding[];

    String Value[];

} String;

Members

wLength

Specifies the length of the version resource.

wValueLength

Specifies the length of the Value member in the current VS_VERSION_INFO structure. This value is zero if there is no Value member associated with the current version structure.

wType

Specifies the type of data in the version resource. This member is 1 if the version resource contains text data and 0 if the version resource contains binary data.

szKey

Specifies an arbitrary Unicode string. The szKey member can be one or more of the following values. These values are guidelines only.

String	Meaning
Comments	The Value member contains any additional information that should be displayed for diagnostic purposes. This string can be an arbitrary length.
CompanyName	The Value member identifies the company that produced the file. For example, “Microsoft Corporation” or “Standard Microsystems Corporation, Inc.”
FileDescription	The Value member describes the file in such a way that it can be presented to users. This string may be presented in a list box when the user is choosing files to install. For example, “Keyboard driver for AT-style keyboards” or “Microsoft Word for Windows”.
FileVersion	The Value member identifies the version of this file. For example, Value could be “3.00A” or “5.00.RC2”.
InternalName	The Value member identifies the file’s internal name, if one exists. For example, this string would contain the module name for Windows dynamic-link libraries (DLLs), a virtual device name for Windows virtual devices, or a device name for MS-DOS device drivers.
LegalCopyright	The Value member describes all copyright notices, trademarks, and registered trademarks that apply to the file. This should include the full text of all notices, legal symbols, copyright dates, trademark numbers, and so on. In English, this string should be in the format “Copyright Microsoft Corp. 1990−1994”.
LegalTrademarks	The Value member describes all trademarks and registered trademarks that apply to the file. This should include the full text of all notices, legal symbols, trademark numbers, and so on. In English, this string should be in the format “Windows is a trademark of Microsoft Corporation”.
OriginalFilename	The Value member identifies the original name of the file, not including a path. This enables an application to determine whether a file has been renamed by a user. This name may not be MS-DOS 8.3-format if the file is specific to a non-FAT file system.
PrivateBuild	The Value member describes by whom, where, and why this private version of the file was built. This string should only be present if the VS_FF_PRIVATEBUILD flag is set in the dwFileFlags member of the VS_FIXEDFILEINFO structure. For example, Value could be “Built by OSCAR on \OSCAR2”.
ProductName	The Value member identifies the name of the product with which this file is distributed. For example, this string could be “Microsoft Windows”.
ProductVersion	The Value member identifies the version of the product with which this file is distributed. For example, Value could be “3.00A” or “5.00.RC2”.
SpecialBuild	The Value member describes how this version of the file differs from the normal version. This entry should only be present if the VS_FF_SPECIALBUILD flag is set in the dwFileFlags member of the VS_FIXEDFILEINFO structure. For example, Value could be “Private build for Olivetti solving mouse problems on M250 and M250E computers”.
Padding

Contains as many zero words as necessary to align the Value member on a 32-bit boundary.

Value

Specifies a zero-terminated string. See the szKey member description for more information.

Remarks

A String structure may have an szKey value of, for example, “CompanyName” and a Value of “Microsoft Corporation”. Another String structure with the same szKey value could contain a Value of “Microsoft GmbH”. This might occur if the second String structure were associated with a StringTable structure whose szKey value is 040704b0 — that is, German/Unicode. The code page can be set to 1200 (decimal) or 0x04b0 (hexadecimal) to indicate Unicode. The code page can also be set to the value that is appropriate for the language component. After you choose the value for the code page you should continue to use the same value in later revisions to the file.

See Also

StringTable, VS_FIXEDFILEINFO, VS_VERSION_INFO


StringFileInfo

The StringFileInfo structure depicts the organization of data in a file-version resource. This structure is not a true C-language structure because it contains variable-length members. This structure was created solely to depict the organization of data in a version resource and does not appear in any of the header files shipped with the Microsoft Win32 Software Development Kit (SDK).

The StringFileInfo structure contains version information that must be displayed for a particular language.

StringFileInfo {

    WORD        wLength;

    WORD        wValueLength;

    WORD        wType;

    WCHAR       szKey[];

    WORD        Padding[];

    StringTable Children[];

};

Members

wLength

Specifies the length of the version resource.

wValueLength

Specifies the length of the Value member in the current VS_VERSION_INFO structure. This value is zero if there is no Value member associated with the current version structure.

wType

Specifies the type of data in the version resource. This member is 1 if the version resource contains text data and 0 if the version resource contains binary data.

szKey

Contains the Unicode string “StringFileInfo”.

Padding

Contains as many zero words as necessary to align the Children member on a 32-bit boundary.

Children

Specifies a list of one or more Children structures. Each StringTable structure’s szKey member indicates the appropriate language.

Remarks

The Children member of the VS_VERSION_INFO structure may contain zero or more StringFileInfo structures.

See Also

StringTable, VS_VERSION_INFO


StringTable

The StringTable structure depicts the organization of data in a file-version resource. This structure is not a true C-language structure because it contains variable-length members. This structure was created solely to depict the organization of data in a version resource and does not appear in any of the header files shipped with the Microsoft Win32 Software Development Kit (SDK).

The StringTable structure contains language and code-page formatting information for the strings specified by the Children member. A code page is an ordered character set.

StringTable {

    WORD   wLength;

    WORD   wValueLength;

    WORD   wType;

    WCHAR  szKey[];

    String Children[];

};

Members

wLength

Specifies the length of the version resource.

wValueLength

Specifies the length of the Value member in the current VS_VERSION_INFO structure. This value is zero if there is no Value member associated with the current version structure.

wType

Specifies the type of data in the version resource. This member is 1 if the version resource contains text data and 0 if the version resource contains binary data.

szKey

Specifies an 8-digit hexadecimal number stored as a Unicode string. The four most significant digits represent the language identifier. The four least significant digits represent the code page for which the data is formatted.

Each Microsoft Standard Language identifier contains two parts: the low-order 10 bits specify the major language, and the high-order 6 bits specify the sublanguage. For a table of valid identifiers see Language Identifiers.

Padding

Contains as many zero words as necessary to align the Children member on a 32-bit boundary.

Children

Specifies a list of zero or more String structures.

Remarks

The Children member of the StringFileInfo structure contains at least one StringTable structure with an szKey value of “04091200”. This value indicates that the language is U.S. English and the code page is Unicode.

The code page portion of the szKey member can be set to 1200 (decimal) or 0x04b0 (hexadecimal) to indicate Unicode. The code page can also be set to the value that is appropriate for the language component. After you choose the value for the code page you should continue to use the same value in later revisions to the file.

An executable file or dynamic-link library (DLL) that supports multiple languages should have a version resource for each language, rather than a single version resource that contains strings in several languages.

See Also

String, StringFileInfo, VS_VERSION_INFO


STYLEBUF

The STYLEBUF structure contains the identifier and name of a style.

typedef struct _tagSTYLEBUF {
    DWORD  dwStyle;
    CHAR  szDescription[32];
} STYLEBUF;

Members

dwStyle

Style of the register string. Can be IME_REGWORD_STYLE_EUDC to indicate a string in the EUDC range.

szDescription

Description of the style.


STYLESTRUCT

The STYLESTRUCT structure contains the window styles for a window.

typedef struct tagSTYLESTRUCT {  // ss

    DWORD styleOld;

    DWORD styleNew;

} STYLESTRUCT, * LPSTYLESTRUCT;

Members

style

Specifies an array of window style or extended-style flags.

See Also

WM_STYLECHANGED, WM_STYLECHANGING


SYSTEM_ALARM_ACE

Reserved for future use.


SYSTEM_AUDIT_ACE

The SYSTEM_AUDIT_ACE structure defines an access-control entry (ACE) for the system access-control list (ACL) specifying what types of access cause system-level notifications. A system-audit ACE causes an audit message to be logged when a specified user or group attempts to gain access to an object. The user or group is identified by a security identifier (SID).

typedef struct _SYSTEM_AUDIT_ACE { // sada

    ACE_HEADER  Header;

    ACCESS_MASK Mask;

    DWORD       SidStart;

} SYSTEM_AUDIT_ACE;

Members

Header

Specifies an ACE_HEADER structure.

Mask

Specifies an ACCESS_MASK structure that gives the access rights causing audit messages to be generated. The SUCCESSFUL_ACCESS_ACE_FLAG and FAILED_ACCESS_ACE_FLAG flags in the AceFlags member of the ACE_HEADER structure indicate whether messages are generated for successful access attempts, unsuccessful access attempts, or both.

SidStart

Specifies a SID. An access attempt of a kind specified by the Mask member by any user or group whose SID matches the SidStart member causes the system to generate an audit message. If an application does not specify a SID for this member, audit messages are generated for the specified access rights for all users and groups.

Remarks

Audit messages are stored in an event log that can be manipulated by using the Win32 API event-logging functions or by using Windows NT Event Viewer (EVENTVWR.EXE).

ACE structures should be aligned on doubleword boundaries. All Windows memory-management functions return doubleword-aligned handles to memory.

See Also

ACCESS_ALLOWED_ACE, ACCESS_DENIED_ACE, ACCESS_MASK, ACE_HEADER, ACL, SYSTEM_ALARM_ACE


SYSTEM_INFO

The SYSTEM_INFO structure contains information about the current computer system. This includes the architecture and type of the processor, the number of processors in the system, the page size, and other such information.

typedef struct _SYSTEM_INFO { // sinf

    union {

        DWORD  dwOemId;

        struct {

            WORD wProcessorArchitecture;

            WORD wReserved;

        };

    };

    DWORD  dwPageSize;

    LPVOID lpMinimumApplicationAddress;

    LPVOID lpMaximumApplicationAddress;

    DWORD  dwActiveProcessorMask;

    DWORD  dwNumberOfProcessors;

    DWORD  dwProcessorType;

    DWORD  dwAllocationGranularity;

    WORD  wProcessorLevel;

    WORD  wProcessorRevision;

} SYSTEM_INFO;

Members

dwOemId

An obsolete member that is retained for compatibility with previous versions of Windows NT. Beginning with Windows NT 3.51 and the initial release of Windows 95, use the wProcessorArchitecture branch of the union.

Windows 95: The system always sets this member to zero, the value defined for PROCESSOR_ARCHITECTURE_INTEL.

wProcessorArchitecture

Specifies the system’s processor architecture. This value can be one of the following values:

Value

PROCESSOR_ARCHITECTURE_INTEL

Windows NT only: PROCESSOR_ARCHITECTURE_MIPS

Windows NT only: PROCESSOR_ARCHITECTURE_ALPHA

Windows NT only: PROCESSOR_ARCHITECTURE_PPC

Windows NT only: PROCESSOR_ARCHITECTURE_UNKNOWN

wReserved

Reserved for future use.

dwPageSize

Specifies the page size and the granularity of page protection and commitment. This is the page size used by the VirtualAlloc function.

lpMinimumApplicationAddress

Pointer to the lowest memory address accessible to applications and dynamic-link libraries (DLLs).

lpMaximumApplicationAddress

Pointer to the highest memory address accessible to applications and DLLs.

dwActiveProcessorMask

Specifies a mask representing the set of processors configured into the system. Bit 0 is processor 0; bit 31 is processor 31.

dwNumberOfProcessors

Specifies the number of processors in the system.

dwProcessorType

Windows 95:

Specifies the type of processor in the system.

Windows NT:

This member is no longer relevant, but is retained for compatibility with Windows 95 and previous versions of Windows NT. Use the wProcessorArchitecture, wProcessorLevel, and wProcessorRevision members to determine the type of processor.

This member is one of the following values:

Value

PROCESSOR_INTEL_386

PROCESSOR_INTEL_486

PROCESSOR_INTEL_PENTIUM

Windows NT only: PROCESSOR_MIPS_R4000

Windows NT only: PROCESSOR_ALPHA_21064

dwAllocationGranularity

Specifies the granularity with which virtual memory is allocated. For example, a VirtualAlloc request to allocate 1 byte will reserve an address space of dwAllocationGranularity bytes. This value was hard coded as 64K in the past, but other hardware architectures may require different values.

wProcessorLevel

Windows 95: This member is not used.

Windows NT: Specifies the system’s architecture-dependent processor level.

If wProcessorArchitecture is PROCESSOR_ARCHITECTURE_INTEL, wProcessorLevel can be one of the following values:

Value	Meaning
3	Intel 80386
4	Intel 80486
5	Pentium
If wProcessorArchitecture is PROCESSOR_ARCHITECTURE_MIPS, wProcessorLevel is of the form 00xx, where xx is an 8-bit implementation number (bits 8-15 of the PRId register). The member can be the following value:

Value	Meaning
0004	MIPS R4000
If wProcessorArchitecture is PROCESSOR_ARCHITECTURE_ALPHA, wProcessorLevel is of the form xxxx, where xxxx is a 16-bit processor version number (the low-order 16 bits of a version number from the firmware). The member can be one of the following values:

Decimal Value	Meaning
21064	Alpha 21064
21066	Alpha 21066
21164	Alpha 21164
If wProcessorArchitecture is PROCESSOR_ARCHITECTURE_PPC, wProcessorLevel is of the form xxxx, where xxxx is a 16-bit processor version number (the high-order 16 bits of the Processor Version Register). The member can be one of the following values:

Decimal Value	Meaning
1	PPC 601
3	PPC 603
4	PPC 604
6	PPC 603+
9	PPC 604+
20	PPC 620
wProcessorRevision

Windows 95: This member is not used.

Windows NT: Specifies an architecture-dependent processor revision. The following table shows how the revision value is assembled for each type of processor architecture.

Processor Architecture	Value
Intel 80386 or 80486	A value of the form xxyz.  If xx is equal to 0xFF, y - 0xA is the model number, and z is the stepping identifier. For example, an Intel 80486-D0 system returns 0xFFD0. If xx is not equal to 0xFF, xx + 'A' is the stepping letter and yz is the minor stepping.
Intel Pentium,  Cyrix, or  NextGen 586	A value of the form xxyy, where xx is the model number and yy is the stepping. For example, a value of 0x0201 indicates Model 2, Stepping 1.
MIPS	A value of the form 00xx, where xx is the 8-bit revision number of the processor (the low-order 8 bits of the PRId register).
ALPHA	A value of the form xxyy, where xxyy is the low-order 16 bits of the processor revision number from the firmware. Display this value as follows:  Model ‘A’+xx, Pass yy
PPC	A value of the form xxyy, where xxyy is the low-order 16 bits of the Processor Version Register. Display this value as a fixed point number: xx.yy
Remarks

Beginning with Windows NT 3.51 and the initial release of Windows 95, the SYSTEM_INFO structure has changed as follows:

•	The dwOemId member has been changed to a union. The union supports a new way to describe processor architecture used by Windows NT, while maintaining compatibility with Windows 95 and previous versions of Windows NT.

•	The dwProcessorType member is now obsolete on Windows NT. It is still used on Windows 95.

•	A previously reserved DWORD member at the end of the structure has been replaced by the wProcessorLevel and wProcessorRevision members. Windows 95 does not use these members.

See Also

GetSystemInfo, MapViewOfFile, MapViewOfFileEx


SYSTEM_POWER_STATUS

The SYSTEM_POWER_STATUS structure contains information about the power status of the system.

typedef struct _SYSTEM_POWER_STATUS {
    BYTE ACLineStatus;
    BYTE  BatteryFlag;
    BYTE  BatteryLifePercent;
    BYTE  Reserved1;
    DWORD  BatteryLifeTime;
    DWORD  BatteryFullLifeTime;
} SYSTEM_POWER_STATUS;
typedef struct SYSTEM_POWER_STATUS *LPSYSTEM_POWER_STATUS;

Members

ACLineStatus

AC power status. This parameter can be one of the following values:

Value	Meaning
0	Offline
1	Online
255	Unknown status.
All other values are reserved.

BatteryFlag

Battery charge status. This parameter can be a combination of the following values:

Value	Meaning
1	High
2	Low
4	Critical
8	Charging
128	No system battery
255	Unknown status
All other values are reserved.

BatteryLifePercent

Percentage of full battery charge remaining. This member can be a value in the range 0 to 100, or 255 if status is unknown. All other values are reserved.

Reserved1

Reserved; must be zero.

BatteryLifeTime

Number of seconds of battery life remaining, or 0xFFFFFFFF if remaining seconds are unknown.

BatteryFullLifeTime

Number of seconds of battery life when at full charge, or 0xFFFFFFFF if full lifetime is unknown.

Remarks

Windows 95 is only capable of estimating BatteryFullTime based on calculations on BatteryLifeTime and BatteryLifePercent. Without smart battery subsystems, this value may not be accurate enough to be useful.


SYSTEMTIME

The SYSTEMTIME structure represents a date and time using individual members for the month, day, year, weekday, hour, minute, second, and millisecond.

typedef struct _SYSTEMTIME {  // st

    WORD wYear;

    WORD wMonth;

    WORD wDayOfWeek;

    WORD wDay;

    WORD wHour;

    WORD wMinute;

    WORD wSecond;

    WORD wMilliseconds;

} SYSTEMTIME;

Members

wYear

Specifies the current year.

wMonth

Specifies the current month; January = 1, February = 2, and so on.

wDayOfWeek

Specifies the current day of the week; Sunday = 0, Monday = 1, and so on.

wDay

Specifies the current day of the month.

wHour

Specifies the current hour.

wMinute

Specifies the current minute.

wSecond

Specifies the current second.

wMilliseconds

Specifies the current millisecond.

Remarks

It is not recommended that you add and subtract values from the SYSTEMTIME structure to obtain relative times. Instead, you should

•	Convert the SYSTEMTIME structure to a FILETIME structure.

•	Copy the resulting FILETIME structure to a LARGE_INTEGER structure.

•	Use normal 64-bit arithmetic on the LARGE_INTEGER value.

See Also

FILETIME, GetSystemTime, LARGE_INTEGER, SetSystemTime


TAPE_ERASE

The TAPE_ERASE structure describes the partition to be erased.

typedef struct _TAPE_ERASE { // ter

    ULONG Type;

} TAPE_ERASE;

Members

Type

Specifies how to erase the tape. This member must have one of the following values:

Value	Description
TAPE_ERASE_LONG	Erases the entire partition.
TAPE_ERASE_SHORT	Erases only the partition’s header block.


TAPE_GET_DRIVE_PARAMETERS

The TAPE_GET_DRIVE_PARAMETERS structure describes the tape drive.

typedef struct _TAPE_GET_DRIVE_PARAMETERS { // tgdp

    BOOLEAN ECC;

    BOOLEAN Compression;

    BOOLEAN DataPadding;

    BOOLEAN ReportSetmarks;

    ULONG   DefaultBlockSize;

    ULONG   MaximumBlockSize;

    ULONG   MinimumBlockSize;

    ULONG   MaximumPartitionCount;

    ULONG   FeaturesLow;

    ULONG   FeaturesHigh;

    ULONG   EOTWarningZoneSize;

} TAPE_GET_DRIVE_PARAMETERS;

Members

ECC

Specifies whether the device supports hardware error correction. This member is TRUE if hardware error correction is supported.

Compression

Specifies whether hardware data compression is enabled or disabled. This member is TRUE if hardware data compression is enabled.

DataPadding

Specifies whether data padding is enabled or disabled. Data padding keeps the tape streaming at a constant speed. This member is TRUE if data padding is enabled.

ReportSetmarks

Specifies whether setmark reporting is enabled or disabled. This member is TRUE if setmark reporting is enabled.

DefaultBlockSize

Specifies the device’s default fixed block size.

MaximumBlockSize

Specifies the device’s maximum block size.

MinimumBlockSize

Specifies the device’s minimum block size.

MaximumPartitionCount

Specifies the maximum number of partitions that can be created on the device.

FeaturesLow

Specifies the low-order 32 bits of the device features flag. This member can be one or more of following values:

Value	Meaning
TAPE_DRIVE_COMPRESSION	The device supports hardware data compression.
TAPE_DRIVE_ECC	The device supports hardware error correction.
TAPE_DRIVE_ERASE_BOP_ONLY	The device performs the erase operation from the beginning-of-partition marker only.
TAPE_DRIVE_ERASE_LONG	The device performs a long erase operation.
TAPE_DRIVE_ERASE_IMMEDIATE	The device performs an immediate erase operation —  that is, it returns when the erase operation begins.
TAPE_DRIVE_ERASE_SHORT	The device performs a short erase operation.
TAPE_DRIVE_FIXED	The device creates fixed data partitions.
TAPE_DRIVE_FIXED_BLOCK	The device supports fixed-length block mode.
TAPE_DRIVE_INITIATOR	The device creates initiator-defined partitions.
TAPE_DRIVE_PADDING	The device supports data padding.
TAPE_DRIVE_GET_ABSOLUTE_BLK	The device provides the current device-specific block address.
TAPE_DRIVE_GET_LOGICAL_BLK	The device provides the current logical block address (and logical tape partition).
TAPE_DRIVE_REPORT_SMKS	The device supports setmark reporting.
TAPE_DRIVE_SELECT	The device creates select data partitions.
TAPE_DRIVE_SET_EOT_WZ_SIZE	The device supports setting the end-of-medium warning size.
TAPE_DRIVE_TAPE_CAPACITY	The device returns the maximum capacity of the tape.
TAPE_DRIVE_TAPE_REMAINING	The device returns the remaining capacity of the tape.
TAPE_DRIVE_VARIABLE_BLOCK	The device supports variable-length block mode.
TAPE_DRIVE_WRITE_PROTECT	The device returns an error if the tape is write-enabled or write-protected.
FeaturesHigh

Contains the high-order 32 bits of the device features flag. This member can be one or more of the following values:

Value	Meaning
TAPE_DRIVE_ABS_BLK_IMMED	The device moves the tape to a device-specific block address and returns as soon as the move begins.
TAPE_DRIVE_ABSOLUTE_BLK	The device moves the tape to a device specific block address.
TAPE_DRIVE_END_OF_DATA	The device moves the tape to the end-of-data marker in a partition.
TAPE_DRIVE_FILEMARKS	The device moves the tape forward (or backward) a specified number of filemarks.
TAPE_DRIVE_LOAD_UNLOAD	The device enables and disables the device for further operations.
TAPE_DRIVE_LOAD_UNLD_IMMED	The device supports immediate load and unload operations.
TAPE_DRIVE_LOCK_UNLOCK	The device enables and disables the tape ejection mechanism.
TAPE_DRIVE_LOCK_UNLK_IMMED	The device supports immediate lock and unlock operations.
TAPE_DRIVE_LOG_BLK_IMMED	The device moves the tape to a logical block address in a partition and returns as soon as the move begins.
TAPE_DRIVE_LOGICAL_BLK	The device moves the tape to a logical block address in a partition.
TAPE_DRIVE_RELATIVE_BLKS	The device moves the tape forward (or backward) a specified number of blocks.
TAPE_DRIVE_REVERSE_POSITION	The device moves the tape backward over blocks, filemarks, or setmarks.
TAPE_DRIVE_REWIND_IMMEDIATE	The device supports immediate rewind operation.
TAPE_DRIVE_SEQUENTIAL_FMKS	The device moves the tape forward (or backward) to the first occurrence of a specified number of consecutive filemarks.
TAPE_DRIVE_SEQUENTIAL_SMKS	The device moves the tape forward (or backward) to the first occurrence of a specified number of consecutive setmarks.
TAPE_DRIVE_SET_BLOCK_SIZE	The device supports setting the size of a fixed-length logical block or setting the variable-length block mode.
TAPE_DRIVE_SET_COMPRESSION	The device enables and disables hardware data compression.
TAPE_DRIVE_SET_ECC	The device enables and disables hardware error correction.
TAPE_DRIVE_SET_PADDING	The device enables and disables data padding.
TAPE_DRIVE_SET_REPORT_SMKS	The device enables and disables the reporting of setmarks.
TAPE_DRIVE_SETMARKS	The device moves the tape forward (or reverse) a specified number of setmarks.
TAPE_DRIVE_SPACE_IMMEDIATE	The device supports immediate spacing.
TAPE_DRIVE_TENSION	The device supports tape tensioning.
TAPE_DRIVE_TENSION_IMMED	The device supports immediate tape tensioning.
TAPE_DRIVE_WRITE_FILEMARKS	The device writes filemarks.
TAPE_DRIVE_WRITE_LONG_FMKS	The device writes long filemarks.
TAPE_DRIVE_WRITE_MARK_IMMED	The device supports immediate writing of short and long filemarks.
TAPE_DRIVE_WRITE_SETMARKS	The device writes setmarks.
TAPE_DRIVE_WRITE_SHORT_FMKS	The device writes short filemarks.
EOTWarningZoneSize

Indicates the number of bytes between the end-of-tape warning and the physical end of the tape.


TAPE_GET_MEDIA_PARAMETERS

The TAPE_GET_MEDIA_PARAMETERS structure describes the tape in the tape drive.

typedef struct _TAPE_GET_MEDIA_PARAMETERS {  // tgmp

    LARGE_INTEGER   Capacity;

    LARGE_INTEGER   Remaining;

    DWORD   BlockSize;

    DWORD   PartitionCount;

    BOOLEAN WriteProtected;

} TAPE_GET_MEDIA_PARAMETERS;

Members

Capacity

Specifies the total number of bytes on the current tape partition.

Remaining

Specifies the number of bytes between the current position and the end of the current tape partition.

BlockSize

Specifies the number of bytes per block.

PartitionCount

Specifies the number of partitions on the tape.

WriteProtected

Specifies whether the tape is write-protected. If this member is TRUE, the tape is write-protected.

Remarks

The GetTapeParameters function fills the Remaining and Capacity members with estimates of the tape remaining in the current tape partition and the total capacity of the current tape partition.

See Also

GetTapeParameters


TAPE_GET_POSITION

The TAPE_GET_POSITION structure describes the position of the tape.

typedef struct _TAPE_GET_POSITION { // tgpos

    ULONG Type;

    ULONG Partition;

    ULONG OffsetLow;

    ULONG OffsetHigh;

} TAPE_GET_POSITION;

Members

Type

Specifies the type of position. This member must be one of the following values:

Value	Description
TAPE_ABSOLUTE_POSITION	The position specified by the OffsetLow and OffsetHigh members is an absolute number of blocks from the beginning of the partition specified by the Partition member.
TAPE_LOGICAL_POSITION	The position specified by OffsetLow and OffsetHigh is relative to the current position in the partition specified by Partition.
Partition

Specifies the partition to position within. If this member is zero, the current partition is assumed.

OffsetLow

Specifies the low-order 32 bits of the block address.

OffsetHigh

Specifies the high-order 32 bits of the block address. If the high-order 32 bits are not required, this member should be zero.


TAPE_PREPARE

The TAPE_PREPARE structure describes how to prepare the tape.

typedef struct _TAPE_PREPARE { // tp

    ULONG Operation;

} TAPE_PREPARE;

Members

Operation

Specifies how to prepare the tape. This member must be one of the following values:

Value	Description
TAPE_LOCK	Locks the tape ejection mechanism so that the tape is not ejected accidentally during a tape operation.
TAPE_TENSION	Moves to the end of the tape and rewinds to the beginning of the tape. This value is ignored if the tape device does not support tensioning.
TAPE_UNLOAD	Rewinds and unloads the tape.
TAPE_UNLOCK	Unlocks the tape ejection mechanism.


TAPE_SET_DRIVE_PARAMETERS

The TAPE_SET_DRIVE_PARAMETERS structure describes the tape drive.

typedef struct _TAPE_SET_DRIVE_PARAMETERS {  // tsdp

    BOOLEAN ECC;

    BOOLEAN Compression;

    BOOLEAN DataPadding;

    BOOLEAN ReportSetmarks;

    ULONG   EOTWarningZoneSize;

} TAPE_SET_DRIVE_PARAMETERS;

Members

ECC

Specifies whether the device supports hardware error correction. This member is TRUE if hardware error correction is supported.

Compression

Specifies whether hardware data compression is enabled or disabled. This member is TRUE if hardware data compression is enabled.

DataPadding

Specifies whether data padding is enabled or disabled. Data padding keeps the tape streaming at a constant speed. This member is TRUE if data padding is enabled.

ReportSetmarks

Specifies whether setmark reporting is enabled or disabled. This member is TRUE if setmarks are enabled.

EOTWarningZoneSize

Specifies the number of bytes between the end-of-tape warning and the physical end of the tape.


TAPE_SET_MEDIA_PARAMETERS

The TAPE_SET_MEDIA_PARAMETERS structure describes the tape in the tape drive.

typedef struct _TAPE_SET_MEDIA_PARAMETERS { // tsmp

    ULONG BlockSize;

} TAPE_SET_MEDIA_PARAMETERS;

Members

BlockSize

Specifies the number of bytes per block. Maximum and minimum block sizes can be obtained by calling the GetTapeParameters function.

Remarks

There is no longer a requirement that block sizes be powers of 2.

See Also

GetTapeParameters, SetTapeParameters


TAPE_SET_POSITION

The TAPE_SET_POSITION structure describes how and where to position the tape.

typedef struct _TAPE_SET_POSITION { // tspos

    ULONG Method;

    ULONG Partition;

    ULONG OffsetLow;

    ULONG OffsetHigh;

} TAPE_SET_POSITION;

Members

Method

Specifies the type of positioning. This member must be one of the following values:

Value	Description
TAPE_ABSOLUTE_BLOCK	Moves the tape to the device-specific block address specified by the OffsetLow and OffsetHigh members. The Partition member is ignored.
TAPE_LOGICAL_BLOCK	Moves the tape to the block address specified by OffsetLow and OffsetHigh in the partition specified by Partition.
TAPE_REWIND	Moves the tape to the beginning of the current partition. The Partition, OffsetLow, and OffsetHigh members are ignored.
TAPE_SPACE_END_OF_DATA	Moves the tape to the end of the data on the partition specified by Partition.
TAPE_SPACE_FILEMARKS	Moves the tape forward (or backward) the number of filemarks specified by OffsetLow and OffsetHigh in the current partition. The Partition member is ignored.
TAPE_SPACE_RELATIVE_BLOCKS	Moves the tape forward (or backward) the number of blocks specified by OffsetLow and OffsetHigh in the current partition. The Partition member is ignored.
TAPE_SPACE_SEQUENTIAL_FMKS	Moves the tape forward (or backward) to the first occurrence of n filemarks in the current partition, where n is the number specified by OffsetLow and OffsetHigh. The Partition parameter is ignored.
TAPE_SPACE_SEQUENTIAL_SMKS	Moves the tape forward (or backward) to the first occurrence of n setmarks in the current partition, where n is the number specified by OffsetLow and OffsetHigh. The Partition member is ignored.
TAPE_SPACE_SETMARKS	Moves the tape forward (or backward) the number of setmarks specified by OffsetLow and OffsetHigh in the current partition. The Partition member is ignored.
Partition

Specifies the partition to position within. If this member is zero, the current partition is assumed.

OffsetLow

Specifies the low-order 32 bits of the block address or count for the position operation specified by the Method member.

OffsetHigh

Specifies the high-order 32 bits of the block address or count for the position operation specified by the Method member. If the high-order 32 bits are not required, this member should be zero.

Remarks

If the positioning is relative, a positive offset moves the tape forward (toward the end of the tape) and a negative offset moves the tape backward (toward the beginning of the tape).


TAPE_WRITE_MARKS

The TAPE_WRITE_MARKS structure describes the type and number of tapemarks to write.

typedef struct _TAPE_WRITE_MARKS { // twm

    ULONG Type;

    ULONG Count;

} TAPE_WRITE_MARKS;

Members

Type

Specifies the type of tapemark to write. This member can be one of the following values:

Value	Description
TAPE_LONG_FILEMARKS	Writes long filemarks.
TAPE_SEQUENTIAL_FILEMARKS	Writes sequential filemarks.
TAPE_SETMARKS	Writes setmarks.
TAPE_SHORT_FILEMARKS	Writes short filemarks.
Count

Specifies the number of tapemarks to write.


TBADDBITMAP

The TBADDBITMAP structure adds a bitmap that contains button images to a toolbar.

typedef struct {  // tbab

    HINSTANCE hInst;

    UINT nID;

} TBADDBITMAP, *LPTBADDBITMAP;

Members

hInst

Handle to the module instance with the executable file that contains a bitmap resource. You can add the system-defined button bitmaps to the list by specifying HINST_COMMCTRL as the hInst member and one of the following values as the nID member:

Value	Meaning
IDB_STD_LARGE_COLOR	Adds large, color standard bitmaps.
IDB_STD_SMALL_COLOR	Adds small, color standard bitmaps.
IDB_VIEW_LARGE_COLOR	Adds large, color view bitmaps.
IDB_VIEW_SMALL_COLOR	Adds small, color view bitmaps.
For more information about the system-defined standard and view bitmaps, see the following Remarks section.

nID

Resource identifier of the bitmap resource that contains the button images. If hInst is NULL, this parameter must be the handle to a bitmap that contains the button images.

Remarks

The Windows header files provide the following values that you use as indexes to the standard and view bitmaps.

STD_COPY	STD_PASTE
STD_CUT	STD_PRINT
STD_DELETE	STD_PRINTPRE
STD_FILENEW	STD_PROPERTIES
STD_FILEOPEN	STD_REDOW
STD_FILESAVE	STD_REPLACE
STD_FIND	STD_UNDO
STD_HELP
VIEW_LARGEICONS	VIEW_SORTNAME
VIEW_SMALLICONS	VIEW_SORTSIZE
VIEW_LIST	VIEW_SORTDATE
VIEW_DETAILS	VIEW_SORTTYPE
The TBADDBITMAP structure is used with the TB_ADDBITMAP message.

See Also

TB_ADDBITMAP


TBBUTTON

The TBBUTTON structure contains information about a button in a toolbar.

typedef struct _TBBUTTON { \\ tbb

    int iBitmap;

    int idCommand;

    BYTE fsState;

    BYTE fsStyle;

    DWORD dwData;

    int iString;

} TBBUTTON, NEAR* PTBBUTTON, FAR* LPTBBUTTON;

typedef const TBBUTTON FAR* LPCTBBUTTON;

Members

iBitmap

Zero-based index of button image.

idCommand

Command identifier associated with the button. This identifier is used in a WM_COMMAND message when the button is chosen. If the fsStyle member is the TBSTYLE_SEP value, this member must be zero.

fsState

Button state flags. This member can be a combination of the values listed in Toolbar Button States.

fsStyle

Button style. This member can be a combination of values listed in Toolbar Button Styles

dwData

Application-defined value.

iString

Zero-based index of button string.

See Also

WM_COMMAND


TBNOTIFY

The TBNOTIFY structure contains information used to process notification messages from a toolbar.

typedef struct { \\ tbn

    NMHDR hdr;

    int iItem;

    TBBUTTON tbButton;

    int cchText;

    LPTSTR pszText;

} TBNOTIFY, FAR* LPTBNOTIFY;

Members

hdr

Required for all WM_NOTIFY messages.

iItem

Index of the button associated with notification.

tbButton

Address of a TBBUTTON structure that contains information about the toolbar button associated with the notification.

cchText

Count of characters in the button text.

pszText

Address of the button text.

See Also

TBBUTTON, WM_NOTIFY


TBSAVEPARAMS

The TBSAVEPARAMS function specifies the location in the registry where the TB_SAVERESTORE message stores and retrieves information about the state of a toolbar.

typedef struct { \\ tbsr

    HKEY hkr;

    LPCTSTR pszSubKey;

    LPCTSTR pszValueName;

} TBSAVEPARAMS;

Members

hkr

Handle to the registry key.

pszSubKey

Subkey name.

pszValueName

Value name.

See Also

TB_SAVERESTORE


TC_HITTESTINFO

The TC_HITTESTINFO structure contains information about a hit test.

typedef struct _TC_HITTESTINFO {

    POINT pt;     // position to hit test, in client coordinates

    UINT  flags;  // variable to receive hit test results

} TC_HITTESTINFO;

Members

pt

Position to hit test, in client coordinates.

flags

Variable that receives the results of a hit test. The tab control sets this member to one of the following values:

Value	Meaning
TCHT_NOWHERE	The position is not over a tab.
TCHT_ONITEM	The position is over a tab, but not over its icon or its text. For owner-drawn tab controls, this value is specified if the position is anywhere over a tab.
TCHT_ONITEMICON	The position is over a tab’s icon.
TCHT_ONITEMLABEL	The position is over a tab’s text.
TCHT_ONITEM is a bitwise OR operation on TCHT_ONITEMICON and TCHT_ONITEMLABEL.

Remarks

This structure is used with the TCM_HITTEST message.

See Also

TCM_HITTEST


TC_ITEM

The TC_ITEM structure specifies or receives the attributes of a tab.

typedef struct _TC_ITEM {

    UINT mask;         // value specifying which members to retrieve or set

    UINT lpReserved1;  // reserved; do not use

    UINT lpReserved2;  // reserved; do not use

    LPSTR pszText;     // pointer to string containing tab text

    int cchTextMax;    // size of buffer pointed to by the pszText member

    int iImage;        // index to tab control's image

    LPARAM lParam;     // application-defined data associated with tab

} TC_ITEM;

Members

mask

Value specifying which members to retrieve or set. This member can be TCIF_ALL (meaning all members), or zero or more of the following values:

Value	Meaning
TCIF_TEXT	The pszText member is valid.
TCIF_IMAGE	The iImage member is valid.
TCIF_PARAM	The lParam member is valid.
TCIF_RTLREADING	Displays the text of pszText using right-to-left reading order on Hebrew or Arabic systems.
lpReserved1

Reserved; do not use.

lpReserved2

Reserved; do not use.

pszText

Pointer to a null-terminated string that contains the tab text if the structure contains information about a tab. If the structure is receiving information, this member specifies the address of the buffer that receives the tab text.

cchTextMax

Size of the buffer pointed to by the pszText member. If the structure is not receiving information, this member is ignored.

iImage

Index into the tab control’s image list or  − 1 if there is no image for the tab.

lParam

Application-defined data associated with the tab. If there are more or less than 4 bytes of application-defined data per tab, an application must define a structure and use it instead of the TC_ITEM structure. The first member of the application-defined structure must be a TC_ITEMHEADER structure.

Remarks

This structure is used with the TCM_INSERTITEM, TCM_GETITEM, and TCM_SETITEM messages.

See Also

TCM_GETITEM, TCM_INSERTITEM, TC_ITEMHEADER, TCM_SETITEM


TC_ITEMHEADER

The TC_ITEMHEADER structure specifies or receives the attributes of a tab. This structure is the same as the TC_ITEM structure, that it does not include an lParam member for application-defined data.

typedef struct _TC_ITEMHEADER {

    UINT mask;         // value specifying which members to retrieve or set

    UINT lpReserved1;  // reserved; do not use

    UINT lpReserved2;  // reserved; do not use

    LPSTR pszText;     // pointer to string containing tab text

    int cchTextMax;    // size of buffer pointed to by the pszText member

    int iImage;        // index to tab control's image

} TC_ITEMHEADER;

Members

mask

Value specifying which members to retrieve or set. This member can be TCIF_ALL (meaning all members), or zero or more of the following values:

Value	Meaning
TCIF_TEXT	The pszText member is valid.
TCIF_IMAGE	The iImage member is valid.
TCIF_PARAM	The lParam member is valid.
TCIF_RTLREADING	Displays the text of pszText using right-to-left reading order on Hebrew or Arabic systems.
lpReserved1

Reserved; do not use.

lpReserved2

Reserved; do not use.

pszText

Pointer to a null-terminated string that contains the tab text if the structure contains information about a tab. If the structure is receiving information, this member specifies the address of the buffer that receives the tab text.

cchTextMax

Size of the buffer pointed to by the pszText member. If the structure is not receiving information, this member is ignored.

iImage

Index into the tab control’s image list or  − 1 if there is no image for the tab.

Remarks

An application cannot use the TC_ITEM structure to retrieve or set the application-defined data for tabs in a tab control with more or less than four extra bytes per tab. Instead, you should define a structure that consists of the TC_ITEMHEADER structure followed by application-defined data.

To set the number of extra bytes per tab, use the TCM_SETITEMEXTRA message.

See Also

TC_ITEM, TCM_SETITEMEXTRA


TC_KEYDOWN

The TC_KEYDOWN structure contains information about a key press in a tab control. This structure is used with the TCN_KEYDOWN notification message.

typedef struct _TC_KEYDOWN {

    NMHDR hdr;    // notification header

    WORD wVKey;   // virtual-key code

    UINT flags;
} TC_KEYDOWN;

Members

hdr

Notification header

wVKey

Virtual key code.

flags

Same as the lParam parameter of the WM_KEYDOWN message.

See Also

TCN_KEYDOWN, WM_KEYDOWN


TEXTMETRIC

The TEXTMETRIC structure contains basic information about a physical font. All sizes are given in logical units; that is, they depend on the current mapping mode of the display context.

typedef struct tagTEXTMETRIC { // tm

    LONG tmHeight;

    LONG tmAscent;

    LONG tmDescent;

    LONG tmInternalLeading;

    LONG tmExternalLeading;

    LONG tmAveCharWidth;

    LONG tmMaxCharWidth;

    LONG tmWeight;

    LONG tmOverhang;

    LONG tmDigitizedAspectX;

    LONG tmDigitizedAspectY;

    BCHAR tmFirstChar;

    BCHAR tmLastChar;

    BCHAR tmDefaultChar;

    BCHAR tmBreakChar;

    BYTE tmItalic;

    BYTE tmUnderlined;

    BYTE tmStruckOut;

    BYTE tmPitchAndFamily;

    BYTE tmCharSet;

} TEXTMETRIC;

Members

tmHeight

Specifies the height (ascent + descent) of characters.

tmAscent

Specifies the ascent (units above the base line) of characters.

tmDescent

Specifies the descent (units below the base line) of characters.

tmInternalLeading

Specifies the amount of leading (space) inside the bounds set by the tmHeight member. Accent marks and other diacritical characters may occur in this area. The designer may set this member to zero.

tmExternalLeading

Specifies the amount of extra leading (space) that the application adds between rows. Since this area is outside the font, it contains no marks and is not altered by text output calls in either OPAQUE or TRANSPARENT mode. The designer may set this member to zero.

tmAveCharWidth

Specifies the average width of characters in the font (generally defined as the width of the letter x). This value does not include the overhang required for bold or italic characters.

tmMaxCharWidth

Specifies the width of the widest character in the font.

tmWeight

Specifies the weight of the font.

tmOverhang

Specifies the extra width per string that may be added to some synthesized fonts. When synthesizing some attributes, such as bold or italic, graphics device interface (GDI) or a device may have to add width to a string on both a per-character and per-string basis. For example, GDI makes a string bold by expanding the spacing of each character and overstriking by an offset value; it italicizes a font by shearing the string. In either case, there is an overhang past the basic string. For bold strings, the overhang is the distance by which the overstrike is offset. For italic strings, the overhang is the amount the top of the font is sheared past the bottom of the font.

The tmOverhang member enables the application to determine how much of the character width returned by a GetTextExtentPoint32 function call on a single character is the actual character width and how much is the per-string extra width. The actual width is the extent minus the overhang.

tmDigitizedAspectX

Specifies the horizontal aspect of the device for which the font was designed.

tmDigitizedAspectY

Specifies the vertical aspect of the device for which the font was designed. The ratio of the tmDigitizedAspectX and tmDigitizedAspectY members is the aspect ratio of the device for which the font was designed.

tmFirstChar

Specifies the value of the first character defined in the font.

tmLastChar

Specifies the value of the last character defined in the font.

tmDefaultChar

Specifies the value of the character to be substituted for characters not in the font.

tmBreakChar

Specifies the value of the character that will be used to define word breaks for text justification.

tmItalic

Specifies an italic font if it is nonzero.

tmUnderlined

Specifies an underlined font if it is nonzero.

tmStruckOut

Specifies a strikeout font if it is nonzero.

tmPitchAndFamily

Specifies information about the pitch, the technology, and the family of a physical font.

The four low-order bits of this member specify information about the pitch and the technology of the font. A constant is defined for each of the four bits:

Constant	Meaning
TMPF_FIXED_PITCH	If this bit is set the font is a variable pitch font. If this bit is clear the font is a fixed pitch font. Note very carefully that those meanings are the opposite of what the constant name implies.
TMPF_VECTOR	If this bit is set the font is a vector font.
TMPF_TRUETYPE	If this bit is set the font is a TrueType font.
TMPF_DEVICE	If this bit is set the font is a device font.
An application should carefully test for qualities encoded in these low-order bits, making no arbitrary assumptions. For example, besides having their own bits set, TrueType and PostScript fonts set the TMPF_VECTOR bit. A monospace bitmap font has all of these low-order bits clear; a proportional bitmap font sets the TMPF_FIXED_PITCH bit. A Postscript printer device font sets the TMPF_DEVICE, TMPF_VECTOR, and TMPF_FIXED_PITCH bits.

The four high-order bits of tmPitchAndFamily designate the font’s font family. An application can use the value 0xF0 and the bitwise AND operator to mask out the four low-order bits of tmPitchAndFamily, thus obtaining a value that can be directly compared with font family names to find an identical match. For information about font families, see the description of the LOGFONT structure.

tmCharSet

Specifies the character set of the font.

See Also

GetTextMetrics, GetTextExtentPoint32, LOGFONT


TEXTRANGE

The TEXTRANGE structure receives a range of text from a rich edit control. This structure is filled in by the EM_GETTEXTRANGE message. The buffer pointed to by the lpstrText member must be large enough to receive all characters and the teminating null character.

pedef struct _textrange {

    CHARRANGE chrg;

    LPSTR lpstrText;

} TEXTRANGE;

Members

chrg

Range of characters to get.

lpstrText

Pointer to buffer to receive the text.

See Also

EM_GETTEXTRANGE


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

See Also

NetRemoteTOD


TIME_ZONE_INFORMATION

The TIME_ZONE_INFORMATION structure specifies information specific to the time zone.

typedef struct _TIME_ZONE_INFORMATION { // tzi

    LONG       Bias;

    WCHAR      StandardName[ 32 ];

    SYSTEMTIME StandardDate;

    LONG       StandardBias;

    WCHAR      DaylightName[ 32 ];

    SYSTEMTIME DaylightDate;

    LONG       DaylightBias;

} TIME_ZONE_INFORMATION;

Members

Bias

Specifies the current bias, in minutes, for local time translation on this computer. The bias is the difference, in minutes, between Coordinated Universal Time (UTC) and local time. All translations between UTC and local time are based on the following formula:

UTC = local time + bias

This member is required.

StandardName

Specifies a null-terminated string associated with standard time on this operating system. For example, this parameter could contain “EST” to indicate Eastern Standard Time. This string is not used by the operating system, so anything stored there by using the SetTimeZoneInformation function is returned unchanged by the GetTimeZoneInformation function. This string can be empty.

StandardDate

Specifies a SYSTEMTIME structure that contains a date and UTC when the transition from daylight time to standard time occurs on this operating system. If this date is not specified, the wMonth member in the SYSTEMTIME structure must be zero. If this date is specified, the DaylightDate value in the TIME_ZONE_INFORMATION structure must also be specified. Local time translations done during the standard-time range are relative to the supplied StandardBias value.

This member supports two date formats. Absolute format specifies an exact date and time when standard time begins. In this form, the wYear, wMonth, wDay, wHour, wMinute, wSecond, and wMilliseconds members of the SYSTEMTIME structure are used to specify an exact date.

Day-in-month format is specified by setting the wYear member to zero, setting the wDayOfWeek member to an appropriate weekday, and using a wDay value in the range 1 through 5 to select the correct day in the month. Using this notation, the first Sunday in April can be specified, as can the last Thursday in October (5 is equal to “the last”).

StandardBias

Specifies a bias value to be used during local time translations that occur during standard time. This member is ignored if a value for the StandardDate member is not supplied.

This value is added to the value of the Bias member to form the bias used during standard time. In most time zones, the value of this member is zero.

DaylightName

Specifies a null-terminated string associated with daylight time on this operating system. For example, this parameter could contain “PDT” to indicate Pacific Daylight Time. This string is not used by the operating system, so anything stored there by using the SetTimeZoneInformation function is returned unchanged by the GetTimeZoneInformation function. This string can be empty.

DaylightDate

Specifies a SYSTEMTIME structure that contains a date and UTC when the transition from standard time to daylight time occurs on this operating system. If this date is not specified, the wMonth member in the SYSTEMTIME structure must be zero. If this date is specified, the StandardDate value in the TIME_ZONE_INFORMATION structure must also be specified. Local time translations during the daylight-time range are relative to the supplied DaylightBias value. This member supports the absolute and day-in-month time formats described for the StandardDate member.

DaylightBias

Specifies a bias value to be used during local time translations that occur during daylight time. This member is ignored if a value for the DaylightDate member is not supplied.

This value is added to the value of the Bias member to form the bias used during daylight time. In most time zones, the value of this member is  − 60.

See Also

GetTimeZoneInformation, SetTimeZoneInformation, SYSTEMTIME


TOGGLEKEYS

The TOGGLEKEYS structure contains information about the ToggleKeys accessibility feature. When the ToggleKeys feature is on, the computer emits a high-pitched tone whenever the user turns on the CAPS LOCK, NUM LOCK, or SCROLL LOCK key, and a low-pitched tone whenever the user turns off one of those keys.

typedef struct tagTOGGLEKEYS {     // tk

    DWORD cbSize;

    DWORD dwFlags;

} TOGGLEKEYS;

Members

cbSize

Specifies the size, in bytes, of this structure.

dwFlags

A set of bit flags that specify properties of the ToggleKeys feature. The following bit flag values are defined:

Value	Meaning
TKF_AVAILABLE	If this flag is set, the ToggleKeys feature is available.
TKD_CONFIRMHOTKEY	Windows 95 only: A confirmation dialog box appears when the Togglekeys feature is activated by using the hot key.
TKF_HOTKEYACTIVE	If this flag is set, the user can turn the ToggleKeys feature on and off by holding down the NUM LOCK key for eight seconds.
TKF_HOTKEYSOUND	If this flag is set, the system plays a siren sound when the user turns the ToggleKeys feature on or off by using the hot key.
TKF_TOGGLEKEYSON	If this flag is set, the ToggleKeys feature is on.
Remarks

An application uses a TOGGLEKEYS structure when calling the SystemParametersInfo function with the wAction parameter set to SPI_GETTOGGLEKEYS or SPI_SETTOGGLEKEYS. When using SPI_GETTOGGLEKEYS, an application must specify the cbSize member of the TOGGLEKEYS structure; the SystemParametersInfo function fills the remaining members. An application must specify all structure members when using the SETTOGGLEKEYS value.

See Also

SystemParametersInfo


TOKEN_CONTROL

The TOKEN_CONTROL structure contains information that identifies an access token.

typedef struct _TOKEN_CONTROL { // tc

    LUID TokenId;

    LUID AuthenticationId;

    LUID ModifiedId;

    TOKEN_SOURCE TokenSource;

} TOKEN_CONTROL ;

Members

TokenId

Specifies a locally unique identifier (LUID) identifying this instance of the token object.

AuthenticationId

Specifies an LUID assigned to the session this token represents. There can be many tokens representing a single logon session.

ModifiedId

Specifies an LUID that changes each time the token is modified. An application can use this value as a test of whether a security context has changed since it was last used.

TokenSource

Specifies a TOKEN_SOURCE structure identifying the agency that issued the token. This information is used in audit logging.

See Also

LUID, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


TOKEN_DEFAULT_DACL

The TOKEN_DEFAULT_DACL structure specifies a discretionary access-control list (ACL).

typedef struct _TOKEN_DEFAULT_DACL {  // tdd

    PACL DefaultDacl;

} TOKEN_DEFAULT_DACL;

Members

DefaultDacl

Points to an ACL structure assigned by default to any objects created by the user represented by the access token.

Remarks

The GetTokenInformation function retrieves the default discretionary ACL for an access token, in the form of a TOKEN_DEFAULT_DACL structure. This structure is also used with the SetTokenInformation function to set the default discretionary ACL.

See Also

ACL, GetTokenInformation, SetTokenInformation, TOKEN_CONTROL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


TOKEN_GROUPS

The TOKEN_GROUPS structure contains information about a set of groups in an access token.

typedef struct _TOKEN_GROUPS { // tg

    DWORD GroupCount;

    SID_AND_ATTRIBUTES Groups[ANYSIZE_ARRAY];

} TOKEN_GROUPS;

Members

GroupCount

Specifies the number of groups in the access token.

Groups

Specifies an array of SID_AND_ATTRIBUTES structures containing a token’s group security identifiers (SIDs) and corresponding attributes.

The following attributes can be used with this parameter:

Value	Meaning
SE_GROUP_MANDATORY	The group cannot be disabled.
SE_GROUP_ENABLED_BY_DEFAULT	The group is enabled by default.
SE_GROUP_ENABLED	The group is enabled.
SE_GROUP_OWNER	The user is the owner of the group or the SID can be assigned as the owner of the token or objects.
SE_GROUP_LOGON_ID	The group is a logon identifier.
See Also

AdjustTokenGroups, SID_AND_ATTRIBUTES, TOKEN_CONTROL, TOKEN_DEFAULT_DACL, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


TOKEN_OWNER

The TOKEN_OWNER structure contains the default owner SID that will be applied to newly created objects.

typedef struct _TOKEN_OWNER { // to

    PSID Owner;

} TOKEN_OWNER;

Members

Owner

Points to a SID structure representing a user who will become the owner of any objects created by a process using this access token. The security identifier (SID) must be one of the user or group SIDs already in the token.

See Also

GetTokenInformation, SetTokenInformation, SID, TOKEN_CONTROL, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


TOKEN_PRIMARY_GROUP

The TOKEN_PRIMARY_GROUP structure specifies a group security identifier (SID) for an access token.

typedef struct _TOKEN_PRIMARY_GROUP { // tpg

    PSID PrimaryGroup;

} TOKEN_PRIMARY_GROUP;

Members

PrimaryGroup

Points to a SID structure representing a group that will become the primary group of any objects created by a process using this access token. The security identifier (SID) must be one of the group SIDs already in the token.

See Also

GetTokenInformation, SetTokenInformation, SID, TOKEN_CONTROL, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


TOKEN_PRIVILEGES

The TOKEN_PRIVILEGES structure contains information about a set of privileges for an access token.

typedef struct _TOKEN_PRIVILEGES { // tp

    DWORD PrivilegeCount;

    LUID_AND_ATTRIBUTES Privileges[ANYSIZE_ARRAY];

} TOKEN_PRIVILEGES;

Members

PrivilegeCount

Specifies the number of entries in the Privileges array.

Privileges

Specifies an array of LUID_AND_ATTRIBUTES structures. Each structure contains the LUID and attributes of a privilege. The attributes of a privilege can be a combination of the following values:

Attribute	Description
SE_PRIVILEGE_ENABLED_BY_DEFAULT
	The privilege is enabled by default.
SE_PRIVILEGE_ENABLED
	The privilege is enabled.
SE_PRIVILEGE_USED_FOR_ACCESS
	The privilege was used to gain access to an object or service. This flag is used to identify the relevant privileges in a set passed by a client application that may contain unnecessary privileges.
See Also

AdjustTokenPrivileges, GetTokenInformation, LUID, LUID_AND_ATTRIBUTES, PrivilegeCheck, PrivilegedServiceAuditAlarm, PRIVILEGE_SET, SetTokenInformation, TOKEN_CONTROL, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


TOKEN_SOURCE

The TOKEN_SOURCE structure identifies the source of an access token.

typedef struct _TOKEN_SOURCE { // ts

    Char Sourcename[8];

    LUID SourceIdentifier;

} TOKEN_SOURCE;

Members

SourceName

Specifies an 8-byte character string used to identify the source of an access token. This is used to distinguish between such sources as Session Manager, LAN Manager, and RPC Server. A string, rather than a constant, is used to identify the source so users and developers can make extensions to the system, such as by adding other networks, that act as the source of access tokens.

SourceIdentifier

Specifies a locally unique identifier (LUID) provided by the source component named by the SourceName member. This value aids the source component in relating context blocks, such as session-control structures, to the token. This value is typically, but not necessarily, an LUID.

See Also

GetTokenInformation, LUID, TOKEN_CONTROL, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


TOKEN_STATISTICS

The TOKEN_STATISTICS structure contains information about an access token. An application can retrieve this information by calling the GetTokenInformation function.

typedef struct _TOKEN_STATISTICS { // tst

    LUID  TokenId;

    LUID  AuthenticationId;

    LARGE_INTEGER ExpirationTime;

    TOKEN_TYPE    TokenType;

    SECURITY_IMPERSONATION_LEVEL ImpersonationLevel;

    DWORD DynamicCharged;

    DWORD DynamicAvailable;

    DWORD GroupCount;

    DWORD PrivilegeCount;

    LUID  ModifiedId;

} TOKEN_STATISTICS;

Members

TokenId

Specifies a locally unique identifier (LUID) that identifies this instance of the token object.

AuthenticationId

Specifies an LUID assigned to the session this token represents. There can be many tokens representing a single logon session.

ExpirationTime

Specifies the time at which this token expires. Expiration times for access tokens are not supported in the current version of Windows NT.

TokenType

Specifies a TOKEN_TYPE enumerated type indicating whether the token is a primary or impersonation token.

ImpersonationLevel

Specifies a SECURITY_IMPERSONATION_LEVEL enumerated type indicating the impersonation level of the token. This member is valid only if the TokenType is TokenImpersonation.

DynamicCharged

Specifies the amount, in bytes, of memory allocated for storing default protection and a primary group identifier.

DynamicAvailable

Specifies the portion of memory allocated for storing default protection and a primary group identifier not already in use. This value is returned as a count of free bytes.

GroupCount

Specifies the number of supplemental group security identifiers (SIDs) included in the token.

PrivilegeCount

Specifies the number of privileges included in the token.

ModifiedId

Specifies an LUID that changes each time the token is modified. An application can use this value as a test of whether a security context has changed since it was last used.

See Also

GetTokenInformation, LUID, SECURITY_IMPERSONATION_LEVEL, TOKEN_CONTROL, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_TYPE, TOKEN_USER


TOKEN_USER

The TOKEN_USER structure identifies the user associated with an access token.

typedef struct _TOKEN_USER { // tu

    SID_AND_ATTRIBUTES User;

} TOKEN_USER;

Members

User

Specifies an SID_AND_ATTRIBUTES structure representing the user associated with the access token. There are currently no attributes defined for user security identifiers (SIDs).

See Also

GetTokenInformation, SID_AND_ATTRIBUTES, TOKEN_CONTROL, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE


TOOLINFO

The TOOLINFO structure contains information about a tool in a tooltip control.

typedef struct {  // ti

    UINT      cbSize;

    UINT      uFlags;

    HWND      hwnd;

    UINT      uId;

    RECT      rect;

    HINSTANCE hinst;

    LPTSTR     lpszText;

} TOOLINFO, NEAR *PTOOLINFO, FAR *LPTOOLINFO;

Members

cbSize

Size, in bytes, of the TOOLINFO structure. This member must be specified.

uFlags

A set of bit flags. This member can be a combination of the following values:

Value	Meaning
TTF_IDISHWND	Indicates that the uId member is the window handle to the tool. If this flag is not set, uId is the identifier of the tool.
TTF_CENTERTIP	Centers the tooltip window below the tool specified by the uId member.
TTF_RTLREADING	Displays text using right-to-left reading order on Hebrew or Arabic systems.
TTF_SUBCLASS	Indicates that the tooltip control should subclass the tool's window to intercept messages, such as WM_MOUSEMOVE. If not set, you need to use the TTM_RELAYEVENT message to forward messages to the tooltip control. For a list of messages that a tooltip control processes, see TTM_RELAYEVENT.
hwnd

Handle to the window that contains the tool. If lpszText includes the LPSTR_TEXTCALLBACK value, this member identifies the window that receives TTN_NEEDTEXT notification messages.

uId

Application-defined identifier of the tool. If uFlags includes the TTF_IDISHWND value, uId must specify the window handle to the tool.

rect

Coordinates of the bounding rectangle of the tool. The coordinates are relative to the upper-left corner of the client area of the window identified by hwnd. If uFlags includes the TTF_IDISHWND value, this member is ignored.

hinst

Handle to the instance that contains the string resource for the tool. If lpszText specifies the identifier of a string resource, this member is used.

lpszText

Pointer to the buffer that contains the text for the tool, or identifier of the string resource that contains the text. If this member is set to the LPSTR_TEXTCALLBACK value, the control sends the TTN_NEEDTEXT notification message to the owner window to retrieve the text.

See Also

TTN_NEEDTEXT


TOOLTIPTEXT

The TOOLTIPTEXT structure identifies a tool for which text is to be displayed and receives the text for the tool.

typedef struct { // ttt

    NMHDR     hdr;

    LPTSTR    lpszText;

    char      szText[80];

    HINSTANCE hinst;

    UINT      uFlags;

} TOOLTIPTEXT, FAR *LPTOOLTIPTEXT;

Members

hdr

Specifies a NMHDR structure, which enables the tooltip control to pass a pointer to a TOOLTIPTEXT structure as the lParam parameter of a WM_NOTIFY message.

lpszText

Pointer to a string that contains or receives the text for a tool. If hinst specifies an instance handle, this member must be the identifier of a string resource.

szText

Buffer that receives the tooltip text. An application can copy the text to this buffer as an alternative to specifying a string address or string resource.

hinst

Handle to the instance that contains a string resource to be used as the tooltip text. If lpszText is the pointer to the tooltip text, this member is NULL.

uFlags

Flag that indicates how to interpret the idFrom member of the NMHDR structure that is included in the structure. If this member is the TTF_IDISHWND value, idFrom is the handle of the tool. Otherwise, idFrom is the identifier of the tool.

If this member is the TTF_RTLREADING value, text on Hebrew or Arabic systems is displayed using right-to-left reading order.

Remarks

This structure is used with the TTN_NEEDTEXT notification message.

See Also

NMHDR, TTN_NEEDTEXT, WM_NOTIFY


TPMPARAMS

The TPMPARAMS structure contains extended parameters for the TrackPopupMenuEx function.

typedef struct tagTPMPARAMS {

    UINT cbSize;

    RECT rcExclude;

} TPMPARAMS, FAR *LPTPMPARAMS;

Members

cbsize

Size of structure, in bytes.

rcExclude

Rectangle to exclude when positioning the window, in screen coordinates.

See Also

TrackPopupMenuEx, Rectangle


TRACKMOUSEEVENT [New - Windows NT]
TRACKMOUSEEVENT

[New - Windows NT]

The TRACKMOUSEEVENT structure is used by the TrackMouseEvent function to track when the mouse pointer leaves a window or hovers over a window for a specified amount of time.

typedef struct tagTRACKMOUSEEVENT {

    DWORD cbSize;

    DWORD dwFlags;

    HWND  hwndTrack;

    DWORD dwHoverTime;

} TRACKMOUSEEVENT, *LPTRACKMOUSEEVENT;

Members

cbSize

Specifies the size of the TRACKMOUSEEVENT structure.

dwFlags

Specifies the services requested. This member can be a combination of the following values:

Value	Meaning
TME_CANCEL	The caller wants to cancel a prior tracking request.  The caller should also specify the type of tracking that it wants to cancel. For example, to cancel hover tracking, the caller must pass the TME_CANCEL and TME_HOVER flags.
TME_HOVER	The caller wants hover notification. Notification is delivered as a WM_MOUSEHOVER message.  If the caller requests hover tracking while hover tracking is already active, the hover timer will be reset. This flag is ignored if the mouse pointer is not over the specified window or area.
TME_LEAVE	The caller wants leave notification. Notification is delivered as a WM_MOUSELEAVE message.  If the mouse is not over the specified window or area, a leave notification is generated immediately and no further tracking is performed.
TME_QUERY	The function fills in the structure instead of treating it as a tracking request. The structure is filled such that had that structure been passed to TrackMouseEvent it would generate the current tracking. The only anomaly is that the hover timeout returned is always the actual timeout and not HOVER_DEFAULT, if HOVER_DEFAULT was specified during the original TrackMouseEvent request.
hwndTrack

Specifies the handle of the window to track.

dwHoverTime

Specifies the hover timeout (if TME_HOVER was specified in dwFlags), in milliseconds. Can be HOVER_DEFAULT, which means to use the system default hover timeout.

Remarks

The system default hover timeout is initially the menu dropdown time, which is 400 milliseconds. You can call SystemParametersInfo and use SPI_GETMOUSEHOVERTIME to retrieve the default hover timeout.

The system default hover rectangle is the same as the double-click rectangle. You can call SystemParametersInfo and use SPI_GETMOUSEHOVERWIDTH and SPI_GETMOUSEHOVERHEIGHT to retrieve the size of the rectangle within which the mouse pointer has to stay for TrackMouseEvent to generate a WM_MOUSEHOVER message.

See Also

SystemParametersInfo,
TrackMouseEvent


TRANSMIT_FILE_BUFFERS

The TRANSMIT_FILE_BUFFERS structure specifies data to be transmitted before and after file data during a TransmitFile function file transfer operation.

typedef struct _TRANSMIT_FILE_BUFFERS {

    PVOID Head;

    DWORD HeadLength;

    PVOID Tail;

    DWORD TailLength;

} TRANSMIT_FILE_BUFFERS;

Members

Head

Pointer to a buffer that contains data to be transmitted before the file data is transmitted.

HeadLength

Specifies the number of bytes of data in the buffer pointed to by the Head member that are to be transmitted.

Tail

Pointer to a buffer that contains data to be transmitted after the file data is transmitted.

TailLength

Specifies the number of bytes of data in the buffer pointed to by the Tail member that are to be transmitted.

See Also

TransmitFile


TRUSTEE [New - Windows NT]
TRUSTEE

[New - Windows NT]

The TRUSTEE structure identifies a user account, group account, or a logon account for a program such as a Windows NT service. The structure can use a name or a security identifier (SID) to identify the trustee.

Access control functions, such as SetEntriesInAcl and GetExplicitEntriesFromAcl, use this structure to identify the logon account associated with the access-control or audit-control information in an EXPLICIT_ACCESS structure.

typedef struct _TRUSTEE

{

    PTRUSTEE                    pMultipleTrustee;

    MULTIPLE_TRUSTEE_OPERATION  MultipleTrusteeOperation;

    TRUSTEE_FORM                TrusteeForm;

    TRUSTEE_TYPE                TrusteeType;

    LPTSTR                      ptstrName;

} TRUSTEE;

Members

pMultipleTrustee

Pointer to a TRUSTEE structure that identifies a server account that can impersonate the user identified by the ptstrName member. Windows NT does not currently support this functionality; therefore, this member must be NULL.

MultipleTrusteeOperation

Specifies a value from the MULTIPLE_TRUSTEE_OPERATION enumeration type. Currently, this member must be NO_MULTIPLE_TRUSTEE.

TrusteeForm

Specifies a value from the TRUSTEE_FORM enumeration type that indicates whether the trustee is identified by name or by a SID.

TrusteeType

Specifies a value from the TRUSTEE_TYPE enumeration type that indicates whether the trustee is a user account, a group account, or the account type is unknown.

ptstrName

If TrusteeForm is TRUSTEE_IS_NAME, this member is a pointer to a null-terminated string that contains the name of the trustee.

If TrusteeForm is TRUSTEE_IS_SID, this member is a pointer to the SID of the trustee.

Remarks

A trustee name can have any of the following formats:

•	A fully qualified name, such as “g:\remotedir\abc”.

•	A Windows NT version 3.x or later domain account, such as “redmond\xyz”.

•	One of the predefined group names, such as “EVERYONE” or “GUEST”.

•	One of the following special names.

Name	Meaning
“CURRENT_USER”	Indicates the owner of the calling thread or process.
“CREATOR OWNER”	Indicates the CREATOR_OWNER security identifier. This is a SID used in inheritable ACEs. When a new object is created, the system replaces this SID with the SID of the user who created the object.
“CREATOR GROUP”	Indicates the CREATOR_GROUP security identifier. This is a SID used in inheritable ACEs. When a new object is created, the system replaces this SID with the primary group SID of the user who created the object.
A trustee SID can be any user or group SID. It can also be any of the universal, well-known SIDs. For more information, see Security Identifiers (SIDs).

See Also

ACL, EXPLICIT_ACCESS, GetExplicitEntriesFromAcl, MULTIPLE_TRUSTEE_OPERATION, SetEntriesInAcl, SID, TRUSTEE_FORM, TRUSTEE_TYPE


TTHITTESTINFO

The TTHITTESTINFO structure contains information that a tooltip control uses to determine whether a point is in the bounding rectangle of the specified tool. If the point is in the rectangle, the structure receives information about the tool.

typedef struct _TT_HITTESTINFO { // tthti

    HWND hwnd;

    POINT pt;

    TOOLINFO ti;

} TTHITTESTINFO, FAR * LPHITTESTINFO;

Members

hwnd

Handle to the tool or window with the specified tool.

pt

Client coordinates of the point to test.

ti

A TOOLINFO structure. If the point specified by pt is in the tool specified by hwnd, this structure receives information about the tool. Before sending the TTM_HITTEST message, set the cbSize member of this structure to sizeof(TOOLINFO).

Remarks

This structure is used with the TTM_HITTEST message.

See Also

TOOLINFO, TTM_HITTEST


TTPOLYCURVE

The TTPOLYCURVE structure contains information about a curve in the outline of a TrueType character.

typedef struct tagTTPOLYCURVE { // ttpc

    WORD    wType;

    WORD    cpfx;

    POINTFX apfx[1];

} TTPOLYCURVE, FAR* LPTTPOLYCURVE;

Members

wType

Specifies the type of curve described by the structure. This member can be one of the following values:

Value	Meaning
TT_PRIM_LINE	Curve is a polyline.
TT_PRIM_QSPLINE	Curve is a Bézier spline.
cpfx

Specifies the number of POINTFX structures in the array.

apfx

Specifies an array of POINTFX structures that define the polyline or Bézier spline.

Remarks

When an application calls the GetGlyphOutline function, a glyph outline for a TrueType character is returned in a TTPOLYGONHEADER structure, followed by as many TTPOLYCURVE structures as are required to describe the glyph. All points are returned as POINTFX structures and represent absolute positions, not relative moves. The starting point given by the pfxStart member of the TTPOLYGONHEADER structure is the point at which the outline for a contour begins. The TTPOLYCURVE structures that follow can be either polyline records or spline records.

Polyline records are a series of points; lines drawn between the points describe the outline of the character. Spline records represent the quadratic curves (that is, quadratic b-splines) used by TrueType.

See Also

GetGlyphOutline, POINTFX, TTPOLYGONHEADER


TTPOLYGONHEADER

The TTPOLYGONHEADER structure specifies the starting position and type of a contour in a TrueType character outline.

typedef struct _TTPOLYGONHEADER { // ttph

    DWORD   cb;

    DWORD   dwType;

    POINTFX pfxStart;

} TTPOLYGONHEADER, FAR* LPTTPOLYGONHEADER;

Members

cb

Specifies the number of bytes required by the TTPOLYGONHEADER structure and TTPOLYCURVE structure or structures required to describe the contour of the character.

dwType

Specifies the type of character outline returned. Currently, this value must be TT_POLYGON_TYPE.

pfxStart

Specifies the starting point of the contour in the character outline.

Remarks

Each TTPOLYGONHEADER structure is followed by one or more TTPOLYCURVE structures.

See Also

POINTFX, TTPOLYCURVE


TV_DISPINFO

The TV_DISPINFO structure retrieves and sets information about a tree-view item.

typedef struct _TV_DISPINFO {  tvdi

    NMHDR   hdr;

    TV_ITEM item;

} TV_DISPINFO;

Members

hdr

Specifies a NMHDR structure, which enables a tree-view control to pass a pointer to a TV_DISPINFO structure as the lParam parameter of a WM_NOTIFY message.

item

Specifies a TV_ITEM structure that identifies and contains information about the tree-view item. The mask member of the TV_ITEM structure specifies which information is being set or retrieved; it can be one or more of the following values:

Value	Meaning
TVIF_CHILDREN	The cChildren member specifies, or is to receive, a value that indicates whether the item has child items.
TVIF_IMAGE	The iImage member specifies, or is to receive, the index of the item’s non-selected icon in the image list.
TVIF_SELECTEDIMAGE	The iSelectedImage member specifies, or is to receive, the index of the item’s selected icon in the image list.
TVIF_TEXT	The pszText member specifies the new item text or the pointer to a buffer that is to receive the item text.
If the structure is receiving item text, you typically copy the text to the buffer pointed to by the pszText member of the TV_ITEM structure. However, you can return a string in the pszText member instead. If you do so, you cannot change or delete the string until the corresponding item text is deleted or until two additional TVN_GETDISPINFO notification messages have been sent.

Remarks

A pointer to a TV_DISPINFO structure is passed as the lParam parameter when a tree-view control sends a WM_NOTIFY message with the TVN_GETDISPINFO and TVN_SETDISPINFO notification codes. A tree-view control sends these notifications in the following situations in which the parent window of the control stores information about a tree-view item:

•	If the pszText member of the item’s TV_ITEM structure is the LPSTR_TEXTCALLBACK value, the control sends these notifications to retrieve or set the item’s text.

•	If the iImage or iSelectedImage member of the item’s TV_ITEM structure is the I_IMAGECALLBACK value, the control sends these notifications to retrieve or set the index of an item’s icons in the control’s image list.

•	If the cChildren member of the item’s TV_ITEM structure is the I_CHILDRENCALLBACK value, the control sends these notifications to retrieve or set a value that indicates whether the item has child items.

See Also

NMHDR, TV_ITEM, TVN_GETDISPINFO, TVN_SETDISPINFO, WM_NOTIFY


TV_HITTESTINFO

The TV_HITTESTINFO structure contains information used to determine the location of a point relative to a tree-view control.

typedef struct _TVHITTESTINFO {  tvhtst

    POINT     pt;

    UINT      flags;

    HTREEITEM hItem;

} TV_HITTESTINFO, FAR *LPTV_HITTESTINFO;

Members

pt

Client coordinates of point to test.

flags

Variable that receives information about the results of a hit test. This member can be one or more of the following values:

Value	Meaning
TVHT_ABOVE	Above the client area
TVHT_BELOW	Below the client area
TVHT_NOWHERE	In the client area, but below the last item
TVHT_ONITEM	On the bitmap or label associated with an item
TVHT_ONITEMBUTTON	On the button associated with an item
TVHT_ONITEMICON	On the bitmap associated with an item
TVHT_ONITEMINDENT	In the indentation associated with an item
TVHT_ONITEMLABEL	On the label (string) associated with an item
TVHT_ONITEMRIGHT	In the area to the right of an item
TVHT_ONITEMSTATEICON	On the state icon for a tree-view item that is in a user-defined state
TVHT_TOLEFT	To the right of the client area
TVHT_TORIGHT	To the left of the client area
hItem

Handle to the item that occupies the point.

Remarks

This structure is used with the TVM_HITTEST message.

See Also

TVM_HITTEST


TV_INSERTSTRUCT

The TV_INSERTSTRUCT structure contains information used to add a new item to a tree-view control.

typedef struct _TV_INSERTSTRUCT {  tvins

    HTREEITEM hParent;

    HTREEITEM hInsertAfter;

    TV_ITEM   item;

} TV_INSERTSTRUCT, FAR *LPTV_INSERTSTRUCT;

Members

hParent

Handle to the parent item. If this member is the TVI_ROOT value or NULL, the item is inserted at the root of the tree-view control.

hInsertAfter

Handle to the item after which the new item is to be inserted or one of the following values:

Value	Meaning
TVI_FIRST	Inserts the item at the beginning of the list.
TVI_LAST	Inserts the item at the end of the list.
TVI_SORT	Inserts the item into the list in alphabetical order.
item

Information about the item to add.

Remarks

This structure is used with the TVM_INSERTITEM message.

See Also

TVM_INSERTITEM


TV_ITEM

The TV_ITEM structure specifies or receives attributes of a tree-view item.

typedef struct _TV_ITEM {  tvi

    UINT       mask;

    HTREEITEM  hItem;

    UINT       state;

    UINT       stateMask;

    LPSTR      pszText;

    int        cchTextMax;

    int        iImage;

    int        iSelectedImage;

    int        cChildren;

    LPARAM     lParam;

} TV_ITEM, FAR *LPTV_ITEM;

Members

mask

Array of flags that indicate which of the other structure members contain valid data. When this structure is used with the TVM_GETITEM message, the mask member indicates the item attributes to retrieve. This member can be a combination of the following values:

Value	Meaning
TVIF_CHILDREN	The cChildren member is valid.
TVIF_HANDLE	The hItem member is valid.
TVIF_IMAGE	The iImage member is valid.
TVIF_PARAM	The lParam member is valid.
TVIF_SELECTEDIMAGE	The iSelectedImage member is valid.
TVIF_STATE	The state and stateMask members are valid.
TVIF_TEXT	The pszText and cchTextMax members are valid.
hItem

Identifies the item to which this structure refers.

state

Specifies the current state of the item if the item’s state is being retrieved, or the new state if the item’s state is being set. The stateMask member specifies the bits of the state member that are valid. This member can be any valid combination of state values. For a list of item states, see Tree-View Item States.

stateMask

Specifies the bits of the state member that are valid.

pszText

Pointer to a null-terminated string that contains the item text if the structure specifies item attributes. If this member is the LPSTR_TEXTCALLBACK value, the parent window is responsible for storing the name. In this case, the tree-view control sends the parent window a TVN_GETDISPINFO notification message when it needs the item text for displaying, sorting, or editing, and a TVN_SETDISPINFO notification message when the item text changes.

If the structure is receiving item attributes, this member is the pointer to the buffer that receives the item text.

cchTextMax

Size of the buffer pointed to by the pszText member if the structure is receiving item attributes. If the structure specifies item attributes, this member is ignored.

iImage

Index in the tree-view control’s image list of the icon image to use when the item is in the non-selected state.

If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the tree-view control sends the parent a TVN_GETDISPINFO notification message to get the index when it needs to display the image.

iSelectedImage

Index in the tree-view control’s image list of the icon image to use when the item is in the selected state.

If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the tree-view control sends the parent a TVN_GETDISPINFO notification message to get the index when it needs to display the image.

cChildren

Flag that indicates whether the item has associated child items. This member is one of the following values:

Value	Meaning
zero	The item has no child items.
1	The item has one or more child items.
I_CHILDRENCALLBACK	The parent window keeps track of whether the item has child items. In this case, when the tree-view control needs to display the item, the control sends the parent a TVN_GETDISPINFO notification message to determine whether the item has child items.
If the tree-view control has the TVS_HASBUTTONS style, it uses this member to determine whether to display the button indicating the presence of child items. You can use this member to force the control to display the button even though the item does not have any child items inserted. This allows you to display the button while minimizing the control’s memory usage by inserting child items only when the item is visible or expanded.

lParam

A 32-bit value to associate with the item.

Remarks

This structure is used with the TVM_GETITEM, TVM_SETITEM, and TVM_INSERTITEM messages. It is also included with many of the notification messages. When the structure is used to retrieve item information, only the structure members indicated by mask contain valid data. All other members are invalid.

See Also

TVN_GETDISPINFO, TVM_GETITEM, TVM_INSERTITEM, TVN_SETDISPINFO, TVM_SETITEM


TV_KEYDOWN

The TV_KEYDOWN structure contains information about a keyboard event in a tree-view control.

pedef struct _TV_KEYDOWN { tvkd

    NMHDR hdr;

    WORD  wVKey;

    UINT  flags;

} TV_KEYDOWN;

Members

hdr

Specifies a NMHDR structure, which enables a tree-view control to pass a pointer to a TV_KEYDOWN structure as the lParam parameter of a WM_NOTIFY message.

sVKey

Virtual key code.

flags

Always zero.

Remarks

This structure is used with the TVN_KEYDOWN notification message.

See Also

NMHDR, TVN_KEYDOWN, WM_NOTIFY


TV_SORTCB

The TV_SORTCB structure contains information used to sort child items in a tree-view control.

typedef struct _TV_SORTCB { tvscb

    HTREEITEM    hParent;

    PFNTVCOMPARE lpfnCompare;

    LPARAM       lParam;

} TV_SORTCB, FAR *LPTV_SORTCB;

Members

lpfnCompare

Pointer to an application-defined callback function, which is called during a sort operation each time the relative order of two list items needs to be compared. The callback function has the following form:

int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2,

LPARAM lParamSort);

The callback function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

The lParam1 and lParam2 parameters correspond to the lParam member of the TV_ITEM structure for the two items being compared. The lParamSort parameter corresponds to the lParam member of the TV_SORTCB structure that was passed with the TVM_SORTCHILDRENCB message.

hParent

Handle to the parent item.

lParam

Application-defined 32-bit value.

Remarks

This structure is used with the TVM_SORTCHILDRENCB message.

See Also

TV_ITEM, TVM_SORTCHILDRENCB


UDACCEL

The UDACCEL structure contains acceleration information for an up-down control.

typedef struct {

    UINT nSec;

    UINT nInc;

} UDACCEL;

Members

nSec

Amount of elapsed time, in seconds, before the position change increment specified by nInc is used.

nInc

Position change increment to use after the time specified by nSec elapses.


ULARGE_INTEGER

The ULARGE_INTEGER structure is used to specify a 64-bit unsigned integer value.

typedef union _ULARGE_INTEGER {

    struct {

        DWORD LowPart;

        DWORD HighPart;

    };

    DWORDLONG QuadPart;

} ULARGE_INTEGER;

Members

LowPart

Specifies the low-order 32 bits.

HighPart

Specifies the high-order 32 bits.

QuadPart

Specifies a 64-bit unsigned integer.

Remarks

The ULARGE_INTEGER structure is actually a union. If your compiler has built-in support for 64-bit integers, use the QuadPart member to store the 64-bit integer. Otherwise, use the LowPart and HighPart members to store the 64-bit integer.

See Also

LARGE_INTEGER


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

See Also

WNetGetUniversalName, REMOTE_NAME_INFO


UNLOAD_DLL_DEBUG_INFO

The UNLOAD_DLL_DEBUG_INFO structure contains information about a dynamic-link library (DLL) that has just been unloaded.

typedef struct _UNLOAD_DLL_DEBUG_INFO { // uddi

    LPVOID lpBaseOfDll;

} UNLOAD_DLL_DEBUG_INFO;

Members

lpBaseOfDll

Points to the base address of the DLL in the address space of the process unloading the DLL.

See Also

DEBUG_EVENT


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

See Also

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.

See Also

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.

See Also

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.

See Also

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, and Windows 95 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_PASSWRD_NOTREQD	No password is required.
UF_PASSWRD_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_PASSWORD	Represents the password, which should never expire on the account. This value is valid only for Windows NT.
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.

See Also

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, and Windows 95 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_PASSWRD_NOTREQD	No password is required.
UF_PASSWRD_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_PASSWORD	Represents the password, which should never expire on the account. This value is valid only for Windows NT.
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.

See Also

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, and Windows 95 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_PASSWRD_NOTREQD	No password is required.
UF_PASSWRD_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_PASSWORD	Represents the password, which should never expire on the account. This value is valid only for Windows NT.
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, 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 NetUserAdd 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.

See Also

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.

See Also

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.

See Also

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_PASSWRD_NOTREQD	No password is required.
UF_PASSWRD_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_PASSWORD	Represents the password, which should never expire on the account. This value is valid only for Windows NT.
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.

See Also

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.

See Also

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_PASSWRD_NOTREQD	No password is required.
UF_PASSWRD_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_PASSWORD	Represents the password, which should never expire on the account. This value is valid only for Windows NT.
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.

See Also

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, and Windows 95 clients to access a Windows NT server using the account.

See Also

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
See Also

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.

See Also

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.

See Also

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_PASSWRD_NOTREQD	No password is required.
UF_PASSWRD_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_PASSWORD	Represents the password, which should never expire on the account. This value is valid only for Windows NT.
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.
See Also

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.

See Also

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
See Also

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.

See Also

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.

See Also

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

See Also

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.

See Also

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.

See Also

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.


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.

See Also

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.

See Also

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.

See Also

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.


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.

See Also

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.


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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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.

See Also

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

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.

See Also

NetUserModalsSet


USEROBJECTFLAGS

The USEROBJECTFLAGS structure contains information about a window station or desktop handle.

typedef struct tagUSEROBJECTFLAGS {

    BOOL fInherit;

    BOOL fReserved;

    DWORD dwFlags;

} USEROBJECTFLAGS;

Members

fInherit

Specifies whether the handle is inherited when a new process is created. If this member is TRUE, new processes will inherit the handle.

fReserved

Reserved for future use. This member must be FALSE.

dwFlags

For window stations, this member can contain the following window station attribute flag:

Value	Description
WSF_VISIBLE	Window station has visible display surfaces.
For desktops, the dwFlags member can contain the following desktop control flag:

Value	Description
DF_ALLOWOTHERACCOUNTHOOK	Allows processes running in other accounts on the desktop to set hooks in this process.
See Also

CreateDesktop, GetUserObjectInformation, OpenDesktop, OpenInputDesktop, SetUserObjectInformation


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.

See Also

NetAlertRaise


VALENT

The VALENT structure contains information about a registry value. The RegQueryMultipleValues function uses this structure.

typedef struct value_ent {

    LPTSTR   ve_valuename;

    DWORD ve_valuelen;

    DWORD ve_valueptr;

    DWORD ve_type;

}VALENT;

Members

ve_valuename

Pointer to a null-terminated string. Before calling RegQueryMultipleValues, set this member to point to the name of a value to retrieve.

ve_valuelen

Specifies the size, in bytes, of the data pointed to by ve_valueptr.

ve_valueptr

Pointer to the data for the value entry. This is a pointer to the value’s data returned in the lpValueBuf buffer filled in by RegQueryMultipleValues.

ve_type

Specifies the type code for the value entry. The type code can be one of the following values:

Value	Meaning
REG_BINARY	Binary data in any form.
REG_DWORD	A 32-bit number.
REG_DWORD_LITTLE_ENDIAN	A 32-bit number in little-endian format (same as REG_DWORD). In little-endian format, the most significant byte of a word is the high-order byte. This is the most common format for computers running Windows NT and Windows 95.
REG_DWORD_BIG_ENDIAN	A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low-order byte.
REG_EXPAND_SZ	A null-terminated string that contains unexpanded references to environment variables (for example, “%PATH%”). It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
REG_LINK	A Unicode symbolic link.
REG_MULTI_SZ	An array of null-terminated strings, terminated by two null characters.
REG_NONE	No defined value type.
REG_RESOURCE_LIST	A device-driver resource list.
REG_SZ	A null-terminated string. It will be a Unicode or ANSI string, depending on whether you use the Unicode or ANSI functions.
See Also

RegQueryMultipleValues


Var

The Var structure depicts the organization of data in a file-version resource. This structure is not a true C-language structure because it contains variable-length members. This structure was created solely to depict the organization of data in a version resource and does not appear in any of the header files shipped with the Microsoft Win32 Software Development Kit (SDK).

The Var structure typically contains a list of languages that the version of the application or dynamic-link library (DLL) supports.

Var {

    WORD  wLength;

    WORD  wValueLength;

    WORD  wType;

    WCHAR szKey[];

    WORD  Padding[];

    WORD  Value[];

};

Members

wLength

Specifies the length of the version resource.

wValueLength

Specifies the length of the Value member in the current VS_VERSION_INFO structure. This value is zero if there is no Value member associated with the current version structure.

wType

Specifies the type of data in the version resource. This member is 1 if the version resource contains text data and 0 if the version resource contains binary data.

szKey

Contains the Unicode string “Translation” or a user-defined key string value.

Padding

Contains as many zero words as necessary to align the Value member on a 32-bit boundary.

Value

Specifies a list of one or more values that are typically language identifiers.

Remarks

If you use the Var structure to list the languages your application or DLL supports, a suggestion is that you use the Value member to contain an array of doubleword values indicating the language and code-page combinations supported by this file. The high-order word of each doubleword could contain a Microsoft language identifier and the low-order word could contain the IBM® code-page number. Either high-order or low-order word may be zero, indicating that the file is language or code-page independent. If this block is omitted, the file will be interpreted as language and code-page independent.

See Also

VarFileInfo, VS_VERSION_INFO


VarFileInfo

The VarFileInfo structure depicts the organization of data in a file-version resource. This structure is not a true C-language structure because it contains variable-length members. This structure was created solely to depict the organization of data in a version resource and does not appear in any of the header files shipped with the Microsoft Win32 Software Development Kit (SDK).

The VarFileInfo structure contains version information not dependent on a particular language and code page.

VarFileInfo {

    WORD  wLength;

    WORD  wValueLength;

    WORD  wType;

    WCHAR szKey[];

    WORD  Padding[];

    Var   Children[];

};

Members

wLength

Specifies the length of the version resource.

wValueLength

Specifies the length of the Value member in the current VS_VERSION_INFO structure. This value is zero if there is no Value member associated with the current version structure.

wType

Specifies the type of data in the version resource. This member is 1 if the version resource contains text data and 0 if the version resource contains binary data.

szKey

Contains the Unicode string “VarFileInfo”.

Padding

Contains as many zero words as necessary to align the Children member on a 32-bit boundary.

Children

Specifies a list of zero or more Var structures.

Remarks

The Children member of the VS_VERSION_INFO structure may contain zero or more VarFileInfo structures.

See Also

Var, VS_VERSION_INFO


VERIFY_INFORMATION

The VERIFY_INFORMATION structure provides information used to logically format a disk extent.

typedef struct _VERIFY_INFORMATION {

   LARGE_INTEGER  StartingOffset;

   DWORD  Length;

} VERIFY_INFORMATION ;

Members

StartingOffset

Specifies the starting offset of the disk extent.

Length

Length, in bytes, of the disk extent.

Remarks

The DeviceIoControl function uses a VERIFY_INFORMATION structure as input to an IOCTL_DISK_VERIFY device I/O operation.

See Also

DeviceIoControl, IOCTL_DISK_VERIFY


VS_FIXEDFILEINFO

The VS_FIXEDFILEINFO structure contains version information about a file. This information is language and code-page independent.

typedef struct _VS_FIXEDFILEINFO {  // vsffi

    DWORD dwSignature;

    DWORD dwStrucVersion;

    DWORD dwFileVersionMS;

    DWORD dwFileVersionLS;

    DWORD dwProductVersionMS;

    DWORD dwProductVersionLS;

    DWORD dwFileFlagsMask;

    DWORD dwFileFlags;

    DWORD dwFileOS;

    DWORD dwFileType;

    DWORD dwFileSubtype;

    DWORD dwFileDateMS;

    DWORD dwFileDateLS;

} VS_FIXEDFILEINFO;

Members

dwSignature

Contains the value 0xFEEFO4BD. This is used with the szKey member of VS_VERSION_INFO data when searching a file for the VS_FIXEDFILEINFO structure.

dwStrucVersion

Specifies the binary version number of this structure. The high-order word of this member contains the major version number, and the low-order word contains the minor version number.

dwFileVersionMS

Specifies the most significant 32 bits of the file’s binary version number. This member is used with dwFileVersionLS to form a 64-bit value used for numeric comparisons.

dwFileVersionLS

Specifies the least significant 32 bits of the file’s binary version number. This member is used with dwFileVersionMS to form a 64-bit value used for numeric comparisons.

dwProductVersionMS

Specifies the most significant 32 bits of the binary version number of the product with which this file was distributed. This member is used with dwProductVersionLS to form a 64-bit value used for numeric comparisons.

dwProductVersionLS

Specifies the least significant 32 bits of the binary version number of the product with which this file was distributed. This member is used with dwProductVersionMS to form a 64-bit value used for numeric comparisons.

dwFileFlagsMask

Contains a bitmask that specifies the valid bits in dwFileFlags. A bit is valid only if it was defined when the file was created.

dwFileFlags

Contains a bitmask that specifies the Boolean attributes of the file. This member can include one or more of the following values:

Flag	Description
VS_FF_DEBUG	The file contains debugging information or is compiled with debugging features enabled.
VS_FF_INFOINFERRED	The file’s version structure was created dynamically; therefore, some of the members in this structure may be empty or incorrect. This flag should never be set in a file’s VS_VERSION_INFO data.
VS_FF_PATCHED	The file has been modified and is not identical to the original shipping file of the same version number.
VS_FF_PRERELEASE	The file is a development version, not a commercially released product.
VS_FF_PRIVATEBUILD	The file was not built using standard release procedures. If this flag is set, the StringFileInfo structure should contain a PrivateBuild entry.
VS_FF_SPECIALBUILD	The file was built by the original company using standard release procedures but is a variation of the normal file of the same version number. If this flag is set, the StringFileInfo structure should contain a SpecialBuild entry.
dwFileOS

Specifies the operating system for which this file was designed. This member can be one of the following values:

Flag	Description
VOS_UNKNOWN	The operating system for which the file was designed is unknown to Windows.
VOS_NT	The file was designed for Windows NT.
VOS_WINDOWS32	The file was designed for the Win32 API.
An application can combine these values to indicate that the file was designed for one operating system running on another. The following dwFileOS values are examples of this, but are not a complete list:

Flag	Description
VOS_DOS_WINDOWS32	The file was designed for the Win32 API running on MS-DOS.
VOS_NT_WINDOWS32	The file was designed for the Win32 API running on Windows NT.
dwFileType

Specifies the general type of file. This member can be one of the following values:

Flag	Description
VFT_UNKNOWN	The file type is unknown to Windows.
VFT_APP	The file contains an application.
VFT_DLL	The file contains a dynamic-link library (DLL).
VFT_DRV	The file contains a device driver. If dwFileType is VFT_DRV, dwFileSubtype contains a more specific description of the driver.
VFT_FONT	The file contains a font. If dwFileType is VFT_FONT, dwFileSubtype contains a more specific description of the font file.
VFT_VXD	The file contains a virtual device.
VFT_STATIC_LIB	The file contains a static-link library.
All other values are reserved for future use by Microsoft.

dwFileSubtype

Specifies the function of the file. The possible values depend on the value of dwFileType. For all values of dwFileType not described in the following list, dwFileSubtype is zero.

If dwFileType is VFT_DRV, dwFileSubtype can be one of the following values:

Flag	Description
VFT2_UNKNOWN	The driver type is unknown by Windows.
VFT2_DRV_PRINTER	The file contains a printer driver.
VFT2_DRV_KEYBOARD	The file contains a keyboard driver.
VFT2_DRV_LANGUAGE	The file contains a language driver.
VFT2_DRV_DISPLAY	The file contains a display driver.
VFT2_DRV_MOUSE	The file contains a mouse driver.
VFT2_DRV_NETWORK	The file contains a network driver.
VFT2_DRV_SYSTEM	The file contains a system driver.
VFT2_DRV_INSTALLABLE	The file contains an installable driver.
VFT2_DRV_SOUND	The file contains a sound driver.
If dwFileType is VFT_FONT, dwFileSubtype can be one of the following values:

Flag	Description
VFT2_UNKNOWN	The font type is unknown by Windows.
VFT2_FONT_RASTER	The file contains a raster font.
VFT2_FONT_VECTOR	The file contains a vector font.
VFT2_FONT_TRUETYPE	The file contains a TrueType font.
If dwFileType is VFT_VXD, dwFileSubtype contains the virtual device identifier included in the virtual device control block.

All dwFileSubtype values not listed here are reserved for future use by Microsoft.

dwFileDateMS

Specifies the most significant 32 bits of the file’s 64-bit binary creation date and time stamp.

dwFileDateLS

Specifies the least significant 32 bits of the file’s 64-bit binary creation date and time stamp.

Remarks

The Value member of the VS_VERSION_INFO data is a VS_FIXEDFILEINFO structure.

See Also

StringFileInfo, VS_VERSION_INFO


VS_VERSION_INFO

The VS_VERSION_INFO structure depicts the organization of data in a file-version resource. This structure is not a true C-language structure because it contains variable-length members. This structure was created solely to depict the organization of data in a version resource and does not appear in any of the header files shipped with the Microsoft Win32 Software Development Kit (SDK).

VS_VERSION_INFO {

    WORD  wLength;

    WORD  wValueLength;

    WORD  wType;

    WCHAR szKey[];

    WORD  Padding1[];

    VS_FIXEDFILEINFO Value;

    WORD  Padding2[];

    WORD  Children[];

};

Members

wLength

Specifies the length of the VS_VERSION_INFO structure. This length does not include any padding that aligns the subsequent version structure on a 32-bit boundary.

wValueLength

Specifies the length of the Value member. This value is zero if there is no Value member associated with the current version structure.

wType

Specifies the type of data in the version resource. This member is 1 if the version resource contains text data and 0 if the version resource contains binary data.

szKey

Contains the Unicode string “VS_VERSION_INFO”.

Padding1

Contains as many zero words as necessary to align the Value member on a 32-bit boundary.

Value

Contains a VS_FIXEDFILEINFO structure that specifies arbitrary data associated with this structure. The wValueLength member specifies the length of this member; if wValueLength is zero, this member does not exist.

Padding2

Contains as many zero words as necessary to align the Children member on a 32-bit boundary. These bytes are not included in wValueLength. This member is optional.

Children

Specifies a list of zero or more StringFileInfo or VarFileInfo structures (or both) that are children of the current version structure.

Remarks

The VS_VERSION_INFO structure is the root structure that contains all other file information structures.

See Also

StringFileInfo, VarFileInfo, VS_FIXEDFILEINFO


WIN32_FILE_ATTRIBUTE_DATA [New - Windows NT]
WIN32_FILE_ATTRIBUTE_DATA

[New - Windows NT]

The WIN32_FILE_ATTRIBUTE_DATA structure contains attribute information for a file or directory. The GetFileAttributesEx function uses this structure.

The information contained in the WIN32_FILE_ATTRIBUTE_DATA structure is a superset of the information returned by the GetFileAttributes function.

typedef struct _WIN32_FILE_ATTRIBUTE_DATA{

    DWORD      dwFileAttributes;

    FILETIME   ftCreationTime;

    FILETIME   ftLastAccessTime;

    FILETIME   ftLastWriteTime;

    DWORD      nFileSizeHigh;

    DWORD      nFileSizeLow;

} WIN32_FILE_ATTRIBUTE_DATA, *LPWIN32_FILE_ATTRIBUTE_DATA;

Members

dwFileAttributes

A set of bit flags that specifies FAT-style attribute information for the file or directory. This is the same information that the GetFileAttributes function returns.

The following attribute flags are defined:

Value	Description
FILE_ATTRIBUTE_ARCHIVE	The file or directory is an archive file or directory. Applications use this flag to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED	The file or directory is compressed. For a file, this means that all data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_DIRECTORY	The “file or directory” is a directory.
FILE_ATTRIBUTE_HIDDEN	The file or directory is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL	The file or directory has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_OFFLINE	The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage.
FILE_ATTRIBUTE_READONLY	The file or directory is read-only. Applications can read from the file but cannot write to it or delete it. In the case of a directory, applications cannot delete it.
FILE_ATTRIBUTE_SYSTEM	The file or directory is part of, or is used exclusively by, the operating system.
FILE_ATTRIBUTE_TEMPORARY	The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed.
ftCreationTime

A FILETIME structure that specifies when the file or directory was created.

ftLastAccessTime

A FILETIME structure. For a file, the structure specifies when the file was last read from or written to. For a directory, the structure specifies when the directory was created. For both files and directories, the specified date will be correct, but the time of day will always be set to midnight.

ftLastWriteTime

A FILETIME structure. For a file, the structure specifies when the file was last written to. For a directory, the structure specifies when the directory was created.

nFileSizeHigh

Specifies the high-order DWORD of the file size. This member has no meaning for directories.

nFileSizeLow

Specifies the low-order DWORD of the file size. This member has no meaning for directories.

See Also

GetFileAttributesEx, GET_FILEEX_INFO_LEVELS


WIN32_FIND_DATA

The WIN32_FIND_DATA structure describes a file found by the FindFirstFile or FindNextFile function.

typedef struct _WIN32_FIND_DATA { // wfd

    DWORD dwFileAttributes;

    FILETIME ftCreationTime;

    FILETIME ftLastAccessTime;

    FILETIME ftLastWriteTime;

    DWORD    nFileSizeHigh;

    DWORD    nFileSizeLow;

    DWORD    dwReserved0;

    DWORD    dwReserved1;

    TCHAR    cFileName[ MAX_PATH ];

    TCHAR    cAlternateFileName[ 14 ];

} WIN32_FIND_DATA;

Members

dwFileAttributes

Specifies the file attributes of the file found. This member can be one or more of the following values:

Value	Meaning
FILE_ATTRIBUTE_ARCHIVE
	The file is an archive file. Applications use this value to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED
	The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_DIRECTORY
	The file is a directory.
FILE_ATTRIBUTE_HIDDEN
	The file is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL
	The file has no other attributes set. This value is valid only if used alone.
FILE_ATTRIBUTE_OFFLINE
	The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage.
FILE_ATTRIBUTE_READONLY
	The file is read-only. Applications can read the file but cannot write to it or delete it.
FILE_ATTRIBUTE_SYSTEM
	The file is part of the operating system or is used exclusively by it.
FILE_ATTRIBUTE_TEMPORARY
	The file is being used for temporary storage. Applications should write to the file only if absolutely necessary. Most of the file’s data remains in memory without being flushed to the media because the file will soon be deleted.
ftCreationTime

Specifies a FILETIME structure containing the time the file was created. FindFirstFile and FindNextFile report file times in Coordinated Universal Time (UTC) format. These functions set the FILETIME members to zero if the file system containing the file does not support this time member. You can use the FileTimeToLocalFileTime function to convert from UTC to local time, and then use the FileTimeToSystemTime function to convert the local time to a SYSTEMTIME structure containing individual members for the month, day, year, weekday, hour, minute, second, and millisecond.

ftLastAccessTime

Specifies a FILETIME structure containing the time that the file was last accessed. The time is in UTC format; the FILETIME members are zero if the file system does not support this time member.

ftLastWriteTime

Specifies a FILETIME structure containing the time that the file was last written to. The time is in UTC format; the FILETIME members are zero if the file system does not support this time member.

nFileSizeHigh

Specifies the high-order DWORD value of the file size, in bytes. This value is zero unless the file size is greater than MAXDWORD. The size of the file is equal to (nFileSizeHigh * MAXDWORD) + nFileSizeLow.

nFileSizeLow

Specifies the low-order DWORD value of the file size, in bytes.

dwReserved0

Reserved for future use.

dwReserved1

Reserved for future use.

cFileName

A null-terminated string that is the name of the file.

cAlternateFileName

A null-terminated string that is an alternative name for the file. This name is in the classic 8.3 (filename.ext) filename format.

Remarks

If a file has a long filename, the complete name appears in the cFileName field, and the 8.3 format truncated version of the name appears in the cAlternateFileName field. Otherwise, cAlternateFileName is empty. As an alternative, you can use the GetShortPathName function to find the 8.3 format version of a filename.

See Also

FindFirstFile, FindNextFile, FILETIME, FileTimeToLocalFileTime, FileTimeToSystemTime, GetShortPathName


WIN32_STREAM_ID

struct WIN32_STREAM_ID {

    DWORD dwStreamId;

    DWORD dwStreamAttributes;

    LARGE_INTEGER Size;

    DWORD dwStreamNameSize;

    WCHAR  cStreamName[ ] ;

}

Members

dwStreamId

Specifies the type of data. This member can be one of the following values:

Value	Meaning
BACKUP_DATA	Standard data
BACKUP_EA_DATA	Extended attribute data
BACKUP_SECURITY_DATA	Windows NT security descriptor data
BACKUP_ALTERNATE_DATA	Alternative data streams
BACKUP_LINK	Hard link information
dwStreamAttributes

Specifies the attributes of data to facilitate cross-operating system transfer. This member must be one or more of the following values:

Value	Description
STREAM_MODIFIED_WHEN_READ	Attribute set if the stream contains data that is modified when read. Allows the backup application to know that verification of data will fail.
STREAM_CONTAINS_SECURITY	Stream contains security data (general attributes). Allows the stream to be ignored on cross-operations restore.
Size

Specifies the size, in bytes, of data. Note that this is a 64-bit value.

dwStreamNameSize

Specifies the length of the name of the alternative data stream.

cStreamName

Specifies the name of the alternative data stream, in Unicode™.

See Also

BackupRead, BackupSeek, BackupWrite


WIN_CERTIFICATE [New - Windows NT]
WIN_CERTIFICATE

[New - Windows NT]

The WIN_CERTIFICATE structure contains the type and data for a WinTrust certificate. You can use this generic data structure to store certificates for a variety of WinTrust verification operations. A certificate typically contains encrypted information that can be used to identify and verify the authenticity of a subject, such as a software publisher or an executable file.

typedef struct _WIN_CERTIFICATE {

    DWORD       dwLength;

    WORD        wRevision;

    WORD        wCertificateType;

    BYTE        bCertificate[ANYSIZE_ARRAY];

} WIN_CERTIFICATE, *LPWIN_CERTIFICATE;

Members

dwLength

Specifies the size, in bytes, of the WIN_CERTIFICATE structure, including the data in the bCertificate array.

wRevision

Indicates the revision level of the structure. Currently, this value must be WIN_TRUST_REVISION_1_0.

wCertificateType

Specifies the type of certificate. This member can be one of the following values.

Value	Meaning
WIN_CERT_TYPE_X509	The certificate contains an X.509 Certificate.
WIN_CERT_TYPE_PKCS_SIGNED_DATA	The certificate contains a PKCS SignedData structure.
WIN_CERT_TYPE_RESERVED_1	Reserved.
bCertificate

A variable-sized array of bytes that contains the certificate data.

See Also

WinSubmitCertificate, WinTrustProviderSubmitCertificate, WinTrustSubjectCheckContentInfo, WinTrustSubjectGetCertHeader, WinTrustSubjectGetCertificate, WinTrustSubjectGetName


WIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT [New - Windows NT]
WIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT

[New - Windows NT]

The WIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT structure identifies the subject to be evaluated in some WinVerifyTrust verification operations. For example, Microsoft’s Software Publisher Trust Provider uses this structure with some of its action identifiers.

typedef struct _WIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT {

    HANDLE            hClientToken;

    GUID *            SubjectType;

    WIN_TRUST_SUBJECT Subject;

} WIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT, *LPWIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT ;

Members

hClientToken

Handle to the access token of the calling process.SubjectType

Pointer to a GUID structure that identifies the type of subject that a trust provider must evaluate. The value of this member determines the type of data pointed to by the Subject member.

The WinTrust service is designed to work with trust providers and subject interface packages (SIPs) implemented by third parties. Each SIP provides its own unique set of subject type identifiers, and each trust provider specifies the set of subject types that it can evaluate for a specified action identifier. For information about the subject and action identifiers supported by a trust provider, see the documentation for that trust provider.

For example, for the WIN_SPUB_ACTION_PUBLISHED_SOFTWARE action, Microsoft’s Software Publisher Trust Provider supports the following subject types.

Value	Description
WIN_TRUST_SUBJTYPE_PE_IMAGE
	Microsoft Portable Executable image files.
WIN_TRUST_SUBJTYPE_JAVA_CLASS
	Java class files.
WIN_TRUST_SUBJTYPE_CABINET
WIN_TRUST_SUBJTYPE_RAW_FILE
Subject

Pointer to a buffer that a trust provider uses to access the subject. The format of this data depends on the type of subject. For example, the subject types supported by the WIN_SPUB_ACTION_PUBLISHED_SOFTWARE action use a WIN_TRUST_SUBJECT_FILE structure that contains a handle or a path to the file to be evaluated.

Remarks

The WIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT structure is one of the data structures defined in WINBASE.H for use with the ActionData parameter of the WinVerifyTrust function. Trust providers can use one of the predefined structures, or define their own.

See Also

GUID, WIN_TRUST_ACTDATA_SUBJECT_ONLY, WIN_TRUST_SUBJECT_FILE, WinVerifyTrust


WIN_TRUST_ACTDATA_SUBJECT_ONLY [New - Windows NT]
WIN_TRUST_ACTDATA_SUBJECT_ONLY

[New - Windows NT]

The WIN_TRUST_ACTDATA_SUBJECT_ONLY structure is one of the structures defined in WINBASE.H for use with the ActionData parameter of the WinVerifyTrust function. Trust providers can use one of the predefined structures, or define their own.

typedef struct _WIN_TRUST_ACTDATA_SUBJECT_ONLY {

    GUID *            SubjectType;

    WIN_TRUST_SUBJECT Subject;

} WIN_TRUST_ACTDATA_SUBJECT_ONLY, *LPWIN_TRUST_ACTDATA_SUBJECT_ONLY;

Members

SubjectType

Pointer to a GUID structure that identifies the type of subject that a trust provider must evaluate. The value of this member determines the type of data pointed to by the Subject member.

The WinTrust service is designed to work with trust providers and subject interface packages (SIPs) implemented by third parties. Each SIP provides its own unique set of subject type identifiers, and each trust provider specifies the set of subject types that it can evaluate for a specified action identifier. For information about the subject and action identifiers supported by a trust provider, see the documentation for that trust provider.

Subject

Pointer to a buffer that a trust provider uses to access the subject. The format of this data depends on the type of subject.

See Also

GUID, WIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT, WinVerifyTrust


WIN_TRUST_SUBJECT_FILE [New - Windows NT]
WIN_TRUST_SUBJECT_FILE

[New - Windows NT]

The WIN_TRUST_SUBJECT_FILE structure identifies a file to be evaluated in a WinVerifyTrust verification operation. For example, Microsoft’s Software Publisher Trust Provider uses this structure for verification operations that require access to the software image to be evaluated.

typedef struct _WIN_TRUST_SUBJECT_FILE {

    HANDLE  hFile;

    LPCWSTR lpPath;

} WIN_TRUST_SUBJECT_FILE, *LPWIN_TRUST_SUBJECT_FILE;

Members

hFile

Handle to the file to evaluate in a WinVerifyTrust operation. The handle must have FILE_READ_DATA access to the file.

lpPath

Pointer to a null-terminated Unicode string that specifies the complete path of the file to evaluate.

Remarks

The WIN_TRUST_SUBJECT_FILE structure is one of the structures defined for use by trust providers to specify information about a subject to be evaluated in a trust inquiry. Trust providers can use this structure, or define their own.

See Also

WIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT, WinVerifyTrust


WIN_TRUST_SIP_SUBJECT [New - Windows NT]
WIN_TRUST_SIP_SUBJECT

[New - Windows NT]

The WIN_TRUST_SIP_SUBJECT structure identifies the subject to be evaluated by a Subject Interface Package (SIP). A SIP is a third-party component of the WinTrust service that can evaluate a subject to verify its authenticity.

typedef struct _WIN_TRUST_SIP_SUBJECT {

    GUID *                  SubjectType;

    WIN_TRUST_SUBJECT       Subject;

} WIN_TRUST_SIP_SUBJECT, *LPWIN_TRUST_SIP_SUBJECT;

Members

SubjectType

Pointer to a GUID structure that identifies the type of subject to be evaluated. The value of this member determines the type of data pointed to by the Subject member.

Each SIP supports a unique set of subject types that it can evaluate. For information about specific subject types, see the documentation for the individual SIPs.

Subject

Pointer to data that the SIP uses to access the subject. The format of this data depends on the type of subject.

See Also

WinTrustSubjectCheckContentInfo, WinTrustSubjectEnumCertificates, WinTrustSubjectGetCertHeader, WinTrustSubjectGetCertificate, WinTrustSubjectGetName


WINDOW_BUFFER_SIZE_RECORD

The WINDOW_BUFFER_SIZE_RECORD structure is used in a console INPUT_RECORD structure to report changes in the size of the screen buffer.

typedef struct _WINDOW_BUFFER_SIZE_RECORD { // wbsr

    COORD dwSize;

} WINDOW_BUFFER_SIZE_RECORD;

Members

dwSize

Specifies the new size of the screen buffer, in character cell columns and rows.

Remarks

Buffer size events are placed in the input buffer when the console is in window-aware mode (ENABLE_WINDOW_INPUT).

See Also

INPUT_RECORD, ReadConsoleInput


WINDOWPLACEMENT

The WINDOWPLACEMENT structure contains information about the placement of a window on the screen.

typedef struct _WINDOWPLACEMENT {     // wndpl

    UINT  length;

    UINT  flags;

    UINT  showCmd;

    POINT ptMinPosition;

    POINT ptMaxPosition;

    RECT  rcNormalPosition;

} WINDOWPLACEMENT;

Members

length

Specifies the length, in bytes, of the structure. Before calling the GetWindowPlacement or SetWindowPlacement functions, set this member to sizeof(WINDOWPLACEMENT).

GetWindowPlacement and SetWindowPlacement fail if this member is not set correctly.

flags

Specifies flags that control the position of the minimized window and the method by which the window is restored. This member can be one or both of the following values:

Value	Meaning
WPF_RESTORETOMAXIMIZED
	Specifies that the restored window will be maximized, regardless of whether it was maximized before it was minimized. This setting is only valid the next time the window is restored. It does not change the default restoration behavior. This flag is only valid when the SW_SHOWMINIMIZED value is specified for the showCmd member.
WPF_SETMINPOSITION
	Specifies that the coordinates of the minimized window may be specified. This flag must be specified if the coordinates are set in the ptMinPosition member.
showCmd

Specifies the current show state of the window. This member can be one of the following values:

Value	Meaning
SW_HIDE	Hides the window and activates another window.
SW_MINIMIZE	Minimizes the specified window and activates the top-level window in the system’s list.
SW_RESTORE	Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position (same as SW_SHOWNORMAL).
SW_SHOW	Activates a window and displays it in its current size and position.
SW_SHOWMAXIMIZED	Activates a window and displays it as a maximized window.
SW_SHOWMINIMIZED	Activates a window and displays it as an icon.
SW_SHOWMINNOACTIVE	Displays a window as an icon. The active window remains active.
SW_SHOWNA	Displays a window in its current state. The active window remains active.
SW_SHOWNOACTIVATE	Displays a window in its most recent size and position. The active window remains active.
SW_SHOWNORMAL	Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position (same as SW_RESTORE).
ptMinPosition

Specifies the coordinates of the window’s upper-left corner when the window is minimized.

ptMaxPosition

Specifies the coordinates of the window’s upper-left corner when the window is maximized.

rcNormalPosition

Specifies the window’s coordinates when the window is in the restored position.

See Also

ShowWindow, POINT, RECT


WINDOWPOS

The WINDOWPOS structure contains information about the size and position of a window.

typedef struct _WINDOWPOS { // wp

    HWND hwnd;

    HWND hwndInsertAfter;

    int  x;

    int  y;

    int  cx;

    int  cy;

    UINT flags;

} WINDOWPOS;

Members

hwnd

Identifies the window.

hwndInsertAfter

Specifies the position of the window in Z order (front-to-back position). This member can be the handle of the window behind which this window is placed, or can be one of the special values listed with the SetWindowPos function.

x

Specifies the position of the left edge of the window.

y

Specifies the position of the top edge of the window.

cx

Specifies the window width, in pixels.

cy

Specifies the window height, in pixels.

flags

Specifies the window position. This member can be one of the following values:

Value	Meaning
SWP_DRAWFRAME	Draws a frame (defined in the window’s class description) around the window.
SWP_FRAMECHANGED	Sends a WM_NCCALCSIZE message to the window, even if the window’s size is not being changed. If this flag is not specified, WM_NCCALCSIZE is sent only when the window’s size is being changed.
SWP_HIDEWINDOW	Hides the window.
SWP_NOACTIVATE	Does not activate the window. If this flag is not set, the window is activated and moved to the top of either the topmost or non-topmost group (depending on the setting of the hWndInsertAfter parameter).
SWP_NOCOPYBITS	Discards the entire contents of the client area. If this flag is not specified, the valid contents of the client area are saved and copied back into the client area after the window is sized or repositioned.
SWP_NOMOVE	Retains the current position (ignores the X and Y parameters).
SWP_NOOWNERZORDER	Does not change the owner window’s position in the Z order.
SWP_NOREDRAW	Does not redraw changes. If this flag is set, no repainting of any kind occurs. This applies to the client area, the nonclient area (including the title bar and scroll bars), and any part of the parent window uncovered as a result of the window being moved. When this flag is set, the application must explicitly invalidate or redraw any parts of the window and parent window that need redrawing.
SWP_NOREPOSITION	Same as the SWP_NOOWNERZORDER flag.
SWP_NOSENDCHANGING	Prevents the window from receiving the WM_WINDOWPOSCHANGING message.
SWP_NOSIZE	Retains the current size (ignores the cx and cy parameters).
SWP_NOZORDER	Retains the current Z order (ignores the hWndInsertAfter parameter).
SWP_SHOWWINDOW	Displays the window.
See Also

EndDeferWindowPos, SetWindowPos, WM_NCCALCSIZE


WINTRUST_CLIENT_TP_DISPATCH_TABLE [New - Windows NT]
WINTRUST_CLIENT_TP_DISPATCH_TABLE

[New - Windows NT]

The WINTRUST_CLIENT_TP_DISPATCH_TABLE structure contains a set of pointers to functions implemented by WinTrust for use by the client component of a trust provider. WinTrust passes a pointer to this dispatch table when it calls the WinTrustProviderClientInitialize function that the trust provider exports.

typedef struct _WINTRUST_CLIENT_TP_DISPATCH_TABLE

{

    LPWINTRUST_PROVIDER_PING                ServerPing;

    LPWINTRUST_SUBJECT_CHECK_CONTENT_INFO   CheckSubjectContentInfo;

    LPWINTRUST_SUBJECT_ENUM_CERTIFICATES    EnumSubjectCertificates;

    LPWINTRUST_SUBJECT_GET_CERTIFICATE      GetSubjectCertificate;

    LPWINTRUST_SUBJECT_GET_CERT_HEADER      GetSubjectCertHeader;

    LPWINTRUST_SUBJECT_GET_NAME             GetSubjectName;

} WINTRUST_CLIENT_TP_DISPATCH_TABLE, *LPWINTRUST_CLIENT_TP_DISPATCH_TABLE;

Members

ServerPing

Pointer to a WinTrustProviderPing function. The current release of WinTrust sets this member to NULL because it does not support the WinTrust server component.

CheckSubjectContentInfo

Pointer to a WinTrustSubjectCheckContentInfo function.

EnumSubjectCertificates

Pointer to a WinTrustSubjectEnumCertificates function.

GetSubjectCertificate

Pointer to a WinTrustSubjectGetCertificate function.

GetSubjectCertHeader

Pointer to a WinTrustSubjectGetCertHeader function.

GetSubjectName

Pointer to a WinTrustSubjectGetName function.

See Also

WINTRUST_CLIENT_TP_INFO, WinTrustProviderClientInitialize, WinTrustProviderPing, WinTrustSubjectCheckContentInfo, WinTrustSubjectEnumCertificates, WinTrustSubjectGetCertHeader, WinTrustSubjectGetCertificate, WinTrustSubjectGetName


WINTRUST_CLIENT_TP_INFO [New - Windows NT]
WINTRUST_CLIENT_TP_INFO

[New - Windows NT]

The WINTRUST_CLIENT_TP_INFO structure contains information that WinTrust passes to the client component of a trust provider. WinTrust passes a pointer to this structure when it calls the trust provider’s WinTrustProviderClientInitialize function.

typedef struct _WINTRUST_CLIENT_TP_INFO {

    DWORD                                   dwRevision;

    LPWINTRUST_CLIENT_TP_DISPATCH_TABLE     lpServices;

} WINTRUST_CLIENT_TP_INFO,  *LPWINTRUST_CLIENT_TP_INFO;

Members

dwRevision

Indicates the revision level of the WinTrust component that calls the trust provider’s WinTrustProviderClientInitialize function. WinTrust sets this value to WIN_TRUST_REVISION_1_0.

lpServices

Pointer to a WINTRUST_CLIENT_TP_DISPATCH_TABLE structure that contains a set of pointers to functions implemented by WinTrust for use by the client component of a trust provider.

See Also

WINTRUST_CLIENT_TP_DISPATCH_TABLE, WinTrustProviderClientInitialize


WINTRUST_PROVIDER_CLIENT_INFO [New - Windows NT]
WINTRUST_PROVIDER_CLIENT_INFO

[New - Windows NT]

The WINTRUST_PROVIDER_CLIENT_INFO structure contains information about the client component of a trust provider. The trust provider’s WinTrustProviderClientInitialize function passes WinTrust a pointer to this dispatch table.

typedef struct _WINTRUST_PROVIDER_CLIENT_INFO {

    DWORD                                   dwRevision;

    LPWINTRUST_PROVIDER_CLIENT_SERVICES     lpServices;

    DWORD                                   dwActionIdCount;

    GUID *                                  lpActionIdArray;

} WINTRUST_PROVIDER_CLIENT_INFO, *LPWINTRUST_PROVIDER_CLIENT_INFO;

Members

dwRevision

Indicates the revision level of the trust provider. Currently, a trust provider must set this value to WIN_TRUST_REVISION_1_0.

lpServices

Pointer to a WINTRUST_PROVIDER_CLIENT_SERVICES structure that contains pointers to a set of functions implemented by the trust provider. WinTrust can call these functions to access the services of the trust provider.

dwActionIdCount

Specifies the number of action identifier entries in the lpActionIdArray array.

lpActionIdArray

Pointer to an array of GUID pointers. Each GUID structure identifies an action that the trust provider can handle.

See Also

GUID, WINTRUST_PROVIDER_CLIENT_SERVICES, WinTrustProviderClientInitialize


WINTRUST_PROVIDER_CLIENT_SERVICES [New - Windows NT]
WINTRUST_PROVIDER_CLIENT_SERVICES

[New - Windows NT]

The WINTRUST_PROVIDER_CLIENT_SERVICES structure contains pointers to a set of functions implemented by a trust provider to be called by WinTrust. The trust provider’s WinTrustProviderClientInitialize function passes WinTrust a pointer to this dispatch table.

typedef struct _WINTRUST_PROVIDER_CLIENT_SERVICES

{

    LPWINTRUST_PROVIDER_CLIENT_UNLOAD       Unload;

    LPWINTRUST_PROVIDER_VERIFY_TRUST        VerifyTrust;

    LPWINTRUST_PROVIDER_SUBMIT_CERTIFICATE  SubmitCertificate;

} WINTRUST_PROVIDER_CLIENT_SERVICES, *LPWINTRUST_PROVIDER_CLIENT_SERVICES;

Members

Unload

Pointer to a WinTrustProviderClientUnload function.

VerifyTrust

Pointer to a WinTrustProviderVerifyTrust function.

SubmitCertificate

Pointer to a WinTrustProviderSubmitCertificate function.

See Also

WINTRUST_PROVIDER_CLIENT_INFO, WinTrustProviderClientInitialize, WinTrustProviderClientUnload, WinTrustProviderSubmitCertificate, WinTrustProviderVerifyTrust


WINTRUST_PROVIDER_SERVER_INFO [New - Windows NT]
WINTRUST_PROVIDER_SERVER_INFO

[New - Windows NT]

The WINTRUST_PROVIDER_SERVER_INFO structure contains information about the server component of a trust provider.

The current release of WinTrust does not include the WinTrust server component. Consequently, WinTrust does not currently use this structure.

typedef struct _WINTRUST_PROVIDER_SERVER_INFO {

    DWORD                                   dwRevision;

    LPWINTRUST_PROVIDER_SERVER_SERVICES     lpServices;

} WINTRUST_PROVIDER_SERVER_INFO, *LPWINTRUST_PROVIDER_SERVER_INFO;

Members

dwRevision

Indicates the revision level of the trust provider. Currently, a trust provider must set this value to WIN_TRUST_REVISION_1_0.

lpServices

Pointer to a WINTRUST_PROVIDER_SERVER_SERVICES structure that contains pointers to a set of functions implemented by the trust provider. WinTrust can call these functions to access the services of the trust provider.

See Also

WINTRUST_PROVIDER_SERVER_SERVICES, WinTrustProviderServerInitialize


WINTRUST_PROVIDER_SERVER_SERVICES [New - Windows NT]
WINTRUST_PROVIDER_SERVER_SERVICES

[New - Windows NT]

The WINTRUST_PROVIDER_SERVER_SERVICES structure contains a set of pointers to functions implemented by a trust provider to be called by WinTrust.

The current release of WinTrust does not include the WinTrust server component. Consequently, WinTrust does not call these functions and trust provider DLLs do not need to implement them.

typedef struct _WINTRUST_PROVIDER_SERVER_SERVICES

{

    LPWINTRUST_PROVIDER_SERVER_UNLOAD       Unload;

    LPWINTRUST_PROVIDER_PING                Ping;

} WINTRUST_PROVIDER_SERVER_SERVICES, *LPWINTRUST_PROVIDER_SERVER_SERVICES;

Members

Unload

Pointer to a WinTrustProviderServerUnload function.

Ping

Pointer to a WinTrustProviderPing function.

See Also

WINTRUST_PROVIDER_SERVER_INFO, WinTrustProviderPing, WinTrustProviderServerInitialize, WinTrustProviderServerUnload


WINTRUST_SERVER_TP_DISPATCH_TABLE [New - Windows NT]
WINTRUST_SERVER_TP_DISPATCH_TABLE

[New - Windows NT]

The WINTRUST_SERVER_TP_DISPATCH_TABLE structure contains a set of pointers to functions implemented by WinTrust for use by the server component of a trust provider.

The current release of WinTrust does not include the WinTrust server component. Consequently, WinTrust does not use this structure.

typedef struct _WINTRUST_SERVER_TP_DISPATCH_TABLE

{

    LPWINTRUST_SUBJECT_CHECK_CONTENT_INFO   CheckSubjectContentInfo;

    LPWINTRUST_SUBJECT_ENUM_CERTIFICATES    EnumSubectCertificates;

    LPWINTRUST_SUBJECT_GET_CERTIFICATE      GetSubjectCertificate;

    LPWINTRUST_SUBJECT_GET_CERT_HEADER      GetSubjectCertHeader;

    LPWINTRUST_SUBJECT_GET_NAME             GetSubjectName;

} WINTRUST_SERVER_TP_DISPATCH_TABLE, *LPWINTRUST_SERVER_TP_DISPATCH_TABLE;

Members

CheckSubjectContentInfo

Pointer to a WinTrustSubjectCheckContentInfo function.

EnumSubjectCertificates

Pointer to a WinTrustSubjectEnumCertificates function.

GetSubjectCertificate

Pointer to a WinTrustSubjectGetCertificate function.

GetSubjectCertHeader

Pointer to a WinTrustSubjectGetCertHeader function.

GetSubjectName

Pointer to a WinTrustSubjectGetName function.

See Also

WINTRUST_SERVER_TP_INFO, WinTrustProviderServerInitialize, WinTrustSubjectCheckContentInfo, WinTrustSubjectEnumCertificates, WinTrustSubjectGetCertHeader, WinTrustSubjectGetCertificate, WinTrustSubjectGetName


WINTRUST_SERVER_TP_INFO [New - Windows NT]
WINTRUST_SERVER_TP_INFO

[New - Windows NT]

The WINTRUST_SERVER_TP_INFO structure contains information that WinTrust passes to the server component of a trust provider.

The current release of WinTrust does not include the WinTrust server component. Consequently, WinTrust does not use this structure.

typedef struct _WINTRUST_SERVER_TP_INFO {

    DWORD                                   dwRevision;

    LPWINTRUST_SERVER_TP_DISPATCH_TABLE     lpServices;

} WINTRUST_SERVER_TP_INFO,  *LPWINTRUST_SERVER_TP_INFO;

Members

dwRevision

Indicates the revision level of WinTrust. Currently, WinTrust sets this value to WIN_TRUST_REVISION_1_0.

lpServices

Pointer to a WINTRUST_SERVER_TP_DISPATCH_TABLE structure that contains a set of pointers to functions implemented by WinTrust for use by the server component of a trust provider.

See Also

WINTRUST_SERVER_TP_DISPATCH_TABLE, WinTrustProviderServerInitialize


WINTRUST_SIP_DISPATCH_TABLE [New - Windows NT]
WINTRUST_SIP_DISPATCH_TABLE

[New - Windows NT]

The WINTRUST_SIP_DISPATCH_TABLE structure contains pointers to a set of functions implemented by a Subject Interface Package (SIP) to be called by WinTrust.

A pointer to this dispatch table is passed to WinTrust by the SIP’s WinTrustSipInitialize function.

typedef struct _WINTRUST_SIP_DISPATCH_TABLE

{

    LPWINTRUST_SUBJECT_CHECK_CONTENT_INFO   CheckSubjectContentInfo;

    LPWINTRUST_SUBJECT_ENUM_CERTIFICATES    EnumSubjectCertificates;

    LPWINTRUST_SUBJECT_GET_CERTIFICATE      GetSubjectCertificate;

    LPWINTRUST_SUBJECT_GET_CERT_HEADER      GetSubjectCertHeader;

    LPWINTRUST_SUBJECT_GET_NAME             GetSubjectName;

} WINTRUST_SIP_DISPATCH_TABLE, *LPWINTRUST_SIP_DISPATCH_TABLE;

Members

CheckSubjectContentInfo

Pointer to a WinTrustSubjectCheckContentInfo function that verifies whether a certificate adequately represents the contents of a subject.

EnumSubjectCertificates

Pointer to a WinTrustSubjectEnumCertificates function that retrieves the types of certificates that are bundled within a subject.

GetSubjectCertificate

Pointer to a WinTrustSubjectGetCertificate function that retrieves a certificate from a subject.

GetSubjectCertHeader

Pointer to a WinTrustSubjectGetCertHeader function that retrieves a certificate header from a subject.

GetSubjectName

Pointer to a WinTrustSubjectGetCertHeader function that retrieves the name of a subject.

See Also

WINTRUST_SIP_INFO, WinTrustSipInitialize


WINTRUST_SIP_INFO [New - Windows NT]
WINTRUST_SIP_INFO

[New - Windows NT]

The WINTRUST_SIP_INFO structure contains information about a Subject Interface Package (SIP). A pointer to this structure is passed to WinTrust by the SIP’s WinTrustSipInitialize function.

typedef struct _WINTRUST_SIP_INFO {

    DWORD                               dwRevision;

    LPWINTRUST_SIP_DISPATCH_TABLE       lpServices;

    DWORD                               dwSubjectTypeCount;

    GUID *                              lpSubjectTypeArray;

} WINTRUST_SIP_INFO, *LPWINTRUST_SIP_INFO;

Members

dwRevision

Indicates the revision level of the SIP. A SIP should set this value to WIN_TRUST_REVISION_1_0.

lpServices

Pointer to a WINTRUST_SIP_DISPATCH_TABLE structure that contains pointers to a set of functions implemented by the SIP for use by WinTrust.

dwSubjectTypeCount

Specifies the number of subject type entries in the lpSubjectTypeArray array.

lpSubjectTypeArray

Pointer to an array of GUID pointers. Each GUID structure identifies a subject type that the SIP can handle.

See Also

GUID, WINTRUST_SIP_DISPATCH_TABLE, WinTrustSipInitialize


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 LAN Manager software.

typedef struct _WKSTA_INFO_100 {
    DWORD     wki100_platform_id;
    LPTSTR    wki100_computername;
    LPTSTR    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 LAN Manager software running on the computer.

wki100_ver_minor

Specifies the minor version number of the LAN Manager software running on the computer.

See Also

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 LAN Manager software.

typedef struct _WKSTA_INFO_101 {
    DWORD     wki101_platform_id;
    LPTSTR    wki101_computername;
    LPTSTR    wki101_langroup;
    DWORD     wki101_ver_major;
    DWORD     wki101_ver_minor;
    LPTSTR    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 LAN Manager software running on the computer.

wki101_ver_minor

Specifies the minor version number of the LAN Manager software running on the computer.

wki101_lanroot

Points to a Unicode string that contains the path to the LANMAN directory.

See Also

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 LAN Manager software.

typedef struct _WKSTA_INFO_102 {
    DWORD     wki102_platform_id;
    LPTSTR    wki102_computername;
    LPTSTR    wki102_langroup;
    DWORD     wki102_ver_major;
    DWORD     wki102_ver_minor;
    LPTSTR    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 LAN Manager software running on the computer.

wki102_ver_minor

Specifies the minor version number of the LAN Manager software 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.

See Also

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 LAN Manager software.

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

See Also

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 LAN Manager software.

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

See Also

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;
    LPTSTR    wkti0_transport_name;
    LPTSTR    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.

See Also

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

See Also

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 LAN Manager domains accessed by the workstation, and user account information.

typedef struct _WKSTA_USER_INFO_1 {
    LPTSTR    wkui1_username;
    LPTSTR    wkui1_logon_domain;
    LPTSTR    wkui1_oth_domains;
    LPTSTR    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 LAN Manager 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.

See Also

NetWkstaUserEnum, NetWkstaUserGetInfo, NetWkstaUserSetInfo


WKSTA_USER_INFO_1101

The WKSTA_USER_INFO_1101 structure contains user information about the LAN Manager domains accessed by a workstation.

typedef struct _WKSTA_USER_INFO_1101 {
    LPTSTR    wkui1101_oth_domains;
} WKSTA_USER_INFO_1101, *PWKSTA_USER_INFO_1101, *LPWKSTA_USER_INFO_1101;

Members

wkui1101_oth_domains

Returns the list of other LAN Manager domains browsed by this workstation. The domain names are separated by blanks.

See Also

NetWkstaUserGetInfo, NetWkstaUserSetInfo


WNDCLASS

The WNDCLASS structure contains the window class attributes that are registered by the RegisterClass function.

typedef struct _WNDCLASS {    // wc

    UINT    style;

    WNDPROC lpfnWndProc;

    int     cbClsExtra;

    int     cbWndExtra;

    HANDLE  hInstance;

    HICON   hIcon;

    HCURSOR hCursor;

    HBRUSH  hbrBackground;

    LPCTSTR lpszMenuName;

    LPCTSTR lpszClassName;

} WNDCLASS;

Members

style

Specifies the class style(s). Styles can be combined by using the bitwise OR (|) operator. This member can be any combination of the following values:

Value	Action
CS_BYTEALIGNCLIENT	Aligns the window’s client area on the byte boundary (in the x direction) to enhance performance during drawing operations. This style affects the width of the window and its horizontal position on the display.
CS_BYTEALIGNWINDOW	Aligns a window on a byte boundary (in the x direction) to enhance performance during operations that involve moving or sizing the window. This style affects the width of the window and its horizontal position on the display.
CS_CLASSDC	Allocates one device context to be shared by all windows in the class. Because window classes are process specific, it is possible for multiple threads of a multithreaded application to create a window of the same class. It is also possible for the threads to attempt to use the device context simultaneously. When this happens, the operating system allows only one of the threads to successfully finish its drawing operation.
CS_DBLCLKS	Sends double-click messages to the window procedure when the user double-clicks the mouse while the cursor is within a window belonging to the class.
CS_GLOBALCLASS	Allows an application to create a window of the class regardless of the value of the hInstance parameter passed to the CreateWindow or CreateWindowEx function. If you do not specify this style, the hInstance parameter passed to the CreateWindow (or CreateWindowEx) function must be the same as the hInstance parameter passed to the RegisterClass function.
	You can create a global class by creating the window class in a dynamic-link library (DLL) and listing the name of the DLL in the registry under the following keys:
	HKEY_LOCAL_MACHINE\Software \Microsoft\Windows NT\ CurrentVersion\Windows\APPINIT_DLLS
	Whenever a process starts, the operating system loads the specified DLLs in the context of the newly started process before calling the main function in that process. The DLL must register the class during its initialization procedure and must specify the CS_GLOBALCLASS style.
CS_HREDRAW	Redraws the entire window if a movement or size adjustment changes the width of the client area.
CS_NOCLOSE	Disables the Close command on the System menu.
CS_OWNDC	Allocates a unique device context for each window in the class.
CS_PARENTDC	Sets the clipping region of the child window to that of the parent window so that the child can draw on the parent. A window with the CS_PARENTDC style bit receives a regular device context from the system’s cache of device contexts. It does not give the child the parent’s device context or device context settings. Specifying CS_PARENTDC enhances an application’s performance.
CS_SAVEBITS	Saves, as a bitmap, the portion of the screen image obscured by a window. Windows uses the saved bitmap to re-create the screen image when the window is removed. Windows displays the bitmap at its original location and does not send WM_PAINT messages to windows obscured by the window if the memory used by the bitmap has not been discarded and if other screen actions have not invalidated the stored image. This style is useful for small windows (for example, menus or dialog boxes) that are displayed briefly and then removed before other screen activity takes place. This style increases the time required to display the window, because the operating system must first allocate memory to store the bitmap.
CS_VREDRAW	Redraws the entire window if a movement or size adjustment changes the height of the client area.
lpfnWndProc

Points to the window procedure. For more information, see WindowProc.

cbClsExtra

Specifies the number of extra bytes to allocate following the window-class structure. The operating system initializes the bytes to zero.

cbWndExtra

Specifies the number of extra bytes to allocate following the window instance. The operating system initializes the bytes to zero. If an application uses the WNDCLASS structure to register a dialog box created by using the CLASS directive in the resource file, it must set this member to DLGWINDOWEXTRA.

hInstance

Identifies the instance that the window procedure of this class is within.

hIcon

Identifies the class icon. This member must be a handle of an icon resource. If this member is NULL, an application must draw an icon whenever the user minimizes the application’s window.

hCursor

Identifies the class cursor. This member must be a handle of a cursor resource. If this member is NULL, an application must explicitly set the cursor shape whenever the mouse moves into the application’s window.

hbrBackground

Identifies the class background brush. This member can be a handle to the physical brush to be used for painting the background, or it can be a color value. A color value must be one of the following standard system colors (the value 1 must be added to the chosen color). If a color value is given, you must convert it to one of the following HBRUSH types:

COLOR_ACTIVEBORDER
COLOR_ACTIVECAPTION
COLOR_APPWORKSPACE
COLOR_BACKGROUND
COLOR_BTNFACE
COLOR_BTNSHADOW
COLOR_BTNTEXT
COLOR_CAPTIONTEXT
COLOR_GRAYTEXT
COLOR_HIGHLIGHT
COLOR_HIGHLIGHTTEXT
COLOR_INACTIVEBORDER
COLOR_INACTIVECAPTION
COLOR_MENU
COLOR_MENUTEXT
COLOR_SCROLLBAR
COLOR_WINDOW
COLOR_WINDOWFRAME
COLOR_WINDOWTEXT

The operating system automatically deletes class background brushes when the class is freed. An application should not delete these brushes, because a class may be used by multiple instances of an application.

When this member is NULL, an application must paint its own background whenever it is requested to paint in its client area. To determine whether the background must be painted, an application can either process the WM_ERASEBKGND message or test the fErase member of the PAINTSTRUCT structure filled by the BeginPaint function.

lpszMenuName

Points to a null-terminated character string that specifies the resource name of the class menu, as the name appears in the resource file. If you use an integer to identify the menu, use the MAKEINTRESOURCE macro. If this member is NULL, windows belonging to this class have no default menu.

lpszClassName

Points to a null-terminated string or is an atom. If this parameter is an atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value, must be in the low-order word of lpszClassName; the high-order word must be zero.

If lpszClassName is a string, it specifies the window class name.

See Also

BeginPaint, CreateWindow, CreateWindowEx, GetDC, GlobalAddAtom, MAKEINTRESOURCE, PAINTSTRUCT, RegisterClass, WNDCLASSEX, WindowProc, WM_PAINT


WNDCLASSEX

The WNDCLASSEX structure contains window class information. It is used with the the RegisterClassEx and GetClassInfoEx functions.

The WNDCLASSEX structure is similar to the WNDCLASS structure. There are two differences. WNDCLASSEX includes the cbSize member, which specifies the size of the structure, and the hIconSm member, which contains a handle to a small icon associated with the window class.

typedef struct _WNDCLASSEX {    // wc

    UINT    cbSize;

    UINT    style;

    WNDPROC lpfnWndProc;

    int     cbClsExtra;

    int     cbWndExtra;

    HANDLE  hInstance;

    HICON   hIcon;

    HCURSOR hCursor;

    HBRUSH  hbrBackground;

    LPCTSTR lpszMenuName;

    LPCTSTR lpszClassName;

    HICON   hIconSm;

} WNDCLASSEX;

Members

cbSize

Specifies the size, in bytes, of this structure. Set this member to sizeof(WINDOWCLASSEX). Be sure to set this member before calling the GetClassInfoEx function.

style

Specifies the class style(s). Styles can be combined by using the bitwise OR (|) operator. This member can be any combination of the following values:

Value	Action
CS_BYTEALIGNCLIENT	Aligns the window’s client area on the byte boundary (in the x direction) to enhance performance during drawing operations. This style affects the width of the window and its horizontal position on the display.
CS_BYTEALIGNWINDOW	Aligns a window on a byte boundary (in the x direction) to enhance performance during operations that involve moving or sizing the window. This style affects the width of the window and its horizontal position on the display.
CS_CLASSDC	Allocates one device context to be shared by all windows in the class. Because window classes are process specific, it is possible for multiple threads of a multithreaded application to create a window of the same class. It is also possible for the threads to attempt to use the device context simultaneously. When this happens, the operating system allows only one of the threads to successfully finish its drawing operation.
CS_DBLCLKS	Sends double-click messages to the window procedure when the user double-clicks the mouse while the cursor is within a window belonging to the class.
CS_GLOBALCLASS	Allows an application to create a window of the class regardless of the value of the hInstance parameter passed to the CreateWindow or CreateWindowEx function. If you do not specify this style, the hInstance parameter passed to the CreateWindow (or CreateWindowEx) function must be the same as the hInstance parameter passed to the RegisterClass function.
	You can create a global class by creating the window class in a dynamic-link library (DLL) and listing the name of the DLL in the registry under the following keys:
	HKEY_LOCAL_MACHINE\Software \Microsoft\Windows NT\ CurrentVersion\Windows\APPINIT_DLLS
	Whenever a process starts, the operating system loads the specified DLLs in the context of the newly started process before calling the main function in that process. The DLL must register the class during its initialization procedure and must specify the CS_GLOBALCLASS style.
CS_HREDRAW	Redraws the entire window if a movement or size adjustment changes the width of the client area.
CS_NOCLOSE	Disables the Close command on the System menu.
CS_OWNDC	Allocates a unique device context for each window in the class.
CS_PARENTDC	Sets the clipping region of the child window to that of the parent window so that the child can draw on the parent. A window with the CS_PARENTDC style bit receives a regular device context from the system’s cache of device contexts. It does not give the child the parent’s device context or device context settings. Specifying CS_PARENTDC enhances an application’s performance.
CS_SAVEBITS	Saves, as a bitmap, the portion of the screen image obscured by a window. Windows uses the saved bitmap to re-create the screen image when the window is removed. Windows displays the bitmap at its original location and does not send WM_PAINT messages to windows obscured by the window if the memory used by the bitmap has not been discarded and if other screen actions have not invalidated the stored image. This style is useful for small windows (for example, menus or dialog boxes) that are displayed briefly and then removed before other screen activity takes place. This style increases the time required to display the window, because the operating system must first allocate memory to store the bitmap.
CS_VREDRAW	Redraws the entire window if a movement or size adjustment changes the height of the client area.
lpfnWndProc

Points to the window procedure. For more information, see WindowProc.

cbClsExtra

Specifies the number of extra bytes to allocate following the window-class structure. The operating system initializes the bytes to zero.

cbWndExtra

Specifies the number of extra bytes to allocate following the window instance. The operating system initializes the bytes to zero. If an application uses the WNDCLASS structure to register a dialog box created by using the CLASS directive in the resource file, it must set this member to DLGWINDOWEXTRA.

hInstance

Identifies the instance that the window procedure of this class is within.

hIcon

Identifies the class icon. This member must be a handle of an icon resource. If this member is NULL, an application must draw an icon whenever the user minimizes the application’s window.

hCursor

Identifies the class cursor. This member must be a handle of a cursor resource. If this member is NULL, an application must explicitly set the cursor shape whenever the mouse moves into the application’s window.

hbrBackground

Identifies the class background brush. This member can be a handle to the physical brush to be used for painting the background, or it can be a color value. A color value must be one of the following standard system colors (the value 1 must be added to the chosen color). If a color value is given, you must convert it to one of the following HBRUSH types:

COLOR_ACTIVEBORDER
COLOR_ACTIVECAPTION
COLOR_APPWORKSPACE
COLOR_BACKGROUND
COLOR_BTNFACE
COLOR_BTNSHADOW
COLOR_BTNTEXT
COLOR_CAPTIONTEXT
COLOR_GRAYTEXT
COLOR_HIGHLIGHT
COLOR_HIGHLIGHTTEXT
COLOR_INACTIVEBORDER
COLOR_INACTIVECAPTION
COLOR_MENU
COLOR_MENUTEXT
COLOR_SCROLLBAR
COLOR_WINDOW
COLOR_WINDOWFRAME
COLOR_WINDOWTEXT

The operating system automatically deletes class background brushes when the class is freed. An application should not delete these brushes, because a class may be used by multiple instances of an application.

When this member is NULL, an application must paint its own background whenever it is requested to paint in its client area. To determine whether the background must be painted, an application can either process the WM_ERASEBKGND message or test the fErase member of the PAINTSTRUCT structure filled by the BeginPaint function.

lpszMenuName

Points to a null-terminated character string that specifies the resource name of the class menu, as the name appears in the resource file. If you use an integer to identify the menu, use the MAKEINTRESOURCE macro. If this member is NULL, windows belonging to this class have no default menu.

lpszClassName

Points to a null-terminated string or is an atom. If this parameter is an atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value, must be in the low-order word of lpszClassName; the high-order word must be zero.

If lpszClassName is a string, it specifies the window class name.

hIconSm

Handle to a small icon that is associated with the window class. If this member is NULL, the system searches the icon resource specified by the hIcon member for an icon of the appropriate size to use as the small icon.

See Also

GetClassInfoEx, RegisterClassEx, WNDCLASS


XFORM

The XFORM structure specifies a world-space to page-space transformation.

typedef struct  _XFORM {  // xfrm

    FLOAT eM11;

    FLOAT eM12;

    FLOAT eM21;

    FLOAT eM22;

    FLOAT eDx;

    FLOAT eDy;

} XFORM;

Members

eM11

Specifies the following:

Operation	Meaning
Scaling	Horizontal scaling component
Rotation	Cosine of rotation angle
Reflection	Horizontal component
eM12

Specifies the following:

Operation	Meaning
Shear	Horizontal proportionality constant
Rotation	Sine of the rotation angle
eM21

Specifies the following:

Operation	Meaning
Shear	Vertical proportionality constant
Rotation	Negative sine of the rotation angle
eM22

Specifies the following:

Operation	Meaning
Scaling	Vertical scaling component
Rotation	Cosine of rotation angle
Reflection	Vertical reflection component
eDx

Specifies the horizontal translation component.

eDy

Specifies the vertical translation component.

Remarks

The following list describes how the members are used for each operation:

Operation	eM11	eM12	eM21	eM22
Rotation	Cosine	Sine	Negative sine	Cosine
Scaling	Horizontal scaling component	Nothing	Nothing	Vertical Scaling Component
Shear	Nothing	Horizontal Proportionality Constant	Vertical Proportionality Constant	Nothing
Reflection	Horizontal Reflection Component	Nothing	Nothing	Vertical Reflection Component
See Also

ExtCreateRegion, GetWorldTransform, ModifyWorldTransform, PlayEnhMetaFile, SetWorldTransform


Simple Types

Various simple data types define the size and meaning of parameters, return values, and members associated with the functions, messages, and structures of Microsoft Windows. The following table contains character, integer, and Boolean types; pointer types; and handles. The character, integer, and Boolean types are common to most C compilers. Many of the pointer-type names begin with a prefix of P or LP. A Windows-based application uses a handle to refer to a resource that has been loaded into memory. Windows provides access to these resources through internally maintained tables that contain individual entries for each handle. Each entry in the handle table contains the address of the resource and a means of identifying the resource type.

Type	Definition
ABORTPROC	Pointer to an application-defined callback function that the operating system calls when a print job is to be cancelled during spooling. See AbortProc for information on functions of this type.
ACMDRIVERENUMCB	Pointer to an application-defined callback function that is used with the acmDriverEnum function. See acmDriverEnumCallback for information on functions of this type.
ACMDRIVERPROC	Pointer to an application-defined callback function that is used with an installable audio compression manager (ACM) driver. See acmDriverProc for information on functions of this type.
ACMFILTERCHOOSEHOOKPROC	Pointer to an application-defined function that hooks the acmFilterChoose dialog box. See acmFilterChooseHookProc for information on functions of this type.
ACMFILTERENUMCB	Pointer to an application-defined callback function that is used with the acmFilterEnum function. See acmFilterEnumCallback for information on functions of this type.
ACMFILTERTAGENUMCB	Pointer to an application-defined callback function that is used with the acmFilterTagEnum function. See acmFilterTagEnumCallback for information on functions of this type.
ACMFORMATCHOOSEHOOKPROC	Pointer to an application-defined function that hooks the acmFormatChoose dialog box. See acmFormatChooseHookProc for information on functions of this type.
ACMFORMATENUMCB	Pointer to an application-defined callback function that is used with the acmFormatEnum function. See acmFormatEnumCallback for information on functions of this type.
ACMFORMATTAGENUMCB	Pointer to an application-defined callback function that is used with the acmFormatTagEnum function. See acmFormatTagEnumCallback for information on functions of this type.
APPLET_PROC	Pointer to a library-defined callback function that is the entry point for a Control Panel application. See CplApplet for information on functions of this type.
ATOM	Atom (a reference to a character string in an atom table).
BOOL	Boolean variable (should be TRUE or FALSE).
BOOLEAN	Boolean variable (should be TRUE or FALSE).
BYTE	Byte (8 bits).
CCHAR	Windows character.
CHAR	Windows character.
COLORREF	Red, green, blue (RGB) color value (32 bits).
CONST	Variable whose value is to remain constant during execution.
CRITICAL_SECTION	Critical-section object.
CTRYID	Country identifier.
DLGPROC	Pointer to an application-defined dialog box callback procedure.
DWORD	Doubleword (32 bits).
DWORDLONG	Double (64 bits).
EDITWORDBREAKPROC	Pointer to an application-defined callback function that the operating system calls when a multiline edit control needs to break a line of text. See EditWordBreakProc for information on functions of this type.
ENHMFENUMPROC	Pointer to an application-defined callback function that enumerates enhanced-metafile records.
ENUMRESLANGPROC	Pointer to an application-defined callback function that enumerates resource languages.
ENUMRESNAMEPROC	Pointer to an application-defined callback function that enumerates resource names.
ENUMRESTYPEPROC	Pointer to an application-defined callback function that enumerates resource types.
FARPROC	Pointer to a callback function.
FLOAT	Floating-point variable.
FONTENUMPROC	Pointer to an application-defined callback function that enumerates fonts.
GLOBALHANDLE	Handle of a global memory block.
GOBJENUMPROC	Pointer to an application-defined callback function that enumerates graphics device interface (GDI) objects.
GRAYSTRINGPROC	Pointer to an application-defined callback function that draws gray text.
HACCEL	Handle of an accelerator table.
HANDLE	Handle of an object.
HBITMAP	Handle of a bitmap.
HBRUSH	Handle of a brush.
HCOLORSPACE	Windows 95 only: Handle of a logical color space.
HCONV	Handle of a dynamic data exchange (DDE) conversation.
HCONVLIST	Handle of a DDE conversation list.
HCURSOR	Handle of a cursor.
HDC	Handle of a device context (DC).
HDDEDATA	Handle of DDE data.
HDWP	Handle of a deferred window position structure.
HENHMETAFILE	Handle of an enhanced metafile.
HFILE	Handle of a file.
HFONT	Handle of a font.
HGDIOBJ	Handle of a GDI object.
HGLOBAL	Handle of a global memory block.
HHOOK	Handle of a hook.
HICON	Handle of an icon.
HIMAGELIST	Handle to an image list.
HINSTANCE	Handle of an instance.
HKEY	Handle of a registry key.
HKL	Handle of a keyboard layout.
HLOCAL	Handle of a local memory block.
HMENU	Handle of a menu.
HMETAFILE	Handle of a metafile.
HMODULE	Handle of a module.
HOOKPROC	Pointer to an application-defined hook function.
HPALETTE	Handle of a palette.
HPEN	Handle of a pen.
HRGN	Handle of a region.
HRSRC	Handle of a resource.
HSZ	Handle of a DDE string.
HTREEITEM	Handle of an item in a tree-view control.
HWINSTA	Handle of a workstation.
HWND	Handle of a window.
INT	Signed integer.
IPADDR	A 32-bit value that contains an IP address. To convert this value to the “a.b.c.d” string form of an IP address, map the high-order byte to a, the low-order byte to d, and so on.
LANGID	Language identifier.
LCID	Locale identifier.
LCSCSTYPE	Color space type.
LCSGAMUTMATCH	Gamut-matching method.
LCTYPE	Locale type.
LINEDDAPROC	Pointer to a callback function that processes line coordinates.
LOCALHANDLE	Handle of a local memory block.
LONG	32-bit signed value.
LONGLONG	Double (64 bits).
LP	Pointer to a null-terminated Unicode™ string.
LPARAM	32-bit message parameter.
LPBOOL	Pointer to a Boolean variable.
LPBYTE	Pointer to a byte.
LPCCH	Pointer to a constant Windows character.
LPCCHOOKPROC	Pointer to an application-defined hook function.
LPCFHOOKPROC	Pointer to an application-defined hook function.
LPCH	Pointer to a Windows character.
LPCOLORREF	Pointer to a COLORREF value.
LPCRITICAL_SECTION	Pointer to a critical-section object.
LPCSTR	Pointer to a constant null-terminated Windows character string.
LPCTSTR	Pointer to a constant null-terminated Unicode or Windows character string.
LPCWCH	Pointer to a constant null-terminated Unicode character.
LPCWSTR	Pointer to a constant null-terminated Unicode character string.
LPDWORD	Pointer to an unsigned doubleword (32 bits).
LPFRHOOKPROC	Pointer to an application-defined hook function.
LPHANDLE	Pointer to a handle.
LPHANDLER_FUNCTION	Pointer to a handler function.
LPINT	Pointer to a signed integer.
LPLONG	Pointer to a signed long (32 bits).
LPOFNHOOKPROC	Pointer to an application-defined hook function.
LPPRINTHOOKPROC	Pointer to an application-defined hook function.
LPSETUPHOOKPROC	Pointer to an application-defined hook function.
LPSTR	Pointer to a null-terminated Windows character string.
LPTCH	Pointer to a Unicode character or a Windows character.
LPTSTR	Pointer to a null-terminated Windows or Unicode character string.
LRESULT	Signed result of message processing.
LPVOID	Pointer to any type.
LPWCH	Pointer to a Unicode character.
LPWORD	Pointer to an unsigned word (16 bits).
LPWSTR	Pointer to a null-terminated Unicode character string.
LUID	Locally unique identifier.
MFENUMPROC	Pointer to an application-defined callback function that enumerates metafile records.
NPSTR	Pointer to a null-terminated Windows character string.
NWPSTR	Pointer to a null-terminated Unicode string.
PBOOL	Pointer to a Boolean variable.
PBOOLEAN	Pointer to a Boolean variable.
PBYTE	Pointer to a byte.
PCCH	Pointer to a constant Windows character.
PCH	Pointer to a Windows character.
PCHAR	Pointer to a Windows character.
PCRITICAL_SECTION	Pointer to a critical-section object.
PCSTR	Pointer to a constant null-terminated Windows character string.
PCWCH	Pointer to a constant Unicode character.
PCWSTR	Pointer to a constant null-terminated Unicode character string.
PDWORD	Pointer to an unsigned doubleword (32 bits).
PFLOAT	Pointer to a floating-point variable.
PFNCALLBACK	Pointer to a callback function.
PHANDLE	Pointer to a handle.
PHANDLER_ROUTINE	Pointer to a handler routine.
PHKEY	Pointer to a registry key.
PINT	Pointer to a signed integer.
PLCID	Pointer to a locale identifier.
PLONG	Pointer to a signed long (32 bits).
PLUID	Pointer to a locally unique identifier (LUID).
PROC	Pointer to a callback function.
PROPENUMPROC	Pointer to an application-defined callback function that enumerates window properties. See PropEnumProc for information on functions of this type.
PROPENUMPROCEX	Pointer to an application-defined callback function that enumerates window properties. See PropEnumProcEx for information on functions of this type.
PSHORT	Pointer to a signed short (16 bits).
PSID	Pointer to a security identifier (SID).
PSTR	Pointer to a null-terminated Windows character string.
PSZ	Pointer to a null-terminated Windows character string.
PTBYTE	Pointer to a Windows or Unicode character.
PTCH	Pointer to a Windows or Unicode character.
PTCHAR	Pointer to a Windows or Unicode character.
PTSTR	Pointer to a null-terminated Windows or Unicode character string.
PUCHAR	Pointer to an unsigned Windows character.
PUINT	Pointer to an unsigned integer.
PULONG	Pointer to an unsigned long (32 bits).
PUSHORT	Pointer to an unsigned short (16 bits).
PVOID	Pointer to any type.
PWCH	Pointer to a Unicode character.
PWCHAR	Pointer to a Unicode character.
PWORD	Pointer to an unsigned word (16 bits).
PWSTR	Pointer to a null-terminated Unicode character string.
REGSAM	Security access mask for registry key.
SC_HANDLE	Handle of a service.
SENDASYNCPROC	Pointer to an application-defined callback function that the operating system calls when the SendMessageCallback function is called. The system passes the message to the callback function after passing the message to the destination window procedure. See SendAsyncProc for information on functions of this type.
SERVICE_STATUS_HANDLE	Handle of a service status value.
SHORT	Short integer.
SPHANDLE	Pointer to a handle.
TBYTE	Windows or Unicode character.
TCHAR	Unicode character or Windows character.
TIMERPROC	Pointer to an application-defined timer callback function.
UCHAR	Unsigned Windows character.
UINT	Unsigned integer.
ULONG	Unsigned long integer (32 bits).
USHORT	Unsigned short integer (16 bits).
VOID	Any type.
WCHAR	Unicode character.
WNDENUMPROC	Pointer to an application-defined callback function that enumerates windows.
WNDPROC	Pointer to an application-defined window procedure.
WORD	Unsigned word (16 bits).
WPARAM	32-bit message parameter.
YIELDPROC	Pointer to a yield callback function.


Command Window Interface

This section describes the commands that you can run in the Command window. It describes the commands that apply to debugging user-mode applications, as well as those that apply to debugging kernel-mode drivers.

You can use standard editing keys when you enter a command. Use the UP ARROW and DOWN ARROW keys to retrieve previous commands. Edit the current command line with the BACKSPACE, DELETE, INSERT, and LEFT ARROW and RIGHT ARROW keys. Press the ESC key to clear the current line.

To copy text from a previous line in the Command window, highlight the text by holding down the left mouse button and dragging the mouse pointer. Click the right mouse button to copy the highlighted text to the Clipboard. Click the right button again to paste the text into the current command line. You can use the same technique to copy text from other windows to the Command window. You can also press CTRL+INS to copy highlighted text to the Clipboard and press SHIFT+INS to paste text from the Clipboard to the insertion point.


Command Conventions

Many commands in this section use a specific range syntax or process and thread syntax.


Range Syntax

You can specify a range as either of the following:

•	startaddress endaddress

•	startaddress L length

With the first method, you specify the start and end addresses of the range. With the second method, you specify the start address, the letter “L,” and the number of data items in the range.

Note  With the DC (Display Memory) and the U (Unassemble) commands, you can also use the following to dump line instructions starting at startaddress:

startaddress I line


Process and Thread Syntax

You can specify a process in the following ways:

Symbol	Description
|.	The current process.
|number	The process number.
|*	All processes.
You can specify a thread in the following ways:

Symbol	Description
~.	The current thread.
~number	The thread ID.
~*	All threads.
If you do not specify a process or thread with a command, the command will act on the current process or thread. To set the current process or thread, enter a process or thread specifier alone on a command line.

To display the state of the processes or threads, type pipeline (|) or tilde (~) alone on the command line.

In kernel debugging, threads represent the physical processors of the target computer: a two-processor computer would have two threads, one for each processor. The single process represents the target computer itself.


Command List

The following table lists the commands that you can run in the Command window:

Command	Definition
*	Comment
;	Command Separator
?	Evaluate Expression
!	User Extension DLL
|	Display Process State
~	Display Thread State
#	Search for Disassembly Pattern
%	Change Context
.attach	Attach to Process
.cache	Cache Size
.list	Display Source/Assembly Listing
.logappend	Append Log File
.logclose	Close Log File
.logopen	Open Log File
.reboot	Reboot Target Machine
.reload	Reload Symbols
BC	Breakpoint Clear
BD	Breakpoint Disable
BE	Breakpoint Enable
BL	Breakpoint List
BP	Set Breakpoint
C	Compare Memory
DA, DB, DC, DD, DI, DS, DT, DU, DW	Display Memory
EA, EB, ED, EI, ES, ET, EU, EW	Enter Values
F	Freeze Thread
FIA, FIB, FID, FII, FIS, FIT, FIU, FIW	Fill Memory
FR	Floating-Point Registers
G	Go
GH	Go-- Exception Handled
GN	Go-- Exception not Handled
K, KB, KN, KS, KV	Display Stack Backtrace
L	Restart Debuggee
LM	List Loaded Modules
LN	List Nearest Symbols
M	Move Memory
N	Set Number Base
P	Program Step
Q	Quit WinDbg
R	Registers
REMOTE	Start Remote Server
RT	Register Display Toggle
S+, S-	Set Source/Assembly Mode
SA, SB, SD, SI, SS, ST, SU, SW	Search Memory
SEB, SEW	Set Error Break, Set Error Warning
SX, SXD, SXE, SXN	Set Exceptions
T	Trace
U	Unassemble
X	Examine Symbols
Z	Unfreeze Thread


* (Comment)

Syntax

*

Description

If this character is at the start of a line, then the rest of the line is treated as a comment.


; (Command Separator)

Syntax

;

Description

Use this character to separate multiple commands on a single line. Commands are executed sequentially from left to right. All commands on a single line refer to the current thread, unless otherwise specified. If a command causes the thread to execute, the remaining commands on the line will be deferred until that thread stops on a debug event.


? (Evaluate Expression)

Syntax

? expression [,format]

Parameters

expression

Expression to be evaluated with the expression evaluator.

format

C-style format characters. For example, to display a long int, use LI as the format specifier. Do not use percent signs (%).

Description

Evaluates and displays the value of the expression or symbol in the context of the current thread and process.

Note  The C++ expression evaluator cannot calculate expressions that use the conditional operator (?:).


! (User Extension DLL)

Syntax

! [filename.]function [string]

Parameters

filename

Name of the DLL to call (without the .DLL extension), followed by a period (.). The default filename is NTSDEXTS.DLL.

In kernel debugging, the default extension DLL depends upon the target platform:

Target platform	Default extension DLL
x86	KDEXTX86.DLL
MIPS	KDEXTMIP.DLL
ALPHA	KDEXTALP.DLL
function

Name of the DLL function to call.

string

String to pass to the DLL function.

Description

Calls a DLL function from WinDbg. Use this command to call special routines while debugging. For a complete list of the built-in extension commands, enter !? at the WinDbg prompt.


# (Search for Disassembly Pattern)

Syntax

# [pattern] [address]

Parameters

pattern

The pattern to search for in the Disassembly window.

address

The address after which to search.

Description

Displays the first line of assembly code after address that contains the specified pattern.


% (Change Context)

Syntax

%[frame]

Parameters

frame

The number of the frame on the call stack to change context to. The current procedure is number 0 on the stack.

Description

Changes the context to the specified frame. Updates the Locals window with the variables of the new frame.

Use the KN command to list the call stack with the frame numbers.


.attach (Attach to Process)

Syntax

.attach process

Parameter

process

Process ID of task to debug.

Description

Windows NT only: Starts debugging the process specified by process. You can use PView to find process IDs of running programs or use the Attach command from the Run menu to select a task.

This command is similar to the /P command-line option.


.cache (Cache Size)

Syntax

.cache [cachesize]

Parameter

cachesize

The size of the kernel debugging cache, in MB. If you do not specify cachesize, the command displays the status of the cache. If you issue .cache 0, the cache is disabled.

Description

Sets the size of the cache for WinDbg KD to use for memory values. Normal operations, such as single-stepping or the G command, invalidate the cache. If WinDbg KD has frozen the target computer, but hardware on the target can change memory (for example, through shared memory or DMA), you must disable the cache to see the memory changes.


.list (Display Source/Assembly Listing)

Syntax

.list [address]

Parameter

address

The address at which to start displaying the listing.

Description

Displays source-code lines and their corresponding assembly code, starting at address. If you do not specify address, the display starts from the current address.


.logappend (Append Log file)

Syntax

.logappend [filename]

Parameter

filename

Filename of the log file. The default filename is WINDBG.LOG.

Description

Sends a copy of the events and commands from the Command window to the given log file. If you are already logging, that log file will be closed. If filename already exists, new information will be appended to it.


.logclose (Close Log File)

Syntax

.logclose

Description

Closes any currently open log file.


.logopen (Open Log File)

Syntax

.logopen [filename]

Parameter

filename

Filename of the log file. The default filename is WINDBG.LOG.

Description

Sends a copy of the events and commands from the Command window to the given log file. If you are already logging, the current log file will be closed. If filename already exists, its contents will be overwritten.


.reboot (Reboot Target Machine)

Syntax

.reboot

Description

Reboots the target computer (WinDbg KD only).


.reload (Reload Symbols)

Syntax

.reload [modulename]

Parameter

modulename

The name of the module whose symbols you want to reload.

Description

Loads symbols for the specified module on the target system. If you do not specify modulename, the symbols for all loaded modules will be reloaded. This command is useful in the event of a system crash, which can result in the loss of symbols for the target computer.


BC (Breakpoint Clear)

Syntax

BC {breakpoint [breakpoint...] | *}

Parameter

breakpoint

The number of the breakpoint to be cleared. Use the Breakpoint List (BL) command to display currently set breakpoints and their numbers. Specify ranges of breakpoints with a hyphen. Separate multiple breakpoints with spaces or commas.

Description

Removes one or more previously set breakpoints from the system. BC* clears all breakpoints.


BD (Breakpoint Disable)

Syntax

BD {breakpoint [breakpoint...] | *}

Parameter

breakpoint

The number of the breakpoint to be disabled. Use the Breakpoint List (BL) command to display currently set breakpoints and their numbers. Specify ranges of breakpoints with a hyphen. Separate multiple breakpoints with spaces or commas.

Description

Disables, but does not delete, one or more breakpoints. BD* disables all breakpoints. While a breakpoint is disabled, the system does not check to see if the conditions specified in the breakpoint are valid.

Use the Breakpoint Enable (BE) command to reenable a disabled breakpoint.


BE (Breakpoint Enable)

Syntax

BE {breakpoint [breakpoint...] | *}

Parameter

breakpoint

The number of the breakpoint to be enabled. Use the Breakpoint List (BL) command to display currently set breakpoints and their numbers. Specify ranges of breakpoints with a hyphen. Separate multiple breakpoints with spaces or commas.

Description

Restores one or more breakpoints that were temporarily disabled by the Breakpoint Disable (BD) command. BE* enables all breakpoints.


BL (Breakpoint List)

Syntax

BL

Description

Lists all breakpoints. For each breakpoint, the command displays the following:

•	The breakpoint number

•	The breakpoint status, where “E” is for enabled, “D” is for disabled, “V” is for virtual, and “U” is for unknown address. A virtual breakpoint is a breakpoint for code that is not currently loaded.

•	The conditional information specifying the breakpoint, such as the address, expression, and length. If a breakpoint has a pass count, the remaining number of times that the breakpoint will be ignored is listed in parentheses.

BL also displays commands to execute, message/message classes (in the case of message breakpoints), thread and process number.


BP (Set Breakpoint)

Syntax

[thread] BP [breakpoint] [location] [condition] [option...]

Parameters

thread

The thread that the breakpoint will apply to. See Process and Thread Syntax for more information on the thread syntax.

breakpoint

The breakpoint number to be set. If the given breakpoint number already exists, the new breakpoint will replace the old.

location

The memory location of the breakpoint, in the format given in the table below.

condition

One of the breakpoint conditions given in the table below. You can specify multiple conditions for a breakpoint.

option

One of the breakpoint options given in the table below. Separate multiple options with spaces.

Description

Sets a breakpoint. You can combine locations, conditions, and options to set different kinds of breakpoints. If you do not specify a thread, the breakpoint will apply to all threads.

If you want to put a breakpoint on a C++ public, enclose the expression in parentheses. For example, “BP (??MyPublic)” or “BP (operator new)”.

On x86 computers, WinDbg will use debug registers to implement watchpoints if:

•	There is a debug register available

•	Memory size is 1

•	Memory size is 2 and address is WORD aligned

•	Memory size is 4 and address is DWORD aligned

You can use the following options when setting a breakpoint:

Location	Description
[{[procedure], [module], [exe]}]address	The address for the breakpoint.
[{[procedure], [module],  [exe]}]@line	The line number for the breakpoint.
Condition	Description
?expression	Break if expression is true.
=address [/Rcount]	Break if memory at address has changed. Use the /R option to specify the number of bytes to check (default is 1).
Option	Description
/Pcount	Ignore the breakpoint count times.
/Ccmdlist	Execute cmdlist when the breakpoint is hit. The cmdlist parameter is a semicolon-separated list of one or more debugger commands. If cmdlist includes multiple commands, enclose it in quotes (").
/Mmessagename /Mmessageclass	Break only if the given message name or message class has been received.
/Q	Suppress the unresolved-breakpoint dialog box for this breakpoint.
/Hprocess	Specify the process number to attach the breakpoint to. Defaults to all threads in process if /T is not used. If /H is not specified and no debuggee is running, the default is process 0.
/Tthread	Specify the thread number to attach the breakpoint to. Defaults to current process if /H is not used.


C (Compare Memory)

Syntax

C range address

Parameters

range

The first memory area to compare. See Range Syntax for information on the range syntax.

address

The starting address of the second memory area.

Description

Compares the values held in two memory areas. Specify the first area with the range parameter. Specify the starting address of the second area with address. The second area is the same length as the first. If the two areas are not identical, WinDbg will display all memory addresses in range where they do not agree.


DA, DB, DC, DD, DI, DS, DT, DU, DW (Display Memory)

Syntax

D{A | B | C | D | I | S | T | U | W} [[range]]

Parameters

range

The memory area to display. See Range Syntax for information on the range syntax.

Description

Displays the contents of memory in the given range. Each line shows the address of the first byte in the line, followed by the contents of memory at that and following locations.

If you omit range, the command will display memory starting at the ending location of the last Display command. This allows you to continuously scan through memory.

When WinDbg is displaying ANSI or Unicode characters, it will stop displaying characters at the first null byte. When displaying ANSI characters, all characters, including non-printable characters, are displayed using the current code page character set. With Unicode, all nonprintable and nonmappable characters are displayed as dots.

Command	Definition	Displays
DA	Display ANSI	ANSI (extended ASCII) characters
DB	Display Bytes (char)	Byte values and ANSI characters
DC	Display Code	Assembly-language instructions (disassembly)
DD	Display Doublewords  (long)	Doubleword (4-byte) values and ANSI characters
DI	Display 8-Byte Reals (double)	8-byte hexadecimal values and floating-point representations
DS	Display 4-Byte Reals  (float)	4-byte hexadecimal values and floating-point representations
DT	Display 10-Byte Reals  (long double)	10-byte hexadecimal values and floating-point representations
DU	Display Unicode	Unicode characters
DW	Display Words (short)	Word values and Unicode characters
Note  With the DC (Dump Code) command, you can use the standard range syntax or startaddress I line to dump line instructions starting at startaddress.


EA, EB, ED, EI, ES, ET, EU, EW (Enter Values)

Syntax

E{A | B | D | I | S | T | U | W} address [[values]]

Parameters

address

The starting address to enter values.

values

One or more values to enter into memory. Separate multiple numeric values with spaces.

Description

Enters the values that you specify into memory. If you do not specify any values, the current address and the value at that address will be displayed. You can then enter a new value, preserve the current value in memory by pressing the space bar, or stop entering data by pressing ENTER alone.

When entering numeric values, you can use C-style radix prefixes to override the default radix. Prefix octal constants with a “0o” (for example 0o1776), hexadecimal constants with “0x” (for example 0xF000), and decimal constants with “0t” (for example 0t199).

When entering ANSI or Unicode values, you can include space (" ") characters by enclosing the character string in quotation marks (" or '). If you enclose the string in double quotation marks, WinDbg will automatically null-terminate the string. Single quotation marks (') will not add a null character. You can enter standard C escape characters, such as \t, \007, and \".

Command	Definition	Enter
EA	Enter ANSI	ANSI (extended ASCII) characters
EB	Enter Bytes (char)	Byte values
ED	Enter Doublewords (long)	Doubleword (4-byte) values
EI	Enter 8-Byte Reals (double)	Floating-point numbers
ES	Enter 4-Byte Reals (float)	Floating-point numbers
ET	Enter 10-Byte Reals (long double)	Floating-point numbers
EU	Enter Unicode	Unicode characters
EW	Enter Words (short)	Word values


F (Freeze Thread)

Syntax

[[thread]] F

Parameter

thread

The thread to be frozen. See Process and Thread Syntax for information on the thread syntax.

Description

Freezes the given thread, causing it to wait until it is unfrozen. Other threads will continue to execute. If no thread is specified, the current thread is frozen.

Use the Z (Unfreeze) command to reenable the thread.


FIA, FIB, FID, FII, FIS, FIT, FIU, FIW (Fill Memory)

Syntax

FI{A | B | D | I | S | T | U | W} range pattern

Parameters

range

The memory area to fill. See Range Syntax for information on the range syntax.

pattern

One or more values to fill memory with. Separate multiple numeric values with spaces.

Description

Fills the memory area specified by range with the user-specified pattern. The entire range will be filled by repeatedly storing pattern into memory.

When entering numeric values, you can use C-style radix prefixes to override the default radix. Prefix octal constants with a “0o” (for example 0o1776), hexadecimal constants with “0x” (for example 0xF000), and decimal constants with “0t” (for example 0t199).

When entering ANSI or Unicode values, you can include space (" ") characters by enclosing the character string in quotation marks (" or '). If you enclose the string in double quotation marks, WinDbg will automatically null-terminate the string. Single quotation marks (') will not add a null character. Standard C escape characters (such as \t, \007, and \") are also allowed.

Command	Definition	Fill
FIA	Fill ANSI	ANSI (extended ASCII) characters
FIB	Fill Bytes (char)	Byte values
FID	Fill Doublewords (long)	Doubleword (4-byte) values
FII	Fill 8-Byte Reals (double)	Floating-point numbers
FIS	Fill 4-Byte Reals (float)	Floating-point numbers
FIT	Fill 10-Byte Reals (long double)	Floating-point numbers
FIU	Fill Unicode	Unicode characters
FIW	Fill Words (short)	Word values


FR (Floating-Point Registers)

Syntax

[[thread]] FR [[register [[=value]] ]]

Parameters

thread

The thread from which the floating-point registers are to be read. See Process and Thread Syntax for information on the thread syntax.

register

The floating-point register to display or modify.

value

The floating-point value to assign to register.

Description

Displays or modifies floating-point registers. If no thread is specified, the current thread is used.

If you do not specify a register, all of the floating-point registers are displayed. If you specify a register, the command displays the current value of the register and prompts for a new value. If you specify both a register and a value, the command changes the register to contain the value.

Use the R command to view and modify standard registers.


G (Go)

Syntax

[[process|thread]] G [[breakaddress]]

Parameters

process

The process to execute. See Process and Thread Syntax for information on the process syntax.

thread

The thread to execute. See Process and Thread Syntax for information on the thread syntax.

breakaddress

The address for an unconditional breakpoint.

Description

Starts executing the given process or thread. Execution will halt at the end of the program, when breakaddress is hit, or when another event causes the debugger to stop.

Note  The breakpoint associated with breakaddress will only be hit by the current thread. Other threads that execute the code at that location will not be stopped.


GH (Go Exception Handled)

Syntax

[[thread]] GH

Parameter

thread

The thread to execute. This thread must have been stopped by an exception. See Process and Thread Syntax for information on the thread syntax.

Description

Marks the given thread’s exception as being handled and allows the thread to continue execution at the instruction that caused the exception. This allows the debuggee to handle the exception. You can also use Go Handled from the Run menu to mark the exception as handled.

Use the GN (Go Exception Not Handled) command to continue execution without marking the exception as handled.


GN (Go Exception Not Handled)

Syntax

[[thread]] GN

Parameter

thread

The thread to execute. This thread must have been stopped by an exception. See Process and Thread Syntax for information on the thread syntax.

Description

Continues execution of the given thread without marking the exception as having been handled. This allows the debuggee’s exception handler to handle the exception. You can also use Go Unhandled from the Run menu to continue the exception.

Use the GH (Go Exception Handled) command to continue execution after marking the exception as having been handled.


K, KB, KN, KS, KV (Display Stack Backtrace)

Syntax

[[thread]] K[[BNSV]] [[framecount]]

Parameters

thread

The thread whose stack is to be displayed. See Process and Thread Syntax for information on the thread syntax.

framecount

Number of stack frames to display.

Description

Displays the stack frame of the given thread. Each display line shows the name or address of the procedure called, the arguments used on the call, and the address of the statement that called it. You can use any or all of the options in a single command; for example, K, KB, and KBNSV are valid commands. The following table describes the effect of the options:

Option	Effect
none	The K command without any options displays the basic call stack based on debugging information in the executable. It displays the frame pointer, return address, and function names.
B	The B option causes the K command to additionally display the first three parameters to the functions.
N	The N option causes the K command to additionally display the frame numbers for the calls.
S	The S option causes the K command to additionally display source module and line number information for the calls.
V	The V option causes the K command to additionally display runtime function information.


L (Restart Debuggee)

Syntax

L [[parameters]]

Parameter

parameters

Command-line options for the debuggee.

Description

Restarts the debuggee with optional parameters supplied as command-line options.


LM (List Loaded Modules)

Syntax

LM  [/s  [/o]]  [/f ]  [modulename]

Parameter

parameters

/s  List segmented modules.

/f   List flat modules.

/o  Sorts segmented modules by selector.

modulename    Module to list

Description

This command lists the specified loaded modules. If you do not specify a modulename, LM will list all loaded modules. If /f and /s are both absent from the command line, LM will assume both; the following two commands are equivalent:

> LM

> LM  /f  /s

Segmented modules are sorted by module name, then selector, unless you specified /o. Flat modules are sorted by base address.


LN (List Nearest symbols)

Syntax

LN address

Parameter

address

The address to search for symbols.

Description

Displays the symbols at or near the given address. You can use this command to help determine what a pointer is pointing to. It also can be useful when looking at a corrupted stack to determine what procedure made a call.


M (Move Memory)

Syntax

M range address

Parameters

range

The memory area to copy. See Range Syntax for information on the range syntax.

address

The starting address of the destination memory area.

Description

Copies the contents of memory from one location to another. It is legal for address to be part of range. Overlapping moves are handled correctly.


N (Set Number Base)

Syntax

N radix

Parameter

radix

The default number base used for numeric display and entry. Legal values are 8 (octal), 10 (decimal), and 16 (hexadecimal).

Description

Sets the default number base to radix. You can use C-style radix prefixes to override the default radix.

WinDbg’s default is base 16.


P (Program Step)

Syntax

[[thread]] P [[count]]

Parameters

thread

The thread to step through. See Process and Thread Syntax for information on the thread syntax.

count

The number of instructions or source lines to step through before stopping.

Description

Executes the instruction (in ASM mode) or source line (in SRC mode) at the instruction pointer. If WinDbg encounters a CALL instruction or interrupt while stepping, the called subroutine will execute before control returns to the debugger.

Use the T (Trace) command to have WinDbg step through subroutine calls and interrupt-handling routines.


Q (Quit WinDbg)

Syntax

Q

Description

Exits WinDbg. This command is identical to choosing Exit from the File menu.


R (Registers)

Syntax

[[thread]] R [[register [[=value]] ]]

Parameters

thread

The thread from which the registers are to be read. See Process and Thread Syntax for information on the thread syntax.

register

The register to display or modify.

value

The value to assign to register.

Description

Displays or modifies registers. If you do not specify a thread, the current thread is used.

If you do not specify a register, all of the registers are displayed. If you specify a register, the command displays the current value of the register. If you specify both a register and a value, the command changes the register to contain the value.

Use the FR (Floating-Point Registers) command to view and modify floating-point registers.


REMOTE (Start Remote Server)

Syntax

REMOTE [[pipename | STOP]]

Parameters

pipename

The name that you want to use for the remote server pipe.

STOP

Ends a currently active remote server.

Description

Starts a remote server, which lets you get access to the Command window from another computer on the network. You can then enter Command window commands on the other computer to debug the application remotely.

If you do not specify any parameters to REMOTE, the command displays its connection status and the name of the client.

To connect from another computer, run the following in a cmd shell (the command prompt):

remote /c hostname pipename

where hostname is the computer name of the computer that is running WinDbg and pipename is the same as above.

You now have access from the remote computer to the WinDbg Command window.


RT (Register Display Toggle)

Syntax

[[thread]] RT

Parameters

thread

The thread from which the registers are to be read. See Process and Thread Syntax for information on the thread syntax.

Description

Toggles the register display (WinDbg KD only). The default is off.


S+, S - (Set Source/Assembly Mode)
S+, S − (Set Source/Assembly Mode)

Syntax

S+
S −

Description

Use these commands to switch between source mode (where the debugger steps line-by-line through the source code) and assembly-language mode (where the debugger steps instruction-by-instruction). The S+ command switches to Source mode, and S −  switches to assembly-language mode. The status bar displays whether the current mode is SRC or ASM.


SA, SB, SD, SI, SS, ST, SU, SW (Search Memory)

Syntax

S{A | B | D | I | S | T | U | W} range pattern

Parameters

range

The memory area to search through. See Range Syntax for information on the range syntax.

pattern

One or more byte values or ANSI or Unicode characters to search for. Separate multiple values with spaces.

Description

Searches through memory to find a specific byte pattern. If the pattern is found, WinDbg will display the first memory address in range where it was found.

When entering numeric values to search for, you can use C-style radix prefixes to override the default radix. Prefix octal constants with a “0o” (for example 0o1776), hexadecimal constants with “0x” (for example 0xF000), and decimal constants with “0t” (for example 0t199).

When entering Unicode values to search for, you can include space (" ") characters by enclosing the character string in quotation marks (" or '). If you enclose the string in double quotation marks, WinDbg will automatically null-terminate the string. Single quotation marks (') will not add a null character. Standard C escape characters (such as \t, \007, and \") are also allowed.

Command	Definition	Fill
SA	Search ANSI	ANSI (extended ASCII) characters
SB	Search Bytes (char)	Byte values
SD	Search Doublewords (long)	Doubleword (4-byte) values
SI	Search 8-Byte Reals (double)	Floating-point numbers
SS	Search 4-Byte Reals (float)	Floating-point numbers
ST	Search 10-Byte Reals (long double)	Floating-point numbers
SU	Search Unicode	Unicode characters
SW	Search Words (short)	Word values


SEB, SEW (Set Error Break, Set Error Warning)

Syntax

SEB [[level]]
SEW [[level]]

Parameters

level

The error level required to break into the debugger (SEB) or display a message (SEW). One of the following:

Level	Triggered by
0	Nothing. Disables breaks or warnings.
1	Severe errors only.
2	All errors.
3	All warnings and errors.
Description

The SEB command causes the debugger to break after the debuggee causes a system error or warning of the appropriate level. The SEW command causes the debugger to display a message under these conditions. If you do not specify a level, the commands will default to level 1.

The SEB command implies an SEW level equal to or greater than its own level. For example, SEB 3 causes the debugger to give warnings at levels 1 − 3.

These errors are triggered by the WOW subsystem. They are known as RIPs from Win16 where they usually signal a fatal program error. They are often caused by passing a bad value to an API function.


SX (Set Exceptions)

Syntax

SX [[exception]]
SXE exception [[message]] [[/Ccmdlist1]] [[/C2cmdlist2]]
SX{D | N} exception [[message]] [[/C2cmdlist2]]

Parameters

exception

The exception number that the command acts upon, in the current radix. If you do not specify an exception, the SX command will display information on all exceptions.

message

Message to display in the Command window when the exception is trapped.

cmdlist1

Semicolon-separated list of WinDbg commands to execute when an exception first occurs. The /C option is permitted only with the SXE command. Enclose in quotes if cmdlist1 includes spaces or semicolons.

cmdlist2

Semicolon-separated list of WinDbg commands to execute after an exception has not been handled. Enclose in quotes if cmdlist2 includes spaces or semicolons.

Description

Controls the behavior of the debugger when trapping exceptions before executing exception-handling code. The debugger always halts before execution returns from the exception handler.

Command	Action
SX	Displays the events that the debugger will halt for.
SXD	Causes the debugger to ignore the specified exception and issue an automatic GN command.
SXE	Causes the debugger to halt at the specified exception.
SXN	Causes the debugger to display a message before the exception is passed to the debuggee, and causes the debugger to issue a GN command after the message is displayed.
The /C option (allowed only with SXE) tells WinDbg to execute the specified debugger commands on the first chance (before the exception is passed to the debuggee). The /C2 option tells WinDbg to execute the specified debugger commands on the second chance (if the exception is not handled by WinDbg or the application). See your documentation on structured exception handling for more information.

When the debugger stops due to an exception, only the GN (Go Exception Not Handled) and GH (Go Exception Handled) commands can be used to continue execution. The SXD and SXN commands automatically call GN.


T (Trace)

Syntax

[[thread]] T [[count]]

Parameters

thread

The thread to trace through. See Process and Thread Syntax for information on the thread syntax.

count

The number of instructions or source lines (depending on the Source/Assembly mode) to step through before stopping.

Description

Executes the instruction or source line at the instruction pointer and displays the resulting values of all registers and flags.

Use the P (Program Step) command to have WinDbg execute subroutine calls or interrupts without returning control to the debugger.


U (Unassemble)

Syntax

U  [[range]]

Parameters

range

The memory area that contains the instructions to unassemble. See Range Syntax. You can use the standard range syntax or startaddress I line to dump line instructions starting at startaddress.

Description

Displays the instructions of the program being debugged. If you do not specify range, the debugger displays the instructions generated from the first eight lines of code at the current address.

The 80286 protected-mode mnemonics cannot be displayed.


X (Examine Symbols)

Syntax

X [[options]] [[ { [[procedure]], [[module]], [[executable]] } ]] [[pattern]]

Parameters

options

Specifies the scope of the symbol search. These options cannot be separated by spaces and must immediately follow the X (for example, XEM). Use the following letters to specify scope:

Option	Description
C	Search current class.
E	Search entire executable or DLL, except for current module.
F	Search current function.
G	Search all global symbols.
L	Search current code block (lexical scope).
M	Search current module.
P	Search all public symbols.
procedure, module, executable

The area to search. For example,

{Function1, srcfile.c, target.dll}

will search Function1 from SCRFILE.C in TARGET.DLL. This is identical to the breakpoint context operator.

pattern

A pattern to search for. The ? and * wildcards are supported.

Description

Displays the symbols in all contexts that match pattern. If you do not specify any options, all except public symbols are searched. If you do not specify a pattern, all symbols will be displayed. The search will be case-sensitive if the Ignore Case option is not checked in the Debug command from the Options menu.


Z (Unfreeze Thread)

Syntax

[[thread]] Z

Parameters

thread

The thread or threads to be unfrozen. See Process and Thread Syntax for information on the thread syntax.

Description

Unfreezes the specified thread. If you do not specify the thread, this command unfreezes the thread that caused the most recent exception, if any. You can freeze threads with the F (Freeze) command.


Debugging Programs

The WinDbg debugger lets you analyze the internal workings of your program by using the debugger to control program execution and examine variables, memory, and registers. In this section, you will use the GENERIC program to learn debugging strategies and techniques within WinDbg.

This section describes the following tasks:

•	Preparing a debug version of a program

•	Setting and removing breakpoints

•	Controlling program execution

•	Using watch expressions

•	Using Quickwatch

•	Debugging services

•	Postmortem debugging

•	Remote debugging


Preparing a Debug Version of a Program

Before a program can be debugged, you must include debugging information with the project. It is also a good idea to disable code optimization, so that line numbers in the source file match line numbers being executed. Your compiler and linker documentation cover these options.

To build the GENERIC project for debugging

1.	Open a command prompt from the Start menu.

2.	Move to the directory containing the GENERIC example program. It should be under the MSTOOLS\SAMPLES\WIN32 directory.

3.	If you are using Microsoft Visual C++, build the executable by typing

NMAKE /A

Otherwise, follow the instructions included with your development tools for building a Win32-based application.

4.	Load the executable into WinDbg by typing

WINDBG GENERIC.EXE


Setting and Removing Breakpoints

Breakpoints are useful when you have a general idea of where a bug occurs in a program. WinDbg runs until it reaches a breakpoint, then stops. You can then step to the next line of code or trace through a function until you find the problem.

To set a breakpoint in the GENERIC program

1.	Move the insertion point to the first line of the About function in the source code.

2.	From the Debug menu, choose Breakpoints. The Breakpoints dialog box appears.

3.	From the Break list, select at Location.

4.	Choose Add.

5.	Choose OK.

6.	Choose Go from the Run menu. The GENERIC program begins to run.

7.	While the program is running, choose About Generic from its Help menu. The program stops and the breakpoint line is highlighted in the source window.

To remove a breakpoint

1.	From the Debug menu, choose Breakpoints. The Breakpoints dialog box appears.

2.	Select the breakpoint to remove from the Breakpoints list.

3.	Choose Delete.

4.	Choose OK.

The Breakpoints dialog box offers a variety of options for setting breakpoints. You can set breakpoints based on Windows messages, memory location, and the values in an expression. See WINDBG.HLP for details.


Controlling Program Execution

Once a breakpoint is reached and the program stops, you can control execution with commands on the Run menu. The following list shows the commands and their actions.

Command	Action
Restart	Resets execution to the first line of the program. It reloads the program into memory and discards the current values of all variables.
Stop Debugging	Terminates the debugging session and returns to a normal editing session.
Go	Executes code from the current statement until a breakpoint or the end of the program is reached.
Attach	Selects a running process to debug.
Continue to Cursor	Executes the program as far as the line that currently has the cursor. This is equivalent to setting a temporary breakpoint at the cursor location.
Trace Into	Steps into a function when it is called and steps through all of the instructions in the function.
Step Over	Single-steps through instructions in the program. If this command is used when you reach a function call, the function is executed without stepping through the function instructions.
Halt	Halts the program and returns control to WinDbg.
Go Handled	Continues the execution of a program that has stopped at an exception, marking the exception as having been handled.
Go Unhandled	Continues the execution of a program that has stopped at an exception, without marking the exception has having been handled. The system attempts to locate an exception handler defined by the application.
Set Thread	Selects a thread to monitor with the debugger. This determines which thread receives debugger commands and is viewed by the display windows. Also freezes and thaws individual threads.
Set Process	Selects a process to monitor with the debugger. This determines which process receives debugger commands and is viewed by the display windows.
Source/Asm Mode	Toggles between source and assembly modes.


Using Watch Expressions

The Watch Expressions command shows a variable’s name and value in the Watch window. It updates the window whenever the variable’s value changes. This feature is useful during debugging to check the value of a variable. You can enter expressions as well as variables.

To add a watch variable

1.	In the GENERIC program, select the message variable in the About function.

2.	From the Debug menu, choose Watch Expression. The selected message variable appears in the Watch Expression text box.

3.	Choose Add.

4.	Choose OK. The Watch window opens, and it includes the message variable.

5.	Resize the Watch window so it is visible with the source window displayed.

6.	With the breakpoint in the GENERIC program still in place, choose Go from the Run menu. The message variable is updated to show its new value.

To remove the message variable from the Watch Expression list

1.	From the Debug menu, choose Watch Expression.

2.	Select Message from the Watch Expression list.

3.	Choose Delete.

4.	Choose Close.


Using Quickwatch

Quickwatch gives you a fast way to view variables and expressions. Unlike Watch Expressions, which are stored in the Watch window, the values of Quickwatch variables and expressions appear only in the Quickwatch dialog box. This is useful in exploratory debugging where you are checking a number of variables that are suspect.

To use Quickwatch

1.	With the breakpoint in the About procedure, run the GENERIC program, open the Help menu of the Generic Sample Application, and select the About Generic command.

2.	Move the insertion point in the source file to the message variable in the About function.

3.	From the Debug menu, choose Quickwatch. You can also use the Quickwatch button on the Toolbar.

4.	Choose Cancel to close the Quickwatch dialog box.

The Quickwatch dialog box also lists commands that you can use to evaluate expressions, add variables and expressions to the Watch Expression list, contract and expand structures, and modify values.


Debugging Services

Windows NT only: WinDbg can be used to debug service applications. The debugging process is the same as for a Win32-based application, but starting and stopping the debug session is slightly different.

To debug a service

1. 	Build the service with debugging information.

2. 	Install the service.

3. 	Start the service by using either the Services control panel applet or the SC tool in the MSTOOLS\BIN directory.

4. 	Open the source files for the service and set any breakpoints.

5. 	Attach to the service by choosing Attach from the Run menu or using the .attach command.

Exiting WinDbg will terminate the service. The service must be restarted with the Services control panel applet or the SC tool.


Postmortem Debugging

Windows NT only: When a program crashes (for example, after a general-protection fault), the system automatically invokes a debugger that is specified in the registry. To make WinDbg be that debugger, use REGEDT32.EXE to edit the following registry key:

HKEY_LOCAL_MACHINE
SOFTWARE
Microsoft
Windows NT
CurrentVersion
AeDebug

Add or edit the Debugger value entry (REG_SZ). Give it the following string value:

windbg -p %ld -e %ld

You can also use the Attach command from the Run menu to debug a process that is already running.


Remote Debugging

Remote debugging lets you debug a program from another computer. You run WinDbg on one computer (the host) and install the program you are debugging on another (the target). You run a remote monitor program (WinDbgRm) on the target computer to control the program you are debugging. WinDbgRm communicates with WinDbg across a serial cable or across the network.

Remote debugging isolates WinDbg from the program being debugged so that errors in the program do not affect the debugger, and the debugger does not affect the target system. If the program crashes the remote system, your development system continues to run.

The remote monitor demands fewer system resources, and after starting and loading the program to be debugged, it does not use the file system. Therefore, the monitor has no effect on the resources that can change your program’s behavior.

You can debug large programs or programs that destabilize the operating system. You can also debug programs on smaller systems that cannot support the full debugger. You can debug programs cross-platform. Some bugs that you cannot reproduce while running under the full debugger can appear under the remote monitor.

The process of debugging a program on a remote computer is almost the same as for local debugging. The only difference is in how you start the session. The following sections describe the hardware and files required for remote debugging and how to configure the debugger components on the host and target computers.


Requirements

Remote debugging requires two computers, the host running Microsoft Windows NT and the target running Windows NT. Serial debugging requires a serial port connecting the host and target computers. Debugging through a named pipe requires that both computers be connected to a common network that is supported by Windows NT. Network debugging is faster and does not require a special cable between the two systems.

To remotely debug using the serial ports, connect the host and target computers with a null-modem cable plugged into the serial ports on the two computers. A null modem is a serial cable that connects the transmitting line at each end to the receiving line at the opposite end. You cannot use an extension cable with “straight-through” connections.

Most computer stores stock or can assemble a null-modem cable for you with the correct wiring and the appropriate connectors for your host and target computers.


Starting a Remote Debugging Session

After the WinDbg components are in their locations and properly configured, you can begin a remote debugging session.

To start a remote debugging session

1.	If you are debugging across a serial cable, connect the cable to both the target and host.

2.	On the target computer:

•	Install your program and its DLLs. You do not need to have the source files on the target.

•	Start WinDbgRm.

•	WinDbgRm starts minimized as an icon. Its default is to communicate with WinDbg across the network, using the named pipe “windbg”. If you want to change how the host and target communicate, double-click on the WinDbgRm icon and select the Transport DLL command from the Options menu. Choose the appropriate transport layer in the Known Transport Layers list box.

3.	On the host computer:

•	Start WinDbg from the command prompt:

start windbg yourprog.exe

•	Use the Debugger DLLs command from the Options menu to change the transport layer to match the one used by WinDbgRm on the target. If you are using named pipes, use the Change button to modify the transport layer parameters so that the first parameter is the name of the target computer.

•	Select the Execution Model and Expression Evaluator to reflect the target computer.

•	Use the User DLLs command from the Options menu to specify the symbol search path to your program’s symbols; use the Debug command from the Options menu to specify the source search path to your source files.

•	Select Go from the Run menu.

If you can start your program on the target before attaching the debugger to it, then you can change step 3 as follows:

On the host computer:

•	Start WinDbg.

•	Use the Debugger DLLs command from the Options menu to change the transport layer to match the one used by WinDbgRm on the target. If you are using named pipes, use the Change button to modify the transport layer parameters so that the first parameter is the name of the target computer.

•	Select the Execution Model and Expression Evaluator to reflect the target computer.

•	Use the User DLLs command from the Options menu to specify the symbol search path to your program’s symbols; use the Debug command from the Options menu to specify the source search path to your source files.

•	Select the Attach command from the Run menu.

•	Select your program from the task list that the Attach command displays.

To connect to a computer with an IPC password, use the NET USE command to manually connect to the remote IPC$ share.

Use the .disconnect command to disconnect the host from the target. Use the .attach command to reestablish the connection. Another computer can run WinDbg and use .attach to connect to the target and debug your program. If you are still connected and another computer tries to connect to the target, you will receive a popup notifying you of that fact. You have 20 seconds to cancel the pop-up, then you will be disconnected and the other computer will be connected as the host of the remote debugging session.

If problems occur, check connections and make sure that WinDbg and WinDbgRm are using the same communications methods. If your system has trouble maintaining the communications link between the host and target computers, when communicating through a serial port, reduce the transmission baud rate.


Using the Editor

Use the WinDbg integrated text editor to edit source files. Writing text with the WinDbg editor is similar to using most other editors. For example, to start a new line, press ENTER; to leave a blank line between lines, press ENTER twice; If you make a mistake while typing, press BACKSPACE to delete the error.

This section provides information on how to edit source files. Most of the procedures, such as file and text handling and moving around in a file, follow basic Windows editing conventions.


Managing Source Files

This section explains how to create, save, open, and close a file. To familiarize yourself with the steps, you can use the sample program below. You can also use this program to try the other editing features described in this section.

/* Sample program. */

#include <stdio.h>

main()
{
     printf("Win32 console I/O is easy!\n");
}


Opening and Closing Source Files

To create a new source file

1.	Choose New from the File menu.

2.	Type your program into the new window.

New files are labeled “UNTITLED n” until they are saved.

Note  Before you can save or close a window it must be active. To make a window active, either click on the window or select the window name or number from the Window menu.

To open an existing source file

1.	From the File menu, choose Open.

2.	If the file is on a network share, click the Network button to select the share.

3.	Choose a drive from the Drives list box. The default drive is the current drive.

4.	From the Directories list box, double-click a directory where the file is stored (or down a directory path to the directory where the file is stored.)

5.	Choose a file type in the List Files of Type box. Only files with the chosen extension(s) are displayed in the File Name box.

6.	Double-click a filename, or click a filename and choose OK.

The names of the four most recently opened files are displayed at the end of the File menu. To open one of these files, choose its name from the menu.

Because the editor works with any ASCII file, you can open and edit text files created with other editors.

When a source file is opened, its name is added to the Window menu. If you want to see more than one view of your source file, use the New Window command on the Window menu to open another view. A file can be opened only once; if you try to open a file that is already open, the file’s window will activate, but the file will not be reloaded. You can, however, open multiple windows showing the same source file, so that you can, for instance, compare two different sections of the file. If more than one copy of the file is displayed, the window is titled filename:x, where x is a unique window number.

To save a source file

1.	Activate the source window.

2.	From the File menu, choose Save.

3.	If your file is unnamed, WinDbg displays the Save As dialog box. Enter the file’s name. If you are using the sample program, name the file FIRST.C.

4.	Select the drive and the directory to save the file to by choosing items from the Drives and Directories list boxes.

5.	Choose OK.

If the file has already been named, the Save command saves any changes without displaying the Save As dialog box.

The title bar will display an asterisk (*) when the source file has been modified.

To save a source file under a different name

1.	Activate the source window.

2.	From the File menu, choose Save As.

3.	Type a new name for the file.

4.	Choose OK.

This is useful for maintaining revised copies of a source file while keeping the original unchanged. You can also use the Save As command to name and save a newly created file.

To save all open source files that are new or have been changed

•	Choose Save All from the File menu.

To close a source file

1.	Activate the source window.

2.	From the File menu, choose Close.

If you are using the sample program, use one of these techniques to close the FIRST.C source window.

If you create a new source file or modify an existing file and try to close it before saving, a message appears asking if you want to save the changes before closing.

To activate a source window

•	Click the title bar.

 − Or −

•	Select it from the Window menu.

 − Or −

•	Use the shortcut key listed on the title bar (ALT + # for windows 0 − 9,
ALT + CTRL + # for windows 10 − 19).

 − Or −

•	Use CTRL + F6 to cycle through all active windows.

To close a source window

1.	Activate the source window.

2.	Double-click the document Control-menu box.

 − or −

Press CTRL + F4.


Merging Source Files

The Merge command inserts another file at the insertion point. You can also use the command to replace selected text within the active source window with the contents of another file.

To merge source files

1.	Move the insertion point where you want to merge text, or select the text you want to replace.

2.	From the File menu, choose Merge. The Merge dialog box appears.

3.	Select the drive and directory where the source file to be inserted is stored. The default is the current drive and directory.

4.	Select the type of file to display.

5.	Type a filename or select the name from the list of files.

6.	Choose OK to merge the specified file at the insertion point.

As an alternative you can open a file with the editor and copy and paste text to another file.


Moving Around Source Files

This section discusses some special techniques for moving around source files in WinDbg.

To move to a specific line within the source window

1.	From the View menu, choose Goto Line. The Line dialog box appears.

2.	Enter the line number you wish to move to.

3.	Choose OK.

To set a tag in the source window

1.	Move the insertion point to the line where you want to set a tag.

2.	From the View menu, choose Toggle Tag. The tagged line is highlighted.

You can tag frequently accessed lines in your source file and use menu commands to move quickly to them. Tags can be cleared when you no longer need them.

To clear a tag

1.	Move the insertion point to the tagged line.

2.	From the View menu, choose Toggle Tag. The tag and the highlight are removed.

To remove all tags in a window, choose Clear All Tags from the View menu.

To move to the next tag after the insertion point

•	From the View menu, choose Next Tag, or press F2.

To move to the previous tag before the insertion point

•	From the View menu, choose Previous Tag, or press SHIFT + F2.


Using the Keyboard Commands

The editor includes a number of special keystrokes for editing and moving around in a source file. These are in addition to the familiar ARROW keys, SPACEBAR, and ENTER.

To move to	Press
Word to left	CTRL+LEFT ARROW
Word to right	CTRL+RIGHT ARROW
Beginning of current line	HOME
End of current line	END
Beginning of file	CTRL+HOME
End of file	CTRL+END
See WINDBG.HLP for the complete set of WinDbg keyboard commands.


Controlling the Source Window

The editor features a number of options that affect the source window. These include the ability to set tabs, highlight language syntax within the window, and make the file read-only.


Setting Tabs

You can set tab stops in a source file and save them as tabs or spaces when you save the file.

To set tabs

1.	Choose Environment from the Options menu. The Environment dialog box appears.

2.	Enter the number of spaces to be used as a tab stop in the Tab Stops text box.

3.	Choose the Keep Tabs option to treat tabs as a single tab character when the source file is saved.

 − or −

Choose Insert Spaces to convert tabs to the number of spaces shown in the Tab Stops box.

4.	Choose OK.


Highlighting Language Syntax

WinDbg highlights C language keywords, identifiers, comments, and strings in different colors. This feature is useful when viewing lengthy and complex source files. For example, if you are editing a file with a .C extension, all C keywords are highlighted.


Making a File Read-Only

The Read Only command makes the active source window read-only. When you choose this command, the window cannot be altered.

This command is useful when you are viewing a program and don’t want to accidentally make any changes to the window.

To make a source window read-only

1.	Activate the window.

2.	From the Edit menu, choose Read Only.

To deactivate the command, choose it again.

A check mark next to the Read Only menu item and the word READ in the status bar at the bottom of the screen indicate that the source file is read-only.


Finding and Replacing

The WinDbg editor offers advanced find and replace capabilities. You can search for literal text or use regular expressions to find words or characters in the source window.

The Find command searches for specified text. The Replace command finds the text and replaces it with other text.


Finding Text

To find a character, word, or group of characters in the active source window

1.	Position the insertion point where you want to start the search.

2.	From the Edit menu, choose Find. The Find dialog box appears.

3.	In the Find What box, type the text you want to find, or choose from the 16 previous instances of text searched for, which are listed in the drop-down box.

4.	Choose any of the Find options, as described below.

5.	Choose OK.

When you choose the Find command, the editor uses the location of the insertion point to select a default search string. If the insertion point is inside a word, that word is displayed as the search text in the Find What box.

If the insertion point is between words, the word to the right is displayed. If there is no word to the right, the word to the left is displayed. If that is not possible, nothing is displayed.

The Find dialog box has these choices for locating text:

Command	Description
Match Whole Word Only	Searches for complete occurrences of the text. A word contains only the characters a − z and A − Z, the numbers 0 − 9, and the # or _ (underscore) characters. If you don’t select this option, the editor finds embedded occurrences; for example, “main” in “remainder”.
Match Case	Searches for text that matches the capitalization of the search text.
Regular Expression	Finds text using patterns. See the WinDbg help file for details on regular expressions.
Direction	The Up option searches from the insertion point to the beginning of the file. The Down option searches from the insertion point to the end of the file.
Tag All	Searches for text and marks each line that contains the text. Use the Tag commands from the View menu to move to each marked line.
If the text is located, the source window scrolls to the text and highlights it. Choose Find Next from the abbreviated Find dialog box to move to the next occurrence of the text.


Replacing Text

To find and replace text

1.	From the Edit menu, choose Replace. The Replace dialog box appears.

2.	In the Find What box, type the search text or regular expression, or choose from the 16 previous instances of text searched for, which are listed in the drop-down box.

3.	In the Replace With box, type the replacement text, or choose from the 16 previous instances of text searched for, which are listed in the drop-down box.

4.	Set any change options you need. These options are the same as those in the Find dialog box (see the previous section, “Finding Text”).

5.	Choose OK.

For information on default search strings, see the previous section, “Finding Text.”

To repeat the last search or search and replace

•	Choose Find Next in the abbreviated Find or Replace dialog box. The abbreviated dialog box remains active until the search reaches the starting location (after wrapping) or until you choose Cancel.


About WinDbg

The WinDbg debugger is a powerful, graphical tool that allows you to debug programs and edit source code.

Windows NT: You can use WinDbg to debug service applications, kernel-mode drivers, and 16-bit Windows-based applications.

This introduction covers the following topics:

•	Installing WinDbg

•	Starting and quitting WinDbg

•	WinDbg windows

•	Customizing WinDbg


Installing WinDbg

The WinDbg files are copied with other development files from the Win32 SDK CD-ROM. By default, the files are held in the MSTOOLS\BIN directory.


Starting and Quitting WinDbg

After you have installed WinDbg, you can start it by selecting it from the Start menu. You can also start WinDbg from the command line by typing

windbg [-a] [-g] [-h] [-i] [-k[platform port speed]] [-l[text]] [-m] [-p id [-e event]] [-s[pipe]] [-v] [-w name ] [-y path] [-z crashfile] [filename[.ext] [arguments]]

The following table describes the command-line options.

Option	Description
-a	Ignore all bad symbols (but still print warning message).
-g	Go now; start executing the process.
-h	Causes child processes to inherit access to WinDbg’s handles.
-i	Ignore workspace; like running without any registry data.
-k [platform port speed]	Run as a kernel debugger with the specified options:   platform is the target computer type (i386, mips, alpha)   port is the com port (com1 ... comn)   speed is the com port speed (9600, 19200, 57600, ...)
-l [text]	Sets the window title for WinDbg.
-m	Start WinDbg minimized.
-p id	Attach to the process with the given id.
-e event	Signal an event after process is attached. Used only for post-mortem debugging (AeDebug).
-s [pipe]	Start a remote .EXE server, using the named pipe.
-v	Verbose option; WinDbg prints module load and unload messages.
-w name	Load the named workspace.
-y path	Search for symbols along the specified path. You can specify multiple paths by separating them with semicolons.
-z crashfile	Debug the specified crash dump file.
filename[.ext]	Program to debug or file to edit. If no extension is specified, WinDbg assumes an .EXE extension. If the file is not an .EXE or .COM file, WinDbg will try to load it as a text file.
arguments	Arguments to program being debugged.
To quit WinDbg, choose Exit from the File menu.


WinDbg Windows

WinDbg uses windows to present and enter information. These windows are like standard windows in other applications for Windows.

Window	Description
Calls	Displays the current call stack and lets you jump to any stack frame displayed.
Command	Allows you to enter debugger commands with the keyboard.
Disassembly	Assembly-language instructions being stepped through.
Floating point	Current contents of floating-point registers and stack.
Locals	Values of local variables within the current function.
Memory	Current contents of the application virtual memory.
Registers	Current contents of the CPU registers.
Watch	Used to monitor variables and expressions.


The Toolbar

The Toolbar appears beneath the menu bar (see the figure below). It provides shortcuts for menu selections.

You can hide or display the Toolbar with the Toolbar command on the View menu. When this command is checked, the Toolbar appears. When it is turned off (unchecked), the Toolbar is hidden. You turn the command on or off by selecting it.

To issue debug commands, click one of the icons on the Toolbar:

Icon	Action
	Starts or continues execution. Execution proceeds until the program reaches a breakpoint or the program ends. All threads and processes are unfrozen. Equivalent to the Go command from the Run menu.
	Stops the program and its threads, allowing you to regain control of the debugger. Equivalent to the Halt command from the Run menu.
	Sets a breakpoint at the current line.
	Displays the Quickwatch debugging dialog box. Equivalent to the Quickwatch command from the Debug menu.
	Steps into a function when it is called and steps through all of the instructions in the function. Equivalent to the Trace Into command from the Run menu.
	Single-steps through instructions in the program. If this command is used when you reach a function call, the function is executed without stepping through the function instructions. Equivalent to the Step Over command from the Run menu.
	Switches between source and assembly mode. Equivalent to switching modes with the Toggle Source/Asm Mode command from the Run menu.
	Switches between source and assembly mode. Equivalent to switching modes with the Toggle Source/Asm Mode command from the Run menu.
	Opens the Options dialog, if any, for the current window.
When a button cannot be used (for example, a trace command while the debuggee is running), the button is grayed.

Font selection is not available from the toolbar. You can change the typeface of the current source file by choosing Font from the Options menu.


The Status Bar

A status bar (see the figure below) appears at the bottom of the main WinDbg window. The status bar provides information about WinDbg and the active source window, such as line and column position and editor mode. When debugging, the status bar will also give the WinDbg process ID (PID) and thread ID (TID) of the code being debugged.

The status bar displays the following information:

Contents	Description
Message box	Displays messages from the environment.
SRC/ASM	Indicates whether WinDbg is in source or assembly mode.
pid	Shows the ID number of the process being debugged.
tid	Shows the ID number of the thread being debugged.
^Q	Indicates a WordStar keystroke sequence.
OVR	Indicates overtype mode.
READ	Indicates read-only status.
CAPS	Indicates that CAPS LOCK is on.
NUM	Indicates that NUM LOCK is on.
Line	Displays the line number at the insertion point in the current window.
Column	Displays the column number at the insertion point in the current window.
You can hide or display the status bar with the Status Bar command on the View menu. When this command is checked, the status bar appears. When it is turned off (unchecked), the status bar is hidden. Turn the command on or off by selecting it.


Customizing WinDbg

Many parts of WinDbg can be customized to suit your programming needs. This section discusses how you can modify the appearance and functionality of WinDbg.


Using the Program Registry

To start debugging a program from within WinDbg, you must first add it to the program registry (or use the .ATTACH command). The WinDbg program registry is a list of programs that WinDbg can debug. Each program in the registry has one or more workspaces associated with it. A workspace is a set of WinDbg defaults that can be associated with a program.

To add a program to the registry

1.	Choose Open from the Program menu.

The Program Open dialog will appear with a list of all of the programs in the registry.

2.	Choose New.

The common Open dialog will appear.

3.	Open the executable file that you want to debug, and choose OK.

The dialog boxes will close. WinDbg is now ready to begin debugging.

To load a program already in the registry

1.	Choose Open from the Program menu.

The Program Open dialog will appear with a list of all of the programs in the registry.

2.	Select the program to debug from the Programs list.

3.	Select the workspace to use from the Workspaces list.

For more information on workspaces, see the following section, “Using Workspaces.”

4.	Choose OK.

To delete a program

1.	Choose Delete from the Program menu.

2.	In the Program box, select the program that you want to delete.

3.	Choose Delete. The selected program will disappear.

4.	Choose OK.


Using Workspaces

With workspaces, you can save and restore the state of WinDbg between debugging sessions and customize WinDbg for different debugging situations. Workspaces are saved in the registry for each user.

When you debug a program for the first time or start WinDbg without loading a debuggee, you start with the Common Workspace. The Common Workspace is different from other workspaces because it is not associated with a particular program, but is available at all times. You can use the Common Workspace as a starting point for custom workspaces that are saved with each program.

You can change the Common Workspace to reflect your preferences for WinDbg.

To change the Common Workspace

1.	Configure WinDbg windows and options.

2.	Choose Save Common from the Program menu.

Note  Since the Common Workspace does not correspond to a specific program, breakpoints, watch expressions, and other program-specific information are not saved.

To create a new workspace

1.	Load a debuggee using Open from the Program menu.

2.	Configure WinDbg windows, breakpoints, and options.

3.	Choose Save As from the Program menu.

4.	Enter a name for the workspace.

If you check the Make Default box, the workspace will be saved with the given name, and it will be made the default workspace for the program when the Program Open Dialog box is next used.

5.	Choose OK.

To delete a workspace

1.	Choose Delete from the Program menu.

2.	In the Program box, select the program that has the workspace that you want to delete.

3.	In the Workspace box, select the workspaces that you want to delete.

4.	Choose Delete. The selected workspaces will disappear.

5.	Choose OK.


Changing Display Colors

Using different colors for various language elements such as functions and variables gives you immediate visual cues about the structure of your source code. You can change the default colors of these elements as well as the color of other text in WinDbg, such as reserved words, breakpoints, and information windows.

To change the colors in the source window

1.	From the Options menu, choose Color. The Color dialog box appears.

2.	From the Items list select the item you want to change. For this example, select Source Window.

3.	Select the color square from the palette to represent the foreground color. Press Set Foreground. The new color combination is shown in the Items box.

4.	Select the color square to represent the background color from the palette shown. Press Set Background. The new color combination is shown in the Items box.

5.	Choose OK to apply the change to the source window. You can change several items in the list before choosing OK.

To change the source window back to its original colors

1.	From the Options menu, choose Color.

2.	From the Items list, select Source Window.

3.	Choose Set Default.

4.	Choose OK.

To change all windows back to their default colors

1.	From the Options menu, choose Color.

2.	Choose Select All.

3.	Choose Set Default.

4.	Choose OK.


Setting Font Type and Size

You can specify which font type and size appear in WinDbg source windows. You can choose any font type and size found within the system.

To set the font type and size

1.	From the Options menu, choose Font. The Font dialog box appears.

2.	Select the font, font style, and size from the combo boxes. The words “sample text” will change to the font you selected.

3.	Choose OK.

The Make Default box in the Font dialog box sets the selected font and size as the default.

Text within the source window can be only one font and size. Multiple fonts cannot be displayed in the same source window.


Acknowledge Close

Acknowledges the close state of the internal close flag.

mov ah, 16h    ; Windows multiplex function

mov al, 8Fh    ; VM Close

mov dh, 2      ; Acknowledge Close

mov dl, 0      ; always 0

int 2Fh

or ax, ax

jz success

Return Value

Returns zero in the AX register if successful.

Remarks

Acknowledging the close state is necessary if an application needs to perform additional keyboard input before exiting. If the close state has been signaled but not yet acknowledged by an application, all keyboard read operations will return NULL and buffered line input will return an empty string.


Cancel Close

Cancels the close operation.

mov ah, 16h    ; Windows multiplex function

mov al, 8Fh    ; VM Close

mov dh, 3      ; Cancel Close

mov dl, 0      ; always 0

int 2Fh

or ax, ax

jz success

Return Value

Returns zero in the AX register if successful.

Remarks

After acknowledging the close state of the internal close flag, an application should either exit or cancel the close operation by calling Cancel Close.


CreateToolhelp32Snapshot

Takes a snapshot of the processes and the heaps, modules, and threads used by the processes.

HANDLE WINAPI CreateToolhelp32Snapshot(DWORD dwFlags,
    DWORD th32ProcessID);

Parameters

dwFlags

Flags specifying portions of the system to include in the snapshot. These values are defined:

TH32CS_INHERIT	Indicates that the snapshot handle is to be inheritable.
TH32CS_SNAPALL	Equivalent to specifying the TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS, and TH32CS_SNAPTHREAD values.
TH32CS_SNAPHEAPLIST	Includes the heap list of the specified  process in the snapshot.
TH32CS_SNAPMODULE	Includes the module list of the specified  process in the snapshot.
TH32CS_SNAPPROCESS	Includes the Win32 process list in the snapshot.
TH32CS_SNAPTHREAD	Includes the Win32 thread list in the snapshot.
th32ProcessID

Process identifier. This parameter can be zero to indicate the current process. This parameter is used when the TH32CS_SNAPHEAPLIST or TH32CS_SNAPMODULE value is specified. Otherwise, it is ignored.

Return Value

Returns an open handle to the specified snapshot if successful or  − 1 otherwise.

Remarks

The snapshot taken by this function is examined by the other tool help functions to provide their results. Access to the snapshot is read only. The snapshot handle acts like an object handle and is subject to the same rules regarding which processes and threads it is valid in.

To retrieve an extended error status code generated by this function, use the GetLastError function.

To destroy the snapshot, use the CloseHandle function.


Enable or Disable Close Command

Enables or disables the Close command in the system menu.

mov ah, 16h    ; Windows multiplex function

mov al, 8Fh    ; VM Close

mov dh, 0      ; Enable or Disable Close Command

mov dl, Flags  ; see below

int 2Fh

or ax, ax

jz success

Parameters

Flags

Close flags. This parameter can be one of these values:

00h	Disables the Close command.
01h	Enables the Close command.
Return Value

Returns zero in the AX register if successful.


Get Application Title

Copies the application title to the specified buffer.

mov  ah, 16h           ; Windows multiplex function

mov  al, 8Eh           ; VM Title

mov  di, seg AppTitle  ; see below

mov  es, di

mov  di, offset AppTitle

mov  cx, Size          ; see below

mov  dx, 2             ; Get Application Title

int  2Fh

cmp  ax, 1

je   success

Parameters

AppTitle

Address of a buffer that receives the application title. This parameter must not be zero.

Size

Size, in bytes, of the buffer pointed to by AppTitle.

Return Value

Returns 1 in the AX register if successful or zero otherwise.

Remarks

Get Application Title copies as much of the title as possible, but never more than the specified number of bytes. The function always appends a terminating null character to the title in the buffer.


Get Virtual Machine Title

Copies the virtual machine title to the specified buffer.

mov  ah, 16h           ; Windows multiplex function

mov  al, 8Eh           ; VM Title

mov  di, seg VMTitle   ; see below

mov  es, di

mov  di, offset VMTitle

mov  cx, Size          ; see below

mov  dx, 3             ; Get Virtual Machine Title

int  2Fh

cmp  ax, 1

je   success

Parameters

VMTitle

Address of a buffer that receives the virtual machine title. This parameter must not be zero.

Size

Size, in bytes, of the buffer pointed to by VMTitle.

Return Value

Returns 1 in the AX register if successful or zero otherwise.

Remarks

Get Virtual Machine Title copies as much of the title as possible, but never more than the specified number of bytes. The function always appends a terminating null character to the title in the buffer.


Heap32First

Retrieves information about the first block of a heap that has been allocated by a process.

BOOL WINAPI Heap32First(LPHEAPENTRY32 lphe, DWORD th32ProcessID,
    DWORD th32HeapID);

Parameters

lphe

Address of a buffer containing a HEAPENTRY32 structure.

th32ProcessID

Identifier of the process context that owns the heap.

th32HeapID

Identifier of the heap to enumerate.

Return Value

Returns TRUE if information for the first heap block has been copied to the buffer or FALSE otherwise. The ERROR_NO_MORE_FILES error value is returned by the GetLastError function if the heap is invalid or empty.

Remarks

The calling application must set the dwSize member of HEAPENTRY32 to the size, in bytes, of the structure. Heap32First changes dwSize to the number of bytes written to the structure. This will never be greater than the initial value of dwSize, but it may be smaller. If the value is smaller, do not rely on the values of any members whose offsets are greater than this value.

To access subsequent blocks of the same heap, use the Heap32Next function.


Heap32ListFirst

Retrieves information about the first heap that has been allocated by a specified process.

BOOL WINAPI Heap32ListFirst(HANDLE hSnapshot, LPHEAPLIST32 lphl);

Parameters

hSnapshot

Handle of the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lphl

Address of a buffer containing a HEAPLIST32 structure.

Return Value

Returns TRUE if the first entry of the heap list has been copied to the buffer or FALSE otherwise. The ERROR_NO_MORE_FILES error value is returned by the GetLastError function when no heap list exists or the snapshot does not contain heap list information.

Remarks

The calling application must set the dwSize member of HEAPLIST32 to the size, in bytes, of the structure. Heap32ListFirst changes dwSize to the number of bytes written to the structure. This will never be greater than the initial value of dwSize, but it may be smaller. If the value is smaller, do not rely on the values of any members whose offsets are greater than this value.

To retrieve information about other heaps in the heap list, use the Heap32ListNext function.


Heap32ListNext

Retrieves information about the next heap that has been allocated by a  process.

BOOL WINAPI Heap32ListNext(HANDLE hSnapshot, LPHEAPLIST32 lphl);

Parameters

hSnapshot

Handle of the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lphl

Address of a buffer containing a HEAPLIST32 structure.

Return Value

Returns TRUE if the next entry of the heap list has been copied to the buffer or FALSE otherwise. The ERROR_NO_MORE_FILES error value is returned by the GetLastError function when no more entries in the heap list exist.

Remarks

To retrieve information about the first heap in a heap list, use the Heap32ListFirst function.


Heap32Next

Retrieves information about the next block of a heap that has been allocated by a process.

BOOL WINAPI Heap32Next(LPHEAPENTRY32 lphe);

Parameters

lphe

Address of a buffer containing a HEAPENTRY32 structure.

Return Value

Returns TRUE if information about the next block in the heap has been copied to the buffer or FALSE otherwise. The GetLastError function returns ERROR_NO_MORE_FILES when no more objects in the heap exist and ERROR_INVALID_DATA if the heap appears to be corrupt or is modified during the walk in such a way that Heap32Next cannot continue.

Remarks

To retrieve information for the first block of a heap, use the Heap32First function.


Interrupt 21h Function 4302h

Obtains the compressed size, in bytes, of a given file or directory.

mov ax, 4302h            ; Get Compressed File Size

mov dx, seg PathName     ; see below

mov ds, dx

mov dx, offset PathName

int 21h

jc error

Parameters

PathName

Address of a null-terminated string that specifies the file or directory to retrieve the file size for.

Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

The function obtains the actual number of bytes of disk storage used to store the file. If the file is located on a volume that supports compression and the file is compressed, the value obtained is the compressed size of the specified file. If the file is not located on a volume that supports compression or if the file is not compressed, the value obtained is the file size, in bytes, rounded up to the nearest cluster boundary.


Interrupt 21h Function 440Dh Minor Code 48h

Locks or unlocks the volume in the given drive (preventing or permitting its removal) or returns the locked status of the given drive.

mov ax, 440Dh           ; generic IOCTL

mov bx, DriveNum        ; see below

mov ch, 8               ; device category

mov cl, 48h             ; Lock or Unlock Removable Media

mov dx, seg ParamBlock  ; see below

mov ds, dx

mov dx, offset ParamBlock

int 21h

jc  error

Parameters

DriveNum

Drive to lock or unlock. This parameter can be 0 for default drive, 1 for A, 2 for B, and so on.

ParamBlock

Address of a PARAMBLOCK structure that specifies the operation to carry out and receives a count of the number of locks on the drive.

Return Value

Clears the carry flag and copies the number of pending locks on the given drive to the NumLocks member of the PARAMBLOCK structure if successful. Otherwise, the function sets the carry flag and sets the AX register to one of the following error values:

01h	The function is not supported.
B0h	The volume is not locked in the drive.
B2h	The volume is not removable.
B4h	The lock count has been exceeded.


Interrupt 21h Function 440Dh Minor Code 49h

Ejects the specified media.

mov ax, 440Dh     ; generic IOCTL

mov bx, DriveNum  ; see below

mov ch, 8         ; device category

mov cl, 49h       ; Eject Removable Media

int 21h

jc  error

Parameters

DriveNum

Drive to eject. This parameter can be 0 for default drive, 1 for A, 2 for B, and so on.

Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to one of the following error values:

01h	The function is not supported.
B1h	The volume is locked in the drive.
B2h	The volume is not removable.
B5h	The valid eject request has failed.
Remarks

If a given physical drive has more than one logical volume, all volumes must be unlocked by using Lock/Unlock Removable Media (Interrupt 21h Function 440Dh Minor Code 48h) before the drive will eject.


Interrupt 21h Function 440Dh Minor Code 4Ah

Locks the logical volume.

mov ax, 440Dh        ; generic IOCTL

mov bh, LockLevel    ; see below

mov bl, DriveNum     ; see below

mov ch, 08h          ; device category (must be 08h)

mov cl, 4Ah          ; Lock Logical Volume

mov dx, Permissions  ; see below

int 21h

jc error

Parameters

LockLevel

Level of the lock. This parameter must be either 0, 1, 2, or 3.

DriveNum

Drive to lock. This parameter can be 0 for the default drive, 1 for A, 2 for B, and so on.

Permissions

Operations that the system permits while the volume is locked. This parameter is specified only when a level 1 lock is obtained or when a level 0 lock is obtained for the second time for formatting the volume. For other lock levels, this parameter is zero. When a level 1 lock is obtained, bits 0 and 1 of this parameter specify whether the system permits write operations, new file mappings, or both by other processes during a level 1 lock as well as during level 2 and 3 locks. If this parameter specifies that write operations, new file mappings, or both are failed, these operations are failed during level 1, 2, and 3 locks. This parameter has the following form:

Bit	Meaning
0	0 = Write operations are failed (specified when a level 1 lock is obtained).
0	1 = Write operations are allowed (specified when a level 1 lock is obtained).
1	0 = New file mapping are allowed (specified when a level 1 lock is obtained).
1	1 = New file mapping are failed (specified when a level 1 lock is obtained).
2	1 = The volume is locked for formatting (specified when a level 0 lock is obtained for the second time).
Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

The volume must be locked before the application performs direct disk write operations by using Interrupt 26h or the IOCTL control functions. Lock Physical Volume (Interrupt 21h Function 440Dh Minor Code 4Bh) is used instead of this function before a call to an Interrupt 13h function. Unlock Logical Volume (Interrupt 21h Function 440Dh Minor Code 6Ah) should be used to release the lock.


Interrupt 21h Function 440Dh Minor Code 4Bh

Locks the physical volume.

mov ax, 440Dh        ; generic IOCTL

mov bh, LockLevel    ; see below

mov bl, DriveNum     ; see below

mov ch, 08h          ; device category (must be 08h)

mov cl, 4Bh          ; Lock Physical Volume

mov dx, Permissions  ; see below

int 21h

jc error

Parameters

LockLevel

Level of the lock. This parameter must be either 0, 1, 2, or 3.

DriveNum

Drive to lock. This parameter must be one of these values (same device unit numbers as for Interrupt 13h):

00 - 7Fh	Floppy disk drive (00 for the first floppy drive, 01 for the second, and so on).
80 - FFh	Hard disk drive (80 for the first hard disk drive, 81 for the second, and so on).
Permissions

Operations that the system permits while the volume is locked. This parameter is specified only when a level 1 lock is obtained or when a level 0 lock is obtained for the second time for formatting the volume. For other lock levels, this parameter is zero. When a level 1 lock is obtained, bits 0 and 1 of this parameter specify whether the system permits write operations, new file mappings, or both by other processes during a level 1 lock as well as during level 2 and 3 locks. If this parameter specifies that write operations, new file mappings, or both are failed, these operations are failed during level 1, 2, and 3 locks. This parameter has the following form:

Bit	Meaning
0	0 = Write operations are failed (specified when a level 1 lock is obtained).
0	1 = Write operations are allowed (specified when a level 1 lock is obtained).
1	0 = New file mapping are allowed (specified when a level 1 lock is obtained).
1	1 = New file mapping are failed (specified when a level 1 lock is obtained).
2	1 = The volume is locked for formatting (specified when a level 0 lock is obtained for the second time).
Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

The volume must be locked before the application performs direct disk write operations by using Interrupt 13h, Interrupt 26h, or the Interrupt 21h IOCTL functions. A single physical volume may be divided into more than one logical volume, which is also called a partition. The system automatically takes a logical volume lock on all logical volumes on the specified physical drive. If the application performs disk writes only to a logical drive, Lock Logical Volume (Interrupt 21h Function 440Dh Minor Code 4Ah) is used instead of this function. Unlock Physical Volume (Interrupt 21h Function 440Dh Minor Code 6Bh) should be called to release the lock.


Interrupt 21h Function 440Dh Minor Code 6Ah

Unlocks the logical volume or decrements the lock level.

mov ax, 440Dh      ; generic IOCTL

mov bl, DriveNum   ; see below

mov ch, 08h        ; device category (must be 08h)

mov cl, 6Ah        ; Unlock Logical Volume

int 21h

jc error

Parameters

DriveNum

Drive to unlock. This parameter can be 0 for the default drive, 1 for A, 2 for B, and so on.

Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

This function is used to release the lock obtained by using Lock Logical Volume (Interrupt 21h Function 440Dh Minor Code 4Ah). Only the lock owner can release the lock on a volume.

To release the lock on the volume, an application must call Unlock Logical Volume the same number of times that Lock Logical Volume was called.


Interrupt 21h Function 440Dh Minor Code 6Bh

Unlocks the physical volume or decrements the lock level.

mov ax, 440Dh      ; generic IOCTL

mov bl, DriveNum   ; see below

mov ch, 08h        ; device category (must be 08h)

mov cl, 6Bh        ; Unlock Physical Volume

int 21h

jc enter

Parameters

DriveNum

Drive to unlock. This parameter must be one of these values (same device unit numbers as for Interrupt 13h):

00 - 7Fh	Floppy disk drive (00 for the first floppy drive, 01 for the second, and so on).
80 - FFh	Hard disk drive (80 for the first hard disk drive, 81 for the second, and so on).
Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

This function is used to release the lock obtained by using Lock Physical Volume (Interrupt 21h Function 440Dh Minor Code 4Bh). Only the lock owner can release the lock on a volume.

To release the lock on the volume, an application must call Unlock Physical Volume the same number of times that Lock Physical Volume was called.


Interrupt 21h Function 440Dh Minor Code 6Ch

Polls the state of the access flag on a volume to determine if a write operation (for example, deleting or renaming a file or writing to a file) or a new file mapping has occurred since the last poll.

mov ax, 440Dh        ; generic IOCTL

mov bl, DriveNum     ; see below

mov ch, 08h          ; device category (must be 08h)

mov cl, 6Ch          ; Get Lock Flag State

int 21h

jc error

mov [AccessFlag], ax  ; state of access flag

Parameters

DriveNum

Drive to poll. This parameter can be 0 for the default drive, 1 for A, 2 for B, and so on.

Return Value

Clears the carry flag and sets the AX register to one of the following values if successful:

0	No write operations or file mappings have occurred since the last poll.
1	A write operation has occurred since the last poll (clears the volume access flag).
2	A file mapping has occurred since the last poll, or a 32-bit Windows-based DLL or executable has been opened (clears the volume access flag).
Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

Only the current lock owner may poll the access flag. The system fails other processes with ERROR_ACCESS_DENIED error value. Write operations performed by the lock owner do not cause a change in the state of the access flag.

When a lock is obtained that allows write operations or new file mappings, the system sets a flag whenever one of these operations happens on the volume. If a write operation or new file mapping has occurred since the last poll, Get Lock Flag State returns 1 or 2 respectively in the AX register and clears the volume access flag. If the swap file has grown or shrunk since the last poll, Get Lock Flag State returns 1. Note that write operations to the swap file that do not cause a change in size do not cause a change in the state of the access flag. If a 32-bit Windows-based DLL or executable has been opened since the last poll, Get Lock Flag State returns 2.


Interrupt 21h Function 440Dh Minor Code 6Dh

Enumerates open files on the specified drive.

mov ax, 440Dh           ; generic IOCTL

mov bx, DriveNum        ; see below

mov ch, 08h             ; device category (must be 08h)

mov cl, 6Dh             ; Enumerate Open Files

mov dx, seg PathBuf     ; see below

mov ds, dx

mov dx, offset PathBuf

mov si, FileIndex       ; see below

mov di, EnumType        ; see below

int 21h

jc  error

mov [OpenMode], ax      ; mode file was opened in

mov [FileType], cx      ; normal file or memory-mapped file

Parameters

DriveNum

Drive on which to enumerate the files. This parameter can be 0 for the default drive, 1 for A, 2 for B, and so on.

PathBuf

Address of a buffer that receives the path of the open file. The length of the buffer varies depending on the volume. Get Volume Information (Interrupt 21h Function 71A0h) is used to determine the maximum allowed length of a path for the volume.

FileIndex

Index of the file to retrieve the path for.

EnumType

Kind of file to enumerate. This parameter can be 0 to enumerate all open files or 1 to enumerate only open unmovable files, including open memory-mapped files and other open unmovable files (32-bit Windows-based DLLs and executables).

Return Value

Clears the carry flag, copies the path of an open file to the given buffer, and sets the AX and CX registers to the following values if successful:

AX	Mode that the file was opened in, which is a combination of access mode, sharing mode, and open flags. It can be one value each from the access and sharing modes and any combination of open flags.
	Access modes
	OPEN_ACCESS_READONLY (0000h)
	OPEN_ACCESS_WRITEONLY (0001h)
	OPEN_ACCESS_READWRITE (0002h)
	OPEN_ACCESS_RO_NOMODLASTACCESS (0004h)
	Share modes
	OPEN_SHARE_COMPATIBLE (0000h)
	OPEN_SHARE_DENYREADWRITE (0010h)
	OPEN_SHARE_DENYWRITE (0020h)
	OPEN_SHARE_DENYREAD (0030h)
	OPEN_SHARE_DENYNONE (0040h)
	Open flags
	OPEN_FLAGS_NOINHERIT (0080h)
	OPEN_FLAGS_NO_BUFFERING (0100h)
	OPEN_FLAGS_NO_COMPRESS (0200h)
	OPEN_FLAGS_ALIAS_HINT (0400h)
	OPEN_FLAGS_NOCRITERR (2000h)
	OPEN_FLAGS_COMMIT (4000h)
CX	File type. It can be one of the following values:
	0	For normal files
	1	For a memory-mapped files (memory-mapped files are unmovable)
	2	For any other unmovable files (32-bit Windows-based DLLs and executables)
	4	For the swap file
Note that if a memory-mapped file is returned (CX = 1), the value returned in the AX register is limited to the following values:

OPEN_ACCESS_READONLY (0000h)
OPEN_ACCESS_READWRITE (0002h)
Otherwise, the function sets the carry flag and sets the AX register to the following error value:

ERROR_ACCESS_DENIED	The value of FileIndex exceeds the number of open files on the drive.
Remarks

This function returns information about one file at a time. To enumerate all open files, the function must be called repeatedly with FileIndex set to a new value for each call. FileIndex should be set to zero initially and then incremented by one for each subsequent call. The function returns the ERROR_NO_MORE_FILES error value when all open files on the volume have been enumerated.

This function may return inconsistent results when used to enumerate files on an active volume — that is, on a volume where other processes may be opening and closing files. Applications should use Lock Logical Volume (Interrupt 21h Function 440Dh Minor Code 4Ah) to take a level 3 lock before enumerating open files.


Interrupt 21h Function 440Dh Minor Code 6Eh

Retrieves information about the swap file.

mov ax, 440Dh           ; generic IOCTL

mov ch, 08h             ; device category (must be 08h)

mov cl, 6Eh             ; Find Swap File

mov dx, seg PathBuf     ; see below

mov ds, dx

mov dx, offset PathBuf

int 21h

jc  error

mov [PagerType], ax            ; pager type

mov WORD PTR [FileSize], bx    ; swap file size in 4K pages

mov WORD PTR [FileSize+2], cx

Parameters

PathBuf

Address of the buffer that receives the path of the swap file. To determine the maximum allowed length of a path for the volume, call Get Volume Information (Interrupt 21h Function 71A0h).

Return Value

Clears the carry flag, copies the swap file path to the given buffer, and sets the following registers if successful:

AX	Pager type. It can be 1 for no pager, 2 for paging through MS-DOS, and 3 for paging through the protected-mode input and output (I/O) supervisor.
CX:BX	Current size of the swap file in 4K pages.
Otherwise, this function sets the carry flag and sets the AX register to an error value.


Interrupt 21h Function 440Dh Minor Code 6Fh

Retrieves information about the specified drive.

mov ax, 440Dh            ; generic IOCTL

mov bx, DriveNum         ; see below

mov ch, 8                ; device category

mov cl, 6Fh              ; Get Drive Map Info

mov dx, seg DriveMapInfo ; see below

mov ds, dx

mov dx, offset DriveMapInfo

int 21h

jc  error

Parameters

DriveNum

Drive to obtain information about. This parameter can be 0 for the default drive, 1 for A, 2 for B, and so on.

DriveMapInfo

Address of the DRIVE_MAP_INFO structure that receives information about the specified drive.


Interrupt 21h Function 440Dh Minor Code 70h

Retrieves the current lock level and permissions on the specified drive.

mov ax, 440Dh        ; generic IOCTL

mov bl, DriveNum     ; see below

mov ch, 08h          ; device category (must be 08h)

mov cl, 70h          ; Get Current Lock State

int 21h

jc error

Parameters

DriveNum

Drive to retrieve lock information about. This parameter can be 0 for the default drive, 1 for A, 2 for B, and so on.

Return Value

Clears the carry flag and sets the AX and CX registers to these values if successful:

AX	Current lock level. It may be either  0, 1, 2 or 3. If the volume is not locked, AX contains  − 1
CX	Lock permissions. The bits have the following form:
Bit	Meaning
0	0 = Write operations are failed.
0	1 = Write operations are allowed, unless they are blocked by the lock level.
1	0 = New file mapping are allowed, unless they are blocked by the lock level.
1	1 = New file mapping are failed.
2	1 = The volume is locked for formatting.
Remarks

The lock level and the permissions determine the kind of access processes other than the lock owner have to the volume while it is locked. The following operations are allowed by processes other than lock owner at each lock level:

Level	Operations
0	Read operations, write operations, and new file mappings are failed.
1	Read operations are allowed. Write operations and new file mappings are either allowed or failed based on permissions.
2	Read operations are allowed. Write operations and new file mappings are either failed or blocked based on permissions.
3	Read operations are blocked. Write operations and new file mappings are either failed or blocked based on permissions.


Interrupt 21h Function 440Dh Minor Code 71h

Retrieves the first cluster of the specified file or directory.

mov ax, 440Dh            ; generic IOCTL

mov bx, CharSet          ; see below

mov ch, 08h              ; device category

mov cl, 71h              ; Get First Cluster

mov dx, seg PathName     ; see below

mov ds, dx

mov dx, offset PathName

int 21h

jc error

Parameters

CharSet

Character set of PathName. This parameter must be one of these values:

BCS_WANSI (0)	Windows ANSI character set
BCS_OEM (1)	Current OEM character set
BCS_UNICODE (2)	Unicode character set
PathName

Address of a null-terminated string containing the path of the file or directory to retrieve the first cluster for.

Return Value

Clears the carry flag and sets DX:AX to the first cluster number if successful. Otherwise, the function sets the carry flag and returns either the ERROR_INVALID_FUNCTION or ERROR_ACCESS_DENIED value in AX.

Remarks

The first cluster of a file is the first cluster of the FAT cluster chain describing the data associated with the file. The first cluster of a directory is the first cluster of the FAT cluster chain associated with the directory. It is the cluster that contains the “.” and “..” entries. The function finds any file or directory regardless of attribute (system, hidden, or read-only). It does not find volume labels.

If your application is unable to accommodate a 32-bit cluster number, you must check to see if the value returned in the DX register is greater than zero.

if(MAKELONG(regAX,regDX) > 0x0000FFF8)
    b32BitNum = TRUE;
else
    b32BitNum = FALSE;

It is the calling application’s responsibility to check to see if the returned cluster number is valid.

if((MAKELONG(regAX,regDX) < 2L) || (MAKELONG(regAX,regDX) > maxClus))
    bInvalidNum = TRUE;
else
    bInvalidNum = FALSE;

In the preceding example, the maxClus variable is the maximum legal cluster number, as a DWORD type, computed from the drive parameters.


Interrupt 21h Function 5704h

Retrieves the last access date for the given file.

mov ax, 5704h   ; Get Last Access Date and Time

mov bx, Handle  ; see below

int 21h

jc  error

mov [Date], dx  ; last access date

mov [Time], cx  ; currently not supported, always 0

Parameters

Handle

File handle.

Return Value

Clears the carry flag and sets the CX register to zero and the DX register to these values if successful:

Bits	Contents
0−4	Day of the month (1−31)
5−8	Month (1 = January, 2 = February, and so on)
9−15	Year offset from 1980 (that is, add 1980 to get the actual year)
Otherwise, the function sets the carry flag and sets the AX register to an error value.


Interrupt 21h Function 5705h

Sets the last access date for the given file.

mov ax, 5705h       ; Set Last Access Date and Time

mov bx, Handle      ; see below

mov cx, 0           ; time currently not supported, always 0

mov dx, AccessDate  ; see below

int 21h

jc  error

Parameters

Handle

File handle.

AccessDate

New access date. The date is a packed 16-bit value with this form:

Bits	Contents
0−4	Day of the month (1−31)
5−8	Month (1 = January, 2 = February, and so on)
9−15	Year offset from 1980 (that is, add 1980 to get the actual year)
Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.


Interrupt 21h Function 5706h

Retrieves the creation date and time for the given file.

mov ax, 5706h           ; Get Creation Date and Time

mov bx, Handle          ; see below

int 21h

jc  error

mov [Time], cx          ; creation time

mov [Date], dx          ; creation date

mov [MilliSeconds], si  ; number of 10 ms intervals in 2 seconds

Parameters

Handle

File handle.

Return Value

Clears the carry flag and sets the CX, DX, and SI registers to these values if successful:

CX	Creation time. The time is a packed 16-bit value with the following form:
Bits	Contents
0−4	Second divided by 2
5−10	Minute (0−59)
11−15	Hour (0−23 on a 24-hour clock)
DX	Creation date. The date is a packed 16-bit value with the following form:
Bits	Contents
0−4	Day of the month (1−31)
5−8	Month (1 = January, 2 = February, and so on)
9−15	Year offset from 1980 (that is, add 1980 to get the actual year)
SI	Number of 10 millisecond intervals in 2 seconds to add to the MS-DOS time. The number can be a value in the range of 0 to 199.
Otherwise, the function sets the carry flag and sets the AX register to an error value.


Interrupt 21h Function 5707h

Sets the creation date and time for the given file.

mov ax, 5707h         ; Set Creation Date and Time

mov bx, Handle        ; see below

mov cx, Time          ; see below

mov dx, Date          ; see below

mov si, MilliSeconds  ; see below

int 21h

jc  error

Parameters

Handle

File handle.

Time

New creation time. The time is a packed 16-bit value with the following form:

Bits	Contents
0−4	Second divided by 2
5−10	Minute (0−59)
11−15	Hour (0−23 on a 24-hour clock)
Date

New creation date. The date is a packed 16-bit value with the following form:

Bits	Contents
0−4	Day of the month (1−31)
5−8	Month (1 = January, 2 = February, and so on)
9−15	Year offset from 1980 (that is, add 1980 to get the actual year)
MilliSeconds

Number of 10 millisecond intervals in 2 seconds to add to the MS-DOS time. The number can be a value in the range 0 to 199.

Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.


Interrupt 21h Function 6Ch

Opens or creates a file having the given name and attributes.

mov ah, 6Ch             ; Extended Open/Create

mov bx, ModeAndFlags    ; see below

mov cx, Attributes      ; see below

mov dx, Action          ; action to take

mov si, seg Filename    ; see below

mov ds, si

mov si, offset Filename

int 21h

jc error

mov [Handle], ax        ; file handle

mov [ActionTaken], cx   ; action taken to open file

Parameters

ModeAndFlags

Combination of access mode, sharing mode, and open flags. This parameter can be one value each from the access and sharing modes and any combination of open flags:

Access mode	Meaning
OPEN_ACCESS_READONLY (0000h)
	Opens the file for reading only.
OPEN_ACCESS_WRITEONLY (0001h)
	Opens the file for writing only.
OPEN_ACCESS_READWRITE (0002h)
	Opens the file for reading and writing.
0003h
	Reserved; do not use.
OPEN_ACCESS_RO_NOMODLASTACCESS (0004h)
	Opens the file for reading only without modifying the file’s last access date.
Sharing mode	Meaning
OPEN_SHARE_COMPATIBLE (0000h)
	Opens the file with compatibility mode, allowing any process on a given computer to open the file any number of times.
OPEN_SHARE_DENYREADWRITE (0010h)
	Opens the file and denies both read and write access to other processes.
OPEN_SHARE_DENYWRITE (0020h)
	Opens the file and denies write access to other processes.
OPEN_SHARE_DENYREAD (0030h)
	Opens the file and denies read access to other processes.
OPEN_SHARE_DENYNONE (0040h)
	Opens the file without denying read or write access to other processes, but no process may open the file with compatibility mode.
Open flags	Meaning
OPEN_FLAGS_NOINHERIT (0080h)
	If this flag is set, a child process created with Load and Execute Program (Interrupt 21h Function 4B00h) does not inherit the file handle. If the handle is needed by the child process, the parent process must pass the handle value to the child process. If this flag is not set, child processes inherit the file handle.
OPEN_FLAGS_NOCRITERR (2000h)
	If a critical error occurs while MS-DOS is opening this file, Critical-Error Handler (Interrupt 24h) is not called. Instead, MS-DOS simply returns an error value to the program.
OPEN_FLAGS_COMMIT (4000h)
	After each write operation, MS-DOS commits the file (flushes the contents of the cache buffer to disk).
Attributes

Attributes for files that are created or truncated. This parameter may be a combination of these values:

_A_NORMAL (0000h)
	The file can be read from or written to. This value is valid only if used alone.
_A_RDONLY (0001h)
	The file can be read from, but not written to.
_A_HIDDEN (0002h)
	The file is hidden and does not appear in an ordinary directory listing.
_A_SYSTEM (0004h)
	The file is part of the operating system or is used exclusively by it.
_A_VOLID (0008h)
	The name specified by Filename is used as the volume label for the current medium.
_A_ARCH (0020h)
	The file is an archive file. Applications use this value to mark files for backup or removal.
Action

Action to take it the file exists or does not exist. This parameter can be a combination of these values:

FILE_CREATE (0010h)	Creates a new file if it does not already exist or fails if the file already exists.
FILE_OPEN (0001h)	Opens the file. The function fails if the file does not exist.
FILE_TRUNCATE (0002h)	Opens the file and truncates it to zero length (replaces the existing file). The function fails if the file does not exist.
The only valid combinations are FILE_CREATE combined with FILE_OPEN or FILE_CREATE combined with FILE_TRUNCATE.

Filename

Address of a null-terminated string specifying the name of the file to be opened or created. The name must be in the standard MS-DOS 8.3 filename format. The string must be a valid path for the volume associated with the given drive.

Return Value

Clears the carry flag, copies the file handle to the AX register, and sets CX to one of the following values if successful:

ACTION_OPENED (0001h)

ACTION_CREATED_OPENED (0002h)

ACTION_REPLACED_OPENED (0003h)

Otherwise, this function sets the carry flag and sets the AX register to one of the following error values:

ERROR_INVALID_FUNCTION (0001h)

ERROR_FILE_NOT_FOUND (0002h)

ERROR_PATH_NOT_FOUND (0003h)

ERROR_TOO_MANY_OPEN_FILES (0004h)

ERROR_ACCESS_DENIED (0005h)

Remarks

This function does not support long filenames. If the specified name is too long, this function truncates the name to the standard 8.3 format following the same naming scheme that the system uses when creating an alias for a long filename.

A file on a remote directory — that is, a directory on the network — cannot be opened, unless appropriate permissions for the directory exist.


Interrupt 21h Function 710Dh

Flushes file system buffers and caches and optionally remounts the drivespace volume. Any write operations that the system has buffered are performed, and all waiting data is written to the appropriate drive.

mov ax, 710Dh      ; Reset Drive

mov cx, Flag       ; see below

mov dx, DriveNum   ; see below

int 21h

jc  error

Parameters

Flag

Flag specifying whether the system should flush and invalidate the data in the cache as well as the file system buffers. This parameter must be one of these values:

0000h	Resets the drive and flushes the file system buffers for the given drive.
0001h	Resets the drive, flushes the file system buffers, and flushes and invalidates the cache for the specified drive.
0002h	Remounts the drivespace volume.
The Flag value of 0002h is only supported on drivespace volumes. You should specify this value when the on-media format of the drivespace volume has changed and you want the file system to reinitialize and read the new format.

DriveNum

Drive to reset. This parameter can be 0 for the default drive, 1 for A, 2 for B, and so on.

Return Value

This function has no return value.


Interrupt 21h Function 7139h

Creates a new directory having the given name.

mov ax, 7139h     ; Make Directory

mov dx, seg Name  ; see below

mov ds, dx

mov dx, offset Name

int 21h

jc  error

Parameters

Name

Address of a null-terminated string specifying the name of the directory to create. Long filenames are allowed.

Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.


Interrupt 21h Function 713Ah

Removes the given directory. The directory must be empty.

mov ax, 713Ah     ; Remove Directory

mov dx, seg Name  ; see below

mov ds, dx

mov dx, offset Name

int 21h

jc  error

Parameters

Name

Address of a null-terminated string specifying the name of the directory to remove. Long filenames are allowed.

Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

The root directory cannot be deleted.


Interrupt 21h Function 713Bh

Changes the current directory to the directory specified by the given path.

mov ax, 713Bh     ; Change Directory

mov dx, seg Path  ; see below

mov ds, dx

mov dx, offset Path

int 21h

jc error

Parameters

Path

Address of a null-terminated string specifying the directory to change to. The path, which can include the drive letter, must be a valid path for the given volume. Long filenames are allowed.

Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

The current or default directory is the directory that the system uses whenever an application supplies a filename that does not explicitly specify a directory. Similarly, the current or default drive is the drive the system uses whenever an application supplies a path that does not explicitly specify a drive. If a drive other than the default drive is specified as part of the new directory path, this function changes the current directory on that drive but does not change the default drive. Set Default Drive (Interrupt 21h Function 0Eh) can be used to change the default drive.


Interrupt 21h Function 7141h

Deletes the given file or files. If the specified filename contains a wildcard character, this function can delete multiple files that match the wildcard.

mov ax, 7141h             ; Delete File

mov ch, MustMatchAttrs    ; see below

mov cl, SearchAttrs       ; see below

mov dx, seg Filename      ; see below

mov ds, dx

mov dx, offset Filename

mov si, WildcardAndAttrs  ; see below

int 21h

jc error

Parameters

MustMatchAttrs

Additional filter on the attributes specified in SearchAttrs. This parameter can be a combination of these values:

_A_NORMAL (0000h)
	The file can be read from or written to. This value is valid only if used alone.
_A_RDONLY (0001h)
	The file can be read from, but not written to.
_A_HIDDEN (0002h)
	The file is hidden and does not appear in an ordinary directory listing.
_A_SYSTEM (0004h)
	The file is part of the operating system or is used exclusively by it.
_A_VOLID (0008h)
	The name specified by Filename is used as the volume label for the current medium.
_A_SUBDIR (0010h)
	The name specified by Filename is used as a directory, not a file.
_A_ARCH (0020h)
	The file is an archive file. Applications use this value to mark files for backup or removal.
SearchAttrs

File attributes to search for. This parameter can be a combination of these values:

_A_NORMAL (0000h)

_A_RDONLY (0001h)

_A_HIDDEN (0002h)

_A_SYSTEM (0004h)

_A_VOLID (0008h)

_A_SUBDIR (0010h)

_A_ARCH (0020h)

Filename

Address of a null-terminated string specifying the name of the file to delete. If WildcardAndAttrs is 1, the “*” and “?” wildcard characters are permitted in the filename. Long filenames are allowed.

WildcardAndAttrs

Search criteria. This parameter must be one of these values:

0	Wildcard characters are not allowed in Filename. Any specified attributes are ignored.
1	Wildcard characters are allowed in Filename. Files with specified attributes are matched.
Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

Wildcard searches are more flexible in Windows 95 than in MS-DOS. Both long filenames and aliases are considered in searches. For example, *1 finds Windows 95 filenames (both long filenames and aliases) that end in a 1 and *mid* finds filenames that contain the characters mid. In MS-DOS and in Windows 95 searching on real-mode FAT directories, all characters after the first * are ignored.

For more information about how MustMatchAttrs and SearchAttrs are used, see the comments for Find First File (Interrupt 21h Function 714Eh).


Interrupt 21h Function 7143h

Retrieves or sets the file attributes, gets the compressed file size, or retrieves or sets the date and time for the given file.

mov ax, 7143h         ; Get or Set File Attributes
mov bl, Action        ; see below
mov cx, Attributes    ; see below
mov di, Date          ; see below
mov cx, Time          ; see below
mov si, MilliSeconds  ; see below
mov dx, seg Filename  ; see below
mov ds, dx
mov dx, offset Filename
int 21h

jc  error
; see below for return values

Parameters

Action

Action to take. This parameter can be one of the following values:

0	Retrieve attributes.
1	Set specified attributes.
2	Get physical size of a compressed file.
3	Set last write date/time.
4	Get last write date/time.
5	Set last access date.
6	Get last access date.
7	Set creation date/time.
8	Get creation date/time.
Attributes

File attributes to set, which are used only if Action is 1. This parameter can be a combination of these values:

_A_NORMAL (0000h)
	The file can be read from or written to. This value is valid only if used alone.
_A_RDONLY (0001h)
	The file can be read from, but not written to.
_A_HIDDEN (0002h)
	The file is hidden and does not appear in an ordinary directory listing.
_A_SYSTEM (0004h)
	The file is part of the operating system or is used exclusively by it.
_A_ARCH (0020h)
	The file is an archive file. Applications use this value to mark files for backup or removal.
Time

New time to set, which is used only if Action is 3 (set last write date/time) or 7 (set creation date/time) The time is a packed 16-bit value with the following form:

Bits	Contents
0−4	Second divided by 2
5−10	Minute (0−59)
11−15	Hour (0−23 on a 24-hour clock)
Date

New date to set, which is used only if Action is 3 (set last write date/time), 5 (set last access date), or 7 (set creation date/time). The date is a packed 16-bit value with the following form:

Bits	Contents
0−4	Day of the month (1−31)
5−8	Month (1 = January, 2 = February, and so on)
9−15	Year offset from 1980 (that is, add 1980 to get the actual year)
MilliSeconds

Number of 10 millisecond intervals in 2 seconds to add to the MS-DOS time. The number can be a value in the range 0 to 199. This value is only used if Action is 7 (set creation date/time).

Filename

Address of a null-terminated string specifying the name of the file to retrieve or set attributes for. Long filenames are allowed.

Return Value

Clears the carry flag if successful.

If Action is zero (retrieve attributes), the file attributes returned in the CX register may be a combination of the following values :

_A_NORMAL (0000h)

_A_RDONLY (0001h)

_A_HIDDEN (0002h)

_A_SYSTEM (0004h)

_A_VOLID (0008h)

_A_SUBDIR (0010h)

_A_ARCH (0020h)

If Action is 2 (get physical size of a compressed file), the size, in bytes, of the compressed file is returned in DX:AX. This value is the physical size of the compressed file — that is, the actual number of bytes that the compressed file occupies on disk.

If Action is 4 (get last write date/time) or 8 (get creation date/time), the CX register contains the time as a packed 16-bit value with the following form:

Bits	Contents
0−4	Second divided by 2
5−10	Minute (0−59)
11−15	Hour (0−23 on a 24-hour clock)
If Action is 4 (get last write date/time), 6 (get last access date), or 8 (get creation date/time), the DI register contains the date as a packed 16-bit value with the following form:

Bits	Contents
0−4	Day of the month (1−31)
5−8	Month (1 = January, 2 = February, and so on)
9−15	Year offset from 1980 (that is, add 1980 to get the actual year)
If Action is 8 (get creation date/time), the SI register contains the number of 10 millisecond intervals in 2 seconds to add to the MS-DOS time. The number can be a value in the range of 0 to 199.

If the function is not successful, it sets the carry flag and sets the AX register to an error value.


Interrupt 21h Function 7147h

Copies the path of the current directory for the given drive to the buffer. The copied path does not include the drive letter or the leading backslash.

mov ax, 7147h       ; Get Current Directory

mov dl, Drive       ; see below

mov si, seg Buffer  ; see below

mov ds, si

mov si, offset Buffer

int 21h

jc  error

Parameters

Drive

Drive number. This parameter can be 0 for current drive, 1 for A, 2 for B, and so on.

Buffer

Address of the buffer that receives the path. The buffer must be at least as big as the maximum allowed path for this volume as returned by Get Volume Information (Interrupt 21h Function 71A0h).

Return Value

Clears the carry flag and copies the path if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.


Interrupt 21h Function 714Eh

Searches a directory for the first file or directory whose name and attributes match the specified name and attributes.

mov ax, 714Eh             ; Find First File

mov ch, MustMatchAttrs    ; see below

mov cl, SearchAttrs       ; see below

mov dx, seg Filename      ; see below

mov ds, dx

mov dx, offset Filename

mov di, seg FindData      ; see below

mov es, di

mov di, offset FindData

mov si, DateTimeFormat    ; see below

int 21h

jc  error

mov [Handle], ax          ; search handle

mov [ConversionCode], cx  ; Unicode to OEM/ANSI conversion OK?

Parameters

MustMatchAttrs

Additional filter on the attributes specified in SearchAttrs. This parameter can be a combination of these values:

_A_NORMAL (0000h)
	The file can be read from or written to. This value is valid only if used alone.
_A_RDONLY (0001h)
	The file can be read from, but not written to.
_A_HIDDEN (0002h)
	The file is hidden and does not appear in an ordinary directory listing.
_A_SYSTEM (0004h)
	The file is part of the operating system or is used exclusively by it.
_A_VOLID (0008h)
	The name specified by Filename is used as the volume label for the current medium.
_A_SUBDIR (0010h)
	The name specified by Filename is used as a directory, not a file.
_A_ARCH (0020h)
	The file is an archive file. Applications use this value to mark files for backup or removal.
SearchAttrs

File attributes to search for. This parameter can be a combination of these values:

_A_NORMAL (0000h)

_A_RDONLY (0001h)

_A_HIDDEN (0002h)

_A_SYSTEM (0004h)

_A_VOLID (0008h)

_A_SUBDIR (0010h)

_A_ARCH (0020h)

Filename

Address of a null-terminated string specifying the name of the file or directory to search for. The name, which must be a valid filename or directory name, can include the “*” and “?” wildcard characters. Long filenames are allowed.

FindData

Address of a WIN32_FIND_DATA structure that receives information about the file.

DateTimeFormat

Date and time format to be returned. This parameter must be one of these values:

0	Returns the date and time in 64-bit file time format.
1	Returns the MS-DOS date and time values. MS-DOS date and time values are returned in the low doubleword of the FILETIME structure. Within the doubleword, the date is returned in the high-order word; the time is in the low-order word.
Return Value

Clears the carry flag, copies information about the file to the specified buffer, returns the search handle in the AX register, and sets the CX register to a combination of the following values if successful:

0x0000	All characters in the primary and alternate name members in the structure specified by FindData were successfully converted from Unicode.
0x0001	The primary name returned in the structure specified by FindData contains underscore characters in place of characters that could not be converted from Unicode.
0x0002	The alternate name returned in the structure specified by FindData contains underscore characters in place of characters that could not be converted from Unicode.
Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

Find First File and subsequent calls to Find Next File (Interrupt 21h Function 714Fh) use the following algorithm to match the attributes of a file or directory (referred to as Attributes in the algorithm) against MustMatchAttrs and SearchAttrs.

if  ((((<MustMatchAttrs> & ~<Attributes>) & 0x3F) == 0)
      && (((~<SearchAttrs> & <Attributes>) & 0x1E) == 0))
    {
         return the file or directory name
    }
    else
    {
         continue searching for the next name
    }

The following table lists the MustMatchAttrs and SearchAttrs values for some common searches where the specified filename is “*.*”. In the table, the word normal means that the read only, hidden, or system attributes have not been set. Parentheses are used to indicate that a file or directory has more than one attribute. For example, (hidden and system) indicates that a file or directory has both the hidden attribute and the system attribute.

MustMatchAttrs	SearchAttrs	Find results
10h	10h	All normal directories
10h	12h	All normal and hidden directories
10h	14h	All normal and system directories
10h	16h	All normal, hidden, system and (hidden and system) directories
12h	12h	All hidden directories
14h	14h	All system directories
16h	16h	All (hidden and system) directories
00h	00h	All normal files
00h	01h	All normal and read only files
00h	02h	All normal and hidden files
00h	04h	All normal and system files
00h	06h	All normal, hidden, system, and (hidden and system) files
00h	10h	All normal files and directories
01h	01h	All read only files
02h	02h	All hidden files
02h	06h	All hidden and (hidden and system) files
This function can be used to return the volume label by specifying only _A_VOLID (0008h) in both MustMatchAttrs and SearchAttrs.

An application may use the handle returned in the AX register in subsequent calls to Find Next File (Interrupt 21h Function 714Fh). It is important to close the handle when it is no longer needed by calling Find Close (Interrupt 21h Function 71A1h).

Wildcard searches are more flexible in Windows 95 than in MS-DOS. For example, *1 finds the filenames (both long filenames and aliases) that end in a 1, and *mid* finds filenames that contain the characters mid. In MS-DOS and in Windows 95 searching on real-mode FAT directories, all characters after the first * are ignored.


Interrupt 21h Function 714Fh

Searches for the next file in a directory, returning information about the file in the given buffer.

mov ax, 714Fh            ; Find Next File

mov bx, Handle           ; see below

mov di, seg FindData     ; see below

mov es, di

mov di, offset FindData

mov si, DateTimeFormat   ; see below

int 21h

jc error

mov [ConversionCode], cx  ; Unicode to OEM/ANSI conversion OK?

Parameters

Handle

Search handle. It must have been previously returned from Find First File (Interrupt 21h Function 714Eh).

FindData

Address of a WIN32_FIND_DATA structure that receives information about the file.

DateTimeFormat

Date and time format to be returned. This parameter must be one of these values:

0	Returns the date and time in 64-bit file time format.
1	Returns the MS-DOS date and time values. MS-DOS date and time values are returned in the low doubleword of the FILETIME structure. Within the doubleword, the date is returned in the high-order word; the time is in the low-order word.
Return Value

Clears the carry flag, copies information to the specified buffer, and sets the CX register to a combination of these values if successful:

0x0000	All characters in the primary and alternate name member in the structure specified by FindData were successfully converted from Unicode.
0x0001	The primary name returned in the structure specified by FindData contains underscore characters in place of characters that could not be converted from Unicode.
0x0002	The alternate name returned in the structure specified by FindData contains underscore characters in place of characters that could not be converted from Unicode.
Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

It is important to close the handle when it is no longer needed by calling Find Close (Interrupt 21h Function 71A1h).


Interrupt 21h Function 7156h

Changes the name of the given file or directory to the new name.

mov ax, 7156h           ; Rename File

mov dx, seg OldName     ; see below

mov ds, dx

mov dx, offset OldName

mov di, seg NewName     ; see below

mov es, di

mov di, offset NewName

int 21h

jc  error

Parameters

OldName

Address of a null-terminated string specifying the original name of the file or the directory to rename. Long filenames are allowed.

NewName

Address of a null-terminated string specifying the new name for the file or the directory. The function will fail if this parameter specifies an existing file or directory. The new name must not specify a drive different than the original drive. Long filenames are allowed.

Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.


Interrupt 21h Function 7160h Minor Code 0h

Retrieves the full path for the specified file or path.

mov ax, 7160h

mov cl, 0                  ; Get Full Path Name

mov ch, SubstExpand        ; see below

mov si, seg SourcePath     ; see below

mov ds, si

mov si, offset SourcePath

mov di, seg DestPath       ; see below

mov es, di

mov di, offset DestPath

int 21h

jc  error

Parameters

SubstExpand

Flag that indicates whether the returned path should contain a SUBST drive letter or the path associated with the SUBST drive. Zero is specified to indicate that the returned path should contain the path associated with the SUBST drive, and 80h is specified to indicate that the returned path should contain the SUBST drive letter.

SourcePath

Address of a null-terminated string that names the file or path to retrieve the full path for. Either the long filename or the standard 8.3 filename format is acceptable.

DestPath

Address of the buffer that receives the full path. The buffer should be large enough to contain the largest possible Windows 95 path (260 characters, including the drive letter, colon, leading backslash, and terminating null character).

Return Value

Clears the carry flag, modifies the AX register, and returns the full path in the given buffer if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

When just a filename is specified, this function merges the name of the current drive and directory with the specified filename to determine the full path. Relative paths containing the characters “.” and “..” in SourcePath are fully expanded. The function does no validation, so the specified filename or path does not need to exist.


Interrupt 21h Function 7160h Minor Code 1h

Retrieves the complete path in its short form (the standard 8.3 format) for the specified file or path. The function returns the 8.3 filename for all directories in the path.

mov ax, 7160h

mov cl, 1                  ; Get Short Path Name

mov ch, SubstExpand        ; see below

mov si, seg SourcePath     ; see below

mov ds, si

mov si, offset SourcePath

mov di, seg DestPath       ; see below

mov es, di

mov di, offset DestPath

int 21h

jc  error

Parameters

SubstExpand

Flag that indicates if the returned path should contain a SUBST drive letter or the path associated with the SUBST drive. Zero is specified to indicate that the returned path should contain the path associated with the SUBST drive, and 80h is specified to indicate that the returned path should contain the SUBST drive letter.

SourcePath

Address of a null-terminated string that names the file or path to retrieve the complete short path for. Either the long or short form is acceptable as the source string.

DestPath

Address of the buffer that receives the complete path. The buffer should be large enough to contain the largest possible Windows 95 path in the short form (260 characters, including the drive letter, colon, leading backslash, and terminating null character).

Return Value

Clears the carry flag, modifies the AX register, and returns the complete short path in the given buffer if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

Relative paths containing the characters “.” and “..” in SourcePath are fully expanded. Since this function performs validation, SourcePath must contain either a valid filename or path.


Interrupt 21h Function 7160h Minor Code 2h

Retrieves the complete path in its long filename form for the specified file or path. The function returns the long name for all directories in the path.

mov ax, 7160h

mov cl, 2                  ; Get Long Path Name

mov ch, SubstExpand        ; see below

mov si, seg SourcePath     ; see below

mov ds, si

mov si, offset SourcePath

mov di, seg DestPath       ; see below

mov es, di

mov di, offset DestPath

int 21h

jc  error

Parameters

SubstExpand

Flag that indicates if the returned path should contain a SUBST drive letter or the path associated with the SUBST drive. Zero is specified to indicate that the returned path should contain the path associated with the SUBST drive, and 80h is specified to indicate that the returned path should contain the SUBST drive letter.

SourcePath

Address of a null-terminated string that names the file or path to retrieve the complete long path for. Either the long filename or the short form is acceptable as the source string.

DestPath

Address of the buffer that receives the complete path. The buffer should be large enough to contain the largest possible Windows 95 path (260 characters, including the drive letter, colon, leading backslash, and terminating null character).

Return Value

Clears the carry flag, modifies the AX register, and returns the complete long path in the given buffer if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

Relative paths containing the characters “.” and “..” in SourcePath are fully expanded. Since this function performs validation, SourcePath must contain either a valid filename or path.


Interrupt 21h Function 716Ch

Creates or opens a file.

mov ax, 716Ch          ; Create or Open File

mov bx, ModeAndFlags   ; see below

mov cx, Attributes     ; see below

mov dx, Action         ; see below

mov si, seg Filename   ; see below

mov ds, si

mov si, offset Filename

mov di, AliasHint      ; see below

int 21h

jc error

mov [Handle], ax       ; file handle

mov [ActionTaken], cx  ; action taken to open file

Parameters

ModeAndFlags

Combination of access mode, sharing mode, and open flags. This parameter can be one value each from the access and sharing modes and any combination of open flags:

Access mode	Meaning
OPEN_ACCESS_READONLY (0000h)
	Opens the file for reading only.
OPEN_ACCESS_WRITEONLY (0001h)
	Opens the file for writing only.
OPEN_ACCESS_READWRITE (0002h)
	Opens the file for reading and writing.
0003h
	Reserved; do not use.
OPEN_ACCESS_RO_NOMODLASTACCESS (0004h)
	Opens the file for reading only without modifying the file’s last access date.
Sharing mode	Meaning
OPEN_SHARE_COMPATIBLE (0000h)
	Opens the file with compatibility mode, allowing any process on a given computer to open the file any number of times.
OPEN_SHARE_DENYREADWRITE (0010h)
	Opens the file and denies both read and write access to other processes.
OPEN_SHARE_DENYWRITE (0020h)
	Opens the file and denies write access to other processes.
OPEN_SHARE_DENYREAD (0030h)
	Opens the file and denies read access to other processes.
OPEN_SHARE_DENYNONE (0040h)
	Opens the file without denying read or write access to other processes, but no process may open the file for compatibility access.
Open flags	Meaning
OPEN_FLAGS_NOINHERIT (0080h)
	If this flag is set, a child process created with Load and Execute Program (Interrupt 21h Function 4B00h) does not inherit the file handle. If the handle is needed by the child process, the parent process must pass the handle value to the child process. If this flag is not set, child processes inherit the file handle.
OPEN_FLAGS_NO_BUFFERING (0100h)
	The file is to be opened with no intermediate buffering or caching done by the system. Read and write operations access the disk directly. All reads and writes to the file must be done at file positions that are multiples of the disk sector size, in bytes, and the number of bytes read or written should also be a multiple of the sector size. Applications can determine the sector size, in bytes, with the Get Disk Free Space function (Interrupt 21h, Function 36h).
OPEN_FLAGS_NO_COMPRESS (0200h)
	The file should not be compressed on a volume that performs file compression. If the volume does not perform file compression, this flag is ignored. This flag is valid only on file creation and is ignored on file open.
OPEN_FLAGS_ALIAS_HINT (0400h)
	The number in the DI register is to be used as the numeric tail for the alias (short filename). For more information, see AliasHint below.
OPEN_FLAGS_NOCRITERR (2000h)
	If a critical error occurs while MS-DOS is opening this file, Critical-Error Handler (Interrupt 24h) is not called. Instead, MS-DOS simply returns an error value to the program.
OPEN_FLAGS_COMMIT (4000h)
	After each write operation, MS-DOS commits the file (flushes the contents of the cache buffer to disk).
Attributes

Attributes for files that are created or truncated. This parameter may be a combination of these values:

_A_NORMAL (0000h)
	The file can be read from or written to. This value is valid only if used alone.
_A_RDONLY (0001h)
	The file can be read from, but not written to.
_A_HIDDEN (0002h)
	The file is hidden and does not appear in an ordinary directory listing.
_A_SYSTEM (0004h)
	The file is part of the operating system or is used exclusively by it.
_A_VOLID (0008h)
	The name specified by Filename is used as the volume label for the current medium and is restricted to the standard 8.3 format. For information about an alternative way to set the volume label, see Set Media ID (Interrupt 21h Function 440Dh Minor Code 46h) in the Microsoft MS-DOS Programmer’s Reference.
_A_ARCH (0020h)
	The file is an archive file. Applications use this value to mark files for backup or removal.
Action

Action to take it the file exists or if it does not exist. This parameter can be a combination of these values:

FILE_CREATE (0010h)	Creates a new file if it does not already exist. The function fails if the file already exists.
FILE_OPEN (0001h)	Opens the file. The function fails if the file does not exist.
FILE_TRUNCATE (0002h)	Opens the file and truncates it to zero length (replaces the existing file). The function fails if the file does not exist.
The only valid combinations are FILE_CREATE combined with FILE_OPEN or FILE_CREATE combined with FILE_TRUNCATE.

Filename

Address of a null-terminated string specifying the name of the file to be opened or created. The string must be a valid path for the volume associated with the given drive. Long filenames are allowed.

AliasHint

Number that is used in the numeric tail for the alias (short filename). A numeric tail, which consists of the tilde character (~) followed a number, is appended to the end of a filename. The system constructs the alias from the first few characters of the long filename followed by the numeric tail. The system starts with the number 1 in the numeric tail. If that filename is in use, it uses the number 2. It continues in this fashion until a unique name is found. To override the default numbering scheme, you must specify the OPEN_FLAGS_ALIAS_HINT value when you create the file in addition to specifying this parameter. If a filename already exists with the specified numeric tail, the system uses the default numbering scheme. You should specify a number for this parameter, not the tilde character.

Return Value

Clears carry flag, copies the file handle to the AX register, and sets the CX register to one of the following values if successful:

ACTION_OPENED (0001h)

ACTION_CREATED_OPENED (0002h)

ACTION_REPLACED_OPENED (0003h)

Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

A file on a remote directory — that is, a directory on the network — cannot be opened, created, or modified, unless the appropriate permissions for the directory exist.


Interrupt 21h Function 71A0h

Returns information about the volume associated with the given root directory.

mov ax, 71A0h          ; Get Volume Information

mov di, seg Buffer     ; see below

mov es, di

mov di, offset Buffer

mov cx, BufSize        ; see below

mov dx, seg RootName   ; see below

mov ds, dx

mov dx, offset RootName

int 21h

jc  error

mov [Flags], bx        ; file system flags

mov [MaxFilename], cx  ; max. filename length, excluding null

mov [MaxPath], dx      ; max. path length, including null

Parameters

Buffer

Address of a buffer that receives a null-terminated string specifying the name of the file system.

BufSize

Size, in bytes, of the buffer that receives the name. The buffer should include space for the terminating null character.

RootName

Address of a null-terminated string specifying the name of the root directory of the volume to check. This parameter must not be NULL, or the function will fail. The format for this parameter is “C:\”.

Return Value

Clears the carry flag, copies the file system name to the buffer given by the ES:DI register pair, and sets the BX, CX, and DX registers to the following values if successful:

BX	File system flags, which can be a combination of these values:

FS_CASE_SENSITIVE (0001h)
Specifies that searches are case-sensitive.

FS_CASE_IS_PRESERVED (0002h)
Preserves case in directory entries.

FS_UNICODE_ON_DISK (0004h)
Uses Unicode characters in file and directory names.

FS_LFN_APIS (4000h)
Supports new long filename functions.

   FS_VOLUME_COMPRESSED (8000h)
Specifies that the volume is compressed.

CX	Maximum allowed length, excluding the terminating null character, of a filename for this volume. For example, on the protected-mode FAT file system, this value is 255.
DX	Maximum allowed length of a path for this volume, including the drive letter, colon, leading slash, and terminating null character. For example, on the protected-mode FAT file system, this value is 260.
Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

This function accesses the disk the first time it is called, but subsequent calls do not access the disk.


Interrupt 21h Function 71A1h

Closes the file search identified by the search handle.

mov ax, 71A1h   ; Find Close

mov bx, Handle  ; see below

int 21h

jc  error

Parameters

Handle

Search handle. It must have been previously returned from Find First File (Interrupt 21h Function 714Eh).

Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

Unlike MS-DOS Find First File (Interrupt 21h Function 4Eh), the long filename version of Find First File (Interrupt 21h Function 714Eh) allocates internal storage for the search operations and returns a handle that identifies the storage. This handle is used with Find Next File. To make sure this internal storage is freed, you must call Find Close to end the search.


Interrupt 21h Function 71A6h

Retrieves information about the specified file.

mov ax, 71a6h              ; Get File Info By Handle

mov bx, Handle             ; see below

mov dx, seg lpFileInfo     ; see below

mov ds, dx

mov dx, offset lpFileInfo

stc                        ; must set carry flag

int 21h

jnc success

cmp ax, 7100h

je not_supported

Parameters

Handle

File handle to retrieve information about.

lpFileInfo

Address of a BY_HANDLE_FILE_INFORMATION structure that receives the file information. The structure can be used in subsequent calls to Get File Info By Handle to refer to the information about the file.

Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

Note that it is important to explicitly set the carry flag before calling this function.


Interrupt 21h Function 71A7h Minor Code 0h

Converts a 64-bit file time to MS-DOS date and time values.

mov ax, 71A7h           ; date and time format conversion

mov bl, 0               ; File Time To DOS Time

mov si, seg lpft        ; see below

mov ds, si

mov si, offset lpft

int 21h

jc  error

mov [DOSTime], cx

mov [DOSDate], dx

mov [MilliSeconds], bh  ; number of 10ms intervals in 2 seconds

Parameters

lpft

Address of a FILETIME structure containing the 64-bit file time to convert to the MS-DOS date and time format.

Return Value

Clears the carry flag, and sets the BH, CX, and DX registers to these values if successful:

BH	Number of 10 millisecond intervals in 2 seconds to add to the MS-DOS time. It can be a value in the range 0 to 199.
CX	MS-DOS time. The time is a packed 16-bit value with the following form:
Bits	Contents
0−4	Second divided by 2
5−10	Minute (0−59)
11−15	Hour (0−23 on a 24-hour clock)
DX	MS-DOS date. The date is a packed 16-bit value with the following form:
Bits	Contents
0−4	Day of the month (1−31)
5−8	Month (1 = January, 2 = February, and so on)
9−15	Year offset from 1980 (that is, add 1980 to get the actual year)
Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

The MS-DOS date format can represent only dates between 1/1/1980 and 12/31/2107; this conversion fails if the input file time is outside this range.

The time in FILETIME must be Coordinated Universal Time (UTC). The MS-DOS time is local time.


Interrupt 21h Function 71A7h Minor Code 1h

Converts MS-DOS date and time values to 64-bit file time.

mov ax, 71A7h         ; date and time format conversion

mov bl, 1             ; Dos Time To File Time

mov bh, MilliSeconds  ; see below

mov cx, DOSTime       ; see below

mov dx, DOSDate       ; see below

mov di, seg lpft      ; see below

mov es, di

mov di, offset lpft

int 21h

jc  error

Parameters

MilliSeconds

Number of 10 millisecond intervals in 2 seconds to add to the MS-DOS time. The number can be a value in the range 0 to 199.

DOSTime

MS-DOS time to convert. The time is a packed 16-bit value with the following form:

Bits	Contents
0−4	Second divided by 2
5−10	Minute (0−59)
11−15	Hour (0−23 on a 24-hour clock)
DOSDate

MS-DOS date to convert. The date is a packed 16-bit value with the following form:

Bits	Contents
0−4	Day of the month (1−31)
5−8	Month (1 = January, 2 = February, and so on)
9−15	Year offset from 1980 (that is, add 1980 to get the actual year)
lpft

Address of a FILETIME structure to receive the converted 64-bit file time.

Return Value

Clears the carry flag and returns the 64-bit file time in the specified structure if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

The time in FILETIME must be Coordinated Universal Time (UTC). The MS-DOS time is local time.


Interrupt 21h Function 71A8h

Generates an alias (a filename in the 8.3 format) for the specified long filename.

mov ax, 71a8h               ; generate short name

mov si, seg LongFilename    ; see below

mov ds, si

mov si, offset LongFilename

mov di, seg ShortFilename   ; see below

mov es, di

mov di, offset ShortFilename

mov dh, ShortNameFormat     ; see below

mov dl, CharSet             ; see below

int 21h

Parameters

LongFilename

Address of null-terminated string that names the long filename to generate an alias for. This string must contain only a filename, not a path.

ShortFilename

Address of null-terminated string that receives the generated alias.

ShortNameFormat

Format for the returned alias (0 is specified for an 11 character directory entry format or 1 for an 8.3 format).

CharSet

Character set of both the long filename and alias. This parameter is a packed 8-bit value with the following form:

Bits	Contents
0−3	Specifies the character set of the source long filename.
4−7	Specifies the character set of the destination alias.
One of the following values is specified to indicate the character set for the long filename and alias:

BCS_WANSI (0)	Windows ANSI character set
BCS_OEM (1)	Current OEM character set
BCS_UNICODE (2)	Unicode character set
Return Value

Returns the generated alias in the specified buffer if successful.

Remarks

This function generates the alias using the same algorithm that the system uses with the exception that the returned alias will never have a numeric tail. A numeric tail is appended to the end of an alias and consists of the tilde character (~) followed a number. When the system generates an alias, it may attach a numeric tail if the default alias already exists in the current directory. Because this function does not check the current directory to see if the alias already exists, the returned alias will never have a numeric tail. This service is useful for disk utilities that are trying to establish whether the alias, which seems to be associated with a long filename, is correctly associated.


Interrupt 21h Function 71A9h

Creates or opens a file. This function is for use by real-mode servers only. It takes the same parameters as Create or Open File (Interrupt 21h Function 716Ch) and returns a global file handle.


Interrupt 21h Function 71AAh Minor Code 0h

Associates a path with a drive letter.

mov ax, 71aah            ; SUBST

mov bh, 0                ; Create Subst

mov bl, DriveNum         ; see below

mov dx, seg PathName     ; see below

mov ds, dx

mov dx, offset PathName

int 21h

jc error

Parameters

DriveNum

Drive to SUBST. This parameter can be 0 for the default drive, 1 for A, 2 for B, and so on.

PathName

Address of path to associate the drive with.

Return Value

Clears the carry flag if successful. Otherwise the function sets the carry flag and returns an error value in the AX register


Interrupt 21h Function 71AAh Minor Code 1h

Terminate the association between a path and a drive letter.

mov ax, 71aah            ; SUBST

mov bh, 1                ; Terminate Subst

mov bl, DriveNum         ; see below

int 21h

jc error

Parameters

DriveNum

Drive to terminate SUBST. This parameter can 1 for A, 2 for B, and so on. Note that DriveNum cannot be 0 to indicate the default drive.

Return Value

Clears the carry flag if successful. Otherwise, the function sets the carry flag and returns an error value in the AX register.


Interrupt 21h Function 71AAh Minor Code 2h

Determines if the specified drive is associated with a path and, if it is, retrieves the associated path.

mov ax, 71aah            ; SUBST

mov bh, 2                ; Query SUBST

mov bl, DriveNum         ; see below

mov dx, seg PathName     ; see below

mov ds, dx

mov dx, offset PathName

int 21h

jc error

Parameters

DriveNum

Drive to SUBST. This parameter can 1 for A, 2 for B, and so on. Note that DriveNum cannot be 0 to indicate the default drive.

PathName

Address of buffer that receives the null-terminated string of the path associated with the specified drive. The buffer must be of MAXPATHLEN size.

Return Value

Clears the carry flag and retrieves the associated path in the specified buffer if successful. Otherwise, the function sets the carry flag and returns an error value in the AX register.


Module32First

Retrieves information about the first module associated with a process.

BOOL WINAPI Module32First(HANDLE hSnapshot, LPMODULEENTRY32 lpme);

Parameters

hSnapshot

Handle of the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lpme

Address of a buffer containing a MODULEENTRY32 structure.

Return Value

Returns TRUE if the first entry of the module list has been copied to the buffer or FALSE otherwise. The ERROR_NO_MORE_FILES error value is returned by the GetLastError function if no modules exist or the snapshot does not contain module information.

Remarks

The calling application must set the dwSize member of MODULEENTRY32 to the size, in bytes, of the structure. Module32First changes dwSize to the number of bytes written to the structure. This will never be greater than the initial value of dwSize, but it may be smaller. If the value is smaller, do not rely on the values of any members whose offsets are greater than this value.

To retrieve information about other modules associated with the specified process, use the Module32Next function.


Module32Next

Retrieves information about the next module associated with a process or thread.

BOOL WINAPI Module32Next(HANDLE hSnapshot, LPMODULEENTRY32 lpme);

Parameters

hSnapshot

Handle of the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lpme

Address of a buffer containing a MODULEENTRY32 structure.

Return Value

Returns TRUE if the next entry of the module list has been copied to the buffer or FALSE otherwise. The ERROR_NO_MORE_FILES error value is returned by the GetLastError function if no more modules exist.

Remarks

To retrieve information about first module associated with a process, use the Module32First function.


Process32First

Retrieves information about the first process encountered in a system snapshot.

BOOL WINAPI Process32First(HANDLE hSnapshot, LPPROCESSENTRY32 lppe);

Parameters

hSnapshot

Handle of the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lppe

Address of a PROCESSENTRY32 structure.

Return Value

Returns TRUE if the first entry of the process list has been copied to the buffer or FALSE otherwise. The ERROR_NO_MORE_FILES error value is returned by the GetLastError function if no processes exist or the snapshot does not contain process information.

Remarks

The calling application must set the dwSize member of PROCESSENTRY32 to the size, in bytes, of the structure. Process32First changes dwSize to the number of bytes written to the structure. This will never be greater than the initial value of dwSize, but it may be smaller. If the value is smaller, do not rely on the values of any members whose offsets are greater than this value.

To retrieve information about other processes recorded in the same snapshot, use the Process32Next function.


Process32Next

Retrieves information about the next process recorded in a system snapshot.

BOOL WINAPI Process32Next(HANDLE hSnapshot, LPPROCESSENTRY32 lppe);

Parameters

hSnapshot

Handle of the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lppe

Address of a PROCESSENTRY32 structure.

Return Value

Returns TRUE if the next entry of the process list has been copied to the buffer or FALSE otherwise. The ERROR_NO_MORE_FILES error value is returned by the GetLastError function if no processes exist or the snapshot does not contain process information.

Remarks

To retrieve information about the first process recorded in a snapshot, use the Process32First function.


Query Close

Indicates whether the user has attempted to close an MS-DOS − based application from Windows by choosing the Close command from the system menu.

mov ah, 16h   ; Windows multiplex function

mov al, 8Fh   ; VM Close

mov dh, 1     ; Query Close

mov dl, 0     ; always 0

int 2Fh

Return Value

Returns one of the following values in the AX register:

0	The close command was chosen, and the application has not acknowledged the close state.
1	The close command was chosen, and the application has acknowledged the close state.
168Fh	The close command has not been chosen, and the application should continue running.
Remarks

Query Close returns a nonzero value if the application has not enabled the Close command by using the Enable or Disable Close Command function.


RegisterServiceProcess

The RegisterServiceProcess function registers or unregisters a service process. A service process continues to run after the user logs off.

DWORD RegisterServiceProcess(DWORD dwProcessId,
    DWORD dwType);

Parameters

dwProcessId

Specifies the identifier of the process to register as a service process. Specifies NULL to register the current process.

dwType

Specifies whether the service is to be registered or unregistered. This parameter can be one of the following values.

Value	Meaning
RSP_SIMPLE_SERVICE	Registers the process as a service process.
RSP_UNREGISTER_SERVICE	Unregisters the process as a service process.
Return Value

The return value is 1 if successful or 0 if an error occurs.


Set Application Title

Sets the application title to the given string.

mov  ah, 16h           ; Windows multiplex function

mov  al, 8Eh           ; VM Title

mov  di, seg AppTitle  ; see below

mov  es, di

mov  di, offset AppTitle

mov  dx, 0             ; Set Application Title

int  2Fh

cmp   ax, 1

je   success

Parameters

AppTitle

Address of a null-terminated string specifying the application title. The title must not exceed 80 characters, including the terminating null character. If this parameter is zero or points to an empty string, the function removes the current application title.

Return Value

Returns 1 in the AX register if successful or zero otherwise.

Remarks

Although not common, Set Application Title may return 1 in the AX register even though the title was not changed. In general, applications must not rely on the operating system to keep an accurate copy of the current title.


Set Virtual Machine Title

Sets the virtual machine title to the given string. Applications should not change the virtual machine title except under explicit instructions from the user.

mov  ah, 16h           ; Windows multiplex function

mov  al, 8Eh           ; VM Title

mov  di, seg VMTitle   ; see below

mov  es, di

mov  di, offset VMTitle

mov  dx, 1             ; Set Virtual Machine Title

int  2Fh

cmp   ax, 1

je   success

Parameters

VMTitle

Address of a null-terminated string specifying the virtual machine title. The title must not exceed 30 characters, including the terminating null character. If this parameter is zero or points to an empty string, the function removes the current virtual machine title.

Return Value

Returns 1 in the AX register if successful or zero otherwise.

Remarks

Although not common, Set Virtual Machine Title may return 1 in the AX register even though the title was not changed. In general, applications must not rely on the operating system to keep an accurate copy of the current title.


Thread32First

Retrieves information about the first thread of any process encountered in a system snapshot.

BOOL WINAPI Thread32First(HANDLE hSnapshot, LPTHREADENTRY32 lpte);

Parameters

hSnapshot

Handle of the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lpte

Address of a THREADENTRY32 structure.

Return Value

Returns TRUE if the first entry of the thread list has been copied to the buffer or FALSE otherwise. The ERROR_NO_MORE_FILES error value is returned by the GetLastError function if no threads exist or the snapshot does not contain thread information.

Remarks

The calling application must set the dwSize member of THREADENTRY32 to the size, in bytes, of the structure. Thread32First changes dwSize to the number of bytes written to the structure. This will never be greater than the initial value of dwSize, but it may be smaller. If the value is smaller, do not rely on the values of any members whose offsets are greater than this value.

To retrieve information about other threads recorded in the same snapshot, use the Thread32Next function.


Thread32Next

Retrieves information about the next thread of any process encountered in the system memory snapshot.

BOOL WINAPI Thread32Next(HANDLE hSnapshot, LPTHREADENTRY32 lpte);

Parameters

hSnapshot

Handle of the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lpte

Address of a THREADENTRY32 structure.

Return Value

Returns TRUE if the next entry of the thread list has been copied to the buffer or FALSE otherwise. The ERROR_NO_MORE_FILES error value is returned by the GetLastError function if no threads exist or the snapshot does not contain thread information.

Remarks

To retrieve information about the first thread recorded in a snapshot, use the Thread32First function.


Toolhelp32ReadProcessMemory

Copies memory allocated to another process into an application-supplied buffer.

BOOL WINAPI Toolhelp32ReadProcessMemory(DWORD th32ProcessID,
    LPCVOID lpBaseAddress, LPVOID lpBuffer, DWORD cbRead,
    LPDWORD lpNumberOfBytesRead);

Parameters

th32ProcessID

Identifier of the process whose memory is being copied. This parameter can be zero to copy the memory of the current process.

lpBaseAddress

Base address in the specified process to read. Before transferring any data, the system verifies that all data in the base address and memory of the specified size is accessible for read access. If this is the case, the function proceeds. Otherwise, the function fails.

lpBuffer

Address of the buffer that receives the contents of the address space of the specified process.

cbRead

Number of bytes to read from the specified process.

lpNumberOfBytesRead

Number of bytes copied to the specified buffer. If this parameter is NULL, it is ignored.

Return Value

Returns TRUE if successful.


VWIN32_DIOCCompletionRoutine

Notifies the system that an asynchronous operation in a virtual device driver is complete. The VxD calls this service after the asynchronous input and output (I/O) operation to signal the application.

mov ebx, Internal  ; see below
VxDCall VWIN32_DIOCCompletionRoutine

Parameters

Internal

Event identifier. This parameter must be the same value initially passed to the VxD in the Internal member of the OVERLAPPED structure.

Return Value

No return value.

Remarks

Before calling this service, the VxD must set the InternalHigh member of the OVERLAPPED structure to the number of bytes of return data.


W32_DEVICEIOCONTROL

Passes a control code and related information to a virtual device driver.

include VMM.INC

mov ebx, VMHandle

mov eax, W32_DEVICEIOCONTROL

mov esi, OFFSET32 dioparams

VMMCall System_Control

Parameters

VMHandle

Handle of the virtual machine.

dioparams

Address of a DIOCParams structure containing a control code and information that the VxD needs to process the control code.

Return Value

Returns one of the following values in the EAX register:

0	The control code processed successfully.
− 1	An asynchronous operation is in progress. A VxD must return this value only if the lpoOverlapped member of the DIOCParams structure is not NULL.
Error code	An error occurred.
Remarks

This message is sent to a VxD when an application specifies the name of a VxD in the CreateFile function and when an application specifies the device handle of the VxD in a call to the DeviceIoControl or CloseHandle function. This message uses the ESI register.


DIOC_REGISTERS

Contains the register values for calling Interrupt 21h commands through the DeviceIoControl function. The meaning of the registers depends on the given command.

typedef struct DIOCRegs {

    DWORD   reg_EBX;

    DWORD   reg_EDX;

    DWORD   reg_ECX;

    DWORD   reg_EAX;

    DWORD   reg_EDI;

    DWORD   reg_ESI;

    DWORD   reg_Flags;

} DIOC_REGISTERS;

Members

reg_EBX

EBX register.

reg_EDX

EDX register.

reg_ECX

ECX register.

reg_EAX

EAX register

reg_EDI

EDI register.

reg_ESI

ESI register.

reg_Flags

Flags register.

Remarks

Some interrupt functions require far pointers passed in segment:offset pairs where the segment is placed in a segment register. Since the 32-bit code does not have segments, the DIOC_REGISTERS structure contains no segment registers. You should place the full pointer into the structure member that corresponds to the register used to hold the offset portion of the real-mode pointer. For example, use reg_EDX for pointers that go into the DS:DX registers.


DIOCParams

Contains information that an application has passed to the virtual device driver (VxD) by calling the DeviceIoControl function.

include vwin32.inc

DIOCParams STRUC
    Internal1             DD  ?
    VMHandle              DD  ?
    Internal2             DD  ?
    dwIoControlCode       DD  ?
    lpvInBuffer           DD  ?
    cbInBuffer            DD  ?
    lpvOutBuffer          DD  ?
    cbOutBuffer           DD  ?
    lpcbBytesReturned     DD  ?
    lpoOverlapped         DD  ?
    hDevice               DD  ?
    tagProcess            DD  ?
DIOCParams ENDS

Members

Internal1

Reserved.

VMHandle

Handle of virtual machine.

Internal2

Reserved.

dwIoControlCode

Control code to process. This member can be a developer-defined value or one of these system-defined values:

DIOC_CLOSEHANDLE	Notifies a VxD that an application has closed its device handle for the VxD. The VxD should perform cleanup operations and release any structures associated with the application.
DIOC_GETVERSION	Queries the VxD to determine if it supports the device IOCTL interface. If the VxD supports the interface, it must clear the EAX register. Otherwise, it must place a nonzero value in EAX. If cbOutBuffer is nonzero and the VxD supports the interface, the VxD should copy version information to the lpvOutBuffer.
lpvInBuffer

Address of a buffer that contains data needed to process the control code.

cbInBuffer

Size, in bytes, of the buffer pointed to by lpvInBuffer.

lpvOutBuffer

Address of a buffer that receives the results of processing the control code.

cbOutBuffer

Size, in bytes, of the buffer pointed to by lpvOutBuffer.

lpcbBytesReturned

Number of bytes copied to the buffer pointed to by lpvOutBuffer.

lpoOverlapped

Address of an OVERLAPPED structure that contains information used to complete the command asynchronously. If the command is to be completed synchronously, this member is NULL.

hDevice

Handle of device.

tagProcess

Information that the VxD can use to tag the current request along with hDevice. When the VxD receives a DIOC_CLOSEHANDLE control code for hDevice and tagProcess, it should perform appropriate cleanup operations.


DRIVE_MAP_INFO

Contains information about the drive specified in the call to Get Drive Map Info (Interrupt 2lh Function 440Dh Minor Code 6Fh).

DRIVE_MAP_INFO	struc

    dmiAllocationLength   db ?
    dmiInfoLength         db ?
    dmiFlags              db ?
    dmiInt13Unit          db ?
    dmiAssociatedDriveMap dd ?
    dmiPartitionStartRBA  dq ?
DRIVE_MAP_INFO	ends

Members

dmiAllocationLength

Length of the buffer provided by the application calling Get Drive Map Info. This value should be the size of the DRIVE_MAP_INFO structure.

dmiInfoLength

Number of bytes that Get Drive Map Info used in the buffer provided by the calling application. Typically, this value is the size of the DRIVE_MAP_INFO structure.

dmiFlags

Flags describing the given drive. This member, which is filled by Get Drive Map Info, can be a combination of these values:

PROT_MODE_LOGICAL_DRIVE (01h)	A protected-mode driver is in use for this logical drive.
PROT_MODE_PHYSICAL_DRIVE (02h)	A protected-mode driver is in use for the physical drive corresponding to this logical drive.
PROT_MODE_ONLY_DRIVE (04h)	The drive is not available when running with MS-DOS.
PROT_MODE_EJECT (08h)	A protected-mode drive supports an electronic eject operation.
PROT_MODE_ASYNC_NOTIFY (10h)	The drive issues media arrival and removal notifications. This value is currently used for CD-ROM drives that are controlled by the protected-mode driver and that cause a broadcast message when media is removed or inserted without the application having to make a request to the drive. It can also be used by disk drivers.
dmiInt13Unit

Physical drive number of the given drive. This member, which is filled by Get Drive Map Info, can be one of these values:

00 - 7Fh	Floppy disk drive (00 for the first floppy drive, 01 for the second, and so on).
80 - FEh	Hard disk drive (80 for the first hard disk drive, 81 for the second, and so on).
FFh	The given drive does not map to a physical drive.
dmiAssociatedDriveMap

Logical drive numbers that are associated with the given physical drive. For example, a host drive C with child drive letters A and B would return with bits 0 and 1 set.

dmiPartitionStartRBA

Relative block address offset from the start of the physical volume to the start of the given partition.

Remarks

Before an application makes a call to Get Drive Map Info, the dmiAllocationLength member must be set to the size of the DRIVE_MAP_INFO structure. All other members of the structure are filled in by Get Drive Map Info.


HEAPENTRY32

Describes one entry (block) of a heap that is being examined.

typedef struct tagHEAPENTRY32

{

    DWORD  dwSize;

    HANDLE hHandle;

    DWORD  dwAddress;

    DWORD  dwBlockSize;

    DWORD  dwFlags;

    DWORD  dwLockCount;

    DWORD  dwResvd;

    DWORD  th32ProcessID;

    DWORD  th32HeapID;

} HEAPENTRY32;

typedef HEAPENTRY32 *  PHEAPENTRY32;

typedef HEAPENTRY32 *  LPHEAPENTRY32;

Members

dwSize

Specifies the length, in bytes, of the structure. Before calling the Heap32First function, set this member to

sizeof(HEAPENTRY32).

hHandle

Handle of the heap block.

dwAddress

Linear address of the start of the block.

dwBlockSize

Size, in bytes, of the heap block.

dwFlags

Flags. These values are defined:

LF32_FIXED	The memory block has a fixed (unmovable) location.
LF32_FREE	The memory block is not used.
LF32_MOVEABLE	The memory block location can be moved.
dwLockCount

Lock count on the memory block. The lock count is incremented each time the GlobalLock or LocalLock function is called on the block either by the application or the DLL that the heap belongs to.

dwResvd

Reserved; do not use.

th32ProcessID

Identifier of the process to examine. The contents of this member can be used by Win32 API elements.

th32HeapID

Heap identifier in the owning process context. The contents of this member has meaning only to the tool help functions. It is not a handle, nor is it usable by Win32 API elements.


HEAPLIST32

Describes an entry from a list that enumerates the heaps used by a specified process.

typedef struct tagHEAPLIST32 {

    DWORD dwSize;

    DWORD th32ProcessID;

    DWORD th32HeapID;

    DWORD dwFlags;

} HEAPLIST32;

typedef HEAPLIST32 *  PHEAPLIST32;

typedef HEAPLIST32 *  LPHEAPLIST32;

Members

dwSize

Specifies the length, in bytes, of the structure. Before calling the Heap32ListFirst function, set this member to

sizeof(HEAPLIST32).

th32ProcessID

Identifier of the process to examine. The contents of this member can be used by Win32 API elements.

th32HeapID

Heap identifier in the owning process context. The contents of this member has meaning only to the tool help functions. It is not a handle, nor is it usable by Win32 API elements.

dwFlags

Flags. These values are defined:

HF32_DEFAULT	Process’s default heap


MID

Contains information that uniquely identifies a disk or other storage medium.

MID struc
    midInfoLevel   dw 0
    midSerialNum   dd ?
    midVolLabel    db 11 dup (?)
    midFileSysType db 8 dup (?)
MID ends

Members

midInfoLevel

Information level. This member must be zero.

midSerialNum

Serial number for the medium.

midVolLabel

Volume label for the medium. If the label has fewer than 11 characters, space characters (ASCII 20h) fill the remaining bytes in this member.

midFileSysType

Type of file system as an 8-byte ASCII string. This member can be one of these values:

FAT12	12-bit file allocation table (FAT)
FAT16	16-bit FAT
CDROM	High Sierra file system
CD001	ISO9660 file system
CDAUDIO	Audio disk
If the name has fewer than eight characters, space characters (ASCII 20h) fill the remaining bytes in this member.


MODULEENTRY32

Describes an entry from a list that enumerates the modules used by a specified process.

typedef struct tagMODULEENTRY32 {

    DWORD   dwSize;

    DWORD   th32ModuleID;

    DWORD   th32ProcessID;

    DWORD   GlblcntUsage;

    DWORD   ProccntUsage;

    BYTE  * modBaseAddr;

    DWORD   modBaseSize;

    HMODULE hModule;

    char    szModule[MAX_MODULE_NAME32 + 1];

    char    szExePath[MAX_PATH];

} MODULEENTRY32;

typedef MODULEENTRY32 *  PMODULEENTRY32;

typedef MODULEENTRY32 *  LPMODULEENTRY32;

Members

dwSize

Specifies the length, in bytes, of the structure. Before calling the Module32First function, set this member to

sizeof(MODULEENTRY32).

th32ModuleID

Module identifier in the context of the owning process. The contents of this member has meaning only to the tool help functions. It is not a handle, nor is it usable by Win32 API elements.

th32ProcessID

Identifier of the process being examined. The contents of this member can be used by Win32 API elements.

GlblcntUsage

Global usage count on the module.

ProccntUsage

Module usage count in the context of the owning process.

modBaseAddr

Base address of the module in the context of the owning process.

modBaseSize

Size, in bytes, of the module.

hModule

Handle of the module in the context of the owning process.

szModule

String containing the module name.

szExePath

String containing the location (path) of the module.

Note  modBaseAddr and hModule are valid only in the context of the process specified by th32ProcessID.


PARAMBLOCK

Contains information about locked drives.

PARAMBLOCK struc
    Operation db ?
    NumLocks  db ?
PARAMBLOCK ends

Members

Operation

Operation to carry out provided by the calling application of Lock/Unlock Removable Media (Interrupt 21h Function 440Dh Minor Code 48h). This member can be one of these values:

0	Locks the volume in the drive.
1	Unlocks the volume in the drive.
2	Returns the lock or unlock status.
All other values are reserved.

NumLocks

Number of locks pending on the given drive filled in by Lock/Unlock Removable Media.


PROCESSENTRY32

Describes an entry from a list that enumerates the processes residing in the system address space when a snapshot was taken.

typedef struct tagPROCESSENTRY32 {

    DWORD dwSize;

    DWORD cntUsage;

    DWORD th32ProcessID;

    DWORD th32DefaultHeapID;

    DWORD th32ModuleID;

    DWORD cntThreads;

    DWORD th32ParentProcessID;

    LONG  pcPriClassBase;

    DWORD dwFlags;

    char szExeFile[MAX_PATH];

} PROCESSENTRY32;

typedef PROCESSENTRY32 *  PPROCESSENTRY32;

typedef PROCESSENTRY32 *  LPPROCESSENTRY32;

Members

dwSize

Specifies the length, in bytes, of the structure. Before calling the Process32First function, set this member to

sizeof(PROCESSENTRY32).

cntUsage

Number of references to the process. A process exists as long as its usage count is nonzero. As soon as its usage count becomes zero, a process terminates.

th32ProcessID

Identifier of the process. The contents of this member can be used by Win32 API elements.

th32DefaultHeapID

Identifier of the default heap for the process. The contents of this member has meaning only to the tool help functions. It is not a handle, nor is it usable by Win32 API elements.

th32ModuleID

Module identifier of the process. The contents of this member has meaning only to the tool help functions. It is not a handle, nor is it usable by Win32 API elements.

cntThreads

Number of execution threads started by the process.

th32ParentProcessID

Identifier of the process that created the process being examined. The contents of this member can be used by Win32 API elements.

pcPriClassBase

Base priority of any threads created by this process.

dwFlags

Reserved; do not use.

szExeFile

Path and filename of the executable file for the process.


THREADENTRY32

Describes an entry from a list that enumerates the threads executing in the system when a snapshot was taken.

typedef struct tagTHREADENTRY32{

    DWORD  dwSize;

    DWORD  cntUsage;

    DWORD  th32ThreadID;

    DWORD  th32OwnerProcessID;

    LONG   tpBasePri;

    LONG   tpDeltaPri;

    DWORD  dwFlags;

} THREADENTRY32;

typedef THREADENTRY32 *  PTHREADENTRY32;

typedef THREADENTRY32 *  LPTHREADENTRY32;

Members

dwSize

Specifies the length, in bytes, of the structure. Before calling the Thread32First function, set this member to

sizeof(THREADENTRY32).

cntUsage

Number of references to the thread. A thread exists as long as its usage count is nonzero. As soon as its usage count becomes zero, a thread terminates.

th32ThreadID

Identifier of the thread. This identifier is compatible with the thread identifier returned by the CreateProcess function.

th32OwnerProcessID

Identifier of the process that created the thread. The contents of this member can be used by Win32 API elements.

tpBasePri

Initial priority level assigned to a thread. These values are defined:

THREAD_PRIORITY_IDLE

Indicates a base priority level of 1 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 16 for REALTIME_PRIORITY_CLASS processes.

THREAD_PRIORITY_LOWEST

Indicates 2 points below normal priority for the priority class.

THREAD_PRIORITY_BELOW_NORMAL

Indicates 1 point below normal priority for the priority class.

THREAD_PRIORITY_NORMAL

Indicates normal priority for the priority class.

THREAD_PRIORITY_ABOVE_NORMAL

Indicates 1 point above normal priority for the priority class.

THREAD_PRIORITY_HIGHEST

Indicates 2 points above normal priority for the priority class.

THREAD_PRIORITY_TIME_CRITICAL

Indicates a base priority level of 15 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 31 for REALTIME_PRIORITY_CLASS processes.

tpDeltaPri

Change in the priority level of a thread. This value is a signed delta from the base priority level assigned to the thread.

dwFlags

Reserved; do not use.


Int 21h Function 440Dh Minor Code 40h (FAT32)

mov  bx, Drive           ;See below

mov  ch, DeviceCat       ;See below

mov  cl, 40h             ;Set device parameters

mov  dx, seg DriveDP     ;See below

mov  ds, dx

mov  dx, offset DriveDP  ;ds:dx points to a device parameters structure

mov  ax, 440Dh           ;IOCTL for block device

int  21h

jc  error_handler       ;carry set means error

Sets the device parameters for the specified block device.

•	If the function is successful, clears the carry flag. Otherwise, sets the carry flag and sets the AX register to one of the following error values.

Value 	Name

0001h 	ERROR_INVALID_FUNCTION

0002h 	ERROR_FILE_NOT_FOUND

0005h 	ERROR_ACCESS_DENIED

Drive

Specifies the drive that parameters are being set for (0 = default drive, 1 = A, 2 = B, and so on).

DeviceCat

Specifies the expected format of the device parameters information structure.

Value 	Expected device parameters structure

08h 	DEVICEPARAMS (FAT16 or FAT12 drive. Will fail on FAT32 drives.)

48h 	EA_DEVICEPARAMETERS (FAT32) (FAT32, FAT16 or FAT12 drives). This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

DriveDP

Points to the applicable device parameters structure that contains the parameters for the specified block device. The format of the expected device parameters is indicated in the above DeviceCat field.

Set Device Parameters returns 0002h (ERROR_FILE_NOT_FOUND) if the specified drive number is invalid.

If the number of sectors specified in the applicable device parameters structure is not zero, a TRACKLAYOUT structure specifying the size of each sector must follow the device parameters structure.

In the case of a FAT16 or FAT12 drive, the device parameters structure is a DEVICEPARAMS structure. For FAT32 drives, the device parameters structure is an EA_DEVICEPARAMETERS (FAT32) structure.


Int 21h Function 440Dh Minor Code 41h (FAT32)

mov     bx, Drive               ;See below

mov     ch, DeviceCat           ;See below

mov     cl, 41h                 ;Write Track on Logical Drive

mov     dx, seg WriteBlock      ;See below

mov     ds, dx

mov     dx, offset WriteBlock   ;ds:dx points to RWBLOCK structure

mov     ax, 440Dh               ;IOCTL for block device

int     21h

jc      error_handler           ;carry set means error

Writes data from a buffer to a track on the specified device.

•	If the function is successful, clears the carry flag. Otherwise, sets the carry flag and sets the AX register to one of the following error values.

Value 	Name

0001h 	ERROR_INVALID_FUNCTION

0002h 	ERROR_FILE_NOT_FOUND

0005h 	ERROR_ACCESS_DENIED

Drive

Specifies the drive information is to be written to (0 = default drive, 1 = A, 2 = B, and so on).

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

Value	Description

08h 	FAT16 or FAT12 drive. (Will fail on FAT32 drives.)

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

WriteBlock

Points to an RWBLOCK structure that contains information specifying the sectors to be written to. The rwBuffer field must contain the address of the buffer that contains the data to write to the disk. The RWBLOCK structure has the following form:

RWBLOCK STRUC

    rwSpecFunc      db  0  ;special functions (must be zero)

    rwHead          dw  ?  ;head to read/write

    rwCylinder      dw  ?  ;cylinder to read/write

    rwFirstSector   dw  ?  ;first sector to read/write

    rwSectors       dw  ?  ;number of sectors to read/write

    rwBuffer        dd  ?  ;address of buffer for read/write data

RWBLOCK ENDS

Write Track on Logical Drive returns 0002h (ERROR_FILE_NOT_FOUND) if the specified drive number is invalid.


Int 21h Function 440Dh Minor Code 42h (FAT32)

mov     bx, Drive                 ;See below

mov     ch, DeviceCat             ;See below

mov     cl, 42h                   ;Format track on logical drive

mov     dx, seg FormatBlock       ;See below

mov     ds, dx

mov     dx, offset FormatBlock    ;ds:dx points to FVBLOCK structure

mov     ax, 440Dh                 ;IOCTL for block device

int     21h

jc      error_handler             ;carry set means error

Formats and verifies a track on the specified device.

•	If the fvSpecFunc field in the FVBLOCK structure is 1, clears the carry flag and sets the fvSpecFunc field to one of the following values.

Value 	Meaning

0 	ROM support for given format combination

1 	No ROM support

2 	Illegal format combination

3 	No media present

If the fvSpecFunc field is 0 and the function is successful, clears the carry flag. Otherwise, sets the carry flag and sets the AX register to one of the following error values.

Value 	Name

0001h 	ERROR_INVALID_FUNCTION

0002h 	ERROR_FILE_NOT_FOUND

0005h 	ERROR_ACCESS_DENIED

Format Track on Logical Drive returns 0002h (ERROR_FILE_NOT_FOUND) if the specified drive number is invalid.

Drive

Specifies the drive on which the track is to be formatted and verified (0 = default drive, 1 = A, 2 = B, and so on).

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

Value	Description

08h 	FAT16 or FAT12 drive. (Will fail on FAT32 drives.)

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

FormatBlock

Points to an FVBLOCK structure that specifies the head and cylinder to format. The FVBLOCK structure has the following form:

FVBLOCK STRUC

    fvSpecFunc    db  0   ;special functions

    fvHead        dw  ?   ;head to format/verify

    fvCylinder    dw  ?   ;cylinder to format/verify

    fvTracks      dw  ?   ;tracks to format/verify

FVBLOCK ENDS

The fvSpecFunc field can be 0, 1, or 2. The fvTracks field is ignored.


Int 21h Function 440Dh Minor Code 46h (FAT32)

mov     bx, Drive               ;See below

mov     ch, DeviceCat           ;See below

mov     cl, 46h                 ;Set Media ID

mov     dx, seg MediaID         ;See below

mov     ds, dx

mov     dx, offset MediaID      ;ds:dx points to MID structure

mov     ax, 440Dh               ;IOCTL for block device

int     21h

jc      error_handler           ;carry set means error

Sets sets the volume label, serial number, and file system for the specified drive.

•	If the function is successful, clears the carry flag. Otherwise, sets the carry flag and sets the AX register to one of the following error values.

Value 	Name

0001h 	ERROR_INVALID_FUNCTION

0002h 	ERROR_FILE_NOT_FOUND

0005h 	ERROR_ACCESS_DENIED

Drive

Specifies the drive for which identification is to be set (0 = default drive, 1 = A, 2 = B, and so on).

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

Value	Description

08h 	FAT16 or FAT12 drive. (Will fail on FAT32 drives.)

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

MediaID

Points to a MID structure that contains information that uniquely identifies a disk or other storage medium. The MID structure has the following form:

MID STRUC

    midInfoLevel   dw  0           ;information level

    midSerialNum   dd  ?           ;serial number

    midVolLabel    db  11 dup (?)  ;ASCII volume label

    midFileSysType db  8 dup (?)   ;file system type

MID ENDS

Set Media ID returns 0002h (ERROR_FILE_NOT_FOUND) if the specified drive number is invalid.


Int 21h Function 440Dh Minor Code 47h (FAT32)

mov     bx, Drive               ;See below

mov     ch, DeviceCat           ;See below

mov     cl, 47h                 ;Set access flag

mov     dx, seg SpecialFunc     ;See below

mov     ds, dx

mov     dx, offset SpecialFunc  ;ds:dx points to SPECIALFUNC structure

mov     ax, 440Dh               ;IOCTL for block device

int     21h

jc      error_handler           ;carry set means error

Sets the access flag for the specified drive.

•	If the function is successful, clears the carry flag. Otherwise sets the carry flag, and sets the AX register to one of the following error values.

Value 	Name

0001h 	ERROR_INVALID_FUNCTION

0002h 	ERROR_FILE_NOT_FOUND

0005h 	ERROR_ACCESS_DENIED

Drive

Specifies the drive for which the access flag is to be set (0 = default drive, 1 = A, 2 = B, and so on).

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

Value	Description

08h 	FAT16 or FAT12 drive. (Will fail on FAT32 drives.)

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

SpecialFunc

Points to a SPECIALFUNC structure that contains information specifying the state of the access flag. The SPECIALFUNC structure has the following form:

SPECIALFUNC STRUC

    sfFunction  db  0   ;special function (must be 0)

    sfAccessFlg db  ?   ;access flag, 0 if access blocked

                        ;"unformatted"

SPECIALFUNC ENDS

Set Access Flag returns 0002h (ERROR_FILE_NOT_FOUND) if the specified drive number is invalid.


Int 21h Function 440Dh Minor Code 48h (FAT32)

mov ax, 440Dh           ; Generic IOCTL

mov bx, DriveNum        ; See below

mov ch, DeviceCat       ; See below

mov cl, 48h             ; Lock or unlock removable media

mov dx, seg ParamBlock  ; See below

mov ds, dx

mov dx, offset ParamBlock

int 21h

jc  error_handler       ; Carry set means error

Locks or unlocks the volume in the given drive (preventing or permitting its removal) or returns the locked status of the given drive.

•	If the function is successful, clears the carry flag and copies the number of pending locks on the given drive to the NumLocks member of the PARAMBLOCK structure. Otherwise, sets the carry flag and sets the AX register to one of the following error values.

Value	Description
01h	The function is not supported.
B0h	The volume is not locked in the drive.
B2h	The volume is not removable.
B4h	The lock count has been exceeded.
DriveNum

Drive to lock or unlock (0 = default drive, 1 = A, 2 = B, and so on).

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

Value	Description

08h 	FAT32, FAT16, or FAT12 drive.

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

ParamBlock

Address of a PARAMBLOCK structure that specifies the operation to carry out and receives a count of the number of locks on the drive.


Int 21h Function 440Dh Minor Code 49h (FAT32)

mov ax, 440Dh      ; Generic IOCTL

mov bx, DriveNum   ; See below

mov ch, DeviceCat  ; See below

mov cl,            ; Eject Removable Media

int 21h

jc  error_handler  ; Carry set means error

Ejects the specified media.

•	If the function is successful, clears the carry flag. Otherwise, sets the carry flag and sets the AX register to one of the following error values.

01h	The function is not supported.
B1h	The volume is locked in the drive.
B2h	The volume is not removable.
B5h	The valid eject request has failed.
DriveNum

Drive to eject (0 = default drive, 1 = A, 2 = B, and so on).

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

Value	Description

08h 	FAT16 or FAT12 drive

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

If a given physical drive has more than one logical volume, all volumes must be unlocked by using Int 21h Function 440Dh Minor Code 48h (FAT32) before the drive will eject.


Int 21h Function 440Dh Minor Code 4Ah (FAT32)

mov ax, 440Dh        ; generic IOCTL

mov bh, LockLevel    ; see below

mov bl, DriveNum     ; see below

mov ch, DeviceCat    ; see below

mov cl, 4Ah          ; Lock Logical Volume

mov dx, Permissions  ; see below

int 21h

jc error_handler

Locks the logical volume.

•	Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

LockLevel

Level of the lock. This parameter must be either 0, 1, 2, or 3.

DriveNum

Drive to lock. This parameter can be 0 for the default drive, 1 for A, 2 for B, and so on.

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

Value	Description

08h 	FAT32, FAT16, or FAT12 drive.

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

Permissions

Operations that the system permits while the volume is locked. This parameter is specified only when a level 1 lock is obtained or when a level 0 lock is obtained for the second time for formatting the volume. For other lock levels, this parameter is zero. When a level 1 lock is obtained, bits 0 and 1 of this parameter specify whether the system permits write operations, new file mappings, or both by other processes during a level 1 lock as well as during level 2 and 3 locks. If this parameter specifies that write operations, new file mappings, or both are failed, these operations are failed during level 1, 2, and 3 locks. This parameter has the following form:

Bit 	Meaning

0 	0 = Write operations are failed (specified when a level 1 lock is obtained).

0 	1 = Write operations are allowed (specified when a level 1 lock is obtained).

1 	0 = New file mapping are allowed (specified when a level 1 lock is obtained).

1 	1 = New file mapping are failed (specified when a level 1 lock is obtained).

2	1 = The volume is locked for formatting (specified when a level 0 lock is obtained for the second time).

The volume must be locked before the application performs direct disk write operations by using Interrupt 26h or the IOCTL control functions. Lock Physical Volume (Interrupt 21h Function 440Dh Minor Code 4Bh (FAT32)) is used instead of this function before a call to an Interrupt 13h function. You must use Unlock Logical Volume (Interrupt 21h Function 440Dh Minor Code 6Ah (FAT32)) to release the lock.


Int 21h Function 440Dh Minor Code 4Bh (FAT32)

mov ax, 440Dh        ; generic IOCTL

mov bh, LockLevel    ; see below

mov bl, DriveNum     ; see below

mov ch, DeviceCat    ; see below

mov cl, 4Bh          ; Lock Physical Volume

mov dx, Permissions  ; see below

int 21h

jc error_handler

Locks the physical volume.

•	Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

LockLevel

Level of the lock. This parameter must be either 0, 1, 2, or 3.

DriveNum

Drive to lock. This parameter must be one of the following values (same device unit numbers as for Interrupt 13h):

00 - 7Fh 	Floppy disk drive (00 for the first floppy drive, 01 for the second, and so on).

80 - FFh 	Hard disk drive (80 for the first hard disk drive, 81 for the second, and so on).

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

Value	Description

08h 	FAT32, FAT16, or FAT12 drive.

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

Permissions

Operations that the system permits while the volume is locked. This parameter is specified only when a level 1 lock is obtained or when a level 0 lock is obtained for the second time for formatting the volume. For other lock levels, this parameter is zero. When a level 1 lock is obtained, bits 0 and 1 of this parameter specify whether the system permits write operations, new file mappings, or both by other processes during a level 1 lock as well as during level 2 and 3 locks. If this parameter specifies that write operations, new file mappings, or both are failed, these operations are failed during level 1, 2, and 3 locks. This parameter has the following form:

Bit 	Meaning

0 	0 = Write operations are failed (specified when a level 1 lock is obtained).

0 	1 = Write operations are allowed (specified when a level 1 lock is obtained).

1 	0 = New file mapping are allowed (specified when a level 1 lock is obtained).

1 	1 = New file mapping are failed (specified when a level 1 lock is obtained).

2	1 = The volume is locked for formatting (specified when a level 0 lock is obtained for the second time).

The volume must be locked before the application performs direct disk write operations by using Interrupt 13h, Interrupt 26h, or the Interrupt 21h IOCTL functions. A single physical volume may be divided into more than one logical volume, which is also called a partition. The system automatically takes a logical volume lock on all logical volumes on the specified physical drive. If the application performs disk writes only to a logical drive, Lock Logical Volume (Interrupt 21h Function 440Dh Minor Code 4Ah (FAT32)) is used instead of this function. Unlock Physical Volume (Interrupt 21h Function 440Dh Minor Code 6Bh (FAT32)) should be called to release the lock.


Int 21h Function 440Dh Minor Code 60h (FAT32)

mov  bx, Drive           ;See below

mov  ch, DeviceCat       ;See below

mov  cl, 60h             ;Get device parameters

mov  dx, seg DriveDP     ;See below

mov  ds, dx

mov  dx, offset DriveDP  ;ds:dx points to a device parameters structure

mov  ax, 440Dh           ;IOCTL for block device

int  21h

jc   error_handler       ;carry set means error

Returns the device parameters for the specified block device.

•	If the function is successful, clears the carry flag. Otherwise, sets the carry flag and sets the AX register to one of the following error values.

Value 	Name

0001h 	ERROR_INVALID_FUNCTION

0002h 	ERROR_FILE_NOT_FOUND

0005h 	ERROR_ACCESS_DENIED

Drive

Specifies the drive for which parameters are requested (0 = default drive, 1 = A, 2 = B, and so on).

DeviceCat

Specifies the expected format of device parameters information structure.

Value	Expected Device Parameters Structure
08h	DEVICEPARAMS (FAT16 or FAT12 drive. This call will work on FAT32 drives, but results are not reliable. Use the 48h form for FAT32 media).
48h	EA_DEVICEPARAMETERS (FAT32) (FAT32, FAT16 or FAT12) This value is supported on Windows 95 OEM Service Release 2 and later.
Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

DriveDP

Points to the applicable device parameters structure containing the parameters for the specified block device. The format of the expected device parameters is indicated in the DeviceCat field above.

The special functions field in the device parameters structure determines whether the function retrieves current or default information. If the field is set to 1, the function retrieves information about the current medium in the drive. If the field is set to 0, the function retrieves information about the default medium for the drive.

Get Device Parameters returns 0002h (ERROR_FILE_NOT_FOUND) if the specified drive number is invalid.


Int 21h Function 440Dh Minor Code 61h (FAT32)

mov     bx, Drive               ;See below

mov     ch, DeviceCat           ;See below

mov     cl, 61h                 ;Read track on logical drive

mov     dx, seg ReadBlock       ;See below

mov     ds, dx

mov     dx, offset ReadBlock    ;ds:dx points to RWBLOCK structure

mov     ax, 440Dh               ;IOCTL for block device

int     21h

jc      error_handler           ;carry set means error

Reads data from a track on the specified device and places the data in memory.

•	If the function is successful, clears the carry flag. Otherwise, sets the carry flag and sets the AX register to one of the following error values.

Value 	Name

0001h 	ERROR_INVALID_FUNCTION

0002h 	ERROR_FILE_NOT_FOUND

0005h 	ERROR_ACCESS_DENIED

Drive

Specifies the drive to be read from (0 = default drive, 1 = A, 2 = B, and so on).

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

Value	Description

08h 	FAT16 or FAT12 drive. (Will fail on a FAT32 drive).

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

ReadBlock

Points to an RWBLOCK structure that contains information specifying the sectors to be read from. The RWBLOCK structure has the following form:

RWBLOCK STRUC

    rwSpecFunc      db  0  ;special functions (must be zero)

    rwHead          dw  ?  ;head to read/write

    rwCylinder      dw  ?  ;cylinder to read/write

    rwFirstSector   dw  ?  ;first sector to read/write

    rwSectors       dw  ?  ;number of sectors to read/write

    rwBuffer        dd  ?  ;address of buffer for read/write data

RWBLOCK ENDS

Read Track on Logical Drive returns 0002h (ERROR_FILE_NOT_FOUND) if the specified drive number is invalid.


Int 21h Function 440Dh Minor Code 62h (FAT32)

mov     bx, Drive                 ;See below

mov     ch, DeviceCat             ;See below

mov     cl, 62h                   ;Verify track on logical drive

mov     dx, seg VerifyBlock       ;See below

mov     ds, dx

mov     dx, offset VerifyBlock    ;ds:dx points to FVBLOCK structure

mov     ax, 440Dh                 ;IOCTL for block device

int     21h

jc      error_handler             ;carry set means error

Verifies a track on the specified device.

•	If the function is successful, clears the carry flag. Otherwise, sets the carry flag and sets the AX register to one of the following error values.

Value 	Name

0001h 	ERROR_INVALID_FUNCTION

0002h 	ERROR_FILE_NOT_FOUND

0005h 	ERROR_ACCESS_DENIED

Drive

Specifies the drive on which the track is to be verified (0 = default drive, 1 = A, 2 = B, and so on).

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

Value	Description

08h 	FAT16 or FAT12 drive (Will fail on a FAT32 drive.)

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

VerifyBlock

Points to an FVBLOCK structure that specifies the head and cylinder to verify. The FVBLOCK structure has the following form:

FVBLOCK STRUC

    fvSpecFunc    db  0   ;special functions

    fvHead        dw  ?   ;head to format/verify

    fvCylinder    dw  ?   ;cylinder to format/verify

    fvTracks      dw  ?   ;tracks to format/verify

FVBLOCK ENDS

The fvSpecFunc field can be 0 or 2.

Verify Track on Logical Drive returns 0002h (ERROR_FILE_NOT_FOUND) if the specified drive number is invalid.


Int 21h Function 440Dh Minor Code 66h (FAT32)

mov     bx, Drive            ;See below

mov     ch, DeviceCat        ;See below

mov     cl, 66h              ;Get Media ID

mov     dx, seg MediaID      ;See below

mov     ds, dx

mov     dx, offset MediaID   ;ds:dx points to MID structure

mov     ax, 440Dh            ;IOCTL for block device

int     21h

jc      error_handler        ;carry set means error

Returns the volume label, serial number and file system for the specified drive.

•	If the function is successful, clears the carry flag, and fills in the parameter block (an MID structure) with information about the disk. Otherwise, sets the carry flag and sets the AX register to one of the following error values.

Value 	Name

0001h 	ERROR_INVALID_FUNCTION

0002h 	ERROR_FILE_NOT_FOUND

0005h 	ERROR_ACCESS_DENIED

Drive

Specifies the drive for which information is to be returned (0 = default drive, 1 = A, 2 = B, and so on).

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

Value	Description

08h 	FAT32, FAT16, or FAT12 drive.

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

MediaID

Points to an MID structure that receives information that uniquely identifies a disk or other storage medium. The MID structure has the following form:

MID STRUC

    midInfoLevel   dw  0           ;information level

    midSerialNum   dd  ?           ;serial number

    midVolLabel    db  11 dup (?)  ;ASCII volume label

    midFileSysType db  8 dup (?)   ;file system type

MID ENDS

Get Media ID returns 0002h (ERROR_FILE_NOT_FOUND) if the specified drive number is invalid.


Int 21h Function 440Dh Minor Code 67h (FAT32)

mov     bx, Drive               ;See below

mov     ch, DeviceCat           ;See below

mov     cl, 67h                 ;Get access flag

mov     dx, seg SpecialFunc     ;See below

mov     ds, dx

mov     dx, offset SpecialFunc  ;ds:dx points to SPECIALFUNC structure

mov     ax, 440Dh               ;IOCTL for block device

int     21h

jc      error_handler           ;carry set means error

Retrieves the access flag for the specified drive.

•	If the function is successful, clears the carry flag. Otherwise, sets the carry flag and sets the AX register to one of the following error values.

Value 	Name

0001h 	ERROR_INVALID_FUNCTION

0002h 	ERROR_FILE_NOT_FOUND

0005h 	ERROR_ACCESS_DENIED

Drive

Specifies the drive for which the access flag is to be retrieved (0 = default drive, 1 = A, 2 = B, and so on).

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

08h 	FAT32, FAT16, or FAT12 drive.

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

SpecialFunc

Points to a SPECIALFUNC structure that receives the state of the access flag. The SPECIALFUNC structure has the following form:

SPECIALFUNC STRUC

    sfFunction  db  0   ;special function (must be 0)

    sfAccessFlg db  ?   ;access flag, 0 if access blocked

                        ;"unformatted"

SPECIALFUNC ENDS

Get Access Flag returns 0002h (ERROR_FILE_NOT_FOUND) if the specified drive number is invalid.


Int 21h Function 440Dh Minor Code 68h (FAT32)

mov     bx, Drive               ;See below

mov     ch, DeviceCat           ;See below

mov     cl, 68h                 ;Sense media type

mov     dx, seg Media           ;See below

mov     ds, dx

mov     dx, offset Media        ;ds:dx points to buffer for media type

mov     ax, 440Dh               ;IOCTL for block device

int     21h

jc      error_handler           ;carry set means error

Returns the media type for the specified block device.

•	If the function is successful, clears the carry flag. Otherwise, sets the carry flag and sets the AX register to one of the following error values.

Value 	Name

0001h 	ERROR_INVALID_FUNCTION

0005h 	ERROR_ACCESS_DENIED

Drive

Specifies the drive for which parameters are requested (0 = default drive, 1 = A, 2 = B, and so on).

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

08h 	FAT32, FAT16, or FAT12 drive.

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

Media

Points to a 2-byte buffer that receives information about the media type for the given drive. The buffer has the following form:

Offset	Description
00h	Receives a value specifying whether the media type is the default value. This byte is set to 01h for the default media type and to 00h for any other media type.
01h	Receives a value specifying the media type. This byte is set to 02h for 720K disks, 07h for 1.44-MB disks, and 09h for 2.88-MB disks.
Sense Media Type may also return a device-dependent error value as specified by the device driver.

Sense Media Type returns 0005h (ERROR_ACCESS_DENIED) if the media type for the specified drive cannot be determined or if the given drive is not ready. Programs can use Get Extended Error (Function 59h) to retrieve additional information about the error.


Int 21h Function 440Dh Minor Code 6Ah (FAT32)

mov ax, 440Dh      ; generic IOCTL

mov bl, DriveNum   ; see below

mov ch, DeviceCat  ; see below

mov cl, 6Ah        ; Unlock Logical Volume

int 21h

jc error_handler

Unlocks the logical volume or decrements the lock level.

•	Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

DriveNum

Drive to unlock. This parameter can be 0 for the default drive, 1 for A, 2 for B, and so on.

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

08h 	FAT32, FAT16, or FAT12 drive.

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

Use this function to release the lock obtained by using Lock Logical Volume (Interrupt 21h Function 440Dh Minor Code 4Ah (FAT32)). Only the lock owner can release the lock on a volume.

To release the lock on the volume, an application must call Unlock Logical Volume the same number of times that Lock Logical Volume was called.


Int 21h Function 440Dh Minor Code 6Bh (FAT32)

mov ax, 440Dh      ; generic IOCTL

mov bl, DriveNum   ; see below

mov ch, DeviceCat  ; see below

mov cl, 6Bh        ; Unlock Physical Volume

int 21h

jc error_handler

Unlocks the physical volume or decrements the lock level.

•	Clears the carry flag if successful. Otherwise, the function sets the carry flag and sets the AX register to an error value.

DriveNum

Drive to unlock. This parameter must be one of these values (same device unit numbers as for Interrupt 13h):

00 - 7Fh 	Floppy disk drive (00 for the first floppy drive, 01 for the second, and so on).

80 - FFh 	Hard disk drive (80 for the first hard disk drive, 81 for the second, and so on).

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

08h 	FAT32, FAT16, or FAT12 drive.

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

This function is used to release the lock obtained by using Lock Physical Volume (Interrupt 21h Function 440Dh Minor Code 4Bh (FAT32)). Only the lock owner can release the lock on a volume.

To release the lock on the volume, an application must call Unlock Physical Volume the same number of times that Lock Physical Volume was called.


Int 21h Function 440Dh Minor Code 6Ch (FAT32)

mov ax, 440Dh        ; generic IOCTL

mov bl, DriveNum     ; see below

mov ch, DeviceCat    ; see below

mov cl, 6Ch          ; Get Lock Flag State

int 21h

jc error_handler

mov [AccessFlag], ax  ; state of access flag

Polls the state of the access flag on a volume to determine if a write operation (for example, deleting or renaming a file or writing to a file) or a new file mapping has occurred since the last poll.

•	Clears the carry flag and sets the AX register to one of the following values if successful:

0 	No write operations or file mappings have occurred since the last poll.

1 	A write operation has occurred since the last poll (clears the volume access flag).

2 	A file mapping has occurred since the last poll, or a 32-bit Windows-based DLL or executable has been opened (clears the volume access flag).

Otherwise, the function sets the carry flag and sets the AX register to an error value.

DriveNum

Drive to poll. This parameter can be 0 for the default drive, 1 for A, 2 for B, and so on.

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

08h 	FAT32, FAT16, or FAT12 drive.

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

Only the current lock owner may poll the access flag. The system fails other processes with ERROR_ACCESS_DENIED error value. Write operations performed by the lock owner do not cause a change in the state of the access flag.

When a lock is obtained that allows write operations or new file mappings, the system sets a flag whenever one of these operations happens on the volume. If a write operation or new file mapping has occurred since the last poll, Get Lock Flag State returns 1 or 2 respectively in the AX register and clears the volume access flag. If the swap file has grown or shrunk since the last poll, Get Lock Flag State returns 1. Note that write operations to the swap file that do not cause a change in size do not cause a change in the state of the access flag. If a 32-bit Windows-based DLL or executable has been opened since the last poll, Get Lock Flag State returns 2.


Int 21h Function 440Dh Minor Code 6Dh (FAT32)

mov ax, 440Dh           ; generic IOCTL

mov bx, DriveNum        ; see below

mov ch, DeviceCat       ; see below

mov cl, 6Dh             ; Enumerate Open Files

mov dx, seg PathBuf     ; see below

mov ds, dx

mov dx, offset PathBuf

mov si, FileIndex       ; see below

mov di, EnumType        ; see below

int 21h

jc  error

mov [OpenMode], ax      ; mode file was opened in

mov [FileType], cx      ; normal file or memory-mapped file

Enumerates open files on the specified drive.

•	Clears the carry flag, copies the path of an open file to the given buffer, and sets the AX and CX registers to the following values if successful:

AX 	Mode that the file was opened in, which is a combination of access mode, sharing mode, and open flags. It can be one value each from the access and sharing modes and any combination of open flags.

Access modes

OPEN_ACCESS_READONLY (0000h)

OPEN_ACCESS_WRITEONLY (0001h)

OPEN_ACCESS_READWRITE (0002h)

OPEN_ACCESS_RO_NOMODLASTACCESS (0004h)

Share modes

OPEN_SHARE_COMPATIBLE (0000h)

OPEN_SHARE_DENYREADWRITE (0010h)

OPEN_SHARE_DENYWRITE (0020h)

OPEN_SHARE_DENYREAD (0030h)

OPEN_SHARE_DENYNONE (0040h)

Open flags

OPEN_FLAGS_NOINHERIT (0080h)

OPEN_FLAGS_NO_BUFFERING (0100h)

OPEN_FLAGS_NO_COMPRESS (0200h)

OPEN_FLAGS_ALIAS_HINT (0400h)

OPEN_FLAGS_NOCRITERR (2000h)

OPEN_FLAGS_COMMIT (4000h)

CX 	File type. It can be one of the following values:

0 	For normal files

1 	For a memory-mapped files (memory-mapped files are unmovable)

2 	For any other unmovable files (32-bit Windows-based DLLs and executables)

4 	For the swap file

Note that if a memory-mapped file is returned (CX = 1), the value returned in the AX register is limited to the following values:

OPEN_ACCESS_READONLY (0000h)

OPEN_ACCESS_READWRITE (0002h)

Otherwise, the function sets the carry flag and sets the AX register to the following error value:

ERROR_ACCESS_DENIED 	The value of FileIndex exceeds the number of open files on the drive.

DriveNum

Drive on which to enumerate the files. This parameter can be 0 for the default drive, 1 for A, 2 for B, and so on.

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

08h 	FAT32, FAT16, or FAT12 drive.

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

PathBuf

Address of a buffer that receives the path of the open file. The length of the buffer varies depending on the volume. Get Volume Information (Interrupt 21h Function 71A0h) is used to determine the maximum allowed length of a path for the volume.

FileIndex

Index of the file to retrieve the path for.

EnumType

Kind of file to enumerate. This parameter can be 0 to enumerate all open files or 1 to enumerate only open unmovable files, including open memory-mapped files and other open unmovable files (32-bit Windows-based DLLs and executables).

This function returns information about one file at a time. To enumerate all open files, the function must be called repeatedly with FileIndex set to a new value for each call. FileIndex should be set to zero initially and then incremented by one for each subsequent call. The function returns the ERROR_NO_MORE_FILES error value when all open files on the volume have been enumerated.

This function may return inconsistent results when used to enumerate files on an active volume 3/4 that is, on a volume where other processes may be opening and closing files. Applications should use Lock Logical Volume (Interrupt 21h Function 440Dh Minor Code 4Ah) to take a level 3 lock before enumerating open files.


Int 21h Function 440Dh Minor Code 6Eh (FAT32)

mov ax, 440Dh       ; generic IOCTL

mov ch, DeviceCat       ; see below

mov cl, 6Eh             ; Find Swap File

mov dx, seg PathBuf     ; see below

mov ds, dx

mov dx, offset PathBuf

int 21h

jc  error_handler

mov [PagerType], ax            ; pager type

mov WORD PTR [FileSize], bx    ; swap file size in 4K pages

mov WORD PTR [FileSize+2], cx

Retrieves information about the swap file.

•	Clears the carry flag, copies the swap file path to the given buffer, and sets the following registers if successful:

AX 	Pager type. It can be 1 for no pager, 2 for paging through MS-DOS, and 3 for paging through the protected-mode input and output (I/O) supervisor.

CX:BX 	Current size of the swap file in 4K pages.

Otherwise, this function sets the carry flag and sets the AX register to an error value.

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

08h 	FAT32, FAT16, or FAT12 drive.

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

PathBuf

Address of the buffer that receives the path of the swap file. To determine the maximum allowed length of a path for the volume, call Get Volume Information (Interrupt 21h Function 71A0h).


Int 21h Function 440Dh Minor Code 6Fh (FAT32)

mov ax, 440Dh             ; Generic IOCTL

mov bx, DriveNum          ; See below

mov ch, DeviceCat         ; See below

mov cl, 6Fh               ; Get drive map info

mov dx, seg DriveMapInfo  ; See below

mov ds, dx

mov dx, offset DriveMapInfo

int 21h

jc  error_handler         ; Carry set means error

Retrieves information about the specified drive. This call only works under Windows 95. It will fail if called from exclusive MS-DOS mode.

DriveNum

Drive to obtain information about (0 = default drive, 1 = A, 2 = B, and so on).

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

08h 	FAT32, FAT16, or FAT12 drive.

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

DriveMapInfo

Address of the DRIVE_MAP_INFO structure that receives information about the specified drive. The DRIVE_MAP_INFO structure has the following form:

DRIVE_MAP_INFO    struc

    dmiAllocationLength   db ?

    dmiInfoLength         db ?

    dmiFlags              db ?

    dmiInt13Unit          db ?

    dmiAssociatedDriveMap dd ?

    dmiPartitionStartRBA  dq ?

DRIVE_MAP_INFO    ends


Int 21h Function 440Dh Minor Code 70h (FAT32)

mov ax, 440Dh        ; generic IOCTL

mov bl, DriveNum     ; see below

mov ch, DeviceCat    ; see below

mov cl, 70h          ; Get Current Lock State

int 21h

jc error_handler

Retrieves the current lock level and permissions on the specified drive.

•	Clears the carry flag and sets the AX and CX registers to these values if successful:

AX 	Current lock level. It may be either 0, 1, 2 or 3. If the volume is not locked, AX contains - 1

CX 	Lock permissions. The bits have the following form:

Bit 	Meaning

0 	0 = Write operations are failed.

0 	1 = Write operations are allowed, unless they are blocked by the lock level.

1 	0 = New file mapping are allowed, unless they are blocked by the lock level.

1 	1 = New file mapping are failed.

2 	1 = The volume is locked for formatting.

DriveNum

Drive to retrieve lock information about. This parameter can be 0 for the default drive, 1 for A, 2 for B, and so on.

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

08h 	FAT32, FAT16, or FAT12 drive.

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

The lock level and the permissions determine the kind of access processes other than the lock owner have to the volume while it is locked. The following operations are allowed by processes other than lock owner at each lock level:

Level 	Operations

0 	Read operations, write operations, and new file mappings are failed.

1 	Read operations are allowed. Write operations and new file mappings are either allowed or failed based on permissions.

2 	Read operations are allowed. Write operations and new file mappings are either failed or blocked based on permissions.

3 	Read operations are blocked. Write operations and new file mappings are either failed or blocked based on permissions.


Int 21h Function 440Dh Minor Code 71h (FAT32)

mov ax, 440Dh            ; Generic IOCTL

mov bx, CharSet          ; See below

mov ch, DeviceCat        ; See below

mov cl, 71h              ; Get first cluster

mov dx, seg PathName     ; See below

mov ds, dx

mov dx, offset PathName

int 21h

jc error_handler         ; Carry set means error

Retrieves the first cluster of the specified file or directory. This function is only supported by Windows 95. It will fail if called under MS-DOS. To call this function, the caller must hold a level 3 lock on the drive.

•	If the function is successful, clears the carry flag and sets DX:AX to the first cluster number. Otherwise, sets the carry flag and returns either the ERROR_INVALID_FUNCTION or ERROR_ACCESS_DENIED value in AX.

CharSet

The character set of PathName. This parameter must be one of these values:

BCS_WANSI (0) 	Windows ANSI character set

BCS_OEM (1) 	Current OEM character set

BCS_UNICODE (2) 	Unicode character set

DeviceCat

Specifies a FAT16, FAT12 or FAT32 drive.

08h 	FAT32, FAT16, or FAT12 drive.

48h 	FAT32, FAT16, or FAT12 drive. This value is supported on Windows 95 OEM Service Release 2 and later.

Note: Because this call may be implemented in the device driver, the 48h form of this call may fail on FAT16 or FAT12 media. Therefore, applications making the 48h form of this call must fall back on the 08h form if the 48h call fails.

PathName

Address of a null-terminated string containing the path of the file or directory to retrieve the first cluster for.

The first cluster of a file is the first cluster of the FAT cluster chain describing the data associated with the file. The first cluster of a directory is the first cluster of the FAT cluster chain associated with the directory. The first cluster is the cluster that contains the "." and ".." entries. The Get First Cluster function finds any file or directory regardless of attribute (system, hidden, or read-only). It does not find volume labels.

It is the calling application's responsibility to check to see if the returned cluster number is valid. The following code fragment checks for a valid cluster number and sets a flag accordingly. Note that the maxClus variable is a DWORD that represents the maximum legal cluster number computed from the drive parameters.

if((MAKELONG(regAX,regDX) < 2L) || (MAKELONG(regAX,regDX) > maxClus))

    bInvalidNum = TRUE;

else

    bInvalidNum = FALSE;


Int 21h Function 6Ch (FAT32)

mov ah, 6Ch             ; Extended Open/Create

mov bx, ModeAndFlags    ; See below

mov cx, Attributes      ; See below

mov dx, Action          ; See below

mov si, seg Filename    ; See below

mov ds, si

mov si, offset Filename

int 21h

jc error_handler        ; Carry set means error

mov [Handle], ax        ; file handle

mov [ActionTaken], cx   ; action taken to open file

Opens or creates a file that has the given name and attributes.

•	If the function is successful, clears the carry flag, copies the file handle to the AX register, and sets CX to one of the following values.

ACTION_OPENED (0001h)

ACTION_CREATED_OPENED (0002h)

ACTION_REPLACED_OPENED (0003h)

Otherwise, sets the carry flag and sets the AX register to one of the following error values.

ERROR_INVALID_FUNCTION (0001h)

ERROR_FILE_NOT_FOUND (0002h)

ERROR_PATH_NOT_FOUND (0003h)

ERROR_TOO_MANY_OPEN_FILES (0004h)

ERROR_ACCESS_DENIED (0005h)

ModeAndFlags

A combination of access mode, sharing mode, and open flags. This parameter can be a combination of one value from the access and sharing modes and any combination of open flags:

Access mode	Meaning

OPEN_ACCESS_READONLY (0000h)

Opens the file for reading only.

OPEN_ACCESS_WRITEONLY (0001h)

Opens the file for writing only.

OPEN_ACCESS_READWRITE (0002h)

Opens the file for reading and writing.

0003h

Reserved; do not use.

OPEN_ACCESS_RO_NOMODLASTACCESS (0004h)

Opens the file for reading only without modifying the file's last access date.

Sharing mode	Meaning

OPEN_SHARE_COMPATIBLE (0000h)

Opens the file in compatibility mode, allowing any process on a given computer to open the file any number of times.

OPEN_SHARE_DENYREADWRITE (0010h)

Opens the file and denies both read and write access to other processes.

OPEN_SHARE_DENYWRITE (0020h)

Opens the file and denies write access to other processes.

OPEN_SHARE_DENYREAD (0030h)

Opens the file and denies read access to other processes.

OPEN_SHARE_DENYNONE (0040h)

Opens the file without denying read or write access to other processes, but no process may open the file in compatibility mode.

Open flags 	Meaning

OPEN_FLAGS_NOINHERIT (0080h)

Child processes created with Load and Execute Program (Interrupt 21h Function 4B00h) do not inherit the file handle. If the handle is needed by a child process, the parent process must pass the handle value to the child process. If this flag is not set, child processes inherit the file handle.

EXTENDED_SIZE (1000h)

The file is opened in extended mode. This allows access to files up to 4GB minus 2 bytes. Access includes open and create functions.

OPEN_FLAGS_NOCRITERR (2000h)

If a critical error occurs while MS-DOS is opening this file, Critical-Error Handler (Interrupt 24h) is not called. Instead, MS-DOS simply returns an error value to the program.

OPEN_FLAGS_COMMIT (4000h)

After each write operation, MS-DOS commits the file (flushes the contents of the cache buffer to disk).

Attributes

Attributes for files that are created or truncated. This parameter may be a combination of these values:

FILE_ATTRIBUTE_NORMAL (0000h)

The file can be read from or written to. This value is valid only if used alone.

FILE_ATTRIBUTE_READONLY (0001h)

The file can be read from, but not written to.

FILE_ATTRIBUTE_HIDDEN (0002h)

The file is hidden and does not appear in an ordinary directory listing.

FILE_ATTRIBUTE_SYSTEM (0004h)

The file is part of the operating system or is used exclusively by it.

FILE_ATTRIBUTE_VOLUME (0008h)

The name specified by Filename is used as the volume label for the current medium.

FILE_ATTRIBUTE_ARCHIVE (0020h)

The file is an archive file. Applications use this value to mark files for backup or removal.

Action

Action to take it the file exists or does not exist. This parameter can be a limited combination of the following values:

FILE_CREATE (0010h)

Creates a new file if it does not already exist or fails if the file already exists.

FILE_OPEN (0001h)

Opens the file. The function fails if the file does not exist.

FILE_TRUNCATE (0002h)

Opens the file and truncates it to zero length (replaces the existing file). The function fails if the file does not exist.

Note that valid combinations of the above values are limited to FILE_CREATE combined with FILE_OPEN or FILE_CREATE combined with FILE_TRUNCATE.

Filename

Address of a null-terminated string specifying the name of the file to be opened or created. The name must be in the standard MS-DOS 8.3 filename format. The string must be a valid path for the volume associated with the given drive.

This function does not support long filenames. If the specified name is too long, this function truncates the name to the standard 8.3 format following the same naming scheme that the system uses when creating an alias for a long filename.

A file on a remote directory-that is, a directory on the network-cannot be opened, unless appropriate permissions for the directory exist.


Int 21h Function 7302h Get_ExtDPB (FAT32)

Buffer   dw  ?

DriveDPB DPB <>

BufferSize equ sizeof DPB + sizeof WORD

...

mov  dx, seg Buffer

mov  es, dx

mov  di, offset Buffer  ;See below

mov  dl, DriveNum       ;See below

mov  cx, BufferSize     ;See below

mov  ax, 7302h          ;Get_ExtDPB

int  21h

jc  error_handler       ;carry set means error

Returns a copy of the extended DPB (FAT32) for any valid drive.

•	Clears the carry flag, and returns a copy of the DPB to ES:DI. The copy is a WORD equal to the size (in bytes) of the extended DPB, followed by the extended DPB itself (see EA_DEVICEPARAMETERS (FAT32)).

Buffer

The address of the buffer at ES:DI that will receive the WORD (the size value), followed by the copy of the extended DPB.

DriveNum

The 1-based drive number (0=default; 1=A, 2=B, and so on).

BufferSize

The size of the buffer, in bytes.

The size value returned by this function represents the size of the DPB only. It does not include the two bytes of the size field itself.

This call will not work when the VDEF file system is mounted on the drive (for example during formatting).

When calling this function with DeviceIoControl, it is recommended to set the dwloControlCode parameter to VWIN32_DIOC_DOS_IOCTL (defined as 6 in VWIN32.H). For more information on this, see Using VWIN32 to Carry Out MS-DOS Functions.


Int 21h Function 7303h Get_ExtFreeSpace (FAT32)

mov  dx, seg Buffer

mov  es, dx

mov  di, offset Buffer    ;See below

mov  es:[di].ExtGetDskFreSpcStruc.ExtFree_Level, ExpectLevel

mov  cx, BufferSize       ;See below

mov  dx, seg DriveName    ;See below

mov  ds, dx

mov  dx, offset DriveName ;See below

mov  ax, 7303h            ;Get_ExtFreeSpace

int  21h

jc  error_handler         ;carry set means error

Returns the total disk space and the free disk space.

•	Clears the carry flag and returns the total disk space and the free disk space of the specified drive, in the form of an ExtGetDskFreSpcStruc (FAT32) structure, to a buffer at ES:DI. It is recommended to initialize the buffer to the level value the application expects to receive.

Buffer

The address of the buffer at ES:DI that will receive the disk space information.

BufferSize

The size (in bytes) of the buffer.

DriveName

The address of a null terminated string at DS:DX. In real mode, this must be in standard form ("C:\"). In Windows, either the standard name or a universal naming convention form ("\\Server\Share") is acceptable.

When calling this function with DeviceIoControl, the dwloControlCode parameter must be set to VWIN32_DIOC_DOS_IOCTL (defined as 6 in VWIN32.H). For more information on this, see Using VWIN32 to Carry Out MS-DOS Functions.


Int 21h Function 7304h Set_DPBForFormat (FAT32)

mov  dx, seg Buffer

mov  es, dx

mov  di, offset Buffer   ;See below

mov  es:[di].SDPDFormatStruc.SetDPB_Level, ExpectLevel   ;See below

mov  ax, word ptr Value1 ; initialize SDPDFormatStruc values.

                         ; See specific sub-function for details.

mov  word ptr es:[di].SDPDFormatStruc.SetDPB_Value1, ax

mov  ax, word ptr Value1 + 2

mov  word ptr es:[di].SDPDFormatStruc.SetDPB_Value1+2, ax

mov  ax, word ptr SubFunction

mov  word ptr es:[di].SDPDFormatStruc.SetDPB_Function, ax

mov  word ptr es:[di].SDPDFormatStruc.SetDPB_Function+2, 0

mov  dl, DriveNum       ;See below

mov  cx, BufferSize     ;See below

mov  ax, 7304h          ;Set_DPBForFormat

int 21h

Implements a sub-function to perform DPB operations.

There are five sub-functions that can be implemented. The buffer at ES:DI must contain a SDPDFormatStruc (FAT32) structure. The value in the DWORD field, SetDPB_Function, determines which sub-function is called.

Buffer

The address of a buffer containing a SDPDFormatStruc structure at ES:DI.

ExpectLevel

The expected return level value. This should be 0.

DriveNum

The 1-based drive number (0=default; 1=A, 2=B, and so on).

BufferSize

The size of the buffer, in bytes.

Selecting a Sub-Function:

The value in the SetDPB_Function field of the SDPDFormatStruc structure determines which sub-function is implemented.

0	SetDPB_SetAllocInfo
1	SetDPB_SetDPBFrmBPB
2	SetDPB_ForceMediaChng
3	SetDPB_GetSetActFATandMirr
4	SetDPB_GetSetRootDirClus
It is important to be aware of the state of the file system when using this call. If sectors of the drive are cached, or if there are files open, the function may produce unexpected results. To avoid this, ensure that the application closes all files and calls DiskReset to flush and invalidate any caches.

The SDPDFormatStruc also contains four ULONG fields: SetDPB_Value1, SetDPB_Value2, SetDPB_Value3, and SetDPB_Value4. Set these appropriately according to the requirements for each of the sub-functions.

When calling this function with DeviceIoControl, set the dwloControlCode parameter to VWIN32_DIOC_DOS_IOCTL (defined as 6 in VWIN32.H). For more information on this, see Using VWIN32 to Carry Out MS-DOS Functions.


SetDPB_SetAllocInfo (FAT32)

Sets the dpb_free_cnt and dpb_next_free fields in the DPB.

This sub-function is called when the SetDPB_Function field of the SDPDFormatStruc (FAT32) structure is set to 0.

•	Clears the carry flag and sets the dpb_free_cnt and dpb_next_free fields in the DPB based upon the values in the SetDPB_Value1 and SetDPB_Value2 fields within the Set_DPB_ForFormat structure.

SetDPB_Value1 Setting 	Result within DPB

0 	Does not change the dpb_free_cnt field.

0xFFFFFFFF 	Sets dpb_free_cnt to unknown.

(any other value) 	Sets dpb_free_cnt to the specified value if it is a valid cluster count for the drive,.

The free cluster count cannot be explicitly set to zero by this call. This can only be done by setting SetDPB_Value1 to 0xFFFFFFFF, which forces the free space to be re-computed. Also, setting this value improperly causes the free count value to be reported improperly by GetDiskFreeSpace. The settings of 0 or 0xFFFFFFFF are recommended.

SetDPB_Value2 Setting	Result within DPB

0	Does not change the dpb_next_free field.

0xFFFFFFFF	Sets dpb_next_free to force the cluster search to begin at the beginning of the FAT.

(any other value)	Sets dpb_next_free to the given value if it is a valid cluster number for the drive. This causes the search for free clusters to begin at the specified cluster.

The assembler calling sequence for all Int 21h 7304h sub-functions is almost identical. See the main listing for a sample. (Int 21h Function 7304h Set_DPBForFormat (FAT32))


SetDPB_SetDPBFrmBPB (FAT32)

Rebuilds the file system drive DPB from a passed-in BPB (FAT32).

This sub-function is called when the SetDPB_Function field of the SDPDFormatStruc (FAT32) structure is set to 1.

On input, the SetDPB_Value2 member in SDPDFormatStruc must be a DWORD pointer to the BPB.

The PB that the SetDPB_Value2 points to can be in FAT12, FAT16 or FAT32 format.

The drive parameters are often held in the device driver for the drive as well. As a result, it is recommended to accompany this call with a call to Int 21h Function 440Dh Minor Code 40h (FAT32).

The assembler calling sequence for all Int 21h 7304h sub-functions is almost identical. See the main listing for a sample. (Int 21h Function 7304h Set_DPBForFormat (FAT32))


SetDPB_ForceMediaChng (FAT32)

Forces a media change.

This sub-function is called when the SetDPB_Function field of the SDPDFormatStruc (FAT32) structure is set to 2.

•	Sets a flag which causes the next MS-DOS access to the drive to call the BUILD_DPD routine in the drive's device driver.

This is similar to the SetDPB_SetDPBFrmBPB (FAT32) call, except that the BPB is obtained from the device driver instead of a passed-in parameter.

The function does not take effect on this call. Rather, it takes effect upon the next access to the drive. Therefore, it is recommended to immediately follow this with some other Int 21h call to the drive (for example Int 21h Function 7303h Get_ExtFreeSpace (FAT32)).

As a side effect of this call, the next access to the drive also causes dpb_next_free (or extdpb_next_free) to be reset to 2, and the dpb_free_cnt to be reset to 0xFFFFFFFF.

The assembler calling sequence for all Int 21h 7304h sub-functions is almost identical. See the main listing for a sample. (Int 21h Function 7304h Set_DPBForFormat (FAT32))


SetDPB_GetSetActFATandMirr (FAT32)

Allows the active FAT and FAT mirror properties of a FAT32 drive to be read and changed. This call is invalid on FAT12 and FAT16 drives.

This sub-function is called when the SetDPB_Function field of the SDPDFormatStruc (FAT32) structure is set to 3.

•	If the function is unsuccessful, the function sets the carry flag and returns ERROR_GEN_FAILURE (error code 31) to AX. Receiving ERROR_GEN_FAILURE as the return value indicates that a disk error occurred during the attempt to write. In this case, the DPB mirror property is changed, but not properly written to disk. If the function fails, it is recommended that the caller re-write the value returned to SetDBP_Value2 to attempt to undo the change.

SetDPB_Value1

The SetDPB_Value1 field in the SPDPFormatStruc structure determines the SET behavior. If the SetDPB_Value1 field is set to 0xFFFFFFFF, then no changes are made and the ActiveFat and FAT mirror property are returned to SetDPB_Value2.

Failure Conditions:

The low four bits of this value are the zero-based ActiveFAT number. If the ActiveFAT number is greater than or equal to the number of FATs on the drive, the call will fail.

Bit 0x00000080 is the "Disable FAT Mirror" bit. If any bits other than 0x80 and the low four bits are set, the call will fail.

If the FAT Mirror is enabled (bit 0x80 clear) and the ActiveFAT value specified in SetDPB_Value1 is not zero, the call will fail.

SetDPB_Value2

Used as a return field for the previous ActiveFAT and FAT mirror properties. Bits 0 through 3 indicate the active FAT number, bit 7 indicates the mirror state, and all other bits are reserved. If SetDPB_Value1 is 0xFFFFFFFF, the previous state is also the current state.

Bit 7	Description
Set	Enable FAT Mirroring
Clear	Disable FAT Mirroring
Side Effects of Set Form:

The BPB(s) and boot sector(s) of the drive are also written. This is because the ActiveFAT and FAT mirror properties are also stored in the BPB.

If the FAT Mirror is being enabled (that is, bit 0x80 is set in the current state, and bit 0x80 is clear in SetDPB_Value1.) this call will copy the active FAT sectors to all of the other FATs. This process can be very slow.

Note that the device driver may also contain these values as part of its current device parameters. This call will have no effect on the FAT Mirror properties held by the device driver. As a result, it is recommended to immediately follow the set form of the call with a SetDeviceParameters Generic IOCTL call to set the current BPB that the BuildBPB routine of the device returns.

Next Free DPB variable is reset to 2, and the Free Count DPB is reset to 0xFFFFFFFF.

The assembler calling sequence for all Int 21h 7304h sub-functions is almost identical. See the main listing for a sample. (Int 21h Function 7304h Set_DPBForFormat (FAT32))


SetDPB_GetSetRootDirClus (FAT32)

Allows the first cluster of the root directory of a FAT32 drive to be read and changed. This call is invalid on FAT12 and FAT16 drives.

This sub-function is called when the SetDPB_Function field of the SDPDFormatStruc (FAT32) structure is set to 4.

•	If the function is unsuccessful, the function sets the carry flag and returns ERROR_GEN_FAILURE (error code 31) to AX. Receiving ERROR_GEN_FAILURE as the return value indicates that a disk error occurred during the attempt to write. In this case, the DPB mirror property is changed, but not properly written to disk. If the function fails, it is recommended that the caller re-write the value returned to SetDBP_Value2 to attempt to undo the change.

SetDPB_Value1

This field in the SPDPFormatStruc specifies the SET behavior. If the value is 0xFFFFFFFF, then no changes are made and the current root directory first cluster number is returned in SetDPB_Value2.

The value is range checked. It must be >=2 and <= the maximum valid cluster number for the drive.

SetDPB_Value2

This field in the SPDPFormatStruc is used as a return field where the previous root directory first cluster is held. When SetDPB_Value1 is 0xFFFFFFFF, the previous cluster is also the current root directory cluster.

Since the start cluster of the root directory is also stored in the BPB of the boot sector(s) of the drive, this call re-writes these boot sectors as a side effect.

Note that the device driver may also contain these values as part of its current device parameters. This call will have no effect on the FAT Mirror properties held by the device driver. Because of this, it is recommended to immediately follow the set form of the call with a SetDeviceParameters Generic IOCTL call. This sets the current BPB that the BuildBPB routine of the device returns.

The assembler calling sequence for all Int 21h 7304h sub-functions is almost identical. See the main listing for a sample. (Int 21h Function 7304h Set_DPBForFormat (FAT32))


Int 21h Function 7305h Ext_ABSDiskReadWrite (FAT32)

mov  si, 6001h          ;write normal file data. SI=0 for read

                        ;see "In Write Mode" below for more write values

mov  cx, -1             ;cx must be -1

mov  dx, seg Buffer

mov  ds, dx

mov  bx, offset Buffer  ;See below

mov  dl, DriveNum       ;See below

mov  ax, 7305h          ;Ext_ABSDiskReadWrite

int 21h

jc  error_handler       ;carry set means error

Allows absolute disk read/write to FAT32, FAT16, and FAT12 drives. This call replaces Int 25h/26h.

•	If the function is successful, clears the carry flag. Otherwise, sets the carry flag, and sets the AX register with the error code as it is documented for Int 25h/26h.

Buffer

Points to a DISKIO structure that contains the starting sector, the sector count and an address of the buffer to receive the data. The structure must be initialized according to Int 25h/26h documentation. The DISKIO structure has the following form:

DISKIO  STRUC

    diStartSector   dd  ?   ;sector number to start

    diSectors       dw  ?   ;number of sectors

    diBuffer        dd  ?   ;address of buffer

DISKIO  ENDS

DriveNum

The 1-based drive number (0=default; 1=A, 2=B, and so on).

This function operates the same as Int 25h/26h, with the following exceptions:

CX must equal -1 (only the 32-bit starting sector number form is allowed).

The drive number is 1-based (0 = default drive) and is specified in DL instead of AL.

This call does not leave a flag word on the stack like Interrupts 25h and 26h.

This call modifies only the AX register and the flags.

Bit 0 of SI specifies whether the call is to do a READ (INT 0x25) or a WRITE (INT 0x26):

Read and Write Modes:

SI bit 0 clear	READ
SI bit 0 set	WRITE
In Write Mode:

When bit 0 of SI is set (that is, WRITE mode), bits 13, 14 and 15 of SI categorize what type of data is being written:

15	14	13	Description
0	0	0	Other/Unknown.
0	0	1	FAT data.
0	1	0	Directory data.
0	1	1	Normal File data.
1	x	x	Reserved. Bit 15 must be 0.
All other bits of SI (1 through 12) are reserved and must be 0.

This provides information to apps (like compression drivers) so that they can write the data properly based upon the data type specified by the above bits.

Warnings:

Do not set these flags in an attempt to make a compression driver write uncompressed data onto a compressed drive. Compression drivers are not the only applications use these flags.

Do not set the flags improperly, this information is to be used only to indicate what "type" the data is.

When calling this function with DeviceIoControl, it is recommended to set the dwloControlCode parameter to VWIN32_DIOC_DOS_IOCTL (defined as 6 in VWIN32.H). For more information on this, see Using VWIN32 to Carry Out MS-DOS Functions.


Superseded Functions

The following functions have been superseded for Windows OEM Service Release 2 and later:

Interrupt 21h Function 1Fh Get Default DPB:

Superseded by Int 21h Function 7302h Get_ExtDPB (FAT32). Will fail if used on FAT32 media.

Interrupt 21h Function 32h Get DPB:

Superseded by Int 21h Function 7302h Get_ExtDPB (FAT32). Will fail if used on FAT32 media.

Interrupt 21h Function36h Get Disk Free Space:

If total or free disk space is greater than 2GB minus 320k, then 2GB minus 320k is returned. This function is superseded by Int 21h Function 7303h Get_ExtFreeSpace (FAT32).

Interrupts 25h/26h Absolute Disk Read / Write:

Superseded by Int 21h Function 7305h Ext_ABSDiskReadWrite (FAT32). These functions fail on FAT32 drives. This is to prevent non-FAT32 compatible software from being able to access FAT32 media.


BPB (FAT32)

The BPB for FAT32 drives is an extended version of the FAT16/FAT12 BPB. It contains identical information to a standard BPB, but also includes several extra fields for FAT32 specific information.

This structure is implemented in Windows OEM Service Release 2 and later.

A_BF_BPB    STRUC

    A_BF_BPB_BytesPerSector       DW    ?

    A_BF_BPB_SectorsPerCluster    DB    ?

    A_BF_BPB_ReservedSectors      DW    ?

    A_BF_BPB_NumberOfFATs         DB    ?

    A_BF_BPB_RootEntries          DW    ?

    A_BF_BPB_TotalSectors         DW    ?

    A_BF_BPB_MediaDescriptor      DB    ?

    A_BF_BPB_SectorsPerFAT        DW    ?

    A_BF_BPB_SectorsPerTrack      DW    ?

    A_BF_BPB_Heads                DW    ?

    A_BF_BPB_HiddenSectors        DW    ?

    A_BF_BPB_HiddenSectorsHigh    DW    ?

    A_BF_BPB_BigTotalSectors      DW    ?

    A_BF_BPB_BigTotalSectorsHigh  DW    ?

    A_BF_BPB_BigSectorsPerFat     DW    ?

    A_BF_BPB_BigSectorsPerFatHi   DW    ?

    A_BF_BPB_ExtFlags             DW    ?

    A_BF_BPB_FS_Version           DW    ?

    A_BF_BPB_RootDirStrtClus      DW    ?

    A_BF_BPB_RootDirStrtClusHi    DW    ?

    A_BF_BPB_FSInfoSec            DW    ?

    A_BF_BPB_BkUpBootSec          DW    ?

    A_BF_BPB_Reserved             DW    6 DUP (?)

A_BF_BPB    ENDS

A_BF_BPB_BytesPerSector

The number of bytes per sector.

A_BF_BPB_SectorsPerCluster

The number of sectors per cluster.

A_BF_BPB_ReservedSectors

The number of reserved sectors, beginning with sector 0.

A_BF_BPB_NumberOfFATs

The number of File Allocation Tables.

A_BF_BPB_RootEntries

This field is ignored on FAT32 drives.

A_BF_BPB_TotalSectors

The size of the partition, in sectors.

A_BF_BPB_MediaDescriptor

The media descriptor. Values in this field are identical to standard BPB.

A_BF_BPB_SectorsPerFAT

The number of sectors per FAT.

Note: This field will always be zero in a FAT32 BPB. Use the values from A_BF_BPB_BigSectorsPerFat and A_BF_BPB_BigSectorsPerFatHi for FAT32 media.

A_BF_BPB_SectorsPerTrack

The number of sectors per track.

A_BF_BPB_Heads

The number of read/write heads on the drive.

A_BF_BPB_HiddenSectors

The number of hidden sectors on the drive.

A_BF_BPB_HiddenSectorsHigh

The high word of the hidden sectors value.

A_BF_BPB_BigTotalSectors

The total number of sectors on the FAT32 drive.

A_BF_BPB_BigTotalSectorsHigh

The high word of the FAT32 total sectors value.

A_BF_BPB_BigSectorsPerFat

The number of sectors per FAT on the FAT32 drive.

A_BF_BPB_BigSectorsPerFatHi

The high word of the FAT32 sectors per FAT value.

A_BF_BPBExtFlags

Flags describing the drive. Bit 8 of this field indicates whether or not information written to the active FAT will be written to all copies of the FAT. The low 4 bits of this field contain the 0-based FAT number of the Active FAT, but are only meaningful if bit 8 is set. This field can contain a combination of the following values.

Value	Description
BGBPB_F_ActiveFATMsk (000Fh)	Mask for low four bits.
BGBPB_F_NoFATMirror (0080h)	Mask indicating FAT mirroring state. If set, FAT mirroring is disabled. If clear, FAT mirroring is enabled.
Bits 4-6 and 8-15 are reserved.

A_BF_BPB_FS_Version

The file system version number of the FAT32 drive. The high byte represents the major version, and the low byte represents the minor version.

A_BF_BPB_RootDirStrtClus

The cluster number of the first cluster in the FAT32 drive's root directory.

A_BF_BPB_RootDirStrtClusHi

The high word of the FAT32 starting cluster number.

A_BF_BPB_FSInfoSec

The sector number of the file system information sector. The file system info sector contains a BIGFATBOOTFSINFO structure. This field is set to 0FFFFh if there is no FSINFO sector. Otherwise, this value must be non-zero and less than the reserved sector count.

A_BF_BPB_BkUpBootSec

The sector number of the backup boot sector. This field is set to 0FFFFh if there is no backup boot sector. Otherwise, this value must be non-zero and less than the reserved sector count.

A_BF_BPB_Reserved

Reserved field. Do not use.


BIGFATBOOTFSINFO (FAT32)

Contains information about the file system on a FAT32 volume. This structure is implemented in Windows OEM Service Release 2 and later.

BIGFATBOOTFSINFO STRUC

    bfFSInf_Sig               DD    ?

    bfFSInf_free_clus_cnt     DD    ?

    bfFSInf_next_free_clus    DD    ?

    bfFSInf_resvd             DD    3 DUP (?)

BIGFATBOOTFSINFO ENDS

bfFSInf_Sig

The signature of the file system information sector. The value in this field is FSINFOSIG (0x61417272L).

bfFSInf_free_clus_cnt

The count of free clusters on the drive. Set to -1 when the count is unknown.

bfFSInf_next_free_clus

The cluster number of the cluster that was most recently allocated.

bfFSInf_resvd

Reserved field. Do not use.


DPB (FAT32)

The DPB was extended to include FAT32 information. Changes are effective for Windows 95 OEM Service Release 2 and later.

DPB STRUC

    dpb_drive            DB    ?

    dpb_unit             DB    ?

    dpb_sector_size      DW    ?

    dpb_cluster_mask     DB    ?

    dpb_cluster_shift    DB    ?

    dpb_first_fat        DW    ?

    dpb_fat_count        DB    ?

    dpb_root_entries     DW    ?

    dpb_first_sector     DW    ?

    dpb_max_cluster      DW    ?

    dpb_fat_size         DW    ?

    dpb_dir_sector       DW    ?

    dpb_reserved2        DD    ?

    dpb_media            DB    ?

ifdef NOTFAT32

    dpb_first_access     DB    ?

else

    dpb_reserved         DB    ?

endif

    dpb_reserved3        DD    ?

    dpb_next_free        DW    ?

    dpb_free_cnt         DW    ?

ifndef NOTFAT32

    extdpb_free_cnt_hi   DW    ?

    extdpb_flags         DW    ?

    extdpb_FSInfoSec     DW    ?

    extdpb_BkUpBootSec   DW    ?

    extdpb_first_sector  DD    ?

    extdpb_max_cluster   DD    ?

    extdpb_fat_size      DD    ?

    extdpb_root_clus     DD    ?

    extdpb_next_free     DD    ?

endif

DPB ENDS

dpb_drive

The drive number (0 = A, 1 = B, and so on).

dpb_unit

Specifies the unit number. The device driver uses the unit number to distinguish the specified drive from the other drives it supports.

dpb_sector_size

The size of each sector, in bytes.

dpb_cluster_mask

The number of sectors per cluster minus 1.

dpb_cluster_shift

The number of sectors per cluster, expressed as a power of 2.

dpb_first_fat

The sector number of the first sector containing the file allocation table (FAT).

dpb_fat_count

The number of FATs on the drive.

dpb_root_entries

The number of entries in the root directory.

dpb_first_sector

The sector number of the first sector in the first cluster.

dpb_max_cluster

The number of clusters on the drive plus 1. This field is undefined for FAT32 drives.

dpb_fat_size

The number of sectors occupied by each FAT. The value of zero indicates a FAT32 drive. Use the value in extdpb_fat_size instead.

dpb_dir_sector

The sector number of the first sector containing the root directory. This field is undefined for FAT32 drives.

dpb_reserved2

Reserved field. Do not use.

dpb_media

Specifies the media descriptor for the medium in the specified drive.

reserved

Reserved field. Do not use.

dpb_first_access

Indicates whether the medium in the drive has been accessed. This field is initialized to -1 to force a media check the first time this DPB is used.

dpb_reserved3

Reserved field. Do not use.

dpb_next_free

The cluster number of the most recently allocated cluster.

dpb_free_cnt

The number of free clusters on the medium. This field is 0FFFFh if the number is unknown.

extdpb_free_cnt_hi

The high word of free count.

extdpb_flags

Flags describing the drive. The low 4 bits of this field contain the 0-based FAT number of the Active FAT. This field can contain a combination of the following values.

Value	Description
BGBPB_F_ActiveFATMsk (000Fh)	Mask for low four bits.
BGBPB_F_NoFATMirror (0080h)	Do not Mirror active FAT to inactive FATs.
Bits 4-6 and 8-15 are reserved.

extdpb_FSInfoSec

The sector number of the file system information sector. This field is set to 0FFFFh if there is no FSINFO sector. Otherwise, this value must be non-zero and less than the reserved sector count.

extdpb_BkUpBootSec

The sector number of the backup boot sector. This field is set to 0FFFFh if there is no backup boot sector. Otherwise, this value must be non-zero and less than the reserved sector count.

extdpb_first_sector

The first sector of the first cluster.

extdpb_max_cluster

The number of clusters on the drive plus 1.

extdpb_fat_size

The number of sectors occupied by the FAT.

extdpb_root_clus

The cluster number of the first cluster in the root directory.

extdpb_next_free

The number of the cluster that was most recently allocated.


EA_DEVICEPARAMETERS (FAT32)

The equivalent of the DEVICEPARAMS structure, but includes FAT32 specific information. This structure is implemented in Windows OEM Service Release 2 and later.

EA_DEVICEPARAMETERS STRUC

    EDP_SPECIALFUNCTIONS     DB     ?

    EDP_DEVICETYPE           DB     ?

    EDP_DEVICEATTRIBUTES     DW     ?

    EDP_CYLINDERS            DW     ?

    EDP_MEDIATYPE            DB     ?

    EDP_BPB                  DB     SIZE A_BF_BPB DUP (?)

    EDP_RESERVED1            DB     32 DUP (?)

    EDP_TRACKTABLEENTRIES    DW     ?

    EDP_SECTORTABLE          DB MAX_SECTORS_IN_TRACK * SIZE A_SECTORTABLE DUP (?)

EA_DEVICEPARAMETERS ENDS

This structure is identical to DEVICEPARAMS, but includes a FAT32 BPB instead of a standard BPB, followed by a 32 byte reserved field.


ExtGetDskFreSpcStruc (FAT32)

A structure used by Int 21h Function 7303h Get_ExtFreeSpace (FAT32). The structure contains information about the drive's total disk space and free disk space.

This structure is implemented in Windows OEM Service Release 2 and later.

ExtGetDskFreSpcStruc STRUC

    ExtFree_Size                      DW    ?

    ExtFree_Level                     DW    ?

    ExtFree_SectorsPerCluster         DD    ?

    ExtFree_BytesPerSector            DD    ?

    ExtFree_AvailableClusters         DD    ?

    ExtFree_TotalClusters             DD    ?

    ExtFree_AvailablePhysSectors      DD    ?

    ExtFree_TotalPhysSectors          DD    ?

    ExtFree_AvailableAllocationUnits  DD    ?

    ExtFree_TotalAllocationUnits      DD    ?

    ExtFree_Rsvd                      DD    2 DUP (?)

ExtGetDskFreSpcStruc ENDS

ExtFree_Size

A return value that represents the size of the ExtGetDskFreSpcStruc structure, in bytes. The Get_ExtFreeSpace sub-function returns the size value to this field. This member is used only as a return value.

ExtFree_Level

An input and return level value. This must be initialized to zero.

ExtFree_SectorsPerCluster

The number of sectors per cluster.

ExtFree_BytesPerSector

The number of bytes per sector.

ExtFree_AvailClusters

The number of available clusters.

ExtFree_TotalClusters

The total number of clusters on the drive.

ExtFree_AvailablePhysSectors

The number of physical sectors available on the drive, without adjustment for compression.

ExtFree_TotalPhysSectors

The total number of physical sectors on the drive, without adjustment for compression.

ExtFree_AvailableAllocationUnits

The number of available allocation units on the drive, without adjustment for compression.

ExtFree_TotalAllocationUnits

The total number of allocation units on the drive, without adjustment for compression.

ExtFree_Rsvd

Reserved field.


s_partition (FAT32)

s_partition    STRUC

    Part_BootInd        DB    ?

    Part_FirstHead      DB    ?

    Part_FirstSector    DB    ?

    Part_FirstTrack     DB    ?

    Part_FileSystem     DB    ?

    Part_LastHead       DB    ?

    Part_LastSector     DB    ?

    Part_LastTrack      DB    ?

    Part_StartSector    DD    ?

    Part_NumSectors     DD    ?

s_partition    ENDS

Note: Values for head and track are 0-based. Sector values are 1-based. This structure is implemented in Windows OEM Service Release 2 and later.

Part_BootInd

Specifies whether the partition is bootable or not. This value could be set to PART_BOOTABLE (80h), or PART_NON_BOOTABLE(00h). The first partition designated as PART_BOOTABLE is the boot partition. All others are not. Setting multiple partitions to PART_BOOTABLE will result in boot errors.

Part_FirstHead

The first head of this partition. This is a 0-based number representing the offset from the beginning of the disk. The partition includes this head.

Part_FirstSector

The first sector of this partition. This is a 1-based, 6-bit number representing the offset from the beginning of the disk. The partition includes this sector. Bits 0 through 5 specify the 6-bit value; bits 6 and 7 are used with the Part_FirstTrack field.

Part_FirstTrack

The first track of this partition. This is an inclusive 0-based, 10-bit number that represents the offset from the beginning of the disk. The high 2 bits of this value are specified by bits 6 and 7 of the Part_FirstSector field.

PartFileSystem

Specifies the file system for the partition. The following are acceptable values:

Value	Description
PART_UNKNOWN(00h)	Unknown.
PART_DOS2_FAT(01h)	12-bit FAT.
PART_DOS3_FAT(04h)	16-bit FAT. Partition smaller than 32MB.
PART_EXTENDED(05h)	Extended MS-DOS Partition.
PART_DOS4_FAT(06h)	16-bit FAT. Partition larger than or equal to 32MB.
PART_DOS32(0Bh)	32-bit FAT. Partition up to 2047GB.
PART_DOS32X(0Ch)	Same as PART_DOS32(0Bh), but uses Logical Block Address Int 13h extensions.
PART_DOSX13(0Eh)	Same as PART_DOS4_FAT(06h), but uses Logical Block Address Int 13h extensions.
PART_DOSX13X(0Fh)	Same as PART_EXTENDED(05h), but uses Logical Block Address Int 13h extensions.
Part_LastHead

The last head of the partition. This is a 0-based number that represents the offset from the beginning of the disk. The partition includes the head specified by this field.

Part_LastSector

The last sector of this partition. This is a 1-based, 6-bit number representing offset from the beginning of the disk. The partition includes the sector specified by this field. Bits 0 through 5 specify the 6-bit value; bits 6 and 7 are used with the Part_LastTrack field.

Part_LastTrack

The last track of this partition. This is a 0-based, 10-bit number that represents offset from the beginning of the disk. The partition includes this track. The high 2 bits of this value are specified by bits 6 and 7 of the Part_LastSector field.

Part_StartSector

Specifies the 1-based number of the first sector on the disk. This value may not be accurate for extended partitions. Use the Part_FirstSector value for extended partitions.

Part_NumSectors

The 1-based number of sectors in the partition.


SDPDFormatStruc (FAT32)

Structure used to hold information on executing the various sub-functions of Int 21h Function 7304h Set_DPBForFormat (FAT32). This structure is implemented in Windows OEM Service Release 2 and later.

SDPDFormatStruc STRUC

    SetDPB_Size        DW    ?

    SetDPB_Level       DW    ?

    SetDPB_Function    DD    ?

    SetDPB_Value1      DD    ?

    SetDPB_Value2      DD    ?

    SetDPB_Value3      DD    ?

    SetDPB_Value4      DD    ?

SDPDFormatStruc ENDS

SetDPB_Size

A return value field for the sub-functions. This is not an input field.

SetDPB_Level

An input and return level value field. This must be set to 0.

SetDPB_Funtion

Specifies which sub-function will be implemented. The acceptable values are as follows:

0	SetDPB_SetAllocInfo
1	SetDPB_SetDPBFrmBPB
2	SetDPB_ForceMediaChng
3	SetDPB_GetSetActFATandMirr
4	SetDPB_GetSetRootDirClus
SetDPB_Value1

Input field for sub-function. See specific sub-function for details.

SetDPB_Value2

Input field for sub-function. See specific sub-function for details.

SetDPB_Value3

Input field for sub-function. See specific sub-function for details.

SetDPB_Value4

Input field for sub-function. See specific sub-function for details.


DirectX 2


Copyrights and Trademarks

Information in this document is subject to change without notice. Companies, names, and data used in examples are fictitious unless otherwise noted. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation. Microsoft may have patents or pending patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. The furnishing of this document does not give you the license to these patents, trademarks, copyrights, or other intellectual property except as expressly provided in any written license agreement from Microsoft.

©1996 Microsoft Corporation. All rights reserved.

Microsoft, ActiveMovie, Direct3D, DirectDraw, DirectInput, DirectPlay, DirectSound, DirectX, MS-DOS, Win32, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

3D Studio is a registered trademark of Autodesk, Inc.

OpenGL is a registered trademark of Silicon Graphics, Inc.


New Information


Updates and Changes

This information reflects changes made to the DirectX 2 documentation after its SDK was released. The changes are listed by chapter in the order in which the topics appear in that chapter.


DirectDraw

IDirectDraw2::EnumDisplayModes

	The DDSD_REFRESHRATE flag under the dwFlags parameter has been removed. This flag is specified in the dwFlags member of the DDSURFACEDESC structure.
IDirectDraw2::EnumDisplayModes

	The comment section has been clarified. This method enumerates the dwRefreshRate member in the DDSURFACEDESC structure; the IDirectDraw::EnumDisplayModes method does not contain this capability.
IDirectDraw::Initialize

	This method is now fully documented.
IDirectDrawSurface::GetCaps

	The lpDDSCaps parameter name was incorrectly shown as lpDDCaps in the list of parameters. In addition, the definition for lpDDSCaps now states that it is the address of a DDSCAPS structure that will be filled in with the hardware capabilities of the surface.
IDirectDrawClipper::Initialize

	This method is now fully documented.
DDSURFACEDESC

	The DDSD_LPSURFACE flag under the dwFlags member is not needed and has been removed. The lpSurface member of the structure is read-only and therefore does not require this flag for validation.


DirectSound

IDirectSound::Initialize

	This method is now fully documented.
DSBCAPS

	The DSBCAPS_GETCURRENTPOSITION2 flag has been added to this structure's dwFlags member.
DSBUFFERDESC

	The DSBCAPS_GETCURRENTPOSITION2 and DSBCAPS_STICKYFOCUS flags have been added to this structure's dwFlags member.


DirectPlay

No changes.


Direct3D

IDirect3DRMViewport::Configure

	This method is not functional in DirectX 2. Instead of using this method, your application can destroy the old viewport and create a new one at the new position and size.


DirectInput

No changes.


DirectSetup

No changes.


AutoPlay

No changes.


Introducing the DirectX 2 Software Development Kit


Using DirectX 2 in Windows

The Microsoft® DirectX™ 2 Software Development Kit (SDK) provides a finely-tuned set of application programming interfaces (APIs) that give you, as a developer, the resources needed to design high-performance, real-time applications, such as the next generation of computer games and multimedia applications.

Microsoft developed the DirectX 2 SDK for a number of reasons. The primary reason is to make performance on Windows-based platforms rival or exceed performance on MS-DOS-based platforms and game console-system platforms. Other reasons are to promote game development for Microsoft Windows®, and to assist you by providing a robust, standardized, and well-documented platform for which to write games.


Reasons for Developing DirectX Windows Applications

DirectX was developed to provide Microsoft Windows applications with high-performance, real-time access to available hardware on current computer systems. DirectX provides a consistent interface between hardware manufacturers and you, the application developer, thereby reducing the complexity of installation and configuration while utilizing the hardware to its best advantage.

One of the primary reasons for creating DirectX was to promote games development on the Windows platform. The majority of games developed for the personal computer today are MS-DOS-based. However, when developing MS-DOS-based games, you must conform to a number of hardware implementations for a variety of cards, which complicates installation. In addition, development of MS-DOS-based games can be much more complex on a personal computer than on a console system, due to the generalized processor, greater RAM size, and persistent storage of the personal computer.

A high-performance Windows-based game will:

•	Install successfully.

•	Take advantage of hardware accelerator cards designed specifically for improving performance.

•	Take advantage of Windows hardware and software standards such as Plug and Play.

•	Take advantage of the communications services built into Windows.


Providing Standards for Hardware Accelerators

The primary goals of the DirectX 2 SDK are to provide portable access to the features in use with MS-DOS® today, to not compromise MS-DOS or game console performance, and to remove the obstacles to hardware innovation on the personal computer platform.

Another important goal is to provide guidelines for hardware companies based on feedback from high-performance application developers and independent hardware vendors (IHVs). Therefore, the DirectX 2 SDK components often provide specifications for hardware accelerator features that do not yet exist. In many cases, these specifications are emulated in the software. In other cases, the capabilities of the hardware must be polled first, and the feature bypassed if it is not supported.

Some of the display hardware features coming out in the near future include:

•	Overlays. Overlays will be supported so page flipping will be enabled within a window in a graphic device interface (GDI). Page flipping is the double-buffer scheme used to display frames on the entire screen.

•	Sprite engines, used to make overlaying sprites easier.

•	Stretching with interpolation. Stretching a smaller frame to fit the entire screen can be an efficient way to conserve display RAM.

•	Alpha blending, used to mix colors at the hardware pixel level.

•	Three-dimensional (3D) accelerators with perspective-correct textures. This allows textures to be displayed on a 3D surface; for example, hallways in a castle generated by 3D software can be textured with a brick wall bitmap that maintains the correct perspective.

•	Z-buffer-aware blits for 3D graphics.

•	2 megabytes (MB) of display memory as standard. 3D games, for example, generally need at least this much display RAM.

•	A compression standard so you can put more data into display memory. This standard will be used for textures, will include transparency compression, and will be very fast when implemented in software as well as hardware.

Audio hardware features that will be released include:

•	3D audio enhancers that provide a spatial placement for different sounds. This will be particularly effective with headphones.

•	Onboard memory for audio boards.

•	Audio-video combination boards that share onboard memory.

In addition, video playback will see the benefit of hardware accelerators that will be compatible with the DirectX 2 SDK. One of the features that will be supported by future releases of the DirectX 2 SDK is hardware-accelerated decompression of YUV video.


DirectX 2 Components

The DirectX 2 SDK is composed of several interfaces that address and answer the performance issues of programming games and high-performance applications in the Windows 95 operating system:

•	The Microsoft DirectDraw™ application programming interface. This accelerates hardware and software animation techniques by providing direct access to bitmaps in off-screen display memory as well as extremely fast access to the blitting and buffer-flipping capabilities of the hardware.

•	The Microsoft DirectSound™ application programming interface. This enables hardware and software sound mixing and playback.

•	The Microsoft DirectPlay™ application programming interface. This allows easy connectivity of games over a modem link or network.

•	The Microsoft Direct3D™ application programming interface. This provides a high-level Retained-mode interface that allows applications to easily implement a complete 3D graphical system, and a low-level Immediate-mode interface that applications can use to take complete control over the rendering pipeline.

•	The Microsoft DirectInput™ application programming interface. This provides joystick input capabilities to your game that are scalable to future Windows hardware input APIs and drivers.

•	The Microsoft AutoPlay feature of the Microsoft Windows 95 operating system. This lets your CD run an installation program or the game itself immediately upon insertion of the CD.

The last two features, DirectInput and AutoPlay, exist in Microsoft Win32® application programming interface and are not unique to the DirectX 2 SDK.


DirectDraw

The biggest gain in performance in the DirectX 2 SDK comes from the DirectDraw services, a combination of four Component Object Model (COM) interfaces: IDirectDraw, IDirectDrawSurface, IDirectDrawPalette, and IDirectDrawClipper. For more information about the COM concepts required for programming applications using the DirectX 2 SDK, see The Component Object Model.

A DirectDraw object, created using the DirectDrawCreate function, represents the display adapter card. One of the object's methods, IDirectDraw::CreateSurface, creates the primary DirectDrawSurface object, which represents the display memory being viewed on the monitor. From the primary surface, off-screen surfaces can be created in a linked-list fashion.

In the most common case, one back buffer surface is created in addition to the primary surface and exchanges images with the primary surface. While the screen is busy displaying the lines of the image in the primary surface, the back buffer surface frame is being composed. This is done by transferring a series of off-screen bitmaps stored on other DirectDrawSurface objects in display RAM. The IDirectDrawSurface::Flip method is called to display the recently composed frame, which sets a register so the exchange occurs when the screen performs a vertical retrace. This operation is asynchronous, so the application can continue processing after calling IDirectDrawSurface::Flip. (After this method has been called, the back buffer is automatically write-blocked until the exchange occurs.) After the exchange occurs, this process continues: the application composes the next frame in the back buffer, calls IDirectDrawSurface::Flip, and so on.

DirectDraw improves performance over the Windows 3.1 GDI model. The Windows 3.1 GDI model had no direct access to bitmaps in display memory. Blits always occurred in system RAM and were then transferred to display memory, thereby slowing performance. With DirectDraw, all processing is done on the display adapter card whenever possible. DirectDraw also improves performance over the Microsoft Windows 95 and Windows NT GDI model, which uses the CreateDIBSection function to enable hardware processing.

The third type of DirectDraw object is DirectDrawPalette. Because the physical display palette is usually maintained in display hardware, an object represents and manipulates it. The IDirectDrawPalette interface implements palettes in hardware. These bypass Windows palettes and are therefore only available when a game has exclusive access to the display hardware. DirectDrawPalette objects are also created from DirectDraw objects.

The fourth type of DirectDraw object is DirectDrawClipper. DirectDraw manages clipped regions of display memory by using this object.

Transparent blitting is the technique by which a bitmap is transferred to a surface and a certain color, or range of colors, in the bitmap is defined as transparent. Transparent blits are achieved using color keying. Source color keying operates by defining which color or color range on the bitmap is transparent and therefore not copied during a transfer operation. Destination color keying operates by defining which color or color range on the surface will be covered by pixels of that color or color range in the source bitmap.

Finally, DirectDraw supports overlays in hardware and by software emulation. Overlays present an easier means of implementing sprites and managing multiple layers of animation. Any DirectDrawSurface object can be created as an overlay with all of the capabilities of any other surface, plus extra capabilities associated only with overlays. These capabilities require extra display memory, and if there are no overlays in display memory, the overlay surfaces can exist in system memory.

Color keying works in the same way for overlays as for transparent blits. The z-order of the overlay automatically handles the occlusion and transparency manipulations between overlays.


DirectSound

Programming for high-performance applications and games requires efficient and dynamic sound production. Microsoft provides two methods for achieving this: MIDI streams and DirectSound. MIDI streams are actually part of the Windows 95 multimedia application programming interface. They provide the ability to time stamp MIDI messages and send a buffer of these messages to the system, which can then efficiently integrate them with its processes. For more information about MIDI streams, see the documentation included with the Win32 SDK.

DirectSound implements a new model for playing back digitally-recorded sound samples and mixing different sample sources together. As with other object classes in the DirectX 2 SDK, DirectSound uses the hardware to its greatest advantage whenever possible and emulates hardware features in software when the feature is not present in hardware. You can query hardware capabilities at run time to determine the best solution for any given personal computer configuration.

DirectSound is built on the COM-based interfaces IDirectSound and IDirectSoundBuffer, and is extensible to other interfaces. For more information about the COM concepts required for programming applications using the DirectX 2 SDK, see The Component Object Model.

The DirectSound object represents the sound card and its various attributes. The DirectSoundBuffer object is created using the DirectSound object's IDirectSound::CreateSoundBuffer method and represents a buffer containing sound data. Several DirectSoundBuffer objects can exist and be mixed together into the primary DirectSoundBuffer object. DirectSound buffers are used to start, stop, and pause sound playback, and to set attributes such as frequency, format, and so on.

Depending on the card type, DirectSound buffers can exist in hardware as onboard RAM, wave table memory, a direct memory access (DMA) channel, or a virtual buffer (for an I/O port-based audio card). Where there is no hardware implementation of a DirectSound buffer, it is emulated in system memory.

The primary buffer is generally used to mix sound from secondary buffers, but can be accessed directly for custom mixing or other specialized activities. (Use caution in locking the primary buffer, because this blocks all access to the sound hardware from other sources).

The secondary buffers can store common sounds played throughout an application, such as in a game. A sound stored in a secondary buffer can be played as a single event or as a looping sound that plays repeatedly.

Secondary buffers can also play sounds larger than available sound buffer memory. When used to play a sound that is larger than the buffer, the secondary buffer serves as a queue that stores the portions of the sound about to be played.


DirectPlay

One of the most compelling features of the personal computer as a game platform is its easy access to communication services. DirectPlay is a service that capitalizes on this capability and allows multiple players to interact with a game through standard modems, network connections, or online services.

The IDirectPlay interface contains methods providing capabilities such as creating and destroying players, adding players to and deleting players from groups, sending messages to players, inviting players to participate in a game, and so on.

DirectPlay is composed of the interface to the game, as defined by the IDirectPlay interface and the DirectPlay server. DirectPlay servers are provided by Microsoft for modems and networks, as well as by third parties. When using a supported server, DirectPlay-enabled games can bypass connectivity and communication overhead details.


Direct3D

Direct3D is the next generation of real-time, interactive 3D technology for mainstream computer users on the desktop and the Internet. It provides the API services and device independence that you need, delivers a common driver model for hardware vendors, enables turn-key 3D solutions to be offered by personal computer manufacturers, and makes it easy for end-users to add high-end 3D to their systems.

Direct3D is a complete set of real-time 3D graphics services that delivers fast software-based rendering of the full 3D rendering pipeline (transformations, lighting, and rasterization) and transparent access to hardware acceleration. Direct3D offers a comprehensive next-generation 3D solution for mainstream computers. API services include an integrated high-level Retained mode and low-level Immediate mode API, and support for other systems that might use Direct3D to gain access to 3D hardware acceleration. Direct3D is fully scalable, enabling all or part of the 3D rendering pipeline to be accelerated by hardware. Direct3D exposes advanced graphics capabilities of 3D hardware accelerators, including z-buffering, anti-aliasing, alpha blending, mipmapping, atmospheric effects, and perspective-correct texture mapping. Tight integration with other DirectX technologies enables Direct3D to deliver such advanced features as video mapping, hardware 3D rendering in 2D overlay planes—and even sprites—providing seamless use of 2D and 3D graphics in interactive media titles.


DirectInput

The joystick represents a class of devices that report tactile movements and actions players make within a game. DirectInput provides the functionality to process the data representing these movements and actions from joysticks, as well as other related devices, such as trackballs and flight harnesses.

Currently, DirectInput is simply another name for an existing Win32 function, joyGetPosEx. This function provides extended capabilities to its predecessor, joyGetPos, and should be used for any joystick services. In future support for input devices, including virtual reality hardware, games that use joyGetPosEx will be automatically supported for joystick input services. This is not the case for joyGetPos.


AutoPlay

AutoPlay is a feature of Windows 95 that automatically plays a CD-ROM or audio CD when inserted into a CD-ROM drive. While this feature is not specific to the Windows 95 DirectX 2 SDK; any CD-ROM product that bears the Windows 95 logo must be enabled with the AutoPlay feature.


Sample Applications

Sample applications that demonstrate the components of the Windows 95 DirectX 2 SDK are located in the SDK\SAMPLES directory.


DirectX and the Component Object Model


The Component Object Model

Many of the APIs in the DirectX 2 SDK are composed of objects and interfaces based on the Component Object Model (COM). COM is a foundation for an object-based system that focuses on reuse of interfaces and is the model at the heart of OLE programming. It is also an interface specification from which any number of interfaces can be built. It is an object model at the operating system level.

Many DirectX 2 APIs are instantiated as a set of OLE objects. The object can be considered a black box that represents the hardware and requires communication with applications through an interface. The commands sent to and from the object through the COM interface are called methods. For example, the IDirectDraw::GetDisplayMode method is sent through the IDirectDraw interface to get the current display mode of the display adapter from the DirectDraw object.

Objects can bind to other objects at run time and use the implementation of interfaces provided by the other object. If you know an object is an OLE object, and what interfaces that object supports, your application, or another object, can determine what services the first object can be called upon to perform. One of the methods inherited by all OLE objects, called QueryInterface, lets you determine what interfaces are supported by an object and create pointers to these interfaces.


IUnknown

All COM interfaces are derived from an interface called IUnknown. The IUnknown interface provides DirectX with control of the object's lifetime, and the ability to navigate multiple interfaces. IUnknown has only three methods:

•	AddRef, which increments the reference count of the object by 1 when an interface or another application binds itself to the object.

•	Release, which decrements the reference count of the object by 1. When the count reaches 0, the object is deallocated.

•	QueryInterface, which queries the object about the features it supports by asking for pointers to a specific interface.

AddRef and Release maintain the reference count of a particular object. For example, if you create a DirectDrawSurface object, the reference count of the object is set to 1. Each time a function returns a pointer to an interface for that object, the function must then call AddRef through that pointer to increment the reference count. All AddRef calls must be matched with a call to Release. Before the pointer can be destroyed, you must call Release through that pointer. Once the reference count of a particular object reaches 0, the object is destroyed and all interfaces to that object are then invalid.

QueryInterface determines whether an object supports a specific interface. If the interface is supported, QueryInterface returns a pointer to that particular interface. You can then use the methods contained in that interface to communicate with the object. If QueryInterface successfully returns a pointer to an interface, it implicitly calls AddRef to increment the reference count, so your application must call Release to decrement the reference count before destroying the pointer to the interface.


DirectX 2 SDK COM Interfaces

The interfaces in the DirectX 2 SDK have been created at a very basic level of the COM programming hierarchy. Each main device object interface, such as IDirectDraw, IDirectSound, or IDirectPlay, derives directly from the IUnknown interface in OLE. Creation of these basic objects is handled by specialized functions in the dynamic link library (DLL) for each object rather than by the Win32 CoCreateInstance function typically used to create COM objects.

In general, the DirectX 2 SDK object model provides one main object for each device, from which other support service objects are derived. For example, the DirectDraw object represents the display adapter. It is used to create DirectDrawSurface objects that represent the display RAM and DirectDrawPalette objects that represent hardware palettes. Similarly, the DirectSound object represents the audio card and creates DirectSoundBuffer objects that represent the sound sources on that card.

Besides the ability to generate subordinate objects, the main device object determines the capabilities of the hardware device it represents, such as the screen size and number of colors, or whether the audio card has wave table synthesis.


C++ and the COM Interface

To C++ programmers, a COM interface is like an abstract base class. That is, it defines a set of signatures and semantics but not the implementation, and no state data is associated with the interface. In a C++ abstract base class, all methods are defined as "pure virtual," which means they have no code associated with them.

Pure virtual C++ functions and COM interfaces both employ a device called a vtable. A vtable contains the addresses of all functions that implement the given interface. If you want a program or object to use these functions, you can use the QueryInterface method to verify the interface exists on an object, and to obtain a pointer to that interface. What your program or object actually receives from the object after sending QueryInterface is a pointer to the vtable, through which this method can call the interface methods implemented by the object. This mechanism totally isolates private data used by the object and the calling client process.

Another similarity of COM objects to C++ objects is that the first argument of a method is the name of the interface or class, called the this argument in C++. Because COM objects and C++ objects are totally binary compatible, the compiler treats COM interfaces like C++ abstract classes and assumes the same syntax. This results in less complex code. For example, the this argument in C++ is treated as an understood parameter and not coded, and the indirection through the vtable is handled implicitly in C++.


Accessing COM Objects Using C

Any COM interface method can be called from a C program. There are two things you need to remember when calling an interface method from C:

•	The first parameter of the method is always a reference to the object that has been created and is invoking the method (the this argument).

•	Each method in the interface is referenced through a pointer to the object's vtable.

The following example creates a surface associated with a DirectDraw object by calling the IDirectDraw::CreateSurface method using the C programming language:

ret = lpDD->lpVtbl->CreateSurface (lpDD, &ddsd, &lpDDS,

      NULL);

The DirectDraw object associated with the new surface is referenced by the lpDD parameter. Incidentally, this method fills in a surface description structure (&ddsd) and returns a pointer the new surface (&lpDDS).

To call the IDirectDraw::CreateSurface method, you first dereference the DirectDraw object's vtable, then dereference the method from the vtable. The first parameter supplied in the method is a reference to the DirectDraw object that has been created and is invoking the method.

To illustrate the difference between calling a COM object method in C and C++, the same method in C++ is shown below (C++ implicitly dereferences the vtbl pointer and passes the this pointer):

ret = lpDD->CreateSurface(&ddsd, &lpDDS, NULL)


Interface Method Names and Syntax

All of the COM interface methods described in this document are shown using C++ class names. This naming convention is used for consistency, and to differentiate between methods used for different DirectX objects that use the same name, such as QueryInterface, AddRef, and Release. This does not imply that these methods can only be used with C++.

In addition, the syntax provided for the methods uses C++ conventions for consistency. It does not include the this pointer to the interface. When programming in C, the pointer to the interface must be included in each method. For example, the following example shows the C++ syntax for the IDirectDraw::GetCaps method:

HRESULT GetCaps(LPDDCAPS lpDDDriverCaps,

    LPDDCAPS lpDDHELCaps);

The same example using C syntax looks like this:

HRESULT GetCaps(LPDIRECTDRAW lpDD,

    LPDDCAPS lpDDDriverCaps, LPDDCAPS lpDDHELCaps);

The lpDD parameter is a pointer to the DirectDraw structure that represents the DirectDraw object.


Using Macro Definitions

Many of the header files for the DirectX interfaces include macro definitions for each method. These macros are included to simplify the use of the methods in your programming.

For example, the following example uses the IDirectDraw_CreateSurface macro to call the IDirectDraw::CreateSurface method. The first parameter is a reference to the DirectDraw object that has been created and is invoking the method:

ret = IDirectDraw_CreateSurface (lpDD, &ddsd, &lpDDS,

    NULL);

To obtain a current list of the methods supported by macro definitions, see the appropriate header file for the DirectX component you want to use.


Floating-point Precision

The DirectX architecture uses a floating-point precision of 53. If your application needs to change this precision, it must be changed back to 53 when the calculations are finished. Otherwise, system components that depend on the default value will stop working.


Differences Between the Game SDK and the DirectX 2 SDK

The DirectX 2 SDK provides more services—and more avenues for innovation—than did the Game SDK. Although the DirectX 2 SDK contains additional functions and services, all of the applications you have written with the Game SDK will compile and run successfully without changes.

This section identifies some of the most significant differences and improvements of the DirectX 2 SDK over the Game SDK. The purpose of this section is to help developers familiar with the Game SDK quickly identify several important areas of the DirectX SDK that are significantly different.


DirectDraw

The DirectDraw API functions have been significantly improved over those found in the Game SDK. The following list briefly describes the major improvements:

•	The IDirectDraw2 and IDirectDrawSurface2 interfaces were added. For more information, see IDirectDraw2 Interface and IDirectDrawSurface2 Interface.

•	The following flags were added:

DDBLT_DEPTHFILL	DDCAPS_BLTDEPTHFILL
DDCAPS_CANBLTSYSMEM	DDCAPS_CANCLIP
DDCAPS_CANCLIPSTRETCHED	DDCAPS2_NO2DDURING3DSCENE
DDEDM_REFRESHRATES	DDPCAPS_1BIT
DDPCAPS_2BIT	DDPF_PALETTEINDEXED1
DDPF_PALETTEINDEXED2	DDSCAPS_ALLOCONLOAD
DDSCAPS_MIPMAP	DDSD_MIPMAPCOUNT
DDSD_REFRESHRATE
In addition, the name of the DDSCAPS_TEXTUREMAP flag was changed to DDSCAPS_TEXTURE and the name of the DDPF_PALETTEINDEXED4TO8 flag was changed to DDPF_PALETTEINDEXEDTO8.

•	The following error messages were added:

DDERR_CANTLOCKSURFACE	DDERR_CANTPAGELOCK
DDERR_CANTPAGEUNLOCK	DDERR_DCALREADYCREATED
DDERR_INVALIDSURFACETYPE	DDERR_NOMIPMAPHW
DDERR_NOTPAGELOCKED	DDERR_NOTINITIALIZED
•	The IDirectDraw2::SetDisplayMode method contains two new parameters, dwRefreshRate and dwFlags. If neither of these parameters are needed, you can still use IDirectDraw::SetDisplayMode.

•	The IDirectDraw2::EnumDisplayModes method was added to enumerate the refresh rate of the monitor and store it in the dwRefreshRate member of the DDSURFACEDESC structure.

•	A new method has been added to the IDirectDraw2 interface: IDirectDraw2::GetAvailableVidMem.

•	Three new methods have been added to the IDirectDrawSurface2 interface: IDirectDrawSurface2::GetDDInterface, IDirectDrawSurface2::PageLock, and IDirectDrawSurface2::PageUnlock.

•	DirectDraw in the Game SDK limited the available display modes to 640 by 480 with pixel depths of 8 bpp and 16 bpp. DirectDraw now allows an application to change the mode to allow any supported by the display driver.

•	DirectDraw now checks the display modes it is capable of using against the display restrictions of the installed monitor. If the requested mode is not compatible with the monitor, then the IDirectDraw2::SetDisplayMode method will fail. Only modes supported on the installed monitor will be enumerated in the IDirectDraw2::EnumDisplayModes method.

•	In the Game SDK, DirectDraw only allowed the creation of one DirectDraw object per process. If your process happened to use another system component, such as DirectPlay, that created a DirectDraw object, the process would be unable to create another DirectDraw object for its own use. It is now possible for a process to call the DirectDrawCreate function as many times as necessary. A unique and independent interface will be returned from each call. For more information, see Multiple DirectDraw Objects per Process.

•	DirectDraw on the Game SDK required an HWND be specified in the IDirectDraw::SetCooperativeLevel method call regardless of whether or not a full-screen, exclusive mode was being requested. This method no longer requires an HWND be specified if the application is requesting DDSCL_NORMAL mode. It is now possible for an application to use DirectDraw with multiple windows. All of these windows can be used simultaneously in normal mode.

•	In DirectDraw on the Game SDK, if a surface was in system memory, the hardware emulation layer (HEL) automatically performed the blit. However, some display cards have DMA hardware that allows them to efficiently blit to and from system memory surfaces. In the DirectX 2 version of DirectDraw, the DDCAPS structure has been expanded to allow drivers to report this capability. The following members have been added:

DWORD      dwSVBCaps

DWORD      dwSVBCKeyCaps

DWORD      dwSVBFXCaps

DWORD      dwSVBRops[DD_ROP_SPACE]

DWORD      dwVSBCaps

DWORD      dwVSBCKeyCaps

DWORD      dwVSBFXCaps

DWORD      dwVSBRops[DD_ROP_SPACE]

DWORD      dwSSBCaps

DWORD      dwSSBCKeyCaps

DWORD      dwSSBFXCaps

DWORD      dwSSBRops[DD_ROP_SPACE]

•	In DirectDraw on the Game SDK, palettes could only be attached to the primary surface. Palettes can now be attached to any paletized surface (primary, back buffer, off-screen plain, or texture map). For more information, see Setting Palettes on Non-Primary Surfaces.

•	Palettes can now be shared between multiple surfaces. For more information, see Sharing Palettes.

•	In DirectDraw on the Game SDK, only 8-bit (256 entry) palettes were supported. DirectDraw on the DirectX 2 SDK supports 1-bit (2 entry), 2-bit (4 entry), and 4-bit (16 entry) palettes as well. For more information, see New Palette Types.

•	Clippers can now be shared between multiple surfaces. For more information, see Sharing Clippers.

•	A new API function, DirectDrawCreateClipper was added. This function allows clipper objects to be created that are not owned by a DirectDraw object. For more information, see Driver Independent Clippers.

•	In DirectDraw on the Game SDK, the HEL could only create surfaces whose pixel format exactly matched that of the current primary surface. This restriction has been relaxed for the DirectX 2 version of DirectDraw. For more information, see Surface Format Support in the Hardware Emulation Layer (HEL).

•	Support for surfaces specific to 3D rendering (texture maps, mipmaps, and z-buffers) has been added or enhanced in the DirectX 2 version of DirectDraw. For more information, see Texture Maps, Mipmaps, and Z-Buffers.


DirectSound

Although there are few visible external differences between DirectSound on the Game SDK and DirectSound on the DirectX 2 SDK, significant internal improvements have been made. The following is a brief list of some of these differences:

•	Improvements to the wave emulation code, used when no device driver is available, to support wave drivers that do not work correctly.

•	Changes to the sound focus management. These changes should not make any difference to most games. They were needed to support out-of-proc (exe server) COM objects, and to support the requirements of ActiveX™ (Microsoft's high-level media streaming architecture).

•	The DSBCAPS_STICKYFOCUS flag was added. This flag can be specified in a IDirectSound::CreateSoundBuffer method call in order to change the focus behavior of the sound buffer.


DirectPlay

The difference below reflects the only external change that has been made to DirectPlay:

•	The error DPERR_SENDTOOBIG is now returned if the message buffer passed to the IDirectPlay::Send method is larger than DirectPlay allows.


Direct3D

The Game SDK did not contain any Direct3D functionality. All of the Direct3D functionality is new in the DirectX 2 SDK.


DirectInput

No changes were made to this version of DirectInput.


AutoPlay

No changes were made to this version of AutoPlay.


DirectSetup

The DSETUP_D3D flag was added to the dwFlags parameter of the DirectXSetup function.


Conventions

The following conventions are used to define syntax.

Convention	Meaning
Italic text	Denotes a placeholder or variable. You must provide the actual value. For example, the statement SetCursorPos(X, Y) requires you to substitute values for the X and Y parameters.
[]	Enclose optional parameters.
|	Separates an either/or choice.
...	Specifies that the preceding item may be repeated.
.	Represents an omitted portion of a sample application.
.
.
In addition, certain typographic conventions are used to help you understand this material.

Convention	Meaning
SMALL CAPITALS	Indicates the names of keys, key sequences, and key combinations—for example, ALT+SPACEBAR.
FULL CAPITALS	Indicates most type and structure names, which are also bold, and constants.
monospace	Sets off code examples and shows syntax spacing.


DirectDraw


Overview


About DirectDraw

DirectDraw™ is a DirectX™ 2 SDK component that allows direct manipulation of display memory, hardware blitters, hardware overlays, and page flipping. DirectDraw provides this functionality while maintaining compatibility with existing Microsoft® Windows® 95 applications and device drivers.

The DirectX 2 SDK allows you an unprecedented level of access to display and audio hardware, while it insulates you from the specific details of that hardware. DirectX 2 is built for speed. In keeping with these goals, DirectDraw is not a high-level graphics application programming interface (API).

DirectDraw for Windows 95 is a software interface that provides direct access to display devices while maintaining compatibility with the Windows graphics device interface (GDI). DirectDraw provides a device-independent way for games and Windows subsystem software, such as 3D graphics packages and digital video codecs, to gain access to display device-dependent features.

DirectDraw works with a wide variety of display hardware, ranging from simple SVGAs to advanced hardware implementations that provide clipping, stretching, and non-RGB color format support. The interface is designed so that your applications can request the capabilities of the underlying hardware, then use those capabilities as required.

DirectDraw provides the following display device-dependent benefits:

•	Supports double-buffered and page flipping graphics.

•	Provides access to, and control of, the display card's blitter.

•	Supports 3D z-buffers.

•	Supports hardware assisted overlays with z-ordering.

•	Improves graphics quality by providing access to image-stretching hardware.

•	Provides simultaneous access to standard and enhanced display device memory areas.

DirectDraw's mission is to provide device-dependent access to display memory in a device-independent way. Your application need only recognize some basic device dependencies that are standard across hardware implementations, such as RGB and YUV color formats and the stride between raster lines. You need not worry about the specific calling procedures required to utilize the blitter or manipulate palette registers. Essentially, DirectDraw manages display memory. Using DirectDraw, you can manipulate display memory with ease, taking full advantage of the blitting and color decompression capabilities of different types of display hardware without becoming dependent on a particular piece of hardware.

DirectDraw provides world-class game graphics on computers running Windows 95 and Windows NT®.


Introduction to DirectDraw

DirectDraw provides display-memory and display-hardware management services. It also provides the usual functionality associated with memory management: memory can be allocated, moved, transformed, and freed. This memory represents visual images and is referred to as a surface. Through the DirectDraw hardware abstraction layer (HAL), applications are exposed to unique display hardware functionality, including stretching, overlaying, texture mapping, rotating, and mirroring.


Architectural Overview


DirectDraw

DirectDraw is the Windows system component that performs the common functions required by both hardware and software implementations of DirectDraw. As such, DirectDraw is the only client of the DirectDraw hardware abstraction layer (HAL). Applications must write to DirectDraw. DirectDraw returns two sets of capabilities, one for hardware capabilities and one for software emulation capabilities. Using these, an application can easily determine what DirectDraw is emulating and what functionality is provided in hardware and adjust itself accordingly.

DirectDraw is implemented by the DDRAW dynamic-link library (DLL). This 32-bit DLL implements all of the common functionality required by DirectDraw. It performs all of the necessary thunking between Win32 and the 16-bit portions of the HAL, as well as complete parameter validation. It provides management for off-screen display memory, and performs all of the bookkeeping and semantic logic required for DirectDraw. It is responsible for presenting the Component Object Model (COM) interface to the application, hooking hWnds to provide clip lists, and all other device-independent functionality.


DirectDraw HAL

The DirectDraw HAL is hardware dependent and contains only hardware-specific code. The HAL can be implemented in 16 bits, 32 bits, or, on Windows 95, a combination of the two. The HAL is always 32 bits on Windows NT. The HAL can be an integral part of the display driver or a separate DLL that communicates with the display driver through a private interface defined by the driver's creator.

The DirectDraw HAL is implemented by the chip manufacturer, board producer, or original equipment manufacturer (OEM). The HAL implements only the device-dependent code and performs no emulation. If a function is not performed by the hardware, the HAL should not report it as a hardware capability. The HAL should do no parameter validation. The parameters will be validated by DirectDraw before the HAL is invoked.


DirectDraw Software Emulation

DirectDraw's hardware emulation layer (HEL) presents its capabilities to DirectDraw just like a HAL would. By examining these capabilities during application initialization, you can adjust application parameters to provide optimum performance on a variety of platforms. If a DirectDraw HAL is not present or a requested feature is not provided by the hardware, DirectDraw will emulate the missing functionality.


Types of DirectDraw Objects

The DirectDraw object represents the display device. There can be one DirectDraw object for every logical display device in operation. An application development environment, for instance, might have two monitors, one running the application using DirectDraw and one running the development environment using GDI.

A DirectDrawSurface object represents a linear region of display memory that can be directly accessed and manipulated. These display memory addresses may point to visible frame buffer memory (primary surface) or to non-visible buffers (off-screen or overlay surfaces). These non-visible buffers usually reside in display memory, but can be created in system memory if required by the hardware design or if DirectDraw is doing software emulation. An overlay is a surface that can be made visible without altering the pixels it is obscuring. Overlays and sprites are synonymous. A texture map is a surface that can be wrapped onto a 3D surface.

A DirectDrawPalette object represents either a 16 or a 256 color-indexed palette. Palettes are provided for textures, off-screen surfaces, and overlay surfaces, none of which are required to have the same palette as the primary surface.

The DirectDraw object creates DirectDrawSurface, DirectDrawPalette, and DirectDrawClipper objects. DirectDrawPalette and DirectDrawClipper objects must be attached to the DirectDrawSurface objects they affect. A DirectDrawSurface may refuse the request to attach a DirectDrawPalette to it. This is not unusual because most hardware does not support multiple palettes.


Using DirectDraw


IDirectDraw2 Interface

The COM model used by DirectDraw specifies that new functionality can be added by providing new interfaces. This release of DirectDraw implements two new interfaces, the IDirectDraw2 Interface and the IDirectDrawSurface2 Interface. These new interfaces can be obtained by using the IDirectDraw::QueryInterface method, as shown in the following example:

    /*

     * create an IDirectDraw2 interface

     */

    LPDIRECTDRAW        lpDD;

    LPDIRECTDRAW2       lpDD2;

    ddrval = DirectDrawCreate( NULL, &lpDD, NULL );

    if( ddrval != DD_OK )

        return;

    ddrval = lpDD->SetCooperativeLevel( hwnd,

             DDSCL_NORMAL );

    if( ddrval != DD_OK )

        return;

    ddrval = lpDD->QueryInterface( IID_IDirectDraw2,

             (LPVOID *)&lpDD2);

    if( ddrval != DD_OK )

        return;

    ddscaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;

    ddrval = lpDD2->GetAvailableVidMem(&ddscaps, &total,

             &free);

    if( ddrval != DD_OK )

        return;

This example shows C++ syntax for creating an IDirectDraw interface, which then uses the IDirectDraw::QueryInterface method to create an IDirectDraw2 interface. This interface contains the IDirectDraw2::GetAvailableVidMem method. An attempt to use this method from an IDirectDraw interface will result in a compile-time error.

In addition to the IDirectDraw2::GetAvailableVidMem method, the IDirectDraw2 interface contains all of the methods provided in the IDirectDraw interface. Included in this interface are the IDirectDraw2::SetDisplayMode and IDirectDraw2::EnumDisplayModes methods which allow refresh rates to be specified. If refresh rates are not required, the IDirectDraw::SetDisplayMode and IDirectDraw::EnumDisplayModes methods can be used.

The interaction between the IDirectDraw::SetCooperativeLevel and IDirectDraw::SetDisplayMode methods is slightly different than the one between the IDirectDraw2::SetCooperativeLevel and IDirectDraw2::SetDisplayMode methods. If you are using the IDirectDraw interface and an application gains exclusive mode by calling IDirectDraw::SetCooperativeLevel with the DDSCL_EXCLUSIVE flag, changes the mode using IDirectDraw::SetDisplayMode, then releases exclusive mode by calling IDirectDraw::SetCooperativeLevel with the DDSCL_NORMAL flag, the original display mode will not be restored. The new display mode will remain until the application calls the IDirectDraw::RestoreDisplayMode method or the DirectDraw object is deleted. However, if you are using the IDirectDraw2 interface and an application follows the same steps, the original display mode will be restored when exclusive mode is lost.

Note

Because some methods behave somewhat differently in the two interfaces, mixing methods from IDirectDraw and IDirectDraw2 may cause unpredictable results. You should only use functions from one of these interfaces at a time; do not use some functions from IDirectDraw and other functions from IDirectDraw2.

For more information on using the IDirectDrawSurface2 interface, see IDirectDrawSurface2 Interface.


Multiple DirectDraw Objects per Process

DirectDraw allows a process to call the DirectDrawCreate function as many times as necessary. A unique and independent interface will be returned from each call. Each DirectDraw object can be used as desired; there are no dependencies between the objects. Each object behaves exactly as if it had been created by two different processes.

Since the DirectDraw objects are independent, the DirectDrawSurface, DirectDrawPalette, and DirectDrawClipper objects created with a particular DirectDraw object should not be used with other DirectDraw objects because these objects are automatically released when the DirectDraw object is destroyed. If they are used with another DirectDraw object, they may stop functioning if the original object is destroyed.

The exception is DirectDrawClipper objects created with the DirectDrawCreateClipper function. These objects are independent of any particular DirectDraw object and can be used with one or more DirectDraw objects.


Support for High Resolutions and True Color Bit Depths

DirectDraw supports all of the screen resolutions and depths supported by the display device driver. DirectDraw allows an application to change the mode to any one supported by the computer's display driver, including all supported 24- and 32-bpp modes.

DirectDraw also supports hardware emulation layer (HEL) blitting of 24- and 32-bpp surfaces. If the display device driver supports blitting at these resolutions, the hardware blitter will be used for display memory to display memory blits. Otherwise, the HEL will be used to perform the blits.

Windows 95 allows a user to specify the type of monitor that is being used. DirectDraw checks the display modes that it knows about against the display restrictions of the installed monitor. If it is determined that the requested mode is not compatible with the monitor, the IDirectDraw2::SetDisplayMode method call will fail. Only modes that are supported on the installed monitor will be enumerated with the IDirectDraw2::EnumDisplayModes method.


Primary Surface Resource Sharing Model

DirectDraw has a simple resource sharing model. Display memory is a scarce, shared resource. If the mode is changed, all of the surfaces stored in display memory are lost (for more information, see Losing Surfaces).

DirectDraw implicitly creates a GDIPrimarySurface when it is instantiated for a display device DirectDraw is sharing with GDI. GDI is granted shared access to the primary surface. DirectDraw keeps track of the surface memory that GDI recognizes as the primary surface. The DirectDrawSurface that owns GDI's primary surface can always be obtained using the IDirectDraw::GetGDISurface method.

GDI is not allowed to cache fonts, brushes, and device-dependent bitmaps (DDBs) in the display memory managed by DirectDraw. The HAL must reserve whatever display memory the DIB engine driver needs before describing the available memory to DirectDraw's heap manager or before the display device driver can allocate and free memory for its cached data from DirectDraw's heap manager.


Changing Modes and Exclusive Access

Display modes can be changed using the IDirectDraw2::SetDisplayMode method. Modes can be changed by any application as long as all of the applications are sharing the display card.

The DirectDraw exclusive mode does not bar other applications from allocating DirecDrawSurfaces, nor does it exclude them from using DirectDraw or GDI functionality. However, it does prevent all applications, other than the one that obtained exclusive access, from changing the display mode or changing the palette.


Creating DirectDraw Objects Using CoCreateInstance

You can create a DirectDraw object using CoCreateInstance and the IDirectDraw::Initialize method rather than the DirectDrawCreate function. The following steps describe how to create the DirectDraw object:

1	Initialize COM at the start of your application using CoInitialize(NULL).

    if (FAILED(CoInitialize(NULL)))

        return FALSE;

2	Create your DirectDraw object using CoCreateInstance and the IDirectDraw::Initialize method.

ddrval = CoCreateInstance(&CLSID_DirectDraw,

                                       NULL,

                                       CLSCTX_ALL,

                                       &IID_IDirectDraw,

                                       &lpdd);

if( !FAILED(ddrval) )

    ddrval = IDirectDraw_Initialize( lpdd, NULL);

CLSID_DirectDraw is the class identifier of the DirectDraw driver object class and IID_IDirectDraw is the particular DirectDraw interface you want. lpdd is the DirectDraw object returned. CoCreateInstance returns an uninitialized object.

3	Before you use the DirectDraw object, you must call IDirectDraw::Initialize. This method takes the driver GUID parameter that the DirectDrawCreate function typically uses (NULL in this case). Once the DirectDraw object is initialized, you can use and release the DirectDraw object as if it had been created using the DirectDrawCreate function. If you do not call the IDirectDraw::Initialize method before using one of the methods associated with the DirectDraw object, a DDERR_NOTINITIALIZED error will occur.

Before closing the application, shut down COM using CoUninitialize, as shown below.

    CoUnitialize();


Using DirectDrawSurface


IDirectDrawSurface2 Interface

The COM model that DirectDraw uses specifies that new functionality can be added by providing new interfaces. This release of DirectDraw implements two new interfaces, the IDirectDraw2 Interface and the IDirectDrawSurface2 Interface.

The following example shows how to create an IDirectDrawSurface2 interface:

    LPDIRECTDRAWSURFACE     lpSurf;

    LPDIRECTDRAWSURFACE2    lpSurf2;

    // Create surfaces

    memset( &ddsd, 0, sizeof( ddsd ) );

    ddsd.dwSize = sizeof( ddsd );

    ddsd.dwFlags = DDSD_CAPS | DDSD_WIDTH | DDSD_HEIGHT;

    ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN |

                          DDSCAPS_SYSTEMMEMORY;

    ddsd.dwWidth = 10;

    ddsd.dwHeight = 10;

    ddrval = lpDD2->CreateSurface( &ddsd, &lpSurf,

             NULL );

    if( ddrval != DD_OK )

        return;

    ddrval = lpSurf->QueryInterface(

             IID_IDirectDrawSurface2, (LPVOID *)&lpSurf2);

    if( ddrval != DD_OK )

        return;

    ddrval = lpSurf2->PageLock( 0 );

    if( ddrval != DD_OK )

        return;

    ddrval = lpSurf2->PageUnlock( 0 );

    if( ddrval != DD_OK )

        return;

The IDirectDrawSurface2 interface contains all of the methods provided in the IDirectDrawSurface interface, along with three new methods: IDirectDrawSurface2::GetDDInterface, IDirectDrawSurface2::PageLock, and IDirectDrawSurface2::PageUnlock.

For more information on obtaining the IDirectDraw2 interface, see IDirectDraw2 Interface.


Frame Buffer Access

DirectDrawSurface objects represent surface memory in the DirectDraw architecture. A DirectDrawSurface allows an application to directly gain access to this surface memory through the IDirectDrawSurface::Lock method. An application calls this method, providing a RECT structure that specifies the rectangle on the surface it requires access to. If the application calls IDirectDrawSurface::Lock with a NULL RECT, it is assumed that exclusive access to the entire piece of surface memory is being requested by the application. This method fills in a DDSURFACEDESC structure with the information needed for the application to gain access to the surface memory. This information includes the pitch (or stride) and the pixel format of the surface, if different from the pixel format of the primary surface. When an application is finished with the surface memory, the surface memory can be made available with the IDirectDrawSurface::Unlock method.

Experience shows that there are several common problems you may encounter when rendering directly into a DirectDrawSurface. The following list describes some solutions to these problems:

•	Never assume a constant display pitch. Always examine the pitch information returned by the IDirectDrawSurface::Lock method. This pitch may vary for a number of reasons, including the location of the surface memory, the type of display card, or even the version of the DirectDraw driver being used.

•	Limit activity between the calls to the IDirectDrawSurface::Lock and IDirectDrawSurface::Unlock methods. The IDirectDrawSurface::Lock method holds the WIN16 lock so that gaining access to surface memory can occur safely, and the IDirectDrawSurface::GetDC method implicitly calls IDirectDrawSurface::Lock. The WIN16 lock serializes access to GDI and USER, shutting down Windows for the duration between the Lock and Unlock operations, as well as between the GetDC and ReleaseDC operations.

•	Be sure you copy aligned to display memory. Windows 95 uses a page fault handler, Vflatd.386, to implement a virtual flat frame buffer for display cards with bank-switched memory. This module allows these display devices to present a linear frame buffer to DirectDraw. Copying unaligned to display memory can cause the system to suspend operations if the copy happens to span memory banks.


Losing Surfaces

The surface memory associated with a DirectDrawSurface object may be freed, while the DirectDrawSurface objects representing these pieces of surface memory are not necessarily released. When a DirectDrawSurface object loses its surface memory, many methods will return DDERR_SURFACELOST and perform no other function.

Surfaces can be lost because the display card mode was changed or because an application received exclusive access to the display card and freed all of the surface memory currently allocated on the card. The IDirectDrawSurface::Restore method recreates these lost surfaces and reconnects them to their DirectDrawSurface objects.


Surface Format Support in the HEL

The following table shows the pixel formats for off-screen plain surfaces supported by the DirectX 2 HEL. The "Masks" column shows the red, green, blue, and alpha masks for each set of pixel format flags and bit depth.

Pixel Format Flags	Bit Depth	Masks
DDPF_RGB |	1	R: 0x00000000
DDPF_PALETTEINDEXED1		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	2	R: 0x00000000
DDPF_PALETTEINDEXED2		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	4	R: 0x00000000
DDPF_PALETTEINDEXED4		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	8	R: 0x00000000
DDPF_PALETTEINDEXED8		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB	16	R: 0x0000F800
		G: 0x000007E0
		B: 0x0000001F
		A: 0x00000000
DDPF_RGB	16	R: 0x00007C00
		G: 0x000003E0
		B: 0x0000001F
		A: 0x00000000
DDPF_RGB	24	R: 0x00FF0000
		G: 0x0000FF00
		B: 0x000000FF
		A: 0x00000000
DDPF_RGB	24	R: 0x000000FF
		G: 0x0000FF00
		B: 0x00FF0000
		A: 0x00000000
DDPF_RGB	32	R: 0x00FF0000
		G: 0x0000FF00
		B: 0x000000FF
		A: 0x00000000
DDPF_RGB	32	R: 0x000000FF
		G: 0x0000FF00
		B: 0x00FF0000
		A: 0x00000000
In addition to supporting a wider range of off-screen surface formats, the HEL also supports surfaces intended for use by Direct3D, or other 3D renderers.


Color and Format Conversion

Non-RGB surface formats are described by FourCC codes. When the pixel format is requested, if the surface is a non-RGB surface, the DDPF_FOURCC flag will be set and the dwFourCC member in the DDPIXELFORMAT structure will be valid. If the FourCC code represents a YUV format, the DDPF_YUV flag will also be set and the dwYUVBitCount, dwYBits, dwUBits, dwVBits, and dwYUVAlphaBits members will be valid masks that can be used to extract information from the pixels.

If an RGB format is present, the DDPF_RGB flag will be set and the dwRGBBitCount, dwRBits, dwGBits, dwBBits, and dwRGBAlphaBits members will be valid masks that can be used to extract information from the pixels. The DDPF_RGB flag can be set in conjunction with the DDPF_FOURCC flag if a non-standard RGB format is being described.

During color and format conversion, two sets of FourCC codes are exposed to the application. One set of FourCC codes represents what the blitting hardware is capable of; the other represents what the overlay hardware is capable of.


Color Keying

Source and destination color keying for blits and overlays are supported by DirectDraw. For both of these types of color keying, a color key or a color range may be supplied.

Source color keying specifies a color or color range that, in the case of blitting, will not be copied, or, in the case of overlays, not be visible on the destination. Destination color keying specifies a color or color range that, in the case of blitting, will be replaced or, in the case of overlays, be covered up on the destination. The source color key specifies what can and can't be read from the source surface. The destination color key specifies what can and can't be written onto, or covered up, on the destination surface. If a destination surface has a color key, only the pixels that match the color key will be changed, or covered up, on the destination surface.

Some hardware will only support color ranges for YUV pixel data. This is because YUV data is usually video, and, due to quantitization errors during conversion, the transparent background is not a single color.

Content should be authored to a single transparent color whenever possible, regardless of pixel format.


Specifying Color Keys

Color keys are specified in the pixel format of a surface. If a surface is in a palettized format, the color key is specified as an index or a range of indices. If the surface's pixel format is specified by a FourCC code that describes a YUV format, the YUV color key is specified by the three low-order bytes in both the dwColorSpaceLowValue and dwColorSpaceHighValue members of the DDCOLORKEY structure. The lowest order byte has the V data, the second lowest order byte has the U data, and the highest order byte has the Y data. The IDirectDrawSurface::SetColorKey method has a flags parameter that specifies whether the color key is to be used for overlay operations or blit operations, and whether it is a source or a destination key. Some examples of valid color keys follow:

8-bit palettized mode

// palette entry 26 is the color key

dwColorSpaceLowValue = 26;

dwColorSpaceHighValue = 26;

24-bit true color mode

// color 255,128,128 is the color key

dwColorSpaceLowValue = RGBQUAD(255,128,128);

dwColorSpaceHighValue = RGBQUAD(255,128,128);

FourCC YUV mode

// any YUV color where Y is between 100 and 110 and U

//or V is between 50 and 55 is transparent

dwColorSpaceLowValue = YUVQUAD(100,50,50);

dwColorSpaceHighValue = YUVQUAD(110,55,55);


Flipping Surfaces and GDI's Frame Rate

DirectDraw has extended flipping surfaces to encompass more than page flipping and more than visible surface flipping. Any surface can now be constructed as a flipping surface. This has many advantages over the traditional, limited scope of page flipping.

When an IDirectDrawSurface::Flip method operation is requested in DirectDraw, the surface memory areas associated with the DirectDrawSurface objects being flipped are switched. Surfaces attached to the DirectDrawSurface objects being flipped are not affected. For example, in a double-buffered situation, an application that draws on the back buffer always uses the same DirectDrawSurface object. The surface memory underneath the object is just switched with the front buffer when the IDirectDrawSurface::Flip method is requested.

If the front buffer is visible, either because it is the primary surface or because it is an overlay that is currently visible, subsequent calls to the IDirectDrawSurface::Lock method or the IDirectDrawSurface::Blt method that target the back buffer will fail with the DDERR_WASSTILLDRAWING return value until the next vertical refresh occurs. This behavior occurs because the front buffer's previous surface memory, which is no longer attached to the back buffer, is still being drawn to the physical display by the hardware. This situation disappears during the next vertical refresh because the hardware that updates the physical display re-reads the location of the display memory on every refresh.

This physical requirement makes calling the IDirectDrawSurface::Flip method on visible surfaces an asynchronous command. A good practice to follow when building games, for example, is to perform all of the non-visual elements of the game after this method is called. When the input, audio, game play, and system memory drawing operations have been completed, begin the drawing tasks that require gaining access to the visible back buffers.

When your application needs to run in a window and still requires a flipping environment, it will attempt to create a flipping overlay surface. If the hardware does not support overlays, you can create a primary surface that page flips, and when a surface that GDI is not aware of is about to become the primary surface, blit the contents of the primary surface that GDI is writing to onto the buffer that is about to become visible. This takes little, if any, processing time because the blits are performed asynchronously. It can, however, consume considerable blitter bandwidth that is dependent on screen resolution and the size of the window that is being page flipped. As long as the frame rate does not dip below 20 frames a second, GDI will appear to be operating correctly.

Before you instantiate a DirectDraw object, GDI is already using your display memory to display itself. When you call DirectDraw to instantiate a primary surface, the memory address of that surface will be the same as GDI is currently using.

If you create a complex surface with a back buffer, GDI will first point to the display memory for the primary surface. Since GDI has no knowledge of DirectDraw, GDI will continue operating on this surface, even if you have flipped it and it is now the non-visible back buffer.

Many applications will begin by creating one large window that covers the entire screen. As long as your application is active and has the focus, GDI will not attempt to write into its copy of the buffer since nothing it controls needs redrawing.

For other scenarios, always remember that GDI only knows about the original surface, and never knows if it is currently the primary surface or a back buffer. If you do not need the GDI screen, then use the above technique. If you do need GDI, you can try this technique:

•	Create a primary surface with two back buffers.

•	Blit the initial primary surface (the GDI surface) to the middle back buffer.

•	Flip(NULL) to put GDI into last place and make your initial copy visible.

After you have done this, copy from the GDI buffer to the middle buffer, draw what you want the user to see on that buffer, then use the code below, which keeps GDI safely on the bottom and oscillates between the other two buffers.

pPrimary->Flip(pMiddle)


Overlay Z-Order

Overlay z-order determines the order in which overlays clip each other, enabling a hardware sprite system to be implemented under DirectDraw. Overlays are assumed to be on top of all other screen components. Destination color keys are only affected by the bits on the primary surface, not by overlays occluded by other overlays. Source color keys work on an overlay whether or not it has a z-order specified. Overlays that do not have a specified z-order behave in unspecified ways when overlaying the same area on the primary surface. Finally, overlays without a specified z-order are assumed to have a z-order of 0. The possible z-order of overlays begins with 0, just on top of the primary surface, and ends with 4 billion, just underneath the glass on the monitor. An overlay with a z-order of 2 would obscure an overlay with a z-order of 1. An overlay is not allowed to have the same z-order as another overlay.


Palettes and Pixel Formats

DirectDraw enables the creation of multiple palettes that can be attached to off-screen surfaces. When this is done, the off-screen surfaces no longer share the palette of the primary surface. If an off-screen surface with a pixel format different from the primary surface is created, it is assumed that the hardware can use it. For instance, if a paletized off-screen surface is created when the primary surface is in 16-bit color mode, it is assumed that the blitter can convert palettized surfaces to true color during the blit operation.

DirectDraw supports the creation of standard 8-bit palettized surfaces, capable of displaying 256 colors, and two kinds of 4-bit palettized surfaces, each capable of displaying 16 colors. The first kind of 4-bit palettized surface is indexed into a true color palette table; the second kind is indexed into the primary surface indexed palette table. This second type of palette provides 50 percent compression and a layer of indirection to the sprites stored using it.

If these surfaces are to be created, the blitter must be able replace the palette during the blit operation. Therefore, while blitting from one palettized surface to another, the palette is ignored. Palette decoding is only done to true color surfaces, or when the 4-bit palette is an index to an index in the 8-bit palette. In all other cases, the indexed palette is the palette of the destination.

Raster operations for palettized surfaces are ignored. Changing the attached palette of a surface is a very quick operation. All three of these palettized surfaces should be supported as textures on 3D accelerated hardware.


Blitting To and From System Memory Surfaces

Some display cards have DMA hardware that allows them to efficiently blit to and from system memory surfaces. The DDCAPS structure has been expanded to allow drivers to report this capability. The following members have been added:

DWORD   dwSVBCaps

DWORD   dwSVBCKeyCaps

DWORD   dwSVBFXCaps

DWORD   dwSVBRops[DD_ROP_SPACE]

DWORD   dwVSBCaps

DWORD   dwVSBCKeyCaps

DWORD   dwVSBFXCaps

DWORD   dwVSBRops[DD_ROP_SPACE]

DWORD   dwSSBCaps

DWORD   dwSSBCKeyCaps

DWORD   dwSSBFXCaps

DWORD   dwSSBRops[DD_ROP_SPACE]

The SVB prefix indicates capabilities values that relate system memory to display memory blits. The VSB prefix indicates capabilities values that relate display memory to system memory blits. The SSB prefix indicates capabilities values that relate system memory to system memory blits.

The dwSVBCaps member corresponds to the dwCaps member except that it describes the blitting capabilities of the display driver for system memory to display memory blits. Likewise, the dwSVBCKeyCaps member corresponds to the dwCKeyCaps member and the dwSVBFXCaps member corresponds to the dwFXCaps member. The dwSVBRops member array describes the raster operations the driver supports for this type of blit.

These members are only valid if the DDCAPS_CANBLTSYSMEM flag is set in dwCaps, indicating that the driver is able to blit to or from system memory.

If the system memory surface being used by the hardware blitter is not locked, DirectDraw will automatically call the IDirectDrawSurface2::PageLock method on the surface to ensure that the memory has been locked.


Using DirectDrawPalette


Setting Palettes on Non-Primary Surfaces

In DirectX 2, palettes can be attached to any palettized surface (primary, back buffer, off-screen plain, or texture map). Only those palettes attached to primary surfaces will have any effect on the system palette. It is important to note that DirectDraw blits never perform color conversion—any palettes attached to the source or destination surface of a blit are ignored. Furthermore, the DirectDraw surface method, IDirectDrawSurface::GetDC, also ignores any DirectDrawPalette selected into the surface.

Non-primary surface palettes are intended for use by applications or Direct3D, or other 3D renderers.


Sharing Palettes

In DirectX 2, palettes can be shared between multiple surfaces. The same palette can be set on the front and back buffers of a flipping chain or shared between multiple texture surfaces. When a palette is attached to a surface with the IDirectDrawSurface::SetPalette method, the surface increments the reference count of that palette. When the reference count of the surface reaches 0, it will decrement the reference count of the attached palette. In addition, if a palette is detached from a surface by calling IDirectDrawSurface::SetPalette with a NULL palette interface pointer, the reference count of the surface's palette will be decremented.

Note

If the IDirectDrawSurface::SetPalette method is called several times consecutively for the same surface with the same palette, the reference count for the palette will be incremented only once. Subsequent calls will not affect the palette's reference count.


New Palette Types

In DirectX 2, DirectDraw supports 1-bit (2 entry), 2-bit (4 entry) and 4-bit (16 entry) palettes in addition to the 8-bit (256 entry) palettes supported by previous versions. Such palettes can be created by specifying one of the new palette capability flags: DDPCAPS_1BIT, DDPCAPS_2BIT, and DDPCAPS_4BIT. Matching capability flags have been added for surface pixel formats: DDPF_PALETTEINDEXED1, DDPF_PALETTEINDEXED2, and DDPF_PALETTEINDEXED4.

A palette can only be attached to a surface with a matching pixel format. For example, a 2 entry palette created with the DDPCAPS_1BIT flag can only be attached to a 1-bit surface created with the pixel format flag DDPF_PALETTEINDEXED1.

Furthermore, it is now possible to create indexed palettes. An indexed palette is one whose entries do not hold RGB colors, but rather integer indices into the array of PALETTEENTRYs of some target palette. An indexed palette's color table is an array of 2, 4, 16, or 256 bytes, where each byte is an index into some unspecified, destination palette.

To create an indexed palette, specify the palette capability flag DDPCAPS_8BITENTRIES when calling the IDirectDraw::CreatePalette method. For example, to create a 4-bit, indexed palette, specify DDPCAPS_4BIT | DDPCAPS_8BITENTRIES. When creating an indexed palette, a pointer to an array of bytes is passed rather than a pointer to an array of PALETTEENTRY structures. The pointer to the array of bytes must be cast to an LPPALETTEENTRY when calling IDirectDraw::CreatePalette.


Using DirectDrawClipper


Driver Independent Clippers

You can create clipper objects that are not directly owned by any particular DirectDraw object. Such clipper objects can be shared across multiple DirectDraw objects. Driver independent clipper objects are created with the new DirectDraw API function DirectDrawCreateClipper. This function can be called before any DirectDraw objects are created.

Because these clippers are not owned by any DirectDraw object, they are not automatically released when your application's objects are released. If not released explicitly by the application, these clippers will be released by DirectDraw when the application terminates.

You can still create clippers with the IDirectDraw::CreateClipper method. These DirectDrawClipper objects are automatically released when the DirectDraw object from which they were created is released.


Clip Lists

Clip lists are managed by DirectDraw using the DirectDrawClipper object. A DirectDrawClipper can be attached to any surface. A window handle can also be attached to a DirectDrawClipper, in which case DirectDraw will update the DirectDrawClipper clip list with the clip list from the window as it changes.

Although the clip list is visible from the DirectDraw HAL, DirectDraw will only call the HAL for blitting with rectangles that meet the clip list requirements. For instance, if the upper right rectangle of a surface was clipped and the application directed DirectDraw to blit the surface onto the primary surface, DirectDraw would have the HAL do two blits. The first blit would be the upper left hand corner of the surface and the second would be the bottom half of the surface.

The HAL considers the clip list for overlays only if the overlay hardware can support clipping and if destination color keying is not active. Most of today's hardware does not support occluded overlays unless they are being destination color keyed. This can be reported to DirectDraw as a driver capability, in which case the overlay will be turned off if it becomes occluded. Under these conditions, the HAL does not consider clip lists either.


Sharing Clippers

In DirectX 2, clippers can be shared between multiple surfaces. For example, the same clipper can be set on both the front and back buffers of a flipping chain. When a clipper is attached to a surface by using the IDirectDrawSurface::SetClipper method, the surface increments the reference count of that clipper. When the reference count of the surface reaches 0, it will decrement the reference count of the attached clipper. In addition, if a clipper is detached from a surface by calling IDirectDrawSurface::SetClipper with a NULL clipper interface pointer, the reference count of the surface's clipper will be decremented.

Note

If IDirectDrawSurface::SetClipper is called several times consecutively on the same surface for the same clipper, the reference count for the clipper will be incremented only once. Subsequent calls will not affect the clipper's reference count.


Creating Clipper Objects Using CoCreateInstance

DirectDrawClipper objects have full class-factory support for COM compliance. In addition to the standard DirectDrawCreateClipper function and IDirectDraw::CreateClipper method, you can also create a DirectDrawClipper object either by using CoGetClassObject to obtain a class factory and then calling CoCreateInstance, or by calling CoCreateInstance directly. The following example shows how to create a DirectDrawClipper object using CoCreateInstance and the IDirectDrawClipper::Initialize method.

ddrval = CoCreateInstance(&CLSID_DirectDrawClipper,

                                       NULL,

                                       CLSCTX_ALL,

                                       &IID_IDirectDrawClipper,

                                       &lpClipper);

if (!FAILED(ddrval))

ddrval = IDirectDrawClipper_Initialize(lpClipper,

       lpDD, 0UL);

CLSID_DirectDrawClipper is the class identifier of the DirectDrawClipper object class, IID_IDirectDrawClipper is the currently supported interface (which is the one you want), and lpClipper is the clipper object returned.

Clippers created by the class factory mechanism must be initialized with the IDirectDrawClipper::Initialize method before you can use the object. 0UL is the dwFlags parameter, which in this case has a value of 0 since no flags are currently supported. In the example shown here, lpDD is the DirectDraw object that owns the DirectDrawClipper object. However, you could supply a NULL instead, which would create an independent clipper (equivalent to creating a DirectDrawClipper object using the DirectDrawCreateClipper function).

Before closing the application, shut down COM using CoUninitialize, as shown below.

    CoUnitialize();


Support for 3D Surfaces


Texture Maps

In DirectX 2, texture maps can be allocated in system memory using the HEL. To allocate a texture map surface, specify the DDSCAPS_TEXTURE flag in the ddsCaps member of the surface description passed to the IDirectDraw::CreateSurface method.

A wide range of texture pixel formats are supported by the HEL. The following table describes these formats. The "Masks" column contains the red, green, blue, and alpha masks for each set of pixel format flags and bit depths.

Pixel Format Flags	Bit Depth	Masks
DDPF_RGB |	1	R: 0x00000000
DDPF_PALETTEINDEXED1		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	1	R: 0x00000000
DDPF_PALETTEINDEXED1 |		G: 0x00000000
DDPF_PALETTEINDEXEDTO8		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	2	R: 0x00000000
DDPF_PALETTEINDEXED2		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	2	R: 0x00000000
DDPF_PALETTEINDEXED2 |		G: 0x00000000
DDPF_PALETTEINDEXEDTO8		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	4	R: 0x00000000
DDPF_PALETTEINDEXED4		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	4	R: 0x00000000
DDPF_PALETTEINDEXED4 |		G: 0x00000000
DDPF_PALETTEINDEXEDTO8		B: 0x00000000
		A: 0x00000000
DDPF_RGB |	8	R: 0x00000000
DDPF_PALETTEINDEXED8		G: 0x00000000
		B: 0x00000000
		A: 0x00000000
DDPF_RGB	8	R: 0x000000E0
		G: 0x0000001C
		B: 0x00000003
		A: 0x00000000
DDPF_RGB |	16	R: 0x00000F00
DDPF_ALPHAPIXELS		G: 0x000000F0
		B: 0x0000000F
		A: 0x0000F000
DDPF_RGB	16	R: 0x0000F800
		G: 0x000007E0
		B: 0x0000001F
		A: 0x00000000
DDPF_RGB	16	R: 0x0000001F
		G: 0x000007E0
		B: 0x0000F800
		A: 0x00000000
DDPF_RGB	16	R: 0x00007C00
		G: 0x000003E0
		B: 0x0000001F
		A: 0x00000000
DDPF_RGB |	16	R: 0x00007C00
DDPF_ALPHAPIXELS		G: 0x000003E0
		B: 0x0000001F
		A: 0x00008000
DDPF_RGB	24	R: 0x00FF0000
		G: 0x0000FF00
		B: 0x000000FF
		A: 0x00000000
DDPF_RGB	24	R: 0x000000FF
		G: 0x0000FF00
		B: 0x00FF0000
		A: 0x00000000
DDPF_RGB	32	R: 0x00FF0000
		G: 0x0000FF00
		B: 0x000000FF
		A: 0x00000000
DDPF_RGB	32	R: 0x000000FF
		G: 0x0000FF00
		B: 0x00FF0000
		A: 0x00000000
DDPF_RGB |	32	R: 0x00FF0000
DDPF_ALPHAPIXELS		G: 0x0000FF00
		B: 0x000000FF
		A: 0xFF000000
DDPF_RGB |	32	R: 0x000000FF
DDPF_ALPHAPIXELS		G: 0x0000FF00
		B: 0x00FF0000
		A: 0xFF000000
The formats shown in the previous table are those that can be created by the HEL in system memory. The DirectDraw device driver for a 3D-accelerated display card is free to create textures of other formats in display memory. Such a driver should export the DDSCAPS_TEXTURE flag to indicate that it can create textures, and should be prepared to handle the DirectDraw HAL callback CanCreateSurface to verify that the surface description for a texture map is one the driver is prepared to create.


Mipmaps

In DirectX 2, DirectDraw supports mipmapped texture surfaces. A mipmap is a sequence of textures, each of which is a progressively lower resolution, prefiltered representation of the same image. Mipmapping is a computationally low-cost way of improving the quality of rendered textures. Each pre-filtered image, or level, in the mipmap is a power of two smaller than the previous level. In DirectDraw, mipmaps are represented as a chain of attached surfaces. The highest resolution texture is at the head of the chain and has, as an attachment, the next level of the mipmap which has, in turn, an attachment that is the next level in the mipmap, and so on down to the lowest resolution level of the mipmap.

To create a surface representing a single level of a mipmap, specify the DDSCAPS_MIPMAP flag in the surface description passed to the IDirectDraw::CreateSurface method. Because all mipmaps are also textures, the DDSCAPS_TEXTURE flag must also be specified. It is possible to create each level manually and build the chain with the IDirectDrawSurface::AddAttachedSurface method. However, the IDirectDraw::CreateSurface method can be used to build an entire mipmap chain in a single operation.

The following example demonstrates building a chain of five mipmap levels of sizes 256×256, 128×128, 64×64, 32×32 and 16×16.

        DDSURFACEDESC       ddsd;

        LPDIRECTDRAWSURFACE lpDDMipMap;

        ZeroMemory(&ddsd, sizeof(ddsd));

        ddsd.dwSize = sizeof(ddsd);

        ddsd.dwFlags = DDSD_CAPS | DDSD_MIPMAPCOUNT;

        ddsd.dwMipMapCount = 5;

        ddsd.ddsCaps.dwCaps = DDSCAPS_TEXTURE |

                DDSCAPS_MIPMAP | DDSCAPS_COMPLEX;

        ddsd.dwWidth = 256UL;

        ddsd.dwHeight = 256UL;

        ddres = lpDD->CreateSurface(&ddsd, &lpDDMipMap);

        if (FAILED(ddres))

                ...

You can omit the number of mipmaps levels, in which case the IDirectDraw::CreateSurface method will create a chain of surfaces, each a power of two smaller than the previous one, down to the smallest possible size. It is also possible to omit the width and height, in which case IDirectDraw::CreateSurface will create the number of levels you specify with a minimum level size of 1×1.

A chain of mipmap surfaces is traversed using the IDirectDrawSurface::GetAttachedSurface method, specifying the DDSCAPS_MIPMAP and DDSCAPS_TEXTURE capability flags. The following example traverses a mipmap chain from highest to lowest resolutions.

     LPDIRECTDRAWSURFACE lpDDLevel, lpDDNextLevel;

     DDSCAPS ddsCaps;

     lpDDLevel = lpDDMipMap;

     lpDDLevel->AddRef();

     ddsCaps.dwCaps = DDSCAPS_TEXTURE | DDSCAPS_MIPMAP;

     ddres = DD_OK;

     while (ddres == DD_OK)

     {

             // Process this level

             ...

             ddres = lpDDLevel->GetAttachedSurface(

                     &ddsCaps, &lpDDNextLevel);

             lpDDLevel->Release();

             lpDDLevel = lpDDNextLevel;

     }

     if ((ddres != DD_OK) && (ddres != DDERR_NOTFOUND))

             ...

You can also build flippable chains of mipmaps. In this scenario, each mipmap level has an associated chain of back buffer texture surfaces. Each back buffer texture is attached to one level of the mipmap. Only the front buffer in the chain has the DDSCAPS_MIPMAP flag set; the others are simply texture maps (DDSCAPS_TEXTURE). A mipmap level can have two attached texture maps, one with DDSCAPS_MIPMAP set, which is the next level in the mipmap chain, and one with the DDSCAPS_BACKBUFFER flag set, which is the back buffer of the flippable chain. All the surfaces in each flippable chain must be of the same size.

It is not possible to build such a surface arrangement with a single call to the IDirectDraw::CreateSurface method. To construct a flippable mipmap, either build a complex mipmap chain and manually attach back buffers with the IDirectDrawSurface::AddAttachedSurface method or create a sequence of flippable chains and build the mipmap with IDirectDrawSurface::AddAttachedSurface.

Note

Blit operations apply to only a single level in the mipmap chain. To blit an entire chain of mipmaps, each level must be blitted separately.

The IDirectDrawSurface::Flip method will flip all the levels of a mipmap from the level supplied to the lowest level in the map. A destination surface can also be provided, in which case all levels in the mipmap will flip to the back buffer in their flippable chain. This back buffer matches the supplied override. For example, if the third back buffer in the top-level flippable chain is supplied, all levels in the mipmap will flip to their third back buffer.

The number of levels in a mipmap chain is stored explicitly. When the surface description of a mipmap is obtained (using IDirectDrawSurface::Lock or IDirectDrawSurface::GetSurfaceDesc), the dwMipMapCount member will contain the number of levels in a mipmap, including the top level. For levels other than the top level in the map, dwMipMapCount will specify the number of levels from that map to the smallest map in the chain.


Z-Buffers

In DirectX 2, the DirectDraw HEL can create z-buffers for use by Direct3D or other 3D rendering software. The HEL supports both 16- and 32-bit z-buffers. The DirectDraw device driver for a 3D-accelerated display card can permit the creation of z-buffers in display memory by exporting the surface capability DDSCAPS_ZBUFFER. It should also specify the z-buffer depths it supports using the dwZBufferBitDepths member of the DDCAPS structure.

Z-buffers can be cleared using the IDirectDrawSurface::Blt method. A new DirectDraw blit flag (DDBLT_DEPTHFILL) has been defined to indicate that the blit clears z-buffers. If this flag is specified, the DDBLTFX structure passed to the IDirectDrawSurface::Blt method should have its dwFillDepth member set to the required z-depth. If the DirectDraw device driver for a 3D-accelerated display card is designed to provide support for z-buffer clearing in hardware, it should export the capability flag DDCAPS_BLTDEPTHFILL and should have code to handle DDBLT_DEPTHFILL blits. The destination surface of a depth fill blit must be a z-buffer.

Note

The actual interpretation of a depth value is 3D-renderer specific.


Direct3D Integration with DirectDraw


Direct3D Driver Interface

DirectDraw presents a single, unified object to you as an application programmer. This object encapsulates both the DirectDraw and Direct3D states. The DirectDraw driver COM interfaces (IID_IDirectDraw or IID_IDirectDraw2) and the Direct3D driver COM interface (IID_IDirect3D) all allow you to communicate with the same underlying object. Therefore, no Direct3D object is created. Rather, a Direct3D interface to the DirectDraw object is obtained. This is achieved using the standard COM QueryInterface method.

The following example demonstrates how to create the DirectDraw object and obtain a Direct3D interface for communicating with that object.

        LPDIRECTDRAW lpDD;

        LPDIRECT3D   lpD3D;

        ddres = DirectDrawCreate(NULL, &lpDD, NULL);

        if (FAILED(ddres))

                ...

        ddres = lpDD->QueryInterface(IID_IDirect3D,

                &lpD3D);

        if (FAILED(ddres))

                ...

The code shown in the previous example creates a single object and obtains two interfaces to that object. Therefore, the object's reference count after the IDirectDraw::QueryInterface method call is two. The important implication of this is that the lifetime of the Direct3D driver state is the same as that of the DirectDraw object. Releasing the Direct3D interface does not destroy the Direct3D driver state. That state is not destroyed until all references, whether DirectDraw or Direct3D, to that object have been released. Hence, if you release a Direct3D interface while holding a reference to a DirectDraw driver interface, and re-query the Direct3D interface, the Direct3D state will be preserved.


Direct3D Device Interface

As with the object, there is no distinct Direct3D device object. A Direct3D device is simply an interface for communicating with a DirectDraw surface used as a 3D rendering target. The following example creates a Direct3D device interface to a DirectDrawSurface object.

        LPDIRECTDRAWSURFACE lpDDSurface;

        LPDIRECT3DDEVICE    lpD3DDevice;

        ddres = lpDD->CreateSurface(&ddsd, &lpDDSurface,

                NULL);

        if (FAILED(ddres))

                ...

        ddres = lpDDSurface->QueryInterface(lpGuid,

                &lpD3DDevice);

        if (FAILED(ddres))

                ...

The same rules for reference counts and state lifetimes for objects (see Direct3D Driver Interface) apply to DirectDraw surfaces and Direct3D devices. Additionally, multiple, distinct Direct3D device interfaces can be obtained for the same DirectDraw surface. It is possible, therefore, that a single DirectDraw surface could be the target for both a ramp-based device and an RGB-based device.


Direct3D Texture Interface

Direct3D textures are not distinct object types, but rather another interface of DirectDrawSurface objects. The following example obtains a Direct3D texture interface from a DirectDrawSurface object.

        LPDIRECTDRAWSURFACE lpDDSurface;

        LPDIRECT3DTEXTURE   lpD3DTexture;

        ddres = lpDD->CreateSurface(&ddsd, &lpDDSurface,

                NULL);

        if (FAILED(ddres))

                ...

        ddres = lpDDSurface->QueryInterface(

                 IID_IDirect3DTexture, &lpD3DTexture);

        if (FAILED(ddres))

                ...

The same rules for reference counts and state lifetimes discussed for objects (see Direct3D Driver Interface) apply to Direct3D textures. It is possible to use a single DirectDrawSurface as both a rendering target and a texture.


DirectDraw HEL and Direct3D

The DirectDraw HEL has been enhanced to support the creation of texture, mipmap, and z-buffer surfaces. Furthermore, due to the tight integration of DirectDraw and Direct3D, a DirectDraw-enabled system will always provide Direct3D support (in software emulation, at least). Hence, the DirectDraw HEL exports the DDSCAPS_3DDEVICE flag to indicate that a surface can be used for 3D rendering. A DirectDraw driver for a hardware-accelerated 3D display card should export this capability to indicate the presence of hardware-accelerated 3D.


Reference


Functions

Two of the DirectDraw functions initiate control of display memory through the IDirectDraw interface. The first function, DirectDrawCreate, creates an instance of a DirectDraw object that represents a specific piece of display hardware. The second function, DirectDrawEnumerate, obtains a list of all DirectDraw objects installed on a system. These functions are the mechanisms DirectDraw uses to support multiple pieces of display hardware. To support multiple display devices, your application need only select a specific DirectDraw object and instantiate it.

The third function, DirectDrawCreateClipper, creates an instance of a DirectDraw clipper that is not directly owned by a DirectDraw object, and can be shared across multiple driver objects.


DirectDrawCreate

Creates an instance of a DirectDraw object.

HRESULT DirectDrawCreate(
GUID FAR * lpGUID,
LPDIRECTDRAW FAR * lplpDD,
IUnknown FAR * pUnkOuter
);

Parameters

lpGUID

Address of the GUID that represents the driver to be created. NULL is always the active display driver.

lplpDD

Address of a pointer that will be initialized with a valid DirectDraw pointer if the call succeeds.

pUnkOuter

Allows for future compatibility with COM aggregation features. Presently, however, DirectDrawCreate will return an error if this parameter is anything but NULL.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_DIRECTDRAWALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDDIRECTDRAWGUID
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW
DDERR_OUTOFMEMORY
Remarks

This function attempts to initialize a DirectDraw object, then sets a pointer to the object if successful. Calling the IDirectDraw::GetCaps method immediately after initialization is advised to determine to what extent this object is hardware accelerated.


DirectDrawCreateClipper

Creates an instance of a DirectDrawClipper object not associated with a DirectDraw object.

To create a DirectDrawClipper object owned by a specific DirectDraw object, use the IDirectDraw::CreateClipper method.

HRESULT DirectDrawCreateClipper(
DWORD dwFlags,
LPDIRECTDRAWCLIPPER FAR *lplpDDClipper,
IUnknown FAR *pUnkOuter
);

Parameters

dwFlags

This parameter is not currently used and must be set to 0.

lplpDDClipper

Address of a pointer to be filled in with the address of the new DirectDrawClipper object.

pUnkOuter

Allows for future compatibility with COM aggregation features. Presently, however, DirectDrawCreateClipper will return an error if this parameter is anything but NULL.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDPARAMS	DDERR_OUTOFMEMORY
Remarks

This function can be called before any DirectDraw objects are created. Because these clippers are not owned by any DirectDraw object, they are not automatically released when an application's objects are released. If not released explicitly by the application, such clippers will be released by DirectDraw when the application terminates.

See Also

 IDirectDraw::CreateClipper


DirectDrawEnumerate

Enumerates the DirectDraw objects installed on the system. The NULL GUID entry always identifies the primary display device shared with GDI.

HRESULT DirectDrawEnumerate(
LPDDENUMCALLBACK lpCallback,
LPVOID lpContext
);

Parameters

lpCallback

Address of a Callback function that will be called with a description of each DirectDraw-enabled HAL installed in the system.

lpContext

Address of a caller-defined context that will be passed to the enumeration callback each time it is called.

Return Values

Returns DD_OK if successful, or DDERR_INVALIDPARAMS otherwise.


Callback Functions

Most of the functionality of DirectDraw is provided by the methods of its Component Object Model (COM) interfaces. This section lists the callback functions that are not implemented as part of a COM interface.


Callback

Application-defined callback procedure for the DirectDrawEnumerate function.

BOOL WINAPI lpCallback(
GUID FAR * lpGUID,
LPSTR lpDriverDescription,
LPSTR lpDriverName,
LPVOID lpContext
);

Parameters

lpGUID

Address of the unique identifier of the DirectDraw object.

lpDriverDescription

Address of a string containing the driver description.

lpDriverName

Address of a string containing the driver name.

lpContext

Address of a caller-defined structure that will be passed to the callback function each time the function is invoked.

Return Values

Returns DDENUMRET_OK to continue the enumeration, or DDENUMRET_CANCEL to stop it.


EnumCallback

Application-defined callback procedure for the IDirectDraw::EnumSurfaces method.

HRESULT WINAPI lpEnumCallback(
LPDIRECTDRAWSURFACE lpDDSurface,
LPDDSURFACEDESC lpDDSurfaceDesc,
LPVOID lpContext
);

Parameters

lpDDSurface

Address of the DirectDrawSurface currently being enumerated if it is an existing surface (DDENUMSURFACES_DOESEXIST). The value will be NULL if a potential surface is being enumerated (DDENUMSURFACES_CANBECREATED).

lpDDSurfaceDesc

Address of the DDSURFACEDESC structure for the existing or potential surface that most closely matches the requested surface.

lpContext

Address of the caller-defined structure passed to the member every time it is invoked.

Return Values

Returns DDENUMRET_OK to continue the enumeration, or DDENUMRET_CANCEL to stop it.


EnumModesCallback

Application-defined callback procedure for the IDirectDraw2::EnumDisplayModes method.

HRESULT WINAPI lpEnumModesCallback(
LPDDSURFACEDESC lpDDSurfaceDesc,
LPVOID lpContext
);

Parameters

lpDDSurfaceDesc

Address of the DDSURFACEDESC structure that provides the monitor frequency and the mode that can be created. This data is read-only.

lpContext

Address of a caller-defined structure that will be passed to the callback function each time the function is invoked.

Return Values

Returns DDENUMRET_OK to continue the enumeration, or DDENUMRET_CANCEL to stop it.


EnumSurfacesCallback

Application-defined callback procedure for the IDirectDrawSurface::EnumAttachedSurfaces method.

HRESULT WINAPI lpEnumSurfacesCallback(
LPDIRECTDRAWSURFACE lpDDSurface,
LPDDSURFACEDESC lpDDSurfaceDesc,
LPVOID lpContext
);

Parameters

lpDDSurface

Address of the surface attached to this surface.

lpDDSurfaceDesc

Address of a DDSURFACEDESC structure that describes the attached surface.

lpContext

Address of the user-defined context specified by the user.

Return Values

Returns DDENUMRET_OK to continue the enumeration, or DDENUMRET_CANCEL to stop it.


fnCallback

Application-defined callback procedure for the IDirectDrawSurface::EnumOverlayZOrders method.

HRESULT WINAPI lpfnCallback(
LPDIRECTDRAWSURFACE lpDDSurface,
LPVOID lpContext
);

Parameters

lpDDSurface

Address of the surface being overlaid on this surface.

lpContext

Address of the user-defined context specified by the user.

Return Values

Returns DDENUMRET_OK to continue the enumeration, or DDENUMRET_CANCEL to stop it.


IDirectDraw Interface

DirectDraw objects represent the display hardware. An object is hardware-accelerated if the display device for which it was instantiated has hardware acceleration. Three types of objects can be created by a DirectDraw object: DirectDrawSurface, DirectDrawPalette, and DirectDrawClipper.

More than one DirectDraw object can be instantiated at a time. The simplest example of this would be using two monitors on a Windows 95 system. Although Windows 95 does not support dual monitors natively, it is possible to write a DirectDraw HAL for each display device. The display device Windows 95 and GDI recognizes is the one that will be used when the default DirectDraw object is instantiated. The display device that Windows 95 and GDI does not recognize can be addressed by another, independent DirectDraw object that must be created using the second display device's identifying GUID. This GUID can be obtained through the DirectDrawEnumerate function.

The DirectDraw object manages all of the objects it creates. It controls the default palette if the primary surface is in 8 bpp mode, the default color key values, and the hardware display mode. It tracks what resources have been allocated and what resources remain to be allocated.

Changing the display mode is an important piece of DirectDraw functionality. The display mode resolution can be changed at any time unless another application has obtained exclusive access to DirectDraw. The pixel depth of the display mode can only be changed if the application requesting the change has obtained exclusive access to the DirectDraw object. All DirectDrawSurface objects lose surface memory and become inoperative when the mode is changed. A surface's memory must be reallocated using the IDirectDrawSurface::Restore method.


IDirectDraw Interface Method Groups

Applications use the methods of the IDirectDraw interface to create DirectDraw objects and work with system-level variables. The methods can be organized into the following groups:

Allocating memory	Compact
	Initialize
Creating objects	CreateClipper
	CreatePalette
	CreateSurface
Device capabilities	GetCaps
Display modes	EnumDisplayModes
	GetDisplayMode
	GetMonitorFrequency
	RestoreDisplayMode
	SetDisplayMode
Display status	GetScanLine
	GetVerticalBlankStatus
IUnknown	AddRef
	QueryInterface
	Release
Miscellaneous	GetAvailableVidMem
	GetFourCCCodes
	WaitForVerticalBlank
Setting behavior	SetCooperativeLevel
Surfaces	DuplicateSurface
	EnumSurfaces
	FlipToGDISurface
	GetGDISurface
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the DirectDraw object without affecting the functionality of the original interface.


IDirectDraw::AddRef

Increases the reference count of the DirectDraw object by 1. This method is part of the IUnknown interface inherited by DirectDraw.

ULONG AddRef( );

Parameters

Return Values

Returns the new reference count of the object.

Remarks

When the DirectDraw object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirectDraw::Release method to decrease the reference count of the object by 1.

See Also

 IDirectDraw::Initialize, IDirectDraw::QueryInterface, IDirectDraw::Release


IDirectDraw::Compact

At present this method is only a stub; it has not yet been implemented.

HRESULT Compact( );

Parameters

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_SURFACEBUSY	DDERR_NOEXCLUSIVEMODE
Remarks

This method moves all of the pieces of surface memory on the display card to a contiguous block to make the largest single amount of free memory available. This call will fail if any operations are in progress.

The application calling this method must have its cooperative level set to exclusive.


IDirectDraw::CreateClipper

Creates a DirectDrawClipper object.

HRESULT CreateClipper(
DWORD dwFlags,
LPDIRECTDRAWCLIPPER FAR * lplpDDClipper,
IUnknown FAR * pUnkOuter
);

Parameters

dwFlags

This parameter is not currently used and must be set to 0.

lplpDDClipper

Address of a pointer to be filled in with the address of the new DirectDrawClipper object if the IDirectDraw::CreateClipper method is successful.

pUnkOuter

Allows for future compatibility with COM aggregation features. Presently, however, IDirectDraw::CreateClipper will return an error if this parameter is anything but NULL.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY	DDERR_NOCOOPERATIVELEVELSET
Remarks

The DirectDrawClipper object can be attached to a DirectDrawSurface and used during IDirectDrawSurface::Blt, IDirectDrawSurface::BltBatch, and IDirectDrawSurface::UpdateOverlay operations.

To create a DirectDrawClipper object that is not owned by a specific DirectDraw object, use the DirectDrawCreateClipper function.

See Also

 IDirectDrawSurface::GetClipper, IDirectDrawSurface::SetClipper


IDirectDraw::CreatePalette

Creates a DirectDrawPalette object for this DirectDraw object.

HRESULT CreatePalette(
DWORD dwFlags,
LPPALETTEENTRY lpColorTable,
LPDIRECTDRAWPALETTE FAR * lplpDDPalette,
IUnknown FAR * pUnkOuter
);

Parameters

dwFlags

DDPCAPS_1BIT

	Indicates the index is 1 bit. There are two entries in the palette table.
DDPCAPS_2BIT

	Indicates the index is 2 bits. There are four entries in the palette table.
DDPCAPS_4BIT

	Indicates the index is 4 bits. There are sixteen entries in the palette table.
DDPCAPS_8BITENTRIES

	An index to an 8-bit color index. This flag is only valid when used with the DDPCAPS_1BIT, DDPCAPS_2BIT, or DDPCAPS_4BIT flag, and when the target surface is in 8-bpp. Each color entry is one byte long and is an index to a destination surface's 8-bpp palette.
DDPCAPS_8BIT

	Indicates the index is 8 bits. There are 256 entries in the palette table.
DDPCAPS_ALLOW256

	Indicates this palette can have all 256 entries defined.
lpColorTable

Address of an array of 2, 4, 16, or 256 PALETTEENTRY structures that will initialize this DirectDrawPalette object.

lplpDDPalette

Address of a pointer to be filled in with the address of the new DirectDrawPalette object if the IDirectDraw::CreatePalette method is successful.

pUnkOuter

Allows for future compatibility with COM aggregation features. Presently, however, IDirectDraw::CreatePalette returns an error if this parameter is anything but NULL.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_NOEXCLUSIVEMODE
DDERR_INVALIDPARAMS	DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFCAPS	DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED


IDirectDraw::CreateSurface

Creates a DirectDrawSurface object for this DirectDraw object.

HRESULT CreateSurface(
LPDDSURFACEDESC lpDDSurfaceDesc,
LPDIRECTDRAWSURFACE FAR * lplpDDSurface,
IUnknown FAR * pUnkOuter
);

Parameters

lpSurfaceDesc

Address of the DDSURFACEDESC structure that describes the requested surface.

lplpDDSurface

Address of a pointer to be initialized with a valid DirectDrawSurface pointer if the call succeeds.

pUnkOuter

Allows for future compatibility with COM aggregation features. Presently, however, IDirectDraw::CreateSurface will return an error if this parameter is anything but NULL.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_NOALPHAHW
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_UNSUPPORTEDMODE
Remarks

The DirectDrawSurface object represents a surface (pixel memory) that usually resides in the display card memory, but can exist in system memory if display memory is exhausted or if it is explicitly requested. If the hardware cannot support the capabilities requested or if it previously allocated those resources to another DirectDrawSurface object, the call to IDirectDraw::CreateSurface will fail.

This method usually creates one DirectDrawSurface object. If the DDSCAPS_FLIP flag in the dwCaps member of the DDSCAPS structure is set, IDirectDraw::CreateSurface will create several DirectDrawSurface objects, referred to collectively as a complex structure. The additional surfaces created are also referred to as implicit surfaces.

DirectDraw does not permit the creation of display memory surfaces wider than the primary surface.

The following are examples of valid surface creation scenarios:

Scenario 1

The primary surface is the surface currently visible to the user. When you create a primary surface, you are actually creating a DirectDrawSurface object to access an already existing surface being used by GDI. Consequently, while all other types of surfaces require dwHeight and dwWidth values, a primary surface must not have them specified, even if you know they are the same dimensions as the existing surface.

The members of the DDSURFACEDESC structure (ddsd below) relevant to the creation of the primary surface are then filled in.

    DDSURFACEDESC    ddsd;

    ddsd.dwSize = sizeof( ddsd );

    //Tell DDRAW which fields are valid

    ddsd.dwFlags = DDSD_CAPS;

    //Ask for a primary surface

    ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;

Scenario 2

Create a simple off-screen surface of the type that might be used to cache bitmaps that will later be composed with the blitter. A height and width are required for all surfaces except primary surfaces. The members in the DDSURFACEDESC structure (ddsd below) relevant to the creation of a simple off-screen surface are then filled in.

    DDSURFACEDESC    ddsd;

    ddsd.dwSize = sizeof( ddsd );

    //Tell DDRAW which fields are valid

    ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH;

    //Ask for a simple off-screen surface, sized

    //100 by 100 pixels

    ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;

    dwHeight = 100;

    dwWidth = 100;

DirectDraw creates this surface in display memory unless it will not fit, in which case the surface is created in system memory. If the surface must be created in one or the other, use the flags DDSCAPS_SYSTEMMEMORY or DDSCAPS_VIDEOMEMORY in dwCaps to specify system memory or display memory, respectively. An error is returned if the surface cannot be created in the specified location.

DirectDraw also allows for the creation of complex surfaces. A complex surface is a set of surfaces created with a single call to the IDirectDraw::CreateSurface method. If the DDSCAPS_COMPLEX flag is set in the IDirectDraw::CreateSurface call, one or more implicit surfaces will be created by DirectDraw in addition to the surface explicitly specified. Complex surfaces are managed as a single surface—a single call to the IDirectDraw::Release method will release all surfaces in the structure, and a single call to the IDirectDrawSurface::Restore method will restore them all.

Scenario 3

One of the most useful complex surfaces you can specify is composed of a primary surface and one or more back buffers that form a surface flipping environment. The members in the DDSURFACEDESC structure (ddsd below) relevant to complex surface creation are filled in to describe a flipping surface that has one back buffer.

    DDSURFACEDESC      ddsd;

    ddsd.dwSize = sizeof( ddsd );

    //Tell DDRAW which fields are valid

    ddsd.dwFlags = DDSD_CAPS | DDSD_BACKBUFFERCOUNT;

    //Ask for a primary surface with a single

    //back buffer

    ddsd.ddsCaps.dwCaps = DDSCAPS_COMPLEX | DDSCAPS_FLIP |

    DDSCAPS_PRIMARYSURFACE;

    ddsd.dwBackBufferCount = 1;

The previous statements construct a double-buffered flipping environment—a single call to the IDirectDrawSurface::Flip method exchanges the surface memory of the primary surface and the back buffer. If a BackBufferCount of 2 is specified, two back buffers are created, and each call to IDirectDrawSurface::Flip rotates the surfaces in a circular pattern, providing a triple-buffered flipping environment.


IDirectDraw::DuplicateSurface

Duplicates a DirectDrawSurface.

HRESULT DuplicateSurface(
LPDIRECTDRAWSURFACE lpDDSurface,
LPLPDIRECTDRAWSURFACE FAR * lplpDupDDSurface
);

Parameters

lpDDSurface

Address of the DirectDrawSurface structure to be duplicated.

lplpDupDDSurface

Address of the DirectDrawSurface pointer that points to the newly created duplicate DirectDrawSurface structure.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_CANTDUPLICATE	DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS	DDERR_OUTOFMEMORY
DDERR_SURFACELOST
Remarks

This method creates a new DirectDrawSurface object that points to the same surface memory as an existing DirectDrawSurface object. This duplicate can be used just like the original object. The surface memory is released after the last object referencing it is released. A primary surface, 3D surface, or implicitly created surface cannot be duplicated.


IDirectDraw2::EnumDisplayModes

Enumerates all of the display modes the hardware exposes through the DirectDraw object that are compatible with a provided surface description. If NULL is passed for the surface description, all exposed modes will be enumerated.

HRESULT EnumDisplayModes(
DWORD dwFlags,
LPDDSURFACEDESC lpDDSurfaceDesc,
LPVOID lpContext,
LPDDENUMMODESCALLBACK lpEnumModesCallback
);

Parameters

dwFlags

DDEDM_REFRESHRATES

	Enumerate modes with different refresh rates. IDirectDraw2::EnumDisplayModes guarantees that a particular mode will be enumerated only once. This flag specifies whether the refresh rate is taken into account when determining if a mode is unique.
lpDDSurfaceDesc

Address of a DDSURFACEDESC structure that will be checked against available modes. If the value of this parameter is NULL, all modes will be enumerated.

lpContext

Address of a caller-defined structure that will be passed to each enumeration member.

lpEnumModesCallback

Address of the EnumModesCallback function the enumeration procedure will call every time a match is found.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
Remarks

This method enumerates the dwRefreshRate member in the DDSURFACEDESC structure; the IDirectDraw::EnumDisplayModes method does not contain this capability. If you use the IDirectDraw2::SetDisplayMode method to set the refresh rate of a new mode, you must use IDirectDraw2::EnumDisplayModes to enumerate the dwRefreshRate member.

To ensure COM compliance, this method is not part of the IDirectDraw interface, but belongs to the IDirectDraw2 interface. To use this method, you must first query for the IDirectDraw2 interface. For more information, see IDirectDraw2 Interface.

The information in the dwFlags and comment sections has been changed since the DirectX 2 SDK was released. For a complete list of new information, see New Information.

See Also

 IDirectDraw::GetDisplayMode, IDirectDraw2::SetDisplayMode, IDirectDraw::RestoreDisplayMode


IDirectDraw::EnumSurfaces

Enumerates all of the existing or possible surfaces that meet the search criterion specified.

HRESULT EnumSurfaces(
DWORD dwFlags,
LPDDSURFACEDESC lpDDSD,
LPVOID lpContext,
LPDDENUMSURFACESCALLBACk lpEnumCallback
);

Parameters

dwFlags

DDENUMSURFACES_ALL

	Enumerates all of the surfaces that meet the search criterion.
DDENUMSURFACES_MATCH

	Searches for any surface that matches the surface description.
DDENUMSURFACES_NOMATCH

	Searches for any surface that does not match the surface description.
DDENUMSURFACES_CANBECREATED

	Enumerates the first surface that can be created that meets the search criterion.
DDENUMSURFACES_DOESEXIST

	Enumerates the already existing surfaces that meet the search criterion.
lplpDDSD

Address of a DDSURFACEDESC structure that defines the surface of interest.

lpContext

Address of a caller-defined structure to be passed to each enumeration member.

lpEnumCallback

Address of the EnumCallback function the enumeration procedure will call every time a match is found.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
Remarks

If the DDENUMSURFACES_CANBECREATED flag is set, this method will attempt to temporarily create a surface that meets the criteria. Note that as a surface is enumerated, its reference count is increased—if you are not going to use the surface, use IDirectDraw::Release to release the surface after each enumeration.


IDirectDraw::FlipToGDISurface

Makes the surface that GDI writes to the primary surface.

HRESULT FlipToGDISurface( );

Parameters

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_NOTFOUND
Remarks

This method can be called at the end of a page flipping application to ensure that the display memory that GDI is writing to is visible to the user.

See Also

 IDirectDraw::GetGDISurface


IDirectDraw2::GetAvailableVidMem

Gets the total amount of display memory available and the amount of display memory currently free. If NULL is passed to either lpdwTotal or lpdwFree, the value for that parameter is not returned.

HRESULT GetAvailableVidMem(
LPDDSCAPS lpDDSCaps,
LPDWORD lpdwTotal,
LPDWORD lpdwFree
);

Parameters

lpDDSCaps

Address of a DDSCAPS structure that contains the hardware capabilities of the surface.

lpdwTotal

Address of a doubleword to be filled in with the total amount of display memory available.

lpdwFree

Address of a doubleword to be filled in with the amount of display memory currently free.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_NODIRECTDRAWHW
DDERR_INVALIDPARAMS	DDERR_INVALIDCAPS
Remarks

The following C++ example demonstrates using IDirectDraw2::GetAvailableVidMem to determine both the total and free display memory available for texture map surfaces:

        LPDIRECTDRAW2 lpDD2;

        DDSCAPS       ddsCaps;

        DWORD         dwTotal;

        DWORD         dwFree;

        ddres = lpDD->QueryInterface(IID_IDirectDraw2,

        &lpDD2); if (FAILED(ddres))

                         ...

        ddsCaps.dwCaps = DDSCAPS_TEXTURE;

        ddres = lpDD2->GetAvailableVidMem(&ddsCaps,

        &dwTotal, &dwFree);

        if (FAILED(ddres))

                ...

This method only gives a snapshot of the current display memory state. The amount of free display memory is subject to change as surfaces are created and released. Therefore, the free memory value should only be used as a rough guide. In addition, a particular display adapter card may make no distinction between two different memory types. For example, it may use the same portion of display memory to store z-buffers and textures. Hence, allocating one type of surface (for example, a z-buffer) may affect the amount of display memory available for another type of surface (for example, textures). Therefore, it is best to first allocate an application's fixed resources (such as front, back and z-buffers) before determining how much memory is available for dynamic use (such as texture mapping).

To ensure COM compliance, this method is not a member of the IDirectDraw interface, but is part of the IDirectDraw2 interface. To use this method, you must first query for the IDirectDraw2 interface. For more information, see IDirectDraw2 Interface.


IDirectDraw::GetCaps

Fills in the raw, not remaining, capabilities of the device driver for the hardware and the hardware emulation layer (HEL).

HRESULT GetCaps(
LPDDCAPS lpDDDriverCaps,
LPDDCAPS lpDDHELCaps
);

Parameters

lpDDDriverCaps

Address of a DDCAPS structure to be filled in with the capabilities of the hardware, as reported by the device driver.

lpDDHELCaps

Address of a DDCAPS structure to be filled in with the capabilities of the HEL.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
See Also

 DDCAPS


IDirectDraw::GetDisplayMode

Returns the current display mode.

HRESULT GetDisplayMode(
LPDDSURFACEDESC lpDDSurfaceDesc
);

Parameters

lpDDSurfaceDesc

Address of a DDSURFACEDESC structure to be filled in with a description of the surface.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_UNSUPPORTEDMODE
Remarks

An application should not save the information returned by IDirectDraw::GetDisplayMode to restore the display mode on clean up. The mode restoration on clean up should be performed with IDirectDraw::RestoreDisplayMode, thereby avoiding mode setting conflicts that could arise in a multiprocess environment.

See Also

 IDirectDraw2::SetDisplayMode, IDirectDraw::RestoreDisplayMode, IDirectDraw2::EnumDisplayModes


IDirectDraw::GetFourCCCodes

Returns the FourCCCodes supported by the DirectDraw object. IDirectDraw::GetFourCCCodes can also return the number of codes supported.

HRESULT GetFourCCCodes(
LPDWORD lpNumCodes,
LPDWORD lpCodes
);

Parameters

lpNumCodes

Address of a doubleword that contains the number of entries the lpCodes array can hold. If the number of entries is too small to accommodate all the codes, lpNumCodes will be set to the required number and the lpCodes array will be filled with all that will fit.

lpCodes

Address of an array of doublewords to be filled in with FourCC codes supported by this DirectDraw object. If NULL is passed, lpNumCodes will be set to the number of supported FourCC codes and the method will return.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS


IDirectDraw::GetGDISurface

Returns the DirectDrawSurface object that currently represents the surface memory GDI is treating as the primary surface.

HRESULT GetGDISurface(
LPDIRECTDRAWSURFACE FAR * lplpGDIDDSSurface
);

Parameters

lplpGDIDDSSurface

Address of a DirectDrawSurface pointer to the DirectDrawSurface object that currently controls GDI's primary surface memory.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_NOTFOUND
See Also

 IDirectDraw::FlipToGDISurface


IDirectDraw::GetMonitorFrequency

Returns the frequency of the monitor being driven by the DirectDraw object. The frequency value is returned in Hz multiplied by 100. For example, 60Hz is returned as 6000.

HRESULT GetMonitorFrequency(
LPDWORD lpdwFrequency
);

Parameters

lpdwFrequency

Address of the doubleword to be filled in with the monitor frequency.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED


IDirectDraw::GetScanLine

Returns the scan line that is currently being drawn on the monitor.

HRESULT GetScanLine(
LPDWORD lpdwScanLine
);

Parameters

lpdwScanLine

Address of the doubleword to contain the scan line the display is currently on.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED	DDERR_VERTICALBLANKINPROGRESS
See Also

 IDirectDraw::GetVerticalBlankStatus, IDirectDraw::WaitForVerticalBlank


IDirectDraw::GetVerticalBlankStatus

Returns the status of the vertical blank.

HRESULT GetVerticalBlankStatus(
LPBOOL lpbIsInVB
);

Parameters

lpbIsInVB

Address of the BOOL to be filled in with the status of the vertical blank.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
Remarks

This method will set the passed BOOL to TRUE if a vertical blank is occurring and to FALSE otherwise. To synchronize with the vertical blank, use the IDirectDraw::WaitForVerticalBlank method.

See Also

 IDirectDraw::GetScanLine, IDirectDraw::WaitForVerticalBlank


IDirectDraw::Initialize

Initializes the DirectDraw object that was created using the CoCreateInstance OLE function.

HRESULT Initialize(
GUID FAR *lpGUID
);

Parameters

lpGUID

Address of the GUID used as the interface pointer.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_ALREADYINITIALIZED
DDERR_DIRECTDRAWALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDDIRECTDRAWGUID
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NODIREDCTDRAWHW
DDERR_NODIRECTDRAWSUPPORT
DDERR_OUTOFMEMORY
Remarks

If the DirectDrawCreate function was used to create the DirectDraw object, this method will return DDERR_ALREADYINITIALIZED. If IDirectDraw::Initialize is not called when using CoCreateInstance to create the DirectDraw object, any method that is called afterward will return DDERR_NOTINITIALIZED.

This information for this method is new since the DirectX 2 SDK was released. For a complete list of new information, see New Information.

See Also

 IDirectDraw::AddRef, IDirectDraw::QueryInterface, IDirectDraw::Release


IDirectDraw::QueryInterface

Determines if the DirectDraw object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by DirectDraw.

HRESULT QueryInterface(
REFIID riid,
LPVOID FAR * ppvObj
);

Parameters

riid

Reference identifier of the interface being requested.

ppvObj

Address of a pointer to be filled with the interface pointer if the query is successful.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirectDraw::QueryInterface method allows DirectDraw objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.

See Also

 IDirectDraw::AddRef, IDirectDraw::Initialize, IDirectDraw::Release


IDirectDraw::Release

Decreases the reference count of the DirectDraw object by 1. This method is part of the IUnknown interface inherited by DirectDraw.

ULONG Release( );

Parameters

Return Values

Returns the new reference count of the object.

Remarks

The DirectDraw object deallocates itself when its reference count reaches 0. Use the IDirectDraw::AddRef method to increase the reference count of the object by 1.

See Also

 IDirectDraw::AddRef, IDirectDraw::QueryInterface, IDirectDraw::Initialize


IDirectDraw::RestoreDisplayMode

Resets the mode of the display device hardware for the primary surface to what it was before the IDirectDraw2::SetDisplayMode method was called to change it. Exclusive level access is required to use this method.

HRESULT RestoreDisplayMode( );

Parameters

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_GENERIC	DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS	DDERR_LOCKEDSURFACES
DDERR_NOEXCLUSIVEMODE
See Also

 IDirectDraw2::SetDisplayMode, IDirectDraw2::EnumDisplayModes, IDirectDraw::SetCooperativeLevel


IDirectDraw::SetCooperativeLevel

Determines the top-level behavior of the application.

HRESULT SetCooperativeLevel(
HWND hWnd,
DWORD dwFlags
);

Parameters

hWnd

Specifies the window handle used for the application.

dwFlags

DDSCL_ALLOWMODEX

	Allows the use of ModeX display modes.
DDSCL_ALLOWREBOOT

	Allows CTRL_ALT_DEL to function while in full screen exclusive mode.
DDSCL_EXCLUSIVE

	Requests the exclusive level.
DDSCL_FULLSCREEN

	Indicates that the exclusive mode owner will be responsible for the entire primary surface. GDI can be ignored.
DDSCL_NORMAL

	Indicates that the application will function as a regular Windows application.
DDSCL_NOWINDOWCHANGES

	Indicates that DirectDraw is not allowed to minimize or restore the application window on activation.
Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_HWNDALREADYSET	DDERR_INVALIDPARAMS
DDERR_HWNDSUBCLASSED	DDERR_INVALIDOBJECT
DDERR_EXCLUSIVEMODEALREADYSET	DDERR_OUTOFMEMORY
Remarks

The DDSCL_EXCLUSIVE flag must be set to call functions that can have drastic performance consequences for other applications. To call the IDirectDraw::Compact method, change the display mode, or modify the behavior (for example, flipping) of the primary surface, an application must be set to the exclusive level. If an application calls the IDirectDraw::SetCooperativeLevel method with DDSCL_EXCLUSIVE and DDSCL_FULLSCREEN flags set, DirectDraw will attempt to resize its window to full screen. An application must either set the DDSCL_EXCLUSIVE or DDSCL_NORMAL flags, and DDSCL_EXCLUSIVE requires DDSCL_FULLSCREEN.

ModeX modes are only available if an application sets DDSCL_ALLOWMODEX, DDSCL_FULLSCREEN, and DDSCL_EXCLUSIVE. DDSCL_ALLOWMODEX cannot be used with DDSCL_NORMAL. If DDSCL_ALLOWMODEX is not specified, the IDirectDraw2::EnumDisplayModes method will not enumerate the ModeX modes, and the IDirectDraw2::SetDisplayMode method will fail when a ModeX mode is requested. The set of supported display modes may change after using IDirectDraw::SetCooperativeLevel.

ModeX modes are not supported by Windows; therefore, when in a ModeX mode you cannot use the IDirectDrawSurface::Lock method to lock the primary surface, or the IDirectDrawSurface::Blt method to blit to the primary surface. Use the IDirectDrawSurface::GetDC method on the primary surface, or use GDI with a screen DC. ModeX modes are indicated by the DDSCAPS_MODEX flag in the DDSCAPS member of the DDSURFACEDESC structure returned by the IDirectDrawSurface::GetCaps and IDirectDraw2::EnumDisplayModes methods.

Because applications can use DirectDraw with multiple windows, IDirectDraw::SetCooperativeLevel does not require an HWND to be specified if the application is requesting the DDSCL_NORMAL mode. By passing a NULL to HWND, all of the windows can be used simultaneously in normal Windows mode.

See Also

 IDirectDraw2::SetDisplayMode, IDirectDraw::Compact, IDirectDraw2::EnumDisplayModes


IDirectDraw2::SetDisplayMode

Sets the mode of the display device hardware.

HRESULT SetDisplayMode(
DWORD dwWidth,
DWORD dwHeight,
DWORD dwBPP,
DWORD dwRefreshRate,
DWORD dwFlags
);

Parameters

dwWidth

Specifies the width of the new mode.

dwHeight

Specifies the height of the new mode.

dwBPP

Specifies the bits per pixel of the new mode.

dwRefreshRate

Specifies the refresh rate of the new mode. If this parameter is set to 0, the IDirectDraw interface version of this method is used.

dwFlags

This parameter is not currently used and must be set to 0.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_GENERIC	DDERR_INVALIDMODE
DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_LOCKEDSURFACES	DDERR_NOEXCLUSIVEMODE
DDERR_SURFACEBUSY	DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE	DDERR_WASSTILLDRAWING
Remarks

The IDirectDraw::SetCooperativeLevel method must be used to set exclusive level access before the mode can be changed. If other applications have created a DirectDrawSurface object on the primary surface and the mode is changed, those applications' primary surface objects will return DDERR_SURFACELOST until they are restored.

To ensure COM compliance, this method is not part of the IDirectDraw interface, but belongs to the IDirectDraw2 interface. To use this method, you must first query for the IDirectDraw2 interface. For more information, see IDirectDraw2 Interface.

See Also

 IDirectDraw::RestoreDisplayMode, IDirectDraw::GetDisplayMode, IDirectDraw2::EnumDisplayModes, IDirectDraw::SetCooperativeLevel


IDirectDraw::WaitForVerticalBlank

Helps the caller synchronize itself with the vertical blank interval.

HRESULT WaitForVerticalBlank(
DWORD dwFlags,
HANDLE hEvent
);

Parameters

dwFlags

Determines how long to wait for the vertical blank.

DDWAITVB_BLOCKBEGIN

	Returns when the vertical blank interval begins.
DDWAITVB_BLOCKBEGINEVENT

	Triggers an event when the vertical blank begins. This is not currently supported.
DDWAITVB_BLOCKEND

	Returns when the vertical blank interval ends and the display begins.
hEvent

Handle for the event to be triggered when the vertical blank begins.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED	DDERR_WASSTILLDRAWING
See Also

 IDirectDraw::GetVerticalBlankStatus, IDirectDraw::GetScanLine


IDirectDrawSurface Interface

The DirectDrawSurface object represents a two-dimensional piece of memory that contains data. This data is in a form understood by the display hardware represented by the DirectDraw object that created the DirectDrawSurface object. A DirectDrawSurface object is created by the IDirectDraw::CreateSurface method. Although it is not required, the DirectDrawSurface object usually resides in the display RAM of the display card. Unless specifically stated during DirectDrawSurface object creation, the DirectDraw object will put the DirectDrawSurface object wherever the best performance can be achieved given the requested capabilities.

DirectDrawSurface objects can take advantage of specialized processors on display cards, not only to perform certain tasks faster, but to perform some tasks in parallel with the system central processing unit.

DirectDrawSurface objects recognize, and are integrated with, the rest of the components of the Windows display system. DirectDrawSurface objects can create handles to Window GDI device contexts (HDCs) that allow GDI functions to write to the surface memory represented by the DirectDrawSurface object. GDI perceives these HDCs as memory device contexts, but the hardware accelerators are usually enabled for them if they are in display memory.


IDirectDrawSurface Interface Method Groups

Applications use the methods of the IDirectDrawSurface interface to create DirectDrawSurface objects and work with system-level variables. The methods can be organized into the following groups:

Allocating memory	Initialize
	IsLost
	Restore
Attaching surfaces	AddAttachedSurface
	DeleteAttachedSurface
	EnumAttachedSurfaces
	GetAttachedSurface
Blitting	Blt
	BltBatch
	BltFast
Color keys	GetColorKey
	SetColorKey
Device contexts	GetDC
	ReleaseDC
Flipping surfaces	Flip
IUnknown	AddRef
	QueryInterface
	Release
Locking surfaces	Lock
	PageLock
	PageUnlock
	Unlock
Miscellaneous	GetDDInterface
Overlays	AddOverlayDirtyRect
	EnumOverlayZOrders
	GetOverlayPosition
	SetOverlayPosition
	UpdateOverlay
	UpdateOverlayDisplay
	UpdateOverlayZOrder
Status	GetBltStatus
	GetFlipStatus
Surface capabilities	GetCaps
Surface clipper	GetClipper
	SetClipper
Surface description	GetPixelFormat
	GetSurfaceDesc
Surface palettes	GetPalette
	SetPalette
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the DirectDrawSurface object without affecting the functionality of the original interface.


IDirectDrawSurface::AddAttachedSurface

Attaches a surface to another surface.

HRESULT AddAttachedSurface(
LPDIRECTDRAWSURFACE lpDDSAttachedSurface
);

Parameters

lpDDSAttachedSurface

Address of the DirectDrawSurface that is to be attached.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_CANNOTATTACHSURFACE
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACEALREADYATTACHED
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING
Remarks

Possible attachments include z-buffers, alpha channels, and back buffers. Some attachments automatically break other attachments. For example, the 3DZBUFFER can only be attached to one back buffer at a time. Attachment is not bi-directional, and a surface cannot be attached to itself. Emulated surfaces (in system memory) cannot be attached to non-emulated surfaces. Unless one surface is a texture map, the two attached surfaces must be the same size. A flippable surface cannot be attached to another flippable surface of the same type; however, attaching two surfaces of different types is allowed. For example, a flippable z-buffer can be attached to a regular flippable surface. If a non-flippable surface is attached to another non-flippable surface of the same type, the two surfaces will become a flippable chain. If a non-flippable surface is attached to a flippable surface, it becomes part of the existing flippable chain. Additional surfaces can be added to this chain, and each call of the IDirectDrawSurface::Flip method will advance one step through the surfaces.

See Also

 IDirectDrawSurface::DeleteAttachedSurface, IDirectDrawSurface::EnumAttachedSurfaces, IDirectDrawSurface::Flip


IDirectDrawSurface::AddOverlayDirtyRect

Builds the list of the rectangles that need to be updated the next time the IDirectDrawSurface::UpdateOverlayDisplay method is called.

HRESULT AddOverlayDirtyRect(
LPRECT lpRect
);

Parameters

lpRect

Address of the RECT structure that needs to be updated.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED	DDERR_INVALIDSURFACETYPE
Remarks

This method is used for the software implementation. It is not needed if the overlay support is provided by the hardware.

See Also

 IDirectDrawSurface::UpdateOverlayDisplay


IDirectDrawSurface::AddRef

Increases the reference count of the DirectDrawSurface object by 1. This method is part of the IUnknown interface inherited by DirectDraw.

ULONG AddRef( );

Parameters

Return Values

Returns the new reference count of the object.

Remarks

When the DirectDraw object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirectDrawSurface::Release method to decrease the reference count of the object by 1.

See Also

 IDirectDraw::CreateSurface, IDirectDrawSurface::Initialize, IDirectDrawSurface::QueryInterface, IDirectDrawSurface::Release


IDirectDrawSurface::Blt

Performs a bit block transfer.

HRESULT Blt(
LPRECT lpDestRect,
LPDIRECTDRAWSURFACE lpDDSrcSurface,
LPRECT lpSrcRect,
DWORD dwFlags,
LPDDBLTFX lpDDBltFx
);

Parameters

lpDestRect

Address of a RECT structure that defines the upper left and lower right points of the rectangle on the destination surface to be blitted to.

lpDDSrcSurface

Address of the DirectDrawSurface structure that represents the DirectDrawSurface. This is the source for the blit operation.

lpSrcRect

Address of a RECT structure that defines the upper left and lower right points of the rectangle on the source surface to be blitted from.

dwFlags

DDBLT_ALPHADEST

	Uses either the alpha information in pixel format or the alpha channel surface attached to the destination surface as the alpha channel for this blit.
DDBLT_ALPHADESTCONSTOVERRIDE

	Uses the dwAlphaDestConst member in the DDBLTFX structure as the alpha channel for the destination surface for this blit.
DDBLT_ALPHADESTNEG

	The NEG suffix indicates that the destination surface becomes more transparent as the alpha value increases (0 is opaque).
DDBLT_ALPHADESTSURFACEOVERRIDE

	Uses the lpDDSAlphaDest member in the DDBLTFX structure as the alpha channel for the destination for this blit.
DDBLT_ALPHAEDGEBLEND

	Uses the dwAlphaEdgeBlend member in the DDBLTFX structure as the alpha channel for the edges of the image that border the color key colors.
DDBLT_ALPHASRC

	Uses either the alpha information in pixel format or the alpha channel surface attached to the source surface as the alpha channel for this blit.
DDBLT_ALPHASRCCONSTOVERRIDE

	Uses the dwAlphaSrcConst member in the DDBLTFX structure as the alpha channel for the source for this blit.
DDBLT_ALPHASRCNEG

	The NEG suffix indicates that the source surface becomes more transparent as the alpha value increases (0 is opaque).
DDBLT_ALPHASRCSURFACEOVERRIDE

	Uses the lpDDSAlphaSrc member in the DDBLTFX structure as the alpha channel for the source for this blit.
DDBLT_ASYNC

	Performs this blit asynchronously through the FIFO in the order received. If no room is available in the FIFO hardware, fail the call.
DDBLT_COLORFILL

	Uses the dwFillColor member in the DDBLTFX structure as the RGB color that fills the destination rectangle on the destination surface.
DDBLT_DDFX

	Uses the dwDDFX member in the DDBLTFX structure to specify the effects to use for the blit.
DDBLT_DDROPS

	Uses the dwDDROPS member in the DDBLTFX structure to specify the raster operations that are not part of the Win32 API.
DDBLT_DEPTHFILL

	Uses the dwFillDepth member in the DDBLTFX structure as the depth value with which to fill the destination rectangle on the destination z-buffer surface.
DDBLT_KEYDEST

	Uses the color key associated with the destination surface.
DDBLT_KEYDESTOVERRIDE

	Uses the dckDestColorkey member in the DDBLTFX structure as the color key for the destination surface.
DDBLT_KEYSRC

	Uses the color key associated with the source surface.
DDBLT_KEYSRCOVERRIDE

	Uses the dckSrcColorkey member in the DDBLTFX structure as the color key for the source surface.
DDBLT_ROP

	Uses the dwROP member in the DDBLTFX structure for the raster operation for this blit. These ROPs are the same as those defined in the Win32 API.
DDBLT_ROTATIONANGLE

	Uses the dwRotationAngle member in the DDBLTFX structure as the angle (specified in 1/100th of a degree) to rotate the surface.
DDBLT_WAIT

	Postpones the DDERR_WASSTILLDRAWING return value if the blitter is busy. Returns as soon as the blit can be set up or another error occurs.
DDBLT_ZBUFFER

	Performs a z-buffered blit using the z-buffers attached to the source and destination surfaces and the dwZBufferOpCode member in the DDBLTFX structure as the z-buffer opcode.
DDBLT_ZBUFFERDESTCONSTOVERRIDE

	Performs a z-buffered blit using the dwZDestConst and dwZBufferOpCode members in the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for the destination.
DDBLT_ZBUFFERDESTOVERRIDE

	Performs a z-buffered blit using the lpDDSZBuffeDestr and dwZBufferOpCode members in the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for the destination.
DDBLT_ZBUFFERSRCCONSTOVERRIDE

	Performs a z-buffered blit using the dwZSrcConst and dwZBufferOpCode members in the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for the source.
DDBLT_ZBUFFERSRCOVERRIDE

	Performs a z-buffered blit using the lpDDSZBufferSrc and dwZBufferOpCode members in the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for the source.
lpDDBltFx

See the DDBLTFX structure.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_GENERIC	DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_INVALIDRECT	DDERR_NOALPHAHW
DDERR_NOBLTHW	DDERR_NOCLIPLIST
DDERR_NODDROPSHW	DDERR_NOMIRRORHW
DDERR_NORASTEROPHW	DDERR_NOROTATIONHW
DDERR_NOSTRETCHHW	DDERR_NOZBUFFERHW
DDERR_SURFACEBUSY	DDERR_SURFACELOST
DDERR_UNSUPPORTED
Remarks

This method is capable of synchronous or asynchronous blits, either display memory to display memory, display memory to system memory, system memory to display memory, or system memory to system memory. The blits can be performed using z-information, alpha information, source color keys and destination color keys. Arbitrary stretching or shrinking will be performed if the source and destination rectangles are not the same size.

Typically, IDirectDrawSurface::Blt returns immediately with an error if the blitter is busy and the blit could not be set up. The DDBLT_WAIT flag can alter this behavior so that the method will either wait until the blit can be set up or another error occurs before it returns.


IDirectDrawSurface::BltBatch

Performs a sequence of IDirectDrawSurface::Blt operations from several sources to a single destination. At present this method is only a stub; it has not yet been implemented.

HRESULT BltBatch(
LPDDBLTBATCH lpDDBltBatch,
DWORD dwCount,
DWORD dwFlags
);

Parameters

lpDDBltBatch

Address of the first DDBLTBATCH structure that defines the parameters for the blit operations.

dwCount

The number of blit operations to be performed.

dwFlags

This parameter is not used at this time and must be set to 0.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_GENERIC	DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_INVALIDRECT	DDERR_NOALPHAHW
DDERR_NOBLTHW	DDERR_NOCLIPLIST
DDERR_NODDROPSHW	DDERR_NOMIRRORHW
DDERR_NORASTEROPHW	DDERR_NOROTATIONHW
DDERR_NOSTRETCHHW	DDERR_NOZBUFFERHW
DDERR_SURFACEBUSY	DDERR_SURFACELOST
DDERR_UNSUPPORTED


IDirectDrawSurface::BltFast

Performs a source copy blit or transparent blit using a source or destination color key. This method always attempts an asynchronous blit if this is supported by the hardware.

HRESULT BltFast(
DWORD dwX,
DWORD dwY,
LPDIRECTDRAWSURFACE lpDDSrcSurface,
LPRECT lpSrcRect,
DWORD dwTrans
);

Parameters

dwX

X-coordinate to blit to on the destination surface.

dwY

Y-coordinate to blit to on the destination surface.

lpDDSrcSurface

Address of the DirectDrawSurface structure that represents the DirectDrawSurface. This is the source for the blit operation.

lpSrcRect

Address of a RECT structure that defines the upper left and lower right points of the rectangle on the source surface to be blitted from.

dwTrans

Specifies the type of transfer.

DDBLTFAST_DESTCOLORKEY

	A transparent blit that uses the destination's color key.
DDBLTFAST_NOCOLORKEY

	A normal copy blit with no transparency.
DDBLTFAST_SRCCOLORKEY

	A transparent blit that uses the source's color key.
DDBLTFAST_WAIT

	Postpones the DDERR_WASSTILLDRAWING message if the blitter is busy. Returns as soon as the blit can be set up or another error occurs.
Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_EXCEPTION	DDERR_GENERIC
DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_INVALIDRECT	DDERR_NOBLTHW
DDERR_SURFACEBUSY	DDERR_SURFACELOST
DDERR_UNSUPPORTED
Remarks

This method only works on display memory surfaces and cannot clip when blitting. The software implementation of IDirectDrawSurface::BltFast is 10 percent faster than the IDirectDrawSurface::Blt method. However, there is no speed difference between the two if display hardware is being used.

Typically, IDirectDrawSurface::BltFast returns immediately with an error if the blitter is busy and the blit cannot be set up. The DDBLTFAST_WAIT flag can be used to alter this behavior so that this method will not return until either the blit can be set up or another error occurs.


IDirectDrawSurface::DeleteAttachedSurface

Detaches two attached surfaces. The detached surface is not released.

HRESULT DeleteAttachedSurface(
DWORD dwFlags,
LPDIRECTDRAWSURFACE lpDDSAttachedSurface
);

Parameters

dwFlags

This parameter is not used at this time and must be set to 0.

lpDDSAttachedSurface

Address of the DirectDrawSurface structure to be detached. If NULL is passed, all attached surfaces will be detached.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_CANNOTDETACHSURFACE
DDERR_INVALIDPARAMS	DDERR_SURFACENOTATTACHED
DDERR_SURFACELOST
Remarks

If NULL is passed as the surface to be detached, all attached surfaces will be detached. Implicit attachments, those formed by DirectDraw rather than the IDirectDrawSurface::AddAttachedSurface method, cannot be detached. Detaching surfaces from a flippable chain can alter other surfaces in the chain. If a front buffer is detached from a flippable chain, the next surface in the chain becomes the front buffer, and the following surface becomes the back buffer. If a back buffer is detached from a chain, the following surface becomes a back buffer. If a plain surface is detached from a chain, the chain simply becomes shorter. If a flippable chain only has two surfaces and they are detached, the chain is destroyed and both surfaces return to their previous designations.

See Also

 IDirectDrawSurface::Flip


IDirectDrawSurface::EnumAttachedSurfaces

Enumerates all the surfaces attached to a given surface.

HRESULT EnumAttachedSurfaces(
LPVOID lpContext,
LPDDENUMSURFACESCALLBACK lpEnumSurfacesCallback );

Parameters

lpContext

Address of the caller-defined structure that is passed to the enumeration member every time it is called.

lpEnumSurfacesCallback

Address of the EnumSurfacesCallback function that will be called for each surface that is attached to this surface.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_SURFACELOST


IDirectDrawSurface::EnumOverlayZOrders

Enumerates the overlays on the specified destination. The overlays can be enumerated in front-to-back or back-to-front order.

HRESULT EnumOverlayZOrders(
DWORD dwFlags,
LPVOID lpContext,
LPDDENUMSURFACESCALLBACK lpfnCallback
);

Parameters

dwFlags

DDENUMOVERLAYZ_BACKTOFRONT

	Enumerates overlays back to front.
DDENUMOVERLAYZ_FRONTTOBACK

	Enumerates overlays front to back.
lpContext

Address of the user-defined context that will be passed to the callback function for each overlay surface.

lpfnCallback

Address of the fnCallback function that will be called for each surface being overlaid on this surface.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS


IDirectDrawSurface::Flip

Makes the surface memory associated with the DDSCAPS_BACKBUFFER surface become associated with the front buffer surface.

HRESULT Flip(
LPDIRECTDRAWSURFACE lpDDSurfaceTargetOverride,
DWORD dwFlags
);

Parameters

lpDDSurfaceTargetOverride

Address of the DirectDrawSurface structure that will be flipped to. The default for this parameter is NULL, in which case IDirectDrawSurface::Flip cycles through the buffers in the order they are attached to each other. This parameter is only used as an override.

dwFlags

DDFLIP_WAIT

	Typically, if the flip cannot be set up because the state of the display hardware is not appropriate, the error DDERR_WASSTILLDRAWING will return immediately and no flip will occur. Setting this flag causes IDirectDrawSurface::Flip to continue trying to flip if it receives the DDERR_WASSTILLDRAWING error from the HAL. IDirectDrawSurface::Flip will not return until the flipping operation has been successfully set up, or if another error, such as DDERR_SURFACEBUSY, is returned.
Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_GENERIC	DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS	DDERR_NOTFLIPPABLE
DDERR_NOFLIPHW	DDERR_SURFACEBUSY
DDERR_SURFACELOST	DDERR_WASSTILLDRAWING
DDERR_UNSUPPORTED
Remarks

This method can only be called by a surface that has the DDSCAPS_FLIP and DDSCAPS_FRONTBUFFER values set. The display memory previously associated with the front buffer is associated with the back buffer. If there is more than one back buffer, a ring is formed and the surface memory buffers cycle one step through it every time IDirectDrawSurface::Flip is invoked.

The lpDDSurfaceTargetOverride parameter is used in rare cases when the back buffer is not the buffer that should become the front buffer. Typically this parameter is NULL.

The IDirectDrawSurface::Flip method will always be synchronized with the vertical blank.

See Also

 IDirectDrawSurface::GetFlipStatus


IDirectDrawSurface::GetAttachedSurface

Obtains the attached surface that has the specified capabilities.

HRESULT GetAttachedSurface(
LPDDSCAPS lpDDSCaps,
LPLPDIRECTDRAWSURFACE FAR * lplpDDAttachedSurface
);

Parameters

lpDDSCaps

Address of a DDSCAPS structure that contains the hardware capabilities of the surface.

lplpDDAttachedSurface

Address of a pointer to a DirectDrawSurface that will be attached to the current DirectDrawSurface specified by lpDDSurface and has capabilities that match those specified by the lpDDSCaps parameter.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_NOTFOUND	DDERR_SURFACELOST
Remarks

Attachments are used to connect multiple DirectDrawSurface objects into complex structures, like the ones needed to support 3D page flipping with z-buffers. This method will fail if more than one surface is attached that matches the capabilities requested. In this case, the application must use the IDirectDrawSurface::EnumAttachedSurfaces method to obtain the non-unique attached surfaces.


IDirectDrawSurface::GetBltStatus

Obtains the blitter status. This method returns DD_OK if a blitter is present, DDERR_WASSTILLDRAWING if the blitter is busy, or DDERR_NOBLTHW if there is no blitter.

HRESULT GetBltStatus(
DWORD dwFlags
);

Parameters

dwFlags

DDGBS_CANBLT

	Inquires whether a blit involving this surface can occur immediately. Returns DD_OK if the blit can be completed.
DDGBS_ISBLTDONE

	Inquires whether the blit is done. Returns DD_OK if the last blit on this surface has completed.
Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_NOBLTHW	DDERR_SURFACEBUSY
DDERR_SURFACELOST	DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING


IDirectDrawSurface::GetCaps

Returns the capabilities of the surface. These capabilities are not necessarily related to the capabilities of the display device.

HRESULT GetCaps(
LPDDSCAPS lpDDSCaps
);

Parameters

lpDDSCaps

Address of a DDSCAPS structure that will be filled in with the hardware capabilities of the surface.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
Remarks

Information for the lpDDSCaps parameter is new since the DirectX 2 SDK was released. For a complete list of new information, see New Information.


IDirectDrawSurface::GetClipper

Returns the DirectDrawClipper associated with this surface. An error returns if no DirectDrawClipper is associated.

HRESULT GetClipper(
LPDIRECTDRAWCLIPPER FAR * lplpDDClipper
);

Parameters

lplpDDClipper

Address of a pointer to the DirectDrawClipper associated with the surface.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_NOCLIPPERATTACHED
See Also

 IDirectDrawSurface::SetClipper


IDirectDrawSurface::GetColorKey

Returns the color key value for the DirectDrawSurface object.

HRESULT GetColorKey(
DWORD dwFlags,
LPDDCOLORKEY lpDDColorKey
);

Parameters

dwFlags

Determines which color key is requested.

DDCKEY_DESTBLT

	Set if the structure specifies a color key or color space to be used as a destination color key for blit operations.
DDCKEY_DESTOVERLAY

	Set if the structure specifies a color key or color space to be used as a destination color key for overlay operations.
DDCKEY_SRCBLT

	Set if the structure specifies a color key or color space to be used as a source color key for blit operations.
DDCKEY_SRCOVERLAY

	Set if the structure specifies a color key or color space to be used as a source color key for overlay operations.
lpDDColorKey

Address of the DDCOLORKEY structure that will be filled in with the current values for the specified color key of the DirectDrawSurface object.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_NOCOLORKEYHW	DDERR_NOCOLORKEY
DDERR_SURFACELOST	DDERR_UNSUPPORTED
See Also

 IDirectDrawSurface::SetColorKey


IDirectDrawSurface::GetDC

Creates a GDI-compatible hDC for the surface.

HRESULT GetDC(
HDC FAR * lphDC
);

Parameters

lphDC

Address of the returned hDC.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_DCALREADYCREATED	DDERR_GENERIC
DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE	DDERR_SURFACELOST
DDERR_UNSUPPORTED	DDERR_WASSTILLDRAWING
Remarks

This method uses an internal version of the IDirectDrawSurface::Lock method to lock the surface, and the surface will remain locked until the IDirectDrawSurface::ReleaseDC method is called. For more information, see the description of the IDirectDrawSurface::Lock method.

See Also

 IDirectDrawSurface::ReleaseDC, IDirectDrawSurface::Lock


IDirectDrawSurface2::GetDDInterface

Returns an interface to the DirectDraw object that was used to create the surface.

HRESULT GetDDInterface(
LPVOID FAR *lplpDD
);

Parameters

lplpDD

Address of a pointer that will be filled with a valid DirectDraw pointer if the call succeeds.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
Remarks

To ensure COM compliance, this method is not part of the IDirectDrawSurface interface, but of the IDirectDrawSurface2 interface. To use this method, you must first query for the IDirectDrawSurface2 interface. For more information, see IDirectDrawSurface2 Interface.


IDirectDrawSurface::GetFlipStatus

Indicates whether the surface has finished its flipping process. If the surface has not finished its flipping process, it returns DDERR_WASSTILLDRAWING.

HRESULT GetFlipStatus(
DWORD dwFlags
);

Parameters

dwFlags

DDGFS_CANFLIP

	Inquires whether this surface be flipped immediately. Returns DD_OK if the flip can be completed.
DDGFS_ISFLIPDONE

	Inquires whether the flip done. Returns DD_OK if the last flip on this surface has completed.
Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE	DDERR_SURFACEBUSY
DDERR_SURFACELOST	DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING
See Also

 IDirectDrawSurface::Flip


IDirectDrawSurface::GetOverlayPosition

Given a visible, active overlay surface (DDSCAPS_OVERLAY flag set), this method returns the display coordinates of the surface.

HRESULT GetOverlayPosition(
LPLONG lplX,
LPLONG lplY
);

Parameters

lplX

Address of the x-display coordinate.

lplY

Address of the y-display coordinate.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_GENERIC	DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS	DDERR_INVALIDPOSITION
DDERR_NOOVERLAYDEST	DDERR_NOTAOVERLAYSURFACE
DDERR_OVERLAYNOTVISIBLE	DDERR_SURFACELOST
See Also

 IDirectDrawSurface::SetOverlayPosition, IDirectDrawSurface::UpdateOverlay


IDirectDrawSurface::GetPalette

Returns the DirectDrawPalette structure associated with this surface.

HRESULT GetPalette(
LPDIRECTDRAWPALETTE FAR * lplpDDPalette
);

Parameters

lplpDDPalette

Address of a pointer to a DirectDrawPalette structure. This pointer will be filled in with the address of the DirectDrawPalette structure associated with this surface. This will be set to NULL if no DirectDrawPalette is associated with this surface.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_GENERIC	DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS	DDERR_NOEXCLUSIVEMODE
DDERR_NOPALETTEATTACHED	DDERR_SURFACELOST
DDERR_UNSUPPORTED
Remarks

If no palette has been explicitly associated with this surface, it returns NULL for the associated palette. However, if this is the primary surface or a back buffer to the primary surface, it returns a pointer to the system palette if the primary surface is in 8-bpp mode.

See Also

 IDirectDrawSurface::SetPalette


IDirectDrawSurface::GetPixelFormat

Returns the color and pixel format of the surface.

HRESULT GetPixelFormat(
LPDDPIXELFORMAT lpDDPixelFormat
);

Parameters

lpDDPixelFormat

Address of the DDPIXELFORMAT structure that will be filled in with a detailed description of the current pixel and color space format of the surface.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE


IDirectDrawSurface::GetSurfaceDesc

Returns a DDSURFACEDESC structure that describes the surface in its current condition.

HRESULT GetSurfaceDesc(
LPDDSURFACEDESC lpDDSurfaceDesc
);

Parameters

lpDDSurfaceDesc

Address of a DDSURFACEDESC structure to be filled in with the current description of this surface.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
See Also

 DDSURFACEDESC


IDirectDrawSurface::Initialize

Initializes a DirectDrawSurface.

HRESULT Initialize(
LPDIRECTDRAW lpDD,
LPDDSURFACEDESC lpDDSurfaceDesc
);

Parameters

lpDD

Address of the DirectDraw structure that represents the DirectDraw object.

lpDDSurfaceDesc

Address of a DDSURFACEDESC structure to be filled in with the relevant details about the surface.

Return Values

Returns DDERR_ALREADYINITIALIZED.

Remarks

This method is provided for compliance with the Component Object Model (COM) protocol. Since the DirectDrawSurface object is initialized when it is created, calling this method will always result in the DDERR_ALREADYINITIALIZED return value.

See Also

 IDirectDrawSurface::AddRef, IDirectDrawSurface::QueryInterface, IDirectDrawSurface::Release


IDirectDrawSurface::IsLost

Determines if the surface memory associated with a DirectDrawSurface has been freed. If the memory has not been freed, this method will return DD_OK.

HRESULT IsLost( );

Parameters

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_SURFACELOST
Remarks

This method can be used to reallocate surface memory. When a DirectDrawSurface object loses its surface memory, most methods will return DDERR_SURFACELOST and perform no other function.

Surfaces can lose their memory when the mode of the display card is changed, or because an application received exclusive access to the display card and freed all of the surface memory currently allocated on the display card.

See Also

 IDirectDrawSurface::Restore


IDirectDrawSurface::Lock

Obtains a pointer to the surface memory.

HRESULT Lock(
LPRECT lpDestRect,
LPDDSURFACEDESC lpDDSurfaceDesc,
DWORD dwFlags,
HANDLE hEvent
);

Parameters

lpDestRect

Address of a RECT structure that identifies the region of surface that is being locked.

lpDDSurfaceDesc

Address of a DDSURFACEDESC structure to be filled with the relevant details about the surface.

dwFlags

DDLOCK_EVENT

	Triggers the event when IDirectDrawSurface::Lock can return the surface memory pointer requested. Set if an event handle is being passed to IDirectDrawSurface::Lock. If multiple locks of this type are placed on a surface, events will be triggered in FIFO order.
DDLOCK_READONLY

	Indicates that the surface being locked will only be read from.
DDLOCK_SURFACEMEMORYPTR

	Indicates that a valid memory pointer to the top of the specified rectangle should be returned. If no rectangle is specified, a pointer to the top of the surface is returned. This is the default.
DDLOCK_WAIT

	Typically, if a lock cannot be obtained because a blit is in progress, a DDERR_WASSTILLDRAWING error will be returned immediately. If this flag is set, however, IDirectDrawSurface::Lock will retry until a lock is obtained or another error, such as DDERR_SURFACEBUSY, occurs.
DDLOCK_WRITEONLY

	Indicates that the surface being locked will only be written to.
hEvent

Handle to a system event that is triggered when the surface is ready to be locked.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY	DDERR_SURFACEBUSY
DDERR_SURFACELOST	DDERR_WASSTILLDRAWING
Remarks

Once the pointer is obtained, the surface memory can be accessed by your application until the corresponding the IDirectDrawSurface::Unlock method is called. Once this occurs, the pointer to the surface memory is no longer valid.

It is illegal to blit from a region of a surface that is locked. If a blit is attempted on a locked surface, the blit will return either a DDERR_SURFACEBUSY or DDERR_LOCKEDSURFACES error value.

Typically, IDirectDrawSurface::Lock will return immediately with an error when a lock cannot be obtained because a blit is in progress. The DDLOCK_WAIT flag can be set to continue trying to obtain a lock.

To prevent VRAM from being lost during access to a surface, DirectDraw holds the Win16 lock between IDirectDrawSurface::Lock and IDirectDrawSurface::Unlock operations. The Win16 lock is the critical section that serializes access to GDI and USER. Although this technique allows direct access to display memory and prevents other applications from changing the mode during this access, it will stop Windows from running, so IDirectDrawSurface::Lock/IDirectDrawSurface::Unlock and IDirectDrawSurface::GetDC/IDirectDrawSurface::ReleaseDC periods should be kept short. Unfortunately, because Windows is stopped, GUI debuggers cannot be used in between IDirectDrawSurface::Lock/IDirectDrawSurface::Unlock or IDirectDrawSurface::GetDC/IDirectDrawSurface::ReleaseDC operations.

See Also

 IDirectDrawSurface::Unlock, IDirectDrawSurface::GetDC, IDirectDrawSurface::ReleaseDC


IDirectDrawSurface2::PageLock

Prevents a system memory surface from being paged out while a blit using DMA transfers to or from system memory is in progress. A lock count is maintained for each surface and is incremented each time IDirectDrawSurface2::PageLock is called for that surface. The count is decremented when IDirectDrawSurface2::PageUnlock is called. When the count reaches 0, the memory is unlocked and can then be paged by the operating system.

Note

The performance of the operating system could be negatively affected if too much memory is locked.

HRESULT PageLock(
DWORD dwFlags
);

Parameters

dwFlags

This parameter is not used at this time and must be set to 0.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_CANTPAGELOCK	DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS	DDERR_SURFACELOST
Remarks

This method only works on system memory surfaces; it will not page lock a display memory surface or an emulated primary surface. If this method is called on a display memory surface, it will do nothing except return DD_OK.

To ensure COM compliance, this method is not a part of the IDirectDrawSurface interface, but belongs to the IDirectDrawSurface2 interface. To use this method, you must first query for the IDirectDrawSurface2 interface. For more information, see IDirectDrawSurface2 Interface.

See Also

 IDirectDrawSurface2::PageUnlock


IDirectDrawSurface2::PageUnlock

Unlocks a system memory surface, allowing it to be paged out. A lock count is maintained for each surface and is incremented each time IDirectDrawSurface2::PageLock is called for that surface. The count is decremented when IDirectDrawSurface2::PageUnlock is called. When the count reaches 0, the memory is unlocked and can then be paged by the operating system.

HRESULT PageUnlock(
DWORD dwFlags
);

Parameters

dwFlags

This parameter is not used at this time and must be set to 0.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_CANTPAGEUNLOCK	DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS	DDERR_NOTPAGELOCKED
DDERR_SURFACELOST
Remarks

This method only works on system memory surfaces; it will not page unlock a display memory surface or an emulated primary surface. If this method is called on a display memory surface, it will do nothing except return DD_OK.

To ensure COM compliance, this method is not a part of the IDirectDrawSurface interface, but belongs to the IDirectDrawSurface2 interface. To use this method, you must first query for the IDirectDrawSurface2 interface. For more information, see IDirectDrawSurface2 Interface.

See Also

 IDirectDrawSurface2::PageLock


IDirectDrawSurface::QueryInterface

Determines if the DirectDrawSurface object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by DirectDraw.

HRESULT QueryInterface(
REFIID riid,
LPVOID FAR * ppvObj
);

Parameters

riid

Reference identifier of the interface being requested.

ppvObj

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirectDrawSurface::QueryInterface method allows DirectDrawSurface objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.

See Also

 IDirectDrawSurface::AddRef, IDirectDrawSurface::Initialize, IDirectDrawSurface::Release


IDirectDrawSurface::Release

Decreases the reference count of the DirectDrawSurface object by 1. This method is part of the IUnknown interface inherited by DirectDraw.

ULONG Release( );

Parameters

Return Values

Returns the new reference count of the object.

Remarks

The DirectDrawSurface object deallocates itself when its reference count reaches 0. Use the IDirectDrawSurface::AddRef method to increase the reference count of the object by 1.

See Also

 IDirectDrawSurface::AddRef, IDirectDrawSurface::Initialize, IDirectDrawSurface::QueryInterface


IDirectDrawSurface::ReleaseDC

Releases the hDC previously obtained with the IDirectDrawSurface::GetDC method.

HRESULT ReleaseDC(
HDC hDC
);

Parameters

hDC

The hDC previously obtained by IDirectDrawSurface::GetDC.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_GENERIC	DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS	DDERR_SURFACELOST
DDERR_UNSUPPORTED
Remarks

This method also unlocks the surface previously locked when the IDirectDrawSurface::GetDC method was called.

See Also

 IDirectDrawSurface::GetDC


IDirectDrawSurface::Restore

Restores a surface that has been lost. This occurs when the surface memory associated with the DirectDrawSurface object has been freed.

HRESULT Restore( );

Parameters

Return Values

Returns DD_OK is successful, or one of the following error values otherwise:

DDERR_GENERIC	DDERR_INCOMPATIBLEPRIMARY
DDERR_IMPLICITLYCREATED	DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS	DDERR_NOEXCLUSIVEMODE
DDERR_OUTOFMEMORY	DDERR_UNSUPPORTED
DDERR_WRONGMODE
Remarks

Surfaces can be lost because the display card's mode was changed or because an application received exclusive access to the display card and freed all of the surface memory currently allocated on the card. When a DirectDrawSurface object loses its surface memory, many methods will return DDERR_SURFACELOST and perform no other function. The IDirectDrawSurface::Restore method will reallocate surface memory and reattach it to the DirectDrawSurface object.

A single call to this method will restore a DirectDrawSurface's associated implicit surfaces (back buffers, and so on). An attempt to restore an implicitly created surface will result in an error. IDirectDrawSurface::Restore will not work across explicit attachments created using the IDirectDrawSurface::AddAttachedSurface method — each of these surfaces must be restored individually.

See Also

 IDirectDrawSurface::IsLost, IDirectDrawSurface::AddAttachedSurface


IDirectDrawSurface::SetClipper

Attaches a DirectDrawClipper object to a DirectDrawSurface object.

HRESULT SetClipper(
LPDIRECTDRAWCLIPPER lpDDClipper
);

Parameters

lpDDClipper

Address of the DirectDrawClipper structure representing the DirectDrawClipper that will be attached to the DirectDrawSurface. If NULL, the current clipper will be detached.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE	DDERR_NOCLIPPERATTACHED
Remarks

This method is primarily used by surfaces that are being overlaid on or blitted to the primary surface. However, it can be used on any surface. Once a DirectDrawClipper has been attached and a clip list is associated with it, the clipper object will be used for the IDirectDrawSurface::Blt, IDirectDrawSurface::BltBatch, and IDirectDrawSurface::UpdateOverlay operations involving the parent DirectDrawSurface. This method can also detach a DirectDrawSurface's current clipper.

See Also

 IDirectDrawSurface::GetClipper


IDirectDrawSurface::SetColorKey

Sets the color key value for the DirectDrawSurface object if the hardware supports color keys on a per surface basis.

HRESULT SetColorKey(
DWORD dwFlags,
LPDDCOLORKEY lpDDColorKey
);

Parameters

dwFlags

Determines which color key is requested.

DDCKEY_COLORSPACE

	Set if the structure contains a color space. Not set if the structure contains a single color key.
DDCKEY_DESTBLT

	Set if the structure specifies a color key or color space to be used as a destination color key for blit operations.
DDCKEY_DESTOVERLAY

	Set if the structure specifies a color key or color space to be used as a destination color key for overlay operations.
DDCKEY_SRCBLT

	Set if the structure specifies a color key or color space to be used as a source color key for blit operations.
DDCKEY_SRCOVERLAY

	Set if the structure specifies a color key or color space to be used as a source color key for overlay operations.
lpDDColorKey

Address of the DDCOLORKEY structure that has the new color key values for the DirectDrawSurface object.

Return Values

Returns DD_OK is successful, or one of the following error values otherwise:

DDERR_GENERIC	DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS	DDERR_INVALIDSURFACETYPE
DDERR_NOOVERLAYHW	DDERR_NOTAOVERLAYSURFACE
DDERR_SURFACELOST	DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING
See Also

 IDirectDrawSurface::GetColorKey


IDirectDrawSurface::SetOverlayPosition

Changes the display coordinates of an overlay surface.

HRESULT SetOverlayPosition(
LONG lX,
LONG lY
);

Parameters

lX

New x-display coordinate.

lY

New y-display coordinate.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_GENERIC	DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS	DDERR_SURFACELOST
DDERR_UNSUPPORTED
See Also

 IDirectDrawSurface::GetOverlayPosition, IDirectDrawSurface::UpdateOverlay


IDirectDrawSurface::SetPalette

Attaches the specified DirectDrawPalette to a surface. The surface will use this palette for all subsequent operations. The palette change takes place immediately, without regard to refresh timing.

HRESULT SetPalette(
LPDIRECTDRAWPALETTE lpDDPalette
);

Parameters

lpDDPalette

Address of the DirectDrawPalette structure that this surface should use for future operations.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_GENERIC	DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS	DDERR_INVALIDSURFACETYPE
DDERR_NOEXCLUSIVEMODE	DDERR_NOPALETTEATTACHED
DDERR_NOPALETTEHW	DDERR_NOT8BITCOLOR
DDERR_SURFACELOST	DDERR_UNSUPPORTED
See Also

 IDirectDrawSurface::GetPalette, IDirectDraw::CreatePalette


IDirectDrawSurface::Unlock

Notifies DirectDraw that the direct surface manipulations are complete.

HRESULT Unlock(
LPVOID lpSurfaceData
);

Parameters

lpSurfaceData

Address of a pointer returned by the IDirectDrawSurface::Lock method. Since it is possible to call IDirectDrawSurface::Lock multiple times for the same surface with different destination rectangles, this pointer ties the calls to the IDirectDrawSurface::Lock and IDirectDrawSurface::Unlock methods together.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_GENERIC	DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS	DDERR_INVALIDRECT
DDERR_NOTLOCKED	DDERR_SURFACELOST
See Also

 IDirectDrawSurface::Lock


IDirectDrawSurface::UpdateOverlay

Repositions or modifies the visual attributes of an overlay surface. These surfaces must have the DDSCAPS_OVERLAY value set.

HRESULT UpdateOverlay(
LPRECT lpSrcRect,
LPDIRECTDRAWSURFACE lpDDDestSurface,
LPRECT lpDestRect,
DWORD dwFlags,
LPDDOVERLAYFX lpDDOverlayFx
);

Parameters

lpSrcRect

Address of a RECT structure that defines the x, y, width, and height of the region on the source surface being used as the overlay.

lpDDDestSurface

Address of the DirectDrawSurface structure that represents the DirectDrawSurface. This is the surface that is being overlaid.

lpDestRect

Address of a RECT structure that defines the x, y, width, and height of the region on the destination surface that the overlay should be moved to.

dwFlags

DDOVER_ADDDIRTYRECT

	Adds a dirty rectangle to an emulated overlaid surface.
DDOVER_ALPHADEST

	Uses the alpha information in pixel format or the alpha channel surface attached to the destination surface as the alpha channel for the destination overlay.
DDOVER_ALPHADESTCONSTOVERRIDE

	Uses the dwAlphaDestConst member in the DDOVERLAYFX structure as the destination alpha channel for this overlay.
DDOVER_ALPHADESTNEG

	The NEG suffix indicates that the destination surface becomes more transparent as the alpha value increases. (0 is opaque).
DDOVER_ALPHADESTSURFACEOVERRIDE

	Uses the lpDDSAlphaDest member in the DDOVERLAYFX structure as the alpha channel destination for this overlay.
DDOVER_ALPHAEDGEBLEND

	Uses the dwAlphaEdgeBlend member in the DDOVERLAYFX structure as the alpha channel for the edges of the image that border the color key colors.
DDOVER_ALPHASRC

	Uses the alpha information in pixel format or the alpha channel surface attached to the source surface as the source alpha channel for this overlay.
DDOVER_ALPHASRCCONSTOVERRIDE

	Uses the dwAlphaSrcConst member in the DDOVERLAYFX structure as the source alpha channel for this overlay.
DDOVER_ALPHASRCNEG

	The NEG suffix indicates that the source surface becomes more transparent as the alpha value increases.
DDOVER_ALPHASRCSURFACEOVERRIDE

	Uses the lpDDSAlphaSrc member in the DDOVERLAYFX structure as the alpha channel source for this overlay.
DDOVER_DDFX

	Uses the overlay FX flags to define special overlay FX.
DDOVER_HIDE

	Turns this overlay off.
DDOVER_KEYDEST

	Uses the color key associated with the destination surface.
DDOVER_KEYDESTOVERRIDE

	Uses the dckDestColorkey member in the DDOVERLAYFX structure as the color key for the destination surface.
DDOVER_KEYSRC

	Uses the color key associated with the source surface.
DDOVER_KEYSRCOVERRIDE

	Uses the dckSrcColorkey member in the DDOVERLAYFX structure as the color key for the source surface.
DDOVER_SHOW

	Turns this overlay on.
DDOVER_ZORDER

	Uses the dwZOrderFlags member in the DDOVERLAYFX structure as the z-order for the display of this overlay. The lpDDSRelative member will be used if the dwZOrderFlags member is set to either DDOVERZ_INSERTINBACKOF or DDOVERZ_INSERTINFRONTOF.
lpDDOverlayFx

See the DDOVERLAYFX structure.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_GENERIC	DDERR_HEIGHTALIGN
DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_INVALIDRECT	DDERR_INVALIDSURFACETYPE
DDERR_NOSTRETCHHW	DDERR_NOTAOVERLAYSURFACE
DDERR_SURFACELOST	DDERR_UNSUPPORTED
DDERR_XALIGN


IDirectDrawSurface::UpdateOverlayDisplay

Repaints the rectangles in the dirty rectangle list of all active overlays. This clears the dirty rectangle list. This method is for software emulation only—it does nothing if the hardware supports overlays.

HRESULT UpdateOverlayDisplay(
DWORD dwFlags
);

Parameters

dwFlags

Specifies the type of update to perform.

DDOVER_REFRESHDIRTYRECTS

	Updates the overlay display using the list of dirty rectangles previously constructed for this destination. This clears the dirty rectangle list.
DDOVER_REFRESHALL

	Ignores the dirty rectangle list and updates the overlay display completely. This clears the dirty rectangle list.
Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED	DDERR_INVALIDSURFACETYPE
See Also

 IDirectDrawSurface::AddOverlayDirtyRect


IDirectDrawSurface::UpdateOverlayZOrder

Sets the z-order of an overlay. The z-order determines which overlay should be occluded when multiple overlays are displayed simultaneously. Overlay positions are all relative to other overlays — there is no true z-value for them.

HRESULT UpdateOverlayZOrder(
DWORD dwFlags,
LPDIRECTDRAWSURFACE lpDDSReference
);

Parameters

dwFlags

DDOVERZ_INSERTINBACKOF

	Inserts this overlay in the overlay chain behind the reference overlay.
DDOVERZ_INSERTINFRONTOF

	Inserts this overlay in the overlay chain in front of the reference overlay.
DDOVERZ_MOVEBACKWARD

	Moves this overlay one position backward in the overlay chain.
DDOVERZ_MOVEFORWARD

	Moves this overlay one position forward in the overlay chain.
DDOVERZ_SENDTOBACK

	Moves this overlay to the back of the overlay chain.
DDOVERZ_SENDTOFRONT

	Moves this overlay to the front of the overlay chain.
lpDDSReference

Address of the DirectDrawSurface structure that represents the DirectDrawSurface to be used as a relative position in the overlay chain. This parameter is needed only for DDOVERZ_INSERTINBACKOF and DDOVERZ_INSERTINFRONTOF.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_NOTAOVERLAYSURFACE
See Also

 IDirectDrawSurface::EnumOverlayZOrders


IDirectDrawPalette Interface

The DirectDrawPalette object is provided to enable direct manipulation of 16- and 256-color palettes. DirectDrawPalette reserves entries 0 through 255 for 256-color palettes; however, it reserves no entries for 16-color palettes. It allows direct manipulation of the palette table as a table. This table can contain 16- or 24-bit RGB entries representing the colors associated with each of the indexes. For 16-color palettes, the table can also contain indexes to another 256-color palette.

Entries in these tables can be retrieved with the IDirectDrawPalette::GetEntries method and changed with the IDirectDrawPalette::SetEntries method. The IDirectDrawPalette::SetEntries method has a dwFlags parameter that specifies when the changes to the palette should take effect.

DirectDrawPalette objects are usually attached to DirectDrawSurface objects.

Two approaches can be used to provide straightforward palette animation using DirectDrawPalette objects. The first approach involves changing the palette entries that correspond to the colors that need to be animated. This can be done with a single call to the IDirectDrawPalette::SetEntries method. The second approach requires two DirectDrawPalette objects. The animation is performed by attaching first one object then the other to the DirectDrawSurface. This can be done using the IDirectDrawSurface::SetPalette method.


IDirectDrawPalette Interface Method Groups

Applications use the methods of the IDirectDrawPalette interface to create DirectDrawPalette objects and work with system-level variables. The methods can be organized into the following groups:

Allocating memory	Initialize
IUnknown	AddRef
	QueryInterface
	Release
Palette capabilities	GetCaps
Palette entries	GetEntries
	SetEntries
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the DirectDrawPalette object without affecting the functionality of the original interface.


IDirectDrawPalette::AddRef

Increases the reference count of the DirectDrawPalette object by 1. This method is part of the IUnknown interface inherited by DirectDraw.

ULONG AddRef( );

Parameters

Return Values

Returns the new reference count of the object.

Remarks

When the DirectDraw object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirectDrawPalette::Release method to decrease the reference count of the object by 1.

See Also

 IDirectDrawPalette::Initialize, IDirectDrawPalette::QueryInterface, IDirectDrawPalette::Release


IDirectDrawPalette::GetCaps

Returns the capabilities of this palette object.

HRESULT GetCaps(
LPDWORD lpdwCaps
);

Parameters

lpdwCaps

Flags from the dwPalCaps member of the DDCAPS structure that define palette capabilities.

DDPCAPS_4BIT
DDPCAPS_8BIT
DDPCAPS_8BITENTRIES
DDPCAPS_ALLOW256
DDPCAPS_PRIMARYSURFACE
DDPCAPS_PRIMARYSURFACELEFT
DDPCAPS_VSYNC
Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS


IDirectDrawPalette::GetEntries

Queries palette values from a DirectDrawPalette.

HRESULT GetEntries(
DWORD dwFlags,
DWORD dwBase,
DWORD dwNumEntries,
LPPALETTEENTRY lpEntries );

Parameters

dwFlags

This parameter is not used at this time and must be set to 0.

dwBase

Indicates the start of the entries that should be retrieved sequentially.

dwNumEntries

Indicates the number of palette entries lpEntries has room for. The colors of each palette entry will be returned in sequence, from dwStartingEntry through dwCount -1.

lpEntries

Address of the palette entries. The palette entries are one byte each if the DDPCAPS_8BITENTRIES flag is set, and four bytes otherwise. Each field is a color description.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_NOTPALETTIZED
See Also

 IDirectDrawPalette::SetEntries


IDirectDrawPalette::Initialize

Initializes the DirectDrawPalette object.

HRESULT Initialize(
LPDIRECTDRAW lpDD,
DWORD dwFlags,
LPPALETTEENTRY lpDDColorTable
);

Parameters

lpDD

Address of the DirectDraw structure that represents the DirectDraw object.

dwFlags

This parameter is not used at this time and must be set to 0.

lpDDColorTable

This parameter is not used at this time and must be set to 0.

Return Values

Returns DDERR_ALREADYINITIALIZED.

Remarks

This method is provided for compliance with the Component Object Model (COM) protocol. Since the DirectDrawPalette object is initialized when it is created, calling this method will always result in the DDERR_ALREADYINITIALIZED return value.

See Also

 IDirectDrawPalette::AddRef, IDirectDrawPalette::QueryInterface


IDirectDrawPalette::QueryInterface

Determines if the DirectDrawPalette object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by DirectDraw.

HRESULT QueryInterface(
REFIID riid,
LPVOID FAR* ppvObj
);

Parameters

riid

Reference identifier of the interface being requested.

ppvObj

Address of a pointer that receives the interface pointer if the request is successful.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirectDrawPalette::QueryInterface method allows DirectDrawPalette objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.

See Also

 IDirectDrawPalette::AddRef, IDirectDrawPalette::Initialize, IDirectDrawPalette::Release


IDirectDrawPalette::Release

Decreases the reference count of the DirectDrawPalette object by 1. This method is part of the IUnknown interface inherited by DirectDraw.

ULONG Release( );

Parameters

Return Values

Returns the new reference count of the object.

Remarks

The DirectDrawPalette object deallocates itself when its reference count reaches 0. Use the IDirectDrawPalette::AddRef method to increase the reference count of the object by 1.

See Also

 IDirectDrawPalette::AddRef, IDirectDrawPalette::Initialize, IDirectDrawPalette::QueryInterface


IDirectDrawPalette::SetEntries

Changes entries in a DirectDrawPalette immediately. The palette must be attached to a surface using the IDirectDrawSurface::SetPalette method before IDirectDrawPalette::SetEntries can be used.

HRESULT SetEntries(
DWORD dwFlags,
DWORD dwStartingEntry,
DWORD dwCount,
LPPALETTEENTRY lpEntries
);

Parameters

dwFlags

This parameter is not used at this time and must be set to 0.

dwStartingEntry

Specifies the first entry to be set.

dwCount

Specifies the number of palette entries to be changed.

lpEntries

Address of the palette entries. The palette entries are one byte each if the DDPCAPS_8BITENTRIES flag is set and four bytes otherwise. Each field is a color description.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_NOPALETTEATTACHED	DDERR_NOTPALETTIZED
DDERR_UNSUPPORTED
See Also

 IDirectDrawPalette::GetEntries, IDirectDrawSurface::SetPalette


IDirectDrawClipper Interface


IDirectDrawClipper Interface Method Groups

Applications use the methods of the IDirectDraw interface to create DirectDraw objects and work with system-level variables. The methods can be organized into the following groups:

Allocating memory	Initialize
Clip lists	IsClipListChanged
	SetClipList
	SetHWnd
Handles	GetClipList
	GetHWnd
IUnknown	AddRef
	QueryInterface
	Release
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the DirectDrawClipper object without affecting the functionality of the original interface.


IDirectDrawClipper::AddRef

Increases the reference count of the DirectDrawClipper object by 1. This method is part of the IUnknown interface inherited by DirectDraw.

ULONG AddRef( );

Parameters

Return Values

Returns the new reference count of the object.

Remarks

When the DirectDraw object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirectDrawClipper::Release method to decrease the reference count of the object by 1.

See Also

 IDirectDraw::CreateClipper, IDirectDrawClipper::Initialize, IDirectDrawClipper::QueryInterface, IDirectDrawClipper::Release


IDirectDrawClipper::GetClipList

Returns a copy of the clip list associated with a DirectDrawClipper object. A subset of the clip list can be selected by passing a rectangle that clips the clip list.

HRESULT GetClipList(
LPRECT lpRect,
LPRGNDATA lpClipList,
LPDWORD lpdwSize
);

Parameters

lpRect

Address of a rectangle that will be used to clip the clip list.

lpClipList

Address of an RGNDATA structure that will contain the resulting copy of the clip list.

lpdwSize

Set by IDirectDrawClipper::GetClipList to indicate the size of the resulting clip list.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_GENERIC	DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_NOCLIPLIST	DDERR_REGIONTOOSMALL
See Also

 IDirectDrawClipper::SetClipList


IDirectDrawClipper::GetHWnd

Returns the hWnd previously associated with this DirectDrawClipper object by the IDirectDrawClipper::SetHWnd method.

HRESULT GetHWnd(
HWND FAR * lphWnd
);

Parameters

lphWnd

Address of the hWnd previously associated with this DirectDrawClipper by the IDirectDrawClipper::SetHWnd method.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
See Also

 IDirectDrawClipper::SetHWnd


IDirectDrawClipper::Initialize

Initializes a DirectDrawClipper object that was created using the CoCreateInstance OLE function.

HRESULT Initialize(
LPDIRECTDRAW lpDD,
DWORD dwFlags
);

Parameters

lpDD

Address of the DirectDraw structure that represents the DirectDraw object. If this value is set to NULL, an independent clipper object is created (the equivalent of using DirectDrawCreateClipper).

dwFlags

This parameter is not used at this time and must be set to 0.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_ALREADYINITIALIZED
DDERR_INVALIDPARAMS
Remarks

If the DirectDrawCreateClipper function or the IDirectDraw::CreateClipper method was used to create the DirectDrawClipper object, this method will return DDERR_ALREADYINITIALIZED.

The information for this method is new since the DirectX 2 SDK was released. For a complete list of new information, see New Information.

See Also

 IDirectDrawClipper::AddRef, IDirectDraw::CreateClipper, IDirectDrawClipper::QueryInterface, IDirectDrawClipper::Release


IDirectDrawClipper::IsClipListChanged

Monitors the status of the clip list if an hWnd is associated with a DirectDrawClipper.

HRESULT IsClipListChanged(
BOOL FAR * lpbChanged
);

Parameters

lpbChanged

Address of a Boolean value set to TRUE if the clip list has changed.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS


IDirectDrawClipper::QueryInterface

Determines if the DirectDrawClipper object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by DirectDraw.

HRESULT QueryInterface(
REFIID riid,
LPVOID FAR * ppvObj
);

Parameters

riid

Reference identifier of the interface being requested.

ppvObj

Address of a pointer that receives the interface pointer if the request is successful.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirectDrawClipper::QueryInterface method allows DirectDrawClipper objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.

See Also

 IDirectDrawClipper::AddRef, IDirectDrawClipper::Release, IDirectDrawClipper::Initialize


IDirectDrawClipper::Release

Decreases the reference count of the DirectDrawClipper object by 1. This method is part of the IUnknown interface inherited by DirectDraw.

ULONG Release( );

Parameters

Return Values

Returns the new reference count of the object.

Remarks

The DirectDrawClipper object deallocates itself when its reference count reaches 0. Use the IDirectDrawClipper::AddRef method to increase the reference count of the object by 1.

See Also

 IDirectDrawClipper::AddRef, IDirectDrawClipper::Initialize, IDirectDrawClipper::QueryInterface


IDirectDrawClipper::SetClipList

Sets or deletes the clip list used by the IDirectDrawSurface::Blt, IDirectDrawSurface::BltBatch, and IDirectDrawSurface::UpdateOverlay methods on surfaces to which the parent DirectDrawClipper is attached.

HRESULT SetClipList(
LPRGNDATA lpClipList,
DWORD dwFlags
);

Parameters

lpClipList

Either an address to a valid RGNDATA structure or NULL. If there is an existing clip list associated with the DirectDrawClipper and this value is NULL, the clip list will be deleted.

dwFlags

This parameter is not used at this time and must be set to 0.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_CLIPPERISUSINGHWND
DDERR_INVALIDPARAMS	DDERR_INVALIDCLIPLIST
DDERR_OUTOFMEMORY
Remarks

The clip list is a series of rectangles that describes the visible areas of the surface. The clip list cannot be set if an hWnd is already associated with the DirectDrawClipper object. Note that the IDirectDrawSurface::BltFast method cannot clip.

See Also

 IDirectDrawClipper::GetClipList, IDirectDrawSurface::Blt, IDirectDrawSurface::BltFast, IDirectDrawSurface::BltBatch, IDirectDrawSurface::UpdateOverlay


IDirectDrawClipper::SetHWnd

Sets the hWnd that will obtain the clipping information.

HRESULT SetHWnd(
DWORD dwFlags,
HWND hWnd
);

Parameters

dwFlags

This parameter is not used at this time and must be set to 0.

hWnd

The hWnd that obtains the clipping information.

Return Values

Returns DD_OK if successful, or one of the following error values otherwise:

DDERR_INVALIDOBJECT	DDERR_INVALIDPARAMS
DDERR_INVALIDCLIPLIST	DDERR_OUTOFMEMORY
See Also

 IDirectDrawClipper::GetHWnd


Structures


DDBLTBATCH

Passes blit operations to the IDirectDrawSurface::BltBatch method.

typedef struct _DDBLTBATCH{

    LPRECT              lprDest;

    LPDIRECTDRAWSURFACE lpDDSSrc;

    LPRECT              lprSrc;

    DWORD               dwFlags;

    LPDDBLTFX           lpDDBltFx;

} DDBLTBATCH,FAR *LPDDBLTBATCH;

Members

lprDest

Address of a RECT structure that defines the destination for the blit.

lpDDSSrc

Address of a DirectDrawSurface that will be the source of the blit.

lprSrc

Address of a RECT structure that defines the source rectangle of the blit.

dwFlags

Specifies the optional control flags.

DDBLT_ALPHADEST

	Uses either the alpha information in the pixel format or the alpha channel surface attached to the destination surface as the alpha channel for this blit.
DDBLT_ALPHADESTCONSTOVERRIDE

	Uses the dwAlphaDestConst member in the DDBLTFX structure as the alpha channel for the destination surface for this blit.
DDBLT_ALPHADESTNEG

	The NEG suffix indicates that the destination surface becomes more transparent as the alpha value increases (0 is opaque).
DDBLT_ALPHADESTSURFACEOVERRIDE

	Uses the lpDDSAlphaDest member in the DDBLTFX structure as the alpha channel for the destination surface for this blit.
DDBLT_ALPHAEDGEBLEND

	Uses the dwAlphaEdgeBlend member in the DDBLTFX structure as the alpha channel for the edges of the image that border the colors of the color key.
DDBLT_ALPHASRC

	Uses either the alpha information in the pixel format or the alpha channel surface attached to the source surface as the alpha channel for this blit.
DDBLT_ALPHASRCCONSTOVERRIDE

	Uses the dwAlphaSrcConst member in the DDBLTFX structure as the alpha channel for the source for this blit.
DDBLT_ALPHASRCNEG

	The NEG suffix indicates that the source surface becomes more transparent as the alpha value increases (0 is opaque).
DDBLT_ALPHASRCSURFACEOVERRIDE

	Uses the lpDDSAlphaSrc member in the DDBLTFX structure as the alpha channel for the source for this blit.
DDBLT_ASYNC

	Processes this blit asynchronously through the FIFO hardware in the order received. If there is no room in the FIFO hardware, the call fails.
DDBLT_COLORFILL

	Uses the dwFillColor member in the DDBLTFX structure as the RGB color with which to fill the destination rectangle on the destination surface.
DDBLT_DDFX

	Uses the dwDDFX member in the DDBLTFX structure to specify the effects to be used for this blit.
DDBLT_DDROPS

	Uses the dwDDROPS member in the DDBLTFX structure to specify the raster operations that are not part of the Win32 API.
DDBLT_KEYDEST

	Uses the color key associated with the destination surface.
DDBLT_KEYDESTOVERRIDE

	Uses the dckDestColorkey member in the DDBLTFX structure as the color key for the destination surface.
DDBLT_KEYSRC

	Uses the color key associated with the source surface.
DDBLT_KEYSRCOVERRIDE

	Uses the dckSrcColorkey member in the DDBLTFX structure as the color key for the source surface.
DDBLT_ROP

	Uses the dwROP member in the DDBLTFX structure for the raster operation for this blit. The raster operations are the same as those defined in the Win32 API.
DDBLT_ROTATIONANGLE

	Uses the dwRotationAngle member in the DDBLTFX structure as the rotation angle (specified in 1/100th of a degree) for the surface.
DDBLT_ZBUFFER

	A z-buffered blit using the z-buffers attached to the source and destination surfaces and the dwZBufferOpCode member in the DDBLTFX structure as the z-buffer opcode.
DDBLT_ZBUFFERDESTCONSTOVERRIDE

	A z-buffered blit using the dwZDestConst and dwZBufferOpCode members in the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for the destination.
DDBLT_ZBUFFERDESTOVERRIDE

	A z-buffered blit using the lpDDSZBufferDest and dwZBufferOpCode members in the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for the destination.
DDBLT_ZBUFFERSRCCONSTOVERRIDE

	A z-buffered blit using the dwZSrcConst and dwZBufferOpCode members in the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for the source.
DDBLT_ZBUFFERSRCOVERRIDE

	A z-buffered blit using the lpDDSZBufferSrc and dwZBufferOpCode members in the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for the source.
lpDDBltFx

Address of a DDBLTFX structure specifying additional blit effects.


DDBLTFX

Passes raster operations, effects, and override information to the IDirectDrawSurface::Blt method. It is also part of the DDBLTBATCH structure used with the IDirectDrawSurface::BltBatch method.

typedef struct _DDBLTFX{

    DWORD  dwSize;

    DWORD  dwDDFX;

    DWORD  dwROP;

    DWORD  dwDDROP;

    DWORD  dwRotationAngle;

    DWORD  dwZBufferOpCode;

    DWORD  dwZBufferLow;

    DWORD  dwZBufferHigh;

    DWORD  dwZBufferBaseDest;

    DWORD  dwZDestConstBitDepth;

union

{

        DWORD                dwZDestConst;

        LPDIRECTDRAWSURFACE  lpDDSZBufferDest;

};

    DWORD   dwZSrcConstBitDepth;

union

{

        DWORD                dwZSrcConst;

        LPDIRECTDRAWSURFACE  lpDDSZBufferSrc;

};

    DWORD  dwAlphaEdgeBlendBitDepth;

    DWORD  dwAlphaEdgeBlend;

    DWORD  dwReserved;

    DWORD  dwAlphaDestConstBitDepth;

union

{

        DWORD                dwAlphaDestConst;

        LPDIRECTDRAWSURFACE  lpDDSAlphaDest;

};

    DWORD  dwAlphaSrcConstBitDepth;

union

{

        DWORD                dwAlphaSrcConst;

        LPDIRECTDRAWSURFACE  lpDDSAlphaSrc;

};

union

{

        DWORD                 dwFillColor;

        DWORD                 dwFillDepth;

        LPDIRECTDRAWSURFACE  lpDDSPattern;

};

DDCOLORKEY  ddckDestColorkey;

DDCOLORKEY  ddckSrcColorkey;

} DDBLTFX,FAR* LPDDBLTFX;

Members

dwSize

Size of the structure. This must be initialized before the structure is used.

dwDDFX

Specifies the type of FX operations.

DDBLTFX_ARITHSTRETCHY

	Uses arithmetic stretching along the y-axis for this blit.
DDBLTFX_MIRRORLEFTRIGHT

	Turns the surface on its y-axis. This blit mirrors the surface from left to right.
DDBLTFX_MIRRORUPDOWN

	Turns the surface on its x-axis. This blit mirrors the surface from top to bottom.
DDBLTFX_NOTEARING

	Schedules this blit to avoid tearing.
DDBLTFX_ROTATE180

	Rotates the surface 180 degrees clockwise during this blit.
DDBLTFX_ROTATE270

	Rotates the surface 270 degrees clockwise during this blit.
DDBLTFX_ROTATE90

	Rotates the surface 90 degrees clockwise during this blit.
DDBLTFX_ZBUFFERBASEDEST

	Adds the dwZBufferBaseDest member to each of the source z-values before comparing them with the destination z-values during this z-blit.
DDBLTFX_ZBUFFERRANGE

	Uses the dwZBufferLow and dwZBufferHigh members as range values to specify limits to the bits copied from a source surface during this z-blit.
dwROP

Specifies the Win32 raster operations.

dwDDROP

Specifies the DirectDraw raster operations.

dwRotationAngle

Rotation angle for the blit.

dwZBufferOpCode

Z-buffer compares.

dwZBufferLow

Low limit of a z-buffer.

dwZBufferHigh

High limit of a z-buffer.

dwZBufferBaseDest

Destination base value of a z-buffer.

dwZDestConstBitDepth

Bit depth of the destination z-constant.

dwZDestConst

Constant used as the z-buffer destination.

lpDDSZBufferDest

Surface used as the z-buffer destination.

dwZSrcConstBitDepth

Bit depth of the source z-constant.

dwZSrcConst

Constant used as the z-buffer source.

lpDDSZBufferSrc

Surface used as the z-buffer source.

dwAlphaEdgeBlend

Alpha used for edge blending.

dwAlphaEdgeBlendBitDepth

Bit depth of the constant for an alpha edge blend.

dwReserved

Reserved for future use.

dwAlphaDestConstBitDepth

Bit depth of the destination alpha constant.

dwAlphaDestConst

Constant used as the alpha channel destination.

lpDDSAlphaDest

Surface used as the alpha channel destination.

dwAlphaSrcConstBitDepth

Bit depth of the source alpha constant.

dwAlphaSrcConst

Constant used as the alpha channel source.

lpDDSAlphaSrc

Surface used as the alpha channel source.

dwFillColor

Color used to fill a surface when DDBLT_COLORFILL is specified. This value can be either an RGB triple or a palette index, depending on the surface type.

dwFillDepth

Depth value for the z-buffer.

lpDDSPattern

Surface to use as a pattern. The pattern can be used in certain blit operations that combine a source and a destination.

ddckDestColorkey

Destination color key override.

ddckSrcColorkey

Source color key override.


DDCAPS

Represents the capabilities of the hardware exposed through the DirectDraw object. It contains a DDSCAPS structure used in this context to describe what kinds of DirectDrawSurfaces can be created. It may not be possible to simultaneously create all of the surfaces described by these capabilities.

typedef struct _DDCAPS{

    DWORD    dwSize;

    DWORD    dwCaps;

    DWORD    dwCaps2;

    DWORD    dwCKeyCaps;

    DWORD    dwFXCaps;

    DWORD    dwFXAlphaCaps;

    DWORD    dwPalCaps;

    DWORD    dwSVCaps;

    DWORD    dwAlphaBltConstBitDepths;

    DWORD    dwAlphaBltPixelBitDepths;

    DWORD    dwAlphaBltSurfaceBitDepths;

    DWORD    dwAlphaOverlayConstBitDepths;

    DWORD    dwAlphaOverlayPixelBitDepths;

    DWORD    dwAlphaOverlaySurfaceBitDepths;

    DWORD    dwZBufferBitDepths;

    DWORD    dwVidMemTotal;

    DWORD    dwVidMemFree;

    DWORD    dwMaxVisibleOverlays;

    DWORD    dwCurrVisibleOverlays;

    DWORD    dwNumFourCCCodes;

    DWORD    dwAlignBoundarySrc;

    DWORD    dwAlignSizeSrc;

    DWORD    dwAlignBoundaryDest;

    DWORD    dwAlignSizeDest;

    DWORD    dwAlignStrideAlign;

    DWORD    dwRops[DD_ROP_SPACE];

    DDSCAPS  ddsCaps;

    DWORD    dwMinOverlayStretch;

    DWORD    dwMaxOverlayStretch;

    DWORD    dwMinLiveVideoStretch;

    DWORD    dwMaxLiveVideoStretch;

    DWORD    dwMinHwCodecStretch;

    DWORD    dwMaxHwCodecStretch;

    DWORD    dwReserved1;

    DWORD    dwReserved2;

    DWORD    dwReserved3;

    DWORD    dwSVBCaps;

    DWORD    dwSVBCKeyCaps;

    DWORD    dwSVBFXCaps;

    DWORD    dwSVBRops[DD_ROP_SPACE];

    DWORD    dwVSBCaps;

    DWORD    dwVSBCKeyCaps;

    DWORD    dwVSBFXCaps;

    DWORD    dwVSBRops[DD_ROP_SPACE];

    DWORD    dwSSBCaps;

    DWORD    dwSSBCKeyCaps;

    DWORD    dwSSBCFXCaps;

    DWORD    dwSSBRops[DD_ROP_SPACE];

    DWORD    dwReserved4;

    DWORD    dwReserved5;

    DWORD    dwReserved6;

} DDCAPS,FAR* LPDDCAPS;

Members

dwSize

Size of the structure. This must be initialized before the structure is used.

dwCaps

Specifies driver-specific capabilities.

DDCAPS_3D

	Indicates the display hardware has 3D acceleration.
DDCAPS_ALIGNBOUNDARYDEST

	Indicates that DirectDraw will support only those source rectangles with the x-axis aligned to the DDCAPS.dwAlignBoundaryDest boundaries of the surface.
DDCAPS_ALIGNBOUNDARYSRC

	Indicates that DirectDraw will support only those source rectangles with the x-axis aligned to the DDCAPS.dwAlignBoundarySrc boundaries of the surface.
DDCAPS_ALIGNSIZEDEST

	Indicates that DirectDraw will support only those source rectangles whose x-axis size, in bytes, are DDCAPS.dwAlignSizeDest multiples.
DDCAPS_ALIGNSIZESRC

	Indicates that DirectDraw will support only those source rectangles whose x-axis size, in bytes, are DDCAPS.dwAlignSizeSrc multiples.
DDCAPS_ALIGNSTRIDE

	Indicates that DirectDraw will create display memory surfaces that have a stride alignment equal to the DDCAPS.dwAlignStrideAlign value.
DDCAPS_ALPHA

	Indicates the display hardware supports an alpha channel during blit operations.
DDCAPS_BANKSWITCHED

	Indicates the display hardware is bank switched, and is potentially very slow at random access to VRAM.
DDCAPS_BLT

	Indicates that display hardware is capable of blit operations.
DDCAPS_BLTCOLORFILL

	Indicates that display hardware is capable of color filling with blitter.
DDCAPS_BLTDEPTHFILL

	Indicates that display hardware is capable of depth filling z-buffers with blitter.
DDCAPS_BLTFOURCC

	Indicates that display hardware is capable of color space conversions during blit operations.
DDCAPS_BLTQUEUE

	Indicates that display hardware is capable of asynchronous blit operations.
DDCAPS_BLTSTRETCH

	Indicates that display hardware is capable of stretching during blit operations.
DDCAPS_CANBLTSYSMEM

	Indicates that display hardware is capable of blitting to or from system memory.
DDCAPS_CANCLIP

	Indicates that display hardware is capable of clipping with blitting.
DDCAPS_CANCLIPSTRETCHED

	Indicates that display hardware is capable of clipping while stretch blitting.
DDCAPS_COLORKEY

	Supports some form of color key in either overlay or blit operations. More specific color key capability information can be found in the dwCKeyCaps member.
DDCAPS_COLORKEYHWASSIST

	Indicates the color key is hardware assisted.
DDCAPS_GDI

	Indicates that display hardware is shared with GDI.
DDCAPS_NOHARDWARE

	Indicates no hardware support.
DDCAPS_OVERLAY

	Indicates that display hardware supports overlays.
DDCAPS_OVERLAYCANTCLIP

	Indicates that display hardware supports overlays but cannot clip them.
DDCAPS_OVERLAYFOURCC

	Indicates that overlay hardware is capable of color space conversions during overlay operations.
DDCAPS_OVERLAYSTRETCH

	Indicates that overlay hardware is capable of stretching.
DDCAPS_PALETTE

	Indicates that DirectDraw is capable of creating and supporting DirectDrawPalette objects for more surfaces than only the primary surface.
DDCAPS_PALETTEVSYNC

	Indicates that DirectDraw is capable of updating a palette synchronized with the vertical refresh.
DDCAPS_READSCANLINE

	Indicates that display hardware is capable of returning the current scan line.
DDCAPS_STEREOVIEW

	Indicates that display hardware has stereo vision capabilities.
DDCAPS_VBI

	Indicates that display hardware is capable of generating a vertical blank interrupt.
DDCAPS_ZBLTS

	Supports the use of z-buffers with blit operations.
DDCAPS_ZOVERLAYS

	Supports the use of IDirectDrawSurface::UpdateOverlayZOrder as a z-value for overlays to control their layering.
dwCaps2

Specifies more driver-specific capabilities.

DDCAPS2_CERTIFIED

	Indicates that display hardware is certified.
DDCAPS2_NO2DDURING3DSCENE

	Indicates that 2D operations such as IDirectDrawSurface::Blt and IDirectDrawSurface::Lock cannot be performed on any surfaces that Direct3D is using between IDirect3DDevice::BeginScene and IDirect3DDevice::EndScene method calls.
dwCKeyCaps

Color key capabilities.

DDCKEYCAPS_DESTBLT

	Supports transparent blitting with a color key that identifies the replaceable bits of the destination surface for RGB colors.
DDCKEYCAPS_DESTBLTCLRSPACE

	Supports transparent blitting with a color space that identifies the replaceable bits of the destination surface for RGB colors.
DDCKEYCAPS_DESTBLTCLRSPACEYUV

	Supports transparent blitting with a color space that identifies the replaceable bits of the destination surface for YUV colors.
DDCKEYCAPS_DESTBLTYUV

	Supports transparent blitting with a color key that identifies the replaceable bits of the destination surface for YUV colors.
DDCKEYCAPS_DESTOVERLAY

	Supports overlaying with color keying of the replaceable bits of the destination surface being overlaid for RGB colors.
DDCKEYCAPS_DESTOVERLAYCLRSPACE

	Supports a color space as the color key for the destination of RGB colors.
DDCKEYCAPS_DESTOVERLAYCLRSPACEYUV

	Supports a color space as the color key for the destination of YUV colors.
DDCKEYCAPS_DESTOVERLAYONEACTIVE

	Supports only one active destination color key value for visible overlay surfaces.
DDCKEYCAPS_DESTOVERLAYYUV

	Supports overlaying using color keying of the replaceable bits of the destination surface being overlaid for YUV colors.
DDCKEYCAPS_NOCOSTOVERLAY

	Indicates there are no bandwidth trade-offs for using color key with an overlay.
DDCKEYCAPS_SRCBLT

	Supports transparent blitting using the color key for the source with this surface for RGB colors.
DDCKEYCAPS_SRCBLTCLRSPACE

	Supports transparent blitting using a color space for the source with this surface for RGB colors.
DDCKEYCAPS_SRCBLTCLRSPACEYUV

	Supports transparent blitting using a color space for the source with this surface for YUV colors.
DDCKEYCAPS_SRCBLTYUV

	Supports transparent blitting using the color key for the source with this surface for YUV colors.
DDCKEYCAPS_SRCOVERLAY

	Supports overlaying using the color key for the source with this overlay surface for RGB colors.
DDCKEYCAPS_SRCOVERLAYCLRSPACE

	Supports overlaying using a color space as the source color key for the overlay surface for RGB colors.
DDCKEYCAPS_SRCOVERLAYCLRSPACEYUV

	Supports overlaying using a color space as the source color key for the overlay surface for YUV colors.
DDCKEYCAPS_SRCOVERLAYONEACTIVE

	Supports only one active source color key value for visible overlay surfaces.
DDCKEYCAPS_SRCOVERLAYYUV

	Supports overlaying using the color key for the source with this overlay surface for YUV colors.
dwFXCaps

Specifies driver-specific stretching and effects capabilities.

DDFXCAPS_BLTARITHSTRETCHY

	Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink surfaces during a blit operation. Occurs along the y-axis (vertically).
DDFXCAPS_BLTARITHSTRETCHYN

	Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink surfaces during a blit operation. Occurs along the y-axis (vertically), and only works for integer stretching (×1, ×2, and so on).
DDFXCAPS_BLTMIRRORLEFTRIGHT

	Supports mirroring left to right in a blit operation.
DDFXCAPS_BLTMIRRORUPDOWN

	Supports mirroring top to bottom in a blit operation.
DDFXCAPS_BLTROTATION

	Supports arbitrary rotation in a blit operation.
DDFXCAPS_BLTROTATION90

	Supports 90 degree rotations in a blit operation.
DDFXCAPS_BLTSHRINKX

	Supports arbitrary shrinking of a surface along the x-axis (horizontally). This flag is only valid for blit operations.
DDFXCAPS_BLTSHRINKXN

	Supports integer shrinking (×1, ×2, and so on) of a surface along the x-axis (horizontally). This flag is only valid for blit operations.
DDFXCAPS_BLTSHRINKY

	Supports arbitrary shrinking of a surface along the y-axis (vertically). This flag is only valid for blit operations.
DDFXCAPS_BLTSHRINKYN

	Supports integer shrinking (×1, ×2, and so on) of a surface along the y-axis (vertically). This flag is only valid for blit operations.
DDFXCAPS_BLTSTRETCHX

	Supports arbitrary stretching of a surface along the x-axis (horizontally). This flag is only valid for blit operations.
DDFXCAPS_BLTSTRETCHXN

	Supports integer stretching (×1, ×2, and so on) of a surface along the x-axis (horizontally). This flag is only valid for blit operations.
DDFXCAPS_BLTSTRETCHY

	Supports arbitrary stretching of a surface along the y-axis (vertically). This flag is only valid for blit operations.
DDFXCAPS_BLTSTRETCHYN

	Supports integer stretching (×1, ×2, and so on) of a surface along the y-axis (vertically). This flag is only valid for blit operations.
DDFXCAPS_OVERLAYARITHSTRETCHY

	Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink surfaces during an overlay operation. Occurs along the y-axis (vertically).
DDFXCAPS_OVERLAYARITHSTRETCHYN

	Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink surfaces during an overlay operation. Occurs along the y-axis (vertically), and only works for integer stretching (×1, ×2, and so on).
DDFXCAPS_OVERLAYMIRRORLEFTRIGHT

	Supports mirroring of overlays around the vertical axis.
DDFXCAPS_OVERLAYMIRRORUPDOWN

	Supports mirroring of overlays across the horizontal axis.
DDFXCAPS_OVERLAYSHRINKX

	Supports arbitrary shrinking of a surface along the x-axis (horizontally). This flag is only valid for DDSCAPS_OVERLAY surfaces. This flag only indicates the capabilities of a surface; it does not indicate that shrinking is available.
DDFXCAPS_OVERLAYSHRINKXN

	Supports integer shrinking (×1, ×2, and so on) of a surface along the x-axis (horizontally). This flag is only valid for DDSCAPS_OVERLAY surfaces. This flag only indicates the capabilities of a surface; it does not indicate that shrinking is available.
DDFXCAPS_OVERLAYSHRINKY

	Supports arbitrary shrinking of a surface along the y-axis (vertically). This flag is only valid for DDSCAPS_OVERLAY surfaces. This flag only indicates the capabilities of a surface; it does not indicate that shrinking is available.
DDFXCAPS_OVERLAYSHRINKYN

	Supports integer shrinking (x1, x2, and so on) of a surface along the y-axis (vertically). This flag is only valid for DDSCAPS_OVERLAY surfaces. This flag only indicates the capabilities of a surface; it does not indicate that shrinking is available.
DDFXCAPS_OVERLAYSTRETCHX

	Supports arbitrary stretching of a surface along the x-axis (horizontally). This flag is only valid for DDSCAPS_OVERLAY surfaces. This flag only indicates the capabilities of a surface; it does not indicate that stretching is available.
DDFXCAPS_OVERLAYSTRETCHXN

	Supports integer stretching (x1, x2, and so on) of a surface along the x-axis (horizontally). This flag is only valid for DDSCAPS_OVERLAY surfaces. This flag only indicates the capabilities of a surface; it does not indicate that stretching is available.
DDFXCAPS_OVERLAYSTRETCHY

	Supports arbitrary stretching of a surface along the y-axis (vertically). This flag is only valid for DDSCAPS_OVERLAY surfaces. This flag only indicates the capabilities of a surface; it does not indicate that stretching is available.
DDFXCAPS_OVERLAYSTRETCHYN

	Supports integer stretching (x1, x2, and so on) of a surface along the y-axis (vertically). This flag is only valid for DDSCAPS_OVERLAY surfaces. This flag only indicates the capabilities of a surface; it does not indicate that stretching is available.
dwFXAlphaCaps

Specifies driver-specific alpha capabilities.

DDFXALPHACAPS_BLTALPHAEDGEBLEND

	Supports alpha blending around the edge of a source color keyed surface. Used for blit operations.
DDFXALPHACAPS_BLTALPHAPIXELS

	Supports alpha information in pixel format. The bit depth of alpha information in the pixel format can be 1, 2, 4, or 8. The alpha value becomes more opaque as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully transparent value. Used for blit operations.
DDFXALPHACAPS_BLTALPHAPIXELSNEG

	Supports alpha information in pixel format. The bit depth of alpha information in the pixel format can be 1, 2, 4, or 8. The alpha value becomes more transparent as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully opaque value. This flag can only be set if DDCAPS_ALPHA is set. Used for blit operations.
DDFXALPHACAPS_BLTALPHASURFACES

	Supports alpha-only surfaces. The bit depth of an alpha-only surface can be 1, 2, 4, or 8. The alpha value becomes more opaque as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully transparent value. Used for blit operations.
DDFXALPHACAPS_BLTALPHASURFACESNEG

	Indicates the depth of the alpha channel data can be 1, 2, 4, or 8. The NEG suffix indicates this alpha channel becomes more transparent as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully opaque value. This flag can only be set if DDFXCAPS_ALPHASURFACES has been set. Used for blit operations.
DDFXALPHACAPS_OVERLAYALPHAEDGEBLEND

	Supports alpha blending around the edge of a source color keyed surface. Used for overlays.
DDFXALPHACAPS_OVERLAYALPHAPIXELS

	Supports alpha information in pixel format. The bit depth of alpha information in pixel format can be 1, 2, 4, or 8. The alpha value becomes more opaque as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully transparent value. Used for overlays.
DDFXALPHACAPS_OVERLAYALPHAPIXELSNEG

	Supports alpha information in pixel format. The bit depth of alpha information in pixel format can be 1, 2, 4, or 8. The alpha value becomes more transparent as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully opaque value. This flag can only be set if DDFXCAPS_ALPHAPIXELS has been set. Used for overlays.
DDFXALPHACAPS_OVERLAYALPHASURFACES

	Supports alpha-only surfaces. The bit depth of an alpha-only surface can be 1, 2, 4, or 8. The alpha value becomes more opaque as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully transparent value. Used for overlays.
DDFXALPHACAPS_OVERLAYALPHASURFACESNEG

	Indicates the depth of the alpha channel data can be 1, 2, 4, or 8. The NEG suffix indicates this alpha channel becomes more transparent as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully opaque value. This flag can only be set if DDFXCAPS_ALPHASURFACES has been set. Used for overlays.
dwPalCaps

Specifies palette capabilities.

DDPCAPS_1BIT

	The index is 1 bit. There are two entries in the palette table.
DDPCAPS_2BIT

	The index is 2 bits. There are four entries in the palette table.
DDPCAPS_4BIT

	The index is 4 bits. There are sixteen entries in the palette table.
DDPCAPS_8BIT

	The index is 8 bits. There are 256 entries in the palette table.
DDPCAPS_8BITENTRIES

	An index to an 8-bit color index. This field is only valid when used with the DDPCAPS_1BIT, DDPCAPS_2BIT, or DDPCAPS_4BIT capability and when the target surface is in 8 bits per pixel (bpp). Each color entry is one byte long and is an index to an 8-bpp palette on the destination surface.
DDPCAPS_ALLOW256

	Indicates this palette can have all 256 entries defined.
DDPCAPS_PRIMARYSURFACE

	Indicates the palette is attached to the primary surface. Changing this table has an immediate effect on the display unless the DDPCAPS_VSYNC capability is specified and supported.
DDPCAPS_PRIMARYSURFACELEFT

	Indicates the palette is attached to the primary surface on the left. Changing this table has an immediate effect on the display unless the DDPCAPS_VSYNC capability is specified and supported.
DDPCAPS_VSYNC

	Indicates the palette can be modified synchronously with the monitor's refresh rate.
dwSVCaps

Specifies stereo vision capabilities.

DDSVCAPS_ENIGMA

	Indicates the stereo view is accomplished using Enigma encoding.
DDSVCAPS_FLICKER

	Indicates the stereo view is accomplished using high-frequency flickering.
DDSVCAPS_REDBLUE

	Indicates the stereo view is accomplished using red and blue filters applied to the left and right eyes. All images must adapt their color spaces for this process.
DDSVCAPS_SPLIT

	Indicates the stereo view is accomplished with split-screen technology.
dwAlphaBltConstBitDepths

DDBD_2,4,8

dwAlphaBltPixelBitDepths

DDBD_1,2,4,8

dwAlphaBltSurfaceBitDepths

DDBD_1,2,4,8

dwAlphaOverlayConstBitDepths

DDBD_2,4,8

dwAlphaOverlayPixelBitDepths

DDBD_1,2,4,8

dwAlphaOverlaySurfaceBitDepths

DDBD_1,2,4,8

dwZBufferBitDepths

DDBD_8,16,24,32

dwVidMemTotal

Total amount of display memory.

dwVidMemFree

Amount of free display memory.

dwMaxVisibleOverlays

Maximum number of visible overlays.

dwCurrVisibleOverlays

Current number of visible overlays.

dwNumFourCCCodes

Number of FourCC codes.

dwAlignBoundarySrc

Source rectangle alignment.

dwAlignSizeSrc

Source rectangle byte size.

dwAlignBoundaryDest

Destination rectangle alignment.

dwAlignSizeDest

Destination rectangle byte size.

dwAlignStrideAlign

Stride alignment.

dwRops[DD_ROP_SPACE]

Raster operations supported.

ddsCaps

Indicates a DDSCAPS structure with general capabilities.

dwMinOverlayStretch

Minimum overlay stretch factor multiplied by 1000. For example, 1.0 = 1000, 1.3 = 1300.

dwMaxOverlayStretch

Maximum overlay stretch factor multiplied by 1000. For example, 1.0 = 1000, 1.3 = 1300.

dwMinLiveVideoStretch

Minimum live video stretch factor multiplied by 1000. For example, 1.0 = 1000, 1.3 = 1300.

dwMaxLiveVideoStretch

Maximum live video stretch factor multiplied by 1000. For example, 1.0 = 1000, 1.3 = 1300.

dwMinHwCodecStretch

Minimum hardware codec stretch factor multiplied by 1000. For example 1.0 = 1000, 1.3 = 1300.

dwMaxHwCodecStretch

Maximum hardware codec stretch factor multiplied by 1000. For example, 1.0 = 1000, 1.3 = 1300.

dwReserved1,#dwReserved2,#dwReserved3

Reserved for future use.

dwSVBCaps

Specifies the driver-specific capabilities for system memory to display memory blits.

dwSVBCKeyCaps

Specifies the driver color key capabilities for system memory to display memory blits.

dwSVBFXCaps

Specifies the driver FX capabilities for system memory to display memory blits.

dwSVBRops[DD_ROP_SPACE]

Specifies the raster operations supported for system memory to display memory blits.

dwVSBCaps

Specifies the driver-specific capabilities for display memory to system memory blits.

dwVSBCKeyCaps

Specifies the driver color key capabilities for display memory to system memory blits.

dwVSBFXCaps

Specifies the driver FX capabilities for display memory to system memory blits.

dwVSBRops[DD_ROP_SPACE]

Supports raster operations for display memory to system memory blits.

dwSSBCaps

Specifies the driver-specific capabilities for system memory to system memory blits.

dwSSBCKeyCaps

Specifies the driver color key capabilities for system memory to system memory blits.

dwSSBCFXCaps

Specifies the driver FX capabilities for system memory to system memory blits.

dwSSBRops[DD_ROP_SPACE]

Raster operations supported for system memory to system memory blits.

dwReserved4, #dwReserved5, #dwReserved6

Reserved for future use.

Remarks

The values for the dw...BitDepths members (dwAlphaBltConstBitDepths, dwAlphaBltPixelBitDepths, dwAlphBltSurfaceBitDepths, and so on) are:

DDBD_1	1 bit per pixel.
DDBD_2	2 bits per pixel.
DDBD_4	4 bits per pixel.
DDBD_8	8 bits per pixel.
DDBD_16	16 bits per pixel.
DDBD_24	24 bits per pixel.
DDBD_32	32 bits per pixel.


DDCOLORKEY

Describes a source or destination color key or color space. A color key is specified if the low and high range values are the same.

typedef struct _DDCOLORKEY{

    DWORD  dwColorSpaceLowValue;

    DWORD  dwColorSpaceHighValue;

} DDCOLORKEY,FAR* LPDDCOLORKEY;

Members

dwColorSpaceLowValue

Low value, inclusive, of the color range that is to be used as the color key.

dwColorSpaceHighValue

High value, inclusive, of the color range that is to be used as the color key.


DDOVERLAYFX

Passes override information to the IDirectDrawSurface::UpdateOverlay method.

typedef struct _DDOVERLAYFX{

    DWORD  dwSize;

    DWORD  dwAlphaEdgeBlendBitDepth;

    DWORD  dwAlphaEdgeBlend;

    DWORD  dwReserved;

    DWORD  dwAlphaDestConstBitDepth;

union

{

        DWORD                dwAlphaDestConst;

        LPDIRECTDRAWSURFACE  lpDDSAlphaDest;

};

    DWORD  dwAlphaSrcConstBitDepth;

union

{

        DWORD                dwAlphaSrcConst;

        LPDIRECTDRAWSURFACE  lpDDSAlphaSrc;

};

    DDCOLORKEY  dckDestColorkey;

    DDCOLORKEY  dckSrcColorkey;

    DWORD       dwDDFX;

    DWORD       dwFlags;

} DDOVERLAYFX,FAR *LPDDOVERLAYFX;

Members

dwSize

Size of the structure. This must be initialized before the structure is used.

dwAlphaEdgeBlendBitDepth

Bit depth used to specify the constant for an alpha edge blend.

dwAlphaEdgeBlend

Constant to use as the alpha for an edge blend.

dwReserved

Reserved for future use.

dwAlphaDestConstBitDepth

Bit depth used to specify the alpha constant for a destination.

dwAlphaDestConst

Constant to use as the alpha channel for a destination.

lpDDSAlphaDest

Address of a surface to use as the alpha channel for a destination.

dwAlphaSrcConstBitDepth

Bit depth used to specify the alpha constant for a source.

dwAlphaSrcConst

Constant to use as the alpha channel for a source.

lpDDSAlphaSrc

Address of a surface to use as the alpha channel for a source.

dckDestColorkey

Destination color key override.

dckSrcColorkey

Source color key override.

dwDDFX

Overlay FX flags.I

DDOVERFX_ARITHSTRETCHY

	If stretching, use arithmetic stretching along the y-axis for this overlay.
DDOVERFX_MIRRORLEFTRIGHT

	Mirror the overlay around the vertical axis.
DDOVERFX_MIRRORUPDOWN

	Mirror the overlay around the horizontal axis.
dwFlags

This member is not used at this time and must be set to 0.


DDPIXELFORMAT

Describes the pixel format of a DirectDrawSurface object.

typedef struct _DDPIXELFORMAT{

    DWORD  dwSize;

    DWORD  dwFlags;

    DWORD  dwFourCC;

union

{

        DWORD  dwRGBBitCount;

        DWORD  dwYUVBitCount;

        DWORD  dwZBufferBitDepth;

        DWORD  dwAlphaBitDepth;

};

union

{

        DWORD  dwRBitMask;

        DWORD  dwYBitMask;

};

union

{

        DWORD  dwGBitMask;

        DWORD  dwUBitMask;

};

union

{

        DWORD  dwBBitMask;

        DWORD  dwVBitMask;

};

union

{

        DWORD  dwRGBAlphaBitMask;

        DWORD  dwYUVAlphaBitMask;

};

} DDPIXELFORMAT, FAR* LPDDPIXELFORMAT;

Members

dwSize

Size of the structure. This must be initialized before the structure is used.

dwFlags

Specifies the optional control flags.

DDPF_ALPHA

	The pixel format describes an alpha-only surface.
DDPF_ALPHAPIXELS

	The surface has alpha-channel information in the pixel format.
DDPF_COMPRESSED

	The surface will accept pixel data in the specified format and compress it during the write operation.
DDPF_FOURCC

	The FourCC code is valid.
DDPF_PALETTEINDEXED1

	The surface is 1-bit color indexed.
DDPF_PALETTEINDEXED2

	The surface is 2-bit color indexed.
DDPF_PALETTEINDEXED4

	The surface is 4-bit color indexed.
DDPF_PALETTEINDEXED8

	The surface is 8-bit color indexed.
DDPF_PALETTEINDEXEDTO8

	The surface is 1-, 2-, or 4-bit color indexed to an 8-bit palette.
DDPF_RGB

	The RGB data in the pixel format structure is valid.
DDPF_RGBTOYUV

	The surface will accept RGB data and translate it during the write operation to YUV data. The format of the data to be written will be contained in the pixel format structure. The DDPF_RGB flag will be set.
DDPF_YUV

	The YUV data in the pixel format structure is valid.
DDPF_ZBUFFER

	The pixel format describes a z-buffer-only surface.
dwFourCC

FourCC code.

dwRGBBitCount

RGB bits per pixel (DDBD_4,8,16,24,32)

dwYUVBitCount

YUV bits per pixel (DDBD_4,8,16,24,32)

dwZBufferBitDepth

Z-buffer bit depth. (DDBD_8,16,24,32)

dwAlphaBitDepth

Alpha channel bit depth. (DDBD_1,2,4,8)

dwRBitMask

Mask for red bits.

dwYBitMask

Mask for Y bits.

dwGBitMask

Mask for green bits.

dwUBitMask

Mask for U bits.

dwBBitMask

Mask for blue bits.

dwVBitMask

Mask for V bits.

dwRGBAlphaBitMask

Mask for alpha channel.

dwYUVAlphaBitMask

Mask for alpha channel.


DDSCAPS

Defines the capabilities of a DirectDrawSurface. It is part of the DDCAPS structure that is used to describe the capabilities of the DirectDraw object.

typedef struct _DDSCAPS{

        DWORD  dwCaps;

} DDSCAPS,  FAR* LPDDSCAPS;

Members

dwCaps

Specifies the capabilities of the surface.

DDSCAPS_3D

	Supported for backwards compatibility. Applications should use the DDSCAPS_3DDEVICE flag, instead.
DDSCAPS_3DDEVICE

	Indicates that this surface can be used for 3D rendering. Applications can use this flag to ensure that a device that can only render to a certain heap have off-screen surfaces allocated from the correct heap. If this flag is set for a heap, the surface will not be allocated from that heap.
DDSCAPS_ALLOCONLOAD

	Indicates that memory for the surface is not allocated until the surface is loaded using the IDirect3DTexture::Load method.
DDSCAPS_ALPHA

	Indicates that this surface contains alpha information. The pixel format must be interrogated to determine whether this surface contains only alpha information or alpha information interlaced with pixel color data (such as RGBA or YUVA).
DDSCAPS_BACKBUFFER

	Indicates that this surface is THE back buffer of a surface flipping structure. Generally, this capability is set by the IDirectDraw::CreateSurface method when the DDSCAPS_FLIP capability is set. Only the surface that immediately precedes the DDSCAPS_FRONTBUFFER has this capability set. The other surfaces are identified as back buffers by the presence of the DDSCAPS_FLIP flag, their attachment order, and the absence of the DDSCAPS_FRONTBUFFER and DDSCAPS_BACKBUFFER capabilities. If this capability is sent to the IDirectDraw::CreateSurface method, a standalone back buffer is being created. This surface could be attached to a front buffer, another back buffer, or both to form a flipping surface structure after this method is called. See the IDirectDrawSurface::AddAttachedSurface method for a detailed description of the behaviors in this case. DirectDraw supports n surfaces in a surface flipping structure.
DDSCAPS_COMPLEX

	Indicates a complex surface structure is being described. A complex surface structure results in the creation of more than one surface. The additional surfaces are attached to the root surface. The complex structure can only be destroyed by destroying the root.
DDSCAPS_FLIP

	Indicates that this surface is a part of a surface flipping structure. When this capability is passed to the IDirectDraw::CreateSurface method, the DDSCAPS_FRONTBUFFER and DDSCAPS_BACKBUFFER capabilities are not set. Both can be set by this method on resulting creations. The dwBackBufferCount member in the DDSURFACEDESC structure must be set to at least 1 in order for the method call to succeed. The DDSCAPS_COMPLEX capability must always be set when creating multiple surfaces through the IDirectDraw::CreateSurface method.
DDSCAPS_FRONTBUFFER

	Indicates that this surface is the front buffer of a surface flipping structure. It is generally set by the IDirectDraw::CreateSurface method when the DDSCAPS_FLIP capability is set. If this capability is sent to the IDirectDraw::CreateSurface method, a standalone front buffer is created. This surface will not have the DDSCAPS_FLIP capability. It can be attached to other back buffers to form a flipping structure on resulting creations. See the IDirectDrawSurface::AddAttachedSurface method for a detailed description of the behaviors in this case.
DDSCAPS_HWCODEC

	Indicates that this surface should be able to have a stream decompressed to it by the hardware.
DDSCAPS_LIVEVIDEO

	Indicates that this surface should be able to receive live video.
DDSCAPS_MIPMAP

	Indicates that this surface is one level of a mipmap. This surface will be attached to other DDSCAPS_MIPMAP surfaces to form the mipmap. This can be done explicitly by creating a number of surfaces and attaching them with the IDirectDrawSurface::AddAttachedSurface method, or implicitly by the IDirectDraw::CreateSurface method. If this capability is set, then DDSCAPS_TEXTURE must also be set.
DDSCAPS_MODEX

	Indicates that this surface is a 320 x 200 or 320 x 240 ModeX surface.
DDSCAPS_OFFSCREENPLAIN

	Indicates that this surface is any off-screen surface that is not an overlay, texture, z-buffer, front buffer, back buffer, or alpha surface. It is used to identify plain surfaces.
DDSCAPS_OVERLAY

	Indicates that this surface is an overlay. It may or may not be directly visible depending on whether it is currently being overlaid onto the primary surface. DDSCAPS_VISIBLE can be used to determine if it is being overlaid at the moment.
DDSCAPS_OWNDC

	Indicates that this surface will have a DC association for a long period.
DDSCAPS_PALETTE

	Indicates that this device driver allows unique DirectDrawPalette objects to be created and attached to this surface.
DDSCAPS_PRIMARYSURFACE

	Indicates the surface is the primary surface. It represents what is visible to the user at the moment.
DDSCAPS_PRIMARYSURFACELEFT

	Indicates that this surface is the primary surface for the left eye. It represents what is visible to the user's left eye at the moment. When this surface is created, the surface with the DDSCAPS_PRIMARYSURFACE capability represents what is seen by the user's right eye.
DDSCAPS_SYSTEMMEMORY

	Indicates that this surface memory was allocated in system memory.
DDSCAPS_TEXTURE

	Indicates that this surface can be used as a 3D texture. It does not indicate if the surface is being used for that purpose.
DDSCAPS_VIDEOMEMORY

	Indicates that this surface exists in display memory.
DDSCAPS_VISIBLE

	Indicates that changes made to this surface are immediately visible. It is always set for the primary surface and is set for overlays while they are being overlaid and texture maps while they are being textured.
DDSCAPS_WRITEONLY

	Indicates that only write access is permitted to the surface. Read access from the surface may generate a protection fault, but the read results from this surface will not be meaningful.
DDSCAPS_ZBUFFER

	Indicates that this surface is the z-buffer. The z-buffer contains information that cannot be displayed. Instead, it contains bit-depth information that is used to determine which pixels are visible and which are obscured.


DDSURFACEDESC

Is passed to the IDirectDraw::CreateSurface method with a description of the surface that should be created. The relevant members differ for each potential type of surface.

typedef struct _DDSURFACEDESC{

    DWORD  dwSize;

    DWORD  dwFlags;

    DWORD  dwHeight;

    DWORD  dwWidth;

    LONG   lPitch,

    DWORD  dwBackBufferCount,

    union

    {

        DWORD  dwMipMapCount,

        DWORD  dwZBufferBitDepth,

        DWORD  dwRefreshRate,

    };

    DWORD          dwAlphaBitDepth;

    DWORD          dwReserved;

    LPVOID         lpSurface;

    DDCOLORKEY     ddckCKDestOverlay;

    DDCOLORKEY     ddckCKDestBlt;

    DDCOLORKEY     ddckCKSrcOverlay;

    DDCOLORKEY     ddckCKSrcBlt;

    DDPIXELFORMAT  ddpfPixelFormat;

    DDSCAPS        ddsCaps;

} DDSURFACEDESC,  FAR* LPDDSURFACEDESC;

Members

dwSize

Size of the structure. This must be initialized before the structure is used.

dwFlags

Specifies the optional control flags.

DDSD_ALL

	All input members are valid.
DDSD_ALPHABITDEPTH

	Indicates the dwAlphaBitDepth member is valid.
DDSD_BACKBUFFERCOUNT

	Indicates the dwBackBufferCount member is valid.
DDSD_CAPS

	Indicates the ddsCaps member is valid.
DDSD_CKDESTBLT

	Indicates the ddckCKDestBlt member is valid.
DDSD_CKDESTOVERLAY

	Indicates the ddckCKDestOverlay member is valid.
DDSD_CKSRCBLT

	Indicates the ddckCKSrcBlt member is valid.
DDSD_CKSRCOVERLAY

	Indicates the ddckCKSrcOverlay member is valid.
DDSD_HEIGHT

	Indicates the dwHeight member is valid.
DDSD_MIPMAPCOUNT

	Indicates the dwMipMapCount member is valid.
DDSD_PITCH

	Indicates the lPitch member is valid.
DDSD_PIXELFORMAT

	Indicates the ddpfPixelFormat member is valid.
DDSD_REFRESHRATE

	Indicates the dwRefreshRate member is valid.
DDSD_WIDTH

	Indicates the dwWidth member is valid.
DDSD_ZBUFFERBITDEPTH

	Indicates the dwZBufferBitDepth member is valid.
dwHeight

Height of surface.

dwWidth

Width of input surface.

lPitch

Distance to start of next line (return value only).

dwBackBufferCount

Number of back buffers.

dwMipMapCount

Number of mipmap levels.

dwZBufferBitDepth

Depth of z-buffer.

dwRefreshRate

Refresh rate (used when the display mode is described).

dwAlphaBitDepth

Depth of alpha buffer.

dwReserved

Reserved.

lpSurface

Address of the associated surface memory.

ddckCKDestOverlay

Color key for destination overlay use.

ddckCKDestBlt

Color key for destination blit use.

ddckCKSrcOverlay

Color key for source overlay use.

ddckCKSrcBlt

Color key for source blit use.

ddpfPixelFormat

Pixel format description of the surface.

ddsCaps

DirectDraw surface capabilities.

Remarks

The information in the dwFlags member has been changed since the DirectX 2 SDK was released. For a complete list of new information, see New Information.


Return Values

Errors are represented by negative values and cannot be combined. This table lists the values that can be returned by all IDirectDraw, IDirectDrawSurface, IDirectDrawPalette, and IDirectDrawClipper methods. For a list of the error codes each method is capable of returning, see the individual method descriptions.

DD_OK

	The request completed successfully.
DDERR_ALREADYINITIALIZED

	The object has already been initialized.
DDERR_BLTFASTCANTCLIP

	A clipper object is attached to a source surface that has passed into a call to the IDirectDrawSurface::BltFast method.
DDERR_CANNOTATTACHSURFACE

	A surface cannot be attached to another requested surface.
DDERR_CANNOTDETACHSURFACE

	A surface cannot be detached from another requested surface.
DDERR_CANTCREATEDC

	Windows cannot create any more device contexts (DCs).
DDERR_CANTDUPLICATE

	Primary and 3D surfaces, or surfaces that are implicitly created, cannot be duplicated.
DDERR_CANTLOCKSURFACE

	Access to this surface is refused because an attempt was made to lock the primary surface without DCI support.
DDERR_CANTPAGELOCK

	An attempt to page lock a surface failed. Page lock will not work on a display memory surface or an emulated primary surface.
DDERR_CANTPAGEUNLOCK

	An attempt to page unlock a surface failed. Page unlock will not work on a display memory surface or an emulated primary surface.
DDERR_CLIPPERISUSINGHWND

	An attempt was made to set a clip list for a clipper object that is already monitoring an hWnd.
DDERR_COLORKEYNOTSET

	No source color key is specified for this operation.
DDERR_CURRENTLYNOTAVAIL

	No support is currently available.
DDERR_DCALREADYCREATED

	A device context has already been returned for this surface. Only one device context can be retrieved for each surface.
DDERR_DIRECTDRAWALREADYCREATED

	A DirectDraw object representing this driver has already been created for this process.
DDERR_EXCEPTION

	An exception was encountered while performing the requested operation.
DDERR_EXCLUSIVEMODEALREADYSET

	An attempt was made to set the cooperative level when it was already set to exclusive.
DDERR_GENERIC

	There is an undefined error condition.
DDERR_HEIGHTALIGN

	The height of the provided rectangle is not a multiple of the required alignment.
DDERR_HWNDALREADYSET

	The DirectDraw CooperativeLevel HWND has already been set. It cannot be reset while the process has surfaces or palettes created.
DDERR_HWNDSUBCLASSED

	DirectDraw is prevented from restoring state because the DirectDraw CooperativeLevel HWND has been subclassed.
DDERR_IMPLICITLYCREATED

	The surface cannot be restored because it is an implicitly created surface.
DDERR_INCOMPATIBLEPRIMARY

	The primary surface creation request does not match with the existing primary surface.
DDERR_INVALIDCAPS

	One or more of the capability bits passed to the callback function are incorrect.
DDERR_INVALIDCLIPLIST

	DirectDraw does not support the provided clip list.
DDERR_INVALIDDIRECTDRAWGUID

	The GUID passed to the DirectDrawCreate function is not a valid DirectDraw driver identifier.
DDERR_INVALIDMODE

	DirectDraw does not support the requested mode.
DDERR_INVALIDOBJECT

	DirectDraw received a pointer that was an invalid DirectDraw object.
DDERR_INVALIDPARAMS

	One or more of the parameters passed to the method are incorrect.
DDERR_INVALIDPIXELFORMAT

	The pixel format was invalid as specified.
DDERR_INVALIDPOSITION

	The position of the overlay on the destination is no longer legal.
DDERR_INVALIDRECT

	The provided rectangle was invalid.
DDERR_INVALIDSURFACETYPE

	The requested operation could not be performed because the surface was of the wrong type.
DDERR_LOCKEDSURFACES

	One or more surfaces are locked, causing the failure of the requested operation.
DDERR_NO3D

	No 3D is present.
DDERR_NOALPHAHW

	No alpha acceleration hardware is present or available, causing the failure of the requested operation.
DDERR_NOBLTHW

	No blitter hardware is present.
DDERR_NOCLIPLIST

	No clip list is available.
DDERR_NOCLIPPERATTACHED

	No clipper object is attached to the surface object.
DDERR_NOCOLORCONVHW

	The operation cannot be carried out because no color conversion hardware is present or available.
DDERR_NOCOLORKEY

	The surface does not currently have a color key.
DDERR_NOCOLORKEYHW

	The operation cannot be carried out because there is no hardware support for the destination color key.
DDERR_NOCOOPERATIVELEVELSET

	A create function is called without the IDirectDraw::SetCooperativeLevel method being called.
DDERR_NODC

	No device context (DC) has ever been created for this surface.
DDERR_NODDROPSHW

	No DirectDraw raster operation (ROP) hardware is available.
DDERR_NODIRECTDRAWHW

	Hardware-only DirectDraw object creation is not possible; the driver does not support any hardware.
DDERR_NODIRECTDRAWSUPPORT

	DirectDraw support is not possible with the current display driver.
DDERR_NOEMULATION

	Software emulation is not available.
DDERR_NOEXCLUSIVEMODE

	The operation requires the application to have exclusive mode, but the application does not have exclusive mode.
DDERR_NOFLIPHW

	Flipping visible surfaces is not supported.
DDERR_NOGDI

	No GDI is present.
DDERR_NOHWND

	Clipper notification requires an HWND, or no HWND has been previously set as the CooperativeLevel HWND.
DDERR_NOMIPMAPHW

	The operation cannot be carried out because no mipmap texture mapping hardware is present or available.
DDERR_NOMIRRORHW

	The operation cannot be carried out because no mirroring hardware is present or available.
DDERR_NOOVERLAYDEST

	The IDirectDrawSurface::GetOverlayPosition method is called on an overlay that the IDirectDrawSurface::UpdateOverlay method has not been called on to establish a destination.
DDERR_NOOVERLAYHW

	The operation cannot be carried out because no overlay hardware is present or available.
DDERR_NOPALETTEATTACHED

	No palette object is attached to this surface.
DDERR_NOPALETTEHW

	There is no hardware support for 16- or 256-color palettes.
DDERR_NORASTEROPHW

	The operation cannot be carried out because no appropriate raster operation hardware is present or available.
DDERR_NOROTATIONHW

	The operation cannot be carried out because no rotation hardware is present or available.
DDERR_NOSTRETCHHW

	The operation cannot be carried out because there is no hardware support for stretching.
DDERR_NOT4BITCOLOR

	The DirectDrawSurface is not using a 4-bit color palette and the requested operation requires a 4-bit color palette.
DDERR_NOT4BITCOLORINDEX

	The DirectDrawSurface is not using a 4-bit color index palette and the requested operation requires a 4-bit color index palette.
DDERR_NOT8BITCOLOR

	The DirectDrawSurface is not using an 8-bit color palette and the requested operation requires an 8-bit color palette.
DDERR_NOTAOVERLAYSURFACE

	An overlay component is called for a non-overlay surface
DDERR_NOTEXTUREHW

	The operation cannot be carried out because no texture mapping hardware is present or available.
DDERR_NOTFLIPPABLE

	An attempt has been made to flip a surface that cannot be flipped.
DDERR_NOTFOUND

	The requested item was not found.
DDERR_NOTINITIALIZED

	An attempt was made to invoke an interface method of a DirectDraw object created by CoCreateInstance before the object was initialized.
DDERR_NOTLOCKED

	An attempt is made to unlock a surface that was not locked.
DDERR_NOTPAGELOCKED

	An attempt is made to page unlock a surface with no outstanding page locks.
DDERR_NOTPALETTIZED

	The surface being used is not a palette-based surface.
DDERR_NOVSYNCHW

	The operation cannot be carried out because there is no hardware support for vertical blank synchronized operations.
DDERR_NOZBUFFERHW

	The operation cannot be carried out because there is no hardware support for z-buffers when creating a z-buffer in display memory or when performing a z-aware blit.
DDERR_NOZOVERLAYHW

	The overlay surfaces cannot be z-layered based on their BltOrder because the hardware does not support z-layering of overlays.
DDERR_OUTOFCAPS

	The hardware needed for the requested operation has already been allocated.
DDERR_OUTOFMEMORY

	DirectDraw does not have enough memory to perform the operation.
DDERR_OUTOFVIDEOMEMORY

	DirectDraw does not have enough display memory to perform the operation.
DDERR_OVERLAYCANTCLIP

	The hardware does not support clipped overlays.
DDERR_OVERLAYCOLORKEYONLYONEACTIVE

	An attempt was made to have more than one color key active on an overlay.
DDERR_OVERLAYNOTVISIBLE

	The IDirectDrawSurface::GetOverlayPosition method is called on a hidden overlay.
DDERR_PALETTEBUSY

	Access to this palette is refused because the palette is locked by another thread.
DDERR_PRIMARYSURFACEALREADYEXISTS

	This process has already created a primary surface.
DDERR_REGIONTOOSMALL

	The region passed to the IDirectDrawClipper::GetClipList method is too small.
DDERR_SURFACEALREADYATTACHED

	An attempt was made to attach a surface to another surface to which it is already attached.
DDERR_SURFACEALREADYDEPENDENT

	An attempt was made to make a surface a dependency of another surface to which it is already dependent.
DDERR_SURFACEBUSY

	Access to this surface is refused because the surface is locked by another thread.
DDERR_SURFACEISOBSCURED

	Access to the surface is refused because the surface is obscured.
DDERR_SURFACELOST

	Access to this surface is refused because the surface memory is gone. The DirectDrawSurface object representing this surface should have the IDirectDrawSurface::Restore method called on it.
DDERR_SURFACENOTATTACHED

	The requested surface is not attached.
DDERR_TOOBIGHEIGHT

	The height requested by DirectDraw is too large.
DDERR_TOOBIGSIZE

	The size requested by DirectDraw is too large. However, the individual height and width are OK.
DDERR_TOOBIGWIDTH

	The width requested by DirectDraw is too large.
DDERR_UNSUPPORTED

	The operation is not supported.
DDERR_UNSUPPORTEDFORMAT

	The FourCC format requested is not supported by DirectDraw.
DDERR_UNSUPPORTEDMASK

	The bitmask in the pixel format requested is not supported by DirectDraw.
DDERR_UNSUPPORTEDMODE

	The display is currently in an unsupported mode.
DDERR_VERTICALBLANKINPROGRESS

	A vertical blank is in progress.
DDERR_WASSTILLDRAWING

	The previous blit operation that is transferring information to or from this surface is incomplete.
DDERR_WRONGMODE

	This surface cannot be restored because it was created in a different mode.
DDERR_XALIGN

	The provided rectangle was not horizontally aligned on a required boundary.


DirectSound


Overview


About DirectSound

The Microsoft® DirectSound™ application programming interface (API) is the audio component of the Microsoft Windows® 95 DirectX™ 2 Software Development Kit (SDK) that provides low-latency mixing, hardware acceleration, and direct access to the sound device. DirectSound provides this functionality while maintaining compatibility with existing Windows 95-based applications and device drivers.

DirectX 2 allows you, as an application developer, access to the display and audio hardware while insulating you from the specific details of that hardware. The overriding design goal in DirectX 2 is speed. Instead of providing a high-level set of functions, DirectSound provides a device-independent interface, allowing applications to take full advantage of the capabilities of the audio hardware.


Object Types

The most fundamental type of object is the DirectSound object, which represents the sound card itself. The DirectSound object is controlled by the IDirectSound Component Object Model (COM) interface; the methods of this interface allow the application to change the characteristics of the card.

The second type of object is a sound buffer. DirectSound uses primary and secondary sound buffers. Primary sound buffers represent the audio data that is actually heard by the user, while secondary sound buffers represent individual source sounds. DirectSound provides controls for primary and secondary sound buffers in the IDirectSoundBuffer interface.

Primary buffers control sound characteristics, such as output format and total volume. Also, your application can write directly to the primary buffer. In this case, however, the DirectSound mixing and hardware acceleration features are not available. In addition, writing directly to the primary buffer may interfere with other DirectSound applications. When possible, your application should write to secondary buffers instead of the primary buffer. Secondary buffers allow the system to emulate features that might not be present in the hardware; they also allow an application to share the sound card with other applications in the system.

Secondary buffers represent single sound sources used by an application. Each buffer can be played or stopped independently. DirectSound mixes all playing buffers into the primary buffer, then outputs the primary buffer to the sound device. Secondary buffers can reside in hardware or system buffers; hardware buffers are mixed by the sound device without any system processing overhead.

Secondary sound buffers can be either static buffers or streaming buffers. A static buffer means that the buffer contains an entire sound. A streaming buffer means that the buffer only contains part of a sound, and, therefore, your application must continually write new data to the buffer while it is playing. DirectSound will attempt to store static buffers using sound memory located on the sound hardware, if available. Buffers stored on the sound hardware do not consume system processing time when they are played because the mixing is done in the hardware. Reusable sounds, such as gunshots, are the perfect candidates for static buffers.

Your applications will work with two significant positions within a sound buffer: the current play position and the current write position. The current play position indicates the location in the buffer where the sound is being played. The current write position indicates the location where you can safely change the data in the buffer.

The following illustration shows the relationship between the current play and current write positions.

Although DirectSound buffers are conceptually circular, they are implemented using contiguous, linear memory. When the current play position reaches the end of the buffer, it wraps back to the beginning of the buffer.


The DirectSound Object

Each sound device installed in the system is represented by a DirectSound object that is accessed through the IDirectSound interface. Your application can create a DirectSound object by calling the DirectSoundCreate function that returns an IDirectSound interface. DirectSound objects installed in the system can be enumerated by calling the DirectSoundEnumerate function.

Windows is a multitasking operating system. Typically, users run several programs at once and expect them all to share resources. DirectSound objects share sound devices by tracking the input focus, only producing sound when their owning application has the input focus. When an application loses the input focus, the audio streams from that object are muted. Multiple applications can create DirectSound objects for the same sound device. When the input focus changes between applications, the audio output automatically switches from one application's streams to another's. In this way, applications do not have to repeatedly play and stop their buffers when the input focus changes.

Note

The header file for DirectSound includes C programming macro definitions for the methods of the IDirectSound and IDirectSoundBuffer interfaces.


The DirectSoundBuffer Object

Each sound or audio stream is represented by a DirectSoundBuffer object that your application can access through the IDirectSoundBuffer interface. DirectSoundBuffer objects can be created by calling the IDirectSound::CreateSoundBuffer method that returns an IDirectSoundBuffer interface.

Applications are also able to create primary or secondary sound buffers. As previously stated, a secondary sound buffer represents a single sound or audio stream. A primary buffer represents the output audio stream that can be a composite of several mixed secondary buffers. In the current implementation, each DirectSound object has only one primary buffer.

Your application can write data into sound buffers by locking the buffer, writing data to the buffer, and unlocking the buffer. A buffer can be locked by calling the IDirectSoundBuffer::Lock method. This method returns a pointer to the locked portion of the buffer. Once there, it is possible to copy audio data to the buffer. After writing data to the buffer, you must unlock the buffer and complete the write operation by calling the IDirectSoundBuffer::Unlock method.

The primary sound buffer contains the data that is heard. You can play audio data from a secondary sound buffer by using the IDirectSoundBuffer::Play method. This method causes DirectSound to begin mixing the secondary buffer into the primary buffer. By default, IDirectSoundBuffer::Play plays the buffer once and stops at the end. You can also play a sound repeatedly in a continuous loop by specifying the DSBPLAY_LOOPING flag when calling this method. A buffer that is playing can be stopped by using the IDirectSoundBuffer::Stop method.

Generally, the duration of a sound determines how your application uses the associated sound buffer. If the sound data is only a few seconds long, you can use a static buffer to store the sound. If the sound is longer than that, you should use a streaming buffer.

Your application can create a DirectSoundBuffer object that has a static buffer by using the IDirectSound::CreateSoundBuffer method and specifying the DSBCAPS_STATIC flag. DirectSound attempts to store static buffers using sound memory located on the sound hardware, if that memory is available. Buffers stored on sound hardware do not consume system processing time when they are played because the mixing is done in the hardware. Reusable sounds, such as engine roars, cheers, and jeers, are perfect candidates for static buffers.

Streaming buffers can also use hardware mixing if it is supported by the sound device; however, this is efficient only when your application runs on computers with fast data buses, such as the peripheral component interconnect (PCI) bus. If the computer does not have a fast bus, the data transfer overhead outweighs the benefits of hardware mixing. DirectSound will locate streaming buffers in hardware only if the sound device is located on a fast bus.

Note

The DSBCAPS_STATIC flag used with the IDirectSound::CreateSoundBuffer method determines whether the buffer is static or streaming. If this flag is specified, DirectSound creates a static buffer; otherwise, DirectSound creates a streaming buffer.


Software Emulation

DirectSound can emulate in software the features that a particular sound card does not directly support without loss of functionality. Applications can query DirectSound to determine the capabilities of the audio hardware by using the IDirectSound::GetCaps method. A high-performance game, for example, can use this information to scale its audio features.


Device Drivers

DirectSound accesses the sound hardware through the DirectSound hardware-abstraction layer (HAL), an interface that is implemented by the audio-device driver. This is a Windows 95 audio-device driver that has been modified to support the HAL. This driver architecture provides backward compatibility with existing Windows-based applications. The DirectSound HAL provides the following functionality:

•	Acquires and releases control of the audio hardware.

•	Describes the capabilities of the audio hardware.

•	Performs the specified operation when hardware is available.

•	Fails the operation request when hardware is unavailable.

The device driver does not perform any software emulation; it simply reports the capabilities of the hardware to DirectSound and passes requests from DirectSound to the hardware. If the hardware cannot perform a requested operation, the device driver fails the request and DirectSound emulates the operation.

If a DirectSound driver is not available, DirectSound communicates with the audio hardware through the standard Windows 95 or Windows 3.1 audio-device driver. In this case, all DirectSound features are still available through software emulation, but hardware acceleration is not possible.


System Integration

The following diagram shows the relationships between DirectSound and other system audio components.

Using a device driver for the sound hardware that implements the DirectSound HAL provides the best performance for playing audio. The device driver implements each function of the HAL to leverage the architecture of the sound hardware and provide functionality and high performance. The HAL describes the capabilities of the hardware to DirectSound and passes requests from DirectSound to the hardware. If the hardware cannot handle the request, the driver will fail the call. DirectSound then emulates the request in software.

Your application can use DirectSound features even when no DirectSound driver is present. If the sound hardware does not have an installed DirectSound driver, DirectSound uses its HAL emulation layer. This layer uses the Windows multimedia waveform-audio functions.

The DirectSound functions and the waveform-audio functions provide alternative paths to the waveform-audio portion of the sound hardware. A single device provides access from one path at a time. If a waveform-audio driver has allocated a device, trying to allocate that same device using DirectSound will fail. Similarly, if a DirectSound driver has allocated a device, trying to allocate the device using the waveform-audio driver will fail.

If your application needs to use both sets of functions, you should use each set sequentially. For example, you could open the sound hardware by using the DirectSoundCreate function, play sounds using the IDirectSound and IDirectSoundBuffer interfaces, and close the sound hardware by using the IDirectSound::Release method. The sound hardware would then be available for the waveform-audio functions of the Microsoft Win32® SDK.

Also, if two sound devices are installed in the system, your application can access each device independently through either DirectSound or the waveform-audio functions.

The waveform-audio functions continue to be a practical solution for certain applications. For example, your application can easily play a single sound or audio stream, such as an introductory sound, by using the PlaySound function or the WaveOut function.

Note

Microsoft Video For Windows currently uses the waveform-audio functions to output the audio track of an .avi file. Therefore, if your application is using DirectSound and you play an .avi file, the audio track will not be audible. Similarly, if you play an .avi file and attempt to create a DirectSound object, the creation function will return an error.

For now, applications can release the DirectSound object by calling the IDirectSound::Release method before playing an .avi file, and then re-create and reinitialize the DirectSound object and its DirectSoundBuffer objects when the video finishes playing. For more information about IDirectSound::Release, see IUnknown Interface.


DirectSound Features


Mixing

The most used feature of DirectSound is the low-latency mixing of audio streams. Your application can create one or more secondary sound buffers and write audio data to them. You can choose to play or stop any of these buffers. DirectSound mixes all playing buffers and writes the result to the primary sound buffer, which supplies the sound hardware with audio data. There are no limitations to the number of buffers that can be mixed, except the practicalities of available processing time.

Low-latency mixing allows the user to experience no perceptible delay between the time that a buffer plays and the time that the speakers reproduce the sound. In practical terms, this means that the latency is 20 milliseconds or less. The DirectSound mixer provides 20 milliseconds of latency, so there is no perceptible delay before play begins. Under these conditions, if your application plays a buffer and immediately begins a screen animation, the audio and video appear to start synchronously. However, if DirectSound must use the HAL emulation layer (if a DirectSound driver for the sound hardware is not present), the mixer cannot achieve low latency and a hardware-dependent delay, typically 100-150 milliseconds, occurs before the sound is reproduced.

Because only one application at a time can open a particular DirectSound device, only buffers from a single application are audible at any given instance.


Hardware Acceleration

DirectSound automatically takes advantage of accelerated sound hardware, including hardware mixing and hardware sound-buffer memory. Your application does not need to query the hardware or program specifically to use hardware acceleration.

However, for you to make the best possible use of the available hardware resources, you can query DirectSound to receive a full description of the hardware capabilities of the sound device. From this information, you can specify which sound buffers should receive hardware acceleration.

Because your application determines when to use each effect, when to play each sound buffer, and what priority each buffer should take, it can allocate hardware resources as it needs them.


Write Access to the Primary Buffer

The primary sound buffer outputs audio samples to the sound device. DirectSound provides direct write access to the primary buffer; however, this feature is useful for a very limited set of applications that require specialized mixing or other effects not supported by secondary buffers. Gaps in sound are difficult to avoid when an application writes directly to the primary buffer; those that access the primary buffer directly are subject to very stringent performance requirements.

A primary buffer is typically very small, so if your application writes directly to this kind of buffer, it must write blocks of data at short intervals in order to prevent the previous block in the buffer from repeating. During buffer creation, you cannot specify the size of the buffer and must accept the returned size once creation is complete.

When you obtain write access to a primary sound buffer, other DirectSound features become unavailable. Secondary buffers are not mixed and, consequently, hardware-acceleration mixing is unavailable. (When DirectSound mixes sounds from secondary buffers, it places the mixed audio data in the primary buffer.)

Most of your applications should use secondary buffers instead of directly accessing the primary buffer. Applications can write to a secondary buffer easily because the larger buffer size provides more time to write the next block of data, thereby minimizing the risk of gaps in the audio. Even if your application has simple audio requirements, such as using one stream of audio data that does not require mixing, it will achieve better performance by using a secondary buffer to play its audio data.


IDirectSound Interface

A DirectSound object describes the audio hardware on a system. The audio data itself resides in a buffer called a DirectSoundBuffer object. For more information about DirectSound buffers, see IDirectSoundBuffer Interface. The IDirectSound interface enables your application to define and control the sound card, speaker, and memory environment.


Device Capabilities

After calling the DirectSoundCreate function to create a DirectSound object, your application can retrieve the capabilities of the sound device by calling the IDirectSound::GetCaps method. For optimal performance, you should make this call to determine the capabilities of the resident sound card, then modify its sound parameters as appropriate.


Creating Buffers

After calling the DirectSoundCreate function to create a DirectSound object and investigating the capabilities of the sound device, your application can create and enumerate the sound buffers that contain audio data. The IDirectSound::CreateSoundBuffer method creates a sound buffer. The IDirectSound::DuplicateSoundBuffer method creates a second sound buffer using the same physical buffer memory as the first. If you duplicate a sound buffer, you can play both buffers independently without wasting buffer memory.

Your application must use the IDirectSound::SetCooperativeLevel method to set its cooperative level for a sound device before playing any sound buffers. Most applications use a standard priority level, DSSCL_NORMAL, which ensures that they will not conflict with other applications.


Speaker Configuration

The IDirectSound interface contains two methods that allow your application to investigate and set the configuration of the system's speakers. These methods are IDirectSound::GetSpeakerConfig and IDirectSound::SetSpeakerConfig. Currently recognized configurations include headphones, binaural headphones, stereo, quadraphonic, and surround sound.


Hardware Memory Management

Your application can use the IDirectSound::Compact method to move any onboard sound memory into a contiguous block to make the largest portion of free memory available.


IDirectSoundBuffer Interface

The IDirectSoundBuffer interface enables your application to work with buffers of audio data. Audio data resides in a DirectSound buffer. Your application creates DirectSound buffers for each sound or audio stream to be played.

The primary sound buffer represents the actual audio samples output to the sound device. These samples can be a single audio stream or the result of mixing several audio streams. The audio data in a primary sound buffer is typically not accessed directly by applications. However, the primary buffer can be used for control purposes, such as setting the output volume or wave format.

Secondary sound buffers represent a single output stream or sound. Your application can play these buffers into the primary sound buffer. Secondary sound buffers that play concurrently are mixed into the primary buffer, which is then sent to the sound device.


Play Management

Your application can use the IDirectSoundBuffer::Play and IDirectSoundBuffer::Stop methods to control the real-time playback of sound. You can also play a sound using IDirectSoundBuffer::Play. The buffer stops automatically when its end is reached. However, if looping is specified, the buffer repeats until IDirectSoundBuffer::Stop is called.

The IDirectSoundBuffer::Lock method retrieves a write pointer into the current sound buffer. After writing audio data into the buffer, you must unlock the buffer by using the IDirectSoundBuffer::Unlock method. You should not leave the buffer locked for extended periods.

To retrieve or set the current position in the sound buffer, call the IDirectSoundBuffer::GetCurrentPosition or IDirectSoundBuffer::SetCurrentPosition method.


Sound-Environment Management

To retrieve and set the volume at which a buffer is played, your application can use the IDirectSoundBuffer::GetVolume and IDirectSoundBuffer::SetVolume methods. Setting the volume on the primary sound buffer changes the waveform-audio volume of the sound card.

Similarly, by calling the IDirectSoundBuffer::GetFrequency and IDirectSoundBuffer::SetFrequency methods, you can retrieve and set the frequency at which audio samples are played. The frequency of the primary buffer cannot be changed.

To retrieve and set the pan, you can call the IDirectSoundBuffer::GetPan and IDirectSoundBuffer::SetPan methods. The pan of the primary buffer cannot be changed.


Retrieving Information

The IDirectSoundBuffer::GetCaps method retrieves the capabilities of the DirectSoundBuffer object. Your application can use the IDirectSoundBuffer::GetStatus method to determine if the current sound buffer is playing or if it has stopped.

You can use the IDirectSoundBuffer::GetFormat method to retrieve information about the format of the sound data in the buffer. The IDirectSoundBuffer::GetFormat and IDirectSoundBuffer::SetFormat methods can also be used to set the format of the sound data in the primary buffer.

Note

Once a secondary buffer is created, its format is fixed. If a secondary buffer that uses another format is needed, you should create a new sound buffer with the necessary format.


Memory Management

Your application can use the IDirectSoundBuffer::Restore method to restore the sound buffer memory for a specified DirectSoundBuffer object. Although this is useful if the buffer has been lost, the IDirectSoundBuffer::Restore method restores only the memory itself. It cannot restore the content of the memory. Once the buffer memory is restored, it must be rewritten with valid sound data.


IUnknown Interface

Like all Component Object Model (COM) interfaces, the IDirectSound and IDirectSoundBuffer interfaces also include the AddRef, Release, and QueryInterface methods. The AddRef method increases the reference count of the object and the Release method decreases the reference count. Your applications can use the QueryInterface method to determine what additional interfaces an object supports.

When an object is created, its reference count is set to 1. Each time a new application binds to the object or a previously bound application binds to a different interface of the object, the reference count is increased by 1. Each time an application is released from an interface, the reference count is decreased by 1. The object deallocates itself when its reference count goes to 0. The Release method notifies the object that an application is no longer bound to the object.

Your application can use the QueryInterface method to ask an object if it supports a particular interface. If the interface is supported, it can be used immediately. If the interface is not needed, you must call the Release method to free it. QueryInterface allows objects to be extended by Microsoft and third parties without breaking or interfering with each other's existing or future functionality.

Note

DirectSoundBuffer objects are owned by the DirectSound object that created them. When the DirectSound object is released, all buffers created by that object will be released as well and should not be referenced.


Implementation: A Broad Overview

This section describes the programming model for DirectSound and provides some guidelines for typical tasks.

Your application should follow these basic steps to implement DirectSound:

1	Create a DirectSound object by calling the DirectSoundCreate function.

2	Specify a cooperative level by calling the IDirectSound::SetCooperativeLevel method. Most applications use the lowest level, DSSCL_NORMAL.

3	Create secondary buffers using the IDirectSound::CreateSoundBuffer method. Your application need not specify that they are secondary buffers in the DSBUFFERDESC structure; creating secondary buffers is the default.

4	Load the secondary buffers with data. Use the IDirectSoundBuffer::Lock method to obtain a pointer to the data area and the IDirectSoundBuffer::Unlock method to set the data to the device.

5	Use the IDirectSoundBuffer::Play method to play the secondary buffers.

6	Stop all buffers when your application has finished playing sounds by using the IDirectSoundBuffer::Stop method of the DirectSoundBuffer object.

7	Release the secondary buffers.

8	Release the DirectSound object.

Your application can also perform the following optional operations:

•	Set the output format of the primary buffer by creating a primary sound buffer and calling the IDirectSoundBuffer::SetFormat method. This operation requires your application to set the cooperative level to DSSCL_PRIORITY before setting the output format of the primary buffer.

•	Create a primary sound buffer and play the buffer using the IDirectSoundBuffer::Play method. This guarantees that the primary buffer is always playing, even if no secondary buffers are playing. This action consumes some of the processing bandwidth, but it reduces startup time when the first secondary buffer is played.


Creating a DirectSound Object

The easiest way to create a DirectSound object is for your application to call the DirectSoundCreate function and specify a NULL GUID. The function will then attempt to create the object corresponding to the default window's wave device. You must then call the IDirectSound::SetCooperativeLevel method; no sound buffers can be played until this call has been made:

LPDIRECTSOUND lpDirectSound;

if(DS_OK == DirectSoundCreate(NULL, &lpDirectSound,

    NULL)) {

    // Create succeeded!

    lpDirectSound->lpVtbl->SetCooperativeLevel(lpDirectSound,

        hwnd, DSSCL_NORMAL);

    //  .

    //  .  Place code to access DirectSound object here.

    //  .

} else {

    // Create failed!

    //  .

    //  .

    //  .

}

The DirectSoundEnumerate function can be used to specify the particular sound device to create. To use this function, you must create a DSEnumCallback function and, in most cases, an instance data structure:

typedef struct {

    // storage for GUIDs

    // storage for device description strings

} APPINSTANCEDATA, *LPAPPINSTANCEDATA;

BOOL AppEnumCallbackFunction(

    LPGUID lpGuid,

    LPTSTR lpstrDescription,

    LPTSTR lpstrModule,

    LPVOID lpContext)

{

    LPAPPINSTANCEDATA lpInstance = (LPAPPINSTANCEDATA)

    lpContext;

    // Copy GUID into lpInstance structure.

    // Strcpy description string into lpInstance

    // structure.

    return TRUE; // Continue enumerating.

}

Then, to create the DirectSound object, you would use code like this:

AppInitDirectSound()

{

    APPINSTANCEDATA AppInstanceData;

    LPGUID lpGuid;

    LPDIRECTSOUND lpDirectSound;

    HRESULT hr;

    DirectSoundEnumerate(AppEnumCallbackFunction,

    &AppInstanceData);

    lpGuid = AppLetUserSelectDevice(&AppInstanceData);

    // The application should check the return value of

    // DirectSoundCreate for errors.

    hr = DirectSoundCreate(lpGuid, &lpDirectSound, NULL);

    //  .

    //  .

    //  .

}

The DirectSoundCreate function will fail if there is no sound device or if the sound device, as specified by the lpGuid parameter, has been allocated through the waveform-audio functions. You should prepare your applications for this call to fail so that they will either continue without sound or prompt the user to close the application that is using the sound device.


Creating a DirectSound Object Using CoCreateInstance

Use the following steps to create an instance of a DirectSound object using CoCreateInstance:

1	Initialize COM at the start of your application using CoInitialize(NULL).

    if (FAILED(CoInitialize(NULL)))

        return FALSE;

2	Create your DirectSound object using CoCreateInstance and the IDirectSound::Initialize method rather than the DirectSoundCreate function.

    dsrval = CoCreateInstance(&CLSID_DirectSound,

                                           NULL,

                                           CLSCTX_ALL,

                                           &IID_IDirectSound,

                                           &lpds);

    if( !FAILED(dsrval) )

        dsrval = IDirectSound_Initialize( lpds, NULL);

CLSID_DirectSound is the class identifier of the DirectSound driver object class and IID_IDirectSound is the DirectSound interface that you should use. lpds is the uninitialized object CoCreateInstance returns.

Before you use the DirectSound object, you must call IDirectSound::Initialize. IDirectSound::Initialize takes the driver GUID parameter that DirectSoundCreate typically uses (NULL in this case). Once the DirectSound object is initialized, you can use and release the DirectSound object as if it had been created using DirectSoundCreate.

Before closing the application, shut down COM using CoUninitialize, as shown below.

    CoUnitialize()


Querying the Hardware Capabilities

DirectSound allows your application to retrieve the hardware capabilities of the sound device being used by a DirectSound object. Most applications will not need to do this; DirectSound automatically takes advantage of hardware acceleration. However, high-performance applications can use this information to scale their sound requirements to the available hardware. For example, your application might play more sounds if hardware mixing is available.

To retrieve the hardware capabilities, use the IDirectSound::GetCaps method, which will fill in a DSCAPS structure:

AppDetermineHardwareCaps(LPDIRECTSOUND lpDirectSound)

{

    DSCAPS dscaps;

    HRESULT hr;

    dscaps.dwSize = sizeof(DSCAPS);

    hr = lpDirectSound->lpVtbl->GetCaps(lpDirectSound,

    &dscaps);

    if(DS_OK == hr) {

        // Succeeded, now parse DSCAPS structure.

        //  .

        //  .

        //  .

    }

    //  .

    //  .

    //  .

}

The DSCAPS structure contains information about the performance and resources of the sound device, including the maximum resources of each type and the resources that are currently available. There may be trade-offs between various resources; for example, allocating a single hardware streaming buffer might consume two static mixing channels. If your application scales to hardware capabilities, you should call the IDirectSound::GetCaps method between every buffer allocation to determine if there are enough resources for the next buffer creation.

Do not make assumptions about the behavior of the sound device, otherwise your application may work on some sound devices but not on others. Furthermore, advanced devices are under development that will behave differently than existing devices.

When allocating hardware resources, your application should attempt to allocate them as software buffers instead. Complete access to all hardware resources is not always available. For example, because Windows 95 is a multitasking operating system, the IDirectSound::GetCaps method might indicate a free resource, but by the time you attempt to allocate the resource, it may have been allocated to another application.


Creating Sound Buffers


Creating a Basic Sound Buffer

To create a sound buffer, your application fills in a DSBUFFERDESC structure and then calls the IDirectSound::CreateSoundBuffer method. This creates a DirectSoundBuffer object and returns a pointer to an IDirectSoundBuffer interface. This interface can be used to write, manipulate, and play the buffer.

You should create buffers for the most important sounds first, and continue to create them in descending order of importance. DirectSound allocates hardware resources to the first buffer that can take advantage of them.

The following example illustrates how to create a basic secondary buffer:

BOOL AppCreateBasicBuffer(

    LPDIRECTSOUND lpDirectSound,

    LPDIRECTSOUNDBUFFER *lplpDsb)

{

    PCMWAVEFORMAT pcmwf;

    DSBUFFERDESC dsbdesc;

    HRESULT hr;

    // Set up wave format structure.

    memset(&pcmwf, 0, sizeof(PCMWAVEFORMAT));

    pcmwf.wf.wFormatTag = WAVE_FORMAT_PCM;

    pcmwf.wf.nChannels = 2;

    pcmwf.wf.nSamplesPerSec = 22050;

    pcmwf.wf.nBlockAlign = 4;

    pcmwf.wf.nAvgBytesPerSec =

        pcmwf.wf.nSamplesPerSec * pcmwf.wf.nBlockAlign;

    pcmwf.wBitsPerSample = 16;

    // Set up DSBUFFERDESC structure.

    memset(&dsbdesc, 0, sizeof(DSBUFFERDESC)); // Zero it out.

    dsbdesc.dwSize = sizeof(DSBUFFERDESC);

    dsbdesc.dwFlags = DSBCAPS_CTRLDEFAULT; // Need default controls

                                              (pan, volume, frequency).

    dsbdesc.dwBufferBytes = 3 * pcmwf.wf.nAvgBytesPerSec; // 3 second

                                                             buffer.

    dsbdesc.lpwfxFormat = (LPWAVEFORMATEX)&pcmwf;

    // Create buffer.

    hr = lpDirectSound->lpVtbl->CreateSoundBuffer(lpDirectSound,

        &dsbdesc, lplpDsb, NULL);

    if(DS_OK == hr) {

        // Succeeded! Valid interface is in *lplpDsb.

        return TRUE;

    } else {

        // Failed!

        *lplpDsb = NULL;

        return FALSE;

    }

}


Control Options

When creating a sound buffer, your application must specify the control options needed for that buffer. This can be done with the dwFlags member of the DSBUFFERDESC structure, which can contain one or more DSBCAPS_CTRL flags. DirectSound uses this information when allocating hardware resources to sound buffers. For example, a particular device might support hardware buffers but provide no pan control on those buffers. In this case, DirectSound would only use hardware acceleration if the DSBCAPS_CTRLPAN flag was not specified.

To obtain the best performance on all sound cards, your application should only specify those control options which it will actually use.

If your application calls a method that a buffer lacks, that method fails. For example, if you attempt to change the volume by using theIDirectSoundBuffer::SetVolume method, it will succeed if the DSBCAPS_CTRLVOLUME flag was specified when the buffer was created. Otherwise, the method fails and returns the DSERR_CONTROLUNAVAIL error code. Providing controls for the buffers helps to ensure that all applications run correctly on all existing or future sound devices.


Static and Streaming Sound Buffers

A static sound buffer contains a complete sound in memory. These buffers are convenient because the entire sound can be written once to the buffer.

A streaming buffer only represents a portion of a sound, such as a buffer that can hold three seconds of audio data that plays a two-minute sound. In this case, your application must periodically write new data into the sound buffer. However, a streaming buffer requires much less memory than a static buffer.

When creating a sound buffer, you can indicate that a buffer is static by specifying the DSBCAPS_STATIC flag. If this flag is not specified, the buffer is a streaming buffer.

If a sound device has onboard sound memory, DirectSound will attempt to place static buffers in the hardware memory. These buffers can then take advantage of hardware mixing, with the benefit that the processing system incurs little or no overhead to mix these sounds. This is particularly useful for sounds that will be played more than once, such as the sound a character makes while walking or a firearm going off, since the sound data only needs to be downloaded once to the hardware memory.

Streaming buffers are generally located in main system memory to allow efficient writing to the buffer, although hardware mixing can be used on peripheral component interconnect (PCI) machines or other fast buses. There are no requirements on the use of streaming buffers. For example, you can write an entire sound into a streaming buffer if it is big enough. In fact, if you do not intend to use the sound more than once, it may be more efficient to use a streaming buffer because there is no need for the sound data to be downloaded to the hardware memory.

Note

The designation of a buffer as static or streaming is used by DirectSound to optimize performance; it does not restrict how you can use the buffer.


Hardware and Software Sound Buffers

A hardware sound buffer has its mixing performed by a hardware mixer located on the sound device. A software sound buffer has its mixing performed by the system central processing unit. In most cases, your application should simply specify whether the buffer is static or streaming; DirectSound will locate the buffer in hardware or software as appropriate.

If explicitly locating buffers in hardware or software is necessary, however, you can specify either the DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flags in the DSBUFFERDESC structure. If the DSBCAPS_LOCHARDWARE flag is specified and there is insufficient hardware memory or mixing capacity, the buffer creation request will fail. Also, most existing sound devices do not have any hardware memory or mixing capacity, so no hardware buffers can be created on these devices.

The location of a sound buffer can be determined by calling the IDirectSoundBuffer::GetCaps method and checking the dwFlags member of the DSBCAPS structure for either the DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flags. One or the other will always be specified.


Primary and Secondary Sound Buffers

Primary sound buffers represent the actual audio samples that the listener will hear. Secondary buffers each represent a single sound or stream of audio. Your application can create a primary buffer by specifying the DSBCAPS_PRIMARYBUFFER flag in the DSBUFFERDESC structure. If this flag is not specified, a secondary buffer will be created.

Usually you should create secondary sound buffers for each sound in a given application. Note that sound buffers can be reused by overwriting the old sound data with new data. DirectSound takes care of the hardware resource allocation and the mixing together of all buffers that are playing.

If your application uses secondary buffers, you may choose to create a primary sound buffer to perform certain controls. For example, you can control the hardware output format by calling the IDirectSoundBuffer::SetFormat method on the primary buffer. However, any methods that access the actual buffer memory, such as IDirectSoundBuffer::Lock and IDirectSoundBuffer::GetCurrentPosition, will fail.

If your application performs its own mixing, DirectSound provides write access to the primary buffer. You should write data into this buffer in a timely manner; if you do not update the data, the previous buffer will repeat itself, causing gaps in the audio. Write access to the primary buffer is only available if your application has the DSSCL_WRITEPRIMARY cooperative level. At this cooperative level, no secondary buffers can be played.

Note that primary sound buffers must be played with looping. Be sure that the DSBPLAY_LOOPING flag is set.

The following example shows how to obtain write access to the primary buffer:

BOOL AppCreateWritePrimaryBuffer(

    LPDIRECTSOUND lpDirectSound,

    LPDIRECTSOUNDBUFFER *lplpDsb,

    LPDWORD lpdwBufferSize,

    HWND hwnd)

{

    DSBUFFERDESC dsbdesc;

    DSBCAPS dsbcaps;

    HRESULT hr;

    // Set up wave format structure.

    memset(&pcmwf, 0, sizeof(PCMWAVEFORMAT));

    pcmwf.wf.wFormatTag = WAVE_FORMAT_PCM;

    pcmwf.wf.nChannels = 2;

    pcmwf.wf.nSamplesPerSec = 22050;

    pcmwf.wf.nBlockAlign = 4;

    pcmwf.wf.nAvgBytesPerSec =

        pcmwf.wf.nSamplesPerSec * pcmwf.wf.nBlockAlign;

    pcmwf.wBitsPerSample = 16;

    // Set up DSBUFFERDESC structure.

    memset(&lplpDsb, 0, sizeof(DSBUFFERDESC)); // Zero it out.

    dsbdesc.dwSize = sizeof(DSBUFFERDESC);

    dsbdesc.dwFlags = DSBCAPS_PRIMARYBUFFER;

    dsbdesc.dwBufferBytes = 0; // Buffer size is determined

                               // by sound hardware.

    dsbdesc.lpwfxFormat = NULL; // Must be NULL for primary buffers.

    // Obtain write-primary cooperative level.

    hr = lpDirectSound->lpVtbl->SetCooperativeLevel(lpDirectSound,

        hwnd, DSSCL_WRITEPRIMARY);

    if(DS_OK == hr) {

        // Succeeded! Try to create buffer.

        hr = lpDirectSound->lpVtbl->CreateSoundBuffer(lpDirectSound,

            &dsbdesc, lplpDsb, NULL);

        if(DS_OK == hr) {

            // Succeeded! Set primary buffer to desired format.

            hr = (*lplpDsb)->lpVtbl->SetFormat(*lplpDsb, &pcmwf);

            if(DS_OK == hr) {

                // If you want to know the buffer size, call GetCaps.

dsbcaps.dwSize = sizeof(DSBCAPS);

                (*lplpDsb)->lpVtbl->GetCaps(*lplpDsb, &dsbcaps);

                *lpdwBufferSize = dsbcaps.dwBufferBytes;

                return TRUE;

            }

        }

    }

    // If we got here, then we failed SetCooperativeLevel.

    // CreateSoundBuffer, or SetFormat.

    *lplpDsb = NULL;

    *lpdwBufferSize = 0;

    return FALSE;

}


Writing to Sound Buffers

Your application can obtain write access to a sound buffer by using the IDirectSoundBuffer::Lock method. Once the sound buffer (memory) is locked, you can write or copy data to the buffer. The buffer memory must then be unlocked by calling the IDirectSoundBuffer::Unlock method.

Since streaming sound buffers usually wrap around and continue playing from the beginning of the buffer, DirectSound returns two write pointers when locking a sound buffer. For example, if you try to lock 300 bytes beginning at the midpoint of a 400 byte buffer, IDirectSoundBuffer::Lock would return a pointer to the last 200 bytes of the buffer, and a second pointer to the first 100 bytes. Depending on the offset and the length of the buffer, the second pointer may be NULL.

You should be aware that memory for a sound buffer can be lost in certain situations. In particular, this might occur when buffers are located in the hardware sound memory. In the most dramatic case, the sound card itself might be removed from the system while being used; this situation can occur with PCMCIA sound cards. It can also occur when an application with the write-primary cooperative level (DSSCL_WRITEPRIMARY flag) gains the input focus. If this flag is set, DirectSound makes all other sound buffers become lost so that the application with the focus can write directly to the primary buffer. If this happens, DirectSound returns the DSERR_BUFFERLOST error code in response to the IDirectSoundBuffer::Lock and IDirectSoundBuffer::Play methods. When the application lowers its cooperative level from write-primary, or loses the input focus, other applications can attempt to reallocate the buffer memory by calling the IDirectSoundBuffer::Restore method. If successful, this method restores the buffer memory and all other settings for the buffer, such as volume and pan settings. However, a restored buffer does not contain valid sound data. The owning application must rewrite the data to the restored buffer.

The following function writes data to a sound buffer using the IDirectSoundBuffer::Lock and IDirectSoundBuffer::Unlock methods:

BOOL AppWriteDataToBuffer(

    LPDIRECTSOUNDBUFFER lpDsb,

    DWORD dwOffset,

    LPBYTE lpbSoundData,

    DWORD dwSoundBytes)

{

    LPVOID lpvPtr1;

    DWORD dwBytes1;

    LPVOID lpvPtr2;

    DWORD dwBytes2;

    HRESULT hr;

    // Obtain write pointer.

    hr = lpDsb->lpVtbl->Lock(lpDsb, dwOffset, dwSoundBytes, &lpvPtr1,

        &dwBytes1, &lpvPtr2, &dwBytes2, 0);

    // If we got DSERR_BUFFERLOST, restore and retry lock.

    if(DSERR_BUFFERLOST == hr) {

        lpDsb->lpVtbl->Restore(lpDsb);

        hr = lpDsb->lpVtbl->Lock(lpDsb, dwOffset, dwSoundBytes,

            &lpvPtr1, &dwAudio1, &lpvPtr2, &dwAudio2, 0);

    }

    if(DS_OK == hr) {

        // Write to pointers.

        CopyMemory(lpvPtr1, lpbSoundData, dwBytes1);

        if(NULL != lpvPtr2) {

            CopyMemory(lpvPtr2, lpbSoundData+dwBytes1, dwBytes2);

        }

        // Release the data back to DirectSound.

        hr = lpDsb->lpVtbl->Unlock(lpDsb, lpvPtr1, dwBytes1, lpvPtr2,

            dwBytes2);

        if(DS_OK == hr) {

            // Success!

            return TRUE;

        }

    }

    // If we got here, then we failed Lock, Unlock, or Restore.

    return FALSE;

}


Using the DirectSound Mixer

It is easy to mix multiple streams with DirectSound. Your application can simply create secondary buffers, receiving an IDirectSoundBuffer interface for each sound. You can then use these interfaces to write data into the buffers using the IDirectSoundBuffer::Lock and IDirectSoundBuffer::Unlock methods and play the buffers using the IDirectSoundBuffer::Play method. The buffers can be stopped at any time by calling the IDirectSoundBuffer::Stop method.

The IDirectSoundBuffer::Play method will always start playing at the buffer's current position. The current position is specified by an offset, in bytes, into the buffer. The current position of a newly created buffer is 0. When a buffer is stopped, the current position immediately follows the next sample played. The current position can be set explicitly by calling the IDirectSoundBuffer::SetCurrentPosition method, and can be queried by calling the IDirectSoundBuffer::GetCurrentPosition method.

By default, IDirectSoundBuffer::Play will stop playing when it reaches the end of the buffer. This is the correct behavior for non-looping static buffers. (The current position will be reset to the beginning of the buffer at this point.) For streaming buffers or for static buffers that continuously repeat, your application should call IDirectSoundBuffer::Play and specify the DSBPLAY_LOOPING flag in the dwFlags parameter. This will cause the buffer to loop back to the beginning once it reaches the end.

For streaming buffers, your application is responsible for ensuring that the next block of data is written into the buffer before the play cursor loops back to the beginning. This can be done by using the Win32 functions SetTimer or SetEvent to cause a message or callback function to occur at regular intervals. In addition, many DirectSound applications will already have a real-time DirectDraw component which needs to service the display at regular intervals; this component should be able to service DirectSound buffers as well. For optimal efficiency, all applications should write at least one second ahead of the current play cursor to minimize the possibility of gaps in the audio output during playback.

The DirectSound mixer can obtain the best usage out of hardware acceleration if your application correctly specifies the DSBCAPS_STATIC flag for static buffers. This flag should be specified for any static buffers that will be reused. DirectSound will download these buffers to the sound hardware memory, where available, and will thereby not incur any processing overhead in mixing these buffers. The most important static buffers should be created first, in order to give them first priority for hardware acceleration.

The DirectSound mixer will produce the best sound quality if all of your application's sounds use the same wave format and the hardware output format is matched to the format of the sounds. If this is done, the mixer need not perform any format conversion.

The hardware output format can be changed by creating a primary buffer and calling the IDirectSoundBuffer::SetFormat method. Note that this primary buffer is for control purposes only; only applications with a cooperative level of DSSCL_PRIORITY or higher can call this function. DirectSound will then restore the hardware format to the format specified in the last IDirectSoundBuffer::SetFormat method call each time the application gains the input focus.


Using a Custom Mixer

Most applications should use the DirectSound mixer; it should be sufficient for almost all mixing needs and it automatically takes advantage of hardware acceleration, if available. However, if an application requires some other functionality that DirectSound does not provide, it can obtain write access to the primary buffer and mix streams directly into it. This feature is provided for completeness, and should only be useful for a very limited set of high-performance applications. Applications that take advantage of this feature are subject to very stringent performance requirements, since it is difficult to avoid gaps in the audio.

To implement a custom mixer, the application should first obtain the DSSCL_WRITEPRIMARY cooperative level and then create a primary sound buffer. It can then call the IDirectSoundBuffer::Lock method, write data into the returned pointers, and call the IDirectSoundBuffer::Unlock method to release the data back to DirectSound. Applications must explicitly play the primary buffer by calling the IDirectSoundBuffer::Play method to reproduce the sound data in the speakers. Note that the DSBPLAY_LOOPING flag must be specified or the IDirectSoundBuffer::Play call will fail.

The following example illustrates how an application might implement a custom mixer. This function would have to be called at regular intervals, frequently enough to prevent the sound device from repeating blocks of data. The CustomMixer() function is an application-defined function which mixes several streams together, as specified in the application-defined AppStreamInfo structure, and writes the result into the pointer specified:

BOOL AppMixIntoPrimaryBuffer(

    LPAPPSTREAMINFO lpAppStreamInfo,

    LPDIRECTSOUNDBUFFER lpDsbPrimary,

    DWORD dwDataBytes,

    DWORD dwOldPos,

    LPDWORD lpdwNewPos)

{

    LPVOID lpvPtr1;

    DWORD dwBytes1;

    LPVOID lpvPtr2;

    DWORD dwBytes2;

    HRESULT hr;

    // Obtain write pointer.

    hr = lpDsbPrimary->lpVtbl->Lock(lpDsbPrimary, dwOldPos, dwDataBytes,

        &lpvPtr1, &dwBytes1, &lpvPtr2, &dwBytes2, 0);

    // If we got DSERR_BUFFERLOST, restore and retry lock.

    if(DSERR_BUFFERLOST == hr) {

        lpDsbPrimary->lpVtbl->Restore(lpDsbPrimary);

        hr = lpDsbPrimary->lpVtbl->Lock(lpDsbPrimary, dwOldPos,

            dwDataBytes, &lpvPtr1, &dwBytes1, &lpvPtr2, &dwBytes2, 0);

    }

    if(DS_OK == hr) {

        // Mix data into the returned pointers.

        CustomMixer(lpAppStreamInfo, lpvPtr1, dwBytes1);

        *lpdwNewPos = dwOldPos + dwBytes1;

        if(NULL != lpvPtr2) {

            CustomMixer(lpAppStreamInfo, lpvPtr2, dwBytes2);

            *lpdwNewPos = dwBytes2; // Because we wrapped around.

        }

        // Release the data back to DirectSound.

        hr = lpDsbPrimary->lpVtbl->Unlock(lpDsbPrimary, lpvPtr1,

            dwBytes1, lpvPtr2, dwBytes2);

        if(DS_OK == hr) {

            // Success!

            return TRUE;

        }

    }

    // If we got here, then we failed Lock or Unlock.

    return FALSE;

}


Using Compressed Wave Formats

DirectSound does not currently support compressed wave formats. Applications should use the Audio Compression Manager (ACM) functions, provided with the Win32 SDK, to convert compressed audio to pulse coded modulation (PCM) data before writing the data to a sound buffer. In fact, by locking a pointer to the sound buffer memory and passing this pointer to the ACM, the data can be decoded directly into the sound buffer for maximum efficiency.


Reference


Functions

The DirectSound functions create a DirectSound object, which in turn controls the direct-audio memory access enabled by the DirectX 2 SDK. DirectSound virtualizes direct memory access (DMA) to the audio buffer of the sound card. This allows the application, using the DirectSound object, to mix and play its own audio.


DirectSoundCreate

Creates and initializes an IDirectSound interface.

HRESULT DirectSoundCreate(
GUID FAR * lpGuid,
LPDIRECTSOUND * ppDS,
IUnknown FAR * pUnkOuter
);

Parameters

lpGuid

Address of the GUID that identifies the sound device. The value of this parameter must be one of the GUIDs returned by DirectSoundEnumerate, or, to request the default device, NULL.

ppDS

Address of a pointer to a DirectSound object created in response to this function.

pUnkOuter

Controlling unknown of the aggregate. Its value must be NULL.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_ALLOCATED	DSERR_INVALIDPARAM
DSERR_NOAGGREGATION	DSERR_NODRIVER
DSERR_OUTOFMEMORY
Remarks

The application must call the IDirectSound::SetCooperativeLevel method immediately after creating a DirectSound object.

See Also

 IDirectSound::GetCaps, IDirectSound::SetCooperativeLevel


DirectSoundEnumerate

Enumerates the DirectSound drivers installed in the system.

BOOL DirectSoundEnumerate(
LPDSENUMCALLBACK lpDSEnumCallback,
LPVOID lpContext
);

Parameters

lpDSEnumCallback

Address of the DSEnumCallback function that will be called for each DirectSound object installed in the system.

lpContext

Address of the user-defined context passed to the enumeration callback function every time that function is called.

Return Values

Returns DS_OK if successful, or DSERR_INVALIDPARAM otherwise.

See Also

 DSEnumCallback


Callback Functions

Most of the functionality of DirectSound is provided by the methods of its Component Object Model (COM) interfaces. This section lists the callback functions that are not implemented as part of a COM interface.


DSEnumCallback

Application-defined callback function that enumerates the DirectSound drivers. The system calls this function in response to the application's previous call to the DirectSoundEnumerate function.

BOOL DSEnumCallback(
GUID FAR * lpGuid,
LPSTR lpstrDescription,
LPSTR lpstrModule,
LPVOID lpContext
);

Parameters

lpGuid

Address of the GUID that identifies the DirectSound driver being enumerated. This value can be passed to the DirectSoundCreate function to create a DirectSound object for that driver.

lpstrDescription

Address of a null-terminated string that provides a textual description of the DirectSound device.

lpstrModule

Address of a null-terminated string that specifies the module name of the DirectSound driver corresponding to this device.

lpContext

Address of application-defined data that is passed to each callback function.

Return Values

Returns TRUE to continue enumerating drivers, or FALSE to stop.

Remarks

The application can save the strings passed in the lpstrDescription and lpstrModule parameters by copying them into memory that is allocated from the heap. The memory used to pass the strings to this callback function is valid only while this callback function is running.

See Also

 DirectSoundEnumerate


IDirectSound Interface


IDirectSound Interface Method Groups

Applications use the methods of the IDirectSound interface to create DirectSound objects and set up the environment. The methods can be organized into the following groups:

Allocating memory	Compact
	Initialize
Creating buffers	CreateSoundBuffer
	DuplicateSoundBuffer
	SetCooperativeLevel
Device capabilities	GetCaps
IUnknown	AddRef
	QueryInterface
	Release
Speaker configuration	GetSpeakerConfig
	SetSpeakerConfig
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the DirectSound object without affecting the functionality of the original interface.


IDirectSound::AddRef

Increases the reference count of the DirectSound object by 1. This method is part of the IUnknown interface inherited by DirectSound.

ULONG AddRef( );

Parameters

Return Values

Returns the new reference count of the object.

Remarks

When the DirectSound object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirectSound::Release method to decrease the reference count of the object by 1.

See Also

 IDirectSound::QueryInterface, IDirectSound::Release


IDirectSound::Compact

Moves the unused portions of onboard sound memory, if any, to a contiguous block so that the largest portion of free memory will be available.

HRESULT Compact( );

Parameters

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_INVALIDPARAM	DSERR_PRIOLEVELNEEDED
DSERR_UNINITIALIZED
Remarks

If the application calls this method, it must have exclusive cooperation with the DirectSound object. (To get exclusive access, specify DSSCL_EXCLUSIVE in a call to the IDirectSound::SetCooperativeLevel method.) This method will fail if any operations are in progress.

See Also

 IDirectSound, IDirectSound::SetCooperativeLevel


IDirectSound::CreateSoundBuffer

Creates a DirectSoundBuffer object to hold a sequence of audio samples.

HRESULT CreateSoundBuffer(
LPDSBUFFERDESC lpDSBufferDesc,
LPLPDIRECTSOUNDBUFFER * lplpDirectSoundBuffer,
IUnknown FAR * pUnkOuter
);

Parameters

lpDSBufferDesc

Address of a DSBUFFERDESC structure that contains the description of the sound buffer to be created.

lplpDirectSoundBuffer

Address of a pointer to the new DirectSoundBuffer object or NULL if the buffer cannot be created.

pUnkOuter

Controlling unknown of the aggregate. Its value must be NULL.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_ALLOCATED	DSERR_BADFORMAT
DSERR_INVALIDPARAM	DSERR_NOAGGREGATION
DSERR_OUTOFMEMORY	DSERR_UNINITIALIZED
DSERR_UNSUPPORTED
Remarks

Before it can play any sound buffers, the application must specify a cooperative level for a DirectSound object by using the IDirectSound::SetCooperativeLevel method.

The lpDSBufferDesc parameter points to a structure that describes the type of buffer desired, including format, size, and capabilities. The application must specify the needed capabilities, or they will not be available. For example, if the application creates a DirectSoundBuffer object without specifying the DSBCAPS_CTRLFREQUENCY flag, any call to IDirectSoundBuffer::SetFrequency will fail.

The DSBCAPS_STATIC flag can also be specified, in which case DirectSound stores the buffer in onboard memory, if available, in order to take advantage of hardware mixing. To force the buffer to use either hardware or software mixing, use the DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flags.

See Also

 DSBUFFERDESC, IDirectSound, IDirectSound::DuplicateSoundBuffer, IDirectSound::SetCooperativeLevel, IDirectSoundBuffer, IDirectSoundBuffer::GetFormat, IDirectSoundBuffer::GetVolume, IDirectSoundBuffer::Lock, IDirectSoundBuffer::Play, IDirectSoundBuffer::SetFormat, IDirectSoundBuffer::SetFrequency


IDirectSound::DuplicateSoundBuffer

Creates a new DirectSoundBuffer object that uses the same buffer memory as the original object.

HRESULT DuplicateSoundBuffer(
LPDIRECTSOUNDBUFFER lpDsbOriginal,
LPLPDIRECTSOUNDBUFFER lplpDsbDuplicate
);

Parameters

lpDsbOriginal

Address of the DirectSoundBuffer object to be duplicated.

lplpDsbDuplicate

Address of a pointer to the new DirectSoundBuffer object.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_ALLOCATED	DSERR_INVALIDCALL
DSERR_INVALIDPARAM	DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
Remarks

The new object can be used just like the original.

Initially, the duplicate buffer will have the same parameters as the original buffer. However, the application can change the parameters of each buffer independently, and each can be played or stopped without affecting the other.

If data in the buffer is changed through one object, the change will be reflected in the other object since the buffer memory is shared.

The buffer memory will be released when the last object referencing it is released.

See Also

 IDirectSound, IDirectSound::CreateSoundBuffer


IDirectSound::GetCaps

Retrieves the capabilities of the hardware device that is represented by the DirectSound object.

HRESULT GetCaps(
LPDSCAPS lpDSCaps
);

Parameters

lpDSCaps

Address of the DSCAPS structure to contain the capabilities of this sound device.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_GENERIC	DSERR_INVALIDPARAM
DSERR_UNINITIALIZED
Remarks

Information retrieved in the DSCAPS structure describes the maximum capabilities of the sound device and those currently available, such as the number of hardware mixing channels and the amount of onboard sound memory. This information can be used to fine-tune performance and optimize resource allocation.

Because of resource sharing requirements, the maximum capabilities in one area might only be available at the cost of another area. For example, the maximum number of hardware-mixed streaming buffers may only be available if there are no hardware static buffers.

See Also

 DirectSoundCreate, DSCAPS, IDirectSound


IDirectSound::GetSpeakerConfig

Retrieves the speaker configuration specified for this DirectSound object.

HRESULT GetSpeakerConfig(
LPDWORD lpdwSpeakerConfig
);

Parameters

lpdwSpeakerConfig

Address of the speaker configuration for this DirectSound object. The speaker configuration is specified with one of the following values:

DSSPEAKER_HEADPHONE

	The audio is output through headphones.
DSSPEAKER_MONO

	The audio is output through a single speaker.
DSSPEAKER_QUAD

	The audio is output through quadraphonic speakers.
DSSPEAKER_STEREO

	The audio is output through stereo speakers (default value).
DSSPEAKER_SURROUND

	The audio is output through surround speakers.
Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_INVALIDPARAM	DSERR_UNINITIALIZED
See Also

 IDirectSound, IDirectSound::SetSpeakerConfig


IDirectSound::Initialize

Initializes the DirectSound object that was created using the CoCreateInstance OLE function.

HRESULT Initialize(
GUID FAR * lpGuid
);

Parameters

lpGuid

Address of the GUID specifying the sound driver for the DirectSound object to bind to. Use NULL or GUID_NULL to select the primary sound driver.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_INVALIDPARAM	DSERR_ALREADYINITIALIZED
DSERR_NODRIVER	DSERR_GENERIC
Remarks

If DirectSoundCreate is used to create the DirectSound object, this method will return DSERR_ALREADYINITIALIZED.

For more information on using this method with CoCreateInstance, see Creating DirectSound Objects Using CoCreateInstance.

This information is new since the DirectX 2 SDK was released. For a complete list of new information, see New Information.

See Also

 DirectSoundCreate


IDirectSound::QueryInterface

Determines if the DirectSound object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by DirectSound.

HRESULT QueryInterface(
REFIID riid,
LPVOID * ppvObj
);

Parameters

riid

Reference identifier of the interface being requested.

ppvObj

Address of a location to be filled with the returned interface pointer if the query is successful.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_GENERIC	DSERR_INVALIDPARAM
Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirectSound::QueryInterface method allows DirectSound objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.

See Also

 IDirectSound::AddRef, IDirectSound::Release


IDirectSound::Release

Decreases the reference count of the DirectSound object by 1. This method is part of the IUnknown interface inherited by DirectSound.

ULONG Release( );

Parameters

Return Values

Returns the new reference count of the object.

Remarks

The DirectSound object deallocates itself when its reference count reaches 0. Use the IDirectSound::AddRef method to increase the reference count of the object by 1.

See Also

 IDirectSound::AddRef, IDirectSound::QueryInterface


IDirectSound::SetCooperativeLevel

Sets the cooperative level of the application for this sound device.

HRESULT SetCooperativeLevel(
HWND hwnd,
DWORD dwLevel
);

Parameters

hwnd

Window handle for the application.

dwLevel

Requested priority level. Specify one of the following values:

DSSCL_EXCLUSIVE

	Sets the application to the exclusive level. When it has the input focus, the application will be the only one audible. With this level, it also has all the privileges of the DSSCL_PRIORITY level. DirectSound will restore the hardware format, as specified by the most recent call to the IDirectSoundBuffer::SetFormat method, once the application gains the input focus.
DSSCL_NORMAL

	Sets the application to a fully cooperative status. Most applications should use this level, since it has the smoothest multi-tasking and resource-sharing behavior.
DSSCL_PRIORITY

	Sets the application to the priority level. Applications with this cooperative level can call the IDirectSoundBuffer::SetFormat and IDirectSound::Compact methods.
DSSCL_WRITEPRIMARY

	This is the highest priority level. The application has write access to the primary buffers. No secondary buffers in any application can be played.
Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_ALLOCATED	DSERR_INVALIDPARAM
DSERR_UNINITIALIZED	DSERR_UNSUPPORTED
Remarks

The application must set the cooperative level by calling this method before its buffers can be played. The recommended cooperative level is DSSCL_NORMAL; use other priority levels when necessary.

Four cooperative levels are defined: normal, priority, exclusive, and write-primary.

The normal cooperative level is the lowest level. At the normal level, the IDirectSoundBuffer::SetFormat and IDirectSound::Compact methods cannot be called. In addition, the application cannot obtain write access to primary buffers. All applications using this cooperative level use a primary buffer format of 22 kHz, monaural sound, and 8-bit samples to make task switching as smooth as possible.

When using a DirectSound object with the priority cooperative level, the application has first priority to hardware resources, such as hardware mixing, and can call IDirectSoundBuffer::SetFormat and IDirectSound::Compact.

When using a DirectSound object with the exclusive cooperative level, the application has all the privileges of the priority level; in addition, when it has the input focus, only this application's buffers are audible. Once the input focus is gained, DirectSound restores the application's preferred wave format, which was defined in the most recent call to IDirectSoundBuffer::SetFormat.

The highest cooperative level is write-primary. When using a DirectSound object with this cooperative level, your application has direct access to the primary sound buffer. In this mode, the application must lock the buffer using the IDirectSoundBuffer::Lock method and write directly into the primary buffer. While this occurs, secondary buffers cannot be played.

When the application is set to the write-primary cooperative level and gains the input focus, all secondary buffers for other applications are stopped and marked as lost. These buffers must be restored using the IDirectSoundBuffer::Restore method before they can be played again. When the application then loses the input focus, its primary buffer is marked as lost and can be restored after the application regains the input focus.

The write-primary level is not required in order to create a primary buffer. However, to obtain access to the audio samples in the primary buffer, the application must have the write-primary level. If the application does not have this level, then all calls to IDirectSoundBuffer::Lock and IDirectSoundBuffer::Play will fail, although some methods, such as IDirectSoundBuffer::GetFormat, IDirectSoundBuffer::SetFormat, and IDirectSoundBuffer::GetVolume, can still be called successfully.

See Also

 IDirectSound, IDirectSound::Compact, IDirectSoundBuffer::GetFormat, IDirectSoundBuffer::GetVolume, IDirectSoundBuffer::Lock, IDirectSoundBuffer::Play, IDirectSoundBuffer::Restore, IDirectSoundBuffer::SetFormat


IDirectSound::SetSpeakerConfig

Specifies the speaker configuration for the DirectSound object.

HRESULT SetSpeakerConfig(
DWORD dwSpeakerConfig
);

Parameters

dwSpeakerConfig

Speaker configuration of the specified DirectSound object. This parameter can be one of the following values:

DSSPEAKER_HEADPHONE

	The speakers are headphones.
DSSPEAKER_MONO

	The speakers are monaural.
DSSPEAKER_QUAD

	The speakers are quadraphonic.
DSSPEAKER_STEREO

	The speakers are stereo (default value).
DSSPEAKER_SURROUND

	The speakers are surround sound.
Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_INVALIDPARAM	DSERR_UNINITIALIZED
See Also

 IDirectSound, IDirectSound::GetSpeakerConfig


IDirectSoundBuffer Interface


IDirectSoundBuffer Interface Method Groups

Applications use the methods of the IDirectSoundBuffer interface to create DirectSoundBuffer objects and set up the environment. The methods can be organized into the following groups:

Information	GetCaps
	GetFormat
	GetStatus
	SetFormat
IUnknown	AddRef
	QueryInterface
	Release
Memory management	Initialize
	Restore
Play management	GetCurrentPosition
	Lock
	Play
	SetCurrentPosition
	Stop
	Unlock
Sound management	GetFrequency
	GetPan
	GetVolume
	SetFrequency
	SetPan
	SetVolume
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the DirectSoundBuffer object without affecting the functionality of the original interface.


IDirectSoundBuffer::AddRef

Increases the reference count of the DirectSoundBuffer object by 1. This method is part of the IUnknown interface inherited by DirectSound.

ULONG AddRef( );

Parameters

Return Values

Returns the new reference count of the object.

Remarks

When the DirectSoundBuffer object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirectSoundBuffer::Release method to decrease the reference count of the object by 1.

See Also

 IDirectSoundBuffer::QueryInterface, IDirectSoundBuffer::Release


IDirectSoundBuffer::GetCaps

Retrieves the capabilities of the DirectSoundBuffer object.

HRESULT GetCaps(
LPDSBCAPS lpDSBufferCaps
);

Parameters

lpDSBufferCaps

Address of a DSBCAPS structure to contain the capabilities of this sound buffer.

Return Values

Returns DS_OK if successful, or DSERR_INVALIDPARAM otherwise.

Remarks

The DSBCAPS structure contains similar information to the DSBUFFERDESC structure passed to the IDirectSound::CreateSoundBuffer method, with some additional information. This additional information can include the location of the buffer, either in hardware or software, and some cost measures. Examples of cost measures include the time it takes to download to a hardware buffer and the processing overhead required to mix and play the buffer when it is in the system memory.

The flags specified in the dwFlags member of the DSBCAPS structure are the same flags used by the DSBUFFERDESC structure. The only difference is that in the DSBCAPS structure, either DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE will be specified according to the location of the buffer memory. In the DSBUFFERDESC structure, these flags are optional and, depending on which flag is specified, force the buffer to be located in either hardware or software.

See Also

 DSBCAPS, DSBUFFERDESC, IDirectSoundBuffer, IDirectSound::CreateSoundBuffer


IDirectSoundBuffer::GetCurrentPosition

Retrieves the current position of the play and write cursors in the sound buffer.

HRESULT GetCurrentPosition(
LPDWORD lpdwCurrentPlayCursor,
LPDWORD lpdwCurrentWriteCursor
);

Parameters

lpdwCurrentPlayCursor

Address of a variable to contain the current play position in the DirectSoundBuffer object. This position is an offset within the sound buffer and is specified in bytes.

lpdwCurrentWriteCursor

Address of a variable to contain the current write position in the DirectSoundBuffer object. This position is an offset within the sound buffer and is specified in bytes.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_INVALIDPARAM	DSERR_PRIOLEVELNEEDED
Remarks

The write cursor indicates the position at which it is safe to write new data into the buffer. The write cursor always leads the play cursor, typically by about 15 milliseconds worth of audio data.

It is always safe to change data that is behind the position indicated by the lpdwCurrentPlayCursor parameter.

See Also

 IDirectSoundBuffer, IDirectSoundBuffer::SetCurrentPosition


IDirectSoundBuffer::GetFormat

Retrieves a description of the format of the sound data in the buffer, or the buffer size needed to retrieve the format description.

HRESULT GetFormat(
LPWAVEFORMATEX lpwfxFormat,
DWORD dwSizeAllocated,
LPDWORD lpdwSizeWritten
);

Parameters

lpwfxFormat

Address of the WAVEFORMATEX structure to contain a description of the sound data in the buffer. To retrieve the buffer size needed to contain the format description, specify NULL.

dwSizeAllocated

Size, in bytes, of the WAVEFORMATEX structure. DirectSound writes, at most, dwSizeAllocated bytes to that pointer; if the WAVEFORMATEX structure requires more memory, it is truncated.

lpdwSizeWritten

Address of a variable to contain the number of bytes written to the WAVEFORMATEX structure. This parameter can be NULL.

Return Values

Returns DS_OK if successful, or DSERR_INVALIDPARAM otherwise.

Remarks

The WAVEFORMATEX structure can have a variable length that depends on the details of the format. Before retrieving the format description, the application should query the DirectSoundBuffer object for the size of the format by calling this method and specifying NULL for the lpwfxFormat parameter. The size of the structure will be returned in the lpdwSizeWritten parameter. The application can then allocate sufficient memory and call IDirectSoundBuffer::GetFormat again to retrieve the format description.

See Also

 IDirectSoundBuffer, IDirectSoundBuffer::SetFormat


IDirectSoundBuffer::GetFrequency

Retrieves the frequency, in samples per second, at which the buffer is being played. This value will be in the range of 100-100,000.

HRESULT GetFrequency(
LPDWORD lpdwFrequency
);

Parameters

lpdwFrequency

Address of the variable that represents the frequency at which the audio buffer is being played.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_CONTROLUNAVAIL	DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED
See Also

 IDirectSoundBuffer, IDirectSoundBuffer::SetFrequency


IDirectSoundBuffer::GetPan

Retrieves a variable that represents the relative volume between the left and right audio channels.

HRESULT GetPan(
LPLONG lplPan
);

Parameters

lplPan

Address of a variable to contain the relative mix between the left and right speakers.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_CONTROLUNAVAIL	DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED
Remarks

The returned value is measured in hundredths of a decibel (dB), in the range of -10,000 to 10,000. The value -10,000 means the right channel is attenuated by 100 dB. The value 10,000 means the left channel is attenuated by 100 dB. 0 is the neutral value; a pan value of 0 means that both channels are at full volume (they are attenuated by 0 decibels). At any setting other than 0, one of the channels is at full volume and the other is attenuated.

A pan of -2173 means that the left channel is at full volume and the right channel is attenuated by 21.73 dB. Similarly, a pan of 870 means that the left channel is attenuated by 8.7 dB and the right channel is at full volume. A pan of -10,000 means that the right channel is silent and the sound is "all the way to the left," while a pan of 10,000 means that the left channel is silent and the sound is "all the way to the right."

The pan control acts cumulatively with the volume control.

See Also

 IDirectSoundBuffer, IDirectSoundBuffer::GetVolume, IDirectSoundBuffer::SetPan, IDirectSoundBuffer::SetVolume


IDirectSoundBuffer::GetStatus

Retrieves the current status of the sound buffer.

HRESULT GetStatus(
LPDWORD lpdwStatus
);

Parameters

lpdwStatus

Address of a variable to contain the status of the sound buffer. The status can be set to one of the following values:

DSBSTATUS_BUFFERLOST

	The buffer is lost and must be restored before it can be played or locked.
DSBSTATUS_LOOPING

	The buffer is being looped. If this value is not set, the buffer will stop when it reaches the end of the sound data. Note that if this value is set, the buffer must also be playing.
DSBSTATUS_PLAYING

	The buffer is being played. If this value is not set, the buffer is stopped.
Return Values

Returns DS_OK if successful, or DSERR_INVALIDPARAM otherwise.

See Also

 IDirectSoundBuffer


IDirectSoundBuffer::GetVolume

Retrieves the current volume for this sound buffer.

HRESULT GetVolume(
LPLONG lplVolume
);

Parameters

lplVolume

Address of the variable to contain the volume associated with the specified DirectSound buffer.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_CONTROLUNAVAIL	DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED
Remarks

The volume is specified in hundredths of decibels (dB), and ranges from 0 to -10,000. The value 0 represents the original, unadjusted volume of the stream. The value -10,000 indicates an audio volume attenuated by 100 dB, which, for all practical purposes, is silence. Amplification is not currently supported by DirectSound.

The decibel (dB) scale corresponds to the logarithmic hearing characteristics of the ear. For example, an attenuation of 10 dB makes a buffer sound half as loud, and an attenuation of 20 dB makes a buffer sound one quarter as loud.

See Also

 IDirectSoundBuffer, IDirectSoundBuffer::SetVolume


IDirectSoundBuffer::Initialize

Initializes a DirectSoundBuffer object if it has not yet been initialized.

HRESULT Initialize(
LPDIRECTSOUND lpDirectSound,
LPDSBUFFERDESC lpDSBufferDesc
);

Parameters

lpDirectSound

Address of the DirectSound object associated with this DirectSoundBuffer object.

lpDSBufferDesc

Address of a DSBUFFERDESC structure that contains the values used to initialize this sound buffer.

Return Values

Returns DSERR_ALREADYINITIALIZED.

Remarks

Because the IDirectSound::CreateSoundBuffer method calls IDirectSoundBuffer::Initialize internally, it is not needed for the current release of DirectSound. This method is provided for future extensibility.

See Also

 DSBUFFERDESC, IDirectSound::CreateSoundBuffer, IDirectSoundBuffer


IDirectSoundBuffer::Lock

Obtains a valid write pointer to the sound buffer's audio data.

HRESULT Lock(
DWORD dwWriteCursor,
DWORD dwWriteBytes,
LPVOID lplpvAudioPtr1,
LPDWORD lpdwAudioBytes1,
LPVOID lplpvAudioPtr2,
LPDWORD lpdwAudioBytes2,
DWORD dwFlags
);

Parameters

dwWriteCursor

Offset, in bytes, from the start of the buffer to where the lock begins. This parameter is ignored if DSBLOCK_FROMWRITECURSOR is specified in the dwFlags parameter.

dwWriteBytes

Size, in bytes, of the portion of the buffer to lock. Note that the sound buffer is conceptually circular.

lplpvAudioPtr1

Address of a pointer to contain the first block of the sound buffer to be locked.

lpdwAudioBytes1

Address of a variable to contain the number of bytes pointed to by the lplpvAudioPtr1 parameter. If this value is less than the dwWriteBytes parameter, lplpvAudioPtr2 will point to a second block of sound data.

lplpvAudioPtr2

Address of a pointer to contain the second block of the sound buffer to be locked. If the value of this parameter is NULL, the lplpvAudioPtr1 parameter points to the entire locked portion of the sound buffer.

lpdwAudioBytes2

Address of a variable to contain the number of bytes pointed to by the lplpvAudioPtr2 parameter. If lplpvAudioPtr2 is NULL, this value will be 0.

dwFlags

Flags modifying the lock event. The following flag is defined:

DSBLOCK_FROMWRITECURSOR

	Locks from the current write cursor, making a call to IDirectSoundBuffer::GetCurrentPosition unnecessary. If this flag is specified, the dwWriteCursor parameter is ignored. This flag is optional.
Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_BUFFERLOST	DSERR_INVALIDCALL
DSERR_INVALIDPARAM	DSERR_PRIOLEVELNEEDED
Remarks

This method accepts an offset and a byte count, and returns two write pointers and their associated sizes. Two pointers are required because sound buffers are circular. If the locked bytes do not wrap around the end of the buffer, the second pointer, lplpvAudioBytes2, will be NULL. However, if the bytes do wrap around, then the second pointer will point to the beginning of the buffer.

If the application passes NULL for the lplpvAudioPtr2 and lpdwAudioBytes2 parameters, DirectSound will not lock the wraparound portion of the buffer.

The application should write data into the pointers returned by the IDirectSoundBuffer::Lock method and then call the IDirectSoundBuffer::Unlock method to release the buffer back to DirectSound. The sound buffer should not be locked for long periods of time; if it is, the play cursor will reach the locked bytes and configuration-dependent audio problems, possibly random noise, will result.

Warning

This method returns a write pointer only. The application should not try to read sound data from this pointer; the data may not be valid even though the DirectSoundBuffer object contains valid sound data. For example, if the buffer is located in onboard memory, the pointer may be an address to a temporary buffer in main system memory. When IDirectSoundBuffer::Unlock is called, this temporary buffer will be transferred to the onboard memory.

See Also

 IDirectSoundBuffer, IDirectSoundBuffer::GetCurrentPosition, IDirectSoundBuffer::Unlock


IDirectSoundBuffer::Play

Causes the sound buffer to play from the current position.

HRESULT Play(
DWORD dwReserved1,
DWORD dwReserved2,
DWORD dwFlags
);

Parameters

dwReserved1

This parameter is reserved. Its value must be 0.

dwReserved2

This parameter is reserved. Its value must be 0.

dwFlags

Flags specifying how to play the buffer. The following flag is defined:

DSBPLAY_LOOPING

	Once the end of the audio buffer is reached, play restarts at the beginning of the buffer. Play continues until explicitly stopped. This flag must be set when playing primary buffers.
Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_BUFFERLOST	DSERR_INVALIDCALL
DSERR_INVALIDPARAM	DSERR_PRIOLEVELNEEDED
Remarks

For secondary buffers, this method will cause the buffer to be mixed into the primary buffer and output to the sound device. If this is the first buffer to play, it will implicitly create a primary buffer and start playing that buffer; the application does not need to explicitly direct the primary buffer to play.

If the buffer specified in the method is already playing, the call to the method will succeed and the buffer will continue to play. However, the flags that define playback characteristics are superseded by the flags defined in the most recent call.

Primary buffers must be played with the DSBPLAY_LOOPING flag set.

For primary sound buffers, this method will cause them to start playing to the sound device. If the application is set to the DSSCL_WRITEPRIMARY cooperative level, this will cause the audio data in the primary buffer to be output to the sound device. However, if the application is set to any other cooperative level, this method will ensure that the primary buffer is playing even when no secondary buffers are playing; in that case, silence will be played. This may reduce processing overhead when sounds are started and stopped in sequence since the primary buffer will be playing continuously rather than stopping and starting between secondary buffers.

Note

Before this method can be called on any sound buffer, the application must call the IDirectSound::SetCooperativeLevel method and specify a cooperative level, typically DSSCL_NORMAL. If IDirectSound::SetCooperativeLevel has not been called, the IDirectSoundBuffer::Play method returns the DSERR_PRIOLEVELNEEDED error value.

See Also

 IDirectSoundBuffer, IDirectSound::SetCooperativeLevel


IDirectSoundBuffer::QueryInterface

Determines if the DirectSoundBuffer object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by DirectSound.

HRESULT QueryInterface(
REFIID riid,
LPVOID * ppvObj
);

Parameters

riid

Reference identifier of the interface being requested.

ppvObj

Address of a location that will be filled with the returned interface pointer if the query is successful.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_INVALIDPARAM	DSERR_GENERIC
Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirectSoundBuffer::QueryInterface method allows DirectSoundBuffer objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.

See Also

 IDirectSoundBuffer::AddRef, IDirectSoundBuffer::Release


IDirectSoundBuffer::Release

Decreases the reference count of the DirectSoundBuffer object by 1. This method is part of the IUnknown interface inherited by DirectSound.

ULONG Release( );

Parameters

Return Values

Returns the new reference count of the object.

Remarks

The DirectSound object deallocates itself when its reference count reaches 0. Use the IDirectSoundBuffer::AddRef method to increase the reference count of the object by 1.

See Also

 IDirectSoundBuffer::AddRef, IDirectSoundBuffer::QueryInterface


IDirectSoundBuffer::Restore

Restores the memory allocation for a lost sound buffer for the specified DirectSoundBuffer object.

HRESULT Restore( );

Parameters

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_BUFFERLOST	DSERR_INVALIDCALL
DSERR_INVALIDPARAM	DSERR_PRIOLEVELNEEDED
Remarks

If the application does not have the input focus, IDirectSoundBuffer::Restore may not succeed. For example, if the application with the input focus has the DSSCL_WRITEPRIMARY cooperative level, no other application will be able to restore its buffers. Similarly, an application with the DSSCL_WRITEPRIMARY cooperative level must have the input focus to restore its primary buffer.

Once DirectSound restores the buffer memory, the application must rewrite the buffer with valid sound data. DirectSound cannot restore the contents of the memory, only the memory itself.

The application can receive notification that a buffer is lost when it specifies that buffer in a call to the IDirectSoundBuffer::Lock or IDirectSoundBuffer::Play method. These methods return DSERR_BUFFERLOST to indicate a lost buffer. The IDirectSoundBuffer::GetStatus method can also be used to retrieve the status of the sound buffer and test for the DSBSTATUS_BUFFERLOST flag.

See Also

 IDirectSoundBuffer, IDirectSoundBuffer::Lock, IDirectSoundBuffer::Play, IDirectSoundBuffer::GetStatus


IDirectSoundBuffer::SetCurrentPosition

Moves the current play cursor for secondary sound buffers.

HRESULT SetCurrentPosition(
DWORD dwNewPosition
);

Parameters

dwNewPosition

New position, in bytes, from the beginning of the buffer that will be used when the sound buffer is played.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_INVALIDCALL	DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED
Remarks

This method cannot be called on primary sound buffers.

If the buffer is playing, it will immediately move to the new position and continue. If it is not playing, it will begin from the new position the next time the IDirectSoundBuffer::Play method is called.

See Also

 IDirectSoundBuffer, IDirectSoundBuffer::GetCurrentPosition, IDirectSoundBuffer::Play


IDirectSoundBuffer::SetFormat

Sets the format of the primary sound buffer for the application. Whenever this application has the input focus, DirectSound will set the primary buffer to the specified format.

HRESULT SetFormat(
LPWAVEFORMATEX lpfxFormat
);

Parameters

lpfxFormat

Address of a WAVEFORMATEX structure that describes the new format for the primary sound buffer.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_BADFORMAT	DSERR_INVALIDCALL
DSERR_INVALIDPARAM	DSERR_OUTOFMEMORY
DSERR_PRIOLEVELNEEDED	DSERR_UNSUPPORTED
Remarks

A call to this method fails if the sound buffer is playing or the hardware does not directly support the requested pulse coded modulation (PCM) format. It will also fail if the calling application has the DSSCL_NORMAL cooperative level.

If a secondary buffer requires a format change, the application should create a new DirectSoundBuffer object using the new format.

DirectSound supports PCM formats; it does not currently support compressed formats.

See Also

 IDirectSoundBuffer, IDirectSoundBuffer::GetFormat


IDirectSoundBuffer::SetFrequency

Sets the frequency at which the audio samples are played.

HRESULT SetFrequency(
DWORD dwFrequency
);

Parameters

dwFrequency

New frequency, in Hz, at which to play the audio samples. The value must be between 100 and 100,000.

If the value is 0, the frequency is reset to the current buffer format. This format is specified in the IDirectSound::CreateSoundBuffer method.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_CONTROLUNAVAIL	DSERR_GENERIC
DSERR_INVALIDPARAM	DSERR_PRIOLEVELNEEDED
Remarks

Increasing or decreasing the frequency changes the perceived pitch of the audio data. This method does not affect the format of the buffer.

See Also

 IDirectSoundBuffer, IDirectSound::CreateSoundBuffer, IDirectSoundBuffer::GetFrequency, IDirectSoundBuffer::Play, IDirectSoundBuffer::SetFormat


IDirectSoundBuffer::SetPan

Specifies the relative volume between the left and right channels.

HRESULT SetPan(
LONG lPan
);

Parameters

lPan

Relative volume between the left and right channels. This value has a range of -10,000 to 10,000 and is measured in hundredths of a decibel.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_CONTROLUNAVAIL	DSERR_GENERIC
DSERR_INVALIDPARAM	DSERR_PRIOLEVELNEEDED
Remarks

0 is the neutral value for lPan and indicates that both channels are at full volume (attenuated by 0 decibels). At any other setting, one of the channels is at full volume and the other is attenuated. For example, a pan of -2173 means that the left channel is at full volume and the right channel is attenuated by 21.73 dB. Similarly, a pan of 870 means that the left channel is attenuated by 8.7 dB and the right channel is at full volume.

A pan of -10,000 means that the right channel is silent and the sound is "all the way to the left," while a pan of 10,000 means that the left channel is silent and the sound is "all the way to the right."

The pan control is cumulative with the volume control.

See Also

 IDirectSoundBuffer, IDirectSoundBuffer::GetPan, IDirectSoundBuffer::GetVolume, IDirectSoundBuffer::SetVolume


IDirectSoundBuffer::SetVolume

Changes the volume of a sound buffer.

HRESULT SetVolume(
LONG lVolume
);

Parameters

lVolume

New volume requested for this sound buffer. Values range from 0 (0 dB, no volume adjustment) to -10,000 (-100 dB, essentially silent). DirectSound does not currently support amplification.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_CONTROLUNAVAIL	DSERR_GENERIC
DSERR_INVALIDPARAM	DSERR_PRIOLEVELNEEDED
Remarks

Volume units of are in hundredths of decibels, where 0 is the original volume of the stream.

Positive decibels correspond to amplification and negative decibels correspond to attenuation. The decibel scale corresponds to the logarithmic hearing characteristics of the ear. An attenuation of 10 dB makes a buffer sound half as loud; an attenuation of 20 dB makes a buffer sound one quarter as loud. DirectSound does not currently support amplification.

The pan control is cumulative with the volume control.

See Also

 IDirectSoundBuffer, IDirectSoundBuffer::GetPan, IDirectSoundBuffer::GetVolume, IDirectSoundBuffer::SetPan


IDirectSoundBuffer::Stop

Causes the sound buffer to stop playing.

HRESULT Stop( );

Parameters

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_INVALIDPARAM	DSERR_PRIOLEVELNEEDED
Remarks

For secondary buffers, IDirectSoundBuffer::Stop will set the current position of the buffer to the sample that follows the last sample played. This means that if the IDirectSoundBuffer::Play method is called on the buffer, it will continue playing where it left off.

For primary buffers, if an application has the DSSCL_WRITEPRIMARY level, this method will stop the buffer and reset the current position to 0 (the beginning of the buffer). This is necessary because the primary buffers on most sound cards can only play from the beginning of the buffer.

However, if IDirectSoundBuffer::Stop is called on a primary buffer and the application has a cooperative level other than DSSCL_WRITEPRIMARY, this method simply reverses the effects of IDirectSoundBuffer::Play. It configures the primary buffer to stop if no secondary buffers are playing. If other buffers are playing in this or other applications, the primary buffer will not actually stop until they are stopped. This method is useful because playing the primary buffer consumes processing overhead even if the buffer is playing sound data with the amplitude of 0 dB.

See Also

 IDirectSoundBuffer, IDirectSoundBuffer::Play


IDirectSoundBuffer::Unlock

Releases a locked sound buffer.

HRESULT Unlock(
LPVOID lpvAudioPtr1,
DWORD dwAudioBytes1,
LPVOID lpvAudioPtr2,
DWORD dwAudioBytes2
);

Parameters

lpvAudioPtr1

Address of the value retrieved in the lplpvAudioPtr1 parameter of the IDirectSoundBuffer::Lock method.

dwAudioBytes1

Number of bytes actually written into the lpvAudioPtr1 parameter. It should not exceed the number of bytes returned by the IDirectSoundBuffer::Lock method.

lpvAudioPtr2

Address of the value retrieved in the lplpvAudioPtr2 parameter of the IDirectSoundBuffer::Lock method.

dwAudioBytes2

Number of bytes actually written into the lpvAudioPtr2 parameter. It should not exceed the number of bytes returned by the IDirectSoundBuffer::Lock method.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise:

DSERR_INVALIDCALL	DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED
Remarks

An application must pass both pointers, lpvAudioPtr1 and lpvAudioPtr2, returned by the IDirectSoundBuffer::Lock method to ensure the correct pairing of IDirectSoundBuffer::Lock and IDirectSoundBuffer::Unlock. The second pointer is needed even if 0 bytes were written to the second pointer.

Applications must pass the number of bytes actually written to the two pointers in the parameters dwAudioBytes1 and dwAudioBytes2.

Make sure the sound buffer does not remain locked for long periods of time.

See Also

 IDirectSoundBuffer, IDirectSoundBuffer::GetCurrentPosition, IDirectSoundBuffer::Lock


Structures


DSBCAPS

Specifies the capabilities of a DirectSound buffer object, for use by the IDirectSoundBuffer::GetCaps method.

typedef struct _DSBCAPS {

    DWORD dwSize;

    DWORD dwFlags;

    DWORD dwBufferBytes;

    DWORD dwUnlockTransferRate;

    DWORD dwPlayCpuOverhead;

} DSBCAPS, *LPDSBCAPS;

Members

dwSize

Size of this structure, in bytes.

dwFlags

Flags that specify buffer-object capabilities.

DSBCAPS_CTRLFREQUENCY

	The buffer must have frequency control capability.
DSBCAPS_CTRLPAN

	The buffer must have pan control capability.
DSBCAPS_CTRLVOLUME

	The buffer must have volume control capability.
DSBCAPS_GETCURRENTPOSITION2

	Indicates that IDirectSoundBuffer::GetCurrentPosition should use the new behavior of the play cursor. In DirectSound on the Game SDK, the play cursor was significantly ahead of the actual playing sound on emulated sound cards; it was right behind the write cursor. Now, if the DSBCAPS_GETCURRENTPOSITION2 flag is specified, the application can get a more accurate play position. If this flag is not specified, the old behavior is preserved for compatibility. Note that this flag only affects emulated sound cards; if a DirectSound driver is present, the play cursor is accurate for DirectSound on both the Game SDK and DirectX 2.
DSBCAPS_LOCHARDWARE

	Forces the buffer to use hardware mixing, even if DSBCAPS_STATIC is not specified. If the device does not support hardware mixing, or the required hardware memory is not available, the call to IDirectSound::CreateSoundBuffer will fail. The application must ensure that a mixing channel will be available for this buffer; this condition is not guaranteed.
DSBCAPS_LOCSOFTWARE

	Forces the buffer to be stored in software memory and use software mixing, even if DSBCAPS_STATIC is specified and hardware resources are available.
DSBCAPS_PRIMARYBUFFER

	Indicates that the buffer is a primary sound buffer. If this value is not specified, a secondary buffer will be created.
DSBCAPS_STATIC

	Indicates that the buffer will be used for static sound data. Typically, these buffers are loaded once and played many times. These buffers are candidates for hardware memory.
DSBCAPS_STICKYFOCUS

	Changes the focus behavior of the sound buffer. This flag can be specified in an IDirectSound::CreateSoundBuffer call. With this flag set, an application using DirectSound can continue to play its sticky focus buffers if the user switches to another application not using DirectSound. In this situation, the application's normal buffers will be muted, but the sticky focus buffers will still be audible. This is useful for non-game applications, such as movie playback (ActiveMovie™) when the user wants to hear the soundtrack while typing in Word or Excel, for example. If the user switches to DirectSound, all sound buffers, both normal and sticky focus, in the previous application will be muted.
dwBufferBytes

Size of this buffer, in bytes.

dwUnlockTransferRate

Specifies the rate, in kilobytes per second, that data is transferred to the buffer memory when IDirectSoundBuffer::Unlock is called. High-performance applications can use this value to determine the time required for IDirectSoundBuffer::Unlock to execute. For software buffers located in system memory, the rate will be very high since no processing is required. For hardware buffers, the rate may be slower because the buffer might have to be downloaded to the sound card, which may have a limited transfer rate.

dwPlayCpuOverhead

Specifies the processing overhead as a percentage of main processing cycles needed to mix this sound buffer. For hardware buffers, this member will be 0 because the mixing is performed by the sound device. For software buffers, this member depends on the buffer format and the speed of the system processor.

Remarks

The DSBCAPS structure contains information similar to that found in the DSBUFFERDESC structure passed to the IDirectSound::CreateSoundBuffer method, with some additional information. Additional information includes the location of the buffer (hardware or software) and some cost measures (such as the time to download the buffer if located in hardware, and the processing overhead to play the buffer if it is mixed in software).

Note that the dwFlags member of the DSBCAPS structure contains the same flags used by the DSBUFFERDESC structure. The only difference is that in the DSBCAPS structure, either the DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flag will be specified, according to the location of the buffer memory. In the DSBUFFERDESC structure, these flags are optional and are used to force the buffer to be located in either hardware or software.

The information for the DSBCAPS_GETCURRENTPOSITION2 flag is new since the DirectX 2 SDK was released. For a complete list of new information, see New Information.

See Also

 IDirectSound::CreateSoundBuffer, IDirectSoundBuffer::GetCaps


DSBUFFERDESC

Describes the necessary characteristics of a new DirectSoundBuffer object. This structure is used by the IDirectSound::CreateSoundBuffer method.

typedef struct _DSBUFFERDESC{

    DWORD           dwSize;

    DWORD           dwFlags;

    DWORD           dwBufferBytes;

    DWORD           dwReserved;

    LPWAVEFORMATEX  lpwfxFormat;

} DSBUFFERDESC, *LPDSBUFFERDESC;

Members

dwSize

Size of this structure, in bytes.

dwFlags

Identifies the capabilities to include when creating a new DirectSoundBuffer object. Specify one or more of the following:

DSBCAPS_CTRLALL

	The buffer must have all control capabilities.
DSBCAPS_CTRLDEFAULT

	The buffer should have default control options. This is the same as specifying the DSBCAPS_CTRLPAN, DSBCAPS_CTRLVOLUME, and DSBCAPS_CTRLFREQUENCY flags.
DSBCAPS_CTRLFREQUENCY

	The buffer must have frequency control capability.
DSBCAPS_CTRLPAN

	The buffer must have pan control capability.
DSBCAPS_CTRLVOLUME

	The buffer must have volume control capability.
DSBCAPS_GETCURRENTPOSITION2

	Indicates that IDirectSoundBuffer::GetCurrentPosition should use the new behavior of the play cursor. In DirectSound on the Game SDK, the play cursor was significantly ahead of the actual playing sound on emulated sound cards; it was right behind the write cursor. Now, if the DSBCAPS_GETCURRENTPOSITION2 flag is specified, the application can get a more accurate play position. If this flag is not specified, the old behavior is preserved for compatibility. Note that this flag only affects emulated sound cards; if a DirectSound driver is present, the play cursor is accurate for DirectSound on both the Game SDK and DirectX 2.
DSBCAPS_LOCHARDWARE

	Forces the buffer to use hardware mixing, even if DSBCAPS_STATIC is not specified. If the device does not support hardware mixing or if the required hardware memory is not available, the call to the IDirectSound::CreateSoundBuffer method will fail. The application must ensure that a mixing channel will be available for this buffer; this condition is not guaranteed.
DSBCAPS_LOCSOFTWARE

	Forces the buffer to be stored in software memory and use software mixing, even if DSBCAPS_STATIC is specified and hardware resources are available.
DSBCAPS_PRIMARYBUFFER

	Indicates that the buffer is a primary sound buffer. If this value is not specified, a secondary buffer will be created.
DSBCAPS_STATIC

	Indicates that the buffer will be used for static sound data. Typically, these buffers are loaded once and played many times. These buffers are candidates for hardware memory.
DSBCAPS_STICKYFOCUS

	Changes the focus behavior of the sound buffer. This flag can be specified in an IDirectSound::CreateSoundBuffer call. With this flag set, an application using DirectSound can continue to play its sticky focus buffers if the user switches to another application not using DirectSound. In this situation, the application's normal buffers will be muted, but the sticky focus buffers will still be audible. This is useful for non-game applications, such as movie playback (ActiveMovie) when the user wants to hear the soundtrack while typing in Word or Excel, for example. If the user switches to DirectSound, all sound buffers, both normal and sticky focus, in the previous application will be muted.
dwBufferBytes

Size of the new buffer, in bytes. This value must be 0 when creating primary buffers.

dwReserved

This value is reserved. Do not use.

lpwfxFormat

Address of a structure specifying the waveform format for the buffer. This value must be NULL for primary buffers. The application can use IDirectSoundBuffer::SetFormat to set the format of the primary buffer.

Remarks

The DSBCAPS_LOCHARDWARE and DSBCAPS_LOCSOFTWARE flags used in the dwFlags member are optional and mutually exclusive. DSBCAPS_LOCHARDWARE forces the buffer to reside in memory located in the sound card. DSBCAPS_LOCSOFTWARE forces the buffer to reside in main system memory, if possible.

These flags are also defined for the dwFlags member of the DSBCAPS structure, and when used there, the specified flag indicates the actual location of the DirectSoundBuffer object.

When creating a primary buffer, applications must set the dwBufferBytes member to 0; DirectSound will determine the optimal buffer size for the particular sound device in use. To determine the size of a created primary buffer, call IDirectSoundBuffer::GetCaps.

The information for the DSBCAPS_GETCURRENTPOSITION2 and DSBCAPS_STICKYFOCUS flags is new since the DirectX 2 SDK was released. For a complete list of new information, see New Information.

See Also

 IDirectSound::CreateSoundBuffer


DSCAPS

Specifies the capabilities of a DirectSound device for use by the IDirectSound::GetCaps method.

typedef struct _DSCAPS {

    DWORD  dwSize;

    DWORD  dwFlags;

    DWORD  dwMinSecondarySampleRate;

    DWORD  dwMaxSecondarySampleRate;

    DWORD  dwPrimaryBuffers;

    DWORD  dwMaxHwMixingAllBuffers;

    DWORD  dwMaxHwMixingStaticBuffers;

    DWORD  dwMaxHwMixingStreamingBuffers;

    DWORD  dwFreeHwMixingAllBuffers;

    DWORD  dwFreeHwMixingStaticBuffers;

    DWORD  dwFreeHwMixingStreamingBuffers;

    DWORD  dwMaxHw3DAllBuffers;

    DWORD  dwMaxHw3DStaticBuffers;

    DWORD  dwMaxHw3DStreamingBuffers;

    DWORD  dwFreeHw3DAllBuffers;

    DWORD  dwFreeHw3DStaticBuffers;

    DWORD  dwFreeHw3DStreamingBuffers;

    DWORD  dwTotalHwMemBytes;

    DWORD  dwFreeHwMemBytes;

    DWORD  dwMaxContigFreeHwMemBytes;

    DWORD  dwUnlockTransferRateHwBuffers;

    DWORD  dwPlayCpuOverheadSwBuffers;

    DWORD  dwReserved1;

    DWORD  dwReserved2;

} DSCAPS, *LPDSCAPS;

Members

dwSize

Size of this structure, in bytes.

dwFlags

Specifies device capabilities. Can be one or more of the following:

DSCAPS_CERTIFIED

	This driver has been tested and certified by Microsoft.
DSCAPS_CONTINUOUSRATE

	The device supports all sample rates between the dwMinSecondarySampleRate and dwMaxSecondarySampleRate member values. Typically, this means that the actual output rate will be within +/- 10 Hz of the requested frequency.
DSCAPS_EMULDRIVER

	The device does not have a DirectSound driver installed, so it is being emulated through the waveform-audio functions. Performance degradation should be expected.
DSCAPS_PRIMARY16BIT

	The device supports primary buffers with 16-bit samples.
DSCAPS_PRIMARY8BIT

	The device supports primary buffers with 8-bit samples.
DSCAPS_PRIMARYMONO

	The device supports monophonic primary buffers.
DSCAPS_PRIMARYSTEREO

	The device supports stereo primary buffers.
DSCAPS_SECONDARY16BIT

	The device supports hardware-mixed secondary buffers with 16-bit samples.
DSCAPS_SECONDARY8BIT

	The device supports hardware-mixed secondary buffers with 8-bit samples.
DSCAPS_SECONDARYMONO

	The device supports hardware-mixed monophonic secondary buffers.
DSCAPS_SECONDARYSTEREO

	The device supports hardware-mixed stereo secondary buffers.
dwMinSecondarySampleRate and #dwMaxSecondarySampleRate

Minimum and maximum sample rate specifications that are supported by this device's hardware secondary sound buffers.

dwPrimaryBuffers

Number of primary buffers supported. This value will always be 1 for this release.

dwMaxHwMixingAllBuffers

Specifies the total number of buffers that can be mixed in hardware.

dwMaxHwMixingStaticBuffers

Specifies the maximum number of static buffers.

dwMaxHwMixingStreamingBuffers

Specifies the maximum number of streaming buffers.

Note

The value for MaxHwMixingAllBuffers may be less than the sum of dwMaxHwMixingStaticBuffers and dwMaxHwMixingStreamingBuffers. Resource trade-offs frequently occur.

dwFreeHwMixingAllBuffers, #dwFreeHwMixingStaticBuffers, and #dwFreeHwMixingStreamingBuffers

Description of the free, or unallocated, hardware mixing capabilities of the device. These values can be used by an application to determine whether hardware resources are available for allocation to a secondary sound buffer. Also, by comparing these values to the members that specify maximum mixing capabilities, the resources that are already allocated can be determined.

dwMaxHw3DAllBuffers, #dwMaxHw3DStaticBuffers, and #dwMaxHw3DStreamingBuffers

Description of the hardware 3D positional capabilities of the device. These will all be 0 for the first release.

dwFreeHw3DAllBuffers, #dwFreeHw3DStaticBuffers, and #dwFreeHw3DStreamingBuffers

Description of the free, or unallocated, hardware 3D positional capabilities of the device. These will all be 0 for the first release.

dwTotalHwMemBytes

Size, in bytes, of the amount of memory on the sound card that stores static sound buffers.

dwFreeHwMemBytes

Size, in bytes, of the free memory on the sound card.

dwMaxContigFreeHwMemBytes

Size, in bytes, of the largest contiguous block of free memory on the sound card.

dwUnlockTranferRateHwBuffers

Description of the rate, in kilobytes per second, at which data can be transferred to hardware static sound buffers (those located in onboard sound memory). This and the number of bytes transferred determines the duration of a call to the IDirectSoundBuffer::Unlock method.

dwPlayCpuOverheadSwBuffers

Description of the processing overhead, as a percentage of the central processing unit, needed to mix software buffers (those located in main system memory). This varies according to the bus type, the processor type, and the clock speed.

The unlock transfer rate for software buffers is 0 because the data does not need to be transferred anywhere. Similarly, the play processing overhead for hardware buffers is 0 because the mixing is done by the sound device.

dwReserved1, #dwReserved2

These values are reserved. Do not use.

See Also

 IDirectSound::GetCaps


Return Values

Errors are represented by negative values and cannot be combined. This table lists the values that can be returned by all IDirectSound and IDirectSoundBuffer methods. For a list of the error codes each method is capable of returning, see the individual method descriptions.

DS_OK

	The request completed successfully.
DSERR_ALLOCATED

	The request failed because resources, such as a priority level, were already in use by another caller.
DSERR_ALREADYINITIALIZED

	The object is already initialized.
DSERR_BADFORMAT

	The specified wave format is not supported.
DSERR_BUFFERLOST

	The buffer memory has been lost and must be restored.
DSERR_CONTROLUNAVAIL

	The control (volume, pan, and so forth) requested by the caller is not available.
DSERR_GENERIC

	An undetermined error occurred inside the DirectSound subsystem.
DSERR_INVALIDCALL

	This function is not valid for the current state of this object.
DSERR_INVALIDPARAM

	An invalid parameter was passed to the returning function.
DSERR_NOAGGREGATION

	The object does not support aggregation.
DSERR_NODRIVER

	No sound driver is available for use.
DSERR_OTHERAPPHASPRIO

	This value is obsolete and is not used.
DSERR_OUTOFMEMORY

	The DirectSound subsystem could not allocate sufficient memory to complete the caller's request.
DSERR_PRIOLEVELNEEDED

	The caller does not have the priority level required for the function to succeed.
DSERR_UNINITIALIZED

	The IDirectSound::Initialize method has not been called or has not been called successfully before other methods were called.
DSERR_UNSUPPORTED

	The function called is not supported at this time.


DirectPlay


Overview

The Microsoft® DirectPlay™ application programming interface (API) for Windows® 95 is a software interface that simplifies your application's access to communication services. DirectPlay was primarily developed for game communication, but could be used for other applications that require communication independent of the underlying transport, protocol, or online service.

Games are more fun if they can be played against real players, and the personal computer has richer connectivity options than any game platform in history. Instead of forcing you, as a game developer, to deal with the differences that each of these connectivity solutions represents, DirectPlay provides well defined, generalized communication capabilities. DirectPlay shields you from the underlying complexities of diverse connectivity implementations, freeing you to concentrate on producing a great game.


DirectPlay Architecture

DirectPlay uses a simple send/receive communication model to implement a connectivity API tailored to the needs of game play. The DirectPlay architecture is composed of two types of components: DirectPlay itself and the service provider. DirectPlay is provided by Microsoft and presents a common interface to the game. The service provider furnishes medium-specific communication services as requested by DirectPlay. Any organization, including online services, can supply service providers for specialized hardware and communications media. Microsoft includes two service providers with DirectPlay, one for networking and one for modem support.

The DirectPlay interface hides the complexities and unique tasks required to establish an arbitrary communications link inside the DirectPlay service provider implementation. When you design a game for use with DirectPlay, you need only concern yourself with the performance of the communications medium, not whether that medium is provided by a modem, network, or online service.

DirectPlay will dynamically bind to any DirectPlay service provider installed on the user's system. The game interacts with the DirectPlay object. The DirectPlay object interacts with one of the available DirectPlay service providers, and the selected service provider interacts with the transport or protocol.


Globally Unique Identifiers

Each game requires a globally unique identifier (GUID) that it uses to identify itself on the communications medium. These GUIDs, sometimes called UUIDs, can be generated on any computer that has a network card and a copy of Uuidgen.exe, provided as part of the Microsoft Win32® SDK. You create a GUID once while developing the game, and use that GUID throughout the life of the product. There is no need to register this number with Microsoft.


Using DirectPlay

Implement DirectPlay in your application using the following steps:

1	Request that the user of your application select a communication medium for the game.

You can identify the service providers installed on a personal computer by using the DirectPlayEnumerate function.

2	Create a DirectPlay object based on the selected provider by calling the DirectPlayCreate function and specifying the appropriate service provider GUID.

Calling the DirectPlayCreate function causes DirectPlay to load the library for the service provider selected.

3	Request game information, including preferences, from the user. You can store this information in the dwUser member of the DPSESSIONDESC structure.

If the user wants to start a new game, skip to step six.

4	Enumerate existing sessions (existing games that a user can join) by using the IDirectPlay::EnumSessions method.

5	If the user wants to join a game enumerated by the IDirectPlay::EnumSessions method, connect to that game by using the IDirectPlay::Open method and specify the DPOPEN_OPENSESSION flag.

6	If the user wants to start a new game, create a game by using the IDirectPlay::Open method and specifying the DPOPEN_CREATESESSION flag.

7	Create a player or players.

A player's communication capabilities can be determined using the IDirectPlay::GetCaps and IDirectPlay::GetPlayerCaps methods. Other players can be discovered by using the IDirectPlay::EnumPlayers method.

8	Exchange messages among players, including the name server (player ID 0), by using the IDirectPlay::Send and IDirectPlay::Receive methods.

Each player is associated with a friendly name and a formal name that the game can use for tasks such as error reporting and scoring. The game can exchange messages among players by using the unique player ID that is created with the player. The service provider, not DirectPlay, limits the number of players that can participate in a gaming session. In the current implementation, the number of players ranges from 16 for a modem connection to 256 for a network connection.

When using DirectPlay, you are able to define most messages in order to address the particular needs of the game. However, some system messages are defined by DirectPlay. For example, when a player quits or joins a game, that game receives a system message that provides the player's name and the status change that has just occurred. System messages are always sent by the name server, a virtual player whose player ID is 0. System messages start with a 32-bit value that identifies the type of message. Constants that represent system messages begin with 'DPSYS_', and have a corresponding message structure that must be used to interpret them.

Broadcasting a message to all players in the game is simply a matter of sending a message to the name server (that is, to player ID 0). Players receiving a message broadcast in this way see the message as having come from the player who sent it, not from the name server.

DirectPlay does not attempt to provide a general approach for game synchronization; to do so would necessarily impose limitations on the game-playing paradigm. However, the system includes some services that are designed to help you with these tasks. For example, you can specify a notification event when your application creates a player, then use the Microsoft Win32 function WaitForSingleObject to find out whether there is a message pending for that player.


Session Management

A DirectPlay session is an instance of a game. The applications you design can use DirectPlay's session-management functions to open or close a communication channel, save a session in the registry, or enumerate past sessions that have been saved in the registry. A game either creates a new session or enumerates existing or previous sessions and finds one to connect to. If a game has saved a session, it could enumerate previous sessions and perhaps reconnect to the saved session. (This is a particularly appropriate scenario in a modem environment, where a saved session would include phone numbers.) Not all DirectPlay service providers will support saving sessions, however, and this functionality is currently only implemented for modem connections.

The IDirectPlay::Open method is used to create new sessions or to connect to existing or saved sessions. A session is described by its corresponding DPSESSIONDESC structure. This structure contains game-specific values and session particulars, such as the name of the session, an optional password for the session, and the number of players to be allowed in the session. After opening a session, you can call the IDirectPlay::GetCaps method to retrieve the speed of the communications link. To save a record of the session in the registry, call the IDirectPlay::SaveSession method. For a modem connection, you can save the current session and later enumerate all of the saved sessions by calling IDirectPlay::EnumSessions and specifying the DPENUMSESSIONS_PREVIOUS flag. Opening one of these saved sessions retrieves the phone number for that session and dials it. When a game session is over, it can be closed with the IDirectPlay::Close method.


Player Management

The applications you design can use DirectPlay's player-management methods to manage the players in a game session. In addition to creating and destroying players, you can enumerate them or retrieve their communication capabilities.

The IDirectPlay::CreatePlayer and IDirectPlay::DestroyPlayer methods create and delete players in a game session. Upon creation, each player is given a friendly name, a formal name, and a DirectPlay player ID. The player ID is used by the game and DirectPlay to route message traffic. The friendly and formal names are not used internally by DirectPlay; instead, you can use them when communicating with the players. The IDirectPlay::GetPlayerName and IDirectPlay::SetPlayerName methods allow your application to work with the friendly and formal names while the game is being played. The IDirectPlay::EnableNewPlayers method enables or disables the addition of new players and can be used to prohibit the creation of new players once a game is in progress.

You can use the IDirectPlay::EnumPlayers method to discover what players are in a current game session and their friendly and formal names. This function is typically called immediately after the IDirectPlay::Open method opens an existing session. The IDirectPlay::GetPlayerCaps method retrieves information about the speed of a player's connection to the session.


Group Management

The group-management methods allow your application to create groups of players in a session. You can then use a single instance of the IDirectPlay::Send method to send messages to an entire group, rather than to one player at a time. Some service providers can send messages to groups more efficiently than they can send them to the individual players, so, in addition to simplifying player management, groups can be used to conserve communication channel bandwidth.

The IDirectPlay::CreateGroup and IDirectPlay::DestroyGroup methods create and delete a group of players. When you create a group, you assign it a friendly and formal name, just as you would when creating a player. The group is initially empty; you can use the IDirectPlay::AddPlayerToGroup and IDirectPlay::DeletePlayerFromGroup methods to control the membership of the group. The state of the IDirectPlay::EnableNewPlayers method does not affect the ability to create groups.

To discover what groups exist, you can call the IDirectPlay::EnumGroups method. To enumerate the players in a group, call the IDirectPlay::EnumGroupPlayers method.


Message Management

The message-management functions help your application route messages between game players. With the exception of a small number of messages that have been defined by the system, the messages can be defined in any way that you require. Messages should not be excessively large, however. You can use the IDirectPlay::Send method to send a message to an individual player, to a group, or to all the players in the session; simply specify a player ID, a group ID, or 0 as the destination.

To retrieve a message from the message queue, use the IDirectPlay::Receive method. This method allows you to specify whether to retrieve the first message in the queue, only the messages to a particular player, or only those from a particular player. You can use the IDirectPlay::GetMessageCount method to retrieve the number of messages waiting for a given player.


Reference


Functions

The DirectPlay functions are used to initiate communication through the DirectPlay interface. The DirectPlayCreate function is used to instantiate a DirectPlay object for a particular service provider. The DirectPlayEnumerate function is used to obtain a list of all the DirectPlay service providers installed on the system. This is the mechanism DirectPlay uses to support multiple communication transports and protocols. To utilize protocol-independent communication services, your application need only select a specific service provider and instantiate it.


DirectPlayCreate

Creates an instance of a DirectPlay object.

HRESULT DirectPlayCreate(
LPGUID lpGUID,
LPDIRECTPLAY FAR * lplpDP,
IUnknown FAR * pUnkOuter
);

Parameters

lpGUID

Address for the GUID that represents the driver to be created.

lplpDP

Address for a pointer to initialize with a valid DirectPlay pointer.

pUnkOuter

Address for the IUnknown interface. This parameter is provided for future compatibility with COM aggregation features. Presently, however, the DirectPlayCreate function will return an error if this parameter is anything but NULL.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_EXCEPTION	DPERR_INVALIDPARAMS
DPERR_UNAVAILABLE
Remarks

This function attempts to initialize a DirectPlay object and sets a pointer to it if successful. It is a good idea to call the DirectPlayEnumerate function immediately before initialization in order to determine what types of service providers are available.

See Also

 DirectPlayEnumerate


DirectPlayEnumerate

Enumerates the DirectPlay service providers installed on the system.

LT DirectPlayEnumerate(
LPDPENUMDPCALLBACK lpEnumDPCallback,
LPVOID lpContext
);

Parameters

lpEnumDPCallback

Address for the EnumDPCallback function that will be called with a description of each DirectPlay service provider interface installed in the system.

lpContext

Address for a caller-defined structure that will be passed to the callback function each time the function is invoked.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_EXCEPTION	DPERR_GENERIC


Callback Functions

Most of the functionality of DirectPlay is provided by the methods of its Component Object Model (COM) interfaces. This section lists the callback functions that are not implemented as part of a COM interface.


EnumDPCallback

Application-defined callback procedure for the DirectPlayEnumerate function.

BOOL EnumDPCallback(
LPGUID lpSPGuid,
LPSTR lpFriendlyName,
DWORD dwMajorVersion,
DWORD dwMinorVersion,
LPVOID lpContext
);

Parameters

lpSPGuid

Address for the unique identifier of the DirectPlay service provider driver.

lpFriendlyName

Address for a string containing the driver description.

dwMajorVersion

Major version number of the driver.

dwMinorVersion

Minor version number of the driver.

lpContext

Address for a caller-defined context.

Return Values

Returns TRUE to continue the enumeration or FALSE to stop it.


EnumPlayersCallback

Application-defined callback procedure for the IDirectPlay::EnumGroups, IDirectPlay::EnumGroupPlayers, and IDirectPlay::EnumPlayers methods.

BOOL EnumPlayersCallback(
DPID dpID,
LPSTR lpFriendlyName,
LPSTR lpFormalName,
DWORD dwFlags,
LPVOID lpContext
);

Parameters

dpID

Player ID of the group being enumerated.

lpFriendlyName

Address for the zero-terminated string that contains the friendly name of the group.

lpFormalName

Address for the zero-terminated string that contains the formal name of the group.

dwFlags

Specifies the optional control flags.

DPENUMPLAYERS_GROUP

	Specifies that group names and player names should be enumerated.
DPENUMPLAYERS_LOCAL

	Specifies that only local player names need to be enumerated.
DPENUMPLAYERS_REMOTE

	Specifies that only remote player names need to be enumerated.
lpContext

Address for a caller-defined context.

Return Values

Returns TRUE to continue the enumeration or FALSE to stop it.


EnumSessionsCallback

Application-defined callback procedure for the IDirectPlay::EnumSessions method.

BOOL EnumSessionsCallback(
LPDPSESSIONDESC lpDPSGameDesc,
LPVOID lpContext,
LPDWORD lpdwTimeOut,
DWORD dwFlags
);

Parameters

lpDPSGameDesc

Address for a DPSESSIONDESC structure describing the enumerated session. This parameter will be set to NULL if the enumeration has timed out.

lpContext

Address for a caller-defined context.

lpdwTimeOut

Address for a doubleword containing the current time-out value. This can be reset if you feel that some sessions have yet to respond.

dwFlags

Specifies the optional control flag.

DPESC_TIMEDOUT

	The enumeration has timed out. Reset lpdwTimeOut and return TRUE to continue, or FALSE to stop the enumeration.
Return Values

Returns TRUE to continue the enumeration or FALSE to stop it.


IDirectPlay Interface


IDirectPlay Interface Method Groups

Applications use the methods of the IDirectPlay interface to create DirectPlay objects and work with system-level variables. This interface supports the following methods:

Group management	AddPlayerToGroup
	CreateGroup
	DeletePlayerFromGroup
	DestroyGroup
	EnumGroupPlayers
	EnumGroups
IUnknown	AddRef
	QueryInterface
	Release
Message management	GetMessageCount
	Receive
	Send
Player management	CreatePlayer
	DestroyPlayer
	EnableNewPlayers
	EnumPlayers
	GetPlayerCaps
	GetPlayerName
	SetPlayerName
Session management	Close
	EnumSessions
	GetCaps
	Open
	SaveSession
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the DirectPlay object without affecting the functionality of the original interface.


IDirectPlay::AddPlayerToGroup

Adds an existing player to an existing group.

HRESULT AddPlayerToGroup(
DPID pidGroup,
DPID pidPlayer
);

Parameters

pidGroup

ID of the group to be augmented.

pidPlayer

ID of the player to be added to the group.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_GENERIC	DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER
Remarks

A DPMSG_GROUPADD system message is automatically generated to inform other players that the specified player has been added. Groups cannot be added to other groups, but players can be members of multiple groups. The IDirectPlay::AddPlayerToGroup method will generate an error if the player is already a member of the group.

See Also

 IDirectPlay::CreateGroup, IDirectPlay::DeletePlayerFromGroup, DPMSG_GROUPADD


IDirectPlay::AddRef

Increases the reference count of the DirectPlay object by 1. This method is part of the IUnknown interface inherited by DirectPlay.

ULONG AddRef( );

Parameters

Return Values

Returns the new reference count of the object.

Remarks

When the DirectPlay object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirectPlay::Release method to decrease the reference count of the object by 1.

See Also

 IDirectPlay::Initialize, IDirectPlay::QueryInterface, IDirectPlay::Release


IDirectPlay::Close

Closes a previously opened communication channel. All locally created players will be destroyed, with corresponding DPMSG_DELETEPLAYER system messages sent to other session participants.

HRESULT Close( );

Parameters

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDOBJECT	DPERR_INVALIDPARAMS
See Also

 IDirectPlay::DestroyPlayer, DPMSG_DELETEPLAYER


IDirectPlay::CreateGroup

Creates a group of players for a session. A player ID representing the new group will be returned to the caller.

HRESULT CreateGroup(
LPDPID lppidID,
LPSTR lpGroupFriendlyName,
LPSTR lpGroupFormalName
);

Parameters

lppidID

Address for the DPID that will hold the DirectPlay player ID.

lpGroupFriendlyName

Address for the zero-terminated string that contains the friendly name of the group.

lpGroupFormalName

Address for the zero-terminated string that contains the formal name of the group.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_CANTADDPLAYER	DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS	DPERR_OUTOFMEMORY
Remarks

Messages sent to a player ID designating this group will be sent to all members of the group. The lpGroupFriendlyName and lpGroupFormalName parameters are provided for players' convenience only; they are not used internally and do not need to be unique. However, player IDs assigned by DirectPlay will always be unique within a session. Groups are recognized as players for the session player count; if you have a four player game with four existing players, calls to IDirectPlay::CreateGroup will fail. The state of the IDirectPlay::EnableNewPlayers method does not affect your application's ability to create groups.

Upon successful completion, this method sends a DPMSG_ADDPLAYER system message to all of the other players in the game announcing that a new group has been created.

See Also

 IDirectPlay::DestroyGroup, DPMSG_ADDPLAYER, IDirectPlay::EnableNewPlayers, IDirectPlay::EnumGroups, IDirectPlay::EnumGroupPlayers


IDirectPlay::CreatePlayer

Creates a player for the current game session.

HRESULT CreatePlayer(
LPDPID lppidID,
LPSTR lpPlayerFriendlyName,
LPSTR lpPlayerFormalName,
LPHANDLE lpEvent
);

Parameters

lppidID

Address for the DPID that will hold the DirectPlay player ID.

lpPlayerFriendlyName

Address for the zero-terminated string that contains the friendly name of the player.

lpPlayerFormalName

Address for the zero-terminated string that contains the formal name of the player.

lpEvent

Pointer to an event that will be triggered when a message addressed to this player is received.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_CANTADDPLAYER	DPERR_CANTCREATEPLAYER
DPERR_GENERIC	DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS	DPERR_NOCONNECTION
Remarks

A single process can have multiple players that communicate through a DirectPlay object with any number of other players running on multiple computers. The player ID returned to the caller will be used internally to direct the player's message traffic and manage the player. The lpPlayerFriendlyName and lpPlayerFormalName parameters are provided for players' convenience only; they are not used internally and need not be unique. Player IDs assigned by DirectPlay will always be unique within the session.

Upon successful completion, this method sends a DPMSG_ADDPLAYER system message to all of the other players in the game session announcing that a new player has joined the session. The newly created player can use the IDirectPlay::EnumPlayers method to find out who else is in the game session.

It is highly recommended that an application provide a non-NULL lpEvent and use this event for synchronization. After creation of a player, use WaitForSingleObject(*lpEvent, dwTimeout = 0) from Win32 to determine if a player has messages (the return value will be WAIT_TIMEOUT if there are not any waiting messages) or use a different time-out to wait for a message to come in. It is inefficient to loop on the IDirectPlay::Receive method.

See Also

 IDirectPlay::DestroyPlayer, DPMSG_ADDPLAYER, IDirectPlay::EnumPlayers, IDirectPlay::Receive


IDirectPlay::DeletePlayerFromGroup

Removes a player from a group.

HRESULT DeletePlayerFromGroup(
DPID pidGroup,
DPID pidPlayer
);

Parameters

pidGroup

Player ID of the group to be adjusted.

pidPlayer

ID of the player to be removed from the group.

Return Values

Returns DP_OK if successful, or one of the following error messages otherwise:

DPERR_INVALIDOBJECT	DPERR_INVALIDPLAYER
Remarks

A DPMSG_GROUPDELETE system message is automatically generated to inform the other players of this change.

See Also

 IDirectPlay::AddPlayerToGroup, DPMSG_GROUPDELETE


IDirectPlay::DestroyGroup

Deletes a group from the session. The player ID belonging to this group will not be reused during the current session.

HRESULT DestroyGroup(
DPID pidID
);

Parameters

pidID

Player ID of the group being removed from the game.

Return Values

Returns DP_OK if successful, or one of the following error messages otherwise:

DPERR_INVALIDOBJECT	DPERR_INVALIDPLAYER
Remarks

It is not necessary to empty a group before deleting it. The individual players belonging to the group are not destroyed; however, they will be notified by a DPMSG_DELETEPLAYER system message that the group has been removed from the session.

See Also

 IDirectPlay::CreateGroup, DPMSG_DELETEPLAYER


IDirectPlay::DestroyPlayer

Deletes a player from the game session, removes any pending messages destined for that player from the message queue, and removes the player from any groups to which it belonged. The player ID will not be reused during the current session.

HRESULT DestroyPlayer(
DPID pidID
);

Parameters

pidID

ID of the player that is being removed from the game.

Return Values

Returns DP_OK if successful, or one of the following error messages otherwise:

DPERR_INVALIDOBJECT	DPERR_INVALIDPLAYER
Remarks

Calling this method automatically sends a DPMSG_DELETEPLAYER system message to all other players, informing them that this player has been removed from the session.

See Also

 IDirectPlay::CreatePlayer, DPMSG_DELETEPLAYER


IDirectPlay::EnableNewPlayers

Enables or disables the creation of new players.

HRESULT EnableNewPlayers(
BOOL bEnable
);

Parameters

bEnable

If TRUE (the default condition for a session), new players can be created unless the session has reached its maximum capacity. If FALSE, any attempt to create a new player will return an error.

Return Values

Returns DP_OK if successful, or DPERR_INVALIDOBJECT otherwise.

Remarks

This method does not affect your ability to create groups. Typically, new players and groups can be added to a session until the session's player limit has been reached. This method can override this behavior if, for example, a session is in progress and new players are not desired. The IDirectPlay::EnumSessions method will not enumerate sessions where IDirectPlay::EnableNewPlayers has been set to FALSE unless the DPENUMSESSIONS_ALL flag is used.

See Also

 IDirectPlay::CreatePlayer, IDirectPlay::CreateGroup, IDirectPlay::EnumSessions


IDirectPlay::EnumGroupPlayers

Enumerates all of the players of a particular group existing in the current session.

HRESULT EnumGroupPlayers(
DPID pidGroupPID,
LPDPENUMPLAYERSCALLBACK lpEnumPlayersCallback,
LPVOID lpContext,
DWORD dwFlags
);

Parameters

pidGroupPID

Player ID of the group to be enumerated.

lpEnumPlayersCallback

Address for the EnumPlayersCallback function to be called for every player in the group.

lpContext

Address for a caller-defined context that is passed to each enumeration callback.

dwFlags

This parameter is not currently used and must be set to 0.

Return Values

Returns DP_OK if successful, or one of the following error messages otherwise:

DPERR_EXCEPTION	DPERR_INVALIDFLAGS
DPERR_INVALIDOBJECT	DPERR_INVALIDPLAYER
See Also

 IDirectPlay::CreatePlayer, IDirectPlay::DestroyPlayer


IDirectPlay::EnumGroups

Enumerates the groups in a session.

HRESULT EnumGroups(
DWORD dwSessionID,
LPDPENUMPLAYERSCALLBACK lpEnumPlayersCallback,
LPVOID lpContext,
DWORD dwFlags
);

Parameters

dwSessionID

Session of interest. Do not use unless the DPENUMPLAYERS_SESSION flag is specified.

lpEnumPlayersCallback

Address of the EnumPlayersCallback function to be called for every group in the session.

lpContext

Address for a caller-defined context that is passed to each enumeration callback.

dwFlags

Specifies the optional control flag.

DPENUMPLAYERS_SESSION

	Requests the name server for the specified session supply its group list.
Return Values

Returns DP_OK if successful, or one of the following error messages otherwise:

DPERR_INVALIDOBJECT	DPERR_INVALIDPARAMS
DPERR_UNSUPPORTED
Remarks

By default, this method will enumerate using the local player list for the current session. The DPENUMPLAYERS_SESSION flag can be used, along with a session ID, to request that a session's name server provide its list for enumeration. This method cannot be called from within an IDirectPlay::EnumSessions enumeration. Furthermore, use of the DPENUMPLAYERS_SESSION flag with this method must occur after the IDirectPlay::EnumSessions method has been called, and before any attempt to open or close has been made.

See Also

 IDirectPlay::CreatePlayer, IDirectPlay::DestroyPlayer


IDirectPlay::EnumPlayers

Enumerates the players in a session. Groups can also be included in the enumeration by using the DPENUMPLAYERS_GROUP flag.

HRESULT EnumPlayers(
DWORD dwSessionId,
LPDPENUMPLAYERSCALLBACK lpEnumPlayersCallback,
LPVOID lpContext,
DWORD dwFlags
);

Parameters

dwSessionID

Session of interest. Not used unless the DPENUMPLAYERS_SESSION flag is specified.

lpEnumPlayersCallback

Address for the EnumPlayersCallback function that will be called for every player in the session.

lpContext

Address for a caller-defined context that is passed to each enumeration callback.

dwFlags

Specifies the control flags.

DPENUMPLAYERS_GROUP

	Includes groups in the enumeration of players.
DPENUMPLAYERS_PREVIOUS

	Enumerates players previously stored in the registry. Not yet supported.
DPENUMPLAYERS_SESSION

	Requests that the name server supply its group list for the specified session.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_EXCEPTION	DPERR_GENERIC
DPERR_INVALIDOBJECT	DPERR_UNSUPPORTED
Remarks

This method is often called immediately after the DirectPlay object is opened, and will enumerate using the local player list for the current session by default. The IDirectPlay::EnumPlayers method may be called after the IDirectPlay::EnumSessions method in order to obtain a list of players in a particular session. IDirectPlay::EnumPlayers uses the DPENUMPLAYERS_SESSION flag and the session ID returned from the IDirectPlay::EnumSessions method to obtain this list. However, it cannot be called from within an IDirectPlay::EnumSessions enumeration. The use of the DPENUMPLAYERS_SESSION flag with this method must occur after the IDirectPlay::EnumSessions method has been called and before either the IDirectPlay::Close or the IDirectPlay::Open method has been called.

See Also

 IDirectPlay::CreatePlayer, IDirectPlay::DestroyPlayer, IDirectPlay::EnumSessions


IDirectPlay::EnumSessions

Enumerates the game sessions connected to this DirectPlay object.

HRESULT EnumSessions(
LPDPSESSIONDESC lpSDesc,
DWORD dwTimeout,
LPDPENUMSESSIONSCALLBACK lpEnumSessionsCallback,
LPVOID lpContext,
DWORD dwFlags
);

Parameters

lpSDesc

Address for a DPSESSIONDESC structure describing the sessions to be enumerated. If a list of all connected sessions, regardless of GUID, is desired, then the guidSession member in the DPSESSIONDESC structure should be set to NULL. If the DPENUMSESSIONS_AVAILABLE flag is going to be used with a password, then the szPassword member should be set accordingly.

dwTimeout

Total amount of time, in milliseconds, that DirectPlay will allow for the enumeration to complete (not the time between each enumeration).

lpEnumSessionsCallback

Address for the EnumSessionsCallback function to be called for each DirectPlay session responding.

lpContext

Address for a user-defined context that is passed to each enumeration callback.

dwFlags

Specifies the optional control flags.

DPENUMSESSIONS_AVAILABLE

	Enumerates all sessions with a matching password (if provided), opens player slots, and sets the IDirectPlay::EnableNewPlayers method to TRUE.
DPENUMSESSIONS_PREVIOUS

	Enumerates sessions previously stored in the registry.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDOBJECT	DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
Remarks

This method is usually called immediately after the DirectPlay object is instantiated; it cannot be called while a game is connected to a session or after a game has created a session. IDirectPlay::EnumSessions broadcasts an enumeration request and collects replies from the DirectPlay objects that respond. The amount of time DirectPlay spends listening for these replies is controlled by the dwTimeout parameter. When this time interval has expired, your callback will be notified using the DPESC_TIMEDOUT flag, and a NULL value will be passed for the lpDPSGameDesc parameter. At this point, you may choose to continue the enumeration by setting dwTimeOut to a new value and returning TRUE, or returning FALSE to cancel the enumeration.

See Also

 DPSESSIONDESC, IDirectPlay::EnableNewPlayers


IDirectPlay::GetCaps

Obtains the capabilities of this DirectPlay object.

HRESULT GetCaps(
LPDPCAPS lpDPCaps
);

Parameters

lpDPCaps

Address for a DPCAPS structure that will be filled with the capabilities of the DirectPlay object.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDOBJECT	DPERR_INVALIDPARAMS
See Also

 IDirectPlay::GetPlayerCaps, DPCAPS


IDirectPlay::GetMessageCount

Queries the name server for the number of messages queued for a specific local player.

HRESULT GetMessageCount(
DPID pidID,
LPDWORD lpdwCount
);

Parameters

pidID

Player ID for which the message count is requested. The player must be local.

lpdwCount

Address for a doubleword that will be set to the message count.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDOBJECT	DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
See Also

 IDirectPlay::Receive


IDirectPlay::GetPlayerCaps

Obtains the capabilities of the player's connection by querying the DirectPlay object.

HRESULT GetPlayerCaps(
DPID pidID,
LPDPCAPS lpDPPlayerCaps
);

Parameters

pidID

Player ID for which the communication capabilities are requested.

lpDPPlayerCaps

Address for a DPCAPS structure that will be filled with the communication capabilities of the specified player on this DirectPlay object.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDOBJECT	DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
Remarks

This method is needed because communicating with some players may be slower than communicating with others.

See Also

 IDirectPlay::GetCaps


IDirectPlay::GetPlayerName

Obtains the player's friendly and formal names from the name server.

HRESULT GetPlayerName(
DPID pidID,
LPSTR lpPlayerFriendlyName,
LPDWORD lpdwFriendlyNameLength,
LPSTR lpPlayerFormalName,
LPDWORD lpdwFormalNameLength
);

Parameters

pidID

Player ID for which the player names are being requested.

lpPlayerFriendlyName

Address for the buffer to be filled with the player's friendly name. Set to NULL if you are only looking for the size of the friendly name or are only looking for the formal name.

lpdwFriendlyNameLength

Address for a doubleword that either contains the length of the buffer pointed to by the lpPlayerFriendlyName field or will be filled with the length needed for the buffer. Set to NULL if you are only interested in the formal name.

lpPlayerFormalName

Address for the buffer to be filled with the player's formal name. Set to NULL if you are only looking for the size of the formal name or are only looking for the friendly name.

lpdwFormalNameLength

Address for a doubleword that either contains the length of the buffer pointed to by the lpPlayerFormalName parameter or will be filled with the length needed for the buffer. Set to NULL if you are only interested in the friendly name.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_BUFFERTOOSMALL	DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS	DPERR_INVALIDPLAYER
Remarks

If just one of the names is required, you can set the pair of pointers to the other name to NULL. If the length of the names needs to be determined, the pointers to the lengths must be valid; however, they can point to zeros or you can set the pointers to the friendly and formal names to NULL.

If the supplied buffer is not long enough to hold one of the names, an error code will be returned and the corresponding buffer length will be adjusted to be the size of the buffer needed.

See Also

 IDirectPlay::SetPlayerName


IDirectPlay::Initialize

Provided to comply with the Common Object Model (COM) protocol.

HRESULT Initialize(
LPGUID lpGUID
);

Parameters

lpGUID

Address for the GUID used as the interface identifier.

Return Values

Returns DPERR_ALREADYINITIALIZED.

Remarks

Since the DirectPlay object is initialized when it is created, calling this method will always result in the DPERR_ALREADYINITIALIZED return value.

See Also

 IDirectPlay::AddRef, IDirectPlay::QueryInterface


IDirectPlay::Open

Establishes the communication link between DirectPlay and a service provider.

HRESULT Open(
LPDPSESSIONDESC lpSDesc
);

Parameters

lpSDesc

Address for the DPSESSIONDESC structure describing the session to be connected to or created.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_ACTIVEPLAYERS	DPERR_GENERIC
DPERR_INVALIDOBJECT	DPERR_INVALIDPARAMS
DPERR_UNAVAILABLE	DPERR_UNSUPPORTED
DPERR_USERCANCEL
Remarks

In a modem environment, calling this method is equivalent to actually dialing the phone. This prompts the required user interface to configure the communications protocol that will be invoked with the DirectPlay object. In the case of the serial modem service provider supplied with DirectPlay, the user is prompted for dialing information. If the user cancels the dialing process, IDirectPlay::Open will return a DPERR_USERCANCEL error. This method will also return an error if any local players exist when it is called.

See Also

 IDirectPlay::Close, DPSESSIONDESC


IDirectPlay::QueryInterface

Determines if the DirectPlay object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by DirectPlay.

HRESULT QueryInterface(
REFIID riid,
LPVOID * ppvObj
);

Parameters

riid

Reference identifier of the interface being requested.

ppvObj

Address for a pointer to be filled with the interface pointer if the query is successful.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDOBJECT	DPERR_INVALIDPARAMS
Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirectPlay::QueryInterface method allows DirectPlay objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.

See Also

 IDirectPlay::AddRef, IDirectPlay::Release


IDirectPlay::Receive

Retrieves a message from the message queue.

HRESULT Receive(
LPDPID lppidFrom,
LPDPID lppidTo,
DWORD dwFlags,
LPVOID lpvBuffer,
LPDWORD lpdwSize
);

Parameters

lppidFrom

Address for a DPID structure to be filled with the sender's player ID.

lppidTo

Address for a DPID structure to be filled with the receiver's player ID.

dwFlags

Specifies the optional control flags.

DPRECEIVE_ALL

	Returns the first available message. This is the default.
DPRECEIVE_FROMPLAYER

	Returns the first message from the player ID that the lppidFrom parameter points to.
DPRECEIVE_PEEK

	Returns a message as specified by the other flags, but does not remove it from the message queue.
DPRECEIVE_TOPLAYER

	Returns the first message intended for the player ID that the lppidTo parameter points to. System messages are addressed to player ID 0.
lpvBuffer

Address for the message buffer. If this buffer is not long enough to hold the message, an error will be returned and lpdwSize will be filled with the size of message buffer needed.

lpdwSize

Address for the doubleword that specifies the length of the message buffer.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_BUFFERTOOSMALL	DPERR_GENERIC
DPERR_INVALIDOBJECT	DPERR_INVALIDPARAMS
DPERR_NOMESSAGES
Remarks

Any message received from player ID 0 is a system message from the name server. A message sent to the name server to broadcast to all players still appears to be from the sender. Both the DPRECEIVE_TOPLAYER and DPRECEIVE_FROMPLAYER flags can be specified, in which case IDirectPlay::Receive will return whichever message is encountered first.

See Also

 IDirectPlay::Send


IDirectPlay::Release

Decreases the reference count of the DirectPlay object by 1. This method is part of the IUnknown interface inherited by DirectPlay.

ULONG Release( );

Parameters

Return Values

Returns the new reference count of the object.

Remarks

The DirectPlay object deallocates itself when its reference count reaches 0. Use the IDirectPlay::AddRef method to increase the reference count of the object by 1.

See Also

 IDirectPlay::AddRef, IDirectPlay::QueryInterface


IDirectPlay::SaveSession

Saves the current session in the registry.

HRESULT SaveSession( );

Parameters

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_GENERIC	DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS	DPERR_OUTOFMEMORY
DPERR_UNSUPPORTED
Remarks

The functionality of this method is dependent on the service provider, which will save enough transport-specific information in the registry to restore the connection. IDirectPlay::SaveSession is unsupported in the TCP and IPX service providers. In the serial modem service provider, IDirectPlay::SaveSession functions only for the client session (the one that dials), in which case it will save the phone number in the registry for future use.

See Also

 IDirectPlay::EnumSessions


IDirectPlay::Send

Sends messages to other players, to other groups of players, or to all players in the session.

HRESULT Send(
DPID pidFrom,
DPID pidTo,
DWORD dwFlags,
LPVOID lpvBuffer,
DWORD dwBuffSize
);

Parameters

pidFrom

ID of the sending player.

pidTo

ID of the receiving player.

dwFlags

Indicates how the message should be sent. Not all options may be supported by a particular service provider.

DPSEND_GUARANTEE

	Sends the message using a reliable method. Retries until the message is received or until the DirectPlay time-out occurs.
DPSEND_HIGHPRIORITY

	Sends the message as a HIGHPRIORITY message.
DPSEND_TRYONCE

	Sends the message without error detection and without retry options enabled.
lpvBuffer

Address for the message being sent.

dwBuffSize

Length of the message being sent.

Return Values

Returns DP_OK if successful, the number of messages waiting for transmission in DirectPlay's internal queue, or one of the following error values:

DPERR_BUSY	DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER	DPERR_SENDTOOBIG
Remarks

To send a message to another player, specify the appropriate player ID. To send a message to a group of players, send the message to the player ID assigned to the previously created group. To send messages to the entire session, specify the player ID 0, which always represents the name server. IDirectPlay::Send will either return one of the values listed above or the number of messages currently queued for transmission. If the internal queue fills to the limit specified by the dwMaxQueueSize member of the DPCAPS structure, an error will be generated and the message will not be added to the queue. The IDirectPlay::Send method cannot be used inside an IDirectDrawSurface::Lock / IDirectDrawSurface::Unlock or IDirectDrawSurface::GetDC / IDirectDrawSurface::ReleaseDC method pair.

See Also

 IDirectPlay::Receive


IDirectPlay::SetPlayerName

Changes the player's friendly and formal names.

HRESULT SetPlayerName(
DPID pidID,
LPSTR lpPlayerFriendlyName,
LPSTR lpPlayerFormalName
);

Parameters

pidID

ID for which the player name is being requested.

lpPlayerFriendlyName

Address to a string containing the player's new friendly name.

lpPlayerFormalName

Address to a string containing the player's new formal name.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDPLAYER	DPERR_INVALIDOBJECT
Remarks

This method cannot be used to change the names of a group.

See Also

 IDirectPlay::GetPlayerName


Structures

DirectPlay structures must have their size fields, where present, properly set before calling DirectPlay functions or an error will result.

Data structures	DPCAPS
	DPSESSIONDESC
Message structures	DPMSG_ADDPLAYER
	DPMSG_DELETEPLAYER
	DPMSG_GENERIC
	DPMSG_GROUPADD
	DPMSG_GROUPDELETE


DPCAPS

Contains the capabilities of a DirectPlay object after a call to the IDirectPlay::GetCaps method. This structure is read-only.

typedef struct {

    DWORD    dwSize;

    DWORD    dwFlags;

    DWORD    dwMaxBufferSize;

    DWORD    dwMaxQueueSize;

    DWORD    dwMaxPlayers;

    DWORD    dwHundredBaud;

    DWORD    dwLatency;

} DPCAPS;

Members

dwSize

Size of this structure, in bytes. Must be initialized before the structure is used.

dwFlags

Specifies the optional control flags.

DPCAPS_GUARANTEED

	Supports verification of received messages. Retransmits the message, if necessary.
DPCAPS_NAMESERVER

	The computer represented by the calling application is the name server.
DPCAPS_NAMESERVICE

	A name server is supported.
dwMaxBufferSize

Maximum buffer size for this DirectPlay object.

dwMaxQueueSize

Maximum queue size for this DirectPlay object.

dwMaxPlayers

Maximum number of players supported in a session.

dwHundredBaud

Baud rate specified in hundredths. For example, 2400 baud is represented by the value 24.

dwLatency

Latency estimate per service provider, in milliseconds. If this value is 0, DirectPlay cannot provide an estimate. Accuracy for some service providers rests on application-to-application testing, taking into consideration the average message size.


DPSESSIONDESC

Contains a description of the capabilities of a DirectPlay session.

typedef struct {

    DWORD    dwSize;

    GUID     guidSession;

    DWORD    dwSession;

    DWORD    dwMaxPlayers;

    DWORD    dwCurrentPlayers;

    DWORD    dwFlags;

    char     szSessionName[DPSESSIONNAMELEN];

    char     szUserField[DPUSERRESERVED];

    DWORD    dwReserved1;

    char     szPassword[DPPASSWORDLEN];

    DWORD    dwReserved2;

    DWORD    dwUser1;

    DWORD    dwUser2;

    DWORD    dwUser3;

    DWORD    dwUser4;

} DPSESSIONDESC;

typedef DPSESSIONDESC FAR *LPDPSESSIONDESC;

Members

dwSize

Size of this structure, in bytes. Must be initialized before the structure is used.

guidSession

Globally unique identifier (GUID) for the game. It identifies the game so that DirectPlay connects only to other machines playing the same game.

dwSession

Session identifier of the session that has been created or opened.

dwMaxPlayers

Maximum number of players and groups allowed in this session. This member is ignored if the application is not creating a new session.

dwCurrentPlayers

Current players and groups in the session.

dwFlags

Specifies one of the control flags:

DPOPEN_CREATESESSION

	Creates a new session described by the DPSESSIONDESC structure.
DPOPEN_OPENSESSION

	Opens the session identified by the dwSession member.
DPENUMSESSIONS_ALL

	Enumerates all active sessions connected to this DirectPlay object, regardless of their occupancy, passwords, or the IDirectPlay::EnableNewPlayers method's status.
szSessionName

String containing the name of the session.

szUserField

String containing user data.

dwReserved1

Reserved for future use.

szPassword

String containing the optional password that, once set up, is required to join this session.

dwReserved2

Reserved for future use.

dwUser1, #dwUser2, #dwUser3, #dwUser4

User-specific data for the game or session.


System Messages

Messages returned by the IDirectPlay::Receive method from player ID 0 are system messages. All system messages begin with a doubleword dwType. You can cast the buffer returned by the IDirectPlay::Receive method to a generic message (DPMSG_GENERIC) and switch on the dwType element, which will have a value equal to one of the DPSYS_* messages (DPSYS_ADDPLAYER, and so on).

Your application should be prepared to handle the following system messages:

Value of dwType	Message structure
DPSYS_ADDPLAYER	DPMSG_ADDPLAYER
DPSYS_ADDPLAYERTOGROUP	DPMSG_GROUPADD
DPSYS_DELETEGROUP	DPMSG_DELETEPLAYER
DPSYS_DELETEPLAYER	DPMSG_DELETEPLAYER
DPSYS_DELETEPLAYERFROMGRP	DPMSG_GROUPDELETE
DPSYS_SESSIONLOST	DPMSG_GENERIC


DPMSG_ADDPLAYER

Contains information for the DPSYS_ADDPLAYER system message. The system sends this message when players and groups are added to a session.

typedef struct{

    DWORD    dwType;

    DWORD    dwPlayerType;

    DPID     dpId;

    char     szLongName[DPLONGNAMELEN];

    char     szShortName[DPSHORTNAMELEN];

    DWORD    dwCurrentPlayers;

} DPMSG_ADDPLAYER;

Members

dwType

Identifier for the message.

dwPlayerType

Indicates whether a player or a group was added. TRUE indicates a player was added; FALSE indicates a group was added.

dpId

ID for a player or group.

szLongName

Formal name for player or group.

szShortName

Friendly name for player or group.

dwCurrentPlayers

Number of players in the session.


DPMSG_DELETEPLAYER

Contains information for the DPSYS_DELETEPLAYER and DPSYS_DELETEGROUP system messages. The system sends these messages when players and groups are deleted from a session.

typedef struct{

    DWORD    dwType;

    DPID     dpId;

} DPMSG_DELETEPLAYER;

Members

dwType

Identifier for the message.

dpId

ID of a player or group that has been deleted.


DPMSG_GENERIC

This structure is provided for message processing.

typedef struct{

    DWORD    dwType;

} DPMSG_GENERIC;

Members

dwType

Identifier for the message.

Remarks

Your application can first cast the unknown message to the DPMSG_GENERIC type, then perform further processing based on the value of dwType. One other system message, DPSYS_SESSIONLOST, also uses this structure.


DPMSG_GROUPADD

Contains information for the DPSYS_ADDPLAYERTOGROUP and DPSYS_DELETEPLAYERFROMGRP system messages. The system sends these messages when players are added to and deleted from a group, respectively.

typedef struct{

    DWORD    dwType;

    DPID     dpIdGroup;

    DPID     dpIdPlayer;

} DPMSG_GROUPADD;

Members

dwType

Identifier for the message.

dpIdGroup

ID of the group to which the player was added or deleted.

dpIdPlayer

ID of the player that was added to or deleted from the specified group.


DPMSG_GROUPDELETE

Contains information for the DPSYS_DELETEPLAYERFROMGRP message. For a description of the structure members, see the DPMSG_GROUPADD structure.

typedef DPMSG_GROUPADD DMSG_GROUPDELETE;


Return Values

Errors are represented by negative values and cannot be combined. This table lists the values that can be returned by all IDirectPlay methods. For a list of the error codes each method is capable of returning, see the individual method descriptions.

DP_OK

	The request completed successfully.
DPERR_ACCESSDENIED

	The session is full or an incorrect password was supplied.
DPERR_ACTIVEPLAYERS

	The requested operation cannot be performed because there are existing active players.
DPERR_ALREADYINITIALIZED

	This object is already initialized.
DPERR_BUFFERTOOSMALL

	The supplied buffer is not large enough to contain the requested data.
DPERR_BUSY

	The DirectPlay message queue is full.
DPERR_CANTADDPLAYER

	The player cannot be added to the session.
DPERR_CANTCREATEPLAYER

	A new player cannot be created.
DPERR_CAPSNOTAVAILABLEYET

	The capabilities of the DirectPlay object have not been determined yet. This error will occur if the DirectPlay object is implemented on a connectivity solution that requires polling to determine available bandwidth and latency.
DPERR_EXCEPTION

	An exception occurred when processing the request.
DPERR_GENERIC

	An undefined error condition occurred.
DPERR_INVALIDFLAGS

	The flags passed to this function are invalid.
DPERR_INVALIDOBJECT

	The DirectPlay object pointer is invalid.
DPERR_INVALIDPARAMS

	One or more of the parameters passed to the function are invalid.
DPERR_INVALIDPLAYER

	The player ID is not recognized as a valid player ID for this game session.
DPERR_NOCAPS

	The communication link underneath DirectPlay is not capable of this function.
DPERR_NOCONNECTION

	No communication link was established.
DPERR_NOMESSAGES

	There are no messages to be received.
DPERR_NONAMESERVERFOUND

	No name server could be found or created. A name server must exist in order to create a player.
DPERR_NOPLAYERS

	There are no active players in the session.
DPERR_NOSESSIONS

	There are no existing sessions for this game.
DPERR_OUTOFMEMORY

	There is insufficient memory to perform the requested operation.
DPERR_SENDTOOBIG

	The message buffer passed to the IDirectPlay::Send method is larger than allowed.
DPERR_TIMEOUT

	The operation could not be completed in the specified time.
DPERR_UNAVAILABLE

	The requested service provider or session is not available.
DPERR_UNSUPPORTED

	The function is not available in this implementation.
DPERR_USERCANCEL

	The user canceled the connection process during a call to the IDirectPlay::Open method.


Direct3D


Direct3D Overview


Microsoft's 3D-Graphics Solutions

The Microsoft family of advanced 3D-graphics solutions includes the Direct3D™ and OpenGL® application programming interfaces (APIs).

The relationship between the Windows graphics systems, applications written with the Win32® API, the rest of the Windows system, and the hardware is shown in the following illustration.


Direct3D

Direct3D is Microsoft's high-speed 3D software solution. It gives you the ability to create high-performance, real-time 3D applications for typical desktop computers. The system was designed for speed and requires little memory.

Direct3D is implemented in two distinctly different modes: Retained Mode, a high-level API in which the application retains the graphics data, and Immediate Mode, a low-level API in which the application explicitly streams the data out to an execute buffer.

Retained Mode

Direct3D Retained Mode API is designed for manipulating 3D objects and managing 3D scenes. Retained Mode makes it easy to add 3D capabilities to existing Windows-based applications or to create new 3D applications. Its built-in geometry engine supports advanced capabilities like key frame animation and frees you from creating object databases and managing the internal structures of objects. In other words, after using a single call to load a predefined 3D object, the application can use simple methods from the API to manipulate the object in the scene in real-time without having to work explicitly with any of the internal geometry.

Retained Mode is built on top of Immediate Mode and is tightly coupled with the DirectDraw™ application programming interface (API). Microsoft will incorporate Retained Mode into a future version of Windows. For more information, see DirectDraw and Introduction to Direct3D Retained-Mode Objects.

Immediate Mode

Direct3D Immediate Mode is Microsoft's low-level 3D API. It allows you to port games and other high-performance multimedia applications to the Windows operating system.

Immediate Mode is a thin layer above real-time 3D accelerator hardware that gives you access to the features of that hardware. It also offers optimal software rendering for some hardware features that are not present. Immediate Mode gives you the flexibility to exploit your own rendering and scene management technologies. It is a device-independent way for applications to communicate with accelerator hardware at a low level, enabling maximum performance.

Unlike Retained Mode, Immediate Mode does not provide a geometry engine; applications that use Immediate Mode must provide their own object and scene management. Therefore, you should be knowledgeable in 3D graphics programming to use Immediate Mode effectively.

Direct3D is based on the OLE Component Object Model (COM), and is tightly integrated with DirectDraw. Microsoft will incorporate Direct3D into a future version of Windows. For more information, see Introduction to Direct3D Immediate-Mode Objects.

Hardware Abstraction and Emulation

The Direct3D API (like the rest of the DirectX API) is built on top of a hardware-abstraction layer (HAL), which insulates you from device-specific dependencies present in the hardware. A companion piece to the Direct3D HAL is the hardware-emulation layer (HEL). The Direct3D HEL provides software-based emulation of features that are not present in hardware. The combination of these hardware abstraction and emulation layers ensures that the services of the API are always available to you.

The Direct3D HAL is tightly integrated with the DirectDraw HAL and the GDI display driver, giving hardware manufacturers a single, consistent interface to Microsoft graphics APIs, and a long-term, unified driver model for accelerated 3D. Hardware manufacturers need to write only a single driver to accelerate Direct3D, DirectDraw, GDI, and OpenGL. Hardware can accelerate all or part of the 3D graphics rendering pipeline, including geometry transformations, 3D clipping and lighting, and rasterization. The Direct3D HAL has been designed to accommodate future graphics accelerators in addition to those available today.


DirectDraw

DirectDraw provides the fastest way to display graphics on-screen. It is the Windows composition engine for 2D graphics, 3D graphics, and video. DirectDraw composes and moves images very quickly and can employ page flipping to enable smooth animation. This combination of capabilities allows you to create high-speed games and multimedia applications and to port existing titles to Windows quickly and easily. DirectDraw is also the composition engine for all of Microsoft's newest graphics subsystems. You can use it to quickly integrate images generated by Windows GDI, Direct3D, ActiveMovie™, and OpenGL.

DirectDraw is a thin layer above the display hardware that enables you to easily take advantage of the powerful composition abilities of graphics accelerators designed for Windows, including high-speed blitting, interpolated stretching, and overlays. It also supports color space conversion, allowing accelerated video playback. Like Direct3D, DirectDraw is a device-independent way for applications to communicate with hardware. Under MS-DOS, you had to optimize code for each target device. With DirectDraw, however, you can attain high performance consistently across all of the hardware that accelerates DirectDraw.

DirectDraw is a COM-based API. Microsoft will incorporate DirectDraw into a future version of Windows. For more information, see About DirectDraw.


OpenGL

OpenGL is a precise 3D technology used for high-end CAD/CAM, modeling and animation, simulations, scientific visualization, and other exacting 3D-image rendering. It is provided with Windows NT and is available to you for use with Windows 95. Putting OpenGL on Windows 95 means that you can run Win32 OpenGL applications on any Win32 workstation. OpenGL currently takes advantage of any high-end hardware that has OpenGL functionality, using a client driver model designed for OpenGL. A future release of OpenGL will be able to take advantage of lower-priced 3D hardware (provided that it supports the precision conformance requirements of OpenGL) through the Direct3D API, providing a hardware solution that complements Direct3D.


Direct3D Architecture


The Direct3D Vision

Direct3D is designed to enable world-class game and interactive 3D graphics on a computer running Windows. Its mission is to provide device-dependent access to 3D video-display hardware in a device-independent manner. The application does not need to implement the specific calling procedures required to draw texture-mapped, perspective-corrected, or alpha-blended 3D primitives on a particular piece of hardware. Simply put, Direct3D is a drawing interface for 3D hardware. It integrates tightly with DirectDraw as its buffer-management system, allowing DirectDraw surfaces to be used both as 3D rendering targets and as source texture maps. This allows for hardware-decompressed motion-video mapping, hardware 3D rendering in 2D overlay planes, or even sprites, for example.

Direct3D is designed to set a standard for hardware acceleration—including geometry transformations, 3D clipping, and lighting. Direct3D provides a highly optimized, software-only implementation of the full 3D rendering pipeline. Any part or all of this pipeline can be replaced at any stage by accelerating hardware. This allows you to write applications now that will be able to use better hardware acceleration as new hardware is developed.

Direct3D is tightly integrated with DirectDraw. The DirectDraw driver COM interfaces and the Direct3D driver COM interface both allow you to communicate with the same underlying object. For more information about the integration of Direct3D and DirectDraw, see Direct3D Integration with DirectDraw. For information about DirectDraw's support the 3D surfaces, see Support for 3D Surfaces.

Much of the information in this section describes implementation details of Direct3D that do not directly apply to those of you who use the Retained-Mode interface. If you use the Immediate-Mode interface, however, you'll need a good understanding of these implementation details. Those of you who use the Retained-Mode interface will also benefit from a good theoretical grounding in the system architecture.


Rendering Engine

The Direct3D architecture is based on a virtual 3D rendering engine composed of three separate modules:

•	The transformation module handles the transformation of geometry by using three 4-by-4 matrices, one each for the view, world, and projection transformations. This module supports arbitrary projection matrices, allowing perspective and orthographic views.

•	The lighting module calculates lighting information for geometry, supporting ambient, directional, point, and spotlight light sources.

•	The rasterization module uses the output of the geometry and lighting modules to render the scene. The scene description is in an extensible display-list–based format that can support both 2D and 3D primitives.

The following illustration shows how the three modules of the rendering engine interact with the rest of the Direct3D architecture.

The rasterization module interacts with DirectDraw as shown in the following illustration. Direct3D makes use of DirectDraw surfaces as render targets and texture sources.

Each of these modules can be hardware-accelerated or emulated in software. Direct3D can be queried to verify which components are currently running under emulation. When used together, these modules form the Direct3D rendering pipeline.

All three modules are dynamically loadable and can be changed on the fly between rendered frames. This allows new modules to be swapped in for either hardware acceleration or different rendering effects. Direct3D comes with one transformation module but a choice of two lighting and two rasterization modules. This provides greater flexibility in lighting and rendering, allowing the possibility, for example, of rendering more realistic scenes by simply switching the lighting module. An independent vendor could even provide its own special-effects-rasterization modules.


Execute Buffers

Each of the three modules in the rendering engine maintains state information that is set by using the Direct3D API. After all the state information is set, the rendering engine is ready to process display lists, which are known as execute buffers. Your application works explicitly with execute buffers only in Immediate Mode; Retained-Mode applications work at a higher level than this.

Execute buffers are fully self-contained, independent packets of information. They contain a vertex list followed by an instruction stream. The instruction stream consists of operation codes, or opcodes, and the data that is operated on by those opcodes. Direct3D's opcodes are listed in the D3DOPCODE enumerated type. The D3DINSTRUCTION structure describes instructions in an execute buffer; it contains an opcode, the size of each instruction data unit, and a count of the relevant data units that follow.

The following illustration shows the format of execute buffers.

The instructions define how the vertex list should be lit and rendered. One of the most common instructions is a triangle list (D3DOP_TRIANGLE), which is simply a list of triangle primitives that reference vertices in the vertex list. Because all the primitives in the instruction stream reference vertices in the vertex list only, it is easy for the transformation module to reject a whole buffer of primitives if its vertices are outside the viewing frustum.

The hardware determines the size of the execute buffer. You can retrieve this size by calling the IDirect3DDevice::GetCaps method and examining the dwMaxBufferSize member of the D3DDEVICEDESC structure. Typically, 64K is a good size for execute buffers when you are using a software driver because this size makes the best use of the secondary cache. When your application can take advantage of hardware acceleration, however, it should use smaller execute buffers to take advantage of the primary cache.

You can disable the lighting module or both the lighting and transformation modules when you are working with execute buffers. This changes the way the vertex list is interpreted, allowing the user to supply pretransformed or prelit vertices only for the rasterization phase of the rendering pipeline. Note that only one vertex type can be used in each execute buffer.

In addition to execute buffers and state changes, Direct3D accepts a third calling mechanism. Either of the transformation or lighting modules can be called directly. This functionality is useful when rasterization is not required, such as when using the transformation module for bounding-box tests.


Transformation Module

The transformation module has four state registers that the user can modify: the viewport, the viewing matrix, the world matrix, and the projection matrix. Whenever one of these parameters is modified, they are combined to form a new transformation matrix, which is also maintained by the transformation module. The transformation matrix defines the rotation and projection of a set of 3D vertices from their model coordinates to the 2D window.

Although the application can set the transformation matrix directly, it is not recommended. A number of matrix classifications take place in the combination phase that allow optimized transformation math to be used, but this is precluded if the application specifies the matrix directly.

A display list supports a number of different vertex types. For rasterization-only hardware, the application should use the D3DTLVERTEX structure, which is a transformed and lit vertex—that is, it contains screen coordinates and colors. If the hardware handles the transformations, the application should use a D3DLVERTEX structure. This structure contains only data and a color that would be filled by software lighting. The D3DHVERTEX structure defines a homogeneous vertex used when the application is supplying model-coordinate data that needs clipping. If the hardware supports lighting, the application simply uses a D3DVERTEX structure, because this type of vertex can be transformed and lit during rendering. The software emulation driver supports all of these vertex types.

There are two types of methods for the transformation module: those that set the state of the transformation module and those that use the transformation module directly to act on a set of vertices. Calling the transformation module directly is useful for testing bounding volumes or for transforming a set of vectors. These operations transform geometry by using the current transformation matrices. They can also perform clipping tests against the current viewing volume. The structure used for all the direct transformation functions is D3DTRANSFORMDATA.


Lighting Module

The lighting module maintains a stack of current lights, the ambient light level, and a material.

When using the lighting module directly, each element of input data to the lighting module (the D3DLIGHTINGELEMENT structure) contains a direction vector and a position (for positional light sources such as point lights and spotlights).

Two lighting models—monochromatic and RGB—are supported. The color fields are always placed after the D3DLIGHTINGELEMENT structure in the D3DLIGHTDATA structure.

The monochromatic lighting model (sometimes also called the "ramp" lighting model) uses the gray component of each light to calculate a single shade value. The RGB lighting model produces more realistic results, using the full color content of light sources and materials to calculate the lit colors.

For materials with no specular component, the shade is the diffuse component of the light intensity and ranges from 0 (ambient light only) to 1 (full intensity light). For materials with a specular component, the shade combines both the specular and diffuse components of the light according to the following equation:

This shade value is designed to work with precalculated ramps of colors (either in the hardware's color-lookup table or in lookup tables implemented in software). These precalculated ramps are divided into two sections. A ramp of the material's diffuse color takes up the first three-quarters of the precalculated ramp; this ranges from the ambient color to the maximum diffuse color. A ramp ranging from the maximum diffuse color to the maximum specular color of the material takes up the last quarter of the precalculated ramp. For rendering, the shade value should be scaled by the size of the ramp and used as an index to look up the color required.

A packed RGB color is defined as the following:

#define RGB_MAKE (red, green, blue) \

 ((red)   << 16) | \

 ((green) << 8)  | \

 (blue))

A packed RGBA color is defined as the following:

#define RGBA_MAKE(red, green, blue, alpha) \

(((alpha) << 24) | \

 ((red)   << 16) | \

 ((green) << 8)  | \

 (blue))

Colors in Direct3D are defined as follows:

typedef unsigned long D3DCOLOR;

The type of the light must be one of the members of the D3DLIGHTTYPE enumerated type: D3DLIGHT_DIRECTIONAL, D3DLIGHT_POINT, D3DLIGHT_PARALLELPOINT, D3DLIGHT_SPOT, or D3DLIGHT_GLSPOT. This enumerated type is part of the D3DLIGHT structure. Another member of this structure is a D3DCOLORVALUE structure, which specifies the color of the light. The values given for the red, green, and blue light components typically range from 0 to 1. The value for the ramp lighting model is based on the following equation:

Each of the color values can fall outside of the 0 to 1 range, allowing the use of advanced lighting effects (such as dark lights). The direction vectors in the D3DLIGHT structure describe the direction from the model to the light source. This vector should be normalized for directional lights. All vectors should be given in world coordinates; these vectors are transformed into model coordinates by using the current world matrix, allowing the efficient lighting of models without the need to transform the vectors into world coordinates. For point lights and spotlights, the range parameter gives the effective range of the light source. Vertices that are outside this range will not be affected by the light. The intensity of the light is modified by a quadratic attenuation factor, where d is the distance from the vertex being lit to the light, as shown in the following equation:

The remaining members of the D3DLIGHT structure (dvTheta and dvPhi) are used for spotlights to define the angles of the umbra and penumbra cones, respectively. The falloff factor (dvFalloff) is applied between the umbra and penumbra cones of the spotlight.

There are two types of methods for the lighting module, those that set the state of the lighting module, and those that use the lighting module directly to act on a set of points.

Like the transformation module, the lighting module can also be called directly. The D3DLIGHTDATA structure is used for all the direct lighting functions.


Rasterization Module

The rasterization module handles only execute calls—the calls that render execute buffers. Instructions in the execute buffer set the state for the rasterization module.

Execute buffers are processed first by the transformation module. This module runs through the vertex list, generating transformed vertices by using the state information set up for the transformation module. Clipping can be enabled, generating additional clipping information by using the viewport parameters to clip against. The whole buffer can be rejected here if none of the vertices is in view. Then, the vertices are processed by the lighting module, which adds color to them according to the lighting instructions in the execute buffer. Finally, the rasterization module parses the instruction stream, rendering primitives by using the generated vertex information.

When an application calls the IDirect3DDevice::Execute method, the system determines whether the vertex list needs to be transformed or transformed and lit. After these operations have been completed, the instruction list is parsed and rendered.

The screen coordinates range from (0, 0) for the top left of the device (screen or window) to (width – 1, height – 1) for the bottom right of the device. The depth values range from 0 at the front of the viewing frustum to 1 at the back. Rasterization is performed so that if two triangles that share two vertices are rendered, no pixel along the line joining the shared vertices is rendered twice. The rasterizer culls backfacing triangles by determining the winding order of the three vertices of the triangle. Only those triangles whose vertices are traversed in a clockwise orientation are rendered.


Colors and Fog

Colors in Direct3D are properties of vertices, textures, materials, faces, lights, and, of course, palettes.

Palette Entries

Your application can use the IDirect3DRM::CreateDeviceFromSurface method to draw to a DirectDraw surface. You must be sure to attach a DirectDraw palette to the primary DirectDraw surface to avoid unexpected colors in Direct3D applications. The Direct3D sample code in this SDK attaches the palette to the primary surface whenever the window receives a WM_ACTIVATE message. If you need to track the changes that Direct3D makes to the palette of an 8-bit DirectDraw surface, you can call the IDirectDrawPalette::GetEntries method.

Your application can use three flags to specify how it will share palette entries with the rest of the system:

D3DPAL_FREE	The renderer may use this entry freely.
D3DPAL_READONLY	The renderer may not set this entry.
D3DPAL_RESERVED	The renderer may not use this entry.
These flags can be specified in the peFlags member of the standard Win32 PALETTEENTRY structure. (You can also use the members of the D3DRMPALETTEFLAGS enumerated type in the D3DRMPALETTEENTRY structure to specify how to share palette entries.) Your application can use these flags when using either the RGB or monochromatic (ramp) renderer. Although you could supply a read-only palette to the RGB renderer, you will get better results with the ramp renderer.

Fog

Fog is simply the alpha part of the color specified in the specular member of the D3DTLVERTEX structure. Another way of thinking about this is that specular color is really RGBF color, where "F" is "fog."

In monochromatic lighting mode, fog works properly only when the fog color is black or when there is no lighting, in which case any fog color has the same effect.

There are three fog modes: linear, exponential, and exponential squared. Only the linear fog mode is supported for DirectX 2.

When you use linear fog, you specify a start and end point for the fog effect. The fog effect begins at the specified starting point and increases linearly until it reaches its maximum density at the specified end point.

The exponential fog modes begin with a barely visible fog effect and increase to the maximum density along an exponential curve. The following is the formula for the exponential fog mode:

In the exponential squared fog mode, the fog effect increases more quickly than in the exponential fog mode. The following is the formula for the exponential squared fog mode:

In these formulas, e is the base of the natural logarithms; its value is approximately 2.71828. Note that fog can be considered as a measure of visibility—the lower the fog value, the less visible an object is.

For example, if an application used the exponential fog mode and a fog density of 0.5, the fog value at a distance from the camera of 0.8 would be 0.6703, as shown in the following example:


States and State Overrides

Direct3D interprets the data in execute buffers according to the current state settings. Applications set up these states before instructing the system to render data. The D3DSTATE structure contains three enumerated types that expose this architecture: D3DTRANSFORMSTATETYPE, which sets the state of the transform module; D3DLIGHTSTATETYPE, for the lighting module; and D3DRENDERSTATETYPE, for the rasterization module.

Each state includes a Boolean value that is essentially a read-only flag. If this flag is set to TRUE, no further state changes are allowed.

Applications can override the read-only state of a module by using the D3DSTATE_OVERRIDE macro. This mechanism allows an application to reuse an execute buffer, changing its behavior by changing the system's state. Direct3D Retained Mode uses state overrides to accomplish some tasks that otherwise would require completely rebuilding an execute buffer. For example, the Retained-Mode API uses state overrides to replace the material of a mesh with the material of a frame.

An application might use the D3DSTATE_OVERRIDE macro to lock and unlock the Gouraud shade mode, as shown in the following example. (The shade-mode render state is defined by the D3DRENDERSTATE_SHADEMODE member of the D3DRENDERSTATETYPE enumerated type.)

OP_STATE_RENDER(2, lpBuffer);

    STATE_DATA(D3DRENDERSTATE_SHADEMODE, D3DSHADE_GOURAUD, lpBuffer);

    STATE_DATA(D3DSTATE_OVERRIDE(D3DRENDERSTATE_SHADEMODE), TRUE, lpBuffer);

The OP_STATE_RENDER macro implicitly uses the D3DOP_STATERENDER opcode, one of the members of the D3DOPCODE enumerated type. D3DSHADE_GOURAUD is one of the members of the D3DSHADEMODE enumerated type.

After executing the execute buffer, the application could use the D3DSTATE_OVERRIDE macro again, to allow the shade mode to be changed:

    STATE_DATA(D3DSTATE_OVERRIDE(D3DRENDERSTATE_SHADEMODE), FALSE, lpBuffer);

The OP_STATE_RENDER and STATE_DATA macros are defined in the D3dmacs.h header file in the Misc directory of the DirectX 2 SDK sample code; these macros are also described in Setting the Immediate-Mode Render State.


Direct3D File Format

The Direct3D file format stores meshes, textures, animation sets, and user-definable objects, facilitating the exchange of 3D information between applications. Support for animation sets allows predefined paths to be stored for playback in real time. Instancing and hierarchies are also supported, allowing multiple references to a single data object (such as a mesh) while storing the data for the object only once per file.

Direct3D files have a .X file name extension. This DirectX™ 2 Software Development Kit (SDK) includes conversion tools (Conv3ds.exe and Convxof.exe) that allow you to convert files from 3DS files generated by Autodesk 3D Studio® and from XOF files that were generated for earlier versions of Direct3D.

The Direct3D file format is used natively by the Direct3D Retained-Mode API, providing support for loading predefined objects into an application and for writing mesh information constructed by the application in real time.


A Technical Foundation for 3D Programming

The following sections describe some of the technical concepts you need to understand before you write programs that incorporate 3D graphics. In these sections, you will find a general discussion of coordinate systems and transformations. This is not a discussion of broad architectural details, such as setting up models, lights, and viewing parameters. For more information about these topics, see Introduction to Direct3D Retained-Mode Objects.

If you are already experienced in producing 3D graphics, simply scan the following sections for information that is unique to Direct3D Retained Mode.


3D Coordinate Systems

There are two varieties of Cartesian coordinate systems in 3D graphics: left-handed and right-handed. In both coordinate systems, the positive x-axis points to the right and the positive y-axis points up. You can remember which direction the positive z-axis points by pointing the fingers of either your left or right hand in the positive x direction and curling them into the positive y direction. The direction your thumb points, either toward or away from you, is the direction the positive z-axis points for that coordinate system.

Direct3D's Coordinate System

Direct3D uses the left-handed coordinate system. This means the positive z-axis points away from the viewer, as shown in the following illustration:

In a left-handed coordinate system, rotations occur clockwise around any axis that is pointed at the viewer.

If you need to work in a right-handed coordinate system—for example, if you are porting an application that relies on right-handedness—you can do so by making two simple changes to the data passed to Direct3D.

•	Flip the order of triangle vertices so that the system traverses them clockwise from the front. In other words, if the vertices are v0, v1, v2, pass them to Direct3D as v0, v2, v1.

•	Scale the projection matrix by -1 in the z direction. To do this, flip the signs of the _13, _23, _33, and _43 members of the D3DMATRIX structure.

U- and V-Coordinates

Direct3D also uses texture coordinates. These coordinates (u and v) are used when mapping textures onto an object. The v-vector describes the direction or orientation of the texture and lies along the z-axis. The u-vector (or the up vector) typically lies along the y-axis, with its origin at [0,0,0]. For more information about u- and v-coordinates, see Direct3DRMWrap.


3D Transformations

In programs that work with 3D graphics, you can use geometrical transformations to:

•	Express the location of an object relative to another object.

•	Rotate, shear, and size objects.

•	Change viewing positions, directions, and perspective.

You can transform any point into another point by using a 4-by-4 matrix. In the following example, a matrix is used to reinterpret the point (x, y, z), producing the new point (x', y', z'):

You perform the following operations on (x, y, z) and the matrix to produce the point (x', y', z'):

The most common transformations are translation, rotation, and scaling. You can combine the matrices that produce these effects into a single matrix to calculate several transformations at once. For example, you can build a single matrix to translate and rotate a series of points.

Matrices are specified in row order. For example, the following matrix could be represented by an array:

The array for this matrix would look like the following:

D3DMATRIX scale = {

    D3DVAL(s),    0,            0,            0,

    0,            D3DVAL(s),    D3DVAL(t),    0,

    0,            0,            D3DVAL(s),    D3DVAL(v),

    0,            0,            0,            D3DVAL(1)

};

Translation

The following transformation translates the point (x, y, z) to a new point (x', y', z'):

Rotation

The transformations described in this section are for left-handed coordinate systems, and so may be different from transformation matrices you have seen elsewhere.

The following transformation rotates the point (x, y, z) around the x-axis, producing a new point (x', y', z'):

The following transformation rotates the point around the y-axis:

The following transformation rotates the point around the z-axis:

Note that in these example matrices, the Greek letter theta stands for the angle of rotation, specified in radians. Angles are measured clockwise when looking along the rotation axis toward the origin.

Scaling

The following transformation scales the point (x, y, z) by arbitrary values in the x-, y-, and z-directions to a new point (x', y', z'):


Polygons

Three-dimensional objects in Direct3D are made up of meshes. A mesh is a set of faces, each of which is described by a simple polygon. The fundamental polygon type is the triangle. Although Retained-Mode applications can specify polygons with more than three vertices, the system translates these into triangles before the objects are rendered. Immediate-Mode applications must use triangles.

Geometry Requirements

Triangles are the preferred polygon type because they are always convex and they are always planar, two conditions that are required of polygons by the renderer. A polygon is convex if a line drawn between any two points of the polygon is also inside the polygon.

The three vertices of a triangle always describe a plane, but it is easy to accidentally create a non-planar polygon by adding another vertex.

Face and Vertex Normals

Each face in a mesh has a perpendicular face normal whose direction is determined by the order in which the vertices are defined and by whether the coordinate system is right- or left-handed. If the normal vector of a face is oriented toward the viewer, that side of the face is its front. In Direct3D, only the front side of a face is visible, and a front face is one in which vertices are defined in clockwise order.

Direct3D applications do not need to specify face normals; the system calculates them automatically when they are needed. The system uses face normals in the flat shade mode. For Phong and Gouraud shade modes, and for controlling lighting and texturing effects, the system uses vertex normals.

Shade Modes

In the flat shade mode, the system duplicates the color of one vertex across all the other faces of the primitive. In the Gouraud and Phong shade modes, vertex normals are used to give a smooth look to a polygonal object. In Gouraud shading, the color and intensity of adjacent vertices is interpolated across the space that separates them. In Phong shading, the system calculates the appropriate shade value for each pixel on a face.

Note

Phong shading is not supported for DirectX 2.

Most applications use Gouraud shading because it allows objects to appear smooth and is computationally efficient. Gouraud shading can miss details that Phong shading will not, however. For example, Gouraud and Phong shading would produce very different results in the case shown by the following illustration, in which a spotlight is completely contained within a face.

In this case, the Phong shade mode would calculate the value for each pixel and display the spotlight. The Gouraud shade mode, which interpolates between vertices, would miss the spotlight altogether; the face would be rendered as though the spotlight did not exist.

In the flat shade mode, the following pyramid would be displayed with a sharp edge between adjoining faces; the system would generate automatic face normals. In the Gouraud or Phong shade modes, however, shading values would be interpolated across the edge, and the final appearance would be of a curved surface.

If you want to use the Gouraud or Phong shade mode to display curved surfaces and you also want to include some objects with sharp edges, your application would need to duplicate the vertex normals at any intersection of faces where a sharp edge was required, as shown in the following illustration.

In addition to allowing a single object to have both curved and flat surfaces, the Gouraud shade mode lights flat surfaces more realistically than the flat shade mode. A face in the flat shade mode is a uniform color, but Gouraud shading allows light to fall across a face correctly; this effect is particularly obvious if there is a nearby point source. Gouraud shading is the preferred shade mode for most Direct3D applications.

Triangle Interpolants

The system interpolates the characteristics of a triangle's vertices across the triangle when it renders a face. The following are the triangle interpolants:

•	Color

•	Specular

•	Fog

•	Alpha

All of the triangle interpolants are modified by the current shade mode:

Flat	No interpolation is done. Instead, the color of the first vertex in the triangle is applied across the entire face.
Gouraud	Linear interpolation is performed between all three vertices.
Phong	Vertex parameters are reevaluated for each pixel in the face, using the current lighting. The Phong shade mode is not supported for DirectX 2.
The color and specular interpolants are treated differently, depending on the color model. In the RGB color model (D3DCOLOR_RGB), the system uses the red, green, and blue color components in the interpolation. In the monochromatic model (D3DCOLOR_MONO), the system uses only the blue component of the vertex color.

For example, if the red component of the color of vertex 1 were 0.8 and the red component of vertex 2 were 0.4, in the Gouraud shade mode and RGB color model the system would use interpolation to assign a red component of 0.6 to the pixel at the midpoint of the line between these vertices.

The alpha component of a color is treated as a separate interpolant because device drivers can implement transparency in two different ways: by using texture blending or by using stippling.

An application can use the dwShadeCaps member of the D3DPRIMCAPS structure to determine what forms of interpolation the current device driver supports.


Triangle Strips and Fans

You can use triangle strips and triangle fans to specify an entire surface without having to provide all three vertices for each of the triangles. For example, only seven vertices are required to define the following triangle strip.

The system uses vertices v0, v1, and v2 to draw the first triangle, v1, v3, and v2 to draw the second triangle, v3, v4, and v2 to draw the third, and so on. Notice that the vertices of the second triangle are out of order; this is required to make sure that all of the triangles are drawn in a clockwise orientation.

A triangle fan is similar to a triangle strip, except that all of the triangles share one vertex.

The system uses vertices v0, v1, and v2 to draw the first triangle, v0, v2, and v3 to draw the second triangle, and so on.

You can use the wFlags member of the D3DTRIANGLE structure to specify the flags that build triangle strips and fans.


Vectors and Quaternions

Vectors are used throughout Direct3D to describe position and orientation. Each vertex in a primitive is described by a vector that gives its position, a normal vector that gives its orientation, texture coordinates, and a color. (In Retained Mode, the D3DRMVERTEX structure contains these values.)

Quaternions add a fourth element to the [x, y, z] values that define a vector. They are an alternative to the matrix methods that are typically used for 3D rotations. Direct3D's Retained Mode includes some functions that help you work with quaternions. For example, the D3DRMQuaternionFromRotation function adds a rotation value to a vector that defines an axis of rotation and returns the result in a quaternion defined by a D3DRMQUATERNION structure.

Retained-Mode applications can use the following functions to simplify the task of working with vectors and quaternions:

D3DRMQuaternionFromRotation
D3DRMQuaternionMultiply
D3DRMQuaternionSlerp
D3DRMVectorAdd
D3DRMVectorCrossProduct
D3DRMVectorDotProduct
D3DRMVectorModulus
D3DRMVectorNormalize
D3DRMVectorRandom
D3DRMVectorReflect
D3DRMVectorRotate
D3DRMVectorScale
D3DRMVectorSubtract


Floating-point Precision

Direct3D, like the rest of the DirectX architecture, uses a floating-point precision of 53 bits. If your application needs to change this precision, it must change it back to 53 when the calculations are finished. Otherwise, system components that depend on the default value will stop working.


Performance Optimization

Every developer who creates real-time applications that use 3D graphics is concerned about performance optimization. This section provides you with guidelines about getting the best performance from your code.

You can use the guidelines in the following sections for any Direct3D application:

•	Clip Tests on Execution

•	Batching Primitives

•	Texture Size

•	Triangle Flags

Direct3D applications can use either the ramp driver (for the monochromatic color model) or the RGB driver. The performance notes in the following sections apply to the ramp driver:

•	Ramp Performance Tips

•	Ramp Textures

•	Z-Buffers

•	Copy Mode


Clip Tests on Execution

Your application can use the IDirect3DDevice::Execute method to render primitives with or without automatic clipping. Using this method without clipping is always faster than setting the clipping flags because clipping tests during either the transformation or rasterization stages slow the process. If your application does not use automatic clipping, however, it must ensure that all of the rendering data is wholly within the viewing frustum. The best way to ensure this is to use simple bounding volumes for the models and transform these first. You can use the results of this first transformation to decide whether to wholly reject the data because all the data is outside the frustum, whether to use the no-clipping version of the IDirect3DDevice::Execute method because all the data is within the frustum, or whether to use the clipping flags because the data is partially within the frustum. In Immediate Mode it is possible to set up this sort of functionality within one execute buffer by using the flags in the D3DSTATUS structure and the D3DOP_BRANCHFORWARD member of the D3DOPCODE enumerated type to skip geometry when a bounding volume is outside the frustum. Direct3D's Retained Mode automatically uses these features to speed up its use of execute buffers.


Batching Primitives

To get the best rendering performance during execution, you should try to work with primitives in batches and keep the number of render-state changes as low as possible. For example, if you have an object with two textures, group the triangles that use the first texture and follow them with the necessary render state to change the texture, then group all the triangles that use the second texture. The simplest hardware support for Direct3D is called with batches of render states and batches of primitives through the hardware-abstraction layer (HAL). The more effectively the instructions are batched, the fewer HAL calls are performed during execution.


Texture Size

Texture-mapping performance is heavily dependent on the speed of memory. There are a number of ways to maximize the cache performance of your application's textures.

•	Keep the textures small; the smaller the textures are, the better chance they have of being maintained in the main CPU's secondary cache.

•	Do not change the textures on a per-primitive basis. Try to keep polygons grouped in order of the textures they use.

•	Use square textures whenever possible. Textures whose dimensions are 256 by 256 are the fastest. If your application uses four 128-by-128 textures, for example, try to ensure that they use the same palette and place them all into one 256-by-256 texture. This technique also reduces the amount of texture swapping. Of course, you should not use 256-by-256 textures unless your application requires that much texturing because, as already mentioned, textures should be kept as small as possible.


Triangle Flags

The wFlags member of the D3DTRIANGLE structure includes flags that allow the system to reuse vertices when building triangle strips and fans. Effective use of these flags allows some hardware to run much faster than it would otherwise.

Applications can use these flags in two ways as acceleration hints to the driver:

D3DTRIFLAG_STARTFLAT(len)

	If the current triangle is culled, the driver can also cull the number of subsequent triangles given by len in the strip or fan.
D3DTRIFLAG_ODD and D3DTRIFLAG_EVEN

	The driver needs to reload only one new vertex from the triangle and it can reuse the other two vertices from the last triangle that was rendered.
The best possible performance occurs when an application uses both the D3DTRIFLAG_STARTFLAT flag and the D3DTRIFLAG_ODD and D3DTRIFLAG_EVEN flags.

Because some drivers might not check the D3DTRIFLAG_STARTFLAT flag, applications must be careful when using it. An application using a driver that doesn't check this flag might not render polygons that should have been rendered.

Applications must use the D3DTRIFLAG_START flag before using the D3DTRIFLAG_ODD and D3DTRIFLAG_EVEN flags. D3DTRIFLAG_START causes the driver to reload all three vertices. All triangles following the D3DTRIFLAG_START flag can use the D3DTRIFLAG_ODD and D3DTRIFLAG_EVEN flags indefinitely, providing the triangles share edges.

The debugging version of this SDK validates the D3DTRIFLAG_ODD and D3DTRIFLAG_EVEN flags.

For more information, see Triangle Strips and Fans.


Ramp Performance Tips

Applications should use the following techniques to achieve the best possible performance when using the monochromatic (ramp) driver:

•	Share the same palette among all textures.

•	Keep the number of colors in the palette as low as possible—64 or fewer is best.

•	Keep the ramp size in materials at 16 or less.

•	Make all materials the same (except the texture handle)—allow the textures to specify the coloring. For example, make all the materials white and keep their specular power the same. Many applications do not need more than two materials in a scene: one with a specular power for shiny objects, and one without for matte objects.

•	Keep textures as small as possible.

•	Fit multiple small textures into a single texture that is 256-by-256 pixels.

•	Render small triangles by using the Gouraud shade mode, and render large triangles by using the flat shade mode.

Developers who must use more than one palette can optimize their code by using one palette as a master palette and ensuring that the other palettes contain a subset of the colors in the master palette.


Ramp Textures

Applications that use the ramp driver should be conservative with the number of texture colors they require. Each color used in a monochromatic texture requires its own lookup table during rendering. If your application uses hundreds of colors in a scene during rendering, the system must use hundreds of lookup tables, which do not cache well. Also, try to share palettes between textures whenever possible. Ideally, all of your application's textures will fit into one palette, even when you are using a ramp driver with depths greater than 8-bit color.


Z-Buffers

Applications that use the ramp driver can increase performance when using z-buffering and texturing by ensuring that scenes are rendered from front to back. Textured z-buffered primitives are pretested against the z-buffer on a scanline basis. If a scanline is hidden by a previously rendered polygon, the system rejects it quickly and efficiently. Z-buffering can improve performance, but the technique is most useful when a scene includes a great deal of overdraw. Overdraw is the average number of times a screen pixel is written to. Overdraw is difficult to calculate exactly, but you can often make a close approximation. If the overdraw averages less than 2, you can achieve the best performance by turning z-buffering off.

You can also improve the performance of your application by z-testing primitives; that is, by testing a given list of primitives against the z-buffer. This allows for fast bounding-box rejection of occluded geometry.

The Retained-Mode API can automatically order its scenes from front to back to facilitate z-buffer optimization. Retained Mode also z-tests primitives for all meshes that contain more than a few hundred triangles.

You can use the fill-rate test in the D3dtest.exe application that is provided with this SDK to demonstrate overdraw performance for a given driver. (The fill-rate test draws four tunnels from front to back or back to front, depending on the setting you choose.)

On faster personal computers, software rendering to system memory is often faster than rendering to video memory, although it has the disadvantage of not being able to use double buffering or hardware-accelerated clear operations. If your application can render to either system or video memory, and if you include a routine that tests which is faster, you can take advantage of the best approach on the current system. The Direct3D sample code in this SDK demonstrates this strategy. It is necessary to implement both methods because there is no other way to test the speed. Speeds can vary enormously from computer to computer, depending on the main-memory architecture and the type of graphics adapter being used. Although you can use D3dtest.exe to test the speed of system memory against video memory, it cannot predict the performance of your user's personal computer.

You can run all of the Direct3D samples in system memory by using the "-systemmemory" command-line option. This is also useful when developing code because it allows your application to fail in a way that stops the renderer without stopping your system—DirectDraw does not take the WIN16 lock for system-memory surfaces. (The WIN16 lock serializes access to GDI and USER, shutting down Windows for the interval between calls to the IDirectDrawSurface::Lock and IDirectDrawSurface::Unlock methods, as well as between calls to the IDirectDrawSurface::GetDC and IDirectDrawSurface::ReleaseDC methods.)


Copy Mode

Applications that use the ramp driver can sometimes improve performance by using the D3DTBLEND_COPY texture-blending mode from the D3DTEXTUREBLEND enumerated type.

To use copy mode, your application's textures must use the same pixel format as the primary surface and also must use the same palette as the primary surface. Copy mode does no lighting and simply copies texture pixels to the screen. This is often a good technique for prelit textured scenes.

If your application uses the monochromatic model with 8-bit color and no lighting, performance can improve if you use copy mode. If your application uses 16-bit color, however, copy mode is not quite as fast as using modulated textures; for 16-bit color, textures are twice the size as in the 8-bit case, and the extra burden on the cache makes performance slightly worse than using an 8-bit lit texture. Again, you can use D3dtest.exe to verify system performance in this case.


Retained-Mode Overview


About Retained Mode

This section describes Direct3D's Retained Mode, Microsoft's solution for real-time 3D graphics on the personal computer. If you need to create a 3D environment and manipulate it in real time, you should use Direct3D's Retained-Mode API.

Direct3D is integrated tightly with DirectDraw. A DirectDraw object encapsulates both the DirectDraw and Direct3D states—your application can use the IDirectDraw::QueryInterface method to retrieve an IDirect3D interface to a DirectDraw object. For more information about this integration, see Direct3D Driver Interface.

If you have written code that uses 3D graphics before, many of the concepts underlying Retained Mode will be familiar to you. If, however, you are new to 3D programming, you should pay close attention to Introduction to Direct3D Retained-Mode Objects, and you should read A Technical Foundation for 3D Programming. Whether you are new to 3D programming or just beginning, you should look carefully at the sample code included with this SDK; it illustrates how to put Retained Mode to work in real-world applications.

This section is an introduction to 3D programming. It describes Microsoft's 3D-graphics solutions and some of the technical background you need to manipulate points in three dimensions. It is not an introduction to programming with Direct3D's Retained Mode; for this information, see Direct3D Retained-Mode Tutorial.


Introduction to Direct3D Retained-Mode Objects

All access to Direct3D Retained Mode is through a small set of objects. The following table lists these objects and a brief description of each:

Object	Description
Direct3DRMAnimation	This object defines how a transformation will be modified, often in reference to a Direct3DRMFrame object; therefore, you can use it to animate the position, orientation, and scaling of Direct3DRMVisual, Direct3DRMLight, and Direct3DRMViewport objects.
Direct3DRMAnimationSet	This object allows Direct3DRMAnimation objects to be grouped together.
Direct3DRMDevice	This object represents the visual display destination for the renderer.
Direct3DRMFace	This object represents a single polygon in a mesh.
Direct3DRMFrame	This object positions objects within a scene and defines the positions and orientations of visual objects.
Direct3DRMLight	This object defines one of five types of lights that are used to illuminate the visual objects in a scene.
Direct3DRMMaterial	This object defines how a surface reflects light.
Direct3DRMMesh	This object consists of a set of polygonal faces. You can use this object to manipulate groups of faces and vertices.
Direct3DRMMeshBuilder	This object allows you to work with individual vertices and faces in a mesh.
Direct3DRMObject	This object is a base class used by all other Direct3D Retained-Mode objects; it has characteristics that are common to all objects.
Direct3DRMPickedArray	This object identifies a visual object that corresponds to a given 2D point.
Direct3DRMShadow	This object defines a shadow.
Direct3DRMTexture	This object is a rectangular array of colored pixels.
Direct3DRMUserVisual	This object is defined by an application to provide functionality not otherwise available in the system.
Direct3DRMViewport	This object defines how the 3D scene is rendered into a 2D window.
Direct3DRMVisual	This object is anything that can be rendered in a scene. Visual objects need not be visible; for example, a frame can be added as a visual object.
Direct3DRMWrap	This object calculates texture coordinates for a face or mesh.
Many objects can be grouped into arrays, called array objects. Array objects make it simpler to apply operations to the entire group. The COM interfaces that allow you to work with array objects contain the GetElement and GetSize methods. These methods retrieve a pointer to an element in the array and the size of the array, respectively. For more information about array interfaces, see Introduction to Array Interfaces.


Objects and Interfaces

Calling the IObjectName::QueryInterface method retrieves a valid interface pointer only if the object supports that interface; therefore, you could call the IDirect3DRMDevice::QueryInterface method to retrieve the IDirect3DRMWinDevice interface, but not to retrieve the IDirect3DRMVisual interface.

Object name	Supported interfaces
Direct3DRMAnimation	IDirect3DRMAnimation
Direct3DRMAnimationSet	IDirect3DRMAnimationSet
Direct3DRMDevice	IDirect3DRMDevice, IDirect3DRMWinDevice
Direct3DRMFace	IDirect3DRMFace
Direct3DRMFrame	IDirect3DRMFrame, IDirect3DRMVisual
Direct3DRMLight	IDirect3DRMLight
Direct3DRMMaterial	IDirect3DRMMaterial
Direct3DRMMesh	IDirect3DRMMesh, IDirect3DRMVisual
Direct3DRMMeshBuilder	IDirect3DRMMeshBuilder, IDirect3DRMVisual
Direct3DRMShadow	IDirect3DRMShadow, IDirect3DRMVisual
Direct3DRMTexture	IDirect3DRMTexture, IDirect3DRMVisual
Direct3DRMUserVisual	IDirect3DRMUserVisual, IDirect3DRMVisual
Direct3DRMViewport	IDirect3DRMViewport
Direct3DRMWrap	IDirect3DRMWrap
The following code sample illustrates how to create two interfaces to a single Direct3DRMDevice object. The IDirect3DRM::CreateObject method creates an uninitialized Direct3DRMDevice object. The IDirect3DRMDevice::InitFromClipper method initializes the object. The call to the IDirect3DRMDevice::QueryInterface method creates a second interface to the Direct3DRMDevice object—an IDirect3DRMWinDevice interface the application will use to handle WM_PAINT and WM_ACTIVATE messages.

d3drmapi->CreateObject(CLSID_CDirect3DRMDevice, NULL,

    IID_IDirect3DRMDevice,(LPVOID FAR*)&dev1);

dev1->InitFromClipper(lpDDClipper, IID_IDirect3DRMDevice,

    r.right, r.bottom);

dev1->QueryInterface(IID_IDirect3DRMWinDevice, (LPVOID*) &dev2);

To determine if two interfaces refer to the same object, call the QueryInterface method of each interface and compare the values of the pointers they return. If the pointer values are the same, the interfaces refer to the same object.

All Direct3D Retained-Mode objects support the IDirect3DRMObject and IUnknown interfaces in addition to the interfaces in the preceding list. Array objects are not derived from IDirect3DRMObject, however. Array objects have no class identifiers (CLSIDs) because they are not needed. Applications cannot create array objects in a call to the IDirect3DRM::CreateObject method; instead, they should use the creation methods listed below for each interface:

Array interface	Creation method
IDirect3DRMDeviceArray	IDirect3DRM::GetDevices
IDirect3DRMFaceArray	IDirect3DRMMeshBuilder::GetFaces
IDirect3DRMFrameArray	IDirect3DRMPickedArray::GetPick
	or IDirect3DRMFrame::GetChildren
IDirect3DRMLightArray	IDirect3DRMFrame::GetLights
IDirect3DRMPickedArray	IDirect3DRMViewport::Pick
IDirect3DRMViewportArray	IDirect3DRM::CreateFrame
IDirect3DRMVisualArray	IDirect3DRMFrame::GetVisuals


Objects and Reference Counting

Whenever an object is created, its reference count is increased. Each time an application creates a child of an object or a method returns a pointer to an object, the system increases the reference count for that object. The object is not deleted until its reference count reaches zero.

Applications should need to keep track of the reference count for a single object only: the root of the scene. The system keeps track of the other reference counts automatically. Applications should be able to simply release the scene, the viewport, and the device when they clean up before exiting. (When your application releases the viewport, the system automatically takes care of the camera's references.) An application could theoretically release a viewport without releasing the device, such as if it needed to add a new viewport to the device, but whenever an application releases a device, it should release the viewport as well.

The reference count of a frame object increases whenever a child frame or visual object is added to the frame. When you use the IDirect3DRMFrame::AddChild method to move a child from one parent to another, the system handles the reference counting automatically.

After your application loads a visual object into a scene, the scene handles the reference counting for the visual object. The application no longer needs the visual object and can release it.

Creating and applying a wrap does not increase the reference count of any objects, because wrapping is really just a convenient method of calculating texture coordinates.


Direct3DRMAnimation and Direct3DRMAnimationSet

An animation in Retained Mode is defined by a set of keys. A key is a time value associated with a scaling operation, an orientation, or a position. A Direct3DRMAnimation object defines how a transformation is modified according to the time value. The animation can be set to operate on a Direct3DRMFrame object, so it could be used to animate the position, orientation, and scaling of Direct3DRMVisual, Direct3DRMLight, and Direct3DRMViewport objects.

TheIDirect3DRMAnimation::AddPositionKey, IDirect3DRMAnimation::AddRotateKey, and IDirect3DRMAnimation::AddScaleKey methods each specify a time value whose units are arbitrary. If an application adds a position key with a time value of 99, for example, a new position key with a time value of 49 would occur exactly halfway between the (zero-based) beginning of the animation and the first position key.

The animation is driven by calling the IDirect3DRMAnimation::SetTime method. This sets the visual object's transformation to the interpolated position, orientation, and scale of the nearby keys in the animation. As with the methods that add animation keys, the time value for IDirect3DRMAnimation::SetTime is an arbitrary value, based on the positions of keys the application has already added.

A Direct3DRMAnimationSet object allows Direct3DRMAnimation objects to be grouped together. This allows all the animations in an animation set to share the same time parameter, simplifying the playback of complex articulated animation sequences. An application can add an animation to an animation set by using the IDirect3DRMAnimationSet::AddAnimation method, and it can remove one by using the IDirect3DRMAnimationSet::DeleteAnimation method. Animation sets are driven by calling the IDirect3DRMAnimationSet::SetTime method.

For related information, see the IDirect3DRMAnimation and IDirect3DRMAnimationSet interfaces.


Direct3DRMDevice and Direct3DRMDeviceArray

All forms of rendered output must be associated with an output device. The device object represents the visual display destination for the renderer.

The renderer's behavior depends on the type of output device that is specified. You can define multiple viewports on a device, allowing different aspects of the scene to be viewed simultaneously. You can also specify any number of devices, allowing multiple destination devices for the same scene.

Retained Mode supports devices that render directly to the screen, to windows, or into application memory.

For related information, see the IDirect3DRMDevice interface.

Quality

The device allows the scene and its component parts to be rendered with various degrees of realism. Each mesh can have its own quality, but the maximum quality available for a mesh is that of the device.

An application can change the rendering quality of a device by using the IDirect3DRMDevice::SetQuality and IDirect3DRMMeshBuilder::SetQuality methods. To retrieve the rendering quality for a device, it can use the IDirect3DRMDevice::GetQuality and IDirect3DRMMeshBuilder::GetQuality methods.

Color Models

Retained Mode supports two color models: an RGB model and a monochromatic (or ramp) model. To retrieve the color model, an application can use the IDirect3DRMDevice::GetColorModel method.

The RGB model treats color as a combination of red, green, and blue light, and it supports multiple light sources that can be colored. There is no limit to the number of colors in the scene. You can use this model with 8-, 16-, 24-, and 32-bit displays. If the display depth is less than 24 bits, the limited color resolution can produce banding artifacts; you can avoid these artifacts by using optional dithering.

The monochromatic model also supports multiple light sources, but their color content is ignored. Each source is set to a gray intensity. RGB colors at a vertex are interpreted as brightness levels, which (in Gouraud shading) are interpolated across a face between vertices with different brightnesses. The number of differently colored objects in the scene is limited; after all the system's free palette entries are used up, the system's internal palette manager finds colors that already exist in the palette and that most closely match the intended colors. Like the RGB model, you can use this model with 8-, 16-, 24-, and 32-bit displays. (The monochromatic model supports only 8-bit textures, however.) The advantage of the monochromatic model over the RGB model is simply performance.

It is not possible to change the color model of a Direct3D device. Your application should use the IDirect3D::EnumDevices or IDirect3D::FindDevice method to identify a driver that supports the required color model, then specify this driver in one of the device-creation methods.

Window Management

For correct operation, applications must inform Retained Mode when WM_MOVE, WM_PAINT, and WM_ACTIVATE messages are received from the operating system by using the IDirect3DRMWinDevice::HandlePaint and IDirect3DRMWinDevice::HandleActivate methods.

For related information, see IDirect3DRMWinDevice.


Direct3DRMFace and Direct3DRMFaceArray

A face represents a single polygon in a mesh. An application can set the color, texture, and material of the face by using the IDirect3DRMFace::SetColor, IDirect3DRMFace::SetColorRGB, IDirect3DRMFace::SetTexture, and IDirect3DRMFace::SetMaterial methods.

Faces are constructed from vertices by using the IDirect3DRMFace::AddVertex and IDirect3DRMFace::AddVertexAndNormalIndexed methods. An application can read the vertices of a face by using the IDirect3DRMFace::GetVertices and IDirect3DRMFace::GetVertex methods.

For related information, see IDirect3DRMFace.


Direct3DRMFrame and Direct3DRMFrameArray

The term frame is derived from an object's physical frame of reference. The frame's role in Retained Mode is similar to a window's role in a windowing system. Objects can be placed in a scene by stating their spatial relationship to a relevant reference frame; they are not simply placed in world space. A frame is used to position objects in a scene, and visuals take their positions and orientation from frames.

A scene in Retained Mode is defined by a frame that has no parent frame; that is, a frame at the top of the hierarchy of frames. This frame is also sometimes called a root frame or master frame. The scene defines the frame of reference for all of the other objects. You can create a scene by calling the IDirect3DRM::CreateFrame function and specifying NULL for the first parameter.

You should be comfortable with Direct3D's left-handed coordinate system before working with frames. For more information about coordinate systems, see 3D Coordinate Systems.

Hierarchies

The frames in a scene are arranged in a tree structure. Frames can have a parent frame and child frames. Remember, a frame that has no parent frame defines a scene.

Child frames have positions and orientations relative to their parent frames. If the parent frame moves, the child frames also move.

An application can set the position and orientation of a frame relative to any other frame in the scene, including the root frame if it needs to set an absolute position.  You can also remove frames from one parent frame and add them to another at any time by using the IDirect3DRMFrame::AddChild method. To remove a child frame entirely, use the IDirect3DRMFrame::DeleteChild method. To retrieve a frame's child and parent frames, use the IDirect3DRMFrame::GetChildren and IDirect3DRMFrame::GetParent methods.

You can add frames as visuals to other frames, allowing you to use a given hierarchy many times throughout a scene. The new hierarchies are referred to as instances. Be careful to avoid instancing a parent frame into its children, because that will degrade performance. Retained Mode does no run-time checking for cyclic hierarchies. You cannot create a cyclic hierarchy by using the methods of the IDirect3DRMFrame interface; instead, this is possible only when you add a frame as a visual.

Transformations

You can also think of the position and orientation of a frame relative to its parent frame as a linear transformation that takes vectors defined relative to the child frame and changes them to equivalent vectors defined relative to the parent.

Transformations can be represented by 4-by-4 matrices, and coordinates can be represented by four-element row vectors, [x, y, z, 1].

If vchild is a coordinate in the child frame, then vparent, the equivalent coordinate in the parent frame, is defined as:

vparent=vchildTchild
Tchild is the child frame's transformation matrix.

The transformations of all the parent frames above a child frame up to the root frame are concatenated with the transformation of that child to produce a world transformation. This world transformation is then applied to the visuals on the child frame before rendering. Coordinates relative to the child frame are sometimes called model coordinates. After the world transformation is applied, coordinates are called world coordinates.

The transformation of a frame can be modified directly by using the IDirect3DRMFrame::AddTransform, IDirect3DRMFrame::AddScale, IDirect3DRMFrame::AddRotation, and IDirect3DRMFrame::AddTranslation methods. Each of these methods specifies a member of the D3DRMCOMBINETYPE enumerated type, which specifies how the matrix supplied by the application should be combined with the current frame's matrix.

The IDirect3DRMFrame::GetRotation and IDirect3DRMFrame::GetTransform methods allow you to retrieve a frame's rotation axis and transformation matrix. To change the rotation of a frame, use the IDirect3DRMFrame::SetRotation method.

Use the IDirect3DRMFrame::Transform and IDirect3DRMFrame::InverseTransform methods to change between world coordinates and frame coordinates.

Motion

Every frame has an intrinsic rotation and velocity. Frames that are neither rotating nor translating simply have zero values for these attributes. These attributes are used before each scene is rendered to move objects in the scene, and they can also be used to create simple animations.

Callback Functions

Frames support a callback function that you can use to support more complex animations. The application registers a function that the frame calls before the motion attributes are applied. Where there are multiple frames in a hierarchy, each with associated callback functions, the parent frames are called before the child frames. For a given hierarchy, rendering does not take place until all of the required callback functions have been invoked.

To add this callback function, use the IDirect3DRMFrame::AddMoveCallback method; to remove it, use the IDirect3DRMFrame::DeleteMoveCallback method.

You can use these callback functions to provide new positions and orientations from a preprogrammed animation sequence or to implement dynamic motion in which the activities of visuals depend upon the positions of other objects in the scene.


Direct3DRMLight and Direct3DRMLightArray

Lighting effects are employed to increase the visual fidelity of a scene. The system colors each object based on the object's orientation to the light sources in the scene. The contribution of each light source is combined to determine the color of the object during rendering. All lights have color and intensity that can be varied independently.

An application can attach lights to a frame to represent a light source in a scene. When a light is attached to a frame, it illuminates visual objects in the scene. The frame provides both position and orientation for the light. In other words, the light originates from the origin of the frame it is attached to. An application can move and redirect a light source simply by moving and reorienting the frame the light source is attached to.

Each viewport owns one or more lights. No light can be owned by more than one viewport. For more information about the interdependencies of Direct3D components, see Object Connectivity.

Retained Mode currently provides five types of light sources: ambient, directional, parallel point, point, and spotlight.

Ambient

An ambient light source illuminates everything in the scene, regardless of the orientation, position, and surface characteristics of the objects in the scene. Because ambient light illuminates a scene with equal strength everywhere, the position and orientation of the frame it is attached to are inconsequential. Multiple ambient light sources are combined within a scene.

Directional

A directional light source has orientation but no position. The light is attached to a frame but appears to illuminate all objects with equal intensity, as if it were at an infinite distance from the objects. The directional source is commonly used to simulate distant light sources, such as the sun. It is the best choice of light to use for maximum rendering speed.

Parallel Point

A parallel point light source illuminates objects with parallel light, but the orientation of the light is taken from the position of the parallel point light source. That is, like a directional light source, a parallel point light source has orientation, but it also has position. For example, two meshes on either side of a parallel point light source are lit on the side that faces the position of the source. The parallel point light source offers similar rendering-speed performance to the directional light source.

Point

A point light source radiates light equally in all directions from its origin. It requires the calculation of a new lighting vector for every facet or normal it illuminates, and for this reason it is computationally more expensive than a parallel point light source. It does, however, produce a more faithful lighting effect and should be chosen where visual fidelity is the deciding concern.

Spotlight

A spotlight emits a cone of light. Only objects within the cone are illuminated. The cone produces light of two degrees of intensity, with a central brightly lit section (the umbra) that acts as a point source, and a surrounding dimly lit section (the penumbra) that merges with the surrounding deep shadow. The angles of these two sections can be individually specified by using the IDirect3DRMLight::GetPenumbra, IDirect3DRMLight::GetUmbra, IDirect3DRMLight::SetPenumbra, and IDirect3DRMLight::SetUmbra methods.


Direct3DRMMaterial

A material defines how a surface reflects light. A material has two components: an emissive property (whether it emits light) and a specular property, whose brightness is determined by a power setting. The value of the power determines the sharpness of the reflected highlights, with a value of 5 giving a metallic appearance and higher values giving a more plastic appearance.

An application can control the emission of a material by using the IDirect3DRMMaterial::GetEmissive and IDirect3DRMMaterial::SetEmissive methods, the specular component by using the IDirect3DRMMaterial::GetSpecular and IDirect3DRMMaterial::SetSpecular methods, and the power by using the IDirect3DRMMaterial::GetPower and IDirect3DRMMaterial::SetPower methods.


Direct3DRMMesh and Direct3DRMMeshBuilder

A mesh is a visual object that is made up of a set of polygonal faces. A mesh defines a set of vertices and a set of faces (the faces are defined in terms of the vertices and normals of the mesh). Changing a vertex or normal that is used by several faces changes the appearance of all faces sharing it.

The vertices of a mesh define the positions of faces in the mesh, and they can also be used to define 2D coordinates within a texture map.

You can manipulate meshes in Retained Mode by using two COM interfaces: IDirect3DRMMesh and IDirect3DRMMeshBuilder. IDirect3DRMMesh is very fast, and you should use it when a mesh is subject to frequent changes, such as when morphing. IDirect3DRMMeshBuilder is built on top of the IDirect3DRMMesh interface. Although the IDirect3DRMMeshBuilder interface is a convenient way to perform operations on individual faces and vertices, the system must convert a Direct3DRMMeshBuilder object into a Direct3DRMMesh object before rendering it. For meshes that do not change or that change infrequently, this conversion has a negligible impact on performance.

If an application needs to assign the same characteristics (such as material or texture) to several vertices or faces, it can use the IDirect3DRMMesh interface to combine them in a group. If the application needs to share vertices between two different groups (for example, if neighboring faces in a mesh are different colors), the vertices must be duplicated in both groups. The IDirect3DRMMesh::AddGroup method assigns a group identifier to a collection of faces. This identifier is used to refer to the group in subsequent calls.

The IDirect3DRMMeshBuilder and IDirect3DRMMesh interfaces allow an application to create faces with more than three sides. They also automatically split a mesh into multiple buffers if, for example, the hardware the application is rendering to has a limit of 64K and a mesh is larger than that size. These features set the Direct3DRMMesh and Direct3DRMMeshBuilder API apart from the Direct3D API.

You can add vertices and faces individually to a mesh by using the IDirect3DRMMeshBuilder::AddVertex, IDirect3DRMMeshBuilder::AddFace, and IDirect3DRMMeshBuilder::AddFaces methods.

You can define individual color, texture, and material properties for each face in the mesh, or for all faces in the mesh at once, by using the IDirect3DRMMesh::SetGroupColor, IDirect3DRMMesh::SetGroupColorRGB, IDirect3DRMMesh::SetGroupTexture, and IDirect3DRMMesh::SetGroupMaterial methods.

For a mesh to be rendered, you must first add it to a frame by using the IDirect3DRMFrame::AddVisual method. You can add a single mesh to multiple frames to create multiple instances of that mesh.

Your application can use flat, Gouraud, and Phong shade modes, as specified by a call to the IDirect3DRMMesh::SetGroupQuality method. (Phong shading is not available for DirectX 2, however.) This method uses values from the D3DRMRENDERQUALITY enumerated type. For more information about shade modes, see Polygons.

You can set normals (which should be unit vectors), or normals can be calculated by averaging the face normals of the surrounding faces by using the IDirect3DRMMeshBuilder::GenerateNormals method.


Direct3DRMObject

Direct3DRMObject is the common superclass of all objects in the system. A Direct3DRMObject object has characteristics common to all objects.

Each Direct3DRMObject object is instantiated as a COM object. In addition to the methods of the IUnknown interface, each object has a standard set of methods that are generic to all.

To create an object, the application must first have instantiated a Direct3D Retained-Mode object by calling the Direct3DRMCreate function. The application then calls the method of the object's interface that creates an object, and it specifies parameters specific to the object. For example, to create a Direct3DRMAnimation object, the application would call the IDirect3DRM::CreateAnimation method. The creation method then creates a new object, initializes some of the object's attributes from data passed in the parameters (leaving all others with their default values), and returns the object. Applications can then specify the interface for this object to modify and use the object.

Any object can store 32 bits of application-specific data. This data is not interpreted or altered by Retained Mode. The application can read this data by using the IDirect3DRMObject::GetAppData method, and it can write to it by using the IDirect3DRMObject::SetAppData method. Finding this data is simpler if the application keeps a structure for each Direct3DRMFrame object. For example, if calling the IDirect3DRMFrame::GetParent method retrieves a Direct3DRMFrame object, the application can easily retrieve the data by using a pointer to its private structure, possibly avoiding a time-consuming search.

You might also want to assign a name to an object to help you organize an application or as part of your application's user interface. You can use the IDirect3DRMObject::SetName and IDirect3DRMObject::GetName methods to set and retrieve object names.

Another example of possible uses for application-specific data is when an application needs to group the faces within a mesh into subsets (for example, for front and back faces). You could use the application data in the face to note in which of these groups a face should be included.

An application can specify a function to call when an object is destroyed, such as when the application needs to deallocate memory associated with the object. To do this, use the IDirect3DRMObject::AddDestroyCallback method. To remove a function previously registered with this method, use the IDirect3DRMObject::DeleteDestroyCallback method.

The callback function is called only when the object is destroyed—that is, when the object's reference count has reached 0 and the system is about to deallocate the memory for the object. If an application kept additional data about an object (so that its dynamics could be implemented, for example), the application could use this callback function as a way to notify itself that it can dispose of the data.

For related information, see IDirect3DRMObject.


Direct3DRMPickedArray

Picking is the process of searching for visuals in a scene, given a 2D coordinate in a viewport. You can use the IDirect3DRMViewport::Pick method to retrieve an IDirect3DRMPickedArray interface, and then call the IDirect3DRMPickedArray::GetPick method to retrieve an IDirect3DRMFrameArray interface and a visual object. The array of frames is the path through the hierarchy leading to the visual object; that is, a hierarchical list of the visual object's parent frames, with the top-most parent in the hierarchy first in the array.


Direct3DRMShadow

Applications can produce an initialized and usable shadow simply by calling the IDirect3DRM::CreateShadow method. The IDirect3DRMShadow interface exists so that applications that create a shadow by using the IDirect3DRM::CreateObject method can initialize the shadow by calling the IDirect3DRMShadow::Init method.


Direct3DRMTexture

A texture is a rectangular array of colored pixels. (The rectangle does not necessarily have to be square, although the system deals most efficiently with square textures.) You can use textures for texture-mapping faces, in which case their dimensions must be powers of two.

An IDirect3DRMTexture interface is actually an interface to a DirectDrawSurface object, not to a distinct Direct3D texture object. For more information about the relationship between textures in Direct3D and surfaces in DirectDraw, see Direct3D Texture Interface.

Your application can use the IDirect3DRM::CreateTexture method to create a texture from a D3DRMIMAGE structure, or the IDirect3DRM::CreateTextureFromSurface method to create a texture from a DirectDraw surface. The IDirect3DRM::LoadTexture method allows your application to load a texture from a file; the texture should be in Windows bitmap (.bmp) or Portable Pixmap (.ppm) format.

The texture coordinates of each face define the region in the texture that is mapped onto that particular face. Your application can use a wrap to calculate texture coordinates. For more information, see Direct3DRMWrap.

Decals

Textures can also be rendered directly, as visuals. Textures used this way are sometimes known as decals, a term adopted by Retained Mode. A decal is rendered into a viewport-aligned rectangle. The rectangle can optionally be scaled by the depth component of the decal's position. The size of the decal is taken from a rectangle defined relative to the containing frame by using the IDirect3DRMTexture::SetDecalSize method. (An application can retrieve the size of the decal by using the IDirect3DRMTexture::GetDecalSize method.) The decal is then transformed and perspective projection is applied.

Decals have origins that your application can set and retrieve by using the IDirect3DRMTexture::SetDecalOrigin and IDirect3DRMTexture::GetDecalOrigin methods. The origin is an offset from the top-left corner of the decal. The default origin is [0, 0]. The decal's origin is aligned with its frame's position when rendering.

Texture Colors

You can set and retrieve the number of colors that are used to render a texture by using the IDirect3DRMTexture::SetColors and IDirect3DRMTexture::GetColors methods.

If your application uses the RGB color model, you can use 8-bit, 24-bit, and 32-bit textures. If you use the monochromatic (or ramp) color model, however, you can use only 8-bit textures.

Several shades of each color are used when lighting a scene. An application can set and retrieve the number of shades used for each color by calling the IDirect3DRMTexture::SetShades and IDirect3DRMTexture::GetShades methods.

A Direct3DRMTexture object uses a D3DRMIMAGE structure to define the bitmap that the texture will be rendered from. If the application provides the D3DRMIMAGE structure, the texture can easily be animated or altered during rendering.

Mipmaps

A mipmap is a sequence of textures, each of which is a progressively lower resolution, prefiltered representation of the same image. Mipmapping is a computationally low-cost way of improving the quality of rendered textures. Each prefiltered image, or level, in the mipmap is a power of two smaller than the previous level. You can specify mipmaps when filtering textures by calling the IDirect3DRMDevice::SetTextureQuality method.

For more information about how to use DirectDraw to create mipmaps, see Mipmaps.

Texture Filtering

After a texture has been mapped to a surface, the texture elements (texels) of the texture rarely correspond to individual pixels in the final image. A pixel in the final image can correspond to a large collection of texels or to a small piece of a single texel. You can use texture filtering to specify how to interpolate texel values to pixels.

You can use the IDirect3DRMDevice::SetTextureQuality method and the D3DRMTEXTUREQUALITY enumerated type to specify the texture filtering mode for your application.

Texture Transparency

You can use the IDirect3DRMTexture::SetDecalTransparency method to produce transparent textures. Another method for achieving transparency is to use DirectDraw's support for color keys. Color keys are colors or ranges of colors that can be part of either the source or destination of a blit or overlay operation. You can specify that these colors should always be overwritten or never be overwritten.

For more information about DirectDraw's support for color keys, see Color Keying.

For related information, see IDirect3DRMTexture.


Direct3DRMUserVisual

User-visual objects are application-defined data that an application can add to a scene and then render, typically by using a customized rendering module. For example, an application could add sound as a user-visual object in a scene, and then render the sound during playback.

You can use the IDirect3DRM::CreateUserVisual method to create a user-visual object.


Direct3DRMViewport and Direct3DRMViewportArray

The viewport defines how the 3D scene is rendered into a 2D window. The viewport defines a rectangular area on a device that objects will be rendered into.

Camera

The viewport uses a Direct3DRMFrame object as a camera. The camera frame defines which scene is rendered and the viewing position and direction. The viewport renders only what is visible along the positive z-axis of the camera frame, with the up direction being in the direction of the positive y-axis.

An application can call the IDirect3DRMViewport::SetCamera method to set a camera for a given viewport. This method sets a viewport's position, direction, and orientation to that of the given camera frame. To retrieve the current camera settings, call the IDirect3DRMViewport::GetCamera method.

Viewing Frustum

The viewing frustum is a 3D volume in a scene positioned relative to the viewport's camera. Objects within the viewing frustum are visible. For perspective viewing, the viewing frustum is the volume of an imaginary pyramid that is between the front clipping plane and the back clipping plane.

The camera is at the tip of the pyramid, and its z-axis runs from the tip of the pyramid to the center of the pyramid's base. The front clipping plane is a distance D from the camera, and the back clipping plane is a distance F from the front clipping plane. An application can set and retrieve these values by using the IDirect3DRMViewport::SetFront, IDirect3DRMViewport::SetBack, IDirect3DRMViewport::GetFront, and IDirect3DRMViewport::GetBack methods. The height of the front clipping plane is 2h and defines the field of view. An application can set and retrieve the value of h by using the IDirect3DRMViewport::SetField and IDirect3DRMViewport::GetField methods.

The angle of view, A, is defined by the following equation, which can be used to calculate a value for h when a particular camera angle is desired:

The viewing frustum is a pyramid only for perspective viewing. For orthographic viewing, the viewing frustum is cuboid. These viewing types (or projection types) are defined by the D3DRMPROJECTIONTYPE enumerated type and used by the IDirect3DRMViewport::GetProjection and IDirect3DRMViewport::SetProjection methods.

Transformations

To render objects with 3D coordinates in a 2D window, the object must be transformed into the camera's frame. A projection matrix is then used to give a four-element homogeneous coordinate [x y z w], which is used to derive a three-element coordinate [x/w y/w z/w], where [x/w y/w] is the coordinate to be used in the window and z/w is the depth, ranging from 0 at the front clipping plane to 1 at the back clipping plane. The projection matrix is a combination of a perspective transformation followed by a scaling and translation to scale the objects into the window.

The following matrix is the projection matrix. In these formulas, h is the half-height of the viewing frustum, F is the position in z-coordinates of the back clipping plane, and D is the position in z-coordinates of the front clipping plane:

The following matrix is the window-scaling matrix. (The scales are dependent on the size and position of the window.) In these formulas, s is the window-scaling factor and o is the window origin:

The following matrix is the viewing matrix. This is a combination of the projection matrix and window matrix, or the dot product of P and W:

The scaling factors and origin sx, sy, ox, and oy are chosen so that the region [-h -h D] to [h h D] fits exactly into either the window's height or the window's width, whichever is larger.

The application can use the IDirect3DRMViewport::Transform and IDirect3DRMViewport::InverseTransform methods to transform vectors to screen coordinates from world coordinates and vice versa. An application can use these methods to support dragging, as shown in the following example:

/*

 * Drag a frame by [delta_x delta_y] pixels in the view.

 */

void DragFrame(LPDIRECT3DRMVIEWPORT view,

    LPDIRECT3DRMFRAME frame,

    LPDIRECT3DRMFRAME scene,

    int delta_x, int delta_y)

{

    D3DVECTOR p1;

    D3DRMVECTOR4D p2;

    frame->GetPosition(scene, &p1);

    view->Transform(&p2, &p1);

    p2.x += delta_x * p2.w;

    p2.y += delta_y * p2.w;

    view->InverseTransform(&p1, &p2);

    frame->SetPosition(scene, p1.x, p1.y, p1.z);

}

An application uses the viewport transformation to ensure that the distance by which the object is moved in world coordinates is scaled by the object's distance from the camera to account for perspective. Note that the result from IDirect3DRMViewport::Transform is a four-element homogeneous vector. This avoids the problems associated with coordinates being scaled by an infinite amount near the camera's position.

The viewport projection matrix produces a well-defined 3D coordinate only for points inside the viewing frustum. For a homogeneous point [x y z w] after projection, this is true if the following equations hold:

Picking

Picking is the process of searching for visuals in the scene given a 2D coordinate in the viewport's window. An application can use the IDirect3DRMViewport::Pick method to retrieve either the closest object in the scene or a depth-sorted list of objects.


Direct3DRMVisual and Direct3DRMVisualArray

Visuals are objects that can be rendered in a scene. Visuals are visible only when they are added to a frame in that scene. An application can add a visual to a frame by using the IDirect3DRMFrame::AddVisual method. The frame provides the visual with position and orientation for rendering.

You should use the IDirect3DRMVisualArray interface to work with groups of visual objects; although there is a IDirect3DRMVisual COM interface, it has no methods.

The most common visual types are Direct3DRMMeshBuilder and Direct3DRMTexture objects.


Direct3DRMWrap

You can use a wrap to calculate texture coordinates for a face or mesh. To create a wrap, the application must specify a type, a reference frame, an origin, a direction vector, and an up vector. The application must also specify a pair of scaling factors and an origin for the texture coordinates.

Your application calls the IDirect3DRM::CreateWrap function to create an IDirect3DRMWrap interface. This interface has two unique methods: IDirect3DRMWrap::Apply, which applies a wrap to the vertices of the object, and IDirect3DRMWrap::ApplyRelative, which transforms the vertices of a wrap as it is applied.

The D3DRMMAPPING type includes the D3DRMMAP_WRAPU and D3DRMMAP_WRAPV flags. These flags determine how the rasterizer interprets texture coordinates. The rasterizer always interpolates the shortest distance between texture coordinates—that is, a line. The path taken by this line, and the valid values for the u- and v-coordinates, varies with the use of the wrapping flags. If either or both flags is set, the line can wrap around the texture edge in the u or v direction, as if the texture had a cylindrical or toroidal topology.

•	In flat wrapping mode, in which neither of the wrapping flags is set, the plane specified by the u- and v-coordinates is an infinite tiling of the texture. In this case, values greater than 1.0 are valid for u and v. The shortest line between (0.1, 0.1) and (0.9, 0.9) passes through (0.5, 0.5).

•	If either D3DRMMAP_WRAPU or D3DRMMAP_WRAPV is set, the texture is a cylinder with an infinite length and a circumference of 1.0. Texture coordinates greater than 1.0 are valid only in the dimension that is not wrapped. The shortest distance between texture coordinates varies with the wrapping flag; if D3DRMMAP_WRAPU is set, the shortest line between (0.1, 0.1) and (0.9, 0.9) passes through (0, 0.5).

•	If both D3DRMMAP_WRAPU and D3DRMMAP_WRAPV are set, the texture is a torus. Because the system is closed, texture coordinates greater that 1.0 are invalid. The shortest line between (0.1, 0.1) and (0.9, 0.9) passes through (0, 0).

Although texture coordinates that are outside the valid range may be truncated to valid values, this behavior is not defined.

Typically, applications set a wrap flag for cylindrical wraps when the intersection of the texture edges does not match the edges of the face; applications do not set a wrap flag when more than half of a texture is applied to a single face.


Wrapping Types

There are four wrapping types:

•	Flat

•	Cylindrical

•	Spherical

•	Chrome

This section describes these wrapping types. In the examples, the direction vector (the v vector) lies along the z-axis, and the up vector (the u vector) lies along the y-axis, with the origin at [0 0 0].

Flat

The flat wrap conforms to the faces of an object as if the texture were a piece of rubber that was stretched over the object.

The [u v] coordinates are derived from a vector [x y z] by using the following equations:

u=sux–ou
v=svy–ov
In these formulas, s is the window-scaling factor and o is the window origin. The application should choose a pair of scaling factors and offsets that map the ranges of x and y to the range from 0 to 1 for u and v.

Cylindrical

The cylindrical wrap treats the texture as if it were a piece of paper that is wrapped around a cylinder so that the left edge is joined to the right edge. The object is then placed in the middle of the cylinder and the texture is deformed inward onto the surface of the object.

For a cylindrical texture map, the effects of the various vectors are shown in the following illustration.

The direction vector specifies the axis of the cylinder, and the up vector specifies the point on the outside of the cylinder where u equals 0. To calculate the texture [u v] coordinates for a vector [x y z], the system uses the following equations:

Typically, u would be left unscaled and v would be scaled and translated so that the range of z maps to the range from 0 to 1 for v.

Spherical

For a spherical wrap, the u-coordinate is derived from the angle that the vector [x y 0] makes with the x-axis (as in the cylindrical map) and the v-coordinate from the angle that the vector [x y z] makes with the z-axis. Note that this mapping causes distortion of the texture at the z-axis.

This translates to the following equations:

The scaling factors and texture origin will often not be needed here as the unscaled range of u and v is already 0 through 1.

Chrome

A chrome wrap allocates texture coordinates so that the texture appears to be reflected onto the objects. The chrome wrap takes the reference frame position and uses the vertex normals in the mesh to calculate reflected vectors. The texture u- and v-coordinates are then calculated from the intersection of these reflected vectors with an imaginary sphere that surrounds the mesh. This gives the effect of the mesh reflecting whatever is wrapped on the sphere.


Direct3D Retained-Mode Tutorial

To create a Windows-based Direct3D Retained-Mode application, you set up the features of two different environments: the devices, viewports, and color capabilities of the Windows environment, and the models, textures, lights, and positions of the virtual environment. This section describes some simple Retained-Mode sample code that is part of this SDK.


Setting up the Windows Environment

The Rmmain.cpp file in the samples provded with this SDK is used as a basis for all of the Retained-Mode samples. This file contains the standard Windows framework of initialization, setting up a message loop, and creating a window procedure for message processing, but it also does some work that is specific to Direct3D Retained-Mode applications:

•	It enumerates the current Direct3D device drivers. This is described in the Enumerating Direct3D Device Drivers section.

•	It creates the Retained-Mode API, the scene and camera frames, and a DirectDrawClipper object. This is described in the Initialization section.

•	It creates a Direct3DRM device and viewport. This is described in the Creating a Direct3DRM Device and Viewport section.

•	It sets the rendering quality, dithering flag, texture quality, shades, default texture colors, and default texture shades. This is described in the Setting the Render State section.

•	It calls a locally defined BuildScene function to set up the lights and visuals in a scene. This is described in the Setting Up the Virtual Environment section.

•	It renders the scene. This is described in the Rendering into a Viewport section.

•	It makes the mouse status available to sample applications. This is described in the OverrideDefaults and ReadMouse section.


Enumerating Direct3D Device Drivers

Rmmain.cpp calls the locally defined InitApp function as its first action inside the WinMain function, and it fails if InitApp is not successful. InitApp creates the window and initializes all objects that are required to begin rendering a 3D scene.

After performing some standard tasks in the initialization of a Windows application and initializing global variables to acceptable default settings, InitApp verifies that Direct3D device drivers are present by calling the locally defined EnumDrivers function.

EnumDrivers sets up a callback function that examines each of the drivers in the system and picks the best one for the application's needs. This is not the easiest or even the best way to find Direct3D device drivers, however. Instead of setting up an enumeration routine, most applications will allow the system to automatically enumerate the current drivers by calling the IDirect3DRM::CreateDeviceFromClipper method and specifying NULL for the lpGUID parameter. This is the recommended way to create a Retained-Mode device because it always works, even if the user installs new hardware. When you use this method and both a hardware and a software device meet the default requirements, the system always retrieves the hardware device. An application should enumerate devices instead of specifying NULL for lpGUID only if it has unusual requirements.

EnumDrivers first calls the DirectDrawCreate function to create a DirectDraw object and then calls IDirectDraw::QueryInterface to retrieve an interface to Direct3D. The first parameter of this method is the interface identifier (IID) that identifies the IDirect3D COM interface. These identifiers are defined in the D3d.h header file. Each identifier is in the form IID_InterfaceName. For example, the IID for the IDirect3DRMTexture interface is IID_IDirect3DRMTexture.

After creating the Direct3D interface, EnumDrivers calls the IDirect3D::EnumDevices method to enumerate the Direct3D drivers. The first parameter to this method is a D3DENUMDEVICESCALLBACK callback function, in this case named enumDeviceFunc. The second parameter is a pointer to the myglobs structure, which contains the global variables Rmmain.cpp uses to set up the 3D environment. The CurrDriver member of the myglobs structure is simply an integer indicating the number of the Direct3D driver currently being used. The application initializes this value to -1 before calling IDirect3D::EnumDevices; the callback function checks this value to find out whether the driver being enumerated is the first valid driver.

static BOOL EnumDrivers(HWND win)

{

LPDIRECTDRAW lpDD;

LPDIRECT3D lpD3D;

HRESULT rval;

HMENU hmenu;

rval = DirectDrawCreate(NULL, &lpDD, NULL);

rval = lpDD->QueryInterface(IID_IDirect3D, (void**) &lpD3D);

myglobs.CurrDriver = -1;

rval = lpD3D->EnumDevices(enumDeviceFunc, &myglobs.CurrDriver);

lpD3D->Release();

lpDD->Release();

// Code omitted here that adds the driver names to the File menu.

return TRUE;

}

The enumDeviceFunc (D3DENUMDEVICESCALLBACK) callback function records each usable Direct3D device driver's name and globally unique identifier (GUID) and chooses a driver. The following code sample shows the enumDeviceFunc callback function. First, this callback function creates a D3DDEVICEDESC structure and copies the input lpContext parameter to a parameter called lpStartDriver. (The lpContext parameter is application-defined data—it can be any data the application requires.) The fourth parameter passed to enumDeviceFunc is a pointer to a D3DDEVICEDESC structure describing the hardware; the function uses the dcmColorModel member of this structure to determine whether it should examine the description of the hardware or the description of the hardware emulation layer (HEL). Any driver that cannot support the current bit-depth is skipped. The current driver's GUID and name are copied into the myglobs structure. Then the enumDeviceFunc callback function performs a few tests to compare the driver being enumerated against the driver stored as lpStartDriver. Whenever the driver being enumerated is implemented in hardware or uses the RGB instead of the monochromatic color model, that driver becomes the new lpStartDriver.

Finally, enumDeviceFunc increments the variable that counts the number of drivers. If this count exceeds the maximum, it returns D3DENUMRET_CANCEL to cancel the enumeration. Otherwise, it returns D3DENUMRET_OK to continue the enumeration.

static HRESULT WINAPI enumDeviceFunc(

    LPGUID lpGuid, LPSTR lpDeviceDescription, LPSTR lpDeviceName,

    LPD3DDEVICEDESC lpHWDesc, LPD3DDEVICEDESC lpHELDesc,

    LPVOID lpContext)

{

static BOOL hardware = FALSE; // Current start driver is hardware

static BOOL mono = FALSE;     // Current start driver is mono light

LPD3DDEVICEDESC lpDesc;

int *lpStartDriver = (int *)lpContext;

// Decide which device description we should consult.

lpDesc = lpHWDesc->dcmColorModel ? lpHWDesc : lpHELDesc;

// If this driver cannot render in the current display bit depth, skip

// it and continue with the enumeration.

if (!(lpDesc->dwDeviceRenderBitDepth & BPPToDDBD(myglobs.BPP)))

    return D3DENUMRET_OK;

// Record this driver's info.

memcpy(&myglobs.DriverGUID[myglobs.NumDrivers], lpGuid, sizeof(GUID));

strcpy(&myglobs.DriverName[myglobs.NumDrivers][0], lpDeviceName);

// Choose hardware over software, RGB lights over mono lights.

if (*lpStartDriver == -1) {

    // This is the first valid driver.

    *lpStartDriver = myglobs.NumDrivers;

    hardware = lpDesc == lpHWDesc ? TRUE : FALSE;

    mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ? TRUE : FALSE;

} else if (lpDesc == lpHWDesc && !hardware) {

    // This driver is hardware and start driver is not.

    *lpStartDriver = myglobs.NumDrivers;

    hardware = lpDesc == lpHWDesc ? TRUE : FALSE;

    mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ? TRUE : FALSE;

} else if ((lpDesc == lpHWDesc && hardware ) || (lpDesc == lpHELDesc

                         && !hardware)) {

    if (lpDesc->dcmColorModel == D3DCOLOR_MONO && !mono) {

    // This driver and start driver are the same type, and this

    // driver is mono while start driver is not.

    *lpStartDriver = myglobs.NumDrivers;

    hardware = lpDesc == lpHWDesc ? TRUE : FALSE;

    mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ? TRUE : FALSE;

    }

}

myglobs.NumDrivers++;

if (myglobs.NumDrivers == MAX_DRIVERS)

    return (D3DENUMRET_CANCEL);

return (D3DENUMRET_OK);

}

When EnumDrivers function returns, it calls the IDirect3D::Release and IDirectDraw::Release methods to decrease the reference count of these COM objects. Every time an application calls the Release method on an object, the reference count for that object is reduced by 1. The system deallocates the object when its reference count reaches 0.

Whenever Rmmain.cpp calls a COM method, the return value is checked and the function fails if the method does not succeed. This error-checking has been omitted from the samples in this section for the sake of brevity. Sometimes the error-checking code calls the D3DRMErrorToString function (which is implemented in Rmerror.c in the same directory as Rmmain.cpp). This function simply maps an HRESULT error value to an explanatory string and returns the string.

If any COM interfaces have already been successfully created when a method fails, the error-checking code calls the Release method for that interface before returning FALSE.


Initialization

After enumerating the Direct3D device drivers, the InitApp function in Rmmain.cpp calls the Direct3DRMCreate function to create the Retained-Mode API:

LPDIRECT3DRM lpD3DRM;

HRESULT rval;

rval = Direct3DRMCreate(&lpD3DRM);

The sample then uses the Direct3DRM object to create the master reference frame (the "scene") and the camera frame by calling the IDirect3DRM::CreateFrame method. After creating the camera frame, this sample calls the IDirect3DRMFrame::SetPosition method to set its position.

rval = lpD3DRM->CreateFrame(NULL, &myglobs.scene);

rval = lpD3DRM->CreateFrame(myglobs.scene, &myglobs.camera);

// Set the position of the camera frame.

rval = myglobs.camera->SetPosition(myglobs.scene, D3DVAL(0.0),

    D3DVAL(0.0), D3DVAL(0.0));

The scene and camera members of the myglobs structure have the same type: LPDIRECT3DRMFRAME. The D3DVAL macro creates a value whose type is D3DVALUE from a supplied floating-point number.

Next, InitApp creates a DirectDraw clipper object by calling the DirectDrawCreateClipper function, and associates the window with the clipper object by calling the IDirectDrawClipper::SetHWnd method. This clipper object is subsequently used to create the Direct3D Windows device. The advantage of using a clipper object to create the device is that in this case DirectDraw does the clipping automatically.

LPDIRECTDRAWCLIPPER lpDDClipper;

HWND win;

rval = DirectDrawCreateClipper(0, &lpDDClipper, NULL);

rval = lpDDClipper->SetHWnd(0, win);

InitApp uses the DirectDraw clipper object and the Direct3D driver retrieved by the EnumDrivers function in a call to the locally defined CreateDevAndView function. CreateDevAndView is discussed in the following section, Creating a Direct3DRM Device and Viewport.

GetClientRect(win, &rc);

if (!CreateDevAndView(lpDDClipper, myglobs.CurrDriver,

        rc.right, rc.bottom)) {

    return FALSE;

}

// Create the scene to be rendered by calling this sample's BuildScene.

if (!BuildScene(myglobs.dev, myglobs.view, myglobs.scene,

    myglobs.camera))

    return FALSE;

// Ready to render.

myglobs.bInitialized = TRUE;

// Display the window.

ShowWindow(win, cmdshow);

UpdateWindow(win);

return TRUE;


Creating a Direct3DRM Device and Viewport

The InitApp function calls the locally defined CreateDevAndView function to create a Direct3DRM device and viewport. This function's parameters are a pointer to a DirectDrawClipper object, the number identifying the current driver, and the width and height of the current window's client rectangle.

After verifying that the window dimensions are valid, CreateDevAndView calls the IDirect3DRM::CreateDeviceFromClipper method to create a Direct3DRM device (stored in the dev member of the myglobs structure).

static BOOL CreateDevAndView(LPDIRECTDRAWCLIPPER lpDDClipper,

    int driver, int width, int height)

{

HRESULT rval;

if (!width || !height) {

    Msg("Cannot create a D3DRM device with invalid window dimensions.");

    return FALSE;

}

// Create the D3DRM device from this window and using the specified D3D

// driver.

rval = lpD3DRM->CreateDeviceFromClipper(lpDDClipper,

    &myglobs.DriverGUID[driver], width, height, &myglobs.dev);

CreateDevAndView uses the device it just created and the camera frame in a call to the IDirect3DRM::CreateViewport method that creates a Direct3DRM viewport. The width and height of the viewport are retrieved by calling the IDirect3DRMDevice::GetWidth and IDirect3DRMDevice::GetHeight methods. The viewport is stored in the view member of the myglobs structure. After creating the viewport, the code sets its background depth to a large number by calling the IDirect3DRMViewport::SetBack method.

width = myglobs.dev->GetWidth();

height = myglobs.dev->GetHeight();

rval = lpD3DRM->CreateViewport(myglobs.dev, myglobs.camera, 0, 0, width,

    height, &myglobs.view);

rval = myglobs.view->SetBack(D3DVAL(5000.0));

Finally, CreateDevAndView calls the locally defined SetRenderState function to set the rendering quality, fill mode, lighting state, and color shade. This function is described in Setting the Render State.

// Set the rendering quality, fill mode, lighting state and

// color shade information.

if (!SetRenderState())

    return FALSE;

return TRUE;

}


Setting the Render State

The InitApp function calls CreateDevAndView, which in turn calls the SetRenderState function to set the rendering quality, fill mode, lighting state, and color shade. Rmmain.cpp calls the SetRenderState function whenever the render state may have changed; for example, whenever the user changes the fill or lighting modes.

SetRenderState calls the IDirect3DRMDevice::SetQuality method to set the rendering quality, IDirect3DRMDevice::SetDither to set the dithering flag, and IDirect3DRMDevice::SetTextureQuality to set the texture quality. Each of these methods has a Get counterpart, which SetRenderState calls before setting any values. If the current value in the myglobs structure is the same as the value retrieved by the Get method, the function takes no further action.

BOOL SetRenderState(void)

{

HRESULT rval;

if (myglobs.dev->GetQuality() != myglobs.RenderQuality) {

    rval = myglobs.dev->SetQuality(myglobs.RenderQuality);

}

if (myglobs.dev->GetDither() != myglobs.bDithering) {

    rval = myglobs.dev->SetDither(myglobs.bDithering);

}

if (myglobs.dev->GetTextureQuality() != myglobs.TextureQuality) {

    rval = myglobs.dev->SetTextureQuality(myglobs.TextureQuality);

}

Now SetRenderState sets the shades, default texture colors, and default texture shades based on the current number of bits per pixel.

•	If the device supports only one bit per pixel, SetRenderState uses IDirect3DRMDevice::SetShades to set the number of shades to four; this is the number of shades in a ramp of colors used for shading. SetRenderState also calls IDirect3DRM::SetDefaultTextureShades to set the default number of shades for textures.

•	If the device supports 16 bits per pixel, SetRenderState calls an additional method: IDirect3DRM::SetDefaultTextureColors. This method sets the default number of colors used in textures.

•	If the device supports 24 or 32 bits per pixel, SetRenderState calls the same methods as for 16 bits per pixel. The only difference is that in this case it sets the shades and default texture shades to 256 instead of 32.

switch (myglobs.BPP) {

    case 1:

    if (FAILED(myglobs.dev->SetShades(4)))

        goto shades_error;

    if (FAILED(lpD3DRM->SetDefaultTextureShades(4)))

        goto shades_error;

    break;

    case 16:

    if (FAILED(myglobs.dev->SetShades(32)))

        goto shades_error;

    if (FAILED(lpD3DRM->SetDefaultTextureColors(64)))

        goto shades_error;

    if (FAILED(lpD3DRM->SetDefaultTextureShades(32)))

        goto shades_error;

    break;

    case 24:

    case 32:

    if (FAILED(myglobs.dev->SetShades(256)))

        goto shades_error;

    if (FAILED(lpD3DRM->SetDefaultTextureColors(64)))

        goto shades_error;

    if (FAILED(lpD3DRM->SetDefaultTextureShades(256)))

        goto shades_error;

    break;

}

return TRUE;

shades_error:

Msg("A failure occurred while setting color shade information.\n");

return FALSE;

}

The FAILED macro is defined as follows in the Winerror.h header file:

#define FAILED(Status) ((HRESULT)(Status)<0)


Setting Up the Virtual Environment

After the InitApp function has created the window, enumerated the Direct3D drivers, created the Retained-Mode API, created the scene and camera frames, created a DirectDrawClipper object, and created the Direct3D device and viewport, it calls a locally defined BuildScene function to build the scene. Each of the Direct3D samples in this SDK includes its own BuildScene function. These implementations of BuildScene vary depending on the capabilities being demonstrated by the sample.

This section discusses the simplest implementation of BuildScene in this SDK: the version in Egg.c. In this module, BuildScene performs the following tasks:

•	Sets up the lights. This is described in the Setting Up the Lights section.

•	Adds a mesh to the scene and sets up the position, rotation, and orientation of its frame. This is described in the Loading and Adding a Mesh section.

•	Releases the objects that it has created. This is described in the Releasing the Direct3DRM Objects section.

•	Overrides several of the default settings from Rmmain.cpp. This is described in the OverrideDefaults and ReadMouse section.


Setting Up the Lights

The BuildScene function implements two light sources: an ambient light and a directional light. An ambient light casts a uniform light over the entire scene. The position and orientation of its containing frame are ignored. A directional light, on the other hand, has direction but no position. It is attached to a frame but appears to illuminate all objects with equal intensity, as if it were at an infinite distance from each object.

First the BuildScene function creates a frame for the directional light and calls the IDirect3DRMFrame::SetPosition method to set its position in the scene. Then it calls the IDirect3DRM::CreateLightRGB method to create a directional light source. The IDirect3DRMFrame::AddLight method adds the directional light to the lighting frame. Then the IDirect3DRMFrame::SetRotation method causes the lighting frame to rotate.

After setting up the directional light, BuildScene creates a much dimmer ambient light source, again by calling IDirect3DRM::CreateLightRGB. Because ambient lights are not affected by the position and orientation of their containing frame, the BuildScene function specifies the frame for the entire scene in the call to IDirect3DRMFrame::AddLight that adds the ambient light.

LPDIRECT3DRMFRAME lights = NULL;

LPDIRECT3DRMLIGHT light1 = NULL;

LPDIRECT3DRMLIGHT light2 = NULL;

    .

    .

    .

if (FAILED(lpD3DRM->lpVtbl->CreateFrame(lpD3DRM, scene, &lights)))

    goto generic_error;

if (FAILED(lights->lpVtbl->SetPosition(lights, scene, D3DVAL(5),

        D3DVAL(5), -D3DVAL(1))))

    goto generic_error;

if (FAILED(lpD3DRM->lpVtbl->CreateLightRGB(lpD3DRM,

        D3DRMLIGHT_DIRECTIONAL, D3DVAL(0.9),

        D3DVAL(0.8), D3DVAL(0.7), &light1)))

    goto generic_error;

if (FAILED(lights->lpVtbl->AddLight(lights, light1)))

    goto generic_error;

if (FAILED(lights->lpVtbl->SetRotation(lights, scene, D3DVAL(0),

        D3DVAL(1), D3DVAL(1), D3DVAL(-0.02))))

    goto generic_error;

if (FAILED(lpD3DRM->lpVtbl->CreateLightRGB(lpD3DRM, D3DRMLIGHT_AMBIENT,

        D3DVAL(0.1), D3DVAL(0.1), D3DVAL(0.1), &light2)))

    goto generic_error;

if (FAILED(scene->lpVtbl->AddLight(scene, light2)))

    goto generic_error;

The generic_error label identifies a place in the code where Egg.c displays a message box with an error value, releases any created COM objects, and returns FALSE from the BuildScene function.


Loading and Adding a Mesh

The BuildScene function in Egg.c loads a simple egg-shaped mesh into the scene and rotates the frame containing the mesh.

A call to the IDirect3DRM::CreateMeshBuilder method retrieves the IDirect3DRMMeshBuilder COM interface. BuildScene uses this interface for only one call before releasing it; it calls the IDirect3DRMMeshBuilder::Load method to load a mesh file named Egg.x.

Next, BuildScene calls IDirect3DRM::CreateFrame to create a frame for the mesh, and then it calls IDirect3DRMFrame::AddVisual to add the mesh to that frame.

Then, BuildScene sets the position and orientation of the camera frame in relation to the scene frame by calling the IDirect3DRMFrame::SetPosition and IDirect3DRMFrame::SetOrientation methods. Finally, it rotates the mesh frame in relation to the scene frame by calling the IDirect3DRMFrame::SetRotation method.

LPDIRECT3DRMMESHBUILDER egg_builder = NULL;

LPDIRECT3DRMFRAME egg = NULL;

    .

    .

    .

if (FAILED(lpD3DRM->lpVtbl->CreateMeshBuilder(lpD3DRM, &egg_builder)))

    goto generic_error;

rval = egg_builder->lpVtbl->Load(egg_builder, "egg.x", NULL,

    D3DRMLOAD_FROMFILE, NULL, NULL);

if (FAILED(lpD3DRM->lpVtbl->CreateFrame(lpD3DRM, scene, &egg)))

    goto generic_error;

if (FAILED(egg->lpVtbl->AddVisual(

        egg, (LPDIRECT3DRMVISUAL)egg_builder)))

    goto generic_error;

if (FAILED(camera->lpVtbl->SetPosition(

        camera, scene, D3DVAL(0), D3DVAL(0), -D3DVAL(10))))

    goto generic_error;

if (FAILED(camera->lpVtbl->SetOrientation(

        camera, scene, D3DVAL(0), D3DVAL(0), D3DVAL(1), D3DVAL(0),

        D3DVAL(1), D3DVAL(0))))

    goto generic_error;

if (FAILED(egg->lpVtbl->SetRotation(

        egg, scene, D3DVAL(0), D3DVAL(1), D3DVAL(1), D3DVAL(0.02))))

    goto generic_error;


Releasing the Direct3DRM Objects

The last task performed by the BuildScene function in Egg.c is to release the Direct3DRM objects it creates—the frames for the mesh and lights, the mesh itself, and the two lights:

RELEASE(egg);

RELEASE(lights);

RELEASE(egg_builder);

RELEASE(light1);

RELEASE(light2);

The RELEASE macro calls the Release method for the appropriate interface. It is defined in C++ and C versions in the Rmdemo.h header file. The syntax of the C version looks like this:

#define RELEASE(x) if (x != NULL) {x->lpVtbl->Release(x); x = NULL;}

Rmmain.cpp also releases any objects it creates, in its CleanUpAndPostQuit function. The code calls CleanUpAndPostQuit whenever initialization has been completed and the application must exit: when a WM_QUIT message is received, when the user chooses the Exit command, on fatal errors, and so on.

void CleanUpAndPostQuit(void)

{

myglobs.bInitialized = FALSE;

RELEASE(myglobs.scene);

RELEASE(myglobs.camera);

RELEASE(myglobs.view);

RELEASE(myglobs.dev);

RELEASE(lpD3DRM);

RELEASE(lpDDClipper);

myglobs.bQuit = TRUE;

}


OverrideDefaults and ReadMouse

Samples can use the OverrideDefaults function with Rmmain.cpp, in addition to the standard BuildScene function. Egg.c includes an implementation of OverrideDefaults that simply sets the bNoTextures member to TRUE in the Defaults structure (defined in Rmdemo.h) and changes the name of the application:

void OverrideDefaults(Defaults *defaults)

{

    defaults->bNoTextures = TRUE;

    strcpy(defaults->Name, "Egg Direct3DRM Example");

}

Rmmain.cpp includes another function, ReadMouse, that samples can use to retrieve the mouse status. For an example of how this function is used, see the Quat.c sample in this SDK.

void ReadMouse(int* b, int* x, int* y)

{

    *b = myglobs.mouse_buttons;

    *x = myglobs.mouse_x;

    *y = myglobs.mouse_y;

}


Rendering into a Viewport

The Rmmain.cpp file calls the RenderLoop function as part of the message loop in the WinMain function. The RenderLoop function performs a few simple tasks:

•	Calls IDirect3DRMFrame::Move to apply the rotations and velocities for all frames in the hierarchy.

•	Calls IDirect3DRMViewport::Clear to clear the current viewport, setting it to the current background color.

•	Calls IDirect3DRMViewport::Render to render the current scene into the current viewport.

•	Calls IDirect3DRMDevice::Update to copy the rendered image to the display.

static BOOL RenderLoop()

{

HRESULT rval;

rval = myglobs.scene->Move(D3DVAL(1.0));

rval = myglobs.view->Clear();

rval = myglobs.view->Render(myglobs.scene);

rval = myglobs.dev->Update();

return TRUE;

}


Immediate-Mode Overview


About Immediate Mode

This section describes Direct3D's Immediate Mode, Microsoft's low-level 3D API. Direct3D's Immediate Mode is ideal for developers who need to port games and other high-performance multimedia applications to the Microsoft Windows operating system. Immediate Mode is a device-independent way for applications to communicate with accelerator hardware at a low level. Direct3D's Retained Mode is built on top of Immediate Mode.

Developers who use Immediate Mode instead of Retained Mode are typically experienced in high-performance programming issues, and may also be experienced in 3D graphics. Even if this is the case for you, you should read A Technical Foundation for 3D Programming. This section discusses implementation details of Direct3D that you need to know to work effectively with the system. The overall Direct3D architecture is described in Direct3D Architecture; this is essential reading for Immediate-Mode developers. If you want an overview of Immediate Mode, you should read Introduction to Direct3D Immediate-Mode Objects. Your best source of information about Immediate Mode, however, is probably the sample code included with this SDK; it illustrates how to put Direct3D's Immediate Mode to work in real-world applications.

This section is not an introduction to programming with Direct3D's Immediate Mode; for this information, see Direct3D Immediate-Mode Tutorial.


Introduction to Direct3D Immediate-Mode Objects

Direct3D's Immediate Mode consists of API elements that create objects, fill them with data, and link them together. Direct3D's Retained Mode is built on top of Immediate Mode. For a description of the overall organization of the system and the organization of Immediate Mode in particular, see Direct3D Architecture.

The following table shows the eight object types in Immediate Mode, their Component Object Model (COM) interfaces, and a description of each:

Object type	COM interface and description
Interface	IDirect3D
	COM interface object
Device	IDirect3DDevice
	Hardware device
Texture	IDirect3DTexture
	DirectDraw surface containing an image
Material	IDirect3DMaterial
	Surface properties, such as color and texture
Light	IDirect3DLight
	Light source
Viewport	IDirect3DViewport
	Screen region to draw to
Matrix	IDirect3DDevice
	4-by-4 homogeneous transformation matrix
ExecuteBuffer	IDirect3DExecuteBuffer
	List of vertex data and instructions about how to render it
Rendering is done by using execute buffers. These buffers contain vertex data and a list of opcodes that, when interpreted, instruct the rendering engine to produce an image. The execute buffer COM object contains only pointers and some descriptions of the format of the buffer. The contents of the buffer are dynamically allocated and can reside in the memory of the graphics card.

Each of the objects can effectively exist in one or more of the following forms:

•	A COM object.

•	A structure exposed to the developer that effectively contains a copy of the data in the COM object. This form is typically used to copy data into or out of the actual COM object.

•	A handle. In this case, the data resides on the hardware and can be manipulated by it.

The following table shows the forms in which each of the Direct3D objects can exist:

	COM interface	Structure	Handle
Device	x
Texture	x	x	x
Material	x	x	x
Light	x	x
Viewport	x
Matrix		x	x
ExecuteBuffer	x	x


Direct3D Object Types

This section describes Direct3D object types. An application creates Direct3D objects roughly in the following order:

Direct3D objects
Device objects
Texture objects
Material objects
Light objects
Viewport objects
Execute-buffer objects


Direct3D Interface Objects

You can create a Direct3D interface object by calling the IDirectDraw::QueryInterface method, as follows:

lpDirectDraw->QueryInterface(

    IID_IDirect3D,  // IDirect3D interface ID

    lpD3D);         // Address of a Direct3D object

The object referred to by an IDirect3D interface contains a list of viewports, lights, materials, and devices. You can use the methods of the IDirect3D interface to create other objects or to find Direct3D devices.


Direct3D Device Objects

You can create a Direct3D device object by calling the IDirectDrawSurface::QueryInterface method for a backbuffer surface. The following example calls the IDirectDraw::CreateSurface and IDirectDrawSurface::GetAttachedSurface methods to retrieve the backbuffer surface.

lpDirectDraw->CreateSurface(

    lpDDSurfDesc,   // Address of a DDSURFACEDESC structure

    lpFrontBuffer,  // Address of a DIRECTDRAWSURFACE structure

    pUnkOuter);     // NULL

lpFrontBuffer->GetAttachedSurface(

    &ddscaps,         // Address of a DDSCAPS structure

    &lpBackBuffer);   // Address of a DIRECTDRAWSURFACE structure

lpBackBuffer->QueryInterface(

    GUIDforID3DDevice,   // ID for IDirect3DDevice interface

    lpD3DDevice);        // Address of a DIRECT3DDEVICE object

The first parameter of the call to the IDirectDrawSurface::QueryInterface method for the back buffer is the globally unique identifier (GUID) for the IDirect3DDevice interface. You can retrieve this GUID by calling the IDirect3D::EnumDevices method; the system supplies the GUID when it calls the D3DENUMDEVICESCALLBACK callback function you supply in the call to IDirect3D::EnumDevices.

A Direct3D device object resides on (or "is owned by") the interface list and has its own list of execute buffers and viewports. It also has a list of textures and materials, each of which points both to the next texture or material in the list and back to the device. For more information about this hierarchy, see Object Connectivity.

The methods of the IDirect3DDevice interface report hardware capabilities, maintain a list of viewports, manipulate matrix objects, and execute execute-buffer objects.

Matrices appear to you only as handles. You can create a Direct3D matrix by calling the IDirect3DDevice::CreateMatrix method, and you can set the contents of the matrix by calling the IDirect3DDevice::SetMatrix method. Matrix handles are used in execute buffers.


Direct3D Texture Objects

A texture is a rectangular array of colored pixels. (The rectangle does not necessarily have to be square, although the system deals most efficiently with square textures.) You can use textures for texture-mapping faces, in which case their dimensions must be powers of two. If your application uses the RGB color model, you can use 8-, 24-, and 32-bit textures. If you use the monochromatic (or ramp) color model, however, you can use only 8-bit textures.

You can retrieve an interface to a Direct3D texture object by calling the IDirectDrawSurface::QueryInterface method and specifying IID_IDirect3DTexture. An IDirect3DTexture interface is actually an interface to a DirectDrawSurface object, not to a distinct Direct3D texture object. For more information about the relationship between textures in Direct3D and surfaces in DirectDraw, see Direct3D Texture Interface.

The following example demonstrates how to create an IDirect3DTexture interface and then how to load the texture by calling the IDirect3DTexture::GetHandle and IDirect3DTexture::Load methods.

lpDDS->QueryInterface(IID_IDirect3DTexture,

    lpD3DTexture);  // Address of a DIRECT3DTEXTURE object

lpD3DTexture->GetHandle(

    lpD3DDevice,    // Address of a DIRECT3DDEVICE object

    lphTexture);    // Address of a D3DTEXTUREHANDLE

lpD3DTexture->Load(

    lpD3DTexture);  // Address of a DIRECT3DTEXTURE object

Texture objects reside on the interface list and point both to the next texture in a device's list and back to their associated device or devices. (For more information about this hierarchy, see Object Connectivity.) The texture handle is used in materials and execute buffers, and as a z-buffer for a viewport. You can use the IDirect3DTexture interface to load and unload textures, retrieve handles, and track changes to palettes.

Texture Wrapping

The texture coordinates of each face define the region in the texture that is mapped onto that particular face. Your application can use a wrap to calculate texture coordinates. For more information, see Direct3DRMWrap.

Your application can use the D3DRENDERSTATE_WRAPU and D3DRENDERSTATE_WRAPV render states (from the D3DRENDERSTATETYPE enumerated type) to specify how the rasterizer should interpret texture coordinates. The rasterizer always interpolates the shortest distance between texture coordinates; that is, a line. The path taken by this line, and the valid values for the u- and v-coordinates, varies with the use of the wrapping flags. If either or both flags is set, the line can wrap around the texture edge in the u or v direction, as if the texture had a cylindrical or toroidal topology.

•	In flat wrapping mode, in which neither of the wrapping flags is set, the plane specified by the u- and v-coordinates is an infinite tiling of the texture. In this case, values greater than 1.0 are valid for u and v. The shortest line between (0.1, 0.1) and (0.9, 0.9) passes through (0.5, 0.5).

•	If either D3DRENDERSTATE_WRAPU or D3DRENDERSTATE_WRAPV is set, the texture is an infinite cylinder with a circumference of 1.0. Texture coordinates greater than 1.0 are valid only in the dimension that is not wrapped. The shortest distance between texture coordinates varies with the wrapping flag; if D3DRENDERSTATE_WRAPU is set, the shortest line between (0.1, 0.1) and (0.9, 0.9) passes through (0, 0.5).

•	If both D3DRENDERSTATE_WRAPU and D3DRENDERSTATE_WRAPV are set, the texture is a torus. Because the system is closed, texture coordinates greater that 1.0 are invalid. The shortest line between (0.1, 0.1) and (0.9, 0.9) passes through (0, 0).

Although texture coordinates that are outside the valid range may be truncated to valid values, this behavior is not defined.

Typically, applications set a wrap flag for cylindrical wraps when the intersection of the texture edges does not match the edges of the face, and do not set a wrap flag when more than half of a texture is applied to a single face.

For more information about wrapping, see Wrapping Types in the introduction to Direct3D Retained-Mode objects.

Texture Filtering and Blending

After a texture has been mapped to a surface, the texture elements (texels) of the texture rarely correspond to individual pixels in the final image. A pixel in the final image can correspond to a large collection of texels or to a small piece of a single texel. You can use texture filtering to specify how to interpolate texel values to pixels.

You can use the D3DRENDERSTATE_TEXTUREMAG and D3DRENDERSTATE_TEXTUREMIN render states (from the D3DRENDERSTATETYPE enumerated type) to specify the type of texture filtering to use.

The D3DRENDERSTATE_TEXTUREMAPBLEND render state allows you to specify the type of texture blending. Texture blending combines the colors of the texture with the color of the surface to which the texture is being applied. This can be an effective way to achieve a translucent appearance. Texture blending can produce unexpected colors; the best way to avoid this is to ensure that the color of the material is white. The texture-blending options are specified in the D3DTEXTUREBLEND enumerated type.

You can use the D3DRENDERSTATE_SRCBLEND and D3DRENDERSTATE_DSTBLEND render states to specify how colors in the source and destination are combined. The combination options (called blend factors) are specified in the D3DBLEND enumerated type.

Mipmaps

A mipmap is a sequence of textures, each of which is a progressively lower resolution, prefiltered representation of the same image. Mipmapping is a computationally low-cost way of improving the quality of rendered textures. Each prefiltered image, or level, in the mipmap is a power of two smaller than the previous level.

You can use mipmaps when texture-filtering by specifying the appropriate filter mode in the D3DTEXTUREFILTER enumerated type. To find out what kinds of mipmapping support are provided by a device, use the flags specified in the dwTextureFilterCaps member of the D3DPRIMCAPS structure.

For more information about how to use DirectDraw to create mipmaps, see Mipmaps.

Transparency and Translucency

As already mentioned, one method for achieving the appearance of transparent or translucent textures is by using texture blending. You can also use alpha channels and the D3DRENDERSTATE_BLENDENABLE render state (from the D3DRENDERSTATETYPE enumerated type).

A more straightforward approach to achieving transparency or translucency is to use DirectDraw's support for color keys. Color keys are colors or ranges of colors that can be part of either the source or destination of a blit or overlay operation. You can specify whether these colors should always or never be overwritten.

For more information about DirectDraw's support for color keys, see Color Keying.


Direct3D Material Objects

You can create an interface to a Direct3D material by calling the IDirect3D::CreateMaterial method. The following example demonstrates how to create an IDirect3DMaterial interface. Then it demonstrates how to set the material and retrieve its handle by calling the IDirect3DMaterial::SetMaterial and IDirect3DMaterial::GetHandle methods.

lpDirect3D->CreateMaterial(

    lplpDirect3DMaterial,  // Address of a new material

    pUnkOuter);            // NULL

lpDirect3DMaterial->SetMaterial(

    lpD3DMat);             // Address of a D3DMATERIAL structure

lpDirect3DMaterial->GetHandle(

    lpD3DDevice,           // Address of a DIRECT3DDEVICE object

    lpD3DMat);             // Address of a D3DMATERIAL structure

Material objects reside on the interface list and point both to the next material in a device's list and back to their associated device or devices. (For more information about this hierarchy, see Object Connectivity.) A material contains colors and may contain a texture handle. The material handle is used inside execute buffers or to set the background of a viewport. You can use the IDirect3DMaterial interface to get and set materials, retrieve handles, and reserve colors.


Direct3D Light Objects

You can create a Direct3D light object by calling the IDirect3D::CreateLight method. The following example demonstrates how to create an IDirect3DLight interface, and then it sets the light by calling the IDirect3DLight::SetLight method.

lpDirect3D->CreateLight(

    lplpDirect3DLight,  // Address of a new light

    pUnkOuter);         // NULL

lpDirect3DLight->SetLight(

    lpLight);    // Address of a D3DLIGHT structure

Light objects reside on the interface list and on a viewport list. You can use the IDirect3DLight interface to get and set lights.


Direct3D Viewport Objects

You can create a Direct3D viewport object by calling the IDirect3D::CreateViewport method. The following example demonstrates how to create an IDirect3DViewport interface. Then it demonstrates how to add the viewport to a device by calling the IDirect3DDevice::AddViewport method and how to set up the viewport by calling the IDirect3DViewport::SetViewport, IDirect3DViewport::SetBackground, and IDirect3DViewport::AddLight methods.

lpDirect3D->CreateViewport(

    lplpDirect3DViewport,  // Address of a new viewport

    pUnkOuter);            // NULL

lpD3DDevice->AddViewport(

    lpD3DViewport)         // Attach viewport to device

lpD3DViewport->SetViewport(

    lpData);               // Address of a D3DVIEWPORT structure that

                           // Sets the viewport's location on the screen

lpD3DViewport->SetBackground(

    lphMat);               // Address of a D3DMATERIALHANDLE for

                           // background

lpD3DViewport->AddLight(

    lpD3DLight);           // Address of a light object

Viewport objects reside on the interface and device lists. The object maintains a list of lights as well as screen data, and it may have a material handle and a texture handle for the background. You can use the IDirect3DViewport interface to get and set backgrounds and viewports, add and delete lights, and transform vertices.


Direct3D Execute-Buffer Objects

Execute buffers contain a vertex list followed by an instruction stream. The instruction stream consists of operation codes, or opcodes, and the data that modifies those opcodes. For a description of execute buffers, see Execute Buffers.

You can create a Direct3D execute-buffer object by calling the IDirect3DDevice::CreateExecuteBuffer method.

lpD3DDevice->CreateExecuteBuffer(

    lpDesc,       // Address of a DIRECT3DEXECUTEBUFFERDESC structure

    lplpDirect3DExecuteBuffer,  // Address to contain a pointer to the

                                // Direct3DExecuteBuffer object

    pUnkOuter);   // NULL

Execute-buffer objects reside on a device list. You can use the IDirect3DDevice::CreateExecuteBuffer method to allocate space for the actual buffer, which may be on the hardware device.

The buffer is filled with two contiguous arrays of vertices and opcodes by using the following calls to the IDirect3DExecuteBuffer::Lock, IDirect3DExecuteBuffer::Unlock, and IDirect3DExecuteBuffer::SetExecuteData methods:

lpD3DExBuf->Lock(

    lpDesc);.      // Address of a DIRECT3DEXECUTEBUFFERDESC structure

//  .

//  .  Store contents through the supplied address

//  .

lpD3DExBuf->Unlock();

lpD3DExBuf->SetExecuteData(

    lpData);       // Address of a D3DEXECUTEDATA structure

The last call in the preceding example is to the IDirect3DExecuteBuffer::SetExecuteData method. This method notifies Direct3D where the two parts of the buffer reside relative to the address that was returned by the call to the IDirect3DExecuteBuffer::Lock method.

You can use the IDirect3DExecuteBuffer interface to get and set execute data, and to lock, unlock, optimize, and validate the execute buffer.


Object Connectivity

The following illustration shows how each execute buffer and viewport is owned by exactly one device, and each light is owned by exactly one viewport.

Material and texture objects can be associated with more than one device. Each node in the following illustration contains a pointer back to the head of the list it is in. (These pointers, however, are not shown in the illustration.) From any texture or material node, pointers lead back both to the texture or material object and to the relevant device.

You can create interface, device, and texture objects by calling the QueryInterface method. Material, light, and viewport objects are created by calls to the methods of the IDirect3D interface. Execute buffers and matrices are created by calls to the methods of the IDirect3DDevice interface. An interface object (Direct3D object) has a list of all created device, viewport, light, and material objects, but not execute buffers or textures.


Direct3D Immediate-Mode Tutorial

To create a Windows-based Direct3D Immediate-Mode application, you create DirectDraw and Direct3D objects, set render states, fill execute buffers, and execute those buffers. This section explains some simple Immediate-Mode sample code that is part of this SDK.

The D3dmain.cpp file in the samples provided with this SDK is used as a basis for all of the other Immediate-Mode samples. D3dmain.cpp contains the standard Windows framework of initialization, setting up a message loop, and creating a window procedure for message processing, but it also does some work that is specific to Direct3D Immediate-Mode applications. This work is discussed in the following sections:

•	Beginning Initialization

•	Creating DirectDraw and Direct3D Objects

•	Setting Up the Device-Creation Callback Function

•	Initializing the Viewport

•	Setting the Immediate-Mode Render State

•	Completing Initialization

•	Running the Rendering Loop

•	Cleaning Up

The Immediate-Mode samples in this SDK include some code that is not documented here. In particular, this SDK includes a collection of helper functions collectively referred to as the D3DApp functions. You might find them useful when writing your own Immediate-Mode applications. These helper functions are referred to frequently in this documentation but are not covered exhaustively. They are implemented by the D3dapp.c, Ddcalls.c, D3dcalls.c, Texture.c, and Misc.c source files. The Stats.cpp source file sends frame-rate and screen-mode information to the screen.

Every sample that uses D3dmain.cpp must implement the following functions, which enable samples to customize their behavior:

•	InitScene

•	InitView

•	RenderScene

•	ReleaseView

•	ReleaseScene

•	OverrideDefaults

In addition, samples can use the SetMouseCallback and SetKeyboardCallback functions to read mouse and keyboard input.


Beginning Initialization

The first Direct3D task the WinMain function in D3dmain.cpp does is call the locally defined AppInit function, which creates the application window and initializes all objects needed to begin rendering. The WinMain function also implements the message pump for D3dmain.cpp and calls the locally defined RenderLoop and CleanUpAndPostQuit functions. The AppInit function calls other functions to help it do its work, and these functions, in turn, call still more functions; this group of initialization functions is the subject of most of this tutorial.

After performing some standard tasks in the initialization of a Windows application and initializing global variables to acceptable default settings, AppInit calls the InitScene function that each sample that uses D3dmain.cpp must implement. Simple sample applications, such as Oct1.c, implement versions of InitScene that do nothing but return TRUE. More complicated samples, such as Tunnel.c, use InitScene to allocate memory, generate points, and set global variables.

The last thing the AppInit function does before it returns is call the CreateD3DApp function, which is implemented in D3dmain.cpp. The functions called by CreateD3Dapp do much of the initialization work.


Creating DirectDraw and Direct3D Objects

The CreateD3DApp function in D3dmain.cpp is responsible for initializing the DirectDraw and Direct3D objects that are required before rendering begins. Important local functions called by CreateD3DApp include D3DAppCreateFromHWND, D3DAppGetRenderState, OverrideDefaults, D3DAppSetRenderState, ReleaseView, and InitView. Functions whose names begin with D3DApp are part of the D3DApp series of helper functions.

The same command-line options passed to the WinMain function are also passed to CreateD3DApp. Valid options are -systemmemory and -emulation. The -systemmemory option is used purely for debugging. The -emulation option prevents the application from using DirectDraw or Direct3D hardware.

CreateD3DApp calls the D3DAppAddTexture function to generate a series of textures. Then the D3DAppAddTexture function creates a source texture surface and object in system memory. Then it creates a second, initially empty, texture surface in video memory if hardware is present. The source texture is loaded into the destination texture surface and then discarded. This two-stage process allows a device to compress or reformat a texture map as it enters video memory. The code uses the IDirectDrawSurface::QueryInterface method to retrieve an interface to an IDirect3DTexture interface and the IDirect3DTexture::Load method to load the textures. The IDirect3DTexture::GetHandle method is used to create a list of texture handles.

After creating a list of textures, CreateD3DApp creates the DirectDraw and Direct3D objects required to start rendering. The code uses the D3DAppCreateFromHWND helper function. D3DAppCreateFromHWND uses functions that are implemented in the D3dapp.c, D3dcalls.c, Texture.c, and Ddcalls.c source files.

First, D3DAppCreateFromHWND uses the DirectDrawEnumerate and DirectDrawCreate functions to create and initialize the DirectDraw object, sets the values of global variables, and enumerates the display modes by calling the IDirectDraw2::EnumDisplayModes method.

D3DAppCreateFromHWND then creates the Direct3D object and enumerates the Direct3D device drivers. To create the Direct3D object, it calls the IDirectDraw::QueryInterface method, passing the IID_IDirect3D interface identifier. It uses IDirect3D::EnumDevices to enumerate the device drivers.

Calling IDirect3D::EnumDevices is not the easiest or even the best way to find Direct3D device drivers, however. Instead of setting up an enumeration routine, most Immediate-Mode applications use the IDirect3D::FindDevice method. This method allows you to simply specify the capabilities of the device you prefer—the system examines the available drivers and returns the globally unique identifier (GUID) for the first matching device. The system always searches the hardware first, so if both a hardware and a software device meet the required capabilities, the system returns the GUID for the hardware device.

After choosing a device driver and display mode (full-screen versus windowed), D3DAppCreateFromHWND creates front and back buffers for the chosen display mode. The code performs different actions based on whether the application is running in a window or the full screen, and whether video memory or system memory is being employed. If the application is running in a window, the code calls the IDirectDraw::CreateClipper method to create a clipper object and then calls the IDirectDrawClipper::SetHWnd method to attach it to the window and the IDirectDrawSurface::SetClipper method to attach it to the front buffer.

Then, D3DAppCreateFromHWND checks whether the front buffer is palettized. If it is, the code initializes the palette. First it creates the palette by calling the IDirectDraw::CreatePalette method, then it uses the IDirectDrawSurface::SetPalette method to set this as the palette for the front and back surfaces.

At this point the code calls the IDirectDraw::CreateSurface method to create a z-buffer, the IDirectDrawSurface::AddAttachedSurface method to attach the z-buffer to the back buffer, and the IDirectDrawSurface::GetSurfaceDesc method to determine whether the z-buffer is in video memory.

Then the code creates an IDirect3DDevice interface and uses it to enumerate the texture formats. The sample calls the IDirectDrawSurface::QueryInterface method to create the interface and the IDirect3DDevice::EnumTextureFormats method to enumerate the texture formats. When the textures have been enumerated, the code uses the same series of calls it employed in CreateD3DApp to load the textures and create a list of texture handles.

After using the driver's bit-depth and total video memory to filter the appropriate display modes, the code sets up the device-creation callback function, which is described in Setting Up the Device-Creation Callback Function.

When the device-creation callback function has been set up, D3DAppCreateFromHWND sets the application's render state, which is described in Setting the Immediate-Mode Render State.

When the D3DAppCreateFromHWND function has created the required Direct3D objects and set up the render state, it is almost finished. The function calls a local function to set the dirty rectangles for the front and back buffers to the entire client area, sets flags indicating that the application is initialized and that rendering can proceed, and returns TRUE.

The last part of the D3DAppCreateFromHWND function is its error-handling section. Whenever a call fails, the error-handling code jumps to the exit_with_error label. This section calls the callback function that destroys the device, resets the display mode and cooperative level if the application was running in full-screen mode, releases all the Direct3D and DirectDraw objects that were created, and returns FALSE.


Setting Up the Device-Creation Callback Function

The third parameter of the D3DAppCreateFromHWND function is an address of a callback function that is implemented as the AfterDeviceCreated function in D3dmain.cpp. AfterDeviceCreated creates the Direct3D viewport and returns it to D3DAppCreateFromHWND.

First the code calls the IDirect3D::CreateViewport method to create a viewport, and then it calls the IDirect3DDevice::AddViewport method to add the viewport to the newly created Direct3D device. After initializing the viewport's dimensions in a D3DVIEWPORT structure, the code calls the IDirect3DViewport::SetViewport method to set the viewport to those dimensions.

Then, the AfterDeviceCreated function calls the InitView function. InitView, like the InitScene function called earlier by D3dmain.cpp, must be implemented by each sample that uses D3dmain.cpp. One implementation of InitView is described in Initializing the Viewport.

After calling InitView and changing some of the menu items, AfterDeviceCreated finishes by calling the CleanUpAndPostQuit function. This function is described in Cleaning Up.


Initializing the Viewport

Each of the code samples that uses D3dmain.cpp must implement a version of the InitView function to set up the viewport and create the sample's execute buffers. This section discusses the implementation of InitView found in the Oct1.c sample.

First, InitView creates and initializes some materials, material handles, and texture handles. It uses the IDirect3D::CreateMaterial method to create a material, the IDirect3DMaterial::SetMaterial method to set the material data that InitView has just initialized, and the IDirect3DMaterial::GetHandle and IDirect3DViewport::SetBackground methods to set this material as the background for the viewport.

Now the InitView function sets the view, world, and projection matrices for the viewport. InitView uses the MAKE_MATRIX macro to create and set matrices. MAKE_MATRIX is defined in D3dmacs.h as follows:

#define MAKE_MATRIX(lpDev, handle, data) \

    if (lpDev->lpVtbl->CreateMatrix(lpDev, &handle) != D3D_OK) \

        return FALSE; \

    if (lpDev->lpVtbl->SetMatrix(lpDev, handle, &data) != D3D_OK) \

        return FALSE

As you can see, MAKE_MATRIX is simply a convenient way of calling the IDirect3DDevice::CreateMatrix and IDirect3DDevice::SetMatrix methods in a single step.

Now InitView creates and sets up an execute buffer. After initializing the members of a D3DEXECUTEBUFFERDESC structure, the code calls the IDirect3DDevice::CreateExecuteBuffer method to create the execute buffer and IDirect3DExecuteBuffer::Lock to lock it so that it can be filled.

InitView fills the execute buffer by using the OP_STATE_TRANSFORM and STATE_DATA macros from D3dmacs.h. These macros are described in Setting the Immediate-Mode Render State, along with more information about working with execute buffers.

When the execute buffer has been set up, InitView calls the IDirect3DExecuteBuffer::Unlock method to unlock it, the IDirect3DExecuteBuffer::SetExecuteData method to set the data into the buffer, and then the IDirect3DDevice::BeginScene, IDirect3DDevice::Execute, and IDirect3DDevice::EndScene methods to execute the execute buffer. Because the function has no further use for this execute buffer, it then calls IDirect3DExecuteBuffer::Release.

The InitView function now sets up two more materials by using the same procedure it used to set the materials earlier: it uses the IDirect3D::CreateMaterial method to create a material, the IDirect3DMaterial::SetMaterial method to set the material data (after filling the members of the D3DMATERIAL structure), and the IDirect3DMaterial::GetHandle method to retrieve a handle to the material. These handles are used later with the D3DLIGHTSTATE_MATERIAL member of the D3DLIGHTSTATETYPE enumerated type to associate lights with the new materials.

Now InitView sets up the vertices. The code uses the D3DVALP macro to convert floating-point numbers into the D3DVALUE members of the D3DVERTEX structure. It also uses the D3DRMVectorNormalize function to normalize the x-coordinate of the normal vector for each of the vertices it sets up.

When the vertices have been set up, InitView creates another execute buffer, copies the vertices to the buffer, and sets the execute data. It does not execute the execute buffer, however; this time, executing the execute buffer occurs in the rendering loop.

Finally, InitView sets up the lights for Oct1.c. After initializing the members of a D3DLIGHT structure, it calls the IDirect3D::CreateLight, IDirect3DLight::SetLight, and IDirect3DViewport::AddLight methods to add the light to the viewport.


Setting the Immediate-Mode Render State

The D3DAppISetRenderState function in the D3dcalls.c source file creates and executes an execute buffer that sets the render state and light state for the current viewport. The D3DAppCreateFromHWND function calls D3DAppISetRenderState from D3dapp.c; generally, the sample code calls D3DAppISetRenderState whenever the render state needs to be set or reset. This section reproduces the D3DAppISetRenderState function (except for some error-checking code).

After setting some local variables, including the D3DEXECUTEBUFFERDESC and D3DEXECUTEDATA structures, D3DAppISetRenderState calls the IDirect3DDevice::CreateExecuteBuffer method to create an execute buffer. When the execute buffer has been created, the code calls the IDirect3DExecuteBuffer::Lock method to lock it so that it can be filled.

BOOL D3DAppISetRenderState()

{

D3DEXECUTEBUFFERDESC debDesc;

D3DEXECUTEDATA d3dExData;

LPDIRECT3DEXECUTEBUFFER lpD3DExCmdBuf = NULL;

LPVOID lpBuffer, lpInsStart;

size_t size;

// Create an execute buffer of the required size and lock it

// so that it can be filled.

size = 0;

size += sizeof(D3DINSTRUCTION) * 3;

size += sizeof(D3DSTATE) * 17;

memset(&debDesc, 0, sizeof(D3DEXECUTEBUFFERDESC));

debDesc.dwSize = sizeof(D3DEXECUTEBUFFERDESC);

debDesc.dwFlags = D3DDEB_BUFSIZE;

debDesc.dwBufferSize = size;

LastError = d3dappi.lpD3DDevice->lpVtbl->CreateExecuteBuffer(

    d3dappi.lpD3DDevice, &debDesc, &lpD3DExCmdBuf, NULL);

LastError = lpD3DExCmdBuf->lpVtbl->Lock(lpD3DExCmdBuf, &debDesc);

memset(debDesc.lpData, 0, size);

lpInsStart = debDesc.lpData;

lpBuffer = lpInsStart;

The d3dappi.lpD3DDevice parameter in the call to IDirect3DDevice::CreateExecuteBuffer is a pointer to a Direct3DDevice object. The lpData member of the debDesc variable (a D3DEXECUTEBUFFERDESC structure) is a pointer to the actual data in the execute buffer.

Now the D3DAppISetRenderState function sets the render states. It uses the OP_STATE_DATA macro to help do some of this work. This macro, in turn, uses the PUTD3DINSTRUCTION macro. These macros are defined as follows in the D3dmacs.h header file in this SDK:

#define PUTD3DINSTRUCTION(op, sz, cnt, ptr) \

    ((LPD3DINSTRUCTION) ptr)->bOpcode = op; \

    ((LPD3DINSTRUCTION) ptr)->bSize = sz; \

    ((LPD3DINSTRUCTION) ptr)->wCount = cnt; \

    ptr = (void *)(((LPD3DINSTRUCTION) ptr) + 1)

#define OP_STATE_RENDER(cnt, ptr) \

    PUTD3DINSTRUCTION(D3DOP_STATERENDER, sizeof(D3DSTATE), cnt, ptr)

Notice that the PUTD3DINSTRUCTION macro is little more than an initializer for the D3DINSTRUCTION structure. D3DOP_STATERENDER, the first parameter of the call to PUTD3DINSTRUCTION in the OP_STATE_RENDER macro, is one of the opcodes in the D3DOPCODE enumerated type; the second parameter is the size of the D3DSTATE structure.

The STATE_DATA macro, which is also defined in D3dmacs.h, handles the render states. To work with the render states, it uses pointers to members in the D3DSTATE structure—in particular, a pointer to the D3DRENDERSTATETYPE enumerated type.

#define STATE_DATA(type, arg, ptr) \

    ((LPD3DSTATE) ptr)->drstRenderStateType = (D3DRENDERSTATETYPE)type; \

    ((LPD3DSTATE) ptr)->dwArg[0] = arg; \

    ptr = (void *)(((LPD3DSTATE) ptr) + 1)

The following code fragment from D3DAppISetRenderState uses the OP_STATE_RENDER and STATE_DATA macros to set 14 render states. The d3dapprs structure is the D3DAppRenderState structure, which is defined in the D3dapp.h header file.

OP_STATE_RENDER(14, lpBuffer);

    STATE_DATA(D3DRENDERSTATE_SHADEMODE, d3dapprs.ShadeMode, lpBuffer);

    STATE_DATA(D3DRENDERSTATE_TEXTUREPERSPECTIVE,

        d3dapprs.bPerspCorrect, lpBuffer);

    STATE_DATA(D3DRENDERSTATE_ZENABLE, d3dapprs.bZBufferOn &&

        d3dappi.ThisDriver.bDoesZBuffer, lpBuffer);

    STATE_DATA(D3DRENDERSTATE_ZWRITEENABLE, d3dapprs.bZBufferOn,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_ZFUNC, D3DCMP_LESSEQUAL, lpBuffer);

    STATE_DATA(D3DRENDERSTATE_TEXTUREMAG, d3dapprs.TextureFilter,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_TEXTUREMIN, d3dapprs.TextureFilter,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_TEXTUREMAPBLEND, d3dapprs.TextureBlend,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_FILLMODE, d3dapprs.FillMode, lpBuffer);

    STATE_DATA(D3DRENDERSTATE_DITHERENABLE, d3dapprs.bDithering,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_SPECULARENABLE, d3dapprs.bSpecular,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_ANTIALIAS, d3dapprs.bAntialiasing,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_FOGENABLE, d3dapprs.bFogEnabled,

        lpBuffer);

    STATE_DATA(D3DRENDERSTATE_FOGCOLOR, d3dapprs.FogColor, lpBuffer);

Now the OP_STATE_RENDER and STATE_DATA macros set three light states. The OP_EXIT macro simply uses the PUTD3DINSTRUCTION macro to call the D3DOP_EXIT opcode from the D3DOPCODE enumerated type.

OP_STATE_LIGHT(3, lpBuffer);

    STATE_DATA(D3DLIGHTSTATE_FOGMODE, d3dapprs.bFogEnabled ?

        d3dapprs.FogMode : D3DFOG_NONE, lpBuffer);

    STATE_DATA(D3DLIGHTSTATE_FOGSTART,

        *(unsigned long*)&d3dapprs.FogStart, lpBuffer);

    STATE_DATA(D3DLIGHTSTATE_FOGEND, *(unsigned long*)&d3dapprs.FogEnd,

        lpBuffer);

OP_EXIT(lpBuffer);

Now that the render states have been set, D3DAppISetRenderState unlocks the execute buffer by calling the IDirect3DExecuteBuffer::Unlock method. It sets the execute data by calling the IDirect3DExecuteBuffer::SetExecuteData method. Finally, it begins the scene, executes the execute buffer, and ends the scene again by calling the IDirect3DDevice::BeginScene, IDirect3DDevice::Execute, and IDirect3DDevice::EndScene methods.

LastError = lpD3DExCmdBuf->lpVtbl->Unlock(lpD3DExCmdBuf);

memset(&d3dExData, 0, sizeof(D3DEXECUTEDATA));

d3dExData.dwSize = sizeof(D3DEXECUTEDATA);

d3dExData.dwInstructionOffset = (ULONG) 0;

d3dExData.dwInstructionLength = (ULONG) ((char*)lpBuffer -

    (char*)lpInsStart);

lpD3DExCmdBuf->lpVtbl->SetExecuteData(lpD3DExCmdBuf, &d3dExData);

LastError =

    d3dappi.lpD3DDevice->lpVtbl->BeginScene(d3dappi.lpD3DDevice);

LastError =

    d3dappi.lpD3DDevice->lpVtbl->Execute(d3dappi.lpD3DDevice,

        lpD3DExCmdBuf, d3dappi.lpD3DViewport);

LastError = d3dappi.lpD3DDevice->lpVtbl->EndScene(d3dappi.lpD3DDevice);

The D3DAppISetRenderState has finished its work with the execute buffer, so it calls the IDirect3DExecuteBuffer::Release method to release it, and it returns.

lpD3DExCmdBuf->lpVtbl->Release(lpD3DExCmdBuf);

return TRUE;

}


Completing Initialization

The CreateD3DApp function that is called by the AppInit function in WinMain has created most of the underpinnings of a Direct3D application, but it hasn't finished yet. Before D3dmain.cpp calls the rendering loop, CreateD3DApp must complete a few more tasks.

After copying the current render states into the application's local D3DAppRenderState structure, CreateD3DApp calls the OverrideDefaults function. OverrideDefaults is another function that must be supported by all samples that use D3dmain.cpp. Sometimes an application will do very little in its OverrideDefaults function; for example, the Oct1.c sample simply replaces the default name with the string, "Octagon D3D Example".

Now CreateD3DApp calls the D3DAppSetRenderState function, which simply checks the status of the saved render states and either resets them (if no render states were provided in the call) or saves them before calling the D3DAppISetRenderState function, which is discussed in Setting the Immediate-Mode Render State.

As a final step before entering the rendering loop, CreateD3DApp calls the ReleaseView and InitView functions. These functions, like OverrideDefaults, are implemented by each sample application. ReleaseView simply releases any objects created in a previous call to the InitView function. (InitView, as you recall, is first called as part of the AfterDeviceCreated callback function.) This final call to InitView sets up the viewport again (in case there have been changes since the device was created) and re-creates the sample's execute buffers. For more information about InitView, see Initializing the Viewport.

This is the end not only of the CreateD3DApp function in D3dmain.cpp; it is also the end of the AppInit function. Now that the code has finished with the initialization part of the work, it can enter the rendering loop.


Running the Rendering Loop

After initializing the application, the WinMain function in D3dmain.cpp sets up the message loop. The code monitors the message queue until there are no pressing messages and then calls the RenderLoop function. RenderLoop is defined in D3dmain.cpp. WinMain maintains a count of the number of times RenderLoop can fail; if it fails more than three times, the application quits.

The RenderLoop function renders the next frame in the scene and updates the window.

The first task in the RenderLoop function is to restore any lost DirectDraw surfaces, if possible. It calls the IDirectDrawSurface::IsLost method to identify lost surfaces and IDirectDrawSurface::Restore to restore them. Then RenderLoop clears the back buffer and, if enabled, the z-buffer, by calling the IDirect3DRMViewport::Clear method.

Now RenderLoop calls the RenderScene function implemented by the sample application calling D3dmain.cpp. A sample's RenderScene function can take into account a complex series of special cases, or it can be as simple as the implementation in Oct1.c. Then, the RenderScene function executes the execute buffer by calling IDirect3DDevice::BeginScene, IDirect3DDevice::Execute, and IDirect3DDevice::EndScene, retrieves any new execute data by calling IDirect3DExecuteBuffer::GetExecuteData, updates the screen extents, and then calls a local TickScene function that changes the viewing position by calling the IDirect3DDevice::SetMatrix method.

Finally, the RenderLoop function calls the D3DAppRenderExtents helper function to keep track of the changed sections of the front and back buffers and blits or flips the back buffer to the front buffer.


Cleaning Up

Whenever an error occurs from which the application cannot recover, or the application receives a WM_QUIT or MENU_EXIT message, the application calls the CleanUpAndPostQuit function. CleanUpAndPostQuit does some simple error-checking and then calls the ReleaseScene function. ReleaseScene is the last of the functions that must be implemented by sample applications using D3dmain.cpp. This is an application's chance to release any remaining objects or free memory. For simple applications, like Oct1.c, ReleaseScene is simply a stub.

Finally, the CleanUpAndPostQuit function calls the PostQuitMessage function to end the application.


Retained-Mode Reference


Functions


Direct3DRMCreate

Creates an instance of a Direct3DRM object.

HRESULT Direct3DRMCreate(
LPDIRECT3DRM FAR * lplpD3DRM
);

Parameters

lplpD3DRM

Address of a pointer that will be initialized with a valid Direct3DRM pointer if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 Direct3DRMObject


D3DRMColorGetAlpha

Retrieves the alpha component of a color.

D3DVALUE D3DRMColorGetAlpha(
D3DCOLOR d3drmc
);

Parameters

d3drmc

Color from which the alpha component is retrieved.

Return Values

Returns the alpha value if successful, or zero otherwise.

See Also

 D3DRMColorGetBlue, D3DRMColorGetGreen, D3DRMColorGetRed


D3DRMColorGetBlue

Retrieves the blue component of a color.

D3DVALUE D3DRMColorGetBlue(
D3DCOLOR d3drmc
);

Parameters

d3drmc

Color from which the blue component is retrieved.

Return Values

Returns the blue value if successful, or zero otherwise.

See Also

 D3DRMColorGetAlpha, D3DRMColorGetGreen, D3DRMColorGetRed


D3DRMColorGetGreen

Retrieves the green component of a color.

D3DVALUE D3DRMColorGetGreen(
D3DCOLOR d3drmc
);

Parameters

d3drmc

Color from which the green component is retrieved.

Return Values

Returns the green value if successful, or zero otherwise.

See Also

 D3DRMColorGetAlpha, D3DRMColorGetBlue, D3DRMColorGetRed


D3DRMColorGetRed

Retrieves the red component of a color.

D3DVALUE D3DRMColorGetRed(
D3DCOLOR d3drmc
);

Parameters

d3drmc

Color from which the red component is retrieved.

Return Values

Returns the red value if successful, or zero otherwise.

See Also

 D3DRMColorGetAlpha, D3DRMColorGetBlue, D3DRMColorGetGreen


D3DRMCreateColorRGB

Creates an RGB color from supplied red, green, and blue components.

D3DVALUE D3DRMCreateColorRGB(
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);

Parameters

red, green, and blue

Components of the RGB color.

Return Values

Returns the new RGB value if successful, or zero otherwise.

See Also

 D3DRMCreateColorRGBA


D3DRMCreateColorRGBA

Creates an RGBA color from supplied red, green, blue, and alpha components.

D3DVALUE D3DRMCreateColorRGBA(
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue,
D3DVALUE alpha
);

Parameters

red, green, blue, and alpha

Components of the RGBA color.

Return Values

Returns the new RGBA value if successful, or zero otherwise.

See Also

 D3DRMCreateColorRGB


D3DRMFREEFUNCTION

Frees memory. This function is application-defined.

typedef VOID (*D3DRMFREEFUNCTION)(LPVOID lpArg);

typedef D3DRMFREEFUNCTION *LPD3DRMFREEFUNCTION;

Parameters

lpArg

Address of application-defined data.

Return Values

No return value.

Remarks

Applications might define their own memory-freeing function if the standard C run-time routines do not meet their requirements.


D3DRMMALLOCFUNCTION

Allocates memory. This function is application-defined.

typedef LPVOID (*D3DRMMALLOCFUNCTION)(DWORD dwSize);

typedef D3DRMMALLOCFUNCTION *LPD3DRMMALLOCFUNCTION;

Parameters

dwSize

Specifies the size, in bytes, of the memory that will be allocated.

Return Values

Returns the address of the allocated memory if successful, or zero otherwise.

Remarks

Applications might define their own memory-allocation function if the standard C run-time routines do not meet their requirements.


D3DRMMatrixFromQuaternion

Calculates the matrix for the rotation that a unit quaternion represents.

void D3DRMMatrixFromQuaternion (
D3DRMMATRIX4D mat,
LPD3DRMQUATERNION lpquat
);

Parameters

mat

Address that will contain the calculated matrix when the function returns. (The D3DRMMATRIX4D type is an array.)

lpquat

Address of the D3DRMQUATERNION structure.

Return Values

No return value.


D3DRMQuaternionFromRotation

Retrieves a unit quaternion that represents a rotation of a specified number of radians around the given axis.

LPD3DRMQUATERNION D3DRMQuaternionFromRotation(
LPD3DRMQUATERNION lpquat,
LPD3DVECTOR lpv,
D3DVALUE theta
);

Parameters

lpquat

Address of a D3DRMQUATERNION structure that will contain the result of the operation.

lpv

Address of a D3DVECTOR structure specifying the axis of rotation.

theta

Number of radians to rotate around the axis specified by the lpv parameter.

Return Values

Returns the address of the unit quaternion that was passed as the first parameter if successful, or zero otherwise.


D3DRMQuaternionMultiply

Calculates the product of two quaternion structures.

LPD3DRMQUATERNION D3DRMQuaternionMultiply(
LPD3DRMQUATERNION lpq,
LPD3DRMQUATERNION lpa,
LPD3DRMQUATERNION lpb
);

Parameters

lpq

Address of the D3DRMQUATERNION structure that will contain the product of the multiplication.

lpa and lpb

Addresses of the D3DRMQUATERNION structures that will be multiplied together.

Return Values

Returns the address of the quaternion that was passed as the first parameter if successful, or zero otherwise.


D3DRMQuaternionSlerp

Interpolates between two quaternion structures, using spherical linear interpolation.

LPD3DRMQUATERNION D3DRMQuaternionSlerp(
LPD3DRMQUATERNION lpq,
LPD3DRMQUATERNION lpa,
LPD3DRMQUATERNION lpb,
D3DVALUE alpha
);

Parameters

lpq

Address of the D3DRMQUATERNION structure that will contain the interpolation.

lpa and lpb

Addresses of the D3DRMQUATERNION structures that are used as the starting and ending points for the interpolation, respectively.

alpha

Value between 0 and 1 that specifies how far to interpolate between lpa and lpb.

Return Values

Returns the address of the quaternion that was passed as the first parameter if successful, or zero otherwise.


D3DRMREALLOCFUNCTION

Reallocates memory. This function is application-defined.

typedef LPVOID (*D3DRMREALLOCFUNCTION)(LPVOID lpArg,

    DWORD dwSize);

typedef D3DRMREALLOCFUNCTION *LPD3DRMREALLOCFUNCTION;

Parameters

lpArg

Address of application-defined data.

dwSize

Size, in bytes, of the reallocated memory.

Return Values

Returns an address of the reallocated memory if successful, or zero otherwise.

Remarks

Applications may define their own memory-reallocation function if the standard C run-time routines do not meet their requirements.


D3DRMVectorAdd

Adds two vectors.

LPD3DVECTOR D3DRMVectorAdd(
LPD3DVECTOR lpd,
LPD3DVECTOR lps1,
LPD3DVECTOR lps2
);

Parameters

lpd

Address of a D3DVECTOR structure that will contain the result of the addition.

lps1 and lps2

Addresses of the D3DVECTOR structures that will be added together.

Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.


D3DRMVectorCrossProduct

Calculates the cross product of the two vector arguments.

LPD3DVECTOR D3DRMVectorCrossProduct(
LPD3DVECTOR lpd,
LPD3DVECTOR lps1,
LPD3DVECTOR lps2
);

Parameters

lpd

Address of a D3DVECTOR structure that will contain the result of the cross product.

lps1 and lps2

Addresses of the D3DVECTOR structures from which the cross product is produced.

Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.


D3DRMVectorDotProduct

Returns the vector dot product.

D3DVALUE D3DRMVectorDotProduct(
LPD3DVECTOR lps1,
LPD3DVECTOR lps2
);

Parameters

lps1 and lps2

Addresses of the D3DVECTOR structures from which the dot product is produced.

Return Values

Returns the result of the dot product if successful, or zero otherwise.


D3DRMVectorModulus

Returns the length of a vector (that is, sqrt(x*x + y*y + z*z)).

D3DVALUE D3DRMVectorModulus(
LPD3DVECTOR lpv
);

Parameters

lpv

Address of the D3DVECTOR structure whose length is returned.

Return Values

Returns the length of the D3DVECTOR structure if successful, or zero otherwise.


D3DRMVectorNormalize

Scales a vector so that its modulus is 1.

LPD3DVECTOR D3DRMVectorNormalize(
LPD3DVECTOR lpv
);

Parameters

lpv

Address of a D3DVECTOR structure that will contain the result of the scaling operation.

Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero if an error occurs, such as if, for example, a zero vector was passed.


D3DRMVectorRandom

Returns a random unit vector.

LPD3DVECTOR D3DRMVectorRandom(
LPD3DVECTOR lpd
);

Parameters

lpd

Address of a D3DVECTOR structure that will contain a random unit vector.

Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.


D3DRMVectorReflect

Reflects a ray about a given normal.

LPD3DVECTOR D3DRMVectorReflect(
LPD3DVECTOR lpd,
LPD3DVECTOR lpRay,
LPD3DVECTOR lpNorm
);

Parameters

lpd

Address of a D3DVECTOR structure that will contain the result of the operation.

lpRay

Address of a D3DVECTOR structure that will be reflected about a normal.

lpNorm

Address of a D3DVECTOR structure specifying the normal about which the vector specified in lpRay is reflected.

Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.


D3DRMVectorRotate

Rotates a vector around a given axis.

LPD3DVECTOR D3DRMVectorRotate(
LPD3DVECTOR lpr,
LPD3DVECTOR lpv,
LPD3DVECTOR lpaxis,
D3DVALUE theta
);

Parameters

lpr

Address of a D3DVECTOR structure that will contain the result of the operation.

lpv

Address of a D3DVECTOR structure that will be rotated around the given axis.

lpaxis

Address of a D3DVECTOR structure that is the axis of rotation.

theta

The rotation in radians.

Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.


D3DRMVectorScale

Scales a vector uniformly in all three axes.

LPD3DVECTOR D3DRMVectorScale(
LPD3DVECTOR lpd,
LPD3DVECTOR lps,
D3DVALUE factor
);

Parameters

lpd

Address of a D3DVECTOR structure that will contain the result of the operation.

lps

Address of a D3DVECTOR structure that this function scales.

factor

Scaling factor. A value of 1 does not change the scaling; a value of 2 doubles it, and so on.

Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.


D3DRMVectorSubtract

Subtracts two vectors.

LPD3DVECTOR D3DRMVectorSubtract(
LPD3DVECTOR lpd,
LPD3DVECTOR lps1,
LPD3DVECTOR lps2
);

Parameters

lpd

Address of a D3DVECTOR structure that will contain the result of the operation.

lps1

Address of the D3DVECTOR structure from which lps2 is subtracted.

lps2

Address of the D3DVECTOR structure that is subtracted from lps1.

Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.


Callback Functions


D3DRMDEVICEPALETTECALLBACK

Enumerates palette entries. This callback function is application-defined.

void (
*D3DRMDEVICEPALETTECALLBACK
)
(
LPDIRECT3DRMDEVICE lpDirect3DRMDev,
LPVOID lpArg,
DWORD dwIndex,
LONG red,
LONG green,
LONG blue
);

Parameters

lpDirect3DRMDev

Address of the IDirect3DRMDevice interface for this device.

lpArg

Address of application-defined data passed to this callback function.

dwIndex

Index of the palette entry being described.

red, green, and blue

Red, green, and blue components of the color at the given index in the palette.

Return Values

No return value.

Remarks

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.


D3DRMFRAMEMOVECALLBACK

Enables an application to apply customized algorithms when a frame is moved or updated. You can use this callback function to compensate for changing frame rates. This callback function is application-defined.

void (
*D3DRMFRAMEMOVECALLBACK
)(
LPDIRECT3DRMFRAME lpD3DRMFrame,
LPVOID lpArg,
D3DVALUE delta
);

Parameters

lpD3DRMFrame

Address of the Direct3DRMFrame object that is being moved.

lpArg

Address of application-defined data passed to this callback function.

delta

Amount of change to apply to the movement. There are two components to the change in position of a frame: linear and rotational. The change in each component is equal to velocity_of_component × delta. Although either or both of these velocities can be set relative to any frame, the system automatically converts them to velocities relative to the parent frame for the purpose of applying time deltas.

Return Values

No return value.

Remarks

Your application can synthesize the acceleration of a frame relative to its parent frame. To do so, on each tick your application should set the velocity of the child frame relative to itself to (a units per tick) × 1 tick, where a is the required acceleration. This is equal to a × delta units per tick. Internally, a × delta units per tick relative to the child frame is converted to (v + (a × delta)) units per tick relative to the parent frame, where v is the current velocity of the child relative to the parent.

You can add and remove this callback function from your application by using the IDirect3DRMFrame::AddMoveCallback and IDirect3DRMFrame::DeleteMoveCallback methods.

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.


D3DRMLOADCALLBACK

Loads objects named in a call to the IDirect3DRM::Load method. This callback function is application-defined.

void (
*D3DRMLOADCALLBACK
)(
LPDIRECT3DRMOBJECT lpObject,
REFIID ObjectGuid,
LPVOID lpArg
);

Parameters

lpObject

Address of the Direct3DRMObject being loaded.

ObjectGuid

Globally unique identifier (GUID) of the object being loaded.

lpArg

Address of application-defined data passed to this callback function.

Return Values

No return value.

Remarks

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.

See Also

 IDirect3DRM::Load


D3DRMLOADTEXTURECALLBACK

Loads texture maps from a file or resource named in a call to one of the Load methods. This callback function is application-defined.

HRESULT (
*D3DRMLOADTEXTURECALLBACK
)(
char *tex_name,
void *lpArg,
LPDIRECT3DRMTEXTURE * lpD3DRMTex
);

Parameters

tex_name

Address of a string containing the name of the texture.

lpArg

Address of application-specific data.

lpD3DRMTex

Address of the Direct3DRMTexture object.

Return Values

Should return D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

Applications can use this callback function to implement support for textures that are not in the Windows bitmap (.bmp) or Portable Pixmap (.ppm) P6 format.

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.

See Also

 IDirect3DRM::Load, IDirect3DRMAnimationSet::Load, IDirect3DRMFrame::Load, IDirect3DRMMeshBuilder::Load


D3DRMOBJECTCALLBACK

Enumerates objects in response to a call to the IDirect3DRM::EnumerateObjects method. This callback function is application-defined.

void (
*D3DRMOBJECTCALLBACK
)(
LPDIRECT3DRMOBJECT lpD3DRMobj,
LPVOID lpArg
);

Parameters

lpD3DRMobj

Address of an IDirect3DRMObject interface for the object being enumerated. The application must call the Release method for each enumerated object.

lpArg

Address of application-defined data passed to this callback function.

Return Values

No return value.

Remarks

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.

See Also

 IDirect3DRM::EnumerateObjects


D3DRMUPDATECALLBACK

Alerts the application whenever the device changes. This callback function is application-defined.

void (
*D3DRMUPDATECALLBACK
)(
LPDIRECT3DRMDEVICE lpobj,
LPVOID lpArg,
int x,
LPD3DRECT d3dRectUpdate
);

Parameters

lpobj

Address of the Direct3DRMDevice object to which this callback function applies.

lpArg

Address of application-defined data passed to this callback function.

x

Number of rectangles specified in the d3dRectUpdate parameter.

d3dRectUpdate

Array of one or more D3DRECT structures that describe the area to be updated. The coordinates are specified in device units.

Return Values

No return value.

Remarks

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.

See Also

 IDirect3DRMDevice::AddUpdateCallback, IDirect3DRMDevice::DeleteUpdateCallback, IDirect3DRMDevice::Update


D3DRMUSERVISUALCALLBACK

Alerts an application that supplies user-visual objects that it should execute the execute buffer. This function is application-defined.

int (
*D3DRMUSERVISUALCALLBACK
)(
LPDIRECT3DRMUSERVISUAL lpD3DRMUV,
LPVOID lpArg,
D3DRMUSERVISUALREASON lpD3DRMUVreason,
LPDIRECT3DRMDEVICE lpD3DRMDev,
LPDIRECT3DRMVIEWPORT lpD3DRMview
);

Parameters

lpD3DRMUV

Address of the Direct3DRMUserVisual object.

lpArg

Address of application-defined data passed to this callback function.

lpD3DRMUVreason

One of the members of the D3DRMUSERVISUALREASON enumerated type:

D3DRMUSERVISUAL_CANSEE

	The application should return TRUE if the user-visual object is visible in the viewport. In this case, the application uses the device specified in the lpD3DRMview parameter.
D3DRMUSERVISUAL_RENDER

	The application should render the user-visual element. In this case, the application uses the device specified in the lpD3DRMDev parameter.
lpD3DRMDev

Address of a Direct3DRMDevice object used to render the Direct3DRMUserVisual object.

lpD3DRMview

Address of a Direct3DRMViewport object used to determine whether the Direct3DRMUserVisual object is visible.

Return Values

Returns TRUE if the lpD3DRMUVreason parameter is D3DRMUSERVISUAL_CANSEE and the user-visual object is visible in the viewport. Returns FALSE otherwise. If the lpD3DRMUVreason parameter is D3DRMUSERVISUAL_RENDER, the return value is application-defined. It is always safe to return TRUE.

Remarks

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.

See Also

 IDirect3DRMUserVisual::Init


D3DRMWRAPCALLBACK

This callback function is not supported.

void (
*D3DRMWRAPCALLBACK
)(
LPD3DVECTOR lpD3DVector,
int* lpU,
int* lpV,
LPD3DVECTOR lpD3DRMVA,
LPD3DVECTOR lpD3DRMVB,
LPVOID lpArg
);


IDirect3DRM Array Interfaces


Introduction to Array Interfaces

The array interfaces make it possible for your application to group objects into arrays, making it simpler to apply operations to the entire group. The following array interfaces are available:

IDirect3DRMArray
IDirect3DRMDeviceArray
IDirect3DRMFaceArray
IDirect3DRMFrameArray
IDirect3DRMLightArray
IDirect3DRMPickedArray
IDirect3DRMViewportArray
IDirect3DRMVisualArray


IDirect3DRMArray Interface Method Groups

The IDirect3DRMArray interface organizes groups of objects. Applications typically use array objects that are subsidiary to this interface, rather than using this interface directly. This interface supports the following methods:

Information	GetSize
IUnknown	AddRef
	QueryInterface
	Release
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMArray object without affecting the functionality of the original interface.


IDirect3DRMArray::AddRef

Increases the reference count of the Direct3DRMArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMArray.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMArray object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMArray::Release method to decrease the reference count of the object by 1.


IDirect3DRMArray::GetSize

Retrieves the size, in objects, of the Direct3DRMArray object.

DWORD GetSize( );

Return Values

Returns the size.


IDirect3DRMArray::QueryInterface

Determines if the Direct3DRMArray object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMArray.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMArray::QueryInterface method allows Direct3DRMArray objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMArray::Release

Decreases the reference count of the Direct3DRMArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMArray.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMArray object deallocates itself when its reference count reaches 0. Use the IDirect3DRMArray::AddRef method to increase the reference count of the object by 1.


IDirect3DRMDeviceArray Interface Method Groups

Applications use the methods of the IDirect3DRMDeviceArray interface to organize device objects. The methods can be organized into the following groups:

Information	GetElement
	GetSize
IUnknown	AddRef
	QueryInterface
	Release
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMDeviceArray object without affecting the functionality of the original interface. In addition, the IDirect3DRMDeviceArray interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMDeviceArray object is obtained by calling the IDirect3DRM::GetDevices method.


IDirect3DRMDeviceArray::AddRef

Increases the reference count of the Direct3DRMDeviceArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMDeviceArray.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMDeviceArray object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMDeviceArray::Release method to decrease the reference count of the object by 1.


IDirect3DRMDeviceArray::GetElement

Retrieves a specified element in a Direct3DRMDeviceArray object.

HRESULT GetElement(
DWORD index,
LPDIRECT3DRMDEVICE * lplpD3DRMDevice
);

Parameters

index

Element in the array.

lplpD3DRMDevice

Address that will be filled with a pointer to an IDirect3DRMDevice interface.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMDeviceArray::GetSize

Retrieves the number of elements contained in a Direct3DRMDeviceArray object.

DWORD GetSize( );

Return Values

Returns the number of elements.


IDirect3DRMDeviceArray::QueryInterface

Determines if the Direct3DRMDeviceArray object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMDeviceArray.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMDeviceArray::QueryInterface method allows Direct3DRMDeviceArray objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMDeviceArray::Release

Decreases the reference count of the Direct3DRMDeviceArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMDeviceArray.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMDeviceArray object deallocates itself when its reference count reaches 0. Use the IDirect3DRMDeviceArray::AddRef method to increase the reference count of the object by 1.


IDirect3DRMFaceArray Interface Method Groups

Applications use the methods of the IDirect3DRMFaceArray interface to organize faces in a mesh. The methods can be organized into the following groups:

Information	GetElement
	GetSize
IUnknown	AddRef
	QueryInterface
	Release
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMFaceArray object without affecting the functionality of the original interface. In addition, the IDirect3DRMFaceArray interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMFaceArray object is obtained by calling the IDirect3DRMMeshBuilder::GetFaces method.


IDirect3DRMFaceArray::AddRef

Increases the reference count of the Direct3DRMFaceArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMFaceArray.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMFaceArray object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMFaceArray::Release method to decrease the reference count of the object by 1.


IDirect3DRMFaceArray::GetElement

Retrieves a specified element in a Direct3DRMFaceArray object.

HRESULT GetElement(
DWORD index,
LPDIRECT3DRMFACE * lplpD3DRMFace
);

Parameters

index

Element in the array.

lplpD3DRMFace

Address that will be filled with a pointer to an IDirect3DRMFace interface.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFaceArray::GetSize

Retrieves the number of elements contained in a Direct3DRMFaceArray object.

DWORD GetSize( );

Return Values

Returns the number of elements.


IDirect3DRMFaceArray::QueryInterface

Determines if the Direct3DRMFaceArray object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMFaceArray.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMFaceArray::QueryInterface method allows Direct3DRMFaceArray objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMFaceArray::Release

Decreases the reference count of the Direct3DRMFaceArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMFaceArray.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMFaceArray object deallocates itself when its reference count reaches 0. Use the IDirect3DRMFaceArray::AddRef method to increase the reference count of the object by 1.


IDirect3DRMFrameArray Interface Method Groups

Applications use the methods of the IDirect3DRMFrameArray interface to organize frame objects. The methods can be organized into the following groups:

Information	GetElement
	GetSize
IUnknown	AddRef
	QueryInterface
	Release
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMFrameArray object without affecting the functionality of the original interface. In addition, the IDirect3DRMFrameArray interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMFrameArray object is obtained by calling the IDirect3DRMPickedArray::GetPick or IDirect3DRMFrame::GetChildren method.


IDirect3DRMFrameArray::AddRef

Increases the reference count of the Direct3DRMFrameArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMFrameArray.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMFrameArray object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMFrameArray::Release method to decrease the reference count of the object by 1.


IDirect3DRMFrameArray::GetElement

Retrieves a specified element in a Direct3DRMFrameArray object.

HRESULT GetElement(
DWORD index,
LPDIRECT3DRMFRAME * lplpD3DRMFrame
);

Parameters

index

Element in the array.

lplpD3DRMFrame

Address that will be filled with a pointer to an IDirect3DRMFrame interface.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFrameArray::GetSize

Retrieves the number of elements contained in a Direct3DRMFrameArray object.

DWORD GetSize( );

Return Values

Returns the number of elements.


IDirect3DRMFrameArray::QueryInterface

Determines if the Direct3DRMFrameArray object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMFrameArray.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMFrameArray::QueryInterface method allows Direct3DRMFrameArray objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMFrameArray::Release

Decreases the reference count of the Direct3DRMFrameArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMFrameArray.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMFrameArray object deallocates itself when its reference count reaches 0. Use the IDirect3DRMFrameArray::AddRef method to increase the reference count of the object by 1.


IDirect3DRMLightArray Interface Method Groups

Applications use the methods of the IDirect3DRMLightArray interface to organize light objects. The methods can be organized into the following groups:

Information	GetElement
	GetSize
IUnknown	AddRef
	QueryInterface
	Release
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMLightArray object without affecting the functionality of the original interface. In addition, the IDirect3DRMLightArray interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMLightArray object is obtained by calling the IDirect3DRMFrame::GetLights method.


IDirect3DRMLightArray::AddRef

Increases the reference count of the Direct3DRMLightArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMLightArray.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMLightArray object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMLightArray::Release method to decrease the reference count of the object by 1.


IDirect3DRMLightArray::GetElement

Retrieves a specified element in a Direct3DRMLightArray object.

HRESULT GetElement(
DWORD index,
LPDIRECT3DRMLIGHT * lplpD3DRMLight
);

Parameters

index

Element in the array.

lplpD3DRMLight

Address that will be filled with a pointer to an IDirect3DRMLight interface.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMLightArray::GetSize

Retrieves the number of elements contained in a Direct3DRMLightArray object.

DWORD GetSize( );

Return Values

Returns the number of elements.


IDirect3DRMLightArray::QueryInterface

Determines if the Direct3DRMLightArray object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMLightArray.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMLightArray::QueryInterface method allows Direct3DRMLightArray objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMLightArray::Release

Decreases the reference count of the Direct3DRMLightArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMLightArray.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMLightArray object deallocates itself when its reference count reaches 0. Use the IDirect3DRMLightArray::AddRef method to increase the reference count of the object by 1.


IDirect3DRMPickedArray Interface Method Groups

Applications use the methods of the IDirect3DRMPickedArray interface to organize pick objects. The methods can be organized into the following groups:

Information	GetPick
	GetSize
IUnknown	AddRef
	QueryInterface
	Release
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMPickedArray object without affecting the functionality of the original interface. In addition, the IDirect3DRMPickedArray interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMPickedArray object is obtained by calling the IDirect3DRMViewport::Pick method.


IDirect3DRMPickedArray::AddRef

Increases the reference count of the Direct3DRMPickedArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMPickedArray.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMPickedArray object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMPickedArray::Release method to decrease the reference count of the object by 1.


IDirect3DRMPickedArray::GetPick

Retrieves the Direct3DRMVisual and Direct3DRMFrame objects intersected by the specified pick.

HRESULT GetPick(
DWORD index,
LPDIRECT3DRMVISUAL * lplpVisual,
LPDIRECT3DRMFRAMEARRAY * lplpFrameArray,
LPD3DRMPICKDESC lpD3DRMPickDesc
);

Parameters

index

Index into the pick array identifying the pick for which information will be retrieved.

lplpVisual

Address that will contain a pointer to the Direct3DRMVisual object associated with the specified pick.

lplpFrameArray

Address that will contain a pointer to the Direct3DRMFrameArray object associated with the specified pick.

lpD3DRMPickDesc

Address of a D3DRMPICKDESC structure specifying the pick position and face and group identifiers of the objects being retrieved.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMViewport::Pick


IDirect3DRMPickedArray::GetSize

Retrieves the number of elements contained in a Direct3DRMPickedArray object.

DWORD GetSize( );

Return Values

Returns the number of elements.


IDirect3DRMPickedArray::QueryInterface

Determines if the Direct3DRMPickedArray object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMPickedArray.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMPickedArray::QueryInterface method allows Direct3DRMPickedArray objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMPickedArray::Release

Decreases the reference count of the Direct3DRMPickedArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMPickedArray.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMPickedArray object deallocates itself when its reference count reaches 0. Use the IDirect3DRMPickedArray::AddRef method to increase the reference count of the object by 1.


IDirect3DRMViewportArray Interface Method Groups

Applications use the methods of the IDirect3DRMViewportArray interface to organize viewport objects. The methods can be organized into the following groups:

Information	GetElement
	GetSize
IUnknown	AddRef
	QueryInterface
	Release
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMViewportArray object without affecting the functionality of the original interface. In addition, the IDirect3DRMViewportArray interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMViewportArray object is obtained by calling the IDirect3DRM::CreateFrame method.


IDirect3DRMViewportArray::AddRef

Increases the reference count of the Direct3DRMViewportArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMViewportArray.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMViewportArray object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMViewportArray::Release method to decrease the reference count of the object by 1.


IDirect3DRMViewportArray::GetElement

Retrieves a specified element in a Direct3DRMViewportArray object.

HRESULT GetElement(
DWORD index,
LPDIRECT3DRMVIEWPORT * lplpD3DRMViewport
);

Parameters

index

Element in the array.

lplpD3DRMViewport

Address that will be filled with a pointer to an IDirect3DRMViewport interface.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMViewportArray::GetSize

Retrieves the number of elements contained in a Direct3DRMViewportArray object.

DWORD GetSize( );

Return Values

Returns the number of elements.


IDirect3DRMViewportArray::QueryInterface

Determines if the Direct3DRMViewportArray object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMViewportArray.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMViewportArray::QueryInterface method allows Direct3DRMViewportArray objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMViewportArray::Release

Decreases the reference count of the Direct3DRMViewportArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMViewportArray.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMViewportArray object deallocates itself when its reference count reaches 0. Use the IDirect3DRMViewportArray::AddRef method to increase the reference count of the object by 1.


IDirect3DRMVisualArray Interface Method Groups

Applications use the methods of the IDirect3DRMVisualArray interface to organize groups of visual objects. The methods can be organized into the following groups:

Information	GetElement
	GetSize
IUnknown	AddRef
	QueryInterface
	Release
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMVisualArray object without affecting the functionality of the original interface. In addition, the IDirect3DRMVisualArray interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMVisualArray object is obtained by calling the IDirect3DRMFrame::GetVisuals method.


IDirect3DRMVisualArray::AddRef

Increases the reference count of the Direct3DRMVisualArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMVisualArray.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMVisualArray object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMVisualArray::Release method to decrease the reference count of the object by 1.


IDirect3DRMVisualArray::GetElement

Retrieves a specified element in a Direct3DRMVisualArray object.

HRESULT GetElement(
DWORD index,
LPDIRECT3DRMVISUAL * lplpD3DRMVisual
);

Parameters

index

Element in the array.

lplpD3DRMVisual

Address that will be filled with a pointer to an IDirect3DRMVisual interface.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMVisualArray::GetSize

Retrieves the number of elements contained in a Direct3DRMVisualArray object.

DWORD GetSize( );

Return Values

Returns the number of elements.


IDirect3DRMVisualArray::QueryInterface

Determines if the Direct3DRMVisualArray object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMVisualArray.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMVisualArray::QueryInterface method allows Direct3DRMVisualArray objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMVisualArray::Release

Decreases the reference count of the Direct3DRMVisualArray object by 1. This method is part of the IUnknown interface inherited by Direct3DRMVisualArray.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMVisualArray object deallocates itself when its reference count reaches 0. Use the IDirect3DRMVisualArray::AddRef method to increase the reference count of the object by 1.


IDirect3DRM Interface


IDirect3DRM Interface Method Groups

Applications use the methods of the IDirect3DRM interface to create Direct3DRM objects and work with system-level variables. The methods can be organized into the following groups:

Animation	CreateAnimation
	CreateAnimationSet
Devices	CreateDevice
	CreateDeviceFromClipper
	CreateDeviceFromD3D
	CreateDeviceFromSurface
	GetDevices
Enumeration	EnumerateObjects
Faces	CreateFace
Frames	CreateFrame
IUnknown	AddRef
	QueryInterface
	Release
Lights	CreateLight
	CreateLightRGB
Materials	CreateMaterial
Meshes	CreateMesh
	CreateMeshBuilder
Miscellaneous	CreateObject
	CreateUserVisual
	GetNamedObject
	Load
	Tick
Search paths	AddSearchPath
	GetSearchPath
	SetSearchPath
Shadows	CreateShadow
Textures	CreateTexture
	CreateTextureFromSurface
	LoadTexture
	LoadTextureFromResource
	SetDefaultTextureColors
	SetDefaultTextureShades
Viewports	CreateViewport
Wraps	CreateWrap
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRM object without affecting the functionality of the original interface.

The IDirect3DRM COM interface is created by calling the Direct3DRMCreate function.


IDirect3DRM::AddRef

Increases the reference count of the Direct3DRM object by 1. This method is part of the IUnknown interface inherited by Direct3DRM.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRM object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRM::Release method to decrease the reference count of the object by 1.


IDirect3DRM::AddSearchPath

Adds a list of directories to the end of the current file search path.

HRESULT AddSearchPath(
LPCSTR lpPath
);

Parameters

lpPath

Address of a null-terminated string specifying the path to add to the current search path.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

For Windows, the path should be a list of directories separated by semicolons (;).

See Also

 IDirect3DRM::SetSearchPath


IDirect3DRM::CreateAnimation

Creates an empty Direct3DRMAnimation object.

HRESULT CreateAnimation(
LPDIRECT3DRMANIMATION * lplpD3DRMAnimation
);

Parameters

lplpD3DRMAnimation

Address that will be filled with a pointer to an IDirect3DRMAnimation interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::CreateAnimationSet

Creates an empty Direct3DRMAnimationSet object.

HRESULT CreateAnimationSet (
LPDIRECT3DRMANIMATIONSET * lplpD3DRMAnimationSet
);

Parameters

lplpD3DRMAnimationSet

Address that will be filled with a pointer to an IDirect3DRMAnimationSet interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::CreateDevice

Not implemented on the Windows platform.

HRESULT CreateDevice(
DWORD dwWidth,
DWORD dwHeight,
LPDIRECT3DRMDEVICE* lplpD3DRMDevice
);


IDirect3DRM::CreateDeviceFromClipper

Creates a Direct3DRM Windows device by using a specified DirectDrawClipper object.

HRESULT CreateDeviceFromClipper(
LPDIRECTDRAWCLIPPER lpDDClipper,
LPGUID lpGUID,
int width,
int height,
LPDIRECT3DRMDEVICE * lplpD3DRMDevice
);

Parameters

lpDDClipper

Address of a DirectDrawClipper object.

lpGUID

Address of a globally unique identifier (GUID). This parameter can be NULL.

width and height

Width and height of the device to be created.

lplpD3DRMDevice

Address that will be filled with a pointer to an IDirect3DRMDevice interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

If the lpGUID parameter is NULL, the system searches for a device with a default set of device capabilities. This is the recommended way to create a Retained-Mode device because it always works, even if the user installs new hardware.

The system describes the default settings by using the following flags from the D3DPRIMCAPS structure in internal device-enumeration calls:

D3DPCMPCAPS_LESSEQUAL
D3DPMISCCAPS_CULLCCW
D3DPRASTERCAPS_FOGVERTEX
D3DPSHADECAPS_ALPHAFLATSTIPPLED
D3DPTADDRESSCAPS_WRAP
D3DPTBLENDCAPS_COPY | D3DPTBLENDCAPS_MODULATE
D3DPTEXTURECAPS_PERSPECTIVE | D3DPTEXTURECAPS_TRANSPARENCY
D3DPTFILTERCAPS_NEAREST
If a hardware device is not found, the monochromatic (ramp) software driver is loaded. An application should enumerate devices instead of specifying NULL for lpGUID if it has special needs that are not met by this list of default settings.


IDirect3DRM::CreateDeviceFromD3D

Creates a Direct3DRM Windows device by using specified Direct3D objects.

HRESULT CreateDeviceFromD3D(
LPDIRECT3D lpD3D,
LPDIRECT3DDEVICE lpD3DDev,
LPDIRECT3DRMDEVICE * lplpD3DRMDevice
);

Parameters

lpD3D

Address of an instance of Direct3D.

lpD3DDev

Address of a Direct3D device object.

lplpD3DRMDevice

Address that will be filled with a pointer to an IDirect3DRMDevice interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::CreateDeviceFromSurface

Creates a Windows device for rendering from the specified DirectDraw surfaces.

HRESULT CreateDeviceFromSurface(
LPGUID lpGUID,
LPDIRECTDRAW lpDD,
LPDIRECTDRAWSURFACE lpDDSBack,
LPDIRECT3DRMDEVICE * lplpD3DRMDevice
);

Parameters

lpGUID

Address of the globally unique identifier (GUID) used as the required device driver. If this parameter is NULL, the default device driver is used.

lpDD

Address of the DirectDraw object that is the source of the DirectDraw surface.

lpDDSBack

Address of the DirectDrawSurface object that represents the back buffer.

lplpD3DRMDevice

Address that will be filled with a pointer to an IDirect3DRMDevice interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::CreateFace

Creates an instance of the IDirect3DRMFace interface.

HRESULT CreateFace(
LPDIRECT3DRMFACE * lplpd3drmFace
);

Parameters

lplpd3drmFace

Address that will be filled with a pointer to an IDirect3DRMFace interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::CreateFrame

Creates a new child frame of the given parent frame.

HRESULT CreateFrame(
LPDIRECT3DRMFRAME lpD3DRMFrame,
LPDIRECT3DRMFRAME* lplpD3DRMFrame
);

Parameters

lpD3DRMFrame

Address of a frame that is to be the parent of the new frame.

lplpD3DRMFrame

Address that will be filled with a pointer to an IDirect3DRMFrame interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The child frame inherits the motion attributes of its parent. For example, if the parent is moving with a given velocity, the child frame will also move with that velocity. Furthermore, if the parent is set rotating, the child frame will rotate about the origin of the parent. Frames that have no parent are called scenes. To create a scene, specify NULL as the parent. An application can create a frame with no parent and then attach it to a parent frame later by using the IDirect3DRMFrame::AddChild method.

See Also

 IDirect3DRMFrame::AddChild


IDirect3DRM::CreateLight

Creates a new light source with the given type and color.

HRESULT CreateLight(
D3DRMLIGHTTYPE d3drmltLightType,
D3DCOLOR cColor,
LPDIRECT3DRMLIGHT* lplpD3DRMLight
);

Parameters

d3drmltLightType

One of the lighting types given in the D3DRMLIGHTTYPE enumerated type.

cColor

Color of the light.

lplpD3DRMLight

Address that will be filled with a pointer to an IDirect3DRMLight interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::CreateLightRGB

Creates a new light source with the given type and color.

HRESULT CreateLightRGB(
D3DRMLIGHTTYPE ltLightType,
D3DVALUE vRed,
D3DVALUE vGreen,
D3DVALUE vBlue,
LPDIRECT3DRMLIGHT* lplpD3DRMLight
);

Parameters

ltLightType

One of the lighting types given in the D3DRMLIGHTTYPE enumerated type.

vRed, vGreen, and vBlue

Color of the light.

lplpD3DRMLight

Address that will be filled with a pointer to an IDirect3DRMLight interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::CreateMaterial

Creates a material with the given specular properties.

HRESULT CreateMaterial(
D3DVALUE vPower,
LPDIRECT3DRMMATERIAL * lplpD3DRMMaterial
);

Parameters

vPower

Sharpness of the reflected highlights, with a value of 5 giving a metallic look and higher values giving a more plastic look to the rendered surface.

lplpD3DRMMaterial

Address that will be filled with a pointer to an IDirect3DRMMaterial interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::CreateMesh

Creates a new mesh object with no faces. The mesh is not visible until it is added to a frame.

HRESULT CreateMesh(
LPDIRECT3DRMMESH* lplpD3DRMMesh
);

Parameters

lplpD3DRMMesh

Address that will be filled with a pointer to an IDirect3DRMMesh interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::CreateMeshBuilder

Creates a new mesh builder object.

HRESULT CreateMeshBuilder(
LPDIRECT3DRMMESHBUILDER* lplpD3DRMMeshBuilder
);

Parameters

lplpD3DRMMeshBuilder

Address that will be filled with a pointer to an IDirect3DRMMeshBuilder interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::CreateObject

Creates a new object without initializing the object.

HRESULT CreateObject(
REFCLSID rclsid,
LPUNKNOWN pUnkOuter,
REFIID riid,
LPVOID FAR* ppv
);

Parameters

rclsid

Class identifier for the new object.

pUnkOuter

Allows COM aggregation features.

riid

Interface identifier of the object to be created.

ppv

Address of a pointer to the object when the method returns.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

An application that calls this method must initialize the object that has been created. (The other creation methods of the IDirect3DRM interface initialize the object automatically.) To initialize the new object, you should use the Init method for that object. An application should call the Init method only once to initialize any given object.

Applications can use this method to implement aggregation in Direct3DRM objects.


IDirect3DRM::CreateShadow

Creates a shadow by using the specified visual and light, projecting the shadow onto the specified plane. The shadow is a visual that should be added to the frame that contains the visual.

HRESULT CreateShadow(
LPDIRECT3DRMVISUAL lpVisual,
LPDIRECT3DRMLIGHT lpLight,
D3DVALUE px,
D3DVALUE py,
D3DVALUE pz,
D3DVALUE nx,
D3DVALUE ny,
D3DVALUE nz,
LPDIRECT3DRMVISUAL * lplpShadow
);

Parameters

lpVisual

Address of the Direct3DRMVisual object that is casting the shadow.

lpLight

Address of the IDirect3DRMLight interface that is the light source.

px, py, and pz

Plane that the shadow is to be projected on.

nx, ny, and nz

Normal to the plane that the shadow is to be projected on.

lplpShadow

Address of a pointer to be initialized with a valid pointer to the shadow visual, if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::CreateTexture

Creates a texture from an image in memory.

HRESULT CreateTexture(
LPD3DRMIMAGE lpImage,
LPDIRECT3DRMTEXTURE* lplpD3DRMTexture
);

Parameters

lpImage

Address of a D3DRMIMAGE structure describing the source for the texture.

lplpD3DRMTexture

Address that will be filled with a pointer to an IDirect3DRMTexture interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The memory associated with the image is used each time the texture is rendered, rather than the memory being copied into Direct3DRM's buffers. This allows the image to be used both as a rendering target and as a texture.


IDirect3DRM::CreateTextureFromSurface

Creates a texture from a specified DirectDraw surface.

HRESULT CreateTextureFromSurface(
LPDIRECTDRAWSURFACE lpDDS,
LPDIRECT3DRMTEXTURE * lplpD3DRMTexture
);

Parameters

lpDDS

Address of the DirectDrawSurface object containing the texture.

lplpD3DRMTexture

Address that will be filled with a pointer to an IDirect3DRMTexture interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::CreateUserVisual

Creates an application-defined visual object, which can then be added to a scene and rendered by using an application-defined handler.

HRESULT CreateUserVisual(
D3DRMUSERVISUALCALLBACK fn,
LPVOID lpArg,
LPDIRECT3DRMUSERVISUAL * lplpD3DRMUV
);

Parameters

fn

Application-defined D3DRMUSERVISUALCALLBACK callback function.

lpArg

Address of application-defined data passed to the callback function.

lplpD3DRMUV

Address that will be filled with a pointer to an IDirect3DRMUserVisual interface if the call succeeds.

Return Values

Should return D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::CreateViewport

Creates a viewport on a device with device coordinates (dwXPos, dwYPos) to (dwXPos + dwWidth, dwYPos + dwHeight).

HRESULT CreateViewport(
LPDIRECT3DRMDEVICE lpDev,
LPDIRECT3DRMFRAME lpCamera,
DWORD dwXPos,
DWORD dwYPos,
DWORD dwWidth,
DWORD dwHeight,
LPDIRECT3DRMVIEWPORT* lplpD3DRMViewport
);

Parameters

lpDev

Device on which the viewport is to be created.

lpCamera

Frame that describes the position and direction of the view.

dwXPos, dwYPos, dwWidth, and dwHeight

Position and size of the viewport, in device coordinates.

lplpD3DRMViewport

Address that will be filled with a pointer to an IDirect3DRMViewport interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The viewport displays objects in the scene that contains the camera, with the view direction and up vector taken from the camera.


IDirect3DRM::CreateWrap

Creates a wrapping function that can be used to assign texture coordinates to faces and meshes. The vector [ox oy oz] gives the origin of the wrap, [dx dy dz] gives its z-axis, and [ux uy uz] gives its y-axis. The 2D vectors [ou ov] and [su sv] give an origin and scale factor in the texture applied to the result of the wrapping function.

HRESULT CreateWrap(
D3DRMWRAPTYPE type,
LPDIRECT3DRMFRAME lpRef,
D3DVALUE ox,
D3DVALUE oy,
D3DVALUE oz,
D3DVALUE dx,
D3DVALUE dy,
D3DVALUE dz,
D3DVALUE ux,
D3DVALUE uy,
D3DVALUE uz,
D3DVALUE ou,
D3DVALUE ov,
D3DVALUE su,
D3DVALUE sv,
LPDIRECT3DRMWRAP* lplpD3DRMWrap
);

Parameters

type

One of the members of the D3DRMWRAPTYPE enumerated type.

lpRef

Reference frame for the wrap.

ox, oy, and oz

Origin of the wrap.

dx, dy, and dz

The z-axis of the wrap.

ux, uy, and uz

The y-axis of the wrap.

ou and ov

Origin in the texture.

su and sv

Scale factor in the texture.

lplpD3DRMWrap

Address that will be filled with a pointer to an IDirect3DRMWrap interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMWrap


IDirect3DRM::EnumerateObjects

Calls the callback function specified by the func parameter on each of the active Direct3DRM objects.

HRESULT EnumerateObjects(
D3DRMOBJECTCALLBACK func,
LPVOID lpArg
);

Parameters

func

Application-defined D3DRMOBJECTCALLBACK callback function to be called with each Direct3DRMObject object and the application-defined argument.

lpArg

Address of application-defined data passed to the callback function.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::GetDevices

Returns all the Direct3DRM devices that have been created in the system.

HRESULT GetDevices(
LPDIRECT3DRMDEVICEARRAY* lplpDevArray
);

Parameters

lplpDevArray

Address of a pointer that will be filled with the resulting array of Direct3DRM devices. For information about the Direct3DRMDeviceArray object, see the IDirect3DRMDeviceArray interface.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::GetNamedObject

Finds a Direct3DRMObject, given its name.

HRESULT GetNamedObject(
const char * lpName,
LPDIRECT3DRMOBJECT* lplpD3DRMObject
);

Parameters

lpName

Name of the object to be searched for.

lplpD3DRMObject

Address of a pointer to be initialized with a valid Direct3DRMObject pointer if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::GetSearchPath

Returns the current file search path.

HRESULT GetSearchPath(
DWORD * lpdwSize,
LPSTR lpszPath
);

Parameters

lpdwSize

Address of the number of returned path elements. This parameter cannot be NULL.

lpszPath

Address of a null-terminated string specifying the search path. If this parameter is NULL, the method returns the size of the required string in the location pointed to by the lpdwSize parameter.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRM::SetSearchPath


IDirect3DRM::Load

Loads an object.

HRESULT Load(
LPVOID lpvObjSource,
LPVOID lpvObjID,
LPIID * lplpGUIDs,
DWORD dwcGUIDs,
D3DRMLOADOPTIONS d3drmLOFlags,
D3DRMLOADCALLBACK d3drmLoadProc,
LPVOID lpArgLP,
D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc,
LPVOID lpArgLTP,
LPDIRECT3DRMFRAME lpParentFrame
);

Parameters

lpvObjSource

Source for the object to be loaded. This source can be a file, resource, memory block, or stream, depending on the source flags specified in the d3drmLOFlags parameter.

lpvObjID

Object name or position to be loaded. The use of this parameter depends on the identifier flags specified in the d3drmLOFlags parameter. If the D3DRMLOAD_BYPOSITION flag is specified, this parameter is a pointer to a DWORD value that gives the object's order in the file. This parameter can be NULL.

lplpGUIDs

Address of an array of interface identifiers to be loaded. For example, if this parameter is a two-element array containing IID_IDirect3DMeshBuilder and IID_IDirect3DRMAnimationSet, this method loads all the animation sets and mesh-builder objects.

dwcGUIDs

Number of elements specified in the lplpGUIDs parameter.

d3drmLOFlags

Value of the D3DRMLOADOPTIONS type describing the load options.

d3drmLoadProc

A D3DRMLOADCALLBACK callback function called when the system reads the specified object.

lpArgLP

Address of application-defined data passed to the D3DRMLOADCALLBACK callback function.

d3drmLoadTextureProc

A D3DRMLOADTEXTURECALLBACK callback function called to load any textures used by an object.

lpArgLTP

Address of application-defined data passed to the D3DRMLOADTEXTURECALLBACK callback function.

lpParentFrame

Address of a parent frame. This information is useful when loading Direct3DRMAnimationSet or Direct3DRMFrame objects because these objects would be created with a NULL parent otherwise. This value can be NULL.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::LoadTexture

Loads a texture from the specified file. This texture can have 8, 24, or 32 bits-per-pixel, and it should be in either the Windows bitmap (.bmp) or Portable Pixmap (.ppm) P6 format.

HRESULT LoadTexture(
const char * lpFileName,
LPDIRECT3DRMTEXTURE* lplpD3DRMTexture
);

Parameters

lpFileName

Name of the required .bmp or .ppm file.

lplpD3DRMTexture

Address of a pointer to be initialized with a valid Direct3DRMTexture pointer if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::LoadTextureFromResource

Loads a texture from a specified resource.

HRESULT LoadTextureFromResource(
HRSRC rs,
LPDIRECT3DRMTEXTURE * lplpD3DRMTexture
);

Parameters

rs

Handle of the resource.

lplpD3DRMTexture

Address of a pointer to be initialized with a valid Direct3DRMTexture object if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRM::QueryInterface

Determines if the Direct3DRM object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRM.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRM::QueryInterface method allows Direct3DRM objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRM::Release

Decreases the reference count of the Direct3DRM object by 1. This method is part of the IUnknown interface inherited by Direct3DRM.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRM object deallocates itself when its reference count reaches 0. Use the IDirect3DRM::AddRef method to increase the reference count of the object by 1.


IDirect3DRM::SetDefaultTextureColors

Sets the default colors to be used for a Direct3DRMTexture object.

HRESULT SetDefaultTextureColors(
DWORD dwColors
);

Parameters

dwColors

Number of colors.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

This method affects the texture colors only when it is called before the IDirect3DRM::CreateTexture method; it has no effect on textures that have already been created.


IDirect3DRM::SetDefaultTextureShades

Sets the default shades to be used for an Direct3DRMTexture object.

HRESULT SetDefaultTextureShades(
DWORD dwShades
);

Parameters

dwShades

Number of shades.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

This method affects the texture shades only when it is called before the IDirect3DRM::CreateTexture method; it has no effect on textures that have already been created.


IDirect3DRM::SetSearchPath

Sets the current file search path from a list of directories.

HRESULT SetSearchPath(
LPCSTR lpPath
);

Parameters

lpPath

Address of a null-terminated string specifying the path to set as the current search path.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The default search path is taken from the value of the D3DPATH environment variable. If this is not set, the search path will be empty. When opening a file, the system first looks for the file in the current working directory and then checks every directory in the search path.

See Also

 IDirect3DRM::GetSearchPath


IDirect3DRM::Tick

Performs the Direct3DRM system heartbeat. When this method is called, the positions of all moving frames are updated according to their current motion attributes, the scene is rendered to the current device, and relevant callback functions are called at their appropriate times. Control is returned when the rendering cycle is complete.

HRESULT Tick(
D3DVALUE d3dvalTick
);

Parameters

d3dvalTick

Velocity and rotation step for the IDirect3DRMFrame::SetRotation and IDirect3DRMFrame::SetVelocity methods.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

You can implement this method by using other Retained-Mode methods to allow more flexibility in rendering a scene.


IDirect3DRMAnimation Interface


IDirect3DRMAnimation Interface Method Groups

Applications use the methods of the IDirect3DRMAnimation interface to animate the position, orientation, and scaling of visuals, lights, and viewports. The methods can be organized into the following groups:

IUnknown	AddRef
	QueryInterface
	Release
Keys	AddPositionKey
	AddRotateKey
	AddScaleKey
	DeleteKey
Miscellaneous	SetFrame
	SetTime
Options	GetOptions
	SetOptions
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMAnimation object without affecting the functionality of the original interface. In addition, the IDirect3DRMAnimation interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMAnimation object is obtained by calling the IDirect3DRM::CreateAnimation method.


IDirect3DRMAnimation::AddPositionKey

Adds a position key to the animation.

HRESULT AddPositionKey(
D3DVALUE rvTime,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ
);

Parameters

rvTime

Time in the animation to store the position key. The time units are arbitrary and zero-based; a key whose rvTime value is 49 occurs exactly in the middle of an animation whose last key has an rvTime value of 99.

rvX, rvY, and rvZ

Position.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The transformation applied by this method is a translation. For information about the matrix mathematics involved in transformations, see 3D Transformations.

See Also

 IDirect3DRMAnimation::DeleteKey


IDirect3DRMAnimation::AddRef

Increases the reference count of the Direct3DRMAnimation object by 1. This method is part of the IUnknown interface inherited by Direct3DRMAnimation.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMAnimation object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMAnimation::Release method to decrease the reference count of the object by 1.


IDirect3DRMAnimation::AddRotateKey

Adds a rotate key to the animation.

HRESULT AddRotateKey(
D3DVALUE rvTime,
D3DRMQUATERNION *rqQuat
);

Parameters

rvTime

Time in the animation to store the rotate key. The time units are arbitrary and zero-based; a key whose rvTime value is 49 occurs exactly in the middle of an animation whose last key has an rvTime value of 99.

rqQuat

Quaternion representing the rotation.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

This method applies a rotation transformation. For information about the matrix mathematics involved in transformations, see 3D Transformations.

See Also

 IDirect3DRMAnimation::DeleteKey


IDirect3DRMAnimation::AddScaleKey

Adds a scale key to the animation.

HRESULT AddScaleKey(
D3DVALUE rvTime,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ
);

Parameters

rvTime

Time in the animation to store the scale key. The time units are arbitrary and zero-based; a key whose rvTime value is 49 occurs exactly in the middle of an animation whose last key has an rvTime value of 99.

rvX, rvY, and rvZ

Scale factor.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

This method applies a scaling transformation. For information about the matrix mathematics involved in transformations, see 3D Transformations.

See Also

 IDirect3DRMAnimation::DeleteKey


IDirect3DRMAnimation::DeleteKey

Removes a key from an animation.

HRESULT DeleteKey(
D3DVALUE rvTime
);

Parameters

rvTime

Time identifying the key that will be removed from the animation.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMAnimation::GetOptions

Retrieves animation options.

D3DRMANIMATIONOPTIONS GetOptions( );

Return Values

Returns the value of the D3DRMANIMATIONOPTIONS type describing the animation options.

See Also

 IDirect3DRMAnimation::SetOptions


IDirect3DRMAnimation::QueryInterface

Determines if the Direct3DRMAnimation object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMAnimation.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows Direct3DRMAnimation objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMAnimation::Release

Decreases the reference count of the Direct3DRMAnimation object by 1. This method is part of the IUnknown interface inherited by Direct3DRMAnimation.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMAnimation object deallocates itself when its reference count reaches 0. Use the IDirect3DRMAnimation::AddRef method to increase the reference count of the object by 1.


IDirect3DRMAnimation::SetFrame

Sets the frame for the animation.

HRESULT SetFrame(
LPDIRECT3DRMFRAME lpD3DRMFrame
);

Parameters

lpD3DRMFrame

Address of a variable representing the frame to set for the animation.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMAnimation::SetOptions

Sets the animation options.

HRESULT SetOptions(
D3DRMANIMATIONOPTIONS d3drmanimFlags
);

Parameters

d3drmanimFlags

Value of the D3DRMANIMATIONOPTIONS type describing the animation options.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMAnimation::GetOptions


IDirect3DRMAnimation::SetTime

Sets the current time for this animation.

HRESULT SetTime(
D3DVALUE rvTime
);

Parameters

rvTime

New current time for the animation. The time units are arbitrary and zero-based; a key whose rvTime value is 49 occurs exactly in the middle of an animation whose last key has an rvTime value of 99.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMAnimationSet Interface


IDirect3DRMAnimationSet Interface Method Groups

Applications use the methods of the IDirect3DRMAnimationSet interface to group Direct3DRMAnimation objects together, which can simplify the playback of complex animation sequences. The methods can be organized into the following groups:

Adding, loading,	AddAnimation
and removing	DeleteAnimation
	Load
IUnknown	AddRef
	QueryInterface
	Release
Time	SetTime
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMAnimationSet object without affecting the functionality of the original interface. In addition, the IDirect3DRMAnimationSet interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMAnimationSet object is obtained by calling the IDirect3DRM::CreateAnimationSet method.


IDirect3DRMAnimationSet::AddAnimation

Adds an animation to the animation set.

HRESULT AddAnimation(
LPDIRECT3DRMANIMATION lpD3DRMAnimation
);

Parameters

lpD3DRMAnimation

Address of the Direct3DRMAnimation object to be added to the animation set.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMAnimationSet::AddRef

Increases the reference count of the Direct3DRMAnimationSet object by 1. This method is part of the IUnknown interface inherited by Direct3DRMAnimationSet.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMAnimationSet object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMAnimationSet::Release method to decrease the reference count of the object by 1.


IDirect3DRMAnimationSet::DeleteAnimation

Removes a previously added animation from the animation set.

HRESULT DeleteAnimation(
LPDIRECT3DRMANIMATION lpD3DRMAnimation
);

Parameters

lpD3DRMAnimation

Address of the Direct3DRMAnimation object to be removed from the animation set.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMAnimationSet::Load

Loads an animation set.

HRESULT Load(
LPVOID lpvObjSource,
LPVOID lpvObjID,
D3DRMLOADOPTIONS d3drmLOFlags,
D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc,
LPVOID lpArgLTP,
LPDIRECT3DRMFRAME lpParentFrame
);

Parameters

lpvObjSource

Source for the object to be loaded. This source can be a file, resource, memory block, or stream, depending on the source flags specified in the d3drmLOFlags parameter.

lpvObjID

Object name or position to be loaded. The use of this parameter depends on the identifier flags specified in the d3drmLOFlags parameter. If the D3DRMLOAD_BYPOSITION flag is specified, this parameter is a pointer to a DWORD value that gives the object's order in the file. This parameter can be NULL.

d3drmLOFlags

Value of the D3DRMLOADOPTIONS type describing the load options.

d3drmLoadTextureProc

A D3DRMLOADTEXTURECALLBACK callback function called to load any textures used by the object.

lpArgLTP

Address of application-defined data passed to the D3DRMLOADTEXTURECALLBACK callback function.

lpParentFrame

Address of a parent Direct3DRMFrame object. This prevents the frames referred to by the animation set from being created with a NULL parent.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

By default, this method loads the first animation set in the file specified by the lpvObjSource parameter.


IDirect3DRMAnimationSet::QueryInterface

Determines if the Direct3DRMAnimationSet object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMAnimationSet.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMAnimationSet::QueryInterface method allows Direct3DRMAnimationSet objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMAnimationSet::Release

Decreases the reference count of the Direct3DRMAnimationSet object by 1. This method is part of the IUnknown interface inherited by Direct3DRMAnimationSet.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMAnimationSet object deallocates itself when its reference count reaches 0. Use the IDirect3DRMAnimationSet::AddRef method to increase the reference count of the object by 1.


IDirect3DRMAnimationSet::SetTime

Sets the time for this animation set.

HRESULT SetTime(
D3DVALUE rvTime
);

Parameters

rvTime

New time.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMDevice Interface


IDirect3DRMDevice Interface Method Groups

Applications use the methods of the IDirect3DRMDevice interface to interact with the output device. The methods can be organized into the following groups:

Buffer counts	GetBufferCount
	SetBufferCount
Color models	GetColorModel
Dithering	GetDither
	SetDither
Initialization	Init
	InitFromClipper
	InitFromD3D
IUnknown	AddRef
	QueryInterface
	Release
Miscellaneous	GetDirect3DDevice
	GetHeight
	GetTrianglesDrawn
	GetViewports
	GetWidth
	GetWireframeOptions
	Update
Notifications	AddUpdateCallback
	DeleteUpdateCallback
Rendering quality	GetQuality
	SetQuality
Shading	GetShades
	SetShades
Texture quality	GetTextureQuality
	SetTextureQuality
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMDevice object without affecting the functionality of the original interface. In addition, the IDirect3DRMDevice interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMDevice object is obtained by calling the IDirect3DRM::CreateDevice method.


IDirect3DRMDevice::AddRef

Increases the reference count of the Direct3DRMDevice object by 1. This method is part of the IUnknown interface inherited by Direct3DRMDevice.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMDevice object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMDevice::Release method to decrease the reference count of the object by 1.


IDirect3DRMDevice::AddUpdateCallback

Adds a callback function that alerts the application when a change occurs to the device. The system calls this callback function whenever the application calls the IDirect3DRMDevice::Update method.

HRESULT AddUpdateCallback(
D3DRMUPDATECALLBACK d3drmUpdateProc,
LPVOID arg
);

Parameters

d3drmUpdateProc

Address of an application-defined callback function, D3DRMUPDATECALLBACK.

arg

Private data to be passed to the update callback function.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMDevice::DeleteUpdateCallback, IDirect3DRMDevice::Update, D3DRMUPDATECALLBACK


IDirect3DRMDevice::DeleteUpdateCallback

Removes an update callback function that was added by calling the IDirect3DRMDevice::AddUpdateCallback method.

HRESULT DeleteUpdateCallback(
D3DRMUPDATECALLBACK d3drmUpdateProc,
LPVOID arg
);

Parameters

d3drmUpdateProc

Address of an application-defined callback function, D3DRMUPDATECALLBACK.

arg

Private data that was passed to the update callback function.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMDevice::AddUpdateCallback, IDirect3DRMDevice::Update, D3DRMUPDATECALLBACK


IDirect3DRMDevice::GetBufferCount

Retrieves the value set in a call to the IDirect3DRMDevice::SetBufferCount method.

DWORD GetBufferCount( );

Return Values

Returns the number of buffers—one for single-buffering, two for double-buffering, and so on.


IDirect3DRMDevice::GetColorModel

Retrieves the color model of a device.

D3DCOLORMODEL GetColorModel( );

Return Values

Returns a value from the D3DCOLORMODEL enumerated type that describes the Direct3D color model (RGB or monochrome).

See Also

 Color Models


IDirect3DRMDevice::GetDirect3DDevice

Retrieves a pointer to an Immediate-Mode device.

HRESULT GetDirect3DDevice(
LPDIRECT3DDEVICE * lplpD3DDevice
);

Parameters

lplpD3DDevice

Address of a pointer that is initialized with a pointer to an Immediate-Mode device object.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMDevice::GetDither

Retrieves the dither flag for the device.

BOOL GetDither( );

Return Values

Returns TRUE if the dither flag is set, or FALSE otherwise.

See Also

 IDirect3DRMDevice::SetDither


IDirect3DRMDevice::GetHeight

Retrieves the height, in pixels, of a device. This method is a convenience function.

DWORD GetHeight( );

Return Values

Returns the height.


IDirect3DRMDevice::GetTrianglesDrawn

Retrieves the number of triangles drawn to a device since its creation. This method is a convenience function.

DWORD GetTrianglesDrawn( );

Return Values

Returns the number of triangles.

Remarks

The number of triangles includes those that were passed to the renderer but were not drawn because they were backfacing. The number does not include triangles that were rejected for lying outside of the viewing frustum.


IDirect3DRMDevice::GetQuality

Retrieves the rendering quality for the device.

D3DRMRENDERQUALITY GetQuality( );

Return Values

Returns one or more of the members of the enumerated types represented by the D3DRMRENDERQUALITY type.

See Also

 IDirect3DRMDevice::SetQuality


IDirect3DRMDevice::GetShades

Retrieves the number of shades in a ramp of colors used for shading.

DWORD GetShades( );

Return Values

Returns the number of shades.

See Also

 IDirect3DRMDevice::SetShades


IDirect3DRMDevice::GetTextureQuality

Retrieves the current texture quality parameter for the device. Texture quality is relevant only for an RGB device.

D3DRMTEXTUREQUALITY GetTextureQuality( );

Return Values

Returns one of the members of the D3DRMTEXTUREQUALITY enumerated type.

See Also

 IDirect3DRMDevice::SetTextureQuality


IDirect3DRMDevice::GetViewports

Constructs a Direct3DRMViewportArray object that represents the viewports currently constructed from the device.

HRESULT GetViewports(
LPDIRECT3DRMVIEWPORTARRAY* lplpViewports
);

Parameters

lplpViewports

Address of a pointer that is initialized with a valid Direct3DRMViewportArray object if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMDevice::GetWidth

Retrieves the width, in pixels, of a device. This method is a convenience function.

DWORD GetWidth( );

Return Values

Returns the width.


IDirect3DRMDevice::GetWireframeOptions

Retrieves the wireframe options of a given device.

DWORD GetWireframeOptions( );

Return Values

Returns a bitwise OR of the following values:

D3DRMWIREFRAME_CULL

	The backfacing faces are not drawn.
D3DRMWIREFRAME_HIDDENLINE

	Wireframe-rendered lines are obscured by nearer objects.


IDirect3DRMDevice::Init

Not implemented on the Windows platform.

HRESULT Init(
ULONG width,
ULONG height
);


IDirect3DRMDevice::InitFromClipper

Initializes a device from a specified DirectDrawClipper object.

HRESULT InitFromClipper(
LPDIRECTDRAWCLIPPER lpDDClipper,
LPGUID lpGUID,
int width,
int height
);

Parameters

lpDDClipper

Address of the DirectDrawClipper object to use as an initializer.

lpGUID

Address of the globally unique identifier (GUID) used as the interface identifier.

width and height

Width and height of the device.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMDevice::InitFromD3D

Initializes a Retained-Mode device from a specified Direct3D Immediate-Mode object and Immediate-Mode device.

HRESULT InitFromD3D(
LPDIRECT3D lpD3D,
LPDIRECT3DDEVICE lpD3DIMDev
);

Parameters

lpD3D

Address of the Direct3D Immediate-Mode object to use to initialize the Retained-Mode device.

lpD3DIMDev

Address of the Immediate-Mode device to use to initialize the Retained-Mode device.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMDevice::QueryInterface

Determines if the Direct3DRMDevice object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMDevice.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMDevice::QueryInterface method allows Direct3DRMDevice objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMDevice::Release

Decreases the reference count of the Direct3DRMDevice object by 1. This method is part of the IUnknown interface inherited by Direct3DRMDevice.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMDevice object deallocates itself when its reference count reaches 0. Use the IDirect3DRMDevice::AddRef method to increase the reference count of the object by 1.


IDirect3DRMDevice::SetBufferCount

Sets the number of buffers currently being used by the application.

HRESULT SetBufferCount(
DWORD dwCount
);

Parameters

dwCount

Specifies the number of buffers—one for single-buffering, two for double-buffering, and so on. The default value is 1, which is correct only for single-buffered window operation.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

An application that employs double-buffering or triple-buffering must use this method to inform the system of how many buffers it is using so that the system can calculate how much of the window to clear and update on each frame.

See Also

 IDirect3DRMDevice::GetBufferCount


IDirect3DRMDevice::SetDither

Sets the dither flag for the device.

HRESULT SetDither(
BOOL bDither
);

Parameters

bDither

New dithering mode for the device. The default is TRUE.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMDevice::GetDither


IDirect3DRMDevice::SetQuality

Sets the rendering quality of a device

HRESULT SetQuality (
D3DRMRENDERQUALITY rqQuality
);

Parameters

rqQuality

One or more of the members of the enumerated types represented by the D3DRMRENDERQUALITY type. The default setting is D3DRMRENDER_FLAT.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The rendering quality is the maximum quality at which rendering can take place on the rendering surface of that device. Each mesh can have its own quality, but the maximum quality available for a mesh is that of the device. Different devices can have different qualities. For example, previewing devices usually have a lower quality, while devices used for final viewing usually have a higher quality.

See Also

 IDirect3DRMDevice::GetQuality


IDirect3DRMDevice::SetShades

Sets the number of shades in a ramp of colors used for shading.

HRESULT SetShades(
DWORD ulShades
);

Parameters

ulShades

New number of shades. This parameter must be a power of 2. The default is 32.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMDevice::GetShades


IDirect3DRMDevice::SetTextureQuality

Sets the texture quality for the device.

HRESULT SetTextureQuality(
D3DRMTEXTUREQUALITY tqTextureQuality
);

Parameters

tqTextureQuality

One of the members of the D3DRMTEXTUREQUALITY enumerated type. The default is D3DRMTEXTURE_NEAREST.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMDevice::GetTextureQuality


IDirect3DRMDevice::Update

Copies the image that has been rendered to the display. It also provides a heartbeat function to the device driver.

HRESULT Update( );

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

Each call to this method causes the system to call an application-defined callback function, D3DRMUPDATECALLBACK. To add a callback function, use the IDirect3DRMDevice::AddUpdateCallback method.

See Also

 IDirect3DRMDevice::AddUpdateCallback, D3DRMUPDATECALLBACK


IDirect3DRMFace Interface


IDirect3DRMFace Interface Method Groups

Applications use the methods of the IDirect3DRMFace interface to interact with a single polygon in a mesh. The methods can be organized into the following groups:

Color	GetColor
	SetColor
	SetColorRGB
IUnknown	AddRef
	QueryInterface
	Release
Materials	GetMaterial
	SetMaterial
Textures	GetTexture
	GetTextureCoordinateIndex
	GetTextureCoordinates
	GetTextureTopology
	SetTexture
	SetTextureCoordinates
	SetTextureTopology
Vertices and normals	AddVertex
	AddVertexAndNormalIndexed
	GetNormal
	GetVertex
	GetVertexCount
	GetVertexIndex
	GetVertices
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMFace object without affecting the functionality of the original interface. In addition, the IDirect3DRMFace interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMFace object is obtained by calling the IDirect3DRM::CreateFace method.


IDirect3DRMFace::AddRef

Increases the reference count of the Direct3DRMFace object by 1. This method is part of the IUnknown interface inherited by Direct3DRMFace.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMFace object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMFace::Release method to decrease the reference count of the object by 1.


IDirect3DRMFace::AddVertex

Adds a vertex to a Direct3DRMFace object.

HRESULT AddVertex(
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);

Parameters

x, y, and z

The x, y, and z components of the position of the new vertex.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFace::AddVertexAndNormalIndexed

Adds a vertex and a normal to a Direct3DRMFace object, using an index for the vertex and an index for the normal in the containing mesh builder. The face, vertex, and normal must already be part of a Direct3DRMMeshBuilder object.

HRESULT AddVertexAndNormalIndexed(
DWORD vertex,
DWORD normal
);

Parameters

vertex and normal

Indexes of the vertex and normal to add.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFace::GetColor

Retrieves the color of a Direct3DRMFace object.

D3DCOLOR GetColor( );

Return Values

Returns the color.

See Also

 IDirect3DRMFace::SetColor


IDirect3DRMFace::GetMaterial

Retrieves the material of a Direct3DRMFace object.

HRESULT GetMaterial(
LPDIRECT3DRMMATERIAL* lplpMaterial
);

Parameters

lplpMaterial

Address of a variable that will be filled with a pointer to the Direct3DRMMaterial object applied to the face.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFace::SetMaterial


IDirect3DRMFace::GetNormal

Retrieves the normal of a Direct3DRMFace object.

HRESULT GetNormal(
D3DVECTOR *lpNormal
);

Parameters

lpNormal

Address of a D3DVECTOR structure that will be filled with the normal vector of the face.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFace::GetTexture

Retrieves the Direct3DRMTexture object applied to a Direct3DRMFace object.

HRESULT GetTexture(
LPDIRECT3DRMTEXTURE* lplpTexture
);

Parameters

lplpTexture

Address of a variable that will be filled with a pointer to the texture applied to the face.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFace::SetTexture


IDirect3DRMFace::GetTextureCoordinateIndex

Retrieves the index of the vertex for texture coordinates in the face's mesh. This index corresponds to the index specified in the dwIndex parameter.

int GetTextureCoordinateIndex(
DWORD dwIndex
);

Parameters

dwIndex

Index within the face of the vertex.

Return Values

Returns the index.


IDirect3DRMFace::GetTextureCoordinates

Retrieves the texture coordinates of a vertex in a Direct3DRMFace object.

HRESULT GetTextureCoordinates(
DWORD index,
D3DVALUE *lpU,
D3DVALUE *lpV
);

Parameters

index

Index of the vertex.

lpU and lpV

Addresses of variables that are filled with the texture coordinates of the vertex.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFace::GetTextureTopology

Retrieves the texture topology of a Direct3DRMFace object.

HRESULT GetTextureTopology(
BOOL *lpU,
BOOL *lpV
);

Parameters

lpU and lpV

Addresses of variables that are set or cleared depending on how the cylindrical wrapping flags are set for the face.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFace::SetTextureTopology


IDirect3DRMFace::GetVertex

Retrieves the position and normal of a vertex in a Direct3DRMFace object.

HRESULT GetVertex(
DWORD index,
D3DVECTOR *lpPosition,
D3DVECTOR *lpNormal
);

Parameters

index

Index of the vertex.

lpPosition and lpNormal

Addresses of D3DVECTOR structures that will be filled with the position and normal of the vertex, respectively.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFace::GetVertexCount

Retrieves the number of vertices in a Direct3DRMFace object.

int GetVertexCount( );

Return Values

Returns the number of vertices.


IDirect3DRMFace::GetVertexIndex

Retrieves the index of the vertex in the face's mesh. This index corresponds to the index specified in the dwIndex parameter.

int GetVertexIndex (
DWORD dwIndex
);

Parameters

dwIndex

Index within the face of the vertex.

Return Values

Returns the index.


IDirect3DRMFace::GetVertices

Retrieves the position and normal of each vertex in a Direct3DRMFace object.

HRESULT GetVertices(
DWORD *lpdwVertexCount,
D3DVECTOR *lpPosition,
D3DVECTOR *lpNormal
);

Parameters

lpdwVertexCount

Address of a variable that is filled with the number of vertices. This parameter cannot be NULL.

lpPosition and lpNormal

Arrays of D3DVECTOR structures that will be filled with the positions and normal vectors of the vertices, respectively. If both of these parameters are NULL, the method will fill the lpdwVertexCount parameter with the number of vertices that will be retrieved.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFace::QueryInterface

Determines if the Direct3DRMFace object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMFace.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that is filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMFace::QueryInterface method allows Direct3DRMFace objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMFace::Release

Decreases the reference count of the Direct3DRMFace object by 1. This method is part of the IUnknown interface inherited by Direct3DRMFace.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMFace object deallocates itself when its reference count reaches 0. Use the IDirect3DRMFace::AddRef method to increase the reference count of the object by 1.


IDirect3DRMFace::SetColor

Sets a Direct3DRMFace object to a given color.

HRESULT SetColor(
D3DCOLOR color
);

Parameters

color

Color to set.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFace::GetColor


IDirect3DRMFace::SetColorRGB

Sets a Direct3DRMFace object to a given color.

HRESULT SetColorRGB(
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);

Parameters

red, green, and blue

The red, green, and blue components of the color.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFace::SetMaterial

Sets the material of a Direct3DRMFace object.

HRESULT SetMaterial(
LPDIRECT3DRMMATERIAL lpD3DRMMaterial
);

Parameters

lpD3DRMMaterial

Address of the material.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFace::GetMaterial


IDirect3DRMFace::SetTexture

Sets the texture of a Direct3DRMFace object.

HRESULT SetTexture(
LPDIRECT3DRMTEXTURE lpD3DRMTexture
);

Parameters

lpD3DRMTexture

Address of the texture.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFace::GetTexture


IDirect3DRMFace::SetTextureCoordinates

Sets the texture coordinates of a specified vertex in a Direct3DRMFace object.

HRESULT SetTextureCoordinates(
DWORD vertex,
D3DVALUE u,
D3DVALUE v
);

Parameters

vertex

Index of the vertex to be set. For example, if the face were a triangle, the possible vertex indices would be 0, 1, and 2.

u and v

Texture coordinates to assign to the specified vertex.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFace::SetTextureTopology

Sets the texture topology of a Direct3DRMFace object.

HRESULT SetTextureTopology(
BOOL cylU,
BOOL cylV
);

Parameters

cylU and cylV

Specify whether the texture has a cylindrical topology in the u and v dimensions.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFace::GetTextureTopology


IDirect3DRMFrame Interface


IDirect3DRMFrame Interface Method Groups

Applications use the methods of the IDirect3DRMFrame interface to interact with frames—an object's frame of reference. The methods can be organized into the following groups:

Background	GetSceneBackground
	GetSceneBackgroundDepth
	SetSceneBackground
	SetSceneBackgroundDepth
	SetSceneBackgroundImage
	SetSceneBackgroundRGB
Color	GetColor
	SetColor
	SetColorRGB
Fog	GetSceneFogColor
	GetSceneFogEnable
	GetSceneFogMode
	GetSceneFogParams
	SetSceneFogColor
	SetSceneFogEnable
	SetSceneFogMode
	SetSceneFogParams
Hierarchies	AddChild
	DeleteChild
	GetChildren
	GetParent
	GetScene
IUnknown	AddRef
	QueryInterface
	Release
Lighting	AddLight
	DeleteLight
	GetLights
Loading	Load
Material modes	GetMaterialMode
	SetMaterialMode
Positioning and	AddMoveCallback
movement	AddRotation
	AddScale
	AddTranslation
	DeleteMoveCallback
	GetOrientation
	GetPosition
	GetRotation
	GetVelocity
	LookAt
	Move
	SetOrientation
	SetPosition
	SetRotation
	SetVelocity
Sorting	GetSortMode
	GetZbufferMode
	SetSortMode
	SetZbufferMode
Textures	GetTexture
	GetTextureTopology
	SetTexture
	SetTextureTopology
Transformations	AddTransform
	GetTransform
	InverseTransform
	Transform
Visual objects	AddVisual
	DeleteVisual
	GetVisuals
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMFrame object without affecting the functionality of the original interface. In addition, the IDirect3DRMFrame interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMFrame object is obtained by calling the IDirect3DRM::CreateFrame method.


IDirect3DRMFrame::AddChild

Adds a child frame to a frame hierarchy.

HRESULT AddChild(
LPDIRECT3DRMFRAME lpD3DRMFrameChild
);

Parameters

lpD3DRMFrameChild

Address of the Direct3DRMFrame object that will be added as a child.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

If the frame being added as a child already has a parent, this method removes it from its previous parent before adding it to the new parent.

See Also

 Hierarchies


IDirect3DRMFrame::AddLight

Adds a light to a frame.

HRESULT AddLight(
LPDIRECT3DRMLIGHT lpD3DRMLight
);

Parameters

lpD3DRMLight

Address of a variable that represents the Direct3DRMLight object to be added to the frame.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFrame::AddMoveCallback

Adds a callback function for special movement processing.

HRESULT AddMoveCallback(
D3DRMFRAMEMOVECALLBACK d3drmFMC,
VOID * lpArg
);

Parameters

d3drmFMC

Application-defined D3DRMFRAMEMOVECALLBACK callback function.

lpArg

Application-defined data to be passed to the callback function.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::Move, IDirect3DRMFrame::DeleteMoveCallback


IDirect3DRMFrame::AddRef

Increases the reference count of the Direct3DRMFrame object by 1. This method is part of the IUnknown interface inherited by Direct3DRMFrame.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMFrame object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMFrame::Release method to decrease the reference count of the object by 1.


IDirect3DRMFrame::AddRotation

Adds a rotation about (rvX, rvY, rvZ) by the number of radians specified in rvTheta.

HRESULT AddRotation(
D3DRMCOMBINETYPE rctCombine,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ,
D3DVALUE rvTheta
);

Parameters

rctCombine

A member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new rotation with any current frame transformation.

rvX, rvY, and rvZ

Axis about which to rotate.

rvTheta

Angle of rotation, in radians.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The specified rotation changes the matrix only for the frame identified by this IDirect3DRMFrame interface. This method changes the objects in the frame only once, unlike IDirect3DRMFrame::SetRotation, which changes the matrix with every render tick.

See Also

 3D Transformations, IDirect3DRMFrame::SetRotation


IDirect3DRMFrame::AddScale

Scales a frame's local transformation by (rvX, rvY, rvZ).

HRESULT AddScale(
D3DRMCOMBINETYPE rctCombine,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ
);

Parameters

rctCombine

Member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new scale with any current frame transformation.

rvX, rvY, and rvZ

Define the scale factors in the x, y, and z directions.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The specified transformation changes the matrix only for the frame identified by this IDirect3DRMFrame interface.

See Also

 3D Transformations


IDirect3DRMFrame::AddTransform

Transforms the local coordinates of the frame by the given affine transformation according to the value of the rctCombine parameter.

HRESULT AddTransform(
D3DRMCOMBINETYPE rctCombine,
D3DRMMATRIX4D rmMatrix
);

Parameters

rctCombine

Member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new transformation with any current transformation.

rmMatrix

Member of the D3DRMMATRIX4D array that defines the transformation matrix to be combined.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

Although a 4-by-4 matrix is given, the last column must be the transpose of [0 0 0 1] for the transformation to be affine.

The specified transformation changes the matrix only for the frame identified by this IDirect3DRMFrame interface.

See Also

 3D Transformations


IDirect3DRMFrame::AddTranslation

Adds a translation by (rvX, rvY, rvZ) to a frame's local coordinate system.

HRESULT AddTranslation(
D3DRMCOMBINETYPE rctCombine,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ
);

Parameters

rctCombine

Member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new translation with any current translation.

rvX, rvY, and rvZ

Define the position changes in the x, y, and z directions.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The specified translation changes the matrix only for the frame identified by this IDirect3DRMFrame interface.

See Also

 3D Transformations


IDirect3DRMFrame::AddVisual

Adds a visual object to a frame.

HRESULT AddVisual(
LPDIRECT3DRMVISUAL lpD3DRMVisual
);

Parameters

lpD3DRMVisual

Address of a variable that represents the Direct3DRMVisual object to be added to the frame.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

Visual objects include meshes and textures. When a visual object is added to a frame, it becomes visible if the frame is in view. The visual object is referenced by the frame.


IDirect3DRMFrame::DeleteChild

Removes a frame from the hierarchy. If the frame is not referenced, it is destroyed along with any child frames, lights, and meshes.

HRESULT DeleteChild(
LPDIRECT3DRMFRAME lpChild
);

Parameters

lpChild

Address of a variable that represents the Direct3DRMFrame object to be used as the child.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 Hierarchies


IDirect3DRMFrame::DeleteLight

Removes a light from a frame, destroying it if it is no longer referenced. When a light is removed from a frame, it no longer affects meshes in the scene its frame was in.

HRESULT DeleteLight(
LPDIRECT3DRMLIGHT lpD3DRMLight
);

Parameters

lpD3DRMLight

Address of a variable that represents the Direct3DRMLight object to be removed.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFrame::DeleteMoveCallback

Removes a callback function that performed special movement processing.

HRESULT DeleteMoveCallback(
D3DRMFRAMEMOVECALLBACK d3drmFMC,
VOID * lpArg
);

Parameters

d3drmFMC

Application-defined D3DRMFRAMEMOVECALLBACK callback function.

lpArg

Application-defined data that was passed to the callback function.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::AddMoveCallback, IDirect3DRMFrame::Move


IDirect3DRMFrame::DeleteVisual

Removes a visual object from a frame, destroying it if it is no longer referenced.

HRESULT DeleteVisual(
LPDIRECT3DRMVISUAL lpD3DRMVisual
);

Parameters

lpD3DRMVisual

Address of a variable that represents the Direct3DRMVisual object to be removed.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFrame::GetChildren

Retrieves a list of child frames in the form of a Direct3DRMFrameArray object.

HRESULT GetChildren(
LPDIRECT3DRMFRAMEARRAY* lplpChildren
);

Parameters

lplpChildren

Address of a pointer to be initialized with a valid Direct3DRMFrameArray pointer if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 Direct3DRMFrameArray, Hierarchies


IDirect3DRMFrame::GetColor

Retrieves the color of the frame.

D3DCOLOR GetColor( );

Return Values

Returns the color of the Direct3DRMFrame object.

See Also

 IDirect3DRMFrame::SetColor


IDirect3DRMFrame::GetLights

Retrieves a list of lights in the frame in the form of a Direct3DRMLightArray object.

HRESULT GetLights(
LPDIRECT3DRMLIGHTARRAY* lplpLights
);

Parameters

lplpLights

Address of a pointer to be initialized with a valid Direct3DRMLightArray pointer if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMLightArray


IDirect3DRMFrame::GetMaterialMode

Retrieves the material mode of the frame.

D3DRMMATERIALMODE GetMaterialMode( );

Return Values

Returns a member of the D3DRMMATERIALMODE enumerated type that specifies the current material mode.

See Also

 IDirect3DRMFrame::SetMaterialMode


IDirect3DRMFrame::GetOrientation

Retrieves the orientation of a frame relative to the given reference frame.

HRESULT GetOrientation(
LPDIRECT3DRMFRAME lpRef,
LPD3DVECTOR lprvDir,
LPD3DVECTOR lprvUp
);

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

lprvDir and lprvUp

Addresses of D3DVECTOR structures that will be filled with the directions of the frame's z- and y-axes respectively.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::SetOrientation


IDirect3DRMFrame::GetParent

Retrieves the parent frame of the current frame.

HRESULT GetParent(
LPDIRECT3DRMFRAME* lplpParent
);

Parameters

lplpParent

Address of a pointer that will be filled with the pointer to the Direct3DRMFrame object representing the frame's parent. If the current frame is the root, this pointer will be NULL when the method returns.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFrame::GetPosition

Retrieves the position of a frame relative to the given reference frame (for example, this method retrieves the distance of the frame from the reference). The distance is stored in the lprvPos parameter as a vector rather than as a linear measure.

HRESULT GetPosition(
LPDIRECT3DRMFRAME lpRef,
LPD3DVECTOR lprvPos
);

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

lprvPos

Address of a D3DVECTOR structure that will be filled with the frame's position.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::SetPosition


IDirect3DRMFrame::GetRotation

Retrieves the rotation of the frame relative to the given reference frame.

HRESULT GetRotation(
LPDIRECT3DRMFRAME lpRef,
LPD3DVECTOR lprvAxis,
LPD3DVALUE lprvTheta
);

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

lprvAxis

Address of a D3DVECTOR structure that will be filled with the frame's axis of rotation.

lprvTheta

Address of a variable that will be the frame's rotation, in radians.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::SetRotation, Transformations


IDirect3DRMFrame::GetScene

Retrieves the root frame of the hierarchy containing the given frame.

HRESULT GetScene(
LPDIRECT3DRMFRAME* lplpRoot
);

Parameters

lplpRoot

Address of the pointer that will be filled with the pointer to the Direct3DRMFrame object representing the scene's root frame.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFrame::GetSceneBackground

Retrieves the background color of a scene.

D3DCOLOR GetSceneBackground( );

Return Values

Returns the color.


IDirect3DRMFrame::GetSceneBackgroundDepth

Retrieves the current background-depth buffer for the scene.

HRESULT GetSceneBackgroundDepth(
LPDIRECTDRAWSURFACE * lplpDDSurface
);

Parameters

lplpDDSurface

Address of a pointer that will be initialized with the address of a DirectDraw surface representing the current background-depth buffer.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::SetSceneBackgroundDepth


IDirect3DRMFrame::GetSceneFogColor

Retrieves the fog color of a scene.

D3DCOLOR GetSceneFogColor( );

Return Values

Returns the fog color.


IDirect3DRMFrame::GetSceneFogEnable

Returns whether fog is currently enabled for this scene.

BOOL GetSceneFogEnable( );

Return Values

Returns TRUE if fog is enabled, and FALSE otherwise.


IDirect3DRMFrame::GetSceneFogMode

Returns the current fog mode for this scene.

D3DRMFOGMODE GetSceneFogMode( );

Return Values

Returns a member of the D3DRMFOGMODE enumerated type that specifies the current fog mode.


IDirect3DRMFrame::GetSceneFogParams

Retrieves the current fog parameters for this scene.

HRESULT GetSceneFogParams(
D3DVALUE * lprvStart,
D3DVALUE * lprvEnd,
D3DVALUE * lprvDensity
);

Parameters

lprvStart, lprvEnd, and lprvDensity

Addresses of variables that will be the fog start, end, and density values.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFrame::GetSortMode

Retrieves the sorting mode used to process child frames.

D3DRMSORTMODE GetSortMode( );

Return Values

Returns the member of the D3DRMSORTMODE enumerated type that specifies the sorting mode.

See Also

 IDirect3DRMFrame::SetSortMode


IDirect3DRMFrame::GetTexture

Retrieves the texture of the given frame.

HRESULT GetTexture(
LPDIRECT3DRMTEXTURE* lplpTexture
);

Parameters

lplpTexture

Address of the pointer that will be filled with the address of the Direct3DRMTexture object representing the frame's texture.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::SetTexture


IDirect3DRMFrame::GetTextureTopology

Retrieves the topological properties of a texture when mapped onto objects in the given frame.

HRESULT GetTextureTopology(
BOOL * lpbWrap_u,
BOOL * lpbWrap_v
);

Parameters

lpbWrap_u and lpbWrap_v

Addresses of variables that are set to TRUE if the texture is mapped in the u and v directions, respectively.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::SetTextureTopology


IDirect3DRMFrame::GetTransform

Retrieves the local transformation of the frame as a 4-by-4 affine matrix.

HRESULT GetTransform(
D3DRMMATRIX4D rmMatrix
);

Parameters

rmMatrix

A D3DRMMATRIX4D array that will be filled with the frame's transformation. Because this is an array, this value is actually an address.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 3D Transformations


IDirect3DRMFrame::GetVelocity

Retrieves the velocity of the frame relative to the given reference frame.

HRESULT GetVelocity(
LPDIRECT3DRMFRAME lpRef,
LPD3DVECTOR lprvVel,
BOOL fRotVel
);

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

lprvVel

Address of a D3DVECTOR structure that will be filled with the frame's velocity.

fRotVel

Flag specifying whether the rotational velocity of the object is taken into account when retrieving the linear velocity. If this parameter is TRUE, the object's rotational velocity is included in the calculation.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::SetVelocity


IDirect3DRMFrame::GetVisuals

Retrieves a list of visuals in the frame.

HRESULT GetVisuals(
LPDIRECT3DRMVISUALARRAY* lplpVisuals
);

Parameters

lplpVisuals

Address of a pointer to be initialized with a valid Direct3DRMVisualArray pointer if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFrame::GetZbufferMode

Retrieves the z-buffer mode; that is, whether z-buffering is enabled or disabled.

D3DRMZBUFFERMODE GetZbufferMode( );

Return Values

Returns one of the members of the D3DRMZBUFFERMODE enumerated type.

See Also

 IDirect3DRMFrame::SetZbufferMode


IDirect3DRMFrame::InverseTransform

Transforms the vector in the lprvSrc parameter in world coordinates to frame coordinates, and returns the result in the lprvDst parameter.

HRESULT InverseTransform(
D3DVECTOR *lprvDst,
D3DVECTOR *lprvSrc
);

Parameters

lprvDst

Address of a D3DVECTOR structure that will be filled with the result of the transformation.

lprvSrc

Address of a D3DVECTOR structure that is the source of the transformation.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 3D Transformations


IDirect3DRMFrame::Load

Loads a Direct3DRMFrame object.

HRESULT Load(
LPVOID lpvObjSource,
LPVOID lpvObjID,
D3DRMLOADOPTIONS d3drmLOFlags,
D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc,
LPVOID lpArgLTP
);

Parameters

lpvObjSource

Source for the object to be loaded. This source can be a file, resource, memory block, or stream, depending on the source flags specified in the d3drmLOFlags parameter.

lpvObjID

Object name or position to be loaded. The use of this parameter depends on the identifier flags specified in the d3drmLOFlags parameter. If the D3DRMLOAD_BYPOSITION flag is specified, this parameter is a pointer to a DWORD value that gives the object's order in the file. This parameter can be NULL.

d3drmLOFlags

Value of the D3DRMLOADOPTIONS type describing the load options.

d3drmLoadTextureProc

A D3DRMLOADTEXTURECALLBACK callback function called to load any textures used by the object.

lpArgLTP

Address of application-defined data passed to the D3DRMLOADTEXTURECALLBACK callback function.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

By default, this method loads the first frame hierarchy in the file specified by the lpvObjSource parameter. The frame that calls this method is used as the parent of the new frame hierarchy.


IDirect3DRMFrame::LookAt

Faces the frame toward the target frame, relative to the given reference frame, locking the rotation by the given constraints.

HRESULT LookAt(
LPDIRECT3DRMFRAME lpTarget,
LPDIRECT3DRMFRAME lpRef,
D3DRMFRAMECONSTRAINT rfcConstraint
);

Parameters

lpTarget and lpRef

Addresses of variables that represent the Direct3DRMFrame objects to be used as the target and reference, respectively.

rfcConstraint

Member of the D3DRMFRAMECONSTRAINT enumerated type that specifies the axis of rotation to constrain.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFrame::Move

Applies the rotations and velocities for all frames in the given hierarchy.

HRESULT Move(
D3DVALUE delta
);

Parameters

delta

Amount to change the velocity and rotation.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFrame::QueryInterface

Determines if the Direct3DRMFrame object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMFrame.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMFrame::QueryInterface method allows Direct3DRMFrame objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMFrame::Release

Decreases the reference count of the Direct3DRMFrame object by 1. This method is part of the IUnknown interface inherited by Direct3DRMFrame.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMFrame object deallocates itself when its reference count reaches 0. Use the IDirect3DRMFrame::AddRef method to increase the reference count of the object by 1.


IDirect3DRMFrame::SetColor

Sets the color of the frame. This color is used for meshes in the frame when the D3DRMMATERIALMODE enumerated type is D3DRMMATERIAL_FROMFRAME.

HRESULT SetColor(
D3DCOLOR rcColor
);

Parameters

rcColor

New color for the frame.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::GetColor, IDirect3DRMFrame::SetMaterialMode


IDirect3DRMFrame::SetColorRGB

Sets the color of the frame. This color is used for meshes in the frame when the D3DRMMATERIALMODE enumerated type is D3DRMMATERIAL_FROMFRAME.

HRESULT SetColorRGB(
D3DVALUE rvRed,
D3DVALUE rvGreen,
D3DVALUE rvBlue
);

Parameters

rvRed, rvGreen, and rvBlue

New color for the frame. Each component of the color should be in the range 0 to 1.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::SetMaterialMode


IDirect3DRMFrame::SetMaterialMode

Sets the material mode for a frame. The material mode determines the source of material information for visuals rendered with the frame.

HRESULT SetMaterialMode(
D3DRMMATERIALMODE rmmMode
);

Parameters

rmmMode

One of the members of the D3DRMMATERIALMODE enumerated type.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::GetMaterialMode


IDirect3DRMFrame::SetOrientation

Aligns a frame so that its z-direction points along the direction vector [rvDx, rvDy, rvDz] and its y-direction aligns with the vector [rvUx, rvUy, rvUz].

HRESULT SetOrientation(
LPDIRECT3DRMFRAME lpRef,
D3DVALUE rvDx,
D3DVALUE rvDy,
D3DVALUE rvDz,
D3DVALUE rvUx,
D3DVALUE rvUy,
D3DVALUE rvUz
);

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

rvDx, rvDy, and rvDz

New z-axis for the frame.

rvUx, rvUy, and rvUz

New y-axis for the frame.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The default orientation of a frame has a direction vector of [0, 0, 1] and an up vector of [0, 1, 0].

If [rvUx, rvUy, rvUz] is parallel to [rvDx, rvDy, rvDz], the D3DRMERR_BADVALUE error value is returned; otherwise, the [rvUx, rvUy, rvUz] vector passed is projected onto the plane that is perpendicular to [rvDx, rvDy, rvDz].

See Also

 IDirect3DRMFrame::GetOrientation


IDirect3DRMFrame::SetPosition

Sets the position of a frame relative to the frame of reference. It places the frame a distance of [rvX, rvY, rvZ] from the reference. When a child frame is created within a parent, it is placed at [0, 0, 0] in the parent frame.

HRESULT SetPosition(
LPDIRECT3DRMFRAME lpRef,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ
);

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

rvX, rvY, and rvZ

New position for the frame.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::GetPosition


IDirect3DRMFrame::SetRotation

Sets a frame rotating by the given angle around the given vector at each call to the IDirect3DRM::Tick or IDirect3DRMFrame::Move method. The direction vector [rvX, rvY, rvZ] is defined in the reference frame.

HRESULT SetRotation(
LPDIRECT3DRMFRAME lpRef,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ,
D3DVALUE rvTheta
);

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

rvX, rvY, and rvZ

Vector about which rotation occurs.

rvTheta

Rotation angle, in radians.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The specified rotation changes the matrix with every render tick, unlike the IDirect3DRMFrame::AddRotation method, which changes the objects in the frame only once.

See Also

 IDirect3DRMFrame::AddRotation, IDirect3DRMFrame::GetRotation


IDirect3DRMFrame::SetSceneBackground

Sets the background color of a scene.

HRESULT SetSceneBackground(
D3DCOLOR rcColor
);

Parameters

rcColor

New color for the background.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFrame::SetSceneBackgroundDepth

Specifies a background-depth buffer for a scene.

HRESULT SetSceneBackgroundDepth(
LPDIRECTDRAWSURFACE lpImage
);

Parameters

lpImage

Address of a DirectDraw surface that will store the new background depth for the scene.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The image must have a depth of 16. If the image and viewport sizes are different, the image is scaled first. For best performance when animating the background-depth buffer, the image should be the same size as the viewport. This enables the depth buffer to be updated directly from the image memory without incurring extra overhead.

See Also

 IDirect3DRMFrame::GetSceneBackgroundDepth


IDirect3DRMFrame::SetSceneBackgroundImage

Specifies a background image for a scene.

HRESULT SetSceneBackgroundImage(
LPDIRECT3DRMTEXTURE lpTexture
);

Parameters

lpTexture

Address of a Direct3DRMTexture object that will contain the new background scene.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

If the image is a different size or color depth than the viewport, the image will first be scaled or converted to the correct depth. For best performance when animating the background, the image should be the same size and color depth. This enables the background to be rendered directly from the image memory without incurring any extra overhead.


IDirect3DRMFrame::SetSceneBackgroundRGB

Sets the background color of a scene.

HRESULT SetSceneBackgroundRGB(
D3DVALUE rvRed,
D3DVALUE rvGreen,
D3DVALUE rvBlue
);

Parameters

rvRed, rvGreen, and rvBlue

New color for the background.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFrame::SetSceneFogColor

Sets the fog color of a scene.

HRESULT SetSceneFogColor(
D3DCOLOR rcColor
);

Parameters

rcColor

New color for the fog.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFrame::SetSceneFogEnable

Sets the fog enable state.

HRESULT SetSceneFogEnable(
BOOL bEnable
);

Parameters

bEnable

New fog enable state.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMFrame::SetSceneFogMode

Sets the fog mode.

HRESULT SetSceneFogMode(
D3DRMFOGMODE rfMode
);

Parameters

rfMode

One of the members of the D3DRMFOGMODE enumerated type, specifying the new fog mode.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::SetSceneFogParams


IDirect3DRMFrame::SetSceneFogParams

Sets the current fog parameters for this scene.

HRESULT SetSceneFogParams(
D3DVALUE rvStart,
D3DVALUE rvEnd,
D3DVALUE rvDensity
);

Parameters

rvStart and rvEnd

Fog start and end points for linear fog mode. These settings determine the distance from the camera at which fog effects first become visible and the distance at which fog reaches its maximum density.

rvDensity

Fog density for the exponential fog modes. This value should be in the range 0 through 1.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 D3DRMFOGMODE, IDirect3DRMFrame::SetSceneFogMode


IDirect3DRMFrame::SetSortMode

Sets the sorting mode used to process child frames. You can use this method to change the properties of hidden-surface-removal algorithms.

HRESULT SetSortMode(
D3DRMSORTMODE d3drmSM
);

Parameters

d3drmSM

One of the members of the D3DRMSORTMODE enumerated type, specifying the sorting mode. The default value is D3DRMSORT_FROMPARENT.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::GetSortMode


IDirect3DRMFrame::SetTexture

Sets the texture of the frame.

HRESULT SetTexture(
LPDIRECT3DRMTEXTURE lpD3DRMTexture
);

Parameters

lpD3DRMTexture

Address of a variable that represents the Direct3DRMTexture object to be used.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The texture is used for meshes in the frame when the D3DRMMATERIALMODE enumerated type is D3DRMMATERIAL_FROMFRAME. To disable the frame's texture, use a NULL texture.

See Also

 IDirect3DRMFrame::GetTexture, IDirect3DRMFrame::SetMaterialMode


IDirect3DRMFrame::SetTextureTopology

Defines the topological properties of the texture coordinates across objects in the frame.

HRESULT SetTextureTopology(
BOOL bWrap_u,
BOOL bWrap_v
);

Parameters

bWrap_u and bWrap_v

Variables that are set to TRUE to map the texture in the u- and v-directions, respectively.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::GetTextureTopology


IDirect3DRMFrame::SetVelocity

Sets the velocity of the given frame relative to the reference frame. The frame will be moved by the vector [rvX, rvY, rvZ] with respect to the reference frame at each successive call to the IDirect3DRM::Tick or IDirect3DRMFrame::Move method.

HRESULT SetVelocity(
LPDIRECT3DRMFRAME lpRef,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ,
BOOL fRotVel
);

Parameters

lpRef

Address of a variable that represents the Direct3DRMFrame object to be used as the reference.

rvX, rvY, and rvZ

New velocity for the frame.

fRotVel

Flag specifying whether the rotational velocity of the object is taken into account when setting the linear velocity. If TRUE, the object's rotational velocity is included in the calculation.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::GetVelocity


IDirect3DRMFrame::SetZbufferMode

Sets the z-buffer mode; that is, whether z-buffering is enabled or disabled.

HRESULT SetZbufferMode(
D3DRMZBUFFERMODE d3drmZBM
);

Parameters

d3drmZBM

One of the members of the D3DRMZBUFFERMODE enumerated type, specifying the z-buffer mode. The default value is D3DRMZBUFFER_FROMPARENT.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMFrame::GetZbufferMode


IDirect3DRMFrame::Transform

Transforms the vector in the lpd3dVSrc parameter in frame coordinates to world coordinates, returning the result in the lpd3dVDst parameter.

HRESULT Transform(
D3DVECTOR *lpd3dVDst,
D3DVECTOR *lpd3dVSrc
);

Parameters

lpd3dVDst

Address of a D3DVECTOR structure that will be filled with the result of the transformation operation.

lpd3dVSrc

Address of a D3DVECTOR structure that is the source of the transformation operation.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 3D Transformations


IDirect3DRMLight Interface


IDirect3DRMLight Interface Method Groups

Applications use the methods of the IDirect3DRMLight interface to interact with light objects. The methods can be organized into the following groups:

Attenuation	GetConstantAttenuation
	GetLinearAttenuation
	GetQuadraticAttenuation
	SetConstantAttenuation
	SetLinearAttenuation
	SetQuadraticAttenuation
Color	GetColor
	SetColor
	SetColorRGB
Enable frames	GetEnableFrame
	SetEnableFrame
IUnknown	AddRef
	QueryInterface
	Release
Light types	GetType
	SetType
Range	GetRange
	SetRange
Spotlight options	GetPenumbra
	GetUmbra
	SetPenumbra
	SetUmbra
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMLight object without affecting the functionality of the original interface. In addition, the IDirect3DRMLight interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMLight object is obtained by calling the IDirect3DRM::CreateLight or IDirect3DRM::CreateLightRGB method.


IDirect3DRMLight::AddRef

Increases the reference count of the Direct3DRMLight object by 1. This method is part of the IUnknown interface inherited by Direct3DRMLight.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMLight object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMLight::Release method to decrease the reference count of the object by 1.


IDirect3DRMLight::GetColor

Retrieves the color of the current Direct3DRMLight object.

D3DCOLOR GetColor( );

Return Values

Returns the color.

See Also

 IDirect3DRMLight::SetColor


IDirect3DRMLight::GetConstantAttenuation

Retrieves the constant attenuation factor for the Direct3DRMLight object.

D3DVALUE GetConstantAttenuation( );

Return Values

Returns the constant attenuation value.

Remarks

The constant attenuation value affects the light intensity inversely. For example, a constant attenuation value of 2 halves the intensity of the light.

See Also

 IDirect3DRMLight::SetConstantAttenuation


IDirect3DRMLight::GetEnableFrame

Retrieves the enable frame for a light. The enable frame is the frame to which a light applies.

HRESULT GetEnableFrame(
LPDIRECT3DRMFRAME * lplpEnableFrame
);

Parameters

lplpEnableFrame

Address of a pointer that will contain the enable frame for the current Direct3DRMFrame object.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMLight::SetEnableFrame


IDirect3DRMLight::GetLinearAttenuation

Retrieves the linear attenuation factor for a light.

D3DVALUE GetLinearAttenuation( );

Return Values

Returns the linear attenuation value.

See Also

 IDirect3DRMLight::SetLinearAttenuation


IDirect3DRMLight::GetPenumbra

Retrieves the penumbra angle of a spotlight.

D3DVALUE GetPenumbra( );

Return Values

Returns the penumbra value.

See Also

 IDirect3DRMLight::SetPenumbra


IDirect3DRMLight::GetQuadraticAttenuation

Retrieves the quadratic attenuation factor for a light.

D3DVALUE GetQuadraticAttenuation( );

Return Values

Returns the quadratic attenuation value.

See Also

 IDirect3DRMLight::SetQuadraticAttenuation


IDirect3DRMLight::GetRange

Retrieves the range of the current Direct3DRMLight object.

D3DVALUE GetRange( );

Return Values

Returns a value describing the range.

See Also

 IDirect3DRMLight::SetRange


IDirect3DRMLight::GetType

Retrieves the type of a given light.

D3DRMLIGHTTYPE GetType( );

Return Values

Returns one of the members of the D3DRMLIGHTTYPE enumerated type.

See Also

 IDirect3DRMLight::SetType


IDirect3DRMLight::GetUmbra

Retrieves the umbra angle of the Direct3DRMLight object.

D3DVALUE GetUmbra( );

Return Values

Returns the umbra angle.

See Also

 IDirect3DRMLight::SetUmbra


IDirect3DRMLight::QueryInterface

Determines if the Direct3DRMLight object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMLight.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMLight::QueryInterface method allows Direct3DRMLight objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMLight::Release

Decreases the reference count of the Direct3DRMLight object by 1. This method is part of the IUnknown interface inherited by Direct3DRMLight.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMLight object deallocates itself when its reference count reaches 0. Use the IDirect3DRMLight::AddRef method to increase the reference count of the object by 1.


IDirect3DRMLight::SetColor

Sets the color of the given light.

HRESULT SetColor(
D3DCOLOR rcColor
);

Parameters

rcColor

New color for the light.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMLight::GetColor


IDirect3DRMLight::SetColorRGB

Sets the color of the given light.

HRESULT SetColorRGB(
D3DVALUE rvRed,
D3DVALUE rvGreen,
D3DVALUE rvBlue
);

Parameters

rvRed, rvGreen, and rvBlue

New color for the light.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMLight::SetConstantAttenuation

Sets the constant attenuation factor for a light.

HRESULT SetConstantAttenuation(
D3DVALUE rvAtt
);

Parameters

rvAtt

New attenuation factor.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The constant attenuation value affects the light intensity inversely. For example, a constant attenuation value of 2 halves the intensity of the light.

See Also

 IDirect3DRMLight::GetConstantAttenuation


IDirect3DRMLight::SetEnableFrame

Sets the enable frame for a light. The enable frame is the frame to which a light applies.

HRESULT SetEnableFrame(
LPDIRECT3DRMFRAME lpEnableFrame
);

Parameters

lpEnableFrame

Address of the light's enable frame. Child frames of this frame are also enabled for this light source.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMLight::GetEnableFrame


IDirect3DRMLight::SetLinearAttenuation

Sets the linear attenuation factor for a light.

HRESULT SetLinearAttenuation(
D3DVALUE rvAtt
);

Parameters

rvAtt

New attenuation factor.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMLight::GetLinearAttenuation


IDirect3DRMLight::SetPenumbra

Sets the angle of the penumbra cone.

HRESULT SetPenumbra(
D3DVALUE rvAngle
);

Parameters

rvAngle

New penumbra angle. This angle must be greater than or equal to the angle of the umbra. If you try to set the penumbra angle to less than the umbra angle, the umbra angle will be set equal to the penumbra angle. The default value is 0.5 radians.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMLight::GetPenumbra


IDirect3DRMLight::SetQuadraticAttenuation

Sets the quadratic attenuation factor for a light.

HRESULT SetQuadraticAttenuation(
D3DVALUE rvAtt
);

Parameters

rvAtt

New attenuation factor.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMLight::GetQuadraticAttenuation


IDirect3DRMLight::SetRange

Sets the range of a light. The light affects objects that are within the range only.

HRESULT SetRange(
D3DVALUE rvRange
);

Parameters

rvRange

New range. The default value is 256.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMLight::GetRange


IDirect3DRMLight::SetType

Changes the light's type.

HRESULT SetType(
D3DRMLIGHTTYPE d3drmtType
);

Parameters

d3drmtType

New light type specified by one of the members of the D3DRMLIGHTTYPE enumerated type.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMLight::GetType


IDirect3DRMLight::SetUmbra

Sets the angle of the umbra cone.

HRESULT SetUmbra(
D3DVALUE rvAngle
);

Parameters

rvAngle

New umbra angle. This angle must be less than or equal to the angle of the penumbra. If you try to set the umbra angle to greater than the penumbra angle, the penumbra angle will be set equal to the umbra angle. The default value is 0.4 radians.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMLight::GetUmbra


IDirect3DRMMaterial Interface


IDirect3DRMMaterial Interface Method Groups

Applications use the methods of the IDirect3DRMMaterial interface to interact with material objects. The methods can be organized into the following groups:

Emission	GetEmissive
	SetEmissive
IUnknown	AddRef
	QueryInterface
	Release
Power for	GetPower
specular exponent	SetPower
Specular	GetSpecular
	SetSpecular
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMMaterial object without affecting the functionality of the original interface. In addition, the IDirect3DRMMaterial interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMMaterial object is obtained by calling the IDirect3DRM::CreateMaterial method.


IDirect3DRMMaterial::AddRef

Increases the reference count of the Direct3DRMMaterial object by 1. This method is part of the IUnknown interface inherited by Direct3DRMMaterial.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMMaterial object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMMaterial::Release method to decrease the reference count of the object by 1.


IDirect3DRMMaterial::GetEmissive

Retrieves the setting for the emissive property of a material. The emissive setting is the color and intensity of the light the object emits.

HRESULT GetEmissive(
D3DVALUE *lpr,
D3DVALUE *lpg,
D3DVALUE *lpb
);

Parameters

lpr, lpg, and lpb

Addresses that will contain the red, green, and blue components of the emissive color when the method returns.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMaterial::SetEmissive


IDirect3DRMMaterial::GetPower

Retrieves the power used for the specular exponent in the given material.

D3DVALUE GetPower( );

Return Values

Returns the value specifying the power of the specular exponent.

See Also

 IDirect3DRMMaterial::SetPower


IDirect3DRMMaterial::GetSpecular

Retrieves the color of the specular highlights of a material.

HRESULT GetSpecular(
D3DVALUE *lpr,
D3DVALUE *lpg,
D3DVALUE *lpb
);

Parameters

lpr, lpg, and lpb

Addresses that will contain the red, green, and blue components of the color of the specular highlights when the method returns.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMaterial::SetSpecular


IDirect3DRMMaterial::QueryInterface

Determines if the Direct3DRMMaterial object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMMaterial.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMMaterial::QueryInterface method allows Direct3DRMMaterial objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMMaterial::Release

Decreases the reference count of the Direct3DRMMaterial object by 1. This method is part of the IUnknown interface inherited by Direct3DRMMaterial.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMMaterial object deallocates itself when its reference count reaches 0. Use the IDirect3DRMMaterial::AddRef method to increase the reference count of the object by 1.


IDirect3DRMMaterial::SetEmissive

Sets the emissive property of a material. The emissive property is the color and intensity of the light the object emits.

HRESULT SetEmissive(
D3DVALUE r,
D3DVALUE g,
D3DVALUE b
);

Parameters

r, g, and b

Red, green, and blue components of the emissive color.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMaterial::GetEmissive


IDirect3DRMMaterial::SetPower

Sets the power used for the specular exponent in a material.

HRESULT SetPower(
D3DVALUE rvPower
);

Parameters

rvPower

New specular exponent.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMaterial::GetPower


IDirect3DRMMaterial::SetSpecular

Sets the color of the specular highlights for a material.

HRESULT SetSpecular(
D3DVALUE r,
D3DVALUE g,
D3DVALUE b
);

Parameters

r, g, and b

Red, green, and blue components of the color of the specular highlights.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMaterial::GetSpecular


IDirect3DRMMesh Interface


IDirect3DRMMesh Interface Method Groups

Applications use the methods of the IDirect3DRMMesh interface to interact with groups of meshes. The methods can be organized into the following groups:

Color	GetGroupColor
	SetGroupColor
	SetGroupColorRGB
Creation and	AddGroup
information	GetBox
	GetGroup
	GetGroupCount
IUnknown	AddRef
	QueryInterface
	Release
Materials	GetGroupMaterial
	SetGroupMaterial
Miscellaneous	Scale
	Translate
Rendering quality	GetGroupQuality
	SetGroupQuality
Texture mapping	GetGroupMapping
	SetGroupMapping
Textures	GetGroupTexture
	SetGroupTexture
Vertex positions	GetVertices
	SetVertices
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMMesh object without affecting the functionality of the original interface. In addition, the IDirect3DRMMesh interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMMesh object is obtained by calling the IDirect3DRM::CreateMesh method.


IDirect3DRMMesh::AddGroup

Groups a collection of faces and retrieves an identifier for the group.

HRESULT AddGroup(
unsigned vCount,
unsigned fCount,
unsigned vPerFace,
unsigned *fData,
D3DRMGROUPINDEX *returnId
);

Parameters

vCount and fCount

Number of vertices and faces in the group.

vPerFace

Number of vertices per face in the group, if all faces have the same vertex count. If the group contains faces with varying vertex counts, this parameter should be zero.

fData

Address of face data. If the vPerFace parameter specifies a value, this data is simply a list of indices into the group's vertex array. If vPerFace is zero, the vertex indices should be preceded by an integer giving the number of vertices in that face. For example, if vPerFace is zero and the group is made up of triangular and quadrilateral faces, the data might be in the following form: 3 index index index 4 index index index index 3 index index index ...

returnId

Address of a variable that will identify the group when the method returns.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

A newly added group has the following default properties:

•	White

•	No texture

•	No specular reflection

•	Position, normal, and color of each vertex in the vertex array equal to zero

To set the positions of the vertices, use the IDirect3DRMMesh::SetVertices method.


IDirect3DRMMesh::AddRef

Increases the reference count of the Direct3DRMMesh object by 1. This method is part of the IUnknown interface inherited by Direct3DRMMesh.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMMesh object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMMesh::Release method to decrease the reference count of the object by 1.


IDirect3DRMMesh::GetBox

Retrieves the bounding box containing a Direct3DRMMesh object. The bounding box gives the minimum and maximum model coordinates in each dimension.

HRESULT GetBox(
D3DRMBOX * lpD3DRMBox
);

Parameters

lpD3DRMBox

Address of a D3DRMBOX structure that will be filled with the bounding box coordinates.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMesh::GetGroup

Retrieves the data associated with a specified group.

HRESULT GetGroup(
D3DRMGROUPINDEX id,
unsigned *vCount,
unsigned *fCount,
unsigned *vPerFace,
DWORD *fDataSize,
unsigned *fData
);

Parameters

id

Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.

vCount and fCount

Addresses of variables that will contain the number of vertices and the number of faces for the group when the method returns. These parameters can be NULL.

vPerFace

Address of a variable that will contain the number of vertices per face for the group when the method returns. This parameter can be NULL.

fDataSize

Address of a variable that specifies the number of unsigned elements in the buffer pointed to by the fData parameter. This parameter cannot be NULL.

fData

Address of a buffer that will contain the face data for the group when the method returns. The format of this data is the same as was specified in the call to the IDirect3DRMMesh::AddGroup method. If this parameter is NULL, the method returns the required size of the buffer in the fDataSize parameter.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMesh::GetGroupColor

Retrieves the color for a group.

D3DCOLOR GetGroupColor(
D3DRMGROUPINDEX id
);

Parameters

id

Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.

Return Values

Returns a D3DCOLOR variable specifying the color if successful, or zero otherwise.

See Also

 IDirect3DRMMesh::SetGroupColor, IDirect3DRMMesh::SetGroupColorRGB


IDirect3DRMMesh::GetGroupCount

Retrieves the number of groups for a given Direct3DRMMesh object.

unsigned GetGroupCount( );

Return Values

Returns the number of groups if successful, or zero otherwise.


IDirect3DRMMesh::GetGroupMapping

Returns a description of how textures are mapped to a group in a Direct3DRMMesh object.

D3DRMMAPPING GetGroupMapping(
D3DRMGROUPINDEX id
);

Parameters

id

Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.

Return Values

Returns one of the D3DRMMAPPING values describing how textures are mapped to a group, if successful. Returns zero otherwise.

See Also

 IDirect3DRMMesh::SetGroupMapping


IDirect3DRMMesh::GetGroupMaterial

Retrieves a pointer to the material associated with a group in a Direct3DRMMesh object.

HRESULT GetGroupMaterial(
D3DRMGROUPINDEX id,
LPDIRECT3DRMMATERIAL *returnPtr
);

Parameters

id

Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.

returnPtr

Address of a pointer to a variable that will contain the IDirect3DRMMaterial interface for the group when the method returns.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMesh::SetGroupMaterial


IDirect3DRMMesh::GetGroupQuality

Retrieves the rendering quality for a specified group in a Direct3DRMMesh object.

D3DRMRENDERQUALITY GetGroupQuality(
D3DRMGROUPINDEX id
);

Parameters

id

Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.

Return Values

Returns values from the enumerated types represented by D3DRMRENDERQUALITY if successful, or zero otherwise. These values include the shading, lighting, and fill modes for the object.

See Also

 IDirect3DRMMesh::SetGroupQuality


IDirect3DRMMesh::GetGroupTexture

Retrieves an address of the texture associated with a group in a Direct3DRMMesh object.

HRESULT GetGroupTexture(
D3DRMGROUPINDEX id,
LPDIRECT3DRMTEXTURE *returnPtr
);

Parameters

id

Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.

returnPtr

Address of a pointer to a variable that will contain the IDirect3DRMTexture interface for the group when the method returns.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMesh::SetGroupTexture


IDirect3DRMMesh::GetVertices

Retrieves the vertex positions for a specified group in a Direct3DRMMesh object.

HRESULT GetVertices(
D3DRMGROUPINDEX id,
DWORD index,
DWORD count,
D3DRMVERTEX *returnPtr
);

Parameters

id

Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.

index

Index into the array of D3DRMVERTEX structures at which to begin returning vertex positions.

count

Number of D3DRMVERTEX structures (vertices) to retrieve following the index given in the index parameter. This parameter cannot be NULL.

returnPtr

Array of D3DRMVERTEX structures that will contain the vertex positions when the method returns. If this parameter is NULL, the method returns the required number of D3DRMVERTEX structures in the count parameter.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMesh::SetVertices


IDirect3DRMMesh::QueryInterface

Determines if the Direct3DRMMesh object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMMesh.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMMesh::QueryInterface method allows Direct3DRMMesh objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMMesh::Release

Decreases the reference count of the Direct3DRMMesh object by 1. This method is part of the IUnknown interface inherited by Direct3DRMMesh.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMMesh object deallocates itself when its reference count reaches 0. Use the IDirect3DRMMesh::AddRef method to increase the reference count of the object by 1.


IDirect3DRMMesh::Scale

Scales a Direct3DRMMesh object by the given scaling factors, parallel to the x-, y-, and z-axes in model coordinates.

HRESULT Scale(
D3DVALUE sx,
D3DVALUE sy,
D3DVALUE sz
);

Parameters

sx, sy, and sz

Scaling factors that are applied along the x-, y-, and z-axes.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMesh::SetGroupColor

Sets the color of a group in a Direct3DRMMesh object.

HRESULT SetGroupColor(
D3DRMGROUPINDEX id,
D3DCOLOR value
);

Parameters

id

Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.

value

Color of the group.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMesh::GetGroupColor, IDirect3DRMMesh::SetGroupColorRGB


IDirect3DRMMesh::SetGroupColorRGB

Sets the color of a group in a Direct3DRMMesh object, using individual RGB values.

HRESULT SetGroupColorRGB(
D3DRMGROUPINDEX id,
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);

Parameters

id

Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.

red, green, and blue

Red, green, and blue components of the group color.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMesh::GetGroupColor, IDirect3DRMMesh::SetGroupColor


IDirect3DRMMesh::SetGroupMapping

Sets the mapping for a group in a Direct3DRMMesh object. The mapping controls how textures are mapped to a surface.

HRESULT SetGroupMapping(
D3DRMGROUPINDEX id,
D3DRMMAPPING value
);

Parameters

id

Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.

value

Value of the D3DRMMAPPING type describing the mapping for the group.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMesh::GetGroupMapping


IDirect3DRMMesh::SetGroupMaterial

Sets the material associated with a group in a Direct3DRMMesh object.

HRESULT SetGroupMaterial(
D3DRMGROUPINDEX id,
LPDIRECT3DRMMATERIAL value
);

Parameters

id

Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.

value

Address of the IDirect3DRMMaterial interface for the Direct3DRMMesh object.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMesh::GetGroupMaterial


IDirect3DRMMesh::SetGroupQuality

Sets the rendering quality for a specified group in a Direct3DRMMesh object.

HRESULT SetGroupQuality(
D3DRMGROUPINDEX id,
D3DRMRENDERQUALITY value
);

Parameters

id

Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.

value

Values from the enumerated types represented by the D3DRMRENDERQUALITY type. These values include the shading, lighting, and fill modes for the object.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMesh::GetGroupQuality


IDirect3DRMMesh::SetGroupTexture

Sets the texture associated with a group in a Direct3DRMMesh object.

HRESULT SetGroupTexture(
D3DRMGROUPINDEX id,
LPDIRECT3DRMTEXTURE value
);

Parameters

id

Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.

value

Address of the IDirect3DRMTexture interface for the Direct3DRMMesh object.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMesh::GetGroupTexture


IDirect3DRMMesh::SetVertices

Sets the vertex positions for a specified group in a Direct3DRMMesh object.

HRESULT SetVertices(
D3DRMGROUPINDEX id,
unsigned index,
unsigned count,
D3DRMVERTEX *values
);

Parameters

id

Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.

index

Index into the array specified in the values parameter at which to begin setting vertex positions.

count

Number of vertices to set following the index given in the index parameter.

values

Array of D3DRMVERTEX structures specifying the vertex positions to be set.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMesh::GetVertices


IDirect3DRMMesh::Translate

Adds the specified offsets to the vertex positions of a Direct3DRMMesh object.

HRESULT Translate(
D3DVALUE tx,
D3DVALUE ty,
D3DVALUE tz
);

Parameters

tx, ty, and tz

Offsets that are added to the x-, y-, and z-coordinates respectively of each vertex position.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder Interface


IDirect3DRMMeshBuilder Interface Method Groups

Applications use the methods of the IDirect3DRMMeshBuilder interface to interact with mesh objects. The methods can be organized into the following groups:

Color	GetColorSource
	SetColor
	SetColorRGB
	SetColorSource
Creation and	GetBox
information
Faces	AddFace
	AddFaces
	CreateFace
	GetFaceCount
	GetFaces
IUnknown	AddRef
	QueryInterface
	Release
Loading	Load
Meshes	AddMesh
	CreateMesh
Miscellaneous	AddFrame
	AddMeshBuilder
	ReserveSpace
	Save
	Scale
	SetMaterial
	Translate
Normals	AddNormal
	GenerateNormals
	SetNormal
Perspective	GetPerspective
	SetPerspective
Rendering quality	GetQuality
	SetQuality
Textures	GetTextureCoordinates
	SetTexture
	SetTextureCoordinates
	SetTextureTopology
Vertices	AddVertex
	GetVertexColor
	GetVertexCount
	GetVertices
	SetVertex
	SetVertexColor
	SetVertexColorRGB
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMMeshBuilder object without affecting the functionality of the original interface. In addition, the IDirect3DRMMeshBuilder interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMMeshBuilder object is obtained by calling the IDirect3DRM::CreateMeshBuilder method.


IDirect3DRMMeshBuilder::AddFace

Adds a face to a Direct3DRMMeshBuilder object.

HRESULT AddFace(
LPDIRECT3DRMFACE lpD3DRMFace
);

Parameters

lpD3DRMFace

Address of the face being added.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

Any one face can exist in only one mesh at a time.


IDirect3DRMMeshBuilder::AddFaces

Adds faces to a Direct3DRMMeshBuilder object.

HRESULT AddFaces(
DWORD dwVertexCount,
D3DVECTOR * lpD3DVertices,
DWORD normalCount,
D3DVECTOR *lpNormals,
DWORD *lpFaceData,
LPDIRECT3DRMFACEARRAY* lplpD3DRMFaceArray
);

Parameters

dwVertexCount

Number of vertices.

lpD3DVertices

Base address of an array of D3DVECTOR structures that stores the vertex positions.

normalCount

Number of normals.

lpNormals

Base address of an array of D3DVECTOR structures that stores the normal positions.

lpFaceData

For each face, this parameter should contain a vertex count followed by the indices into the vertices array. If normalCount is not zero, this parameter should contain a vertex count followed by pairs of indices, with the first index of each pair indexing into the array of vertices, and the second indexing into the array of normals. The list of indices must terminate with a zero.

lplpD3DRMFaceArray

Address of a pointer to an IDirect3DRMFaceArray interface that will be filled with a pointer to the newly created faces.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::AddFrame

Adds the contents of a frame to a Direct3DRMMeshBuilder object.

HRESULT AddFrame(
LPDIRECT3DRMFRAME lpD3DRMFrame
);

Parameters

lpD3DRMFrame

Address of the frame whose contents are being added.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The source frame is not modified or referenced by this operation.


IDirect3DRMMeshBuilder::AddMesh

Adds a mesh to a Direct3DRMMeshBuilder object.

HRESULT AddMesh(
LPDIRECT3DRMMESH lpD3DRMMesh
);

Parameters

lpD3DRMMesh

Address of the mesh being added.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::AddMeshBuilder

Adds the contents of a Direct3DRMMeshBuilder object to another Direct3DRMMeshBuilder object.

HRESULT AddMeshBuilder(
LPDIRECT3DRMMESHBUILDER lpD3DRMMeshBuild
);

Parameters

lpD3DRMMeshBuild

Address of the Direct3DRMMeshBuilder object whose contents are being added.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The source Direct3DRMMeshBuilder object is not modified or referenced by this operation.


IDirect3DRMMeshBuilder::AddNormal

Adds a normal to a Direct3DRMMeshBuilder object.

int AddNormal(
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);

Parameters

x, y, and z

The x, y, and z components of the direction of the new normal.

Return Values

Returns the index of the normal.


IDirect3DRMMeshBuilder::AddRef

Increases the reference count of the Direct3DRMMeshBuilder object by 1. This method is part of the IUnknown interface inherited by Direct3DRMMeshBuilder.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMMeshBuilder object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMMeshBuilder::Release method to decrease the reference count of the object by 1.


IDirect3DRMMeshBuilder::AddVertex

Adds a vertex to a Direct3DRMMeshBuilder object.

int AddVertex(
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);

Parameters

x, y, and z

The x, y, and z components of the position of the new vertex.

Return Values

Returns the index of the vertex.


IDirect3DRMMeshBuilder::CreateFace

Creates a new face with no vertices and adds it to a Direct3DRMMeshBuilder object.

HRESULT CreateFace(
LPDIRECT3DRMFACE* lplpD3DRMFace
);

Parameters

lplpD3DRMFace

Address of a pointer to an IDirect3DRMFace interface that will be filled with a pointer to the face that was created.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::CreateMesh

Creates a new mesh from a Direct3DRMMeshBuilder object.

HRESULT CreateMesh(
LPDIRECT3DRMMESH* lplpD3DRMMesh
);

Parameters

lplpD3DRMMesh

Address that will be filled with a pointer to an IDirect3DRMMesh interface.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::GenerateNormals

Processes the Direct3DRMMeshBuilder object and generates vertex normals that are the average of each vertex's adjoining face normals.

HRESULT GenerateNormals( );

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

Averaging the normals of back-to-back faces produces a zero normal.


IDirect3DRMMeshBuilder::GetBox

Retrieves the bounding box containing a Direct3DRMMeshBuilder object. The bounding box gives the minimum and maximum model coordinates in each dimension.

HRESULT GetBox(
D3DRMBOX *lpD3DRMBox
);

Parameters

lpD3DRMBox

Address of a D3DRMBOX structure that will be filled with the bounding box coordinates.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::GetColorSource

Retrieves the color source of a Direct3DRMMeshBuilder object. The color source can be either a face or a vertex.

D3DRMCOLORSOURCE GetColorSource( );

Return Values

Returns a member of the D3DRMCOLORSOURCE enumerated type.

See Also

 IDirect3DRMMeshBuilder::SetColorSource


IDirect3DRMMeshBuilder::GetFaceCount

Retrieves the number of faces in a Direct3DRMMeshBuilder object.

int GetFaceCount( );

Return Values

Returns the number of faces.


IDirect3DRMMeshBuilder::GetFaces

Retrieves the faces of a Direct3DRMMeshBuilder object.

HRESULT GetFaces(
LPDIRECT3DRMFACEARRAY* lplpD3DRMFaceArray
);

Parameters

lplpD3DRMFaceArray

Address of a pointer to an IDirect3DRMFaceArray interface that is filled with an address of the faces.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::GetPerspective

Determines whether perspective correction is on for a Direct3DRMMeshBuilder object.

BOOL GetPerspective( );

Return Values

Returns TRUE if perspective correction is on, or FALSE otherwise.


IDirect3DRMMeshBuilder::GetQuality

Retrieves the rendering quality of a Direct3DRMMeshBuilder object.

D3DRMRENDERQUALITY GetQuality( );

Return Values

Returns a member of the D3DRMRENDERQUALITY enumerated type that specifies the rendering quality of the mesh.

See Also

 IDirect3DRMMeshBuilder::SetQuality


IDirect3DRMMeshBuilder::GetTextureCoordinates

Retrieves the texture coordinates of a specified vertex in a Direct3DRMMeshBuilder object.

HRESULT GetTextureCoordinates(
DWORD index,
D3DVALUE *lpU,
D3DVALUE *lpV
);

Parameters

index

Index of the vertex.

lpU and lpV

Addresses of variables that will be filled with the texture coordinates of the vertex when the method returns.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMeshBuilder::SetTextureCoordinates


IDirect3DRMMeshBuilder::GetVertexColor

Retrieves the color of a specified vertex in a Direct3DRMMeshBuilder object.

D3DCOLOR GetVertexColor(
DWORD index
);

Parameters

index

Index of the vertex.

Return Values

Returns the color.

See Also

 IDirect3DRMMeshBuilder::SetVertexColor


IDirect3DRMMeshBuilder::GetVertexCount

Retrieves the number of vertices in a Direct3DRMMeshBuilder object.

int GetVertexCount( );

Return Values

Returns the number of vertices.


IDirect3DRMMeshBuilder::GetVertices

Retrieves the vertices, normals, and face data for a Direct3DRMMeshBuilder object.

HRESULT GetVertices(
DWORD *vcount,
D3DVECTOR *vertices,
DWORD *ncount,
D3DVECTOR *normals,
DWORD *face_data_size,
DWORD *face_data
);

Parameters

vcount

Address of a variable that will contain the number of vertices.

vertices

Address of an array of D3DVECTOR structures that will contain the vertices for the Direct3DRMMeshBuilder object.

ncount

Address of a variable that will contain the number of normals.

normals

Array of D3DVECTOR structures that will contain the normals for the Direct3DRMMeshBuilder object.

face_data_size

Address of a variable that specifies the size of the buffer pointed to by the face_data parameter. The size is given in units of DWORD values. This parameter cannot be NULL.

face_data

Address of the face data for the Direct3DRMMeshBuilder object. This data is in the same format as specified in the IDirect3DRMMesh::AddGroup method except that it is null-terminated. If this parameter is NULL, the method returns the required size of the face-data buffer in the face_data_size parameter.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::Load

Loads a Direct3DRMMeshBuilder object.

HRESULT Load(
LPVOID lpvObjSource,
LPVOID lpvObjID,
D3DRMLOADOPTIONS d3drmLOFlags,
D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc,
LPVOID lpvArg
);

Parameters

lpvObjSource

Source for the object to be loaded. This source can be a file, resource, memory block, or stream, depending on the source flags specified in the d3drmLOFlags parameter.

lpvObjID

Object name or position to be loaded. The use of this parameter depends on the identifier flags specified in the d3drmLOFlags parameter. If the D3DRMLOAD_BYPOSITION flag is specified, this parameter is a pointer to a DWORD value that gives the object's order in the file. This parameter can be NULL.

d3drmLOFlags

Value of the D3DRMLOADOPTIONS type describing the load options.

d3drmLoadTextureProc

A D3DRMLOADTEXTURECALLBACK callback function called to load any textures used by an object.

lpvArg

Address of application-defined data passed to the D3DRMLOADTEXTURECALLBACK callback function.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

By default, this method loads the first mesh from the source specified in the lpvObjSource parameter.


IDirect3DRMMeshBuilder::QueryInterface

Determines if the Direct3DRMMeshBuilder object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMMeshBuilder.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMMeshBuilder::QueryInterface method allows Direct3DRMMeshBuilder objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMMeshBuilder::Release

Decreases the reference count of the Direct3DRMMeshBuilder object by 1. This method is part of the IUnknown interface inherited by Direct3DRMMeshBuilder.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMMeshBuilder object deallocates itself when its reference count reaches 0. Use the IDirect3DRMMeshBuilder::AddRef method to increase the reference count of the object by 1.


IDirect3DRMMeshBuilder::ReserveSpace

Reserves space within a Direct3DRMMeshBuilder object for the specified number of vertices, normals, and faces. This allows the system to use memory more efficiently.

HRESULT ReserveSpace(
DWORD vertexCount,
DWORD normalCount,
DWORD faceCount
);

Parameters

vertexCount, normalCount, and faceCount

Number of vertices, normals, and faces to allocate space for.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::Save

Saves a Direct3DRMMeshBuilder object.

HRESULT Save(
const char * lpFilename,
D3DRMXOFFORMAT d3drmXOFFormat,
D3DRMSAVEOPTIONS d3drmSOContents
);

Parameters

lpFilename

Address specifying the name of the created file. This file must have a .X file name extension.

d3drmXOFFormat

The D3DRMXOF_TEXT value from the D3DRMXOFFORMAT enumerated type.

d3drmSOContents

Value of the D3DRMSAVEOPTIONS type describing the save options.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::Scale

Scales a Direct3DRMMeshBuilder object by the given scaling factors, parallel to the x-, y-, and z-axes in model coordinates.

HRESULT Scale(
D3DVALUE sx,
D3DVALUE sy,
D3DVALUE sz
);

Parameters

sx, sy, and sz

Scaling factors that are applied along the x-, y-, and z-axes.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::SetColor

Sets all the faces of a Direct3DRMMeshBuilder object to a given color.

HRESULT SetColor(
D3DCOLOR color
);

Parameters

color

Color of the faces.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::SetColorRGB

Sets all the faces of a Direct3DRMMeshBuilder object to a given color.

HRESULT SetColorRGB(
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);

Parameters

red, green, and blue

Red, green, and blue components of the color.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::SetColorSource

Sets the color source of a Direct3DRMMeshBuilder object.

HRESULT SetColorSource(
D3DRMCOLORSOURCE source
);

Parameters

source

Member of the D3DRMCOLORSOURCE enumerated type that specifies the new color source to use.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMeshBuilder::GetColorSource


IDirect3DRMMeshBuilder::SetMaterial

Sets the material of all the faces of a Direct3DRMMeshBuilder object.

HRESULT SetMaterial(
LPDIRECT3DRMMATERIAL lpIDirect3DRMmaterial
);

Parameters

lpIDirect3DRMmaterial

Address of IDirect3DRMMaterial interface for the Direct3DRMMeshBuilder object.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::SetNormal

Sets the normal vector of a specified vertex in a Direct3DRMMeshBuilder object.

HRESULT SetNormal(
DWORD index,
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);

Parameters

index

Index of the normal to be set.

x, y, and z

The x, y, and z components of the vector to assign to the specified normal.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::SetPerspective

Enables or disables perspective-correct texture-mapping for a Direct3DRMMeshBuilder object.

HRESULT SetPerspective(
BOOL perspective
);

Parameters

perspective

Specify TRUE if the mesh should be texture-mapped with perspective correction, or FALSE otherwise.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::SetQuality

Sets the rendering quality of a Direct3DRMMeshBuilder object.

HRESULT SetQuality(
D3DRMRENDERQUALITY quality
);

Parameters

quality

Member of the D3DRMRENDERQUALITY enumerated type that specifies the new rendering quality to use.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMeshBuilder::GetQuality


IDirect3DRMMeshBuilder::SetTexture

Sets the texture of all the faces of a Direct3DRMMeshBuilder object.

HRESULT SetTexture(
LPDIRECT3DRMTEXTURE lpD3DRMTexture
);

Parameters

lpD3DRMTexture

Address of the required Direct3DRMTexture object.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::SetTextureCoordinates

Sets the texture coordinates of a specified vertex in a Direct3DRMMeshBuilder object.

HRESULT SetTextureCoordinates(
DWORD index,
D3DVALUE u,
D3DVALUE v
);

Parameters

index

Index of the vertex to be set.

u and v

Texture coordinates to assign to the specified mesh vertex.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMeshBuilder::GetTextureCoordinates


IDirect3DRMMeshBuilder::SetTextureTopology

Sets the texture topology of a Direct3DRMMeshBuilder object.

HRESULT SetTextureTopology(
BOOL cylU,
BOOL cylV
);

Parameters

cylU and cylV

Specify TRUE for either or both of these parameters if you want the texture to have a cylindrical topology in the u and v dimensions respectively; otherwise, specify FALSE.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::SetVertex

Sets the position of a specified vertex in a Direct3DRMMeshBuilder object.

HRESULT SetVertex(
DWORD index,
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);

Parameters

index

Index of the vertex to be set.

x, y, and z

The x, y, and z components of the position to assign to the specified vertex.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::SetVertexColor

Sets the color of a specified vertex in a Direct3DRMMeshBuilder object.

HRESULT SetVertexColor(
DWORD index,
D3DCOLOR color
);

Parameters

index

Index of the vertex to be set.

color

Color to assign to the specified vertex.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMMeshBuilder::GetVertexColor


IDirect3DRMMeshBuilder::SetVertexColorRGB

Sets the color of a specified vertex in a Direct3DRMMeshBuilder object.

HRESULT SetVertexColorRGB(
DWORD index,
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);

Parameters

index

Index of the vertex to be set.

red, green, and blue

Red, green, and blue components of the color to assign to the specified vertex.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMMeshBuilder::Translate

Adds the specified offsets to the vertex positions of a Direct3DRMMeshBuilder object.

HRESULT Translate(
D3DVALUE tx,
D3DVALUE ty,
D3DVALUE tz
);

Parameters

tx, ty, and tz

Offsets that are added to the x-, y-, and z-coordinates respectively of each vertex position.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMObject Interface


IDirect3DRMObject Interface Method Groups

Applications use the methods of the IDirect3DRMObject interface to work with the object superclass of Direct3DRM objects. The methods can be organized into the following groups:

Application-specific	GetAppData
data	SetAppData
Cloning	Clone
IUnknown	AddRef
	QueryInterface
	Release
Naming	GetClassName
	GetName
	SetName
Notifications	AddDestroyCallback
	DeleteDestroyCallback
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMObject object without affecting the functionality of the original interface.

The Direct3DRMObject object is obtained through the appropriate call to the QueryInterface method from any Direct3DRM object. All Direct3DRM objects inherit the IDirect3DRMObject interface methods.


IDirect3DRMObject::AddDestroyCallback

Registers a function to be called when an object is destroyed.

HRESULT AddDestroyCallback(
D3DRMOBJECTCALLBACK lpCallback,
LPVOID lpArg
);

Parameters

lpCallback

User-defined callback function that will be called when the object is destroyed.

lpArg

Address of application-defined data passed to the callback function. Because this function is called after the object has been destroyed, you should not call this function with the object as an argument.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMObject::AddRef

Increases the reference count of the Direct3DRMObject object by 1. This method is part of the IUnknown interface inherited by Direct3DRMObject.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMObject object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMObject::Release method to decrease the reference count of the object by 1.


IDirect3DRMObject::Clone

Creates a copy of an object.

HRESULT Clone(
LPUNKNOWN pUnkOuter,
REFIID riid,
LPVOID *ppvObj
);

Parameters

pUnkOuter

Allows COM aggregation features.

riid

Identifier of the object being copied.

ppvObj

Address that will contain the copy of the object when the method returns.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMObject::DeleteDestroyCallback

Removes a function previously registered with the IDirect3DRMObject::AddDestroyCallback method.

HRESULT DeleteDestroyCallback(
D3DRMOBJECTCALLBACK d3drmObjProc,
LPVOID lpArg
);

Parameters

d3drmObjProc

User-defined D3DRMOBJECTCALLBACK callback function that will be called when the object is destroyed.

lpArg

Address of application-defined data passed to the callback function.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMObject::GetAppData

Retrieves the 32 bits of application-specific data in the object. The default value is 0.

DWORD GetAppData( );

Return Values

Returns the data value defined by the application.

See Also

 IDirect3DRMObject::SetAppData


IDirect3DRMObject::GetClassName

Retrieves the name of the object's class.

HRESULT GetClassName(
LPDWORD lpdwSize,
LPSTR lpName
);

Parameters

lpdwSize

Address of a variable containing the size, in bytes, of the buffer pointed to by the lpName parameter.

lpName

Address of a variable that will contain a null-terminated string identifying the class name when the method returns. If this parameter is NULL, the lpdwSize parameter will contain the required size for the string when the method returns.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMObject::GetName

Retrieves the object's name.

HRESULT GetName(
LPDWORD lpdwSize,
LPSTR lpName
);

Parameters

lpdwSize

Address of a variable containing the size, in bytes, of the buffer pointed to by the lpName parameter.

lpName

Address of a variable that will contain a null-terminated string identifying the object's name when the method returns. If this parameter is NULL, the lpdwSize parameter will contain the required size for the string when the method returns.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMObject::SetName


IDirect3DRMObject::QueryInterface

Determines if the Direct3DRMObject object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMObject.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMObject::QueryInterface method allows Direct3DRMObject objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMObject::Release

Decreases the reference count of the Direct3DRMObject object by 1. This method is part of the IUnknown interface inherited by Direct3DRMObject.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMObject object deallocates itself when its reference count reaches 0. Use the IDirect3DRMObject::AddRef method to increase the reference count of the object by 1.


IDirect3DRMObject::SetAppData

Sets the 32 bits of application-specific data in the object.

HRESULT SetAppData(
DWORD ulData
);

Parameters

ulData

User-defined data to be stored with the object.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMObject::GetAppData


IDirect3DRMObject::SetName

Sets the object's name.

HRESULT SetName(
const char * lpName
);

Parameters

lpName

User-defined data to be the name for the object.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMObject::GetName


IDirect3DRMShadow Interface


IDirect3DRMShadow Interface Method Groups

Applications use the IDirect3DRMShadow interface to initialize Direct3DRMShadow objects. Note that this initialization is not necessary if the application calls the IDirect3DRM::CreateShadow method; it is required only if the application calls the IDirect3DRM::CreateObject method to create the shadow. This interface supports the following methods:

Initialization	Init
IUnknown	AddRef
	QueryInterface
	Release
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMShadow object without affecting the functionality of the original interface. In addition, the IDirect3DRMShadow interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMShadow object is obtained by calling the IDirect3DRM::CreateShadow method.


IDirect3DRMShadow::AddRef

Increases the reference count of the Direct3DRMShadow object by 1. This method is part of the IUnknown interface inherited by Direct3DRMShadow.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMShadow object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMShadow::Release method to decrease the reference count of the object by 1.


IDirect3DRMShadow::Init

Initializes a Direct3DRMShadow object.

HRESULT Init(
LPDIRECT3DRMVISUAL lpD3DRMVisual,
LPDIRECT3DRMLIGHT lpD3DRMLight,
D3DVALUE px,
D3DVALUE py,
D3DVALUE pz,
D3DVALUE nx,
D3DVALUE ny,
D3DVALUE nz
);

Parameters

lpD3DRMVisual

Address of the Direct3DRMVisual object casting the shadow.

lpD3DRMLight

Address of the Direct3DRMLight object that provides the light that defines the shadow.

px, py, and pz

Coordinates of a point on the plane on which the shadow is cast.

nx, ny, and nz

Coordinates of the normal vector of the plane on which the shadow is cast.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMShadow::QueryInterface

Determines if the Direct3DRMShadow object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMShadow.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMShadow::QueryInterface method allows Direct3DRMShadow objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMShadow::Release

Decreases the reference count of the Direct3DRMShadow object by 1. This method is part of the IUnknown interface inherited by Direct3DRMShadow.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMShadow object deallocates itself when its reference count reaches 0. Use the IDirect3DRMShadow::AddRef method to increase the reference count of the object by 1.


IDirect3DRMTexture Interface


IDirect3DRMTexture Interface Method Groups

Applications use the methods of the IDirect3DRMTexture interface to work with textures, which are rectangular arrays of pixels. The methods can be organized into the following groups:

Color	GetColors
	SetColors
Decals	GetDecalOrigin
	GetDecalScale
	GetDecalSize
	GetDecalTransparency
	GetDecalTransparentColor
	SetDecalOrigin
	SetDecalScale
	SetDecalSize
	SetDecalTransparency
	SetDecalTransparentColor
Images	GetImage
Initialization	InitFromFile
	InitFromResource
	InitFromSurface
IUnknown	AddRef
	QueryInterface
	Release
Renderer notification	Changed
Shading	GetShades
	SetShades
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMTexture object without affecting the functionality of the original interface. In addition, the IDirect3DRMTexture interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMTexture object is obtained by calling the IDirect3DRM::CreateTexture method.


IDirect3DRMTexture::AddRef

Increases the reference count of the Direct3DRMTexture object by 1. This method is part of the IUnknown interface inherited by Direct3DRMTexture.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMTexture object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMTexture::Release method to decrease the reference count of the object by 1.


IDirect3DRMTexture::Changed

Informs the renderer that the application has changed the pixels or the palette of a texture.

HRESULT Changed(
BOOL bPixels,
BOOL bPalette
);

Parameters

bPixels

If this parameter is TRUE, the pixels have changed.

bPalette

If this parameter is TRUE, the palette has changed.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMTexture::GetColors

Retrieves the maximum number of colors used for rendering a texture.

DWORD GetColors( );

Return Values

Returns the number of colors.

Remarks

This method returns the number of colors that the texture has been quantized to, not the number of colors in the image from which the texture was created. Consequently, the number of colors that are returned usually matches the colors that were set by calling the IDirect3DRM::SetDefaultTextureColors method, unless you used the IDirect3DRMTexture::SetColors method explicitly to change the colors for the texture.

See Also

 IDirect3DRMTexture::SetColors


IDirect3DRMTexture::GetDecalOrigin

Retrieves the current origin of the decal.

HRESULT GetDecalOrigin(
LONG * lplX,
LONG * lplY
);

Parameters

lplX and lplY

Addresses of variables that will be filled with the origin of the decal when the method returns.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMTexture::SetDecalOrigin


IDirect3DRMTexture::GetDecalScale

Retrieves the scaling property of the given decal.

DWORD GetDecalScale( );

Return Values

Returns the scaling property if successful, or -1 otherwise.

See Also

 IDirect3DRMTexture::SetDecalScale


IDirect3DRMTexture::GetDecalSize

Retrieves the size of the decal.

HRESULT GetDecalSize(
D3DVALUE *lprvWidth,
D3DVALUE *lprvHeight
);

Parameters

lprvWidth and lprvHeight

Addresses of variables that will be filled with the width and height of the decal when the method returns.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMTexture::SetDecalSize


IDirect3DRMTexture::GetDecalTransparency

Retrieves the transparency property of the decal.

BOOL GetDecalTransparency( );

Return Values

Returns TRUE if the decal has a transparent color, FALSE otherwise.

See Also

 IDirect3DRMTexture::SetDecalTransparency


IDirect3DRMTexture::GetDecalTransparentColor

Retrieves the transparent color of the decal.

D3DCOLOR GetDecalTransparentColor( );

Return Values

Returns the value of the transparent color.

See Also

 IDirect3DRMTexture::SetDecalTransparentColor


IDirect3DRMTexture::GetImage

Returns an address of the image that the texture was created with.

D3DRMIMAGE * GetImage( );

Return Values

Returns the address of the D3DRMIMAGE structure that the current texture was created with.


IDirect3DRMTexture::GetShades

Retrieves the number of shades used for each color in the texture when rendering.

DWORD GetShades( );

Return Values

Returns the number of shades.

See Also

 IDirect3DRMTexture::SetShades


IDirect3DRMTexture::InitFromFile

Initializes a texture by using the information in a given file.

HRESULT InitFromFile(
const char *filename
);

Parameters

filename

Address of a string specifying the file from which initialization information is drawn.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMTexture::InitFromResource, IDirect3DRMTexture::InitFromSurface


IDirect3DRMTexture::InitFromResource

Initializes a Direct3DRMTexture object from a specified resource.

HRESULT InitFromResource(
HRSRC rs
);

Parameters

rs

Handle of the specified resource.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMTexture::InitFromFile, IDirect3DRMTexture::InitFromSurface


IDirect3DRMTexture::InitFromSurface

Initializes a texture by using the data from a given DirectDraw surface.

HRESULT InitFromSurface(
LPDIRECTDRAWSURFACE lpDDS
);

Parameters

lpDDS

Address of a DirectDraw surface from which initialization information is drawn.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMTexture::InitFromFile, IDirect3DRMTexture::InitFromResource


IDirect3DRMTexture::QueryInterface

Determines if the Direct3DRMTexture object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMTexture.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMTexture::QueryInterface method allows Direct3DRMTexture objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMTexture::Release

Decreases the reference count of the Direct3DRMTexture object by 1. This method is part of the IUnknown interface inherited by Direct3DRMTexture.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMTexture object deallocates itself when its reference count reaches 0. Use the IDirect3DRMTexture::AddRef method to increase the reference count of the object by 1.


IDirect3DRMTexture::SetColors

Sets the maximum number of colors used for rendering a texture. This method is required only in the ramp color model.

HRESULT SetColors(
DWORD ulColors
);

Parameters

ulColors

Number of colors. The default value is 8.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMTexture::GetColors


IDirect3DRMTexture::SetDecalOrigin

Sets the origin of the decal as an offset from the top left of the decal.

HRESULT SetDecalOrigin(
LONG lX,
LONG lY
);

Parameters

lX and lY

New origin, in decal coordinates, for the decal. The default origin is [0, 0].

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The decal's origin is mapped to its frame's position when rendering. For example, the origin of a decal of a cross would be set to the middle of the decal, and the origin of an arrow pointing down would be set to midway along the bottom edge.

See Also

 IDirect3DRMTexture::GetDecalOrigin


IDirect3DRMTexture::SetDecalScale

Sets the scaling property for a decal.

HRESULT SetDecalScale(
DWORD dwScale
);

Parameters

dwScale

If this parameter is TRUE, depth is taken into account when the decal is scaled. If it is FALSE, depth information is ignored. The default value is TRUE.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMTexture::GetDecalScale


IDirect3DRMTexture::SetDecalSize

Sets the size of the decal to be used if the decal is being scaled according to its depth in the scene.

HRESULT SetDecalSize(
D3DVALUE rvWidth,
D3DVALUE rvHeight
);

Parameters

rvWidth and rvHeight

New width and height, in model coordinates, of the decal. The default size is [1, 1].

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMTexture::GetDecalSize


IDirect3DRMTexture::SetDecalTransparency

Sets the transparency property of the decal.

HRESULT SetDecalTransparency(
BOOL bTransp
);

Parameters

bTransp

If this parameter is TRUE, the decal has a transparent color. If it is FALSE, it has an opaque color. The default value is FALSE.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMTexture::GetDecalTransparency


IDirect3DRMTexture::SetDecalTransparentColor

Sets the transparent color for a decal.

HRESULT SetDecalTransparentColor(
D3DCOLOR rcTransp
);

Parameters

rcTransp

New transparent color. The default transparent color is black.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMTexture::GetDecalTransparentColor


IDirect3DRMTexture::SetShades

Sets the maximum number of shades to use for each color for the texture when rendering. This method is required only in the ramp color model.

HRESULT SetShades(
DWORD ulShades
);

Parameters

ulShades

New number of shades. The default value is 16.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMTexture::GetShades


IDirect3DRMUserVisual Interface


IDirect3DRMUserVisual Interface Method Groups

Applications use the IDirect3DRMUserVisual interface to initialize Direct3DRMUserVisual objects. Note that this initialization is not necessary if the application calls the IDirect3DRM::CreateUserVisual method; it is required only if the application calls the IDirect3DRM::CreateObject method to create the user-visual object. This interface supports the following methods:

Initialization	Init
IUnknown	AddRef
	QueryInterface
	Release
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMUserVisual object without affecting the functionality of the original interface. In addition, the IDirect3DRMUserVisual interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMUserVisual object is obtained by calling the IDirect3DRM::CreateUserVisual method.


IDirect3DRMUserVisual::AddRef

Increases the reference count of the Direct3DRMUserVisual object by 1. This method is part of the IUnknown interface inherited by Direct3DRMUserVisual.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMUserVisual object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMUserVisual::Release method to decrease the reference count of the object by 1.


IDirect3DRMUserVisual::Init

Initializes a Direct3DRMUserVisual object.

HRESULT Init(
D3DRMUSERVISUALCALLBACK d3drmUVProc,
void * lpArg
);

Parameters

d3drmUVProc

Application-defined D3DRMUSERVISUALCALLBACK callback function.

lpArg

Application-defined data to be passed to the callback function.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

Applications can call the IDirect3DRM::CreateUserVisual method to create and initialize a user-visual object at the same time. It is necessary to call IDirect3DRMUserVisual::Init only when the application has created the user-visual object by calling the IDirect3DRM::CreateObject method.


IDirect3DRMUserVisual::QueryInterface

Determines if the Direct3DRMUserVisual object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMUserVisual.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMUserVisual::QueryInterface method allows Direct3DRMUserVisual objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMUserVisual::Release

Decreases the reference count of the Direct3DRMUserVisual object by 1. This method is part of the IUnknown interface inherited by Direct3DRMUserVisual.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMUserVisual object deallocates itself when its reference count reaches 0. Use the IDirect3DRMUserVisual::AddRef method to increase the reference count of the object by 1.


IDirect3DRMViewport Interface


IDirect3DRMViewport Interface Method Groups

Applications use the methods of the IDirect3DRMViewport interface to work with viewport objects. The methods can be organized into the following groups:

Camera	GetCamera
	SetCamera
Clipping planes	GetBack
	GetFront
	GetPlane
	SetBack
	SetFront
	SetPlane
Dimensions	GetHeight
	GetWidth
Field of view	GetField
	SetField
Initialization	Init
IUnknown	AddRef
	QueryInterface
	Release
Miscellaneous	Clear
	Configure
	ForceUpdate
	GetDevice
	GetDirect3DViewport
	Pick
	Render
Offsets	GetX
	GetY
Projection types	GetProjection
	SetProjection
Scaling	GetUniformScaling
	SetUniformScaling
Transformations	InverseTransform
	Transform
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMViewport object without affecting the functionality of the original interface. In addition, the IDirect3DRMViewport interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMViewport object is obtained by calling the IDirect3DRM::CreateViewport method.


IDirect3DRMViewport::AddRef

Increases the reference count of the Direct3DRMViewport object by 1. This method is part of the IUnknown interface inherited by Direct3DRMViewport.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMViewport object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMViewport::Release method to decrease the reference count of the object by 1.


IDirect3DRMViewport::Clear

Clears the given viewport to the current background color.

HRESULT Clear( );

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMViewport::Configure

This method is not functional in DirectX 2. Instead of using this method, your application can destroy the old viewport and create a new one at the new position and size.

This information for this method is new since the DirectX 2 SDK was released. For a list of all changes to the documentation since the SDK was released, see New Information.

HRESULT Configure(
LONG lX,
LONG lY,
DWORD dwWidth,
DWORD dwHeight
);


IDirect3DRMViewport::ForceUpdate

Forces an area of the viewport to be updated. The specified area will be copied to the screen at the next call to the IDirect3DRMDevice::Update method.

HRESULT ForceUpdate(
DWORD dwX1,
DWORD dwY1,
DWORD dwX2,
DWORD dwY2
);

Parameters

dwX1 and dwY1

Upper-left corner of area to be updated.

dwX2 and dwY2

Lower-right corner of area to be updated.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The system might update any region that is larger than the specified rectangle, including possibly the entire window.


IDirect3DRMViewport::GetBack

Retrieves the position of the back clipping plane for a viewport.

D3DVALUE GetBack( );

Return Values

Returns a value describing the position.

See Also

 IDirect3DRMViewport::SetBack, Viewing Frustum


IDirect3DRMViewport::GetCamera

Retrieves the camera for a viewport.

HRESULT GetCamera(
LPDIRECT3DRMFRAME *lpCamera
);

Parameters

lpCamera

Address of a variable that represents the Direct3DRMFrame object representing the camera.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMViewport::SetCamera, Camera


IDirect3DRMViewport::GetDevice

Retrieves the device associated with a viewport.

HRESULT GetDevice(
LPDIRECT3DRMDEVICE *lpD3DRMDevice
);

Parameters

lpD3DRMDevice

Address of a variable that represents the Direct3DRMDevice object.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMViewport::GetDirect3DViewport

Retrieves the Direct3D viewport corresponding to the current Direct3DRMViewport.

HRESULT GetDirect3DViewport(
LPDIRECT3DVIEWPORT * lplpD3DViewport
);

Parameters

lplpD3DViewport

Address of a pointer that is initialized with a pointer to the Direct3DViewport object.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMViewport::GetField

Retrieves the field of view for a viewport.

D3DVALUE GetField( );

Return Values

Returns a value describing the field of view.

See Also

 IDirect3DRMViewport::SetField, Viewing Frustum


IDirect3DRMViewport::GetFront

Retrieves the position of the front clipping plane for a viewport.

D3DVALUE GetFront( );

Return Values

Returns a value describing the position.

See Also

 IDirect3DRMViewport::SetFront, Viewing Frustum


IDirect3DRMViewport::GetHeight

Retrieves the height, in pixels, of the viewport.

DWORD GetHeight( );

Return Values

Returns the pixel height.


IDirect3DRMViewport::GetPlane

Retrieves the front clipping plane of the viewing frustum.

HRESULT GetPlane(
D3DVALUE *lpd3dvLeft,
D3DVALUE *lpd3dvRight,
D3DVALUE *lpd3dvBottom,
D3DVALUE *lpd3dvTop
);

Parameters

lpd3dvLeft, lpd3dvRight, lpd3dvBottom, and lpd3dvTop

Addresses of variables that will be filled to represent the front clipping plane.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMViewport::SetPlane


IDirect3DRMViewport::GetProjection

Retrieves the projection type for the viewport. A viewport can use either orthographic or perspective projection.

D3DRMPROJECTIONTYPE GetProjection( );

Return Values

Returns one of the members of the D3DRMPROJECTIONTYPE enumerated type.

See Also

 IDirect3DRMViewport::SetProjection


IDirect3DRMViewport::GetUniformScaling

Retrieves the scaling property used to scale the viewing volume into the larger dimension of the window.

BOOL GetUniformScaling( );

Return Values

Returns TRUE if the viewport scales uniformly, or FALSE otherwise.

See Also

 IDirect3DRMViewport::SetUniformScaling


IDirect3DRMViewport::GetWidth

Retrieves the width, in pixels, of the viewport.

DWORD GetWidth( );

Return Values

Returns the pixel width.


IDirect3DRMViewport::GetX

Retrieves the x-offset of the start of the viewport on a device.

LONG GetX( );

Return Values

Returns the x-offset.


IDirect3DRMViewport::GetY

Retrieves the y-offset of the start of the viewport on a device.

LONG GetY( );

Return Values

Returns the y-offset.


IDirect3DRMViewport::Init

Initializes a Direct3DRMViewport object.

HRESULT Init(
LPDIRECT3DRMDEVICE lpD3DRMDevice,
LPDIRECT3DRMFRAME lpD3DRMFrameCamera,
DWORD xpos,
DWORD ypos,
DWORD width,
DWORD height
);

Parameters

lpD3DRMDevice

Address of the DirectD3DRMDevice object associated with this viewport.

lpD3DRMFrameCamera

Address of the camera frame associated with this viewport.

xpos and ypos

The x- and y-coordinates of the upper-left corner of the viewport.

width and height

Width and height of the viewport.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMViewport::InverseTransform

Transforms the vector in the lprvSrc parameter in screen coordinates to world coordinates, and returns the result in the lprvDst parameter.

HRESULT InverseTransform(
D3DVECTOR * lprvDst,
D3DRMVECTOR4D * lprvSrc
);

Parameters

lprvDst

Address of a D3DVECTOR structure that will be filled with the result of the operation when the method returns.

lprvSrc

Address of a D3DRMVECTOR4D structure representing the source of the operation.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMViewport::Pick

Finds a depth-sorted list of objects (and faces, if relevant) that includes the path taken in the hierarchy from the root down to the frame that contained the object.

HRESULT Pick(
LONG lX,
LONG lY,
LPDIRECT3DRMPICKEDARRAY* lplpVisuals
);

Parameters

lX and lY

Coordinates to be used for picking.

lplpVisuals

Address of a pointer to be initialized with a valid pointer to the IDirect3DRMPickedArray interface if the call succeeds.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMViewport::QueryInterface

Determines if the Direct3DRMViewport object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMViewport.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMViewport::QueryInterface method allows Direct3DRMViewport objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMViewport::Release

Decreases the reference count of the Direct3DRMViewport object by 1. This method is part of the IUnknown interface inherited by Direct3DRMViewport.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMViewport object deallocates itself when its reference count reaches 0. Use the IDirect3DRMViewport::AddRef method to increase the reference count of the object by 1.


IDirect3DRMViewport::Render

Renders a frame hierarchy to the given viewport. Only those visuals on the given frame and any frames below it in the hierarchy are rendered.

HRESULT Render(
LPDIRECT3DRMFRAME lpD3DRMFrame
);

Parameters

lpD3DRMFrame

Address of a variable that represents the Direct3DRMFrame object that represents the frame hierarchy to be rendered.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMViewport::SetBack

Sets the position of the back clipping plane for a viewport.

HRESULT SetBack(
D3DVALUE rvBack
);

Parameters

rvBack

New position of the back clipping plane.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMViewport::GetBack, IDirect3DRMViewport::SetFront, Viewing Frustum


IDirect3DRMViewport::SetCamera

Sets a camera for a viewport.

HRESULT SetCamera(
LPDIRECT3DRMFRAME lpCamera
);

Parameters

lpCamera

Address of a variable that represents the Direct3DRMFrame object that represents the camera.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

This method sets a viewport's position, direction, and orientation to that of the given camera frame. The view is oriented along the positive z-axis of the camera frame, with the up direction being in the direction of the positive y-axis.

See Also

 IDirect3DRMViewport::GetCamera, Camera


IDirect3DRMViewport::SetField

Sets the field of view for a viewport.

HRESULT SetField(
D3DVALUE rvField
);

Parameters

rvField

New field of view. The default value is 0.5. If this value is less than or equal to zero, this method returns the D3DRMERR_BADVALUE error.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMViewport::GetField, Viewing Frustum


IDirect3DRMViewport::SetFront

Sets the position of the front clipping plane for a viewport.

HRESULT SetFront(
D3DVALUE rvFront
);

Parameters

rvFront

New position of the front clipping plane.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The default position is 1.0. If the value passed is less than or equal to zero, this method returns the D3DRMERR_BADVALUE error.

See Also

 IDirect3DRMViewport::GetFront, Viewing Frustum


IDirect3DRMViewport::SetPlane

Sets the front clipping plane of the viewing frustum by supplying the coordinates of the four sides, relative to the camera's z-axis.

HRESULT SetPlane(
D3DVALUE rvLeft,
D3DVALUE rvRight,
D3DVALUE rvBottom,
D3DVALUE rvTop
);

Parameters

rvLeft, rvRight, rvBottom, and rvTop

New front clipping plane.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMViewport::GetPlane


IDirect3DRMViewport::SetProjection

Sets the projection type for a viewport.

HRESULT SetProjection(
D3DRMPROJECTIONTYPE rptType
);

Parameters

rptType

One of the members of the D3DRMPROJECTIONTYPE enumerated type.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRMViewport::GetProjection


IDirect3DRMViewport::SetUniformScaling

Sets the scaling property used to scale the viewing volume into the larger dimension of the window.

HRESULT SetUniformScaling(
BOOL bScale
);

Parameters

bScale

New scaling property. If this parameter is TRUE, the same horizontal and vertical scaling factor is used to scale the viewing volume. Otherwise, different scaling factors are used to scale the viewing volume exactly into the window. The default setting is TRUE.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

This method is typically used with the IDirect3DRMViewport::SetPlane method to support banding.

See Also

 IDirect3DRMViewport::GetUniformScaling


IDirect3DRMViewport::Transform

Transforms the vector in the lprvSrc parameter in world coordinates to screen coordinates, and returns the result in the lprvDst parameter.

HRESULT Transform(
D3DRMVECTOR4D * lprvDst,
D3DVECTOR * lprvSrc
);

Parameters

lprvDst

Address of a D3DRMVECTOR4D structure that acts as the destination for the transformation operation.

lprvSrc

Address of a D3DVECTOR structure that acts as the source for the transformation operation.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

Remarks

The result of the transformation is a four-element homogeneous vector to avoid dividing by zero when the vector is close to the camera's position. The point represented by the resulting vector is visible if the following equations are true:


IDirect3DRMWinDevice Interface


IDirect3DRMWinDevice Interface Method Groups

Applications use the methods of the IDirect3DRMWinDevice interface to respond to window messages in a window procedure. This interface supports the following methods:

Handles	HandleActivate
	HandlePaint
IUnknown	AddRef
	QueryInterface
	Release
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMWinDevice object without affecting the functionality of the original interface.

The Direct3DRMWinDevice object is obtained by calling the IDirect3DRMObject::QueryInterface method and specifying IID_IDirect3DRMWinDevice, or by calling a method such as IDirect3DRM::CreateDeviceFromD3D. Its methods are inherited from the IDirect3DRMDevice interface.


IDirect3DRMWinDevice::AddRef

Increases the reference count of the Direct3DRMWinDevice object by 1. This method is part of the IUnknown interface inherited by Direct3DRMWinDevice.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMWinDevice object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMWinDevice::Release method to decrease the reference count of the object by 1.


IDirect3DRMWinDevice::HandleActivate

Responds to a Windows WM_ACTIVATE message. This ensures that the colors are correct in the active rendering window.

HRESULT HandleActivate(
WORD wParam
);

Parameters

wParam

WPARAM parameter passed to the message-processing procedure with the WM_ACTIVATE message.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMWinDevice::HandlePaint

Responds to a Windows WM_PAINT message. The hDC parameter should be taken from the PAINTSTRUCT structure given to the Windows BeginPaint function. This method should be called before repainting any application areas in the window because it may repaint areas outside the viewports that have been created on the device.

HRESULT HandlePaint(
HDC hDC
);

Parameters

hDC

Handle of the device context (DC).

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.


IDirect3DRMWinDevice::QueryInterface

Determines if the Direct3DRMWinDevice object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMWinDevice.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMWinDevice::QueryInterface method allows Direct3DRMWinDevice objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMWinDevice::Release

Decreases the reference count of the Direct3DRMWinDevice object by 1. This method is part of the IUnknown interface inherited by Direct3DRMWinDevice.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMWinDevice object deallocates itself when its reference count reaches 0. Use the IDirect3DRMWinDevice::AddRef method to increase the reference count of the object by 1.


IDirect3DRMWrap Interface


IDirect3DRMWrap Interface Method Groups

Applications use the methods of the IDirect3DRMWrap interface to work with wrap objects. This interface supports the following methods:

Initialization	Init
IUnknown	AddRef
	QueryInterface
	Release
Wrap	Apply
	ApplyRelative
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DRMWrap object without affecting the functionality of the original interface. In addition, the IDirect3DRMWrap interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName
The Direct3DRMWrap object is obtained by calling the IDirect3DRM::CreateWrap method.


IDirect3DRMWrap::AddRef

Increases the reference count of the Direct3DRMWrap object by 1. This method is part of the IUnknown interface inherited by Direct3DRMWrap.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DRMWrap object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DRMWrap::Release method to decrease the reference count of the object by 1.


IDirect3DRMWrap::Apply

Applies a Direct3DRMWrap object to its destination object. The destination object is typically a face or a mesh.

HRESULT Apply(
LPDIRECT3DRMOBJECT lpObject
);

Parameters

lpObject

Address of the destination object.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRM::CreateWrap


IDirect3DRMWrap::ApplyRelative

Applies the wrap to the vertices of the object, first transforming each vertex by the frame's world transformation and the wrap's reference frame's inverse world transformation.

HRESULT ApplyRelative(
LPDIRECT3DRMFRAME frame,
LPDIRECT3DRMOBJECT mesh
);

Parameters

frame

Direct3DRMFrame object containing the object to wrap.

mesh

Direct3DRMWrap object to apply.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRM::CreateWrap


IDirect3DRMWrap::Init

Initializes a Direct3DRMWrap object.

HRESULT Init(
D3DRMWRAPTYPE d3drmwt,
LPDIRECT3DRMFRAME lpd3drmfRef,
D3DVALUE ox,
D3DVALUE oy,
D3DVALUE oz,
D3DVALUE dx,
D3DVALUE dy,
D3DVALUE dz,
D3DVALUE ux,
D3DVALUE uy,
D3DVALUE uz,
D3DVALUE ou,
D3DVALUE ov,
D3DVALUE su,
D3DVALUE sv
);

Parameters

d3drmwt

One of the members of the D3DRMWRAPTYPE enumerated type.

lpd3drmfRef

Address of a Direct3DRMFrame object representing the reference frame for this Direct3DRMWrap object.

ox, oy, and oz

Origin of the wrap.

dx, dy, and dz

The z-axis of the wrap.

ux, uy, and uz

The y-axis of the wrap.

ou and ov

Origin in the texture.

su and sv

Scale factor in the texture.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained-Mode Return Values.

See Also

 IDirect3DRM::CreateWrap


IDirect3DRMWrap::QueryInterface

Determines if the Direct3DRMWrap object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DRMWrap.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3DRM_OK if successful, or D3DRMERR_BADVALUE otherwise.

Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DRMWrap::QueryInterface method allows Direct3DRMWrap objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DRMWrap::Release

Decreases the reference count of the Direct3DRMWrap object by 1. This method is part of the IUnknown interface inherited by Direct3DRMWrap.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DRMWrap object deallocates itself when its reference count reaches 0. Use the IDirect3DRMWrap::AddRef method to increase the reference count of the object by 1.


Structures


D3DRMBOX

Defines the bounding box retrieved by the IDirect3DRMMesh::GetBox and IDirect3DRMMeshBuilder::GetBox methods.

typedef struct _D3DRMBOX {

    D3DVECTOR min, max;

}D3DRMBOX;

typedef D3DRMBOX *LPD3DRMBOX;

Members

min and #max

Values defining the bounds of the box. These values are D3DVECTOR structures.

See Also

 D3DVECTOR, IDirect3DRMMesh::GetBox, IDirect3DRMMeshBuilder::GetBox


D3DRMIMAGE

Describes an image that is attached to a texture by the IDirect3DRM::CreateTexture method. IDirect3DRMTexture::GetImage returns the address of this image.

typedef struct _D3DRMIMAGE {

    int                width, height;

    int                aspectx, aspecty;

    int                depth;

    int                rgb;

    int                bytes_per_line;

    void*              buffer1;

    void*              buffer2;

    unsigned long      red_mask;

    unsigned long      green_mask;

    unsigned long      blue_mask;

    unsigned long      alpha_mask;

    int                palette_size;

    D3DRMPALETTEENTRY* palette;

}D3DRMIMAGE;

typedef D3DRMIMAGE, *LPD3DRMIMAGE;

Members

width and #height

Width and height of the image, in pixels.

aspectx and #aspecty

Aspect ratio for nonsquare pixels.

depth

Bits per pixel.

rgb

If this member FALSE, pixels are indices into a palette. Otherwise, pixels encode RGB values.

bytes_per_line

Number of bytes of memory for a scanline. This value must be a multiple of four.

buffer1

Memory to render into (first buffer).

buffer2

Second rendering buffer for double buffering. Set this member to NULL for single buffering.

red_mask, #green_mask, #blue_mask, and #alpha_mask

If rgb is TRUE, these members are masks for the red, green, and blue parts of a pixel. Otherwise, they are masks for the significant bits of the red, green, and blue elements in the palette. For example, most SVGA displays use 64 intensities of red, green, and blue, so the masks should all be set to 0xfc.

palette_size

Number of entries in the palette.

palette

If rgb is FALSE, this member is the address of a D3DRMPALETTEENTRY structure describing the palette entry.

See Also

 IDirect3DRM::CreateTexture, IDirect3DRMTexture::GetImage


D3DRMLOADMEMORY

Identifies a resource to be loaded when an application calls the IDirect3DRM::Load method (or one of the other Load methods) and specifies D3DRMLOAD_FROMMEMORY.

typedef struct _D3DRMLOADMEMORY {

    LPVOID lpMemory;

    DWORD  dSize;

} D3DRMLOADMEMORY, *LPD3DRMLOADMEMORY;

Members

lpMemory

Address of a block of memory to be loaded.

dSize

Size, in bytes, of the block of memory to be loaded.

See Also

 IDirect3DRM::Load, IDirect3DRMAnimationSet::Load, IDirect3DRMFrame::Load, IDirect3DRMMeshBuilder::Load, D3DRMLOADOPTIONS, D3DRMLOADRESOURCE


D3DRMLOADRESOURCE

Identifies a resource to be loaded when an application calls the IDirect3DRM::Load method (or one of the other Load methods) and specifies D3DRMLOAD_FROMRESOURCE.

typedef struct _D3DRMLOADRESOURCE {

    HMODULE hModule;

    LPCTSTR lpName;

    LPCTSTR lpType;

} D3DRMLOADRESOURCE, *LPD3DRMLOADRESOURCE;

Members

hModule

Handle of the module containing the resource to be loaded. If this member is NULL, the resource must be attached to the calling executable file.

lpName

Name of the resource to be loaded. For example, if the resource is a mesh, this member should specify the name of the mesh file.

lpType

User-defined type identifying the resource.

Remarks

If the high-order word of the lpName or lpType member is zero, the low-order word specifies the integer identifier of the name or type of the given resource. Otherwise, those parameters are long pointers to null-terminated strings. If the first character of the string is a pound sign (#), the remaining characters represent a decimal number that specifies the integer identifier of the resource's name or type. For example, the string "#258" represents the integer identifier 258. An application should reduce the amount of memory required for the resources by referring to them by integer identifier instead of by name.

When an application calls a Load method and specifies D3DRMLOAD_FROMRESOURCE, it does not need to find or unlock any resources; the system handles this automatically.

See Also

 IDirect3DRM::Load, IDirect3DRMAnimationSet::Load, IDirect3DRMFrame::Load, IDirect3DRMMeshBuilder::Load, D3DRMLOADMEMORY, D3DRMLOADOPTIONS


D3DRMPALETTEENTRY

Describes the color palette used in a D3DRMIMAGE structure. This structure is used only if the rgb member of the D3DRMIMAGE structure is FALSE. (If it is TRUE, RGB values are used.)

typedef struct _D3DRMPALETTEENTRY {

    unsigned char red;

    unsigned char green;

    unsigned char blue;

    unsigned char flags;

}D3DRMPALETTEENTRY;

typedef D3DRMPALETTEENTRY, *LPD3DRMPALETTEENTRY;

Members

red, #green, and #blue

Values defining the primary color components that define the palette. These values can range from 0 through 255.

flags

Value defining how the palette is used by the renderer. This value is one of the members of the D3DRMPALETTEFLAGS enumerated type.

See Also

 D3DRMIMAGE, D3DRMPALETTEFLAGS


D3DRMPICKDESC

Contains the pick position and face and group identifiers of the objects retrieved by the IDirect3DRMPickedArray::GetPick method.

typedef struct _D3DRMPICKDESC {

    ULONG       ulFaceIdx;

    LONG        lGroupIdx;

    D3DVECTOR   vPosition;

} D3DRMPICKDESC, *LPD3DRMPICKDESC;

Members

ulFaceIdx

Face index of the retrieved object.

lGroupIdx

Group index of the retrieved object.

vPosition

Value describing the position of the retrieved object. This value is a D3DVECTOR structure.

See Also

 D3DVECTOR, IDirect3DRMPickedArray::GetPick


D3DRMQUATERNION

Describes the rotation used by the IDirect3DRMAnimation::AddRotateKey method. It is also used in several of Direct3D's mathematical functions.

typedef struct _D3DRMQUATERNION {

    D3DVALUE   s;

    D3DVECTOR  v;

}D3DRMQUATERNION;

typedef D3DRMQUATERNION, *LPD3DRMQUATERNION;

See Also

 IDirect3DRMAnimation::AddRotateKey, D3DRMQuaternionFromRotation, D3DRMQuaternionMultiply, D3DRMQuaternionSlerp, D3DRMMatrixFromQuaternion


D3DRMVECTOR4D

Describes the screen coordinates used as the destination of a transformation by the IDirect3DRMViewport::Transform method and as the source of a transformation by the IDirect3DRMViewport::InverseTransform method.

typedef struct _D3DRMVECTOR4D {

    D3DVALUE x;

    D3DVALUE y;

    D3DVALUE z;

    D3DVALUE w;

}D3DRMVECTOR4D;

typedef D3DRMVECTOR4D, *LPD3DRMVECTOR4D;

Members

x, #y, #z, and #w

Values of the D3DVALUE type describing homogeneous values. These values define the result of the transformation.

See Also

 IDirect3DRMViewport::Transform, IDirect3DRMViewport::InverseTransform


D3DRMVERTEX

Describes a vertex in a Direct3DRMMesh object.

typedef struct _D3DRMVERTEX{

    D3DVECTOR position;

    D3DVECTOR normal;

    D3DVALUE  tu, tv;

    D3DCOLOR  color;

} D3DRMVERTEX;

Members

position

Position of the vertex.

normal

Normal vector for the vertex.

tu and #tv

Horizontal and vertical texture coordinates, respectively, for the vertex.

color

Vertex color.

See Also

 IDirect3DRMMesh::GetVertices, IDirect3DRMMesh::SetVertices


Enumerated Types


D3DRMCOLORSOURCE

Describes the color source of a Direct3DRMMeshBuilder object. You can set the color source by using the IDirect3DRMMeshBuilder::SetColorSource method. To retrieve it, use the IDirect3DRMMeshBuilder::GetColorSource method.

typedef enum _D3DRMCOLORSOURCE{

    D3DRMCOLOR_FROMFACE,

    D3DRMCOLOR_FROMVERTEX

} D3DRMCOLORSOURCE;

Values

D3DRMCOLOR_FROMFACE

The object's color source is a face.

D3DRMCOLOR_FROMVERTEX

The object's color source is a vertex.

See Also

 IDirect3DRMMeshBuilder::SetColorSource, IDirect3DRMMeshBuilder::GetColorSource


D3DRMCOMBINETYPE

Specifies how to combine two matrices.

typedef enum _D3DRMCOMBINETYPE{

    D3DRMCOMBINE_REPLACE,

    D3DRMCOMBINE_BEFORE,

    D3DRMCOMBINE_AFTER

} D3DRMCOMBINETYPE;

Values

D3DRMCOMBINE_REPLACE

The supplied matrix replaces the frame's current matrix.

D3DRMCOMBINE_BEFORE

The supplied matrix is multiplied with the frame's current matrix and precedes the current matrix in the calculation.

D3DRMCOMBINE_AFTER

The supplied matrix is multiplied with the frame's current matrix and follows the current matrix in the calculation.

Remarks

The order of the supplied and current matrices when they are multiplied together is important because matrix multiplication is not commutative.

See Also

 IDirect3DRMFrame::AddRotation, IDirect3DRMFrame::AddScale, IDirect3DRMFrame::AddTransform, IDirect3DRMFrame::AddTranslation


D3DRMFILLMODE

One of the enumerated types that is used in the definition of the D3DRMRENDERQUALITY type.

typedef enum _D3DRMFILLMODE {

    D3DRMFILL_POINTS    = 0 * D3DRMLIGHT_MAX,

    D3DRMFILL_WIREFRAME = 1 * D3DRMLIGHT_MAX,

    D3DRMFILL_SOLID     = 2 * D3DRMLIGHT_MAX,

    D3DRMFILL_MASK      = 7 * D3DRMLIGHT_MAX,

    D3DRMFILL_MAX       = 8 * D3DRMLIGHT_MAX

} D3DRMFILLMODE;

Values

D3DRMFILL_POINTS

Fills points only; minimum fill mode.

D3DRMFILL_WIREFRAME

Fill wireframes.

D3DRMFILL_SOLID

Fill solid objects.

D3DRMFILL_MASK

Fill using a mask.

D3DRMFILL_MAX

Maximum value for fill mode.

See Also

 D3DRMLIGHTMODE, D3DRMSHADEMODE, D3DRMRENDERQUALITY


D3DRMFOGMODE

Contains values that specify how rapidly and in what ways the fog effect intensifies with increasing distance from the camera.

typedef enum _D3DRMFOGMODE{

    D3DRMFOG_LINEAR,

    D3DRMFOG_EXPONENTIAL,

    D3DRMFOG_EXPONENTIALSQUARED

} D3DRMFOGMODE;

Values

D3DRMFOG_LINEAR

The fog effect intensifies linearly between the start and end points, according to the following formula:

This is the only fog mode supported for DirectX 2.

D3DRMFOG_EXPONENTIAL

The fog effect intensifies exponentially, according to the following formula:

D3DRMFOG_EXPONENTIALSQUARED

The fog effect intensifies exponentially with the square of the distance, according to the following formula:

Remarks

Note that fog can be considered a measure of visibility—the lower the fog value produced by one of the fog equations, the less visible an object is.

You can specify the fog's density and start and end points by using the IDirect3DRMFrame::SetSceneFogParams method. In the formulas for the exponential fog modes, e is the base of the natural logarithms; its value is approximately 2.71828.

See Also

 IDirect3DRMFrame::SetSceneFogMode, IDirect3DRMFrame::SetSceneFogParams


D3DRMFRAMECONSTRAINT

Describes the axes of rotation to constrain when viewing a Direct3DRMFrame object. The IDirect3DRMFrame::LookAt method uses this enumerated type.

typedef enum _D3DRMFRAMECONSTRAINT {

    D3DRMCONSTRAIN_Z,

    D3DRMCONSTRAIN_Y,

    D3DRMCONSTRAIN_X

} D3DRMFRAMECONSTRAINT;

Values

D3DRMCONSTRAIN_Z

Use only x and y rotations.

D3DRMCONSTRAIN_Y

Use only x and z rotations.

D3DRMCONSTRAIN_X

Use only y and z rotations.

See Also

 IDirect3DRMFrame::LookAt


D3DRMLIGHTMODE

One of the enumerated types that is used in the definition of the D3DRMRENDERQUALITY type.

typedef enum _D3DRMLIGHTMODE {

    D3DRMLIGHT_OFF      = 0 * D3DRMSHADE_MAX,

    D3DRMLIGHT_ON       = 1 * D3DRMSHADE_MAX,

    D3DRMLIGHT_MASK     = 7 * D3DRMSHADE_MAX,

    D3DRMLIGHT_MAX      = 8 * D3DRMSHADE_MAX

} D3DRMLIGHTMODE;

Values

D3DRMLIGHT_OFF

Lighting is off.

D3DRMLIGHT_ON

Lighting is on.

D3DRMLIGHT_MASK

Lighting uses a mask.

D3DRMLIGHT_MAX

Maximum lighting mode.

See Also

 D3DRMFILLMODE, D3DRMSHADEMODE, D3DRMRENDERQUALITY


D3DRMLIGHTTYPE

Defines the light type in calls to the IDirect3DRM::CreateLight method.

typedef enum _D3DRMLIGHTTYPE{

    D3DRMLIGHT_AMBIENT,

    D3DRMLIGHT_POINT,

    D3DRMLIGHT_SPOT,

    D3DRMLIGHT_DIRECTIONAL,

    D3DRMLIGHT_PARALLELPOINT

} D3DRMLIGHTTYPE;

Values

D3DRMLIGHT_AMBIENT

Light is ambient.

D3DRMLIGHT_POINT

Light is a point source.

D3DRMLIGHT_SPOT

Light is a spotlight source.

D3DRMLIGHT_DIRECTIONAL

Light is a directional source.

D3DRMLIGHT_PARALLELPOINT

Light is a parallel source.


D3DRMMATERIALMODE

Describes the type retrieved by the IDirect3DRMFrame::GetMaterialMode method and set by the IDirect3DRMFrame::SetMaterialMode method.

typedef enum _D3DRMMATERIALMODE{

    D3DRMMATERIAL_FROMMESH,

    D3DRMMATERIAL_FROMPARENT,

    D3DRMMATERIAL_FROMFRAME

} D3DRMMATERIALMODE;

Values

D3DRMMATERIAL_FROMMESH

Material information is retrieved from the visual object (the mesh) itself. This is the default setting.

D3DRMMATERIAL_FROMPARENT

Material information, along with color or texture information, is inherited from the parent frame.

D3DRMMATERIAL_FROMFRAME

Material information is retrieved from the frame, overriding any previous material information that the visual object may have possessed.

See Also

 IDirect3DRMFrame::GetMaterialMode, IDirect3DRMFrame::SetMaterialMode


D3DRMPALETTEFLAGS

Used to define how a color may be used in the D3DRMPALETTEENTRY structure.

typedef enum _D3DRMPALETTEFLAGS {

    D3DRMPALETTE_FREE,

    D3DRMPALETTE_READONLY,

    D3DRMPALETTE_RESERVED

} D3DRMPALETTEFLAGS;

Values

D3DRMPALETTE_FREE

Renderer may use this entry freely.

D3DRMPALETTE_READONLY

Fixed but may be used by renderer.

D3DRMPALETTE_RESERVED

May not be used by renderer.

See Also

 D3DRMPALETTEENTRY


D3DRMPROJECTIONTYPE

Defines the type of projection used in a Direct3DRMViewport object. The IDirect3DRMViewport::GetProjection and IDirect3DRMViewport::SetProjection methods use this enumerated type.

typedef enum _D3DRMPROJECTIONTYPE{

    D3DRMPROJECT_PERSPECTIVE,

    D3DRMPROJECT_ORTHOGRAPHIC

} D3DRMPROJECTIONTYPE;

Values

D3DRMPROJECT_PERSPECTIVE

The projection is perspective.

D3DRMPROJECT_ORTHOGRAPHIC

The projection is orthographic.

See Also

 IDirect3DRMViewport::GetProjection, IDirect3DRMViewport::SetProjection


D3DRMRENDERQUALITY

Combines descriptions of the shading mode, lighting mode, and filling mode for a Direct3DRMMesh object.

typedef enum _D3DRMSHADEMODE {

    D3DRMSHADE_FLAT        = 0,

    D3DRMSHADE_GOURAUD     = 1,

    D3DRMSHADE_PHONG       = 2,

    D3DRMSHADE_MASK        = 7,

    D3DRMSHADE_MAX         = 8

} D3DRMSHADEMODE;

typedef enum _D3DRMLIGHTMODE {

    D3DRMLIGHT_OFF          = 0 * D3DRMSHADE_MAX,

    D3DRMLIGHT_ON           = 1 * D3DRMSHADE_MAX,

    D3DRMLIGHT_MASK         = 7 * D3DRMSHADE_MAX,

    D3DRMLIGHT_MAX          = 8 * D3DRMSHADE_MAX

} D3DRMLIGHTMODE;

typedef enum _D3DRMFILLMODE {

    D3DRMFILL_POINTS        = 0 * D3DRMLIGHT_MAX,

    D3DRMFILL_WIREFRAME     = 1 * D3DRMLIGHT_MAX,

    D3DRMFILL_SOLID         = 2 * D3DRMLIGHT_MAX,

    D3DRMFILL_MASK          = 7 * D3DRMLIGHT_MAX,

    D3DRMFILL_MAX           = 8 * D3DRMLIGHT_MAX

} D3DRMFILLMODE;

typedef DWORD D3DRMRENDERQUALITY;

#define D3DRMRENDER_WIREFRAME   (D3DRMSHADE_FLAT+D3DRMLIGHT_OFF+D3DRMFILL_WIREFRAME)

#define D3DRMRENDER_UNLITFLAT   (D3DRMSHADE_FLAT+D3DRMLIGHT_OFF+D3DRMFILL_SOLID)

#define D3DRMRENDER_FLAT        (D3DRMSHADE_FLAT+D3DRMLIGHT_ON+D3DRMFILL_SOLID)

#define D3DRMRENDER_GOURAUD     (D3DRMSHADE_GOURAUD+D3DRMLIGHT_ON+D3DRMFILL_SOLID)

#define D3DRMRENDER_PHONG       (D3DRMSHADE_PHONG+D3DRMLIGHT_ON+D3DRMFILL_SOLID)

Values

D3DRMSHADEMODE, D3DRMLIGHTMODE, and D3DRMFILLMODE

These enumerated types describe the shade, light, and fill modes for Direct3DRMMesh objects.

D3DRMRENDER_WIREFRAME

Display only the edges.

D3DRMRENDER_UNLITFLAT

Flat shaded without lighting.

D3DRMRENDER_FLAT

Flat shaded.

D3DRMRENDER_GOURAUD

Gouraud shaded.

D3DRMRENDER_PHONG

Phong shaded. Phong shading is not supported for DirectX 2.

See Also

 IDirect3DRMMesh::GetGroupQuality, IDirect3DRMMesh::SetGroupQuality


D3DRMSHADEMODE

One of the enumerated types that is used in the definition of the D3DRMRENDERQUALITY type.

typedef enum _D3DRMSHADEMODE {

    D3DRMSHADE_FLAT     = 0,

    D3DRMSHADE_GOURAUD  = 1,

    D3DRMSHADE_PHONG    = 2,

    D3DRMSHADE_MASK     = 7,

    D3DRMSHADE_MAX      = 8

} D3DRMSHADEMODE;

See Also

 D3DRMFILLMODE, D3DRMLIGHTMODE, D3DRMRENDERQUALITY


D3DRMSORTMODE

Describes how child frames are sorted in a scene.

typedef enum _D3DRMSORTMODE {

    D3DRMSORT_FROMPARENT,

    D3DRMSORT_NONE,

    D3DRMSORT_FRONTTOBACK,

    D3DRMSORT_BACKTOFRONT

} D3DRMSORTMODE;

Values

D3DRMSORT_FROMPARENT

Child frames inherit the sorting order of their parents. This is the default setting.

D3DRMSORT_NONE

Child frames are not sorted.

D3DRMSORT_FRONTTOBACK

Child frames are sorted front-to-back.

D3DRMSORT_BACKTOFRONT

Child frames are sorted back-to-front.

See Also

 IDirect3DRMFrame::GetSortMode, IDirect3DRMFrame::SetSortMode


D3DRMTEXTUREQUALITY

Describes the texture quality for the IDirect3DRMDevice::SetTextureQuality and IDirect3DRMDevice::GetTextureQuality methods.

typedef enum _D3DRMTEXTUREQUALITY{

    D3DRMTEXTURE_NEAREST,

    D3DRMTEXTURE_LINEAR,

    D3DRMTEXTURE_MIPNEAREST,

    D3DRMTEXTURE_MIPLINEAR,

    D3DRMTEXTURE_LINEARMIPNEAREST,

    D3DRMTEXTURE_LINEARMIPLINEAR

} D3DRMTEXTUREQUALITY;

Values

D3DRMTEXTURE_NEAREST

Choose the nearest pixel in the texture.

D3DRMTEXTURE_LINEAR

Linearly interpolate the four nearest pixels.

D3DRMTEXTURE_MIPNEAREST

Similar to D3DRMTEXTURE_NEAREST, but uses the appropriate mipmap instead of the texture.

D3DRMTEXTURE_MIPLINEAR

Similar to D3DRMTEXTURE_LINEAR, but uses the appropriate mipmap instead of the texture.

D3DRMTEXTURE_LINEARMIPNEAREST

Similar to D3DRMTEXTURE_MIPNEAREST, but interpolates between the two nearest mipmaps.

D3DRMTEXTURE_LINEARMIPLINEAR

Similar to D3DRMTEXTURE_MIPLINEAR, but interpolates between the two nearest mipmaps.


D3DRMUSERVISUALREASON

Defines the reason the system has called the D3DRMUSERVISUALCALLBACK callback function.

typedef enum _D3DRMUSERVISUALREASON {

    D3DRMUSERVISUAL_CANSEE,

    D3DRMUSERVISUAL_RENDER

} D3DRMUSERVISUALREASON;

Values

D3DRMUSERVISUAL_CANSEE

The callback function should return TRUE if the user-visual object is visible in the viewport.

D3DRMUSERVISUAL_RENDER

The callback function should render the user-visual object.

See Also

 D3DRMUSERVISUALCALLBACK


D3DRMWRAPTYPE

Defines the type of Direct3DRMWrap object created by the IDirect3DRM::CreateWrap method. You can also use this enumerated type to initialize a Direct3DRMWrap object in a call to the IDirect3DRMWrap::Init method.

typedef enum _D3DRMWRAPTYPE{

    D3DRMWRAP_FLAT,

    D3DRMWRAP_CYLINDER,

    D3DRMWRAP_SPHERE,

    D3DRMWRAP_CHROME

} D3DRMWRAPTYPE;

Values

D3DRMWRAP_FLAT

The wrap is flat.

D3DRMWRAP_CYLINDER

The wrap is cylindrical.

D3DRMWRAP_SPHERE

The wrap is spherical.

D3DRMWRAP_CHROME

The wrap allocates texture coordinates so that the texture appears to be reflected onto the objects.

See Also

 IDirect3DRM::CreateWrap, IDirect3DRMWrap::Init, Wrapping Types


D3DRMXOFFORMAT

Defines the file type used by the IDirect3DRMMeshBuilder::Save method.

typedef enum _D3DRMXOFFORMAT{

    D3DRMXOF_BINARY,

    D3DRMXOF_COMPRESSED,

    D3DRMXOF_TEXT

} D3DRMXOFFORMAT;

Values

D3DRMXOF_BINARY

Not currently supported.

D3DRMXOF_COMPRESSED

Not currently supported.

D3DRMXOF_TEXT

File is in text format. This is the only file type that is currently supported.

See Also

 IDirect3DRMMeshBuilder::Save


D3DRMZBUFFERMODE

Describes whether z-buffering is enabled.

typedef enum _D3DRMZBUFFERMODE {

    D3DRMZBUFFER_FROMPARENT,

    D3DRMZBUFFER_ENABLE,

    D3DRMZBUFFER_DISABLE

} D3DRMZBUFFERMODE;

Values

D3DRMZBUFFER_FROMPARENT

The frame inherits the z-buffer setting from its parent frame. This is the default setting.

D3DRMZBUFFER_ENABLE

Z-buffering is enabled.

D3DRMZBUFFER_DISABLE

Z-buffering is disabled.

See Also

 IDirect3DRMFrame::GetZbufferMode, IDirect3DRMFrame::SetZbufferMode


Other Types


D3DRMANIMATIONOPTIONS

Specifies values used by the IDirect3DRMAnimation::GetOptions and IDirect3DRMAnimation::SetOptions methods to define how animations are played.

typedef DWORD D3DRMANIMATIONOPTIONS;

#define D3DRMANIMATION_CLOSED             0x02L

#define D3DRMANIMATION_LINEARPOSITION     0x04L

#define D3DRMANIMATION_OPEN               0x01L

#define D3DRMANIMATION_POSITION           0x00000020L

#define D3DRMANIMATION_SCALEANDROTATION   0x00000010L

#define D3DRMANIMATION_SPLINEPOSITION     0x08L

Parameters

D3DRMANIMATION_CLOSED

The animation plays continually, looping back to the beginning whenever it reaches the end.

D3DRMANIMATION_LINEARPOSITION

The animation's position is set linearly.

D3DRMANIMATION_OPEN

The animation plays once and stops.

D3DRMANIMATION_POSITION

The animation's position matrix should overwrite any transformation matrices that could be set by other methods.

D3DRMANIMATION_SCALEANDROTATION

The animation's scale and rotation matrix should overwrite any transformation matrices that could be set by other methods.

D3DRMANIMATION_SPLINEPOSITION

The animation's position is set using splines.


D3DRMCOLORMODEL

Describes the color model implemented by the device. For more information, see the D3DCOLORMODEL enumerated type.

typedef D3DCOLORMODEL D3DRMCOLORMODEL;

See Also

 D3DCOLORMODEL


D3DRMLOADOPTIONS

Defines options for the IDirect3DRM::Load, IDirect3DRMAnimationSet::Load, IDirect3DRMFrame::Load, and IDirect3DRMMeshBuilder::Load methods. These options modify how the object is loaded.

typedef DWORD D3DRMLOADOPTIONS;

#define D3DRMLOAD_FROMFILE             0x00L

#define D3DRMLOAD_FROMRESOURCE         0x01L

#define D3DRMLOAD_FROMMEMORY           0x02L

#define D3DRMLOAD_FROMSTREAM           0x03L

#define D3DRMLOAD_BYNAME               0x10L

#define D3DRMLOAD_BYPOSITION           0x20L

#define D3DRMLOAD_BYGUID               0x30L

#define D3DRMLOAD_FIRST                0x40L

#define D3DRMLOAD_INSTANCEBYREFERENCE  0x100L

#define D3DRMLOAD_INSTANCEBYCOPYING    0x200L

Parameters

Source flags

D3DRMLOAD_FROMFILE

Load from a file. This is the default setting.

D3DRMLOAD_FROMRESOURCE

Load from a resource. If this flag is specified, the lpvObjSource parameter of the calling Load method must point to a D3DRMLOADRESOURCE structure.

D3DRMLOAD_FROMMEMORY

Load from memory. If this flag is specified, the lpvObjSource parameter of the calling Load method must point to a D3DRMLOADMEMORY structure.

D3DRMLOAD_FROMSTREAM

Load from a stream.

Identifier flags

D3DRMLOAD_BYNAME

Load using a specified name.

D3DRMLOAD_BYPOSITION

Load using a specified zero-based position (that is, the nth object in the file).

D3DRMLOAD_BYGUID

Load using a specified globally unique identifier (GUID).

D3DRMLOAD_FIRST

Load the first top-level object of the given type (for example, a mesh if the application calls IDirect3DRMMeshBuilder::Load). This is the default setting.

Instance flags

D3DRMLOAD_INSTANCEBYREFERENCE

Check whether an object already exists with the same name as specified and, if so, use an instance of that object instead of creating a new one.

D3DRMLOAD_INSTANCEBYCOPYING

Check whether an object already exists with the same name as specified and, if so, copy that object.

Remarks

Each of the Load methods uses an lpvObjSource parameter to specify the source of the object and an lpvObjID parameter to identify the object. The system interprets the contents of the lpvObjSource parameter based on the choice of source flags, and it interprets the contents of the lpvObjID parameter based on the choice of identifier flags.

The instance flags do not change the interpretation of any of the parameters. By using the D3DRMLOAD_INSTANCEBYREFERENCE flag, it is possible for an application to load the same file twice without creating any new objects. If an object does not have a name, setting the D3DRMLOAD_INSTANCEBYREFERENCE flag has the same effect as setting the D3DRMLOAD_INSTANCEBYCOPYING flag; the loader creates each unnamed object as a new one, even if some of the objects are identical.


D3DRMMAPPING

Specifies values used by the IDirect3DRMMesh::GetGroupMapping and IDirect3DRMMesh::SetGroupMapping methods to define how textures are mapped to a group.

typedef DWORD D3DRMMAPPING, D3DRMMAPPINGFLAG;

static const D3DRMMAPPINGFLAG D3DRMMAP_WRAPU = 1;

static const D3DRMMAPPINGFLAG D3DRMMAP_WRAPV = 2;

static const D3DRMMAPPINGFLAG D3DRMMAP_PERSPCORRECT = 4;

Parameters

D3DRMMAPPINGFLAG

Type equivalent to D3DRMMAPPING.

D3DRMMAP_WRAPU

Texture wraps in the u direction.

D3DRMMAP_WRAPV

Texture wraps in the v direction.

D3DRMMAP_PERSPCORRECT

Texture wrapping is perspective-corrected.

Remarks

The D3DRMMAP_WRAPU and D3DRMMAP_WRAPV flags determine how the rasterizer interprets texture coordinates. The rasterizer always interpolates the shortest distance between texture coordinates; that is, a line. The path taken by this line, and the valid values for the u- and v-coordinates, varies with the use of the wrapping flags. If either or both flags is set, the line can wrap around the texture edge in the u or v direction, as if the texture had a cylindrical or toroidal topology. For more information, see Direct3DRMWrap.

See Also

 Direct3DRMWrap, IDirect3DRMMesh::GetGroupMapping, IDirect3DRMMesh::SetGroupMapping


D3DRMMATRIX4D

Expresses a transformation as an array. The organization of the matrix entries is D3DRMMATRIX4D[row][column].

typedef D3DVALUE D3DRMMATRIX4D[4][4];

See Also

 IDirect3DRMFrame::AddTransform, IDirect3DRMFrame::GetTransform


D3DRMSAVEOPTIONS

Defines options for the IDirect3DRMMeshBuilder::Save method.

typedef DWORD D3DRMSAVEOPTIONS;

#define D3DRMXOFSAVE_NORMALS 1

#define D3DRMXOFSAVE_TEXTURECOORDINATES 2

#define D3DRMXOFSAVE_MATERIALS 4

#define D3DRMXOFSAVE_TEXTURENAMES 8

#define D3DRMXOFSAVE_ALL 15

Parameters

D3DRMXOFSAVE_NORMALS

Save normal vectors in addition to the basic geometry.

D3DRMXOFSAVE_TEXTURECOORDINATES

Save texture coordinates in addition to the basic geometry.

D3DRMXOFSAVE_MATERIALS

Save materials in addition to the basic geometry.

D3DRMXOFSAVE_TEXTURENAMES

Save texture names in addition to the basic geometry.

D3DRMXOFSAVE_ALL

Save normal vectors, texture coordinates, materials, and texture names in addition to the basic geometry.


Return Values

The methods of the Direct3D Retained-Mode Component Object Model (COM) interfaces can return the following values.

D3DRM_OK

	No error.
D3DRMERR_BADALLOC

	Out of memory.
D3DRMERR_BADDEVICE

	Device is not compatible with renderer.
D3DRMERR_BADFILE

	Data file is corrupt.
D3DRMERR_BADMAJORVERSION

	Bad DLL major version.
D3DRMERR_BADMINORVERSION

	Bad DLL minor version.
D3DRMERR_BADOBJECT

	Object expected in argument.
D3DRMERR_BADTYPE

	Bad argument type passed.
D3DRMERR_BADVALUE

	Bad argument value passed.
D3DRMERR_FACEUSED

	Face already used in a mesh.
D3DRMERR_FILENOTFOUND

	File cannot be opened.
D3DRMERR_NOTDONEYET

	Unimplemented.
D3DRMERR_NOTFOUND

	Object not found in specified place.
D3DRMERR_UNABLETOEXECUTE

	Unable to carry out procedure.


Immediate-Mode Reference


Macros


D3DDivide

Divides two values.

D3DDivide(
a,
b
)(
float
)((
double
)(
a
) / (
double
)(
b
))

Parameters

a and b

Dividend and divisor in the expression, respectively.

Return Values

Returns the quotient of the division.

See Also

 D3DMultiply


D3DMultiply

Multiplies two values.

D3DMultiply(
a,
b
)((
a
) * (
b
))

Parameters

a and b

Values to be multiplied.

Return Values

Returns the product of the multiplication.

See Also

 D3DDivide


D3DRGB

Initializes a color with the supplied RGB values.

D3DRGB(
r,
g,
b
) \
(
0xff000000L | (((
long
)((
r
) * 255
)) << 16
) | \
(((
long
)((
g
) * 255
)) << 8
) | (
long
)((
b
) * 255
))

Parameters

r, g, and b

Red, green, and blue components of the color. These should be floating-point values in the range 0 through 1.

Return Values

Returns the D3DCOLOR value corresponding to the supplied RGB values.

See Also

 D3DRGBA


D3DRGBA

Initializes a color with the supplied RGBA values.

D3DRGBA(
r,
g,
b,
a
) \
((((
long
)((
a
) * 255
)) << 24
) | (((
long
)((
r
) * 255
)) << 16
) |
(((
long
)((
g
) * 255
)) << 8
) | (
long
)((
b
) * 255
))

Parameters

r, g, b, and a

Red, green, blue, and alpha components of the color.

Return Values

Returns the D3DCOLOR value corresponding to the supplied RGBA values.

See Also

 D3DRGB


D3DSTATE_OVERRIDE

Overrides the state of the rasterization, lighting, or transformation module. Applications can use this macro to lock and unlock a state.

D3DSTATE_OVERRIDE(
type
)((
DWORD
)(
type
) + D3DSTATE_OVERRIDE_BIAS
)

Parameters

type

State to override. This parameter should be one of the members of the D3DTRANSFORMSTATETYPE, D3DLIGHTSTATETYPE, or D3DRENDERSTATETYPE enumerated types.

Return Values

No return value.

Remarks

An application might, for example, use the STATE_DATA macro (defined in the D3dmacs.h header file in the Misc directory of the DirectX 2 SDK sample code) and D3DSTATE_OVERRIDE to lock and unlock the D3DRENDERSTATE_SHADEMODE render state:

//  Lock the shade mode.

STATE_DATA(D3DSTATE_OVERRIDE(D3DRENDERSTATE_SHADEMODE), TRUE, lpBuffer);

//  Work with the shade mode and unlock it when read-only status is not required.

STATE_DATA(D3DSTATE_OVERRIDE(D3DRENDERSTATE_SHADEMODE), FALSE, lpBuffer);

For more information about overriding rendering states, see States and State Overrides.


D3DVAL

Creates a value whose type is D3DVALUE.

D3DVAL(
val
)((
float
)val
)

Parameters

val

Value to be converted.

Return Values

Returns the converted value.

See Also

 D3DVALP


D3DVALP

Creates a value of the specified precision.

D3DVALP(
val,
prec
)((
float
)val
)

Parameters

val

Value to be converted.

prec

Ignored.

Return Values

Returns the converted value.

Remarks

The precision, as implemented by the D3DVAL macro, is 16 bits for the fractional part of the value.

See Also

 D3DVAL


RGB_GETBLUE

Retrieves the blue component of a D3DCOLOR value.

RGB_GETBLUE(
rgb
)((
rgb
) & 0xff
)

Parameters

rgb

Color index from which the blue component is retrieved.

Return Values

Returns the blue component.


RGB_GETGREEN

Retrieves the green component of a D3DCOLOR value.

RGB_GETGREEN(
rgb
)(((
rgb
) >> 8
) & 0xff
)

Parameters

rgb

Color index from which the green component is retrieved.

Return Values

Returns the green component.


RGB_GETRED

Retrieves the red component of a D3DCOLOR value.

RGB_GETRED(
rgb
)(((
rgb
) >> 16
) & 0xff
)

Parameters

rgb

Color index from which the red component is retrieved.

Return Values

Returns the red component.


RGB_MAKE

Creates an RGB color from supplied values.

RGB_MAKE(
r,
g,
b
)((
D3DCOLOR
)(((
r
) << 16
) | ((
g
) << 8
) | (
b
)))

Parameters

r, g, and b

Red, green, and blue components of the color to be created. These should be integer values in the range zero through 255.

Return Values

Returns the color.


RGB_TORGBA

Creates an RGBA color from a supplied RGB color.

RGB_TORGBA(
rgb
)((
D3DCOLOR
)((
rgb
) | 0xff000000
))

Parameters

rgb

RGB color to be converted to an RGBA color.

Return Values

Returns the RGBA color.

See Also

 RGBA_TORGB


RGBA_GETALPHA

Retrieves the alpha component of an RGBA D3DCOLOR value.

RGBA_GETALPHA(
rgb
)((
rgb
) >> 24
)

Parameters

rgb

Color index from which the alpha component is retrieved.

Return Values

Returns the alpha component.


RGBA_GETBLUE

Retrieves the blue component of an RGBA D3DCOLOR value.

RGB_GETBLUE(
rgb
)((
rgb
) & 0xff
)

Parameters

rgb

Color index from which the blue component is retrieved.

Return Values

Returns the blue component.


RGBA_GETGREEN

Retrieves the green component of an RGBA D3DCOLOR value.

RGB_GETGREEN(
rgb
)(((
rgb
) >> 8
) & 0xff
)

Parameters

rgb

Color index from which the green component is retrieved.

Return Values

Returns the green component.


RGBA_GETRED

Retrieves the red component of an RGBA D3DCOLOR value.

RGB_GETRED(
rgb
)(((
rgb
) >> 16
) & 0xff
)

Parameters

rgb

Color index from which the red component is retrieved.

Return Values

Returns the red component.


RGBA_MAKE

Creates an RGBA D3DCOLOR value from supplied red, green, blue, and alpha components.

RGBA_MAKE(
r,
g,
b,
a
) \
((
D3DCOLOR
)(((
a
) << 24
) | ((
r
) << 16
) | ((
g
) << 8
) | (
b
)))

Parameters

r, g, b, and a

Red, green, blue, and alpha components of the RGBA color to be created.

Return Values

Returns the color.


RGBA_SETALPHA

Sets the alpha component of an RGBA D3DCOLOR value.

RGBA_SETALPHA(
rgba,
x
)(((
x
) << 24
) | ((
rgba
) & 0x00ffffff
))

Parameters

rgba

RGBA color for which the alpha component will be set.

x

Value of alpha component to be set.

Return Values

Returns the RGBA color whose alpha component has been set.


RGBA_TORGB

Creates an RGB D3DCOLOR value from a supplied RGBA D3DCOLOR value by stripping off the alpha component of the color.

RGBA_TORGB(
rgba
)((
D3DCOLOR
)((
rgba
) & 0xffffff
))

Parameters

rgba

RGBA color to be converted to an RGB color.

Return Values

Returns the RGB color.

See Also

 RGB_TORGBA


Callback Functions


D3DENUMDEVICESCALLBACK

Prototype definition for the callback function to enumerate installed Direct3D devices.

typedef HRESULT (FAR PASCAL * LPD3DENUMDEVICESCALLBACK)

    (LPGUID lpGuid, LPSTR lpDeviceDescription,

    LPSTR lpDeviceName, LPD3DDEVICEDESC lpD3DHWDeviceDesc,

    LPD3DDEVICEDESC lpD3DHELDeviceDesc, LPVOID lpUserArg);

Parameters

lpGuid

Address of a globally unique identifier (GUID).

lpDeviceDescription

Address of a textual description of the device.

lpDeviceName

Address of the device name.

lpD3DHWDeviceDesc

Address containing the hardware capabilities of the Direct3D device.

lpD3DHELDeviceDesc

Address containing the emulated capabilities of the Direct3D device.

lpUserArg

Address of application-defined data passed to this callback function.

Return Values

Applications should return one of the following values:

D3DENUMRET_CANCEL

	Cancel the enumeration.
D3DENUMRET_OK

	Continue the enumeration.
Remarks

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.


D3DENUMTEXTUREFORMATSCALLBACK

Prototype definition for the callback function to enumerate texture formats.

typedef HRESULT (WINAPI* LPD3DENUMTEXTUREFORMATSCALLBACK)

    (LPDDSURFACEDESC lpDdsd, LPVOID lpUserArg);

Parameters

lpDdsd

Address of the DirectDrawSurface object containing the texture information.

lpUserArg

Address of application-defined data passed to this callback function.

Remarks

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.


D3DVALIDATECALLBACK

Application-defined callback function supplied when an application calls the IDirect3DExecuteBuffer::Validate method. This method is a debugging routine that checks the execute buffer and returns an offset into the buffer when any errors are encountered.

typedef HRESULT (WINAPI* LPD3DVALIDATECALLBACK)

    (LPVOID lpUserArg, DWORD dwOffset);

Parameters

lpUserArg

Address of application-defined data passed to this callback function.

dwOffset

Offset into the execute buffer at which the system found an error.

Remarks

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.


IDirect3D Interface


IDirect3D Interface Method Groups

Applications use the methods of the IDirect3D interface to create Direct3D objects and set up the environment. The methods can be organized into the following groups:

Creation	CreateLight
	CreateMaterial
	CreateViewport
Enumeration	EnumDevices
and initialization	FindDevice
	Initialize
IUnknown	AddRef
	QueryInterface
	Release
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3D object without affecting the functionality of the original interface.


IDirect3D::AddRef

Increases the reference count of the Direct3D object by 1. This method is part of the IUnknown interface inherited by Direct3D.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3D object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3D::Release method to decrease the reference count of the object by 1.


IDirect3D::CreateLight

Allocates a Direct3DLight object. This object can then be associated with a viewport by using the IDirect3DViewport::AddLight method.

HRESULT CreateLight(
LPDIRECT3DLIGHT* lplpDirect3Dlight,
IUnknown* pUnkOuter
);

Parameters

lplpDirect3DLight

Address that will be filled with a pointer to an IDirect3DLight interface if the call succeeds.

pUnkOuter

This parameter is provided for future compatibility with COM aggregation features. Currently, however, the IDirect3D::CreateLight method returns an error if this parameter is anything but NULL.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


IDirect3D::CreateMaterial

Allocates a Direct3DMaterial object.

HRESULT CreateMaterial(
LPDIRECT3DMATERIAL* lplpDirect3DMaterial,
IUnknown* pUnkOuter
);

Parameters

lplpDirect3DMaterial

Address that will be filled with a pointer to an IDirect3DMaterial interface if the call succeeds.

pUnkOuter

This parameter is provided for future compatibility with COM aggregation features. Currently, however, the IDirect3D::CreateMaterial method returns an error if this parameter is anything but NULL.

Return Values

Returns D3D_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Immediate-Mode Return Values.


IDirect3D::CreateViewport

Creates a Direct3DViewport object. The viewport is associated with a Direct3DDevice object by using the IDirect3DDevice::AddViewport method.

HRESULT CreateViewport(
LPDIRECT3DVIEWPORT* lplpD3DViewport,
IUnknown* pUnkOuter
);

Parameters

lplpD3DViewport

Address that will be filled with a pointer to an IDirect3DViewport interface if the call succeeds.

pUnkOuter

This parameter is provided for future compatibility with COM aggregation features. Currently, however, the IDirect3D::CreateViewport method returns an error if this parameter is anything but NULL.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


IDirect3D::EnumDevices

Enumerates all Direct3D device drivers installed on the system.

HRESULT EnumDevices(
LPD3DENUMDEVICESCALLBACK lpEnumDevicesCallback,
LPVOID lpUserArg
);

Parameters

lpEnumDevicesCallback

Address of the D3DENUMDEVICESCALLBACK callback function that the enumeration procedure will call every time a match is found.

lpUserArg

Address of application-defined data passed to the callback function.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


IDirect3D::FindDevice

Finds a device with specified characteristics and retrieves a description of it.

HRESULT FindDevice(
LPD3DFINDDEVICESEARCH lpD3DFDS,
LPD3DFINDDEVICERESULT lpD3DFDR
);

Parameters

lpD3DFDS

Address of the D3DFINDDEVICESEARCH structure describing the device to be located.

lpD3DFDR

Address of the D3DFINDDEVICERESULT structure describing the device if it is found.

Return Values

Returns D3D_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Immediate-Mode Return Values.


IDirect3D::Initialize

This method is provided for compliance with the COM protocol.

HRESULT Initialize(
REFIID lpREFIID
);

Parameters

lpREFIID

Address of a universally unique identifier (UUID).

Return Values

Returns DDERR_ALREADYINITIALIZED because the Direct3D object is initialized when it is created.


IDirect3D::QueryInterface

Determines if the Direct3D object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3D.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3D::QueryInterface method allows Direct3D objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3D::Release

Decreases the reference count of the Direct3D object by 1. This method is part of the IUnknown interface inherited by Direct3D.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3D object deallocates itself when its reference count reaches 0. Use the IDirect3D::AddRef method to increase the reference count of the object by 1.


IDirect3DDevice Interface


IDirect3DDevice Interface Method Groups

Applications use the methods of the IDirect3DDevice interface to retrieve and set the capabilities of Direct3D devices. The methods can be organized into the following groups:

Execution	CreateExecuteBuffer
	Execute
Information	EnumTextureFormats
	GetCaps
	GetDirect3D
	GetPickRecords
	GetStats
IUnknown	AddRef
	QueryInterface
	Release
Matrices	CreateMatrix
	DeleteMatrix
	GetMatrix
	SetMatrix
Miscellaneous	Initialize
	Pick
	SwapTextureHandles
Scenes	BeginScene
	EndScene
Viewports	AddViewport
	DeleteViewport
	NextViewport
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DDevice object without affecting the functionality of the original interface.

The Direct3DDevice object is obtained through the appropriate call to the IDirect3DDevice::QueryInterface method from a DirectDrawSurface object that was created as a 3D-capable surface.


IDirect3DDevice::AddRef

Increases the reference count of the Direct3DDevice object by 1. This method is part of the IUnknown interface inherited by Direct3DDevice.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DDevice object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DDevice::Release method to decrease the reference count of the object by 1.


IDirect3DDevice::AddViewport

Adds the specified viewport to the list of viewport objects associated with the device.

HRESULT AddViewport(
LPDIRECT3DVIEWPORT lpDirect3DViewport
);

Parameters

lpDirect3DViewport

Address of the IDirect3DViewport interface that should be associated with this Direct3DDevice object.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


IDirect3DDevice::BeginScene

Begins a scene.

HRESULT BeginScene( );

Return Values

Returns D3D_OK if successful or an error otherwise.

Remarks

Applications must call this method before performing any rendering, and must call IDirect3DDevice::EndScene when rendering is complete.

See Also

 IDirect3DDevice::EndScene


IDirect3DDevice::CreateExecuteBuffer

Allocates an execute buffer for a display list. The list may be read by hardware DMA into VRAM for processing. All display primitives in the buffer that have indices to vertices must also have those vertices in the same buffer.

HRESULT CreateExecuteBuffer(
LPDIRECT3DEXECUTEBUFFERDESC lpDesc,
LPDIRECT3DEXECUTEBUFFER* lplpDirect3DExecuteBuffer,
IUnknown* pUnkOuter
);

Parameters

lpDesc

Address of a D3DEXECUTEBUFFERDESC structure that describes the Direct3DExecuteBuffer object to be created. The call will fail if a buffer of at least the specified size cannot be created.

lplpDirect3DExecuteBuffer

Address of a pointer that will be filled with the address of the new Direct3DExecuteBuffer object.

pUnkOuter

This parameter is provided for future compatibility with COM aggregation features. Currently, however, this method returns an error if this parameter is anything but NULL.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks

The D3DEXECUTEBUFFERDESC structure describes the execute buffer to be created. At a minimum, the application must specify the size required. If the application specifies DEBCAPS_VIDEO_MEMORY in the capabilities member, Direct3D will attempt to keep the execute buffer in video memory.

The application can use the IDirect3DExecuteBuffer::Lock method to request that the memory be moved. When this method returns, it will adjust the contents of the D3DEXECUTEBUFFERDESC structure to indicate whether the data resides in system or video memory.


IDirect3DDevice::CreateMatrix

Creates a matrix.

HRESULT CreateMatrix(
LPD3DMATRIXHANDLE lpD3DMatHandle
);

Parameters

lpD3DMatHandle

Address of a variable that will contain a handle to the matrix that is created. The call will fail if a buffer of at least the size of the matrix cannot be created.

Return Values

Returns D3D_OK if successful, or an error otherwise, such as DDERR_INVALIDPARAMS.

See Also

 IDirect3DDevice::DeleteMatrix, IDirect3DDevice::SetMatrix


IDirect3DDevice::DeleteMatrix

Deletes a matrix handle. This matrix handle must have been created by using the IDirect3DDevice::CreateMatrix method.

HRESULT DeleteMatrix(
D3DMATRIXHANDLE d3dMatHandle
);

Parameters

d3dMatHandle

Matrix handle to be deleted.

Return Values

Returns D3D_OK if successful, or an error otherwise, such as DDERR_INVALIDPARAMS.

See Also

 IDirect3DDevice::CreateMatrix, IDirect3DDevice::SetMatrix


IDirect3DDevice::DeleteViewport

Removes the specified viewport from the list of viewport objects associated with the device.

HRESULT DeleteViewport(
LPDIRECT3DVIEWPORT lpDirect3DViewport
);

Parameters

lpDirect3DViewport

Address of the Direct3DViewport object that should be disassociated with this Direct3DDevice object.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


IDirect3DDevice::EndScene

Ends a scene that was begun by calling the IDirect3DDevice::BeginScene method.

HRESULT EndScene( );

Return Values

Returns D3D_OK if successful, or an error otherwise.

See Also

 IDirect3DDevice::BeginScene


IDirect3DDevice::EnumTextureFormats

Queries the current driver for a list of supported texture formats.

HRESULT EnumTextureFormats(
LPD3DENUMTEXTUREFORMATSCALLBACK lpd3dEnumTextureProc,
LPVOID lpArg
);

Parameters

lpd3dEnumTextureProc

Address of the D3DENUMTEXTUREFORMATSCALLBACK callback function that the enumeration procedure will call for each texture format.

lpArg

Address of application-defined data passed to the callback function.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks


IDirect3DDevice::Execute

Executes a buffer.

HRESULT Execute(
LPDIRECT3DEXECUTEBUFFER lpDirect3DExecuteBuffer,
LPDIRECT3DVIEWPORT lpDirect3DViewport,
DWORD dwFlags
);

Parameters

lpDirect3DExecuteBuffer

Address of the execute buffer to be executed.

lpDirect3DViewport

Address of the Direct3DViewport object that describes the transformation context into which the execute buffer will be rendered.

dwFlags

Flags specifying whether or not objects in the buffer should be clipped. This parameter must be one of the following values:

D3DEXECUTE_CLIPPED

	Clip any primitives in the buffer that are outside or partially outside the viewport.
D3DEXECUTE_UNCLIPPED

	All primitives in the buffer are contained within the viewport.
Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
See Also

 D3DEXECUTEDATA, D3DINSTRUCTION, IDirect3DExecuteBuffer::Validate


IDirect3DDevice::GetCaps

Retrieves the capabilities of the Direct3DDevice object.

HRESULT GetCaps(
LPD3DDEVICEDESC lpD3DHWDevDesc,
LPD3DDEVICEDESC lpD3DHELDevDesc
);

Parameters

lpD3DHWDevDesc

Address of the D3DDEVICEDESC structure that will contain the hardware features of the device.

lpD3DHELDevDesc

Address of the D3DDEVICEDESC structure that will contain the software emulation being provided.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks

This method does not retrieve the capabilities of the display device. To retrieve this information, use the IDirectDraw::GetCaps method.


IDirect3DDevice::GetDirect3D

Retrieves the current IDirect3D interface.

HRESULT GetDirect3D(
LPDIRECT3D* lpD3D
);

Parameters

lpD3D

Address that will contain the interface when the method returns.

Return Values

Returns D3D_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Immediate-Mode Return Values.


IDirect3DDevice::GetMatrix

Retrieves a matrix from a matrix handle. This matrix handle must have been created by using the IDirect3DDevice::CreateMatrix method.

HRESULT GetMatrix(
D3DMATRIXHANDLE lpD3DMatHandle,
LPD3DMATRIX lpD3DMatrix
);

Parameters

lpD3DMatHandle

Address of a variable that contains the matrix to be retrieved.

lpD3DMatrix

Address of a D3DMATRIX structure that contains the matrix when the method returns.

Return Values

Returns D3D_OK if successful, or an error otherwise, such as DDERR_INVALIDPARAMS.

See Also

 IDirect3DDevice::CreateMatrix, IDirect3DDevice::DeleteMatrix, IDirect3DDevice::SetMatrix


IDirect3DDevice::GetPickRecords

Retrieves the pick records for a device.

HRESULT GetPickRecords(
LPDWORD lpCount,
LPD3DPICKRECORD lpD3DPickRec
);

Parameters

lpCount

Address of a variable that contains the number of D3DPICKRECORD structures to retrieve.

lpD3DPickRec

Address that will contain an array of D3DPICKRECORD structures when the method returns.

Return Values

Returns D3D_OK if successful or an error otherwise.

Remarks

An application typically calls this method twice. In the first call, the second parameter is set to NULL, and the first parameter retrieves a count of all relevant D3DPICKRECORD structures. The application then allocates sufficient memory for those structures and calls the method again, specifying the newly allocated memory for the second parameter.


IDirect3DDevice::GetStats

Retrieves statistics about a device.

HRESULT GetStats(
LPD3DSTATS lpD3DStats
);

Parameters

lpD3DStats

Address of a D3DSTATS structure that will be filled with the statistics.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


IDirect3DDevice::Initialize

Initializes a device.

HRESULT Initialize(
LPDIRECT3D lpd3d,
LPGUID lpGUID,
LPD3DDEVICEDESC lpd3ddvdesc
);

Parameters

lpd3d

Address of the Direct3D device to use as an initializer.

lpGUID

Address of the globally unique identifier (GUID) used as the interface identifier.

lpd3ddvdesc

Address of a D3DDEVICEDESC structure describing the Direct3DDevice object to be initialized.

Return Values

Returns D3D_OK if successful, or an error otherwise. For a list of possible return values, see Direct3D Immediate-Mode Return Values.


IDirect3DDevice::NextViewport

Enumerates the viewports associated with the device.

HRESULT NextViewport(
LPDIRECT3DVIEWPORT lpDirect3DViewport,
LPDIRECT3DVIEWPORT* lplpDirect3DViewport,
DWORD dwFlags
);

Parameters

lpDirect3DViewport

Address of a viewport in the list of viewports associated with this Direct3DDevice object.

lplpDirect3DViewport

Address of the next viewport in the list of viewports associated with this Direct3DDevice object.

dwFlags

Flags specifying which viewport to retrieve from the list of viewports. The default setting is D3DNEXT_NEXT.

D3DNEXT_HEAD	Retrieve the item at the beginning of the list.
D3DNEXT_NEXT	Retrieve the next item in the list.
D3DNEXT_TAIL	Retrieve the item at the end of the list.
Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


IDirect3DDevice::Pick

Executes a buffer without performing any rendering, but returns a z-ordered list of offsets to the primitives that cover the rectangle specified by lpRect.

This call fails if the Direct3DExecuteBuffer object is locked.

HRESULT Pick(
LPDIRECT3DEXECUTEBUFFER lpDirect3DExecuteBuffer,
LPDIRECT3DVIEWPORT lpDirect3DViewport,
DWORD dwFlags,
LPD3DRECT lpRect
);

Parameters

lpDirect3DExecuteBuffer

Address of an execute buffer from which the z-ordered list is retrieved.

lpDirect3DViewport

Address of a viewport in the list of viewports associated with this Direct3DDevice object.

dwFlags

No flags are currently defined for this method.

lpRect

Address of a D3DRECT structure specifying the range of device coordinates to be picked.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

D3DERR_EXECUTE_LOCKED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks

If the x1 and x2 members of the structure specified in the lpRect parameter are equal, and the y1 and y2 members are equal, a single pixel is used for picking. The coordinates are specified in device-pixel space.

All Direct3DExecuteBuffer objects must be attached to a Direct3DDevice object in order for this method to succeed.

See Also

 IDirect3DDevice::GetPickRecords


IDirect3DDevice::QueryInterface

Determines if the Direct3DDevice object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DDevice.

HRESULT QueryInterface(
REFIID riid,
LPVOID* obp
);

Parameters

riid

Reference identifier of the interface being requested.

obp

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DDevice::QueryInterface method allows Direct3DDevice objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DDevice::Release

Decreases the reference count of the Direct3DDevice object by 1. This method is part of the IUnknown interface inherited by Direct3DDevice.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DDevice object deallocates itself when its reference count reaches 0. Use the IDirect3DDevice::AddRef method to increase the reference count of the object by 1.


IDirect3DDevice::SetMatrix

Applies a matrix to a matrix handle. This matrix handle must have been created by using the IDirect3DDevice::CreateMatrix method.

HRESULT SetMatrix(
D3DMATRIXHANDLE d3dMatHandle,
LPD3DMATRIX lpD3DMatrix
);

Parameters

d3dMatHandle

Matrix handle to be set.

lpD3DMatrix

Address of a D3DMATRIX structure that describes the matrix to be set.

Return Values

Returns D3D_OK if successful, or an error otherwise, such as DDERR_INVALIDPARAMS.

Remarks

Transformations inside the execute buffer include a handle of a matrix. The IDirect3DDevice::SetMatrix method enables an application to change this matrix without having to lock and unlock the execute buffer.

See Also

 IDirect3DDevice::CreateMatrix, IDirect3DDevice::GetMatrix, IDirect3DDevice::DeleteMatrix


IDirect3DDevice::SwapTextureHandles

Swaps two texture handles.

HRESULT SwapTextureHandles(
LPDIRECT3DTEXTURE lpD3DTex1,
LPDIRECT3DTEXTURE lpD3DTex2
);

Parameters

lpD3DTex1 and lpD3DTex2

Addresses of the textures whose handles will be swapped when the method returns.

Return Values

Returns D3D_OK if successful or an error otherwise.

Remarks

This method is useful when an application is changing all the textures in a complicated object.


IDirect3DExecuteBuffer Interface


IDirect3DExecuteBuffer Interface Method Groups

Your application uses the methods of the IDirect3DExecuteBuffer interface to set up and control a Direct3D execute buffer. The methods can be organized into the following groups:

Execute data	GetExecuteData
	SetExecuteData
IUnknown	AddRef
	QueryInterface
	Release
Lock and unlock	Lock
	Unlock
Miscellaneous	Initialize
	Optimize
	Validate
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DExecuteBuffer object without affecting the functionality of the original interface.


IDirect3DExecuteBuffer::AddRef

Increases the reference count of the Direct3DExecuteBuffer object by 1. This method is part of the IUnknown interface inherited by Direct3DExecuteBuffer.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DExecuteBuffer object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DExecuteBuffer::Release method to decrease the reference count of the object by 1.


IDirect3DExecuteBuffer::GetExecuteData

Retrieves the execute data state of the Direct3DExecuteBuffer object. The execute data is used to describe the contents of the Direct3DExecuteBuffer object.

HRESULT GetExecuteData(
LPD3DEXECUTEDATA lpData
);

Parameters

lpData

Address of a D3DEXECUTEDATA structure that will be filled with the current execute data state of the Direct3DExecuteBuffer object.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

D3DERR_EXECUTE_LOCKED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks

This call fails if the Direct3DExecuteBuffer object is locked.

See Also

 IDirect3DExecuteBuffer::SetExecuteData


IDirect3DExecuteBuffer::Initialize

This method is provided for compliance with the COM protocol.

HRESULT Initialize(
LPDIRECT3DDEVICE lpDirect3DDevice,
LPD3DEXECUTEBUFFERDESC lpDesc
);

Parameters

lpDirect3DDevice

Address of the device representing the Direct3D object.

lpDesc

Address of a D3DEXECUTEBUFFERDESC structure that describes the Direct3DExecuteBuffer object to be created. The call fails if a buffer of at least the specified size cannot be created.

Return Values

Returns DDERR_ALREADYINITIALIZED because the Direct3DExecuteBuffer object is initialized when it is created.


IDirect3DExecuteBuffer::Lock

Obtains a direct pointer to the commands in the execute buffer.

HRESULT Lock(
LPD3DEXECUTEBUFFERDESC lpDesc
);

Parameters

lpDesc

Address of a D3DEXECUTEBUFFERDESC structure. When the method returns, the lpData member will be set to point to the actual data the application has access to. This data may reside in system or video memory, and is specified by the dwCaps member. The application may use the IDirect3DExecuteBuffer::Lock method to request that Direct3D move the data between system or video memory.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

D3DERR_EXECUTE_LOCKED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING
Remarks

This call fails if the Direct3DExecuteBuffer object is locked—that is, if another thread is accessing the buffer, or if a IDirect3DDevice::Execute method that was issued on this buffer has not yet completed.

See Also

 IDirect3DExecuteBuffer::Unlock


IDirect3DExecuteBuffer::Optimize

Not currently supported.

HRESULT Optimize( );


IDirect3DExecuteBuffer::QueryInterface

Determines if the Direct3DExecuteBuffer object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DExecuteBuffer.

HRESULT QueryInterface(
REFIID riid,
LPVOID* ppvObj
);

Parameters

riid

Reference identifier of the interface being requested.

ppvObj

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DExecuteBuffer::QueryInterface method allows Direct3DExecuteBuffer objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.

This call fails if the Direct3DExecuteBuffer object is locked.


IDirect3DExecuteBuffer::Release

Decreases the reference count of the Direct3DExecuteBuffer object by 1. This method is part of the IUnknown interface inherited by Direct3DExecuteBuffer.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DExecuteBuffer object deallocates itself when its reference count reaches 0. Use the IDirect3DExecuteBuffer::AddRef method to increase the reference count of the object by 1.

This call fails if the Direct3DExecuteBuffer object is locked.


IDirect3DExecuteBuffer::SetExecuteData

Sets the execute data state of the Direct3DExecuteBuffer object. The execute data is used to describe the contents of the Direct3DExecuteBuffer object.

HRESULT SetExecuteData(
LPD3DEXECUTEDATA lpData
);

Parameters

lpData

Address of a D3DEXECUTEDATA structure that describes the execute buffer layout.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

D3DERR_EXECUTE_LOCKED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks

This call fails if the Direct3DExecuteBuffer object is locked.

See Also

 IDirect3DExecuteBuffer::GetExecuteData


IDirect3DExecuteBuffer::Unlock

Releases the direct pointer to the commands in the execute buffer. This must be done prior to calling the IDirect3DDevice::Execute method for the buffer.

HRESULT Unlock( );

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

D3DERR_EXECUTE_NOT_LOCKED
DDERR_INVALIDOBJECT
See Also

 IDirect3DExecuteBuffer::Lock


IDirect3DExecuteBuffer::Validate

Checks an execute buffer and returns an offset into the buffer when any errors are encountered. This method is a debugging routine.

HRESULT Validate(
LPDWORD lpdwOffset,
LPD3DVALIDATECALLBACK lpFunc,
LPVOID lpUserArg,
DWORD dwReserved
);

Parameters

lpdwOffset

Address of a variable that will be filled with the offset into the execute buffer at which an error was first detected. This parameter is filled in only if NULL is specified for the lpFunc parameter. If a callback function is specified for lpFunc, the offset for each error is passed to the callback function, and the lpdwOffset parameter is not set.

lpFunc

Address of an application-defined D3DVALIDATECALLBACK callback function. If this parameter is NULL, checking stops when the first error is detected.

lpUserArg

Address of application-defined data passed to the callback function.

dwReserved

Reserved for future use.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks

The callback function specified in the lpFunc parameter is called whenever an error is detected in the execute buffer. The system passes to this callback function the value specified in lpUserArg and the offset into the execute buffer where the error was detected.

This call fails if the Direct3DExecuteBuffer object is locked.


IDirect3DLight Interface


IDirect3DLight Interface Method Groups

Applications use the methods of the IDirect3DLight interface to retrieve and set the capabilities of lights. The methods can be organized into the following groups:

Get and set	GetLight
	SetLight
Initialization	Initialize
IUnknown	AddRef
	QueryInterface
	Release
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DLight object without affecting the functionality of the original interface.


IDirect3DLight::AddRef

Increases the reference count of the Direct3DLight object by 1. This method is part of the IUnknown interface inherited by Direct3DLight.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DLight object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DLight::Release method to decrease the reference count of the object by 1.


IDirect3DLight::GetLight

Retrieves the light information for the Direct3DLight object.

HRESULT GetLight(
LPD3DLIGHT lpLight
);

Parameters

lpLight

Address of a D3DLIGHT structure that will be filled with the current light data.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
See Also

 IDirect3DLight::SetLight


IDirect3DLight::Initialize

This method is provided for compliance with the COM protocol.

HRESULT Initialize(
LPDIRECT3D lpDirect3D
);

Parameters

lpDirect3D

Address of the Direct3D structure representing the Direct3D object.

Return Values

Returns DDERR_ALREADYINITIALIZED because the Direct3DLight object is initialized when it is created.


IDirect3DLight::QueryInterface

Determines if the Direct3DLight object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DLight.

HRESULT QueryInterface(
REFIID riid,
LPVOID* ppvObj
);

Parameters

riid

Reference identifier of the interface being requested.

ppvObj

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DLight::QueryInterface method allows Direct3DLight objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DLight::Release

Decreases the reference count of the Direct3DLight object by 1. This method is part of the IUnknown interface inherited by Direct3DLight.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DLight object deallocates itself when its reference count reaches 0. Use the IDirect3DLight::AddRef method to increase the reference count of the object by 1.


IDirect3DLight::SetLight

Sets the light information for the Direct3DLight object.

HRESULT SetLight(
LPD3DLIGHT lpLight
);

Parameters

lpLight

Address of a D3DLIGHT structure that will be used to set the current light data.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
See Also

 IDirect3DLight::GetLight


IDirect3DMaterial Interface


IDirect3DMaterial Interface Method Groups

Applications use the methods of the IDirect3DMaterial interface to retrieve and set the properties of materials. The methods can be organized into the following groups:

Color reservation	Reserve
	Unreserve
IUnknown	AddRef
	QueryInterface
	Release
Materials	GetMaterial
	SetMaterial
Miscellaneous	GetHandle
	Initialize
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DMaterial object without affecting the functionality of the original interface.


IDirect3DMaterial::AddRef

Increases the reference count of the Direct3DMaterial object by 1. This method is part of the IUnknown interface inherited by Direct3DMaterial.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DMaterial object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DMaterial::Release method to decrease the reference count of the object by 1.


IDirect3DMaterial::GetHandle

Obtains the material handle for the Direct3DMaterial object. This handle is used in all Direct3D API calls where a material is to be referenced. A material can be used by only one device at a time.

If the device is destroyed, the material is disassociated from the device.

HRESULT GetHandle(
LPDIRECT3DDEVICE lpDirect3DDevice,
LPD3DMATERIALHANDLE lpHandle
);

Parameters

lpDirect3DDevice

Address of the Direct3DDevice object in which the material is being used.

lpHandle

Address of a variable that will be filled with the material handle corresponding to the Direct3DMaterial object.

Return Values

Returns D3D_OK if successful, or DDERR_INVALIDOBJECT otherwise.


IDirect3DMaterial::GetMaterial

Retrieves the material data for the Direct3DMaterial object.

HRESULT GetMaterial(
LPD3DMATERIAL lpMat
);

Parameters

lpMat

Address of a D3DMATERIAL structure that will be filled with the current material properties.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
See Also

 IDirect3DMaterial::SetMaterial


IDirect3DMaterial::Initialize

This method is provided for compliance with the COM protocol.

HRESULT Initialize(
LPDIRECT3D lpDirect3D
);

Parameters

lpDirect3D

Address of the Direct3D structure representing the Direct3D object.

Return Values

Returns DDERR_ALREADYINITIALIZED because the Direct3DMaterial object is initialized when it is created.


IDirect3DMaterial::QueryInterface

Determines if the Direct3DMaterial object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DMaterial.

HRESULT QueryInterface(
REFIID riid,
LPVOID* ppvObj
);

Parameters

riid

Reference identifier of the interface being requested.

ppvObj

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DMaterial::QueryInterface method allows Direct3DMaterial objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DMaterial::Release

Decreases the reference count of the Direct3DMaterial object by 1. This method is part of the IUnknown interface inherited by Direct3DMaterial.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DMaterial object deallocates itself when its reference count reaches 0. Use the IDirect3DMaterial::AddRef method to increase the reference count of the object by 1.


IDirect3DMaterial::Reserve

Not currently implemented.

HRESULT Reserve( );


IDirect3DMaterial::SetMaterial

Sets the material data for the Direct3DMaterial object.

HRESULT SetMaterial(
LPD3DMATERIAL lpMat
);

Parameters

lpMat

Address of a D3DMATERIAL structure that contains the material properties.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
See Also

 IDirect3DMaterial::GetMaterial


IDirect3DMaterial::Unreserve

Not currently implemented.

HRESULT Unreserve( );


IDirect3DTexture Interface


IDirect3DTexture Interface Method Groups

Applications use the methods of the IDirect3DTexture interface to retrieve and set the properties of textures. The methods can be organized into the following groups:

Handles	GetHandle
Initialization	Initialize
IUnknown	AddRef
	QueryInterface
	Release
Loading	Load
	Unload
Palette information	PaletteChanged
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DTexture object without affecting the functionality of the original interface.

The Direct3DTexture object is obtained through the appropriate call to the IDirect3D::QueryInterface method from a DirectDrawSurface object that was created as a texture map.


IDirect3DTexture::AddRef

Increases the reference count of the Direct3DTexture object by 1. This method is part of the IUnknown interface inherited by Direct3DTexture.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DTexture object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DTexture::Release method to decrease the reference count of the object by 1.


IDirect3DTexture::GetHandle

Obtains the texture handle for the Direct3DTexture object. This handle is used in all Direct3D API calls where a texture is to be referenced.

HRESULT GetHandle(
LPDIRECT3DDEVICE lpDirect3DDevice,
LPD3DTEXTUREHANDLE lpHandle
);

Parameters

lpDirect3DDevice

Address of the Direct3DDevice object into which the texture is to be loaded.

lpHandle

Address that will contain the texture handle corresponding to the Direct3DTexture object.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

D3DERR_BADOBJECT
DDERR_INVALIDPARAMS


IDirect3DTexture::Initialize

This method is provided for compliance with the COM protocol.

HRESULT Initialize(
LPDIRECT3DDEVICE lpD3DDevice,
LPDIRECTDRAWSURFACE lpDDSurface
);

Parameters

lpD3DDevice

Address of the device representing the Direct3D object.

lpDDSurface

Address of the DirectDraw surface for this object.

Return Values

Returns DDERR_ALREADYINITIALIZED because the Direct3DTexture object is initialized when it is created.


IDirect3DTexture::Load

Loads a texture that was created with the DDSCAPS_ALLOCONLOAD flag, which indicates that memory for the DirectDraw surface is not allocated until the surface is loaded by using this method.

HRESULT Load(
LPDIRECT3DTEXTURE lpD3DTexture
);

Parameters

lpD3DTexture

Address of the texture to load.

Return Values

Returns D3D_OK if successful, or an error otherwise. For a list of possible return values, see Direct3D Immediate-Mode Return Values.

See Also

 IDirect3DTexture::Unload


IDirect3DTexture::PaletteChanged

Informs the driver that the palette has changed on a surface.

HRESULT PaletteChanged(
DWORD dwStart,
DWORD dwCount
);

Parameters

dwStart

Index of first palette entry that has changed.

dwCount

Number of palette entries that have changed.

Return Values

Returns D3D_OK if successful, or an error otherwise. For a list of possible return values, see Direct3D Immediate-Mode Return Values.

Remarks

This method is particularly useful for applications that play video clips and therefore require palette-changing capabilities.


IDirect3DTexture::QueryInterface

Determines if the Direct3DTexture object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DTexture.

HRESULT QueryInterface(
REFIID riid,
LPVOID* ppvObj
);

Parameters

riid

Reference identifier of the interface being requested.

ppvObj

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DTexture::QueryInterface method allows Direct3DTexture objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DTexture::Release

Decreases the reference count of the Direct3DTexture object by 1. This method is part of the IUnknown interface inherited by Direct3DTexture.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DTexture object deallocates itself when its reference count reaches 0. Use the IDirect3DTexture::AddRef method to increase the reference count of the object by 1.


IDirect3DTexture::Unload

Unloads the current texture.

HRESULT Unload( );

Return Values

Returns D3D_OK if successful, or an error otherwise. For a list of possible return values, see Direct3D Immediate-Mode Return Values.

See Also

 IDirect3DTexture::Load


IDirect3DViewport Interface


IDirect3DViewport Interface Method Groups

Applications use the methods of the IDirect3DViewport interface to retrieve and set the properties of viewports. The methods can be organized into the following groups:

Backgrounds	GetBackground
	GetBackgroundDepth
	SetBackground
	SetBackgroundDepth
Initialization	Initialize
IUnknown	AddRef
	QueryInterface
	Release
Lights	AddLight
	DeleteLight
	LightElements
	NextLight
Materials and viewports	Clear
	GetViewport
	SetViewport
Transformation	TransformVertices
All COM interfaces inherit the IUnknown interface methods, which are listed in the "IUnknown" group above. These three methods allow additional interfaces to be added to the Direct3DViewport object without affecting the functionality of the original interface.


IDirect3DViewport::AddLight

Adds the specified light to the list of Direct3DLight objects associated with this viewport.

HRESULT AddLight(
LPDIRECT3DLIGHT lpDirect3DLight
);

Parameters

lpDirect3DLight

Address of the Direct3DLight object that should be associated with this Direct3DDevice object.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


IDirect3DViewport::AddRef

Increases the reference count of the Direct3DViewport object by 1. This method is part of the IUnknown interface inherited by Direct3DViewport.

ULONG AddRef( );

Return Values

Returns the new reference count of the object.

Remarks

When the Direct3DViewport object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the IDirect3DViewport::Release method to decrease the reference count of the object by 1.


IDirect3DViewport::Clear

Clears the viewport or a set of rectangles in the viewport to the current background material.

HRESULT Clear(
DWORD dwCount,
LPD3DRECT lpRects,
DWORD dwFlags
);

Parameters

dwCount

Number of rectangles pointed to by lpRects.

lpRects

Address of an array of D3DRECT structures.

dwFlags

Flags indicating what to clear: the rendering target, the z-buffer, or both.

D3DCLEAR_TARGET	Clear the rendering target to the background material (if set).
D3DCLEAR_ZBUFFER	Clear the z-buffer or set it to the current background depth field (if set).
Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


IDirect3DViewport::DeleteLight

Removes the specified light from the list of Direct3DLight objects associated with this viewport.

HRESULT DeleteLight(
LPDIRECT3DLIGHT lpDirect3DLight
);

Parameters

lpDirect3DLight

Address of the Direct3DLight object that should be disassociated with this Direct3DDevice object.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


IDirect3DViewport::GetBackground

Retrieves the handle of a material that represents the current background associated with the viewport.

HRESULT GetBackground(
LPD3DMATERIALHANDLE lphMat,
LPBOOL lpValid
);

Parameters

lphMat

Address that will contain the handle of the material being used as the background.

lpValid

Address of a variable that will be filled to indicate whether a background is associated with the viewport. If this parameter is FALSE, no background is associated with the viewport.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
See Also

 IDirect3DViewport::SetBackground


IDirect3DViewport::GetBackgroundDepth

Retrieves a DirectDraw surface that represents the current background-depth field associated with the viewport.

HRESULT GetBackgroundDepth(
LPDIRECTDRAWSURFACE* lplpDDSurface,
LPBOOL lpValid
);

Parameters

lplpDDSurface

Address that will be initialized to point to a DirectDrawSurface object representing the background depth.

lpValid

Address of a variable that is set to FALSE if no background depth is associated with the viewport.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
See Also

 IDirect3DViewport::SetBackgroundDepth


IDirect3DViewport::GetViewport

Retrieves the viewport registers of the viewport.

HRESULT GetViewport(
LPD3DVIEWPORT lpData
);

Parameters

lpData

Address of a D3DVIEWPORT structure representing the viewport.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
See Also

 IDirect3DViewport::SetViewport


IDirect3DViewport::Initialize

This method is provided for compliance with the COM protocol.

HRESULT Initialize(
LPDIRECT3D lpDirect3D
);

Parameters

lpDirect3D

Address of the Direct3D structure representing the Direct3D object.

Return Values

Returns DDERR_ALREADYINITIALIZED because the Direct3DViewport object is initialized when it is created.


IDirect3DViewport::LightElements

Calculates light intensities and colors for rendering a geometry.

HRESULT LightElements(
DWORD dwElementCount,
LPD3DLIGHTDATA lpData
);

Parameters

dwElementCount

Number of elements to be lit.

lpData

Address of a D3DLIGHTDATA structure that contains the points to be lit and the resulting colors.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


IDirect3DViewport::NextLight

Enumerates the Direct3DLight objects associated with the viewport.

HRESULT NextLight(
LPDIRECT3DLIGHT lpDirect3DLight,
LPDIRECT3DLIGHT* lplpDirect3DLight,
DWORD dwFlags
);

Parameters

lpDirect3DLight

Address of a light in the list of lights associated with this Direct3DDevice object.

lplpDirect3DLight

Address of a pointer that will contain the requested light in the list of lights associated with this Direct3DDevice object. The requested light is specified in the dwFlags parameter.

dwFlags

Flags specifying which light to retrieve from the list of lights. The default setting is D3DNEXT_NEXT.

D3DNEXT_HEAD	Retrieve the item at the beginning of the list.
D3DNEXT_NEXT	Retrieve the next item in the list.
D3DNEXT_TAIL	Retrieve the item at the end of the list.
Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


IDirect3DViewport::QueryInterface

Determines if the Direct3DViewport object supports a particular COM interface. If it does, the system increases the reference count for the object, and the application can begin using that interface immediately. This method is part of the IUnknown interface inherited by Direct3DViewport.

HRESULT QueryInterface(
REFIID riid,
LPVOID* ppvObj
);

Parameters

riid

Reference identifier of the interface being requested.

ppvObj

Address of a pointer that will be filled with the interface pointer if the query is successful.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks

If the application does not need to use the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The IDirect3DViewport::QueryInterface method allows Direct3DViewport objects to be extended by Microsoft and third parties without interfering with each other's existing or future functionality.


IDirect3DViewport::Release

Decreases the reference count of the Direct3DViewport object by 1. This method is part of the IUnknown interface inherited by Direct3DViewport.

ULONG Release( );

Return Values

Returns the new reference count of the object.

Remarks

The Direct3DViewport object deallocates itself when its reference count reaches 0. Use the IDirect3DViewport::AddRef method to increase the reference count of the object by 1.


IDirect3DViewport::SetBackground

Sets the background associated with the viewport.

HRESULT SetBackground(
D3DMATERIALHANDLE hMat
);

Parameters

hMat

Material handle that will be used as the background.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
See Also

 IDirect3DViewport::GetBackground


IDirect3DViewport::SetBackgroundDepth

Sets the background-depth field for the viewport.

HRESULT SetBackgroundDepth(
LPDIRECTDRAWSURFACE lpDDSurface
);

Parameters

lpDDSurface

Address of the DirectDrawSurface object representing the background depth.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks

The z-buffer is filled with the specified depth field when the IDirect3DViewport::Clear method is called and the D3DCLEAR_ZBUFFER flag is specified. The bit depth must be 16 bits.

See Also

 IDirect3DViewport::GetBackgroundDepth


IDirect3DViewport::SetViewport

Sets the viewport registers of the viewport.

HRESULT SetViewport(
LPD3DVIEWPORT lpData
);

Parameters

lpData

Address of a D3DVIEWPORT structure that contains the new viewport.

Return Values

Returns D3D_OK if successful, or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
See Also

 IDirect3DViewport::GetViewport


IDirect3DViewport::TransformVertices

Transforms a set of vertices by the transformation matrix.

HRESULT TransformVertices(
DWORD dwVertexCount,
LPD3DTRANSFORMDATA lpData,
DWORD dwFlags,
LPDWORD lpOffscreen
);

Parameters

dwVertexCount

Number of vertices in the lpData parameter to be transformed.

lpData

Address of a D3DTRANSFORMDATA structure that contains the vertices to be transformed.

dwFlags

One of the following flags. See the comments section following the parameter description for a discussion of how to use these flags.

D3DTRANSFORM_CLIPPED
D3DTRANSFORM_UNCLIPPED
lpOffscreen

Address of a variable that is set to a nonzero value if the resulting vertices are all off-screen.

Return Values

Returns D3D_OK if successful or an error otherwise, which may be one of the following values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
Remarks

If the dwFlags parameter is set to D3DTRANSFORM_CLIPPED, this method uses the current transformation matrix to transform a set of vertices, checking the resulting vertices to see if they are within the viewing frustum. The homogeneous part of the D3DTLVERTEX structure within lpData will be set if the vertex is clipped; otherwise only the screen coordinates will be set. The clip intersection of all the vertices transformed is returned in lpOffscreen. That is, if lpOffscreen is nonzero, all the vertices were off-screen and not straddling the viewport. The drExtent member of the D3DTRANSFORMDATA structure will also be set to the 2D bounding rectangle of the resulting vertices.

If the dwFlags parameter is set to D3DTRANSFORM_UNCLIPPED, this method uses the current transformation matrix to transform a set of vertices. In this case, the system assumes that all the resulting coordinates will be within the viewing frustum. The drExtent member of the D3DTRANSFORMDATA structure will be set to the bounding rectangle of the resulting vertices.

The dwClip member of D3DTRANSFORMDATA can help the transformation module determine whether the geometry will need clipping against the viewing volume. Before transforming a geometry, high-level software often can test whether bounding boxes or bounding spheres are wholly within the viewing volume, allowing clipping tests to be skipped, or wholly outside the viewing volume, allowing the geometry to be skipped entirely.


Structures


D3DBRANCH

Performs conditional operations inside an execute buffer. This structure is a forward-branch structure.

typedef struct _D3DBRANCH {

    DWORD dwMask;

    DWORD dwValue;

    BOOL  bNegate;

    DWORD dwOffset;

} D3DBRANCH, *LPD3DBRANCH;

Members

dwMask

Bitmask for the branch. This mask is combined with the driver-status mask by using the logical AND operator. If the result equals the value specified in the dwValue member and the bNegate member is FALSE, the branch is taken.

For a list of the available driver-status masks, see the dwStatus member of the D3DSTATUS structure.

dwValue

Application-defined value to compare against the operation described in the dwMask member.

bNegate

TRUE to negate comparison.

dwOffset

How far to branch forward. Specify zero to exit.


D3DCOLORVALUE

Describes color values for the D3DLIGHT and D3DMATERIAL structures.

typedef struct _D3DCOLORVALUE {

    union {

        D3DVALUE r;

        D3DVALUE dvR;

    };

    union {

        D3DVALUE g;

        D3DVALUE dvG;

    };

    union {

        D3DVALUE b;

        D3DVALUE dvB;

    };

    union {

        D3DVALUE a;

        D3DVALUE dvA;

    };

} D3DCOLORVALUE;

Members

dvR, #dvG, #dvB, and #dvA

Values of the D3DVALUE type specifying the red, green, blue, and alpha components of a color.


D3DDEVICEDESC

Contains a description of the current device. This structure is used to query the current device by such methods as IDirect3DDevice::GetCaps.

typedef struct _D3DDeviceDesc {

    DWORD            dwSize;

    DWORD            dwFlags;

    D3DCOLORMODEL    dcmColorModel;

    DWORD            dwDevCaps;

    D3DTRANSFORMCAPS dtcTransformCaps;

    BOOL             bClipping;

    D3DLIGHTINGCAPS  dlcLightingCaps;

    D3DPRIMCAPS      dpcLineCaps;

    D3DPRIMCAPS      dpcTriCaps;

    DWORD            dwDeviceRenderBitDepth;

    DWORD            dwDeviceZBufferBitDepth;

    DWORD            dwMaxBufferSize;

    DWORD            dwMaxVertexCount;

} D3DDEVICEDESC, *LPD3DDEVICEDESC;

Members

dwSize

Size, in bytes, of this structure.

dwFlags

Flags identifying the members of this structure that contain valid data.

D3DDD_BCLIPPING

	The bClipping member is valid.
D3DDD_COLORMODEL

	The dcmColorModel member is valid.
D3DDD_DEVCAPS

	The dwDevCaps member is valid.
D3DDD_LIGHTINGCAPS

	The dlcLightingCaps member is valid.
D3DDD_LINECAPS

	The dpcLineCaps member is valid.
D3DDD_MAXBUFFERSIZE

	The dwMaxBufferSize member is valid.
D3DDD_MAXVERTEXCOUNT

	The dwMaxVertexCount member is valid.
D3DDD_TRANSFORMCAPS

	The dtcTransformCaps member is valid.
D3DDD_TRICAPS

	The dpcTriCaps member is valid.
dcmColorModel

One of the members of the D3DCOLORMODEL enumerated type, specifying the color model for the device.

dwDevCaps

Flags identifying the capabilities of the device.

D3DDEVCAPS_EXECUTESYSTEMMEMORY

	Device can use execute buffers from system memory.
D3DDEVCAPS_EXECUTEVIDEOMEMORY

	Device can use execute buffers from video memory.
D3DDEVCAPS_FLOATTLVERTEX

	Device accepts floating point for post-transform vertex data.
D3DDEVCAPS_SORTDECREASINGZ

	Device needs data sorted for decreasing depth.
D3DDEVCAPS_SORTEXACT

	Device needs data sorted exactly.
D3DDEVCAPS_SORTINCREASINGZ

	Device needs data sorted for increasing depth.
D3DDEVCAPS_TEXTURESYSTEMMEMORY

	Device can retrieve textures from system memory.
D3DDEVCAPS_TEXTUREVIDEOMEMORY

	Device can retrieves textures from device memory.
D3DDEVCAPS_TLVERTEXSYSTEMMEMORY

	Device can use buffers from system memory for transformed and lit vertices.
D3DDEVCAPS_TLVERTEXVIDEOMEMORY

	Device can use buffers from video memory for transformed and lit vertices.
dtcTransformCaps

One of the members of the D3DTRANSFORMCAPS structure, specifying the transformation capabilities of the device.

bClipping

TRUE if the device can perform 3D clipping.

dlcLightingCaps

One of the members of the D3DLIGHTINGCAPS structure, specifying the lighting capabilities of the device.

dpcLineCaps and #dpcTriCaps

D3DPRIMCAPS structures defining the device's support for line-drawing and triangle primitives.

dwDeviceRenderBitDepth

Device's rendering bit-depth. This can be one of the following DirectDraw bit-depth constants: DDBD_8, DDBD_16, DDBD_24, or DDBD_32.

dwDeviceZBufferBitDepth

Device's z-buffer bit-depth. This can be one of the following DirectDraw bit-depth constants: DDBD_8, DDBD_16, DDBD_24, or DDBD_32.

dwMaxBufferSize

Maximum size of the execute buffer for this device. If this member is 0, the application can use any size.

dwMaxVertexCount

Maximum vertex count for this device.

See Also

 D3DCOLORMODEL, D3DFINDDEVICERESULT, D3DLIGHTINGCAPS, D3DPRIMCAPS, D3DTRANSFORMCAPS


D3DEXECUTEBUFFERDESC

Describes the execute buffer for such methods as IDirect3DDevice::CreateExecuteBuffer and IDirect3DExecuteBuffer::Lock.

typedef struct _D3DExecuteBufferDesc {

    DWORD  dwSize;

    DWORD  dwFlags;

    DWORD  dwCaps;

    DWORD  dwBufferSize;

    LPVOID lpData;

} D3DEXECUTEBUFFERDESC;

typedef D3DEXECUTEBUFFERDESC *LPD3DEXECUTEBUFFERDESC;

Members

dwSize

Size of this structure, in bytes.

dwFlags

Flags identifying the members of this structure that contain valid data.

D3DDEB_BUFSIZE	The dwBufferSize member is valid.
D3DDEB_CAPS	The dwCaps member is valid.
D3DDEB_LPDATA	The lpData member is valid.
dwCaps

Location in memory of the execute buffer.

D3DDEBCAPS_SYSTEMMEMORY

	The execute buffer data resides in system memory.
D3DDEBCAPS_VIDEOMEMORY

	The execute buffer data resides in device memory.
D3DDEBCAPS_MEM

	A logical OR of D3DDEBCAPS_SYSTEMMEMORY and D3DDEBCAPS_VIDEOMEMORY.
dwBufferSize

Size of the execute buffer, in bytes.

lpData

Address of the buffer data.


D3DEXECUTEDATA

Specifies data for the IDirect3DDevice::Execute method. When this method is called and the transformation has been done, the instruction list starting at the value specified in the dwInstructionOffset member is parsed and rendered.

typedef struct _D3DEXECUTEDATA {

    DWORD     dwSize;

    DWORD     dwVertexOffset;

    DWORD     dwVertexCount;

    DWORD     dwInstructionOffset;

    DWORD     dwInstructionLength;

    DWORD     dwHVertexOffset;

    D3DSTATUS dsStatus;

} D3DEXECUTEDATA, *LPD3DEXECUTEDATA;

Members

dwSize

Size of this structure, in bytes.

dwVertexOffset

Offset into the list of vertices.

dwVertexCount

Number of vertices to execute.

dwInstructionOffset

Offset into the list of instructions to execute.

dwInstructionLength

Length of the instructions to execute.

dwHVertexOffset

Offset into the list of vertices for the homogeneous vertex used when the application is supplying screen coordinate data that needs clipping.

dsStatus

Value storing the screen extent of the rendered geometry for use after the transformation is complete. This value is a D3DSTATUS structure.

See Also

 D3DSTATUS


D3DFINDDEVICERESULT

Identifies a device an application has found by calling the IDirect3D::FindDevice method.

typedef struct _D3DFINDDEVICERESULT {

    DWORD         dwSize;

    GUID          guid;

    D3DDEVICEDESC ddHwDesc;

    D3DDEVICEDESC ddSwDesc;

} D3DFINDDEVICERESULT, *LPD3DFINDDEVICERESULT;

Members

dwSize

Size, in bytes, of the structure.

guid

Globally unique identifier (GUID) of the device that was found.

ddHwDesc and #ddSwDesc

D3DDEVICEDESC structures describing the hardware and software devices that were found.

See Also

 D3DFINDDEVICESEARCH


D3DFINDDEVICESEARCH

Specifies the characteristics of a device an application wants to find. This structure is used in calls to the IDirect3D::FindDevice method.

typedef struct _D3DFINDDEVICESEARCH {

    DWORD         dwSize;

    DWORD         dwFlags;

    BOOL          bHardware;

    D3DCOLORMODEL dcmColorModel;

    GUID          guid;

    DWORD         dwCaps;

    D3DPRIMCAPS   dpcPrimCaps;

} D3DFINDDEVICESEARCH, *LPD3DFINDDEVICESEARCH;

Members

dwSize

Size, in bytes, of this structure.

dwFlags

Flags defining the type of device the application wants to find. This member can be one or more of the following values:

D3DFDS_ALPHACMPCAPS

	Match the dwAlphaCmpCaps member of the D3DPRIMCAPS structure specified as the dpcPrimCaps member of this structure.
D3DFDS_COLORMODEL

	Match the color model specified in the dcmColorModel member of this structure.
D3DFDS_DSTBLENDCAPS

	Match the dwDestBlendCaps member of the D3DPRIMCAPS structure specified as the dpcPrimCaps member of this structure.
D3DFDS_GUID

	Match the globally unique identifier (GUID) specified in the guid member of this structure.
D3DFDS_HARDWARE

	Match the hardware or software search specification given in the bHardware member of this structure.
D3DFDS_LINES

	Match the D3DPRIMCAPS structure specified by the dpcLineCaps member of the D3DDEVICEDESC structure.
D3DFDS_MISCCAPS

	Match the dwMiscCaps member of the D3DPRIMCAPS structure specified as the dpcPrimCaps member of this structure.
D3DFDS_RASTERCAPS

	Match the dwRasterCaps member of the D3DPRIMCAPS structure specified as the dpcPrimCaps member of this structure.
D3DFDS_SHADECAPS

	Match the dwShadeCaps member of the D3DPRIMCAPS structure specified as the dpcPrimCaps member of this structure.
D3DFDS_SRCBLENDCAPS

	Match the dwSrcBlendCaps member of the D3DPRIMCAPS structure specified as the dpcPrimCaps member of this structure.
D3DFDS_TEXTUREBLENDCAPS

	Match the dwTextureBlendCaps member of the D3DPRIMCAPS structure specified as the dpcPrimCaps member of this structure.
D3DFDS_TEXTURECAPS

	Match the dwTextureCaps member of the D3DPRIMCAPS structure specified as the dpcPrimCaps member of this structure.
D3DFDS_TEXTUREFILTERCAPS

	Match the dwTextureFilterCaps member of the D3DPRIMCAPS structure specified as the dpcPrimCaps member of this structure.
D3DFDS_TRIANGLES

	Match the D3DPRIMCAPS structure specified by the dpcTriCaps member of the D3DDEVICEDESC structure.
D3DFDS_ZCMPCAPS

	Match the dwZCmpCaps member of the D3DPRIMCAPS structure specified as the dpcPrimCaps member of this structure.
bHardware

Flag specifying whether the device to find is implemented as hardware or software. If this member is TRUE, the device to search for has hardware rasterization and may also provide other hardware acceleration. Applications that use this flag should set the D3DFDS_HARDWARE bit in the dwFlags member.

dcmColorModel

One of the members of the D3DCOLORMODEL enumerated type, specifying whether the device to find should use the ramp or RGB color model.

guid

Globally unique identifier (GUID) of the device to find.

dwCaps

Capability flags.

dpcPrimCaps

Specifies a D3DPRIMCAPS structure defining the device's capabilities for each primitive type.

See Also

 D3DFINDDEVICERESULT


D3DHVERTEX

Defines a homogeneous vertex used when the application is supplying screen coordinate data that needs clipping. This structure is part of the D3DTRANSFORMDATA structure.

typedef struct _D3DHVERTEX {

    DWORD        dwFlags;

    union {

        D3DVALUE hx;

        D3DVALUE dvHX;

    };

    union {

        D3DVALUE hy;

        D3DVALUE dvHY;

    };

    union {

        D3DVALUE hz;

        D3DVALUE dvHZ;

    };

} D3DHVERTEX, *LPD3DHVERTEX;

Members

dwFlags

Flags defining the clip status of the homogeneous vertex. This member can be one or more of the flags described in the dwClip member of the D3DTRANSFORMDATA structure.

dvHX, #dvHY, and #dvHZ

Values of the D3DVALUE type describing transformed homogeneous coordinates. These coordinates define the vertex.


D3DINSTRUCTION

Defines an instruction in an execute buffer. A display list is made up from a list of variable length instructions. Each instruction begins with a common instruction header and is followed by the data required for that instruction.

typedef struct _D3DINSTRUCTION {

    BYTE bOpcode;

    BYTE bSize;

    WORD wCount;

} D3DINSTRUCTION, *LPD3DINSTRUCTION;

Members

bOpcode

Rendering operation, specified as a member of the D3DOPCODE enumerated type.

bSize

Size of each instruction data unit. This member can be used to skip to the next instruction in the sequence.

wCount

Number of data units of instructions that follow. This member allows efficient processing of large batches of similar instructions, such as triangles that make up a triangle mesh.


D3DLIGHT

Defines the light type in calls to methods such as IDirect3DLight::SetLight and IDirect3DLight::GetLight.

typedef struct _D3DLIGHT {

    DWORD         dwSize;

    D3DLIGHTTYPE  dltType;

    D3DCOLORVALUE dcvColor;

    D3DVECTOR     dvPosition;

    D3DVECTOR     dvDirection;

    D3DVALUE      dvRange;

    D3DVALUE      dvFalloff;

    D3DVALUE      dvAttenuation0;

    D3DVALUE      dvAttenuation1;

    D3DVALUE      dvAttenuation2;

    D3DVALUE      dvTheta;

    D3DVALUE      dvPhi;

} D3DLIGHT, *LPD3DLIGHT;

Members

dwSize

Size, in bytes, of this structure.

dltType

Type of the light source. This value is one of the members of the D3DLIGHTTYPE enumerated type.

dcvColor

Color of the light. This member is a D3DCOLORVALUE structure.

dvPosition and #dvDirection

Position and direction of the light in world space.

dvRange

Distance beyond which the light has no effect.

dvFalloff

Decrease in illumination between the umbra (the angle specified by the dvTheta member) and the outer edge of the penumbra (the angle specified by the dvPhi member).

dvAttenuation0

Constant light intensity. Specifies a light level that does not decrease between the light and the cutoff point given by the dvRange member.

dvAttenuation1

Light intensity that decreases linearly. The light intensity is 50 percent of this value halfway between the light and the cutoff point given by the dvRange member.

dvAttenuation2

Light intensity that decreases according to a quadratic attenuation factor.

dvTheta

Angle, in radians, of the spotlight's umbra—that is, the fully illuminated spotlight cone.

dvPhi

Angle, in radians, defining the outer edge of the spotlight's penumbra. Points outside this cone are not lit by the spotlight.

Remarks

The system uses all three of the attenuation settings to determine how the effect of a light decreases with distance from the source. The following equation shows how the attentuation settings are interpreted. The value d here is the distance between the vertex being lit and the light:

For more information about lights, see Lighting Module.

See Also

 D3DLIGHTTYPE


D3DLIGHTDATA

Describes the points to be lit and resulting colors in calls to the IDirect3DViewport::LightElements method.

typedef struct _D3DLIGHTDATA {

    DWORD                dwSize;

    LPD3DLIGHTINGELEMENT lpIn;

    DWORD                dwInSize;

    LPD3DTLVERTEX        lpOut;

    DWORD                dwOutSize;

} D3DLIGHTDATA, *LPD3DLIGHTDATA;

Members

dwSize

Size, in bytes, of this structure.

lpIn

Address of a D3DLIGHTINGELEMENT structure specifying the input positions and normal vectors.

dwInSize

Amount to skip from one input element to the next. This allows the application to store extra data inline with the element.

lpOut

Address of a D3DTLVERTEX structure specifying the output colors.

dwOutSize

Amount to skip from one output color to the next. This allows the application to store extra data inline with the color.


D3DLIGHTINGCAPS

Describes the lighting capabilities of a device. This structure is a member of the D3DDEVICEDESC structure.

typedef struct _D3DLIGHTINGCAPS {

    DWORD dwSize;

    DWORD dwCaps;

    DWORD dwLightingModel;

    DWORD dwNumLights;

} D3DLIGHTINGCAPS, *LPD3DLIGHTINGCAPS;

Members

dwSize

Size, in bytes, of this structure.

dwCaps

Flags describing the capabilities of the lighting module. The following flags are defined:

D3DLIGHTCAPS_DIRECTIONAL

	Directional lights are supported.
D3DLIGHTCAPS_GLSPOT

	OpenGL-style spotlights are supported.
D3DLIGHTCAPS_PARALLELPOINT

	Parallel point lights are supported.
D3DLIGHTCAPS_POINT

	Point lights are supported.
D3DLIGHTCAPS_SPOT

	Spotlights are supported.
dwLightingModel

Flags defining whether the lighting model is RGB or monochrome. The following flags are defined:

D3DLIGHTINGMODEL_MONO	Monochromatic lighting model.
D3DLIGHTINGMODEL_RGB	RGB lighting model.
dwNumLights

Number of lights that can be handled.


D3DLIGHTINGELEMENT

Describes the points in model space that will be lit. This structure is part of the D3DLIGHTDATA structure.

typedef struct _D3DLIGHTINGELEMENT {

    D3DVECTOR dvPosition;

    D3DVECTOR dvNormal;

} D3DLIGHTINGELEMENT, *LPD3DLIGHTINGELEMENT;

Members

dvPosition

Value specifying the lightable point in model space. This value is a D3DVECTOR structure.

dvNormal

Value specifying the normalized unit vector. This value is a D3DVECTOR structure.

See Also

 D3DLIGHTDATA, IDirect3DViewport::LightElements


D3DLINE

Describes a line for the D3DOP_LINE opcode in the D3DOPCODE enumerated type.

typedef struct _D3DLINE {

    union {

        WORD v1;

        WORD wV1;

    };

    union {

        WORD v2;

        WORD wV2;

    };

} D3DLINE, *LPD3DLINE;

Members

wV1 and #wV2

Vertex indices.

Remarks

Because lines are rendered by using a list of vertices that are to be joined, one less than the count of lines will be rendered.


D3DLINEPATTERN

Describes a line pattern. These values are used by the D3DRENDERSTATE_LINEPATTERN render state in the D3DRENDERSTATETYPE enumerated type.

typedef struct _D3DLINEPATTERN {

    WORD wRepeatFactor;

    WORD wLinePattern;

} D3DLINEPATTERN;

Members

wRepeatFactor

Number of bits in the pattern specified by the wLinePattern member to use before starting over again at the beginning of the pattern.

wLinePattern

Bits specifying the line pattern. For example, the following value would produce a dotted line: 1100110011001100.


D3DLVERTEX

Defines an untransformed and lit vertex (model coordinates with color). Applications should use this structure if the hardware handles vertex transformations. This structure contains only data and a color that would be filled by software lighting.

typedef struct _D3DLVERTEX {

    union {

        D3DVALUE x;

        D3DVALUE dvX;

    };

    union {

        D3DVALUE y;

        D3DVALUE dvY;

    };

    union {

        D3DVALUE z;

        D3DVALUE dvZ;

    };

    DWORD        dwReserved;

    union {

        D3DCOLOR color;

        D3DCOLOR dcColor;

    };

    union {

        D3DCOLOR specular;

        D3DCOLOR dcSpecular;

    };

    union {

        D3DVALUE tu;

        D3DVALUE dvTU;

    };

    union {

        D3DVALUE tv;

        D3DVALUE dvTV;

    };

} D3DLVERTEX, *LPD3DLVERTEX;

Members

dvX, #dvY, and #dvZ

Values of the D3DVALUE type specifying the homogeneous coordinates of the vertex.

dwReserved

Reserved; must be zero.

dcColor and #dcSpecular

Values of the D3DCOLOR type specifying the color and specular component of the vertex.

dvTU and #dvTV

Values of the D3DVALUE type specifying the texture coordinates of the vertex.


D3DMATERIAL

Specifies material properties in calls to the IDirect3DMaterial::GetMaterial and IDirect3DMaterial::SetMaterial methods.

typedef struct _D3DMATERIAL {

    DWORD             dwSize;

    union {

        D3DCOLORVALUE diffuse;

        D3DCOLORVALUE dcvDiffuse;

    };

    union {

        D3DCOLORVALUE ambient;

        D3DCOLORVALUE dcvAmbient;

    };

    union {

        D3DCOLORVALUE specular;

        D3DCOLORVALUE dcvSpecular;

    };

    union {

        D3DCOLORVALUE emissive;

        D3DCOLORVALUE dcvEmissive;

    };

    union {

        D3DVALUE      power;

        D3DVALUE      dvPower;

    };

    D3DTEXTUREHANDLE  hTexture;

    DWORD             dwRampSize;

} D3DMATERIAL, *LPD3DMATERIAL;

Members

dwSize

Size, in bytes, of this structure.

dcvDiffuse, #dcvAmbient, #dcvSpecular, and #dcvEmissive

Values specifying the diffuse color, ambient color, specular color, and emissive color of the material, respectively. These values are D3DCOLORVALUE structures.

dvPower

Value of the D3DVALUE type specifying the sharpness of specular highlights.

hTexture

Handle of the texture map.

dwRampSize

Size of the color ramp. For the monochromatic (ramp) driver, this value must be less than or equal to 1 for materials assigned to the background; otherwise, the background is not displayed. This behavior also occurs when a texture that is assigned to the background has an associated material whose dwRampSize member is greater than 1.

Remarks

The texture handle is acquired from Direct3D by loading a texture into the device. The texture handle may be used only when it has been loaded into the device.

See Also

 IDirect3DMaterial::GetMaterial, IDirect3DMaterial::SetMaterial


D3DMATRIX

typedef struct _D3DMATRIX {

    D3DVALUE _11, _12, _13, _14;

    D3DVALUE _21, _22, _23, _24;

    D3DVALUE _31, _32, _33, _34;

    D3DVALUE _41, _42, _43, _44;

} D3DMATRIX, *LPD3DMATRIX;

Remarks

Describes a matrix for such methods as IDirect3DDevice::GetMatrix and IDirect3DDevice::SetMatrix.

See Also

 IDirect3DDevice::GetMatrix,IDirect3DDevice::SetMatrix


D3DMATRIXLOAD

Describes the operand data for the D3DOP_MATRIXLOAD opcode in the D3DOPCODE enumerated type.

typedef struct _D3DMATRIXLOAD {

    D3DMATRIXHANDLE hDestMatrix;

    D3DMATRIXHANDLE hSrcMatrix;

} D3DMATRIXLOAD, *LPD3DMATRIXLOAD;

Members

hDestMatrix and #hSrcMatrix

Handles of the destination and source matrices. These values are D3DMATRIX structures.

See Also

 D3DOPCODE


D3DMATRIXMULTIPLY

Describes the operand data for the D3DOP_MATRIXMULTIPLY opcode in the D3DOPCODE enumerated type.

typedef struct _D3DMATRIXMULTIPLY {

    D3DMATRIXHANDLE hDestMatrix;

    D3DMATRIXHANDLE hSrcMatrix1;

    D3DMATRIXHANDLE hSrcMatrix2;

} D3DMATRIXMULTIPLY, *LPD3DMATRIXMULTIPLY;

Members

hDestMatrix

Handle of the matrix that stores the product of the source matrices. This value is a D3DMATRIX structure.

hSrcMatrix1 and #hSrcMatrix2

Handles of the first and second source matrices. These values are D3DMATRIX structures.

See Also

 D3DOPCODE


D3DPICKRECORD

Returns information about picked primitives in an execute buffer for the IDirect3DDevice::GetPickRecords method.

typedef struct _D3DPICKRECORD {

    BYTE     bOpcode;

    BYTE     bPad;

    DWORD    dwOffset;

    D3DVALUE dvZ;

} D3DPICKRECORD, *LPD3DPICKRECORD;

Members

bOpcode

Opcode of the picked primitive.

bPad

Pad byte.

dwOffset

Offset from the start of the execute buffer in which the picked primitive was found.

dvZ

Depth of the picked primitive.

Remarks

The x- and y-coordinates of the picked primitive are specified in the call to the IDirect3DDevice::Pick method that created the pick records.

See Also

 IDirect3DDevice::GetPickRecords, IDirect3DDevice::Pick


D3DPOINT

Describes operand data for the D3DOP_POINT opcode in the in D3DOPCODE enumerated type.

typedef struct _D3DPOINT {

    WORD wCount;

    WORD wFirst;

} D3DPOINT, *LPD3DPOINT;

Members

wCount

Number of points.

wFirst

Index of the first vertex.

Remarks

Points are rendered by using a list of vertices.

See Also

 D3DOPCODE


D3DPRIMCAPS

Defines the capabilities for each primitive type. This structure is used when creating a device and when querying the capabilities of a device. This structure defines several members in the D3DDEVICEDESC structure.

typedef struct _D3DPrimCaps {

    DWORD dwSize;

    DWORD dwMiscCaps;

    DWORD dwRasterCaps;

    DWORD dwZCmpCaps;

    DWORD dwSrcBlendCaps;

    DWORD dwDestBlendCaps;

    DWORD dwAlphaCmpCaps;

    DWORD dwShadeCaps;

    DWORD dwTextureCaps;

    DWORD dwTextureFilterCaps;

    DWORD dwTextureBlendCaps;

    DWORD dwTextureAddressCaps;

    DWORD dwStippleWidth;

    DWORD dwStippleHeight;

} D3DPRIMCAPS, *LPD3DPRIMCAPS;

Members

dwSize

Size, in bytes, of this structure.

dwMiscCaps

General capabilities for this primitive. This member can be one or more of the following:

D3DPMISCCAPS_CONFORMANT

	The device conforms to the OpenGL standard.
D3DPMISCCAPS_CULLCCW

	The driver supports counterclockwise culling through the D3DRENDERSTATE_CULLMODE state. (This applies only to triangle primitives.) This corresponds to the D3DCULL_CCW member of the D3DCULL enumerated type.
D3DPMISCCAPS_CULLCW

	The driver supports clockwise triangle culling through the D3DRENDERSTATE_CULLMODE state. (This applies only to triangle primitives.) This corresponds to the D3DCULL_CW member of the D3DCULL enumerated type.
D3DPMISCCAPS_CULLNONE

	The driver does not perform triangle culling. This corresponds to the D3DCULL_NONE member of the D3DCULL enumerated type.
D3DPMISCCAPS_LINEPATTERNREP

	The driver can handle values other than 1 in the wRepeatFactor member of the D3DLINEPATTERN structure. (This applies only to line-drawing primitives.)
D3DPMISCCAPS_MASKPLANES

	The device can perform a bitmask of color planes.
D3DPMISCCAPS_MASKZ

	The device can enable and disable modification of the z-buffer on pixel operations.
dwRasterCaps

Information on raster-drawing capabilities. This member can be one or more of the following:

D3DPRASTERCAPS_DITHER

	The device can dither to improve color resolution.
D3DPRASTERCAPS_FOGTABLE

	The device calculates the fog value by referring to a lookup table containing fog values that are indexed to the depth of a given pixel.
D3DPRASTERCAPS_FOGVERTEX

	The device calculates the fog value during the lighting operation, places the value into the alpha component of the D3DCOLOR value given for the specular member of the D3DTLVERTEX structure, and interpolates the fog value during rasterization.
D3DPRASTERCAPS_PAT

	The driver can perform patterned drawing (lines or fills with D3DRENDERSTATE_LINEPATTERN or one of the D3DRENDERSTATE_STIPPLEPATTERN render states) for the primitive being queried.
D3DPRASTERCAPS_ROP2

	The device can support raster operations other than R2_COPYPEN.
D3DPRASTERCAPS_STIPPLE

	The device can stipple polygons to simulate translucency.
D3DPRASTERCAPS_SUBPIXEL

	The device performs subpixel placement of z, color, and texture data, rather than working with the nearest integer pixel coordinate. This helps avoid bleed-through due to z imprecision, and jitter of color and texture values for pixels. Note that there is no corresponding state that can be enabled and disabled; the device either performs subpixel placement or it does not, and this bit is present only so that the Direct3D client will be better able to determine what the rendering quality will be.
D3DPRASTERCAPS_SUBPIXELX

	The device is subpixel accurate along the x-axis only and is clamped to an integer y-axis scanline. For information about subpixel accuracy, see D3DPRASTERCAPS_SUBPIXEL.
D3DPRASTERCAPS_XOR

	The device can support XOR operations. If this flag is not set but D3DPRIM_RASTER_ROP2 is set, then XOR operations must still be supported.
D3DPRASTERCAPS_ZTEST

	The device can perform z-test operations. This effectively renders a primitive and indicates whether any z pixels would have been rendered.
dwZCmpCaps

Z-buffer comparison functions that the driver can perform. This member can be one or more of the following:

D3DPCMPCAPS_ALWAYS

	Always pass the z test.
D3DPCMPCAPS_EQUAL

	Pass the z test if the new z equals the current z.
D3DPCMPCAPS_GREATER

	Pass the z test if the new z is greater than the current z.
D3DPCMPCAPS_GREATEREQUAL

	Pass the z test if the new z is greater than or equal to the current z.
D3DPCMPCAPS_LESS

	Pass the z test if the new z is less than the current z.
D3DPCMPCAPS_LESSEQUAL

	Pass the z test if the new z is less than or equal to the current z.
D3DPCMPCAPS_NEVER

	Always fail the z test.
D3DPCMPCAPS_NOTEQUAL

	Pass the z test if the new z does not equal the current z.
dwSrcBlendCaps

Source blending capabilities. This member can be one or more of the following. (The RGBA values of the source and destination are indicated with the subscripts s and d.)

D3DPBLENDCAPS_BOTHINVSRCALPHA

	Source blend factor is (1-As, 1-As, 1-As, 1-As) and destination blend factor is (As, As, As, As); the destination blend selection is overridden.
D3DPBLENDCAPS_BOTHSRCALPHA

	Source blend factor is (As, As, As, As) and destination blend factor is (1-As, 1-As, 1-As, 1-As); the destination blend selection is overridden.
D3DPBLENDCAPS_DESTALPHA

	Blend factor is (Ad, Ad, Ad, Ad).
D3DPBLENDCAPS_DESTCOLOR

	Blend factor is (Rd, Gd, Bd, Ad).
D3DPBLENDCAPS_INVDESTALPHA

	Blend factor is (1-Ad, 1-Ad, 1-Ad, 1-Ad).
D3DPBLENDCAPS_INVDESTCOLOR

	Blend factor is (1-Rd, 1-Gd, 1-Bd, 1-Ad).
D3DPBLENDCAPS_INVSRCALPHA

	Blend factor is (1-As, 1-As, 1-As, 1-As).
D3DPBLENDCAPS_INVSRCCOLOR

	Blend factor is (1-Rd, 1-Gd, 1-Bd, 1-Ad).
D3DPBLENDCAPS_ONE

	Blend factor is (1, 1, 1, 1).
D3DPBLENDCAPS_SRCALPHA

	Blend factor is (As, As, As, As).
D3DPBLENDCAPS_SRCALPHASAT

	Blend factor is (f, f, f, 1); f = min(As, 1-Ad).
D3DPBLENDCAPS_SRCCOLOR

	Blend factor is (Rs, Gs, Bs, As).
D3DPBLENDCAPS_ZERO

	Blend factor is (0, 0, 0, 0).
dwDestBlendCaps

Destination blending capabilities. This member can be the same capabilities that are defined for the dwSrcBlendCaps member.

dwAlphaCmpCaps

Alpha-test comparison functions that the driver can perform. This member can be the same capabilities that are defined for the dwZCmpCaps member.

dwShadeCaps

Shading operations that the device can perform. It is assumed, in general, that if a device supports a given command (such as D3DOP_TRIANGLE) at all, it supports the D3DSHADE_FLAT mode (as specified in the D3DSHADEMODE enumerated type). This flag specifies whether the driver can also support Gouraud and Phong shading and whether alpha color components are supported for each of the three color-generation modes. When alpha components are not supported in a given mode, the alpha value of colors generated in that mode is implicitly 255. This is the maximum possible alpha (that is, the alpha component is at full intensity).

The color, specular highlights, fog, and alpha interpolants of a triangle each have capability flags that an application can use to find out how they are implemented by the device driver. These are modified by the shade mode, color model, and by whether the alpha component of a color is blended or stippled. For more information, see Polygons.

This member can be one or more of the following:

D3DPSHADECAPS_ALPHAFLATBLEND

D3DPSHADECAPS_ALPHAFLATSTIPPLED

	Device can support an alpha component for flat blended and stippled transparency, respectively (the D3DSHADE_FLAT state for the D3DSHADEMODE enumerated type). In these modes, the alpha color component for a primitive is provided as part of the color for the first vertex of the primitive.
D3DPSHADECAPS_ALPHAGOURAUDBLEND

D3DPSHADECAPS_ALPHAGOURAUDSTIPPLED

	Device can support an alpha component for Gouraud blended and stippled transparency, respectively (the D3DSHADE_GOURAUD state for the D3DSHADEMODE enumerated type). In these modes, the alpha color component for a primitive is provided at vertices and interpolated across a face along with the other color components.
D3DPSHADECAPS_ALPHAPHONGBLEND

D3DPSHADECAPS_ALPHAPHONGSTIPPLED

	Device can support an alpha component for Phong blended and stippled transparency, respectively (the D3DSHADE_PHONG state for the D3DSHADEMODE enumerated type). In these modes, vertex parameters are reevaluated on a per-pixel basis, applying lighting effects for the red, green, and blue color components. Phong shading is not supported for DirectX 2.
D3DPSHADECAPS_COLORFLATMONO

D3DPSHADECAPS_COLORFLATRGB

	Device can support colored flat shading in the D3DCOLOR_MONO and D3DCOLOR_RGB color models, respectively. In these modes, the color component for a primitive is provided as part of the color for the first vertex of the primitive. In monochromatic lighting modes, only the blue component of the color is interpolated; in RGB lighting modes, of course, the red, green, and blue components are interpolated.
D3DPSHADECAPS_COLORGOURAUDMONO

D3DPSHADECAPS_COLORGOURAUDRGB

	Device can support colored Gouraud shading in the D3DCOLOR_MONO and D3DCOLOR_RGB color models, respectively. In these modes, the color component for a primitive is provided at vertices and interpolated across a face along with the other color components. In monochromatic lighting modes, only the blue component of the color is interpolated; in RGB lighting modes, of course, the red, green, and blue components are interpolated.
D3DPSHADECAPS_COLORPHONGMONO

D3DPSHADECAPS_COLORPHONGRGB

	Device can support colored Phong shading in the D3DCOLOR_MONO and D3DCOLOR_RGB color models, respectively. In these modes, vertex parameters are reevaluated on a per-pixel basis. Lighting effects are applied for the red, green, and blue color components in RGB mode, and for the blue component only for monochromatic mode. Phong shading is not supported for DirectX 2.
D3DPSHADECAPS_FOGFLAT

D3DPSHADECAPS_FOGGOURAUD

D3DPSHADECAPS_FOGPHONG

	Device can support fog in the flat, Gouraud, and Phong shading models, respectively. Phong shading is not supported for DirectX 2.
D3DPSHADECAPS_SPECULARFLATMONO

D3DPSHADECAPS_SPECULARFLATRGB

	Device can support specular highlights in flat shading in the D3DCOLOR_MONO and D3DCOLOR_RGB color models, respectively.
D3DPSHADECAPS_SPECULARGOURAUDMONO

D3DPSHADECAPS_SPECULARGOURAUDRGB

	Device can support specular highlights in Gouraud shading in the D3DCOLOR_MONO and D3DCOLOR_RGB color models, respectively.
D3DPSHADECAPS_SPECULARPHONGMONO

D3DPSHADECAPS_SPECULARPHONGRGB

	Device can support specular highlights in Phong shading in the D3DCOLOR_MONO and D3DCOLOR_RGB color models, respectively. Phong shading is not supported for DirectX 2.
dwTextureCaps

Miscellaneous texture-mapping capabilities. This member can be one or more of the following:

D3DPTEXTURECAPS_ALPHA

	RGBA textures are supported in the D3DTEX_DECAL and D3DTEX_MODULATE texture filtering modes. If this capability is not set, then only RGB textures are supported in those modes. Regardless of the setting of this flag, alpha must always be supported in D3DTEX_DECAL_MASK, D3DTEX_DECAL_ALPHA, and D3DTEX_MODULATE_ALPHA filtering modes whenever those filtering modes are available.
D3DPTEXTURECAPS_BORDER

	Texture mapping along borders is supported.
D3DPTEXTURECAPS_PERSPECTIVE

	Perspective correction is supported.
D3DPTEXTURECAPS_POW2

	All non-mipmapped textures must have widths and heights specified as powers of two if this flag is set. (Note that all mipmapped textures must always have dimensions that are powers of two.)
D3DPTEXTURECAPS_SQUAREONLY

	All textures must be square.
D3DPTEXTURECAPS_TRANSPARENCY

	Texture transparency is supported. (Only those texels that are not the current transparent color are drawn.)
dwTextureFilterCaps

Texture-mapping capabilities. This member can be one or more of the following:

D3DPTFILTERCAPS_LINEAR

	A weighted average of a 2-by-2 area of texels surrounding the desired pixel is used. This applies to both zooming in and zooming out. If either zooming in or zooming out is supported, then both must be supported.
D3DPTFILTERCAPS_LINEARMIPLINEAR

	Similar to D3DPRIM_TEX_MIP_LINEAR, but interpolates between the two nearest mipmaps.
D3DPTFILTERCAPS_LINEARMIPNEAREST

	Similar to D3DPRIM_TEX_MIP_NEAREST, but interpolates between the two nearest mipmaps.
D3DPTFILTERCAPS_MIPLINEAR

	Similar to D3DPRIM_TEX_LINEAR, but uses the appropriate mipmap for texel selection.
D3DPTFILTERCAPS_MIPNEAREST

	Similar to D3DPRIM_TEX_NEAREST, but uses the appropriate mipmap for texel selection.
D3DPTFILTERCAPS_NEAREST

	The texel with coordinates nearest to the desired pixel value is used. This applies to both zooming in and zooming out. If either zooming in or zooming out is supported, then both must be supported.
dwTextureBlendCaps

Texture-blending capabilities. See the D3DTEXTUREBLEND enumerated type for discussions of the various texture-blending modes. This member can be one or more of the following:

D3DPTBLENDCAPS_COPY

	Copy mode texture-blending (D3DTBLEND_COPY from the D3DTEXTUREBLEND enumerated type) is supported.
D3DPTBLENDCAPS_DECAL

	Decal texture-blending mode (D3DTBLEND_DECAL from the D3DTEXTUREBLEND enumerated type) is supported.
D3DPTBLENDCAPS_DECALALPHA

	Decal-alpha texture-blending mode (D3DTBLEND_DECALALPHA from the D3DTEXTUREBLEND enumerated type) is supported.
D3DPTBLENDCAPS_DECALMASK

	Decal-mask texture-blending mode (D3DTBLEND_DECALMASK from the D3DTEXTUREBLEND enumerated type) is supported.
D3DPTBLENDCAPS_MODULATE

	Modulate texture-blending mode (D3DTBLEND_MODULATE from the D3DTEXTUREBLEND enumerated type) is supported.
D3DPTBLENDCAPS_MODULATEALPHA

	Modulate-alpha texture-blending mode (D3DTBLEND_MODULATEALPHA from the D3DTEXTUREBLEND enumerated type) is supported.
D3DPTBLENDCAPS_MODULATEMASK

	Modulate-mask texture-blending mode (D3DTBLEND_MODULATEMASK from the D3DTEXTUREBLEND enumerated type) is supported.
dwTextureAddressCaps

Texture-addressing capabilities. This member can be one or more of the following:

D3DPTADDRESSCAPS_CLAMP

	Device can clamp textures to addresses.
D3DPTADDRESSCAPS_MIRROR

	Device can mirror textures to addresses.
D3DPTADDRESSCAPS_WRAP

	Device can wrap textures to addresses.
dwStippleWidth and #dwStippleHeight

Maximum width and height of the supported stipple (up to 32-by-32).

Remarks


D3DPROCESSVERTICES

Describes how vertices in the execute buffer should be handled by the driver. This is used by the D3DOP_PROCESSVERTICES opcode in the D3DOPCODE enumerated type.

typedef struct _D3DPROCESSVERTICES {

    DWORD dwFlags;

    WORD  wStart;

    WORD  wDest;

    DWORD dwCount;

    DWORD dwReserved;

} D3DPROCESSVERTICES, *LPD3DPROCESSVERTICES;

Members

dwFlags

One or more of the following flags indicating how the driver should process the vertices:

D3DPROCESSVERTICES_COPY

	Vertices should simply be copied to the driver, because they have always been transformed and lit. If all the vertices in the execute buffer can be copied, the driver does not need to do the work of processing the vertices, and a performance improvement results.
D3DPROCESSVERTICES_NOCOLOR

	Vertices should not be colored.
D3DPROCESSVERTICES_OPMASK

	Specifies a bitmask of the other flags in the dwFlags member, exclusive of D3DPROCESSVERTICES_NOCOLOR and D3DPROCESSVERTICES_UPDATEEXTENTS.
D3DPROCESSVERTICES_TRANSFORM

	Vertices should be transformed.
D3DPROCESSVERTICES_TRANSFORMLIGHT

	Vertices should be transformed and lit.
D3DPROCESSVERTICES_UPDATEEXTENTS

	Extents of all transformed vertices should be updated. This information is returned in the drExtent member of the D3DSTATUS structure.
wStart

Index of the first vertex in the source.

wDest

Index of the first vertex in the local buffer.

dwCount

Number of vertices to be processed.

dwReserved

Reserved; must be zero.

See Also

 D3DOPCODE


D3DRECT

Rectangle definition.

typedef struct _D3DRECT {

    union {

        LONG x1;

        LONG lX1;

    };

    union {

        LONG y1;

        LONG lY1;

    };

    union {

        LONG x2;

        LONG lX2;

    };

    union {

        LONG y2;

        LONG lY2;

    };

} D3DRECT, *LPD3DRECT;

;

Members

lX1 and #lY1

Coordinates of the upper-left corner of the rectangle.

lX2 and #lY2

Coordinates of the lower-right corner of the rectangle.

See Also

 D3DRMUPDATECALLBACK, IDirect3DDevice::Pick, IDirect3DViewport::Clear


D3DSPAN

Defines a span for the D3DOP_SPAN opcode in the D3DOPCODE enumerated type. Spans join a list of points with the same y value. If the y value changes, a new span is started.

typedef struct _D3DSPAN {

    WORD wCount;

    WORD wFirst;

} D3DSPAN, *LPD3DSPAN;

Members

wCount

Number of spans.

wFirst

Index to first vertex.

See Also

 D3DOPCODE


D3DSTATE

Describes the render state for the D3DOP_STATETRANSFORM, D3DOP_STATELIGHT, and D3DOP_STATERENDER opcodes in the D3DOPCODE enumerated type. The first member of this structure is the relevant enumerated type and the second is the value for that type.

typedef struct _D3DSTATE {

    union {

        D3DTRANSFORMSTATETYPE dtstTransformStateType;

        D3DLIGHTSTATETYPE     dlstLightStateType;

        D3DRENDERSTATETYPE    drstRenderStateType;

    };

    union {

        DWORD                 dwArg[1];

        D3DVALUE              dvArg[1];

    };

} D3DSTATE, *LPD3DSTATE;

Members

dtstTransformStateType, #dlstLightStateType, and #drstRenderStateType

One of the members of the D3DTRANSFORMSTATETYPE, D3DLIGHTSTATETYPE, or D3DRENDERSTATETYPE enumerated type specifying the render state.

dvArg

Value of the type specified in the first member of this structure.

See Also

 D3DLIGHTSTATETYPE, D3DOPCODE, D3DRENDERSTATETYPE, and D3DTRANSFORMSTATETYPE, D3DVALUE


D3DSTATS

Contains statistics used by the IDirect3DDevice::GetStats method.

typedef struct _D3DSTATS {

    DWORD dwSize;

    DWORD dwTrianglesDrawn;

    DWORD dwLinesDrawn;

    DWORD dwPointsDrawn;

    DWORD dwSpansDrawn;

    DWORD dwVerticesProcessed;

} D3DSTATS, *LPD3DSTATS;

Members

dwSize

Size, in bytes, of this structure.

dwTrianglesDrawn, #dwLinesDrawn, #dwPointsDrawn, and #dwSpansDrawn

Number of triangles, lines, points, and spans drawn since the device was created.

dwVerticesProcessed

Number of vertices processed since the device was created.

See Also

 IDirect3DDevice::GetStats


D3DSTATUS

Describes the current status of the execute buffer. This structure is part of the D3DEXECUTEDATA structure and is used with the D3DOP_SETSTATUS opcode in the D3DOPCODE enumerated type.

typedef struct _D3DSTATUS {

    DWORD   dwFlags;

    DWORD   dwStatus;

    D3DRECT drExtent;

} D3DSTATUS, *LPD3DSTATUS;

Members

dwFlags

One of the following flags, specifying whether the status, the extents, or both are being set:

D3DSETSTATUS_STATUS

	Set the status.
D3DSETSTATUS_EXTENTS

	Set the extents specified in the drExtent member.
D3DSETSTATUS_ALL

	Set both the status and the extents.
dwStatus

Clipping flags. This member can be one or more of the following flags:

Combination and General Flags

D3DSTATUS_CLIPINTERSECTION

	Combination of all CLIPINTERSECTION flags.
D3DSTATUS_CLIPUNIONALL

	Combination of all CLIPUNION flags.
D3DSTATUS_DEFAULT

	Combination of D3DSTATUS_CLIPINTERSECTION and D3DSTATUS_ZNOTVISIBLE flags. This value is the default.
D3DSTATUS_ZNOTVISIBLE

Clip Intersection Flags

D3DSTATUS_CLIPINTERSECTIONLEFT

	Logical AND of the clip flags for the vertices compared to the left side of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONRIGHT

	Logical AND of the clip flags for the vertices compared to the right side of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONTOP

	Logical AND of the clip flags for the vertices compared to the top of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONBOTTOM

	Logical AND of the clip flags for the vertices compared to the bottom of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONFRONT

	Logical AND of the clip flags for the vertices compared to the front clipping plane of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONBACK

	Logical AND of the clip flags for the vertices compared to the back clipping plane of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONGEN0 through D3DSTATUS_CLIPINTERSECTIONGEN5

	Logical AND of the clip flags for application-defined clipping planes.
Clip Union Flags

D3DSTATUS_CLIPUNIONLEFT

	Equal to D3DCLIP_LEFT.
D3DSTATUS_CLIPUNIONRIGHT

	Equal to D3DCLIP_RIGHT.
D3DSTATUS_CLIPUNIONTOP

	Equal to D3DCLIP_TOP.
D3DSTATUS_CLIPUNIONBOTTOM

	Equal to D3DCLIP_BOTTOM.
D3DSTATUS_CLIPUNIONFRONT

	Equal to D3DCLIP_FRONT.
D3DSTATUS_CLIPUNIONBACK

	Equal to D3DCLIP_BACK.
D3DSTATUS_CLIPUNIONGEN0 through D3DSTATUS_CLIPUNIONGEN5

	Equal to D3DCLIP_GEN0 through D3DCLIP_GEN5.
Basic Clipping Flags

D3DCLIP_BACK

	All vertices are clipped by the back plane of the viewing frustum.
D3DCLIP_BOTTOM

	All vertices are clipped by the bottom plane of the viewing frustum.
D3DCLIP_FRONT

	All vertices are clipped by the front plane of the viewing frustum.
D3DCLIP_LEFT

	All vertices are clipped by the left plane of the viewing frustum.
D3DCLIP_RIGHT

	All vertices are clipped by the right plane of the viewing frustum.
D3DCLIP_TOP

	All vertices are clipped by the top plane of the viewing frustum.
D3DCLIP_GEN0 through D3DCLIP_GEN5

	Application-defined clipping planes.
drExtent

A D3DRECT structure that defines a bounding box for all the relevant vertices. For example, the structure might define the area containing the output of the D3DOP_PROCESSVERTICES opcode, assuming the D3DPROCESSVERTICES_UPDATEEXTENTS flag is set in the D3DPROCESSVERTICES structure.

Remarks

The status is a rolling status and is updated during each execution. The bounding box in the drExtent member can grow with each execution, but it does not shrink; it can be reset only by using the D3DOP_SETSTATUS opcode.

See Also

 D3DEXECUTEDATA, D3DOPCODE, D3DRECT


D3DTEXTURELOAD

Describes operand data for the D3DOP_TEXTURELOAD opcode in the D3DOPCODE enumerated type.

typedef struct _D3DTEXTURELOAD {

    D3DTEXTUREHANDLE hDestTexture;

    D3DTEXTUREHANDLE hSrcTexture;

} D3DTEXTURELOAD, *LPD3DTEXTURELOAD;

Members

hDestTexture

Handle of the destination texture.

hSrcTexture

Handle of the source texture.

Remarks

The textures referred to by the hDestTexture and hSrcTexture members must be the same size.


D3DTLVERTEX

Defines a transformed and lit vertex (screen coordinates with color) for the D3DLIGHTDATA structure.

typedef struct _D3DTLVERTEX {

    union {

        D3DVALUE sx;

        D3DVALUE dvSX;

    };

    union {

        D3DVALUE sy;

        D3DVALUE dvSY;

    };

    union {

        D3DVALUE sz;

        D3DVALUE dvSZ;

    };

    union {

        D3DVALUE rhw;

        D3DVALUE dvRHW;

    };

    union {

        D3DCOLOR color;

        D3DCOLOR dcColor;

    };

    union {

        D3DCOLOR specular;

        D3DCOLOR dcSpecular;

    };

    union {

        D3DVALUE tu;

        D3DVALUE dvTU;

    };

    union {

        D3DVALUE tv;

        D3DVALUE dvTV;

    };

} D3DTLVERTEX, *LPD3DTLVERTEX;

Members

dvSX, #dvSY, and #dvSZ

Values of the D3DVALUE type describing a vertex in screen coordinates.

dvRHW

Value of the D3DVALUE type that is the reciprocal of homogeneous w. This value is 1 divided by the distance from the origin to the object along the z-axis.

dcColor and #dcSpecular

Values of the D3DCOLOR type describing the color and specular component of the vertex.

dvTU and #dvTV

Values of the D3DVALUE type describing the texture coordinates of the vertex.

See Also

 D3DLIGHTDATA


D3DTRANSFORMCAPS

Describes the transformation capabilities of a device. This structure is part of the D3DDEVICEDESC structure.

typedef struct _D3DTransformCaps {

    DWORD dwSize;

    DWORD dwCaps;

} D3DTRANSFORMCAPS, *LPD3DTRANSFORMCAPS;

Members

dwSize

Size, in bytes, of this structure.

dwCaps

Flag specifying whether the system clips while transforming. This member can be zero or the following flag:

D3DTRANSFORMCAPS_CLIP	The system clips while transforming.


D3DTRANSFORMDATA

Contains information about transformations for the IDirect3DViewport::TransformVertices method.

typedef struct _D3DTRANSFORMDATA {

    DWORD        dwSize;

    LPVOID       lpIn;

    DWORD        dwInSize;

    LPVOID       lpOut;

    DWORD        dwOutSize;

    LPD3DHVERTEX lpHOut;

    DWORD        dwClip;

    DWORD        dwClipIntersection;

    DWORD        dwClipUnion;

    D3DRECT      drExtent;

} D3DTRANSFORMDATA, *LPD3DTRANSFORMDATA;

Members

dwSize

Size of the structure, in bytes.

lpIn

Address of the vertices to be transformed.

dwInSize

Stride of the vertices to be transformed.

lpOut

Address used to store the transformed vertices.

dwOutSize

Stride of output vertices.

lpHOut

Address of a value that contains homogeneous transformed vertices. This value is a D3DHVERTEX structure

dwClip

Flags specifying how the vertices are clipped. This member can be one or more of the following values:

D3DCLIP_BACK

	Clipped by the back plane of the viewing frustum.
D3DCLIP_BOTTOM

	Clipped by the bottom plane of the viewing frustum.
D3DCLIP_FRONT

	Clipped by the front plane of the viewing frustum.
D3DCLIP_LEFT

	Clipped by the left plane of the viewing frustum.
D3DCLIP_RIGHT

	Clipped by the right plane of the viewing frustum.
D3DCLIP_TOP

	Clipped by the top plane of the viewing frustum.
D3DCLIP_GEN0 through D3DCLIP_GEN5

	Application-defined clipping planes.
dwClipIntersection

Flags denoting the intersection of the clip flags. This member can be one or more of the following values:

D3DSTATUS_CLIPINTERSECTIONLEFT

	Logical AND of the clip flags for the vertices compared to the left side of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONRIGHT

	Logical AND of the clip flags for the vertices compared to the right side of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONTOP

	Logical AND of the clip flags for the vertices compared to the top of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONBOTTOM

	Logical AND of the clip flags for the vertices compared to the bottom of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONFRONT

	Logical AND of the clip flags for the vertices compared to the front clipping plane of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONBACK

	Logical AND of the clip flags for the vertices compared to the back clipping plane of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONGEN0 through D3DSTATUS_CLIPINTERSECTIONGEN5

	Logical AND of the clip flags for application-defined clipping planes.
dwClipUnion

Flags denoting the union of the clip flags. This member can be one or more of the following values:

D3DSTATUS_CLIPUNIONLEFT

	Equal to D3DCLIP_LEFT.
D3DSTATUS_CLIPUNIONRIGHT

	Equal to D3DCLIP_RIGHT.
D3DSTATUS_CLIPUNIONTOP

	Equal to D3DCLIP_TOP.
D3DSTATUS_CLIPUNIONBOTTOM

	Equal to D3DCLIP_BOTTOM.
D3DSTATUS_CLIPUNIONFRONT

	Equal to D3DCLIP_FRONT.
D3DSTATUS_CLIPUNIONBACK

	Equal to D3DCLIP_BACK.
D3DSTATUS_CLIPUNIONGEN0 through D3DSTATUS_CLIPUNIONGEN5

	Equal to D3DCLIP_GEN0 through D3DCLIP_GEN5.
drExtent

Value that defines the extent of the transformed vertices. This structure is filled by the transformation module with the screen extent of the transformed geometry. For geometries that are clipped, this extent will only include vertices that are inside the viewing volume. This value is a D3DRECT structure

Remarks

Each input vertex should be a three-vector vertex giving the [x y z] coordinates in model space for the geometry. The dwInSize member gives the amount to skip between vertices, allowing the application to store extra data inline with each vertex.

All values generated by the transformation module are stored as 16-bit precision values. The clip is treated as an integer bitfield that is set to the inclusive OR of the viewing volume planes that clip a given transformed vertex.

See Also

 IDirect3DViewport::TransformVertices


D3DTRIANGLE

Describes the base type for all triangles. The triangle is the main rendering primitive.

For related information, see the D3DOP_TRIANGLE member in the D3DOPCODE enumerated type.

typedef struct _D3DTRIANGLE {

    union {

        WORD v1;

        WORD wV1;

    };

    union {

        WORD v2;

        WORD wV2;

    };

    union {

        WORD v3;

        WORD wV3;

    };

    WORD     wFlags;

} D3DTRIANGLE, *LPD3DTRIANGLE;

Members

wV1, #wV2, and #wV3

Vertices describing the triangle.

wFlags

Flags describing which edges of the triangle to enable. (This information is useful only in wireframe mode.) This value can be a combination of the following edge and strip and fan flags:

Edge flags

D3DTRIFLAG_EDGEENABLE1

	Edge defined by v1–v2.
D3DTRIFLAG_EDGEENABLE2

	Edge defined by v2–v3.
D3DTRIFLAG_EDGEENABLE3

	Edge defined by v3–v1.
D3DTRIFLAG_EDGEENABLETRIANGLE

	All edges.
Strip and fan flags

D3DTRIFLAG_EVEN

	The v1–v2 edge of the current triangle is adjacent to the v3–v1 edge of the previous triangle; that is, v1 is the previous v1, and v2 is the previous v3.
D3DTRIFLAG_ODD

	The v1–v2 edge of the current triangle is adjacent to the v2–v3 edge of the previous triangle; that is, v1 is the previous v3, and v2 is the previous v2.
D3DTRIFLAG_START

	Begin the strip or fan, loading all three vertices.
D3DTRIFLAG_STARTFLAT(len)

	If this triangle is culled, also cull the specified number of subsequent triangles. This length must be greater than zero and less than 30.
Remarks

This structure can be used directly for all triangle fills. For flat shading, the color and specular components are taken from the first vertex. The three vertex indices v1, v2, and v3 are vertex indexes into the vertex list at the start of the execute buffer.

Enabled edges are visible in wireframe mode. When an application displays wireframe triangles that share an edge, it typically enables only one (or neither) edge to avoid drawing the edge twice.

The D3DTRIFLAG_ODD and D3DTRIFLAG_EVEN flags refer to the locations of a triangle in a conventional triangle strip or fan. If a triangle strip had five triangles, the following flags would be used to define the strip:

D3DTRIFLAG_START
D3DTRIFLAG_ODD
D3DTRIFLAG_EVEN
D3DTRIFLAG_ODD
D3DTRIFLAG_EVEN
Similarly, the following flags would define a triangle fan with five triangles:

D3DTRIFLAG_START
D3DTRIFLAG_EVEN
D3DTRIFLAG_EVEN
D3DTRIFLAG_EVEN
D3DTRIFLAG_EVEN
The following flags could define a flat triangle fan with five triangles:

D3DTRIFLAG_STARTFLAT(4)
D3DTRIFLAG_EVEN
D3DTRIFLAG_EVEN
D3DTRIFLAG_EVEN
D3DTRIFLAG_EVEN
See Also

 Triangle Strips and Fans


D3DVECTOR

Defines a vector for many Direct3D and Direct3DRM methods and structures.

typedef struct _D3DVECTOR {

    union {

        D3DVALUE x;

        D3DVALUE dvX;

    };

    union {

        D3DVALUE y;

        D3DVALUE dvY;

    };

    union {

        D3DVALUE z;

        D3DVALUE dvZ;

    };

} D3DVECTOR, *LPD3DVECTOR;

Members

dvX, #dvY, and #dvZ

Values of the D3DVALUE type describing the vector.

See Also

 D3DLIGHT, D3DLIGHTINGELEMENT, D3DRMBOX, D3DRMQUATERNION, D3DRMVERTEX


D3DVERTEX

Defines an untransformed and unlit vertex (model coordinates with normal direction vector).

For related information, see the D3DOP_TRIANGLE member in the D3DOPCODE enumerated type.

typedef struct _D3DVERTEX {

    union {

        D3DVALUE x;

        D3DVALUE dvX;

    };

    union {

        D3DVALUE y;

        D3DVALUE dvY;

    };

    union {

        D3DVALUE z;

        D3DVALUE dvZ;

    };

    union {

        D3DVALUE nx;

        D3DVALUE dvNX;

    };

    union {

        D3DVALUE ny;

        D3DVALUE dvNY;

    };

    union {

        D3DVALUE nz;

        D3DVALUE dvNZ;

    };

    union {

        D3DVALUE tu;

        D3DVALUE dvTU;

    };

    union {

        D3DVALUE tv;

        D3DVALUE dvTV;

    };

} D3DVERTEX, *LPD3DVERTEX;

Members

dvX, #dvY, and #dvZ

Values of the D3DVALUE type describing the homogeneous coordinates of the vertex.

dvNX, #dvNY, and #dvNZ

Values of the D3DVALUE type describing the normal coordinates of the vertex.

dvTU and #dvTV

Values of the D3DVALUE type describing the texture coordinates of the vertex.

See Also

 D3DVALUE


D3DVIEWPORT

Defines the visible 3D volume and the 2D screen area that a 3D volume projects onto for the IDirect3DViewport::GetViewport and IDirect3DViewport::SetViewport methods.

When the viewport is changed, the driver builds a new transformation matrix.

The coordinates and dimensions of the viewport are given relative to the top left of the device.

typedef struct _D3DVIEWPORT {

    DWORD    dwSize;

    DWORD    dwX;

    DWORD    dwY;

    DWORD    dwWidth;

    DWORD    dwHeight;

    D3DVALUE dvScaleX;

    D3DVALUE dvScaleY;

    D3DVALUE dvMaxX;

    D3DVALUE dvMaxY;

    D3DVALUE dvMinZ;

    D3DVALUE dvMaxZ;

} D3DVIEWPORT, *LPD3DVIEWPORT;

Members

dwSize

Size of this structure, in bytes.

dwX and #dwY

Coordinates of the top-left corner of the viewport.

dwWidth and #dwHeight

Dimensions of the viewport.

dvScaleX and #dvScaleY

Values of the D3DVALUE type describing the scaling quantities homogeneous to screen.

dvMaxX, #dvMaxY, #dvMinZ, and #dvMaxZ

Values of the D3DVALUE type describing the maximum and minimum homogeneous coordinates of x, y, and z.

See Also

 D3DVALUE, IDirect3DViewport::GetViewport, IDirect3DViewport::SetViewport


Enumerated Types


D3DBLEND

Defines the supported blend modes for the D3DRENDERSTATE_DSTBLEND values in the D3DRENDERSTATETYPE enumerated type. In the member descriptions that follow, the RGBA values of the source and destination are indicated with the subscripts s and d.

typedef enum _D3DBLEND {

    D3DBLEND_ZERO            = 1,

    D3DBLEND_ONE             = 2,

    D3DBLEND_SRCCOLOR        = 3,

    D3DBLEND_INVSRCCOLOR     = 4,

    D3DBLEND_SRCALPHA        = 5,

    D3DBLEND_INVSRCALPHA     = 6,

    D3DBLEND_DESTALPHA       = 7,

    D3DBLEND_INVDESTALPHA    = 8,

    D3DBLEND_DESTCOLOR       = 9,

    D3DBLEND_INVDESTCOLOR    = 10,

    D3DBLEND_SRCALPHASAT     = 11,

    D3DBLEND_BOTHSRCALPHA    = 12,

    D3DBLEND_BOTHINVSRCALPHA = 13,

} D3DBLEND;

Values

D3DBLEND_ZERO

Blend factor is (0, 0, 0, 0).

D3DBLEND_ONE

Blend factor is (1, 1, 1, 1).

D3DBLEND_SRCCOLOR

Blend factor is (Rs, Gs, Bs, As).

D3DBLEND_INVSRCCOLOR

Blend factor is (As, As, As, As, 1-As).

D3DBLEND_SRCALPHA

Blend factor is (As, As, As, As).

D3DBLEND_INVSRCALPHA

Blend factor is (1-As, 1-As, 1-As).

D3DBLEND_DESTALPHA

Blend factor is (Ad, Ad, Ad, Ad).

D3DBLEND_INVDESTALPHA

Blend factor is (1-Ad, 1-Ad, 1-Ad, 1-Ad).

D3DBLEND_DESTCOLOR

Blend factor is (Rd, Gd, Bd, Ad).

D3DBLEND_INVDESTCOLOR

Blend factor is (1-Rd, 1-Gd, 1-Bd, 1-Ad).

D3DBLEND_SRCALPHASAT

Blend factor is (f, f, f, 1); f = min(As, 1-Ad).

D3DBLEND_BOTHSRCALPHA

Source blend factor is (As, As, As, As), and destination blend factor is (1-As, 1-As, 1-As, 1-As); the destination blend selection is overridden.

D3DBLEND_BOTHINVSRCALPHA

Source blend factor is (1-As, 1-As, 1-As, 1-As), and destination blend factor is (As, As, As, As); the destination blend selection is overridden.

Remarks


D3DCMPFUNC

Defines the supported compare functions for the D3DRENDERSTATE_ZFUNC and D3DRENDERSTATE_ALPHAFUNC values of the D3DRENDERSTATETYPE enumerated type.

typedef enum _D3DCMPFUNC {

    D3DCMP_NEVER        = 1,

    D3DCMP_LESS         = 2,

    D3DCMP_EQUAL        = 3,

    D3DCMP_LESSEQUAL    = 4,

    D3DCMP_GREATER      = 5,

    D3DCMP_NOTEQUAL     = 6,

    D3DCMP_GREATEREQUAL = 7,

    D3DCMP_ALWAYS       = 8,

} D3DCMPFUNC;

Values

D3DCMP_NEVER

Always fail the test.

D3DCMP_LESS

Accept the new pixel if its value is less than the value of the current pixel.

D3DCMP_EQUAL

Accept the new pixel if its value equals the value of the current pixel.

D3DCMP_LESSEQUAL

Accept the new pixel if its value is less than or equal to the value of the current pixel.

D3DCMP_GREATER

Accept the new pixel if its value is greater than the value of the current pixel.

D3DCMP_NOTEQUAL

Accept the new pixel if its value does not equal the value of the current pixel.

D3DCMP_GREATEREQUAL

Accept the new pixel if its value is greater than or equal to the value of the current pixel.

D3DCMP_ALWAYS

Always pass the test.


D3DCOLORMODEL

Defines the color model that the system will run in.

typedef enum _D3DCOLORMODEL {

    D3DCOLOR_MONO = 1,

    D3DCOLOR_RGB  = 2,

} D3DCOLORMODEL;

Values

D3DCOLOR_MONO

Use a monochromatic model (or ramp model). In this model, the blue component of a vertex color is used to define the brightness of a lit vertex.

D3DCOLOR_RGB

Use a full RGB model.

See Also

 D3DDEVICEDESC, D3DFINDDEVICESEARCH, D3DLIGHTSTATETYPE, IDirect3DRMDevice::GetColorModel


D3DCULL

Defines the supported cull modes. These define how faces are culled when rendering a geometry.

typedef enum _D3DCULL {

    D3DCULL_NONE = 1,

    D3DCULL_CW   = 2,

    D3DCULL_CCW  = 3,

} D3DCULL;

Values

D3DCULL_NONE

Do not cull faces.

D3DCULL_CW

Cull faces with clockwise vertices.

D3DCULL_CCW

Cull faces with counterclockwise vertices.

See Also

 D3DPRIMCAPS, D3DRENDERSTATETYPE


D3DFILLMODE

Contains constants describing the fill mode. These values are used by the D3DRENDERSTATE_FILLMODE render state in the D3DRENDERSTATETYPE enumerated type.

typedef enum _D3DFILLMODE {

    D3DFILL_POINT     = 1,

    D3DFILL_WIREFRAME = 2,

    D3DFILL_SOLID     = 3

} D3DFILLMODE;

Values

D3DFILL_POINT

Fill points.

D3DFILL_WIREFRAME

Fill wireframes.

D3DFILL_SOLID

Fill solids.


D3DFOGMODE

Contains constants describing the fog mode. These values are used by the D3DRENDERSTATE_FOGTABLEMODE render state in the D3DRENDERSTATETYPE enumerated type.

typedef enum _D3DFOGMODE {

    D3DFOG_NONE   = 0,

    D3DFOG_EXP    = 1,

    D3DFOG_EXP2   = 2,

    D3DFOG_LINEAR = 3

} D3DFOGMODE;

Values

D3DFOG_NONE

No fog effect.

D3DFOG_EXP

The fog effect intensifies exponentially, according to the following formula:

D3DFOG_EXP2

The fog effect intensifies exponentially with the square of the distance, according to the following formula:

D3DFOG_LINEAR

The fog effect intensifies linearly between the start and end points, according to the following formula:

This is the only fog mode supported for DirectX 2.

Remarks

Note that fog can be considered a measure of visibility—the lower the fog value produced by one of the fog equations, the less visible an object is.


D3DLIGHTSTATETYPE

Defines the light state for the D3DOP_STATELIGHT opcode. This enumerated type is part of the D3DSTATE structure.

typedef enum _D3DLIGHTSTATETYPE {

    D3DLIGHTSTATE_MATERIAL   = 1,

    D3DLIGHTSTATE_AMBIENT    = 2,

    D3DLIGHTSTATE_COLORMODEL = 3,

    D3DLIGHTSTATE_FOGMODE    = 4,

    D3DLIGHTSTATE_FOGSTART   = 5,

    D3DLIGHTSTATE_FOGEND     = 6,

    D3DLIGHTSTATE_FOGDENSITY = 7,

} D3DLIGHTSTATETYPE;

Values

D3DLIGHTSTATE_MATERIAL

Defines the material associated with a light. The default value is NULL.

D3DLIGHTSTATE_AMBIENT

Defines whether the light is ambient. The default value is 0.

D3DLIGHTSTATE_COLORMODEL

One of the members of the D3DCOLORMODEL enumerated type. The default value is D3DCOLOR_RGB.

D3DLIGHTSTATE_FOGMODE

One of the members of the D3DFOGMODE enumerated type. The default value is D3DFOG_NONE.

D3DLIGHTSTATE_FOGSTART

Defines the starting value for fog. The default value is 1.0.

D3DLIGHTSTATE_FOGEND

Defines the ending value for fog. The default value is 100.0.

D3DLIGHTSTATE_FOGDENSITY

Defines the density setting for fog. The default value is 1.0.

See Also

 D3DOPCODE and D3DSTATE


D3DLIGHTTYPE

Defines the light type. This enumerated type is part of the D3DLIGHT structure.

typedef enum _D3DLIGHTTYPE {

    D3DLIGHT_POINT         = 1,

    D3DLIGHT_SPOT          = 2,

    D3DLIGHT_DIRECTIONAL   = 3,

    D3DLIGHT_PARALLELPOINT = 4,

    D3DLIGHT_GLSPOT        = 5,

} D3DLIGHTTYPE;

Values

D3DLIGHT_POINT

Light is a point source.

D3DLIGHT_SPOT

Light is a spotlight source.

D3DLIGHT_DIRECTIONAL

Light is a directional source.

D3DLIGHT_PARALLELPOINT

Light is a parallel source.

D3DLIGHT_GLSPOT

Light is a GL-style spotlight.

See Also

 Direct3DRMLight


D3DOPCODE

Contains the opcodes for execute buffers.

typedef enum _D3DOPCODE {

    D3DOP_POINT           = 1,

    D3DOP_LINE            = 2,

    D3DOP_TRIANGLE        = 3,

    D3DOP_MATRIXLOAD      = 4,

    D3DOP_MATRIXMULTIPLY  = 5,

    D3DOP_STATETRANSFORM  = 6,

    D3DOP_STATELIGHT      = 7,

    D3DOP_STATERENDER     = 8,

    D3DOP_PROCESSVERTICES = 9,

    D3DOP_TEXTURELOAD     = 10,

    D3DOP_EXIT            = 11,

    D3DOP_BRANCHFORWARD   = 12,

    D3DOP_SPAN            = 13,

    D3DOP_SETSTATUS       = 14,

} D3DOPCODE;

Values

D3DOP_POINT

Sends a point to the renderer. Operand data is described by the D3DPOINT structure.

D3DOP_LINE

Sends a line to the renderer. Operand data is described by the D3DLINE structure.

D3DOP_TRIANGLE

Sends a triangle to the renderer. Operand data is described by the D3DTRIANGLE structure.

D3DOP_MATRIXLOAD

Triggers a data transfer in the rendering engine. Operand data is described by the D3DMATRIXLOAD structure.

D3DOP_MATRIXMULTIPLY

Triggers a data transfer in the rendering engine. Operand data is described by the D3DMATRIXMULTIPLY structure.

D3DOP_STATETRANSFORM

Sets the value of internal state variables in the rendering engine for the transformation module. Operand data is a variable token and the new value. The token identifies the internal state variable, and the new value is the value to which that variable should be set. For more information about these variables, see the D3DSTATE structure and the D3DTRANSFORMSTATETYPE enumerated type.

D3DOP_STATELIGHT

Sets the value of internal state variables in the rendering engine for the lighting module. Operand data is a variable token and the new value. The token identifies the internal state variable, and the new value is the value to which that variable should be set. For more information about these variables, see the D3DSTATE structure and the D3DLIGHTSTATETYPE enumerated type.

D3DOP_STATERENDER

Sets the value of internal state variables in the rendering engine for the rendering module. Operand data is a variable token and the new value. The token identifies the internal state variable, and the new value is the value to which that variable should be set. For more information about these variables, see the D3DSTATE structure and the D3DRENDERSTATETYPE enumerated type.

D3DOP_PROCESSVERTICES

Sets both lighting and transformations for vertices. Operand data is described by the D3DPROCESSVERTICES structure.

D3DOP_TEXTURELOAD

Triggers a data transfer in the rendering engine. Operand data is described by the D3DTEXTURELOAD structure.

D3DOP_EXIT

Signals that the end of the list has been reached.

D3DOP_BRANCHFORWARD

Enables a branching mechanism within the execute buffer. For more information, see the D3DBRANCH structure.

D3DOP_SPAN

Spans a list of points with the same y value. For more information, see the D3DSPAN structure.

D3DOP_SETSTATUS

Resets the status of the execute buffer. For more information, see the D3DSTATUS structure.

Remarks

An execute buffer has two parts: an array of vertices (each typically with position, normal vector, and texture coordinates) and an array of opcode/operand groups. One opcode can have several operands following it; the system simply performs the relevant operation on each operand.

See Also

 D3DINSTRUCTION


D3DRENDERSTATETYPE

Describes the render state for the D3DOP_STATERENDER opcode. This enumerated type is part of the D3DSTATE structure. The values mentioned in the following descriptions are set in the second member of this structure.

typedef enum _D3DRENDERSTATETYPE {

    D3DRENDERSTATE_TEXTUREHANDLE      = 1,

    D3DRENDERSTATE_ANTIALIAS          = 2,

    D3DRENDERSTATE_TEXTUREADDRESS     = 3,

    D3DRENDERSTATE_TEXTUREPERSPECTIVE = 4,

    D3DRENDERSTATE_WRAPU              = 5,

    D3DRENDERSTATE_WRAPV              = 6,

    D3DRENDERSTATE_ZENABLE            = 7,

    D3DRENDERSTATE_FILLMODE           = 8,

    D3DRENDERSTATE_SHADEMODE          = 9,

    D3DRENDERSTATE_LINEPATTERN        = 10,

    D3DRENDERSTATE_MONOENABLE         = 11,

    D3DRENDERSTATE_ROP2               = 12,

    D3DRENDERSTATE_PLANEMASK          = 13,

    D3DRENDERSTATE_ZWRITEENABLE       = 14,

    D3DRENDERSTATE_ALPHATESTENABLE    = 15,

    D3DRENDERSTATE_LASTPIXEL          = 16,

    D3DRENDERSTATE_TEXTUREMAG         = 17,

    D3DRENDERSTATE_TEXTUREMIN         = 18,

    D3DRENDERSTATE_SRCBLEND           = 19,

    D3DRENDERSTATE_DESTBLEND          = 20,

    D3DRENDERSTATE_TEXTUREMAPBLEND    = 21,

    D3DRENDERSTATE_CULLMODE           = 22,

    D3DRENDERSTATE_ZFUNC              = 23,

    D3DRENDERSTATE_ALPHAREF           = 24,

    D3DRENDERSTATE_ALPHAFUNC          = 25,

    D3DRENDERSTATE_DITHERENABLE       = 26,

    D3DRENDERSTATE_BLENDENABLE        = 27,

    D3DRENDERSTATE_FOGENABLE          = 28,

    D3DRENDERSTATE_SPECULARENABLE     = 29,

    D3DRENDERSTATE_ZVISIBLE           = 30,

    D3DRENDERSTATE_SUBPIXEL           = 31,

    D3DRENDERSTATE_SUBPIXELX          = 32,

    D3DRENDERSTATE_STIPPLEDALPHA      = 33,

    D3DRENDERSTATE_FOGCOLOR           = 34,

    D3DRENDERSTATE_FOGTABLEMODE       = 35,

    D3DRENDERSTATE_FOGTABLESTART      = 36,

    D3DRENDERSTATE_FOGTABLEEND        = 37,

    D3DRENDERSTATE_FOGTABLEDENSITY    = 38,

    D3DRENDERSTATE_STIPPLEENABLE      = 39,

    D3DRENDERSTATE_STIPPLEPATTERN00   = 64,

       // Stipple patterns 01 through 30 omitted here.

    D3DRENDERSTATE_STIPPLEPATTERN31   = 95,

} D3DRENDERSTATETYPE;

Values

D3DRENDERSTATE_TEXTUREHANDLE

Texture handle. The default value is NULL.

D3DRENDERSTATE_ANTIALIAS

Antialiasing primitive edges. The default value is FALSE.

D3DRENDERSTATE_TEXTUREADDRESS

One of the members of the D3DTEXTUREADDRESS enumerated type. The default value is D3DTADDRESS_WRAP.

D3DRENDERSTATE_TEXTUREPERSPECTIVE

TRUE for perspective correction. The default value is FALSE.

D3DRENDERSTATE_WRAPU

TRUE for wrapping in u direction. The default value is FALSE.

D3DRENDERSTATE_WRAPV

TRUE for wrapping in v direction. The default value is FALSE.

D3DRENDERSTATE_ZENABLE

TRUE to enable the z-buffer comparison test when writing to the frame buffer. The default value is FALSE.

D3DRENDERSTATE_FILLMODE

One or more members of the D3DFILLMODE enumerated type. The default value is D3DFILL_SOLID.

D3DRENDERSTATE_SHADEMODE

One or more members of the D3DSHADEMODE enumerated type. The default value is D3DSHADE_GOURAUD.

D3DRENDERSTATE_LINEPATTERN

The D3DLINEPATTERN structure. The default values are 0 for wRepeatPattern and 0 for wLinePattern.

D3DRENDERSTATE_ROP2

One of the 16 ROP2 binary raster operations specifying how the supplied pixels are combined with the pixels of the display surface. The default value is R2_COPYPEN. Applications can use the D3DPRASTERCAPS_ROP2 flag in the dwRasterCaps member of the D3DPRIMCAPS structure to determine whether additional raster operations are supported.

D3DRENDERSTATE_PLANEMASK

Physical plane mask whose type is ULONG. The default value is ~0.

D3DRENDERSTATE_ZWRITEENABLE

TRUE to enable z writes. The default value is TRUE. This member enables an application to prevent the system from updating the z-buffer with new z values.

D3DRENDERSTATE_ALPHATESTENABLE

TRUE to enable alpha tests. The default value is FALSE. This member enables applications to turn off the tests that otherwise would accept or reject a pixel based on its alpha value.

D3DRENDERSTATE_LASTPIXEL

TRUE to prevent drawing the last pixel in a line. The default value is FALSE.

D3DRENDERSTATE_TEXTUREMAG

One of the members of the D3DTEXTUREFILTER enumerated type. The default value is D3DFILTER_NEAREST.

D3DRENDERSTATE_TEXTUREMIN

One of the members of the D3DTEXTUREFILTER enumerated type. The default value is D3DFILTER_NEAREST.

D3DRENDERSTATE_SRCBLEND

One of the members of the D3DBLEND enumerated type. The default value is D3DBLEND_ONE.

D3DRENDERSTATE_DSTBLEND

One of the members of the D3DBLEND enumerated type. The default value is D3DBLEND_ZERO.

D3DRENDERSTATE_TEXTUREMAPBLEND

One of the members of the D3DTEXTUREBLEND enumerated type. The default value is D3DTBLEND_MODULATE.

D3DRENDERSTATE_CULLMODE

One of the members of the D3DCULL enumerated type. The default value is D3DCULL_CCW. Software renderers have a fixed culling order and do not support changing the culling mode.

D3DRENDERSTATE_ZFUNC

One of the members of the D3DCMPFUNC enumerated type. The default value is D3DCMP_LESSEQUAL. This member enables an application to accept or reject a pixel based on its distance from the camera.

D3DRENDERSTATE_ALPHAREF

Value specifying a reference alpha value against which pixels are tested when alpha-testing is enabled. This value's type is D3DFIXED. The default value is 0.

D3DRENDERSTATE_ALPHAFUNC

One of the members of the D3DCMPFUNC enumerated type. The default value is D3DCMP_ALWAYS. This member enables an application to accept or reject a pixel based on its alpha value.

D3DRENDERSTATE_DITHERENABLE

TRUE to enable dithering. The default value is FALSE.

D3DRENDERSTATE_BLENDENABLE

TRUE to enable alpha blending. The default value is FALSE.

D3DRENDERSTATE_FOGENABLE

TRUE to enable fog. The default value is FALSE.

D3DRENDERSTATE_SPECULARENABLE

TRUE to enable specular. The default value is TRUE.

D3DRENDERSTATE_ZVISIBLE

TRUE to enable z-checking. The default value is FALSE. Z-checking is a culling technique in which a polygon representing the screen space of an entire group of polygons is tested against the z-buffer to discover whether any of the polygons should be drawn.

D3DRENDERSTATE_SUBPIXEL

TRUE to enable subpixel correction. The default value is FALSE.

D3DRENDERSTATE_SUBPIXELX

TRUE to enable correction in X only. The default value is FALSE.

D3DRENDERSTATE_STIPPLEDALPHA

TRUE to enable stippled alpha. The default value is FALSE.

D3DRENDERSTATE_FOGCOLOR

Value whose type is D3DCOLOR. The default value is 0.

D3DRENDERSTATE_FOGTABLEMODE

One of the members of the D3DFOGMODE enumerated type. The default value is D3DFOG_NONE.

D3DRENDERSTATE_FOGTABLESTART

Fog table start. This is the position at which fog effects begin for linear fog mode.

D3DRENDERSTATE_FOGTABLEEND

Fog table end. This is the position at which fog effects reach their maximum density for linear fog mode.

D3DRENDERSTATE_FOGTABLEDENSITY

Sets the maximum fog density for linear fog mode. This value can range from 0 to 1.

D3DRENDERSTATE_STIPPLEENABLE

Enables stippling in the device driver. When stippled alpha is enabled, it must override the current stipple pattern. When stippled alpha is disabled, the stipple pattern must be returned.

D3DRENDERSTATE_STIPPLEPATTERN00 through D3DRENDERSTATE_STIPPLEPATTERN31

Stipple pattern. Each render state applies to a separate line of the stipple pattern.

See Also

 D3DOPCODE, D3DSTATE


D3DSHADEMODE

Describes the supported shade mode for the D3DRENDERSTATE_SHADEMODE render state in the D3DRENDERSTATETYPE enumerated type.

typedef enum _D3DSHADEMODE {

    D3DSHADE_FLAT    = 1,

    D3DSHADE_GOURAUD = 2,

    D3DSHADE_PHONG   = 3,

} D3DSHADEMODE;

Values

D3DSHADE_FLAT

Flat shade mode. The color of the first vertex in the triangle is used to determine the color of the face.

D3DSHADE_GOURAUD

Gouraud shade mode. The color of the face is determined by a linear interpolation between all three of the triangle's vertices.

D3DSHADE_PHONG

Phong shade mode is not supported for DirectX 2.

See Also

 D3DRENDERSTATETYPE


D3DTEXTUREADDRESS

Describes the supported texture address for the D3DRENDERSTATE_TEXTUREADDRESS render state in the D3DRENDERSTATETYPE enumerated type.

typedef enum _D3DTEXTUREADDRESS {

    D3DTADDRESS_WRAP   = 1,

    D3DTADDRESS_MIRROR = 2,

    D3DTADDRESS_CLAMP  = 3,

} D3DTEXTUREADDRESS;

Values

D3DTADDRESS_WRAP

The D3DRENDERSTATE_WRAPU and D3DRENDERSTATE_WRAPV render states of the D3DRENDERSTATETYPE enumerated type are used. This is the default setting.

D3DTADDRESS_MIRROR

Equivalent to a tiling texture-addressing mode (that is, when neither D3DRENDERSTATE_WRAPU nor D3DRENDERSTATE_WRAPV is used) except that the texture is flipped at every integer junction. For u values between 0 and 1, for example, the texture is addressed normally, between 1 and 2 the texture is flipped (mirrored), between 2 and 3 the texture is normal again, and so on.

D3DTADDRESS_CLAMP

Texture coordinates greater than 1.0 are set to 1.0, and values less than 0.0 are set to 0.0.

Remarks

For more information about using the D3DRENDERSTATE_WRAPU and D3DRENDERSTATE_WRAPV render states, see Direct3D Texture Objects.

See Also

 D3DRENDERSTATETYPE


D3DTEXTUREBLEND

Defines the supported texture-blending modes. This enumerated type is used by the D3DRENDERSTATE_TEXTUREMAPBLEND render state in the D3DRENDERSTATETYPE enumerated type.

typedef enum _D3DTEXTUREBLEND {

    D3DTBLEND_DECAL         = 1,

    D3DTBLEND_MODULATE      = 2,

    D3DTBLEND_DECALALPHA    = 3,

    D3DTBLEND_MODULATEALPHA = 4,

    D3DTBLEND_DECALMASK     = 5,

    D3DTBLEND_MODULATEMASK  = 6,

    D3DTBLEND_COPY          = 7,

} D3DTEXTUREBLEND;

Values

D3DTBLEND_DECAL

Decal texture-blending mode is supported. In this mode, the RGB and alpha values of the texture replace the colors that would have been used with no texturing.

D3DTBLEND_MODULATE

Modulate texture-blending mode is supported. In this mode, the RGB values of the texture are multiplied with the RGB values that would have been used with no texturing. Any alpha values in the texture replace the alpha values in the colors that would have been used with no texturing.

D3DTBLEND_DECALALPHA

Decal-alpha texture-blending mode is supported. In this mode, the RGB and alpha values of the texture are blended with the colors that would have been used with no texturing, according to the following formula:

C = (1–At)Co + AtCt

In this formula, C stands for color, A for alpha, t for texture, and o for original object (before blending).

In the D3DTBLEND_DECALALPHA mode, any alpha values in the texture replace the alpha values in the colors that would have been used with no texturing.

D3DTBLEND_MODULATEALPHA

Modulate-alpha texture-blending mode is supported. In this mode, the RGB values of the texture are multiplied with the RGB values that would have been used with no texturing, and the alpha values of the texture are multiplied with the alpha values that would have been used with no texturing.

D3DTBLEND_DECALMASK

Decal-mask texture-blending mode is supported.

D3DTBLEND_MODULATEMASK

Modulate-mask texture-blending mode is supported.

D3DTBLEND_COPY

Copy texture-blending mode is supported.

Remarks

Modulation combines the effects of lighting and texturing. Because colors are specified as values between and including 0 and 1, modulating (multiplying) the texture and pre-existing colors together typically produces colors that are less bright than either source. The brightness of a color component is undiminished when one of the sources for that component is white (1). The simplest way to ensure that the colors of a texture do not change when the texture is applied to an object is to ensure that the object is white (1,1,1).


D3DTEXTUREFILTER

Defines the supported texture filter modes used by the D3DRENDERSTATE_TEXTUREMAG render state in the D3DRENDERSTATETYPE enumerated type.

typedef enum _D3DTEXTUREFILTER {

    D3DFILTER_NEAREST          = 1,

    D3DFILTER_LINEAR           = 2,

    D3DFILTER_MIPNEAREST       = 3,

    D3DFILTER_MIPLINEAR        = 4,

    D3DFILTER_LINEARMIPNEAREST = 5,

    D3DFILTER_LINEARMIPLINEAR  = 6,

} D3DTEXTUREFILTER;

Values

D3DFILTER_NEAREST

The texel with coordinates nearest to the desired pixel value is used. This applies to both zooming in and zooming out. If either zooming in or zooming out is supported, then both must be supported.

D3DFILTER_LINEAR

A weighted average of a 2-by-2 area of texels surrounding the desired pixel is used. This applies to both zooming in and zooming out. If either zooming in or zooming out is supported, then both must be supported.

D3DFILTER_MIPNEAREST

Similar to D3DFILTER_NEAREST, but uses the appropriate mipmap for texel selection.

D3DFILTER_MIPLINEAR

Similar to D3DFILTER_LINEAR, but uses the appropriate mipmap for texel selection.

D3DFILTER_LINEARMIPNEAREST

Similar to D3DFILTER_MIPNEAREST, but interpolates between the two nearest mipmaps.

D3DFILTER_LINEARMIPLINEAR

Similar to D3DFILTER_MIPLINEAR, but interpolates between the two nearest mipmaps.

Remarks


D3DTRANSFORMSTATETYPE

Describes the transformation state for the D3DOP_STATETRANSFORM opcode in the D3DOPCODE enumerated type. This enumerated type is part of the D3DSTATE structure.

typedef enum _D3DTRANSFORMSTATETYPE {

    D3DTRANSFORMSTATE_WORLD      = 1,

    D3DTRANSFORMSTATE_VIEW       = 2,

    D3DTRANSFORMSTATE_PROJECTION = 3,

} D3DTRANSFORMSTATETYPE;

Values

D3DTRANSFORMSTATE_WORLD

D3DTRANSFORMSTATE_VIEW

D3DTRANSFORMSTATE_PROJECTION

Define the matrices for the world, view, and projection transformations. The default values are NULL (the identity matrices).

See Also

 D3DOPCODE, D3DRENDERSTATETYPE


Other Types


D3DCOLOR

This type is the fundamental Direct3D color type.

typedef DWORD D3DCOLOR, D3DCOLOR, *LPD3DCOLOR;

See Also

 D3DRGB, D3DRGBA


D3DVALUE

This type is the fundamental Direct3D fractional data type.

typedef float D3DVALUE, *LPD3DVALUE;


Return Values

Errors are represented by negative values and cannot be combined. This table lists the values that can be returned by all Direct3D methods. See the individual method descriptions for lists of the values each can return.

D3D_OK

D3DERR_BADMAJORVERSION

D3DERR_BADMINORVERSION

D3DERR_EXECUTE_CLIPPED_FAILED

D3DERR_EXECUTE_CREATE_FAILED

D3DERR_EXECUTE_DESTROY_FAILED

D3DERR_EXECUTE_FAILED

D3DERR_EXECUTE_LOCK_FAILED

D3DERR_EXECUTE_LOCKED

D3DERR_EXECUTE_NOT_LOCKED

D3DERR_EXECUTE_UNLOCK_FAILED

D3DERR_LIGHT_SET_FAILED

D3DERR_MATERIAL_CREATE_FAILED

D3DERR_MATERIAL_DESTROY_FAILED

D3DERR_MATERIAL_GETDATA_FAILED

D3DERR_MATERIAL_SETDATA_FAILED

D3DERR_MATRIX_CREATE_FAILED

D3DERR_MATRIX_DESTROY_FAILED

D3DERR_MATRIX_GETDATA_FAILED

D3DERR_MATRIX_SETDATA_FAILED

D3DERR_SCENE_BEGIN_FAILED

D3DERR_SCENE_END_FAILED

D3DERR_SCENE_IN_SCENE

D3DERR_SCENE_NOT_IN_SCENE

D3DERR_SETVIEWPORTDATA_FAILED

D3DERR_TEXTURE_CREATE_FAILED

D3DERR_TEXTURE_DESTROY_FAILED

D3DERR_TEXTURE_GETSURF_FAILED

D3DERR_TEXTURE_LOAD_FAILED

D3DERR_TEXTURE_LOCK_FAILED

D3DERR_TEXTURE_LOCKED

D3DERR_TEXTURE_NO_SUPPORT

D3DERR_TEXTURE_NOT_LOCKED

D3DERR_TEXTURE_SWAP_FAILED

D3DERR_TEXTURE_UNLOCK_FAILED


DirectInput


Overview


Introduction to Joysticks

The Microsoft® DirectInput™ application programming interface (API) provides fast and consistent access to analog and digital joysticks. The DirectInput API maintains consistency with the joystick APIs of the Microsoft Win32® Software Development Kit (SDK), but has improved responsiveness and reliability by changing the device driver model. DirectInput device drivers use the registry to store settings for standard joysticks, calibration information for previously configured joysticks, and settings for OEM-supplied joysticks.

This section describes DirectInput functions, messages, and structures that support joysticks while it updates the Win32 joystick API documentation. The DirectInput APIs also apply to other ancillary input devices that track positions within an absolute coordinate system, such as touch screens, digitizing tablets, and light pens. Extended capabilities also provide support for rudder pedals, flight yokes, virtual-reality headgear, and other devices. Each device can use up to six axes of movement, a point-of-view hat, and 32 buttons.

You can design your application to use DirectInput functions to determine the capabilities of the joysticks and joystick drivers. Also, a joystick's position and button information can be processed by querying the joystick.


Joystick Capabilities

DirectInput services are loaded when the operating system is started. DirectInput supports analog and digital joysticks. Analog joysticks require real-time responsiveness and place a higher burden on the system than digital joysticks. DirectInput services can simultaneously monitor analog joysticks in a number of different configurations. These configurations range from two analog joysticks that track up to four axes of movement and use up to four buttons to four analog joysticks that track two axes of movement and use up to four buttons. In contrast, DirectInput services can support up to 16 digital joysticks, each with up to six axes of movement and up to 32 buttons.

Each axis of movement that a joystick tracks has a range of motion. The range of motion is the distance a joystick handle can move from its neutral, or resting, position to the farthest points from that resting position.

The joystick driver can support up to 16 minidrivers, with each minidriver supporting one joystick. You can retrieve the number of joysticks supported by a joystick driver by using the joyGetNumDevs function. This function returns an unsigned integer specifying the number of joysticks that the driver can support, or 0 if there is no joystick support.

Your application can determine if a joystick is attached to the computer by using the joyGetPosEx function. This function returns JOYERR_NOERROR if the specified device is attached, or JOYERR_UNPLUGGED otherwise.

Each joystick has several capabilities that are available to your application. You can retrieve the capabilities of a joystick by using the joyGetDevCaps function. This function fills a JOYCAPS structure with joystick capabilities, such as valid axes of movement for the joystick, minimum and maximum values for its coordinate system, and the number of buttons on the joystick.

Note

The return value of joyGetNumDevs does not indicate the number of joysticks attached to the system, but the number of joysticks that the system supports.


Joystick Calibration and Testing

Microsoft Windows® 95 provides a joystick application in the Control Panel to calibrate and test joysticks, including range of motion and buttons. This application lets the user choose from a list of joysticks, including the following:

•	Generic joystick configurations

•	OEM joysticks

•	Custom joysticks

The application allows the calibration of up to six axes of motion, 32 buttons, and a point-of-view hat for each joystick. Calibration information is stored in the registry, so the user can switch from one joystick to another without recalibrating each one every time it is used. Once the user has calibrated or selected a new joystick, the calibration application updates the registry with the selected joystick and calibration information, and notifies the joystick driver accordingly.

Additionally, this application can notify a particular joystick of changes to the registry that affect the joystick by using the joyConfigChanged function.


Joystick Position

You can query a joystick for position and button information by using the joyGetPosEx function. This function reports position information returned by the older joystick functions of the Win32 API, including position coordinates for the x-, y-, and z-axes. It also reports state information for up to four buttons. The joyGetPosEx function also provides access to the following information:

•	Status of fourth, fifth, and sixth axes (r, u, and v)

•	Rudder information

•	Point-of-view hat

•	State information for up to 32 buttons

•	Uncalibrated (raw) joystick data

•	Scaled data for a defined range of values

•	Centered scaled data

•	Scaled data that includes a dead zone around the neutral joystick position


Reference


Joystick Groups

This section describes the functions and structures associated with joysticks. The elements are grouped as follows:

Device capabilities	JOYCAPS
	joyConfigChanged
	joyGetDevCaps
	joyGetNumDevs
Querying a joystick	joyGetPosEx
	JOYINFOEX


Functions


joyConfigChanged

Notifies the joystick driver that the registry contains new joystick settings.

MMRESULT joyConfigChanged(
DWORD dwFlags
);

Parameters

dwFlags

This parameter is reserved and must be set to 0.

Return Values

Returns JOYERR_NOERROR if successful, or one of the following error values otherwise:

JOYERR_NOCANDO	JOYERR_REGISTRYNOTVALID
Remarks

The joystick calibration property sheet in the control panel calls this function when the user calibrates or recalibrates a joystick, or when a different joystick device is selected.

If your application is designed to customize joystick performance, such as an OEM joystick calibration application, you can use this function to notify the joystick driver that the JOYSTICK_USER values in the registry for the currently selected joystick have changed. The JOYSTICK_USER values are located in the HKEY_LOCAL_MACHINE hive of the registry.


joyGetDevCaps

Queries a joystick to determine its capabilities.

MMRESULT joyGetDevCaps(
UINT uJoyID,
LPJOYCAPS pjc,
UINT cbjc
);

Parameters

uJoyID

Identifier of the joystick, either JOYSTICKID1 or JOYSTICKID2, to be queried.

pjc

Address for a JOYCAPS structure to contain the capabilities of the joystick.

cbjc

Size of the JOYCAPS structure, in bytes.

Return Values

Returns JOYERR_NOERROR if successful, or one of the following error values otherwise:

MMSYSERR_INVALPARAM	MMSYSERR_NODRIVER
Remarks

You can use the joyGetNumDevs function to determine the number of joystick devices supported by the driver.

See Also

 JOYCAPS, joyGetNumDevs


joyGetNumDevs

Queries the joystick driver for the number of joysticks it supports.

UINT joyGetNumDevs(VOID);

Parameters

Return Values

Returns the number of joysticks supported by the driver, or 0 if no driver is present.

Remarks

The joyGetPosEx function is used to determine whether a given joystick is physically attached to the computer.

See Also

 joyGetDevCaps


joyGetPosEx

Queries a joystick for its position and button status.

MMRESULT joyGetPosEx(
UINT uJoyID,
LPJOYINFOEX pji
);

Parameters

uJoyID

Identifier of the joystick to be queried.

pji

Address for a JOYINFOEX structure that contains extended position information and button status of the joystick.

Return Values

Returns JOYERR_NOERROR if successful, or one of the following error values otherwise:

JOYERR_UNPLUGGED	MMSYSERR_BADDEVICEID
MMSYSERR_INVALPARAM	MMSYSERR_NODRIVER
Remarks

Before calling this function, your application must identify the items to query by setting one or more flags in the dwFlags member of the JOYINFOEX structure.

This function provides access to extended devices, such as rudder pedals, point-of-view hats, devices with a large number of buttons, and coordinate systems using up to six axes.

See Also

 JOYINFOEX


Structures


JOYCAPS

Contains information about the specified joystick's capabilities.

typedef struct {

    WORD wMid;

    WORD wPid;

    CHAR szPname[MAXPNAMELEN];

    UINT wXmin;

    UINT wXmax;

    UINT wYmin;

    UINT wYmax;

    UINT wZmin;

    UINT wZmax;

    UINT wNumButtons;

    UINT wPeriodMin;

    UINT wPeriodMax;

\\  The following members are not in previous versions

\\  of Windows.

    UINT wRmin;

    UINT wRmax;

    UINT wUmin;

    UINT wUmax;

    UINT wVmin;

    UINT wVmax;

    UINT wCaps;

    UINT wMaxAxes;

    UINT wNumAxes;

    UINT wMaxButtons;

    CHAR szRegKey[MAXPNAMELEN];

    CHAR szOEMVxD[MAXOEMVXD];

} JOYCAPS;

Members

wMid

Manufacturer identifier.

wPid

Product identifier.

szPname

Null-terminated string that contains the joystick product name.

wXmin and #wXmax

Minimum and maximum x-coordinate values.

wYmin and #wYmax

Minimum and maximum y-coordinate values.

wZmin and #wZmax

Minimum and maximum z-coordinate values.

wNumButtons

Number of joystick buttons.

wPeriodMin and #wPeriodMax

Minimum and maximum polling frequencies supported once an application has captured a joystick.

wRmin and #wRmax

Minimum and maximum rudder values. The rudder is the fourth axis of movement.

wUmin and #wUmax

Minimum and maximum u-coordinate (fifth axis) values.

wVmin and #wVmax

Minimum and maximum v-coordinate (sixth axis) values.

wCaps

Joystick capabilities. The following flags define individual capabilities that a joystick might have:

JOYCAPS_HASPOV

	The joystick has point-of-view information.
JOYCAPS_HASR

	The joystick has rudder (fourth axis) information.
JOYCAPS_HASU

	The joystick has u-coordinate (fifth axis) information.
JOYCAPS_HASV

	The joystick has v-coordinate (sixth axis) information.
JOYCAPS_HASZ

	The joystick has z-coordinate information.
JOYCAPS_POV4DIR

	The joystick point-of-view supports discrete values (centered, forward, backward, left, and right).
JOYCAPS_POVCTS

	The joystick point-of-view supports continuous degree bearings.
wMaxAxes

Maximum number of axes supported by the joystick.

wNumAxes

Number of axes currently in use by the joystick.

wMaxButtons

Maximum number of buttons supported by the joystick.

szRegKey

Null-terminated string that contains the registry key for the joystick.

szOEMVxD

Null-terminated string that identifies the joystick driver OEM.

See Also

 joyGetDevCaps


JOYINFOEX

Contains extended information about the joystick position, the point-of-view position, and the button state.

typedef struct joyinfoex_tag {

    DWORD dwSize;

    DWORD dwFlags;

    DWORD dwXpos;

    DWORD dwYpos;

    DWORD dwZpos;

    DWORD dwRpos;

    DWORD dwUpos;

    DWORD dwVpos;

    DWORD dwButtons;

    DWORD dwButtonNumber;

    DWORD dwPOV;

    DWORD dwReserved1;

    DWORD dwReserved2;

} JOYINFOEX;

Members

dwSize

Size of this structure, in bytes.

dwFlags

Flags that indicate if information returned in this structure is valid. Members that do not contain valid information are set to 0. The following flags are defined:

JOY_RETURNALL

	Equivalent to setting all of the JOY_RETURN values except JOY_RETURNRAWDATA.
JOY_RETURNBUTTONS

	The dwButtons member contains valid information about the state of each joystick button.
JOY_RETURNCENTERED

	Centers the joystick neutral position to the middle value of each axis of movement.
JOY_RETURNPOV

	The dwPOV member contains valid information about the point-of-view control, which is expressed in discrete units.
JOY_RETURNPOVCTS

	The dwPOV member contains valid information about the point-of-view control expressed in continuous, one-hundredth of a degree units.
JOY_RETURNR

	The dwRpos member contains valid rudder pedal information. This indicates the existence of a fourth axis.
JOY_RETURNRAWDATA

	Indicates that uncalibrated joystick readings are stored in this structure.
JOY_RETURNU

	The dwUpos member contains valid data for a fifth axis of the joystick, if such an axis is available. 0 is returned otherwise.
JOY_RETURNV

	The dwVpos member contains valid data for a sixth axis of the joystick, if such an axis is available. 0 is returned otherwise.
JOY_RETURNX

	The dwXpos member contains valid data for the x-coordinate of the joystick.
JOY_RETURNY

	The dwYpos member contains valid data for the y-coordinate of the joystick.
JOY_RETURNZ

	The dwZpos member contains valid data for the z-coordinate of the joystick.
JOY_USEDEADZONE

	Expands the range for the neutral position of the joystick and calls this range the dead zone. The joystick driver returns a constant value for all positions in the dead zone.
The following flags provide data to calibrate a joystick and are intended for custom calibration applications:

JOY_CAL_READ3

	Reads the x-, y-, and z-coordinates, then stores the raw values in the dwXpos, dwYpos, and dwZpos members, respectively.
JOY_CAL_READ4

	Reads the rudder information and the x-, y-, and z-coordinates, then stores the raw values in the dwRpos, dwXpos, dwYpos, and dwZpos members, respectively.
JOY_CAL_READ5

	Reads the rudder information and the x-, y-, z-, and u-coordinates, then stores the raw values in the dwRpos, dwXpos, dwYpos, dwZpos, and dwUpos members, respectively.
JOY_CAL_READ6

	Reads the raw v-axis data if a joystick minidriver is present to provide the information. Returns 0 otherwise.
JOY_CAL_READALWAYS

	Reads the joystick port even if the driver does not detect a device.
JOY_CAL_READRONLY

	Reads the rudder information if a joystick minidriver is present to provide the data, then stores the raw value in the dwRpos member. Returns 0 otherwise.
JOY_CAL_READUONLY

	Reads the u-coordinate if a joystick minidriver is present to provide the data, then stores the raw value in the dwUpos member. Returns 0 otherwise.
JOY_CAL_READVONLY

	Reads the v-coordinate if a joystick minidriver is present to provide the data, then stores the raw value in the dwVpos member. Returns 0 otherwise.
JOY_CAL_READXONLY

	Reads the x-coordinate and stores the raw value in the dwXpos member.
JOY_CAL_READXYONLY

	Reads the x- and y-coordinates and stores the raw values in the dwXpos and dwYpos members, respectively.
JOY_CAL_READYONLY

	Reads the y-coordinate and stores the raw value in the dwYpos member.
JOY_CAL_READZONLY

	Reads the z-coordinate and stores the raw value in the dwZpos member.
dwXpos, #dwYpos, #dwZpos

Current x-coordinate, y-coordinate, and z-coordinate positions, respectively.

dwRpos

Current position of the rudder or fourth joystick axis.

dwUpos, #dwVpos

Current 5th axis and 6th axis positions, respectively.

dwButtons

Current state of the 32 joystick buttons. The value of this member can be set to any combination of JOY_BUTTONn flags, where n is a value ranging from one to 32. Each value corresponds to the button that is pressed.

dwButtonNumber

Current button number that is pressed.

dwPOV

Current position of the point-of-view control. Values for this member range from 0 to 35,900. These values represent each view's angle, in degrees, multiplied by 100.

dwReserved1, #dwReserved2

Reserved, do not use.

Remarks

The value of the dwSize member is also used to identify the version number for the structure when it is passed to the joyGetPosEx function.

Most devices with a point-of-view control have only five positions. When the JOY_RETURNPOV flag is set, these positions are reported by using the following JOY_POV constants.

Point-of-view positions	Description
JOY_POVBACKWARD	Point-of-view hat is pressed backward. The value 18,000 represents an orientation of 180.00 degrees.
JOY_POVCENTERED	Point-of-view hat is in the neutral position. The value -1 means the point-of-view hat has no angle to report.
JOY_POVFORWARD	Point-of-view hat is pressed forward. The value 0 represents an orientation of 0.00 degrees.
JOY_POVLEFT	Point-of-view hat is being pressed to the left. The value 27,000 represents an orientation of 270.00 degrees.
JOY_POVRIGHT	Point-of-view hat is pressed to the right. The value 9,000 represents an orientation of 90.00 degrees.
The default Windows 95 joystick driver currently supports these five discrete directions. If your application can accept only the defined point-of-view values, it must use the JOY_RETURNPOV flag. If your application can accept other degree readings, it should use the JOY_RETURNPOVCTS flag to obtain continuous data if it is available. The JOY_RETURNPOVCTS flag also supports the JOY_POV constants used with the JOY_RETURNPOV flag.

See Also

 joyGetPosEx


Return Values

Errors are represented by negative values and cannot be combined. This table lists the failures that can be returned by all DirectInput functions. For a list of the error codes each function is capable of returning, see the individual function descriptions.

JOYERR_NOCANDO

	The joystick driver cannot update the device information from the registry.
JOYERR_NOERROR

	The request completed successfully.
JOYERR_REGISTRYNOTVALID

	One or more registry joystick entries contain invalid data.
JOYERR_UNPLUGGED

	The specified joystick is not connected to the computer.
MMSYSERR_BADDEVICEID

	The specified joystick identifier is invalid.
MMSYSERR_INVALPARAM

	An invalid parameter was passed.
MMSYSERR_NODRIVER

	The joystick driver is not present.


DirectSetup


Overview


About DirectSetup

DirectSetup is a simple application programming interface (API) that provides you with a one-call installation for the DirectX™ 2 components. This is more than a convenience; DirectX 2 is a complex product and its installation is an involved task. You should not attempt a manual installation of DirectX 2.


Using DirectSetup

Although there are two APIs provided by DirectSetup, only one is of use to you as an application developer. The other is designed for those who plan to install their own DirectX device drivers, and is not addressed in this document.

Although DirectSetup allows you to install a single DirectX component, such as DirectDraw, this is not recommended since the space saving advantages are minimal due to the interdependent design of DirectX components.


Reference


Functions

There are only two functions provided by DirectSetup, and only one of them, DirectXSetup, is of interest to you as an application developer. The other, DirectXDeviceSetup, is intended for use by manufacturers who want to install their own DirectX device drivers, and is not addressed in this document. The declarations for DirectSetup can be found in Dsetup.h.


DirectXSetup

Installs one or more DirectX components.

int WINAPI DirectXSetup(
HWND hwnd,
LPSTR root_path,
DWORD dwflags
);

Parameters

hwnd

Parent HWND for the setup dialog boxes.

root_path

Address of a string containing the root path of the DirectX component files.

dwflags

One or more flags used to indicate which DirectX components should be installed. A full installation is recommended.

DSETUP_D3D	Installs Direct3D.
DSETUP_DDRAW	Installs DirectDraw.
DSETUP_DIRECTX	Installs all DirectX components.
DSETUP_DPLAY	Installs DirectPlay.
DSETUP_DSOUND	Installs DirectSound.
DSETUP_REINSTALL	Installs even if the existing components are the same version.
Return Values

Returns one of the following values:

SUCCESS

	A 0 is returned if the setup was successful and no reboot is required.
	A 1 is returned if the setup was successful and a reboot is required.
DSETUPERR_BADSOURCESIZE

	A file's size could not be verified or was incorrect.
DSETUPERR_BADSOURCETIME

	A file's date and time could not be verified or was incorrect.
DSETUPERR_BADWINDOWSVERSION

	The Windows version on your system is not supported by DirectX.
DSETUPERR_CANTFINDDIR

	The setup program could not find the working directory.
DSETUPERR_CANTFINDINF

	A required .inf file could not be found.
DSETUPERR_INTERNAL

	An internal error occurred.
DSETUPERR_NOCOPY

	A file's version could not be verified or was incorrect. If the DSETUP_REINSTALL flag is specified, equal versions will be installed.
DSETUPERR_OUTOFDISKSPACE

	The setup program ran out of disk space during installation.
DSETUPERR_SOURCEFILENOTFOUND

	One of the required source files could not be found.


AutoPlay


Overview


About AutoPlay

Microsoft® AutoPlay is a feature of the Microsoft Windows® operating system. When you insert a CD containing AutoPlay into a CD-ROM drive on computer running Windows, AutoPlay automatically starts an application on the CD that installs, configures, and runs the selected product.

You can use AutoPlay to install and run CD-ROM applications that run in Windows, whether the application is based on the MS-DOS® operating system, Windows 3.0, Windows 3.1, Windows 95, or Windows NT. If you want your CD-ROM product to display the Microsoft Windows 95 logo, it must be enabled for AutoPlay.

Note

MS-DOS, Windows versions 3.0 and higher, and Windows NT versions 3.51 and earlier do not support AutoPlay. Adding AutoPlay to a CD, however, does not hinder or alter user interaction when the CD-ROM is installed on a computer running one of these operating systems.


How AutoPlay Works

The implementation of AutoPlay relies on the following three items:

•	A set of 32-bit CD-ROM device drivers for Windows 95 and Windows NT. These device drivers detect when a user inserts a CD into a CD-ROM drive; device drivers for MS-DOS or previous versions of Windows do not.

•	An Autorun.inf file on the CD. When you insert a CD into a CD-ROM drive on a computer running Windows 95 or Windows NT, the system immediately checks whether the CD has a personal computer file system. If it does, the system checks for a file named Autorun.inf. This file specifies the application that AutoPlay runs, and can contain other information as well. For more information about this file, see The Autorun.inf File.

•	A startup application on the CD. Although you can start any application on the CD by specifying it in the Autorun.inf file, typically the application performs a startup or installation function. By including your own startup application, you can control the install, uninstall, and run processes for your product.


The Autorun.inf File

The Autorun.inf file is a text file located in the root directory of the CD. This file contains the name of the startup application on the CD (the application that runs automatically when the CD is inserted in the drive), and the icon that you want to represent the Autoplay-enabled CD in the Windows user interface. The Autorun.inf file can also contain any optional menu commands that you want added to the shortcut menu that is displayed when the user selects the CD-ROM icon and right-clicks the mouse.

At a minimum, an Autorun.inf file contains three lines of text and identifies the startup application and the icon, as shown in the following example:

[autorun]

open=filename.exe

icon=filename.ico

The [autorun] section identifies the lines that follow it as AutoPlay commands. An [autorun] section is required in every Autorun.inf file. The open command specifies the path and file name of the startup application, and the icon command specifies the file that contains the icon information.

The Autorun.inf file can also contain architecture-specific sections for Windows NT 4.0 running on RISC processors. For each type of processor architecture, add a section to the Autorun.inf file that contains the file name of the startup application you want to run for that architecture. For x86 architectures, use the standard [autorun] line. Use [autorun.mips] to run an application on MIPS architecture, [autorun.alpha] for applications on the Alpha architecture, and [autorun.ppc] for the PowerPC architecture. The following example shows how to create an Autorun.inf file that runs different startup applications depending on the computer architecture:

[autorun]

open=filename.exe

icon=filename.ico

[autorun.mips]

open=filenam2.exe

icon=filename.ico

[autorun.alpha]

open=filenam3.exe

icon=filename.ico

[autorun.ppc]

open=filenam4.exe

icon=filename.ico

The shell checks for a platform-specific section first. If it does not find one, it uses the information in the [autorun] section. After the shell finds a section, it ignores all of the other sections, so make sure each section contains all the information for that section.


Tips for Writing AutoPlay Applications


Opening a Startup Application

Users should receive feedback soon after they insert an AutoPlay CD into the drive. You can accomplish this by specifying a small startup application that loads very quickly in the open command of the Autorun.inf file. The application should also clearly identify the title it will play, and it should provide an easy way to cancel the operation.


Loading in the Background

Typically, users click OK when the startup application displays a dialog box asking them if they would like to proceed. Take advantage of this time by starting another thread that begins loading the startup application in the background before the user clicks OK. This significantly reduces the time users perceive it takes to load your application.


Conserving Hard Disk Space

Hard disk space is a limited resource. Here are a few tips that conserve hard disk usage:

•	Run your application from the CD-ROM directly, without running any installation program.

•	If your application needs to use the hard drive, install only the functional components necessary to run the application. In addition, provide a way to uninstall these components from the hard disk. For more information about uninstalling an application, see the documentation included with the Microsoft Win32 Software Development Kit (SDK).

•	If your application needs to use the drive as a data cache, provide the user with options in the startup application that will discard the cached data when the user quits the title or game.


Using the Registry

The registry is a feature of Windows that supersedes the initialization (.ini) and application configuration files. For more information about registry manipulation application programming interfaces (APIs), see the documentation included with the Microsoft Win32 SDK.

If your product records and uses initialization information, you can use the registry to store and retrieve this information. Your startup application can use the information in the registry to determine whether the product needs to be installed. If there are no registry entries for your product—which means your product is being used for the first time—you could display a dialog box that lists the setup options. If your product is listed in the registry—which means it has already been installed—you could display a dialog box with just the OK and Cancel buttons.

By changing the system registry, you can enable a computer to read the Autorun.inf file from a floppy disk. This feature of implementing AutoPlay on a floppy disk is provided only to help you debug your Autorun.inf files before you burn the CD. AutoPlay is intended for public distribution on CD only. To implement AutoPlay on a floppy disk, carry out the following procedure:

1	In Registry Editor (Regedit.exe), search for the string "auto". The results of the search should be in the HKEY_CURRENT_USER key under the following subkey:

\Software\Microsoft\Windows\CurrentVersion\Policies \Explorer

2	Using your right mouse button, click the NoDriveTypeAutoRun value, and then click Modify.

3	Change the data of the NoDriveTypeAutoRun value from 0000 95 00 00 00 to 0000 91 00 00 00, and then click OK. This enables AutoPlay on any drive; however, you must select AutoPlay when working with a floppy disk to run the startup application. You can double-click the floppy disk icon, or select the floppy disk icon and access the shortcut menu to start AutoPlay.

4	After you complete your tests of Autorun.inf, reset the value of NoDriveTypeAutoRun to 0000 95 00 00 00.

Important

Because implementing AutoPlay on a floppy disk provides an easy way to spread computer viruses, it is appropriate to suspect that any publicly distributed floppy disk that contains Autorun.inf files is contaminated.


Setting the NoDriveTypeAutoRun Value

The NoDriveTypeAutoRun value in the registry is a four-byte binary data value of the type REG_BINARY. The first byte of this value represents different kinds of drives that can be excluded from working with AutoPlay. The initial setting for this byte is 0x95, which excludes the unrecognized type drive, DRIVE_UNKNOWN, DRIVE_REMOVEABLE, and DRIVE_FIXED media types from being used with AutoPlay. You can enable a floppy disk drive for AutoPlay by resetting bit 2 to zero, or by specifying the value 0x91 to maintain the rest of the initial settings. A table identifying the bits, bitmask constants, and a brief description of the drives follows:

Bit number	Bitmask constant	Description
0 (low-order bit)	DRIVE_UNKNOWN	Drive type not identified.
1	DRIVE_NO_ROOT_DIR	Root directory does not exist.
2	DRIVE_REMOVEABLE	Disk can be removed from drive (a floppy disk).
3	DRIVE_FIXED	Disk cannot be removed from drive (a hard disk).
4	DRIVE_REMOTE	Network drive.
5	DRIVE_CDROM	CD-ROM drive.
6	DRIVE_RAMDISK	RAM disk.
7 (high-order bit)		Reserved for future use.
Note

For Windows NT, you must restart Windows Explorer before any changes go into effect.


Suppressing AutoPlay

You can manually prevent the Autorun.inf file on a CD from being parsed and carried out by holding down the SHIFT key when you insert the CD. For users of Windows NT version 4.0 and Windows 95 with Internet Explorer version 4.0, however, you can suppress AutoPlay automatically. You might want to do this if your application has a setup program that requires the user to insert a CD that contains an Autorun.inf file. In this case, you do not want the AutoPlay feature to begin running an application while your setup program is running. To suppress AutoPlay if your setup application is in the foreground window, add the following code to your setup initialization code:

uMessage - RegisterWindowMessage(TEXT("QueryCancelAutoPlay"));

Then, add the following code to your setup window procedure:

if(msg == uMessage)

{

    // return 1 to cancel AutoPlay

    // return 0 to allow AutoPlay

    return 1L;

}


AutoPlay for MS-DOS-Based Applications

You can also use AutoPlay to install, configure, and run MS-DOS-based applications in a Windows MS-DOS session. You can configure each MS-DOS-based application with its own unique icon, Config.sys file, and Autoexec.bat file.

Windows creates correct configuration files for an MS-DOS-based application. The startup application can then cause the MS-DOS-based application to start within a window. It can even cause Windows to effectively restart the application if necessary and immediately return to Windows when the application closes.


Reference


Commands


defaulticon

Specifies an absolute path on the CD to the file that contains the information for the icon that represents the AutoPlay-enabled CD in the Windows user interface.

defaulticon=path\iconname.ico

Parameters

path\iconname.ico

Absolute path and file name of the file containing the icon information. You can also specify a .bmp, .exe, or .dll file. If a file contains more than one icon, specify the resource number (index) of the icon in the file to use.

Remarks

If both the icon and defaulticon commands are present in an Autorun.inf file, AutoPlay uses the icon specified in the defaulticon command.

If the drive does not contain an AutoPlay-enabled CD, the system uses a default icon in its place.

See Also

 icon


icon

Specifies a file that contains the information for the icon that represents the AutoPlay-enabled CD in the Windows user interface. The file name specified with this command must be located in the same directory as the file name specified by the open command.

icon=filename.ico

Parameters

filename.ico

Name of the file containing the icon. You can also specify a .bmp, .exe, or .dll file. If a file contains more than one icon, specify the resource number (index) of the icon in the file to use.

Remarks

If the drive does not contain an AutoPlay-enabled CD, the system uses a default icon in its place.

The following example specifies the second icon in a file to represent a CD. The first icon's index is set to zero.

icon=filename.exe 1

See Also

 defaulticon


open

Specifies the path and file name of the application that AutoPlay runs when you insert the CD into a CD-ROM drive.

open=dir\filename.exe

Parameters

dir\filename.exe

Path and file name of any executable file to run or document to open when the CD is inserted. If no path is specified, Windows looks for the file in the root of the CD. You can specify a relative path to locate the file in a subdirectory.

If the file is a document, Windows starts the application associated with the specified document.

Remarks

You can also include command-line parameters that AutoPlay passes to the program upon execution.

Use this command to open a startup application that provides instant feedback for the user. For more information about startup applications, see Opening a Startup Application.


shell

Changes the default entry of the shortcut menu to the specified custom command.

shell=verb

Parameters

verb

Abbreviated form of a custom command. The custom command must be defined in the Autorun.inf file.

Remarks

AutoPlay is the default menu item defined for any AutoPlay-enabled disk.

When the user double-clicks on the icon for your CD, the command associated with the verb is carried out.

See Also

 shell\verb


shell\verb

Specifies a custom command listed in the shortcut menu for the icon. The first line identifies the executable file that performs the command. The second line specifies the custom entry of the shortcut menu.

shell\verb\command=filename.exe
shell\verb=Menu Item Name

Parameters

verb

Abbreviated form of the command. This parameter associates a command with the executable file name and the menu item. It must not contain embedded spaces.

You will not see verb unless Menu Item Name is omitted from Autorun.inf.

filename.exe

File name of the application that performs the custom command.

Menu Item Name

Menu item text that can contain mixed case letters and spaces. You can also set an accelerator for the menu item by preceding one of the letters in the item with an ampersand.

Remarks

When you point to an icon in the Windows user interface and click the right mouse button, Windows presents a shortcut menu for that icon. If an Autorun.inf file is present on a CD, Windows automatically adds AutoPlay to the shortcut menu, and sets it as the default behavior. Double-clicking the icon will carry out whatever is specified in the open command.

To add the command ReadMe to the shortcut menu for your product, include the following in the Autorun.inf file:

shell\readit\command=notepad abc\readme.txt

shell\readit=Read &Me

See Also

 shell, open


RasAdminAcceptNewConnection
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RasAdminConnectionHangupNotification
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RasAdminGetIpAddressForUser
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RasAdminReleaseIpAddress
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RasSecurityDialogBegin
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	rasshost.h
Unicode	No
Platform Notes	None


RasSecurityDialogEnd
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	rasshost.h
Unicode	No
Platform Notes	None


WinTrustProviderClientInitialize
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wintrust.h
Unicode	Unicode only
Platform Notes	None


WinTrustProviderServerInitialize
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wintrust.h
Unicode	Unicode only
Platform Notes	None


WinTrustSipInitialize
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wintrust.h
Unicode	No
Platform Notes	None


WinTrustProviderClientUnload
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wintrust.h
Unicode	No
Platform Notes	None


WinTrustProviderPing
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wintrust.h
Unicode	Unicode only
Platform Notes	None


WinTrustProviderServerUnload
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wintrust.h
Unicode	No
Platform Notes	None


WinTrustProviderSubmitCertificate
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wintrust.h
Unicode	No
Platform Notes	None


WinTrustProviderVerifyTrust
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wintrust.h
Unicode	No
Platform Notes	None


WinTrustSubjectCheckContentInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wintrust.h
Unicode	No
Platform Notes	None


WinTrustSubjectEnumCertificates
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wintrust.h
Unicode	No
Platform Notes	None


WinTrustSubjectGetCertHeader
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wintrust.h
Unicode	No
Platform Notes	None


WinTrustSubjectGetCertificate
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wintrust.h
Unicode	No
Platform Notes	None


WinTrustSubjectGetName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wintrust.h
Unicode	Unicode only
Platform Notes	None


AbortProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	wingdi.h
Unicode	No
Platform Notes	ABORTPROC


acmDriverEnumCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	msacm.h
Unicode	No
Platform Notes	ACMDRIVERENUMCB


acmDriverProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	msacm.h
Unicode	No
Platform Notes	ACMDRIVERPROC


acmFilterChooseHookProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	msacm.h
Unicode	WinNT
Platform Notes	ACMFILTERCHOOSEHOOKPROC


acmFilterEnumCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	msacm.h
Unicode	WinNT
Platform Notes	ACMFILTERENUMCB


acmFilterTagEnumCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	msacm.h
Unicode	WinNT
Platform Notes	ACMFILTERTAGENUMCB


acmFormatChooseHookProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	msacm.h
Unicode	WinNT
Platform Notes	ACMFORMATCHOOSEHOOKPROC


acmFormatEnumCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	msacm.h
Unicode	WinNT
Platform Notes	ACMFORMATENUMCB


acmFormatTagEnumCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	msacm.h
Unicode	WinNT
Platform Notes	ACMFORMATTAGENUMCB


acmStreamConvertCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


AddPropSheetPageProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	prsht.h
Unicode	No
Platform Notes	LPFNADDPROPSHEETPAGEPROC


BrowseCallbackProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	shlobj.h
Unicode	No
Platform Notes	BFFCALLBACK


Callback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	ddraw.h
Unicode	No
Platform Notes	None


CALLERRELEASE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mapiutil.h
Unicode	No
Platform Notes	None


CallWndProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	HOOKPROC


CallWndRetProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	HOOKPROC


capControllCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


capErrorCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


capStatusCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


capVideoStreamCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


capWaveStreamCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


capYieldCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


CBTProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	HOOKPROC


CCHookProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	commdlg.h
Unicode	No
Platform Notes	LPCCHOOKPROC


CFHookProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	commdlg.h
Unicode	No
Platform Notes	LPCFHOOKPROC


CopyProgressRoutine
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


CplApplet
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	cpl.h
Unicode	No
Platform Notes	APPLET_PROC


D3DENUMDEVICESCALLBACK
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DENUMTEXTUREFORMATSCALLBACK
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DRMDEVICEPALETTECALLBACK
Windows NT	No
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMFRAMEMOVECALLBACK
Windows NT	No
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMFREEFUNCTION
Windows NT	No
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMLOADCALLBACK
Windows NT	No
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMLOADTEXTURECALLBACK
Windows NT	No
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMMALLOCFUNCTION
Windows NT	No
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMOBJECTCALLBACK
Windows NT	No
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMREALLOCFUNCTION
Windows NT	No
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMUPDATECALLBACK
Windows NT	No
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMUSERVISUALCALLBACK
Windows NT	No
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMWRAPCALLBACK
Windows NT	No
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DVALIDATECALLBACK
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


DdeCallback
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	ddeml.h
Unicode	No
Platform Notes	PFNCALLBACK


DebugProc
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	HOOKPROC


DialogProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	DLGPROC


DISMISSMODELESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mapidefs.h
Unicode	No
Platform Notes	None


DrawStateProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	DRAWSTATEPROC


DriverProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mmsystem.h
Unicode	No
Platform Notes	DRIVERPROC


DSEnumCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	dsound.h
Unicode	No
Platform Notes	None


EditWordBreakProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	winuser.h
Unicode	WinNT
Platform Notes	EDITWORDBREAKPROC


EditWordBreakProcEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


EnhMetaFileProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	wingdi.h
Unicode	No
Platform Notes	ENHMFENUMPROC


EnumCalendarInfoProc
Windows NT	Yes
Win95	No
Win32s	Yes
Import Library	user-defined
Header File	winnls.h
Unicode	WinNT
Platform Notes	CALINFO_ENUMPROC


EnumCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	ddraw.h
Unicode	No
Platform Notes	None


EnumChildProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	WNDENUMPROC


EnumCodePagesProc
Windows NT	Yes
Win95	No
Win32s	Yes
Import Library	user-defined
Header File	winnls.h
Unicode	WinNT
Platform Notes	CODEPAGE_ENUMPROC


EnumDateFormatsProc
Windows NT	Yes
Win95	No
Win32s	Yes
Import Library	user-defined
Header File	winnls.h
Unicode	WinNT
Platform Notes	DATEFMT_ENUMPROC


EnumDesktopProc
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	winuser.h
Unicode	WinNT
Platform Notes	DESKTOPENUMPROC


EnumDPCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	dplay.h
Unicode	No
Platform Notes	None


EnumFontFamExProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	wingdi.h
Unicode	No
Platform Notes	FONTENUMPROC


EnumFontFamProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	wingdi.h
Unicode	No
Platform Notes	FONTENUMPROC


EnumFontsProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	wingdi.h
Unicode	No
Platform Notes	FONTENUMPROC


EnumICMProfilesProc
Windows NT	No
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	wingdi.h
Unicode	No
Platform Notes	ICMENUMPROC


EnumLocalesProc
Windows NT	Yes
Win95	No
Win32s	Yes
Import Library	user-defined
Header File	winnls.h
Unicode	WinNT
Platform Notes	LOCALE_ENUMPROC


EnumMetaFileProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	wingdi.h
Unicode	No
Platform Notes	MFENUMPROC


EnumModesCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	ddraw.h
Unicode	No
Platform Notes	None


EnumObjectsProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	wingdi.h
Unicode	No
Platform Notes	GOBJENUMPROC


EnumPlayersCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	dplay.h
Unicode	No
Platform Notes	None


EnumRegisterWordProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	imm.h
Unicode	WinNT
Platform Notes	REGISTERWORDENUMPROC


EnumResLangProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winbase.h
Unicode	No
Platform Notes	ENUMRESLANGPROC


EnumResNameProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winbase.h
Unicode	No
Platform Notes	ENUMRESNAMEPROC


EnumResTypeProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winbase.h
Unicode	No
Platform Notes	ENUMRESTYPEPROC


EnumSessionsCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	dplay.h
Unicode	No
Platform Notes	None


EnumSurfacesCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	ddraw.h
Unicode	No
Platform Notes	None


EnumThreadWndProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	WNDENUMPROC


EnumTimeFormatsProc
Windows NT	Yes
Win95	No
Win32s	Yes
Import Library	user-defined
Header File	winnls.h
Unicode	WinNT
Platform Notes	TIMEFMT_ENUMPROC


EnumWindowsProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	WNDENUMPROC


EnumWindowStationProc
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	winuser.h
Unicode	WinNT
Platform Notes	WINSTAENUMPROC


ExtensionPropSheetPageProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	prsht.h
Unicode	No
Platform Notes	LPFNADDPROPSHEETPAGES


FileIOCompletionRoutine
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


FMExtensionProc
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	wfext.h
Unicode	WinNT
Platform Notes	Windows 95: Only supports 16-bit FileManager


fnCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	ddraw.h
Unicode	No
Platform Notes	None


FNIDLE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


ForegroundIdleProc
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	HOOKPROC


FRHookProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	commdlg.h
Unicode	No
Platform Notes	LPFRHOOKPROC


GetMsgProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	HOOKPROC


IOProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	mmsystem.h
Unicode	No
Platform Notes	MMIOPROC


JournalPlaybackProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	HOOKPROC


JournalRecordProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	HOOKPROC


KeyboardProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	HOOKPROC


LINECALLBACK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LineDDAProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	wingdi.h
Unicode	No
Platform Notes	LINEDDAPROC


LPFNBUTTON
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mapidefs.h
Unicode	No
Platform Notes	None


MessageProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	HOOKPROC


MidiInProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


MidiOutProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


MMIOProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	mmsystem.h
Unicode	No
Platform Notes	MMIOPROC


MouseProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	HOOKPROC


MSGCALLRELEASE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	imessage.h
Unicode	No
Platform Notes	None


MSGSERVICEENTRY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mapispi.h
Unicode	No
Platform Notes	None


MyStatusProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


NOTIFCALLBACK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mapidefs.h
Unicode	No
Platform Notes	May not be supported in future versions


OFNHookProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	LPOFNHOOKPROC


OFNHookProcOldStyle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	LPOFNHOOKPROC


OPTIONCALLBACK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mapispi.h
Unicode	No
Platform Notes	None


ORASADFunc
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	ras.h
Unicode	No
Platform Notes	None


OutputProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	GRAYSTRINGPROC


PagePaintHook
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	commdlg.h
Unicode	No
Platform Notes	LPPAGEPAINTHOOK


PageSetupHook
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	commdlg.h
Unicode	No
Platform Notes	LPPAGESETUPHOOK


PHONECALLBACK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


PreprocessMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mapispi.h
Unicode	No
Platform Notes	None


PrintHookProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	commdlg.h
Unicode	No
Platform Notes	LPPRINTHOOKPROC


PropEnumProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	winuser.h
Unicode	WinNT
Platform Notes	PROPENUMPROC


PropEnumProcEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	winuser.h
Unicode	WinNT
Platform Notes	PROPENUMPROCEX


PropSheetPageProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	prsht.h
Unicode	WinNT
Platform Notes	LPFNPSPCALLBACK


PropSheetProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	prsht.h
Unicode	No
Platform Notes	PFNPROPSHEETCALLBACK


RASADFunc
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasDialFunc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	ras.h
Unicode	No
Platform Notes	None


RasDialFunc1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	ras.h
Unicode	No
Platform Notes	None


RasDialFunc2
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	ras.h
Unicode	No
Platform Notes	None


RasPBDlgFunc
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	rasdlg.h
Unicode	WinNT
Platform Notes	None


RemovePreprocessInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mapispi.h
Unicode	No
Platform Notes	None


SendAsyncProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	SENDASYNCPROC


ServiceMain
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


SERVICEWIZARDDLGPROC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mapiwz.h
Unicode	No
Platform Notes	None


SetupHookProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	commdlg.h
Unicode	No
Platform Notes	LPSETUPHOOKPROC


ShellProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	HOOKPROC


SnmpExtensionInit
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


SnmpExtensionQuery
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


SnmpExtensionTrap
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


SoundSentryProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


SP_FILE_CALLBACK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SymbolRegisteredCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SymEnumModulesCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SymEnumSymbolsCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SysMsgProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	HOOKPROC


TimeProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mmsystem.h
Unicode	No
Platform Notes	TIMECALLBACK


TimerProc
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	TIMERPROC


waveInProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


waveOutProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	-
Unicode	No
Platform Notes	None


WindowProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	WNDPROC


WIZARDENTRY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mapiwz.h
Unicode	No
Platform Notes	None


MCI_BREAK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_CAPTURE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_CLOSE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_CONFIGURE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_COPY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_CUE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_CUT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_DELETE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_ESCAPE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_FREEZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_GETDEVCAPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_INDEX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_INFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_LIST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_LOAD
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_MARK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_MONITOR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_OPEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_PASTE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_PAUSE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_PLAY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_PUT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_QUALITY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_REALIZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_RECORD
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_RESERVE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_RESTORE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_RESUME
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SAVE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SEEK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SET
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SETAUDIO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SETTIMECODE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SETTUNER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SETVIDEO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SIGNAL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SPIN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_STATUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_STEP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_STOP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SYSINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_UNDO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_UNFREEZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_UPDATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_WHERE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_WINDOW
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


break
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


capability
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


capture
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


close
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


configure
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


copy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


cue
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


cut
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


delete
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


escape
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


freeze
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


index
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


info
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


list
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


load
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


mark
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


monitor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


open
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


paste
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


pause
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


play
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


put
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


quality
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


realize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


record
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


reserve
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


restore
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


resume
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


save
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


seek
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


set
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


setaudio
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


settimecode
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


settuner
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


setvideo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


signal
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


spin
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


status
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


step
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


stop
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


sysinfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


undo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


unfreeze
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


update
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


where
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


window
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


CMC_X_COM_ATTACH_CHARPOS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcext.h
Unicode	No
Platform Notes	None


CMC_X_COM_CAN_SEND_RECIP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcext.h
Unicode	No
Platform Notes	None


CMC_X_COM_CONFIG_DATA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcext.h
Unicode	No
Platform Notes	None


CMC_X_COM_PRIORITY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcext.h
Unicode	No
Platform Notes	None


CMC_X_COM_RECIP_ID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcext.h
Unicode	No
Platform Notes	None


CMC_X_COM_SAVE_MESSAGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcext.h
Unicode	No
Platform Notes	None


CMC_X_COM_SENT_MESSAGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcext.h
Unicode	No
Platform Notes	None


CMC_X_COM_SUPPORT_EXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcext.h
Unicode	No
Platform Notes	None


CMC_X_COM_TIME_RECEIVED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcext.h
Unicode	No
Platform Notes	None


CMC_X_MS_ADDRESS_UI
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcmsxt.h
Unicode	No
Platform Notes	None


CMC_X_MS_ATTACH_DATA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcmsxt.h
Unicode	No
Platform Notes	None


CMC_X_MS_FUNCTION_FLAGS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcmsxt.h
Unicode	No
Platform Notes	None


CMC_X_MS_MESSAGE_DATA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcmsxt.h
Unicode	No
Platform Notes	None


CMC_X_MS_SESSION_FLAGS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcmsxt.h
Unicode	No
Platform Notes	None


CMC_XS_COM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcext.h
Unicode	No
Platform Notes	None


CMC_XS_MS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcmsxt.h
Unicode	No
Platform Notes	None


XTYP_ADVDATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


XTYP_ADVREQ
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


XTYP_ADVSTART
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


XTYP_ADVSTOP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


XTYP_CONNECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


XTYP_CONNECT_CONFIRM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


XTYP_DISCONNECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


XTYP_ERROR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


XTYP_EXECUTE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


XTYP_MONITOR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


XTYP_POKE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


XTYP_REGISTER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


XTYP_REQUEST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


XTYP_UNREGISTER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


XTYP_WILDCONNECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


XTYP_XACT_COMPLETE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


FSCTL_DISMOUNT_VOLUME
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


FSCTL_GET_COMPRESSION
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


FSCTL_LOCK_VOLUME
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


FSCTL_SET_COMPRESSION
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


FSCTL_UNLOCK_VOLUME
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_CHECK_VERIFY
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_EJECT_MEDIA
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_FORMAT_TRACKS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_GET_DRIVE_GEOMETRY
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_GET_DRIVE_LAYOUT
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_GET_MEDIA_TYPES
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_GET_PARTITION_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_LOAD_MEDIA
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_MEDIA_REMOVAL
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_PERFORMANCE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_REASSIGN_BLOCKS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_SET_DRIVE_LAYOUT
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_SET_PARTITION_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_VERIFY
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_SERIAL_LSRMST_INSERT
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


ABProviderInit
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mapispi.h
Unicode	No
Platform Notes	None


HPProviderInit
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mapihook.h
Unicode	No
Platform Notes	None


MSProviderInit
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mapispi.h
Unicode	No
Platform Notes	None


XPProviderInit
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user-defined
Header File	mapispi.h
Unicode	No
Platform Notes	None


ACCESS_MODE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	accctrl.h
Unicode	WinNT
Platform Notes	None


MULTIPLE_TRUSTEE_OPERATION
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	accctrl.h
Unicode	WinNT
Platform Notes	None


SE_OBJECT_TYPE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	accctrl.h
Unicode	WinNT
Platform Notes	None


TRUSTEE_FORM
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	accctrl.h
Unicode	WinNT
Platform Notes	None


TRUSTEE_TYPE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	accctrl.h
Unicode	WinNT
Platform Notes	None


ACL_INFORMATION_CLASS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


ACTIVATEFLAGS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


ADVF
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


BIND_FLAGS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


BINDSPEED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


CALLTYPE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


CLSCTX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wtypes.h
Unicode	Yes
Platform Notes	None


COINIT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objbase.h
Unicode	Yes
Platform Notes	None


D3DBLEND
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DCMPFUNC
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DCOLORMODEL
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DCULL
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DFILLMODE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DFOGMODE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DLIGHTSTATETYPE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DLIGHTTYPE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DOPCODE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DRENDERSTATETYPE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DRMCOLORSOURCE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMCOMBINETYPE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMFILLMODE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMFOGMODE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMFRAMECONSTRAINT
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMLIGHTMODE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMLIGHTTYPE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMMATERIALMODE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMPALETTEFLAGS
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMPROJECTIONTYPE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMRENDERQUALITY
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMSHADEMODE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMSORTMODE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMTEXTUREQUALITY
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMUSERVISUALREASON
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMWRAPTYPE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMXOFFORMAT
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMZBUFFERMODE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DSHADEMODE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DTEXTUREADDRESS
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DTEXTUREBLEND
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DTEXTUREFILTER
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DTRANSFORMSTATETYPE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


DATADIR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


DISCARDCACHE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


DROPEFFECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


DVASPECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


DVASPECT2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


DVASPECTINFOFLAG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


DVEXTENTMODE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


EXTCONN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


FD_FLAGS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


GET_FILEEX_INFO_LEVELS
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


GUIDKIND
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


HITRESULT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


KEYMODIFIERS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	controls.idl
Unicode	Yes
Platform Notes	None


LOCKTYPE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


MEDIA_TYPE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


MKRREDUCE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


MKSYS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


MSHCTX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wtypes.h
Unicode	Yes
Platform Notes	None


MSHLFLAGS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wtypes.h
Unicode	Yes
Platform Notes	None


OLECLOSE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


OLECONTF
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


OLECREATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OLEDCFLAGS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


OLEGETMONIKER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


OLELINKBIND
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


OLEMISC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


OLERENDER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


OLEUIPASTEFLAG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OLEUPDATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


OLEVERBATTRIB
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


OLEWHICHMK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


PENDINGMSG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


PENDINGTYPE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


PICTURE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


PICTYPE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	olectl.h
Unicode	Yes
Platform Notes	None


POINTERINACTIVE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


PROPSETFLAG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


QACONTAINERFLAGS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


RAS_PARAMS_FORMAT
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rassapi.h
Unicode	No
Platform Notes	None


RASCONNSTATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ras.h
Unicode	No
Platform Notes	None


RASPROJECTION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ras.h
Unicode	No
Platform Notes	None


REGCLS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objbase.h
Unicode	Yes
Platform Notes	None


RPC_C_AUTHN_LEVEL_xxx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	rpcdce.h
Unicode	Yes
Platform Notes	None


RPC_C_AUTHN_xxx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	rpcdce.h
Unicode	Yes
Platform Notes	None


RPC_C_AUTHZ_xxx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	rpcdce.h
Unicode	Yes
Platform Notes	None


RPC_C_IMP_LEVEL_xxx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	rpcdce.h
Unicode	Yes
Platform Notes	None


SECURITY_IMPERSONATION_LEVEL
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


SERVERCALL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


SHCONTF
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


SHGNO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


SID_NAME_USE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


STATFLAG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wtypes.h
Unicode	Yes
Platform Notes	None


STGC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wtypes.h
Unicode	Yes
Platform Notes	None


STGFMT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File
Unicode	Yes
Platform Notes	None


STGM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objbase.h
Unicode	Yes
Platform Notes	None


STGMOVE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wtypes.h
Unicode	Yes
Platform Notes	None


STGTY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


STREAM_SEEK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


TOKEN_INFORMATION_CLASS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TOKEN_TYPE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TYMED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


UASFLAGS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


USERCLASSTYPE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


VIEWSTATUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


__WSAFDIsSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	Yes
Platform Notes	Win32s supports WS 1.1


_hread
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


_hwrite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


_lclose
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


_lcreat
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


_llseek
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


_lopen
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


_lread
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


_lwrite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


AbnormalTermination
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File
Unicode	No
Platform Notes	None


AbortDoc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


AbortPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


AbortPrinter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


AbortSystemShutdown
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


ACCELERATEABSDI
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapidefs.h
Unicode	No
Platform Notes	None


accept
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


AcceptEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	mswsock.lib
Header File	mswsock.h
Unicode	No
Platform Notes	Microsoft-specific extension


AccessCheck
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


AccessCheckAndAuditAlarm
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


acmDriverAdd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmDriverClose
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmDriverDetails
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmDriverEnum
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmDriverID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmDriverMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmDriverOpen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmDriverPriority
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmDriverRemove
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmFilterChoose
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFilterDetails
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFilterEnum
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFilterTagDetails
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFilterTagEnum
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFormatChoose
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFormatDetails
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFormatEnum
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFormatSuggest
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmFormatTagDetails
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFormatTagEnum
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmGetVersion
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmMetrics
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmStreamClose
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmStreamConvert
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmStreamMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmStreamOpen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmStreamPrepareHeader
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmStreamReset
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmStreamSize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmStreamUnprepareHeader
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


AcsLan
Windows NT	Yes
Win95	No
Win32s	No
Import Library	dlcapi.lib
Header File	dlcapi.h
Unicode	No
Platform Notes	None


ActivateKeyboardLayout
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


AddAccessAllowedAce
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


AddAccessDeniedAce
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


AddAce
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


AddAtom
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


AddAuditAccessAce
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


AddFontResource
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


AddForm
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AddJob
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AddMonitor
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AddPort
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AddPrinter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AddPrinterConnection
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AddPrinterDriver
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AddPrintProcessor
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AddPrintProvidor
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AdjustTokenGroups
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


AdjustTokenPrivileges
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


AdjustWindowRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


AdjustWindowRectEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


AdvancedDocumentProperties
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AllocateAndInitializeSid
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


AllocateLocallyUniqueId
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


AllocConsole
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


AngleArc
Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


AnimatePalette
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


AnyPopup
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


AppendMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


Arc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ArcTo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


AreAllAccessesGranted
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


AreAnyAccessesGranted
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


AreFileApisANSI
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	On Win32s the file APIs are always ANSI


ArrangeIconicWindows
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


AttachThreadInput
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


auxGetDevCaps
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


auxGetNumDevs
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


auxGetVolume
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


auxOutMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


auxSetVolume
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


AVIBuildFilter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


AVIClearClipboard
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileAddRef
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileCreateStream
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileEndRecord
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileExit
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileGetStream
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


AVIFileInit
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileOpen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


AVIFileReadData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileRelease
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileWriteData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIGetFromClipboard
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIMakeCompressedStream
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIMakeFileFromStreams
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIMakeStreamFromClipboard
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIPutFileOnClipboard
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVISave
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


AVISaveOptions
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVISaveOptionsFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVISaveV
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


AVIStreamAddRef
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamBeginStreaming
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamCreate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamEndStreaming
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamFindSample
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamGetFrame
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamGetFrameClose
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamGetFrameOpen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


AVIStreamLength
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamOpenFromFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


AVIStreamRead
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamReadData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamReadFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamRelease
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamSampleToTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamSetFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamStart
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamTimeToSample
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamWrite
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamWriteData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


BackupEventLog
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


BackupRead
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


BackupSeek
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


BackupWrite
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


Beep
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


BeginDeferWindowPos
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


BeginPaint
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


BeginPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


BeginUpdateResource
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


bind
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


BindImage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


BindImageEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


BindMoniker
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


BitBlt
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


BringWindowToTop
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


BroadcastSystemMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


BuildCommDCB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


BuildCommDCBAndTimeouts
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


BuildDisplayTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


BuildExplicitAccessWithName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


BuildImpersonateExplicitAccessWithName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


BuildImpersonateTrustee
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


BuildSecurityDescriptor
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


BuildTrusteeWithName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


BuildTrusteeWithSid
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


CallMsgFilter
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CallNamedPipe
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CallNextHookEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CallWindowProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CancelDC
Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


CancelIo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


CancelWaitableTimer
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


capCreateCaptureWindow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


capGetDriverDescription
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


CascadeWindows
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ChangeClipboardChain
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ChangeDisplaySettings
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


ChangeIdleRoutine
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


ChangeMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


ChangeServiceConfig
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


char_array_from_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


char_from_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


CharLower
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CharLowerBuff
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CharNext
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CharNextExA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CharPrev
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CharPrevExA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CharToOem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CharToOemBuff
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CharUpper
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CharUpperBuff
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CheckColorsInGamut
Windows NT	No
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


CheckDlgButton
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CheckMenuItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CheckMenuRadioItem
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CheckParameters
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	Intel only


CheckParms
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	None


CheckRadioButton
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CheckSumMappedFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ChildWindowFromPoint
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ChildWindowFromPointEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ChooseColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.lib
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


ChooseFont
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.lib
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


ChoosePixelFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


Chord
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ClearCommBreak
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


ClearCommError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


ClearEventLog
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ClientToScreen
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ClipCursor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CloseClipboard
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CloseDesktop
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CloseDriver
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


CloseEnhMetaFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


CloseEventLog
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


CloseFigure
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CloseHandle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


CloseIMsgSession
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	imessage.h
Unicode	No
Platform Notes	May not be supported in future versions


CloseMetaFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


ClosePrinter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	No
Platform Notes	None


CloseServiceHandle
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	No
Platform Notes	None


closesocket
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


CloseWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CloseWindowStation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CLSIDFromProgID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CLSIDFromString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


cmc_act_on
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


cmc_free
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


cmc_list
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


cmc_logoff
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


cmc_logon
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


cmc_look_up
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


cmc_query_configuration
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


cmc_read
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


cmc_send
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


cmc_send_documents
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CoBuildVersion
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.lib
Header File	objbase.h
Unicode	No
Platform Notes	None


CoCopyProxy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoCreateFreeThreadedMarshaler
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoCreateGuid
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoCreateInstance
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoCreateInstanceEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoDisconnectObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoDosDateTimeToFileTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoFileTimeNow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoFileTimeToDosDateTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoFreeAllLibraries
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoFreeLibrary
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoFreeUnusedLibraries
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoGetCallContext
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoGetClassObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoGetCurrentProcess
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoGetInstanceFromFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoGetInstanceFromIStorage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoGetInterfaceAndReleaseStream
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoGetMalloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoGetMarshalSizeMax
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoGetStandardMarshal
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoGetState
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.lib
Header File	objbase.h
Unicode	No
Platform Notes	None


CoGetTreatAsClass
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoImpersonateClient
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoInitialize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoInitializeEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoInitializeSecurity
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoIsHandlerConnected
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.lib
Header File	objbase.h
Unicode	No
Platform Notes	None


CoIsOle1Class
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.lib
Header File	objbase.h
Unicode	No
Platform Notes	None


CoLoadLibrary
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoLockObjectExternal
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


ColorMatchToTarget
Windows NT	No
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


ColsHandlerConnected
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


ColsOle1Class
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoMarshalHresult
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoMarshalInterface
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoMarshalInterTheadInterfaceInStream
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CombineRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CombineTransform
Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


CommandLineToArgvW
Windows NT	Yes
Win95	No
Win32s	Yes
Import Library	shell32.lib
Header File	shellapi.h
Unicode	No
Platform Notes	None


CommConfigDialog
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CommDlgExtendedError
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.lib
Header File	commdlg.h
Unicode	No
Platform Notes	None


CompareFileTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


CompareString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


ConfigurePort
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


connect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


ConnectNamedPipe
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


ConnectToPrinterDlg
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	No
Platform Notes	None


ContinueDebugEvent
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


ControlService
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	No
Platform Notes	None


ConvertDefaultLocale
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	None


ConvertThreadToFiber
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


CopyAcceleratorTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CopyCursor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CopyEnhMetaFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


CopyFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CopyFileEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CopyIcon
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CopyImage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CopyMemory
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


CopyMetaFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


CopyRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CopySid
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


CoQueryAuthenticationServices
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoQueryClientBlanket
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoQueryProxyBlanket
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoRegisterClassObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoRegisterMallocSpy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoRegisterMessageFilter
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoReleaseMarshalData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoRevertToSelf
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoRevokeClassObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoRevokeMallocSpy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoSetProxyBlanket
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoTaskMemAlloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoTaskMemFree
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoTaskMemRealloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoTreatAsClass
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoUninitialize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoUnmarshalHresult
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CoUnmarshalInterface
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CountClipboardFormats
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateAcceleratorTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CreateAntiMoniker
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CreateBindCtx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CreateBitmap
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateBitmapIndirect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateBrushIndirect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateCaret
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateColorSpace
Windows NT	No
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


CreateCompatibleBitmap
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateCompatibleDC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateConsoleScreenBuffer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


CreateCursor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateDataAdviseHolder
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CreateDataCache
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CreateDC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


CreateDesktop
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CreateDialogIndirectParam
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CreateDialogParam
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CreateDIBitmap
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateDIBPatternBrush
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateDIBPatternBrushPt
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


CreateDIBSection
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


CreateDirectory
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateDirectoryEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateDiscardableBitmap
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateDispTypeInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	All
Platform Notes	All 32-bit OLE Apis are UNICODE only


CreateEditableStream
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


CreateEllipticRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CreateEllipticRgnIndirect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CreateEnhMetaFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


CreateErrorInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


CreateEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateFiber
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


CreateFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateFileMapping
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateFileMoniker
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CreateFont
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


CreateFontIndirect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


CreateGenericComposite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CreateHalftonePalette
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


CreateHatchBrush
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateIC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


CreateIcon
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateIconFromResource
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateIconFromResourceEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateIconIndirect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateILockBytesOnHGlobal
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


CreateIoCompletionPort
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


CreateIProp
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


CreateItemMoniker
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CreateMailslot
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateMappedBitmap
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


CreateMDIWindow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CreateMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateMetaFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


CreateMutex
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateNamedPipe
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateOleAdviseHolder
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


CreatePalette
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreatePatternBrush
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreatePen
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreatePenIndirect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreatePipe
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


CreatePointerMoniker
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


CreatePolygonRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CreatePolyPolygonRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CreatePopupMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


CreatePrivateObjectSecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


CreateProcess
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateProcessAsUser
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreatePropertySheetPage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	prsht.h
Unicode	WinNT
Platform Notes	None


CreateRectRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CreateRectRgnIndirect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CreateRemoteThread
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


CreateRoundRectRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CreateScalableFontResource
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


CreateSemaphore
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateService
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


CreateSolidBrush
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateStatusWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


CreateStdDispatch
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


CreateStreamOnHGlobal
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


CreateTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


CreateTapePartition
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


CreateThread
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


CreateToolbarEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


CreateTypeLib
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	All
Platform Notes	All 32-bit OLE Apis are UNICODE only


CreateUpDownControl
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


CreateWaitableTimer
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CreateWindowEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	hMenu limited to WORD on Win32s


CreateWindowStation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CryptAcquireContext
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptCreateHash
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptDecrypt
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptDeriveKey
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptDestroyHash
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptDestroyKey
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptEncrypt
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptExportKey
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptGenKey
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptGenRandom
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptGetHashParam
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptGetKeyParam
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptGetProvParam
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptGetUserKey
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptHashData
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptHashSessionKey
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptImportKey
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptReleaseContext
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptSetHashParam
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptSetKeyParam
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptSetProvider
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptSetProvParam
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptSignHash
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


CryptVerifySignature
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	advapi32.lib
Header File	wincrypt.h
Unicode	WinNT
Platform Notes	None


D3DRMColorGetAlpha
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMColorGetBlue
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMColorGetGreen
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMColorGetRed
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMCreateColorRGB
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMCreateColorRGBA
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMMatrixFromQuaternion
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMQuaternionFromRotation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMQuaternionMultiply
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMQuaternionSlerp
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMVectorAdd
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMVectorCrossProduct
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMVectorDotProduct
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMVectorModulus
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMVectorNormalize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMVectorRandom
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMVectorReflect
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMVectorRotate
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMVectorScale
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMVectorSubtract
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


data_from_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


data_into_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


data_size_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


DceErrorInqText
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


DdeAbandonTransaction
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeAccessData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeAddData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeClientTransaction
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeCmpStringHandles
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeConnect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeConnectList
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeCreateDataHandle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeCreateStringHandle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	WinNT
Platform Notes	None


DdeDisconnect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeDisconnectList
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeEnableCallback
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeFreeDataHandle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeFreeStringHandle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeGetData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeGetLastError
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeImpersonateClient
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeInitialize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	WinNT
Platform Notes	None


DdeKeepStringHandle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeNameService
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdePostAdvise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeQueryConvInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeQueryNextServer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeQueryString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	WinNT
Platform Notes	None


DdeReconnect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeSetQualityOfService
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	dde.h
Unicode	No
Platform Notes	None


DdeSetUserHandle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeUnaccessData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeUninitialize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ddeml.h
Unicode	No
Platform Notes	None


DebugActiveProcess
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


DebugBreak
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


DefDlgProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DefDriverProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DeferWindowPos
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DefFrameProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DefineDosDevice
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


DefMDIChildProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DefScreenSaverProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	scrnsave.lib
Header File	scrnsave.h
Unicode	No
Platform Notes	None


DefWindowProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DeinitMapiUtil
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


DeleteAce
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


DeleteAtom
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


DeleteColorSpace
Windows NT	No
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


DeleteCriticalSection
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


DeleteDC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


DeleteEnhMetaFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


DeleteFiber
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


DeleteFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


DeleteForm
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DeleteMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DeleteMetaFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


DeleteMonitor
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DeleteObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


DeletePort
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DeletePrinter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	No
Platform Notes	None


DeletePrinterConnection
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	-
Unicode	WinNT
Platform Notes	None


DeletePrinterData
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DeletePrinterDriver
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DeletePrintProcessor
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DeletePrintProvidor
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DeleteService
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	No
Platform Notes	None


DeregisterEventSource
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


DeregisterIdleRoutine
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


DescribePixelFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


DestroyAcceleratorTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DestroyCaret
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DestroyCursor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DestroyIcon
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DestroyMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DestroyPrivateObjectSecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


DestroyPropertySheetPage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	prsht.h
Unicode	No
Platform Notes	None


DestroyWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DeviceCapabilities
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


DeviceIoControl
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


DialogBoxIndirectParam
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DialogBoxParam
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


Direct3DRMCreate
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


DirectDrawCreate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ddraw.lib
Header File	ddraw.h
Unicode	No
Platform Notes	None


DirectDrawCreateClipper
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ddraw.lib
Header File	ddraw.h
Unicode	No
Platform Notes	None


DirectDrawEnumerate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ddraw.lib
Header File	ddraw.h
Unicode	No
Platform Notes	None


DirectPlayCreate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	dplay.lib
Header File	dplay.h
Unicode	No
Platform Notes	None


DirectPlayEnumerate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	dplay.lib
Header File	dplay.h
Unicode	No
Platform Notes	None


DirectSoundCreate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	dsound.lib
Header File	dsound.h
Unicode	No
Platform Notes	None


DirectSoundEnumerate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	dsound.lib
Header File	dsound.h
Unicode	No
Platform Notes	None


DirectXSetup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	dsetup.lib
Header File	dsetup.h
Unicode	No
Platform Notes	None


DisableThreadLibraryCalls
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


DisconnectNamedPipe
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


DispatchMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DispGetIDsOfNames
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


DispGetParam
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


DispInvoke
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


DlgDirList
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DlgDirListComboBox
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DlgDirSelectComboBoxEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DlgDirSelectEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DllCanUnloadNow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


DllEntryPoint
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


DllGetClassObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


DllRegisterServer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	olectl.h
Unicode	Yes
Platform Notes	None


DllUnregisterServer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	olectl.h
Unicode	Yes
Platform Notes	None


DocumentProperties
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DocumentPropertySheets
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winspool.h
Unicode
Platform Notes	None


DoDragDrop
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


DosDateTimeToFileTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


DosDateTimeToVariantTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


double_array_from_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


double_from_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


DPtoLP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


DragAcceptFiles
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.lib
Header File	shellapi.h
Unicode	No
Platform Notes	None


DragDetect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DragFinish
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.lib
Header File	shellapi.h
Unicode	No
Platform Notes	None


DragObject
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DragQueryFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.lib
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


DragQueryPoint
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.lib
Header File	shellapi.h
Unicode	No
Platform Notes	None


DrawAnimatedRects
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawCaption
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawDibBegin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibChangePalette
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibClose
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibDraw
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibEnd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibGetBuffer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibGetPalette
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibOpen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibProfileDisplay
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibRealize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibSetPalette
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibStart
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibStop
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawEdge
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawEscape
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


DrawFocusRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawFrameControl
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawIcon
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawIconEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawInsert
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


DrawMenuBar
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawState
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawStatusText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


DrawText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DrawTextEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


DriverCallback
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	digitalv.h
Unicode	No
Platform Notes	None


DrvGetModuleHandle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DuplicateHandle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


DuplicateIcon
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	shell32.lib
Header File	shellapi.h
Unicode	No
Platform Notes	None


DuplicateToken
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


DuplicateTokenEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


EditStreamClone
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


EditStreamCopy
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


EditStreamCut
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


EditStreamPaste
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


EditStreamSetInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


EditStreamSetName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


Ellipse
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


EmptyClipboard
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


EnableEUDC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File
Unicode
Platform Notes	None


EnableIdleRoutine
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


EnableMenuItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


EnableScrollBar
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


EnableWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


EndDeferWindowPos
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


EndDialog
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


EndDoc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


EndDocPrinter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	No
Platform Notes	None


EndPage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


EndPagePrinter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	No
Platform Notes	None


EndPaint
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


EndPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


EndUpdateResource
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


EnterCriticalSection
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


enum_from_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


EnumCalendarInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


EnumChildWindows
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


EnumClipboardFormats
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


EnumDateFormats
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


EnumDependentServices
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


EnumDesktops
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


EnumDesktopWindows
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


EnumDisplaySettings
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


EnumDPCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	dplay.lib
Header File	dplay.h
Unicode	No
Platform Notes	None


EnumEnhMetaFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


EnumFontFamilies
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


EnumFontFamiliesEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	Win95
Platform Notes	None


EnumFonts
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


EnumForms
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumICMProfiles
Windows NT	No
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


EnumJobs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumMetaFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


EnumMonitors
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumObjects
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


EnumPorts
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumPrinterData
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumPrinterDrivers
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumPrinters
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumPrintProcessorDatatypes
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumPrintProcessors
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumProps
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


EnumPropsEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


EnumProtocols
Windows NT	Yes
Win95	No
Win32s	No
Import Library	wsock32.lib
Header File	nspapi.h
Unicode	WinNT
Platform Notes	Microsoft-specific extension


EnumResourceLanguages
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT; Win95
Platform Notes	None


EnumResourceNames
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT; Win95
Platform Notes	None


EnumResourceTypes
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT; Win95
Platform Notes	None


EnumServicesStatus
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


EnumSystemCodePages
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


EnumSystemLocales
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


EnumThreadWindows
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


EnumTimeFormats
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


EnumWindows
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


EnumWindowStations
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


EqualPrefixSid
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


EqualRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


EqualRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


EqualSid
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


EraseTape
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


Escape
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


EscapeCommFunction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


ExcludeClipRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ExcludeUpdateRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ExitProcess
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


ExitThread
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


ExitWindows
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ExitWindowsEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ExpandEnvironmentStrings
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ExtCreatePen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Only supports solid colors (e.g., BS_SOLID brushes); also int == 16 bits


ExtCreateRegion
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Fails if the transform involves a shearing or rotation; int == 16 bits


ExtEscape
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


ExtFloodFill
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ExtractAssociatedIcon
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	shell32.lib
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


ExtractIcon
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.lib
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


ExtractIconEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


ExtSelectClipRgn
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ExtTextOut
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT; Win95
Platform Notes	Windows 95: 16-bit coordinates only


FatalAppExit
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


FatalExit
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


FBadColumnSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	May not be supported in future versions


FBadEntryList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	May not be supported in future versions


FBadProp
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	May not be supported in future versions


FBadPropTag
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	May not be supported in future versions


FBadRestriction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	May not be supported in future versions


FBadRglpNameID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	May not be supported in future versions


FBadRglpszW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	May not be supported in future versions


FBadRow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	May not be supported in future versions


FBadRowSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	May not be supported in future versions


FBadSortOrderSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	May not be supported in future versions


FBinFromHex
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


FEqualNames
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


FileTimeToDosDateTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


FileTimeToLocalFileTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	Win32s always uses LocalTime never UTC


FileTimeToSystemTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


FillConsoleOutputAttribute
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


FillConsoleOutputCharacter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


FillMemory
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


FillPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


FillRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


FillRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


FindAtom
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


FindClose
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


FindCloseChangeNotification
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


FindClosePrinterChangeNotification
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	No
Platform Notes	None


FindDebugInfoFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


FindExecutable
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.lib
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


FindExecutableImage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


FindFirstChangeNotification
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


FindFirstFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	Win32s returns times in LocalTime


FindFirstFileEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


FindFirstFreeAce
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


FindFirstPrinterChangeNotification
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	No
Platform Notes	None


FindNextChangeNotification
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


FindNextFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	Win32s returns times in LocalTime


FindNextPrinterChangeNotification
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	No
Platform Notes	None


FindResource
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT; Win95
Platform Notes	None


FindResourceEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT; Win95
Platform Notes	None


FindText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.lib
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


FindWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


FindWindowEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


FlashWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


FlattenPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


float_array_from_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


float_from_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


FloodFill
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


FlushConsoleInputBuffer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


FlushFileBuffers
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


FlushInstructionCache
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	This is valid on SMP platforms only; Windows 95 returns a constant


FlushViewOfFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


FoldString
Windows NT	Yes
Win95	No
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


FormatMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


FPropCompareProp
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


FPropContainsProp
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


FPropExists
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


FrameRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


FrameRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


FreeConsole
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


FreeDDElParam
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	dde.h
Unicode	No
Platform Notes	None


FreeEnvironmentStrings
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


FreeImageColorMatcher
Windows NT	No
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


FreeLibrary
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


FreeLibraryAndExitThread
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


FreePadrlist
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


FreePrinterNotifyInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	No
Platform Notes	None


FreePropVariantArray
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objidl.h
Unicode	Yes
Platform Notes	None


FreeProws
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


FreeSid
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


FtAddFt
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


FtgRegisterIdleRoutine
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


FtMulDw
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


FtMulDwDw
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


FtNegFt
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


FtSubFt
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


GdiComment
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GdiFlush
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GdiGetBatchLimit
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GdiSetBatchLimit
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GenerateConsoleCtrlEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


GetAcceptExSockaddrs
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	mswsock.lib
Header File	mswsock.h
Unicode	No
Platform Notes	Microsoft-specific extension


GetAce
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetAclInformation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetACP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	None


GetActiveObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


GetActiveWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetAddressByName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	wsock32.lib
Header File	nspapi.h
Unicode	WinNT
Platform Notes	Microsoft-specific extension


GetArcDirection
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetAspectRatioFilterEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetAsyncKeyState
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetAtomName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetAttribIMsgOnIStg
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	imessage.h
Unicode	No
Platform Notes	None


GetAuditedPermissionsFromAcl
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


GetBinaryType
Windows NT	Yes
Win95	No
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetBitmapDimensionEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetBkColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetBkMode
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetBoundsRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetBrushOrgEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetCapture
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetCaretBlinkTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetCaretPos
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetCharABCWidths
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


GetCharABCWidthsFloat
Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


GetCharacterPlacement
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetCharWidth
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT; Win95
Platform Notes	Windows 95: int == 16 bits


GetCharWidth32
Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


GetCharWidthFloat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


GetClassFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


GetClassInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetClassInfoEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetClassLong
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetClassName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetClassWord
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetClientRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetClipboardData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetClipboardFormatName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetClipboardOwner
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetClipboardViewer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetClipBox
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetClipCursor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetClipRgn
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetColorAdjustment
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetColorSpace
Windows NT	No
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetCommandLine
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT; Win95
Platform Notes	None


GetCommConfig
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCommMask
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCommModemStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCommProperties
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCommState
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCommTimeouts
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCompressedFileSize
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetComputerName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetConsoleCP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	Windows 95 limitations


GetConsoleCursorInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


GetConsoleMode
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


GetConsoleOutputCP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	Windows 95 limitations


GetConsoleScreenBufferInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


GetConsoleTitle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


GetConvertStg
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


GetCPInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	None


GetCurrencyFormat
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


GetCurrentDirectory
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetCurrentFiber
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winnt.h
Unicode	No
Platform Notes	None


GetCurrentHwProfile
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetCurrentObject
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetCurrentPositionEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetCurrentProcess
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCurrentProcessId
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCurrentThread
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCurrentThreadId
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCurrentTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCursor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetCursorPos
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDateFormat
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


GetDC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDCEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDCOrgEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetDefaultCommConfig
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetDesktopWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDeviceCaps
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetDeviceGammaRamp
Windows NT	No
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetDialogBaseUnits
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDIBColorTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetDIBits
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetDiskFreeSpace
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetDiskFreeSpaceEx
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetDlgCtrlID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDlgItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDlgItemInt
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDlgItemText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetDoubleClickTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDriverModuleHandle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


GetDriveType
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetEffectiveClientRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


GetEffectiveRightsFromAcl
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


GetEnhMetaFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


GetEnhMetaFileBits
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetEnhMetaFileDescription
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


GetEnhMetaFileHeader
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetEnhMetaFilePaletteEntries
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetEnvironmentStrings
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetEnvironmentVariable
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetErrorInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


GetExceptionCode
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode
Platform Notes	None


GetExceptionInformation
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode
Platform Notes	None


GetExitCodeProcess
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetExitCodeThread
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetExpandedName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.lib
Header File	lzexpand.h
Unicode	WinNT
Platform Notes	None


GetExplicitEntriesFromAcl
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


GetFiberData
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winnt.h
Unicode	No
Platform Notes	None


GetFileAttributes
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetFileAttributesEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetFileInformationByHandle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetFileSecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetFileSize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetFileTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetFileTitle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.lib
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


GetFileType
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetFileVersionInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	version.lib
Header File	winver.h
Unicode	WinNT
Platform Notes	None


GetFileVersionInfoSize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	version.lib
Header File	winver.h
Unicode	WinNT
Platform Notes	None


GetFocus
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetFontAssocStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File
Unicode
Platform Notes	None


GetFontData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetFontLanguageInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetForegroundWindow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetForm
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


GetFullPathName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetGlyphOutline
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetGraphicsMode
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Only GM_COMPATIBLE is supported


GetHandleInformation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetHGlobalFromILockBytes
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


GetHGlobalFromStream
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


gethostbyaddr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


gethostbyname
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


gethostname
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


GetICMProfile
Windows NT	No
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


GetIconInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetImageConfigInformation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


GetImageUnusedHeaderBytes
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


GetInputState
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetInstance
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


GetJob
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


GetKBCodePage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetKernelObjectSecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetKerningPairs
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetKeyboardLayout
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetKeyboardLayoutList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetKeyboardLayoutName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetKeyboardState
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetKeyboardType
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetKeyNameText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetKeyState
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetLargestConsoleWindowSize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


GetLastActivePopup
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetLastError
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetLengthSid
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetLocaleInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


GetLocalTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetLogColorSpace
Windows NT	No
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


GetLogicalDrives
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetLogicalDriveStrings
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetMailslotInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetMapMode
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuCheckMarkDimensions
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuContextHelpId
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuDefaultItem
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuItemCount
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuItemID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuItemInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetMenuItemRect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuState
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetMessageExtraInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMessagePos
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMessageTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMetaFileBitsEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetMetaRgn
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetMiterLimit
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetModuleFileName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetModuleHandle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetMultipleTrustee
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


GetMultipleTrusteeOperation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


GetNameByType
Windows NT	Yes
Win95	No
Win32s	No
Import Library	wsock32.lib
Header File	nspapi.h
Unicode	WinNT
Platform Notes	Microsoft-specific extension


GetNamedPipeHandleState
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetNamedPipeInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetNamedSecurityInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


GetNearestColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetNearestPaletteIndex
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetNextDlgGroupItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetNextDlgTabItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetNextWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetNumberFormat
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


GetNumberOfConsoleInputEvents
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


GetNumberOfConsoleMouseButtons
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


GetNumberOfEventLogRecords
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


GetObjectType
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetOEMCP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	None


GetOldestEventLogRecord
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetOpenClipboardWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetOpenFileName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.lib
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


GetOpenFileNamePreview
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


GetOutlineTextMetrics
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


GetOverlappedResult
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	Windows 95: Only on serial and IOCTL devices


GetPaletteEntries
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetParent
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


getpeername
Windows NT	No
Win95	No
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


GetPixel
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetPixelFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


GetPolyFillMode
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetPrinter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


GetPrinterData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


GetPrinterDriver
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


GetPrinterDriverDirectory
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


GetPrintProcessorDirectory
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


GetPriorityClass
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetPriorityClipboardFormat
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetPrivateObjectSecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetPrivateProfileInt
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetPrivateProfileSection
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetPrivateProfileSectionNames
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetPrivateProfileString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetPrivateProfileStruct
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetProcAddress
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetProcessAffinityMask
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	This is valid on SMP platforms only; Windows 95 returns a constant


GetProcessHeap
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetProcessHeaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetProcessPriorityBoost
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetProcessShutdownParameters
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetProcessTimes
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetProcessVersion
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetProcessWindowStation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetProcessWorkingSetSize
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetProfileInt
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetProfileSection
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetProfileString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetProp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


getprotobyname
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


getprotobynumber
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


GetQueuedCompletionStatus
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetQueueStatus
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetRasterizerCaps
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetRegionData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetRgnBox
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetROP2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetRunningObjectTable
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


GetSaveFileName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.lib
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


GetSaveFileNamePreview
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


GetScrollInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetScrollPos
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetScrollRange
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetSecurityDescriptorControl
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSecurityDescriptorDacl
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSecurityDescriptorGroup
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSecurityDescriptorLength
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSecurityDescriptorOwner
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSecurityDescriptorSacl
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSecurityInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	No
Platform Notes	None


getservbyname
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


getservbyport
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


GetService
Windows NT	Yes
Win95	No
Win32s	No
Import Library	wsock32.lib
Header File	nspapi.h
Unicode	WinNT
Platform Notes	Microsoft-specific extension


GetServiceDisplayName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


GetServiceKeyName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


GetShortPathName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetSidIdentifierAuthority
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSidLengthRequired
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSidSubAuthority
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSidSubAuthorityCount
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


getsockname
Windows NT	No
Win95	No
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


getsockopt
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


GetStartupInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetStdHandle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetStockObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetStretchBltMode
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetStringTypeA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	None


GetStringTypeEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


GetStringTypeW
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


GetSubMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetSysColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetSysColorBrush
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	Win32s: supports only Windows 3.1 system colors.


GetSystemDefaultLangID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	None


GetSystemDefaultLCID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	None


GetSystemDirectory
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetSystemInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSystemMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetSystemMetrics
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetSystemPaletteEntries
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetSystemPaletteUse
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetSystemPowerStatus
Windows NT	No
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSystemTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSystemTimeAdjustment
Windows NT	Yes
Win95	No
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSystemTimeAsFileTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetTabbedTextExtent
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetTapeParameters
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetTapePosition
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetTapeStatus
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetTempFileName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetTempPath
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetTextAlign
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetTextCharacterExtra
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetTextCharset
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetTextCharsetInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetTextColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetTextExtentExPoint
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT; Win95
Platform Notes	Windows 95: int == 16 bits


GetTextExtentPoint
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT; Win95
Platform Notes	Windows 95: int == 16 bits


GetTextExtentPoint32
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT; Win95
Platform Notes	Windows 95: int == 16 bits


GetTextFace
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


GetTextMetrics
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


GetThreadContext
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetThreadDesktop
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: NOP; only one desktop


GetThreadLocale
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	Windows 95: Locales are static & can change only at system boot


GetThreadPriority
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetThreadPriorityBoost
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetThreadSelectorEntry
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetThreadTimes
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetTickCount
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetTimeFormat
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


GetTimestampForLoadedLibrary
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


GetTimeZoneInformation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetTokenInformation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetTopWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetTrusteeForm
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


GetTrusteeName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


GetTrusteeType
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


GetTypeByName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	wsock32.lib
Header File	nspapi.h
Unicode	WinNT
Platform Notes	Microsoft-specific extension


GetUpdateRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetUpdateRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetUserDefaultLangID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	None


GetUserDefaultLCID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	None


GetUserName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetUserObjectInformation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetUserObjectSecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetVersion
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetVersionEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GetViewportExtEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetViewportOrgEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetVolumeInformation
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWindowContextHelpId
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWindowDC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWindowExtEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetWindowLong
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetWindowOrgEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetWindowPlacement
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWindowRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWindowRgn
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWindowsDirectory
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetWindowText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetWindowTextLength
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetWindowThreadProcessId
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWindowWord
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWinMetaFileBits
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetWorldTransform
Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


glAccum
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glAddSwapHintRectWIN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glAlphaFunc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glArrayElementEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glBegin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glBitmap
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glBlendFunc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glCallList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glCallLists
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glClear
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glClearAccum
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glClearColor
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glClearDepth
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glClearIndex
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glClearStencil
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glClipPlane
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3b
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3bv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3dv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3fv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3i
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3iv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3s
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3sv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3ub
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3ubv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3ui
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3uiv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3us
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor3usv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4b
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4bv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4dv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4fv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4i
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4iv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4s
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4sv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4ub
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4ubv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4ui
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4uiv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4us
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColor4usv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColorMask
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColorMaterial
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glColorPointerEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glCopyPixels
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glCullFace
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glDeleteLists
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glDepthFunc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glDepthMask
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glDepthRange
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glDisable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glDrawArraysEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glDrawBuffer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glDrawPixels
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEdgeFlag
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEdgeFlagPointerEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEdgeFlagv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEnable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEnd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEndList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEvalCoord1d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEvalCoord1dv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEvalCoord1f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEvalCoord1fv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEvalCoord2d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEvalCoord2dv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEvalCoord2f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEvalCoord2fv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEvalMesh1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEvalMesh2
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEvalPoint1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glEvalPoint2
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glFeedbackBuffer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glFinish
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glFlush
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glFogf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glFogfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glFogi
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glFogiv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glFrontFace
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glFrustum
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGenLists
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetBooleanv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetClipPlane
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetDoublev
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetFloatv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetIntegerv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetLightfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetLightiv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetMapdv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetMapfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetMapiv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetMaterialfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetMaterialiv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetPixelMapfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetPixelMapuiv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetPixelMapusv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetPointervEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetPolygonStipple
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetString
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetTexEnvfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetTexEnviv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetTexGendv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetTexGenfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetTexGeniv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetTexImage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetTexLevelParameterfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetTexLevelParameteriv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetTexParameterfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glGetTexParameteriv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glHint
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glIndexd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glIndexdv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glIndexf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glIndexfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glIndexi
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glIndexiv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glIndexMask
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glIndexPointEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glIndexs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glIndexsv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glInitNames
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glIsEnabled
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glIsList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glLightf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glLightfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glLighti
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glLightiv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glLightModelf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glLightModelfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glLightModeli
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glLightModeliv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glLineStipple
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glLineWidth
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glListBase
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glLoadIdentity
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glLoadMatrixd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glLoadMatrixf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glLoadName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glLogicOp
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glMap1d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glMap1f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glMap2d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glMap2f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glMapGrid1d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glMapGrid1f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glMapGrid2d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glMapGrid2f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glMaterialf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glMaterialfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glMateriali
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glMaterialiv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glMatrixMode
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glMultMatrixd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glMultMatrixf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glNewList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glNormal3b
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glNormal3bv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glNormal3d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glNormal3dv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glNormal3f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glNormal3fv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glNormal3i
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glNormal3iv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glNormal3s
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glNormal3sv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glNormalPointerEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


GlobalAddAtom
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GlobalAlloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	GMEM_FIXED is expensive (locks pages) on Win32s - use GMEM_MOVEABLE


GlobalDeleteAtom
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalDiscard
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalFindAtom
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GlobalFlags
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalFree
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalGetAtomName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GlobalHandle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalLock
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalMemoryStatus
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalReAlloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalSize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalUnlock
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


glOrtho
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPassThrough
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPixelMapfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPixelMapuiv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPixelMapusv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPixelStoref
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPixelStorei
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPixelTransferf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPixelTransferi
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPixelZoom
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPointSize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPolygonMode
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPolygonStipple
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPopAttrib
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPopMatrix
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPopName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPushAttrib
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPushMatrix
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glPushName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos2d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos2dv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos2f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos2fv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos2i
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos2iv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos2s
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos2sv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos3d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos3dv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos3f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos3fv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos3i
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos3iv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos3s
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos3sv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos4d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos4dv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos4f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos4fv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos4i
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos4iv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos4s
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRasterPos4sv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glReadBuffer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glReadPixels
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRectd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRectdv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRectf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRectfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRecti
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRectiv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRects
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRectsv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRenderMode
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRotated
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glRotatef
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glScaled
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glScalef
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glScissor
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glSelectBuffer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glShadeModel
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glStencilFunc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glStencilMask
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glStencilOp
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord1d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord1dv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord1f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord1fv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord1i
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord1iv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord1s
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord1sv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord2d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord2dv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord2f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord2fv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord2i
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord2iv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord2s
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord2sv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord3d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord3dv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord3f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord3fv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord3i
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord3iv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord3s
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord3sv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord4d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord4dv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord4f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord4fv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord4i
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord4iv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord4s
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoord4sv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexCoordPointerEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexEnvf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexEnvfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexEnvi
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexEnviv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexGend
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexGendv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexGenf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexGenfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexGeni
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexGeniv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexImage1D
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexImage2D
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexParameterf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexParameterfv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexParameteri
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTexParameteriv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTranslated
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glTranslatef
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluBeginCurve
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluBeginPolygon
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluBeginSurface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluBeginTrim
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluBuild1DMipmaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluBuild2DMipmaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluCylinder
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluDeleteNurbsRenderer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluDeleteQuadric
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluDeleteTess
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluDisk
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluEndCurve
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluEndPolygon
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluEndSurface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluEndTrim
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluErrorString
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluErrorUnicodeStringEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	WinNT
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluGetNurbsProperty
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluGetString
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluGetTessProperty
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluLoadSamplingMatrices
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluLookAt
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluNewNurbsRenderer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluNewQuadric
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluNewTess
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluNextContour
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluNurbsCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluNurbsCurve
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluNurbsProperty
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluNurbsSurface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluOrtho2D
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluPartialDisk
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluPerspective
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluPickMatrix
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluProject
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluPwlCurve
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluQuadricCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluQuadricDrawStyle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluQuadricNormals
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluQuadricOrientation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluQuadricTexture
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluScaleImage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluSphere
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluTessBeginContour
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluTessBeginPolygon
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluTessCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluTessEndContour
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluTessEndPolygon
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluTessNormal
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluTessProperty
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluTessVertex
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


gluUnProject
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	glu32.lib
Header File	glu.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex2d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex2dv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex2f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex2fv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex2i
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex2iv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex2s
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex2sv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex3d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex3dv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex3f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex3fv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex3i
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex3iv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex3s
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex3sv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex4d
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex4dv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex4f
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex4fv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex4i
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex4iv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex4s
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertex4sv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glVertexPointerEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


glViewport
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	gl.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


GrayString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


Handler
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	-
Unicode	No
Platform Notes	None


HandlerRoutine
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	-
Unicode	No
Platform Notes	None


HeapAlloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapCompact
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapCreate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapDestroy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapFree
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapLock
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapReAlloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapSize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapUnlock
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapValidate
Windows NT	Yes
Win95	No
Win32s	in debug version only
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapWalk
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


HexFromBin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


HideCaret
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


HiliteMenuItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


HrAddColumnsEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


HrAllocAdviseSink
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


HrComposeEID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


HrComposeMsgID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


HrDecomposeEID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


HrDecomposeMsgID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


HrDispatchNotifications
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


HrEntryIDFromSz
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


HrGetOneProp
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


HrIStorageFromStream
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


HrQueryAllRows
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


HrSetOneProp
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


HrSzFromEntryID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


HrThisThreadAdviseSink
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


HrValidateIPMSubtree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


htonl
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


htons
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


I_BrowserDebugTrace
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmbrowsr.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_BrowserQueryOtherDomains
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmbrowsr.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_BrowserQueryStatistics
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmbrowsr.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_BrowserResetNetlogonState
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmbrowsr.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_BrowserResetStatistics
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmbrowsr.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_BrowserServerEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmbrowsr.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_NetLogonControl
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_NetLogonControl2
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_RpcAllocate
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcBindingCopy
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcBindingInqDynamicEndpoint
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcBindingInqTransportType
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcBindingIsClientLocal
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcClearMutex
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcDeleteMutex
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcFree
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcFreeBuffer
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcGetAssociationContext
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcGetBuffer
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcGetCurrentCallHandle
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcIfInqTransferSyntaxes
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcMapWin32Status
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpc.h
Unicode	WinNT
Platform Notes	None


I_RpcMonitorAssociation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcNsBindingSetEntryName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcNsGetBuffer
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsip.h
Unicode	WinNT
Platform Notes	None


I_RpcNsRaiseException
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsip.h
Unicode	WinNT
Platform Notes	None


I_RpcNsSendReceive
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsip.h
Unicode	WinNT
Platform Notes	None


I_RpcPauseExecution
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcReBindBuffer
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcns4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcRequestMutex
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcSendReceive
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcServerRegisterForwardFunction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcSetAssociationContext
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcSsDontSerializeContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_RpcStopMonitorAssociation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


I_UuidCreate
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdcep.h
Unicode	WinNT
Platform Notes	None


ICClose
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


ICCompress
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressorChoose
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressorFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompress
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressExBegin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressExQuery
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDraw
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawBegin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawSuggestFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICGetDisplayFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICGetInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICImageCompress
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICImageDecompress
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICInstall
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICLocate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICOpen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICOpenFunction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICRemove
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICSendMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICSeqCompressFrame
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICSeqCompressFrameEnd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICSeqCompressFrameStart
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICSetState
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


ICSetStatusProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


IIDFromString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


ImageAddCertificate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ImageDirectoryEntryToData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ImageEnumerateCertificates
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ImageGetCertificateData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ImageGetCertificateHeader
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ImageGetDigestStream
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ImagehlpApiVersion
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ImagehlpApiVersionEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ImageList_Add
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_AddMasked
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_BeginDrag
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_Create
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_Destroy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_DragEnter
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_DragLeave
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_DragMove
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_DragShowNolock
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_Draw
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_DrawEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_EndDrag
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_GetBkColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_GetDragImage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_GetIcon
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_GetIconSize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_GetImageCount
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_GetImageInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_LoadImage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


ImageList_Merge
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_Read
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_Remove
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_Replace
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_ReplaceIcon
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_SetBkColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_SetDragCursorImage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_SetIconSize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_SetOverlayImage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_Write
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageLoad
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ImageNtHeader
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ImageRemoveCertificate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ImageRvaToSection
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ImageRvaToVa
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ImageUnload
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ImmAssociateContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmConfigureIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmCreateContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmDestroyContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmEnumRegisterWord
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmEscape
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetCandidateList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetCandidateListCount
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetCandidateWindow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmGetCompositionFont
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetCompositionString
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetCompositionWindow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmGetContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmGetConversionList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetConversionStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmGetDefaultIMEWnd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmGetDescription
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetGuideLine
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetIMEFileName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetOpenStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmGetProperty
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmGetRegisterWordStyle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetStatusWindowPos
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmGetVirtualKey
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmInstallIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmIsIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmIsUIMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmNotifyIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmRegisterWord
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmReleaseContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmSetCandidateWindow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmSetCompositionFont
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmSetCompositionString
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmSetCompositionWindow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmSetConversionStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmSetOpenStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmSetStatusWindowPos
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmSimulateHotKey
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	No
Platform Notes	None


ImmUnregisterWord
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imm32.lib
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImpersonateDdeClientWindow
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	dde.h
Unicode	No
Platform Notes	None


ImpersonateLoggedOnUser
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


ImpersonateNamedPipeClient
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


ImpersonateSelf
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


IMPGetIME
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winnls32.h
Unicode	Yes
Platform Notes	None


IMPQueryIME
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winnls32.h
Unicode	Yes
Platform Notes	None


IMPSetIME
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winnls32.h
Unicode	Yes
Platform Notes	None


inet_addr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


inet_ntoa
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


InflateRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


InitAtomTable
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


InitCommonControls
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


InitializeAcl
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


InitializeCriticalSection
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


InitializeSecurityDescriptor
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


InitializeSid
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


InitiateSystemShutdown
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


InSendMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


InsertMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


InsertMenuItem
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


InterlockedCompareExchange
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


InterlockedDecrement
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


InterlockedExchange
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


InterlockedExchangeAdd
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


InterlockedIncrement
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


IntersectClipRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


IntersectRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


InvalidateRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


InvalidateRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


InvertRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


InvertRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ioctlsocket
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


IsAccelerator
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


IsBadCodePtr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


IsBadHugeReadPtr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


IsBadHugeWritePtr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


IsBadReadPtr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


IsBadStringPtr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


IsBadWritePtr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


IsCharAlpha
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


IsCharAlphaNumeric
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


IsCharLower
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


IsCharUpper
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


IsChild
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


IsClipboardFormatAvailable
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


IsDBCSLeadByte
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	None


IsDBCSLeadByteEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	None


IsDebuggerPresent
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File
Unicode	No
Platform Notes	None


IsDialogMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


IsDlgButtonChecked
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


IsEqualGUID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.lib
Header File	objbase.h
Unicode	No
Platform Notes	None


IsIconic
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


IsMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


IsProcessorFeaturePresent
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


IsRectEmpty
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


IsTextUnicode
Windows NT	Yes
Win95	No
Win32s	Yes
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


IsValidAcl
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


IsValidCodePage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	None


IsValidLocale
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	None


IsValidPtrOut
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.lib
Header File	objbase.h
Unicode	No
Platform Notes	None


IsValidSecurityDescriptor
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


IsValidSid
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


IsWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


IsWindowEnabled
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


IsWindowUnicode
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


IsWindowVisible
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


IsZoomed
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


joyConfigChanged
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	winmm.h
Unicode	No
Platform Notes	None


joyGetDevCaps
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


joyGetNumDevs
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


joyGetPos
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


joyGetPosEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


joyGetThreshold
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


joyReleaseCapture
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


joySetCapture
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


joySetThreshold
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


keybd_event
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


KillTimer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


LAUNCHWIZARDENTRY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiwz.h
Unicode	No
Platform Notes	None


LBItemFromPt
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


LCMapString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


LeaveCriticalSection
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


LHashValOfNameSys
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


lineAccept
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineAddProvider
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineAddToConference
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineAgentSpecific
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineAnswer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineBlindTransfer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineClose
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineCompleteCall
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineCompleteTransfer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineConfigDialog
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineConfigDialogEdit
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineConfigProvider
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


LineDDA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


lineDeallocateCall
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineDevSpecific
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineDevSpecificFeature
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineDial
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineDrop
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineForward
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGatherDigits
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGenerateDigits
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGenerateTone
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineGetAddressCaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetAddressID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetAddressStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetAgentActivityList
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetAgentCaps
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetAgentGroupList
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetAgentStatus
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetAppPriority
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetCallInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetCallStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineGetConfRelatedCalls
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineGetCountry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetDevCaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetDevConfig
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetIcon
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetLineDevStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetMessage
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineGetNewCalls
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineGetNumRings
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineGetProviderList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetRequest
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineGetStatusMessages
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineGetTranslateCaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineHandoff
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineHold
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineInitialize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineInitializeEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineMakeCall
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineMonitorDigits
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineMonitorMedia
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineMonitorTones
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineNegotiateAPIVersion
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineNegotiateExtVersion
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineOpen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


linePark
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


linePickup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


linePrepareAddToConference
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineProxyMessage
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineProxyResponse
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineRedirect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineRegisterRequestRecipient
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineReleaseUserUserInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineRemoveFromConference
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineRemoveProvider
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSecureCall
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSendUserUserInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetAgentActivity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetAgentGroup
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetAgentState
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetAppPriority
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineSetAppSpecific
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetCallData
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetCallParams
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetCallPrivilege
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetCallQualityOfService
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetCallTreatment
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetCurrentLocation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetDevConfig
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineSetLineDevStatus
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetMediaControl
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetMediaMode
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetNumRings
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetStatusMessages
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetTerminal
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSetTollList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineSetupConference
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineSetupTransfer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineShutdown
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineSwapHold
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


LineTo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


lineTranslateAddress
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineTranslateDialog
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


lineUncompleteCall
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineUnhold
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


lineUnpark
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


listen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


LoadAccelerators
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadBitmap
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadCursor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadCursorFromFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadIcon
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadImage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


LoadImageColorMatcher
Windows NT	No
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


LoadKeyboardLayout
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	Windows 95: Only 1 keybrd loaded at once


LoadLibrary
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


LoadLibraryEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	Windows 95 limitations


LoadMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadMenuIndirect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadModule
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


LoadRegTypeLib
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


LoadResource
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


LoadString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadTypeLib
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


LocalAlloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalDiscard
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalFileTimeToFileTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalFlags
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalFree
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalHandle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalLock
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalReAlloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalSize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalUnlock
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


LockFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


LockFileEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


LockResource
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


LockServiceDatabase
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	No
Platform Notes	None


LockWindowUpdate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


LogonUser
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


long_array_from_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


long_from_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


long_from_ndr_temp
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


LookupAccountName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


LookupAccountSid
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


LookupIconIdFromDirectory
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


LookupIconIdFromDirectoryEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


LookupPrivilegeDisplayName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


LookupPrivilegeName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


LookupPrivilegeValue
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


LookupSecurityDescriptorParts
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


LPropCompareProp
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


LPtoDP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


LSEnumProviders
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	lsapi32.lib
Header File	lsapi.h
Unicode	No
Platform Notes	None


LSFreeHandle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	lsapi32.lib
Header File	lsapi.h
Unicode	No
Platform Notes	None


LSGetMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	lsapi32.lib
Header File	lsapi.h
Unicode	No
Platform Notes	None


LSQuery
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	lsapi32.lib
Header File	lsapi.h
Unicode	No
Platform Notes	None


LSRelease
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	lsapi32.lib
Header File	lsapi.h
Unicode	No
Platform Notes	None


LSRequest
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	lsapi32.lib
Header File	lsapi.h
Unicode	No
Platform Notes	None


lstrcat
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


lstrcmp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


lstrcmpi
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


lstrcpy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


lstrcpyn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


lstrlen
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT; Win95
Platform Notes	None


LSUpdate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	lsapi32.lib
Header File	lsapi.h
Unicode	No
Platform Notes	None


LZClose
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.lib
Header File	lzexpand.h
Unicode	No
Platform Notes	None


LZCopy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.lib
Header File	lzexpand.h
Unicode	No
Platform Notes	None


LZInit
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.lib
Header File	lzexpand.h
Unicode	No
Platform Notes	None


LZOpenFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.lib
Header File	lzexpand.h
Unicode	WinNT
Platform Notes	None


LZRead
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.lib
Header File	lzexpand.h
Unicode	No
Platform Notes	None


LZSeek
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.lib
Header File	lzexpand.h
Unicode	No
Platform Notes	None


MakeAbsoluteSD
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


MakeDragList
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


MakeSelfRelativeSD
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


MakeSuredirectoryPathExists
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


MapAndLoad
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


MapDebugInformation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


MapDialogRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


MapFileAndCheckSumA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


MapFileAndCheckSumW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


MapGenericMask
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


MAPIAddress
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MAPIAddress (VB)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapivb32.bas
Unicode	No
Platform Notes	None


MAPIAdminProfiles
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapix.h
Unicode	No
Platform Notes	None


MAPIAllocateBuffer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapix.h
Unicode	No
Platform Notes	None


MAPIAllocateMore
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapix.h
Unicode	No
Platform Notes	None


MAPIDeInitIdle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


MAPIDeleteMail
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MAPIDeleteMail (VB)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapivb32.bas
Unicode	No
Platform Notes	None


MAPIDetails
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MAPIDetails (VB)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapivb32.bas
Unicode	No
Platform Notes	None


MAPIFindNext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MAPIFindNext (VB)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapivb32.bas
Unicode	No
Platform Notes	None


MAPIFreeBuffer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapix.h
Unicode	No
Platform Notes	None


MAPIFreeBuffer (Simple MAPI)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MAPIGetDefaultMalloc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


MAPIInitialize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapix.h
Unicode	No
Platform Notes	None


MAPIInitIdle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


MAPILogoff
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MAPILogoff (VB)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapivb32.bas
Unicode	No
Platform Notes	None


MAPILogon
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MAPILogon (VB)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapivb32.bas
Unicode	No
Platform Notes	None


MAPILogonEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapix.h
Unicode	Yes
Platform Notes	None


MAPIOpenFormMgr
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiform.h
Unicode	No
Platform Notes	None


MAPIOpenLocalFormContainer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiform.h
Unicode	No
Platform Notes	None


MAPIReadMail
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MAPIReadMail (VB)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapivb32.bas
Unicode	No
Platform Notes	None


MAPIResolveName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MAPIResolveName (VB)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapivb32.bas
Unicode	No
Platform Notes	None


MAPISaveMail
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MAPISaveMail (VB)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapivb32.bas
Unicode	No
Platform Notes	None


MAPISendDocuments
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MAPISendDocuments (VB)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapivb32.bas
Unicode	No
Platform Notes	None


MAPISendMail
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MAPISendMail (VB)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapivb32.bas
Unicode	No
Platform Notes	None


MAPIUninitialize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapix.h
Unicode	No
Platform Notes	None


MapStorageSCode
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	imessage.h
Unicode	No
Platform Notes	May not be supported in future versions


MapViewOfFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	Windows 95: Memory mapped files appear in the same address space in all processes


MapViewOfFileEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	Windows 95: Memory mapped files appear in the same address space in all processes


MapVirtualKey
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


MapVirtualKeyEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


MapWindowPoints
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


MaskBlt
Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


mciGetCreatorTask
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mciGetDeviceID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mciGetErrorString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mciGetYieldProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mciSendCommand
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mciSendString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mciSetYieldProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCIWndCreate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


MCIWndRegisterClass
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode	No
Platform Notes	None


MenuHelp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


MenuItemFromPoint
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


MesBufferHandleReset
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	midles.h
Unicode	WinNT
Platform Notes	None


MesDecodeBufferHandleCreate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	midles.h
Unicode	WinNT
Platform Notes	None


MesDecodeIncrementalHandleCreate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	midles.h
Unicode	WinNT
Platform Notes	None


MesEncodeDynBufferHandleCreate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	midles.h
Unicode	WinNT
Platform Notes	None


MesEncodeFixedBufferHandleCreate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	midles.h
Unicode	WinNT
Platform Notes	None


MesEncodeIncrementalHandleCreate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	midles.h
Unicode	WinNT
Platform Notes	None


MesHandleFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	midles.h
Unicode	WinNT
Platform Notes	None


MesIncrementalHandleReset
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	midles.h
Unicode	WinNT
Platform Notes	None


MesInqProcEncodingId
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	midles.h
Unicode	WinNT
Platform Notes	None


MessageBeep
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


MessageBox
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT; Win95
Platform Notes	None


MessageBoxEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT; Win95
Platform Notes	None


MessageBoxIndirect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


midiConnect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiDisconnect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInAddBuffer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInClose
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInGetDevCaps
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


midiInGetErrorText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


midiInGetID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInGetNumDevs
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInOpen
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	Win32s: CALLBACK_FUNCTION not supported


midiInPrepareHeader
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInReset
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInStart
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInStop
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInUnprepareHeader
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutCacheDrumPatches
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutCachePatches
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutClose
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutGetDevCaps
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


midiOutGetErrorText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


midiOutGetID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutGetNumDevs
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutGetVolume
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutLongMsg
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutOpen
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	Win32s: CALLBACK_FUNCTION not supported


midiOutPrepareHeader
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutReset
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutSetVolume
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutShortMsg
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutUnprepareHeader
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamClose
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamOpen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamOut
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamPause
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamPosition
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamProperty
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamRestart
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamStop
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midl_allocate
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


MIDL_user_allocate
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user defined
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


MIDL_wchar_strcpy
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


MIDL_wchar_strlen
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


mixerClose
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mixerGetControlDetails
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mixerGetDevCaps
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mixerGetID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mixerGetLineControls
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mixerGetLineInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mixerGetNumDevs
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mixerMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mixerOpen
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mixerSetControlDetails
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MkParseDisplayName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


mmioAdvance
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioAscend
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioClose
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioCreateChunk
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioDescend
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioFlush
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioGetInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioInstallIOProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mmioOpen
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mmioRead
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioRename
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mmioSeek
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioSendMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioSetBuffer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioSetInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioStringToFOURCC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mmioWrite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmsystemGetVersion
Windows NT	No
Win95	No
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


ModifyMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


ModifyWorldTransform
Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


MonikerCommonPrefixWith
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


MonikerRelativePathTo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


mouse_event
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


MoveFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


MoveFileEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	Windows 95: MOVEFILE_DELAY_UNTIL_REBOOT not supported.


MoveMemory
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


MoveToEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


MoveWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


MsgWaitForMultipleObjects
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


MsgWaitForMultipleObjectsEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


MulDiv
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


MultiByteToWideChar
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	None


MultinetGetConnectionPerformance
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NDdeGetErrorString
Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.lib
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeGetShareSecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.lib
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeGetTrustedShare
Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.lib
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeIsValidAppTopicList
Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.lib
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeIsValidShareName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.lib
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeSetShareSecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.lib
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeSetTrustedShare
Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.lib
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeShareAdd
Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.lib
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeShareDel
Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.lib
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeShareEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.lib
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeShareGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.lib
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeShareSetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.lib
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeTrustedShareEnum
Windows NT	Yes
Win95	No
Win32s	Yes
Import Library	nddeapi.lib
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDRCContextBinding
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


NDRCContextMarshall
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


NDRCContextUnmarshall
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


NDRcopy
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


NDRSContextMarshall
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


NDRSContextUnmarshall
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


NetAccessAdd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	None


NetAccessCheck
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	svrapi.h
Unicode	WinNT
Platform Notes	None


NetAccessDel
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	None


NetAccessEnum
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	None


NetAccessGetInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	None


NetAccessGetUserPerms
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	None


NetAccessSetInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	None


NetAlertRaise
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmalert.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetAlertRaiseEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmalert.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetApiBufferAllocate
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmapibuf.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetApiBufferFree
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmapibuf.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetApiBufferReallocate
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmapibuf.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetApiBufferSize
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmapibuf.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetApipBufferAllocate
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmapibuf.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetAuditClear
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmapibuf.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetAuditRead
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmapibuf.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetAuditWrite
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaudit.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


Netbios
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	nb30.h
Unicode	No
Platform Notes	None


NetConfigGet
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmconfig.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetConfigGetAll
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmconfig.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetConfigSet
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmconfig.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetConnectionEnum
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetErrorLogClear
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmerrlog.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetErrorLogRead
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmerrlog.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetErrorLogWrite
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmerrlog.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetFileClose
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetFileEnum
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetFileGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGetAnyDCName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGetDCName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGetDisplayInformationIndex
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupAdd
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupAddUser
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupDel
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupDelUser
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupGetUsers
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupSetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupSetUsers
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetHandleGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmchdev.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetHandleSetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmchdev.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupAdd
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupAddMember
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupAddMembers
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupDel
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupDelMember
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupDelMembers
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupGetMembers
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupSetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupSetMembers
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetMessageBufferSend
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmmsg.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetMessageNameAdd
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmmsg.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetMessageNameDel
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmmsg.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetMessageNameEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmmsg.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetMessageNameGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmmsg.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetQueryDisplayInformation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetRemoteComputerSupports
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmremutl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetRemoteTOD
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmremutl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplExportDirAdd
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplExportDirDel
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplExportDirEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplExportDirGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplExportDirLock
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplExportDirSetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplExportDirUnlock
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplImportDirAdd
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplImportDirDel
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplImportDirEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplImportDirGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplImportDirLock
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplImportDirUnlock
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplSetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetScheduleJobAdd
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmat.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetScheduleJobDel
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmat.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetScheduleJobEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmat.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetScheduleJobGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmat.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServerDiskEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmserver.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServerEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmserver.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServerGetInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	lmserver.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServerSetInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	lmserver.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServerTransportAdd
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmserver.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServerTransportDel
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmserver.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServerTransportEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmserver.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServiceControl
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmsvc.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServiceEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmsvc.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServiceGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmsvc.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServiceInstall
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmsvc.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetSessionDel
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetSessionEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetSessionGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareAdd
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareCheck
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareDel
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareDelSticky
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareEnum
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareEnumSticky
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareGetInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareSetInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.lib
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetStatisticsGet
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmstats.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetStatisticsGet2
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmstats.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUseAdd
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmuse.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUseDel
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmuse.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUseEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmuse.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUseGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmuse.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserAdd
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserChangePassword
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserDel
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserGetGroups
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserGetLocalGroups
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserModalsGet
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserModalsSet
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserSetGroups
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserSetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaSetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaTransportAdd
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaTransportDel
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaTransportEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaUserEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaUserGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaUserSetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NotifyBootConfigStatus
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	No
Platform Notes	None


NotifyChangeEventLog
Windows NT	Yes
Win95	No
Win32s	Yes
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


NSPGetServiceClassInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	Yes
Platform Notes	None


NSPInstallServiceClass
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	Yes
Platform Notes	None


NSPLookupServiceBegin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


NSPLookupServiceEnd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	Yes
Platform Notes	None


NSPLookupServiceNext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	Yes
Platform Notes	None


NSPRemoveServiceClass
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


NSPSetService
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	Yes
Platform Notes	None


NSPStartup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	Yes
Platform Notes	None


ntohl
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


ntohs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


OaBuildVersion
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


ObjectCloseAuditAlarm
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ObjectDeleteAuditAlarm
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ObjectOpenAuditAlarm
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ObjectPrivilegeAuditAlarm
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OemKeyScan
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


OemToChar
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


OemToCharBuff
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


OffsetClipRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


OffsetRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


OffsetRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


OffsetViewportOrgEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


OffsetWindowOrgEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


OleBuildVersion
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.lib
Header File	ole2.h
Unicode	No
Platform Notes	None


OleConvertIStorageToOLESTREAM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleConvertIStorageToOLESTREAMEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleConvertOLESTREAMToIStorage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleConvertOLESTREAMToIStorageEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreateDefaultHandler
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreateEmbeddingHelper
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreateEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreateFontIndirect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	olepro32.dll
Header File	olectl.h
Unicode	Yes
Platform Notes	None


OleCreateFromData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreateFromDataEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreateFromFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreateFromFileEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreateLink
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreateLinkEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreateLinkFromData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreateLinkFromDataEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreateLinkToFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreateLinkToFileEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreateMenuDescriptor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleCreatePictureIndirect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	olepro32.dll
Header File	olectl.h
Unicode	Yes
Platform Notes	None


OleCreatePropertyFrame
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	olepro32.dll
Header File	olectl.h
Unicode	Yes
Platform Notes	None


OleCreatePropertyFrameIndirect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	olepro32.dll
Header File	olectl.h
Unicode	Yes
Platform Notes	None


OleCreateStaticFromData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleDestroyMenuDescriptor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleDoAutoConvert
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleDraw
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleDuplicateData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleFlushClipboard
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleGetAutoConvert
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleGetClipboard
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleGetIconOfClass
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleGetIconOfFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleIconToCursor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	olepro32.dll
Header File	olectl.h
Unicode	Yes
Platform Notes	None


OleInitialize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleIsCurrentClipboard
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleIsRunning
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleLoad
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleLoadFromStream
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleLoadPicture
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	olepro32.dll
Header File	olectl.h
Unicode	Yes
Platform Notes	None


OleLockRunning
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleMetafilePictFromIconAndLabel
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleNoteObjectVisible
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleQueryCreateFromData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleQueryLinkFromData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleRegEnumFormatEtc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleRegEnumVerbs
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleRegGetMiscStatus
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleRegGetUserType
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleRun
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleSave
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleSaveToStream
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleSetAutoConvert
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleSetClipboard
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleSetContainedObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleSetMenuDescriptor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleTranslateAccelerator
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OleTranslateColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	olepro32.dll
Header File	olectl.h
Unicode	Yes
Platform Notes	None


OleUIAddVerbMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	Oledlg.dll
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OleUIBusy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	Oledlg.dll
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OleUICanConvertOrActivateAs
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	Oledlg.dll
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OleUIChangeIcon
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	Oledlg.dll
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OleUIChangeSource
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	Oledlg.dll
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OleUIConvert
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	Oledlg.dll
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OleUIEditLinks
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	Oledlg.dll
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OleUIInsertObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	Oledlg.dll
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OleUIObjectProperties
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	Oledlg.dll
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OleUIPasteSpecial
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	Oledlg.dll
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OleUIPromptUser
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	Oledlg.dll
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OleUIUpdateLinks
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	Oledlg.dll
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OleUninitialize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


OpenBackupEventLog
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OpenClipboard
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


OpenDesktop
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


OpenDriver
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


OpenEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OpenEventLog
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OpenFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


OpenFileMapping
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OpenIcon
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


OpenIMsgOnIStg
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	imessage.h
Unicode	No
Platform Notes	None


OpenIMsgSession
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	imessage.h
Unicode	No
Platform Notes	May not be supported in future versions


OpenInputDesktop
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


OpenMutex
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OpenPrinter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


OpenProcess
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	On Win32s fdwAccess and fInherit ignored (set to PROCESS_ALL_ACCCESS and TRUE)


OpenProcessToken
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


OpenSCManager
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


OpenSemaphore
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OpenService
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


OpenStreamOnFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


OpenThreadToken
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


OpenTnefStream
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	tnef.h
Unicode	No
Platform Notes	None


OpenTnefStreamEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	tnef.h
Unicode	No
Platform Notes	None


OpenWaitableTimer
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OpenWindowStation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


OutputDebugString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


PackDDElParam
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	dde.h
Unicode	No
Platform Notes	None


PageSetupDlg
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	commdlg32.lib
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


PaintDesktop
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


PaintRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PatBlt
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PathToRegion
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PeekConsoleInput
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


PeekMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


PeekNamedPipe
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


phoneClose
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneConfigDialog
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


phoneDevSpecific
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneGetButtonInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


phoneGetData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneGetDevCaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


phoneGetDisplay
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneGetGain
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneGetHookSwitch
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneGetIcon
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


phoneGetID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


phoneGetLamp
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneGetMessage
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneGetRing
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneGetStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


phoneGetStatusMessages
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneGetVolume
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneInitialize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneInitializeEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


phoneNegotiateAPIVersion
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneNegotiateExtVersion
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneOpen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneSetButtonInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


phoneSetData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneSetDisplay
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneSetGain
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneSetHookSwitch
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneSetLamp
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneSetRing
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneSetStatusMessages
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneSetVolume
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


phoneShutdown
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	No
Platform Notes	None


Pie
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PlayEnhMetaFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Skips records which couldn't be processed under Windows 95's GDI: greater than 16-bit coordinates, no shearing or rotations, no dashed widelines, etc.


PlayEnhMetaFileRecord
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Skips records which couldn't be processed under Windows 95's GDI: greater than 16-bit coordinates, no shearing or rotations, no dashed widelines, etc.


PlayMetaFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


PlayMetaFileRecord
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


PlaySound
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


PlgBlt
Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


PolyBezier
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PolyBezierTo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PolyDraw
Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


Polygon
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


Polyline
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PolylineTo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PolyPolygon
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PolyPolyline
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PolyTextOut
Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


PostAppMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


PostMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


PostQueuedCompletionStatus
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


PostQuitMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


PostThreadMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


PpropFindProp
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


PR_RTF_IN_SYNC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PrepareTape
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


PrintDlg
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.lib
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


PrinterMessageBox
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


PrinterProperties
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	No
Platform Notes	None


PrivilegeCheck
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


PrivilegedServiceAuditAlarm
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ProgIDFromCLSID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


PropCopyMore
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


PropertySheet
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	prsht.h
Unicode	WinNT
Platform Notes	None


PropVariantClear
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objidl.h
Unicode	Yes
Platform Notes	None


PropVariantCopy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objidl.h
Unicode	Yes
Platform Notes	None


PtInRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


PtInRegion
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PtVisible
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PulseEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


PurgeComm
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


QueryDosDevice
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


QueryPathOfRegTypeLib
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


QueryPerformanceCounter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


QueryPerformanceFrequency
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


QueryServiceConfig
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


QueryServiceLockStatus
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


QueryServiceObjectSecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	No
Platform Notes	None


QueryServiceStatus
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	No
Platform Notes	None


QueueUserAPC
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


RaiseException
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


RasAdminFreeBuffer
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rassapi.lib
Header File	rassapi.h
Unicode	No
Platform Notes	None


RasAdminGetErrorString
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rassapi.lib
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RasAdminGetUserAccountServer
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rassapi.lib
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RasAdminPortClearStatistics
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rassapi.lib
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RasAdminPortDisconnect
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rassapi.lib
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RasAdminPortEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rassapi.lib
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RasAdminPortGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rassapi.lib
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RasAdminServerGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rassapi.lib
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RasAdminUserGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rassapi.lib
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RasAdminUserSetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rassapi.lib
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RasConnectionNotification
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasCreatePhonebookEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNt
Platform Notes	None


RasDeleteEntry
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasDial
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasDialDlg
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasdlg.lib
Header File	rasdlg.h
Unicode	WinNT
Platform Notes	None


RasEditPhonebookEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNt
Platform Notes	None


RasEntryDlg
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasdlg.lib
Header File	rasdlg.h
Unicode	WinNT
Platform Notes	None


RasEnumAutodialAddresses
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasEnumConnections
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasEnumDevices
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasEnumEntries
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasGetAutodialAddress
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasGetAutodialEnable
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasGetAutodialParam
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasGetConnectStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasGetCountryInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasGetCredentials
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasGetEntryDialParams
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	No
Platform Notes	None


RasGetEntryProperties
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasGetErrorString
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasGetProjectionInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasGetSubEntryHandle
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasGetSubEntryProperties
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasHangUp
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasMonitorDlg
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasdlg.lib
Header File	rasdlg.h
Unicode	WinNT
Platform Notes	None


RasPhonebookDlg
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasdlg.lib
Header File	rasdlg.h
Unicode	WinNT
Platform Notes	None


RasRenameEntry
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasSecurityDialogComplete
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	rasshost.h
Unicode	No
Platform Notes	None


RasSecurityDialogGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	Dynamic load from RASMAN.DLL
Header File	rasshost.h
Unicode	No
Platform Notes	None


RasSecurityDialogReceive
Windows NT	Yes
Win95	No
Win32s	No
Import Library	Dynamic load from RASMAN.DLL
Header File	rasshost.h
Unicode	No
Platform Notes	None


RasSecurityDialogSend
Windows NT	Yes
Win95	No
Win32s	No
Import Library	Dynamic load from RASMAN.DLL
Header File	rasshost.h
Unicode	No
Platform Notes	None


RasSetAutodialAddress
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasSetAutodialEnable
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasSetAutodialParam
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasSetCredentials
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasSetEntryDialParams
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	No
Platform Notes	None


RasSetEntryProperties
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasSetSubEntryProperties
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasValidateEntryName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rasapi32.lib
Header File	ras.h
Unicode	WinNT
Platform Notes	None


ReadClassStg
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


ReadClassStm
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


ReadConsole
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


ReadConsoleInput
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


ReadConsoleOutput
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


ReadConsoleOutputAttribute
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


ReadConsoleOutputCharacter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


ReadDirectoryChangesW
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ReadEventLog
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ReadFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	Windows 95: No overlapped regions, except for serial devices


ReadFileEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	Windows 95 limitations


ReadFmtUserTypeStg
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


ReadPrinter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	No
Platform Notes	None


ReadProcessMemory
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


RealizePalette
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


ReBaseImage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


Rectangle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


RectInRegion
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


RectVisible
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


recv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


recvfrom
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


RedrawWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


RegCloseKey
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.lib
Header File	winreg.h
Unicode	No
Platform Notes	None


RegConnectRegistry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegCreateKey
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegCreateKeyEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegDeleteKey
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegDeleteValue
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegEnumKey
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegEnumKeyEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegEnumValue
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegFlushKey
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.lib
Header File	winreg.h
Unicode	No
Platform Notes	None


RegGetKeySecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winreg.h
Unicode	No
Platform Notes	None


RegisterActiveObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


RegisterClass
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


RegisterClassEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


RegisterClipboardFormat
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


RegisterDialogClasses
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	scrnsave.lib
Header File	scrnsave.h
Unicode	No
Platform Notes	None


RegisterDragDrop
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


RegisterEventSource
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


RegisterHotKey
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


RegisterServiceCtrlHandler
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


RegisterTypeLib
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	All
Platform Notes	All 32-bit OLE Apis are UNICODE only


RegisterWindowMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


RegLoadKey
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegNotifyChangeKeyValue
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winreg.h
Unicode	No
Platform Notes	None


RegOpenKey
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegOpenKeyEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegQueryInfoKey
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegQueryMultipleValues
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegQueryValue
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegQueryValueEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegReplaceKey
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegRestoreKey
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegSaveKey
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegSetKeySecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winreg.h
Unicode	No
Platform Notes	None


RegSetValue
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegSetValueEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegUnLoadKey
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


ReleaseCapture
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ReleaseDC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ReleaseMutex
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


ReleaseSemaphore
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


ReleaseStgMedium
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


RemoveDirectory
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


RemoveFontResource
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


RemoveMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


RemovePrivateCvSymbolic
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


RemoveProp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


RemoveRelocations
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ReplaceText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.lib
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


ReplyMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ReportEvent
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ResetDC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


ResetEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


ResetPrinter
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


ResizePalette
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


RestoreDC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


ResumeThread
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


ReuseDDElParam
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	dde.h
Unicode	No
Platform Notes	None


RevertToSelf
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


RevokeActiveObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


RevokeDragDrop
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


RoundRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


RpcAbnormalTermination
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RpcBindingCopy
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcBindingFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcBindingFromStringBinding
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcBindingInqAuthClient
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcBindingInqAuthInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcBindingInqObject
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcBindingReset
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcBindingServerFromClient
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcBindingSetAuthInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcBindingSetObject
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcBindingToStringBinding
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcBindingVectorFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcCancelThread
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcEndExcept
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RpcEndFinally
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RpcEpRegister
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcEpRegisterNoReplace
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcEpResolveBinding
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcEpUnregister
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcExcept
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RpcExceptionCode
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RpcFinally
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RpcIfIdVectorFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcIfInqId
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcImpersonateClient
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpc.h
Unicode	WinNT
Platform Notes	None


RpcMacSetYieldInfo
Windows NT	No
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File
Unicode	No
Platform Notes	Macintosh Client only


RpcMgmtEnableIdleCleanup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtEpEltInqBegin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtEpEltInqDone
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtEpEltInqNext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtEpUnregister
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtInqComTimeout
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtInqDefaultProtectLevel
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtInqIfIds
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtInqServerPrincName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtInqStats
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtIsServerListening
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtSetAuthorizationFn
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtSetCancelTimeout
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtSetComTimeout
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtSetServerStackSize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtStatsVectorFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtStopServerListening
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtWaitServerListen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcNetworkInqProtseqs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcNetworkIsProtseqValid
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcNsBindingExport
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsBindingImportBegin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsBindingImportDone
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsBindingImportNext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsBindingInqEntryName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcNsBindingLookupBegin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsBindingLookupDone
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsBindingLookupNext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsBindingSelect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsBindingUnexport
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsEntryExpandName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsEntryObjectInqBegin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsEntryObjectInqDone
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsEntryObjectInqNext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsGroupDelete
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsGroupMbrAdd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsGroupMbrInqBegin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsGroupMbrInqDone
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsGroupMbrInqNext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsGroupMbrRemove
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsMgmtBindingUnexport
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsMgmtEntryCreate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsMgmtEntryDelete
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsMgmtEntryInqIfIds
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsMgmtHandleSetExpAge
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsMgmtInqExpAge
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsMgmtSetExpAge
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsProfileDelete
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsProfileEltAdd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsProfileEltInqBegin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsProfileEltInqDone
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsProfileEltInqNext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsProfileEltRemove
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.lib
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcObjectInqType
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcObjectSetInqFn
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcObjectSetType
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcProtseqVectorFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcRaiseException
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcRevertToSelf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpc.h
Unicode	WinNT
Platform Notes	None


RpcRevertToSelfEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpc.h
Unicode	WinNT
Platform Notes	None


RpcServerInqBindings
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerInqIf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerListen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerRegisterAuthInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerRegisterIf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerRegisterIfEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerUnregisterIf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerUseAllProtseqs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerUseAllProtseqsEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerUseAllProtseqsIf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerUseAllProtseqsIfEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerUseProtseq
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerUseProtseqEp
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerUseProtseqEpEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerUseProtseqEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerUseProtseqIf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcServerUseProtseqIfEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcSmAllocate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSmClientFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSmDestroyClientContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSmDisableAllocate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSmEnableAllocate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSmFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSmGetThreadHandle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSmSetClientAllocFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSmSetThreadHandle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSmSwapClientAllocFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSsAllocate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSsDestroyClientContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSsDisableAllocate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSsDontSerializeContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSsEnableAllocate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSsFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSsGetThreadHandle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSsSetClientAllocFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSsSetThreadHandle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcSsSwapClientAllocFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


RpcStringBindingCompose
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcStringBindingParse
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcStringFree
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcTestCancel
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcTryExcept
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RpcTryFinally
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RpcWinSetYieldInfo
Windows NT	No
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File
Unicode	No
Platform Notes	16-bit Windows client only


RpcWinSetYieldTimeout
Windows NT	No
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File
Unicode	No
Platform Notes	16-bit Windows client only


RTFSync
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


RxNetAccessAdd
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


RxNetAccessDel
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


RxNetAccessEnum
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


RxNetAccessGetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


RxNetAccessGetUserPerms
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


RxNetAccessSetInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


RxRemoteApi
Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.lib
Header File	lmremutl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


SafeArrayAccessData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayAllocData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayAllocDescriptor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayCopy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayCreate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayDestroy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayDestroyData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayDestroyDescriptor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayGetDim
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayGetElement
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayGetElemsize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayGetLBound
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayGetUBound
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayLock
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayPtrOfIndex
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayPutElement
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayRedim
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayUnaccessData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayUnlock
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SaveDC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


ScaleViewportExtEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ScaleWindowExtEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ScBinFromHexBounded
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


ScCopyNotifications
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


ScCopyProps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


ScCountNotifications
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


ScCountProps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


ScCreateConversationIndex
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


ScDupPropset
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


ScheduleJob
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	No
Platform Notes	None


ScInitMapiUtil
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


ScLocalPathFromUNC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


ScMAPIXFromCMC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapi.h
Unicode	No
Platform Notes	None


ScMAPIXFromSMAPI
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapi.h
Unicode	No
Platform Notes	None


ScreenSaverConfigureDialog
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	scrnsave.lib
Header File	scrnsave.h
Unicode	No
Platform Notes	None


ScreenSaverProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	scrnsave.lib
Header File	scrnsave.h
Unicode	No
Platform Notes	None


ScreenToClient
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ScRelocNotifications
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


ScRelocProps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


ScrollConsoleScreenBuffer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


ScrollDC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ScrollWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ScrollWindowEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ScUNCFromLocalPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


SearchPath
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


SearchTreeForFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


select
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	Win32s supports WS 1.1


SelectClipPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SelectClipRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SelectObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


SelectPalette
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


send
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


SendDlgItemMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SendDriverMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


SendIMEMessageEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	ime.h
Unicode	Yes
Platform Notes	None


SendMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SendMessageCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SendMessageTimeout
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SendNotifyMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


sendto
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


SetAbortProc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetAclInformation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetActiveWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetArcDirection
Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetAttribIMsgOnIStg
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	imessage.h
Unicode	No
Platform Notes	None


SetBitmapBits
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetBitmapDimensionEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetBkColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetBkMode
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetBoundsRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetBrushOrgEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetCapture
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetCaretBlinkTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetCaretPos
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetClassLong
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SetClassWord
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetClipboardData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetClipboardViewer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetColorAdjustment
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetColorSpace
Windows NT	No
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


SetCommBreak
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetCommConfig
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetCommMask
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetCommState
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetCommTimeouts
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetComputerName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


SetConsoleActiveScreenBuffer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleCP
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleCtrlHandler
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleCursorInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleCursorPosition
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleMode
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleOutputCP
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleScreenBufferSize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleTextAttribute
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleTitle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


SetConsoleWindowInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConvertStg
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


SetCurrentDirectory
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


SetCursor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetCursorPos
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetDebugErrorLevel
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetDefaultCommConfig
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


SetDeviceGammaRamp
Windows NT	No
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


SetDIBColorTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


SetDIBits
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetDIBitsToDevice
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetDlgItemInt
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetDlgItemText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SetDoubleClickTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetEndOfFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetEnhMetaFileBits
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


SetEntriesInAcl
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


SetEnvironmentVariable
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


SetErrorInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


SetErrorMode
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	This is used for RISC platforms only. x86 platforms and Windows 95 return a constant


SetEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetFileApisToANSI
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	On Win32s all file APIs are ANSI


SetFileApisToOEM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	On Win32s all file APIs are ANSI


SetFileAttributes
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


SetFilePointer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetFileSecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


SetFileTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetFocus
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetForegroundWindow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetForm
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


SetGraphicsMode
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Only GM_COMPATIBLE is supported


SetHandleCount
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetHandleInformation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetICMMode
Windows NT	No
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


SetICMProfile
Windows NT	No
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


SetImageConfigInformation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SetJob
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


SetKernelObjectSecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetKeyboardState
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetLastError
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetLastErrorEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetLocaleInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


SetLocalTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetMailslotInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetMapMode
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetMapperFlags
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetMenuContextHelpId
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetMenuDefaultItem
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetMenuItemBitmaps
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetMenuItemInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetMessageExtraInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetMetaFileBitsEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetMetaRgn
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetMiterLimit
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetNamedPipeHandleState
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetNamedSecurityInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	WinNT
Platform Notes	None


SetPaletteEntries
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetParent
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetPixel
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


SetPixelFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


SetPixelV
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetPolyFillMode
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetPort
Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


SetPrinter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


SetPrinterData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


SetPriorityClass
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetPrivateObjectSecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetProcessAffinityMask
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode
Platform Notes	None


SetProcessPriorityBoost
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode
Platform Notes	None


SetProcessShutdownParameters
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetProcessWindowStation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetProcessWorkingSetSize
Windows NT	Yes
Win95	No
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetProp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SetRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetRectEmpty
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetRectRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetROP2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetScrollInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetScrollPos
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetScrollRange
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetSecurityDescriptorDacl
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetSecurityDescriptorGroup
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetSecurityDescriptorOwner
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetSecurityDescriptorSacl
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetSecurityInfo
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	aclapi.h
Unicode	No
Platform Notes	None


SetService
Windows NT	Yes
Win95	No
Win32s	No
Import Library	wsock32.lib
Header File	nspapi.h
Unicode	WinNT
Platform Notes	Obsolete in NT 4.0


SetServiceBits
Windows NT	Yes
Win95	No
Win32s	Yes
Import Library	advapi32.lib
Header File	lmserver.h
Unicode	No
Platform Notes	None


SetServiceObjectSecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	No
Platform Notes	None


SetServiceStatus
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	No
Platform Notes	None


setsockopt
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


SetStdHandle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetStretchBltMode
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetSysColors
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetSystemCursor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetSystemPaletteUse
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetSystemPowerState
Windows NT	No
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetSystemTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetSystemTimeAdjustment
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetTapeParameters
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetTapePosition
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetTextAlign
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetTextCharacterExtra
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetTextColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetTextJustification
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetThreadAffinityMask
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	This is valid on SMP platforms only; Windows 95 returns a constant


SetThreadContext
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetThreadDesktop
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: NOP; only one desktop


SetThreadIdealProcessor
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetThreadLocale
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	Windows 95: Locales are static & can change only at system boot


SetThreadPriority
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetThreadPriorityBoost
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetThreadToken
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetTimer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetTimeZoneInformation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetTokenInformation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetUnhandledExceptionFilter
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetupAddToSourceList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupCancelTemporarySourceList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	No
Platform Notes	None


SetupCloseFileQueue
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	No
Platform Notes	None


SetupCloseInfFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	No
Platform Notes	None


SetupComm
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetupCommitFileQueue
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupCopyError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupDecompressOrCopyFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupDefaultQueueCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupDeleteError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupFindFirstLine
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupFindNextLine
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	No
Platform Notes	None


SetupFindNextMatchLine
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupFreeSourceList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupGetBinaryField
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	No
Platform Notes	None


SetupGetFieldCount
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	No
Platform Notes	None


SetupGetFileCompressionInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupGetInfFileList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupGetInflnformation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupGetIntField
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	No
Platform Notes	None


SetupGetLineByIndex
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupGetLineCount
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupGetLineText
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupGetMultiSzField
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupGetSourceFileLocation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupGetSourceFileSize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupGetSourceInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupGetStringField
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupGetTargetPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupInitDefaultQueueCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	No
Platform Notes	None


SetupInitDefaultQueueCallbackEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	No
Platform Notes	None


SetupInitializeFileLog
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupInstallFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupInstallFileEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupInstallFilesFromInfSection
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupInstallFromInfSection
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupInstallServicesFromInfSection
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupIterateCabinet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupLogFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupOpenAppendInfFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupOpenFileQueue
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	No
Platform Notes	None


SetupOpenInfFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupOpenMasterInf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	No
Platform Notes	None


SetupPromptForDisk
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupPromptReboot
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	No
Platform Notes	None


SetupQueryFileLog
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupQueryInfFileInformation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupQueryInfVersionInformation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupQuerySourceList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupQueueCopy
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupQueueCopySection
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupQueueDefaultCopy
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupQueueDelete
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupQueueDeleteSection
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupQueueRename
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupQueueRenameSection
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupRemoveFileLogEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupRemoveFromSourceList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupRenameError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupScanFileQueue
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupSetDirectoryId
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupSetPlatformPathOverride
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupSetSourceList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SetupTermDefaultQueueCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	No
Platform Notes	None


SetupTerminateFileLog
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	setupapi.lib
Header File	setupapi.h
Unicode	No
Platform Notes	None


SetUserObjectInformation
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SetUserObjectSecurity
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetViewportExtEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetViewportOrgEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetVolumeLabel
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


SetWaitableTimer
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SetWindowContextHelpId
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetWindowExtEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetWindowLong
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SetWindowOrgEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetWindowPlacement
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetWindowPos
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetWindowRgn
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetWindowsHookEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SetWindowText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SetWindowWord
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SetWinMetaFileBits
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


SetWorldTransform
Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


SHAddToRecentDocs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shlobj.h
Unicode	No
Platform Notes	None


SHAppBarMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shellapi.h
Unicode	No
Platform Notes	None


SHBrowseForFolder
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shlobj.h
Unicode	No
Platform Notes	None


SHChangeNotify
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shlobj.h
Unicode	No
Platform Notes	None


Shell_NotifyIcon
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


ShellAbout
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.lib
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


ShellExecute
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.lib
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


ShellExecuteEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


SHFileOperation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


SHFreeNameMappings
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shellapi.h
Unicode	No
Platform Notes	None


SHGetDataFromIDList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shlobj.h
Unicode	WinNT
Platform Notes	None


SHGetDesktopFolder
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shlobj.h
Unicode	No
Platform Notes	None


SHGetFileInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


SHGetInstanceExplorer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shlobj.h
Unicode	No
Platform Notes	None


SHGetMalloc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shlobj.h
Unicode	No
Platform Notes	None


SHGetPathFromIDList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shlobj.h
Unicode	No
Platform Notes	None


SHGetSpecialFolderLocation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shlobj.h
Unicode	No
Platform Notes	None


SHLoadInProc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	shlobj.h
Unicode	No
Platform Notes	None


short_array_from_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


short_from_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


short_from_ndr_temp
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


ShowCaret
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ShowCursor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ShowHideMenuCtl
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ShowOwnedPopups
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ShowScrollBar
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ShowWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ShowWindowAsync
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


shutdown
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


SignalObjectAndWait
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SizeofResource
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


Sleep
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SleepEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


sndPlaySound
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


SnmpMgrClose
Windows NT	Yes
Win95	No
Win32s	No
Import Library	mgmtapi.lib
Header File	mgmtapi.h
Unicode	No
Platform Notes	None


SnmpMgrGetTrap
Windows NT	Yes
Win95	No
Win32s	No
Import Library	mgmtapi.lib
Header File	mgmtapi.h
Unicode	No
Platform Notes	None


SnmpMgrOidToStr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	mgmtapi.lib
Header File	mgmtapi.h
Unicode	No
Platform Notes	None


SnmpMgrOpen
Windows NT	Yes
Win95	No
Win32s	No
Import Library	mgmtapi.lib
Header File	mgmtapi.h
Unicode	No
Platform Notes	None


SnmpMgrRequest
Windows NT	Yes
Win95	No
Win32s	No
Import Library	mgmtapi.lib
Header File	mgmtapi.h
Unicode	No
Platform Notes	None


SnmpMgrStrToOid
Windows NT	Yes
Win95	No
Win32s	No
Import Library	mgmtapi.lib
Header File	mgmtapi.h
Unicode	No
Platform Notes	None


SnmpMgrTrapListen
Windows NT	Yes
Win95	No
Win32s	No
Import Library	mgmtapi.lib
Header File	mgmtapi.h
Unicode	No
Platform Notes	None


SnmpUtilOidAppend
Windows NT	Yes
Win95	No
Win32s	No
Import Library	snmp.lib
Header File	snmp.h
Unicode	No
Platform Notes	None


SnmpUtilOidCmp
Windows NT	Yes
Win95	No
Win32s	No
Import Library	snmp.lib
Header File	snmp.h
Unicode	No
Platform Notes	None


SnmpUtilOidCpy
Windows NT	Yes
Win95	No
Win32s	No
Import Library	snmp.lib
Header File	snmp.h
Unicode	No
Platform Notes	None


SnmpUtilOidFree
Windows NT	Yes
Win95	No
Win32s	No
Import Library	snmp.lib
Header File	snmp.h
Unicode	No
Platform Notes	None


SnmpUtilOidNCmp
Windows NT	Yes
Win95	No
Win32s	No
Import Library	snmp.lib
Header File	snmp.h
Unicode	No
Platform Notes	None


SnmpUtilPrintAsnAny
Windows NT	Yes
Win95	No
Win32s	No
Import Library	snmp.lib
Header File	snmp.h
Unicode	No
Platform Notes	None


SnmpUtilVarBindCpy
Windows NT	Yes
Win95	No
Win32s	No
Import Library	snmp.lib
Header File	snmp.h
Unicode	No
Platform Notes	None


SnmpUtilVarBindFree
Windows NT	Yes
Win95	No
Win32s	No
Import Library	snmp.lib
Header File	snmp.h
Unicode	No
Platform Notes	None


SnmpUtilVarBindListCpy
Windows NT	Yes
Win95	No
Win32s	No
Import Library	snmp.lib
Header File	snmp.h
Unicode	No
Platform Notes	None


SnmpUtilVarBindListFree
Windows NT	Yes
Win95	No
Win32s	No
Import Library	snmp.lib
Header File	snmp.h
Unicode	No
Platform Notes	None


socket
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


SplitSymbols
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


StackWalk
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


StartDoc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


StartDocPrinter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


StartPage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


StartPagePrinter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	No
Platform Notes	None


StartService
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


StartServiceCtrlDispatcher
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


StgCreateDocfile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


StgCreateDocfileOnILockBytes
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


StgIsStorageFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


StgIsStorageILockBytes
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


StgOpenStorage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.lib
Header File	objbase.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


StgOpenStorageOnILockBytes
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.lib
Header File	objbase.h
Unicode	No
Platform Notes	None


StgSetTimes
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


StretchBlt
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


StretchDIBits
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


StringFromCLSID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


StringFromGUID2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


StringFromIID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	Yes
Platform Notes	None


StrokeAndFillPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


StrokePath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SubtractRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SuspendThread
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SwapBuffers
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


SwapMouseButton
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SwitchDesktop
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


SwitchToFiber
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SwitchToThread
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SymCleanup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SymEnumerateModules
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SymEnumerateSymbols
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SymFunctionTableAccess
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SymGetModuleBase
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SymGetModuleInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SymGetOptions
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable. Windows NT: This function is not available under Windows NT 3.51; it was introduced in Windows NT 4.0.


SymGetSearchPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SymGetSymFromAddr
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SymGetSymFromName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SymGetSymNext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable. Windows NT: This function is not available under Windows NT 3.51; it was introduced in Windows NT 4.0.


SymGetSymPrev
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable. Windows NT: This function is not available under Windows NT 3.51; it was introduced in Windows NT 4.0.


SymInitialize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SymLoadModule
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SymRegisterCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable. Windows NT: This function is not available under Windows NT 3.51; it was introduced in Windows NT 4.0.


SymSetOptions
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable. Windows NT: This function is not available under Windows NT 3.51; it was introduced in Windows NT 4.0.


SymSetSearchPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SymUnDName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SymUnloadModule
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


SysAllocString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SysAllocStringByteLen
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SysAllocStringLen
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SysFreeString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SysReAllocString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SysReAllocStringLen
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SysStringByteLen
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SysStringLen
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SystemParametersInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SystemTimeToFileTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SystemTimeToTzSpecificLocalTime
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


SzFindCh
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


SzFindLastCh
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


SzFindSz
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


TabbedTextOut
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


tapiGetLocationInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


tapiRequestMakeCall
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	tapi32.lib
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


TerminateProcess
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


TerminateThread
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


TextOut
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	WinNT; Win95
Platform Notes	Windows 95: 16-bit coordinates only


TileWindows
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


timeBeginPeriod
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


timeEndPeriod
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


timeGetDevCaps
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


timeGetSystemTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


timeGetTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


timeKillEvent
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


timeSetEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


TlsAlloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


TlsFree
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


TlsGetValue
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


TlsSetValue
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


ToAscii
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ToAsciiEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ToUnicode
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


TrackMouseEvent
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


TrackPopupMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


TrackPopupMenuEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


TransactNamedPipe
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


TranslateAccelerator
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


TranslateCharsetInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


TranslateMDISysAccel
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


TranslateMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


TransmitCommChar
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


TransmitFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	mswsock.lib
Header File	mswsock.h
Unicode	No
Platform Notes	Microsoft-specific extension


tree_into_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


tree_peek_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


tree_size_ndr
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcndr.h
Unicode	WinNT
Platform Notes	None


TryEnterCriticalSection
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


UFromSz
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


UlAddRef
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


UlFromSzHex
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


UlPropSize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


UlRelease
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	May not be supported in future versions


UlValidateParameters
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	Intel only


UlValidateParms
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	None


UnDecorateSymbolName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


UnhandledExceptionFilter
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


UnhookWindowsHookEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


UnionRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


UnloadKeyboardLayout
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


UnlockFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


UnlockFileEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


UnlockServiceDatabase
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winsvc.h
Unicode	No
Platform Notes	None


UnMapAndLoad
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


UnmapDebugInformation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


UnmapViewOfFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


UnpackDDElParam
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	dde.h
Unicode	No
Platform Notes	None


UnrealizeObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


UnregisterClass
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


UnregisterHotKey
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


UpdateColors
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


UpdateDebugInfoFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


UpdateDebugInfoFileEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	imagehlp.lib
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable. Windows NT: This function is not available under Windows NT 3.51; it was introduced in Windows NT 4.0.


UpdateICMRegKey
Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


UpdateResource
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


UpdateWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


UuidCompare
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


UuidCreate
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


UuidCreateNil
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


UuidEqual
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


UuidFromString
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


UuidHash
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


UuidIsNil
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


UuidToString
Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.lib
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


ValidateParameters
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	Intel only


ValidateParms
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapival.h
Unicode	No
Platform Notes	None


ValidateRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


ValidateRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


VarBoolFromCy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBoolFromDate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBoolFromDisp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBoolFromI2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBoolFromI4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBoolFromR4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBoolFromR8
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBoolFromStr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBoolFromUI1
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBstrFromBool
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromCy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromDate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromDisp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromI2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromI4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromR4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromR8
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromUI1
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarCyFromBool
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarCyFromDate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarCyFromDisp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarCyFromI2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarCyFromI4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarCyFromR4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarCyFromR8
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarCyFromStr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarCyFromUI1
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromBool
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromCy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromDisp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromI2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromI4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromR4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromR8
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromStr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarDateFromUI1
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromBool
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromCy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromDate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromDisp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromI4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromR4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromR8
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromStr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarI2FromUI1
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromBool
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromCy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromDate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromDisp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromI2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromR4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromR8
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromStr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarI4FromUI1
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VariantChangeType
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VariantChangeTypeEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VariantClear
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VariantCopy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VariantCopyInd
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VariantInit
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VariantTimeToDosDateTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromBool
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromCy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromDate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromDisp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromI2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromI4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromR8
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromStr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarR4FromUI1
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromBool
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromCy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromDate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromDisp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromI2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromI4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromR4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromStr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromUI1
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromBool
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromCy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromDate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromDisp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromI2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromI4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromR4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromR8
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromStr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.lib
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VerFindFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	version.lib
Header File	winver.h
Unicode	WinNT
Platform Notes	None


VerInstallFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	version.lib
Header File	winver.h
Unicode	WinNT
Platform Notes	None


VerLanguageName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winver.h
Unicode	WinNT
Platform Notes	None


VerQueryValue
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	version.lib
Header File	winver.h
Unicode	WinNT
Platform Notes	None


VirtualAlloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualAllocEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualFree
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualFreeEx
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualLock
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualProtect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualProtectEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualQuery
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualQueryEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualUnlock
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


VkKeyScan
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


VkKeyScanEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


WaitCommEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


WaitForDebugEvent
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


WaitForInputIdle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


WaitForMultipleObjects
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


WaitForMultipleObjectsEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


WaitForSingleObject
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


WaitForSingleObjectEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


WaitMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


WaitNamedPipe
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


waveInAddBuffer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInClose
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInGetDevCaps
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


waveInGetErrorText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


waveInGetID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInGetNumDevs
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInGetPosition
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInOpen
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	Win32s: CALLBACK_FUNCTION not supported


waveInPrepareHeader
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInReset
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInStart
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInStop
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInUnprepareHeader
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutBreakLoop
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutClose
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutGetDevCaps
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


waveOutGetErrorText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


waveOutGetID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutGetNumDevs
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutGetPitch
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutGetPlaybackRate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutGetPosition
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutGetVolume
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutOpen
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	Win32s: CALLBACK_FUNCTION not supported


waveOutPause
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutPrepareHeader
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutReset
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutRestart
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutSetPitch
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutSetPlaybackRate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutSetVolume
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutUnprepareHeader
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutWrite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.lib
Header File	mmsystem.h
Unicode	No
Platform Notes	None


wglCopyContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


wglCreateContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


wglCreateLayerContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


wglDeleteContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


wglDescribeLayerPlane
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


wglGetCurrentContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


wglGetCurrentDC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


wglGetLayerPaletteEntries
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


wglGetProcAddress
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


wglMakeCurrent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


wglRealizeLayerPalette
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


wglSetLayerPaletteEntries
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


wglShareLists
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


wglSwapLayerBuffers
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


wglUseFontBitmaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: OpenGL is available as a redistributable


wglUseFontOutlines
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	opengl32.lib
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: OpenGL is available as a redistributable


WideCharToMultiByte
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winnls.h
Unicode	No
Platform Notes	None


WidenPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


WindowFromDC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


WindowFromPoint
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	No
Platform Notes	None


WinExec
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


WinHelp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


WinLoadTrustProvider
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


WinMain
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


WINNLSEnableIME
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winnls32.h
Unicode	Yes
Platform Notes	None


WINNLSGetEnableStatus
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winnls32.h
Unicode	Yes
Platform Notes	None


WINNLSGetIMEHotkey
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winnls32.h
Unicode	Yes
Platform Notes	None


WinSubmitCertificate
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


WinVerifyTrust
Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


WNetAddConnection
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	mpr.lib
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetAddConnection2
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.lib
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetAddConnection3
Windows NT	Yes
Win95	No
Win32s	No
Import Library	mpr.lib
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetCancelConnection
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	mpr.lib
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	Win32: New in 1.3


WNetCancelConnection2
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.lib
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetCloseEnum
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.lib
Header File	winnetwk.h
Unicode	No
Platform Notes	None


WNetConnectionDialog
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.lib
Header File	winnetwk.h
Unicode	No
Platform Notes	None


WNetDisconnectDialog
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.lib
Header File	winnetwk.h
Unicode	No
Platform Notes	None


WNetEnumResource
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.lib
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetGetConnection
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	mpr.lib
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetGetLastError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.lib
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetGetUniversalName
Windows NT	Yes
Win95	No
Win32s	No
Import Library	mpr.lib
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetGetUser
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.lib
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetOpenEnum
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.lib
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WPUCloseEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WPUCloseSocketHandle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WPUCreateEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WPUCreateSocketHandle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WPUFDiSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WPUGetProviderPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WPUModifyIFSHandle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WPUPostMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WPUQueryBlockingCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WPUQuerySocketHandleContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WPUQueueApc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WPUResetEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WPUSetEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WrapCompressedRTFStream
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


WrapStoreEntryID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mapi32.lib
Header File	mapiutil.h
Unicode	No
Platform Notes	None


WriteClassStg
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


WriteClassStm
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


WriteConsole
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


WriteConsoleInput
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


WriteConsoleOutput
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


WriteConsoleOutputAttribute
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	No
Platform Notes	None


WriteConsoleOutputCharacter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


WriteFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	Windows 95: No overlapped regions, except for serial devices


WriteFileEx
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	Windows 95 limitations


WriteFmtUserTypeStg
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	Yes
Platform Notes	None


WritePrinter
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	winspool.h
Unicode	No
Platform Notes	None


WritePrivateProfileSection
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


WritePrivateProfileString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


WritePrivateProfileStruct
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


WriteProcessMemory
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


WriteProfileSection
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


WriteProfileString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


WriteTapemark
Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


WSAAccept
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAAddressToString
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	Yes
Platform Notes	None


WSAAsyncGetHostByAddr
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAAsyncGetHostByName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAAsyncGetProtoByName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAAsyncGetProtoByNumber
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAAsyncGetServByName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAAsyncGetServByPort
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAAsyncSelect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSACancelAsyncRequest
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSACancelBlockingCall
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSACleanup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSACloseEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAConnect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSACreateEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSADuplicateSocket
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	WinNT; Win95
Platform Notes	None


WSAEnumNameSpaceProviders
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	Yes
Platform Notes	None


WSAEnumNetworkEvents
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAEnumProtocols
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	WinNT; Win95
Platform Notes	None


WSAEventSelect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAGetLastError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAGetOverlappedResult
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAGetQOSByName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAGetServiceClassInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	Yes
Platform Notes	None


WSAGetServiceClassNameByServiceClassId
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	Yes
Platform Notes	None


WSAHtonl
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAHtons
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAInstallServiceClass
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	Yes
Platform Notes	None


WSAIoctl
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAIsBlocking
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAJoinLeaf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSALookupServiceBegin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	Yes
Platform Notes	None


WSALookupServiceEnd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSALookupServiceNext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	Yes
Platform Notes	None


WSANtohl
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSANtohs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSApSetPostRoutine
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	Yes
Platform Notes	None


WSARecv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSARecvDisconnect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSARecvEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	mswsock.lib
Header File	mswsock.h
Unicode	No
Platform Notes	Microsoft-specific extension


WSARecvFrom
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSARemoveServiceClass
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAResetEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSASend
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSASendDisconnect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSASendTo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSASetBlockingHook
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSASetEvent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSASetLastError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSASetService
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	Yes
Platform Notes	None


WSASocket
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	WinNT; Win95
Platform Notes	None


WSAStartup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAStringToAddress
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAUnhookBlockingHook
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSAWaitForMultipleEvents
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	ws2_32.lib
Header File	winsock2.h
Unicode	No
Platform Notes	None


WSPAccept
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPAddressToString
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPAsyncSelect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPBind
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPCancelBlockingCall
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPCleanup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPCloseSocket
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPConnect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPDuplicateSocket
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPEnumNetworkEvents
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPEventSelect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPGetOverlappedResult
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPGetPeerName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPGetQOSByName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPGetSockName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPGetSockOpt
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPIoctl
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPJoinLeaf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPListen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPRecv
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPRecvDisconnect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPRecvFrom
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


wsprintf
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


WSPSelect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPSend
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPSendDisconnect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPSendTo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPSetSockOpt
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPShutdown
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPSocket
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPStartup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


WSPStringToAddress
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ws2spi.h
Unicode	No
Platform Notes	None


wvsprintf
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


ZeroMemory
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


Add interface method (Attachments Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Add interface method (Fields Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Add interface method (Messages Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Add interface method (Recipients Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


AddressBook interface method (Session OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Delete interface method (AddressEntry OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Delete interface method (Attachment OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Delete interface method (Attachments Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Delete interface method (Field OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Delete interface method (Fields Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Delete interface method (Folder OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Delete interface method (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Delete interface method (Messages Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Delete interface method (Recipient OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Delete interface method (Recipients Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Details interface method (AddressEntry OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


GetAddressEntry interface method (Session OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


GetFirst interface method (Folders Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


GetFirst interface method (Messages Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


GetFolder interface method (Session OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


GetInfoStore interface method (Session OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


GetLast interface method (Folders Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


GetLast interface method (Messages Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


GetMessage interface method (Session OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


GetNext interface method (Folders Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


GetNext interface method (Messages Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


GetPrevious interface method (Folders Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


GetPrevious interface method (Messages Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


IABContainer::CopyEntries
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IABContainer::CreateEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IABContainer::DeleteEntries
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IABContainer::ResolveNames
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IABLogon::Advise
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IABLogon::CompareEntryIDs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IABLogon::GetLastError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IABLogon::GetOneOffTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IABLogon::Logoff
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IABLogon::OpenEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IABLogon::OpenStatusEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IABLogon::OpenTemplateID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IABLogon::PrepareRecips
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IABLogon::Unadvise
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IABProvider::Logon
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IABProvider::Shutdown
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IAddrBook::Address
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	WinNT
Platform Notes	None


IAddrBook::Advise
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IAddrBook::CompareEntryIDs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IAddrBook::CreateOneOff
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	WinNT
Platform Notes	None


IAddrBook::Details
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	WinNT
Platform Notes	None


IAddrBook::GetDefaultDir
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IAddrBook::GetPAB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IAddrBook::GetSearchPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IAddrBook::NewEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IAddrBook::OpenEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IAddrBook::PrepareRecips
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IAddrBook::QueryDefaultRecipOpt
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IAddrBook::RecipOptions
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IAddrBook::ResolveName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	WinNT
Platform Notes	None


IAddrBook::SetDefaultDir
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IAddrBook::SetPAB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IAddrBook::SetSearchPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IAddrBook::Unadvise
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IAdviseSink
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IAdviseSink::OnClose
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IAdviseSink::OnDataChange
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IAdviseSink::OnRename
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IAdviseSink::OnSave
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IAdviseSink::OnViewChange
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IAdviseSink2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IAdviseSink2::OnLinkSrcChange
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IAdviseSinkEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IAdviseSinkEx::OnViewStatusChange
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IAVIEditStream::Clone
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIEditStream::Copy
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIEditStream::Cut
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIEditStream::Paste
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIEditStream::SetInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIFile::CreateStream
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIFile::EndRecord
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIFile::GetStream
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIFile::Info
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIFile::Open
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIFile::ReadData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIFile::WriteData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIStream::Create
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIStream::Delete
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIStream::FindSample
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIStream::Info
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIStream::Read
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIStream::ReadData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIStream::ReadFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIStream::SetFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIStream::Write
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIStream::WriteData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIStreaming::Begin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IAVIStreaming::End
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IBindCtx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IBindCtx::EnumObjectParam
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IBindCtx::GetBindOptions
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IBindCtx::GetObjectParam
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IBindCtx::GetRunningObjectTable
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IBindCtx::RegisterObjectBound
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IBindCtx::RegisterObjectParam
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IBindCtx::ReleaseBoundObjects
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IBindCtx::RevokeObjectBound
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IBindCtx::RevokeObjectParam
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IBindCtx::SetBindOptions
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IClassFactory
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	unknwn.h
Unicode	Yes
Platform Notes	None


IClassFactory::CreateInstance
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	unknwn.h
Unicode	Yes
Platform Notes	None


IClassFactory::LockServer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	unknwn.h
Unicode	Yes
Platform Notes	None


IClassFactory2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IClassFactory2::CreateInstanceLic
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IClassFactory2::GetLicInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IClassFactory2::RequestLicKey
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IClientSecurity
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IClientSecurity::CopyProxy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IClientSecurity::QueryBlanket
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IClientSecurity::SetBlanket
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


ICommDlgBrowser::IncludeObject
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


ICommDlgBrowser::OnDefaultCommand
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


ICommDlgBrowser::OnStateChange
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IConnectionPoint
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IConnectionPoint::Advise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IConnectionPoint::EnumConnections
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IConnectionPoint::GetConnectionInterface
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IConnectionPoint::GetConnectionPointContainer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IConnectionPoint::Unadvise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IConnectionPointContainer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IConnectionPointContainer::EnumConnectionPoints
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IConnectionPointContainer::FindConnectionPoint
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IContextMenu::GetCommandString
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IContextMenu::InvokeCommand
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IContextMenu::QueryContextMenu
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IContextMenu2::GetCommandString
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IContextMenu2::HandleMenuMsg
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IContextMenu2::InvokeCommand
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IContextMenu2::QueryContextMenu
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


ICopyHook::CopyCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IDataAdviseHolder
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IDataAdviseHolder::Advise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IDataAdviseHolder::EnumAdvise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IDataAdviseHolder::SendOnDataChange
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IDataAdviseHolder::Unadvise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IDataObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IDataObject::DAdvise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IDataObject::DUnadvise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IDataObject::EnumDAdvise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IDataObject::EnumFormatEtc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IDataObject::GetCanonicalFormatEtc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IDataObject::GetData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IDataObject::GetDataHere
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IDataObject::QueryGetData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IDataObject::SetData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IDirect3D::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3D::CreateLight
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3D::CreateMaterial
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3D::CreateViewport
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3D::EnumDevices
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3D::FindDevice
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3D::Initialize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3D::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3D::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::AddViewport
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::BeginScene
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::CreateExecuteBuffer
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::CreateMatrix
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::DeleteMatrix
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::DeleteViewport
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::EndScene
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::EnumTextureFormats
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::Execute
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::GetCaps
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::GetDirect3D
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::GetMatrix
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::GetPickRecords
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::GetStats
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::Initialize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::NextViewport
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::Pick
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::SetMatrix
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DDevice::SwapTextureHandles
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DExecuteBuffer::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DExecuteBuffer::GetExecuteData
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DExecuteBuffer::Initialize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DExecuteBuffer::Lock
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DExecuteBuffer::Optimize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DExecuteBuffer::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DExecuteBuffer::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DExecuteBuffer::SetExecuteData
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DExecuteBuffer::Unlock
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DExecuteBuffer::Validate
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DLight::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DLight::GetLight
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DLight::Initialize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DLight::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DLight::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DLight::SetLight
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DMaterial::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DMaterial::GetHandle
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DMaterial::GetMaterial
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DMaterial::Initialize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DMaterial::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DMaterial::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DMaterial::Reserve
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DMaterial::SetMaterial
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DMaterial::Unreserve
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DRM::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::AddSearchPath
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateAnimation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateAnimationSet
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateDevice
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateDeviceFromClipper
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateDeviceFromD3D
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateDeviceFromSurface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateFace
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateFrame
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateLight
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateLightRGB
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateMaterial
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateMesh
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateMeshBuilder
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateObject
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateShadow
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateTexture
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateTextureFromSurface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateUserVisual
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateViewport
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::CreateWrap
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::EnumerateObjects
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::GetDevices
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::GetNamedObject
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::GetSearchPath
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::Load
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::LoadTexture
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::LoadTextureFromResource
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::SetDefaultTextureColors
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::SetDefaultTextureShades
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::SetSearchPath
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRM::Tick
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimation::AddPositionKey
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimation::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimation::AddRotateKey
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimation::AddScaleKey
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimation::DeleteKey
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimation::GetOptions
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimation::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimation::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimation::SetFrame
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimation::SetOptions
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimation::SetTime
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimationSet::AddAnimation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimationSet::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimationSet::DeleteAnimation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimationSet::Load
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimationSet::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimationSet::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMAnimationSet::SetTime
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMArray::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMArray::GetSize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMArray::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMArray::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::AddUpdateCallback
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::DeleteUpdateCallback
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::GetBufferCount
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::GetColorModel
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::GetDirect3DDevice
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::GetDither
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::GetHeight
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::GetQuality
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::GetShades
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::GetTextureQuality
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::GetTrianglesDrawn
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::GetViewports
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::GetWidth
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::GetWireframeOptions
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::Init
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::InitFromClipper
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::InitFromD3D
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::SetBufferCount
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::SetDither
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::SetQuality
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::SetShades
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::SetTextureQuality
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDevice::Update
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDeviceArray::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDeviceArray::GetElement
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDeviceArray::GetSize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDeviceArray::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMDeviceArray::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::AddVertex
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::AddVertexAndNormalIndexed
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::GetColor
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::GetMaterial
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::GetNormal
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::GetTexture
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::GetTextureCoordinateIndex
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::GetTextureCoordinates
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::GetTextureTopology
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::GetVertex
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::GetVertexCount
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::GetVertexIndex
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::GetVertices
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::SetColor
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::SetColorRGB
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::SetMaterial
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::SetTexture
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::SetTextureCoordinates
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFace::SetTextureTopology
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFaceArray::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFaceArray::GetElement
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFaceArray::GetSize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFaceArray::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFaceArray::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::AddChild
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::AddLight
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::AddMoveCallback
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::AddRotation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::AddScale
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::AddTransform
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::AddTranslation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::AddVisual
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::DeleteChild
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::DeleteLight
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::DeleteMoveCallback
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::DeleteVisual
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetChildren
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetColor
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetLights
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetMaterialMode
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetOrientation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetParent
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetPosition
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetRotation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetScene
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetSceneBackground
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetSceneBackgroundDepth
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetSceneFogColor
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetSceneFogEnable
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetSceneFogMode
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetSceneFogParams
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetSortMode
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetTexture
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetTextureTopology
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetTransform
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetVelocity
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetVisuals
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::GetZbufferMode
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::InverseTransform
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::Load
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::LookAt
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::Move
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetColor
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetColorRGB
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetMaterialMode
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetOrientation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetPosition
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetRotation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetSceneBackground
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetSceneBackgroundDepth
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetSceneBackgroundImage
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetSceneBackgroundRGB
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetSceneFogColor
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetSceneFogEnable
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetSceneFogMode
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetSceneFogParams
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetSortMode
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetTexture
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetTextureTopology
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetVelocity
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::SetZbufferMode
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrame::Transform
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrameArray::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrameArray::GetElement
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrameArray::GetSize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrameArray::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMFrameArray::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::GetColor
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::GetConstantAttenuation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::GetEnableFrame
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::GetLinearAttenuation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::GetPenumbra
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::GetQuadraticAttenuation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::GetRange
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::GetType
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::GetUmbra
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::SetColor
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::SetColorRGB
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::SetConstantAttenuation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::SetEnableFrame
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::SetLinearAttenuation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::SetPenumbra
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::SetQuadraticAttenuation
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::SetRange
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::SetType
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLight::SetUmbra
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLightArray::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLightArray::GetElement
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLightArray::GetSize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLightArray::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMLightArray::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMaterial::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMaterial::GetEmissive
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMaterial::GetPower
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMaterial::GetSpecular
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMaterial::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMaterial::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMaterial::SetEmissive
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMaterial::SetPower
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMaterial::SetSpecular
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::AddGroup
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::GetBox
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::GetGroup
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::GetGroupColor
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::GetGroupCount
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::GetGroupMapping
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::GetGroupMaterial
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::GetGroupQuality
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::GetGroupTexture
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::GetVertices
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::Scale
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::SetGroupColor
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::SetGroupColorRGB
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::SetGroupMapping
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::SetGroupMaterial
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::SetGroupQuality
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::SetGroupTexture
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::SetVertices
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMesh::Translate
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::AddFace
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::AddFaces
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::AddFrame
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::AddMesh
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::AddMeshBuilder
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::AddNormal
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::AddVertex
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::CreateFace
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::CreateMesh
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::GenerateNormals
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::GetBox
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::GetColorSource
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::GetFaceCount
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::GetFaces
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::GetPerspective
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::GetQuality
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::GetTextureCoordinates
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::GetVertexColor
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::GetVertexCount
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::GetVertices
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::Load
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::ReserveSpace
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::Save
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::Scale
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::SetColor
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::SetColorRGB
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::SetColorSource
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::SetMaterial
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::SetNormal
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::SetPerspective
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::SetQuality
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::SetTexture
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::SetTextureCoordinates
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::SetTextureTopology
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::SetVertex
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::SetVertexColor
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::SetVertexColorRGB
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMMeshBuilder::Translate
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMObject::AddDestroyCallback
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMObject::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMObject::Clone
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMObject::DeleteDestroyCallback
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMObject::GetAppData
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMObject::GetClassName
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMObject::GetName
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMObject::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMObject::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMObject::SetAppData
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMObject::SetName
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMPickedArray::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMPickedArray::GetPick
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMPickedArray::GetSize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMPickedArray::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMPickedArray::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMShadow::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMShadow::Init
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMShadow::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMShadow::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::Changed
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::GetColors
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::GetDecalOrigin
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::GetDecalScale
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::GetDecalSize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::GetDecalTransparency
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::GetDecalTransparentColor
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::GetImage
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::GetOpacity
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::GetShades
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::InitFromFile
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::InitFromResource
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::InitFromSurface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::SetColors
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::SetDecalOrigin
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::SetDecalScale
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::SetDecalSize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::SetDecalTransparency
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::SetDecalTransparentColor
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::SetOpacity
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMTexture::SetShades
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMUserVisual::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMUserVisual::Init
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMUserVisual::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMUserVisual::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::Clear
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::Configure
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::ForceUpdate
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::GetBack
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::GetCamera
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::GetDevice
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::GetDirect3DViewport
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::GetField
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::GetFront
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::GetHeight
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::GetPlane
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::GetProjection
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::GetUniformScaling
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::GetWidth
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::GetX
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::GetY
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::Init
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::InverseTransform
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::Pick
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::Render
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::SetBack
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::SetCamera
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::SetField
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::SetFront
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::SetPlane
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::SetProjection
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::SetUniformScaling
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewport::Transform
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewportArray::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewportArray::GetElement
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewportArray::GetSize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewportArray::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMViewportArray::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMVisualArray::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMVisualArray::GetElement
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMVisualArray::GetSize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMVisualArray::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMVisualArray::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMWinDevice::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMWinDevice::HandleActivate
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMWinDevice::HandlePaint
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMWinDevice::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMWinDevice::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMWrap::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMWrap::Apply
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMWrap::ApplyRelative
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMWrap::Init
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMWrap::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DRMWrap::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


IDirect3DTexture::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DTexture::GetHandle
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DTexture::Initialize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DTexture::Load
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DTexture::PaletteChanged
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DTexture::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DTexture::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DTexture::Unload
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::AddLight
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::AddRef
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::Clear
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::DeleteLight
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::GetBackground
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::GetBackgroundDepth
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::GetViewport
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::Initialize
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::LightElements
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::NextLight
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::QueryInterface
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::Release
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::SetBackground
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::SetBackgroundDepth
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::SetViewport
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirect3DViewport::TransformVertices
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::AddRef
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::Compact
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::CreateClipper
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::CreatePalette
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::CreateSurface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::DuplicateSurface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::EnumSurfaces
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::FlipToGDISurface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::GetCaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::GetDisplayMode
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::GetFourCCCodes
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::GetGDISurface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::GetMonitorFrequency
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::GetScanLine
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::GetVerticalBlankStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::Initialize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::QueryInterface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::Release
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::RestoreDisplayMode
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::SetCooperativeLevel
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw::WaitForVerticalBlank
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw2::EnumDisplayModes
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw2::GetAvailableVidMem
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDraw2::SetDisplayMode
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawClipper::AddRef
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawClipper::GetClipList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawClipper::GetHWnd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawClipper::Initialize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawClipper::IsClipListChanged
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawClipper::QueryInterface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawClipper::Release
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawClipper::SetClipList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawClipper::SetHWnd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawPalette::AddRef
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawPalette::GetCaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawPalette::GetEntries
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawPalette::Initialize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawPalette::QueryInterface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawPalette::Release
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawPalette::SetEntries
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::AddAttachedSurface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::AddOverlayDirtyRect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::AddRef
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::Blt
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::BltBatch
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::BltFast
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::DeleteAttachedSurface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::EnumAttachedSurfaces
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::EnumOverlayZOrders
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::Flip
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::GetAttachedSurface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::GetBltStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::GetCaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::GetClipper
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::GetColorKey
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::GetDC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::GetFlipStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::GetOverlayPosition
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::GetPalette
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::GetPixelFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::GetSurfaceDesc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::Initialize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::IsLost
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::Lock
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::QueryInterface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::Release
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::ReleaseDC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::Restore
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::SetClipper
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::SetColorKey
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::SetOverlayPosition
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::SetPalette
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::Unlock
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::UpdateOverlay
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::UpdateOverlayDisplay
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface::UpdateOverlayZOrder
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface2::GetDDInterface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface2::PageLock
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectDrawSurface2::PageUnlock
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


IDirectPlay::AddPlayerToGroup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::AddRef
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::Close
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::CreateGroup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::CreatePlayer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::DeletePlayerFromGroup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::DestroyGroup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::DestroyPlayer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::EnableNewPlayers
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::EnumGroupPlayers
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::EnumGroups
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::EnumPlayers
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::EnumSessions
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::GetCaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::GetMessageCount
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::GetPlayerCaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::GetPlayerName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::Initialize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::Open
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::QueryInterface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::Receive
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::Release
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::SaveSession
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::Send
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectPlay::SetPlayerName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


IDirectSound::AddRef
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSound::Compact
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSound::CreateSoundBuffer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSound::DuplicateSoundBuffer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSound::GetCaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSound::GetSpeakerConfig
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSound::Initialize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSound::QueryInterface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSound::Release
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSound::SetCooperativeLevel
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSound::SetSpeakerConfig
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::AddRef
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::GetCaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::GetCurrentPosition
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::GetFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::GetFrequency
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::GetPan
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::GetStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::GetVolume
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::Initialize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::Lock
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::Play
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::QueryInterface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::Release
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::Restore
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::SetCurrentPosition
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::SetFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::SetFrequency
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::SetPan
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::SetVolume
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::Stop
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDirectSoundBuffer::Unlock
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


IDropSource
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IDropSource::GiveFeedback
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IDropSource::QueryContinueDrag
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IDropTarget
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IDropTarget::DragEnter
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IDropTarget::DragLeave
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IDropTarget::DragOver
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IDropTarget::Drop
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IEnumConnectionPoints
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IEnumConnections
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IEnumFORMATETC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IEnumIDList::Clone
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IEnumIDList::Next
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IEnumIDList::Reset
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IEnumIDList::Skip
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IEnumMoniker
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IEnumOleUndoUnits
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IEnumOLEVERB
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IEnumSTATDATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IEnumSTATPROPSETSTG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IEnumSTATPROPSTG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IEnumSTATSTG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IEnumString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IEnumUnknown
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IErrorLog
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IErrorLog::AddError
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IExternalConnection
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IExternalConnection::AddConnection
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IExternalConnection::ReleaseConnection
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IExtractIcon::Extract
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IExtractIcon::GetIconLocation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IFileViewer::PrintTo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IFileViewer::Show
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IFileViewer::ShowInitialize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IFileViewerSite::GetPinnedWindow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IFileViewerSite::SetPinnedWindow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IFont
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::AddRefHfont
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::Clone
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::get_Bold
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::get_Charset
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::get_hFont
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::get_Italic
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::get_Name
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::get_Size
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::get_Strikethrough
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::get_Underline
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::get_Weight
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::IsEqual
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::put_Bold
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::put_Charset
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::put_Italic
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::put_Name
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::put_Size
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::put_Strikethrough
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::put_Underline
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::put_Weight
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::QueryTextMetrics
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::ReleaseHfont
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::SetHdc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFont::SetRatio
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IFontDisp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IGetFrame::Begin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IGetFrame::End
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IGetFrame::GetFrame
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


IGetFrame::SetFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.lib
Header File	vfw.h
Unicode
Platform Notes	None


ILockBytes
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


ILockBytes::Flush
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


ILockBytes::LockRegion
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


ILockBytes::ReadAt
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


ILockBytes::SetSize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


ILockBytes::Stat
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


ILockBytes::UnlockRegion
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


ILockBytes::WriteAt
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMalloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMalloc::Alloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMalloc::DidAlloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMalloc::Free
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMalloc::GetSize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMalloc::HeapMinimize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMalloc::Realloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMallocSpy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMallocSpy::PostAlloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMallocSpy::PostDidAlloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMallocSpy::PostFree
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMallocSpy::PostGetSize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMallocSpy::PostHeapMinimize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMallocSpy::PostRealloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMallocSpy::PreAlloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMallocSpy::PreDidAlloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMallocSpy::PreFree
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMallocSpy::PreGetSize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMallocSpy::PreHeapMinimize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMallocSpy::PreRealloc
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMAPIAdviseSink::OnNotify
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIContainer::GetContentsTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIContainer::GetHierarchyTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIContainer::GetSearchCriteria
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIContainer::OpenEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIContainer::SetSearchCriteria
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIControl::Activate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIControl::GetLastError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIControl::GetState
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIFolder::CopyFolder
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIFolder::CopyMessages
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIFolder::CreateFolder
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIFolder::CreateMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIFolder::DeleteFolder
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIFolder::DeleteMessages
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIFolder::EmptyFolder
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIFolder::GetMessageStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIFolder::SaveContentsSort
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIFolder::SetMessageStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIFolder::SetReadFlags
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIForm::Advise
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIForm::DoVerb
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIForm::GetViewContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIForm::SetViewContext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIForm::ShutdownForm
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIForm::Unadvise
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormAdviseSink::OnActivateNext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormAdviseSink::OnChange
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormContainer::CalcFormPropSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormContainer::GetDisplay
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormContainer::InstallForm
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormContainer::RemoveForm
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormContainer::ResolveMessageClass
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormContainer::ResolveMultipleMessageClasses
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormFactory::CreateClassFactory
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormFactory::LockServer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormInfo::CalcFormPropSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormInfo::CalcVerbSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormInfo::MakeIconFromBinary
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormInfo::OpenFormContainer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormInfo::SaveForm
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormMgr::CalcFormPropSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormMgr::CreateForm
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormMgr::IsInConflict
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormMgr::LoadForm
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormMgr::OpenFormContainer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormMgr::PrepareForm
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormMgr::ResolveMessageClass
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormMgr::ResolveMultipleMessageClasses
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormMgr::SelectForm
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormMgr::SelectFormContainer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIFormMgr::SelectMultipleForms
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIMessageSite::CopyMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIMessageSite::DeleteMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIMessageSite::GetFolder
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIMessageSite::GetFormManager
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIMessageSite::GetMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIMessageSite::GetSession
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIMessageSite::GetSiteStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIMessageSite::GetStore
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIMessageSite::MoveMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIMessageSite::NewMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIMessageSite::SaveMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIMessageSite::SubmitMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIProgress::GetFlags
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIProgress::GetMax
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIProgress::GetMin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIProgress::Progress
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIProgress::SetLimits
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIProp::CopyProps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIProp::CopyTo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIProp::DeleteProps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIProp::GetIDsFromNames
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIProp::GetLastError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIProp::GetNamesFromIDs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIProp::GetPropList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIProp::GetProps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIProp::Openproperty
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIProp::SaveChanges
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIProp::SetProps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPISession::AdminServices
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::Advise
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::CompareEntryIDs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::EnumAdrTypes
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::GetLastError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::GetMsgStoresTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::GetStatusTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::Logoff
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::MessageOptions
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::OpenAddressBook
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::OpenEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::OpenMsgStore
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::OpenProfileSection
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::PrepareForm
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::QueryDefaultMessageOpt
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::QueryIdentity
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::SetDefaultStore
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::ShowForm
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPISession::Unadvise
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMAPIStatus::ChangePassword
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIStatus::FlushQueues
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIStatus::SettingsDialog
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIStatus::ValidateState
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPISupport::Address
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::CompareEntryIDs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::CompleteMsg
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::CopyFolder
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::CopyMessages
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::CreateOneOff
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::Details
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::DoConfigPropsheet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::DoCopyProps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::DoCopyTo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::DoProgressDialog
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::DoSentMail
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::ExpandRecips
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::GetLastError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::GetMemAllocRoutines
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::GetOneOffTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::GetSvcConfigSupportObj
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::IStorageFromStream
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::MakeInvalid
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::ModifyProfile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::ModifyStatusRow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::NewEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::NewUID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::Notify
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::OpenAddressBook
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::OpenEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::OpenProfileSection
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::OpenTemplateID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::PrepareSubmit
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::ReadReceipt
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::RegisterPreprocessor
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::SetProviderUID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::SpoolerNotify
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::SpoolerYield
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::StatusRecips
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::StoreLogoffTransports
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::Subscribe
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::Unsubscribe
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPISupport::WrapStoreEntryID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMAPITable::Abort
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::Advise
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::CollapseRow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::CreateBookmark
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::ExpandRow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::FindRow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::FreeBookmark
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::GetCollapseState
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::GetLastError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::GetRowCount
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::GetStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::QueryColumns
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::QueryPosition
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::QueryRows
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::QuerySortOrder
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::Restrict
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::SeekRow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::SeekRowApprox
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::SetCollapseState
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::SetColumns
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::SortTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::Unadvise
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPITable::WaitForCompletion
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMAPIViewAdviseSink::OnNewMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIViewAdviseSink::OnPrint
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIViewAdviseSink::OnSaved
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIViewAdviseSink::OnShutdown
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIViewAdviseSink::OnSubmitted
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIViewContext::ActivateNext
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIViewContext::GetPrintSetup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIViewContext::GetSaveStream
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIViewContext::GetViewStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMAPIViewContext::SetAdviseSink
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IMarshal
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMarshal::DisconnectObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMarshal::GetMarshalSizeMax
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMarshal::GetUnmarshalClass
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMarshal::MarshalInterface
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMarshal::ReleaseMarshalData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMarshal::UnmarshalInterface
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMessage::CreateAttach
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMessage::DeleteAttach
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMessage::GetAttachmentTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMessage::GetRecipientTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMessage::ModifyRecipients
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMessage::OpenAttach
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMessage::SetReadFlag
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMessage::SubmitMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMessageFilter
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMessageFilter::HandleInComingCall
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMessageFilter::MessagePending
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMessageFilter::RetryRejectedCall
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker::BindToObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker::BindToStorage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker::CommonPrefixWith
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker::ComposeWith
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker::Enum
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker::GetDisplayName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker::GetTimeOfLastChange
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker::Hash
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker::Inverse
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker::IsEqual
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker::IsRunning
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker::IsSystemMoniker
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker::ParseDisplayName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker::Reduce
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMoniker::RelativePathTo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMsgServiceAdmin::AdminProviders
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMsgServiceAdmin::ConfigureMsgService
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMsgServiceAdmin::CopyMsgService
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMsgServiceAdmin::CreateMsgService
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMsgServiceAdmin::DeleteMsgService
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMsgServiceAdmin::GetLastError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMsgServiceAdmin::GetMsgServiceTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMsgServiceAdmin::GetProviderTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMsgServiceAdmin::MsgServiceTransportOrder
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMsgServiceAdmin::OpenProfileSection
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMsgServiceAdmin::RenameMsgService
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMsgServiceAdmin::SetPrimaryIdentity
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IMsgStore::AbortSubmit
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMsgStore::Advise
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMsgStore::CompareEntryIDs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMsgStore::FinishedMsg
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMsgStore::GetOutgoingQueue
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMsgStore::GetReceiveFolder
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMsgStore::GetReceiveFolderTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMsgStore::NotifyNewMail
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMsgStore::OpenEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMsgStore::SetLockState
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMsgStore::SetReceiveFolder
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMsgStore::StoreLogoff
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMsgStore::Unadvise
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IMSLogon::Advise
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMSLogon::CompareEntryIDs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMSLogon::GetLastError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMSLogon::Logoff
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMSLogon::OpenEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMSLogon::OpenStatusEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMSLogon::Unadvise
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMSProvider::CompareStoreIDs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMSProvider::Logon
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMSProvider::Shutdown
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMSProvider::SpoolerLogon
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IMultiQI
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IMultiQI::QueryMultipleInterfaces
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


INotifyReplica::YouAreAReplica
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	reconcil.h
Unicode	No
Platform Notes	None


IObjectWithSite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IObjectWithSite::GetSite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IObjectWithSite::SetSite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleAdviseHolder
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleAdviseHolder::Advise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleAdviseHolder::EnumAdvise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleAdviseHolder::SendOnClose
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleAdviseHolder::SendOnRename
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleAdviseHolder::SendOnSave
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleAdviseHolder::Unadvise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleCache
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleCache::Cache
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleCache::EnumCache
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleCache::InitCache
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleCache::SetData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleCache::Uncache
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleCache2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleCache2::DiscardCache
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleCache2::UpdateCache
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleCacheControl
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleCacheControl::OnRun
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleCacheControl::OnStop
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleClientSite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleClientSite::GetContainer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleClientSite::GetMoniker
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleClientSite::OnShowWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleClientSite::RequestNewObjectLayout
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleClientSite::SaveObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleClientSite::ShowObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleContainer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleContainer::EnumObjects
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleContainer::LockContainer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleControl
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleControl::FreezeEvents
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleControl::GetControlInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleControl::OnAmbientPropertyChange
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleControl::OnMnemonic
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleControlSite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleControlSite::GetExtendedControl
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleControlSite::LockInPlaceActive
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleControlSite::OnControlInfoChanged
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleControlSite::OnFocus
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleControlSite::ShowPropertyFrame
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleControlSite::TransformCoords
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleControlSite::TranslateAccelerator
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceActiveObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceActiveObject::EnableModeless
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceActiveObject::OnDocWindowActivate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceActiveObject::OnFrameWindowActivate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceActiveObject::ResizeBorder
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceActiveObject::TranslateAccelerator
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceFrame
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceFrame::EnableModeless
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceFrame::InsertMenus
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceFrame::RemoveMenus
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceFrame::SetMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceFrame::SetStatusText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceFrame::TranslateAccelerator
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceObject::InPlaceDeactivate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceObject::ReactivateAndUndo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceObject::SetObjectRects
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceObject::UIDeactivate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceObjectWindowless
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceObjectWindowless::GetDropTarget
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceObjectWindowlessOnWindowMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSite::CanInPlaceActivate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSite::DeactivateAndUndo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSite::DiscardUndoState
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSite::GetWindowContext
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSite::OnInPlaceActivate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSite::OnInPlaceDeactivate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSite::OnPosRectChange
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSite::OnUIActivate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSite::OnUIDeactivate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSite::Scroll
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteEx::OnInPlaceActivateEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteEx::OnInPlaceDeactivateEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteEx::RequestUIActivate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteWindowless
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteWindowless::AdjustRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteWindowless::CanWindowlessActivate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteWindowless::GetCapture
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteWindowless::GetDC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteWindowless::InvalidateRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteWindowless::InvalidateRgn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteWindowless::OnDefWindowMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteWindowless::ReleaseDC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteWindowless::ScrollRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteWindowless::SetCapture
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteWindowless::SetFocus
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceSiteWindowless:GetFocus
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceUIWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceUIWindow::GetBorder
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceUIWindow::RequestBorderSpace
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceUIWindow::SetActiveObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleInPlaceUIWindow::SetBorderSpace
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleItemContainer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleItemContainer::GetObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleItemContainer::GetObjectStorage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleItemContainer::IsRunning
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleLink
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleLink::BindIfRunning
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleLink::BindToSource
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleLink::GetBoundSource
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleLink::GetSourceDisplayName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleLink::GetSourceMoniker
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleLink::GetUpdateOptions
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleLink::SetSourceDisplayName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleLink::SetSourceMoniker
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleLink::SetUpdateOptions
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleLink::UnbindSource
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleLink::Update
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::Advise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::Close
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::DoVerb
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::EnumAdvise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::EnumVerbs
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::GetClientSite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::GetClipboardData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::GetExtent
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::GetMiscStatus
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::GetMoniker
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::GetUserClassID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::GetUserType
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::InitFromData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::IsUpToDate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::SetClientSite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::SetColorScheme
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::SetExtent
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::SetHostNames
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::SetMoniker
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::Unadvise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleObject::Update
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleParentUndoUnit
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleParentUndoUnit::Add
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleParentUndoUnit::Close
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleParentUndoUnit::FindUnit
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleParentUndoUnit::GetParentState
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleParentUndoUnit::Open
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUILinkContainer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUILinkContainer::CancelLink
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUILinkContainer::GetLinkSource
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUILinkContainer::GetLinkUpdateOptions
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUILinkContainer::GetNextLink
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUILinkContainer::OpenLinkSource
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUILinkContainer::SetLinkSource
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUILinkContainer::SetLinkUpdateOptions
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUILinkContainer::UpdateLink
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUILinkInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUILinkInfo::GetLastUpdate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUIObjInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUIObjInfo::ConvertObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUIObjInfo::GetConvertInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUIObjInfo::GetObjectInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUIObjInfo::GetViewInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUIObjInfo::SetViewInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


IOleUndoManager
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoManager::Add
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoManager::Close
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoManager::DiscardFrom
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoManager::Enable
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoManager::EnumRedoable
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoManager::EnumUndoable
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoManager::GetLastRedoDescription
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoManager::GetLastUndoDescription
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoManager::GetOpenParentState
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoManager::Open
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoManager::UndoTo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoManager:RedoTo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoUnit
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoUnit::Do
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoUnit::GetDescription
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoUnit::GetUnitType
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleUndoUnit::OnNextAdd
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IOleWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleWindow::ContextSensitiveHelp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IOleWindow::GetWindow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IParseDisplayName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IParseDisplayName::ParseDisplayName
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IPerPropertyBrowsing
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPerPropertyBrowsing::GetDisplayString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPerPropertyBrowsing::GetPredefinedStrings
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPerPropertyBrowsing::GetPredefinedValue
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPerPropertyBrowsing::MapPropertyToPage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPersist
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersist::GetClassID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistFile::GetCurFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistFile::IsDirty
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistFile::Load
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistFile::Save
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistFile::SaveCompleted
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistFolder::Initialize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IPersistMemory
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPersistMemory::GetSizeMax
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPersistMemory::InitNew
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPersistMemory::IsDirty
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPersistMemory::Load
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPersistMemory::Save
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPersistMessage::GetClassID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IPersistMessage::GetLastError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IPersistMessage::HandsOffMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IPersistMessage::InitNew
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IPersistMessage::IsDirty
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IPersistMessage::Load
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IPersistMessage::Save
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IPersistMessage::SaveCompleted
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


IPersistPropertyBag
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPersistPropertyBag::Read
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPersistPropertyBag::Write
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPersistStorage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistStorage::HandsOffStorage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistStorage::InitNew
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistStorage::IsDirty
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistStorage::Load
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistStorage::Save
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistStorage::SaveCompleted
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistStream
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistStream::GetSizeMax
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistStream::IsDirty
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistStream::Load
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistStream::Save
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPersistStreamInit
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPersistStreamInit::GetSizeMax
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPersistStreamInit::InitNew
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPersistStreamInit::IsDirty
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPersistStreamInit::Load
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPersistStreamInit::Save
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPicture
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPicture::get_Attributes
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPicture::get_CurDC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPicture::get_Handle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPicture::get_Height
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPicture::get_hPal
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPicture::get_KeepOriginalFormat
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPicture::get_Type
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPicture::get_Width
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPicture::PictureChanged
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPicture::put_KeepOriginalFormat
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPicture::Render
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPicture::SaveAsFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPicture::SelectPicture
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPicture::set_hPal
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPictureDisp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPointerInactive
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPointerInactive::GetActivationPolicy
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPointerInactive::OnInactiveMouseMove
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPointerInactive::OnInactiveSetCursor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IProfAdmin::AdminServices
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IProfAdmin::ChangeProfilePassword
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IProfAdmin::CopyProfile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IProfAdmin::CreateProfile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IProfAdmin::DeleteProfile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IProfAdmin::GetLastError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IProfAdmin::GetProfileTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IProfAdmin::RenameProfile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IProfAdmin::SetDefaultProfile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


IPropData::HrAddObjProps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


IPropData::HrGetPropAccess
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


IPropData::HrSetObjAccess
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


IPropData::HrSetPropAccess
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


IPropertyNotifySink
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyNotifySink::OnChanged
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyNotifySink::OnRequestEdit
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPage::Activate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPage::Apply
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPage::Deactivate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPage::GetPageInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPage::Help
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPage::IsPageDirty
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPage::Move
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPage::SetObjects
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPage::SetPageSite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPage::Show
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPage::TranslateAccelerator
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPage2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPage2::EditProperty
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPageSite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPageSite::GetLocaleID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPageSite::GetPageContainer
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPageSite::OnStatusChange
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertyPageSite::TranslateAccelerator
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IPropertySetStorage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertySetStorage::Create
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertySetStorage::Delete
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertySetStorage::Enum
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertySetStorage::Open
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertyStorage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertyStorage::Commit
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertyStorage::DeleteMultiple
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertyStorage::DeletePropertyNames
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertyStorage::Enum
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertyStorage::ReadMultiple
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertyStorage::ReadPropertyNames
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertyStorage::Revert
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertyStorage::SetClass
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertyStorage::SetTimes
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertyStorage::Stat
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IPropertyStorage::WriteMultiple
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IProvideClassInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IProvideClassInfo::GetClassInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IProvideClassInfo2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IProvideClassInfo2::GetGUID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IProviderAdmin::CreateProvider
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IProviderAdmin::DeleteProvider
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IProviderAdmin::GetLastError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IProviderAdmin::GetProviderTable
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IProviderAdmin::OpenProfileSection
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


IQuickActivate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IQuickActivate::GetContentExtent
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IQuickActivate::QuickActivate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IQuickActivate::SetContentExtent
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IReconcilableObject::GetProgressFeedbackMaxEstimate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	reconcil.h
Unicode	No
Platform Notes	None


IReconcilableObject::Reconcile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	reconcil.h
Unicode	No
Platform Notes	None


IReconcileInitiator::SetAbortCallback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	reconcil.h
Unicode	No
Platform Notes	None


IReconcileInitiator::SetProgressFeedback
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	reconcil.h
Unicode	No
Platform Notes	None


IRichEditOle::ActivateAs
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOle::ContextSensitiveHelp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOle::ConvertObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOle::GetClientSite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOle::GetClipboardData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOle::GetLinkCount
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOle::GetObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOle::GetObjectCount
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOle::HandsOffStorage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOle::ImportDataObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOle::InPlaceDeactivate
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOle::InsertObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOle::SaveCompleted
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOle::SetDvaspect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOle::SetHostNames
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOle::SetLinkAvailable
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOleCallback::ContextSensitiveHelp
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOleCallback::DeleteObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOleCallback::GetClipboardData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOleCallback::GetContextMenu
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOleCallback::GetDragDropEffect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOleCallback::GetInPlaceContext
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOleCallback::GetNewStorage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOleCallback::QueryAcceptData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOleCallback::QueryInsertObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRichEditOleCallback::ShowContainerUI
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	richole.h
Unicode
Platform Notes	None


IRootStorage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IRootStorage::SwitchToFile
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IROTData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IROTData::GetComparisonData
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IRunnableObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IRunnableObject::GetRunningClass
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IRunnableObject::IsRunning
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IRunnableObject::LockRunning
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IRunnableObject::Run
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IRunnableObject::SetContainedObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IRunningObjectTable
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IRunningObjectTable::EnumRunning
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IRunningObjectTable::GetObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IRunningObjectTable::GetTimeOfLastChange
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IRunningObjectTable::IsRunning
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IRunningObjectTable::NoteChangeTime
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IRunningObjectTable::Register
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IRunningObjectTable::Revoke
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IServerSecurity
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IServerSecurity::ImpersonateClient
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IServerSecurity::IsImpersonating
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IServerSecurity::QueryBlanket
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IServerSecurity::RevertToSelf
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IShellBrowser::BrowseObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellBrowser::EnableModelessSB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellBrowser::GetControlWindow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellBrowser::GetViewStateStream
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellBrowser::InsertMenusSB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellBrowser::OnViewWindowActive
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellBrowser::QueryActiveShellView
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellBrowser::RemoveMenusSB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellBrowser::SendControlMsg
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellBrowser::SetMenuSB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellBrowser::SetStatusTextSB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellBrowser::TranslateAcceleratorSB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellExecuteHook::Execute
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellExtInit::Initialize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellFolder::BindToObject
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellFolder::BindToStorage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellFolder::CompareIDs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellFolder::CreateViewObject
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellFolder::EnumObjects
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellFolder::GetAttributesOf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellFolder::GetDisplayNameOf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellFolder::GetUIObjectOf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellFolder::ParseDisplayName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellFolder::SetNameOf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellIcon::GetIconOf
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::GetArguments
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::GetDescription
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::GetHotkey
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::GetIconLocation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::GetIDList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::GetPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::GetShowCmd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::GetWorkingDirectory
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::Resolve
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::SetArguments
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::SetDescription
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::SetHotkey
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::SetIconLocation
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::SetIDList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::SetPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::SetRelativePath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::SetShowCmd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellLink::SetWorkingDirectory
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellPropSheetExt::AddPages
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellPropSheetExt::ReplacePage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellView::AddPropertySheePages
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellView::CreateViewWindow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellView::DestroyViewWindow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellView::EnableModeless
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellView::GetCurrentInfo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellView::GetItemObject
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellView::Refresh
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellView::SaveViewState
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellView::SelectItem
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellView::TranslateAccelerator
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


IShellView::UIActivate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


ISimpleFrameSite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


ISimpleFrameSite::PostMessageFilter
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


ISimpleFrameSite::PreMessageFilter
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


ISpecifyPropertyPages
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


ISpecifyPropertyPages::GetPages
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


ISpoolerHook::InboundMsgHook
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapihook.h
Unicode	No
Platform Notes	None


ISpoolerHook::OutboundMsgHook
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapihook.h
Unicode	No
Platform Notes	None


IStdMarshalInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStdMarshalInfo::GetClassForHandler
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage::Commit
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage::CopyTo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage::CreateStorage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage::CreateStream
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage::DestroyElement
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage::EnumElements
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage::MoveElementTo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage::OpenStorage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage::OpenStream
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage::RenameElement
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage::Revert
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage::SetClass
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage::SetElementTimes
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage::SetStateBits
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStorage::Stat
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStream
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStream::Clone
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStream::Commit
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStream::CopyTo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStream::LockRegion
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStream::Read
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStream::Revert
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStream::Seek
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStream::SetSize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStream::Stat
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStream::UnlockRegion
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


IStream::Write
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


ITableData::HrDeleteRow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


ITableData::HrDeleteRows
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


ITableData::HrEnumRow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


ITableData::HrGetView
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


ITableData::HrInsertRow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


ITableData::HrModifyRow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


ITableData::HrModifyRows
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


ITableData::HrNotify
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


ITableData::HrQueryRow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


ITnef::AddProps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tnef.h
Unicode	No
Platform Notes	None


ITnef::EncodeRecips
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tnef.h
Unicode	No
Platform Notes	None


ITnef::ExtractProps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tnef.h
Unicode	No
Platform Notes	None


ITnef::Finish
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tnef.h
Unicode	No
Platform Notes	None


ITnef::FinishComponent
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tnef.h
Unicode	No
Platform Notes	None


ITnef::OpenTaggedBody
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tnef.h
Unicode	No
Platform Notes	None


ITnef::SetProps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tnef.h
Unicode	No
Platform Notes	None


IUnknown
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	Unknwn.h
Unicode	Yes
Platform Notes	None


IUnknown::AddRef
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	Unknwn.h
Unicode	Yes
Platform Notes	None


IUnknown::QueryInterface
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	Unknwn.h
Unicode	Yes
Platform Notes	None


IUnknown::Release
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	Unknwn.h
Unicode	Yes
Platform Notes	None


IViewObject
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IViewObject::Draw
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IViewObject::Freeze
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IViewObject::GetAdvise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IViewObject::GetColorSet
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IViewObject::SetAdvise
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IViewObject::Unfreeze
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IViewObject2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IViewObject2::GetExtent
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


IViewObjectEx
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IViewObjectEx::GetNaturalExtent
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IViewObjectEx::GetRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IViewObjectEx::GetViewStatus
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IViewObjectEx::QueryHitPoint
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IViewObjectEx::QueryHitRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


IXPLogon::AddressTypes
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IXPLogon::EndMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IXPLogon::FlushQueues
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IXPLogon::Idle
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IXPLogon::OpenStatusEntry
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IXPLogon::Poll
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IXPLogon::RegisterOptions
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IXPLogon::StartMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IXPLogon::SubmitMessage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IXPLogon::TransportLogoff
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IXPLogon::TransportNotify
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IXPLogon::ValidateState
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IXPProvider : IUnknown
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IXPProvider::Shutdown
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


IXPProvider::TransportLogon
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


Logoff interface method (Session OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Logon interface method (Session OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Options interface method (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


ReadFromFile interface method (Attachment OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


ReadFromFile interface method (Field OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Resolve interface method (Recipient OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Resolve interface method (Recipients Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Send interface method (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


SetNamespace interface method (Fields Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Sort interface method (Messages Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Update interface method (AddressEntry OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Update interface method (Folder OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Update interface method (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


WriteToFile interface method (Attachment OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


WriteToFile interface method (Field OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


D3DRMANIMATIONOPTIONS
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMCOLORMODEL
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMLOADOPTIONS
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMMAPPING
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMMATRIX4D
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMSAVEOPTIONS
Windows NT	No
Win95	Yes
Win32s	No
Import Library	d3drm.lib
Header File	d3drm.h
Unicode	No
Platform Notes	None


Animate_Close
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


Animate_Create
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


Animate_Open
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


Animate_Play
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


Animate_Seek
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


Animate_Stop
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


AVIStreamDataSize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamEnd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamEndTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamFormatSize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamIsKeyFrame
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamLengthTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamNearestKeyFrame
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamNearestKeyFrameTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamNearestSample
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamNearestSampleTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamNextKeyFrame
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamNextKeyFrameTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamNextSample
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamNextSampleTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamPrevKeyFrame
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamPrevKeyFrameTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamPrevSample
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamPrevSampleTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamSampleSize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamSampleToSample
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamStartTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capCaptureAbort
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capCaptureGetSetup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capCaptureSequence
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capCaptureSequenceNoFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capCaptureSetSetup
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capCaptureSingleFrame
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capCaptureSingleFrameClose
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capCaptureSingleFrameOpen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capCaptureStop
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capDlgVideoCompression
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capDlgVideoDisplay
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capDlgVideoFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capDlgVideSource
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capDriverConnect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capDriverDisconnect
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capDriverGetCaps
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capDriverGetName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capDriverGetVersion
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capEditCopy
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capFileAlloc
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capFileGetCaptureFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capFileSaveAs
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capFileSaveDib
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capFileSetCaptureFile
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capFileSetInfoChunk
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capGetAudioFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capGetAudioFormatSize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capGetMCIDeviceName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capGetStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capGetUserData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capGetVideoFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capGrabFrame
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capGrabFrameNoStop
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capOverlay
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capPaletteAuto
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capPaletteManual
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capPaletteOpen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capPalettePaste
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capPaletteSave
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capPreview
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capPreviewRate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capPreviewScale
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capSetAudioFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capSetCallbackOnCapControl
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capSetCallbackOnError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capSetCallbackOnFrame
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capSetCallbackOnStatus
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capSetCallbackOnVideoStream
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capSetCallbackOnWaveStream
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capSetCallbackOnYield
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capSetMCIDeviceName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capSetScrollPos
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capSetUserData
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


capSetVideoFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


CbADRLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbFLATENTRY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbFLATENTRYLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbFLATMTSIDLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbMAPIFormInfoArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


CbMAPIFormPropArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


CbMAPIVerbArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


CbMessageClassArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbMTSID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbNewADRLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbNewENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbNewFLATENTRY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbNewFLATENTRYLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbNewFLATMTSIDLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbNewMTSID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbNewSPropAttrArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	imessage.h
Unicode	No
Platform Notes	None


CbNewSPropProblemArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbNewSPropTagArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbNewSRowSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbNewSSortOrderSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbSPropAttrArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	imessage.h
Unicode	No
Platform Notes	None


CbSPropProblemArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbSPropTagArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbSRowSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CbSSortOrderSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CHANGE_PROP_TYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CMYK
Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


CommDlg_OpenSave_GetFilePath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


CommDlg_OpenSave_GetFolderIDList
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	commdlg.h
Unicode	No
Platform Notes	None


CommDlg_OpenSave_GetFolderPath
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


CommDlg_OpenSave_GetSpec
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


CommDlg_OpenSave_HideControl
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	commdlg.h
Unicode	No
Platform Notes	None


CommDlg_OpenSave_SetControlText
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	commdlg.h
Unicode	No
Platform Notes	None


CommDlg_OpenSave_SetDefExt
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	commdlg.h
Unicode	No
Platform Notes	None


CreateDialog
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CreateDialogIndirect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


D3DDivide
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


D3DMultiply
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


D3DRGB
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


D3DRGBA
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


D3DSTATE_OVERRIDE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


D3DVAL
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


D3DVALP
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


DialogBox
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DialogBoxIndirect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DrawDibUpdate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


FACILITY_NT_BIT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


FAILED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


FORWARD_WM_NOTIFY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


GetBValue
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetCValue
Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetGValue
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetKValue
Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetMValue
Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetRValue
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetScode
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


GetYValue
Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


HANDLE_WM_NOTIFY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


HasOverlappedIoCompleted
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


Header_DeleteItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


Header_GetItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


Header_GetItemCount
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


Header_InsertItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


Header_Layout
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


Header_SetItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


HIBYTE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


HIWORD
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


HRESULT_CODE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


HRESULT_FACILITY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


HRESULT_FROM_NT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


HRESULT_FROM_WIN32
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


HRESULT_SEVERITY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


ICAbout
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressBegin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressEnd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressGetFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressGetFormatSize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressGetSize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressQuery
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICConfigure
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressBegin
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressEnd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressExEnd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressGetFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressGetFormatSize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressGetPalette
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressOpen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressQuery
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressSetPalette
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawChangePalette
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawEnd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawFlush
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawGetTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawOpen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawQuery
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawRealize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawRenderBuffer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawSetTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawStart
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawStartPlay
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawStop
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawStopPlay
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawWindow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICGetBuffersWanted
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICGetDefaultKeyFrameRate
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICGetDefaultQuality
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICGetState
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICGetStateSize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICQueryAbout
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICQueryConfigure
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICSetState
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ImageList_AddIcon
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_ExtractIcon
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_LoadBitmap
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comctl32.lib
Header File	commctrl.h
Unicode	No
Platform Notes	None


INDEXTOOVERLAYMASK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


INDEXTOSTATEIMAGEMASK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


Int32x32To64
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


Int64ShllMod32
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


Int64ShraMod32
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


Int64ShrlMod32
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


IS_ERROR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


IsEqualCLSID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


IsEqualGUID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objbase.h
Unicode	Yes
Platform Notes	None


IsEqualIID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


IsEqualMAPIUID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


LANGIDFROMLCID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


ListView_Arrange
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_CreateDragImage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_DeleteAllItems
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_DeleteColumn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_DeleteItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_EditLabel
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


ListView_EnsureVisible
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_FindItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


ListView_GetBkColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetCallbackMask
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetColumn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


ListView_GetColumnWidth
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetCountPerPage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetEditControl
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetImageList
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetISearchString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


ListView_GetItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


ListView_GetItemCount
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetItemPosition
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetItemRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetItemSpacing
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetItemState
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetItemText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


ListView_GetNextItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetOrigin
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetSelectedCount
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetStringWidth
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


ListView_GetTextBkColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetTextColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetTopIndex
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_GetViewRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_HitTest
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_InsertColumn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


ListView_InsertItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


ListView_RedrawItems
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_Scroll
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_SetBkColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_SetCallbackMask
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_SetColumn
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


ListView_SetColumnWidth
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_SetImageList
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_SetItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


ListView_SetItemCount
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_SetItemPosition
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_SetItemPosition32
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_SetItemState
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_SetItemText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


ListView_SetTextBkColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_SetTextColor
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_SortItems
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ListView_Update
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


LOBYTE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


LOWORD
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


MAKE_HRESULT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


MAKE_SCODE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


MAKEINTATOM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


MAKEINTRESOURCE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


MAKELANGID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


MAKELCID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


MAKELONG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


MAKELPARAM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


MAKELRESULT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


MAKEPOINTS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


MAKEROP4
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


MAKEWORD
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


MAKEWPARAM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


max
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


MCI_HMS_HOUR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_HMS_MINUTE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_HMS_SECOND
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_MAKE_HMS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_MAKE_MSF
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_MAKE_TMSF
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_MSF_FRAME
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_MSF_MINUTE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_MSF_SECOND
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_TMSF_FRAME
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_TMSF_MINUTE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_TMSF_SECOND
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_TMSF_TRACK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCIWndCanConfig
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndCanEject
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndCanPlay
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndCanRecord
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndCanSave
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndCanWindow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndChangeStyles
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndClose
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndDestroy
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndEject
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndEnd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetActiveTimer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetAlias
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetDest
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetDevice
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetDeviceID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetEnd
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetError
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetFileName
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetInactiveTimer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetLength
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetMode
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetPalette
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetPosition
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetPositionString
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetRepeat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetSource
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetSpeed
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetStart
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetStyles
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetTimeFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetVolume
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndGetZoom
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndHome
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndNew
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndOpen
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndOpenDialog
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndOpenInterface
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndPause
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndPlay
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndPlayFrom
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndPlayFromTo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndPlayReverse
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndPlayTo
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndPutDest
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndPutSource
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndRealize
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndRecord
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndResume
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndReturnString
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndSave
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndSaveDialog
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndSeek
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndSendString
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndSetActiveTimer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndSetInactiveTimer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndSetOwner
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndSetPalette
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndSetRepeat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndSetSpeed
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndSetTimeFormat
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndSetTimers
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndSetVolume
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndSetZoom
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndStep
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndStop
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndUseFrames
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndUseTime
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWndValidateMedia
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


MEVT_EVENTPARM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MEVT_EVENTTYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


min
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


mmioFOURCC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MVI_PROP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


PALETTEINDEX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


PALETTERGB
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


POINTSTOPOINT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


POINTTOPOINTS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


PRIMARYLANGID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


PROP_ID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


PROP_TAG
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


PROP_TYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


PropagateResult
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


PropSheet_AddPage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


PropSheet_Apply
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


PropSheet_CancelToClose
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


PropSheet_Changed
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


PropSheet_GetCurrentPageHwnd
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


PropSheet_GetTabControl
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


PropSheet_IsDialogMessage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


PropSheet_PressButton
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


PropSheet_QuerySiblings
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


PropSheet_RebootSystem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


PropSheet_RemovePage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


PropSheet_RestartWindows
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


PropSheet_SetCurSel
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


PropSheet_SetCurSelByID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


PropSheet_SetFinishText
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	WinNT
Platform Notes	None


PropSheet_SetTitle
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	WinNT
Platform Notes	None


PropSheet_SetWizButtons
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


PropSheet_UnChanged
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


ResultFromScode
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


RGB
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


RGB_GETBLUE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


RGB_GETGREEN
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


RGB_GETRED
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


RGB_MAKE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


RGB_TORGBA
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


RGBA_GETALPHA
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


RGBA_GETBLUE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


RGBA_GETGREEN
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


RGBA_GETRED
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


RGBA_MAKE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


RGBA_SETALPHA
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


RGBA_TORGB
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3dtypes.h
Unicode	No
Platform Notes	None


SCODE_CODE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


SCODE_FACILITY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


SCODE_SEVERITY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


SizedADRLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SizedDtblButton
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SizedDtblCheckBox
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SizedDtblComboBox
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SizedDtblEdit
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SizedDtblGroupBox
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SizedDtblLabel
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SizedDtblPage
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SizedENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SizedSPropProblemArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SizedSPropTagArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SizedSRowSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SizedSSortOrderSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SORTIDFROMLCID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


SUBLANGID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


SUCCEEDED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winerror.h
Unicode	Yes
Platform Notes	None


TabCtrl_AdjustRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_DeleteAllItems
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_DeleteItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_GetCurFocus
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_GetCurSel
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_GetImageList
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_GetItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TabCtrl_GetItemCount
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_GetItemRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_GetRowCount
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_GetToolTips
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_HitTest
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_InsertItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TabCtrl_RemoveImage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_SetCurFocus
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_SetCurSel
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_SetImageList
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_SetItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TabCtrl_SetItemExtra
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_SetItemSize
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_SetPadding
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TabCtrl_SetToolTips
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TAPIERROR_FORMATMESSAGE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


TEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winnt.h
Unicode	WinNT
Platform Notes	None


TreeView_CreateDragImage
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_DeleteAllItems
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_DeleteItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_EditLabel
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TreeView_EndEditLabelNow
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_EnsureVisible
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_Expand
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetChild
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetCount
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetDropHilite
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetEditControl
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetFirstVisible
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetImageList
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetIndent
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetISearchString
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TreeView_GetItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TreeView_GetItemRect
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetNextItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetNextSibling
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetNextVisible
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetParent
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetPrevSibling
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetPrevVisible
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetRoot
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetSelection
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_GetVisibleCount
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_HitTest
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_InsertItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TreeView_Select
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_SelectDropTarget
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_SelectItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_SelectSetFirstVisible
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_SetImageList
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_SetIndent
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_SetItem
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TreeView_SortChildren
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


TreeView_SortChildrenCB
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


UInt32x32To64
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


ABM_ACTIVATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


ABM_GETAUTOHIDEBAR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


ABM_GETSTATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


ABM_GETTASKBARPOS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


ABM_NEW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


ABM_QUERYPOS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


ABM_REMOVE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


ABM_SETAUTOHIDEBAR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


ABM_SETPOS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


ABM_WINDOWPOSCHANGED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


ABN_FULLSCREENAPP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


ABN_POSCHANGED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


ABN_STATECHANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


ABN_WINDOWARRANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


ACM_OPEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


ACM_PLAY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


ACM_STOP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


BM_CLICK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BM_GETCHECK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BM_GETIMAGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BM_GETSTATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BM_SETCHECK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BM_SETIMAGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BM_SETSTATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BM_SETSTYLE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_ADDSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_DELETESTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_DIR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_FINDSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_FINDSTRINGEXACT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETCOUNT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETCURSEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETDROPPEDCONTROLRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETDROPPEDSTATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETDROPPEDWIDTH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETEDITSEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETEXTENDEDUI
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETHORIZONTALEXTENT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETITEMDATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETITEMHEIGHT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETLBTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETLBTEXTLEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETLOCALE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETTOPINDEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_INITSTORAGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_INSERTSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_LIMITTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_MSGMAX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_RESETCONTENT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SELECTSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETCURSEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETDROPPEDWIDTH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETEDITSEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETEXTENDEDUI
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETHORIZONTALEXTENT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETITEMDATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETITEMHEIGHT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETLOCALE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETTOPINDEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SHOWDROPDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CDM_GETFILEPATH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


CDM_GETFOLDERIDLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


CDM_GETFOLDERPATH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


CDM_GETSPEC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


CDM_HIDECONTROL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


CDM_SETCONTROLTEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


CDM_SETDEFEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


CDN_FILEOK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


CDN_FOLDERCHANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


CDN_HELP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


CDN_INITDONE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


CDN_SELCHANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


CDN_SHAREVIOLATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


CDN_TYPECHANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


CPL_DBLCLK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	cpl.h
Unicode	No
Platform Notes	None


CPL_EXIT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	cpl.h
Unicode	No
Platform Notes	None


CPL_GETCOUNT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	cpl.h
Unicode	No
Platform Notes	None


CPL_INIT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	cpl.h
Unicode	No
Platform Notes	None


CPL_INQUIRE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	cpl.h
Unicode	No
Platform Notes	None


CPL_NEWINQUIRE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	cpl.h
Unicode	No
Platform Notes	None


CPL_SELECT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	cpl.h
Unicode	No
Platform Notes	None


CPL_STOP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	cpl.h
Unicode	No
Platform Notes	None


DM_GETDEFID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


DM_REPOSITION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


DM_SETDEFID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


DRV_CLOSE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DRV_CONFIGURE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DRV_DISABLE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DRV_ENABLE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DRV_EXITSESSION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DRV_FREE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DRV_INSTALL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DRV_LOAD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DRV_OPEN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DRV_POWER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DRV_QUERYCONFIGURE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DRV_REMOVE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


EM_CANPASTE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_CANUNDO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_CHARFROMPOS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_DISPLAYBAND
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_EMPTYUNDOBUFFER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_EXGETSEL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_EXLIMITTEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_EXLINEFROMCHAR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_EXSETSEL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_FINDTEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_FINDTEXTEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_FINDWORDBREAK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_FMTLINES
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_FORMATRANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_GETCHARFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_GETEVENTMASK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_GETFIRSTVISIBLELINE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	For Single Line Edit controls Win32s returns 0


EM_GETHANDLE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETIMECOLOR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_GETIMEOPTIONS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_GETLIMITTEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETLINE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETLINECOUNT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETMARGINS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETMODIFY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETOLEINTERFACE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_GETOPTIONS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_GETPARAFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_GETPASSWORDCHAR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETPUNCTUATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_GETRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETSEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETSELTEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_GETTEXTRANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_GETTHUMB
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETWORDBREAKPROC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETWORDBREAKPROCEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_GETWORDWRAPMODE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_HIDESELECTION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_LIMITTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_LINEFROMCHAR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_LINEINDEX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_LINELENGTH
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_LINESCROLL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_PASTESPECIAL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_POSFROMCHAR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_REPLACESEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_REQUESTRESIZE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_SCROLL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SCROLLCARET
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SELECTIONTYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_SETBKGNDCOLOR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_SETCHARFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_SETEVENTMASK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_SETHANDLE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETIMECOLOR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_SETIMEOPTIONS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_SETLIMITTEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETMARGINS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETMODIFY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETOLECALLBACK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_SETOLEINTERFACE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File
Unicode
Platform Notes	None


EM_SETOPTIONS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_SETPARAFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_SETPASSWORDCHAR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETPUNCTUATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_SETREADONLY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETRECTNP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETSEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETTABSTOPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETTARGETDEVICE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_SETWORDBREAK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETWORDBREAKPROC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETWORDBREAKPROCEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_SETWORDWRAPMODE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_STREAMIN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_STREAMOUT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EM_UNDO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


FM_GETDRIVEINFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	WinNT
Platform Notes	Windows 95: Only supports 16-bit FileManager


FM_GETFILESEL
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	WinNT
Platform Notes	Windows 95: Only supports 16-bit FileManager


FM_GETFILESELLFN
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	WinNT
Platform Notes	Windows 95: Only supports 16-bit FileManager


FM_GETFOCUS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FM_GETSELCOUNT
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FM_GETSELCOUNTLFN
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FM_REFRESH_WINDOWS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FM_RELOAD_EXTENSIONS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_HELPMENUITEM
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_HELPSTRING
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_INITMENU
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_LOAD
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_SELCHANGE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_TOOLBARLOAD
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_UNLOAD
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_USER_REFRESH
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


HDM_DELETEITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


HDM_GETITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


HDM_GETITEMCOUNT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


HDM_HITTEST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


HDM_INSERTITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


HDM_LAYOUT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


HDM_SETITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


HKM_GETHOTKEY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


HKM_SETHOTKEY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


HKM_SETRULES
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


ICM_ABOUT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_COMPRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_COMPRESS_BEGIN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_COMPRESS_END
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_COMPRESS_FRAMES_INFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_COMPRESS_GET_FORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_COMPRESS_GET_SIZE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_COMPRESS_QUERY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_CONFIGURE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DECOMPRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DECOMPRESS_BEGIN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DECOMPRESS_END
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DECOMPRESS_GET_FORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DECOMPRESS_GET_PALETTE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DECOMPRESS_QUERY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DECOMPRESS_SET_PALETTE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DECOMPRESSEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DECOMPRESSEX_BEGIN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DECOMPRESSEX_END
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DECOMPRESSEX_QUERY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_BEGIN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_CHANGEPALETTE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_END
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_FLUSH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_GET_PALETTE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_GETTIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_QUERY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_REALIZE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_RENDERBUFFER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_SETTIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_START
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_START_PLAY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_STOP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_STOP_PLAY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_SUGGESTFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_DRAW_WINDOW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_GET
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_GETBUFFERSWANTED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_GETDEFAULTKEYFRAMERATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_GETDEFAULTQUALITY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_GETINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_GETQUALITY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_GETSTATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_SET_STATUS_PROC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_SETQUALITY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICM_SETSTATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


IMC_CLOSESTATUSWINDOW
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMC_GETCANDIDATEPOS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMC_GETCOMPOSITIONFONT
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMC_GETCOMPOSITIONWINDOW
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMC_GETCONVERSIONMODE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File
Unicode
Platform Notes	None


IMC_GETOPENSTATUS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File
Unicode
Platform Notes	None


IMC_GETSENTENCEMODE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File
Unicode
Platform Notes	None


IMC_GETSTATUSWINDOWPOS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMC_OPENSTATUSWINDOW
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMC_SETCANDIDATEPOS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMC_SETCOMPOSITIONFONT
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMC_SETCOMPOSITIONWINDOW
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMC_SETCONVERSIONMODE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File
Unicode
Platform Notes	None


IMC_SETOPENSTATUS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File
Unicode
Platform Notes	None


IMC_SETSENTENCEMODE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File
Unicode
Platform Notes	None


IMC_SETSTATUSWINDOWPOS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


LB_ADDFILE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_ADDSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_DELETESTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_DIR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_FINDSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_FINDSTRINGEXACT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETANCHORINDEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_GETCARETINDEX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_GETCOUNT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_GETCURSEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_GETHORIZONTALEXTENT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_GETITEMDATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETITEMHEIGHT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETITEMRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETLOCALE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_GETSEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETSELCOUNT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_GETSELITEMS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETTEXTLEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETTOPINDEX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_INITSTORAGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_INSERTSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_ITEMFROMPOINT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_RESETCONTENT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SELECTSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_SELITEMRANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_SELITEMRANGEEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SETANCHORINDEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SETCARETINDEX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_SETCOLUMNWIDTH
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SETCOUNT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SETCURSEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_SETHORIZONTALEXTENT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SETITEMDATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_SETITEMHEIGHT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_SETLOCALE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SETSEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_SETTABSTOPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SETTOPINDEX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LINE_ADDRESSSTATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_AGENTSPECIFIC
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_AGENTSTATUS
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_APPNEWCALL
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_CALLINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_CALLSTATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_CLOSE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_CREATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_DEVSPECIFIC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_DEVSPECIFICFEATURE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_GATHERDIGITS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_GENERATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_LINEDEVSTATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_MONITORDIGITS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_MONITORMEDIA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_MONITORTONE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_PROXYREQUEST
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_REMOVE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_REPLY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LINE_REQUEST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


LVM_ARRANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_CREATEDRAGIMAGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_DELETEALLITEMS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_DELETECOLUMN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_DELETEITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_EDITLABEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LVM_ENSUREVISIBLE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_FINDITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LVM_GETBKCOLOR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETCALLBACKMASK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETCOLUMN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LVM_GETCOLUMNWIDTH
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETCOUNTPERPAGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETEDITCONTROL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETIMAGELIST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETISEARCHSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LVM_GETITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LVM_GETITEMCOUNT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETITEMPOSITION
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETITEMRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETITEMSPACING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETITEMSTATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETITEMTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LVM_GETNEXTITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETORIGIN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETSELECTEDCOUNT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETSTRINGWIDTH
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LVM_GETTEXTBKCOLOR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETTEXTCOLOR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETTOPINDEX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_GETVIEWRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_HITTEST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_INSERTCOLUMN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LVM_INSERTITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LVM_REDRAWITEMS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_SCROLL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_SETBKCOLOR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_SETCALLBACKMASK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_SETCOLUMN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LVM_SETCOLUMNWIDTH
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_SETIMAGELIST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_SETITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LVM_SETITEMCOUNT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_SETITEMPOSITION
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_SETITEMPOSITION32
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_SETITEMSTATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_SETITEMTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LVM_SETTEXTBKCOLOR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_SETTEXTCOLOR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_SORTITEMS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVM_UPDATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


MCIWNDM_CAN_CONFIG
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_CAN_EJECT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_CAN_PLAY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_CAN_RECORD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_CAN_SAVE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_CAN_WINDOW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_CHANGESTYLES
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_EJECT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_GET_DEST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_GET_SOURCE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_GETACTIVETIMER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_GETALIAS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_GETDEVICE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


MCIWNDM_GETDEVICEID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_GETEND
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_GETERROR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


MCIWNDM_GETFILENAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


MCIWNDM_GETINACTIVETIMER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_GETLENGTH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_GETMODE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


MCIWNDM_GETPALETTE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_GETPOSITION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


MCIWNDM_GETREPEAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_GETSPEED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_GETSTART
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_GETSTYLES
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_GETTIMEFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


MCIWNDM_GETVOLUME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_GETZOOM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_NEW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


MCIWNDM_NOTIFYERROR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_NOTIFYMEDIA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_NOTIFYMODE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_NOTIFYPOS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_NOTIFYSIZE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_OPEN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


MCIWNDM_OPENINTERFACE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_PLAYFROM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_PLAYREVERSE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_PLAYTO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_PUT_DEST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_PUT_SOURCE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_REALIZE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_RETURNSTRING
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


MCIWNDM_SENDSTRING
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


MCIWNDM_SETACTIVETIMER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_SETINACTIVETIMER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_SETOWNER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_SETPALETTE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_SETREPEAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_SETSPEED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_SETTIMEFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


MCIWNDM_SETTIMERS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_SETVOLUME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_SETZOOM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MCIWNDM_VALIDATEMEDIA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


MIM_CLOSE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIM_DATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIM_ERROR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIM_LONGDATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIM_LONGERROR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIM_MOREDATA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIM_OPEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_ACM_FILTERCHOOSE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	msacm.h
Unicode	No
Platform Notes	None


MM_ACM_FORMATCHOOSE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	msacm.h
Unicode	No
Platform Notes	None


MM_JOY1BUTTONDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_JOY1BUTTONUP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_JOY1MOVE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_JOY1ZMOVE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_JOY2BUTTONDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_JOY2BUTTONUP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_JOY2MOVE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_JOY2ZMOVE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MCINOTIFY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MCISIGNAL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MIM_CLOSE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MIM_DATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MIM_ERROR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MIM_LONGDATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MIM_LONGERROR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MIM_MOREDATA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MIM_OPEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MIXM_CONTROL_CHANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MIXM_LINE_CHANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MOM_CLOSE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MOM_DONE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MOM_OPEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MOM_POSITIONCB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_WIM_CLOSE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_WIM_DATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_WIM_OPEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_WOM_CLOSE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_WOM_DONE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_WOM_OPEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMIOM_CLOSE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMIOM_OPEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMIOM_READ
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMIOM_RENAME
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMIOM_SEEK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMIOM_WRITE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMIOM_WRITEFLUSH
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MOM_CLOSE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MOM_DONE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MOM_OPEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MOM_POSITIONCB
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


NIM_ADD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


NIM_DELETE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


NIM_MODIFY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


PBM_DELTAPOS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


PBM_SETPOS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


PBM_SETRANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


PBM_SETSTEP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


PBM_STEPIT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


PHONE_BUTTON
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


PHONE_CLOSE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


PHONE_CREATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


PHONE_DEVSPECIFIC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


PHONE_REMOVE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


PHONE_REPLY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


PHONE_STATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	No
Platform Notes	None


PSM_ADDPAGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSM_APPLY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSM_CANCELTOCLOSE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSM_CHANGED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSM_GETCURRENTPAGEHWND
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSM_GETTABCONTROL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSM_ISDIALOGMESSAGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSM_PRESSBUTTON
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSM_QUERYSIBLINGS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSM_REBOOTSYSTEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSM_REMOVEPAGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSM_RESTARTWINDOWS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSM_SETCURSEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSM_SETCURSELID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSM_SETFINISHTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	WinNT
Platform Notes	None


PSM_SETTITLE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	WinNT
Platform Notes	None


PSM_SETWIZBUTTONS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSM_UNCHANGED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSN_HASHELP
Windows NT
Win95
Win32s
Import Library	-
Header File
Unicode
Platform Notes	None


SB_GETBORDERS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


SB_GETPARTS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


SB_GETRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


SB_GETTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


SB_GETTEXTLENGTH
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


SB_SETMINHEIGHT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


SB_SETPARTS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


SB_SETTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


SB_SIMPLE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


SBM_ENABLE_ARROWS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


SBM_GETPOS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


SBM_GETRANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


SBM_GETSCROLLINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


SBM_SETPOS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


SBM_SETRANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


SBM_SETRANGEREDRAW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


SBM_SETSCROLLINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


STM_GETICON
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


STM_GETIMAGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


STM_SETICON
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


STM_SETIMAGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


STN_CLICKED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


STN_DBLCLK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


STN_DISABLE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


STN_ENABLE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


TB_ADDBITMAP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_ADDBUTTONS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_ADDSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TB_AUTOSIZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_BUTTONCOUNT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_BUTTONSTRUCTSIZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_CHANGEBITMAP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_CHECKBUTTON
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_COMMANDTOINDEX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_CUSTOMIZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_DELETEBUTTON
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_ENABLEBUTTON
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_GETBITMAP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_GETBITMAPFLAGS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_GETBUTTON
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_GETBUTTONTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TB_GETITEMRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_GETROWS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_GETSTATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_GETTOOLTIPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_HIDEBUTTON
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_INDETERMINATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_INSERTBUTTON
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_ISBUTTONCHECKED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_ISBUTTONENABLED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_ISBUTTONHIDDEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_ISBUTTONINDETERMINATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_ISBUTTONPRESSED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_PRESSBUTTON
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_SAVERESTORE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TB_SETBITMAPSIZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_SETBUTTONSIZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_SETCMDID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_SETPARENT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_SETROWS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_SETSTATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TB_SETTOOLTIPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_CLEARSEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_CLEARTICS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_GETCHANNELRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_GETLINESIZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_GETNUMTICS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_GETPAGESIZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_GETPOS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_GETPTICS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_GETRANGEMAX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_GETRANGEMIN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_GETSELEND
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_GETSELSTART
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_GETTHUMBLENGTH
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_GETTHUMBRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_GETTIC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_GETTICPOS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_SETLINESIZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_SETPAGESIZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_SETPOS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_SETRANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_SETRANGEMAX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_SETRANGEMIN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_SETSEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_SETSELEND
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_SETSELSTART
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_SETTHUMBLENGTH
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_SETTIC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBM_SETTICFREQ
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_ADJUSTRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_DELETEALLITEMS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_DELETEITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_GETCURFOCUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_GETCURSEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_GETIMAGELIST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_GETITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TCM_GETITEMCOUNT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_GETITEMRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_GETROWCOUNT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_GETTOOLTIPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_HITTEST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_INSERTITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TCM_REMOVEIMAGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_SETCURFOCUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_SETCURSEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_SETIMAGELIST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_SETITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TCM_SETITEMEXTRA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_SETITEMSIZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_SETPADDING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCM_SETTOOLTIPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TTM_ACTIVATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TTM_ADDTOOL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TTM_DELTOOL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TTM_ENUMTOOLS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TTM_GETCURRENTTOOL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TTM_GETTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TTM_GETTOOLCOUNT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TTM_GETTOOLINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TTM_HITTEST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TTM_NEWTOOLRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TTM_RELAYEVENT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TTM_SETDELAYTIME
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TTM_SETTOOLINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TTM_UPDATETIPTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TTM_WINDOWFROMPOINT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_CREATEDRAGIMAGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_DELETEITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_EDITLABEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TVM_ENDEDITLABELNOW
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_ENSUREVISIBLE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_EXPAND
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_GETCOUNT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_GETEDITCONTROL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_GETIMAGELIST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_GETINDENT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_GETISEARCHSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TVM_GETITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TVM_GETITEMRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_GETNEXTITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_GETVISIBLECOUNT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_HITTEST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_INSERTITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TVM_SELECTITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_SETIMAGELIST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_SETINDENT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_SETITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TVM_SORTCHILDREN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVM_SORTCHILDRENCB
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


UDM_GETACCEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


UDM_GETBASE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


UDM_GETBUDDY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


UDM_GETPOS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


UDM_GETRANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


UDM_SETACCEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


UDM_SETBASE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


UDM_SETBUDDY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


UDM_SETPOS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


UDM_SETRANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


WIM_CLOSE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


WIM_DATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


WIM_OPEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


WM_ACTIVATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ACTIVATEAPP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_APP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ASKCBFORMATNAME
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CANCELJOURNAL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CANCELMODE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CAP_ABORT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_DLG_VIDEOCOMPRESSION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_DLG_VIDEODISPLAY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_DLG_VIDEOFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_DLG_VIDEOSOURCE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_DRIVER_CONNECT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_DRIVER_DISCONNECT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_DRIVER_GET_CAPS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_DRIVER_GET_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


WM_CAP_DRIVER_GET_VERSION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


WM_CAP_EDIT_COPY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_FILE_ALLOCATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_FILE_GET_CAPTURE_FILE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


WM_CAP_FILE_SAVEAS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


WM_CAP_FILE_SAVEDIB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


WM_CAP_FILE_SET_CAPTURE_FILE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


WM_CAP_FILE_SET_INFOCHUNK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_GET_AUDIOFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_GET_MCI_DEVICE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


WM_CAP_GET_SEQUENCE_SETUP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_GET_STATUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_GET_USER_DATA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_GET_VIDEOFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_GRAB_FRAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_GRAB_FRAME_NOSTOP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_PAL_AUTOCREATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_PAL_MANUALCREATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_PAL_OPEN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


WM_CAP_PAL_PASTE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_PAL_SAVE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


WM_CAP_SEQUENCE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SEQUENCE_NOFILE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SET_AUDIOFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SET_CALLBACK_CAPCONTROL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SET_CALLBACK_ERROR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


WM_CAP_SET_CALLBACK_FRAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SET_CALLBACK_STATUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


WM_CAP_SET_CALLBACK_VIDEOSTREAM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SET_CALLBACK_WAVESTREAM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SET_CALLBACK_YIELD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SET_MCI_DEVICE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


WM_CAP_SET_OVERLAY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SET_PREVIEW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SET_PREVIEWRATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SET_SCALE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SET_SCROLL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SET_SEQUENCE_SETUP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SET_USER_DATA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SET_VIDEOFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SINGLE_FRAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SINGLE_FRAME_CLOSE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_SINGLE_FRAME_OPEN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAP_STOP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


WM_CAPTURECHANGED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CHANGECBCHAIN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CHAR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CHARTOITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CHILDACTIVATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CHOOSEFONT_GETLOGFONT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


WM_CHOOSEFONT_SETFLAGS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


WM_CHOOSEFONT_SETLOGFONT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


WM_CLEAR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CLOSE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_COMMAND
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_COMPACTING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_COMPAREITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CONTEXTMENU
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CONVERTREQUESTEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


WM_COPY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_COPYDATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CPL_LAUNCH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	cpl.h
Unicode	No
Platform Notes	None


WM_CPL_LAUNCHED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	cpl.h
Unicode	No
Platform Notes	None


WM_CREATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CTLCOLORBTN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CTLCOLORDLG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CTLCOLOREDIT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CTLCOLORLISTBOX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CTLCOLORMSGBOX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CTLCOLORSCROLLBAR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CTLCOLORSTATIC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CUT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DDE_ACK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_ADVISE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_DATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_EXECUTE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_INITIATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_POKE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_REQUEST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_TERMINATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_UNADVISE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DEADCHAR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DELETEITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DESTROY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DESTROYCLIPBOARD
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DEVICECHANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DEVMODECHANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DISPLAYCHANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DRAWCLIPBOARD
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DRAWITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DROPFILES
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ENABLE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ENDSESSION
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ENTERIDLE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ENTERMENULOOP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ENTERSIZEMOVE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ERASEBKGND
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_EXITMENULOOP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_EXITSIZEMOVE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_FONTCHANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_GETDLGCODE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_GETFONT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_GETHOTKEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_GETICON
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_GETMINMAXINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_GETTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_GETTEXTLENGTH
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_HELP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_HOTKEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_HSCROLL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_HSCROLLCLIPBOARD
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ICONERASEBKGND
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_IME_CHAR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


WM_IME_COMPOSITION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


WM_IME_COMPOSITIONFULL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


WM_IME_CONTROL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


WM_IME_ENDCOMPOSITION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


WM_IME_KEYDOWN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


WM_IME_KEYLAST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


WM_IME_KEYUP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


WM_IME_NOTIFY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


WM_IME_REPORT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ime.h
Unicode	No
Platform Notes	None


WM_IME_SELECT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


WM_IME_SETCONTEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


WM_IME_STARTCOMPOSITION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


WM_INITDIALOG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_INITMENU
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_INITMENUPOPUP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_INPUTLANGCHANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_INPUTLANGCHANGEREQUEST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_KEYDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_KEYFIRST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_KEYLAST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_KEYUP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_KILLFOCUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_LBUTTONDBLCLK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_LBUTTONDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_LBUTTONUP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MBUTTONDBLCLK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MBUTTONDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MBUTTONUP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDIACTIVATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDICASCADE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDICREATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDIDESTROY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDIGETACTIVE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDIICONARRANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDIMAXIMIZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDINEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDIREFRESHMENU
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDIRESTORE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDISETMENU
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDITILE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MEASUREITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MENUCHAR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MENUSELECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MOUSEACTIVATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MOUSEMOVE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MOUSEWHEEL
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


WM_MOVE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MOVING
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCACTIVATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCCALCSIZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCCREATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCDESTROY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCHITTEST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCLBUTTONDBLCLK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCLBUTTONDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCLBUTTONUP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCMBUTTONDBLCLK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCMBUTTONDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCMBUTTONUP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCMOUSEMOVE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCPAINT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCRBUTTONDBLCLK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCRBUTTONDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCRBUTTONUP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NEXTDLGCTL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NOTIFY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NOTIFYFORMAT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	Win32s: ANSI & Win95 controls only


WM_NULL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PAINT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PAINTCLIPBOARD
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PAINTICON
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PALETTECHANGED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PALETTEISCHANGING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PARENTNOTIFY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PASTE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_POWER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_POWERBROADCAST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PRINT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PRINTCLIENT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PSD_ENVSTAMPRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


WM_PSD_FULLPAGERECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


WM_PSD_GREEKTEXTRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


WM_PSD_MARGINRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


WM_PSD_MINMARGINRECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


WM_PSD_PAGESETUPDLG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


WM_PSD_YAFULLPAGERECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


WM_QUERYDRAGICON
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_QUERYENDSESSION
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_QUERYNEWPALETTE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_QUERYOPEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_QUEUESYNC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_QUIT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_RASDIALEVENT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ras.h
Unicode	No
Platform Notes	None


WM_RBUTTONDBLCLK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_RBUTTONDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_RBUTTONUP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_RENDERALLFORMATS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_RENDERFORMAT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SETCURSOR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SETFOCUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SETFONT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SETHOTKEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SETICON
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SETREDRAW
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SETTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SETTINGCHANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


WM_SHOWWINDOW
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SIZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SIZECLIPBOARD
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SIZING
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SPOOLERSTATUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_STYLECHANGED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_STYLECHANGING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SYSCHAR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SYSCOLORCHANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SYSCOMMAND
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SYSDEADCHAR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SYSKEYDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SYSKEYUP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_TCARD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_TIMECHANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_TIMER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_UNDO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_USER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_USERCHANGED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_VKEYTOITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_VSCROLL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_VSCROLLCLIPBOARD
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_WINDOWPOSCHANGED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_WINDOWPOSCHANGING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_WININICHANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


WOM_CLOSE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


WOM_DONE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


WOM_OPEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


WS_EX_CLIENTEDGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WS_EX_MDICHILD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WS_EX_WINDOWEDGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


ACN_START
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


ACN_STOP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


BN_CLICKED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_DBLCLK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_DISABLE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_DOUBLECLICKED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_HILITE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_KILLFOCUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_PAINT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_PUSHED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_SETFOCUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_UNHILITE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_UNPUSHED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_CLOSEUP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_DBLCLK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_DROPDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_EDITCHANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_EDITUPDATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_ERRSPACE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_KILLFOCUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_SELCHANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_SELENDCANCEL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_SELENDOK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_SETFOCUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


DBT_APPYBEGIN
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_APPYEND
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_CONFIGCHANGECANCELED
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_CONFIGCHANGED
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_CONFIGMGAPI32
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_CONFIGMGPRIVATE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_DEVICEARRIVAL
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_DEVICEQUERYREMOVE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_DEVICEQUERYREMOVEFAILED
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_DEVICEREMOVECOMPLETE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_DEVICEREMOVEPENDING
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_DEVICETYPESPECIFIC
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_DEVTYP_OEM
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_DEVTYP_PORT
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_DEVTYP_VOLUME
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_MONITORCHANGE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_NO_DISK_SPACE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_QUERYCHANGECONFIG
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_SHELLLOGGEDON
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_USERDEFINED
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_VOLLOCKLOCKFAILED
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_VOLLOCKLOCKRELEASED
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_VOLLOCKLOCKTAKEN
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_VOLLOCKQUERYLOCK
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_VOLLOCKQUERYUNLOCK
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DBT_VOLLOCKUNLOCKFAILED
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DL_BEGINDRAG
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


DL_CANCELDRAG
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


DL_COPYCURSOR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


DL_CURSORSET
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


DL_DRAGGING
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


DL_DROPPED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


DL_MOVECURSOR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


DL_STOPCURSOR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


EN_CHANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EN_CORRECTTEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EN_DROPFILES
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EN_ERRSPACE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EN_HSCROLL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EN_IMECHANGE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EN_KILLFOCUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EN_MAXTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EN_MSGFILTER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EN_OLEOPFAILED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EN_PROTECTED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EN_REQUESTRESIZE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EN_SAVECLIPBOARD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EN_SELCHANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EN_SETFOCUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EN_STOPNOUNDO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EN_UPDATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EN_VSCROLL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


HDN_BEGINTRACK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


HDN_DIVIDERDBLCLICK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


HDN_ENDTRACK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


HDN_ITEMCHANGED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


HDN_ITEMCHANGING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


HDN_ITEMCLICK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


HDN_ITEMDBLCLICK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


HDN_TRACK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


IMN_CHANGECANDIDATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMN_CLOSECANDIDATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMN_CLOSESTATUSWINDOW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMN_GUIDELINE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMN_OPENCANDIDATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMN_OPENSTATUSWINDOW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMN_SETCANDIDATEPOS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMN_SETCOMPOSITIONFONT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMN_SETCOMPOSITIONWINDOW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMN_SETCONVERSIONMODE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMN_SETOPENSTATUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMN_SETSENTENCEMODE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


IMN_SETSTATUSWINDOWPOS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


LBN_DBLCLK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LBN_ERRSPACE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LBN_KILLFOCUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LBN_SELCANCEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LBN_SELCHANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LBN_SETFOCUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


LVN_BEGINDRAG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVN_BEGINLABELEDIT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LVN_BEGINRDRAG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVN_COLUMNCLICK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVN_DELETEALLITEMS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVN_DELETEITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVN_ENDLABELEDIT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LVN_GETDISPINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LVN_INSERTITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVN_ITEMCHANGED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVN_ITEMCHANGING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVN_KEYDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LVN_SETDISPINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


NM_CLICK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


NM_DBLCLK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


NM_KILLFOCUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


NM_OUTOFMEMORY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


NM_RCLICK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


NM_RDBLCLK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


NM_RETURN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


NM_SETFOCUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


PBT_APMBATTERYLOW
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	pbt.h
Unicode	No
Platform Notes	None


PBT_APMOEMEVENT
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	pbt.h
Unicode	No
Platform Notes	None


PBT_APMPOWERSTATUSCHANGE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	pbt.h
Unicode	No
Platform Notes	None


PBT_APMQUERYSTANDBY
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	pbt.h
Unicode	No
Platform Notes	None


PBT_APMQUERYSTANDBYFAILED
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	pbt.h
Unicode	No
Platform Notes	None


PBT_APMQUERYSUSPEND
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	pbt.h
Unicode	No
Platform Notes	None


PBT_APMQUERYSUSPENDFAILED
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	pbt.h
Unicode	No
Platform Notes	None


PBT_APMRESUMECRITICAL
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	pbt.h
Unicode	No
Platform Notes	None


PBT_APMRESUMEFROMFAILURE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	pbt.h
Unicode	No
Platform Notes	None


PBT_APMRESUMESTANDBY
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	pbt.h
Unicode	No
Platform Notes	None


PBT_APMRESUMESUSPEND
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	pbt.h
Unicode	No
Platform Notes	None


PBT_APMSTANDBY
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	pbt.h
Unicode	No
Platform Notes	None


PBT_APMSUSPEND
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	pbt.h
Unicode	No
Platform Notes	None


PSN_APPLY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSN_HELP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSN_KILLACTIVE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSN_QUERYCANCEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSN_RESET
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSN_SETACTIVE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSN_WIZBACK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSN_WIZFINISH
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PSN_WIZNEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_COPYERROR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_DELETEERROR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_ENDCOPY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_ENDDELETE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_ENDQUEUE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_ENDRENAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_ENDSUBQUEUE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_FILEEXTRACTED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_FILEINCABINET
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_FILEOPDELAYED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_LANGMISMATCH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_NEEDMEDIA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_NEEDNEWCABINET
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_QUEUESCAN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_RENAMEERROR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_STARTCOPY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_STARTDELETE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_STARTQUEUE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_STARTRENAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_STARTSUBQUEUE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_TARGETEXISTS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPFILENOTIFY_TARGETNEWER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


TBN_BEGINADJUST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBN_BEGINDRAG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBN_CUSTHELP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBN_ENDADJUST
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBN_ENDDRAG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBN_GETBUTTONINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TBN_QUERYDELETE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBN_QUERYINSERT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBN_RESET
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBN_TOOLBARCHANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TCN_KEYDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	no
Platform Notes	None


TCN_SELCHANGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	no
Platform Notes	None


TCN_SELCHANGING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	no
Platform Notes	None


TTN_NEEDTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TTN_POP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TTN_SHOW
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVN_BEGINDRAG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TVN_BEGINLABELEDIT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TVN_BEGINRDRAG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TVN_DELETEITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TVN_ENDLABELEDIT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TVN_GETDISPINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TVN_ITEMEXPANDED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TVN_ITEMEXPANDING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TVN_KEYDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TVN_SELCHANGED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TVN_SELCHANGING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TVN_SETDISPINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


UDN_DELTAPOS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


AddressEntry OLE Messaging object
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Attachment OLE Messaging object
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Attachments Collection OLE Messaging object
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Field OLE Messaging object
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Fields Collection OLE Messaging object
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Folder OLE Messaging object
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Folders Collection OLE Messaging object
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


InfoStore OLE Messaging object
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


InfoStores Collection OLE Messaging object
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Message OLE Messaging object
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Messages Collection OLE Messaging object
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Recipient OLE Messaging object
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Recipients Collection OLE Messaging object
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Session OLE Messaging object
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Address property (AddressEntry OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Address property (Recipient OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


AddressEntry property (Recipient OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Application property
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Attachments property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Class property
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Conversation property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


ConversationIndex property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


ConversationTopic property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Count property (Attachments Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Count property (Fields Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Count property (InfoStores Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Count property (Recipients Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


CurrentUser property (Session OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


DeliveryReceipt property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


DisplayType property (AddressEntry OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


DisplayType property (Recipient OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Encrypted property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Fields property (AddressEntry OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Fields property (Folder OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Fields property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


FolderID property (Folder OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


FolderID property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Folders property (Folder OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


ID property (AddressEntry OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


ID property (Field OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


ID property (Folder OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


ID property (InfoStore OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


ID property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Importance property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Inbox property (Session OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Index property (Attachment OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Index property (Field OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Index property (InfoStore OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Index property (Recipient OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


InfoStores property (Session OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Item property (Attachments Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Item property (Fields Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Item property (InfoStores Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Item property (Recipients Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


MAPIOBJECT property (Folder OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


MAPIOBJECT property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


MAPIOBJECT property (Session OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Members property (AddressEntry OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Messages property (Folder OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Name property (AddressEntry OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Name property (Attachment OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Name property (Field OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Name property (Folder OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Name property (InfoStore OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Name property (Recipient OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Name property (Session OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


OperatingSystem property (Session OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Outbox property (Session OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Parent property
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Position property (Attachment OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


PR_7BIT_DISPLAY_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_AB_DEFAULT_DIR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_AB_DEFAULT_PAB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_AB_PROVIDER_ID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_AB_PROVIDERS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_AB_SEARCH_PATH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_AB_SEARCH_PATH_UPDATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ACCESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ACCESS_LEVEL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ACCOUNT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ACKNOWLEDGEMENT_MODE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ADDRTYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ALTERNATE_RECIPIENT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ALTERNATE_RECIPIENT_ALLOWED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ANR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ASSISTANT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ASSISTANT_TELEPHONE_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ASSOC_CONTENT_COUNT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ATTACH_DATA_BIN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ATTACH_DATA_OBJ
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ATTACH_ENCODING
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ATTACH_EXTENSION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ATTACH_LONG_PATHNAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ATTACH_METHOD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ATTACH_MIME_TAG
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ATTACH_NUM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ATTACH_PATHNAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ATTACH_RENDERING
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ATTACH_SIZE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ATTACH_TAG
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ATTACH_TRANSPORT_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ATTACHMENT_X400_PARAMETERS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_AUTHORIZING_USERS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_AUTO_FORWARD_COMMENT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_AUTO_FORWARDED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_BODY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_BODY_CRC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_BUSINESS_FAX_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_BUSINESS_TELEPHONE_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_BUSINESS2_TELEPHONE_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CALLBACK_TELEPHONE_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CAPABILITIES_TABLE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CAR_TELEPHONE_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CLIENT_SUBMIT_TIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_COMMENT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_COMMON_VIEWS_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_COMPANY_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTAINER_CLASS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTAINER_CONTENTS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTAINER_FLAGS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTAINER_HIERARCHY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTAINER_MODIFY_VERSION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTENT_CONFIDENTIALITY_ALGORITHM_ID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTENT_CORRELATOR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTENT_COUNT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTENT_IDENTIFIER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTENT_INTEGRITY_CHECK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTENT_LENGTH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTENT_RETURN_REQUESTED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTENT_UNREAD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTENTS_SORT_ORDER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTROL_FLAGS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTROL_ID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTROL_STRUCTURE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONTROL_TYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONVERSATION_INDEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONVERSATION_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONVERSATION_PR_CONVERSION_EITS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONVERSION_PROHIBITED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONVERSION_WITH_LOSS_PROHIBITED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CONVERTED_EITS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CORRELATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CORRELATE_MTSID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_COUNTRY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CREATE_TEMPLATES
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CREATION_TIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CREATION_VERSION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_CURRENT_VERSION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DEF_CREATE_DL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DEF_CREATE_MAILUSER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DEFAULT_STORE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DEFAULT_VIEW_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DEFERRED_DELIVERY_TIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DELEGATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DELETE_AFTER_SUBMIT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DELIVER_TIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DELIVERY_POINT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DELTAX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DELTAY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DEPARTMENT_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DEPTH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DETAILS_TABLE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DISC_VAL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DISCARD_REASON
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DISCLOSURE_OF_RECIPIENTS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DISCRETE_VALUES
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DISPLAY_BCC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DISPLAY_CC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DISPLAY_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DISPLAY_TO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DISPLAY_TYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DL_EXPANSION_HISTORY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_DL_EXPANSION_PROHIBITED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_EMAIL_ADDRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_END_DATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_EXPIRY_TIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_EXPLICIT_CONVERSION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_FILTERING_HOOKS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_FINDER_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_FOLDER_ASSOCIATED_CONTENTS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_FOLDER_TYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_FORM_CATEGORY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_FORM_CATEGORY_SUB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_FORM_CLSID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_FORM_CONTACT_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_FORM_DESIGNER_GUID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_FORM_DESIGNER_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_FORM_HIDDEN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_FORM_HOST_MAP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_FORM_MESSAGE_BEHAVIOR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_FORM_VERSION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_GENERATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_GIVEN_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_GOVERNMENT_ID_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_HASATTACH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_HEADER_FOLDER_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_HOME_FAX_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_HOME_TELEPHONE_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_HOME2_TELEPHONE_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ICON
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_IDENTITY_DISPLAY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_IDENTITY_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_IDENTITY_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_IMPLICIT_CONVERSION_PROHIBITED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_IMPORTANCE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_INCOMPLETE_COPY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_INITIAL_DETAILS_PANE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_INITIALS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_INSTANCE_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_IPM_ID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_IPM_OUTBOX_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_IPM_OUTBOX_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_IPM_RETURN_REQUESTED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_IPM_SENTMAIL_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_IPM_SENTMAIL_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_IPM_SUBTREE_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_IPM_SUBTREE_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_IPM_WASTEBASKET_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_IPM_WASTEBASKET_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ISDN_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_KEYWORD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_LANGUAGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_LANGUAGES
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_LAST_MODIFICATION_TIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_LATEST_DELIVERY_TIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_LOCALITY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_LOCATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MAIL_PERMISSION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MAPPING_SIGNATURE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MDB_PROVIDER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MESSAGE_ATTACHMENTS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MESSAGE_CC_ME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MESSAGE_CLASS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MESSAGE_DELIVERY_ID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MESSAGE_DELIVERY_TIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MESSAGE_DOWNLOAD_TIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MESSAGE_FLAGS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MESSAGE_RECIP_ME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MESSAGE_RECIPIENTS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MESSAGE_SECURITY_LABEL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MESSAGE_SIZE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MESSAGE_SUBMISSION_ID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MESSAGE_TO_ME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MESSAGE_TOKEN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MHS_COMMON_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MINI_ICON
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MOBILE_TELEPHONE_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MODIFY_VERSION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_MSG_STATUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_NDR_DIAG_CODE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_NDR_REASON_CODE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_NON_RECEIPT_NOTIFICATION_REQUESTED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_NON_RECEIPT_REASON
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_NORMALIZED_SUBJECT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_NULL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_OBJECT_TYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_OBSOLETED_IPMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_OFFICE_LOCATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORGANIZATIONAL_ID_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIG_MESSAGE_CLASS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGIN_CHECK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_AUTHOR_ADDRTYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_AUTHOR_EMAIL_ADDRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_AUTHOR_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_AUTHOR_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_AUTHOR_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_DELIVERY_TIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_DISPLAY_BCC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_DISPLAY_CC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_DISPLAY_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_DISPLAY_TO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_EITS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_SENDER_ADDRTYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_SENDER_EMAIL_ADDRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_SENDER_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_SENDER_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_SENDER_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_SENSITIVITY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_SENT_REPRESENTING_ADDRTYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_SENT_REPRESENTING_EMAIL_ADDRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_SENT_REPRESENTING_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_SENT_REPRESENTING_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_SENT_REPRESENTING_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_SUBJECT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINAL_SUBMIT_TIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINALLY_INTENDED_RECIP_ADDRTYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINALLY_INTENDED_RECIP_EMAIL_ADDRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINALLY_INTENDED_RECIP_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINALLY_INTENDED_RECIPIENT_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINATING_MTA_CERTIFICATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINATOR_AND_DL_EXPANSION_HISTORY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINATOR_CERTIFICATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINATOR_NON_DELIVERY_REPORT_REQUESTED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINATOR_REQUESTED_ALTERNATE_RECIPIENT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ORIGINATOR_RETURN_ADDRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_OTHER_TELEPHONE_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_OWN_STORE_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_OWNER_APPT_ID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PAGER_TELEPHONE_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PARENT_DISPLAY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PARENT_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PARENT_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PHYSICAL_DELIVERY_BUREAU_FAX_DELIVERY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PHYSICAL_DELIVERY_MODE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PHYSICAL_DELIVERY_REPORT_REQUEST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PHYSICAL_FORWARDING_ADDRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PHYSICAL_FORWARDING_ADDRESS_REQUESTED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PHYSICAL_FORWARDING_PROHIBITED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PHYSICAL_RENDITION_ATTRIBUTES
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_POST_OFFICE_BOX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_POSTAL_ADDRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_POSTAL_CODE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PREPROCESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PRIMARY_CAPABILITY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PRIMARY_FAX_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PRIMARY_TELEPHONE_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PRIORITY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PROOF_OF_DELIVERY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PROOF_OF_DELIVERY_REQUESTED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PROOF_OF_SUBMISSION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PROOF_OF_SUBMISSION_REQUESTED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PROVIDER_DISPLAY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PROVIDER_DLL_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PROVIDER_ORDINAL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PROVIDER_SUBMIT_TIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_PROVIDER_UID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RADIO_TELEPHONE_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RCVD_REPRESENTING_ADDRTYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RCVD_REPRESENTING_EMAIL_ADDRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RCVD_REPRESENTING_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RCVD_REPRESENTING_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RCVD_REPRESENTING_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_READ_RECEIPT_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_READ_RECEIPT_REQUESTED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_READ_RECEIPT_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RECEIPT_TIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RECEIVE_FOLDER_SETTINGS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RECEIVED_BY_ADDRTYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RECEIVED_BY_EMAIL_ADDRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RECEIVED_BY_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RECEIVED_BY_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RECEIVED_BY_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RECIPIENT_CERTIFICATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RECIPIENT_NUMBER_FOR_ADVICE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RECIPIENT_REASSIGNMENT_PROHIBITED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RECIPIENT_STATUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RECIPIENT_TYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RECORD_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REDIRECTION_HISTORY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REGISTERED_MAIL_TYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RELATED_IPMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REMOTE_PROGRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REMOTE_PROGRESS_TEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REMOTE_VALIDATE_OK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RENDERING_POSITION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REPLY_RECIPIENT_ENTRIES
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REPLY_RECIPIENT_NAMES
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REPLY_REQUESTED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REPLY_TIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REPORT_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REPORT_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REPORT_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REPORT_TAG
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REPORT_TEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REPORT_TIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REPORTING_DL_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REPORTING_MTA_CERTIFICATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_REQUESTED_DELIVERY_METHOD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RESOURCE_FLAGS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RESOURCE_METHODS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RESOURCE_PATH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RESOURCE_TYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RESPONSE_REQUESTED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RESPONSIBILITY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RETURNED_IPM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ROW_TYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_ROWID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RTF_COMPRESSED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RTF_SYNC_BODY_COUNT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RTF_SYNC_BODY_CRC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RTF_SYNC_BODY_TAG
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RTF_SYNC_PREFIX_COUNT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_RTF_SYNC_TRAILING_COUNT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SEARCH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SECURITY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SELECTABLE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SEND_RICH_INFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SENDER_ADDRTYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SENDER_EMAIL_ADDRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SENDER_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SENDER_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SENDER_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SENSITIVITY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SENT_REPRESENTING_ADDRTYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SENT_REPRESENTING_EMAIL_ADDRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SENT_REPRESENTING_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SENT_REPRESENTING_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SENT_REPRESENTING_SEARCH_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SENTMAIL_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SERVICE_DLL_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SERVICE_ENTRY_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SERVICE_EXTRA_UIDS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SERVICE_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SERVICE_UID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SERVICES
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SPOOLER_STATUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_START_DATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_STATE_OR_PROVINCE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_STATUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_STATUS_CODE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_STATUS_STRING
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_STORE_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_STORE_PROVIDERS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_STORE_RECORD_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_STORE_STATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_STORE_SUPPORT_MASK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_STREET_ADDRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SUBFOLDERS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SUBJECT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SUBJECT_IPM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SUBJECT_PREFIX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SUBMIT_FLAGS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SUPPLEMENTARY_INFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_SURNAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_TELEX_NUMBER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_TEMPLATEID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_TITLE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_TNEF_CORRELATION_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_TRANSMITTABLE_DISPLAY_NAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_TRANSPORT_KEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_TRANSPORT_MESSAGE_HEADERS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_TRANSPORT_PROVIDERS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_TRANSPORT_STATUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_TYPE_OF_MTS_USER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_USER_CERTIFICATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_VALID_FOLDER_MASK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_VIEWS_ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_WIZARD_NO_PAB_PAGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiwz.h
Unicode	No
Platform Notes	None


PR_WIZARD_NO_PST_PAGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiwz.h
Unicode	No
Platform Notes	None


PR_X400_CONTENT_TYPE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_X400_DEFERRED_DELIVERY_CANCEL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_XPOS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


PR_YPOS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapitags.h
Unicode	No
Platform Notes	None


ProviderName property (InfoStore OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


ReadReceipt property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Recipients property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Resolved property (Recipients Collection)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


RootFolder property (InfoStore OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Sender property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Sent property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Session property
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Signed property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Size property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Source property (Attachment OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


StoreID property (Folder OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


StoreID property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Subject property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Submitted property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Text property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


TimeReceived property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


TimeSent property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Type property (AddressEntry OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Type property (Attachment OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Type property (Field OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Type property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Type property (Recipient OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Unread property (Message OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Value property (Field OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


Version property (Session OLE Messaging object)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mdisp.odl
Unicode	No
Platform Notes	None


COLOROKSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


FILEOKSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


FINDMSGSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


HELPMSGSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


LBSELCHSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


RASDIALEVENT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ras.h
Unicode	No
Platform Notes	None


SETRGBSTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


SHAREVISTRING
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


ACCESS_TOKEN
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


BOOKMARK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


BYTE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


CMC_boolean
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_buffer
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_enum
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_flags
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_object_identifier
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_return_code
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_session_id
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_string
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_ui_id
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


D3DCOLOR
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DVALUE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


HCALL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


HCOLORSPACE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	windef.h
Unicode	No
Platform Notes	None


HLINE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


HLINEAPP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


HPHONE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


HPHONEAPP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


HRESULT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wtypes.h
Unicode	No
Platform Notes	None


LHANDLE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


LONG
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


MapiFile (VB)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapivb32.bas
Unicode	No
Platform Notes	None


MapiMessage (VB)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapivb32.bas
Unicode	No
Platform Notes	None


MapiRecip (VB)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapivb32.bas
Unicode	No
Platform Notes	None


SCODE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wtypes.h
Unicode	No
Platform Notes	None


TCHAR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


ULONG
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


WCHAR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


QACONTAINER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


QACONTROL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


_DEV_BROADCAST_USERDEFINED
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


ABC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


ABCFLOAT
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


ACCEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


ACCESS_ALLOWED_ACE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


ACCESS_DENIED_ACE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


ACCESS_INFO_0
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


ACCESS_INFO_1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


ACCESS_MASK
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


ACCESSTIMEOUT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


ACE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


ACE_HEADER
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


ACL
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


ACL_REVISION_INFORMATION
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


ACL_SIZE_INFORMATION
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


ACMDRIVERDETAILS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


ACMFILTERCHOOSE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


ACMFILTERDETAILS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


ACMFILTERTAGDETAILS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


ACMFORMATCHOOSE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


ACMFORMATDETAILS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


ACMFORMATTAGDETAILS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


ACMSTREAMHEADER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	msacm.h
Unicode	No
Platform Notes	None


ACTION_HEADER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	nb30.h
Unicode	No
Platform Notes	None


ADAPTER_STATUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	nb30.h
Unicode	No
Platform Notes	None


ADDJOB_INFO_1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


ADDRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


ADMIN_OTHER_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	lmalert.h
Unicode	No
Platform Notes	None


ADRENTRY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


ADRLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


ADRPARM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


ANIMATIONINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


API_VERSION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


APPBARDATA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


AT_ENUM
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmat.h
Unicode	No
Platform Notes	None


AT_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmat.h
Unicode	No
Platform Notes	None


AUDIT_ENTRY
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaudit.h
Unicode	No
Platform Notes	None


AUXCAPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


AVICOMPRESSOPTIONS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFILEINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


AVISTREAMINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


BIND_OPTS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


BITMAP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


BITMAPCOREHEADER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


BITMAPCOREINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


BITMAPFILEHEADER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


BITMAPINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


BITMAPINFOHEADER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


BITMAPV4HEADER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


BLOB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wtypes.h
Unicode	No
Platform Notes	None


BROWSEINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


BY_HANDLE_FILE_INFORMATION
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


CABINET_INFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


CADWORD
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


CALPOLESTR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


CANDIDATEFORM
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


CANDIDATELIST
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


CAPDRIVERCAPS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


CAPINFOCHUNK
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


CAPSTATUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


CAPTUREPARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


CAUUID
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


CBT_CREATEWND
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CBTACTIVATESTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CHAR_INFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wincon.h
Unicode	No
Platform Notes	None


CHARFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	WinNT
Platform Notes	None


CHARRANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


CHARSET
Windows NT
Win95
Win32s
Import Library	-
Header File
Unicode
Platform Notes	None


CHARSETINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


CHOOSECOLOR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


CHOOSEFONT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


CIDA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


CIEXYZ
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


CIEXYZTRIPLE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


CLIENTCREATESTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CMC_attachment
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_counted_string
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_extension
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_message
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_message_reference
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_message_summary
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_recipient
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_time
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmc.h
Unicode	No
Platform Notes	None


CMC_X_COM_configuration
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcext.h
Unicode	No
Platform Notes	None


CMC_X_COM_support
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcext.h
Unicode	No
Platform Notes	None


CMC_X_MS_ATTACH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	xcmcmsx2.h
Unicode	No
Platform Notes	None


CMINVOKECOMMANDINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


COLORADJUSTMENT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


COLORMAP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


COLORREF
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	windef.h
Unicode	No
Platform Notes	None


COMMCONFIG
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


COMMPROP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


COMMTIMEOUTS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


COMPAREITEMSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


COMPCOLOR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


COMPOSITIONFORM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	No
Platform Notes	None


COMPVARS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


COMSTAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


CONFIG_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmconfig.h
Unicode	No
Platform Notes	None


CONFIG_INFO_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmconfig.h
Unicode	No
Platform Notes	None


CONNECTDATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


CONNECTION_INFO_0
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


CONNECTION_INFO_1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


CONSOLE_CURSOR_INFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wincon.h
Unicode	No
Platform Notes	None


CONSOLE_SCREEN_BUFFER_INFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wincon.h
Unicode	No
Platform Notes	None


CONTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


CONTROLINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


CONVCONTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


CONVINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


COORD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wincon.h
Unicode	No
Platform Notes	None


COPYDATASTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


COSERVERINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


CPINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winnls.h
Unicode	No
Platform Notes	None


CPLINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	cpl.h
Unicode	No
Platform Notes	None


CREATE_PROCESS_DEBUG_INFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


CREATE_THREAD_DEBUG_INFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


CREATESTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CSADDR_INFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	nspapi.h
Unicode	No
Platform Notes	None


CURRENCY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


CURRENCYFMT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


CURSORSHAPE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CWPRETSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


CWPSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


D3DBRANCH
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DCOLORVALUE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DDEVICEDESC
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DEXECUTEBUFFERDESC
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DEXECUTEDATA
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DFINDDEVICERESULT
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DFINDDEVICESEARCH
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DHVERTEX
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DINSTRUCTION
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DLIGHT
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DLIGHTDATA
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DLIGHTINGCAPS
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DLIGHTINGELEMENT
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DLINE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DLINEPATTERN
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DLVERTEX
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DMATERIAL
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DMATRIX
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DMATRIXLOAD
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DMATRIXMULTIPLY
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DPICKRECORD
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DPOINT
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DPRIMCAPS
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DPROCESSVERTICES
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DRECT
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DRMBOX
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMIMAGE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMLOADMEMORY
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMLOADRESOURCE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMPALETTEENTRY
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMPICKDESC
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMQUATERNION
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMVECTOR4D
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DRMVERTEX
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	d3drm.h
Unicode	No
Platform Notes	None


D3DSPAN
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DSTATE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DSTATS
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DSTATUS
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DTEXTURELOAD
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DTLVERTEX
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DTRANSFORMCAPS
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DTRANSFORMDATA
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DTRIANGLE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DVECTOR
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DVERTEX
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


D3DVIEWPORT
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


DATATYPES_INFO_1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DCB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


DDBLTBATCH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


DDBLTFX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


DDCAPS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


DDCOLORKEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


DDEACK
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	dde.h
Unicode	No
Platform Notes	None


DDEADVISE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	dde.h
Unicode	No
Platform Notes	None


DDEDATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	dde.h
Unicode	No
Platform Notes	None


DDEML_MSG_HOOK_DATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


DDEPOKE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	dde.h
Unicode	No
Platform Notes	None


DDOVERLAYFX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


DDPIXELFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


DDSCAPS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


DDSURFACEDESC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ddraw.h
Unicode	No
Platform Notes	None


DEBUG_EVENT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


DEBUGHOOKINFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


DELETEITEMSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


DEV_BROADCAST_DEVNODE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DEV_BROADCAST_HDR
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DEV_BROADCAST_NET
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DEV_BROADCAST_OEM
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DEV_BROADCAST_PORT
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DEV_BROADCAST_VOLUME
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	dbt.h
Unicode	No
Platform Notes	None


DEVMODE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


DEVNAMES
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	No
Platform Notes	None


DIBSECTION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


DISK_GEOMETRY
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


DISK_PERFORMANCE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


DLGITEMTEMPLATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


DLGITEMTEMPLATEEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


DLGTEMPLATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


DLGTEMPLATEEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


DOC_INFO_1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DOC_INFO_2
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	Win95
Platform Notes	None


DOCINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


DOCUMENTPROPERTYHEADER
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winspool.h
Unicode
Platform Notes	None


DPCAPS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


DPMSG_ADDPLAYER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


DPMSG_DELETEPLAYER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


DPMSG_GENERIC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


DPMSG_GROUPADD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


DPMSG_GROUPDELETE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


DPSESSIONDESC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dplay.h
Unicode	No
Platform Notes	None


DRAGLISTINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


DRAWDIBTIME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


DRAWITEMSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


DRAWTEXTPARAMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


DRIVE_LAYOUT_INFORMATION
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


DRIVER_INFO_1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DRIVER_INFO_2
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DRIVER_INFO_3
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DROPFILES
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


DRVCONFIGINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DSBCAPS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


DSBUFFERDESC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


DSCAPS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	dsound.h
Unicode	No
Platform Notes	None


DTBLBUTTON
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


DTBLCHECKBOX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


DTBLCOMBOBOX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


DTBLDDLBX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


DTBLEDIT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


DTBLGROUPBOX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


DTBLLABEL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


DTBLLBX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


DTBLMVDDLBOX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


DTBLMVLISTBOX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


DTBLPAGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


DTBLRADIOBUTTON
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


DTCTL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


DTPAGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


DVASPECTINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


DVEXTENTINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


DVTARGETDEVICE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	Winbase.h
Unicode	Yes
Platform Notes	None


EDITSTREAM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


EMR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRANGLEARC
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRARC, EMRARCTO, EMRCHORD, EMRPIE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRBITBLT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRCREATEBRUSHINDIRECT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRCREATECOLORSPACE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRCREATEDIBPATTERNBRUSHPT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRCREATEMONOBRUSH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRCREATEPALETTE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRCREATEPEN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRELLIPSE, EMRRECTANGLE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMREOF
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMREXCLUDECLIPRECT, EMRINTERSECTCLIPRECT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMREXTCREATEFONTINDIRECTW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMREXTCREATEPEN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMREXTFLOODFILL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMREXTSELECTCLIPRGN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMREXTTEXTOUTA, EMREXTTEXTOUTW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRFILLPATH, EMRSTROKEANDFILLPATH, EMRSTROKEPATH
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRFILLRGN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRFRAMERGN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRGDICOMMENT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRINVERTRGN, EMRPAINTRGN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRLINETO, EMRMOVETOEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRMASKBLT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRMODIFYWORLDTRANSFORM
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMROFFSETCLIPRGN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRPLGBLT
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRPOLYDRAW
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRPOLYDRAW16
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRPOLYLINE, EMRPOLYBEZIER, EMRPOLYGON, EMRPOLYBEZIERTO, EMRPOLYLINETO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRPOLYLINE16, EMRPOLYBEZIER16, EMRPOLYGON16, EMRPOLYBEZIERTO16, EMRPOLYLINETO16
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRPOLYPOLYLINE, EMRPOLYPOLYGON
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRPOLYPOLYLINE16, EMRPOLYPOLYGON16
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRPOLYTEXTOUTA, EMRPOLYTEXTOUTW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRRESIZEPALETTE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRRESTOREDC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRROUNDRECT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSCALEVIEWPORTEXTEX, EMRSCALEWINDOWEXTEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSELECTCOLORSPACE, EMRDELETECOLORSPACE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSELECTOBJECT, EMRDELETEOBJECT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSELECTPALETTE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSETARCDIRECTION
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSETBKCOLOR, EMRSETTEXTCOLOR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSETCOLORADJUSTMENT
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSETDIBITSTODEVICE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSETMAPPERFLAGS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSETMITERLIMIT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSETPALETTEENTRIES
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSETPIXELV
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSETVIEWPORTEXTEX, EMRSETWINDOWEXTEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSETVIEWPORTORGEX, EMRSETWINDOWORGEX, EMRSETBRUSHORGEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSETWORLDTRANSFORM
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSTRETCHBLT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRSTRETCHDIBITS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


EMRTEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


ENCORRECTTEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


ENDROPFILES
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


ENHMETAHEADER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


ENHMETARECORD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


ENOLEOPFAILED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


ENPROTECTED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


ENSAVECLIPBOARD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


ENTRYID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


ENTRYLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


ENUM_SERVICE_STATUS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


ENUMLOGFONT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


ENUMLOGFONTEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


ERRLOG_OTHER_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmalert.h
Unicode	No
Platform Notes	None


ERROR_NOTIFICATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


EVENTLOGRECORD
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


EVENTMSG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


EXCEPTION_DEBUG_INFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


EXCEPTION_POINTERS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


EXCEPTION_RECORD
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


EXIT_PROCESS_DEBUG_INFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


EXIT_THREAD_DEBUG_INFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


EXPLICIT_ACCESS
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	accctrl.h
Unicode	WinNT
Platform Notes	None


EXT_BUTTON
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	No
Platform Notes	None


EXTENDED_NOTIFICATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


EXTLOGFONT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


EXTLOGPEN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


FILE_IN_CABINET_INFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


FILE_INFO_2
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


FILE_INFO_3
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


FILE_NOTIFY_INFORMATION
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


FILEDESCRIPTOR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


FILEGROUPDESCRIPTOR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


FILEPATHS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


FILETIME
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


FILETIME
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	olectl.h
Unicode	Yes
Platform Notes	None


FILTERKEYS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


FIND_NAME_BUFFER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	nb30.h
Unicode	No
Platform Notes	None


FIND_NAME_HEADER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	nb30.h
Unicode	No
Platform Notes	None


FINDREPLACE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


FINDTEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	WinNT
Platform Notes	None


FINDTEXTEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	WinNT
Platform Notes	None


FIXED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


FLAGLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


FLATENTRY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


FLATENTRYLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


FLATMTSIDLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


FMS_GETDRIVEINFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	WinNT
Platform Notes	None


FMS_GETFILESEL
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	WinNT
Platform Notes	None


FMS_LOAD
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	WinNT
Platform Notes	None


FMS_TOOLBARLOAD
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wfext.h
Unicode	No
Platform Notes	None


FOCUS_EVENT_RECORD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wincon.h
Unicode	No
Platform Notes	None


FOLDERSETTINGS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


FONTDESC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	olectl.h
Unicode	Yes
Platform Notes	None


FONTSIGNATURE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


FORM_INFO_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


FORMAT_PARAMETERS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


FORMATETC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


FORMATRANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


FORMPRINTSETUP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


FVSHOWINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


GCP_RESULTS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


GENERIC_MAPPING
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


GLYPHMETRICS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


GLYPHMETRICSFLOAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


GROUP_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


GROUP_INFO_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


GROUP_INFO_1002
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


GROUP_INFO_1005
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


GROUP_INFO_2
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


GROUP_USERS_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


GROUP_USERS_INFO_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


GUID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiguid.h
Unicode	No
Platform Notes	None


HANDLE_INFO_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmchdev.h
Unicode	No
Platform Notes	None


HANDLETABLE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


HD_HITTESTINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


HD_ITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


HD_LAYOUT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


HD_NOTIFY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


HELPINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


HELPWININFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


HIGHCONTRAST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


HSZPAIR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


HW_PROFILE_INFO
Windows NT	Yes
Win95	OSR2
Win32s	No
Import Library
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ICCOMPRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCOMPRESSFRAMES
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDECOMPRESS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDECOMPRESSEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDRAW
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDRAWBEGIN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDRAWSUGGEST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICONINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


ICONMETRICS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


ICOPEN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


ICSETSTATUSPROC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vfw.h
Unicode	No
Platform Notes	None


IID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiguid.h
Unicode	No
Platform Notes	None


IMAGE_DEBUG_INFORMATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


IMAGEHLP_DEFERRED_SYMBOL_LOAD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


IMAGEHLP_DUPLICATE_SYMBOL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


IMAGEHLP_MODULE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


IMAGEHLP_SYMBOL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


IMAGEINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


INFCONTEXT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


INPUT_RECORD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wincon.h
Unicode	No
Platform Notes	None


INTERFACEINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


ITEMIDLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


JOB_INFO_1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


JOB_INFO_2
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


JOB_INFO_3
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	No
Platform Notes	None


JOYCAPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


JOYINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


JOYINFOEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


KDHELP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


KERNINGPAIR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


KEY_EVENT_RECORD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wincon.h
Unicode	No
Platform Notes	None


KEYARRAY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


LANA_ENUM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	nb30.h
Unicode	No
Platform Notes	None


LARGE_INTEGER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


LDT_ENTRY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


LICINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


LINEADDRESSCAPS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEADDRESSSTATUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEAGENTACTIVITYENTRY
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEAGENTACTIVITYLIST
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEAGENTCAPS
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEAGENTGROUPENTRY
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEAGENTGROUPLIST
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEAGENTSTATUS
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEAPPINFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINECALLINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINECALLLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINECALLPARAMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINECALLSTATUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINECALLTREATMENTENTRY
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINECARDENTRY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINECOUNTRYENTRY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINECOUNTRYLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEDEVCAPS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEDEVSTATUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEDIALPARAMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEEXTENSIONID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEFORWARD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEFORWARDLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEGENERATETONE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEINITIALIZEEXPARAMS
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINELOCATIONENTRY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEMEDIACONTROLCALLSTATE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEMEDIACONTROLDIGIT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEMEDIACONTROLMEDIA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEMEDIACONTROLTONE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEMESSAGE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEMONITORTONE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEPROVIDERENTRY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEPROVIDERLIST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEPROXYREQUEST
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINEREQMAKECALL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode	WinNT
Platform Notes	None


LINETERMCAPS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINETRANSLATECAPS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LINETRANSLATEOUTPUT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


LIST_ENTRY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	imagehlp.h
Unicode	No
Platform Notes	None


LOAD_DLL_DEBUG_INFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


LOADED_IMAGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


LOCALESIGNATURE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


LOCALGROUP_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


LOCALGROUP_INFO_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


LOCALGROUP_INFO_1002
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


LOCALGROUP_MEMBERS_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


LOCALGROUP_MEMBERS_INFO_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


LOCALGROUP_MEMBERS_INFO_2
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


LOCALGROUP_MEMBERS_INFO_3
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


LOCALGROUP_USERS_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


LOGBRUSH
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


LOGCOLORSPACE
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	Win95
Platform Notes	None


LOGFONT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


LOGPALETTE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


LOGPEN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


LS_CHALLDATA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	lsapi32.lib
Header File	lsapi.h
Unicode	No
Platform Notes	None


LS_CHALLENGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	lsapi32.lib
Header File	lsapi.h
Unicode	No
Platform Notes	None


LS_MSG_DIGEST
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	lsapi32.lib
Header File	lsapi.h
Unicode	No
Platform Notes	None


LUID
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


LUID_AND_ATTRIBUTES
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


LV_COLUMN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LV_DISPINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LV_FINDINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LV_HITTESTINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


LV_ITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


LV_KEYDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


MAPIERROR
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


MapiFileDesc (Simple MAPI)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MapiFileTagExt (Simple MAPI)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MAPIINIT_0
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapix.h
Unicode	No
Platform Notes	None


MapiMessage (Simple MAPI)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MAPINAMEID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


MapiRecipDesc (Simple MAPI)
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapi.h
Unicode	No
Platform Notes	None


MAPIUID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


MAT2
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


MCI_ANIM_OPEN_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_ANIM_PLAY_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_ANIM_RECT_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_ANIM_STEP_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_ANIM_UPDATE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_ANIM_WINDOW_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_BREAK_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_DGV_CAPTURE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	WinNT
Platform Notes	None


MCI_DGV_COPY_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_CUE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_CUT_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_DELETE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_FREEZE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_INFO_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	WinNT
Platform Notes	None


MCI_DGV_LIST_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	WinNT
Platform Notes	None


MCI_DGV_LOAD_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_MONITOR_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_OPEN_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	WinNT
Platform Notes	None


MCI_DGV_PASTE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_PAUSE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_PLAY_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_PUT_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_QUALITY_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	WinNT
Platform Notes	None


MCI_DGV_RECORD_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_RECT_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_RESERVE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	WinNT
Platform Notes	None


MCI_DGV_RESTORE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	WinNT
Platform Notes	None


MCI_DGV_RESUME_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_SAVE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	WinNT
Platform Notes	None


MCI_DGV_SET_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_SETAUDIO_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	WinNT
Platform Notes	None


MCI_DGV_SETVIDEO_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	WinNT
Platform Notes	None


MCI_DGV_SIGNAL_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_STATUS_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	WinNT
Platform Notes	None


MCI_DGV_STEP_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_STOP_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_UPDATE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	No
Platform Notes	None


MCI_DGV_WINDOW_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	digitalv.h
Unicode	WinNT
Platform Notes	None


MCI_GENERIC_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_GETDEVCAPS_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_INFO_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MCI_LOAD_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MCI_OPEN_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MCI_OVLY_LOAD_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MCI_OVLY_OPEN_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MCI_OVLY_RECT_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_OVLY_SAVE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MCI_OVLY_WINDOW_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MCI_PLAY_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_RECORD_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SAVE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MCI_SEEK_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SEQ_SET_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SET_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_STATUS_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SYSINFO_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MCI_VCR_CUE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vcr.h
Unicode	No
Platform Notes	None


MCI_VCR_LIST_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vcr.h
Unicode	No
Platform Notes	None


MCI_VCR_PLAY_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vcr.h
Unicode	No
Platform Notes	None


MCI_VCR_RECORD_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vcr.h
Unicode	No
Platform Notes	None


MCI_VCR_SEEK_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vcr.h
Unicode	No
Platform Notes	None


MCI_VCR_SET_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vcr.h
Unicode	No
Platform Notes	None


MCI_VCR_SETAUDIO_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vcr.h
Unicode	No
Platform Notes	None


MCI_VCR_SETTUNER_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vcr.h
Unicode	No
Platform Notes	None


MCI_VCR_SETVIDEO_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vcr.h
Unicode	No
Platform Notes	None


MCI_VCR_STATUS_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vcr.h
Unicode	No
Platform Notes	None


MCI_VCR_STEP_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	vcr.h
Unicode	No
Platform Notes	None


MCI_VD_ESCAPE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MCI_VD_PLAY_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_VD_STEP_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_WAVE_DELETE_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_WAVE_OPEN_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MCI_WAVE_SET_PARMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MDICREATESTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


MEASUREITEMSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


MEMORY_BASIC_INFORMATION
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


MEMORYSTATUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


MENU_EVENT_RECORD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wincon.h
Unicode	No
Platform Notes	None


MENUEX_TEMPLATE_HEADER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	-
Unicode
Platform Notes	None


MENUEX_TEMPLATE_ITEM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	-
Unicode
Platform Notes	None


MENUITEMINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


MENUITEMTEMPLATE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


MENUITEMTEMPLATEHEADER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


METAFILEPICT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


METAHEADER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


METARECORD
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


MIDIEVENT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIDIHDR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIDIINCAPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MIDIOUTCAPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MIDIPROPTEMPO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIDIPROPTIMEDIV
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIDISTRMBUFFVER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MINIMIZEDMETRICS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


MINMAXINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


MIXERCAPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MIXERCONTROL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MIXERCONTROLDETAILS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIXERCONTROLDETAILS_BOOLEAN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIXERCONTROLDETAILS_LISTTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MIXERCONTROLDETAILS_SIGNED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIXERCONTROLDETAILS_UNSIGNED
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIXERLINE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MIXERLINECONTROLS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


MMCKINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMIOINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMTIME
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MODEMDEVCAPS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mcx.h
Unicode	No
Platform Notes	None


MODEMSETTINGS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	mcx.h
Unicode	No
Platform Notes	None


MONCBSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


MONCONVSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


MONERRSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


MONHSZSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	WinNT
Platform Notes	None


MONITOR_INFO_1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


MONITOR_INFO_2
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


MONLINKSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


MONMSGSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	ddeml.h
Unicode	No
Platform Notes	None


MOUSE_EVENT_RECORD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wincon.h
Unicode	No
Platform Notes	None


MOUSEHOOKSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


MOUSEKEYS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


MSG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


MSG_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmmsg.h
Unicode	No
Platform Notes	None


MSG_INFO_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmmsg.h
Unicode	No
Platform Notes	None


MSGBOXPARAMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	No


MSGFILTER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


MTSID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


MULTI_QI
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


MULTIKEYHELP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


NAME_BUFFER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	nb30.h
Unicode	No
Platform Notes	None


NCB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	nb30.h
Unicode	No
Platform Notes	None


NCCALCSIZE_PARAMS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


NDDESHAREINFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	nddeapi.h
Unicode	No
Platform Notes	None


NET_DISPLAY_GROUP
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


NET_DISPLAY_MACHINE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


NET_DISPLAY_USER
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


NETCONNECTINFOSTRUCT
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnetwk.h
Unicode	No
Platform Notes	None


NETRESOURCE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


NEWCPLINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	cpl.h
Unicode	WinNT
Platform Notes	None


NEWMAIL_NOTIFICATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


NEWTEXTMETRIC
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


NEWTEXTMETRICEX
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


NM_LISTVIEW
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


NM_TREEVIEW
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


NM_UPDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


NMHDR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


NONCLIENTMETRICS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


NOTIFICATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


NOTIFKEY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


NOTIFYICONDATA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	No
Platform Notes	None


NRESARRAY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


NS_SERVICE_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	nspapi.h
Unicode	WinNT
Platform Notes	None


NUMBERFMT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


OBJECT_NOTIFICATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


OBJECTDESCRIPTOR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


OCPFIPARAMS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	olectl.h
Unicode	Yes
Platform Notes	None


OFNOTIFY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


OFSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


OLEINPLACEFRAMEINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


OLEMENUGROUPWIDTHS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


OLEUIBUSY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OLEUICHANGEICON
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OLEUICHANGESOURCE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OLEUICONVERT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OLEUIEDITLINKS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OLEUIGNRLPROPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OLEUIINSERTOBJECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OLEUILINKPROPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OLEUIOBJECTPROPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OLEUIPASTEENTRY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OLEUIPASTESPECIAL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OLEUIVIEWPROPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oledlg.h
Unicode	Yes
Platform Notes	None


OLEVERB
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	oleidl.h
Unicode	Yes
Platform Notes	None


OPENFILENAME
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


OPTIONDATA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapispi.h
Unicode	No
Platform Notes	None


OSVERSIONINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OUTLINETEXTMETRIC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


OUTPUT_DEBUG_STRING_INFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


OVERLAPPED
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


PAGESETUPDLG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


PAINTSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


PALETTEENTRY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


PANOSE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


PARAFORMAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


PARTITION_INFORMATION
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


PATCHARRAY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


PCMWAVEFORMAT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


PERF_COUNTER_BLOCK
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winperf.h
Unicode	No
Platform Notes	None


PERF_COUNTER_DEFINITION
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winperf.h
Unicode	No
Platform Notes	None


PERF_DATA_BLOCK
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winperf.h
Unicode	No
Platform Notes	None


PERF_INSTANCE_DEFINITION
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winperf.h
Unicode	No
Platform Notes	None


PERF_OBJECT_TYPE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winperf.h
Unicode	No
Platform Notes	None


PFNIDLE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiutil.h
Unicode	No
Platform Notes	None


PHONEBUTTONINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


PHONECAPS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


PHONEEXTENSIONID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


PHONEINITIALIZEEXPARAMS
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


PHONEMESSAGE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


PHONESTATUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


PICTDESC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	olectl.h
Unicode	Yes
Platform Notes	None


POINT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	windef.h
Unicode	No
Platform Notes	None


POINTF
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


POINTFLOAT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: OpenGL is available as a redistributable


POINTFX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


POINTL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	windef.h
Unicode	No
Platform Notes	None


POINTS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	windef.h
Unicode	No
Platform Notes	None


POLYTEXT
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


PORT_INFO_1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


PORT_INFO_2
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


PORT_INFO_3
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


PREVENT_MEDIA_REMOVAL
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


PRINT_OTHER_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmalert.h
Unicode	No
Platform Notes	None


PRINTDLG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


PRINTER_DEFAULTS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


PRINTER_INFO_1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


PRINTER_INFO_2
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


PRINTER_INFO_3
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


PRINTER_INFO_4
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


PRINTER_INFO_5
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


PRINTER_INFO_6
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


PRINTER_NOTIFY_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	No
Platform Notes	None


PRINTER_NOTIFY_INFO_DATA
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	No
Platform Notes	None


PRINTER_NOTIFY_OPTIONS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	No
Platform Notes	None


PRINTER_NOTIFY_OPTIONS_TYPE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	No
Platform Notes	None


PRINTPROCESSOR_INFO_1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


PRIVILEGE_SET
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


PROCESS_HEAP_ENTRY
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


PROCESS_INFORMATION
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


PROPPAGEINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ocidl.h
Unicode	Yes
Platform Notes	None


PROPSHEETHEADER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	WinNT
Platform Notes	None


PROPSHEETPAGE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	WinNT
Platform Notes	None


PROPSHEETUI_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	compstui.h
Unicode
Platform Notes	None


PROPSPEC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


PROPVARIANT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


PROTOCOL_INFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	nspapi.h
Unicode	WinNT
Platform Notes	None


PROVIDOR_INFO_1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


PSHNOTIFY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	prsht.h
Unicode	No
Platform Notes	None


PUNCTUATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


QUERY_SERVICE_CONFIG
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


QUERY_SERVICE_LOCK_STATUS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


RAS_PARAMETERS
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rassapi.h
Unicode	No
Platform Notes	None


RAS_PORT_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RAS_PORT_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RAS_PORT_STATISTICS
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rassapi.h
Unicode	No
Platform Notes	None


RAS_PPP_ATCP_RESULT
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RAS_PPP_IPCP_RESULT
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RAS_PPP_IPXCP_RESULT
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RAS_PPP_NBFCP_RESULT
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RAS_PPP_PROJECTION_RESULT
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RAS_SECURITY_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rasshost.h
Unicode	No
Platform Notes	None


RAS_SERVER_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rassapi.h
Unicode	No
Platform Notes	None


RAS_USER_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rassapi.h
Unicode	WinNT
Platform Notes	None


RASADPARAMS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	ras.h
Unicode	No
Platform Notes	None


RASAMB
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RASAUTODIALENTRY
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RASCONN
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RASCONNSTATUS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RASCREDENTIALS
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RASCTRYINFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	ras.h
Unicode	No
Platform Notes	None


RASDEVINFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RASDIALDLG
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rasdlg.h
Unicode	No
Platform Notes	None


RASDIALEXTENSIONS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	ras.h
Unicode	No
Platform Notes	None


RASDIALPARAMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ras.h
Unicode	WinNT
Platform Notes	Yes


RASENTRY
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RASENTRYDLG
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rasdlg.h
Unicode	WinNT
Platform Notes	None


RASENTRYNAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RASIPADDR
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	ras.h
Unicode	No
Platform Notes	None


RASMONITORDLG
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rasdlg.h
Unicode	No
Platform Notes	None


RASNOUSER
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rasdlg.h
Unicode	WinNT
Platform Notes	None


RASPBDLG
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rasdlg.h
Unicode	WinNT
Platform Notes	None


RASPPPIP
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RASPPPIPX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RASPPPNBF
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	ras.h
Unicode	WinNT
Platform Notes	Yes


RASSLIP
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RASSUBENTRY
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RASTERIZER_STATUS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


REASSIGN_BLOCKS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


RECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	windef.h
Unicode	No
Platform Notes	None


RECTL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	windef.h
Unicode	No
Platform Notes	None


REGISTERWORD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	WinNT
Platform Notes	None


REMOTE_NAME_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


RemSNB
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


REOBJECT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	richole.h
Unicode	No
Platform Notes	None


REPASTESPECIAL
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


REPL_EDIR_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmrepl.h
Unicode	No
Platform Notes	None


REPL_EDIR_INFO_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmrepl.h
Unicode	No
Platform Notes	None


REPL_EDIR_INFO_1000
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmrepl.h
Unicode	No
Platform Notes	None


REPL_EDIR_INFO_1001
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmrepl.h
Unicode	No
Platform Notes	None


REPL_EDIR_INFO_2
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmrepl.h
Unicode	No
Platform Notes	None


REPL_EDIR_INFO_3
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmrepl.h
Unicode	No
Platform Notes	None


REPL_IDIR_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmrepl.h
Unicode	No
Platform Notes	None


REPL_IDIR_INFO_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmrepl.h
Unicode	No
Platform Notes	None


REPL_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmrepl.h
Unicode	No
Platform Notes	None


REPL_INFO_1000
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmrepl.h
Unicode	No
Platform Notes	None


REPL_INFO_1001
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmrepl.h
Unicode	No
Platform Notes	None


REPL_INFO_1002
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmrepl.h
Unicode	No
Platform Notes	None


REPL_INFO_1003
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmrepl.h
Unicode	No
Platform Notes	None


REQRESIZE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


RGBQUAD
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


RGBTRIPLE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


RGNDATA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


RGNDATAHEADER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


RIP_INFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


SAndRestriction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SAppTimeArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SBinary
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SBinaryArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SBitMaskRestriction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SCommentRestriction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SComparePropsRestriction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SContentRestriction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SCROLLINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


SCurrencyArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SDateTimeArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SDoubleArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SECURITY_ATTRIBUTES
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


SECURITY_DESCRIPTOR
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


SECURITY_DESCRIPTOR_CONTROL
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


SECURITY_INFORMATION
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


SECURITY_MESSAGE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rasshost.h
Unicode	No
Platform Notes	None


SECURITY_QUALITY_OF_SERVICE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


SELCHANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	No
Platform Notes	None


SERIALKEYS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SERVER_INFO_100
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1005
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_101
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1010
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1016
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1017
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1018
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_102
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1107
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1501
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1502
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1503
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1506
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1509
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1510
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1511
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1512
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1513
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1515
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1516
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1518
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1523
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1528
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1529
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1530
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1533
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1534
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1535
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1536
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1538
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1539
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1540
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1541
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1542
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1544
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1550
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_1552
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_402
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_403
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_502
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_INFO_503
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVER_TRANSPORT_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmserver.h
Unicode	No
Platform Notes	None


SERVICE_ADDRESS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	nspapi.h
Unicode	No
Platform Notes	None


SERVICE_ADDRESSES
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	nspapi.h
Unicode	No
Platform Notes	None


SERVICE_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	nspapi.h
Unicode	WinNT
Platform Notes	None


SERVICE_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmsvc.h
Unicode	No
Platform Notes	None


SERVICE_INFO_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmsvc.h
Unicode	No
Platform Notes	None


SERVICE_INFO_2
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmsvc.h
Unicode	No
Platform Notes	None


SERVICE_STATUS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winsvc.h
Unicode	No
Platform Notes	None


SERVICE_TABLE_ENTRY
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


SERVICE_TYPE_INFO_ABS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	nspapi.h
Unicode	WinNT
Platform Notes	None


SERVICE_TYPE_VALUE_ABS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	nspapi.h
Unicode	WinNT
Platform Notes	None


SESSION_BUFFER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	nb30.h
Unicode	No
Platform Notes	None


SESSION_HEADER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	nb30.h
Unicode	No
Platform Notes	None


SESSION_INFO_0
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


SESSION_INFO_1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


SESSION_INFO_10
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


SESSION_INFO_2
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


SESSION_INFO_502
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


SET_PARTITION_INFORMATION
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


SExistRestriction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SGuidArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SHARE_INFO_0
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


SHARE_INFO_1
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


SHARE_INFO_1004
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


SHARE_INFO_1006
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


SHARE_INFO_1501
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


SHARE_INFO_2
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


SHARE_INFO_502
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	lmshare.h
Unicode	No
Platform Notes	None


SHELLEXECUTEINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


SHFILEINFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


SHFILEOPSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


SHITEMID
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


SHNAMEMAPPING
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


SID
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


SID_AND_ATTRIBUTES
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


SID_IDENTIFIER_AUTHORITY
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


SINGLE_LIST_ENTRY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


SIZE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	windef.h
Unicode	No
Platform Notes	None


SLargeIntegerArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SLongArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SLPSTRArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SMALL_RECT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wincon.h
Unicode	No
Platform Notes	None


SMAPIFormInfoArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


SMAPIFormProp
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


SMAPIFormPropArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


SMAPIFormPropEnumVal
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


SMAPIVerb
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


SMAPIVerbArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapiform.h
Unicode	No
Platform Notes	None


SMessageClassArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SNB
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


SNotRestriction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SOLE_AUTHENTICATION_SERVICE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


SOrRestriction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SOUNDSENTRY
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SOURCE_MEDIA
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	Yes
Platform Notes	None


SP_INF_INFORMATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	setupapi.h
Unicode	No
Platform Notes	None


SPropAttrArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	imessage.h
Unicode	No
Platform Notes	None


SpropertyRestriction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SPropProblem
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SPropProblemArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SPropTagArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SPropValue
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SRealArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SRestriction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SRow
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SRowSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SShortArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SSizeRestriction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SSortOrder
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SSortOrderSet
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SSubRestriction
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


STACKFRAME
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imagehlp.h
Unicode	No
Platform Notes	Windows 95: IMAGEHLP is available as a redistributable.


STARTUPINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


STAT_SERVER_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmstats.h
Unicode	No
Platform Notes	None


STAT_WORKSTATION_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmstats.h
Unicode	No
Platform Notes	None


STATDATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


STATPROPSETSTG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


STATPROPSTG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


STATSTG
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


STATUS_OBJECT_NOTIFICATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


STD_ALERT
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmalert.h
Unicode	No
Platform Notes	None


STGMEDIUM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	objidl.h
Unicode	Yes
Platform Notes	None


STICKYKEYS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


STnefProblem
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tnef.h
Unicode	No
Platform Notes	None


STnefProblemArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tnef.h
Unicode	No
Platform Notes	None


String
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


StringFileInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


StringTable
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


STRRET
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	shlobj.h
Unicode	No
Platform Notes	None


STYLEBUF
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	imm.h
Unicode	WinNT
Platform Notes	None


STYLESTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


SWStringArray
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


SYSTEM_ALARM_ACE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


SYSTEM_AUDIT_ACE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


SYSTEM_INFO
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


SYSTEM_POWER_STATUS
Windows NT	No
Win95	Yes
Win32s	No
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


SYSTEMTIME
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


TABLE_NOTIFICATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	mapidefs.h
Unicode	No
Platform Notes	None


TAPE_ERASE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TAPE_GET_DRIVE_PARAMETERS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TAPE_GET_MEDIA_PARAMETERS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TAPE_GET_POSITION
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TAPE_PREPARE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TAPE_SET_DRIVE_PARAMETERS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TAPE_SET_MEDIA_PARAMETERS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TAPE_SET_POSITION
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TAPE_WRITE_MARKS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TBADDBITMAP
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBBUTTON
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TBNOTIFY
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TBSAVEPARAMS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TC_HITTESTINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TC_ITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TC_ITEMHEADER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TC_KEYDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TEXTMETRIC
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


TEXTRANGE
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	richedit.h
Unicode	WinNT
Platform Notes	None


TIME_OF_DAY_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmremutl.h
Unicode	No
Platform Notes	None


TIME_ZONE_INFORMATION
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


TIMECAPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


TOGGLEKEYS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


TOKEN_CONTROL
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TOKEN_DEFAULT_DACL
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TOKEN_GROUPS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TOKEN_OWNER
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TOKEN_PRIMARY_GROUP
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TOKEN_PRIVILEGES
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TOKEN_SOURCE
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TOKEN_STATISTICS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TOKEN_USER
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


TOOLINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TOOLTIPTEXT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TPMPARAMS
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


TRACKMOUSEEVENT
Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.lib
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


TRANSMIT_FILE_BUFFERS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winsock.h
Unicode	No
Platform Notes	None


TRUSTEE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	accctrl.h
Unicode	WinNT
Platform Notes	None


TTHITTESTINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TTPOLYCURVE
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


TTPOLYGONHEADER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


TV_DISPINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TV_HITTESTINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TV_INSERTSTRUCT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TV_ITEM
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


TV_KEYDOWN
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


TV_SORTCB
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


UDACCEL
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	commctrl.h
Unicode	No
Platform Notes	None


ULARGE_INTEGER
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winnt.h
Unicode	No
Platform Notes	None


UNIVERSAL_NAME_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


UNLOAD_DLL_DEBUG_INFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


USE_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmuse.h
Unicode	No
Platform Notes	None


USE_INFO_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmuse.h
Unicode	No
Platform Notes	None


USE_INFO_2
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmuse.h
Unicode	No
Platform Notes	None


USER_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_10
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1003
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1005
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1006
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1007
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1008
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1009
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1010
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1011
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1012
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1013
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1014
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1017
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1018
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1020
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1023
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1024
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1025
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1051
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1052
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_1053
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_11
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_2
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_20
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_21
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_22
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_INFO_3
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_MODALS_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_MODALS_INFO_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_MODALS_INFO_1001
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_MODALS_INFO_1002
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_MODALS_INFO_1003
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_MODALS_INFO_1004
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_MODALS_INFO_1005
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_MODALS_INFO_1006
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_MODALS_INFO_1007
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_MODALS_INFO_2
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_MODALS_INFO_3
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmaccess.h
Unicode	No
Platform Notes	None


USER_OTHER_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmalert.h
Unicode	No
Platform Notes	None


USEROBJECTFLAGS
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


VALENT
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


Var
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


VarFileInfo
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


VARSTRING
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	tapi.h
Unicode
Platform Notes	None


VERIFY_INFORMATION
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winioctl.h
Unicode	No
Platform Notes	None


VS_FIXEDFILEINFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winver.h
Unicode	No
Platform Notes	None


VS_VERSION_INFO
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	-
Unicode	No
Platform Notes	None


WAVEFILTER
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmreg.h
Unicode	No
Platform Notes	None


WAVEFORMAT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmreg.h
Unicode	No
Platform Notes	None


WAVEFORMATEX
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmreg.h
Unicode	No
Platform Notes	None


WAVEHDR
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	No
Platform Notes	None


WAVEINCAPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


WAVEOUTCAPS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


WIN_CERTIFICATE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wintrust.h
Unicode	No
Platform Notes	None


WIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


WIN_TRUST_ACTDATA_SUBJECT_ONLY
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


WIN_TRUST_SIP_SUBJECT
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wintrust.h
Unicode	No
Platform Notes	None


WIN_TRUST_SUBJECT_FILE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winbase.h
Unicode	Unicode only
Platform Notes	None


WIN32_FILE_ATTRIBUTE_DATA
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


WIN32_FIND_DATA
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


WIN32_STREAM_ID
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	winbase.h
Unicode	No
Platform Notes	None


WINDOW_BUFFER_SIZE_RECORD
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wincon.h
Unicode	No
Platform Notes	None


WINDOWPLACEMENT
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WINDOWPOS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	No
Platform Notes	None


WINTRUST_CLIENT_TP_DISPATCH_TABLE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wintrust.h
Unicode	No
Platform Notes	None


WINTRUST_CLIENT_TP_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wintrust.h
Unicode	No
Platform Notes	None


WINTRUST_PROVIDER_CLIENT_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wintrust.h
Unicode	No
Platform Notes	None


WINTRUST_PROVIDER_CLIENT_SERVICES
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wintrust.h
Unicode	No
Platform Notes	None


WINTRUST_PROVIDER_SERVER_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wintrust.h
Unicode	No
Platform Notes	None


WINTRUST_PROVIDER_SERVER_SERVICES
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wintrust.h
Unicode	No
Platform Notes	None


WINTRUST_SERVER_TP_DISPATCH_TABLE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wintrust.h
Unicode	No
Platform Notes	None


WINTRUST_SERVER_TP_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wintrust.h
Unicode	No
Platform Notes	None


WINTRUST_SIP_DISPATCH_TABLE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wintrust.h
Unicode	No
Platform Notes	None


WINTRUST_SIP_INFO
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wintrust.h
Unicode	No
Platform Notes	None


WKSTA_INFO_100
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmwksta.h
Unicode	No
Platform Notes	None


WKSTA_INFO_101
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmwksta.h
Unicode	No
Platform Notes	None


WKSTA_INFO_102
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmwksta.h
Unicode	No
Platform Notes	None


WKSTA_INFO_1101
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmwksta.h
Unicode	No
Platform Notes	None


WKSTA_INFO_302
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmwksta.h
Unicode	No
Platform Notes	None


WKSTA_INFO_402
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmwksta.h
Unicode	No
Platform Notes	None


WKSTA_INFO_502
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmwksta.h
Unicode	No
Platform Notes	None


WKSTA_TRANSPORT_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmwksta.h
Unicode	No
Platform Notes	None


WKSTA_USER_INFO_0
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmwksta.h
Unicode	No
Platform Notes	None


WKSTA_USER_INFO_1
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmwksta.h
Unicode	No
Platform Notes	None


WKSTA_USER_INFO_1101
Windows NT	Yes
Win95	No
Win32s	No
Import Library	-
Header File	lmwksta.h
Unicode	No
Platform Notes	None


WNDCLASS
Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


WNDCLASSEX
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


XFORM
Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	-
Header File	wingdi.h
Unicode	No
Platform Notes	None


RAS_PARAMS_VALUE
Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rassapi.h
Unicode	No
Platform Notes	None